English · 简体中文
WebCodex
让云端 AI Agent 使用你自己机器上的真实开发环境。
把 ChatGPT、Claude 等 MCP 客户端连接到你已有的仓库、Git 工作区和开发工具。
一台电脑 · 多台电脑 · 文档 · Issues · 参与贡献 · 安全说明
WebCodex 是自托管工具运行时：Server 认证请求，并将请求路由到仓库所在机器上的 Runner。你可以直接让 AI 理解项目、修改代码、运行测试、检查 Git 或排查问题。无需把整个项目搬到托管环境里；按请求读取的文件内容和其他工具结果仍可能返回给 AI 客户端。
## 开始使用 WebCodex
临时体验单个仓库可先查看[快速试用](docs/QUICK_START.zh-CN.md)，使用 `webcodex share`。长期使用的统一安装流程仍在开发中，请先查看[验收状态](docs/unified-deployment-validation.md)。对应安装包通过验收并发布后，按代码所在位置选择安装方式：
- **一台电脑：**在个人工作站安装 WebCodex，打开 Desktop，并按[统一安装指南](docs/unified-installation.zh-CN.md)操作。每个平台的统一安装包包含 Desktop、CLI、Server 和 Runner。
- **多台电脑：**在承载 WebCodex Server 的机器以及持有代码仓库的每台机器上安装相同平台安装包。按[统一安装指南](docs/unified-installation.zh-CN.md#多台电脑)和[部署验收清单](docs/unified-deployment-validation.md)操作。
面向 Windows NSIS、macOS 安装包和 Debian 12 / Ubuntu 22.04+ `.deb` 的 x64、arm64 统一安装包是**构建流程定义的交付目标**，六类安装文件仍需完成原生构建和安装验收后才能发布。三种平台的真实机器安装、重启持久性、GUI 行为和升级尚未全部验收；本文档不宣称跨平台体验一致。已发布文件见 [GitHub Releases](https://github.com/yyjeqhc/webcodex/releases)。仓库 [`download/`](download/README.md) 目录仅包含静态页面源文件；[下载页 workflow](https://github.com/yyjeqhc/webcodex/actions/workflows/download-page.yml) 会在 Release 发布后根据 manifest 构建 GitHub Actions artifact，但不会托管或部署网页。源码预览请检出要验证的功能分支或发布修订，再按 [Desktop 开发指南](docs/DESKTOP_DEVELOPMENT.zh-CN.md#linux-源码预览与已有-server)操作。
Linux 机器不安装 Desktop 而加入已有 Server，请看 [Runtime 安装与 CLI 加入](docs/runtime-installation.zh-CN.md)。高级自托管、npm/runtime 压缩包、Docker 和历史版本请看[部署指南](docs/DEPLOYMENT.zh-CN.md)。
## 能做什么？
- **理解和修改代码** —— 读取、搜索、分析项目，并在配置好的项目范围内进行受保护的修改。
- **使用真实开发环境** —— 在仓库所在机器上运行命令、测试、格式化、编译器和项目自己的工具。
- **检查 Git** —— 查看状态和差异，让代码变化保持可见、可审查。
- **处理长时间任务** —— 任务可以持续运行并保持可观察，不需要一次模型回复一直等待到底。
- **保留人工审查** —— 通过 [Runtime Console](docs/runtime-console.md)、Workflow Session 证据、Job 和 Git 差异审查工作，无需额外的任务/结果验收子系统。
## 为什么用 WebCodex？
- **代码留在自己的机器上。** 不需要把整个仓库上传到聊天服务。
- **AI 使用的是真实开发环境。** 文件、Git、编译器、测试和已有工具链都可以直接复用。
- **工作不局限于一次请求。** 长时间执行、测试结果和相关证据可以继续观察。
- **既能临时使用，也能长期部署。** 可以一条命令快速分享，也可以连接到自托管服务长期使用。
## 工作方式
```text
AI 客户端
|
| MCP / HTTPS
v
WebCodex Server
|
| 经过认证的 Runner 连接
v
你机器上的 Runner
|
+-- 代码仓库
+-- Git
+-- 编译器 / 测试 / 开发工具
```
如果需要了解内部的 Server/Runner 架构、协议接口和权限边界，再阅读[架构说明](docs/ARCHITECTURE.md)、[MCP](docs/MCP.zh-CN.md)和[认证模型](docs/AUTH_MODEL.zh-CN.md)。
## Star History
下图展示上游仓库 [yyjeqhc/webcodex](https://github.com/yyjeqhc/webcodex) 的 Star 历史。
## 平台安装包
统一安装包目标平台为 Windows NSIS、macOS 和 Debian 12 / Ubuntu 22.04+ `.deb`，支持 x64 与 arm64。构建流程定义了这些目标；六类安装文件仍需完成原生构建和安装验收后才能发布。详见[统一安装指南](docs/unified-installation.zh-CN.md)和[验收清单](docs/unified-deployment-validation.md)。现有 Release artifact 与 npm/Docker 部署路径仍作为高级历史/兼容参考保留在[部署指南](docs/DEPLOYMENT.zh-CN.md)。
## 文档
- [统一安装指南](docs/unified-installation.zh-CN.md) —— 统一安装包的个人与多机配置
- [部署验收清单](docs/unified-deployment-validation.md) —— 各平台验收状态与真实机器检查项
- [Runtime 安装与 CLI 加入](docs/runtime-installation.zh-CN.md) —— 无 Desktop 的 Linux Runner 配置与安装包更新/恢复
- [旧版 Desktop 安装指南](docs/desktop-install.zh-CN.md) —— 现有 Release 的详细说明
- [Desktop 日常使用](docs/desktop-guide.zh-CN.md) —— 项目、连接、活动与后台运行
- [Desktop Runtime 兼容说明](docs/DESKTOP_RUNTIME_COMPATIBILITY.zh-CN.md) —— 兼容 Runtime 选择、诊断与回滚
- [Runtime Console](docs/runtime-console.md) —— 浏览器中的活动、项目、Session 与 Agent 通信
- [任务接续](docs/SESSION_CONTINUITY.zh-CN.md) —— 显式保存并跨对话继续有权访问的工作
- [Desktop 开发与打包](docs/DESKTOP_DEVELOPMENT.zh-CN.md) —— 在 Linux、Windows、macOS 从源码运行，以及本地打包
- [完整使用指南](docs/PERSONAL_SETUP.zh-CN.md) —— CLI、已有 Server、Linux 与高级普通 Server + Runner 配置
- [快速试用](docs/QUICK_START.zh-CN.md) —— 用 `share` 临时体验一个仓库
- [MCP](docs/MCP.zh-CN.md) —— ChatGPT、Claude、认证方式和 MCP 参考
- [部署指南](docs/DEPLOYMENT.zh-CN.md) —— 生产、自托管和高级运维
- [故障排查](docs/TROUBLESHOOTING.zh-CN.md) —— ChatGPT/MCP Host、连接和运行问题
- [CLI](docs/CLI.zh-CN.md) —— 命令与凭据参考
- [AI 辅助接入](docs/AI_ONBOARDING.zh-CN.md) —— 让 AI 帮你配置 WebCodex
- [安全说明](SECURITY.md) —— 安全模型与使用建议
- [文档索引](docs/INDEX.zh-CN.md) —— 全部用户和贡献者文档
## 安全
WebCodex 能在配置的项目范围内读取和修改文件、执行命令。建议使用版本控制，不要把凭据写进提示词、日志或 Git，只注册确实希望 AI 访问的项目目录。工具返回的结果（包括按请求读取的文件片段）可能传给 AI 客户端。完整安全模型见 [SECURITY.md](SECURITY.md)。
## 从源码构建
如果已发布版本遇到问题，不必只能等待维护者发布新版本。欢迎先在最新 `main`
复现问题，在本地构建并验证 focused fix，然后直接提交 pull request。
CLI / Server / Runner 开发需要先安装 [Git](https://git-scm.com/) 和通过
[rustup](https://rustup.rs/) 安装的 stable Rust toolchain，然后使用日常 dogfood
profile 构建：
```bash
cargo build --locked --profile dogfood --workspace --bins
```
产物位于 `target/dogfood/`。如果修改 Desktop/frontend，还需要 Node.js 22 + npm
以及对应平台的 native toolchain。Windows Desktop 开发需要 MSVC / Windows SDK
环境；macOS 需要 Xcode Command Line Tools。完整 prerequisites、源码运行和打包流程见
[Desktop 开发与打包](docs/DESKTOP_DEVELOPMENT.zh-CN.md)。
本地验证 Desktop installer 时请使用仓库 helper，而不是直接执行 raw Tauri bundle：
```powershell
# Windows：clean 且已提交的源码
.\scripts\build_desktop_windows_local.ps1
# Windows：显式把未提交修改打成 dirty dogfood installer
.\scripts\build_desktop_windows_local.ps1 -AllowDirty
```
```bash
# macOS
bash scripts/build_desktop_macos_local.sh
```
这些属于开发/dogfood 构建，不是正式 Release artifact。
## 参与贡献
欢迎提交 Issue，也非常欢迎 focused pull request。维护者响应时间可能有所变化，因此如果
能够在最新 `main` 复现问题，尤其欢迎直接排查、在本地构建验证修复并提交 PR，而不必
等待维护者先实现。可以使用 WebCodex 本身、Codex、ChatGPT、Claude 或其他 coding
agent 辅助阅读、修改和验证仓库。
Bug 报告需要提供哪些信息、自助修复流程、验证要求与 PR 说明见
[CONTRIBUTING.zh-CN.md](CONTRIBUTING.zh-CN.md)。
## 支持 WebCodex ☕
如果 WebCodex 对你有所帮助，欢迎自愿扫码请维护者喝杯咖啡；不赞助也完全不影响使用，Star、反馈问题和贡献代码同样很有帮助。[赞赏说明](docs/SPONSORSHIP.zh-CN.md)。
| 微信赞赏 | 支付宝收款 |
| :---: | :---: |
| 
| 
|
点击图片可以打开或保存高清二维码，方便使用手机相册识别。付款前请在支付应用中核对收款人；这是向维护者个人的自愿赞赏，不由 GitHub 代收。
## 致谢
感谢 [LINUX DO](https://linux.do/) 社区提供友好的技术交流与开源分享环境。
感谢 [AtomGit](https://atomgit.com/) 在国内托管 WebCodex 镜像，方便中国大陆用户访问项目并获取发布版本。
## 许可证
使用 Apache License 2.0，见 [LICENSE](LICENSE)。
## Desktop Shell 与 Runtime 升级
Desktop 可以保留当前 Shell，并使用单独选择的兼容 Runtime。构建修订与软件版本用于诊断，不是兼容性开关。自行构建、切换与恢复、追踪、诊断报告与更新提示见 [Desktop Runtime 兼容说明](docs/DESKTOP_RUNTIME_COMPATIBILITY.zh-CN.md)。