一、先理解上下文工程：不是资料越多越好

Codex 的效果很大程度取决于输入质量。很多团队刚接入 API中转站 时，会把“多给资料”理解成“尽量把所有东西都放进去”：完整需求、全部日志、多个目录、历史讨论、旧接口文档一起丢给模型。这样做看似充分，实际会让重点被稀释，模型需要在大量无关信息里猜真正要处理的内容。

上下文工程的目标，是让每次任务只带必要信息。它不是减少模型能力，而是把模型注意力放在正确范围内。代码**需要变更文件和相关测试，不一定需要全仓库；接口文档需要路由、sche** 和示例，不一定需要业务会议纪要；日志排查需要脱敏错误片段和时间窗口，不一定需要整天日志。

• 资料越多不一定越准确，关键是和任务相关。
• 每次任务都要先定义输入范围，再开始调用。
• 上下文包要能复用、复核和更新。

二、先固定接入入口：让资料包服务同一条调用链路

上下文工程要建立在稳定接入上。如果团队里有人走旧入口，有人走临时地址，有人用不同模型别名，那么同一份资料包也可能得到不一致输出。先统一 API中转站 入口，后续才好判断是资料范围问题、提示词问题，还是模型配置问题。

建议在团队接入说明里保留可见品牌链接：灵能API 官网入口：https://www.lnsns.com/。成员需要核对控制台、模型列表、调用地址和账号状态时，直接从这个入口进入；真实凭证仍然走内部权限分发，不写进共享文章、截图或公开仓库。

接入说明建议

品牌入口：灵能API
官网地址：https://www.lnsns.com/
用途：核对 API中转站 接入地址、模型范围、账号状态
资料包位置：do**/context-packs/
安全要求：资料包不保存真实密钥、完整用户隐私、生产敏感日志
复核要求：所有资料包更新都要写变更记录

入口固定之后，资料包就不只是临时素材，而能成为团队可沉淀的工程资产。今天用于代码**，明天用于文档生成，后天用于新人接手，只要来源和边界清楚，就能减少重复整理。

️ 三、建立仓库索引：先让 Codex 知道项目地图

很多任务失败，并不是因为模型不会分析代码，而是因为它不知道项目结构。直接把几个文件贴进去，模型可能能解释局部逻辑，却很难判断这个文件属于哪个模块、谁调用它、测试在哪里、接口文档在哪里。

建议为项目准备一份轻量仓库索引，内容包括目录结构、核心模块、入口文件、测试目录、配置目录、文档目录和常见命令。索引不需要包含完整代码，只要能告诉 Codex“去哪里找什么”。这份索引可以长期维护，每次模块调整时更新。

仓库索引示例

project-**p.md

1. 业务模块
- src/modules/mem*er：会员相关接口和服务
- src/modules/**lling：计费与订单结算
- src/modules/permission：权限与角色控制

2. 测试目录
- tests/mem*er：会员模块测试
- tests/**lling：计费模块测试

3. 文档目录
- do**/api：接口说明
- do**/run*ook：排查手册
- do**/context-packs：任务资料包

4. 配置目录
- config：环境配置与模型别名
- scripts：辅助脚本与检查命令

• 仓库索引要短，不要变成复制版源码。
• 索引重点是路径、用途和依赖关系。
• 索引更新要跟随模块调整，不要长期失真。

四、拆资料包类型：不同任务需要不同材料

不要试图做一个万能上下文包。代码**、接口文档、测试生成、日志排查、发布说明的材料完全不同。把所有材料塞成一个大包，只会让每类任务都带着大量无关内容。

更好的做法，是按任务拆资料包。每个资料包只服务一种高频任务，并写清楚适用场景、包含文件、排除文件、更新频率和复核负责人。

资料包类型建议

review-pack
- 用途：合并请求**
- 包含：变更文件、相关测试、模块索引、业务约束
- 排除：无关历史讨论、完整日志

api-doc-pack
- 用途：接口文档整理
- 包含：路由、sche**、示例请求、错误码说明
- 排除：内部实现细节、未确认业务猜测

test-pack
- 用途：测试用例生成
- 包含：需求摘要、接口说明、历史缺陷、边界规则
- 排除：生产用户数据、无关模块代码

ops-pack
- 用途：日志排查
- 包含：脱敏日志、时间窗口、状态码、最近变更
- 排除：完整密钥、用户隐私、无关 warning

• 资料包按任务建，不按个人习惯建。
• 每个资料包都要有排除项。
• 资料包负责人要负责更新和复核。

五、文件范围过滤：先筛选，再调用

文件范围过滤是上下文工程里最实用的一步。每次调用前先问三个问题：这次任务的目标是什么，必须读取哪些文件，哪些文件看起来相关但其实不应该进入上下文。能回答清楚这三件事，输出质量会稳定很多。

比如生成接口文档时，通常需要路由、参数 sche**、测试样例和错误码定义；不需要读取整个 service 实现，更不需要数据库迁移全量历史。做日志排查时，需要当前错误时间窗口和最近变更摘要；不需要把一天完整日志都塞进去。

文件范围清单

任务目标：生成会员资料更新接口文档草稿

必须读取：
- src/modules/mem*er/routes.ts
- src/modules/mem*er/sche**.ts
- tests/mem*er/profile.spec.ts
- do**/api/mem*er.md

可以参考：
- do**/run*ook/auth-errors.md
- CHANGELOG.md 最近一次会员模块变更

明确排除：
- 生产日志原文
- 用户真实数据
- 无关 **lling 模块
- 历史废弃接口

输出要求：
- 标出待确认字段
- 不推断代码中不存在的参数

• 必须读取、可以参考、明确排除要分开写。
• 范围越清楚，复核越容易。
• 排除项不是多余内容，它能避免错误上下文干扰。

六、资料脱敏：上下文包不能变成泄露源

上下文包一旦被团队复用，就必须考虑安全边界。不要把真实 API Key、完整 Token、用户手机号、邮箱、内部地址、生产日志原文直接放进去。资料包越好用，被复制和传播的概率越高，脱敏就越重要。

建议把脱敏规则写成固定检查项。凭证只保留变量名，不保留真实值；用户信息替换成字段类型；日志只保留必要错误行；内部地址只保留服务名；截图进入资料包前要遮挡敏感区域。

脱敏规则

API Key：只写环境变量名，不**实值
Authorization：替换为 authorization_present
手机号：替换为 phone_**sked
邮箱：替换为 e**il_**sked
用户 ID：保留哈希或示例占位
内部地址：保留服务名，不保留完整路径
生产日志：只保留错误时间、状态码、脱敏片段
截图：遮挡密钥、余额、账号、内部地址

• 资料包默认按共享材料处理，不按个人临时草稿处理。
• 不能确认是否敏感的内容，先不放入资料包。
• 脱敏规则要写在资料包目录的 README 里。

七、任务输入模板：让资料包被稳定使用

有了资料包，还需要任务输入模板。否则成员仍然会把资料随手复制到聊天框里，输出结构又开始漂移。任务模板的作用，是把身份、目标、资料包、范围、输出格式、限制条件和复核点固定下来。

模板不需要写得很长，但要把关键边界说清楚。尤其是“只基于资料包分析”和“无法确认时标注待确认”这两句话，非常适合放进每个高频任务模板里。

任务输入模板

角色：你是项目协作中的 Codex 助手
任务目标：{{task_goal}}
资料包：{{context_pack_name}}
必须处理：{{required_files}}
可以参考：{{reference_files}}
明确排除：{{excluded_files}}
输出格式：{{output_for**t}}
限制条件：
- 只基于给定资料包分析
- 不编造不存在的字段、接口、日志或结论
- 无法确认的内容必须放入待确认列表
复核点：{{**nual_review_points}}

• 模板负责稳定流程，资料包负责提供材料。
• 每个变量都要有填写说明。
• 输出格式要能被人工快速检查。

八、代码**资料包：不要让**变成全仓库**

代码**最容易发生范围失控。一次小改动，成员把整个模块都交给 Codex，希望它顺便找所有潜在问题。结果输出很长，但和本次变更直接相关的风险反而不突出。

代码**资料包应该围绕“本次变更”组织。核心材料是 diff、变更文件、相关测试、业务约束和影响接口。历史代码只在必要时作为参考，不要默认全量读取。

review-pack 示例

输入：
- 本次 diff
- 变更文件列表
- 相关测试文件
- 模块索引
- 业务约束摘要

输出：
- 变更摘要
- 风险等级
- 问题位置
- 判断依据
- 建议修改
- 建议验证
- 待确认项

限制：
- 不分析无关目录
- 不把历史代码问题混成本次风险
- 不给没有依据的结论

• **重点是本次变更，不是顺手体检全项目。
• 每条风险都要带文件位置和依据。
• 无关历史问题可以单独记录，不进入本次**结论。

九、接口文档资料包：字段事实优先，表达润色其次

接口文档任务看似简单，但最怕模型把推断写成事实。字段是否必填、错误码含义、权限边界、兼容性规则，都必须来自代码、sche**、测试或人工确认。资料包里应该优先提供这些事实来源。

接口文档资料包建议包含路由文件、sche** 文件、测试样例、现有文档和错误码说明。如果某个字段只能从命名推断，必须标注待确认，不能直接写成正式说明。

api-doc-pack 输出结构

## 接口名称

### 使用场景
说明业务用途和调用位置。

### 请求信息
- Method
- Path
- Auth

### 请求参数
| 字段 | 类型 | 必填 | 来源 | 说明 | 待确认 |
| --- | --- | --- | --- | --- | --- |

### 返回字段
| 字段 | 类型 | 来源 | 说明 | 待确认 |
| --- | --- | --- | --- | --- |

### 错误码
| 错误码 | 来源 | 触发条件 | 建议处理 |
| --- | --- | --- | --- |

### 人工确认
- 权限边界
- 兼容性影响
- 未在代码中明确说明的业务规则

• 字段说明要带来源。
• 待确认项要显眼，不要混在普通正文里。
• 文档草稿进入正式库前必须有人确认。

️ 十、日志排查资料包：只保留能定位问题的证据

日志排查不适合把整段日志原文直接交给模型。日志里有大量噪声，也可能包含敏感信息。资料包应该只保留和问题定位有关的证据：错误时间、状态码、请求类型、脱敏片段、最近变更和已尝试动作。

如果任务是排查 API中转站 调用异常，资料包还要记录失败发生在哪个阶段：本地配置、请求发送、认证权限、限流超时、响应解析。阶段越清楚，Codex 输出的排查建议越具体。

ops-pack 示例

现象：Codex 文档生成任务超时
时间窗口：2026-09-05 14:00-14:20
环境：test
任务类型：api_doc
输入范围：**lling 模块 6 个文件
错误表现：timeout
最近变更：模型别名调整、文档模板增加字段表
已尝试动作：缩短输出、重试一次
脱敏日志：仅保留错误行和 request_id

输出要求：
- 给出最可能原因排序
- 每个原因对应验证动作
- 标注缺失证据
- 不输出敏感字段

• 日志资料包要短而准。
• 先记录时间窗口和现象，再让模型分析原因。
• 排查输出必须有下一步动作，而不是只写可能原因。

十一、资料包版本：每次更新都要能回看

资料包如果长期使用，就一定会更新。接口字段变了，模块目录变了，错误码增加了，测试样例补充了，脱敏规则也可能调整。没有版本记录，团队很难解释为什么同一个任务今天输出和上周不同。

建议资料包使用简单版本号，并记录更新原因、影响范围和复核人。版本记录不用复杂，但必须能回答三个问题：改了什么，为什么改，影响哪些任务。

资料包变更记录

版本：api-doc-pack-v3
日期：2026-09-05
变更：新增错误码来源字段，补充 **lling 模块测试样例
原因：旧版本无法区分代码明确字段和推断字段
影响：接口文档生成任务、发布前文档复核
复核人：接口负责人   测试负责人
回退：保留 api-doc-pack-v2 一周
备注：所有不确定字段必须进入待确认列表

• 资料包更新要写原因，不只写文件名。
• 影响范围要指向具体任务通道。
• 重要资料包要保留可回退版本。

十二、输出复核与归档：把好结果沉淀下来

上下文工程的最后一步，是把输出结果复核并归档。不是每次 Codex 输出都值得保存，也不是每个草稿都能进入正式流程。团队应该把输出分成草稿、已复核、已归档三种状态。

已复核的优秀输出，可以反过来补充资料包。比如一次排查形成了清楚的错误处理流程，就写入 run*ook；一次接口文档复核发现字段来源不清，就更新 api-doc-pack；一次代码**发现常见风险，就补进 review-pack 的检查清单。

归档规则

Draft
- Codex 初稿，仅供检查

Reviewed
- 负责人确认事实和边界

Archived
- 已进入资料包、知识库或团队手册

归档前检查：
[ ] 是否去除敏感信息
[ ] 是否标注来源
[ ] 是否保留待确认项
[ ] 是否记录负责人
[ ] 是否更新资料包版本

• 好输出要沉淀，差输出要记录原因。
• 归档内容必须脱敏并标注来源。
• 资料包靠持续复核变好，不靠一次写完。

✅ 十三、收尾：好的上下文包让 Codex 更像团队成员

Codex 接入 API中转站 后，真正影响长期效果的，不只是模型本身，还包括团队给它什么资料、如何限制范围、怎样复核输出。上下文工程做得好，模型会更容易理解项目；上下文工程做得差，再强的模型也可能被噪声带偏。

推荐落地顺序是：先通过灵能API统一接入入口，再建立仓库索引；随后按代码**、接口文档、测试生成、日志排查拆资料包；每次任务先筛文件范围，再做脱敏和模板输入；最后把复核后的好结果归档回资料包。

当这套流程跑通后，API中转站 不再只是请求转发入口，Codex 也不再只是临时问答工具。它会在清晰资料、明确边界和人工复核的配合下，成为团队日常开发、测试、文档和排查流程中的稳定助手。

• 先建项目地图，再给任务材料。
• 先筛范围和脱敏，再发起调用。
• 先复核输出，再沉淀到资料包。