auto_agent/智能化部署agent-当前进度总结.md

# 智能化部署 Agent 当前进度总结

更新时间:2026-04-09

## 1. 当前总体状态

当前阶段已完成从"需求方案"到"技术架构"再到"接口定义"和"demo 后端骨架"的文档化收敛,整体处于:

**方案已成型、文档体系已建立、技术路线已基本明确、demo 后端主链路已可运行**

当前产出重点已经从纯文档设计切换为:

**文档收口 + demo 代码骨架落地 + 主链路验证**

---

## 2. 已完成的文档产出

当前目录已形成以下核心文档:

1. `智能化部署agent.md`
   用于描述项目目标、场景、总体方案、风险、安全和实施路线。

2. `智能化部署agent-技术架构设计说明书.md`
   用于描述系统架构、模块分层、数据模型、接口建议、安全设计和实施约束。

3. `智能化部署agent-demo接口定义说明.md`
   用于描述 demo 阶段的接口协议、统一响应格式、状态枚举、Agent 接口、软件 A 最小能力实现接口、身份 demo 接口、审批 demo 接口。

4. `智能化部署agent-demo后端项目骨架设计.md`
   用于描述 demo 后端的推荐技术栈、项目结构、模块职责、数据库表建议、代码落点和开发顺序。

5. `docs/智能化部署agent-demo最小DDL设计.md`
   用于沉淀 demo 阶段最小可运行的数据表结构。

6. `docs/智能化部署agent-demo首批OpenAPI.yaml`
   用于沉淀第一批已收口接口的 OpenAPI 草案。

7. `智能化部署agent-技术架构设计说明书.backup-20260408-141109.md`
   为技术架构说明书备份文件。
8. `edge-agent/README.md` 及 `edge-agent/app/*`
   用于沉淀本地 edge-agent 初始化代码骨架与运行说明。

---

## 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 最小能力实现接口。
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. 开发顺序建议。

### 3.7 demo 后端初始化代码已开始落地

当前已完成以下代码层工作:

1. 已生成 FastAPI demo 后端项目基础目录。
2. 已补充 `pyproject.toml`、基础 `README` 和 `.gitignore`。
3. 已实现 `task`、`approval_request`、`tool_call`、`audit_log` 对应的最小模型和数据库初始化逻辑。
4. 已打通三条主接口:
   `POST /api/agent/tasks`、`POST /api/agent/tasks/{task_id}/confirm`、`GET /api/agent/tasks/{task_id}`
5. 已实现最小 `identity demo`、`approval demo`、`software-a 最小能力实现接口`。
6. 已将高风险任务确认后的审批创建流程接入后端主链路。
7. 已实现最小 `edge` 心跳、拉取任务、回传结果接口。
8. 已将默认验证任务接入 edge 调度主链路。
9. 已将 `software-a` 最小能力部署任务创建接入主执行链。
10. 已将 `tool_call` 和 `audit_log` 接入主链路关键动作。
11. 已实现任务报告接口,可返回审批、工具、验证、审计轨迹。
12. 已实现任务取消接口,并将 `request_id`、`operator` 维度写入关键审计和工具调用记录。
13. 已补充自动化测试,并基于内存 SQLite 完成首轮通过验证。
14. 已完成任务状态机第一轮收紧,补上重复确认、审批后任务状态漂移、edge 重复回传等冲突校验。
15. 已补上首轮失败分支细化,包括 software-a 最小能力实现执行失败、审批驳回、edge 验证失败三条主失败路径。
16. 已完成 `duration_ms` 第一轮落地,`tool_call` 和 edge 验证轨迹可基于 `started_at` / `finished_at` 自动计算并返回时长。
17. 已完成结果摘要第一轮结构化改造,任务详情和任务报告可返回 `result_summary_detail`,包含最终状态、失败原因、software-a 摘要、审批摘要和验证摘要。
18. 已补充任务报告级聚合指标 `task_metrics`,可返回总耗时、确认等待耗时、审批耗时、执行耗时、工具耗时汇总、验证耗时汇总及相关计数。
19. 已补充失败路径与幂等性测试,覆盖创建任务幂等、重复审批决策冲突、错误 edge 回传冲突、重复取消冲突等场景。
20. 已创建本地 `edge-agent` 初始化骨架,包含配置加载、后端客户端、工具注册、`http_health_check` 执行器、轮询调度器与启动入口。
21. 已补充 `edge-agent` 启动脚本与便携打包脚本,覆盖 Windows `zip` 与 Linux `tar.gz` 两类交付方向。
22. 已补充 `edge-agent` 基础测试,覆盖 `http_health_check` 执行器和轮询调度器主路径。
23. 已补充 `edge-agent` 基础执行器实现,新增 `check_port`、`check_process`、`grep_log` 三类能力并接入工具注册表。

### 3.8 当前代码可运行范围

截至当前回合,后端代码已具备以下最小可运行范围:

1. 任务创建、确认、查询、取消。
2. 高风险任务确认后自动创建审批单。
3. 审批通过后进入执行链,审批驳回后进入取消态。
4. 执行链包含:
   software-a 权限校验 -> software-a 最小能力部署任务创建 -> edge 默认验证任务创建 -> edge 拉取 -> edge 回传。
5. 任务详情接口可返回:
   当前状态、software-a 状态、工具调用摘要、验证结果摘要。
6. 任务报告接口可返回:
   `task_basic`、`intent_snapshot`、`approval_trace`、`tool_trace`、`verification_trace`、`result_summary`、`audit_trace`
7. edge 侧已支持:
   心跳、拉取任务、回传结果、上报异常事件。
8. 执行指标当前已支持:
   `tool_trace.duration_ms`、`verification_trace.duration_ms` 与 `task_metrics`
9. 结果摘要当前已支持:
   `result_summary_detail.final_status`、`final_reason`、`software_a`、`approval`、`verification`
10. 本地 `edge-agent` 当前已具备最小启动骨架:
   心跳、拉取任务、执行 `http_health_check`、回传结果、上报异常。
11. 本地 `edge-agent` 当前已具备:
   启动脚本、打包脚本、基础执行器测试和轮询调度测试。
12. 本地 `edge-agent` 当前已具备已注册工具:
   `http_health_check`、`check_port`、`check_process`、`grep_log`

当前测试基线:

1. 共 20 条测试通过。
2. 使用 `sqlite:///:memory:` 做回归验证。
3. 当前主链路已不是“只有接口壳”,而是具备最小闭环行为。
4. `edge-agent` 侧基础测试共 10 条通过。

---

## 4. 当前已明确的核心技术结论

### 4.1 架构方向

当前建议的总体方向是:

**软件 A 做执行底座,Agent 做智能编排层,本地 Agent 做受控执行器**

### 4.2 MVP 路线

当前 MVP 路线已经收敛为:

1. 自然语言发起任务。
2. Agent 解析意图并做结构化任务生成。
3. 策略层做风险判断。
4. 调用软件 A 最小能力实现执行部署或控制动作。
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。

该结论已在本轮决策、最小 DDL 和当前后端实现中落地。

### 4.6 开源和商用许可判断

当前讨论结论是:

1. Python、FastAPI、LangGraph、Pydantic、SQLAlchemy、PostgreSQL 等组件,整体上适合免费使用和商用。
2. Redis 的许可证情况相对复杂,不建议在文档中简单视为"低风险宽松开源"。
3. 如果确实需要 Redis 类组件,后续应评估 Valkey 或在 demo 阶段先不强依赖缓存中间件。

该结论已收口为当前 demo 阶段“不引入 Redis 强依赖”的正式实现策略。

### 4.7 本轮正式落地决策

本轮已正式确认以下落地决策,后续实现与文档以此为准:

1. demo 数据库默认采用 `SQLite`,后续试点和正式化阶段再切换 `PostgreSQL`。
2. demo 阶段不引入 `Redis` 强依赖,缓存能力默认弱化,任务队列先采用数据库表 + 后台轮询方式承接。
3. 用户端 `edge-agent` 交付格式正式确认为:
   Windows 使用 `zip` 便携包,Linux 使用 `tar.gz` 自包含运行目录。
4. 文档补充策略正式确认为:
   只补最小 DDL 和首批 OpenAPI 草案,不一次性扩展到全部表和全部接口。
5. 开发顺序正式确认为:
   先补最小 DDL 和首批 OpenAPI,再直接进入 FastAPI demo 后端骨架开发。

### 4.8 当前代码层关键实现约定

以下约定虽然部分未完整回写到全部设计文档,但当前代码实现已经以此为准:

1. 任务主状态机当前主要覆盖:
   `CREATED` -> `PENDING_CONFIRM` -> `RUNNING` -> `VERIFYING` -> `SUCCEEDED` / `FAILED` / `CANCELLED`
2. 高风险任务路径为:
   `PENDING_CONFIRM` -> `PENDING_APPROVAL` -> `RUNNING`
3. `software-a` 最小能力实现当前在任务详情查询时会同步刷新状态,因此:
   确认接口返回的 `software_a_task_status` 可能是 `RUNNING`,而后续查询任务详情时可能已变为 `SUCCEEDED`
4. 当前 demo 中的 operator 默认使用:
   `alice(u1001)` 作为任务发起和执行方,`bob(u2001)` 作为审批人
5. 当前 edge 默认验证工具为:
   `http_health_check`
6. 当前默认 edge 节点 ID 为:
   `edge-shanghai-001`
7. 当前任务报告中的 `tool_trace` 和 `audit_trace` 已包含 `request_id` 和 operator 信息,后续扩展应保持兼容。
8. 当前已补上的状态约束包括:
   重复确认拦截、重复执行拦截、审批决策前必须仍处于 `PENDING_APPROVAL`、edge 重复回传拦截、非 `RUNNING` 任务不再下发 edge 执行。
9. 当前 demo 已支持可控失败模拟:
   若 `app_code` 或 `version` 包含 `fail`,则 `software-a` 最小能力实现会返回失败任务,用于联调失败分支。

---

## 5. 当前待补强的部分

当前还未收口,或仅实现了最小版本的工作包括:

1. 本地 `edge-agent` 初始化代码与打包脚本已完成第一轮,但尚未接入私有 Python 运行时和真正的便携发布流程。
2. 文件型 SQLite / PostgreSQL 实库运行验证。
3. 身份 demo / 审批 demo 与任务主链路的权限、审批决策联动细化。
4. 任务级聚合指标已完成第一轮,但更细的任务级指标拆分仍可继续增强,如等待时长细分、失败步骤占比、阶段级统计。
5. 更真实的验证插件实现,尤其是服务控制、日志时间范围过滤、进程指标扩展。
6. 部署脚本和运行脚本进一步完善,包括私有运行时打包。
7. OpenAPI 扩展到第二批接口。
8. 更多测试用例与联调脚本。

### 5.1 当前已知环境限制

以下问题不是当前代码逻辑错误,而是当前运行环境限制:

1. 当前对话环境下,文件型 SQLite 落盘会出现 `disk I/O error`。
2. 因此当前自动化验证统一采用:
   `DATABASE_URL=sqlite:///:memory:`
3. 当前测试命令需禁用 pytest cache provider,否则可能因写缓存目录失败出现噪音告警。
4. PowerShell 内联脚本在中文字符串场景下可能有编码干扰,因此测试样例优先使用 ASCII 文本。

---

## 6. 当前待落地重点

当前不是继续补基础文档,而是继续补强现有可运行链路。优先级建议收敛为:

1. 增补失败路径与幂等性测试:
   已完成一轮,后续可继续补回滚和更细冲突场景。
2. 继续丰富审计细节与任务级指标拆分:
   让任务级总耗时、审批耗时、等待耗时、阶段时长边界更直观。
3. 再补更多执行指标:
   如失败步骤占比、阶段级耗时拆分、任务级成功率统计。
4. 然后再继续:
   本地 `edge-agent` 执行器增强、第二批 OpenAPI、更多联调能力。

当前状态:

**SQLite / 去 Redis / 最小 DDL / 首批 OpenAPI / FastAPI 骨架 / 主接口 / demo adapter / edge 接口 / 第一轮任务级聚合指标 / 第一轮失败与幂等性测试 / edge-agent 初始化骨架 / edge-agent 启动与打包脚本 / edge-agent 基础测试,均已完成第一轮落地。**

---

## 7. 建议的下一步

按当前进度,建议后续直接按以下顺序推进:

1. 增补状态冲突、失败回滚、重复上报等测试。
2. 再补更多任务级执行指标。
3. 继续增强审计细节。
4. 再进入本地 `edge-agent` 初始化代码和第二批 OpenAPI。

当前更推荐:

**继续迭代代码主链路,不再回到“大段补文档”的节奏。**

### 7.1 如果下一轮需要快速续接,优先做什么

如果后续上下文被裁剪,建议下一轮直接先读取本文件,然后按以下顺序继续:

1. 优先读取:
   `backend/README.md`
2. 再读取关键代码入口:
   `backend/app/main.py`
   `backend/app/api/agent/tasks.py`
   `backend/app/services/task_service.py`
   `backend/app/services/approval_service.py`
   `backend/app/services/edge_service.py`
3. 再读取测试:
   `backend/tests/test_task_api.py`

下一步推荐顺序:

1. 再补更细的任务级指标拆分。
2. 再补审计细节和聚合摘要。
3. 继续补本地 Agent 执行器与真正的便携运行时打包。
4. 再补第二批 OpenAPI。

### 7.2 如果上下文快满,有什么影响

主要影响是:

1. 对话里的临时上下文可能被裁剪。
2. 已写入仓库的代码和文档不会受影响。
3. 因此续接时优先读本文件和 `backend/README.md`,成本可控。

结论:

**上下文快满不会影响现有代码成果,只会增加下一轮续接时重新装载上下文的成本。**

当前推荐命令:

```bash
set PYTHONPATH=backend
set DATABASE_URL=sqlite:///:memory:
.venv\Scripts\python -m pytest backend/tests -q -p no:cacheprovider
```

---

## 8. 当前一句话结论

目前不是"还在想法阶段",而是已经完成了:

**方案文档 -> 技术架构 -> 接口定义 -> 后端骨架**

当前已经完成从"写文档"切换到"写 demo 代码"的第一步,下一步进入:

**更多执行指标 -> 审计细节增强 -> 本地 Agent 与联调能力继续补齐**