6.1 KiB
Ship 记录契约
目录
布局
.pouch/ship/<ship-id>/
current.yaml # 总账：kind、状态、stopAt、指针
spec.md # 短需求说明（short 和 long 都有）
tasks.yaml # 本 ship 的任务 DAG
status.md # 给人看的一页摘要
1-spec/ # 规格、评审、根因和 handoff
2-develop/ # 开发任务和变更
3-test/ # 任务验证与集成回归
4-review/ # PR、审核与合并
5-build/ # 合并后的构建/obtain
6-publish/ # 发布产物
7-deploy/ # 部署与健康检查
stage.yaml # 阶段状态和包含的步骤
activity.md # 该阶段的调度、结果和证据摘要
spec/ # 仅 long：PRD 版本、评审、handoff
brief.md
prd-v001.html
review.yaml
decisions.yaml
risks.yaml
handoff.yaml # 仅 approved 后
status.md 给人看；Agent 以 current.yaml 为准。两份不一致时改 status.md。
阶段目录由 create_ship.py 初始化，由 next_step.py 在派发和收到结果时追加活动记录；
大日志留在原测试、构建或部署位置，阶段目录只保存摘要和路径。
新建 ship 使用可排序的 YYYYMMDD-短语，例如 20261014-dynamic-editor。旧的无日期
记录仍可读取和校验，不要为了改名移动既有 ship 目录。
current.yaml
必填：shipId、kind、status、title、spec、tasks、evidence。
shipId 必须等于目录名。
shipId: add-export-button
kind: short
title: 列表页增加导出按钮
status: in_progress
stopAt: review_ready
source:
kind: user
ref: null
parentShipId: null
childShipIds: []
spec:
path: spec.md
revision: null
specStatus: null
prd: null
approvedRevision: null
reviews: null
handoff: null
tasks:
path: tasks.yaml
delivery:
stopAt: review_ready
state: change_ready
manager:
lastStep: null
lastResult: null
inFlight: null
evidence:
testRuns: []
artifacts: []
deploys: []
prs: []
commits: []
kind：short | long。
status：draft、spec_review、approved、in_progress、blocked、done、parked、superseded。
delivery.state 使用 delivery-loop 内部里程碑：change_ready、verified、
pr_opened、merged、regression_passed、artifact_built、published、deployed。
source.kind：user | hunt | ack | pr | feishu。修 ACK 缺陷时
source.kind: ack 且 ref 为缺陷任务 id。
manager 由入口主会话维护，可选。lastStep / lastResult / lastSummary 记录刚结束的那一步；
inFlight 在 worker 未返回时写成步骤名，返回后清掉。worker 不要写这些字段。
lastResult：pass | fail | blocked | ask。
short 与 long
同一套字段，厚度不同。
| 字段 | short | long |
|---|---|---|
spec.md |
四段：要做什么、不做什么、可观察验收、怎么验。有故障证据时加复现和根因 | 同一四段作摘要 |
spec/ |
不要创建 | specifier 写入 PRD、评审、决策、风险、handoff |
spec.revision 等 |
保持 null |
与 PRD 版本同步 |
tasks.yaml |
恰好 1 条 | DAG；dependsOn 指向本文件内 id |
| 子项 | 无 | 默认是 task。只有该切片有独立 stopAt 并单独发布时才晋升为子 ship，写入 childShipIds |
范围变大时保持同一 shipId，把 kind 改成 long，补 spec/ 并拆任务。
spec.md 不要写成 HTML PRD。long 的评审稿是 spec/prd-vNNN.html。
任务
tasks.yaml 只描述本 ship 的工作项，不是 ACK 缺陷板。
shipId: add-export-button
tasks:
- id: T-01
title: 在列表页增加导出按钮
dependsOn: []
expected:
- 登录用户在列表页看到「导出」
verification:
- 浏览器打开列表页，按钮可见且可点
status: open
stopAt: review_ready
允许的任务 status：open、in_progress、blocked、verified、merged、done。
long 的子任务默认 stopAt 为 pr_opened 或 merged，不要单独打生产 tag 或升级生产。
父 ship 在依赖任务完成后做集成回归，再按父记录的 delivery.stopAt 继续。
从 spec/handoff.yaml 建任务时复制 id、title、dependsOn、expected、
verification，不要写进 .pouch/ack/tasks.yaml。
证据指针
不要把 tester 快照、镜像层或 compose 日志复制进 ship 目录。追加指针：
evidence:
testRuns:
- path: .pouch/tester/runs/20261013T031000Z-smoke-ab12.yaml
result: pass
suite: smoke
artifacts:
- sha: 0123456789abcdef0123456789abcdef01234567
digest: sha256:abc
ref: harbor.example.com/app:1.2.3
venue: ci
deploys:
- env: test
revision: 0123456789abcdef0123456789abcdef01234567
health: pass
prs:
- url: https://git.example.com/app/-/merge_requests/12
status: opened
commits:
- sha: 0123456789abcdef0123456789abcdef01234567
role: baseline
delivery-loop 阶段与指针：
| 阶段 | 至少追加 |
|---|---|
change_ready |
commits role: baseline |
verified |
testRuns |
pr_opened |
prs |
merged |
commits role: merged |
regression_passed |
testRuns（回归） |
artifact_built / published |
artifacts |
deployed |
deploys |
path 相对项目根。文件不存在则校验失败。用 scripts/append_evidence.py 追加后立刻
validate_ship.py。
旧 specifier 目录
打开某个 id 时按这个顺序：
.pouch/ship/<id>/已存在：用它。若同时还留着.pouch/specifier/features/<id>/，报告旧路径为遗留，不要两处同时写。- 只有
.pouch/specifier/features/<id>/：把它移到.pouch/ship/<id>/spec/，按旧current.yaml生成 shipcurrent.yaml（kind: long），用brief.md补spec.md摘要，再校验。 - 两处都没有：由入口 skill 调用
create_ship.py新建。