@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 检查环境。
/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）。
/vsl:ra-clarify <objective>
只做需求分析与澄清，不做实现。子代理无法直接向用户提问时，以 PENDING_QUESTIONS 块结束，由主 Agent 转述提问、携带回答重发，循环至无歧义。产出需求文档写入 .ra-agent/output/。
ra-criteria
从需求生成退出准则 / 验收标准（SC/AC），由专用子代理 criteria-spec 执行（Command + Agent + Tool）。
/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 可覆盖入口。
（无命令；由主 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，证据链随循环累积。
/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 中启用：
$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 并重启宿主，或取消安装该模块即可停用。详细启用与验证说明见 模块说明。
rewind
运行时模块，仅提供 vsl_rewind_candidates、vsl_rewind_commit、vsl_rewind_status，不增加命令、Agent 或 Skill。需要同时使用包含原生 Rewind bridge v1 的 DevEco 构建。
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 免重装快速修改：
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 原生程序。
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 外部命令兼容（安装插件不等于启用外部来源）：
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证明。
开发接入
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 条目。
本地包验证（开发辅助，无需全局安装）：
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 | 模块、适配器与安装集成测试 |
新增模块：
- 在
src/plugin/modules/新建模块文件，返回PluginModule，按需填写 Command / Agent / Skill / Tool，名称带统一前缀（如vsl:、ra:）。 - 注册进
src/plugin/index.ts的默认模块列表。 - 补充资源注册与执行测试。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 另覆盖失败、取消和修复轮数上限等场景。测试使用本地受控模型响应，不验证真实模型的语义准确率。