Files
dxdesigner-part-replacement/docs/user/current-program-flow.md
T

163 lines
12 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 程序流程与阻塞去向(BOM 调整前调查快照)
整理日期:2026-11-10。依据:已同步的 `4f8fbd7` 及当前工作区修改。本文描述现有实现,不代表未来设计;本次只整理代码路径,没有重新进行真实 CAD 阻塞验收。
后续已按用户确认修改 BOM 导入、原生核验和网表比对路径;最新源码流程见 [BOM 原生核验流程](bom-native-workflow.md)。本页保留修改前的诊断路径,用于理解原有阻塞原因。
当前有三条执行链:主程序的 CAD 任务队列、普通 Harness 对话、自动异常诊断。普通对话已开放原生工具;自动诊断会话仍只读取事件快照,再由主程序决定是否执行固定恢复动作。
## 1. 主程序:从任务建立到执行结束
```mermaid
flowchart TD
A[启动程序并加载任务库] --> B{任务来源}
B -->|主程序建立或选择| D[任务中心显示任务]
B -->|Agent 提议建立| C[Qt 确认任务名称和工程范围]
C -->|确认并建立成功| D
D --> E[导入 Excel 或编辑替换计划]
E --> F[预览并保存计划]
F --> G[选择当前任务或工程队列]
G --> H[预检并确认执行范围]
H -->|条件不足或取消| W[等待修改计划、补齐输入或确认]
W --> F
H -->|通过并确认| I[记录执行轮次和队列检查点]
I --> J[工程备份、打开 CAD、准备替换]
J --> K[逐项替换、保存、关闭、重开回读]
K --> L{实际执行结果}
J -->|准备失败| L
L -->|成功或无匹配等已确定结果| N[保存回执并处理后续任务]
L -->|已确定的安全失败| M[记录失败并继续后续工程]
M --> N
N --> O{主轮次是否已跑完}
O -->|否| J
O -->|是| P[对可安全重试的问题项执行问题轮次]
P --> Q[保存完成、失败或暂停结果]
L -->|中断、保存未核验或未知异常| R[暂停队列并保留现场]
L -->|用户暂停或尚未完成| R
P -->|范围改变或结果不确定| R
R --> S[按原因进行核验恢复、准备重试或人工处理]
S -->|条件恢复后重新确认继续| G
Q -->|仍有失败| T[触发 AI 异常介入]
R --> T
T --> U[见图 2:诊断、有限恢复或升级]
```
- “问题轮次”是程序已有的确定性重试机制,不依赖模型。它在主轮次未暂停、未被停止且服务支持时,处理预留范围内的安全失败项。
- 主轮次已经完成的队列条目会被跳过;恢复时还会检查任务顺序和计划是否变化。
- Excel 预览有未保存修改时,当前执行按钮会先保存,之后需要再次点击进入执行确认。
- Agent 建立任务成功后,当前工作区会清除搜索和分类筛选,选中新任务并刷新主任务中心。选择的工作文件夹是 Harness 工作区,任务记录由主程序的任务服务建立。
- 预检检查本地计划、文件和既有证据;不等于已成功连接 CAD 或中心库。正式执行时仍可能遇到 CAD、库和保存问题。
- 图中的预检为总体阶段。当前主程序批量入口对不超过 20 个任务使用统一预检与执行回执路径;超过 20 个时直接走既有任务队列,仍有队列和服务自身检查。这是现存入口差异。
## 2. 异常介入:AI 能处理到哪一步
```mermaid
flowchart TD
A[执行失败、队列阻塞、资源残留或无进展告警] --> B{自动介入开启且 AI 可用}
B -->|否| C[保留主程序错误状态;阻塞观察项待处理]
B -->|是| D[同一阻塞去重并排入诊断]
D --> E{主程序是否正在执行}
E -->|是且事件需要操作| F[等待执行通道空闲]
F --> E
E -->|空闲或仅做只读观察| G[采集任务快照和诊断证据]
G --> H[模型只读诊断并建议动作]
H --> I{建议及当前条件}
I -->|允许重试的已确定失败| J[重新核对状态并取得执行通道]
J --> K[消耗重试预算并执行既有失败重试]
K --> L[重新读取队列和任务结果]
L -->|全部完成且无失败、无中断、无暂停| M[resolved:本次任务恢复已核验]
I -->|允许处理的资源残留| N[清理本程序拥有的资源]
N --> O[独立检查剩余资源]
O -->|实际清理且确认释放| P[resolved:资源释放已核验]
O -->|检查时已自行释放| PC[observed_cleared:未执行 AI 清理]
I -->|只读、数据缺失、预算耗尽或不符合条件| R[保留实际动作与未解决原因]
J -->|状态改变或通道不允许| R
L -->|未解决| R
O -->|未释放或核验不完整| R
R --> S[模型可用且预算仍有余量时反思]
S --> V[保存证据包和工单草稿并尝试提交 Git]
V -->|工单及附件均成功| X[escalated:已升级,等待处理]
V -->|提交未完成| Y[pending_issue:保留证据,可补交]
M --> Z[刷新状态;原批量队列不在此处自动续跑]
P --> Z
PC --> Z
```
执行重试要求:上下文存在、结果已确定、处于失败重试阶段、错误码可重试、原任务已有执行授权、没有暂停或取消、自动介入仍开启、预算未耗尽、模型明确建议重试;操作发生前还会重新核对状态和执行通道。
目标计划的“问题轮次”和 AI 重试共用操作预留机制,避免同一个失败操作被两条链重复消费;普通规则队列的 AI 重试使用持久化的任务/运行预算。一次诊断事件最多尝试一次重试、一次允许的资源清理,不会持续循环修复。
**资源释放成功仅表示资源问题解决。它不会重开工程、恢复原队列,也不证明 CAD 替换成功。**
诊断与反思共用模型时间预算:`min(300, max(90, response_timeout_seconds × 2))` 秒;当前设置为 0 时,自动诊断预算仍是 90 秒。Harness 启动/会话就绪另有等待上限。模型失败或预算耗尽会保留证据并走升级路径;取消诊断会保存本地证据并停止后续动作。
自动诊断通常不占用 CAD 执行通道;实际重试和清理仍需要串行取得该通道。AI 不可用不会单独成为普通任务无法执行的理由,原有业务阻塞仍需解除。
## 3. 普通 Harness 对话与任务中心的关系
```mermaid
flowchart TD
A[用户输入任务并选择工作区] --> B[原生 Harness 规划和工具调用]
B --> C{当前操作}
C -->|文件、Shell 等原生工具| D[执行工具并读取真实结果]
D --> B
C -->|建立或改变主程序任务| E[调用应用任务工具]
E --> F[按操作进入 Qt 预览、确认及任务服务]
F -->|成功或失败回执| B
F -->|等待确认| W[等待用户处理]
C -->|需要缺失信息或工具审批| W
W -->|获得输入或批准| B
C -->|任务完成| Z[回复结果及证据]
C -->|暂停、取消或无法继续| X[保留会话状态并说明阻塞]
```
普通会话保留原生工具和 goal 能力。原生 goal 可管理多轮执行,但能否继续取决于实际工具结果、输入、审批和运行时状态。应用任务工具仍调用任务服务,遵循 CAD 执行所需的状态检查。
自动异常诊断使用另一类会话,其工具被限制为 `dx_task_snapshot`。普通会话开放原生工具,并没有同步把自动诊断改造成能自行修改文件、运行 Shell、寻找中心库和接续 CAD 队列的完整修复 Agent。
## 4. 阻塞后,具体等谁处理
| 阻塞情形 | 当前程序动作 | 自动继续情况 |
| --- | --- | --- |
| 单项失败且已确认没有未核验写入 | 记录失败,允许后续工程继续;主轮次结束后尝试问题轮次 | 支持局部继续;失败项受重试范围与预算约束 |
| AI 收到允许重试的临时错误 | 诊断后,条件满足才执行一次既有重试并核验 | 可完成本次任务;没有自动恢复原批量队列的接续 |
| 队列报告 `task_queue_blocked` | 可以触发诊断,但此错误码本身不在自动重试名单 | 通常留证、升级,等待后续处理 |
| 保存过但未核验、进程中断导致状态不确定 | 暂停队列,禁止直接重放替换;提供“核验并恢复”入口 | 需要确认后核验;该入口不会直接重复原生替换 |
| 界面观察到 120 秒无进展 | 触发 `operation_stalled` 只读观察,后台工作可能仍在运行 | 该告警本身不终止工作,也不执行恢复 |
| 底层 worker 长时间没有业务进展 | 按阶段空闲阈值请求停止;后续依可安全停止状态处理 | 不可安全停止的写入可能继续等待安全完成,需要人工介入 |
| CAD 弹窗或尚未释放的资源 | 提供弹窗处理/资源清理;符合条件可尝试一次自动清理并核验 | 资源释放后仍需检查工程并继续任务 |
| 工程文件、中心库、料号或有效计划缺失 | 显示错误,部分入口提供只读诊断 | 当前没有通用的自动补齐链,需要提供或修正输入 |
| 等待 Qt 确认、工具批准、用户主动暂停 | 保留等待/暂停状态 | 等用户处理后继续 |
| 自动介入关闭或 AI 不可用 | 主程序仍保留业务错误;观察协调器可保留待处理阻塞 | 不会因此自动解决;执行错误入队接口可能直接返回,不能假定每条事件都已排队 |
| Git 工单或附件上传失败 | 保存 `pending_issue` 和本地证据,提供补交 | 补交工单不会恢复 CAD 执行 |
120 秒无进展告警和 worker 空闲监控是两套机制。worker 使用业务进展而非单纯心跳判断;在不可安全停止的阶段可能等待完成,不能把“有心跳”“仍在运行”视为业务正在前进。
## 5. 当前闭环缺口
1. **阻塞分类没有完整传递。** 批量队列结束后的失败会分别映射为 `execution_failed` 或 `task_queue_blocked`;后者没有进入自动重试名单。观察协调器传入的多数阻塞快照又被设为只读,诊断结束后通常不会执行修复。
2. **诊断可选动作只有重试、清理和不操作。** 自动诊断尚无“检查输入 → 修复环境/计划 → 验证修复 → 继续执行”的通用工具链。缺库、缺文件和确定性错误容易停在升级工单。
3. **局部处理与原队列续跑没有接起来。** 单个任务重试通过或资源释放后,程序刷新状态,没有自动重新核对原批次检查点并继续剩余工程。
4. **同一阻塞不会无限触发。** 去重可避免刷屏和重复动作;但诊断结束后仍存在的同一阻塞,不能指望它自动反复启动 Agent,必须有进展、状态变化或显式处理。
后续若实现完整闭环,流程需要接上:识别具体阻塞 → 可执行修复 → 独立核验 → 重新核对原队列范围 → 继续未完成项;确实缺少用户信息时再进入明确的等待状态。以上是后续建议,本文没有改变现有行为。
## 代码定位
| 行为 | 实现位置 |
| --- | --- |
| Agent 建立任务及任务中心刷新 | `src/dx_productivity/trial_task_center/ui/dsh_task_creation.py:117` |
| 保存计划、确认执行、批量结果转异常事件 | `src/dx_productivity/trial_task_center/ui/main_window.py:744`、`:788` |
| 失败项准备重试;核验并恢复入口 | `src/dx_productivity/trial_task_center/ui/main_window.py:1060`、`:1104` |
| 预检内容与 CAD 连接检查边界 | `src/dx_productivity/dsh/task_lifecycle.py:47` |
| 执行日志、队列调用和实际回执 | `src/dx_productivity/dsh/execution_runs.py:47` |
| 安全失败继续、不确定暂停、问题轮次 | `src/dx_productivity/trial_task_center/task_queue.py:193` |
| 问题轮次预留及范围检查 | `src/dx_productivity/trial_task_center/problem_pass.py:16` |
| 阻塞去重及 120 秒观察告警 | `src/dx_productivity/trial_task_center/ui/dsh_blockers.py:22`、`:83` |
| 阻塞快照默认只读、执行事件携带原授权 | `src/dx_productivity/trial_task_center/ui/main_window.py:1520`、`:1542` |
| AI 排队、执行通道、共享诊断预算 | `src/dx_productivity/trial_task_center/ui/dsh_automation.py:137`、`:232`、`:288` |
| 重试错误分类与暂停/不确定处理 | `src/dx_productivity/dsh/failure_policy.py:8` |
| 诊断、重试、资源清理、核验与升级 | `src/dx_productivity/dsh/incidents.py:167` |
| 自动诊断工具限制及原生会话等待 | `integration/dsh/task-plugin/host.mjs:130`、`:184` |
| worker 业务进展监控及停止处理 | `src/dx_productivity/trial_task_center/worker_monitor.py:207`、`:474` |