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 阶段建议至少包含 2 个运行单元:

1. `agent-backend`
2. `edge-agent`

说明:

1. demo 阶段默认采用 `SQLite`,以本地文件方式随 `agent-backend` 一起运行,不额外部署数据库单元。
2. demo 阶段不引入 `Redis` 强依赖,任务轮询、简单队列和状态流转先通过数据库表和后台 worker 承接。

可选:

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. SQLite
6. LangGraph

补充说明:

1. demo 默认数据库为 `SQLite`。
2. Repository 和 ORM 层需预留切换 `PostgreSQL` 的能力。
3. demo 阶段不将 `Redis` 作为启动前置依赖。

## 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 为什么 demo 默认使用 SQLite 且不强依赖 Redis

1. `SQLite` 安装成本最低,更适合 demo 阶段快速打通闭环。
2. `SQLite` 足以支撑单体服务、低并发联调和最小可运行演示。
3. 当前主链路优先级高于基础设施完整性,队列能力可先通过数据库表和 worker 轮询承接。
4. `Redis` 可在后续进入多实例部署、强幂等或高并发调度阶段时再评估引入,优先评估 `Valkey` 或兼容方案。

## 3.3 如果团队必须走 Java

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

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

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

---

## 4. 项目结构建议

## 4.1 仓库形态建议

建议采用单仓结构:

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

## 4.2 后端目录结构建议

```text
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 目录建议

```text
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. 所有执行结果结构化回传。

## 9.3 本地 Agent 交付格式

demo 阶段正式确认:

1. Windows 使用 `zip` 便携包交付。
2. Linux 使用 `tar.gz` 自包含运行目录交付。
3. 两个平台均不依赖客户现场预装 Python。
4. 单文件可执行包不作为第一阶段默认方案。

---

## 10. 配置与环境变量建议

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

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

说明:

1. demo 阶段 `DATABASE_URL` 默认建议为 `sqlite:///./data/agent_demo.db`。
2. 如后续切换 `PostgreSQL`,优先只调整配置,不改动 service 层接口。
3. demo 阶段不要求 `REDIS_URL`。

本地 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}`
8. 最小 DDL 文档。
9. 首批 OpenAPI 草案。

## 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. 为后续替换真实系统和服务拆分预留空间。