# ADR-016: Protocol-first / Runtime-optional

状态: 已确认
日期: 2026-04-26

## 背景

Sopify runtime 已膨胀至 ~29K 行 Python / 66 个模块。核心价值（plan 约定、状态交接、checkpoint、history、blueprint）天然是文件协议，不必须由 Python runtime 承载。复杂 runtime 容易把"LLM 随机出错"变成"系统性卡在某状态"，后者更不可控。

## 决策

**Sopify 从 Runtime-centric 演进为 Protocol-first。**

三层定位：

| 层 | 内容 | 体量 | 可替代性 |
|----|------|------|---------|
| **Protocol** | `.sopify-skills/` 目录约定、plan/state/history schema、SKILL.md 编排 | 纯文档 | 不可替代 |
| **Validator** | ActionProposal 校验、状态迁移校验、archive check/apply、diagnostics | ~2K 行 | 独立交付 |
| **Runtime** | gate / router / engine / handoff / checkpoint 状态机 | 目标 <20K 行 | 可选增强 / 参考实现 |

两种操作模式：

- **Convention 模式（下界）**：LLM 读 SKILL.md → 自行推进 → Validator 事后校验。适用：轻量任务、新宿主接入。
- **Runtime 模式（上界）**：完整 runtime 控制状态迁移。适用：确定性门控、审计、恢复、权限边界。

模式选择维度是**过程要求**，不是模型强弱。

## 战略论据

1. **核心价值不在 Python runtime** — plan、状态交接、checkpoint、history 天然是文件协议
2. **Protocol 更抗平台替代** — Runtime 编排易被宿主替代；`.sopify-skills/` 可审计资产格式可被各宿主复用
3. **Convention 是多宿主最短路径** — Protocol + SKILL.md + Validator 让新宿主先"会读会写"
4. **复杂 runtime 不解决 LLM 出错** — 把随机错误变成系统性卡顿更不可控

## 四步演进路线

| 步骤 | 内容 | 前置 |
|------|------|------|
| Step 1 | 提取 Protocol 文档：plan/state/lifecycle/SKILL.md 规范 → `blueprint/protocol.md` v0 已落地 | 无 |
| Step 2 | Protocol validator CLI (check / doctor / archive) | Step 1 |
| Step 3 | SKILL.md 表单式增强 + Action Schema Boundary | Step 1 + ADR-017 |
| Step 4 | Runtime 可选化：Convention 下界 + Runtime 上界 | Step 2+3 验证 |

## 后果

- 新功能优先考虑是否可以纯 Protocol 实现
- Runtime 体量目标 <20K 行（从当前 ~29K 削减）
- SKILL.md 必须是表单式（弱模型可机械填写），不是方法论散文
