niuniu/gaokao-volunteer-system

Fork 0

Files

Hermes Agent ae4835eeab

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

feat(rules): add phase1 truth source loader and rules cli

2026-06-16 18:14:41 +08:00

32 KiB

Raw Blame History

DESIGN_RULES_TRUSTED_CLI_2026-06-16

最后更新: 2026-06-16 真相源: 本设计是 docs/PROJECT_PLANNING_REALIGNMENT_2026-06-16.md 审计结果的具体设计落点。目标: 在不破坏现有 v2.1 已完成能力的前提下，把"规则可信化 / 专业目录可信化 / CLI 能力面 / 智能体调度 / 整体整合"一次性收敛到下一阶段实施级方案。

0. 阅读顺序

本节
§1 总目标与边界
§2 规则规范可信化架构
§3 统一审计引擎
§4 专业目录数据真相源
§5 Application Services 层
§6 统一 CLI 命令面
§7 智能体能力调度层
§8 整体项目整合
§9 与现有 PRD/ROADMAP/规划的对接
§10 风险与验证
§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 数据模型

# 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

不破坏现有 27 省的覆盖。迁移后:

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. 三仓推送

每月一次"规则刷新日"运行:

python3 -m data.rules.cli status

返回每个省的:

规则数量
最近验证时间
是否有未填 source_evidence_id
是否存在 active 状态但 last_verified_at > 90 天的规则

3. 统一审计引擎

3.1 接口设计

# 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 输入模型

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 引擎内部分层

Schema 校验 — 必填字段、字段类型
全国通用规则检查 — 例如:
- 平行志愿原则是否被违反
- "一次投档"原则在文本中是否被描述正确
省级规则检查 — 例如:
- 志愿数是否在 max_volunteers 范围内
- 是否使用了正确的"模式"术语
数据完整性检查 — 例如:
- 每个 item 必须有 reference_rank 或明确标注待官方公布
- 院校代码与名称是否对得上
风险评估 — 不在规则层,而是规则层之上,见 §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 教育部本科专业目录

# 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 高校招生专业(招生章程)

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 关键接口草案

# 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: ...

# 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: ...

# 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: ...

# 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 不可恢复(权限/数据完整性)

错误输出统一格式:

{"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 能力注册表

# 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 必须有:

可运行入口: gaokao-cli <group> --help 出树
可执行 smoke: gaokao-cli audit run --province 湖南 --plan fixtures/sample.json 返回结构化结果
可回归测试: pytest gaokato/ data/rules/ data/majors_catalog/ -q 全绿
可读源码: 服务层每个函数都有 docstring + 错误码
可被智能体调用: hermes skill gaokato_capabilities.json 列出全部 capability
可被后台调用: 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 — 规则真相源化(无破坏,低风险)

目标: 把"规则硬编码"升级为"可追溯规则"

任务:

落 rules/_truth/national.yaml + province/<prov>.yaml(27 省)
写迁移脚本 scripts/migrate_province_rules_to_truth.py
落 data/rules/loader.py + audit_engine.py 最小可用版
保留 scripts/gaokao-checker 与 SKILL 行为
加测试: data/rules/tests/test_loader.py + test_audit_engine.py

验收:

gaokao-cli rules status 可用
gaokao-cli audit run 行为与旧 gaokao-checker 一致
27 省规则 100% 迁移

Phase 2 — 统一审计引擎最小可用

任务:

gaokato/services/audit.py 抽核心
gaokato/transport/cli.py 注册 gaokao-cli audit run/explain/list-rules
skills/gaokao-counselor-long 内部改为调 service(或 CLI)
旧 skill 行为不变

验收:

gaokao-cli audit run + JSON 输出
hermes skill 仍能调起同一能力

Phase 3 — 专业目录接入(MVP)

任务:

落 data/majors_catalog/national/2024.json(教育部最新)
落 5-10 所重点高校 2025/2026 招生目录
gaokato/services/majors.py
gaokato.services.audit 接入 major_validation
gaokao-cli majors lookup/validate/list-changes

验收:

任意 plan 跑 gaokao-cli majors validate 可标出已撤销/新设专业
至少 1 个 e2e:大厂AI方案 → audit run → major validation 命中

Phase 4 — 统一 CLI 命令面

任务:

落 gaokato/transport/cli.py 全部子命令
保留旧脚本 alias + deprecation warning
gaokao-cli doctor 自检
gaokato/capabilities/registry.py 全集

验收:

全部 25+ 子命令可用
gaokao-cli --help 树清晰
所有 --json 行为一致

Phase 5 — 智能体调度与 admin 整合

任务:

admin/routes/* 委托 gaokato.services.*
hermes skill gaokato_capabilities.json 导出
至少 3 个 skill 角色(客服/运营/顾问)绑定 capability
端到端跑通

验收:

客服智能体可"读方案 → 调 audit → 查 order → 出报告"
运营智能体可"创建订单 → 改状态 → 出报告"
顾问智能体可"生成方案 → 校验 → 出报告"

Phase 6 — 文档/真相源索引收口

任务:

落 RULES_SOURCE_OF_TRUTH.md MAJOR_DATA_SOURCE_OF_TRUTH.md CLI_API_MAPPING.md
CURRENT_STATE.md 更新指向本设计
PROJECT_PLANNING_REALIGNMENT_2026-06-16.md 标记已落地

验收:

任何入口文档(CURRENT_STATE / README / PROJECT_PLANNING_REALIGNMENT)不再有冲突

12. 一次性完成顺序

主代理按以下顺序继续执行(用户已批准继续):

本设计落盘 ✅ (本文件)
审计落盘 ✅ (PROJECT_PLANNING_REALIGNMENT_2026-06-16.md)
三处真相源文档 → RULES_SOURCE_OF_TRUTH.md + MAJOR_DATA_SOURCE_OF_TRUTH.md + CLI_API_MAPPING.md
整体规划对接 → 提交一次 docs-only commit + 三仓推送
回主对话 → 报告本轮完成

下一轮(用户再"继续"):

Phase 1 实施
TDD 走 RED-GREEN
仍然按"生产级 + 三仓同步"标准

版本: v1.0
最后更新: 2026-06-16
对应规划: docs/PROJECT_PLANNING_REALIGNMENT_2026-06-16.md
后续执行: 等待用户"继续"进入 Phase 1

32 KiB Raw Blame History

DESIGN_RULES_TRUSTED_CLI_2026-06-16

0. 阅读顺序

1. 总目标与边界

1.1 解决什么

1.2 不解决什么

1.3 关键设计原则

2. 规则规范可信化架构

2.1 四层模型

2.2 关键目录与文件

2.3 数据模型

2.4 与现有 PROVINCE_RULES 的迁移

2.5 2026 规则更新流程

3. 统一审计引擎

3.1 接口设计

3.2 输入模型

3.3 引擎内部分层

3.4 与 gaokao-spec-checker / gaokao-audit 的关系

4. 专业目录数据真相源

4.1 必要性

4.2 数据模型(两层)

L1 教育部本科专业目录

L2 高校招生专业(招生章程)

4.3 数据接入

4.3.1 教育部本科专业目录(国家级)

4.3.2 高校招生专业(校级)

4.4 在审计引擎里的使用

4.5 风险管理

5. Application Services 层

5.1 为什么需要

5.2 设计

5.3 与现有代码关系

5.4 关键接口草案

5.5 日志与权限

6. 统一 CLI 命令面

6.1 命令入口

6.2 公共约定

6.3 命令集详细

6.4 实现位置

6.5 安装与发现

7. 智能体能力调度层

7.1 形态

7.2 能力注册表

7.3 与 Hermes skill 的关系

7.4 与 admin HTTP 的关系

7.5 与真实"志愿服务智能体"的关系

8. 整体项目整合

8.1 真相源分层

8.2 目录结构(终态)

8.3 不会破坏的边界

8.4 数据流总图

9. 与现有 PRD / ROADMAP / 规划的对接

9.1 PRD 对接

9.2 ROADMAP 对接

9.3 IMPLEMENTATION_PLAN_v2 对接

9.4 本设计与原 4 个优化目标对齐

10. 风险与验证

10.1 关键风险

10.2 真实验收标准

10.3 阶段验收检查点

11. 实施阶段

Phase 1 — 规则真相源化(无破坏,低风险)

Phase 2 — 统一审计引擎最小可用

Phase 3 — 专业目录接入(MVP)

Phase 4 — 统一 CLI 命令面

Phase 5 — 智能体调度与 admin 整合

Phase 6 — 文档/真相源索引收口

12. 一次性完成顺序

32 KiB

Raw Blame History

3.4 与 `gaokao-spec-checker` / `gaokao-audit` 的关系