# 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