codex-evolution

让 Codex 记住你在每个项目里的协作偏好。

如果你经常反复告诉 Codex：

• “复杂需求先讨论方案，再进入实现”
• “这个项目用中文沟通”
• “发布前先更新版本号和 CHANGELOG”
• “不要改用户已有的 AGENTS.md”

codex-evolution 会把这些长期可复用的项目经验沉淀到本地 SQLite，并在下一次会话开始时自动注入给 Codex。你不需要手动维护一堆规则文件，也不需要每次开新会话都重新交代一遍。

为什么值得安装

• 适配 Codex 客户端和命令行：通过 Codex SessionStart hook 注入上下文，直接打开客户端也能生效。
• 不污染用户项目文件：不默认改写 AGENTS.md，也不托管 AGENTS.override.md。
• 只学习长期协作规则：过滤“继续”“可以”“ok”等噪音，候选经验需要重复支撑才会升级为 active。
• 本地优先，可控可删：prompt、经验和运行状态都保存在本机 ~/.codex-evolution。
• 中文体验友好：初始化、doctor、help、状态检查都优先输出中文。

当前能力：

• project_key 隔离
• UserPromptSubmit hook 采集 prompt
• SessionStart hook 注入项目经验
• candidate -> active 经验晋升
• 重复支撑会提升经验置信度，避免稳定经验被单次低分覆盖
• 经验重整、衰减与归档
• openai-compatible / codex-exec 学习 provider

核心思路

和直接改全局 AGENTS.md 不同，codex-evolution 走的是 hooks + 本地记忆路线：

• 通过 UserPromptSubmit hook 收集用户 prompt
• 后台定期用可配置 LLM 提取长期项目经验
• 系统根据当前目录识别项目
• 从本地数据库读取该项目经验
• 通过 SessionStart hook 在会话开始时注入上下文
• cdxe 负责初始化、安装 hooks、诊断、手动学习和启动底层 codex

经验如何变得稳定

codex-evolution 不会把每一句话都立刻写进上下文。它会先把单次命中的长期规则放进 candidate，等语义相近的 prompt 再次出现后才升级为 active。

经验被重复支撑后，系统会给它更稳定的置信度下限：

• 2 条 prompt 支撑：confidence 至少 0.7
• 3 条 prompt 支撑：confidence 至少 0.8
• 5 条 prompt 支撑：confidence 至少 0.9

如果已有经验的置信度更高，后续命中不会因为 LLM 单次打低分而被降下来。长期不再命中的经验会逐步从 active 进入 decaying，最后归档为 archived，不再注入上下文。

30 秒开始

npm install -g codex-evolution
cdxe

首次启动会自动初始化本地数据库、安装 hooks，并引导你配置学习模型。

进入 Codex 后执行：

/hooks

然后 trust 这两条命令：

• UserPromptSubmit：采集你的 prompt，用于后续学习
• SessionStart：会话开始时注入项目经验

完成后，即使你后续直接从 Codex 客户端打开项目，也会在 SessionStart 时读取当前目录的项目经验并注入到本次会话。

日常只记住 4 个命令

cdxe                  # 启动 Codex，并确保初始化流程已完成
cdxe doctor           # 检查 hooks、学习模型、自动学习和上下文注入是否健康
cdxe context:preview  # 预览当前项目会注入给 Codex 的经验
cdxe scheduler:tick   # 手动触发一次经验提取

目录结构

• src/cli.js: CLI 入口
• src/hooks: Codex hooks、prompt 采集与 SessionStart 注入
• src/reconciliation: 经验重整
• src/runtime: 运行时上下文渲染
• src/providers: 学习 provider
• src/storage: SQLite 与 repositories

快速开始

安装

全局安装：

npm install -g codex-evolution

安装后推荐直接使用：

cdxe

完整命令也保留可用：

codex-evolution

开发联调时也可以直接在仓库里：

npm link

首次启动

直接运行推荐使用短命令：

cdxe

完整命令也同样可用：

codex-evolution

如果你还没做全局安装，也可以直接本地运行：

npm start

如果想把命令链接到全局：

npm link
cdxe -help

查看中文帮助：

cdxe -help
codex-evolution -help

如果你想快速跑一轮完整体验，不自己手动造 prompt，可以直接执行：

cdxe demo:experience

或者：

npm run demo:e2e

如果想重新体验初始化流程：

cdxe onboarding:reset

如果想连学习模型配置一起清掉，重新走完整初始化：

cdxe onboarding:reset --include-config

首次启动现在会自动做这些事：

• 初始化本地 SQLite 数据库
• 检查并自动安装 UserPromptSubmit 与 SessionStart hooks
• 在终端明确提醒你：进入 Codex 后需要执行 /hooks 并 trust 这两条命令
• 如果还没配置学习模型，进入一次简短引导
• 连通性检查通过后，可选开启后台自动学习

trust 完成后，即使你后续直接从 Codex 客户端打开项目，也会在 SessionStart 时读取当前目录的项目经验并注入到本次会话。

如果你更喜欢手动控制，也可以继续用下面这些显式命令。

升级

如果你是全局安装的，升级到最新版：

npm install -g codex-evolution@latest

升级后建议执行一次：

cdxe doctor

卸载

由于 npm 不会自动帮我们执行卸载清理，推荐先运行：

cdxe cleanup

如果你还想一并删除本地数据库、状态文件和日志：

cdxe cleanup --include-home

然后再卸载全局包：

npm uninstall -g codex-evolution

1. 初始化数据库

cdxe db:init

2. 安装 hooks

cdxe hooks:install

检查 hook 是否真的安装并被 Codex trust：

cdxe hooks:doctor

如果你只想移除 hook：

cdxe hooks:uninstall

想一次性检查整套系统是否健康：

cdxe doctor

如果你想直接查看 SQLite 里最近收集到的 prompt：

cdxe prompts:list
cdxe prompts:list --limit 50
cdxe prompts:list --guidance-only
cdxe prompts:list --pending-only
cdxe prompts:list --json

如果你想拿结构化输出：

cdxe doctor --json

如果你希望它顺手自动修一部分本地问题：

cdxe doctor --fix

3. 初始化学习 provider 配置

默认生成 openai-compatible 配置：

cdxe config:init

如果你只想继续试 codex-exec：

cdxe config:init codex-exec

配置模板见：

• config.example.json

4. 填学习模型配置

默认配置文件位置：

~/.codex-evolution/config.json

本地调试时也可以用：

CODEX_EVOLUTION_HOME=.codex-evolution-local npm start -- config:init

例如：

{
  "reconcile": {
    "provider": "openai-compatible",
    "model": "gpt-4.1-mini",
    "baseURL": "https://api.openai.com/v1",
    "apiKeyEnv": "OPENAI_API_KEY"
  }
}

说明：

• baseUrl 和 baseURL 都支持
• 也可以不用内嵌 apiKey，改用 apiKeyEnv
• 环境变量优先级高于配置文件

5. 验证配置

查看当前实际解析出来的配置：

cdxe config:show

这里会同时显示：

• configPath
• statePath
• configFileExists
• 脱敏后的学习 provider 配置摘要

探测学习 provider 是否可用：

cdxe reconcile:probe

6. 跑一次真实学习

cdxe scheduler:tick

6.1 一键体验完整链路

如果你已经配好了学习 provider，想快速验证：

• prompt 入库
• 学习执行
• 经验生成
• 上下文更新

可以直接跑：

cdxe demo:experience

它会在当前项目根目录下创建一个隔离的 demo home：

<project>/.codex-evolution-demo

默认行为：

• 注入 3 条示例 prompt
• 执行一次真实学习
• 输出最终经验和运行时上下文预览

如果你想保留上一次 demo 数据，不重置 demo home：

cdxe demo:experience --keep-home

如果你想拿结构化结果：

cdxe demo:experience --json

7. 启动持续学习循环

cdxe scheduler:watch --interval-seconds 3600

如果想把后台自动学习交给系统托管，也可以用：

cdxe scheduler:enable --interval-seconds 3600

调试时可以只跑一次：

cdxe scheduler:watch --interval-seconds 5 --max-runs 1

8. 查看学习结果

cdxe reconcile:status
cdxe context:preview

9. 停止或关闭后台自动学习

临时停止当前 watcher：

cdxe scheduler:stop

彻底关闭自动学习，并阻止后续启动时自动拉起：

cdxe scheduler:disable

查看后台自动学习日志：

cdxe scheduler:logs
cdxe scheduler:logs --lines 200

常用命令

cdxe [codex args...]
cdxe db:init
cdxe cleanup [--include-home]
cdxe demo:experience [path] [--keep-home] [--json]
cdxe config:init [provider] [--force]
cdxe config:show
cdxe doctor [path] [--fix] [--json]
cdxe onboarding:reset [--include-config]
cdxe hooks:install [hooks-path]
cdxe hooks:doctor
cdxe hooks:uninstall [hooks-path]
cdxe hook:user-prompt-submit
cdxe hook:session-start
cdxe prompts:list [path] [--limit N] [--guidance-only] [--ignored-only] [--pending-only] [--json]
cdxe project-key [path]
cdxe reconcile:probe [path]
cdxe reconcile:status [path]
cdxe reconcile:prepare [path]
cdxe reconcile:apply <run-id>
cdxe reconcile:decay [path]
cdxe scheduler:tick [path]
cdxe scheduler:enable [--interval-seconds N]
cdxe scheduler:stop
cdxe scheduler:disable
cdxe scheduler:logs [--lines N]
cdxe scheduler:watch [path] [--interval-seconds N] [--max-runs N]
cdxe context:preview [path]

codex-evolution 完整命令名与 cdxe 等价，文档里默认使用短命令。

发布到 npm

当前机器的默认 npm registry 如果不是官方源，发布前请先确认：

npm config get registry

这个项目已经在 package.json 里设置了：

• publishConfig.registry = https://registry.npmjs.org/

所以正常发布时会优先走官方 npm registry。

推荐发布前执行：

npm test
env npm_config_cache=$(pwd)/.npm-cache npm pack --dry-run
npm publish --registry https://registry.npmjs.org/

如果你想先确认当前登录的官方 npm 账号，也可以执行：

npm whoami --registry https://registry.npmjs.org/

学习 provider

codex-exec

优点：

• 零额外配置
• 直接复用本机 codex

限制：

• 容易受本机 Codex 网络、认证、skills 环境影响

openai-compatible

优点：

• 更稳定
• 更容易接 OneAPI / OpenRouter / 兼容网关
• 不依赖 codex exec

要求：

• 兼容 POST /chat/completions
• 返回标准 chat completion JSON

reconcile:status 会看什么

这个命令会输出：

• 当前项目 project_key
• 当前生效的学习 provider 配置摘要
• 当前 auto-learning 状态
• prompt 总数 / pending 数
• 最近 5 次 reconciliation run
• 当前 active/decaying experiences

它是目前最直接的“学习链有没有在工作”的观察入口。

doctor 会看什么

doctor 默认会做一轮完整健康检查，并且会真实调用当前学习 provider 做一次 probe。

它会检查：

• 本地目录、配置文件、数据库和核心表是否正常
• 当前目录如何解析为 project_key
• UserPromptSubmit / SessionStart hooks 是否安装、启用、已 trust
• 当前学习 provider 是否真实可用
• 当前项目 prompt / learning run / experience 状态
• 自动学习 watcher 是否运行、锁文件和日志是否正常
• 运行时上下文是否可正常渲染

默认输出是中文摘要，适合人直接看：

cdxe doctor

如果你愿意让它自动修一部分安全的本地问题，例如：

• 初始化/修复数据库
• 自动安装缺失的 Codex hooks
• 当自动学习本来就已开启但 watcher 挂掉时，尝试重新拉起

可以用：

cdxe doctor --fix

如果你想让别的脚本消费结果，可以用：

cdxe doctor --json

当前验证状态

当前代码已经验证过这些链路：

• UserPromptSubmit prompt 入库
• scheduler:tick 经验提取
• context:preview 上下文预览
• SessionStart hook 返回 additionalContext
• hooks:install 同时安装 UserPromptSubmit 与 SessionStart
• hooks:doctor 检查双 hook 安装和 trust 状态
• cdxe 默认透传启动参数，避免重复注入 developer_instructions

并且测试已覆盖：

• provider 配置解析
• prompt 入库
• 经验重整
• 衰减
• 配置初始化与展示
• 运行时上下文渲染
• SessionStart fail-open
• 双 hook 安装、卸载与诊断

测试

npm test

发布前检查

发布前建议至少执行：

npm run release:check

如果你只想看最终会被发布哪些文件：

npm run pack:check

建议发布流程：

1. npm test
2. npm run pack:check
3. 先更新 package.json 中的版本号
4. 再更新 CHANGELOG.md
5. 再执行 npm publish