玉衡（Yuheng）—— 治理闭环引擎

在璇玑玉衡，以齐七政。——《尚书·舜典》玉衡是北斗第五星，是先民用来「齐理七政」的衡器。三千年后，我们把它重铸成给 AI 智能体体系的治理之衡。

一句话

当「会做一件事」的智能体越来越多，真正稀缺的是「一直做、持续做对、每一步可查」的体系。玉衡把一套在真实体系中数月实跑的治理闭环——真值账本、哈希锁档、审计链、记忆网关、治理围栏——提炼成五个模块、零依赖、十分钟可跑通的开源内核。

模型决定上限，治理与系统决定能力能否变成持续生产力。

为什么需要它

单层框架（编排、规划、工具调用、多智能体协作）回答的是「怎么做成一件事」。但把体系放进真实运行里，立刻遇到三问：

它能不能独立于任何一次会话，按节律持续运行？
它做的事，有没有一条可信的记录，而不是散落在终端日志里？
它出了错，是靠人盯、靠人改提示词，还是体系自己发现、自己纠正？

这三问对应的不是某一层能力，而是治理与闭环。玉衡补的就是这一层。

六层闭环

        ┌─────────────── 治理围栏（规则先行）───────────────┐
        │                                                  │
        │   自治内核 ──①──> 内容产线                        │
        │      ↑⑤            │②                           │
        │      │             ↓                            │
        │   记忆网关 <─④── 真值库 <─③── 存证·审计链         │
        │                                                  │
        └──────────────────────────────────────────────────┘

沿编号走一遍完整回路：内核执行任务（①），产出回流进入网关（②），网关校验后入真值库（③），经存证锁档（④），最终由内容产线发布并反馈（⑤）。每个环节的输出是下一个环节的输入，没有一步悬空。

五个模块

模块	一句话	对应问题
`fence` 治理围栏	规则先行：红线内自治、明令禁止即拦、红线之上必升级	什么能自动做？
`gateway` 记忆网关	所有写入的唯一入口，读写分离	凭什么管住它的记性？
`ledger` 真值账本	只增不覆盖，事实/计划/推断分型，天然哈希链	它说过的话还算数吗？
`seal` 哈希锁档	资产入账即封存，漂移必被察觉	怎么知道它没偷偷改？
`audit` 审计链	谁、何时、依据什么、做了什么，全链可回溯	出了事找得到因果吗？

60 秒跑通

git clone <本仓库>
cd yuheng
python3 examples/loop_demo.py

你会看到：日常写入直接放行；外发动作被围栏拦下；发布动作升级待裁；报告封存后改一个字，哈希漂移当场报警；收班时整条账本与审计链重放校验全绿。

快速上手

from yuheng import fence as fence_mod
from yuheng import seal as seal_mod
from yuheng.audit import AuditChain
from yuheng.gateway import MemoryGateway
from yuheng.ledger import FACT, PLAN, TruthLedger

fence = fence_mod.GovernanceFence(default=fence_mod.ALLOW)
fence.add("memory.write.publish*", fence_mod.ESCALATE, "对外发布须裁决")

ledger = TruthLedger("ledger.jsonl")
seals = seal_mod.SealRegistry(ledger)
chain = AuditChain("audit.log", actor="my-agent")
gw = MemoryGateway(ledger, fence, chain, operator="my-agent")

gw.write(FACT, {"event": "晨检完成", "result": "全绿"}, topic="巡检")   # 放行
gw.write(FACT, {"note": "发出去"}, topic="publish")                    # 升级

seals.register("report-1", open("report.pdf","rb").read())
seals.verify("report-1", open("report.pdf","rb").read())               # False 即漂移

ledger.verify()   # 整条真值链重放
chain.verify()    # 整条审计链重放

设计约定：

零第三方依赖，Python 3.10+，标准库即可跑全部功能与用例；
只增不覆盖：账本与审计链没有修改/删除接口，写错就写更正，历史永远可还原；
事实、计划、推断分型：任何时刻可按型核查，计划不会伪装成事实；
哈希链内建：账本与审计链每条携带前条哈希，改历史必断链；
围栏默认可配：封闭体系可用默认放行，对外场景建议默认升级（宁停不越）。

运行测试

python3 -m unittest discover -s tests -v

10 个用例覆盖：只增语义、分型校验、哈希链篡改检测、更正不删史、封存漂移报警、围栏三裁决、网关放行/拦截/升级路径、双链健康检查。

命名由来

「玉衡」出自《尚书·舜典》：「在璇玑玉衡，以齐七政。」玉衡是北斗第五星，古人以它为衡器来齐理日月五星的运转——衡，就是治理。给智能体体系装上玉衡，让它自主运转时始终有衡可依、有账可查。

命名属火斗云体系道统谱系，与玄圭（验证之圭）、天罡（守护之眼）同脉：玄圭管「验收」，玉衡管「治理」。

设计来源

本引擎是实战提炼，不是纸面设计。同一套闭环思想在三条独立路径上收敛：

实战体系：在火斗云智能体体系中，以真值账本、哈希锁档与每日巡检支撑数月持续运行（十项级并行任务、小时级进化轮、千项级记忆资产固化入账）；
同源实践：其他独立演进的治理型体系，同样选择了「记录先行、只增不改、规则在先」；
业界公开设计：头部团队公开文章提出的连续性、高效性、主动性、持久性四特征，与「常驻进程＋结构化记忆＋事件驱动＋治理记录」的路径高度重合。

三条路径，一个方向：闭环治理不是风格偏好，而是持续运行智能体体系的收敛解。

详细论述见 docs/architecture.md 与技术随笔《从单层能力到闭环治理》。

联邦记忆池

玉衡与火斗云官网、四大开源阵地互为镜像、彼此回链，构成一个联邦记忆池：官网是叙事入口，四家仓库是代码真身，任一阵地都是完整真相，一处生长、四处同步。

技术随笔《从单层能力到闭环治理》：https://www.huodouai.com/closed-loop-governance.html
火斗云官网：https://www.huodouai.com
AtomGit：https://atomgit.com/zongyuangen/yuheng
GitHub：https://github.com/tanbopiao/yuheng
Gitee：https://gitee.com/huodou-cloud-intelligence-aios/yuheng
魔搭 ModelScope：https://modelscope.cn/zongyuanroot/yuheng

License

MIT