📝 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
This commit is contained in:
chenxin committed
commit
42513d13c6
37 files changed
+5795
No files matched your search
@@ -0,0 +1,178 @@
|
||||
# Agent 运行时
|
||||
|
||||
## 1. 运行模型
|
||||
|
||||
```text
|
||||
Conversation → Run → Turn → ModelCall / ToolCall → Message
|
||||
```
|
||||
|
||||
- 一个用户输入创建或继续一个 Run。
|
||||
- 一个 Run 可包含多个 Turn。
|
||||
- 一个 Turn 可包含多个模型 attempt 和并行 ToolCall。
|
||||
- 每次重试、故障转移、`pause_turn` 续跑都创建新的 ModelCall 记录。
|
||||
- 子 Agent 是独立 Run 或 ChildRun，必须引用父 Run，并继承更窄权限。
|
||||
|
||||
## 2. 周天体系
|
||||
|
||||
运行层以周天为循环叙事，承接 Hunjing 旧版（main 分支）的小周天/大周天设计并补全其架构（决策见 [ADR-023](../decisions/README.md#adr-023周天体系统一小周天闭环与大周天演化)）：
|
||||
|
||||
- **小周天**：一次 Run 从输入到答复或行动结果的可追踪认知闭环。上节 Run/Turn/ModelCall/ToolCall 分层即小周天的可追踪链路；闭环完成时记录完成信号（含归真、记忆候选与观测摘要的引用）。
|
||||
- **大周天**：跨 Run 的角色自我评估演化循环（见 [ADR-018](../decisions/README.md#adr-018角色内驱力与大周天演化进入-10)），以 `BigCycle`（`cycle_`）为聚合根持久化，执行为一个受托后台 Run。
|
||||
|
||||
```mermaid
|
||||
flowchart TB
|
||||
IN[run input] --> CTX[context assembly]
|
||||
CTX --> MT[model and tool turns]
|
||||
MT --> OUT[streamed output]
|
||||
OUT --> SIG[run completed signal]
|
||||
SIG --> ACC[signal accumulation]
|
||||
ACC -->|threshold or window or manual| TRIG[BigCycle triggered]
|
||||
TRIG --> P1[phase recall]
|
||||
P1 --> P2[phase evaluate]
|
||||
P2 --> P3[phase propose]
|
||||
P3 --> P4[phase submit]
|
||||
P4 --> REV[existing candidate review]
|
||||
REV --> EFF[approved evolutions]
|
||||
EFF --> CTX2[future context assembly]
|
||||
```
|
||||
|
||||
### 2.1 小周天闭环
|
||||
|
||||
- 闭环链路：输入 → 上下文装配 → 模型/工具 Turn → 流式输出 → 观测记录（usage、工具轨迹、审计）→ 完成信号。
|
||||
- 完成信号是小周天对大周天的唯一输出面：包含 Run ID、归真引用、产生的候选引用、token/费用与时间窗；不包含隐藏推理。
|
||||
- 流式运转（增量、节流、事件序）由灵台引擎小周天模块（`hj_stream`）承载；触发条件与预算核算的确定性计算由洛书（`hj_plan`）承载。
|
||||
|
||||
### 2.2 大周天循环
|
||||
|
||||
`BigCycle`（`cycle_`，UUIDv7）聚合：触发条件快照、输入引用集（窗口内小周天 Run、记忆变化、时间窗）、阶段状态与阶段记忆（`_phase_memory`：每阶段输入输出摘要，供审计与幂等）、产物候选引用、预算与执行 Run 关联。状态机 `big_cycle_status`：`pending` → `running` → `completed`/`failed`（登记于[协议与稳定标识](../contracts/README.md)）。
|
||||
|
||||
触发条件为可配置阈值组合，逐角色设频率上限：累计小周天数、归真数量、记忆候选存量、距上次大周天时间窗、用户手动触发。
|
||||
|
||||
四阶段评估：
|
||||
|
||||
| 阶段 | 职责 | 产物 |
|
||||
| --- | --- | --- |
|
||||
| 回顾（recall） | 拉取窗口内小周天完成信号与归真结果 | 输入引用集与阶段记忆 |
|
||||
| 对照（evaluate） | 以内驱力维度对照当前道体基线与关系状态 | 差异与演化方向摘要 |
|
||||
| 提议（propose） | 生成记忆、人格、关系、世界认知与次生目标候选（含叩心候选） | 携带 `big_cycle` 来源的候选集 |
|
||||
| 提交（submit） | 候选进入既有审核流转，cycle 关闭 | 审核引用与演化谱系 |
|
||||
|
||||
经审核生效的演化（人格版本、关系、记忆）进入后续小周天的上下文装配（第 7 节顺序的第 2、4 层），形成"小周天运转 → 大周天评估 → 演化生效 → 影响后续小周天"的增益闭环。约束：大周天执行是受托后台 Run，不形成第二个角色身份；守一、预算受控、候选先于写入与用户可关闭原则见 ADR-018。
|
||||
|
||||
## 3. 状态机
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> queued
|
||||
queued --> running
|
||||
running --> waiting_approval
|
||||
waiting_approval --> running : approved
|
||||
waiting_approval --> cancelled : denied or expired
|
||||
running --> completed
|
||||
running --> failed
|
||||
running --> cancelled
|
||||
completed --> [*]
|
||||
failed --> [*]
|
||||
cancelled --> [*]
|
||||
```
|
||||
|
||||
## 4. 单轮时序
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant C as Client
|
||||
participant A as API
|
||||
participant R as Runtime
|
||||
participant M as Model Adapter
|
||||
participant P as Policy
|
||||
participant T as Tool Runtime
|
||||
participant O as Observability
|
||||
|
||||
C->>A: user message
|
||||
A->>R: create or continue Run
|
||||
R->>O: run.started / turn.started
|
||||
R->>M: model request
|
||||
M-->>R: text and tool_use blocks + usage
|
||||
R->>O: model.request.completed
|
||||
alt no tool call
|
||||
R-->>A: final message stream
|
||||
else tool call
|
||||
R->>P: decide capability and risk
|
||||
alt approval required
|
||||
P-->>C: approval request
|
||||
C-->>P: allow or deny
|
||||
end
|
||||
P->>T: execute allowed calls
|
||||
T-->>R: tool results
|
||||
R->>M: continue with all tool results
|
||||
M-->>R: final response + usage
|
||||
end
|
||||
R->>O: turn.completed / run.completed
|
||||
R-->>C: final event
|
||||
```
|
||||
|
||||
## 5. 模型调用规则
|
||||
|
||||
- 业务只使用逻辑模型和能力需求；Adapter 决定上游协议和模型 ID。
|
||||
- 请求前保存 `context_snapshot` 清单和不可逆摘要，不默认保存完整拼接 Prompt。
|
||||
- 流式输出以最终固化 Message 为权威；delta 是临时事件。
|
||||
- 记录上游 request ID、开始时间、首 token、结束时间、stop reason 和真实 usage。
|
||||
- `input_tokens + cache_creation_input_tokens + cache_read_input_tokens` 才是总输入规模。
|
||||
- Provider 未提供 token 时 `usage_source=unavailable`；估算值必须标记为 `gateway_estimate`。
|
||||
- Provider 原生 Prompt Cache 与平台响应缓存是两个概念，字段不得混用。
|
||||
|
||||
## 6. Tool Use 规则
|
||||
|
||||
- `tool_use.id` 与 `tool_result.tool_use_id` 必须一一对应。
|
||||
- 同一模型响应中的并行工具先全部执行，再以一个用户工具结果消息返回。
|
||||
- 工具入参先按 JSON Schema 校验，再交给 Policy。
|
||||
- 工具失败返回结构化 `is_error`，不能丢弃失败后假装没有调用。
|
||||
- 副作用工具必须有幂等键；重试前检查已有结果。
|
||||
- 工具结果先作为带来源的观察，经过大小限制、脱敏和内容安全处理后才能进入后续上下文。
|
||||
- 行动自主性分级 `autonomy_level`（登记于契约）：自省（无外部后果的内部整理，可自动执行）、循律（既有授权内执行）、请命（需确认）、禁域（拒绝）；分级由 Policy 按能力、数据、后果、情境四维判定。
|
||||
- Skill 与工具只提供受限工作方法：与角色基线、用户当前指令、关系边界或 Policy 规则冲突时必须让位，不得以"技能惯例"扩大权限。
|
||||
|
||||
## 7. 上下文装配
|
||||
|
||||
稳定顺序：
|
||||
|
||||
1. 可用工具定义；
|
||||
2. 系统与角色稳定指令；
|
||||
3. 当前路径消息；
|
||||
4. 获准记忆和知识；
|
||||
5. 动态运行上下文；
|
||||
6. 当前用户输入。
|
||||
|
||||
Prompt Cache 依赖字节级前缀一致。工具和系统稳定内容置前；时间、请求 ID、当前输入等动态内容置后。缓存命中只由 Provider usage 判定。
|
||||
|
||||
## 8. 记忆写入
|
||||
|
||||
记忆提取在 Message 完成后异步生成 MemoryCandidate；Candidate 经 Policy 与必要的人工确认后才能创建不可变 MemoryVersion。自动提取不能修改 `identity_baseline`，敏感资料、关系结论、高影响推断和第三方信息默认要求确认。完整的所有权、写入、纠正、召回和 ContextSnapshot 规则见[记忆与知识架构](memory-and-knowledge.md)。
|
||||
|
||||
## 9. 多 Agent 编排
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
C[Coordinator Run] --> P[Plan and Budget]
|
||||
P --> A1[Child Run A]
|
||||
P --> A2[Child Run B]
|
||||
P --> A3[Child Run C]
|
||||
A1 & A2 & A3 --> H[Structured Handoff]
|
||||
H --> V[Coordinator Verification]
|
||||
V --> F[Final Result]
|
||||
```
|
||||
|
||||
- Coordinator 只在任务可独立并行、需要不同专长或上下文隔离时创建 ChildRun。
|
||||
- ChildRun 使用独立上下文与事件流，共享文件/对象必须通过显式资源授权。
|
||||
- 深度、并发、总 token、费用、墙钟时间和工具调用数由 RunBudget 硬限制。
|
||||
- 子 Agent 的插件、工具、网络、设备和数据范围是父权限的交集子集。
|
||||
- Handoff 包含结论、证据 ID、产物 ID、未完成项、错误和 usage，不传隐藏推理。
|
||||
- 角色 Agent 的后台子 Run 不形成第二个角色身份，也不能独立演进关系或人格。
|
||||
- 用户可以查看、暂停、取消单个 ChildRun 或整个协调 Run。
|
||||
|
||||
## 10. 取消与恢复
|
||||
|
||||
- 取消信号传播到模型流、工具执行和子 Run。
|
||||
- 已产生的部分文本标记为 `interrupted`，不作为完成答复。
|
||||
- 服务重启从持久化状态恢复；等待审批的 Run 不因 Worker 更换丢失。
|
||||
- 无法证明工具是否执行时，状态为 `unknown_outcome`，不得自动重试有副作用操作。
|
||||
@@ -0,0 +1,134 @@
|
||||
# 社区、协作与市场架构
|
||||
|
||||
## 1. 领域边界
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
ID[Identity] --> COMMUNITY[Community]
|
||||
ID --> WORKSPACE[Collaboration]
|
||||
COMMUNITY --> CATALOG[Marketplace Catalog]
|
||||
WORKSPACE --> CATALOG
|
||||
CATALOG --> ORDER[Order]
|
||||
ORDER --> PAYMENT[Payment]
|
||||
PAYMENT --> LEDGER[Ledger and Settlement]
|
||||
COMMUNITY --> MOD[Moderation]
|
||||
CATALOG --> MOD
|
||||
PLUGIN[Plugin Registry] --> CATALOG
|
||||
CHARACTER[Character Releases] --> CATALOG
|
||||
```
|
||||
|
||||
社区互动、协作权限、商品目录、订单支付和不可变账务分开建模。点赞数、销量、推荐分数不能成为支付账或许可事实源。
|
||||
|
||||
## 2. 社区
|
||||
|
||||
### 2.1 内容与互动
|
||||
|
||||
- 用户主页、关注关系和可见性；
|
||||
- 动态、文章、图片、音视频和作品集合；
|
||||
- 评论、回复、点赞、收藏、标签和分享；
|
||||
- 搜索、话题、推荐流、趋势和通知；
|
||||
- 屏蔽、静音、举报、审核、申诉和处置历史。
|
||||
|
||||
### 2.2 角色社区
|
||||
|
||||
角色、世界设定、知识库、工作流、Prompt、Live2D、3D、声音和插件都以**发布版本**进入社区：
|
||||
|
||||
- 草稿与已发布版本分离；
|
||||
- 每版保存来源、作者、许可证、兼容版本和变更说明；
|
||||
- Fork 创建谱系边，不冒充原作者或同一角色身份；
|
||||
- 下架阻止新分发，但既有许可副本按许可与安全处置规则处理；
|
||||
- 角色私密记忆、关系和会话永不随公开角色版本发布。
|
||||
|
||||
## 3. 搜索与推荐
|
||||
|
||||
- 搜索索引是派生数据，可从公开内容和许可元数据重建。
|
||||
- 推荐使用显式互动、内容特征和用户可控偏好；私密消息、敏感记忆、精确位置和诊断内容不作为特征。
|
||||
- 用户可以查看主要推荐原因、关闭个性化和重置推荐数据。
|
||||
- 反指标包括成瘾诱导、付费偏置未披露、未成年人不当内容和小创作者系统性不可见。
|
||||
|
||||
## 4. 内容治理
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> draft
|
||||
draft --> published
|
||||
published --> limited
|
||||
published --> removed
|
||||
limited --> published
|
||||
limited --> removed
|
||||
removed --> appealed
|
||||
appealed --> published
|
||||
appealed --> removed
|
||||
```
|
||||
|
||||
Policy 覆盖：违法内容、现实人物冒充、声音/肖像许可、成人内容、骚扰、隐私、恶意插件、版权和交易欺诈。自动模型只能产生信号或临时限流，高影响永久处置需要可审阅规则和申诉。
|
||||
|
||||
## 5. 协作空间
|
||||
|
||||
Workspace 包含：
|
||||
|
||||
- owner、admin、editor、reviewer、viewer 等 RBAC；
|
||||
- 邀请、移除、权限变更和外部链接；
|
||||
- 角色、世界、知识、工作流和资产的版本分支；
|
||||
- 评审、评论、批准、合并和活动记录；
|
||||
- 协同编辑 presence、乐观并发或 CRDT；
|
||||
- 发布权限与市场上架权限分离。
|
||||
|
||||
协作者能编辑项目不等于能读取成员私密记忆、个人对话、支付账户或诊断内容。
|
||||
|
||||
## 6. 插件注册与分发
|
||||
|
||||
插件发布物包含 Manifest、包摘要、签名、权限、依赖、兼容版本、配置 Schema、隐私说明、源代码/许可证信息和安全扫描结果。
|
||||
|
||||
状态：draft → submitted → review → published → suspended/removed。更新产生新不可变版本；安全撤架可阻止安装和执行，但不能静默删除历史 Run 的 PluginSnapshot。
|
||||
|
||||
## 7. 市场商品与许可
|
||||
|
||||
商品类型：角色发布版、角色卡、世界设定、知识库、Prompt/工作流、Live2D、3D、声音、媒体包和插件。
|
||||
|
||||
每个 Listing 绑定：
|
||||
|
||||
- seller 与可验证发布版本；
|
||||
- 价格、货币、地区、税类和可售状态；
|
||||
- 许可证、允许的用途、席位/设备范围、更新政策和退款政策；
|
||||
- 审核状态、年龄分级、交付对象摘要和内容哈希。
|
||||
|
||||
订单成功创建 `entitlement`；下载 URL 只是短期交付方式，不是许可本身。
|
||||
|
||||
## 8. 支付、退款与账务
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant U as Buyer
|
||||
participant O as Order Service
|
||||
participant P as Payment Provider
|
||||
participant W as Webhook Consumer
|
||||
participant L as Ledger
|
||||
participant E as Entitlement
|
||||
|
||||
U->>O: create order with idempotency key
|
||||
O->>P: create payment
|
||||
P-->>U: payment confirmation flow
|
||||
P-->>W: signed webhook
|
||||
W->>W: verify and deduplicate
|
||||
W->>L: append payment entries
|
||||
L->>E: grant entitlement
|
||||
E-->>U: deliver purchased version
|
||||
```
|
||||
|
||||
- 金额使用最小货币单位或 Decimal；
|
||||
- Ledger 采用复式或等价不可变分录，修正使用反向分录；
|
||||
- 订单、Provider payment、退款、拒付、平台费、创作者应付和税费分别记录；
|
||||
- Webhook 不依赖到达顺序，按 Provider event ID 幂等；
|
||||
- 每日自动对账 Provider 报表、订单和 Ledger；
|
||||
- 退款更新 entitlement 的后续更新/下载策略，不能删除审计账。
|
||||
|
||||
## 9. 创作者结算
|
||||
|
||||
- 创作者账户记录 KYC/主体状态、地区、结算币种、税务资料引用和 Provider account；
|
||||
- 收益先进入 pending，经过退款/拒付准备期后转 available；
|
||||
- SettlementBatch 生成应付、费用、税款和净额；
|
||||
- Provider payout 失败可重试，但同一结算批次不能重复付款；
|
||||
- 提供对账单、发票/税务数据导出、结算历史和争议工单。
|
||||
|
||||
敏感 KYC 和银行数据优先由支付 Provider 托管；Hunjing 只保存引用、状态和必要的脱敏信息。
|
||||
@@ -0,0 +1,123 @@
|
||||
# 数据架构
|
||||
|
||||
## 1. 事实源
|
||||
|
||||
关系数据库保存角色、社区、协作、交易、插件和运行的权威状态；对象存储保存媒体与交付物；全文、向量、图投影、推荐特征和缓存都是派生数据。
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
DB[(Relational Source of Truth)] --> FTS[Full-text Index]
|
||||
DB --> V[Vector Index]
|
||||
DB --> G[Graph Projection]
|
||||
DB --> C[Cache]
|
||||
FS[(Object Storage)] --> DB
|
||||
FTS & V & G & C --> Q[Query and Retrieval]
|
||||
```
|
||||
|
||||
任何索引可从数据库和对象存储重建，不能反向覆盖角色、记忆、社区来源、许可或交易账。
|
||||
|
||||
## 2. 核心关系
|
||||
|
||||
```mermaid
|
||||
erDiagram
|
||||
PERSONAL_DOMAIN ||--o{ CHARACTER : owns
|
||||
CHARACTER ||--o{ CHARACTER_VERSION : versions
|
||||
CHARACTER ||--o{ CHARACTER_ASSET : presents
|
||||
CHARACTER ||--o{ MEMORY : remembers
|
||||
CONVERSATION ||--o{ BRANCH : contains
|
||||
BRANCH ||--o{ MESSAGE : orders
|
||||
CONVERSATION ||--o{ RUN : triggers
|
||||
RUN ||--o{ TURN : contains
|
||||
TURN ||--o{ MODEL_CALL : attempts
|
||||
TURN ||--o{ TOOL_CALL : invokes
|
||||
RUN }o--|| PLUGIN_SNAPSHOT : pins
|
||||
WORKSPACE ||--o{ WORKSPACE_MEMBER : authorizes
|
||||
WORKSPACE ||--o{ PROJECT_ASSET : contains
|
||||
USER ||--o{ COMMUNITY_CONTENT : publishes
|
||||
COMMUNITY_CONTENT ||--o{ INTERACTION : receives
|
||||
PUBLISHER ||--o{ PLUGIN_VERSION : releases
|
||||
MARKETPLACE_LISTING }o--|| RELEASE_VERSION : sells
|
||||
ORDER ||--o{ ORDER_ITEM : contains
|
||||
ORDER ||--o{ LEDGER_ENTRY : posts
|
||||
ORDER_ITEM ||--|| ENTITLEMENT : grants
|
||||
SETTLEMENT_BATCH ||--o{ LEDGER_ENTRY : settles
|
||||
```
|
||||
|
||||
## 3. 数据分区
|
||||
|
||||
| 范围 | 典型数据 | 默认可见性 |
|
||||
| --- | --- | --- |
|
||||
| Personal Domain | 私密角色、记忆、对话、设备授权 | owner only |
|
||||
| Workspace | 协作角色、世界、资产、评审 | member RBAC |
|
||||
| Community | 已发布内容、互动、公开版本 | visibility policy |
|
||||
| Marketplace | 商品、许可和公开交付摘要 | regional catalog |
|
||||
| Finance | 订单、支付、退款、账务、结算 | buyer/seller/finance roles |
|
||||
| Diagnostics | Run、工具、上下文和敏感支持包 | scoped grant |
|
||||
|
||||
公开角色 Release 不包含 Personal Domain 中的私密记忆、关系、对话和密钥。
|
||||
|
||||
## 4. 角色、记忆与资产
|
||||
|
||||
- CharacterVersion：不可变角色设定版本。
|
||||
- CharacterAsset：图像、声音、Live2D、3D、动作和场景版本，引用对象与许可。
|
||||
- Memory/MemoryVersion：长期状态、来源、敏感度、置信度、有效期、审批和纠正链；所有权、写入、版本、检索与装配见[记忆与知识架构](memory-and-knowledge.md)。
|
||||
- KnowledgeDocument：外部资料、世界设定和共享知识，不等于人物经历。
|
||||
- ReleaseVersion：面向社区/市场发布的不可变物料清单与内容哈希。
|
||||
|
||||
## 5. 社区与协作
|
||||
|
||||
- CommunityContent 使用统一发布对象加类型化 payload；互动独立记录并支持软删除与治理状态。
|
||||
- Follow、Block、Report 和 ModerationCase 为一等对象。
|
||||
- WorkspaceMember 和资源 ACL 双重约束；关键权限变更写审计。
|
||||
- 协同编辑使用版本号/乐观锁；高频富文本或场景编辑确有需要时采用 CRDT，快照仍落关系事实源。
|
||||
- 推荐特征保存来源和版本，允许用户清除；Restricted 数据不得进入。
|
||||
|
||||
## 6. 插件 Registry
|
||||
|
||||
Plugin、PluginVersion、PackageBlob、Signature、PermissionManifest、Compatibility、Review、Installation 和 PluginSnapshot 分开保存。PluginVersion 不可变；下架修改可分发状态，不改历史包摘要和 Run 快照。
|
||||
|
||||
## 7. 订单与账务
|
||||
|
||||
- Listing 可变；OrderItem 固定购买时的版本、价格、税、许可和卖家快照。
|
||||
- PaymentAttempt、Refund、Dispute、Entitlement 与 Order 分离。
|
||||
- LedgerEntry 不可变，使用平衡分录或等价会计模型；修正写反向分录。
|
||||
- CreatorBalance 是 Ledger 聚合，不是独立可编辑事实。
|
||||
- SettlementBatch 固定结算项；PayoutAttempt 记录 Provider 结果和幂等键。
|
||||
- 金额使用整数最小单位或 Decimal，记录币种、汇率来源和价格版本。
|
||||
|
||||
## 8. Run 与诊断
|
||||
|
||||
Run 只保存聚合状态。Turn、ModelCall、ToolCall、ContextSnapshot、PluginSnapshot 和 AuditEvent 独立查询。Provider 原始正文默认不保存；支持需要时进入加密、限期对象并受 Sensitive DiagnosticGrant 控制。
|
||||
|
||||
## 9. 删除与许可传播
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
D[Delete or revoke request] --> A[Authorize and audit]
|
||||
A --> P[Update authoritative source]
|
||||
P --> I[Remove indexes and caches]
|
||||
P --> O[Delete or redact derived objects]
|
||||
P --> R[Evaluate releases and entitlements]
|
||||
R --> N[Stop new distribution or updates]
|
||||
O --> B[Apply backup retention]
|
||||
B --> T[Keep minimal tombstone]
|
||||
```
|
||||
|
||||
删除私密源数据不等于撤销所有已合法发布许可；撤架、许可撤销、安全强制停用和用户删除分别建模。墓碑不保存被删原文。
|
||||
|
||||
## 10. 一致性与事件
|
||||
|
||||
- 权威状态和 Outbox 在同一事务写入；完整 1.0 的媒体、索引、通知、支付、社区和插件消费者需要 Outbox。
|
||||
- Webhook/ToolCall 在副作用前写 pending 与幂等键，完成后写结果。
|
||||
- 支付事件不依赖到达顺序；重复事件返回已有处理结果。
|
||||
- 搜索、推荐、媒体和向量失败可重建，不影响权威状态。
|
||||
|
||||
## 11. 存储选择
|
||||
|
||||
- SQLite：本地开发与个人轻量自托管。
|
||||
- PostgreSQL：正式部署的关系事实源和全文检索。
|
||||
- Redis：队列、限流、实时会话和短期状态。
|
||||
- S3-compatible：媒体、插件包、交付物和加密支持包。
|
||||
- pgvector：默认语义检索起点；规模或评测需要时替换为专用向量库。
|
||||
- 图关系先使用 PostgreSQL；多跳规模证明需要时启用 Neo4j/NebulaGraph 投影。
|
||||
- 分析/搜索引擎按社区规模引入，不成为交易或身份事实源。
|
||||
@@ -0,0 +1,184 @@
|
||||
# 前端富内容实时渲染
|
||||
|
||||
## 1. 适用客户端
|
||||
|
||||
同一渲染内核服务 Next.js Web、Tauri Desktop 和 Tauri Mobile。平台差异只位于资源加载、文件保存、设备能力和性能档位；ContentBlock 与流状态机保持一致。
|
||||
|
||||
推荐组件：
|
||||
|
||||
- Markdown：`react-markdown` + `remark-gfm` + 受控 remark/rehype 插件；
|
||||
- Code：Shiki，高亮 Worker 与缓存；
|
||||
- Math：KaTeX 为默认，MathJax 只作为兼容回退；
|
||||
- Mermaid：Mermaid strict mode，在 Worker/隔离容器渲染 SVG；
|
||||
- 长列表：`@tanstack/react-virtual`；
|
||||
- 媒体：原生 image/video/audio，使用受控资源 URL；
|
||||
- 状态：TanStack Query 管服务端资源；轻量本地 store 管流 accumulator 和 UI 状态。
|
||||
|
||||
新增依赖前仍需按 AGENTS.md 查当前维护状态和已安装能力。
|
||||
|
||||
## 2. 渲染流水线
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
SSE[SSE Events] --> ACC[Event Accumulator]
|
||||
ACC --> STORE[Block Store]
|
||||
STORE --> PARSE[Incremental Parse]
|
||||
PARSE --> SAFE[Sanitize and Validate]
|
||||
SAFE --> RENDER[Typed Renderers]
|
||||
RENDER --> DOM[Accessible UI]
|
||||
FINAL[Completed Message] --> RECON[Reconcile]
|
||||
RECON --> STORE
|
||||
```
|
||||
|
||||
各层职责：
|
||||
|
||||
1. Event Accumulator：校验 run sequence 与 block delta index，去重和检测缺口。
|
||||
2. Block Store：以 `message_id/block_id` 保存原始 block、流状态和 renderer 状态。
|
||||
3. Parse：只对允许增量的类型做节流解析。
|
||||
4. Sanitize：URL、Markdown AST、SVG、公式和媒体元数据安全处理。
|
||||
5. Renderer：按 Block type 分派，未知类型显示兼容占位而不崩溃。
|
||||
6. Reconcile：`content.block.completed` 与 `message.completed` 到达后用权威快照替换临时状态。
|
||||
|
||||
## 3. 流状态机
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> pending
|
||||
pending --> streaming : block.started
|
||||
streaming --> streaming : ordered delta
|
||||
streaming --> awaiting_replay : delta gap
|
||||
awaiting_replay --> streaming : replay filled
|
||||
awaiting_replay --> completed : final snapshot
|
||||
streaming --> completed : block.completed
|
||||
streaming --> failed : block.failed
|
||||
streaming --> cancelled : block.cancelled
|
||||
failed --> completed : retry/resource ready
|
||||
completed --> [*]
|
||||
cancelled --> [*]
|
||||
```
|
||||
|
||||
- 乱序 delta 暂存在小窗口；超过窗口请求重放，不猜顺序。
|
||||
- 重复 delta 根据 `(block_id, delta_index)` 丢弃。
|
||||
- 连接断开保留乐观内容并标记“正在恢复”；最终 GET Run/Message 对账。
|
||||
- Final snapshot 与累积 hash 不一致时记录前端诊断并以服务端快照为准。
|
||||
|
||||
## 4. Markdown 增量渲染
|
||||
|
||||
### 4.1 策略
|
||||
|
||||
- 原始增量文本始终保留；AST 是可丢弃派生状态。
|
||||
- 以 50–100 ms 或换行边界节流解析，不逐 token 全量重渲染。
|
||||
- 未闭合 fence、链接、表格、强调或数学定界符保持源码/纯文本展示，不自动补造语义。
|
||||
- Completed 后对完整 Markdown 再解析一次，替换临时 AST。
|
||||
- 大 Block 分段渲染，避免每次 delta 重建整个消息树。
|
||||
|
||||
### 4.2 安全
|
||||
|
||||
- 禁用原始 HTML；若以后开放，仅对可信内部内容使用严格 allowlist。
|
||||
- 链接协议允许 `https`、`mailto` 和内部资源 scheme；拒绝 `javascript`、危险 `data`、`file`。
|
||||
- 外链打开使用 `noopener noreferrer`，并显示目标域。
|
||||
- Markdown 图片规范化为 Image Block；不直接加载任意第三方跟踪像素。
|
||||
|
||||
## 5. Code 与 Shiki
|
||||
|
||||
- 流式时先用等宽纯文本展示；完整行或节流窗口后发送 Worker 高亮。
|
||||
- Shiki grammar 按需加载并缓存；未知语言回退 plain text。
|
||||
- 超大代码块关闭实时高亮，完成后按可见区域高亮。
|
||||
- 提供复制、换行、下载、语言、文件名和行号；复制取原始源码，不从高亮 DOM 提取。
|
||||
- 代码永不在渲染器执行；可执行动作是独立 Tool/Approval。
|
||||
|
||||
## 6. 数学公式
|
||||
|
||||
### 6.1 解析
|
||||
|
||||
- Native Math Block 直接按 `notation` 处理。
|
||||
- Markdown 中只有闭合 `$...$`、`$$...$$`、`\(...\)`、`\[...\]` 才触发公式渲染。
|
||||
- 流式未闭合公式显示转义源码和稳定占位，避免页面反复跳动。
|
||||
- KaTeX 解析失败显示 `fallback_text` 或源码，并提供错误详情展开。
|
||||
|
||||
### 6.2 安全和可访问性
|
||||
|
||||
- KaTeX `trust=false`，限制宏、展开深度和输入长度；禁用 URL/HTML 注入命令。
|
||||
- 生成 MathML/ARIA；Block 公式提供自然语言 `fallback_text`、变量和单位说明。
|
||||
- 用户可切换“渲染公式/显示源码”。
|
||||
- 常见公式描述采用“名称 → 公式 → 变量/单位 → 适用条件 → 示例”的结构，不把推导过程混入隐藏思维。
|
||||
|
||||
## 7. Mermaid
|
||||
|
||||
- 流式期间不渲染图，仅展示代码骨架和进度。
|
||||
- `block.completed` 后把源码发送 Worker；验证节点数、边数、字符数和超时。
|
||||
- Mermaid 使用 `securityLevel: strict`，禁止 click、HTML label、外部资源和任意初始化指令。
|
||||
- 输出 SVG 再经 sanitizer；SVG 不允许 script、foreignObject、事件属性或外部 URL。
|
||||
- 渲染失败显示源码、错误摘要和“复制到 Mermaid 编辑器”的安全动作，不空白。
|
||||
- 提供缩放、平移、适配宽度、下载 SVG/PNG、文本替代和全屏。
|
||||
- 图表在移动端默认源码/缩略图折叠，按需展开，防止长宽溢出。
|
||||
|
||||
## 8. 图片、视频和音频
|
||||
|
||||
### 图片
|
||||
|
||||
- 使用 `file_id` 换取短期授权 URL；响应式尺寸、懒加载、占位、失败重试和 alt。
|
||||
- 不信任服务端文件名/MIME；资源域返回正确 Content-Type、CSP、CORP 和 `nosniff`。
|
||||
- 大图支持查看器、缩放和下载；不默认将 EXIF 暴露给其他用户。
|
||||
|
||||
### 视频
|
||||
|
||||
- 等待 `resource_ready` 后显示 poster；使用 HLS/DASH 或受控 MP4。
|
||||
- 提供字幕、转写、时长、加载/转码状态和失败说明。
|
||||
- 自动播放默认关闭；有声音播放必须由用户手势触发。
|
||||
|
||||
### 音频
|
||||
|
||||
- 显示波形/时长/转写；流式 TTS 与固化 Audio Block 分离。
|
||||
- 实时语音使用 WebSocket 播放队列，不把每帧写入 React 树。
|
||||
- 支持打断、静音、速度和字幕；停止后清空未播放帧。
|
||||
|
||||
## 9. Agent、工具和审批展示
|
||||
|
||||
- AgentStatus Block 显示当前阶段、ChildRun、预算、等待和取消操作，不展示隐藏推理。
|
||||
- ToolCall Block 默认显示工具名、用途、状态、耗时和脱敏参数摘要；敏感详情走诊断授权。
|
||||
- ApprovalRequest 必须显示动作、目标、影响、费用、数据范围、有效期、允许/拒绝按钮。
|
||||
- ToolResult 区分成功、错误、未知结果和产物，不把错误结果渲染成普通助手文本。
|
||||
- 并行 ChildRun 使用树/时间线，主消息流只展示汇总状态，避免刷屏。
|
||||
|
||||
## 10. 长列表与性能
|
||||
|
||||
- Conversation/Community/Diagnostics 使用虚拟滚动，Block 高度由 ResizeObserver 缓存。
|
||||
- 流式中的当前 Message 可脱离虚拟列表单独渲染，完成后归档入列表。
|
||||
- Markdown AST、Shiki tokens、Mermaid SVG 和 Math 渲染按 content hash 缓存。
|
||||
- Worker 处理高亮、Mermaid 和重解析；主线程只提交最终安全树。
|
||||
- `prefers-reduced-motion` 关闭非必要动画；流式光标不引发布局抖动。
|
||||
- 建立不同设备性能档：关闭实时代码高亮、降低 Avatar 帧率、延迟复杂图渲染，而不丢失内容。
|
||||
|
||||
## 11. 可访问性
|
||||
|
||||
- 每个 Block 使用正确语义元素和可聚焦操作。
|
||||
- 新 delta 不持续抢夺屏幕阅读器焦点；用节流 `aria-live` 汇报状态。
|
||||
- 图像必有 alt；图表有 title/caption/源码替代；音视频有字幕/转写。
|
||||
- 数学提供 MathML 和 fallback text；代码支持键盘复制和横向滚动。
|
||||
- 工具确认、错误和费用不能只靠颜色表达。
|
||||
- Avatar/动效不阻塞核心内容和操作。
|
||||
|
||||
## 12. 失败与降级
|
||||
|
||||
| 失败 | 展示 |
|
||||
| --- | --- |
|
||||
| Markdown 解析失败 | 转义纯文本 |
|
||||
| Shiki 失败 | plain code |
|
||||
| Math 失败 | fallback text + source |
|
||||
| Mermaid 失败 | source + error summary |
|
||||
| 媒体未就绪 | progress placeholder |
|
||||
| 媒体失败 | retry/download details |
|
||||
| 未知 Block type | “当前客户端暂不支持” + JSON-safe summary |
|
||||
| SSE 断线 | recovering 状态 + replay/final fetch |
|
||||
| hash 不一致 | final snapshot + diagnostic marker |
|
||||
|
||||
降级必须保留用户内容，不以空白、崩溃或静默删除处理。
|
||||
|
||||
## 13. 测试
|
||||
|
||||
- 对每种 Block 建立 canonical fixture、流式分片、断线、重复、乱序、失败和未知类型测试。
|
||||
- Markdown/Math/Mermaid 做 XSS、URL、SVG、宏膨胀和资源耗尽测试。
|
||||
- 浏览器组件测试覆盖键盘、屏幕阅读器、reduced motion 和移动布局。
|
||||
- Playwright 覆盖从 SSE 到 Markdown/公式/Mermaid/媒体/Tool Approval 的端到端流程。
|
||||
- 对 1 MB Markdown、万行代码、复杂 Mermaid、长公式和大量消息做性能基线。
|
||||
@@ -0,0 +1,119 @@
|
||||
# 灵台引擎架构
|
||||
|
||||
> 决策依据：[ADR-016](../decisions/README.md#adr-016灵台引擎采用-c-核心与稳定-c-abi)、[ADR-017](../decisions/README.md#adr-017灵台引擎双形态部署)。ABI 稳定值登记于 [Lingtai C ABI](../contracts/lingtai-ffi.md)，独立服务契约见 [Lingtai Service](../contracts/lingtai-service.md)。文化名见[文化语言体系](../product/cultural-language.md)。
|
||||
|
||||
## 1. 定位与不变量
|
||||
|
||||
灵台引擎（Lingtai Engine / `libhunjing`）是 C++ 实现的确定性计算库，支持进程内嵌入与独立服务两种部署形态，为 Python、Rust、Go 宿主提供同一份核心实现：
|
||||
|
||||
- **无权威状态**：角色、消息、记忆、订单等权威数据只在关系数据库与对象存储；引擎持有的一切中间产物可丢弃重建。崩溃或版本更换后，宿主从权威数据重放即可恢复。
|
||||
- **最小 I/O**：除显式传入的只读索引文件（`hj_recall` 以只读方式 mmap）外，引擎不打开文件、不发起网络、不连接数据库；输入输出全部经调用参数。独立服务形态下，网络端点由服务壳承担，核心计算仍不做自主 I/O。
|
||||
- **单一核心、双形态**：进程内嵌入与 gRPC 独立服务是同一核心的两种壳；任何能力的语义在两种形态下必须一致（同一 golden 测试集约束），形态选择是部署决策而非代码分叉。
|
||||
- **Core 的一部分**：灵台引擎实现治理内核中的确定性判定部分，属于不可插件化边界；插件不直接链接引擎，只能经宿主 Runtime 间接获得能力。
|
||||
- **fail closed**：引擎缺失、初始化失败、ABI 不匹配或服务不可达时，依赖该能力的宿主路径必须显式失败；禁止在宿主语言内维护第二份实现作为降级。
|
||||
|
||||
## 2. 灵台六模块子系统
|
||||
|
||||
| 文化名 | 稳定模块 | 职责 | 禁止承担 |
|
||||
| --- | --- | --- | --- |
|
||||
| 太一 | `hj_core` | 单一稳定入口：ABI/服务版本协商、句柄生命周期、跨形态统一路由、Run/Turn 状态转换合法性校验、事件 `sequence` 分配、跨模块错误上下文 | 持久化状态、业务裁决 |
|
||||
| 小周天 | `hj_stream` | ContentBlock 流事件编码、`delta_index` 维护、`(block_id, delta_index)` 去重键、节流与背压计算、重放缓冲 | 发起网络 I/O、持久化流历史 |
|
||||
| 洛书 | `hj_plan` | 计划 DAG 校验与拓扑排序、RunBudget 核算、Context Manifest 的 token 预算裁剪与优先级排序 | 调用模型、执行工具、创建子 Run |
|
||||
| 河图 | `hj_recall` | 端侧与离线场景的只读混合检索索引、重排打分、多路检索合并 | 成为服务端权威检索（PostgreSQL 仍为权威）、写入索引 |
|
||||
| 陶钧 | `hj_transform` | Markdown → canonical ContentBlock 确定性解析、数学定界符与 Mermaid fenced 提取、parser version 标注、导出重建 | 执行 HTML、请求网络资源 |
|
||||
| 烛照 | `hj_policy` | JSON Schema 子集结构校验、路径 canonicalize 与根目录约束、URL scheme/host 校验、HMAC 验签、幂等键规范化、分层递进的决策表评估 | 发起用户审批交互、执行副作用 |
|
||||
|
||||
"太一出两仪"：`hj_core`（太一）是唯一对外总入口（单一稳定入口理念），承载版本协商、句柄与跨形态路由；其余五模块的会话句柄都从 `HjEngine` 派生并在其中登记，统一计数、统一回收——诸枢皆居灵台之内。烛照的判定按"结构 → 路径/URL → 签名 → 预算"分层递进，单层拒绝即短路返回，对应纵深防御理念。
|
||||
|
||||
```mermaid
|
||||
flowchart TB
|
||||
API[hj_ C ABI and gRPC service face] --> CORE[hj_core]
|
||||
CORE --> STREAM[hj_stream]
|
||||
CORE --> PLAN[hj_plan]
|
||||
CORE --> RECALL[hj_recall]
|
||||
CORE --> TRANSFORM[hj_transform]
|
||||
CORE --> POLICY[hj_policy]
|
||||
RECALL --> RO[(read-only index files)]
|
||||
```
|
||||
|
||||
## 3. 部署形态
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
subgraph Embedded
|
||||
PY[FastAPI host] --> B1[nanobind binding]
|
||||
RS[Tauri Rust host] --> B2[bindgen wrapper]
|
||||
GO2[Go gateway host] --> B3[cgo binding]
|
||||
B1 & B2 & B3 --> ABIL[stable C ABI hj_]
|
||||
end
|
||||
subgraph Standalone
|
||||
ANY[any host in deployment] --> GRPC[gRPC over mTLS]
|
||||
end
|
||||
ABIL --> ENGINE[Lingtai core]
|
||||
GRPC --> SRV[hunjing-lingtai-server]
|
||||
SRV --> ENGINE
|
||||
```
|
||||
|
||||
### 3.1 进程内嵌入（默认）
|
||||
|
||||
- 宿主经 C ABI 链接 `libhunjing`；绑定层是薄封装：类型转换、内存托管（RAII/GC 挂钩）、错误映射为各语言惯用错误类型；不复制业务语义，不缓存权威状态。
|
||||
- 适用：模块化单体部署的全部计算路径、Tauri 桌面/移动端（含离线）、对延迟敏感的调用（每请求同步计算）。
|
||||
- 宿主负责一切 I/O 编排：数据库读写、模型调用、SSE/WebSocket 传输、审批交互。引擎只回答"计算结果是什么"，不回答"接下来做什么"。
|
||||
|
||||
### 3.2 独立服务（按需启用）
|
||||
|
||||
- `hunjing-lingtai-server` 链接同一核心，以 gRPC 暴露能力；契约（proto、方法、流语义、错误映射）见 [Lingtai Service](../contracts/lingtai-service.md)。
|
||||
- 适用：重型解析/检索需要独立扩缩容与资源隔离；同一部署内多宿主（API、Worker、网关）共享引擎容量；引擎需独立升级发布；跨机器集中计算。
|
||||
- 服务只在部署内部网络监听，经 mTLS/工作负载身份认证；不进入公共 API 分面，不经网关对外暴露。
|
||||
- 启用标准沿用[系统架构](system-architecture.md)的服务拆分标准；不满足标准时保持嵌入形态。
|
||||
|
||||
### 3.3 形态选择与演化
|
||||
|
||||
- 默认嵌入；满足独立扩缩容、故障域、资源隔离或多宿主共享证据时切换或混用（例如服务端用服务形态、端侧用嵌入形态）。
|
||||
- 客户端代码面向"引擎 Port"编程（进程内与服务两个实现），切换形态不改业务语义，只改部署配置；Port 定义见[内部端口](../contracts/internal-api.md)的组织方式。
|
||||
- 前端 Web（TypeScript）不经 C ABI；如需复用解析逻辑，WebAssembly 编译目标与"经服务形态远程消费"作为 1.0 后评估项，不在本架构承诺内。
|
||||
|
||||
### 3.4 真实调用点
|
||||
|
||||
| 宿主路径 | 使用子系统 | 对应工作包 |
|
||||
| --- | --- | --- |
|
||||
| 消息创建：用户 Markdown 规范化为 canonical ContentBlock | `hj_transform` | WP-03 |
|
||||
| Run SSE：事件 envelope 编码、增量去重与节流 | `hj_stream` | WP-03/WP-05 |
|
||||
| Tool input Schema 校验、工具路径/URL 约束判定 | `hj_policy` | WP-06 |
|
||||
| Webhook 验签与幂等键规范化 | `hj_policy` | WP-13 |
|
||||
| 计划 DAG 校验与 RunBudget 核算 | `hj_plan` | WP-06 |
|
||||
| Tauri 移动端加密离线缓存的本地检索与重排 | `hj_recall`（仅嵌入形态） | WP-10 |
|
||||
| Run/Turn 状态转换合法性校验 | `hj_core` | WP-05/WP-06 |
|
||||
|
||||
## 4. 内存、线程与错误模型
|
||||
|
||||
- **所有权**：引擎分配的缓冲区只能交还 `hj_buffer_free` 释放；宿主内存以 `const` 指针加长度只读传入，引擎不得持有调用返回后的宿主指针。
|
||||
- **字符串**：一律 UTF-8；输入可为 NUL 结尾或指针加长度，输出始终为指针加长度。
|
||||
- **句柄**：`HjEngine` 线程安全，可被多线程并发调用；`hj_stream` 等会话级句柄单线程亲和，由创建线程使用。句柄关闭两次返回 `HJ_ERR_HANDLE_INVALID`，不崩溃。
|
||||
- **回调**：流式回调在调用线程同步触发；回调内部禁止再调用引擎 API，违规以 `HJ_ERR_REENTRANCY` 尽力检测。
|
||||
- **异常与崩溃**：C++ 异常不得跨越 ABI；引擎入口捕获一切异常并转换为 `HjStatus`。任何输入都不得导致引擎 `abort`/未定义行为——解析失败返回 `HJ_ERR_PARSE_FAILED`，超限返回 `HJ_ERR_LIMIT_EXCEEDED`。
|
||||
- **错误传递**：`HjStatus` 携带稳定码；`hj_last_error` 提供该线程最近一次错误的消息缓冲（不含敏感正文），绑定层映射为宿主异常/`Result`/`error`，服务层再映射为 HTTP 错误契约。
|
||||
|
||||
## 5. 与既有架构的关系
|
||||
|
||||
- **内容契约不变**：`hj_transform` 的输入输出即 [统一富内容与流式协议](../contracts/content-blocks-and-streaming.md) 定义的 Block 与事件 JSON Schema；引擎输出 canonical JSON（键序确定），供 hash 与跨端一致性测试。
|
||||
- **状态机权威不变**：Run/Turn/ModelCall 的持久化与恢复遵循 [Agent 运行时](agent-runtime.md)；`hj_core` 只校验状态迁移合法性并分配 `sequence`，不存储权威状态。
|
||||
- **检索分工**：服务端权威检索仍是 PostgreSQL 全文与 pgvector（[记忆与知识架构](memory-and-knowledge.md)）；`hj_recall` 服务于端侧离线与重排计算，索引是可重建投影，删除与授权变化随宿主重建传播。
|
||||
- **策略归属**：审批流、用户确认与 Policy 最终裁决遵循 [安全与诊断访问](../security/security-and-diagnostics.md)；`hj_policy` 提供确定性判定原语与高速规则评估，不发起 I/O、不绕过审批。
|
||||
- **插件边界**：[插件系统](plugin-system.md) 的 Manifest、Snapshot、双轨执行不变；插件经宿主间接消费引擎能力，Run 快照记录引擎与 parser 版本。
|
||||
|
||||
## 6. 构建、分发与平台
|
||||
|
||||
- 语言标准 C++23，CMake + Ninja；符号默认隐藏，仅导出 `hj_*`（API 卫生，非对抗手段）。
|
||||
- 产物：动态库 `libhunjing`（`.so`/`.dylib`/`.dll`）与静态库；独立服务二进制 `hunjing-lingtai-server`；单一公共头 `include/hunjing/lingtai.h` 与服务 proto（见 [Lingtai Service](../contracts/lingtai-service.md)）。
|
||||
- 平台矩阵：Linux x86_64/aarch64、macOS aarch64、Windows x86_64、iOS/Android arm64（服务态）；iOS/Android 仅嵌入形态，不交付服务二进制。
|
||||
- CI 产出带版本号的预编译产物并做签名与哈希公示；自托管者可从源码构建，构建须可重现。
|
||||
- 依赖最小化：第三方库进入前按工程规则评估官方文档、许可与维护状态；ANN/分词/gRPC 栈等实现选型在实现期以补充 ADR 登记，本文不预设。
|
||||
|
||||
## 7. 安全与测试边界
|
||||
|
||||
- 引擎的全部输入（用户 Markdown、模型输出、工具参数、检索查询、Webhook 原始字节）按不可信输入处理：长度与深度硬上限、资源限额由配置发布且 Schema 有上界。
|
||||
- 持续测试门槛：`hj_transform`/`hj_policy` 为 fuzz 必测目标（libFuzzer）；每次提交跑 ASan/UBSan，线程路径跑 TSan；ABI 快照测试保证符号与布局不发生未声明变更。
|
||||
- 双形态一致性：同一组 canonical 输入在 Python/Rust/Go 绑定与 gRPC 服务路径下的输出字节一致（golden 测试覆盖进程内与服务两种形态），防止绑定或服务壳漂移。
|
||||
- 服务形态额外要求：mTLS 双向认证、每方法超时与并发上限、背压与限流、调用审计（不含正文）；服务不可达时宿主 fail closed。
|
||||
- 引擎产物进入诊断或日志前遵守脱敏规则；错误消息不包含请求正文、密钥或凭据。
|
||||
@@ -0,0 +1,123 @@
|
||||
# 媒体、Avatar 与设备架构
|
||||
|
||||
## 1. 范围
|
||||
|
||||
完整 1.0 支持文字、图像、音频、实时语音、Live2D、3D Avatar，以及 Web、Tauri 桌面和 Tauri 移动端的文件、相机、麦克风、屏幕与位置能力。
|
||||
|
||||
## 2. 媒体处理
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
IN[Upload or Capture] --> CONSENT[Consent and Scope]
|
||||
CONSENT --> SCAN[Safety and Malware Scan]
|
||||
SCAN --> STORE[(Original Object)]
|
||||
STORE --> JOB[Media Job]
|
||||
JOB --> DERIVE[Transcode, ASR, Generate, Rig]
|
||||
DERIVE --> REVIEW[User Review]
|
||||
REVIEW --> ASSET[Versioned Character Asset]
|
||||
ASSET --> RENDER[Client Avatar Runtime]
|
||||
```
|
||||
|
||||
- 原始媒体、派生媒体、缩略图、转写和模型输入分别记录来源与保留期。
|
||||
- 媒体任务异步执行，支持进度、取消、失败重试和幂等。
|
||||
- 生成或编辑结果先是候选，用户采用后才成为角色正式资产版本。
|
||||
- 文件名、MIME、实际内容、尺寸和许可都要验证。
|
||||
|
||||
## 3. 语音
|
||||
|
||||
### 3.1 能力
|
||||
|
||||
- 上传音频和语音消息；
|
||||
- 流式或分段 ASR；
|
||||
- TTS 流式合成；
|
||||
- WebSocket 实时语音会话；
|
||||
- 打断、端点检测、字幕、语言检测和切换；
|
||||
- 预设声音、原创声音设计和授权声音克隆；
|
||||
- 原音频与 TTS 默认短期缓存，ASR 原转写与正影文本并存；多说话者默认匿名分段，长期声纹与身份识别需独立同意；不承诺持续监听或电话级全双工。
|
||||
|
||||
### 3.2 实时链路
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant C as Client
|
||||
participant G as Realtime Gateway
|
||||
participant A as ASR
|
||||
participant R as Agent Runtime
|
||||
participant T as TTS
|
||||
|
||||
C->>G: audio frames
|
||||
G->>A: authorized audio stream
|
||||
A-->>G: transcript deltas
|
||||
G->>R: finalized user segment
|
||||
R-->>G: text deltas
|
||||
G->>T: speakable text
|
||||
T-->>G: audio frames
|
||||
G-->>C: text and audio events
|
||||
C->>G: interrupt
|
||||
G->>R: cancel current generation
|
||||
G->>T: stop synthesis
|
||||
```
|
||||
|
||||
音频原文默认短期保留；转写纠正创建新版本。声音克隆必须绑定授权主体、用途、期限、传播范围和撤回状态。
|
||||
|
||||
## 4. 图像与角色一致性
|
||||
|
||||
- 文生图、图生图、局部重绘、背景去除、分层和风格参考；
|
||||
- 角色稳定外观参考与可变属性分离；
|
||||
- 每次生成保存模型、提示摘要、来源资产、许可和安全结果；
|
||||
- 社区/市场发布前检查现实人物、版权、成人内容和来源许可。
|
||||
|
||||
## 5. Live2D
|
||||
|
||||
1.0 包含：
|
||||
|
||||
- Cubism-compatible 模型导入和校验；
|
||||
- 图像分层辅助和候选导出；
|
||||
- 参数、表情、口型、视线、物理和动作映射；
|
||||
- 可视化参数编辑、预览和版本；
|
||||
- Web/Tauri 运行时；
|
||||
- 标准资源导出。
|
||||
|
||||
不重做 Cubism Editor 的全部专业绘制和网格编辑功能。
|
||||
|
||||
## 6. 3D
|
||||
|
||||
1.0 采用开放格式和非破坏编辑：
|
||||
|
||||
- VRM/glTF 导入、验证和标准化；
|
||||
- 材质、纹理、骨骼、BlendShape/表情映射；
|
||||
- 动作库、动画状态、口型、视线和实时姿态；
|
||||
- 灯光、相机、环境和场景对象编辑；
|
||||
- 角色附件、服饰挂点和版本；
|
||||
- WebGPU/WebGL 与 Tauri Runtime；
|
||||
- VRM/glTF 导出和来源清单。
|
||||
|
||||
2.0 才引入完整网格建模、雕刻、拓扑、绑定和 LLM 直接修改几何/绑定。1.0 的编辑命令和版本历史必须可扩展到该能力。
|
||||
|
||||
## 7. 设备授权
|
||||
|
||||
`device_grant` 至少绑定：
|
||||
|
||||
- user、device、character；
|
||||
- capability：file/camera/microphone/screen/location/notification；
|
||||
- purpose、scope、precision；
|
||||
- granted/started/expires/revoked 时间；
|
||||
- foreground/background 限制；
|
||||
- retention 与 derived-use 策略。
|
||||
|
||||
### 7.1 规则
|
||||
|
||||
- 默认关闭；首次使用由系统权限和产品确认共同授权。
|
||||
- 相机、麦克风和屏幕采集始终显示可感知指示。
|
||||
- 位置支持单次、使用期间、精度和有效期，不默认后台持续采集；相机支持单次看见与限时通感。
|
||||
- 设备采用一次配对、设备密钥、可撤销证书和可验证固件。
|
||||
- Tauri command 按 capability allowlist 暴露，不提供通用任意命令桥。
|
||||
- 移动平台后台能力受 iOS/Android 平台规则限制；不通过隐藏保活绕过。
|
||||
- 设备失联只允许已授权的本地缓存和安全停止，不运行独立角色副本。
|
||||
|
||||
## 8. 隐私与删除
|
||||
|
||||
- 原始采集和派生内容分别删除；
|
||||
- 已撤回声音授权停止新生成和新发布；
|
||||
- 社区或市场已有合法许可副本按许可条款处理，但不得继续暴露已删除的私密源文件；
|
||||
- 人脸、声纹、精确位置和屏幕内容为 Restricted 数据，不进入普通日志、推荐特征或自动记忆。
|
||||
@@ -0,0 +1,184 @@
|
||||
# 记忆与知识架构
|
||||
|
||||
> 本文定义 1.0 的记忆所有权、写入、版本、检索和上下文装配边界。字段与稳定枚举以 `docs/contracts/` 和后续 OpenAPI 3.1 为准。
|
||||
|
||||
## 1. 边界
|
||||
|
||||
- `Message` 是不可被记忆覆盖的原始交流记录；编辑产生 Revision。
|
||||
- `MemoryCandidate` 是待判定的提取结果，不参与正式召回。
|
||||
- `Memory` 是稳定标识；`MemoryVersion` 是不可变内容版本，当前版本仅由 `Memory` 指针引用。
|
||||
- `KnowledgeDocument` 保存外部资料和世界设定；其切片与索引是可重建投影，不冒充人物经历。
|
||||
- Character baseline、用户资料、关系、知识和记忆分别建模；任何记忆策略都不能直接修改 CharacterVersion。
|
||||
- 对话压缩、工作上下文和 Provider Prompt Cache 是运行期派生状态，不属于长期记忆。
|
||||
- 1.0 不定义可绕过治理的 `WorkingMemory` 类型；当前分支消息和 Run 临时上下文始终按 Personal Domain/Workspace、Character、Conversation、Branch 与 Run 授权，不能因“临时”跳过隔离。
|
||||
|
||||
1.0 的权威记忆是可检查、可纠正的文本或结构化记录。KV cache、隐藏状态和模型权重适配不作为权威记忆，也不进入 1.0 记忆可携格式。
|
||||
|
||||
## 2. 所有权与作用域
|
||||
|
||||
每条 Memory 必须属于且只属于一个授权边界：
|
||||
|
||||
| 所有权 | 必需关联 | 可选关联 | 用途 |
|
||||
| --- | --- | --- | --- |
|
||||
| Personal Domain | `personal_domain_id` | `character_id` | 用户级或私密角色级记忆 |
|
||||
| Workspace | `workspace_id` | `character_id` | 经成员权限允许的协作记忆 |
|
||||
|
||||
约束：
|
||||
|
||||
- `personal_domain_id` 与 `workspace_id` 二选一；在数据库层使用检查约束落实。
|
||||
- `character_id` 只能引用同一所有权边界内的 Character。
|
||||
- `conversation_id`、`message_id`、`content_block_id`、`run_id` 和 `tool_call_id` 是来源或适用条件，不是授权边界。
|
||||
- 角色间共享通过显式授权和独立引用完成，不复制一份失去来源关系的 Memory。
|
||||
- 子 Agent 只读父 Run 已批准的召回快照；默认没有创建、批准、纠正或删除长期记忆的能力。
|
||||
- 社区 Release、市场交付物和推荐特征不得包含 Personal Domain Memory。Workspace 内容发布前同样经过独立发布审查。
|
||||
|
||||
## 3. 记忆分类
|
||||
|
||||
1.0 只定义四类可解释长期记忆；稳定值登记在[协议与稳定标识](../contracts/README.md#memory_kind)，并在实现前进入 OpenAPI/Schema：
|
||||
|
||||
| 类型 | 含义 | 默认写入要求 |
|
||||
| --- | --- | --- |
|
||||
| `fact` | 可核对的人、事、状态或约束 | 有明确来源；冲突时生成纠正候选 |
|
||||
| `preference` | 用户或角色明确表达、或系统推断的偏好 | 显式与推断分开；推断偏好需要置信度 |
|
||||
| `event` | 带时间范围的经历或事件 | 保留时间语义和来源 |
|
||||
| `relationship` | 人物间关系及其变化 | 高影响，默认人工确认 |
|
||||
|
||||
身份基线、人格设定、权限、秘密、工具定义和知识文档不塞入上述类型。需要新类型时先更新契约和评测，不使用任意 metadata 绕过类型系统。
|
||||
|
||||
## 4. 写入与版本
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
S[Source] --> E[Extract]
|
||||
E --> C[Candidate]
|
||||
C --> P{Policy}
|
||||
P -->|approve| V[MemoryVersion]
|
||||
P -->|review| H[Human review]
|
||||
H -->|approve| V
|
||||
P -->|reject| X[Rejected]
|
||||
H -->|reject| X
|
||||
V --> A[(Authoritative DB)]
|
||||
A --> I[Indexes]
|
||||
I --> R[Retrieve]
|
||||
R --> M[ContextSnapshot]
|
||||
```
|
||||
|
||||
### 4.1 来源
|
||||
|
||||
Candidate 至少记录：
|
||||
|
||||
- 所有权边界、目标 Character（如有）和候选类型；
|
||||
- 精确来源引用，包括 Message/Block、KnowledgeDocument chunk 或 ToolCall 的 ID 与版本；
|
||||
- extractor、prompt、parser 和 policy 版本；
|
||||
- 候选正文、结构化时间、置信度、敏感度和创建时间；
|
||||
- 来源内容 hash 与候选 fingerprint，用于幂等和去重。
|
||||
|
||||
自动提取由 Message 完成后的 Outbox/Job 异步触发，不延长消息与 Run 的原子创建事务。重复消费相同来源与 extractor 版本必须返回同一候选或明确的去重结果。
|
||||
|
||||
ToolResult、网页、文件和模型输出都只是观察。它们可以产生 Candidate，但未经来源校验与 Policy 判定不能直接成为事实。
|
||||
|
||||
### 4.2 审批
|
||||
|
||||
- 用户显式创建可直接进入批准流程，但仍执行 Schema、所有权、敏感度和冲突检查。
|
||||
- 敏感资料、第三方个人信息、关系结论、高影响推断和隐式偏好默认需要人工确认。
|
||||
- 低风险自动候选只有在策略明确允许的白名单内容上才能自动批准，并必须附带撤销窗（写入后一段时间内一键撤销且不留检索痕迹）；策略版本必须进入审计。白名单外内容一律进入人工审核。
|
||||
- Candidate 的批准或拒绝是幂等命令；批准时在一个事务写 Memory/MemoryVersion、AuditEvent 和 OutboxEvent。
|
||||
- Candidate 不使用 `memory_status`；其生命周期与正式 Memory 分开定义。
|
||||
|
||||
### 4.3 纠正与并发
|
||||
|
||||
- 创建、纠正、取代和恢复均创建新的 MemoryVersion，不原地覆盖历史内容。
|
||||
- PATCH Memory 必须携带 `If-Match`；并发版本不匹配返回 `412 precondition_failed`。
|
||||
- 用户纠正优先绑定上一次召回的 Memory ID/Version ID，避免仅凭自然语言重新搜索后误改同名记忆。
|
||||
- 纠正后的旧版本保留谱系但不再参与召回；恢复旧内容也创建新版本。
|
||||
- 删除立即阻止读取与召回，清除所有版本中的原文及派生索引，只保留不含原文的最小墓碑和审计元数据。
|
||||
|
||||
### 4.4 归真作用域
|
||||
|
||||
记忆候选与手动入忆必须携带并保留来源界域 `canonical_scope`（见 [ADR-020](../decisions/README.md#adr-020对话三界与归真作用域)）：
|
||||
|
||||
- **真界**（`reality`）：按既有候选、审批与敏感度规则进入角色正式经历记忆。
|
||||
- **境界**（`world`）：归真只形成该世界的知识候选（境忆），进入 KnowledgeDocument 与世界实体体系，不进入角色真界经历记忆，也不影响现实关系数据。
|
||||
- **幻境**（`simulation`）：不自动形成长期记忆候选；用户可将启发、观点或假设手动入忆，强制标注性质（事实/观点/启发/假设），且仍走敏感度与确认规则——幻境不得成为绕过敏感审批的通道。
|
||||
|
||||
界域来源不可事后静默更改；跨界引用只提供来源，不改变目标记忆的作用域。
|
||||
|
||||
## 5. 衰减、有效期与整理
|
||||
|
||||
- `valid_from`/`expires_at` 表达事实有效期；过期版本在召回资格过滤阶段排除，但仍可按授权查看历史。
|
||||
- 衰减只影响排序或生成归档候选，不静默改写、删除或降低用户已确认事实的真实性。
|
||||
- 用户可固定重要记忆；固定状态仍不能绕过删除、撤权或有效期。
|
||||
- 去重、合并、冲突检测和归档由异步 Job 执行，任务带租约与幂等键；失败不影响权威版本和在线对话。
|
||||
- 自动整理结果仍是 Candidate 或新版本提案，不能绕过审批策略。
|
||||
|
||||
具体衰减函数和阈值必须通过评测确定，不在架构层虚构固定数值。
|
||||
|
||||
## 6. 检索管线
|
||||
|
||||
检索严格按以下顺序执行：
|
||||
|
||||
1. 根据 actor、Personal Domain/Workspace 和 Character 在数据库查询层限定可见集合；
|
||||
2. 过滤非 active、已过期、已撤权、已删除和被取代版本；
|
||||
3. 并行生成全文、语义和结构化关系候选；
|
||||
4. 按 Memory ID/Version ID 合并去重并重排；
|
||||
5. 应用敏感度、用途、数据驻留和 Run 权限策略；
|
||||
6. 按 token/条目/延迟预算选择进入上下文的结果；
|
||||
7. 将召回证据固化到 ContextSnapshot，供用户解释和受保护诊断。
|
||||
|
||||
禁止先跨域全量召回再在应用层过滤。向量分数不能替代授权、来源可信度或有效期判定。
|
||||
|
||||
公开 Memory Search 只返回调用者有权查看的命中项，并包含命中版本、来源、各检索通道分数、重排结果、召回说明和是否进入上下文。被权限过滤的对象不能以计数、分数或错误细节泄露存在性。
|
||||
|
||||
## 7. 上下文装配
|
||||
|
||||
上下文顺序沿用 [Agent 运行时](agent-runtime.md#7-上下文装配)：工具定义 → 稳定指令 → 当前分支消息 → 获准记忆与知识 → 动态运行上下文 → 当前输入。
|
||||
|
||||
ContextSnapshot 对每个候选记录：
|
||||
|
||||
- Memory ID、Version ID、来源引用和内容 hash；
|
||||
- 召回通道、原始分数、重排分数和策略结果；
|
||||
- 是否选中、未选原因、估算 token 和最终顺序；
|
||||
- 检索器、embedder、reranker、policy 与装配器版本。
|
||||
|
||||
ContextSnapshot 不保存隐藏推理。普通 Run API 只返回用户可理解的来源摘要；详细分数、排除原因和版本信息遵守 DiagnosticGrant。
|
||||
|
||||
## 8. 索引与故障语义
|
||||
|
||||
- PostgreSQL/SQLite 中的 Memory、MemoryVersion 和来源关联是权威事实；全文、pgvector 和图关系是可重建投影。
|
||||
- 权威事务通过 Outbox 驱动索引更新。索引延迟时，新版本可暂时降级为关系数据库检索，旧版本不得继续被召回。
|
||||
- 删除与撤权事件优先于普通重建任务；消费者按 event ID 幂等。
|
||||
- 无法证明索引已清除时，对目标 Memory fail closed，并记录待修复状态，不能继续返回旧结果。
|
||||
- 图投影只用于结构化关系检索；没有量化多跳收益前不引入专用图数据库。
|
||||
|
||||
## 9. 插件边界
|
||||
|
||||
Memory extractor、deduper、reranker、decay 和 context provider 可以由插件贡献。Core 始终负责：
|
||||
|
||||
- 身份、所有权和授权过滤；
|
||||
- Candidate/Version 状态迁移与事务；
|
||||
- 敏感度、审批、删除、审计和 Outbox；
|
||||
- 插件输入输出 Schema、资源预算和版本快照；
|
||||
- 最终 ContextSnapshot 与召回证据。
|
||||
|
||||
插件只能提出 Candidate、分数或排序，不能直接写权威 Memory、扩大作用域、读取未授权来源或阻止删除传播。
|
||||
|
||||
## 10. 评测与验收
|
||||
|
||||
WP-04 至少留下以下可重复证据：
|
||||
|
||||
- **写入质量**：事实、偏好、事件、关系的提取 precision/recall，以及敏感内容错误自动批准率；
|
||||
- **召回质量**：长对话、多会话、时间推理、冲突纠正和多跳关系的 Recall@K、MRR/nDCG 与最终问答正确率；
|
||||
- **安全正确性**：跨用户、跨角色、跨 Workspace、跨 Conversation/Branch/Run、已删除、已过期和已撤权内容的召回率必须为 0；Candidate、来源 Prompt Injection 和插件输出不能扩大 scope 或绕过审批；
|
||||
- **可追溯性**：每个进入上下文的 Memory 都能定位到当前版本和未删除来源；
|
||||
- **恢复能力**：索引全量重建、重复 Outbox、乱序消费和删除重放后结果一致；
|
||||
- **性能成本**：写入延迟、检索 p50/p95、候选数、rerank 时延、上下文 token 和单次召回成本。
|
||||
|
||||
LoCoMo、LongMemEval 等公开数据集可用于回归，不替代 Hunjing 自有的中文、多角色、分支、敏感审批、删除和越权测试集。阈值在实现前通过基线实验写入发布门，不引用外部项目宣传分数作为验收结果。
|
||||
|
||||
## 11. MemOS 采纳边界
|
||||
|
||||
参考基线：MemTensor/MemOS commit `28dfb4e7d3adad1c93fd5574675f913921367d36`，Apache-2.0。详细证据见[参考项目研究](../research/reference-projects.md#memos)。
|
||||
|
||||
采纳：类型化且可检查的记忆、来源追踪、分层检索、快速摄取后异步精炼、后台整理、基于已召回 ID 的纠正、可重复评测。
|
||||
|
||||
不采纳：把 MemCube 当作 Hunjing 授权边界、原地更新权威记忆、开放式 metadata 代替契约、运行时隐式建表、把向量/图存储作为事实源、保存或回放隐藏状态/KV cache、在 1.0 用参数记忆修改模型权重。
|
||||
@@ -0,0 +1,153 @@
|
||||
# 插件系统与生态
|
||||
|
||||
## 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。
|
||||
@@ -0,0 +1,107 @@
|
||||
# 系统架构
|
||||
|
||||
## 1. 逻辑架构
|
||||
|
||||
完整 1.0 由多端客户端、统一 API、领域模块、Agent/Plugin Runtime、媒体与实时处理、生态与交易模块以及隔离执行边界组成。逻辑边界是强约束，物理部署可按规模合并或拆分。
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
subgraph Clients
|
||||
WEB[Web]
|
||||
DESK[Tauri Desktop]
|
||||
MOB[Tauri Mobile]
|
||||
end
|
||||
|
||||
WEB & DESK & MOB --> EDGE[API and Realtime Edge]
|
||||
EDGE --> CORE[Core Application]
|
||||
CORE --> AGENT[Agent Runtime]
|
||||
CORE --> SOCIAL[Community and Collaboration]
|
||||
CORE --> MARKET[Marketplace and Ledger]
|
||||
CORE --> MEDIA[Media and Avatar Runtime]
|
||||
AGENT --> PLUGIN[Plugin Runtime]
|
||||
PLUGIN --> MODELS[Model Providers]
|
||||
PLUGIN --> TOOLS[Tools and MCP]
|
||||
CORE --> DATA[(Primary Data)]
|
||||
MEDIA --> OBJECTS[(Media Objects)]
|
||||
AGENT --> SANDBOX[Sandbox Workers]
|
||||
```
|
||||
|
||||
## 2. 模块职责
|
||||
|
||||
| 模块 | 职责 | 禁止承担 |
|
||||
| --- | --- | --- |
|
||||
| Identity & Domain | 登录、用户、设备、数据域、会话 | 角色人格和模型路由 |
|
||||
| Character | 角色、设定版本、关系、谱系、导入导出 | Provider 凭据和交易账 |
|
||||
| Conversation | 多模态消息、分支、引用、流式和压缩 | 决定长期记忆写入 |
|
||||
| Memory & Knowledge | 候选、版本、召回、纠正、删除、索引 | 覆盖角色基线 |
|
||||
| Agent Runtime | Agent/Run/Turn、计划、并行、暂停、取消、验收 | 绕过 Policy 执行工具 |
|
||||
| Model Gateway | Provider、逻辑模型、路由、流式、usage、成本 | 角色和社区业务 |
|
||||
| Plugin Runtime | Manifest、生命周期、Snapshot、Registry、SDK | 身份根策略和交易账 |
|
||||
| Tool & Sandbox | Schema、审批、幂等、隔离执行、结果净化 | 自行扩大能力范围 |
|
||||
| Media Pipeline | ASR/TTS、图像、Live2D、3D 资产处理 | 授予设备采集权限 |
|
||||
| Avatar Runtime | Live2D/3D 渲染、动作、表情、场景同步 | 修改权威角色数据 |
|
||||
| Device Capability | 文件、相机、麦克风、屏幕、位置和设备授权 | 后台常开采集 |
|
||||
| Community | 社交图、内容、互动、搜索、推荐、治理 | 支付结算和私密记忆 |
|
||||
| Collaboration | Workspace、RBAC、邀请、评审、版本、协同 | 跨 Workspace 隐式共享 |
|
||||
| Marketplace | 商品、许可、交付和版本可售性 | 直接改写支付账 |
|
||||
| Payment & Ledger | 订单、支付、退款、分成、余额、结算、对账 | 浮点金额和可变历史账 |
|
||||
| Policy & Moderation | 工具、插件、设备、内容、交易和年龄策略 | 执行业务副作用 |
|
||||
| Observability | Trace、Run 诊断、审计、成本、支持包 | 普通接口泄露敏感正文 |
|
||||
|
||||
## 3. 物理部署原则
|
||||
|
||||
开发期可在模块化单体中合并多数业务模块，但以下边界必须独立：
|
||||
|
||||
- Sandbox Worker：执行不可信代码；
|
||||
- Media Worker：处理重型媒体任务；
|
||||
- Realtime Gateway：SSE/WebSocket/语音会话；
|
||||
- Payment Webhook Consumer：验签、幂等和账务入账；
|
||||
- Object Storage：媒体和市场交付物；
|
||||
- Search/Index Worker：全文、向量和社区索引。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
C[Clients] --> E[Edge and Realtime]
|
||||
E --> A[Application API]
|
||||
A --> DB[(PostgreSQL)]
|
||||
A --> R[(Redis)]
|
||||
A --> S3[(S3-compatible Storage)]
|
||||
A --> W[Job Workers]
|
||||
W --> SB[Sandbox Pool]
|
||||
W --> GPU[Media or GPU Workers]
|
||||
W --> IDX[Search and Vector Index]
|
||||
A --> PAY[Payment Providers]
|
||||
PAY --> WH[Webhook Consumer]
|
||||
WH --> DB
|
||||
```
|
||||
|
||||
PersonalDomain 创建或迁移时绑定一个固定数据区域：权威数据、密钥、对象、索引和备份在该区域驻留，不因流量路由、故障转移或用户旅行自动跨区漂移；跨区只能走正式迁移协议。跨区模型处理按地区规则、数据敏感度和用户授权单独治理，且必须经用户明确披露与授权；高敏数据（含私箧）可完全禁止跨区模型处理。
|
||||
|
||||
自托管遥测默认关闭。本地开发可用 SQLite、本地对象和单 Worker；完整 1.0 正式云与社区/交易部署使用 PostgreSQL、Redis、对象存储和异步 Worker。向量库、图数据库与独立 Go 网关按量化规模选择，不因技术清单强制引入。灵台引擎默认进程内嵌入；满足独立扩缩容、故障域或资源隔离标准时可启用 `hunjing-lingtai-server` 独立服务形态（见[灵台引擎架构](lingtai-engine.md)）。
|
||||
|
||||
## 4. 客户端边界
|
||||
|
||||
- Web：完整社区、市场、创作、对话和管理体验。
|
||||
- Tauri Desktop：Web 能力加本地文件、屏幕、相机、麦克风、系统通知和沙箱桥接。
|
||||
- Tauri Mobile：iOS/Android 的相机、麦克风、文件、位置、通知和 Avatar 运行。
|
||||
- 客户端权限由平台权限和 Hunjing `device_grant` 双重约束。
|
||||
- 客户端不保存平台 Provider 密钥；离线缓存按用户和设备加密。
|
||||
|
||||
## 5. 数据与信任边界
|
||||
|
||||
1. 每次资源访问验证数据域、Workspace、角色、内容可见性和交易主体。
|
||||
2. Provider Header deny-by-default，仅 Adapter 白名单透传。
|
||||
3. 插件贡献能力；Core 决定加载、权限、审批、数据和审计。
|
||||
4. 未可信插件不进入主进程；没有可用隔离后端时拒绝执行。
|
||||
5. 支付 Provider Webhook 先验签和幂等，再写不可变账务记录。
|
||||
6. 社区公开内容、协作私有内容、角色私密数据和诊断数据使用不同访问策略。
|
||||
7. 设备采集默认关闭，逐能力展示状态并可即时撤回。
|
||||
8. 市场许可不自动授予插件执行权限、角色私密数据或设备能力。
|
||||
|
||||
## 6. 可靠性目标
|
||||
|
||||
1.0 目标值：核心文字相伴官方云 SLO 99.9%；权威数据 RPO 不高于 5 分钟、RTO 不高于 1 小时，以恢复演练而非配置声明证明；媒体与可重建索引可采用更宽目标但不阻塞权威恢复。SLI 口径、窗口与排除规则在发布门前定义并验证（见[发布门](../product/complete-1.0-scope.md#44-可靠性门)）。
|
||||
|
||||
## 7. 服务拆分标准
|
||||
|
||||
模块只有满足独立扩缩容、故障域、数据/密钥边界、团队发布节奏或量化瓶颈时才拆服务。拆分保持端口、事件和账务契约；不因语言偏好拆分。
|
||||
Reference in new issue
Block a user