diff --git a/docs/02-user-guide/02-conversations/01-sending-messages.md b/docs/02-user-guide/02-conversations/01-sending-messages.md index 84373a0..15c28cc 100644 --- a/docs/02-user-guide/02-conversations/01-sending-messages.md +++ b/docs/02-user-guide/02-conversations/01-sending-messages.md @@ -2,6 +2,7 @@ title: 发送消息 description: 学习在 DesireCore 中发送文本、图片、文件，以及使用快捷操作和斜杠命令 keywords: [发送消息, 文本输入, 图片上传, 文件引用, 截图, 斜杠命令, 快捷键] +last-reviewed: 2026-07-23 --- # 发送消息 @@ -85,6 +86,25 @@ DesireCore 的输入区域支持多种消息发送方式，包括文本、图片 这种方式适合把桌面、下载目录或文件管理器中的素材直接交给当前智能体处理。 +## 切换工作目录 + +输入框下方的工作目录胶囊和资源面板会显示智能体目录、全局目录以及当前智能体所属团队的共享目录。 + +- 点击智能体或全局目录，会把它设为普通会话的主工作目录。 +- 点击团队共享目录，会为当前具体会话激活该团队；输入框胶囊随即显示团队目录和“团队”标签，右上角资源入口也会显示团队图标角标。再次点击可退出团队作用域。 +- 团队目录不是只读标签。发送下一条消息时，DesireCore 会把对应 `teamId` 交给后端校验，校验通过后它才成为真实 cwd。 +- 智能体运行中不能切换目录，避免正在执行的相对路径和文件权限突然改变。 + +每个会话的团队选择彼此独立。手动多会话模式下，同一智能体的不同会话也可以使用不同的团队目录。 + +创建团队时，DesireCore 会自动建立一条团队共享目录绑定。组长、初始成员以及之后添加或改任主管的成员都从团队关系继承同一目录，不需要逐个配置；非成员不会看到该团队目录。目录绑定失败时，团队创建也会失败，不会留下缺少共享目录的团队。 + +如果这个团队用于代码交付、审计或其他对目录一致性要求高的工作，可以在创建弹窗开启“仅使用团队工作目录”： + +- 开启后，团队共享目录会成为该团队会话的唯一项目工作目录。成员自己的默认目录和全局目录不会进入 cwd、Plan、项目规则或文件工具的工作目录范围。 +- 这个开关不会删除成员原来的目录设置；退出团队作用域后，个人目录仍然正常可用。 +- 不开启时保持兼容行为：团队目录优先，成员和全局目录仍作为相关工作目录保留。 + ## 智能预测 当你刚完成一轮对话、输入框为空且智能体处于空闲状态时，DesireCore 可能会在输入框上方显示一条「下一条消息」预测芯片。 @@ -109,7 +129,7 @@ DesireCore 的输入区域支持多种消息发送方式，包括文本、图片 | 类型 | 语法 | 说明 | |------|------|------| -| 系统命令 | `/命令名` | 内置功能，如 `/plan`、`/new`、`/compact`、`/rewind`、`/steer`、`/help` 等 | +| 系统命令 | `/命令名` | 内置功能，如 `/new`、`/compact`、`/rewind`、`/steer`、`/help` 等 | | 技能调用 | `/skill:技能名` | 调用已安装的技能 | | 快捷调用 | `/技能名` | 直接输入技能名称快速调用 | @@ -119,7 +139,6 @@ DesireCore 的输入区域支持多种消息发送方式，包括文本、图片 | 命令 | 用途 | 适合场景 | |------|------|----------| -| `/plan` | 强制 Companion 先制定计划再动手 | 希望先确认方案，再允许智能体执行 | | `/new` | 开启新的上下文边界 | 想换话题，但保留可见历史 | | `/compact` | 手动压缩当前会话上下文 | 长对话接近模型上下文上限 | | `/rewind` | 回撤到某条用户消息前的检查点 | 智能体走错方向，想回到之前状态 | @@ -127,12 +146,7 @@ DesireCore 的输入区域支持多种消息发送方式，包括文本、图片 | `/skill:技能名` | 显式加载指定技能 | 已知道当前任务需要某个技能 | | `/help` | 查看可用命令完整列表 | 不确定当前有哪些可用命令 | -:::tip `/plan` 的两种用法 -- 单独发送 `/plan`：开启计划模式，不发任何消息 -- `/plan 把所有 console.log 换成 logger.info`：开启计划模式 + 把任务作为消息发出去 - -计划被批准（或拒绝）后，强制模式会自动关闭。 -::: +如果希望智能体只制定计划而暂不执行，直接用自然语言说明，例如：“先写 Plan，不要执行。”Plan 是工作目录中的版本化文件，不需要开启模式或使用专门命令。详见 [计划文件与自然协作](../04-delegation/02-plan-confirmation.md)。 `/steer` 只在智能体运行中生效。发送后它会作为运行中的 steer 指令进入当前任务，并在历史中以专门标记展示。 diff --git a/docs/02-user-guide/03-teaching/01-delegation-interaction.md b/docs/02-user-guide/03-teaching/01-delegation-interaction.md index 8cb9d28..6613620 100644 --- a/docs/02-user-guide/03-teaching/01-delegation-interaction.md +++ b/docs/02-user-guide/03-teaching/01-delegation-interaction.md @@ -46,11 +46,11 @@ DesireCore：你教一次，智能体就记住了。下次遇到类似情况， ### 2. 可委派 -教会之后，你可以把任务交给智能体去做。它会先制定计划、征求你的确认，然后在你允许的权限范围内执行。 +教会之后，你可以把任务交给智能体去做。它会先在工作目录建立或更新计划，允许你随时用自然语言审阅和修改，然后在你允许的权限范围内执行。 > "帮我审一下这份采购合同。" -智能体不会立刻开始——它会先告诉你它打算怎么做，等你确认后才动手。 +智能体会先让计划可见，但不要求你点击统一的“批准计划”按钮。你可以说“先只写计划”让它停在规划阶段；否则它会继续执行已授权步骤，并在真正的高风险动作前单独请求确认。 ### 3. 可审计 diff --git a/docs/02-user-guide/03-teaching/02-six-primitives.md b/docs/02-user-guide/03-teaching/02-six-primitives.md index fdff71c..8426665 100644 --- a/docs/02-user-guide/03-teaching/02-six-primitives.md +++ b/docs/02-user-guide/03-teaching/02-six-primitives.md @@ -74,9 +74,10 @@ DesireCore 的所有交互都建立在六个基本原语之上。理解它们， 3. [固化步骤] 检查质保期 → 与 12 个月底线对比 4. [灵活步骤] 分析进口设备相关条款 5. [灵活步骤] 综合评估合同风险等级 - 6. [人闸门] 生成审查报告，等待你确认后发送给对方 + 6. [人闸门] 发送审查报告前单独请求确认 - 是否按此计划执行？" + 计划会保存到当前工作目录；你可以随时告诉我修改。 + 如果只需要计划而暂不执行，请直接说明。" ``` :::info 什么是固化、灵活、人闸门？ @@ -89,7 +90,7 @@ DesireCore 的所有交互都建立在六个基本原语之上。理解它们， ### 第五步：做（Execute）——它执行任务 -你确认计划后，智能体开始逐步执行。你可以实时看到每一步的进展： +除非你要求“先只写计划”，智能体会在当前授权范围内逐步执行。你可以实时看到进展；遇到计划中标注的人闸门时，它仍会为那个具体动作单独请求确认： ``` 智能体： diff --git a/docs/02-user-guide/04-delegation/01-giving-tasks.md b/docs/02-user-guide/04-delegation/01-giving-tasks.md index f3d681d..4f3db40 100644 --- a/docs/02-user-guide/04-delegation/01-giving-tasks.md +++ b/docs/02-user-guide/04-delegation/01-giving-tasks.md @@ -2,6 +2,7 @@ title: 下达任务 description: 学习如何向智能体清晰地描述一个任务，以及"下达任务"与"简单提问"的区别。 keywords: [下达任务, 委派, 任务描述, delegate, 任务范围] +last-reviewed: 2026-07-22 --- # 下达任务 @@ -106,13 +107,13 @@ keywords: [下达任务, 委派, 任务描述, delegate, 任务范围] ``` 你下达任务 ↓ -智能体可能追问（Clarify）—— 如果信息不够 +智能体在工作目录建立或读取 Plan ↓ -智能体制定计划（Plan）—— 并等你确认 +信息不足时通过自然对话追问（Clarify） ↓ -你确认或修改计划 +智能体按你的回答产生新的 Plan revision ↓ -智能体开始执行（Execute） +智能体在当前权限边界内开始执行（Execute） ↓ 遇到关键节点时暂停确认（人闸门） ↓ @@ -132,5 +133,5 @@ keywords: [下达任务, 委派, 任务描述, delegate, 任务范围] | **每步确认** | 高风险或首次执行 | "每一步都跟我确认后再做" | :::info 下一步 -下达任务后，智能体会先给你一份计划。前往 [计划确认](./02-plan-confirmation.md) 了解如何审阅和确认智能体的执行计划。 +下达任务后，智能体会在工作目录建立或读取 Plan。前往 [计划文件与自然协作](./02-plan-confirmation.md) 了解如何审阅、直接修改和用自然语言修订计划。 ::: diff --git a/docs/02-user-guide/04-delegation/02-plan-confirmation.md b/docs/02-user-guide/04-delegation/02-plan-confirmation.md index 60e645c..f7b577f 100644 --- a/docs/02-user-guide/04-delegation/02-plan-confirmation.md +++ b/docs/02-user-guide/04-delegation/02-plan-confirmation.md @@ -1,211 +1,111 @@ --- -title: 计划确认 -description: 了解智能体如何制定执行计划、计划中包含什么信息、如何审阅修改计划，以及如何主动要求"先想清楚再动手"。 -keywords: [计划, Plan, 确认, 审阅, 步骤, 执行计划, Plan Mode, 强制规划] +title: 计划文件与自然协作 +description: 了解智能体如何在工作目录维护可版本化计划，以及如何通过自然对话审阅、修改和继续执行。 +keywords: [计划, Plan, 审阅, 修订, 步骤, 工作目录, 版本] +last-reviewed: 2026-07-23 --- -# 计划确认 +# 计划文件与自然协作 -当你下达一个任务后，智能体不会立即开始执行——它会先制定一份计划，等你审阅确认后才动手。 +对于需要执行工具、修改文件、委派、多步交付或产生外部影响的任务，智能体会先在当前工作目录建立或读取一份 Plan，再开始行动。 -## 为什么需要确认计划 +Plan 是普通 Markdown 工作文件，不是需要开启的模式，也不是执行授权。你可以随时用自然语言补充、修改或停止方案；真正涉及敏感或高风险动作时，DesireCore 仍会在具体动作发生前触发权限确认或人闸门。 -在现实中，你也不会让一个新来的同事直接开干。好的做法是：先让他说说打算怎么做，你觉得没问题了再让他动手。 +## Plan 为什么保存在项目中 -这样做的好处是： -- **发现误解**：智能体可能理解错了你的意图 -- **补充遗漏**：智能体可能遗漏了某个重要步骤 -- **调整策略**：你可能有更好的执行思路 -- **设置边界**：提前标记哪些步骤需要你确认 +- **透明**：可以直接在编辑器中打开，不依赖聊天界面。 +- **可修改**：你可以手工编辑，智能体继续前会重新读取。 +- **可追溯**：每次实质修订保留一个不可变历史版本。 +- **跟项目走**：可以按团队习惯选择是否纳入 Git。 -## 智能体什么时候会主动制定计划 +## 哪些请求会建立 Plan -智能体会**自动判断**何时该先制定计划，何时可以直接动手。判断的依据是： +| 请求类型 | 智能体行为 | +|---|---| +| 修改文件、运行执行性工具或操作外部系统 | 先创建或读取 Plan | +| 委派其他智能体或完成多步交付 | 先创建或读取 Plan | +| 信息不足 | 先写包含“待澄清项”的微型 Plan，再向你提问并修订 | +| 执行中目标、约束或策略发生变化 | 先产生新版本，再继续行动 | +| 纯问答、解释或寒暄 | 不创建 Plan 文件 | -| 任务特征 | 智能体的处理 | -|---------|------------| -| 涉及修改 3 个以上文件，或预计要执行 5 步以上 | 先制定计划 | -| 包含**不可逆操作**（删除文件、发布版本、迁移数据、对外发送邮件等） | 先制定计划 | -| 你明确说"先做计划"/"先想清楚"/"列一下步骤" | 先制定计划 | -| 智能体自己也不太确定该怎么做 | 先制定计划 | -| 单个文件的小修改 | 直接做 | -| 纯查询、解释、读取信息 | 直接答 | -| 你明确说"直接做"/"不用计划" | 直接做 | +Plan 规则是一项智能体行为规范，而不是会话锁或只读模式。它不会隐藏工具，也不会因为文件存在就绕过权限检查。 -这就像一个有经验的同事——简单的小事不会动不动来找你确认，但碰到大事或有歧义的事一定会先问。 +## 文件位置 -:::tip 想让智能体每次都先做计划？ -往下看「主动要求先做计划」一节——你可以**强制要求**智能体本次会话里任何任务都先制定计划，不管大小。 -::: - -## 计划包含哪些内容 - -智能体制定的计划通常包含以下信息： - -![执行计划](/img/user-guide/delegation/plan-confirmation.svg) - -完整的计划是一份结构化文档，自动保存在 **当前工作目录** 的 `plans/` 子文件夹下（文件名按任务关键词命名，例如 `plans/review-procurement-contract.md`）。即便你关掉对话，文件也会留在那里，方便后续查阅或纳入版本控制。 - -### 计划文件的标准结构 - -每份计划包含以下章节： - -| 章节 | 作用 | -|------|------| -| **Context** | 为什么要做这件事、要解决的问题、约束条件 | -| **Steps** | 分步操作清单，每一步标注风险等级与是否需要你中途确认 | -| **Critical Files** | 涉及的关键文件清单（含路径和行号），让你一眼知道动哪儿 | -| **Artifacts** | 会新建 / 修改 / 删除哪些文件 | -| **Verification** | 怎么知道任务成功完成（可运行的检查命令或手测步骤） | -| **Risks & Rollback** | 可能出错的地方，以及万一出错怎么撤回 | - -### 步骤类型说明 - -| 图标 | 类型 | 含义 | -|------|------|------| -| ⚙️ | **固化步骤** | 规则明确、结果确定的步骤，像程序一样执行 | -| 🧠 | **灵活步骤** | 需要 AI 理解和判断的步骤，结果可能因情况而异 | -| 🚪 | **人闸门** | 执行到此步骤时暂停，等待你的确认（计划中标注为 `confirm: yes` 的步骤） | - -:::info 风险等级 = 自动决定要不要确认 -每个步骤会标注 `risk: low | med | high`。**高风险步骤会自动设为"人闸门"**——这是智能体的纪律，避免在你没看到的时候做不可逆的操作。 -::: - -## 主动要求"先做计划" - -如果你希望智能体**每次都先做计划**（即便是简单任务），有三种方式可以**强制开启计划模式**——开启后，本次会话里所有任务都会经过"计划→审批→执行"流程，直到你关闭它或计划被批准后自动退出。 - -### 方式 1：点击 📋 按钮 - -聊天界面顶部右侧有一个 📋 Plan 按钮，点击切换。开启后会有明显视觉提示： - -- 按钮高亮（紫色背景） -- 输入框边框变为紫色 -- 输入框 placeholder 提示"Plan Mode 已开启：发送的任务会先制定计划再执行" - -### 方式 2：快捷键 `Shift + Tab` - -在主界面（光标不在输入框时）按 `Shift + Tab`，与点击 📋 按钮等价。这是与 Claude Code 对齐的快捷键习惯。 - -### 方式 3：斜杠命令 `/plan` - -在输入框打 `/plan` 提交： - -- 单独发送 `/plan` → 开启计划模式，不发任何消息 -- 发送 `/plan 帮我重构用户模块` → 开启计划模式 + 把 "帮我重构用户模块" 作为任务发出去 - -:::tip 三种入口效果完全相同 -你可以按习惯选用任何一种。计划被批准（或拒绝）后，强制模式会**自动关闭**，你会看到一条 toast 提示"✓ Plan 已批准，开始执行"，无需手动关闭。 -::: - -### 强制模式与自动判断的区别 - -| 场景 | 不开启强制模式（默认） | 开启强制模式 | -|------|----------------------|-------------| -| 你问"1+1=?" | 直接回答 2 | 仍然先制定（很简单的）计划走一遍流程 | -| 你说"帮我加个注释" | 单文件小修改，直接做 | 仍然先制定计划 | -| 你说"重构整个 auth 模块" | 自动触发计划 | 自动触发计划（结果相同） | +每项任务使用独立目录： -强制模式适用于**重要场景**： - -- 你正在让智能体改一个关键系统，要全程可控 -- 你刚教了智能体新规则，想确认它确实理解 -- 你打算让智能体连续做多件事，希望每件事都先看到计划 - -不需要强制模式时，让智能体自己判断更高效。 - -## 如何审阅计划 - -审阅计划时，重点关注以下几点： - -### 1. 步骤是否完整 - -看看是否有遗漏的重要步骤。比如你教过"进口设备必须检查中文说明书条款"，计划中是否包含了这一步？ - -### 2. 步骤类型是否合理 - -- 规则明确的步骤应该是"固化"的 -- 需要理解判断的步骤应该是"灵活"的 -- 高风险操作应该有"人闸门" - -### 3. 风险提示是否到位 - -智能体会主动标注可能的风险。如果你觉得还有其他风险，可以补充。 - -### 4. 人闸门的设置 - -确认哪些步骤需要你中间确认。太多会影响效率，太少可能有风险。 - -### 5. 关键文件清单是否合理 - -计划列出的"Critical Files"应该是你预期会动到的文件。如果出现了你不希望被改动的文件，及时指出。 - -## 审批的三个选项 +```text +<当前工作目录>/.desirecore/plans// +├── PLAN.md +└── revisions/ + ├── 000001.md + ├── 000002.md + └── ... +``` -智能体把计划做好后，会通过结构化提问让你做选择： +- `PLAN.md` 保存当前版本。 +- `revisions/` 保存不可变历史。 +- 首次创建时，`PLAN.md` 与 `revisions/000001.md` 内容一致。 +- 恢复旧内容也会创建新版本，不会改写历史。 -| 选项 | 含义 | -|------|------| -| **批准并执行** | 按当前计划执行；强制模式自动关闭 | -| **需要修改** | 你描述修改点，智能体改完计划再让你审一次 | -| **拒绝** | 任务终止；强制模式自动关闭 | +DesireCore 不会自动修改项目的 `.gitignore`，也不会替你暂存或提交这些文件。 -## 修改计划 +### 多个工作目录和团队目录 -如果计划需要调整，你可以直接说： +- 普通会话按“智能体主目录/第一个有效目录 → 全局主目录/第一个有效目录”选择 cwd。 +- 你可以在输入框的工作目录胶囊或资源面板中点击团队共享目录，显式激活该会话的团队作用域；再次点击同一团队会退出。 +- 团队选择属于当前具体会话。发送消息时 DesireCore 会携带 `teamId`，后端再次校验成员身份和共享目录，校验失败不会静默回落。 +- 同时存在多个可访问目录时，一个任务仍只有一份权威 Plan。它固定写在当前 cwd，其他目录记录在 `related_workdirs` 中，跨目录操作使用绝对路径。 +- 如果创建团队时开启了“仅使用团队工作目录”，团队目录就是唯一项目工作目录和唯一 Plan 根目录，成员/全局目录不会写入 `related_workdirs`；成员原有目录设置不会被删除。 +- 任务进行中切换普通主目录不会搬迁旧 Plan；跨团队继续时，会在新团队目录建立新 Plan，并通过 `continued_from` 链接旧 Plan。 -``` -你："计划基本可以，但做两个修改： - 1. 第 4 步改为固化步骤——进口设备条款的检查规则我之前 - 已经教过了，直接按规则检查就行 - 2. 在第 5 步和第 6 步之间加一个步骤：把报告先保存为 - 草稿，不要直接发送" -``` +运行中的会话不能切换工作目录作用域。空闲会话切换后，下一条消息会同时使用新的 cwd、文件权限、项目指引和 Plan 根目录，避免新旧目录混用。 -智能体会更新计划文件并再次展示给你确认： +## Plan 包含什么 -``` -智能体："已更新计划。变更如下： +一份典型 Plan 包含： - 步骤 4：🧠 [灵活] → ⚙️ [固化] 按已有规则检查进口设备条款 - 新增步骤 6：⚙️ [固化] 保存审查报告草稿 +| 部分 | 内容 | +|---|---| +| **目标** | 要解决的问题与完成标准 | +| **约束与决策** | 已知边界、选择的方案、不能做的事情 | +| **实施顺序** | 按依赖排列的步骤，而不是优先级列表 | +| **待澄清项** | 当前信息不足的地方 | +| **风险与验证** | 可能的风险、具体 Human Gate、如何确认结果 | - 计划文件已更新至 plans/review-procurement-contract.md - 确认按更新后的计划执行？" -``` +Plan 的 frontmatter 会记录 `id`、`revision`、`parent_revision`、`workdir`、绝对 `plan_path`、`scope`、`related_workdirs` 和更新时间等版本信息；团队 Plan 还会记录 `team_id`。它不会记录 `approved`、`rejected`、`mode` 或 `phase` 等流程状态。 -## 快速确认 +## 如何审阅和修改 -对于简单或你已经熟悉的任务，你可以跳过详细审阅： +不需要点击固定的“批准计划”按钮。直接告诉智能体你的意见即可： -``` -你："计划没问题，直接开始。" +```text +“先只写计划，不要执行。” +“第二步改成先备份，再迁移。” +“这个方案可以继续，但发送邮件前必须问我。” +“方向不对，保留现有版本并重新规划。” ``` -或者对于低风险的常规任务，你可以提前告知智能体不需要确认计划： +如果修改影响目标、约束、策略、步骤或验证方式，智能体会创建新的 revision。普通进度变化不会产生 Plan 版本。 -``` -你："帮我审查这份合同，不用让我确认计划，按之前的流程做就行。" -``` +你也可以直接打开 `PLAN.md` 修改。智能体继续前应重新读取文件；发现外部改动时先合并，不应静默覆盖。 -:::warning 首次执行新类型任务时建议确认计划 -即使你很信任智能体，第一次执行某类新任务时，还是建议看一眼计划。等确认它确实理解了你的要求后，下次就可以放心跳过了。 -::: +## Plan 不等于授权 -## 关于计划文件的位置 +下面三个概念相互独立： -每个智能体的计划文件落在**它自己的工作目录**下的 `plans/` 子文件夹——这是有意为之： +| 概念 | 作用 | +|---|---| +| **Plan** | 记录准备做什么、为什么和怎样验证 | +| **自然对话** | 你表达修订、继续、暂停或改变方向 | +| **Human Gate** | 对某个具体高风险动作作出允许或拒绝 | -- **可审阅**：计划是普通 Markdown 文件，你可以在编辑器里直接打开、对比版本 -- **可纳入版本控制**：如果工作目录是 git 仓库，计划会成为团队的"决策日志" -- **跟项目走**：换台机器 / 拉一份仓库即可看到所有历史计划 +因此，“计划没问题，继续”不会永久放开权限；如果后面要删除数据、发布版本、发送邮件或执行其他高风险动作，DesireCore 仍会按当前审批策略处理。 -不同智能体之间**互相看不到**对方的计划——切换到另一个智能体，看到的就是它自己的计划库，不会混淆。 +## 与任务进度的区别 -:::info 不想让计划文件污染目录？ -你可以把 `plans/` 加进 `.gitignore`，让它只在本地保留、不进版本控制。 -::: +Plan 负责策略，Task 负责可分派责任和执行状态。步骤多不等于必须创建任务清单。只有需要跨智能体分工、等待或阻塞、持续展示进度，或者你明确要求跟踪时，智能体才会使用 Task。 :::info 下一步 -确认计划后，智能体就开始执行了。前往 [执行监控](./03-execution-monitoring.md) 了解如何监控执行过程，以及智能体如何用**任务清单**透明展示每一步进度。 +前往 [执行监控](./03-execution-monitoring.md) 了解如何查看正在执行的任务、工具调用和回执。 ::: diff --git a/docs/02-user-guide/04-delegation/03-execution-monitoring.md b/docs/02-user-guide/04-delegation/03-execution-monitoring.md index 69d0227..44cc801 100644 --- a/docs/02-user-guide/04-delegation/03-execution-monitoring.md +++ b/docs/02-user-guide/04-delegation/03-execution-monitoring.md @@ -1,12 +1,12 @@ --- title: 执行监控 -description: 了解如何在智能体执行任务时监控进度，理解固化步骤和灵活步骤的区别，以及如何用任务清单透明展示每一步进度。 +description: 了解如何在智能体执行任务时监控进度，理解固化步骤和灵活步骤的区别，以及何时用任务清单展示关键进度。 keywords: [执行, 监控, 固化步骤, 灵活步骤, 暂停, 恢复, 进度, 任务清单, Task] --- # 执行监控 -确认计划后，智能体开始执行任务。你可以实时监控每一步的进展，并在需要时随时介入。较新的 DesireCore 会把复杂任务同步到悬浮任务板，方便你在长任务中看到全局进度。 +计划写入后，智能体会按你的自然语言指示继续、暂停或修改执行。你可以实时监控进展，并在需要时随时介入；不需要先操作一个统一的“批准计划”状态。较新的 DesireCore 会在长任务确实需要责任分派、阻塞跟踪、跨智能体协作或持续可见进度时使用悬浮任务板。 ## 执行过程的实时展示 @@ -29,7 +29,7 @@ keywords: [执行, 监控, 固化步骤, 灵活步骤, 暂停, 恢复, 进度, ## 任务清单（让进度对你透明） -进入执行阶段后，智能体会**把计划里的每一步转成一条任务**，挂在它自己的「任务清单」上。你随时能问"现在到哪一步了""还剩什么"，智能体不需要回忆——直接查清单即可。 +任务清单不是 Plan 的状态机，也不会机械复制 Plan 的每一步。只有当工作需要明确负责人、记录阻塞、协调多个智能体，或需要持续展示关键进度时，智能体才把相应工作项挂到自己的「任务清单」上。简单顺序仍以 Plan 文件为准。你随时可以问“现在到哪一步了”“还剩什么”。 ### 任务清单的样子 @@ -39,7 +39,7 @@ keywords: [执行, 监控, 固化步骤, 灵活步骤, 暂停, 恢复, 进度, 📋 任务清单（智能体「合同审查助手」） 🔄 #1 解析合同文件，提取关键条款 - 进行中 · 关联 plans/review-procurement-contract.md 第 1 步 + 进行中 · 关联 .desirecore/plans//PLAN.md 🔹 #2 检查违约金比例 待办 · 依赖 #1 完成 @@ -77,7 +77,7 @@ keywords: [执行, 监控, 固化步骤, 灵活步骤, 暂停, 恢复, 进度, 如果智能体在执行中发现需要调整步骤，它会： 1. 主动告诉你"打算偏离原计划，原因是 X" -2. 征得你同意后更新任务清单（增加新任务或修改已有任务） +2. 通过自然对话吸收你的意见；如果你明确要求先确认，它会等待，否则更新相关任务项 3. 把偏离记录追加到计划文件末尾的 `## Execution Notes` 小节 这样事后看 plan 文件 + 任务清单，能完整还原"实际怎么做的"。 diff --git a/docs/04-concepts/02-delegation-model.md b/docs/04-concepts/02-delegation-model.md index cd1c7f2..e3b5b7f 100644 --- a/docs/04-concepts/02-delegation-model.md +++ b/docs/04-concepts/02-delegation-model.md @@ -44,13 +44,13 @@ DesireCore 采用的是**委派模式（Delegation）**：你把事情"交代" ### 4. 立 -- Plan（它制定计划） -> 同伴："我计划分三步完成这份合同审查：1) 结构检查 2) 条款风险分析 3) 生成审查报告。第 2 步涉及修改建议，需要你确认后再执行。" +> 同伴："我计划分三步完成这份合同审查：1) 结构检查 2) 条款风险分析 3) 生成审查报告。如果后续要把报告发送给对方，我会在发送前单独请你确认。" -同伴会给出计划、拆解步骤、标注风险点和需要你确认的环节。 +同伴会在工作目录维护可版本化的计划，拆解步骤、标注风险点和真正需要人闸门的具体动作。你可以直接用自然语言或编辑计划文件来审阅和修改，不需要切换 Plan 模式或点击统一的“批准计划”。 ### 5. 做 -- Execute（它执行任务） -在你确认计划后，同伴按步骤执行。过程中，确定性的操作直接做，需要判断的操作智能处理，高风险操作暂停等你确认。 +除非你明确要求“先只写计划”，同伴会在当前授权范围内按计划继续执行。过程中，确定性的操作直接做，需要判断的操作智能处理；发送、发布、删除等高风险动作仍在实际发生前暂停等你确认。对计划的认可不会替代这些动作级权限。 ### 6. 复 -- Reflect（它交付回执并复盘） @@ -61,13 +61,15 @@ DesireCore 采用的是**委派模式（Delegation）**：你把事情"交代" ## 完整的委派流程 ``` -你发起任务 → 同伴追问确认 → 同伴制定计划 - ↓ - 你确认/修改计划 - ↓ - 同伴执行任务 - ↓ - 同伴复盘 + 交付回执 +你发起任务 → 同伴建立或读取 Plan + ↓ + 信息不足时先写待澄清项，再向你追问 + ↓ + 自然对话审阅或修改（按需） + ↓ + 同伴执行已授权步骤 → 具体人闸门（按需） + ↓ + 同伴复盘 + 交付回执 ↓ 是否学到新东西？ ↓ ↓ diff --git a/docs/05-more/03-glossary.md b/docs/05-more/03-glossary.md index beaa4cb..ad20248 100644 --- a/docs/05-more/03-glossary.md +++ b/docs/05-more/03-glossary.md @@ -2,6 +2,7 @@ title: 术语表 description: DesireCore 核心术语的完整定义，按字母排序 keywords: [术语, 词汇表, 定义, Glossary] +last-reviewed: 2026-07-22 --- # 术语表 @@ -64,7 +65,7 @@ DesireCore 的核心交互范式。不是"我问你答"，而是"我教你做" 将文本转换为数值向量的过程，用于语义搜索和相似度匹配。DesireCore 支持多家供应商的嵌入模型。 ### Execute（做） -六原语之一。智能体在获得计划确认后，在允许的权限和边界内行动、调用工具、推进任务。 +六原语之一。智能体依据当前 Plan，在允许的权限和边界内行动、调用工具、推进任务；Plan 的存在不代表获得额外授权。 ## F @@ -99,7 +100,7 @@ DesireCore 的核心交互范式。不是"我问你答"，而是"我教你做" 智能体的性格定义文件（`persona.md`）。包含沟通风格、决策偏好、输出规范等，是智能体"像谁"的核心定义。不是"人设文案"，而是可执行的行为规范。 ### Plan（立） -六原语之一。智能体给出执行计划，拆解步骤、标注风险点和需要用户确认的环节。 +六原语之一。智能体在当前工作目录维护可版本化计划，记录目标、约束、步骤、风险和验证方式。Plan 通过自然对话修订，不是模式或执行授权。 ### Principles（行为准则） 智能体的行为规则文件（`principles.md`）。定义了"必须做什么""绝不做什么""什么时候找人确认"等规则。 diff --git a/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/02-conversations/01-sending-messages.md b/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/02-conversations/01-sending-messages.md index fef9fd0..418ef3f 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/02-conversations/01-sending-messages.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/02-conversations/01-sending-messages.md @@ -2,6 +2,7 @@ title: Sending Messages description: Learn how to send text, images, files, and use shortcuts and slash commands in DesireCore keywords: [sending messages, text input, image upload, file reference, screenshot, slash commands, keyboard shortcuts] +last-reviewed: 2026-07-23 --- # Sending Messages @@ -83,6 +84,19 @@ When you drag local files or folders over the chat area, it becomes highlighted. - Other files are added as file references - Folders are added as Working Directories +## Switching Working Directories + +The working-directory pill below the input and the resource panel show agent directories, global directories, and shared directories for teams the current agent belongs to. + +- Clicking an agent or global directory makes it the primary directory for normal conversations. +- Clicking a team shared directory activates that team for the specific conversation. The input pill then shows the directory with a Team label, and the resource button in the upper-right shows a team badge. Click the same team again to leave the team scope. +- Team directories are not read-only labels. On the next message, DesireCore sends the corresponding `teamId` for backend validation; only a validated directory becomes the real cwd. +- Directory scope cannot change while the agent is running, which prevents relative paths and file permissions from changing mid-execution. + +Team selection is independent for each conversation. In manual multi-conversation mode, different conversations with the same agent can use different team directories. + +When a team is created, DesireCore automatically establishes one shared-directory binding for the team. The supervisor, initial members, later-added members, and a replacement supervisor all inherit that same directory from team membership; non-members do not see it. If the directory cannot be bound, team creation fails instead of leaving a team without a shared directory. + ## Slash Commands Typing `/` (slash) in the input box pops up the command auto-completion menu. Slash commands let you quickly call system functions and Digital Companion skills. @@ -97,7 +111,7 @@ Typing `/` (slash) in the input box pops up the command auto-completion menu. Sl | Type | Syntax | Description | |------|------|------| -| System Commands | `/command_name` | Built-in functions, such as `/help`, `/skill`, `/plan`, etc. | +| System Commands | `/command_name` | Built-in functions, such as `/help`, `/skill`, `/new`, and `/compact` | | Skill Invocation | `/skill:skill_name` | Call installed skills | | Quick Invocation | `/skill_name` | Directly input skill name for quick calling | @@ -107,18 +121,12 @@ After typing `/skill:`, the list of skills available to the current Digital Comp | Command | Purpose | |---------|---------| -| `/plan` | Force the Companion to plan first before acting (see [Plan Confirmation](../04-delegation/02-plan-confirmation.md#asking-the-agent-to-always-plan-first)) | | `/new` | Start a new conversation, isolated from the current context | | `/compact` | Manually compact the current conversation history to free up context space | | `/steer` | Inject a guiding message while the Companion is thinking (without interrupting generation) | | `/help` | View the full list of available commands | -:::tip Two ways to use `/plan` -- Send `/plan` alone — enables Plan Mode without sending any message -- Send `/plan replace all console.log with logger.info` — enables Plan Mode + submits the task - -After the plan is approved (or rejected), forced mode auto-disables. -::: +If you want the agent to write a Plan without executing, say so naturally—for example, “Write the Plan first; do not execute yet.” Plans are versioned files in the working directory and do not require a mode or special command. See [Plan Files and Natural Collaboration](../04-delegation/02-plan-confirmation.md). ## Shortcut Quick Reference diff --git a/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/03-teaching/01-delegation-interaction.md b/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/03-teaching/01-delegation-interaction.md index f1416a0..8fe8a91 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/03-teaching/01-delegation-interaction.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/03-teaching/01-delegation-interaction.md @@ -46,11 +46,11 @@ The agent will record this rule and automatically apply it next time it reviews ### 2. Delegable -Once taught, you can delegate tasks to the agent. It will first create a plan, seek your confirmation, and then execute within the permissions you allow. +Once taught, you can delegate tasks to the agent. It first creates or updates a plan in the workspace, lets you review and revise it through natural conversation, and then executes within the permissions you allow. > "Help me review this procurement contract." -The agent won't start immediately—it will first tell you what it plans to do, and only proceed after you confirm. +The agent makes the plan visible first, but there is no blanket “approve plan” button. Say “plan only” when you want it to stop after planning; otherwise it may continue through authorized steps and will request confirmation separately before an actual high-risk action. ### 3. Auditable diff --git a/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/03-teaching/02-six-primitives.md b/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/03-teaching/02-six-primitives.md index 9e8bba0..2cb4b77 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/03-teaching/02-six-primitives.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/03-teaching/02-six-primitives.md @@ -74,9 +74,10 @@ Agent: "I plan to review this contract in the following steps: 3. [Deterministic] Check warranty period → Compare with 12-month minimum 4. [Adaptive] Analyze imported equipment related clauses 5. [Adaptive] Comprehensive contract risk assessment - 6. [Human Gate] Generate review report, waiting for your confirmation before sending + 6. [Human Gate] Ask for confirmation immediately before sending the report - Proceed with this plan?" + I will save this plan in the current workspace; you can revise it at any time. + If you want a plan without execution, say so explicitly." ``` :::info What are Deterministic, Adaptive, and Human Gate? @@ -89,7 +90,7 @@ See [Execution Monitoring](../04-delegation/03-execution-monitoring.md) for deta ### Step 5: Execute—It Executes the Task -After you confirm the plan, the agent begins executing step by step. You can see the progress of each step in real time: +Unless you ask for “plan only,” the agent proceeds step by step within the permissions already granted. You can see progress in real time; when it reaches a marked human gate, it still asks for confirmation for that specific action: ``` Agent: diff --git a/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/04-delegation/01-giving-tasks.md b/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/04-delegation/01-giving-tasks.md index 14d5f56..35e2f78 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/04-delegation/01-giving-tasks.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/04-delegation/01-giving-tasks.md @@ -2,6 +2,7 @@ title: Giving Tasks description: Learn how to clearly describe a task to your agent, and the difference between "giving a task" and "simple inquiry." keywords: [giving tasks, delegation, task description, delegate, task scope] +last-reviewed: 2026-07-22 --- # Giving Tasks @@ -106,13 +107,13 @@ After you give a task, the agent operates according to the following process: ``` You give a task ↓ -Agent may ask for clarification (Clarify) — if information is insufficient +Agent creates or reads a Plan in the working directory ↓ -Agent creates a plan (Plan) — and waits for your confirmation +Agent asks naturally for clarification when information is missing ↓ -You confirm or modify the plan +Agent creates a new Plan revision from your answer ↓ -Agent begins execution (Execute) +Agent begins execution within the active permission boundaries ↓ Pauses for confirmation at key nodes (Human Gate) ↓ @@ -132,5 +133,5 @@ You can control the agent's autonomy as needed: | **Step-by-Step Confirmation** | High-risk or first-time execution | "Confirm with me before every step" | :::info Next Step -After giving a task, the agent will first present you with a plan. Go to [Plan Confirmation](./02-plan-confirmation.md) to learn how to review and confirm the agent's execution plan. +After receiving a task, the agent creates or reads a Plan in the working directory. See [Plan Files and Natural Collaboration](./02-plan-confirmation.md) to learn how to review, edit, and revise it through natural conversation. ::: diff --git a/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/04-delegation/02-plan-confirmation.md b/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/04-delegation/02-plan-confirmation.md index 31b91ea..7ded48e 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/04-delegation/02-plan-confirmation.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/04-delegation/02-plan-confirmation.md @@ -1,211 +1,111 @@ --- -title: Plan Confirmation -description: Learn how the agent creates execution plans, what information is included, how to review and modify them, and how to require the agent to "think before acting". -keywords: [plan, confirmation, review, steps, execution plan, Plan Mode, force plan] +title: Plan Files and Natural Collaboration +description: Learn how agents keep versioned plans in the working directory and how to review, revise, and continue through natural conversation. +keywords: [plan, review, revision, steps, working directory, versioning] +last-reviewed: 2026-07-22 --- -# Plan Confirmation +# Plan Files and Natural Collaboration -When you assign a task, the agent won't start executing immediately—it will first create a plan and wait for your review and confirmation before proceeding. +For work that calls tools, changes files, delegates work, has multiple delivery steps, or affects an external system, the agent first creates or reads a Plan in the current working directory before acting. -## Why Plan Confirmation is Needed +A Plan is an ordinary Markdown work file. It is not a mode and does not grant permission to execute. You can revise, pause, or redirect it in natural language at any time. When a sensitive or high-risk action is actually about to happen, DesireCore still applies the relevant permission check or Human Gate. -In reality, you wouldn't let a new colleague start working immediately either. Good practice is: first have them explain what they plan to do, and only let them proceed when you think it's okay. +## Why Plans Live in the Project -The benefits are: -- **Discover misunderstandings**: The agent may have misunderstood your intent -- **Fill gaps**: The agent may have missed an important step -- **Adjust strategy**: You may have a better execution approach -- **Set boundaries**: Mark in advance which steps need your confirmation +- **Transparent**: open them in any editor without relying on the chat UI. +- **Editable**: you can edit a Plan directly, and the agent should reread it before continuing. +- **Traceable**: every substantive revision keeps an immutable historical version. +- **Project-local**: your team decides whether Plan files belong in Git. -## When Does the Agent Automatically Make a Plan +## Which Requests Create a Plan -The agent **judges automatically** when to make a plan first and when it can act directly. The criteria are: +| Request type | Agent behavior | +|---|---| +| Change files, run action-oriented tools, or affect an external system | Create or read a Plan first | +| Delegate to another agent or deliver multi-step work | Create or read a Plan first | +| Missing information | Write a small Plan with open questions, ask for clarification, then revise it | +| Goal, constraints, or strategy changes during execution | Create a new revision before continuing | +| Pure Q&A, explanation, or casual conversation | Do not create a Plan file | -| Task characteristic | Agent behavior | -|--------------------|----------------| -| Modifying 3+ files, or anticipating 5+ tool calls | Plan first | -| Includes **irreversible operations** (delete files, publish a release, migrate data, send email to external parties, etc.) | Plan first | -| You explicitly say "make a plan first" / "think it through" / "list the steps" | Plan first | -| The agent itself is uncertain how to proceed | Plan first | -| Single-file small edits | Act directly | -| Pure queries / explanations / reads | Answer directly | -| You explicitly say "just do it" / "no plan needed" | Act directly | +This is an agent behavior policy, not a session lock or read-only mode. It does not hide tools, and the presence of a Plan never bypasses permission checks. -This works like an experienced colleague—they don't run plans by you for small things, but always check before big or ambiguous ones. +## File Location -:::tip Want the agent to plan every time? -See "Asking the Agent to Always Plan First" below—you can **force** the agent to plan for any task in this session, regardless of size. -::: - -## What the Plan Contains - -The plan created by the agent typically includes the following information: - -![Execution Plan](/img/user-guide/delegation/plan-confirmation.svg) - -The full plan is a structured document, automatically saved to the **current working directory** under the `plans/` subfolder (the file is named after the task's keywords, e.g. `plans/review-procurement-contract.md`). Even if you close the conversation, the file stays there for later review or version control. - -### Plan File Sections - -Each plan contains these sections: - -| Section | Purpose | -|---------|---------| -| **Context** | Why this is being done, the problem to solve, constraints | -| **Steps** | Ordered step list, each marked with risk level and whether your confirmation is required mid-flight | -| **Critical Files** | Critical files involved (with paths and line numbers), so you know exactly what's being touched | -| **Artifacts** | Which files will be created / modified / deleted | -| **Verification** | How to know the task succeeded (concrete runnable check commands or manual test steps) | -| **Risks & Rollback** | What could go wrong, and how to recover if it does | - -### Step Type Explanation - -| Icon | Type | Meaning | -|------|------|---------| -| ⚙️ | **Deterministic Step** | Steps with clear rules and certain results, executed like a program | -| 🧠 | **Adaptive Step** | Steps requiring AI understanding and judgment, results may vary by situation | -| 🚪 | **Human Gate** | Pause when executing to this step, waiting for your confirmation (steps marked `confirm: yes` in the plan) | - -:::info Risk level decides confirmation automatically -Each step carries a `risk: low | med | high` tag. **High-risk steps are automatically set as "human gates"** — this is the agent's discipline to avoid irreversible actions when you aren't watching. -::: - -## Asking the Agent to Always Plan First - -If you want the agent to **plan every time** (even for simple tasks), there are three ways to **force Plan Mode** on. Once enabled, every task in this session goes through "plan → approval → execute" until you turn it off, or until a plan is approved and auto-exits. - -### Method 1: Click the 📋 button - -There is a 📋 Plan button on the right side of the chat header. Click it to toggle. When enabled, you'll see clear visual cues: - -- The button is highlighted (purple background) -- The input box border turns purple -- The placeholder reads "Plan Mode is on: the agent will draft a plan before executing" - -### Method 2: Keyboard shortcut `Shift + Tab` - -Press `Shift + Tab` on the main interface (when the cursor isn't in the input box). Equivalent to clicking the 📋 button. This matches Claude Code's habit. - -### Method 3: Slash command `/plan` - -Type `/plan` in the input box and submit: - -- Send `/plan` alone → enable Plan Mode without sending any message -- Send `/plan refactor the user module` → enable Plan Mode + submit "refactor the user module" as the task - -:::tip All three entry points do the same thing -Pick whichever fits your habit. After the plan is approved (or rejected), forced mode **auto-disables**—you'll see a toast "✓ Plan approved, executing". No need to turn it off manually. -::: - -### Forced Mode vs Auto-Judgment - -| Scenario | Without forced mode (default) | With forced mode | -|----------|------------------------------|------------------| -| You ask "1+1=?" | Direct answer: 2 | Still goes through the (very simple) plan flow | -| You say "add a comment to this line" | Single-file edit, act directly | Still plans first | -| You say "refactor the whole auth module" | Auto-triggers plan | Auto-triggers plan (same result) | +Each task uses its own directory: -Forced mode is useful when: - -- You're letting the agent change a critical system and want full control -- You just taught the agent new rules and want to confirm it actually internalized them -- You're about to delegate a series of tasks and want to see plans for each one - -Otherwise, letting the agent decide on its own is more efficient. - -## How to Review the Plan - -When reviewing the plan, focus on the following points: - -### 1. Are Steps Complete? - -See if any important steps are missing. For example, if you taught "imported equipment must have Chinese instruction manual clause checked," is this step included in the plan? - -### 2. Are Step Types Reasonable? - -- Steps with clear rules should be "deterministic" -- Steps requiring understanding and judgment should be "adaptive" -- High-risk operations should have "human gates" - -### 3. Are Risk Warnings in Place? - -The agent will proactively mark possible risks. If you think there are other risks, you can add them. - -### 4. Human Gate Settings - -Confirm which steps need your intermediate confirmation. Too many will affect efficiency, too few may pose risks. - -### 5. Is the Critical Files List Reasonable? - -The "Critical Files" section should match what you expect to be touched. If files you didn't intend to modify show up, raise it. - -## Three Approval Options +```text +/.desirecore/plans// +├── PLAN.md +└── revisions/ + ├── 000001.md + ├── 000002.md + └── ... +``` -When the agent finishes the plan, it asks you a structured question with three choices: +- `PLAN.md` contains the current version. +- `revisions/` contains immutable history. +- On creation, `PLAN.md` and `revisions/000001.md` have the same content. +- Restoring older content creates a new revision instead of rewriting history. -| Option | Meaning | -|--------|---------| -| **Approve and execute** | Execute the current plan; forced mode auto-disables | -| **Needs revision** | You describe what to change; the agent rewrites the plan and asks again | -| **Reject** | Task terminated; forced mode auto-disables | +DesireCore does not automatically change `.gitignore`, stage these files, or commit them. -## Modifying the Plan +### Multiple and Team Working Directories -If the plan needs adjustment, you can simply say: +- A normal conversation resolves cwd from the agent primary/first valid directory, then the global primary/first valid directory. +- Click a team shared directory in the input-area working-directory pill or resource panel to activate that team's scope for the conversation. Click the same team again to leave it. +- Team selection belongs to the specific conversation. DesireCore sends its `teamId`, and the backend revalidates membership and the shared directory instead of silently falling back. +- Even when several directories are accessible, a task has one authoritative Plan in the current cwd. Other directories are recorded in `related_workdirs`, and cross-directory work uses absolute paths. +- If a team is created with "only use team working directory" enabled, the team directory becomes the sole project working directory and sole Plan root; member/global directories are not written to `related_workdirs`. The member's original directory settings are not deleted. +- Changing a normal primary directory does not move an in-progress Plan. Continuing across teams creates a new Plan in the new team directory and links the old one through `continued_from`. -``` -You: "The plan is basically fine, but make two changes: - 1. Change step 4 to deterministic step—the rules for checking imported equipment clauses were already - taught before, just check according to the rules - 2. Add a step between step 5 and step 6: save the report as a - draft first, don't send it directly" -``` +The working-directory scope cannot change while a conversation is running. After an idle conversation switches scope, its next message uses the new cwd, file permissions, project instructions, and Plan root together so old and new directory context cannot be mixed. -The agent will update the plan file and show it to you again for confirmation: +## What a Plan Contains -``` -Agent: "Plan updated. Changes as follows: +A typical Plan includes: - Step 4: 🧠 [Adaptive] → ⚙️ [Deterministic] Check imported equipment clauses according to existing rules - New Step 6: ⚙️ [Deterministic] Save review report draft +| Section | Content | +|---|---| +| **Goal** | The problem and completion criteria | +| **Constraints and decisions** | Known boundaries, chosen approach, and prohibited actions | +| **Implementation order** | Dependency order, not a priority ranking | +| **Open questions** | Information that is still missing | +| **Risks and verification** | Risks, concrete Human Gates, and how the result will be checked | - Plan file updated at plans/review-procurement-contract.md - Confirm execution according to updated plan?" -``` +Plan frontmatter records `id`, `revision`, `parent_revision`, `workdir`, the absolute `plan_path`, `scope`, `related_workdirs`, and timestamps; team Plans also record `team_id`. It does not store workflow states such as `approved`, `rejected`, `mode`, or `phase`. -## Quick Confirmation +## Reviewing and Revising a Plan -For simple tasks or tasks you're already familiar with, you can skip detailed review: +There is no required “approve plan” button. Just tell the agent what you want: -``` -You: "The plan is fine, start directly." +```text +“Write the Plan only; do not execute yet.” +“Change step two so we back up before migrating.” +“Continue with this approach, but ask me before sending the email.” +“This direction is wrong. Keep the current revision and plan again.” ``` -Or for low-risk routine tasks, you can inform the agent in advance that plan confirmation isn't needed: +If your change affects the goal, constraints, strategy, steps, or verification, the agent creates a new revision. Ordinary progress updates do not create Plan versions. -``` -You: "Help me review this contract, no need to confirm the plan with me, just follow the previous process." -``` +You can also edit `PLAN.md` directly. Before continuing, the agent should reread the file and merge external edits instead of silently overwriting them. -:::warning Recommended to Confirm Plan for First-Time Execution of New Task Types -Even if you trust the agent, it's recommended to take a look at the plan when executing a new type of task for the first time. After confirming it truly understands your requirements, you can confidently skip it next time. -::: +## A Plan Is Not Authorization -## Where Plan Files Live +These concepts remain separate: -Each agent's plan files live in **its own working directory** under the `plans/` subfolder—this is intentional: +| Concept | Purpose | +|---|---| +| **Plan** | Records what is intended, why, and how it will be verified | +| **Natural conversation** | Expresses revisions, continuation, pauses, or a change of direction | +| **Human Gate** | Allows or rejects a specific high-risk action | -- **Reviewable**: Plans are plain Markdown files; you can open them in any editor and diff versions -- **Version-controllable**: If the working directory is a git repo, plans become the team's "decision log" -- **Tied to the project**: Switch machines or check out a fresh copy of the repo to see all historical plans +Saying “the Plan looks good, continue” does not permanently open permissions. If later work deletes data, publishes a release, sends an email, or performs another high-risk action, DesireCore still follows the active approval policy. -Different agents **cannot see each other's plans**—switching to another agent shows you its own plan library, no confusion. +## Plans vs Task Progress -:::info Don't want plans cluttering the directory? -Add `plans/` to `.gitignore` to keep them local only and out of version control. -::: +Plans describe strategy. Tasks describe assignable ownership and execution state. A Plan with many steps does not automatically need a task list. Agents use Tasks when work needs cross-agent ownership, waiting or blocking, ongoing progress visibility, or when you explicitly request tracking. :::info Next Step -After confirming the plan, the agent begins execution. Go to [Execution Monitoring](./03-execution-monitoring.md) to see how the agent uses a **task list** to make every step's progress transparent to you. +See [Execution Monitoring](./03-execution-monitoring.md) to learn how to inspect active tasks, tool calls, and receipts. ::: diff --git a/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/04-delegation/03-execution-monitoring.md b/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/04-delegation/03-execution-monitoring.md index fcdcf5f..7cec0be 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/04-delegation/03-execution-monitoring.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/04-delegation/03-execution-monitoring.md @@ -1,12 +1,12 @@ --- title: Execution Monitoring -description: Learn how to monitor progress while the agent executes tasks, understand the difference between deterministic and adaptive steps, and how the task list makes every step transparent. +description: Learn how to monitor progress while the agent executes tasks, understand deterministic and adaptive steps, and when to use a task list for key progress. keywords: [execution, monitoring, deterministic step, adaptive step, pause, resume, progress, task list] --- # Execution Monitoring -After confirming the plan, the agent begins executing the task. You can monitor the progress of each step in real time and intervene at any time when needed. +After the plan is written, the agent follows your natural-language direction to continue, pause, or revise execution. You can monitor progress and intervene at any time; there is no blanket plan-approval state to operate first. For long-running work, newer DesireCore versions use the floating task board when responsibility, blockers, cross-agent coordination, or durable progress visibility genuinely need tracking. ## Real-Time Display of Execution Process @@ -52,7 +52,7 @@ When a task is executing, you will see a real-time updated progress panel: ## Task List (Transparent Progress) -Once execution begins, the agent **converts each step in the plan into a task** on its own "task list". You can ask "where are we?" / "what's left?" any time—the agent doesn't need to recall anything; it just queries the list. +A task list is not a state machine for the Plan, and it does not mechanically duplicate every Plan step. The agent creates task items only when work needs explicit ownership, blocker tracking, cross-agent coordination, or durable visibility of key progress. Simple sequencing remains in the Plan file. You can still ask “where are we?” or “what’s left?” at any time. ### What the Task List Looks Like @@ -62,7 +62,7 @@ Each task has a clear title, status, and links to related context: 📋 Task List (agent "Contract Review Assistant") 🔄 #1 Parse contract file, extract key clauses - In progress · linked to plans/review-procurement-contract.md step 1 + In progress · linked to .desirecore/plans//PLAN.md 🔹 #2 Check penalty percentage Pending · depends on #1 completing @@ -100,7 +100,7 @@ Dependencies appear in the list as "depends on #X" so you can see the full task If the agent needs to adjust steps mid-flight, it will: 1. Proactively tell you "I'm going to deviate from the original plan, because X" -2. After your agreement, update the task list (add new tasks or modify existing ones) +2. Incorporate your feedback through natural conversation; wait only when you explicitly require confirmation, otherwise update the relevant task items 3. Append the deviation log to the `## Execution Notes` section at the end of the plan file This way, looking at the plan file + task list later gives you a complete reconstruction of "what actually happened". diff --git a/i18n/en/docusaurus-plugin-content-docs/current/04-concepts/02-delegation-model.md b/i18n/en/docusaurus-plugin-content-docs/current/04-concepts/02-delegation-model.md index 717464a..4cf27d3 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/04-concepts/02-delegation-model.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/04-concepts/02-delegation-model.md @@ -44,13 +44,13 @@ When encountering uncertainty, the companion won't guess — it will proactively ### 4. Plan — Plan (It formulates a plan) -> Companion: "I plan to complete this contract review in three steps: 1) Structure check 2) Clause risk analysis 3) Generate review report. Step 2 involves modification suggestions and requires your confirmation before execution." +> Companion: "I plan to complete this contract review in three steps: 1) Structure check 2) Clause risk analysis 3) Generate review report. If the report later needs to be sent to the other party, I will ask for confirmation immediately before sending it." -The companion presents a plan, breaks down steps, and marks risk points and areas requiring your confirmation. +The companion maintains a versioned plan in the workspace, breaks down steps, and marks risk points and the specific actions that truly require a human gate. You can review it through natural conversation or by editing the plan file—there is no Plan mode or blanket “approve plan” button. ### 5. Execute — Execute (It carries out the task) -After you confirm the plan, the companion executes step by step. During the process, deterministic operations are done directly, operations requiring judgment are handled intelligently, and high-risk operations pause for your confirmation. +Unless you explicitly ask for “plan only,” the companion proceeds within the permissions already granted. Deterministic operations run directly, judgment-heavy work remains adaptive, and high-risk actions such as sending, publishing, or deleting still pause for confirmation immediately before the action. Accepting a plan never replaces action-level permission. ### 6. Reflect — Reflect (It delivers receipts and reviews) @@ -61,12 +61,14 @@ The companion submits a work receipt, reviews deviations, and writes new experie ## Complete Delegation Flow ``` -You initiate task → Companion asks for clarification → Companion formulates plan - ↓ - You confirm/modify plan - ↓ - Companion executes task - ↓ +You initiate task → Companion creates or reads Plan + ↓ + Writes clarification items first if info is missing, then asks you + ↓ + Natural review or revision (as needed) + ↓ + Execute authorized steps → Specific human gate (as needed) + ↓ Companion reviews + delivers receipt ↓ Did it learn something new? diff --git a/i18n/en/docusaurus-plugin-content-docs/current/05-more/03-glossary.md b/i18n/en/docusaurus-plugin-content-docs/current/05-more/03-glossary.md index 5a53127..4472ef3 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/05-more/03-glossary.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/05-more/03-glossary.md @@ -2,6 +2,7 @@ title: Glossary description: Complete definitions of DesireCore core terms, sorted alphabetically keywords: [terms, glossary, definitions, Glossary] +last-reviewed: 2026-07-22 --- # Glossary @@ -64,7 +65,7 @@ A record of changes to files or content, with deletions marked in red and additi The process of converting text to numerical vectors for semantic search and similarity matching. DesireCore supports embedding models from multiple providers. ### Execute (Do) -One of the Six Primitives. After obtaining plan confirmation, the agent acts within allowed permissions and boundaries, invokes tools, and advances the task. +One of the Six Primitives. The agent acts from the current Plan within the allowed permissions and boundaries, invokes tools, and advances the task. A Plan does not grant additional authorization. ## F @@ -99,7 +100,7 @@ Model Context Protocol. An open standard proposed by Anthropic that allows AI mo The agent's personality definition file (`persona.md`). Contains communication style, decision preferences, output specifications, etc.—the core definition of "who the agent is like." Not a "character setting copy," but executable behavioral specifications. ### Plan -One of the Six Primitives. The agent provides an execution plan, breaking down steps and marking risk points and areas requiring user confirmation. +One of the Six Primitives. The agent keeps a versioned Plan in the current working directory, recording goals, constraints, steps, risks, and verification. Plans are revised through natural conversation; they are not a mode or execution permission. ### Principles The agent's behavioral rules file (`principles.md`). Defines "must do," "never do," and "when to ask for confirmation" rules.