aiagent/docs/architecture/可执行的 90 天演进路线图.md

可执行的 90 天演进路线图

目标：在不推翻现有平台的前提下，演进为“可编排 + 可编程 + 可治理”的企业 Agent 平台。
原则：保留现有优势（可视化流程、权限体系、执行日志/审计），做渐进增强。

---

一、90 天总目标（验收口径）

• 支持 Main Agent -> 子 Agent 的真实委派执行（非占位）。
• 支持 模板化创建场景 Agent（复制模板 + 参数注入）。
• 支持 治理能力（预算、审计、告警、人工确认）。
• 前端提供可用的 主控台入口（路由、执行、追踪）。

---

二、阶段拆解

阶段 1（Day 1-30）：稳态自动化夯实

1) 子工作流真实执行（最小闭环）

目标

• 将 subworkflow 从占位实现升级为真实执行能力。

代码改动

• backend/app/services/workflow_engine.py
  • 实现 subworkflow 节点真实执行：
    • 读取目标 workflow/agent 配置。
    • 构造并执行子 WorkflowEngine。
    • 返回结构化 output/status/error。
  • 增加防护参数：max_subworkflow_depth（默认 2）。
• backend/app/tasks/workflow_tasks.py
  • 透传嵌套执行上下文（parent_execution_id、depth）。
• backend/app/api/executions.py
  • 扩展执行输出，保留父子执行关联字段。

验收

• 一个 Agent 可在流程内调用另一个 Agent/Workflow 并拿到结果。
• 执行日志可追踪父子链路。

---

2) 16 号稳定性与模板规范化

目标

• 让 Loop 多段执行在生产可稳定运行并可复制。

代码/文档改动

• backend/scripts/create_zhini_kefu_16.py
  • 固化 loop 数据路径与 merge 行为。
  • 支持 2 段/3 段模式开关。
• 知你客服16号能力文档.md
  • 增加“已知边界、推荐场景、故障排查”章节。
• 知你客服15号_循环工作流设计.md
  • 增补“跨轮状态传递策略”（文件接力/Cache接力）。

验收

• 连续 20 次回归无 loop_rounds 空值类错误。
• 常见问法稳定返回，不再出现异常回显。

---

3) 观测与失败重试

目标

• 提高运行可观测性与容错能力。

代码改动

• backend/app/services/execution_logger.py
  • 增加统一错误码（例如 SUBFLOW_DEPTH_EXCEEDED）。
• backend/app/tasks/workflow_tasks.py
  • 增加可配置的退避重试（1-2 次）。
• backend/app/api/execution_logs.py
  • 增加 parent/child 聚合查询接口。

验收

• 失败能定位到“哪一层、哪个节点、哪次子调用”。
• 重试行为可追踪可审计。

---

阶段 2（Day 31-60）：多 Agent 协作

4) Main Agent 路由协议（结构化输出）

目标

• 主入口 Agent 负责任务分解与路由决策。

代码改动

• 新增：backend/scripts/create_main_agent.py
  • 创建主入口 Agent（仅输出结构化路由结果）。
• backend/app/services/workflow_engine.py
  • 增加 invoke_agent 节点（推荐）或等价工具调用。
• backend/app/services/tool_registry.py / backend/app/services/builtin_tools.py
  • 若走工具路线，注册 invoke_agent 工具与 schema。

验收

• 用户一次输入，主 Agent 完成路由并触发子 Agent 执行。
• 子执行结果可被主流程汇总输出。

---

5) 场景模板库（客服/研发/运维/数据）

目标

• 形成可复用模板，降低搭建门槛。

代码改动

• 新增目录：backend/scripts/templates/
  • template_customer_service.py
  • template_dev_codegen.py
  • template_ops_log_analysis.py
• backend/app/api/agents.py
  • 增加“从模板创建 Agent”接口（可选）。
• 前端模板入口（视项目结构放到 Agent 创建页对应组件）
  • 增加模板选择 + 参数表单。

验收

• 至少 3 个模板可一键创建并执行。
• 模板参数（工具白名单、段数、预算）可配置。

---

6) Human-in-the-loop（关键动作确认）

目标

• 将危险操作纳入审批闭环。

代码改动

• backend/app/services/workflow_engine.py
  • 增加 approval 节点，或在节点 data 中支持 requires_approval。
• backend/app/api/executions.py
  • 增加“挂起等待审批 / 审批通过继续执行”接口。
• 前端执行页面
  • 增加审批状态展示与操作入口。

验收

• 高风险节点默认挂起，审批通过后继续。
• 审批日志可追溯。

---

阶段 3（Day 61-90）：治理与平台化

7) 成本、预算与并发治理

目标

• 防止执行失控，支持组织级运营。

代码改动

• backend/app/services/workflow_engine.py
  • 增加预算控制：max_steps、工具调用上限、token 估算上限。
• backend/app/models/（新增预算配置模型）
  • 按租户/项目/Agent 维度配置预算。
• backend/app/api/monitoring.py / backend/app/api/alert_rules.py
  • 增加预算超限告警与熔断策略。

验收

• 可按 Agent 设置预算阈值并生效。
• 超限自动终止并记录可读原因。

---

8) 统一 DSL（场景可编程输入）

目标

• 让不同模板复用统一输入契约。

代码改动

• 新增：backend/app/services/scenario_dsl.py
  • 定义标准输入：目标、约束、产物、验收标准。
• backend/app/services/workflow_engine.py
  • 在入口处做 DSL 校验与标准化映射。
• 模板脚本
  • 全部迁移到 DSL 输入。

验收

• 同一输入可驱动多模板运行。
• 场景迁移与复用成本显著下降。

---

9) 主控台（应用商店 + 运行看板）

目标

• 降低业务用户使用门槛，强化平台可运营性。

前端改动（按现有结构落地）

• 新增页面：
  • MainConsole（主入口）
  • TemplateMarket（模板市场）
  • ExecutionBoard（父子执行链看板）
• 新增 API 封装：
  • 模板创建、子执行追踪、审批操作。

验收

• 业务用户流程：选模板 -> 填参数 -> 执行 -> 看结果。
• 管理员可查看预算、告警、审计。

---

三、每周里程碑（12 周）

• W1-W2：subworkflow 真执行 + 深度防护。
• W3-W4：日志链路 + 16 号稳定性回归。
• W5-W6：Main Agent 路由 + invoke_agent。
• W7-W8：模板库 + 审批节点。
• W9-W10：预算治理 + DSL。
• W11-W12：主控台 + UAT + 发布。

---

四、90 天成功指标（建议）

• 模板复用率 > 60%。
• 核心场景自动化成功率 > 85%。
• 平均处理时长下降 >= 30%。
• 可审计执行覆盖率 = 100%。
• 高风险动作审批覆盖率 = 100%。

---

五、本周可立刻开工的 3 件事

1. 完成 subworkflow 真执行（workflow_engine.py）。
2. 定义 Main Agent 的路由 JSON 协议（先后端可消费）。
3. 上线 3 个模板脚本（客服/研发/运维）并打通端到端回归。

---

六、风险与规避

• 风险：多 Agent 递归调用导致资源爆炸。
  规避：max_subworkflow_depth + max_steps + 预算熔断。

• 风险：模型动态创建 workflow JSON 质量不稳定。
  规避：优先“模板复制 + 参数注入”，减少从零生成。

• 风险：工具权限与合规风险。
  规避：工具白名单、审批节点、审计留痕。

---

说明：本路线图基于当前仓库已有能力（工作流引擎、Agent API、执行任务、日志与权限）制定，采用“可交付优先”的渐进式演进策略。