@x-otto/plugin 0.1.0-alpha.1 → 0.1.0-alpha.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.md +58 -45
  2. package/dist/index.d.ts +886 -76
  3. package/dist/index.js +2 -2
  4. package/package.json +7 -6
package/README.md CHANGED
@@ -1,90 +1,103 @@
1
1
  # @x-otto/plugin
2
2
 
3
- > Plugin 清单（`otto-plugin.json`）的解析、目录发现、贡献词表、信任模型与作者 SDK——RFC-044 插件体系的「只读不执行」地基层。
3
+ > Parsing of the plugin manifest (`otto-plugin.json`), directory discovery, contribution vocabulary, trust model, and author SDK — the "read-only, no execution" foundation layer of the plugin system.
4
4
 
5
- `@x-otto/plugin` 是 otto 插件系统的协议层与契约层。一个插件 = 一个目录 + 一份 `otto-plugin.json`，其目录下用 `skills/`、`agents/`、`commands/`、`.mcp.json` 等子目录贡献能力（由消费方 `@x-otto/coding` 的各轴 loader 消费）。
5
+ `@x-otto/plugin` is the protocol and contract layer of otto's plugin system. A plugin = a directory + an
6
+ `otto-plugin.json` file, which contributes capabilities via subdirectories such as `skills/`, `agents/`, `commands/`,
7
+ and `.mcp.json` (consumed by the various axis loaders in `@x-otto/coding`).
6
8
 
7
- ## 核心功能
9
+ ## Core Features
8
10
 
9
- | 模块 | 功能 |
11
+ | Module | Function |
10
12
  |------|------|
11
- | `parsePluginManifest` | 解析 manifest（fail-closed + lenient 混合） |
12
- | `discoverPlugins` | 扫描三层插件目录（项目/仓库/用户） |
13
- | `topoSortPlugins` | 拓扑排序 + 缺依赖传递剔除 + 环检测 |
14
- | `filterEngineCompatible` | 引擎 ABI 版本兼容过滤 |
15
- | `definePlugin` | 插件作者 SDK（Vite defineConfig 对等物） |
16
- | 信任模型 | 布尔信任 + 逐高危能力授予 |
17
- | `PluginI18nRegistry` | 国际化条目注册表（与 TUI STR 平行） |
18
- | 贡献点系统 | 动作/菜单/context-key 贡献点解析与派发 |
13
+ | `parsePluginManifest` | Parses the manifest (fail-closed + lenient hybrid) |
14
+ | `discoverPlugins` | Scans the three-tier plugin directory structure (project/repository/user) |
15
+ | `topoSortPlugins` | Topological sort + transitive removal of missing dependencies + cycle detection |
16
+ | `filterEngineCompatible` | Filters by engine ABI version compatibility |
17
+ | `definePlugin` | Plugin-author SDK (equivalent to Vite's defineConfig) |
18
+ | Trust Model | Boolean trust + per-high-risk-capability grants |
19
+ | `PluginI18nRegistry` | Internationalization entry registry (parallel to TUI STR) |
20
+ | Contribution Point System | Parsing and dispatch of action/menu/context-key contribution points |
19
21
 
20
- ## 安装
22
+ ## Installation
21
23
 
22
24
  ```bash
23
25
  pnpm add @x-otto/plugin
24
26
  ```
25
27
 
26
- ## 用法
28
+ ## Usage
27
29
 
28
30
  ```ts
29
- // 发现已安装插件
31
+ // Discover installed plugins
30
32
  import { discoverPlugins } from '@x-otto/plugin'
31
33
  const plugins = discoverPlugins({ cwd, homedir, disabled: ['plugin-x'] })
32
34
 
33
- // 解析单一 manifest
35
+ // Parse a single manifest
34
36
  import { parsePluginManifest } from '@x-otto/plugin'
35
37
  const manifest = parsePluginManifest(content, path) // null on fail
36
38
 
37
- // 作者定义插件
39
+ // Author-defined plugin
38
40
  import { definePlugin } from '@x-otto/plugin'
39
41
  export default definePlugin((ctx) => ({
40
42
  hooks: {
41
43
  preToolUse: (ctx) => ctx.toolName === 'write' ? { decision: 'deny' } : { decision: 'allow' },
44
+ // 通知出站交付（turn_complete/error/approval_required/input_required 归一后触发）。
45
+ // 例：把 otto 通知转发到自己的推送渠道。
46
+ onNotification: (ctx) => {
47
+ console.log(`[${ctx.notification_type}] ${ctx.message}`)
48
+ },
42
49
  },
43
50
  }))
44
51
  ```
45
52
 
46
- ## 目录概览
53
+ ## Directory Overview
47
54
 
48
55
  ```
49
56
  src/
50
57
  manifest.ts # PluginManifest zod schema + parsePluginManifest
51
- discovery.ts # discoverPlugins 三层目录扫描
52
- contributions.ts # PluginContributions 统一贡献词表类型
53
- contribution-points.ts # 贡献点注册表（POINT 常量）
54
- contribution-resolver.ts # 贡献点解析器
55
- context-keys.ts # 上下文键求值
56
- contribution-dispatch.ts # 贡献点派发器
58
+ discovery.ts # discoverPlugins three-tier directory scanning
59
+ contributions.ts # PluginContributions unified contribution vocabulary type
60
+ contribution-points.ts # contribution point registry (POINT constants)
61
+ points-extension.ts # per-domain contribution point constants
62
+ points-shell.ts # per-domain contribution point constants
63
+ contribution-resolver.ts # contribution point resolver
64
+ context-keys.ts # context key evaluation
65
+ contribution-dispatch.ts # contribution point dispatcher
57
66
  sdk.ts # definePlugin + PluginModule/PluginContext/PluginHooks
58
- dependency-graph.ts # topoSortPlugins 拓扑排序
59
- engine-compat.ts # 引擎版本兼容门
60
- api-version.ts # PLUGIN_API_VERSION 常量
61
- plugin-trust.ts # 信任模型（HIGH_RISK_CAPABILITIES）
62
- trust-store.ts # 信任白名单持久化
63
- i18n-registry.ts # 国际化条目注册表
64
- input/ # sigil 输入系统（builtin/file/registry）
67
+ dependency-graph.ts # topoSortPlugins topological sort
68
+ engine-compat.ts # engine version compatibility gate
69
+ api-version.ts # PLUGIN_API_VERSION constant
70
+ capabilities.ts # PLUGIN_CAPABILITIES + HIGH_RISK_CAPABILITIES risk classification (single source)
71
+ plugin-trust.ts # trust model (executable surface scan + per-capability grant)
72
+ trust-store.ts # trust allowlist persistence
73
+ i18n-registry.ts # internationalization entry registry
74
+ input/ # sigil input system (builtin/file/registry)
65
75
  index.ts
66
- tests/ # 测试文件
76
+ tests/ # test files
67
77
  ```
68
78
 
69
- ## 关键类型
79
+ ## Key Types
70
80
 
71
- - `PluginManifest`：插件清单（id/name/scripts/capabilities/engines/contributes）
72
- - `PluginContributions`：统一贡献词表（commands/agents/skills/mcp/providers/oauth/panels/actions/menus/...）
73
- - `PluginModule`：代码插件的运行时模块（hooks/tools/monitors/providerFactories/services/...）
74
- - `PluginContext`：装载时注入工厂的上下文
75
- - `DiscoveredPlugin`：发现结果（id/dir/manifest/scope）
81
+ - `PluginManifest`: the plugin manifest (id/name/scripts/capabilities/engines/contributes)
82
+ - `PluginContributions`: unified contribution vocabulary (commands/agents/skills/mcp/providers/oauth/panels/actions/menus/...)
83
+ - `PluginModule`: the runtime module of a code plugin (hooks/tools/monitors/providerFactories/services/...)
84
+ - `PluginContext`: the context injected with factories at load time
85
+ - `DiscoveredPlugin`: a discovery result (id/dir/manifest/scope)
76
86
 
77
- ## 信任模型
87
+ ## Trust Model
78
88
 
79
- 高危能力清单（`HIGH_RISK_CAPABILITIES`）：provider / tools / tui.renderer / network / wire-protocol / a2ui.component / panel.backend / input.resolver / a2ui.renderer / agent.dispatch / service。已信任插件升级后首次声明这些能力必须重新确认。
89
+ High-risk capability list (`HIGH_RISK_CAPABILITIES`, derived in `capabilities.ts` from the per-capability risk
90
+ classification): provider / tools / tui.renderer / network / wire-protocol / a2ui.component / panel.backend /
91
+ mcp.server / input.resolver / a2ui.renderer / agent.dispatch / service / session.read / llm.complete / user.ask.
92
+ When an already-trusted plugin is upgraded and declares one of these capabilities for the first time, it must be
93
+ re-confirmed.
80
94
 
81
- ## 依赖
95
+ ## Dependencies
82
96
 
83
- - Internal: `@x-otto/env`, `@x-otto/interchange`, `@x-otto/provider`, `@x-otto/shared`
97
+ - Internal: `@x-otto/env`, `@x-otto/hook-contracts`, `@x-otto/interchange`, `@x-otto/provider`, `@x-otto/shared`
84
98
  - External: `zod`, `semver`
85
99
 
86
- ## 相关
100
+ ## Related
87
101
 
88
102
  - [Architecture](./ARCHITECTURE.md)
89
- - RFC-044 插件体系（D2 manifest/发现；R4 fail-closed、R6 source key、R7 层源覆盖）
90
- - `@x-otto/extension`（re-export 本包 SDK 作为 extension 作者统一入口）
103
+ - `@x-otto/extension` (re-exports this package's SDK as the unified entry point for extension authors)