cms-bp-monthly-report-reviser

SKILL.md

---
name: cms-bp-monthly-report-reviser
description: BP月报修订工具。用于初始化本地或远端 BP 自查月报、按章节边界生成精确修订、执行确认后的安全写入、修改灯色、追加证据、解释口径等，最终提交到工作协同形成新的汇报版本。
---

# BP 月报修订器

本 skill 的唯一主流程是：在 `bp/report-reviser/{reportMonth}-月报-{reportRecordId}/` 生成干净 Markdown，AI 只按章节规则提出修改方案，用户确认后由脚本精确写入。不要把 `report_parts/` 作为最终拆分结果或前端正文来源。

## 核心边界

- **月份目录是唯一正文来源**：前端会读取所有非 JSON 文件，所以最终可见 Markdown 只能放在 `bp/report-reviser/{reportMonth}-月报-{reportRecordId}/` 下。
- **目录月份必须标准化**：`reportMonth` 必须使用 `YYYY-MM`，例如 `2026-05-月报-2058815281387614209`；不要使用 `2026年5月-月报-...` 作为正式工作目录。
- **默认不写文件**：用户只提出修改意图时，只输出修改方案；只有明确确认后才调用脚本写入。
- **普通正文修订只用精确替换**：使用 `apply_chapter_patch`，必须提供 `targetFile + locator.originalText`，禁止整章重写或模糊替换。
- **专门动作不能混进正文 patch**：灯色走 `update_lamp_color`；证据追加走 `add_evidence_ref`；普通正文替换不得直接改灯色、证据编号、汇报链接或系统事实。
- **派生区可受控补正**：`1.2`、`2.1`、`3.1` 优先由脚本联动更新；若脚本漏同步且用户明确要求补正，可以按当前统计句或 Markdown 表格格式精确替换，并在 `reason`、`factBasis` 写清依据。
- **灯色修改只能由用户明确发起**：不要主动问用户“要不要改灯色”“想改成什么灯色”。用户没有明确提出改灯色和目标灯色时，只能解释现状、说明边界或建议补充事实。
- **改绿必须有依据**：任何目标 / KR / 举措改成绿灯前，必须由用户明确发起，并提供文字说明、证据或相关上传汇报；不能无依据直接改绿。
- **改灯必须写入修改原因**：调用 `update_lamp_color` 必须提供 `--reason`，脚本会把本次修改原因写入目标明细正文的“判断理由”或“结论一句话”中，例如 `（修改原因：用户确认因 Rxxxx 证据证明已完成）`。
- **灯色争议要留痕**：如果 AI 判断补充证据与指标无关联、不建议改灯，但员工仍主张改灯，不要覆盖系统灯色；应走 `update_manual_judgment` 记录双方意见，例如 `AI判断：...；员工主张：...；确认提醒：...`。
- **第 2 章事实项硬锁定**：目标编号/名称、KR 编号/名称/衡量标准、举措编号/名称、证据编号/链接、计划期系统判断不能直接改。
- **第 6/7 章完全不可改**；第 8 章只允许脚本追加证据。
- **ID 全程字符串**：禁止对 reportId、taskId、huibao id 等做数值转换。

## 按需读取

不要启动时加载所有 reference。按任务读取：

| 场景 | 必读文件 |
|------|----------|
| 判断章节能否修改 | `references/rules/editable-boundary-rules.md` |
| 定位具体章节规则 | `references/rules/chapter-detail-rules.md` |
| 所有普通章节修订 | `references/rules/common-rules.md` 和对应 `references/rules/chapters/*.md` |
| 修订第 2.2 目标明细 | `references/rules/chapters/02-goal-detail.md` |
| 填写或修改人工判断 | `references/rules/chapters/02-manual-judgment.md` |
| 解释灯色、灯色争议、改灯 | `references/rules/chapters/02-lamp-rules.md` |
| 生成普通正文 patch | `references/rules/patch-rules.md` 和 `references/templates/chapter_patch_schema.json` |
| 写入失败或校验争议 | `references/rules/validation-rules.md` |
| 初始化、灯色、证据、交付命令 | `references/workflows.md` |
| 维护历史 `report_parts` 流程 | `references/legacy-report-parts.md` |

## 主流程

### 1. 初始化

本地 Markdown 报告：

- 执行以下脚本 若未安装 `requests`，**必须先安装**，再运行脚本：
- **禁止**在未实际运行脚本的情况下，根据代码或经验「模拟/推断/口述」脚本输出。

```bash
python3 scripts/monthly_report_reviser.py prepare_revision_workspace --report_id {reportId}
```

在 sandbox exec / tool runner 中执行远端初始化时，`BP_OPEN_API_APP_KEY` 必须通过执行工具的 `env` 参数传入，禁止写成 `export ... && python3 ...` 或 `BP_OPEN_API_APP_KEY=... python3 ...` 这类 shell 前缀。

```json
{
  "command": "python3 scripts/monthly_report_reviser.py prepare_revision_workspace --report_id {reportId}",
  "env": {
    "BP_OPEN_API_APP_KEY": "{个人AppKey（用于访问业务接口）}"
  }
}
```

初始化完成后，只向用户展示 `bp/report-reviser/{reportMonth}-月报-{reportRecordId}/`。如果出现 `report_parts/`，那是内部或 legacy 过程，不是最终拆分结果。

### 2. 定位和判断

根据用户意图定位 `bp/report-reviser/{reportMonth}-月报-{reportRecordId}/` 下的 Markdown 文件：

1. 章节编号/章节名精确匹配
2. 目标编号/目标名称匹配
3. 全文关键词搜索

然后读取相关章节规则，判断能否改：

- 可普通修订：提出具体替换方案和目标文件。
- 需要原因：先追问原因，并在修改内容中保留原因表达。
- 禁止直接改：说明边界，并改用专门动作或人工判断。

### 3. 用户确认前只给方案

确认表达包括：`确认写入`、`可以，写进去`、`就这样改`、`帮我保存`、`按这个改`。

确认前输出类似：

```text
我会修改：
2_目标自查明细/2.2_目标明细/02_🟡 XXX.md

修改点：
1. ...
2. ...

请确认是否写入。
```

### 4. 确认后写入

普通正文修订：

```bash
python3 scripts/monthly_report_reviser.py apply_chapter_patch \
  --report_id {reportId} \
  --patch_file {patch_path}
```

灯色修改：

```bash
python3 scripts/monthly_report_reviser.py update_lamp_color \
  --report_id {reportId} \
  --code P4939-9.1 \
  --new_lamp yellow \
  --reason "用户确认后的灯色判断依据；涉及证据 Rxxxx"
```

追加证据：

```bash
python3 scripts/monthly_report_reviser.py add_evidence_ref \
  --report_id {reportId} \
  --evidence_file {evidence_json_path}
```

脚本成功后会刷新 `report_manifest.json`、`chapter_revision_manifest.json`，并追加 `revision_history.jsonl`。

## 灯色规则摘要

- 普通正文 patch 必须拦截任何灯色 emoji、灯色文字、灯色样式变化。
- 不主动追问用户要改成什么灯色；灯色修改必须由用户明确发起并给出目标灯色。
- 改成绿灯必须有用户确认后的文字说明、证据或相关上传汇报；不强制要求用户提供 R/RP 编号或汇报 ID。
- 每次改灯必须把修改原因写回正文判断理由。
- KR 灯色不按举措灯机械聚合；必须根据衡量标准、当前结果、用户补充、下级举措实际完成情况和证据判断。
- 举措灯色只更新对应举措，并提示上层 KR/目标可能需要重新评估。
- 目标灯色按当前 KR 灯色聚合；合法变更后联动目标明细正文、`2.1` 总览和 `1.2` 灯色分布。目标文件名来自 Markdown 标题，不包含灯色。
- 普通 `2.2` 正文修订不会自动同步 `2.1`、第 3 章、第 1 章或报告头；如需同步，必须单独提出并确认对应章节修改。

## 证据规则摘要

- 禁止手工编造 R/RP 编号或 `huibao://` 链接。
- 新增证据可以来自用户上传、系统解析出的汇报 ID/正文或用户补充说明；`reportId` 和 `relatedCodes` 不再强制必填。
- 用户通过云端小助手上传关联汇报时，后台会把汇报 ID 和汇报正文解析进 message；AI 必须优先从 message 中提取，不要追问用户汇报编号或 ID。
- 拿到汇报 ID 后，AI 可自行生成证据编号，并按固定格式组装链接：`huibao://view?id={汇报ID}`。
- `add_evidence_ref` 只追加第 8 章证据索引；正文中引用新证据前，必须先完成证据追加。

## 交付

交付给用户或前端时，只交付 `bp/report-reviser/{reportMonth}-月报-{reportRecordId}/`：

- Markdown 是正文。
- JSON 是索引/校验/历史。
- 不读取、不展示、不依赖 `report_parts/`、`assembled_report.md`、`export_report.md`、`preview.md`。

更多命令细节见 `references/workflows.md`。