Codex on 拾光集

让 Codex 越用越聪明：用一套长期规则积累项目经验

Sat, 25 Jul 2026 22:38:00 +0800

很多人在使用 Codex 时，会遇到一个明显的问题：

同样的错误反复出现，同样的项目规范需要重复说明，每次开始新任务，都像重新认识一个陌生的助手。

想解决这个问题，单靠一句“记住我的习惯”并不够。更有效的方法，是通过一段初始化提示词，为 Codex 建立一套长期工作规则，让它主动记录经验、复盘问题，并在新项目开始前读取这些规则。

这套方法的核心，是让 Codex 自动创建并持续维护三个文档：

全局工作台
全局复盘日志
新项目 SOP

它们共同组成一套可持续积累的项目知识库。

一、为什么要建立长期工作规则？

Codex 很擅长执行当前任务，但它并不会天然理解你的全部开发习惯。

例如，你可能希望它：

修改代码前先理解项目结构；
尽量只改动必要文件；
不要随意重构无关代码；
每次修改后说明改了什么；
遇到错误时记录原因和解决办法；
创建新项目时使用统一目录和命名方式。

如果每次都重新输入这些要求，不仅麻烦，也容易遗漏。

因此，更合理的做法不是不断追加临时提示词，而是建立一套固定文档，让 Codex 在工作前主动读取，在工作后持续更新。

二、三个核心文档分别做什么？

1. 全局工作台

全局工作台相当于 Codex 的“工作说明书”。

它主要用于规定 Codex 的通用行为，例如：

开始任务前需要检查哪些内容；
修改代码时应遵守什么原则；
哪些文件可以修改，哪些文件不要轻易触碰；
项目文档分别放在哪里；
不同规则文件之间如何配合；
完成任务后需要输出哪些说明。

全局工作台还可以作为整个规则体系的目录，帮助 Codex快速找到其他文档。

简单来说，它解决的是：

Codex 应该按照什么方式工作。

2. 全局复盘日志

全局复盘日志用于记录实际工作中出现过的问题。

可以写入的内容包括：

曾经修改错误的文件；
因不了解项目结构导致的问题；
重复出现的命令错误；
构建、测试或部署失败的原因；
用户已经明确否定过的方案；
已经验证有效的解决方法；
今后遇到类似问题时应如何处理。

复盘日志不是普通的操作记录，而是一份可复用的经验库。

每完成一个重要任务，Codex 都可以检查：

这次是否出现了错误；
错误为什么发生；
下次如何避免；
有没有可以复用的方法。

这样做的意义在于，同一个坑尽量只踩一次。

3. 新项目 SOP

新项目 SOP 用来规定创建新项目时的标准流程。

例如可以要求：

每个项目必须使用独立文件夹；
项目名称采用统一格式；
创建 README、任务记录和状态文档；
开发前先确认技术栈和目录结构；
不在桌面或临时目录随意堆放文件；
初始化 Git 仓库并配置忽略文件；
重要操作前先备份；
完成初始搭建后记录项目状态。

它解决的是：

新项目应该按照什么顺序开始。

有了这份 SOP，即使同时管理多个项目，也能尽量保持目录、文档和操作方式一致。

三、把规则写入 Agent.md

三个文档创建完成后，还需要在项目的核心规则文件中加入一条最高优先级指令。

常见文件名可能是：

1
2
3

AGENTS.md
Agent.md
agents.md

具体名称需要根据 Codex 当前使用的规则机制和项目结构决定。

可以在其中写入类似规则：

执行任何新项目或重要任务之前，必须先阅读全局工作台、全局复盘日志和新项目 SOP。确认理解相关规则后，再开始分析、修改或创建文件。

这一步非常重要。

如果只是创建文档，却没有要求 Codex 在任务开始前主动读取，那么这些文档很容易变成无人使用的资料。

真正有效的机制应该是：

开始任务
  ↓
读取全局规则
  ↓
查看历史复盘
  ↓
按照 SOP 执行
  ↓
完成任务
  ↓
记录新的经验

这样才能形成完整闭环。

四、它为什么会“越用越聪明”？

这里所说的“越用越聪明”，并不是让 Codex 自动升级模型，也不是增加账户额度。

它真正改变的是工作上下文。

随着任务不断增加，复盘日志里会逐渐积累：

你常用的技术栈；
你不喜欢的代码风格；
你习惯的目录结构；
项目中容易出错的位置；
已经尝试过但失败的方案；
更适合你的操作流程；
不同项目之间可以复用的经验。

当 Codex 每次工作前都读取这些信息，它就能减少重复试错，也更容易按照你的习惯完成任务。

从实际体验上看，它会表现得越来越稳定，也越来越像一个熟悉你项目的长期协作者。

五、这套机制需要注意什么？

虽然长期规则很有用，但并不是文档越多越好。

首先，规则要保持简洁。过多重复、冲突或已经失效的内容，反而会干扰 Codex 的判断。

其次，复盘日志要记录结论，而不是堆积完整聊天内容。建议重点保留：

问题是什么；
原因是什么；
最终如何解决；
下次应该怎么做。

最后，重要规则仍然应该保存在项目文件中，而不是完全依赖模型自身的临时上下文。文件更容易检查、修改、同步和备份，也适合在多台电脑或团队成员之间共享。

总结

想让 Codex 更懂你的项目，关键并不是不断寻找更长、更复杂的提示词，而是建立一套可以持续维护的工作机制。

通过全局工作台统一行为规则，通过全局复盘日志沉淀经验，再通过新项目 SOP 规范项目初始化流程，最后将“任务开始前必须阅读这些文档”写入 AGENTS.md，就能形成一个不断积累和复用经验的闭环。

它不会让 Codex 的模型能力发生变化，但能明显减少重复沟通、无关修改和重复踩坑。

真正让 Codex 越用越顺手的，不是一段神奇提示词，而是一套能够长期执行、持续复盘、不断更新的项目规则体系。

Codex 钩子是什么？用途与使用方法

Fri, 24 Jul 2026 17:55:00 +0800

在 ChatGPT 的 Codex 设置中，你可能会看到一个名为“钩子”的页面。

这里的钩子，英文叫 Hooks。它不是聊天记忆，也不是定时任务，而是一套给 Codex 使用的自动触发机制。

简单理解就是：

当 Codex 执行到某个步骤时，自动运行你提前设置好的脚本。

例如，Codex 准备执行命令时，可以先检查命令是否危险；修改代码后，可以自动运行测试；会话结束时，也可以自动保存日志或整理交接信息。

钩子可以做什么？

钩子常见的用途包括：

执行命令前检查危险操作；
防止用户误贴 API Key；
修改代码后自动运行测试；
检查代码格式是否符合规范；
会话开始时加载项目说明；
上下文压缩前保存重要信息；
会话结束时生成日志或清理临时文件。

Codex 官方支持多个生命周期节点，包括 SessionStart、PreToolUse、PostToolUse、UserPromptSubmit、PreCompact、Stop 和 SessionEnd 等。([OpenAI Developers][1])

常见钩子类型

`SessionStart`

在 Codex 会话开始、恢复或清空后触发。

适合自动加载：

项目开发规范；
环境说明；
当前任务进度；
必须遵守的注意事项。

`PreToolUse`

在 Codex 调用工具之前触发。

例如，Codex 准备执行 Bash 命令时，可以先检查：

rm -rf

如果脚本判断命令危险，就可以阻止执行。PreToolUse 能拦截 Bash、文件修改和部分 MCP 工具调用。([OpenAI Developers][1])

`PostToolUse`

在命令或工具执行结束后触发。

适合：

检查命令返回结果；
自动记录日志；
发现测试失败后提醒 Codex；
修改文件后运行格式检查。

需要注意，PostToolUse 是在操作已经执行后运行，因此它无法撤销已经产生的文件修改或其他副作用。([OpenAI Developers][1])

`UserPromptSubmit`

在用户的提示词正式提交给模型前触发。

可以用来：

检查提示词中是否包含密码或密钥；
自动补充开发规范；
对不清楚的需求增加提醒；
阻止某些不符合要求的提示词。

该钩子能够读取即将提交的 prompt 内容，并可以添加额外上下文或阻止提交。([OpenAI Developers][1])

`SessionEnd`

当主会话正式结束时触发。

适合：

保存最后的工作记录；
清理临时文件；
记录会话结束状态；
生成简单的交接信息。

不过它属于结束后的辅助操作，无法继续控制已经结束的对话。([OpenAI Developers][1])

钩子配置放在哪里？

Codex 可以从以下位置读取钩子：

~/.codex/hooks.json
~/.codex/config.toml
项目目录/.codex/hooks.json
项目目录/.codex/config.toml

前两种属于用户级配置，会影响你打开的多个项目。

后两种属于项目级配置，只对当前项目生效。项目级钩子只有在该项目被信任后才会加载。([OpenAI Developers][1])

对于普通用户，更推荐使用：

`1`	`项目目录/.codex/hooks.json`

这样配置不会影响其他项目，也方便随项目一起管理。

一个最简单的钩子示例

下面创建一个非常基础的钩子：

每次 Codex 会话开始时，提醒它先阅读项目规范。

第一步：创建目录

在项目根目录创建：

.codex

目录结构如下：

你的项目/
├─ .codex/
│  ├─ hooks.json
│  └─ hooks/
│     └─ session_start.py
├─ AGENTS.md
└─ 其他项目文件

第二步：创建脚本

创建文件：

`1`	`.codex/hooks/session_start.py`

写入下面的内容：

import json
import sys


def main() -> None:
    # Codex 会通过标准输入传入钩子事件信息。
    try:
        json.load(sys.stdin)
    except json.JSONDecodeError:
        pass

    result = {
        "hookSpecificOutput": {
            "hookEventName": "SessionStart",
            "additionalContext": (
                "开始处理项目之前，请先阅读项目根目录中的 "
                "AGENTS.md，并遵守其中的开发规范。"
            ),
        }
    }

    print(json.dumps(result, ensure_ascii=False))


if __name__ == "__main__":
    main()

Codex 的命令型钩子会通过标准输入接收一个 JSON 对象，其中通常包含当前目录、会话编号、事件名称和模型信息。([OpenAI Developers][1])

第三步：创建 hooks.json

在：

`1`	`.codex/hooks.json`

中写入：

{
  "description": "当前项目的 Codex 自动化钩子",
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup|resume|clear|compact",
        "hooks": [
          {
            "type": "command",
            "command": "python .codex/hooks/session_start.py",
            "statusMessage": "正在加载项目开发规范",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

这里各项含义如下：

`1`	`SessionStart`

表示在会话开始时运行。

matcher

表示哪些启动方式能够触发钩子。

command

表示需要运行的脚本。

`1`	`statusMessage`

表示运行钩子时显示的提示。

timeout

表示脚本最长允许运行多少秒。

Windows 用户需要注意

在 Windows 中，如果 python 命令不能使用，可以改成：

`1`	`"command": "py .codex/hooks/session_start.py"`

或者使用 Python 的完整路径：

`1`	`"command": "C:\\Python312\\python.exe .codex\\hooks\\session_start.py"`

项目可能从子目录启动，正式使用时最好通过项目根目录定位脚本，避免相对路径失效。官方文档也建议项目钩子尽量从 Git 根目录解析脚本位置。([OpenAI Developers][1])

如何启用和检查钩子？

保存文件后，重新打开 Codex。

然后在 Codex CLI 中输入：

/hooks

你可以在这里：

查看已经发现的钩子；
查看钩子来自哪个配置文件；
信任新钩子；
禁用某个钩子；
重新启用钩子。

出于安全原因，普通命令钩子在首次运行前需要用户检查并信任。钩子内容发生改变后，Codex 会重新要求确认。([OpenAI Developers][1])

因此，看到“未找到钩子”，只是表示当前没有安装或配置可用钩子，并不是程序发生故障。

再举一个实用例子：修改代码后提醒运行测试

创建：

`1`	`.codex/hooks/post_edit.py`

写入：

import json
import sys


def main() -> None:
    data = json.load(sys.stdin)
    tool_name = data.get("tool_name", "")

    if tool_name == "apply_patch":
        result = {
            "hookSpecificOutput": {
                "hookEventName": "PostToolUse",
                "additionalContext": (
                    "代码文件刚刚发生修改。继续任务前，请检查 Git diff，"
                    "并运行与本次修改相关的测试。"
                ),
            }
        }

        print(json.dumps(result, ensure_ascii=False))


if __name__ == "__main__":
    main()

然后把 hooks.json 修改为：

{
  "description": "当前项目的 Codex 自动化钩子",
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup|resume|clear|compact",
        "hooks": [
          {
            "type": "command",
            "command": "python .codex/hooks/session_start.py",
            "statusMessage": "正在加载项目规范",
            "timeout": 10
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "apply_patch",
        "hooks": [
          {
            "type": "command",
            "command": "python .codex/hooks/post_edit.py",
            "statusMessage": "正在检查代码修改",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

这样 Codex 修改文件后，钩子会提醒它检查差异并运行测试。

如何关闭钩子？

临时禁用单个钩子，可以在 Codex 中输入：

/hooks

然后选择对应钩子并禁用。

要彻底关闭所有生命周期钩子，可以打开：

`1`	`~/.codex/config.toml`

加入：

1
2

[features]
hooks = false

Codex 的钩子功能默认启用，上面的配置会关闭所有钩子。([OpenAI Developers][1])

使用钩子需要注意什么？

钩子本质上可以执行本地脚本，因此不要随意信任来历不明的钩子。

尤其要检查：

是否包含删除文件的命令；
是否上传本地代码；
是否读取环境变量和 API Key；
是否自动运行网络请求；
是否安装未知软件；
是否使用管理员权限；
是否修改 Git 仓库以外的文件。

多个符合条件的命令钩子可能同时运行，而且一个钩子不一定能阻止另一个钩子开始执行。官方因此要求非托管钩子在首次运行及修改后重新接受信任检查。([OpenAI Developers][1])

总结

Codex 钩子可以理解为一套自动化规则：

发生某个事件
        ↓
自动运行指定脚本
        ↓
检查、提醒、补充信息或阻止操作

它最适合用来完成：

自动加载项目规范；
阻止危险命令；
修改后自动检查；
自动运行测试；
保存日志和项目状态。

普通用户不配置钩子，也可以正常使用 Codex。只有当你希望 Codex 的工作流程更加固定、安全和自动化时，才需要使用它。

HANDOFF.md 是什么？让新 AI 会话无缝接手旧任务

Fri, 24 Jul 2026 17:39:00 +0800

在 Codex、Claude Code 或 Cursor 中连续工作很久后，常见问题是：

对话上下文快满了；
AI 开始忘记早期要求；
新建会话后又要重新解释项目；
已完成的工作、踩过的坑和后续计划容易丢失。

HANDOFF.md 就是一份 AI 交接文档。

它把当前会话中的关键信息整理成 Markdown 文件，让下一次新会话先阅读这份文档，再继续工作。

使用后有什么效果？

它不能增加模型额度，也不能让 AI 永久记住所有内容，但可以明显改善长任务的连续性：

新会话更快理解项目；
减少重复介绍背景；
保留已经完成的工作；
记录当前卡点和错误尝试；
避免新 AI 重复踩坑；
让 Codex、Claude Code、Cursor 之间也能互相交接。

这种方法本质上是把聊天记录中最重要的信息，压缩成一份可长期保存的项目说明。已有 handoff 工具和实践也采用类似思路：把目标、决定、当前状态、关键文件和下一步写入 Markdown，再由新会话读取。

什么时候使用？

比较适合以下情况：

当前对话即将达到上下文上限；
一个项目需要分多次完成；
准备关闭 Codex 或 Claude Code；
想换一个 AI 工具继续处理；
当前 AI 开始遗忘前面的要求；
任务中已经做过很多测试和修改。

不要等到 AI 已经严重混乱后再生成，最好在当前会话仍能准确回忆全部过程时使用。

可直接复制的交接指令

本次对话即将结束，请在当前项目根目录生成一份交接文档，并命名为 HANDOFF.md。

文档必须包含以下内容：

1. 整体任务目标
2. 用户的核心要求和限制条件
3. 当前项目环境、技术栈和目录位置
4. 现阶段已经完成的工作
5. 已修改、新增或删除的关键文件
6. 当前尚未完成的工作
7. 当前遇到的卡点、报错和阻碍
8. 已经尝试过但没有成功的方法
9. 本轮对话中踩过的坑
10. 后续必须规避的雷区
11. 后续完整执行方案
12. 下一步最优先执行的具体任务
13. 验证工作是否完成的方法
14. 运行、测试、构建和部署命令
15. 其他新会话必须知道的重要信息

要求：

- 不要只写简单摘要。
- 必须写清楚为什么这样做，以及当前结果是什么。
- 涉及文件时写出完整或相对路径。
- 涉及命令时使用代码块完整记录。
- 涉及报错时保留关键报错内容。
- 明确区分已经确认的事实、推测和待验证事项。
- 不要隐瞒失败过程和未解决问题。
- 整篇文档必须做到：即使新会话完全没有当前聊天记录，也能仅通过 HANDOFF.md 理解项目并继续工作。
- 生成完成后，请检查文档是否遗漏关键要求，不要继续执行其他任务。

新会话中发送的指令

请先完整读取当前项目根目录中的 HANDOFF.md。

读取后不要立即修改代码，先完成以下工作：

1. 总结当前项目目标；
2. 说明已经完成的工作；
3. 列出尚未完成的任务；
4. 指出当前卡点和需要规避的雷区；
5. 给出你准备执行的下一步方案。

确认已经正确理解 HANDOFF.md 后，再继续处理项目。

使用时需要注意

HANDOFF.md 的质量取决于当前 AI 是否真正掌握项目状态。

如果交接文档只写“已经修改页面，后续继续优化”，新会话仍然无法接手。好的交接文档应该写清：

改了哪个文件；
为什么修改；
修改后的结果；
哪个方案失败；
下一步具体做什么；
怎样判断任务完成。

另外，交接文档只是记录状态，不会自动保存未提交代码。重要项目仍然需要配合 Git 提交、测试和备份。

总结

这段指令的真正价值，不是让 AI 获得永久记忆，而是人为建立一套可靠的“项目交接机制”。

对于需要多轮完成的网站开发、代码修复、服务器配置和大型项目，它可以减少大量重复沟通，并降低新会话错误接手的风险。

jCodeMunch MCP 使用教程：让 Codex、Claude Code 少读废代码，降低 Token 消耗

Fri, 24 Jul 2026 10:23:00 +0800

使用 Codex、Claude Code 或 Cursor 编写项目时，你可能遇到过这样的情况：

明明只需要修改一个函数，AI 却读取了整个文件；
为了寻找一段代码，AI 连续扫描几十个文件；
项目越大，分析速度越慢；
代码还没改多少，上下文或使用额度却消耗了很多；
AI 读了大量无关代码，反而开始答非所问。

jcodemunch-mcp 正是为了解决这类问题而出现的。

它不会替代 Codex，也不是一个新的 AI 编程模型。它更像是给 AI 编程助手安装了一套“代码目录和精准检索系统”，让 AI 在分析项目时，不必每次都从头翻阅整个代码仓库。

本文将从零开始说明：

jCodeMunch MCP 是什么；
它有什么实际作用；
它是怎样减少 Token 消耗的；
哪些用户适合安装；
如何在 Windows、macOS 和 Linux 上安装；
如何连接 Codex CLI、Claude Code 和 Cursor；
安装后应该怎样使用；
常见问题及注意事项。

一、jCodeMunch MCP 是什么

jCodeMunch MCP 是一个面向 AI 编程助手的代码检索工具。

它会先扫描并建立项目索引，然后把代码中的内容拆分成更容易检索的结构，例如：

函数；
类；
方法；
常量；
导入关系；
文件结构；
类的继承关系；
某个函数被哪些地方调用；
修改某段代码可能影响哪些位置。

当 Codex 或 Claude Code 需要查找代码时，jCodeMunch 可以只返回真正相关的函数或类，而不是把整个文件全部发送给 AI。

项目官方将它定义为一个“本地优先的结构化代码检索系统”。它使用 tree-sitter 分析代码的抽象语法树，并通过 MCP 协议把检索能力提供给 Codex、Claude Code、Cursor 等工具。

简单理解：

普通方式是让 AI 一本一本地翻书；jCodeMunch 则先为所有书建立目录，让 AI 直接翻到需要的那一页。

二、MCP 又是什么

MCP 的全称是：

`1`	`Model Context Protocol`

中文可以理解为“模型上下文协议”。

它是一种让 AI 调用外部工具的标准接口。

例如，支持 MCP 的 AI 编程工具可以连接：

文件系统；
数据库；
GitHub；
浏览器；
搜索引擎；
项目管理工具；
代码索引工具。

jCodeMunch 本身就是一个 MCP Server，也就是“向 AI 提供代码检索能力的服务”。

安装完成后，大致关系如下：

Codex / Claude Code / Cursor
             ↓
          MCP 协议
             ↓
       jCodeMunch MCP
             ↓
      本地项目代码索引

你仍然是在 Codex 或 Claude Code 中提问，只是 AI 在需要寻找代码时，可以调用 jCodeMunch 提供的工具。

三、它解决了什么问题

1. 避免读取整个大文件

假设项目中有一个 700 行的文件，而你只需要修改其中一个 30 行的函数。

普通 AI 编程流程可能是：

读取整个 700 行文件
↓
从中寻找目标函数
↓
理解上下文
↓
修改其中 30 行

使用 jCodeMunch 后，可以变成：

搜索函数名称
↓
只取得目标函数的 30 行代码
↓
理解并修改

项目文档给出的典型示例是：编辑一个大文件中的单个函数时，可以从读取约 700 行缩小到读取约 30 行。不过实际节省程度取决于项目结构和具体任务。

2. 更快找到代码位置

当你问：

`1`	`用户登录验证写在哪里？`

普通方式可能会在整个项目里搜索：

login
auth
token
user
session

然后打开多个文件逐个判断。

jCodeMunch 可以直接从函数、类和方法的索引中寻找相关符号，例如：

AuthService.login
verifyToken
UserSession
authenticateRequest

这样返回的结果通常更加集中。

3. 帮助理解陌生项目

当你第一次接触一个 GitHub 项目时，经常不知道：

入口文件在哪里；
主要模块有哪些；
API 路由放在哪里；
数据库逻辑在哪一层；
某个类被哪些文件使用；
修改某个函数会影响什么。

jCodeMunch 可以先提供仓库结构、文件概要和符号列表，再按需要提取具体代码。

这比一开始就让 AI 阅读整个项目更加节省上下文。

4. 辅助重构和影响范围分析

除了查找函数，它还可以帮助 AI 分析：

`1`	`修改这个函数后，可能影响哪些调用位置？`

或者：

`1`	`这个类被哪些模块引用？`

项目提供了依赖关系、导入者、调用关系和影响范围等检索能力。这是普通文本搜索不容易直接完成的事情。

5. 减少无关代码干扰

上下文并不是越多越好。

当 AI 同时看到大量无关代码时，可能出现：

抓错重点；
混淆同名函数；
根据旧代码做出判断；
修改不相关文件；
输出内容牛头不对马嘴。

精确地提供少量相关代码，有时比一次性塞入整个仓库更有利于模型判断。

四、它真的能节省 95% Token 吗

jCodeMunch 项目宣传可以将代码探索过程中的 Token 消耗降低 95% 以上，并公开了一套基准测试。

在项目当前公开的测试中，作者使用 Express、FastAPI 和 Gin 三个代码仓库，执行了 15 次代码检索任务。测试比较了：

将仓库源代码全部读取；
先搜索符号，再读取最相关的三个符号。

该测试报告的平均 Token 降幅为 99.6%。

不过需要正确理解这个数字。

这项测试主要衡量的是：

“精准检索代码”与“读取全部源代码”之间的 Token 差异。

它并不直接代表：

你的 Codex 总额度一定减少 99.6%；
每次编程任务都能减少 99.6%；
AI 输出内容的 Token 也会同时减少；
最终答案质量一定提升；
所有类型的项目都能达到同样效果。

项目自己的测试方法也明确说明，它没有测量完整任务质量、总延迟或端到端完成效果，而且测试查询数量较少，不同项目的实际结果可能不同。

因此，更准确的说法是：

在大型、结构清晰的代码仓库中，当 AI 需要查找某个函数、类或模块时，jCodeMunch 有机会显著减少读取代码所消耗的上下文；但实际节省比例需要根据项目和任务判断。

五、哪些人适合使用

jCodeMunch 比较适合以下情况。

适合使用

经常使用 Codex CLI、Claude Code 或 Cursor；
项目中有很多文件；
单个代码文件比较长；
经常让 AI 分析陌生 GitHub 项目；
经常进行局部修改；
经常寻找函数、类、接口或调用关系；
使用额度有限，希望减少无关扫描；
需要在大型项目中进行重构；
同一个项目会被 AI 反复分析。

暂时没有必要使用

项目只有几个文件；
每个文件只有几十行；
只是偶尔让 AI 写一小段独立代码；
任务本身就必须阅读完整文件；
AI 主要用于写文章，而不是分析代码；
当前使用的客户端不支持 MCP。

例如，一个只有三个 HTML 文件的小网站，安装 jCodeMunch 的意义可能不大。

但对于 Next.js、Vue、Laravel、Django、WordPress 插件或包含大量模块的工具项目，它更容易发挥作用。

六、支持哪些语言和工具

根据项目当前说明，jCodeMunch 支持 70 多种语言，包括：

Python；
JavaScript；
TypeScript；
Go；
Rust；
Java；
C；
C++；
C#；
PHP；
Ruby；
Swift；
Kotlin。

它通过 tree-sitter 对这些语言进行代码结构分析。

支持的 MCP 客户端包括：

Codex CLI；
Claude Code；
Claude Desktop；
Cursor；
VS Code；
Continue；
Windsurf；
Cline；
Roo Code；
Gemini CLI；
Qwen Code；
其他支持 MCP 的客户端。

具体支持情况可能随着版本更新而变化，应以项目最新 README 为准。

七、安装前需要准备什么

建议先准备：

1
2
3

Python
终端工具
支持 MCP 的 AI 编程客户端

检查 Python

打开 PowerShell、Windows Terminal 或 macOS/Linux 终端，输入：

`1`	`python --version`

有些系统需要输入：

`1`	`python3 --version`

看到类似下面的结果，说明 Python 已经安装：

`1`	`Python 3.12.4`

然后检查 pip：

`1`	`pip --version`

或者：

`1`	`python -m pip --version`

如果提示找不到 python 或 pip，需要先安装 Python，并在安装时勾选：

`1`	`Add Python to PATH`

八、最简单的安装方法

官方目前提供了自动初始化命令。它可以尝试检测 Claude Code、Claude Desktop、Cursor、Windsurf 和 Continue，并自动写入对应配置。

打开终端，执行：

`1`	`pip install jcodemunch-mcp`

安装完成后执行：

`1`	`jcodemunch-mcp init`

程序会进入交互式设置流程，可能会询问：

要为哪些 MCP 客户端安装；
是否添加使用规则；
是否安装自动更新索引的 Hook；
是否立即索引当前项目；
是否检查 AI 配置中的 Token 浪费。

按照终端提示选择即可。

完成后，重新启动 Codex、Claude Code、Cursor 或对应编辑器。

先查看但不修改配置

担心自动初始化修改配置，可以先执行：

`1`	`jcodemunch-mcp init --dry-run`

它会显示准备进行哪些操作，但不会真正修改文件。

也可以运行演示模式：

`1`	`jcodemunch-mcp init --demo`

这两项功能适合第一次接触 MCP 的用户。

九、Windows 安装建议

Windows 用户可以在 PowerShell 中执行：

`1`	`python -m pip install -U jcodemunch-mcp`

安装后检查：

`1`	`jcodemunch-mcp --version`

如果能够看到版本号，继续执行：

`1`	`jcodemunch-mcp init`

提示“找不到 jcodemunch-mcp”

这是 Windows 上比较常见的问题，通常是 Python 的 Scripts 目录没有加入 PATH。

先执行：

`1`	`python -m jcodemunch_mcp --help`

如果这个命令可以运行，说明包已经安装，只是系统找不到独立的可执行文件。

可以在 MCP 配置中使用：

{
  "command": "python",
  "args": ["-m", "jcodemunch_mcp"]
}

也可以查找安装位置：

`1`	`where.exe jcodemunch-mcp`

如果仍然找不到，执行：

`1`	`python -m site --user-base`

输出目录下面通常会有一个 Scripts 文件夹，需要将该目录加入 Windows 的 PATH。

十、在 Claude Code 中安装

方法一：自动设置

执行：

1
2

pip install jcodemunch-mcp
jcodemunch-mcp init

初始化程序会尝试自动发现 Claude Code 并写入配置。

完成后重启 Claude Code，然后输入：

/mcp

查看是否出现：

`1`	`jcodemunch`

方法二：手动添加

如果已经使用 pip 安装，可以运行：

`1`	`claude mcp add -s user jcodemunch jcodemunch-mcp`

这里的：

-s user

表示把它安装到用户级别，而不是只在当前项目中使用。

如果采用 uvx，可以使用：

`1`	`claude mcp add -s user jcodemunch uvx jcodemunch-mcp`

项目文档提醒，若 Windows 无法找到程序，可以把命令替换为实际的 jcodemunch-mcp.exe 绝对路径。

十一、在 Cursor 中安装

最省事的方法仍然是：

1
2

pip install jcodemunch-mcp
jcodemunch-mcp init

如果自动识别失败，可以在 Cursor 的 MCP 配置中添加：

{
  "mcpServers": {
    "jcodemunch": {
      "command": "uvx",
      "args": ["jcodemunch-mcp"]
    }
  }
}

没有安装 uv，也可以使用 Python：

{
  "mcpServers": {
    "jcodemunch": {
      "command": "python",
      "args": ["-m", "jcodemunch_mcp"]
    }
  }
}

保存后彻底关闭并重新打开 Cursor。

注意，不只是关闭项目窗口，而是要完全退出 Cursor 进程后重新启动。

十二、在 Codex CLI 中安装

Codex CLI 的配置方式和 Cursor 不同。

Codex 使用的是 TOML 配置文件，通常位于：

`1`	`~/.codex/config.toml`

Windows 中一般对应：

`1`	`C:\Users\你的用户名\.codex\config.toml`

推荐方法：使用独立虚拟环境

项目当前文档建议 Codex CLI 不要在首次连接时直接使用 uvx，因为首次运行产生的安装输出有可能干扰 MCP 的 JSON-RPC 握手。更稳妥的方式是先把 jCodeMunch 安装到虚拟环境，再让 Codex 直接调用可执行文件。

macOS 或 Linux

进入准备使用的目录：

`1`	`python3 -m venv .venv`

安装：

`1`	`.venv/bin/pip install -U jcodemunch-mcp`

测试：

`1`	`.venv/bin/jcodemunch-mcp --help`

然后编辑：

`1`	`~/.codex/config.toml`

加入：

1
2

[mcp_servers.jcodemunch]
command = "/你的绝对路径/.venv/bin/jcodemunch-mcp"

这里一定要使用真实的绝对路径，不要直接照抄示例。

Windows

在 PowerShell 中创建虚拟环境：

`1`	`python -m venv C:\Tools\jcodemunch-venv`

安装：

`1`	`C:\Tools\jcodemunch-venv\Scripts\python.exe -m pip install -U jcodemunch-mcp`

测试：

`1`	`C:\Tools\jcodemunch-venv\Scripts\jcodemunch-mcp.exe --help`

然后打开：

`1`	`C:\Users\你的用户名\.codex\config.toml`

加入：

1
2

[mcp_servers.jcodemunch]
command = "C:\\Tools\\jcodemunch-venv\\Scripts\\jcodemunch-mcp.exe"

TOML 中的 Windows 路径建议使用双反斜杠：

\\

保存配置后，彻底关闭 Codex CLI，再重新启动。

简单但不优先推荐的 Codex 配置

部分环境也可以使用：

1
2
3

[mcp_servers.jcodemunch]
command = "uvx"
args = ["jcodemunch-mcp"]

但根据项目当前说明，Codex 对 MCP 启动时的标准输出比较严格，因此预先安装并指向真实可执行文件通常更加稳定。

十三、安装完成后如何建立项目索引

只连接 MCP 还不够，jCodeMunch 必须先知道你要分析哪个项目。

最简单的方法是进入项目目录：

`1`	`cd 你的项目目录`

然后在 Codex 或 Claude Code 中提出：

`1`	`请使用 jCodeMunch 检查当前项目是否已经建立索引。如果没有，请为当前项目建立索引。`

也可以要求它先解析当前目录：

`1`	`请先使用 resolve_repo 识别当前项目。如果项目尚未建立索引，请调用 index_folder。`

如果初始化时选择了：

`1`	`Index current project`

当前项目可能已经建立了索引。

索引的作用

第一次建立索引时，jCodeMunch 会：

扫描项目文件；
识别代码语言；
使用 tree-sitter 解析代码；
提取函数、类、方法等符号；
保存文件结构和代码位置；
建立可供 AI 查询的本地索引。

之后再次查询相同项目时，不必重新从头解析全部内容。

十四、如何确认它已经正常工作

可以在 AI 编程工具中输入：

`1`	`请使用 jCodeMunch 显示当前项目的仓库概要。`

或者：

`1`	`请使用 jCodeMunch 列出当前项目的主要目录、模块、类和函数。`

还可以测试：

`1`	`请使用 search_symbols 查找项目中的登录验证函数，不要使用普通的全文文件扫描。`

能够返回结构化的函数、类或文件结果，说明它已经工作。

在 Claude Code 中，还可以输入：

/mcp

确认 jcodemunch 状态是否为已连接。

十五、安装后一定要告诉 AI 使用它

这是最容易被忽略的一步。

MCP 安装成功，只代表 AI“可以使用”jCodeMunch，并不代表 AI“每次都会主动使用”。

很多 AI 编程助手仍然可能优先使用自己的：

Read；
Grep；
Glob；
Bash；
全文件扫描。

项目文档也明确提醒，如果没有添加使用规则，AI 可能继续使用原生文件工具，而不调用 jCodeMunch。

可以在项目的 AGENTS.md、CLAUDE.md 或其他项目指令文件中加入：

## Code Exploration Policy

分析、搜索或理解项目代码时，优先使用 jCodeMunch MCP。

- 查找函数、类或方法时，优先使用 search_symbols。
- 查看文件结构时，优先使用 get_file_outline。
- 查看项目结构时，优先使用 get_repo_outline 或 get_file_tree。
- 修改具体函数前，优先使用 get_symbol_source 获取目标代码。
- 只有在确实需要完整文件上下文时，才读取整个文件。
- 如果项目尚未建立索引，先使用 resolve_repo 和 index_folder。

如果是 Codex，可以把类似规则写入项目根目录的：

`1`	`AGENTS.md`

这样 Codex 每次进入项目时，都更容易遵守这套代码检索方式。

还可以直接在对话中说：

`1`	`本次任务必须优先使用 jCodeMunch 搜索符号和读取目标代码，不要一开始就扫描整个项目。`

十六、推荐的实际使用提示词

1. 第一次了解项目

`1`	`请先使用 jCodeMunch 获取项目概要、主要目录和核心模块，不要直接读取所有文件。然后用小白能够理解的语言说明这个项目是怎样运行的。`

2. 查找功能位置

`1`	`请使用 jCodeMunch 查找用户登录、Token 验证和权限检查相关的函数或类，并告诉我它们分别位于哪些文件中。`

3. 修改一个函数

`1`	`请使用 jCodeMunch 查找负责文件上传的函数，只读取目标函数及必要的调用上下文。确认影响范围后再修改，不要扫描无关文件。`

4. 分析报错

`1`	`请根据下面的报错信息，使用 jCodeMunch 查找相关符号、调用方和异常处理逻辑，然后判断最可能的问题位置。`

5. 分析修改影响

`1`	`请使用 jCodeMunch 分析修改 UserService.updateProfile 后可能影响的调用位置、接口和测试文件。`

6. 接手陌生 GitHub 项目

`1`	`请使用 jCodeMunch 为这个项目建立索引，然后依次说明项目入口、目录结构、核心模块、数据流和运行方法。不要一次读取整个仓库。`

十七、代码修改后索引会不会过期

会。

如果文件内容已经修改，但索引仍然保留旧版本，AI 可能检索到过期代码。

jcodemunch-mcp init 可以选择安装自动化 Hook，例如：

修改文件后自动重新索引；
在读取大文件前提醒使用精准检索；
在上下文压缩前保存会话信息。

这些功能在 Claude Code 中支持得相对完整。自动初始化程序也可以选择索引当前项目和安装相关 Hook。

对于没有对应 Hook 的编辑器，可以：

使用 VS Code 扩展进行保存后重新索引；
修改重要文件后让 AI 重新索引；
重新运行项目索引命令；
在开始新任务前检查索引是否过期。

项目本身也支持增量索引，不一定每次都需要完整扫描整个仓库。

十八、是否需要 API Key

基础代码索引和符号检索不一定需要 AI API Key。

不配置额外模型时，jCodeMunch 仍然可以根据：

函数签名；
类名称；
方法名称；
文件位置；
代码结构；

生成基础索引。

如果需要更强的语义搜索或 AI 生成摘要，可以安装额外组件。

本地语义搜索

`1`	`pip install "jcodemunch-mcp[local-embed]"`

然后下载本地模型：

`1`	`jcodemunch-mcp download-model`

根据项目文档，该模型下载大小约为 23MB，首次下载后可以在本地运行，不需要每次调用网络 API。

OpenAI 兼容摘要

`1`	`pip install "jcodemunch-mcp[openai]"`

Claude 摘要

`1`	`pip install "jcodemunch-mcp[anthropic]"`

Gemini 摘要

`1`	`pip install "jcodemunch-mcp[gemini]"`

这些属于增强功能，不是第一次安装必须完成的步骤。

对于小白，建议先只安装基础版本：

`1`	`pip install jcodemunch-mcp`

确认基础功能正常后，再考虑语义搜索和 AI 摘要。

十九、隐私和代码安全

jCodeMunch 采用“本地优先”架构，索引和代码缓存主要保存在本地。项目架构文档表示，它会保存符号元数据、原始文件缓存和代码字节位置，以便进行精准提取。

但需要注意：

安装第三方工具前，应自行检查项目代码和许可证；
如果启用了 OpenAI、Claude 或 Gemini 摘要，相关代码摘要可能会发送给对应 API；
本地嵌入模式下载模型后可以在本机推理；
不要把 API Key 直接提交到 GitHub；
公司机密项目应先确认企业安全政策；
不要轻易安装不需要的全部扩展依赖。

项目配置文档显示，基础包不会自动引入远程 AI 服务；启用不同的扩展后，才可能连接 Anthropic、Google 或 OpenAI 等外部服务。

二十、许可证需要特别注意

jCodeMunch 并不是传统意义上完全不受限制的 MIT 开源项目。

项目当前采用自己的双用途许可证：

个人、非商业用途免费；
商业用途需要购买许可证；
不能随意改名、重新包装并发布到公共软件包仓库；
修改和再分发时还需要遵守项目许可证中的其他条件。

因此：

个人学习、个人项目可以按照许可证免费使用；
用于公司业务、收费项目或商业开发前，应阅读完整许可证；
不要只看到 GitHub 仓库是公开的，就默认可以无限制商业使用。

许可证条款可能变化，正式商用前应以仓库中的最新 LICENSE 文件为准。

二十一、常见问题

1. 安装后 AI 还是一直读取完整文件

原因通常不是安装失败，而是 AI 没有被要求使用它。

处理方法：

在 AGENTS.md 或 CLAUDE.md 中添加使用规则；
在提示词中明确要求优先调用 jCodeMunch；
检查 MCP 是否处于连接状态；
确认当前项目已经建立索引。

2. 提示 `jcodemunch-mcp is not recognized`

说明系统找不到可执行文件。

先试：

`1`	`python -m jcodemunch_mcp --help`

然后将 MCP 配置改为：

{
  "command": "python",
  "args": ["-m", "jcodemunch_mcp"]
}

或者查找 jcodemunch-mcp.exe 的真实路径并使用绝对路径。

3. Codex 启动时卡住

不要优先使用首次运行的 uvx。

先把 jCodeMunch 安装到固定虚拟环境，再让：

`1`	`~/.codex/config.toml`

直接指向 jcodemunch-mcp 可执行文件。

这是该项目当前针对 Codex CLI 给出的推荐配置。

4. 建立索引后代码更新了怎么办

让 jCodeMunch重新索引修改过的文件，或者安装自动重新索引 Hook。

5. 小项目有必要安装吗

通常没有必要。

jCodeMunch 的优势主要体现在：

大文件；
多文件；
陌生项目；
频繁查找；
局部修改；
重构分析。

6. 它能增加 Codex 额度吗

不能。

它不会：

修改 Codex 订阅；
增加账户额度；
绕过使用限制；
改变 OpenAI 的计费规则。

它只是尽量减少 AI 在读取和查找代码时产生的无效上下文。

7. 它能保证 AI 不犯错吗

不能。

它改善的是代码检索方式，不是模型本身的推理能力。

AI 仍然可能：

理解错误；
修改错误；
漏掉调用关系；
生成存在漏洞的代码。

重要修改仍应执行：

代码审查
单元测试
构建测试
实际运行验证
Git 版本控制

二十二、如何卸载

使用 pip 安装的，可以执行：

`1`	`pip uninstall jcodemunch-mcp`

然后删除对应客户端中的 MCP 配置。

例如 Codex 的：

`1`	`[mcp_servers.jcodemunch]`

Cursor 或 Claude Desktop 配置中的：

"jcodemunch": {
  "command": "...",
  "args": [...]
}

如果创建了单独的虚拟环境，也可以直接删除该虚拟环境目录。

注意，不要误删整个 Codex、Cursor 或 Claude 的配置文件，只删除 jCodeMunch 对应的配置块。

二十三、是否值得安装

我的判断是：

jCodeMunch MCP 不是所有用户都必须安装，但对于经常使用 Codex、Claude Code 或 Cursor 分析中大型项目的人，它是一个值得尝试的代码上下文优化工具。

它真正的价值，不是让 AI“变得更聪明”，而是让 AI：

少读无关文件；
更快找到目标函数；
只提取必要代码；
更清楚地理解项目结构；
在有限上下文中保留更多有效信息。

对于只有几个文件的小项目，提升可能不明显。

对于包含大量源码、模块和依赖关系的项目，它可能显著改善代码探索过程。

最稳妥的使用方式是：

先安装基础版本
↓
连接一个 MCP 客户端
↓
为一个真实项目建立索引
↓
明确要求 AI 优先使用符号检索
↓
观察 Token、速度和回答质量
↓
再决定是否长期使用

不要只看项目宣传的节省比例，更应该根据自己的项目实际测试。

最小安装流程总结

普通用户

1
2

pip install jcodemunch-mcp
jcodemunch-mcp init

重新启动 AI 编程客户端，然后让它：

`1`	`使用 jCodeMunch 检查并索引当前项目。`

Codex CLI 用户

创建固定虚拟环境：

`1`	`python -m venv .venv`

安装：

`1`	`.venv/bin/pip install -U jcodemunch-mcp`

在 Windows 中对应：

`1`	`.venv\Scripts\python.exe -m pip install -U jcodemunch-mcp`

然后在：

`1`	`~/.codex/config.toml`

中加入：

1
2

[mcp_servers.jcodemunch]
command = "/jcodemunch-mcp可执行文件的绝对路径"

最后，在项目根目录的 AGENTS.md 中加入：

`1`	`分析项目代码时优先使用 jCodeMunch MCP。先搜索符号和文件概要，只在确实需要完整上下文时读取整个文件。`

项目地址：https://github.com/jgravelle/jcodemunch-mcp

完成这些步骤后，jCodeMunch 才算真正融入 Codex 的日常代码分析流程。

Codex 省额度工具包（新手版）

Tue, 21 Jul 2026 18:13:00 +0800

这套文件不会增加 Codex 额度，也不会改变收费标准。它通过限制无关扫描、无关修改、完整测试和重复解释，减少不必要的 Token 与 credits 消耗。

工具包下载

点击下载 Codex 省额度工具包（新手版）

下载完成后，请先解压 ZIP 压缩包，再按照下方步骤安装。

最简单的安装方法

第一步：解压

解压下载的 ZIP 文件。

第二步：复制到项目根目录

把解压后的以下内容复制到你的项目最外层目录：

.agents 文件夹
AGENTS.md
PROJECT_STATUS.md
prompts 文件夹

项目根目录通常是能够看到 package.json、README.md、.git 或源代码文件夹的位置。

复制完成后的结构应类似：

你的项目/
├─ .agents/
│  └─ skills/
│     ├─ project-navigation/
│     ├─ minimal-code-change/
│     ├─ targeted-testing/
│     ├─ diagnose-before-fixing/
│     └─ website-small-task/
├─ prompts/
├─ AGENTS.md
├─ PROJECT_STATUS.md
├─ package.json
└─ src/

Windows 默认可能隐藏以点号开头的文件夹。即使看不到 .agents，只要复制成功即可。可以在资源管理器中开启“查看 → 显示 → 隐藏的项目”。

第三步：编辑 PROJECT_STATUS.md

用记事本或 VS Code 打开 PROJECT_STATUS.md，只填写你知道的内容。不知道的地方可以保留。

也可以在 Codex 中粘贴：

请读取当前项目，并只查看项目根目录、package.json、README.md 和主要源码目录。不要扫描整个仓库。然后帮我填写 PROJECT_STATUS.md，控制在100行以内，不修改其他文件。

第四步：重新打开项目

如果 Codex 已经打开这个项目，请关闭当前 Codex 会话并重新打开项目，使它重新发现 AGENTS.md 和 Skills。

官方支持在 CLI、IDE 扩展和 ChatGPT/Codex 桌面应用中使用 Skills。项目级 Skills 放在项目根目录的 .agents/skills 中。

第五步：第一次验证

在 Codex 中粘贴：

请不要修改任何文件。告诉我：
1. 你读取到了哪些 AGENTS.md；
2. 你发现了哪些项目 Skills；
3. 用5行以内总结当前工作规则。

能看到五个 Skill 名称，说明安装成功。

日常怎么使用

打开 prompts 文件夹，根据任务复制对应模板：

01-修改小功能.txt：增加小功能或修改页面
02-修复报错.txt：解决报错、502、Docker、Nginx、Cloudflare 等问题
03-只分析不修改.txt：担心 Codex 乱改时先分析
04-继续未完成项目.txt：继续上一次工作
05-检查本次修改.txt：提交前检查
06-让Codex填写项目资料.txt：第一次安装后使用

把方括号中的内容替换成你的实际需求即可。

Skill 如何手动调用

在支持 Skill 选择的界面中，可以使用 /skills 查看 Skills，或在提示词中输入 $ 后选择 Skill。

也可以直接复制：

`1`	`请使用 $project-navigation、$minimal-code-change 和 $targeted-testing。`

排查报错时复制：

`1`	`请使用 $diagnose-before-fixing。`

如果界面没有自动补全 $技能名称，直接用自然语言写出 Skill 名称也可以；Codex 也会根据 Skill 的 description 自动判断是否调用。

最省额度的使用习惯

一次只完成一个明确功能。
指定允许读取和允许修改的目录。
小修改不运行完整构建和全部测试。
长对话使用 /compact，不同功能使用新会话。
复杂任务先用 Plan 模式，确认方案后再修改。
不要同时启动多个 agent 处理同一问题。
不要安装大量重复 Skills；本工具包的五个已足够大多数小项目。
每完成一个阶段，让 Codex 更新 PROJECT_STATUS.md。
重要修改前先提交 Git，避免反复回滚。
普通任务优先使用较轻量模型，疑难问题再切换更强模型。

哪些内容需要你自己修改

AGENTS.md 是通用规则，通常不用改。

PROJECT_STATUS.md 建议填写：

项目要做什么
使用什么框架
当前完成到哪里
下一步是什么
哪些文件不能改

如果项目有特殊测试命令，也应写进去。

卸载方法

删除项目根目录中的以下内容即可：

.agents/
AGENTS.md
PROJECT_STATUS.md
prompts/