# DxDesigner 器件批量替换工具 DxPartReplace 应用图标 面向 **Windows + DxDesigner / Expedition Enterprise 7.9.5** 的器件批量替换工具。一个工程对应一个任务,可以只替换同料号下的部分位号;支持直接编辑和 Excel BOM 导入,同批工程按顺序执行。 本轮 BOM、Mentor 会话与 Harness 修改尚未发布,详见 [PR 开发及验收清单](docs/testing/2026-11-12-pr-checklist.md)。最新审查修复的本地启动入口为 `outputs/pr27-followup-20261113/app/DxPartReplace/启动程序.cmd`,使用同目录 `data`,候选 SHA256 为 `a96a505b1f8e…`;已验证冻结内容与正常启动退出,尚未完成 20 项实机验收。该候选复用本机不变依赖,不作为独立发行包分发。原 R17 `de35b91aaf4c…` 的记录与产物保留为历史,下方已有发行包不包含本轮修改。 本轮验证记录见 [本地实机验收](docs/testing/2026-11-12-final-local-validation.md)、[单次与批次分步计时](docs/testing/2026-11-12-final-step-timings.md) 和 [执行、阻塞及恢复流程图](docs/user/execution-flow-2026-11-12.md)。验收按预设的成功、无需替换与失败分别判定;已知的可重试失败任务列表徽标问题在收尾清单单列。 2026-11-13 的 [PR #27 审查修复与复核](docs/testing/2026-11-13-pr27-review-fixes.md) 单列最新结果:停滞计时、执行回执、BOM 错误、网表范围与确认后状态检查已修复;新候选启动及冻结校验通过,新 20 项实机仍因 Mentor 退出超时未完成,尚未发布。 **当前版本:V1.3.1(实机测试预发布)** · [本版变更与已知问题](docs/releases/v1.3.1.md) · [完整使用说明](docs/user/v1.1.0-project-tasks.md) V1.3.1 包含 PR #27 的原生 BOM 按需核验、Mentor 批内复用、前后网表比对、完整普通 Harness 及审查修复,沿用紫蓝双环图标和原生三栏 DSH 助手。错误触发自有 Mentor 自动回收,确认相关进程退出后才释放桌面;具体时限与恢复要求见[停止与恢复说明](docs/user/safe-stop-and-recovery.md)。 本地交付目录为 `outputs/releases/v1.3.1`,包含自解压 EXE、ZIP 便携包、SHA256、逐文件清单和本次构建验证报告。两种包均保留完整 Node/Harness、Qt WebEngine 和应用资源。升级前退出旧程序并备份 `data`,解压到新目录,完整保留 EXE 与 `_internal`,不要只替换 EXE。 **V1.3.1 下载** · [自解压 EXE](https://git.simgreek.com/Skyworth_Digital_Hardware/dxdesigner-part-replacement/releases/download/v1.3.1/DxPartReplace-1.3.1.exe) · [ZIP 便携包](https://git.simgreek.com/Skyworth_Digital_Hardware/dxdesigner-part-replacement/releases/download/v1.3.1/DxPartReplace-1.3.1.zip) · [版本说明与附件](https://git.simgreek.com/Skyworth_Digital_Hardware/dxdesigner-part-replacement/releases/tag/v1.3.1)。本版 Mentor 退出超时仍待实机复核,最新 20 项 CAD 验收未完成。 本版提供[目标封装选择](docs/user/target-cell-selection.md):目标封装可留空,此时工具不主动覆写封装,可后续与中心库同步;需要指定时,在料号规则中读取并选择合法封装。BOM 保持原 11 列。 ## DSH助手:在工具内使用 AI 本项目已将 **DSH助手** 集成到任务中心主窗口。顶部固定显示两个入口:左侧 **任务中心**、右侧 **DSH助手**,单击即可切换,无需展开菜单;助手保留 DeepSeek Harness 官方三栏界面、SVG 动画、模型选择、会话和未发送草稿。也可以使用 `Ctrl+Shift+D` 打开助手。 DSH助手围绕真实任务中心工作,支持: - 用自然语言创建任务、修改规则、复制或归档任务;工程选择和提交仍由原生窗口确认。 - 查询任务快照、执行预检、影响范围和实际执行历史。 - 识别已保存的逐项 Value 策略(继承、保留、Part Label、料号或自定义);可从对话打开当前任务的原生 BOM 多文件选择流程,校验后仍需核对预览并手动保存。 - 在原生确认后按冻结范围执行任务,支持安全暂停、原队列恢复和排期授权。 - 顶部 **AI 自动介入** 开关默认开启并记住设置;异常、BOM 校验失败、预检阻断、资源释放问题和后台操作长期无进展时自动新建诊断对话,收集脱敏证据,按规则重试或清理自有资源并核验,未解决则转受限 Git 工单。 - 右上角使用无外框、无常驻文字的 **AI 状态灯**:绿色待机、黄色检查或介入中、红色未配置/不可用或待人工处理;关闭 **AI 自动介入** 后显示灰色静默。悬浮可查看状态、介入原因、所属任务和当前阶段,点击进入助手,右键可取消本次介入。未配置模型或 API Key 时,仅提示状态,不自动启动诊断、复盘或工单流程,也不弹窗、锁住任务操作;仍可手动打开助手配置模型。 - AI 等待模型、复盘、工单上报及后台查询使用独立工作通道,不锁住普通任务操作。只有实际修复及核验占用任务执行通道;执行前重新核对任务证据和所属轮次,期间有新任务、未保存编辑或现场变化则放弃旧建议,保留证据且不自动重排。在助手面板取消诊断,或右键状态灯选择 **取消本次 AI 介入**,会停止模型请求、保存本地证据并转人工接管;已进入执行的 CAD 步骤仍按原暂停/强停机制安全收尾。拒绝关闭或取消未保存计划的关闭确认时,诊断继续。诊断与复盘从原生会话准备好后共享等待预算,默认 180 秒,随模型超时设置调整为 90–300 秒;运行时启动和会话创建另有最多 300 秒的等待上限,不挤占分析时间。 - 后台读取异常先在约 200 毫秒后复查,连续失败才介入;同一持续阻塞不会周期性重复建会话,关闭再开启自动介入可主动重新诊断。面板分别显示清理次数及独立核验结果;资源自行释放显示“自行解除”,不会计作 AI 修复。资源清理使用独立控制,不显示 CAD 暂停或强停按钮。 - 模型配置的后台检查不会取消健康的在途诊断,也不会把“配置恢复”当成用户重新开启开关。同一异常保持原事件编号,完成后不因配置状态波动重新发诊断;只恢复此前尚未开始的待处理项。仅新异常、用户重新导入或主动关闭再开启允许再次介入。 - 本地模型配置检查仅在超时时补试一次,每次最多 3 秒;连续超时显示检查状态,在途诊断和事件去重保持有效。配置检查不请求远端模型,检查中或临时检查失败时,普通任务的原始错误仍会正常反馈。 - 在右侧任务监管中查看运行、影响、排期、经验、工单和用量;审计损坏、证据缺失和未知计数会明确显示。 普通对话使用官方 Standard Harness,提供 PowerShell/Shell、工作区文件写入与编辑、goal、jobs、子智能体和原生上下文压缩,默认权限策略为 `workspace-write`。启动前设置 `DSH_PERMISSION_MODE=read-only` 并重启,可切换为官方只读策略。任务中心的任务工具仍经过原生确认与执行证据核验;通用 Shell 的实际能力不能用这些任务工具的门禁来描述。本版新建的自动异常诊断及复盘使用独立会话,只能读取绑定事件快照,限制由运行时工具守卫执行。关闭 **AI 自动介入** 停止自动诊断,普通对话的工具能力由其 Harness 权限策略控制。未配置模型时仍可使用任务监管和本地恢复功能。 首次接入打开 **工具设置 → 模型 → 添加模型提供商 → 自定义模型 API**,填写 API 地址、协议和密钥,点击 **获取可用模型** 并选择需要的模型,也可手动填写模型 ID。保存后在输入框下方选择模型。设置保存在任务中心数据目录的专用 Harness profile,重启会保留;主工具预配置的密钥继续由 Windows DPAPI 保护,模型设置页新增的密钥使用 Harness 本地凭据存储。开发环境也可通过 `DSH_API_BASE`、`DSH_MODEL`、`DSH_API_KEY` 临时提供配置。不要把数据目录、API key 或 Git 凭据提交到 Git。 对话输入框的 **+ → 文件** 可上传文本、ZIP 等文件;也可通过官方工作区入口选择本地文件夹,或直接提供路径让助手读取、搜索。ZIP 会解压到新的文件夹,返回真实路径后继续分析内容,不覆盖已有文件。启动展示直接使用 Harness 官方加载动画。 详细的能力边界、异常介入、证据链、排期和工单说明见 [DSH助手使用与监管说明](docs/user/dsh-ai-supervision.md)。源码环境可用下面的命令检查运行时门禁: ```powershell $env:PYTHONPATH = 'src' python -X utf8 -m dx_productivity.dsh --doctor node tools/verify_dsh_runtime.mjs ``` ## 图文教程 当前开发工作区已调整 BOM 流程:导入先保存待核验清单,确认执行后逐工程使用原生 CLI 核验,读取失败不回退 CAD;替换前后从固定副本异步导出并比对连接网表。见 [新的 BOM 流程说明](docs/user/bom-native-workflow.md) 和 [当前执行、阻塞与恢复流程图](docs/user/execution-flow-2026-11-12.md)。下方旧版截图仍用于说明控件位置,旧发行 EXE 不包含尚未发布的源码修改。 按下面 **13 步**,完成“创建任务 → 填 BOM → 导入校验 → 保存计划 → 替换 → 查看结果”。本例有两个工程 `Audio_D2128`、`Audio_T605A`,各自只替换 `RV05`,保留同料号下的 `RV11`。 截图来自真实窗口:起始页为 V1.1.3,后续操作图取自已验收的 V1.1.2 业务流程,操作位置相同。点击图片可以放大查看;BOM 填写图为示意。 ### 第 1 步:解压并打开应用 推荐下载上方自解压 EXE,双击后选择新的解压目录,完成后运行目录内的 DxPartReplace.exe。自解压引擎已内置,无需另外安装 7-Zip,也无需通过 Windows 资源管理器解压。 [下载 V1.2.2 便携包](https://git.simgreek.com/Skyworth_Digital_Hardware/dxdesigner-part-replacement/releases/download/v1.2.2/DxPartReplace-1.2.2.zip),**完整解压**,双击 `DxPartReplace.exe`。保留它与 `_internal` 的相对位置,无需安装 Python;本机需要可用的 DxDesigner、许可证和中央库。 打开后看到下图主窗口。首次使用请准备完整的工程副本,执行前保存并关闭待处理工程。 ![第 1 步:打开应用,进入任务主窗口](docs/user/media/tutorial/01-open.png) ### 第 2 步:新建任务,读取工程目录 点击左下方 **新建**。在弹窗中填写工程根目录,或点击 **选择目录**,再点击 **读取工程**。 **完成标志:** 弹窗列表显示该目录下找到的 `.prj` 工程。 ![第 2 步:填写根目录,点击读取工程](docs/user/media/tutorial/02-read-projects.png) ### 第 3 步:勾选工程,创建任务 勾选这次要处理的工程,点击右下角 **创建任务**。本例勾选两个工程。 **完成标志:** 左侧出现两个任务,**一个工程对应一个任务**。 ![第 3 步:勾选两个工程,点击创建任务](docs/user/media/tutorial/03-create-tasks.png) ### 第 4 步:导出本批 BOM 模板 选中左侧任意一个任务,切换到顶部 **本批位号计划**,点击 **BOM 模板**,选择文件保存位置。 **完成标志:** 导出的 Excel 包含本批所有工程,工程名称和完整路径已经填写好。此时不需要先采集位号,也不需要先添加料号规则。 ![第 4 步:切换本批位号计划,导出 BOM 模板](docs/user/media/tutorial/04-export-template.png) ### 第 5 步:在 Excel 中填写替换项 打开刚导出的模板,**保留全部 11 列表头以及原工程路径**。同一工程需要填写多条替换时,复制该工程行后再填写。 本例在两个工程行中分别填写相同的旧、新料号和 `RV05`: ![第 5 步:BOM 填写示意,两个工程各替换 RV05](docs/user/media/tutorial/05-fill-bom.png) | 要填写的列 | 填法 | | --- | --- | | `old_part_number` | 工程当前的旧料号,本例为 `4100-CA0000-T7` | | `new_part_number` | 中央库中的目标新料号,本例为 `4100-CA0000-T0` | | `refdes` | 要替换的位号,本例为 `RV05`;多个位号可用逗号、分号、空格或顿号分隔 | | `enabled` | `TRUE` / `是` 表示替换,`FALSE` / `否` 表示保留;留空默认替换,建议显式填写 | | `sync_nc` | 是否同步 NC,默认开启;按需要填 `TRUE` 或 `FALSE` | | `custom_value` | 可选的自定义 Value;留空时使用任务的 Value 策略 | 料号按**文本**填写,不要使用公式。相同位号出现在多个图页时,补填 `schematic_name`、`sheet_number` 或 `uid` 消除歧义。旧新相同、链式或循环替换会被拒绝。 **本例首次导入只列出 RV05,采集到的 RV11 默认保留。再次导入时,未列出的既有计划行会保留原勾选;需要停用时,请取消勾选或明确填写 `enabled=FALSE`。** 填完后保存 Excel 文件。 ### 第 6 步:导入填写好的 BOM 返回应用,在 **本批位号计划** 点击 **导入 BOM**,选择刚保存的 Excel,等待校验结果。 当前开发版导入先核对表格和工程归属,保存待核验请求;确认执行后,逐工程用原生 CLI 查询需要的器件,读取失败不回退 CAD。**导入不会执行替换。** 下图为旧发行版的控件示例,当前流程以导入报告和执行确认展示的范围为准。 ![第 6 步:点击导入 BOM,选择填写好的 Excel](docs/user/media/tutorial/06-import-bom.png) ### 第 7 步:检查导入报告,有错误先修正 点击校验状态条中的 **详情**。报告会显示通过、失败、未检查的行数,以及 Excel 行号和错误原因。 下图是故意填入不存在位号的示例:**通过 2 行、失败 1 行**,错误定位到 Excel 第 4 行。按报告修正 Excel、保存文件,再次点击 **导入 BOM**。 **有错误时不会部分保存。全部通过后再继续下一步。** 新一次导入开始后旧报告会清除;导入失败仍保留已有预览和手动编辑,取消文件选择则保留原报告。 ![第 7 步:查看校验详情,按 Excel 行号修正错误](docs/user/media/tutorial/07-import-errors.png) ### 第 8 步:核对每个工程的预览,保存计划 报告全部通过后,关闭详情,依次选中左侧各任务,核对: - 需要替换的 `RV05` 已勾选,新料号正确。 - 需要保留的 `RV11` 未勾选。 - 自定义 Value、同步 NC 等逐行设置符合预期。 确认后点击 **保存本批位号计划**;单工程编辑或保存完成后,按钮显示 **保存位号计划**。 **完成标志:** 底部提示计划保存完成。下图为保存后的状态,只有 RV05 启用。 ![第 8 步:检查替换勾选和新料号,保存本批位号计划](docs/user/media/tutorial/08-review-save.png) ### 第 9 步:按任务确认 Value 与封装设置 选中一个任务,按需设置顶部 **Value 策略**:勾选后,将替换后的 **Part Label 写入 Value**;逐行自定义 Value 优先。处理多个工程时,分别确认各任务的开关。 本例开启该选项。**复制的是 Part Label,不是把新料号直接写进 Value。** ![第 9 步:按当前任务设置 Part Label 写入 Value](docs/user/media/tutorial/09-value-policy.png) 目标封装可留空,工具不主动覆写 Cell Name,可后续与中心库同步。需要本轮指定时,在 **本批料号规则** 中编辑对应旧、新料号规则,读取并选择合法封装,核对计划中的选择后保存。详见[封装操作说明](docs/user/target-cell-selection.md)。 ### 第 10 步:选择执行范围,确认后开始 只处理选中工程,点击底部 **执行当前任务**;处理同批工程,点击左侧 **顺序执行本批任务**。本例使用后者。 在确认弹窗中核对工程数量和执行范围,确认无误再点击 **Yes / 是**。 ![第 10 步:核对两个工程的执行范围,确认顺序执行](docs/user/media/tutorial/10-confirm-execution.png) **搜索和显示排序只影响浏览,不改变本批执行范围。** 调整实际执行顺序,请使用左下方 **上移任务 / 下移任务**。 ### 第 11 步:等待后台执行和保存重开核验 工具按工程顺序执行替换,保存、关闭并重新打开核验。左侧显示各任务状态,底部显示当前阶段和进度。 ![第 11 步:观察任务状态和底部执行进度](docs/user/media/tutorial/11-running.png) 运行期间可以在主桌面查看其他文件,请勿打开或修改本次正在处理的同一工程。需要暂停时,点击 **完成当前项后暂停**,等待当前步骤安全收尾。 普通暂停等待当前项到达安全边界;执行错误或持续停滞会先写入保护记录,再自动回收自有 Mentor。也可手动选择 **强制结束…**;结果不确定时先核验恢复,不能直接重复替换。详见[停止、强制结束与恢复](docs/user/safe-stop-and-recovery.md)。 **完成标志:** 任务显示已完成,底部提示本批执行结束。还要打开结果核对,不能只看进度条。 ### 第 12 步:查看实际修改结果与日志 选中要检查的任务,点击右下角 **替换结果 / 日志**,查看 **位号替换结果**。 本例应看到:`RV05` 的旧料号为 `4100-CA0000-T7`,回读料号为 `4100-CA0000-T0`,核验状态为 **已保存并核验**。 ![第 12 步:查看位号、旧料号、实际回读料号和核验状态](docs/user/media/tutorial/12-results.png) 需要排查原因时,切到 **完整日志**,查看具体阶段和耗时;可用 **上一页日志 / 最新日志** 翻页。失败、未命中或未核验不会被当作已保存成功。 ![第 12 步补充:完整日志显示各阶段和处理信息](docs/user/media/tutorial/12-complete-log.png) ### 第 13 步:需要继续替换时,开始新一轮 已完成任务可以点击底部 **开始新一轮**: ![第 13 步入口:任务完成后,底部出现开始新一轮](docs/user/media/tutorial/13-new-round-entry.png) 核对弹窗中的任务范围,再确认。 ![第 13 步:核对新一轮范围及旧证据归档说明](docs/user/media/tutorial/13-new-round.png) **完成标志:** 已完成任务恢复为待配置,旧计划、命令、快照和日志归档保留。接下来按工程**当前料号**重新填 BOM 或修改规则,重新采集、保存后执行;旧轮次通过 **查看轮次证据** 打开。 出现状态不确定或恢复提示时,先使用 **核验并恢复**,按[恢复说明](docs/user/interrupted-recovery.md)处理。 ## 不使用 Excel:直接在界面编辑 1. 在 **本批料号规则** 添加旧、新料号,按需配置 Value 与同步 NC;规则提供采集条件和默认值。 2. 切到 **本批位号计划**,点击 **采集所有匹配位号**。 3. 勾选需要替换的行,逐行填写新料号、自定义 Value 和 NC。查找可按位号、UID、料号、图页或 Value 过滤;批量操作的范围会显示为当前工程或可见行。 4. 保存计划后执行。位号计划模式以**已保存的每行计划**为准,手动覆盖的值不会因修改默认规则而被随意覆盖。 两种方式可以配合使用,不必为了编辑而先导出 Excel。切换任务会保留编辑草稿;关闭时有未保存内容会提示保存全部、放弃或取消。 ## Value、NC 与日志选项 - 顶部 **Value 策略** 开关控制当前任务是否将替换后的 Part Label 写入 Value;逐行自定义 Value 优先。处理多个任务时,分别确认各任务的开关。 - **同步 NC** 是逐行选项,默认开启,可以关闭。 - 点击 **完成当前项后暂停** 后,工具在当前步骤安全收尾后停止,不会在原生写入中途强行中断。 - 点击 **替换结果 / 日志** 查看图页、位号、旧料号、实际回读料号和核验状态。失败、未命中、未核验不会显示为已保存成功;完整日志支持翻页。 - 日志和 BOM 详情按需打开,关闭后释放窗口;数据和证据仍保留。 ## 更新程序与保留数据 先关闭旧程序并备份 `data`。完整解压新包,用新 EXE 和 `_internal` 配合原 `data` 使用;不要混用不同版本的依赖目录,也不要删除原数据。 ```text DxPartReplace/ DxPartReplace.exe _internal/ data/ 首次运行后创建,更新时保留 task-center.db 任务数据库 logs/application.log 应用日志 tasks/<任务ID>/ 任务事件、备份、快照及轮次证据 ``` 不同版本不要同时打开同一数据目录。排查失败时保留日志、原生报告和工程副本;不要手工删除锁文件、状态或恢复证据来强行续跑。 ## 验证范围与已知限制 历史 V1.3.0 本地包的 1358 项回归、图标、版本资源及 66,805 个文件校验记录见 [V1.3.0 构建记录](docs/releases/v1.3.0-build.md),不作为 V1.3.1 的验收结果。V1.3.1 的实际构建验证记录随 Release 附件提供;本版未宣称完成真实 CAD 20 项验收。官方 Harness 前端保留自身的预览版标记,产物未做代码签名。 V1.1.4 Beta 4 沿用批次后台资源管理:一次 BOM 导入或顺序执行共用一个私有桌面,CAD 按需启动并在同批工程间复用,批次结束统一退出。若提示 **资源释放待处理**,已保存核验的结果保留,请点击 **重新清理资源**;该操作只清理后台资源,不会再次替换。旧的工程保护锁仍按“核验并恢复”处理。设计、异常边界与实机结果见[批次运行时验收记录](docs/testing/2026-10-21-batch-private-runtime.md)。 资源释放会追加日志:在 **替换结果 / 日志 → 完整日志** 查看本批开始释放、释放成功/失败及重新清理的结果。独立文件位于 `data/batch-resources/<批次ID>/resource-release.log`,记录批次、桌面、CAD PID、退出码、释放耗时、句柄关闭和桌面消失的分别确认,以及失败原因;同时保留 `session.json` 的原始释放证明。重启后重新检查也会追加记录,不覆盖原失败日志。 V1.1.3 的业务代码沿用本机已验收候选:两工程实际替换和独立回读、362 字符工程路径、BOM 失败/成功导入、Part Label 写入 Value、可选封装、旧版任务数据副本、新轮次和自有后台资源释放。新增图标及版本元数据另做冻结包检查。详见[验收报告](docs/testing/2026-10-19-release-preparation.md)。 当前按 **evaluation-only(评估试用)** 交付。不同机器、中央库和 CAD 版本仍需用工程副本确认兼容性;替换回读通过不代表已通过 Packager、ERC 或网表检查。 首次采集与 CAD 启动可能需要较长时间,存在已知的偶发 COM 启动阻塞;启动有等待上限和清理机制。验收候选的两工程执行为 167 秒;千步模拟队列为 21.09 秒,两者测量范围不同。长路径兼容已覆盖验证场景,不代表旧 CAD 或中央库支持任意路径。 ## 开发与更多资料 源码运行需要 Python 3.12: ```powershell py -3.12 -m venv .venv .\.venv\Scripts\python.exe -m pip install -e ".[dev]" .\.venv\Scripts\python.exe -m dx_productivity.trial_task_center.application ``` 源码默认数据目录为 `%LOCALAPPDATA%\DxProductivity\trial-task-center`,可用 `DX_TASK_CENTER_HOME` 指定独立目录。运行回归:`python -m pytest -q`;构建使用 `packaging/Build-DxPartReplace.ps1`。 - [历史窗口 GIF(补充演示,录制于 V1.1.2)](docs/user/media/v1.1.2-window-bom-tutorial.gif) - [完整桌面使用说明](docs/user/v1.1.0-project-tasks.md) - [中断核验与恢复](docs/user/interrupted-recovery.md) - [Value 与属性继承](docs/user/value-copy-and-layout.md) - [历史流程和独立 CLI 说明](docs/user/trial-task-center.md) - [CLI 与原生批处理集成](docs/user/part-replacement.md) - [V1.1.3 版本说明](docs/releases/v1.1.3.md) - [V1.3.1 实机测试版说明](docs/releases/v1.3.1.md) - [V1.3.0 版本说明](docs/releases/v1.3.0.md) - [V1.3.0 构建记录与校验值](docs/releases/v1.3.0-build.md)