qi-pi 2.0

本地优先的 Agent Kernel + Runtime Plane。Session Event Log 是唯一持久事实源，Everything is a Plugin。

qi-pi 2.0 把执行内核、单机运行平面和传输层明确分开：

REST / WebSocket / SSE / DSH
              ↓
           qi_host
              ↓
      qi_runtime_plane
              ↓
         Agent Kernel
              ↓
     SQLite WAL Runtime Store

• Kernel：Context、Session Actor、Agent Loop、Tool、Approval、Interrupt。
• Runtime Plane：Durable Submission、Worker、Lease、Recovery、Outbox、Stream。
• Host：鉴权、Wire 校验、DTO 映射与响应编码。
• Plugins：标准能力、产品、媒体、Provider 和基础设施。

仓库不实现 Cloud Control Plane、Tenant、Billing、PostgreSQL、Redis、NATS 或多机调度。Runtime Store、 Lease 和 Stream 都通过接口可替换。

安装

Python 3.12+：

qi-agent wheel 包含 Kernel、Runtime Plane、Host、基础设施、标准插件和默认的 OpenAI / DashScope Provider。业务仓库只需安装这一个项目包；第三方依赖由安装器解析。 Python 嵌入调用使用 from qi_boot import AgentRuntime，见 独立业务仓库接入。

uv tool install qi-agent
export DASHSCOPE_API_KEY='...'
qi-agent serve

可选能力：

pip install 'qi-agent[memory]'
pip install 'qi-agent[media]'
pip install 'qi-agent[blog]'
pip install 'qi-agent[full]'

源码开发：

uv sync --all-extras
uv run pytest packages plugins tests
uv run ruff check packages plugins tests
uv run pyright
uv run python scripts/generate_references.py --check

Agent Protocol v3

创建 Session：

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

提交输入：

curl -X POST http://127.0.0.1:8765/api/v3/sessions/SESSION_ID/submissions \
  -H 'content-type: application/json' \
  -d '{
    "operationId":"client-op-1",
    "sessionId":"SESSION_ID",
    "kind":"user-input",
    "payload":{
      "model":{"id":"qwen3.7-max-2026-06-08","provider":"dashscope","display_name":"Qwen3.7 Max"},
      "content":[{"type":"text","text":"你好"}]
    },
    "source":{"transport":"rest"}
  }'

202 表示命令已经持久接纳，不表示 Turn 已完成。结果通过 GET /api/v3/sessions/{session_id}/events 或 /api/v3/agent/ws 获取。

WebSocket 是 JSON-RPC 2.0 双向通道，协议版本固定为 3。审批、Interrupt、Steer 和普通输入都 转换成同一种 Submission。DSH UI 保留自己的 Wire，但内部同样只提交 Submission。

持久化与恢复

可通过独立的 qi-runtime-postgres 插件切换 PostgreSQL，参见 安装、配置与独立业务仓库示例。默认内核不依赖 PG 驱动。

默认事实存储是 <data-dir>/runtime.sqlite3：

submission/accepted + submissions + event_outbox
                   同一 SQLite 事务
                              ↓
                     durable receipt
                              ↓
                       Worker claim
                              ↓
               Session Lease + fencing generation
                              ↓
                      Session Actor

事件只在提交成功后向 SSE、WebSocket、DSH 和投影 Listener 发布。启动时会恢复 pending/过期 claim、 Active Turn，以及“input 已落盘但 turn/start 尚未产生”的输入。

旧 1.x JSONL/Zstd 数据不由新 Host 兼容读取。离线迁移：

qi-agent migrate runtime-v2 --data-dir /path/to/data

成功后旧目录保留为只读备份。

插件

标准能力随 qi-agent 一起发布，仍保留各自的插件 ID 和 Python Namespace：

可选插件使用 Manifest Schema 2，内置插件通过 qi_agent.bundled_plugins Entry Point 发现。 安装 Distribution 不等于启用能力；Profile、Bundle 和 cordis.yml 决定当前 Context Tree。2.0 不保留 qi_agent.plan、qi_agent.fs 等旧导入路径。

文档

• 架构总览
• Runtime Plane
• Control Plane 边界
• 源码阅读指南
• 命名规范与 Python 导入迁移
• 重点注释规范
• Agent Protocol v3
• Session Store Schema 3
• 插件运行时
• Tool Contract
• DSH Host 与 UI