---
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 会话模式