diff --git a/docs/round-85-optimize-integration-shape-plan.md b/docs/round-85-optimize-integration-shape-plan.md new file mode 100644 index 0000000..eb44d82 --- /dev/null +++ b/docs/round-85-optimize-integration-shape-plan.md @@ -0,0 +1,200 @@ +# 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 + +阻塞问题:无。 + +检查结论:目标、写入范围、验收标准、验证命令、真实 MOM 门禁和停止条件均已明确;单 agent 任务没有并行写入冲突,也没有依赖未讨论的产品决策。 + +## 12. 目标分支合并前确认 + +本轮计划分支为 `round/85-optimize-integration-shape`,基于 `main`。后续实现、验证和自检通过后,主 agent 必须先报告:主要结论、关键洞察、仍需特别留意的风险和未覆盖环境,再请求用户确认是否合并到 `main`。未获得确认前,不合并目标分支。 + +## 13. 当前轮次完成定义 + +- 本计划文件已提交到轮次分支。 +- 用户确认后才能进入目标模式实现;当前不修改生产代码。 +- 实现完成后必须通过自身检查;如形成集成结果,补充统一集成审计和真实 MOM 验证。 +- 轮次结束时保留计划、验证证据和未合并分支,直到用户明确决定是否合并。 +