368 lines
13 KiB
Markdown
368 lines
13 KiB
Markdown
# 智能化部署 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`,成本可控。
|
|
|
|
结论:
|
|
|
|
**上下文快满不会影响现有代码成果,只会增加下一轮续接时重新装载上下文的成本。**
|
|
|
|
当前推荐命令:
|
|
|
|
```bash
|
|
set PYTHONPATH=backend
|
|
set DATABASE_URL=sqlite:///:memory:
|
|
.venv\Scripts\python -m pytest backend/tests -q -p no:cacheprovider
|
|
```
|
|
|
|
---
|
|
|
|
## 8. 当前一句话结论
|
|
|
|
目前不是"还在想法阶段",而是已经完成了:
|
|
|
|
**方案文档 -> 技术架构 -> 接口定义 -> 后端骨架**
|
|
|
|
当前已经完成从"写文档"切换到"写 demo 代码"的第一步,下一步进入:
|
|
|
|
**duration_ms 回填 -> 失败结果呈现增强 -> 本地 Agent 与联调能力继续补齐**
|