qi-agent 0.1.1__tar.gz

qi_agent-0.1.1/.github/workflows/ci.yml

@@ -0,0 +1,40 @@
+name: ci
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  quality:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.12"
+          enable-cache: true
+      - run: uv sync --frozen --all-packages
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+      - run: npm install --global @mermaid-js/mermaid-cli
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+      - run: uv run pyright
+      - run: uv run pytest packages tests/contract
+      - run: uv run pytest tests/integration tests/e2e
+      - run: uv run python scripts/load_test.py --sessions 5 --turns 5 --telemetry 100
+      - run: uv run python scripts/verify_docs.py
+      - run: uv run python scripts/generate_references.py --check
+      - run: uv build --all-packages --out-dir dist/internal
+      - run: uv build --package qi-ai --out-dir dist
+      - run: uv build --package qi-agent --out-dir dist
+      - run: uv run python scripts/smoke_wheels.py
+      - working-directory: examples/live2d_agent/browser
+        run: npm ci
+      - working-directory: examples/live2d_agent/browser
+        run: npm audit --audit-level=high
+      - working-directory: examples/live2d_agent/browser
+        run: npm test
+      - working-directory: examples/live2d_agent/browser
+        run: npm run build

qi_agent-0.1.1/.github/workflows/release.yml

@@ -0,0 +1,42 @@
+name: Publish packages to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - name: Check out source
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.12"
+          enable-cache: true
+
+      - name: Install workspace
+        run: uv sync --frozen --all-packages --dev
+
+      - name: Run tests
+        run: uv run pytest -q
+
+      - name: Build public packages
+        run: |
+          uv build --package qi-ai --out-dir dist
+          uv build --package qi-agent --out-dir dist
+
+      - name: Smoke test public wheels
+        run: uv run python scripts/smoke_wheels.py
+
+      - name: Publish to PyPI
+        run: uv publish --check-url https://pypi.org/simple dist/*

qi_agent-0.1.1/.gitignore

@@ -0,0 +1,16 @@
+.venv/
+.pytest_cache/
+.ruff_cache/
+.hypothesis/
+.coverage
+htmlcov/
+dist/
+build/
+*.egg-info/
+__pycache__/
+*.py[cod]
+*.db
+*.sqlite3
+.pi-py/
+node_modules/
+examples/live2d_agent/browser/public/live2dcubismcore.min.js

qi_agent-0.1.1/.python-version

@@ -0,0 +1 @@
+3.12

qi_agent-0.1.1/CHANGELOG.md

@@ -0,0 +1,81 @@
+# Changelog
+
+格式遵循 Keep a Changelog；版本号遵循 Semantic Versioning。
+
+## Unreleased
+
+- 新增可选 `qi-voice` 包、阿里百炼 `cosyvoice-v3.5-plus` WebSocket 实时 TTS、一次性默认音色
+  注册命令与受保护的 PCM 流式接口。
+- 明确正式 Live2D UI 嵌入 Astro Blog 全局布局，独立浏览器示例仅用于协议诊断和部署冒烟。
+
+### Added
+
+- 新增 `qi-agent install/update/remove/list` 轻量插件管理，支持本地目录、Git、PyPI、原子替换和
+  `extensions.lock.json` 解析版本锁定。
+
+- 完成 `agent.qixiaoluo.dpdns.org` Named Tunnel、Vercel Production BFF 与
+  `blog.qixiaoluo.dpdns.org` 自定义域名部署，并通过 Session、Run、Live2D SSE 和 PCM TTS
+  线上冒烟测试。
+- 新增 macOS 家庭服务器启动包装器、Keychain/launchd/Cloudflare Named Tunnel 运维文档，
+  并覆盖 loopback 绑定、异常恢复和 Vercel BFF 部署边界。
+- 新增可独立构建的 `qi-blog` 与 `qi-web` 包：Blog Catalog 检索/打开/相关推荐工具，以及只读、同源、白名单校验的网站动作意图。
+- Live2D 事件流支持 `live2d.web.action.intent`；动作只由浏览器在用户确认后执行，不提供 DOM、脚本或内容写入能力。
+- 新增可独立构建的 `qi-memory` 包：ADD-only MemoryService、SQLite/InMemory Store、Hashing 与
+  OpenAI-compatible Embedder、FTS/向量 RRF、情景时间衰减和 MMR。
+- 新增 `memory_remember`、`memory_search`、`memory_forget` Tool，七个 Memory AdminAction 和
+  `qi-agent memory` 运维 CLI；遗忘 Tool 默认进入 Approval。
+- 新增按 Session Metadata/Identity Hash/Session 回退的 Namespace 隔离，以及成功 Run 后 User-only
+  保守捕获、Secret/PII/Prompt Injection 拒绝和不可信上下文转义。
+- 新增 Memory 研究、ADR、Schema、配置、安全与运维文档，并把第六个 wheel 纳入隔离安装烟测。
+- 新增可独立构建的 `qi-live2d` 包：Cubism 模型资产校验、LLM 控制 Tool、AgentEvent 状态映射、
+  Session Snapshot 和可重放 SSE。
+- 新增阿里云百炼 `dashscope` OpenAI-compatible Provider 配置。
+- 新增 Live2D 模型、资产、命令、Snapshot、事件流和 Extension AdminAction 管理接口。
+- 新增 `qi-live2d inspect` 模型诊断命令和隔离 wheel 安装冒烟门禁。
+- 新增安全、原子、支持旧文件名编码的 `qi-live2d unpack`，以及可复用的部署 Manifest
+  `overlay` 命令。
+- 新增可运行的 PixiJS Live2D 参考 Renderer，覆盖 Session、Run、Live2D SSE、Expression 与
+  Motion 端到端调用。
+- 新增可选 Chromium 部署烟测，验证 WebGL 模型加载、Session 刷新恢复、认证、Agent Tool 与
+  Live2D SSE 的真实浏览器链路。
+- 完成 `huimeng.zip` 模型实测：10 个 Expression、`Idle[0]` Motion、8192 纹理和 DashScope
+  Tool Call 全链路均已验证。
+
+### Changed
+
+- PyPI 发布面从九个 workspace distribution 收敛为 `qi-ai` 与 `qi-agent` 两个公开包；内部模块
+  继续独立做依赖边界、类型和构建验证。
+
+- Runtime 现在真正消费 ContextProvider、TelemetrySink、AdminAction Capability。
+- Extension 全局/Session 禁用同时作用于 Capability、Hook、Telemetry 和生命周期。
+- 热重载把 Capability、Hook 与 lifecycle 固定到同一 Run generation；旧实例在最后一个 Registry
+  Snapshot 释放后 Shutdown。
+- Run 与 Live2D SSE 支持 SQLite 重放、`Last-Event-ID` 续传和 Live2D Snapshot/Sequence 重启恢复。
+- ContextProvider 与 TelemetrySink 使用 Hook 超时预算，坏扩展不能永久阻塞 Run。
+- `qi-agent doctor` 会隔离报告 Live2D 模型错误并继续执行其余后端检查。
+- Live2D 终止事件显式携带最终状态，使浏览器在 Run 完成或失败时无需额外 Snapshot 请求即可
+  恢复为 `idle` 或 `error`。
+- Live2D Event 在 Python 运行时执行与 JSON Schema 相同的类型/载荷校验；公开错误只含稳定错误码
+  和安全文案。
+- Session Live2D SSE 连接可承载连续多轮 Run，内存回放改为有界窗口，完整历史继续由 SQLite
+  提供。
+- 模型 Overlay 改为保留并合并原有 Expression/Motion，同名冲突明确拒绝。
+
+## 0.1.0 - 2026-07-31
+
+### Added
+
+- 四包 Python 3.12+ `uv` workspace 和单向依赖检查。
+- 四种 Provider Adapter、统一流事件、Usage/Cost、重试和取消。
+- Agent Loop、Tool Policy、Approval、Steering、Follow-up 与运行限制。
+- Capability/Hook/Extension/ResourceLoader 和可回滚热重载。
+- JSONL Session、Branch、Compaction、修复、导出和 Extension State。
+- FastAPI/SSE 控制面、SQLite Telemetry 投影、Rollup 与恢复 Worker。
+- 云 Provider 原生 SSE、结构化 Tool 续轮、并发幂等 Run 与延迟/Approval 投影。
+- Run 级持久 Extension Session 绑定和有界 Event subscriber backpressure。
+- 非交互式 `qi-agent` CLI、配置优先级、Keyring 和日志脱敏。
+- Contract、Integration、E2E 测试和完整架构/协议/运维文档。
+
+### Explicitly not included in 0.1.0
+
+- TUI、管理前端、Live2D、TTS、RAG 和具体 Channel Adapter。

qi_agent-0.1.1/CONTRIBUTING.md

@@ -0,0 +1,34 @@
+# Contributing
+
+## 开发环境
+
+要求 `uv` 和 Git。初始化后不要直接在系统 Python 安装依赖。
+
+```bash
+uv sync --all-packages
+```
+
+## 改动规则
+
+1. 保持 `qi_ai ← qi_agent_core ← qi_agent_runtime ← qi_agent_server` 单向依赖；可选
+   `qi_live2d` 只依赖 Runtime，Server 可以组合它，主体包禁止反向导入。
+2. 新的外部变化必须放到现有 seam 的 Adapter 后；不要让 Core 感知供应商或数据库。
+3. 先添加一个描述公共行为的测试，再实现一条纵向链路。
+4. 公共接口、事件或存储格式变化必须同时修改 Markdown、Schema 和 Changelog。
+5. Accepted ADR 不修改结论；新建 ADR 取代旧决定。
+
+## 提交前检查
+
+```bash
+uv run ruff check .
+uv run ruff format --check .
+uv run pyright
+uv run pytest
+uv build --all-packages
+uv run python scripts/smoke_wheels.py
+uv run python scripts/verify_docs.py
+uv run python scripts/generate_references.py --check
+```
+
+提交应小而完整：测试、实现和对应文档在同一提交。不要提交真实 API Key、用户 Session、
+SQLite 数据库或 Extension 信任文件。

qi_agent-0.1.1/PKG-INFO

@@ -0,0 +1,206 @@
+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)。

qi_agent-0.1.1/README.md

@@ -0,0 +1,187 @@
+# 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)。

qi_agent-0.1.1/SECURITY.md

@@ -0,0 +1,30 @@
+# Security
+
+## 支持范围
+
+安全更新优先覆盖最新 `0.x` 版本。漏洞请通过仓库私有安全报告渠道提交，不要在公开 Issue
+附带 Secret、Session JSONL 或数据库副本。
+
+## 信任边界
+
+Extension 是进程内 Python 代码，不是沙箱。已安装 Entry Point 和用户目录 Extension 被视为
+操作者主动安装；项目目录 `.pi-py/extensions/` 默认不执行，必须通过 Trust Store 授权。
+Manifest 权限是审计声明，不等价于操作系统隔离。
+
+## Secret
+
+- 优先读取 Provider 专用环境变量，其次读取系统 Keyring。
+- Secret 不进入 `Model`、Agent Event、Session JSONL、Audit Log 或 OpenAPI。
+- `RedactingFilter` 会遮盖常见 Bearer/API Key/Token 日志片段，但调用者仍应避免记录原始请求头。
+- 曾粘贴到聊天、Issue 或日志的测试 Key 也视为已泄露，完成烟测后应立即轮换。
+
+## 管理接口
+
+生产或远程访问必须设置 `PI_AGENT_ADMIN_TOKEN`，使用 Bearer Token；Cookie 会话还要求
+`X-CSRF-Token`。默认监听回环地址。TLS 应由反向代理终止，数据库和 Session 目录应限制为
+服务账号可读写。
+
+## Extension 供应链
+
+固定依赖版本，验证发布包来源；本地代码变更通过 Fingerprint 触发两阶段重载。已安装包代码
+升级应重启进程，以免同一解释器同时持有不兼容模块。

qi_agent-0.1.1/docs/adr/0001-four-package-architecture.md

@@ -0,0 +1,20 @@
+# ADR-0001: Four-package architecture
+
+- Status: Accepted
+- Date: 2026-07-31
+
+## Context
+
+Agent 主体必须能脱离网站、Live2D 和任何 Channel 复用，同时允许模型、运行时与控制面按不同
+速度变化。单包会让 FastAPI/SQLite/厂商 SDK 侵入 Agent Loop。
+
+## Decision
+
+采用 `qi_ai ← qi_agent_core ← qi_agent_runtime ← qi_agent_server` 四包单向依赖。以 AST Contract
+Test 和独立 wheel build 强制边界。
+
+## Consequences
+
+Core 测试快速且确定；Provider 和存储可替换。跨包功能需要显式事件/协议，初期文件数更多，
+但调用者只学习所在层的接口。
+

qi_agent-0.1.1/docs/adr/0002-no-tui.md

@@ -0,0 +1,18 @@
+# ADR-0002: No TUI
+
+- Status: Accepted
+- Date: 2026-07-31
+
+## Context
+
+系统目标是多客户端共享后端。TUI 会把键盘循环、渲染状态和交互假设带入主体。
+
+## Decision
+
+0.1.0 不实现 TUI。只提供非交互 CLI、HTTP/SSE 和 OpenAPI。后台统计先提供后端接口，不提供
+管理 SPA。
+
+## Consequences
+
+自动化和服务部署更简单；交互式体验由未来独立客户端实现，不改变 Agent Core。
+