@luban-code/luban-code 1.66.0 → 1.100.0

package/LICENSE

@@ -1,204 +1,204 @@
-
-                                 Apache License
-                           Version 2.0, January 2004
-                        http://www.apache.org/licenses/
-
-   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
-
-   1. Definitions.
-
-      "License" shall mean the terms and conditions for use, reproduction,
-      and distribution as defined by Sections 1 through 9 of this document.
-
-      "Licensor" shall mean the copyright owner or entity authorized by
-      the copyright owner that is granting the License.
-
-      "Legal Entity" shall mean the union of the acting entity and all
-      other entities that control, are controlled by, or are under common
-      control with that entity. For the purposes of this definition,
-      "control" means (i) the power, direct or indirect, to cause the
-      direction or management of such entity, whether by contract or
-      otherwise, or (ii) ownership of fifty percent (50%) or more of the
-      outstanding shares, or (iii) beneficial ownership of such entity.
-
-      "You" (or "Your") shall mean an individual or Legal Entity
-      exercising permissions granted by this License.
-
-      "Source" form shall mean the preferred form for making modifications,
-      including but not limited to software source code, documentation
-      source, and configuration files.
-
-      "Object" form shall mean any form resulting from mechanical
-      transformation or translation of a Source form, including but
-      not limited to compiled object code, generated documentation,
-      and conversions to other media types.
-
-      "Work" shall mean the work of authorship, whether in Source or
-      Object form, made available under the License, as indicated by a
-      copyright notice that is included in or attached to the work
-      (an example is provided in the Appendix below).
-
-      "Derivative Works" shall mean any work, whether in Source or Object
-      form, that is based on (or derived from) the Work and for which the
-      editorial revisions, annotations, elaborations, or other modifications
-      represent, as a whole, an original work of authorship. For the purposes
-      of this License, Derivative Works shall not include works that remain
-      separable from, or merely link (or bind by name) to the interfaces of,
-      the Work and Derivative Works thereof.
-
-      "Contribution" shall mean any work of authorship, including
-      the original version of the Work and any modifications or additions
-      to that Work or Derivative Works thereof, that is intentionally
-      submitted to Licensor for inclusion in the Work by the copyright owner
-      or by an individual or Legal Entity authorized to submit on behalf of
-      the copyright owner. For the purposes of this definition, "submitted"
-      means any form of electronic, verbal, or written communication sent
-      to the Licensor or its representatives, including but not limited to
-      communication on electronic mailing lists, source code control systems,
-      and issue tracking systems that are managed by, or on behalf of, the
-      Licensor for the purpose of discussing and improving the Work, but
-      excluding communication that is conspicuously marked or otherwise
-      designated in writing by the copyright owner as "Not a Contribution."
-
-      "Contributor" shall mean Licensor and any individual or Legal Entity
-      on behalf of whom a Contribution has been received by Licensor and
-      subsequently incorporated within the Work.
-
-   2. Grant of Copyright License. Subject to the terms and conditions of
-      this License, each Contributor hereby grants to You a perpetual,
-      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-      copyright license to reproduce, prepare Derivative Works of,
-      publicly display, publicly perform, sublicense, and distribute the
-      Work and such Derivative Works in Source or Object form.
-
-   3. Grant of Patent License. Subject to the terms and conditions of
-      this License, each Contributor hereby grants to You a perpetual,
-      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-      (except as stated in this section) patent license to make, have made,
-      use, offer to sell, sell, import, and otherwise transfer the Work,
-      where such license applies only to those patent claims licensable
-      by such Contributor that are necessarily infringed by their
-      Contribution(s) alone or by combination of their Contribution(s)
-      with the Work to which such Contribution(s) was submitted. If You
-      institute patent litigation against any entity (including a
-      cross-claim or counterclaim in a lawsuit) alleging that the Work
-      or a Contribution incorporated within the Work constitutes direct
-      or contributory patent infringement, then any patent licenses
-      granted to You under this License for that Work shall terminate
-      as of the date such litigation is filed.
-
-   4. Redistribution. You may reproduce and distribute copies of the
-      Work or Derivative Works thereof in any medium, with or without
-      modifications, and in Source or Object form, provided that You
-      meet the following conditions:
-
-      (a) You must give any other recipients of the Work or
-          Derivative Works a copy of this License; and
-
-      (b) You must cause any modified files to carry prominent notices
-          stating that You changed the files; and
-
-      (c) You must retain, in the Source form of any Derivative Works
-          that You distribute, all copyright, patent, trademark, and
-          attribution notices from the Source form of the Work,
-          excluding those notices that do not pertain to any part of
-          the Derivative Works; and
-
-      (d) If the Work includes a "NOTICE" text file as part of its
-          distribution, then any Derivative Works that You distribute must
-          include a readable copy of the attribution notices contained
-          within such NOTICE file, excluding those notices that do not
-          pertain to any part of the Derivative Works, in at least one
-          of the following places: within a NOTICE text file distributed
-          as part of the Derivative Works; within the Source form or
-          documentation, if provided along with the Derivative Works; or,
-          within a display generated by the Derivative Works, if and
-          wherever such third-party notices normally appear. The contents
-          of the NOTICE file are for informational purposes only and
-          do not modify the License. You may add Your own attribution
-          notices within Derivative Works that You distribute, alongside
-          or as an addendum to the NOTICE text from the Work, provided
-          that such additional attribution notices cannot be construed
-          as modifying the License.
-
-      You may add Your own copyright statement to Your modifications and
-      may provide additional or different license terms and conditions
-      for use, reproduction, or distribution of Your modifications, or
-      for any such Derivative Works as a whole, provided Your use,
-      reproduction, and distribution of the Work otherwise complies with
-      the conditions stated in this License.
-
-   5. Submission of Contributions. Unless You explicitly state otherwise,
-      any Contribution intentionally submitted for inclusion in the Work
-      by You to the Licensor shall be under the terms and conditions of
-      this License, without any additional terms or conditions.
-      Notwithstanding the above, nothing herein shall supersede or modify
-      the terms of any separate license agreement you may have executed
-      with Licensor regarding such Contributions.
-
-   6. Trademarks. This License does not grant permission to use the trade
-      names, trademarks, service marks, or product names of the Licensor,
-      except as required for reasonable and customary use in describing the
-      origin of the Work and reproducing the content of the NOTICE file.
-
-   7. Disclaimer of Warranty. Unless required by applicable law or
-      agreed to in writing, Licensor provides the Work (and each
-      Contributor provides its Contributions) on an "AS IS" BASIS,
-      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
-      implied, including, without limitation, any warranties or conditions
-      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
-      PARTICULAR PURPOSE. You are solely responsible for determining the
-      appropriateness of using or redistributing the Work and assume any
-      risks associated with Your exercise of permissions under this License.
-
-   8. Limitation of Liability. In no event and under no legal theory,
-      whether in tort (including negligence), contract, or otherwise,
-      unless required by applicable law (such as deliberate and grossly
-      negligent acts) or agreed to in writing, shall any Contributor be
-      liable to You for damages, including any direct, indirect, special,
-      incidental, or consequential damages of any character arising as a
-      result of this License or out of the use or inability to use the
-      Work (including but not limited to damages for loss of goodwill,
-      work stoppage, computer failure or malfunction, or any and all
-      other commercial damages or losses), even if such Contributor
-      has been advised of the possibility of such damages.
-
-   9. Accepting Warranty or Additional Liability. While redistributing
-      the Work or Derivative Works thereof, You may choose to offer,
-      and charge a fee for, acceptance of support, warranty, indemnity,
-      or other liability obligations and/or rights consistent with this
-      License. However, in accepting such obligations, You may act only
-      on Your own behalf and on Your sole responsibility, not on behalf
-      of any other Contributor, and only if You agree to indemnify,
-      defend, and hold each Contributor harmless for any liability
-      incurred by, or claims asserted against, such Contributor by reason
-      of your accepting any such warranty or additional liability.
-
-   END OF TERMS AND CONDITIONS
-
-   APPENDIX: How to apply the Apache License to your work.
-
-      To apply the Apache License to your work, attach the following
-      boilerplate notice, with the fields enclosed by brackets "[]"
-      replaced with your own identifying information. (Don't include
-      the brackets!)  The text should be enclosed in the appropriate
-      comment syntax for the file format. We also recommend that a
-      file or class name and description of purpose be included on the
-      same "printed page" as the copyright notice for easier
-      identification within third-party archives.
-
-   Copyright 2026 eppen (liuhualiang)
-
-   Licensed under the Apache License, Version 2.0 (the "License");
-   you may not use this file except in compliance with the License.
-   You may obtain a copy of the License at
-
-       http://www.apache.org/licenses/LICENSE-2.0
-
-   Unless required by applicable law or agreed to in writing, software
-   distributed under the License is distributed on an "AS IS" BASIS,
-   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-   See the License for the specific language governing permissions and
-   limitations under the License.
-
-Copyright 2026 eppen (liuhualiang)
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 eppen (liuhualiang)
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+
+Copyright 2026 eppen (liuhualiang)

package/README.md

@@ -8,23 +8,96 @@
 
 **中文简介**：装在侧边栏里的编码 agent。说人话 → 它改文件、跑命令、自己验证，然后告诉你改了什么。零源码补丁，可从 VS Code 市场 / Open VSX / VSIX 安装，也能用脚本装成 App 的内置扩展。[完整中文说明 →](https://github.com/eppen/luban/blob/main/README.zh.md)
 
-<!-- 截图占位：把图片放进 media/screenshots/ 后，取消下面两行的注释 -->
-<!-- ![Chat panel and inline diff](https://raw.githubusercontent.com/eppen/luban/main/media/screenshots/panel.png) -->
-<!-- ![Per-hunk review in the editor](https://raw.githubusercontent.com/eppen/luban/main/media/screenshots/review.png) -->
+![Chat panel and inline diff](https://raw.githubusercontent.com/eppen/luban-assets/main/screenshots/panel.png)
+
+![Per-hunk review in the editor](https://raw.githubusercontent.com/eppen/luban-assets/main/screenshots/review.png)
 
 ## Highlights
 
 - **Plan first, execute after you approve** — Plan mode is read-only by construction (write tools are not registered, commands are checked). The plan is saved as a Markdown file you can edit; executing it re-reads that file. You can also pick a Cursor plan (`~/.cursor/plans/*.plan.md`) from the command palette and execute it with Luban.
 - **Review in the editor, not in chat** — every write opens a real diff: accept or reject hunk by hunk from CodeLens or the diff title bar.
-- **Context without ceremony** — `@file`, `@folder/`, `#selection`, or right-click a file or folder in the Explorer → **Add File / Folder to Luban Chat**; select code in the editor and right-click **Add Selection to Luban Chat** (or `Cmd/Ctrl+Alt+A`) to drop a `#selection path:start-end` token that carries its own position, so several selections can stack; plus automatic context from the editor around your cursor; a local BM25 index backs `search_code`, with `glob` for filenames and `grep` for regex.
+- **Context without ceremony** — `@file`, `@folder/`, `#selection`, or right-click a file or folder in the Explorer → **Add File / Folder to Luban Chat** (drops the token into the current chat) or **Add File / Folder to Luban New Chat** (opens a fresh session first, then inserts the token and focuses the input); select code in the editor and it shows **Add to Chat / Add to New Chat** right above the selection (CodeLens), or right-click **Add Selection to Luban Chat** (or `Cmd/Ctrl+Alt+A`) to drop a `#selection path:start-end` token that carries its own position, so several selections can stack, or **Add Selection to Luban New Chat** to open a fresh session first, then insert the token and focus the input; plus automatic context from the editor around your cursor; a local BM25 index backs `search_code`, with `glob` for filenames and `grep` for regex.
 - **Real edits, reversible** — `write_file` / `replace_in_file` / `apply_patch` (multi-file add/update/delete), plus `delete_file` / `move_file`; every change lands in REVIEW with per-hunk accept/undo, and `read_lints` lets the agent see type/syntax errors right after writing.
 - **Any OpenAI-compatible provider** — DeepSeek, Ollama, llama.cpp, vLLM and friends via `~/.luban/providers.json`. API keys go to SecretStorage, never to disk.
 - **Sessions that survive a reload** — history on disk, several concurrent tabs, a message queue while a turn is running, opt-in multi-turn memory. Sent prompts can be edited in place (`✎`): pressing Send truncates everything after it and reruns the turn with the edited text. The history popup has a search box: titles filter as you type, 2+ characters also scan message text, tool results and file references.
 - **Built for cheap multi-turn** — message layout is aligned to token prefix caching (typically 95%+ cache hits after the second turn); each turn shows input / output / cache / context usage, and a local ledger feeds a token dashboard.
-- **Extensible** — local stdio MCP servers and `SKILL.md` skills join the same tool loop; Plan mode only sees tools declared read-only.
-- **Optional real-browser view** — `browser` drives a local headless Chrome/Edge over CDP (read-only: open, accessibility snapshot, screenshot, console, failed requests). Off by default via `luban.browser.enabled`; screenshots are only visible to models with `vision` enabled.
+- **Extensible** — local stdio MCP servers, `SKILL.md` skills and in-process plugins join the same tool loop; Plan mode only sees tools declared read-only.
+- **Plugins without a protocol** — drop a `plugin.json` + `index.js` into `~/.luban/plugins` or `<workspace>/.luban/plugins` and its tools show up as `pl__<plugin>__<tool>` (off by default via `luban.plugins.enabled`; they run in-process, so the first load and any content change ask for confirmation).
+- **Cloud backup over WebDAV** — its own **☁ Backup** tab in the settings panel (next to General / Settings / Usage) takes a server URL, username and app password (the password lives in SecretStorage, never on disk) and uploads sessions, image attachments, plans, provider config and `mcp.json` to your own WebDAV server. You can inspect the remote manifest and restore by sha1 diff; files about to be overwritten are snapshotted into `~/.luban/backups/` first, and `providers.json` is merged rather than replaced (API keys never come back from the remote side).
+- **Optional real-browser view** — `browser` drives a local headless Chrome/Edge over CDP (open, accessibility snapshot, screenshot, console, failed requests; plus `click` / `type` / `scroll` to drive the page in Agent mode — not available in Plan mode, first use asks for confirmation). Off by default via `luban.browser.enabled`; screenshots are only visible to models with `vision` enabled.
 - **Optional desktop control (macOS and Windows)** — `computer` screenshots the real screen, reads on-screen text via OCR (macOS; on Windows it falls back to viewing the screenshot), lists windows, and can click / double-click / drag / scroll / type / send key combos. Off by default via `luban.computer.enabled`; the first action that touches mouse or keyboard asks for confirmation; unavailable in Plan mode; models without `vision` automatically fall back to OCR text.
 - **Optional tab completion** — DeepSeek FIM completion, off by default.
+- **A Markdown preview you can live with** — the built-in VSCodium preview is awkward, so Luban ships its own: **Luban: Markdown preview** (or the 📖 button in the editor title bar) opens a side-by-side panel with syntax-highlighted code blocks, local images resolved relative to the file, and one-way scroll sync from the editor. It reuses the same renderer as the chat panel and the same highlighter as the CLI terminal — one set of rules, three surfaces.
+- **Status-bar light** — one line in the status bar: `(o.o) run_command npm test`. The little carpenter's ASCII face plus what the agent is doing right now (thinking / writing / running a tool / waiting / done / error) — the same face you see in the terminal. Hover for the full picture of this turn, click to open the panel, and it falls asleep (`-_-`) when idle for a while. Turn it off with `luban.statusBar.enabled`.
+
+## CLI
+
+This package also ships the `luban` command — a headless entry point that reuses the extension's agent tool loop (same `~/.luban/providers.json` config).
+
+```bash
+npm i -g @luban-code/luban-code
+luban --plan "调研 src/ 的目录结构并给出重构建议"   # read-only plan (default)
+luban --agent --apply "新建 utils.js 并写测试"      # full agent with writes
+luban                                              # interactive multi-turn (TTY)
+```
+
+With `--apply`, every write shows a unified diff and asks before touching disk (`--yes` skips the prompt). In interactive mode, `Enter` sends, `Ctrl-J` / `Alt+Enter` inserts a newline, `/` completes commands, `@` completes workspace paths, and `Esc` cancels the running turn. Run `luban --help` for all flags (`--model`, `--root`, `--json`, `--max-rounds`, …).
+
+Plugins install from the registry (`registry/registry.json`; sources live in [eppen/luban-plugins](https://github.com/eppen/luban-plugins)):
+
+```bash
+luban plugin list                  # entries: signature, review status, permissions
+luban plugin add demo --dry-run    # verify only, nothing written
+luban plugin add demo              # verify signature → check review → fetch tag → check sourceSha256 → install
+luban plugin remove demo           # moves it to the trash, restorable
+```
+
+Skills (`type: "skill"` entries: plain `SKILL.md`, no code, no permission prompt):
+
+```bash
+luban skill list                   # only skill entries
+luban skill add changelog-draft   # → ~/.luban/skills/changelog-draft (visible on the next turn)
+luban skill remove changelog-draft # moves it to ~/.luban/skills-trash, restorable
+```
+
+Install never auto-trusts: after enabling `luban.plugins.enabled`, the first load lists the tools and asks once more, and any content change asks again. The registry shipped with the package is the default; override with `--registry <path|URL>` or `LUBAN_REGISTRY` (mirror / local entries).
+
+## In Zed / JetBrains (ACP)
+
+The same core can be driven by other editors: `acp.js` speaks ACP (Agent Client Protocol) over stdio, so Zed / JetBrains can use Luban as their own agent — messages, reasoning, tool cards and plans render natively, and every file write is handed to the client's permission dialog as a diff.
+
+```jsonc
+// Add an agent to Zed's settings, then pick it from the + menu in the agent panel
+{
+  "agent_servers": {
+    "Luban": { "type": "custom", "command": "npx", "args": ["-y", "@luban-code/luban-acp@latest"] }
+  }
+}
+```
+
+The published entry point is the standalone npm package `@luban-code/luban-acp` (bin `luban-acp`):
+
+```bash
+npx -y @luban-code/luban-acp@latest   # no install needed
+npm i -g @luban-code/luban-acp        # or install it once
+```
+
+In an ACP client that takes a command plus arguments (ACP Pro, Zed, JetBrains), fill in:
+
+| Field | Value |
+|---|---|
+| Name | `Luban` |
+| Command | `npx` |
+| Args | `-y @luban-code/luban-acp@latest` |
+
+> **Why a separate package?** npm's `npx <pkg>` picks the bin whose name matches the package name (scope
+> stripped) — with several bins and no match it fails with `could not determine executable to run`.
+> The main package is `@luban-code/luban-code` with bins `luban` / `luban-acp`, so `npx` on it cannot
+> infer one; it now also ships a `luban-code` alias bin for exactly that reason. ACP therefore lives in
+> its own package, whose name and bin are both `luban-acp` — the same shape as
+> `@agentclientprotocol/claude-agent-acp` and friends.
+
+Flags: `--root` / `--model` / `--read-only` / `--plugins` / `--log`; models and keys still come from `~/.luban/providers.json`. Known gaps (no session history, no unsaved-editor content, no LSP diagnostics, `run_command` runs unprompted) are listed in [docs/acp.md](docs/acp.md).
 
 ## Install
 
@@ -71,6 +144,20 @@ Editing `~/.luban/providers.json` by hand works too (run `Reload providers.json`
 | **Plan** | Read-only investigation; produces a plan file and touches nothing until you press *Execute*. |
 | **Chat** | Plain Q&A, no file access. Add `@web` to search first. |
 
+## Luban models in the VS Code Chat / Agents window
+
+VS Code's standalone **Agents window** (and the sidebar Chat view) only lists models registered through
+`vscode.lm` — an extension's own webview cannot appear there. Luban registers every model from
+`providers.json` as a language model provider (vendor `luban`), so the same endpoint can be used from
+that window:
+
+1. Reload the window after installing the extension.
+2. Chat / Agents window → model picker → **Manage Models…** → **Luban** → tick the models you want.
+3. Pick “«model» · Luban”.
+
+The tool loop, edits and terminal in that window are VS Code's own; Luban's sidebar, sessions and
+per-hunk review are not involved. See [configuration](https://github.com/eppen/luban/blob/main/docs/configuration.md).
+
 ## Documentation
 
 The Marketplace only renders this page, so the details live on GitHub:
@@ -91,7 +178,7 @@ The Marketplace only renders this page, so the details live on GitHub:
 
 ## Safety
 
-`run_command` executes in **your own shell** — there is no OS-level sandbox. Plan mode adds a heuristic read-only check on commands, and file tools may touch paths outside the workspace (`luban.fs.allowOutsideWorkspace=false` restricts them). MCP servers run as child processes with your user's permissions: only configure servers you trust. See [known limitations](https://github.com/eppen/luban/blob/main/docs/limitations.md).
+`run_command` executes in **your own shell** — there is no OS-level sandbox. Plan mode adds a heuristic read-only check on commands, and file tools may touch paths outside the workspace (`luban.fs.allowOutsideWorkspace=false` restricts them). MCP servers run as child processes with your user's permissions: only configure servers you trust. Local plugins are even closer to home — they are `require`d into the extension process, gated only by "off by default + confirm on first load + confirm again when the plugin's contents change". See [known limitations](https://github.com/eppen/luban/blob/main/docs/limitations.md).
 
 ## License