doc

README.md

@@ -125,79 +125,83 @@ runner = AgentRunner(
 
 内置 skills（`agent/memory/skills/`）始终自动加载，`skills_dir` 的内容额外追加。
 
-## 经验系统（Experience System）
+## 知识管理系统（Knowledge Management）
 
-经验系统通过**提取、注入、反馈、更新**四个环节，让 Agent 从历史执行中学习并持续改进。
+知识管理系统通过**提取、存储、注入**三个环节，让 Agent 积累和复用结构化知识。
 
 ### 核心流程
 
 **1. 提取（Extract）**
-- **触发时机**：Level 2 压缩时自动触发
-- **提取方式**：在压缩历史消息前，先调用 LLM 对当前执行过程进行反思（reflect）
-- **输出格式**：ACE 规范经验条目
-  ```
-  当 [条件/Context] 时，应该 [动作/Action]（原因：[逻辑/Reason]）
-  ```
-- **存储位置**：追加到 `experiences.md` 文件（默认 `./.cache/experiences.md`）
-
-**2. 注入（Inject）**
-- **触发时机**：切换 Goal 时自动触发
-- **检索策略**：两阶段检索
-  - Stage 1: 语义路由（LLM 挑选 2*k 个相关经验）
-  - Stage 2: 质量精排（根据 metrics 筛选最终 k 个）
-- **注入方式**：将检索到的经验注入到主 Agent 的上下文中
-
-**3. 反馈（Feedback）**
-- **触发时机**：压缩时分析历史消息中经验的使用效果
-- **评价维度**：
-  - `helpful`: 经验有效，帮助完成任务
-  - `harmful`: 经验误导，导致错误
-  - `mixed`: 部分有效，需要改进
-- **反馈来源**：LLM 分析执行过程中经验的实际效果
-
-**4. 更新（Update）**
-- **Metrics 更新**：根据反馈调整 `helpful` 和 `harmful` 计数
-- **内容进化**：
-  - `helpful` + 有改进建议 → 触发经验重写（evolve）
-  - `harmful` 累积 → 降低检索权重或标记为有害
-- **质量过滤**：检索时自动过滤 `quality_score < -2` 的有害经验
-
-### 经验文件格式
-
-```markdown
----
-id: ex_02271430_a3f2
-trace_id: 6822d4e0-8aeb-449f-962e-c431c409a5a0
-tags: {intent: [解构, 图片分析], state: [多图]}
-metrics: {helpful: 3, harmful: 0}
-created_at: 2026-02-27 14:30:15
-updated_at: 2026-02-27 15:20:42
----
-当需要分析多张图片时，应该先并行读取所有图片再统一分析（原因：避免重复调用 LLM，节省 token 和时间）。
-```
-
-### 经验库瘦身
-
-`experience.py` 中提供 `slim_experiences()` 函数，可调用顶级 LLM 合并语义相似的经验，减少冗余。
-
-**功能**：
-- 识别并合并语义高度相似的经验
-- 保留 helpful 最高的 ID
-- 合并 metrics（helpful/harmful 取各条之和）
-- 保持 ACE 规范格式
-
-**状态**：已实现但暂未自动调用，可在 `analyze_story/run.py` 的交互菜单中手动触发（选项 7）。
+- **触发时机**：
+  - 压缩时提取：消息量超阈值触发压缩时，在 Level 1 过滤前用完整 history 反思
+  - 完成时提取：Agent 运行完成后（不代表任务完成，可能中途退出等待人工评估）
+- **提取方式**：调用 LLM 对执行过程进行反思，提取可复用的知识
+- **自定义 Prompt**：可通过配置自定义反思 prompt，空则使用默认（见 `agent/core/prompts/knowledge.py`）
+
+**2. 存储（Store）**
+- **存储位置**：KnowHub 服务（默认 `http://localhost:8765`）
+- **知识结构**：
+  - `title`: 知识标题
+  - `content`: 知识内容
+  - `type`: 知识类型（strategy/tool/pattern/pitfall 等）
+  - `tags`: 标签（键值对，用于分类和检索）
+  - `scopes`: 作用域（如 `org:cybertogether`）
+  - `owner`: 所有者（默认从 git config user.email 获取）
+  - `resource_ids`: 关联资源 ID 列表（代码片段、凭证、cookies 等）
+- **资源管理**：
+  - 知识可关联多个资源（通过 `resource_ids` 字段）
+  - 资源包含 `body`（公开内容）和 `secure_body`（加密内容）
+  - 支持代码片段、API 凭证、cookies 等多种资源类型
+
+**3. 注入（Inject）**
+- **触发时机**：Agent 切换当前工作的 Goal 时自动触发
+- **检索策略**：基于 Goal 描述和上下文，从知识库检索相关知识
+- **注入方式**：将检索到的知识注入到 Agent 的上下文中
 
 ### 配置
 
 ```python
+from agent.core.runner import KnowledgeConfig
+
+knowledge_config = KnowledgeConfig(
+    # 压缩时提取
+    enable_extraction=True,
+    reflect_prompt="",  # 空则使用默认
+
+    # 完成时提取
+    enable_completion_extraction=True,
+    completion_reflect_prompt="",  # 空则使用默认
+
+    # 知识注入
+    enable_injection=True,
+
+    # 默认字段（保存/搜索时自动注入）
+    owner="user@example.com",  # 空则从 git config 获取
+    default_tags={"project": "my_project"},
+    default_scopes=["org:cybertogether"],
+    default_search_types=["strategy", "tool"],
+    default_search_owner=""  # 空则不过滤
+)
+
 runner = AgentRunner(
     llm_call=...,
     trace_store=...,
-    experiences_path="./.cache/experiences.md",  # 自定义经验文件路径
+    knowledge_config=knowledge_config
 )
 ```
 
+### 知识工具
+
+框架提供以下内置工具用于知识管理：
+
+- `knowledge_save`: 保存知识到知识库
+- `knowledge_search`: 搜索知识库
+- `knowledge_get`: 获取指定知识详情
+- `resource_save`: 保存资源（代码、凭证等）
+- `resource_get`: 获取资源内容
+
+这些工具会自动注入配置的默认字段（owner, tags, scopes 等）。
+
 ## AgentRunner 参数
 
 ```python
@@ -206,9 +210,10 @@ AgentRunner(
     trace_store=None,        # Trace 持久化（推荐 FileSystemTraceStore）
     tool_registry=None,      # 工具注册表（默认：全局 registry）
     skills_dir=None,         # 自定义 skills 目录
-    experiences_path="./.cache/experiences.md",  # 经验文件路径
+    knowledge_config=None,   # 知识管理配置（KnowledgeConfig）
     memory_store=None,       # 记忆存储
     utility_llm_call=None,   # 轻量 LLM（生成任务标题等）
+    debug=False,             # 调试模式
 )
 ```
 
@@ -289,56 +294,64 @@ agent/
 
 
 
-# 交互式运行指南
+## 交互式 CLI（Interactive CLI）
 
-本模块展示了如何通过 `run.py` 驱动一个具备“人机协作”能力的 Agent。支持实时监控、手动干预、经验总结以及任务回溯。
-
----
+框架提供交互式控制器，支持实时监控、手动干预和经验总结。
 
-## 1. 快速启动
+### 使用方式
 
-确保已配置 `.env` 中的 API Key，并安装依赖。
-
-```bash
-# 运行还原任务（新建 Trace）
-python examples/restore/run.py
+```python
+from agent.cli import InteractiveController
 
-# 恢复已有任务继续执行
-python examples/restore/run.py --trace <YOUR_TRACE_ID>
+# 创建交互控制器
+interactive = InteractiveController(
+    runner=runner,
+    store=store,
+    enable_stdin_check=True  # 启用标准输入检查
+)
 
+# 在执行循环中检查用户输入
+async for item in runner.run(messages=messages, config=config):
+    cmd = interactive.check_stdin()
+    if cmd == 'pause':
+        await runner.stop(trace_id)
+        menu_result = await interactive.show_menu(trace_id, current_sequence)
+        # 处理菜单结果...
+    elif cmd == 'quit':
+        await runner.stop(trace_id)
+        break
 ```
 
-## 2. 交互控制 (Interactive Controls)
+### 交互控制
 
-在执行过程中，你可以通过命令行实时控制 Agent 的行为：
+在执行过程中，可以通过命令行实时控制：
 
 | 按键 | 动作 | 说明 |
 | --- | --- | --- |
 | `p` / `pause` | **暂停执行** | 立即挂起 Agent 循环，进入交互菜单 |
 | `q` / `quit` | **停止执行** | 安全停止并保存当前的执行状态 |
 
----
+### 交互菜单功能
 
-## 3. 交互菜单功能
+进入暂停模式后，系统提供以下操作：
 
-进入暂停模式后，系统提供以下高级操作：
+1. **插入干预消息**：直接向 Agent 下达新指令
+2. **触发经验总结 (Reflect)**：强制 Agent 对当前过程进行反思
+3. **查看 GoalTree**：可视化当前任务的拆解结构和完成进度
+4. **上下文压缩 (Compact)**：手动精简对话历史
 
-1. **插入干预消息**：直接向 Agent 下达新指令，Agent 将带着新指令继续。
-2. **触发经验总结 (Reflect)**：强制 Agent 对当前过程进行反思，并将“避坑指南”存入经验库。
-3. **查看 GoalTree**：可视化当前任务的拆解结构和完成进度。
-4. **上下文压缩 (Compact)**：手动精简对话历史，保留关键信息以应对长文本 Token 限制。
-5. **经验库瘦身**：调用 LLM 合并冗余经验，提升后续检索质量。
+### 项目配置示例
 
----
+参考 `examples/research/config.py`。
 
-## 4. 任务可视化与调试
+## 任务可视化与调试
 
 框架在运行期间会生成唯一的 `trace_id`。
 
 * **本地日志**：所有的执行细节、工具调用和 Goal 状态均持久化在 `.trace/` 目录下。
 * **Web 可视化**：
 1. 启动服务器：`python api_server.py`
-2. 启动前端: 
+2. 启动前端:
 ```
   cd frontend/react-template
   yarn
@@ -352,32 +365,34 @@ python examples/restore/run.py --trace <YOUR_TRACE_ID>
 
 ---
 
-## 5. 示例项目结构
-- 可以参考其他文件夹中的结构
+## 示例项目结构
+
+可以参考其他文件夹中的结构：
+
 ```text
 examples/[your_example]/
-├── input/             # (可选)输入数据（原图、解构脚本）
-├── output_1/          # (可选)还原结果输出目录
+├── input/             # (可选)输入数据
+├── output_1/          # (可选)输出目录
 ├── skills/            # (可选)领域专属 Skill (.md)
 ├── tool/              # (可选)自定义工具
 ├── presets.json       # (可选)预定义的子 Agent 配置
-├── production.prompt  # (必须)任务核心 System Prompt和 User Prompt
+├── config.py          # (推荐)项目配置
+├── [task].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/`文件夹下保存已有的知识条目
+* **运行轨迹**：根目录下 `.trace/` 文件夹下的实际运行路径结果
+* **知识库**：KnowHub 服务中保存的知识条目（通过 API 访问）