TC 追踪器
TC Tracker (技术变更跟踪器)
通过结构化的 JSON 记录、强制执行的状态机以及会话交接格式，跟踪每一次代码变更。当之前的 AI 会话过期时，新会话可以通过该格式干净地恢复工作。
概述
技术变更 (Technical Change, TC) 是一种结构化记录，用于捕捉变更内容、变更原因、变更人员、变更时间、测试方式以及为下一个会话准备的工作进度。记录以 JSON 格式存储在目标项目的 docs/TC/ 目录下，并根据严格的 Schema 和状态机进行验证。
在以下场景中使用此技能：
- 用户要求“跟踪此变更”或需要代码修改的审计轨迹
- 用户希望将进行中的工作移交给未来的 AI 会话
- 需要超出 commit message 范围的结构化发布日志
- 在接手现有项目时需要追溯性的变更文档
- 用户调用
/tc init,/tc create,/tc update,/tc status,/tc resume或/tc close
在以下场景中不要使用此技能：
- 用户仅需要从 git 历史中生成变更日志（请使用
engineering/changelog-generator）
- 用户仅需要跟踪技术债项（请使用
engineering/tech-debt-tracker）
- 变更极其微小（如拼写错误、格式调整）且不影响行为
存储布局
每个项目将 TC 存储在 {project_root}/docs/TC/：
docs/TC/
├── tc_config.json # 项目设置
├── tc_registry.json # 主索引 + 统计数据
├── records/
│ └── TC-001-04-05-26-user-auth/
│ └── tc_record.json # 唯一事实来源
└── evidence/
└── TC-001/ # 日志片段、命令输出、截图TC ID 命名规范
- 主 TC：
TC-NNN-MM-DD-YY-functionality-slug(例如：TC-001-04-05-26-user-authentication)
- 子 TC：
TC-NNN.A或TC-NNN.A.1(字母 = 修订版本，数字 = 子修订版本)
NNN为顺序编号，MM-DD-YY为创建日期，slug 采用 kebab-case 格式。
状态机
planned (计划中) -> in_progress (进行中) -> implemented (已实现) -> tested (已测试) -> deployed (已部署)
| | | | |
+-> blocked (阻塞) -+ +- in_progress <-------+
| (返工 / 热修复)
+-> planned> 完整状态转换表和恢复流程请参阅 references/lifecycle.md。
工作流命令
该技能提供五个 Python 脚本，对 TC 记录执行确定性的、仅依赖标准库的操作。每个脚本均支持 --help 和 --json。
1. 在项目中初始化跟踪
python3 scripts/tc_init.py --project "My Project" --root .创建 docs/TC/, docs/TC/records/, docs/TC/evidence/, tc_config.json 和 tc_registry.json。该操作具有幂等性 —— 重新运行将报告“已初始化”并显示当前统计数据。
2. 创建新的 TC 记录
python3 scripts/tc_create.py \
--root . \
--name "user-authentication" \
--title "Add JWT-based user authentication" \
--scope feature \
--priority high \
--summary "Adds JWT login + middleware" \
--motivation "Required for protected endpoints"生成下一个顺序 TC ID，创建记录目录，写入完整的 tc_record.json（状态为 planned，R1 创建版本），并更新注册表。
3. 更新 TC
记录# 状态流转（基于状态机验证）
python3 scripts/tc_update.py --root . --tc-id TC-001-04-05-26-user-auth \
--set-status in_progress --reason "Starting implementation"
添加文件
python3 scripts/tc_update.py --root . --tc-id TC-001-04-05-26-user-auth \
--add-file src/auth.py:created
追加交接数据
python3 scripts/tc_update.py --root . --tc-id TC-001-04-05-26-user-auth \
--handoff-progress "JWT middleware wired up" \
--handoff-next "Write integration tests" \
--handoff-next "Update README"每次更改都会追加一个顺序的 R<n> 修订条目，刷新 updated 时间，并在原子化写入（先写 .tmp 再重命名）前根据 Schema 重新验证。
4. 查看状态
# 单个 TC
python3 scripts/tc_status.py --root . --tc-id TC-001-04-05-26-user-auth
所有 TC（注册表摘要）
python3 scripts/tc_status.py --root . --all --json5. 验证记录或注册表
python3 scripts/tc_validator.py --record docs/TC/records/TC-001-.../tc_record.json
python3 scripts/tc_validator.py --registry docs/TC/tc_registry.json验证器会强制执行 Schema 约束，检查状态机的合法性，验证 R<n> 和 T<n> ID 的顺序，并断言审批的一致性（approved=true 必须包含 approved_by 和 approved_date）。
> 完整 Schema 请参阅 references/tc-schema.md。
斜杠命令分发器 (Slash-Command Dispatcher)
仓库在 commands/tc.md 中提供了一个 /tc 斜杠命令，根据子命令分发到相应的脚本：
| 命令 | 操作 |
|---------|--------|
| /tc init | 为当前项目运行 tc_init.py |
| /tc create <name> | 提示填写字段，运行 tc_create.py |
| /tc update <tc-id> | 通过 tc_update.py 应用用户描述的更改 |
| /tc status [tc-id] | 运行 tc_status.py |
| /tc resume <tc-id> | 显示交接内容，归档前一会话，开始新会话 |
| /tc close <tc-id> | 流转至 deployed 状态，设置审批 |
| /tc export | 重新渲染所有衍生产物 |
| /tc dashboard | 重新渲染注册表摘要 |
斜杠命令是用户界面，Python 脚本则是执行引擎。
会话交接格式 (Session Handoff Format)
交接块位于每个 TC 的 session_context.handoff 中，是 AI 连续性最关键的字段。它包含：
progress_summary—— 已完成的工作
next_steps—— 剩余操作的有序列表
blockers—— 任何阻碍进度的因素
key_context—— 下一个 Bot 必须知道的关键决策、坑点或模式
files_in_progress—— 正在编辑的文件及其状态（editing,needs_review,partially_done,ready）
decisions_made—— 包含理由和时间戳的架构决策
> 完整结构和填写规则请参阅 references/handoff-format.md。
验证规则（强制执行）
1. 状态机 —— 仅允许合法的状态流转。
2. 顺序 ID —— revision_history 使用 R1, R2, R3...；test_cases 使用 T1, T2, T3...。
3. 仅追加历史 —— 修订条目绝不被修改或删除。
4. 审批一致性 —— approved=true 必须包含 approved_by 和 approved_date。
5. TC ID 格式 —— 必须符合 TC-NNN-MM-DD-YY-slug。
6. 子 TC ID 格式 —— 必须符合 TC-NNN.A 或 TC-NNN.A.N。
7. 原子写入 —— JSON 先写入 .tmp 文件再重命名。
8. 注册表统计 —— 每次写入注册表时重新计算。
非阻塞簿记模式
TC 追踪
g 绝不能中断主工作流。
- 严禁在编码过程中停下来行内更新 TC 记录。 请保持编码。
- 在自然里程碑处，启动后台子代理来更新记录。
- 仅在确实需要时提出问题（例如：“此项工作与任何活跃的 TC 都不匹配 —— 是否创建新记录？”），且每个会话仅询问一次，而非每个文件询问一次。
- 会话结束前，在关闭前编写最终的交接块（handoff block）。
追溯性批量创建
对于缺乏文档记录的现有项目，请构建一个 retro_changelog.json（每个逻辑变更一条记录），并将其循环输入到 tc_create.py 中，或扩展该脚本以支持批量模式。请按功能而非文件对提交进行分组。
反模式
| 反模式 | 为什么不好 | 建议做法 |
|--------------|--------------|-----------------|
| 编辑 revision_history 来“修复”拼写错误 | 历史记录仅限追加 —— 篡改会破坏审计追踪 | 添加一条修正该字段的新修订记录 |
| 跳过状态机（例如“直接将状态设为 deployed”） | 绕过了验证并隐藏了跳过的阶段 | 遵循 in_progress -> implemented -> tested -> deployed 流程 |
| 每个修改的文件创建一次 TC | 导致相关工作碎片化并使注册表膨胀 | 每个逻辑单元（功能、修复、重构）创建一次 TC |
| 在每次代码编辑之间行内更新 TC | 降低主代理速度，浪费上下文 | 在里程碑处启动后台子代理 |
| 在没有 approved_by 的情况下标记 approved=true | 验证器将拒绝；审计追踪具有误导性 | 始终同时设置 approved_by 和 approved_date |
| 直接使用文本编辑器覆盖 tc_record.json | 存在写入中断导致损坏的风险且跳过了验证 | 使用 tc_update.py（原子写入 + 模式检查） |
| 在 notes 或证据中放入密钥 | 记录会被提交到仓库 | 引用环境变量或外部密钥存储 |
| 删除后重复使用 TC ID | 破坏了顺序保证并混淆历史记录 | 仅递增 —— 绝不回收 |
| 让 next_steps 过时 | 违背了交接的初衷 | 在每个里程碑处更新，即使是“无变化” |
交叉引用
engineering/changelog-generator— 根据 Conventional Commits 生成 Keep-a-Changelog 发布日志。可与 TC 追踪器配合使用：TC 用于细粒度的单次变更审计，changelog 用于面向用户的发布日志。
engineering/tech-debt-tracker— 用于追踪长期技术债项，而非离散的代码变更。
engineering/focused-fix— 当 Bug 修复需要系统性的全功能修复时，先运行/focused-fix，然后将结果记录为 TC。
project-management/decision-log— 在 TC 的decisions_made块中做出的架构决策也可以提升至项目级的决策日志。
engineering-team/code-reviewer— 合并前的评审自然契合tested -> deployed的转换；在approval.approved_by中记录评审人。
本技能相关参考
- references/tc-schema.md — TC 记录和注册表的完整 JSON 模式。
- references/lifecycle.md — 状态机、有效转换和恢复流程。
- references/handoff-format.md — 会话交接结构和最佳实践。
