@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 +145 -63
- package/README.md +144 -61
- package/dist/index.cjs +1 -1
- package/dist/index.d.cts +883 -713
- package/dist/index.d.ts +883 -713
- package/dist/index.mjs +1 -1
- package/package.json +8 -8
package/README.en.md
CHANGED
|
@@ -2,17 +2,21 @@
|
|
|
2
2
|
|
|
3
3
|
# @easbot/plugin
|
|
4
4
|
|
|
5
|
-
EASBot Plugin System
|
|
5
|
+
EASBot Plugin System — type contracts, manifest validation, and extension point definitions
|
|
6
6
|
|
|
7
7
|
## Version
|
|
8
8
|
|
|
9
|
-
v0.3.
|
|
9
|
+
v0.3.36
|
|
10
10
|
## Features
|
|
11
11
|
|
|
12
|
-
- **
|
|
13
|
-
- **
|
|
14
|
-
- **
|
|
15
|
-
- **
|
|
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
|
-
###
|
|
26
|
-
|
|
27
|
-
```typescript
|
|
28
|
-
import { createHookRegistry, HOOK_EVENTS } from '@easbot/plugin';
|
|
29
|
+
### Plugin entry
|
|
29
30
|
|
|
30
|
-
|
|
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
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
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
|
-
|
|
61
|
+
export default MyPlugin;
|
|
62
|
+
export { MyPlugin as Plugin };
|
|
63
|
+
```
|
|
41
64
|
|
|
42
|
-
|
|
43
|
-
import { createCommandRegistry } from '@easbot/plugin';
|
|
65
|
+
### Command system
|
|
44
66
|
|
|
45
|
-
|
|
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
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
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
|
-
|
|
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
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
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
|
-
###
|
|
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
|
-
|
|
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
|
-
|
|
161
|
+
See "Command system" above; single source of truth is `@easbot/types/native/command.ts`.
|
|
85
162
|
|
|
86
|
-
|
|
|
87
|
-
|
|
|
88
|
-
| `
|
|
89
|
-
| `
|
|
90
|
-
| `
|
|
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
|
|
95
|
-
|
|
|
96
|
-
|
|
|
97
|
-
|
|
|
98
|
-
|
|
|
99
|
-
|
|
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 插件系统
|
|
5
|
+
EASBot 插件系统 —— 类型契约、清单校验与扩展点定义
|
|
6
6
|
|
|
7
7
|
## 版本
|
|
8
8
|
|
|
9
|
-
v0.3.
|
|
9
|
+
v0.3.36
|
|
10
10
|
## 特性
|
|
11
11
|
|
|
12
|
-
-
|
|
13
|
-
-
|
|
14
|
-
-
|
|
15
|
-
-
|
|
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
|
-
###
|
|
26
|
-
|
|
27
|
-
```typescript
|
|
28
|
-
import { createHookRegistry, HOOK_EVENTS } from '@easbot/plugin';
|
|
29
|
+
### 插件入口
|
|
29
30
|
|
|
30
|
-
|
|
31
|
-
const hooks = createHookRegistry();
|
|
31
|
+
插件入口 MUST 导出 `default` / `Plugin` / `plugin` 之一,签名为 `Plugin = (input: PluginInput) => Promise<PluginDefinition>`。
|
|
32
32
|
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
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
|
-
|
|
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
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
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
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
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
|
-
###
|
|
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
|
-
|
|
162
|
+
见上文「命令系统」,唯一真源为 `@easbot/types/native/command.ts`。
|
|
85
163
|
|
|
86
|
-
|
|
|
87
|
-
|
|
|
88
|
-
| `
|
|
89
|
-
| `
|
|
90
|
-
| `
|
|
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
|
-
|
|
|
97
|
-
|
|
|
98
|
-
|
|
|
99
|
-
|
|
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
|
|