# Decision Page Skill

> 当存在需要用户人工拍板的决策事项（累计至少 2 项，或用户明确要求决策页）时使用。先充分调研本地事实与可靠来源，给出带证据、收益、代价、不确定性和推荐前提的完整信息，再生成本地交互决策页；通过理解检查确认用户掌握关键取舍后才允许保存。页面提供与当前 CLI 智能体的实时问答、热更新和 decisions-log.md 持久记录，适用于任何能运行 Python 并读取 watch/poll 事件流的智能体。人工决策不得只在聊天里罗列。

- Skill: `w-jming/decision-page-skill` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add w-jming/decision-page-skill`
- Raw SKILL.md: https://api.skillmd.com/api/skills/w-jming/decision-page-skill/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: w-jming (https://skillmd.com/u/w-jming)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/w-jming/decision-page-skill

---


# decision-page-skill · 证据驱动的交互决策页

使用零依赖 Python 服务与单文件 HTML，把“调研 → 理解 → 拍板 → 回填执行”做成可审计的本地流程。服务只绑定 `127.0.0.1`，与具体智能体或 CLI 无关。

## 硬性门槛

1. **先调研，后请求决策。** 不得先让用户在信息不足的空壳选项中选择，再事后补证据。
2. **让页面自洽。** 用户不打开外部文档，也应能理解为何要决策、各方案的收益和代价、推荐成立的前提、尚存的不确定性。
3. **验证理解，不只要求“已阅读”。** 每项至少设置一道针对关键事实或取舍的理解题；答对后才解锁选项。不得把“是否同意推荐方案”当作理解题。
4. **如实标注证据边界。** 区分已验证事实、推断和未知；不得伪造来源或用来源数量替代证据质量。
5. **使用实际 CLI 名称。** 页面名称由运行时自动探测或 `--agent-name` 显式传入；不得在模板中写死某个智能体品牌。

## 工作流

### 1. 完成调研门槛

先收集每项决策真正需要的信息：

- 检查项目中的源码、配置、日志、计划、约束和已有决策，确认实际现状而非只依赖用户的一句话描述。
- 对可能变化、自己不确定或风险较高的事实，查询当前的一手或权威来源；记录可追溯的文件路径、文档章节或 URL，以及核对日期。
- 比较 2–4 个互斥且覆盖合理路径的选项。逐项写明收益、代价或风险、依赖、可逆性以及不适用条件。
- 给出一个明确推荐，同时写清推荐成立的前提；将影响选择但尚未验证的内容列入 `uncertainties`。

仅当用户能从页面回答以下问题时，才算“信息充分”：为什么现在必须决策；每个方案得到什么、牺牲什么；推荐基于哪些约束；什么新事实会改变推荐；仍有哪些未知。如果关键未知足以使比较失真，继续调研或先向用户说明阻塞，不得要求拍板。

### 2. 放置模板

把 `templates/decide.py` 与 `templates/decisions.html` 复制到项目内同一目录：

- Git 仓库：优先放在 `docs/decisions/` 或项目既有治理目录，并遵守分支、评审和提交规范。
- 非仓库场景：放在任务工作目录。

数据文件默认与脚本同目录，也可统一用 `--dir <数据目录>` 指定。

### 3. 生成并校验 decisions.json

使用 v2 数据契约。下面是一项决策的最小结构；需要完整范例时读取 `examples/demo/decisions.json`：

```json
{
  "schemaVersion": 2,
  "title": "项目名",
  "subtitle": "本批决策的共同背景",
  "decisions": [
    {
      "id": "D1",
      "title": "一句话标题",
      "doc": "相关本地文档（可选）",
      "background": "现状、约束与为什么现在需要决策。",
      "research": {
        "summary": "调研后的综合判断。",
        "checkedAt": "YYYY-MM-DD",
        "evidence": [
          {
            "finding": "已验证的结论",
            "impact": "它如何影响本次选择",
            "source": "本地路径、文档章节或 URL"
          }
        ],
        "uncertainties": ["仍未验证但可能改变选择的事项"]
      },
      "recommendationReason": "推荐方案、成立前提，以及何时应改选。",
      "allowCustom": true,
      "options": [
        {
          "key": "A",
          "label": "方案 A",
          "desc": "一句话定位",
          "benefits": ["主要收益"],
          "costs": ["主要代价或风险"],
          "recommended": true
        },
        {
          "key": "B",
          "label": "方案 B",
          "desc": "一句话定位",
          "benefits": ["主要收益"],
          "costs": ["主要代价或风险"]
        }
      ],
      "understandingChecks": [
        {
          "id": "U1",
          "question": "哪项事实最可能改变当前推荐？",
          "options": [
            {"key": "A", "label": "事实 A"},
            {"key": "B", "label": "事实 B"}
          ],
          "answer": "B",
          "explanation": "解释关键取舍；答错时帮助用户重新理解，而不是只判错。"
        }
      ],
      "status": "open"
    }
  ]
}
```

保持以下质量要求：

- 每项恰好一个 `recommended: true`，并用 `recommendationReason` 说明理由和前提。
- `evidence` 每条同时包含结论、决策影响和来源；`checkedAt` 反映本次实际核对日期。
- `uncertainties` 可以为空，但只能在认真检查后留空；不得用空数组隐藏未知。
- 理解题检查关键事实、风险或推荐前提，答案必须能从页面调研信息中推出。高风险、难逆转或信息密集的决策应设置多道题。
- 选项应互斥并覆盖合理路径；自定义选项不等于可以省略明显方案。

生成后必须先运行：

```bash
python3 <目录>/decide.py validate --dir <数据目录>
```

校验不通过时修复所有问题，不得把未通过的页面交给用户。

### 4. 启动并核对运行时身份

在后台启动服务：

```bash
python3 <目录>/decide.py --dir <数据目录>
# 可选：--port N、--no-browser、--idle-timeout N
```

服务会从父进程和环境变量探测当前 CLI，并打印 `当前 CLI：<名称>`。发送页面地址前核对该名称；若探测错误或回退为“智能体”，使用实际 CLI 的显示名称重启：

```bash
python3 <目录>/decide.py --dir <数据目录> --agent-name "<当前 CLI 名称>"
# 也可设置 DECISION_PAGE_AGENT_NAME
```

不要把示例中的某个品牌复制为默认值。页面从 `/api/state.runtime.agentName` 读取名称并同步更新标题、聊天状态和通知文案。

服务默认打开 `http://127.0.0.1:8765`。它只监听本机；不要改为 `0.0.0.0`。默认在页面关闭且无请求 3600 秒后退出，`--idle-timeout 0` 可关闭自动退出。

### 5. 值守提问与保存事件

使用当前 CLI 可用的后台或流式执行能力运行：

```bash
python3 <目录>/decide.py watch --dir <数据目录>
```

如不便常驻，则在继续工作的间隙周期调用：

```bash
python3 <目录>/decide.py poll --dir <数据目录>
```

事件格式为 `QUESTION #<id>: ...` 或 `SAVED: ...`，游标保存在数据目录的 `.decide-watch.json`，默认只消费新增事件。

收到 `QUESTION` 后：

1. 读取 `chat.jsonl` 获取完整上下文。
2. 先回答已有证据能支持的部分；若问题暴露信息缺口，继续调研，不得凭印象补全。
3. 如证据、推荐、选项或理解题发生变化，编辑 `decisions.json` 并重新运行 `validate`。页面会热更新并清除旧版本的选择和理解状态；已经保存的旧结论也会标为失效并要求重新确认。
4. 用 stdin 方式回复，避免 shell 引号问题：

```bash
python3 <目录>/decide.py reply - --dir <数据目录> <<'EOF'
回答内容；支持 **加粗**、`代码`、列表和代码块。
EOF
```

回复要及时、具体，并说明新增证据是否改变推荐。不得为了让用户尽快选择而弱化风险或未知。

收到 `SAVED` 后进入下一步。服务端会再次校验资料版本、选项和理解答案，不信任浏览器传来的展示文本；过期资料无法保存。

### 6. 回填并执行

1. 读取 `decisions-log.md` 最新的 `<!-- 待智能体回填 -->` 条目。
2. 核对其中的选择、调研日期、资料版本和理解确认记录。
3. 将结论回填到项目的决策表、计划或待办，解锁对应工作。
4. 把注释原地改为 `已回填（日期）`，再按结论执行。

`watch`/`poll` 只按新增 `## ` 日志条目触发；原地修改回填标记不会重放历史。

### 7. 收尾

决策完成后停止 `watch` 或轮询，结束后台 `decide.py` 服务，并确认所有日志条目已回填。保留 `decisions.json` 的 `status: "decided"` 与 `result`；后续更新文件时不得覆盖已有结果。

## 文件契约与注意事项

| 文件 | 写入方 | 作用 |
|---|---|---|
| `decisions.json` | 当前智能体 | 调研、选项、理解题与决策状态；修改即热更新 |
| `chat.jsonl` | 页面写 user；`reply` 写 assistant | 浏览器与值守会话的消息通道；不要手工伪造 user 行 |
| `decisions-log.md` | 页面保存接口追加 | 跨会话持久契约，应纳入项目治理记录 |

- 所有子命令都接受 `--dir <数据目录>`，服务、值守、回复和校验必须指向同一目录。
- 页面不能通过 `file://` 直接使用，必须由 `decide.py` 提供服务。
- 决策资料变更会产生新版本摘要；浏览器会清除旧理解状态、使基于旧资料的已保存结论失效，服务端也会拒绝旧版本提交。
- 简单单项、低风险二选一可直接对话确认；一旦累计多项或需要背景比较，必须使用本技能的页面和调研门槛。