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

{qi_coding_agent-0.2.1 → 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.2.1 → 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.2.1 → qi_coding_agent-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: qi-coding-agent
-Version: 0.2.1
+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.2.1 → qi_coding_agent-0.4.0}/design/PLAN.md

@@ -173,10 +173,10 @@ testpaths = ["tests"]
 | B9 | agent.md icon | 不进 v1 |
 | B10 | 样例 | examples/ 加 writer + general(演示 auto 多角色) |
 | A7 | 凭证存储 | auth store `~/.qi/agent/auth.json`(0600,git 不跟踪);解析顺序 auth store → 约定 env → models.json `apiKey` 引用;`qi auth login/logout/list` + 只读三件套 `print-api-key` / `print-bearer-token` / `check`(退出码对齐 pi:0/1/2)、`qi init` 引导 |
-| A8 | 全局目录层级 | `~/.qi/agent/` ↔ `<项目>/.qi` 配对(对齐 pi 的 `~/.pi/agent` ↔ `.pi`);旧扁平布局启动时自动迁移(不覆盖);`QI_AGENT_HOME` = agent 目录、`QI_CONFIG_DIR` = 名字空间根 |
+| A8 | 全局目录层级 | `~/.qi/agent/` ↔ `<cwd>/.qi` 配对(对齐 pi 的 `~/.pi/agent` ↔ `.pi`);旧扁平布局启动时自动迁移(不覆盖);`QI_AGENT_HOME` = agent 目录、`QI_CONFIG_DIR` = 名字空间根 |
 | A9 | 设置文件 | `settings.json` 两级深合并、数组整体替换;默认模型只属于 settings(`models.json` 里已不读取);字段清单与“仅存储未生效”清单见 [settings.md](../docs/settings.md);`qi config` 读写 |
-| A10 | 顶层技能 | 六级来源(低→高):`~/.agents/skills` → `~/.qi/agent/skills` → user `settings.skills` → 项目 `.agents/skills` 祖先链 → `<git根>/.qi/skills` → project `settings.skills`;agent 自带者最高;同层同名报错、跳层覆盖;排除项作用于整个发现集 |
-| A11 | 系统提示词 | 默认基座**代码内**(`system_prompt.py`,按解析后的工具集生成「可用工具 / 指南」+ **手册索引**);`SYSTEM.md` **整体替换**默认基座(项目 > 全局);之后动态追加 `<project_context>`(AGENTS.override.md > AGENTS.md > AGENTS.MD > CLAUDE.md > CLAUDE.MD,全局 + 祖先链至 git 根)→ `<available_skills>` XML(无 `read`/`bash` 则不注入)→ cwd → `--append-system-prompt`。角色层与数据源**不在 core**(归 qi-agents / 提供方扩展)。详见 [configuration.md](../docs/configuration.md) |
+| A10 | 顶层技能 | 六级来源(低→高):`~/.agents/skills` → `~/.qi/agent/skills` → user `settings.skills` → 项目 `.agents/skills` 祖先链 → `<cwd>/.qi/skills` → project `settings.skills`;agent 自带者最高;同层同名报错、跳层覆盖;排除项作用于整个发现集 |
+| A11 | 系统提示词 | 默认基座**代码内**(`system_prompt.py`,按解析后的工具集生成「可用工具 / 指南」+ **手册索引**);`SYSTEM.md` **整体替换**默认基座(项目 > 全局);之后动态追加 `<project_context>`(AGENTS.override.md > AGENTS.md > AGENTS.MD > CLAUDE.md > CLAUDE.MD,全局 + 祖先链至文件系统根)→ `<available_skills>` XML(无 `read`/`bash` 则不注入)→ cwd → `--append-system-prompt`。角色层与数据源**不在 core**(归 qi-agents / 提供方扩展)。详见 [configuration.md](../docs/configuration.md) |
 | A12 | 轮次 / 超时 / 中断 | **对齐 pi:runner 里既不设轮次上限,也不套回合级请求超时** —— 循环是 `while True`,退出靠模型不再调工具 / 中止 / 嵌入方谓词 `stop_after`(pi 的 `shouldStopAfterTurn` 同形,默认 `None` = 不限)。**qi 自己从不传谓词**(pi-coding-agent 也从不实现那个钩子):交互式靠 `escape` / 客户端断开,无头靠 `SIGTERM`/`SIGHUP` → `kill_live_children()` + `exit(143/129)`(对齐 pi 的 `killTrackedDetachedChildren`)。请求级超时与重试归 **provider 层**(`settings.json` 的 `retry.provider.timeoutMs` / `maxRetries` → litellm `timeout` / `num_retries`;对齐 pi 的 `getProviderRetrySettings`)。中断是**协作式**(`abort.py` 的 `AbortSignal`):未执行的 tool_call 补“已中断”结果、半截回答照常落盘、照常发 `agent_end`(data 带 `aborted`);TUI `escape` 宽限 3s 后 `cancel_all()` 兜底;硬取消(`CancelledError`,含 SIGINT/ASGI 取消)也先落盘再抛 |
 
 ### 仍待定(v2 + 实现期)

{qi_coding_agent-0.2.1 → 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 |
@@ -49,7 +50,7 @@ agent 只可能出现在 **3 个位置**,目录名都用 `agents/`:
 | --- | --- | --- |
 | 包内置 `qi_agent/builtin/agents/` | 框架自带兜底(仅 `general`),随 wheel 发布 | 最低 |
 | `~/.qi/agent/agents/` | 全局(所有项目可用) | 中 |
-| `<项目>/.qi/agents/` | 项目私有(跟项目走,可提交共享) | **高** |
+| `<cwd>/.qi/agents/` | 项目私有(跟 cwd 走,可提交共享) | **高** |
 
 同名规则:
 
@@ -127,7 +128,7 @@ opening:
 | 2 | `~/.qi/agent/skills/` | `qi-global` | 认 |
 | 3 | user `settings.json` 的 `skills[]` | `settings-global` | 认 |
 | 4 | `.agents/skills/`(cwd → git 根,远→近) | `agents-project` | 忽略 |
-| 5 | `<git根>/.qi/skills/` | `qi-project` | 认 |
+| 5 | `<cwd>/.qi/skills/` | `qi-project` | 认 |
 | 6 | project `settings.json` 的 `skills[]` | `settings-project` | 认 |
 
 - **agent 自带技能优先级最高**:同名时覆盖顶层 —— 越具体越优先。
@@ -142,7 +143,7 @@ opening:
 ## 6. 装载与校验流程
 
 ```text
-扫 ~/.qi/agent/agents/ 与 <项目>/.qi/agents/(项目优先,同名警告)
+扫 ~/.qi/agent/agents/ 与 <cwd>/.qi/agents/(项目优先,同名警告)
   → 每个 <name>/ 解析 agent.md:
      frontmatter → AgentConfig(pydantic)
      校验: name==目录名 / description 非空 / tools 存在于 ToolCatalog
@@ -175,7 +176,7 @@ AgentUnit("code-analyst")
 | 来源 | 位置 | 可见性 |
 | --- | --- | --- |
 | 全局 server | `~/.qi/agent/mcp.json`(共享基建,凭证仅 env 引用) | 按 agent 声明绑定 |
-| 项目 server | `<git根>/.qi/mcp.json`(跟项目走,可提交共享) | 按 agent 声明绑定 |
+| 项目 server | `<cwd>/.qi/mcp.json`(跟项目走,可提交共享) | 按 agent 声明绑定 |
 | 私有 server | agent 目录内 `mcp.json`(拷贝即走) | **仅该 agent**,自动绑定 |
 
 三处**同一份格式**(`{"mcpServers": {…}}`),共用一个解析器(`loader.read_mcp_file`)。
@@ -281,7 +282,7 @@ qi agents import skill:path/to/skill   # 包装成私有技能进目标 agent
 | agent 形态 | 目录形式 `agents/<name>/`,入口固定 `agent.md` |
 | include 机制 | frontmatter `include: [...]` 拼入 system prompt(显式) |
 | 通用小能力 | 做成**全局代码工具**,不做成技能 |
-| 存放位置 | 3 处:包内置 `qi_agent/builtin/agents/` + `~/.qi/agent/agents/` + `<项目>/.qi/agents/`;无 env 层 |
+| 存放位置 | 3 处:包内置 `qi_agent/builtin/agents/` + `~/.qi/agent/agents/` + `<cwd>/.qi/agents/`;无 env 层 |
 | 覆盖规则 | 项目 > 用户 > 内置(静默覆盖,不警告);同层重复报错 |
 | 目录命名 | 隐藏目录 `.qi`(全局 `~/.qi`,项目 `.qi`),对齐 pi 的 `.pi` |
 | 内置内容 | 内置 1 个 `general` 兜底 agent(零配置可执行的前提);**不内置技能**;示例放 `examples/agents/`,不自动加载 |
@@ -289,7 +290,7 @@ qi agents import skill:path/to/skill   # 包装成私有技能进目标 agent
 | 无内置技能 | 撤销"内置技能覆盖"问题(H4 moot) |
 | opening 字段 | v1 补充:message(agent 开场白,进会话历史)+ suggestions(UI 层快捷提问,不进历史) |
 | 执行参数 | model / temperature 不进 agent.md;模型归 `models.json` + `settings.json`。轮次不是字段而是**谓词**:`RunnerSettings.stop_after`(pi 的 `shouldStopAfterTurn` 同形,默认 `None` = 不限),**qi 自己不传**(同 pi 定义了却不实现)。请求级超时/重试也不在 agent 层:归 provider SDK(`settings.json` 的 `retry.provider`,见 [settings.md](../docs/settings.md)) |
-| MCP | **v1**:私有 mcp.json 仅本 agent 自动绑定;全局(`~/.qi/agent/mcp.json`)+ 项目(`<git根>/.qi/mcp.json`)两张声明表按 `mcp_servers` 声明绑定,**默认无、显式声明**(凭证敏感);同名项目覆盖全局;凭证仅 env 引用 |
+| MCP | **v1**:私有 mcp.json 仅本 agent 自动绑定;全局(`~/.qi/agent/mcp.json`)+ 项目(`<cwd>/.qi/mcp.json`)两张声明表按 `mcp_servers` 声明绑定,**默认无、显式声明**(凭证敏感);同名项目覆盖全局;凭证仅 env 引用 |
 | 数据源 | 实例在 agent 目录 data_sources.json(私有自动绑定,凭证 env);工具/type 能力由 db 插件提供,装载门控见 [plugins.md](plugins.md) |
 | 导入/导出 | agent 自包含目录;import = 拷贝 + 复用装载校验器预检 + 明文凭证扫描;export 产物可直接 import |
 

{qi_coding_agent-0.2.1 → 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.2.1 → qi_coding_agent-0.4.0}/design/extensions-design.md

@@ -228,7 +228,7 @@ tools = await api.resolveTools("mcp_servers", scope=role_dir)   # 新增;没人
 - **因此角色的 `tools:` 白名单支持通配**:`tools: read, grep, mcp__github__*` —— 这也是唯一让
   “角色只拿到某个 server 的工具”写得出来的办法(逐条列工具名会在 server 升级后失效)。
 
-**作用域三层**(沿用 v1,勿改):全局 `~/.qi/agent/mcp.json` → 项目 `<git 根>/.qi/mcp.json`
+**作用域三层**(沿用 v1,勿改):全局 `~/.qi/agent/mcp.json` → 项目 `<cwd>/.qi/mcp.json`
 (同名覆盖全局)→ **agent 私有** `<agent 目录>/mcp.json`(自动绑定,只本角色可见)。
 
 **边界澄清(易混,写下来免得绕回去)** —— 分工不是“谁读那个文件”,而是**“谁知道 `mcp.json`

{qi_coding_agent-0.2.1 → qi_coding_agent-0.4.0}/design/internals.md

@@ -15,7 +15,7 @@
   有 `bash`/`powershell` 但没有 `grep`/`find`/`ls` 时给"用 shell 做文件操作",措辞分三种)。
 - 基座来源解析:`loader.resolve_base_prompt()` → `("", "builtin")` 表示用代码内默认;
   项目 > 用户 > 内置,**取第一个非空文件**(空文件/读失败视为未配置)。
-- 项目上下文:`paths.project_context_ancestors()`(全局 + 祖先链,止于 git 根,按路径去重),
+- 项目上下文:`paths.context_file_ancestors()`(全局 + 祖先链,**走到文件系统根**,按路径去重),
   每级目录按 `AGENTS.override.md > AGENTS.md > AGENTS.MD > CLAUDE.md > CLAUDE.MD` 取第一个命中。
 - 技能块:只给 name / description / location 的 XML;有 `read` 就说"用 read 读全文",只有 `bash` 就说 bash;
   两者都没有 → 整块不注入。相对路径以 SKILL.md 所在目录为基准解析,并在工具命令里用绝对路径。
@@ -34,7 +34,7 @@
 | `APPEND_SYSTEM.md` | 不实现;追加走 `--append-system-prompt` 或写进 `SYSTEM.md` |
 | 空文件 | 视为未配置,继续向下找;不产生空基座 |
 | 工具清单 | 列**解析后**的工具集(模型可调用全集);不写"你可能还有其他工具" |
-| 项目上下文 | 候选顺序 + 全局/祖先链 + 止于 git 根;空文件跳过;**不需要项目信任** |
+| 项目上下文 | 候选顺序 + 全局/祖先链 + 走到文件系统根;空文件跳过;**不需要项目信任** |
 | 技能注入 | XML(含 location);无 `read`/`bash` 则整块不注入 |
 | 自身文档索引 | 由 `docs.json` 生成;两处目录都找不到就整块不注入 |
 | 模板化 | 不做 `{{cwd}}` 之类占位符;动态块由代码追加 |

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

@@ -41,8 +41,8 @@ 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/` → `<项目>/.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 位置 | **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` / `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) |
@@ -79,7 +79,7 @@ core 移除:core 只认 `RunSpec`,而且 `AgentRunner` **不再自己拼 prompt*
 
 ## 4. 目录布局(运行时)
 
-全局侧比项目侧深一层,与 pi 同构:`~/.pi/agent/` ↔ `<项目>/.pi/`。全部用户级状态都挂在 `agent/` 下,
+全局侧比项目侧深一层,与 pi 同构:`~/.pi/agent/` ↔ `<cwd>/.pi/`。全部用户级状态都挂在 `agent/` 下,
 `~/.qi` 本身只是名字空间外壳(`QI_CONFIG_DIR` 可改)。
 
 ```text
@@ -96,7 +96,7 @@ core 移除:core 只认 `RunSpec`,而且 `AgentRunner` **不再自己拼 prompt*
     ├── mcp.json            # 全局 MCP 声明    —— 读它的扩展:qi-mcp
     └── sessions/*.jsonl    # 会话
 
-<项目>/.qi/                 # 项目级(扁平;与 ~/.qi/agent 配对)
+<cwd>/.qi/                 # 项目级 = **当前目录**(对齐 pi 的 `<cwd>/.pi/`;扁平,与 ~/.qi/agent 配对)
 ├── settings.json           # 覆盖全局(深合并;数组整体替换)
 ├── models.json
 ├── skills/  agents/  extensions/
@@ -110,7 +110,7 @@ core 移除:core 只认 `RunSpec`,而且 `AgentRunner` **不再自己拼 prompt*
 > `agent/` 与 `extensions/`,只在目标不存在时搬,绝不覆盖。
 >
 > 提示词的两个入口不要混:`SYSTEM.md` **整体替换**默认基座(项目 > 全局 > 代码内默认);
-> `AGENTS.md` / `CLAUDE.md`(全局 `~/.qi/agent/` + 项目根及各级祖先,止于 git 根)则作为
+> `AGENTS.md` / `CLAUDE.md`(全局 `~/.qi/agent/` + cwd 及各级祖先,走到文件系统根)则作为
 > `<project_context>` **追加**。两者与角色层、技能、工作目录的推出顺序见
 > [configuration.md](../docs/configuration.md)。
 

{qi_coding_agent-0.2.1 → 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) 因此不描述不存在的机制)。
@@ -132,7 +137,7 @@ qi 在这一层**刻意与 pi 保持一致**:字段名、命令名、`/tree` 语
 | | pi | qi |
 | --- | --- | --- |
 | 发现规则 | `~/.agents/skills` + 项目 `.agents/skills`(递归、含 SKILL.md 即技能) | 同构(第 1、4 层) |
-| 私有层 | 无 | **多 4 层**:`~/.qi/agent/skills`、`<git根>/.qi/skills`、以及两侧 `settings.skills[]` |
+| 私有层 | 无 | **多 4 层**:`~/.qi/agent/skills`、`<cwd>/.qi/skills`、以及两侧 `settings.skills[]` |
 | 注入方式 | `<available_skills>` + 渐进披露 | 同(共用同一形态) |
 | `--skill` / `--no-skills` | 有 | 同,且组合语义一致(`--no-skills` 不影响 `--skill`) |
 | 同层同名 | 报错 | 同 |
@@ -150,10 +155,10 @@ pi 里其实是两个正交概念:编译进 dist 的**默认 prompt**(代码内
 | | pi 0.85.1 | qi v2 |
 | --- | --- | --- |
 | 默认基座 | 代码内字符串 + 运行时拼接 | `src/qi_agent/system_prompt.py`(同样代码内) |
-| 覆盖 | `SYSTEM.md` **整体替换**默认 prompt | 同左(`<项目>/.qi/SYSTEM.md` > `~/.qi/agent/SYSTEM.md`) |
+| 覆盖 | `SYSTEM.md` **整体替换**默认 prompt | 同左(`<cwd>/.qi/SYSTEM.md` > `~/.qi/agent/SYSTEM.md`) |
 | 追加 | `APPEND_SYSTEM.md` | **不实现**(v1 决策保留;需要时用 `SYSTEM.md` 写全;命令行侧有 `--append-system-prompt`) |
 | 动态块 | 工具清单、条件化 guidelines、`<project_context>`、`<available_skills>`、cwd | 同左;v1 还多过**数据源清单**与**角色层**两项 qi 独有内容,两者随 P-E4c 移出 core(角色层现由 qi-agents 经 `before_agent_start` 注入) |
-| 祖先链边界 | 走到文件系统根 | 止于 **git 根**(与 `.agents/skills` 的继承范围一致) |
+| 祖先链边界 | 走到文件系统根 | **走到文件系统根**(与 pi 一致;`.agents/skills` 那条另止于 git 根) |
 | 自身文档索引 | README/docs/examples 绝对路径 + 12 条指路 | 从 `docs/docs.json` 的 navigation 生成(见 [configuration.md](../docs/configuration.md)) |
 
 ## 10. 开发与测试(原 `development.md` §7)
@@ -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/` ↔ `<项目>/.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 一致」 |

{qi_coding_agent-0.2.1 → qi_coding_agent-0.4.0}/design/plugins.md

@@ -16,7 +16,7 @@
 | 通道 | 怎么装 | 装到哪 | 发现机制 | 场景 |
 | --- | --- | --- | --- | --- |
 | **pip 包** | `qi install qi-db-tools`(PyPI / git / 本地) | venv 的 site-packages(环境级) | **entry point 扫描**(`importlib.metadata`,启动时自动发现) | 分发、团队共享、锁依赖 |
-| **本地目录** | 手动放置/复制源码目录 | `~/.qi/plugins/<name>/`(全局)或 `<项目>/.qi/plugins/<name>/`(项目,需信任) | **目录扫描** | 未发布/私有/本地开发,拷贝即用 |
+| **本地目录** | 手动放置/复制源码目录 | `~/.qi/plugins/<name>/`(全局)或 `<cwd>/.qi/plugins/<name>/`(项目,需信任) | **目录扫描** | 未发布/私有/本地开发,拷贝即用 |
 
 pip 包通过 **entry point** 声明(对齐 pytest/uvicorn 模式),无需维护安装清单: