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

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

@@ -0,0 +1,94 @@
+# 配置参考
+
+Pi × IDE 通过三层配置：各 IDE 设置、Pi 侧环境变量，以及 config JSON 中的顶层选项。
+
+配置文件：
+
+- **全局：** `~/.pi/pi-x-ide/config.json`
+- **项目：** `<cwd>/.pi/pi-x-ide/config.json`（对支持的键覆盖全局）
+
+Pi 侧变量可设为真实环境变量 **或** 写入 config 的 `env`。真实环境变量优先级更高。交互设置（`Display`、`AutoInstall` 等）见 [`/ide settings`](commands.md)。
+
+```json
+{
+  "$schema": "https://raw.githubusercontent.com/saifymatteo/pi-x-ide/refs/heads/main/schemas/config.json",
+  "fixPrompt": "Analyze the errors and warnings at the following location, and try to fix them:\n{DIAGNOSTIC}",
+  "status_display": "widget",
+  "env": {
+    "PI_X_IDE_AUTO_INSTALL": "1",
+    "PI_X_IDE_ATTACH_SHORTCUT": "ctrl+alt+k"
+  }
+}
+```
+
+起始模板见 [`config.example.json`](../../../config.example.json)，编辑器 schema 见 [`schemas/config.json`](../../../schemas/config.json)。
+
+## VS Code 设置
+
+| 键               | 类型      | 默认值  | 说明                                                                                    |
+| ---------------- | --------- | ------- | --------------------------------------------------------------------------------------- |
+| `piXIde.useTmux` | `boolean` | `false` | 通过终端图标用 `tmux` 打开 Pi。每次点击都会创建一个新 session，终端 detach 后自动销毁。 |
+
+## Zed
+
+| 环境变量                        | 默认值       | 说明                                                |
+| ------------------------------- | ------------ | --------------------------------------------------- |
+| `PI_X_IDE_ZED_DB`               | （自动检测） | 覆盖 Zed SQLite 数据库路径。                        |
+| `PI_X_IDE_ZED_POLL_INTERVAL_MS` | `1000`       | Zed SQLite 轮询间隔（毫秒），限制在 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`
+
+## Neovim
+
+```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 文件夹。 |
+
+如果 sidecar 无法启动，请运行 `:PiXIdeStatus`，或设置 `sidecar_cmd` 为自定义命令。见 [安装 Neovim 插件](../how-to/install-neovim.md#排查-sidecar)。
+
+| 命令            | 行为                                                    |
+| --------------- | ------------------------------------------------------- |
+| `:PiXIdeStart`  | 启动 Neovim sidecar 并写入 lock file。                  |
+| `:PiXIdeStop`   | 停止 sidecar 并移除 lock file。                         |
+| `:PiXIdeStatus` | 显示 sidecar 是否正在运行。                             |
+| `:PiXIdeAttach` | 将当前文件或选区作为 `@relative/path#Lx-Ly` 附加到 Pi。 |
+
+## Pi 侧环境变量
+
+| 变量                            | 默认值       | 说明                                                                                                            |
+| ------------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------- |
+| `PI_X_IDE_AUTO_INSTALL`         | `1`          | Pi 启动时自动安装 VS Code 扩展。设为 `0`/`false`/`off` 可禁用。也可在 `/ide settings` 中以 `AutoInstall` 配置。 |
+| `PI_X_IDE_ATTACH_SHORTCUT`      | `ctrl+alt+k` | Pi TUI 的 `/ide attach` 快捷键。设为 `off`、`none`、`false` 或 `0` 可禁用。                                     |
+| `PI_X_IDE_HOST_OVERRIDE`        | （未设置）   | 覆盖 Pi 连接 IDE WebSocket 时使用的 host。适用于 WSL2 网络场景。                                                |
+| `PI_X_IDE_ZED_DB`               | （自动检测） | 覆盖 Zed SQLite 数据库路径。                                                                                    |
+| `PI_X_IDE_ZED_POLL_INTERVAL_MS` | `1000`       | Zed SQLite 轮询间隔（毫秒），限制在 100–2000 范围。                                                             |
+
+## 顶层选项
+
+<a id="顶层选项"></a>
+
+| 选项             | 默认值                                                                                          | 说明                                                                                                                                                                                    |
+| ---------------- | ----------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `fixPrompt`      | `Analyze the errors and warnings at the following location, and try to fix them:\n{DIAGNOSTIC}` | 请求修复 IDE 诊断信息时的自定义 prompt 前缀。使用 `{DIAGNOSTIC}` 作为诊断上下文的占位符。如果未包含占位符，诊断上下文会拼接在你的 prompt 之后。                                         |
+| `status_display` | `widget`                                                                                        | 在 Pi TUI 中显示 IDE 连接状态的位置。默认 `widget`（编辑器上方）；`statusline` 使用页脚状态行。同一时间只启用一种显示方式。项目配置覆盖全局。可在 `/ide settings` 中以 `Display` 设置。 |
+
+`fixPrompt` 控制 VS Code **Pi: Fix it** Quick Fix 使用的 prompt。见 [安装 VS Code 扩展](../how-to/install-vscode.md#诊断-quick-fix)。

package/docs/zh-CN/reference/feature-parity.md

@@ -0,0 +1,21 @@
+# 功能对比
+
+各编辑器集成支持的能力。
+
+| 功能                                      | VS Code              | Zed     | Neovim                   | JetBrains            |
+| ----------------------------------------- | -------------------- | ------- | ------------------------ | -------------------- |
+| 实时文件追踪                              | ✅ 实时推送          | ✅ 轮询 | ✅ 通过 sidecar 实时推送 | ✅ 实时推送          |
+| 实时选区追踪                              | ✅ 实时推送          | ✅ 轮询 | ✅ 通过 sidecar 实时推送 | ✅ 实时推送          |
+| IDE 上下文 attach 快捷键                  | ✅ 默认 `Ctrl+Alt+K` | ❌      | ✅ 自定义快捷键 keymap   | ✅ 默认 `Ctrl+Alt+K` |
+| Pi TUI attach 快捷键（默认 `Ctrl+Alt+K`） | ✅                   | ✅      | ✅                       | ✅                   |
+| LLM 上下文注入                            | ✅                   | ✅      | ✅                       | ✅                   |
+| `/ide auto`                               | ✅                   | ✅      | ✅                       | ✅                   |
+| 诊断 Quick Fix                            | ✅                   | ❌      | ❌                       | ❌                   |
+| 自动安装                                  | ✅ 仅 VS Code 系列   | N/A     | ❌                       | ❌                   |
+
+## 注意
+
+- **Zed** 没有扩展 API，文件和选区追踪基于轮询（默认 1000 ms）。见 [架构](../explanation/architecture.md#zed-轮询)。
+- **Neovim** 用 sidecar 进程承载 WebSocket 服务器；attach 快捷键在 Lua 插件中配置，不继承自 Pi。见 [安装 Neovim 插件](../how-to/install-neovim.md)。
+- **诊断 Quick Fix** 和 **自动安装** 是 VS Code 系列功能。
+- **WSL2** 跨边界发现对所有写 lock file 的编辑器（VS Code 系列、Neovim、JetBrains）均可用，Zed 则通过其 Windows 数据库路径支持。见 [在 WSL2 中使用](../how-to/use-wsl2.md)。

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

@@ -0,0 +1,54 @@
+# 协议参考
+
+Pi × IDE 通过本地 WebSocket 连接 Pi 和 IDE，连接由 lock file 发现。本页是快速参考；确切字段语义、消息结构和完整规范见 [`docs/specs/ide-protocol.md`](../../specs/ide-protocol.md)。
+
+## lock file
+
+- **目录：** `~/.pi/pi-x-ide/lock/`（权限 `0700`）
+- **命名：** `<ide>-<pid>-<port>.lock` - 例如 `vscode-12345-48123.lock`、`nvim-98765-50001.lock`、`jetbrains-4242-51234.lock`
+- **权限：** 文件权限 `0600`，原子写入（临时文件 + rename）
+
+lock file 广播 WebSocket 端点、auth token、workspace 文件夹和时间戳。
+
+## 传输
+
+- **协议：** WebSocket（`ws://host:port`）
+- **线路格式：** JSON-RPC 2.0
+
+## 认证
+
+Pi 连接时携带头：
+
+```text
+x-pi-x-ide-authorization: <authToken>
+```
+
+token 是 64 字符的十六进制串（`randomBytes(32)`），每次 IDE 会话生成并写入 lock file。服务器拒绝缺失或无效 token 的连接。
+
+## 握手
+
+Pi 发送带 `cwd` 的 `initialize` 请求；IDE 响应服务器信息，并立即发送初始 `selection_changed` 或 `selection_cleared` 通知。
+
+## 通知
+
+| 方法                       | 触发时机                                           |
+| -------------------------- | -------------------------------------------------- |
+| `selection_changed`        | 活跃编辑器或选区变化。                             |
+| `selection_cleared`        | 无活跃本地文本编辑器（JetBrains）。                |
+| `at_mentioned`             | 用户调用 IDE attach 选区命令。                     |
+| `diagnostic_fix_requested` | 用户在诊断上选择 Pi Quick Fix（仅 VS Code 系列）。 |
+
+line 和 character 偏移从 0 开始，与 VS Code/LSP 一致。Neovim 把字节列转换为 UTF-16 character 偏移；JetBrains 从 UTF-16 code-unit 计数派生 character 偏移。
+
+## TUI 行为
+
+连接后，Pi 根据 `status_display`（项目配置覆盖全局；可通过 `/ide settings` 设置）只在一处显示 IDE 连接状态：
+
+- `widget`（默认）：通过 `ctx.ui.setWidget("pi-x-ide", ...)` 显示在编辑器上方。
+- `statusline`：通过 `ctx.ui.setStatus("pi-x-ide", ...)` 显示在默认页脚状态行。
+
+两种位置都显示紧凑的连接/选区状态（IDE 图标、spinner 或状态标记、文件、范围，以及 `pending` / `sent` attach 状态），刻意不显示选中文本内容。见 [配置](configuration.md#顶层选项)。
+
+## 完整规范
+
+完整 lock file schema、WSL2 发现与 host 解析规则、以及每条通知的确切 JSON 见 [`docs/specs/ide-protocol.md`](../../specs/ide-protocol.md)。各编辑器传输方式的设计理由见 [架构](../explanation/architecture.md)。

package/docs/zh-CN/tutorials/get-started.md

@@ -0,0 +1,101 @@
+# Pi × IDE 入门指南
+
+本教程带你从全新安装走到第一次把 IDE 选区送进 LLM 对话。大约 5 分钟，以 VS Code 为例 - Cursor 和 Windsurf 流程相同。
+
+> 已经装好了，只想附加选区？直接跳到 [附加选区并对话](#第-5-步附加选区并对话)。
+> 用其他编辑器？Zed、Neovim、JetBrains 的安装见 [操作指南](../how-to/)。
+
+## 你将学到
+
+- 如何安装 Pi 扩展包和 VS Code 扩展。
+- 如何启动 Pi 让它自动发现你的 IDE。
+- 一段选中的文本如何变成 LLM 上下文。
+
+## 开始之前
+
+你需要：
+
+- 已安装 [`pi`](https://github.com/earendil-works/pi-coding-agent) CLI 并加入 `PATH`。
+- 已安装 VS Code、Cursor 或 Windsurf。
+- 一个至少包含一个源文件的项目文件夹。
+
+## 第 1 步：安装 Pi 扩展包
+
+```bash
+pi install npm:pi-x-ide
+```
+
+这会把 `pi-x-ide` 包加入 Pi。下次启动 Pi 时会自动加载，无需额外配置。
+
+## 第 2 步：安装 VS Code 扩展
+
+在 IDE 的 **扩展** 面板搜索
+[`balaenis.pi-x-ide`](https://marketplace.visualstudio.com/items?itemName=balaenis.pi-x-ide)
+并安装。
+
+> 也可以在 Pi TUI 中运行 `/ide install`，它会自动检测 `code`、`cursor` 或 `windsurf` 并安装扩展。Pi 启动时若检测到受支持的 VS Code 集成终端，也会尝试自动安装。
+
+安装后重新加载 IDE 窗口，让扩展生效。
+
+## 第 3 步：在项目中启动 Pi
+
+在 IDE 内打开终端（Terminal -> New Terminal），然后在与 IDE workspace 相同的项目目录启动 Pi：
+
+```bash
+pi
+```
+
+Pi 加载 `pi-x-ide` 并查找 IDE 连接。当终端工作目录位于某个 IDE workspace 文件夹内时，Pi 会自动连接。Pi 输入框上方会出现一个 widget，显示连接和选区状态。
+
+## 第 4 步：打开文件并选中文本
+
+回到 IDE，打开一个源文件，选中几行文本。Pi widget 应实时更新：
+
+```
+⧉ ⇡ foo.ts#L10-L20
+```
+
+`⇡` 标记表示选区处于 **pending** 状态 - Pi 已注意到它，但尚未附加到消息。
+
+如果 widget 没出现，见 [排查连接问题](../how-to/troubleshoot-connection.md)。
+
+## 第 5 步：附加选区并对话
+
+在 IDE 中选中文本后，聚焦 Pi TUI 并按 `Ctrl+Alt+K`（macOS：`Ctrl+Option+K`）。Pi 会在输入框插入一个 mention：
+
+```
+@src/foo.ts#L10-L20
+```
+
+输入问题并提交，选中文本会作为该轮的 LLM 上下文注入。提交后 widget 标记变为 `✓`：
+
+```
+⧉ ✓ foo.ts#L10-L20
+```
+
+会话记录会将你的提示与 IDE 上下文分开显示。Pi 会把 IDE 元数据显示为紫色自定义消息，并将相同元数据发送给代理：
+
+```text
+你的提示
+### IDE Context
+- **IDE**: vscode
+- **File**: `src/foo.ts`
+- **Selection**: L10-L20
+```
+
+附加内容只有 IDE、文件路径和选区行范围，不包含选中的源代码。这样代理需要更多上下文时可以自行读取文件。若打开的文件没有选区，则省略 `Selection` 行。蓝色用户提示保持不变。
+
+你可以反复按 `Ctrl+Alt+K` 把多个范围追加到同一条消息，也可以在两轮之间重新选中文本，每次附加新的上下文。
+
+## 刚才发生了什么
+
+当你选中文本时，IDE 会通过本地 WebSocket 向 Pi 广播一条 `selection_changed` 通知。Pi 缓存最新选区并标记为 pending。按下附加快捷键时，Pi 把 `@file#Lx-Ly` mention 插入输入框。提交消息时，Pi 会将 IDE 名称、文件路径和选区行范围作为单独的紫色自定义消息添加给代理，不会自动发送选中的源代码。
+
+完整机制 - lock file、host 解析、Neovim sidecar，以及为什么 Zed 用轮询 - 见 [发现机制](../explanation/discovery.md) 和 [架构](../explanation/architecture.md)。
+
+## 下一步
+
+- [安装其他编辑器](../how-to/) - Zed、Neovim 或 JetBrains。
+- [在 WSL2 中使用](../how-to/use-wsl2.md) - Pi 在 WSL，IDE 在 Windows。
+- [配置参考](../reference/configuration.md) - 环境变量、快捷键、`fixPrompt` 和 `status_display`。
+- [`/ide` 命令参考](../reference/commands.md) - 在 TUI 中管理连接。

package/package.json

@@ -1,6 +1,88 @@
 {
   "name": "@saifymatteo/pi-x-ide",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.20.1",
+  "description": "Pi extension package for IDE selection context integration.",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist/src",
+    "schemas",
+    "docs/tutorials",
+    "docs/how-to",
+    "docs/reference",
+    "docs/explanation",
+    "docs/zh-CN",
+    "docs/specs/ide-protocol.md",
+    "config.example.json",
+    "CONTRIBUTING.md",
+    "CONTRIBUTING.zh-CN.md",
+    "CHANGELOG.md",
+    "RELEASE.md"
+  ],
+  "scripts": {
+    "prepack": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\" && node node_modules/@typescript/native-preview/bin/tsgo -p tsconfig.publish.json && node scripts/build-pi-entry.mjs"
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "ide",
+    "vscode",
+    "zed",
+    "neovim",
+    "nvim",
+    "jetbrains",
+    "intellij",
+    "idea"
+  ],
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/saifymatteo/pi-x-ide.git"
+  },
+  "bugs": {
+    "url": "https://github.com/saifymatteo/pi-x-ide/issues"
+  },
+  "homepage": "https://github.com/saifymatteo/pi-x-ide#readme",
+  "workspaces": [
+    "ide-plugins/vscode"
+  ],
+  "packageManager": "bun@1.3.14",
+  "engines": {
+    "node": ">=26"
+  },
+  "type": "module",
+  "main": "./dist/src/pi/index.js",
+  "dependencies": {
+    "effect": "^3.22.0",
+    "ws": "^8.21.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.99.1",
+    "@earendil-works/pi-tui": "^0.99.1",
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^26.0.0",
+    "@types/ws": "^8.18.1",
+    "@typescript/native-preview": "7.0.0-dev.20260707.2",
+    "@vscode/vsce": "^3.9.2",
+    "esbuild": "^0.28.1",
+    "eslint": "^10.4.1",
+    "eslint-config-prettier": "^10.1.8",
+    "prettier": "^3.8.4",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.61.0"
+  },
+  "trustedDependencies": [
+    "esbuild"
+  ],
+  "pi": {
+    "image": "https://fastly.jsdelivr.net/gh/saifymatteo/pi-x-ide@main/assets/icons/pi-x-ide.png",
+    "extensions": [
+      "./dist/src/pi/index.js"
+    ]
+  }
+}

package/schemas/config.json

@@ -0,0 +1,77 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/saifymatteo/pi-x-ide/schemas/config.json",
+  "title": "Pi config.json",
+  "description": "Schema for Pi-side configuration read from ~/.pi/pi-x-ide/config.json.",
+  "type": "object",
+  "additionalProperties": true,
+  "properties": {
+    "fixPrompt": {
+      "type": "string",
+      "description": "Custom prompt prefix when requesting a fix for IDE diagnostics. Use {DIAGNOSTIC} as a placeholder for the diagnostic context. If the placeholder is omitted, the diagnostic context is appended after your prompt.",
+      "default": "Analyze the errors and warnings at the following location, and try to fix them:\n{DIAGNOSTIC}"
+    },
+    "status_display": {
+      "type": "string",
+      "description": "Where to show IDE connection status. Use \"widget\" for the above-editor widget (default), or \"statusline\" for the default footer status line.",
+      "default": "widget",
+      "enum": [
+        "widget",
+        "statusline"
+      ]
+    },
+    "env": {
+      "type": "object",
+      "description": "Pi-side environment variables. Real environment variables override these values.",
+      "additionalProperties": {
+        "type": [
+          "string",
+          "number",
+          "boolean"
+        ]
+      },
+      "properties": {
+        "PI_X_IDE_AUTO_INSTALL": {
+          "type": [
+            "string",
+            "number",
+            "boolean"
+          ],
+          "description": "Controls VS Code extension auto-install. Values 0, false, and off disable it."
+        },
+        "PI_X_IDE_ATTACH_SHORTCUT": {
+          "type": "string",
+          "description": "Pi TUI shortcut for attaching the latest IDE selection. Set to off, none, false, or 0 to disable."
+        },
+        "PI_X_IDE_HOST_OVERRIDE": {
+          "type": "string",
+          "description": "Override the host Pi uses to connect to IDE WebSocket lock files. Useful for WSL2 or custom networking."
+        },
+        "PI_X_IDE_ZED_DB": {
+          "type": "string",
+          "description": "Override path to Zed's SQLite database."
+        },
+        "PI_X_IDE_ZED_POLL_INTERVAL_MS": {
+          "type": [
+            "string",
+            "number"
+          ],
+          "description": "Polling interval in milliseconds when checking Zed's SQLite database for selection changes."
+        }
+      },
+      "patternProperties": {}
+    }
+  },
+  "examples": [
+    {
+      "fixPrompt": "Analyze the errors and warnings at the following location, and try to fix them:\n{DIAGNOSTIC}",
+      "status_display": "widget",
+      "env": {
+        "PI_X_IDE_AUTO_INSTALL": "0",
+        "PI_X_IDE_ATTACH_SHORTCUT": "ctrl+alt+k",
+        "PI_X_IDE_ZED_DB": "/home/user/.local/share/zed/db/0-stable/db.sqlite",
+        "PI_X_IDE_ZED_POLL_INTERVAL_MS": 1000
+      }
+    }
+  ]
+}