yyjeqhc/webcodex · 上手攻略

  • 仓库：yyjeqhc/webcodex
  • 链接：https://github.com/yyjeqhc/webcodex
  • 分类：AI 开发工具 · 本地工具链桥接
  • 作者：Jay
  • 更新：2026-09-29

是什么

WebCodex 是一个本地开发环境桥接工具，让云端 AI Agent（如 ChatGPT、Claude）直接使用你本机已有的真实代码仓库、Git 工作区和开发工具链，而不需要把代码上传到任何托管服务或云端沙箱。

核心定位是把「AI 客户端（MCP）」和「你的真实机器」连接起来：AI 负责理解、修改、审查代码，运行测试和命令；代码、编译器、Git 历史都在你自己的电脑上，不需要迁移任何文件。

解决什么问题

AI 编码 Agent（如 Cursor、Claude Code）目前有两类局限：

  • 云端沙箱限制：代码需要上传到服务提供商的服务器才能被 AI 访问，存在隐私风险，且无法使用本地特定的工具链（编译器、系统库、项目配置）。
  • 上下文窗口压缩：项目一大，AI 的上下文容量就被代码占满，效率下降。

WebCodex 通过 MCP（Model Context Protocol）协议，在不移动代码的前提下，让 AI 客户端直接读写本地仓库、查看 Git diff、执行命令、运行测试，代码始终留在本机。

典型痛点：开发者想用 AI 审查公司私有代码库、不想把专有项目放进托管的 AI 工作区、需要 AI 能运行项目特定的测试和构建脚本。

快速安装

⚠️ 统一安装包仍在开发中

文档明确说明：Windows NSIS、macOS .pkg、Debian .deb 六类安装包仍需原生构建和验收才能发布，三种平台的 GUI 行为和升级流程尚未全部验收，跨平台体验不保证一致。请先查看 部署验收清单。

当前可用方式

方式一：直接下载 Release（推荐尝鲜）

# 访问 GitHub Releases 下载对应平台的二进制
# https://github.com/yyjeqhc/webcodex/releases/latest

方式二：源码编译（需 Rust）

# 依赖：Git + Rust (stable toolchain via rustup)
git clone https://github.com/yyjeqhc/webcodex.git
cd webcodex

# 使用 dogfood profile 构建，产出在 target/dogfood/
cargo build --locked --profile dogfood --workspace --bins

方式三：Docker 部署

# 参考 docs/DEPLOYMENT.md 中的 Docker 说明
# （具体镜像名和标签请以实际 Release 为准）
docker pull ghcr.io/yyjeqhc/webcodex:latest

方式四：npm / runtime 压缩包

# 高级用户，参考 docs/DEPLOYMENT.md

快速试用（单仓库临时体验）

# 安装后，用 share 命令临时共享一个仓库给 AI 客户端
webcodex share /path/to/your/repo
# 输出一个连接地址，填入 AI 客户端的 MCP 配置

核心用法

连接 AI 客户端（以 MCP 为例）

  1. 启动 WebCodex Desktop 或 Server
  2. 在 ChatGPT / Claude 客户端的 MCP 设置中，添加 WebCodex 服务器地址（通常是 http://127.0.0.1:PORT，具体端口参看 Server 启动输出）
  3. AI 客户端即可通过 MCP 协议访问配置的仓库

WebCodex Desktop 日常操作

  • 添加项目：在 Desktop 界面中注册希望 AI 访问的本地仓库目录
  • 查看活动：实时查看 AI 对哪些文件做了读写操作、运行了哪些命令
  • Git 可见性：所有 Git 操作（status、diff、log）保持在人类可审查状态
  • 后台运行：Server 可以长期运行，任务结果通过 Web UI 持续可查

运行时控制台

AI 执行长时间任务时，可以打开 Runtime Console 查看进度，而不是让一次 AI 对话一直等到超时。任务结果、测试输出都在 Console 中可见，支持人工审查后再决定是否继续。

架构简介

AI 客户端 (ChatGPT/Claude)
       |
       | MCP / HTTPS
       v
  WebCodex Server
       |
       v
   本机机器
       +-- repository（代码仓库）
       +-- Git（工作区、diff）
       +-- compilers / tests / developer tools

Server 负责接收 AI 请求、路由到 Runner 执行命令、管理认证和权限边界。具体协议细节见 docs/ARCHITECTURE.md 和 docs/MCP.md。

CLI 参考

# 启动 Desktop
webcodex desktop

# 启动 Server
webcodex server

# 临时共享一个仓库
webcodex share /path/to/repo

# 连接凭证管理
webcodex auth

详细 CLI 命令见 docs/CLI.md。

典型适用场景

  1. 私有代码库 AI 审查：公司内部项目不想上传到任何第三方，WebCodex 让 AI 直接在本地仓库工作，代码不出本机。
  2. 依赖特殊工具链的项目：需要调用特定编译器、CUDA 版本、系统库的工程，AI 直接用本机工具执行，比云端沙箱更真实。
  3. AI + Git 协同开发：AI 修改代码后，人类可以通过 git diff 审查每一步变化，防止 AI 擅自改坏代码。
  4. 长期任务保持可观察：AI 运行测试套件或构建脚本时，不需要一个对话窗口一直开着，任务在后台执行，人类随时可查。
  5. 多机器共享一套 AI 环境：在个人工作站安装 Server，在持有仓库的其他机器上安装 Runner，通过 MCP 跨机器协作。

坑与注意

  1. ⚠️ 统一安装包尚未正式发布：文档明确警告六类安装包仍在开发中，跨平台行为不保证一致。若遇安装问题，参考 deployment validation 核查当前验收状态。
  2. ⚠️ 统一安装流程仍在开发：多台电脑配置场景建议等正式 Release；当前尝鲜建议用 Release 二进制或源码编译。
  3. 安全边界需自行评估：WebCodex 在配置的项目范围内可以读写文件、执行任意命令。使用前建议通读 SECURITY.md，不要把凭据写入提示词或日志。
  4. 仅限受保护项目：建议只用版本控制管理项目目录，注册 AI 访问范围时限定在必要目录内，避免越权访问。
  5. 长任务需要 Server 持续运行：如果 AI 需要运行长时间构建/测试任务，对应 Server/Runner 进程不能中断，需要配置为持久运行（systemd 或类似）。
  6. MCP 客户端兼容性：部分旧版 AI 客户端 MCP 实现可能与 WebCodex 有细微差异，遇到认证或连接问题参考 TROUBLESHOOTING.md。

与同类对比

方案 代码存储 工具链真实性 部署复杂度 隐私保证
WebCodex 本机，不上传 ✅ 真实本机工具链 中（需配置 Server/Runner） ✅ 完全本地
Cursor Cloud / Claude Code Cloud 云端 ⚠️ 模拟环境 低（开箱即用） ⚠️ 代码上传云端
直接给 AI 写文件（传统方式） 通过对话传递 ❌ 无法运行测试/编译 低 ❌ 上下文窗口受限
GitHub Copilot Workspace 云端 + 拉取 PR ⚠️ 云端执行 中 ⚠️ 部分数据在 GitHub
LocalAI + 自建 Agent 本机 ✅ 本机 高（需自己搭） ✅ 完全本地

结论：WebCodex 是目前唯一在「本机代码不移动」+「真实工具链可用」+「MCP 协议兼容主流 AI 客户端」三个维度同时满足的方案，适合隐私敏感且依赖特殊本地工具链的开发者。

一句话推荐结论

如果你需要在不把代码上传云端的前提下，让 ChatGPT/Claude 直接阅读、修改、测试你本机的真实项目——WebCodex 是目前最干净的解决方案，安装前记得先查一下 unified-deployment-validation 确认当前版本是否已通过你所在平台的验收。