fischer-agentkit/plan.md at 94c4c8b88751176d4ccc71f571247794bebd72e2

34 KiB

Raw Blame History

date	deepened	status	origin
2026-06-09	2026-06-09	active	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

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

34 KiB Raw Blame History Unescape Escape

Summary

Problem Frame

Key Technical Decisions

High-Level Technical Design

Requirements Traceability

Implementation Units

Phase 1: 核心内核与经验基础

U1. GoalPlanner — 目标分析与计划生成

U2. PlanExecutor — 计划执行与并行调度

U3. PlanChecker — 检查与复盘闭环

U4. Skill 标准规范升级

U5. ExperienceStore — 任务经验库

Phase 2: 智能终端与自进化增强

U6. PitfallDetector — 避坑预警

U7. PathOptimizer — 执行路径优化

U8. TerminalSession — 智能终端交互

Phase 3: 知识库与 RAG 增强

U9. LocalDocumentIngestion — 本地文档摄取

U10. ExternalKBAdapters — 外部知识库适配器

U11. MultiSourceRAG — 多源 RAG 与信息源指定

Phase 4: Computer Use 集成

U12. ComputerUseTool — Computer Use 集成

Phase 5: 前端门户

U13a. Vue3 门户基础 — 对话界面与路由

U13b. 管理页面 — 知识库/技能/终端/设置

U13c. 自进化仪表盘 — 经验可视化与指标监控

U14. Workflow 可视化编辑器

Phase 6: 端到端验证

U15. 端到端企业场景验证

Scope Boundaries

Risks & Dependencies

Outstanding Questions

Sources & Research

34 KiB

Raw Blame History