# R2.7.5 调查报告

## 结论

用户澄清后，目标可收敛为按下游 API Key 注入一组虚拟 skill 的 `name + description`。description 负责说明触发条件，并引导 Agent 从公司内网读取最新版说明、文件或脚本；Sub2API 不需要保存或分发完整 `SKILL.md`、references、scripts 或 bundle。

这会显著缩小实现面，但 Sub2API 当前仍没有同时满足“按 API Key 配置”和“覆盖原生 `/v1/responses`”的官方配置，因此严格服务端按 Key 控制无法只靠现有配置完成。

## 源码事实

- `backend/internal/server/middleware/api_key_auth.go` 已将完整 API Key 实体放入请求上下文，具备按 Key 选择配置的基础。
- `backend/ent/schema/api_key.go` 当前没有 skill、catalog 或 instructions 字段。
- `backend/internal/service/api_key_auth_cache.go` 与 `api_key_auth_cache_impl.go` 使用 API Key 鉴权快照；新增按 Key catalog 时必须进入快照并提升版本。
- `gateway.forced_codex_instructions_template_file` 是全局配置，模板数据也不含 API Key 信息。
- 该全局模板当前只用于 `/v1/messages` 到 OpenAI OAuth Responses 的桥接路径。
- 原生 `/v1/responses` 路径只在 instructions 为空时补默认 Codex instructions，不会应用上述模板。

## 候选方案

### 现有全局模板

适合所有 Key 共用同一 description，且流量只走 `/v1/messages` 桥接的情况。它不能按 Key 区分，也不覆盖员工 Codex 常用的原生 `/v1/responses`，因此不满足完整目标。

### 外部反向代理

代理可按 Bearer Key 的指纹映射 catalog，并改写请求 `instructions`。这能做到不修改 Sub2API，但会新增一层敏感 Key 处理面，还要正确处理 Responses、compact、messages、流式和请求体兼容，运维复杂度高，不推荐作为默认方案。

### Sub2API 最小扩展

推荐在 API Key 上增加结构化字段，例如：

```json
[
  {
    "name": "company-dev",
    "description": "当任务涉及公司项目时使用。先从公司内网固定地址读取最新说明。"
  }
]
```

最小改动范围：

- API Key migration、Ent schema、repository/service 和管理员 CRUD。
- 鉴权快照加入 catalog 并提升 snapshot version。
- 鉴权完成后，将 catalog 追加到最终 Responses instructions，覆盖 `/v1/responses`、`/v1/responses/compact` 和 `/v1/messages` bridge。
- 保留客户端已有 instructions，只追加企业 catalog，不覆盖用户内容。
- 日志只记录 API Key 标识、catalog 名称或内容 hash，不记录完整 description。
- 不增加文件、脚本、manifest 或 bundle 存储与分发能力。

建议注入文本保持短小稳定：

```md
## Company Skills

- `company-dev`: 当任务涉及公司项目时使用。使用前从公司内网固定地址读取最新说明。
```

## 能力边界

- 这是请求上下文里的虚拟 skill catalog，不是 Codex 客户端本地发现的 skill，不会自动出现在 `/skills` 或本地 skill selector。
- description 应明确写出触发条件、内网入口和读取动作，自动命中仍依赖模型判断。
- Agent 必须具备访问公司内网及其认证的权限；sandbox 或网络策略可能阻止拉取。
- description 不应要求 Agent 把 Sub2API API Key 转发给内网服务。
- 内网资源宜提供版本或内容 hash，避免同一个 description 指向的内容静默漂移。
- 提示词注入不是安全强制机制；必须强制执行的企业策略仍需独立权限和服务端控制。

## 建议

若要求每个 API Key 独立配置，并确保 Codex 原生 Responses 请求生效，采用上述最小 Sub2API 扩展。若所有 Key 完全共用一条 description，可暂时使用现有全局模板验证交互文案，但它不是完整交付方案。

本轮仅完成只读源码调查和方案收敛，未修改 Sub2API 源码、版本、配置或运行面。
