migrating-pi-to-pydantic-ai

将 Pi 迁移到 Pydantic AI

保留可观察到的行为，而非 Pi 的 TypeScript API。迁移最小的完整调用路径，并将产品／宿主基础设施保留在应用程序中。

在选择目标前追踪源实现

1. 阅读仓库说明、package.json、Pi 设置、测试、扩展／包清单和运行时入口。记录已安装的 Pi、Pydantic AI 和 Harness 版本。
2. 从 Pi CLI、RPC 边界或 createAgentSession().prompt() 追踪一次真实请求，覆盖资源发现、系统指令、工具、扩展、模型请求、消息、压缩／重试、事件、会话条目、UI／RPC 输出和副作用。建立有针对性的基线或特征测试。
3. 清点所有已启用的扩展工厂和包资源。对每个 pi.on(...)、registerTool、registerCommand、提供程序注册、渲染器／UI 贡献、技能、提示词和持久化条目，记录其触发时机、可信输入、修改内容、输出、状态所有者以及对调用方可见的影响。
4. 在适用时区分以下契约：
   • 模型消息、仅追加的会话条目／树分支、压缩摘要和扩展状态；
   • 模型选择的工具输入、可信宿主上下文、项目信任、审批、授权和 OS 隔离；
   • token 增量、工具生命周期、Pi 扩展事件、能力事件、RPC 事件和终端渲染；
   • Agent 循环行为、CLI／TUI 宿主行为、提供程序传输、包分发和外部副作用。
5. 记录每项观察到的契约、其所有者、语义差异和可执行验证。已安装但未启用的 Pi 包功能不属于迁移范围。

阅读研究与概念映射，了解检测到的功能。实施前请阅读验证与切换。

将扩展视为能力候选项

Pi 扩展是最接近 Pydantic AI 能力的源概念，但其范围更广。扩展可以将 Agent 行为与终端 UI、命令、提供程序注册、资源发现和宿主生命周期结合起来。迁移职责，而非扩展文件：

1. 将可复用的面向模型行为——工具、指令、模型设置、历史／事件处理、护栏和 Agent 循环钩子——映射到生命周期相符的现有 Core 或 Harness 能力。
2. 在 Core Capability 中打包相关指令和工具；仅当可复用行为需要生命周期钩子、自适应模型／设置、原生工具或类型化能力事件时，才继承 AbstractCapability。
3. 将 CLI 命令、标志、键盘快捷键、TUI 渲染器／对话框、会话选择、项目信任、包安装和提供程序凭据设置保留在 Python 应用程序或接口适配器中。它们不会仅因由 Pi 扩展负责，就成为 Agent 能力。
4. 在这一边界拆分混合扩展。权限扩展可以拆分为 ToolGuardrail 或审批能力，加上由应用程序负责的审批 UI；编码包可以拆分为 Coder 和宿主配置；提供程序扩展则仍是模型／提供程序集成。
5. 仅在证据表明顺序会产生影响时才保留顺序。Pi 处理程序的加载顺序与 Pydantic AI 的能力／钩子顺序属于不同的契约。

选择最小目标

• 核心： 使用 pydantic_ai.Agent 实现 Agent 循环、类型化依赖、工具/工具集、输出、规范化消息、能力/钩子、流式处理、审批、用量限制、插桩、MCP，以及提供商/模型集成。
• Harness： 仅当 Coder 的精确组合符合需求时，才用它提供 Pi 的常规编码工具。只有在观察到相应行为时，才添加 FileSystem、Shell、Skills、Planning、SubAgents、护栏、上下文压缩、工具输出限制或步骤持久化等专用能力。
• 应用/接口： 有意保留或替换 CLI/TUI/RPC、身份验证、项目信任、设置、提供商登录/目录、会话浏览、包管理、部署和传输。
• 图： 对确定性工作流使用普通异步 Python 或 pydantic_graph；不要把它们编码到提示词或子 Agent 中。
• 缺口： 指出没有受支持的公共接入点的行为，说明其影响，并测试有界适配器。不要仅为声称功能对等，就克隆 Pi 的扩展总线或 JSONL 格式。

常见的嵌入式迁移方案包括一个可复用的 Agent、Coder 或更精简的能力组合、类型化依赖中的应用服务、由应用负责的消息/会话存储，以及现有 RPC 或 UI 边界上的轻量适配器。

应用高风险关卡

• ctx、项目信任、凭据、会话管理器和服务句柄都属于受信任的宿主上下文。将其等效内容放入类型化依赖或应用服务中，绝不能放入由模型选择的工具参数中。
• Pi 会话 JSONL 是仅追加的分支宿主日志，包含的内容不止模型上下文。result.all_messages() 保留的是模型历史，而不是树导航、标签、扩展条目、上下文压缩记录、模型变更、队列或已放弃的分支。应选择并测试转换方案、兼容存储，或接受从头开始。
• Pi 的上下文压缩、上下文拦截、引导/后续队列、重试和分支摘要都有特定的时序。分别选择匹配的核心/Harness 接入点并测试顺序；通用消息历史或摘要功能并不能自动实现功能对等。
• 根据效果映射 tool_call 权限关卡。使用护栏进行验证/阻止/脱敏；对于必须等待审批的操作，使用延迟工具。将身份、授权、UI、审计、持久化和幂等性交由应用处理。
• Pi 扩展会以宿主权限运行任意 TypeScript。Pydantic AI 能力也会运行应用代码；两者都不是沙箱。对于不受信任的命令或代码，应使用操作系统/容器/云隔离边界。
• Harness Skills 会按需加载已配置的 SKILL.md 指令，但不会复现 Pi 的发现根目录、资源文件、脚本、重新加载、包安装或行为性 frontmatter。观察到这些行为时，应单独保留相应功能。
• 仅将 SubAgents 用于由模型定向的隔离任务。确定性编排以及 Pi 特有的子进程/tmux/包语义应保留在应用代码中。
• 只有在测试过加载时机、架构、提示词/缓存变更和提供商回退行为后，才将动态工具激活映射到核心 ToolSearch 或按需能力。
• Pydantic AI 运行事件和能力事件无法复现 Pi 的扩展事件总线、RPC 协议或 TUI 渲染生命周期。只适配使用者依赖的稳定字段。
• Pi 提供商扩展和负载钩子可能会更改身份验证、目录、线缆负载、标头和流式处理。应在 Pydantic AI 模型/提供商层或应用传输层实现这些功能，并运行提供商契约测试；不要将其隐藏在通用能力中。

实现并验证一个纵向切片

1. 保留受支持的 CLI、RPC、SDK、作业或 UI 边界，仅替换 Agent 自有的内部实现。
2. 从核心功能和最精简的编码能力开始。只有在经过追踪的契约要求时，才添加更广泛的 Harness 行为。
3. 对于每项源扩展，记录其划分：能力行为、应用/接口行为、保留的集成和差距。通过各自的真实边界测试每一侧。
4. 对 RPC/事件和持久化记录使用与语言无关的测试夹具。测试工具参数/结果、错误、事件顺序、会话续接、UI 决策和副作用。离线使用确定性模型；仅针对提供方行为添加有针对性的录制式/实时提供方测试。
5. 只有在没有任何保留的路径需要 Pi 包、设置、Node 运行时或扩展适配器之后，才将其移除。

在实现之前，说明会产生重大影响的语义变更：Pi 的行为、目标行为、对调用方的影响、建议的选择以及剩余风险。

完成

应用验证与切换中的完成标准。准确标注虚假、录制、实时提供方、终端、重启和沙箱证据。