Metadata-Version: 2.5
Name: qi-agent
Version: 2.1.0
Summary: Agent Kernel, local Runtime Plane, standard plugins, and Host
Requires-Python: >=3.12
Requires-Dist: agent-client-protocol<0.12,>=0.11
Requires-Dist: aiohttp<4,>=3.10
Requires-Dist: fastapi>=0.116
Requires-Dist: filelock>=3.18
Requires-Dist: httpx>=0.28
Requires-Dist: jsonschema>=4.23
Requires-Dist: keyring>=25.6
Requires-Dist: litellm<1.102,>=1.101
Requires-Dist: mcp<3,>=2
Requires-Dist: packaging>=24
Requires-Dist: platformdirs>=4.3
Requires-Dist: pydantic-settings>=2.9
Requires-Dist: pydantic>=2.10
Requires-Dist: pyyaml>=6.0.2
Requires-Dist: typer>=0.16
Requires-Dist: uvicorn>=0.35
Requires-Dist: websockets>=15.0
Requires-Dist: zstandard>=0.23
Provides-Extra: blog
Requires-Dist: qi-blog<3,>=2.0.1; extra == 'blog'
Requires-Dist: qi-web<3,>=2.0.1; extra == 'blog'
Provides-Extra: claude
Requires-Dist: claude-agent-sdk<0.3,>=0.2; extra == 'claude'
Provides-Extra: full
Requires-Dist: qi-blog<3,>=2.0.1; extra == 'full'
Requires-Dist: qi-live2d<3,>=2.0.1; extra == 'full'
Requires-Dist: qi-memory[graphiti,hnsw]<3,>=2.0.1; extra == 'full'
Requires-Dist: qi-voice<3,>=2.0.1; extra == 'full'
Requires-Dist: qi-web<3,>=2.0.1; extra == 'full'
Provides-Extra: media
Requires-Dist: qi-live2d<3,>=2.0.1; extra == 'media'
Requires-Dist: qi-voice<3,>=2.0.1; extra == 'media'
Requires-Dist: qi-web<3,>=2.0.1; extra == 'media'
Provides-Extra: memory
Requires-Dist: qi-memory<3,>=2.0.1; extra == 'memory'
Description-Content-Type: text/markdown

# qi-pi 2.0

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

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

```text
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、Redis、NATS 或多机调度。Runtime Store、
Lease 和 Stream 都通过接口可替换。

## 安装

Python 3.12+。2.1.0 默认集成 LiteLLM SDK + Router。

`qi-agent` wheel 包含 Kernel、Runtime Plane、Host、基础设施、标准插件和默认的
LiteLLM SDK + Router Adapter 和 DashScope Web Search。业务仓库只需安装这一个项目包；第三方依赖由安装器解析。
Python 嵌入调用使用 `from qi_boot import AgentRuntime`，见
[独立业务仓库接入](docs/development/embedding.md)。

```bash
uv tool install qi-agent==2.1.0
cp examples/models.yml models.yml
export DASHSCOPE_API_KEY='...'
qi-agent serve
```

可选能力：

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

源码开发：

```bash
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：

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

提交输入：

```bash
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":"chat","provider":"litellm","display_name":"chat"},
      "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，参见
[安装、配置与独立业务仓库示例](docs/development/postgres-storage.md)。默认内核不依赖 PG 驱动。

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

```text
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 兼容读取。离线迁移：

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

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

## 插件

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

| 插件 ID | Namespace | 能力 |
| --- | --- | --- |
| `qi-agent-standard` | `qi_standard` | Attachment、Title、System Prompt、Context Window、Notes、History |
| `qi-agent-workflow` | `qi_workflow` | Plan、Goal、Todo、Schedule、Skill |
| `qi-agent-coding` | `qi_coding` | Filesystem、Shell、Terminal、Jobs、MCP、LSP、Web Search |
| `qi-agent-collaboration` | `qi_collaboration` | Channel、Subagent、ACP、Claude/Codex/Peer Adapter |
| `qi-agent-persona` | `qi_persona` | Soul、Emotion、Local Refiner |

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

## 文档

- [架构总览](docs/architecture/overview.md)
- [Runtime Plane](docs/architecture/runtime-plane.md)
- [Control Plane 边界](docs/architecture/control-plane-boundary.md)
- [源码阅读指南](docs/code-reading-guide.md)
- [命名规范与 Python 导入迁移](docs/development/naming.md)
- [重点注释规范](docs/development/comments.md)
- [Agent Protocol v3](docs/protocols/agent-protocol-v3.md)
- [Session Store Schema 3](docs/protocols/session-format.md)
- [插件运行时](docs/protocols/plugin-runtime.md)
- [Tool Contract](docs/protocols/tool-contract.md)
- [DSH Host 与 UI](docs/protocols/dsh-host-ui.md)
