QCode 群岛 Qiuner/QCode

QCode

简体中文 · English

把 AI 编程从一本正经的聊天框里拿出来，放进一片可以探索的群岛。

和陪在你工作旁边的 AI 伙伴一起做真实项目，边创造边学编程。

官网 ·下载 ·演示视频 ·社区 ·简介 ·截图 ·快速开始 ·工作原理 ·文档 ·参与贡献 ·支持

▶ 观看演示视频

[!IMPORTANT]
QCode 还在早期开发阶段。目前提供本地 Web MVP 和 Windows x64 启动器/打包预览；macOS Intel / Apple Silicon 便携版已经实现，但尚未发布。安装与构建细节见桌面启动器指南。

Windows 便携预览版：下载 v0.1.0-preview.2。解压 ZIP，运行 QCode.exe。数据存放在 %LOCALAPPDATA%\QCode\data；首次启动时，只有新目录不存在，才会迁移旧数据目录。预览版未签名，也没有自动更新。上一个版本仍可下载。

QCode 是什么？

QCode 是一个可探索的环境，用来学习和创作 AI 编程。它把平时藏在聊天框、终端和工具列表背后的智能体能力，变成岛屿世界里的伙伴、地点和行动。你可以从一个想法开始，和 AI 一起把它变成真正能跑起来的项目，不需要先掌握模型、会话、工具调用或仓库结构。

选择引导式学习，在完成第一个项目的过程中认识需求、项目、执行、审批和验证。或者选择自由创作，接入已有项目，按自己的节奏探索。学习附着在真实工作上，而不是单独拆成一门课程：AI 可以行动，但提出想法、体验过程、判断结果、打磨成品的仍然是你。

可探索的世界让第一次接触 AI 编程没那么吓人，同时又不隐藏它真实的能力与责任。任务状态会体现在世界和居民身上，文件、对话历史和项目都有清晰的入口。需要更多细节时，高级工作台会展示完整对话、工具调用和人工审批。

当前体验

在 Windows 上，安装好的预览版会从 QCode 快捷方式启动服务并打开小岛，运行时和资源都已包含在内。源码构建仍可用 打开小岛.cmd 打开已在运行的开发服务；这个脚本不是安装版应用的入口。

主要功能

工作台 Available now 接入真实的本地项目，与 AI 对话，查看文件和工具调用，处理审批，继续已有的工作区和会话。

教育与引导 Planned 把需求、项目选择、执行、审批和验证变成一条循序渐进的学习路径，面向刚接触 AI 编程的人。

更多小岛 Planned 扩展群岛，加入各具特色的地点、居民和主题，让不同的项目能力拥有自己的性格和归属。

更丰富的玩法 Planned 把任务进度、居民关系、探索和已完成的工作串联起来，加入更多互动和发现，同时不影响真实工作流。

| 居民 | 角色 | 当前能力 |
| Q · Computer | 创客伙伴 | 通过完整对话接收目标，并借助附件、模型设置和权限来读取、修改和验证项目 |
| Uncle Moss | 项目与历史管家 | 选择并切换项目，搜索历史，打开或恢复已有对话 |
| Alan · File Keeper | 文件管家 | 浏览真实目录，预览文本，展示已暂存、未暂存和未跟踪的 Git 变更 |

- 跟着引导学习，或自由创作： 教程帮你完成第一个项目，普通项目则直接进入创作。
- 在项目里学习： 讲解、练习和验证共用同一个真实工作区。
- 居民就是能力入口： 每位居民都有清晰的职责、对话和状态。
- 过程可见： 角色、对话气泡和动画会反映 AI 的工作状态。
- 专业界面依然可用： 高级工作台展示完整对话、工具结果和人工审批。
- 不重复造执行引擎： QCode 底层使用固定版本的 DeepSeek Harness 运行时。

截图

当前岛屿与 Q

Q 和它的两条机械臂在中央平台上

Q 连接原生对话，并为真实项目执行任务。Uncle Moss 管理项目和对话历史，Alan 检查文件。Web 面板和窄屏截图将重新采集；过时的图片已移除，以免误导当前界面。

快速开始

环境要求

- 源码开发需要 Windows 或 macOS Intel / Apple Silicon；便携预览见桌面启动器指南
- Node.js ^22.19.0 或 >=24.0.0
- Corepack
- 支持子模块的 Git
- 导出世界时需要 Godot 4.7.2 及其 Web 导出模板，或配置好 GODOT_BIN

启动本地 Web 应用

在仓库根目录运行以下命令：

corepack enable
corepack yarn install --immutable
corepack yarn dev:web --no-open

打开终端里打印的本地 URL。首次使用时，按界面提示配置模型并选择本地项目目录，然后就可以和居民对话了。
开发数据默认存放在仓库内的 .qcode-home/。如果 .qcode-home/ 还不存在，而 .agent-isles-home/ 已经存在，就会迁移过来。想换个位置，在启动前设置 DSH_HOME。

社区与反馈

在 QCode QQ 社区分享你的作品、交流技巧、寻求帮助（以中文为主）。

QQ 群：543293474 —— 用 QQ 扫码，或复制群号搜索加群。

报告 bug、提功能需求，请走 GitHub Issues，方便跟踪进度。

工作原理

Creator / learner
-> QCode Web: island world, residents, conversations, and state
-> QCode Host/Client plugins: Workspace and Resident/Session mapping
-> DeepSeek Harness: models, tools, approvals, files, and terminals
-> Local project

Godot 负责渲染世界和居民状态。React 提供工作区选择和居民交互面板。会话与执行状态始终以 DeepSeek Harness 为唯一事实来源。QCode 通过公开的 DSH/Cordis 插件接口集成，不改上游源码，也不在它外面再包一层 Session API。

仓库结构

| 目录 | 用途 |
| apps/web/ | 启动 QCode DSH Web 配置档 |
| apps/desktop/ | Windows 和 macOS Intel / Apple Silicon 启动器、打包与校验脚本 |
| packages/qcode-web/ | QCode Host/Client Web 插件 |
| games/mosslight/ | 用 Blender 和 Godot 构建的世界 |
| deepseek-harness/ | 锁定版本的上游 Git 子模块 |
| vendor/dsh-runtime/ | 锁定并校验过的 DSH 运行时包 |
| docs/ | 产品、架构与实现文档 |

开发命令

| 命令 | 用途 |
| corepack yarn dev:web --no-open | 构建插件并启动本地 Web 应用 |
| corepack yarn typecheck | 对 Web 插件做类型检查 |
| corepack yarn build:web | 构建 Web 插件 |
| corepack yarn build:world | 导出 Godot Web 世界 |
| corepack yarn check:upstream | 校验锁定版本的上游子模块 |
| corepack yarn check:vendored-runtime | 校验 vendored 运行时 |

上游与版本管理

当前稳定通道锁定 DeepSeek Harness 0.1.3-alpha.1，对应提交 d347e703908d0406b7a7ef80e3a0e594d86b2215。版本与运行时产物记录在 upstream.json。

- 不要直接改 deepseek-harness/。
- 升级运行时之前，先更新锁定版本，再跑兼容性校验。
- QCode 的产品逻辑放在自己的插件和世界代码里。

当前限制

- File Keeper 的只读行为目前靠应用层边界和提示词约束，还不是完整的硬权限边界。
- File Keeper 目前还不能编辑文件、预览图片、访问远程文件系统，也不能显示父仓库的变更。
- 完整的第一课还没用真实模型跑通端到端验证；真实任务、恢复路径和教学节奏仍待验证。
- 面板支持移动端布局，但世界控制仍主要面向键盘和鼠标设计。
- 通知存在当前浏览器里，不会跨浏览器同步，也不使用操作系统通知。
- 最新的 Windows 安装包还没重新构建，也没验证过安装、卸载和真实任务。预览版未签名；自动更新和发布通道尚未实现。

文档

- 桌面启动器和预览版
- 贡献指南
- 支持
- 商业许可
- 安全策略
- 行为准则
- 第三方声明
- 更新日志

详细的架构与实现文档目前以中文维护，放在 docs/ 下。

贡献

欢迎提交 bug 报告、功能提案和 pull request。开始大型功能或交互改版之前，请先开 Issue 对齐范围。

开发要求、初始设置、测试和 pull request 规范见贡献指南。指南里也列出了 Web 插件、岛屿与居民、教程、桌面分发和文档修改相关的技术文档。

路线图

- 用真实模型完成端到端验证，跑通完整的第一课和主要失败路径。
- 为不同居民建立可强制执行的权限边界。
- 完善 Windows 构建的签名、自动更新和分发。
- 扩充课程、项目模板，以及和任务进度联动的世界反馈。