开发者文档

语言：四川话 | English | 普通话 | 日本語

给要改库内部的贡献者看的。用库的先去 文档首页 或 赶紧上手，莫一上来就翻源码，打脑壳。

仓库结构

src/pagent/     库代码
examples/       能跑的示例
tests/          pytest
docs/           文档

核心：agent.py（循环）、session.py（对话、滑动窗口/压缩）、llm.py（Provider）、tool.py、tokens.py、events.py。

能力清单

模块	说明
Session	API 形状消息；SlidingWindowSession（按 token 裁）；CompactingSession（LLM 压缩）
LLM	invoke / invoke_stream；RunEnd 是单次模型结果
Agent	run / arun / arun_events / arun_wire
tokens	count_tokens、count_tokens_detail、format_context
events	RunBegin、TextDelta、StepEnd、RunEnd 等 — 见 事件流

刻意莫做

• 并行工具、RAG、MCP、内置文件/Shell、多模态、检查点 — 业务层自己整，库莫胀。
• run() 非流式；流式用 arun() / arun_events()。

本地开发

先把环境 理抹 整齐，再 架势（uv 是啥子？看这儿）：

cd pagent
uv sync --group dev --extra search
pip install -e ".[search]"
uv run pre-commit install
uv run pytest -q

pytest 全绿、pre-commit 过一道 没得问题，再提 PR — 这样办 落教、稳当。还差一脚的，攒把劲 哈。

文档站

VitePress，配置在 docs/.vitepress/config.mts。

cd docs
npm install
npm run dev
npm run build

推 main 后 docs.yml 把 docs/.vitepress/dist/ 发到 gh-pages。仓库 Settings → Pages 选 gh-pages / root，你 经佑 到起发布配置就安逸。

更多

• 事件类型
• reasoning_content 例子
• Hooks 计划（还没实现，先摆在这儿）