@luban-code/luban-code 0.0.0-stage → 1.66.0

package/LICENSE

@@ -0,0 +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)

package/README.md

@@ -1,3 +1,100 @@
-# Temporary Holding Version
+# Luban
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![VS Marketplace](https://img.shields.io/visual-studio-marketplace/v/liuhualiang.luban?label=marketplace)](https://marketplace.visualstudio.com/items?itemName=liuhualiang.luban)
+[![Installs](https://img.shields.io/visual-studio-marketplace/i/liuhualiang.luban?label=installs)](https://marketplace.visualstudio.com/items?itemName=liuhualiang.luban)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](https://github.com/eppen/luban/blob/main/LICENSE)
+
+**A side-bar coding agent for VS Code and VSCodium.** Describe what you want — it edits files in your workspace, runs a script or the build to verify, then tells you what changed. No patched editor, no takeover of the native chat: a normal extension that installs from the Marketplace.
+
+**中文简介**：装在侧边栏里的编码 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) -->
+
+## 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.
+- **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.
+- **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.
+
+## Install
+
+| Where | How |
+|---|---|
+| VS Code | Extensions panel → search `Luban` → install, or use the [Marketplace page](https://marketplace.visualstudio.com/items?itemName=liuhualiang.luban) |
+| VSCodium / Open VSX | Extensions panel → search `Luban` → install |
+| VSIX | Download `luban-v*.vsix` from [Releases](https://github.com/eppen/luban/releases), then `⋯` → **Install from VSIX…** |
+| Built-in extension | `./install-into-vscodium.sh` — installs Luban as an app-level extension (VSCodium only, re-run after every app upgrade) |
+
+Requirements: VS Code / VSCodium **1.100+**, plus at least one provider (a remote one needs an API key; a loopback endpoint such as Ollama / llama.cpp / vLLM runs without one).
+
+## Quick start
+
+1. **Configure a provider** — click **⚙** at the bottom of the panel (or run `Provider settings`), fill in base URL, models and API key, then hit *Test connection*.
+2. **Open the panel** — Luban icon in the activity bar, or `Cmd+Shift+L`.
+3. **Ask for something** — e.g. `新建 utils.js，导出 debounce(fn, ms) 和 throttle(fn, ms)，然后用 node 测一下两者行为`.
+
+Editing `~/.luban/providers.json` by hand works too (run `Reload providers.json` after):
+
+```json
+{
+  "defaultModel": "deepseek::deepseek-flash",
+  "providers": [
+    {
+      "id": "deepseek",
+      "name": "DeepSeek",
+      "baseUrl": "https://api.deepseek.com/v1",
+      "apiKeyEnv": "DEEPSEEK_API_KEY",
+      "models": [
+        { "id": "deepseek-flash", "name": "DeepSeek Flash",
+          "maxInputTokens": 65536, "maxOutputTokens": 8192, "toolCalling": true }
+      ]
+    }
+  ]
+}
+```
+
+## Modes
+
+| Mode | What it can do |
+|---|---|
+| **Agent** | Read / write files and run commands, then verify the result. |
+| **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. |
+
+## Documentation
+
+The Marketplace only renders this page, so the details live on GitHub:
+
+| | |
+|---|---|
+| [Usage and features](https://github.com/eppen/luban/blob/main/docs/usage.md) | Shortcuts, three modes, plan files, `@` `#` references, web search |
+| [Tools, MCP and skills](https://github.com/eppen/luban/blob/main/docs/tools.md) | Every built-in tool, stdio MCP servers, `SKILL.md` |
+| [Reviewing changes](https://github.com/eppen/luban/blob/main/docs/review.md) | Editor diff, per-hunk accept / reject |
+| [Sessions and memory](https://github.com/eppen/luban/blob/main/docs/sessions.md) | History layout, tabs, multi-turn memory, message queue |
+| [How it works](https://github.com/eppen/luban/blob/main/docs/internals.md) | Request flow, tool-loop budgets, prefix caching, usage, dashboard |
+| [Configuration](https://github.com/eppen/luban/blob/main/docs/configuration.md) | Provider panel, `providers.json`, all settings, code layout |
+| [Known limitations](https://github.com/eppen/luban/blob/main/docs/limitations.md) | What is deliberately not supported |
+| [Troubleshooting](https://github.com/eppen/luban/blob/main/docs/troubleshooting.md) | Symptom → cause → fix |
+| [Verification](https://github.com/eppen/luban/blob/main/docs/verification.md) | Test results per release |
+| [Debugging and release](https://github.com/eppen/luban/blob/main/docs/development.md) | Headless `op` channel, release pipeline |
+| [Changelog](https://github.com/eppen/luban/blob/main/docs/changelog.md) | Per-version changes |
+
+## 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).
+
+## License
+
+Apache-2.0 © 2026 eppen (liuhualiang). See [LICENSE](https://github.com/eppen/luban/blob/main/LICENSE) and [NOTICE](https://github.com/eppen/luban/blob/main/NOTICE).
+
+The Luban name and icon are not licensed under Apache-2.0.

package/README.zh.md

@@ -0,0 +1,151 @@
+# Luban（鲁班）
+
+[![VS Marketplace](https://img.shields.io/visual-studio-marketplace/v/liuhualiang.luban?label=marketplace)](https://marketplace.visualstudio.com/items?itemName=liuhualiang.luban)
+[![Installs](https://img.shields.io/visual-studio-marketplace/i/liuhualiang.luban?label=installs)](https://marketplace.visualstudio.com/items?itemName=liuhualiang.luban)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
+
+VSCodium / VS Code 里的**侧边栏 AI 编码助手**：说人话 → 它改文件、跑命令、自己验证，然后告诉你改了什么。
+零源码补丁（不动编辑器源码）：可以从 VS Code 市场 / Open VSX / VSIX 作为普通扩展安装，也可以用脚本装成 App 的内置扩展。
+
+版本 **1.23.2** · [English](README.md) · [全部文档](docs/README.md)
+
+<!-- 截图占位：把图片放进 media/screenshots/ 后，取消下面两行的注释 -->
+<!-- ![聊天面板与行内 diff](media/screenshots/panel.png) -->
+<!-- ![编辑器内的逐块审阅](media/screenshots/review.png) -->
+
+## 它是什么
+
+一个装在侧边栏里的编码 agent。你描述要做什么，它直接读写你工作区里的文件、跑命令验证，最后用一两句话汇报。
+
+**四个不一样的地方**
+
+- **审阅在编辑器里**：每写一个文件自动开出原生 diff，标题栏与两侧 CodeLens 逐块保留 / 撤销，聊天区只留一行摘要
+- **只读是真的只读**：Plan 模式下写文件的工具根本没注册，命令还要过一道只读校验，产出的计划落成 Markdown 文件，你改完再执行就按改后的走
+- **为省 token 而设计**：消息排布对齐前缀缓存（第 2 轮起通常 95%+ 命中），每轮显示输入 / 输出 / 缓存 / 上下文占用，另有本地账本与用量看板
+- **不挑模型**：任何 OpenAI 兼容端点（DeepSeek / Ollama / llama.cpp / vLLM…），API key 存 SecretStorage 不落盘
+
+**能做的事**
+
+- 生成代码：新建文件、整体重写
+- 修改代码：读原文 → 精确局部替换（不做"整文件重写"式瞎改）
+- 自我验证：写完自己跑 `node xxx.js` / `npx tsc --noEmit`，用真实输出说话
+- 先计划后执行：Plan 模式只读调研出计划，你确认了才动文件；命令面板也能读取 Cursor 的计划文件（`~/.cursor/plans/*.plan.md`）直接执行
+- 多 provider：DeepSeek / 任何 OpenAI 兼容端点，配置里加一段就行
+- 多轮记忆：同一会话里的追问会带上前几轮的提问与回答（只带正文，按轮数 / 字符预算自动裁剪）
+- 历史查询：会话弹层顶部有搜索框 —— 标题即时过滤，输入 2 个字以上连正文一起查（回答、工具结果、`@` 引用路径都能搜到），命中词高亮、命中行带一段摘要
+- 改历史：已发出的提问点气泡上的 `✎` 就能就地改，点「发送」自动截掉这条之后的记录并用改后的内容重新开跑一轮
+- 代码引用：`@` 选文件、`@` 选文件夹、`#` 引用编辑器选区；在编辑器里选中代码后右键「Add Selection to Luban Chat」（或 `Cmd/Ctrl+Alt+A`）可插入带位置与行号的 `#selection 路径:起始-结束`，多次选区、跨文件都能叠加，发送时各自展开成一份引用
+- 自动上下文：不写 `@` 也会把**本会话用过的文件**（`@` 引用过 / 带选区带过）的代码附在消息末尾（有选区给选区，否则光标附近约 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 = 不限）
+- 每轮 usage：回答下方一行显示输入 / 输出 / 缓存命中 / 上下文占用 / 请求数，header 常驻上下文占用条（按模型窗口算百分比）
+- 外部工具：本地 stdio MCP server 的工具并入同一个工具循环（`mcp__<server>__<tool>`），Plan 模式只放行声明只读的工具
+- 技能：扫描 `~/.luban/skills`、`~/.claude/skills`、`~/.cursor/skills` 与项目同名目录，把 `SKILL.md` 的 name/description 注入系统提示，模型需要时用 `read_skill` 读全文
+- 审阅改动：写完自动在编辑器开出 diff（标题栏「全部保留 / 全部撤销」+ 两侧 hunk 逐块 CodeLens）+ 行内 diff 高亮 + 侧边栏摘要卡片
+
+**不做的事**（要做就得 fork 编辑器源码，明确冻结）：next-edit prediction、向量语义检索。Tab 补全与本地词法检索已在 1.13.0 补上。
+
+**和原生 chat 的关系**：没有关系。它不注册 chatAgent、不占用原生聊天窗口、不需要 `@luban`，VS Code 怎么改 chat 层都影响不到它。
+
+## 安装
+
+| 途径 | 做法 |
+|---|---|
+| VS Code 官方市场 | 扩展面板搜 `Luban`，或 <https://marketplace.visualstudio.com/items?itemName=liuhualiang.luban> |
+| Open VSX（VSCodium 默认） | 扩展面板搜 `Luban` |
+| VSIX | 从 [Releases](https://github.com/eppen/luban/releases) 下载 `luban-v*.vsix`，扩展面板 `⋯` → **Install from VSIX…**；或命令行 `code --install-extension luban-v1.23.2.vsix`（VSCodium 用 `codium`） |
+| 内置扩展（仅 VSCodium） | `./install-into-vscodium.sh`，装成 App 级扩展；每次升级 VSCodium 后要重跑 |
+
+前置条件：
+
+- VS Code / VSCodium **1.100+**
+- `~/.luban/providers.json` 里至少配好一个 provider
+- 对应的 API key（环境变量或 `~/.hermes/.env`）；**本机端点免 key**（`localhost` / `127.x` 的 Ollama、llama.cpp、vLLM 等直接用）
+
+### 装成内置扩展（脚本）
+
+```bash
+cd ~/luban
+./install-into-vscodium.sh                  # 默认装到 ~/Applications/VSCodium.app
+# 或指定路径：./install-into-vscodium.sh /Applications/VSCodium.app
+```
+
+脚本做四件事：
+
+1. 复制扩展到 `VSCodium.app/Contents/Resources/app/extensions/luban`
+2. 备份 `product.json`（`.orig`，只备一次）并把 `nameShort` / `nameLong` 改成 `Luban`
+3. 删掉 `~/.vscode-oss/extensions/` 下的同名副本和 `extensions.json`
+4. 提示你重启
+
+重启后侧边栏会**自动打开**（可用设置项 `luban.autoOpen` 关掉）。这种方式不跟随市场自动更新，日常建议用市场版。
+
+## 快速开始
+
+1. **配 provider**：面板底部 **⚙**（或命令面板 `Provider settings`），填 `baseUrl` / 模型 / API key，点「测试连接」
+2. **打开面板**：活动栏 Luban 图标，或 `Cmd+Shift+L`
+3. **提需求**：`新建 utils.js，导出 debounce(fn, ms) 和 throttle(fn, ms)，然后用 node 测一下两者行为`
+
+也可以手改 `~/.luban/providers.json`（改完跑命令 `Reload providers.json` 热重载）：
+
+```json
+{
+  "defaultModel": "deepseek::deepseek-flash",
+  "providers": [
+    {
+      "id": "deepseek",
+      "name": "DeepSeek",
+      "baseUrl": "https://api.deepseek.com/v1",
+      "apiKeyEnv": "DEEPSEEK_API_KEY",
+      "models": [
+        { "id": "deepseek-flash", "name": "DeepSeek Flash",
+          "maxInputTokens": 65536, "maxOutputTokens": 8192, "toolCalling": true }
+      ]
+    }
+  ]
+}
+```
+
+字段、key 解析顺序、Ollama 等本地端点的注意事项见 [配置](docs/configuration.md)。
+
+## 三档模式
+
+| 模式 | 能做什么 |
+|---|---|
+| **Agent** | 读写文件、跑命令、自己验证；需要外部信息时自己联网 |
+| **Plan** | 只读调研，产出「目标 / 现状 / 步骤 / 验证方式 / 风险」计划并落盘，点「▶ 执行这个计划」才动文件 |
+| **Chat** | 纯问答，不碰文件；带 `@web` 时先联网搜索再回答 |
+
+## 文档
+
+市场页面只渲染 `README.md`，细节都在 [docs/](docs/README.md)：
+
+| 文档 | 内容 |
+|---|---|
+| [用法与能力](docs/usage.md) | 快捷键、三档模式、Plan 计划文件、`@` `#` 引用、联网搜索 |
+| [工具集、MCP 与技能](docs/tools.md) | 每个内置工具的参数与限制、stdio MCP、`SKILL.md` |
+| [审阅变更](docs/review.md) | 编辑器内 diff、逐块保留 / 撤销 |
+| [会话、多轮记忆与消息队列](docs/sessions.md) | 会话落盘、多标签、记忆派生、排队接力 |
+| [工作原理与内部机制](docs/internals.md) | 请求链路、工具循环闸门、前缀缓存、usage、用量看板 |
+| [配置](docs/configuration.md) | Provider 面板、`providers.json`、全部设置项、代码结构 |
+| [已知限制](docs/limitations.md) | 功能冻结后明确不做的部分 |
+| [竞品对比](docs/competitive-analysis.zh.md) | 同类编码 agent 的对比矩阵、差异点与短板 |
+| [常见故障处理](docs/troubleshooting.md) | 按现象查原因 |
+| [验证记录](docs/verification.md) | 各版本的真机 / 桩测试结果 |
+| [调试、无头验证与发布](docs/development.md) | 无头 `op` 列表、维护者发布流程 |
+| [变更历史](docs/changelog.md) | 按版本记录的改动要点 |
+
+## 安全须知
+
+`run_command` 跑的就是**你本机的 shell**，没有 OS 级沙箱；Plan 模式额外加一道启发式只读校验。文件工具默认允许操作工作区外的路径（`luban.fs.allowOutsideWorkspace=false` 可收回）。MCP server 是权限等同当前用户的子进程，只配置可信 server。详见 [已知限制](docs/limitations.md)。
+
+## 许可
+
+Apache-2.0 © 2026 eppen (liuhualiang)
+
+版权与归属声明见 `NOTICE`；名称与图标不随 Apache-2.0 授权。
+
+本协议自 1.7.1 起生效。