tencentblueking 需求实现提交
定位
commit 是 pipeline 的终结阶段——代码已通过全部校验（架构/安全/CodeReview/测试覆盖）， 本阶段负责"收尾"：统计成果、记录度量、提交代码、更新外部状态。
本子 skill 在主会话中直接执行，不通过 speckit-execution-agent。 原因：commit 操作需要完整的 git 权限和 TAPD MCP 访问，且无 speckit 命令可调用。
前置条件
- 当前需求
meta.yaml.phase为validated - 代码已通过架构校验、安全校验、CodeReview 和测试覆盖审查
meta.yaml.implement_baseline_commit已存在（implement 阶段写入）
输入
${WORKDIR}/meta.yaml（读取implement_baseline_commit/stats.cost/history/workspace_id）${WORKDIR}/context.md（Code scope 白名单，用于确认变更范围）
执行流程
1. 变更统计
统计本需求从 implement 开始到当前的全量代码变更。
基线：meta.yaml.implement_baseline_commit
对比目标：当前工作区（HEAD）
统计维度：
| 指标 | 说明 |
|---|---|
total |
总变更行数（新增 + 删除） |
add_code |
新增行数 |
delete_code |
删除行数 |
logic_code |
非测试、非文档的代码文件变更行数 |
test_code |
测试文件变更行数（*_test.* / *_spec.* / test_*.*） |
docs |
文档文件变更行数（*.md / *.txt / *.rst） |
files |
变更文件数 |
使用 git diff --numstat <baseline> 获取原始数据，按文件后缀归类。
1.5 成本最终对账门禁（权威兜底）
commit 是 pipeline 终结阶段，是成本聚合的最后一道门禁。因 5a 即时聚合可能因
hook 异步写入而 miss，本步骤全量对账，确保 cost-events.jsonl 完整入账。
全量读取
${WORKDIR}/cost-events.jsonl（每行一个事件，含唯一ts_event）。读取
meta.yaml.stats.cost.per_call[]，以各条目的ts_event构建"已聚合集合"。逐条比对：凡 jsonl 中
ts_event不在已聚合集合内的事件 → 判为遗漏， append 到per_call[]（保留 stage/attempt/round/ts_event/ts_marker/duration_sec/ input_tokens/output_tokens/cache_tokens/credit 等字段）。重算所有累加字段：
total_duration_sec/total_input_tokens/total_output_tokens/total_cache_tokens/total_cached_write_tokens/total_cached_miss_tokens/total_credit/total_cost_usd（= total_credit）/subagent_calls（= 有效事件条数）。将对账结果写入
process.log：[cost-reconcile] jsonl_events=<N> already_merged=<M> newly_merged=<K> final_per_call=<N>容错：个别事件字段缺失时，跳过该字段累加并在
process.log记 warning， 不因单条异常中断对账（延续"hook 失败不阻塞主流程"语义）。幂等：以
ts_event去重，重复执行对账不会重复累加。
执行顺序（本子 skill 内固定）：1.5 对账 → 2 成本汇总 → 3 更新 stats → 6 写 commit.md → 7 git commit， 确保
commit.md与meta.yaml反映对账后的完整成本。
2. 成本数据汇总
从 meta.yaml.stats.cost 读取经步骤 1.5 对账补齐后的成本度量数据，汇总两个维度。
3.1 总体 cost
直接读取 cost 的顶层 total 字段：
| 指标 | 来源字段 |
|---|---|
| 总耗时 | cost.total_duration_sec（秒） |
| 总成本 | cost.total_credit（积分；同 cost.total_cost_usd） |
| 总输入 tokens | cost.total_input_tokens |
| 总输出 tokens | cost.total_output_tokens |
| 总缓存 tokens | cost.total_cache_tokens |
| subagent 调用次数 | cost.subagent_calls |
3.2 各阶段 cost
遍历 cost.per_call[]，按 stage 字段分组聚合（duration_sec / credit / input_tokens / output_tokens / cache_tokens / calls），将结果写入 meta.yaml.stats.cost.per_stage。
stage 取值：clarify / specify / plan / tasks-generate / tasks-analyze / implement / validate-arch / validate-security / validate-codereview / validate-test / validate-fix
3. 更新 meta.yaml.stats
将步骤 2 的代码变更统计写入 meta.yaml.stats（与已有的 cost 字段并列）：
stats:
total: <TOTAL>
add_code: <ADD_CODE>
delete_code: <DELETE_CODE>
logic_code: <LOGIC_CODE>
test_code: <TEST_CODE>
docs: <DOCS>
files: <FILES>
cost:
# ... 已有字段不变，新增 per_stage ...
per_stage: { ... }
started_at/end_at不由本子 skill 维护——开始时间在history[0].ts， 结束时间在最新history条目的ts。
4. 更新状态
- 更新
meta.yaml.phase为committed meta.yaml.history追加成功记录，清空meta.yaml.last_failure
5. 构建 Commit 信息
按 ../references/commit-conventions.md 规范构建 commit message：
- type：feat / fix / refactor / docs / test 等
- scope：涉及的模块
- subject：一句话概括变更目的（祈使语气）
- body：变更内容要点
- footer：
--story=${ID}（关联 TAPD 需求）
6. 记录 commit.md
将 commit 信息保存到 ${WORKDIR}/commit.md，格式如下：
# Commit 记录
## Commit Message
<构建好的 commit message>
## Commit Hash
<git rev-parse HEAD 的输出>
## 变更统计
| 指标 | 值 |
|------|-----|
| 总变更行数 | <total> |
| 新增代码 | <add_code> |
| 删除代码 | <delete_code> |
| 逻辑代码 | <logic_code> |
| 测试代码 | <test_code> |
| 文档变更 | <docs> |
| 变更文件数 | <files> |
## 成本汇总
### 总体
| 指标 | 值 |
|------|-----|
| 总耗时 | <total_duration_sec> s |
| 总成本 | <total_credit> credit |
| 总输入 tokens | <total_input_tokens> |
| 总输出 tokens | <total_output_tokens> |
| 总缓存 tokens | <total_cache_tokens> |
| subagent 调用次数 | <subagent_calls> |
### 各阶段
| 阶段 | 耗时 | 成本 | 输入 tokens | 输出 tokens | 缓存 tokens | 调用次数 |
|------|------|------|------------|------------|------------|---------|
| <stage> | <duration_sec> s | <credit> credit | <input_tokens> | <output_tokens> | <cache_tokens> | <calls> |
| ... | | | | | | |
## 时间
- 开始时间：<history[0].ts>
- 完成时间：<当前 ISO 8601 时间>
commit.md 产出门禁：写入后立即校验
${WORKDIR}/commit.md存在且包含三部分—— 「变更统计」「成本汇总」「时间」。任一缺失或为空则补写完整后再继续， 确保先于步骤 7 的代码提交，使 commit.md 纳入本次提交。 门禁结果写process.log：[commit-md-gate] status=<ok|fixed>。
7. 提交代码
默认精确暂存 Code scope + WORKDIR 产物；仅当工作树已确认无无关改动时才允许 git add -A。
git commit -m "<commit message>"
commit后任何文件信息回填与补充都无需commit，会有其他流程处理。
8. 更新 TAPD 需求状态
使用 TAPD MCP stories_update 更新需求状态：
| 参数 | 值 | 来源 |
|---|---|---|
| workspace_id | TAPD 工作空间 ID | meta.yaml.workspace_id → project.json → 询问 |
| id | 需求 ID | pipeline 传入 |
| v_status | "for test" | 固定值 |
错误处理：
stories_update失败时不阻塞 git commit（代码提交是核心操作）。 失败信息记录到process.log，由人工后续在 TAPD 中补录。
9. 更新 meta.yaml.phase
将 meta.yaml.phase 更新为 committed。
可重入约定
commit 是 pipeline 终结阶段，通常不会被回退到。但以下场景需要幂等保证：
| 场景 | 处理 |
|---|---|
| git commit 因 hooks 失败 | 修复后重试，git add -A && git commit 幂等 |
| TAPD 更新失败 | 不阻塞，记录日志后正常推进 phase |
重复进入已是 committed 的 phase |
pipeline 主编排检测到 phase==committed 直接退出（完工） |
| 中途崩溃后恢复 | meta.yaml 已是 validated → 重新执行全部步骤（幂等：git add -A 收集相同内容，commit message 重新生成） |
| 对账/commit.md 门禁重复执行 | 幂等：对账按 ts_event 去重不重复累加；commit.md 校验缺失才补写，已完整则跳过 |
参考资料
| 文件 | 用途 | 何时读取 |
|---|---|---|
../references/commit-conventions.md |
Commit message 格式规范 | 步骤 6 构建 commit 信息时 |
../references/context-and-meta-template.md |
meta.yaml stats 字段定义 | 步骤 4 写入统计时 |
产出
- 代码已提交至本地仓库（git commit）
${WORKDIR}/meta.yaml— stats 字段已填充（代码变更 + cost 汇总）${WORKDIR}/commit.md— Commit 记录文件（含变更统计 + 成本汇总 + 时间）， 经产出门禁校验完整并纳入本次 git commit- TAPD 需求 v_status 更新为"for test"
- 需求 phase 为
committed