chenxin
42513d13c6
- 产品层：产品宪章与永久禁域、产品定义、完整 1.0 范围与发布门、道家文化语言体系、指标与反指标 - 研究层：参考项目研究（deepseek-harness、pi、MemOS、模型网关）、灵台原生引擎研究（业界原生引擎架构理念与道家文化出处） - 架构层：系统、Agent 运行时（周天体系）、插件系统、灵台引擎（C++ 双形态）、媒体与设备、社区协作市场、前端富内容渲染、数据、记忆与知识 - 契约层：协议与稳定标识、API 总体约定、Native API、兼容网关、实时与 Webhook、内部端口、统一 ContentBlock 与流式（含分支对话交互态）、灵台 C ABI 与 gRPC Service、API 表面、HTTP 与事件、运行观测 - 决策：ADR-001 至 ADR-023（模块化单体、每 attempt 持久化、候选记忆、OAuth 2.1、灵台引擎、双形态部署、大周天演化、宪章、三界作用域、私箧与保全态、叩心、周天统一等） - 交付：WP-01 至 WP-15 实施 TODO 与设计阶段交接文档 - 工程：AGENTS.md 工程规则（含 C++/灵台规范）、CLAUDE.md 引用、.gitignore
154 lines
5.3 KiB
Markdown
154 lines
5.3 KiB
Markdown
# 插件系统与生态
|
||
|
||
## 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。
|