# 成熟组件复用与本次改动

本次把一次性“整包事实 → 模型解释”扩展为真正的单 Agent 工具循环：模型先选业务证据，SDK 执行只读工具，模型看结果后继续查询或提交结构化提案。最终卡片仍由现有编排器重算和审核。没有另造多 Agent 系统，也没有改变 11 字段决策卡的公共协议。

## 实际复用的代码

| 组件 | 固定版本 / 许可 | 实际使用 | 不由它保证的部分 |
|---|---|---|---|
| [PydanticAI Slim](https://github.com/pydantic/pydantic-ai/tree/v2.45.0) | 2.45.0 / MIT | Agent 原生工具循环、函数 schema、结构化 output_type、UsageLimits、FunctionModel 离线替身 | 业务事实、根因、授权真实性、经营收益 |
| [Pydantic Evals](https://pydantic.dev/docs/ai/evals/evals/) | 2.45.0 / MIT | Dataset、Case、代码 Evaluator 和执行结果汇总；复用现有 C/F 案例 | 测试样本独立性、真人判断、模型优越性 |
| Pydantic | 本机验证 2.13.5 / MIT | 提案字段类型、长度、枚举和额外字段约束 | 有效 JSON 内的业务观点是否正确 |

未复制第三方实现代码。完整上游许可在 [PydanticAI LICENSE](https://github.com/pydantic/pydantic-ai/blob/v2.45.0/LICENSE) 与 [Pydantic LICENSE](https://github.com/pydantic/pydantic/blob/v2.13.5/LICENSE)。安装包会携带其各自许可。`requirements-agent.txt` 固定直接依赖，`requirements-agent-tested.txt` 记录本机 Python 3.12.14 的完整解析结果；后者不是所有平台均已验证的承诺。

[LangGraph](https://docs.langchain.com/oss/python/langgraph/overview) 的持久化和长流程图适合另一类需求；当前没有跨天恢复、外部事务或多角色协作状态，不为用框架而引入这些能力。SDK 依赖内部的图组件不表示本产品已拆成多个 agents。

## 运行

原有 `python3 -m category_system demo` 继续支持 Python 3.9+ 标准库。SDK 路径要求 Python 3.10+；本次实际验证使用 3.12.14。在解压后的项目目录执行：

```bash
python3.12 -m venv .venv
.venv/bin/python -m pip install -r requirements-agent.txt
# 纯离线：脚本模型调用真实 SDK 与业务工具，不访问模型服务
.venv/bin/python -B scripts/evaluate_sdk.py
.venv/bin/python -B -m unittest discover -s tests -v
```

Windows 使用 `.venv\Scripts\python.exe` 替换 `.venv/bin/python`。离线报告和可读卡片位于 `artifacts/sdk_validation/`，其模型回答由脚本给定，不能用于展示真实模型的自主诊断成绩。

真实模型必须由运行者显式选择。例如，已确认可使用现有 Codex 订阅时，可按 [PydanticAI 的 Codex provider 文档](https://pydantic.dev/docs/ai/models/openai-codex/) 配置原生 provider，再执行：

```bash
.venv/bin/python -B -m category_system run --data data/fresh_case --case F01 \
  --agent-model openai-codex:gpt-6-astra \
  --agent-request-limit 5 --agent-tool-limit 6 --agent-timeout 90 \
  --output artifacts/F01_sdk_card.json
```

该显式命令会发送当前合成情境并消耗订阅额度。provider 按上游文档使用现有登录；本项目不实现登录、复制凭据或修改账号配置，也不会自动回退到付费 API。此 provider 已完成 F01 一例真实调用，记录见 [首例实测](../artifacts/sdk_live/F01_001/REPORT.md)；这是新的 SDK 路径，不能宣称已修复旧 CLI 启动问题。已有 API 配置的运行者可显式选择相应 provider；费用、权限和数据发送边界须由运行者自行确定。默认运行与离线评测均不会加载真实 provider。

SDK 输出文件必须使用新路径。若文件已存在，程序在调用模型前停止并保留旧记录，避免将旧卡误认成本次成功；失败后不能把旧文件当新结果。调用上限按 SDK 轮数计，底层服务的传输重试另列为未控制，不承诺精确费用上限。

## 业务与证据边界

模型可检查经营表现、诊断运营异常、比较当前已审核的生鲜方案。工具使用封存的当前情境，模型不能提供新的成本、改订货计划、改授权或选别的文件。每次返回记录证据编号和结果指纹，提案引用范围限于实际取得的结果；只有“ID 确实存在”不再够用。无工具调用、格式不符、引用未见证据、达到调用上限或超时，均不产生合格提案。

权威数字仍来自原计算器；方案贡献与缺货风险是条件测算，不是预测。模型的候选行动和补证问题保留“未验证”状态，即使有合法引用也不自动成立。`run_case` 再次计算证据与门禁，所有真实经营动作仍需人工处理，`execution_status=not_executed`。

脚本验证只检查 SDK 流程及数值、商业权限的非干扰。F01 首个真实调用观察到了正确的方案取舍和具体补证，也发现来源输出遗漏分析必需性与授权类型。补回来源语义后，[第二次真实复测](../artifacts/sdk_live/F01_002/REPORT.md)明确区分了分析依据与执行审批，同时保留关键数字和未知项。这只是一对已知案例的前后观察，不构成稳定改善或相同工具条件下对通用助手的优势。原 20 份 B/C 记录、旧组件调用失败及两次真实调用的源码快照继续保留，各段结果不混为一轮成绩。

## 同工具对比入口

`scripts/run_same_tools.py` 用同一个 PydanticAI 循环执行角色提示对比；Python 入口新增仅限 `category` / `general` 的 `proposal_role` 参数，默认仍为原品类角色，CLI 默认、工具、模型配置与决策协议没有改变。运行记录保存实际指令的 SHA-256。

复现实验须使用已配置原生 Codex 登录、具有相应服务权限的 SDK 环境。以下第一步只准备本地文件；第二步会使用现有登录发起六份真实提案请求，失败即停止。它不改登录文件、不自动退回 API 密钥或再次派发。

```bash
# 使用新的目录；不得覆盖或续写已运行的 same_tools_001
python -B scripts/run_same_tools.py prepare --output artifacts/my_same_tools_run --criteria artifacts/same_tools_001/criteria.json
python -B scripts/run_same_tools.py run --output artifacts/my_same_tools_run
```

首次执行后 `session.started` 会阻止重复启动，包括失败或中断；保留记录，不能删除标记把重跑冒充首轮。准备时及每次调用前校验冻结文件、当前源码和依赖版本。完整证据见 [同工具结果](../artifacts/same_tools_001/REPORT.md)，其比较范围严格限于角色措辞，不能宣称整套系统优于通用助手。

## 方法借鉴与反证

- [Anthropic 工具设计](https://www.anthropic.com/engineering/writing-tools-for-agents)：采用少量有业务目的的只读接口；本次借鉴方法，未复用 Anthropic SDK。
- [Anthropic Agent 评测](https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents)：分别检查调用过程与最终结果；引用合法性和协议正确性不能替代业务价值。
- [BCG agentic merchandising](https://www.bcg.com/publications/2026/how-agentic-ai-is-transforming-retail-merchandising)：采用定量引擎与明确决定权的思路；未实现其描绘的跨系统运营模型。
- [McKinsey merchant workflow](https://www.mckinsey.com/industries/retail/our-insights/merchants-unleashed-how-agentic-ai-transforms-retail-merchandising)：工作流、数据和采用能力会限制收益。文章所述商户调研中，多数受访者报告的影响有限；框架升级本身不构成商业成功。

这些来源帮助确定范围和验收方式，没有提供本项目数据、经营阈值或效果背书。既有 Blue Yonder / SymphonyAI 的借鉴与未实现项见 [行业研究](RESEARCH.md)。