766 lines
34 KiB
Markdown
766 lines
34 KiB
Markdown
---
|
||
date: 2026-06-09
|
||
deepened: 2026-06-09
|
||
status: active
|
||
origin: docs/brainstorms/2026-06-09-agentkit-capability-matrix/requirements.md
|
||
---
|
||
|
||
## Summary
|
||
|
||
基于内核+插件架构，为 AgentKit 构建 7 项企业级能力：自主闭环执行引擎（内核）、Skill 标准规范升级、知识库与 RAG 增强、智能终端交互、Computer Use 集成、可视化 Workflow、自进化经验积累。分 6 个阶段交付，先建内核再逐步接入插件能力，最终通过端到端企业场景验证。
|
||
|
||
## Problem Frame
|
||
|
||
企业想用 AI Agent 但不会落地。AgentKit 已具备 Skill/ReAct/Pipeline/RAG/Shell 等基础能力，但缺少自主闭环执行、Computer Use、可视化 Workflow、任务经验积累等高级能力，且各能力之间缺乏统一调度中枢。需要以自主闭环执行引擎为内核，其他能力作为 Skill 插件接入，形成企业综合门户。
|
||
|
||
---
|
||
|
||
## Key Technical Decisions
|
||
|
||
**KTD-1. GoalPlanner 包装 Orchestrator._decompose_task()，而非独立实现**
|
||
|
||
现有 `Orchestrator._decompose_task()`（`src/agentkit/core/orchestrator.py`）已实现 LLM 驱动任务分解 + `_build_parallel_groups()` 并行组构建 + 单任务 fallback。GoalPlanner 作为前置增强层包装此方法：先通过结构化目标分解（规则/模板）生成初始方案，再让 LLM 细化调整；如果 GoalPlanner 返回了有效方案可直接跳过 LLM 调用。保持 fallback 机制不变，确保向后兼容。PlanExecutor 同理扩展 `Orchestrator.execute()`，注入执行策略，保留默认 `_execute_plan` 作为 fallback。
|
||
|
||
**KTD-2. 经验库使用 PostgreSQL + pgvector 混合存储**
|
||
|
||
结构化字段（task_type, outcome, duration）存 PostgreSQL 表，语义向量存 pgvector，全文检索用 tsvector。与现有 `EpisodicMemory` 共享基础设施，无需引入新依赖（ChromaDB/FAISS）。
|
||
|
||
**KTD-3. Computer Use 作为 Tool 插件集成**
|
||
|
||
新增 `ComputerUseTool`（继承 `Tool` 基类），内部调用 Anthropic Computer Use API。与 `ShellTool` 形成降级链：ComputerUseTool 失败 → ShellTool/API → AskHumanTool。符合 Skill 插件架构，无需修改核心引擎。
|
||
|
||
**KTD-4. Vue Flow 作为 Workflow 可视化编辑器**
|
||
|
||
Vue Flow 是 Vue3 原生组件，轻量（~60KB gzip），DAG 天然支持，自定义节点丰富。与现有 `PipelineEngine` 的 DAG 模型完美对应。Vue Flow JSON 可直接映射为 `PipelineStage` 配置。
|
||
|
||
**KTD-5. 智能终端增强现有 ShellTool**
|
||
|
||
在现有 `ShellTool` 基础上增加 `TerminalSession`（会话状态管理）和 `PTYSession`（交互式命令支持），而非替换。保持向后兼容，新功能通过配置开关启用。
|
||
|
||
**KTD-6. 前端独立 SPA，通过 API 与后端交互**
|
||
|
||
Vue3 前端作为独立 SPA，通过 FastAPI REST API + WebSocket 与后端通信。前端代码放在 `src/agentkit/server/frontend/` 目录，构建产物输出到 `src/agentkit/server/static/`。与现有 Server 架构无缝集成。
|
||
|
||
**KTD-7. KBAdapter 使用独立 KnowledgeBase 协议，不直接实现 Memory 接口**
|
||
|
||
Memory 接口的 `retrieve(key)`/`delete(key)` 是精确 key-value 语义，与知识库的语义检索模型不匹配。创建独立的 `KnowledgeBase` 协议（`ingest`/`query`/`delete_by_id`/`list_sources`/`health_check`），`SemanticMemory` 内部组合使用 `KnowledgeBase`，而非强制适配。这避免了 `retrieve(key)` 的人为映射和性能损失。
|
||
|
||
**KTD-8. PipelineStage 扩展 type/config 字段，WorkflowDefinition 继承 Pipeline**
|
||
|
||
现有 `PipelineStage` 没有 `type` 字段，`action` 隐含类型语义。新增 `type: str = "skill"`（默认值不破坏现有数据）和 `config: dict = {}`（类型特定配置）。`WorkflowDefinition` 继承 `Pipeline`（而非 `PipelineStage`），新增 `workflow_id`/`triggers`/`variables_schema`/`output_schema` 字段。
|
||
|
||
---
|
||
|
||
## High-Level Technical Design
|
||
|
||
```mermaid
|
||
flowchart TB
|
||
subgraph Portal["企业 Agent 门户 (Vue3 SPA)"]
|
||
Chat["统一对话界面"]
|
||
WF["Workflow 编辑器"]
|
||
KB["知识库管理"]
|
||
Term["智能终端"]
|
||
CU["Computer Use"]
|
||
EVO["自进化仪表盘"]
|
||
end
|
||
|
||
subgraph Kernel["自主闭环执行引擎"]
|
||
GP["GoalPlanner<br/>目标→计划"]
|
||
PE["PlanExecutor<br/>并行执行"]
|
||
PC["PlanChecker<br/>检查+复盘"]
|
||
end
|
||
|
||
subgraph Plugins["Skill 插件"]
|
||
RAG["RAG Skill<br/>本地+外部"]
|
||
ST["TerminalSkill<br/>智能终端"]
|
||
CUT["ComputerUseSkill<br/>UI自动化"]
|
||
end
|
||
|
||
subgraph Foundation["现有基础设施"]
|
||
RE["ReActEngine"]
|
||
ORC["Orchestrator"]
|
||
PL["PipelineEngine"]
|
||
SR["SkillRegistry"]
|
||
TR["ToolRegistry"]
|
||
MR["MemoryRetriever"]
|
||
ES["ExperienceStore<br/>(新增)"]
|
||
end
|
||
|
||
Chat --> GP
|
||
GP --> PE
|
||
PE --> PC
|
||
PC --> ES
|
||
|
||
PE --> RAG
|
||
PE --> ST
|
||
PE --> CUT
|
||
|
||
RAG --> MR
|
||
ST --> TR
|
||
CUT --> TR
|
||
PE --> ORC
|
||
PE --> PL
|
||
GP --> SR
|
||
|
||
WF --> PL
|
||
EVO --> ES
|
||
```
|
||
|
||
---
|
||
|
||
## Requirements Traceability
|
||
|
||
| Origin R-ID | Plan Coverage |
|
||
|---|---|
|
||
| R1-R6 | U1 (GoalPlanner), U2 (PlanExecutor), U3 (PlanChecker) |
|
||
| R7-R10 | U4 (Skill 标准规范升级) |
|
||
| R11-R14 | U9 (本地文档摄取), U10 (外部知识库适配器), U11 (多源 RAG) |
|
||
| R15-R18 | U8 (智能终端交互) |
|
||
| R19-R22 | U12 (Computer Use 集成) |
|
||
| R24-R28 | U14 (Workflow 可视化编辑器) |
|
||
| R29-R33 | U5 (ExperienceStore), U6 (PitfallDetector), U7 (PathOptimizer) |
|
||
| R34 | U13a (对话界面与路由) |
|
||
| R35 | U13b (管理页面) |
|
||
| R36 | U13c (自进化仪表盘) |
|
||
|
||
---
|
||
|
||
## Implementation Units
|
||
|
||
### Phase 1: 核心内核与经验基础
|
||
|
||
### U1. GoalPlanner — 目标分析与计划生成
|
||
|
||
**Goal:** 用户给定自然语言目标后，自动生成结构化执行计划，包含任务拆解、依赖关系、并行度识别。
|
||
|
||
**Requirements:** R1, R2
|
||
|
||
**Dependencies:** 无
|
||
|
||
**Files:**
|
||
- `src/agentkit/core/goal_planner.py` (新建)
|
||
- `src/agentkit/core/plan_schema.py` (新建)
|
||
- `src/agentkit/core/orchestrator.py` (修改 — 增加 GoalPlanner 分支)
|
||
- `tests/unit/core/test_goal_planner.py` (新建)
|
||
|
||
**Approach:**
|
||
- 新增 `GoalPlanner` 类，包装 `Orchestrator._decompose_task()` 作为前置增强层（见 KTD-1）
|
||
- `GoalPlanner.generate_plan(goal, context, available_skills)` → `ExecutionPlan`
|
||
- 执行流程：GoalPlanner 先通过结构化目标分解（规则/模板）生成初始方案 → 如果有效则跳过 LLM 调用 → 否则将初始方案作为上下文注入 `_decompose_task()` 的 LLM prompt → LLM 细化调整
|
||
- `ExecutionPlan` 包含 `PlanStep` 列表，每个 step 有 name/description/dependencies/parallel_group/required_skills
|
||
- 依赖识别：复用 `_build_parallel_groups()` 的拓扑排序逻辑
|
||
- 人工确认：`ExecutionPlan` 序列化为可读格式，通过 `AskHumanTool` 请求确认/修改
|
||
- 修改 `Orchestrator._decompose_task()`：增加 `if self._goal_planner:` 分支
|
||
|
||
**Patterns to follow:** `Orchestrator._decompose_task()` 的 LLM 调用模式（`src/agentkit/core/orchestrator.py`）
|
||
|
||
**Test scenarios:**
|
||
- 简单目标（单步任务）→ 生成单步计划
|
||
- 复杂目标（多步任务）→ 生成多步计划，正确识别依赖和并行关系
|
||
- 无可用 Skill 的目标 → 计划标注能力缺口，请求人工介入
|
||
- 用户修改计划 → 更新后重新验证依赖关系
|
||
- Covers AE1: 3 个竞品调研自动识别为并行步骤
|
||
|
||
**Verification:** `GoalPlanner` 能将"调研 3 个竞品 SEO 策略并生成对比报告"分解为包含并行步骤的结构化计划
|
||
|
||
### U2. PlanExecutor — 计划执行与并行调度
|
||
|
||
**Goal:** 按确认后的 ExecutionPlan 执行，自动并行调度无依赖步骤，支持执行中调整。
|
||
|
||
**Requirements:** R3, R5
|
||
|
||
**Dependencies:** U1
|
||
|
||
**Files:**
|
||
- `src/agentkit/core/plan_executor.py` (新建)
|
||
- `tests/unit/core/test_plan_executor.py` (新建)
|
||
|
||
**Approach:**
|
||
- 新增 `PlanExecutor` 类，扩展 `Orchestrator.execute()` 的执行策略（见 KTD-1）
|
||
- 在 `Orchestrator.execute()` 中注入 PlanExecutor：`if self._plan_executor: await self._plan_executor.execute(plan, task) else: await self._execute_plan(plan, task)`
|
||
- 按 `parallel_group` 分组执行：复用 `_execute_plan()` 的 `asyncio.gather` 并行模式
|
||
- 执行状态机：PENDING → RUNNING → COMPLETED/FAILED → CHECKING → RETRYING
|
||
- 失败处理：检查步骤失败时，根据失败类型决定重试/调整计划/请求人工
|
||
- 与 `AgentPool` 集成：每个步骤通过 `AgentPool.create_agent_from_skill()` 创建 Agent 执行
|
||
- 兼容现有的 `subtask_results` 累积模式
|
||
|
||
**Patterns to follow:** `Orchestrator.execute()` 的并行组执行模式（`src/agentkit/core/orchestrator.py`）
|
||
|
||
**Test scenarios:**
|
||
- 3 个并行步骤全部成功 → 结果正确汇总
|
||
- 并行步骤中 1 个失败 → 其他步骤继续，失败步骤进入检查
|
||
- 步骤失败后自动重试成功
|
||
- 步骤失败后调整计划（跳过/替换）继续执行
|
||
- 执行中请求人工介入后继续
|
||
|
||
**Verification:** PlanExecutor 能并行执行无依赖步骤，失败步骤正确处理
|
||
|
||
### U3. PlanChecker — 检查与复盘闭环
|
||
|
||
**Goal:** 每步执行后检查产出质量，全部完成后复盘总结并写入经验库。
|
||
|
||
**Requirements:** R4, R5, R6
|
||
|
||
**Dependencies:** U2, U5
|
||
|
||
**Files:**
|
||
- `src/agentkit/core/plan_checker.py` (新建)
|
||
- `tests/unit/core/test_plan_checker.py` (新建)
|
||
|
||
**Approach:**
|
||
- 新增 `PlanChecker` 类，集成 `QualityGate` 和 `LLMReflector`
|
||
- 检查环节：每步完成后，`QualityGate` 验证产出 + LLM 评估是否达标
|
||
- 复盘环节：全部完成后，`LLMReflector` 生成复盘报告（成功路径、失败原因、耗时分布）
|
||
- 经验写入：复盘结果写入 `ExperienceStore`（U5）
|
||
- 闭环：检查不通过 → 触发重试或计划调整（与 U2 的失败处理联动）
|
||
|
||
**Patterns to follow:** `EvolutionMixin.evolve_after_task()` 的反思-优化流程（`src/agentkit/evolution/lifecycle.py`）
|
||
|
||
**Test scenarios:**
|
||
- 所有步骤通过检查 → 生成复盘报告，经验写入 ExperienceStore
|
||
- 某步骤检查不通过 → 触发重试
|
||
- 重试后仍不通过 → 请求人工介入
|
||
- 复盘报告包含成功路径和失败原因
|
||
- Covers AE3: 错误经验写入后，后续任务能检索到避坑预警
|
||
|
||
**Verification:** 完整的 分析→计划→执行→检查→复盘→总结 闭环可运行
|
||
|
||
### U4. Skill 标准规范升级
|
||
|
||
**Goal:** 定义 Skill 标准接口规范，支持动态注册、版本管理、能力查询，确保 7 项能力以 Skill 插件形式接入。
|
||
|
||
**Requirements:** R7, R8, R9, R10
|
||
|
||
**Dependencies:** 无
|
||
|
||
**Files:**
|
||
- `src/agentkit/skills/base.py` (修改)
|
||
- `src/agentkit/skills/registry.py` (修改)
|
||
- `src/agentkit/skills/loader.py` (修改)
|
||
- `src/agentkit/skills/schema.py` (新建)
|
||
- `tests/unit/skills/test_skill_registry_v2.py` (新建)
|
||
|
||
**Approach:**
|
||
- 扩展 `SkillConfig`：新增 `version`（语义版本）、`dependencies`（依赖的 Skill/Tool 声明）、`capabilities`（能力标签，用于查询）
|
||
- 新增 `SkillSpec` schema：定义 Skill 的标准接口规范（元数据、输入输出 Schema、依赖声明、质量门禁配置）
|
||
- 增强 `SkillRegistry`：新增 `query_by_capability()`（按能力标签查询）、`get_versions()`（版本管理）、`health_check()`（依赖检查）
|
||
- 增强 `SkillLoader`：支持从 Python 包自动发现 Skill（entry_points 机制）
|
||
- RAG/Terminal/ComputerUse 等新能力均以 Skill 插件形式注册
|
||
|
||
**Patterns to follow:** 现有 `SkillConfig` 的 Pydantic 模型模式（`src/agentkit/skills/base.py`）
|
||
|
||
**Test scenarios:**
|
||
- 注册带版本和依赖的 Skill → 成功注册，依赖检查通过
|
||
- 注册缺少依赖的 Skill → 依赖检查失败，返回错误信息
|
||
- 按能力标签查询 → 返回匹配的 Skill 列表
|
||
- 同名 Skill 注册新版本 → 版本历史保留，默认使用最新版
|
||
- 从 Python 包自动发现 Skill → 正确加载
|
||
|
||
**Verification:** 开发者可用 10-20 行 YAML 定义一个 Skill 并注册到平台（SC2）
|
||
|
||
### U5. ExperienceStore — 任务经验库
|
||
|
||
**Goal:** 存储任务执行经验（成功路径、失败原因、耗时分布），支持按任务类型检索和语义搜索。
|
||
|
||
**Requirements:** R29, R30, R33
|
||
|
||
**Dependencies:** U4
|
||
|
||
**Files:**
|
||
- `src/agentkit/evolution/experience_store.py` (新建)
|
||
- `src/agentkit/evolution/experience_schema.py` (新建)
|
||
- `tests/unit/evolution/test_experience_store.py` (新建)
|
||
|
||
**Approach:**
|
||
- 新增 `ExperienceStore` 类，独立于现有 `EvolutionStore`
|
||
- `TaskExperience` 数据模型：task_type, goal, steps, outcome, duration, success_rate, failure_reasons, optimization_tips, embedding, created_at
|
||
- 存储：PostgreSQL 表 + pgvector 向量索引 + tsvector 全文索引
|
||
- 检索：精确匹配 task_type + 语义相似度排序 + 时效性衰减
|
||
- 与 `EvolutionMixin` 集成：`evolve_after_task()` 完成后自动调用 `ExperienceStore.record_experience()`
|
||
- 指标追踪：`EvolutionMetrics` 追踪完成率/耗时/重试率趋势（R33）
|
||
|
||
**Patterns to follow:** `EpisodicMemory` 的 pgvector + PostgreSQL 存储模式（`src/agentkit/memory/episodic.py`）
|
||
|
||
**Test scenarios:**
|
||
- 记录成功任务经验 → 正确存储，可按 task_type 检索
|
||
- 记录失败任务经验 → failure_reasons 正确存储
|
||
- 语义检索 → 返回与查询语义相似的经验
|
||
- 时效性衰减 → 近期经验权重高于旧经验
|
||
- 指标趋势查询 → 返回完成率/耗时/重试率变化
|
||
|
||
**Verification:** 任务完成后经验自动写入，新任务可检索到相关经验
|
||
|
||
---
|
||
|
||
### Phase 2: 智能终端与自进化增强
|
||
|
||
### U6. PitfallDetector — 避坑预警
|
||
|
||
**Goal:** 新任务启动时检索错误经验，匹配当前计划步骤，自动预警。
|
||
|
||
**Requirements:** R32
|
||
|
||
**Dependencies:** U5
|
||
|
||
**Files:**
|
||
- `src/agentkit/evolution/pitfall_detector.py` (新建)
|
||
- `tests/unit/evolution/test_pitfall_detector.py` (新建)
|
||
|
||
**Approach:**
|
||
- 新增 `PitfallDetector` 类
|
||
- `check_pitfalls(task_type, planned_steps)` → `list[PitfallWarning]`
|
||
- 匹配逻辑：检索同类任务的失败经验，将失败步骤与当前计划步骤进行语义匹配
|
||
- 预警级别：HIGH（历史高失败率步骤）、MEDIUM（有失败记录但频率低）、LOW（仅提示）
|
||
- 集成到 `GoalPlanner`：计划生成后可选调用 `PitfallDetector`，预警信息附加到计划中（GoalPlanner 在 Phase 1 已可独立运行，PitfallDetector 是 Phase 2 的可选增强）
|
||
|
||
**Patterns to follow:** `RuleBasedReflector` 的规则匹配模式（`src/agentkit/evolution/reflector.py`）
|
||
|
||
**Test scenarios:**
|
||
- 计划包含历史高失败率步骤 → 返回 HIGH 级别预警
|
||
- 计划无历史失败记录 → 返回空列表
|
||
- 多个步骤有风险 → 按严重程度排序返回
|
||
- Covers AE3: "调用 X 系统 API 在高峰期超时率 60%" → 新任务调用时自动预警
|
||
|
||
**Verification:** 新任务计划包含历史失败步骤时，自动返回避坑预警
|
||
|
||
### U7. PathOptimizer — 执行路径优化
|
||
|
||
**Goal:** 发现更优执行路径时自动更新经验库中的推荐路径。
|
||
|
||
**Requirements:** R31
|
||
|
||
**Dependencies:** U5
|
||
|
||
**Files:**
|
||
- `src/agentkit/evolution/path_optimizer.py` (新建)
|
||
- `tests/unit/evolution/test_path_optimizer.py` (新建)
|
||
|
||
**Approach:**
|
||
- 新增 `PathOptimizer` 类
|
||
- `ExecutionPath` 数据模型：steps, total_duration, success_rate, sample_count
|
||
- 对比逻辑：新路径与现有最优路径比较（综合耗时和成功率），决定是否更新
|
||
- 更新策略：新路径成功率更高或同成功率但耗时更短 → 更新推荐路径
|
||
- 集成到 `PlanChecker`：复盘时可选调用 `PathOptimizer.evaluate_and_update()`（PlanChecker 在 Phase 1 已可独立运行，PathOptimizer 是 Phase 2 的可选增强）
|
||
|
||
**Patterns to follow:** `ABTester` 的统计比较模式（`src/agentkit/evolution/ab_tester.py`）
|
||
|
||
**Test scenarios:**
|
||
- 新路径耗时更短 → 更新推荐路径
|
||
- 新路径成功率更高 → 更新推荐路径
|
||
- 新路径无明显优势 → 保留现有推荐路径
|
||
- 样本量不足 → 不更新，记录待观察
|
||
|
||
**Verification:** 同类任务执行多次后，推荐路径自动优化
|
||
|
||
### U8. TerminalSession — 智能终端交互
|
||
|
||
**Goal:** 增强现有 ShellTool，支持会话状态维护、交互式命令、输出理解。
|
||
|
||
**Requirements:** R15, R16, R17, R18
|
||
|
||
**Dependencies:** U4
|
||
|
||
**Files:**
|
||
- `src/agentkit/tools/terminal_session.py` (新建)
|
||
- `src/agentkit/tools/pty_session.py` (新建)
|
||
- `src/agentkit/tools/shell.py` (修改)
|
||
- `src/agentkit/tools/output_parser.py` (新建)
|
||
- `tests/unit/tools/test_terminal_session.py` (新建)
|
||
- `tests/unit/tools/test_pty_session.py` (新建)
|
||
|
||
**Approach:**
|
||
- 新增 `TerminalSession` 类：维护 cwd/env/history，跨命令保持状态
|
||
- 新增 `PTYSession` 类：基于 `pexpect` 或 `asyncio` + `os.openpty()` 实现伪终端，支持交互式命令
|
||
- 增强 `ShellTool`：新增 `session_id` 参数，指定会话执行；无 session_id 时保持现有行为（向后兼容）
|
||
- 新增 `OutputParser`：结构化解析命令输出（错误类型、退出码含义、可操作建议）
|
||
- 安全控制：危险操作通过 `AskHumanTool` 请求确认，所有操作记录审计日志
|
||
|
||
**Patterns to follow:** 现有 `ShellTool` 的白名单 + 危险命令拦截模式（`src/agentkit/tools/shell.py`）
|
||
|
||
**Test scenarios:**
|
||
- 跨命令保持 cwd → cd 后执行 pwd 返回正确目录
|
||
- 跨命令保持 env → export 后执行 echo 返回正确值
|
||
- 交互式命令自动应答 → 命令等待输入时自动提供
|
||
- 危险命令需确认 → rm 命令触发 AskHumanTool
|
||
- 输出解析 → 错误输出结构化为错误类型+建议
|
||
- 无 session_id 时保持现有行为
|
||
|
||
**Verification:** Agent 能在终端会话中跨命令保持状态，处理交互式命令
|
||
|
||
---
|
||
|
||
### Phase 3: 知识库与 RAG 增强
|
||
|
||
### U9. LocalDocumentIngestion — 本地文档摄取
|
||
|
||
**Goal:** 支持上传文档（PDF/Word/Markdown 等），自动分块、向量化、索引。
|
||
|
||
**Requirements:** R11
|
||
|
||
**Dependencies:** U4
|
||
|
||
**Files:**
|
||
- `src/agentkit/memory/document_loader.py` (新建)
|
||
- `src/agentkit/memory/local_rag.py` (新建)
|
||
- `src/agentkit/memory/chunking.py` (新建)
|
||
- `tests/unit/memory/test_document_loader.py` (新建)
|
||
- `tests/unit/memory/test_local_rag.py` (新建)
|
||
|
||
**Approach:**
|
||
- 新增 `DocumentLoader`：支持 PDF（PyMuPDF/pdfplumber）、Word（python-docx）、Markdown（mistune）、HTML（BeautifulSoup）、纯文本
|
||
- 新增 `LocalRAGService`：实现 `KnowledgeBase` 协议（见 KTD-7），使用 pgvector 存储 + 检索（复用 `EpisodicMemory` 的 pgvector 基础设施）
|
||
- 分块策略：复用 `ContextualChunker`（`src/agentkit/memory/contextual_retrieval.py`），新增按文档结构的分块（按标题/段落）
|
||
- 嵌入：复用 `OpenAIEmbedder`（`src/agentkit/memory/embedder.py`）
|
||
- 摄取 Pipeline：上传 → 解析 → 分块 → 嵌入 → 写入 pgvector
|
||
|
||
**Patterns to follow:** `HttpRAGService` 的 HTTP 客户端模式（`src/agentkit/memory/http_rag.py`），`KnowledgeBase` 协议（KTD-7）
|
||
|
||
**Test scenarios:**
|
||
- 上传 PDF → 正确解析、分块、向量化、可检索
|
||
- 上传 Markdown → 按标题结构分块
|
||
- 上传 Word → 正确解析文本和表格
|
||
- 检索上传的文档 → 返回相关内容+来源追溯
|
||
- 大文件分块 → 块大小在配置范围内
|
||
|
||
**Verification:** 上传企业文档后可通过 RAG 检索到相关内容
|
||
|
||
### U10. ExternalKBAdapters — 外部知识库适配器
|
||
|
||
**Goal:** 对接飞书知识库、Confluence、企业 Wiki 等外部知识库，统一检索接口。
|
||
|
||
**Requirements:** R12
|
||
|
||
**Dependencies:** U4
|
||
|
||
**Files:**
|
||
- `src/agentkit/memory/knowledge_base.py` (新建 — KnowledgeBase 协议定义)
|
||
- `src/agentkit/memory/adapters/base.py` (新建)
|
||
- `src/agentkit/memory/adapters/feishu.py` (新建)
|
||
- `src/agentkit/memory/adapters/confluence.py` (新建)
|
||
- `src/agentkit/memory/adapters/generic_http.py` (新建)
|
||
- `tests/unit/memory/test_adapters.py` (新建)
|
||
|
||
**Approach:**
|
||
- 定义独立 `KnowledgeBase` 协议（见 KTD-7）：`ingest(docs)`/`query(text, top_k)`/`delete_by_id(id)`/`list_sources()`/`health_check()`
|
||
- 定义 `KBAdapter` 抽象基类实现 `KnowledgeBase` 协议：`search()`, `get_document()`, `list_sources()`, `health_check()`
|
||
- `FeishuKBAdapter`：对接飞书知识库 API
|
||
- `ConfluenceAdapter`：对接 Confluence REST API
|
||
- `GenericHTTPAdapter`：通用 HTTP 适配器，配置 API endpoint + auth 即可对接任意 HTTP 知识库
|
||
- 所有适配器实现 `KnowledgeBase` 协议（非 `Memory` 接口），可被 `MultiSourceRetriever` 统一调度
|
||
- `SemanticMemory` 内部组合使用 `KnowledgeBase`，而非强制适配 `Memory` 的 `retrieve(key)` 语义
|
||
|
||
**Patterns to follow:** `HttpRAGService` 的 HTTP 客户端模式（`src/agentkit/memory/http_rag.py`）
|
||
|
||
**Test scenarios:**
|
||
- FeishuKBAdapter 检索 → 返回飞书知识库内容
|
||
- ConfluenceAdapter 检索 → 返回 Confluence 页面内容
|
||
- GenericHTTPAdapter 检索 → 返回配置的 HTTP API 内容
|
||
- 适配器健康检查 → 正确报告连接状态
|
||
- 认证失败 → 返回明确错误信息
|
||
|
||
**Verification:** 可通过统一接口检索飞书知识库和 Confluence 内容
|
||
|
||
### U11. MultiSourceRAG — 多源 RAG 与信息源指定
|
||
|
||
**Goal:** 用户可在任务级别指定信息源，支持多源混合检索，结果包含来源追溯。
|
||
|
||
**Requirements:** R13, R14
|
||
|
||
**Dependencies:** U9, U10
|
||
|
||
**Files:**
|
||
- `src/agentkit/memory/multi_source_retriever.py` (新建)
|
||
- `src/agentkit/memory/retriever.py` (修改)
|
||
- `tests/unit/memory/test_multi_source_rag.py` (新建)
|
||
|
||
**Approach:**
|
||
- 新增 `MultiSourceRetriever`：管理多个 `KnowledgeBase` 协议实现（LocalRAGService、各 KBAdapter、HttpRAGService 适配器）
|
||
- 信息源指定：`search(query, sources=["feishu", "local:合规文档"])` → 仅从指定源检索
|
||
- 混合检索：并行查询多个源，按权重融合排序
|
||
- 来源追溯：每个检索结果附带 `source_id` + `document_title` + `chunk_location`
|
||
- 集成到 `MemoryRetriever`：新增 `sources` 参数，传递给 `MultiSourceRetriever`
|
||
- 所有 RAG 源统一实现 `KnowledgeBase` 协议（KTD-7），`MultiSourceRetriever` 不再区分 Memory 和 KBAdapter 接口
|
||
|
||
**Patterns to follow:** `MemoryRetriever` 的混合检索模式（`src/agentkit/memory/retriever.py`）
|
||
|
||
**Test scenarios:**
|
||
- 指定单个信息源 → 仅从该源检索
|
||
- 指定多个信息源 → 并行检索，结果融合排序
|
||
- 不指定信息源 → 从所有可用源检索
|
||
- 来源追溯 → 每个结果包含来源信息
|
||
- Covers AE4: 指定"合规文档库"和"法务知识库" → 仅从这两个源检索
|
||
|
||
**Verification:** 用户可指定信息源检索，结果包含来源追溯
|
||
|
||
---
|
||
|
||
### Phase 4: Computer Use 集成
|
||
|
||
### U12. ComputerUseTool — Computer Use 集成
|
||
|
||
**Goal:** 集成 Anthropic Computer Use API，支持截屏识别、UI 操作、降级策略、录制回放。
|
||
|
||
**Requirements:** R19, R20, R21, R22
|
||
|
||
**Dependencies:** U4
|
||
|
||
**Files:**
|
||
- `src/agentkit/tools/computer_use.py` (新建)
|
||
- `src/agentkit/tools/computer_use_session.py` (新建)
|
||
- `src/agentkit/tools/computer_use_recorder.py` (新建)
|
||
- `tests/unit/tools/test_computer_use.py` (新建)
|
||
|
||
**Approach:**
|
||
- 新增 `ComputerUseTool`（继承 `Tool`）：封装 Anthropic Computer Use API 调用
|
||
- 新增 `ComputerUseSession`：管理虚拟桌面会话（Docker 沙箱），维护操作上下文
|
||
- 操作类型：screenshot → click → type → scroll → drag → key → wait
|
||
- 降级链：ComputerUseTool 失败 → 检查是否有 API/CLI 替代 → ShellTool → AskHumanTool
|
||
- 新增 `ComputerUseRecorder`：记录每次截屏和操作，支持回放和审核
|
||
- 注册为 Skill 插件：`computer_use` Skill，可被自主执行引擎调用
|
||
|
||
**Patterns to follow:** `ShellTool` 的 Tool 基类实现 + 安全控制模式（`src/agentkit/tools/shell.py`）
|
||
|
||
**Test scenarios:**
|
||
- 截屏并识别 UI 元素 → 返回可操作区域列表
|
||
- 点击指定坐标 → 操作成功
|
||
- 输入文本到输入框 → 操作成功
|
||
- 多步骤 UI 操作 → 每步根据结果决定下一步
|
||
- API 不可用时降级到 ShellTool → 正确降级
|
||
- Covers AE2: Computer Use 失败 → 降级到 OA 系统 API
|
||
- 操作录制回放 → 可回放操作序列
|
||
|
||
**Verification:** Computer Use 可在企业 Web 系统上完成基本操作（登录、填表、提交）（SC4）
|
||
|
||
---
|
||
|
||
### Phase 5: 前端门户
|
||
|
||
### U13a. Vue3 门户基础 — 对话界面与路由
|
||
|
||
**Goal:** 搭建 Vue3 SPA 骨架，实现统一对话界面作为 7 项能力的入口，IntentRouter 自动路由到对应能力。
|
||
|
||
**Requirements:** R34
|
||
|
||
**Dependencies:** U1, U2, U3
|
||
|
||
**Files:**
|
||
- `src/agentkit/server/frontend/` (新建目录)
|
||
- `src/agentkit/server/frontend/src/App.vue` (新建)
|
||
- `src/agentkit/server/frontend/src/views/ChatView.vue` (新建)
|
||
- `src/agentkit/server/frontend/src/components/chat/` (新建目录)
|
||
- `src/agentkit/server/frontend/src/stores/` (新建目录)
|
||
- `src/agentkit/server/frontend/src/api/` (新建目录)
|
||
- `src/agentkit/server/frontend/src/router/index.ts` (新建)
|
||
- `src/agentkit/server/routes/portal.py` (新建)
|
||
- `tests/unit/server/test_portal_routes.py` (新建)
|
||
|
||
**Approach:**
|
||
- Vue3 + TypeScript + Pinia + Vue Router + Ant Design Vue
|
||
- 对话界面为主入口，IntentRouter 自动路由到对应能力
|
||
- 侧边导航骨架：对话/工作流/知识库/技能/终端/Computer Use/自进化/设置
|
||
- API 层：封装 FastAPI REST API + WebSocket 调用
|
||
- 新增 Portal API 路由：对话消息、意图路由、能力状态查询
|
||
- 构建产物输出到 `src/agentkit/server/static/`，替换现有 `index.html`
|
||
|
||
**Patterns to follow:** 现有 FastAPI 路由结构（`src/agentkit/server/routes/`）
|
||
|
||
**Test scenarios:**
|
||
- 对话界面发送消息 → 正确路由到对应能力
|
||
- 侧边导航切换 → 正确加载对应视图
|
||
- WebSocket 实时推送 → 执行进度正确显示
|
||
- 意图路由 → "帮我查知识库"路由到 RAG 能力
|
||
|
||
**Verification:** 用户通过对话界面发送消息，系统能正确识别意图并路由到对应能力
|
||
|
||
### U13b. 管理页面 — 知识库/技能/终端/设置
|
||
|
||
**Goal:** 实现知识库管理、技能浏览、终端交互、系统设置等管理页面。
|
||
|
||
**Requirements:** R35
|
||
|
||
**Dependencies:** U13a, U9, U10, U8
|
||
|
||
**Files:**
|
||
- `src/agentkit/server/frontend/src/views/KnowledgeBaseView.vue` (新建)
|
||
- `src/agentkit/server/frontend/src/views/SkillsView.vue` (新建)
|
||
- `src/agentkit/server/frontend/src/views/TerminalView.vue` (新建)
|
||
- `src/agentkit/server/frontend/src/views/SettingsView.vue` (新建)
|
||
- `src/agentkit/server/frontend/src/components/kb/` (新建目录)
|
||
- `src/agentkit/server/frontend/src/components/skills/` (新建目录)
|
||
- `src/agentkit/server/frontend/src/components/terminal/` (新建目录)
|
||
- `src/agentkit/server/routes/kb_management.py` (新建)
|
||
- `src/agentkit/server/routes/skill_management.py` (新建)
|
||
|
||
**Approach:**
|
||
- 知识库管理页：文档上传、信息源配置、检索测试、来源追溯展示
|
||
- 技能浏览页：已注册 Skill 列表、能力标签筛选、版本管理、依赖检查
|
||
- 终端交互页：WebSocket 终端会话、命令历史、输出高亮
|
||
- 设置页：LLM 配置、Skill 配置、知识库连接配置
|
||
- 各页面通过 Pinia store 管理状态，API 层统一封装
|
||
|
||
**Patterns to follow:** U13a 的 API 层和 Store 模式
|
||
|
||
**Test scenarios:**
|
||
- 知识库管理页面上传文档 → 文档正确摄取
|
||
- 技能浏览页按能力标签筛选 → 返回匹配 Skill
|
||
- 终端交互页发送命令 → 输出正确显示
|
||
- 设置页面配置 LLM → 配置生效
|
||
|
||
**Verification:** 管理员可通过管理页面完成知识库管理、技能浏览、终端交互、系统配置
|
||
|
||
### U13c. 自进化仪表盘 — 经验可视化与指标监控
|
||
|
||
**Goal:** 实现自进化经验的可视化展示和指标监控，让用户了解 Agent 的进化状态。
|
||
|
||
**Requirements:** R36
|
||
|
||
**Dependencies:** U13a, U5, U6, U7
|
||
|
||
**Files:**
|
||
- `src/agentkit/server/frontend/src/views/EvolutionView.vue` (新建)
|
||
- `src/agentkit/server/frontend/src/components/evolution/` (新建目录)
|
||
- `src/agentkit/server/routes/evolution_dashboard.py` (新建)
|
||
- `tests/unit/server/test_evolution_dashboard.py` (新建)
|
||
|
||
**Approach:**
|
||
- 经验时间线：展示任务经验积累历程，成功/失败分布
|
||
- 指标趋势图：完成率、耗时、重试率变化曲线（ECharts/AntV）
|
||
- 避坑预警面板：当前任务的风险提示，历史失败步骤高亮
|
||
- 路径优化记录：推荐路径变更历史，新旧路径对比
|
||
- 实时更新：WebSocket 推送新经验和指标变化
|
||
|
||
**Patterns to follow:** U13a 的 WebSocket 实时推送模式
|
||
|
||
**Test scenarios:**
|
||
- 经验时间线展示 → 正确显示成功/失败分布
|
||
- 指标趋势图 → 完成率/耗时曲线正确渲染
|
||
- 避坑预警面板 → 当前任务风险提示正确显示
|
||
- 实时更新 → 新经验写入后仪表盘自动刷新
|
||
|
||
**Verification:** 用户可通过仪表盘直观了解 Agent 的经验积累和进化状态
|
||
|
||
### U14. Workflow 可视化编辑器
|
||
|
||
**Goal:** 基于 Vue Flow 构建可视化拖拽编排界面，支持条件分支、并行执行、人工审批、动态调整。
|
||
|
||
**Requirements:** R24, R25, R26, R27, R28
|
||
|
||
**Dependencies:** U13a
|
||
|
||
**Files:**
|
||
- `src/agentkit/server/frontend/src/views/WorkflowEditorView.vue` (新建)
|
||
- `src/agentkit/server/frontend/src/components/workflow/FlowCanvas.vue` (新建)
|
||
- `src/agentkit/server/frontend/src/components/workflow/NodePalette.vue` (新建)
|
||
- `src/agentkit/server/frontend/src/components/workflow/PropertyPanel.vue` (新建)
|
||
- `src/agentkit/server/frontend/src/components/workflow/SkillNode.vue` (新建)
|
||
- `src/agentkit/server/frontend/src/components/workflow/ConditionNode.vue` (新建)
|
||
- `src/agentkit/server/frontend/src/components/workflow/ApprovalNode.vue` (新建)
|
||
- `src/agentkit/server/frontend/src/utils/workflowSerializer.ts` (新建)
|
||
- `src/agentkit/server/routes/workflows.py` (新建)
|
||
- `src/agentkit/orchestrator/workflow_schema.py` (新建)
|
||
- `tests/unit/server/test_workflow_routes.py` (新建)
|
||
|
||
**Approach:**
|
||
- Vue Flow 画布：拖拽节点构建 Workflow
|
||
- 自定义节点类型：SkillNode（引用已注册 Skill）、ConditionNode（条件分支）、ApprovalNode（人工审批）、ParallelNode（并行分组）
|
||
- 序列化：Vue Flow JSON → `WorkflowDefinition`（继承 `Pipeline`，见 KTD-8），其中每个节点映射为扩展后的 `PipelineStage`（含 `type`/`config` 字段）
|
||
- 后端 API：Workflow CRUD + 执行 + 状态查询 + WebSocket 进度推送
|
||
- `WorkflowDefinition` 继承 `Pipeline`，新增 `workflow_id`/`triggers`/`variables_schema`/`output_schema` 字段
|
||
- `PipelineStage` 扩展 `type: str = "skill"` 和 `config: dict = {}`，默认值不破坏现有数据
|
||
- 人工审批：执行到 ApprovalNode 时暂停，通知审批人，确认后继续
|
||
- 动态调整：执行中可通过 API 增删节点或切换分支
|
||
|
||
**Patterns to follow:** `PipelineEngine` 的 DAG 执行模式（`src/agentkit/orchestrator/pipeline_engine.py`）
|
||
|
||
**Test scenarios:**
|
||
- 拖拽 Skill 节点到画布 → 节点正确渲染
|
||
- 连接节点建立依赖 → 边正确创建
|
||
- 添加条件分支节点 → 条件配置正确
|
||
- 添加人工审批节点 → 审批流程正确
|
||
- 序列化为 YAML → 与 PipelineEngine 格式兼容
|
||
- Covers AE5: Workflow 包含审批节点 → 执行到该节点暂停等待确认
|
||
|
||
**Verification:** 用户可通过拖拽构建 Workflow 并执行
|
||
|
||
---
|
||
|
||
### Phase 6: 端到端验证
|
||
|
||
### U15. 端到端企业场景验证
|
||
|
||
**Goal:** 用"目标驱动的复杂任务"场景端到端验证 7 项能力集成。
|
||
|
||
**Requirements:** R1-R36 (集成验证)
|
||
|
||
**Dependencies:** U1-U14 全部完成（含 U13a/U13b/U13c）
|
||
|
||
**Files:**
|
||
- `tests/integration/test_goal_driven_scenario.py` (新建)
|
||
- `configs/skills/goal_driven_agent.yaml` (新建)
|
||
- `configs/pipelines/goal_driven_pipeline.yaml` (新建)
|
||
|
||
**Approach:**
|
||
- 验证场景："分析竞品 SEO 策略并生成优化方案"
|
||
- 覆盖能力：自主闭环（目标→计划→执行→检查→复盘）+ RAG（检索企业知识库）+ Skill 调度（调用搜索/分析/生成 Skill）
|
||
- 验证指标：端到端完成率、并行执行效率、经验积累效果
|
||
- 补充验证：知识库问答+系统操作场景、Workflow 编排场景
|
||
|
||
**Test scenarios:**
|
||
- 目标驱动场景端到端执行 → 生成完整优化方案
|
||
- 并行步骤自动调度 → 3 个竞品调研并行执行
|
||
- 经验积累 → 第二次执行同类任务耗时减少
|
||
- 知识库指定信息源 → 仅从指定源检索
|
||
- Workflow 人工审批 → 执行到审批节点暂停
|
||
|
||
**Verification:** 一个完整企业场景端到端走通，覆盖自主闭环+RAG+Skill 调度（SC1）
|
||
|
||
---
|
||
|
||
## Scope Boundaries
|
||
|
||
**Deferred for later:**
|
||
- Skill 市场/社区
|
||
- 多租户隔离
|
||
- 企业级认证/权限体系（RBAC/LDAP/SSO）
|
||
- 移动端适配
|
||
- Workflow 模板市场
|
||
- Computer Use 自研视觉识别（替代第三方 API）
|
||
- 经验库跨组织共享
|
||
|
||
**Outside this product's identity:**
|
||
- LLM 训练/微调平台
|
||
- 数据标注平台
|
||
- 低代码应用开发平台
|
||
|
||
---
|
||
|
||
## Risks & Dependencies
|
||
|
||
| Risk | Impact | Mitigation |
|
||
|------|--------|-----------|
|
||
| Anthropic Computer Use API 可靠性有限 | Computer Use 能力不稳定 | 降级链（API → ShellTool → AskHuman），Docker 沙箱隔离 |
|
||
| Vue3 前端重构工作量大 | 延迟 Phase 5 交付 | 后端 API 先行，前端可分批交付（先对话界面，再 Workflow 编辑器） |
|
||
| 经验库初期数据为空 | 自进化效果不明显 | 预置种子经验（从测试和文档中提取），冷启动策略 |
|
||
| pgvector 性能瓶颈 | 大规模知识库检索慢 | 分区索引、查询优化、缓存层 |
|
||
| PipelineEngine 强依赖 Redis+SQLAlchemy | 无 Redis/PG 环境无法运行 | 提供 LocalRAGService 和内存 PipelineState 降级方案 |
|
||
|
||
---
|
||
|
||
## Outstanding Questions
|
||
|
||
**Deferred to implementation:**
|
||
- OQ1. 经验库的精确表结构和索引策略——实现时根据数据量调整
|
||
- OQ2. PTY 实现选型：pexpect vs asyncio+openpty——U8 实现时根据跨平台需求决定
|
||
- OQ3. HttpRAGService 如何适配 KnowledgeBase 协议——U10 实现时决定是包装适配还是重构
|
||
|
||
---
|
||
|
||
## Sources & Research
|
||
|
||
- 现有架构分析：`src/agentkit/core/`, `src/agentkit/skills/`, `src/agentkit/orchestrator/`, `src/agentkit/memory/`, `src/agentkit/tools/`, `src/agentkit/evolution/`
|
||
- Anthropic Computer Use API 文档：beta API，支持 computer/text_editor/bash 三种工具类型
|
||
- Vue Flow：Vue3 原生流程图库，6k+ stars，DAG 支持，自定义节点
|
||
- Agent 自进化模式：Reflexion（反思-修正）、Experience Replay（经验回放）、Genetic Evolution（遗传进化）
|
||
- 企业门户架构：Dify/Coze/FastGPT 的对话驱动+能力面板模式
|
||
- 智能终端模式：Claude Code 的执行-观察-决策循环 + PTY 会话模式
|