dark/auto_agent
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
auto_agent/智能化部署agent-当前进度总结.md

13 KiB
Raw Blame History

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

更新时间:2026-04-08

1. 当前总体状态

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

方案已成型、文档体系已建立、技术路线已基本明确、demo 后端代码骨架已开始实现

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

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

2. 已完成的文档产出

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

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

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

  3. 智能化部署agent-demo接口定义说明.md 用于描述 demo 阶段的接口协议、统一响应格式、状态枚举、Agent 接口、软件 A demo 接口、身份 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 为技术架构说明书备份文件。

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. 开发顺序建议。

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 demo 接口。
  6. 已将高风险任务确认后的审批创建流程接入后端主链路。
  7. 已实现最小 edge 心跳、拉取任务、回传结果接口。
  8. 已将默认验证任务接入 edge 调度主链路。
  9. 已将 software-a demo 部署任务创建接入主执行链。
  10. 已将 tool_call 和 audit_log 接入主链路关键动作。
  11. 已实现任务报告接口,可返回审批、工具、验证、审计轨迹。
  12. 已实现任务取消接口,并将 request_id、operator 维度写入关键审计和工具调用记录。
  13. 已补充自动化测试,并基于内存 SQLite 完成首轮通过验证。
  14. 已完成任务状态机第一轮收紧,补上重复确认、审批后任务状态漂移、edge 重复回传等冲突校验。
  15. 已补上首轮失败分支细化,包括 software-a demo 执行失败、审批驳回、edge 验证失败三条主失败路径。

3.8 当前代码可运行范围

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

  1. 任务创建、确认、查询、取消。
  2. 高风险任务确认后自动创建审批单。
  3. 审批通过后进入执行链,审批驳回后进入取消态。
  4. 执行链包含: software-a 权限校验 -> software-a demo 部署任务创建 -> edge 默认验证任务创建 -> edge 拉取 -> edge 回传。
  5. 任务详情接口可返回: 当前状态、software-a 状态、工具调用摘要、验证结果摘要。
  6. 任务报告接口可返回: task_basic、intent_snapshot、approval_trace、tool_trace、verification_trace、result_summary、audit_trace
  7. edge 侧已支持: 心跳、拉取任务、回传结果、上报异常事件。

当前测试基线:

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

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。

该结论已在本轮决策、最小 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 demo 当前在任务详情查询时会同步刷新状态,因此: 确认接口返回的 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 demo 会返回失败任务,用于联调失败分支。

5. 当前待补强的部分

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

  1. 本地 edge-agent 初始化代码与打包脚本。
  2. 文件型 SQLite / PostgreSQL 实库运行验证。
  3. 身份 demo / 审批 demo 与任务主链路的权限、审批决策联动细化。
  4. duration_ms 等执行指标的真实计算与回填。
  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. 回填执行指标: 重点补 duration_ms、更完整的执行结果摘要与审计信息。
  2. 增补失败路径与幂等性测试: 重点补重复请求、重复回传、异常回滚等场景。
  3. 继续丰富结果摘要与审计细节: 让失败原因在详情和报告里更直观可见。
  4. 然后再继续: 本地 edge-agent 骨架、第二批 OpenAPI、更多联调能力。

当前状态:

SQLite / 去 Redis / 最小 DDL / 首批 OpenAPI / FastAPI 骨架 / 三条主接口 / demo adapter / edge 接口,均已完成第一轮落地。

7. 建议的下一步

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

  1. 计算并持久化 duration_ms。
  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. 计算并回填 duration_ms。
  2. 再补失败路径和幂等性测试。
  3. 再补结果摘要和失败原因展示。
  4. 再补本地 Agent 初始化代码或第二批 OpenAPI。

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

主要影响是:

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

结论:

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

当前推荐命令:

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

8. 当前一句话结论

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

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

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

duration_ms 回填 -> 失败结果呈现增强 -> 本地 Agent 与联调能力继续补齐