boss-skills v1 API · 任意 LLM runtime 接入指南

v0.3.0 起 boss-skills 升级为 HTTP API product: FastAPI + Dockerfile + OpenAPI 3.0 spec. 任何 HTTP client (curl / Python / Hermes / OpenClaw / 自写 runtime) 都能调用 5 个 sync endpoint。Hermes runtime 从未实现 (audit 2026-05-28 confirmed), HTTP API 是跨语言 LCD (lowest common denominator) 解。详见 ADR-004.

v0.3.0-rc · 2026-05-28
port · 8421
API ver · v1 (sync)
spec · OpenAPI 3.0

▮ HERO · 任意 host 30 秒起步

# 1. 装 server (本地 / Docker / 云三选一) $ docker build -t boss-vault:v0.3.0 . $ docker run -d -p 8421:8421 -e ANTHROPIC_API_KEY=$KEY boss-vault:v0.3.0 # 2. 验证 (curl 任何 host 都能用) $ curl localhost:8421/v1/healthz {"status":"ok","timestamp":"2026-05-28T04:29:47Z"} # 3. 任意 runtime 接入: HTTP client = boss-skills client $ curl localhost:8421/v1/panels | jq '.panels[0]' {"name":"default","anchor_slug":"tian","judges":[7 evaluators]}

JUMP TO §1 · 5 endpoint §2 · 4 client §3 · 3 deployment §4 · v1 vs v2 §5 · Cheat sheet

SECTION 1 5 个 sync endpoint 点卡看 example + response shape

SECTION 2 4 种 LLM runtime 接入示例点 tab 切换 client 代码

完整 cookbook (含错误处理 / auth 提示 / v2 路线): docs/api/integration-cookbook.md · OpenAPI 3.0 spec: docs/api/openapi.json

SECTION 3 3 种 deployment 形态对比 D1/D2/D3 + 新 API 的位置

形态	装机	always-on	有 v1 HTTP API?	infra 成本
D1 · Local Claude Code	5 min · symlink	❌ 终端在线时	⚠️ 不内置, 但可手动 uvicorn boss_server:app 起本地 HTTP	$0
D2 · Self-host Hermes	1-2 小时 · 云 VM	✅ systemd + nginx	★ 真实物 · systemd ExecStart 改为 uvicorn boss_server (ADR-004)	$10-30/月
D3 · GitHub Actions	15 min · push + secret	⚠️ schedule (5min cron)	❌ 仅 attribution cron, 不暴露 HTTP API	$0
★ Docker container	30 sec · docker run	✅ daemon	★ 包内嵌 · `EXPOSE 8421` + healthcheck	$0 (本地) / 云 host 价

关键洞察 (ADR-004 §6): v1 HTTP API 是逻辑产品边界, 不是 repo 边界。"任意 runtime 调 boss-skills" 在单 repo 内就实现了, 不必拆 boss-skills + boss-vault-<slug> 两 repo (C 档推迟)。

SECTION 4 v1 vs v2 路线为什么 v1 不接完整 judgement

v1 sync metadata + attribution (已 ship)

2026-05-28 · ADR-004 落地

GET /v1/healthz · liveness
GET /v1/version · skill + git + vault 版本
GET /v1/panels · 列 panels + 评委 + anchor_slug
GET /v1/anchors · 列 anchors + perspective 状态
POST /v1/attribution/check · 触发 30/90/365 (同步 ≤ 30s)

覆盖场景: 外部 runtime query boss-vault 配置 + 跑 attribution cron 自动化. 不接完整 Phase 0-5 流水线 (45 min sync 不可行)。

v2 async judgement pipeline (推迟)

触发后启动 · 见右下方 signal

POST /v2/judgement · 异步触发, 返回 job_id
GET /v2/judgement/{job_id} · 查状态 (pending / running / done / failed)
GET /v2/judgement/{job_id}/result · 拿 report.md + reviews
Webhook callback · 你的 runtime 提供 URL, boss-skills 完成后 POST 通知
in-memory job queue → Redis-backed (生产化)

触发信号 (ADR-004 §2.4): v1 用户反馈稳定 ≥ 30 天 / 外部 runtime 明确需求"HTTP 触发完整 judgement" / in-memory queue 不够。

SECTION 5 Cheat sheet · 一屏速查可拷贝走

# 装 server (任意 host 30 秒)

$ docker build -t boss-vault:v0.3.0 .

$ docker run -d -p 8421:8421 -e ANTHROPIC_API_KEY=$KEY boss-vault:v0.3.0

# 5 sync endpoint

$ curl localhost:8421/v1/healthz # liveness

$ curl localhost:8421/v1/version # skill + git + vault 版本

$ curl localhost:8421/v1/panels # 列 panels + 评委 + anchor_slug

$ curl localhost:8421/v1/anchors # 列 anchors + perspective 状态

$ curl -X POST localhost:8421/v1/attribution/check \

-H "Content-Type: application/json" \

-d '{"dry_run": true}' # 触发 30/90/365

# Interactive docs

# Swagger UI → http://localhost:8421/docs

# ReDoc → http://localhost:8421/redoc

# OpenAPI 3.0 JSON → http://localhost:8421/v1/openapi.json

# 本地不 docker · 直跑 uvicorn (开发模式 reload)

$ pip install -r requirements.txt

$ uvicorn scripts.boss_server:app --reload --port 8421