209 lines
11 KiB
Markdown
209 lines
11 KiB
Markdown
# Round 85: optimize 集成形态计划
|
||
|
||
更新时间：2026-09-03
|
||
|
||
## 1. 本轮目标
|
||
|
||
将当前 `optimize` 的集成形态落定为 `aps-agent` 内部的 V2 原生排产求解器，并为下一轮实现定义清晰、可验证的边界。
|
||
|
||
本轮只完成架构和实施计划，不修改生产代码。下一轮实现应能让真实 MOM 数据经过 APS 既有闭环，由 optimize 求解，再通过 V2 校验并写回 APS 版本和审计记录。
|
||
|
||
## 2. 背景与当前状态
|
||
|
||
### aps-agent 现有主链
|
||
|
||
```text
|
||
/api/flex/schedule
|
||
-> Harness P1 门禁
|
||
-> workflow / run_flex_schedule
|
||
-> MOM/world 同步、MRP 分解、来源标注
|
||
-> closed_loop_problem
|
||
-> SchedulingProblemV2
|
||
-> solver
|
||
-> SchedulingValidator
|
||
-> 候选结果原子化物化
|
||
-> WorldStore + audit
|
||
```
|
||
|
||
关键现有模块：
|
||
|
||
- `server/agent_core/harness.py`：权限等级和写入门禁
|
||
- `server/aps_domain/flex.py`：柔性排产入口和审计闭环
|
||
- `server/aps_domain/closed_loop_problem.py`：需求、BOM、供应和阻断建模
|
||
- `server/aps_domain/closed_loop_runtime.py`：V2 问题、求解、校验和物化
|
||
- `server/aps_domain/scheduling_problem_v2.py`：生产排产问题/结果契约
|
||
- `server/aps_domain/scheduling_validator.py`：独立 fail-closed 校验
|
||
- `server/engines/`：RULE、CP、HYBRID、GA、NSGA2、EXTERNAL 等引擎
|
||
- `server/importers/mom_pack.py`、`excel_importer.py`、`profiles/kangni.json`：现有 MOM/Kangni 导入
|
||
- `server/state/store.py`：WorldStore 唯一状态源
|
||
|
||
### optimize 现有能力
|
||
|
||
- Node 调度规则：EDD、SPT、PRIORITY、FIFO、LPT、CR、ATC
|
||
- Node CP-SAT 适配和独立结果认证
|
||
- Kangni/MOM 输入准入、manifest/hash、数据等级和阻断报告
|
||
- source-aware RAG、文档抽取、检索和 Python 数据流
|
||
- 既有 Node/Python 测试和 fixture
|
||
|
||
### 预检记录
|
||
|
||
- 目标仓库：`C:\Users\ssk\workspaces\aps-agent`
|
||
- 目标分支：`main`
|
||
- 轮次分支：`round/85-optimize-integration-shape`
|
||
- 轮次工作树：`C:\Users\ssk\worktrees\aps-agent-round-85-optimize-integration-shape`
|
||
- 基线 commit：`7f171f328d99974ff83eba1754b2fe669c7f9d15`
|
||
- 原始 `optimize` 工作树存在既有未提交/未跟踪改动，受保护，不自动带入本轮工作树
|
||
- `aps-agent` 轮次工作树当前干净
|
||
|
||
## 3. 已确认决策
|
||
|
||
任务重量：轻量。当前只有一个主集成方向，后续实现可由单 agent 在轮次工作树完成，不预先创建 worker worktree。
|
||
|
||
P0/P1 决策：
|
||
|
||
1. `optimize` 的最终身份是 V2 原生求解器。
|
||
2. 第一阶段直接进入生产 `closed-loop V2`，不建立 legacy 主链。
|
||
3. 第一轮纳入排产核心、APS 适配和 provenance；复用 aps-agent 已有 MOM/Kangni 导入；RAG 不在本轮重做。
|
||
4. APS WorldStore 是唯一权威状态源；optimize 不拥有订单、物料、资源或排产版本状态。
|
||
5. 成功标准包含真实 MOM 数据端到端验收；数据被 admission 阻断时必须准确报告阻断原因。
|
||
6. 排产核心迁移为 Python；Node 版本仅作为迁移期间的差分基线。
|
||
7. APS 与 optimize 直接使用完整 V2 问题/结果格式，不保留简化格式作为生产接口。
|
||
8. 七种规则和 CP-SAT 一起迁移；规则作为稳定基线，CP-SAT 处理复杂约束。
|
||
|
||
## 4. 集成形态
|
||
|
||
```text
|
||
APS WorldStore / MOM importer
|
||
-> closed_loop_problem
|
||
-> SchedulingProblemV2
|
||
-> OptimizeEngine (Python)
|
||
- dispatch rules: EDD/SPT/PRIORITY/FIFO/LPT/CR/ATC
|
||
- CP-SAT adapter/certification
|
||
-> SchedulingValidator
|
||
-> closed_loop_runtime materialization
|
||
-> APS schedule version / audit / evidence
|
||
```
|
||
|
||
optimize 只能产生候选排产解。Harness、Workflow、WorldStore、版本发布、确认卡、MES 写入和审计仍由 aps-agent 负责。
|
||
|
||
现有 MOM 导入直接复用，不创建第二套 `records` 主模型。optimize 当前 manifest/hash 能力只在必要处转换成 APS 的 source revision、problem hash、solverMeta 和 evidenceRefs。
|
||
|
||
## 5. 下一轮实现范围
|
||
|
||
### In scope
|
||
|
||
- 在 `server/engines/` 增加 Python `OptimizeEngine`，接入 `get_engine("OPTIMIZE")`。
|
||
- 将七种 dispatch 规则迁移到统一的 V2 求解输入和结果结构。
|
||
- 将当前 CP-SAT 认证规则迁移或接入 APS 现有 solver isolation/validator 边界。
|
||
- 将 `SchedulingProblemV2` 转成算法内部只读视图，并将结果转换成 `SchedulingSolutionV2`。
|
||
- 接入算法版本、随机种子、输入 hash、运行 ID、solverMeta 和 evidenceRefs。
|
||
- 复用现有 `server/importers/mom_pack.py` 和 Kangni world fixture，完成真实 MOM 闭环测试。
|
||
- 保留 Node 结果对照脚本或 fixture，验证迁移前后的算法关键指标一致性。
|
||
|
||
### Out of scope
|
||
|
||
- 不复制或重写 aps-agent 的 MOM/Kangni importer。
|
||
- 不创建第二套 WorldStore、订单模型、排产版本或冲突模型。
|
||
- 不迁移 optimize 的前端、独立 Gateway 或独立审批流程。
|
||
- 不在本轮重做 APS 已有 `server/knowledge/` 的知识资产、检索和权限平台。
|
||
- 不把 Node 运行时作为 APS 生产容器的必要依赖。
|
||
- 不在本轮扩展新的 GA、NSGA-II 或其他算法；先完成已确认的七种规则和 CP-SAT。
|
||
|
||
## 6. 实施任务与写入边界
|
||
|
||
本轮后续采用单 agent 轻量实现，所有写入只发生在轮次工作树。任务顺序如下：
|
||
|
||
1. **契约与引擎骨架**
|
||
- 写入范围：`server/engines/`、必要的 `server/aps_domain/` 适配文件
|
||
- 结果：`OptimizeEngine` 可被工厂选择，并明确 V2 输入/输出边界
|
||
- 停止条件：发现 V2 字段不足以表达当前算法所需约束时，先回报，不绕过契约
|
||
|
||
2. **规则算法迁移**
|
||
- 写入范围：`server/engines/` 下 optimize 专属实现和算法目录注册
|
||
- 结果：七种规则在同一 V2 只读问题上运行，返回可校验的候选解
|
||
- 停止条件：规则语义无法在 V2 中保持，或必须修改 WorldStore 才能运行
|
||
|
||
3. **CP-SAT 认证接入**
|
||
- 写入范围：`server/engines/`、必要的 solver isolation 适配和测试
|
||
- 结果：CP-SAT 结果带独立目标/完成时间检查，不声称未经证明的 optimal
|
||
- 停止条件：需要改变现有 solver 子进程安全边界，或出现无法解释的目标不一致
|
||
|
||
4. **真实 MOM 闭环与差分验证**
|
||
- 写入范围：`tests/golden/`、`tests/e2e/` 或明确的 round fixture；不修改原始 MOM 数据
|
||
- 结果：真实 MOM world 能完成 admission、求解、V2 校验和版本物化；被阻断时有稳定 blocker
|
||
- 停止条件：真实数据缺少业务前置条件，必须记录为数据阻断，不通过放宽校验解决
|
||
|
||
## 7. 成功标准
|
||
|
||
- `get_engine("OPTIMIZE")` 能稳定选择 Python OptimizeEngine。
|
||
- 七种规则和 CP-SAT 均使用 `SchedulingProblemV2`，不依赖旧简化生产接口。
|
||
- 结果必须通过 `SchedulingValidator`；非法结果不得写入 APS 生产版本。
|
||
- 真实 MOM 数据从 APS 现有 importer/world 进入闭环，产生以下之一：
|
||
- 合法、可追溯的排产版本；或
|
||
- 明确、可复现的 admission blocker。
|
||
- 版本中包含算法 ID/版本、problem hash、run ID、solverMeta 和 evidenceRefs。
|
||
- Node 对照结果用于发现迁移差异，但不参与生产写回。
|
||
|
||
## 8. 验证方式
|
||
|
||
下一轮至少执行：
|
||
|
||
- `pytest tests/golden/test_rule_engine.py tests/golden/test_cp_engine.py -q`
|
||
- 相关 `SchedulingProblemV2` / `scheduling_validator` golden tests
|
||
- 新增 `test_optimize_engine.py`：工厂选择、V2 字段、规则结果和非法结果拒绝
|
||
- 新增真实 MOM 闭环测试：导入或加载现有 MOM world -> `flex.schedule` -> blocker 或合法版本
|
||
- Node/Python 差分检查：同一固定输入的订单完成时间、总延迟、资源分配和状态语义
|
||
- 运行 `git diff --check`，确认没有无关文件和临时数据
|
||
|
||
真实数据门禁必须在集成点之前安排：先确认 MOM world 的 admission 状态，再判断求解器和物化结果。不能只在最终测试阶段才发现数据本身不可排。
|
||
|
||
## 9. 关键风险与控制
|
||
|
||
| 风险 | 影响 | 控制方式 |
|
||
|---|---|---|
|
||
| V2 与 optimize 旧模型字段不一致 | 迁移时丢失资源/物料/来源信息 | 先做只读 V2 adapter；缺字段时停下扩展契约，不静默丢弃 |
|
||
| 重复维护 MOM 输入模型 | 数据含义和 hash 漂移 | 复用 aps-agent importer/world，optimize 不写业务输入 |
|
||
| Node/Python 结果差异 | 迁移后业务行为变化 | 固定 fixture 做差分；记录算法版本、种子和时间语义 |
|
||
| 外部/不完整 MOM 数据被误判为算法失败 | 错误业务结论 | 保留 admission blocker，阻断时不物化版本 |
|
||
| CP-SAT 认证被绕过 | 产生虚假的 optimal/feasible 声明 | 统一经过现有 solver isolation 和独立 Validator |
|
||
| 迁移范围扩展到 RAG/UI/MES | 本轮失控 | 明确排除；通过现有接口接入，不改主流程 |
|
||
|
||
## 10. 停止条件
|
||
|
||
遇到以下情况暂停并回报，不继续扩大改动：
|
||
|
||
- 必须修改 WorldStore 的权威语义或审批/审计门禁才能接入。
|
||
- 需要引入第二套生产订单、物料、资源或版本数据源。
|
||
- V2 契约无法表达真实 MOM 约束，且无法通过局部兼容字段解决。
|
||
- 真实 MOM 数据的阻断原因尚未明确，却要求通过放宽校验让测试通过。
|
||
- Node/Python 差分出现未解释的完成时间、资源分配或可行性变化。
|
||
- 需要新增生产依赖、许可证或外部服务而没有明确运行环境。
|
||
|
||
## 11. 计划可行性检查
|
||
|
||
PLAN AUDIT: PASS
|
||
|
||
## 14. 本轮实施结果
|
||
|
||
- 已新增 `server/engines/optimize_engine.py`，并通过 `get_engine("OPTIMIZE")` 接入 APS。
|
||
- 七种派工规则（EDD/SPT/PRIORITY/FIFO/LPT/CR/ATC）共用 APS 的能力池、日历、班组、工装和物化逻辑；结果统一进入 `SchedulingSolutionV2` 校验。
|
||
- `/api/flex/schedule` 增加 `engine=OPTIMIZE`；Optimize 版本记录 `solverId`、`solverVersion`、`algorithmId`、`algorithmVersion`，并保留 V2 provenance 和 adapter assumption。
|
||
- 准入阻断时仍由 APS 记录零工单 DRAFT 版本，同时保留请求的引擎身份和 blocker，不绕过 admission。
|
||
- 新增 `tests/golden/test_optimize_engine.py`；Optimize/V2/算法注册表相关定向测试共 20 项通过，相关 APS 回归共 34 项通过。
|
||
- 当前 APS 轮次工作树未包含 `server/data/world-proj_712276ba.json`，因此真实 MOM world 用例只能按既有测试策略跳过；全量 CP/Excel 测试还受到当前环境 NumPy（X86_V2）二进制不兼容影响。CP-SAT 的 V2 原生求解器仍应作为后续轮次接入，本轮不把 PoolEngine 适配器冒充为 CP-SAT 最优证明。
|
||
|
||
阻塞问题：无。
|
||
|
||
检查结论：目标、写入范围、验收标准、验证命令、真实 MOM 门禁和停止条件均已明确；单 agent 任务没有并行写入冲突，也没有依赖未讨论的产品决策。
|
||
|
||
## 12. 目标分支合并前确认
|
||
|
||
本轮计划分支为 `round/85-optimize-integration-shape`，基于 `main`。后续实现、验证和自检通过后，主 agent 必须先报告：主要结论、关键洞察、仍需特别留意的风险和未覆盖环境，再请求用户确认是否合并到 `main`。未获得确认前，不合并目标分支。
|
||
|
||
## 13. 当前轮次完成定义
|
||
|
||
- 本计划文件已提交到轮次分支。
|
||
- 用户确认后才能进入目标模式实现；当前不修改生产代码。
|
||
- 实现完成后必须通过自身检查；如形成集成结果，补充统一集成审计和真实 MOM 验证。
|
||
- 轮次结束时保留计划、验证证据和未合并分支，直到用户明确决定是否合并。
|