niuniu/gaokao-volunteer-system
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
77cde03f1db425e77d754a9880d8f1da33523493
gaokao-volunteer-system/docs/CLI_API_MAPPING.md
Hermes 77cde03f1d
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
feat(cli): delegate share/payment-doctor to gaokao-cli (phase 3 batch 2) 
Builds on 7d31d75 (order delegation + doctor self-check). The unified
gaokao-cli now also wraps the legacy shortlink and payment-doctor
scripts through thin runpy-based compat shims.

- data/cli_compat_gaokao_shortlink.py: loads scripts/gaokao-shortlink
  via runpy.run_path; preserves argv routing for native subcommands
  (create/list/resolve/revoke/...).
- data/cli_compat_payment_doctor.py: loads scripts/payment_provider_doctor.py;
  strips the leading 'doctor' marker (the legacy script takes no args)
  and rejects unrecognised tokens so silent flag drops are surfaced.
- data/rules/cli.py main(): routes gaokao-cli {share,payment} <...>
  to the compat shims; gaokao-cli order remains delegated to
  data.orders.cli.
- docs/CLI_API_MAPPING.md §2.1: records the actually-shipped command
  surface (rules / majors / majors school-* / audit / order / share /
  payment doctor / doctor) so the design doc matches runtime.
- tests/test_cli_doctor_phase3.py: covers share delegation, payment
  doctor rejection, and the passthrough help flow.

Verification:
- focused: 6 passed
- dev-verify full gate: all checks passed (ruff / mypy / coverage / pytest / benchmark)
2026-06-17 19:16:44 +08:00

150 lines
9.3 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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` | (新增) |
### 2.1 已落地命令清单（2026-06-17 snapshot）
当前 `gaokao-cli` 真实可用的子命令：
| 顶层命令 | 子命令 | 落点 |
| --------- | --------------------------------------------------------------------- | ---------------------------------------------------------------- |
| `rules` | `status` / `verify` | `data/rules/cli.py` `RuleLoader` |
| `majors` | `status` / `lookup <name>` / `verify` / `changes` | `data/majors_catalog/cli.py` `MajorsCatalogLoader` |
| `majors` | `school-status --year <y>` / `school-verify --year <y>` | `data/majors_catalog/cli.py` |
| `audit` | `run --province <p> --plan <json>` | `data/rules/audit_engine.py` `AuditEngine` |
| `order` | 委派到 `data/orders/cli.py` 子命令（`create/list/show/...`） | 复用 `data/orders/cli.py` |
| `share` | 委派到 `scripts/gaokao-shortlink` 子命令（`create/list/resolve/...`） | 复用 `data/cli_compat_gaokao_shortlink.py` |
| `payment` | `doctor`（委派到 `scripts/payment_provider_doctor.py`） | 复用 `data/cli_compat_payment_doctor.py` |
| `doctor` | `--json` 自检 rules / majors / majors_verify | `data/rules/cli.py`（复用 `RuleLoader` + `MajorsCatalogLoader`） |
**未启动（占位）**：`delivery` / `retention` / `backup` / `channel` 暂不并入 `gaokao-cli`，保留各自独立 `scripts/gaokao-*` 入口。
---
## 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
Reference in New Issue View Git Blame Copy Permalink