Skip to main content

aps-kernel — Metis 谋序(APS 标准版)

运筹帷幄,谋定后动 —— 同衡·谋序·同枢,智造同频。 One Truth. One Plan. One Rhythm.

可嵌入的确定性排产内核:CP-SAT 精确求解、独立复核器、 工序-资源适配数据模型、设备槽位与班次日历、ε-约束 trade-off、headless CLI。

标准版 vs 专业版:本包只含可嵌入内核(无 UI / 无服务 / 无 LLM)。 甘特图前端、Web 控制台、AI 编排层、多租户 RLS、审批与 IM 通道 属专业版(Docker 镜像 + docker compose)。

🌐 官网:https://aps.zhinengti.online 家族:Nereus 同衡(数字孪生)· Metis 谋序(智能排产)· Hermes 同枢(物流调度)


⭐ 求解能力(横向基准,非自说自话)

在 16 个标准 FJSP 实例(ft/la/abz/orb/swv/ta/yn,来源 job_shop_lib MIT, 含文献公认最优值)上的实测:

实例 工单×机器 SPT 基线 规则链 CP-SAT 文献最优 vs 最优
ft06 6×6 94 92 55 55 +0.0% OPTIMAL
ft10 10×10 1530 1310 930 930 +0.0% OPTIMAL
ft20 20×5 1513 1565 1165 1165 +0.0% OPTIMAL
la01-05 10×5 ~1000 ~940 最优 — +0.0% OPTIMAL
abz5/6 10×10 ~1700 ~1600 1234/943 同 +0.0% OPTIMAL
orb01 10×10 1489 1631 1082 1059 +2.2% FEASIBLE
swv01/02 20×10 ~2100 ~2100 1495/1562 1407/1475 +6% FEASIBLE
ta01/02 15×15 ~2100 ~2040 1233/1248 1231/1244 +0.3% FEASIBLE
yn1 20×20 1547 1509 944 884 +6.8% FEASIBLE

11/16 达到文献最优,其余为大规模实例(20 秒预算不足,已如实标 gap)。 全部 11/11 独立复核通过。

python benchmarks/run_standard_bench.py --time-limit 30

当前状态

v1.56.0 —— 「物料没齐的活不许开工」终于在两条路径上都说同一句话(I15 齐套硬约束 · 从 partial 升 implemented)。这条能力 1.50.0 就有雏形,但当时它只是挂在 CP-SAT 求解器的一个选项上(CpSatOptions.kit_blocking)—— 于是贪心路径完全没有保护:直接调 aps_kernel.solver.greedy.schedule() 的调用方(专业版平台、热力图、what-if、reschedule…)照样把未齐套的工单排进计划。这不是「少一个功能」,是同一个业务规则在两条主路径上口径分裂 —— 而当时复核器也没有这一项 ⟹ 谁都看不出来。这一版把它提升为数据形状:ScheduleInput.kit_ready(工单级三态字典)+ ScheduleInput.kit_blocking(开关,默认 False ⟹ 不声明就不改变任何行为),新模块 kit_gate.py 作唯一真源,贪心与 CP-SAT 共用同一个判据,不会两边各写一遍后漂移。两条路径都在入口处(建索引之前)剔除 ⟹ 被拦工序不进排序候选集,不占排序名额、不影响其他工单落位;剔除与记账同源 ⟹ 进 unscheduled + unscheduled_reasons + unscheduled_jobs + diagnostics["kit_blocking"],不静默消失。新增复核器第 18 项「齐套放行」(三查:该拦的没被排 / 拦下的要记账 / 没拦的别冤枉)—— 这一项不能省:齐套拦截是主动剔除,不是参与求解的约束 ⟹ 剔错了没有任何求解器会报错,计划看起来完全正常。⭐⭐ 三态纪律是本条的核心:kit_ready[job] is False 才拦;缺键 / None = 没做判定 ⟹ 放行。用 not ready 判断会把「没导 BOM」当成「没齐」⟹ 用户什么都没配,整个车间排不出来 —— 这是比不做还糟的默认。另加 CLI --kit-blocking、CSV 可选表 kitting.csv、JSON 往返保留两个字段(否则「导出→导入」后齐套拦截静默消失,而复核器读的是导入后的数据,也看不出异常)。1.50.0 的老用法(CpSatOptions.kit_blocking=True + solve(kit_ready=...))逐位不变(显式传参优先于数据字段)。清单缺口 8 → 7(36/43)。⚠️⚠️ 发布前逐条走用户路径,又抓出 5 个「看起来正常、实际错」的缺陷(写完全绿,但旧测试测的是被调用方而不是接线):① --kit-blocking 注册在 solve 而处理代码写在 whatif ⟹ aps solve --kit-blocking 完全无效;② parse_input 用 bool(v) ⟹ JSON null 被当成「未齐套」(误拦)、"false" 被当成「已齐套」(漏拦 —— 物料没齐的工单被排进计划且不报错);③ kit_ready 引用不存在的工单 ⟹ 幽灵工单进未排清单;④ JSON 层不回填 Job.operation_ids ⟹ 工单安静消失(CSV 层早有回填 ⟹ 同一模型两个入口两套行为);⑤ 求解器从未把 kit_ready 传给排序上下文 ⟹ R06「齐套优先」(1.12.0 就实现了)从未真正生效。五个的共同教训:接线测试必须走真实入口 —— 开关类要真跑一次看行为、解析类要用目标格式原文、规则类要测「求解器 → 规则」那一段。

v1.55.0 —— 「这道活发出去做」第一次能表达(I27 外协/委外)。清单里这行长期写着「无外协资源类型、无外协工序标记、无外协提前期(lead time)、无发运/返回时序」。这一版加 OutsourceSpec(lead_minutes, vendor_id, vendor_slots) 与 Operation.outsource:一道工序整道发出去,lead_minutes 是从发出到返回的总周转(运输 + 供应商排产 + 加工 + 回程),vendor_slots 是这家厂同时能接几单。⭐⭐ 关键决定是把它做成「构造期归一化」而不是「一条新约束」:供应商合成成一台厂外资源 @vendor:<id>,工序的候选里补上一条 duration = lead_minutes —— 于是外协工序就是一道普通工序,只是它的设备在厂外。收益不是少写代码,而是口径安全:贪心 / CP-SAT / 独立复核 / 交期倒排 / 负荷报表 / 甘特渲染全部自动同口径,消费方零接线(对比 1.54.0 的质量门要在 5 处分别接线、其中 2 处写完测试还是假绿)。归一发生在 ScheduleInput.__post_init__,结构上不可跳过,且靠结构判据幂等(dataclasses.replace 不会叠加重复资源)。⭐ 供应商挂 24/7 连续日历且刻意不受本厂班次约束:对方班次我们不知道,套用本厂班次会让 30 小时周转期被切成 4 天,而计划看起来完全合理;这也让负荷报表的分母是 1440 而不是默认 480(否则跨夜周转期会被报成 300% 假过载)。新增复核器第 17 项「外协时序」,六查:提前期为正 / 保留前缀自洽 / 同厂槽位声明一致 / 时长==提前期 / 没发错厂 / 并发 ≤ 槽位 —— 前五项各自用只制造那一种违规的数据单独注入验证过,条条真红。刻意不建模(写进 docstring):外协成本与汇率 ⟹ 因此不能替你权衡「自制 vs 外发」(一道工序同时声明内部候选与外协时,求解器只会按最早完工挑,诊断里把它数成 alternative);分批发运;外协件不合格返工(要检就在下一道挂 InspectionGate)。⚠️ 顺带抓到一类更危险的老 bug:JSON 往返在静默丢字段 —— Resource.attributes、Operation.requirements(1.52.0)、inspection_gate(1.54.0)、skill_pool(1.16.0)、Location.available、split_report 都没进 to_dict()/parse_input(),而 parse_input 的 docstring 上写着「可无损往返」。后果是存盘再读回来,人手变无限、质检锁定消失、吨位要求全判无合格设备,症状全在排产上、根因在序列化。还抓到 Priority 每往返一次就降一档(0 基下标碰枚举值:MEDIUM→LOW、URGENT→CRITICAL)。新增 tests/test_roundtrip_contract.py:一条「整图相等」断言(新字段默认失败,不可能假绿)+ 一条「夹具里每个字段都必须是非默认值」的反向断言守着上一条的前提。清单缺口 9 → 8(35/43)。

v1.54.0 —— 「这道活过了检没有」第一次能挡住下一道(I26 质量锁定)。清单里这行写着「内核没有『未过检 ⟹ 强制不可开工』的硬约束标记位,只能把质检当普通工序建模」—— 后者能表达顺序,却把检验变成产出(进甘特图、进未排对账、进产能报表),而且表达不了静置:注塑件必须凉 4 小时再检,那 4 小时不占人、不占机,只是不许开工。这一版加 InspectionGate(hold_minutes 静置 + duration_minutes 检验 + 可选 resource_id 检验台)与 Operation.inspection_gate,放行时刻 = 完工 + 静置 + 检验,后继开工不得早于它;检验占用走并行通道 ScheduleResult.inspection_bookings(像换型占技师那样,不进 assignments)。⭐ 四处同源接线,每处都单独注入验证过:贪心两条路(跨工单 pred_floor 与同工单 level_end —— 只接一条,另一条就静默绕过)、CP-SAT 三处(precedence、stage 串行、检验台进 res_demands 容量池 —— 容量约束必须排在门之后,否则检验台无限产能)、warm 校验、复核器第 16 项「质量门放行」(三查:放行约束 / 记录对账 / 检验台容量)。⚠️ 测试写完发现有两处假绿:同工单用例被 level_end 兜住,pred_floor 删掉也不红;CP-SAT 的 precedence 同理 —— 补了跨工单用例才抓住。刻意不建模(写进 docstring):不合格返工(需不合格率与返工路径,属仿真)、首件检验(与 interruptible 语义冲突)、抽检比例(抽检 20% 与全检同样占满时长)。清单缺口 10 → 9(34/43)。

v1.53.0 —— 交期第一次成为「排程方向」(I21)。清单里这行长期写着「没有倒排调度。交期在模型里的角色仅是惩罚项与排序键,不是排程方向」——事实是 _tardiness 与 CR/EDD 只回答「先排哪个」,而排产引擎从 0.x 起只有一个方向(从最早可开工往后排),于是现场最日常的那句「客户要求 3 月 8 日交货,这批活最晚哪天必须投料」在 CLI 里根本没有入口:只有 aps trace(为什么排在这个时刻),方向正好相反。这一版加 aps backward 与 backward_schedule():在一份已排好的计划上做逆拓扑回推(工单内 seq 降序 + 跨工单 predecessors),给出每道工序的最晚开工、最晚设备就位时刻(− setup)与交期浮动 total_float_minutes(< 0 = 已经来不及,绝对值就是差多少)。⭐ 三个刻意选择:① 不做逆序重排 —— 逆推只读计划、不改分配,不引入第二套时间语义;真逆排会在换型上翻车(A→B 45 分钟 ≠ B→A 45 分钟,负时间轴把方向搞反,而结果看起来完全合理)。② 贴日历 —— latest_fit 找的是「交期前最后一个能放下整段占用区间的起点」而不是算术相减:交期落在午休就把最晚开工退到上午窗口末尾,否则会给一个物理上不存在的时刻。③ 浮动不叫 slack —— trace 的 slack_minutes 是「哪条约束顶住了这个时刻」,这里的 total_float_minutes 是「离交期还有多少余量」,同一个词两个意思,混用会让两个答案看起来像一个。⚠️ 三种「不猜」各有出口且都带原因文本:无交期工单、末道未排(前道因此也无锚点,宁可报无法反推也不给假时刻)、交期前放不下整段窗口;跨窗口工序按实际跨度逆推(分段停机无法复原)。浮动是「依赖链 + 日历」口径,不是「还能右移多久而不撞车」(后者要重排才知道)。⭐ 五条不变量在测试里无条件断言(依赖方向 / 层间串行 / 日历上界 / 浮动单调性 / 逆推不改计划),并用两次注入证明它们真会红:忽略后继 ⟹ 5 条红;latest_fit 退化成「取窗口起点」⟹ 8 条红。⚠️ 写的时候自己又踩了一次 date + timedelta(hours=18) 静默丢小时(交期变成 00:00、全部判来不及),测试里已立成显式契约。清单缺口 11 → 10(33/43)。

v1.52.0 —— 「这台机够不够大」第一次能被表达(I18)。清单里这行写着「缺数据也缺机制:内核没有『资源数值属性』与『工序需求下限』两个概念,所以『这台模具要 160 吨以上冲床』既无字段可填也无代码可比」。此前候选筛选的五个条件全是集合成员判定(resource_id / skill / tool_id 在不在),没有一处数值比较 —— 于是「够不够大」在模型里根本不存在,160 吨的模具会被排到 100 吨冲床上,而计划看起来完全正常。这一版补上两个概念:Resource.attributes(设备属性,如 {"tonnage": 200} 吨)+ Operation.requirements(工序要求,如 tonnage ≥ 160),配两张可选表 resource_attributes.csv / operation_requirements.csv。⭐ 刻意用通用属性字典而不是 tonnage 具名字段:注塑要锁模力、机加工要行程与台面、热处理要炉膛,具名字段只能追着一个行业跑。⭐ fail-closed:资源没标该属性 ⟹ 判不满足,不是「不校验」—— 这与 Resource.tools 的「空 = 不校验」刻意相反,因为撞机是不可逆的物理事故,「没标吨位」不能被当成「吨位无限」。两种原因的文案必须不同(「未声明」= 去补数据;「小于要求」= 换设备),压成一个「不可用」用户就不知道该干什么。⭐ 判据只有一个实现(requirements.unmet_requirement),五处共用:贪心候选 / CP-SAT 候选 / CP-SAT warm 校验 / 诊断模型 / 独立复核 —— 少接一处就会出现「求解器说不能排、复核器说排得对」。复核器新增第 15 项「资源适配」,从 assignments 独立重算。⚠️ 「不写需求就逐位不变」已实测:demo(30,seed=7) 13821 分钟、3 单模板 1020 分钟均未变。清单缺口 12 → 11。

v1.51.0 —— 换型终于要占用技师了(I03)。清单里这行曾长期写着「技师容量从未被占用」:Resource.setup_resource 与 SetupRule.resource 都只起「这台设备要不要建模换型」的门控作用,技师本身不在任何容量池里 ⟹ 3 台设备同时换型、只有 1 名调机工,模型照样让它们并行。这一版把技师真正放进产能:换型窗口 = [工序占用起点 − 换型时长, 工序占用起点),容量 = 技师资源的槽位数(2 个槽位 = 2 名技师可并行)。SetupRule.requires_resource 那个零调用点的死字段随之复活成 setup_resource_for()(规则级 resource 覆盖设备级),于是「A→B 换型要模具师傅、其它换型要普通调机工」这类真实分工第一次有承载位。⭐ 换型占用走独立通道 ScheduleResult.setup_bookings,不塞进 assignments —— 塞进去会同时打破「每道工序恰有一条分配」的对账、给甘特图添一排假工序、把技师分钟算成产能产出。⭐ 复核器新增第 14 项「技师容量」,从 assignments 独立重算而不是信求解器自报,并与 setup_bookings 逐资源对账(「记录」与「计划」分叉时,用户看到的是好看的那份)。资源负荷报表里技师不再恒为 0%(demo 实测 RES-SETUP 峰值 45.4%,此前 0)。⚠️ 破坏性:声明了 setup_resource 且技师真的不够时,换型现在会排队 ⟹ 计划可能变长、工序可能后移;无争用时逐位不变(demo 13821 分钟、3 单模板 1020 分钟均未变,见 docs/MIGRATION.md)。⚠️ CP-SAT 侧尚未建模,diagnostics.setup_technician.modeled 会明说,aps validate 会如实判红 —— 不假装两边一样。

v1.50.0 —— 未齐套的工单不再占着产能空等(I15,opt-in)。aps rules --list 从 1.47.0 起就诚实写着「齐套不是硬约束:未齐套的工单照样被排上设备」——齐套只影响「排哪个在前」,不影响「能不能排」。这一版补上,但做成开关:CpSatOptions(kit_blocking=True) + solve(kit_ready={...}) 时,kit_ready[job] is False 的工单整单不进模型。⭐ 刻意选「从 data 剔除」而不是「加 presence == 0 约束」:_solve_core 内部还有「贪心 warm 当 horizon 上界 + hint」那一层,只在模型里加约束 ⟹ 贪心仍会排上未齐套单 ⟹ 上界不合法、hint 冲突,正是「只改主路径不改回退路径」的老坑;剔除 data 后 CP-SAT / 回退 / 无解三条路径结构上都看不到这些工序。⚠️ 三态:kit_ready 的 None 是「没做判定」(没导 BOM),必须放行,用 is False 严格判断 —— 写成 not ready 就等于「谁导了 BOM 谁才能排产」。被拦工序补进 unscheduled + unscheduled_reasons + diagnostics["kit_blocking"],不静默丢。本版无破坏性变更(默认关闭 ⟹ 现有计划逐位不变);清单 I15 由 absent 转 partial(⚠️ 缺口总数不变,仍是 13:absent 11→10、partial 2→3)。 ⭐ 同版补上 aps gates --check all:把六道门收成一条命令,三态 pass / fail / unknown + 退出码 0/1/2 —— 判不了既不算过也不算不过,并写明去哪儿判(G1 缺真实 bundle、G3 需 30s 求解、G4 在平台包 e2e 里)。有门判不了时退出码是 2(无法认证)不是 0。

v1.46.0(门禁判据) —— 让「数据治理做到什么程度算做到了」能被判定。1.45.0 给了归一器,可 2.0.0 的 G1 门禁写着「可执行率 ≥ 80%」却没法判:那份 21,218 米的数据不在仓库里,每轮都只能重复「指标没动」。这一版补的不是功能,是判据 —— 一份可复现的脏数据语料(tests/fixtures/ingest_corpus/):raw/ 是会动的字节(不靠生成脚本重建,否则改脚本就悄悄改语料)、corpus.yaml 把期望值写成数据(不存 golden file —— 那是把实现的输出抄一遍)、通用 runner 消费它(122 项)。它判的是「归一器有没有漏 / 原因码判得对不对 / 审计层会不会静默丢行」。⭐ 顺带逼出四处真缺陷(都是「以前没人验证过」那一类):DUP_KEY 声明了 1.42.0 起从未抛出(重复工序 id 两条都进模型,同一道活被排两遍、各占一遍产能且不报错)、工序工时没有 > 0 校验(填 0 占位被当成「很快的工序」,整张计划看起来非常漂亮)、休息日 00:00,00:00 被当成「起止填反」、工序没资源时报的修法指向了错误的地方(拆成新码 NO_RESOURCE)。⭐ 反向注入还抓出一处**「能力没守卫」**:operation_resources 的查重豁免(保护「一工序多资源」这个 FJSP 核心能力)当时没有任何样本覆盖 ⟹ 注入后测试纹丝不动,已补样本(现变红 16 处)。⚠️ 破坏性:主键重复不再静默接受、工时 0 现在被拒。但这份语料判不了 44.1% → 80% —— 它是「尺子准不准」的回归护栏,不是「客户数据好不好」的测量 —— 迁移见 docs/MIGRATION.md。

v1.49.0 —— 门禁判据自己也有漏洞 —— 补上;并给拖期加了第二条下界来源(松弛下界);并把第五道门(G5 契约稳定)也变成可执行判据。1.48.0 把 G3(拖期可核证)变成可执行判据后,回头实测小实例时发现判据本身有两处「比门禁宽松」,与 1.47.0 那四处「声明与实现不一致」同一族。① 实例规模不足曾能「通过」:门禁原文是「30 单实例必须满足其一」,但实现只判证书不判规模 ⟹ --jobs 5 会去判 5 单的证书,而小实例更容易拿到 tardiness_certified=true(下界=上界=0)⟹ 5 单就能「通过」一门要求 30 单的门禁。修法:新增 gates.scale_sufficient() 做唯一真源;规模不足 ⟹ 强制判红(且理由要说清「差在哪」)。⚠️ 规模不足不是「判据坏了」(退出码 2)—— 判据本身好好的,是被测对象不满足门禁的前提 ⟹ 属「门禁没过」(退出码 1),退出码三档语义不变。② --json 原本不是纯 JSON:JSON 前面有人读格式的头部 ⟹ jq 直接解析失败。门禁判据的消费者就是 CI ⟹ 输出必须机器可读;现所有人读格式都收进非 JSON 分支,错误路径也输出 JSON。⭐ 两条都有守卫:tests/test_gates.py +6 条(规模门禁 / 纯 JSON / 反向断言非 JSON 模式仍有人读格式),tests/test_gates_injection.py +2 条(其中「规模门禁」那条是端到端的:复制整棵包 ⟹ 注入 scale_sufficient 恒真 ⟹ 断言 2 单从「rc=1 判红」变成「rc=0 放行」⟹ 证明它确实是那道拦截)。⚠️ 顺带把文档里的实测数字改了口径:原写「上界实测 115,497 ~ 119,440」,后续实测出现 108,700 落在区间外 ⟹ 不再把随机值写成区间,改为「11 万分钟量级(⚠️ FEASIBLE 的上界每次找到的解不同)」。

v1.48.0 —— 第四道门(G3 拖期可核证)也能自己判了 —— 而且它诚实地说「没通过」。2.0.0 门禁里的 G3 此前只有一行文档(「下界只到 0,最小拖期从未被证明」),做没做只能靠读文档。新增 aps gates --check g3:按门禁原文读 aps solve --json 的证书四个字段,判 ① 已证最优、② 诚实区间(tardiness_lower_bound > 0 且上界/下界 ≤ 2),并明确拒绝「下界 0」;退出码 0/1/2 与 aps rules --list 同构。⚠️ 实测未通过(30 单 / 240 工序 / 30s):FEASIBLE、拖期上界在 11 万 分钟量级(⚠️ FEASIBLE 的上界每次找到的解不同,实测见过 108,700 ~ 119,440)、下界 0、gap 95.45% ⟹ 判红。⭐ 这正是门禁该有的样子:以前这一格是「可核对未可证」,现在能算出差在哪(差一个正下界)。根因已定位(第②级 FEASIBLE 时 CP-SAT 只证明了平凡界「拖期 ≥ 0」);下一步是加一条松弛下界(忽略资源争抢、按工单算最早完工时间),⚠️ 但那会改变对外字段的数值 ⟹ 属数值口径变更,必须先 A/B 才能上线。⚠️ aps gates 不是六道门总览 —— G1(真实客户数据)与 G5(连续 3 个干净 minor)没有可执行判据,硬写成「跑一下就算」就是造永远绿的假绿灯。

v1.47.0 —— 三道门从「文档里的说法」变成「可执行的判据」。2.0.0 门禁里的 G2(规则清单)、G4(专业版 e2e)、G6(文案对齐)此前只有文档、没有判据 ⟹ 「做没做」只能靠读文档。这一版把三道都变成可跑的:① aps rules --list —— aps 侧规则清单(43 条:通用排序规则 G## 10 条全部已实现 + 行业约束 I## 33 条,缺口在这),每条带「实现位置 / 适用分册 / 缺什么 / 取证位置」,并逐条与代码核对(实现被删 ⟹ 红;缺口被填了 ⟹ 也红)⟹ 清单永远与 reality 同步。⭐ 顺带抓出四处「声明与实现不一致」:换型的技师容量从未被占用(setup_resource 只做门控)、齐套不是硬约束(未齐套的工单照样被排上设备)、负荷均衡只是可选 ε 约束、资源优选匹配(吨位/机床适配)确实没有。② 专业版一条 e2e:CSV bundle 上传 → 排产 → 甘特只读 → 拖拽改期 → 乐观锁冲突 409 → 负荷热力图刷新,任一步失败即整条红(+ 5 条反向注入证明它真能红)。③ 文案守卫:对外材料(README / PyPI / 官网 / 前端 / CLI)不许自称「完整 APS 系统」等,内部文档豁免。⚠️ G1 的真门禁仍未达成 —— 真实客户数据 ≥80% 至今无法判定(那份数据不在仓库里)。

v1.45.0 —— 让「进不来的那 56%」回来一部分。1.42.0 的 aps health 只说了「哪一行进不来、为什么、怎么修」,现场下一句是「然后呢,500 行我手工改到什么时候」。而其中相当一部分根本不用人来判断:「1,200 分钟」「2026.8.15」「300 秒」「有」——这些不是内容错,是写法错。新增 aps_kernel.normalize 与 aps health --what-if / --repair-out:只修写法、不修内容,只动审计已判为「进不来」的行,逐格给出 before/after 凭证,写完回读自证。构造脏 bundle 实测 81.25% → 100%(救回 3 行 / 改 7 格 / 2 轮)。红线写死在代码里:名称里带全角数字不改(改了名就对不上路由且不报错)、单位只按列白名单换算(setup_seconds 常年是分钟,再除以 60 等于把 1.43.0 的坑挖深)、开始/结束填反不自动交换。⚠️ 原因码变具体(UNKNOWN → BAD_SLOT / TIME_ORDER / OUT_OF_RANGE),且「所有行都被逐行拒掉」不再被误报成「整表缺列阻断」——迁移见 docs/MIGRATION.md。

v1.44.0(换型门控) —— 换型矩阵「配了却不用」。上一版把换型矩阵列进「未做」,这一版做完了,才发现真正的坑不在数据、而在内核的门控:setup_rules 配了 ≠ 换型被建模 —— 两个求解器都要求资源声明过 setup_resource(换型要占用调机工/换模工),否则规则一条都不用,而且不报错。最小夹具实测:600 → 645 分钟,文件在、格式对、validate 也不报错,只是少了换型时间。新增 SETUP_RULES_IGNORED(WARNING)让它可见;刻意没有改求解器语义 ——那会改变所有既存数据的 makespan(同 1.40.0 的教训)。Aethon 侧补上 --setup-group-map / --setup-matrix / --setup-resource-slots / --probe-setup,顺带修掉三处接入问题:产品要按编码匹配路由(订单常填编码、路由写中文名)、一张脏单不该让整包失败(改为整单跳过 + 逐单归因)、某类型设备全部停机时要把根因说出来。取证结论很硬:母体四个换型落点全都给不出 from→to —— 模具台账只有 to、换模记录无 from_mold_code 且样本不足、route_steps.mold_code 0/82、setup_time_sec 是每单必付准备(与顺序无关)。⟹ 换型矩阵只能客户给;这次至少把「要什么」变成了有据可查的两张表。 上一版 v1.43.0 —— 让「母体数据能进来了」这句话能被验证。上一版给了尺子(能说清多少行进不来),但没有解决「从 Aethon 导出一次能不能进得来」;实测结论是手工导必错,而且错得无声。两件事:① ⚠️ 列名陷阱:operation_resources.csv 的 setup_seconds 列,值一直是分钟(解析时 ×60)——文档从没写过,按列名填就放大 60 倍且不报错。修法不是改名了事:新增语义正确的 setup_minutes(模板改用它),老的保留为别名且值口径不变(改口径比不改更危险),两列同给则拒绝;这是同类错误第 3 次(前两次:Priority.parse("1") 静默变 MEDIUM、Aethon 交期被写进 status 列)。② Aethon 侧新建唯一导出入口 scripts/export_to_aps.py:三条硬规矩 —— 不猜(产品有两条 active 路由时先判工序指纹是否等价,等价才消歧留痕,不等价直接失败并列候选)、缺失不当零也不当约束(节拍为 0 用 run_time_sec 兜底并逐条报;日历三张表全 0 行所以必须 --workweek 显式给)、导出物必须能进来(写完立刻调 aps_kernel.ingest 审计 + 试排一次,结果写进 export_manifest.json,逐列记录来源与假设)。实测 aethon.db:可执行率 100%/100%、11/11 全排上。三条以前没被说出来过的事实:run_time_sec 恒等于节拍×4(派生字段,而母体自己的 aps_routes.py 却优先取它 ⟹ 工时放大 4 倍);大批量工序不标跨窗就是 11/11 全部 UNSCHEDULED 且只报 INFEASIBLE;排上之后拖期仍达跨度的 111% ⟹ 那是承诺超出产能,调求解器参数没用。 上一版 v1.42.0 —— 把「数据进不来」变成可数的东西。cp_sat_demo 那条教训(初排 21,218 米 → 可执行 9,361 米,-56%)一直只有结论、没有工具:healthcheck 算的是「进来了的数据值可不可信」(折扣估计),而真正咬人的是压根没进来的行 —— 它们在 CSV 解析里第一行脏就整包 raise,healthcheck 根本看不到。新增 aps_kernel.ingest + aps health <目录>:复用唯一解析器逐行归因,给出按行与按工时加权两个可执行率(后者与「21,218 米→9,361 米」同口径),15 个原因码各带「怎么修」,级联失败单独标(1 张工单被拒 ⟹ 8 道工序一起进不来)。⚠️ 破坏性:Priority.parse("1") 曾静默返回 MEDIUM —— 而自带模板写的就是 "5"/"2",等于所有从模板出发的数据优先级都是错的、急单排到最后且不报错;已修,排产顺序会变(迁移见 docs/MIGRATION.md)。 上一版 v1.41.0 —— 「交期优先」从声明变成可核对的证书。上一版留的判断题是「第 ② 级(拖期)的最优值既非上界也非下界(23,006 vs 19,117)」,实测后发现约束一直在(最终解 19,117 ≤ 23,006 恒成立),问题在别处:① 证书里没有一句话解释这两个数的关系,于是被读成「承诺 23,006、实际给 19,117」;② 第 ② 级是 FEASIBLE、下界只到 0(gap 100%),「最小拖期」从未被证明;③ 第 ② 级 UNKNOWN 时那条约束压根没执行 ⟹ 第 ③ 级对拖期毫无约束(实测 det=0.08:T=7,364 vs det=0.2:T=4,916,状态都报 FEASIBLE)。修法:objective 新增 tardiness_bound / tardiness_lower_bound / tardiness_certified / tardiness_improved_by_stage3 四个字段;第 ② 级 UNKNOWN 时用贪心拖期兜底当上界(A/B 四种 det × 两种 seed 解逐位相同,只多一行证书)⟹ 承诺退到最硬的一级**「不劣于规则链」;回退路径与空解路径同步补齐字段。连带修一个只改主路径会漏掉的坑:平台 objective 标量原本「累加所有数值项」,新字段会把它从 2,427 悄悄变成 3 万量级 ⟹ 改成白名单。⚠️ 诚实结论:这一版让「交期优先」可核对,但没有变强** —— 默认配置下第 ② 级普遍未证最优,对外只能说「不劣于该级所得解 / 不劣于规则链」。 上一版 v1.40.0 —— 把「预算」和「证书」变得可测量,并借此否掉三个「显然该做」的改动。① max_deterministic_time 此前是每级各给一份 ⟹ 实际总工作量 3×det,且 STAGE_*_SHARE 对 det 完全失效(改份额只改墙钟)⟹ 「同一 det 预算下比较两种份额」的实验根本做不出来;现改为按墙钟份额切分,新增 CpSatStats.stage_det 可断言。② 新增可信 A/B 工具:workers=1 + 固定 seed + 固定 det 逐位可复现(实测两次 branches=204497 完全相同、墙钟差 6%)⟹ 差异只来自算法。③ lexicographic_stages 会位置漂移(某级没跑就整体前移,实测 [0.0, 6698.0] 把 makespan 摆在索引 1)⟹ 新增 lexicographic_stage_names;并统一回退路径的键名(此前回退只写 stage_values,按 lexicographic_stages 取值拿到 None)。实测否决三个优化(结论已写进代码,防止重来):给拖期加「不劣于规则链」硬上界 ⟹ 分支数砍半、seed 42 直接回退(6,331/19,117 → 贪心 10,890/27,686);同预算拆多起点取最优 ⟹ 拖期 +30%;份额再平衡 20/80 ⟹ seed 42 变好、seed 143 反向,实例敏感故不改默认。上一版 1.39.0 —— 20 单求解从「时好时坏」到稳定。三个真因:① 字典序三级各建 solver 却从不传解 ⟹ 第 ③ 级重付 18 秒去找一个已经拿到过的可行解(修:_carry_solution_as_hint,CpSatStats.hints_carried 可观测);② 「makespan 不劣于贪心」的上界只加在第 ③ 级,而第 ② 级的解 makespan 13,772 > 贪心 10,890 ⟹ 传下去的解被自己的上界排除 ⟹ 修 hint 失败(修:上界提前到第 ② 级前);③ 「总拖期」一直是逐工序累加,一单 8 道工序越期罚 8 次 —— demo 20 单放大 6.68 倍(184,818 vs 27,686),第 ② 级的最优方向被「工序数」污染(修:模型/报告/贪心三处统一按工单 Σ max(0, C_j − d_j))。⚠️ 拖期口径变更破坏兼容:total_tardiness_minutes 与 ε 预算值需要按新口径重新标定。顺带修一个诚实性 bug:「前级 FEASIBLE + 末级 OPTIMAL」曾被标成 OPTIMAL(实测低报 773 分钟却挂着最优标签)。实测 20 单 30s 六次:2/6 → 6/6 不回退,makespan 3,849~6,825(贪心 10,890)。上一版 1.38.0:P1-9 的成因查清了,不是 presolve:presolve 本就全程关闭,把它打开反而 branches=0(1.8.0 结论仍成立)。真因是COMPACT_AUTO_OPS = 320 按旧模型标定 —— 逐窗口建模每工序约 600 个变量,20 单就是 96,118 个变量,30 秒内一个可行解都没有;紧凑建模同一数据 2,662 个变量(3%),同预算能到 5,032。阈值改为 64(8 单起紧凑),实测 12 单从 4,857(回退贪心)变为 2,506 / 平台 2,115(不回退)。另修两处「声明与实现不符」:回退路径把 hint_used/hint_feasible 写死成 True(hint=False 也报「已用且可行」),以及原阈值测试是恒真断言。⚠️ 20 单 30 秒仍不稳(16 次仅 2 次成功),已排除五个嫌疑并如实登记。上一版 1.37.0:网页不再静默回退(solverFallback)。

模块 状态 关键能力
数据模型 P0 ✅ 工序-资源适配、空适配 ≠ 全设备可用、槽位
输入校验 P0 ✅ 三项 P0 准则 + 5 类检查 + 跨窗口工序预警(OP_WINDOW_TOO_SMALL,1.19.0)
规则引擎 P1 ✅ 7 条规则(CR/EDD/SPT/WKWR/ATC/加权优先级/FIFO)+ 8 条链
日历与齐套 P2 ✅ 三日历求交、班次×资源×位置、工单级齐套布尔判定
换型规则链 P2 ✅ frePPLe 语义、无匹配 = 硬约束禁止、参数配置化、非对称 A→B≠B→A、矩阵格式
CP-SAT 求解 P3 ✅ 字典序三级目标、容量池用 AddCumulative、冻结窗口
独立复核器 P4 ✅ 18 项真检查(含日历可行、模具互斥、技能资格、依赖满足、技能池容量、换型成本、技师容量、资源适配、质量门放行、外协时序、齐套放行)、用输入重算不信任求解器
Provenance P4 ✅ 快照 hash + 配置/源码/求解器版本
CLI + 基准 P5 ✅ solve / benchmark / explain / chains / health / lotting
冲突诊断 ✅ aps explain —— 最小冲突集 + 排不下原因
ε-约束 trade-off ✅ 钉住交期预算,问 makespan 能压到多少
数据体检 ✅ aps health —— 四张底账逐项核对 + 可执行率估计
规则清单(可执行) ✅ aps rules --list —— 43 条(通用排序 G## 10 条全实现 + 行业约束 I## 33 条,缺口 13 条在这(partial 3 / absent 10)),逐条与代码核对(实现被删 ⟹ 红;缺口被填 ⟹ 也红),退出码可接 CI
设备负载均衡旋钮 ✅ ε-约束第 3 个旋钮:钉住设备负荷不均衡度
工装模具约束 ✅ 跨设备 NoOverlap —— 冲压/注塑的头号约束,「机床等模具」不再是隐患
并行工序 ✅ 同 seq 的工序可同时执行(双人工位装配 / 多工位并行检测)
序列相关换型 ✅ 换型真实占用产能(贪心+CP-SAT+复核器三方一致);A→B 与 B→A 可不同
换型成本 ✅ SetupRule.cost(元/次)→ Assignment.setup_cost,result.csv/甘特图/求解证书三个出口(1.17.0)。⚠️ 只计真换型,固定准备不计;四层费率由用户自配
换型矩阵格式 ✅ 直接贴工厂的换型矩阵表(行业通用格式),支持非对称与「禁止该换型」
拆批合批 ✅ 求解前预处理;工时按数量缩放;最小批量约束;合批守交期红线
人员技能资格 ✅ 工序声明技能 → 资源必须持证(1.6.0)。无证资源自动跳过;缺证时警告点名技能而非静默
工序依赖 ✅ predecessors + min_lag_minutes(1.7.0):跨工单拓扑就绪门 + 并行组内分层 + 前道完工地板;pred 未排 ⟹ 约束不生效(与 CP-SAT presence 语义一致)
固定准备时间 ✅ setup_seconds(1.7.0):装夹/调机首件确认每单必付,占用区间 [start−P, end] 两求解器+复核器三方同口径
有效工时(能率/倍速) ✅ Resource.max_efficiency(设备能率上限)× OperationResource.efficiency(产品实际倍速),取 min 后折算工时(1.11.0)。2 腔注塑机跑 1 穴产品不会凭空快一倍
设备保养窗口 ✅ Resource.maintenance + calendar.maintenance_schedule(every_days=6, duration_days=1)(1.15.0)。日历层挖洞,两求解器+复核器天然同口径。⚠️ 周期按自然日近似,非按累计加工量
计划员入口(标准版用起来) ✅ aps demo 生成 CSV 模板 → Excel 填报 → aps solve --gantt/--csv/--certificate/--validation-report。全程不写代码(1.9.0)。⭐ aps demo --tight-due 紧交期变体 + 配套急单:aps whatif 目录 --add whatif-urgent.json --freeze-before 1000 一跑就能看到 pushed/flipped_late(默认模板交期偏宽,这两栏恒为空——1.29.0 补的演示盲区)
插单影响仿真(What-If) ✅ aps whatif --add delta.json:插一个急单,谁被推后/谁从准时变拖期/makespan 增多少。冻结已下达计划 + 重排 + 差分;冻结逐条核对(frozen_honored),CP-SAT 回退贪心时如实标注质量降级(1.20.0)
可解释规则链推荐 ✅ aps recommend 输入.json:按实例特征(换型组覆盖/交期紧度/等级差/候选数)推荐规则链,每条推荐带可核对理由;特征不足降级 default 标 weak,不硬凑;推荐不排他——附 benchmark 对比命令(1.30.0,策略回路第一步)
计划执行风险(概率交期) ✅ aps risk 输入.json --plan plan.json:时长 PERT-Beta 矩匹配采样 + 按计划顺序前向传播 ⟹ makespan 与各工单完工 P50/P80/P95、每张单按期概率、敏感性 TOP(哪道工序波动最伤交期)。口径诚实:计划固定、时长波动,非重新优化;同 seed 必同结果(1.30.0)
日补货计划 ✅ aps replenish 输入 --bom --inventory [--plan]:工单物料需求 ⟹ 净额双口径(net_now=需求−现库存[在途救不了当天开工] / net_total=再减在途[订单按它提])+ 批量取整 + 在途 ETA 晚于开工警告(总缺口 0 也会延期开工)。建议=「计划工件」(PlannedOrder,MO/PO 种子),转单是下游决策;单层 BOM/无预测口径写死(1.34.0,E3-1 决策 8.1)
审批账本(HITL) ✅ ApprovalLedger(追加写 JSONL/SQLite)+ ApprovalGate:commit/方案切换/undo 等改变基线的动作过门,未批准 ⟹ 结构化拒绝 APPROVAL_REQUIRED;AI 工具面刻意没有 approve(AI 可提议可查看,不能裁决自己)。账本管决定不管执行(诚实边界写死)(1.31.0)
求解参数/链草稿推荐 ✅ recommend_solver_options(特征⟹时间预算,出处式推论非新基准);validate_chain_draft(LLM 写草稿、内核校验、人审入库 —— P2-6 纪律进校验)
MS Project 导入 ✅ aps import-mspdi 计划.xml:只读 MSPDI(Project 另存为 XML)⟹ ScheduleInput + 逐条映射报告(摘要跳过/里程碑零工时/SS 等类型点名跳过/未分配落 UNASSIGNED 告警/日历不搬)。导入产物可排可复核(1.31.0)
AI 会话方案管理 ✅ ApsSession.commit/discard/undo/save_scheme/load_scheme:「就按插了 J-7 的方案继续」可执行;commit 落库并作废旧基线(必须重解);方案 A/B 对比;工具 aps_apply_whatif/aps_scheme 带结构化拒绝码(1.30.0)
滚动重排编排(专业版) ✅ POST /api/v1/reschedule/rolling:到点/偏差触发 ⟹ 冻结=已发生的现实(实绩覆盖计划——实际 8:25 开工,新计划从 8:25 接续)+ 带符号差分 + baseRevision 409 防互踩。内核 solve_with_maintenance(frozen=) 两求解器同源透传(1.30.0)
专业版工程面 ✅ API key 认证(APS_API_KEY,未设=关闭+显式警告)+ SQLite 持久化(APS_DB_PATH:会话基线/滚动历史)+ Dockerfile/compose + GitHub Actions CI(1.30.0 —— 此前是家族三仓中唯一无 CI/无 Docker 的)
家族闭环实验 ✅ scripts/family/:①计划⟹ILESP TaskBody 派工契约(缺站点映射=跳过+告警)②CPS 影子扰动⟹推演输入(故障→保养窗口/急单→whatif delta)③baseRevision 家族协议 PoC(两系统两条路径独立算令牌⟹同值)。各带 --self-test(1.30.0)
计划 vs 实绩对账 ✅ aps compare 输入.json --plan plan.json --actual 报工.csv:逐工序偏差(开工/完工/时长/换设备)+ 按设备汇总 + 工单完工偏差 + 换型假设 vs 实绩间隙(校准的数据源)。四态如实报告:配对 / 实绩缺报 / 计划外 / 计划未排但现场干了;实绩为空或缺 horizon 响亮失败,不出空报告(1.29.0,实绩回路第一步——对账先于学习)
拖拽重排(交互式甘特) ✅ aps_kernel.reschedule_move(data, MoveRequest(...)):把一道工序拖到新位置,前道原位钉死 + 后道按同一位移量顺延,其余交 CP-SAT 重排 ⟹ 完整新计划 + 差分报告。⭐ 差分三档口径:moved(全部位移,带符号,含被提前的)/ pushed(只取正,向后兼容)/ flipped_late+new_late(准时变拖期)。⭐ 诚实闸门 moved_honored 逐条核对资源+槽位+起点,无解时如实报 INFEASIBLE ⟹ 前端必须提示「拖拽未生效」而非假装成功(1.22.0)
行业分册(专业版规则库) ✅ src/aps_kernel/data/industries/*.yaml 可执行配置(随 wheel 分发,pip 用户 aps industries 直接可见)+ aps industries / solve --industry。注塑册(1.18.0:非对称换型矩阵 + 四层成本 + 保养 + 首检/烘料)、冲压册(1.19.0:同吨位 12min / 跨吨位 45min + 首件检测 2h)、机加班(1.22.0:换型三档 45/60/90min + 组名三段式约定 + Aethon 实测的固定准备 15min)。每条参数标来源;应用后结果必须改变(测试锁住)

三个设计立场

1. 诚实高于漂亮

OPTIMAL 只在真正证明最优时才标;FEASIBLE 必带真实 gap; 超时回退贪心解时 diagnostics["solver_fallback"] 明确标注来源; 全部未排时标 INFEASIBLE 而非 OPTIMAL(避免"看起来排好了")。

这直接对应论文《Formalize, Don't Optimize》的三个统计口径: 返回结果率 / 验证通过率 / 已返回中通过比例 —— 分母不同,不可混比。

2. 复核器是必需品,不是锦上添花

validator.independent_validate() 用输入数据重算(时长、槽位、日历、 换型、设备资格、技能资格、依赖满足),不信任求解结果自报的值。这不是防御性冗余 ——

开发中它抓到过槽位重叠 48 处而求解器报 OPTIMAL、 makespan = 2.3e18 的垃圾值(UNKNOWN 时仍读未赋值变量)。

3. 基准必须公平

所有基线必须在相同约束集下比较。曾实现一个无视日历/工序先后的 SPT 基线, 得出「SPT 比 CP-SAT 还优」的颠倒结论(vsSPT = -203%)。

非法基线比没有基线更糟 —— 它会得出完全相反的结论。


🏗 分层架构:本包的位置

博客园《CP-SAT 排产、排程、排班》:

「APS(长周期规划)+ RTS/RTD(实时派工)双层架构是业界最佳实践」 「前一天做的排程,第二天全乱套」—— 排程 ≠ 派工 是经典误区

┌─────────────────────────────────────────────────┐
│  上层(aps-platform / 本包之外)                  │
│  · MRP / 采购 / 库存                              │
│  · APS 长周期计划(天/周)                        │
│  · RTS / RTD 实时派工(分钟级)  ← 不在本包        │
│  · MES 执行回写 / 甘特图 UI                       │
└─────────────────────────────────────────────────┘
                ↕ ScheduleInput / ScheduleResult
┌─────────────────────────────────────────────────┐
│  aps-kernel(本包)—— 求解内核,不含流程            │
│  ✅ 数据模型 / 输入校验                            │
│  ✅ 规则引擎(7 规则 + 8 链)                     │
│  ✅ CP-SAT 精确求解 + 贪心兜底                    │
│  ✅ 冻结窗口(支持增量重排)                      │
│  ✅ 独立复核器(18 项)                          │
│  ✅ ε-约束 trade-off / 冲突诊断 / 基准            │
│  ❌ 不做派工、不做 UI、不做持久化、不含 LLM         │
└─────────────────────────────────────────────────┘

⚠️ 为什么派工不在本包:派工是高频决策(分钟级刷新), 需要实时状态推送与人工干预;本包是低频决策(计划级), 追求确定性与可审计。把两者混在一个包里会同时失去两者。

⚠️ 本包负责「证明这个计划可执行」,不负责「生成甘特图」:

「排产的难点从来不是生成一个计划,而是证明这个计划在约束下可执行。」 —— 《LLM 不会给你最优排产,求解器会》


版本与兼容性

当前 1.56.0 —— 功能优先迭代期,API 会随功能演进
含义 ⚠️ 1.0.0 的 API 冻结承诺已于 2026-10-17 取消,现按功能优先迭代
变更记录 CHANGELOG.md —— 逐版本变更
升级迁移 docs/MIGRATION.md —— 破坏性变更清单 + 「数值会变多少」的实测对照。升级前必读
2.0.0 门禁 docs/2.0.0门禁.md —— 六道可核对的门,回答「现在离 2.0 还有多远」

快速开始

⭐ 不会写 JSON?走这条路(1.9.0 起,给计划员用的入口)

pip install aps-kernel

# 1) 生成一套带示例数据的 CSV 模板(五张表)
aps demo mydata

# 2) 用 Excel 打开 mydata/ 下的 CSV,改成你的数据
#    (jobs / operations / operation_resources / resources / calendar)

# 3) 求解 + 出甘特图 + 出可贴回 Excel 的结果 + 求解证书 + 复核报告
aps solve mydata/ --solver cpsat \
    --gantt gantt.html --csv result.csv \
    --certificate cert.txt --validation-report audit.html

# 4) 双击 gantt.html 看甘特图;audit.html 看独立复核的 18 项

三个产物各回答一个问题:

产物 回答
gantt.html 计划长什么样
cert.txt 这个解证明过吗(OPTIMAL 才写「已证明最优」,贪心解写「未经求解器验证」)
audit.html 独立复核器逐条验算的结果(不复用求解器任何中间结果)

全程不需要写一行代码、不需要懂 JSON。五张表都是扁平 CSV, Excel 直接改;导入时缺列/类型错会点名到文件和列名,不会静默取默认值。

程序员路径(JSON / Python)

# 0) ⭐ 上线前先体检(核对工时/BOM/日历/换型矩阵四张底账)
aps health input.json --bom bom.json --inventory stock.json

# 1) 看内置规则链
aps chains

# 2) 求解(贪心,快)
aps solve input.json --chain default

# 3) 求解(CP-SAT,可证 OPTIMAL)
aps solve input.json --solver cpsat --time-limit 30 --gantt g.html --csv r.csv

# 4) 排不下时诊断原因(最小冲突集)
aps explain input.json

# 5) 基准验证(规则链 vs SPT vs CP-SAT)
aps benchmark --sizes 5,8,10 --chains default

# 6) ⭐ 看 aps 侧规则清单(通用排序规则 vs 行业约束,分母分开)
aps rules --list

aps health 的退出码可直接接 CI:0 可上线 / 1 需补数 / 2 阻断。

aps rules --list 的退出码同样可接 CI:0 清单与代码完全一致 / 1 有条目核对失败或清单与代码脱节 / 2 清单本身坏了。 ⚠️ 两档失败刻意分开:「清单坏了」要修文件,「清单过期了」要补实现或更新清单。

from aps_kernel import schedule, solve, CpSatOptions, independent_validate

# 贪心(快,不证明最优)
result = schedule(data, chain="default")

# CP-SAT(可证 OPTIMAL)
result, stats = solve(
    data, options=CpSatOptions(time_limit_seconds=30, workers=8),
)

# 独立复核 —— 不信任求解器自报
checks = independent_validate(data, result)
assert all(ok for _, ok, _ in checks)

🤖 AI 集成(两条路,按场景选)

⭐ 本包在完全没有 LLM 的环境下 100% 可用 —— 核心(求解/复核/诊断) 零 LLM 依赖,pytest tests/ 不需要装 byoe、不需要 API key、不需要网络。 AI 能力是可选增强。

路径 A:进程内类库(AI 副驾 / 对话式排产,推荐)

同进程调用,数据留在 Python 侧,LLM 只发小增量:

pip install 'aps-kernel[byoe]'    # 可选依赖,MIT
import byoe
from aps_kernel.byoe_bridge import build_aps_agent

agent = build_aps_agent(data=my_schedule_input)
print(agent.chat("这周产能够吗?插一个急单会挤掉谁?"))

为什么类库比 MCP 更适合 AI 场景(两条硬伤,均实测):

MCP 路径 类库路径
数据搬运 3 单的 ScheduleInput JSON = 27,908 字节;tools/call 无状态 ⟹ LLM 每次全量搬 Python 侧持有数据集,LLM 只发小增量(插单只传一个新工单)
超时 byoe 的 MCP 客户端硬编码 30 秒 ⟹ 需 async_mode + task_id 轮询 进程内直调,无此限制

提供 6 个会话工具:aps_solve / aps_whatif_insert / aps_plan_summary / aps_explain / aps_health / aps_validate。

路径 B:MCP server(跨进程 / 跨语言 / 任何 MCP 客户端)

aps-mcp        # 或 python -m aps_kernel.mcp_server
import byoe

agent = byoe.create_agent(
    model="deepseek-v4-flash",
    api_key="sk-...",
    mcp_servers=[{
        "name": "aps",
        "command": ["aps-mcp"],
        "allow_tools": ["aps_*"],
    }],
)

⚠️ MCP 客户端超时 30 秒 ⟹ 大算例请用 options.async_mode=true (立即返回 task_id),再用 aps_get_result 轮询。

两条路共用同一份实现

工具定义在 aps_kernel/tools.py(协议无关层),MCP 与类库只是两个宿主 ⟹ 结构上杜绝「口径分裂」。


已知局限(诚实列出)

局限 说明
Job.due_date 只能表达天 ✅ 已修复(v0.10.0):改为 `date
交期需整日或整时 建议传 datetime;传 date 时按当天 00:00 算,不是「当天结束」—— 与部分 APS 的约定不同,转换时请留意
大规模 gap 仍大 实测(1.8.0,12 机 24 槽位,30 秒预算):该实例族上约 50 工单以内达 OPTIMAL,80 工单起超时回退贪心。⚠️ 不能推广成「工单数 < N 就能证最优」:2026-10-31 用 demo 数据复测(30 秒 / 8 workers)只有 4 单 OPTIMAL,6/8/10/12/16 单均为 FEASIBLE —— 能否证明取决于实例结构、预算与目标级数,请以证书里的 status 为准,不要按工单数推断。已修的根因是 presolve 吃光预算(branches: 0,搜索从未运行)—— 熔断后 3 工单快 8 倍、20 工单从 UNKNOWN 变 OPTIMAL/6.9s。仍存限制:makespan 级本身在 30 秒内证不了最优(裸模型能 OPTIMAL,说明瓶颈在该目标的建模而非 presolve,属下一步优化对象)
换型为静态规则,非序列相关 ✅ 已修复(v1.4.0/1.5.0):换型时间真实占用产能(此前只记录不预留,计划现场执行不了);A→B 与 B→A 可不同(换下的模具比装上的更重是物理现实)。仍不支持「A→B→C 链式换型」的组合优化
缺拆批合批 ✅ 已修复(v1.5.0):split_input / merge_compatible_jobs。工时按数量线性缩放(不缩放时拆 4 批 makespan 120→480)。合批守交期红线,默认关闭
换型建模假设「同槽位同组成块」 CP-SAT 的换型约束是充分非必要的(排除交错排法),非等价改写。换型极贵时该假设成立,但这是真实限制
工序必须放进单个日历窗口 ✅ 已修复(v1.21.0):Operation.interruptible 支持跨窗口续排(午休/夜间停机时暂停加工)。⚠️ 约束:跨度独占槽位(工件不下机,段间空隙不能插别的活);首段必须容得下固定准备(setup_seconds 装夹/调机不可打断);各段长度之和 == ceil(工时) + 准备。两个求解器同口径
模具无寿命/维护周期建模 ✅ 已修复(v1.15.0):Resource.maintenance + calendar.maintenance_schedule(日历层挖洞,两求解器+复核器同口径)。⚠️ 周期按自然日近似,非按累计加工量;「这副模还能用几次」的寿命计数仍未建模(冲压按冲次保养同属此列,P2-8)
技能只有资格过滤,无池容量 ✅ 已修复(v1.16.0):ScheduleInput.skill_pool(厂级几人 = 几并行),CP-SAT/贪心/复核器三方同口径。⚠️ 多工种共享同一设备的并发上限仍未建模(专业版)
无持久化状态 每次求解无状态,冻结窗口需由调用方传入
合成 demo 交期偏宽 demo 默认交期 = horizon+5 天 ≫ makespan → 拖期恒为 0;验证拖期逻辑需改用紧交期
体检的可执行率是估计值 基于静态校验,不检查「现场是否会临时变更」。cp_sat_demo 实测 44%,本估计通常偏乐观

安装与依赖

  • Python ≥ 3.11
  • 运行时依赖:ortools >= 9.12、PyYAML
  • 仅发 wheel(py3-none-any),不发 sdist

License

MIT

Metadata

Release files for aps-kernel 1.56.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Built distribution (wheel)

Table of built distributions (wheels) for aps-kernel 1.56.0
File Interpreter ABI Platform Actions
aps_kernel-1.56.0-py3-none-any.whl Python 3 none any Details for aps_kernel-1.56.0-py3-none-any.whl

Release files / aps_kernel-1.56.0-py3-none-any.whl

Download URL aps_kernel-1.56.0-py3-none-any.whl
Size 628.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
27b78cdc50ea88f947f80ab2e17c344d6ef71431fbcf031e990db7c342497163
BLAKE2b-256 checksum
How to use checksums
fee8f7989448f2e11fd69b5f9998682d9f450c6ffe03959e860b62b936d092df
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.7

Security for aps-kernel 1.56.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.56.0 This release

1 release file No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page