@bitfun-vsl/plugin 0.0.0-stage → 0.0.2

package/docs/code-review-integration.md

@@ -0,0 +1,182 @@
+# review 完整封装集成方案
+
+本文说明 `code-review` 模块如何将 `review`（CR）作为完整审查引擎接入 `@bitfun-vsl/plugin`，供 DevEco Code 和 Claude Code 使用。
+
+## 1. 目标与边界
+
+模块直接执行 CR 的 `cr review` 命令，保留 CR 的文件选择、规则解析、分组调度、模型调用、结果过滤、覆盖统计和会话恢复能力。插件只负责注册宿主资源、组装结构化参数、启动原生进程、传递取消信号和返回结构化结果。
+
+模块不调用 `cr delegate`，不重新实现 CR 的审查流程，也不修改 DevEco Code、Claude Code 或 CR 源码。
+
+CR 使用自己的模型和凭据配置。插件不会把宿主 Agent 的模型配置自动转换成 CR 配置。
+
+## 2. 按需注册资源
+
+当前模块只注册两类资源：
+
+| 资源 | 名称 | 用途 |
+| --- | --- | --- |
+| Command | `/vsl:review` | 发起完整 CR 审查 |
+| Command | `/vsl:cr-health` | 检查 CR 程序和接口 |
+| Tool | `vsl_cr_review` | 执行 `cr review` |
+| Tool | `vsl_cr_health` | 检查版本、参数兼容性，可选测试模型连接 |
+
+本模块不注册 Agent 和 Skill。Command 的提示词包含调用约束，工具描述包含参数和结果解释规则。其他模块仍可以独立注册 Agent、Skill 或四类资源的任意组合。
+
+## 3. 调用链
+
+```text
+slash command
+  -> DevEco Code / Claude Code 主 Agent
+  -> vsl_cr_review
+  -> 本地 cr 原生程序
+  -> CR 内部审查引擎和 CR 配置的模型
+  -> JSON 结果、manifest、会话文件
+  -> VSL 工具返回摘要和完整结果文件路径
+```
+
+Command 负责将自然语言转换为工具参数。Tool 不接受任意 shell 字符串，只使用参数数组启动进程。
+
+## 4. 支持的审查范围
+
+工具参数对应 CR 的原生参数：
+
+| 参数 | 说明 |
+| --- | --- |
+| `repo` | 仓库绝对路径，默认使用宿主项目目录 |
+| `commit` | 单提交审查 |
+| `from`、`to` | 两个 ref 的范围审查，必须同时提供 |
+| `preview` | 只查看范围，不调用模型 |
+| `resume` | 恢复提交或 ref 范围的 CR 会话；工作区不支持恢复 |
+| `background`、`backgroundFile` | 业务背景 |
+| `exclude` | 排除模式数组 |
+| `rule` | 自定义规则文件 |
+| `provider`、`model`、`effort` | 本次执行的 CR 模型覆盖项 |
+| `concurrency`、`taskTimeoutMinutes`、`maxTokensBudget` | CR 内部执行限制 |
+| `overallTimeoutMinutes` | 插件控制的整个进程期限，默认 60 分钟 |
+
+约束与 CR 一致：`commit` 不能和 `from/to` 同时使用；`preview` 不能和 `resume` 同时使用；`resume` 必须带原始 commit 或 ref 范围。
+
+## 5. 结果语义
+
+CR 的 JSON 结果完整保存在缓存目录的 `result.json`，错误诊断保存在 `stderr.log`。工具返回文件路径、会话 ID、摘要、发现和覆盖信息。
+
+`manifest.terminal_state` 是审查完成状态的依据：
+
+| 状态 | 含义 |
+| --- | --- |
+| `complete` | 选中的审查项全部完成 |
+| `partial` | 有完成项，也有失败或未覆盖项 |
+| `failed` | 审查失败 |
+| `skipped` | 没有可支持的文件或 CR 明确跳过 |
+
+退出码为 0、发现数量为 0 或空文本都不能单独证明审查完成。`partial`、`failed` 和 `skipped` 必须在主 Agent 的最终报告中明确说明。预算停止可能产生部分结果并以 0 退出，因此还必须检查 manifest 覆盖集合。
+
+当结果较大时，工具只在响应中返回有限数量的发现，同时设置 `findingsTruncated`，主 Agent 应按 `resultFile` 分批读取完整 JSON。原始文件不写入被审查仓库。
+
+## 6. CR 可执行文件
+
+优先通过 `VSL_CR_BIN` 指向原生可执行文件的绝对路径，例如 Windows 的 `cr.exe`。未设置时，模块会从 PATH 查找 `cr.exe`/`cr` 或 `cr.exe`/`cr`。
+
+`VSL_CR_BIN` 不接受 `.cmd`、`.bat`、`.ps1` 或 `.js` shim。进程使用 `shell: false` 启动，并设置 `CR_NO_UPDATE=1`，避免审查期间自动更新 CR。
+
+本地源码验证可以在 `review` 目录构建原生程序后设置该变量。发布包应固定经过验证的 CR 版本，不在工具调用中自动安装或升级。
+
+## 7. 宿主适配
+
+DevEco 通过原生插件 Tool 注册，当前适配器已经改为从模块 JSON Schema 生成字符串、数字、整数、布尔值、数组和枚举参数。
+
+Claude Code 通过 VSL MCP Server 暴露相同工具。MCP Server 支持并发请求、`notifications/cancelled`、工具错误返回和请求体大小限制；CR 长调用不会阻塞后续 ping 或取消消息。
+
+## 8. 目录结构
+
+```text
+src/
+├── plugin/
+│   ├── contracts.ts
+│   ├── schema.ts
+│   ├── index.ts
+│   └── modules/
+│       ├── trajectory-analysis.ts
+│       └── code-review/
+│           ├── index.ts       # Command、Tool、JSON Schema
+│           └── runtime.ts     # CR 定位、进程生命周期、结果解析
+└── hosts/
+    ├── deveco/
+    │   ├── plugin.ts          # DevEco Tool 适配
+    │   └── schema.ts          # JSON Schema 到 Zod 参数转换
+    └── claude-code/
+        └── mcp-server.ts      # MCP 并发、取消和错误隔离
+
+assets/claude-code/
+└── commands/
+    ├── review.md
+    └── cr-health.md
+
+doc/
+└── code-review-integration.md
+
+test/
+├── code-review.test.ts
+└── code-review-integration.test.ts
+```
+
+## 9. 验证方式
+
+执行：
+
+```bash
+bun run typecheck
+bun test
+bun run build
+```
+
+本地 CR 验证顺序：
+
+1. `vsl_cr_health` 检查原生程序和 `review --help` 的 JSON 接口参数。
+2. 使用 `preview: true` 验证工作区、commit 和 ref 范围，不产生模型请求。
+3. 在小型临时 Git 仓库执行一次真实审查。
+4. 分别验证超时、取消、模型失败、预算部分完成和 resume。
+5. 将打包的插件安装到 DevEco 实际加载的配置目录，并在 Claude Code 中验证 MCP 工具发现和 slash command。
+
+完整审查的验收标准是：结果包含 manifest，覆盖项可解释，终态与报告一致，失败不会被报告为“没有问题”。
+
+## 10. 本地使用与测试记录
+
+在启动 DevEco 或 Claude Code 的同一终端设置环境变量：
+
+```powershell
+$env:VSL_CR_BIN = 'D:\path\to\cr.exe'
+```
+
+Claude 使用包内 `assets/claude-code` 目录；DevEco 使用 `@bitfun-vsl/plugin` 的原生插件入口。更新 DevEco 时，需要更新 `~/.config/deveco` 实际依赖的 tarball 并重启宿主，仅全局安装 npm 包不能证明 DevEco 已加载新版本。CLI 的环境变量需要由宿主进程继承。
+
+直接通过两个宿主的命令调用：
+
+```text
+/vsl:cr-health
+/vsl:review 预览当前工作区修改
+/vsl:review 审查提交 abc123
+/vsl:review 比较 main 和 feature-login
+/vsl:review 恢复会话 <session-id>，原范围 main 到 feature-login
+```
+
+工具默认使用 60 分钟整体期限，范围为 0.001 到 1440 分钟。CR 的 `--timeout` 是内部任务期限，两者不能混用。缓存默认位于 Windows `%LOCALAPPDATA%/vsl/cr`，其他系统为 `$XDG_CACHE_HOME/vsl/cr` 或 `~/.cache/vsl/cr`；可通过 `VSL_CR_CACHE_DIR` 覆盖。缓存不会自动清理，可按自己的保留策略删除已结束运行的目录。
+
+子进程 stdout/stderr 流式保存；合计超过 32 MiB 会终止执行并保留诊断。响应超过 64,000 字符时返回 `detailsTruncated` 和完整文件路径；发现被省略时返回 `findingsTruncated`。这两个标记均要求读取原始文件再给出完整报告。
+
+真实 CR CLI 集成测试在可找到原生程序时运行，否则明确跳过。使用已有安装时设置 `VSL_CR_BIN` 即可。默认测试只执行健康检查、预览、无效 ref、DevEco 注册与 MCP 调用；不发起模型请求。完整模型测试需要显式启用：
+
+```powershell
+$env:VSL_CR_LIVE_TEST = '1'
+bun test test/code-review-integration.test.ts
+```
+
+2026-10-21 已使用本机 CR `v1.12.9 (bccbc15f)` 验证：
+
+- 工作区跟踪/未跟踪文件、提交和范围预览、排除规则、无效 ref 诊断通过。
+- 模块注册、DevEco 原生 schema、Claude MCP 调用与并发取消测试通过。
+- 真实模型连接检查成功；临时 Git 仓库的完整审查返回 `complete`，完成目标文件审查，发现 1 个问题。
+- 显式较小预算的试跑返回 `failed` 和预算分类，原始结果及 session ID 均保留。
+
+上述宿主适配验证覆盖原生插件注册接口和 MCP 协议，本次未修改用户已安装的宿主配置，也未在两个宿主的交互会话中重新验证 slash 命令。长任务宿主超时、实际交互会话中的取消与 resume 仍需要安装后验证。

package/docs/init-installation.md

@@ -0,0 +1,97 @@
+# init 安装与本地验证
+
+在 `D:\code\spec\vsl\plugin\bitfun_horizon_verify` 执行：
+
+```powershell
+npm pack
+bun .\dist\cli\index.js init --package "$PWD\bitfun-vsl-plugin-0.0.1.tgz"
+```
+
+向导只有三个步骤：
+
+1. 多选宿主：DevEco Code、Claude Code、BitFun。空格勾选，方向键切换，`a` 全选。
+2. 多选模块：`trajectory-analysis`、`code-review` 默认全部勾选，可以取消不需要的模块。每个模块自带 Command、Agent、Skill、Tool，不单独选择资源。
+3. 显示宿主、模块与来源摘要，最后确认一次“是否执行安装？”。取消或 Ctrl+C 不执行安装。
+
+`--package` 预设本地包来源，仍显示宿主和模块选择。`--host` / `--modules` 可跳过对应选择。`--yes` 用于自动化，要求显式指定宿主；`--json` 输出诊断 JSON。`--dry-run` 只计算安装信息，不修改配置，也不要求确认。
+
+## 三个宿主的加载方式
+
+| 宿主 | init 写入 | 宿主加载 |
+| --- | --- | --- |
+| DevEco Code | `~/.config/deveco` 下的实际 npm 依赖与 `deveco.jsonc`/`deveco.json` 的唯一 VSL 入口 | 原生插件 Hook 注册选中模块的命令、Agent、Skill 路径和工具 |
+| BitFun | 平台用户目录的 `bitfun/config` 下的 npm 依赖（Windows 为 `%APPDATA%/bitfun/config`）、`app.json` 中 BitFun 专用入口、`~/.config/opencode/command/vsl/*.md` | 原生插件注册 Agent、Skill 和 Tool；OpenCode 命令源扫描命令文件 |
+| Claude Code | 本地 marketplace、选中模块生成的原生插件和 MCP 配置，通过 Claude CLI 安装 | 原生插件加载 Command/Agent/Skill，MCP 启动共享工具 |
+
+BitFun 的原生用户根：Windows 为 `%APPDATA%/bitfun`，macOS 为 `~/Library/Application Support/bitfun`，Linux 为 `$XDG_CONFIG_HOME/bitfun`（默认 `~/.config/bitfun`）。`BITFUN_USER_ROOT` / `BITFUN_E2E_USER_ROOT` 覆盖根目录，init 的 `--config-dir` 可显式指定 config 目录。
+
+BitFun 还需启用 OpenCode 命令兼容，安装插件不等于启用外部来源。用实际 BitFun 可执行文件执行：
+
+```powershell
+bitfun config external set-enabled true --scope global
+bitfun config external set-mode recommended --ecosystem opencode --scope global
+bitfun config external status
+```
+
+确认有效设置中 `Status: enabled`、`OpenCode mode: recommended`、`command: auto`。VSL 会把命令文件安装到 BitFun 扫描的 OpenCode 目录；当前 BitFun CLI 的启动页不读取外部命令，进入会话后才刷新来源。启动页直接显示需要 BitFun 宿主侧增加启动发现，不能通过重新运行 VSL init 修复。会话中通过 `/extensions` 检查并刷新来源。BitFun 的命令名为 `/vsl/trajectory`、`/vsl/cr-health`、`/vsl/review`；命令参数是在选择命令后填写，列表不会显示 `sample.trace` 参数。
+
+BitFun 命令默认不带 `agent` 前置字段，保持已有适配约束；插件工具对原生主 Agent 不可见，由主 Agent 使用 Task 委派。插件激活仅限本地工作区。
+
+所有宿主读取同一次模块选择。未通过 init 安装的原生入口仍可使用，未配置模块选择时默认启用全部模块。全局 npm 安装仅提供 CLI，init 才会更新宿主真正读取的依赖。安装不会增加第二份 VSL 注册。
+
+选择 `code-review` 时，init 自动检测本机原生 CR 并将绝对路径保存到安装运行时配置和收据，避免桌面宿主的 PATH 与终端不同导致 `cr-health` 找不到程序。`--cr-bin <绝对路径>` 可显式指定；检测不到时 CLI 会提示后续配置方法。更新后用 `doctor --json` 查看 `crBinary`，并完整重启宿主。
+
+## 隔离配置目录验证本地包
+
+先在隔离目录验证安装文件及插件入口，避免影响日常配置。下面使用包内 CLI 安装相同 tgz，不需要全局安装：
+
+```powershell
+$vslTestRoot = Join-Path $env:TEMP ("vsl-manual-" + [guid]::NewGuid())
+$vslPackage = Join-Path $PWD "bitfun-vsl-plugin-0.0.1.tgz"
+bun .\dist\cli\index.js init --host bitfun --package "$vslPackage" `
+  --config-dir "$vslTestRoot\bitfun-config" `
+  --command-dir "$vslTestRoot\opencode" --state-dir "$vslTestRoot\state"
+```
+
+这时仍出现模块复选列表和一次最终确认。安装后：
+
+```powershell
+bun .\dist\cli\index.js doctor --host bitfun `
+  --config-dir "$vslTestRoot\bitfun-config" --state-dir "$vslTestRoot\state" --json
+Get-Content "$vslTestRoot\bitfun-config\node_modules\@bitfun-vsl\plugin\package.json"
+Get-ChildItem "$vslTestRoot\opencode\command\vsl"
+```
+
+预期：`installed: true`、`configured: true`、`changedFiles: []`、`recoveryRequired: false`。全部模块对应三个命令文件；只选 `trajectory-analysis` 对应 `trajectory.md`，只选 `code-review` 对应 `review.md` 和 `cr-health.md`。
+
+更新仍传入相同的 `--config-dir`、`--command-dir`、`--state-dir`；取消模块后对应旧命令应清理。重复相同安装不增加注册。未托管同名命令内容不同、或用户修改过受管文件时，安装报错并保留原文件。中断安装用相同目标参数执行 `vsl recover --host bitfun --yes` 后再重试。
+
+DevEco 可用相同流程，将 `--host` 改为 `deveco`，去掉 `--command-dir`，配置路径改为 `$vslTestRoot\deveco`。Claude 改为 `claude-code` 并使用独立 `--config-dir`，需安装真实 Claude CLI。
+
+## 包内 CLI 与真实宿主验证
+
+验证发布包自身的 CLI，可先在独立目录安装 tgz：
+
+```powershell
+npm install --prefix "$vslTestRoot\cli" --ignore-scripts "$vslPackage"
+bun "$vslTestRoot\cli\node_modules\@bitfun-vsl\plugin\dist\cli\index.js" init --package "$vslPackage"
+```
+
+此命令进入完整向导，默认写入选中宿主的正常用户目录。若只验证文件安装，继续传入隔离参数。
+
+完成正常用户目录安装后，完整重启对应宿主，新建本地工作区会话，在宿主内调用 `vsl_runtime_info`，将 `version`、`buildId`、`installationId`、`modules` 与 `vsl doctor --host <宿主> --json` 对照。再执行 `/vsl:trajectory sample.trace`、`/vsl:cr-health`；需要完整代码审查时触发 `/vsl:review`。轨迹模块当前是确定性 mock；完整审查需要 CR 可执行文件和模型配置。
+
+上述冒号命名适用于 DevEco 和 Claude Code；BitFun 使用 `/vsl/trajectory sample.trace`、`/vsl/cr-health`、`/vsl/review`。BitFun 的启动页显示属于宿主能力；VSL init 负责安装和注册资源，不会改写宿主的启动页发现逻辑。
+
+隔离目录文件安装通过并不证明正在运行的桌面宿主加载了它。`loaded: "not checked"` 和 `verified: false` 表示尚无真实宿主证据；不能用全局版本或文件时间代替 `vsl_runtime_info`。
+
+## 开发验证
+
+```powershell
+bun run typecheck
+bun test
+$env:VSL_CLAUDE_INSTALL_TEST = "1"
+bun test test/installation.test.ts
+```
+
+安装集成测试使用真实 npm/tgz 和临时目录，覆盖 DevEco、BitFun 模块筛选、命令更新、收据、冲突保护、恢复、卸载；Claude 真实 CLI 安装测试需显式启用。模型驱动的完整审查需要另外启用现有 CR 实测开关。