aps-agent/docs/architecture/harness.md

门禁权力矩阵（Harness）

与 server/agent_core/harness.py 的 _POWER_MAP 一一对应。
改 _POWER_MAP 或新增需备案的 API → 同轮改本表，并在 ../CHANGELOG.md 留痕。

等级语义：P0 只读 / P1 写沙盒或草稿（直通）/ P2 写主干或破坏性（单次确认卡）/ P3 外部副作用（二次确认；未登记动作默认 P3 拒绝）。

权力矩阵（与 _POWER_MAP 同步）

action	等级	为什么是这个等级	确认卡要点	加入
schedule.run	P1	试排只产草稿版本	无需确认	M1
schedule.publish	P2	发布写主干、推进订单状态	版本号/订单数/冲突数；发布前自动建档	M1
scenario.compare	P1	深拷贝沙盒，主干零接触	无需确认	M2
scenario.sensitivity	P1	参数扰动 Tornado，沙盒不写主干	无需确认	SC-06
sop.compile	P0	SOP→约束编译预览	无需确认	IND-02
sop.apply	P2	应用 SOP 规则包	效果摘要；写前自动建档	IND-02
checkpoint.create	P1	只新增快照	无需确认	M2
checkpoint.rollback	P2	整体替换主干世界	目标检查点；回滚前再自动建档	M2
data.reset	P2	清空重播种子	明示重置；重置前自动建档	M1
knowledge.query	P0	只读知识；强制出处	无需确认	M3
knowledge.import	P2	导入 PDF/docx/md 切块入库	文件/切块数；确认后写资产	RAG
skill.list	P0	外部算法 skill 清单	无需确认	Skill
skill.health	P0	skill 健康检查	无需确认	Skill
skill.register	P2	登记/更新 skill 端点	ID/端点/轨道	Skill
skill.enable	P2	启停 skill	skillId + 目标状态	Skill
guidance.next	P0	主动引导下一步建议（空态/冲突/知识未命中）	无需确认	AG-07
params.query	P0	排产参数只读	无需确认	OR-02
params.update	P2	客户等级/目标权重/展望期	变更摘要；写前自动建档	OR-02
param.optimize	P1	参数优化触发（split→回放→候选 GRAY，不写主干参数）	无需确认	§9.8
param.experiment.promote	P2	实验转正：验证集回放 finalize GRAY→FULL，退化自动回滚	实验摘要/候选参数/回放 KPI；写前自动建档	§9.8
param.experiment.rollback	P1	手动回滚实验（恢复基线参数）	无需确认	§9.8
param.observation.record	P1	线上 KPI 观测回调（对比基线，连续劣化自动回滚）	无需确认	§9.8
constraint.profile.query	P0	约束剖面只读	无需确认	SC-04
constraint.profile.save	P2	约束启停/硬软	变更摘要；写前自动建档	SC-04
constraint.rule.query	P0	约束规则库只读（默认通用规则 + 计划员扩充规则）	无需确认	SC-04
constraint.rule.save	P2	计划员一句话扩充规则（新增/启用/停用/删除）	类别/范围/强度/是否接入引擎；写前自动建档	SC-04
governance.rule.create	P2	创建规则会改变自动化执行输入	规则标识/房间/触发器；批准后写入并自动建档	R71.6
governance.rule.update	P2	更新规则会改变自动化执行语义	规则标识与 before/after；批准后写入并自动建档	R71.6
governance.rule.delete	P2	删除规则会停止后续自动化执行	规则标识；批准后删除并自动建档	R71.6
governance.rule.enable	P2	启用规则会使其参与自动化 tick	规则标识与目标状态；批准后写入并自动建档	R71.6
governance.rule.disable	P2	停用规则会使其退出自动化 tick	规则标识与目标状态；批准后写入并自动建档	R71.6
report.generate	P1	产出文档并入知识库（不改排产世界）	无需确认；对外承诺函未来升 P2	M3
order.upsert	P2	新增/编辑销售订单会改变后续排产输入	客户/产品/数量/交期；写入前自动建档	M4 首切片
order.cancel	P2	取消订单会从后续排产输入中排除	订单号/当前状态；写入前自动建档	M4 首切片
order.complete	P2	完成订单会从后续排产输入中排除	订单号/当前状态；写入前自动建档	M4 首切片
order.delete	P2	物理删除订单池记录	订单号；清草稿 MRP；写入前自动建档	录数
order.clear	P2	一键清空全部订单与采购/委外建议	条数摘要；写入前自动建档	清理
order.submit	P1	提交审核：DRAFT/REJECTED/CHANGED → SUBMITTED	无需确认	OR-03
order.approve	P2	批准进排产池：SUBMITTED/CHANGED → APPROVED	订单号列表；写入前自动建档	OR-03
order.reject	P2	驳回：SUBMITTED/CHANGED → REJECTED	订单号/原因；写入前自动建档	OR-03
rush.evaluate	P1	插单影响快评：双沙盒对比，不改主干	无需确认	OR-04
rush.apply	P2	采用插单：LNS 局部修复（apply_lns_local，DRAFT+LNS_RUSH，窗口外订单冻结）或升级全量重排（apply_rush）；execute_confirmed 按 impact.lns 路由 LOCAL/ESCALATE	影响摘要+lns 摘要；写入前自动建档；audit 记 mode+escalateReasons	OR-04
forecast.query	P0	预测/长周期订单只读	无需确认	OR-05
forecast.upsert	P2	新建/编辑预测台账（默认不进正式排产）	产品/数量/分桶/交期；写入前自动建档	OR-05
forecast.delete	P2	删除预测台账	预测号；写入前自动建档	OR-05
forecast.convert	P2	预测转正为 APPROVED 销售订单	预测号→销售单；写入前自动建档	OR-05
plan.buckets	P0	时间分桶计划：日/周/月/混合粗能力对照	无需确认	PL-01
plan.rccp	P0	有限/无限产能粗评估对照（RCCP）	无需确认	PL-02
plan.feasibility	P0	交期可行性：累计粗能力能否按期	无需确认	PL-03
plan.inventory	P0	库存投影：物料随时间可用量曲线	无需确认	PL-04
plan.leveling	P0	产能平衡/削峰：超载桶挪空档建议	无需确认	PL-05
plan.supply	P0	产供方向：加班/扩线/外协结构化建议	无需确认	PL-06
project.create	P1	新建项目与默认会话	无需确认	AG-08
project.delete	P1	删项目元数据（不删世界）	无需确认	AG-08
session.create	P1	新建会话	无需确认	AG-08
message.append	P1	追加会话消息	无需确认	AG-08
message.replace	P1	整包替换会话消息	无需确认	AG-08
workspace.replace	P1	整包同步工作区（迁移）	无需确认	AG-08
data.import	P2	自然语言批量导入订单/物料	行数摘要；写入前自动建档	录数
master.line.upsert	P2	产线编辑/停启用改后续新排产资源池	产线/产能/状态变更影响面；写入前自动建档	M4 首切片
drawing.master.apply	P2	工程图纸候选写入物料、BOM 与工艺主数据	图纸来源、候选摘要与主数据影响；写入前自动建档	图纸解析
master.material.upsert	P2	物料新建/全字段/停用改齐套与产品池	编码类型库存状态；写入前自动建档	工艺模型
master.maintenance.upsert	P2	维保新增/取消改设备避让窗口	设备/窗口起止；写入前自动建档	M4 首切片
master.bom.upsert	P2	BOM 头/明细增删改齐套与采购建议	增删改用量/关键料；写入前自动建档	工艺模型
master.routing.upsert	P2	工艺路线/步骤增删改占槽与外协	步骤工时/外协；写入前自动建档	工艺模型
master.operation.upsert	P2	工序库改路线可选步骤	编码/标准工时；写入前自动建档	工艺模型
master.lineProduct.upsert	P2	产线-产品绑定改选线依据（排产前必需）	产线×产品/优先级；写入前自动建档	工艺模型
master.changeover.upsert	P2	换型矩阵写入（产品族切换分钟）	从族/到族/分钟；写入前自动建档	MD-06
master.workstation.upsert	P2	工位新增/编辑/停用会改变后续排产资源池	工位编码/产线/状态；出卡与执行前均自动建档	R71.3
master.equipment.upsert	P2	设备新增/编辑/停用会改变后续有限产能资源池	设备编码/工位/状态；出卡与执行前均自动建档	R71.3
master.bom.release	P2	发布不可变 BOM 版本快照	产品/版本/明细行；执行前自动建档	R71.3
master.bom.rollback	P2	恢复已发布 BOM 快照并切换默认版本	产品/目标版本；执行前自动建档	R71.3
master.routing.release	P2	发布不可变工艺路线版本快照	产品/版本/步骤；执行前自动建档	R71.3
master.routing.rollback	P2	恢复已发布工艺快照并切换默认版本	产品/目标版本；执行前自动建档	R71.3
master.calendar.holiday.upsert	P2	节假日新增/编辑会改变后续工作日历与新排产输入	日期/名称；出卡与执行前均自动建档，统一由 /api/actions/confirm 执行	R71.3
master.calendar.template.create	P2	新建周班次模板会改变后续日历生成依据	产线/班次/工作日/节假日；执行前自动建档	R71.3
master.calendar.week.copy	P2	批量生成班次日历会改变后续可用产能	模板/日期范围/产线；执行前自动建档	R71.3
changeover.query	P0	换型矩阵只读	无需确认	MD-06
campaign.preview	P0	战役/批次合并预览	无需确认	SC-08
master.clear	P2	一键清理主数据板块（按范围清空）	scope=resource/process/calendar/flex/all；写入前自动建档	清理
import.commit	P2	Excel/CSV 校验通过行写入主干	文件名/种类/行数；写入前自动建档	MD-04
order.decompose	P1	订单分解只写 DRAFT 建议表（采购/委外），不碰主数据	无需确认（ALGO_RUN 审计留痕）	M4 首切片
mrp.release	P2	MRP 草稿采购/委外转正式	下达范围；写入前自动建档	M4
plan.trace	P0	计划追溯只读单据链	无需确认	追溯
flex.schedule	P1	柔性排产（能力池+虚拟产线）只写 flex* 草稿表	无需确认（ALGO_RUN 审计留痕）	M5 首切片
flex.reschedule	P2	分级重排 L2/L3/L4：窗外冻结 + 窗内重排，影响面大	等级/冻结工单/重排订单数；执行前自动建档	DY-01
flex.swap	P1	L1 局部换机：池内备机接手，他单不动	无需确认	DY-01
flex.capacity	P0	瓶颈产能评估（能力池日产能）	无需确认；联动视口产能池	EX-10
flex.conflict.resolve	P1	EX-03 冲突安全修复（重排类另 stage P2）	无需确认（重排走 flex.reschedule 卡）	EX-03
conflict.list	P0	冲突中心只读	无需确认	EX-03
flex.adjust.preview	P0	EX-04 甘特调程预览	无需确认	EX-04
flex.adjust.commit	P2	EX-04 柔性甘特调程提交新草稿	工单/平移量/联动条数；执行前自动建档	EX-04
schedule.adjust.preview	P0	EX-04 固定甘特调程预览	无需确认	EX-04
schedule.adjust.commit	P2	EX-04 固定甘特调程提交新草稿	工单/平移量；执行前自动建档	EX-04
sap.status	P0	MD-05 SAP 连接状态（Mock）	无需确认	MD-05
sap.sync.inbound	P2	MD-05 SAP→APS 拉单/库存	新单数/库存项；执行前自动建档	MD-05
sap.sync.outbound	P2	MD-05 APS→SAP 开完工回写	条数/幂等；执行前自动建档	MD-05
mes.status	P0	EX-05 MES 连接状态（Mock）	无需确认	EX-05
mes.dispatch	P3	EX-05 下发车间（外部副作用）	版本/新下发条数；同一令牌二次确认；最终批准签发绑定审批参数摘要的一次性作用域执行凭据；执行前自动建档；最终审计绑定确认令牌、精确版本、真实前置快照和排产证据	EX-05
mes.report	P1	EX-09 报工回流写工单进度；FB-03 起 S6 断连补录可经确认卡显式声明 offlineBooking（双端核验断连事实后本地落账 + syncStatus=PENDING_SYNC，在线路径语义不变）	无需确认	EX-09
readiness.query	P0	数据齐备度检查（产品→路线→工时→资源→日历）只读	无需确认	M-B
flex.time.update	P2	更新产品×工序单件工时并标记来源，改后续排产输入	产品/工序/分钟/来源；写入前自动建档	M-B
rag.query	P0	外部 Skill 消费知识库（只读，manifest ragScopes 鉴权）	无需确认	M-E
routing.template.apply	P2	行业模板实例化为产品工艺路线（工时标「模板」）	模板/产品/步数/知识出处；写入前自动建档	M-E
schedule.wizard	P0	引导式排产向导（对话态本身只读，写入走各自 P2）	无需确认	M-F
agent.fallback.propose	P1	意图未识别（assistant.reply/unknown）时拉起 Pi 只读分析兜底：产分析草稿（沙盒语义），不写主干世界；FF-01 fallback 开关默认关	无需确认	FB-01
agent.fallback.execute	P2	智能兜底：执行已批准计划——计划锁（计划+指纹 sha256 冻结进卡、逐步比对、偏离即熔断）+ checkpoint 成对快照 + 失败自动回滚 + diff 对账报告；Pi 只编排既有已登记写意图，无新物理写通道	计划/指纹/runId；批准后建执行前后成对快照；偏离/失败自动回滚到前快照并显式声明	FB-02
agent.fallback.execute.highrisk	P3	智能兜底高危执行：登记在册、默认拒绝，FB-02 轮不开放白名单（任何含 P3 步骤的计划整计划拒绝出卡）	暂不开放	FB-02
agent.fallback.policy.update	P2	白名单治理：经确认卡原子替换 fallback-highrisk.json（编排器再生成完整文档 + 复验 + 旧文件 .bak 备份 + 漂移比对）	冻结文档 sha256/前后文件 sha256/ diff 声明；审批窗口内文件被改即拒绝	FB-03
agent.fallback.ops.config.apply	P3	S7 受控配置变更：双审批 + 一次性 executionGrant + 原子替换 features.json（contentSha256/beforeSha256 编排器机器再生成，不信 Pi 申报）	grantId/双人 approvals/前后文件 sha256；grant 单次消费、过期/错配即拒绝	FB-03
agent.token.issue	P2	Pi Agent 长期只读凭证签发：登记租户/设备绑定与有效期，先人工确认再写入 agent-tokens.json	租户/设备/有效期摘要；P2 阶段才接通	Pi Agent
agent.token.revoke	P2	Pi Agent 长期只读凭证吊销：先人工确认再把登记记录置为 revoked	tokenId/绑定主体摘要；P2 阶段才接通	Pi Agent
viewport.*	P0	纯视图状态	无需确认	M1
query.*	P0	只读查询	无需确认	M1

认证握手端点（安全边界，不入 _POWER_MAP）

端点	用途	加入
POST /api/auth/login·refresh·logout · GET /api/auth/me	Web 用户会话	Auth/Tenancy
POST /api/auth/license/activate	桌面客户端授权码激活、设备绑定与期限校验	Desktop License

只读端点备案（P0，不入 _POWER_MAP）

端点	用途	加入
GET /api/world/summary·gantt·load·due	世界视图投影	M1
GET /api/constraints · GET /api/constraints/library	约束剖面 / 约束规则库（默认通用规则 + 计划员扩充规则，只读）	SC-04
GET /api/timeline	时间线	M2
GET /api/checkpoints/{pairId}	检查点世界侧投影（P0，summary+固定/柔性工单+产能池；缺失 404）	矩阵 54
GET /api/checkpoints?pairIds=&branchIds=&sessionId=	分支锚定批量投影（P0，缺失项上报）	矩阵 54
POST /api/wms/events	WMS 缺料事件上报（P1：幂等消费→库存版本→影响评估→Explore 方案卡 P2 门禁）	矩阵 74/77
GET /api/wms/replay	WMS 事件重放（P0）	矩阵 74
GET /api/wms/inventory	库存台账/版本投影（P0 只读）	矩阵 74
GET /api/saga · GET /api/saga/{id}	Saga 列表/详情（中间态可见，P0）	矩阵 78/119
GET /api/params/experiments	参数实验列表/状态（P0）	矩阵 87
POST /api/params/optimize · POST /api/params/observations	参数优化触发 / 线上观测回调（P1）	矩阵 87
POST /api/params/experiments/{id}/promote · .../rollback	实验转正（P2 确认卡）/ 手动回滚（P1）	矩阵 87
POST /api/multimodal/extract	多模态候选抽取（P0 只读：结构化候选+置信度）	矩阵 101
POST /api/multimodal/ingest	多模态摄取（低置信出 P2 确认卡，确认前不写世界）	矩阵 101
GET /api/features	功能开关（P0 只读）：文件化配置功能上线/隐藏；可用性开关非权限边界，缺失/损坏回退默认值并显式 error；响应携带 defaultOff 集合显式标注默认关功能（当前含 fallback：会拉起外部 LLM 子进程并产生 token 成本，默认关与其余键 fail-open 相反，详见 fallback.md）	FF-01
GET /api/gov/archive/verify	WORM 归档完整性验证（P0 只读：sha256/merkle 篡改检出）	矩阵 104/116/112
POST /api/gov/archive/run	触发归档密封（P1：archive_old + worm manifest）	矩阵 104/116/112
POST /api/saga/{id}/retry	Saga 重试（P1，先按快照回滚步副作用）	矩阵 78/119
POST /api/saga/{id}/compensate	手动触发补偿链（P1）	矩阵 78/119
POST /api/saga/{id}/takeover	人工接管（P1，补偿失败安全降级）	矩阵 78/119
POST /api/automation/tick · GET /api/automation/status	自动化定时驱动（手动 tick + lifespan 后台自动；P1 驱动/ P0 状态）	矩阵 76
POST /api/rebuild/{module_id}	可重生流水线触发（候选构建+隔离黄金+安全扫描+灰度，P1）	矩阵 91
GET /api/rebuild · `POST /api/rebuild/{module_id}/promote	rollback`	流水线状态/转正/回滚（P0/P1）
GET /api/gov/pending	待审批	M2
GET /api/gov/approval-history	按租户/项目过滤的审批历史、停留时长和超时结果	M2
GET /api/gov/audit	审计链	M2
POST /api/gov/audit/events	桌面端/登录态审计事件上报（矩阵 103 收口：desktop 模式由 SidecarIdentityApp nonce 门禁即身份（updater 带 nonce 即可）；web 模式要求登录身份；可选 idempotencyKey 幂等去重；失败 4xx 明确；事件复用 write_audit 入链）	矩阵 103
GET /api/gov/modules	模块注册表	M2
GET /api/gov/policy	权力矩阵投影	M2.5
GET /api/gov/tests	黄金测试看板（run=true 须线程池，防阻塞）	M2.5
GET /api/plans/{planId} · /{planId}/versions	Plan 最新版与不可变版本历史（P0）	Plan §3.1
POST /api/plans · /{planId}/regenerate	追加 Plan 草稿/重生版本（P1，不写世界状态）	Plan §3.1
GET /api/settings/llm	LLM 状态	M2.5
GET /api/knowledge/assets · /{id}	知识资产	M3
POST /api/knowledge/import · /upload	知识导入（P2 暂存确认卡）	RAG
GET /api/skills · /health	外部算法 Skill 清单/健康	Skill
POST /api/skills/register	登记 Skill（P2 暂存）	Skill
GET /api/reports/{type}	报告导出 daily / version-diff	M3
GET /api/orders	订单管理页投影（订单 + 成品选项）	M4 首切片
GET /api/master	主数据管理页投影（资源树/物料BOM/日历维保）	M4 首切片
GET /api/mrp	MRP 建议单投影（采购/委外 DRAFT）	M4 首切片
POST /api/mrp/decompose	订单分解（P1 直通，经 harness.guard）	M4 首切片
GET /api/flex/world	柔性排产页投影（能力池/设备/模具/订单 + 虚拟产线）	M5 首切片
POST /api/flex/schedule	柔性排产（P1 直通，经 harness.guard）	M5 首切片
POST /api/flex/reschedule	分级重排暂存确认卡（P2，执行走 confirm）	DY-01
POST /api/flex/swap	L1 局部换机（P1）	DY-01
GET /api/flex/conflicts	冲突中心（P0）	EX-03
POST /api/flex/conflicts/resolve	冲突修复（P1 / 或 stage P2）	EX-03
POST /api/flex/adjust/preview	甘特调程预览（P0）	EX-04
POST /api/flex/adjust/stage	甘特调程确认卡（P2）	EX-04
POST /api/schedule/adjust/preview	固定轨调程预览（P0）	EX-04
POST /api/schedule/adjust/stage	固定轨调程确认卡（P2）	EX-04
GET /api/sap/status	SAP 连接状态（Mock，P0）	MD-05
GET /api/sap/inbound/preview · outbound/preview	SAP 入/出站预览（P0）	MD-05
POST /api/sap/inbound/stage · outbound/stage	SAP 同步确认卡（P2）	MD-05
GET /api/mes/status · execution · dispatch/preview	MES 状态/进度/下发预览（P0）	EX-05/09
POST /api/mes/dispatch/stage	MES 下发确认卡（P3，首次批准只留审计，二次批准才执行）	EX-05
POST /api/mes/report	报工回流（P1）	EX-09
GET /api/analytics/kpi	KPI 仪表盘聚合（P0）	EX-08
GET /api/analytics/utilization	资源利用率：设备热力+班组（P0）	EX-06
GET /api/analytics/compare	方案对比表（P0 沙盒）	EX-07
POST /api/flex/simulate-due	交期承诺模拟（P0 只读沙盒，PL-08 雏形）	M5 首切片
GET /api/flex/capacity	瓶颈产能法分析（P0，各池日产能+限制性瓶颈，PL-07 / EX-10）	M5 首切片
POST /api/import/preview	Excel/CSV 上传校验（P1，不写主干）	MD-04
POST /api/rush/evaluate	插单影响快评（P1 沙盒，经 harness.guard）	OR-04
POST /api/orders/submit	订单提交审核（P1 直通）	OR-03
GET /api/forecast	预测/长周期订单投影（P0）	OR-05
GET /api/plan/buckets	时间分桶计划投影（P0，含 capacityMode）	PL-01/02
GET /api/plan/rccp	有限/无限粗能力对照（P0）	PL-02
GET /api/plan/feasibility	交期可行性（P0，前置于排产）	PL-03
GET /api/plan/inventory	库存投影（P0）	PL-04
GET /api/plan/leveling	产能平衡/削峰建议（P0）	PL-05
GET /api/plan/supply	产供方向决策（P0）	PL-06
GET /api/workspace	项目/会话/消息工作区快照（P0）	AG-08
PUT /api/workspace	整包同步工作区（P1，迁移/防抖）	AG-08
GET/PUT/POST /api/sessions/{id}/messages	会话消息读写（P0/P1）	AG-08
GET /api/readiness · /api/times	齐备度报告 / 工时矩阵（P0）	M-B
POST /api/times/update	工时更新确认卡（P2 暂存）	M-B
GET /api/projects · /api/packs	项目清单 / 数据包清单（P0）	M-A
GET /api/templates · /recommend	工艺模板库 / 按产品推荐（P0）	M-E
POST /api/templates/apply	模板生成路线确认卡（P2 暂存）	M-E
POST /api/rag/query	Skill 消费 RAG（P0，apiKey + ragScopes 鉴权）	M-E
GET /api/knowledge/index/status · POST …/rebuild	向量索引状态 / 重建（P0 / P1）	M-E
POST /api/skills/{id}/enable	启停 skill 确认卡（P2 暂存）	M-D
GET /api/skills/{id}/audit · /history	skill 审计过滤 / 健康历史（P0）	M-D
POST /api/skills/{id}/test	跑该 skill 黄金测试子集（P1，子进程）	M-D
GET /api/skills/contracts	SchedulingProblem/Solution 契约（P0）	M-D
GET /api/mcp/plugins*	MCP 插件清单/健康/权限/审计（P0）	M-D
POST /api/mcp/plugins/register · /enable · /permissions	MCP 注册/启停/权限（P2 审计）	M-D
GET /api/jobs · POST /api/jobs	异步任务列表/提交（敏感性、Sobol、蒙特卡洛、CP 整约束与 RHS 参数重算）	M3
GET /api/jobs/{id} · /cancel	异步任务轮询/取消	M3

确认暂存端点备案（不直接执行写入）

端点	用途	权力路径	加入
POST /api/orders/stage	订单新增/编辑/取消/完成/批准/驳回生成确认卡	order.* P2 → /api/actions/confirm 执行	M4 首切片
POST /api/rush/stage	采用紧急插单生成确认卡	rush.apply P2 → /api/actions/confirm 执行	OR-04
POST /api/forecast/stage	预测新建/删除/转正确认卡	forecast.* P2 → /api/actions/confirm 执行	OR-05
POST /api/projects · DELETE /api/projects/{id} · POST /api/sessions	项目/会话元数据（P1 直通）	project.* / session.create	AG-08
POST /api/projects/{id}/files/upload	浏览器上传本地工程数据文件到项目目录（P1 直通）	project.*	AG-08
POST /api/master/stage	产线/物料/维保编辑生成确认卡	master.* P2 → /api/actions/confirm 执行	M4 首切片
POST /api/import/commit	导入批次生成确认卡	import.commit P2 → /api/actions/confirm 执行	MD-04
POST /api/constraints/rules/stage	计划员扩充约束规则（新增/启停/删除）生成确认卡	constraint.rule.save P2 → /api/actions/confirm 执行	SC-04

审批角色策略

APS_APPROVAL_ROLE_POLICIES 可按精确 action 和 P2/P3 等级分别配置发起、批准、历史查看角色。每种能力独立解析，固定优先级为：精确 action > power 等级 > 既有全局环境变量。

{
  "actions": {
    "mes.dispatch": {
      "initiate": ["dispatcher"],
      "approve": ["mes-approver"],
      "history": ["mes-auditor"]
    }
  },
  "powers": {
    "P2": {
      "approve": ["planner", "approver"]
    },
    "P3": {
      "approve": ["senior-approver"]
    }
  }
}

• action 必须是 _POWER_MAP 中精确登记且需要审批的 P2/P3 动作；不接受 *。
• 规则只允许 initiate、approve、history，值必须为角色字符串数组；空数组表示除合法 system 身份外不授权任何角色。
• 某能力未在 action 规则声明时回退同等级规则，再未声明时分别回退 APS_APPROVAL_INITIATOR_ROLES、APS_APPROVAL_ROLES、APS_APPROVAL_VIEW_ROLES，保持既有部署兼容。
• 未知字段/action/等级、重复 JSON 键、非数组或非法角色会使整份配置失效。失效期间包括 system 在内均不得发起、批准或查看审批；GET /api/gov/policy 保留原字段，并通过各条目的 rolePolicy.valid=false/error 暴露配置错误。
• 角色策略只决定谁可操作，不改变 P2 一次批准和 P3 两个不同用户批准的次数与职责分离约束。

防线

1. P2 只能：stage_confirmation → 持久审批队列 → 确认卡/门禁管理台 → /api/actions/confirm → take_confirmation，批准一次后令牌失效
2. P3 使用同一令牌由两个不同用户连续批准：首次只写 GATE 审计并保留令牌，同一用户再次批准被职责分离门禁拒绝；第二名用户批准后签发绑定规范化审批参数摘要的一次性内部执行凭据，才允许外部副作用；审批记录冻结发起人的有效 worldKey，第二审批人的当前个人空间不能改变执行目标；mes.dispatch 必须以原始 track/versionId/evidenceRefs 消费该凭据，并校验真实存在的 beforeSnapshot
3. 未登记动作 → P3 拒绝；guard() 禁止 P2/P3 直通
4. P2/P3 写入前自动 Checkpoint（publish / reset / rollback / 外部下发）
5. GATE / WORLD_WRITE 写审计哈希链，可 verify_audit_chain
6. 审批队列、审批历史和一次性执行凭据经统一 backend 原子持久化；文件后端使用原子替换，数据库后端使用请求 revision CAS 和短事务。最终批准、P3 grant 签发和审批事件同事务提交；数据库只保存 grant token 的 SHA-256。审批和凭据 TTL 分别由 APS_APPROVAL_TTL_SECONDS、APS_EXECUTION_GRANT_TTL_SECONDS 控制，重启后继续生效且过期结果进入审批历史
7. 发起/批准/历史权限按 APS_APPROVAL_ROLE_POLICIES 的精确 action > power > 全局环境变量确定；配置非法时全部失败关闭。全部审计 actor 只从认证身份派生，不信任客户端 sessionId；损坏或字段非法的审批文件会被隔离为 .corrupt-* 并告警，拒绝继续使用其中令牌

默认 APS_APPROVAL_BACKEND=file：使用进程内可重入锁、同机跨进程文件锁和原子文件替换，可防止多个本机 Gateway worker 重复签发。显式设置 APS_APPROVAL_BACKEND=database 后复用 APS_DATABASE_URL 的 MySQL；批准/驳回竞态、最终 grant 签发和 grant 消费均使用 CAS 保证跨连接只有一个赢家。database 模式缺少 URL、配置 APS_APPROVAL_PATH、连接失败或使用非 MySQL 方言时失败关闭，不回退 file；APS_APPROVAL_DATABASE_ALLOW_SQLITE=1 只允许测试。

共享切换必须先执行 Alembic 20260731_03 并整体切换所有节点，禁止 file/database 混跑。当前仅完成 SQLite 本地合同/CAS 测试，尚未宣称 MySQL 实机或多主机故障注入验收通过。

证据链 v1（§3.4）

• 出卡冻结：stage_confirmation 记录 evidenceRefs（显式或按 versionId 派生 schedule-version:<id>）、beforeSnapshot（写前 checkpoint pairId）与 beforeFingerprint（输入快照指纹，世界已加载时）。
• 确认信封完整性：出卡同时记录 paramsHash 与 envelopeHash；后者绑定 action/power/tenant/project/world/session/params/evidence/snapshot/requester/requiredApprovals。file/database 后端均在 decide 的共同 allowed 回调内、消费或签发 grant 前重算；缺失、旧格式或篡改记录失败关闭。
• folder.schedule 专用冻结：stage 只读沙盒分析；source manifest、world fingerprint、frozen payload digest、beforeSnapshot 四类证据全部入信封。SQL/Excel/CSV 解析与 manifest 使用同一次 immutable bytes；confirm 不重读活动目录。
• folder.schedule 原子执行：冻结数据只写候选世界，import/schedule/save 全部成功后一次提交；任一点失败写 DENIED 并丢弃候选，L2 Plan 只在提交成功后 APPROVED。
• Automation G4 授权：升权 P3 信封必须携带 automation-authorization.v1，绑定完整 Rule、harnessAction/power 与 BusinessActionBinding；grant 保存批准摘要，每次执行前对当前 rule/binding 重算，漂移即撤销。
• G4 写动作禁止 handler 直通，只允许 Binding + business_bridge；真实 /api/actions/confirm/batch 在第二名审批人完成后消费一次性 executionGrant 并铸造 AutomationGate grant。
• 执行强校验（fail closed）：execute_confirmed 在最终批准后、写世界前调用 verify_pending_evidence：
  • 版本证据绑定：params 含 versionId 时必须携带 schedule-version:<versionId> 证据，否则拒绝；
  • 前置快照存在：beforeSnapshot 指向的 checkpoint 必须存在，否则拒绝；
  • 版本一致性：世界带版本表时 versionId 必须仍可解析，否则拒绝（对象域校验，避免全局指纹假阳性）。
• 审计统一：全部 P2/P3 写审计事件携带 beforeSnapshot 与 evidenceRefs；拒绝路径写 DENIED 审计且不改变世界。
• 输入快照指纹：world_fingerprint 对业务主数据投影做 SHA256（排除 append-only 日志/审计/同步流水），用于出卡与执行间的漂移检测证据。
• mes.dispatch 原有强绑定（确认令牌 + 版本证据 + 写前快照）保持不变，作为统一协议的参考实现。
• 审批意见：take_confirmation(confirm_id, approve, note=...) 携带可选意见，随批准/驳回记录进 approvals 与审批历史事件（文件与共享 database 后端一致）；网关 ConfirmRequest.note 透传，管理台审批历史展示。
• 审批委托：stage_confirmation(..., delegate_user_id=...) 出卡时可指定被委托人；P2 单重审批作用域允许 owner 或被委托人操作，P3 双人职责分离不变（委托不视为身份合并）。
• 审批转派：transfer_confirmation(confirm_id, to_user_id) 把待确认项转派给指定用户（P2；转派后 owner=目标用户、原 owner/delegate 不可再审批；P3 拒绝转派保双人分离）；历史事件 TRANSFERRED 记录 from/to；网关 POST /api/actions/transfer。
• 统一 EvidenceItem：server/agent_core/evidence.py 提供结构化证据记录（kind/ref/version/runId/engine/seed/inputsHash/knowledgeVersion/confirmId/note）与 trace_chain()（规范化 JSON + 链哈希，可复算可追溯）；证据引用语法 <kind>:<id> 与 schedule-version:<id> 协议兼容。
• schedule.run 接入：server/aps_domain/workflow.py 的 _run_schedule 求解后经 _build_run_trace 构造 EvidenceItem 链（schedule-version/run/algorithm），ALGO_RUN schedule.run 审计 rationale 携带 traceChainHash/traceCount/traceSummary（可复算可追溯；失败返回空链摘要，不影响求解）。链哈希只含确定性信息（版本/run/引擎/策略/求解状态/gap/输入包指纹），墙钟 solveTimeSec 保留在审计顶层字段不进入链哈希，RULE/CP/HYBRID/GA 四引擎同输入同种子可复算；审计 evidence 合并 schedule-version:<id> 引用（_run_audit_evidence）。
• EXTERNAL 引擎接入：_run_flex 的 flex.schedule.external 分支经 _build_external_trace 构造同构链（schedule-version/run/EXTERNAL/algorithm），审计携带 traceChainHash；algo_skill_stub.runId 改为输入派生确定性哈希保证可复算；前端 GovConsole 审计链新增「可追溯链」列展示链哈希与摘要。
• 审计独立介质锚定：server/agent_core/audit_ledger.py 提供 audit_root(events)（对链哈希做双哈希聚合根）与 AnchorLedger（按租户/项目隔离的 append-only JSONL 账本）；/api/gov/audit 返回 anchor 状态，POST /api/gov/audit/anchor 显式锚定；改事件/删账本行可被检测（与链式校验互补）。
• 审计事件镜像：server/agent_core/audit_mirror.py 提供 AuditMirror（按租户/项目隔离 append-only JSONL）；APS_AUDIT_MIRROR=1 时 write_audit 同步镜像每条事件（尽力而为，失败只记日志），/api/gov/audit 有镜像时以镜像为事件源（业务进程改 world 无法抹掉独立介质证据）。
• 审计合规导出：server/agent_core/audit_export.py 提供 sanitize_event（token/password/secret/key/authorization/credential 键值递归掩码）与 export_events（json/csv）；/api/gov/audit/export 导出当前作用域事件（脱敏）+ 链/锚定摘要。
• 审计完整性告警：server/agent_core/audit_alerts.py 聚合链断裂（critical）、锚定不匹配/账本损坏、未锚定、镜像未启用等告警；/api/gov/audit 返回 alerts，管理台 AuditView 按 severity 展示。

变更记录

日期	变更
2026-09-04	FB-03-BUG-1 修复：mes.apply_report 新增 keyword-only offline_booking（默认 False，在线路径逐字节不变）；S6 断连补录显式离线落账（声明 + 断连事实双端核验，syncStatus=PENDING_SYNC，滥用即拒）
2026-09-04	FB-03：agent.fallback.policy.update 登记 P2（白名单治理原子写）；agent.fallback.ops.config.apply 登记 P3（S7 受控配置变更，双审批 + executionGrant）；refresh_confirmation_world_fingerprint 推进指纹时同步重算信封哈希（S6 多卡场景实测缺陷修复）
2026-09-03	FB-02：agent.fallback.execute 登记 P2（兜底写路径：计划锁+成对快照+自动回滚+diff 对账）；agent.fallback.execute.highrisk 登记 P3（默认拒绝，本轮不开放）
2026-09-02	FB-01：agent.fallback.propose 登记 P1（智能兜底只读车道，FF-01 fallback 开关默认关）；/api/features 响应新增 defaultOff 字段
2026-08-17	Round 72：P2/P3 params/envelope hash 决策前重算；folder.schedule immutable source bytes、四证据冻结、candidate-world 原子提交与 TOCTOU 关闭
2026-08-17	Round 73：Automation G4 完整 Rule/Binding authorization digest；漂移撤 grant；无业务桥 P3 DENIED；真实 API 双人审批铸 grant
2026-08-01	trace_chain 接入 schedule.run：ALGO_RUN 审计携带 traceChainHash/traceCount/traceSummary；schedule.run 首接入矩阵 114 行
2026-08-01	trace_chain 跨引擎可复算：墙钟移出链哈希；evidence 并入 schedule-version 引用；RULE/CP/HYBRID/GA 四引擎可复算（round-16 补充）
2026-08-01	EXTERNAL 引擎接入 trace_chain（flex.schedule.external 审计携带 traceChainHash）+ 前端审计链「可追溯链」列（round-16b）
2026-08-01	对话状态与世界状态成对快照：CheckpointStore 支持 conversationSide，_create_checkpoint 统一建档、_restore_conversation_side 回滚成对恢复（round-17）
2026-08-01	审计完整性告警通知渠道：audit_notify（console/jsonl/webhook + 防抖），/api/gov/audit 联动（round-18）
2026-08-01	审计完整 Merkle 树：audit_merkle（merkle_root/merkle_proof/verify_proof），JSON 导出携带 merkleRoot（round-19）
2026-08-01	审计 append-only 守护：audit_filelock 跨进程锁 + audit_ledger.archive_old 保留窗口归档（round-20）
2026-08-01	偏好学习升级：项目隔离（record/preferred_strategy 带 project_id）、explain 解释、reset 重置、冷启动/不确定度（round-21）
2026-08-01	Explore 与 Runtime 数据边界：explore_boundary（readonly_view + run_explore），scenario.compare 接入统一通道（round-22）
2026-08-01	L0-L3 Plan 重放：plan_runtime.node_at/replay_verify + plan_api 重放端点（round-23）
2026-08-01	统一工具运行时：LLM 提议意图唯一执行入口（登记校验 + TOOL 审计），gateway 聊天接入（round-24）
2026-08-01	分支树：BranchStore（fork/rename/switch/discard/merge + 状态机 + 审计），gateway branches API，快照纳入分支（round-25）
2026-08-01	主数据工艺路线树产品升级：成品→半成品→工序层级树，build_process_tree 补展示字段（round-26）
2026-08-01	分支切换自动恢复锚定检查点：_create_checkpoint 锚定分支、switch 端点成对恢复（round-27）
2026-08-01	偏好解释 UI（设置·个人偏好 + /api/settings/preferences）+ stub runId 可复算修复（round-28）
2026-08-01	主数据工艺树 → 树形表格：sourcing 去重/半成品推导/工序名补齐 + 类型来源标签（round-29）
2026-08-01	L0-L3 Plan 批准/驳回审计：transition_status + approve/reject 端点（round-30）
2026-08-01	Agent 自动编排：P2 出卡建 L0/L1/L2 链、批准/驳回流转、_load regen 校验修复（round-31）
2026-08-01	偏好时间衰减加权模型：来源权重×时间衰减（半衰期14天），偏好漂移（round-32）
2026-08-01	Explore 通道扩展：run_sensitivity/run_monte_carlo 接入 run_explore 统一边界（round-33）
2026-08-01	多智能体并行：session_ref/context_policy（A）、automation G0-G4（B）、分支树UI+时间线微观层（C）——round-34
2026-08-02	多智能体并行·第二批：CP-SAT工序级（D）、algolib+param_opt（E）、MCP总线+async_jobs（F）——round-35
2026-07-31	跨主机审批首切片：显式 MySQL backend、规范化 request/grant/event 表、CAS 终态和一次性消费、token 摘要落库；文件后端保持默认
2026-07-31	审批角色策略：支持 exact action / P2/P3 分级覆盖，按能力确定性回退全局角色；非法配置失败关闭，治理投影追加配置来源与校验状态
2026-07-31	审批治理持久化：队列/历史/执行凭据跨重启恢复，支持 TTL、P3 双人职责分离、停留时长和治理历史 API/UI
2026-07-31	二次审计整改：执行凭据绑定审批参数摘要；MES 展示上限不再截断执行，整版完成标记取决于全部工单幂等链接
2026-07-31	Plan §3.1：备案 /api/plans P0/P1 端点；创建/重生只追加治理版本，不穿透世界状态
2026-07-31	审计整改：P3 最终批准签发一次性作用域执行凭据；MES 精确锁定审批版本并校验真实快照/证据；跨租户不泄漏令牌状态
2026-07-31	P3 二次确认：首次批准仅审计并保留令牌，第二次批准才执行 mes.dispatch 外部副作用；最终审计绑定确认令牌、前置快照和排产证据
2026-07-16	初版 8 条 + M2.5 只读端点
2026-07-23	RAG：knowledge.import P2；Skill：skill.*；端点 /api/knowledge/import* /api/skills*
2026-07-16	迁入 architecture/harness.md；注明 tests 线程池
2026-07-16	OR-01：新增 order.upsert/cancel/complete P2 与订单暂存端点
2026-07-16	MD-01/02/03：新增 master.line/material/maintenance.upsert P2 与 /api/master、/api/master/stage
2026-07-16	MRP：新增 master.bom/routing.upsert P2、order.decompose P1 与 /api/mrp*
2026-07-22	DY-01：flex.reschedule 升 P2；新增 flex.swap P1 与 /api/flex/swap
2026-07-22	EX-03：conflict.list P0、flex.conflict.resolve P1 与冲突 API
2026-07-22	EX-04：flex.adjust.preview P0 / flex.adjust.commit P2
2026-07-22	EX-04：schedule.adjust.preview/commit 固定轨对称
2026-07-22	MD-05：sap.status P0 / `sap.sync.inbound
2026-07-22	EX-05/09：mes.dispatch P3 / mes.report P1（Mock MES）
2026-07-22	EX-07/08：`/api/analytics/compare
2026-07-22	EX-06：/api/analytics/utilization 设备热力+班组并发；SC-11 文档对齐
2026-07-22	AG-07：guidance.next P0 + /api/guidance 主动引导
2026-07-22	OR-02：params.query P0 / params.update P2 + /api/params*
2026-07-22	SC-04：constraint.profile.* + /api/constraints*；硬约束拦发布
2026-07-23	OR-05：forecast.query P0 / `forecast.upsert
2026-07-23	PL-01：plan.buckets P0 + /api/plan/buckets 分桶视口
2026-07-23	PL-02：capacityMode + plan.rccp P0 + /api/plan/rccp
2026-07-23	PL-03：plan.feasibility P0 + /api/plan/feasibility
2026-07-23	PL-04：plan.inventory P0 + /api/plan/inventory
2026-07-23	PL-05：plan.leveling P0 + /api/plan/leveling
2026-07-23	PL-06：plan.supply P0 + /api/plan/supply
2026-07-23	MD-06：changeover.query / master.changeover.upsert + RuleEngine C10
2026-07-23	SC-07：策略 CHANGEOVER_MIN + 方案对比换型卡
2026-07-23	SC-08：策略 CAMPAIGN + campaign.preview
2026-07-23	SC-06：scenario.sensitivity P1 + /api/scenario/sensitivity Tornado
2026-07-23	SC-03：get_engine(CP) → CpSatEngine（OR-Tools）；GA/HYBRID 仍 RULE 代跑
2026-07-23	SC-03：get_engine(HYBRID) → HybridEngine（RULE hint → CP）
2026-07-23	IND-02：sop.compile P0 / sop.apply P2 + /api/sop*；C13_sop
2026-07-23	通用平台 M-A/B：readiness.query P0 / flex.time.update P2 + /api/readiness /api/times* /api/projects /api/packs
2026-07-23	通用平台 M-D/E/F：rag.query P0 / routing.template.apply P2 / schedule.wizard P0 + skill 管理台端点与模板/索引端点
2026-09-17	SC-04 扩充：constraint.rule.query P0 / constraint.rule.save P2 + /api/constraints/library、/api/constraints/rules/stage；默认通用规则保持内建目录，计划员扩充规则按类别/范围归档，未接入引擎的规则如实标注

Round 65 P2/P3 排产发布与 MES 分离

• POST /api/schedule/publish/stage 只暂存 schedule.publish P2 确认卡，绑定 track + versionId + schedule-evidence；执行仍唯一经 /api/actions/confirm。
• 柔性发布出卡和执行时都重算 publishReady；证据漂移或版本替换一律拒绝。
• mes.dispatch 保持 P3 双人职责分离；不在 MES 路径中暗中把 DRAFT 改为 PUBLISHED。

Round 65 审计补强：P2/P3 证据闭包

• schedule.publish 与 mes.dispatch 共享的 evidence 包含 problemDigest、solutionDigest、solutionActivityDigest、validationDigest、currentValidationDigest 和当前多资源快照摘要。
• 工单必须绑定 activityId、activityIdentity、closedLoopRequirementId；TEAM/TOOLING 分配与工单 teamCode/moldCode 不一致时失败关闭。
• 发布/下发时重建 FACTORY/WORKSHOP/LINE/WORKSTATION/EQUIPMENT/TEAM/TOOLING 当前约束并重新运行 V2 Validator。
• WMS Saga 在确认执行前后比较版本集合，只接受唯一新版本，并核验 flex.reschedule.approve 审计的 confirmId、versionId 与 WMS event evidence。

Pi Agent 外向接入（方向 A · P1 只读）

• server/auth/agent_tokens.py：长期只读机器凭证登记。APS_AGENT_TOKEN_SECRET 必配，缺失时签发/鉴权均返回 AGENT_TOKEN_NOT_CONFIGURED；APS_AGENT_TOKEN_PATH 缺省为 data 目录 agent-tokens.json。token 为 HMAC(base64url body.signature)，含 tokenId/kind/scope/iat/exp；principal 的 user_id/tenant_uuid 绑定个人/租户世界。
• server/gateway/agent_api.py：GET /api/agent/intents、GET /api/agent/intents/{name}、POST /api/agent/invoke。目录为显式登记的 19 项只读白名单（含 query.kpi；排除会写主干/知识库/报告的 data.analyze/folder.analyze/report.generate），不再自动投影 tool_runtime._READONLY_INTENTS/_POWER_MAP P0；非只读意图 P1/P2 返回 CONFIRM_REQUIRED，P3 返回 POWER_DENIED，未登记返回 INTENT_NOT_REGISTERED，均写 AGENT DENIED 审计且不调用 handle_intent。
• 鉴权：AuthenticationMiddleware 对 /api/agent/ 的 Authorization: Bearer <agent-token> 先行鉴权，失败返回 AuthError JSON；无 Bearer 在认证开启时仍回退 Web/桌面 cookie/license；认证关闭时不再落到匿名/本地管理员，而是返回 AGENT_TOKEN_REQUIRED 401。/api/agent/* 不加入 PUBLIC_API_PATHS。
• 配置与签发：服务端需设置 APS_AGENT_TOKEN_SECRET；签发/列出/吊销可用 .venv\Scripts\python.exe scripts\pi_agent_token.py issue|list|revoke。Pi 端把一次性签发的 token 写入自己的配置文件/环境变量即可。
• 当前范围仅 P1 只读直通；P1/P2 写意图、确认卡三态与 MCP 总线治理不在本段备案内。