@saifymatteo/pi-x-ide 0.0.0-stage → 1.20.2

package/docs/zh-CN/explanation/effect.md

@@ -0,0 +1,90 @@
+# Effect 采用说明
+
+Pi × IDE 在 Pi 侧把 [Effect](https://effect.website/) 当作**实现细节**，用于结构化失败、Schema 校验与可组合的异步流程。VS Code、测试与 Pi host 回调使用的公开 API 仍保持 Promise / 同步友好。本文面向改动 `src/shared/*` 或 `src/pi/*` 的贡献者。
+
+## 为什么在这里用 Effect
+
+- **结构化错误** — tagged 失败（如 `LockFileParseError`、连接 / 安装错误）携带字段，避免靠字符串解析。
+- **Schema 解码** — lock file、selection、diagnostic 载荷共用校验路径（`effect-schema` → `schema.ts` 适配层）。
+- **边界控制** — discovery、host resolve、install、connect、reconnect、Zed 轮询等 IO 可在进程边界 fail-closed 或 log-and-swallow。
+
+Effect 不是产品功能，终端用户无需配置。
+
+## 边界规则
+
+- **禁止** 把 Effect 失败抛进 Pi host 回调或 VS Code activation。
+- 在边界用 `Effect.runPromise` / `Effect.runSync`、Phase 1 runner（`runEffect` / `runEffectSync`）或 Pi 助手（`runPiEffect`）退出 Effect。
+- Pi 边界失败时：经 `logExtensionError` / `containPiError` 上报（走 pi `ui.notify`，不写 `console`）；可选设置 `runtime.connectionStatus = "error"`。
+- **中断**（reconnect / Zed poll fiber）视为取消，不是 UI error。
+
+`authToken` 只出现在 WebSocket 升级头。不要把 token 或完整 lock JSON 写进日志、Effect 错误消息或 `scope` 字符串。
+
+## 模块地图
+
+| 模块                                                                                                       | 作用                                                                                |
+| ---------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
+| `src/shared/effect-errors.ts`                                                                              | `Data.TaggedError` 领域错误（可读 `message`）                                       |
+| `src/shared/effect-runtime.ts`                                                                             | `runEffect` / `runEffectSync`（吞失败并打日志）；`runEffectOrThrow`（测试）         |
+| `src/shared/effect-schema.ts`                                                                              | Effect Schema 定义与 `decode*`                                                      |
+| `src/shared/schema.ts`                                                                                     | 稳定的 `is*` / `parse*` 门面                                                        |
+| `src/shared/jsonrpc-guard.ts`                                                                              | 无 Effect 的 `isJsonRpcRequest`，供 VS Code `ide-server` 依赖图使用                 |
+| `src/pi/index.ts`、`commands.ts`、`context.ts`、`ui.ts`、`state.ts`、`safety.ts`、`diagnostic-renderer.ts` | 轻量静态壳：注册、状态 UI、本地 diagnostic 渲染器、错误收敛（无 Effect、无 pi-tui） |
+| `src/pi/config-ui.ts`                                                                                      | Settings 对话框（pi-tui）；仅由 `/ide settings` 动态导入加载                        |
+| `src/pi/runtime-loader.ts`                                                                                 | 重型 runtime 动态边界：缓存的 `import("./runtime-services.js")`                     |
+| `src/pi/runtime-services.ts`                                                                               | 重型生命周期：discovery/install/connect/reconnect/Zed（可导入 Effect）              |
+| `src/pi/effect-boundary.ts`                                                                                | `runPiEffect` → `containPiError` + UI 状态（导入 Effect runtime）                   |
+| `src/pi/safety.ts`                                                                                         | 无 Effect 的 `containPiError`、`runPiBoundary`、`runPiBoundaryAsync`                |
+| `src/pi/discovery.ts`、`ide-host.ts`、`install.ts`                                                         | Effect 程序 + Promise 门面                                                          |
+| `src/pi/connection.ts`                                                                                     | 连接握手 Effect；tagged timeout 映射为 `IdeConnectionTimeoutError`                  |
+| `src/pi/reconnect.ts`、`zed.ts`                                                                            | reconnect 延迟与 Zed 轮询的可中断 fiber                                             |
+
+VS Code 仍通过 `@shared/*` 引入必须保持无 Effect 的路径（`jsonrpc-guard`、protocol、lock-file 辅助）。若把 `effect-schema` 拉进 VS Code 包体，属于 escape hatch 失败：解码应留在 Pi 侧，或在包体膨胀时拆分 guard。
+
+### Pi 启动壳与重型 runtime
+
+- 发布的 Pi 入口是 esbuild code-split ESM 壳（`dist/src/pi/index.js`），Effect / `ws` / `node:sqlite` 只出现在指向 lazy chunk 的 **dynamic-import** 边上。
+- `runtime-loader.ts` 是重型生命周期（`runtime-services.ts`）的动态边界。`effect-boundary.ts` 可导入 Effect；静态壳不得导入。
+- `/ide settings` 是第二道懒加载边界：`commands.ts` 仅在 settings 子命令执行时动态导入 `config-ui.ts`，从而把 `pi-tui`（SettingsList 等）排除在静态壳依赖图之外。由于 lazy chunk 打包了独立的 pi-tui 代码，它会使用 `ctx.ui.custom()` 注入的 keybinding manager 初始化该副本，使用户自定义键位继续生效。
+- diagnostic 消息渲染器是**本地**、符合 Component 形状（`render` / `invalidate`）的实现，因此静态壳不会产生指向 `@earendil-works/pi-tui` 的 runtime edge。Config UI 使用本地 `DynamicBorder`，避免 coding-agent 的 value import。
+- **Host package runtime edge 禁止规则：** 所有生成的 Pi entry JS 产物（静态入口与 lazy chunk）都不得出现对 `@earendil-works/pi-coding-agent` 或 `@earendil-works/pi-tui` 的 runtime external import。type-only 导入可以；原生 ESM 中的 value import 会绕过 Pi 的 jiti alias，导致 host 包重复加载。bundler 的 metafile gate 会在残留任何 host external edge 时让构建失败。`pi-tui` 打进 settings 的 lazy chunk；coding-agent 仍可保留在 esbuild `external` 列表供未来检查，但产物中不得出现其 runtime edge。
+- 在静态壳中新增 Effect、重型 runtime 或 host package 的 value 静态导入属于**启动回归**。topology / size gate 会在静态入口出现重型静态依赖、或任何产物重新引入 host runtime external edge 时让构建失败。
+
+## 导入风格
+
+优先 Effect 子路径导入以便 tree-shaking：
+
+```ts
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import * as Data from "effect/Data";
+import * as Fiber from "effect/Fiber";
+```
+
+## 错误标记约定
+
+- 使用 `effect-errors.ts` 中已有 tag（或在真正需要的 phase 再新增）。
+- 覆盖 `message`，让默认日志可读，且不泄露密钥。
+- 现有代码用 `instanceof` 检查的 Promise 门面（如 `IdeConnectionTimeoutError`）必须把 tagged 失败映射回这些 class。
+
+## 仍保持 Promise / 同步的部分
+
+- 导出的 discovery、install、connect、host-resolve 入口。
+- `IdeConnection` 类方法与回调模型。
+- VS Code extension activation 与共享 IDE WebSocket server。
+- 纯函数：排序、版本比较、路径匹配、Zed snapshot SQL。
+
+重型 runtime（`runtime-services.ts` 及其下游）的调用点应继续使用 Promise 门面，除非某条路径明确改用 `effect-boundary.ts` 中的 `runPiEffect`。轻量静态壳不得导入 `effect-boundary.ts` 或 Effect 模块。
+
+## 非目标
+
+- 用完整 `Layer` DI 重写扩展入口。
+- 重写 JetBrains Kotlin / Neovim Lua。
+- 强制把 `node:test` 换成 `@effect/vitest`。
+- 变更 on-wire 协议或 lock-file JSON 形状。
+- 为 Effect 演示增加 mock / 假数据路径。
+
+## 相关
+
+- [架构](architecture.md) — 进程角色与数据流。
+- [发现机制](discovery.md) — lock 排序（行为不因 Effect 改变）。
+- 实现计划：[effect-adoption-plan](../../plans/effect-adoption-plan/)。

package/docs/zh-CN/how-to/install-jetbrains.md

@@ -0,0 +1,49 @@
+# 安装 JetBrains 插件
+
+Pi × IDE 通过 Marketplace 插件集成 IntelliJ IDEA、PyCharm、WebStorm 等 JetBrains IDE。
+
+## 前置条件
+
+- 已安装 [`pi`](https://github.com/earendil-works/pi-coding-agent) CLI。
+- 已安装 Pi 包：`pi install npm:pi-x-ide`。
+- JetBrains IDE（建议 2024.2 或更高）。
+
+## 从 JetBrains Marketplace 安装
+
+1. 在 IDE 中打开 **Settings / Preferences -> Plugins -> Marketplace**。
+2. 搜索 `balaenis.pi-x-ide`。
+3. 点击 **Install**，按提示重启 IDE。
+
+插件也列在 [JetBrains Marketplace](https://plugins.jetbrains.com/plugin/32664-pi-x-ide)。
+
+## 验证连接
+
+1. 在 JetBrains IDE 中打开项目。
+2. 在该项目中打开终端并启动 Pi：
+
+   ```bash
+   pi
+   ```
+
+3. 打开源文件并选中文本。Pi widget 应显示：
+
+   ```
+   ⧉ ⇡ foo.ts#L10-L20
+   ```
+
+如果 widget 没出现，见 [排查连接问题](troubleshoot-connection.md)。
+
+## 附加选区
+
+在编辑器中选中文本后，任选其一：
+
+- 按 `Ctrl+Alt+K`（Linux/Windows）或 `Cmd+Alt+K`（macOS）。
+- 在 Find Action 对话框（`Ctrl+Shift+A` / `Cmd+Shift+A`）中运行 **Pi x IDE: Attach Selection**。
+
+Pi 把 `@relative/path#Lx-Ly` 插入输入框。提交消息即可把选中文本作为 LLM 上下文发送。
+
+## 注意
+
+- JetBrains 对非空选区和"有活跃文件但无选中文本"两种情况都会发送选区通知。
+- 诊断 Quick Fix 和自动安装是 VS Code 系列功能，JetBrains 不支持。见 [功能对比](../reference/feature-parity.md)。
+- 本地开发和 sandbox 测试见 [CONTRIBUTING.zh-CN.md](../../../CONTRIBUTING.zh-CN.md)。

package/docs/zh-CN/how-to/install-neovim.md

@@ -0,0 +1,126 @@
+# 安装 Neovim 插件
+
+Neovim 支持由一个 Lua 插件加一个 **sidecar** 进程组成。插件观察编辑器和选区；sidecar 持有 Pi 连接的 WebSocket 服务器。sidecar 二进制首次启动时自动下载，并提供 Node.js 回退。
+
+## 前置条件
+
+- 已安装 [`pi`](https://github.com/earendil-works/pi-coding-agent) CLI。
+- 已安装 Pi 包：`pi install npm:pi-x-ide`。
+- Neovim ≥ 0.9。
+
+## 用 lazy.nvim 安装
+
+```lua
+{
+  "saifymatteo/pi-x-ide",
+  build = function(plugin)
+    vim.opt.rtp:prepend(plugin.dir .. "/ide-plugins/nvim")
+    require("pi_x_ide.download").run({ refresh = true })
+  end,
+  init = function(plugin)
+    vim.opt.rtp:prepend(plugin.dir .. "/ide-plugins/nvim")
+  end,
+  main = "pi_x_ide",
+  opts = {
+    keymap = "<leader>aa",
+  },
+}
+```
+
+> **注意：** `init` 块将插件子目录加入 runtime path，以规避部分版本 lazy.nvim 的 Lua 模块解析兼容性问题。可选的 `build` 钩子会预下载 sidecar 二进制；可以省略 - 插件会在首次启动时按需下载。
+
+## 作为原生 package 安装
+
+```vim
+set runtimepath+=/path/to/pi-x-ide/ide-plugins/nvim
+lua require("pi_x_ide").setup({ keymap = "<leader>pa" })
+```
+
+## 验证连接
+
+1. 在 Neovim 中打开项目。
+2. 在该项目中打开终端并启动 Pi：
+
+   ```bash
+   pi
+   ```
+
+3. 打开文件并选中文本（visual 模式）。Pi widget 应显示：
+
+   ```
+   ⧉ ⇡ foo.ts#L10-L20
+   ```
+
+如果 widget 没出现，见 [排查 sidecar](#排查-sidecar) 和 [排查连接问题](troubleshoot-connection.md)。
+
+## 附加选区
+
+选中文本后，按配置的 `keymap`（默认 `<C-A-k>`），或运行：
+
+```vim
+:PiXIdeAttach
+```
+
+Pi 把 `@relative/path#Lx-Ly` 插入输入框。提交消息即可把选中文本作为 LLM 上下文发送。
+
+## 配置
+
+```lua
+require("pi_x_ide").setup({
+  enabled = true,
+  keymap = "<C-A-k>",
+  debounce_ms = 150,
+  -- sidecar_cmd = { "node", "/absolute/path/to/pi-x-ide-nvim-sidecar.cjs" },
+  -- workspace_folders = { "/path/to/project" },
+})
+```
+
+| 选项                | 默认值    | 说明                                |
+| ------------------- | --------- | ----------------------------------- |
+| `enabled`           | `true`    | 启用或禁用插件。                    |
+| `keymap`            | `<C-A-k>` | 附加当前选区到 Pi 的快捷键。        |
+| `debounce_ms`       | `150`     | 选区通知去抖间隔。                  |
+| `sidecar_cmd`       | （自动）  | 覆盖 sidecar 命令。                 |
+| `workspace_folders` | （自动）  | 覆盖向 Pi 广播的 workspace 文件夹。 |
+
+## 命令
+
+| 命令            | 行为                                                    |
+| --------------- | ------------------------------------------------------- |
+| `:PiXIdeStart`  | 启动 sidecar 并写入 lock file。                         |
+| `:PiXIdeStop`   | 停止 sidecar 并移除 lock file。                         |
+| `:PiXIdeStatus` | 显示 sidecar 是否正在运行。                             |
+| `:PiXIdeAttach` | 将当前文件或选区作为 `@relative/path#Lx-Ly` 附加到 Pi。 |
+
+## sidecar 的解析顺序
+
+插件按以下顺序解析 sidecar：
+
+1. `ide-plugins/nvim/bin/` 中的平台二进制。
+2. 从 GitHub Releases 下载并缓存、经 SHA256 校验的二进制。
+3. 回退到 Node.js 脚本（`pi-x-ide-nvim-sidecar.cjs`）。
+
+sidecar 为何存在见 [架构](../explanation/architecture.md#neovim-sidecar)。
+
+## 排查 sidecar
+
+如果 widget 始终不出现，很可能是 sidecar 启动失败。
+
+1. 运行 `:PiXIdeStatus` 查看 sidecar 是否在运行。
+2. 检查 lock file 是否已写入：
+
+   ```bash
+   ls -l ~/.pi/pi-x-ide/lock
+   ```
+
+   应看到类似 `nvim-<pid>-<port>.lock` 的文件。如果没有，说明 sidecar 未启动。
+
+3. 如果二进制下载失败，显式把 `sidecar_cmd` 指向 Node 回退：
+
+   ```lua
+   require("pi_x_ide").setup({
+     sidecar_cmd = { "node", "/path/to/pi-x-ide/ide-plugins/nvim/bin/pi-x-ide-nvim-sidecar.cjs" },
+   })
+   ```
+
+4. 依赖回退时，确保 `node` 在 `PATH` 中。

package/docs/zh-CN/how-to/install-vscode.md

@@ -0,0 +1,67 @@
+# 安装 VS Code 扩展
+
+Pi × IDE 通过一个扩展集成 VS Code、Cursor 和 Windsurf。本指南介绍三种安装方式和连接验证。
+
+## 前置条件
+
+- 已安装 [`pi`](https://github.com/earendil-works/pi-coding-agent) CLI。
+- 已安装 Pi 包：`pi install npm:pi-x-ide`。
+- VS Code、Cursor 或 Windsurf。
+
+## 方式一：从 Marketplace 安装（推荐）
+
+在 IDE 的 **扩展** 面板搜索
+[`balaenis.pi-x-ide`](https://marketplace.visualstudio.com/items?itemName=balaenis.pi-x-ide)
+并安装。安装后重新加载窗口。
+
+## 方式二：通过 Pi CLI 安装
+
+在 Pi TUI 中运行：
+
+```
+/ide install
+```
+
+Pi 自动检测 `PATH` 中的 `code`、`cursor` 或 `windsurf` CLI，并对其执行 `--force --install-extension`。
+
+## 方式三：Pi 启动时自动安装
+
+当 Pi 从受支持的 VS Code 集成终端启动时，会异步尝试自动安装或更新扩展。默认开启。如需关闭：
+
+```bash
+PI_X_IDE_AUTO_INSTALL=0
+```
+
+所有 Pi 侧选项见 [配置参考](../reference/configuration.md)。
+
+## 验证连接
+
+1. 在 IDE 中打开项目文件夹。
+2. 在该项目文件夹中打开集成终端并启动 Pi：
+
+   ```bash
+   pi
+   ```
+
+3. 打开源文件并选中文本。Pi widget 应显示：
+
+   ```
+   ⧉ ⇡ foo.ts#L10-L20
+   ```
+
+如果 widget 没出现，见 [排查连接问题](troubleshoot-connection.md)。
+
+## VS Code 设置
+
+| 键               | 类型      | 默认值  | 说明                                                                                    |
+| ---------------- | --------- | ------- | --------------------------------------------------------------------------------------- |
+| `piXIde.useTmux` | `boolean` | `false` | 通过终端图标用 `tmux` 打开 Pi。每次点击都会创建一个新 session，终端 detach 后自动销毁。 |
+
+## 诊断 Quick Fix
+
+将光标放在 error 或 warning 上，打开 Quick Fix（`Ctrl+.`），选择：
+
+- **Pi: Fix it** - 把诊断信息发送给 Pi 并启动分析对话。
+- **Pi: Send diagnostic** - 把诊断上下文粘贴到 Pi 输入框，不启动对话。
+
+**Pi: Fix it** 使用的 prompt 前缀可通过 `fixPrompt` 配置。见 [配置](../reference/configuration.md#顶层选项)。

package/docs/zh-CN/how-to/install-zed.md

@@ -0,0 +1,56 @@
+# 在 Zed 中使用 Pi × IDE
+
+Zed 无需扩展。Pi 在 Zed 终端中运行时自动检测，并读取 Zed 本地状态数据库来追踪活跃文件和选区。
+
+## 前置条件
+
+- 已安装 [`pi`](https://github.com/earendil-works/pi-coding-agent) CLI。
+- 已安装 Pi 包：`pi install npm:pi-x-ide`。
+- 已安装 Zed。
+
+## 连接
+
+1. 在 Zed 中打开项目文件夹。
+2. 在 Zed 中打开终端（`Zed -> Terminal -> New Terminal`）并启动 Pi：
+
+   ```bash
+   pi
+   ```
+
+Pi 检测到 Zed 环境（`ZED_TERM=true` 或 `TERM_PROGRAM=zed`）后开始轮询 Zed 的 SQLite 数据库。Pi 输入框上方出现 widget，显示活跃文件和选区。
+
+## 验证是否正常
+
+在 Zed 中打开文件并选中文本，widget 应实时更新：
+
+```
+⧉ ⇡ foo.ts#L10-L20
+```
+
+聚焦 Pi TUI 并按 `Ctrl+Alt+K`（macOS：`Ctrl+Option+K`），把选区作为 `@src/foo.ts#L10-L20` 插入，然后提交消息。
+
+## 追踪原理
+
+Zed 没有扩展 API，Pi 直接从本地 SQLite 数据库读取编辑器状态。轮询默认每 1000 ms 一次，数据库 WAL 文件未变化时跳过本次。详见 [架构](../explanation/architecture.md#zed-轮询)。
+
+## 配置
+
+| 环境变量                        | 默认值       | 说明                                     |
+| ------------------------------- | ------------ | ---------------------------------------- |
+| `PI_X_IDE_ZED_DB`               | （自动检测） | 覆盖 Zed SQLite 数据库路径。             |
+| `PI_X_IDE_ZED_POLL_INTERVAL_MS` | `1000`       | 轮询间隔（毫秒），限制在 100–2000 范围。 |
+
+默认数据库路径：
+
+- **Linux：** `~/.local/share/zed/db/0-stable/db.sqlite`
+- **macOS：** `~/Library/Application Support/Zed/db/0-stable/db.sqlite`
+- **Windows：** `%LOCALAPPDATA%\Zed\db\0-stable\db.sqlite`
+- **WSL + Windows 版 Zed：** `/mnt/c/Users/<user>/AppData/Local/Zed/db/0-stable/db.sqlite`
+
+这些变量可设为真实环境变量或写入 `~/.pi/pi-x-ide/config.json` 的 `env`。见 [配置](../reference/configuration.md)。
+
+## 注意
+
+- Zed 基于 **轮询**，widget 最多每个轮询间隔更新一次，而非每次按键。
+- IDE 侧附加快捷键（VS Code/JetBrains 中的 `Ctrl+Alt+K`）在 Zed 中不可用 - 请用 Pi TUI 快捷键。
+- 诊断 Quick Fix 和自动安装是 VS Code 系列功能，Zed 不支持。见 [功能对比](../reference/feature-parity.md)。

package/docs/zh-CN/how-to/troubleshoot-connection.md

@@ -0,0 +1,85 @@
+# 排查连接问题
+
+Pi widget 不出现，或显示无 IDE 连接。按以下顺序排查。
+
+## 1. 确认两侧都在运行
+
+- IDE 扩展/插件已安装，且安装后已重新加载窗口。
+- Pi 是 **从 IDE workspace 文件夹内的终端**（或同一项目目录）启动的。
+
+如果 IDE 在 Pi **之后** 启动，重新加载 IDE 窗口让它写入 lock file，然后在 Pi 中重新匹配：
+
+```
+/ide auto
+```
+
+## 2. 检查 lock file
+
+IDE 插件把 lock file 写到 `~/.pi/pi-x-ide/lock/`。列出目录：
+
+```bash
+ls -l ~/.pi/pi-x-ide/lock
+```
+
+应看到类似 `vscode-12345-48123.lock`、`nvim-98765-50001.lock` 或 `jetbrains-4242-51234.lock` 的文件。
+
+- **完全没有文件：** IDE 扩展未运行。重新加载 IDE 窗口或重启 IDE。VS Code 可执行 **Developer: Reload Window**。
+- **文件存在但 Pi 未连接：** 继续第 3 步。
+
+## 3. 检查工作目录匹配
+
+Pi 仅在终端 `cwd` **位于** IDE workspace 文件夹内时自动连接。如果在父目录（例如 `~/`）启动 Pi，没有精确匹配。任选其一：
+
+- 从项目目录内重启 Pi，或
+- 运行 `/ide` 打开选择器手动选择连接，或
+- 运行 `/ide auto` 重新匹配。
+
+## 4. 查看连接状态
+
+运行：
+
+```
+/ide status
+```
+
+显示当前连接、workspace 和最近选区。若报告无连接，运行 `/ide list` 查看 Pi 找到的候选 lock file。
+
+## 5. 过期或死进程 lock file
+
+如果上一个 IDE 实例崩溃，lock file 可能残留。当权威的 PID 或 WSL TCP 活性检查成功时，Pi 会保留 lock。仅当权威活性不可用或被禁用时，Pi 才按年龄清理。
+
+活动中的 VS Code、Neovim 或 JetBrains 生产者通常会在下一次 15 分钟心跳时重建被外部删除的 lock。机制说明见 [发现机制](../explanation/discovery.md)。
+
+手动删除 lock file 之前，先确认 IDE 已停止：
+
+```bash
+rm ~/.pi/pi-x-ide/lock/*.lock
+```
+
+然后重新加载或重启生产者，再运行 `/ide auto`。
+
+> 如果 IDE 仍在 Windows 上运行，**不要**从 WSL 手动删除 Windows 侧的 lock file - Pi 用 `runningInWindows: true` 安全地探测它们。
+
+## 6. Neovim sidecar 未启动
+
+对 Neovim，widget 依赖 sidecar 进程。见 [安装 Neovim 插件 -> 排查 sidecar](install-neovim.md#排查-sidecar)。
+
+## 7. WSL2 跨边界问题
+
+如果 Pi 在 WSL、IDE 在 Windows，受限网络下自动 host 发现可能失败。设置 `PI_X_IDE_HOST_OVERRIDE` - 见 [在 WSL2 中使用](use-wsl2.md#自动发现失败时)。
+
+## 禁用集成
+
+如果需要临时停止 Pi 附加 IDE 上下文：
+
+```
+/ide off
+```
+
+断开并关闭自动上下文附加。运行 `/ide auto` 可重新启用。
+
+## 仍未解决
+
+- [发现机制](../explanation/discovery.md) - 匹配和 host 解析规则。
+- [`/ide` 命令参考](../reference/commands.md) - 所有可用命令。
+- [架构](../explanation/architecture.md) - 组件和数据流。

package/docs/zh-CN/how-to/use-wsl2.md

@@ -0,0 +1,75 @@
+# 在 WSL2 中使用 Pi × IDE
+
+当 Pi 运行在 WSL2 内、IDE 运行在原生 Windows 上时，Pi × IDE 会自动跨 WSL 边界发现 IDE 连接。本指南介绍常见场景和受限网络下的手动覆盖。
+
+## 前置条件
+
+- WSL 内已安装 [`pi`](https://github.com/earendil-works/pi-coding-agent) CLI。
+- 已安装 Pi 包：`pi install npm:pi-x-ide`。
+- Windows 上运行 IDE（VS Code、Cursor、Windsurf 或 JetBrains），并已安装 `pi-x-ide` 扩展/插件。
+
+## 连接
+
+1. 在 Windows IDE 中打开项目。
+2. 在 WSL 内 `cd` 到同一项目目录并启动 Pi：
+
+   ```bash
+   cd /mnt/c/Users/you/project
+   pi
+   ```
+
+Pi 同时扫描 Linux home 的 lock 目录和 Windows 用户目录的 lock 目录。发现 Windows lock file（`runningInWindows: true`）时，自动解析可达 host（见下文）并连接。widget 出现在 Pi 输入框上方。
+
+## host 如何解析
+
+lock file 的 `host` 是 `127.0.0.1`，对 Windows 上的 IDE 进程正确，但从 WSL 内部不可达。Pi 按以下顺序解析可用 host：
+
+1. **`PI_X_IDE_HOST_OVERRIDE`** - 若设置则直接使用。
+2. **WSL 默认网关** - 从 `ip route show` 解析，仅当对 `<gateway>:<port>` 的短 TCP 探测成功时使用。
+3. lock file 的 `host` 值，最后回退到 `127.0.0.1`。
+
+大多数配置下第 2 步即可处理，无需任何设置。完整说明见 [发现机制](../explanation/discovery.md#解析连接-host)。
+
+## 自动发现失败时
+
+如果你的 WSL 网络模式、防火墙或终端安全策略阻止了网关探测，Pi 无法到达 IDE。请显式覆盖 host。
+
+### 同机、mirrored/localhost 网络
+
+```bash
+PI_X_IDE_HOST_OVERRIDE=127.0.0.1 pi
+```
+
+### NAT 网络 - 使用 Windows host IP
+
+```bash
+PI_X_IDE_HOST_OVERRIDE=<windows-host-ip> pi
+```
+
+从 WSL 默认网关获取 Windows host IP：
+
+```bash
+ip route show | grep default
+# default via 172.x.x.1 dev eth0
+```
+
+用网关地址（`172.x.x.1`）作为 `<windows-host-ip>`。
+
+### 持久化覆盖
+
+把变量写入 `~/.pi/pi-x-ide/config.json` 而非 shell：
+
+```json
+{
+  "env": {
+    "PI_X_IDE_HOST_OVERRIDE": "172.x.x.1"
+  }
+}
+```
+
+完整环境变量参考见 [配置](../reference/configuration.md)。
+
+## 注意
+
+- 来自 Windows IDE 的路径会先规范化为 Linux 路径再匹配 workspace，所以 `/mnt/c/...` 和 `C:\...` 都能匹配你的 WSL 项目目录。
+- 运行在 Windows 上的 Zed 也可跨 WSL 发现；其数据库从 `/mnt/c/Users/<user>/AppData/Local/Zed/db/0-stable/db.sqlite` 读取。需要时用 `PI_X_IDE_ZED_DB` 覆盖。

package/docs/zh-CN/reference/commands.md

@@ -0,0 +1,54 @@
+# `/ide` 命令参考
+
+Pi × IDE 在 Pi TUI 中注册 `/ide` 命令族，用于管理 IDE 连接。
+
+| 命令            | 行为                                                |
+| --------------- | --------------------------------------------------- |
+| `/ide`          | 打开 TUI 选择器，列出可用 IDE 连接。                |
+| `/ide status`   | 显示当前连接、workspace 和最近选区。                |
+| `/ide list`     | 列出 lock 目录中的候选连接。                        |
+| `/ide auto`     | 重新按 cwd 自动匹配，匹配成功时连接。               |
+| `/ide off`      | 断开并关闭自动上下文附加。                          |
+| `/ide attach`   | 手动把最新选区范围插入输入框。                      |
+| `/ide install`  | 通过支持的 IDE CLI 安装或更新 `balaenis.pi-x-ide`。 |
+| `/ide settings` | 打开 IDE 设置（`Display`、`AutoInstall` 等）。      |
+
+### `/ide settings`
+
+统一配置入口。布局：
+
+```text
+Settings:
+→ Display       widget      IDE 状态显示位置：widget 或 statusline
+  AutoInstall   true        启动时自动安装 VS Code 系扩展
+```
+
+| 设置          | 取值                    | 配置键 / 环境变量           | 默认     |
+| ------------- | ----------------------- | --------------------------- | -------- |
+| `Display`     | `widget` / `statusline` | `status_display`            | `widget` |
+| `AutoInstall` | `true` / `false`        | `env.PI_X_IDE_AUTO_INSTALL` | `true`   |
+
+快捷键：
+
+| 按键     | 行为                     |
+| -------- | ------------------------ |
+| `↑`/`↓`  | 在设置项之间移动         |
+| `Space`  | 切换当前设置项的值       |
+| `Ctrl+S` | 将全部设置保存到全局配置 |
+| `Ctrl+P` | 将全部设置保存到项目配置 |
+| `Esc`    | 取消，不保存             |
+
+- **全局：** `~/.pi/pi-x-ide/config.json`
+- **项目：** `<cwd>/.pi/pi-x-ide/config.json`（覆盖全局）
+
+`Display` 会立即作用于当前 Pi session。见 [配置](configuration.md)。
+
+## 附加快捷键
+
+Pi 默认在 TUI 中注册 `Ctrl+Alt+K`，作为 `/ide attach` 的快捷键。重复按下会把最新选中的范围追加到当前输入框，因此可以在编辑器中多次选择不同文本并逐个附加。
+
+- **macOS：** 这是终端快捷键（`Ctrl+Option+K`）。`Cmd` 快捷键通常由终端或系统处理，Pi TUI 无法接收。
+- **自定义：** 设置 `PI_X_IDE_ATTACH_SHORTCUT` 为其他 pi key id。
+- **禁用：** 设置 `PI_X_IDE_ATTACH_SHORTCUT` 为 `off`、`none`、`false` 或 `0`。
+
+完整环境变量参考见 [配置](configuration.md)。