四种方式用 boss，先搞清楚该走哪条

A · 体验接口 已上线 免 token

首页的在线体验台走的就是这组接口。服务端用自己的模型代跑完整流程，你只管发议题、取报告。

# 1) 探活
$ curl -s https://svc.apex.fan/v1/healthz
{"ok":true,"service":"boss-svc","schema_version":"1.0"}

# 2) 起一单 (topic 与 review_doc 至少给一个)
$ curl -s https://svc.apex.fan/v1/demo/start \
    -H "Content-Type: application/json" \
    -d '{"topic":"评估 X 产品线明年是否扩张"}'
{"run_id":"run_...","judges_total":4,"judges":[...]}

# 3) 轮询进度 (进度只存内存, 过期会 404 — 重新发起即可)
$ curl -s https://svc.apex.fan/v1/demo/status/run_xxxxx

# 4) 取报告 · 三种格式任选
$ curl -sL https://svc.apex.fan/v1/demo/report/run_xxxxx/md   -o report.md
$ curl -sL https://svc.apex.fan/v1/demo/report/run_xxxxx/html -o report.html
$ curl -sL https://svc.apex.fan/v1/demo/report/run_xxxxx/pdf  -o report.pdf

# 5) 浏览公开判例库 (别人跑过的, 保留 7 天)
$ curl -s "https://svc.apex.fan/v1/demo/gallery?limit=5"
$ curl -s https://svc.apex.fan/v1/demo/gallery/run_xxxxx

以上为默认值，服务端可调；线上实际值以部署配置为准。

• 提交内容会公开 7 天。议题与生成的报告会进公开判例库，其他访客可浏览与下载。严禁提交机密内容。
• 体验接口不连知识库——评委 doctrine 照常加载（那是方法论本体），但不会检索你的组织数据。
• prompt 包不出网：与路径 B 不同，体验接口把全套 prompt 留在服务端，你只拿最终报告。

B · HTTP 三连（自带模型） 已上线

boss 出题与纪律，你的模型出判断，boss 再做确定性聚合。适合正式集成——模型选型和费用都在你手里。

# 环境
$ export BOSS=https://svc.apex.fan
$ export TOKEN=***          # 值来自 BOSS_SVC_TOKEN, 向服务管理员申请
$ AUTH=(-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json")

# 1) prepare — 起 run, 拿冻结 context + 全套 prompt 包
$ curl -s $BOSS/v1/prepare "${AUTH[@]}" \
    -d '{"scene":"default","topic":"评估 X 产品线明年是否扩张"}'

# 2) 你的模型按 prompt 包跑 synthesis 与每位评委, 然后回传
$ curl -s $BOSS/v1/submit "${AUTH[@]}" \
    -d '{"run_id":"run_...","reviews":[{"judge":"tian","review_md":"---\n..."}]}'

# 3) render — 确定性聚合出富报告 (可重复调用)
$ curl -s $BOSS/v1/render "${AUTH[@]}" -d '{"run_id":"run_..."}'

• run TTL 24 小时，过期物理删除，之后 submit / render 会 404。
• submit 全批原子：任一份 review 不合格，整批 422 拒绝并返回逐条明细。维度评委必填 adversarial_view 三字段（if_thesis_wrong / contrary_signal_observed / base_rate_warning），anchor 评委不写。
• prompt 模板里的哨兵 <<SYNTHESIS_MD>> / <<REVIEWS_MD>> 必须用字符串替换，不要用模板引擎（正文含大括号会炸）。
• 浏览器直连需要你的域名在服务端 CORS 白名单里（精确匹配，不支持通配）；curl 与服务端调用不受影响。
• 完整契约与字段说明见 MCP 接入指南 · 回传契约，两条路径共用同一套契约。

懒得自己编排？这两个脚本把上面整套压成一条命令

「prepare → 跑 synthesis → 逐评委打分 → submit → merge → render」全帮你串好， 模型调用留在你自己进程里。拷走随便改，没有黑盒。

# 下载并跑 (Python 版)
$ curl -O https://www.apex.fan/examples/boss_byom.py
$ export BOSS_SVC_TOKEN=***          # 服务 token
$ export ANTHROPIC_API_KEY=***      # 或 OPENAI_API_KEY

$ python3 boss_byom.py "评估 X 产品线明年是否扩张" -o report.md
① prepare …
   run_id=run_... · panel=default · 4 位评委
② synthesis …
③ 4 位评委打分 (并发 3) …
   ✓ tian (anchor)
   ✓ industry-trend (dimension)
   …
④ submit …
⑤ merge …
⑥ render …
✓ 报告已写入 report.md

# 评议一份现成文档
$ python3 boss_byom.py --doc plan.md -o review.md

# Bash 版: 报告走 stdout, 进度走 stderr, 所以重定向只拿到报告
$ curl -O https://www.apex.fan/examples/boss-byom.sh && chmod +x boss-byom.sh
$ ./boss-byom.sh "评估 X 产品线明年是否扩张" > report.md

• 两个脚本都只用环境变量读凭证，不写配置文件、不落盘 token。
• 换模型供应商只需改 call_model() 一个函数——脚本其余部分与模型无关。
• 常见错误码（401 / 404 / 422 / 502 / 503）都当场给提示，不用回来翻文档。
• 脚本按当前契约写死了哨兵替换与字段名。契约若升级，以本页与 /docs 为准，脚本可能需要同步——它们是示例，不是受支持的产品。

C · MCP 接入（Claude Code） 已上线

与路径 B 能力等价，但你不用手写调用——配好之后用自然语言驱动，Claude 自己跑完整闭环。

// .mcp.json — 放在项目根目录, 重启会话生效
{
  "mcpServers": {
    "boss": { "type": "http", "url": "https://<your-endpoint>/mcp" }
  }
}

然后在对话里直接说：

用 boss_prepare 起一个评审: scene 用 default, 议题是"评估 X 产品线明年是否扩张"。
拿到 prompt 包后你自己跑 synthesis 和每位评委, 然后 submit 回去, 最后 render 出报告给我。

• 经反向代理接入时，服务端必须把对外域名加进 BOSS_SVC_ALLOWED_HOSTS。MCP SDK 的 DNS-rebinding 防护默认只认 localhost，隧道进来的请求 Host 是公网域名，不加白名单会返回 421 Invalid Host header。本机直连调试用 http://127.0.0.1:8431/mcp。
• 裸 curl 打 /mcp 会得到 406，这是正常的——MCP 要求客户端接受 text/event-stream。能收到 406 说明请求已穿过安全层。
• 详细工作流、契约与 FAQ 见 MCP 接入指南。

D · 本地 CLI（自托管） 仅本地

唯一能连完整知识库、用全部参数、跑三套导出的方式。没有 pip 包，直接跑仓库里的脚本。

# 安装
$ git clone https://github.com/zhanglunet/boss-vault.git && cd boss-vault
$ make install                                # 依赖 + git hook + 建目录
$ bash scripts/install_tian_skill.sh          # 把 /boss 装进 Claude Code
$ cp .env.example .env.local && vi .env.local # 填模型 key
$ set -a; source .env.local; set +a            # ⚠ .env 不会自动加载, 必须手动 source
$ make smoke                                  # 1 分钟自检

# 跑一单
$ python3 scripts/run_pipeline_local.py "议题" --brand <slug>

# 评议一份现成方案文档
$ python3 scripts/run_pipeline_local.py --review docs/plan.md

# 在 Claude Code 里用 slash command
> /boss 评估 X 产品线明年是否扩张

• .env 不会自动加载。脚本里没有 dotenv 调用，必须自己 set -a; source .env; set +a 或逐个 export，否则模型调用会因为缺 key 而失败。
• /boss 的参数和 Python CLI 不是同一套。--quick / --refresh / --focus 等只被 slash command 理解，直接传给 run_pipeline_local.py 会报 unrecognized arguments。
• 需要 Python 3.11+。知识库不是硬依赖——没有编译好的知识库时会退化成全文检索。
• 完整参数表见 手册 · CLI 参考；自托管说明见 产品页 · 上手。