✨ feat: 灵台引擎五神齐备与 Go/Rust 官方绑定(WP-15)

- 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 输入在四端输出字节相同(跨端一致性首次全语言验证)
This commit is contained in:
chenxin committed 2026-09-12 13:54:12 +08:00
1 parent 99a7789432
commit a39cec5287
15 files changed
+1205 -3

No files matched your search

+228
View File
@@ -0,0 +1,228 @@
# This file is automatically @generated by Cargo.
# It is not intended for manual editing.
version = 4
[[package]]
name = "aho-corasick"
version = "1.1.5"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "c982642fa9e8606056828ee9a8505737230110bb1099153c79efe865c59d12ba"
dependencies = [
"memchr",
]
[[package]]
name = "bindgen"
version = "0.71.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "5f58bf3d7db68cfbac37cfc485a8d711e87e064c3d0fe0435b92f7a407f9d6b3"
dependencies = [
"bitflags",
"cexpr",
"clang-sys",
"itertools",
"log",
"prettyplease",
"proc-macro2",
"quote",
"regex",
"rustc-hash",
"shlex",
"syn",
]
[[package]]
name = "bitflags"
version = "2.13.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "3ded4057c258ba199e2d26386d3af3780957ecaee6c4ef4041c6b4b8b97c0b06"
[[package]]
name = "cexpr"
version = "0.6.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "6fac387a98bb7c37292057cffc56d62ecb629900026402633ae9160df93a8766"
dependencies = [
"nom",
]
[[package]]
name = "cfg-if"
version = "1.0.4"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801"
[[package]]
name = "clang-sys"
version = "1.9.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "157a8ba7b480713b56f4c09fd13fc3e0a22a5dfab8097ba61cbc5feef950788a"
dependencies = [
"glob",
"libc",
"libloading",
]
[[package]]
name = "either"
version = "1.18.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "252afb9ae5eaa683babdc6a068b3f5726eb19e05070c731f9b2a23a7c3e8ed34"
[[package]]
name = "glob"
version = "0.3.4"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "e4eba85ea1d0a966a983acd07deee566e67395d2d96b6fb39e62b5a833f1eb0b"
[[package]]
name = "hunjing-lingtai"
version = "0.1.0"
dependencies = [
"bindgen",
]
[[package]]
name = "itertools"
version = "0.13.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "413ee7dfc52ee1a4949ceeb7dbc8a33f2d6c088194d9f922fb8318faf1f01186"
dependencies = [
"either",
]
[[package]]
name = "libc"
version = "0.2.189"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "3eaf3ede3fee6db1a4c2ee091bf8a8b4dccdc6d17f656fb07896ee72867612f2"
[[package]]
name = "libloading"
version = "0.8.9"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "d7c4b02199fee7c5d21a5ae7d8cfa79a6ef5bb2fc834d6e9058e89c825efdc55"
dependencies = [
"cfg-if",
"windows-link",
]
[[package]]
name = "log"
version = "0.4.34"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "f9f8bd3e56ce4dfc153cf470fffbfa98c7620958b312ca5c3a4b8d5181fd13c6"
[[package]]
name = "memchr"
version = "2.8.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98"
[[package]]
name = "minimal-lexical"
version = "0.2.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "68354c5c6bd36d73ff3feceb05efa59b6acb7626617f4962be322a825e61f79a"
[[package]]
name = "nom"
version = "7.1.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "d273983c5a657a70a3e8f2a01329822f3b8c8172b73826411a55751e404a0a4a"
dependencies = [
"memchr",
"minimal-lexical",
]
[[package]]
name = "prettyplease"
version = "0.2.37"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "479ca8adacdd7ce8f1fb39ce9ecccbfe93a3f1344b3d0d97f20bc0196208f62b"
dependencies = [
"proc-macro2",
"syn",
]
[[package]]
name = "proc-macro2"
version = "1.0.107"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9"
dependencies = [
"unicode-ident",
]
[[package]]
name = "quote"
version = "1.0.47"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001"
dependencies = [
"proc-macro2",
]
[[package]]
name = "regex"
version = "1.13.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "f020237b6c8eed93db2e2cb53c00c60a8e1bc73da7d073199a1180401450218d"
dependencies = [
"aho-corasick",
"memchr",
"regex-automata",
"regex-syntax",
]
[[package]]
name = "regex-automata"
version = "0.4.18"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "ad8553b9b26413251cbf30e620595c7a41b3887f03da04579c0e6b0d6a06b4b2"
dependencies = [
"aho-corasick",
"memchr",
"regex-syntax",
]
[[package]]
name = "regex-syntax"
version = "0.8.11"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "d6f6ff9a378485b298a5286656da665ba74413d36db0979633275d2e708145d4"
[[package]]
name = "rustc-hash"
version = "2.1.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "6b1e7f9a428571be2dc5bc0505c13fb6bf936822b894ec87abf8a08a4e51742d"
[[package]]
name = "shlex"
version = "1.3.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "0fda2ff0d084019ba4d7c6f371c95d8fd75ce3524c3cb8fb653a3023f6323e64"
[[package]]
name = "syn"
version = "2.0.119"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "872831b642d1a07999a962a351ed35b955ea2cfc8f3862091e2a240a84f17297"
dependencies = [
"proc-macro2",
"quote",
"unicode-ident",
]
[[package]]
name = "unicode-ident"
version = "1.0.24"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75"
[[package]]
name = "windows-link"
version = "0.2.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5"
+12
View File
@@ -0,0 +1,12 @@
[package]
name = "hunjing-lingtai"
version = "0.1.0"
edition = "2021"
description = "灵台引擎官方 Rust 绑定(ADR-016/017)"
license = "Apache-2.0"
[lib]
path = "src/lib.rs"
[build-dependencies]
bindgen = "0.71"
+56
View File
@@ -0,0 +1,56 @@
use std::env;
use std::path::PathBuf;
fn main() {
let header = PathBuf::from("../../include/hunjing/lingtai.h")
.canonicalize()
.expect("找不到引擎公共头");
let bindings = bindgen::Builder::default()
.header(header.to_string_lossy())
.allowlist_function("hj_.*")
.allowlist_type("Hj.*")
.allowlist_var("HJ_.*")
.generate()
.expect("bindgen 生成失败(需要 libclang)");
let out_dir = PathBuf::from(env::var("OUT_DIR").unwrap());
bindings
.write_to_file(out_dir.join("bindings.rs"))
.expect("写 bindings.rs 失败");
println!("cargo:rerun-if-changed={}", header.display());
// 直接编译引擎源码(自包含)
let src = PathBuf::from("../../src").canonicalize().expect("找不到引擎源码");
for cpp in ["lingtai.cpp", "transform.cpp", "modules.cpp"] {
println!("cargo:rustc-cxx=g++");
let _ = cpp;
}
// 用 cc crate 风格手动调用:为最小依赖,此处直接输出编译指令给 rustc 链接预编译静态库
// 简化:编译为单个静态库由 build.rs 调用 clang++
// 逐个编译 .o,再归档为静态库
let objects: Vec<_> = ["lingtai.cpp", "transform.cpp", "modules.cpp"]
.iter()
.map(|cpp| {
let obj = out_dir.join(format!("{}.o", cpp.replace(".cpp", "")));
let status = std::process::Command::new("clang++")
.args(["-std=c++23", "-O2", "-c"])
.arg(src.join(cpp))
.arg("-I").arg(src.parent().unwrap().join("include"))
.arg("-I").arg(&src)
.arg("-fvisibility=hidden")
.arg("-o").arg(&obj)
.status()
.expect("clang++ 启动失败");
assert!(status.success(), "引擎编译失败:{cpp}");
obj
})
.collect();
let out_lib = out_dir.join("libhunjing_engine.a");
let status = std::process::Command::new("ar")
.arg("crus").arg(&out_lib)
.args(&objects)
.status()
.expect("ar 启动失败");
assert!(status.success(), "归档失败");
println!("cargo:rustc-link-search=native={}", out_dir.display());
println!("cargo:rustc-link-lib=static=hunjing_engine");
println!("cargo:rustc-link-lib=dylib=c++");
}
+158
View File
@@ -0,0 +1,158 @@
//! 灵台引擎官方 Rust 绑定(bindgen 生成 + 安全包装,ADR-016/017)。
//! 薄封装:句柄 RAII、错误转 `Result`;禁止裸指针外泄(契约 lingtai-ffi 第 8 节)。
#![allow(clippy::missing_safety_doc)]
include!(concat!(env!("OUT_DIR"), "/bindings.rs"));
use std::ffi::{c_char, c_void, CStr, CString};
use std::fmt;
#[derive(Debug)]
pub enum Error {
InvalidArgument(String),
OutOfMemory,
UnsupportedAbi,
HandleInvalid,
ParseFailed(String),
LimitExceeded(String),
PolicyDenied(String),
Internal(String),
Unknown(i32, String),
}
impl fmt::Display for Error {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Error::InvalidArgument(m) => write!(f, "参数不合法:{m}"),
Error::OutOfMemory => write!(f, "内存分配失败"),
Error::UnsupportedAbi => write!(f, "ABI major 不匹配"),
Error::HandleInvalid => write!(f, "句柄无效"),
Error::ParseFailed(m) => write!(f, "解析失败:{m}"),
Error::LimitExceeded(m) => write!(f, "超限:{m}"),
Error::PolicyDenied(m) => write!(f, "策略拒绝:{m}"),
Error::Internal(m) => write!(f, "内部错误:{m}"),
Error::Unknown(code, m) => write!(f, "未知错误 {code}:{m}"),
}
}
}
impl std::error::Error for Error {}
fn map_status(st: HjStatus, message: String) -> Result<(), Error> {
match st {
HjStatus_HJ_OK => Ok(()),
HjStatus_HJ_ERR_INVALID_ARGUMENT => Err(Error::InvalidArgument(message)),
HjStatus_HJ_ERR_OUT_OF_MEMORY => Err(Error::OutOfMemory),
HjStatus_HJ_ERR_UNSUPPORTED_ABI => Err(Error::UnsupportedAbi),
HjStatus_HJ_ERR_HANDLE_INVALID => Err(Error::HandleInvalid),
HjStatus_HJ_ERR_PARSE_FAILED => Err(Error::ParseFailed(message)),
HjStatus_HJ_ERR_LIMIT_EXCEEDED => Err(Error::LimitExceeded(message)),
HjStatus_HJ_ERR_POLICY_DENIED => Err(Error::PolicyDenied(message)),
HjStatus_HJ_ERR_INTERNAL => Err(Error::Internal(message)),
other => Err(Error::Unknown(other as i32, message)),
}
}
fn last_error() -> String {
unsafe {
let ptr = hj_last_error();
if ptr.is_null() {
String::new()
} else {
CStr::from_ptr(ptr).to_string_lossy().into_owned()
}
}
}
/// 引擎句柄(RAII:Drop 自动释放)。
pub struct Engine {
ptr: *mut HjEngine,
}
impl Engine {
pub fn new() -> Result<Self, Error> {
let mut ptr: *mut HjEngine = std::ptr::null_mut();
let st = unsafe { hj_engine_new(HJ_ABI_VERSION, &mut ptr) };
map_status(st, last_error())?;
Ok(Engine { ptr })
}
/// Markdown → canonical ContentBlock JSON。
pub fn transform_markdown(&self, input: &str) -> Result<String, Error> {
let cin = CString::new(input).map_err(|_| Error::InvalidArgument("含 NUL".into()))?;
let mut buf: *mut HjBuffer = std::ptr::null_mut();
let st = unsafe {
hj_transform_markdown(self.ptr, cin.as_ptr(), cin.as_bytes().len(), &mut buf)
};
map_status(st, last_error())?;
take_buffer(buf)
}
/// 候选重排(确定性)。
pub fn recall_rerank(&self, candidates_json: &str) -> Result<String, Error> {
let cin =
CString::new(candidates_json).map_err(|_| Error::InvalidArgument("含 NUL".into()))?;
let mut buf: *mut HjBuffer = std::ptr::null_mut();
let st = unsafe { hj_recall_rerank(cin.as_ptr(), &mut buf) };
map_status(st, last_error())?;
take_buffer(buf)
}
}
impl Drop for Engine {
fn drop(&mut self) {
if !self.ptr.is_null() {
unsafe { hj_engine_free(self.ptr) };
}
}
}
// Send/Sync:HjEngine 线程安全(契约第 4 节)
unsafe impl Send for Engine {}
unsafe impl Sync for Engine {}
fn take_buffer(buf: *mut HjBuffer) -> Result<String, Error> {
if buf.is_null() {
return Err(Error::Internal("缓冲为空".into()));
}
unsafe {
let data = hj_buffer_data(buf) as *const c_char;
let len = hj_buffer_len(buf);
let slice = std::slice::from_raw_parts(data as *const u8, len);
let out = String::from_utf8_lossy(slice).into_owned();
hj_buffer_free(buf);
Ok(out)
}
}
/// URL 协议校验(仅 http/https)。
pub fn validate_url(url: &str) -> Result<(), Error> {
let cu = CString::new(url).map_err(|_| Error::InvalidArgument("含 NUL".into()))?;
let st = unsafe { hj_policy_validate_url(cu.as_ptr()) };
map_status(st, last_error())
}
/// 路径约束(授权根内、拒绝 ..)。
pub fn validate_path(path: &str, root: &str) -> Result<(), Error> {
let cp = CString::new(path).map_err(|_| Error::InvalidArgument("含 NUL".into()))?;
let cr = CString::new(root).map_err(|_| Error::InvalidArgument("含 NUL".into()))?;
let st = unsafe { hj_policy_validate_path(cp.as_ptr(), cr.as_ptr()) };
map_status(st, last_error())
}
/// 决策表(契约 autonomy_level × risk)。
pub fn decide(autonomy: i32, risk: i32) -> i32 {
unsafe { hj_policy_decide(autonomy, risk) }
}
/// 预算核算。
pub fn check_budget(used: i64, maximum: i64) -> Result<(), Error> {
let st = unsafe { hj_plan_check_budget(used, maximum) };
map_status(st, last_error())
}
/// 解析器版本。
pub fn transform_version() -> String {
unsafe { CStr::from_ptr(hj_transform_version()).to_string_lossy().into_owned() }
}
+33
View File
@@ -0,0 +1,33 @@
use hunjing_lingtai::{decide, check_budget, transform_version, validate_path, validate_url, Engine};
#[test]
fn lifecycle_and_transform_golden() {
assert_eq!(transform_version(), "hunjing-markdown-v1");
let engine = Engine::new().expect("引擎初始化");
let out = engine
.transform_markdown("x\n```mermaid\nA-->B\n```\n$$\nz\n$$\n")
.expect("transform");
let want = r#"{"parser_version":"hunjing-markdown-v1","blocks":[{"type":"markdown","text":"x","flavor":"hunjing-gfm-v1","status":"completed"},{"type":"mermaid","source":"A-->B","status":"completed"},{"type":"math","notation":"latex","display":"block","source":"z","status":"completed"}]}"#;
assert_eq!(out, want);
}
#[test]
fn policy_primitives() {
validate_url("https://ok.example").unwrap();
assert!(validate_url("javascript:alert(1)").is_err());
validate_path("/data/d/f", "/data/d").unwrap();
assert!(validate_path("/data/d/../x", "/data/d").is_err());
assert_eq!(decide(1, 0), 0); // 循律+只读 = allow
assert_eq!(decide(0, 2), 2); // 自省+高影响 = deny
assert!(check_budget(10, 10).is_err());
}
#[test]
fn recall_rerank_deterministic() {
let engine = Engine::new().unwrap();
let input = r#"{"query_terms":["魂镜"],"candidates":[{"id":"a","text":"魂镜 系统"},{"id":"b","text":"无"}]}"#;
let out1 = engine.recall_rerank(input).unwrap();
let out2 = engine.recall_rerank(input).unwrap();
assert_eq!(out1, out2);
assert_eq!(out1, r#"{"ranked":[{"id":"a","score":10},{"id":"b","score":0}]}"#);
}