📝 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,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。
|
||||
- 引擎产物进入诊断或日志前遵守脱敏规则；错误消息不包含请求正文、密钥或凭据。
|
||||
Reference in new issue
Block a user