sign-off-axi

sign-off-axi

sign-off-axi 会将你的问题放在一个本地页面（127.0.0.1）上，用户只需单击即可逐一回答，你之后可以查看保存的答案。 每个问题都是一个条目：发布问题，等待，再读取答案。 看板包含五个区域：Today（需要用户处理的事项、今天已验证的内容以及你的回复）、Decide（所有等待处理的请求，以及待审核的设计；在手机上点击 Show more 可显示后续行，计数不会改变）、Evidence（证据，不是请求）、Reports（说明文档）和 Tickets（工作内容，按史诗、工单和任务组织）。 每张卡片都会打开自己的页面，包含一个操作栏（回答，或对报告执行 Agree、Disagree、Comment 和 Ask）、一个 Activity（谁发布了内容、每个答案、备注、评论和回复，以及各自的进展）以及可在打开该卡片的列表中前后切换的 Previous 和 Next。看板会显示自身版本（--version、侧边栏底部、Today's More），并可安装为应用：在 HTTPS 或 localhost 上依次选择 More、Install app。

如果未指定看板文件，命令会使用项目中由 npx -y sign-off-axi init 设置的最近 .sign-off/ 看板（向上查找到仓库根目录）；若不存在，则使用 ~/.sign-off/decisions.json。只有在需要使用其他看板时，才在命令后指定看板文件。测试和临时运行绝不能连接到用户自己的看板：请将 SIGN_OFF_HOME 设为临时文件夹。 使用 open <board> 启动临时服务，或在前台运行 serve <board> 后，结束前请使用 npx -y sign-off-axi stop <board> 停止服务（使用同一个看板文件）。不要通过 shell 终止输出中显示的 PID，也不要让服务运行到超时：stop 会检查记录的服务是否正在为该看板提供服务，并确保不影响其他看板。

当前指南以 CLI 为准

不要依据本文档获取命令、标志或输出信息——已安装的副本可能过时。请从 CLI 获取最新的准确信息：

• npx -y sign-off-axi --help 查看命令、看板和示例
• npx -y sign-off-axi <command> --help 查看某个命令的标志

你无需全局安装 sign-off-axi——使用 npx -y sign-off-axi 调用即可。 如果 sign-off-axi 的输出中显示以 sign-off-axi 开头的后续命令，请改为运行 npx -y sign-off-axi ...。 每个常规 sign-off 命令都不会调用模型。选择启用的独立所有者分发器会使用常规凭据和可选的已注册模型，恢复已注册的 Claude Code 会话。

以事件形式接收答案

答案会直接送达，无需任何人替你留意。

1. 为自己选择一个 filer id：你的 Agent 会话 id，或任意短名称（由 1–128 个 A-Z a-z 0-9 . _ - 字符组成）。如果未提供，发帖时会在存在 Claude Code 会话 id 的情况下保存该 id。卡片的 Activity 会显示短名称，标明发帖者和领取答案的人；如果显示的是纯会话 id，则会显示 Agent。
2. 每次发布内容时都使用 --filer <id>，或者为每条命令设置一次环境变量 SIGN_OFF_FILER=<id>。
3. 发出提问、计划或引导式报告后，立即运行 npx -y sign-off-axi wait --filer <id>（使用与发帖时相同的 board 文件；证据帖不会等待）。它会返回你尚未处理的所有内容的答案，即使答案是在你开始等待之前给出的；随后，board 会在对应卡片上将其显示为已读。它还会返回你引导式计划或报告上的深入了解操作（按照下方报告一节所述进行回复）。每次收到回复以及计划被退回后，都要再次运行它；即使没有需要回复的内容，引导式页面也会继续监听。对方之后可以更改答案：更改后的答案会作为带有 replaces 的新答案返回（该字段指向被替换的答案，而你可能已经根据旧答案采取了行动）；请改为依据新答案行动。TIMEOUT 表示再次运行；NOT_FOUND 表示你的内容都不在等待中，且没有内容支持“深入了解”操作。只有绑定 filer 的 wait 才会接收“深入了解”操作；面向整个 board 的答案等待会将它留在队列中。这需要有正在运行的监听器：它不会唤醒休眠的 Agent 会话。
4. 根据答案、备注、设计变更备注、新一轮内容或评论采取行动后，请告知对方：npx -y sign-off-axi feedback <key> --reply "<what you did, one or two lines>" --link <the pull request or new version>（也可以使用 --acted --link <url>，不附带文字）。对方在卡片上发送的任何内容（答案、备注、新一轮内容、评论）都会显示其处理轨迹：已发送、已送达（你的 wait 或 on_answer 钩子已收到）、已读以及已回复，并附上你的回复文字和链接；回复会显示在对方的 Today 中。已读但尚未行动：feedback <key> --read；仅确认已交接：--delivered。--at <epoch seconds> 可记录较早发生的步骤（重放）：卡片上已显示的步骤会保持不变，因此可以安全地重复运行。再次发布卡片会将对方发送的内容标记为已处理。
5. 如果要在 Claude Code 会话空闲时单独使用“深入了解”，请在编写内容时注册该会话的实际 UUID：运行 npx -y sign-off-axi owner <board> --filer <id> --host claude --session <actual UUID> --cwd <absolute project folder>（可选参数为 --model <model id>）。使用主机提供的会话身份，不要编造 id，也不要注册其他会话。如果主机尚未提供你的 UUID，请说明目前无法注册。运行单独的本地进程 npx -y sign-off-axi owner <board> --dispatch --timeout 3600；该进程退出后请重新启动。不要同时使用 wait 来接收该所有者的请求。仅支持 Claude Code；无需 Firstmate。唤醒后，检查请求和原始文档，使用 owner <board> --ack <id> 确认收到确切的 id，然后发送一条最终回复 deeper <board> --id <id> --text "<answer>"，不要使用 --more。重试会保留请求，不会追加到已完成的答案中。owner <board> 会将排队失败的请求与已送达和所有者已读的请求分别显示；不要提供替代答案。现有的活动监听器仍支持流式分段回复。
6. 如果你无法阻塞等待，board 所有者可以在 board 旁的 config.yaml 中设置 on_answer: <command>：每收到一个答案，就会运行该命令，并将答案作为 JSON 传入其标准输入；不会经过 shell（因此 | 和 > 不会生效；请指定脚本）。运行 npx -y sign-off-axi doctor 可检查它是否能够运行。

确保每张卡片都能让人在手机上用 10 秒读完

用户经常在手机上查看看板。每张卡片都必须让不写代码的人能在 10 秒内看懂。

• 标题：用一个简短句子说明结果或提出问题：“现在可以使用通行密钥登录了”“这周发布新的登录方式吗？”。绝不能是工具名称、运行 ID、版本标签、文件路径或错误代码。
• --about：用 1 或 2 个简短句子说明用户能看到哪些变化。采用 ASD-STE100 简明技术英语：句子简短、使用主动语态、使用常见词汇。
• 在卡片上展示证据：使用 --type evidence 发布待检查的结果，并附上截图或录屏（--media）；用户可选择 Pass、Fail 或 Needs work。证据行会在标题旁显示第一张截图和检查结果（Passed、Failed、Not run），点按后会在原处展开该行，并以可滑动条带显示所有截图：将能证明所述内容的截图放在最前面，标题写明结果。图片比文字更能说明问题时，请添加示意图或交互式页面（见下文）。
• 提供可从卡片下载的文件，例如可供安装的 Android 构建版本：添加 --attach <file>（最多 5 个文件，类型不限，默认每个文件最大 1 GB；SIGN_OFF_ATTACH_MAX_MB 可更改限制）。用户可在手机或平板电脑上点按卡片中的 Download。文件会复制到看板旁边并以流式方式传输，不会读入内存；卡片需要提供 --media 截图，也可以只包含文件。
• 每张卡片只询问一个决定，并推荐你会选择的答案（见下文的问题标准）。
• 在 --link 中提供拉取请求或页面链接。在带有 run 的契约证据消息中，outcome 行会作为卡片标题：请写成用户能看到的结果。

将每张卡片关联到对应工单

如果工作属于某个工单且你知道其 ID，请在该工单的每条 raise 和 post 命令中传入 --ticket <id>（任何 --type 或 --kind，或消息或 --from 项中包含 "ticket"）。卡片随后会显示 Ticket 行，其中包含工单标题和进度；点按该行可打开工单并查看其所有卡片。

• 此参数是可选的，仅作引用：不知道工单时不要填写，也绝不要编造 ID。如果工单不在看板上，卡片不会显示此行，其他功能与之前相同。
• 工单可独立存在：npx -y sign-off-axi ticket --id <id> --title "<the work>" --progress <0-100> 可创建工单，工作进展时再次使用 --progress 更新进度。工单可按 Epic > 工单 > 任务的层级嵌套：使用 --parent <id> 可将一个工单放在另一个工单之下；如果一个工单下有其他工单，其进度会取这些工单的平均值，因此请更新没有子项的工单进度。知道优先级和项目时，添加 --priority P0-P3 和 --project <name>；工作等待时添加 --hold yes（继续后改为 --hold no）；用户提出该工作时添加 --asked yes；添加 --release <label> 指定包含该工作的版本；使用 --state queued|"in progress"|"on hold"|done 设置工单的列表状态（此设置优先于进度和 hold）；使用 --pr <url>（可重复使用或以逗号分隔）添加拉取请求：工单页面会显示版本、状态和每个关联的 PR；--pr 会替换列表，因此请一次传入全部 PR。将字段设为空值可清除该字段。只能编写你自己的工单。ticket --id <id> 会显示工单及其卡片；ticket 会列出所有工单。

说明卡片的紧急程度，并为项目设置图标

• 知道卡片的紧急程度时，在 raise 和 post 命令中传入 --priority P0（最紧急）到 P3（最不紧急）（任何 --type 或 --kind，或消息或 --from 项中包含 "priority"）。卡片会以标签形式显示优先级，看板也可以按优先级排序。不知道时不要填写：没有优先级的卡片不会显示标签。
• 项目有专属图标时，将图片放入看板文件夹，然后运行一次 npx -y sign-off-axi project --name <project> --icon <path from the board's folder>（.png、.jpg、.webp 或 .svg 格式，不得含脚本，大小不超过 500 KB）。项目名称应与你的卡片中使用的名称一致。没有图标的项目会显示首字母；绝不要为其绘制或编造图标。

提出好问题

如果问题违反这些规则，sign-off 会拒绝，并指出相关字段和一种修正方法；raise --help 可查看当前标志。

• 新的 Decide 问题需要 --ask-ref <captain-message-id-or-hold-id>（在消息或动态中为 ask_ref）：引用需要此答案的 captain 消息或实际 hold。请使用真实 ID，不要编造引用。CLI 会检查其格式，但不会检查它是否存在于其他工具中。后续问题应放入待办列表，而不是看板。计划、报告、证据、参与记录以及已发布的卡片仍可正常使用。
• 一个决定对应一张卡片。发布前，运行 npx -y sign-off-axi list --full 并查看未处理的卡片。如果已有相同决定，就不要再次提问：等待该卡片；或者，为了更好地提问，使用 --merge <its key> 发布一张卡片：旧卡片必须包含新卡片的所有选项，并且也会在答案给出后隐藏并关闭。绝不要为一个决定发布第二张卡片：如果提问重复了一个未处理的问题（答案相同，标题中的词语有至少 80% 相同），就不会发布，并会在拒绝信息中指出应等待的卡片。一张卡片得到回答后，同一决定下的所有未处理问题都会采用该答案。一张卡片在对应问题得到回答前只属于该问题；合并后的卡片本身不会再合并其他卡片，已回答或已撤销的卡片也不会被合并。
• 标题：用 12 个或更少的词写成一个普通疑问句，以“？”结尾，且按钮能回答该问题。不得添加“Say yes or no:”“Captain hold:”或“Captain:”前缀，不得包含任务名称或 ID。
• --why：用 1 或 2 行简短说明问题内容，以及为何现在需要答案。
• 按钮应与文本中的选项一致：是非题使用 Yes 和 No；选择题则每个选项使用一个 --option，每个标签都以对应字母（A、B、C）开头。使用 Yes/No 按钮时，文本中不得出现 A/B/C；问题中也不得使用 Done 或 Not now 按钮。
• --outcome <value>=<text>：说明选中该答案后接下来会发生什么，每个选项各用一行。
• 使用 --recommend 指出你会选择的答案，并用一行 --recommend-reason 说明理由。
• --default：说明用户不回复时会发生什么，以及用 --silent-by <ISO UTC time> 指定时间。用户的 leash 决定届时会发生什么：在 When it matters（默认模式）下，未处理的看板会在 --silent-by 指定的时间采用 --default；在 Act, then tell me 模式下，你的 raise 会立即采用 --recommend，并说明 picked <value>；在 Ask me first 模式下，不会采用任何选项。以这种方式采用的答案会通过 wait 返回，并带有 taken: default 或 taken: agent：继续执行该选项并保持等待，因为用户仍可更改答案（更改内容会带有 replaces）。切勿自行替用户做决定。
• 对于会删除或覆盖内容、无法撤销、会花费资金、涉及密码或密钥，或会改变访问权限的问题，使用 --guard destructive|irreversible|money|credential|security：无论 leash 如何设置，都不会采用默认答案或其他选项。看板也会根据问题措辞识别此类问题并启用保护，但只要适用，就应明确指定 guard。
• 如果误发了卡片：npx -y sign-off-axi dismiss <key> 会将其隐藏，restore <key> 会将其恢复。用户在卡片上点击 Discard 并选择原因（Not relevant、Replaced by newer 或 Done elsewhere）后，卡片会移至 Archived；点击 Undo 可在 10 秒内恢复。随后，你的 wait --filer 会通过 discarded 返回该卡片及其原因（--events 中会有一行 "event":"discarded"）：停止执行卡片要求的工作。answers 也会在 discarded 下列出它。要自行执行同样的撤销操作，请使用：dismiss <key> --reason not-relevant|replaced|done-elsewhere。
• 任务结束时（已合并、已放弃，或已通过其他方式回答），运行 npx -y sign-off-axi dismiss --filer <id>：你发布的所有仍在等待的卡片都会从 Decide 中移除。报告会在提交一天后自动从主视图移除；它们会在各自屏幕的 Archived 下等待，使用 restore <key> 可恢复。证据会一直保留在 Evidence 屏幕上，直到被撤销；使用相同的 key 再次发布但提供不同证明，会替换该卡片。不会删除任何内容。 一个好的“是/否”问题：

npx -y sign-off-axi raise --ask-ref <captain-message-id-or-hold-id> --title "Ship the new sign-in screen this week?" \
  --why "The screen is ready and the release goes out Friday." \
  --outcome yes="It ships to everyone on Friday." --outcome no="It waits for next week's release." \
  --recommend yes --recommend-reason "Every check passed on 3 phones." \
  --default no --silent-by 2026-10-19T16:00Z

一个好的 A/B/C 选择题：

npx -y sign-off-axi raise --ask-ref <captain-message-id-or-hold-id> --title "Which day should the release ship?" \
  --why "Two fixes are still in review." \
  --option a="A: Today" --option b="B: Friday" --option c="C: Next week" \
  --outcome a="It ships now, without the 2 fixes." --outcome b="It ships with both fixes." --outcome c="It waits for the redesign too." \
  --recommend b --recommend-reason "Both fixes land by Thursday." --default b

证据用于证明；报告用于说明；计划用于请求批准

• 证据：证明某件事确实有效的内容，可以是实际产品的屏幕截图或片段（--type evidence）。它会放在 Evidence 中，绝不是请求，因此绝不要把证明内容作为问题发布；只有文字或占位图片的内容会被拒绝。
• 计划：你打算做什么，供用户在你开始前审批（post --kind plan --from plan.json；形状见 post --help 和包文档中的契约）。用户会审批或修改每个部分，回答每项决定，然后一次性全部发回：像处理请求一样等待，并使用 answers --json 阅读（每个部分一条备注，每项决定一个值）。
• 设计评审：post --kind design（schema 2）会放在 Designs 下（手机上是 Decide 的第二个列表），由负责分流设计的人评审，绝不会直接进入用户的 Decide；此人执行 promote <key> 后，卡片才会进入 Decide。绝不要自行运行 promote。设计卡片只能是一个简单问题，由读者回答 Yes 或 Change：
  • 标题就是这个问题，不超过 12 个词，例如“是否批准 Reports 的这个新版手机端列表末尾？”。不能是任务或分支名称、PR、切片、Agent 的消息 ID 或文件名；about 中也不能出现这些内容，也不能是屏幕标题或说明文字：否则 post 会拒绝。
  • 每个发生变化的状态一张屏幕截图（最多 8 张；不能在三个宽度下展示同一状态），每个画面各有一张图片：仅在内容不同时提供 today（当前上线版本）、built 或 proposed（新外观）和 target（已批准的设计）。删掉看起来与其他画面相同的画面：如果两张画面的差异小于 0.1%，post 会拒绝。绝不要把几列画面放在一张图片中：看板会自行排列并标注画面。
  • 每个画面都要用 area（图片中的比例）框出变化之处，并用一行 caption 说明。截取能显示变化的状态：静止时看不到的淡入效果或移动的线条，需要截取滚动后的状态。
  • accepts 指定 Yes 所批准的画面。分流者的评审结论填入 reviewed。形状见 post --help，示例见包中的 fixtures/contract/design.v2。
• 报告：深入的说明，仅在用户要求解释，或必须弄清某个概念、设计或权衡时使用。合并、PR 结果、收据、评审结论或状态备注都不是报告。
• 报告由看板绘制为一个可滚动页面的字段组成，绝不是文本卡片，也不是你构建的页面。运行 npx -y sign-off-axi report init .sign-off/reports/<key> --purpose <kind>，替换 report.json 中的每一行 FILL:，然后运行 npx -y sign-off-axi post --kind report --from .sign-off/reports/<key>/report.json --filer <id>。保留为 FILL: 的文字会被拒绝。
• 每份报告都要在 purpose 中说明用途和类型；report init 和 post 会拒绝缺少这些信息的报告。若报告发布时没有填写类型，则需用 report kind <key> <kind> --by <your id> 补上。选择最合适的一项：research（研究与探索：问题、选项、来源）、plan（实施计划：逐步说明如何完成工作）、decision（决策与建议：权衡一个选择）、audit（根据标准检查了什么，以及需要修正什么）、incident（事件复盘：出了什么问题、原因是什么、有哪些改变）、status（工作进展），或在都不适用时选择 other。看板会在报告的列表行和标题中显示类型，并附上一行用途说明；用户可以按类型筛选 Reports。
• 计划结构相同，只是包含由用户决定的问题：运行 report init .sign-off/plans/<key> --plan，填写 plan.json，然后运行 post --kind plan --from <file> --filer <id>，接着运行 wait --filer <id>。用户可以点击 Go ahead，接受你推荐的所有选择，因此请推荐你自己会采取的做法，并在 quiet 中说明用户未回复时会发生什么。
• 按看板展示的顺序，为读者撰写每个部分：这是什么（答案和一张图片：条形图、步骤图或方块图，或设计、架构或计划报告所需的示意图）、我的理解（用你自己的话复述请求，让用户指出理解是否有误）、我的发现、我的建议（计划）、你要决定的事项（计划，最多五个问题，每个问题都要写明你的选择及理由）、下一步。
  • 先给答案：图片的标题就是答案，用一句简单的话表达。
  • 每个要点配一张图片；数字放在 details 中，点击后再显示，绝不要写在句子里。
  • 句子要简短：text 写一行，more 写展开后显示的内容；各要点之间换行。绝不要写成需要读者滚动查看的段落。
  • 用不写代码的人也能理解的简单词语；不要写 ID、文件路径或工具名称。
  • 如果事实会过时，请注明事实成立的日期。
• 研究报告（比较、选项研究、“我们应该使用 X 吗？”之类的问题）必须达到高于说明文的标准。仅凭你自己的数据支持少数几个选项，会被拒绝。
  • 先列出必备条件。调查所有真实可选项，再根据这些条件筛选出候选项。用一行说明每个选项被淘汰的原因。
  • 为每个候选项使用相同的评估维度，并列出完整的优缺点，放在一个便于比较的表格中：每个选项各有一个 found 项目，在 text 中写优缺点，在 more 中按相同顺序逐行写出每个维度，格式为“维度：值。”。看板会将此部分绘制为一个表格；旧版看板则会将相同行内容显示为文本。
  • 每项主张都要附上外部依据及链接：GitHub issues（未修复的 bug、回归问题、升级故障以及维护者的答复）、Reddit、Hacker News、X、论坛和博客。如果网站阻止抓取，请说明无法读取的内容。厂商营销内容、星标数和你自己团队的工作日志数据都不是证据。
  • 将你亲自核实的内容与他人提出的主张分开：单独设一个部分，或让每行都以“Checked:”或“Reported:”开头。
  • 结尾要给出明确的首选建议和备选方案，并分别说明理由。
• 计划中的每个选择都必须达到相同的研究标准，然后提供用户批准所需的信息：选项及其优缺点、你的建议、范围（包含和不包含的内容）、按顺序排列的步骤、每项风险及应对措施，以及如何证明工作已完成（在 understood 中写明 Done when，并在 next 中说明证明材料放在哪里）。
• 新版引导式默认格式为计划 schema 3 和报告 schema 5（contract 1），且必须填写 filer。旧版 schema 仍可加载。计划的每个部分，以及报告当前所显示部分的一条提示栏，都提供 Ask a question、Go deeper、Simplify this、Show an example、Why?，以及自由文本和后续追问。点击 Ask a question 会聚焦到部分编辑框；必须填写文字并点击 Send。其他预设会立即发送。问题和自定义内容必须包含非空白文字（最多 500 个代码点）；自由文本和后续追问使用自定义选项。请在对应部分针对具体操作和问题作答：解释、补充细节、使用更简单的词语、举例或说明原因。所有请求都使用同一条交互流程：版本 1 会携带操作、不可变的所有者、文档修订版和目标，并可选带上选段（所撰写的字段、代码点起止位置、原文引述）；如果包含选段，就要针对文档中原位显示的引述内容作答。使用 deeper --json --all 读取这些字段；依据原始文档执行请求的操作作答，绝不要改写文字或更改计划决策。处理活跃回复时必须使用 --filer <your id>；已注册会话须先确认确切 ID。过期目标和其他所有者的请求会被拒绝。答案会就地展开，并在明确被阅读之前，即使重新加载仍保持 New。发布报告和计划后，以及每次回复后，都要让所有者分发器/监听器保持运行。
• 看板会显示每个部分由谁阅读以及阅读时间，并在每个部分下方显示支持的预设。用户点击预设后，wait --filer <id> 会返回请求（包括操作、部分和任何问题）；也可以运行 npx -y sign-off-axi deeper <board> --filer <id> 列出未处理请求。活跃监听器应使用简单的语言分几行作答：每段内容运行一次 npx -y sign-off-axi deeper <board> --filer <id> --id <id> --text "<what you found>" --more，最后一段则不带 --more。已注册但处于休眠状态的所有者应按上述说明确认请求并发送最终答案。看板会将每段内容实时显示在用户点击的位置。用户对某个部分点击 Agree、Disagree 或 Comment 时，同一个 wait 会收到包含该部分和文字的事件；使用相同的 deeper --id <id> --text 回复，并在用户说得有理时修改页面。绝不要写长篇大论：简短作答，用户可以继续追问。
• 在告诉用户看板已就绪前，先以 390 px 宽度打开看板并查看：首屏必须给出答案和图片。
• 关于设计产出（屏幕截图、模型制作的 mockup 或选项）的报告必须始终附带图库，绝不能直接粘贴图片：运行 report init <folder> --purpose <kind> --gallery，将每个选项的屏幕截图保存在看板文件所在的文件夹中（手机画面宽 390，桌面画面宽 1280，无需准备浅色版本），并在第一部分填写图库：每个选项填写 label、制作该选项的 model 和 ran（UTC）；每个画面填写 device（phone 或 desktop）、src 和说明画面内容的 caption。没有说明或设备类型的画面会被 post 拒绝。看板会将选项绘制为可滑动的横排（桌面端为一行），并列显示两种画面，点击后可打开全尺寸图片。
• 使用看板自带的内容块展示报告部分，绝不要使用自制 HTML 或 CSS：在部分中添加 blocks：callout（单独展示的备注、警告或问题）、beats（由图片组成的步骤条，每步包含时间、标题和文字）、video（带封面的影片）、table、compare（前后对比）和 evidence 行（状态为 fixed、progress 或 waiting）。将文件放在看板文件旁边；post 会将其固定。若第一段文字重复了 about 中的内容，post 会发出警告：此处应写新内容。
• 使用看板自带的工具包（下一章）撰写报告，绝不要写成自制页面。只有在演示必须由读者点击，且没有任何内容块可以展示时，才使用页面（参见 report init <folder> --page --purpose <kind>）。

使用白板的组件撰写报告

你为白板提供文字、文件和表格；白板会用自己的字体和配色来呈现，支持浅色和深色模式，内容在单栏中铺满宽度。撰写报告时，切勿编写 HTML、CSS、颜色或卡片：自己制作的页面无法与白板保持一致，而计划或报告若要供人阅读，就必须与白板的其他内容风格一致。

1. 运行 npx -y sign-off-axi report init .sign-off/reports/<key> --purpose <kind>（设计输出请添加 --gallery），然后填写每一处 FILL: 行。没有内容可展示的报告无需添加区块。
2. 用区块展示内容，而不是写成段落：在章节中添加 blocks（按给定顺序排列，1 到 12 个）。将每张图片或影片与 report.json 放在同一目录，并按路径命名；发布时会固定这些文件。
3. 发布：运行 post --kind report --from .sign-off/reports/<key>/report.json --filer <id>。以 390 px 宽度打开白板，分别查看浅色和深色模式，确认无误后再说报告已就绪。

根据读者需要查看的内容来选择区块：

区块	用途	字段
callout	单独强调一项内容：注意事项、警告或问题	tone（note、warn 或 ask）、title（60）、text（280）
beats	读者需要逐步浏览的内容序列：影片场景、流程	beats，2 到 12 个；每个包含 image、time、title（80）、text（280）
video	短片	src（.mp4 或 .webm，50 MB）、poster、length、caption
image	中立的参考图片，不作判断	src、caption（280）、可选的 alt（280）；图片整体保持原始宽高比
file	供下载的本地文件	src（任意文件，最大 5 MB）、caption（280），像媒体文件一样固定；下载时作为附件
table	原始数据，包括不规则表格	columns（1 到 20）、rows（最多 30）；单元格为文本（120）或 {text, colspan, rowspan}；保留空单元格和原样编写的不齐整行。宽表或不规则表格在手机上可在区块内滚动
compare	前后对比	before 和 after，各自包含 image 和 caption（80）
evidence	为每项状态提供截图	rows，每项包含 image、title、note、status（fixed、progress 或 waiting）

• 每个区块表达一个观点，每个要点对应一个区块；数字表格胜过三段数字描述，屏幕步骤组件胜过编号列表。
• 每个部分都要提供新信息。如果某个章节的首段重复了 about 中的内容，发布时会发出警告，但不会拒绝。
• 模型生成的选项应使用图库，而不是图片列表：请参阅上方的设计输出规则。gallery 和 blocks 可同时用于一个章节，图库放在前面。
• 文件路径必须位于白板目录内，且不得包含 ..、?、# 或反斜杠。发布时会固定文件内容；文件更改后，必须重新发布才能使用。
• 图片格式为 .png、.jpg、.jpeg 或 .webp；路径不得包含 ..、?、# 或反斜杠。
• 所有标题和标签都使用句首字母大写格式；不要全大写，不要使用颜色词，也不要在任何字段中使用标记语言。
• 自制页面（report init --page）首次发布时也必须符合白板风格：若页面自定义了三种或更多颜色，或在卡片中绘制卡片，发布会被拒绝，并提示使用区块。脚手架本身不会绘制这些内容；请使用系统颜色（Canvas、CanvasText、GrayText）。已发布到白板的报告会保持提交时的样子。

遵循报告类型对应的工作流

每种报告类型都有优秀团队撰写此类文档时会依次包含的部分。每个部分单独设为一个 "part": "<id>" 章节（最多 10 个章节）；如果报告 5 缺少某个部分、重复某个部分，或包含不属于该类型的部分，post 会拒绝该报告并指出如何修正。report init <folder> --purpose <kind> 会写入所有部分，供你填写。看板会将这些部分显示为报告的进度条，读者每读完一个部分，该部分就会填充。

• research（研究与探索；参考 GOV.UK 的探索阶段等探索简报，https://www.gov.uk/service-manual/agile-delivery/how-the-discovery-phase-works，以及 Teresa Torres 的机会解决方案树，https://www.producttalk.org/opportunity-solution-trees/）：`question`（问题，以及它为何此刻重要）、`scope`（范围内和范围外的内容）、`method`（研究方式）、`sources`（至少 3 项，每项都包含 link 和 "source": "primary" 或 "user"，且至少包含一份用户报告：issue、论坛、Reddit、Hacker News 或 X）、options（至少 2 项，采用相同的维度，以便看板绘制成一张表）、findings（每项都包含 "confidence": "high" | "medium" | "low"）、not-checked（未检查或无法阅读的内容）、recommendation（你的首选方案和次选方案）、open-questions。看板会在报告顶部统计链接来源和用户报告的数量。
• plan（实施计划；参考 Google 的设计文档，https://www.industrialempathy.com/posts/design-docs-at-google/，Rust RFC 模板，https://github.com/rust-lang/rfcs/blob/master/0000-template.md，以及 Shape Up 的方案说明，https://basecamp.com/shapeup/1.5-chapter-06）：`goal`（目标和非目标）、`current`（当前的工作方式）、`design`（该部分、某个条目或可视内容中要包含真实图表）、`slices`（按顺序排列，每项都包含 size，例如 "S, half a day"）、tests（每个切片对应的测试和证明）、risks（每项风险及回滚方式）、rollout、estimate（时间范围）、owner-calls（用户必须做出的决定）。用户逐节作答的计划仍然使用 post --kind plan；计划报告是供人阅读的。
• decision（决策与建议；参考 Michael Nygard 的架构决策记录，https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions）：`context`（清楚说明各种影响因素）、`options`、`recommendation`、`consequences`（后续影响，包括利弊）。
• audit（参考 Yellow Book 中审计发现的要素：标准、状况、原因和影响，https://www.gao.gov/yellowbook）：`scope`、`standard`（用于核对的规则及其链接）、`findings`（每项说明实际情况、与规则的差异、原因及其代价）、`fixes`（按紧急程度从高到低排列）。
• incident（事件报告与复盘；参考 Google SRE 手册中的无责复盘，https://sre.google/sre-book/postmortem-culture/）：`impact`（影响对象、影响程度和持续时间）、`timeline`（每个事件单独列为一项，并注明时间）、`root-cause`（系统层面的根因，而非个人）、`actions`（为避免问题再次发生而采取的变更）。
• status：done、in-progress、blocked（受阻情况及阻碍原因）、up-next。
• other：没有固定部分；仅在不适用于其他类型时使用。

在每份设计、架构或计划报告中绘制真实图示

计划以及解释设计或架构的报告，至少需要一个真实图示：直接绘制对象本身，作为架构图（展示各部分及其通信关系）或流程图（按顺序展示步骤及其箭头）。条形图、卡片或编号列表都不是图示。其他报告只有在结构、顺序或依赖关系是重点时才添加图示；重点是数字时，保留条形图或卡片。

• 在与计划或报告文件同目录的 .html 页面中绘制内联 <svg>（手动绘制，或使用单独安装的 Archify skill：npx skills add tt-a1i/archify -g，然后运行 ARCHIFY_UPDATE_CHECK_DISABLED=1 archify finalize --quality showcase）。不要使用图示图片、<img> 或从网络加载的页面。
• 在 visual、某个区块或某个条目中添加 "diagram": [{"label": "Flow", "src": "diagrams/flow.html"}]（1 到 3 个视图，以标签页形式显示）；旁边的行仍应以列表形式呈现相同答案。将主要图示放在 visual 中，让它成为读者看到的第一张图。
• 确保图示适合手机阅读：viewBox 宽度为 320 到 340，最多两列，标签长度约不超过 16 个字符，图中文字至少为 12 px，不要图例。宽大的时序图或对比图无法适配：将相同流程改为纵向绘制，并将 Today 和 After 作为两个视图。
• 确保图示在浅色和深色模式下都易于阅读：所有颜色都必须使用 CSS 变量，并添加 @media (prefers-color-scheme: dark) 区块切换颜色（浅色背景上使用深色文字，深色背景上使用浅色文字）。看板会告知页面自身使用浅色还是深色模式，并启用或停用相应规则，因此图示会跟随看板的模式切换。切勿将黑色或白色固定用于图示。
• Post 会拒绝最小文字在宽度为 390 px 的手机上小于 12 px、带有品牌标记（切勿设置 brand）或没有 <svg> 绘图的图示。Post 会固定每个页面（为你写入其 sha256 和 bytes）：发布后更改的页面不会显示，因此更改后必须重新发布计划或报告。
• 在报告中，点按图示可打开全尺寸视图（手机上单独显示）；在计划中，手机会以列的完整宽度显示图示，并提供 Full size；桌面端则会就地打开 Show me。声称已发布之前，请分别在浅色和深色模式下以 390 px 宽度打开图示。

请用户登录

如果工作需要用户登录（例如通过 npm login 提供登录链接），请发布一张登录卡片。它会显示在等待事项的顶部。

1. 发布卡片：npx -y sign-off-axi post --type signin --key <key> --service "<service>" --link <sign-in URL> --unlocks "<what it unlocks>" --waits "<who waits>" --expires 15m。--expires 指链接失效的时间：可以是 ISO 日期时间，也可以是距现在的时间，例如 15m。只能发布 http(s) 链接，切勿发布密码或令牌。
2. 确认登录成功后，关闭卡片：npx -y sign-off-axi signin done --key <key>。wait --key <key> 会在登录完成后返回。
3. 链接过期时，卡片会显示这一情况。获取新链接后，使用相同的 --key 重新发布：卡片会显示新链接并再次进入等待状态。
4. 如果链接很快过期（npm login --auth-type=web 链接大约只能使用 5 分钟），请改为发布 --start '["npm", "login", "--auth-type=web"]'，而不是 --link 和 --expires：每次点按 Open，都会在看板的计算机上运行该命令，并打开命令输出的新链接。命令以退出码 0 结束时，卡片会自动关闭。

设计决策：展示 A/B/C 方案，而非只用文字描述

当用户必须选择某项内容的外观或工作方式时，请按以下步骤操作：

1. 用一行文字说明设计问题。
2. 构建恰好 3 个结构不同的方案：布局、层级或操作方式各不相同。只有颜色不同的方案不算。
3. 将它们放在项目中的 .sign-off/mocks/<key>/ 下（如果缺少 .sign-off/，请运行一次 npx -y sign-off-axi init）：创建 3 个文件（a.html、b.html、c.html，或截图），或创建一个 index.html，通过 ?variant=a、b 或 c 显示对应方案。
4. 用通俗的语言简要说明取舍（不超过 5 行：每个方案的优缺点），并推荐一个方案。
5. 使用 npx -y sign-off-axi post .sign-off/decisions.json --type design --key <key> 将其发布到项目看板；每个方案提供一个 --option 和一个 --mock，并提供 --tradeoff 和 --recommend（请参阅 post --help）。Mock 路径相对于 .sign-off/：单页形式可用 --mock a=mocks/<key>/a.html，或 --mock a=mocks/<key>/index.html?variant=a。如果某个方案也能通过 URL 实时运行，请为其添加 --link a=<http or https URL>（每个方案一个）：卡片会在对应 mock 下方显示一个「打开实时版本」链接，并在新标签页中打开。然后运行 npx -y sign-off-axi open .sign-off/decisions.json，并将 URL 提供给用户。
6. 使用 npx -y sign-off-axi wait .sign-off/decisions.json --key <key> 等待回复。
7. 使用 npx -y sign-off-axi answers .sign-off/decisions.json --key <key> --json 读取回复。用户选择方案时会提供 answer，并可能附带 note，即用户随回复发送的评论；"answer": "text" 表示用户自行填写的回复（「以我的名义发送」或「发送回复」），该回复位于 note 中。rounds 中没有 answer 的条目，或时间晚于 answer 的 at 的条目，表示用户想要新一轮方案：阅读其 note，构建 3 个新方案，并使用新的 key 发布。如果答案或轮次中有 comments 列表，表示用户对 mock 中某些部分的评论：mock 是方案，ref、tag 和 words 用于标识元素，text 是评论；请根据评论修改对应方案。
8. 将胜出的方案实现到正式代码中，然后删除 .sign-off/mocks/<key>/。

请使用快速、低成本的模型构建 mock：mock 是临时产物。如果已安装 first-draft，可以让它构建 mock，并在 --tradeoff 末尾写入 Open in first-draft: <label> <url> 链接；看板会将其显示为可直接访问的链接。

当文字不足以表达时，展示出来

使用能清楚说明事项的最简单视图：纯文本，然后是图表，再然后是交互页面，最后是配有旁白的视频。

• 图表：在 .sign-off/mocks/<key>/ 下绘制 SVG（或保存 PNG），然后使用 --type diagram --view mocks/<key>/flow.svg 发布。
• 交互页面：在 .sign-off/mocks/<key>/ 下编写一个自包含的 .html 文件（CSS 和 JS 均内联，不访问网络），然后使用 --type interactive --view mocks/<key>/demo.html 发布。页面在沙盒中运行：不能调用 fetch、不能访问远程文件，也不能访问仪表板。
• 配有旁白的视频（说明视频）：仅使用免费的本地工具自行制作，绝不要使用付费或在线语音服务：
  1. 使用 ASD-STE100 简明技术英语编写简短脚本：分成 3 到 5 个部分，每部分包含 1 或 2 个简短句子，总时长约 20 到 40 秒。
  2. 为每个部分制作一张静态图（截图或简单幻灯片），所有图的尺寸相同，例如 1280x720 PNG。
  3. 使用免费的本地引擎将每个部分转换为语音，例如 piper（pip install piper-tts）或 espeak-ng：piper -m <voice>.onnx -f 1.wav < 1.txt。
  4. 将每张静态图与对应语音合并，然后合并各部分：ffmpeg -loop 1 -i 1.png -i 1.wav -c:v libx264 -tune stillimage -pix_fmt yuv420p -c:a aac -shortest 1.mp4，然后运行 ffmpeg -f concat -i parts.txt -c copy -movflags +faststart explainer.mp4（parts.txt 中列出 file '1.mp4' 等内容）。
  5. 使用 --type explainer --media explainer.mp4 --about "<one-line summary>" 发布，并为每个部分添加一个 --chapter <m:ss>=<title>（使用 ffprobe -show_entries format=duration 获取每个部分的时长）。视频会在卡片上播放；章节可跳转到对应部分。

所有这些都应像决策一样作答（是/否，或使用你自己的 --option，并通过 --recommend 指出你会选择的选项）；然后以同样的方式等待并阅读回答。

请求

$ARGUMENTS

如果上一行包含问题，则表示用户在调用此技能时附带了该问题——请获取当前 CLI 指南，然后提问。 如果该行为空或只有占位符，则根据对话推断问题。