📝 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,141 @@
|
||||
# 灵台引擎研究与采纳结论
|
||||
|
||||
> 研究日期：2026-09-03（同日更新七神调研）。外部资料会变化；本文固定的是架构证据与文化出处，不表示任何运行依赖。本研究的用途边界：学习公开讨论中的组件组织架构理念，用于 Hunjing 自身核心库设计；不实现、不协助实现任何针对抖音或第三方系统的签名生成、设备指纹伪造或风控对抗功能。
|
||||
|
||||
## 1. 结论
|
||||
|
||||
- 采纳"抖音六神/七神"的**组织架构理念**：性能与安全敏感核心以 C/C++ 编译为原生库，宿主语言只保留薄入口；通过极小的稳定 ABI 暴露能力；多个子系统各司其职、由一个中枢统一协调；同一核心在多端（服务端、桌面、移动）复用。
|
||||
- 七神（六神加 X-Perseus）的核心增量理念：**"并非单一算法，而是一组相互关联、层层递进的校验参数"**——分层递进防御；**单一稳定入口**（native 层一个 `leviathan` 风格入口按输入输出整套结果）；**神有新陈代谢而入口稳定**（旧神弱化为短签名、新神接管核心校验，但调用面不变）；**同一核心多形态交付**（进程内调用、RPC 独立服务、脱离真机的模拟执行三种形态并存）。
|
||||
- 不采纳其**功能与对抗手段**：Hunjing 不做设备指纹采集、反爬签名或混淆对抗；Hunjing 是开放、可审计、可自托管的平台，安全边界靠架构隔离与显式授权，不靠对抗自己部署者的混淆。
|
||||
- 子系统文化命名承接 Hunjing 旧版（main 分支）已确立的"灵台/九枢"血脉：**灵台**为认知运行域与诸枢之居，作引擎总名；六模块取 **太一、小周天、洛书、河图、烛照** 五个旧概念加补位词 **陶钧**。**文化命名跟随自身职责与经典映射，不跟随外部体系的神数与版本数字**——业界从"六神"演进为"七神"是其自身的新陈代谢，Hunjing 只吸收其理念，不复制其数字。文化名只进入品牌与文档层，工程标识使用中性英文 `hj_*`。
|
||||
- C++ 核心以**稳定 C ABI 为进程内唯一真源**；以 **gRPC 服务面**为独立运行形态的契约；Python、Go、Rust 在两种形态下都经官方薄绑定/客户端消费。C++ ABI（不同编译器/标准库版本）不作为稳定接口。
|
||||
- 相关决策见 [ADR-016](../decisions/README.md#adr-016灵台引擎采用-c-核心与稳定-c-abi)与 [ADR-017](../decisions/README.md#adr-017灵台引擎双形态部署)，架构见[灵台引擎架构](../architecture/lingtai-engine.md)，ABI 契约见 [Lingtai C ABI](../contracts/lingtai-ffi.md)，服务契约见 [Lingtai Service](../contracts/lingtai-service.md)。
|
||||
|
||||
## 2. 抖音六神/七神原生架构证据
|
||||
|
||||
### 2.1 是什么
|
||||
|
||||
"六神"是中文逆向工程社区对抖音/TikTok 客户端请求签名与设备风控 native 组件体系的通称；随版本加入 X-Perseus 后社区改称"七神"。其外在表现是一组以神名命名的请求头，核心实现集中在 native 动态库（近年为 `libmetasec_ml.so`，更早版本位于 `libcms.so` 等）。
|
||||
|
||||
公开资料中较一致的七神构成（随版本浮动，仅供架构参考）：
|
||||
|
||||
| 神名 | 社区公开描述的职责 |
|
||||
| --- | --- |
|
||||
| X-Khronos | 时间戳维度，防请求重放 |
|
||||
| X-Gorgon | 请求 URL/Body 签名，防内容篡改 |
|
||||
| X-Ladon | 设备环境/短签名，随版本弱化 |
|
||||
| X-Argus | 设备环境与完整性，随版本弱化 |
|
||||
| X-Helios | 主要校验参数之一（新版强化） |
|
||||
| X-Medusa | 设备参数与风控信息载体（新版强化） |
|
||||
| X-Perseus | 第七神，新版新增校验维度 |
|
||||
|
||||
### 2.2 可采纳的架构证据
|
||||
|
||||
- **薄宿主入口**：Java/Kotlin 层只保留极少的入口类与方法（公开分析指出的单一 native 入口风格），签名计算、协议编排全部位于 native 层。
|
||||
- **单一稳定总入口**：native 层以一个稳定入口函数按版本与输入产出整套结果，具体"神"的内部分工与增减不外泄到调用面。
|
||||
- **分层递进校验**：时间、内容完整性、设备环境、风控信息各自独立又层层递进，构成纵深防御；单点被绕过不等于体系失效。
|
||||
- **多神协同与新陈代谢**：组件分别覆盖不同校验维度，相互独立又共同产出完整凭证；随威胁演化，旧组件权重下降、新组件接管，但对外契约稳定。
|
||||
- **一套核心多形态交付**（社区三阶段实践印证）：进程内直接调用（App 自身）；把核心包装为本地服务经 RPC 供外部调用；在受控运行时中模拟执行以脱离原始宿主。同一核心计算逻辑可以更换宿主形态而不重写。
|
||||
- **多端复用**：同一 C/C++ 核心覆盖 Android、iOS 与服务端校验，宿主语言差异被隔离在绑定层。
|
||||
- **版本与自校验意识**：组件携带版本信息并对自身完整性做校验，防止被替换后静默产出错误结果。
|
||||
- **性能路径下沉**：高频执行（每次请求）的加密与编码全部 native 化，宿主语言只做 I/O 编排。
|
||||
|
||||
### 2.3 不照搬
|
||||
|
||||
- **功能本身**：请求签名对抗、设备指纹、风控数据采集与 Hunjing 的产品域无关，且与"设备采集默认关闭、显式授权、可即时撤回"的设备原则冲突。
|
||||
- **OLLVM 混淆与反调试对抗**：Hunjing 的安全边界依赖进程/容器隔离、权限审批和审计；对部署者隐藏实现与开放、可自托管、可审计的目标冲突。符号最小化在 Hunjing 中只作为 API 卫生实践（`-fvisibility=hidden` + 仅导出 `hj_*`），不作为对抗手段。
|
||||
- **`X-` 前缀请求头**：原体系的 `X-Gorgon` 等沿用 2012 年前的旧惯例；Hunjing 公共契约遵循 RFC 6648，新私有字段不使用 `X-` 前缀（见[参考项目研究](reference-projects.md)第 5 节）。
|
||||
- **神名进入协议值**：文化名只做品牌叙事；ABI 符号、模块名和错误码使用中性英文，遵循 [ADR-014](../decisions/README.md#adr-014文化名只属于品牌展示)。
|
||||
- **对抗式的"模拟执行逃逸"**：社区第三阶段（脱离宿主模拟执行）在 Hunjing 语境下的正当对应物是"引擎可在任意宿主进程/服务形态中运行"，因为引擎本就属于部署者自己；不存在对抗关系。
|
||||
|
||||
## 3. 道家文化出处：灵台与六模块
|
||||
|
||||
Hunjing 旧版（main 分支）以"灵台"为认知运行域、九枢居其内；本引擎承接该血脉，总名**灵台**，六模块各取其义。
|
||||
|
||||
经典出处：
|
||||
|
||||
- **灵台**：《庄子·庚桑楚》"不可内于灵台"，注家释为心；旧版九枢（灵核、太一、司命、烛照、河图、洛书、息壤、百工、天工阁）皆居灵台之内——中枢统摄诸模块。
|
||||
- **太一**：《吕氏春秋·大乐》"太一出两仪，两仪出阴阳"；道家至高统摄，喻"唯一、统一"——单一稳定总入口。旧版太一承载目标统摄。
|
||||
- **洛书**：《易·系辞上》"河出图，洛出书，圣人则之"；九宫定序，喻规划布局。旧版洛书即 Planner（计划）。
|
||||
- **河图**：同出《易·系辞》；旧版河图即 World Model（世界认知），并明言"图库是河图投影，不是事实源"——与本项目"检索索引是可重建投影"语义同构。
|
||||
- **小周天**：内丹家以周天喻气机循环运转；旧版小周天指一次 Run 的认知闭环——流式增量与事件序的运转意象。角色层面的"大周天"（自我评估演化循环）另见[文化语言体系](../product/cultural-language.md)，不属引擎模块。
|
||||
- **烛照**：旧版九枢之一，司观察与反思；取"烛照明察"义——校验与判定。
|
||||
- **陶钧**：《文心雕龙·神思》"陶钧文思，贵在虚静"；转轮陶冶、化材料为器——内容规范化转造。
|
||||
|
||||
模块映射：
|
||||
|
||||
| 文化名 | 直白解释 | 承接/出处 | 工程模块 |
|
||||
| --- | --- | --- | --- |
|
||||
| 太一 | 引擎中枢：单一稳定入口、版本协商、句柄、状态机校验、事件序 | 旧版九枢"太一"；《吕氏春秋》 | `hj_core` |
|
||||
| 小周天 | 流式引擎：增量、节流、去重、重放缓冲 | 旧版"小周天=Run 闭环"；内丹周天 | `hj_stream` |
|
||||
| 洛书 | 计划引擎：DAG 校验、预算核算、上下文装配计算 | 旧版九枢"洛书=Planner"；《易·系辞》 | `hj_plan` |
|
||||
| 河图 | 检索引擎：离线混合索引、重排打分、结果合并 | 旧版九枢"河图=World Model"；《易·系辞》 | `hj_recall` |
|
||||
| 陶钧 | 内容引擎：Markdown 规范化为 canonical ContentBlock | 《文心雕龙》"陶钧文思"（补位新词） | `hj_transform` |
|
||||
| 烛照 | 策略引擎：Schema/路径/URL 校验、验签、幂等键、分层决断 | 旧版九枢"烛照=观察反思" | `hj_policy` |
|
||||
|
||||
旧版九枢中的司命、息壤、百工、天工阁、灵核已在当前分支分别对应司命台（治理域）、息壤（记忆域）、百工坊（插件域）、天工阁（Agent 域）与角色人格层，不重复用于引擎模块。"单一稳定入口"理念由太一（`hj_core`）承载：`hj_core` 是唯一对外句柄根与跨形态（进程内/服务）统一入口。文化名与直白解释按[文化语言体系](../product/cultural-language.md)的双层规则展示；`hj_*` 是唯一稳定工程值。
|
||||
|
||||
## 4. C++ 多语言绑定与双形态选型
|
||||
|
||||
目标：一个 C++ 核心库，支持**进程内嵌入**（Python/Rust/Go 宿主经 C ABI）与**独立服务运行**（同一核心包成网络服务，供本部署内多宿主或跨机器消费）两种形态，同一份核心代码与语义。
|
||||
|
||||
### 4.1 为什么以 C ABI 为进程内真源
|
||||
|
||||
- C ABI 是 Python（ctypes/cffi/pybind11/nanobind）、Go（cgo）、Rust（bindgen）三方都可消费的唯一公共分母；C++ ABI 本身不跨编译器稳定。
|
||||
- 头文件 `include/hunjing/lingtai.h` 可被三个生态的绑定生成器直接解析，避免手写三份漂移的声明。
|
||||
- 绑定层保持薄：仅做类型转换、内存托管和错误映射，不复制业务语义。
|
||||
|
||||
### 4.2 独立服务形态为什么用 gRPC
|
||||
|
||||
- 三语言一等客户端（官方生成器），天然匹配"同一契约、多宿主消费"。
|
||||
- 双向流原语覆盖 `hj_stream` 的服务化语义；HTTP/JSON+SSE 组合在跨语言客户端生成、二进制负载与连接复用上成本更高。
|
||||
- 服务是部署内部组件（非公开 API 分面），不进入 OpenAPI 公共契约；proto 作为该内部契约真源登记于 `docs/contracts/`，与 JSON Schema 的字段语义保持同源映射。
|
||||
- 社区"RPC 远程调用"阶段的实践证明：把原生核心包成本地服务、以稳定接口供外部调用，是同一核心的成熟第二形态。
|
||||
|
||||
### 4.3 各语言消费方式
|
||||
|
||||
| 语言 | 进程内形态 | 服务形态 |
|
||||
| --- | --- | --- |
|
||||
| Python | nanobind 薄封装（备选 pybind11） | 生成的 gRPC stub |
|
||||
| Go | cgo 绑定 | 生成的 gRPC stub |
|
||||
| Rust | bindgen `-sys` + 安全包装 | `tonic` + 生成的 stub |
|
||||
|
||||
否决的替代方案：
|
||||
|
||||
- **各语言独立实现核心**：确定性 parser 与策略判定必须全端一致，多份实现必然漂移，违反"单一真源"。
|
||||
- **pyo3 / UniFFI**：均只覆盖部分语言，无法同时服务 Go。
|
||||
- **服务形态复用公共 HTTP 分面**：会把内部计算面混入对外 API 契约，破坏分面纪律与稳定性承诺。
|
||||
- **Rust 作为核心语言**：Python/Go 消费 Rust cdylib 同样要经 C ABI，且 C++ 音视频/图形生态衔接成本更低；记录于 ADR-016。
|
||||
|
||||
### 4.4 稳定性策略
|
||||
|
||||
- 进程内：只导出 `extern "C"` 函数与不透明句柄；`HJ_ABI_VERSION` 协商；结构体不透明（见 [Lingtai C ABI](../contracts/lingtai-ffi.md)）。
|
||||
- 服务：gRPC 按 protobuf 语义化演进（不改既有字段编号与类型）；服务与进程内两种形态的语义一致性由同一 golden 测试集约束。
|
||||
- 新增计算能力默认在两种形态同时暴露；仅在单形态有意义的能力（如端侧离线索引）必须显式登记形态边界。
|
||||
|
||||
## 5. 来源
|
||||
|
||||
抖音六神/七神架构（公开技术分析，仅作组织架构证据）：
|
||||
|
||||
- <https://zhuanlan.zhihu.com/p/2013639720807183181>（抖音七神协议逆向踩坑记录）
|
||||
- <https://blog.csdn.net/2503_90751938/article/details/161750852>（七神算法协议分层描述）
|
||||
- <https://blog.csdn.net/2503_90751938/article/details/161145893>（七神组成与演进）
|
||||
- <https://oacia.dev/douyin-6shen-init/>（六神字符串解密与 so 结构分析）
|
||||
- <https://bbs.kanxue.com/thread-259906.htm>（x-gorgon 入口定位笔记）
|
||||
- <https://zhuanlan.zhihu.com/p/42685936>（抖音签名算法逆向杂谈）
|
||||
- <https://www.ctfiot.com/310073.html>（X-Medusa native 签名分析）
|
||||
|
||||
道家与文论经典：
|
||||
|
||||
- <https://zh.wikisource.org/zh-hans/莊子/庚桑楚>（灵台出处，维基文库）
|
||||
- <https://ctext.org/lv-shi-chun-qiu/da-yue/zh>（太一出处，《吕氏春秋·大乐》）
|
||||
- <https://zh.wikisource.org/zh-hans/易經/繫辭上>（河图洛书出处，《易·系辞上》）
|
||||
- <https://zh.wikisource.org/zh-hans/文心雕龍/神思>（陶钧出处，《文心雕龙·神思》）
|
||||
|
||||
绑定与 RPC 工具链（实现期按 ADR 复核版本与许可）：
|
||||
|
||||
- <https://github.com/wjakob/nanobind>（nanobind）
|
||||
- <https://pkg.go.dev/cmd/cgo>（cgo）
|
||||
- <https://github.com/rust-lang/rust-bindgen>（bindgen）
|
||||
- <https://grpc.io/docs/what-is-grpc/>（gRPC）
|
||||
- <https://github.com/hyperium/tonic>（Rust gRPC，tonic）
|
||||
Reference in new issue
Block a user