hunjing/docs/architecture/lingtai-engine.md

灵台引擎架构

决策依据：ADR-016、ADR-017。ABI 稳定值登记于 Lingtai C ABI，独立服务契约见 Lingtai Service。文化名见文化语言体系。

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 → 签名 → 预算"分层递进，单层拒绝即短路返回，对应纵深防御理念。

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. 部署形态

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。
• 适用：重型解析/检索需要独立扩缩容与资源隔离；同一部署内多宿主（API、Worker、网关）共享引擎容量；引擎需独立升级发布；跨机器集中计算。
• 服务只在部署内部网络监听，经 mTLS/工作负载身份认证；不进入公共 API 分面，不经网关对外暴露。
• 启用标准沿用系统架构的服务拆分标准；不满足标准时保持嵌入形态。

3.3 形态选择与演化

• 默认嵌入；满足独立扩缩容、故障域、资源隔离或多宿主共享证据时切换或混用（例如服务端用服务形态、端侧用嵌入形态）。
• 客户端代码面向"引擎 Port"编程（进程内与服务两个实现），切换形态不改业务语义，只改部署配置；Port 定义见内部端口的组织方式。
• 前端 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 的输入输出即 统一富内容与流式协议 定义的 Block 与事件 JSON Schema；引擎输出 canonical JSON（键序确定），供 hash 与跨端一致性测试。
• 状态机权威不变：Run/Turn/ModelCall 的持久化与恢复遵循 Agent 运行时；hj_core 只校验状态迁移合法性并分配 sequence，不存储权威状态。
• 检索分工：服务端权威检索仍是 PostgreSQL 全文与 pgvector（记忆与知识架构）；hj_recall 服务于端侧离线与重排计算，索引是可重建投影，删除与授权变化随宿主重建传播。
• 策略归属：审批流、用户确认与 Policy 最终裁决遵循 安全与诊断访问；hj_policy 提供确定性判定原语与高速规则评估，不发起 I/O、不绕过审批。
• 插件边界：插件系统 的 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）。
• 平台矩阵：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。
• 引擎产物进入诊断或日志前遵守脱敏规则；错误消息不包含请求正文、密钥或凭据。