pi-python-core 0.8.1__tar.gz → 0.9.0__tar.gz

pi_python_core-0.9.0/PKG-INFO

@@ -0,0 +1,126 @@
+Metadata-Version: 2.4
+Name: pi-python-core
+Version: 0.9.0
+Summary: An embeddable asyncio agent core with opt-in Claude and OpenAI providers
+License-Expression: MIT
+License-File: LICENSE
+License-File: NOTICE
+Classifier: Framework :: AsyncIO
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: Free Threading :: 2 - Beta
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: jsonschema<5,>=4.18
+Requires-Dist: websockets>=14.2
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.10; extra == 'mcp'
+Provides-Extra: oauth
+Requires-Dist: pyjwt[crypto]<3,>=2.8; extra == 'oauth'
+Provides-Extra: providers
+Requires-Dist: pyjwt[crypto]<3,>=2.8; extra == 'providers'
+Description-Content-Type: text/markdown
+
+# pi-python-core
+
+**English** | [中文](README.zh-CN.md)
+
+An embeddable Python agent core, ported from [Pi](https://github.com/earendil-works/pi) (pinned to `v1.0.0`). It does one job: send the conversation to a model, run the tools the model asks for, hand the results back, and repeat until the model answers. Tools are plain Python functions; the model can be Claude, GPT, DeepSeek, or an open model running on your own machine or cluster.
+
+`pi-agent-core` on PyPI is a separate project that ports an older version from pi-mono (early 2026). This library follows the behavior of Pi v1.0.0, compared case by case with the upstream code's actual output, and ships its own connectors for Claude, OpenAI, DeepSeek and local models, with no model SDK required.
+
+## Install
+
+Python 3.11–3.14 (including free-threaded 3.14t) and PyPy 3.11. No Node.js or model SDK needed.
+
+```bash
+pip install pi-python-core      # or: uv add pi-python-core
+```
+
+You install `pi-python-core` and import `pi_python`.
+
+| Option | What it adds |
+|---|---|
+| (none) | The agent core and the built-in model connectors: Claude, OpenAI, Codex, DeepSeek, and any OpenAI-compatible server (Ollama, vLLM, llama.cpp, …) |
+| `[oauth]` | Verifies the identity token when you sign in with a ChatGPT account (`openai-chatgpt`); it brings in the compiled `cryptography` package. Claude subscription and Codex sign-in do not need it |
+| `[providers]` | Same as `[oauth]`; keeps install commands from 0.8.1 and earlier working |
+| `[mcp]` | Gives the agent the tools of MCP servers, including those a plugin declares |
+
+Dependencies are version ranges rather than pins, so the package fits into most existing environments.
+
+## Five-minute start
+
+```python
+from pi_python import Agent, tool
+from pi_python.providers import AnthropicProvider
+
+@tool
+def word_count(text: str) -> int:
+    """Count the words in a text."""
+    return len(text.split())
+
+agent = Agent(provider=AnthropicProvider(api_key="..."), model="claude-sonnet-4-5", tools=[word_count])
+result = agent.prompt_sync("How many words are in 'to be or not to be'?")
+print(result.messages[-1].content[0].text)
+```
+
+`@tool` builds a tool from the function's signature and docstring; both plain and `async` functions work. In async code, use `await agent.prompt(...)`. Switching to a local model changes two lines:
+
+```python
+from pi_python.providers import OpenAICompletionsProvider
+
+llm = OpenAICompletionsProvider(base_url="http://localhost:11434/v1", name="ollama")
+agent = Agent(provider=llm, model=llm.model("qwen3:8b", context_window=40960), tools=[word_count])
+```
+
+To try it offline first: `python examples/quickstart.py`.
+
+## What it does
+
+| Need | How | Example |
+|---|---|---|
+| Write tools | Decorate a plain function with `@tool`; arguments such as pydantic models, dataclasses, enums and dates are converted automatically; hand-written or MCP-generated JSON Schema works too | [quickstart](examples/quickstart.py) |
+| Connect a model | Claude and GPT through an API key or subscription sign-in; DeepSeek; any OpenAI-compatible server | [local_model](examples/local_model.py), [provider_chat](examples/provider_chat.py) |
+| Use MCP tools | `async with connect_stdio(...) as tools`, or `connect_http(url)` for a remote server | [mcp_tools](examples/mcp_tools.py) |
+| Let one agent call another | Wrap the sub-agent as a tool; cancellation propagates down. Plugins can also define subagents in Markdown | [subagent](examples/subagent.py) |
+| Package and share capabilities | A plugin bundles tools, instructions, hooks, skills, prompt templates, subagents and MCP servers; load it by name or path with `load_plugins` and build the agent with `plugins.agent(...)` | [plugin_demo](examples/plugin_demo.py) |
+| Intervene mid-run | `steer` injects guidance, `follow_up` queues the next task, `abort` cancels at any time (callable from any thread) | |
+| Context full, service errors | `is_context_overflow` and `is_retryable_error` tell you why, `continue_run()` retries, `transform_context` compacts | [recovery](examples/recovery.py) |
+| Save and restore conversations | `encode_messages` / `decode_messages`; your application decides where to store them | [save_restore](examples/save_restore.py) |
+| Observe and audit | Subscribe to events; hooks before and after tool execution can block or rewrite tool calls | |
+
+Apart from `provider_chat`, which needs real credentials, every example runs offline without an API key, and the tests run each one.
+
+## Relationship to Pi
+
+The run loop, event order, hooks, queues, and the handling of errors and cancellation all match Pi, and this is checked differentially: the same inputs go to the pinned upstream code and to this library, and the model requests, tool calls, events and final transcript are compared item by item. All cases currently agree: 25 for the core loop, 50 for model connectors, 2 for multi-turn WebSocket, and 44 error-classification samples. The plugin rules for skills, prompt templates and frontmatter are compared the same way against Pi's coding-agent code.
+
+A few differences are deliberate, such as strict tool-argument validation without type coercion, and returning copies of state to callers. Others are additions for Python users, such as `@tool`, blocking calls, and calling `continue_run()` directly after a failure. Each one is recorded in the [coverage map](compat/COVERAGE.md) (Chinese). Features Pi keeps in its application layer (terminal UI, session file format, context compaction) are not in this core; compaction can be built with hooks, and an example shows the full approach. Plugins are the one piece taken from that layer: an optional module that reads Pi's package format and builds an ordinary Agent from it. This project uses its own version numbers and is not an official Pi release.
+
+## Documentation
+
+- [Concepts on one page: five ideas and one turn](docs/CONCEPTS.md)
+- [Public API](docs/API.md)
+- [Model connectors, subscription sign-in and local models](docs/PROVIDERS.md)
+- [Plugins: skills, prompt templates, subagents and MCP servers](docs/PLUGINS.md)
+- [Implementation and verification results](docs/IMPLEMENTATION.md) (Chinese)
+- [Item-by-item comparison with Pi, and deliberate differences](compat/COVERAGE.md) (Chinese)
+- [Rebuilding the reference and checking release candidates](reference/README.md) (Chinese)
+
+## Development
+
+```bash
+uv sync --locked --extra oauth --extra mcp
+uv run pytest -q
+uv run python scripts/verify.py      # every check, including the comparison with upstream (needs Node)
+```
+
+CI is defined in `.github/workflows/ci.yml` and runs on GitHub Actions for every push: each Python version on Linux (including 3.14t and PyPy), plus macOS and Windows.

pi_python_core-0.9.0/README.md

@@ -0,0 +1,95 @@
+# pi-python-core
+
+**English** | [中文](README.zh-CN.md)
+
+An embeddable Python agent core, ported from [Pi](https://github.com/earendil-works/pi) (pinned to `v1.0.0`). It does one job: send the conversation to a model, run the tools the model asks for, hand the results back, and repeat until the model answers. Tools are plain Python functions; the model can be Claude, GPT, DeepSeek, or an open model running on your own machine or cluster.
+
+`pi-agent-core` on PyPI is a separate project that ports an older version from pi-mono (early 2026). This library follows the behavior of Pi v1.0.0, compared case by case with the upstream code's actual output, and ships its own connectors for Claude, OpenAI, DeepSeek and local models, with no model SDK required.
+
+## Install
+
+Python 3.11–3.14 (including free-threaded 3.14t) and PyPy 3.11. No Node.js or model SDK needed.
+
+```bash
+pip install pi-python-core      # or: uv add pi-python-core
+```
+
+You install `pi-python-core` and import `pi_python`.
+
+| Option | What it adds |
+|---|---|
+| (none) | The agent core and the built-in model connectors: Claude, OpenAI, Codex, DeepSeek, and any OpenAI-compatible server (Ollama, vLLM, llama.cpp, …) |
+| `[oauth]` | Verifies the identity token when you sign in with a ChatGPT account (`openai-chatgpt`); it brings in the compiled `cryptography` package. Claude subscription and Codex sign-in do not need it |
+| `[providers]` | Same as `[oauth]`; keeps install commands from 0.8.1 and earlier working |
+| `[mcp]` | Gives the agent the tools of MCP servers, including those a plugin declares |
+
+Dependencies are version ranges rather than pins, so the package fits into most existing environments.
+
+## Five-minute start
+
+```python
+from pi_python import Agent, tool
+from pi_python.providers import AnthropicProvider
+
+@tool
+def word_count(text: str) -> int:
+    """Count the words in a text."""
+    return len(text.split())
+
+agent = Agent(provider=AnthropicProvider(api_key="..."), model="claude-sonnet-4-5", tools=[word_count])
+result = agent.prompt_sync("How many words are in 'to be or not to be'?")
+print(result.messages[-1].content[0].text)
+```
+
+`@tool` builds a tool from the function's signature and docstring; both plain and `async` functions work. In async code, use `await agent.prompt(...)`. Switching to a local model changes two lines:
+
+```python
+from pi_python.providers import OpenAICompletionsProvider
+
+llm = OpenAICompletionsProvider(base_url="http://localhost:11434/v1", name="ollama")
+agent = Agent(provider=llm, model=llm.model("qwen3:8b", context_window=40960), tools=[word_count])
+```
+
+To try it offline first: `python examples/quickstart.py`.
+
+## What it does
+
+| Need | How | Example |
+|---|---|---|
+| Write tools | Decorate a plain function with `@tool`; arguments such as pydantic models, dataclasses, enums and dates are converted automatically; hand-written or MCP-generated JSON Schema works too | [quickstart](examples/quickstart.py) |
+| Connect a model | Claude and GPT through an API key or subscription sign-in; DeepSeek; any OpenAI-compatible server | [local_model](examples/local_model.py), [provider_chat](examples/provider_chat.py) |
+| Use MCP tools | `async with connect_stdio(...) as tools`, or `connect_http(url)` for a remote server | [mcp_tools](examples/mcp_tools.py) |
+| Let one agent call another | Wrap the sub-agent as a tool; cancellation propagates down. Plugins can also define subagents in Markdown | [subagent](examples/subagent.py) |
+| Package and share capabilities | A plugin bundles tools, instructions, hooks, skills, prompt templates, subagents and MCP servers; load it by name or path with `load_plugins` and build the agent with `plugins.agent(...)` | [plugin_demo](examples/plugin_demo.py) |
+| Intervene mid-run | `steer` injects guidance, `follow_up` queues the next task, `abort` cancels at any time (callable from any thread) | |
+| Context full, service errors | `is_context_overflow` and `is_retryable_error` tell you why, `continue_run()` retries, `transform_context` compacts | [recovery](examples/recovery.py) |
+| Save and restore conversations | `encode_messages` / `decode_messages`; your application decides where to store them | [save_restore](examples/save_restore.py) |
+| Observe and audit | Subscribe to events; hooks before and after tool execution can block or rewrite tool calls | |
+
+Apart from `provider_chat`, which needs real credentials, every example runs offline without an API key, and the tests run each one.
+
+## Relationship to Pi
+
+The run loop, event order, hooks, queues, and the handling of errors and cancellation all match Pi, and this is checked differentially: the same inputs go to the pinned upstream code and to this library, and the model requests, tool calls, events and final transcript are compared item by item. All cases currently agree: 25 for the core loop, 50 for model connectors, 2 for multi-turn WebSocket, and 44 error-classification samples. The plugin rules for skills, prompt templates and frontmatter are compared the same way against Pi's coding-agent code.
+
+A few differences are deliberate, such as strict tool-argument validation without type coercion, and returning copies of state to callers. Others are additions for Python users, such as `@tool`, blocking calls, and calling `continue_run()` directly after a failure. Each one is recorded in the [coverage map](compat/COVERAGE.md) (Chinese). Features Pi keeps in its application layer (terminal UI, session file format, context compaction) are not in this core; compaction can be built with hooks, and an example shows the full approach. Plugins are the one piece taken from that layer: an optional module that reads Pi's package format and builds an ordinary Agent from it. This project uses its own version numbers and is not an official Pi release.
+
+## Documentation
+
+- [Concepts on one page: five ideas and one turn](docs/CONCEPTS.md)
+- [Public API](docs/API.md)
+- [Model connectors, subscription sign-in and local models](docs/PROVIDERS.md)
+- [Plugins: skills, prompt templates, subagents and MCP servers](docs/PLUGINS.md)
+- [Implementation and verification results](docs/IMPLEMENTATION.md) (Chinese)
+- [Item-by-item comparison with Pi, and deliberate differences](compat/COVERAGE.md) (Chinese)
+- [Rebuilding the reference and checking release candidates](reference/README.md) (Chinese)
+
+## Development
+
+```bash
+uv sync --locked --extra oauth --extra mcp
+uv run pytest -q
+uv run python scripts/verify.py      # every check, including the comparison with upstream (needs Node)
+```
+
+CI is defined in `.github/workflows/ci.yml` and runs on GitHub Actions for every push: each Python version on Linux (including 3.14t and PyPy), plus macOS and Windows.

pi_python_core-0.8.1/README.md → pi_python_core-0.9.0/README.zh-CN.md

@@ -1,5 +1,7 @@
 # pi-python-core
 
+[English](README.md) | **中文**
+
 一个可嵌入的 Python agent 核心，移植自 [Pi](https://github.com/earendil-works/pi)（固定参照 `v1.0.0`）。它负责一件事：把对话发给模型，执行模型要求的工具，把结果交回模型，直到得到回答。工具就是普通的 Python 函数；模型可以是 Claude、GPT、DeepSeek，也可以是本机或集群上的开源模型。
 
 PyPI 上的 `pi-agent-core` 是另一个独立项目，移植的是 2026 年初 pi-mono 中的旧版本。本库对照 Pi v1.0.0 的行为，与上游的实际运行结果逐组比较；并自带 Claude、OpenAI、DeepSeek 和本地模型的接入，不需要安装任何模型 SDK。
@@ -9,16 +11,17 @@ PyPI 上的 `pi-agent-core` 是另一个独立项目，移植的是 2026 年初
 支持 Python 3.11–3.14（包括无 GIL 的 3.14t）和 PyPy 3.11，不需要 Node 或任何模型 SDK。
 
 ```bash
-pip install 'pi-python-core[providers]'      # 或 uv add 'pi-python-core[providers]'
+pip install pi-python-core      # 或 uv add pi-python-core
 ```
 
 安装名是 `pi-python-core`，导入名是 `pi_python`。
 
 | 安装选项 | 带来什么 |
 |---|---|
-| 不加选项 | 执行核心，只依赖 `jsonschema` |
-| `[providers]` | 真实模型接入：Claude、OpenAI、Codex、DeepSeek，以及任何 OpenAI 兼容服务（Ollama、vLLM、llama.cpp 等） |
-| `[mcp]` | 把 MCP 服务器的工具交给 agent |
+| 不加选项 | 执行核心和内置模型接入：Claude、OpenAI、Codex、DeepSeek，以及任何 OpenAI 兼容服务（Ollama、vLLM、llama.cpp 等） |
+| `[oauth]` | 用 ChatGPT 账号登录（`openai-chatgpt`）时校验身份令牌，会带进需要编译的 `cryptography`。Claude 订阅和 Codex 登录不需要它 |
+| `[providers]` | 与 `[oauth]` 相同，让 0.8.1 及以前的安装命令仍然可用 |
+| `[mcp]` | 把 MCP 服务器的工具交给 agent，插件声明的 MCP 服务器也需要它 |
 
 依赖写的是版本范围而不是固定版本，能和大多数已有环境共存。
 
@@ -55,8 +58,9 @@ agent = Agent(provider=llm, model=llm.model("qwen3:8b", context_window=40960), t
 |---|---|---|
 | 写工具 | `@tool` 装饰普通函数；pydantic 模型、dataclass、枚举、日期等参数自动转换；也接受手写或 MCP 生成的 JSON Schema | [quickstart](examples/quickstart.py) |
 | 接模型 | Claude 与 GPT 的 API key 或订阅登录；DeepSeek；任何 OpenAI 兼容服务 | [local_model](examples/local_model.py)，[provider_chat](examples/provider_chat.py) |
-| 用 MCP 工具 | `async with connect_stdio(...) as tools` | [mcp_tools](examples/mcp_tools.py) |
-| 让一个 agent 调用另一个 | 把子 agent 包成工具，取消会一路传下去 | [subagent](examples/subagent.py) |
+| 用 MCP 工具 | `async with connect_stdio(...) as tools`；远程服务器用 `connect_http(url)` | [mcp_tools](examples/mcp_tools.py) |
+| 让一个 agent 调用另一个 | 把子 agent 包成工具，取消会一路传下去；插件也可以用 Markdown 定义子 agent | [subagent](examples/subagent.py) |
+| 打包和分享能力 | 插件把工具、说明、钩子、技能、提示模板、子 agent 和 MCP 服务器打成一组；用 `load_plugins` 按名字或路径加载，再用 `plugins.agent(...)` 构造 agent | [plugin_demo](examples/plugin_demo.py) |
 | 中途干预 | `steer` 插入指导，`follow_up` 排队后续任务，`abort` 随时取消（任何线程都可以调用） | |
 | 上下文满了、服务出错 | `is_context_overflow`、`is_retryable_error` 判断原因，`continue_run()` 重试，`transform_context` 压缩 | [recovery](examples/recovery.py) |
 | 保存与恢复对话 | `encode_messages` / `decode_messages`，应用决定存在哪里 | [save_restore](examples/save_restore.py) |
@@ -66,15 +70,16 @@ agent = Agent(provider=llm, model=llm.model("qwen3:8b", context_window=40960), t
 
 ## 与 Pi 的关系
 
-执行循环、事件顺序、钩子、队列、出错与取消的处理都与 Pi 一致，并用差分验证：同一组输入分别交给固定版本的上游代码和本库运行，逐项比较模型请求、工具调用、事件和最终记录。目前核心循环 25 组、模型接入 50 组、WebSocket 多轮 2 组、出错判断 44 条样例全部一致。
+执行循环、事件顺序、钩子、队列、出错与取消的处理都与 Pi 一致，并用差分验证：同一组输入分别交给固定版本的上游代码和本库运行，逐项比较模型请求、工具调用、事件和最终记录。目前核心循环 25 组、模型接入 50 组、WebSocket 多轮 2 组、出错判断 44 条样例全部一致。插件里技能、提示模板和文件头元数据的规则，也用同样的方法和 Pi 的 coding-agent 代码对照。
 
-有几处是有意的差异，例如工具参数严格校验、不自动转换类型，返回给调用者的状态是副本；另一些是为 Python 用户加的，例如 `@tool`、同步调用、失败后直接 `continue_run()`。逐项记录见[验收映射](compat/COVERAGE.md)。Pi 放在应用层的功能（终端界面、会话文件格式、上下文压缩）不在本库核心里；压缩可以用钩子实现，示例里有完整做法。本项目使用自己的版本号，并非 Pi 官方发行版。
+有几处是有意的差异，例如工具参数严格校验、不自动转换类型，返回给调用者的状态是副本；另一些是为 Python 用户加的，例如 `@tool`、同步调用、失败后直接 `continue_run()`。逐项记录见[验收映射](compat/COVERAGE.md)。Pi 放在应用层的功能（终端界面、会话文件格式、上下文压缩）不在本库核心里；压缩可以用钩子实现，示例里有完整做法。插件是从应用层取来的唯一一块：一个可选模块，读取 Pi 的 package 格式，再据此构造普通的 Agent。本项目使用自己的版本号，并非 Pi 官方发行版。
 
 ## 文档
 
-- [一页看懂：五个概念和一轮的流程](docs/CONCEPTS.md)
-- [公开 API](docs/API.md)
-- [模型接入、订阅登录与本地模型](docs/PROVIDERS.md)
+- [一页看懂：五个概念和一轮的流程](docs/zh/CONCEPTS.md)
+- [公开 API](docs/zh/API.md)
+- [模型接入、订阅登录与本地模型](docs/zh/PROVIDERS.md)
+- [插件：技能、提示模板、子 agent 和 MCP 服务器](docs/zh/PLUGINS.md)
 - [实施与验证结果](docs/IMPLEMENTATION.md)
 - [与 Pi 的逐项对照和有意差异](compat/COVERAGE.md)
 - [参照重建与候选版本验证](reference/README.md)
@@ -82,7 +87,7 @@ agent = Agent(provider=llm, model=llm.model("qwen3:8b", context_window=40960), t
 ## 开发
 
 ```bash
-uv sync --locked --extra providers --extra mcp
+uv sync --locked --extra oauth --extra mcp
 uv run pytest -q
 uv run python scripts/verify.py      # 全部检查，含与上游的差分（需要 Node）
 ```

{pi_python_core-0.8.1 → pi_python_core-0.9.0}/compat/COVERAGE.md

@@ -36,7 +36,7 @@
 
 D1–D8 保持原设计的含义。D1 严格输入；D2 执行前钩子不能通过原地修改参数改变调用；D3 资源预算；D4 Python 取消及未知结果；D5 状态复制；D6 输出检查；D7 诊断、原始结果和完整流校验；D8 文本与工具子集。每项有独立 Python 断言，不以 skip 代替验收。
 
-范围外项目：真实模型 SDK、图片/音频/专有推理、OAuth、MCP 客户端、TUI/CLI、持久化与崩溃恢复、子 agent 管理器、Slurm/PBS，以及真实 HPC/科研任务效果。模型侧不支持的内容显式拒绝。上游真实模型 e2e、代理和其他应用测试未运行；它们不计入通过数。
+范围外项目：真实模型 SDK、图片/音频/专有推理、OAuth、MCP 客户端、TUI/CLI、持久化与崩溃恢复、子 agent 管理器、Slurm/PBS，以及真实 HPC/科研任务效果。（后来的版本加入了其中几项的可选模块，核心仍不包含它们：0.7 起有 MCP 适配，0.9 起插件模块提供 Pi 示例扩展里的 `subagent` 工具，见下面各版本的小节。）模型侧不支持的内容显式拒绝。上游真实模型 e2e、代理和其他应用测试未运行；它们不计入通过数。
 
 ## 已知验收边界
 
@@ -48,7 +48,7 @@ D1–D8 保持原设计的含义。D1 严格输入；D2 执行前钩子不能通
 
 新增 Python 合同见 `test_extended_core.py`、`test_providers.py`、`test_oauth.py`。8 个共享网络流输入在 `provider-fixtures/`，实际上游解析器输出和 Python 输出保存在 [provider-conformance.json](results/provider-conformance.json)。它们对比最终内容、签名和停止原因，不等价于所有供应商请求选项或真实账号端到端兼容。
 
-当前边界与明确差异见 [PROVIDERS.md](../docs/PROVIDERS.md)。0.1 的 accepted baseline 保留为历史核心验收记录，新增能力单独记录，不修改固定上游提交。
+当前边界与明确差异见 [PROVIDERS.md](../docs/zh/PROVIDERS.md)。0.1 的 accepted baseline 保留为历史核心验收记录，新增能力单独记录，不修改固定上游提交。
 
 ## 0.3 范围修订
 
@@ -93,7 +93,7 @@ D1–D8 不变。本轮明确记录的差异：WebSocket 帧不带 `stream` 字
 这一轮的目标是好装、多版本可用、容易在上面搭完整的 agent。按与上游的关系分三类记录。
 
 与上游一致，并有对照证据：
-- **Chat Completions 接入**：逐项移植 `openai-completions.ts`，新增 16 组 Provider 差分（Provider 差分共 50 组），覆盖 Ollama、vLLM、llama.cpp、OpenRouter、DeepSeek 等兼容配置和全部 11 种推理参数格式。与上游的差异见 [PROVIDERS](../docs/PROVIDERS.md#本地模型与-openai-兼容服务)。
+- **Chat Completions 接入**：逐项移植 `openai-completions.ts`，新增 16 组 Provider 差分（Provider 差分共 50 组），覆盖 Ollama、vLLM、llama.cpp、OpenRouter、DeepSeek 等兼容配置和全部 11 种推理参数格式。与上游的差异见 [PROVIDERS](../docs/zh/PROVIDERS.md#本地模型与-openai-兼容服务)。
 - **出错判断**：`is_context_overflow`、`is_retryable_error`、`is_recoverable_length` 移植自 `overflow.ts` 和 `retry.ts`，44 条共享样例与上游函数的实际输出一致（`scripts/recovery_conformance.py`）。另外认识本库自己的错误格式：Python 网络错误名，以及按 HTTP 状态码判断本库的 HTTP 错误；上游格式的文字仍按上游规则判断。
 - **工具 schema**：不再只接受一个子集。与上游一样接受 draft-07 等标准 schema，并按 `format`、`pattern` 校验参数（已用上游校验器对同一 schema 实测）；仍只允许指向 schema 内部的引用。D1 的"不转换类型"不变。
 - **HTTP 错误正文**：与上游一样保留，最多 4000 字符；本库另外把请求所带的凭据替换为 `[redacted]`。
@@ -117,3 +117,31 @@ CI 第一次在 GitHub 上运行，Linux 和 macOS 全部通过，另外发现
 
 - **Windows 读错文本文件。** Windows 默认按 cp1252 读文本，含中文的测试数据被读坏。库、compat、测试和示例里的文本读写现在都明确使用 UTF-8；库读取内置模型表时也一样（该文件目前全是 ASCII，以前没有出错）。凭据文件 `0o600` 权限的检查只在 POSIX 上进行，Windows 没有这种权限位。
 - **PyPy 在极深的 schema 上崩溃。** 以前靠 `RecursionError` 拒绝嵌套过深的工具 schema。CPython 上实际上限随 schema 写法变化（`anyOf` 嵌套 81 层，`items` 嵌套 122 层），PyPy 的 JIT 偶尔在报错之前就撑爆底层栈，进程段错误退出。现在注册时先用非递归方式计数，对象和数组嵌套超过 100 层就报 `ConfigurationError`，在所有解释器上相同。上游 Pi 没有这项限制，属于本库新增的差异。代价是：嵌套超过 100 层、以前在 CPython 上能通过的 schema 现在被拒绝。以前子 schema 的嵌套最多能到 197 层，`default`、`const` 等数据值里的嵌套能到约 1000 层。
+
+## 0.9 新增：插件
+
+0.9 加了可选模块 `pi_python.plugins`。它读取 Pi coding-agent 的 package 格式（技能、提示模板、子 agent 定义、`mcp.json` 和扩展代码），再据此构造普通的 Agent。执行循环没有改动。核心只改了一处：把后置钩子应用部分更新（`ToolResultUpdate`）的代码提取成函数 `apply_result_update`，供插件模块复用，行为不变。按与上游的关系分三类记录。
+
+与上游一致，并有对照证据（命令 `scripts/plugin_conformance.py`，运行器 `reference/plugin-runner.ts`，输入 `compat/plugin-cases.json` 和 `compat/plugin-fixtures/`，测试 `tests/test_plugin_conformance.py`）：
+- **提示模板**：`substituteArgs` 38 条、`parseCommandArgs` 11 条、`expandPromptTemplate` 10 条，与上游函数的实际输出一致；读取 `prompts/` 目录得到的名字、描述、参数提示和正文与 `loadPromptTemplates` 一致。
+- **技能**：用一个 13 项的技能目录对照 `loadSkillsFromDir`，覆盖合法技能、名字不合规、缺少描述、禁止模型调用、深层嵌套、技能目录下不再查找、隐藏目录、顶层松散的 `.md`、YAML 写错和描述过长。加载的技能和警告一致；YAML 语法错误的警告文字不同，只比较出现在哪个文件。`formatSkillsForPrompt` 输出的 `<available_skills>` 部分逐字一致，开头的说明改为使用 `read_skill` 工具。`/skill:name` 的展开格式照 `agent-session.ts` 的 `_expandSkillCommand` 移植；它是私有方法，没有做差分。
+- **frontmatter**：10 条共享样例与 Pi 的 `parseFrontmatter` 一致。另外用 Pi 依赖的 `yaml` 库，对本机 2056 个真实的技能、子 agent 和命令文件做了一次比对（不在 CI 里）：两边都能解析的 2034 个结果完全相同；13 个未加引号、含 `: ` 的描述，YAML 报错而本库接受；4 个含 `{{TITLE}}` 的页面模板本库拒绝；5 个两边都拒绝。
+- **多个处理函数怎样合并**：照 `runner.ts` 的 `emitToolCall`、`emitToolResult`、`emitContext`、`emitBeforeProviderRequest` 等移植。只有 Python 测试，没有共享差分：这些规则在 coding-agent 的扩展运行器里，不在固定参照的核心测试范围内。
+- **子 agent 工具**：参数、三种模式、并行上限（8 个任务，同时 4 个）、并行汇总里每个回答 50 KiB 的截断和结果文字，照示例扩展 `examples/extensions/subagent` 移植，只有 Python 测试。
+
+本库新增，或与上游做法不同：
+- 上游由命令行程序发现和加载 package（`pi install`、`settings.json`、项目信任）。本库没有应用程序，由应用代码指定加载哪些插件，不自动发现。已安装的插件通过 entry point 组 `pi_python.plugins` 注册，对应 `pi install npm:...`。
+- 插件代码是 Python 的 `setup(api)`，对应 Pi 扩展的工厂函数。`PluginAPI` 只保留与界面无关的部分（工具、系统提示、钩子、事件、MCP），没有命令、快捷键、渲染器等终端界面接口；另加了 `service`（应用提供的对象）、`options`（按插件分开的设置）、`add_check`（自检）和 `on_close`。
+- 插件处理函数出错时交给 `on_error`，默认写日志；上游交给 `emitError`，显示在界面上。`before_tool_call` 与上游一样，出错时让这次调用失败。应用自己的钩子保持核心行为，不做隔离。
+- 模型用 `read_skill` 工具读取技能（上游让模型用通用的 `read` 工具）。它只能读技能目录里的文件，单个文件不超过 256 KiB。
+- 子 agent 在同一进程、同一事件循环里运行（上游为每个子 agent 启动一个 pi 子进程），使用主 agent 的 Provider 和合并后的全部钩子。上游的子进程会加载同样的扩展，所以插件的处理函数同样作用于子 agent，这一点与上游一致。不指定模型时，子 agent 用调用那一刻主 agent 的模型（上游从设置里取默认模型）。没有上游的 `agentScope`、`cwd` 参数和项目级 agent 的确认步骤。
+- MCP：工具名为 `mcp__<服务器>__<工具>`，但工具名里的 `-` 保留（上游换成 `_`）。字符串里只展开 `${PLUGIN_ROOT}`、`${PYTHON}` 和环境变量，前两个是本库新增；不支持 `!命令`。不支持 OAuth、`exposure` / `toolExposure` 和单次请求超时，这些设置会被忽略并给出警告。新增 `pi_python.mcp.connect_http`，连接 streamable HTTP 服务器；在 MCP SDK 1.10、1.30 和 2.3 上测过。
+- 技能查找不读 `.gitignore`、`.ignore`、`.fdignore`；同一目录里的条目按名字排序（上游按文件系统返回的顺序）；经符号链接回到已经找过的目录时不再进入。
+- 发布前的安全审查加了几处上游没有的保护：`read_skill` 在访问文件系统之前，先按文字拒绝绝对路径、盘符和网络路径（Windows 上解析 `//主机/共享` 时就会连接该主机），`SKILL.md` 也受 256 KiB 上限约束；MCP 的 header 和 URL 不得含控制字符，取自环境变量的值在警告里显示为 `***`；`connect_http` 只在同一源内跟随重定向（MCP SDK 1.10 会跟随到任何源，并把自定义 header 一起带过去）；frontmatter 超过 64 KiB 或嵌套超过 64 层时不予读取；子 agent 运行带着主 agent 的 `RunLimits`。接力步数仍和上游一样不设上限。
+- frontmatter 由内置的小解析器读取，不依赖 YAML 库（比对结果见上）。
+
+已知差异与限制：
+- 没有上游的项目信任机制。插件文档写明只应加载可信的插件；因为不会自动发现插件，只有应用代码点名的插件才会运行。
+- 子 agent 定义里 Claude Code 格式的其他字段（如 `color`）会被忽略。
+
+验证结果见 [实施与验证结果](../docs/IMPLEMENTATION.md)。