简介
SSP 定义了一个小而稳定的接口，服务于多阶段工作流。状态可预测，上下文可持续， 每个阶段都能读取上游事实而无需猜测。
设计意图
将路由状态与共享事实分离，让阶段逻辑可独立演进，同时保持整条管线稳定。
为什么是 SSP
当交接是隐式的，流程就会断。SSP 把路由显式化，并把共享事实放在一个可持久的位置。
可携带交接
任何调度器拿到同一份状态根目录即可接管。
可追溯产物
每个阶段都记录产物，便于审计与复现。
低成本
两个文件、JSON Schema，无需服务端。
生态价值
统一状态契约让工作流数据可互操作。规模化之后，这能促成更可靠的编排模式 与更快的迭代效率。
快速开始
- 创建状态根目录
.skill-state/。 - 添加
state.json与context.json。 - 更新
phase以驱动路由。 - 将阶段产物写入
context.json。 - 使用 JSON Schema 校验文件。
核心文件
state.json
路由状态与阶段产物。
- phase
- current_skill
- outputs.stage.status
- timestamps
context.json
跨阶段共享的事实、配置与结果。
- project brief
- service configs
- validation results
- artifacts
生命周期
读取状态
调度器读取 phase 与 outputs 决定下一阶段。
执行阶段
阶段读取 context，完成工作并写入新事实。
更新状态
记录状态、产物与时间戳，便于审计与复现。
传播性
SSP 将状态根目录视为可携带的工作单元。复制
state.json 与 context.json（以及被引用的产物）
即可让另一套调度器接管继续运行。
可接力规则
- 不要依赖隐式运行时状态。
- 必须在
outputs.*.files中列出必需产物。 - 保持交接可复现、可审计。
SSP vs MCP / Spec-driven
SSP vs MCP
- MCP 定义工具能力与调用方式。
- SSP 定义运行时状态与交接语义。
- 两者在真实工作流里是互补的。
SSP vs spec-driven
- spec-driven 关注任务契约与 API。
- SSP 关注流程连续性与阶段产物。
- SSP 依赖 profile 定义具体阶段。
协议要点
必需字段
state.json 必须包含：
- phase
- created_at
- last_updated
- current_skill
- outputs
状态取值
阶段状态必须在以下集合内：
- pending
- in_progress
- completed
- blocked
- failed
{
"protocol_version": "0.1",
"phase": "idle",
"created_at": null,
"last_updated": null,
"current_skill": null,
"env": {
"registry": ".skill-state/env.json",
"local": ".skill-state/env.local.json"
},
"outputs": {
"plan": {"status": "pending", "files": []},
"build": {"status": "pending", "files": []},
"verify": {"status": "pending", "last_check": null}
}
}Schema
使用 JSON Schema 校验 SSP 文件，避免结构漂移。
State Schema
schemas/state.schema.json
Context Schema
schemas/context.schema.json
Profiles
Profile 描述阶段名称与期望的上下文字段。协议本身保持不变， 只有 Profile 在变化。
示例 Profile（非规范）
具体映射请参考仓库中的 profiles/three-stage。
- trend2work：项目摘要与规划输出
- tech-dev：集成与配置落地
- iterate-check：验证与报告
示例
示例文件位于 examples/。
state.json
examples/state.json
context.json
examples/context.json
FAQ
SSP 只是两个 JSON 文件吗？
文件是接口，但协议定义了必需字段、产物记录与交接语义。 简洁是设计目标。
SSP 会替代 MCP 吗？
不会。MCP 解决工具集成，SSP 解决状态与连续性，两者互补。
phase 可以随意吗？
协议允许任意字符串，profile 或调度器可限制与校验。
为什么不用数据库？
可以使用数据库。SSP 关注契约而非存储方式，文件更便携、 可版本化、易于 diff。
一致性
- 状态根目录包含 state.json 与 context.json。
- state.json 保持必需字段与输出状态。
- context.json 不写入敏感信息，仅存共享事实。
- 以 schemas/ 作为结构真值源。
安全
不要写入密钥
敏感信息请使用 env registry 或外部密钥管理。
控制 PII
如包含用户数据，请记录留存与脱敏规则。
v0.2 扩展（草案）
以下是建立在核心协议之上的可选增强。
- Phase policy 与允许的跳转规则。
- 交接的传播元数据。
- 产物的 provenance 与执行信息。
- 验证钩子与阶段门禁。
- Profile 注册表与发现机制。
路线图
- 参考验证器与工具链
- Profile 注册表
- 一致性测试