qi-coding-agent 0.1.0__py3-none-any.whl

qi_agent/docs/json.md

@@ -0,0 +1,112 @@
+# JSON 事件流模式
+
+`qi --mode json "问题"` 不走 TUI,而是把**每个事件**作为一个 JSON 对象打到 **stdout**,一行一个
+(JSONL)。给脚本、管道、上游服务消费用。
+
+```bash
+qi --mode json "总结这个仓库" | jq -r 'select(.kind=="text") | .text'
+```
+
+- **`--mode json` 隐含无头**:即使不加 `-p` 也不进 TUI(判定见 `cli.py` 的 `interactive`)。
+- **stdout 只有事件流**。启动提示、警告、`--verbose` 的进度都走 **stderr** —— 所以 `| jq` 不用
+  过滤杂音。(`--verbose` 对这条流没有影响:JSON 模式本就输出全部事件。)
+- **一个事件一行**。这是刻意的:多行美化会让消费端无法按行切分。契约由
+  `tests/test_cli_run.py::test_mode_json_emits_one_object_per_line` 钉住。
+
+## 1. 每个对象的形状
+
+固定 5 个键,顺序不保证,解析请按名取:
+
+| 键 | 类型 | 说明 |
+| --- | --- | --- |
+| `kind` | string | 事件类型(见 §2) |
+| `agent` | string \| null | 产出该事件的运行单元名(core 是固定名 `general`;子运行会用自己的名字) |
+| `tool` | string \| null | 仅工具事件有值 |
+| `text` | string | 该事件的主文本;没有则为 `""` |
+| `data` | object | 结构化补充信息;没有则为 `{}` |
+
+```jsonc
+{"kind": "agent_start", "agent": "general", "tool": null, "text": "", "data": {}}
+{"kind": "text_delta", "agent": "general", "tool": null, "text": "问题在", "data": {}}
+{"kind": "tool_start", "agent": "general", "tool": "read", "text": "", "data": {"args": {"path": "src/parse.py"}}}
+{"kind": "tool_end", "agent": "general", "tool": "read", "text": "…文件内容…", "data": {"status": "ok", "duration_ms": 12, "exit_code": null, "error": null}}
+{"kind": "text", "agent": "general", "tool": null, "text": "问题在偏移量计算。", "data": {}}
+{"kind": "agent_end", "agent": "general", "tool": null, "text": "问题在偏移量计算。", "data": {"messages": [...], "usage": {"prompt_tokens": 3120, "completion_tokens": 140, "total_tokens": 3260, "llm_calls": 2, "turns": 1}}}
+```
+
+## 2. 事件类型
+
+**core 今天会发的事件**(发射点在 `runner.py` / `runtime.py`):
+
+| `kind` | 时机 | 关键 `data` 键 |
+| --- | --- | --- |
+| `agent_start` | 回合开始 | — |
+| `text_delta` | 逐字增量(打字机效果) | — |
+| `thinking_delta` | 思维链增量 | — |
+| `assistant_message` | 每轮 LLM 回复完成一次 | `{"step": int, "tool_calls": [名字]}` |
+| `tool_start` | 工具调用前 | `{"args": {…}}` |
+| `tool_end` | 工具调用后 | `{"status": "ok"\|"error", "duration_ms": int, "exit_code": int\|null, "error": str\|null}` |
+| `text` | 本回合**最终回答**(整段) | — |
+| `agent_end` | 回合结束 | `{"messages": [...], "usage": {…}}` |
+| `error` | 回合内的失败(模型拒答、工具异常等) | — |
+| `compaction_start` / `compaction_end` | 自动压缩前后 | `{"auto": true, "tokens": int, …}` / `{"auto": true, "tokensBefore": int, …}` |
+
+**声明了但 core 已不再发射**(`AgentEvent` 的注释里还留着,消费者仍会看到旧会话相关的处理代码):
+
+| `kind` | 状态 |
+| --- | --- |
+| `dispatch` | v3 取消 auto 分派后不再产生。`cli.py` / `tui.py` / qi-web 仍**读取**它以便旧会话回放 |
+| `opening` | 不再发射(旧会话里仍有,前端读取以正确回放) |
+
+> **扩展之间的事件(`api.events`)不在这条流里。** 那是扩展对扩展的频道,与这里的宿主事件是
+> 两套 API(见 [extensions.md](extensions.md) §5)。
+
+## 3. 两个必须知道的坑
+
+### `text_delta` 和 `text` 都会出现 —— 别把两者相加
+
+`text_delta` 是逐字增量,`text` 是本回合的**完整回答**。同一条流里两者都有,所以:
+
+- 想要打字机效果 → 只读 `text_delta`;
+- 想要"这一轮的答案" → **只读 `text`**(CLI 与 TUI 就是这么做的);
+- 两者混着累加会得到重复内容。
+
+### 顺序就是因果顺序,不要重排
+
+一轮里 `text_delta*` 与 `tool_start`/`tool_end` 按**真实发生顺序**穿插(工具调用之间的叙述不会被
+丢弃或后置)。把所有文本提到开头、把工具行推到末尾会失去因果 —— 那就等于把这条流降级成
+"两堆东西"。
+
+## 4. 消费示例
+
+```bash
+# 只要最终答案(忽略增量与工具)
+qi --mode json "解释 src/parse.py" | jq -r 'select(.kind=="text") | .text'
+
+# 跟踪工具调用(名字 + 状态 + 耗时)
+qi --mode json "跑一下测试" | jq -r 'select(.kind=="tool_end") | "\(.tool) \(.data.status) \(.data.duration_ms)ms"'
+
+# 取用量
+qi --mode json "你好" | jq -c 'select(.kind=="agent_end") | .data.usage'
+```
+
+```python
+# Python:一次一行读,不必缓冲(JSONL 的用处就在这)
+import json, subprocess
+proc = subprocess.Popen(["qi", "--mode", "json", "总结这个仓库"],
+                        stdout=subprocess.PIPE, text=True)
+for line in proc.stdout:
+    event = json.loads(line)
+    if event["kind"] == "text":
+        print(event["text"])
+```
+
+## 5. 稳定性
+
+**可以依赖**:5 个键的名字 · §2 里"今天会发"的事件类型与它们的 `data` 键 · 一事件一行 · 因果顺序。
+
+**不要依赖**:键的输出顺序 · 未知 `kind` 的存在与否(新事件会加进来)· `data` 里字段是否齐全
+(不同 provider 给的信息不同)· 同一条流里"某类事件恰好出现几次"。
+
+**读到不认识的 `kind` 时跳过即可,不要报错** —— 这与 qi 各处一致的原则相同(旧会话里也有已废弃
+的类型,新版本仍要能回放)。

qi_agent/docs/keybindings.md

@@ -0,0 +1,83 @@
+# 键位
+
+qi 的键位是**固定的**:没有 `keybindings.json` 这类配置文件。要加自己的键,写一个扩展用
+`api.register_shortcut("ctrl+x", handler)`(key 用 Textual 的写法;坏键名只提示,不让启动失败)。
+
+TUI 里 `/hotkeys` 会列出当前生效的键位,并如实标出哪些还没做。
+
+## 主键位
+
+| 键 | 行为 |
+| --- | --- |
+| `escape` | 中断当前回合:**协作式**(未执行的工具补上"已中断"结果、半截回答照常落盘);再按一次、或 3s 宽限期到点仍未收尾 → 强制终止 |
+| `escape` ×2 | 空编辑器连按两次(500ms 内):按 `settings.doubleEscapeAction` 开 `/tree` 或 `/fork`(默认 `tree`) |
+| `ctrl+c` | 清空输入框;再按一次退出 |
+| `ctrl+d` | 输入框为空时退出;非空删右侧字符 |
+| `ctrl+o` | 展开 / 折叠工具输出(压缩块也用它展开看摘要) |
+| `ctrl+t` | 显示 / 隐藏思考块 |
+| `shift+tab` | 循环思考级别(off → minimal → … → max → off) |
+| `ctrl+x` | 复制最后一条回答 |
+| `ctrl+g` | 用 `$EDITOR` 编辑当前输入 |
+| `ctrl+l` | 模型选择器(与 `/model` 同一个) |
+| `ctrl+p` / `ctrl+shift+p` | 下一个 / 上一个模型(轮换清单由 `/scoped-models` 决定) |
+| `ctrl+z` | 挂起(回到 shell) |
+
+## 输入层(多行编辑器)
+
+| 键 | 行为 |
+| --- | --- |
+| `enter` | 提交 |
+| `shift+enter` / `ctrl+j` | 换行 |
+| `ctrl+b` / `ctrl+f` | 光标左 / 右 |
+| `↑` / `↓` | 没有补全面板时翻输入历史(首次进入留住草稿、手动改动即退出);否则移动光标 |
+| `alt+b` `alt+f` `alt+←/→` | 按词移动 |
+| `alt+d` | 删后一个词 |
+| `ctrl+-` | 撤销(`ctrl+z` 留给挂起) |
+| `ctrl+w` / `ctrl+u` / `ctrl+k` / `alt+backspace` | 删词 / 删到行首 / 删到行尾 |
+| `ctrl+y` / `alt+y` | kill-ring 的 yank / yank-pop(删掉的文本进环、连续删合并) |
+| `ctrl+v` | 粘贴(含括号粘贴,多行可用) |
+
+编辑器最多 8 行(矮终端还会再降);长高的部分由 transcript 让位。
+
+## 补全面板
+
+| 键 | 行为 |
+| --- | --- |
+| 行首 `/xx` | 命令名补全 |
+| `/model` `/thinking` `/login` | 参数补全(模型 `provider/model` / 思考级别 / provider) |
+| `@xx`(任意位置) | 路径补全:装了 `fd` 走全树搜索(尊重 `.gitignore`),否则只扫当前目录一层;目录优先 |
+| `tab` | 接受候选(**无候选时仍是缩进**) |
+| `↑` / `↓` | 面板开着时选候选;否则翻输入历史 / 移动光标 |
+| `escape` | 先关面板,再考虑中断 |
+
+## 会话选择器(`/resume`)
+
+| 键 | 行为 |
+| --- | --- |
+| 输入框打字 | 过滤:空格分词(模糊子序列)/ `"短语"` 精确连续 / `re:<正则>` 正则 |
+| `tab` | 切换范围:**当前目录**(默认)↔ 全部 |
+| `↑` / `↓` / `enter` | 选 / 恢复 |
+| `ctrl+n` | 只看命名会话 |
+| `ctrl+s` | 排序循环:树状 → 最近 → 最相关 |
+| `ctrl+p` | 显示 / 隐藏会话文件路径 |
+| `ctrl+r` | 重命名选中会话 |
+| `ctrl+d` | 删除选中会话(**先确认**;当前会话删不掉) |
+| `escape` | 先退出重命名态 / 取消删除确认,再关面板 |
+
+## 树选择器(`/tree`)
+
+| 键 | 行为 |
+| --- | --- |
+| 输入框打字 | 搜索节点(空格分词,全部命中才显示) |
+| `↑` / `↓` / `enter` | 选 / 跳到该节点继续 |
+| `ctrl+d` / `ctrl+t` / `ctrl+u` / `ctrl+l` / `ctrl+a` | 过滤:默认(隐藏状态类)/ 隐藏工具结果 / 只看用户消息 / 只看有标签 / 全部 |
+| `ctrl+o` / `shift+ctrl+o` | 过滤模式循环 / 反向循环 |
+| `shift+l` | 编辑标签(`enter` 保存;留空 = 清除) |
+| `shift+t` | 标签是否附带时间戳 |
+| `escape` | 先退出标签编辑,再关面板 |
+
+## 尚未支持
+
+| 键 | 期望用途 | 现状 |
+| --- | --- | --- |
+| `ctrl+v` | 粘贴图片 | 无图片输入,目前只会粘文本 |

qi_agent/docs/models.md

@@ -0,0 +1,138 @@
+# 选一个模型
+
+qi 通过 litellm 调各家模型。provider 与模型定义都在 `models.json`;**默认模型**在 `settings.json`。
+凭证明文只进 `auth.json` 或环境变量,`models.json` 只允许**引用**。
+
+## 选一条连接
+
+| 想怎么接 | 用什么 |
+| --- | --- |
+| 用 qi 自带的**预置**(国产为主:baseUrl + 约定环境变量 + 核过的模型清单) | `qi init --preset <名>` 或交互式 `qi init` |
+| 自己写一个 provider(自建代理 / 聚合平台) | 编辑 `models.json` 的 `providers` 段,或 `qi init -y` |
+| 本地无鉴权端点(Ollama / llama.cpp / LM Studio) | 写 provider + 一个字面 `apiKey`(如 `"none"`) |
+| 按次换模型,不写配置 | `qi --provider <名> --model <provider/模型>` |
+
+## 认证
+
+凭证解析顺序(auth store → 约定环境变量 → `models.json` 的 `apiKey` 引用)、约定变量表与排查口径见
+[providers.md](providers.md)。`qi auth login <provider>` 写 `auth.json`(0600);TUI 里是 `/login`。
+
+## 选默认模型
+
+```jsonc
+// ~/.qi/agent/settings.json
+{ "defaultProvider": "deepseek", "defaultModel": "deepseek-chat" }
+```
+
+- **唯一来源是 `settings.json`**:`models.json` 里的 `defaultProvider` / `defaultModel`
+  **完全不参与**(不是优先级更低),写了会被忽略并在 `qi doctor` 里报出来。
+- 缺任一项就启动失败,并给出可照抄的迁移命令。
+- 查看:`qi --list-models [搜索词]`(缺密钥的也列,这是诊断面;解析不出凭证的 provider 不列)。
+
+## 接本地模型
+
+本地端点不需要密钥,但要让它**进 `/model` 与 `ctrl+p` 清单**:
+
+```jsonc
+{ "providers": { "local": {
+    "baseUrl": "http://localhost:1234/v1",
+    "api": "openai-completions",
+    "apiKey": "none",                       // 字面值 —— resolve_key 认它,请求只是多一个 Authorization 头
+    "models": [{ "id": "qwen3-8b", "contextWindow": 32768, "maxTokens": 4096 }]
+} } }
+```
+
+`ollama` 是唯一**免密钥**的内置特例(显示为"无需密钥(本地 provider)")。
+
+## 配一个兼容端点
+
+```jsonc
+{
+  "providers": {
+    "deepseek": {
+      "baseUrl": "https://api.deepseek.com/v1",
+      "api": "openai-completions",
+      "apiKey": "$DEEPSEEK_API_KEY",
+      "headers": {},
+      "models": [
+        { "id": "deepseek-chat", "name": "DeepSeek Chat",
+          "reasoning": false, "input": ["text"],
+          "contextWindow": 128000, "maxTokens": 16384 }
+      ]
+    }
+  }
+}
+```
+
+| 字段 | 必填 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| `providers.<name>.baseUrl` | | | API endpoint |
+| `providers.<name>.api` | | `openai-completions` | `openai-completions` / `openai-responses` / `anthropic-messages` / `google-generative-ai` |
+| `providers.<name>.apiKey` | | | 引用:字面量 / `$ENV` / `${ENV}` / `!command`;省略则查 auth store / 约定环境变量 |
+| `providers.<name>.headers` | | | 自定义请求头,值语法同 `apiKey` |
+| `providers.<name>.models[]` | | | 模型列表,每个至少 `id` |
+| `models[].reasoning` | | `false` | 是否支持扩展思考(决定要不要下发 `reasoning_effort`) |
+| `models[].contextWindow` | | `128000` | 上下文窗口 token(自动压缩的阈值基于它) |
+| `models[].maxTokens` | | `16384` | 最大输出 token(作为请求的 `max_tokens` 上限) |
+| `models[].input` | | `["text"]` | 输入类型 |
+
+模型条目可缺省,`resolve_model()` 会用 provider 默认 + 内置默认补齐。
+
+**`apiKey` 值语法**:
+
+| 写法 | 行为 |
+| --- | --- |
+| `"sk-abc"` | 字面量 |
+| `"$ENV"` / `"${ENV}"` | 环境变量插值;**缺失 = 整个值解析失败**(不返回半截) |
+| `"!command args"` | 执行命令取 stdout;非零退出 / 超时(30s)/ 引号不配对 = 失败。**不走 shell**(`shlex` 拆参 + `shell=False`) |
+| `"$$x"` / `"$!x"` | 转义:得到字面 `$x` / `!x` |
+
+## 手写还是让 `qi init` 写
+
+`qi init` 引导默认模型,三步:**选 provider**(已有 / 预置 `[预置]` / 新建 → Base URL → API 类型 →
+API Key,直接写 `auth.json`)→ **Add Models**(`＋ Add a model` / `↻ Refresh model list (GET /models)` /
+`✓ Done` 循环)→ **Activate LLM Model**(写 `defaultProvider` / `defaultModel` 进 `settings.json`)。
+`-l` 写项目 `<项目>/.qi/models.json`(否则全局)。
+
+```bash
+qi init                       # 交互式
+qi init --list-presets        # 看内置预置 provider
+qi init --preset deepseek     # 物化预置(写 models.json)+ 设为默认;可逗号写多个;幂等,不覆盖你写过的值
+qi init --refresh deepseek    # 拉厂商 /models 对齐本地清单(只加不删)
+
+qi init -y --provider deepseek --model deepseek-chat \
+    --base-url https://api.deepseek.com/v1 --api openai-completions --api-key sk-xxx
+```
+
+| 选项 | 说明 |
+| --- | --- |
+| `-y, --yes` | 非交互:必须配 `--provider`(与 `--model`) |
+| `--provider <name>` / `--model <id>` | provider 名(已有或新建)/ 模型 id |
+| `--base-url <url>` / `--api <type>` | endpoint / API 形态 |
+| `--api-key <key>` / `--api-key-env <VAR>` | 写 `auth.json` / 在 `models.json` 里引用环境变量 |
+| `--reasoning` / `--no-reasoning` | 模型是否支持扩展思考 |
+| `--context-window <int>` / `--max-tokens <int>` | 两个元数据(默认 128000 / 16384) |
+| `-l, --local` | 写项目 `.qi/models.json` |
+
+已有模型按 id upsert,重跑安全;`--preset` / `--refresh` 都**只补缺不覆盖**。
+
+## 查找层级
+
+```text
+models.json:  $QI_AGENT_CONFIG(env 指定文件,最高)
+              → <项目>/.qi/models.json
+              → ~/.qi/agent/models.json
+
+默认模型:     <项目>/.qi/settings.json > ~/.qi/agent/settings.json(唯一来源)
+```
+
+键级深合并,内层覆盖外层;文件不存在则跳过。provider 按名覆盖,`models` 数组**整体替换**。
+
+## 排错
+
+| 现象 | 先看 |
+| --- | --- |
+| 模型不在 `/model` 或 `ctrl+p` 清单里 | 清单只列**解析得出凭证**的 provider —— 跑 `qi --list-models` 看 `credential` 列 |
+| "我明明设了环境变量" | `qi doctor` 会给出凭证**来源**(`auth(...)` / `env:XXX` / `config:...`),区分"没读到"与"读到了但为空" |
+| provider 拒收 `reasoning_effort` | qi 会自动去掉参数重试并在 footer 提示一次;也可把该模型的 `reasoning` 改成 `false` |
+| 相容端点返回 4xx | 先确认 `api` 形态选对(`openai-completions` vs `openai-responses` vs `anthropic-messages`) |

qi_agent/docs/packages.md

@@ -0,0 +1,155 @@
+# 扩展的安装与声明
+
+> 装扩展 = 调 pip(或放一个目录);qi **不做**这件事,只做「**声明层 + 比对**」。
+> 相关:[cli.md](cli.md)(命令速查)、[extensions.md](extensions.md)(扩展机制与 API)、[settings.md](settings.md)(`packages` / `extensions` 字段)。
+
+## 1. 谁负责跱这一步
+
+`qi install` **存在**,但它只是**帮你跱一步**:调一次 pip,然后把声明写进
+`settings.packages`。**它不替代“想清楚装到哪个环境”这件事** —— 三种目标环境的行为真的不同:
+
+1. **目标环境有三种**:qi 自己的 venv、`uv tool` 托管的环境、只读的系统解释器(Homebrew / 系统 Python)。
+   qi 每次都把要跑的命令**先打出来**,所以你能看出装到了哪里;只读解释器下 pip 会自己报错,
+   qi 把输出原样给你并补上 `uv tool install qi-coding-agent --with <包>` 那条出路。
+2. **`uv tool` 会整个重建环境**。uv 文档的原话:tool 环境 "may be upgraded via `uv tool upgrade`,
+   or **re-created entirely** via subsequent `uv tool install`"。所以 pip 装进去的扩展**会被抹掉**
+   —— 声明还在,`qi doctor` 会把它报出来(这正是“声明层”存在的意义)。
+3. **`remove` 不卸包**:它只从声明里移除,并把 `pip uninstall` 命令给你。
+   装/卸包是 pip 的事,声明是你的事。
+4. **声明与实装始终是两件事**:声明说"这个环境该有什么",实装由 pip 决定。所以 `qi list` /
+   `qi doctor` 永远做**两个方向**的比对 —— 即使你用的是 `qi install`。
+
+## 2. 声明怎么写
+
+`settings.json` 的 `packages` 是字符串数组(也容忍 `{"name": …}` 这种结构体写法):
+
+```json
+{ "packages": ["pip:qi-mcp>=0.2", "local:./extensions/qi-agents"] }
+```
+
+| 写法 | 通道 | 名字从哪来 |
+| --- | --- | --- |
+| `pip:qi-mcp` | pip | 包名 |
+| `qi-mcp` | pip | 同上(前缀可省) |
+| `qi-mcp>=0.2` | pip | 名字 + 版本约束(整个 spec 会进装法) |
+| `Qi.MCP` | pip | **PEP 503 归一** → `qi-mcp`(与「已装」侧同一规则,否则一边算命中一边不算) |
+| `qi-mcp @ git+https://host/repo` | pip | **显式名字**(PEP 508 的 `名字 @ URL`) |
+| `local:./extensions/qi-mcp` | 目录 | 目录名 |
+| `/abs/path`、`./rel`、`~/x`、`file:…` | 目录 | `Path(...).name` |
+| `{"name": "pip:qi-mcp"}` | 按内容判 | 取 `name` / `spec` / `source` 里第一个非空的 |
+
+> **裸 URL 故意不猜名字**:把 `git+https://host/qi-mcp` 读成一个叫 `git` 的包,比认不出更坏。
+> 这种声明会被**原样回显**并提示改成 `名字 @ URL` —— 不静默丢。
+
+作用域:用户级 `~/.qi/agent/settings.json` 与项目级 `<git 根>/.qi/settings.json` **都读**,
+同名以**项目**为准(近者胜)。两份**分别解析**而不是合并数组 —— 合并会让一侧的声明落到另一侧的基准上。
+
+## 3. 已装扩展从哪来
+
+三个通道,与**装载路径**是同一套(所以报告不会与"实际能加载什么"错位):
+
+| 通道 | 位置 |
+| --- | --- |
+| pip | entry point 组 `qi.extensions`(`importlib.metadata`) |
+| 目录 | `~/.qi/agent/extensions/<名>/extension.py`、项目 `.qi/extensions/<名>/extension.py` |
+| 附加 | `qi -e <dir>`、`settings.extensions[]` |
+
+> **未信任的项目目录不扫** —— 与装载路径同一条门控。否则未信任项目的 `.qi/extensions/`
+> 会让报告显得"已装",而实际一个都没加载。
+
+同名去重:entry point 先到先得。
+
+## 4. 两条装法,失效面不同
+
+`qi doctor` / `qi list` 会把两条都打出来,**不替你选**:
+
+```bash
+# ① 直接装进 qi 所在的那个解释器(最直接)
+/path/to/venv/bin/python -m pip install "qi-mcp>=0.2"
+
+# ② 写进 uv tool 的托管依赖(uv tool 重建 / 升级后仍然在 —— 推荐)
+uv tool install qi-coding-agent --with "qi-mcp>=0.2"
+```
+
+| | ① 直接 pip | ② uv 托管依赖 |
+| --- | --- | --- |
+| 装到哪 | `sys.executable` 对应的环境 | uv 的 tool 环境 |
+| uv tool 重建后 | **丢**(声明还在,所以 `qi doctor` 会把它报出来) | 保留 |
+| 只读解释器 | 失败(pip 自己报错) | 可行 |
+| 适合 | 自己管 venv 的人 | 用 `uv tool` 装 qi 的人 |
+
+## 5. 怎么读输出
+
+装好了但没声明(这份环境里三个扩展都是 editable 装进来的):
+
+```text
+$ qi list
+                            扩展
+┏━━━━━━━━━━━┳━━━━━━┳━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━┓
+┃ 扩展      ┃ 通道 ┃ 版本  ┃ 来源                   ┃ 声明 ┃
+┡━━━━━━━━━━━╇━━━━━━╇━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━┩
+│ qi-mcp    │ pip  │ 0.1.0 │ qi-mcp 0.1.0 · user    │ 否   │
+│ qi-agents │ pip  │ 0.1.0 │ qi-agents 0.1.0 · user │ 否   │
+│ qi-web    │ pip  │ 0.1.0 │ qi-web 0.1.0 · user    │ 否   │
+└───────────┴──────┴───────┴────────────────────────┴──────┘
+  已装但未声明(3): qi-mcp、qi-agents、qi-web —— 写进 settings.packages 才能在 uv
+tool 重建后补回
+```
+
+声明里有一条装不上、还有一条认不出时(`packages: ["pip:qi-todo", "qi-agents", "git+https://host/repo"]`):
+
+```text
+                               扩展
+┏━━━━━━━━━━━┳━━━━━━┳━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━┓
+┃ 扩展      ┃ 通道 ┃ 版本  ┃ 来源                        ┃ 声明   ┃
+┡━━━━━━━━━━━╇━━━━━━╇━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━┩
+│ qi-mcp    │ pip  │ 0.1.0 │ qi-mcp 0.1.0 · user         │ 否     │
+│ qi-agents │ pip  │ 0.1.0 │ qi-agents 0.1.0 · user      │ 是     │
+│ qi-web    │ pip  │ 0.1.0 │ qi-web 0.1.0 · user         │ 否     │
+│ qi-todo   │ pip  │ —     │ pip:qi-todo · settings:user │ 未安装 │
+└───────────┴──────┴───────┴─────────────────────────────┴────────┘
+包声明:
+  ✗ 声明了但没装: pip:qi-todo (settings:user)
+      /…/bin/python3 -m pip install "qi-todo"
+      uv tool install qi-coding-agent --with "qi-todo"
+  ⚠ 无法解析的声明: git+https://host/repo
+      用 `名字 @ URL` 写法才认得出名(如 qi-mcp @ git+https://host/repo)
+  已装但未声明(2): qi-mcp、qi-web —— 写进 settings.packages 才能在 uv tool 重建后补回
+```
+
+四类信息各自的含义:
+
+| 输出 | 含义 | 该怎么办 |
+| --- | --- | --- |
+| 表格里的普通行 | 实际能加载的扩展(通道 / 版本 / 来源 / 是否声明) | — |
+| `未安装` 的行 + `✗ 声明了但没装` | 声明在、加载不到 —— 最可能是 `uv tool` 重建把它抹了 | 复制下面给出的命令 |
+| `⚠ 无法解析的声明` | 这条声明 qi 不认识(典型:裸 URL) | 改成 `名字 @ URL` |
+| `已装但未声明` | 装了,但 `settings.packages` 里没有 | 写上 —— 否则下次重建后没人知道它该在 |
+
+`qi doctor` 的包声明节与 `qi list` 用**同一个**打印函数,所以两边一致;doctor 还会顺带查配置、
+凭证与扩展的宿主依赖契约(见 §7)。
+
+## 6. 报告的数据结构
+
+嵌入方拿到的是 `packages.PackageReport`:
+
+| 字段 | 含义 |
+| --- | --- |
+| `installed` | 实际可加载的扩展(三个通道,去重后) |
+| `declared` | 可解析的声明(项目覆盖用户) |
+| `missing` | 声明了但没装 —— **每一个都带可复制的装法** |
+| `undeclared` | 装了但没声明 |
+| `unparsed` | 认不出的声明(保留**原始 spec**,回显给用户) |
+| `consistent` | 上面三个偏差列表都空 |
+
+两个方向**不合成一个数**:`missing` 与 `undeclared` 的处置完全不同(一个是"装回来",
+一个是"补声明"),合成一个"不一致"会让人无从下手。
+
+## 7. 边界
+
+- 这是**声明与实装的比对**,不是依赖求解器:qi 不去读每个扩展的 `requires()` 算冲突树。
+  那件事在**装载时**按「扩展有没有把宿主写进依赖」单独报(见 [extensions.md §10](extensions.md))。
+- **目录通道的 PEP 723 声明**:`# /// script` 里的 `dependencies` 目前只用于上面那条宿主依赖检查;
+  `qi doctor` 还**不**据它去查"这些依赖装齐了没有"。
+- `settings.packages`(包声明)与 `settings.extensions`(资源路径)是**两件事**:
+  前者是"这个环境该装什么",后者是"到哪里去找扩展目录"。