📝 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）
|
||||
@@ -0,0 +1,157 @@
|
||||
# 参考项目研究与采纳结论
|
||||
|
||||
> 研究日期：2026-09-02 至 2026-09-03。外部仓库会变化；下列 commit 用于固定研究证据，不表示运行依赖。
|
||||
|
||||
## 1. 结论
|
||||
|
||||
- 可以参考 deepseek-harness 的“一切皆插件”，但准确边界应是：**所有可扩展能力皆插件，不是所有系统职责皆插件。**
|
||||
- Core 必须保留最小、不可替换的安全和一致性职责：身份、授权、租户隔离、审批、事务、审计、插件加载验证和执行中止。
|
||||
- 1.0 业务核心采用模块化单体，不复制参考项目源码；同时完整实现双轨插件 Runtime、Registry、开发 SDK 和插件市场。
|
||||
- 只有 bundled Core plugin 可进主进程；第三方本地代码插件进入独立进程或容器，声明式/远程插件默认受限。
|
||||
- 角色卡只作为导入材料；记忆、身份和会话运行记录分别建模。
|
||||
- 模型网关职责必须在 1.0 完整实现；先作为明确模块交付，是否物理拆为独立 Go 服务由扩缩容、故障域和区域路由需求决定。
|
||||
|
||||
## 2. DeepSeek Harness 与 pi
|
||||
|
||||
### 2.1 DeepSeek Harness
|
||||
|
||||
研究基线：`dd6322d604e00eec1ba5e0c8541159906a21094a`；研究时最新：`4e84901e6471b79ec0338099867ebb4606d12bb5`。
|
||||
|
||||
可采纳证据：
|
||||
|
||||
- `docs/architecture.zh.md`：Cordis 插件提供 service、typed event 和 reversible effect；model adapter、tool registry、session log 与 agent loop 都能由插件贡献。
|
||||
- `packages/core/session/src/types.ts`：Session 使用类型化事件表达 turn、assistant message、tool call/result 和 request header。
|
||||
- `packages/extensions/cordis-host-runner/src/registry.ts`、`lifecycle.ts`：插件、Package、Run 有独立生命周期；注册和 effect 可撤销；加载失败清理已创建资源。
|
||||
- `packages/sandbox/sandbox/src/index.ts`：无可用隔离后端时 fail closed，禁止静默退化为未隔离执行。
|
||||
- `packages/subagent/subagent/src/child-agent.ts`：子 Agent 有深度上限，工具过滤、沙箱和审批策略只能收窄。
|
||||
|
||||
不照搬：
|
||||
|
||||
- Cordis 作为整个产品内核会引入高学习成本；本项目只吸收生命周期、依赖声明、可撤销注册和事件机制。
|
||||
- `node:vm` 不是安全隔离；参考项目源码也明确其 closure 仍可逃逸。未可信插件必须进独立进程/容器或远程协议。
|
||||
- Profile/Bundle/Patch 的完整配置层不是 1.0 必需形态；插件 Manifest、安装配置、权限授予和 Run Snapshot 已覆盖当前需求。
|
||||
|
||||
来源：<https://github.com/deepseek-ai/deepseek-harness>
|
||||
|
||||
### 2.2 pi
|
||||
|
||||
研究 commit：`96317e50b8d6e7f6d0e47fd29122baf1461c00f5`。
|
||||
|
||||
可采纳证据：
|
||||
|
||||
- `packages/coding-agent/src/core/extensions/loader.ts`：发现、加载、初始化、提交/丢弃和 runtime invalidation 分离。
|
||||
- `docs/extensions.md`：扩展可贡献 events、tools、commands；session replacement 会 shutdown、reload、rebind、start。
|
||||
- 项目本地扩展具有完整系统权限，只应在可信项目中启用；扩展异常记录后不必拖垮整个 Agent，但工具调用错误应 fail safe。
|
||||
|
||||
不照搬：
|
||||
|
||||
- 1.0 不从项目目录隐式加载任意代码；安装必须经过 Registry/本地包校验和明确权限确认。
|
||||
- UI 扩展进入 1.0，但使用声明式组件或隔离消息协议；快捷键和命令只有插件真实声明时注册，不作为所有插件的强制样板。
|
||||
|
||||
来源：<https://github.com/earendil-works/pi>
|
||||
|
||||
## 3. 角色与记忆项目
|
||||
|
||||
| 项目 | 采纳 | 不采纳 |
|
||||
| --- | --- | --- |
|
||||
| SillyTavern | 角色卡、角色/聊天/Persona/全局 Lore 作用域、Lorebook 触发与预算 | 角色卡等同身份；聊天向量等同长期记忆 |
|
||||
| Memory-Palace | L0/L1/L2 派生链、写入审查、快照、版本、衰减候选、混合检索 | 将其直接作为完整角色或会话系统 |
|
||||
| nocturne_memory | Namespace、Boot Context、版本链和人工清理 | 删除访问路径却保留正文仍称“永久删除” |
|
||||
| TencentDB-Agent-Memory | Conversation→Atomic Memory→Scenario→Profile 分层；Team/Agent/User/Session 作用域 | Profile 等同角色人格；仅靠作用域字段替代鉴权 |
|
||||
| mem0 | `user_id`/`agent_id`/`run_id` 过滤、过期和 History API | 把通用 Memory API 当作事实源或完整审计 |
|
||||
| MemOS | 类型化可检查记忆、来源链、快速摄取后异步精炼、后台整理、基于已召回 ID 的纠正和公开评测框架 | MemCube 等同授权域；原地更新权威记忆；开放 metadata 代替契约；把 KV cache、隐藏状态或权重适配当作 1.0 权威记忆 |
|
||||
| Artemis / NagaAgent | 角色配置与任务 Agent 分离、结构化事实抽取、SSE 工具循环 | 任务清理等同记忆删除；文件复制等同身份迁移 |
|
||||
|
||||
### MemOS
|
||||
|
||||
研究基线：`28dfb4e7d3adad1c93fd5574675f913921367d36`；许可证：Apache-2.0。
|
||||
|
||||
可采纳证据：
|
||||
|
||||
- `docs/en/open_source/home/architecture.md`：MOS、MemCube、Memory 与 Scheduler 分层；文本记忆可编辑、可追踪，官方建议从 GeneralTextMemory 起步，再按实测引入图或激活记忆。
|
||||
- `src/memos/memories/textual/item.py`：`SourceMessage` 保存消息、文档、文件和图像来源；文本记忆区分状态、版本、历史、置信度、会话和显式/隐式偏好。
|
||||
- `docs/en/open_source/modules/mem_reader.md`：Fast 模式先规范化、切片和索引，Fine 模式再用模型提取；支持后台从原始快照精炼为结构化记忆。
|
||||
- `docs/en/open_source/modules/mem_scheduler.md`：摄取、整理、偏好和反馈是异步任务，并记录队列、延迟、容量和操作日志。
|
||||
- `docs/en/open_source/modules/mem_feedback.md`：纠正优先携带上一轮已召回 Memory ID，以降低重新搜索误改；旧内容归档并保留版本关系。
|
||||
- `evaluation/`：以 LoCoMo、LongMemEval 等数据集比较长对话、时间和长期记忆能力，证明记忆系统必须有独立评测，而不能只验证向量查询成功。
|
||||
|
||||
不照搬：
|
||||
|
||||
- MemCube 的 user/cube 关系不足以表达 Hunjing 的 Personal Domain、Character、Workspace、发布与财务授权，不能成为本项目权限模型。
|
||||
- `BaseTextMemory.update()` 和部分实现的原地更新不满足 Hunjing 的不可变 MemoryVersion 与 ETag 并发要求。
|
||||
- `TextualMemoryMetadata(extra="allow")` 适合研究框架扩展，不适合作为公开稳定契约；Hunjing 新字段必须进入 OpenAPI/Schema。
|
||||
- MemOS 的 UserManager 运行时 `create_all`、同步 I/O 和本地 root 用户初始化不进入生产身份边界。
|
||||
- MemOS 的 WorkingMemory 特殊检索路径不能作为隔离范例；Hunjing 的临时上下文同样必须校验 Personal Domain/Workspace、Character、Conversation、Branch 与 Run。
|
||||
- MemOS 当前认证可由环境变量默认关闭，并使用内部 Header/共享秘密判断服务身份；Hunjing 不允许整体关闭认证，也不以用户可提交 Header 代替 workload identity/mTLS。
|
||||
- Activation/KV-cache 与 Parametric/LoRA memory 是模型运行优化或权重适配；1.0 不把它们称为用户可携、可纠正的权威长期记忆。
|
||||
- 外部 benchmark 宣传分数不作为 Hunjing 发布证据；必须固定数据集、版本、模型、检索配置和自有安全测试。
|
||||
|
||||
Hunjing 的采纳设计见[记忆与知识架构](../architecture/memory-and-knowledge.md)。
|
||||
|
||||
来源：
|
||||
|
||||
- <https://github.com/SillyTavern/SillyTavern>
|
||||
- <https://github.com/AGI-is-going-to-arrive/Memory-Palace>
|
||||
- <https://github.com/Dataojitori/nocturne_memory>
|
||||
- <https://github.com/TencentCloud/TencentDB-Agent-Memory>
|
||||
- <https://github.com/mem0ai/mem0>
|
||||
- <https://github.com/MemTensor/MemOS>
|
||||
- <https://github.com/momori777/Artemis>
|
||||
- <https://github.com/RTGS2017/NagaAgent>
|
||||
|
||||
## 4. 模型网关项目
|
||||
|
||||
aiway、octopus、new-api、metapi、axonhub 与 lens 共同证明了网关的成熟需求：供应商适配、逻辑模型、端点池、密钥、限流、用量、计费、流式转发和管理面。Hunjing 只采用这些职责，不复制任何一个项目的全部管理模型。
|
||||
|
||||
可追溯证据：
|
||||
|
||||
- aiway 的 `docs/gateway/{auth,monitoring,security}.md` 与 `gateway/src/handler/{auth,logger,response,routing}.rs` 分离认证、日志、响应和路由。
|
||||
- octopus 的 `internal/relay/{protocol,route,upstream,handler}.go` 与 `internal/server/` 展示协议、路由、上游和 API 边界。
|
||||
- new-api 的 `middleware/request-id.go`、`model/log.go`、`controller/audit.go`、`relay/helper/price.go` 覆盖 request ID、usage log、操作审计、缓存计价与预扣；它没有替代 W3C Trace Context。
|
||||
- metapi 的 `src/server/proxy-core/providers/headerUtils.ts`、`orchestration/upstreamRequest.ts`、`conductor/retryPolicy.ts` 展示 Header、上游请求和重试职责。
|
||||
- axonhub 的 `docs/en/getting-started/request-processing.md`、`guides/tracing.md`、`guides/cost-tracking.md` 明确 Request/Trace/Thread 层次、缓存 token、价格版本和可关闭正文存储。
|
||||
|
||||
1.0 必须实现至少 OpenAI-compatible 与 Anthropic Messages 两类协议、逻辑模型路由、流式、usage、成本、BYOK 和端点治理。以下条件决定是否把已完成的网关模块物理拆成独立服务，而不是决定能力是否进入 1.0：
|
||||
|
||||
- 三个以上运行服务都需要模型调用；
|
||||
- 网关和业务 API 需要独立扩缩容；
|
||||
- BYOK、费率、端点健康或区域路由成为独立运营职责；
|
||||
- Python 进程内实现已成为可测量瓶颈。
|
||||
|
||||
来源：
|
||||
|
||||
- <https://github.com/xgpxg/aiway>
|
||||
- <https://github.com/bestruirui/octopus>
|
||||
- <https://github.com/QuantumNous/new-api>
|
||||
- <https://github.com/cita-777/metapi>
|
||||
- <https://github.com/looplj/axonhub>
|
||||
- <https://github.com/dyedd/lens>
|
||||
|
||||
## 5. 标准与官方资料
|
||||
|
||||
- HTTP 字段名大小写不敏感；未知字段通常由代理转发，除非明确阻止：RFC 9110 §§5.1–5.3。
|
||||
- 新私有字段不使用 `X-` 前缀：RFC 6648 §3。
|
||||
- Bearer token 通过 `Authorization` 和 TLS 传输，不放 URI query：RFC 6750 §§2.1、2.3、5.3。
|
||||
- 分布式追踪使用 W3C `traceparent` / `tracestate`；其中不得放 PII 或业务秘密。`baggage` 只能传播低敏、低基数上下文，不能作为授权来源。
|
||||
- OpenTelemetry 的 GenAI 语义约定可用于统一 Provider、模型、操作、token 和 finish reason 的 Span 属性；业务 Run/Turn ID 仍由本项目契约定义。
|
||||
- Claude Prompt Cache 是严格前缀匹配，顺序为 `tools → system → messages`；usage 分开返回未缓存输入、缓存创建和缓存读取 token。
|
||||
- Claude client tool 以 `tool_use.id` 与 `tool_result.tool_use_id` 关联；并行调用的结果应在一个用户消息中返回。
|
||||
- OpenAI Responses/Chat 与 Anthropic Messages 的 usage 形状不同：OpenAI 可在 `input_tokens_details.cached_tokens` 报告缓存读取，Anthropic 使用 `cache_creation_input_tokens` 与 `cache_read_input_tokens`。Adapter 必须标准化但保留 `usage_source`，不能假设两者语义完全相同。
|
||||
- OpenAI 返回 `x-request-id`，并允许客户端提供 `X-Client-Request-Id`；Anthropic 返回 `request-id`，错误体带 `request_id`。这些是上游请求标识，不替代本地 `Hunjing-Request-ID` 或 `traceparent`。
|
||||
- 流式连接可能在 HTTP 200 后产生错误；首个用户可见流事件发出后，不允许静默切换 Provider 后重新生成另一份内容。
|
||||
|
||||
官方资料：
|
||||
|
||||
- <https://platform.openai.com/docs/api-reference>
|
||||
- <https://platform.openai.com/docs/api-reference/responses>
|
||||
- <https://platform.openai.com/docs/guides/prompt-caching>
|
||||
- <https://platform.claude.com/docs/en/build-with-claude/prompt-caching>
|
||||
- <https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview>
|
||||
- <https://platform.claude.com/docs/en/api/errors>
|
||||
- <https://www.w3.org/TR/trace-context/>
|
||||
- <https://www.w3.org/TR/baggage/>
|
||||
- <https://opentelemetry.io/docs/specs/semconv/registry/attributes/gen-ai/>
|
||||
- <https://opentelemetry.io/docs/specs/semconv/http/http-spans/>
|
||||
- <https://opentelemetry.io/docs/specs/semconv/url/>
|
||||
- <https://datatracker.ietf.org/doc/rfc6648/>
|
||||
- <https://datatracker.ietf.org/doc/rfc6750/>
|
||||
Reference in new issue
Block a user