niuniu/gaokao-volunteer-system
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(planning): add 2026-06-16 realignment audit and rule/cli/major design
Some checks failed
CI / pytest (Python 3.10) (push) Has been cancelled
Details
CI / pytest (Python 3.11) (push) Has been cancelled
Details
CI / pytest (Python 3.12) (push) Has been cancelled
Details

Browse Source
This commit is contained in:
Hermes Agent
2026-06-16 17:35:09 +08:00
parent a86bd08281
commit 78a9cb6fd9
6 changed files with 1531 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files

132
docs/CLI_API_MAPPING.md Normal file
View File

@@ -0,0 +1,132 @@
# CLI_API_MAPPING
最后更新: 2026-06-16
真相源: 本文件是"CLI / HTTP / Skill / 内部 import"四层调用关系的入口索引。
设计上下文: `docs/DESIGN_RULES_TRUSTED_CLI_2026-06-16.md` §5-§7
---
## 1. 四层关系
```
┌──────────────────────────────────────────────────────────────┐
│ 入口层 │
│ - gaokao-cli (CLI) │
│ - admin FastAPI (HTTP) │
│ - Hermes skill tool (Agent) │
│ - 旧 scripts/* (compatibility, 3-6 个月内 alias) │
└────────────────┬─────────────────────────────────────────────┘
▼
┌──────────────────────────────────────────────────────────────┐
│ Transport 层 (gaokato/transport/) │
│ - cli.py — argparse/typer 入口 │
│ - http_client — admin 内部调用封装 │
│ - skill_adapter — 给 hermes skill 用的稳定接口 │
└────────────────┬─────────────────────────────────────────────┘
▼
┌──────────────────────────────────────────────────────────────┐
│ Application Services 层 (gaokato/services/) │
│ - audit.py, order.py, plan.py, report.py, │
│ payment.py, majors.py, rules.py, delivery.py │
└────────────────┬─────────────────────────────────────────────┘
▼
┌──────────────────────────────────────────────────────────────┐
│ Domain 层(现有 data/ 域) │
│ data/rules, data/orders, data/payments, data/majors_catalog,│
│ data/crowd_db, data/notifications │
└──────────────────────────────────────────────────────────────┘
```
---
## 2. CLI 入口对照
| 旧入口 | 新 CLI 子命令 | 服务层 |
| ------------------------------------- | ---------------------------------------- | --------------------------- |
| `scripts/gaokao-checker` | `gaokao-cli audit run` | `gaokato.services.audit` |
| `scripts/gaokao-audit` | `gaokao-cli audit run` | 同上 |
| `scripts/gaokao-order-manager` | `gaokao-cli order {create,get,list,...}` | `gaokato.services.order` |
| `scripts/gaokao-shortlink` | `gaokao-cli share` (TBD) | (新增) |
| `scripts/gaokao-data-trace` | `gaokao-cli majors list-changes` | `gaokato.services.majors` |
| `scripts/gaokao-channel-fallback` | `gaokao-cli channel fallback` | (新增) |
| `scripts/gaokao-delivery-dispatch.py` | `gaokao-cli delivery dispatch` | `gaokato.services.delivery` |
| `scripts/gaokao-delivery-watchdog.py` | `gaokao-cli delivery watchdog` | 同上 |
| `scripts/gaokao-retention-cleanup.py` | `gaokao-cli retention cleanup` | (新增) |
| `scripts/payment_provider_doctor.py` | `gaokao-cli payment doctor` | `gaokato.services.payment` |
| `scripts/backup_snapshot.sh` | `gaokao-cli backup snapshot` | (新增) |
| `scripts/backup_verify.sh` | `gaokao-cli backup verify` | (新增) |
---
## 3. HTTP / admin 路由对照
| 现有 admin 路由 | 服务层 |
| ---------------------------------------------- | ---------------------------------------- |
| `admin/routes/orders.py` | `gaokato.services.order.*` |
| `admin/routes/cases.py` | `gaokato.services.case.*` (待抽) |
| `admin/routes/users.py` | `gaokato.services.user.*` (待抽) |
| `admin/routes/stats.py` | `gaokato.services.stats.*` (待抽) |
| `admin/routes/notifications.py` | `gaokato.services.notification.*` (待抽) |
| `admin/routes/payments.py` (隐含在 web_public) | `gaokato.services.payment.*` |
| `admin/routes/web_public.py` | 直接调 `gaokato.services.*` |
---
## 4. Hermes skill 调用对照
| Skill | 改前 | 改后 |
| ------------------------ | -------------------------------------------------- | ------------------------------------------------------------------ |
| `gaokao-counselor-long` | `import skills.gaokao-audit.scripts.audit_service` | `from gaokato.services import audit` 或 `gaokao-cli audit run ...` |
| `gaokao-audit` | 自包含脚本 | 调 `gaokato.services.audit.audit_plan` |
| `gaokao-spec-checker` | 自包含 regex | 调 `gaokato.services.audit` 薄 wrapper |
| `gaokao-college-advisor` | prompt 内部 | 调 `gaokato.services.plan.generate` |
| `zhangxuefeng-skillset` | prompt 内部 | 不变(只借用表达风格) |
---
## 5. 退出码与输出规范
| 退出码 | 含义 |
| ------ | --------------------------------- |
| 0 | 成功 |
| 1 | 业务错误(校验不通过 / 查询无结果) |
| 2 | 调用错误(参数 / IO / 网络) |
| 3 | 不可恢复(权限 / 数据完整性) |
JSON 错误:
```json
{
"ok": false,
"code": "E05099",
"message": "...",
"details": {}
}
```
---
## 6. 智能体能力注册表
`gaokato/capabilities/registry.py` 列出全部能力。每个能力包含:
- `name`
- `description`
- `cli` 子命令路径
- `schema`(参数 JSON schema)
- `risk`(`read` / `write` / `destructive`)
- `roles`(可调用角色)
- `examples`
---
## 7. Phase 4 必须收口
- 全部 25+ 子命令上线
- 旧 scripts/\* 全部 alias + deprecation warning
- `gaokao-cli doctor` 自检全绿
- `gaokato/capabilities/registry.py` 全集登记
---
**下一阶段**: Phase 4-5 实施,见 `docs/DESIGN_RULES_TRUSTED_CLI_2026-06-16.md` §11

21
docs/CURRENT_STATE.md
View File

@@ -5,14 +5,19 @@
真相源优先级:
1. 本文件
2. docs/FINAL_COMPLETION_REPORT_2026-06-13.md
3. docs/P0_P1_P2_REMEDIATION_PLAN_2026-06-14.md（当前整改板；2026-06-15 已做状态归一）
4. docs/FRONTEND_UI_AUDIT_2026-06-16.md
5. docs/FRONTEND_UI_EXECUTION_BOARD_2026-06-16.md
6. docs/ACTIVE_REMEDIATION_2026-06-13.md
7. product/PRD.md / product/ROADMAP.md / docs/IMPLEMENTATION_PLAN_v2.md
8. docs/PRODUCTION_DEPLOYMENT_CHECKLIST_2026-06-15.md
9. reports/PRODUCT_PLANNING_TECH_ALIGNMENT_REVIEW_2026-06-13.md（历史评审快照）
2. docs/PROJECT_PLANNING_REALIGNMENT_2026-06-16.md（本轮新增的规划/实现漂移审计）
3. docs/DESIGN_RULES_TRUSTED_CLI_2026-06-16.md（本轮新增的下一阶段设计：规则可信化 + CLI 能力层）
4. docs/RULES_SOURCE_OF_TRUTH.md（本轮新增的规则真相源索引）
5. docs/MAJOR_DATA_SOURCE_OF_TRUTH.md（本轮新增的专业目录真相源索引）
6. docs/CLI_API_MAPPING.md（本轮新增的 CLI/API 映射索引）
7. docs/FINAL_COMPLETION_REPORT_2026-06-13.md
8. docs/P0_P1_P2_REMEDIATION_PLAN_2026-06-14.md（当前整改板；2026-06-15 已做状态归一）
9. docs/FRONTEND_UI_AUDIT_2026-06-16.md
10. docs/FRONTEND_UI_EXECUTION_BOARD_2026-06-16.md
11. docs/ACTIVE_REMEDIATION_2026-06-13.md
12. product/PRD.md / product/ROADMAP.md / docs/IMPLEMENTATION_PLAN_v2.md
13. docs/PRODUCTION_DEPLOYMENT_CHECKLIST_2026-06-15.md
14. reports/PRODUCT_PLANNING_TECH_ALIGNMENT_REVIEW_2026-06-13.md（历史评审快照）
---

950
docs/DESIGN_RULES_TRUSTED_CLI_2026-06-16.md Normal file
View File

@@ -0,0 +1,950 @@
# DESIGN_RULES_TRUSTED_CLI_2026-06-16
最后更新: 2026-06-16
真相源: 本设计是 `docs/PROJECT_PLANNING_REALIGNMENT_2026-06-16.md` 审计结果的具体设计落点。
目标: 在不破坏现有 v2.1 已完成能力的前提下，把"规则可信化 / 专业目录可信化 / CLI 能力面 / 智能体调度 / 整体整合"一次性收敛到下一阶段实施级方案。
---
## 0. 阅读顺序
1. 本节
2. §1 总目标与边界
3. §2 规则规范可信化架构
4. §3 统一审计引擎
5. §4 专业目录数据真相源
6. §5 Application Services 层
7. §6 统一 CLI 命令面
8. §7 智能体能力调度层
9. §8 整体项目整合
10. §9 与现有 PRD/ROADMAP/规划的对接
11. §10 风险与验证
12. §11 实施阶段
---
## 1. 总目标与边界
### 1.1 解决什么
- 规则三处真相源不一致(2.1 审计)
- 规则无证据链(2.2)
- 专业目录无结构化真相源(2.3)
- CLI 不统一(2.5)
- 智能体无统一调度(2.6)
- 文档分层混乱(2.8)
### 1.2 不解决什么
- 真实支付 acceptance(外部条件阻塞,与本设计解耦)
- 现有 SKILL.md 内部对话风格(本设计不动 skill 角色,只把它们的"事实与执行"抽到 services + CLI)
- 短期内不可能做完的 27 省"规则自动化采集" — 留 Phase 2
- 完整 SaaS 化 UI 重构
### 1.3 关键设计原则
- **单一真相源**: 任何"权威数据"在系统中只允许有一个写入路径
- **可追溯**: 任何规则/数据都带来源、版本、更新时间
- **可分层调用**: 一份实现同时供 CLI / Hermes skill / HTTP / 智能体
- **可回归验证**: 每条新能力必须有可被 pytest 调用的最小 happy path + error path
- **不破坏现有 v2.1 入口**: admin/、data/orders/、data/payments/ 已收口,只新增层,不改既有契约
---
## 2. 规则规范可信化架构
### 2.1 四层模型
```
┌──────────────────────────────────────────────────────────┐
│ L1 规则证据层 (rules/_evidence/) │
│ 官方文件 / 公告原文 / 抓取快照 / 摘录 │
│ - 存储格式: evidence_id, source_url, fetched_at, ... │
│ - 写入方式: 手动 + 校验脚本 │
└────────────────────┬─────────────────────────────────────┘
▼
┌──────────────────────────────────────────────────────────┐
│ L2 规则真相源层 (rules/_truth/) │
│ - national_rules.yaml # 全国通用规则 │
│ - province/<prov>.yaml # 各省 2026 规则 │
│ - 字段: rule_id, scope, severity, source_evidence_id, │
│ effective_date, version, status │
└────────────────────┬─────────────────────────────────────┘
▼
┌──────────────────────────────────────────────────────────┐
│ L3 规则聚合层 (data/rules/loader.py) │
│ - 加载 national + province 规则 │
│ - 校验所有 source_evidence_id 都能在 L1 找到 │
│ - 对外暴露 get_rule(province, rule_id) │
│ - 暴露 list_province_rules(province) 等枚举接口 │
└────────────────────┬─────────────────────────────────────┘
▼
┌──────────────────────────────────────────────────────────┐
│ L4 规则应用层 │
│ - 统一审计引擎(data/rules/audit_engine.py) │
│ - CLI `gaokao-cli rules` │
│ - HTTP API `/api/rules/...` │
│ - Hermes skill `gaokao-rules-doctor` │
└──────────────────────────────────────────────────────────┘
```
### 2.2 关键目录与文件
新增:
- `rules/_evidence/`
- `README.md` — 收录规范
- `hunan/2026-本科批-院校专业组.md` — 抓取/摘录
- `hunan/2026-征集志愿.txt` — 原始公告
- ...
- `rules/_truth/`
- `national.yaml` — 全国通用规则(平行志愿、一次投档、退档机制等)
- `province/<prov>.yaml` — 各省 2026 规则
- `data/rules/__init__.py`
- `data/rules/loader.py`
- `data/rules/audit_engine.py`
- `data/rules/models.py`
- `data/rules/tests/test_loader.py`
- `data/rules/tests/test_audit_engine.py`
保留并改造:
- `rules/provinces.md` → 改成自动生成索引, 由 `data/rules/loader.py` 输出
- `scripts/gaokao-checker` → 改为薄 wrapper, 内部调 `audit_engine.run()`
### 2.3 数据模型
```python
# data/rules/models.py
class RuleSeverity(str, Enum):
FATAL = "fatal"
CRITICAL = "critical"
WARNING = "warning"
INFO = "info"
class RuleScope(str, Enum):
NATIONAL = "national"
PROVINCE = "province"
class Rule:
rule_id: str # e.g. "HUNAN.max_volunteers"
scope: RuleScope
province: str | None # 当 scope=province 时
year: int # 2026
title: str
description: str
severity: RuleSeverity
# 规则可机读形式,如 {"max_volunteers": 45}
value: dict
# 证据链
source_evidence_id: str
effective_date: date
last_verified_at: datetime
version: str # "2026.1"
status: str # "active" | "draft" | "deprecated"
class AuditIssue:
rule_id: str
severity: RuleSeverity
title: str
message: str
evidence_quote: str | None
suggestion: str | None
```
### 2.4 与现有 PROVINCE_RULES 的迁移
迁移方式: 一次性脚本 `scripts/migrate_province_rules_to_truth.py`:
- 读 `scripts/gaokao-checker` 里的 `PROVINCE_RULES`
- 给每条记录生成 `source_evidence_id` 占位 + `last_verified_at = 2026-06-12`
- 输出 `rules/_truth/province/*.yaml`
- 保留 `gaokao-checker` 旧 API,但内部委托给 `audit_engine`
不破坏现有 28 省的覆盖。迁移后:
- `PROVINCE_RULES` 作为"过渡期镜像"保留
- 新代码只读 `data/rules/loader.py`
- 旧 skill 暂时继续用 `PROVINCE_RULES`,不影响线上
### 2.5 2026 规则更新流程
```
官方文件发布 (人)
↓
1. 抓取/摘录 -> rules/_evidence/<prov>/<date>.md
2. 更新 rules/_truth/province/<prov>.yaml
3. python3 -m data.rules.cli verify <prov> # 自检 schema + 证据引用
4. pytest data/rules/tests/ # 跑回归
5. git commit -m "rules(<prov>): update 2026.2 ..."
6. 三仓推送
```
每月一次"规则刷新日"运行:
```bash
python3 -m data.rules.cli status
```
返回每个省的:
- 规则数量
- 最近验证时间
- 是否有未填 source_evidence_id
- 是否存在 active 状态但 last_verified_at > 90 天的规则
---
## 3. 统一审计引擎
### 3.1 接口设计
```python
# data/rules/audit_engine.py
class AuditEngine:
def __init__(self, rule_loader: RuleLoader): ...
def run(
self,
province: str,
plan: VolunteerPlan,
# 可选上下文: 选科 / 体检 / 投档历史
context: AuditContext | None = None,
) -> AuditResult: ...
class AuditResult:
province: str
overall_pass: bool
issues: list[AuditIssue]
applied_rule_ids: list[str]
evidence_chain: list[EvidenceRef] # 用于报告里附"依据文件"
schema_version: str
```
### 3.2 输入模型
```python
class VolunteerPlanItem:
school_name: str
school_code: str | None
major_group_code: str | None
major_names: list[str]
subject_requirements: list[str] | None
adjustment: bool | None # 是否服从组内调剂
reference_rank: int | None # 2025 年位次
class VolunteerPlan:
province: str
score: int | None
rank: int | None
subject_combo: str | None
items: list[VolunteerPlanItem]
```
### 3.3 引擎内部分层
1. **Schema 校验** — 必填字段、字段类型
2. **全国通用规则检查** — 例如:
- 平行志愿原则是否被违反
- "一次投档"原则在文本中是否被描述正确
3. **省级规则检查** — 例如:
- 志愿数是否在 max_volunteers 范围内
- 是否使用了正确的"模式"术语
4. **数据完整性检查** — 例如:
- 每个 item 必须有 reference_rank 或明确标注待官方公布
- 院校代码与名称是否对得上
5. **风险评估** — 不在规则层,而是规则层之上,见 §3.4
### 3.4 与 `gaokao-spec-checker` / `gaokao-audit` 的关系
| 能力 | 改造前 | 改造后 |
| ------------------------- | ---------------------------------------------------- | --------------------------------------------------------------------- |
| regex 规则检查 | `skills/gaokao-spec-checker/scripts/spec_checker.py` | 保留,改为薄 wrapper, 内部调 `audit_engine` |
| 完整审核(含扎堆/数据溯源) | `skills/gaokao-audit/scripts/audit_service.py` | 保留,改为薄 wrapper, 内部调 `audit_engine` + crowd_db + major_catalog |
| 客服/智能体调用 | 直接 `import` | 改为调 CLI 或 HTTP,不再依赖 Python 模块路径 |
---
## 4. 专业目录数据真相源
### 4.1 必要性
用户原话:"最近两年各学校和国家机构取消和新增了很多专业,防止我们提供错误的专业"。
当前仓库:
- 没有教育部本科专业目录导入
- 没有高校招生专业目录导入
- 现有 `data/crowd_db/*.json` 只是"大厂AI 热门汇总",与官方目录不是同一回事
- 推荐/审核如果引用"已撤销专业"或"目录外专业名",系统不会报警
### 4.2 数据模型(两层)
#### L1 教育部本科专业目录
```python
# data/majors/models.py
class NationalMajor:
code: str # 教育部专业代码 e.g. "120201K"
name: str # 官方名称 e.g. "工商管理"
discipline: str # 学科门类 e.g. "管理学"
category: str # 专业类 e.g. "工商管理类"
degree: str # 授予学位 e.g. "管理学学士"
is_directional: bool # 是否国家控制布点专业
status: str # "active" | "renamed" | "merged" | "deprecated"
year_added: int # 首次列入目录年份
year_removed: int | None
notes: str | None
source_url: str
last_verified_at: datetime
```
#### L2 高校招生专业(招生章程)
```python
class SchoolMajorOffering:
school_code: str
school_name: str
major_code: str # 教育部专业代码
major_name: str # 学校招生目录名称
admission_year: int
province: str
duration_years: int
tuition_cny: int | None
study_mode: str # "全日制"
is_new: bool # 该校该年新增
is_discontinued: bool # 该校该年撤销/停招
source: str
last_verified_at: datetime
```
### 4.3 数据接入
#### 4.3.1 教育部本科专业目录(国家级)
- **优先级 1**: 教育部 2024 年发布《普通高等学校本科专业目录》
- **优先级 2**: 教育部学位中心公开数据
- **来源类型**:
- 半自动抓取 + 人工校对(高优)
- 用户/客服智能体可调 `gaokao-cli majors ingest <url>` 提交
- **落地格式**: `data/majors_catalog/national/{year}.json` + `latest.json` 软链
- **不做**:
- 自动爬取(高风险/合规)
- 把整个目录当自动真相源(目录有延迟,需要人工核对)
#### 4.3.2 高校招生专业(校级)
- **优先级 1**: 各高校招生章程(每年 5-7 月发布)
- **优先级 2**: 阳光高考平台公示
- **格式**: `data/majors_catalog/schools/{year}/{school_code}.json`
- **接入方式**:
- 暂不做自动抓取
- 维护一个 `schools_2026.csv` 入口清单(20-30 所主流校)
- 每个文件加 `confidence` 字段和 `verified_by` 字段
### 4.4 在审计引擎里的使用
`audit_engine` 新增一个 `major_validation` 检查步骤:
- 输入 plan 里的 `major_names`
- 对每一条:
- 查 `NationalMajor` 是否存在且 `status=active`
- 如果不存在或已撤销,标 `FATAL` 错误
- 如果 `is_new=true`(2024 之后新设),建议核查该专业是否真招
- 给出 evidence: 教育部目录年份 + 国家专业代码
对学校专业组同理:
- 查 `SchoolMajorOffering` 是否在 2026 招生目录
- 标记 `is_discontinued` 的项
### 4.5 风险管理
- **不在审计/推荐里引用 2024 年前撤销的专业** — 默认行为
- **新设专业必须有 2024 之后的 evidence** — 默认行为
- **失败安全**: 如果某条 major 在 national catalog 找不到,只警告,不强阻断(因为可能有"新设尚未入库"的情况)
- **所有"找不到"必须留下"待人工确认"标签**
---
## 5. Application Services 层
### 5.1 为什么需要
现有调用方式:
- `skills/gaokao-counselor-long` 通过 `import skills.gaokao-audit.scripts.audit_service` 直接调
- `scripts/gaokao-order-manager` 通过 `import data.orders.cli` 直接调
问题:
- 调用方依赖服务方内部模块路径
- 没有事务边界、权限、日志
- 不能跨 Python 版本/虚拟环境复用
### 5.2 设计
新增 `gaokato/services/` 包,作为"业务门面"层:
```
gaokato/
├── services/
│ ├── __init__.py
│ ├── audit.py # audit_plan(province, plan, ctx) -> AuditResult
│ ├── order.py # create_order, get_order, list_orders, update_status
│ ├── plan.py # generate_plan, validate_plan
│ ├── report.py # render_report
│ ├── payment.py # payment_doctor, ...
│ ├── majors.py # lookup_major, validate_plan_majors
│ ├── rules.py # list_province_rules, get_rule, status
│ └── delivery.py # dispatch, watchdog
└── transport/
├── cli.py # argparse / typer
├── http_client.py # admin FastAPI 调用封装
└── skill_adapter.py # 给 hermes skill 用的稳定接口
```
### 5.3 与现有代码关系
- `data/orders/cli.py` 已有 `OrdersCLI`,把核心方法抽到 `gaokato.services.order`
- `skills/gaokao-audit/scripts/audit_service.py` 抽到 `gaokato.services.audit`
- `scripts/gaokao-checker` 改为调 `gaokato.services.audit.run(...)`
- 旧 skill 与旧 CLI 内部都委托给 services,保持外部契约
### 5.4 关键接口草案
```python
# gaokato/services/audit.py
def audit_plan(
province: str,
plan: VolunteerPlan | dict,
*,
include_crowd_check: bool = True,
include_major_validation: bool = True,
output_format: str = "structured", # "structured" | "text" | "json"
) -> AuditResult: ...
```
```python
# gaokato/services/order.py
def create_order(
service_code: str, # "audit" | "standard" | "premium"
customer_name: str,
customer_contact: str,
*,
source: str = "agent-cli",
actor: str | None = None, # 谁触发的(留痕)
dry_run: bool = False,
) -> Order: ...
def get_order(order_id: str) -> Order: ...
def list_orders(*, status: str | None = None, limit: int = 50) -> list[Order]: ...
def update_status(order_id: str, new_status: str, *, actor: str, note: str | None = None) -> Order: ...
```
```python
# gaokato/services/rules.py
def list_province_rules(province: str) -> list[Rule]: ...
def get_rule(province: str, rule_id: str) -> Rule: ...
def status(province: str | None = None) -> RulesStatus: ...
```
```python
# gaokato/services/majors.py
def lookup_major(name_or_code: str) -> NationalMajor | None: ...
def validate_plan_majors(plan: VolunteerPlan) -> list[AuditIssue]: ...
```
### 5.5 日志与权限
- 所有 service 调用强制写 `logs/gaokato_audit.log`(JSON Lines)
- 每条记录包含:
- `ts`
- `actor`
- `action`
- `args`(脱敏)
- `result`(`ok` / `error`)
- `duration_ms`
- 不在 services 层做"用户/角色"判断,留给上层:
- CLI 入口用 `--actor`
- HTTP API 用 JWT subject
- Skill 用 skill 自身 caller
---
## 6. 统一 CLI 命令面
### 6.1 命令入口
`gaokao-cli` 单一入口,子命令分组:
```
gaokao-cli
├── audit
│ ├── run # gaokato.services.audit.audit_plan
│ ├── explain # 输出某条规则的解释与证据
│ └── list-rules # 列出某省 2026 规则
├── order
│ ├── create
│ ├── get
│ ├── list
│ ├── update-status
│ └── export
├── plan
│ ├── generate
│ └── validate
├── report
│ ├── render
│ └── export-pdf
├── majors
│ ├── lookup
│ ├── validate
│ └── list-changes
├── rules
│ ├── status
│ ├── list
│ └── explain
├── payment
│ ├── doctor
│ └── status
├── delivery
│ ├── dispatch
│ ├── watchdog
│ └── status
├── channel
│ ├── fallback
│ └── status
├── backup
│ ├── snapshot
│ ├── verify
│ └── restore
└── retention
├── cleanup
└── status
```
### 6.2 公共约定
- 所有命令支持:
- `--json` 输出 JSON
- `--actor <who>` 留痕
- `--quiet` 仅退出码
- 退出码:
- `0` 成功
- `1` 业务错误
- `2` 调用错误(参数/IO)
- `3` 不可恢复(权限/数据完整性)
- 错误输出统一格式:
```json
{"ok": false, "code": "E05099", "message": "...", "details": {...}}
```
- 长操作命令支持 `--watch`(简单轮询)
- 任何"写"操作支持 `--dry-run`
### 6.3 命令集详细
| 命令 | 用途 | 适用角色 |
| --------------------- | ------------------------------ | ------------------ |
| `audit run` | 对一份方案做政策+专业+扎堆审核 | 客服/智能体/管理员 |
| `audit list-rules` | 列某省 2026 规则 | 客服/智能体/管理员 |
| `audit explain` | 解释某条规则的来源 | 客服/智能体 |
| `order create` | 创建订单 | 智能体/管理员 |
| `order get` | 查询订单 | 客服/智能体 |
| `order list` | 列表 | 客服/管理员 |
| `order update-status` | 推进状态 | 管理员 |
| `order export` | CSV 导出 | 管理员 |
| `plan generate` | 生成方案 | 智能体 |
| `plan validate` | 校验方案 | 智能体 |
| `report render` | 渲染报告 | 智能体 |
| `report export-pdf` | 导出 PDF | 智能体/管理员 |
| `majors lookup` | 查专业 | 客服/智能体 |
| `majors validate` | 校验方案中所有专业 | 智能体 |
| `majors list-changes` | 列近两年专业增减 | 客服/智能体 |
| `rules status` | 规则台账状态 | 管理员 |
| `rules list` | 规则列表 | 管理员/客服 |
| `rules explain` | 规则解释 | 客服 |
| `payment doctor` | 支付 provider 健康检查 | 管理员 |
| `payment status` | 支付状态汇总 | 管理员 |
| `delivery dispatch` | 触发交付 | 管理员/智能体 |
| `delivery watchdog` | 跑一次 watchdog | 管理员 |
| `channel fallback` | 渠道兜底拉取 | 管理员 |
| `backup snapshot` | 备份 | 管理员 |
| `backup verify` | 校验备份 | 管理员 |
| `backup restore` | 恢复 | 管理员 |
| `retention cleanup` | 清理超期 | 管理员 |
| `retention status` | 状态 | 管理员 |
### 6.4 实现位置
`gaokato/transport/cli.py` 用 `typer`(或 `argparse` 子解析),每个子命令对应一个 handler,内部委派 `gaokato.services.*`。
向后兼容:
- `scripts/gaokao-audit` 改成 `gaokao-cli audit run`
- `scripts/gaokao-order-manager` 改成 `gaokao-cli order ...`
- `scripts/gaokao-checker` 改成 `gaokao-cli audit run`
- 旧入口保留 3-6 个月作为 alias,带 deprecation warning
### 6.5 安装与发现
- `gaokao-cli` 在 `pyproject.toml` 注册 `console_scripts`
- `gaokao-cli --help` 输出命令树
- `gaokao-cli <group> --help` 输出子命令
- `gaokao-cli doctor` 自检: Python 版本、env、DB、规则可加载性
---
## 7. 智能体能力调度层
### 7.1 形态
不重写已有 skill(它们已经稳)。新增**能力注册表 + 调用层**:
```
gaokato/
├── capabilities/
│ ├── __init__.py
│ ├── registry.py # 能力注册表
│ └── adapters/
│ ├── hermes.py # 把能力导出为 hermes tool
│ └── skill.py # 让 skill 通过 cli 调用
```
### 7.2 能力注册表
```python
# gaokato/capabilities/registry.py
class Capability:
name: str
description: str
cli: str # "audit run" / "order create" ...
schema: dict # JSON schema, 参数约束
risk: str # "read" | "write" | "destructive"
roles: list[str] # 哪些角色可调
examples: list[dict]
REGISTRY: list[Capability] = [
Capability(
name="audit_plan",
description="对一份志愿方案做政策/专业/扎堆四维审核",
cli="gaokao-cli audit run --province <p> --plan <file>",
schema={...},
risk="read",
roles=["agent", "operator", "admin"],
examples=[...],
),
...
]
```
### 7.3 与 Hermes skill 的关系
- **现状**:
- `gaokao-counselor-long` 靠 Python import 调 audit_service
- 与目录结构耦合
- **目标**:
- skill 内部 import `gaokato.services.audit` 而非 `skills.gaokao-audit.scripts.audit_service`
- 不再走 Python import 调外部脚本,改用 `subprocess` 调 `gaokao-cli`
- 这给"未来切到独立进程/HTTP"留好接口
### 7.4 与 admin HTTP 的关系
- 现有 `admin/routes/orders.py`、`admin/routes/cases.py` 等直接调 data 层的 DAO
- 改造路径:
- `admin/routes/orders.py` 内部改为调 `gaokato.services.order.*`
- HTTP 层不再直接读 `data/orders/*`
- 这样:
- CLI 与 admin 用同一份 service 实现
- 未来后台 API 拆分不影响业务
### 7.5 与真实"志愿服务智能体"的关系
- 单一智能体 = 一个 role + 多个 capability
- 推荐形态:
- 客服智能体: `audit_plan` + `order get` + `report render`
- 运营智能体: `order create` + `order update-status` + `report render`
- 志愿顾问智能体: `plan generate` + `plan validate` + `audit run`
- 管理员智能体: 全集 + `payment doctor` + `backup verify`
- 智能体本身不实现业务,只编排 capability
---
## 8. 整体项目整合
### 8.1 真相源分层
```
CURRENT_STATE.md # 项目总览 + 当前阶段
PROJECT_PLANNING_REALIGNMENT_2026-06-16.md # 漂移审计(本轮新增)
RULES_SOURCE_OF_TRUTH.md # 规则真相源索引(本轮新增)
MAJOR_DATA_SOURCE_OF_TRUTH.md # 专业目录真相源索引(本轮新增)
CLI_API_MAPPING.md # CLI/HTTP/skill 三层映射(本轮新增)
DESIGN_RULES_TRUSTED_CLI_2026-06-16.md # 本设计
```
### 8.2 目录结构(终态)
```
/home/long/project/gaokao-volunteer-system/
├── admin/ # 现有 FastAPI 后台
├── data/ # 现有 data 域
├── skills/ # 现有 skill
├── scripts/ # 现有 scripts(逐步 thin wrapper)
├── gaokato/ # 【新增】应用服务 + transport + capability
│ ├── services/
│ ├── transport/
│ └── capabilities/
├── rules/ # 【扩展】
│ ├── _evidence/ # 规则证据(原文/摘录)
│ ├── _truth/ # 规则真相源
│ │ ├── national.yaml
│ │ └── province/
│ ├── errors/
│ └── provinces.md # 自动生成索引
├── data/majors_catalog/ # 【新增】专业目录真相源
│ ├── national/
│ └── schools/
└── docs/
├── CURRENT_STATE.md
├── PROJECT_PLANNING_REALIGNMENT_2026-06-16.md
├── RULES_SOURCE_OF_TRUTH.md
├── MAJOR_DATA_SOURCE_OF_TRUTH.md
├── CLI_API_MAPPING.md
└── DESIGN_RULES_TRUSTED_CLI_2026-06-16.md
```
### 8.3 不会破坏的边界
- `admin/` 的现有路由契约不破坏
- `data/orders/`、`data/payments/` 的现有 DAO/Model 不破坏
- `skills/` 的现有 SKILL.md frontmatter 不破坏(只改内部 import)
- `scripts/gaokao-checker` 之类的旧入口 alias 保留 3-6 个月
### 8.4 数据流总图
```
外部输入 (用户/智能体/CLI/HTTP)
↓
统一入口(CLI / admin FastAPI / Hermes tool)
↓
gaokato.services.* (业务门面,带审计日志)
↓
├─→ data.rules.audit_engine (规则层,读 rules/_truth)
├─→ data.majors_catalog (专业目录)
├─→ data.crowd_db (扎堆检测)
├─→ data.orders.dao (订单)
├─→ data.payments.service (支付)
└─→ data.notifications (通知)
↓
SQLite / 文件存储
```
---
## 9. 与现有 PRD / ROADMAP / 规划的对接
### 9.1 PRD 对接
- PRD 中"F020 AI 方案审核"标 ✅,实际本设计把它从"skill 内部能力"提升为"系统级 capability"
- PRD 中 F011 数据自动更新,本设计给出真实数据接入路径
- PRD 中 F015 智能推荐,本设计为其提供"可信数据底座"
### 9.2 ROADMAP 对接
- 2026 Q2 阶段:已闭合
- 2026 Q3 阶段建议插入:
- **本设计是 2026 Q3 收口级工作**
- 不与商业化目标冲突,反而是商业化的必要前置
### 9.3 IMPLEMENTATION_PLAN_v2 对接
- T1~T11 已完成,本设计是后续 T13 候选
- T12 用户端 Web 自助的下一阶段,需要本设计提供:
- 规则可信化(否则 2026 高考季扛不住)
- 专业目录可信化(否则推荐错误成本高)
- CLI 能力面(否则客服/运营跟不上)
### 9.4 本设计与原 4 个优化目标对齐
| 目标 | 落到本设计的哪里 |
| ----------------- | ---------------- |
| 规则规范可信化 | §2 + §3 |
| 2026 专业目录 | §4 |
| CLI 能力层 | §5 + §6 + §7 |
| 整体规划/实现优化 | §8 + §9 |
---
## 10. 风险与验证
### 10.1 关键风险
- **R1**: 迁移 `PROVINCE_RULES` 时可能漏字段
- 缓解: 一次性脚本 + 全量单元测试,确保 28 省全覆盖
- **R2**: 教育部专业目录与"高校招生目录"语义混淆
- 缓解: §4.2 明确两层,分别建模
- **R3**: 客服/智能体依赖旧 Python 路径,新设计未落地前不能破坏
- 缓解: §8.3 明确保留旧入口 3-6 个月
- **R4**: 全国通用规则抽象被过度设计
- 缓解: Phase 1 只抽"已明确稳定的"全国规则,避免空想规则
- **R5**: 真实环境无 2026 规则原文
- 缓解: Phase 1 接受"暂以 2025 已稳定规则 + 标注 last_verified_at"为基线
- **R6**: CLI 改名影响线上脚本
- 缓解: 旧 entry 保留为 alias + deprecation warning
### 10.2 真实验收标准
每条 Phase 必须有:
1. **可运行入口**: `gaokao-cli <group> --help` 出树
2. **可执行 smoke**: `gaokao-cli audit run --province 湖南 --plan fixtures/sample.json` 返回结构化结果
3. **可回归测试**: `pytest gaokato/ data/rules/ data/majors_catalog/ -q` 全绿
4. **可读源码**: 服务层每个函数都有 docstring + 错误码
5. **可被智能体调用**: hermes skill `gaokato_capabilities.json` 列出全部 capability
6. **可被后台调用**: `admin/routes/` 全部委托给 `gaokato.services.*`
### 10.3 阶段验收检查点
每个 Phase 结束时必须:
- 跑 `bash scripts/dev-verify.sh`
- 跑 `gaokao-cli doctor`
- 跑 `gaokao-cli rules status`
- 跑 `gaokao-cli majors validate fixtures/sample.json`
- 三仓推送
---
## 11. 实施阶段
### Phase 1 — 规则真相源化(无破坏,低风险)
**目标**: 把"规则硬编码"升级为"可追溯规则"
任务:
1. 落 `rules/_truth/national.yaml` + `province/<prov>.yaml`(28 省)
2. 写迁移脚本 `scripts/migrate_province_rules_to_truth.py`
3. 落 `data/rules/loader.py` + `audit_engine.py` 最小可用版
4. 保留 `scripts/gaokao-checker` 与 SKILL 行为
5. 加测试: `data/rules/tests/test_loader.py` + `test_audit_engine.py`
验收:
- `gaokao-cli rules status` 可用
- `gaokao-cli audit run` 行为与旧 `gaokao-checker` 一致
- 28 省规则 100% 迁移
---
### Phase 2 — 统一审计引擎最小可用
任务:
1. `gaokato/services/audit.py` 抽核心
2. `gaokato/transport/cli.py` 注册 `gaokao-cli audit run/explain/list-rules`
3. `skills/gaokao-counselor-long` 内部改为调 service(或 CLI)
4. 旧 skill 行为不变
验收:
- `gaokao-cli audit run` + JSON 输出
- hermes skill 仍能调起同一能力
---
### Phase 3 — 专业目录接入(MVP)
任务:
1. 落 `data/majors_catalog/national/2024.json`(教育部最新)
2. 落 5-10 所重点高校 2025/2026 招生目录
3. `gaokato/services/majors.py`
4. `gaokato.services.audit` 接入 major_validation
5. `gaokao-cli majors lookup/validate/list-changes`
验收:
- 任意 plan 跑 `gaokao-cli majors validate` 可标出已撤销/新设专业
- 至少 1 个 e2e:大厂AI方案 → audit run → major validation 命中
---
### Phase 4 — 统一 CLI 命令面
任务:
1. 落 `gaokato/transport/cli.py` 全部子命令
2. 保留旧脚本 alias + deprecation warning
3. `gaokao-cli doctor` 自检
4. `gaokato/capabilities/registry.py` 全集
验收:
- 全部 25+ 子命令可用
- `gaokao-cli --help` 树清晰
- 所有 `--json` 行为一致
---
### Phase 5 — 智能体调度与 admin 整合
任务:
1. `admin/routes/*` 委托 `gaokato.services.*`
2. hermes skill `gaokato_capabilities.json` 导出
3. 至少 3 个 skill 角色(客服/运营/顾问)绑定 capability
4. 端到端跑通
验收:
- 客服智能体可"读方案 → 调 audit → 查 order → 出报告"
- 运营智能体可"创建订单 → 改状态 → 出报告"
- 顾问智能体可"生成方案 → 校验 → 出报告"
---
### Phase 6 — 文档/真相源索引收口
任务:
1. 落 `RULES_SOURCE_OF_TRUTH.md` `MAJOR_DATA_SOURCE_OF_TRUTH.md` `CLI_API_MAPPING.md`
2. `CURRENT_STATE.md` 更新指向本设计
3. `PROJECT_PLANNING_REALIGNMENT_2026-06-16.md` 标记已落地
验收:
- 任何入口文档(CURRENT_STATE / README / PROJECT_PLANNING_REALIGNMENT)不再有冲突
---
## 12. 一次性完成顺序
主代理按以下顺序继续执行(用户已批准继续):
1. **本设计落盘** ✅ (本文件)
2. **审计落盘** ✅ (`PROJECT_PLANNING_REALIGNMENT_2026-06-16.md`)
3. **三处真相源文档** → `RULES_SOURCE_OF_TRUTH.md` + `MAJOR_DATA_SOURCE_OF_TRUTH.md` + `CLI_API_MAPPING.md`
4. **整体规划对接** → 提交一次 docs-only commit + 三仓推送
5. **回主对话** → 报告本轮完成
下一轮(用户再"继续"):
- Phase 1 实施
- TDD 走 RED-GREEN
- 仍然按"生产级 + 三仓同步"标准
---
**版本**: v1.0
**最后更新**: 2026-06-16
**对应规划**: `docs/PROJECT_PLANNING_REALIGNMENT_2026-06-16.md`
**后续执行**: 等待用户"继续"进入 Phase 1

136
docs/MAJOR_DATA_SOURCE_OF_TRUTH.md Normal file
View File

@@ -0,0 +1,136 @@
# MAJOR_DATA_SOURCE_OF_TRUTH
最后更新: 2026-06-16
真相源: 本文件是"专业目录"维度的入口索引。
审计上下文: `docs/PROJECT_PLANNING_REALIGNMENT_2026-06-16.md` §2.3-2.4
设计上下文: `docs/DESIGN_RULES_TRUSTED_CLI_2026-06-16.md` §4
---
## 1. 范围
本文件收敛以下两类信息:
- 教育部本科专业目录(国家级)
- 高校招生专业目录(校级)
---
## 2. 当前真相源路径
| 类别 | 路径 | 格式 | 写入方式 |
| --------------- | ------------------------------------------------------- | -------- | ------------------------- |
| 国家级专业目录 | `data/majors_catalog/national/<year>.json` | JSON | 半自动抓取 + 人工校对 |
| 国家级当前 | `data/majors_catalog/national/latest.json` | JSON | 软链或生成时锁定 |
| 校级招生专业 | `data/majors_catalog/schools/<year>/<school_code>.json` | JSON | 人工为主,来源高校招生章程 |
| 元数据 | `data/majors_catalog/METADATA.md` | Markdown | 人工维护 |
| 已撤销/新设清单 | `data/majors_catalog/changes/2024-2026.md` | Markdown | 人工维护 |
---
## 3. 两层数据模型
### 3.1 国家级(NationalMajor)
```python
NationalMajor:
code: str # 教育部专业代码, e.g. "120201K"
name: str # 官方名称, e.g. "工商管理"
discipline: str # 学科门类
category: str # 专业类
degree: str # 授予学位
is_directional: bool # 国家控制布点专业
status: "active" | "renamed" | "merged" | "deprecated"
year_added: int
year_removed: int | None
notes: str | None
source_url: str
last_verified_at: datetime
```
### 3.2 校级(SchoolMajorOffering)
```python
SchoolMajorOffering:
school_code: str
school_name: str
major_code: str
major_name: str
admission_year: int
province: str
duration_years: int
tuition_cny: int | None
study_mode: str
is_new: bool
is_discontinued: bool
source: str
last_verified_at: datetime
```
---
## 4. 接入策略
### 4.1 国家级
- **首选源**: 教育部 2024 年《普通高等学校本科专业目录》
- **兜底源**: 阳光高考/学位中心
- **抓取方式**: 不自动爬取,使用人工收录 + 摘录
- **校验**: `python3 -m data.majors_catalog.cli verify national`
### 4.2 校级
- **首选源**: 各高校 2025/2026 招生章程
- **覆盖范围**: 首批 5-10 所重点高校
- **接入节奏**: 每所高校每年一次,5 月前完成
- **校验**: `python3 -m data.majors_catalog.cli verify school <code>`
---
## 5. 审计引擎集成
`audit_engine.run` 接收 plan,新增一步:
```python
def _validate_majors(plan: VolunteerPlan) -> list[AuditIssue]:
issues = []
for item in plan.items:
for major_name in item.major_names:
major = majors_catalog.lookup(major_name)
if major is None:
issues.append(AuditIssue(
rule_id="MAJORS.not_found",
severity=RuleSeverity.WARNING,
title=f"专业未在国家级目录中找到: {major_name}",
suggestion="请人工核对",
))
elif major.status != "active":
issues.append(AuditIssue(
rule_id="MAJORS.deprecated",
severity=RuleSeverity.CRITICAL,
title=f"专业已撤销/合并/改名: {major.name}",
evidence_quote=f"{major.year_removed} 年已 {major.status}",
))
return issues
```
---
## 6. Phase 3 必须收口
- `data/majors_catalog/national/2024.json` 落地,500+ 专业覆盖
- 5+ 重点高校 2025/2026 招生目录落地
- `gaokao-cli majors lookup/validate` 可用
- 1+ 真实 e2e:大厂AI方案跑 audit run 命中 major 验证
---
## 7. 风险
- 国家级目录与校级目录语义混淆
- 教育部新设专业不进入旧目录(2024 之后新设)
- 跨年招生章程口径不一致
---
**下一阶段**: Phase 3 实施,见 `docs/DESIGN_RULES_TRUSTED_CLI_2026-06-16.md` §11

178
docs/PROJECT_PLANNING_REALIGNMENT_2026-06-16.md Normal file
View File

@@ -0,0 +1,178 @@
# PROJECT_PLANNING_REALIGNMENT_2026-06-16
最后更新: 2026-06-16
真相源: 本文件是 `docs/CURRENT_STATE.md` 之外的"规划/实现漂移审计"补充真相源。
本审计聚焦: 当前规划/设计文档与代码、规则、数据之间的真实不一致点。
---
## 1. 范围与方法
- 审计对象:
- 产品规划: `product/PRD.md`、`product/ROADMAP.md`
- 技术设计: `docs/TECH_ARCHITECTURE.md`、`docs/ADMIN_DESIGN.md`、`docs/SHARING_DESIGN.md`、`docs/PAYMENT_DOMAIN_DESIGN.md`
- 实施计划: `docs/IMPLEMENTATION_PLAN_v2.md`
- 规则真相源: `rules/provinces.md`、`rules/errors/ERRORS.md`、`skills/gaokao-spec-checker/SKILL.md`、`scripts/gaokao-checker`、`data/crowd_db/*.json`
- Skill 定义: `skills/gaokao-spec-checker/SKILL.md`、`skills/gaokao-audit/SKILL.md`、`skills/gaokao-counselor-long/SKILL.md`、`skills/gaokao-college-advisor/SKILL.md`、`skills/zhangxuefeng-skillset/SKILL.md`
- 实际代码: `admin/`、`data/`、`scripts/`
- 审计目标: 不重复 T12/支付/portal 已收口结论，只补"规划 vs 实现 vs 规则 vs 数据"的真实不一致。
---
## 2. 主要漂移与缺口
### 2.1 规则能力: 三处真相源口径不一致
- `rules/provinces.md`:
- 院校专业组模式 14 省
- 专业+学校模式 8 省
- 传统模式 5 省
- 合计 27 省
- `skills/gaokao-spec-checker/SKILL.md` frontmatter:
- 列名包含 28 省(含广西)
- 摘要中按 14/8/6 描述,与 provinces.md 传统模式数量不同(5 vs 6)
- `scripts/gaokao-checker` 的 `PROVINCE_RULES`:
- 实际定义 28 省(含广西、山西)
- 但不包含陕西
- 真实差距:
- 文档对外宣称 27 省
- 实际规则 28 省
- SKILL.md 与 provinces.md 的传统模式数对不上(6 vs 5)
- 风险:
- 客服/智能体在文档与脚本之间会获得不同省份覆盖承诺
- 后续任何"加省/删省"都会在三个真相源之间产生连锁漂移
### 2.2 规则证据链不足: 全国通用规则没有独立抽象
- 现状:
- `gaokao-spec-checker` 的检查项是硬编码的省级字段(志愿数、专业组数、调剂范围等)
- 没有"全国通用规则"独立层
- 没有"省级差异规则"独立层
- 规则来源只在 PROVINCE_RULES 的 `official_url` 字段里给一个官网链接,没有版本号、发布日期、收录人、证据文件
- 后果:
- 任何省级规则更新,必须改 `gaokao-checker` 源码
- 没有任何审计能告诉你"湖南 2026 规则 v1.2 是基于哪份官方文件"
- 智能体调用 spec-checker 时无法解释"为什么这一条规则成立"
### 2.3 专业目录数据: 没有结构化真相源
- 现状:
- 仓库内无 `data/majors/`、无 `data/majors_catalog/` 等目录
- 现有 `data/crowd_db/hunan.json` 等只是"大厂AI热门推荐汇总",不是教育部本科专业目录
- 院校专业组里的"专业名"散落在各 SKILL.md / rules / crowd_db / 报告中,无统一结构
- 没有"专业是否存在 / 是否 2026 仍招生 / 是否已撤销"的元数据
- 后果:
- 任何推荐、审核、报告都可能在引用:
- 已经撤销的专业
- 已经合并的专业
- 近两年新设的目录外专业
- 没有机制阻止"AI 生成方案里写了已经撤销的某专业"
### 2.4 数据溯源机制: 局部实现, 缺统一抽象
- 现状:
- `data/crowd_db/hunan.json` 内有 `source / source_url / source_type / confidence` 字段
- 但只是"这一份" crowd_db 数据的元数据
- 没有任何代码层把这些元数据汇总到"整个项目的数据来源台账"
- SKILL.md 之间的引用缺乏统一证据链
- 后果:
- `data_trace` 脚本/能力只在 crowd_db 范围可用
- 真实生产环境里"这份院校数据来自哪里"无法一键回答
### 2.5 CLI 能力面: 多入口, 缺统一命令面
- 现状(部分清单):
- `scripts/gaokao-checker` — 规范检查
- `scripts/gaokao-audit` — 审核
- `scripts/gaokao-order-manager` — 订单 CLI
- `scripts/gaokao-shortlink` — 短链接
- `scripts/gaokao-data-trace` — 数据溯源
- `scripts/gaokao-channel-fallback` — 渠道兜底
- `scripts/gaokao-delivery-*.py` — 交付相关
- `scripts/backup_*` — 备份
- `scripts/gaokao-retention-cleanup.py` — 数据保留
- `scripts/payment_provider_doctor.py` — 支付 provider 健康检查
- 问题:
- 命令命名风格不统一(`gaokao-` 前缀 vs 业务前缀)
- 参数风格、输出格式、退出码各脚本不统一
- 没有"统一 CLI 入口"能让客服/运营/智能体一句话调起全部能力
- 智能体(尤其 gaokao-counselor-long)直接调 Python 模块,而不是稳定 CLI
### 2.6 智能体集成: Skill 之间耦合度高, 缺统一调度层
- 现状:
- `gaokao-counselor-long` 通过 Python import 直接调 `skills/gaokao-audit/scripts/audit_service`
- 文档化的"统一 CLI 入口"实际是 `python3 scripts/gaokao-audit <file> --json`
- 没有"能力注册表 / agent capability catalog"层
- 后果:
- 任何脚本目录结构改动都会破坏 smart body 调用
- 跨 skill 协作靠约定,不靠契约
- 运营/客服智能体无法在不读源码的情况下找到所有可用能力
### 2.7 PRD/TECH_ARCHITECTURE 与实现的脱节点
- `docs/TECH_ARCHITECTURE.md` 第 2.1 节明确说"省份规则: hardcoded in scripts":
- 这是真实状态,但 TECH_ARCHITECTURE 写得像"目标态",不是真实态
- `docs/TECH_ARCHITECTURE.md` 列出"v2.0 已有 `gaokao-checker` 入口", 但 SKILL.md 与 plan 都没有把"gaokao-checker 是审核入口"这件事正式承认
- `product/PRD.md` 的 F020 "AI 方案审核" 标 ✅ 已完成, 但 `gaokao-audit` 现状只能本地 smoke + 文档化能力, 真实客服/智能体调用未走 prod 链路
- `docs/ADMIN_DESIGN.md` 描述的"案例管理 / 数据监控"在 `admin/routes/cases.py` `admin/routes/stats.py` 里, 但与 PRD 描述不完全一致(PRD 描述更"全栈", 实现是 admin 后台视角)
### 2.8 文档分层不统一
- 现状:
- 设计文档(ADMIN_DESIGN / SHARING_DESIGN / TECH_ARCHITECTURE) 描述的是 v1.0 目标态
- 计划文档(IMPLEMENTATION_PLAN_v2) 是 v2.0 实施态
- 当前状态文档(CURRENT_STATE) 是 v2.1 已完成态
- 没有任何文档明确说"哪一份是当前真相源"在每个维度上
- 后果:
- 阅读者要自己在多份文档之间"挑最新"
- AI 智能体引用时容易引用过期设计
---
## 3. 优先级判断
### P0 — 不修会直接影响生产可信度
- 规则三处真相源口径不一致(2.1)
- 专业目录数据没有结构化真相源(2.3)
### P1 — 不修会限制下一阶段能力建设
- 规则证据链不足, 无全国/省级规则分层(2.2)
- CLI 能力面不统一(2.5)
- 智能体集成无统一调度层(2.6)
### P2 — 不修会继续漂移但不立即影响生产
- 数据溯源机制缺统一抽象(2.4)
- PRD/TECH_ARCHITECTURE 与实现脱节(2.7)
- 文档分层不统一(2.8)
---
## 4. 下一阶段必须分两条线
- **可信化线(P0)**:
- 规则真相源改造
- 专业目录数据接入与版本化
- **能力层线(P1)**:
- 统一审计引擎
- 统一 CLI 命令面
- 智能体能力注册表
- 文档/架构收敛(P2)放在可信化线和能力层线收口后, 一次性收敛
---
## 5. 与本轮新任务的对接
本审计直接回答用户最新提出的四个优化目标:
| 用户目标 | 对应审计结论 | 后续设计 |
| ----------------- | ------------ | ------------------------- |
| 规则规范可信化 | 2.1, 2.2 | 规则四层模型 |
| 2026 官方专业目录 | 2.3, 2.4 | 专业目录数据模型 + 真相源 |
| 系统 CLI 能力层 | 2.5, 2.6 | 统一命令面 + 智能体调度 |
| 整体规划/实现优化 | 2.7, 2.8 | 文档分层 + 真相源索引 |
后续设计见: `docs/DESIGN_RULES_TRUSTED_CLI_2026-06-16.md`

122
docs/RULES_SOURCE_OF_TRUTH.md Normal file
View File

@@ -0,0 +1,122 @@
# RULES_SOURCE_OF_TRUTH
最后更新: 2026-06-16
真相源: 本文件是"规则"维度的入口索引。
审计上下文: `docs/PROJECT_PLANNING_REALIGNMENT_2026-06-16.md`
设计上下文: `docs/DESIGN_RULES_TRUSTED_CLI_2026-06-16.md` §2
---
## 1. 范围
本文件收敛以下三类信息:
- 各省高考 2026 规则
- 全国通用规则
- 错误模式库
---
## 2. 当前真相源路径(Phase 1 之后)
| 类别 | 路径 | 格式 | 写入方式 |
| ------------ | ----------------------------------- | --------- | ---------------------------------- |
| 全国通用规则 | `rules/_truth/national.yaml` | YAML | 人工 PR + 自动校验 |
| 省级规则 | `rules/_truth/province/<prov>.yaml` | YAML | 人工 PR + 自动校验 |
| 规则证据原文 | `rules/_evidence/<prov>/<file>` | 抓取/摘录 | 人工收录 |
| 错误模式库 | `rules/errors/ERRORS.md` | Markdown | 人工维护(短期保留) |
| 跨省索引 | `rules/provinces.md` | Markdown | 由 `data/rules/loader.py` 自动生成 |
---
## 3. 数据模型最小契约
```python
Rule:
rule_id: str # e.g. HUNAN.max_volunteers
scope: "national" | "province"
province: str | None
year: int
title: str
description: str
severity: "fatal" | "critical" | "warning" | "info"
value: dict # 机读字段,如 {"max_volunteers": 45}
source_evidence_id: str # 指向 rules/_evidence/<id>.md
effective_date: date
last_verified_at: datetime
version: str
status: "active" | "draft" | "deprecated"
```
---
## 4. 当前覆盖矩阵(写入本文件时为准)
| 省份 | 模式 | 文档宣称 | checker 实际 | 备注 |
| ------ | ---------- | --------------- | -------------- | ------------------------------ |
| 湖南 | 院校专业组 | ✅ | ✅ | 详细规则见 province/hunan.yaml |
| 广东 | 院校专业组 | ✅ | ✅ | |
| 湖北 | 院校专业组 | ✅ | ✅ | |
| 安徽 | 院校专业组 | ✅ | ✅ | |
| 江西 | 院校专业组 | ✅ | ✅ | |
| 甘肃 | 院校专业组 | ✅ | ✅ | |
| 黑龙江 | 院校专业组 | ✅ | ✅ | |
| 江苏 | 院校专业组 | ✅ | ✅ | |
| 福建 | 院校专业组 | ✅ | ✅ | |
| 广西 | 院校专业组 | ✅ | ✅ | |
| 北京 | 院校专业组 | ✅ | ✅ | |
| 上海 | 院校专业组 | ✅ | ✅ | |
| 天津 | 院校专业组 | ✅ | ✅ | |
| 海南 | 院校专业组 | ✅ | ✅ | |
| 浙江 | 专业+学校 | ✅ | ✅ | |
| 山东 | 专业+学校 | ✅ | ✅ | |
| 河北 | 专业+学校 | ✅ | ✅ | |
| 重庆 | 专业+学校 | ✅ | ✅ | |
| 辽宁 | 专业+学校 | ✅ | ✅ | |
| 贵州 | 专业+学校 | ✅ | ✅ | |
| 青海 | 专业+学校 | ✅ | ✅ | |
| 吉林 | 专业+学校 | ✅ | ✅ | |
| 新疆 | 传统 | ✅ | ✅ | |
| 西藏 | 传统 | ✅ | ✅ | |
| 河南 | 传统 | ✅ | ✅ | |
| 四川 | 传统 | ✅ | ✅ | |
| 云南 | 传统 | ✅ | ✅ | |
| 山西 | 传统 | ❌(SKILL.md 漏) | ✅(checker 有) | SKILL.md frontmatter 漂移待修 |
| 陕西 | — | ❌(SKILL.md 含) | ❌(checker 无) | checker 漂移待修 |
---
## 5. 文档漂移清单(已识别)
- D1: `rules/provinces.md` 描述 27 省,实际 28 省
- D2: `skills/gaokao-spec-checker/SKILL.md` 含山西漏陕西
- D3: 传统模式数 provinces.md 写 5,SKILL.md 写 6
- D4: 文档与代码都没有 source_evidence_id 链
---
## 6. Phase 1 必须收口
- 28 省全部有 `province/<prov>.yaml`
- 至少 1 条全国通用规则有 `national.yaml`
- 1-2 个规则有真实 `source_evidence_id` 链路(湖南优先)
- `gaokao-cli rules status` 可用
---
## 7. 验证脚本
```bash
# 规则台账
gaokao-cli rules status
# 单条规则解释
gaokao-cli rules explain --province 湖南 --rule-id HUNAN.max_volunteers
# 一致性自检
python3 -m data.rules.cli verify
```
---
**下一阶段**: Phase 1 实施,见 `docs/DESIGN_RULES_TRUSTED_CLI_2026-06-16.md` §11