@easbot/plugin 0.3.29 → 0.3.36

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.
package/README.en.md CHANGED
@@ -2,17 +2,21 @@
2
2
 
3
3
  # @easbot/plugin
4
4
 
5
- EASBot Plugin System - Hooks, Commands, and Tool Management
5
+ EASBot Plugin System — type contracts, manifest validation, and extension point definitions
6
6
 
7
7
  ## Version
8
8
 
9
- v0.3.29
9
+ v0.3.36
10
10
  ## Features
11
11
 
12
- - **Hook System**: Event-driven hook mechanism for extending Agent behavior
13
- - **Command System**: Extensible command registration and execution
14
- - **Tool System**: Plugin tools with permission control
15
- - **Shell Integration**: Shell command execution support
12
+ - **Plugin contract**: `Plugin` / `PluginInput` / `PluginDefinition` (single source of truth for all extension points)
13
+ - **Hook contract**: `HookEvent` / `HOOK_EVENTS` / `HookMatcher` (with `priority` / `timeoutMs` / `failurePolicy`) / 5 executor schemas / event input validation
14
+ - **Auth contract**: `AuthHook` / `AuthMethod` / `AuthPrompt` / `AuthOAuthResult` (OAuth and API methods)
15
+ - **Command & tool contract**: re-exports `CommandDefinition` / `ToolDefinition` from `@easbot/types` plus the `createTool` factory
16
+ - **Manifest & validation**: `PluginManifestSchema` / `validatePluginManifest` / `validatePluginDefinition` (closed top-level fields, at least one capability, bidirectional `capabilities` check)
17
+ - **No marketplace**: the install-source catalog belongs to the `@easbot/agent` CLI layer; `PluginDefinition` does not declare this field
18
+
19
+ > ⚠️ This is a **contract-only package**: no HookRegistry implementation, no plugin loading, no capability registration. Loading and registration live in `@easbot/agent/src/plugin/plugin.ts`; see [`spec/plugin-standard.md`](../../spec/plugin-standard.md).
16
20
 
17
21
  ## Installation
18
22
 
@@ -22,95 +26,173 @@ pnpm add @easbot/plugin
22
26
 
23
27
  ## Quick Start
24
28
 
25
- ### Hook System
26
-
27
- ```typescript
28
- import { createHookRegistry, HOOK_EVENTS } from '@easbot/plugin';
29
+ ### Plugin entry
29
30
 
30
- // Create hook registry
31
- const hooks = createHookRegistry();
31
+ A plugin entry MUST export one of `default` / `Plugin` / `plugin`, with the signature `Plugin = (input: PluginInput) => Promise<PluginDefinition>`.
32
32
 
33
- // Register a hook
34
- hooks.register(HOOK_EVENTS.BEFORE_TOOL_CALL, async (tool, context) => {
35
- console.log('Tool called:', tool.name);
36
- return context;
33
+ ```typescript
34
+ import { HookEvent, tool, type Plugin, type PluginDefinition } from '@easbot/plugin';
35
+
36
+ export const MyPlugin: Plugin = async (input): Promise<PluginDefinition> => ({
37
+ hooks: [
38
+ {
39
+ event: HookEvent.ToolBefore,
40
+ hooks: [
41
+ {
42
+ type: 'function',
43
+ handler: async (hookInput, context) => ({
44
+ modified: false,
45
+ input: hookInput,
46
+ output: { directory: input.directory },
47
+ }),
48
+ },
49
+ ],
50
+ },
51
+ ],
52
+ tools: {
53
+ echo: tool({
54
+ description: 'Echo the input text',
55
+ args: { text: tool.schema.string() },
56
+ execute: async (args) => String(args.text ?? ''),
57
+ }),
58
+ },
37
59
  });
38
- ```
39
60
 
40
- ### Command System
61
+ export default MyPlugin;
62
+ export { MyPlugin as Plugin };
63
+ ```
41
64
 
42
- ```typescript
43
- import { createCommandRegistry } from '@easbot/plugin';
65
+ ### Command system
44
66
 
45
- const commands = createCommandRegistry();
67
+ The **contract types** for commands (`CommandDefinition` / `CommandInfo` / `CommandArguments` / `CommandExecutionContext` / `CommandExecuteResult` …) have their **single source of truth in `@easbot/types`** (`native/command.ts`); this package only re-exports them.
46
68
 
47
- // Register a command
48
- commands.register({
49
- name: 'hello',
50
- description: 'Say hello',
51
- execute: async (args, session) => {
52
- await session.send('Hello!');
69
+ ```typescript
70
+ import type { CommandDefinition } from '@easbot/plugin';
71
+
72
+ const myPlugin = async (): Promise<PluginDefinition> => ({
73
+ commands: {
74
+ hello: {
75
+ name: 'hello',
76
+ description: 'Say hello',
77
+ execute: async (args, ctx) => ({
78
+ title: 'hello',
79
+ metadata: { sessionId: ctx.sessionId },
80
+ output: 'Hello!',
81
+ success: true,
82
+ }),
83
+ },
53
84
  },
54
85
  });
55
86
  ```
56
87
 
57
- ### Tool System
88
+ > ⚠️ The command **registry** (`register` / `list`) lives in `CommandRegistry` of `@easbot/agent`; this package only provides type declarations.
89
+
90
+ ### Tool system
91
+
92
+ The real signature of `createTool` / `tool()` is `{ description, args, execute }` — there are **no** `name` / `parameters` fields. `args` is a Zod schema map and `execute` returns `Promise<string>`.
58
93
 
59
94
  ```typescript
60
95
  import { createTool } from '@easbot/plugin';
96
+ import { z } from 'zod';
61
97
 
62
98
  const tool = createTool({
63
- name: 'my-tool',
64
- description: 'A custom tool',
65
- parameters: z.object({
66
- input: z.string(),
67
- }),
68
- execute: async ({ input }) => {
69
- return { result: input.toUpperCase() };
70
- },
99
+ description: 'Uppercase the input text',
100
+ args: { input: z.string() },
101
+ execute: async ({ input }) => input.toUpperCase(),
102
+ });
103
+ ```
104
+
105
+ ## Manifest & Validation
106
+
107
+ Contract and executable checks for `plugin.json` (`spec/plugin-standard.md` §2.1 / §6):
108
+
109
+ | API | Description |
110
+ | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
111
+ | `PluginManifestSchema` / `PluginManifest` | Zod schema and type for `plugin.json` (`name` required) |
112
+ | `validatePluginManifest(input)` | Returns `{ ok: true; manifest }` or `{ ok: false; errors: string[] }` |
113
+ | `validatePluginDefinition(def, options?)` | Validates the `PluginDefinition` returned by an entry (MUST be called by the host loader); `options.capabilities` enables the bidirectional manifest check |
114
+ | `PLUGIN_CAPABILITIES` / `PLUGIN_DEFINITION_KEYS` | 8 capability types and the closed set of `PluginDefinition` top-level fields |
115
+ | `PLUGIN_HOOK_FAILURE_POLICIES` | `fail-open` / `fail-closed` |
116
+ | `isValidPluginId(id)` / `PLUGIN_ID_PATTERN` | Plugin id naming: `^[a-z0-9][a-z0-9._-]{1,63}$` |
117
+ | `isValidPluginEntry(entry)` / `PLUGIN_ENTRY_EXTENSIONS` | Entry path safety (`./` prefix, no `..`, only `.mjs/.js/.cjs`) |
118
+ | `PLUGIN_ENTRY_NAMES` | Entry export allowlist `default` / `Plugin` / `plugin` |
119
+
120
+ ```typescript
121
+ import { HookEvent, validatePluginManifest, validatePluginDefinition } from '@easbot/plugin';
122
+
123
+ const manifest = validatePluginManifest({
124
+ name: 'memory',
125
+ entry: './index.mjs',
126
+ capabilities: ['hooks', 'tools'],
71
127
  });
128
+ if (!manifest.ok) throw new Error(manifest.errors.join('; '));
129
+
130
+ const definition = validatePluginDefinition(
131
+ {
132
+ hooks: [
133
+ {
134
+ event: HookEvent.SessionStart,
135
+ hooks: [{ type: 'function', handler: async (input) => ({ modified: false, input }) }],
136
+ },
137
+ ],
138
+ tools: { memory: { description: 'Memory tool', args: {}, execute: async () => 'ok' } },
139
+ },
140
+ { capabilities: manifest.manifest.capabilities },
141
+ );
72
142
  ```
73
143
 
144
+ > `PluginDefinition` is a closed set: it MUST declare at least one capability; `marketplace`, dotted inline hook keys and any unknown top-level field are rejected.
145
+
74
146
  ## API
75
147
 
76
- ### HookRegistry
148
+ ### Hook contract
149
+
150
+ | Symbol | Description |
151
+ | --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
152
+ | `HookEvent` | Event constants (`domain.action.phase`, e.g. `HookEvent.SessionStart`) |
153
+ | `HOOK_EVENTS` | **Array** of event names (`Object.values(HookEvent)`), not an enum object |
154
+ | `HookMatcher` | `{ event, matcher?, hooks, priority?, timeoutMs?, failurePolicy? }`; `event` MUST be in `HOOK_EVENTS` |
155
+ | `HookDefinition` | Union of 5 executors: `command` / `prompt` / `http` / `agent` / `function` |
156
+ | `HookOutputWrapper` | `{ modified, input, output? }`; executors MUST return `{ success: false }` instead of throwing |
157
+ | `validateHookInput` / `safeValidateHookInput` / `getEventInputSchema` | Event input schema validation |
77
158
 
78
- | Method | Description |
79
- | ---------------------------- | ------------------------------- |
80
- | `register(event, handler)` | Register a hook handler |
81
- | `unregister(event, handler)` | Remove a hook handler |
82
- | `clear(event)` | Clear all handlers for an event |
159
+ ### Command types
83
160
 
84
- ### CommandRegistry
161
+ See "Command system" above; single source of truth is `@easbot/types/native/command.ts`.
85
162
 
86
- | Method | Description |
87
- | --------------------- | ------------------ |
88
- | `register(command)` | Register a command |
89
- | `get(name)` | Get a command |
90
- | `execute(name, args)` | Execute a command |
163
+ | Type | Description |
164
+ | ------------------------- | ------------------------------------------------------------ |
165
+ | `CommandDefinition` | Runtime command definition (`execute` required) |
166
+ | `CommandInfo` | Registry entry / HTTP response contract (`execute` optional) |
167
+ | `CommandConfigInfo` | Config-shape command template (value of `config.command`) |
168
+ | `CommandMetadata` | Markdown frontmatter declaration shape |
169
+ | `CommandArguments` | Command arguments (string / record) |
170
+ | `CommandExecutionContext` | Command execution context (sessionId / directory / …) |
171
+ | `CommandExecuteResult` | Command execution result |
91
172
 
92
- ### createTool
173
+ ### createTool / tool
93
174
 
94
- | Property | Type | Description |
95
- | ----------- | --------- | ------------------- |
96
- | name | string | Tool name |
97
- | description | string | Tool description |
98
- | parameters | ZodSchema | Parameter schema |
99
- | execute | function | Tool implementation |
175
+ | Property | Type | Required | Description |
176
+ | ------------- | ------------------------------------ | ----------- | ----------------------------------------- |
177
+ | `description` | `string` | ✅ | Tool description |
178
+ | `args` | `Record<string, z.ZodTypeAny>` | ✅ | Zod schema map for arguments |
179
+ | `execute` | `(args, context) => Promise<string>` | ✅ required | Implementation; enforced by the validator |
180
+
181
+ ### Marketplace (outside this contract)
182
+
183
+ `marketplace` is an **install-source catalog**, not a runtime plugin capability. `PluginDefinition` does not declare it, and this package no longer exports `MarketplaceEntry` / `MarketplaceDefinition` / `registerMarketplace()` registry APIs. The types live in `@easbot/agent/src/cli/plugin/type.ts`; metadata lives in `.easbot-plugin/marketplace.json`.
184
+
185
+ ## Reference Implementation
186
+
187
+ - `packages/memory/src/plugin/` — first plugin built on this contract (4 hooks + 1 tool)
188
+ - `packages/memory/plugin/` — distributable directory installable via `easbot plugins install`
100
189
 
101
190
  ## Development
102
191
 
103
192
  ```bash
104
- # Install dependencies
105
193
  pnpm install
106
-
107
- # Build
108
194
  pnpm build
109
-
110
- # Test
111
- pnpm test
112
-
113
- # Type check
195
+ pnpm test:run # vitest run (manifest / definition / auth / hook closed-set contracts)
114
196
  pnpm type-check
115
197
  ```
116
198
 
package/README.md CHANGED
@@ -2,17 +2,21 @@
2
2
 
3
3
  # @easbot/plugin
4
4
 
5
- EASBot 插件系统 - Hook、命令和工具管理
5
+ EASBot 插件系统 —— 类型契约、清单校验与扩展点定义
6
6
 
7
7
  ## 版本
8
8
 
9
- v0.3.29
9
+ v0.3.36
10
10
  ## 特性
11
11
 
12
- - **Hook 系统**:事件驱动的 Hook 机制,扩展 Agent 行为
13
- - **命令系统**:可扩展的命令注册和执行
14
- - **工具系统**:插件工具与权限控制
15
- - **Shell 集成**:Shell 命令执行支持
12
+ - **插件契约**:`Plugin` / `PluginInput` / `PluginDefinition`(8 类能力字段的闭集,唯一真值源)
13
+ - **Hook 契约**:`HookEvent` / `HOOK_EVENTS` / `HookMatcher`(含 `priority` / `timeoutMs` / `failurePolicy`)/ 5 类执行器 Schema / 事件输入校验
14
+ - **Auth 契约**:`AuthHook` / `AuthMethod` / `AuthPrompt` / `AuthOAuthResult`(OAuth 与 API 两种认证方法)
15
+ - **命令与工具契约**:re-export `@easbot/types` 的 `CommandDefinition` / `ToolDefinition`(`execute` 必填)+ `createTool` 工厂
16
+ - **清单与校验**:`PluginManifestSchema` / `validatePluginManifest` / `validatePluginDefinition`(顶层闭集、至少一能力、`capabilities` 双向交叉校验)
17
+ - **不含 marketplace**:安装源 catalog 归 `@easbot/agent` CLI 层,`PluginDefinition` 不声明该字段
18
+
19
+ > ⚠️ 本包是**纯契约包**:不提供 HookRegistry 实现、不加载插件、不注册能力。加载与注册由 `@easbot/agent/src/plugin/plugin.ts` 负责;完整规范见 [`spec/plugin-standard.md`](../../spec/plugin-standard.md)。
16
20
 
17
21
  ## 安装
18
22
 
@@ -22,95 +26,174 @@ pnpm add @easbot/plugin
22
26
 
23
27
  ## 快速开始
24
28
 
25
- ### Hook 系统
26
-
27
- ```typescript
28
- import { createHookRegistry, HOOK_EVENTS } from '@easbot/plugin';
29
+ ### 插件入口
29
30
 
30
- // 创建 Hook 注册表
31
- const hooks = createHookRegistry();
31
+ 插件入口 MUST 导出 `default` / `Plugin` / `plugin` 之一,签名为 `Plugin = (input: PluginInput) => Promise<PluginDefinition>`。
32
32
 
33
- // 注册 Hook
34
- hooks.register(HOOK_EVENTS.BEFORE_TOOL_CALL, async (tool, context) => {
35
- console.log('Tool called:', tool.name);
36
- return context;
33
+ ```typescript
34
+ import { HookEvent, tool, type Plugin, type PluginDefinition } from '@easbot/plugin';
35
+
36
+ export const MyPlugin: Plugin = async (input): Promise<PluginDefinition> => ({
37
+ hooks: [
38
+ {
39
+ event: HookEvent.ToolBefore,
40
+ hooks: [
41
+ {
42
+ type: 'function',
43
+ handler: async (hookInput, context) => ({
44
+ modified: false,
45
+ input: hookInput,
46
+ output: { directory: input.directory },
47
+ }),
48
+ },
49
+ ],
50
+ },
51
+ ],
52
+ tools: {
53
+ echo: tool({
54
+ description: 'Echo the input text',
55
+ args: { text: tool.schema.string() },
56
+ execute: async (args) => String(args.text ?? ''),
57
+ }),
58
+ },
37
59
  });
60
+
61
+ export default MyPlugin;
62
+ export { MyPlugin as Plugin };
38
63
  ```
39
64
 
40
65
  ### 命令系统
41
66
 
42
- ```typescript
43
- import { createCommandRegistry } from '@easbot/plugin';
44
-
45
- const commands = createCommandRegistry();
67
+ 命令**契约类型**(`CommandDefinition` / `CommandInfo` / `CommandArguments` / `CommandExecutionContext` / `CommandExecuteResult` …)的**唯一真源是 `@easbot/types`**(`native/command.ts`),本包只做 re-export(对外 API 面不变)。
46
68
 
47
- // 注册命令
48
- commands.register({
49
- name: 'hello',
50
- description: '打招呼',
51
- execute: async (args, session) => {
52
- await session.send('你好!');
69
+ ```typescript
70
+ import type { CommandDefinition } from '@easbot/plugin';
71
+
72
+ // 在 PluginDefinition.commands 里声明命令(map 形态,key = command id)
73
+ const myPlugin = async (): Promise<PluginDefinition> => ({
74
+ commands: {
75
+ hello: {
76
+ name: 'hello',
77
+ description: '打招呼',
78
+ execute: async (args, ctx) => ({
79
+ title: 'hello',
80
+ metadata: { sessionId: ctx.sessionId },
81
+ output: '你好!',
82
+ success: true,
83
+ }),
84
+ },
53
85
  },
54
86
  });
55
87
  ```
56
88
 
89
+ > ⚠️ 命令的**注册表**(`register` / `list`)在 `@easbot/agent` 的 `CommandRegistry`,本包只提供类型声明。
90
+
57
91
  ### 工具系统
58
92
 
93
+ `createTool` / `tool()` 的真实签名是 `{ description, args, execute }`,**没有** `name` / `parameters` 字段;`args` 是 Zod schema map,`execute` 返回 `Promise<string>`。
94
+
59
95
  ```typescript
60
96
  import { createTool } from '@easbot/plugin';
97
+ import { z } from 'zod';
61
98
 
62
99
  const tool = createTool({
63
- name: 'my-tool',
64
- description: '自定义工具',
65
- parameters: z.object({
66
- input: z.string(),
67
- }),
68
- execute: async ({ input }) => {
69
- return { result: input.toUpperCase() };
70
- },
100
+ description: 'Uppercase the input text',
101
+ args: { input: z.string() },
102
+ execute: async ({ input }) => input.toUpperCase(),
103
+ });
104
+ ```
105
+
106
+ ## 插件清单与校验
107
+
108
+ `plugin.json` 的契约与可执行检查(对应 `spec/plugin-standard.md` §2.1 / §6):
109
+
110
+ | API | 说明 |
111
+ | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
112
+ | `PluginManifestSchema` / `PluginManifest` | `plugin.json` 的 Zod schema 与类型(`name` 必填) |
113
+ | `validatePluginManifest(input)` | 返回 `{ ok: true; manifest }` 或 `{ ok: false; errors: string[] }` |
114
+ | `validatePluginDefinition(def, options?)` | 校验入口返回的 `PluginDefinition`(宿主加载器 MUST 调用);`options.capabilities` 触发与 manifest 的双向交叉校验 |
115
+ | `isValidPluginId(id)` / `PLUGIN_ID_PATTERN` | 插件 id 命名:`^[a-z0-9][a-z0-9._-]{1,63}$` |
116
+ | `isValidPluginEntry(entry)` / `PLUGIN_ENTRY_EXTENSIONS` | 入口路径安全(`./` 开头、无 `..`、仅 `.mjs/.js/.cjs`) |
117
+ | `PLUGIN_ENTRY_NAMES` | 入口导出白名单 `default` / `Plugin` / `plugin` |
118
+ | `PLUGIN_CAPABILITIES` / `PLUGIN_DEFINITION_KEYS` | 8 类能力枚举与 `PluginDefinition` 顶层字段闭集 |
119
+ | `PLUGIN_HOOK_FAILURE_POLICIES` | hook 失败策略 `fail-open` / `fail-closed` |
120
+
121
+ ```typescript
122
+ import { HookEvent, validatePluginManifest, validatePluginDefinition } from '@easbot/plugin';
123
+
124
+ const manifest = validatePluginManifest({
125
+ name: 'memory',
126
+ entry: './index.mjs',
127
+ capabilities: ['hooks', 'tools'],
71
128
  });
129
+ if (!manifest.ok) throw new Error(manifest.errors.join('; '));
130
+
131
+ const definition = validatePluginDefinition(
132
+ {
133
+ hooks: [
134
+ {
135
+ event: HookEvent.SessionStart,
136
+ hooks: [{ type: 'function', handler: async (input) => ({ modified: false, input }) }],
137
+ },
138
+ ],
139
+ tools: { memory: { description: 'Memory tool', args: {}, execute: async () => 'ok' } },
140
+ },
141
+ { capabilities: manifest.manifest.capabilities },
142
+ );
72
143
  ```
73
144
 
145
+ > `PluginDefinition` 是闭集:MUST 至少声明一个能力字段;`marketplace`、点分内联 hook 键与任何未知顶层字段一律被拒绝。
146
+
74
147
  ## API
75
148
 
76
- ### HookRegistry
149
+ ### Hook 契约
150
+
151
+ | 符号 | 说明 |
152
+ | --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
153
+ | `HookEvent` | 事件常量(`domain.action.phase` 三段式,如 `HookEvent.SessionStart`) |
154
+ | `HOOK_EVENTS` | 事件名**数组**(`Object.values(HookEvent)`,不是枚举对象) |
155
+ | `HookMatcher` | `{ event, matcher?, hooks, priority?, timeoutMs?, failurePolicy? }`;`event` MUST 命中 `HOOK_EVENTS` |
156
+ | `HookDefinition` | 5 类执行器联合:`command` / `prompt` / `http` / `agent` / `function` |
157
+ | `HookOutputWrapper` | `{ modified, input, output? }`;`output.denied: true` 表达 `fail-closed` 拒绝;禁止用 throw 表达业务拒绝 |
158
+ | `validateHookInput` / `safeValidateHookInput` / `getEventInputSchema` | 事件输入 Schema 校验 |
77
159
 
78
- | 方法 | 说明 |
79
- | ---------------------------- | -------------------- |
80
- | `register(event, handler)` | 注册 Hook 处理器 |
81
- | `unregister(event, handler)` | 移除 Hook 处理器 |
82
- | `clear(event)` | 清除事件的所有处理器 |
160
+ ### Command 类型
83
161
 
84
- ### CommandRegistry
162
+ 见上文「命令系统」,唯一真源为 `@easbot/types/native/command.ts`。
85
163
 
86
- | 方法 | 说明 |
87
- | --------------------- | -------- |
88
- | `register(command)` | 注册命令 |
89
- | `get(name)` | 获取命令 |
90
- | `execute(name, args)` | 执行命令 |
164
+ | 类型 | 说明 |
165
+ | ------------------------- | ------------------------------------------------ |
166
+ | `CommandDefinition` | 运行期命令定义(`execute` 必填) |
167
+ | `CommandInfo` | 命令注册表条目 / HTTP 响应契约(`execute` 可选) |
168
+ | `CommandConfigInfo` | 配置态命令模板(`config.command` 的值) |
169
+ | `CommandMetadata` | Markdown frontmatter 声明形态 |
170
+ | `CommandArguments` | 命令参数(字符串 / 对象) |
171
+ | `CommandExecutionContext` | 命令执行上下文(sessionId / directory / …) |
172
+ | `CommandExecuteResult` | 命令执行结果 |
91
173
 
92
- ### createTool
174
+ ### createTool / tool
93
175
 
94
- | 属性 | 类型 | 说明 |
95
- | ----------- | --------- | -------- |
96
- | name | string | 工具名称 |
97
- | description | string | 工具描述 |
98
- | parameters | ZodSchema | 参数模式 |
99
- | execute | function | 工具实现 |
176
+ | 属性 | 类型 | 必填 | 说明 |
177
+ | ------------- | ------------------------------------ | ------- | ------------------------ |
178
+ | `description` | `string` | ✅ | 工具描述 |
179
+ | `args` | `Record<string, z.ZodTypeAny>` | ✅ | 参数 schema map |
180
+ | `execute` | `(args, context) => Promise<string>` | ✅ 必填 | 工具实现;validator 强制 |
181
+
182
+ ### Marketplace(不属于本包契约)
183
+
184
+ `marketplace` 是**安装源 catalog**,不是插件运行时能力:`PluginDefinition` 不声明该字段,本包也不再导出 `MarketplaceEntry` / `MarketplaceDefinition` / `registerMarketplace()` 等注册中心 API。相关类型位于 `@easbot/agent/src/cli/plugin/type.ts`,元数据载体为 `.easbot-plugin/marketplace.json`。
185
+
186
+ ## 落地样板
187
+
188
+ - `packages/memory/src/plugin/` —— 首个按本契约实现的插件(3 个 hook + 1 个 tool)
189
+ - `packages/memory/plugin/` —— 可被 `easbot plugins install` 安装的分发目录
100
190
 
101
191
  ## 开发
102
192
 
103
193
  ```bash
104
- # 安装依赖
105
194
  pnpm install
106
-
107
- # 构建
108
195
  pnpm build
109
-
110
- # 测试
111
- pnpm test
112
-
113
- # 类型检查
196
+ pnpm test:run # vitest run(覆盖 manifest / definition / auth / hook 闭集契约)
114
197
  pnpm type-check
115
198
  ```
116
199