@luban-code/luban-code 1.66.1 → 1.100.1

package/README.zh.md

@@ -7,11 +7,11 @@
 VSCodium / VS Code 里的**侧边栏 AI 编码助手**：说人话 → 它改文件、跑命令、自己验证，然后告诉你改了什么。
 零源码补丁（不动编辑器源码）：可以从 VS Code 市场 / Open VSX / VSIX 作为普通扩展安装，也可以用脚本装成 App 的内置扩展。
 
-版本 **1.66.0** · [English](README.md) · [全部文档](docs/README.md)
+版本 **1.79.0** · [English](README.md) · [全部文档](docs/README.md)
 
-<!-- 截图占位：把图片放进 media/screenshots/ 后，取消下面两行的注释 -->
-<!-- ![聊天面板与行内 diff](media/screenshots/panel.png) -->
-<!-- ![编辑器内的逐块审阅](media/screenshots/review.png) -->
+![聊天面板与行内 diff](https://raw.githubusercontent.com/eppen/luban-assets/main/screenshots/panel.png)
+
+![编辑器内的逐块审阅](https://raw.githubusercontent.com/eppen/luban-assets/main/screenshots/review.png)
 
 ## 它是什么
 
@@ -23,6 +23,8 @@ VSCodium / VS Code 里的**侧边栏 AI 编码助手**：说人话 → 它改文
 - **只读是真的只读**：Plan 模式下写文件的工具根本没注册，命令还要过一道只读校验，产出的计划落成 Markdown 文件，你改完再执行就按改后的走
 - **为省 token 而设计**：消息排布对齐前缀缓存（第 2 轮起通常 95%+ 命中），每轮显示输入 / 输出 / 缓存 / 上下文占用，另有本地账本与用量看板
 - **不挑模型**：任何 OpenAI 兼容端点（DeepSeek / Ollama / llama.cpp / vLLM…），API key 存 SecretStorage 不落盘
+- **状态栏状态灯**：右下角一行 `(o.o) run_command npm test` —— 小木匠「班班」的脸加当前在干嘛（思考中 / 输出中 / 执行工具 / 等待确认 / 完成 / 出错），和终端里是同一张脸，鼠标悬停看这一轮的全景，点击打开面板；挂机久了它自己睡（`-_-`）。不需要可关（`luban.statusBar.enabled`）
+- **顺手的 Markdown 预览**：VSCodium 自带的预览太难用，Luban 自己做一个 —— 命令面板执行「Luban: Markdown 预览」（或编辑器标题栏的 📖 按钮）在旁边开一个预览面板：代码块带语法高亮、本地图片按相对路径显示、编辑器滚动时预览跟着走。渲染器与聊天面板共用，高亮规则与终端 CLI 共用 —— 一套规则，三处使用。
 
 **能做的事**
 
@@ -34,18 +36,20 @@ VSCodium / VS Code 里的**侧边栏 AI 编码助手**：说人话 → 它改文
 - 多轮记忆：同一会话里的追问会带上前几轮的提问与回答（只带正文，按轮数 / 字符预算自动裁剪）
 - 历史查询：会话弹层顶部有搜索框 —— 标题即时过滤，输入 2 个字以上连正文一起查（回答、工具结果、`@` 引用路径都能搜到），命中词高亮、命中行带一段摘要
 - 改历史：已发出的提问点气泡上的 `✎` 就能就地改，点「发送」自动截掉这条之后的记录并用改后的内容重新开跑一轮
-- 代码引用：`@` 选文件、`@` 选文件夹、`#` 引用编辑器选区；在编辑器里选中代码后右键「Add Selection to Luban Chat」（或 `Cmd/Ctrl+Alt+A`）可插入带位置与行号的 `#selection 路径:起始-结束`，多次选区、跨文件都能叠加，发送时各自展开成一份引用
+- 代码引用：`@` 选文件、`@` 选文件夹、`#` 引用编辑器选区；在编辑器里选中代码后，选区首行上方会直接浮出「加入聊天 / 加入新聊天」两枚 CodeLens（点一下即引用），也可右键「Add Selection to Luban Chat」（或 `Cmd/Ctrl+Alt+A`）插入带位置与行号的 `#selection 路径:起始-结束`，多次选区、跨文件都能叠加，发送时各自展开成一份引用，「Add Selection to Luban **New** Chat」则先开一个全新会话再插入并聚焦输入框，方便直接发第一条消息；资源管理器里右键文件 / 文件夹 →「Add File / Folder to Luban Chat」把 `@路径` / `@目录/` 插进当前会话，「Add File / Folder to Luban **New** Chat」则先开一个全新会话再插入并聚焦输入框，方便直接发第一条消息
 - 自动上下文：不写 `@` 也会把**本会话用过的文件**（`@` 引用过 / 带选区带过）的代码附在消息末尾（有选区给选区，否则光标附近约 200 行）；别的会话正在看的文件不会被带进来，新会话首轮要带文件请用 `@` 或选中一段
 - 代码检索：`search_code` 本地词法索引 + BM25，返回「路径:行号: 命中行」，大仓库不用再 `list_files` 全量扫
 - Tab 补全：DeepSeek FIM 续写光标处代码，`Tab` 接受（默认关闭，命令面板一键开）
 - 联网搜索：`@web` 先搜再答并列出来源；Agent / Plan 也能自己调 `web_search` / `web_fetch`
-- 看真实页面：`browser` 用本机 Chrome / Edge 的无头实例打开地址、取可访问性大纲、截图、看 console 与失败请求（默认关闭，设置 `luban.browser.enabled=true`；只读，不点击不输入；截图只在开了 `vision` 的模型下才会被看到）
-- 操作本机桌面（macOS / Windows）：`computer` 截屏 / 识别屏幕文字 / 列窗口 / 点击 / 双击 / 拖动 / 滚动 / 输入 / 组合键（默认关闭，设置 `luban.computer.enabled=true`；首次动键鼠要确认一次；Plan 模式不可用；macOS 上没开 `vision` 的模型会自动改走 OCR 文字，Windows 暂未实现 OCR、只能看图）
-- 工具循环按预算收敛：主约束是上下文窗口（工具结果占位压缩）+ 墙钟 + 死循环检测，轮数上限只作安全阀（默认 100，可配，0 = 不限）
+- 看真实页面：`browser` 用本机 Chrome / Edge 的无头实例打开地址、取可访问性大纲、截图、看 console 与失败请求；Agent 模式下还能 `click` / `type` / `scroll` 驱动页面交互（Plan 模式不可用，首次需确认）（默认关闭，设置 `luban.browser.enabled=true`；截图只在开了 `vision` 的模型下才会被看到）
+- 操作本机桌面（macOS / Windows / Linux）：`computer` 截屏 / 识别屏幕文字 / 列窗口 / 点击 / 双击 / 拖动 / 滚动 / 输入 / 组合键（默认关闭，设置 `luban.computer.enabled=true`；首次动键鼠要确认一次；Plan 模式不可用；macOS 上没开 `vision` 的模型会自动改走 OCR 文字，Windows 暂未实现 OCR、只能看图。Linux 需要 `xdotool` + `ffmpeg`/`imagemagick`，OCR 用 `tesseract-ocr`；Wayland 会话下 xdotool 只能操作 XWayland 应用，无头环境要先起 Xvfb）
+- 工具循环按预算收敛：主约束是上下文窗口（工具结果占位压缩）+ 墙钟 + 死循环检测，轮数上限只作安全阀（默认 200，可配，0 = 不限）
 - 每轮 usage：回答下方一行显示输入 / 输出 / 缓存命中 / 上下文占用 / 请求数，header 常驻上下文占用条（按模型窗口算百分比）
 - 外部工具：本地 stdio MCP server 的工具并入同一个工具循环（`mcp__<server>__<tool>`），Plan 模式只放行声明只读的工具
+- 本地插件：`~/.luban/plugins` 与 `<工作区>/.luban/plugins` 里放一个 `plugin.json` + `index.js`，它的工具就以 `pl__<plugin>__<tool>` 进同一个工具循环 —— 不用起进程、不用写协议（默认关闭，设置 `luban.plugins.enabled=true`；插件跑在扩展进程内，首次加载与内容变更都会先确认）
 - 技能：扫描 `~/.luban/skills`、`~/.claude/skills`、`~/.cursor/skills` 与项目同名目录，把 `SKILL.md` 的 name/description 注入系统提示，模型需要时用 `read_skill` 读全文
 - 审阅改动：写完自动在编辑器开出 diff（标题栏「全部保留 / 全部撤销」+ 两侧 hunk 逐块 CodeLens）+ 行内 diff 高亮 + 侧边栏摘要卡片
+- 云端备份（WebDAV）：设置面板里**独立一个「☁ 云端备份」分区**（与常规 / 设置 / 用量并列），填服务器地址 / 用户名 / 应用专用密码（密码进 SecretStorage），一键把会话、图片附件、计划、provider 配置与 `mcp.json` 传到自己的 WebDAV，也能查看远端清单并按 sha1 差异恢复回来（覆盖前先快照到 `~/.luban/backups/`，`providers.json` 只合并不覆盖、key 不回落）
 
 **不做的事**（要做就得 fork 编辑器源码，明确冻结）：next-edit prediction、向量语义检索。Tab 补全与本地词法检索已在 1.13.0 补上。
 
@@ -62,7 +66,65 @@ luban --agent --apply "新建 utils.js 并写测试"      # 完整 agent，放
 luban                                              # 交互多轮（需要 TTY）
 ```
 
-全量参数见 `luban --help`（`--model` / `--root` / `--json` / `--max-rounds` 等）。
+配合 `--apply` 时，每次落盘前会显示 unified diff 并逐次确认（`--yes` 可跳过确认）。交互模式里 `Enter` 发送、`Ctrl-J` / `Alt+Enter` 换行，输入 `/` 补全命令、`@` 补全文件，跑动中按 `Esc` 取消本轮。全量参数见 `luban --help`（`--model` / `--root` / `--json` / `--max-rounds` 等）。
+
+插件从索引装（索引是 `registry/registry.json`，插件源码在 [eppen/luban-plugins](https://github.com/eppen/luban-plugins)）：
+
+```bash
+luban plugin list                  # 索引里的插件：签名、审核状态、权限
+luban plugin add demo --dry-run    # 只校验不落盘
+luban plugin add demo              # 验签 → 查审核 → 按 tag 拉包 → 校对 sourceSha256 → 装进 ~/.luban/plugins
+luban plugin remove demo           # 移进回收站，可还原
+```
+
+技能（`type: "skill"` 条目：纯 `SKILL.md`，无代码、不需要信任确认）：
+
+```bash
+luban skill list                   # 只列技能
+luban skill add changelog-draft    # → ~/.luban/skills/changelog-draft（下一轮即出现在技能目录里）
+luban skill remove changelog-draft # 移进 ~/.luban/skills-trash/，可还原
+```
+
+`add` 装完**不会自动信任**：打开 `luban.plugins.enabled` 后首次加载会列出工具清单再问一次，插件目录内容一变就重新问。
+索引默认用包内自带的一份，`--registry <路径|URL>` 或环境变量 `LUBAN_REGISTRY` 可换（内网镜像 / 本地试条目）。
+
+## 在 Zed / JetBrains 里用（ACP）
+
+同一个内核也能被别的编辑器驱动：`acp.js` 在 stdio 上讲 ACP（Agent Client Protocol），
+Zed / JetBrains 把 Luban 当成自己的 agent —— 正文、思考、工具卡片、计划都是原生渲染，
+写文件前会把 diff 交给客户端的权限弹窗确认。
+
+```jsonc
+// Zed 设置里加一个 agent，然后在 agent 面板的 + 菜单里选它
+{
+  "agent_servers": {
+    "Luban": { "type": "custom", "command": "npx", "args": ["-y", "@luban-code/luban-acp@latest"] }
+  }
+}
+```
+
+发布态是独立 npm 包 `@luban-code/luban-acp`（bin 就叫 `luban-acp`）：
+
+```bash
+npx -y @luban-code/luban-acp@latest   # 免安装
+npm i -g @luban-code/luban-acp        # 或装一次
+```
+
+在「启动命令 + 参数」这种 ACP 客户端（ACP Pro / Zed / JetBrains）里这样填：
+
+| 字段 | 值 |
+|---|---|
+| Name | `Luban` |
+| Command | `npx` |
+| Args | `-y @luban-code/luban-acp@latest` |
+
+> **为什么单独一个包**：npm 的 `npx <pkg>` 会去找「包名去掉 scope」同名的那个 bin，
+> 包里有多个 bin 又对不上时就报 `could not determine executable to run`。主包叫
+> `luban-code`、bin 是 `luban` / `luban-acp`，对不上 —— 所以主包额外挂了个 `luban-code`
+> 别名 bin（让 `npx` 主包能唯一推断出 CLI），ACP 走独立包（包名和 bin 都叫 `luban-acp`，
+> 天然唯一可推断）。跟 `@agentclientprotocol/claude-agent-acp` 等其它 agent 的装法完全同构。
+
+参数 `--root` / `--model` / `--read-only` / `--plugins` / `--log`，模型与 key 仍走 `~/.luban/providers.json`。能力边界（没有历史会话、读不到编辑器未保存内容、没有 LSP 诊断、`run_command` 不拦）见 [docs/acp.md](docs/acp.md)。
 
 ## 安装
 
@@ -132,6 +194,18 @@ cd ~/luban
 | **Plan** | 只读调研，产出「目标 / 现状 / 步骤 / 验证方式 / 风险」计划并落盘，点「▶ 执行这个计划」才动文件 |
 | **Chat** | 纯问答，不碰文件；带 `@web` 时先联网搜索再回答 |
 
+## 在 VS Code Chat / Agents 窗口里用 Luban 的模型
+
+独立 **Agents 窗口**（以及侧栏 Chat）只认 `vscode.lm` 里注册的模型，扩展自己的 webview 进不去。Luban 把
+`providers.json` 里的每个模型注册成语言模型提供者（vendor `luban`），所以：
+
+1. 装好扩展后 `Reload Window`；
+2. Chat / Agents 窗口 → 模型选择器 → **Manage Models…** → **Luban** → 勾选要用的模型；
+3. 选「xxx · Luban」发消息 —— 用的是 Luban 配置的端点与 key。
+
+那个窗口里的工具循环、编辑、终端都是 VSCode 自己的；Luban 的侧栏 / 会话 / 逐块审阅不参与。
+细节与排障见 [配置](docs/configuration.md#在-vs-code-chat--agents-窗口里用-luban-的模型)。
+
 ## 文档
 
 市场页面只渲染 `README.md`，细节都在 [docs/](docs/README.md)：
@@ -153,7 +227,7 @@ cd ~/luban
 
 ## 安全须知
 
-`run_command` 跑的就是**你本机的 shell**，没有 OS 级沙箱；Plan 模式额外加一道启发式只读校验。文件工具默认允许操作工作区外的路径（`luban.fs.allowOutsideWorkspace=false` 可收回）。MCP server 是权限等同当前用户的子进程，只配置可信 server。详见 [已知限制](docs/limitations.md)。
+`run_command` 跑的就是**你本机的 shell**，没有 OS 级沙箱；Plan 模式额外加一道启发式只读校验。文件工具默认允许操作工作区外的路径（`luban.fs.allowOutsideWorkspace=false` 可收回）。MCP server 是权限等同当前用户的子进程，只配置可信 server；本地插件更直接 —— 它 `require` 进扩展进程，靠「默认关闭 + 首次确认 + 内容变更再确认」控制风险，同样不是沙箱。详见 [已知限制](docs/limitations.md)。
 
 ## 许可