Decision Board 是一个帮助用户在多个可比选项之间一次性并排挑选的交互式看板技能。它从 JSON 规格渲染出单文件 HTML 看板，等待用户选择，读取结果，然后由智能体根据选择执行后续动作（写文档、提交 PR、更新配置等）。
用途与定位
该技能只处理“挑选”这一步。从材料中抽取决策并判断权衡发生在之前，应用选择发生在之后。触发条件是结构匹配，而不是领域或数量。
使用条件（按重要性排序）
- 各选项形状一致：每一项都是在共享字段（label、可选 cost / preview）之上的 N 选一。如果每项都需要自定义形状，用文字更好。
- 预览值得一看：用户能从并排查看各选项预览中获益，而非阅读文字。如果一句话就能说清选择，内联问答更快。
- 单人、一次完成：用于个人决策，而非异步评审。
- 项数是zui弱的信号：约 5–30 是典型区间，但结构良好的 4 项仍可用看板，而 10 项互不相关的杂问则不合适。匹配度优先于数量。
如果结构不匹配，应指出并建议改用其他格式。
工作流程
该技能分五步处理一次会话。步骤 1、2、4、5 由智能体负责，步骤 3 由用户负责。
- 从用户材料中抽取决策
用户通常带着非结构化材料而来——会议纪要、含矛盾段落的审计文档、聊天记录、脑中列表。把每个决策作为一个单元抽出，含四部分：
- 正在决定什么（一行标题）。
- 当前状态或冲突——实际代码、引用的段落、现有行为。这成为决策的 context。
- 候选选项——至少两个，各有短标签以及被选中后会发生的改变。这成为 options[].label + options[].preview。
- 智能体的推荐及理由——若智能体有意见，标记某个选项为 recommended，并将理由写入 rationale。
仅当用户已带来结构化的决策与选项列表时，才跳过此步。
- 构建规格
将抽取的决策转换为 spec.json。完整 schema、字段语义、markdown 语法及三个端到端示例（工程 ADR、文案审计、运维分诊）见 references/spec-format.md。
最小形态（其余均可选）：
{ "title": "ADR-2026-05", "decisions": [ { "id": "auth-storage", "title": "Where do we store the session?", "context": "Today we keep the token in localStorage…", "options": [ {"key": "a", "label": "httpOnly cookie", "preview": "…"}, {"key": "b", "label": "Keep localStorage", "preview": "…"} ], "recommended": "a", "rationale": "Cuts XSS exposure" } ] }
两条长度指引决定用户能否真正做出选择：
- context 是用户的决策背景，不只是“出错的地方”。目标约 5–15 行 markdown，含当前行为、矛盾文档或代码、受影响者、哪条假设不成立。仅两行引用会让用户无从选择。
- options[].preview 是用户的决策证据，不只是标签。目标约 5–15 行 markdown——diff、结果代码、完整政策文本、发生变化的调用点。如果两个选项的预览一眼看去读法相同，用户就无法仅凭预览选择。
渲染前先把规格展示给用户并获得批准。渲染出错需重载页面并清理 localStorage；批准出错只是一条聊天消息。
- 运行 serve.py 并等待用户
该命令会阻塞，直到用户提交或取消——这是预期的调用方式。进程的退出码是回传给智能体的信号，而不是用户消息。
python "${CLAUDE_SKILL_DIR}/scripts/serve.py" path/to/spec.json --output result.json
用宿主支持的长时命令模式调用该脚本——后台进程加完成通知，或带充足超时的阻塞式子进程调用。不要问用户“完成后告诉我”；进程退出就是信号。进程退出后，按退出码分支（见下方 Result schema），仅在退出码为 0 时才读取 result.json。
serve.py 默认绑定 7117 端口，并会向占用该端口的现有进程发送 SIGTERM。用 --port N 覆盖。
stdout 前两行可机器解析：
RESULT_PATH=/abs/path/to/spec.20260511-093000.result.json PORT=7117
当请求端口被占用而回退到操作系统分配的端口时，PORT 行很重要——若需向用户展示看板 URL，请捕获它。捕获两者，然后等待进程退出。退出码告知智能体会话如何结束：
退出码 / 含义 / result.json / 智能体应做什么
- 0 / 点击了 Submit / 已写入 / 读取结果，应用选择
- 1 / spec 无效 / 未写入 / 修复 spec，重试
- 124 / 心跳超时（浏览器离开约 60 秒以上）/ 未写入 / 告知用户失去联系；提议重试
- 125 / 用户点击 Cancel（或 ESC）/ 未写入 / 用户拒绝——不要反驳，询问是否想换一种方式
- 130 / 用户在终端按 Ctrl+C / 未写入 / 视同 125（明确中止）
智能体契约：只有 0 才是“我们拿到了选择”的结果。其他任何情况都意味着没有结果文件，智能体应向用户解释发生了什么。
两个值得了解的标志（其余用 --help）：
- --output PATH — 固定结果路径。默认带时间戳，避免重复运行覆盖。
- --static PATH — 写出独立 HTML 文件并退出，而非提供服务。用于离线分享/归档；静态文件没有 Submit 按钮。
- 按退出码分支
进程退出时，退出码告知智能体走哪条路径。上方汇总表即为契约；各退出码的完整推理（含部分提交处理与 hold 语义）见 references/result-handling.md。
四条适用于所有退出码的规则：
- 仅在退出码为 0 时读取 result.json。对于 124 / 125 / 130，文件不存在。
- 不要臆造选择。若用户取消或断开，智能体应确认并询问下一步——不得静默默认到推荐选项。
- 不要问用户“你完成了吗？”退出码即信号。
- 退出码分支优先于周边默认。退出码 0 且有明确选择即为用户确认——无需额外询问“是否继续”即可应用。退出码 124 / 125 / 130 及 null 选择永不被 recommended 或任何其他回退替换。
- 应用选择
对于退出码 0，读取 result.json 并逐项决策执行。其形态：
{ "title": "ADR-2026-05", "submitted_at": "2026-05-12T09:30:00Z", "decisions": { "<decision-id>": { "choice": "a", "hold": false, "note": "" } } }
当用户提交但未选择时，choice 为 null；hold 标记后续项；note 为纯文本。完整语义（部分提交、hold 工作流）见 references/result-handling.md。
该技能本身从不编辑用户仓库——应用选择是智能体的职责。按领域举例：
- 工程决策 → 打开 PR、编辑配置、运行迁移、更新依赖。
- 文案/设计审计 → 将改动写入相关文件、起草评审评论、提交 issue。
- 运营/流程 → 撰写复盘邮件、提交后续工单、安排延期项、更新规划文档。
- hold 选择 → 作为后续项呈现（不静默），例如加入 TODO 文件或开跟踪 issue。
- null 选择 → 呈现给用户；不得视为默认。询问是延期、重跑看板，还是保持未决。
模式
- 非结构化输入：抽取决策、起草 spec、获批准，然后渲染。不要先渲染再指望。
- 稍后添加决策：用户编辑 spec.json 并刷新标签页。localStorage 以 spec 标题 + 决策 id 为键，因此添加/删除/重命名决策会使键失效并重新开始。重命名选项键也会在恢复时被捕获，并重置该决策的选择（存储值不再是有效选项）。
- 超过 15 个决策：添加 categories 数组。过滤栏会自动出现。
不适用范围
- 每决策单选：无多选、无加权选择。若用户需选两个选项或分配权重，请用调查工具——该技能建模的是“N 选一”。
- 多用户同步/异步协作：单一 localStorage、单一 Submit、无在线状态。
- 持久化服务器状态：全部客户端；服务器在 Submit 后退出。
- 决策依赖（若 A 则 B）：每个决策独立选择。将依赖关系展示在汇总文本中。
- 富文本备注：评论字段为纯文本。
- 程序化应用：智能体读取结果并执行——看板从不编辑用户仓库。
若用户要求上述任一，建议改用其他工具。该技能是单会话挑选通道，不是协作基础设施。