技能使用指南

skill-status-sync（状态同步技能）Skill 是什么？如何安装？

状态同步技能Skill（skill-status-sync）一次调用即可原子同步 TODO.md 与 state.json，支持 preflight_update、postflight_update、artifact_link 三种操作，内置状态映射、幂等补链与 jq 转义防护，明确定位为独立使用。本文详解安装验证步骤、使用方法、竞品对比与真实场景体验，帮你快速告别任务状态不一致。

状态同步技能Skillskill-status-sync
8 个章节 约 16 分钟阅读 AI 智能生成

状态同步技能Skill：一次调用，让 TODO.md 与 state.json 永远说同一句话

核心结论速览

  • 状态同步技能Skill（英文名 skill-status-sync，技能ID 12870）是一个「直接执行型」原子状态同步技能，专门解决 TODO.md 与 state.json 两个文件状态不一致的老问题。
  • 它提供三个明确的操作入口：preflight_update（进入进行中状态）、postflight_update（落地最终状态并挂载工件）、artifact_link（幂等添加工件链接）。
  • 最大特点是「内联执行、不生成子代理」，避免多技能之间的暂停边界与内存开销问题，同时保证跨两个文件的更新是原子的。
  • 它明确定位为仅供独立使用：用于手动状态修正、独立脚本、工作流失败恢复和隔离测试，而不是塞进 /research、/plan、/implement 等工作流命令中。
  • 内置状态映射表、两步 jq 模式（规避转义问题）与完整的错误处理，把「手改 JSON 改崩了」的风险降到最低。

1. 该技能叫什么？如何下载安装 AI 技能提升开发效率？

基本信息

项目 内容
中文名 状态同步技能Skill
英文名 skill-status-sync
技能ID 12870
技能类型 直接执行型（内联执行，不派生子代理）
权限范围 Bash、Edit、Read、Read(/tmp/.json)、Bash(rm:)

它到底解决什么问题？

在多技能协作的 AI 开发流程里，一个任务的状态往往要同时记录在两个地方：给人看的 specs/TODO.md（用 [RESEARCHING]、[PLANNED] 这类状态标记）和给程序读的 specs/state.json（用 researching、planned 这类字段）。只要其中一处漏改，就会出现「TODO 上写着已完成、state 里还是进行中」的错位，后续工作流就会基于错误状态继续跑，最后演变成排查成本极高的连锁问题。

不仅如此，历史上用 jq 直接拼接 JSON 时，还容易踩到字符转义导致的解析失败（技能详情中称为问题 #1132）。状态同步技能Skill 的价值，就是把「改状态」这件事标准化成一次原子操作：两个文件一起改、格式统一、失败有回退提示。

一键安装的思路与步骤

AI 技能的安装通常遵循「获取技能包 → 放入技能目录 → 重启会话生效」的通用路径。由于技能详情中未提供具体的安装命令、仓库地址与版本号，以下为通用流程，具体入口与命令以官方说明为准：

  1. 确认安装前提：你的 AI 编程环境需要支持 Skill 机制，并已开启 Bash、Edit、Read 等工具权限；由于本技能会读写 specs/state.json、specs/TODO.md 并通过 /tmp 做中转，工作目录中应已存在这两个文件。
  2. 获取技能：通过官方技能市场、官方仓库或团队内部技能源搜索 skill-status-sync（技能ID 12870）并下载，具体地址以官方说明为准。
  3. 放置到技能目录：按官方文档把技能文件放入约定的技能目录（不同宿主环境的目录约定不同，以官方说明为准）。
  4. 重启或刷新会话：让技能注册到当前会话，确保模型能识别到该技能。
  5. 验证是否生效：在一个测试任务上调用一次 preflight_update，检查是否返回带 status: "synced"、summary、previous_status、new_status 的 JSON 对象；若同时观察到 state.json 的时间戳与 TODO.md 的状态标记都已变化，即说明安装成功。

2. 该技能的主要功能和特点

  • 三操作覆盖完整生命周期：preflight_update 对应 GATE IN 检查点（设置进行中状态），postflight_update 对应 GATE OUT 检查点（设置最终状态并链接工件），artifact_link 用于工件创建后的单独补链。
  • 跨文件原子更新：一次操作同时修改 state.json 与 TODO.md，避免「只改了一半」的中间态。
  • 状态映射标准化：not_started → [NOT STARTED]、researching → [RESEARCHING]、planning → [PLANNING]、implementing → [IMPLEMENTING]；收尾阶段则是 researched → [RESEARCHED]、planned → [PLANNED]、implemented → [IMPLEMENTED]、partial → [PARTIAL]。
  • 工件链接幂等：artifact_link 会先检查 TODO.md 中是否已存在该路径，存在则返回 skipped，不会重复插入链接。
  • 内联执行、无子代理开销：技能内联执行，不生成子代理，直接规避了内存问题与多技能暂停边界问题。
  • 两步 jq 模式防转义报错：写 JSON 时先更新时间戳、再追加数组元素，两段式写法专门规避问题 #1132 的转义陷阱。
  • 插入位置有规则：research 链接插在 Language 行之后，plan 插在 Research 行之后（无 Research 则插在 Language 行之后），summary 插在 Plan 行之后，保证 TODO.md 结构稳定可读。
  • 完整错误处理：任务不存在、状态转换非法、文件写入失败、jq 解析失败都有对应的失败返回与处置建议；jq 失败时会记录到 errors.json 并用两步模式重试。
  • 边界清晰：详情中明确标注「仅供独立使用」，工作流技能已内联处理自己的预检/后检状态更新。

和普通工具比强在哪？ 普通做法是「手工改两个文件」或「随手写一段 jq」——前者容易漏、后者容易因转义炸掉。本技能把校验、映射、写入顺序、幂等判断一次性固化成可复用动作，并返回结构化 JSON 结果，便于脚本和后续流程消费。

3. 如何使用该技能？

步骤 1：明确调用方式。 该技能属于手动触发的独立技能，通常在对话中直接点名调用，或由独立脚本按技能约定调用。以下为参数示例，具体语法以官方说明为准。

步骤 2：调用 preflight_update（进入进行中状态）。 需要提供任务编号、目标状态（必须是 researching / planning / implementing 之一）、会话标识：

operation: preflight_update
task_number: 12
target_status: researching
session_id: manual_correction

执行后技能会先校验任务是否存在于 state.json，再更新 status 与 last_updated，最后修改 TODO.md 的状态标记，并返回：

{
  "status": "synced",
  "summary": "Updated task #12 to [RESEARCHING]",
  "previous_status": "not_started",
  "new_status": "researching"
}

步骤 3：调用 postflight_update（收尾并挂载工件）。 目标状态必须是最终变体（researched / planned / implemented / partial），并传入工件数组：

operation: postflight_update
task_number: 12
target_status: researched
artifacts: [{path: "specs/012/research-012.md", type: "research"}]
session_id: manual_correction

返回结果中会包含 artifacts_linked 列表，例如 ["specs/012/research-012.md"]。

步骤 4：单独补链用 artifact_link。 当某个工件是事后生成的，只补链接不改状态：

operation: artifact_link
task_number: 12
artifact_path: specs/012/research-012.md
artifact_type: research

若该链接已存在，返回 status: "skipped" 与 summary: "Link already exists"；否则返回 status: "linked"。注意技能会自动剥离 specs/ 前缀再写入 TODO.md 的相对链接。

步骤 5：核对结果。 检查返回 JSON 的 status 字段是否符合预期，并顺手看一眼 TODO.md 对应 ### {task_number}. 条目下的状态标记与工件行。

输入输出要点小结：输入是「操作类型 + 任务号 + 状态 + 会话标识（+ R工数组）」；输出是「状态结果 + 摘要 + 前后状态 + 已链接工件」。失败时返回失败状态，并附带当前状态、允许的转换或权限建议。

4. 同类型竞品对比分析

方案名称 定位 核心功能 安装/使用门槛 适用场景 优势与不足
状态同步技能Skill（skill-status-sync） 专用原子状态同步技能 三操作读写 state.json 与 TODO.md、状态映射、幂等补链、错误处理 需支持 Skill 的环境，工作目录需已有两个目标文件；学习成本低 手动修正、独立脚本、失败恢复、隔离测试 优势：原子、幂等、返回结构化结果、规避 jq 转义坑；不足：明确不支持在工作流命令中直接使用
手工编辑两个文件 最原始的替代方案 人肉改 JSON 字段与 Markdown 标记 零门槛 一次性、极简单的小改动 优势：无需依赖；不足：极易漏改、无映射校验、易写坏 JSON、无法幂等
自写 jq/Shell 脚本 团队自定义自动化 按需实现状态写入与工件追加 需熟悉 jq 语法与转义规则，维护成本高 有固定格式的定制流水线 优势：可自由扩展；不足：转义易出错（正是问题 #1132 的来源）、缺少统一错误处理与幂等逻辑
工作流技能内置状态更新 流程内建能力 在 /research、/plan、/implement 等命令中内联更新状态 随工作流技能一起获得 标准工作流全自动推进 优势：流程顺滑、无暂停边界问题；不足：不做流程外的独立修正，手动补状态时仍需本技能

5. 该技能的典型应用场景与实际体验情况

场景一：AI 助手「跑飞了」之后的手动状态修正。 角色：使用多技能工作流的开发者。痛点：某次会话中断，TODO.md 显示 [RESEARCHING]，state.json 却仍是 not_started，后续命令据此判断错误。使用方式：调用 preflight_update 把两边统一到 researching，再继续推进。实际体验：一次调用即可对齐两个文件，返回的 previous_status / new_status 让人一眼看清改了什么，比逐个文件翻找快得多。注意：目标状态必须落在允许的变体集合内，否则会收到「无效状态转换」的失败返回。

场景二：独立脚本的收尾环节。 角色：写自动化小脚本的工程师。痛点：脚本生成研究报告后，需要把文件挂到任务条目上，但不想引入整个工作流技能。使用方式：脚本末尾调 postflight_update，把 {path, type} 数组一并传入。实际体验：返回的 artifacts_linked 可直接作为脚本日志，省去自己写 jq 拼 JSON 的一段代码，也避免了转义翻车。

场景三：工作流失败后的恢复操作。 角色：需要「救场」的维护者。痛点：工作流中途异常，工件其实已生成但没登记。使用方式：先用 artifact_link 单独补链（幂等，重复执行不会产生重复行），再视情况用 postflight_update 落最终状态。实际体验：幂等判断非常省心，反复调用不会污染 TODO.md。注意链接会被自动剥离 specs/ 前缀，写路径时按约定传入即可。

场景四：隔离测试状态更新行为。 角色：在改造流程前做验证的工程师。痛点：想确认状态机行为是否符合预期，又不敢直接在工作流里试。使用方式：在测试任务上用 session_id 标识测试会话，跑一遍 preflight/postflight/artifact_link 全链路。实际体验：上手难度低，三条操作语义清晰，返回 JSON 结构固定，便于断言与回归。

6. 该技能能为用户带来的价值

  • 消灭「双写不一致」这一类隐性 Bug：把两个文件的更新收敛为一次原子操作，从根上减少「TODO 与 state 打架」导致的错误决策与重复返工。
  • 降低工具门槛：不需要背 jq 语法、不需要记状态映射规则，调用方只关心「操作 + 任务号 + 目标状态」三个要素。
  • 减少失败成本：内置任务存在性校验、状态转换校验、文件写入失败提示与 jq 解析失败重试路径，出错时给出可执行的下一步，而不是留下一份损坏的 JSON。
  • 避免资源浪费：内联执行、不生成子代理，省去子代理带来的内存开销与技能间的暂停边界问题。
  • 长期可维护性：统一的状态映射与固定的 TODO.md 插入顺序，让团队里任何人打开文件都能读懂当前进度，为后续自动化与审计打好基础。

7. 常见问题 FAQ

Q1：这个技能怎么安装？装了怎么确认生效？ 按官方说明把 skill-status-sync（技能ID 12870）放入技能目录并重启会话即可，具体命令与目录约定以官方说明为准。验证方法是调用一次 preflight_update，看到返回 JSON 里 status 为 synced，且 state.json 与 TODO.md 同步变化，即代表生效。

Q2：为什么说它「仅供独立使用」？我能在 /research、/plan 里用吗？ 不建议。技能详情明确说明：工作流技能（如 skill-researcher、skill-planner、skill-implementer）现在内联处理自己的预检/后检状态更新，在工作流命令中直接调用本技能会重新引入多技能暂停边界问题。它更适合手动修正、独立脚本、失败恢复与隔离测试。

Q3：preflight_update 和 postflight_update 有什么区别？ 前者用于 GATE IN，只接受进行中状态（researching / planning / implementing）；后者用于 GATE OUT，只接受最终状态（researched / planned / implemented / partial），并额外支持传入工件数组完成链接。

Q4：重复调用 artifact_link 会不会产生重复链接？ 不会。该操作是幂等的：执行前会先检查 TODO.md 中是否已存在该路径，已存在则返回 skipped 与「Link already exists」。

Q5：适合谁用？和自写 jq 脚本怎么选？ 适合正在使用 TODO.md + state.json 双文件管理任务状态的开发者与自动化脚本作者。如果你的需求是一次性的、格式极简单的改动，手改也能应付；但只要涉及状态映射、工件追加和反复执行，本技能在正确性与可维护性上明显优于自写 jq 脚本。收费与否、授权范围等信息以官方说明为准。