chenxin
a39cec5287
- C++ 新增四模块（modules.cpp，19 个导出符号全部 hj_*）： 小周天 hj_stream：流会话（sequence/delta_index 单调）与 content.block.delta envelope 确定性编码（重放字节一致） 烛照 hj_policy：URL 协议白名单（拒 file/javascript/data）、路径授权根与 .. 段拒绝、幂等键非空≤128、四维决策表（autonomy×risk→allow/ask/deny，非法输入 deny fail-closed） 洛书 hj_plan：预算核算（达限/负数拒绝） 河图 hj_recall：确定性重排（词频×稳定排序，canonical JSON 输出；非法输入 PARSE_FAILED） - doctest 22 用例 20135 断言全绿（含每模块 golden 与确定性双跑） - Go 绑定（cgo 自包含编译引擎源码）：Engine RAII/TransformMarkdown/ValidateURL/ValidatePath/Decide/CheckBudget/RecallRerank；go test 3 用例通过（transform/rerank golden 与 C++ 字节一致） - Rust 绑定（bindgen 生成 + 安全包装）：Engine RAII（Drop 释放）、Error 枚举映射全部 HjStatus、Send/Sync（HjEngine 线程安全）；cargo test 3 用例通过（同 golden） - 三端（C++/Go/Rust）与 Python golden 一致：同一 markdown 输入在四端输出字节相同（跨端一致性首次全语言验证）
121 lines
4.7 KiB
C
121 lines
4.7 KiB
C
// Hunjing 灵台引擎公共头（Lingtai C ABI）。
|
||
// 契约真源：docs/contracts/lingtai-ffi.md；本文件是机器化前的稳定声明基线。
|
||
// 只导出 extern "C" 的 hj_* 符号与不透明句柄；异常、STL、RTTI 不跨越边界。
|
||
#ifndef HUNJING_LINGTAI_H
|
||
#define HUNJING_LINGTAI_H
|
||
|
||
#include <stddef.h>
|
||
#include <stdint.h>
|
||
|
||
#if defined(_WIN32)
|
||
#if defined(HJ_BUILDING)
|
||
#define HJ_API __declspec(dllexport)
|
||
#else
|
||
#define HJ_API __declspec(dllimport)
|
||
#endif
|
||
#else
|
||
#define HJ_API __attribute__((visibility("default")))
|
||
#endif
|
||
|
||
#ifdef __cplusplus
|
||
extern "C" {
|
||
#endif
|
||
|
||
// 当前 ABI major；major 不匹配时 hj_engine_new 拒绝初始化。
|
||
#define HJ_ABI_VERSION 1
|
||
|
||
// 不透明句柄：字段布局不进入契约。
|
||
typedef struct HjEngine HjEngine;
|
||
typedef struct HjBuffer HjBuffer;
|
||
|
||
// 稳定状态码（登记于契约第 5 节；新增不破坏兼容）。
|
||
typedef enum HjStatus {
|
||
HJ_OK = 0,
|
||
HJ_ERR_INVALID_ARGUMENT = 1,
|
||
HJ_ERR_OUT_OF_MEMORY = 2,
|
||
HJ_ERR_UNSUPPORTED_ABI = 3,
|
||
HJ_ERR_HANDLE_INVALID = 4,
|
||
HJ_ERR_REENTRANCY = 5,
|
||
HJ_ERR_PARSE_FAILED = 6,
|
||
HJ_ERR_LIMIT_EXCEEDED = 7,
|
||
HJ_ERR_POLICY_DENIED = 8,
|
||
HJ_ERR_SIGNATURE_INVALID = 9,
|
||
HJ_ERR_INDEX_CORRUPT = 10,
|
||
HJ_ERR_BUFFER_TOO_SMALL = 11,
|
||
HJ_ERR_INTERNAL = 12
|
||
} HjStatus;
|
||
|
||
// 返回引擎构建时的 ABI major。
|
||
HJ_API uint32_t hj_abi_version(void);
|
||
|
||
// 创建引擎句柄；宿主传入所需 major，不匹配返回 HJ_ERR_UNSUPPORTED_ABI 且不产生句柄。
|
||
// 成功时 *out_engine 非空。HjEngine 线程安全。
|
||
HJ_API HjStatus hj_engine_new(uint32_t required_abi_major, HjEngine **out_engine);
|
||
|
||
// 释放引擎句柄；句柄不在登记表（含二次释放）返回 HJ_ERR_HANDLE_INVALID，不崩溃。
|
||
HJ_API HjStatus hj_engine_free(HjEngine *engine);
|
||
|
||
// 释放引擎分配的缓冲；仅用于引擎产出的 HjBuffer。
|
||
HJ_API HjStatus hj_buffer_free(HjBuffer *buffer);
|
||
|
||
// 读取缓冲内容与长度；非法句柄返回 NULL / 0。
|
||
HJ_API const void *hj_buffer_data(const HjBuffer *buffer);
|
||
HJ_API size_t hj_buffer_len(const HjBuffer *buffer);
|
||
|
||
// 线程局部的最近一次错误消息（UTF-8、脱敏、不含正文与密钥）；下一次调用覆盖。
|
||
HJ_API const char *hj_last_error(void);
|
||
|
||
// ===== 脾神（hj_transform）：Markdown → canonical ContentBlock 确定性解析 =====
|
||
|
||
// 返回当前 parser version（稳定标识，随实现演进递增）。
|
||
HJ_API const char *hj_transform_version(void);
|
||
|
||
// 将 Markdown 规范化为 canonical ContentBlock JSON（键序确定、UTF-8）。
|
||
// 输出经 HjBuffer 返回，由 hj_buffer_free 释放；blocks 不含 id（由宿主生成）。
|
||
// 限额与非法 UTF-8 分别返回 HJ_ERR_LIMIT_EXCEEDED / HJ_ERR_INVALID_ARGUMENT。
|
||
HJ_API HjStatus hj_transform_markdown(
|
||
HjEngine *engine, const char *input, size_t input_len, HjBuffer **out);
|
||
|
||
// ===== 小周天（hj_stream）：确定性流事件编码 =====
|
||
|
||
// 流会话句柄：Run 内 sequence 与 block delta_index 计数（契约第 5 节）。
|
||
typedef struct HjStream HjStream;
|
||
|
||
HJ_API HjStatus hj_stream_new(HjEngine *engine, HjStream **out_stream);
|
||
HJ_API HjStatus hj_stream_free(HjStream *stream);
|
||
// 追加文本增量：输出 content.block.delta envelope 的 canonical JSON
|
||
// （含 sequence 与 delta_index，键序确定）；输出经 HjBuffer 返回。
|
||
HJ_API HjStatus hj_stream_append_delta(
|
||
HjStream *stream, const char *block_id, const char *text, size_t text_len,
|
||
HjBuffer **out);
|
||
HJ_API uint64_t hj_stream_sequence(const HjStream *stream);
|
||
|
||
// ===== 烛照（hj_policy）：确定性判定原语 =====
|
||
|
||
// URL 校验：仅 http/https；拒绝 file/javascript/data 等协议（契约 3.4）。
|
||
HJ_API HjStatus hj_policy_validate_url(const char *url);
|
||
// 路径约束：canonicalize 后必须位于 root 内；越界返回 HJ_ERR_POLICY_DENIED。
|
||
HJ_API HjStatus hj_policy_validate_path(const char *path, const char *root);
|
||
// 幂等键：非空且不超过 128 字符（契约第 6 节）。
|
||
HJ_API HjStatus hj_policy_validate_idempotency_key(const char *key);
|
||
// 决策表：autonomy（0=自省 1=循律 2=请命 3=禁域）× risk（0=只读 1=副作用 2=高影响）
|
||
// 返回 0=allow 1=ask 2=deny；非法输入返回 2。
|
||
HJ_API int hj_policy_decide(int autonomy_level, int risk_level);
|
||
|
||
// ===== 洛书（hj_plan）：预算核算 =====
|
||
|
||
// 已用 >= 上限 返回 HJ_ERR_LIMIT_EXCEEDED；负数参数 HJ_ERR_INVALID_ARGUMENT。
|
||
HJ_API HjStatus hj_plan_check_budget(int64_t used, int64_t maximum);
|
||
|
||
// ===== 河图（hj_recall）：确定性重排 =====
|
||
|
||
// 候选重排：输入 {"query_terms": [".."], "candidates": [{"id","text"}]}
|
||
// 输出按确定性得分（词频 × 简单位置权重）排序的 canonical JSON。
|
||
HJ_API HjStatus hj_recall_rerank(const char *candidates_json, HjBuffer **out);
|
||
|
||
#ifdef __cplusplus
|
||
} // extern "C"
|
||
#endif
|
||
|
||
#endif // HUNJING_LINGTAI_H
|