# 外部算法排产 Skill

> 对齐 [plan.md §6.8](../../plan.md)：可插拔 HTTP/本地算法，经 harness 门禁，写回柔性草稿。

## 契约

- **SchedulingProblem / SchedulingSolution**：`server/aps_domain/scheduling_dto.py`
  JSON Schema：`shared/schemas/scheduling_problem.schema.json`、`scheduling_solution.schema.json`，
  带 `schemaVersion` 版本化；`GET /api/skills/contracts` 可取。
  外部服务**不**接收内部 `flex*` / `world` 表结构。
- **manifest 扩展（M-D）**：`version` / `capabilities`（如 `["flex_schedule","due_promise"]`）/
  `ragScopes`（可访问的知识 kind/tags，供 `/api/rag/query` 鉴权）。旧配置加载时自动升级补默认值。

## 落盘（对标 Codex）

- **桌面**（`APS_MODE=desktop`）：`~/.aps/skills/<skill_id>/manifest.json`（+ 可选 `README.md`）
- **Web 开发默认**：`server/data/skills/<skill_id>/…`（或 `APS_HOME`）
- **测试兼容**：`APS_SKILLS_PATH` / `SkillRegistry(path=skills.json)` 仍支持单文件清单

详见 [desktop.md](./desktop.md)。

## 适配

- `SkillRegistry`（`server/agent_core/skills.py`）：目录扫描优先；默认内置 `algo.stub`（`local://stub`）。
- `ExternalEngine`（`server/engines/external_engine.py`）：`get_engine("EXTERNAL")` / `EXTERNAL:<skill_id>`。
  柔性主路径：`flex.schedule` + `engine=EXTERNAL` / `useExternal` / `skillId` → `run_external_flex`。
- Stub：`server/integrations/algo_skill_stub.py`（亦可 `python -m server.integrations.algo_skill_stub` 起 HTTP）。

## 门禁与口令

| 意图 | 权力 | 说明 |
| --- | --- | --- |
| `skill.list` / `skill.health` | P0 | 清单 / 健康检查 |
| `skill.register` / `skill.enable` | P2 | 改配置（确认卡） |
| `rag.query` | P0 | Skill 消费知识库（ragScopes 鉴权） |
| `flex.schedule`（外部） | P1 | 试排草稿；`evidenceRefs` 含 `skill:` + `run:` |

口令示例：用外部算法试排 · 查看已接入算法 · skill 健康检查 · 登记算法 skill id=… endpoint=…

## 管理台 API（M-D）

| 端点 | 用途 |
| --- | --- |
| `POST /api/skills/{id}/enable` | 启停 → P2 确认卡 |
| `GET /api/skills/{id}/history` | 健康探测历史（注册表存最近 20 次） |
| `GET /api/skills/{id}/audit` | 按 skill 过滤审计链 |
| `POST /api/skills/{id}/test` | 子进程跑该 skill 声明的黄金测试（`golden_tests`） |
| `GET /api/skills/contracts` | DTO JSON Schema 查看 |

## UI

设置 → **算法 Skill**：Codex 式双面板管理台（`apps/web/src/skills/SkillConsole.tsx`）——
左清单/右详情页签（概览/健康/契约/测试/日志），启停 Switch 与登记表单走 P2 确认卡。