# 用户使用手册
English · 简体中文
本文只聚焦插件的实际操作，指导**如何使用**其中的每一个功能；
基础概念和安装方式请见 [README](https://github.com/GZX2211/dsh-Visual-Workflow/blob/main/README.md)；
具体节点配置与流程设计指南请直接查看插件内的**预设工作流模板**（中文界面生成中文版，英文界面生成英文版），模板中的节点说明是详细操作指南。
## 1. 认识主界面
> 这是主工作台界面，所有流程设计、属性编辑全都在该界面进行，图中批注了详细的界面功能说明。
补充：属性栏中的“入库”？
- “入库”是把当前工作流或角色模板转为可复用资产的人工筛选入口。
- 入库的资产在下次执行流程规划或编排调整（改图）时，其中的节点布置和流程设计会被代理参考甚至复用。
- 当你确认某流程结构和其中的节点配置具有参考价值时，点击“入库”，即可让该系统的下一次建设建立在已有资源之上，而非从零开始。
- 由于受模型先验影响，若引入不可靠资源，反而会产生负面污染，所以请务必审核入库的资产。
## 2. 资产与经验管理
> 这是资产管理界面（点击左下角切换），该界面通过 tab 分类，后续种类可能会更多，以最新为准。
各类别说明：
- **工作流资产**：供父代理规划工作流或改图时参考；通过工作台中的“入库”手动创建。
- **角色资产**：保存可复用的角色配置；供父代理配置节点时参考或复用；重复角色会被去重储存。
- **经验**：保存可供特定主体召回的实践经验。不再适用时会自动归档；也可以手动修改或归档。
- **经验生成提示词**：维护经验提炼时使用的提示词版本；同样支持手动管理。
> 该界面的所有内容都是为了系统“可演化”而服务的。
## 3. 工具组合管理
> 这是工具组合管理界面，也是整个插件最常用、最重要的管理页，其承载了插件功能的实现方式，以及官方和 MCP 工具集的全面管理。
给角色配置工具：
1. 打开**工具组合管理**，勾选所需工具集创建一个工具组合。
2. 回到工作台，选中角色节点，在**工具组合**中选择它。
3. 运行前确认该角色的工具权限；如有遗漏会无法完成任务。
### 关闭某项能力
在**工具管理**中找到对应工具，关闭其全局开关；
全局开关会影响所有代理的工具可见性（包括父代理）；
只限制某个子代理角色时，从该角色的工具组合中取消勾选即可；
| 目标 | 操作 |
|---|---|
| 关闭父代理查阅组织资产 | 关闭 `wf_org_catalog` |
| 阻止父代理修改工作流图 | 关闭 `wf_graph_patch` |
| 关闭经验召回 | 关闭 `wf_experience_recall` 或从不需要经验能力的角色组合中移除经验工具 |
| 关闭复盘与经验记录 | 关闭 `wf_experience_learn` |
| 关闭经验效果反馈 | 关闭 `wf_experience_feedback` |
| 关闭插件消息投递 | 关闭 `wf_send_message` |
| 关闭代理向用户提问 | 关闭 `wf_ask_user` |
| 关闭数据库查询能力 | 取消角色节点的 `db-in` 连线，或关闭 `wf_db_query` |
### 工具互斥
本插件部分工具（wf_*）会与官方工具互斥，请按需选择并只开启其中一个：
1. ask_user_question 与 wf_ask_user:
区别只在于是否需要让子代理提问；本插件工具可以让所有代理提问；而官方仅限父代理。
2. send_message 与 wf_send_message：
都是代理间发送信息的工具，但是官方工具在开启 Agent Team 功能时会产生缺陷，无法向普通子代理发消息（只能发给团队成员）；因此我在其上对该问题进行了修复。如果未来官方修复这个问题，插件自带工具自然退役。
3. spawn_teammate 与 wf_run_node：
区别在于是否需要更多的团队成员属性配置；本插件工具可以配置属性栏中显示的所有内容；官方只能继承父代理的配置。
## 4. 创建并运行工作流
两种方式：
- 手动设计：详细设计指南请直接下载插件打开预设模板中的对应节点查看说明。
- 使用 `/arrange` 生成工作流：
在主会话中输入：
```text
/arrange 做一个内容生产流水线，包含选题、资料收集、成稿、审核和发布
```
操作说明：
1. 在意图中写清任务目标、阶段、交付物和重要约束。
2. 等待父代理规划。它会使用 Catalog 工具查看可用资产、工具组合、模型和编排规则，再通过图修改工具创建工作流模板。
3. 打开工作台检查生成的节点、依赖、角色配置和工具组合。
4. 修正不符合预期的部分。
5. 点击**运行**开始执行。
### 运行中调整
- **父代理改图**：需授予改图权限；父代理会根据流程执行情况、任务匹配度、阻塞性，自行进行流程修复和重编排。
- **人工改图**：运行时在画布中修改节点或连线，保存后检查最新拓扑与节点状态，再观察后续调度。
- **设置人工检查点**：在需要审核的位置插入**暂停**阶段节点。流程到达该节点后会暂停并保存断点；检查后再次运行。
- **断点续跑**：打开对应的活跃实例，查看当前节点状态，点击运行即可在上次因意外而中断的节点处续跑。
## 5. 提示词分层
为了该系统可靠的维护性和可演化性。因此，编写和修改提示词时要分层编写，再放到对应位置。
### 两种提示词类别
- **编排提示词**：面向父代理，指导它规划、调度、检查和调整工作流。
- **执行提示词**：面向子代理，指导它完成被分配的具体工作。
### 三个治理层次
| 层次 | 应该写什么 | 在哪里维护 |
|---|---|---|
| **规则提示词** | 跨任务长期有效的机制规则、图操作约定和项目规范 | 插件按需注入的规则文本；项目长期规范 AGENTS.md 放在项目文档中 |
| **职责提示词** | 父代理或某个子代理长期承担的职责、边界、质量标准 | 父代理节点或角色节点的 `System Prompt`；可复用角色放入资产管理的角色提示词 |
| **任务提示词** | 本次任务目标、输入、执行要求、交付物和验收标准 | 任务节点的描述；或父代理通过 `wf_send_message` 下发给节点的具体任务 |
### 编写时按这三步判断
1. **每次任务都不变吗？** 是：放规则层。
2. **只对某种角色长期有效吗？** 是：放职责层。
3. **只对当前任务或节点有效吗？** 是：放任务层。
维护原则：变化频率通常是**规则 < 职责 < 任务**。不要把一次性任务要求写进规则提示词或职责提示词，也不要把所有通用规范复制到每个任务里，这对未来整个 Agent 的使用过程都会很有帮助；另外说明，这不是该插件的硬性约定，而是作为一个使用者和开发者所积累的经验。
> 你同样可以要求 Agent 按此标准进行维护，但是 Agent 改过的内容一定要审核，这是保证工作流运行可控性的边界。
## 6. 常见操作问题
- **`/arrange` 没有生成预期流程**：把目标、阶段、交付物和关键约束写得更具体；检查 `wf_org_catalog` 与 `wf_graph_patch` 是否开启；在工作台检查并修正生成图。
- **节点无法调用工具**：检查节点所选工具组合、全局工具开关，以及是否需要 `db-in` 连线。
- **父代理无法修改图**：检查 `wf_graph_patch` 是否开启；确认修改对象是模板还是当前实例，并使用对应的 `scope`。
- **代理无法向其他成员发消息**：确认 `wf_send_message` 已开启、发送方工具组合包含它，并检查该代理上下文中是否有注入其他成员的节点 ID。
- **修改资产后召回没有变化**：检查修改的是否是活跃提示词版本（active 指针标记）；再确认工具返回体中是否返回了该资产内容。
遇到无法解决的问题时，记录当时情况再复现一次（如果可以），然后在 issue 中向我提出来；你如果很擅长定位问题并修改代码，也可以提交 PR；我会及时处理。
