opensource/bisheng
3
0
Fork 0
mirror of https://github.com/dataelement/bisheng.git synced 2026-09-01 15:32:50 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs(3.0): PRD v2.4 修订交付形态 — 技能包 + HTTP API + 个人密钥

Browse Source 
用户澄清真实案例：腾讯 ima 把自己做成技能包（ima-skills-1.1.9.zip）
供 openclaw 这类 Agent 安装，接入两步都是「复制一段东西交给 Agent」。
实地下载解包取证（S21），据此重写交付形态。

撤销两处判断：
- 「skill 包不是一种接入形态」——错。对 A 类通用 Agent 它就是接入形态
- 「remote MCP server 是必做项」——那是 B 类（WorkBuddy）的要求，本期不承诺 B 类

新增核心区分（§3.5）：目标 Agent 分两类
- A 类 有执行能力的通用 Agent（openclaw/Claude Code/自研）：技能包 +
  HTTP + 个人密钥，对方不必开任何口子；跑在用户可控环境里，**连通性
  风险随之消解**（D14 改判）
- B 类 平台内配插件（Coze/豆包/WorkBuddy/钉钉）：各家形态不同，D18 二期

§4.10.7 重写：技能包必备件（对标 ima 拆包）、私有化三处差异
（base URL 不可硬编码 / allowed_domains 随实例生成 / 由本实例分发）、
平台现成件（dev_toolkit/skills 包结构 + 匿名分发端点 + 内置包先例）。
标注一处会卡链路的格式差异：现端点产 gzip tarball，ima 用 zip。

§4.10.5 第 4 项改为「给 Agent 的安装提示词」，须按当前实例地址动态生成。

新增 AC-P18~P21（安装提示词带实例地址 / 技能包可解包安装 / 安全白名单
随实例生成 / 端到端链路验收）、附录 A.2-bis ima 拆包记录、S21 来源、
A.8-bis 补 S21 取证性质与 openclaw 未取证的限定、附录 F 两条措辞红线。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
LineWalker
2026-08-27 13:56:24 +08:00
parent c0aea4dec1
commit bf776091a8
1 changed files with 150 additions and 51 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/product/3.0 开放 API 鉴权与身份传递 PRD.md
+150 -51
View File
@@ -12,7 +12,7 @@
| v2.0 → v2.1 主要变更 | 应用工场三个扩展位收口：① **附录 B 分为 B.1（V2 端点）/ B.2（本地开发三面）**，三位的能力↔权限位映射登记完毕；② 核实并关闭「`identity:read` 是否覆盖既有端点」——V2 现有八个模块中**不存在用户/组织查询端点**，本位只作用于 MCP 身份工具；③ 立规则：**三个扩展位只走模式 S，且与 `delegate` 互斥**（签发/编辑硬阻断 + 运行期入口拒绝），补 AC-48 / AC-49（§4.2.3 / §4.2.4 / §4.7.3 / 附录 B.2）；④ 2026-08-17 清理两处早于 v2.0 ⑥⑦ 决议的残留表述：§4.7 引言（「绑定使用人可选」→ 资源归属人已是正文概念、「应用 token 另占一 tab」→ 应用运行期凭据不设管理界面）、§4.7.2 概览「删除阻断」→ 与 §4.7.4 / AC-31 一致的「二次确认即可删除、不阻断」 |
| v2.1 → v2.2 主要变更 | 2026-08-17 两项裁定，均落在 §4.6.3：① **日常/任务模式的对外区分改用 `bisheng_mode` 扩展字段，`background` 恢复 OpenAI 原义**（**D11**，推翻原「`task_mode` ⟷ `background` 一一对应」的写法）——能力轴与传输轴解耦，新增错误码 `26017` 与 AC-50，`26015` 收窄为纯传输语义；连带订正「切任务模式只需翻一个布尔」的过度承诺（§4.6.3 六末段）。② **Chat Completions 薄兼容层由「待客户场景决定」改判为本次明确不做**（**D12**），进 §六非目标、附录 B.1 对应行划除 |
| v2.2 → v2.3 主要变更 | 2026-08-18，按研发反馈重定 §4.6.3 的文档层级：① **PRD 不再指定日常模式会话的对外契约形态**（**D9 改判**，展开见 §7.5）——原「OpenAI Responses 兼容子集」及其字段映射、事件对应、拒绝清单全部移出正文，改为「调用方必须能表达的业务入参」+「八条与形态无关的硬边界」，形态由研发在 design 决定；触发点是研发反馈对标成本高，根因是**模型侧契约承接应用侧能力**的语义错配（要求调用方拼 system message 等）。② **连带取消「官方 OpenAI SDK 可直连」这一产品需求**（AC-36 改写、进 §六非目标）——该诉求由 `model:invoke` 模型协议面承接。③ **D11 / D12 规则不变、表述泛化**：D11 只约束「运行模式」与「同步/异步」不得合并，不再指定承载字段；D12 由「不做 Chat Completions 薄兼容层」泛化为「同一能力不做第二套并行契约」。④ 附录 B.1 端点行改按能力命名（路径归 design）、附录 C `26015` / `26017` 改按能力语义表述、附录 E.3 去字段名保留取证 |
| v2.3 → v2.4 主要变更 | 2026-08-27，**「不做个人访问令牌」改判为交付**（**D13**，展开见 §7.6）——客户提出新场景：员工在个人中心自助申请密钥，接入 workbuddy / 豆包工作台一类第三方办公 Agent，检索本人有权访问的知识空间内容。① 新增 **§3.5 场景四**（判据是「谁来配这把密钥」，前三类由管理员配、场景四由员工自配，且**首次出现数据流出组织控制边界**）；② 新增 **§4.10 R10 个人访问令牌**——**PAT 是新的主体类型，不是新的身份模式**，权限基准与模式 S 一致，§4.3.1 流程一个分支不改；③ §1.1 第二层由「密钥必绑服务账号」放宽为「**密钥必绑主体**」，层义不变、主体不再只有一类；④ 新增治理三闸门（能力开关默认关 / 管理员台账与强制吊销 / 审计双归属）与 **管理员持有的 PAT 不享受管理员短路** 这条硬规则；⑤ §6 非目标删除「不实现个人访问令牌」，改为「PAT 本期只开 `knowledge:read`，`identity:read` 与 `delegate` 为永久禁令」；⑥ 附录 C 新增 `26040`–`26043`；⑦ **连带须改 release-contract 的 INV-28 与表 1 ApiCredential 行**（原文「平台不存在自然人个人凭据」「全平台唯一主体轨」），不改则 Constitution Check 必判冲突；⑧ 同日行业调研（GitHub / GitLab / Slack / Atlassian / WorkBuddy / 钉钉 / Coze 一手文档，S14–S20）带来**三处改判**：**(a) remote MCP server 由「增强项」升为「必做项」**——WorkBuddy 接外部服务只接受「安装自定义 MCP 服务」；**(b) 「员工把自己的 PAT 填进豆包」在 Coze 上没有原生落点**（其静态密钥是插件级全局一把），须回问客户、OAuth 授权服务器列 D18 二期；**(c) 随人级联失效不是行业默认**（只有 Slack 有明文，GitHub 明确策略收紧不追溯吊销），必须自建、不得援引「业界都这么做」 |
| v2.3 → v2.4 主要变更 | 2026-08-27，**「不做个人访问令牌」改判为交付**（**D13**，展开见 §7.6）——客户提出新场景：员工在个人中心自助申请密钥，交给自己在用的通用 Agent（openclaw / Claude Code 一类），检索本人有权访问的知识空间内容——**真实对标案例是腾讯 ima 把自己做成技能包供 openclaw 安装**（S21）。① 新增 **§3.5 场景四**（判据是「谁来配这把密钥」，前三类由管理员配、场景四由员工自配，且**首次出现数据流出组织控制边界**）；② 新增 **§4.10 R10 个人访问令牌**——**PAT 是新的主体类型，不是新的身份模式**，权限基准与模式 S 一致，§4.3.1 流程一个分支不改；③ §1.1 第二层由「密钥必绑服务账号」放宽为「**密钥必绑主体**」，层义不变、主体不再只有一类；④ 新增治理三闸门（能力开关默认关 / 管理员台账与强制吊销 / 审计双归属）与 **管理员持有的 PAT 不享受管理员短路** 这条硬规则；⑤ §6 非目标删除「不实现个人访问令牌」，改为「PAT 本期只开 `knowledge:read`，`identity:read` 与 `delegate` 为永久禁令」；⑥ 附录 C 新增 `26040`–`26043`；⑦ **连带须改 release-contract 的 INV-28 与表 1 ApiCredential 行**（原文「平台不存在自然人个人凭据」「全平台唯一主体轨」），不改则 Constitution Check 必判冲突；⑧ 同日行业调研（GitHub / GitLab / Slack / Atlassian 一手文档，S14–S17）：**随人级联失效不是行业默认**（只有 Slack 有明文，GitHub 明确策略收紧「不撤销也不禁用」存量令牌），必须自建、不得援引「业界都这么做」；⑨ **同日据真实案例（腾讯 ima → openclaw，一手拆包 S21）重写交付形态**——目标 Agent 分两类：**A 类有执行能力的通用 Agent**（openclaw / Claude Code / 自研）走「**技能包 + HTTP API + 个人密钥**」，本期唯一承诺；**B 类平台内配插件**（Coze / 豆包 / WorkBuddy / 钉钉）各家形态不同、列 D18 二期。连带：**「MCP 必做」的中途判断被撤销**（那是 B 类要求）、**「技能包不是接入形态」的初判被推翻**、**连通性风险（D14）对 A 类消解**（这类 Agent 本来就跑在用户内网） |
> **阅读指引**
> §1 是全文结论，只读这一节即可做立项决策。§2–§3 说明问题与需求来源，§4 是需求正文（研发与产品的执行依据），§5–§7 是验收、边界与待决项。
@@ -58,7 +58,7 @@
| **P0** | 关闭匿名通道 | 服务账号主体（含**资源归属人**，§4.5 定义 6）+ 服务账号密钥 + 全端点接入鉴权 + 管理界面 | 约 11~12 人天 ⚠️ |
| **P1** | 身份传递 | 两种身份模式 + 外部用户标识头 + 受限委托五道准入 + 审计双归属 + 裸 user_id 参数收口 + **检索补文件级过滤**（§4.4.6） | 约 12~14 人天 ⚠️ |
| **P1** | 日常模式会话开放 | 以**业务语义**开放工作台日常模式对话：选模型 + 可选挂知识库 / 开平台工具 / 传附件 + 服务端多轮 + 流式与非流式 + 会话附件上传（**契约形态归 design**；**会话列表/历史查询、第二套并行契约均本次不做**，§4.6.3） | 约 12~15 人天 ⚠️，**须按新形态重估** |
| **P1** | **个人访问令牌**（§4.10） | 自助签发面 + 自然人主体解析 + 只读权限位白名单 + 必填过期与上限 + 级联失效 + 管理员台账与强制吊销 + 审计归因；**交付形态 = remote MCP server + HTTP 双形态** | 约 11~13 人天 |
| **P1** | **个人访问令牌**（§4.10） | 自助签发面 + 自然人主体解析 + 只读权限位白名单 + 必填过期与上限 + 级联失效 + 管理员台账与强制吊销 + 审计归因；**交付形态 = 知识检索技能包 + HTTP API + 个人密钥**（对标腾讯 ima → openclaw，§4.10.7） | 约 11~13 人天 |
| **P2** | 企业级运营 | 限流配额、IP 白名单、幂等性、OpenAPI 规范导出、签名断言换令牌、MCP 复用同一密钥体系；**Coze / 豆包所需的 OAuth 授权服务器**（D18） | 待估 |
> ⚠️ **两项 P1 的估算需复核**：检索的文件级过滤改造（§4.4.6）是代码核实后新增的工作项，原估算未包含它；反向地，**会话列表/历史查询及其硬约束已于 2026-08-16 移出范围**，**Chat Completions 薄兼容层已于 2026-08-17 明确不做**（D12），**2026-08-18 又取消了「对标 OpenAI Responses 子集」这一形态要求**（D9 改判）——后者砍掉的是对象模型保真、事件类型对齐、SDK 反序列化验收、完整拒绝清单等一批纯兼容性工作量，日常模式会话那行应显著下调。两项需一并重算。
@@ -244,20 +244,29 @@ BiSheng 对外暴露两组 HTTP 接口：
### 典型形态
员工在个人中心自助申请一把属于自己的密钥，填进他日常在用的第三方办公 AI 助手（workbuddy、豆包工作台一类），此后在那个助手里直接提问，助手代他检索平台知识空间的内容。
员工在自己日常用的通用 Agent（openclaw、Claude Code、Cursor 一类）里安装一个「BiSheng 知识检索」技能包，把自己在平台申请的密钥交给它，此后直接在那个 Agent 里提问，由它代为检索平台知识空间的内容。
**已有可直接对标的一手样本**：腾讯 ima 正是这么做的——把知识库与笔记能力打成 `ima-skills` 技能包供 Agent 安装，接入只有两步，**两步都是"复制一段东西交给 Agent"**：
```
员工 ──申请──▶ 个人中心签发 bs-pat-…
│
▼
第三方办公 Agent（员工自己配置）
│ Authorization: Bearer bs-pat-…
▼
POST /api/v2/filelib/retrieve
│
权限基准 = 这名员工本人
① 复制一段提示词 ──▶ 发给 Agent
「请安装 ima 技能，下载地址：…/ima-skills-1.1.9.zip
API Key 获取：…/agent-interface」
Agent 自己去下载、解压、安装
② 到平台密钥页取 API Key ──▶ 发给 Agent 完成配置
Agent 写进本地配置或环境变量
此后：员工在 Agent 里提问
│ 技能包告诉 Agent 该调哪个端点、怎么带凭据
▼
POST /api/v2/filelib/retrieve Authorization: Bearer bs-pat-…
│
权限基准 = 这名员工本人
```
> **注意第 ① 步那段提示词的性质**：它**不是给人看的安装说明，是给 Agent 的指令**。用户只负责复制粘贴，安装动作由 Agent 自己完成。这决定了 §4.10.5 密钥页要产出的是什么（见该节第 4 项）。
### 与前三类场景的本质差别：**谁来配这把密钥**
§3.1–3.3 三类场景有一个未言明的共同前提：**调用方是组织采购或自建的系统，密钥由管理员配置**。因此"最小必要权限"可以由管理员集中收敛——这正是服务账号存在的理由（§4.2.2）。
@@ -282,17 +291,22 @@ BiSheng 对外暴露两组 HTTP 接口：
4. 管理员必须能看见本租户有哪些人签了密钥、最后什么时候用过，并能强制吊销
5. 员工需要知道"怎么填进那个助手"——**接口文档要能直接复制走**，否则拿到一串密钥等于没交付
### ⚠️ 两个不在技术方案里、但决定成败的前提
### 目标 Agent 分两类，本期只承诺其中一类
**前提一 · 连通性。** 私有化部署的 BiSheng 在客户内网，而 WorkBuddy / 豆包工作台是**公有云 SaaS**——公有云侧访问不到内网地址。因此场景四要真正跑通，必须先明确打通方式（经网关暴露 / 办公 Agent 也在内网 / 出站连接器）。**这一条须问客户，不能由我们假设**；它不改变本 PRD 的技术方案，但会影响有效期上限与 IP 白名单的优先级（**D14**）。
这两类的**接入形态与可行性完全不同**，混为一谈会做出错误承诺：
**前提二 · 目标平台不是都接受"一把员工自己的密钥"。** 调研核实（详见 §4.10.7）：
| | **A 类 · 有执行能力的通用 Agent**（本期目标） | **B 类 · 平台内配插件/连接器** |
|---|---|---|
| 代表 | openclaw、Claude Code、Cursor、客户自研 Agent | Coze / 扣子、豆包工作台、WorkBuddy、钉钉 |
| 能力 | 有本地文件系统与进程执行能力，能自己发 HTTP 请求 | 只能在对方平台的管理界面里配一个插件 / 连接器 |
| 接入形态 | **技能包 + HTTP API + 一把个人密钥**——对方不必为我们开任何口子 | 受各家形态约束：WorkBuddy 只接 MCP [S18]；**Coze 的静态密钥是插件级全局一把，没有 per-user 填密钥的位置** [S20]；钉钉可吃自定义 Header 但凭据是连接器级、管理员托管 [S19] |
| 运行位置 | **用户自己可控的环境（本机 / 自有容器）→ 本来就在内网** | 公有云 SaaS |
| 连通性 | ✅ **不成问题** | ⚠️ 公有云侧访问不到客户内网 |
| 本期 | ✅ 承诺 | ❌ 不承诺（**D18**） |
- **WorkBuddy** 接外部服务**只接受「安装自定义 MCP 服务」**——形态是 MCP，不是 OpenAPI [S18]
- **钉钉连接器**可以吃 `Authorization: Bearer`，但凭据是**连接器级、管理员集中托管**，没有"每人填自己 key"的位置 [S19]
- **Coze / 扣子的静态密钥是插件级全局一把，没有 per-user 填 key 的输入位**——"员工把自己的密钥填进插件"**在 Coze 上没有原生落点**，要拿到调用者本人身份只有 OAuth 授权码一条路 [S20]。⚠️ 本轮取证的是 Coze（`docs.coze.cn`），**「豆包工作台」本身未取证**，不得直接套用
**A 类是 ima 走的那条路，也是本期唯一承诺的路。** 它同时消解了原先最大的那条风险——私有化部署的连通性：这类 Agent 跑在用户可控环境里，够得着内网的 BiSheng。
> **第三条与客户的原始描述有出入，必须回问确认两件事**：① 要接的到底是哪个平台（Coze / 扣子？豆包工作台？WorkBuddy？）；② 若是 Coze 形态，"发一把个人密钥"解决不了问题（**D18**）。这不影响本需求本身的价值——WorkBuddy 与客户自研 Agent 都吃得下——但影响"能接哪个平台"这个承诺。
> ⚠️ **B 类须回问客户**：如果客户点名的其实是豆包工作台或 Coze，那么"发一把个人密钥"解决不了问题，需要各自适配（**D18**）。本轮取证的是 Coze（`docs.coze.cn`），**「豆包工作台」本身未取证，不得直接套用**。
---
@@ -1134,9 +1148,21 @@ R4 定义 2「权限单独授予」落在这里。
1. **签发**：填名称 + 选有效期（上限内），确认后**一次性展示明文**，此后只见掩码
2. **列表**：自己名下全部令牌的名称、掩码、创建时间、最后使用时间、有效期
3. **吊销**：单个吊销 + 一键吊销全部（泄漏应急）
4. **接入说明**：可直接复制的调用示例（端点、请求头、一个最小请求体），以及"填到哪里"的指引
4. **一段可一键复制的「安装提示词」**——**给 Agent 的，不是给人的**
> 第 4 项不是文档工作的附属品，而是这个功能能否被用起来的决定因素。**员工拿到一串密钥而不知道下一步做什么，功能等于没交付。**
> **第 4 项不是文档工作的附属品，而是这个功能能否被用起来的决定因素。** 员工拿到一串密钥而不知道下一步做什么，功能等于没交付。
对标 ima 的做法（§4.10.7），这段提示词的内容是一句自然语言指令，员工复制后直接粘给 Agent，由 Agent 自己完成安装：
```
请安装 BiSheng 知识检索技能。
技能包下载地址：<本实例地址>/api/v1/dev-toolkit/skills/<pack>
密钥获取地址：<本实例地址>/<密钥页路径>
```
**关键在"本实例地址"**：BiSheng 是私有化部署，每个客户的地址都不一样，这段提示词**必须由页面按当前实例动态生成**，不能是一段静态文案（这是 ima 作为 SaaS 不需要处理、而我们必须处理的差异，§4.10.7）。
页面上同时保留一份**给人看的**最小调用示例（端点、请求头、一个最小请求体），供客户自研 Agent 或直接用 curl 验证的场景。
**员工只看得到自己的令牌**，看不到任何其他人的；管理员在服务账号模块也看不到任何个人令牌——管理员侧是另一块（§4.10.6）。
@@ -1164,34 +1190,60 @@ GitHub 的逐把审批与组织令牌台账**只覆盖新一代 fine-grained 令
GitLab 的服务账号凭据**本身就是 PAT**，却被**显式排除**在"关闭企业用户 PAT"这条组织策略之外，并且有独立的过期设置 [S15]。Slack 同构——user token 随人失效、bot token 不随人失效 [S16]。
> 对 BiSheng 的直接含义：**关闭个人访问令牌，绝不能连带关掉服务账号密钥**（那会直接打断所有生产集成）。共用底座、分别治理——这也正是 §4.10.2「只有五处不同」那张表的意义。
### 4.10.7 交付物：形态由目标 Agent 决定，不由我们偏好决定
### 4.10.7 交付物：一个技能包 + HTTP API + 一把个人密钥
调研的第一条结论是**这一节不能按"我们想给什么"来写**：两个客户点名的目标平台，接入形态要求完全不同，其中一个**根本没有给 PAT 留位置**。
#### 目标形态：把平台自己做成一个「技能」，交给有执行能力的通用 Agent
| 目标平台 | 官方接入机制 | 能不能吃一把「员工自己的 PAT」 |
**已有可直接对标的一手样本**：腾讯 ima 把自己的知识库与笔记能力做成 `ima-skills` 技能包，供 openclaw 这类 Agent 安装。它的接入只有两步，且**两步都是"复制一段东西交给 Agent"**：
1. **复制一段自然语言提示词发给 Agent** ——内容是「请安装 ima 技能，下载地址：`…/skills/ima-skills-1.1.9.zip`，API Key 获取：`…/agent-interface`」。**这段提示词不是给人看的安装说明，是给 Agent 的指令**：Agent 自己去下载、解压、安装。
2. **到平台的密钥页取密钥，发给 Agent 完成配置** ——Agent 把它写进本地配置或环境变量。
> **这与 §4.10.7 之前设想的两类平台都不同。** Coze / 豆包 / WorkBuddy 那类是「在平台的管理界面里配一个插件或连接器」，因此受各家鉴权形态的约束（Coze 甚至没有 per-user 填密钥的位置）。而 openclaw / Claude Code / Cursor 这类是**有本地文件系统与进程执行能力的通用 Agent**——**平台方只要提供 HTTP API + 一份教 Agent 怎么调的技能包 + 一把密钥就够了**，不需要对方平台为我们开任何口子。
**这条路径把 §3.5「前提一 · 连通性」基本消解掉了**：这类 Agent 跑在用户自己可控的环境里（本机或自有容器），**本来就在内网**，够得着私有化部署的 BiSheng。原先担心的"公有云 SaaS 访问不到客户内网"只对 Coze / 豆包那一类成立。
#### 技能包里必须有什么（对标 ima 一手拆包）
| 件 | ima 的做法 | BiSheng 落地要点 |
|---|---|---|
| **WorkBuddy**（腾讯云 CodeBuddy 家族） | 「连接器」；接外部服务**只有自定义连接器一条路**，而自定义连接器的实现形态就是**「安装自定义的 MCP 服务」**；鉴权支持 OAuth token 与**手工填入的 API key** [S18] | ✅ **能**，但**必须以 remote MCP server 交付**，OpenAPI schema 在这里不成立 |
| **钉钉连接器** | 七种鉴权并列，其中「自定义签名鉴权」可把任意 HTTP Header 表达出来（官方给了直接构造 `Authorization` 头的表达式示例） [S19] | ⚠️ **形式上能**，但凭据是**连接器级、由管理员集中托管**，没有"每个员工填自己 key"的原生位置 |
| **Coze / 扣子** | 插件；OAuth 2.0 授权码是唯一能拿到"调用者本人"的路径，智能体侧强制每个终端用户各自授权；**非 OAuth 的 Service 类型是插件级固定密钥**，配置里没有 per-user 填 key 的输入位 [S20] | ❌ **不能**。员工自助 PAT 在 Coze 上只能退化成"每人各建一个私有插件"，不是可运营的形态 |
| **根 `SKILL.md`** | frontmatter（name / description / homepage）+ 正文是**路由表**：模块决策表、易混淆场景、跨模块任务 | description 要写足触发词（"知识库""检索""搜一下有没有…"），否则 Agent 不会主动用它 |
| **`meta.json`** | 版本号 + `required_binaries`（node ≥18，并写明为什么需要） | 声明运行时依赖，Agent 据此预检 |
| **共享请求脚本** | `ima_api.cjs`：统一 POST、凭据加载（环境变量 → 配置文件）、错误分层、版本自检 | 同构一个即可；BiSheng 侧建议用平台已有的技能包语言习惯 |
| **子技能目录** | `knowledge-base/` `notes/` 各自 `SKILL.md` + `references/api.md` + `scripts/` | 本期只需一个「知识检索」子技能，未来可扩 |
| **`references/api.md`** | 端点全表、数据结构、错误码、**认证 Header 表** | 这是 Agent 真正照着调的那份 |
| **`metadata.security`** | `credentials_usage` 自然语言说明 + **`allowed_domains` 白名单** | ⚠️ 见下方私有化差异 |
| **安装提示词** | 平台页面上「一键复制」的一段话 | 由个人中心密钥页**按本实例地址生成**（§4.10.5 第 4 项） |
> ⚠️ **本轮取证的是 Coze / 扣子（`docs.coze.cn`），不是「豆包工作台」本身。** 二者同属字节，但**它们的插件机制是否一致，本轮没有取证**。客户若点名的是豆包工作台，须单独核实——**不得把 Coze 的结论直接当成豆包的结论**。
> ima 的技能包里有**很大篇幅在教 Agent 避坑**（PowerShell 5.1 会把请求体静默转成 GBK、写入前必须校验 UTF-8、上传文件不许改文件名、重名必须先检查）。这提示了技能包的真实性质：**它不是接口文档的另一种排版，而是"把我们踩过的坑写成给 Agent 的强制规则"**。BiSheng 侧对应的坑至少有：检索结果的引用怎么回链、知识空间 ID 从哪来（先调清单再检索）、分页游标怎么用。
#### 由此得出的三条结论
#### 私有化部署带来的三处差异（ima 是 SaaS，这三处它不需要处理）
**结论一 · remote MCP server 是必做项，不是增强项。**
WorkBuddy 接外部服务**只接受 MCP**——这一条推翻了本轮调研之前「MCP 只是开放能力层部署下的可选增强」的初判。平台正在建的 MCP Server 工具面已经具备所需的全部条件——标准 MCP 协议、与开放 API 同一鉴权语义、**工具清单按密钥权限位过滤**、一律模式 S。个人令牌只能持 `knowledge:read`，因此接进去后**自动只看到「知识库检索」与「知识库清单查询」两个工具**，没有新的过滤逻辑要写。增量只有一处：**让 MCP 面接受自然人主体的凭据**（与 HTTP 面共用同一个主体解析）。
1. **Base URL 不能硬编码。** ima 写死 `https://ima.qq.com`；BiSheng **每个客户的地址都不一样**。技能包必须把它做成配置项（环境变量 + 配置文件），并且**在个人中心生成的那段安装提示词里带上本实例地址**。
2. **`allowed_domains` 必须跟着实例走。** 这个字段的作用是让 Agent 宿主约束凭据只能发往哪些域。私有化下它是客户自己的域名，只能在**下发时生成**，不能写死在仓库里。
3. **技能包由客户自己的实例分发，不从公网取。** 这反而更简单——从本实例下载的包，可以在打包时把 Base URL 与 allowed_domains 直接填好。
> ⚠️ 但 MCP 面受「开放能力层部署开关」管辖、默认关闭，**标准版部署没有 MCP 面**。若客户要接 WorkBuddy，**部署开放能力层是前置条件**，须在方案阶段讲清楚。
#### 平台已有的现成件（这条路径几乎不需要新建基础设施）
**结论二 · HTTP + `Authorization: Bearer` + 接口文档同样必做。**
钉钉连接器与绝大多数自研 Agent 走的都是这条；它也是唯一与部署形态无关、恒在的路径。内容 = 端点、请求头、一个最小可跑的请求体、"填到哪里"的说明。落点是既有对外接口文档新增一章，以及个人中心密钥页里的可复制代码块。
| 现成件 | 位置 | 说明 |
|---|---|---|
| 技能包目录规范 | `dev_toolkit/skills/<pack>/`（`SKILL.md` + `references/` + `scripts/` + `example/`） | 与 ima 的结构同构 |
| **技能包分发端点** | `GET /api/v1/dev-toolkit/skills/{pack}` | **已实现且刻意匿名**——"技能包是公开指引"，与 ima 的公开下载地址同一取向 |
| 安装指引端点 | `GET /api/v1/dev-toolkit/install-guide.md` | 可承接安装提示词 |
| 内置技能包先例 | `linsight/builtin_skills/`（三个 office 包） | 同一套 `SKILL.md` + `references` + `scripts` 结构 |
> **权限收敛的责任完全在我们这一侧。** WorkBuddy 文档明写「自定义连接器的**访问范围由您的配置决定**，WorkBuddy 不预设范围」[S18]——对端不会替我们兜任何底。这正是 §4.10.3 只开一个只读位、§4.10.6 三道闸门的现实理由。
> ⚠️ **一处需要确认的格式差异**：现有分发端点产出的是 **gzip tarball**，而 ima 用的是 **zip**。目标 Agent 吃哪种、能不能两种都吃，须在 design 阶段实测——**这是个会卡住整条链路的小细节**。
**结论三 · 要接 Coze 这类平台，PAT 本身不够——那需要 OAuth 授权服务器，列为二期（D18）。**
这一条与客户的原始描述有出入，**必须回给客户确认两件事**：① 要接的到底是 Coze / 扣子，还是豆包工作台（后者本轮未取证）；② 若确为 Coze 形态，那么"发一把个人密钥"解决不了问题——其静态密钥是**插件级全局一把**，拿不到调用者本人。本期不为它提前改协议：一期做 MCP + HTTP，覆盖 WorkBuddy 与客户自研 Agent；OAuth 等 D18 决策。
#### 三条形态取舍
> **「skill 包」不是一种接入形态。** 客户提到的"skill"若指 Agent Skills 格式的技能包，它解决的是"教 Agent 怎么用"，不是"Agent 怎么连上来"；作为面向内部开发者的补充可以有，但**不能替代 MCP 或 HTTP 这两条真正的接入路径**。
**结论一 · 技能包 + HTTP API 是主路径，本期必做。**
它对目标 Agent 零要求（对方不必支持 MCP，也不必为我们开插件位），对平台侧几乎零新建（分发端点、包结构、内置包先例都在）。
**结论二 · MCP 面是可选增强，不是前置条件。**
平台规划中的 MCP 工具面（受开放能力层部署开关管辖、默认关闭）仍然有价值——支持 MCP 的 Agent 接起来更省事，且工具清单会按权限位自动过滤（个人令牌只持 `knowledge:read`，因此只会看到检索与知识空间清单两个工具）。但**它不是本场景的必要条件**：技能包路径不依赖它。
**结论三 · Coze / 豆包 / WorkBuddy 是另一类场景，本期不承诺。**
那一类是"在对方平台的界面里配插件/连接器"，受各家鉴权形态约束——Coze 的静态密钥是**插件级全局一把**，没有 per-user 填密钥的位置 [S20]；WorkBuddy 只接受"安装自定义 MCP 服务" [S18]。**要接那一类需要各自适配，与本期的技能包路径不是同一件事**（D18）。
#### 文件级过滤不在本需求的工作量里
@@ -1199,11 +1251,6 @@ WorkBuddy 接外部服务**只接受 MCP**——这一条推翻了本轮调研
> **一处必须写明的能力边界**：门面对**知识空间**按文件级过滤，对**文档知识库**按**库级**过滤——因为平台没有文档知识库的文件级权限模型。这不是缺口，是模型如此；但**对外措辞不能笼统说"按文件级权限过滤"**（进附录 F）。
#### ⚠️ 两条取证限制，落地前须复核
1. **「WorkBuddy」存在同名歧义**——除腾讯云 CodeBuddy 家族的 workbuddy.cn 外，另有非腾讯的同名现场服务 SaaS。**须与客户确认指的是哪一个**；本节全部结论只对 workbuddy.cn 成立。
2. 该条证据在调研中**未完成对抗性复核**（检索配额耗尽）。结论一的份量足够大，**建议在立项前用浏览器实地复核一次连接器文档**。
---
# 五、验收标准
@@ -1299,8 +1346,15 @@ WorkBuddy 接外部服务**只接受 MCP**——这一条推翻了本轮调研
- **AC-P16**　A 租户的令牌查不到 B 租户任何数据；跨租户列令牌返回空。
- **AC-P17**　**管理员持有的令牌不享受管理员短路**：以租户管理员的令牌检索一个未显式授权给他的知识空间 → 无结果；且签发表单与详情页对该持有人显示专门提示（**不得静默缩水**）。
- **AC-P18**　个人中心密钥页产出的**安装提示词带的是当前实例地址**（私有化下每个客户不同），不是静态文案；复制后直接粘给 Agent 即可完成技能包安装。
- **AC-P19**　技能包经既有匿名分发端点可下载，且**目标 Agent 能实际解包安装**——`zip` 与 `gzip tarball` 的格式差异须实测确认（§4.10.7）。
- **AC-P20**　技能包 `SKILL.md` 的安全声明里，凭据只允许发往**本实例域名**；该白名单随实例地址生成，不硬编码。
- **AC-P21**　按技能包的指引走完全程（装包 → 配密钥 → 提问），Agent 返回的检索结果与 AC-P5 一致——**验收的是这条链路端到端可用，不只是 API 可调**。
> **AC-P5 与 AC-P7 是这个功能"可不可信"的两条线：多一条是越权，少一条是功能不可用。**
> 二者都必须双向验证——正例验集合相等，反例验不出现。
>
> **AC-P21 是这个功能"用不用得起来"的那条线。** API 全部可调、密钥全部正确，但员工装不上技能包或 Agent 不知道该怎么调，功能同样等于没交付（§4.10.5 第 4 项）。
---
@@ -1341,10 +1395,10 @@ WorkBuddy 接外部服务**只接受 MCP**——这一条推翻了本轮调研
| **D9** | 日常模式会话的对外契约形态 | **已改判：PRD 不裁定，交 design** | 2026-08-18。原「已定：OpenAI Responses 子集」作废——PRD 只给业务入参与八条硬边界（§4.6.3 二 / 三），字段名、事件名、端点路径与是否对标第三方契约由研发在 design 决定并记录理由。连带**取消「官方 OpenAI SDK 可直连」这一产品需求**（展开见 §7.5），伴生 AC-36 相应改写 |
| **D11** | 「运行模式」与「同步/异步」是否合并成一个开关 | **已定：不合并，两个独立维度** | 2026-08-17 裁定，2026-08-18 随 D9 去掉具体字段名（**规则不变，只是不再指定用哪个字段承载**）。否决合并的理由：① 内部两个分支都是同步 SSE 流，「模式 ⟷ 同步/异步」的映射连现状都不成立；② 调用方为躲网关超时打开异步、却被静默切到灵思（计费 / 耗时 / 输出形态全变，并挤占共享 worker 池）；③ 透支「日常模式 + 异步」这一格，日后要开就得破坏性改契约。承载字段归 design |
| **D13** | 个人访问令牌做不做 | **已改判：做**（原「不做」作废） | 2026-08-27。触发点是 §3.5 场景四——员工自助接入个人办公助手，与前三类的系统集成不是同一件事。原否决的三条理由逐条重估后，一条被新场景推翻、一条成本估错了一个量级、一条是同一事实的两种读法。展开见 §7.6 |
| **D14** | 私有化内网 × 公有云办公 Agent 的连通方式 | **待定 · 须问客户** | 公有云 SaaS 访问不到客户内网。三条候选：① 经网关把检索接口暴露到公网 / 专线 ② 办公 Agent 本身也在客户内网 ③ 出站连接器。**不改技术方案，但决定有效期上限与 IP 白名单（现 P2）是否前移**。这条不定，功能做完也用不起来（§3.5 末段） |
| **D14** | 私有化内网 × 目标 Agent 的连通方式 | **已定：A 类不成问题；B 类才有此问题** | 2026-08-27 随真实案例澄清后改判。**A 类（openclaw / Claude Code / 客户自研）跑在用户自己可控的环境里，本来就在内网**，够得着私有化的 BiSheng——原先"公有云 SaaS 访问不到客户内网"这条风险**只对 B 类成立**（Coze / 豆包 / WorkBuddy）。本期只承诺 A 类，因此这条不再是阻塞项。IP 白名单（P2）与有效期上限按常规安全取值即可，不必为连通性提前 |
| **D15** | PAT 能力开关的层级 | **待定** | 部署级（`config.yaml`，与开放能力层开关同构）还是租户级（DB 配置，与工作台租户配置同构）？多租户下若只有部署级，Root 一开则全部子租户被动接受一条数据出口。**建议：部署级默认关 + 多租户下追加租户级，不推迟到 P2** |
| **D16** | PAT 的交付形态 | **已定：MCP + HTTP 双形态，两条都必做** | 2026-08-27 调研改判（原判断「MCP 只是增强」是错的）。**WorkBuddy 接外部服务只接受「安装自定义 MCP 服务」** [S18]，所以 remote MCP server 是必做项；HTTP + `Authorization: Bearer` + 接口文档覆盖钉钉连接器与自研 Agent，且是唯一与部署形态无关的恒在路径。**连带前置条件**：MCP 面受开放能力层部署开关管辖，客户要接 WorkBuddy 则必须部署该层。展开见 §4.10.7 |
| **D18** | 要接 Coze / 豆包工作台的话，做不做 OAuth 授权服务器 | **待定 · 二期，且须先回问客户** | **Coze 插件的静态密钥形态是插件级全局一把，没有 per-user 填 key 的输入位**——"员工把自己的 PAT 填进豆包"在 Coze 上没有原生落点；要拿到调用者本人身份只有 OAuth 授权码一条路 [S20]。**这与客户的原始描述有出入，必须确认他们要接的到底是哪个平台**。一期不为它提前改协议 |
| **D16** | PAT 的交付形态 | **已定：技能包 + HTTP API + 个人密钥** | 2026-08-27 两次改判后的终版。**① 初判「技能包不是接入形态」——错**：真实案例（腾讯 ima → openclaw）证明技能包**就是**面向 A 类通用 Agent 的接入形态。**② 中途判「MCP 是必做项」——也不对**：那是 B 类（WorkBuddy）的要求，本期不承诺 B 类。**终版**：技能包 + HTTP API 主路径必做，MCP 面降为可选增强（支持 MCP 的 Agent 接起来更省事，但不是前置条件）。平台侧几乎零新建——包结构、匿名分发端点 `GET /api/v1/dev-toolkit/skills/{pack}`、内置包先例都已存在。展开见 §4.10.7 |
| **D18** | 要不要额外支持 B 类平台（Coze / 豆包 / WorkBuddy / 钉钉） | **待定 · 二期，须客户明确提出再评估** | B 类各家形态不同、要各自适配：**Coze 的静态密钥是插件级全局一把，没有 per-user 填密钥的位置**，要拿调用者本人身份只有 OAuth 授权码（= 做 OAuth 授权服务器）[S20]；WorkBuddy 只接受「安装自定义 MCP 服务」[S18]；钉钉可吃自定义 Header 但凭据是连接器级、管理员托管 [S19]。**本期只承诺 A 类（§3.5 表），不为 B 类提前改协议。** 若客户点名的其实是豆包工作台，须先确认其插件机制（本轮取证的是 Coze，不是豆包） |
| **D17** | 管理员持有的 PAT 是否继承管理员短路 | **已定：不继承** | 平台只有 `super_admin` / `tenant_admin` 两个 allow-all 短路。若 PAT 继承，一把放在第三方 SaaS 里的密钥就等于全租户知识的读取权。判据是「管理权限不是业务权限」。实现上是结构性的——构造身份时不带管理员标志位，与服务账号侧同一做法。**但不得静默**：签发表单与详情页须对管理员显式提示（§4.10.3、AC-P17） |
| **D12** | 是否为同一能力再交付一套并行契约 | **已定：不做** | 2026-08-17 裁定（原针对「Chat Completions 薄兼容层」，2026-08-18 随 D9 泛化为形态无关的规则）。同一能力只维护一套对外契约：第二套要么功能残缺（薄层承载不了平台工具与知识库引用），要么迫使平台长期维护两份映射；「第三方生态支持度」目前是假设而非确认诉求。想拿通用 OpenAI 客户端直连的，走 `model:invoke` 模型协议面。将来出现真实场景单独立项重估，不在本次留占位 |
@@ -1532,15 +1586,54 @@ OWASP API Security Top 10 2023 将 BOLA（对象级授权失效）列为第一
**本轮未取得任何可核实结论、因此不入表的产品**：Notion、LangSmith、Dify、RAGFlow、FastGPT、Coze 的 PAT 设计。
**「明文只显示一次 + 哈希存储」本轮未取得一手引用**，故不入本表（该做法在本 PRD 的依据是 §4.2.5–4.2.6 的既有论证，不依赖本表）。
### 接入形态一侧（第三方办公 Agent）
### 接入形态一侧：目标 Agent 分两类
| 平台 | 官方接入机制 | 能否吃"员工自己的 PAT" | 来源 |
**A 类 · 有执行能力的通用 Agent（本期目标）**
| 平台 | 接入机制 | 能否吃"员工自己的密钥" | 来源 |
|---|---|---|---|
| **WorkBuddy**（腾讯云 CodeBuddy 家族） | 连接器；外部服务**只有自定义连接器一条路**，形态 = **安装自定义 MCP 服务**；鉴权支持 OAuth token 与手工填入的 API key | ✅ 能，但**必须以 remote MCP server 交付** | [S18] ⚠️ 未对抗性复核 + 同名歧义 |
| **openclaw** 等通用 Agent | **安装技能包**（zip）+ 自己发 HTTP 请求；凭据存本地配置文件或环境变量 | ✅ **能，且这正是设计意图**——凭据本来就是逐用户各自配置的 | [S21]（ima 技能包一手拆包） |
| 客户自研 Agent | HTTP + 任意鉴权头 | ✅ 能 | — |
**B 类 · 在对方平台界面里配插件 / 连接器（本期不承诺，D18）**
| 平台 | 官方接入机制 | 能否吃"员工自己的密钥" | 来源 |
|---|---|---|---|
| **WorkBuddy**（腾讯云 CodeBuddy 家族） | 连接器；外部服务**只有自定义连接器一条路**，形态 = **安装自定义 MCP 服务** | ⚠️ 能，但**必须以 remote MCP server 交付** | [S18] ⚠️ 未对抗性复核 + 同名歧义 |
| **钉钉连接器** | 七种鉴权并列，「自定义签名鉴权」可构造任意 HTTP Header | ⚠️ 形式上能；但凭据**连接器级、管理员集中托管**，无 per-user 位 | [S19] ⚠️ 属"连接平台"，未证明 AI 助理会消费 |
| **Coze / 扣子** | 插件；OAuth 2.0 授权码是拿到"调用者本人"的唯一路径 | ❌ **不能**——Service 类型是**插件级全局一把密钥**，无 per-user 输入位 | [S20] |
> **这张表是 §4.10.7 三条结论的全部依据**，也是"交付形态由目标 Agent 决定、不由我们偏好决定"这句话的出处。
> **两类的分水岭是"对方有没有本地执行能力"**：A 类自己会发请求，我们只要给 API + 教程 + 密钥；B 类只能在对方的框里配，因此受对方鉴权形态约束。**§4.10.7 的三条形态取舍全部出自这张表。**
### ima 技能包拆包记录 [S21]
对 `ima-skills-1.1.9.zip` 实地下载解包（2026-08-27），结构与关键设计：
```
ima-skill/
SKILL.md ← frontmatter + 模块路由表 + 强制规则 + 凭据检查
meta.json ← version + required_binaries（node ≥18，含 reason）
ima_api.cjs ← 统一 POST / 凭据加载 / 错误分层 / 版本自检
knowledge-base/
SKILL.md ← 接口决策表 + 写入类工作流「安全门」
references/api.md ← 端点全表 + 数据结构 + 错误码 + 认证 Header 表
scripts/{cos-upload,preflight-check}.cjs
notes/
SKILL.md references/api.md
```
| 设计点 | ima 的做法 |
|---|---|
| 鉴权 | 两个自定义 Header：`ima-openapi-clientid` + `ima-openapi-apikey`（**不是** `Authorization: Bearer`） |
| 协议 | 统一 HTTP POST + JSON body，响应封 `{"code":0,"msg":"","data":{}}` |
| 凭据存放 | 环境变量 `IMA_OPENAPI_CLIENTID`/`IMA_OPENAPI_APIKEY` **优先**，回落 `~/.config/ima/{client_id,api_key}` |
| 安全声明 | frontmatter `metadata.security`：`credentials_usage` 自然语言 + **`allowed_domains` 白名单**（`ima.qq.com`、`*.myqcloud.com`） |
| 宿主适配 | frontmatter `metadata.openclaw`：`emoji` / `requires.env` / `primaryEnv` |
| 自更新 | 每天首次调用检查版本；`-200` = 需更新且原请求未发送，stdout 带 `instruction` prompt 引导用户更新 |
| 权限语义 | `get_addable_knowledge_base_list` = "**当前用户有权限**添加内容的知识库"——即按密钥属主的权限过滤，与本 PRD §4.10.3 同构 |
| 篇幅分布 | **大部分正文在教 Agent 避坑**：PowerShell 5.1 静默转 GBK、写入前必须校验 UTF-8、上传不许改文件名、重名必须先检查 |
> **最后一行是本记录最有价值的一条**：技能包**不是接口文档的另一种排版**，而是"把我们踩过的坑写成给 Agent 的强制规则"。
## A.3 逐字原文与来源
@@ -1753,7 +1846,9 @@ Coze 官方文档自述 [S5]：
③ OWASP 相关条目、令牌泛滥（token sprawl）、DLP 与出站合规要求
> §4.10.6 三道闸门的依据是 §3.5 的场景推理 + S14–S17 的产品先例，**不是**合规条文——对外措辞不得暗示后者。
2. **两条主张被明确推翻（0-3），不得引用**：「GitHub 离职即自动级联吊销 PAT」「GitLab 删除或封禁用户即自动吊销其 PAT」。正确口径见 §4.10.4。
3. **S18（WorkBuddy）有两处弱点**：本轮未完成对抗性复核（检索配额耗尽）；且「WorkBuddy」存在同名歧义（另有非腾讯的现场服务 SaaS）。**§4.10.7 结论一（MCP 必做）完全建立在这一条上，立项前须用浏览器实地复核并与客户确认平台身份。**
3. **S18（WorkBuddy）有两处弱点**：本轮未完成对抗性复核（检索配额耗尽）；且「WorkBuddy」存在同名歧义（另有非腾讯的现场服务 SaaS）。**它现在只支撑 B 类那张表的一行（D18 二期），不再是任何本期结论的地基**——2026-08-27 真实案例澄清后，「MCP 必做」这条中途判断已被撤销（详见 §4.10.7 / D16）。若二期确要接 WorkBuddy，届时须实地复核并与客户确认平台身份。
4. **S21（ima 技能包）的取证性质与其余各条不同，可信度更高**：它不是文档转述，而是**实地下载 zip 解包后逐文件读取**（拆包记录见 A.2-bis）。其结论只描述"ima 是怎么做的"，**不构成"业界通行做法"**——本轮只有这一个技能包样本。
5. **仍然未取证的一项**：openclaw 本身的官方文档。A 类的能力刻画（有本地文件系统与进程执行能力、凭据逐用户各自配置）是**从 ima 技能包内容反推**的硬事实（它读 `~/.config/ima/`、跑 `node` 脚本、声明 `metadata.openclaw.requires.env`），推断可靠，但**不等于读过 openclaw 官方规范**。若要在对外材料里承诺"支持 openclaw"，须另行取证其技能包格式（尤其 **zip vs gzip tarball** 这一项，见 §4.10.7）。
4. **S19（钉钉）的适用范围限定**：证据属"钉钉连接平台"（我的连接 / 连接器），两页均**未说明钉钉 AI 助理会把这些连接器当作工具或知识源消费**。不可据此承诺"能接钉钉 AI 助理"。
5. **S20（Coze）的官方文档自相矛盾一处**：`agent_plugin` 页称"发布后默认使用开发者账号授权"，与 `plugin_node` 页的"智能体中每个用户各自授权"打架。**因此"发布后仍逐用户授权"不可当既定事实**；本 PRD 只用了未被矛盾波及的那半——静态密钥是插件级全局一把。
6. **A.2-bis 中标注"本轮未核实"的格子就是未核实**，不得在对外材料里补白成"业界通行做法"。
@@ -1933,6 +2028,8 @@ Coze 官方文档自述 [S5]：
| S19 | 钉钉 · 连接器自定义签名鉴权（可构造任意 Header） | https://open.dingtalk.com/document/connector/custom-signature-authentication |
| S20 | Coze / 扣子 · OAuth 插件（授权码 + 每用户授权） | https://docs.coze.cn/guides_oauth_plugin |
| S20 | Coze / 扣子 · 插件节点授权模式 | https://docs.coze.cn/guides/plugin_node |
| **S21** | **腾讯 ima · Skills 安装页**（真实案例来源，用户提供截图） | https://ima.qq.com/agent-interface |
| **S21** | **腾讯 ima · 技能包本体**（2026-08-27 实地下载解包，见 A.2-bis 拆包记录） | https://app-dl.ima.qq.com/skills/ima-skills-1.1.9.zip |
> **本轮取证边界（务必遵守）**：以下三类主张在本轮**零条通过对抗性核查**，本 PRD 因此**没有**引用它们，后续也不得以"业界都这么做"补写——① MCP 授权规范（OAuth 2.1 Resource Server / Protected Resource Metadata / RFC 8707）② 查询期 ACL 与 security trimming 的厂商做法（Azure AI Search / Graph connectors / Glean / Elastic / Kendra）③ OWASP、令牌泛滥、DLP 与出站合规。**另有两条被明确推翻**：「GitHub 离职即自动级联吊销 PAT」「GitLab 删除或封禁用户即自动吊销其 PAT」——均以 0-3 被否，**不可引用**（正确口径见 §4.10.4）。
>
@@ -2189,3 +2286,5 @@ assignee 行的外键指向 `permission_grant` 而非主体（`grant.py` 中 `on
| 管理员持有的令牌按普通用户判定，看不到未显式授权给他的内容 | 管理员的令牌等同于管理员在平台里的可见范围 |
| 持有人离职 / 停用后其令牌自动失效 | 令牌"永久有效"或"和账号一样长期可用" |
| 管理员可查看本租户令牌的元数据并强制吊销 | 管理员可以查看或找回令牌明文（**明文不存在**） |
| 支持接入**有执行能力的通用 Agent**（装技能包 + 配密钥即可） | 笼统说"支持接入各类 AI 助手"——**Coze / 豆包 / WorkBuddy / 钉钉属另一类，本期不承诺**（§3.5 表 / D18） |
| ima 把知识库做成技能包供 Agent 安装，是一个可对标的先例 | 「业界都用技能包」——**本轮只有 ima 一个样本**（A.8-bis 第 4 条） |