Qiuner/agent-isles · 上手攻略

  • 仓库：Qiuner/agent-isles
  • 链接：https://github.com/Qiuner/agent-isles
  • 分类：AI Coding 工具 · 智能体开发平台
  • 作者：Tom
  • 更新：2026-09-18

这是什么

agent-isles 是一个可探索的岛屿世界，把 AI 编程能力从枯燥的聊天框和终端里拎出来，变成一个你可以用鼠标探索的群岛界面。它由 DeepSeek Harness 驱动内核，外部套了一层 Godot 4 构建的 GUI 岛屿，让你"看见"AI 在工作——居民（NPG）对应不同能力入口，项目进度反映在世界状态上，而高级工作台保留了完整的会话、工具调用和人工审批界面。

本质上它是 DeepSeek Harness 的可视化前端，配有三个角色： - Q（计算机向导）：接收目标、用完整对话和附件工作，读写修改项目文件 - Uncle Moss（项目管理员）：切换项目、搜索历史、恢复会话 - Alan（文件管理员）：浏览真实目录、预览文本、显示 Git 变更

解决什么问题

大多数 AI Coding 工具（Cursor、Copilot、Claude Code 等）都是对话界面——你在 prompt 里看不见 AI 内部在想什么、正在改哪个文件、卡在哪一步。agent-isles 把这些状态具象化为岛屿和居民：当你对 Q 说"帮我写一个 TODO 应用"，小岛上的角色会有对话气泡、动作动画，Alan 的状态反映 Git 有哪些变更。

对于 AI 编程新手，它还提供引导学习路径（guided learning），把需求分析→项目选择→执行→审批→验证拆成循序渐进的教学关卡，而不是把新手直接丢进 terminal。

快速安装

⚠️ 当前（2026-09-18）仍为早期预览阶段，Windows 便携版可下载，macOS 源码可构建但成品未发布。

方式一：Windows 便携预览（推荐尝鲜）

  1. 下载 v0.1.0-preview.1 便携 ZIP
  2. 解压到短路径（如 C:\agent-isles），避免空格和中文
  3. 运行 agent-isles.exe
  4. 首次启动需配置模型（设置 DeepSeek Harness 接入的 API key 和模型）
  5. 数据目录：%LOCALAPPDATA%\agent-isles\data
  6. 退出：从系统托盘菜单选 Exit（关浏览器不会停止服务）

方式二：源码构建（需要全部依赖）

前置要求： - Node.js ^22.19.0 或 >= 24.0.0 - Corepack（corepack enable） - Git（含 submodule 支持） - Godot 4（官方下载，版本不低于 4.3） - Windows 用 .NET Framework C# 编译器 + Inno Setup 6（构建安装包时）

git clone https://github.com/Qiuner/agent-isles.git
cd agent-isles
corepack yarn install

# 构建 Web 前端
corepack yarn build:web

# 构建 Godot 世界资源
corepack yarn build:world

# 构建桌面包
node apps/desktop/build.mjs

# 验证构建产物
powershell -NoProfile -File apps/desktop/verify.ps1 \
  -BuildDirectory (Get-Content dist/desktop-latest.txt)

macOS 源码构建（需要目标机器原生日志，不可用 Rosetta）：

# 安装 Godot 4.7.2 及 Web 导出模板
# 配置 GODOT_BIN 环境变量指向 Godot 执行文件

corepack yarn build:web
corepack yarn build:world
corepack yarn build:desktop:darwin
corepack yarn verify:desktop:darwin

核心用法

界面操作流程

  1. 启动岛屿：运行 agent-isles.exe（Windows）或在源码目录运行 打开小岛.cmd（已运行开发服务时）
  2. 选择模式：启动后选择 Guided Learning（引导学习）或 Free Creation（自由创建）
  3. 与 Q 对话：在岛屿中点击 Q，输入你的项目需求
  4. 用 Alan 查看文件：Alan 会展示当前目录和 Git 状态变更
  5. 用 Uncle Moss 切换项目：管理多个工作区

关键概念

概念 说明
岛屿世界 AI 工作状态的 GUI 映射，状态变化→岛屿/居民状态变化
Q 向导 主要 AI 对话入口，通过完整对话收发目标和结果
DeepSeek Harness 底层执行引擎，agent-isles 不重复造轮子
引导学习 把 AI 编程过程拆成可探索的教学关卡
高级工作台 等价于原始 Harness 界面，完整对话+工具调用+人工审批

典型适用场景

  • AI 编程入门：不想被 terminal 吓退的新手，通过岛屿探索直观理解 AI 编程过程
  • 项目过程可视化：想"看见"AI 在改哪个文件、为什么卡住的场景
  • 教学演示：导师用岛屿界面给学生演示 AI 如何处理需求→代码→验证的完整链路
  • 多项目并行管理：Uncle Moss 管理多个工作区和会话，适合同时维护多个 side project 的开发者

坑与注意

⚠️ 以下为已知限制，2026-09-18 确认：

  1. macOS 便携包未发布：源码构建说明存在，但官方 macOS 预览版 zip 尚未释出，macOS 用户只能从源码构建
  2. Windows 预览版无自动更新：v0.1.0-preview.1 是当前最新版，手动替换文件升级；卸载旧版后再装新版
  3. Unsigned 代码：Windows 和 macOS 预览均为未签名软件，Windows 需绕过 SmartScreen，macOS 需在系统设置中手动允许
  4. 需要自配模型：不自带任何模型，DeepSeek API key 需要自行准备，且需兼容 DeepSeek Harness 格式
  5. Godot 依赖：完整功能需要 Godot 4（桌面构建），仅运行 Web 前端不需要 Godot
  6. 预览版功能有限：README 明确说明 Web 面板和窄屏截图尚未重新采集，界面可能与文档图片不一致
  7. 数据目录：用户数据在 %LOCALAPPDATA%\agent-isles\data，不要直接删此目录

与同类对比

工具 形态 内核 可视化 目标用户
agent-isles 3D 岛屿 GUI DeepSeek Harness 岛屿+角色+动画 AI 编程新手/可视化爱好者
Claude Code 终端 TUI Claude 无 开发者（效率优先）
Cursor IDE 插件 GPT-4o/Claude 代码 Diff 日常编码开发者
GitHub Copilot IDE 插件 GPT-4/Claude 建议高亮 日常编码开发者
DeepSeek Cody Chat UI DeepSeek 无 中文开发者
DSW (Dify) Web GUI 多模型 DAG 工作流 低代码/AI 应用构建

核心差异：agent-isles 的独特价值在于把 AI 编程过程从黑箱变成可探索的 GUI 世界，这与所有纯对话/终端类产品路线都不同。代价是依赖 Godot 生态，重量级预览版仅 Windows 有，macOS/Linux 用户需从源码构建。

一句话结论

想用可视化方式学习 AI 编程、或想"看见"DeepSeek Harness 工作状态的开发者，agent-isles 是目前唯一的岛屿探索形态入口——但需接受早期预览的局限性（Windows 为主、模型自配、无自动更新）。