0 Fork 0

Files

T

chenxin 42513d13c6 📝 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

2026-09-09 21:07:14 +08:00

6.9 KiB

Raw Blame History

Lingtai C ABI

灵台引擎进程内形态的公共契约。本文件是 hj_* 稳定符号、类型与错误码的单一登记处；机器化前以本文件为命名基线，机器化后以 include/hunjing/lingtai.h 与生成 Schema 为准。独立服务形态（gRPC）契约见 Lingtai Service，两种形态共用同一核心与语义；架构语义见灵台引擎架构。

1. 适用范围与稳定性

消费方：官方 Python/Go/Rust 绑定与经部署者授权的第三方宿主。这是公开稳定契约，适用与 Native API 相同的演进纪律：向后兼容的新增函数不升 major；修改既有签名或语义必须升 major。
HjStatus 错误码同时是服务形态错误映射的源枚举（映射表见 Lingtai Service）；新增错误码须同步评估两种形态。
凭据、用户内容与密钥不经 ABI 传递；引擎无网络与持久化能力（只读索引除外），不存在凭据通道。
本 ABI 不是 HTTP 分面，不与 api.<domain>/v1 的资源契约混用；引擎产物的字段与枚举复用本目录既有契约。

2. 命名与符号

对象	规则	示例
函数	`hj_` 前缀 + `snake_case`	`hj_engine_new`
不透明句柄类型	`Hj` 前缀	`HjEngine`、`HjStream`
状态码枚举	`HJ_OK` / `HJ_ERR_*`	`HJ_ERR_PARSE_FAILED`
宏	`HJ_` 前缀大写	`HJ_ABI_VERSION`
库文件	`libhunjing`	`libhunjing.so` / `.dylib` / `.dll`
公共头	单一头文件	`include/hunjing/lingtai.h`

所有导出函数为 extern "C"；结构体不透明（仅前向声明），字段布局不进入契约。
除 hj_* 外不导出任何符号；C++ 类、STL 类型、异常与 RTTI 不得跨越边界。

2.1 模块标识

六个子系统的稳定模块名（职责详见灵台引擎架构，文化名见文化语言体系）：

模块	职责摘要
`hj_core`	版本协商、句柄生命周期、状态转换校验、事件序
`hj_stream`	流事件编码、增量去重、节流与重放缓冲
`hj_plan`	计划 DAG 校验、预算核算、上下文装配计算
`hj_recall`	只读离线混合索引、重排打分、多路合并
`hj_transform`	Markdown 规范化为 canonical ContentBlock
`hj_policy`	Schema/路径/URL 校验、验签、幂等键、决策评估

3. 版本协商

#define HJ_ABI_VERSION 1
uint32_t hj_abi_version(void);

HJ_ABI_VERSION 为当前 major；hj_abi_version() 返回引擎构建时的 major。
宿主在 hj_engine_new 传入所需 major；不一致时返回 HJ_ERR_UNSUPPORTED_ABI 且不产生句柄，禁止静默降级运行。
引擎实现与 parser 版本可经 hj_engine_build_info 查询，供宿主写入 PluginSnapshot、诊断与审计。

4. 生命周期与内存

引擎句柄：hj_engine_new / hj_engine_free；HjEngine 线程安全。
会话句柄（HjStream、HjTransform、HjRecallSession、HjPolicyEval）：从 HjEngine 派生，单线程亲和；每个句柄有对应 hj_*_free。
缓冲区：引擎分配的输出缓冲由 hj_buffer_free 释放；hj_buffer_data/hj_buffer_len 读取内容。宿主不得 free 引擎指针，引擎不得持有返回后的宿主指针。
字符串：UTF-8；输入 NUL 结尾或指针加长度，输出指针加长度。
二次释放、句柄复用与跨线程使用会话句柄返回 HJ_ERR_HANDLE_INVALID，不得崩溃。

5. `HjStatus` 错误码

枚举值	语义	典型映射
`HJ_OK`	成功	—
`HJ_ERR_INVALID_ARGUMENT`	参数为空、编码非法或超长	`validation_failed`
`HJ_ERR_OUT_OF_MEMORY`	引擎分配失败	`internal` + 告警
`HJ_ERR_UNSUPPORTED_ABI`	major 版本不匹配	启动失败
`HJ_ERR_HANDLE_INVALID`	句柄非法、已释放或跨线程	`internal`
`HJ_ERR_REENTRANCY`	回调内再入引擎	`internal`
`HJ_ERR_PARSE_FAILED`	输入无法规范解析	`validation_failed`
`HJ_ERR_LIMIT_EXCEEDED`	长度/深度/节点/预算超限	`payload_too_large` / `limit_exceeded`
`HJ_ERR_POLICY_DENIED`	策略判定拒绝	`permission_denied` / `forbidden`
`HJ_ERR_SIGNATURE_INVALID`	验签失败或时间窗外的重放	`invalid_signature`
`HJ_ERR_INDEX_CORRUPT`	只读索引校验失败	启动失败，要求重建索引
`HJ_ERR_BUFFER_TOO_SMALL`	输出缓冲不足（可重试扩容）	—
`HJ_ERR_INTERNAL`	引擎内部错误	`internal`

新增错误码不破坏兼容；绑定层必须对未知码走失败分支，不得当作成功。
hj_last_error 返回线程局部的最近错误消息（UTF-8、脱敏、不含正文与密钥）；下一次引擎调用覆盖。

6. 数据边界

ContentBlock、流事件与策略判定输入输出使用本目录既有 JSON Schema（统一富内容与流式协议）；引擎输出 canonical JSON：键序确定、无空白、UTF-8，保证 content hash 可跨端复现。
媒体字节（图片摘要、向量、波形）经 hj_buffer 二进制传递，不进入 JSON。
限额（单消息 Block 数、源码长度、节点数、嵌套深度）由宿主配置传入并在 Schema 中保留硬上限；超限返回 HJ_ERR_LIMIT_EXCEEDED，引擎不得为完成解析而放宽限额。

7. 回调约定

typedef void (*HjStreamCallback)(void *user_data,
                                 const char *event_json,
                                 size_t event_len);

回调在触发调用的同一线程同步执行；回调内禁止调用任何 hj_* 函数（HJ_ERR_REENTRANCY）。
event_json 仅在回调期间有效；宿主需要保留必须复制。
回调抛出的宿主异常不得穿透引擎：绑定层捕获后中止本次调用并返回错误。

8. 官方绑定矩阵

语言	包名（建议）	实现	错误映射
Python	`hunjing-lingtai`	nanobind 薄封装，no-gil 标记长计算	`HunjingEngineError` 层级
Rust	`hunjing-lingtai-sys` + `hunjing-lingtai`	bindgen 生成 + 安全包装（RAII、`Result`）	`LingtaiError` enum
Go	`hunjing/lingtai`	cgo，绑定集中在单一包	`errors` 哨兵值

绑定层不缓存权威状态、不补写业务语义；三端输出必须字节一致（golden 测试）。
绑定的内存错误（泄漏/双重释放）由各端测试矩阵覆盖，属于发布门。

9. 禁令清单

不得以宿主语言重新实现已登记的引擎能力作为回退路径。
不得在 ABI 边界传递凭据、Cookie、诊断令牌或用户正文以外的敏感负载。
不得链接未登记的引擎内部符号或依赖头文件未声明的行为。
不得绕过 hj_engine_new 的版本协商直接 dlsym 猜测符号。
不得将引擎错误消息原样透传给最终用户；错误本地化由宿主完成。

6.9 KiB Raw Blame History Unescape Escape