615 lines
33 KiB
Markdown
615 lines
33 KiB
Markdown
# 参考项目调研与全量首版插件架构
|
||
|
||
> 状态：提案
|
||
> 日期：2026-09-01
|
||
> 范围：完整 1.0 的 LLM、Agent、MCP、RAG、记忆、多模态、模型网关、隔离执行、数据与部署
|
||
> 设计方式：绿地重写；保留现有天目和元炁，其他源码、服务和命名均可替换。
|
||
|
||
## 1. 结论
|
||
|
||
可以采用 DeepSeek Harness 的“一切皆插件”思想，但不能原样采用“没有特权内核”的边界。魂镜应使用：
|
||
|
||
> **不可替换的宪章内核 + 一切能力皆插件。**
|
||
|
||
Harness 面向无持续身份的 Coding Agent，Session、Agent loop、持久化和 Sandbox 都可以换实现。魂镜还必须保护人物连续性、用户数据权、唯一命台、归真、同意、删除和禁域。如果普通插件能够替换这些规则，一个错误插件就可能制造双命台、让已删除记忆复活或绕过用户撤权。
|
||
|
||
因此：
|
||
|
||
- **不能插件化**：人物身份与谱系、唯一命台、镜树归真、缘契同意、三界效力、记忆权利、司命禁域、区域/ACL、事务事件与审计；
|
||
- **全部插件化**：模型、Prompt/上下文、Agent 策略、MCP、工具、记忆抽取、RAG、向量/图检索、多模态、形仪渲染、通知、计费、评测、可观测性和 UI 扩展；
|
||
- **首版即完整 1.0**：所有能力类型、默认插件、治理界面、部署配置和失败路径都在 1.0 交付，不把它们推迟到后续阶段；
|
||
- **保留现有实现**：天目（`tianmu`）与元炁（`yuanqi`）源码和 API 保留，由新插件 Host 适配；二者不直接暴露给浏览器或公网。
|
||
|
||
“全部首版交付”不表示把多个互斥存储同时当事实源。所有后端插件都在 1.0 提供并通过契约测试；每个部署 Profile 只激活一个权威实现和必要投影。
|
||
|
||
## 2. 保留的产品与文化事实
|
||
|
||
本方案只继承文档中的稳定产品和中国文化语义：
|
||
|
||
- 魂镜（Hunjing）是个人数字生命平台；
|
||
- 镜生、缘契、三界、形仪、灵台、天宰是六个产品领域；
|
||
- 人物、灵胚、道体、魂籍、命台、执镜者、镜域定义身份与治理；
|
||
- 镜树、问节、候答、主脉、推演枝、采用、归真定义对话效力；
|
||
- 微痕、明忆、重忆、实录、心痕、正影定义记忆与纠正；
|
||
- 司命、百工、授契、行契、请命、禁域定义能力治理；
|
||
- 天工阁承载功能 Agent，功能 Agent 不是人物；
|
||
- 真界、境界、幻境保持“言可入幻，行必归真”；
|
||
- 用户拥有知情、纠正、删除、导出、撤权、暂停和退出权。
|
||
|
||
权威来源是[产品宪章](../product/constitution.md)、[主 PRD](../product/master-prd.md)、[文化命名](../domain/cultural-naming.md)、[领域词典](../domain/glossary.md)、[身份连续性](../domain/identity-continuity.md)、[镜树模型](../domain/mirror-tree-model.md)、[记忆模型](../domain/memory-model.md)与[授权及能力模型](../domain/mandate-and-capability-model.md)。
|
||
|
||
文化名是领域共同语言，不是一张部署清单。除明确要求保留的天目、元炁外，工程进程使用直白英文名。
|
||
|
||
## 3. DeepSeek Harness 调研结论
|
||
|
||
调研基线是 [deepseek-harness `dd6322d`](https://github.com/deepseek-ai/deepseek-harness/tree/dd6322d604e00eec1ba5e0c8541159906a21094a)。
|
||
|
||
### 3.1 “一切皆插件”实际仍有元运行时
|
||
|
||
Harness 的[架构文档](https://github.com/deepseek-ai/deepseek-harness/blob/dd6322d604e00eec1ba5e0c8541159906a21094a/docs/architecture.zh.md#L9-L39)说明 Cordis 插件向共享 Context 贡献 Service、类型化 Event 和可逆 Effect；Profile 与 Bundle 通过有序 patch 组合插件树。它没有业务特权包，但仍依赖不可绕开的元语义：
|
||
|
||
- Loader 解析和装载插件树；
|
||
- Context 保存服务注册与作用域；
|
||
- Fiber 拥有生命周期和可逆副作用；
|
||
- Event 定义 waterfall、serial、parallel、emit 等分派语义；
|
||
- Service Definition、Provider、Consumer 组成可替换 seam；
|
||
- Profile、Bundle、Patch 决定组合与覆盖顺序。
|
||
|
||
因此“一切皆插件”不是“没有内核”，而是**内核缩小为插件元运行时**。
|
||
|
||
### 3.2 值得直接吸收的模式
|
||
|
||
| Harness 机制 | 源码/文档证据 | 魂镜采用方式 |
|
||
| --- | --- | --- |
|
||
| 仅追加 Session 事件 | [`SessionEventMap`](https://github.com/deepseek-ai/deepseek-harness/blob/dd6322d604e00eec1ba5e0c8541159906a21094a/packages/core/session/src/types.ts#L211-L281) 保存 turn、step、assistant chunk/message、tool call/result；模型历史由日志投影 | 采用持久 Run 日志与派生上下文，但正式人物状态仍由领域事务持有 |
|
||
| 持久化是插件 | [`core/session`](https://github.com/deepseek-ai/deepseek-harness/blob/dd6322d604e00eec1ba5e0c8541159906a21094a/packages/core/session/src/index.ts#L1-L18) 明确 Session 是内存日志，持久化监听 `session/event` 并在 `session/flush` 排空 | 采用存储 Provider seam；魂镜要求提交事务与 Outbox 一致，不能只异步缓冲 |
|
||
| Agent loop 可替换 | [`ReactLoopAgent`](https://github.com/deepseek-ai/deepseek-harness/blob/dd6322d604e00eec1ba5e0c8541159906a21094a/packages/core/agent-loop/src/agent.ts#L69-L105) 从 Session 派生请求，管理 inbox、turn、step 和取消 | ReAct、Plan-and-Execute、Outcome loop 都作为策略插件 |
|
||
| 工具执行流水线 | 架构文档定义 `tools/pre-execute → execute → post-execute → tool/result` | 司命不可绕过地包围所有工具插件；插件只能继续收紧权限 |
|
||
| Service seam | 架构文档将 Definition、Provider、Consumer 作为完整替换单元 | 模型、检索、对象存储、通知、计费等使用服务接口和单 Provider 选择 |
|
||
| 作用域组合 | Agent scope 隔离工具、Prompt 和事件；子 Agent 使用 persona、toolFilter | 人物、Run、子 Agent 分级作用域；子作用域只能减少能力 |
|
||
| 子 Agent 权限单调收窄 | [`child-agent.ts`](https://github.com/deepseek-ai/deepseek-harness/blob/dd6322d604e00eec1ba5e0c8541159906a21094a/packages/subagent/subagent/src/child-agent.ts#L39-L118) 固化 depth 和模型；[L166-L267](https://github.com/deepseek-ai/deepseek-harness/blob/dd6322d604e00eec1ba5e0c8541159906a21094a/packages/subagent/subagent/src/child-agent.ts#L166-L267) 固化工具过滤、Sandbox 和 `approvalPolicy: never` | 首版委派深度有限，权限/数据/预算取父级交集，子 Agent 不能现场请命扩权 |
|
||
| Sandbox fail-closed | [`SandboxProvider`](https://github.com/deepseek-ai/deepseek-harness/blob/dd6322d604e00eec1ba5e0c8541159906a21094a/packages/sandbox/sandbox/src/index.ts#L118-L175) 无可用隔离后端时拒绝执行 | 隔离插件没有实现承诺的边界时必须拒绝，不允许静默裸跑 |
|
||
| Profile/Bundle/Patch | [架构文档](https://github.com/deepseek-ai/deepseek-harness/blob/dd6322d604e00eec1ba5e0c8541159906a21094a/docs/architecture.zh.md#L15-L39) | 本地、标准服务器、区域云由版本化 Profile 选择同一插件目录 |
|
||
| 可逆生命周期 | 插件注册是 Fiber effect，卸载自动撤销注册 | 插件启动必须返回 disposer；新 Run pin 版本，旧 Run 保持原组合到结束 |
|
||
|
||
### 3.3 不能照搬的部分
|
||
|
||
Harness 仍处于开发者预览并声明会有破坏性变化。其动态 Cordis Host 使用 `node:vm`，包文档明确指出**不是安全边界**；异步函数还能逃出同步求值时限。魂镜官方云不能允许模型生成任意 Host 插件后直接进入可信进程。
|
||
|
||
魂镜不采用：
|
||
|
||
- 运行中由模型定义并激活任意 Host 代码；
|
||
- 普通插件替换身份、授权、事件真实性或删除语义；
|
||
- 插件直接获得共享数据库对象和全局 Context；
|
||
- 配置 patch 静默替换安全策略；
|
||
- 动态 UI 插件未经签名和用户批准执行；
|
||
- 插件卸载导致历史事件无法解释。
|
||
|
||
## 4. 不可替换的宪章内核
|
||
|
||
```mermaid
|
||
flowchart TB
|
||
subgraph Kernel["宪章内核：不可替换"]
|
||
Auth["认证、镜域 ACL、区域"]
|
||
Identity["人物、道体、魂籍、命台"]
|
||
Canon["镜树、版本、采用、归真"]
|
||
Consent["缘契、同意、三界效力"]
|
||
Rights["记忆权利、正影、删除"]
|
||
Run["Durable Run、job、fencing"]
|
||
Policy["司命、禁域、执行票据"]
|
||
Ledger["事务、Outbox、审计、幂等"]
|
||
Plugins["插件清单、签名、依赖与生命周期"]
|
||
end
|
||
|
||
Plugins --> Capability["能力插件"]
|
||
Run --> Strategy["Agent 策略插件"]
|
||
Policy --> Tool["工具/MCP 插件"]
|
||
Rights --> Memory["记忆/RAG 插件"]
|
||
Ledger --> Projection["投影与通知插件"]
|
||
```
|
||
|
||
内核只保留决定“谁可以改变什么、改变是否有效、如何证明”的规则：
|
||
|
||
1. 认证、镜域/人物 ACL 与固定区域；
|
||
2. 人物身份、谱系、道体、魂籍；
|
||
3. 唯一命台 lease、heartbeat、epoch 和 fencing；
|
||
4. 镜树版本、采用、归真和正式效力；
|
||
5. 缘契、持续同意、三界与现实行动边界；
|
||
6. 三级记忆的确认、正影、删除与停止召回权；
|
||
7. Durable Run、任务 claim、取消、恢复和前台唯一意识；
|
||
8. 司命、授契、行契、请命、禁域和执行票据；
|
||
9. 状态事务、Outbox、审计、幂等与事件重放；
|
||
10. 插件 manifest 校验、签名信任、权限上界、版本 pin 和迁移锁。
|
||
|
||
内核实现可以重写，但运行时不能被普通插件替换或关闭。扩展只能通过窄接口请求内核操作。
|
||
|
||
## 5. 全量首版总体架构
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
Web["hunjing-web"]
|
||
BFF["hunjing-edge<br/>Web BFF 与流代理"]
|
||
|
||
subgraph Host["hunjing-host：Python"]
|
||
Kernel["宪章内核"]
|
||
Runtime["插件 Host 与 Run Runtime"]
|
||
Catalog["Plugin Catalog / Profiles"]
|
||
end
|
||
|
||
Gateway["hunjing-model-gateway<br/>Go"]
|
||
Sandbox["hunjing-sandbox<br/>Rust"]
|
||
Tianmu["天目 tianmu<br/>保留现有 OCR"]
|
||
Yuanqi["元炁 yuanqi<br/>保留现有本地推理"]
|
||
|
||
PG[("PostgreSQL + pgvector")]
|
||
Redis[("Redis")]
|
||
Vector[("Milvus / SeekDB 投影")]
|
||
Graph[("Neo4j / NebulaGraph 投影")]
|
||
Object[("S3 / MinIO")]
|
||
|
||
Provider["外部模型 Provider"]
|
||
MCP["MCP Servers"]
|
||
Device["本地工具与设备"]
|
||
|
||
Web --> BFF
|
||
BFF --> Host
|
||
Kernel --> Runtime
|
||
Catalog --> Runtime
|
||
Host --> Gateway
|
||
Host --> Sandbox
|
||
Host --> Tianmu
|
||
Host --> PG
|
||
Host --> Redis
|
||
Host --> Vector
|
||
Host --> Graph
|
||
Host --> Object
|
||
Gateway --> Provider
|
||
Gateway --> Yuanqi
|
||
Runtime --> MCP
|
||
Sandbox --> Device
|
||
```
|
||
|
||
### 5.1 进程职责
|
||
|
||
| 进程 | 职责 | 禁止 |
|
||
| --- | --- | --- |
|
||
| `hunjing-host` | 宪章内核、领域事务、插件 Host、Run、MCP Host、RAG 编排、记忆治理 | Provider 方言、不可信代码、前端状态 |
|
||
| `hunjing-edge` | Web 聚合、Cookie/JWT 透传、CSRF/CORS、SSE/WebSocket 代理、响应裁剪 | 领域规则、人物状态、司命裁决 |
|
||
| `hunjing-model-gateway` | Provider/Endpoint、协议转换、流、路由、熔断、BYOK、usage、成本 | 人物身份、记忆、关系、业务授权 |
|
||
| `hunjing-sandbox` | 不可信工具、stdio MCP、文件/进程/网络限制、设备安全 | 决定目标、扩大权限、保存人物副本 |
|
||
| `tianmu` | OCR、复杂文档解析 | 访问人物库、决定记忆或事实 |
|
||
| `yuanqi` | 本地 chat、embedding、rerank、ASR | 访问人物库、决定路由与业务授权 |
|
||
| `hunjing-web` | 用户体验、镜树、治理、形仪、运行轨迹 | 密钥、权威状态、直连工具/Provider |
|
||
|
||
这次用户明确要求全部设置，因此模型网关、BFF、Sandbox、Redis、向量与图投影均进入完整 1.0；它们仍遵守“一个事实源、多个投影”的原则。
|
||
|
||
## 6. 插件模型
|
||
|
||
### 6.1 四个信任等级
|
||
|
||
| 等级 | 运行方式 | 允许内容 | 示例 |
|
||
| --- | --- | --- | --- |
|
||
| Kernel | Host 内不可卸载 | 产品不变量和插件元运行时 | 身份、命台、归真、司命、审计 |
|
||
| First-party | Host 内受信插件，随版本签名发布 | 高性能策略、投影和适配 | 记忆抽取、上下文、Agent 策略 |
|
||
| Service | 独立进程，通过版本化 HTTP/MCP | 模型和重型推理 | 天目、元炁、模型网关、向量/图存储 |
|
||
| Untrusted | Sandbox、WASM 或受限 MCP | 用户与第三方扩展 | shell、浏览器、文件、设备工具 |
|
||
|
||
官方云不加载用户提供的 Python 包到 Host 进程。第三方插件必须走 Service 或 Untrusted 等级。
|
||
|
||
### 6.2 Plugin Manifest
|
||
|
||
Harness 当前没有覆盖权限、隔离、数据和迁移的通用 manifest；其静态组合主要依赖 npm `package.json`、Profile/Bundle patch 与代码内 Service 契约。下述 manifest 是魂镜为多租户数字人物安全新增的设计，不是对 Harness 格式的复制。
|
||
|
||
每个插件必须提供版本化 manifest：
|
||
|
||
```yaml
|
||
id: org.hunjing.memory.extractor.default
|
||
version: 1.0.0
|
||
api_version: 1
|
||
kind: memory_extractor
|
||
runtime: in_process
|
||
entrypoint: hunjing_plugins.memory:plugin
|
||
capabilities:
|
||
provides: [memory.extract]
|
||
requires: [model.structured_output, event.read]
|
||
permissions:
|
||
data_read: [mirror_tree.canonized]
|
||
data_write: [memory_candidate]
|
||
network: []
|
||
tools: []
|
||
events:
|
||
consumes: [mirror_tree.canonized]
|
||
produces: [memory.candidate.proposed]
|
||
config_schema: schemas/config.json
|
||
state_schema: schemas/state.json
|
||
migrations: migrations/
|
||
isolation: trusted_first_party
|
||
resources:
|
||
timeout_ms: 30000
|
||
memory_mb: 256
|
||
compatibility:
|
||
host: '>=1 <2'
|
||
signature: '<release signature>'
|
||
```
|
||
|
||
稳定字段取值最终进入契约词典。Manifest 至少声明：身份、版本、Host API、种类、运行方式、入口、提供/依赖能力、数据读写、网络、工具、事件、配置/状态 Schema、迁移、隔离、资源限制、兼容范围和签名。
|
||
|
||
### 6.3 生命周期
|
||
|
||
```mermaid
|
||
stateDiagram-v2
|
||
[*] --> Discovered
|
||
Discovered --> Rejected : manifest/signature invalid
|
||
Discovered --> Installed : package verified
|
||
Installed --> Resolved : dependencies satisfied
|
||
Resolved --> Staged : config and migrations validated
|
||
Staged --> Active : activate
|
||
Active --> Draining : update/disable
|
||
Draining --> Inactive : no pinned Run
|
||
Inactive --> Staged : activate another version
|
||
Inactive --> Removed : uninstall
|
||
Rejected --> [*]
|
||
Removed --> [*]
|
||
```
|
||
|
||
规则：
|
||
|
||
- 安装不等于启用；
|
||
- 激活前完成依赖、配置、权限差异和迁移 dry-run；
|
||
- 每个 Run pin 插件集合与版本，运行中不静默换实现；
|
||
- 更新先启动新版本供新 Run 使用，旧版本 drain 到没有引用；
|
||
- 卸载后历史事件仍由版本化 Schema 和只读 renderer 解释；
|
||
- 启动失败撤销全部注册，不留下半激活能力；
|
||
- 插件不能自行扩大 manifest 权限。
|
||
|
||
### 6.4 Service Seam
|
||
|
||
每项可替换能力由三部分组成：
|
||
|
||
1. **Definition**：Host 定义的稳定接口和数据契约；
|
||
2. **Provider**：一个插件实现；
|
||
3. **Consumer**：只能依赖 Definition，不导入 Provider。
|
||
|
||
每个作用域同一能力默认只有一个权威 Provider。需要 fan-out 的事件和投影显式声明多消费者，不借偶然注册顺序决定结果。
|
||
|
||
### 6.5 两类事件
|
||
|
||
- **Durable Event**：领域事实、Run、工具、确认、记忆和插件迁移；写数据库并可重放；
|
||
- **Runtime Hook**：请求前后、检索候选、渲染、遥测等瞬时扩展点；失败按声明的 fail-open/fail-closed 处理。
|
||
|
||
插件新增模型可见内容时，必须先产生持久来源事件或 Context Snapshot；不能只在内存 hook 中偷偷改 Prompt。
|
||
|
||
## 7. 完整 1.0 插件目录
|
||
|
||
所有种类和默认实现都进入首版。
|
||
|
||
| 插件种类 | 1.0 默认插件 | 说明 |
|
||
| --- | --- | --- |
|
||
| `model_adapter` | OpenAI-compatible、Anthropic、Gemini、DeepSeek、元炁 | 在模型网关内注册协议与能力 |
|
||
| `endpoint_router` | priority failover、weighted、sticky、privacy route | 首事件前切换，首事件后固定 |
|
||
| `ocr_provider` | 天目 PP-OCRv6、天目 PaddleOCR-VL | 保留现有服务 |
|
||
| `local_inference` | 元炁 chat、embedding、rerank、ASR | 保留现有服务 |
|
||
| `prompt_source` | 道体、人物、缘契、三界、世谱、眉批、本相、时间、工具 | 显式 slot、order、priority、budget |
|
||
| `context_transform` | token budget、分支投影、结构感知压缩、引用展开 | 原文可追溯，压缩不入长期记忆 |
|
||
| `memory_recorder` | L0 原始经历 | 保存已归真来源 |
|
||
| `memory_extractor` | L1 原子记忆、实录、心痕、程序经验 | 只产生候选 |
|
||
| `memory_consolidator` | L2 场景、L3 画像 | 首版完整提供，仍是可审查派生版本 |
|
||
| `retriever` | PostgreSQL FTS、pgvector、Milvus/SeekDB | 部署 Profile 选择一个向量 Provider |
|
||
| `reranker` | 元炁、本地 CrossEncoder、远程 rerank | 只重排已授权候选 |
|
||
| `graph_store` | PostgreSQL edge、Neo4j、NebulaGraph | 图库是河图投影，不是事实源 |
|
||
| `knowledge_ingestor` | 文档、网页、角色卡、Lorebook、Wiki、代码 | 保留来源、许可和删除链 |
|
||
| `mcp_transport` | stdio、Streamable HTTP、OAuth | MCP Host 不拥有授权 |
|
||
| `capability` | 文件、网页、HTTP、数据库、代码、设备、搜索 | 全部经百工与司命 |
|
||
| `sandbox_backend` | process、container、remote worker | 无可用边界时 fail-closed |
|
||
| `agent_strategy` | ReAct、Plan-and-Execute、Outcome loop | 共享 Durable Run |
|
||
| `subagent_provider` | in-process、remote、specialist team | 权限取父级交集，委派深度有限 |
|
||
| `scheduler` | event、cron、idle-window | 受预算、静默和停止条件约束 |
|
||
| `proactive_channel` | Web、push、email、桌面通知 | 叩心候选不直接发送 |
|
||
| `embodiment` | 图像、Live2D、TTS、ASR、情相、动作 | 形仪不成为人物身份源 |
|
||
| `device_adapter` | Tauri、本地设备、IoT/机器人 | 云端票据 + 本地硬急停 |
|
||
| `storage` | PostgreSQL、SQLite、本地/S3 对象 | Profile 选择权威实现 |
|
||
| `queue` | PostgreSQL、Redis worker queue | 状态仍回权威库 |
|
||
| `event_projection` | SSE、WebSocket、搜索、向量、图、通知 | 可丢并可重建 |
|
||
| `billing_meter` | 模型、媒体、任务、存储成本 | 不按感情或记忆收费 |
|
||
| `safety` | 输入、输出、Prompt Injection、隐私脱敏 | 可增加限制，不能覆盖禁域 |
|
||
| `evaluation` | RAG、记忆、Agent、连续性、安全评测 | 结果绑定插件与 Prompt 版本 |
|
||
| `observability` | OpenTelemetry、审计导出、脱敏支持包 | 默认不采集原 Prompt/响应 |
|
||
| `ui_extension` | 镜树节点、工具卡、插件设置、Live2D 面板 | 只消费公开 Remote Contract |
|
||
|
||
## 8. 天目与元炁保留边界
|
||
|
||
### 8.1 天目
|
||
|
||
保留现有 `tianmu` 源码、模型加载和端点：
|
||
|
||
- `POST /v1/ocr`；
|
||
- `POST /v1/ocr/vl`；
|
||
- `GET /healthz`；
|
||
- PP-OCRv6 / RapidOCR；
|
||
- PaddleOCR-VL；
|
||
- `models/ocr/` 目录与 `TIANMU_*` 配置。
|
||
|
||
新增的是 Host 侧 `tianmu_ocr` Service 插件，不修改天目领域职责。当前端点接受 URL 和本地路径，且服务没有产品级授权，因此 1.0 部署必须：
|
||
|
||
- 只在内部网络监听，不向浏览器或公网开放；
|
||
- Host 解析上传/URL，完成 SSRF、MIME、体量和权限检查后只发送受控 bytes/base64；
|
||
- 不把用户原始本地路径交给天目；
|
||
- OCR 输出作为有来源观察，不能自动成为事实或记忆；
|
||
- 健康、模型和错误映射由适配插件统一。
|
||
|
||
### 8.2 元炁
|
||
|
||
保留现有 `yuanqi` 源码、模型加载和端点：
|
||
|
||
- `POST /v1/chat/completions`；
|
||
- `POST /v1/embeddings`；
|
||
- `POST /v1/rerank`；
|
||
- `POST /v1/audio/transcriptions` 与 `/v1/asr`；
|
||
- `GET /healthz`；
|
||
- GGUF、BGE-M3、BGE Reranker、SenseVoice 和 `YUANQI_*` 配置。
|
||
|
||
模型网关内置 `yuanqi` Provider 插件；RAG 可分别选择元炁 embedding/rerank 插件。部署要求：
|
||
|
||
- 元炁只在内部网络开放；
|
||
- 由模型网关处理认证、逻辑模型、路由、流和 usage 归一化；
|
||
- ASR 原转写与正影文本分开；
|
||
- 元炁日志不得输出高敏转写全文；
|
||
- 元炁不访问人物数据库，也不决定人物身份、授权或记忆。
|
||
|
||
## 9. 人物 Run 与 Agent 插件
|
||
|
||
### 9.1 不可插件化的 Run 外壳
|
||
|
||
Kernel 持有 Run ID、人物/命台 epoch、状态、turn/step 序号、预算、deadline、取消、确认、插件版本集和事件日志。Agent 策略插件只决定下一步建议，不能自己提交正式状态。
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant K as Kernel Run
|
||
participant S as Agent Strategy Plugin
|
||
participant M as Model Plugin
|
||
participant G as 司命
|
||
participant T as Tool Plugin
|
||
participant D as Durable Log
|
||
|
||
K->>D: turn/start + pinned plugins
|
||
K->>S: context snapshot + allowed capabilities
|
||
S-->>K: next model request
|
||
K->>M: normalized request
|
||
M-->>K: assistant blocks / tool calls
|
||
K->>D: assistant + tool/call
|
||
K->>G: policy decision
|
||
G-->>K: allow / ask / deny
|
||
alt allowed
|
||
K->>T: execution ticket
|
||
T-->>K: result + evidence
|
||
K->>D: tool/result
|
||
K->>S: continue
|
||
else ask
|
||
K->>D: confirmation pending
|
||
end
|
||
K->>D: turn/end
|
||
```
|
||
|
||
### 9.2 每轮诊断记录
|
||
|
||
Kernel 在每轮结束前持久化结构化 Turn Record，不依赖插件自行上报完整性：
|
||
|
||
- 本轮输入/输出消息、Context Snapshot 和固定插件版本集；
|
||
- 每一次模型 attempt，包括实际 Provider、Endpoint、逻辑/真实模型、流式状态、请求/首 token/完成时间；
|
||
- input、output、reasoning、audio、image token；
|
||
- Prompt Cache 创建 token、读取命中 token、`cache_hit` 和 usage 来源；
|
||
- 该轮模型请求的工具列表，以及每个工具的插件、版本、参数摘要、参数哈希、确认、司命裁决、执行后端、结果摘要、结果大小、错误、耗时和证据；
|
||
- fallback/retry 链、停止原因、定点成本、错误和 trace；
|
||
- 子 Agent lineage、depth、委托包和结果交接。
|
||
|
||
Provider 未返回的 usage 字段保持 `unknown`/空值，不以估算冒充真实值；必须估算时同时保存 `usage_source=gateway_estimate`。隐藏 chain-of-thought、密钥、授权头、签名 URL 和默认高敏原文不进入诊断记录。
|
||
|
||
轮次、模型调用和工具调用字段以[契约词典 §7.5](../contracts/contract-glossary.md#75-agent-轮次与模型调用诊断)为单一事实源。
|
||
|
||
### 9.3 首版策略
|
||
|
||
- ReAct：默认对话和工具 loop；
|
||
- Plan-and-Execute：长任务的显式计划与调整；
|
||
- Outcome loop：按可验证 rubric 迭代；
|
||
- Team coordinator：多个独立工作包；
|
||
- Deterministic workflow：输入完全决定输出时不用 Agent。
|
||
|
||
策略可按新 Run 切换，运行中只允许兼容的配置变更，不允许替换持久语义。
|
||
|
||
### 9.4 子 Agent
|
||
|
||
首版支持一层和受控多层配置，但默认上限低。每个子 Agent 持久记录 parent、lineage、depth、任务、plugin set、tool filter、数据范围和预算。权限是父级与委托包的交集；子 Agent 不能通过请命扩大权限，需返回父 Agent 处理。
|
||
|
||
## 10. 模型网关插件
|
||
|
||
模型网关使用“稳定 Gateway Kernel + Provider 插件”：
|
||
|
||
- Kernel 固定鉴权、请求 ID、流提交点、重试边界、熔断状态、usage 和日志；
|
||
- Provider 插件实现请求/响应/流转换、错误解析、模型目录与能力；
|
||
- Route 插件在已获准的 endpoint 集合内排序；
|
||
- 业务隐私、人物预算和区域规则由 Host 先裁定，网关只执行约束。
|
||
|
||
首版包含 OpenAI-compatible、Anthropic、Gemini、DeepSeek、元炁和扩展 Provider SDK。首个 SSE 数据写出后不能跨模型重试。
|
||
|
||
## 11. RAG、记忆与图谱插件
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
Source["归真经历、文档、观察、工具证据"] --> Guard["Kernel ACL、界域、来源、敏感度"]
|
||
Guard --> Ingest["Ingest Plugin"]
|
||
Ingest --> Authority["PostgreSQL 权威原文/版本/墓碑"]
|
||
Authority --> FTS["FTS Projection"]
|
||
Authority --> Vector["Vector Projection Plugin"]
|
||
Authority --> Graph["Graph Projection Plugin"]
|
||
Authority --> Memory["Memory Candidate Plugins L1/L2/L3"]
|
||
|
||
Query["Run 检索意图"] --> Scope["Kernel 权限过滤"]
|
||
Scope --> Retrieve["Retriever Plugins"]
|
||
FTS --> Retrieve
|
||
Vector --> Retrieve
|
||
Graph --> Retrieve
|
||
Retrieve --> Rerank["Reranker Plugin"]
|
||
Rerank --> Budget["Context Budget Plugin"]
|
||
Budget --> Snapshot["持久 Context Snapshot"]
|
||
```
|
||
|
||
规则：
|
||
|
||
- PostgreSQL 是原文、版本、ACL 和删除墓碑的事实源；
|
||
- pgvector、Milvus/SeekDB、Neo4j/NebulaGraph 都是可重建投影；
|
||
- 部署 Profile 选择一个向量主投影和一个图投影，不能让多个后端各自解释事实；
|
||
- ACL 在召回前下推，rerank 不扩大候选；
|
||
- L1/L2/L3 插件只产生候选或派生版本；重忆和正式人格变化仍由 Kernel 确认；
|
||
- 插件卸载先停止新写，drain 投影，历史来源不删除；
|
||
- embedding、chunk 或 graph schema 升级建立新版本投影并原子切换。
|
||
|
||
## 12. MCP、工具与 Sandbox 插件
|
||
|
||
固定能力链：
|
||
|
||
> 意图 → Kernel 司命 → 百工能力解析 → 执行票据 → 插件 → 净化与证据 → Kernel 提交
|
||
|
||
MCP transport、server adapter、tool executor 和 Sandbox backend 均可插件化；司命和执行票据不可插件化。依据 [MCP 2025-11-25](https://modelcontextprotocol.io/specification/2025-11-25)，首版实现 stdio、Streamable HTTP、OAuth 2.1、PKCE、Resource Indicators、audience 校验和 scope step-up。
|
||
|
||
Untrusted 插件在 Sandbox 或独立进程执行。Python import、Node `vm` 和 Prompt 约束都不算安全边界。Sandbox 无法满足声明的隔离模式时 fail-closed。
|
||
|
||
## 13. 数据、事件与插件状态
|
||
|
||
### 13.1 数据边界
|
||
|
||
插件不能获得裸数据库连接。Kernel 提供按 manifest 限制的 Repository/Command：
|
||
|
||
- 读取自动附加镜域、人物、界域和 sensitivity 条件；
|
||
- 写入只允许声明的 candidate、projection 或 plugin-owned schema；
|
||
- 人物核心表只通过 Kernel command 修改；
|
||
- 插件状态使用独立 schema/namespace，带 plugin ID 与 version；
|
||
- secret 通过 opaque handle 使用，不返回明文。
|
||
|
||
### 13.2 事件
|
||
|
||
状态、审计和 Outbox 同事务提交。事件封套包含 event ID、schema version、aggregate/version、Run/trace/causation/correlation、region、visibility、sensitivity 和 payload。插件消费至少一次并幂等；失败进入 retry/DLQ。
|
||
|
||
插件事件 Schema 属于插件包，但正式发布后不可删除；破坏性升级提供 upcaster 或迁移。UI renderer 缺失时仍显示通用事件卡，历史不能因插件卸载不可读。
|
||
|
||
### 13.3 受保护的运行诊断面
|
||
|
||
详细诊断是独立查询面，不混入普通聊天响应和公开 SSE。普通用户界面只显示可解释摘要；详细 Turn、模型 usage、缓存命中和工具轨迹通过受保护端点读取，例如：
|
||
|
||
```text
|
||
POST /v1/diagnostic-grants
|
||
GET /v1/runs/{run_id}/diagnostics
|
||
GET /v1/runs/{run_id}/turns/{turn_id}/diagnostics
|
||
POST /v1/diagnostic-grants/{grant_id}/revoke
|
||
```
|
||
|
||
每个查询必须同时携带普通 `Authorization` 与 `Hunjing-Diagnostic-Token`，并给出 `Hunjing-Diagnostic-Purpose`。令牌短期、对象绑定、scope 受限、只存哈希且可撤销；成功和失败访问均审计。支持人员只能读取用户主动生成并绑定工单的诊断授权，管理员身份本身不构成读取私密运行内容的权限。
|
||
|
||
诊断响应 `no-store`，不经过 CDN；按照 summary/detailed/sensitive 层级脱敏。详细协议和请求头以[契约词典 §13.4](../contracts/contract-glossary.md#134-运行诊断访问协议)为准。
|
||
|
||
### 13.4 热更新矩阵
|
||
|
||
| 变更 | 允许方式 |
|
||
| --- | --- |
|
||
| UI renderer、只读投影、遥测 exporter | 可热插拔，失败隔离 |
|
||
| 通知 channel、reranker、检索权重 | 新请求使用；活动 Run pin 旧版本 |
|
||
| Prompt source、context transform、模型 adapter/route | 新 step 只能在兼容且记录新 Context Snapshot 时切换；默认新 Run 生效 |
|
||
| Agent strategy、tool schema、MCP tool list | 新 Run 生效；活动 Run 需显式暂停和重建请求面 |
|
||
| Memory extractor、chunker、embedding、graph schema | 版本化并后台重建，原子切换 |
|
||
| Storage、queue、事件 persistence | 维护窗口、双写验证和正式迁移 |
|
||
| Kernel、不变量、权限上界、删除语义 | 不支持插件替换；走产品/契约版本升级 |
|
||
| 天目、元炁服务版本 | 通过健康检查和 adapter 兼容验证滚动升级 |
|
||
|
||
## 14. 全量 1.0 部署 Profile
|
||
|
||
### 14.1 `local-full`
|
||
|
||
- Web、BFF、Host、模型网关、Sandbox；
|
||
- SQLite、本地对象目录、Redis 单机；
|
||
- 天目、元炁；
|
||
- pgvector 不可用时使用 SQLite FTS + 本地向量插件；
|
||
- 本地 Live2D、ASR/TTS、MCP、Agent Team 和评测均可用；
|
||
- 明确不宣称 HA 或在线跨区迁移。
|
||
|
||
### 14.2 `server-full`
|
||
|
||
- PostgreSQL + pgvector、Redis、MinIO；
|
||
- Host API/worker、BFF、模型网关、Sandbox、天目、元炁；
|
||
- Neo4j 图投影；Milvus 可切换为向量 Provider；
|
||
- 完整 MCP、后台 Agent、通知、计费、评测和观测。
|
||
|
||
### 14.3 `cloud-region-full`
|
||
|
||
- 区域内高可用 PostgreSQL、Redis、对象存储、Milvus/SeekDB、Neo4j/NebulaGraph；
|
||
- Host、BFF、模型网关、Sandbox worker pool、天目/元炁 GPU pool；
|
||
- KMS/HSM、OpenTelemetry、备份恢复、DLQ、额度结算；
|
||
- 全球入口只做区域判定，不持有可写人物状态。
|
||
|
||
Compose 文件保留按职责拆分；容器统一 `hunjing-` 前缀。1.0 所有 Profile 均有示例配置、健康检查、契约测试和部署文档。
|
||
|
||
## 15. 首版完整能力验收
|
||
|
||
完整 1.0 必须一次性交付：
|
||
|
||
1. 人物降生、魂籍、唯一命台、迁移、恢复、死亡与数据清除分离；
|
||
2. 镜树候答、分支、采用、归真、续思、移栽、流式残答；
|
||
3. 微痕、明忆、重忆、L0/L1/L2/L3、正影、删除、召回来源；
|
||
4. 世谱、文档、网页、知识库、全文、向量、图、rerank 和引用；
|
||
5. 外部 Provider、BYOK、元炁本地推理、天目 OCR、多模态能力；
|
||
6. MCP stdio/HTTP/OAuth、Skill、文件/网页/数据库/HTTP/代码/设备工具；
|
||
7. ReAct、Plan-and-Execute、Outcome、多 Agent、后台受托 Run 和调度；
|
||
8. 司命四维裁决、授契、行契、请命、禁域、Sandbox 与设备硬急停；
|
||
9. 图像、Live2D、语音、ASR/TTS、通感、器谱和形仪版本；
|
||
10. 叩心、静默、频率、渠道、预算和用户负反馈；
|
||
11. 账户、镜域、区域、管理员、订阅、按量、BYOK、保全态和支持包；
|
||
12. 插件安装、签名、权限差异、Profile、更新、drain、迁移、回滚和清单 UI；
|
||
13. SQLite 本地、标准服务器、区域云、备份恢复、RPO/RTO 和 SLO；
|
||
14. 安全、隐私、删除、连续性、RAG、Agent、无障碍和多语评测。
|
||
|
||
能力不可用时必须显示具体硬件、配置、地区或授权原因，不能把未配置伪装为未设计。
|
||
|
||
## 16. 命名
|
||
|
||
保留领域文化名和明确要求保留的天目、元炁：
|
||
|
||
- 天目：本地 OCR 与文档视觉解析；
|
||
- 元炁：本地 LLM、Embedding、Rerank、ASR 和多模态推理。
|
||
|
||
其他工程对象使用直白英文：`hunjing-host`、`hunjing-edge`、`hunjing-model-gateway`、`hunjing-sandbox`、`hunjing-web`。不再把灵台、神识等文化名固定等同某个进程；灵台是领域，神识是模型接入职责。
|
||
|
||
插件 ID 使用反向域名，不使用拼音；用户界面展示文化名、直白解释、Provider 和权限差异。
|
||
|
||
## 17. 架构决策摘要
|
||
|
||
| 决策 | 选择 | 不选择 |
|
||
| --- | --- | --- |
|
||
| 插件哲学 | 宪章内核 + 一切能力皆插件 | 人物不变量也可被普通插件替换 |
|
||
| 插件框架 | 吸收 Cordis seam/scope/effect/profile 思想，自建窄 Plugin API | 直接 Fork Harness 或依赖开发预览动态 Host |
|
||
| 首版范围 | 全量 1.0 一次交付 | 将模型网关、RAG、MCP、多 Agent、多模态推迟 |
|
||
| 保留实现 | 天目、元炁 | 重写两者或让其拥有业务状态 |
|
||
| Host | Python 领域内核与插件 Host | 插件直接共享数据库和全局 Context |
|
||
| 模型 | 独立 Gateway Kernel + Provider 插件 | 销售平台式网关成为领域后端 |
|
||
| Agent | Kernel Run 外壳 + 策略插件 | Agent 插件直接提交人物正式状态 |
|
||
| 数据 | PostgreSQL 事实源 + 多种可重建投影插件 | 多数据库各自解释事实 |
|
||
| 动态扩展 | 签名 First-party、Service、Sandbox/WASM | 用户代码进入 Host 进程或 Node `vm` 当安全边界 |
|
||
| 更新 | Run pin、并行版本、drain、迁移 | 活动 Run 静默换插件 |
|
||
|
||
## 18. 实现前置工作
|
||
|
||
1. 在契约词典登记 Plugin、Package、Profile、Capability、Permission、Execution Ticket、Run Plugin Set 的稳定标识；
|
||
2. 修改文化命名文档，解除灵台/神识与具体进程的一一映射，保留天目和元炁；
|
||
3. 定义 Kernel Command、Durable Event、Runtime Hook、Service Seam 与 Remote Contract；
|
||
4. 定义插件 manifest JSON Schema、签名、依赖解析、权限差异和生命周期；
|
||
5. 定义天目、元炁 adapter 契约和内部网络安全策略；
|
||
6. 定义所有 1.0 默认插件及各 Profile 的锁定版本清单；
|
||
7. 先实现人物唯一命台、Run、司命、Outbox 和插件加载的纵向骨架；
|
||
8. 每个插件留下契约测试、权限测试、失败测试、迁移测试和卸载测试；
|
||
9. 不迁移旧代码结构，只迁移经新 Schema 校验且仍有产品价值的数据。
|
||
|
||
## 19. 调研限制
|
||
|
||
- Harness 固定提交仍属于开发者预览，本文采用模式而非 API 兼容承诺；
|
||
- 动态插件运行器明确不是安全边界，官方云必须使用进程/Sandbox/WASM 隔离；
|
||
- `looplj/axonhubs` 和 `riisovo/memory-trigger` 无法按给定地址验证；
|
||
- 第三方代码采用前仍需复核许可证、安全和维护状态；
|
||
- 本文不声明当前除天目、元炁外的代码应被复用。
|