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

qi_agent/docs/skills.md

@@ -0,0 +1,124 @@
+# 技能
+
+技能是**按需加载的能力说明**:一个目录 + 一份 `SKILL.md`。它的正文**不进系统提示词** —— 提示词里
+只放名字、描述与位置,模型在任务匹配时再用 `read` 去读全文。这叫**渐进披露**:一个技能占提示词的
+成本是两三行,而不是一整篇。
+
+`SKILL.md` 用 YAML frontmatter 开头:
+
+```markdown
+---
+name: code-review-checklist
+description: 审代码时按这份清单逐项检查;涉及并发、错误处理与测试覆盖时使用。
+---
+
+（正文:具体怎么做。可以很长。）
+```
+
+| frontmatter 字段 | 必需 | 说明 |
+| --- | --- | --- |
+| `description` | **是** | **没有 description 的技能不会被装载**(静默跳过,不是报错) |
+| `name` | 否 | 缺省时用目录名(`SKILL.md` 所在目录)或文件名(根级 `*.md` 的 stem) |
+
+**事实源:`src/qi_agent/loader.py`(发现与冲突)+ `src/qi_agent/system_prompt.py`(注入)。**
+
+## 1. 放哪里:六层来源
+
+按**优先级从低到高**排;同名时高的覆盖低的。
+
+| # | 目录 | 层标签 | 说明 |
+| --- | --- | --- | --- |
+| 1 | `~/.agents/skills/` | `agents-global` | **跨工具**(Agent Skills 标准的 `.agents` 目录),全局共享 |
+| 2 | `~/.qi/agent/skills/` | `qi-global` | qi 私有,全局 |
+| 3 | user `settings.json` 的 `skills[]` | `settings-global` | 追加路径,相对 `~/.qi/agent` 解析 |
+| 4 | `.agents/skills/`(cwd → git 根,远→近) | `agents-project` | 跨工具,项目级 |
+| 5 | `<git根>/.qi/skills/` | `qi-project` | qi 私有,项目级 |
+| 6 | project `settings.json` 的 `skills[]` | `settings-project` | 追加路径,相对 `<git根>/.qi` 解析 |
+
+第 1、2、4、5 层的**具体目录**按"跨工具层与 qi 私有层交替"排列(跨工具的 `.agents` 与私有的
+`~/.qi` / `<git根>/.qi` 各占两层)。跨工具目录(`.agents`)与 qi 私有目录的区别不只是名字:
+**跨工具目录只认 `<name>/SKILL.md` 这种结构,不接受根目录下散着的 `*.md`**(见 §2)。
+
+两条容易踩的:
+
+- 第 3、6 层的相对路径**各按自己所在的目录解析**(user 的按 `~/.qi/agent`,project 的按
+  `<git根>/.qi`)。用合并后的配置去解析,会让一侧的路径落到另一侧的基准上。
+- 第 4、5 层是**项目级**(随仓库走)。**注意:项目级技能不受信任门控** —— 未信任的项目里
+  `.agents/skills` 与 `<git根>/.qi/skills` **仍会被装载**。这与项目级*扩展*不同:后者未信任就不扫
+  (因为扩展是可执行代码)。界线画在“可执行 vs 文本”上,而技能是文本指令。详见
+  [security.md](security.md) §2。
+
+## 2. 一个技能根的扫描规则
+
+对每个来源目录:
+
+- **含 `SKILL.md` 的目录即技能,不再向内递归** —— 也就是说技能目录里可以再放参考文件,不会
+  被误当成子技能。
+- **没有 `SKILL.md` 的子目录继续向内找** —— 支持分组目录(如 `skills/lang/python/SKILL.md`)。
+- **根目录下带 `description` 的 `*.md` 也算独立技能** —— 但**只对 qi 侧目录生效**
+  (`~/.qi/agent/skills`、`<git根>/.qi/skills`、以及 `settings.skills[]` 指定的路径与 CLI `--skill`)。
+  跨工具的 `.agents/skills` **不开**这一条,以贴合 Agent Skills 标准。子目录里散着的 `*.md`
+  一律不算。
+- 一个 `--skill` / `settings.skills[]` 条目**可以直接指向一个 `.md` 文件**,也可以指向目录。
+
+## 3. 优先级与冲突
+
+两种同名,处置**刻意不同**:
+
+| 情况 | 行为 |
+| --- | --- |
+| **同一层内**同名 | **报错**(`LoadError`),列出冲突文件。同一层出现两个同名技能,说明配置本身有问题,不猜 |
+| **跨层**同名 | **高优先级静默覆盖**,不提示。这是"项目覆盖全局"的正常用法 |
+
+覆盖发生在装载时:`merged[name]` 被替换。所以最终只有一个同名技能存在,且是优先级最高的那个。
+
+**排除项**:`settings` 的 `skills[]` 里以 `!` 或 `-` 开头的条目是排除项,作用于**整个发现集** ——
+不只是"数组里纳入的那些根"。判定方式是路径匹配:技能的 `SKILL.md` 路径等于该排除路径,**或**
+位于其下。
+
+## 4. 模型怎么看到它
+
+`system_prompt.render_skills()` 生成的块长这样:
+
+```xml
+<available_skills>
+  <skill>
+    <name>code-review-checklist</name>
+    <description>审代码时按这份清单逐项检查…</description>
+    <location>/Users/x/proj/.qi/skills/code-review-checklist/SKILL.md</location>
+  </skill>
+</available_skills>
+```
+
+三条规则:
+
+1. **只给名字、描述、位置**,正文由模型按需 `read`。描述写得准不准,直接决定模型会不会去读它 ——
+   所以 `description` 里应写清"**什么时候用**",而不只是"这是什么"。
+2. **没有能读文件的工具时(`read` / `bash` 都不在),整块不注入**。注入了也读不到,只会诱导模型
+   去调用不存在的工具。
+3. 提示词里明确要求:**`SKILL.md` 里出现相对路径时,以 `SKILL.md` 所在目录为基准解析,并在工具
+   命令里用绝对路径**。
+
+## 5. 开关
+
+| 方式 | 作用 |
+| --- | --- |
+| `qi --skill <路径>` | 追加技能(可重复,**叠加**);优先级**高于全部六层**(标签 `cli`) |
+| `qi --no-skills` / `-ns` | 关闭**自动发现**(六层全跳过),但 **`--skill` 仍然生效** |
+| `settings.json` 的 `skillsEnabled: false` | 等价于 `--no-skills`(只关发现) |
+| `settings.json` 的 `skills: [...]` | 追加来源路径(第 3 / 6 层),支持 glob、`~`、相对路径与排除项 |
+
+`--no-skills` 与 `--skill` 的组合语义是刻意的:"把自动发现的都关掉,只跑我指定的这一个" ——
+调试某个技能时最常用的姿势。
+
+## 6. 强制加载:`/skill:<名>`
+
+渐进披露的另一面是"模型不一定去读"(提示词里只有一行描述)。TUI 里可以自己把它叫起来:
+
+```text
+/skill:brave-search           # 加载并执行该技能
+/skill:pdf-tools extract      # 带参数(作为技能的入参)
+```
+
+它把 SKILL.md **全文**提交给模型,效果与用户手贴内容等价,只是不用手抄。`settings.enableSkillCommands`(默认 `true`)关掉后
+这批命令不存在。

qi_agent/docs/slash-commands.md

@@ -0,0 +1,55 @@
+# 斜杠命令
+
+TUI 里输入 `/` 会补全全部命令(内置的、扩展注册的、技能命令都在里面)。命令**在回合进行中也立即执行**
+(与 `!` bash 一样),否则 `/quit`、`/tree` 这类会按不下去。
+
+## 模型与设置
+
+| 命令 | 说明 |
+| --- | --- |
+| `/model [p/m]` | 不给参数 = 开选择器(与 `ctrl+l` 同一个);给 `p/m` 或唯一模型名 = 直接切。**只列解析得出凭证的模型**。切换会落一条 `model_change`,下次打开这条会话仍用它 |
+| `/scoped-models` | 挑 `ctrl+p` 轮换哪些模型(空 = 全部,写回 `settings.enabledModels`);已不可用的条目画删除线 + `[unavailable]`,取消勾选才移出 |
+| `/thinking` | 不给参数 = 开选择器;切换落一条 `thinking_level_change` entry,下次打开按它还原 |
+| `/settings` | 偏好面板:主题 / 思考级别 / 交互开关(`enter` 换值、`ctrl+s` 保存到**用户级** settings) |
+| `/login [provider]` | 不给 provider 先弹选择器,然后**遮罩输入** API key → 写 `auth.json`(0600)并重建客户端;key 不进 transcript。qi 的凭证层**只有 api_key**,没有订阅登录(OAuth) |
+| `/logout [provider]` | 删 `auth.json` 里那条(**环境变量与 `models.json` 的 `apiKey` 不受影响**);此后那家的模型不再进 `/model` 与 `ctrl+p` 清单 |
+
+## 会话与上下文
+
+| 命令 | 说明 |
+| --- | --- |
+| `/new` | 新会话(**不落文件** —— 与裸 `qi` 一样是预留,说话才落盘) |
+| `/resume [id]` | 不给 id = 打开会话选择器;给 id = 直接恢复 |
+| `/name <name>` | 会话显示名(进 footer)。**命名即落盘**:预留中的会话会因此立刻写出 —— 否则 `/new` / 退出会让名字连会话一起消失 |
+| `/session` | 会话信息(ID / 文件 / cwd / 消息数·仅当前分支 / 节点数与分支点 / 模型 / 用量) |
+| `/tree` | 会话树:跳到本会话任意节点继续(同文件内分支) |
+| `/fork [序号\|id]` | 从某条用户消息**之前**分叉出新会话,并把那条消息放回编辑器 |
+| `/clone [名字]` | 把当前分支复制成新会话 |
+| `/compact [提示]` | 压缩上下文:把旧消息压成结构化摘要(可给一句关注点) |
+
+## 导出与分享
+
+| 命令 | 说明 |
+| --- | --- |
+| `/export [file]` | 导出会话:`.html` → 自包含 HTML(只含当前分支),其余 → 原始 JSONL;默认 `./qi-<id>.jsonl` |
+| `/import <file>` | 从 JSONL 导入并切换会话(重名给提示,不静默覆盖) |
+| `/copy` | 复制最后一条回答到剪贴板(OSC 52) |
+| `/share` | 把当前会话传成**私有** GitHub gist(一个自包含 `.html`)并复制链接。直调 API,不依赖 `gh`;token 顺序照 qi 的凭证原则(auth store → 环境变量):`qi auth login github` → `GITHUB_TOKEN` → `GH_TOKEN` |
+
+## 运行时与项目
+
+| 命令 | 说明 |
+| --- | --- |
+| `/hotkeys` | 快捷键(哪些键位还没做也如实写明) |
+| `/reload` | 重载扩展 / 技能 / 配置(主题改动需重开) |
+| `/trust [yes\|no\|forget]` | 按**目录**记住信任决定(`~/.qi/agent/trust.json`);连带记住上一层,写完要重启才生效 |
+| `/changelog` | 显示 `CHANGELOG.md`(qi 仓库暂无该文件) |
+| `/quit` | 退出 |
+
+## 由资源注册的命令
+
+- 扩展用 `api.register_command` 注册的命令 —— 重名时都留着并变成 `name:1` / `name:2`,一个都不丢。
+- 技能注册的 **`/skill:<名> [参数]`** —— 加载并执行该技能的全文(强制加载的入口);
+  由 `settings.enableSkillCommands` 控制,默认开。见 [skills.md](skills.md)。
+
+`/quit` 与 `/hotkeys` **扩展顶不掉**(顶掉 `/quit` 等于把用户锁在界面里)。

qi_agent/docs/themes.md

@@ -0,0 +1,78 @@
+# 主题
+
+qi 的 TUI 只有**两份内置调色板**:`dark` 与 `light`,就是 `src/qi_agent/themes/` 下的两个 JSON
+(`dark.json` / `light.json`)—— 键名与语义固定成一套,要调配色直接改这两个文件。
+
+> **qi 不支持自定义主题文件**:只有 `dark` / `light` 两个内置值,未知主题名会**报错**,
+> 不会去找用户目录里的 JSON。见 §5。
+
+**事实源:`src/qi_agent/theme.py` + `src/qi_agent/themes/{dark,light}.json`。**
+
+## 1. 选哪一份
+
+优先级(高 → 低):
+
+| 顺序 | 来源 | 取值 |
+| --- | --- | --- |
+| 1 | 环境变量 `QI_THEME` | `dark` / `light` / `auto` |
+| 2 | `settings.json` 的 `theme` | 同上 |
+| 3 | **探测终端背景色**(OSC 11) | 亮背景 → `light`,暗背景 → `dark` |
+| 4 | 兜底 | `dark` |
+
+`auto`(以及未设置)走第 3 步。探测是**查询终端**(OSC 11,超时 150ms),不是猜:
+
+- 终端支持 OSC 11 且回了 `#rrggbb` → 按亮度(`> 0.5` 视为亮)选 `light` / `dark`;
+- **不支持 / 超时 / 回复解析不了 → 落 `dark`**,不报错、不卡住。
+
+探测到的那个背景色会一并带在调色板上(`Palette.terminal_bg`):Textual 的 inline 区域必须有不透明
+底色,把它设成终端背景色才能在视觉上"不填色"(qi 不画底色)。
+
+## 2. 调色板文件长什么样
+
+```jsonc
+{
+  "$schema": "…/theme-schema.json",
+  "name": "dark",
+  "vars":   { "cyan": "#00d7ff", "blue": "#5f87ff", … },      // 命名色(dark 16 项 / light 15 项)
+  "colors": { "accent": "accent", "border": "blue", … },       // 语义键 → 变量名 或 #hex(55 项)
+  "export": { "pageBg": "#18181e", "cardBg": "#1e1e24", … }
+}
+```
+
+解析规则(`load_palette`):
+
+- `colors` 的值**不以 `#` 开头**时,去 `vars` 里查同名变量;查不到就原样当颜色用。
+- **全部转小写**。调色板 JSON 里大小写是混用的(`#2D2838` / `#343841`),而 Textual 的
+  `Color.hex` 会**原样保留**传入字符串的大小写 —— 所以归一必须在 `load_palette` 里做。
+- `export.pageBg` 缺省为 `#18181e`。
+- 取值键(语义色)拼错时**直接报错**(`Palette.hex()`),不会静默变成白色 —— 拼错颜色名最怕
+  的就是"看着像没生效"。
+
+## 3. 同一份调色板喂给三个渲染层
+
+`theme.py` 从一份 `Palette` 导出三个适配对象:
+
+| 导出 | 给谁用 |
+| --- | --- |
+| `rich_theme(palette)` | Rich(非 TUI 场景的输出) |
+| `syntax_theme(palette)` | 代码高亮 |
+| `textual_theme(palette)` | Textual(TUI 本体) |
+
+所以**改主题 = 改那 55 个语义键**,三个渲染层同时跟着变;不需要分别调。
+
+## 4. 主题之外:`theme.py` 里还住着 footer 格式化
+
+同一个文件里还有几个纯格式化函数(`format_tokens` / `shorten_home` / `format_cwd_line` /
+`git_branch`),它们负责状态行里 `~/proj (main)` 这种显示。
+它们与调色板无关,只是碰巧在同一个模块。
+
+## 5. 不能做的事
+
+| 想法 | 现状 |
+| --- | --- |
+| 自定义主题名 | **不支持**。`theme` 只认 `dark` / `light` / `auto`(`auto` 与未设等价);其他值会走"未知 → 退回 dark" |
+| 放一份自己的 JSON 到 `~/.qi/agent/themes/` | **不支持**,没有用户主题目录 |
+| 运行中切换主题 | 交互式前端可切(`ctrl+t` 之外见 [usage.md](usage.md));`QI_THEME` / `settings.theme` 在启动时决定初始值 |
+
+要加自定义主题,需要的是:主题目录的发现规则 + `ThemeError` 之外的加载路径。现在没有,所以本文不描述
+一个不存在的机制。

qi_agent/docs/tui.md

@@ -0,0 +1,109 @@
+# 终端 UI 组件
+
+扩展往界面里加东西的三种集成点。用哪个取决于你要的是"问一句话"还是"接管一块屏幕"。
+
+| 集成点 | 用在哪 | 入口 |
+| --- | --- | --- |
+| **数据层** | 问用户、改状态、读外观 | `ctx.ui.confirm` / `select` / `input` / `editor` / `notify` / `set_status` … |
+| **组件层**(TUI-only) | 往界面里塞自己的组件 | `ctx.ui.custom` / `set_widget` / `set_footer` / `set_header` / `set_editor_component` / `add_autocomplete_provider` / `on_terminal_input` |
+| **渲染回调** | 换掉工具卡片 / 消息 / markdown 的渲染 | `register_entry_renderer` / `register_message_renderer` / `register_markdown_transformer` / `Tool.render_call` / `render_result` / `render_shell` |
+
+`ctx.ui` **总是存在**:没有前端时按调用方给的 `default` 回答,`notify` 落进启动提示,永远不会挂住。
+
+## 数据层
+
+```python
+async def confirm(message, *, title=None, default=False) -> bool
+async def select(message, options, *, title=None, default=None) -> str | None
+async def input(message, *, title=None, default=None, secret=False) -> str | None
+async def editor(prefill="", *, title=None) -> str | None      # 多行
+async def notify(message, *, level="info") -> None
+# 状态与外观
+async def set_status(key, text) / set_title(text)
+await set_working_message(text) / set_working_visible(bool)
+await set_working_indicator({"frames": [...], "intervalMs": int})
+await set_hidden_thinking_label(label)
+await get_tools_expanded() / set_tools_expanded(bool)
+await get_all_themes() / get_theme(name) / set_theme(theme) / theme
+await paste_to_editor / set_editor_text / get_editor_text
+```
+
+**两条硬规则**:
+
+1. **没有后端时每个问答方法返回调用方给的 `default`** —— "交互"退化成"按事先声明好的策略走",
+   而**永远不会挂住**。`confirm` 默认 **False**(拒绝是安全边);`select` / `input` / `editor` 默认 None(取消)。
+   默认值由**调用方**给:只有它知道"这里拒绝安全还是继续安全"。
+2. `notify` 没有后端时**落进 `notes`**,不丢弃。
+
+后端自己抛异常也走 `default`(记一条 note):交互是辅助手段,不该成为新的失败点。
+阻塞式问答还会发 `ui_prompt_start` / `ui_prompt_end`(`{reason, kind, title}`),扩展因此能知道"有人在等交互"。
+
+## 组件层
+
+- `set_widget(fn_or_lines, placement=…)` —— 挂进编辑器上方 / 下方的两个槽位。
+- `custom(fn)` —— 放进模态:签名叫 `fn(ctx, done)` / `fn(ctx)` / `fn()`,返回组件;`done(value)` 结束并返回。
+  非 TUI 前端下返回 `None`。
+- `set_footer(factory)` / `set_header(factory)` —— 内置的只藏起来不卸载,撤回立即恢复。
+- `set_editor_component(factory)` —— 换掉 `#editor`。**必须返回 `TextArea`(或子类)**,否则记 note 并拒绝:
+  qi 的历史环 / kill-ring / 补全面板 / 光标定位都建立在这个接口上。写个 `TextArea` 子类就能做 vim 式模态编辑。
+- `add_autocomplete_provider(factory)` —— `factory(text, cursor_offset) -> list[str | {value, label, description}]`,
+  与命令参数补全**同一套元素形状**;**返回退订函数**;支持 async(晚一拍回填,文本动过就丢弃)。
+- `on_terminal_input(handler)` —— 只支持 `{"consume": True}`(吃掉按键),不支持"换成另一个键":
+  Textual 的 `events.Key` 不是为改写设计的,要改写就用 `set_editor_component` 接管编辑器。返回退订函数。
+
+组件是 **textual widget**;`ctx.mode`(`tui` / `rpc` / `json` / `print`)是组件层的门控口
+(`if ctx.mode == "tui":`)。**按形参个数适配**:声明三个形参(`x, theme, context`)会拿到
+`(payload, ctx, None)`,不报错也不静默失效。
+
+## 渲染回调
+
+回调直接返回组件(或 markdown 字符串);**抛异常 / 返回 `None` → 退回内置渲染** + 在界面上说一句 ——
+工具卡片与消息绝不会因为一个坏回调而消失。
+
+| 钩子 | 签名 | 位置 |
+| --- | --- | --- |
+| `register_entry_renderer(customType, fn)` | `fn(entry, ctx) -> Widget \| None` | 回放遇到该 `custom_type` 时;未知 custom entry 会以 `[type] {json}` 原样显示,**绝不丢弃** |
+| `register_message_renderer(customType, fn)` | `fn(entry, ctx) -> Widget \| None` | 同上,用于带 `custom_type` 的 **message** entry(即 `api.send_message` 以 dict 形状写的那些) |
+| `register_markdown_transformer(fn)` | `fn(markdown, ctx) -> str` | user / assistant 的**最终文本**渲染前链式改写(流式增量不逐个改 —— 半截 markdown 改了更糟) |
+| `Tool.render_call` | `fn(args, ctx) -> Widget \| None` | `tool_start` 时整个替换默认卡片 |
+| `Tool.render_result` | `fn(result, ctx) -> Widget \| None` | `tool_end` 时替换结果组件 |
+| `Tool.render_shell` | `"default"` / `"self"` | `"default"` 给组件套上工具卡片外壳(状态底色 + `(1,1)` 内边距);`"self"` = 自己画框 |
+
+工具块可以是内置 `ToolBlock` 也可以是 `ExtensionToolBlock` —— 两者都实现 `set_state` / `set_output`,
+所以展开 / 复制 / 会话回放不必分叉。
+
+## 例:自定义组件 + 工具卡片
+
+```python
+from qi_agent.extensions import Tool
+from textual.widgets import Static
+
+def register(api):
+    # 1) 往编辑器上方挂一行字
+    api.on("session_start", lambda payload, ctx: ctx.ui.set_widget(lambda ctx: Static("my-ext 在看着"), placement="above"))
+
+    # 2) 一个模态:问一句话,把结果当返回
+    def ask_lot(ctx, done):
+        async def pick(value=None):
+            done(value)
+        return ctx.ui.custom(lambda ctx: Static("…"))     # 真实组件按你的界面写
+
+    # 3) 工具用自己的卡片渲染
+    async def run(args, ctx):
+        return "ok"
+
+    api.register_tool(Tool(
+        name="my_tool", description="示例", parameters={"type": "object", "properties": {}},
+        execute=run,
+        render_call=lambda args, ctx: Static(f"my_tool {args}"),
+        render_result=lambda result, ctx: Static(str(result)),
+    ))
+```
+
+配色请走主题的语义键(别写死 `#rrggbb`),否则换主题时你的组件不会跟着变 —— 见 [themes.md](themes.md)。
+
+## 与其它页面的关系
+
+- 扩展整体的写法(工具、事件、命令、旗标、依赖)见 [extensions.md](extensions.md)。
+- 键位与编辑器行为见 [keybindings.md](keybindings.md)。
+- 实现细节(Textual 的 priority / 焦点坑)见 [design/internals.md](../design/internals.md)。

qi_agent/docs/usage.md

@@ -0,0 +1,112 @@
+# 在终端里用 qi
+
+交互形态的用法。一次性与脚本化用法在 [命令行](cli.md);斜杠命令清单在 [斜杠命令](slash-commands.md);
+键位在 [键位](keybindings.md)。
+
+## 输入第一句
+
+```bash
+qi                      # 进界面,什么都不发
+qi "分析这个仓库"        # 进界面,并把这句话作为首条消息发出
+```
+
+- `@path` 把文件内容带进第一条消息(`@xx` 会补全路径:装了 `fd` 走全树搜索,否则只扫当前目录一层)。
+- `enter` 提交,`shift+enter` / `ctrl+j` 换行;输入框最多 8 行。
+- `↑` / `↓` 在空编辑器或行首时翻输入历史(首次进入留住草稿,手动改动即退出)。
+- **选项写在消息之前**(`qi -nt "问题"`):顶层选项在遇到消息后不再解析。
+
+## 看它怎么干活
+
+transcript 从下往上长,底部固定是「编辑器 + 上下边框 + footer」。footer 最多三行:
+
+```text
+~/Desktop/qi (master) • 会话名          ← cwd(+git 分支)(+会话名)
+↑12k ↓678 1.2%/1.0M (auto)   deepseek/v4.1 • medium   ← token 统计 + 模型与思考级别
+排队 2 / 扩展状态 / 瞬时提示            ← 只在这些内容时出现
+```
+
+- 工具调用是一块带底色的卡片(标题 = `read <path>`,输出按工具截断);`ctrl+o` 展开 / 折叠。
+- 思考内容与回答**分开流式**(灰色斜体),`ctrl+t` 随时隐藏 / 显示。
+- 压缩与分支摘要在回放里显示成底色块(`[compaction]` / `[branch]`),`ctrl+o` 展开看摘要。
+- 正在跑时上边框内嵌 `Working` spinner;`escape` 中断(协作式:未执行的工具补"已中断"结果、半截回答照常落盘)。
+
+## 改变方向
+
+| 操作 | 行为 |
+| --- | --- |
+| 回合中 `enter` | **steer**:排队,当前回合结束后立刻作为下一回合发出 |
+| 回合中 `alt+enter` | **follow-up**:排队,排在所有 steer 之后 |
+| `escape` | 中止当前轮;有排队消息就退回编辑器 |
+| `alt+up` | 取回排队消息(多条按 steer → follow-up 拼回编辑器) |
+
+排队消息会以 dim 行写进 transcript(带"当前回合结束后发送"/"follow-up"标签),不会静默丢。
+**命令(`/x`)与 bash(`!x`)例外:回合进行中也立即执行** —— 否则 `/quit`、`/tree` 这类按不下去。
+`/new` 清空队列;队列只存在当前进程里,不落盘。
+
+## 换模型与设置
+
+| 想换 | 怎么做 |
+| --- | --- |
+| 模型 | `/model`(选择器)或 `ctrl+l`;`ctrl+p` / `ctrl+shift+p` 在 `/scoped-models` 圈定的清单里轮换 |
+| 思考级别 | `/thinking` 或 `shift+tab` 循环(off → minimal → … → max);`--thinking <级别>` 只本次运行 |
+| 偏好(主题 / 交互开关) | `/settings` 面板(`enter` 换值、`ctrl+s` 保存到**用户级** settings) |
+| 本次运行的模型 | `qi --provider <名> --model <provider/模型>:<级别>` |
+
+**切换会落盘**:换模型写一条 `model_change`、换级别写一条 `thinking_level_change`,所以**下次打开这条会话
+仍用当时的模型与级别**(CLI 显式给的 `--model` / `--thinking` 优先)。还原前会检查凭证:provider 已经没密钥
+时退回默认并在启动提示里说明,不会拿着注定 401 的模型继续跑。
+
+思考级别经 litellm 的 `reasoning_effort` 下发(`minimal` / `low` / `medium` / `high`);`xhigh` / `max`
+收敛为 `high`。只有模型在 `models.json` 里声明 `reasoning: true` 时才带参。provider 拒收时自动去掉参数
+重试并提示一次。**默认 `medium`**。
+
+## 接着还是重开
+
+| 想做的事 | 怎么做 |
+| --- | --- |
+| 接着最近一条 | `qi -c` |
+| 指定某条 | `qi --session <id\|前缀\|路径>` |
+| 浏览 / 恢复 / 重命名 / 删除 | `/resume`(或 `qi -r` 直接进选择器;`tab` 切"当前目录 ↔ 全部") |
+| 从某条分叉出新会话 | `/fork [序号\|id]`(把那条消息放回编辑器)、`/clone`、`qi --fork <id>` |
+| 跳到本会话的别的节点继续 | `/tree`(同文件内开分支;被放弃的那段会压成 `branch_summary` 挂过去) |
+| 不落盘地跑一把 | `qi --no-session`(内存会话) |
+
+**裸 `qi` 与 `/new` 走懒建**:会话对象立刻就有,但**文件推迟到第一条助手回答**才出现 ——"进来看看就退出"
+不会在会话目录里留下空文件。`/session` 看当前会话信息(ID / 文件 / cwd / 消息数 / 分支点 / 模型 / 用量)。
+
+## 跑一条终端命令
+
+| 写法 | 行为 |
+| --- | --- |
+| `!<命令>` | 执行 shell;输出以「上下 `─` + `$ cmd` + 输出」块展示,并把「命令 + 输出」落成一条 user 消息供后续回合参考 |
+| `!!<命令>` | 同样执行,但**不进上下文**(块边框变 dim,标题标出) |
+
+这是**你亲手敲的**操作:`!` 命令不经任何过滤(与模型走 `bash` 工具是两回事,见 [security.md](security.md))。
+
+## 复制、导出、分享
+
+| 操作 | 命令 |
+| --- | --- |
+| 复制最后一条回答 | `/copy` 或 `ctrl+x`(剪贴板走 OSC 52) |
+| 导出会话 | `/export [file]` 或 `qi --export out.jsonl`(按扩展名:`.html` → 自包含 HTML(只含当前分支),其余 → 原始 JSONL) |
+| 导入会话 | `/import <file>` |
+| 分享 | `/share` —— 传成**私有** GitHub gist 并复制链接(token 见 [providers.md](providers.md)) |
+
+## 调整终端
+
+- **渲染模式**:`fullscreen`(qi 默认)= 进备用屏、qi 拥有视口,滚轮只在界面内滚;**`regular`** = 不占全屏,
+  滚动交给终端。改 `settings.tuiMode` 或 `--tui-mode <regular|fullscreen>`;改完要**重启**(`--tui-mode` 只覆盖当次)。
+- **配色**:`dark` / `light` / `auto`(探测终端背景色);`QI_THEME=light qi`。见 [themes.md](themes.md)。
+- **版式**:`editorPaddingX` / `outputPad` / `autocompleteMaxVisible` 在 settings 里调。
+
+## 出问题时
+
+```bash
+qi doctor                  # 配置 / 凭证 / 扩展 / 包声明,一次全报(并给出可复制的修复命令)
+qi config --json           # 合并后的设置(含来自哪几个文件)
+qi --list-models           # provider / 模型 / 凭据状态
+qi --verbose -p "问题"      # 无头模式下也看进度(stderr,不污染 stdout)
+```
+
+`qi doctor` 的凭证一节会给出**来源**(`auth(...)` / `env:XXX` / `config:...`)——
+"我明明设了环境变量"这类问题能直接看出是"没读到"还是"读到了但为空"。

qi_agent/export_html.py

@@ -0,0 +1,95 @@
+"""会话导出成**单文件 HTML**(pi 的 `/export [file]`:按扩展名选 HTML 或 JSONL)。
+
+三件事刻意这么做:
+
+* **只导当前分支** —— 用户看到的、能接着跑的就是那一条(与会话回放同一口径);整个文件
+  (含其它分支)仍然可以用 `.jsonl` 导出,那条路没变;
+* **自包含**:CSS 内联、不引任何外部资源 —— 这样一个文件就能分享(将来 `/share` 上传的
+  正是它),离线打开也不掉样式;
+* **一切内容都转义**:这是**可分享的产物**,而会话里装的是用户与模型的自由文本 ——
+  模型输出里的 `<script>` 在别人的浏览器里执行,是这类导出最典型的坑。
+"""
+
+from __future__ import annotations
+
+import html
+from pathlib import Path
+from typing import Any
+
+_CSS = """body { margin: 0 auto; max-width: 52rem; padding: 2rem 1rem;
+  font: 15px/1.6 -apple-system, "Segoe UI", "Noto Sans CJK SC", sans-serif;
+  background: #faf9f7; color: #23201c; }
+h1 { font-size: 1.1rem; margin: 0 0 .25rem; }
+.meta { color: #6b635a; font-size: .8rem; margin-bottom: 1.5rem; }
+.turn { border-left: 3px solid #d8d2c8; padding: .1rem 0 .1rem .8rem; margin: 1rem 0;
+  white-space: pre-wrap; overflow-wrap: anywhere; }
+.user { border-color: #8a7f6d; }
+.assistant { border-color: #6b8ca8; }
+.tool { border-color: #b3a894; color: #554e46; font-family: ui-monospace, monospace;
+  font-size: .85rem; }
+.note { color: #6b635a; font-style: italic; }
+.role { display: block; font-size: .7rem; letter-spacing: .06em; text-transform: uppercase;
+  color: #8a7f6d; margin-bottom: .2rem; }"""
+
+_ROLE_LABEL = {"user": "你", "assistant": "助手", "tool": "工具"}
+
+
+def _text_of(content: Any) -> str:
+    """`content` → 纯文本。字符串直接用;分段列表取其文本;其它形状退 `str()`。
+
+    (会话 entry 的 `content` 多数是字符串,但工具结果与多段消息可能是列表 ——
+    宁可退化成可读的字符串,也不要在这里抛。)
+    """
+    if isinstance(content, str):
+        return content
+    if isinstance(content, list):
+        parts: list[str] = []
+        for item in content:
+            if isinstance(item, str):
+                parts.append(item)
+            elif isinstance(item, dict) and isinstance(item.get("text"), str):
+                parts.append(item["text"])
+        return "\n".join(parts)
+    return "" if content is None else str(content)
+
+
+def render_session_html(session: Any, *, title: str | None = None) -> str:
+    """把会话的**当前分支**渲染成一个自包含 HTML 字符串。"""
+    heading = title or getattr(session, "title", "") or "会话"
+    created = str(getattr(session, "created_at", "") or "")
+    sid = str(getattr(session, "id", "") or "")
+    where = str(getattr(session, "cwd", "") or "")
+    rows: list[str] = []
+    for entry in session.branch():
+        kind = str(entry.get("type") or "")
+        if kind == "message":
+            role = str(entry.get("role") or "assistant")
+            body = _text_of(entry.get("content"))
+            if not body.strip():
+                continue
+            label = _ROLE_LABEL.get(role, role)
+            rows.append(f'<div class="turn {html.escape(role)}">'
+                        f'<span class="role">{html.escape(label)}</span>'
+                        f'{html.escape(body)}</div>')
+        elif kind in ("compaction", "branch_summary"):
+            summary = _text_of(entry.get("summary"))
+            who = "上下文压缩" if kind == "compaction" else "分支摘要"
+            rows.append(f'<div class="turn note">{html.escape(who)}:{html.escape(summary)}</div>')
+    meta = " · ".join(part for part in (sid, created, where) if part)
+    return ("<!doctype html>\n<html lang=\"zh\">\n<head>\n<meta charset=\"utf-8\">\n"
+            f"<title>{html.escape(heading)}</title>\n<style>\n{_CSS}\n</style>\n</head>\n<body>\n"
+            f"<h1>{html.escape(heading)}</h1>\n"
+            f'<p class="meta">{html.escape(meta)}</p>\n'
+            + "\n".join(rows) + "\n</body>\n</html>\n")
+
+
+def write_session_html(session: Any, out: Path, *, title: str | None = None) -> Path:
+    """写文件(目录不存在就建)。返回写到的路径。"""
+    out.parent.mkdir(parents=True, exist_ok=True)
+    out.write_text(render_session_html(session, title=title), encoding="utf-8")
+    return out
+
+
+def html_wanted(path: Path) -> bool:
+    """`.html` / `.htm` → 导 HTML;其余(含 `.jsonl`)→ 导原始 JSONL(pi 同口径)。"""
+    return path.suffix.lower() in (".html", ".htm")