砺石（Whetstone）· 云砺集团统一 AI Agent 框架设计

0. 摘要卡

一句话定位：CPA 现网网关不动（模型流量咽喉），pi/agent_gateway 旁挂为「砺石 Runtime」承载 Agent-as-API 三协议门面 + 服务端循环 + 入站/出站净化，出站模型调用指回 CPA 网关（观测口径不分叉）；控制面 v0.1 轻量起步——manifest 注册仓 + 五态状态机 + xbench 评测门禁 + DuckLake 审计入湖 + 无头 MCP/CLI 管理面；治理能力寄生在流量上冷启动，达到升格触发条件（资产百量级 / 多环境分发 / 有状态审批 / 121 单点瓶颈）才建独立控制面服务。

代号「砺石 / Whetstone」为提议代号：取云砺之「砺」，磨刀石之意——评测门禁与 RSI 闭环把 agent 越磨越利；CLI 命名 whet。注：Whetstone 与 1970 年代同名 CPU benchmark 存在名称沿用，仅内部代号，正式名可在 9-3 对齐会定。

1. 背景与定位

1.1 管控面定位（已拍板，不再讨论）

本框架是管控面，不是开发提速框架。重点 = 安全、权限、可维护性、审计、发布准入，支撑「批量稳定可交付」——咨询项目交付后 BPO 团队可接手运维。框架被拍板为管控面而非 runtime 竞品；管控面的本质是在流量必经之路上执行策略，现网 CPA 网关正是那条必经之路（方案 A 骨架结论，见 §12）。

1.2 纳管合同四条（嫁接 B-11）

1.3 三层范围清单（此表即 9-3 三方对齐会「管什么 / 不管什么」一页纸底稿）

分工事实（仅记分工）：谷雪梅 = 底层 / 新技术 / 模型与数据库 / 数据洞察类系统；框架侧（本文档）= 流程运营型系统整合与标准输出。9-3 与陈岳阳、谷雪梅完成三方框架首次对齐。

1.4 三层技术整合要求

CEO（吴云）明确要求把数据库基础 + 本体（ontology）+ 模型应用「这三个整合在一起」。本设计的兑现方式：manifest 强制声明 data_domain 数据域绑定，注册即成「agent → 本体域 → 表」图边，三层整合成为注册的副产品而非附加工程（嫁接 C-2，详见 §7）。

1.5 推广机制：准入倒逼 + 双载体先行，不行政强推

• 准入倒逼：约束只落在「对外提供服务的发布物」上（注册 + 门禁 + 门面），不约束开发过程与工具；
• 双载体先行：第一用户 = 框架设计者本人的研发本体 / RSI 场景（ontoos-probe agent）；workflow + 提示词路线作为兼容形态纳入（manifest kind: workflow-prompt，嫁接 C-8），运行时不强改；
• 标准权：9-15 Bi-weekly 争取书面确认「标准权」（框架冲突裁决机制）——书面确认前 git PR 准入可被绕过，此为已知组织风险（见 §14-5）。

2. 设计原则

2.1 Agent-as-API 六条硬结论（三份独立报告收敛，直接作设计前提）

1. 不能承诺绝对保密。工具名/描述/schema、调用参数与结果必然进入模型上下文。目标 = 最小披露、不可越权、可审计，不是零可观测。
2. skill 形态的 IP 保护为零（明文落盘）——薄壳原则：核心 knowhow 一律不进可分发包。
3. 三种协议不等价，不能靠字段改名兼容。内部维护 canonical IR + 三个独立 adapter；不支持的能力返回明确 400/501，禁止静默伪造。
4. Agent 循环必须在我方服务端。平台侧只留极薄的发现/路由适配器。
5. 无单一开源仓库能同时满足「三协议皮 + 服务端托管循环 + 默认不泄露 tools/SKILL.md + 生产级流式 + 多租户安全」——必须组合，且自留一层薄但关键的请求改写与出口净化。
6. 授权必须服务端每次调用强制；MCP annotations（readOnlyHint 等）是不可信提示，不能当安全策略。

2.2 三条设计文档必写原则

2.3 熵海七条经验（设计原则内化）

1. RSI 前置 = 高质量结构化数据 + 业务源码；
2. 确定性代码 + 窄上下文，防「代码屎山」；
3. 暂不动底层参数，先 Skill 级 RSI；
4. 必须建可量化 benchmark，目标天级迭代；
5. FDE 模式不可规模化（要规避）；
6. 生态 = 能力封装 MCP/Skill，对接腾讯 WorkBuddy / 阿里云百炼；
7. 优先高频、高人力成本、低容错场景（审单/对账）。

出处：熵海经验教训入库 7 条（facts.md:17，经 internal-assets 笔记转录）。

2.4 诚实口径框（不宣称清单）

3. 总体架构

以方案 A（网关演进派）为骨架、嫁接 B/C 共 12 项机制的合成架构（评审收敛过程见 §12）。五层分层如下，右侧身份 / 审计 / 门禁三条治理线纵贯全部层级。

3.1 分层表

3.2 三方向链路（不得混写）

3.3 部署要点

• CPA 网关不动：CLIProxyAPI 双实例继续承载全部存量模型流量，不在其代码内做二开（治理逻辑不进不可控上游项目）；
• 砺石 Runtime 旁挂：唯一新增常驻进程（pi sidecar，stdlib HTTP server 现成），部署 121 同机或同网段；出站 ModelBackend 指向 CPA 网关 OpenAI 兼容端点——Agent-as-API 流量天然 100% 仍经现网网关；
• 控制面无独立服务：v0.1 = git manifest 仓 + loader + 状态机脚本 + 入湖脚本，零新增服务；升格触发条件：资产百量级 / 多环境分发 / 有状态审批工作流 / 121 单点成为瓶颈；
• 存量零风险：pi 崩溃不影响全司 AI 使用；所有模型 token 消耗仍在同一观测口径计量。

4. 数据面设计

4.1 请求流水线（7 个净化 / 授权点）

4.2 三协议 + MCP 端点表（pi 现成路由）

三套 wire contract 各自验收，不能只改字段名；不支持的 store / reasoning / 附件 / 后台任务等返回 400/501（协议差异见 oss-selection 笔记字段级对照）。

4.3 多形态发布矩阵

4.4 Anything as LLM（model 字段 = agent id）

注册仓里每个 agent 编译为一个 ModelCapability（model 名 = agent id）+ 默认 instructions + 工具白名单；GET /v1/models 即 agent 目录。客户端用任意 OpenAI / Anthropic SDK 把 base_url 指向砺石、model 填 agent id 即可调用。此模式有 OpenClaw 先例佐证（「model 字段是 agent id」），但由 pi 自研实现、不引入 OpenClaw 代码（其 HTTP 面等价完整操作员权限，不能当多租户边界——官方明确）。

4.5 流式策略（如实声明）

5. 控制面设计

5.1 资产治理流与状态机

5.2 manifest schema 示例（YAML）

# manifest.yaml —— 注册市场单一治理锚点（嫁接 B-1 / C-2 / C-7）
id: ontoos-probe-agent
kind: agent            # agent | workflow-prompt | skill | mcp-server | evalset | dataset
version: 0.1.0
owner: platform-arch
runtime: pi-ir         # pi-ir | workflow | agent-cli
three_questions:       # 谷雪梅三问（立项门槛，必填非空）
  goal: "研发本体事实问答的一次解决率"
  metric: "xbench ops_triage 子集 + 线上一次解决率"
  iteration: "badcase 回流产题，evalset 版本 +1 双签入库"
data_domain:           # OntoOS 数据域绑定，注册 CI 做引用校验，注册即图边
  - ontoos.dwd.repo
  - ontoos.dws.deploy
scopes: [ "ontoos.read" ]
risk: low
data_class: internal
evalset: ops-triage-subset@1   # 评测集亦为版本化受治理资产
exports:               # 导出形态能力位；未声明的组合返回 400/501，不静默伪造
  api: true            # 三协议（P0）
  mcp: true            # P0
  cli: false           # P1
  skill: false         # P1（按通道两版壳）
  a2a: false           # P2；v0.1 返回 501
streaming: pseudo      # 伪流如实声明
status: draft          # draft / evaluated / approved / published / deprecated

起点为 pi docs/protocol-contract.md 第 10 节能力注册表 YAML 设计稿 + PublicToolDescriptor / PrivateToolBinding 公私分离；strict loader 拒绝未知字段（借鉴 RSI DEV-BENCH-01 七类 schema 设计，估时未经实施验证，如实标注）。

5.3 无头控制面（框架自身可被 AI agent 操作）

• whet CLI：同一批端点的薄壳（register / gate / audit / approve），供脚本与流水线调用；
• skill 包装：指导 CLI / MCP 用法的薄壳 skill，同批端点；
• UI 保底：只读 console（目录浏览 + 状态机看板 + 审计查询）+ 飞书机器人自助查询（既有能力）——无头优先，界面保底。

6. 模块概要设计（12 模块）

以下为十二模块终版口径（以终版架构 §4 表为准展开）。阶段约定：P0 = v0.1（9-12）可运行；P1 = 9 月底~10 月；P2 = 独立控制面阶段。开源选型均为角色限定（详见 §10 BOM）。

7. 三层整合

CEO（吴云）要求的「数据库基础 + 本体 + 模型应用」三层整合，在本骨架下不需要额外整合工程：manifest 的 data_domain 字段强制声明数据依赖，注册即建立「agent → 本体域 → 表」图边，可回答「哪个 agent 依赖哪张表 / 改表爆炸半径」——三层整合是注册的副产品（嫁接 C-2）。

7.1 semantica 借鉴表（8 个借鉴点 + 边界）

8. 安全设计

8.1 身份演进路线

8.2 多租户与会话归属校验

• 租户 / 主体 / scope 只从已验证 token 推导，绝不信请求 body 同名字段；
• conversation / response / job / 会话句柄全部绑定 tenant + principal，跨主体访问 403——「知道句柄不算认证」，会话 ID 不是授权凭证（否则横向越权）；
• 跨租户拒绝是 9-15 现场负向演示用例（嫁接 B-4）；上线指标：跨租户数据泄露 0、秘密/DLP 逃逸 0、重复副作用 0。

8.3 审批流（人工在环）

高危写操作：策略判定 → 返回 preview / pending_approval → 审批者（专用 scope）经 POST /v1/approvals 签发审批 token——绑定 tenant + principal + call + 参数 hash + 过期时间 + 一次性 nonce；执行携带 X-Approval-Token 与 Idempotency-Key，nonce 一次性消费、幂等重放安全；全程审计留痕。P1 把签发动作接入飞书审批流。

8.4 入站 / 出站净化规则清单

8.5 SSRF 防护栈（pi provider.py 已落码，7 项专项测试实测通过）

• 双栈特殊网段拒绝清单（IPv4 18 段 / IPv6 17 段：loopback、RFC1918、link-local、云 metadata、过渡地址等）；
• 单次 DNS 解析 + 地址钉扎（防 TOCTOU / DNS rebinding）；混合应答 fail-closed；
• 不跟随重定向、忽略代理；模型不得传任意 URL 作下游地址；
• 连接器出站强制复用该防护栈；不受信连接器 P1 进 Docker MCP Gateway 容器隔离 worker（须放在已认证租户路由器之后）。

8.6 威胁要点与确定性控制

9. 可观测与 RSI 闭环

RSI 定位沿 xbench 表述：「企业语境下 RSI 不是 AI 自改权重，而是 Agent 系统的每一次迭代都由客观、稳定、来自真实业务的度量裁决是否算改进——评测门禁就是这个度量（适应度函数）」。数据收集在 P0 即为默认：凡经砺石的请求自动产审计 + 用量入湖，应用侧零改造（寄生冷启动红利）。

9.1 L0~L4 放权分级表（嫁接 B-12，承接 xbench 口径）

门槛数值出处：xbench docs/07（放权分级 L0~L4，按「场景 × 级别」逐格开）；配合 Result 8 态与失败码表作准入量尺（嫁接 B-12）。

9.2 「谷雪梅三问」立项门槛

9.3 与线上指标的对齐纪律

• 三条硬约束：判分器不能由被测 Agent 生成或修改；评审模型与被测模型解耦、版本固定；人工抽检每月 10% 题，一致率跌破 80% 停用该维自动分；
• LLM-Judge 与人工相关系数仅 0.11（OpsEval 参考 0.92）——自动判分暂不可信，保留人工校准环（诚实口径）；
• benchmark 分数须反映线上指标（一次解决率 / MTTR / 人工接管率），连续两周期背离即审计 benchmark 本身。

10. 开源选型 BOM（角色限定，快照 2026-09-01）

脚注：所有 License / stars / push 信息为 2026-09-01 快照口径；stars 与活跃度只是快照，不是质量或安全证明；Hosted / Cloud / Enterprise / Beta 能力不能当作 OSS 自托管能力。明确排除项（Flowise 已归档、LangServe 已归档、MCP-Bridge soft deprecated、Dify 条件排除等）及用法级排除（网关叠网关、OpenClaw 裸暴露）见 oss-selection 笔记 §2。

11. 既有资产映射

11.1 与 RSI 23 票的去重说明（4 条）

1. 框架 = D-10 网络矩阵中的「获批 model gateway」实体；准入 / 凭据 / 审计合同直接承接 DEV-BENCH-02 / 03 / 03A 的 AC，RSI 侧无需另建准入口径；
2. 评测门禁消费 xbench gate 退出码，不重建评测基建；DEV-BENCH-16（sealed 配对 gate）是其 P1 升级形态；
3. manifest strict loader 借鉴 DEV-BENCH-01 七类 schema 设计（Review Ready 估时未经实施验证，如实标注）；
4. 审计 digest 链 / 分级交付合同整体移植 RSI §13 口径（quarantine / retire 不删历史证据；轨迹默认只存 digest）。

RSI 23 票中没有网关 / 注册市场建设票（盘点笔记如实说明），注册市场由框架独担，不构成重复建设；RSI Phase0 拆票（28 工程日）与本 MVP 可并行不抢关键路径。

12. 方案对比与评审记录（design-it-twice 证据）

本设计经三套方案独立设计、三人评审团独立评分后合成（2026-09-01；原始材料 notes/designs/design-a/b/c.md，评审记录见工作流 wf_396bd541-770 输出）。三案均无硬约束违规。

12.1 三案一句话骨架

12.2 评审评分（8 项准则各 1–5 分求和，三位评审独立打分）

注：8 项准则为——管控面定位契合、复用既有资产、9-12 MVP 可行性、安全与权限深度、多形态发布完备、三层整合支撑、RSI 闭环支撑、不重复造轮子，各 1–5 分，总分为求和；逐准则明细评分保存在工作流评审记录（wf_396bd541-770），本文档不逐格转录。三份嫁接（graft）清单高度收敛，合成为下方 12 项。

12.3 胜出理由（A 为骨架）

• 冷启动零摩擦：治理数据从第一天来自真实全量流量，不存在「建好平台没人接」的死亡谷；
• 9-12 硬期限下交付风险最低：新增部署面 = 1 进程 + 1 git 仓 + 脚本，不引入 K8s、不迁移任何现有流量、存量零扰动；
• 与管控面定位同构：管控面的本质是在流量必经之路上执行策略，现网网关正是必经之路；
• 观测口径单一：所有模型 token 经同一网关计量，成本/用量治理不分叉。

A 的已知代价（评审确认并如实保留）：控制面初期简陋（git 仓 + CLI 撑门面）、121 物理单点、多租户硬隔离延后、真流式延后——分别由嫁接项与 §14 风险条目处置。

12.4 嫁接清单（终版采纳，共 12 项）

13. v0.1 MVP 工程切分（9-12 可运行）

13.1 十一项清单

1. 修 pi 控制字符 bug（jsonutil.py:98 + adapters.py:80-81，两处一行）后 28 测试保持全绿；
2. 砺石 Runtime 部署 121，出站指 CPA 网关 OpenAI 兼容端点（DemoModel 离线兜底）；
3. manifest 注册仓 + strict loader（注入 ToolRegistry / CapabilityRegistry / instructions）+ 五态状态机脚本；
4. 审计 JSONL 落盘 + GET /v1/audits（租户过滤 + audit.read scope）+ 入湖接 usage-pipeline / DuckLake；
5. token 签发 CLI + POST /v1/approvals 审批端点（一次性 nonce）；登录 / 审批 secret 分离；
6. 首个注册 agent：研发本体自用（ontoos-probe 场景，第一用户 = 框架设计者本人）；84 skill 批量登记 draft（如实标状态）；
7. xbench gate 挂发布脚本 + wrapper 兜底（并行修假绿 P1-2 与 fail-open P1-7）；
8. SDK 实测：OpenAI / Anthropic SDK 直连，按 400 报错扩字段白名单；
9. MCP 门面演示 + 无头管理工具 3 件（读写拆分）；
10. 写操作拦截 → 审批 → 放行全程审计演示 + 跨租户拒绝负向演示；
11. 注册 manifest PR 走完 draft → published 全状态机一遍。

13.2 9-15 演示脚本要点（Bi-weekly）

1. OpenAI SDK 以 model=ontoos-probe-agent 直连，得到服务端工具闭环的最终答案（客户端看不到 tool_calls）；
2. 同一 agent 经 /mcp tools/call 调用（Anything as LLM 与 MCP 门面双形态）；
3. 一次写操作被拦截 → pending_approval → 审批 → 放行执行一次 → 幂等重放演示，全程审计可查；
4. 负向用例：跨租户访问被拒（403）；未声明能力组合返回 400/501——「返回 200 不算通过」口径的现场兑现；
5. 飞书机器人查该 agent 当日用量与审计；DuckLake 查计量明细；
6. 一次注册 manifest PR 从 draft 走到 published（带 gate 运行 ID + 审批人证据链）。

诚实声明：9-15 演示的 gate 为 oracle / mock 口径（真实模型评测未跑），评测门禁短期是名义可信而非实证可信（见 §14-1）；121 单点 + 内存态下的「可运行」是演示口径（见 §14-7）。

13.3 里程碑时间线

14. 风险与未决问题（九条原样保留，不得软化）

以下九条为评审团 warnings 收编的终版口径，原样保留；等级与责任动作为本设计文档补充标注。等级：阻断（阻断相应路径）/ 高 / 中。

15. 附：数字口径备忘

15.1 网关流量口径（两套并注，统一前不混用）

15.2 ops benchmark 题数三代快照（须并注，不是缩水）

15.3 xbench 状态备忘

xbench 当前快照被 2026-08-31 审查判 REJECT / 不发布（P0：公开数据隐私残留、疑似凭据；P1：gate 零配对假绿、发布 YAML fail-open、沙箱隔离不可信等）。其骨架与方法论可内部复用，但不能宣称已可发布或可作盲测基线；真实模型评测未跑，mock / oracle 分数不代表模型能力；LLM-Judge 与人工相关系数 0.11，自动判分暂不可信。正向事实：22 个单测全过、validate 返回 0（ops 109 / dev_py 20 / dev_java 46 条一致）、校准结果符合预期。

15.4 其他关键数字（出处速查）

• pi/agent_gateway：agent_gateway/ 4,736 行 + tests/ 911 行 = 5,647 行；28 测试全绿（Python 3.12.13 与 3.11 双复验，2026-09-01 实测）；
• OntoOS：ODS 101 → 110 表、DWD 1 → 3、DWS 29 → 33（半月增量）；两轮全量复跑合验假阳 0 / 回归 0 / 真链 175 持平；
• DuckLake 入湖：44 万条请求日志入湖零失败；
• RSI Phase0：23 张票（P0 18）、28 工程日、关键路径 11.5 工作日——Review Ready 估算，未经实施验证；
• dev 判分器区分度：oracle 0.978 vs 低质取巧 0.118（判分器有效性证据，不是模型能力结论）。