简体中文 | English
KayingCode 以 ZCode harness 为载体,全面接入游戏开发场景,打造面向多游戏引擎、多平台的游戏开发 harness。 它将 Agent、引擎工具、运行预览与测试验证连接起来,支持从玩法目标、实现到结果验证的持续迭代。
我们尽可能保留 ZCode 的通用编程能力、交互和运行逻辑,将核心改造集中在游戏开发工作流、引擎接入与多平台验证。多引擎、多平台是持续扩展方向;当前能力与已验收范围见各应用文档。项目基于 官方 ZCode,上游 ZCode 部分遵循 Apache-2.0;KayingCode 项目整体以 AGPL-3.0 发布,为非官方衍生项目。
最新版本:0.2.1(全部版本与校验值)
| 平台 | 下载 |
|---|---|
| Windows x64 | 安装包 |
| macOS Apple Silicon | DMG |
| Linux x64 | AppImage · deb · rpm · pacman |
| Linux arm64 | AppImage · deb · rpm · pacman |
| Android | APK |
macOS Intel(x64)安装包自 0.1.5 起暂停构建;0.1.4 及更早版本仍可在 Releases 中获取。Windows 当前使用自签证书,安装时可能提示“未知发布者”。各平台系统要求与安装说明见对应应用文档。
ZCode、WorkBuddy 等通用 Agent harness 已能很好地完成编码与文档任务,但自带的右侧面板主要承担结果展示,对外开放的能力有限。游戏开发需要的是在 harness 内部完成深度融合:Agent 直接操作内置浏览器里的游戏与平台页面、生成并处理素材、把项目发布到游戏平台,再依据真实截图把画面一轮轮修正到位。这些闭环很难靠一个展示型面板或若干外部链接拼接起来。
KayingCode 把这些能力做进工作台本身:内置浏览器与游戏预览共处同一界面,平台项目、构建与发布由工具直接调用,素材生成随插件提供,双预览与像素差异构成有预算、可停止的视觉修正循环。通用编程能力照常保留,游戏开发的关键步骤也不再把用户带出 harness。
开箱即用,把时间留给创意。 版本内置游戏开发常用插件并随发行版本完成联调:TapTap Maker 游戏开发、Browser Use 浏览器操作、Blender 建模与素材、游戏试玩助理等,安装后即可直接使用。初学者不必先花时间查找插件、安装依赖、配置 MCP 和调试环境,描述自己的想法就能开始第一个项目;需要更多能力时再按需扩展。
游戏开发插件专区
首期以 TapTap 平台为一站式主线。 用 TapTap 账号扫码登录后,项目创建、玩法开发、预览调试到构建发布可在同一个工作台连续完成(平台侧的登录、授权与发布确认仍由用户完成)。工具链、预览与平台账号预先打通,不必在编辑器、浏览器和平台后台之间反复切换,上手成本平缓。
游戏中心 · 我的 TapMaker 游戏
完整工作流由以下环节组成:
- 项目与引擎工具:游戏中心连接项目列表、本地工作区与开发参考;当前内置 TapTap Maker 插件提供项目、诊断、构建及发布工具。
- 实现与运行预览:Agent 在现有 harness 中执行开发任务,本地 Desktop 提供游戏预览、界面截图和功能验证入口。
- 视觉对照与迭代:双预览与像素差异用于对照结果;视觉修复有预算与停止条件,完成情况以真实运行、玩法和视觉验收为准。
- 原型与转写:可用 three.js 网页 Demo 验证原型,再按模块适配到 TapTap Maker,并通过实际预览核对玩法与视觉结果。
- 引擎扩展与平台接入:通过插件、MCP、Skills 和现有接口接入引擎及工具,保留通用编程能力;具体支持范围以当前插件和应用文档为准。
模型与 Provider 配置
按使用场景选择入口,全程无需注册 KayingCode 账号:
- 桌面下载即用:日常在 PC 上开发的用户,直接下载安装 Desktop 即可获得完整工作台,Agent、游戏预览、界面截图与功能验证都在本机运行;也可使用 CLI。
- 手机按需接入:需要移动连接的用户,可通过 Flutter 客户端、H5 与微信小程序 连接桌面已有的 Host 与会话。在桌面左下角打开远控入口并扫码,浏览器或手机即可接入,任务仍留在桌面执行。
- 远控可选自托管,免费且简单:跨网络远控时,可以部署自己的 Relay 服务,Cloudflare 免费层级即可承载;将 Web 与 Relay 部署到同一 HTTPS 地址,按 Relay 部署教程 连接 Desktop。只在本机开发则无需任何部署。
设备身份和浏览器凭据由客户端自动管理,用户无需注册、设置密码或填写 token;授权到期、注销或清除浏览器存储后重新扫码即可。各移动渠道的接入方式及已验收平台见应用文档。Desktop 面向 Windows、macOS、Linux,支持 SSH/WSL/Docker 开发环境。
| 入口 | 用途 | 开发命令 |
|---|---|---|
| Desktop | 本地游戏开发、预览和调试工作台 | pnpm run dev:desktop |
| Web / KayingCode 命令行版 | 浏览器与终端入口,组装 Web、TUI、后端和 Agent | pnpm run dev:web |
| Agent CLI | 终端中的 kayingcode,也为 Desktop/Web 提供运行时 | pnpm --filter @zcode/cli run dev |
本项目按首次发布形态提供说明;安装包与平台支持以实际构建和验收为准。本地模式使用自配 Provider、内置或本地插件;模型调用会向配置端点发送所需上下文,TapTap 等平台工具有各自的登录、授权及发布确认。远控扫码授权是设备连接机制,不是订阅或额度账号。数据与网络行为见 NOTICE.md。
使用微信扫描下方二维码,联系项目团队或加入交流群。也可以发邮件到 service@kayingai.com。
| 分支 | 用途 |
|---|---|
main |
KayingCode 的 GitHub 默认分支。功能、修复和版本准备经 PR 与 CI 合入。 |
zcode-main |
官方 ZCode main 的只读镜像,维护者从上游快进同步。 |
| 短期主题分支 | 从产品 main 创建,例如 project-drag 或 fix/session-reconnect,合入后清理。 |
开发环境、提交信息格式、PR 流程与发布步骤见 README-DEV.md。
首次克隆从 GitHub 取产品源码,默认检出 main。
git clone https://github.com/kaying-ai/KayingCode.git
cd KayingCode在已有 GitHub clone 中,从最新的产品主线开始一项改动。
git switch main
git pull --ff-only origin main
git switch -c fix/session-reconnect
node scripts/check-workspace-freshness.mjs向 GitHub 的 main 提交 PR。维护者从短期 release/<版本> 分支提交版本准备 PR,再为通过发布验收的 main 提交创建 kaying-code-v<版本> 标签。
维护者的 origin 指 GitHub,upstream 指官方 ZCode。旧 Gitee 开发库作为历史档案,可在本地命名为 legacy。新建 Gitee 备份库后,将它配置为 gitee,从 GitHub 单向同步产品主线和正式标签。 工作区迁移、镜像与发布指南
在 GitHub 的 zcode-main 查看 ZCode 原始源码和文档。 ZCode 原始文档
需要比较官方变更时,首次添加 upstream 后获取官方 main。已有该远端的 clone 可直接 fetch。
git remote add --no-tags -t main upstream https://github.com/zai-org/ZCode.git
git fetch --no-tags upstream维护者按指南将 upstream/main 快进同步至 GitHub 的 zcode-main。采纳某项上游改动时,从同步后的产品 main 新建短期适配分支,比较已验收基线与官方提交。 同步 zcode-main
git fetch --no-tags upstream
git switch main
git pull --ff-only origin main
git switch -c adopt-zcode-3-17-2
node scripts/check-workspace-freshness.mjs
upstream_base=$(node -p "require('./UPSTREAM_BASE.json').commit")
git log --oneline "$upstream_base"..upstream/main
git diff --stat "$upstream_base" upstream/main按模块更新 spec、适配实现和测试,记录采纳项、保留的差异和未完成项,验证后向产品 main 提交 PR。目标差异全部审阅并验收后,再更新 UPSTREAM_BASE.json。KayingCode 自身版本独立管理。
准备 Git、Node.js 24.14.0 和 pnpm 10.31.0,版本以 mise.toml 为准。以下开发和打包命令均在仓库根目录执行。
pnpm run bootstrappnpm run bootstrap 安装 workspace 依赖、准备桌面本地运行资源,再执行 build:bootstrap。
Agent CLI 与运行时源码位于 apps/zcode-cli/packages/cli/,作为普通目录随本仓库一起克隆,无需单独拉取或初始化 Git submodule。
根据需要选择其他初始化或构建入口:
| 命令 | 用途 |
|---|---|
pnpm install |
安装依赖 |
pnpm run prepare:desktop-runtime |
准备桌面运行资源,默认包含远程资源准备 |
pnpm run prepare:remote-assets |
单独准备远程运行资源 |
pnpm run bootstrap:with-remote |
初始化依赖、本地与远程资源,并串行构建相关包;跳过桌面应用 bundle |
pnpm run build |
经 turbo 拓扑执行各 workspace 包的构建脚本,包括包内的资源准备步骤 |
默认 bootstrap 跳过远程资源准备,适合本地桌面开发。使用远程工作区或验证远程发行资源时,再运行对应准备命令。
pnpm run dev:desktop
# 使用测试环境
pnpm run dev:desktop:testpnpm run dev:desktop 默认等同于 pnpm run dev:desktop:prod,使用生产服务配置。启动脚本会准备本地运行资源、构建桌面 Agent,再启动 Electron 和源码监听。Agent 构建带源码指纹缓存:相关输入未变且产物齐全时跳过全量重建(日常无改动启动可省约 20s)。
需要独立开发数据目录时,可设置 KAYINGCODE_DATA_BASE_DIR。例如在 macOS / Linux 中:
KAYINGCODE_DATA_BASE_DIR="$HOME/.kayingcode-dev-home" pnpm run dev:desktop:test先执行 pnpm run bootstrap:with-remote 准备远程资源(mock-cdn),再 pnpm run dev:desktop;连接远程项目时资源选择「本地下载后上传」。开发态资源取自本地 packages/desktop/mock-cdn 和本地构建产物,经 SFTP 上传到远程,不访问 CDN。
只开发 Web 或后端时,可从干净克隆安装依赖、生成工作区类型产物,再启动开发服务。Windows 建议使用较短的克隆路径,例如 D:\src\KayingCode。
pnpm install --frozen-lockfile --child-concurrency=1
pnpm run typecheck
pnpm run dev:web
# 指定后端工作区(macOS / Linux)
KAYINGCODE_SERVER_WORKSPACE=/path/to/project pnpm run dev:web该命令同时启动 Web 开发服务器(默认 http://localhost:5173)和后端(默认 http://localhost:3030);浏览器访问前者。/ws 和一般 /api 请求代理到本地后端,/api/v1/oauth/token 单独代理到当前配置的产品服务。
Agent 源码修改后,执行 pnpm exec turbo run build --filter=@zcode/cli... 并重启服务。需要验证完整发行包时,按下方“KayingCode 命令行版”打包章节解压运行。
命令行发行包包含 TUI、Web 和 Agent,统一使用 kayingcode 启动:无参数进入 TUI;第一个参数为 --web 时启动 Web;其他参数交给现有 Agent CLI 处理。两种模式都在本机运行,无需 Electron。
# 默认进入终端交互界面
kayingcode
# 启动 Web 界面
kayingcode --web
# 指定项目和端口,不自动打开浏览器
kayingcode --web --workspace /path/to/project --port 3030 --no-open
# 查看 CLI 或 Web 参数
kayingcode --help
kayingcode --web --helpWeb 模式默认工作目录为当前目录,监听 127.0.0.1,默认不启用访问令牌,自动选择空闲端口并打开浏览器。访问终端输出的地址,按 Ctrl+C 停止服务。局域网访问可使用 --host 0.0.0.0;监听非本机地址时默认生成访问令牌,使用终端输出的带令牌链接。可通过 --token 指定令牌或 --no-token 关闭令牌认证。
直接启动通用 Web 服务的 HTTP 入口时,通过 KAYINGCODE_SERVER_AUTH_TOKEN 配置 API/WebSocket 认证;通过程序接口创建服务时,使用 authToken 选项。
构建方式见下方打包章节。pnpm run build:kayingcode 只生成发行包,不会替换 PATH 中已有的 kayingcode。如果命令仍指向旧安装或其他源码目录,macOS / Linux 可用 command -v kayingcode 检查,Windows 可用 where.exe kayingcode 检查。
直接开发 TUI 或 Agent 时,运行源码入口:
pnpm --filter @zcode/cli run dev --help
pnpm --filter @zcode/cli run dev
# 构建 CLI 及其 workspace 依赖
pnpm exec turbo run build --filter=@zcode/cli...
node apps/zcode-cli/packages/cli/dist/kayingcode.cjs --help这个入口直接运行 Agent CLI,不经过发行包的 --web 分流。开发 Web 用 pnpm run dev:web;验证统一的 kayingcode 命令,用下方解压后的 bin/kayingcode.mjs。
根目录 .env.example 提供服务地址与构建配置示例,可按需复制到 .env,本地覆盖放入 .env.local。Desktop 的开发环境通过 dev:desktop:test / dev:desktop:prod 选择。
| 配置 | 用途 |
|---|---|
KAYINGCODE_DATA_BASE_DIR |
应用数据基目录,数据写入其下的 .kayingcode/ |
KAYINGCODE_SERVER_WORKSPACE |
Web 后端的工作区路径 |
KAYINGCODE_BUILTIN_PROVIDER_CONFIG_FILE |
本地 Provider 配置文件路径;未设置时使用内置配置 |
KAYINGCODE_DIST_BASE_URL |
命令行安装脚本使用的下载根地址 |
运行时变量可在启动命令的环境中显式设置。随客户端发布的默认配置见 config/README.md。
第三方声明生成、发行校验流程及声明在发行物中的位置见 third-party/README.md。
# 自动识别当前系统并构建对应的安装包
pnpm run package
# 等价于 bundle:desktop 不带参数;也可显式指定目标平台与 CPU 架构
pnpm run bundle:desktop -- --os win --arch x64
pnpm run bundle:desktop -- --help未显式指定 --os/--arch 时,默认构建当前系统与当前架构对应的安装包,默认输出目录为 packages/desktop/dist/。打包默认产出正式版本(KayingCode-<version>-<platform>-<arch>.exe,连接生产后端);需要测试后端的 Preview 包时显式 KAYINGCODE_ENV=test pnpm run package。--os 支持 mac、win、linux,--arch 支持 x64、arm64;实际打包与签名需要目标平台对应的工具和配置。
安装:双击打开产物 DMG,将 KayingCode 拖入"应用程序"。本地构建未签名,首次打开若被 macOS 拦截,执行:
sudo xattr -rd com.apple.quarantine /Applications/KayingCode.app构建入口为 pnpm run build:kayingcode。脚本会依次构建 CLI/TUI、后端和 Web,收集 TUI 的原生库、worker 与运行时依赖,再组装发行包;运行发行包仍需要 Node.js,版本以 mise.toml 为准。
打包前必须设置下载根地址 KAYINGCODE_DIST_BASE_URL(可放在 .env、.env.local 或环境变量中),也可以通过 --base-url 传入。以下地址是占位示例,发布时替换为实际托管地址:
pnpm run build:kayingcode --base-url https://downloads.example.com/kayingcode/
# 已配置 KAYINGCODE_DIST_BASE_URL 时
pnpm run build:kayingcode
# 仅重新组包,复用已有的 Agent、后端和 Web 构建产物
pnpm run build:kayingcode --skip-build
# 查看版本、输出目录等可选参数
pnpm run build:kayingcode --help默认版本取根目录 package.json,输出目录为 dist/kayingcode/:
releases/<version>/kayingcode-<version>.tar.gz:运行包。releases/<version>/sha256.txt:校验摘要。latest.json、install.sh:版本索引和安装脚本。
完整目录可上传到配置的下载根地址。安装脚本从该地址下载运行包,默认安装到 ~/.kayingcode/runtime,并在 ~/.local/bin 创建 kayingcode 命令。安装目录可通过 KAYINGCODE_DIST_HOME 修改,命令目录可通过 KAYINGCODE_DIST_BIN_DIR 修改。
本地调试打包产物时,可直接解压运行,无需上传或安装:
kayingcode_version=$(node -p "require('./dist/kayingcode/latest.json').version")
mkdir -p dist/kayingcode/debug
tar -xzf "dist/kayingcode/releases/$kayingcode_version/kayingcode-$kayingcode_version.tar.gz" \
-C dist/kayingcode/debug
# 默认启动 TUI
node dist/kayingcode/debug/kayingcode/bin/kayingcode.mjs
# 启动 Web
node dist/kayingcode/debug/kayingcode/bin/kayingcode.mjs --web \
--workspace "$PWD" --port 3030 --no-open浏览器打开 http://127.0.0.1:3030,即可验证同一后端服务托管 Web 页面和 Agent 的完整链路。该端口需要空闲;如正在运行 pnpm run dev:web,可改用其他 --port。
| 目录 | 当前包名或工程入口 | 职责 |
|---|---|---|
packages/desktop |
@zcode/desktop |
Electron Main、窗口级 Local Host、Renderer 与桌面打包 |
packages/web |
@zcode/web |
浏览器工作台与 Relay Web 界面 |
apps/kayingcode-site |
kayingcode-product-site |
独立静态产品站与本地预览 |
apps/zcode-cli/packages/cli |
@zcode/cli |
Agent CLI/TUI 入口与 SEA 发行 |
packages/zcode-server-cli |
@zcode/server-cli |
上游常驻服务、远程 staging 与代理;保留 SSH/WSL/Docker 开发容器 |
apps/kayingcode-relay-cloudflare |
@kayingcode/relay-cloudflare |
Relay、设备授权与同源 Web 工作台 |
apps/kayingcode-mobile-taro |
@kayingcode/mobile |
Taro 微信小程序与 H5 客户端 |
apps/kayingcode-mobile-flutter |
pubspec.yaml |
Flutter Android/iOS 客户端;使用 Dart 工具链,不属于 pnpm 工作区 |
| 目录 | 职责 |
|---|---|
apps/zcode-cli/packages/adapters |
Agent 文件、网络、模型、插件等 I/O 适配 |
apps/zcode-cli/packages/bootstrap |
Agent 服务与协议装配 |
apps/zcode-cli/packages/shared-types |
Agent CLI 共享类型 |
apps/zcode-cli/packages/contracts |
Agent 端口、事件与工具契约 |
packages/agent-gateway |
Web Host 和 Agent Node 共用的 HTTP/WS RPC ingress |
apps/zcode-cli/packages/i18n |
Agent 国际化资源 |
apps/zcode-cli/packages/core |
Agent 命令、会话与工具运行时 |
apps/zcode-cli/packages/telemetry |
Agent 遥测事件与处理能力 |
packages/client |
Agent 客户端 SDK 与连接适配 |
apps/zcode-cli/packages/dynamic-workflow |
动态工作流引擎核心 |
apps/zcode-cli/packages/dynamic-workflow-runtime |
动态工作流脚本的沙箱执行与宿主桥接 |
packages/mobile-client-core |
手机、H5、小程序共用的配对、连接与投影逻辑 |
packages/model-option-map |
模型选项映射的解析与求值 |
apps/zcode-cli/packages/node-repl-host |
JavaScript 执行与 Browser Use 宿主 |
packages/provider |
Provider 公共能力 |
packages/provider-node |
Provider 的 Node 实现 |
packages/rpc |
跨进程 RPC 框架 |
packages/server |
Web Host 的 HTTP、WebSocket 与远程连接服务 |
packages/services |
业务服务与持久化 |
packages/shared |
多端共享协议、平台接口与类型 |
apps/zcode-cli/packages/swift-bridge |
Swift 互操作占位包 |
apps/zcode-cli/packages/tui |
Agent 终端 UI |
packages/ui |
共享 React 组件、hooks 与 Zustand 状态 |
| 目录 | 职责 |
|---|---|
plugins/ |
可启停的内置插件与随包资产;Computer Use 运行实现位于此处 |
tools/ |
开发、调试、研究与验证工具 |
scripts/、config/、third-party/ |
构建维护脚本、发行配置与第三方声明材料 |
新增文件的落点见 仓库工作规则 和 应用目录说明,完整包信息见 生成包地图。包或插件变更后运行 pnpm run source:plugins、pnpm run source:map 和 pnpm run source:check。
KayingCode 社区版采用 GNU Affero General Public License v3.0(SPDX:AGPL-3.0-only)发布。你可以在遵守 AGPL-3.0 全部条款的前提下使用、修改和分发本项目,包括商业用途。
AGPL-3.0 要求:当你修改本项目并通过网络向用户提供服务时,需要向这些用户提供对应的完整源码。若你需要不受 AGPL-3.0 约束的商业授权,请联系 service@kayingai.com。
本项目基于 ZCode(Apache-2.0);上游代码与声明继续适用 Apache-2.0,各内置插件和第三方组件保留其各自声明的许可。隐私与数据处理说明见 PRIVACY.md。
功能与优惠范围、维护规则、执行与数据风险,以及许可和第三方版权说明,详见 NOTICE.md;隐私与数据处理见 PRIVACY.md。



