Metadata-Version: 2.4
Name: qi-agent
Version: 0.1.1
Summary: Python-first extensible agent backend, server, and built-in adapters
Requires-Python: >=3.12
Requires-Dist: dashscope>=1.26.4
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: platformdirs>=4.3
Requires-Dist: pydantic-settings>=2.9
Requires-Dist: pydantic>=2.10
Requires-Dist: qi-ai<0.2,>=0.1.1
Requires-Dist: typer>=0.16
Requires-Dist: uvicorn>=0.35
Description-Content-Type: text/markdown

# 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：

```bash
uv tool install qi-agent
```

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

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

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

## 快速开始

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

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

启动管理后端：

```bash
uv run qi-agent serve
```

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

```bash
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 + 阿里百炼完整后端流：

```bash
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 完整流程](docs/live2d/overview.md)。可运行的 PixiJS 参考 Renderer 位于
`examples/live2d_agent/browser`，支持模型加载、手动 Expression/Motion 预览和真实 Agent Prompt。

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

```bash
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 研究与设计](docs/memory/research-and-design.md)。

## Python 使用

```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())
```

## 包结构与依赖方向

```mermaid
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 插件：

```bash
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 环境。完整规则见
[插件安装与更新](docs/extensions/package-manager.md)。

## 开发验证

```bash
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 的可选真实门禁见
[绘梦模型接入记录](docs/live2d/huimeng-asset-integration.md)，包含 Python Runtime 与 Chromium
Renderer 两个可执行烟测入口。

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

## 版本状态

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

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