From 482c259f4db4215f3ad9a26b5906ad922197ef9c Mon Sep 17 00:00:00 2001
From: redbotu <darkmatch@163.com>
Date: Wed, 8 Apr 2026 19:08:56 +0800
Subject: [PATCH] =?UTF-8?q?=E8=AE=BE=E8=AE=A1=E6=96=87=E6=A1=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 智能化部署agent-demo后端项目骨架设计.md.txt   |  718 ++++++++++++
 智能化部署agent-demo接口定义说明.md.txt       |  914 +++++++++++++++
 智能化部署agent-当前进度总结.md.txt           |  242 ++++
 ...��术架构设计说明书.backup-20260408-141109.md.txt |  871 ++++++++++++++
 智能化部署agent-技术架构设计说明书.md.txt     |  948 +++++++++++++++
 智能化部署agent.md.txt                        | 1037 +++++++++++++++++
 6 files changed, 4730 insertions(+)
 create mode 100644 智能化部署agent-demo后端项目骨架设计.md.txt
 create mode 100644 智能化部署agent-demo接口定义说明.md.txt
 create mode 100644 智能化部署agent-当前进度总结.md.txt
 create mode 100644 智能化部署agent-技术架构设计说明书.backup-20260408-141109.md.txt
 create mode 100644 智能化部署agent-技术架构设计说明书.md.txt
 create mode 100644 智能化部署agent.md.txt

diff --git a/智能化部署agent-demo后端项目骨架设计.md.txt b/智能化部署agent-demo后端项目骨架设计.md.txt
new file mode 100644
index 0000000..77a1d77
--- /dev/null
+++ b/智能化部署agent-demo后端项目骨架设计.md.txt
@@ -0,0 +1,718 @@
+# 智能化部署 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 仓库形态建议
+
+建议采用单仓结构:
+
+```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. 所有执行结果结构化回传。
+
+---
+
+## 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. 为后续替换真实系统和服务拆分预留空间。
diff --git a/智能化部署agent-demo接口定义说明.md.txt b/智能化部署agent-demo接口定义说明.md.txt
new file mode 100644
index 0000000..a5149b1
--- /dev/null
+++ b/智能化部署agent-demo接口定义说明.md.txt
@@ -0,0 +1,914 @@
+# 智能化部署 Agent Demo 接口定义说明
+
+## 1. 文档说明
+
+### 1.1 文档目的
+
+本文档用于定义智能化部署 Agent MVP 阶段的 demo 接口,作为前后端开发、联调和本地 Agent 接入的直接输入。
+
+本文档覆盖以下接口范围:
+
+1. Agent 对外任务接口。
+2. 云端与本地 Agent 的交互接口。
+3. 软件 A demo 接口。
+4. 身份 demo 接口。
+5. 审批 demo 接口。
+
+### 1.2 设计目标
+
+1. 先打通完整闭环。
+2. 接口语义尽量稳定,便于后续替换为真实系统。
+3. 上层编排尽量不感知 demo 与真实系统差异。
+4. 所有关键动作可追溯、可审计。
+
+### 1.3 非目标
+
+本文档不覆盖:
+
+1. 前端页面字段细节。
+2. 数据库表结构 DDL。
+3. 真实软件 A 适配细节。
+4. 所有部署场景的扩展字段。
+
+---
+
+## 2. 总体约定
+
+## 2.1 协议约定
+
+1. 协议采用 `HTTPS + JSON`。
+2. 字符编码采用 `UTF-8`。
+3. 时间字段统一采用 `yyyy-MM-dd HH:mm:ss.SSS` 字符串格式,例如 `2026-04-07 18:00:00.123`。
+4. 未特殊说明时,所有时间字段默认时区为 `Asia/Shanghai`。
+5. 所有写接口建议支持 `request_id` 做幂等控制。
+
+## 2.2 字段命名规范
+
+1. 所有 JSON 字段统一采用 `snake_case`。
+2. 主键、关联键、设备键、任务键统一使用 `*_id` 后缀,例如 `task_id`、`approval_id`、`edge_id`。
+3. 状态字段统一使用 `*_status` 后缀,例如 `task_status`、`approval_status`。
+4. 类型字段统一使用 `*_type` 后缀,例如 `action_type`、`os_type`。
+5. 时间点字段统一使用 `*_at` 后缀,例如 `created_at`、`finished_at`、`expire_at`;通用响应时间字段保留 `timestamp`。
+6. 毫秒级耗时统一使用 `*_ms` 后缀,例如 `duration_ms`、`latency_ms`、`timeout_ms`。
+7. 数量统计统一使用 `*_count` 后缀,例如 `log_error_count`、`total_count`。
+8. 集合字段优先使用复数名词,例如 `roles`、`permissions`、`target_nodes`。
+9. 布尔字段按语义命名,通用执行结果使用 `success`,权限判断使用 `allowed`,验证结果使用 `*_ok`。
+10. 令牌有效期等以秒为单位的持续时间字段统一使用 `*_seconds` 后缀,例如 `expires_in_seconds`。
+
+## 2.3 通用请求头
+
+面向用户调用:
+
+```http
+Authorization: Bearer <access_token>
+Content-Type: application/json
+X-Request-Id: 2f6af6ad-8d98-4f6a-90d4-1ec6a661f701
+X-Tenant-Id: tenant-demo
+```
+
+面向本地 Agent 调用:
+
+```http
+Authorization: Bearer <edge_token>
+Content-Type: application/json
+X-Request-Id: 4a2e9309-5670-43cf-a88e-7ab5a36190e1
+X-Edge-Id: edge-shanghai-001
+X-Signature: <signature>
+```
+
+## 2.4 通用响应格式
+
+所有接口统一返回如下格式:
+
+```json
+{
+  "request_id": "2f6af6ad-8d98-4f6a-90d4-1ec6a661f701",
+  "success": true,
+  "code": "OK",
+  "message": "success",
+  "data": {},
+  "timestamp": "2026-04-08 14:30:00.123"
+}
+```
+
+字段说明:
+
+1. `request_id`:请求唯一标识。
+2. `success`:是否成功。
+3. `code`:业务错误码。
+4. `message`:可读描述。
+5. `data`:业务数据。
+6. `timestamp`:响应时间。
+
+## 2.5 通用错误码
+
+建议保留以下错误码:
+
+1. `OK`
+2. `INVALID_PARAM`
+3. `UNAUTHORIZED`
+4. `FORBIDDEN`
+5. `NOT_FOUND`
+6. `CONFLICT`
+7. `APPROVAL_REQUIRED`
+8. `CONFIRM_REQUIRED`
+9. `TOOL_CALL_FAILED`
+10. `EDGE_UNAVAILABLE`
+11. `SOFTWARE_A_FAILED`
+12. `TIMEOUT`
+13. `INTERNAL_ERROR`
+
+## 2.6 关键枚举定义
+
+### 2.5.1 风险等级
+
+```json
+["LOW", "MEDIUM", "HIGH"]
+```
+
+### 2.5.2 任务状态
+
+```json
+[
+  "CREATED",
+  "PENDING_CONFIRM",
+  "PENDING_APPROVAL",
+  "RUNNING",
+  "VERIFYING",
+  "SUCCEEDED",
+  "FAILED",
+  "PARTIAL_SUCCEEDED",
+  "CANCELLED"
+]
+```
+
+### 2.5.3 审批状态
+
+```json
+["NOT_REQUIRED", "PENDING", "APPROVED", "REJECTED", "EXPIRED"]
+```
+
+### 2.5.4 动作类型
+
+```json
+[
+  "DEPLOY",
+  "PUSH_CONFIG",
+  "START_SERVICE",
+  "STOP_SERVICE",
+  "RESTART_SERVICE",
+  "ROLLBACK",
+  "QUERY_LOG",
+  "HEALTH_CHECK",
+  "CALL_THIRD_PARTY_API"
+]
+```
+
+---
+
+## 3. Agent 对外接口
+
+## 3.1 创建任务
+
+`POST /api/agent/tasks`
+
+说明:
+
+1. 接收用户自然语言输入。
+2. 返回任务解析结果。
+3. 若缺参或需要确认,不直接执行。
+
+请求示例:
+
+```json
+{
+  "input_text": "把 order-service 1.2.3 部署到测试环境",
+  "channel": "WEB",
+  "session_id": "sess-001",
+  "tenant_id": "tenant-demo",
+  "context": {
+    "preferred_env": "test"
+  }
+}
+```
+
+响应示例:
+
+```json
+{
+  "request_id": "req-001",
+  "success": true,
+  "code": "OK",
+  "message": "success",
+  "data": {
+    "task_id": "task-20260408-001",
+    "parsed_intent": {
+      "action_type": "DEPLOY",
+      "app_code": "order-service",
+      "env": "test",
+      "version": "1.2.3"
+    },
+    "missing_slots": [],
+    "risk_level": "MEDIUM",
+    "task_status": "PENDING_CONFIRM",
+    "next_action": "CONFIRM_TASK"
+  },
+  "timestamp": "2026-04-08 14:30:00.123"
+}
+```
+
+## 3.2 确认任务
+
+`POST /api/agent/tasks/{task_id}/confirm`
+
+说明:
+
+1. 用户确认结构化任务。
+2. 低中风险任务确认后可进入执行。
+3. 高风险任务确认后进入审批。
+
+请求示例:
+
+```json
+{
+  "confirmed": true,
+  "comment": "确认执行"
+}
+```
+
+响应示例:
+
+```json
+{
+  "request_id": "req-002",
+  "success": true,
+  "code": "OK",
+  "message": "task confirmed",
+  "data": {
+    "task_id": "task-20260408-001",
+    "task_status": "RUNNING",
+    "approval_status": "NOT_REQUIRED"
+  },
+  "timestamp": "2026-04-08 14:31:00.123"
+}
+```
+
+## 3.3 查询任务详情
+
+`GET /api/agent/tasks/{task_id}`
+
+响应示例:
+
+```json
+{
+  "request_id": "req-003",
+  "success": true,
+  "code": "OK",
+  "message": "success",
+  "data": {
+    "task_id": "task-20260408-001",
+    "task_status": "VERIFYING",
+    "approval_status": "NOT_REQUIRED",
+    "risk_level": "MEDIUM",
+    "intent": {
+      "action_type": "DEPLOY",
+      "app_code": "order-service",
+      "env": "test",
+      "version": "1.2.3"
+    },
+    "tool_calls": [
+      {
+        "tool_name": "deploy_package",
+        "success": true
+      }
+    ],
+    "verification_result": {
+      "process_ok": true,
+      "port_ok": true,
+      "http_ok": true,
+      "log_error_count": 0
+    },
+    "summary": "部署成功,自动验证通过"
+  },
+  "timestamp": "2026-04-08 14:35:00.123"
+}
+```
+
+## 3.4 查询任务报告
+
+`GET /api/agent/tasks/{task_id}/report`
+
+说明:
+
+返回完整执行报告,适合前端展示和审计导出。
+
+响应 `data` 建议包含:
+
+1. `task_basic`
+2. `intent_snapshot`
+3. `approval_trace`
+4. `tool_trace`
+5. `verification_trace`
+6. `result_summary`
+7. `audit_trace`
+
+## 3.5 取消任务
+
+`POST /api/agent/tasks/{task_id}/cancel`
+
+说明:
+
+1. 仅允许取消未完成任务。
+2. 已经进入软件 A 执行阶段时,需要根据执行状态判断是否支持取消。
+
+---
+
+## 4. 云端与本地 Agent 交互接口
+
+## 4.1 Edge 心跳
+
+`POST /api/agent/edge/heartbeat`
+
+请求示例:
+
+```json
+{
+  "edge_id": "edge-shanghai-001",
+  "hostname": "customer-host-01",
+  "os_type": "WINDOWS",
+  "agent_version": "0.1.0",
+  "capabilities": [
+    "check_process",
+    "check_port",
+    "http_health_check",
+    "grep_log",
+    "service_control_windows"
+  ]
+}
+```
+
+## 4.2 Edge 拉取任务
+
+`POST /api/agent/edge/tasks/pull`
+
+请求示例:
+
+```json
+{
+  "edge_id": "edge-shanghai-001",
+  "max_tasks": 5
+}
+```
+
+响应示例:
+
+```json
+{
+  "request_id": "req-101",
+  "success": true,
+  "code": "OK",
+  "message": "success",
+  "data": {
+    "tasks": [
+      {
+        "task_id": "task-20260408-001",
+        "step_id": "step-verify-01",
+        "tool_name": "http_health_check",
+        "params": {
+          "url": "http://10.0.0.12:8080/actuator/health",
+          "timeout_ms": 3000
+        },
+        "expire_at": "2026-04-08 14:40:00.123"
+      }
+    ]
+  },
+  "timestamp": "2026-04-08 14:35:10.123"
+}
+```
+
+## 4.3 Edge 回传执行结果
+
+`POST /api/agent/edge/tasks/report`
+
+请求示例:
+
+```json
+{
+  "edge_id": "edge-shanghai-001",
+  "task_id": "task-20260408-001",
+  "step_id": "step-verify-01",
+  "tool_name": "http_health_check",
+  "success": true,
+  "code": "OK",
+  "message": "200 OK",
+  "data": {
+    "status_code": 200,
+    "latency_ms": 45
+  },
+  "evidence": {
+    "response_body": "{\"status\":\"UP\"}"
+  },
+  "started_at": "2026-04-08 14:35:11.123",
+  "finished_at": "2026-04-08 14:35:11.456"
+}
+```
+
+## 4.4 Edge 上报异常
+
+`POST /api/agent/edge/events`
+
+说明:
+
+用于上报:
+
+1. 本地 Agent 异常。
+2. 工具不可用。
+3. 证书异常。
+4. 系统资源异常。
+
+---
+
+## 5. 软件 A Demo 接口
+
+## 5.1 设计说明
+
+软件 A demo 版本用于支撑 MVP 闭环,其接口语义需尽量贴近未来真实软件 A 的标准能力。
+
+建议 base path:
+
+`/api/demo/software-a`
+
+## 5.2 创建部署任务
+
+`POST /api/demo/software-a/deploy-tasks`
+
+请求示例:
+
+```json
+{
+  "operator": {
+    "user_id": "u1001",
+    "user_name": "alice"
+  },
+  "tenant_id": "tenant-demo",
+  "app_code": "order-service",
+  "env": "test",
+  "version": "1.2.3",
+  "target_nodes": [
+    "10.0.0.12",
+    "10.0.0.13"
+  ],
+  "deploy_options": {
+    "graceful": true
+  }
+}
+```
+
+响应示例:
+
+```json
+{
+  "request_id": "req-sa-001",
+  "success": true,
+  "code": "OK",
+  "message": "deploy task created",
+  "data": {
+    "software_a_task_id": "sa-task-001",
+    "task_status": "RUNNING"
+  },
+  "timestamp": "2026-04-08 14:32:00.123"
+}
+```
+
+## 5.3 查询部署任务状态
+
+`GET /api/demo/software-a/deploy-tasks/{software_a_task_id}`
+
+响应 `data` 建议包含:
+
+1. `software_a_task_id`
+2. `task_status`
+3. `progress_percent`
+4. `app_code`
+5. `env`
+6. `version`
+7. `target_nodes`
+8. `started_at`
+9. `finished_at`
+10. `error_detail`
+
+## 5.4 推送配置
+
+`POST /api/demo/software-a/config/push`
+
+请求示例:
+
+```json
+{
+  "operator": {
+    "user_id": "u1001",
+    "user_name": "alice"
+  },
+  "app_code": "order-service",
+  "env": "test",
+  "config_template": "default-v1",
+  "config_version": "20260408-01",
+  "target_nodes": [
+    "10.0.0.12"
+  ]
+}
+```
+
+## 5.5 服务控制
+
+### 5.5.1 启动服务
+
+`POST /api/demo/software-a/services/start`
+
+### 5.5.2 停止服务
+
+`POST /api/demo/software-a/services/stop`
+
+### 5.5.3 重启服务
+
+`POST /api/demo/software-a/services/restart`
+
+统一请求示例:
+
+```json
+{
+  "operator": {
+    "user_id": "u1001",
+    "user_name": "alice"
+  },
+  "app_code": "order-service",
+  "env": "test",
+  "target_nodes": [
+    "10.0.0.12"
+  ]
+}
+```
+
+## 5.6 查询日志
+
+`POST /api/demo/software-a/logs/search`
+
+请求示例:
+
+```json
+{
+  "app_code": "order-service",
+  "env": "test",
+  "time_range": {
+    "start_at": "2026-04-08 14:20:00.123",
+    "end_at": "2026-04-08 14:30:00.123"
+  },
+  "keywords": [
+    "ERROR",
+    "Exception"
+  ],
+  "limit": 100
+}
+```
+
+响应 `data` 建议包含:
+
+1. `total_count`
+2. `entries`
+3. `summary`
+
+`entries` 单条建议字段:
+
+1. `timestamp`
+2. `level`
+3. `host`
+4. `message`
+
+## 5.7 查询指标
+
+`POST /api/demo/software-a/metrics/query`
+
+请求示例:
+
+```json
+{
+  "app_code": "order-service",
+  "env": "test",
+  "metric_names": [
+    "cpu_usage",
+    "memory_usage",
+    "http_5xx_count"
+  ],
+  "time_range": {
+    "start_at": "2026-04-08 14:20:00.123",
+    "end_at": "2026-04-08 14:30:00.123"
+  }
+}
+```
+
+## 5.8 查询应用拓扑
+
+`GET /api/demo/software-a/apps/{app_code}/topology?env=test`
+
+## 5.9 权限校验
+
+`POST /api/demo/software-a/permissions/check`
+
+请求示例:
+
+```json
+{
+  "operator": {
+    "user_id": "u1001",
+    "user_name": "alice"
+  },
+  "action_type": "DEPLOY",
+  "app_code": "order-service",
+  "env": "test"
+}
+```
+
+响应示例:
+
+```json
+{
+  "request_id": "req-sa-009",
+  "success": true,
+  "code": "OK",
+  "message": "success",
+  "data": {
+    "allowed": true,
+    "reason": ""
+  },
+  "timestamp": "2026-04-08 14:31:00.123"
+}
+```
+
+---
+
+## 6. 身份 Demo 接口
+
+## 6.1 设计说明
+
+身份 demo 用于 MVP 阶段闭环,不要求完全模拟现网身份系统,但必须支持:
+
+1. 登录。
+2. 用户信息查询。
+3. 角色信息查询。
+4. 基础权限集合返回。
+
+建议 base path:
+
+`/api/demo/identity`
+
+## 6.2 登录
+
+`POST /api/demo/identity/login`
+
+请求示例:
+
+```json
+{
+  "username": "alice",
+  "password": "demo-password"
+}
+```
+
+响应示例:
+
+```json
+{
+  "request_id": "req-id-001",
+  "success": true,
+  "code": "OK",
+  "message": "login success",
+  "data": {
+    "access_token": "demo-token-alice",
+    "expires_in_seconds": 7200,
+    "user": {
+      "user_id": "u1001",
+      "user_name": "alice",
+      "display_name": "Alice",
+      "roles": [
+        "DEPLOY_OPERATOR"
+      ],
+      "tenant_id": "tenant-demo"
+    }
+  },
+  "timestamp": "2026-04-08 14:00:00.123"
+}
+```
+
+## 6.3 获取当前用户信息
+
+`GET /api/demo/identity/me`
+
+## 6.4 查询用户权限
+
+`GET /api/demo/identity/users/{user_id}/permissions`
+
+响应 `data` 建议包含:
+
+1. `user_id`
+2. `roles`
+3. `permissions`
+4. `allowed_envs`
+5. `allowed_apps`
+
+## 6.5 验证 Token
+
+`POST /api/demo/identity/token/introspect`
+
+---
+
+## 7. 审批 Demo 接口
+
+## 7.1 设计说明
+
+审批 demo 用于高风险动作闭环,至少支持:
+
+1. 创建审批单。
+2. 查询审批单。
+3. 通过或驳回审批。
+4. 审批记录留痕。
+
+建议 base path:
+
+`/api/demo/approval`
+
+## 7.2 创建审批单
+
+`POST /api/demo/approval/requests`
+
+请求示例:
+
+```json
+{
+  "task_id": "task-20260408-888",
+  "risk_level": "HIGH",
+  "operator": {
+    "user_id": "u1001",
+    "user_name": "alice"
+  },
+  "action_type": "RESTART_SERVICE",
+  "target": {
+    "app_code": "user-service",
+    "env": "prod"
+  },
+  "reason": "生产故障恢复",
+  "approvers": [
+    "u2001"
+  ]
+}
+```
+
+响应示例:
+
+```json
+{
+  "request_id": "req-ap-001",
+  "success": true,
+  "code": "OK",
+  "message": "approval created",
+  "data": {
+    "approval_id": "ap-20260408-001",
+    "approval_status": "PENDING"
+  },
+  "timestamp": "2026-04-08 14:40:00.123"
+}
+```
+
+## 7.3 查询审批单
+
+`GET /api/demo/approval/requests/{approval_id}`
+
+## 7.4 审批决策
+
+`POST /api/demo/approval/requests/{approval_id}/decision`
+
+请求示例:
+
+```json
+{
+  "decision": "APPROVED",
+  "comment": "同意执行",
+  "operator": {
+    "user_id": "u2001",
+    "user_name": "bob"
+  }
+}
+```
+
+`decision` 可选值:
+
+```json
+["APPROVED", "REJECTED"]
+```
+
+## 7.5 查询待审批列表
+
+`GET /api/demo/approval/requests?approval_status=PENDING&approver_user_id=u2001`
+
+---
+
+## 8. 建议的内部对象结构
+
+## 8.1 Task 对象
+
+```json
+{
+  "task_id": "task-20260408-001",
+  "session_id": "sess-001",
+  "tenant_id": "tenant-demo",
+  "operator": {
+    "user_id": "u1001",
+    "user_name": "alice"
+  },
+  "action_type": "DEPLOY",
+  "app_code": "order-service",
+  "env": "test",
+  "version": "1.2.3",
+  "target_nodes": [
+    "10.0.0.12"
+  ],
+  "risk_level": "MEDIUM",
+  "approval_status": "NOT_REQUIRED",
+  "task_status": "RUNNING"
+}
+```
+
+## 8.2 ToolCall 对象
+
+```json
+{
+  "tool_call_id": "tool-call-001",
+  "task_id": "task-20260408-001",
+  "tool_name": "deploy_package",
+  "request_payload": {},
+  "response_payload": {},
+  "success": true,
+  "duration_ms": 1200,
+  "started_at": "2026-04-08 14:31:00.123",
+  "finished_at": "2026-04-08 14:31:01.456"
+}
+```
+
+## 8.3 Approval 对象
+
+```json
+{
+  "approval_id": "ap-20260408-001",
+  "task_id": "task-20260408-888",
+  "approval_status": "PENDING",
+  "approvers": [
+    "u2001"
+  ],
+  "decision_logs": []
+}
+```
+
+---
+
+## 9. 典型时序
+
+## 9.1 部署时序
+
+1. 用户调用 `POST /api/agent/tasks` 发起自然语言请求。
+2. Agent 完成解析并返回 `task_id` 和结构化结果。
+3. 用户调用确认接口。
+4. Agent 调用身份 demo 获取操作者信息和权限。
+5. Agent 调用软件 A demo 权限校验。
+6. Agent 调用软件 A demo 创建部署任务。
+7. Agent 轮询软件 A demo 查询状态。
+8. Agent 调用 Edge 接口执行本地验证。
+9. Agent 汇总结果,更新任务状态并生成报告。
+
+## 9.2 高风险审批时序
+
+1. 用户发起高风险任务。
+2. Agent 判定需要审批。
+3. Agent 调用审批 demo 创建审批单。
+4. 审批人完成审批。
+5. Agent 检查审批结果。
+6. 审批通过后进入执行。
+
+---
+
+## 10. demo 与正式系统的替换原则
+
+1. Agent 上层只依赖统一语义接口,不直接依赖 demo 接口字段差异。
+2. 软件 A demo、身份 demo、审批 demo 均应封装在适配层后面。
+3. 后续替换真实系统时,优先保持上层对象模型不变。
+4. 如真实系统能力不足,应在适配层内做降级,而不是修改编排主链路。
+
+---
+
+## 11. 推荐开发顺序
+
+1. 先完成通用响应格式、错误码和枚举定义。
+2. 再完成 Agent 对外任务接口。
+3. 再完成软件 A demo 接口。
+4. 再完成身份 demo 和审批 demo。
+5. 最后完成本地 Agent 拉取任务与结果回传接口。
+
+这样可以最短路径打通 MVP 主链路。
diff --git a/智能化部署agent-当前进度总结.md.txt b/智能化部署agent-当前进度总结.md.txt
new file mode 100644
index 0000000..447b1ac
--- /dev/null
+++ b/智能化部署agent-当前进度总结.md.txt
@@ -0,0 +1,242 @@
+# 智能化部署 Agent 当前进度总结
+
+更新时间:2026-04-08
+
+## 1. 当前总体状态
+
+当前阶段已完成从"需求方案"到"技术架构"再到"接口定义"和"demo 后端骨架"的文档化收敛,整体处于:
+
+**方案已成型、文档体系已建立、技术路线已基本明确、代码尚未开始实现**
+
+当前产出重点仍然是文档设计,不是代码开发。
+
+---
+
+## 2. 已完成的文档产出
+
+当前目录已形成以下核心文档:
+
+1. `智能化部署agent.md`
+   用于描述项目目标、场景、总体方案、风险、安全和实施路线。
+
+2. `智能化部署agent-技术架构设计说明书.md`
+   用于描述系统架构、模块分层、数据模型、接口建议、安全设计和实施约束。
+
+3. `智能化部署agent-demo接口定义说明.md`
+   用于描述 demo 阶段的接口协议、统一响应格式、状态枚举、Agent 接口、软件 A demo 接口、身份 demo 接口、审批 demo 接口。
+
+4. `智能化部署agent-demo后端项目骨架设计.md`
+   用于描述 demo 后端的推荐技术栈、项目结构、模块职责、数据库表建议、代码落点和开发顺序。
+
+5. `智能化部署agent-技术架构设计说明书.backup-20260408-141109.md`
+   为技术架构说明书备份文件。
+
+---
+
+## 3. 已完成的主要工作
+
+### 3.1 方案文档已重写
+
+已解决原始文档存在的编码和可读性问题,并重写为结构化方案文档,覆盖:
+
+1. 项目目标。
+2. 产品定位。
+3. 核心需求拆解。
+4. 风险分析。
+5. 开源对标。
+6. MVP 范围。
+7. 实施路线。
+
+### 3.2 技术架构说明书已形成
+
+已形成较完整的技术架构设计说明书,覆盖:
+
+1. 总体架构分层。
+2. 核心模块职责。
+3. 云端与本地部署架构。
+4. 软件 A 集成设计。
+5. 数据模型。
+6. 接口设计建议。
+7. 关键流程设计。
+8. 安全设计。
+9. 非功能设计。
+
+### 3.3 已确认前提已写入架构文档
+
+以下前提已被整理并写入技术架构设计说明书:
+
+1. MVP 阶段先开发 demo 版软件 A,不直接对接真实软件 A。
+2. 软件 A 的操作者透传和权限能力在 demo 阶段由 demo 实现承接。
+3. 本地 Agent 部署环境为 Windows 和 Linux 混合环境。
+4. 试点应用部署方式统一。
+5. 审批系统和身份系统在现网可能已有接口,但当前阶段无法直接接入,需开发 demo 版闭环。
+6. 模型接入方式支持自定义 `base_url` 和 `api_key`。
+
+### 3.4 接口文档已形成
+
+demo 接口定义文档已覆盖:
+
+1. Agent 对外任务接口。
+2. 云端与本地 Agent 交互接口。
+3. 软件 A demo 接口。
+4. 身份 demo 接口。
+5. 审批 demo 接口。
+6. 内部对象结构。
+7. 典型时序。
+
+### 3.5 文档规范已统一
+
+已统一以下文档规范:
+
+1. 时间字段格式统一为 `yyyy-MM-dd HH:mm:ss.SSS`
+2. 默认时区统一为 `Asia/Shanghai`
+3. JSON 字段统一采用 `snake_case`
+4. 字段命名规则统一为:
+   `*_id`、`*_status`、`*_type`、`*_at`、`*_ms`、`*_count`
+
+### 3.6 demo 后端骨架设计已完成
+
+已完成 demo 后端项目骨架设计,明确:
+
+1. 推荐采用单体后端服务 + 模块化分层。
+2. 推荐技术栈为 Python + FastAPI + LangGraph。
+3. 后端目录结构和模块边界。
+4. 核心 service 划分。
+5. 数据库表建议。
+6. 本地 Agent 骨架建议。
+7. 开发顺序建议。
+
+---
+
+## 4. 当前已明确的核心技术结论
+
+### 4.1 架构方向
+
+当前建议的总体方向是:
+
+**软件 A 做执行底座,Agent 做智能编排层,本地 Agent 做受控执行器**
+
+### 4.2 MVP 路线
+
+当前 MVP 路线已经收敛为:
+
+1. 自然语言发起任务。
+2. Agent 解析意图并做结构化任务生成。
+3. 策略层做风险判断。
+4. 调用软件 A demo 执行部署或控制动作。
+5. 调用本地 Agent 做验证。
+6. 汇总结果,生成报告和审计。
+
+### 4.3 技术选型方向
+
+当前建议方向:
+
+1. 编排框架优先 LangGraph。
+2. demo 后端优先 Python + FastAPI。
+3. 用户端本地 Agent 采用受控执行模式。
+4. 所有外部系统统一通过 adapter 接入。
+
+### 4.4 用户端 Python 运行方式建议
+
+当前讨论结论是:
+
+1. 用户端不应依赖客户现场预装 Python。
+2. 本地 Agent 应做成"自带运行时"的便携包。
+3. Windows 可采用 embeddable Python 或等价便携运行方式。
+4. Linux 可采用自包含运行目录或可执行打包方式。
+
+该结论已明确,但尚未系统性回写到所有设计文档。
+
+### 4.5 数据库选择建议
+
+当前讨论结论是:
+
+1. 正式路线可以采用 PostgreSQL。
+2. 如果以 demo 快速落地和减少安装成本为优先,可以先用 SQLite。
+3. 后续试点或正式化阶段再切换 PostgreSQL。
+
+该结论属于当前建议,尚未完整回写到骨架设计文档中。
+
+### 4.6 开源和商用许可判断
+
+当前讨论结论是:
+
+1. Python、FastAPI、LangGraph、Pydantic、SQLAlchemy、PostgreSQL 等组件,整体上适合免费使用和商用。
+2. Redis 的许可证情况相对复杂,不建议在文档中简单视为"低风险宽松开源"。
+3. 如果确实需要 Redis 类组件,后续应评估 Valkey 或在 demo 阶段先不强依赖缓存中间件。
+
+该结论属于当前建议,尚未完整回写到骨架设计文档中。
+
+---
+
+## 5. 当前尚未开始的部分
+
+目前尚未开始以下工作:
+
+1. demo 后端初始化代码。
+2. 本地 Agent 初始化代码。
+3. 数据库建表脚本。
+4. OpenAPI 文档生成。
+5. 软件 A demo 服务实现。
+6. 身份 demo 服务实现。
+7. 审批 demo 服务实现。
+8. 验证插件实现。
+9. 部署脚本和运行脚本。
+10. 测试用例与联调脚本。
+
+---
+
+## 6. 当前存在的待落地事项
+
+虽然整体文档体系已比较完整,但仍有几项内容尚未真正落到可运行层面:
+
+1. 是否正式确认 demo 阶段使用 SQLite 还是 PostgreSQL。
+2. 是否正式确认 Redis 在 demo 阶段保留、替换还是去掉。
+3. 是否正式确认用户端 Agent 的交付格式:
+   Windows zip 包、Linux tar.gz 包,或单文件可执行包。
+4. 是否继续补数据库 DDL 文档。
+5. 是否继续补 OpenAPI 草案。
+6. 是否直接开始生成 demo 后端代码骨架。
+
+---
+
+## 7. 建议的下一步
+
+按当前进度,建议后续按以下顺序推进:
+
+### 路线 A:继续补文档后再开发
+
+1. 补数据库 DDL 设计。
+2. 补 OpenAPI 草案。
+3. 将 SQLite / PostgreSQL、Redis / Valkey、用户端 Python 便携运行方案正式回写到文档。
+
+适合:
+
+1. 先把设计收口到可以评审。
+2. 由多人协作开发前需要统一边界。
+
+### 路线 B:直接进入 demo 代码骨架
+
+1. 生成 FastAPI 后端项目初始化代码。
+2. 生成核心目录结构和空实现。
+3. 先打通 `POST /api/agent/tasks`、确认任务、查询任务三条主接口。
+4. 再补软件 A demo adapter、身份 demo adapter、审批 demo adapter。
+
+适合:
+
+1. 尽快进入实现阶段。
+2. 通过代码反推细节问题。
+
+当前更推荐:
+
+**先补最小 DDL 和 OpenAPI 草案,然后直接进入 demo 后端代码骨架。**
+
+---
+
+## 8. 当前一句话结论
+
+目前不是"还在想法阶段",而是已经完成了:
+
+**方案文档 -> 技术架构 -> 接口定义 -> 后端骨架**
+
+下一步已经可以从"写文档"切换到"写 demo 代码"。
diff --git a/智能化部署agent-技术架构设计说明书.backup-20260408-141109.md.txt b/智能化部署agent-技术架构设计说明书.backup-20260408-141109.md.txt
new file mode 100644
index 0000000..e55ed9e
--- /dev/null
+++ b/智能化部署agent-技术架构设计说明书.backup-20260408-141109.md.txt
@@ -0,0 +1,871 @@
+# 智能化部署 Agent 技术架构设计说明书
+
+## 1. 文档说明
+
+### 1.1 文档目的
+
+本文档用于在《智能化部署 Agent 方案建议》基础上,进一步细化系统技术架构设计,作为后续研发、联调、评审、实施和试点落地的依据。
+
+本文档重点回答以下问题:
+
+1. 系统由哪些模块组成。
+2. 云端与本地分别承担什么职责。
+3. 软件 A 如何被接入和封装。
+4. Agent 如何安全地调用部署、验证、日志、监控和第三方接口能力。
+5. 高危动作如何被拦截、确认、审批和审计。
+6. MVP 阶段应实现哪些能力,哪些能力暂缓。
+
+### 1.2 适用范围
+
+本文档适用于:
+
+1. 研发架构设计。
+2. 软件 A 集成设计。
+3. 本地 Agent 设计。
+4. 安全评审。
+5. MVP 实施和试点。
+
+### 1.3 设计原则
+
+1. 复用软件 A,避免重复建设部署底座。
+2. 所有执行必须受控,禁止模型直接自由执行命令。
+3. 先覆盖标准场景,再扩展复杂场景。
+4. 结论以工具证据为准,不以模型主观推断为准。
+5. 安全、审批、审计与功能同级建设。
+
+---
+
+## 2. 建设目标
+
+## 2.1 业务目标
+
+建设一套支持自然语言交互的智能部署与验证 Agent,面向软件交付、实施和运维场景,完成以下工作:
+
+1. 触发标准化软件部署,优先支持 Java 应用。
+2. 调用软件 A 完成部署包推送、配置推送、任务执行和状态查询。
+3. 执行日志检查、进程检查、端口检查、健康检查、第三方接口联调验证。
+4. 输出标准化执行报告和结果结论。
+5. 在生产等高风险场景下实现权限、审批、确认和审计。
+
+## 2.2 技术目标
+
+1. 建立统一的 Agent 编排层。
+2. 建立统一的工具适配层。
+3. 建立云端编排与本地执行分离架构。
+4. 建立统一的任务模型、工具结果模型和审计模型。
+5. 建立面向高风险动作的安全控制机制。
+
+## 2.3 MVP 目标
+
+MVP 目标是打通一条完整闭环:
+
+> 用户自然语言输入 -> Agent 识别任务 -> 策略校验 -> 调用软件 A -> 本地验证 -> 结果汇总 -> 审计留痕
+
+---
+
+## 3. 总体架构设计
+
+## 3.1 架构概览
+
+系统采用"云端智能编排 + 本地受控执行 + 软件 A 作为执行底座"的总体架构。
+
+### 3.1.1 云端核心职责
+
+1. 用户接入与身份认证。
+2. 大模型推理与任务理解。
+3. 任务编排与状态流转。
+4. 风险识别与策略决策。
+5. 审批、审计和结果归档。
+
+### 3.1.2 本地核心职责
+
+1. 执行云端下发的结构化任务。
+2. 调用软件 A 本地可达能力。
+3. 调用本地验证工具。
+4. 回传结构化结果和执行证据。
+
+### 3.1.3 软件 A 的职责
+
+1. 作为部署和配置下发的主执行引擎。
+2. 提供部署任务状态查询能力。
+3. 提供日志、监控、配置等基础运维数据能力。
+
+## 3.2 架构分层
+
+系统分为六层:
+
+### 第一层:接入层
+
+负责:
+
+1. Web 控制台。
+2. 企业 IM 机器人。
+3. OpenAPI 接口。
+
+### 第二层:会话与任务层
+
+负责:
+
+1. 会话管理。
+2. 用户上下文管理。
+3. 原始输入记录。
+4. 任务创建与任务状态管理。
+
+### 第三层:Agent 编排层
+
+负责:
+
+1. 意图识别。
+2. 参数抽取。
+3. 缺参澄清。
+4. 任务规划。
+5. 工具路由。
+6. 结果总结。
+
+### 第四层:策略治理层
+
+负责:
+
+1. 身份与权限校验。
+2. 风险分级。
+3. 二次确认。
+4. 审批流。
+5. 幂等控制。
+6. 执行限流。
+7. 审计日志。
+
+### 第五层:工具适配层
+
+负责:
+
+1. 软件 A 适配器。
+2. 本地验证适配器。
+3. 第三方接口适配器。
+
+### 第六层:执行与观测层
+
+负责:
+
+1. 云端任务调度。
+2. 本地 Agent 执行器。
+3. 日志、指标、Trace、审计采集。
+
+---
+
+## 4. 核心模块设计
+
+## 4.1 接入层
+
+### 4.1.1 Web 控制台
+
+建议提供以下能力:
+
+1. 对话输入。
+2. 任务执行确认。
+3. 审批处理。
+4. 执行报告展示。
+5. 审计查询。
+
+### 4.1.2 企业 IM 机器人
+
+适合:
+
+1. 快速发起查询类任务。
+2. 快速发起测试/预发部署任务。
+3. 审批通知和结果通知。
+
+### 4.1.3 OpenAPI
+
+用于:
+
+1. 第三方系统发起标准任务。
+2. 自动化平台对接。
+3. 审批和工单系统集成。
+
+## 4.2 会话与任务层
+
+### 4.2.1 会话管理
+
+职责:
+
+1. 维护用户会话上下文。
+2. 关联最近任务。
+3. 支持多轮澄清。
+
+### 4.2.2 任务管理
+
+任务状态建议至少包括:
+
+1. `CREATED`
+2. `PENDING_CONFIRM`
+3. `PENDING_APPROVAL`
+4. `RUNNING`
+5. `VERIFYING`
+6. `SUCCEEDED`
+7. `FAILED`
+8. `PARTIAL_SUCCEEDED`
+9. `CANCELLED`
+
+### 4.2.3 上下文约束
+
+会话层不应将全部历史数据无边界提供给模型,建议:
+
+1. 只传最近相关任务。
+2. 对日志和工具结果做摘要。
+3. 通过结构化上下文替代长文本拼接。
+
+## 4.3 Agent 编排层
+
+建议采用状态机方式实现,优先选择 LangGraph 类框架。
+
+### 4.3.1 编排节点建议
+
+建议包含以下节点:
+
+1. `intent_parse`
+2. `slot_extract`
+3. `task_normalize`
+4. `risk_evaluate`
+5. `confirm_required`
+6. `approval_required`
+7. `tool_dispatch`
+8. `verify_dispatch`
+9. `result_summarize`
+10. `audit_persist`
+
+### 4.3.2 编排输入
+
+输入至少包括:
+
+1. 用户信息。
+2. 原始文本。
+3. 会话上下文。
+4. 环境信息。
+5. 应用元数据。
+6. 风险规则。
+
+### 4.3.3 编排输出
+
+输出至少包括:
+
+1. 标准化动作类型。
+2. 结构化参数。
+3. 风险等级。
+4. 任务执行计划。
+5. 工具调用列表。
+6. 最终结论。
+
+## 4.4 策略治理层
+
+策略治理层必须在模型之外独立实现。
+
+### 4.4.1 权限控制
+
+建议同时支持:
+
+1. RBAC:按角色授权。
+2. ABAC:按环境、应用、租户、动作类型做属性控制。
+
+### 4.4.2 风险分级
+
+建议按以下维度综合计算:
+
+1. 环境级别。
+2. 动作类型。
+3. 是否影响生产流量。
+4. 是否涉及配置变更。
+5. 是否涉及回滚或停机。
+
+### 4.4.3 审批流
+
+审批流建议支持:
+
+1. 单人审批。
+2. 多级审批。
+3. 超时失效。
+4. 审批驳回。
+5. 审批记录审计。
+
+### 4.4.4 幂等与并发控制
+
+建议实现:
+
+1. 任务唯一请求 ID。
+2. 同一应用同一环境互斥执行。
+3. 防止重复部署。
+4. 防止同一审批结果重复使用。
+
+## 4.5 工具适配层
+
+### 4.5.1 设计目标
+
+工具适配层的目标是将不同系统封装成统一可调用能力,避免编排层直接依赖外部系统差异。
+
+### 4.5.2 统一工具协议
+
+建议每个工具遵循统一协议:
+
+输入:
+
+1. `tool_name`
+2. `request_id`
+3. `operator`
+4. `target`
+5. `params`
+
+输出:
+
+1. `success`
+2. `code`
+3. `message`
+4. `data`
+5. `evidence`
+6. `retryable`
+7. `duration_ms`
+8. `timestamp`
+
+### 4.5.3 软件 A 适配器
+
+建议封装以下能力:
+
+1. `deploy_package`
+2. `push_config`
+3. `start_service`
+4. `stop_service`
+5. `restart_service`
+6. `rollback_service`
+7. `query_deploy_task`
+8. `query_logs`
+9. `query_alerts`
+10. `query_metrics`
+
+### 4.5.4 本地验证适配器
+
+建议封装:
+
+1. `check_process`
+2. `check_port`
+3. `http_health_check`
+4. `tcp_probe`
+5. `grep_log`
+6. `jvm_status`
+7. `disk_space_check`
+
+### 4.5.5 第三方接口适配器
+
+建议封装:
+
+1. `invoke_http_api`
+2. `query_cmdb`
+3. `query_config_center`
+4. `create_ticket`
+5. `send_notification`
+
+## 4.6 本地 Agent 执行器
+
+### 4.6.1 核心职责
+
+1. 校验任务签名。
+2. 鉴权与策略匹配。
+3. 执行工具调用。
+4. 采集执行证据。
+5. 回传执行结果。
+
+### 4.6.2 执行约束
+
+1. 不提供自由 Shell 能力。
+2. 仅允许调用白名单工具。
+3. 每个工具独立参数校验。
+4. 每个工具有超时控制。
+5. 每次执行都写审计日志。
+
+---
+
+## 5. 云端与本地部署架构
+
+## 5.1 部署拓扑
+
+建议部署为两部分:
+
+### 云端服务
+
+1. API 网关。
+2. Agent 编排服务。
+3. 策略引擎服务。
+4. 审批与审计服务。
+5. 元数据服务。
+6. 任务中心。
+7. 模型网关。
+
+### 本地服务
+
+1. 本地 Agent。
+2. 本地工具插件。
+3. 本地缓存与任务队列。
+4. 本地审计日志模块。
+
+## 5.2 通信模式
+
+建议采用"云端下发结构化任务,本地回传结构化结果"的方式,避免传输自由文本命令。
+
+通信要求:
+
+1. 双向 TLS。
+2. 设备身份认证。
+3. 请求签名。
+4. 任务过期时间。
+5. 重放保护。
+
+## 5.3 弱网与离线处理
+
+建议支持:
+
+1. 本地任务重试。
+2. 网络恢复后结果补传。
+3. 审批未完成任务不得离线执行。
+4. 高风险任务必须在线校验策略。
+
+---
+
+## 6. 软件 A 集成设计
+
+## 6.1 集成方式
+
+优先级建议如下:
+
+1. 首选 API / SDK 集成。
+2. 其次通过网关封装内部接口。
+3. 不建议通过页面自动化方式集成。
+
+## 6.2 软件 A 接口能力清单
+
+建议与软件 A 对接时确认以下能力:
+
+1. 部署任务创建。
+2. 配置推送。
+3. 应用启停。
+4. 回滚能力。
+5. 任务状态查询。
+6. 日志查询。
+7. 告警查询。
+8. 指标查询。
+9. 应用拓扑查询。
+10. 权限透传或操作者记录。
+
+## 6.3 软件 A 适配器设计要求
+
+1. 对外暴露统一语义接口。
+2. 屏蔽软件 A 错误码差异。
+3. 将软件 A 错误转换为统一错误模型。
+4. 保留软件 A 原始任务 ID 以便追溯。
+
+## 6.4 失败处理设计
+
+需要区分:
+
+1. 调用失败。
+2. 任务创建成功但执行失败。
+3. 软件 A 返回成功但验证失败。
+4. 查询超时或状态不确定。
+
+---
+
+## 7. 数据模型设计
+
+## 7.1 应用元数据模型
+
+建议字段:
+
+1. `app_code`
+2. `app_name`
+3. `env`
+4. `deploy_type`
+5. `package_type`
+6. `service_start_mode`
+7. `health_check_url`
+8. `log_paths`
+9. `listen_ports`
+10. `dependencies`
+11. `config_templates`
+12. `rollback_policy`
+13. `owner`
+14. `risk_level`
+
+## 7.2 任务模型
+
+建议字段:
+
+1. `task_id`
+2. `session_id`
+3. `tenant_id`
+4. `operator`
+5. `intent_type`
+6. `action_type`
+7. `app_code`
+8. `env`
+9. `version`
+10. `target_nodes`
+11. `risk_level`
+12. `approval_status`
+13. `task_status`
+14. `plan_snapshot`
+15. `result_summary`
+16. `created_at`
+17. `updated_at`
+
+## 7.3 工具调用模型
+
+建议字段:
+
+1. `tool_call_id`
+2. `task_id`
+3. `tool_name`
+4. `request_payload`
+5. `response_payload`
+6. `success`
+7. `duration_ms`
+8. `started_at`
+9. `finished_at`
+
+## 7.4 审计模型
+
+建议字段:
+
+1. `audit_id`
+2. `task_id`
+3. `operator`
+4. `action`
+5. `target`
+6. `risk_level`
+7. `approval_trace`
+8. `tool_trace`
+9. `result`
+10. `timestamp`
+
+---
+
+## 8. 接口设计建议
+
+## 8.1 对话任务接口
+
+### 8.1.1 创建任务
+
+`POST /api/agent/tasks`
+
+请求示例字段:
+
+1. `input_text`
+2. `channel`
+3. `session_id`
+4. `tenant_id`
+
+返回字段:
+
+1. `task_id`
+2. `parsed_intent`
+3. `missing_slots`
+4. `risk_level`
+5. `next_action`
+
+### 8.1.2 查询任务状态
+
+`GET /api/agent/tasks/{task_id}`
+
+返回字段:
+
+1. `task_status`
+2. `approval_status`
+3. `tool_calls`
+4. `verification_result`
+5. `summary`
+
+## 8.2 审批接口
+
+### 8.2.1 提交审批
+
+`POST /api/agent/approvals`
+
+### 8.2.2 审批通过/驳回
+
+`POST /api/agent/approvals/{approval_id}/decision`
+
+## 8.3 本地 Agent 回调接口
+
+### 8.3.1 拉取任务
+
+`POST /api/agent/edge/tasks/pull`
+
+### 8.3.2 回传结果
+
+`POST /api/agent/edge/tasks/report`
+
+## 8.4 软件 A 适配器内部接口
+
+建议内部抽象接口:
+
+1. `createDeployTask`
+2. `queryDeployTask`
+3. `pushConfig`
+4. `restartService`
+5. `queryLogs`
+6. `queryMetrics`
+
+---
+
+## 9. 关键流程设计
+
+## 9.1 部署流程
+
+1. 用户输入部署请求。
+2. Agent 解析意图并抽取参数。
+3. 若缺参则澄清。
+4. 风险引擎计算风险等级。
+5. 若需确认或审批,则进入等待状态。
+6. 调用软件 A 创建部署任务。
+7. 查询部署状态直到完成或超时。
+8. 调用本地验证工具执行校验。
+9. 汇总证据并输出结论。
+10. 写入审计。
+
+## 9.2 日志查询流程
+
+1. 用户输入日志查询请求。
+2. Agent 识别应用、环境、时间范围和关键字。
+3. 调用软件 A 或本地日志工具查询。
+4. 进行摘要和异常聚合。
+5. 输出结果。
+
+## 9.3 第三方接口联调验证流程
+
+1. 用户输入联调验证请求。
+2. Agent 路由到第三方接口工具。
+3. 获取响应码、响应体、耗时。
+4. 必要时结合日志和监控交叉验证。
+5. 输出验证结论。
+
+## 9.4 生产环境高危操作流程
+
+1. 判定为高风险操作。
+2. 执行权限校验。
+3. 执行二次确认。
+4. 发起审批。
+5. 审批通过后再执行。
+6. 执行完成后自动验证。
+7. 写入完整审计链路。
+
+---
+
+## 10. 安全设计
+
+## 10.1 身份认证
+
+建议:
+
+1. 用户通过统一身份认证系统接入。
+2. 本地 Agent 使用设备证书认证。
+3. 内部服务间使用服务身份认证。
+
+## 10.2 权限控制
+
+按以下维度控制:
+
+1. 用户角色。
+2. 租户。
+3. 应用。
+4. 环境。
+5. 动作类型。
+
+## 10.3 敏感数据保护
+
+1. Token、密钥、密码不进入模型上下文。
+2. 日志和配置默认脱敏。
+3. 用户展示层默认隐藏敏感字段。
+
+## 10.4 Prompt Injection 防护
+
+1. 所有日志、接口响应、配置文本视为不可信数据。
+2. 不允许外部文本影响系统策略与审批逻辑。
+3. 模型只能建议,不直接突破策略层。
+
+## 10.5 本地执行安全
+
+1. 工具白名单。
+2. 参数白名单和格式校验。
+3. 最小系统权限运行。
+4. 限制出站访问范围。
+5. 每个工具独立超时和资源限制。
+
+## 10.6 审计要求
+
+必须审计:
+
+1. 原始输入。
+2. 解析结果。
+3. 风险结果。
+4. 审批结果。
+5. 工具调用。
+6. 验证结果。
+7. 最终结论。
+
+---
+
+## 11. 非功能设计
+
+## 11.1 可用性
+
+1. 核心服务支持水平扩展。
+2. 任务执行状态可恢复。
+3. 外部系统短时失败可重试。
+
+## 11.2 稳定性
+
+1. 每类工具单独超时控制。
+2. 异常分类处理。
+3. 长任务支持轮询与中断。
+
+## 11.3 可观测性
+
+建议采集:
+
+1. 接口日志。
+2. 工具调用日志。
+3. 任务状态流转日志。
+4. Trace。
+5. 指标监控。
+
+## 11.4 可扩展性
+
+1. 工具插件化。
+2. 应用元数据可配置化。
+3. 策略规则可扩展。
+4. 支持后续增加更多部署类型和中间件类型。
+
+---
+
+## 12. 技术选型建议
+
+## 12.1 编排框架
+
+推荐:
+
+1. LangGraph 作为核心编排框架。
+
+理由:
+
+1. 更适合状态机和受控执行流程。
+2. 更适合插入确认、审批和人工干预。
+3. 更适合长期维护和审计追溯。
+
+## 12.2 快速原型方案
+
+如果需要快速演示,可选:
+
+1. Dify 作为前台工作流和对话原型。
+
+但长期建议迁移回代码化编排。
+
+## 12.3 执行引擎
+
+推荐:
+
+1. 软件 A 作为主执行引擎。
+2. AWX 或 Rundeck 作为补充能力,不作为主底座。
+
+## 12.4 模型接入
+
+建议采用模型网关方式,屏蔽底层模型差异,并统一处理:
+
+1. Prompt 模板。
+2. 模型选择。
+3. 调用审计。
+4. 敏感信息过滤。
+
+---
+
+## 13. MVP 范围与边界
+
+## 13.1 MVP 纳入范围
+
+1. Java 应用标准部署。
+2. 配置推送。
+3. 服务启停/重启。
+4. 日志查询。
+5. 进程/端口/HTTP 健康检查。
+6. 审批和二次确认。
+7. 审计留痕。
+
+## 13.2 MVP 暂不纳入
+
+1. 任意命令执行。
+2. 复杂自治型多 Agent。
+3. 自动根因分析闭环。
+4. 无人审批的生产自动处置。
+5. 全类型应用和全中间件覆盖。
+
+---
+
+## 14. 实施建议
+
+## 14.1 第一阶段:接口与元数据梳理
+
+输出:
+
+1. 软件 A 接口清单。
+2. 试点应用元数据模板。
+3. 风险规则表。
+4. 工具协议定义。
+
+## 14.2 第二阶段:核心链路开发
+
+输出:
+
+1. 对话任务接口。
+2. 编排服务。
+3. 软件 A 适配器。
+4. 本地 Agent 基础执行器。
+5. 基础验证插件。
+
+## 14.3 第三阶段:治理能力补齐
+
+输出:
+
+1. 审批接入。
+2. 审计中心。
+3. 任务中心。
+4. 权限模型。
+
+## 14.4 第四阶段:试点与优化
+
+输出:
+
+1. 试点应用上线。
+2. 指标统计。
+3. 问题闭环与优化清单。
+
+---
+
+## 15. 风险与待确认项
+
+以下内容需要尽快确认,否则会影响架构落地:
+
+1. 软件 A 当前是否有稳定 API/SDK。
+2. 软件 A 是否支持操作者透传和权限控制。
+3. 本地 Agent 部署环境是 Windows、Linux 还是混合。
+4. 试点应用的部署方式是否统一。
+5. 审批系统和身份系统是否已有标准接口。
+6. 模型是否允许使用云端服务,还是必须私有化。
+
+---
+
+## 16. 结论
+
+推荐将本项目建设为"受控执行型部署 Agent 平台",以软件 A 为执行底座,以 LangGraph 为编排核心,以本地 Agent 为边缘执行节点,以策略治理层保障高危动作安全。
+
+从工程落地看,最关键的不是模型能力本身,而是以下四点:
+
+1. 软件 A 能否提供稳定可调用接口。
+2. 应用元数据是否完整。
+3. 本地执行是否足够受控。
+4. 审批、权限、审计是否能真正闭环。
+
+如果以上四点落实,本项目具备较强的 MVP 落地可行性。
diff --git a/智能化部署agent-技术架构设计说明书.md.txt b/智能化部署agent-技术架构设计说明书.md.txt
new file mode 100644
index 0000000..9383c4a
--- /dev/null
+++ b/智能化部署agent-技术架构设计说明书.md.txt
@@ -0,0 +1,948 @@
+# 智能化部署 Agent 技术架构设计说明书
+
+## 1. 文档说明
+
+### 1.1 文档目的
+
+本文档用于在《智能化部署 Agent 方案建议》基础上,进一步细化系统技术架构设计,作为后续研发、联调、评审、实施和试点落地的依据。
+
+本文档重点回答以下问题:
+
+1. 系统由哪些模块组成。
+2. 云端与本地分别承担什么职责。
+3. 软件 A 如何被接入和封装。
+4. Agent 如何安全地调用部署、验证、日志、监控和第三方接口能力。
+5. 高危动作如何被拦截、确认、审批和审计。
+6. MVP 阶段应实现哪些能力,哪些能力暂缓。
+
+### 1.2 适用范围
+
+本文档适用于:
+
+1. 研发架构设计。
+2. 软件 A 集成设计。
+3. 本地 Agent 设计。
+4. 安全评审。
+5. MVP 实施和试点。
+
+### 1.3 设计原则
+
+1. 复用软件 A,避免重复建设部署底座。
+2. 所有执行必须受控,禁止模型直接自由执行命令。
+3. 先覆盖标准场景,再扩展复杂场景。
+4. 结论以工具证据为准,不以模型主观推断为准。
+5. 安全、审批、审计与功能同级建设。
+
+---
+
+## 2. 建设目标
+
+## 2.1 业务目标
+
+建设一套支持自然语言交互的智能部署与验证 Agent,面向软件交付、实施和运维场景,完成以下工作:
+
+1. 触发标准化软件部署,优先支持 Java 应用。
+2. 调用软件 A 完成部署包推送、配置推送、任务执行和状态查询。
+3. 执行日志检查、进程检查、端口检查、健康检查、第三方接口联调验证。
+4. 输出标准化执行报告和结果结论。
+5. 在生产等高风险场景下实现权限、审批、确认和审计。
+
+## 2.2 技术目标
+
+1. 建立统一的 Agent 编排层。
+2. 建立统一的工具适配层。
+3. 建立云端编排与本地执行分离架构。
+4. 建立统一的任务模型、工具结果模型和审计模型。
+5. 建立面向高风险动作的安全控制机制。
+
+## 2.3 MVP 目标
+
+MVP 目标是打通一条完整闭环:
+
+> 用户自然语言输入 -> Agent 识别任务 -> 策略校验 -> 调用软件 A -> 本地验证 -> 结果汇总 -> 审计留痕
+
+---
+
+## 3. 总体架构设计
+
+## 3.1 架构概览
+
+系统采用"云端智能编排 + 本地受控执行 + 软件 A 作为执行底座"的总体架构。
+
+### 3.1.1 云端核心职责
+
+1. 用户接入与身份认证。
+2. 大模型推理与任务理解。
+3. 任务编排与状态流转。
+4. 风险识别与策略决策。
+5. 审批、审计和结果归档。
+
+### 3.1.2 本地核心职责
+
+1. 执行云端下发的结构化任务。
+2. 调用软件 A 本地可达能力。
+3. 调用本地验证工具。
+4. 回传结构化结果和执行证据。
+
+### 3.1.3 软件 A 的职责
+
+1. 作为部署和配置下发的主执行引擎。
+2. 提供部署任务状态查询能力。
+3. 提供日志、监控、配置等基础运维数据能力。
+
+## 3.2 架构分层
+
+系统分为六层:
+
+### 第一层:接入层
+
+负责:
+
+1. Web 控制台。
+2. 企业 IM 机器人。
+3. OpenAPI 接口。
+
+### 第二层:会话与任务层
+
+负责:
+
+1. 会话管理。
+2. 用户上下文管理。
+3. 原始输入记录。
+4. 任务创建与任务状态管理。
+
+### 第三层:Agent 编排层
+
+负责:
+
+1. 意图识别。
+2. 参数抽取。
+3. 缺参澄清。
+4. 任务规划。
+5. 工具路由。
+6. 结果总结。
+
+### 第四层:策略治理层
+
+负责:
+
+1. 身份与权限校验。
+2. 风险分级。
+3. 二次确认。
+4. 审批流。
+5. 幂等控制。
+6. 执行限流。
+7. 审计日志。
+
+### 第五层:工具适配层
+
+负责:
+
+1. 软件 A 适配器。
+2. 本地验证适配器。
+3. 第三方接口适配器。
+
+### 第六层:执行与观测层
+
+负责:
+
+1. 云端任务调度。
+2. 本地 Agent 执行器。
+3. 日志、指标、Trace、审计采集。
+
+---
+
+## 4. 核心模块设计
+
+## 4.1 接入层
+
+### 4.1.1 Web 控制台
+
+建议提供以下能力:
+
+1. 对话输入。
+2. 任务执行确认。
+3. 审批处理。
+4. 执行报告展示。
+5. 审计查询。
+
+### 4.1.2 企业 IM 机器人
+
+适合:
+
+1. 快速发起查询类任务。
+2. 快速发起测试/预发部署任务。
+3. 审批通知和结果通知。
+
+### 4.1.3 OpenAPI
+
+用于:
+
+1. 第三方系统发起标准任务。
+2. 自动化平台对接。
+3. 审批和工单系统集成。
+
+## 4.2 会话与任务层
+
+### 4.2.1 会话管理
+
+职责:
+
+1. 维护用户会话上下文。
+2. 关联最近任务。
+3. 支持多轮澄清。
+
+### 4.2.2 任务管理
+
+任务状态建议至少包括:
+
+1. `CREATED`
+2. `PENDING_CONFIRM`
+3. `PENDING_APPROVAL`
+4. `RUNNING`
+5. `VERIFYING`
+6. `SUCCEEDED`
+7. `FAILED`
+8. `PARTIAL_SUCCEEDED`
+9. `CANCELLED`
+
+### 4.2.3 上下文约束
+
+会话层不应将全部历史数据无边界提供给模型,建议:
+
+1. 只传最近相关任务。
+2. 对日志和工具结果做摘要。
+3. 通过结构化上下文替代长文本拼接。
+
+## 4.3 Agent 编排层
+
+建议采用状态机方式实现,优先选择 LangGraph 类框架。
+
+### 4.3.1 编排节点建议
+
+建议包含以下节点:
+
+1. `intent_parse`
+2. `slot_extract`
+3. `task_normalize`
+4. `risk_evaluate`
+5. `confirm_required`
+6. `approval_required`
+7. `tool_dispatch`
+8. `verify_dispatch`
+9. `result_summarize`
+10. `audit_persist`
+
+### 4.3.2 编排输入
+
+输入至少包括:
+
+1. 用户信息。
+2. 原始文本。
+3. 会话上下文。
+4. 环境信息。
+5. 应用元数据。
+6. 风险规则。
+
+### 4.3.3 编排输出
+
+输出至少包括:
+
+1. 标准化动作类型。
+2. 结构化参数。
+3. 风险等级。
+4. 任务执行计划。
+5. 工具调用列表。
+6. 最终结论。
+
+## 4.4 策略治理层
+
+策略治理层必须在模型之外独立实现。
+
+### 4.4.1 权限控制
+
+建议同时支持:
+
+1. RBAC:按角色授权。
+2. ABAC:按环境、应用、租户、动作类型做属性控制。
+
+### 4.4.2 风险分级
+
+建议按以下维度综合计算:
+
+1. 环境级别。
+2. 动作类型。
+3. 是否影响生产流量。
+4. 是否涉及配置变更。
+5. 是否涉及回滚或停机。
+
+### 4.4.3 审批流
+
+审批流建议支持:
+
+1. 单人审批。
+2. 多级审批。
+3. 超时失效。
+4. 审批驳回。
+5. 审批记录审计。
+
+### 4.4.4 幂等与并发控制
+
+建议实现:
+
+1. 任务唯一请求 ID。
+2. 同一应用同一环境互斥执行。
+3. 防止重复部署。
+4. 防止同一审批结果重复使用。
+
+## 4.5 工具适配层
+
+### 4.5.1 设计目标
+
+工具适配层的目标是将不同系统封装成统一可调用能力,避免编排层直接依赖外部系统差异。
+
+### 4.5.2 统一工具协议
+
+建议每个工具遵循统一协议:
+
+输入:
+
+1. `tool_name`
+2. `request_id`
+3. `operator`
+4. `target`
+5. `params`
+
+输出:
+
+1. `success`
+2. `code`
+3. `message`
+4. `data`
+5. `evidence`
+6. `retryable`
+7. `duration_ms`
+8. `timestamp`
+
+### 4.5.3 软件 A 适配器
+
+建议封装以下能力:
+
+1. `deploy_package`
+2. `push_config`
+3. `start_service`
+4. `stop_service`
+5. `restart_service`
+6. `rollback_service`
+7. `query_deploy_task`
+8. `query_logs`
+9. `query_alerts`
+10. `query_metrics`
+
+### 4.5.4 本地验证适配器
+
+建议封装:
+
+1. `check_process`
+2. `check_port`
+3. `http_health_check`
+4. `tcp_probe`
+5. `grep_log`
+6. `jvm_status`
+7. `disk_space_check`
+
+### 4.5.5 第三方接口适配器
+
+建议封装:
+
+1. `invoke_http_api`
+2. `query_cmdb`
+3. `query_config_center`
+4. `create_ticket`
+5. `send_notification`
+
+## 4.6 本地 Agent 执行器
+
+### 4.6.1 核心职责
+
+1. 校验任务签名。
+2. 鉴权与策略匹配。
+3. 执行工具调用。
+4. 采集执行证据。
+5. 回传执行结果。
+
+### 4.6.2 执行约束
+
+1. 不提供自由 Shell 能力。
+2. 仅允许调用白名单工具。
+3. 每个工具独立参数校验。
+4. 每个工具有超时控制。
+5. 每次执行都写审计日志。
+
+---
+
+## 5. 云端与本地部署架构
+
+## 5.1 部署拓扑
+
+建议部署为两部分:
+
+### 云端服务
+
+1. API 网关。
+2. Agent 编排服务。
+3. 策略引擎服务。
+4. 审批与审计服务。
+5. 元数据服务。
+6. 任务中心。
+7. 模型网关。
+
+### 本地服务
+
+1. 本地 Agent。
+2. 本地工具插件。
+3. 本地缓存与任务队列。
+4. 本地审计日志模块。
+
+### 5.1.1 本地部署环境约束
+
+本地 Agent 部署环境确认为混合环境,需同时支持 Windows 和 Linux,并根据用户现场环境选择部署方式。
+
+因此架构上需满足:
+
+1. 本地 Agent 核心能力跨平台一致。
+2. 工具插件按操作系统实现适配层。
+3. 进程检查、端口检查、日志采集、服务控制等能力需区分 Windows 与 Linux 实现。
+4. 打包、安装、升级和日志路径配置需支持双平台差异。
+
+## 5.2 通信模式
+
+建议采用"云端下发结构化任务,本地回传结构化结果"的方式,避免传输自由文本命令。
+
+通信要求:
+
+1. 双向 TLS。
+2. 设备身份认证。
+3. 请求签名。
+4. 任务过期时间。
+5. 重放保护。
+
+## 5.3 弱网与离线处理
+
+建议支持:
+
+1. 本地任务重试。
+2. 网络恢复后结果补传。
+3. 审批未完成任务不得离线执行。
+4. 高风险任务必须在线校验策略。
+
+---
+
+## 6. 软件 A 集成设计
+
+## 6.1 集成方式
+
+优先级建议如下:
+
+1. 首选 API / SDK 集成。
+2. 其次通过网关封装内部接口。
+3. 不建议通过页面自动化方式集成。
+
+当前确认前提如下:
+
+1. MVP 阶段不直接对接真实软件 A。
+2. 需要先开发一个满足当前需求的 demo 版软件 A 接口层或模拟服务。
+3. 后续对接真实软件 A 时,预计仍需做接口适配或能力改造。
+
+## 6.2 软件 A 接口能力清单
+
+建议与软件 A 对接时确认以下能力:
+
+1. 部署任务创建。
+2. 配置推送。
+3. 应用启停。
+4. 回滚能力。
+5. 任务状态查询。
+6. 日志查询。
+7. 告警查询。
+8. 指标查询。
+9. 应用拓扑查询。
+10. 权限透传或操作者记录。
+
+基于当前已知前提,MVP 阶段建议 demo 版软件 A 至少提供以下能力:
+
+1. 部署任务创建与任务状态查询。
+2. 配置推送。
+3. 服务启停与重启。
+4. 基础日志查询。
+5. 操作者标识透传。
+6. 基础权限控制或最小可用权限校验。
+
+## 6.3 软件 A 适配器设计要求
+
+1. 对外暴露统一语义接口。
+2. 屏蔽软件 A 错误码差异。
+3. 将软件 A 错误转换为统一错误模型。
+4. 保留软件 A 原始任务 ID 以便追溯。
+5. 适配器接口需同时兼容 demo 版软件 A 和后续真实软件 A。
+6. 适配器内部应预留能力探测和版本兼容机制,避免后续接入真实软件 A 时推翻上层编排逻辑。
+
+## 6.4 失败处理设计
+
+需要区分:
+
+1. 调用失败。
+2. 任务创建成功但执行失败。
+3. 软件 A 返回成功但验证失败。
+4. 查询超时或状态不确定。
+
+对于 MVP 阶段,还需要额外区分:
+
+1. demo 版软件 A 能力未实现。
+2. demo 版接口与未来真实软件 A 语义不一致。
+3. 真实软件 A 接入后因接口缺口需要降级处理。
+
+---
+
+## 7. 数据模型设计
+
+本说明书中的时间字段,例如 `created_at`、`updated_at`、`started_at`、`finished_at`、`timestamp`,统一采用 `yyyy-MM-dd HH:mm:ss.SSS` 字符串格式,默认时区为 `Asia/Shanghai`。
+
+字段命名建议统一遵循以下规范:
+
+1. JSON 字段统一采用 `snake_case`。
+2. 主键和关联键统一使用 `*_id`。
+3. 状态字段统一使用 `*_status`。
+4. 类型字段统一使用 `*_type`。
+5. 时间点字段统一使用 `*_at`,通用响应时间可使用 `timestamp`。
+6. 毫秒级耗时统一使用 `*_ms`。
+7. 数量统计统一使用 `*_count`。
+8. 集合字段优先使用复数名词。
+
+## 7.1 应用元数据模型
+
+建议字段:
+
+1. `app_code`
+2. `app_name`
+3. `env`
+4. `deploy_type`
+5. `package_type`
+6. `service_start_mode`
+7. `health_check_url`
+8. `log_paths`
+9. `listen_ports`
+10. `dependencies`
+11. `config_templates`
+12. `rollback_policy`
+13. `owner`
+14. `risk_level`
+
+## 7.2 任务模型
+
+建议字段:
+
+1. `task_id`
+2. `session_id`
+3. `tenant_id`
+4. `operator`
+5. `intent_type`
+6. `action_type`
+7. `app_code`
+8. `env`
+9. `version`
+10. `target_nodes`
+11. `risk_level`
+12. `approval_status`
+13. `task_status`
+14. `plan_snapshot`
+15. `result_summary`
+16. `created_at`
+17. `updated_at`
+
+## 7.3 工具调用模型
+
+建议字段:
+
+1. `tool_call_id`
+2. `task_id`
+3. `tool_name`
+4. `request_payload`
+5. `response_payload`
+6. `success`
+7. `duration_ms`
+8. `started_at`
+9. `finished_at`
+
+## 7.4 审计模型
+
+建议字段:
+
+1. `audit_id`
+2. `task_id`
+3. `operator`
+4. `action`
+5. `target`
+6. `risk_level`
+7. `approval_trace`
+8. `tool_trace`
+9. `result`
+10. `timestamp`
+
+---
+
+## 8. 接口设计建议
+
+## 8.1 对话任务接口
+
+### 8.1.1 创建任务
+
+`POST /api/agent/tasks`
+
+请求示例字段:
+
+1. `input_text`
+2. `channel`
+3. `session_id`
+4. `tenant_id`
+
+返回字段:
+
+1. `task_id`
+2. `parsed_intent`
+3. `missing_slots`
+4. `risk_level`
+5. `next_action`
+
+### 8.1.2 查询任务状态
+
+`GET /api/agent/tasks/{task_id}`
+
+返回字段:
+
+1. `task_status`
+2. `approval_status`
+3. `tool_calls`
+4. `verification_result`
+5. `summary`
+
+## 8.2 审批接口
+
+### 8.2.1 提交审批
+
+`POST /api/agent/approvals`
+
+### 8.2.2 审批通过/驳回
+
+`POST /api/agent/approvals/{approval_id}/decision`
+
+## 8.3 本地 Agent 回调接口
+
+### 8.3.1 拉取任务
+
+`POST /api/agent/edge/tasks/pull`
+
+### 8.3.2 回传结果
+
+`POST /api/agent/edge/tasks/report`
+
+## 8.4 软件 A 适配器内部接口
+
+建议内部抽象接口:
+
+1. `create_deploy_task`
+2. `query_deploy_task`
+3. `push_config`
+4. `restart_service`
+5. `query_logs`
+6. `query_metrics`
+
+---
+
+## 9. 关键流程设计
+
+## 9.1 部署流程
+
+1. 用户输入部署请求。
+2. Agent 解析意图并抽取参数。
+3. 若缺参则澄清。
+4. 风险引擎计算风险等级。
+5. 若需确认或审批,则进入等待状态。
+6. 调用软件 A 创建部署任务。
+7. 查询部署状态直到完成或超时。
+8. 调用本地验证工具执行校验。
+9. 汇总证据并输出结论。
+10. 写入审计。
+
+## 9.2 日志查询流程
+
+1. 用户输入日志查询请求。
+2. Agent 识别应用、环境、时间范围和关键字。
+3. 调用软件 A 或本地日志工具查询。
+4. 进行摘要和异常聚合。
+5. 输出结果。
+
+## 9.3 第三方接口联调验证流程
+
+1. 用户输入联调验证请求。
+2. Agent 路由到第三方接口工具。
+3. 获取响应码、响应体、耗时。
+4. 必要时结合日志和监控交叉验证。
+5. 输出验证结论。
+
+## 9.4 生产环境高危操作流程
+
+1. 判定为高风险操作。
+2. 执行权限校验。
+3. 执行二次确认。
+4. 发起审批。
+5. 审批通过后再执行。
+6. 执行完成后自动验证。
+7. 写入完整审计链路。
+
+---
+
+## 10. 安全设计
+
+## 10.1 身份认证
+
+建议:
+
+1. 用户通过统一身份认证系统接入。
+2. 本地 Agent 使用设备证书认证。
+3. 内部服务间使用服务身份认证。
+
+当前确认前提如下:
+
+1. 现网可能已有身份系统标准接口,但当前阶段无法直接接入。
+2. MVP 阶段需开发 demo 版身份能力,用于完成登录、用户识别、角色识别和基础鉴权闭环。
+
+## 10.2 权限控制
+
+按以下维度控制:
+
+1. 用户角色。
+2. 租户。
+3. 应用。
+4. 环境。
+5. 动作类型。
+
+当前确认前提如下:
+
+1. 现网审批系统可能已有标准接口,但当前阶段无法直接接入。
+2. MVP 阶段需提供 demo 版审批能力,至少支持提交审批、审批通过、审批驳回和审批记录。
+
+## 10.3 敏感数据保护
+
+1. Token、密钥、密码不进入模型上下文。
+2. 日志和配置默认脱敏。
+3. 用户展示层默认隐藏敏感字段。
+
+## 10.4 Prompt Injection 防护
+
+1. 所有日志、接口响应、配置文本视为不可信数据。
+2. 不允许外部文本影响系统策略与审批逻辑。
+3. 模型只能建议,不直接突破策略层。
+
+## 10.5 本地执行安全
+
+1. 工具白名单。
+2. 参数白名单和格式校验。
+3. 最小系统权限运行。
+4. 限制出站访问范围。
+5. 每个工具独立超时和资源限制。
+
+## 10.6 审计要求
+
+必须审计:
+
+1. 原始输入。
+2. 解析结果。
+3. 风险结果。
+4. 审批结果。
+5. 工具调用。
+6. 验证结果。
+7. 最终结论。
+
+---
+
+## 11. 非功能设计
+
+## 11.1 可用性
+
+1. 核心服务支持水平扩展。
+2. 任务执行状态可恢复。
+3. 外部系统短时失败可重试。
+
+## 11.2 稳定性
+
+1. 每类工具单独超时控制。
+2. 异常分类处理。
+3. 长任务支持轮询与中断。
+
+## 11.3 可观测性
+
+建议采集:
+
+1. 接口日志。
+2. 工具调用日志。
+3. 任务状态流转日志。
+4. Trace。
+5. 指标监控。
+
+## 11.4 可扩展性
+
+1. 工具插件化。
+2. 应用元数据可配置化。
+3. 策略规则可扩展。
+4. 支持后续增加更多部署类型和中间件类型。
+
+---
+
+## 12. 技术选型建议
+
+## 12.1 编排框架
+
+推荐:
+
+1. LangGraph 作为核心编排框架。
+
+理由:
+
+1. 更适合状态机和受控执行流程。
+2. 更适合插入确认、审批和人工干预。
+3. 更适合长期维护和审计追溯。
+
+## 12.2 快速原型方案
+
+如果需要快速演示,可选:
+
+1. Dify 作为前台工作流和对话原型。
+
+但长期建议迁移回代码化编排。
+
+## 12.3 执行引擎
+
+推荐:
+
+1. 软件 A 作为主执行引擎。
+2. AWX 或 Rundeck 作为补充能力,不作为主底座。
+
+落地约束:
+
+1. MVP 阶段由 demo 版软件 A 承担主执行引擎角色。
+2. 正式阶段再对接真实软件 A,并通过适配层完成平滑切换。
+
+## 12.4 模型接入
+
+建议采用模型网关方式,屏蔽底层模型差异,并统一处理:
+
+1. Prompt 模板。
+2. 模型选择。
+3. 调用审计。
+4. 敏感信息过滤。
+
+模型接入前提已确认如下:
+
+1. 模型接入方式支持自定义 `base_url` 和 `api_key`。
+2. 因此架构上不强制限定为公有云模型或私有化模型。
+3. 模型网关需支持多模型源配置、动态切换和按租户配置接入参数。
+4. 模型网关需支持最小化敏感信息透传和调用审计。
+
+---
+
+## 13. MVP 范围与边界
+
+## 13.1 MVP 纳入范围
+
+1. Java 应用标准部署。
+2. 配置推送。
+3. 服务启停/重启。
+4. 日志查询。
+5. 进程/端口/HTTP 健康检查。
+6. 审批和二次确认。
+7. 审计留痕。
+
+## 13.2 MVP 暂不纳入
+
+1. 任意命令执行。
+2. 复杂自治型多 Agent。
+3. 自动根因分析闭环。
+4. 无人审批的生产自动处置。
+5. 全类型应用和全中间件覆盖。
+
+---
+
+## 14. 实施建议
+
+## 14.1 第一阶段:接口与元数据梳理
+
+输出:
+
+1. 软件 A 接口清单。
+2. 试点应用元数据模板。
+3. 风险规则表。
+4. 工具协议定义。
+
+## 14.2 第二阶段:核心链路开发
+
+输出:
+
+1. 对话任务接口。
+2. 编排服务。
+3. 软件 A 适配器。
+4. 本地 Agent 基础执行器。
+5. 基础验证插件。
+
+## 14.3 第三阶段:治理能力补齐
+
+输出:
+
+1. 审批接入。
+2. 审计中心。
+3. 任务中心。
+4. 权限模型。
+
+## 14.4 第四阶段:试点与优化
+
+输出:
+
+1. 试点应用上线。
+2. 指标统计。
+3. 问题闭环与优化清单。
+
+---
+
+## 15. 已确认前提与实施约束
+
+以下前提已确认,可作为后续研发与实施的固定输入:
+
+1. 当前不直接对接真实软件 A,MVP 阶段需开发 demo 版软件 A;后续对接真实软件 A 时可能仍需开发改造。
+2. 软件 A 的操作者透传和权限控制在 MVP 阶段由 demo 版能力承接,正式对接真实软件 A 时再评估透传和鉴权改造方案。
+3. 本地 Agent 部署环境为 Windows 和 Linux 混合环境,需按用户现场环境适配。
+4. 试点应用部署方式统一,这有利于先沉淀标准任务模型、标准验证模型和标准回滚策略。
+5. 审批系统和身份系统理论上有标准接口,但当前阶段无法直接提供,MVP 阶段需开发 demo 版能力闭环。
+6. 模型接入采用自定义 `base_url` 和 `api_key` 的方式,因此模型网关必须支持灵活配置,不预设单一模型厂商。
+
+基于以上前提,对实施的直接影响如下:
+
+1. MVP 应优先验证编排层、策略层、本地执行器和统一工具协议,不以真实外部系统对接完成度作为第一阶段阻塞项。
+2. 软件 A、审批系统、身份系统均需采用"适配层 + demo 实现 + 后续真实替换"的分层设计。
+3. 本地工具体系必须从一开始就考虑跨平台实现,避免后续从单平台重构。
+4. 试点应用部署方式统一,可优先围绕单一部署范式建设模板化能力。
+5. 模型网关需在配置、审计、安全过滤层面先抽象清楚,避免后续因模型源变化重构上层调用链路。
+
+---
+
+## 16. 结论
+
+推荐将本项目建设为"受控执行型部署 Agent 平台",以软件 A 为执行底座,以 LangGraph 为编排核心,以本地 Agent 为边缘执行节点,以策略治理层保障高危动作安全。
+
+从工程落地看,最关键的不是模型能力本身,而是以下四点:
+
+1. 软件 A 能否提供稳定可调用接口。
+2. 应用元数据是否完整。
+3. 本地执行是否足够受控。
+4. 审批、权限、审计是否能真正闭环。
+
+如果以上四点落实,本项目具备较强的 MVP 落地可行性。
diff --git a/智能化部署agent.md.txt b/智能化部署agent.md.txt
new file mode 100644
index 0000000..9131a69
--- /dev/null
+++ b/智能化部署agent.md.txt
@@ -0,0 +1,1037 @@
+# 智能化部署 Agent 方案建议
+
+## 1. 项目目标
+
+目标是建设一套面向软件部署与运维验证场景的智能化 Agent,支持云端与用户本地协同,通过自然语言对话完成以下工作:
+
+1. 软件部署,优先支持 Java 应用。
+2. 部署后日志验证、进程/端口/接口/健康检查。
+3. 调用现有软件 A 完成部署包推送、配置推送、监控与告警等动作。
+4. 调用第三方系统接口,完成联调验证、状态查询、数据校验等任务。
+5. 具备安全控制、风险分级、审批确认、审计留痕能力。
+6. 尽快形成 MVP,并逐步扩展到更多环境与应用类型。
+
+一句话定位:
+
+> 不是"让大模型自由操作机器",而是"让大模型理解意图,并驱动受控工具完成标准化部署与验证"。
+
+---
+
+## 2. 项目定位
+
+### 2.1 产品定位
+
+建议将本项目定位为:
+
+**软件 A 之上的智能编排与受控执行层**
+
+软件 A 已经具备部署包、配置文件推送、日志告警、监控仪表盘、配置管理等基础能力,因此 Agent 不应重复建设底层部署平台,而应重点补齐以下能力:
+
+1. 自然语言交互入口。
+2. 任务理解与结构化。
+3. 跨工具编排。
+4. 部署后自动验证。
+5. 风险控制与安全治理。
+6. 结果总结与可解释输出。
+
+### 2.2 边界定义
+
+Agent 应负责:
+
+1. 理解用户意图。
+2. 生成标准化任务。
+3. 路由到软件 A、本地验证工具、第三方接口工具。
+4. 汇总证据并输出结论。
+5. 对高风险动作实施拦截、确认、审批、审计。
+
+Agent 不应直接负责:
+
+1. 任意 Shell 命令的自由执行。
+2. 无边界地访问所有本地资源。
+3. 在生产环境自动执行未审批的高危动作。
+4. 以模型主观判断替代真实工具返回结果。
+
+---
+
+## 3. 核心需求拆解
+
+### 3.1 对话式部署
+
+用户希望通过自然语言完成标准动作,例如:
+
+- "把 order-service 1.2.3 部署到测试环境"
+- "重启预发环境的 payment-service"
+- "把配置模板 A 推到 customer-x 环境"
+
+Agent 需要具备:
+
+1. 意图识别。
+2. 参数提取。
+3. 缺失参数澄清。
+4. 执行前任务回显确认。
+5. 执行后结果总结。
+
+### 3.2 部署后验证
+
+部署完成后需要自动验证,而不是只看"任务执行成功"。
+
+建议至少包含:
+
+1. 日志关键字检查。
+2. 进程状态检查。
+3. 端口监听检查。
+4. HTTP/TCP 健康检查。
+5. 第三方接口联调验证。
+6. 监控指标和告警状态核验。
+
+### 3.3 第三方工具与接口调用
+
+除软件 A 外,还需要支持:
+
+1. 第三方业务接口调用。
+2. CMDB / 配置中心查询。
+3. 监控平台查询。
+4. 工单/审批系统对接。
+5. 消息通知系统对接。
+
+### 3.4 云端与本地协同
+
+Agent 会在云端和用户本地部署,因此必须明确职责:
+
+云端负责:
+
+1. 对话入口。
+2. LLM 推理。
+3. 编排与策略判断。
+4. 审批与审计。
+5. 多租户与权限治理。
+
+本地 Agent 负责:
+
+1. 调用软件 A 的本地能力或受控接口。
+2. 执行本地验证动作。
+3. 访问本地日志、进程、端口等资源。
+4. 回传结构化结果。
+
+### 3.5 安全治理
+
+这是本项目成败关键,不是附属需求。
+
+必须覆盖:
+
+1. 身份认证。
+2. RBAC / ABAC 权限控制。
+3. 高危动作二次确认或审批。
+4. 全链路审计。
+5. 最小权限执行。
+6. 凭据托管与脱敏。
+7. Prompt Injection / 日志注入防护。
+
+---
+
+## 4. 建设原则
+
+### 4.1 先复用,后增强
+
+优先复用软件 A 的能力,Agent 只做增量价值,不重复造轮子。
+
+### 4.2 先标准化,后智能化
+
+先沉淀标准部署流程、标准验证动作、标准回滚流程,再叠加自然语言入口和智能总结。
+
+### 4.3 先受控执行,后扩大权限
+
+所有执行必须通过白名单工具,不允许模型直接获得自由命令执行权。
+
+### 4.4 先测试/预发,后生产
+
+MVP 阶段优先覆盖测试环境和预发环境,生产环境能力必须单独加审批和灰度控制。
+
+### 4.5 先证据,后结论
+
+Agent 的结论必须来自工具返回的结构化证据,而不是模型猜测。
+
+---
+
+## 5. 推荐总体架构
+
+### 5.1 分层架构
+
+建议采用五层架构:
+
+#### 第一层:交互接入层
+
+包含:
+
+1. Web 控制台。
+2. 企业 IM 机器人。
+3. OpenAPI。
+
+职责:
+
+1. 用户认证。
+2. 对话接入。
+3. 操作确认。
+4. 结果展示。
+
+#### 第二层:Agent 编排层
+
+包含:
+
+1. 意图识别。
+2. 参数抽取。
+3. 多轮澄清。
+4. 任务规划。
+5. 工具路由。
+6. 结果汇总。
+7. 风险分级。
+
+这是智能核心,但不直接执行危险动作。
+
+#### 第三层:策略与治理层
+
+包含:
+
+1. 权限校验。
+2. 环境分级。
+3. 审批流。
+4. 高危动作拦截。
+5. 幂等控制。
+6. 速率限制。
+7. 审计日志。
+
+这一层必须独立存在,不能混在 Prompt 里。
+
+#### 第四层:工具适配层
+
+包含三类适配器:
+
+1. 软件 A 适配器。
+2. 本地验证工具适配器。
+3. 第三方系统适配器。
+
+工具适配器对 Agent 暴露统一接口,例如:
+
+- `deploy_package`
+- `push_config`
+- `restart_service`
+- `query_deploy_status`
+- `check_process`
+- `check_port`
+- `http_health_check`
+- `search_logs`
+- `call_third_party_api`
+
+#### 第五层:执行与观测层
+
+包含:
+
+1. 云端执行控制。
+2. 本地 Agent 执行沙箱。
+3. 日志采集。
+4. 指标采集。
+5. Trace / 审计记录。
+
+### 5.2 推荐执行链路
+
+以"部署 Java 应用到测试环境"为例:
+
+1. 用户输入:"把 order-service 1.2.3 部署到测试环境"
+2. Agent 抽取参数:应用、版本、环境、动作。
+3. 若信息不完整则澄清,例如缺少目标节点、配置模板。
+4. 风险引擎判断:测试环境、低风险,可直接执行。
+5. 调用软件 A:下发部署包、推送配置、启动服务。
+6. 获取软件 A 任务状态。
+7. 调用本地验证工具:进程、端口、日志、健康检查。
+8. 若需要,调用第三方接口做联调验证。
+9. 汇总证据,给出结论:成功 / 失败 / 部分成功。
+10. 写入审计记录,并生成可追溯执行报告。
+
+---
+
+## 6. 软件 A 的集成建议
+
+### 6.1 集成原则
+
+软件 A 应视为主执行引擎,Agent 对其做能力封装。
+
+### 6.2 建议对外抽象的标准工具
+
+建议至少封装以下工具能力:
+
+1. `deployPackage(app, env, version, nodes)`
+2. `pushConfig(app, env, configTemplate, configVersion)`
+3. `startService(app, env, nodes)`
+4. `stopService(app, env, nodes)`
+5. `restartService(app, env, nodes)`
+6. `rollbackService(app, env, targetVersion)`
+7. `getDeployTaskStatus(taskId)`
+8. `getAppLogs(app, env, timeRange, keywords)`
+9. `getAlerts(app, env, timeRange)`
+10. `getMetrics(app, env, metricNames, timeRange)`
+11. `getTopology(app, env)`
+12. `getConfigSnapshot(app, env)`
+
+### 6.3 对软件 A 的接口要求
+
+为了让 Agent 真正可落地,软件 A 最好具备以下接口特征:
+
+1. 有明确 API 或 SDK,而不是只靠页面操作。
+2. 支持任务状态查询。
+3. 支持结构化错误码与错误信息。
+4. 支持任务幂等和重试。
+5. 支持按应用、环境、节点查询。
+6. 支持权限透传或二次鉴权。
+
+如果软件 A 当前不具备这些能力,第一阶段应优先补齐 API 封装层。
+
+---
+
+## 7. 本地 Agent 设计建议
+
+### 7.1 本地 Agent 的职责
+
+本地 Agent 不是"迷你大模型",而是"受控执行器"。
+
+它只负责:
+
+1. 接收云端下发的结构化任务。
+2. 校验签名、权限、策略。
+3. 调用本地工具。
+4. 收集结果并返回。
+
+### 7.2 本地 Agent 的安全要求
+
+必须满足:
+
+1. 不暴露任意命令执行能力。
+2. 仅允许调用注册过的白名单工具。
+3. 工具参数做严格校验。
+4. 工具执行进程隔离。
+5. 使用最小 OS 权限运行。
+6. 通信使用双向认证。
+7. 支持证书轮换和吊销。
+8. 支持离线缓存与断点续传,但不离线放开权限。
+
+### 7.3 本地验证工具建议
+
+建议做成轻量插件式能力:
+
+1. `check_process`
+2. `check_port`
+3. `http_health_check`
+4. `tcp_probe`
+5. `grep_log`
+6. `tail_log_summary`
+7. `jvm_status`
+8. `disk_space_check`
+9. `dependent_service_check`
+
+对于 Java 应用,建议增加:
+
+1. JVM 进程识别。
+2. JAR/WAR 版本识别。
+3. GC / OOM 关键日志检测。
+4. Spring Boot Actuator 健康检查适配。
+
+---
+
+## 8. 风险分析与安全防护
+
+### 8.1 主要风险
+
+#### 风险 1:自然语言误解导致误操作
+
+例如环境识别错误、版本识别错误、目标应用识别错误。
+
+防护建议:
+
+1. 关键字段必须结构化确认。
+2. 生产环境必须二次确认。
+3. 高风险动作必须审批。
+4. 不允许模糊命令直接落地执行。
+
+#### 风险 2:模型幻觉导致错误判断
+
+例如任务失败却被总结为成功。
+
+防护建议:
+
+1. 结论只基于工具证据。
+2. 输出中区分"证据"和"判断"。
+3. 对关键结果设硬规则。
+
+#### 风险 3:Prompt Injection / 日志注入
+
+日志中可能包含"忽略之前指令""执行某命令"等恶意文本。
+
+防护建议:
+
+1. 外部日志和接口响应仅作为数据,不作为指令。
+2. 模型系统提示中明确禁止遵循外部文本指令。
+3. 高危动作必须经过策略层,而不是模型直接决定。
+
+#### 风险 4:本地 Agent 成为攻击入口
+
+防护建议:
+
+1. 工具白名单。
+2. 参数校验。
+3. 执行沙箱。
+4. 最小权限。
+5. 出站访问控制。
+6. 本地审计。
+
+#### 风险 5:敏感信息泄露
+
+例如日志、配置、Token、数据库连接串被送入模型。
+
+防护建议:
+
+1. 敏感字段脱敏。
+2. 凭据统一由密钥系统托管。
+3. 模型上下文中尽量不传原始密钥。
+4. 用户可见输出默认脱敏。
+
+#### 风险 6:云边协同链路被伪造或重放
+
+防护建议:
+
+1. 双向 TLS。
+2. 请求签名。
+3. 时间戳和 nonce。
+4. 命令幂等 ID。
+5. 过期校验。
+
+### 8.2 高危动作分级建议
+
+建议按环境和动作双维度分级:
+
+#### 低风险
+
+1. 查询日志。
+2. 查询监控。
+3. 查询部署状态。
+4. 测试环境健康检查。
+
+#### 中风险
+
+1. 测试/预发环境部署。
+2. 测试/预发环境重启服务。
+3. 配置下发但不立即生效。
+
+#### 高风险
+
+1. 生产环境部署。
+2. 生产环境重启/停止服务。
+3. 回滚。
+4. 配置变更立即生效。
+5. 对外部关键接口执行写操作。
+
+高风险动作建议要求:
+
+1. 权限校验。
+2. 二次确认。
+3. 审批流。
+4. 审计记录。
+5. 执行后自动验证。
+
+---
+
+## 9. 开源项目对标与选型建议
+
+以下是当前较适合参考的开源项目,重点看其是否适合作为"框架底座"而不是直接照搬。
+
+### 9.1 LangGraph
+
+定位:
+
+1. 适合做 Agent 编排状态机。
+2. 适合多步骤、可中断、可恢复、可插入人工审批的流程。
+
+优点:
+
+1. 对复杂工作流控制力强。
+2. 适合受控工具调用。
+3. 状态和执行链路清晰,适合审计和重试。
+
+不足:
+
+1. 偏工程化,需要自己搭治理层和业务层。
+2. 不是开箱即用的运维平台。
+
+适合本项目程度:
+
+**高**
+
+建议:
+
+作为核心编排框架优先考虑。
+
+参考:
+
+- https://github.com/langchain-ai/langgraph
+
+### 9.2 Dify
+
+定位:
+
+1. 适合快速做 AI 应用原型。
+2. 适合工作流、插件、知识库、可视化配置。
+
+优点:
+
+1. 上手快。
+2. UI 完整。
+3. 适合快速做 Demo 和 MVP。
+
+不足:
+
+1. 对复杂运维治理、细粒度权限、严格审批链路的定制深度有限。
+2. 作为核心执行编排引擎,灵活性不如代码化方案。
+
+适合本项目程度:
+
+**中高**
+
+建议:
+
+如果目标是"尽快出可演示版本",Dify 可以作为前台工作流原型平台;如果目标是长期可控、强治理,建议仅作为辅助手段,不建议做最终核心底座。
+
+参考:
+
+- https://github.com/langgenius/dify
+
+### 9.3 AWX
+
+定位:
+
+1. Ansible 的可视化与任务编排平台。
+2. 适合主机级批量自动化任务。
+
+优点:
+
+1. 在运维自动化领域成熟。
+2. 有权限、模板、任务执行基础设施。
+3. 对主机操作、批处理较友好。
+
+不足:
+
+1. 更偏自动化执行,不是 AI Agent 框架。
+2. 若软件 A 已覆盖部署能力,AWX 可能更多是补充而非主平台。
+
+适合本项目程度:
+
+**中**
+
+建议:
+
+当软件 A 对部分执行场景覆盖不足时,可作为补充执行引擎,不建议取代软件 A。
+
+参考:
+
+- https://github.com/ansible/awx
+
+### 9.4 Rundeck
+
+定位:
+
+1. 运维 Runbook 与受控任务执行平台。
+2. 擅长自助式操作、权限控制、审计。
+
+优点:
+
+1. 很适合高危任务受控执行。
+2. 审计、权限、作业化管理能力成熟。
+3. 适合承接"必须审批的标准作业"。
+
+不足:
+
+1. AI 编排能力弱,需要外部 Agent 驱动。
+2. 与软件 A 功能可能存在部分重叠。
+
+适合本项目程度:
+
+**中高**
+
+建议:
+
+如果后续要强化"生产环境受控执行"和"运维 Runbook 治理",Rundeck 很值得接入。
+
+参考:
+
+- https://github.com/rundeck/rundeck
+
+### 9.5 Kestra
+
+定位:
+
+1. 通用工作流编排平台。
+2. 擅长事件驱动与声明式流程。
+
+优点:
+
+1. 插件丰富。
+2. 工作流表达能力强。
+3. 适合作为通用流程编排底座。
+
+不足:
+
+1. 偏工作流平台,不是面向 AI 运维场景专门设计。
+2. 与软件 A、Agent 编排层会有一定职责重叠。
+
+适合本项目程度:
+
+**中**
+
+建议:
+
+更适合作为企业统一编排平台的候选,不是本项目 MVP 的优先选择。
+
+参考:
+
+- https://github.com/kestra-io/kestra
+
+### 9.6 AutoGen
+
+定位:
+
+1. 多 Agent 协作框架。
+
+优点:
+
+1. 适合复杂多智能体协作实验。
+
+不足:
+
+1. 本项目首期不需要多 Agent 复杂自治。
+2. 治理和受控执行不是它的强项。
+
+适合本项目程度:
+
+**低到中**
+
+建议:
+
+不建议作为第一阶段主框架。
+
+参考:
+
+- https://github.com/microsoft/autogen
+
+### 9.7 结论:推荐组合
+
+结合"尽快落地"和"安全可控"两个目标,建议优先采用:
+
+**方案 A:长期推荐**
+
+1. LangGraph 作为 Agent 编排核心。
+2. 软件 A 作为主执行引擎。
+3. 自研轻量本地 Agent 作为受控执行器。
+4. 自研策略层实现权限、审批、审计。
+5. 第三方接口通过插件适配器接入。
+
+适合:
+
+1. 需要长期演进。
+2. 需要较强治理和可控性。
+3. 需要深度适配软件 A。
+
+**方案 B:快速演示推荐**
+
+1. Dify 作为对话与工作流前台。
+2. 软件 A 作为主执行引擎。
+3. 本地验证能力先通过轻量插件封装。
+4. 后续再逐步迁移到代码化编排。
+
+适合:
+
+1. 先做 Demo。
+2. 先拿业务反馈。
+3. 研发资源有限。
+
+我的建议:
+
+**如果你们有 2 到 4 名可投入开发人员,优先走方案 A。**
+
+原因是该项目的核心难点不在"聊天",而在"受控执行、安全治理、结果可追溯",这些能力最终还是代码化编排更稳。
+
+---
+
+## 10. MVP 范围建议
+
+### 10.1 MVP 目标
+
+在最短周期内打通一条闭环:
+
+> 自然语言发起部署 -> 调用软件 A 执行 -> 自动验证 -> 输出结论 -> 记录审计
+
+### 10.2 MVP 必做功能
+
+#### A. 对话理解
+
+支持以下意图:
+
+1. 部署应用。
+2. 重启服务。
+3. 查询部署状态。
+4. 查看最近日志。
+5. 执行健康检查。
+
+#### B. 软件 A 接入
+
+至少打通:
+
+1. 部署包推送。
+2. 配置推送。
+3. 启停/重启服务。
+4. 查询任务状态。
+
+#### C. 自动验证
+
+至少包含:
+
+1. 进程检查。
+2. 端口检查。
+3. HTTP 健康检查。
+4. 日志关键字检查。
+
+#### D. 安全控制
+
+至少包含:
+
+1. 用户认证。
+2. RBAC。
+3. 环境分级。
+4. 高危动作二次确认。
+5. 审计留痕。
+
+#### E. 结果报告
+
+输出标准结果:
+
+1. 执行动作。
+2. 目标对象。
+3. 工具调用结果。
+4. 自动验证结果。
+5. 最终结论。
+6. 下一步建议。
+
+### 10.3 MVP 暂不纳入
+
+第一阶段不建议重投入以下能力:
+
+1. 全自动故障根因分析。
+2. 复杂多 Agent 自治协作。
+3. 任意命令执行。
+4. 全量中间件覆盖。
+5. 生产环境无人审批自动处置。
+
+---
+
+## 11. 关键数据模型建议
+
+### 11.1 应用元数据
+
+每个应用至少维护:
+
+1. 应用名。
+2. 所属环境。
+3. 部署方式。
+4. 部署包类型。
+5. 启停方式。
+6. 健康检查地址。
+7. 日志路径。
+8. 监听端口。
+9. 依赖接口。
+10. 配置模板。
+11. 回滚策略。
+12. 负责人。
+
+### 11.2 任务模型
+
+每次任务记录:
+
+1. 用户。
+2. 原始输入。
+3. 标准化意图。
+4. 结构化参数。
+5. 风险等级。
+6. 是否需要审批。
+7. 工具调用轨迹。
+8. 执行证据。
+9. 最终结论。
+10. 审计时间线。
+
+### 11.3 工具结果模型
+
+每次工具调用统一返回:
+
+1. `success`
+2. `code`
+3. `message`
+4. `data`
+5. `evidence`
+6. `retryable`
+7. `timestamp`
+
+这样方便编排层做标准判断。
+
+---
+
+## 12. 典型场景设计
+
+### 场景 1:部署 Java 应用到测试环境
+
+输入:
+
+"把 order-service 1.2.3 部署到测试环境"
+
+执行:
+
+1. 识别应用、版本、环境。
+2. 调用软件 A 执行部署。
+3. 等待任务完成。
+4. 校验进程、端口、健康检查。
+5. 搜索最近 10 分钟 ERROR 日志。
+6. 输出结论。
+
+### 场景 2:验证刚刚部署结果
+
+输入:
+
+"看下刚才部署成功没有"
+
+执行:
+
+1. 关联最近一次任务。
+2. 获取软件 A 执行状态。
+3. 获取日志和健康检查结果。
+4. 生成结论。
+
+### 场景 3:查询错误日志
+
+输入:
+
+"查看 payment-service 最近 10 分钟有没有 ERROR"
+
+执行:
+
+1. 定位应用和环境。
+2. 获取日志摘要。
+3. 统计 ERROR/WARN。
+4. 输出关键异常摘要。
+
+### 场景 4:第三方接口联调验证
+
+输入:
+
+"调用订单创建接口,验证链路是否打通"
+
+执行:
+
+1. 使用预定义第三方接口工具发起调用。
+2. 检查响应码、关键字段、耗时。
+3. 结合目标应用日志进行交叉验证。
+
+### 场景 5:生产环境高危操作
+
+输入:
+
+"重启生产环境 user-service"
+
+执行:
+
+1. 判定高风险。
+2. 权限校验。
+3. 二次确认。
+4. 走审批流。
+5. 审批通过后执行。
+6. 自动验证并审计。
+
+---
+
+## 13. 实施路线建议
+
+### 13.1 第一阶段:标准化梳理,1 到 2 周
+
+输出:
+
+1. 目标应用清单。
+2. 软件 A 接口清单。
+3. 标准部署流程。
+4. 标准验证清单。
+5. 高危动作分级规则。
+
+重点不是写代码,而是把边界和标准动作定义清楚。
+
+### 13.2 第二阶段:MVP 开发,2 到 4 周
+
+输出:
+
+1. Agent 原型。
+2. 软件 A 适配层。
+3. 本地验证插件。
+4. RBAC 与审计基础能力。
+5. 测试环境闭环。
+
+### 13.3 第三阶段:试点应用接入,2 到 4 周
+
+建议选择 1 到 3 个 Java 应用试点:
+
+1. 部署流程相对标准。
+2. 依赖链路适中。
+3. 有明确负责人。
+
+输出:
+
+1. 试点报告。
+2. 问题清单。
+3. 指标评估。
+
+### 13.4 第四阶段:增强治理与扩展场景
+
+逐步加入:
+
+1. 生产环境审批。
+2. 回滚建议。
+3. 更多第三方接口。
+4. 更多应用类型。
+5. 告警联动与半自动处置。
+
+---
+
+## 14. MVP 成功标准
+
+建议用以下指标验收:
+
+1. 至少接入 1 到 3 个 Java 应用。
+2. 测试环境标准部署成功率达到预期。
+3. 自动验证覆盖率达到核心检查项。
+4. 用户可通过自然语言完成核心操作。
+5. 高危动作有确认、审批和审计。
+6. 平均部署验证耗时相对人工流程明显下降。
+7. 出现失败时能给出可追溯证据和明确下一步建议。
+
+---
+
+## 15. 需要尽快补齐的未尽事宜
+
+以下事项建议尽早明确,否则后续容易卡住:
+
+### 15.1 软件 A 能力摸底
+
+需要确认:
+
+1. 是否已有 API / SDK。
+2. 是否支持异步任务查询。
+3. 是否支持节点级操作。
+4. 是否支持权限透传。
+5. 是否支持日志/监控/配置的统一查询。
+
+### 15.2 应用元数据治理
+
+如果没有统一应用元数据,Agent 很难稳定执行。
+
+需要补:
+
+1. 应用清单。
+2. 环境清单。
+3. 节点清单。
+4. 部署方式定义。
+5. 健康检查定义。
+6. 回滚定义。
+
+### 15.3 审批与工单流程
+
+需要明确:
+
+1. 哪些动作必须审批。
+2. 谁能审批。
+3. 审批系统是否已有。
+4. 审批失败如何处理。
+
+### 15.4 凭据与密钥管理
+
+需要明确:
+
+1. API Token 放在哪里。
+2. 本地 Agent 如何安全取凭据。
+3. 模型上下文如何避免泄露敏感信息。
+
+### 15.5 模型部署策略
+
+需要明确:
+
+1. 云端模型还是私有化模型。
+2. 哪些数据允许送入云模型。
+3. 哪些场景必须走私有化推理。
+
+### 15.6 失败与回滚策略
+
+需要定义:
+
+1. 哪些失败自动停止。
+2. 哪些失败允许重试。
+3. 哪些失败触发人工介入。
+4. 哪些失败可以建议回滚。
+
+---
+
+## 16. 最终建议
+
+### 16.1 是否值得做
+
+值得做,而且适合尽快启动 MVP。
+
+原因:
+
+1. 场景明确,价值直接。
+2. 软件 A 已提供良好的执行基础设施。
+3. Java 应用部署与验证动作高度标准化,适合 Agent 化。
+
+### 16.2 推荐落地策略
+
+建议采用:
+
+1. 软件 A 继续做执行底座。
+2. LangGraph 做核心编排。
+3. 本地 Agent 做受控执行器。
+4. 优先做测试/预发环境。
+5. 先覆盖标准部署、验证、日志检查、接口联调四类场景。
+
+### 16.3 不建议的方向
+
+不建议一开始就追求:
+
+1. 全自动生产运维。
+2. 模型自由执行命令。
+3. 大而全平台。
+4. 复杂多 Agent 自治系统。
+
+### 16.4 推荐的第一批交付物
+
+建议马上形成以下四份输出:
+
+1. 软件 A 能力与接口清单。
+2. 试点应用元数据模板。
+3. 高危动作与审批规则。
+4. MVP 原型设计与接口定义。
+
+---
+
+## 17. 参考开源项目
+
+以下信息基于 2026-04-08 可公开访问的官方仓库页面整理:
+
+1. LangGraph: https://github.com/langchain-ai/langgraph
+2. Dify: https://github.com/langgenius/dify
+3. AWX: https://github.com/ansible/awx
+4. Rundeck: https://github.com/rundeck/rundeck
+5. Kestra: https://github.com/kestra-io/kestra
+6. AutoGen: https://github.com/microsoft/autogen
+
+如果下一步需要,我可以继续补两类内容:
+
+1. 把这份文档继续细化成"技术架构设计说明书"。
+2. 直接基于这份方案,在当前目录继续产出 MVP 的接口定义、模块拆分和实施任务清单。