# @bitfun-vsl/plugin 中文文档

规范地址：https://npmcn.com/package/%40bitfun-vsl/plugin/

版本：0\.1\.1
npm 元数据更新时间：2026-11-06T09:50:50.651Z
中文译文更新时间：2026-11-08T05:14:20.570Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40bitfun-vsl/plugin
原文对照：https://npmcn.com/package/%40bitfun-vsl/plugin/?lang=original
项目主页：https://gitcode.com/OpenBitFun/bitfun_horizon_verify#readme
源码仓库：https://gitcode.com/OpenBitFun/bitfun_horizon_verify

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：30.6 MB，14 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：0 个
- 首次发布：2026-10-30T10:54:49.885Z
- 最新版本发布：2026-11-06T09:50:50.443Z
- 近 30 天下载量：1922（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：11（近 12 个月 11 个）

## 中文简介

DevEco 代码、 Claude 代码、 BitFun 和 OpenCode 共享模块和本地主机适配器

## 安装

```sh
npm install @bitfun-vsl/plugin
```

也可以使用：`pnpm add @bitfun-vsl/plugin`、`yarn add @bitfun-vsl/plugin`、`bun add @bitfun-vsl/plugin`

## README

# @bitfun-vsl/plugin

面向 DevEco Code、Claude Code、BitFun 和 OpenCode 的插件包。每个模块提供 Command、Agent、Skill、Tool 四类资源中的一种或多种，通过 `vsl init` 安装进宿主。

## 模块

### code-review

将 CR 的 `cr review` 作为完整审查引擎封装，使用 CR 自己的模型配置。只注册 Command 和 Tool。

前置：本机有 CR 原生程序。将 `VSL_CR_BIN` 设为其绝对路径，或把 `cr` 加入 PATH；init 会自动检测并保存。`/vsl:cr-health` 检查环境。

```text
/vsl:cr-health
/vsl:review 预览当前工作区修改
/vsl:review 审查提交 abc123
/vsl:review 比较 main 和 feature-login
```

审查终态以结果 `manifest.terminal_state` 为准（`complete` / `partial` / `failed` / `skipped`）；退出码为 0 或发现数为 0 都不能单独证明审查完成。

### ra-clarify

EVPI 驱动的需求澄清，由专用子代理 `ra-agent` 执行（Command + Agent + Tool）。

```text
/vsl:ra-clarify <objective>
```

只做需求分析与澄清，不做实现。子代理无法直接向用户提问时，以 `PENDING_QUESTIONS` 块结束，由主 Agent 转述提问、携带回答重发，循环至无歧义。产出需求文档写入 `.ra-agent/output/`。

### ra-criteria

从需求生成退出准则 / 验收标准（SC/AC），由专用子代理 `criteria-spec` 执行（Command + Agent + Tool）。

```text
/vsl:ra-criteria <requirement | path-to-req.json>
```

输入依次解析：文件路径 → `.ra-agent/output/` 下最新 `*-req.json` → 纯文本描述。经 `validate_criteria` 工具校验通过后写入 `.ra-agent/output/{id}-criteria.json`。

### debug-agent

ArkTS / HarmonyOS 运行时验证，由专用子代理 `arkts-debug` 执行（Agent + Tool，无 Command）。将 `arkts-debug-mcp` 的 ArkTS DAP 调试能力嵌入为 Registry 模块：DAP 服务器由 `script/build.ts` 以 node 目标构建为 `assets/scripts/dap-server.js`，宿主进程作为子进程拉起；`ARKTS_SERVER_PATH` 可覆盖入口。

```text
（无命令；由主 Agent 以 Task 派发 arkts-debug 子代理）
```

子代理持有持久 DAP 会话，按场景步骤推进：`start_arkts_session` → `set_step_breakpoints` → `launch_app` → `tap_ui` 等设备操作 → `inspect_current_stop` 采集证据（表达式求值 + 截图）→ `record_debug_step_result` → `export_debug_report`。UI 操作被门控在新断点之后（`ARKTS_STEP_BREAKPOINTS_REQUIRED`）；高级单步工具（`pause_execution` / `step_over` 等 5 个）需 `ARKTS_DEBUG_TOOL_PROFILE=advanced`。会话入口工具仅限 `arkts-debug` 子代理调用（`ARKTS_DEBUG_SUBAGENT_ONLY`），宿主不提供调用方名称时放行。派发子代理时应传入已验证的断点文件绝对路径——子代理没有文件读取工具。报告与截图写入被调试项目的 `.arkts-debug-reports/`。

前置：应用已构建、部署并安装到设备；`arkts_debug_doctor` 体检 DAP 入口、DevEco SDK、HDC 设备与工程（`directory` 参数指定非宿主工作目录的项目根）。

### tdd

状态机强制执行的 TDD 循环（Command + Tool）。RED / GREEN / REFACTOR 三相全部由代码裁决，LLM 无法跳过状态：RED 要求测试 3 次一致性失败并做假绿检测（管道吞退出码、空集合恒真等模式），GREEN 通过摘要校验阻止篡改测试文件，REFACTOR 保持测试常绿。状态持久化到目标项目 `.tdd/state.json`，证据链随循环累积。

```text
/vsl:tdd-start src/calc.js src/calc.test.js bug clamp-rejects-negative "node --test test/calc.test.js"
/vsl:tdd-run red
/vsl:tdd-run green
/vsl:tdd-run refactor
/vsl:tdd-report
```

RED 通过后自动做变异测试：JS/TS 优先 Stryker、Python 走 mutmut、Go/Rust 显式跳过，外部工具缺失时回退到内置零依赖引擎。突变分数低于 70% 会提示回到 RED 补测试。AST 分析使用运行时依赖 `typescript`（随插件安装，与 debug-agent 的 `ws` 同一模式），无需宿主额外配置。

### trajectory-analysis

异步轨迹观测与修复模块，仅支持 DevEco Code 的 `build` Agent。检测、分析复用当前任务的 provider 和模型；两个隐藏子代理 `vsl-trajectory-detector`、`vsl-trajectory-analyzer` 分别检查公开轨迹、只读源码并提出修复建议，由原主 Agent 执行修复。旧的 `/vsl:trajectory` mock 命令已移除。

安装时勾选 `trajectory-analysis`，在启动 DevEco 的同一 PowerShell 中启用：

```powershell
$env:VSL_OBSERVER_PROCESS_MODE = "active"
$env:VSL_OBSERVER_ANALYSIS_MODE = "on"
$env:VSL_OBSERVER_PROCESS_FAMILIES = "two"
$env:VSL_OBSERVER_PROCESS_DELIVERY = "next-loop"
$env:VSL_OBSERVER_PROCESS_CADENCE = "adaptive"
$env:VSL_OBSERVER_PROCESS_TRANSPORT = "stream"
$env:VSL_OBSERVER_PROCESS_TOOL_INTERVAL = "40"
$env:VSL_OBSERVER_MODE = "off"
$env:VSL_OBSERVER_DRIFT_MODE = "off"
$env:VSL_OBSERVER_RISK_MODE = "off"
$env:VSL_OBSERVER_CONTRACT_MODE = "off"
deveco
```

从 40 次完成工具调用起异步检测，后续按运行速度调整间隔；建议进入后续模型请求。任务 idle 时执行最终检查，必要时最多追加两轮同会话修复；失败或 unknown 不记为修复成功。审计默认写入 `%LOCALAPPDATA%/vsl/native-observer/deveco-*/events.jsonl`，可用 `VSL_OBSERVER_STATE_DIRECTORY` 指定目录。

设置 `VSL_OBSERVER_PROCESS_MODE=off` 并重启宿主，或取消安装该模块即可停用。详细启用与验证说明见 [模块说明](https://npmcn.com/package/%40bitfun-vsl/plugin/src/plugin/modules/trajectory-analysis/README.tmp.md)。

### rewind

运行时模块，仅提供 `vsl_rewind_candidates`、`vsl_rewind_commit`、`vsl_rewind_status`，不增加命令、Agent 或 Skill。需要同时使用包含原生 Rewind bridge v1 的 DevEco 构建。

```powershell
vsl init --host deveco --modules rewind --yes
vsl config --host deveco --rewind-mode off --yes
```

四模式：`off` 不挂载；`observe` 记录但禁止恢复；`suggest` 提示并由工具显式提交；`auto` 按策略自动恢复。切换后重启宿主。省略 `--modules` 的 update 保留已选模块；首次安装选中 rewind 时默认 `auto`，安装向导不再询问模式；后续通过 `vsl config` 修改。显式传入 `--rewind-mode` 仍可覆盖默认值。

已安装实例的模式与策略参数可用 `vsl config` 免重装快速修改：

```powershell
vsl config --host deveco --rewind-mode auto --yes    # 切换模式
vsl config --host deveco --rewind-config policy.json --yes   # 只合并策略参数
vsl config --host deveco --rewind-mode auto --dry-run        # 预览将要修改的键
```

`config` 直接重写安装实例内的 `assets/runtime.json` 并同步安装回执，不重新下载或安装包；交互模式会提示选择模式；`--rewind-config` 只覆盖文件中出现的键，文件不含 mode；中断的修改用 `vsl recover` 回滚。

`--rewind-config <JSON文件>` 可传 checks、protectedResources、预算等参数（文件不含 mode）；更新保留旧参数，并合并提供的参数。配置随安装实例写入宿主实际加载的包内 `assets/runtime.json`。用会话内 `vsl_runtime_info` 核对 buildId 和模式，用 `vsl_rewind_status` 核对宿主桥接状态。`doctor` 仅检查安装，不代表运行时加载成功。

`filesystem` 恢复快照文件；`context` 保留当前文件。外部数据库、服务及依赖不在文件快照恢复范围。操作 `completed` 表示恢复交接完成，任务最终成功仍需检查子会话结果。

两个模块可独立选择、启停，也可同时启用。恢复开始后暂停分析投递与 idle 自动续跑，取消恢复前的分析；成功交接后源会话不再投递建议，子会话基于新轨迹重新观测。它们保留独立的检测策略、配置与数据模型。

## 安装

前置：Bun、npm；选择 Claude Code 需要 Claude CLI；启用 `code-review` 模块需要 CR 原生程序。

```powershell
npm install -g @bitfun-vsl/plugin
vsl init
```

向导三步：多选宿主 → 多选模块（默认全选）→ 确认一次。方向键移动、空格勾选、`a` 全选、Ctrl+C 取消。

`vsl` 子命令与参数：

| 命令 / 参数 | 说明 |
| --- | --- |
| `vsl init` / `vsl update` | 安装 / 更新选中宿主的依赖与注册 |
| `vsl config --host deveco` | 免重装修改 rewind 模式与策略，重启宿主生效 |
| `vsl doctor --host <宿主> --json` | 检查文件与注册 |
| `vsl uninstall` / `vsl recover` | 卸载 / 恢复中断的安装 |
| `--host deveco|claude-code|bitfun|opencode` | 指定宿主，可重复传入 |
| `--modules id,id` | 指定模块 |
| `--yes` | 非交互执行（需显式指定宿主） |
| `--package <tgz>` | 使用本地构建包，用于开发验证 |
| `--rewind-mode off|observe|suggest|auto` / `--rewind-config <JSON文件>` | 设置 rewind 模式 / 合并策略参数 |
| `--cr-bin <绝对路径>` | 显式指定 CR 程序 |
| `--config-dir` / `--command-dir` / `--state-dir` | 隔离目录验证；`--config-dir` 仅单宿主，`--command-dir` 仅 BitFun |
| `--dry-run` / `--json` | 只计算不安装 / 输出诊断 JSON |

四宿主加载方式：

| 宿主 | init 写入 | 宿主加载 |
| --- | --- | --- |
| DevEco Code | `~/.config/deveco` 的 npm 依赖与唯一 VSL 插件入口 | 原生插件注册 Command / Agent / Skill / Tool |
| Claude Code | 本地 marketplace 与按模块生成的原生插件、MCP 配置（经 Claude CLI 安装） | 原生插件 + MCP 工具 |
| BitFun | `%APPDATA%/bitfun/config`（Windows）的 npm 依赖、`app.json` 入口、`~/.config/opencode/command/` 命令文件 | 原生插件注册 Agent / Skill / Tool；命令来自外部命令文件 |
| OpenCode | `~/.config/opencode` 的 npm 依赖与 `opencode.json` 插件入口 | 原生插件注册 Command / Agent / Skill / Tool |

BitFun 需额外启用 OpenCode 外部命令兼容（安装插件不等于启用外部来源）：

```powershell
bitfun config external set-enabled true --scope global
bitfun config external set-mode recommended --ecosystem opencode --scope global
bitfun config external status
```

已有无安装清单的旧注册或未托管的 VSL file URL 会报告冲突：先备份并移除旧注册，再运行 init。init 不覆盖用户修改过的受管文件。

## 使用

命令名在所有宿主统一为 `vsl:<名称>`：DevEco、OpenCode 与 Claude Code 都显示为 `/vsl:review`、`/vsl:ra-clarify`（Claude 的插件前缀本身就是 `vsl`）；BitFun 使用斜杠形式（`/vsl/review`、`/vsl/ra-clarify`），且只在进入会话后刷新外部命令，启动页不显示。BitFun 与 OpenCode 并存时，OpenCode 也会读取 BitFun 写入 `~/.config/opencode/command/` 的命令文件，冒号式与斜杠式命令同时可见，功能一致。

OpenCode 只接管 `opencode.json` 的 VSL 注册；上游会合并 `config.json` → `opencode.json` → `opencode.jsonc`，`config.json` 或 `opencode.jsonc` 中出现任何 VSL 条目都会拒绝安装（双注册会让第二实例的命令投影冲突）。

安装后重启宿主，在会话中调用 `vsl_runtime_info`，核对 `version`、`buildId`、`installationId` 和模块与 `vsl doctor --host <宿主> --json` 一致。

排错：

-   `vsl doctor --host <宿主> --json` 查看诊断。
-   安装中断后，用相同目标参数执行 `vsl recover --host <宿主> --yes` 再重试。
-   `doctor` 只证明文件与注册正确；宿主是否真正加载，由运行时的 `vsl_runtime_info` 证明。

## 开发接入

```bash
bun install --ignore-scripts
bun test
bun run typecheck
bun run build
npm pack
```

构建产物不入仓：`dist/`、`assets/scripts/dap-server.js`、`assets/claude-code/scripts/*.js` 与 `assets/install-manifest.json` 都由 `bun run build` 生成，`npm pack` / 发布时由 `prepack` 重新生成。因此全新克隆后必须先 `bun run build`，否则 `arkts_debug_doctor` 会报 `dapServerEntry.exists=false`、安装校验会报缺少 manifest 条目。

本地包验证（开发辅助，无需全局安装）：

```powershell
npm pack
bun .\dist\cli\index.js init --package "$PWD\bitfun-vsl-plugin-<version>.tgz"
```

目录分层：

| 目录 | 职责 |
| --- | --- |
| `src/plugin` | 资源契约、Registry、内置模块与观测调度 |
| `src/hosts` | 宿主适配器：`deveco` / `bitfun-kernel` / `opencode` / `claude-code`（MCP）与共享实现 `shared` |
| `src/cli` | `vsl init / update / config / doctor / uninstall / recover` |
| `src/install` | 从 Registry 渲染各宿主资源文件 |
| `assets` | `bun run build` 生成的宿主资源，随包分发 |
| `test` | 模块、适配器与安装集成测试 |

新增模块：

1.  在 `src/plugin/modules/` 新建模块文件，返回 `PluginModule`，按需填写 Command / Agent / Skill / Tool，名称带统一前缀（如 `vsl:`、`ra:`）。
2.  注册进 `src/plugin/index.ts` 的默认模块列表。
3.  补充资源注册与执行测试。Claude 原生资源与 BitFun 命令文件由构建从 Registry 生成，无需手写。

测试开关：`VSL_CLAUDE_INSTALL_TEST=1` 启用 Claude 真实 CLI 安装测试；`VSL_CR_LIVE_TEST=1` 启用 CR 真实模型审查测试；默认跳过。

真实 DevEco 进程验证：`bun run verify:v3:hosts` 检查最终修复和周期异步检测。每次使用新隔离用户目录；确认产品协议后，可显式设置 `$env:VSL_NATIVE_ACCEPT_PRODUCT_AGREEMENTS="1"`，让测试在隔离目录执行 `auth consent --accept`。该开关默认关闭。`VSL_NATIVE_HOST_TEST=1 bun test test/v3-native-integration.test.ts` 另覆盖失败、取消和修复轮数上限等场景。测试使用本地受控模型响应，不验证真实模型的语义准确率。

## 常见问题

### @bitfun-vsl/plugin 是什么？

DevEco 代码、 Claude 代码、 BitFun 和 OpenCode 共享模块和本地主机适配器

### 如何安装 @bitfun-vsl/plugin？

在项目目录运行 npm install @bitfun-vsl/plugin，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 vsl，可以用 npx vsl 直接运行。

### @bitfun-vsl/plugin 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/bitfun-vsl\_\_plugin 是否存在。

### @bitfun-vsl/plugin 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @bitfun-vsl/plugin 可以商用吗？

@bitfun-vsl/plugin 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @bitfun-vsl/plugin 的下载量有多少？

根据 npm 官方下载统计，@bitfun-vsl/plugin 在 2026/10/08 – 2026/11/06 这 30 天内被下载 1,922 次，日均约 64 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @bitfun-vsl/plugin 还在维护吗？

最新版本 0\.1\.1 发布于 2026/11/06（2 天前）；至今共发布 11 个版本，其中过去 12 个月发布了 11 个；首次发布于 2026/10/30。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。