|
|
@@ -14,11 +14,11 @@
|
|
|
|
|
|
**核心理念:所有 Agent 都是 Trace**
|
|
|
|
|
|
-| 类型 | 创建方式 | 父子关系 | 状态 |
|
|
|
-|------|---------|---------|------|
|
|
|
-| 主 Agent | 直接调用 `runner.run()` | 无 parent | 正常执行 |
|
|
|
-| 子 Agent | 通过 `agent` 工具 | `parent_trace_id` / `parent_goal_id` 指向父 | 正常执行 |
|
|
|
-| 人类协助 | 通过 `ask_human` 工具 | `parent_trace_id` 指向父 | 阻塞等待 |
|
|
|
+| 类型 | 创建方式 | 父子关系 | 状态 |
|
|
|
+| -------- | ----------------------- | ------------------------------------------- | -------- |
|
|
|
+| 主 Agent | 直接调用 `runner.run()` | 无 parent | 正常执行 |
|
|
|
+| 子 Agent | 通过 `agent` 工具 | `parent_trace_id` / `parent_goal_id` 指向父 | 正常执行 |
|
|
|
+| 人类协助 | 通过 `ask_human` 工具 | `parent_trace_id` 指向父 | 阻塞等待 |
|
|
|
|
|
|
---
|
|
|
|
|
|
@@ -74,13 +74,13 @@ agent/
|
|
|
|
|
|
### 职责划分
|
|
|
|
|
|
-| 模块 | 职责 |
|
|
|
-|-----|------|
|
|
|
-| **core/** | Agent 执行引擎 + 预设配置 |
|
|
|
-| **trace/** | 执行追踪 + 计划管理 |
|
|
|
+| 模块 | 职责 |
|
|
|
+| ---------- | ------------------------------------------ |
|
|
|
+| **core/** | Agent 执行引擎 + 预设配置 |
|
|
|
+| **trace/** | 执行追踪 + 计划管理 |
|
|
|
| **tools/** | 与外部世界交互(文件、命令、网络、浏览器) |
|
|
|
-| **skill/** | 技能系统(Skills) |
|
|
|
-| **llm/** | LLM Provider 适配 |
|
|
|
+| **skill/** | 技能系统(Skills) |
|
|
|
+| **llm/** | LLM Provider 适配 |
|
|
|
|
|
|
### 三层记忆模型
|
|
|
|
|
|
@@ -93,9 +93,9 @@ agent/
|
|
|
▲
|
|
|
│ 归纳
|
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
|
-│ Layer 2: Experience(经验库) │
|
|
|
-│ - 数据库存储,条件 + 规则 + 证据 │
|
|
|
-│ - 向量检索,注入到 system prompt │
|
|
|
+│ Layer 2: Knowledge(知识库) │
|
|
|
+│ - 数据库存储,结构化知识 + 向量索引 │
|
|
|
+│ - 语义检索,按需注入到对话历史 │
|
|
|
└─────────────────────────────────────────────────────────────┘
|
|
|
▲
|
|
|
│ 提取
|
|
|
@@ -113,20 +113,20 @@ agent/
|
|
|
|
|
|
框架内部统一使用 OpenAI 兼容格式(`List[Dict]`)存储和传递消息。各 Provider 负责双向转换:
|
|
|
|
|
|
-| 方向 | 说明 |
|
|
|
-|------|------|
|
|
|
+| 方向 | 说明 |
|
|
|
+| --------------------- | ------------------------------------------------ |
|
|
|
| 入(LLM 响应 → 框架) | 提取 content、tool_calls、usage,转换为统一 Dict |
|
|
|
-| 出(框架 → LLM 请求) | OpenAI 格式消息列表 → 各 API 原生格式 |
|
|
|
+| 出(框架 → LLM 请求) | OpenAI 格式消息列表 → 各 API 原生格式 |
|
|
|
|
|
|
#### 工具消息分组
|
|
|
|
|
|
存储层每个 tool result 独立一条 Message(OpenAI 格式最大公约数)。各 Provider 在出方向按 API 要求自行分组:
|
|
|
|
|
|
-| Provider | 分组方式 |
|
|
|
-|----------|---------|
|
|
|
-| OpenRouter | 无需分组(OpenAI 原生支持独立 tool 消息) |
|
|
|
-| Yescode | `_convert_messages_to_anthropic` 合并连续 tool 消息为单个 user message |
|
|
|
-| Gemini | `_convert_messages_to_gemini` 通过 buffer 合并连续 tool 消息 |
|
|
|
+| Provider | 分组方式 |
|
|
|
+| ---------- | ---------------------------------------------------------------------- |
|
|
|
+| OpenRouter | 无需分组(OpenAI 原生支持独立 tool 消息) |
|
|
|
+| Yescode | `_convert_messages_to_anthropic` 合并连续 tool 消息为单个 user message |
|
|
|
+| Gemini | `_convert_messages_to_gemini` 通过 buffer 合并连续 tool 消息 |
|
|
|
|
|
|
#### 跨 Provider 续跑:tool_call_id 规范化
|
|
|
|
|
|
@@ -189,11 +189,11 @@ class RunConfig:
|
|
|
|
|
|
通过 RunConfig 参数自然区分,统一入口 `run(messages, config)`:
|
|
|
|
|
|
-| 模式 | trace_id | after_sequence | messages 含义 | API 端点 |
|
|
|
-|------|----------|---------------|--------------|----------|
|
|
|
-| 新建 | None | - | 初始任务消息 | `POST /api/traces` |
|
|
|
-| 续跑 | 已有 ID | None 或 == head | 追加到末尾的新消息 | `POST /api/traces/{id}/run` |
|
|
|
-| 回溯 | 已有 ID | 主路径上 < head | 在插入点之后追加的新消息 | `POST /api/traces/{id}/run` |
|
|
|
+| 模式 | trace_id | after_sequence | messages 含义 | API 端点 |
|
|
|
+| ---- | -------- | --------------- | ------------------------ | --------------------------- |
|
|
|
+| 新建 | None | - | 初始任务消息 | `POST /api/traces` |
|
|
|
+| 续跑 | 已有 ID | None 或 == head | 追加到末尾的新消息 | `POST /api/traces/{id}/run` |
|
|
|
+| 回溯 | 已有 ID | 主路径上 < head | 在插入点之后追加的新消息 | `POST /api/traces/{id}/run` |
|
|
|
|
|
|
Runner 根据 `after_sequence` 与当前 `head_sequence` 的关系自动判断行为,前端无需指定模式。
|
|
|
|
|
|
@@ -210,7 +210,7 @@ async def run(messages: List[Dict], config: RunConfig = None) -> AsyncIterator[U
|
|
|
|
|
|
# Phase 2: BUILD HISTORY
|
|
|
# 从 head_sequence 沿 parent chain 回溯构建主路径消息
|
|
|
- # 构建 system prompt(新建时注入 skills/experiences;续跑时复用已有)
|
|
|
+ # 构建 system prompt(新建时注入 skills;续跑时复用已有)
|
|
|
# 追加 input messages(设置 parent_sequence 指向当前 head)
|
|
|
history, sequence = await _build_history(trace, messages, config)
|
|
|
|
|
|
@@ -297,9 +297,9 @@ await runner.stop(trace_id)
|
|
|
|
|
|
修复策略:为每个缺失的 tool_result **插入合成的中断通知**(而非裁剪 assistant 消息):
|
|
|
|
|
|
-| 工具类型 | 合成 tool_result 内容 |
|
|
|
-|----------|---------------------|
|
|
|
-| 普通工具 | 简短中断提示,建议重新调用 |
|
|
|
+| 工具类型 | 合成 tool_result 内容 |
|
|
|
+| -------------- | ----------------------------------------------------------------------- |
|
|
|
+| 普通工具 | 简短中断提示,建议重新调用 |
|
|
|
| agent/evaluate | 结构化中断信息,包含 `sub_trace_id`、执行统计、`continue_from` 用法指引 |
|
|
|
|
|
|
agent 工具的合成结果对齐正常返回值格式(含 `sub_trace_id` 字段),主 Agent 可直接使用 `agent(task=..., continue_from=sub_trace_id)` 续跑被中断的子 Agent。合成消息持久化存储,确保幂等。
|
|
|
@@ -313,13 +313,13 @@ agent 工具的合成结果对齐正常返回值格式(含 `sub_trace_id` 字
|
|
|
|
|
|
#### 查询端点
|
|
|
|
|
|
-| 方法 | 路径 | 说明 |
|
|
|
-|------|------|------|
|
|
|
-| GET | `/api/traces` | 列出 Traces |
|
|
|
-| GET | `/api/traces/{id}` | 获取 Trace 详情(含 GoalTree、Sub-Traces) |
|
|
|
-| GET | `/api/traces/{id}/messages` | 获取 Messages(支持 mode=main_path/all) |
|
|
|
-| GET | `/api/traces/running` | 列出正在运行的 Trace |
|
|
|
-| WS | `/api/traces/{id}/watch` | 实时事件推送 |
|
|
|
+| 方法 | 路径 | 说明 |
|
|
|
+| ---- | --------------------------- | ------------------------------------------ |
|
|
|
+| GET | `/api/traces` | 列出 Traces |
|
|
|
+| GET | `/api/traces/{id}` | 获取 Trace 详情(含 GoalTree、Sub-Traces) |
|
|
|
+| GET | `/api/traces/{id}/messages` | 获取 Messages(支持 mode=main_path/all) |
|
|
|
+| GET | `/api/traces/running` | 列出正在运行的 Trace |
|
|
|
+| WS | `/api/traces/{id}/watch` | 实时事件推送 |
|
|
|
|
|
|
**实现**:`agent/trace/api.py`, `agent/trace/websocket.py`
|
|
|
|
|
|
@@ -327,12 +327,12 @@ agent 工具的合成结果对齐正常返回值格式(含 `sub_trace_id` 字
|
|
|
|
|
|
需在 `api_server.py` 中配置 Runner。执行在后台异步进行,通过 WebSocket 监听进度。
|
|
|
|
|
|
-| 方法 | 路径 | 说明 |
|
|
|
-|------|------|------|
|
|
|
-| POST | `/api/traces` | 新建 Trace 并执行 |
|
|
|
-| POST | `/api/traces/{id}/run` | 运行(统一续跑 + 回溯) |
|
|
|
-| POST | `/api/traces/{id}/stop` | 停止运行中的 Trace |
|
|
|
-| POST | `/api/traces/{id}/reflect` | 触发反思,从执行历史中提取经验 |
|
|
|
+| 方法 | 路径 | 说明 |
|
|
|
+| ---- | -------------------------- | --------------------------------------------- |
|
|
|
+| POST | `/api/traces` | 新建 Trace 并执行 |
|
|
|
+| POST | `/api/traces/{id}/run` | 运行(统一续跑 + 回溯) |
|
|
|
+| POST | `/api/traces/{id}/stop` | 停止运行中的 Trace |
|
|
|
+| POST | `/api/traces/{id}/reflect` | 触发反思,从执行历史中提取知识 |
|
|
|
| POST | `/api/traces/{id}/compact` | 触发压缩,通过侧分支多轮 agent 模式压缩上下文 |
|
|
|
|
|
|
```bash
|
|
|
@@ -356,7 +356,7 @@ curl -X POST http://localhost:8000/api/traces/{trace_id}/run \
|
|
|
# 停止
|
|
|
curl -X POST http://localhost:8000/api/traces/{trace_id}/stop
|
|
|
|
|
|
-# 反思:通过侧分支多轮 agent 模式提取经验
|
|
|
+# 反思:通过侧分支多轮 agent 模式提取知识
|
|
|
curl -X POST http://localhost:8000/api/traces/{trace_id}/reflect \
|
|
|
-d '{"focus": "为什么第三步选择了错误的方案"}'
|
|
|
|
|
|
@@ -368,14 +368,6 @@ curl -X POST http://localhost:8000/api/traces/{trace_id}/compact
|
|
|
|
|
|
**实现**:`agent/trace/run_api.py`
|
|
|
|
|
|
-#### 经验端点
|
|
|
-
|
|
|
-| 方法 | 路径 | 说明 |
|
|
|
-|------|------|------|
|
|
|
-| GET | `/api/experiences` | 读取经验文件内容 |
|
|
|
-
|
|
|
-**实现**:`agent/trace/run_api.py`
|
|
|
-
|
|
|
---
|
|
|
|
|
|
## 数据模型
|
|
|
@@ -466,10 +458,12 @@ class Goal:
|
|
|
```
|
|
|
|
|
|
**Goal 类型**:
|
|
|
+
|
|
|
- `normal` - 普通目标,由 Agent 直接执行
|
|
|
- `agent_call` - 通过 `agent`/`evaluate` 工具创建的目标,会启动 Sub-Trace
|
|
|
|
|
|
**agent_call 类型的 Goal**:
|
|
|
+
|
|
|
- 调用 `agent`/`evaluate` 工具时自动设置
|
|
|
- `agent_call_mode` 记录使用的模式(explore/delegate/evaluate)
|
|
|
- `sub_trace_ids` 记录创建的所有 Sub-Trace ID
|
|
|
@@ -477,6 +471,7 @@ class Goal:
|
|
|
- `summary` 包含格式化的汇总结果(explore 模式会汇总所有分支)
|
|
|
|
|
|
**Goal 操作**(通过 goal 工具):
|
|
|
+
|
|
|
- `add` - 添加顶层目标
|
|
|
- `under` - 在指定目标下添加子目标
|
|
|
- `after` - 在指定目标后添加兄弟目标
|
|
|
@@ -537,10 +532,12 @@ Rewind 到 3:3 → 6(parent=3) → 7 (新主路径,4-5 自动脱离)
|
|
|
**关键设计**:只要 `trace.head_sequence` 管理正确(始终指向主路径),`get_main_path_messages()` 自然返回主路径消息,侧分支消息通过 parent_sequence 链自动被跳过,无需额外过滤。
|
|
|
|
|
|
Message 提供格式转换方法:
|
|
|
+
|
|
|
- `to_llm_dict()` → OpenAI 格式 Dict(用于 LLM 调用)
|
|
|
- `from_llm_dict(d, trace_id, sequence, goal_id)` → 从 OpenAI 格式创建 Message
|
|
|
|
|
|
**侧分支字段**:
|
|
|
+
|
|
|
- `branch_type`: "compression" | "reflection" | None(主路径)
|
|
|
- `branch_id`: 同一侧分支的消息共享 branch_id
|
|
|
|
|
|
@@ -594,6 +591,7 @@ AGENT_PRESETS = {
|
|
|
**实现**:`agent/core/presets.py`
|
|
|
|
|
|
**System Prompt 构建优先级**(`agent/core/runner.py:_build_system_prompt`):
|
|
|
+
|
|
|
1. 消息中已有 system → 使用消息中的
|
|
|
2. `config.system_prompt` 显式指定 → 使用 config
|
|
|
3. `preset.system_prompt` 存在 → 使用 preset
|
|
|
@@ -602,6 +600,7 @@ AGENT_PRESETS = {
|
|
|
**用户自定义**:项目级配置文件(如 `examples/production/presets.json`)可通过 `load_presets_from_json()` 加载预设。支持 `system_prompt_file` 字段从 `.prompt` 文件加载完整 system prompt。
|
|
|
|
|
|
**示例**(`examples/production/presets.json`):
|
|
|
+
|
|
|
```json
|
|
|
{
|
|
|
"tool_research": {
|
|
|
@@ -614,6 +613,7 @@ AGENT_PRESETS = {
|
|
|
```
|
|
|
|
|
|
**加载方式**:
|
|
|
+
|
|
|
```python
|
|
|
from agent.core.presets import load_presets_from_json
|
|
|
|
|
|
@@ -621,6 +621,7 @@ load_presets_from_json("examples/production/presets.json")
|
|
|
```
|
|
|
|
|
|
**使用方式**:LLM 调用 `agent` 工具时指定 `agent_type` 参数:
|
|
|
+
|
|
|
```python
|
|
|
agent(task="调研视频生成工具", agent_type="tool_research")
|
|
|
```
|
|
|
@@ -638,10 +639,12 @@ agent(task="调研视频生成工具", agent_type="tool_research")
|
|
|
支持跨设备的 Agent 间持续对话,通过远程 Trace ID 实现:
|
|
|
|
|
|
**Trace ID 格式**:
|
|
|
+
|
|
|
- 本地 Trace:`abc-123`
|
|
|
- 远程 Trace:`agent://terminal-agent-456/abc-123`(协议 + Agent 地址 + 本地 ID)
|
|
|
|
|
|
**使用方式**:
|
|
|
+
|
|
|
```python
|
|
|
# 调用远程 Agent
|
|
|
result = agent(task="分析本地项目", agent_url="https://terminal-agent.local")
|
|
|
@@ -675,18 +678,21 @@ async def agent(
|
|
|
```
|
|
|
|
|
|
**参数**:
|
|
|
+
|
|
|
- `agent_type`: 子 Agent 类型,决定工具权限和默认 skills(对应 `AgentPreset` 名称)
|
|
|
- `skills`: 覆盖 preset 默认值,显式指定注入 system prompt 的 skill 列表
|
|
|
- `agent_url`: 远程 Agent 地址,用于跨设备调用(返回远程 Trace ID)
|
|
|
- `continue_from`: 支持本地或远程 Trace ID
|
|
|
|
|
|
**单任务(delegate)**:`task: str`
|
|
|
+
|
|
|
- 创建单个 Sub-Trace
|
|
|
- 完整工具权限(除 agent/evaluate 外,防止递归)
|
|
|
- 支持 `continue_from` 续跑已有 Sub-Trace(本地或远程)
|
|
|
- 支持 `messages` 预置上下文消息
|
|
|
|
|
|
**多任务(explore)**:`task: List[str]`
|
|
|
+
|
|
|
- 使用 `asyncio.gather()` 并行执行所有任务
|
|
|
- 每个任务创建独立的 Sub-Trace
|
|
|
- 只读工具权限(read_file, grep_content, glob_files, goal)
|
|
|
@@ -738,10 +744,10 @@ MessageContent = Union[str, List[Dict[str, str]]] # content 字段(文本
|
|
|
|
|
|
任务执行中与模型密切协作的实体(子 Agent 或人类),按 **与当前任务的关系** 分类,而非按 human/agent 分类:
|
|
|
|
|
|
-| | 持久存在(外部可查) | 任务内活跃(需要注入) |
|
|
|
-|---|---|---|
|
|
|
+| | 持久存在(外部可查) | 任务内活跃(需要注入) |
|
|
|
+| ----- | ------------------------ | ---------------------- |
|
|
|
| Agent | 专用 Agent(代码审查等) | 当前任务创建的子 Agent |
|
|
|
-| Human | 飞书通讯录 | 当前任务中正在对接的人 |
|
|
|
+| Human | 飞书通讯录 | 当前任务中正在对接的人 |
|
|
|
|
|
|
### 数据模型
|
|
|
|
|
|
@@ -763,6 +769,7 @@ MessageContent = Union[str, List[Dict[str, str]]] # content 字段(文本
|
|
|
|
|
|
```markdown
|
|
|
## Active Collaborators
|
|
|
+
|
|
|
- researcher [agent, completed]: 方案A最优
|
|
|
- 谭景玉 [human, waiting]: 已发送方案确认,等待回复
|
|
|
- coder [agent, running]: 正在实现特征提取模块
|
|
|
@@ -773,6 +780,7 @@ MessageContent = Union[str, List[Dict[str, str]]] # content 字段(文本
|
|
|
### 维护
|
|
|
|
|
|
各工具负责更新 collaborators 列表(通过 `context["store"]` 写入 trace.context):
|
|
|
+
|
|
|
- `agent` 工具:创建/续跑子 Agent 时更新
|
|
|
- `feishu` 工具:发送消息/收到回复时更新
|
|
|
- Runner 只负责读取和注入
|
|
|
@@ -1013,14 +1021,17 @@ async def receive_a2a_message(message: dict):
|
|
|
|
|
|
```markdown
|
|
|
## Current Plan
|
|
|
+
|
|
|
1. [in_progress] 分析代码架构
|
|
|
1.1. [completed] 读取项目结构
|
|
|
1.2. [in_progress] 分析核心模块
|
|
|
|
|
|
## Active Collaborators
|
|
|
+
|
|
|
- researcher [agent, completed]: 已完成调研
|
|
|
|
|
|
## Messages
|
|
|
+
|
|
|
💬 来自 code-reviewer 的 1 条新消息(使用 check_messages 工具查看)
|
|
|
```
|
|
|
|
|
|
@@ -1057,10 +1068,10 @@ def create_timer_hook(timer):
|
|
|
|
|
|
任务执行中与模型密切协作的实体(子 Agent 或人类),按 **与当前任务的关系** 分类,而非按 human/agent 分类:
|
|
|
|
|
|
-| | 持久存在(外部可查) | 任务内活跃(需要注入) |
|
|
|
-|---|---|---|
|
|
|
+| | 持久存在(外部可查) | 任务内活跃(需要注入) |
|
|
|
+| ----- | ------------------------ | ---------------------- |
|
|
|
| Agent | 专用 Agent(代码审查等) | 当前任务创建的子 Agent |
|
|
|
-| Human | 飞书通讯录 | 当前任务中正在对接的人 |
|
|
|
+| Human | 飞书通讯录 | 当前任务中正在对接的人 |
|
|
|
|
|
|
### 数据模型
|
|
|
|
|
|
@@ -1082,6 +1093,7 @@ def create_timer_hook(timer):
|
|
|
|
|
|
```markdown
|
|
|
## Active Collaborators
|
|
|
+
|
|
|
- researcher [agent, completed]: 方案A最优
|
|
|
- 谭景玉 [human, waiting]: 已发送方案确认,等待回复
|
|
|
- coder [agent, running]: 正在实现特征提取模块
|
|
|
@@ -1092,6 +1104,7 @@ def create_timer_hook(timer):
|
|
|
### 维护
|
|
|
|
|
|
各工具负责更新 collaborators 列表(通过 `context["store"]` 写入 trace.context):
|
|
|
+
|
|
|
- `agent` 工具:创建/续跑子 Agent 时更新
|
|
|
- `feishu` 工具:发送消息/收到回复时更新
|
|
|
- Runner 只负责读取和注入
|
|
|
@@ -1116,21 +1129,21 @@ async def my_tool(arg: str, ctx: ToolContext) -> ToolResult:
|
|
|
)
|
|
|
```
|
|
|
|
|
|
-| 类型 | 作用 |
|
|
|
-|------|------|
|
|
|
-| `@tool` | 装饰器,自动注册工具并生成 Schema |
|
|
|
-| `ToolResult` | 工具执行结果,支持双层记忆 |
|
|
|
-| `ToolContext` | 工具执行上下文,依赖注入 |
|
|
|
+| 类型 | 作用 |
|
|
|
+| ------------- | --------------------------------- |
|
|
|
+| `@tool` | 装饰器,自动注册工具并生成 Schema |
|
|
|
+| `ToolResult` | 工具执行结果,支持双层记忆 |
|
|
|
+| `ToolContext` | 工具执行上下文,依赖注入 |
|
|
|
|
|
|
### 工具分类
|
|
|
|
|
|
-| 目录 | 工具 | 说明 |
|
|
|
-|-----|------|------|
|
|
|
-| `trace/` | goal | Agent 内部计划管理 |
|
|
|
-| `builtin/` | agent, evaluate | 子 Agent 创建与评估 |
|
|
|
-| `builtin/file/` | read, write, edit, glob, grep | 文件操作 |
|
|
|
-| `builtin/browser/` | browser actions | 浏览器自动化 |
|
|
|
-| `builtin/` | bash, sandbox, search, webfetch, skill, ask_human | 其他工具 |
|
|
|
+| 目录 | 工具 | 说明 |
|
|
|
+| ------------------ | ------------------------------------------------- | ------------------- |
|
|
|
+| `trace/` | goal | Agent 内部计划管理 |
|
|
|
+| `builtin/` | agent, evaluate | 子 Agent 创建与评估 |
|
|
|
+| `builtin/file/` | read, write, edit, glob, grep | 文件操作 |
|
|
|
+| `builtin/browser/` | browser actions | 浏览器自动化 |
|
|
|
+| `builtin/` | bash, sandbox, search, webfetch, skill, ask_human | 其他工具 |
|
|
|
|
|
|
### 双层记忆管理
|
|
|
|
|
|
@@ -1152,11 +1165,11 @@ ToolResult(
|
|
|
|
|
|
### 分类
|
|
|
|
|
|
-| 类型 | 加载位置 | 加载时机 |
|
|
|
-|------|---------|---------|
|
|
|
-| **内置 Skill** | System Prompt | Agent 启动时自动注入 |
|
|
|
+| 类型 | 加载位置 | 加载时机 |
|
|
|
+| -------------- | ------------- | ------------------------------------------ |
|
|
|
+| **内置 Skill** | System Prompt | Agent 启动时自动注入 |
|
|
|
| **项目 Skill** | System Prompt | Agent 启动时按 preset/call-site 过滤后注入 |
|
|
|
-| **普通 Skill** | 对话消息 | 模型调用 `skill` 工具时 |
|
|
|
+| **普通 Skill** | 对话消息 | 模型调用 `skill` 工具时 |
|
|
|
|
|
|
### 目录结构
|
|
|
|
|
|
@@ -1178,6 +1191,7 @@ agent/skill/skills/ # 内置 Skills(始终加载)
|
|
|
3. `None`(加载全部,向后兼容)
|
|
|
|
|
|
示例:调用子 Agent 时只注入解构相关 skill:
|
|
|
+
|
|
|
```python
|
|
|
agent(task="...", agent_type="deconstruct", skills=["planning", "deconstruct"])
|
|
|
```
|
|
|
@@ -1188,88 +1202,74 @@ agent(task="...", agent_type="deconstruct", skills=["planning", "deconstruct"])
|
|
|
|
|
|
---
|
|
|
|
|
|
-## Experiences 系统
|
|
|
+## Knowledge 系统
|
|
|
|
|
|
-从执行历史中提取的经验规则,用于指导未来任务。
|
|
|
+从执行历史中提取的结构化知识,通过 KnowHub 服务管理,用于指导未来任务。
|
|
|
|
|
|
-### 存储规范
|
|
|
+### 存储架构
|
|
|
|
|
|
-经验以 Markdown 文件存储(默认 `./.cache/experiences.md`),人类可读、可编辑、可版本控制。
|
|
|
+知识存储在独立的 KnowHub 服务中(数据库 + 向量索引),支持:
|
|
|
+- 结构化存储(类型、标签、元数据)
|
|
|
+- 向量检索(语义相似度匹配)
|
|
|
+- 多租户隔离(owner、scopes)
|
|
|
+- 版本管理(created_at、updated_at)
|
|
|
|
|
|
-文件格式:
|
|
|
+**实现**:独立的 KnowHub Server(HTTP API)
|
|
|
|
|
|
-```markdown
|
|
|
----
|
|
|
-id: ex_001
|
|
|
-trace_id: trace-xxx
|
|
|
-category: tool_usage
|
|
|
-tags: {state: ["large_file", "dirty_repo"], intent: ["batch_edit", "safe_modify"]}
|
|
|
-metrics: {helpful: 12, harmful: 0}
|
|
|
-created_at: 2026-02-12 15:30
|
|
|
----
|
|
|
+### 反思机制(Reflect)
|
|
|
|
|
|
----
|
|
|
-id: ex_002
|
|
|
-...
|
|
|
-```
|
|
|
----
|
|
|
+通过 `POST /api/traces/{id}/reflect` 触发,旨在将原始执行历史提炼为可复用的知识。
|
|
|
|
|
|
+**流程**:
|
|
|
+1. **分叉反思**:在 trace 末尾进入 `reflection` 侧分支
|
|
|
+2. **多轮推理**:LLM 可调用 `knowledge_search`、`knowledge_save`、`resource_save` 等工具
|
|
|
+3. **结构化保存**:通过 `knowledge_save` 工具将知识保存到 KnowHub
|
|
|
|
|
|
-### 反思机制(Reflect)
|
|
|
+**实现**:`agent/trace/run_api.py:reflect_trace`
|
|
|
+
|
|
|
+### 知识工具
|
|
|
|
|
|
-通过 POST /api/traces/{id}/reflect 触发,旨在将原始执行历史提炼为可复用的知识。
|
|
|
- 1. 分叉反思:在 trace 末尾追加 user message(含反思与打标 Prompt),作为侧枝执行。
|
|
|
- 2. 结构化生成:
|
|
|
- ·归类:将经验分配至 tool_usage(工具)、logic_flow(逻辑)、environment(环境)等。
|
|
|
- ·打标:提取 state(环境状态)与 intent(用户意图)语义标签。
|
|
|
- ·量化:初始 helpful 设为 1。
|
|
|
- 3. 持久化:将带有元数据的 Markdown 块追加至 experiences.md。
|
|
|
-
|
|
|
-实现:agent/trace/run_api.py:reflect_trace
|
|
|
-
|
|
|
-### 语义注入与匹配流程
|
|
|
-新建 Trace 时,Runner 采用“分析-检索-注入”三阶段策略,实现精准经验推荐。
|
|
|
- 1. 意图预分析
|
|
|
- Runner 调用 utility_llm 对初始任务进行语义提取:
|
|
|
- -输入:"优化这个项目的 Docker 构建速度"
|
|
|
- -输出:{state: ["docker", "ci"], intent: ["optimization"]}
|
|
|
- 2. 语义检索
|
|
|
- 在 _load_experiences 中根据标签进行语义匹配(优先匹配 intent,其次是 state),筛选出相关度最高的 Top-K 条经验。
|
|
|
- 3. 精准注入
|
|
|
- 将匹配到的经验注入第一条 user message 末尾:
|
|
|
+Agent 可通过以下工具与知识库交互:
|
|
|
+
|
|
|
+**`knowledge_search`**:语义检索相关知识
|
|
|
```python
|
|
|
-# _build_history 中(仅新建模式):
|
|
|
-if not config.trace_id:
|
|
|
- relevant_ex = self.experience_retriever.search(task_tags)
|
|
|
- if relevant_ex:
|
|
|
- formatted_ex = "\n".join([f"- [{e.id}] {e.content} (Helpful: {e.helpful})" for e in relevant_ex])
|
|
|
- first_user_msg["content"] += f"\n\n## 参考经验\n\n{formatted_ex}"
|
|
|
+@tool
|
|
|
+async def knowledge_search(
|
|
|
+ query: str,
|
|
|
+ top_k: int = 5,
|
|
|
+ min_score: int = 3,
|
|
|
+ types: Optional[List[str]] = None,
|
|
|
+ owner: Optional[str] = None,
|
|
|
+) -> ToolResult:
|
|
|
+ “””从知识库中检索相关知识”””
|
|
|
```
|
|
|
-实现:agent/core/runner.py:AgentRunner._build_history
|
|
|
|
|
|
-### 经验获取工具
|
|
|
-不再仅限于启动时自动注入,而是通过内置工具供 Agent 在需要时主动调用。当执行结果不符合预期或进入未知领域时,Agent 应优先使用此工具。
|
|
|
-工具定义:
|
|
|
+**`knowledge_save`**:保存新知识
|
|
|
+```python
|
|
|
+@tool
|
|
|
+async def knowledge_save(
|
|
|
+ content: str,
|
|
|
+ type: str,
|
|
|
+ tags: Optional[Dict[str, str]] = None,
|
|
|
+ scopes: Optional[List[str]] = None,
|
|
|
+) -> ToolResult:
|
|
|
+ “””将知识保存到知识库”””
|
|
|
+```
|
|
|
|
|
|
+**`resource_save`**:保存资源文件(代码片段、配置等)
|
|
|
```python
|
|
|
-@tool(description="根据当前任务状态和意图,从经验库中检索相关的历史经验")
|
|
|
-async def get_experience(
|
|
|
- intent: Optional[str] = None,
|
|
|
- state: Optional[str] = None
|
|
|
-) -> Dict[str, Any]:
|
|
|
- """
|
|
|
- 参数:
|
|
|
- intent: 想要达成的目标意图 (如 "optimization", "debug")
|
|
|
- state: 当前环境或遇到的问题状态 (如 "docker_build_fail", "permission_denied")
|
|
|
- """
|
|
|
+@tool
|
|
|
+async def resource_save(
|
|
|
+ content: str,
|
|
|
+ filename: str,
|
|
|
+ description: Optional[str] = None,
|
|
|
+) -> ToolResult:
|
|
|
+ “””保存资源文件到知识库”””
|
|
|
```
|
|
|
-实现: agent/tools/builtin/experience.py
|
|
|
|
|
|
-- 语义匹配与应用流程
|
|
|
- 当 Agent 调用 get_experience 时,系统执行以下逻辑:
|
|
|
- 1. 语义检索:根据传入的 intent 或 state 标签,在 experiences.md 中进行匹配。匹配权重:intent > state > helpful 评分。
|
|
|
- 2. 动态注入:工具返回匹配到的 Top-K 条经验(含 ID 和内容)。
|
|
|
- 3. 策略应用:Agent 接收到工具返回的经验后,需在后续 thought 中声明所选用的策略 ID(如 [ex_001]),并据此调整 goal_tree 或工具调用序列。
|
|
|
+**实现**:`agent/tools/builtin/knowledge.py`
|
|
|
+
|
|
|
+---
|
|
|
|
|
|
## Context 压缩
|
|
|
|
|
|
@@ -1277,10 +1277,10 @@ async def get_experience(
|
|
|
|
|
|
Context 压缩分为两级,通过 `RunConfig` 中的 `goal_compression` 参数控制 Level 1 的行为:
|
|
|
|
|
|
-| 模式 | 值 | Level 1 行为 | Level 2 行为 |
|
|
|
-|------|-----|-------------|-------------|
|
|
|
-| 不压缩 | `"none"` | 跳过 Level 1 | 超限时直接进入 Level 2 |
|
|
|
-| 完成后压缩 | `"on_complete"` | 每个 goal 完成时立刻压缩该 goal 的消息 | 超限时进入 Level 2 |
|
|
|
+| 模式 | 值 | Level 1 行为 | Level 2 行为 |
|
|
|
+| ---------- | --------------- | -------------------------------------- | ------------------------------ |
|
|
|
+| 不压缩 | `"none"` | 跳过 Level 1 | 超限时直接进入 Level 2 |
|
|
|
+| 完成后压缩 | `"on_complete"` | 每个 goal 完成时立刻压缩该 goal 的消息 | 超限时进入 Level 2 |
|
|
|
| 超长时压缩 | `"on_overflow"` | 超限时遍历所有 completed goal 逐个压缩 | Level 1 后仍超限则进入 Level 2 |
|
|
|
|
|
|
默认值:`"on_overflow"`
|
|
|
@@ -1333,10 +1333,11 @@ RunConfig(
|
|
|
|
|
|
通过侧分支队列机制执行,`force_side_branch` 为列表类型:
|
|
|
|
|
|
-1. **反思**(可选,由 `knowledge.enable_extraction` 控制):进入 `reflection` 侧分支,LLM 可多轮调用 knowledge_search、resource_save、knowledge_save 等工具提取经验
|
|
|
+1. **反思**(可选,由 `knowledge.enable_extraction` 控制):进入 `reflection` 侧分支,LLM 可多轮调用 knowledge_search、resource_save、knowledge_save 等工具提取知识
|
|
|
2. **压缩**:进入 `compression` 侧分支,LLM 生成 summary
|
|
|
|
|
|
侧分支队列示例:
|
|
|
+
|
|
|
- 启用知识提取:`force_side_branch = ["reflection", "compression"]`
|
|
|
- 仅压缩:`force_side_branch = ["compression"]`
|
|
|
|
|
|
@@ -1357,6 +1358,7 @@ RunConfig(
|
|
|
### GoalTree 双视图
|
|
|
|
|
|
`to_prompt()` 支持两种模式:
|
|
|
+
|
|
|
- `include_summary=False`(默认):精简视图,用于日常周期性注入
|
|
|
- `include_summary=True`:含所有 completed goals 的 summary,用于 Level 2 压缩时提供上下文
|
|
|
|
|
|
@@ -1389,6 +1391,7 @@ class TraceStore(Protocol):
|
|
|
`get_main_path_messages` 从 `head_sequence` 沿 `parent_sequence` 链回溯,返回主路径上的有序消息列表。
|
|
|
|
|
|
**实现**:
|
|
|
+
|
|
|
- 协议定义:`agent/trace/protocols.py`
|
|
|
- 本地存储:`agent/trace/store.py:FileSystemTraceStore`
|
|
|
- 远程存储:`agent/trace/remote_store.py:RemoteTraceStore`(规划中)
|
|
|
@@ -1398,12 +1401,13 @@ class TraceStore(Protocol):
|
|
|
|
|
|
**HybridTraceStore** 根据 Trace ID 自动路由到本地或远程存储:
|
|
|
|
|
|
-| Trace ID 格式 | 存储位置 | 访问方式 |
|
|
|
-|--------------|---------|---------|
|
|
|
-| `abc-123` | 本地文件系统 | `FileSystemTraceStore` |
|
|
|
-| `agent://host/abc-123` | 远程 Agent | HTTP API(`RemoteTraceStore`) |
|
|
|
+| Trace ID 格式 | 存储位置 | 访问方式 |
|
|
|
+| ---------------------- | ------------ | ------------------------------ |
|
|
|
+| `abc-123` | 本地文件系统 | `FileSystemTraceStore` |
|
|
|
+| `agent://host/abc-123` | 远程 Agent | HTTP API(`RemoteTraceStore`) |
|
|
|
|
|
|
**RemoteTraceStore** 通过 HTTP API 访问远程 Trace:
|
|
|
+
|
|
|
- `GET /api/traces/{trace_id}` - 获取 Trace 元数据
|
|
|
- `GET /api/traces/{trace_id}/messages` - 获取消息历史
|
|
|
- `POST /api/traces/{trace_id}/run` - 续跑(追加消息并执行)
|
|
|
@@ -1429,17 +1433,20 @@ class TraceStore(Protocol):
|
|
|
```
|
|
|
|
|
|
**events.jsonl 说明**:
|
|
|
+
|
|
|
- 记录 Trace 执行过程中的关键事件
|
|
|
- 每行一个 JSON 对象,包含 event_id、event 类型、时间戳等
|
|
|
- 主要事件类型:goal_added, goal_updated, sub_trace_started, sub_trace_completed, rewind
|
|
|
- 用于实时监控和历史回放
|
|
|
|
|
|
**Sub-Trace 目录命名**:
|
|
|
+
|
|
|
- Explore: `{parent}@explore-{序号:03d}-{timestamp}-001`
|
|
|
- Delegate: `{parent}@delegate-{timestamp}-001`
|
|
|
- Evaluate: `{parent}@evaluate-{timestamp}-001`
|
|
|
|
|
|
**meta.json 示例**:
|
|
|
+
|
|
|
```json
|
|
|
{
|
|
|
"trace_id": "0415dc38-...",
|
|
|
@@ -1479,24 +1486,24 @@ class TraceStore(Protocol):
|
|
|
|
|
|
## 相关文档
|
|
|
|
|
|
-| 文档 | 内容 |
|
|
|
-|-----|------|
|
|
|
-| [Context 管理](./context-management.md) | Goals、压缩、Plan 注入策略 |
|
|
|
-| [工具系统](../agent/docs/tools.md) | 工具定义、注册、双层记忆 |
|
|
|
-| [Skills 指南](../agent/docs/skills.md) | Skill 分类、编写、加载 |
|
|
|
-| [多模态支持](../agent/docs/multimodal.md) | 图片、PDF 处理 |
|
|
|
-| [知识管理](./knowledge.md) | 知识结构、检索、提取机制 |
|
|
|
-| [Scope 设计](./scope-design.md) | 知识可见性和权限控制 |
|
|
|
-| [Agent 设计决策](../agent/docs/decisions.md) | Agent Core 架构决策记录 |
|
|
|
-| [Gateway 设计决策](../gateway/docs/decisions.md) | Gateway 架构决策记录 |
|
|
|
-| [组织级概览](../gateway/docs/enterprise/overview.md) | 组织级 Agent 系统架构和规划 |
|
|
|
-| [Enterprise 实现](../gateway/docs/enterprise/implementation.md) | 认证、审计、多租户技术实现 |
|
|
|
-| [测试指南](./testing.md) | 测试策略和命令 |
|
|
|
-| [A2A 协议调研](./research/a2a-protocols.md) | 行业 A2A 通信协议和框架对比 |
|
|
|
-| [A2A 跨设备通信](./research/a2a-cross-device.md) | 跨设备 Agent 通信方案(内部) |
|
|
|
-| [A2A Trace 存储](./research/a2a-trace-storage.md) | 跨设备 Trace 存储方案详细设计 |
|
|
|
-| [MAMP 协议](./research/a2a-mamp-protocol.md) | 与外部 Agent 系统的通用交互协议 |
|
|
|
-| [A2A IM 系统](./a2a-im.md) | Agent 即时通讯系统架构和实现 |
|
|
|
-| [Gateway 架构](../gateway/docs/architecture.md) | Gateway 三层架构和设计决策 |
|
|
|
-| [Gateway 部署](../gateway/docs/deployment.md) | Gateway 部署模式和配置 |
|
|
|
-| [Gateway API](../gateway/docs/api.md) | Gateway API 完整参考 |
|
|
|
+| 文档 | 内容 |
|
|
|
+| --------------------------------------------------------------- | ------------------------------- |
|
|
|
+| [Context 管理](./context-management.md) | Goals、压缩、Plan 注入策略 |
|
|
|
+| [工具系统](../agent/docs/tools.md) | 工具定义、注册、双层记忆 |
|
|
|
+| [Skills 指南](../agent/docs/skills.md) | Skill 分类、编写、加载 |
|
|
|
+| [多模态支持](../agent/docs/multimodal.md) | 图片、PDF 处理 |
|
|
|
+| [知识管理](./knowledge.md) | 知识结构、检索、提取机制 |
|
|
|
+| [Scope 设计](./scope-design.md) | 知识可见性和权限控制 |
|
|
|
+| [Agent 设计决策](../agent/docs/decisions.md) | Agent Core 架构决策记录 |
|
|
|
+| [Gateway 设计决策](../gateway/docs/decisions.md) | Gateway 架构决策记录 |
|
|
|
+| [组织级概览](../gateway/docs/enterprise/overview.md) | 组织级 Agent 系统架构和规划 |
|
|
|
+| [Enterprise 实现](../gateway/docs/enterprise/implementation.md) | 认证、审计、多租户技术实现 |
|
|
|
+| [测试指南](./testing.md) | 测试策略和命令 |
|
|
|
+| [A2A 协议调研](./research/a2a-protocols.md) | 行业 A2A 通信协议和框架对比 |
|
|
|
+| [A2A 跨设备通信](./research/a2a-cross-device.md) | 跨设备 Agent 通信方案(内部) |
|
|
|
+| [A2A Trace 存储](./research/a2a-trace-storage.md) | 跨设备 Trace 存储方案详细设计 |
|
|
|
+| [MAMP 协议](./research/a2a-mamp-protocol.md) | 与外部 Agent 系统的通用交互协议 |
|
|
|
+| [A2A IM 系统](./a2a-im.md) | Agent 即时通讯系统架构和实现 |
|
|
|
+| [Gateway 架构](../gateway/docs/architecture.md) | Gateway 三层架构和设计决策 |
|
|
|
+| [Gateway 部署](../gateway/docs/deployment.md) | Gateway 部署模式和配置 |
|
|
|
+| [Gateway API](../gateway/docs/api.md) | Gateway API 完整参考 |
|