docs: define per-key skill catalog contract

2026-07-18 11:04:58 +02:00
parent b4c3da334a
commit 934de855d9
2 changed files with 93 additions and 0 deletions
@@ -78,6 +78,7 @@ D601 v0.3 当前已具备用户自服务 API key 创建、列表、重命名、
 | PJ2026-01050202 | Key策略 | 本规格 6.2 | scope、expiry、quota、IP 和 rate limit 绑定 | 权限配额、平台配置 | 受保护 API |
 | PJ2026-01050203 | Key校验 | 本规格 6.3 | introspection 和 principal 输出 | 账号状态、key 策略 | Agent编排、Cloud API |
 | PJ2026-01050204 | Key审计 | 本规格 6.4 | last used、拒绝原因和脱敏审计 | key 校验、计量账本 | admin、运营分析 |
+| PJ2026-01050205 | Key Skill Catalog | [APIKey Skill Catalog](PJ2026-01050205-api-key-skill-catalog.md) | 按 Key 绑定虚拟 skill 摘要并注入 Agent 请求 | Key校验、后端Profile | Codex-compatible Agent |

 ## 6. 原子需求

@@ -0,0 +1,92 @@
+# PJ2026-01050205 APIKey Skill Catalog
+
+## 修改历史
+
+| 版本 | 对应 commit id | 更新日期 | 变更说明 |
+| --- | --- | --- | --- |
+
+当前正文仍在规格治理草稿中；未定稿前不新增版本号，不为单次编辑追加 `待提交` 版本。
+
+## 正文
+
+## PJ2026-01050205 APIKey Skill Catalog 需求规格
+
+## 1. 文档控制
+
+| 字段 | 内容 |
+| --- | --- |
+| 编号 | PJ2026-01050205 |
+| 短名 | APIKey Skill Catalog |
+| 层级 | L3 子课题 |
+| 状态 | 已生效 |
+| 上级规格 | [PJ2026-010502 APIKey](PJ2026-010502-api-key.md) |
+| 关联规格 | [PJ2026-010204 后端Profile](PJ2026-010204-backend-profile.md)、[PJ2026-010604 公开入口](PJ2026-010604-public-entry.md) |
+| 规格治理索引 | [规格治理](spec-governance.md) |
+
+## 2. 目的和范围
+
+### 2.1 目的
+
+APIKey Skill Catalog 负责把企业虚拟 skill 的 `name` 和 `description`
+绑定到指定下游 API Key，并在请求进入 Codex-compatible 上游前追加到
+Agent instructions，使企业可以通过 description 引导 Agent 从公司内网读取
+最新文件和脚本。
+
+### 2.2 范围内
+
+- 每个 API Key 独立绑定零个或多个虚拟 skill 摘要。
+- 在 Responses 请求中保留原 instructions 并追加匹配 Key 的 catalog。
+- 支持流式与同步 Responses 请求的透明透传。
+- API Key、Authorization 和上游响应的脱敏日志与健康状态。
+
+### 2.3 范围外
+
+- 不保存或分发完整 `SKILL.md`、references、scripts 或 bundle。
+- 不把虚拟 skill 注册为 Codex 客户端本地 skill，也不承诺出现在 `/skills`。
+- 不替代公司内网资源的认证、版本管理和访问控制。
+- 不修改模型输出、工具执行结果或上游计费语义。
+
+## 3. 系统边界
+
+| 边界项 | 内容 |
+| --- | --- |
+| 外部输入 | Bearer API Key、Responses 请求、按 Key catalog 配置。 |
+| 受控资源 | Key SecretRef、skill name/description、instructions 注入器、上游路由。 |
+| 外部输出 | 原样上游响应、注入摘要、脱敏健康和错误状态。 |
+| 系统边界 | 加载器只做鉴权匹配、catalog 追加和透明代理；Sub2API 继续拥有账号池、调度、计费和上游错误语义。 |
+
+## 4. 原子需求
+
+### 4.1 USER-KEY-SKILL-REQ-001 按 Key 绑定
+
+加载器应通过 YAML 声明 API Key 的 `sourceRef`、`sourceKey` 和虚拟 skill
+列表。完整 Key 只能在进程内用于恒定时间匹配和上游转发，不得写入 YAML、
+日志、状态文件、错误响应或测试报告。
+
+### 4.2 USER-KEY-SKILL-REQ-002 Instructions 追加
+
+加载器应在 `/v1/responses` 与 `/v1/responses/compact` 请求中，把匹配
+Key 的 catalog 追加到现有字符串 instructions；现有 instructions 必须保留。
+未匹配 Key、非 JSON 请求或不支持的 instructions 形状必须返回明确错误，
+不得静默绕过注入。
+
+catalog 注入格式应保持稳定、简短，并只包含 `name + description`。
+
+### 4.3 USER-KEY-SKILL-REQ-003 透明透传
+
+除 instructions 注入外，请求方法、路径、查询参数、Authorization、流式语义、
+上游状态码、响应头和响应体应保持透明。加载器不得把上游失败包装成成功，
+也不得实现 Sub2API 调度、重试、切号或计费。
+
+### 4.4 USER-KEY-SKILL-REQ-004 YAML-first 与开发等级
+
+上游地址、native bind/probe、固定端口、公开域名、Caddy upstream、Key
+SecretRef 和 catalog 必须来自 owning YAML。L0 直接验证配置解析、Key 匹配和
+instructions 注入函数；L1 通过项目 CLI 管理 native 服务，并使用真实 Codex
+Responses 请求验证公开入口到上游的完整链路。
+
+### 4.5 USER-KEY-SKILL-REQ-005 可观测性
+
+健康和 CLI 状态应披露配置摘要、skill 数量、匹配 profile、请求计数、注入计数、
+上游状态和最近错误摘要，但不得披露完整 API Key、Authorization 或 description
+全文。每个代理请求应保留或生成可关联的 request id。