bootstrap repository

Author: joyang1

README.md

@@ -0,0 +1,195 @@
+# codex-viewer
+
+`codex-viewer` 是一个面向 Codex CLI 的 Web 可视化工具。它一边在浏览器里代理执行 `codex`，一边实时捕获和展示请求、响应、上下文、多轮工具调用、token 消耗与终端输出。
+
+适合这几类场景：
+
+- 想在浏览器里使用接近终端的 Codex 输入体验
+- 想看清 Codex 到模型层的真实 request / response 结构
+- 想排查多轮 tool call、continuation request、token usage 的执行链路
+- 想把 Codex CLI 包装成一个可直接分发给团队使用的 npm 工具
+
+## 功能概览
+
+- 浏览器中直接发起 Codex 任务，支持多轮上下文持久化
+- 直连代理拦截 Codex 与模型上游之间的 HTTP / SSE / WebSocket 数据
+- 实时查看 request、response、protocol chain、timeline、terminal
+- 单独查看工具调用与工具响应，并追踪 continuation request
+- JSON 可视化查看，支持树形折叠、格式化代码视图、复制与下载
+- 支持图片与文件附件
+- 自动处理非 ASCII 工作目录，必要时镜像到 `/tmp`
+
+## 界面预览
+
+### 1. Codex 输入工作区
+
+![Codex input workspace](./docs/screenshots/codex-input.svg)
+
+### 2. 请求可视化面板
+
+![Request visualization](./docs/screenshots/request-visualization.svg)
+
+### 3. JSON 结构查看
+
+![JSON viewer](./docs/screenshots/json-viewer.svg)
+
+## 安装
+
+### 全局安装
+
+```bash
+npm install -g codex-viewer
+```
+
+安装完成后可直接运行：
+
+```bash
+codex-viewer --port 3789
+```
+
+### 免安装快速运行
+
+```bash
+npx codex-viewer --port 3789
+```
+
+## 前置条件
+
+在启动 `codex-viewer` 之前，请确认：
+
+- 已安装 Node.js `18+`
+- 已安装可执行的 `codex` CLI
+- `codex` 已完成登录或具备可用的 API / CLI 认证环境
+
+如果你的 `codex` 不在系统 PATH 中，可以通过 `--codex-bin` 指定路径。
+
+## 启动方式
+
+最常用的启动命令：
+
+```bash
+codex-viewer --port 3789
+```
+
+然后打开：
+
+```text
+http://127.0.0.1:3789
+```
+
+你之前本地用的这条命令依然可用：
+
+```bash
+node bin/codex-viewer.js --port 3789
+```
+
+## 常用参数
+
+```bash
+codex-viewer \
+  --port 3789 \
+  --host 127.0.0.1 \
+  --cd /path/to/workspace \
+  --codex-bin codex \
+  --proxy-port 0
+```
+
+主要参数说明：
+
+- `--port`：Web 服务端口，默认 `3789`
+- `--host`：监听地址，默认 `127.0.0.1`
+- `--cd`：默认工作目录
+- `--codex-bin`：Codex CLI 路径，默认 `codex`
+- `--proxy-port`：本地直连代理端口，默认 `0`，表示自动分配空闲端口
+- `--max-events`：前端保留的结构化事件数量
+- `--proxy-max-body`：单个 HTTP 请求/响应允许捕获的最大 body 大小
+- `--proxy-max-ws`：单个 WebSocket frame 允许捕获的最大大小
+- `--proxy-max-json`：允许解析的最大 JSON 体大小
+
+## 使用流程
+
+1. 启动 `codex-viewer`
+2. 在浏览器中进入输入页
+3. 选择工作目录、模型，必要时添加图片或文件
+4. 在输入框中直接输入任务并发送
+5. 在 `request visualization` 中查看：
+   - 原始 request
+   - 最终 response
+   - tool call / tool response
+   - continuation request
+   - protocol chain
+   - terminal 输出
+
+## 这个工具拦截了什么
+
+`codex-viewer` 会在本地启动一层直连代理，把 Codex 的模型请求先导到本地，再转发到上游接口。这样可以捕获：
+
+- session request
+- model request
+- model response
+- tool call
+- tool response
+- continuation request
+- usage / token 统计
+- 错误事件
+- 终端输出流
+
+对于 JSON 请求体，会额外提取核心结构，包括：
+
+- `messages`
+- `input`
+- `instructions`
+- `tool` 上下文
+- `usage`
+
+## 工作区镜像
+
+在某些环境下，Codex CLI 无法直接从包含中文或其他非 ASCII 字符的路径运行。  
+`codex-viewer` 会检测这类情况，并支持自动镜像到 `/tmp/codex-viewer-mirrors/...` 后再运行。
+
+## 本地开发
+
+```bash
+npm install
+npm test
+node bin/codex-viewer.js --port 3789
+```
+
+如果你只想检查最终发布包内容：
+
+```bash
+npm run pack:check
+```
+
+## 发布到 npm
+
+项目已经准备成可直接发布的 npm CLI 包。正式发布前，建议按下面顺序执行：
+
+```bash
+npm login
+npm whoami
+npm run pack:check
+npm publish --access public
+```
+
+如果 `codex-viewer` 这个 unscoped 包名已被占用，建议改成组织作用域，例如：
+
+```bash
+@your-scope/codex-viewer
+```
+
+对应安装命令会变成：
+
+```bash
+npm install -g @your-scope/codex-viewer
+```
+
+## 建议在发布前再补一项
+
+如果你希望 npm 包页面中的 README 截图也稳定显示，建议在 `package.json` 里补上实际 GitHub 仓库地址：
+
+- `repository`
+- `homepage`
+- `bugs`
+
+这样 npm 页面能更稳定地解析 README 中的图片与跳转链接。