# 代码随读 · Codex 插件与独立网页版 0.5

在只读代码面板选中源码，后台直接返回浮窗解释。每次选择无需向聊天发送消息。文件名旁展示用途，代码导图可浏览类、函数、方法和模块，并跳转到实现。

提供 **独立网页版** 和 **Codex 插件**，共用阅读界面。网页版可直接配置 API；插件沿用本机 Codex 登录。项目采用 [MIT License](LICENSE)。

## 下载与启动

从 [Releases](https://github.com/DreamPerday/codex-code-explainer/releases/latest) 下载对应的包，均需要 Node.js（推荐 22+）。

| 版本 | 下载文件 | 启动方式 |
| --- | --- | --- |
| 独立网页版 | `code-explainer-web-0.5.0.zip` | 解压后双击 `启动网页版.cmd`；或运行 `node server.mjs` |
| Codex 插件 | `code-explainer-0.5.0.zip` | 解压后运行 `node scripts/install.mjs`，再运行 `codex plugin add code-explainer@personal` 并重新加载 Codex |

网页版打开 http://127.0.0.1:4318 ，保持后台运行即可。点击右上角“模型与 API”填写基础地址、Key 和模型 ID，支持 OpenAI 兼容的 Chat Completions 接口；也可选择沿用本机 Codex。**API 方式无需安装或登录 Codex**。完整使用说明见 [网页版说明](web/README.md)。

插件安装器会复制到用户目录并更新个人插件目录，修改前备份原目录配置；插件自身的使用需要支持 MCP Apps 的 Codex 客户端。

## 从源码运行

```sh
git clone https://github.com/DreamPerday/codex-code-explainer.git
cd codex-code-explainer
npm ci
npm run build
npm run web
```

从源码安装插件：完成构建后运行 `npm run install:local`，再运行 `codex plugin add code-explainer@personal`。开发检查见 [CONTRIBUTING.md](CONTRIBUTING.md)，第三方许可证见 [THIRD_PARTY.md](THIRD_PARTY.md)。

后台默认仅供本机单人使用，解释时会把所需源码发送给配置的模型提供方。网页版不会自动读取 Codex 聊天记录，可在“项目背景”填写阅读目标。结构导图由本地语法解析生成，AI 详细总结按需触发。

## 使用

1. 安装并重新加载 Codex。说一次“用代码随读打开当前项目”。
2. 选中代码，稳定约 0.4 秒后自动解释；也可关闭自动解释，点击按钮或按 Ctrl+Enter。
3. 浮窗显示作用、输入输出、步骤、源码依据与检查范围。可固定、跳转引用、举例。新选区会取消旧请求。
4. 文件名下方直接显示源码注释或结构提示。点击“AI 完善用途”，分批根据源码生成当前列表的具体中文说明；搜索后可继续补全其他文件。AI 说明有标记，完整文字可悬停查看。
5. 在“项目背景”查看或补充解释背景。源文件或相关依赖改变后，旧解释失效；重新选择会重新生成。
6. 点击工具栏“代码导图”，按项目 → 目录 → 文件 → 类/函数/方法浏览。搜索名称可直接找出折叠分支中的节点；点击节点名称跳转到实际实现并选中源码。

## 选择和切换项目

首页点击“浏览文件夹”，从磁盘、用户目录、桌面、文档、下载或最近项目进入。单击子文件夹选中，双击或点击右箭头进入；可后退、前进、返回上级、点击路径层级及筛选当前目录。点击“打开此文件夹”打开所选目录；未选中子目录时打开当前目录。空文件夹也可选择。默认隐藏点号和 `$` 开头的特殊目录，可手动显示。目录数量超过 400 时，通过筛选继续定位。

Windows 还可点击“系统选择…”调用本机文件夹窗口，确认后直接打开项目；取消不会切换项目。其他系统使用面板浏览。首页保留“直接粘贴路径”；浏览器地址栏也支持粘贴路径并按 Enter 前往。项目打开后，右上角“切换项目”可再次选择，切换失败会保留原项目。

最近 12 个成功打开的项目保存在本机 `~/.codex/code-explainer/recent-projects.json`（遵循 `CODEX_HOME`，也可用 `CODE_EXPLAINER_STATE_DIR` 指定偏好目录），重开面板后仍可使用。文件夹浏览只读取直接子目录名称，不递归扫描磁盘，也不把目录列表发送给解释模型；源码仍按项目读取范围检查。

## 代码思维导图

结构由本地语法树提取，打开即可查看，不等待模型。支持 Python、JavaScript、TypeScript（含 JSX/TSX）的类、函数、方法，以及 TypeScript 的接口、类型、枚举、成员；其他语言显示文件结构。展示定义签名、参数、返回表达式、继承和保守解析的本地调用/导入关系。匿名回调不是独立节点，动态调用、重导出和运行时派发可能无法解析。

节点详情提供“AI 总结框架”“AI 总结本分支”“AI 详细总结”：框架说明模块分层及执行流程，函数说明职责、输入输出、关键步骤和待核实处。结果由独立后台分批生成并直接更新导图，不进入聊天。框架依据结构、文档和最多四份源码片段，优先入口文件；函数附带自身源码及最多四个已解析的相关调用或类定义片段，总结中注明覆盖限制。可取消，函数分析按源码及背景缓存；源码或背景变化后重新生成。

支持源码上方固定、收起后下拉展开，以及阅读面板内悬浮置顶、拖动和缩放窗口。编辑器独立滚动。悬浮范围为插件阅读面板，不能置顶到 Codex 外部或其他桌面应用上方。点击“当前文件”可缩小导图范围；支持画布拖动、搜索及定位所选节点。

默认以 100% 显示，节点文字至少 14px。底部可选 14、16、18 号字，节点和间距随字号扩大，画布支持 50%–300% 缩放。“全屏阅读导图”占满插件阅读区域，Esc 返回；点击可跳转的节点时返回固定布局并定位源码。字号、缩放和显示模式会在宿主允许本地存储时记住。固定面板可拖动底边增高，悬浮面板可拖动右下角调整大小；窄窗口将详情放在下方，避免遮住画布。

单次结构索引最多 300 个文件、800 万源码字符、约 5000 个节点；画布最多显示 350 个节点，超出时通过搜索或折叠分支定位。界面显示实际覆盖范围。只读取已保存源码；如果文件变化，跳转会先刷新导图，避免使用旧行号。详细总结按需触发，不自动为整个大型项目生成长篇解释。

## 独立后台与上下文

后台使用本机 `codex app-server`，通过私有 stdio 通道调用模型。每次请求使用不保存的临时推理会话，不恢复用户聊天、不创建侧栏聊天、不读取聊天数据库。后台进程持续复用；选择取消时中断推理。

优先使用宿主提供的 `CODEX_CLI_PATH`，其次查找本机 Codex CLI。使用它已有的登录及提供方配置，不复制凭据。桌面登录与全局 CLI 登录可能不同，使用独立 CLI 时可能需要 `codex login`。

OpenAI 提供方默认选择列表中的 `gpt-6-luna` 以缩短等待，使用 low 推理强度；自定义提供方沿用已配置模型，因为内置目录中的模型未必在该提供方可用。设置 `CODE_EXPLAINER_MODEL` 可指定其他模型，`CODE_EXPLAINER_CODEX_PATH` 可指定本机 codex.exe。插件不改变全局模型设置。

右上角“解释模型”可查看真实后台返回的模型目录、当前提供方和默认模型，选择列表模型或填写自定义模型 ID。“自动选择”使用上述默认策略；面板中的明确选择优先于环境变量。选区解释、文件用途和导图总结均使用该选择。列表只代表 Codex 目录，不保证自定义提供方支持所有条目；请选择该提供方实际开放的模型，调用失败会显示在面板内。

模型选择保存到本机偏好目录的 `model.json`，作为新面板的默认选择；已经打开的其他面板保留各自的选择。切换会取消当前面板的分析、清除已展示的 AI 总结，模型不同的解释不会复用缓存。无需在插件中输入 API Key；仍使用现有 Codex 登录与模型提供方。独立网页使用单独的本机偏好目录，支持直接配置 API。

打开面板的工具接受 `context`，由当前聊天传入简明背景摘要。后续聊天不自动同步，可在面板编辑，或明确要求 Codex 使用 `update_reader_context` 更新摘要。这是背景摘要共享，**不是自动共享完整聊天历史**。

每次附带选区、当前文件的有界内容、项目关键文档、最多 4 个相关文件片段；调用方扫描最多 48 个候选文件。只根据实际附带资料生成解释，浮窗列出检查范围。未声称每次通读整个项目。

## 速度与缓存

采用直接后台推理、短回答、450ms 轮询和结果缓存。缓存键包含模型、背景、选区、问题和实际上下文版本，最多 120 条，重启清空。相关文件变化使旧解释失效。

本机真实测试中，示例函数完整解释约 5.3 秒；缓存命中不再调用模型。模型、网络、代码复杂度会影响等待时间，这不是固定延迟保证。目录的源码说明无需等待模型，AI 补全按 16 个文件一批进行。

## 开发与安装

需要 Node.js 20+ 和可用的 Codex 后台。

```powershell
npm ci
npm run build
npm run check
npm test
npm run install:local
codex plugin add code-explainer@personal
npm run package
```

`install:local` 复制到用户目录 `plugins/code-explainer`，保留其他插件，并备份个人 marketplace。`dist/plugin` 是自包含服务及界面，运行时无需安装 npm 依赖。`npm run package` 生成安装包。

`npm run preview` 启动仅监听本机的开发预览，使用真实模型解释示例代码；可用 `npm run preview -- "项目绝对路径"` 检查自己的项目。预览宿主不提供聊天消息接口，可验证解释独立于聊天完成；真实 Codex 内面板仍需重新加载插件后打开。

## 边界与验证

只读 UTF-8 磁盘源码；单文件 1MB、选区 20,000 字符。排除依赖、构建和常见凭据文件，禁止越界路径与符号链接。未保存的编辑内容不在数据源中。推理后台关闭 shell、补丁、网页、其他 MCP 和插件工具，只接受文本推理。

自动测试覆盖源文件与依赖变化、取消与新选区、缓存与背景隔离、文件用途、引用行号、语法节点归属、回调返回值隔离、导图调用关系、搜索布局、总结失效与打包 MCP 接口。真实模型测试与 UI 浏览器测试另行运行，不以模拟回答冒充真实接入。

接口参考：[Codex App Server](https://developers.openai.com/codex/app-server/)、[插件界面](https://developers.openai.com/plugins/build/chatgpt-ui)。实现以本机生成的协议类型及实际调用结果为准。