diff --git a/README.md b/README.md index 773af8aec..f0f8fc13c 100644 --- a/README.md +++ b/README.md @@ -1,18 +1,22 @@ -# WebCodex +

English · 简体中文

-[English](README.md) | [简体中文](README.zh-CN.md) +

WebCodex

-**WebCodex lets ChatGPT, Claude, and other AI agents work directly with code and developer tools on your own machines.** +

WebCodex

-Ask your assistant to inspect a repository, modify code, run tests, use Git, or investigate a failure. Your repository stays on the machine where it already lives; you do not need to move the project into a hosted workspace just to use an AI coding agent. +

Give cloud AI agents a real development environment on your own machines.

+

Connect ChatGPT, Claude, and other MCP clients to the repositories, Git checkout, and tools you already use.

+

Quick Trial · Downloads · Full Setup · Documentation · Security

-## Start using WebCodex +

+ MCP protocol + Node.js 18 or newer + Apache 2.0 license +

-### Everyday development: full WebCodex (recommended) - -If you want ChatGPT to keep using your real development environment, start with a **regular Server + Runner**. This is the full development experience: durable access to multiple projects plus project exploration, editing, Git, commands, tests, long-running work, and code navigation. Public HTTPS, Cloudflare Tunnel, and OpenAI Secure MCP Tunnel are only ways for ChatGPT to reach the Server; they do not switch you into a different restricted experience. +Ask your assistant to inspect a repository, modify code, run tests, use Git, or investigate a failure. Your repository stays on the machine where it already lives; you do not need to move the project into a hosted workspace just to use an AI coding agent. -Follow the [Full Setup guide](docs/PERSONAL_SETUP.md) for installation, one-time login, project selection, Runner startup, and ChatGPT connection. You do not need to learn internal identity, registry, or token details before the first successful setup. +## Start using WebCodex ### Just trying it for a few minutes: temporary share @@ -23,7 +27,28 @@ cd /path/to/your/repository npx --yes @yyjeqhc/webcodex share ``` -`share` starts a temporary, single-project, restricted WebCodex environment and prints the ChatGPT connection values. The endpoint and temporary credential stop working when the command exits. It is intended for trials and short-lived sharing, not as the default full daily setup. See the [Quick Trial](docs/QUICK_START.md) for the exact steps. +`share` starts a temporary, single-project WebCodex environment and prints the ChatGPT connection values. The endpoint and credential stop working when the command exits. It is intended for trials and short-lived sharing, not as the default full daily setup. See the [Quick Trial](docs/QUICK_START.md) for the exact steps. + +### Everyday development: full WebCodex (recommended) + +If you want ChatGPT to keep using your real development environment, start with a **regular Server + Runner**. This is the full development experience: durable access to multiple projects plus project exploration, editing, Git, commands, tests, long-running work, and code navigation. Public HTTPS, Cloudflare Tunnel, and OpenAI Secure MCP Tunnel are only ways for ChatGPT to reach the Server; they do not switch you into a different restricted experience. + +For Windows or macOS, the recommended first path is **WebCodex Desktop + the official OpenAI Secure Tunnel**. Follow the [upstream Desktop installation guide](https://github.com/yyjeqhc/webcodex/blob/main/docs/desktop-install.md). For CLI, an existing Server, self-hosting, or advanced setup, use the [Full Setup guide](docs/PERSONAL_SETUP.md). + +### Download a release + +The links below are **official upstream v0.4.1 releases**. They are newer than the source currently on this fork's `main` branch. Choose a Desktop installer for ordinary Windows/macOS use, or a native CLI archive for Server/Runner workflows. [View the release and checksums](https://github.com/yyjeqhc/webcodex/releases/tag/v0.4.1). + +| Platform | Desktop | CLI / Server / Runner | +| --- | --- | --- | +| Windows x64 | [Installer](https://github.com/yyjeqhc/webcodex/releases/download/v0.4.1/webcodex-desktop-v0.4.1-win32-x64-setup.exe) | [Archive](https://github.com/yyjeqhc/webcodex/releases/download/v0.4.1/webcodex-v0.4.1-win32-x64.tar.gz) | +| Windows arm64 | — | [Archive](https://github.com/yyjeqhc/webcodex/releases/download/v0.4.1/webcodex-v0.4.1-win32-arm64.tar.gz) | +| macOS Apple Silicon | [DMG](https://github.com/yyjeqhc/webcodex/releases/download/v0.4.1/webcodex-desktop-v0.4.1-darwin-arm64.dmg) | [Archive](https://github.com/yyjeqhc/webcodex/releases/download/v0.4.1/webcodex-v0.4.1-darwin-arm64.tar.gz) | +| macOS Intel | [DMG](https://github.com/yyjeqhc/webcodex/releases/download/v0.4.1/webcodex-desktop-v0.4.1-darwin-x64.dmg) | [Archive](https://github.com/yyjeqhc/webcodex/releases/download/v0.4.1/webcodex-v0.4.1-darwin-x64.tar.gz) | +| Linux x64 | — | [Archive](https://github.com/yyjeqhc/webcodex/releases/download/v0.4.1/webcodex-v0.4.1-linux-x64.tar.gz) | +| Linux arm64 | — | [Archive](https://github.com/yyjeqhc/webcodex/releases/download/v0.4.1/webcodex-v0.4.1-linux-arm64.tar.gz) | + +The npm installation path remains `npm install -g @yyjeqhc/webcodex` (Node.js 18+). ## What can it do? @@ -31,7 +56,7 @@ npx --yes @yyjeqhc/webcodex share - **Use the real toolchain** — run commands, tests, formatters, compilers, and project-specific tooling on the machine that owns the repository. - **Work with Git** — inspect status and diffs while keeping repository operations visible and reviewable. - **Handle long-running work** — keep jobs observable instead of requiring one model turn to stay open indefinitely. -- **Support human review** — use the Runtime Console and task workflow to guide, cancel, accept, or reject work where those actions are available. +- **Support human review** — use the Runtime Console, Workflow Session evidence, Jobs, and Git/diff review without a separate task/result acceptance subsystem. ## Why WebCodex? @@ -61,21 +86,26 @@ For the internal Server/Runner architecture, protocol surfaces, and authority bo ## Platforms +The platform capabilities below describe the official upstream release linked above. + - **Linux x64/arm64** — local `share`, Server, and Runner workflows. -- **macOS x64/arm64** — local `share` and Runner workflows. -- **Windows x64/arm64** — CLI + Runner, local foreground Server, and explicit `webcodex share --tunnel cloudflare|openai|none`. Windows x64 can auto-manage the pinned Cloudflare Quick Tunnel binary; OpenAI `tunnel-client` is managed on both x64 and arm64. Cloudflare does not publish a Windows ARM64 artifact for the pinned release, so Windows ARM64 Cloudflare sharing requires a trusted explicit/PATH `cloudflared`. WebCodex-managed Windows Server services remain unsupported. +- **macOS x64/arm64** — Desktop local Server + Runner, OpenAI Secure Tunnel, local `share`, and standalone Runner workflows. +- **Windows x64** — Desktop local Server + Runner with the official OpenAI Secure Tunnel, plus CLI + Runner, local foreground Server, and explicit `webcodex share --tunnel cloudflare|openai|none`. +- **Windows arm64** — CLI + Runner, local foreground Server, and `share`; managed OpenAI `tunnel-client` is supported. The pinned Cloudflare release has no official Windows ARM64 artifact, so Cloudflare requires a trusted explicit/PATH `cloudflared`. The Desktop installer is currently Windows x64 only. WebCodex-managed Windows Server services remain unsupported outside Desktop's owned foreground runtime. Windows and long-lived deployments are covered in [Deployment](docs/DEPLOYMENT.md) and [MCP](docs/MCP.md). ## Existing Servers and advanced setup -If someone already provides the WebCodex Server and connection credential, use that existing Server. For a normal personal installation, follow the [Full Setup guide](docs/PERSONAL_SETUP.md). Use [Deployment](docs/DEPLOYMENT.md) later for production hosting, multiple users, systemd/Docker, OAuth, proxies, and private CAs. +If someone already provides the WebCodex Server and connection credential, use that existing Server and follow the [Full Setup guide](docs/PERSONAL_SETUP.md). For a normal Windows/macOS personal installation, use the [upstream Desktop guide](https://github.com/yyjeqhc/webcodex/blob/main/docs/desktop-install.md). Use [Deployment](docs/DEPLOYMENT.md) only for production hosting, multiple users, systemd/Docker, OAuth, proxies, and private CAs. Those are follow-up operating concerns, not concepts a first-time user should have to learn before WebCodex works. ## Documentation -- [Full Setup](docs/PERSONAL_SETUP.md) — recommended daily use: a regular Server + Runner + your projects +- [Upstream Desktop installation](https://github.com/yyjeqhc/webcodex/blob/main/docs/desktop-install.md) — recommended Windows/macOS path: Desktop + official OpenAI Secure Tunnel +- [Using upstream Desktop](https://github.com/yyjeqhc/webcodex/blob/main/docs/desktop-guide.md) — projects, connections, activity, and background operation +- [Full Setup](docs/PERSONAL_SETUP.md) — CLI, existing Server, Linux, and advanced regular Server + Runner setup - [Quick Trial](docs/QUICK_START.md) — temporarily try one repository with `share` - [MCP](docs/MCP.md) — ChatGPT, Claude, authentication choices, and MCP reference - [Deployment](docs/DEPLOYMENT.md) — production, self-hosting, and advanced operations @@ -87,7 +117,7 @@ Those are follow-up operating concerns, not concepts a first-time user should ha ## Security -WebCodex can read and modify files and execute commands inside configured project boundaries. Use version control, keep credentials out of prompts/logs/Git, and register only project roots the assistant should access. Read [SECURITY.md](SECURITY.md) for the complete model. +WebCodex can read and modify files and execute commands inside configured project boundaries. Use version control, keep credentials out of prompts/logs/Git, and register only project roots the assistant should access. Tool results, including requested file excerpts, may be returned to the AI client. Read [SECURITY.md](SECURITY.md) for the complete model. ## Build from source diff --git a/README.zh-CN.md b/README.zh-CN.md index dca27d180..6c531f446 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -1,18 +1,22 @@ -# WebCodex +

English · 简体中文

-[English](README.md) | [简体中文](README.zh-CN.md) +

WebCodex 标志

-**WebCodex 让 ChatGPT、Claude 和其他 AI Agent 直接使用你自己机器上的代码仓库和开发工具。** +

WebCodex

-你可以直接让 AI 理解项目、修改代码、运行测试、检查 Git 或排查问题。仓库仍然留在原来的机器上，不需要为了使用 WebCodex 把整个项目搬到托管环境里。 +

让云端 AI Agent 使用你自己机器上的真实开发环境。

+

把 ChatGPT、Claude 等 MCP 客户端连接到你已有的仓库、Git 工作区和开发工具。

+

快速试用 · 下载 · 完整配置 · 文档 · 安全说明

-## 开始使用 +

+ MCP 协议 + 需要 Node.js 18 或更新版本 + Apache 2.0 许可证 +

-### 日常使用：完整 WebCodex（推荐） - -如果你准备让 ChatGPT 长期使用自己的开发环境，推荐从 **普通 Server + Runner** 开始。这是 WebCodex 的完整开发体验：可以长期连接多个项目，并使用项目探索、编辑、Git、命令、测试、长任务和代码导航能力。公网 HTTPS、Cloudflare Tunnel 或 OpenAI Secure MCP Tunnel 只是 ChatGPT 到 Server 的连接方式，不会把你切换到另一套受限体验。 +你可以直接让 AI 理解项目、修改代码、运行测试、检查 Git 或排查问题。仓库仍然留在原来的机器上，不需要为了使用 WebCodex 把整个项目搬到托管环境里。 -按照[完整使用指南](docs/PERSONAL_SETUP.zh-CN.md)完成安装、一次性登录、项目选择、Runner 启动和 ChatGPT 连接即可。第一次成功使用前，不需要理解内部身份、注册表或令牌细节。 +## 开始使用 ### 只想先试几分钟：临时分享 @@ -25,13 +29,34 @@ npx --yes @yyjeqhc/webcodex share `share` 会临时启动单项目、受限的 WebCodex 环境并给出 ChatGPT 连接信息；关闭命令后连接和临时凭据都会失效。它适合试用和临时分享，不是日常完整体验的默认部署方式。详细步骤见[快速试用](docs/QUICK_START.zh-CN.md)。 +### 日常使用：完整 WebCodex（推荐） + +如果你准备让 ChatGPT 长期使用自己的开发环境，推荐从 **普通 Server + Runner** 开始。这是 WebCodex 的完整开发体验：可以长期连接多个项目，并使用项目探索、编辑、Git、命令、测试、长任务和代码导航能力。公网 HTTPS、Cloudflare Tunnel 或 OpenAI Secure MCP Tunnel 只是 ChatGPT 到 Server 的连接方式，不会把你切换到另一套受限体验。 + +Windows / macOS 普通用户最推荐 **WebCodex Desktop + 官方 OpenAI Secure Tunnel**，直接按 [上游 Desktop 安装与连接指南](https://github.com/yyjeqhc/webcodex/blob/main/docs/desktop-install.zh-CN.md)操作即可；CLI、已有 Server、自托管或高级配置再看[完整使用指南](docs/PERSONAL_SETUP.zh-CN.md)。 + +### 下载发行版 + +下表链接到**上游官方 v0.4.1 Release**，版本比当前 fork 的 `main` 源码更新。Windows/macOS 普通使用可选择 Desktop 安装包；Server/Runner 工作流可选择对应平台的 CLI 压缩包。[查看发行说明与校验值](https://github.com/yyjeqhc/webcodex/releases/tag/v0.4.1)。 + +| 平台 | Desktop | CLI / Server / Runner | +| --- | --- | --- | +| Windows x64 | [安装包](https://github.com/yyjeqhc/webcodex/releases/download/v0.4.1/webcodex-desktop-v0.4.1-win32-x64-setup.exe) | [压缩包](https://github.com/yyjeqhc/webcodex/releases/download/v0.4.1/webcodex-v0.4.1-win32-x64.tar.gz) | +| Windows arm64 | — | [压缩包](https://github.com/yyjeqhc/webcodex/releases/download/v0.4.1/webcodex-v0.4.1-win32-arm64.tar.gz) | +| macOS Apple Silicon | [DMG](https://github.com/yyjeqhc/webcodex/releases/download/v0.4.1/webcodex-desktop-v0.4.1-darwin-arm64.dmg) | [压缩包](https://github.com/yyjeqhc/webcodex/releases/download/v0.4.1/webcodex-v0.4.1-darwin-arm64.tar.gz) | +| macOS Intel | [DMG](https://github.com/yyjeqhc/webcodex/releases/download/v0.4.1/webcodex-desktop-v0.4.1-darwin-x64.dmg) | [压缩包](https://github.com/yyjeqhc/webcodex/releases/download/v0.4.1/webcodex-v0.4.1-darwin-x64.tar.gz) | +| Linux x64 | — | [压缩包](https://github.com/yyjeqhc/webcodex/releases/download/v0.4.1/webcodex-v0.4.1-linux-x64.tar.gz) | +| Linux arm64 | — | [压缩包](https://github.com/yyjeqhc/webcodex/releases/download/v0.4.1/webcodex-v0.4.1-linux-arm64.tar.gz) | + +也可以通过 npm 安装：`npm install -g @yyjeqhc/webcodex`（需要 Node.js 18+）。 + ## 能做什么？ - **理解和修改代码** —— 读取、搜索、分析项目，并在配置好的项目范围内进行受保护的修改。 - **使用真实开发环境** —— 在仓库所在机器上运行命令、测试、格式化、编译器和项目自己的工具。 - **检查 Git** —— 查看状态和差异，让代码变化保持可见、可审查。 - **处理长时间任务** —— 任务可以持续运行并保持可观察，不需要一次模型回复一直等待到底。 -- **保留人工审查** —— 可以通过运行时控制台和任务流程进行指导、取消、接受或拒绝。 +- **保留人工审查** —— 可以通过运行时控制台、任务状态和 Git 差异查看工作结果。 ## 为什么用 WebCodex？ @@ -61,21 +86,26 @@ WebCodex ## 平台支持 +以下平台能力以链接的上游官方版本为准。 + - **Linux x64/arm64** —— 支持本机 `share`、Server 和 Runner 工作流。 -- **macOS x64/arm64** —— 支持本机 `share` 和 Runner 工作流。 -- **Windows x64/arm64** —— 支持 CLI、Runner、本地前台 Server，以及显式 `webcodex share --tunnel cloudflare|openai|none`。Windows x64 可自动管理固定版本的 Cloudflare Quick Tunnel；OpenAI `tunnel-client` 在 x64/arm64 都支持 managed 获取。固定版本 Cloudflare 没有官方 Windows ARM64 artifact，因此 Windows ARM64 使用 Cloudflare 时需要提供受信任的显式/`PATH` `cloudflared`。WebCodex 托管的 Windows Server service 仍不支持。 +- **macOS x64/arm64** —— 支持 Desktop 本机 Server + Runner、OpenAI Secure Tunnel、本机 `share` 和独立 Runner 工作流。 +- **Windows x64** —— 推荐 Desktop 本机 Server + Runner + 官方 OpenAI Secure Tunnel；同时支持 CLI + Runner、本地前台 Server，以及显式 `webcodex share --tunnel cloudflare|openai|none`。 +- **Windows arm64** —— 支持 CLI + Runner、本地前台 Server 与 `share`，managed OpenAI `tunnel-client` 可用。固定版本 Cloudflare 没有官方 Windows ARM64 artifact，因此使用 Cloudflare 时需要受信任的显式/`PATH` `cloudflared`。当前 Desktop installer 仅提供 Windows x64。除 Desktop 自己托管的前台 runtime 外，WebCodex-managed Windows Server service 仍不支持。 Windows 接入和长期部署见[部署指南](docs/DEPLOYMENT.zh-CN.md)与 [MCP](docs/MCP.zh-CN.md)。 ## 已有 Server 与高级配置 -如果已经有人为你提供 WebCodex Server 和接入凭据，可以直接使用已有 Server；普通个人完整安装见[完整使用指南](docs/PERSONAL_SETUP.zh-CN.md)。生产环境、多用户、systemd/Docker、OAuth、代理/私有 CA 等运维内容再查看[部署指南](docs/DEPLOYMENT.zh-CN.md)。 +如果已经有人为你提供 WebCodex Server 和接入凭据，直接使用已有 Server 并看[完整使用指南](docs/PERSONAL_SETUP.zh-CN.md)。普通 Windows / macOS 个人安装使用 [上游 Desktop 指南](https://github.com/yyjeqhc/webcodex/blob/main/docs/desktop-install.zh-CN.md)。生产环境、多用户、systemd/Docker、OAuth、代理/私有 CA 等运维内容再查看[部署指南](docs/DEPLOYMENT.zh-CN.md)。 这些是后续配置，不应该成为第一次使用 WebCodex 的概念负担。 ## 文档 -- [完整使用指南](docs/PERSONAL_SETUP.zh-CN.md) —— 日常使用推荐：普通 Server + Runner + 你的项目 +- [上游 Desktop 安装与连接](https://github.com/yyjeqhc/webcodex/blob/main/docs/desktop-install.zh-CN.md) —— Windows / macOS 推荐路径：Desktop + 官方 OpenAI Secure Tunnel +- [上游 Desktop 日常使用](https://github.com/yyjeqhc/webcodex/blob/main/docs/desktop-guide.zh-CN.md) —— 项目、连接、活动与后台运行 +- [完整使用指南](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) —— 生产、自托管和高级运维 @@ -87,7 +117,7 @@ Windows 接入和长期部署见[部署指南](docs/DEPLOYMENT.zh-CN.md)与 [MCP ## 安全 -WebCodex 能在配置的项目范围内读取和修改文件、执行命令。建议使用版本控制，不要把凭据写进提示词、日志或 Git，只注册确实希望 AI 访问的项目目录。完整安全模型见 [SECURITY.md](SECURITY.md)。 +WebCodex 能在配置的项目范围内读取和修改文件、执行命令。建议使用版本控制，不要把凭据写进提示词、日志或 Git，只注册确实希望 AI 访问的项目目录。工具返回的结果（包括按请求读取的文件片段）可能传给 AI 客户端。完整安全模型见 [SECURITY.md](SECURITY.md)。 ## 从源码构建 diff --git a/docs/assets/brand/webcodex-app-icon.png b/docs/assets/brand/webcodex-app-icon.png new file mode 100644 index 000000000..490b4e1cc Binary files /dev/null and b/docs/assets/brand/webcodex-app-icon.png differ