emperor-agent

Emperor Agent 是一款面向个人长期使用的桌面 Agent。你可以用它处理日常问答，也可以绑定本地项目，让 Agent 在明确的权限和验收条件下读取文件、运行工具并持续推进任务。

桌面端直接托管 TypeScript Core，界面通过 Electron IPC 与核心能力通信。已经退役的 Python CLI、HTTP server 和 WebSocket server 不再参与运行。

导航

• 认识 Emperor Agent
• 下载与首次使用
• Chat、Build、Plan 与 Goal
• 功能与成熟度
• 数据、权限与安全
• 当前边界
• 从源码运行
• 文档导航

认识 Emperor Agent

Emperor Agent 里有几组名称看起来相似，实际处在不同层级：

应用会把会话、记忆、配置、附件和运行轨迹保存在本机。Chat（普通对话）适合问答和轻量任务；Build（项目工作）会绑定本地目录，并读取项目的 AGENTS.md 和工作区上下文。

Plan（规划模式）用于先探索、再提交方案。Goal（目标模式）则负责持续完成一个结果：它会锁定范围和验收条件，执行过程中可以重新规划，但只有证据和 Completion Gate 都通过后才能标记为完成。

Plan 和 Goal 是互斥的顶层模式，Composer 同一时间只显示一个标识。Goal 内部可以使用 Plan 引擎规划和审批，但这只是 Goal 的“规划中”阶段，不会再显示一个独立 Plan。

“本地优先”不等于完全离线。模型请求会发送给你配置的 Provider；调用网页、远程 MCP 或其他联网工具时，对应内容也会离开本机。Emperor Agent 负责把本地运行数据和项目数据边界分开，但无法替代外部服务自身的隐私政策。

下载与首次使用

安装包适合直接使用，不要求目标机预装 Node.js、Python、Git 或 ripgrep。

1. 打开 GitHub Releases。
2. 根据设备选择 macOS、Windows 或 Linux 安装包。
3. 当前公开安装包是未签名 Preview，不是 Stable。运行前请阅读未签名预览版安全说明。
4. 第一次启动后进入设置页，添加模型 Provider、API Key 和模型 ID。
5. 创建 Chat 开始普通对话，或者选择本地目录创建 Build 会话。

启动过程不会强制要求你立刻配置模型。没有可用模型时，对话和模型测试会给出配置入口；已经熟悉配置文件的用户也可以参考 config/examples/model_config.example.json。

模型配置

你可以在设置页保存多个标准接口模型。设置页只管理 Provider、协议、凭证和能力；当前对话使用哪个模型，统一在聊天输入框中选择。收起的模型按钮只显示 Provider Logo 和模型名，展开后可以切换模型、调整该模型支持的思考强度。切换结果从下一轮请求开始生效。旧版双角色字段只用于兼容迁移，不再是当前界面语义。

模型配置、连接测试、视觉能力和数据边界见模型、记忆与附件。

Chat、Build、Plan 与 Goal

Chat：普通对话

Chat 适合日常问答、资料整理和一次性的工具任务。它会使用用户档案、全局长期记忆和当前会话历史，但不会自动绑定某个项目目录。

一次请求通常在当前 Agent turn 内结束。最终回复表示这一轮已经停止生成，不代表系统做过 Goal 式验收。如果结果需要多轮修复、独立复核或可追溯的完成条件，应使用 Goal。

Build：项目工作

Build 会话绑定一个本地文件夹，适合代码、文档和其他项目任务。Agent 可以读取项目 AGENTS.md、当前 workspace 和该项目的私有记忆。

项目私有记忆保存在全局 stateRoot，不会自动改写项目中的 AGENTS.md。文件修改和命令执行仍受当前权限模式、workspace policy 和工具 schema 约束。

Plan：先规划再执行

Plan 用于在动手前看清问题、确认方案。进入 Plan 后，Agent 只能进行只读探索、询问用户和提交计划；它不会成为第四种执行权限。Plan 期间仍可在输入框选择询问、编辑或自动，批准方案后使用最新选择的权限执行具体步骤。

在输入框的 / 菜单选择 Plan 会立即进入规划模式，权限选择器右侧同时出现 Plan 标识。也可以手动输入：

/plan
/plan on
/plan off
/plan status

/plan 与 /plan on 的效果相同。Agent 空闲时，把鼠标移到 Plan 标识上可以点击右上角关闭按钮；系统会退出 Plan，并恢复进入 Plan 前保存的最新执行权限。Agent 正在运行时，这个快捷按钮不可用。

Plan 会记录步骤、依赖和验证要求，但它不是长期目标，也不会单独决定 Goal 是否完成。权限模式还可以通过下面的命令查看或切换：

/mode ask
/mode edits
/mode auto
/mode status

Goal：持续完成结果

Goal 用于需要跨多个回合推进、修复和验收的任务。可以直接输入完整命令：

/goal 完成项目的 Goal 模式升级并通过全部验收

也可以从 / 菜单选择 Goal，或单独输入 /goal。此时权限选择器右侧会先出现 Goal 标识，下一条纯文字会作为 Outcome 创建并启动 Goal。若独立 Plan 已开启，系统会先退出 Plan，再进入 Goal。这个待输入状态只属于当前会话，不会写入 Goal 账本；切换会话或重启应用后会清除。Goal Outcome 暂不接受附件、Skill 或 MCP 引用，界面会阻止提交，不会静默丢弃这些内容。

Goal 创建后会锁定 Outcome、范围、约束和 Acceptance Criteria。它通常会进入 Plan 阶段提出方案，等待批准后再由普通 Agent turns 和工具完成步骤。

Plan 执行完不等于 Goal 已完成。系统还会检查每条必需的验收条件、真实工具 Observation、人工确认或 reviewer 结果。模型回复、Todo、Plan 状态和界面操作都不能直接把 Goal 写成 completed；最终状态由 Core 的 Completion Gate 决定。

Goal 常用命令：

Stop 在 Goal 中表示可恢复的 Pause，不表示已经完成。Cancel 才是不可恢复的终态。应用重启也不会自动恢复写操作，必须由用户显式 Resume。

Composer 同一时间只显示 Goal 或 Plan 其中一个标识。Goal 进入内部规划阶段时仍显示 Goal，状态条会标注“规划中”。鼠标悬浮或键盘聚焦后，标识右上角会出现关闭按钮。尚未创建 Goal 时，关闭只退出待输入状态并保留输入框文字；正式 Goal 处于暂停或等待用户状态时，切换到 Plan 会永久取消旧 Goal，再开启独立 Plan，旧记录仍保留用于审计。Goal 正在 Contract、规划、执行或核验时不能切换，应先停止或暂停。

反向切换同样自动处理：Goal 待输入状态切换到 Plan 时会保留输入框文字；独立 Plan 切换到 Goal 时，必须先成功退出 Plan。/plan off 不会关闭 Goal 内部规划，/plan status 在 Goal 存续期间只报告当前顶层模式为 Goal。

Goal 不会提高当前权限。连续三个 cycle 没有产生可确认的 Goal、Plan、Observation、Evidence 或交互进展时，Coordinator 会安全暂停。默认不设置总 cycle、总时长或总成本上限；需要这些限制时，应显式配置 guard。

怎么选择

其他常用命令

功能与成熟度

下面的分级描述当前能力边界，不代表公开安装包已经进入 Stable。

可直接使用

预览能力

基础设施

数据、权限与安全

本地数据放在哪里

Emperor Agent 把应用资源和用户私有数据分开：

• runtimeRoot 保存内置模板、Skills 和静态资源。开发模式默认是仓库根，打包模式默认是 Electron userData/runtime。
• stateRoot 保存会话、记忆、配置、附件和其他运行数据，默认是 ~/.emperor-agent。

可以通过 EMPEROR_CONFIG_DIR 覆盖 stateRoot。完整的解析优先级、迁移规则和目录说明见全局私有存储根架构。

常用私有路径都相对 stateRoot：

Build 项目目录不会承载私有 session、memory、attachments 或 Goal 数据。项目中允许存在协作文档 AGENTS.md，以及 .emperor/settings*.json、rules/ 和项目级 Skills；这些内容与全局私有 store 不是一回事。

权限模式

Plan 通过 /plan 或 /plan on|off|status 独立管理，不属于权限菜单，并与顶层 Goal 互斥。Goal 内部仍可复用 Plan 引擎，但不会产生第二个用户模式。上述三种权限都