Agent Isles：可探索的岛屿世界 AI 编程学习项目

Qiuner/agent-isles

agent-isles 仍处于早期开发阶段。目前提供本地 Web MVP（Minimum Viable Product，最小可行产品）以及 Windows x64 启动器/打包预览版；macOS Intel 与 Apple Silicon 的便携版构建已实现，但尚未发布。安装与构建细节请参见桌面启动器指南。

Windows 便携预览版：把整个 ZIP 解压到一个较短的路径，然后运行 agent-isles.exe。首次使用时需要配置模型（model）。用户数据保存在 %LOCALAPPDATA%\agent-isles\data；可以通过系统托盘菜单停止服务。该预览版未签名，也没有自动更新功能。请先退出旧版本，再把更新包解压到一个新目录，不要直接覆盖正在使用的文件。

What is agent-isles?

agent-isles 是一个用于学习与创作的 AI 编程可探索环境。它把通常藏在聊天框、终端和工具列表背后的 Agent 能力，转化为一座岛屿世界中的伙伴、地点和行动。你可以从一个想法出发，借助 AI 把它做成一个真正可运行的项目，而无需先掌握模型（model）、会话（session）、工具调用（tool call）或仓库结构。

在完成首个项目的过程中，你可以选择引导式学习，来了解需求、项目、执行、审批与验证；或者选择自由创作，连接已有项目，按自己的节奏探索。学习不脱离实际工作，也不会被拆成一门独立课程：AI 可以行动，而你依然负责提出想法、亲身体验、做出判断并持续打磨结果。

这座可探索的世界让 AI 编程的初次接触不再那么令人畏惧，同时也不会掩盖它真实的能力与责任。任务状态会反映在世界和它的居民身上，而文件、对话历史与项目都有清晰的入口。当你需要更多细节时，高级工作台会展示完整的对话、工具调用以及人工审批流程。

Current experience

在 Windows 上，已安装的预览版会启动服务，并通过 agent-isles 快捷方式打开小岛，运行时和资源都已包含在内。源码构建仍然可以使用 打开小岛.cmd 来打开一个已经在运行的开发服务；该脚本并不是已安装应用的入口。（译注：脚本文件名直接使用了中文"打开小岛"，是项目自带的命名习惯。）

Main features

Workbench

Available now：连接真实的本地项目、与 AI 对话、检查文件和工具调用、处理审批，并继续使用已有的工作区（workspace）和会话（session）。

Education and guidance

Planned：把需求、项目选择、执行、审批与验证，转化为面向 AI 编程新手的渐进式学习路径。

More islands

Planned：扩展群岛，加入不同的地点、居民与主题，让不同项目能力拥有各自的性格与归宿。

Richer ways to play

Planned：通过更多互动和发现，把任务进度、居民关系、探索行为和最终成果串联起来，同时不牺牲真实的工作流。

Resident

| 居民 | 角色 | 当前能力 |
| --- | --- | --- |
| Q · 电脑制造师（Computer Maker） | 伙伴 | 通过完整对话接收目标，并利用附件、模型设置与权限来读取、修改和验证项目 |
| 老苔（Uncle Moss） | 项目与历史管理者 | 选择和切换项目，搜索历史记录，打开或继续已有的对话 |
| 艾伦（Alan）· 文件管理员（File Keeper） | 文件管理员 | 浏览真实目录，预览文本，展示 Git 中已暂存（staged）、未暂存（unstaged）与未跟踪（untracked）的变更 |跟随引导学习，或自由创作：教程会帮助你完成第一个项目，而普通项目则直接进入创作。

- 在项目内学习：讲解、练习与验证共享同一个真实的工作区。
- 居民是能力的入口：每位居民都有清晰的职责、对话与状态。
- 过程是可见的：角色、对话气泡与动画会反映 AI 的工作状态。
- 专业界面依然可用：高级工作台会展示完整的对话、工具结果与人工审批。
- 不重复造执行引擎：agent-isles 底层使用固定的 DeepSeek Harness 运行时。

Screenshots

当前的小岛与 Q：Q 可连接真实项目的原生对话与执行。老苔负责管理项目和对话历史，艾伦负责检查文件。Web 面板与窄屏截图将会重新拍摄；过时的图片已删除，以避免对当前界面造成误导。

Quick start

Requirements

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

Start the local Web app

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

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

打开终端中打印的本地 URL。首次使用时，按界面提示配置模型并选择一个本地项目目录，然后与某位居民对话。

开发数据默认保存在仓库内的 .agent-isles-home/。若想使用其他位置，需在启动前设置 DSH_HOME。

How it works

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

Godot 负责渲染世界与居民状态。React 提供工作区选择与居民交互面板。DeepSeek Harness 仍是对话与执行状态的唯一真实来源（single source of truth）。agent-isles 通过公开的 DSH/Cordis 插件接口（plugin interface）进行集成，既不修改上游源代码，也不会在外面再裹一层会话 API。

Repository layout

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

Development commands

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

Upstream and versioning

当前稳定渠道固定在 DeepSeek Harness 0.1.3-alpha.1，commit 为 d347e703908d0406b7a7ef80e3a0e594d86b2215。版本和运行时产物记录在 upstream.json 中。

- 不要直接修改 deepseek-harness/。
- 升级运行时前，请先更新固定版本，再运行兼容性验证。
- 将 agent-isles 的产品逻辑保留在其自身的插件和世界代码中。

Current limitations

- 文件管理员的只读行为目前是通过应用边界与提示（prompting）来强制执行的，并非完整的硬性权限边界。
- 文件管理员目前还不能编辑文件、预览图片、访问远程文件系统，也无法显示来自父仓库的变更。
- 完整的首节课程尚未在真实模型下完成端到端验证；真实任务、恢复路径与教学节奏仍需验证。
- 面板支持移动端布局，但世界中的控件仍主要面向键鼠设计。
- 通知仅存储在当前浏览器中，既不会跨浏览器同步，也不会使用操作系统的通知能力。
- 最新的 Windows 安装包尚未重新构建并验证安装、卸载与真实任务流程。预览构建未签名；自动更新和发布渠道尚未实现。

Documentation

- 桌面启动器与预览构建
- 贡献指南（Contributing guide）
- 支持
- 安全政策
- 行为准则
- 第三方声明
- 更新日志详细的架构与实现文档目前以中文维护在 docs/ 下。

Contributing

欢迎提交 bug 报告、功能建议和拉取请求（pull request）。在开始大型特性或交互重设计之前，请先开一个 Issue 以对齐范围。

请阅读贡献指南，了解开发要求、初始设置、测试与拉取请求的规范。该指南也会指向与 Web 插件、岛屿与居民、教程、桌面分发和文档变更相关的技术文档。