# 扩展 API

本文档列出了 `jshookmcp` SDK 中所有对外暴露的 API 及使用说明。

## SDK 模块概览

提供以下三个基础模块：

- `@jshookmcp/extension-sdk/plugin`
- `@jshookmcp/extension-sdk/workflow`
- `@jshookmcp/extension-sdk/bridges`

### API 模块统计

| 模块       | 类型声明数量 | 工厂/普通方法 | 上下文对象 (Context) | 说明                        |
| ---------- | -----------: | ------------: | -------------------: | --------------------------- |
| `plugin`   |            9 |             1 |                    6 | Plugin 实例与生命周期上下文 |
| `workflow` |           14 |             4 |                    4 | 工作流节点构造方法          |
| `bridges`  |           15 |            11 |                    0 | 系统层与网络层辅助函数      |

## Plugin SDK 接口说明

### 核心模块 `@jshookmcp/extension-sdk/plugin`

#### 核心类型

- `ToolProfileId`: 控制工具可见性的环境层级。
- `PluginLifecycleContext`: 插件运行时的上下文对象，包含所有允许调用的方法。
- `ExtensionBuilder`: 流式构建器实例。

#### 构造方法

| 初始化方法                     | 示例                                       | 作用                       |
| ------------------------------ | ------------------------------------------ | -------------------------- |
| `createExtension(id, version)` | `createExtension('example.demo', '1.0.0')` | 创建 ExtensionBuilder 实例 |

插件对外展示元数据不通过 `ExtensionBuilder` 设置，统一由同级 `meta.yaml` 提供：`name` / `description` / `author` / `source_repo`。

### PluginLifecycleContext 方法

所有的操作必须通过注入的 `ctx` 对象来进行：

| 方法                         | 示例                                                                    | 权限限制                        |
| ---------------------------- | ----------------------------------------------------------------------- | ------------------------------- |
| `registerMetric(metricName)` | `ctx.registerMetric('demo.requests')`                                   | 需提前注册对应指标              |
| `invokeTool(name, args?)`    | `await ctx.invokeTool('page_navigate', { url: 'https://example.com' })` | 受限于 `allowTool` 白名单与配置 |
| `hasPermission(capability)`  | `ctx.hasPermission('toolExecution')`                                    | 基于配置进行校验                |
| `getConfig(path, fallback)`  | `ctx.getConfig('plugins.demo.timeout', 5000)`                           | 只读配置读取                    |
| `setRuntimeData(key, value)` | `ctx.setRuntimeData('loadedAt', Date.now())`                            | 写入运行时内存数据              |
| `getRuntimeData(key)`        | `ctx.getRuntimeData<number>('loadedAt')`                                | 读取运行时内存数据              |

#### 最小调用示例

```ts
ctx.registerMetric('demo.metric');
await ctx.invokeTool('page_navigate', { url: 'https://example.com' });
```

## Workflow SDK 接口说明

### 核心模块 `@jshookmcp/extension-sdk/workflow`

#### 核心类型

- `WorkflowContract`: 工作流执行树的静态描述。
- `WorkflowExecutionContext`: 工作流运行时的上下文对象。

#### 节点构造方法

| 方法签名                                                          | 功能         |
| ----------------------------------------------------------------- | ------------ |
| `defineWorkflow(id, displayName, configure)`                      | 定义工作流契约 |
| `toolStep(id, toolName, options?)`                                | 单步工具调用 |
| `sequenceStep(id, config?)`                                       | 顺序节点串联 |
| `parallelStep(id, config?)`                                       | 并发节点调度 |
| `branchStep(id, predicateId, config?)`                            | 条件分支路由 |
| `fallbackStep(id, config?)`                                       | 失败回退分支 |

### WorkflowExecutionContext 方法

| 方法                                    | 说明                |
| --------------------------------------- | ------------------- |
| `invokeTool(toolName, args)`            | 触发内置工具调用    |
| `emitSpan(name, attrs?)`                | 记录 Trace 追踪日志 |
| `emitMetric(name, value, type, attrs?)` | 记录数据指标        |
| `getConfig(path, fallback)`             | 读取只读配置        |

#### 最小调用示例

```ts
sequenceStep('main', (s) => {
  s.tool('nav', 'page_navigate', { input: { url: 'https://example.com' } });
  s.tool('dump', 'page_local_storage', { input: { action: 'get' } });
});
```

## Bridge SDK 接口说明

### 核心模块 `@jshookmcp/extension-sdk/bridges`

提供基础操作系统调用和网络请求的安全辅助封装。

#### 辅助方法

| 方法签名                                                  | 用途                                   |
| --------------------------------------------------------- | -------------------------------------- |
| `toTextResponse / toErrorResponse`                        | 格式化为标准 MCP 响应                  |
| `parseStringArg(args, key, required?)`                    | 安全解析参数字符串                     |
| `resolveOutputDirectory(toolName, target, requestedDir?)` | 安全的路径拼接与校验                   |
| `checkExternalCommand(...)`                               | 检查系统命令是否存在                   |
| `runProcess(command, args, options?)`                     | 安全执行子进程命令，包含超时与管道控制 |
| `assertLoopbackUrl(value, label?)`                        | 校验 URL 是否为本地环回地址            |
| `requestJson(url, method?, bodyObj?, timeoutMs?)`         | 封装支持超时的 JSON 请求               |

#### 最小调用示例

```ts
const value = parseStringArg(args, 'url', true);
const checked = assertLoopbackUrl(value);
const result = await requestJson(checked);
return toTextResponse({ success: true, data: result.data });
```

## 核心运行边界限制

- `invokeTool()` **没有任何后门**。调用必须经过预先声明的白名单验证。
- `configDefaults` 仅提供默认值，用户的配置文件优先级最高。
- `loadPluginEnv()` 读取的变量仅在插件内部生效，不会污染全局环境变量。
