主题
04 - 知识能力的供给与调用闭环
一句话：知识能力对外只呈现为一个 MCP 工具的四个动作——查、问、列、取引用，调用方拿不到引擎地址也拿不到引擎密钥；把这条链路跑通的关键不在协议，而在“订阅通过”与“真的能调用”之间那段距离：凭证由谁注入、路由由谁放行、用量由谁记账，三件事必须同一次生效。
一、只暴露四个动作
| 工具 | 干什么 | 输入 | 输出 |
|---|---|---|---|
knowledge_search | 取回带引用的片段 | 查询语句、可选项目范围 | 片段列表 + 页码坐标 |
knowledge_ask | 直接给一段答案 | 问题、会话上下文 | 答案 + 引用 |
list_documents | 列可见文档 | 项目标识 | 文档名、版本、更新时间 |
get_citation | 按引用号取回原文位置 | 引用 ID | 定位信息（页码、坐标、版本）；正文按段限量给，超出走管理台导出 |
四个都是只读动作。写入类（新建知识库、上传文档、改权限）一律不走 MCP，走管理台与控制面 API——工具面一旦被 Agent 自由调用，权限判断就从“人的授权”退化成“模型的自觉”。
引擎自带的 MCP 面只作为登记入口，不进调用路径。 理由不是性能，是责任：直接暴露引擎工具面，等于把引擎的参数（数据集 ID、相似度权重、返回条数）交给调用方，而这些参数恰好是权限与质量的共同入口，必须由 Broker 统一决定。
传输统一走 Streamable HTTP。历史 SSE 通道只保留在 OpenAI 兼容问答面上，并给出下线窗口；两套传输并行会让超时、重连、鉴权出现两种行为，出问题时无法判断是哪一套。
二、凭证在哪一跳注入
只有两跳注入：网关把模型厂商密钥注入到推理出口，Broker 用服务账号或短期令牌访问引擎。调用方与 Agent 上下文中不得出现：引擎的 Authorization、真实内网地址、可生效的数据集 ID、任何连接配置里的密钥字段。
有一条常见错觉要写明：上架响应里不带密钥，不等于密钥不外露。真实泄露通常发生在“把引擎 Key 直接发给员工做个人调试”这一步——一旦个人持有 Key，网关、限流、权限判断全部旁路。所以生产上不给任何自然人签发引擎凭证，调试也走平台凭证。
密钥扫描要覆盖日志、异常栈与工具返回，出现即报警；撤销订阅必须让数据面在短 TTL 内失效，而不是只把市场状态改成“已退订”。
只读不等于不可导出
四个动作循环一遍就能把一份文档拼出来——这是本栏最容易漏的一条泄漏路径，它不违反任何权限规则。三条约束：
| 约束 | 口径 |
|---|---|
| 引用不返回正文 | 工具面只回片段标识、页码坐标、版本与哈希 |
| 分段限量 | 单请求片段数与总字数有上限；单主体对单文档设累计取回量阈值，超阈值触发二次授权并告警 |
| 整篇导出是独立动作 | 不走 MCP，走管理台：独立授权、双人确认，审计记“累计取回量”字段 |
配套一条指标：按主体与文档统计的累计取回量 Top 榜（见 05 §七）。没有这条榜，上面的阈值就只是配置里没有执法的字段。
三、从入库到可被调用的状态链
一份知识产品要穿过四个系统，每个状态只有一个权威持有者：
| 状态 | 权威 | 判据 | 当前状态 |
|---|---|---|---|
| 已解析 / 就绪 | 引擎 | 终态成功 + 分块数偏差在范围 + 抽检留档（见 01） | 判据已定，证据待归档 |
| 已发布 | 市场平台 | 产品在目录可见，元数据与工具清单已注册 | 目录与订阅段已实证 |
| 已订阅 | 市场平台 | 订阅关系通过审批 | 已实证 |
| 可调用 | 网关 + Broker | 路由放行、凭证注入、ACL 映射生效、用量开始记账 | 未覆盖：引擎对外工具面与鉴权、端到端调用与计量闭环尚未实证，不得按“已可调用”叙述 |
最后这一格才是真正的分水岭，也是“订阅成功”最容易骗人的地方：订阅只表示授权关系成立，不表示路由与配额已经生效。判断有没有闭环，看一次真实调用能否成功返回，而不是看控制台上的绿色状态。
这一格目前没过。上游引擎的 MCP 对外工具面与鉴权尚未实测、端到端调用与计量闭环尚未跑通，历史台账记的是未实证与未闭环——本栏把它写成生产要求，而不是既成事实。销项即 06 的第 1 组证据。
一致性做法是显式发布动作 + 定时对账，而不是事件推送：对账比三件事——产品版本、工具清单哈希、端点可达性。差异只告警，刷新必须人工确认。自动刷新看起来省事，实际是把一次错误发布变成全量事故。
四、问答与检索分开两条路
| 通道 | 谁在用 | 形态 |
|---|---|---|
| 知识问答 | 员工（Web / IM） | 网关透传 OpenAI 兼容协议，固定应用与固定知识范围 |
| 知识检索 | Agent（经 MCP 工具面） | Broker 包装的稳定工具 |
| 知识库管理 | 管理员 | 网关按角色白名单放行的管理端点 |
| 模型与密钥 | 平台控制面 | 控制面直连，不经用户流量入口 |
第一条要注意透传范围：兼容协议必须在固定应用、固定知识范围内透传，不能让客户端自由指定数据集或切换应用，否则兼容层会变成越权通道。
五、超时与限流按知识检索的特点配
三条参数跟普通 API 网关不一样：
- 超时分层：连接超时、首包超时、流式空闲超时各自设值，且网关总超时必须小于上游预算，否则上游还在算、网关已经断开，重试就变成重复计费。
- 并发按连接数而不是每秒请求数：长连接问答场景下 QPS 很低但并发很高，按 QPS 限流等于没限。
- 幂等只对只读检索成立：检索可以重试；解析任务、写文档这类动作必须带业务幂等键，否则重试会产生重复入库。
限流返回的 429 要能区分三种原因——配额耗尽、上游限流、本服务并发过高——并各自带重试建议。调用方拿到一个不带原因的 429，只能盲目重试，最后把上游打得更死。
六、三条日常运维动作
新增一个知识库：建库并配解析器与模型 → 导入并解析 → 就绪抽检 → 登记工具元数据 → 建产品与元数据并发布 → 配权限映射 → 放行。验证方式不是“目录里能看到”，而是发起一次经网关的检索并确认引用能打开。
新增一个租户：开通门户与身份提供方（令牌验签必须开）→ 审批开发者 → 签发消费者凭证 → 建立项目与索引映射。验证方式是跨租户负向测试：A 租户凭证访问 B 租户资源必须被拒，并且审计里能查到这条拒绝。
下线一份文档：先停可见性，再清索引与缓存，保留期到后物理删除。验证方式是同一查询返回中不再出现该文档，且旧引用显示失效。
七、边界
- 工具粒度只读是当前边界，写操作进工具面需要先解决“谁为一次写入负责”的问题，不排在本栏范围内。
- 计量记录的是调用事实与用量，价格与结算在企业计费系统；本栏做到能按天对账，不宣称完成计费闭环。
- 观测面板依赖自建：开源版本的可观测能力不足以支撑生产判定，指标与事件落点见 05 部署运维与容量。