docs/plans/2026-06-16-optimization-program.md

# Gaokao Volunteer System 优化计划（2026-06-16）

> **For Hermes:** Use `subagent-driven-development` to execute this plan by workstream. 先审计/设计，再实现，再验证，再文档收口。

**Goal:** 在不扩大范围失控的前提下，把志愿服务项目补齐到“规则可信、专业数据可信、CLI 可调度、规划与实现一致”的下一阶段可执行状态。

**Architecture:** 把任务拆成 4 条主线：规则规范、专业目录数据、CLI 能力层、规划/实现优化。每条主线先做现状审计与真相源整理，再进入实现。跨主线共享单一真相源，避免文档漂移和数据口径冲突。

**Tech Stack:** Python/FastAPI/SQLite/Hermes skills & CLI/静态 HTML portal/测试与文档体系。

---

## 一、总原则

1. **先审计后实现**：先确认当前已有能力、缺口、权威数据源、更新频率。
2. **权威源优先**：省级考试院/教育考试院、教育部/阳光高考/本科专业目录等官方或准官方源优先。
3. **数据与规则分层**：
   - 规则规范 = 可验证约束
   - 专业目录 = 事实数据集
   - CLI = 调度入口
   - 规划/实现优化 = 架构与流程治理
4. **每条主线都要可回归验证**：不是“收集一份材料”就算完成。
5. **先做最小闭环，再扩面**：先覆盖 2026 版核心省份 + 国家级专业目录，再考虑全面扩省与增量同步。

---

## 二、四条主线与验收目标

### Workstream A：2026 志愿规范/审计能力

**目标**

- 明确“全国通用规范 + 各省 2026 规则差异”能否被系统读取、验证、审计。
- 输出一套可由智能体/CLI 调用的规则审计能力。

**要回答的问题**

1. 当前仓库已有多少省份规则？哪些是 2026 版，哪些只是历史迁移？
2. 是否已有“全国通用规范”抽象层？
3. 是否已有可供程序调用的统一审计入口？
4. 哪些省份缺 2026 规则或规则证据链不完整？

**交付物**

- `docs/CURRENT_RULES_STATE_2026-06-16.md`
- `docs/RULES_SOURCE_OF_TRUTH.md`
- `docs/plans/rules-2026-gap-remediation.md`
- 规则能力清单（支持省份 / 不支持省份 / 证据来源 / 更新时间）
- 一个统一 CLI 入口（若现有 `gaokao-checker` 不足则补强）

**验收标准**

- 能列出各省 2026 规则覆盖矩阵
- 能对至少 1 份方案执行真实审计并输出结构化结果
- 明确“全国通用规则”和“省级差异规则”的边界

---

### Workstream B：2026 官方专业目录与近两年专业增减

**目标**

- 建立 2026 官方专业目录的真相源
- 补齐近两年高校/国家层面的新增、取消、停招、调整风险
- 防止系统输出过时或错误专业

**要回答的问题**

1. 当前项目里专业数据来自哪里？是否可追溯？
2. 能否拿到教育部/阳光高考/高校官方的专业目录与变更信息？
3. 数据粒度是“本科专业目录”还是“高校招生专业”级别？
4. 现有推荐/校验链路哪里在消费专业名称？是否会因过时专业导致错误建议？

**交付物**

- `docs/MAJOR_DATA_SOURCE_OF_TRUTH.md`
- `docs/MAJOR_DATA_RISK_MATRIX_2026.md`
- `docs/plans/major-catalog-2026-ingestion.md`
- 专业数据结构定义（目录字段、来源字段、版本字段、变更标签）
- 增量更新策略（年度全量 + 月度差异/人工校验）

**验收标准**

- 能说清当前专业库是否可信
- 至少形成一套 2026 目录接入方案
- 明确“国家目录”与“学校招生专业”两个层次的映射/差异

---

### Workstream C：系统 CLI 能力层（供智能体/运营/客服调用）

**目标**

- 给 Hermes/运营/客服智能体提供稳定 CLI 入口，能创建订单、查询订单、触发服务流程、调用审计/方案能力。

**要回答的问题**

1. 当前已有 CLI 有哪些？哪些只是脚本，哪些具备稳定契约？
2. 运营/客服最小需要哪些命令？
3. CLI 是直连本地代码、直连 DB，还是走 HTTP API？
4. 需要多大权限边界与日志审计？

**建议最小 CLI 范围**

- `create-order`
- `get-order`
- `list-orders`
- `submit-intake` / `update-order-status`
- `run-audit`
- `generate-plan` / `render-report`
- `doctor-payment-provider`

**交付物**

- `docs/CLI_CAPABILITY_PLAN.md`
- `docs/CLI_API_MAPPING.md`
- `docs/plans/agent-cli-surface.md`
- CLI 契约清单（输入/输出/错误码/审计日志）

**验收标准**

- 至少形成一套统一命令面设计
- 明确每个命令是包裹现有脚本还是新增正式入口
- 明确哪些命令给客服，哪些只给运营/管理员

---

### Workstream D：项目规划设计与实现优化

**目标**

- 统一产品规划、规则能力、专业数据、支付/交付、后台/CLI 的真相源，减少“能跑但不可持续”的实现漂移。

**要回答的问题**

1. 当前 PRD / 技术设计 / 实现 / 报告之间有哪些漂移？
2. 现有模块边界是否清楚？
3. 哪些是历史遗留脚本，哪些应提升为正式能力层？
4. 哪些风险会阻碍下一阶段（数据可信、客服协作、支付上线、运营交付）？

**交付物**

- `docs/CURRENT_STATE.md` 更新
- `docs/ARCHITECTURE_OPTIMIZATION_BOARD_2026-06-16.md`
- `docs/ROADMAP_ALIGNMENT_2026-06-16.md`
- 分阶段执行板（P0/P1/P2）

**验收标准**

- 明确当前架构哪些该保留、哪些该收敛
- 明确下一阶段优先级排序
- 文档真相源一致，不再让历史报告互相打架

---

## 三、执行顺序（建议）

### Phase 1：审计与真相源整理（先做）

1. A1 规则覆盖现状审计
2. B1 专业数据来源审计
3. C1 CLI 现状审计
4. D1 规划/实现漂移审计

### Phase 2：方案设计（基于审计结果）

5. A2 规则模型与统一审计入口设计
6. B2 专业目录数据模型与更新策略设计
7. C2 CLI 能力面设计
8. D2 总体架构/路线图对齐

### Phase 3：实现（按依赖顺序）

9. A3 规则审计能力补强
10. B3 专业目录数据接入/清洗/版本化
11. C3 CLI 实现与最小命令闭环
12. D3 文档/执行板/真相源收敛

### Phase 4：验证与交付

13. 规则审计真实案例验证
14. 专业目录抽样对账验证
15. CLI 端到端命令验证
16. 最终文档与执行板收口

---

## 四、子智能体分工建议

### 子智能体 A（规则与审计）

**职责**

- 审计各省规则与全国规则现状
- 盘点 2026 规则覆盖矩阵
- 提出统一审计入口设计

**输入**

- `rules/`
- `skills/gaokao-spec-checker/`
- `scripts/gaokao-checker`
- 相关 docs/plans

**输出**

- 规则覆盖矩阵
- 缺口报告
- 规则审计补强计划

---

### 子智能体 B（专业目录与数据真相）

**职责**

- 审计当前专业数据来源
- 设计 2026 官方专业目录接入方案
- 识别近两年专业增减风险点

**输入**

- `data/`
- `scripts/`
- 相关推荐/校验逻辑
- 官方数据源调研任务

**输出**

- 专业目录真相源文档
- 数据模型与更新方案
- 风险矩阵

---

### 子智能体 C（CLI 与智能体调用面）

**职责**

- 盘点现有脚本与 API
- 设计统一 CLI 面
- 定义智能体/运营/客服最小命令集

**输入**

- `scripts/`
- `admin/`
- `README.md`
- 现有订单/支付/交付入口

**输出**

- CLI 能力清单
- 命令契约
- 实现计划

---

### 子智能体 D（规划/架构/真相源收敛）

**职责**

- 对齐 PRD、ROADMAP、CURRENT_STATE、实现现状
- 输出架构优化与执行优先级

**输入**

- `product/`
- `docs/`
- `reports/`
- 当前代码结构

**输出**

- 当前状态与架构优化板
- 下一阶段 roadmap
- 统一真相源索引

---

## 五、主代理协调规则

1. 主代理先看 4 个子智能体的审计结论，不直接开始大规模实现。
2. 对冲突点做一次真相归并：
   - 规则口径
   - 专业数据口径
   - CLI 调用口径
   - 产品/实现边界
3. 再决定 Phase 2/3 的具体实现顺序。
4. 若你确认执行，默认采用：
   - **先并行审计（A/B/C/D）**
   - **后统一收敛**
   - **再分批实现**

---

## 六、建议的第一批并行任务

### Batch 1（并行，纯审计）

- A：规则规范覆盖审计
- B：专业目录数据源审计
- C：CLI 能力面审计
- D：规划/实现漂移审计

### Batch 2（主代理收敛后）

- 形成单一执行板
- 给出实现优先级
- 选择先落地的 1~2 条主线

---

## 七、当前建议

**不要四条线一起直接开工实现。**
最优顺序是：

1. 先让 4 个子智能体并行做“审计与设计输入”
2. 我汇总成单一执行板
3. 你确认优先级后，再进入实现

这样能避免：

- 规则和专业数据口径冲突
- CLI 做出来后又被架构推翻
- 产品规划和实现再次漂移