niuniu/gaokao-volunteer-system
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
56cf2c3ee2a3c88d4d38269fa138423b08056df3
gaokao-volunteer-system/docs/CLI_API_MAPPING.md
Hermes a57522b11e
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 channel/delivery/retention/backup to gaokao-cli (phase 3 batch 3) 
Round 3 of the unified gaokao-cli rollout. Adds four more passthrough
markers so the unified entry point can drive the remaining ops scripts
without bringing new data models into data/.

- data/cli_compat_delivery_dispatch.py: runpy shim for
  scripts/gaokao-delivery-dispatch.py (DispatchDeliveryEvents).
- data/cli_compat_delivery_watchdog.py: runpy shim for
  scripts/gaokao-delivery-watchdog.py (WatchdogDeliveryEvents).
- data/cli_compat_retention_cleanup.py: runpy shim for
  scripts/gaokao-retention-cleanup.py (OrderRetentionCleanup).
- data/cli_compat_channel_fallback.py: forwarder for
  data.channel_sync.monitor.main (CheckChannelHealth /
  ManualTemplate).
- data/cli_compat_backup.py: subprocess wrapper that dispatches
  scripts/backup_snapshot.sh and scripts/backup_verify.sh.
- data/rules/cli.py main(): routes gaokao-cli {channel, delivery
  {dispatch,watchdog}, retention, backup {snapshot,verify}} to the
  shims; rejects unknown subcommands with a structured error.
- docs/CLI_API_MAPPING.md §2.1: now lists 12 top-level commands with
  their real subcommands and fallback paths.
- tests/test_cli_doctor_phase3.py: +6 tests covering channel
  delegation, delivery dispatch / unknown-subcommand, retention
  routing, backup shell routing, and backup unknown-subcommand
  rejection.

Verification:
- focused: 12 passed
- dev-verify full gate: all checks passed (ruff / mypy / coverage /
  pytest / benchmark)
2026-06-17 22:18:57 +08:00

152 lines
9.8 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` |
| `channel` | `check [--flags]` / `manual-template [--flags]` | 复用 `data/channel_sync/monitor.py` |
| `delivery` | `dispatch [--channel --limit]` / `watchdog [--channel --limit]` | 复用 `scripts/gaokao-delivery-{dispatch,watchdog}.py` |
| `retention` | `cleanup [--flags]`（无子命令，flags 由脚本内部解析） | 复用 `data/orders/retention_cleanup.py` |
| `backup` | `snapshot` / `verify`（调用 `scripts/backup_*.sh`） | 复用 `scripts/backup_*.sh` |
| `doctor` | `--json` 自检 rules / majors / majors_verify | `data/rules/cli.py`（复用 `RuleLoader` + `MajorsCatalogLoader`） |
---
## 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