ADR-004 · boss-skills as a product · HTTP API + cloud deploy
| 字段 | 值 |
|---|---|
| 状态 | accepted · 2026-05-28 · v1 API artifacts 已就位 (本 PR) |
| 日期 | 2026-05-28 |
| 决策者 | CTO + 项目主理 |
| 承接 | ADR-003 (deployment 三形态) · docs/api/integration-cookbook.md |
| 相关 | scripts/boss_server.py · Dockerfile · docs/api/openapi.json |
⚠️ 部分条款已被推翻 (2026-07-25 补注): §3.2 的 「无 auth」tradeoff 自 v0.6 R4 起作废 —— HTTP API 已改为 Bearer token + fail-close(未配
BOSS_API_TOKEN时除/v1/healthz外一律 503)。 本 ADR 其余部分(positioning / HTTP as LCD / v1-v2 分期)仍然有效。 接口现状以运行中服务的/docs与 integration-cookbook §5 为准。
1. Context
1.1 · 用户提出的反思 (2026-05-28)
"实际的需求是做成一个 boss skills, 这样不管 hermes, 还是 openclaw 类似的都能够调用"
这是对 ADR-001/002/003 之后的下一层 positioning shift。之前的 ADR:
| ADR | 解决了什么 |
|---|---|
| 001 | boss-skills 通用流水线 + per-anchor 数据解耦 (架构演进路径) |
| 002 | anchors/<slug>/ 子目录物理落地 (B 档实施) |
| 003 | 上云不再是 V0 验收硬指标, deployment 三形态可选 |
但 ADR-001/002/003 都假设 boss-skills 是自用工具。用户的新诉求是把它做成可被外部 runtime 调用的产品。
1.2 · Reality check (audit 2026-05-28)
$ git ls-files | xargs grep -l "import hermes\|from hermes"
(空)
$ grep "hermes" requirements.txt
(空)Hermes runtime 在 vault 里只是设计概念, 没有实际 Python 实现。python -m hermes 跑不了。templates/boss-hermes.service.example 里的 ExecStart=python -m hermes start 是占位。
意味着: 当前 boss-skills 能从 Claude Code (D1) / GitHub Actions (D3) / run_pipeline_local.py CLI 调用, 但 "通过任意外部 runtime 调用" 这条路径不通, 因为没有 inter-process 协议。
1.3 · 三种 inter-process 接口形态
| 形态 | 谁能调 | 跨语言 | 装机成本 |
|---|---|---|---|
| MCP Server | 支持 MCP 的 client (Claude Desktop / Cursor / 部分新 runtime) | ⚠️ 仅 MCP-aware | pip + mcp.json config |
| HTTP REST API | 任何 HTTP client | ✅ 完全跨语言 | 启动 server + 暴露端口 |
| Python pip package | 任何 Python 程序 | ⚠️ 仅 Python | pip install + import |
选 HTTP REST API: 跨语言, Hermes / OpenClaw 不论用什么实现都能调; 现有 CLI 包一层即可, 重构最小; 是 D2 自托管 Hermes 部署的天然实物。
2. Decision
2.1 · v1 轻量 API (本 PR 落地)
5 个 sync endpoint, 不接完整 Phase 0-5 流水线 (那是 v2):
| Method | Path | Tag | 用途 | 实测响应时间 |
|---|---|---|---|---|
| GET | /v1/healthz | meta | Liveness probe | < 50ms |
| GET | /v1/version | meta | skill name / version / git commit | < 100ms |
| GET | /v1/panels | config | 列 panels/*.yaml + 评委 (含 anchor_slug) | < 200ms |
| GET | /v1/anchors | config | 列 anchors/*/ + perspective skill 状态 | < 200ms |
| POST | /v1/attribution/check | action | 触发 attribution_check.py run, 同步返回 summary | 1-3 s |
实现: scripts/boss_server.py (FastAPI app · ~ 280 行 · 单文件)
OpenAPI 3.0 spec auto-generated: /v1/openapi.json (FastAPI built-in) · 静态版 docs/api/openapi.json
2.2 · 容器化 (本 PR 落地)
Dockerfile · python:3.11-slim 基础镜像 · 任何 docker/k8s host 一键跑:
docker build -t boss-vault:v0.3.0 .
docker run -d -p 8421:8421 -e ANTHROPIC_API_KEY=$X boss-vault:v0.3.0
curl http://localhost:8421/v1/healthz.dockerignore 阻止 confidential 数据 (anchors/<slug>/raw/ / cases/C-* / reports/) 入 image。仅 _demo-* 入 image。
2.3 · Cloud deployment (推迟实物执行, 但 artifacts 就位)
templates/boss-hermes.service.example + templates/nginx-boss-hermes.conf.example 之前 (ADR-003 §D2) 已就位 · __VAULT_ROOT__ / __USER__ / __DOMAIN__ 占位符替换即可上云。
实际云 deploy 推迟到用户提供 SSH 后由 user 跑 3 条命令完成。
2.4 · v2 推迟 (本 PR 不做)
POST /v2/judgement 异步触发完整 Phase 0-5 (45 min) · GET /v2/judgement/{job_id} 查状态 · Webhook callback · job queue。
v2 触发信号:
- v1 实际使用 ≥ 30 天, 用户反馈接口稳定
- 外部 runtime 明确需要 "HTTP 触发完整 judgement"
- in-memory job queue 不够 → 需要 Redis / persistent storage
3. Consequences
3.1 · 收益
- 跨语言可调: 任何 HTTP client (curl / Python / Go / 自写 runtime) 都能用 boss-skills
- boss-skills 升级为 product: 不再绑死 Claude Code, 任何 LLM Agent runtime 可接
- D2 部署有实物:
templates/boss-hermes.service.example的ExecStart改成uvicorn boss_server:app即真可跑 (不再是 placeholder) - OpenAPI 自动生成: FastAPI 内置 Swagger / ReDoc,
/docs/redoc开盒即用, 客户端可 codegen - multi-anchor 价值真兑现: 外部用户用自己的 anchor data + 调 boss-skills HTTP API, multi-anchor 解耦从架构走到接口
3.2 · 接受的 tradeoff
- v1 不接完整 judgement (45 min sync 不可行, 推迟到 v2 async)
无 auth (内网 / 本地 / LAN OK, 公网部署需手动加 nginx auth, 见 cookbook §5)→ 已推翻 (v0.6 R4): 改为 Bearer token + fail-close, 不再依赖反代兜底。见 cookbook §5。- stub fetcher 仍是 stub (attribution_check.py V0 stub 不接真 marsdata/WebSearch, V1 接入再升级)
- Python 单 worker (uvicorn 默认 1 worker, 并发上限 ~ 10 req/s; 生产需
--workers N)
3.3 · 不变的承诺
anchors/<slug>/raw/数据 gitignored, 也不入 docker image (.dockerignore 控)- redact_check fail-close 跨形态生效 (CLI / GitHub Actions / Docker container)
- judgement quality 跨三 deployment 形态 (D1/D2/D3) + 跨 v1 HTTP API 一致
- 5 镜头 + adversarial_view + anchor_delta + 30/90/365 attribution 协议不变
4. Alternatives Considered
| 方案 | 为什么没选 |
|---|---|
| MCP Server 优先 | MCP 当前仅 Anthropic 生态支持 (Claude Desktop / Cursor); Hermes / OpenClaw 等不一定支持。HTTP 是 universal lowest common denominator |
| Python pip package | 限制只 Python 用户; 跨语言不行 |
| gRPC | 二进制协议, 调试不便; OpenAPI ecosystem 更成熟 |
| 直接做 v2 async judgement API | 复杂度高 (job queue + callback + state machine), 应先 ship v1 metadata API 让外部接入起步 |
| 不做 HTTP API, 仅写 cookbook 说"用 subprocess 调 CLI" | subprocess 调用是 hack, 不是 product interface; 调试 / 错误处理 / 可观测性都差 |
5. Migration Plan
5.1 · v1 落地 (本 PR)
- [x]
scripts/boss_server.pyFastAPI app (5 endpoint) - [x]
Dockerfile+.dockerignore - [x]
requirements.txt加 fastapi / uvicorn / pydantic - [x]
docs/api/openapi.json(auto-generated) - [x]
docs/api/integration-cookbook.md(4 种 client 示例) - [x] 本地 verify: uvicorn run + curl 5 endpoint 全 PASS
- [ ] Docker build + run verify (推迟到用户本地或云端 docker host)
5.2 · 文档同步 (本 PR)
- [x] ADR-004 (本文件)
- [x]
docs/adr/README.md索引更新 - [ ] PRD §4.1 加 D2 实物描述 (uvicorn 替换 placeholder)
- [ ]
docs/landing.html加 "v1 API" 段 - [ ]
docs/dev-log/2026-05-28_boss-skills-as-product.md - [ ]
docs/showcase/2026-05-28-boss-skills-api.html可视化页
5.3 · v2 (未来, 推迟)
见上 §2.4 触发信号。
6. 关键反共识立场
PRD v3.1 假设 boss-vault 是单租户工具, deployment 是 ops 决定。本 ADR 进一步:
boss-skills 是 product, 不是 vault 内部组件. 通用
skills/+ 通用 HTTP API + 通用部署模板组成产品包,anchors/<slug>/是用户自带数据。这与 ADR-001 §2.3 "C 档 boss-skills + boss-vault-<slug> 两 repo 分离" 同源, 但不必拆 repo就能兑现 — HTTP API 是逻辑边界, 不是 repo 边界。
C 档 (拆 repo) 推迟到必要时再做。HTTP API 在单 repo 内已经实现 product/data 分离。
7. Verify (本 PR 必过)
- [x] yaml syntax valid (config + panel)
- [x]
python3 scripts/boss_server.py(经 uvicorn) 启动成功 - [x] 5 endpoint 各 curl 一次, JSON 解析无错
- [x]
/v1/openapi.json返回有效 OpenAPI 3.0 spec (5 paths) - [x]
tests/ pytest: 211/212 passed (本 PR 不引入 regression) - [x]
redact_check3 个对外网站 PASS
ADR-004 · accepted · 2026-05-28 · 4 个 ADR 形成 v0.2.1+v0.3.0 时期 boss-vault 完整 positioning (架构 / 实施 / 部署 / 产品)