追踪器 —— 跟踪流动的工作
何时适合使用此技能
特征性问题： “……的状态是什么？” 或 “谁负责这个？”
追踪器 = 在状态间移动的项目，有负责人和时间线，并且值得保留历史记录。
路由测试
满足 至少两项 条件才需要追踪器：
- 随时间变化的状态（不是属性 —— 是 移动）
- 一个人类负责人
- 截止日期
- 层级结构：组 → 子组 → 项目
少于两项？→ registry（注册表）。⚠️ 默认始终是注册表。
构建方式
一个引擎，多种模式。
<tracker-dir>/
schema.json 状态、优先级、层级标签、额外字段
tracker.db SQLite：项目 + 组 + item_history
引擎：engine/tracker.py（位于此SKILL.md旁边）· Python 3.9+ · 零依赖（内置 sqlite3）。
层级结构： group（组）→ subgroup（子组）→ item（项目）。标签因领域而异——对于任务，它是 project（项目）→ module（模块）→ task（任务）；对于Bug，它是 product（产品）→ component（组件）→ bug（Bug）；对于发票，它是 client（客户）→ subscription（订阅）→ invoice（发票）。
与用户协作
- 运行路由测试。 扁平列表 →
registry（注册表）。 - 提出模式： 哪些状态，什么算“已关闭”，哪些优先级，层级结构是什么，哪些额外字段。呈现给用户并请求批准。
- 检查预设 是否存在于
presets/中。 - 使用
init创建，添加组，然后将 追踪器注册到 工作区级的registries.json索引中。 - 说明更新可以通过自然语言报告——代理会将其转换为命令。
命令
路径相对于工作区根目录。根据技能安装位置调整 SKILL_DIR（例如 .pi/skills/tracker）。
T=<SKILL_DIR>/engine/tracker.py
D=trackers/bugs
python3 $T --dir $D init --preset bugs
python3 $T --dir $D group add webapp --name "Web App"
python3 $T --dir $D group add checkout --name "Checkout" --parent webapp
python3 $T --dir $D add "日历中的重复预定" --group webapp --subgroup checkout \
--assignee dana --priority sev2 --client acme --due 2026-08-05
python3 $T --dir $D update 3 --status in-progress --notes "已复现"
python3 $T --dir $D list --assignee dana --group-by status
python3 $T --dir $D list --status blocked
python3 $T --dir $D show 3
python3 $T --dir $D history 3
python3 $T --dir $D report # 摘要：按状态、按负责人、逾期、阻塞
python3 $T --dir $D delete 3 --yes # ⚠️ 永久删除
不带过滤条件的 list 会自动隐藏已关闭的项目。使用 --all 显示所有项目。
可用预设
tasks 任务 · bugs Bug和客户问题 · invoices 发票和催收 ·
features 功能管道
预设解析顺序
init --preset <name> 按以下顺序解析 <name>.json —— 第一个匹配的获胜：
<workspace>/trackers/presets/<name>.json—— 空间本地 预设，相对于引擎运行的工作目录<SKILL_DIR>/presets/<name>.json—— 上述内置预设
与内置预设同名的空间本地预设会覆盖它。如果预设缺失，会列出两个位置中所有可用的名称，并标记 [space]（空间） / [built-in]（内置）。
编写空间本地预设： 将一个模式 JSON（格式与 schema.json 相同，参见内置预设示例）放入 trackers/presets/ 中。该目录仅在显式使用 --preset <name> 时读取 —— 其他文件会被忽略。
铁律
- 📊 追踪器是真相的唯一来源 —— 绝不在代理的内存中保存状态。始终查询。
- ⛔
blocked（阻塞）状态需要在 notes 中注明原因 —— 否则阻塞是无意义的。 - 🗑️ 删除需要
--yes和明确的用户确认。 默认没有“已取消”状态 —— 如果需要，请将其添加到模式中，而不是删除。 - 📜 每次更改都会记录在
item_history中 —— 绝不手动编辑数据库。 - 🔁 三个或更少的状态，没有负责人，也没有截止日期 = 它本该是一个注册表。