0 Fork 0

Files

T

chenxin 42513d13c6 📝 docs: 建立魂镜完整 1.0 设计文档体系

- 产品层：产品宪章与永久禁域、产品定义、完整 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

2026-09-09 21:07:14 +08:00

5.3 KiB

Raw Permalink Blame History

插件系统与生态

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

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. 生命周期

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. 注册、审核与安装

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。

5.3 KiB Raw Permalink Blame History Unescape Escape