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

qi_agent/docs/compaction.md

@@ -0,0 +1,148 @@
+# 上下文压缩
+
+长会话迟早会超出模型窗口。qi 把「太久以前的部分」压成一段**结构化摘要**再继续跑 —— 不是丢弃,
+也不是简单截断。
+
+两种机制共用同一套摘要格式与同一条 LLM 调用路径:
+
+| 机制 | 触发 | 压什么 | 落成 |
+| --- | --- | --- | --- |
+| **压缩** compaction | 上下文超阈值,或用户 `/compact` | 旧消息 | `type=compaction` entry(+ `firstKeptEntryId`) |
+| **分支摘要** branch summary | `/tree` 跳到别的分支 | 「被放弃的那段」 | `type=branch_summary` entry |
+
+**事实源:`src/qi_agent/compaction.py` + `runtime.py` 的 `_history()` / `_maybe_auto_compact()`。**
+
+## 1. 什么时候自动压
+
+开新一回合**之前**检查一次(`_maybe_auto_compact`):
+
+```text
+tokens > contextWindow - reserveTokens        →  压
+```
+
+- **`reserveTokens` 是留给模型回答的余量**(默认 16384),所以阈值不是窗口本身。
+- **预算口径是"重建后的上下文 + 基座提示词",不是原始 entry 之和**:
+  `messages_tokens(_history(session)) + estimate_tokens(base_prompt)`。
+  用原始 entry 求和会把**已经压掉的内容再算一遍** —— 于是压完还超,反复压。
+- `contextWindow` 来自当前模型的 spec;拿不到窗口(`<= 0`)或 `compaction.enabled=false` 就整段跳过。
+
+相关设置(`settings.json` 的 `compaction`,见 [settings.md](settings.md)):
+
+| 键 | 默认 | 说明 |
+| --- | --- | --- |
+| `enabled` | `true` | 关掉后不再自动压(手动 `/compact` 仍可用) |
+| `reserveTokens` | `16384` | 给回答留的余量 |
+| `keepRecentTokens` | `20000` | 压完之后**至少保留**的近期内容 |
+
+非法值(非正整数)一律**回落到默认**,不报错 —— 一个写错的数字不该让会话跑不起来。
+
+## 2. 压什么、留什么:切点规则
+
+从**最新往回**累加 token,累到 `keepRecentTokens` 时把切点放在**不早于**该位置的最近一个合法切点。
+合法切点是:
+
+- `user` / `assistant` 消息
+- `compaction` / `branch_summary` entry
+
+**绝不在工具结果上切** —— 工具结果必须跟在它的调用后面,切在那里会让模型看到一次没有调用的结果。
+
+配套的一个细节:切点会**向前吞掉相邻的不进上下文的 entry**(旧 `dispatch`、叙述、思考),让切点更贴近
+预算。但工具结果虽然也不进上下文,**不属于可吞的元数据** —— 吞掉它等于把切点挪到工具结果上。
+
+### 单个 turn 就超预算:split turn
+
+如果切点落在一个 turn 中间(前面还有 `user` 消息),说明**这一个回合本身就超了预算**。这时做
+**split turn**:
+
+1. 历史部分照常摘要;
+2. 这个 turn 的**前缀**(从 turn 起点到切点)单独摘要一次;
+3. 两段用 `**Turn Context (split turn):**` 分隔后拼成一条摘要。
+
+好处是模型不会看到"半个回合"——要么整段都在摘要里,要么整段都还在上下文里。
+
+## 3. 摘要长什么样
+
+固定 7 段的结构化格式(`SUMMARIZATION_PROMPT`):`Goal` · `Constraints & Preferences` · `Progress`
+(`Done`/`In Progress`/`Blocked`)· `Key Decisions` · `Next Steps` · `Critical Context`。
+
+提示词里两条硬要求:**保持每段简洁**、**原样保留文件路径 / 函数名 / 错误信息**。
+
+**第二次之后的压缩用 `UPDATE_SUMMARIZATION_PROMPT`**:它要求保留旧摘要里的全部信息,只增改
+(把 `In Progress` 里完成的挪进 `Done`、更新 `Next Steps`)。否则每次压缩都会把更早的决策洗掉 ——
+长会话跑到第十次压缩时,模型就不知道最初的目标了。
+
+摘要调用本身也是**一次普通 LLM 调用**,但:
+
+- 用 `system` 提示词明确禁止"接着对话"(否则模型会把摘要写成回答);
+- 会话内容用 `<conversation>` 包裹、旧摘要用 `<previous-summary>` 包裹;
+- **模型试图调用工具就直接报错**(`RuntimeError`):摘要请求必须是一次纯文本输出。
+
+## 4. 摘要怎么回到上下文
+
+`_history()` 的装配规则:
+
+```text
+[system 提示词]
+[上下文已压缩] <summary> [摘要结束,以下是其后的消息]     ← 用 user 角色,不是 system
+从 firstKeptEntryId 开始的消息 …
+沿途的 branch_summary(用「另一条分支的摘要」标签)
+```
+
+三个刻意的选择:
+
+1. **摘要包成 `user` 消息而不是 `system`**:各 provider 对"多个 system"支持不一,而摘要本来就是
+   "过去那段对话"的替身。
+2. **切点由落盘的 `firstKeptEntryId` 决定,不由摘要文本决定**。摘要只负责"讲清楚",保留范围是数据,
+   所以压缩后不会因为模型摘要写得长短而改变窗口。
+3. **没压过时退回「最近 40 条」的简易窗口**。那是压缩接管窗口之前的旧行为;一旦有过压缩,窗口就
+   完全由摘要 + 切点决定。
+
+## 5. 落盘的 entry
+
+```jsonc
+// 压缩
+{"type":"compaction","summary":"…","firstKeptEntryId":"a1b2c3d4e5f6",
+ "tokensBefore":41230,"usage":{…}}
+
+// 分支摘要
+{"type":"branch_summary","summary":"…","fromId":"…","usage":{…}}
+```
+
+`tokensBefore` 是**压缩前**的估算值(前端用它显示"从多少压到多少")。字段全集见
+[session-format.md](session-format.md) §5。
+
+`compact_session()` 在**没什么可压时返回 `None`**,调用方据此提示用户,而不是硬写一条空摘要。
+同一分支上已经压过一次、之后没有任何新内容时也返回 `None`(避免连点两次 `/compact` 压出两条)。
+
+## 6. 分支摘要:`/tree` 跳分支时
+
+`/tree` 跳到旧节点继续时,原来那条分支上的内容会离开上下文。为了让"切回来"之后不丢,qi 把
+**被放弃的那段**压成一条 `branch_summary`,挂到跳过去的位置下:
+
+- 要摘要的范围 = 从 `from_id` **沿 parentId 往回走到共同祖先(不含祖先)**;
+- 只收"会进上下文"的 entry(`is_context_entry`:消息、压缩、分支摘要);
+- **必须在移动 `position` 之前**取好源分支(移完再取拿到的就是目标分支,摘要会静默变成空);
+- 先 `set_position(目标)` 再 `append(摘要)`,于是新 leaf 就是这条摘要。
+
+## 7. 失败与边界
+
+| 情况 | 行为 |
+| --- | --- |
+| 自动压缩失败(模型报错/超时) | **不卡住这一轮**:发一个 error 事件后继续跑。压缩是优化,不是前置条件 |
+| 没什么可压 | `compact_session()` 返回 `None`,前端提示"没有可压缩的内容" |
+| 老 entry 没有 `id` | 不给 id 就没法被 `firstKeptEntryId` 引用 → 直接不压(不猜) |
+| 摘要模型试图调工具 | 抛错(见 §3) |
+| `settings.compaction` 值非法 | 回落到默认,不报错 |
+
+## 8. 扩展能干预压缩吗
+
+能,三个事件(见 [extensions.md](extensions.md) §4)。压缩**只有一个入口**
+(`QiRuntime.compact_session`:TUI 的 `/compact` 与自动压缩都走它),所以三个事件都在那一处发:
+
+| 事件 | 时机 | 契约 |
+| --- | --- | --- |
+| `session_before_compact` | 已经算出怎么切、还没调模型 | `{cancel: true}` 拦下这次压缩;或 `{summary: "…"}` 自带摘要 —— **自带时不调模型**(扩展可能比模型更清楚该记住什么) |
+| `session_compact` | 成功落盘后 | `{entry, summary, provided}`(`provided=true` 表示摘要是扩展给的) |
+| `session_compact_failed` | 摘要调用/落盘失败 | `{error}` —— **先发事件,再把异常抛给调用方**(失败必须传出去,但扩展也该看得见) |
+
+handler 抛异常不影响压缩本身:记一条 note 后继续(与其它事件同一条规矩)。

qi_agent/docs/configuration.md

@@ -0,0 +1,89 @@
+# 配置:qi 目录与上下文文件
+
+qi 的配置分**用户级**与**项目级**两层。
+
+- 用户级 = **agent 目录**,默认 `~/.qi/agent`(`QI_AGENT_HOME` 可改),所有用户级状态都挂在这里。
+- 项目级 = 工作目录下的 `.qi/`,跟仓库走、可提交共享。
+
+项目级**扩展**要过[项目信任](security.md)才加载;`settings.json` 的普通字段(`sessionDir`、`theme`、
+`defaultTools`…)与文本指令(`AGENTS.md`、技能)**不受门控**。
+
+改完手动编辑的文件(设置、指令、资源)后,在 TUI 里 `/reload` 一次。
+
+## agent 目录(用户级)
+
+下表里写成 `<agent-dir>`:
+
+| 路径 | 职责 |
+| --- | --- |
+| `<agent-dir>/settings.json` | 用户级[设置](settings.md):偏好、默认值、资源路径、扩展声明(`packages`) |
+| `<agent-dir>/models.json` | provider 与模型定义、`apiKey` 引用 → [models.md](models.md) |
+| `<agent-dir>/auth.json` | 凭证(0600,按 provider)→ [providers.md](providers.md) |
+| `<agent-dir>/trust.json` | 按目录记住的信任决定(`/trust` 写它) |
+| `<agent-dir>/sessions/` | 会话 JSONL(`settings.sessionDir` 可改)→ [sessions.md](sessions.md) |
+| `<agent-dir>/skills/` | 用户级[技能](skills.md) |
+| `<agent-dir>/extensions/` | 用户级[扩展](extensions.md),一目录一个扩展 |
+| `<agent-dir>/SYSTEM.md` | **整体替换**默认基座(见下) |
+| `<agent-dir>/AGENTS.md`(或 `AGENTS.override.md` / `CLAUDE.md`) | 跨工作目录的用户指令 |
+| `<agent-dir>/agents/`、`<agent-dir>/mcp.json` | **官方扩展自己的目录**:角色(qi-agents)与 MCP server(qi-mcp)—— 没装对应扩展就是普通目录 |
+
+## 项目 `.qi` 目录
+
+| 路径 | 职责 |
+| --- | --- |
+| `.qi/settings.json` | 项目级设置(键级深合并覆盖用户级) |
+| `.qi/models.json` | 项目级 provider / 模型定义(优先于用户级) |
+| `.qi/SYSTEM.md` | **整体替换**本项目里的基座 |
+| `.qi/extensions/` | 项目级扩展(**信任后才加载**) |
+| `.qi/skills/` | 项目级技能 |
+| `.qi/agents/`、`.qi/mcp.json` | 同上:官方扩展自己的目录与声明 |
+
+`SYSTEM.md` 有项目级就用项目级(同名文件**不合并**)。
+
+## 上下文文件
+
+上下文文件与 `.qi/` 配置是两回事:qi 从 **agent 目录**、**工作目录**以及**它的祖先目录**里找,
+在某个目录或其子目录里跑都生效。每级目录按候选顺序取**第一个**命中:
+
+```text
+AGENTS.override.md > AGENTS.md > AGENTS.MD > CLAUDE.md > CLAUDE.MD
+```
+
+顺序 = 用户级 → 项目祖先链**由远到近**(含 cwd),按路径去重;祖先链**止于 git 根**。
+`AGENTS.override.md` 只在**同一目录**里顶替 `AGENTS.md` / `CLAUDE.md`,不会压掉其它目录的。
+空文件视为未配置。上下文文件的发现**不需要项目信任**。
+
+注入位置在 `<project_context>` 块里,是系统提示词的一部分(见 [how-qi-works.md](how-qi-works.md))。
+
+## 换掉或追加系统提示词
+
+| 入口 | 语义 | 落盘 |
+| --- | --- | --- |
+| `.qi/SYSTEM.md` / `<agent-dir>/SYSTEM.md` | **整体替换**基座(项目 > 用户) | 是(仓库 / 用户文件) |
+| `qi --system-prompt "<文本\|文件>"` | **整体替换**基座(只本次运行) | 否 |
+| `qi --append-system-prompt "<文本\|文件>"` | **追加**到每回合提示词末尾(可重复) | 否 |
+| 扩展的 `before_agent_start` | 改 `system_prompt`(链式) | 否 |
+
+**副作用**:默认基座里的「可用工具」「指南」两块跟基座绑在一起,写了 `SYSTEM.md` 就等于接管基座、
+那两块不再出现。写自定义基座时请自己交代工具约定,例如:
+
+```markdown
+你是本仓库(订单服务)的开发助手。
+
+可用工具:`read` / `ls` / `find` / `grep` / `edit` / `write` / `bash` / `clarify`。
+- `bash` 不做命令级过滤,行为由本仓库约定约束。
+- 需求不明确时先用 `clarify` 提问。
+
+## 本仓库环境
+- 跑测试:`uv run pytest -q`
+- 数据库迁移在 `migrations/`,只允许新增文件。
+```
+
+**动态块不受影响**:项目上下文、技能清单、手册索引、工作目录照旧追加 —— 不是"整条提示词只剩你的文件"。
+(实现细节见 [design/internals.md](../design/internals.md)。)
+
+## qi 没有的配置项
+
+- **prompt 模板**:qi 不做可复用提示词模板;要固定前缀就写进 `SYSTEM.md`,或做成技能。
+- **键位配置文件**:qi 没有 `keybindings.json`;键位固定,扩展可用 `register_shortcut` 加自己的。见 [keybindings.md](keybindings.md)。
+- **用户主题目录**:只有内置 `dark` / `light`,`theme` 只认这三个值(`auto` 是探测)。见 [themes.md](themes.md)。

qi_agent/docs/containerization.md

@@ -0,0 +1,80 @@
+# 隔离运行(容器 / VM)
+
+qi **不做进程内沙箱**:`bash` 能跑任何东西,文件工具只是"相对路径基于会话 cwd"的约定。
+工具与扩展都以 qi 进程本身的权限运行(见 [security.md](security.md))。所以**真边界必须来自 qi 之外**。
+
+需要隔离的典型场景:
+
+- 无人值守地跑(`-p` / `--mode json` 喂给 CI),没人盯着它按 `escape`;
+- 让 qi 碰不信任的仓库 —— 里面可能有 `.qi/extensions/`(`-na` 只挡加载,不挡 `bash`);
+- 把 qi 暴露给别的机器或别的用户。
+
+## 选一条隔离路线
+
+| 路线 | 得到什么 | 代价 |
+| --- | --- | --- |
+| **容器**(Docker / Podman) | 文件系统与进程隔离;工作目录按需挂载 | 要自己搭镜像与挂载;凭证得想办法传进去 |
+| **VM** | 与宿主机完全隔离(内核级) | 重、启动慢,适合长期跑或跑高风险任务 |
+| **受限用户 + 只读挂载** | 便宜:换个没有权限的用户跑,仓库只读挂 | 同一内核,隔离弱于容器 |
+| **远端机器 / 一次性实例** | 物理隔离 | 要同步代码与密钥 |
+
+**共同原则**:只把**要干活的目录**放进去;**凭证走运行时注入**(环境变量 / 只读挂载),不要烤进镜像;
+`~/.qi/agent/`(会话、trust、auth)单独挂一个卷,否则每次重建都会丢历史。
+
+## 容器示例
+
+qi 目前**没有发布到 PyPI**(见 [quickstart.md](quickstart.md)),所以镜像是"把仓库放进去装一遍":
+
+```dockerfile
+FROM python:3.12-slim
+RUN apt-get update && apt-get install -y --no-install-recommends git bash \
+    && rm -rf /var/lib/apt/lists/*
+RUN pip install --no-cache-dir uv
+
+WORKDIR /opt/qi
+COPY . /opt/qi
+RUN uv sync --no-dev && ln -s /opt/qi/.venv/bin/qi /usr/local/bin/qi
+
+# 工作目录由运行时挂载进来;agent 目录单独挂卷(会话与 trust 都在这)
+VOLUME ["/root/.qi/agent"]
+WORKDIR /workspace
+ENTRYPOINT ["qi"]
+```
+
+```bash
+docker build -t qi-local .
+docker run --rm -it \
+  -v "$PWD:/workspace" \
+  -v qi-home:/root/.qi/agent \
+  -e DEEPSEEK_API_KEY="$DEEPSEEK_API_KEY" \
+  qi-local
+```
+
+要点:
+
+- **凭证只从环境变量进**(或把 `auth.json` 只读挂载进去),不要 `COPY` 进镜像层 —— 镜像层会被推送、缓存。
+- **工作目录挂载的是宿主机的仓库**,所以 qi 的写操作会真的落到宿主机上;要更安全就挂 `:ro` 再把可写区
+  单独挂成临时目录。
+- **`~/.qi/agent/` 用卷**:会话历史、`trust.json`、agent 级设置都在里面;不挂就每次重建。
+- 想跑无头:`docker run --rm -v "$PWD:/workspace" qi-local -p "把 CHANGELOG 里最近 10 条整理成一句话"`。
+
+## 只读工作目录 + 可写输出目录
+
+只想让它**看**代码、把结果写到别处:
+
+```bash
+docker run --rm -v "$PWD:/workspace:ro" -v "$PWD/out:/out" -w /out qi-local -p "审查 /workspace/src"
+```
+
+文件工具的越界检查只覆盖 `read` / `ls` / `find` / `grep` / `write` / `edit`,而 `bash` 不受限 ——
+所以**只读挂载是这里唯一真正的保证**,不是提示词。
+
+## 网络
+
+qi 只需要能连到模型 provider。要收紧就在容器/防火墙层限制出网;qi 没有内置的网络开关
+(`--offline` 被接受但不做任何事,因为启动期本来就没有网络操作)。
+
+## 与其它页面的关系
+
+- [security.md](security.md):有哪些闸门、哪些地方没有闸门;信任门控挡什么。
+- [bash-allowlist.md](../design/bash-allowlist.md):为什么不做命令白名单(以及它为什么不是边界)。

qi_agent/docs/docs.json

@@ -0,0 +1 @@
+{"_note":["qi 的文档导航清单,形状对齐 pi 的 docs/docs.json(navigation + redirects),可以直接被文档站消费。","navigation = 已验证存在的文档(每条 path 都必须在 docs/ 下真实存在);分组照 pi 的三段式:开始 / 指南(运行 · 定制 · 构建)/ 参考。","planned = qi 增补字段(pi 无),是补齐文档的施工清单:补完一篇,就把该条从 planned 移进 navigation 的对应分类。","planned[].source_of_truth = 写这篇时必须对照的唯一事实来源;不照它写就会产生『文档写了、代码没做』的行为不一致。","planned[].blocker = 非空表示这篇现在**不许写**:功能本身还没实现,先改代码或先撤掉承诺。"],"navigation":[{"title":"开始","items":[{"title":"文档索引","path":"index.md"},{"title":"快速开始","path":"quickstart.md"},{"title":"qi 是怎么工作的","path":"how-qi-works.md"}]},{"title":"指南","items":[{"title":"运行 qi","items":[{"title":"在终端里用 qi","path":"usage.md"},{"title":"选一个模型","path":"models.md"},{"title":"会话与上下文","path":"sessions.md"},{"title":"安全地运行","path":"security.md"},{"title":"隔离运行(容器 / VM)","path":"containerization.md"}]},{"title":"定制 qi","items":[{"title":"配置:qi 目录与上下文文件","path":"configuration.md"},{"title":"技能","path":"skills.md"},{"title":"主题","path":"themes.md"},{"title":"扩展的安装与声明","path":"packages.md"}]},{"title":"构建于 qi","items":[{"title":"写扩展","path":"extensions.md"},{"title":"终端 UI 组件","path":"tui.md"}]}]},{"title":"参考","items":[{"title":"命令行","path":"cli.md"},{"title":"斜杠命令","path":"slash-commands.md"},{"title":"设置(settings.json)","path":"settings.md"},{"title":"环境变量","path":"environment-variables.md"},{"title":"键位","path":"keybindings.md"},{"title":"供应商与凭证","path":"providers.md"},{"title":"会话文件格式","path":"session-format.md"},{"title":"上下文压缩","path":"compaction.md"},{"title":"JSON 事件流","path":"json.md"}]}],"redirects":[{"from":"PLAN.md","to":"../design/PLAN.md"},{"from":"web.md","to":"../design/web.md"},{"from":"plugins.md","to":"../design/plugins.md"},{"from":"dispatcher.md","to":"../design/dispatcher.md"},{"from":"bash-allowlist.md","to":"../design/bash-allowlist.md"},{"from":"tools.md","to":"how-qi-works.md"},{"from":"system-prompt.md","to":"configuration.md"},{"from":"model-config.md","to":"models.md"},{"from":"development.md","to":"../design/development.md"}],"planned":[],"excluded":[{"pi":"prompt-templates.md","reason":"qi 没有 prompt 模板功能(grep promptPaths/prompt_dir 零命中)。要么做,要么不写。"},{"pi":"sdk.md","reason":"qi 没有 createAgentSession 式公开 SDK;等价面是扩展 API,见 docs/extensions.md。"},{"pi":"rpc.md / rpc-commands.md / rpc-extension-ui.md / cli-integration.md","reason":"qi 没有 stdio RPC 模式(--mode 只有 text|json),也没有多语言 SDK;程序化使用只有 JSON 事件流(docs/json.md)。"},{"pi":"message-types.md","reason":"qi 的消息/entry 类型表在 docs/session-format.md §5,不单开一页。"},{"pi":"custom-provider.md","reason":"自定义 provider 在 qi 走 models.json 的 provider 段 + 扩展的 register_provider,已有专页覆盖(docs/models.md、docs/extensions.md)。"},{"pi":"windows.md / termux.md / tmux.md / terminal-setup.md / shell-aliases.md","reason":"平台与外部工具集成,qi 不做;真隔离路线见 docs/containerization.md。"},{"pi":"llama-cpp.md","reason":"本地模型由 docs/models.md 的『连接本地模型』覆盖,不做专用路由器集成。"}]}

qi_agent/docs/environment-variables.md

@@ -0,0 +1,47 @@
+# 环境变量
+
+分三类:**qi 自己的配置变量**、**qi 注入给 shell 工具子进程的会话变量**,以及**各 provider 的凭证变量**
+(后者在 [providers.md](providers.md))。
+
+## qi 的配置变量
+
+| 变量 | 作用 |
+| --- | --- |
+| `QI_AGENT_HOME` | **agent 目录本身**(默认 `~/.qi/agent`)。全部用户级状态的挂载点:`settings.json` / `models.json` / `auth.json` / `sessions/` / `skills/` / `extensions/` / `trust.json` |
+| `QI_CONFIG_DIR` | 名字空间根(默认 `~/.qi`)。仅用于推导默认路径与旧布局迁移 |
+| `QI_AGENT_CONFIG` | **直接指定 `models.json` 文件**(优先于项目 / 全局路径) |
+| `QI_THEME` | `dark` / `light` / `auto`,覆盖 `settings.theme` → [themes.md](themes.md) |
+
+> `QI_AGENT_HOME` 指向的是**目录本身**,不是它的父目录 —— 拿它去拼 `agent/settings.json` 会得到
+> `…/agent/agent/settings.json`。这是这个变量最常见的误用。
+
+`models.json` 的完整查找顺序是 `QI_AGENT_CONFIG` → `<项目>/.qi/models.json` → `~/.qi/agent/models.json`,
+见 [models.md](models.md)。
+
+## 注入给 shell 工具的会话变量
+
+`bash` 与 `powershell` 的**子进程**(以及它们拉起的命令)会拿到这五个:
+
+| 变量 | 值 |
+| --- | --- |
+| `QI_SESSION_ID` | 当前会话 id |
+| `QI_SESSION_FILE` | 会话 JSONL 的绝对路径 |
+| `QI_PROVIDER` / `QI_MODEL` | 当前模型(子运行里是**子运行自己的**模型) |
+| `QI_REASONING_LEVEL` | 当前思考级别 |
+
+**为什么需要**:换模型是**界面状态**,不作为消息进对话 —— 所以 agent 无从"感知"切换动作,
+`env | grep QI_` 是它唯一能**自证**"我现在跑的是什么"的通道(同一条也写进了 bash 的
+prompt guidelines)。
+
+两条约定:
+
+- 注入前**先删掉**这五个键再填 —— 否则子运行里跑的 bash 会继承父的值。
+- 取不到的字段**不设**,而不是设成空串(空串会被读成"设过了,值是空的")。
+
+它们**只注入子进程**,不改变 qi 自己进程的环境。
+
+## provider 凭证变量
+
+`DEEPSEEK_API_KEY`、`OPENAI_API_KEY`、`ANTHROPIC_API_KEY` 这类**约定变量**由 provider 名推导,
+是凭证解析的第 2 顺位(优先于 `models.json` 的 `apiKey`,低于 auth store)。完整表与排查口径见
+[providers.md](providers.md)。