From 934de855d91c5a12be22db87fc4ca478619abfd2 Mon Sep 17 00:00:00 2001 From: pikastech Date: Sat, 18 Jul 2026 11:04:58 +0200 Subject: [PATCH] docs: define per-key skill catalog contract --- .../PJ2026-01/specs/PJ2026-010502-api-key.md | 1 + .../PJ2026-01050205-api-key-skill-catalog.md | 92 +++++++++++++++++++ 2 files changed, 93 insertions(+) create mode 100644 project-management/PJ2026-01/specs/PJ2026-01050205-api-key-skill-catalog.md diff --git a/project-management/PJ2026-01/specs/PJ2026-010502-api-key.md b/project-management/PJ2026-01/specs/PJ2026-010502-api-key.md index d1e22a5f..8c346a60 100644 --- a/project-management/PJ2026-01/specs/PJ2026-010502-api-key.md +++ b/project-management/PJ2026-01/specs/PJ2026-010502-api-key.md @@ -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. 原子需求 diff --git a/project-management/PJ2026-01/specs/PJ2026-01050205-api-key-skill-catalog.md b/project-management/PJ2026-01/specs/PJ2026-01050205-api-key-skill-catalog.md new file mode 100644 index 00000000..9a0707f9 --- /dev/null +++ b/project-management/PJ2026-01/specs/PJ2026-01050205-api-key-skill-catalog.md @@ -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。