auto_agent/智能化部署agent-demo后端项目骨架设计.md

智能化部署 Agent Demo 后端项目骨架设计

1. 文档说明

1.1 文档目的

本文档用于定义智能化部署 Agent demo 阶段的后端项目骨架,作为研发启动时的直接输入。

本文档重点解决以下问题:

1. demo 后端采用什么形态落地。
2. 项目如何分层和分模块。
3. 哪些模块先实现,哪些模块后实现。
4. 数据如何落库。
5. 如何与软件 A demo、身份 demo、审批 demo、本地 Agent 对接。

1.2 适用范围

本文档适用于:

1. 后端研发。
2. 架构设计。
3. 联调排期。
4. demo 落地实施。

1.3 设计原则

1. demo 阶段优先打通主链路,不优先拆分微服务。
2. 内部采用清晰模块边界,后续可平滑拆分。
3. Agent 编排、策略治理、任务中心、适配器层必须独立建模。
4. 所有对外系统都通过适配器访问,不允许业务逻辑直接耦合具体 demo 接口。
5. 数据模型、字段命名、时间格式与现有两份文档保持一致。

---

2. demo 阶段推荐落地形态

2.1 总体建议

demo 阶段建议采用:

单体后端服务 + 模块化分层 + 外部 demo 适配器 + 独立本地 Agent

原因:

1. 当前目标是尽快打通闭环,而不是先解决分布式复杂度。
2. 软件 A、审批、身份本身都是 demo 版,先用单体服务更容易联调。
3. 任务编排、审批状态、工具调用、审计日志之间耦合较强,单体更利于快速演进。
4. 后续如果边界稳定,可以将任务中心、审批中心、模型网关逐步拆分。

2.2 部署单元建议

demo 阶段建议至少包含 4 个运行单元:

1. agent-backend
2. edge-agent
3. postgres
4. redis

可选:

1. software-a-demo
2. identity-demo
3. approval-demo

如果希望进一步压缩工作量,也可以把 software-a-demo、identity-demo、approval-demo 合并进 agent-backend 的 mock 模块中。

---

3. 技术栈建议

3.1 demo 后端推荐技术栈

建议优先采用:

1. Python 3.11+
2. FastAPI
3. Pydantic
4. SQLAlchemy
5. PostgreSQL
6. Redis
7. LangGraph

3.2 选择理由

3.2.1 为什么推荐 Python

1. LangGraph 生态更直接。
2. demo 阶段实现 Agent 编排更快。
3. 适合快速完成工具适配和状态流转。
4. 本地 Agent 也更容易做跨平台实现。

3.2.2 为什么推荐 FastAPI

1. 定义接口快。
2. Pydantic 模型与接口文档天然匹配。
3. 适合 demo 阶段快速落地。

3.2.3 为什么保留 PostgreSQL 和 Redis

1. PostgreSQL 用于结构化任务、审批、审计落库。
2. Redis 用于任务队列、幂等键、短期上下文和轮询状态。

3.3 如果团队必须走 Java

如果团队明确只能走 Java,也可以替换为:

1. Spring Boot
2. Spring Web
3. JPA / MyBatis
4. PostgreSQL
5. Redis

但 demo 阶段的 Agent 编排效率通常不如 Python 方案。

---

4. 项目结构建议

4.1 仓库形态建议

建议采用单仓结构:

smart-deploy-agent-demo/
  backend/
  edge-agent/
  docs/
  scripts/
  deploy/

4.2 后端目录结构建议

backend/
  app/
    api/
      agent/
      edge/
      internal/
    core/
      config.py
      logging.py
      security.py
      exceptions.py
      constants.py
    domain/
      task/
      approval/
      audit/
      edge/
      metadata/
    schemas/
      common.py
      task.py
      approval.py
      edge.py
      software_a.py
    models/
      task.py
      tool_call.py
      approval.py
      audit_log.py
      edge_node.py
      session_context.py
      app_metadata.py
    repositories/
      task_repository.py
      approval_repository.py
      audit_repository.py
      edge_repository.py
      metadata_repository.py
    services/
      task_service.py
      agent_service.py
      intent_service.py
      risk_service.py
      approval_service.py
      audit_service.py
      edge_service.py
      verification_service.py
      report_service.py
    adapters/
      llm/
        llm_gateway.py
      software_a/
        base.py
        demo_adapter.py
      identity/
        base.py
        demo_adapter.py
      approval/
        base.py
        demo_adapter.py
      edge/
        edge_dispatcher.py
    workflows/
      deploy_workflow.py
      query_log_workflow.py
      approval_workflow.py
    workers/
      task_runner.py
      task_polling_worker.py
      verify_worker.py
    db/
      base.py
      session.py
      migrations/
    main.py
  tests/
    api/
    services/
    workflows/
    adapters/

---

5. 模块职责设计

5.1 api 层

职责:

1. 接收 HTTP 请求。
2. 请求参数校验。
3. 调用 service。
4. 输出统一响应格式。

建议按接口边界拆分:

1. api/agent
2. api/edge
3. api/internal

说明:

1. api/agent 对应用户侧接口。
2. api/edge 对应本地 Agent 侧接口。
3. api/internal 对应内部管理、健康检查、mock 控制等接口。

5.2 schemas 层

职责:

1. 定义请求响应模型。
2. 与接口文档字段保持一致。
3. 避免 service 层直接处理原始 dict。

5.3 models 层

职责:

1. 定义数据库模型。
2. 维护持久化结构。
3. 不承载复杂业务逻辑。

5.4 repositories 层

职责:

1. 封装数据库访问。
2. 对 service 层提供统一持久化接口。
3. 隔离 ORM 细节。

5.5 services 层

这是后端核心业务层。

职责:

1. 编排任务创建。
2. 调用风险引擎。
3. 调用审批服务。
4. 调用适配器。
5. 维护任务状态机。
6. 汇总结果和生成报告。

5.6 adapters 层

职责:

1. 封装软件 A demo 调用。
2. 封装身份 demo 调用。
3. 封装审批 demo 调用。
4. 封装模型网关调用。
5. 封装本地 Agent 调度。

原则:

1. 所有外部系统接入必须先经过 adapter。
2. 上层 service 不直接拼接第三方 URL。
3. adapter 返回统一对象模型,而不是原始第三方响应。

5.7 workflows 层

职责:

1. 定义 LangGraph 状态机。
2. 管理任务节点顺序。
3. 将业务 service 组合成可运行工作流。

建议 workflow 按场景拆分:

1. deploy_workflow
2. query_log_workflow
3. approval_workflow

5.8 workers 层

职责:

1. 执行异步任务。
2. 轮询软件 A demo 状态。
3. 拉起验证流程。
4. 处理长任务和超时任务。

---

6. 建议的核心服务拆分

6.1 task_service

职责:

1. 创建任务。
2. 查询任务。
3. 确认任务。
4. 取消任务。
5. 更新任务状态。

6.2 agent_service

职责:

1. 驱动整体任务执行。
2. 调用 intent、risk、approval、adapter、report 等服务。
3. 负责主链路协调。

6.3 intent_service

职责:

1. 调用模型网关解析自然语言。
2. 生成结构化意图。
3. 标记缺失字段。

6.4 risk_service

职责:

1. 基于环境、动作、应用类型计算风险等级。
2. 判断是否需要确认。
3. 判断是否需要审批。

6.5 approval_service

职责:

1. 发起审批。
2. 查询审批状态。
3. 同步审批结果到任务。

6.6 verification_service

职责:

1. 生成验证步骤。
2. 调度本地 Agent。
3. 汇总验证结果。

6.7 report_service

职责:

1. 生成任务详情。
2. 生成任务报告。
3. 生成用户可读摘要。

6.8 audit_service

职责:

1. 记录关键行为。
2. 记录工具调用轨迹。
3. 记录审批轨迹。
4. 记录最终结果。

6.9 edge_service

职责:

1. 管理边缘节点注册和心跳。
2. 下发待执行步骤。
3. 接收执行结果和异常事件。

---

7. 数据库表建议

7.1 核心表清单

demo 阶段建议至少建立以下表:

1. task
2. task_step
3. tool_call
4. approval_request
5. approval_decision_log
6. audit_log
7. edge_node
8. edge_task
9. session_context
10. app_metadata

7.2 task 表建议字段

1. task_id
2. session_id
3. tenant_id
4. operator_user_id
5. operator_user_name
6. input_text
7. action_type
8. app_code
9. env
10. version
11. risk_level
12. approval_status
13. task_status
14. summary
15. created_at
16. updated_at

7.3 task_step 表建议字段

1. step_id
2. task_id
3. step_type
4. step_name
5. step_status
6. executor_type
7. target_edge_id
8. request_payload
9. response_payload
10. started_at
11. finished_at

7.4 tool_call 表建议字段

1. tool_call_id
2. task_id
3. step_id
4. tool_name
5. request_payload
6. response_payload
7. success
8. duration_ms
9. started_at
10. finished_at

7.5 approval_request 表建议字段

1. approval_id
2. task_id
3. approval_status
4. risk_level
5. operator_user_id
6. approver_user_ids
7. reason
8. created_at
9. updated_at

7.6 audit_log 表建议字段

1. audit_id
2. task_id
3. action
4. operator_user_id
5. target
6. result
7. detail
8. timestamp

---

8. 关键运行链路如何落到代码

8.1 创建任务链路

对应模块:

1. api/agent/tasks.py
2. services/task_service.py
3. services/intent_service.py
4. services/risk_service.py
5. repositories/task_repository.py

执行步骤:

1. 接收自然语言输入。
2. 调用 intent_service 生成结构化意图。
3. 调用 risk_service 生成风险等级。
4. 保存任务和初始状态。
5. 返回 task_id 和下一步动作。

8.2 确认任务链路

对应模块:

1. api/agent/tasks.py
2. services/task_service.py
3. services/agent_service.py
4. services/approval_service.py
5. workers/task_runner.py

执行步骤:

1. 接收确认请求。
2. 检查任务状态。
3. 如需审批则发起审批。
4. 如无需审批则投递异步执行任务。

8.3 执行部署链路

对应模块:

1. workflows/deploy_workflow.py
2. services/agent_service.py
3. adapters/software_a/demo_adapter.py
4. workers/task_polling_worker.py
5. services/verification_service.py

执行步骤:

1. 调用软件 A demo 创建部署任务。
2. 轮询部署状态。
3. 部署成功后生成验证步骤。
4. 下发到本地 Agent。
5. 汇总验证结果。
6. 生成报告。

8.4 本地验证链路

对应模块:

1. api/edge/tasks.py
2. services/edge_service.py
3. adapters/edge/edge_dispatcher.py
4. workers/verify_worker.py

执行步骤:

1. 本地 Agent 拉取待执行步骤。
2. 执行本地工具。
3. 上报执行结果。
4. 后端归档步骤状态并更新任务状态。

---

9. 本地 Agent 骨架建议

9.1 本地 Agent 目录建议

edge-agent/
  app/
    core/
      config.py
      security.py
      logging.py
    client/
      backend_client.py
    executors/
      process_executor.py
      port_executor.py
      http_executor.py
      log_executor.py
      windows_service_executor.py
      linux_service_executor.py
    registry/
      tool_registry.py
    scheduler/
      polling_runner.py
    main.py

9.2 本地 Agent 设计原则

1. 仅拉取结构化任务。
2. 不接收自由文本命令。
3. 不开放任意 shell。
4. 工具按操作系统分类适配。
5. 所有执行结果结构化回传。

---

10. 配置与环境变量建议

后端建议至少支持以下配置:

1. APP_ENV
2. APP_PORT
3. DATABASE_URL
4. REDIS_URL
5. LLM_BASE_URL
6. LLM_API_KEY
7. SOFTWARE_A_BASE_URL
8. SOFTWARE_A_TIMEOUT_MS
9. IDENTITY_BASE_URL
10. APPROVAL_BASE_URL
11. EDGE_TOKEN_SECRET
12. DEFAULT_TIMEZONE

本地 Agent 建议至少支持:

1. EDGE_ID
2. EDGE_NAME
3. BACKEND_BASE_URL
4. EDGE_ACCESS_TOKEN
5. EDGE_OS_TYPE
6. POLL_INTERVAL_MS

---

11. 开发顺序建议

11.1 第一批必须完成

1. 通用响应模型。
2. 配置加载。
3. 数据库连接。
4. task、approval_request、audit_log 表。
5. POST /api/agent/tasks
6. POST /api/agent/tasks/{task_id}/confirm
7. GET /api/agent/tasks/{task_id}

11.2 第二批完成

1. 软件 A demo adapter。
2. 部署工作流。
3. 审批 demo adapter。
4. 身份 demo adapter。
5. 异步任务执行。

11.3 第三批完成

1. edge 心跳。
2. edge 拉取任务。
3. edge 回传结果。
4. 验证结果汇总。
5. 任务报告接口。

11.4 第四批完成

1. 审计查询。
2. 应用元数据管理。
3. 错误处理完善。
4. 观测能力补齐。

---

12. 测试建议

12.1 单元测试

优先覆盖:

1. intent_service
2. risk_service
3. task_service
4. approval_service
5. adapter 错误转换

12.2 集成测试

优先覆盖:

1. 创建任务 -> 确认任务 -> 执行部署 -> 完成验证
2. 高风险任务 -> 创建审批 -> 审批通过 -> 执行
3. Edge 拉取任务 -> 执行 -> 回传

12.3 联调测试

至少覆盖:

1. 软件 A demo 联调。
2. 身份 demo 联调。
3. 审批 demo 联调。
4. 本地 Agent 联调。

---

13. 后续拆分方向

当 demo 稳定后,建议按以下边界拆分:

1. agent-api:接入与任务接口
2. agent-orchestrator:Agent 编排和工作流执行
3. agent-governance:审批、权限、风险、审计
4. agent-edge-gateway:本地 Agent 接入与调度

但在 demo 阶段,不建议一开始就拆。

---

14. 结论

demo 阶段最合适的落地方式不是复杂微服务,而是:

单体后端服务承接主业务链路,内部按模块清晰分层;本地 Agent 独立运行;软件 A、身份、审批通过 adapter 接入。

这套骨架的目标不是"一次到位",而是:

1. 尽快打通主链路。
2. 让模块边界稳定下来。
3. 为后续替换真实系统和服务拆分预留空间。