qi-coding-agent 0.3.0__tar.gz → 0.4.0__tar.gz

{qi_coding_agent-0.3.0 → qi_coding_agent-0.4.0}/.gitignore

@@ -22,14 +22,17 @@ data/
 # pi 自身的运行期目录(tasks 输出等,非源码)
 .pi/
 
-# qi-web 前端依赖与构建中间产物
+# qi-web / qi-lab 前端依赖与构建中间产物
 extensions/qi-web/ui/node_modules/
 extensions/qi-web/ui/dist/
+extensions/qi-lab/ui/node_modules/
+extensions/qi-lab/ui/dist/
 
 # 编辑器配置
 .vscode/
 
 # vitest 输出(node 侧测试报告;含绝对路径与时间戳,不入库)。
-# 旧 core web 与 qi-web 扩展两条路径都要盖。
+# 旧 core web 与 qi-web / qi-lab 扩展的路径都要盖。
 web/.vitest/
 extensions/qi-web/ui/.vitest/
+extensions/qi-lab/ui/.vitest/

{qi_coding_agent-0.3.0 → qi_coding_agent-0.4.0}/.pi-lens.json

@@ -3,6 +3,8 @@
     "src/qi_agent/web/static/**",
     "extensions/qi-web/ui/node_modules/**",
     "extensions/qi-web/ui/dist/**",
+    "extensions/qi-lab/ui/node_modules/**",
+    "extensions/qi-lab/ui/dist/**",
     "**/*.min.js"
   ],
   "format": {

{qi_coding_agent-0.3.0 → qi_coding_agent-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: qi-coding-agent
-Version: 0.3.0
+Version: 0.4.0
 Summary: 编码 agent 框架:单 agent core + 扩展(MCP / 多 agent / web)
 Project-URL: Homepage, https://github.com/viewnah/qi
 Project-URL: Repository, https://github.com/viewnah/qi

{qi_coding_agent-0.3.0 → qi_coding_agent-0.4.0}/design/agent-config-design.md

@@ -9,7 +9,8 @@
 > | 本文的说法 | 现状 |
 > | --- | --- |
 > | §4.1 `tools` 省略或 `["*"]` = 全部可用 | **省略 = 继承父**(不是"全部";解释成全部会构成提权)· `Role.tools=None` 的注释写明了这一点 |
-> | `display_name` / `keywords` / `include` / `opening` 字段 | `qi_agents/discovery.py` **不解析**这四个;`display_name` 只在读旧会话的 dispatch entry 时回落 |
+> | `display_name` / `keywords` / `include` 字段 | `qi_agents/discovery.py` **不解析**这三个;`display_name` 只在读旧会话的 dispatch entry 时回落 |
+| `opening` 字段 | **已解析**为 `Role.opening`(`message` / `suggestions`),随 `GET /api/agents` 返回;运行期 `qi.opening` 事件仍不再发射 |
 > | §3 包内置 `builtin/agents/general` 兜底 | P-E4c 已去掉;裸 core 不带角色 |
 > | §9 数据源(`data_sources.json`) | **已无实现**(`runtime.py`:「v3 里没有 `data_sources` 了」) |
 > | §8 MCP(v1:只解析与门控) | 已被 **E25 取代**:qi-mcp 有真客户端、代理工具与 `directTools`;现行语义见 qi-mcp README |

{qi_coding_agent-0.3.0 → qi_coding_agent-0.4.0}/design/development.md

@@ -45,13 +45,24 @@ uv run qi --mode json "你好"   # 改完想看一眼事件流时最快
 ## 3. 测试
 
 ```bash
-.venv/bin/python -m pytest            # 全量(53 个测试文件,约 50 秒)
-.venv/bin/python -m pytest -q tests/test_session.py       # 单个文件
+.venv/bin/python -m pytest            # 全量(88 个测试文件,约 90 秒)
+.venv/bin/python -m pytest -q tests/test_session_store.py   # 单个文件
 uv run pytest -q                      # 等价写法
 ```
 
 **qi 没有 `test.sh`** —— 上面就是唯一入口(别去敲不存在的包装脚本)。
 
+### 扩展的测试放扩展自己目录下
+
+`tests/` 是**宿主**的用例;扩展自带的用例放各自目录(`extensions/qi-agents/tests/`、
+`extensions/qi-lab/tests/`),不往根目录里搬 —— 扩展是独立发行包,测试跟着它走。两个前提缺一不可:
+
+1. **`pyproject.toml` 的 `testpaths` 要同时登记**新目录。pytest 只认列出来的目录,
+   忘了登记不会报错,只是那一批测试**静默不跑**(没失败、也没覆盖);
+2. **conftest 按目录生效**,根 `tests/conftest.py` 覆盖不到子目录 —— 所以每个扩展的 tests/
+   自带一份同源精简版(entry-point stub、`~/.qi` 隔离、必要时再加 `minimal_config`)。
+   改根 conftest 的隔离逻辑时**两边一起改**,否则隔离只对一半测试生效。
+
 ### 默认不装载"本机真装的扩展"
 
 `tests/conftest.py` 里有一个 autouse 夹具,把 `qi.extensions` 这组 entry point **stub 成空**。
@@ -82,7 +93,8 @@ pytestmark = pytest.mark.real_extensions      # 只对这类文件生效
 
 ```jsonc
 "include":    ["src", "tests", "extensions"],
-"extraPaths": ["extensions/qi-agents", "extensions/qi-mcp", "extensions/qi-web", "src"]
+"extraPaths": ["extensions/qi-agents", "extensions/qi-mcp", "extensions/qi-web",
+               "extensions/qi-lab", "src"]
 ```
 
 `extraPaths` 是为了让跨包 import(`from qi_agents.discovery import discover`)在类型检查器里也能解析 ——
@@ -96,14 +108,15 @@ pytestmark = pytest.mark.real_extensions      # 只对这类文件生效
 
 ```text
 src/qi_agent/        # core:单包(一个 wheel)。裸启动 = 单 agent
-extensions/          # 三个独立 pip 包,各自有自己的 pyproject.toml / README
-  qi-agents/         #   角色系统 + subagent 委派
+extensions/          # 四个独立 pip 包,各自有自己的 pyproject.toml / README / tests
+  qi-agents/         #   角色系统 + subagent 委派(用例在 qi-agents/tests/)
   qi-mcp/            #   MCP 支持
   qi-web/            #   HTTP 宿主 + 官方 UI(UI 在 qi-web/ui/,自带 package.json)
+  qi-lab/            #   qi-web 的副本 + 分化(用例在 qi-lab/tests/,契约在 qi-lab/docs/api/)
 design/              # 内部设计、决策记录、变更记录 —— **不进 wheel、不注入提示词**
 docs/                # 手册(见 docs/index.md)+ docs.json(导航清单)
 examples/            # 教学样例(不自动加载)
-tests/               # pytest
+tests/               # 宿主的 pytest 用例(扩展自带的在各自 extensions/*/tests/)
 ```
 
 判据很简单:**只有 `src/qi_agent/` 进 wheel**;`docs/` 目前也不进(要把手册随包发布得改

{qi_coding_agent-0.3.0 → qi_coding_agent-0.4.0}/design/overview.md

@@ -42,7 +42,7 @@ core 移除:core 只认 `RunSpec`,而且 `AgentRunner` **不再自己拼 prompt*
 | --- | --- | --- |
 | agent | **内容**:自包含目录 `agents/<name>/`(`agent.md` + `skills/` + `mcp.json`);frontmatter + 正文即 system prompt。**v3 归 qi-agents** | [qi-agents README](../extensions/qi-agents/README.md) |
 | agent 位置 | **2 处**:`~/.qi/agent/agents/` → `<cwd>/.qi/agents/`(v1 还有"包内置 `general`"那层,P-E4c 删除);项目覆盖全局;同层重复报错 | [agent-config-design.md §3](agent-config-design.md) |
-| agent.md 字段 | **v3 只有 `name` / `description` / `tools` / `model`**;`tools: None` = **继承父**(不是"全部":那会提权)。v1 还有 `display_name` / `keywords` / `include` / `opening` | [agent-config-design.md §4](agent-config-design.md) |
+| agent.md 字段 | **v3 有 `name` / `description` / `tools` / `model` / `opening`**;`tools: None` = **继承父**(不是"全部":那会提权)。`opening` = 开场白 + 选择期快捷提问。v1 还有 `display_name` / `keywords` / `include` | [agent-config-design.md §4](agent-config-design.md) |
 | 技能 | 私有自动绑定、渐进披露、无内置共享库;同一 agent 内同名报错 | [skills.md](../docs/skills.md) |
 | MCP | 全局 `~/.qi/agent/mcp.json` + 项目 `.qi/mcp.json`(项目覆盖全局)+ 角色私有 `mcp.json`;角色能不能用由它的 `tools:` 里写什么决定(**默认拒绝**) | [qi-mcp README](../extensions/qi-mcp/README.md) |
 | 数据源 | 设计上住在 agent `data_sources.json`(私有,凭证 env);**v3 无实现**(没有消费它的扩展) | [agent-config-design.md §9](agent-config-design.md) |

{qi_coding_agent-0.3.0 → qi_coding_agent-0.4.0}/design/pi-alignment.md

@@ -110,6 +110,11 @@ qi 在这一层**刻意与 pi 保持一致**:字段名、命令名、`/tree` 语
 | 订阅登录(Claude Pro/Max、Copilot、Codex、xAI) | **支持**(OAuth,带刷新) | **不支持** —— 只有 API key。`print-bearer-token` 与 `--no-refresh` 为兼容 pi 命令面而存在,语义是空操作 |
 | auth store 结构 | `type` 支持多种(含 OAuth 凭证) | 只有 `type: api_key` |
 | 云 provider(Azure / Bedrock / Vertex / Cloudflare) | 有独立章节 | 走 litellm 通用 provider 配置,没有专门文档 |
+| 小米的四个 provider | `xiaomi`(按量付费)、`xiaomi-token-plan-cn/-sgp/-ams`(套餐) | 同 拆法:`mimo`(按量付费)+ `mimo-token-plan`(CN 套餐,`mimo-token-plan-cn` 为别名;sgp/ams 换 baseUrl) |
+| 其余套餐/订阅变体 | `zai` / `zai-coding-cn`(智谱)、`qwen-token-plan-cn` / `-individual`(阿里)、`kimi-coding`(月之暗面,Anthropic 形态) | 同 拆法:`zai-coding` / `zai-coding-cn`、`qwen-token-plan` / `-cn`、`kimi-coding`;区域差异用 baseUrl 表达,key 环境变量各一套 |
+| 国际站 / 国内站命名 | `moonshotai` / `moonshotai-cn`、`minimax` / `minimax-cn`、`zai` / `zai-coding-cn` | 同约定:**裸名 = 国际站,`-cn` = 国内站**(`zai` / `zai-cn`、`qwen` / `qwen-cn`、`moonshot` / `moonshot-cn`、`minimax` / `minimax-cn`);旧名 `zhipu` / `dashscope` 留作别名 |
+| 内置 provider(预置) | opencode / opencode-go / xiaomi 等随 pi-ai 发布的模型目录 | `presets.py` 预置表;opencode 两个(Zen 按量付费 / Go 套餐额度),端点与 pi 的 `models-store.json` 对齐(`/inference/…`;`api`+`baseUrl` 落在**模型**上),种子 id 对厂商 `/models` 目录核过 |
+| OpenCode 会话头 `x-opencode-session` | `withOpenCodeSessionHeader` 包住全部 4 种 api 实现自动注入 | **同**(内置 `provider_headers.py`:值 = 当前会话 id,没会话回退 `"qi"`;provider/模型 `headers` 可覆盖,扩展事件最后跑) |
 
 **没有 OAuth 的直接后果**:用订阅额度(而非 API key)的用户在 qi 上跑不通,必须换成 API key。
 要补这块,需要的是 auth store 的 `type` 扩展 + 刷新逻辑 —— 现在没有([providers.md](../docs/providers.md) 因此不描述不存在的机制)。
@@ -297,6 +302,8 @@ pi 的 `ToolDefinition.executionMode` 是 `"sequential" | "parallel"`(默认顺
 | `apiKey` 值语法 | `!cmd` / `$ENV` / 转义 | 同 |
 | `auth.json` 结构 | `type: api_key` 等 | 同格式,但只有 `api_key` 一种 |
 | **分派模型**(`routerProvider` / `routerModel`) | pi 无此概念(qi v1 的 Dispatcher 用) | **已作废**:`auto` 分派取消,core 是单 agent。配置里这两个键仍在(老配置不报错),但没有自动分派会用到它们;`qi doctor` 仍会打印解析结果 |
+| 模型数据里的 API 形态 | 模型数据全量标注 `api` + `baseUrl`,按 `model.api` 分发到实现(api map) | 同语义走**覆盖链**:`models[].api` / `models[].baseUrl` > `providers.<name>.api|baseUrl`(默认值)> `openai-completions`。预置物化照 pi 的目录形状**每条模型都写 `api`+`baseUrl`**(单端点厂商从统一值展开),所以端点随形态变后缀(opencode:`/inference/v1` vs `/inference`)与单端点(deepseek/mimo)是同一形状;mimo 的 anthropic 端点由此成对表达 |
+| `openai-responses` 的请求形态 | 直接用 responses 实现(打 `/v1/responses`) | 走 litellm 的 `openai/responses/` 前缀桥接(修复后与 pi 同形态;此前被当 chat completions 发) |
 
 ## 13. TUI(原 `tui.md` 的几段对照)
 
@@ -341,7 +348,7 @@ pi 的 `~/.pi/agent/models-store.json` 不是用户配置,而是**远程模型
 | --- | --- |
 | `cli.md` | 头部「参数尽量与 pi 保持一致」;§1/§2/§4/§5/§6 表格的「pi 对齐」整列(逐个开关的命令名/✅ 对照);各单元格里的出处注(`Print response and exit`、`pi --tools`/`-xt`/`-nbt`/`-nt`、`pi -e`、`pi --models`、`pi --api-key`、`pi -ne`/`-nc`、`pi config`、`pi /login` `/logout`、`pi auth print-*`/`check` 的 0/1/2 退出码);§3 `remove`「与 pi 同义」、`update` 默认「pi 同默认」、`--models` 拉远端目录;§4「面板/清单范围与 pi 逐字相同」、`--no-refresh` 为兼容 pi 命令面;§7 `--offline` 对齐 pi 的语义、输出约定与轮次/中断表的 pi 对照(`killTrackedDetachedChildren`、`shouldStopAfterTurn`);§8 二期「pi 能当场换渲染器」 |
 | `how-qi-works.md` | 标题「8 个对齐 pi core tools」;`find` 与 `glob` 的命名分歧(hikqin/pi);`powershell`「pi 同款、参数与 UTF-8 前缀照搬 pi」;shell 解析顺序对齐 pi(`utils/shell.js`、`commandTransport`);`edit` 按 pi 精确编辑;截断策略对齐 pi 的 `output-accumulator`;会话环境变量对齐 `exposeSessionEnvironment`;bash 无过滤「与 pi 取向一致」+ pi `docs/security.md` 引文;`--tools`/`defaultTools` 对齐;`shellPath` 对齐;stdin 对齐 pi 的 `ignore`;容器化路线;文件工具路径限会话目录「与 pi 同为进程权限模型」;真实文件系统「pi 路线」;变更记录「与 pi 对齐」 |
-| `settings.md` | 「文件位置与字段名对齐 pi」;全局/项目配对 `~/.pi/agent/` ↔ `<cwd>/.pi/`;数组整体替换「与 pi 一致」;`shellPath`/`skillsEnabled`/`enableSkillCommands`/`editorPaddingX`/`outputPad`/`autocompleteMaxVisible` 的 pi 默认值;`tuiMode`「qi 默认与 pi 不同(pi 默认 regular)」;第二张表的「pi 中的用途」列;`branchSummary`(pi 的 defaults to no summary);`thinkingBudgets`(pi 另有内置默认表);`defaultThinkingLevel`(`DEFAULT_THINKING_LEVEL`);`defaultTools`「pi 同义」;`retry.provider`(`getProviderRetrySettings`,pi 用毫秒);`retry.enabled`/`maxRetryDelayMs`(pi 有回合级退避重试);`extensions`「对齐 pi」 |
+| `settings.md` | 「文件位置与字段名对齐 pi」;全局/项目配对 `~/.pi/agent/` ↔ `<cwd>/.pi/`;数组整体替换「与 pi 一致」;`shellPath`/`skillsEnabled`/`enableSkillCommands`/`editorPaddingX`/`outputPad`/`autocompleteMaxVisible` 的 pi 默认值;`tuiMode`「qi 默认与 pi 不同(pi 默认 regular)」;第二张表的「pi 中的用途」列;`branchSummary`(pi 的 defaults to no summary);`thinkingBudgets`(pi 另有内置默认表);`defaultThinkingLevel`(`DEFAULT_THINKING_LEVEL`);`defaultTools`「pi 同义」;`retry.provider`(`getProviderRetrySettings`,pi 用毫秒);`retry.enabled`/`maxRetries`/`baseDelayMs`/`maxAgentDelayMs`(**已接**:agent 级退避重试,见 docs/settings.md §8);`extensions`「对齐 pi」 |
 | `configuration.md` | 头部「对齐 pi 的 `core/system-prompt.js`」;「与 pi 的差异(语义)」小节;§3「pi 同款行为」;§4 三处(「不写 pi 那句"你可能还有别的工具"」、pi 的条件化 guidelines、措辞「与 pi 同形」);§5 三处(「对齐 pi」、「pi 会注入空块」、pi 的 `git worktree` 影子去重);§6 三处(「pi 式 XML」×2、「pi 同款」);§6.1 标题「pi 的 `Additional docs`」与「pi 把"主题 → 文件"写死在源码里」;§6.2「pi 的 text or file contents 口径」;§8 决策表(`customPrompt`、`APPEND_SYSTEM.md`、工具清单措辞、XML 形态) |
 | `session-format.md` | `parentSession`「pi 同名字段」;`firstMessage` 回落;`isChanging`;`isSettingsEntry`;`getSessionContextSettings` + `restoredModel`;`hasConfiguredAuth`;`appendModelChange`(只在新会话写);`modelId` 命名差异(pi 驼峰 vs qi `model_id`);`_persist`;`SessionManager` 构造时就 `newSession()` |
 | `tui.md` | §1「逐项对齐 pi」+「以 pi 的 `modes/interactive` 为基线、`theme/*.json` 逐字移植、渲染细节对照过 `user-message.js`/`assistant-message.js`/`tool-execution.js`/`footer.js`/`dynamic-border.js`」;§1.1「与 pi 同名同义,默认相反」+「pi 的默认 `regular`」行;样例里「照搬 pi 句式」;§1.3「命令选择器 = pi 的 `showSelector()`」「`pi_select_text` 的 `SelectList` 版式」「勾选标记是 pi 的 `✓`/空格」;`md*`/`syntax*` 键;已知差异「Textual 与 pi 自研渲染器的边界」「pi 能当场换渲染器」「pi 有 `fullscreenExitOutput`」;§2 命令表里的 `showModelSelector`、`getAvailableSnapshot()`、`→ ✓ 模型 [provider]` 行、「与 pi 的差异:pi 的 `/login` 主要做订阅登录(`auth.oauth`)」、「对齐 pi」;会话树「对齐 pi 的 `id`/`parentId`」+ 整列 pi + 「pi 在加载时迁移」;树键位「pi 的 `app.tree.*`」;压缩「对齐 pi 的 `core/compaction`」「pi 同款底色块」;键位「已对齐 pi;`core/keybindings.js`」+ 整列「pi 的 action」;思考「对齐 pi 的 `thinkingLevel`」「按 pi 的写法显示 `• thinking off`」「pi `DEFAULT_THINKING_LEVEL`」;「匹配 pi 语义」「`ctrl+p` 在 pi 里是切模型」;「尚未对齐」表头「pi 用途」;会话选择器「对齐 pi 的 `SessionSelectorComponent`」「pi 的三档同名同义」「版式与 pi 一致」「pi 的 `firstMessage` 回落」;补全「对齐 pi 的 autocomplete / `handleBashCommand`」「`getArgumentCompletions`」「`select-list.js` 版式」「来源标签是 pi 的口径」;输入层「对齐 pi `pi-tui/components/editor.js`」+ 整列「pi 的 action」「`undo`(pi 不用 `ctrl+z`)」「`kill-ring.js`」;§3「语义对齐 pi」+ 整列 pi + 「与 pi 一致」 |