一、为什么要先做仓库知识包

很多团队在使用 Codex 时，习惯把当前问题、几段代码和一句“帮我改一下”直接发出去。简单任务这样做没问题，但一旦涉及跨文件修改、接口联动、旧逻辑兼容、测试补齐，缺少上下文就会让 Codex 只能猜。猜得越多，人工复查成本越高。

仓库知识包的作用，就是把项目里反复需要解释的**资料提前整理好。灵能API提供统一 API 中转站入口，CC Switch保存项目对应配置，而知识包则告诉 Codex：这个仓库怎么组织、核心模块在哪里、接口如何命名、哪些边界不能随便改。

二、知识包不是把整个仓库塞进去

仓库知识包不是全量复制项目文件。它更像一份经过筛选的导航图，只保留 Codex 做判断时最需要的信息。信息太少会导致模型猜测，信息太多又会稀释重点，甚至把无关旧逻辑带进当前任务。

整理知识包时，重点不是追求资料多，而是让资料可判断。Codex 看到一份清楚的资料包，会比看到几十个无标注文件更容易给出靠谱建议。

• 保留：目录结构、核心模块说明、接口约定、错误码规则、测试命令、发布注意点。
• 压缩：历史**、重复文档、旧版本说明、已经废弃的接口说明。
• 剔除：完整密钥、真实用户数据、内部账号、无关日志、临时调试输出。
• 标记：仍在使用、准备废弃、只读参考、禁止修改的模块。

三、先确认灵能API入口与模型范围

在整理知识包之前，先进入灵能API https://www.lnsns.com/，确认 API *ase、可用模型、账号状态和团队当前使用策略。知识包通常会配合较长上下文任务使用，因此模型范围和响应稳定性都要提前核对。

团队文档里可以把灵能API写成可点击链接，方便成员回到统一入口核对信息。需要注意的是，知识包里不要保存完整 Key，也不要把账号截图当成项目资料长期分发。

四、按项目建立 CC Switch 配置卡

如果团队同时维护多个项目，不建议所有项目共用同一张 CC Switch 配置卡。不同项目的语言栈、目录结构、测试命令、代码风格都不一样，配置卡和知识包最好一一对应。

这样做的好处是边界清楚。成员不会把项目 A 的规则带到项目 *，也不会在简单问答里加载过重的上下文。

• project-a-codex-context：项目 A 的开发与审阅配置，绑定项目 A 知识包。
• project-*-codex-api-do**：项目 * 的接口文档配置，重点处理接口说明和调用示例。
• project-c-codex-test-helper：项目 C 的测试补齐配置，重点读取测试规范。
• shared-codex-light：轻量问答配置，不默认加载大型知识包。

五、知识包建议包含哪些文件

第一版知识包不需要做得太大。建议从 6 类文件开始，每类文件都要短、准、能验证。文件名也要清楚，方便成员和 Codex 都能理解它的用途。

repo-context/
  01-overview.md          项目目标、核心业务、主要角色
  02-directory-**p.md     目录结构、模块归属、禁止随意改动区域
  03-api-contracts.md     接口命名、请求响应、错误码约定
  04-code-style.md        代码风格、依赖规则、常见模式
  05-test-guide.md        测试命令、测试数据、验收标准
  06-release-notes.md     发布流程、回滚提醒、观察指标

这些文件不必追求一次写完。可以先覆盖最常被问到的内容，再随着 Codex 使用过程不断补充。每次发现模型因为缺少某个**而答偏，就把这个**沉淀进对应文件。

六、目录结构要写给人看，也写给 Codex 看

目录结构文档不要只复制 tree 输出。更有价值的是解释每个关键目录负责什么、谁维护、哪些目录可以修改、哪些目录只读参考。Codex 做跨文件修改时，最需要这类边界信息。

目录说明示例：
/src/api       接口封装层，新增接口优先放这里
/src/do**in    业务规则层，修改前需要确认对应测试
/src/ui        页面组件层，不直接写请求逻辑
/tests         单元测试与集成测试，新增功能必须补测试
/scripts       本地维护脚本，禁止写入真实账号与密钥

这种说明能让 Codex 更快判断修改位置，而不是在多个目录之间来回试探。对新人也有帮助，因为它本质上就是项目导航文档。

七、接口文档要补上真实约束

接口文档如果只写路径和字段，Codex 仍然容易漏掉业务限制。更适合 AI 协作的接口文档，要补上鉴权方式、错误码、幂等规则、分页规则、限流提示和兼容要求。

灵能API https://www.lnsns.com/ 负责中转接入，项目自己的接口文档则负责业务上下文。两者不要混在一起：一个解决模型调用入口，一个解决项目知识表达。

• 鉴权：接口是否需要登录态、服务端签名或内部调用权限。
• 错误码：哪些错误可以重试，哪些错误必须直接提示用户。
• 兼容性：新增字段是否可选，旧客户端是否能忽略。
• 幂等性：重复提交是否会产生重复数据。
• 观察点：接口上线后看哪些日志、状态码和业务指标。

八、测试指南要能直接执行

让 Codex 帮忙补测试时，最怕只告诉它“补一下测试”。知识包里的测试指南应该明确测试框架、命令、目录、命名规则、哪些场景必须覆盖，以及测试失败时先看哪里。

测试指南字段：
测试框架：
单元测试命令：
集成测试命令：
测试文件命名：
Mock 数据位置：
必须覆盖场景：正常路径 / 参数异常 / 权限失败 / 边界值
提交前验收：

如果这些内容已经整理好，Codex 生成测试时会更贴合项目习惯。否则它可能生成一个语法上没问题、但完全不符合团队测试结构的文件。

九、脱敏规则要写在知识包最前面

知识包要长期复用，脱敏规则必须放在明显位置。不要依赖成员每次临时判断哪些内容能发、哪些不能发。规则越明确，协作越顺。

脱敏规则不只是安全要求，也能提高输出质量。Codex 看到清楚的假数据和真实字段含义，会比看到一堆混乱的真实日志更容易分析。

• 禁止放入：完整 Key、真实手机号、邮箱、***、支付信息、**账号。
• 可以替换：用户 ID、订单号、接口域名、内部项目代号。
• 可以概括：业务规模、客户名称、内部流程细节。
• 必须标注：示例数据是否为假数据，错误日志是否已脱敏。

十、给 Codex 的知识包使用提示词

知识包准备好后，还需要一段固定提示词告诉 Codex 如何使用它。重点是要求先读规则、再判断任务类型、最后输出**证结果。

提示词模板：
你将基于 repo-context 中的资料处理当前任务。
请先读取项目概览、目录结构、接口约定和测试指南。
不要修改标记为只读或禁止改动的模块。
如果资料不足，请列出缺失信息，不要自行补全。
输出必须包含：修改建议、涉及文件、验证方式、风险提醒。

这段提示词可以和 CC Switch 配置卡一起保存。成员每次切换到项目配置时，就能沿用同一套上下文规则，减少临时沟通。

十一、知识包要有版本记录

知识包不是一次性资料。项目目录会变，接口会变，测试命令会变，发布流程也会变。如果知识包长期不更新，Codex 反而会基于旧信息给出错误建议。

知识包版本记录：
日期：
修改文件：
修改原因：
影响任务：开发 / 审阅 / 测试 / 文档 / 发布
负责人：
是否需要通知团队：是 / 否

版本记录不需要很复杂，但要让成员知道什么时候更新过、为什么更新。尤其是接口约定和测试命令，一旦变化，就应该同步更新知识包。

十二、当 Codex 答偏时，先修知识包

如果 Codex 输出不理想，不要马上认为模型不行。先检查输入资料：是不是目录说明缺失、接口约束没写、测试命令过期、只读模块没有标注。很多偏差其实是上下文质量问题。

这种修复方式很划算。修一次知识包，后续很多任务都会受益；只在单次对话里纠正，下一次还可能重复踩坑。

• 答错目录：补充目录结构和模块职责。
• 漏掉测试：补充测试指南和提交前验收。
• 接口理解错误：补充请求响应、错误码和兼容规则。
• 建议过度修改：补充禁止改动区域和最小修改原则。

十三、完整落地顺序

• 第一步：进入灵能API https://www.lnsns.com/，确认 API *ase、模型范围和账号状态。
• 第二步：按项目建立 CC Switch 配置卡，不同项目不要混用上下文。
• 第三步：整理项目概览、目录结构、接口约定、代码风格、测试指南和发布提醒。
• **步：把脱敏规则放在知识包最前面，避免敏感信息进入资料。
• 第五步：写一段固定提示词，要求 Codex 按知识包规则处理任务。
• 第六步：用小任务验证知识包是否有效，再扩展到复杂任务。
• 第七步：每次答偏都回头更新知识包，而不是只修单次对话。

✅ 十四、结语：好的上下文，比临时堆文件更重要

Codex API 中转站接入完成后，团队真正要持续打磨的是上下文质量。灵能API提供统一入口，CC Switch负责不同项目配置，仓库知识包负责把项目经验变成可复用资料。

当 Codex 能稳定读到项目概览、目录边界、接口规则、测试方式和脱敏要求时，它给出的建议会更贴近真实工程。与其每次临时解释一遍项目**，不如把这些**沉淀下来，让每一次调用都站在更清楚的上下文上。