# 插件系统与生态

## 1. 设计判断

采用“所有可扩展能力皆插件”，拒绝“所有系统职责皆插件”。插件新增能力；Core 决定能力是否可信、可见、获准执行、可交易和可审计。

## 2. 插件类型

| 类型 | 贡献 |
| --- | --- |
| `model_adapter` | 上游协议、模型目录、能力和 usage 解析 |
| `tool` | Tool Definition 与执行器 |
| `mcp_connector` | MCP Server、工具与资源连接 |
| `skill` | 按需加载的任务说明和资源 |
| `context_provider` | Context Manifest 内容 |
| `memory_policy` | 候选提取、评分、衰减和召回 |
| `importer_exporter` | 角色卡、资料和开放格式 |
| `media_processor` | ASR/TTS、图像、Live2D、3D 处理 |
| `run_hook` | 类型化运行事件观察或受限变换 |
| `ui_extension` | Web/Tauri 声明式页面、面板和渲染器 |
| `remote_plugin` | 独立服务通过稳定协议贡献能力 |

## 3. 非插件化内核

- Authentication、数据域、Workspace 和资源归属；
- Policy 最终裁决、用户审批和设备授权；
- Audit、交易 Ledger、支付与结算状态；
- 数据库事务、删除与许可语义；
- 插件签名、审核、安装策略、权限收窄和撤架；
- Sandbox fail-closed；
- 诊断授权。

插件可以提出信号，不能覆盖内核结论。

## 4. 双轨执行模型

### 4.1 默认受限插件

声明式或远程插件：

- 通过 JSON Schema、MCP 或 Hunjing Plugin RPC 声明能力；
- 不进入主进程，不获得文件系统或任意网络；
- UI 使用声明式组件/iframe 隔离和明确消息协议；
- 每项网络、数据、工具和媒体权限显式声明并可撤销。

### 4.2 可信本地代码插件

部署者明确安装并确认风险后，代码插件在独立进程或容器运行：

- 最小文件挂载、网络 allowlist、CPU/内存/时间限制；
- 独立身份和短期执行凭证；
- 无 Sandbox 后端时拒绝，不退化到主进程；
- 进程崩溃不拖垮 Core；
- 只有 bundled Core plugin 可以进主进程。

语言 VM、Python import 和 Node `vm` 都不是安全隔离。

## 5. Manifest

```yaml
id: example.web-fetch
version: 1.2.0
api_version: v1
runtime: remote
entrypoint: https://plugin.example.com/mcp
publisher: publisher_01...
contributes:
  - tool
permissions:
  network:
    - example.com
  data:
    - public_web
config_schema: schemas/config.json
privacy_policy_url: https://example.com/privacy
license: Apache-2.0
```

插件版本至少声明：ID、不可变版本、API 版本、runtime、entrypoint、贡献、依赖、权限、配置 Schema、发布者、许可、隐私说明、包摘要和签名。

## 6. 生命周期

```mermaid
stateDiagram-v2
  [*] --> discovered
  discovered --> validated
  validated --> installed
  installed --> active
  active --> draining
  draining --> stopped
  stopped --> active
  discovered --> rejected
  validated --> rejected
  active --> suspended
  suspended --> stopped
  stopped --> uninstalled
  uninstalled --> [*]
```

初始化采用事务式注册：声明 contribution 和 reversible effect，全部成功后提交；失败则逆序撤销。

## 7. Run 固定快照

Run 开始生成 `plugin_snapshot`：插件 ID/版本/摘要、配置摘要、工具与 Hook、权限、依赖和执行位置。Run 期间升级、停用、撤架不改变快照；高危安全撤架可以立即阻断后续 ToolCall，但保留审计和明确失败原因。

## 8. Hook 语义

- `observe`：只读，错误记录但不改变主流程；
- `transform`：明确阶段返回新值，串行执行；
- `guard`：返回风险信号，Core Policy 最终裁决；
- `effect`：登记可撤销资源。

Hook 必须有超时和错误策略。插件禁止跨模块写表、读取其他插件私有状态或修改角色/交易权威数据。

## 9. SDK 与开发者体验

1.0 提供：

- TypeScript 与 Python SDK；
- Manifest/Schema 生成与校验；
- 本地模拟 Host；
- 测试凭据、固定事件和权限模拟；
- 插件打包、签名、发布、兼容性和迁移工具；
- UI 扩展组件目录；
- usage、日志、错误和性能诊断；
- 示例插件和安全清单。

## 10. 注册、审核与安装

```mermaid
flowchart LR
  DEV[Developer] --> PACK[Package and Sign]
  PACK --> SCAN[Static and Dynamic Scan]
  SCAN --> REVIEW[Policy Review]
  REVIEW --> REG[Immutable Registry Version]
  REG --> INSTALL[User or Admin Install]
  INSTALL --> GRANT[Permission Review]
  GRANT --> ACTIVE[Activated Version]
```

- 自动扫描不替代人工高风险审核；
- 安装展示数据、网络、设备、费用、外部目的地与现实后果和本地代码权限；
- 升级新增权限时重新确认；
- 允许固定版本、自动安全补丁、回滚和卸载；
- 举报、漏洞、撤架、恶意发布者和依赖供应链有处置流程。

## 11. 插件市场

插件可以免费或付费发布，商品绑定不可变 Registry Version 和许可证。购买只授予下载/使用许可，不自动启用插件或批准权限。付费更新、订阅、退款和创作者结算复用 Marketplace 与 Ledger，不由插件自行处理支付。

## 12. 子 Agent

子 Agent 使用相同插件契约，但深度、并发、工具、数据、网络、预算和运行时间由 Runtime 硬限制；不继承额外审批令牌，默认不能写长期记忆，结果通过结构化 ChildRun 返回父 Run。