# 架构：Category Decision System v0.1

## 目标与边界

本项目是一个离线、可复现的品类经营决策演示：先把 POS、库存、损耗、促销与预算数据转成可复算的证据，再按固定门禁给出 `ACT`、`INVESTIGATE`、`HOLD` 或 `ESCALATE`。核心目标是**决策可靠性**，不是让模型显得更自主。

它不接真实盒马系统、不执行价格或商品动作、不证明任何人的生鲜零售年限、上海区域 P&L 业绩或门店管理经历。所有数据、权限和行动均为合成演示。

## 当前实现

```mermaid
flowchart LR
  D[合成 CSV + case context] --> Q[数据质量与量化工具]
  Q --> O[单一 orchestrator]
  M[显式 PydanticAI 单 Agent] <-->|只读业务工具| Q
  M --> P[结构化候选行动与补证问题\n仅引用实际返回证据]
  P --> O
  O --> G[确定性 decision gates]
  G --> C[固定 Decision Card]
  C --> E[Golden set / 离线评测]
  H[人类批准与执行] -.保留决定权.-> C
```

显式模型路径由 PydanticAI 2.45.0 负责单 Agent 的工具循环、结构化输出和调用上限，现有 orchestrator 负责最终财务口径与行动资格。模型只接收业务工具返回的只读证据，提案引用必须来自已调用结果；提案仍是不可信观点。没有多 Agent 编排、知识图谱、实时竞品抓取、预测模型或外部系统写入。离线规则模式不调用模型；SDK 的 FunctionModel 验证也不是模型业务能力实验。具体依赖、运行方式与边界见 [复用说明](FRAMEWORK_REUSE.md)。

### 模型入口与真实试跑

`category_system/codex_adapter.py` 是可选的、本机 Codex CLI 登录适配器。它由 `scripts/run_experiment.py` 显式启动，默认请求 `gpt-6-astra` 与 `high` reasoning effort；不读取 API key、不购买新额度，却会使用现有 ChatGPT/Codex 订阅额度。适配器以 ephemeral、只读、临时目录会话调用 CLI，并关闭网页搜索、插件、技能发现、主机自动化与其他工具。它不是运行默认值：`python3 -m category_system demo` 仍是纯离线确定性演示。

实验脚本将 B（原始 CSV 直接回答）和 C（工具与固定门禁加同模型假设层）置于相同模型、禁工具条件下，并冻结共同的全品类六项 P&L 标量协议。C 的模型输出只能带 evidence id 的假设，不能计算权威数值或改变 `DECISION`。旧的 `artifacts/protocol_pilot/` 同模型试跑因两组财务范围不一致而保留作协议问题记录，明确排除在任何成绩或优越性结论之外。

`artifacts/live_experiment/` 的原始真实运行曾在保存 13 份记录后被用户中断。中断时缺少记录的 7 份调用是否已经开始、以及未记录的订阅使用量均未知；这些原始记录与中断事实永久保留，不能把 13 份成功记录说成总调用数，也不能叙述为连续完成的 20 次首次调用。

在保持冻结 protocol、源码哈希、输入指纹和“不覆盖、不择优”的前提下，后续恢复段保存了剩余 7 份成功响应。因此当前 ledger 的 B/C 覆盖均为 10/10，且共同记录情境为 10/10；这表示开发 fixtures 上的已保存记录覆盖完成，并不改变原始中断历史、未知总调用数，亦不构成模型优越性、统计显著性或现实经营效果的证明。本次时效与促销识别补丁不会修改这 20 份冻结旧源码的模型回答或其报告中的共同财务核验 B=34/54、C=54/54；它也不是新的模型实测。下一轮 A/B/C/D 比较必须对全部组重新冻结当前公共业务合同、数据和门禁，不能将补丁后的新人工/模型结果混入旧 20 份记录。最初的 CLI 启动失败、恢复准备失败及各不可变 attempt manifest 都继续作为历史证据保留；单个未确认终态的 manifest 不证明相关进程仍在运行、已完成或失败。

官方恢复入口 `scripts/resume_experiment.py` 在 macOS/Linux 上以 `fcntl` 单运行锁保护 `artifacts/live_experiment/attempts/NNN/`，使用冻结 source snapshot 和内置预检，只派发 `failed` / `missing` 配对，绝不重调已成功配对或从多个答案中挑选最佳答案。它会保留每段记录；若没有可恢复配对，则写入 `no_eligible_pairs_noop`，不发出业务调用。需要独立的新实验时，使用 `scripts/run_experiment.py --output <尚不存在的新目录>`；该脚本拒绝已有输出目录。纯离线的 10 情境 demo 与真实试跑无关，仍可跨平台运行。无论哪条路径，结果都只是开发 fixtures 上的探索性证据。

本项目以 Codex CLI `0.153.1` 验证过该适配器。CLI 的 feature flag 与参数可能在后续版本变化；运行前应记录版本，并在不兼容时先检查 CLI 帮助，而不是静默更换模型、放开工具或改变实验条件。

### 输入、工具和输出

- 每行粒度为 `week × store × SKU × channel`，含销售、价格、成本、毛利、库存、损耗、促销、可用性与预算字段。
- 工具计算销售的总销量→SKU 组合→价格桥接，贡献的 SKU 数量→价格→单位成本→已知损耗/促销成本桥接，账实差与缺货率，促销的基线调整 DiD，簇内 leave-one-out 门店比较，商品角色保护、预算偏差和 `pilot_weekly_review`。后者把实际试点池的末周贡献/缺货与前三周事实写入同一证据链，不新增 agent 或决策卡 schema。促销 DiD 只接受固定 4+4 周的完整、无基期污染池，本期处理/促销固定且一致，并拒绝同店 SKU 跨渠道交叉分组；否则返回不可识别。贡献是演示代理口径，未知库存差异单列 exposure；计算结果带方法、范围、局限和 evidence id。
- orchestrator 先检查数据完整性、会计/库存一致性与时效：`data_freshness_days` 及从当前行 `week + 6 天` 到 `as_of` 的最新完整周年龄独立有效且均不超过 7 天；未来、缺失或无效日期直接阻止强结论。随后它保留并列风险，最后将行动限制到已授权的模拟范围。
- 输出卡的顶层字段固定为 `BUSINESS STATE`、`PRIMARY DRIVER`、`EVIDENCE`、`UNKNOWN`、`P&L IMPACT`、`DECISION`、`ACTION`、`OWNER`、`REVIEW`、`REVERSAL CONDITION`、`CONFIDENCE`；可追溯元数据置于 `_meta`。

### 新鲜品的窄范围扩展

`data/fresh_case/` 是与旧周度 POS 分开的合成扩展：它只计算一店一品、三天、已声明批次和到货条件下的 FEFO 流转。系统在来源声明同范围且彼此一致时，分别展示维持、减量订货、折价等条件情境；需求没有概率，折价的需求反应若未给定即为未识别。来源审计只匹配合成声明，`external_authenticity=not_verified`，不验证真实系统、签名、人员或审批。

历史 4+4 周 P&L 仍按原面板口径保留。新鲜品的日度收入、售出成本、到期报损、费用、采购现金和未满足需求只属于三天条件测算，不能替换或合并进历史 P&L。候选订货始终交人工商业复核，系统不下单；复盘也只能核对合成记录的数量/成本守恒和明确记录的未满足订单。

该扩展已用 F01–F04 展示门禁：宽需求范围时不产生稳健候选；窄范围下的减量订货只能升级为 `ESCALATE` 的人工商业复核；合成复盘记录 12/182 个未满足单位时重开需求情境；批次数量冲突时暂停精确方案。它不是完整冷链、预测、真实执行或 ROI 证明。

## 补证后的本地复核

`followup.py` 记录同一案例的补证问题、负责人、材料、采纳/退回与重开状态。`reviewdesk.py` 通过仅本机可访问的页面和原子保存文件提供操作入口，继续调用同一个 `run_case`；它不新增 Agent、业务执行器或模型供应商调用。当前入口只开放人工配置的 F01 合成演练，问题与可变字段的映射由应用明确提供，未选择的字段不得随材料改变。每次操作检查版本，采纳才变更有效证据，并保存完整前后卡和输入指纹；旧模型观点留在初始快照，更新后的卡由程序重新计算。

完整工作流见 [补证说明](FOLLOWUP.md)。本地复核者是自声明身份；来源真实性未验证，采纳只允许材料进入分析，不授予订货、调价或真实审批权。字段关联校验不能替代人工判断材料是否回答了业务问题。当前没有真人使用效果证据。

## 为什么先做单一编排器

行业资料提出“专用且连接的 agents”可覆盖更多 merchandising 任务；这描述的是未来运营模型，不是本项目已采纳的复杂度。v0.1 的问题范围小、证据结构明确，先用单一 orchestrator 使门禁、审计和 Golden set 可验证。只有离线评测证明路由或 specialist 能在同一盲测、同一权限下带来可重复且有意义的增益，才考虑拆分；拆分前不得以“多 Agent”替代证据或责任归属。

## 运行与数据流限制

输入应来自本项目生成器，或满足相同 schema 的受控文件。工具验证周窗口、行级勾稽、主键唯一性和库存滚动结转。`case context` 中的实验可信度、数据新鲜度和模拟权限均是输入声明，不能由模型臆造；v0.1 也不独立验证这些声明。比较、计算与证据只覆盖当前 case 的指定基准期和当前期；跨期因果、客群替代、竞争对手价格和供应原因若没有专门数据，必须进入 `UNKNOWN`。

缺货门禁同时使用全局和目标 SKU 的 `stockout_hours / open_hours` 变化。ACT 进一步检查试点门店×目标 SKU×渠道中最差池的缺货率，并限定到实际实验门店与商品。对于试点中的实际池，周度复核还会在末周贡献由前三周正值转负、或末周缺货率超过 5% 时撤回行动资格并限为成本/补货核查；这不是根因判断或永久停试点命令。真实部署仍需批次与货架状态、供应血缘、访问控制、审批日志、财务口径治理、门店/采购确认、真实实验设计与持续监控；这些均为**未实现的未来工作**。