@bitfun-vsl/plugin 0.0.0-stage → 0.0.2

package/docs/plugin-design.md

@@ -0,0 +1,391 @@
+# VSL 插件系统设计
+
+## 1. 目标与整体结构
+
+`@bitfun-vsl/plugin` 是一个通过 npm 包分发的插件集合，供 DevEco Code 和 Claude Code 使用。一个模块可以提供 Command、Agent、Skill、Tool 中的一种或多种资源。
+
+实现分为三部分：
+
+| 部分 | 位置 | 职责 |
+| --- | --- | --- |
+| 共享模块 | `src/plugin/` | 定义资源契约、聚合模块、校验命名和引用、实现 Tool |
+| 宿主适配 | `src/hosts/` | 将共享资源接入 DevEco 与 BitFun kernel 的 OpenCode 插件 API、Skill 目录或 Claude MCP |
+| Claude 原生资源 | `assets/claude-code/` | 提供 Claude 可直接发现的 Command、Agent、Skill 和 MCP 配置 |
+
+宿主负责模型调用、会话、权限控制、命令解析和 Agent 调度；插件负责资源内容及工具实现。接入使用两个宿主已有的扩展机制，无需修改宿主源码。
+
+```mermaid
+flowchart TD
+    M[模块定义] --> R[Registry 聚合与校验]
+    R --> D[DevEco 插件适配器]
+    R --> I[静态 Skill 路径]
+    R --> B[BitFun kernel 插件适配器]
+    R --> J[BitFun 命令文件]
+    R --> C[Claude MCP Server]
+    D --> DH[DevEco Command / Agent / Tool]
+    B --> BH[BitFun Agent / Tool / Skill]
+    J --> BJ[BitFun Command]
+    I --> DS[DevEco skills 目录]
+    C --> CT[Claude MCP Tools]
+    A[Claude 原生资源目录] --> CH[Claude Command / Agent / Skill]
+```
+
+当前内置轨迹分析 mock 模块和 `code-review` 模块。轨迹模块验证四类资源；代码审查模块只注册 Command 和 Tool，直接封装 review 的完整 `cr review` 引擎。代码审查的结构、配置和验证说明见 `docs/code-review-integration.md`。
+
+## 2. 工程目录结构
+
+以下列出维护中的源码、资源、配置，以及构建产物。`dist/`、生成的 MCP 脚本、`node_modules/` 和本地 tgz 属于生成内容。
+
+```text
+.
+├── src/
+│   ├── index.ts                         # npm 默认入口，导出 DevEco 插件和共享模块 API
+│   ├── plugin/
+│   │   ├── contracts.ts                 # 四类资源、执行上下文、工具返回值的类型
+│   │   ├── registry.ts                  # 模块过滤、资源聚合、冲突和引用校验
+│   │   ├── index.ts                     # createRegistry 与默认内置模块列表
+│   │   └── modules/
+│   │       └── trajectory-analysis.ts   # 轨迹分析模块及三个 mock Tool
+│   └── hosts/
+│       ├── shared/
+│       │   ├── opencode.ts              # OpenCode 插件宿主实现，DevEco 与 BitFun 共用
+│       │   └── schema.ts                # 共享 JSON Schema 到宿主参数定义的转换
+│       ├── deveco/
+│       │   └── plugin.ts                # DevEco V1 Hooks 适配器（写 Command）
+│       ├── bitfun-kernel/
+│       │   ├── plugin.ts                # BitFun kernel 插件入口（不写 Command）
+│       │   └── commands.ts              # 生成 BitFun 命令文件
+│       └── claude-code/
+│           ├── index.ts                 # 导出 MCP 协议处理器
+│           └── mcp-server.ts            # stdio MCP 服务，调用共享 Tool 实现
+├── assets/
+│   ├── skills/                          # 宿主中立的 Skill 静态目录
+│   │   └── vsl-trajectory-analysis/
+│   │       └── SKILL.md                 # 轨迹分析步骤和结果解释规则
+│   └── claude-code/                     # Claude 原生插件根目录
+│       ├── .claude-plugin/
+│       │   └── plugin.json              # 插件名、说明和版本
+│       ├── .mcp.json                    # MCP 服务启动配置
+│       ├── commands/
+│       │   └── trajectory.md            # /vsl:trajectory 命令提示词
+│       ├── agents/
+│       │   └── vsl-trajectory.md         # 轨迹分析 Agent 定义
+│       ├── skills/
+│       │   └── vsl-trajectory-analysis/
+│       │       └── SKILL.md             # 轨迹分析步骤和结果解释规则
+│       └── scripts/
+│           └── mcp-server.js            # 构建生成，Claude 通过 Bun 启动
+├── test/
+│   ├── plugin.test.ts                   # 模块注册、mock 调用、输入、冲突和静态 Skill 检查
+│   └── bitfun-kernel.test.ts            # BitFun 适配器与命令文件生成检查
+├── docs/
+│   └── plugin-design.md                 # 本设计文档
+├── dist/                               # 构建生成的 npm 运行文件
+│   ├── index.js
+│   └── hosts/
+│       ├── deveco/
+│       │   └── plugin.js
+│       ├── bitfun-kernel/
+│       │   └── plugin.js
+│       └── claude-code/
+│           └── index.js
+├── package.json                        # npm 元数据、入口、依赖和构建命令
+├── bun.lock                            # 开发依赖锁定
+├── bunfig.toml                         # Bun 配置
+├── tsconfig.json                       # TypeScript 类型检查配置
+├── tsconfig.build.json                 # TypeScript 构建配置文件；当前 JS 由 Bun 打包
+├── AGENTS.md                           # 仓库开发约定
+├── .gitignore                          # 生成文件与本地目录排除规则
+└── README.md                           # 安装和开发说明
+```
+
+新增模块主要修改 `src/plugin/modules/` 和 `src/plugin/index.ts`。构建从 Registry 统一生成 Skill、Claude 原生资源和 BitFun 命令文件；通过 `vsl init` 安装或更新时，按选中模块同步实际宿主配置。手动安装仍可使用原生入口。
+
+## 3. 模块与资源契约
+
+### 3.1 PluginModule
+
+共享契约定义在 `src/plugin/contracts.ts`：
+
+```ts
+export type PluginModule = {
+  id: string
+  version: string
+  description: string
+  commands?: ModuleCommand[]
+  agents?: ModuleAgent[]
+  skills?: ModuleSkill[]
+  tools?: ModuleTool[]
+}
+```
+
+`id` 标识模块；四个资源数组均可省略，因此模块可以只提供 Skill 或 Tool。模块版本描述模块自身，npm 包版本描述整个分发包；Claude 插件 manifest 和 MCP server 也有各自的版本字段，当前由开发者分别维护。
+
+### 3.2 四类资源的职责
+
+| 资源 | 主要字段 | 执行含义 |
+| --- | --- | --- |
+| Command | `name`、`description`、`template`，可选 `agent`、`model`、`subtask`、`toolNames` | 用户的 slash 入口；宿主展开参数并将提示词交给 Agent |
+| Agent | `name`、`mode`、`prompt`，可选模型、权限和可见性 | 定义模型角色和执行约束，由宿主调度 |
+| Skill | `name`、`description`、`content`，可选 `files` | 按需加载的步骤、规则和参考资料 |
+| Tool | `name`、`description`、`input`、`execute` | 接受结构化参数，执行代码并返回结果 |
+
+Command 可以指向专用 Agent，也可以由主 Agent 处理。Agent 可以加载 Skill、调用 Tool，或依据已有上下文回答。Skill 本身是指令资源，只有其中要求的步骤涉及代码执行时才需要调用 Tool。因此，slash 命令的执行并不要求每次都落到 Tool 上。
+
+`toolNames` 用于校验 Command 引用的工具是否存在；当前执行权限由宿主配置决定，这个字段不生成工具白名单。Skill 名称出现在提示词中时，Registry 也不会自动把它转换为强制加载关系。
+
+### 3.3 Tool 的宿主无关接口
+
+Tool 通过 `execute(input, context)` 执行。`input` 是外部输入，模块需要校验其内容；`context` 提供工作目录、工作树目录、取消信号、可选会话 ID 和进度上报函数。
+
+统一返回值为：
+
+```ts
+export type ToolOutput = {
+  title: string
+  output: string
+  metadata?: Record<string, unknown>
+}
+```
+
+DevEco 适配器将返回值交给原生工具机制；Claude MCP 适配器将 `output` 转换为 MCP 文本结果，并映射 `isError`。MCP 使用进程工作目录，支持请求取消、并发调用和错误隔离，进度上报仍为空实现。代码审查工具支持显式传入 `repo`。
+
+## 4. Registry 注册机制
+
+`createRegistry()` 默认加载轨迹分析和代码审查模块；也可以通过 `modules` 传入明确的模块列表，通过 `enabled` 排除指定模块。例如：
+
+```ts
+const registry = createRegistry({
+  modules: [createTrajectoryAnalysisModule()],
+  enabled: { "trajectory-analysis": true },
+})
+
+const resources = registry.enabled()
+```
+
+聚合过程依次执行：
+
+1. 过滤 `enabled[id] === false` 的模块，其余模块默认启用。
+2. 检查启用模块的 `id` 是否重复。
+3. 分别合并 Command、Agent、Skill、Tool 数组。
+4. 检查每类资源内部的名称冲突。
+5. 检查 Command 的 `agent` 和 `toolNames` 是否引用已注册资源。
+
+最终结果提供四类资源列表，并支持按名称查找 Command 和 Tool。模块目录在代码中组装。init 以模块为粒度选择，保存到安装包内的 `assets/runtime.json`（Claude 原生插件使用 `.vsl-runtime.json`）；宿主通过 `createHostRegistry()` 加载选中模块，并附带 `vsl_runtime_info` 诊断工具。手动安装且没有运行时配置时默认加载全部模块。
+
+## 5. DevEco Code 适配
+
+推荐使用 `vsl init` 的宿主和模块复选向导；下文保留原生手工接入说明。安装与验证操作见 [init 安装](init-installation.md)。
+
+### 5.1 Command、Agent 和 Tool
+
+默认入口 `src/index.ts` 导出 `VslPlugin`。插件加载后，`config` Hook 将模块中的 Command 写入 `config.command`，将 Agent 写入 `config.agent`；如果宿主配置中已有同名资源，会报冲突，避免静默覆盖。
+
+`tool` Hook 将共享 Tool 包装为 `@opencode-ai/plugin` 的原生工具，并把宿主的工作目录、会话 ID、取消信号和进度回调传入共享执行器。
+
+DevEco Tool 包装器根据共享 JSON Schema 生成字符串、布尔值、数字、整数、对象、数组和枚举参数。两端适配器在执行工具前校验输入。
+
+### 5.2 Skill 静态注册
+
+DevEco 通过 `config.skills.paths` 扫描 Skill 目录。npm 包将静态文件放在 `assets/skills/<name>/SKILL.md`，插件加载时把启用模块对应的目录加入 `config.skills.paths`。该流程不依赖 npm `postinstall`，也不写入宿主用户目录。BitFun kernel 适配器注册同一个目录，Skill 内容因此与宿主无关。
+
+Skill 文件随插件版本分发和升级，不会复制到用户配置目录；卸载 npm 包也不会留下需要清理的副本。
+
+包内结构：
+
+```text
+node_modules/@bitfun-vsl/plugin/
+└── assets/
+    └── skills/
+        └── vsl-trajectory-analysis/
+            └── SKILL.md
+```
+
+### 5.3 本地包接入
+
+在本仓库执行 `npm pack` 后，在 DevEco 配置目录安装产物：
+
+```powershell
+cd "$HOME/.config/deveco"
+npm install "D:/path/to/bitfun-vsl-plugin-<version>.tgz"
+```
+
+Skill 随插件入口一起注册。`deveco.jsonc` 中配置专用入口 `"plugin": ["@bitfun-vsl/plugin/server"]`。本地联调也可以直接指向已安装包的 JS 入口，例如：
+
+```json
+{
+  "plugin": [
+    "file:///C:/Users/<user>/.config/deveco/node_modules/@bitfun-vsl/plugin/dist/hosts/deveco/plugin.js"
+  ]
+}
+```
+
+使用自定义 `DEVECO_CONFIG_DIR` 时，安装和启动宿主需要使用相同配置。完成后重启 DevEco，重新加载插件并发现 Skill。
+
+## 6. BitFun Kernel 适配
+
+BitFun（`bitfun_agent_kernel`）的扩展宿主 `src/apps/extension-host` 实现的是 OpenCode 插件契约（对齐 `@opencode-ai/plugin@1.17.18`），所以复用 `src/hosts/shared/opencode.ts`，与 DevEco 只差两处：入口不写 `config.command`，命令改由命令文件分发。
+
+### 6.1 入口与加载方式
+
+`vsl init` 中选择 BitFun 后，安装器更新宿主实际配置目录下的依赖：Windows 为 `%APPDATA%/bitfun/config`，macOS 为 `~/Library/Application Support/bitfun/config`，Linux 为 `${XDG_CONFIG_HOME:-~/.config}/bitfun/config`。`BITFUN_USER_ROOT`、`BITFUN_E2E_USER_ROOT` 可覆盖用户根目录，`--config-dir` 可直接指定配置目录。安装器将 `app.json` 中的 VSL 注册归一为已安装包的 BitFun 专用入口 file URL，并同步 OpenCode 命令文件。它不依赖全局 npm 副本或按包名回退到 DevEco 入口。`--command-dir` 指定自定义 OpenCode 配置目录。
+
+BitFun 从上述配置目录中 `app.json` 的 `plugin` 数组读取声明，入口解析顺序为 `exports["./server"]` → `main` → `index.*`。包内提供两个入口：
+
+| 入口 | 解析结果 | 适用场景 |
+| --- | --- | --- |
+| `@bitfun-vsl/plugin`（包名声明） | `exports["./server"]` → `dist/hosts/deveco/plugin.js` | BitFun 按包名安装时唯一生效的入口 |
+| `file://.../dist/hosts/bitfun-kernel/plugin.js` | 直接指向 BitFun 专用入口 | 本地联调、需要精简行为时 |
+
+两个入口都只导出一个服务函数：BitFun 把模块中任何非函数导出视为错误，当 `default` 不是 `{ server }` 对象时还会把每个函数导出都当作插件调用。因此 `default` 与具名导出必须指向同一个函数。
+
+DevEco 入口也接受声明选项，供只能按包名安装的 BitFun 关闭命令写入：
+
+```jsonc
+{
+  "plugin": [{ "spec": "@bitfun-vsl/plugin", "options": { "writeCommands": false } }]
+}
+```
+
+### 6.2 四类资源映射
+
+| 资源 | BitFun 机制 | 状态 |
+| --- | --- | --- |
+| Tool | 插件 `tool` Hook，工具按原始名称暴露，上下文提供 `directory`、`worktree`、`abort`、`sessionID`、`metadata` | 插件子 Agent 可见，主 Agent 需经 Task 委派 |
+| Agent | `config.agent` 投影为外部子 Agent，`mode`（primary/subagent/all）语义一致 | 直接可用 |
+| Skill | `config.skills.paths` 投影为插件 Skill 根，要求绝对路径、非软链目录、`SKILL.md` 不超过 256 KiB | 直接可用 |
+| Command | `config.command` 没有投影；命令只来自外部命令源（OpenCode 生态扫描 `~/.config/opencode/command[s]/`、`<project>/.opencode/command[s]/`） | 需命令文件 |
+
+BitFun 的插件激活只发生在本地工作区，远程工作区不加载插件。
+
+### 6.3 命令文件
+
+命令名由 `command/` 下的相对路径决定，`command/vsl/trajectory.md` 在 BitFun 中显示为 `/vsl/trajectory`。启用 OpenCode 外部兼容后，VSL 将命令文件安装到 BitFun 扫描的外部命令目录，进入会话后由宿主刷新并显示。当前 BitFun 启动页不读取外部命令，启动页直接显示需要修改 BitFun 宿主；VSL 插件入口无法替代宿主的启动发现逻辑。`src/hosts/bitfun-kernel/commands.ts` 从 Registry 生成这些文件：
+
+```bash
+bun run install:bitfun                 # 写入 ~/.config/opencode/command/vsl/
+bun run install:bitfun -- --root <dir> # 写入其它 OpenCode 配置根
+bun run install:bitfun -- --agent      # 额外写入 agent 前置字段
+```
+
+生成结果与宿主解析规则一致：前置元数据只使用 `description`、`agent`、`model`、`subtask`，正文保留 `$ARGUMENTS` 占位符。旧的 `install:bitfun` 脚本重复执行会先删除 `command/vsl/` 再重建。推荐改用 `vsl init --host bitfun`：它只更新有收据的受管文件、清理取消模块的旧命令并保留其它用户文件；不要对 init 托管目录重复执行旧脚本。
+
+默认不写 `agent`，命令由主 Agent 执行模板。插件工具对原生主 Agent 不可见：插件工具注册时带 `native_agent_visible=false`，主 Agent 直接调用会返回 `not an available deferred tool in the current context`。主 Agent 通过 `Task` 把工具调用委派给插件子 Agent（如 `vsl-trajectory`），命令因此仍能触达插件工具，代价是多一次子会话。原因在宿主侧：`command_source.rs` 把带 `agent` 且无 `model`/`variant` 的命令解析为 `FreshExternalSubagent{ecosystem_id: "opencode", logical_id: <agent>}`，再按 `external_sources.rs` 的 `active_subagents` 校验；该集合只来自外部子 Agent 的核对结果，而插件通过 `config.agent` 投影的 Agent 由 `plugin_capability_publication.rs` 写入 registry 路由覆盖层，不在这一集合内。因此指向插件自有 Agent（如 `vsl-trajectory`）的 `agent` 字段会让命令变成 `Restricted` 而无法执行。`--agent` 只适用于宿主已经把同名外部子 Agent 注册并且审批通过的场景。
+
+### 6.4 验证方式
+
+`bun test` 覆盖适配器和命令文件生成。宿主契约按 `loader.ts` 与 `plugin_config_projection.rs` 的规则核对：入口在包内、单服务函数、`config.command` 未被写入、Agent 与 Skill 投影字段合法、命令文件可被命令源解析。
+
+## 7. Claude Code 适配
+
+### 7.1 原生插件资源
+
+Claude 通过 `assets/claude-code/` 加载插件，目录中的资源分别对应：
+
+| 文件或目录 | Claude 中的作用 |
+| --- | --- |
+| `.claude-plugin/plugin.json` | 声明插件名 `vsl` 和插件元数据 |
+| `commands/trajectory.md` | 注册 `/vsl:trajectory` |
+| `agents/vsl-trajectory.md` | 注册可由宿主调用的分析 Agent |
+| `skills/vsl-trajectory-analysis/SKILL.md` | 注册可由主 Agent 或子 Agent 加载的 Skill |
+| `.mcp.json` | 声明本地 MCP 服务的启动方式 |
+
+Claude 按插件名添加命名空间。当前环境中 Agent 显示为 `vsl:vsl-trajectory`，Skill 显示为 `vsl:vsl-trajectory-analysis`；原生文件名和共享资源名保留模块中的定义。
+
+当前 Command 文件提供分析提示词，Agent 文件独立注册；该 Command 尚未配置显式的专用 Agent 路由。因此 Claude 中的 slash 调用可以由主 Agent 完成，专用 Agent 也可以独立被调用。DevEco 中则通过 Command 的 `agent` 字段绑定 `vsl-trajectory`，两端的调度行为由各自的原生机制决定。
+
+Claude 的 Markdown、插件清单、MCP 配置与 Skill 均由 `src/install/resources.ts` 从共享 Registry 生成。构建时生成全部资源，init 安装时从待安装包按所选模块生成插件，MCP 也读取同一模块配置。
+
+### 7.2 MCP Tool
+
+`.mcp.json` 使用以下命令启动包内服务：
+
+```text
+bun ${CLAUDE_PLUGIN_ROOT}/scripts/mcp-server.js
+```
+
+因此当前 Claude MCP 运行环境需要安装 Bun。服务通过标准输入输出交换逐行 JSON 消息，实现 `initialize`、`ping`、`tools/list` 和 `tools/call`：工具列表来自 Registry，调用按名称找到共享 Tool 并执行。
+
+Claude 中的工具实际名称带有 MCP 前缀，例如 `mcp__plugin_vsl_vsl__vsl_trajectory_analyze`。工具是否允许运行由 Claude 的权限策略控制；资源被发现后，仍需取得执行权限才能完成调用。
+
+本地验证可指向源码中的插件目录，或 npm 安装包内部的同名目录：
+
+```powershell
+claude plugin validate ./assets/claude-code
+claude --plugin-dir ./assets/claude-code -p "/vsl:trajectory sample.trace"
+```
+
+## 8. 轨迹分析模块调用示例
+
+模块定义位于 `src/plugin/modules/trajectory-analysis.ts`，提供以下资源：
+
+| 类型 | 名称 | 当前行为 |
+| --- | --- | --- |
+| Command | `/vsl:trajectory` | 接收 `$ARGUMENTS`，要求加载 Skill 并执行分析 |
+| Agent | `vsl-trajectory` | 组织分析过程，依据工具结果回答 |
+| Skill | `vsl-trajectory-analysis` | 描述读取、分析、按需生成报告的步骤 |
+| Tool | `vsl_trajectory_read` | 返回事件数量和持续时间的 mock 数据 |
+| Tool | `vsl_trajectory_analyze` | 返回阶段、异常和评分的 mock 数据 |
+| Tool | `vsl_trajectory_report` | 返回一段 mock 报告文本 |
+
+执行 `/vsl:trajectory sample.trace` 时，宿主展开参数并运行分析提示词。DevEco 调度专用子 Agent；Claude 按当前 Command 和 Agent 配置执行。Agent 加载 Skill 后，按指令调用 `read → analyze → report（按需）`，最后将工具结果组织为回答。
+
+上述顺序通过提示词和 Skill 指导模型执行，当前没有强制步骤状态机。需要保证固定步骤必定执行时，可以将这些步骤组合成一个确定性 Tool。
+
+分析工具的返回示例：
+
+```json
+{
+  "source": "sample.trace",
+  "eventCount": 12,
+  "phases": 3,
+  "anomalies": 1,
+  "score": 0.92,
+  "mock": true
+}
+```
+
+当前工具只校验 `source` 为字符串，返回固定结果，文件无需真实存在。该结果用于证明宿主能够找到资源并执行共享代码；真实轨迹解析和分析能力需要后续替换 mock 实现。
+
+## 9. 如何扩展模块
+
+1. 在 `src/plugin/modules/` 中新增模块文件，返回一个 `PluginModule`。
+2. 按需要填写四类资源；采用统一前缀避免命名冲突。当前 Skill 名称接受小写字母、数字和连字符组成的名称。
+3. 在 `src/plugin/index.ts` 的默认模块列表中注册模块。启用后的 DevEco Command、Agent、Tool 和静态 Skill 都来自该列表。
+4. 为 Claude 增加对应的 Command、Agent、Skill 原生文件。新增 Tool 会随 Registry 进入 MCP 工具列表。
+5. 为 Tool 声明共享 JSON Schema 并校验输入；DevEco 参数适配器和 Claude MCP 复用参数定义。
+6. 添加模块执行与资源注册测试；涉及 Skill 时，验证打包产物中的静态文件和 Skill 发现过程。
+
+Tool 的可复用逻辑保留在共享模块中；宿主目录负责参数、上下文和结果的转换。这样一个模块的执行代码可以被两个宿主共同使用。
+
+## 10. 构建、打包与验证
+
+### 10.1 开发与产物
+
+```bash
+bun install --ignore-scripts
+bun test
+bun run typecheck
+bun run build
+npm pack
+```
+
+源码依赖安装使用 `--ignore-scripts`，避免开发环境在构建前执行依赖 `dist/` 的安装入口。`typecheck` 使用 `tsgo --noEmit`；`build` 使用 Bun 生成运行文件；`npm pack` 通过 `prepack` 自动执行构建。
+
+npm 包包含 `dist/`、`assets/`、本文档及 npm 默认包含的包元数据和 README。DevEco 插件、Claude 原生资源、MCP 服务和静态 Skill 随同一个 tgz 分发。
+
+当前构建实际生成 JavaScript；`package.json` 中声明的 `.d.ts` 路径和 `dist/plugin/index.js` 尚未由构建命令产出。宿主集成使用已生成的运行入口；对外直接消费共享模块子路径和类型声明的发布支持仍需补齐。
+
+### 10.2 验证内容
+
+| 层次 | 内容 | 通过依据 |
+| --- | --- | --- |
+| 模块测试 | 四类资源聚合、mock 输出、无效输入、重复模块 | `test/plugin.test.ts` |
+| 静态 Skill 测试 | 校验静态目录注入和 `SKILL.md` 存在 | `test/plugin.test.ts` |
+| BitFun 适配器 | 不写 Command、入口与选项行为、命令文件生成与清理 | `test/bitfun-kernel.test.ts` |
+| 打包安装 | 真实安装 tgz，检查运行时依赖和静态 Skill 文件 | 包内文件、入口加载和宿主发现结果 |
+| DevEco 集成 | Command 触发、Agent 调度、Tool 结果、Skill 发现 | 宿主日志、会话记录和 `deveco debug skill` |
+| BitFun 集成 | 工具列表、子 Agent、Skill 发现、命令文件注册 | 宿主插件日志与命令面板 |
+| Claude 集成 | 插件校验、资源发现、MCP 连接与 Tool 执行 | Claude 初始化信息与调用结果 |
+
+本地已经验证轨迹 mock 调用、tgz 安装后的静态 Skill 路径注入，以及 DevEco 原生 Skill 发现。增加模块或改变安装路径后，应围绕受影响的资源重新验证；仅看到工具名称或插件安装成功，不能替代实际执行结果。

package/package.json

@@ -1,6 +1,74 @@
-{
-  "name": "@bitfun-vsl/plugin",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "$schema": "https://json.schemastore.org/package.json",
+  "name": "@bitfun-vsl/plugin",
+  "version": "0.0.2",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "type": "module",
+  "license": "MIT",
+  "description": "Shared modules and native host adapters for DevEco Code, Claude Code and BitFun",
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitcode.com/OpenBitFun/bitfun_horizon_verify.git"
+  },
+  "homepage": "https://gitcode.com/OpenBitFun/bitfun_horizon_verify#readme",
+  "scripts": {
+    "prepack": "bun run build",
+    "typecheck": "tsgo --noEmit",
+    "test": "bun test",
+    "install:bitfun": "bun src/hosts/bitfun-kernel/commands.ts",
+    "build": "bun run script/build.ts"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./plugin": {
+      "types": "./dist/plugin/index.d.ts",
+      "import": "./dist/plugin/index.js"
+    },
+    "./hosts/deveco": {
+      "types": "./dist/hosts/deveco/plugin.d.ts",
+      "import": "./dist/hosts/deveco/plugin.js"
+    },
+    "./server": {
+      "types": "./dist/hosts/deveco/plugin.d.ts",
+      "import": "./dist/hosts/deveco/plugin.js"
+    },
+    "./hosts/bitfun-kernel": {
+      "types": "./dist/hosts/bitfun-kernel/plugin.d.ts",
+      "import": "./dist/hosts/bitfun-kernel/plugin.js"
+    },
+    "./hosts/claude-code": {
+      "types": "./dist/hosts/claude-code/index.d.ts",
+      "import": "./dist/hosts/claude-code/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "assets",
+    "README.md",
+    "docs/plugin-design.md",
+    "docs/init-installation.md",
+    "docs/code-review-integration.md"
+  ],
+  "dependencies": {
+    "@inquirer/prompts": "^8.7.5",
+    "@opencode-ai/plugin": "1.17.9",
+    "jsonc-parser": "3.3.1"
+  },
+  "devDependencies": {
+    "@tsconfig/bun": "1.0.9",
+    "@types/bun": "1.3.13",
+    "@types/node": "24.12.2",
+    "typescript": "5.8.2",
+    "@typescript/native-preview": "7.0.0-dev.20251207.1"
+  },
+  "bin": {
+    "vsl": "dist/cli/index.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}