From 8cd06457e267ba31e6f637aea98d8894dd98045a Mon Sep 17 00:00:00 2001 From: yi-ge Date: Sun, 17 May 2026 17:18:23 +0800 Subject: [PATCH 1/2] =?UTF-8?q?feat(user-guide):=20=E6=89=A9=E5=B1=95?= =?UTF-8?q?=E8=AE=A1=E5=88=92=E7=A1=AE=E8=AE=A4=E4=B8=8E=E6=89=A7=E8=A1=8C?= =?UTF-8?q?=E7=9B=91=E6=8E=A7=E7=AB=A0=E8=8A=82=EF=BC=8C=E8=A6=86=E7=9B=96?= =?UTF-8?q?=E4=B8=89=E5=85=A5=E5=8F=A3=20+=20=E4=BB=BB=E5=8A=A1=E6=B8=85?= =?UTF-8?q?=E5=8D=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 补齐 v10.0.x 引入的 Plan 模式与 Task 清单的客户向说明（中英双语同步）： 计划确认（04-delegation/02-plan-confirmation.md）： - 新增「智能体什么时候会主动制定计划」表，列出自动触发条件与不触发条件 - 新增「主动要求先做计划」一节，介绍三种显式开启入口： · 📋 toggle 按钮（含视觉提示） · Shift+Tab 快捷键 · /plan 斜杠命令（两种用法） - 新增「强制模式与自动判断的区别」对比表 - 新增「审批的三个选项」（批准 / 修改 / 拒绝，含自动退出说明） - 新增「计划文件的位置」一节：每个智能体工作目录下的 plans/ 子文件夹 + plan 文件标准章节（Context / Steps / Critical Files / Artifacts / Verification / Risks & Rollback） 执行监控（04-delegation/03-execution-monitoring.md）： - 步骤状态加 🔹 待办、🗑️ 已放弃 - 新增「任务清单」一大节，覆盖：清单样子、状态立即更新纪律、依赖关系、 偏离同步、per-Agent 私有、跨智能体协作通过消息/回执对齐 斜杠命令（02-conversations/01-sending-messages.md）： - 命令类型表加 /plan - 新增「常用系统命令」表 + /plan 两种用法 tip 英文 i18n 同步上述全部内容。docusaurus build（zh-Hans + en）通过， 无失效链接。 --- .../02-conversations/01-sending-messages.md | 19 +- .../04-delegation/02-plan-confirmation.md | 121 ++++++++++++- .../04-delegation/03-execution-monitoring.md | 78 ++++++++- .../02-conversations/01-sending-messages.md | 19 +- .../04-delegation/02-plan-confirmation.md | 162 +++++++++++++----- .../04-delegation/03-execution-monitoring.md | 76 +++++++- 6 files changed, 415 insertions(+), 60 deletions(-) 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 25c236e..5ddbf88 100644 --- a/docs/02-user-guide/02-conversations/01-sending-messages.md +++ b/docs/02-user-guide/02-conversations/01-sending-messages.md @@ -76,12 +76,29 @@ DesireCore 的输入区域支持多种消息发送方式，包括文本、图片 | 类型 | 语法 | 说明 | |------|------|------| -| 系统命令 | `/命令名` | 内置功能，如 `/help`、`/skill` 等 | +| 系统命令 | `/命令名` | 内置功能，如 `/help`、`/skill`、`/plan` 等 | | 技能调用 | `/skill:技能名` | 调用已安装的技能 | | 快捷调用 | `/技能名` | 直接输入技能名称快速调用 | 输入 `/skill:` 后会自动显示当前 Companion 可用的技能列表，继续输入可过滤匹配。 +### 常用系统命令 + +| 命令 | 作用 | +|------|------| +| `/plan` | 强制 Companion 先制定计划再动手（详见[计划确认](../04-delegation/02-plan-confirmation.md#主动要求先做计划)） | +| `/new` | 开启一个新的对话，与当前对话上下文隔离 | +| `/compact` | 手动压缩当前对话历史，释放上下文空间 | +| `/steer` | 在 Companion 思考过程中插入一条引导消息（不打断生成） | +| `/help` | 查看可用命令完整列表 | + +:::tip `/plan` 的两种用法 +- 单独发送 `/plan`：开启计划模式，不发任何消息 +- `/plan 把所有 console.log 换成 logger.info`：开启计划模式 + 把任务作为消息发出去 + +计划被批准（或拒绝）后，强制模式会自动关闭。 +::: + ## 快捷键速查 | 操作 | 默认快捷键 (macOS) | 默认快捷键 (Windows/Linux) | 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 f426cb5..c7fcd80 100644 --- a/docs/02-user-guide/04-delegation/02-plan-confirmation.md +++ b/docs/02-user-guide/04-delegation/02-plan-confirmation.md @@ -1,7 +1,7 @@ --- title: 计划确认 -description: 了解智能体如何制定执行计划、计划中包含什么信息，以及如何审阅和修改计划。 -keywords: [计划, Plan, 确认, 审阅, 步骤, 执行计划] +description: 了解智能体如何制定执行计划、计划中包含什么信息、如何审阅修改计划，以及如何主动要求"先想清楚再动手"。 +keywords: [计划, Plan, 确认, 审阅, 步骤, 执行计划, Plan Mode, 强制规划] --- # 计划确认 @@ -18,19 +18,101 @@ keywords: [计划, Plan, 确认, 审阅, 步骤, 执行计划] - **调整策略**：你可能有更好的执行思路 - **设置边界**：提前标记哪些步骤需要你确认 +## 智能体什么时候会主动制定计划 + +智能体会**自动判断**何时该先制定计划，何时可以直接动手。判断的依据是： + +| 任务特征 | 智能体的处理 | +|---------|------------| +| 涉及修改 3 个以上文件，或预计要执行 5 步以上 | 先制定计划 | +| 包含**不可逆操作**（删除文件、发布版本、迁移数据、对外发送邮件等） | 先制定计划 | +| 你明确说"先做计划"/"先想清楚"/"列一下步骤" | 先制定计划 | +| 智能体自己也不太确定该怎么做 | 先制定计划 | +| 单个文件的小修改 | 直接做 | +| 纯查询、解释、读取信息 | 直接答 | +| 你明确说"直接做"/"不用计划" | 直接做 | + +这就像一个有经验的同事——简单的小事不会动不动来找你确认，但碰到大事或有歧义的事一定会先问。 + +:::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 模块" | 自动触发计划 | 自动触发计划（结果相同） | + +强制模式适用于**重要场景**： + +- 你正在让智能体改一个关键系统，要全程可控 +- 你刚教了智能体新规则，想确认它确实理解 +- 你打算让智能体连续做多件事，希望每件事都先看到计划 + +不需要强制模式时，让智能体自己判断更高效。 ## 如何审阅计划 @@ -54,6 +136,20 @@ keywords: [计划, Plan, 确认, 审阅, 步骤, 执行计划] 确认哪些步骤需要你中间确认。太多会影响效率，太少可能有风险。 +### 5. 关键文件清单是否合理 + +计划列出的"Critical Files"应该是你预期被动到的文件。如果出现了你不希望被改动的文件，及时指出。 + +## 审批的三个选项 + +智能体把计划做好后，会通过结构化提问让你做选择： + +| 选项 | 含义 | +|------|------| +| **批准并执行** | 按当前计划执行；强制模式自动关闭 | +| **需要修改** | 你描述修改点，智能体改完计划再让你审一次 | +| **拒绝** | 任务终止；强制模式自动关闭 | + ## 修改计划 如果计划需要调整，你可以直接说： @@ -66,7 +162,7 @@ keywords: [计划, Plan, 确认, 审阅, 步骤, 执行计划] 草稿，不要直接发送" ``` -智能体会更新计划并再次展示给你确认： +智能体会更新计划文件并再次展示给你确认： ``` 智能体："已更新计划。变更如下： @@ -74,6 +170,7 @@ keywords: [计划, Plan, 确认, 审阅, 步骤, 执行计划] 步骤 4：🧠 [灵活] → ⚙️ [固化] 按已有规则检查进口设备条款 新增步骤 6：⚙️ [固化] 保存审查报告草稿 + 计划文件已更新至 plans/review-procurement-contract.md 确认按更新后的计划执行？" ``` @@ -95,6 +192,20 @@ keywords: [计划, Plan, 确认, 审阅, 步骤, 执行计划] 即使你很信任智能体，第一次执行某类新任务时，还是建议看一眼计划。等确认它确实理解了你的要求后，下次就可以放心跳过了。 ::: +## 关于计划文件的位置 + +每个智能体的计划文件落在**它自己的工作目录**下的 `plans/` 子文件夹——这是有意为之： + +- **可审阅**：计划是普通 Markdown 文件，你可以在编辑器里直接打开、对比版本 +- **可纳入版本控制**：如果工作目录是 git 仓库，计划会成为团队的"决策日志" +- **跟项目走**：换台机器 / 拉一份仓库即可看到所有历史计划 + +不同智能体之间**互相看不到**对方的计划——切换到另一个智能体，看到的就是它自己的计划库，不会混淆。 + +:::info 不想让计划文件污染目录？ +你可以把 `plans/` 加进 `.gitignore`，让它只在本地保留、不进版本控制。 +::: + :::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 41e69b8..6e14f01 100644 --- a/docs/02-user-guide/04-delegation/03-execution-monitoring.md +++ b/docs/02-user-guide/04-delegation/03-execution-monitoring.md @@ -1,7 +1,7 @@ --- title: 执行监控 -description: 了解如何在智能体执行任务时监控进度，理解固化步骤和灵活步骤的区别，以及如何暂停和恢复执行。 -keywords: [执行, 监控, 固化步骤, 灵活步骤, 暂停, 恢复, 进度] +description: 了解如何在智能体执行任务时监控进度，理解固化步骤和灵活步骤的区别，以及如何用任务清单透明展示每一步进度。 +keywords: [执行, 监控, 固化步骤, 灵活步骤, 暂停, 恢复, 进度, 任务清单, Task] --- # 执行监控 @@ -18,12 +18,82 @@ keywords: [执行, 监控, 固化步骤, 灵活步骤, 暂停, 恢复, 进度] | 状态 | 图标 | 含义 | |------|------|------| -| 已完成 | ✅ | 步骤成功执行 | +| 待办 | 🔹 | 任务已创建但还未开始 | | 执行中 | 🔄 | 正在处理 | -| 等待中 | ⏳ | 排队等待执行 | +| 已完成 | ✅ | 步骤成功执行 | | 需确认 | 🚪 | 人闸门，等待你的确认 | | 警告 | ⚠️ | 执行成功但发现问题 | | 失败 | ❌ | 执行失败 | +| 已放弃 | 🗑️ | 任务被丢弃（已软删除，仍可在审计记录里查到） | + +## 任务清单（让进度对你透明） + +进入执行阶段后，智能体会**把计划里的每一步转成一条任务**，挂在它自己的「任务清单」上。你随时能问"现在到哪一步了""还剩什么"，智能体不需要回忆——直接查清单即可。 + +### 任务清单的样子 + +每条任务都有明确的标题、状态、关联信息： + +``` +📋 任务清单（智能体「合同审查助手」） + +🔄 #1 解析合同文件，提取关键条款 + 进行中 · 关联 plans/review-procurement-contract.md 第 1 步 + +🔹 #2 检查违约金比例 + 待办 · 依赖 #1 完成 + +🔹 #3 检查付款条件 + 待办 · 依赖 #1 完成 + +🔹 #4 分析进口设备条款（灵活） + 待办 · 风险:中 · 依赖 #1 #2 #3 完成 + +🔹 #5 综合风险评估（灵活） + 待办 · 风险:中 · 需要你确认 + +🔹 #6 发送审查报告 + 待办 · 风险:高 · 需要你确认 +``` + +### 状态会**立刻**更新 + +智能体的纪律是： +- **开始做某一步前**，立刻把它的状态切到「🔄 进行中」 +- **做完一步**，立刻切到「✅ 已完成」 +- **不会等一批做完了才统一更新** + +这意味着你看到的进度永远是当前的——不会出现"看上去停了"但其实在干活的情况。 + +### 任务之间的依赖关系 + +任务可以声明"做我之前要先做某某"。比如"运行数据库迁移"必须依赖"备份完成"先成功——智能体看到依赖未完成时不会去执行后续步骤，避免顺序错乱。 + +依赖关系会在清单里显示为「依赖 #X 完成」，你能一眼看出整个任务图的执行顺序。 + +### 偏离计划时清单会同步更新 + +如果智能体在执行中发现需要调整步骤，它会： + +1. 主动告诉你"打算偏离原计划，原因是 X" +2. 征得你同意后更新任务清单（增加新任务或修改已有任务） +3. 把偏离记录追加到计划文件末尾的 `## Execution Notes` 小节 + +这样事后看 plan 文件 + 任务清单，能完整还原"实际怎么做的"。 + +### 任务清单是智能体私有的 + +每个智能体只能看到、修改**自己的**任务清单。这是有意为之： + +- **互不干扰**：切换到另一个智能体，看到的就是它的清单，不会出现别的智能体的待办 +- **责任清晰**：每条任务都能追溯到具体的智能体（不会出现"这是谁做的"的疑问） +- **隔离审计**：任务记录跟着智能体走，便于按智能体维度做事后审查 + +:::tip 跨智能体协作怎么办？ +如果你让多个智能体协作完成一件大事（比如组队任务），每个智能体管理自己的清单，**通过消息和回执互相通报进度**——不是直接读取彼此的清单。这与现实中的团队协作一致：每个人有自己的待办，靠汇报和回执对齐。详见[跨智能体协作](./06-cross-agent.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 c27ccb9..37c36a6 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 @@ -76,12 +76,29 @@ 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`, etc. | +| System Commands | `/command_name` | Built-in functions, such as `/help`, `/skill`, `/plan`, etc. | | Skill Invocation | `/skill:skill_name` | Call installed skills | | Quick Invocation | `/skill_name` | Directly input skill name for quick calling | After typing `/skill:`, the list of skills available to the current Digital Companion is automatically displayed, and continuing to input filters the matches. +### Built-in System Commands + +| 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. +::: + ## Shortcut Quick Reference | Action | Default Shortcut (macOS) | Default Shortcut (Windows/Linux) | 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 a6d919c..31b91ea 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,7 +1,7 @@ --- title: Plan Confirmation -description: Learn how the agent creates execution plans, what information is included in plans, and how to review and modify plans. -keywords: [plan, Plan, confirmation, review, steps, execution plan] +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] --- # Plan Confirmation @@ -18,50 +18,46 @@ The benefits are: - **Adjust strategy**: You may have a better execution approach - **Set boundaries**: Mark in advance which steps need your confirmation +## When Does the Agent Automatically Make a Plan + +The agent **judges automatically** when to make a plan first and when it can act directly. The criteria are: + +| 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 works like an experienced colleague—they don't run plans by you for small things, but always check before big or ambiguous ones. + +:::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 │ -├──────────────────────────────────────────────────────┤ -│ │ -│ Task: Review procurement contract XX-2025-001 │ -│ Estimated steps: 6 │ -│ Estimated time: About 3-5 minutes │ -│ │ -│ Step list: │ -│ │ -│ 1. ⚙️ [Deterministic] Parse contract file, extract key clauses │ -│ Estimated time: 30 seconds │ -│ │ -│ 2. ⚙️ [Deterministic] Check penalty percentage (standard: ≤20%) │ -│ Estimated time: 10 seconds │ -│ │ -│ 3. ⚙️ [Deterministic] Check payment terms (standard: ≥30 days) │ -│ Estimated time: 10 seconds │ -│ │ -│ 4. 🧠 [Adaptive] Analyze imported equipment related clauses │ -│ Estimated time: 1-2 minutes │ -│ Note: Requires AI understanding of contract semantics │ -│ │ -│ 5. 🧠 [Adaptive] Comprehensive risk assessment, generate review report │ -│ Estimated time: 1-2 minutes │ -│ │ -│ 6. 🚪 [Human Gate] Wait for confirmation before sending review report │ -│ Note: Requires your confirmation of report content before sending │ -│ │ -│ Risk warnings: │ -│ - Contract is a scanned document, OCR recognition may have errors │ -│ - Imported equipment clauses require manual review │ -│ │ -│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ -│ │ ✓ Confirm │ │ ✎ Modify │ │ ✗ Cancel │ │ -│ └──────────┘ └──────────┘ └──────────┘ │ -│ │ -└──────────────────────────────────────────────────────┘ -``` +![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 @@ -69,7 +65,54 @@ The plan created by the agent typically includes the following information: |------|------|---------| | ⚙️ | **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 | +| 🚪 | **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) | + +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 @@ -93,6 +136,20 @@ The agent will proactively mark possible risks. If you think there are other ris 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 + +When the agent finishes the plan, it asks you a structured question with three choices: + +| 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 | + ## Modifying the Plan If the plan needs adjustment, you can simply say: @@ -105,7 +162,7 @@ You: "The plan is basically fine, but make two changes: draft first, don't send it directly" ``` -The agent will update the plan and show it to you again for confirmation: +The agent will update the plan file and show it to you again for confirmation: ``` Agent: "Plan updated. Changes as follows: @@ -113,6 +170,7 @@ Agent: "Plan updated. Changes as follows: Step 4: 🧠 [Adaptive] → ⚙️ [Deterministic] Check imported equipment clauses according to existing rules New Step 6: ⚙️ [Deterministic] Save review report draft + Plan file updated at plans/review-procurement-contract.md Confirm execution according to updated plan?" ``` @@ -134,6 +192,20 @@ You: "Help me review this contract, no need to confirm the plan with me, just fo 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. ::: +## Where Plan Files Live + +Each agent's plan files live in **its own working directory** under the `plans/` subfolder—this is intentional: + +- **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 + +Different agents **cannot see each other's plans**—switching to another agent shows you its own plan library, no confusion. + +:::info Don't want plans cluttering the directory? +Add `plans/` to `.gitignore` to keep them local only and out of version control. +::: + :::info Next Step -After confirming the plan, the agent begins execution. Go to [Execution Monitoring](./03-execution-monitoring.md) to learn how to monitor the execution process. +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. ::: 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 df7963c..734c96b 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,7 +1,7 @@ --- title: Execution Monitoring -description: Learn how to monitor progress while the agent executes tasks, understand the difference between deterministic and adaptive steps, and how to pause and resume execution. -keywords: [execution, monitoring, deterministic step, adaptive step, pause, resume, progress] +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. +keywords: [execution, monitoring, deterministic step, adaptive step, pause, resume, progress, task list] --- # Execution Monitoring @@ -41,12 +41,80 @@ When a task is executing, you will see a real-time updated progress panel: | Status | Icon | Meaning | |--------|------|---------| -| Completed | ✅ | Step executed successfully | +| Pending | 🔹 | Task created but not started | | In Progress | 🔄 | Currently processing | -| Waiting | ⏳ | Queued for execution | +| Completed | ✅ | Step executed successfully | | Needs Confirmation | 🚪 | Human Gate, waiting for your confirmation | | Warning | ⚠️ | Execution successful but problem found | | Failed | ❌ | Execution failed | +| Discarded | 🗑️ | Task soft-deleted (still visible in the audit log) | + +## 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. + +### What the Task List Looks Like + +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 + +🔹 #2 Check penalty percentage + Pending · depends on #1 completing + +🔹 #3 Check payment terms + Pending · depends on #1 completing + +🔹 #4 Analyze imported equipment clauses (adaptive) + Pending · risk: med · depends on #1 #2 #3 + +🔹 #5 Comprehensive risk assessment (adaptive) + Pending · risk: med · needs your confirmation + +🔹 #6 Send review report + Pending · risk: high · needs your confirmation +``` + +### Status Updates **Immediately** + +The agent's discipline is: +- **Before starting a step**, immediately switch its status to "🔄 In Progress" +- **As soon as a step is done**, switch to "✅ Completed" +- **Never batch updates** across multiple steps + +That means what you see is always current—no "looks stalled but actually working" situations. + +### Task Dependencies + +A task can declare "you must finish X before me". For example, "run database migration" depends on "backup complete"—if the dependency hasn't finished, the agent won't start the dependent step, preventing out-of-order execution. + +Dependencies appear in the list as "depends on #X" so you can see the full task graph at a glance. + +### Deviations from the Plan Reflect in the List + +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) +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". + +### Task Lists Are Private to Each Agent + +Each agent can see and modify **only its own** task list. By design: + +- **No interference**: Switching to another agent shows you its list—you won't see another agent's to-dos mixed in +- **Clear accountability**: Each task traces back to a specific agent (no "who did this?") +- **Isolated audit**: Task records travel with the agent, making it easy to audit per-agent + +:::tip What about multi-agent collaboration? +When several agents work on a big task (e.g. a team task), each agent manages its own list and **shares progress via messages and receipts**—not by reading each other's lists. This mirrors real teamwork: each person has their own to-do list and aligns through updates and receipts. See [Cross-Agent Collaboration](./06-cross-agent.md). +::: ## Deterministic Steps vs. Adaptive Steps From bda00f31e19280093999d281afaf1fd9dd9930f8 Mon Sep 17 00:00:00 2001 From: yi-ge Date: Sun, 17 May 2026 18:33:14 +0800 Subject: [PATCH 2/2] =?UTF-8?q?docs(user-guide):=20=E4=BF=AE=E5=A4=8D=20Co?= =?UTF-8?q?pilot=20review=20=E5=8F=8D=E9=A6=88?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 状态表加回 ⏳ 等待中 / Waiting 行：例图 / SVG 仍展示该状态，新增"待办 🔹" 表达的是任务清单层面的待办，与运行管线"等待中 ⏳"是不同概念，两者并存 - 移除中文 execution-monitoring 重复的二级标题「## 固化步骤与灵活步骤」 - 修正中文 plan-confirmation "预期被动到" → "预期会动到" 错别字 --- docs/02-user-guide/04-delegation/02-plan-confirmation.md | 2 +- docs/02-user-guide/04-delegation/03-execution-monitoring.md | 3 +-- .../02-user-guide/04-delegation/03-execution-monitoring.md | 1 + 3 files changed, 3 insertions(+), 3 deletions(-) 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 c7fcd80..60e645c 100644 --- a/docs/02-user-guide/04-delegation/02-plan-confirmation.md +++ b/docs/02-user-guide/04-delegation/02-plan-confirmation.md @@ -138,7 +138,7 @@ keywords: [计划, Plan, 确认, 审阅, 步骤, 执行计划, Plan Mode, 强制 ### 5. 关键文件清单是否合理 -计划列出的"Critical Files"应该是你预期被动到的文件。如果出现了你不希望被改动的文件，及时指出。 +计划列出的"Critical Files"应该是你预期会动到的文件。如果出现了你不希望被改动的文件，及时指出。 ## 审批的三个选项 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 6e14f01..d241622 100644 --- a/docs/02-user-guide/04-delegation/03-execution-monitoring.md +++ b/docs/02-user-guide/04-delegation/03-execution-monitoring.md @@ -19,6 +19,7 @@ keywords: [执行, 监控, 固化步骤, 灵活步骤, 暂停, 恢复, 进度, | 状态 | 图标 | 含义 | |------|------|------| | 待办 | 🔹 | 任务已创建但还未开始 | +| 等待中 | ⏳ | 队列排队等待（依赖未完成或前序步骤未结束） | | 执行中 | 🔄 | 正在处理 | | 已完成 | ✅ | 步骤成功执行 | | 需确认 | 🚪 | 人闸门，等待你的确认 | @@ -95,8 +96,6 @@ keywords: [执行, 监控, 固化步骤, 灵活步骤, 暂停, 恢复, 进度, ## 固化步骤与灵活步骤 -## 固化步骤与灵活步骤 - 这是 DesireCore 最核心的设计之一——每个执行步骤都被明确分类，让你知道哪些结果是确定的，哪些包含 AI 判断。 ### 固化步骤（Deterministic Step） 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 734c96b..5fedfa2 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 @@ -42,6 +42,7 @@ When a task is executing, you will see a real-time updated progress panel: | Status | Icon | Meaning | |--------|------|---------| | Pending | 🔹 | Task created but not started | +| Waiting | ⏳ | Queued (waiting on a dependency or an earlier step to finish) | | In Progress | 🔄 | Currently processing | | Completed | ✅ | Step executed successfully | | Needs Confirmation | 🚪 | Human Gate, waiting for your confirmation |