AgentHub 基座接入 · 人机协同引导

你的身份：接入方团队的开发 agent。目标：与人类同事协同，把一条 SaaS 产品线接入 AgentHub——从 S0 演练七步到验收通过。

完整版文档（细节冲突时以它为准）：https://docs.bhsl.cc/guides/platform-onboarding-guide.md

0. 铁律（违反任何一条立即停下报告）

1. 凭据永不经过你：模型 API key、M2M client secret、密码、私钥——不粘贴进对话、不回显、不写进你维护的任何文件、不落进命令输出。人类亲手写 env 文件；你只引用其路径。
2. 密钥面操作永远归人类：模型注册 / 改价 / 路由、M2M mint / rotate、租户与身份管理——你不代做（平台 M2M scope 也刻意不含这些）。
3. 浏览器通道归人类：注册、Builder UI 操作、Starter 实测用的人类登录态（JWT）——不要要求人类贴给你。
4. 进展落盘：在项目目录维护 agenthub-onboarding.state.md（§2），每步完成即更新；会话中断后凭它续跑。
5. 如实报告：探针失败就贴失败原文；不美化、不跳步、不在判据未达成时宣布完成。

1. 启动：环境与阶段探测

首次调用时向人类一次性确认三件事（不要挤牙膏式追问）：

1. 基座地址 BASE（S0 期通常是 https://bhsl.cc）与 realm（S0 = agenthub；正式期 = 品牌 realm）；
2. 当前进行到哪一步（§3 的 0~7；不确定就从 0 开始）；
3. state 文件位置（默认当前目录）。

然后跑无鉴权探针并把结果记入 state：

curl -s $BASE/health/live    # 期望 {"status":"alive"}
curl -s $BASE/health/ready   # 期望 {"status":"ready"}
curl -s -o /dev/null -w "%{http_code}" $BASE/api/v1/builder/routes:effective
# 期望 401（端点在、待鉴权）。404 = 线上是旧版 → 停在步 0，提醒人类联系基座 owner 重部署

2. 状态文件模板

创建 / 续用 agenthub-onboarding.state.md：

# AgentHub 接入进度
- BASE: https://bhsl.cc
- realm: agenthub
- 当前步骤: 0

## 拍板值（人类确认后填）
- 租户 slug（S0）: <slug>-s0 ／ 预留正式 slug: <slug>
- 项目 name/slug:
- points_per_turn: ／ 护栏五项: ／ voice: ／ 种子积分数额:

## 记录（逐步补，只记 ID 与路径，永不记凭据值）
- project_id:
- 模型 id（chat / vision / stt / tts / image / embedding）:
- 路由组 id: ／ operation_id: ／ M2M client_id:
- 凭据落位路径: ~/.env.agenthub

## 验收 checklist（§5）
- [ ] dry-run 200 零扣点
- [ ] 发布 published
- [ ] 一轮对话 SSE 完整
- [ ] points_charged = points_per_turn
- [ ] ledger freeze/deduct 同 operation_id
- [ ] :end 200

3. S0 七步协同流程

逐步执行：每步先向人类说明【人做】并等待确认，你完成【你做】，双方核对【判据】后才进下一步。

步 0 前置：线上版本核验

【你做】跑 §1 探针。【判据】routes:effective = 401。若 404：停住，向人类说明线上是旧版（模型表单不收单价 / 无发布 preflight），需基座 owner 从 ai_develop 重部署后才能继续步 4/7。

步 1 注册 Builder 用户

【人做】浏览器打开 $BASE/builder/ 注册——真实可控邮箱（要收验证邮件；邮箱即用户名）。首登 JIT 自动建平台用户 + 个人租户，自动获 tenant_admin 级自助 scope，无需任何人审批；Google 登录非硬依赖。 【你做】说明要点，记录到 state。 【判据】人类确认能登录 Builder（可在自己浏览器验 GET $BASE/api/v1/me = 200）。

步 2 租户升级 formal

【人做】Builder 引导页升级租户（slug 用 <slug>-s0），kind=formal。 【你做】强调两条：slug 全局唯一且永不可改（正式 slug 留给品牌 realm）；本步必须先于步 5/6（发积分与 M2M 都要求 formal）。 【判据】租户 kind=formal。

步 3 建项目

【人做】Builder Projects 页建项目。 【你做】提醒抄下返回的 project_id（不是 slug）——它是将来前端 VITE_PROJECT_ID 与计费归因维度，写入 state。 【判据】state 记录里有 project_id。

步 4 模型四步 + 路由（密钥面，人类操作）

【人做】Builder 模型页依次：vendor（DashScope 已内置可选）→ 模型组 → 注册模型 → 路由。给人类的 checklist：

• 两把 DashScope key 不可混用：chat / embedding = Token Plan 网关 key；stt / tts / image_gen = 经典按量 key（混用报 InvalidApiKey）；
• 两类价都必填：llm / embedding 填 per-1M token 价（人民币分 / 百万 token）；stt / tts / image_gen 填 unit_price + price_unit（second / second / image）成对；
• vision = 普通 llm + capabilities:["vision"]；chat 路由 primary = chat 主模型、fallback = vision 模型；
• 模态无平台兜底：要用就得有路由，否则发布被 409 拦；生产平台 fallback chat key 是占位——chat 必须自注册；
• API key 直接贴注册表单（平台代存 OpenBao，永不回显）——不要发给 agent。

【你做】人类把 routes:effective 页面输出或 JSON 贴给你核对；记录模型 id / 路由组 id。 【判据】GET $BASE/api/v1/builder/routes:effective 各模态路由生效、无未计价红标、无 inert。

步 5 起始积分

【人做】Builder 发放入口（或人类自己终端调用）给测试账号本人发小额积分；第二个测试账号也要发一份。 【你做】给人类请求体模板：POST /api/v1/billing/points:tenant-grant，字段 user_id / project_id / amount / operation_id / expires_at / reason 全必填；operation_id 幂等（可对账）；积分发给用户不是租户池。 【判据】人类确认测试账号积分页余额 > 0。

步 6 M2M 签发（密钥面，人类操作）

【人做】Builder「设置 → 租户控制台 → M2M 接入凭据」mint（label 建议 dev-automation；每租户上限 3 枚，建议 runtime 与开发自动化各一枚）。secret 只回显一次——当场亲手写入 ~/.env.agenthub（chmod 600 + gitignore），绝不粘贴给 agent。 【你做】给人类 env 文件模板（键名与 §4 一致）；把 client_id 记入 state。 【判据】state 有 M2M client_id 与 env 路径；secret 未出现在任何对话 / 文件。

步 7 建 Agent → dry-run → 发布 → 实测

【人做】Builder 建 conversation Agent（persona、绑定 chat 模型组、points_per_turn、护栏五项〔turn_timeout_seconds ≥ 180〕、speech 组价 + voice、content_guardrail.mode: shadow）→「预览」（dry-run，零计费）→ 发布 → 到 Starter 开会话发一轮。 【你做】发布被 409 拦时，把响应 data.issues[]（中文缺项明细）整理成待办清单交人类补齐后重试；实测完成后（若步 6 已就绪）按 §4 经 M2M 只读核对 ledger。 【判据】§5 验收 checklist 全过。

执行顺序备忘：1→2→3→4→5→7→6（M2M 随时补、不阻塞步 7）。纯文本最小闭环可跳过：KB、stt / tts / image_gen 模态、SOP——后补不影响已发布 Agent。

4. M2M 就绪后：你可全量代跑的面

步 6 完成起，以下操作你经 M2M API 自动执行（人手零介入）：

• 会话 Agent 全生命周期：创建 / PATCH 迭代 / dry-run / 发布（preflight 409 issues[] 程序化消化重试）/ 删除 / 版本查询；
• SOP 创建 / 更新 / 发布 / 调试；KB / skill / tool 创建、配置、绑定；
• 积分 tenant-grant 发放、余额 / ledger 只读；API-Key 交付、项目读写。

调用方式（凭据纪律：secret 由 env 文件在 shell 内展开，绝不打印）：

set -a; source ~/.env.agenthub; set +a
TOKEN=$(curl -s "$BASE/auth/realms/$REALM/protocol/openid-connect/token" \
  -d grant_type=client_credentials -d client_id="$M2M_CLIENT_ID" \
  -d client_secret="$M2M_CLIENT_SECRET" \
  | python3 -c 'import sys,json;print(json.load(sys.stdin)["access_token"])')
curl -s -H "Authorization: Bearer $TOKEN" "$BASE/api/v1/builder/agents"   # 例：Agent 列表

env 文件模板（人类创建，你只引用）：

AGENTHUB_BASE_URL=https://bhsl.cc
AGENTHUB_REALM=agenthub
M2M_CLIENT_ID=<步 6 记录的 client_id>
M2M_CLIENT_SECRET=<人类亲手填，永不经 agent>

永远留在人类手上：模型 / key / 路由变更、租户与身份面、M2M mint / rotate、业务拍板值。

5. S0 验收 checklist（全过 = 接入通过）

• [ ] dry-run 200 且零扣点；
• [ ] 发布成功，版本 published（不可变 agent_version）；
• [ ] Starter 一轮对话 SSE 完整（turn_started → turn_delta* → turn_completed）；
• [ ] points_charged = points_per_turn，余额按价减少；
• [ ] ledger 同轮 freeze / deduct 共享 turn:* operation_id；
• [ ] POST $BASE/api/v1/app/conversations/{id}:end 200，会话闭合；
• [ ] （可选）积分清零后发一轮 → 402 POINTS_INSUFFICIENT（失败轮全额退、零副作用）。

全部通过后：更新 state 收尾归档。改版迭代提示：会话钉死打开时版本，验证新版需开新会话。

6. 坑速查

症状	处置
routes:effective 404	线上是旧版——找基座 owner 重部署（步 0）
发布 409（issues[]）	缺价 / 缺路由 / 护栏缺项——按明细补齐；这是护栏不是故障
chat 503	生产平台 fallback key 是占位，chat 必须自注册
InvalidApiKey	两把 DashScope key 混用（chat ≠ 语音画图）
测试账号 402	积分按用户发，每个测试账号都要发
改版后「没生效」	会话钉版本——验证新版开新会话
新用户看不到 Agent	用户目录租户 RLS 隔离——membership 邀请入域或用建租户的账号测
新用户调租户端点 404	先 GET /api/v1/me（JIT 建本地用户行）
dry-run 404	正确路径 POST /api/v1/builder/agents/{id}/dry-run（非 /chat-dry-run）
M2M secret 丢失	只能由人类 rotate（新 secret 回显一次、旧 secret 即时失效）
改模型组绑定「没生效」	运行时只认租户级 Model Routes，用 routes:effective 核对
图片轮次黄色降级条	vision 无路由的降级占位（警告非错误）；要原生图片理解就配 vision 路由

7. 边界与升级路径

• 你的 API 面以 M2M scope 白名单为界（完整表见完整文档 §3.2）；尝试白名单外操作会被 403——那是设计，不是故障。
• 正式期（品牌域名 + 品牌 realm）：DNS / TLS / 边缘服务器 / new-realm.sh / 全部步骤在新 realm 重跑——见完整文档 §5。边缘服务器「机器面初始化」（装 nginx、渲染模板、放产物、探针）可由你经 ssh 别名执行，私钥留在操作机、不进会话；控制面（购置 / 安全组 / DNS）归人类。机器面初始化的可粘贴提示词模板：../how-to/brand-server-initialization.md。
• 深入阅读：会话运行时协议 · 支付与对账 · worked example：从零发布第一个 SaaS · 完整接入总纲