54 lines
2.6 KiB
Markdown
54 lines
2.6 KiB
Markdown
# 外部算法排产 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 确认卡。
|