简体中文 | English
项目来源：FreeCodeZ 是修改自 ZCode 的二次开发版本，不是原版 ZCode。原版 ZCode 是 GLM / Z.ai 生态的 AI 编程工作台；FreeCodeZ 保留其整体架构与能力，去除了 GLM 套餐与账号体系，并做了大量能力、隐私与体验适配。与原版的完整区别见 与 ZCode 的区别。
FreeCodeZ 是 AI 编程工作台，提供桌面应用、浏览器界面和终端 Agent。本仓库包含客户端、后端服务、共享 UI，以及 Agent CLI 与运行时源码。
| 入口 | 用途 | 开发命令 |
|---|---|---|
| Desktop | Electron 桌面应用 | pnpm dev:desktop |
| Web / ZCode 命令行版 | 终端与浏览器工作台；将 TUI、Web、后端和 Agent 组装为独立运行包 | pnpm dev:web |
| Agent CLI | 在终端中使用 zcode，也为 Desktop 和 Web 提供 Agent 运行时 |
pnpm --filter @zcode/cli dev |
FreeCodeZ 修改自 ZCode 的源码：Desktop、Web、终端 Agent 的整体架构沿用原版，GLM 不再有套餐概念，仅保留为可填 API Key 直连的模型厂商之一。核心区别总结如下：
| 对比维度 | ZCode（原版） | FreeCodeZ |
|---|---|---|
| 定位 | GLM / Z.ai 生态的 AI 编程工作台 | 多厂商通用的 AI 编程工作台 |
| 账号与计费 | Z.ai 账号 OAuth 登录；GLM 编码套餐（Coding Plan / Start Plan）展示、计费与购买升级 | 无账号与套餐体系；仅本地 API Key，通过接入向导连接各厂商 |
| 模型接入 | 以 GLM 系模型为主 | 模板化多厂商直连预设（Moonshot、MiniMax、DeepSeek、阿里百炼等） |
| 推理档位 | 无预设与兜底 | 按厂商预设 + 三层兜底（自动降级重试 / 错误横幅一键修复 / 无档位厂商兼容） |
| 搜索/抓取/视觉 | 能力不全（WebSearch 受门控，无图片搜索与读图工具） | P6 补齐：image_search 三源、WebSearch 混合回落、webfetch 正文提取、ImageUnderstand / ViewImage |
| 插件 | 官方插件市场在线安装 | 10 个内置插件随发行包种子，市场与已安装页对齐原版 |
| 遥测与外联 | 有遥测与性能上报链路 | 遥测全链路移除；外联上行禁止、下行允许（模型请求与资源下载正常，业务数据不外发） |
| 官方 MCP | zcode_official 鉴权与配额链路 | 移除，一律走通用 MCP 标准配置 |
- 移除 GLM 编码套餐（Coding Plan / Start Plan）的套餐展示、计费提示与购买升级入口。
- 移除 Z.ai 账号 OAuth 登录、网页授权回调、token 刷新等账号链路。
- 模型接入收敛为单一 API Key 形态，通过首页与设置页的接入向导连接各模型厂商。
image_search图片搜索：SerpAPI → Brave → Openverse 三源降级，带 SQLite 缓存、URL 归一化去重与 CC 许可筛选。WebSearch混合搜索：优先使用原生搜索，不可用时回落到客户端搜索（Brave / Exa / Linkup），回退结果附带模型侧综合摘要（可关）。webfetch网页抓取：支持输出格式选择与正文（article / main）提取。ImageUnderstand/ViewImage图像理解：通过绑定的视觉模型读图，未配置视觉模型时返回引导提示。- 设置页「搜索与视觉」专属分区：安全搜索、地区、摘要模式、视觉模型绑定（跨厂商选择，文本模型会话也可看图），搜索 API 密钥本地加密存储。
- 模型厂商接入：模板化 Provider 内置配置与接入向导，内置 Moonshot、MiniMax、DeepSeek、阿里百炼等直连预设；推理档位（reasoning effort）按厂商提供预设，并有三层兜底——请求被拒时自动降级重试、错误横幅一键修复、无档位厂商自动兼容。
- 插件体系：内置插件随发行包种子（documents、pdf、presentations、spreadsheets、skill-creator、plugin-creator、zcode-guide、android-emulator、ios-simulator、restore-legacy-sessions），插件市场与已安装页体验对齐上游。
- 隐私与外联：移除遥测与性能上报全链路；外联策略为上行禁止、下行允许——模型请求与资源下载正常，业务数据不外发。
- 移除官方 MCP 鉴权与配额链路（zcode_official），MCP 一律走通用标准配置。
- 侧栏 Provider 密钥状态提示、对话错误横幅归因等体验适配。
各改动的详细产品规则、状态归属与验收场景在内部 spec 文档中维护（不随仓库发布）。
准备 Git、Node.js 24.14.0 和 pnpm 10.33.2，版本以 mise.toml 为准。以下开发和打包命令均在仓库根目录执行。
pnpm bootstrappnpm bootstrap 安装 workspace 依赖、准备桌面本地运行资源，再执行 build:bootstrap。
Agent CLI 与运行时源码位于 apps/zcode-cli/，作为普通目录随本仓库一起克隆，无需单独拉取或初始化 Git submodule。
根据需要选择其他初始化或构建入口：
| 命令 | 用途 |
|---|---|
pnpm install |
安装依赖 |
pnpm prepare:desktop-runtime |
准备桌面运行资源，默认包含远程资源准备 |
pnpm prepare:remote-assets |
单独准备远程运行资源 |
pnpm bootstrap:with-remote |
初始化依赖、本地与远程资源，并串行构建相关包；跳过桌面应用 bundle |
pnpm build |
递归执行各 workspace 包的构建脚本，包括包内的资源准备步骤 |
默认 bootstrap 跳过远程资源准备，适合本地桌面开发。使用远程工作区或验证远程发行资源时，再运行对应准备命令。
pnpm dev:desktop
# 使用测试环境
pnpm dev:desktop:testpnpm dev:desktop 默认等同于 pnpm dev:desktop:prod，使用生产服务配置。启动脚本会准备本地运行资源、构建桌面 Agent，再启动 Electron 和源码监听。
需要独立开发数据目录时，可设置 ZCODE_DATA_BASE_DIR。例如在 macOS / Linux 中：
ZCODE_DATA_BASE_DIR="$HOME/.zcode-dev-home" pnpm dev:desktop:test先执行 pnpm bootstrap:with-remote 准备远程资源（mock-cdn），再 pnpm dev:desktop；连接远程项目时资源选择「本地下载后上传」。开发态资源取自本地 packages/desktop/mock-cdn 和本地构建产物，经 SFTP 上传到远程，不访问 CDN。
修改 Web 或后端源码时，使用开发模式：
pnpm dev:web
# 指定后端工作区（macOS / Linux）
ZCODE_SERVER_WORKSPACE=/path/to/project pnpm dev:web该命令同时启动 Web 开发服务器（默认 http://localhost:5173）和后端（默认 http://localhost:3030）；浏览器访问前者。/ws 和一般 /api 请求代理到本地后端，/api/v1/oauth/token 单独代理到当前配置的产品服务。
Agent 源码修改后，执行 pnpm --filter @zcode/cli... build 并重启服务。需要验证完整发行包时，按下方“ZCode 命令行版”打包章节解压运行。
命令行发行包包含 TUI、Web 和 Agent，统一使用 zcode 启动：无参数进入 TUI；第一个参数为 --web 时启动 Web；其他参数交给现有 Agent CLI 处理。两种模式都在本机运行，无需 Electron。
# 默认进入终端交互界面
zcode
# 启动 Web 界面
zcode --web
# 指定项目和端口，不自动打开浏览器
zcode --web --workspace /path/to/project --port 3030 --no-open
# 查看 CLI 或 Web 参数
zcode --help
zcode --web --helpWeb 模式默认工作目录为当前目录，监听 127.0.0.1，默认不启用访问令牌，自动选择空闲端口并打开浏览器。访问终端输出的地址，按 Ctrl+C 停止服务。局域网访问可使用 --host 0.0.0.0；监听非本机地址时默认生成访问令牌，使用终端输出的带令牌链接。可通过 --token 指定令牌或 --no-token 关闭令牌认证。
直接启动通用 Web 服务的 HTTP 入口时，通过 ZCODE_SERVER_AUTH_TOKEN 配置 API／WebSocket 认证；通过程序接口创建服务时，使用 authToken 选项。
构建方式见下方打包章节。pnpm build:zcode 只生成发行包，不会替换 PATH 中已有的 zcode。如果命令仍指向旧安装或其他源码目录，macOS / Linux 可用 command -v zcode 检查，Windows 可用 where.exe zcode 检查。
直接开发 TUI 或 Agent 时，运行源码入口：
pnpm --filter @zcode/cli dev --help
pnpm --filter @zcode/cli dev
# 构建 CLI 及其 workspace 依赖
pnpm --filter @zcode/cli... build
node apps/zcode-cli/packages/cli/dist/zcode.cjs --help这个入口直接运行 Agent CLI，不经过发行包的 --web 分流。开发 Web 用 pnpm dev:web；验证统一的 zcode 命令，用下方解压后的 bin/zcode.mjs。
根目录 .env.example 提供服务地址与构建配置示例，可按需复制到 .env，本地覆盖放入 .env.local。Desktop 的开发环境通过 dev:desktop:test / dev:desktop:prod 选择。
| 配置 | 用途 |
|---|---|
ZCODE_DATA_BASE_DIR |
应用数据基目录，数据写入其下的 .zcode/ |
ZCODE_SERVER_WORKSPACE |
Web 后端的工作区路径 |
ZCODE_BUILTIN_PROVIDER_CONFIG_FILE |
本地 Provider 配置文件路径；未设置时使用内置配置 |
ZCODE_DIST_BASE_URL |
命令行安装脚本使用的下载根地址 |
运行时变量可在启动命令的环境中显式设置。随客户端发布的默认配置见 config/README.md。
第三方声明生成、发行校验流程及声明在发行物中的位置见 third-party/README.md。
pnpm bundle:desktop
# 指定目标平台与 CPU 架构
pnpm bundle:desktop -- --os win --arch x64
pnpm bundle:desktop -- --help默认目标为 macOS arm64，默认输出目录为 packages/desktop/dist/。--os 支持 mac、win、linux，--arch 支持 x64、arm64；实际打包与签名需要目标平台对应的工具和配置。
安装：双击打开产物 DMG，将 ZCode 拖入"应用程序"。本地构建未签名，首次打开若被 macOS 拦截，执行：
sudo xattr -rd com.apple.quarantine /Applications/ZCode.app构建入口为 pnpm build:zcode。脚本会依次构建 CLI/TUI、后端和 Web，收集 TUI 的原生库、worker 与运行时依赖，再组装发行包；运行发行包仍需要 Node.js，版本以 mise.toml 为准。
打包前必须设置下载根地址 ZCODE_DIST_BASE_URL（可放在 .env、.env.local 或环境变量中），也可以通过 --base-url 传入。以下地址是占位示例，发布时替换为实际托管地址：
pnpm build:zcode --base-url https://downloads.example.com/zcode/
# 已配置 ZCODE_DIST_BASE_URL 时
pnpm build:zcode
# 仅重新组包，复用已有的 Agent、后端和 Web 构建产物
pnpm build:zcode --skip-build
# 查看版本、输出目录等可选参数
pnpm build:zcode --help默认版本取根目录 package.json，输出目录为 dist/zcode/：
releases/<version>/zcode-<version>.tar.gz：运行包。releases/<version>/sha256.txt：校验摘要。latest.json、install.sh：版本索引和安装脚本。
完整目录可上传到配置的下载根地址。安装脚本从该地址下载运行包，默认安装到 ~/.zcode/runtime，并在 ~/.local/bin 创建 zcode 命令。安装目录可通过 ZCODE_DIST_HOME 修改，命令目录可通过 ZCODE_DIST_BIN_DIR 修改。
旧 Lite 用户需要改用上述构建命令、环境变量和新的安装脚本。新安装不会删除旧 Lite 目录，也不会迁移或删除已有会话数据。
本地调试打包产物时，可直接解压运行，无需上传或安装：
zcode_version=$(node -p "require('./dist/zcode/latest.json').version")
mkdir -p dist/zcode/debug
tar -xzf "dist/zcode/releases/$zcode_version/zcode-$zcode_version.tar.gz" \
-C dist/zcode/debug
# 默认启动 TUI
node dist/zcode/debug/zcode/bin/zcode.mjs
# 启动 Web
node dist/zcode/debug/zcode/bin/zcode.mjs --web \
--workspace "$PWD" --port 3030 --no-open浏览器打开 http://127.0.0.1:3030，即可验证同一后端服务托管 Web 页面和 Agent 的完整链路。该端口需要空闲；如正在运行 pnpm dev:web，可改用其他 --port。
| 目录 | 职责 |
|---|---|
packages/desktop |
Electron Main、Host、Renderer 与桌面打包 |
packages/web |
Web 客户端 |
packages/server |
HTTP / WebSocket 服务与远程连接 |
packages/zcode-server-cli |
独立 Server 启动与进程管理 |
packages/ui |
共享 React 组件、hooks 与 Zustand 状态 |
packages/services |
业务服务与持久化 |
packages/shared、packages/rpc、packages/client |
共享协议和类型、RPC 框架、Agent 客户端 SDK |
packages/provider、packages/provider-node |
Provider 公共能力与 Node 实现 |
apps/zcode-cli |
Agent CLI、TUI、运行时与工具 |
scripts、config、third-party |
构建维护脚本、内置配置与第三方声明材料 |
功能与优惠范围、维护规则、执行与数据风险，以及许可和第三方版权说明，详见 NOTICE.md。