Pydantic AI 2.68.0 升级实操：RequestInput 审批、ConversationStore 会话、ModelFallback 截断回退与三处破坏性改名

# 确认 Python 版本满足 PyPI 元数据里的 >=3.11
python --version

# 记录当前安装的 pydantic-ai 版本与依赖
python -m pip show pydantic-ai
python -m pip freeze > requirements-before.txt

# 留一个可回滚的 git 状态
git status --short
git log -1 --oneline
git checkout -b upgrade-pydantic-ai-2680

# 升级前先跑一遍现有测试，保存基线输出
python -m pytest -q > pytest-before.log 2>&1
python -m pip show pytest

# 只升级 pydantic-ai 到 2.68.0（pip）
python -m pip install --upgrade "pydantic-ai==2.68.0"

# 需要验会话存取与持久委派时，按需选 extras
python -m pip install --upgrade "pydantic-ai[ui,temporal]==2.68.0"
# 或验 DBOS 子工作流：python -m pip install --upgrade "pydantic-ai[dbos]==2.68.0"

# uv 项目的等价写法
uv add "pydantic-ai[ui,temporal]==2.68.0"

# 核对装上的确实是 2.68.0
python -m pip show pydantic-ai
python -c "import importlib.metadata as m; print(m.version('pydantic-ai'))"

# 把新版本写进依赖文件，避免 CI 里漂到别的版本
python -m pip freeze > requirements-after.txt
git diff requirements-before.txt requirements-after.txt

# 在仓库根目录搜旧标识符（Linux / macOS / WSL）
grep -R -n -E "num_results|max_duration_secs" --include="*.py" .
grep -R -n -E "CapabilityEvent|previous_item|duration_ms" --include="*.py" .
grep -R -n -E "agent_name|parent_task_id|STEP_PERSISTENCE_EVENTS" --include="*.py" .

# 改名对照（来自官方 Compatibility Notes）
# pydantic_ai_harness:
#   num_results        -> max_results
#   max_duration_secs  -> max_duration_seconds
# CapabilityEvent 字段:
#   -> *_count / *_name / duration_ms / previous_item
# CapabilityEvent outliers:
#   -> <Subject><PastParticiple>Event，另新增 STEP_PERSISTENCE_EVENTS
# 子 Agent 任务控制事件:
#   加 Event 后缀与过去分词名，新增 agent_name 与 parent_task_id

# 改完做一次语法级自检与测试
python -m compileall -q .
python -m pytest -q

# 核对包里确实存在官方提到的名字（只查属性，不臆造导入路径）
python -c "import importlib; m=importlib.import_module('pydantic_ai'); print([n for n in ('RequestInput','AskUser','OutputTokenLimitExceeded','ConversationStore','ModelFallback') if hasattr(m,n)])"

# 在项目里定位旧的审批写法
grep -R -n -E "AskUser|approval|Permissions|deferred" --include="*.py" .

# 官方条目里与这条链路相关的名字（逐项对照文档）
# RequestInput              —— 在 run 内请求审批与回答
# AskUser                   —— 已移到 deferred pipeline
# kind / answered_by        —— deferred calls 的标记字段
# CancellationToken         —— 可从 workflow signal 取消 Temporal durable run
# PromptInjectionDefender   —— 语义分类改为 durable operations，便于在 Temporal 上跑

# 用固定输入跑一条「需要人工批准」的回归用例
python -m pytest -q -k approval

# 官方 2.68.0 特性清单（逐项确认是否影响你的项目）
# ConversationStore / conversation_store  —— UI adapter 会话加载与保存
# OutputTokenLimitExceeded                —— 响应在 max_tokens 处被截断
# ModelFallback                           —— 截断时回退到下一个模型
# RefineOutput                            —— 新增 harness capability
# GoogleDecisionsModel                    —— Gemini Decisions API 后端
# GoogleModel / BedrockConverseModel      —— 用 AI Gateway 的流式成本
# Workspace.run                           —— 支持按命令指定 cwd
# DelegationTasks.discover()              —— 发现委派任务
#                                          单个损坏任务不再阻塞 opened()
# workspace backends                      —— 必须让 detached processes 继续运行
#                                          并在 WorkspaceBackendSuite 里检查

# 回退链是否生效：用超短 max_tokens 触发一次，观察是否切到下一个模型
# 具体配置写法查官方文档；先在测试环境跑，别用生产 prompt
python -m pytest -q -k fallback

# 记录升级后的依赖与测试结果
python -m pip freeze > requirements-after.txt
python -m pytest -q > pytest-after.log 2>&1
git diff --stat

# 回归清单（逐条过一遍，别只看 pytest 退出码）
# 1. 三处改名已全局替换，事件解析兼容新旧字段
# 2. 需要批准的用例：批准前暂停、批准后继续、中断恢复不重复副作用
# 3. 会话能被保存并重新加载（用 ConversationStore 相关用例）
# 4. 超短 max_tokens 能触发截断回退，且费用在预算内
# 5. 一批固定输入的 golden traces 与升级前输出逐项对照
# 6. 用到 Temporal / DBOS 时，子工作流能启动、能取消、能完成

# 汇总对比
python -m pytest -q
git diff pytest-before.log pytest-after.log
git diff requirements-before.txt requirements-after.txt

# 回滚预案：按升级前快照还原（示例，按你项目的依赖工具调整）
# git checkout upgrade-pydantic-ai-2680^ -- requirements.txt
# python -m pip install -r requirements-before.txt