pi-agent-py

pi-agent-py 是一个 Python 3.12+ 的独立 Agent 后端。它把模型供应商、确定性 Agent Loop、扩展宿主、持久会话和控制面拆成内部模块；Adapter 通过公共 Extension seam 接入，供网站、桌面应用或未来 Channel Adapter 共用。主体不包含 TUI、管理前端、 RAG 或具体 Channel。

当前能力

• qi_ai：统一 Message/Content/Provider/Event，OpenAI-compatible、Anthropic、Google Adapter，Usage/Cost、重试、Context Overflow 与协作取消。
• qi_agent_core：Run/Turn 状态机、Agent Loop、Tool JSON Schema 校验、Policy、Approval、 Steering、Follow-up、Abort、限制和不可变事件。
• qi_agent_runtime：Capability Registry、Hook Pipeline、Extension API、资源发现、项目信任、 原子热重载、JSONL Session、Branch、Compaction 和 Extension State。
• qi_agent_server：FastAPI 管理接口、SSE、SQLite 统计投影、后台维护任务和非交互式 CLI。
• qi_live2d：内置的 Cubism 模型校验、LLM 控制 Tool、AgentEvent 映射、Snapshot 和 Live2D SSE Adapter；不进入四个主体模块的下层依赖。
• qi_voice：Provider-neutral TTS seam；首个 Adapter 使用阿里百炼 CosyVoice，并只在服务端读取密钥。
• qi_memory：内置的本地优先长期记忆 Extension，提供 Namespace 隔离、SQLite FTS + Embedding 混合召回、ADD-only 写入、来源审计和物理遗忘。
• qi_blog：读取版本化 Blog Catalog，提供 blog_search、blog_open 和 blog_related，结果带 canonical URL 和稳定文档 ID。
• qi_web：只产生经过白名单校验的网站动作意图；默认支持站内导航和章节定位，不提供 DOM、脚本或 内容修改能力。

安装

普通用户只安装两个公开包：qi-ai 提供可复用的 Provider/Event 协议，qi-agent 包含 Agent、 Runtime、Server 和内置 Adapter：

uv tool install qi-agent

源码开发仍保留独立 workspace 模块：

git clone <repository-url> pi-agent-py
cd pi-agent-py
uv sync --all-packages

无需 Docker。uv 会根据 .python-version 准备 Python 3.12。

快速开始

运行无需外部密钥的本地 Echo Agent：

uv run qi-agent run --prompt "hello"
uv run qi-agent run --json --prompt "hello"

启动管理后端：

uv run qi-agent serve

服务默认监听 127.0.0.1:8765。创建会话和 Run：

curl -s -X POST http://127.0.0.1:8765/api/v1/sessions \
  -H 'content-type: application/json' \
  -d '{"metadata":{"title":"demo"}}'

有外部 Provider 密钥时，通过 OPENAI_API_KEY、ANTHROPIC_API_KEY、GOOGLE_API_KEY 或 DASHSCOPE_API_KEY 注入；密钥不会写入 Session 或 SQLite。阿里百炼使用 dashscope Provider 和默认模型 qwen-plus。

启用 Live2D + 阿里百炼完整后端流：

export DASHSCOPE_API_KEY='replace-with-your-key'
export PI_AGENT_DEFAULT_PROVIDER='dashscope'
export PI_AGENT_DEFAULT_MODEL='qwen-plus'
export PI_AGENT_LIVE2D_MODEL_PATH='/absolute/path/avatar.model3.json'
uv run qi-agent serve

浏览器先读取 /api/v1/live2d/model 获得 manifest_url，再订阅 /api/v1/live2d/sessions/{session_id}/events。详见 Live2D 完整流程。可运行的 PixiJS 参考 Renderer 位于 examples/live2d_agent/browser，支持模型加载、手动 Expression/Motion 预览和真实 Agent Prompt。

启用长期记忆（默认关闭自动捕获）：

export PI_AGENT_MEMORY_ENABLED=true
export PI_AGENT_MEMORY_AUTO_CAPTURE=false
uv run qi-agent memory remember "偏好简洁的中文回答" --namespace 'blog:user-42'
uv run qi-agent memory search "回答风格" --namespace 'blog:user-42'

Blog 或 Channel 创建 Session 时应传 memory_namespace 或稳定的 user_id；未登录访客不传身份时 自动使用 session:<session_id>，不会跨访客共享。完整设计见 Memory 研究与设计。

Python 使用

import asyncio

from qi_agent_core import Agent
from qi_ai import AssistantMessage, Model, TextContent
from qi_ai.providers.testing import ScriptedProvider


async def main() -> None:
    agent = Agent(
        provider=ScriptedProvider([AssistantMessage(content=[TextContent(text="hello")])]),
        model=Model(id="test-local", provider="test", display_name="Scripted test model"),
    )
    result = await agent.run("hi")
    assert result.final_text == "hello"


asyncio.run(main())

包结构与依赖方向

flowchart LR
    Server["qi_agent_server<br/>Control Plane"] --> Runtime["qi_agent_runtime<br/>Extension + Session"]
    Server --> Live2D["qi_live2d<br/>Optional Adapter"]
    Server --> Memory["qi_memory<br/>Optional Extension"]
    Live2D --> Runtime
    Memory --> Runtime
    Runtime --> Core["qi_agent_core<br/>Agent Loop"]
    Core --> AI["qi_ai<br/>Provider Protocol"]

只有向下依赖；Contract Test 会扫描 Python AST 阻止反向导入。内部模块保留各自 pyproject.toml 以验证依赖边界，但 PyPI 只发布 qi-ai 和聚合的 qi-agent，用户不需要逐个安装。

插件管理

qi-agent 可以直接管理本地目录、Git 仓库和 PyPI 插件：

qi-agent install ./my-extension
qi-agent install github:owner/weather-extension@v1.2.0
qi-agent install pypi:qi-agent-weather@1.2.0
qi-agent list
qi-agent update weather-extension
qi-agent update
qi-agent remove weather-extension

安装状态记录在 ~/.pi-agent-py/extensions.lock.json。Git 和本地插件被复制到受管目录；PyPI 插件必须声明 pi_agent.extensions Entry Point，并安装到当前 qi-agent Python 环境。完整规则见 插件安装与更新。

开发验证

uv run ruff check .
uv run ruff format --check .
uv run pyright
uv run pytest
uv build --all-packages --out-dir dist/internal
uv build --package qi-ai --out-dir dist
uv build --package qi-agent --out-dir dist
uv run python scripts/smoke_wheels.py
uv run python scripts/verify_docs.py
uv run python scripts/generate_references.py --check
cd examples/live2d_agent/browser && npm ci && npm test && npm run build

带外部模型和 Provider 的可选真实门禁见 绘梦模型接入记录，包含 Python Runtime 与 Chromium Renderer 两个可执行烟测入口。

架构从 docs/architecture/overview.md 开始；扩展作者从 docs/extensions/overview.md 开始；部署者从 docs/operations/local-development.md 开始。

版本状态

当前实现版本为 0.1.1。完成范围和后续 Live2D/Channel 扩展见 docs/roadmap.md。

将本机作为 Blog 的 Agent 后端时，使用 loopback + Cloudflare Named Tunnel，完整安全和恢复步骤见 docs/operations/macos-home-tunnel.md。