# Codex 独立面板适配决策

## 背景与边界

现有插件依赖 DSH 的模块加载器、会话服务、右栏席位及主题变量，不能直接安装到 Codex。用户要求在 Codex 中打开相同的独立 Git 面板，同时继续维护 DSH。适配只增加本地只读展示，不增加 Git 写操作，也不修改 Codex 应用程序文件。

## 选择

复用 `index.js` 的数据采集与 `client.js` 的 React 面板；新增一个 loopback HTTP 适配器，以生产构建的 React/React DOM 提供宿主运行时。Codex 插件包含一个 skill：启动服务后，用内置 `open_in_codex` 打开右侧浏览器面板。它是聊天旁的独立面板，不是原生全局侧栏扩展。

候选方案：直接加载 DSH 插件缺少宿主 API；单独重写界面会造成双份图谱维护；远程 MCP UI 需要额外服务和路径传输。选择本地浏览器适配可复用行为、离线运行，并可通过卸载插件回退。如果 Codex 提供适用的原生面板扩展接口，再重新评估。

## 契约与生命周期

- 启动：`node codex/scripts/start.mjs --repo <绝对项目路径>`，输出 `{url, repo, pid}`；同项目复用健康服务。
- 只监听 `127.0.0.1` 的随机端口；只接受该端口的 loopback Host、同源 Origin 和 GET 请求。无 CORS 放行。
- 只暴露固定静态资源、健康检查和原有只读 API。目录范围为启动项目及启动时已有的工作树。新增工作树若在范围之外，需要重新启动面板服务。
- 关闭浏览器面板不结束服务；30 分钟无请求后退出。也可对启动器返回的 PID 发送 SIGTERM。
- Codex 服务和 DSH 进程各自维护最多 64 个仓库的轨道记忆，每仓库至多记住 2048 条轨道。交叉评分相同时保持已有历史轨道相对顺序，减少交叉或回收空档时允许重排；进程重启或仓库被 LRU 淘汰后重新分配。失效轨道在下一轮回收，空分支集中放在历史轨道右侧。
- 只合并进行中的采集，不缓存已完成快照或错误。同目录请求共享整份快照，同 `.git` 的不同工作树共享图谱历史；当前分支与文件状态仍按工作树独立读取。每个调用者先通过目录检查。

## 依赖与影响

React 和 React DOM 来自官方 npm 包，许可证 MIT；用于复用现有 React UI。esbuild 来自官方 npm 包，许可证 MIT；仅用于构建。版本及完整性由 `package-lock.json` 锁定，构建后无需 npm 依赖或 CDN。生成文件放在 `codex/dist/`，不进入源码提交；本地插件安装前先构建。DSH 的席位与 HTTP 路由契约不变，只增加响应元数据。

前端使用 `prefers-color-scheme` 跟随系统亮/暗色，以独立主题文件映射 DSH token。React 最佳实践要求不引入第二套界面状态，独立页面直接挂载现有 Panel。

## 资源预算与验证口径

- 单面板最多 1 个进行中的刷新请求；隐藏页面新增轮询请求目标及红线均为 0，恢复可见后读取一次。
- 同目录并发读取共享 1 份进行中快照，同仓库共享 1 份进行中的图谱采集；完成和失败都释放。文件展示上限 700，提交展示上限 120；准确标记截断。
- 生产前端 bundle 目标小于 350 KiB（未压缩），红线 500 KiB；用构建文件实际字节数验证。这里不声称启动耗时、内存或用户操作延迟的提升。
- 自动化验证覆盖可见性、旧请求清理、返回会话、轨道稳定、截断、窗口外分支、只读服务范围。页面验收检查实际渲染、窄栏溢出和控制台错误；没有覆盖到的环境如实记录。

## 本机验收记录（2026-10-18）

- Node.js v24.21.0，本机生产构建；完整回归 19 项通过，源码语法与 diff 空白检查通过。
- 生产前端 262868 字节，低于 350 KiB 目标；首次引入依赖时 npm audit 报告 0 项漏洞。没有做启动时间或内存基准测试。
- Codex 内置浏览器实际打开成功，控制台无 error；360×780 视口下页面与头部 scrollWidth 均为 360px，没有整页横向溢出。已恢复正常视口。
- 实际点击工作树后出现「返回会话工作区」，点击后入口消失且数据重新读取。原生 DSH 页面本轮未单独重启验收；亮色主题未人工切换验收。
- Codex CLI 确认 `git-worktree-panel@local-git-worktree` 已安装并启用；安装副本的前端和服务端 SHA-256 与最终构建一致，安装副本启动器能正常复用面板服务。