|
|
@@ -286,3 +286,98 @@ agent/
|
|
|
```
|
|
|
|
|
|
详细架构文档：[docs/README.md](./docs/README.md)
|
|
|
+
|
|
|
+
|
|
|
+
|
|
|
+# 交互式运行指南
|
|
|
+
|
|
|
+本模块展示了如何通过 `run.py` 驱动一个具备“人机协作”能力的 Agent。支持实时监控、手动干预、经验总结以及任务回溯。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 1. 快速启动
|
|
|
+
|
|
|
+确保已配置 `.env` 中的 API Key，并安装依赖。
|
|
|
+
|
|
|
+```bash
|
|
|
+# 运行还原任务（新建 Trace）
|
|
|
+python examples/restore/run.py
|
|
|
+
|
|
|
+# 恢复已有任务继续执行
|
|
|
+python examples/restore/run.py --trace <YOUR_TRACE_ID>
|
|
|
+
|
|
|
+```
|
|
|
+
|
|
|
+## 2. 交互控制 (Interactive Controls)
|
|
|
+
|
|
|
+在执行过程中，你可以通过命令行实时控制 Agent 的行为：
|
|
|
+
|
|
|
+| 按键 | 动作 | 说明 |
|
|
|
+| --- | --- | --- |
|
|
|
+| `p` / `pause` | **暂停执行** | 立即挂起 Agent 循环，进入交互菜单 |
|
|
|
+| `q` / `quit` | **停止执行** | 安全停止并保存当前的执行状态 |
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 3. 交互菜单功能
|
|
|
+
|
|
|
+进入暂停模式后，系统提供以下高级操作：
|
|
|
+
|
|
|
+1. **插入干预消息**：直接向 Agent 下达新指令，Agent 将带着新指令继续。
|
|
|
+2. **触发经验总结 (Reflect)**：强制 Agent 对当前过程进行反思，并将“避坑指南”存入经验库。
|
|
|
+3. **查看 GoalTree**：可视化当前任务的拆解结构和完成进度。
|
|
|
+4. **上下文压缩 (Compact)**：手动精简对话历史，保留关键信息以应对长文本 Token 限制。
|
|
|
+5. **经验库瘦身**：调用 LLM 合并冗余经验，提升后续检索质量。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 4. 任务可视化与调试
|
|
|
+
|
|
|
+框架在运行期间会生成唯一的 `trace_id`。
|
|
|
+
|
|
|
+* **本地日志**：所有的执行细节、工具调用和 Goal 状态均持久化在 `.trace/` 目录下。
|
|
|
+* **Web 可视化**：
|
|
|
+1. 启动服务器：`python api_server.py`
|
|
|
+2. 启动前端:
|
|
|
+```
|
|
|
+ cd frontend/react-template
|
|
|
+ yarn
|
|
|
+ yarn dev
|
|
|
+```
|
|
|
+2. 访问控制台：`http://localhost:3000`
|
|
|
+3. 在前端界面中切换任务，即直观追踪 Agent 的思考链路。
|
|
|
+
|
|
|
+### 提示：目前前端可视化只供观看本地运行过的trace结果，新任务运行等功能正在开发中，运行可在命令行中执行
|
|
|
+### 绿色节点为整体的goal(目标)，蓝色节点为子goal(目标)，灰色节点为基础信息节点。点击蓝色边/绿色边会折叠节点，点击节点会在右侧显示详情。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 5. 示例项目结构
|
|
|
+- 可以参考其他文件夹中的结构
|
|
|
+```text
|
|
|
+examples/[your_example]/
|
|
|
+├── input/ # (可选)输入数据（原图、解构脚本）
|
|
|
+├── output_1/ # (可选)还原结果输出目录
|
|
|
+├── skills/ # (可选)领域专属 Skill (.md)
|
|
|
+├── tool/ # (可选)自定义工具
|
|
|
+├── presets.json # (可选)预定义的子 Agent 配置
|
|
|
+├── production.prompt # (必须)任务核心 System Prompt和 User Prompt
|
|
|
+└── run.py # (必须)交互式运行入口
|
|
|
+
|
|
|
+```
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 6. 环境兼容性 (Network & Proxy)
|
|
|
+
|
|
|
+针对 Clash Verge / TUN 模式等网络环境，本项目已内置代理自动避让逻辑：
|
|
|
+
|
|
|
+* **代理优化**：通过 `no_proxy` 配置防止 `httpx` 错误引导流量。
|
|
|
+* **Browser 模式**：支持 `cloud` (远程) 和 `local` (本地) 模式切换。
|
|
|
+
|
|
|
+## 7. 运行结果展示 (trace & knowledge)
|
|
|
+
|
|
|
+运行过程中，会自动存储trace运行结果，以及在压缩内容时自动总结经验，在调研任务时自动提取知识，最终会保存在知识库中(以json的形式)
|
|
|
+
|
|
|
+* **运行轨迹**: 根目录下`.trace/`文件夹下的实际运行路径结果
|
|
|
+* **知识库**: 根目录下`.cache/knowledge_atoms/`文件夹下保存已有的知识条目
|
