Skip to content
KlockTXPublic

About

HYMN Yields Markdown Notation - spec-first Markdown data notation with executable Schema contracts and byte-identical Python/JS implementations.

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

HYMN

HYMN Yields Markdown Notation —— 用 Markdown 承载数据,用 Schema 保证准确,用类型化块保证渲染安全。

在同一份 .hymn 文件里承载数据对象、人类文档、契约与渲染安全策略。 既不是 Markdown 的超集,也不以压缩为目标。

仓库导航:本 README 与 spec/ tools/ packages/ examples/ 只描述 HYMN notation 本身。 当前工作区的活跃主线是「中国纸飞机社区」论坛(forum/ + cloudfunctions/forum-api/), 其文件索引、路由表与数据字典见 docs/forum-file-index.md, 与主站 fly.cpac.top 的绑定方案见 docs/cpac-deep-binding.md。 论坛改动不进入本协议的 8 环验收链(该链只管 spec/ 与两套实现)。

::: meta hymn=0.5 mode=mixed schema=agent/v1 safe=strict
:::

::: data
# Agent
name: ResearchBot
version: 1.2.0                  # 版本号是字符串,不是 float
max_tokens: 4096

## Tools
* web_search
* python

## Servers :: array              # 数组必须显式
### server
name: api
url: https://api.example.com :: url

## notes
body: 用法 :: ref               # 引用文档区章节,断链即报 HYMN016
:::

# 用法

这段正文被数据区的 `notes.body` 引用,改名会立刻报错而不是静默丢内容。

::: callout warning
该 Agent 可访问文件系统,请谨慎授权。
:::

快速开始(agent 一键配置)

git clone https://github.com/KlockTX/hymn.git && cd hymn
bash tools/verify.sh --install-deps      # Linux/macOS/Windows Git Bash(或 pwsh tools/verify.ps1)

零第三方运行时依赖,只需 Python ≥ 3.9 与 Node ≥ 20;verify 一条命令跑完 8 环验收链。 安装为工具:pip install .(Python hymn CLI)或 npm install -g ./packages/js(JS CLI)。 agent 工作指令与修改纪律见 AGENTS.md;给 LLM 的速查卡见 hymn guide --for gen|fix。


仓库结构

spec/
  HYMN-0.5-规范.md          ← 完整版规范(CommonMark 式自包含:记法与约定 + 连续编号示例 + 附录;§编号为稳定引用锚)
  HYMN-0.5-agent体验-提案.md ← 0.5 修订的设计与实施记录(fix / guide / 生成侧资产)
  HYMN-架构设计.md           ← 实现架构:L0–L7 分层、跨语言一致性、测试架构、里程碑
  hymn02.py                 解析器:分帧 / 数据 / 类型 / 文档 / 契约 / 引用 / 规范序列化
  hymn_fmt.py               hymn fmt:源规范化(幂等 + 语义保持)
  hymn_render.py            渲染器:Markdown 降级 + HTML 严格层
  hymn_cli.py               CLI:parse / check / fmt / render / to-json / schema / guide
  tables/                   三语言共享常量(错误码 / 块属性 / 类型 / GBNF / agent schema;由导出器生成)
  export_tables.py          从 hymn02.py 的常量导出 tables/(改常量后必须重跑)
  export_grammar.py         从常量导出 agent 生成侧资产(grammar.gbnf + agent_schema.json)
  tests/cases.py            一致性语料真相源(74 用例 + 15 浮点样本)
  tests/fixtures/           契约测试夹具(含注册表解析、0.1 版附录 A、附录 A 冻结期望字节)
  runner.py                 一致性运行器 + 语料编译器 + 常量对齐 + 附录 A + Agent 资产 + 示例门禁
  spec_examples.py          规范示例提取器(CommonMark 式"示例即测试";被 runner 门禁调用,可单跑)
  fuzz.py                   属性 / 模糊测试(不变量 I1–I14 + 检验机会报告)
  render_test.py            渲染器安全测试(结构化断言 + 正向对照)
  cli_test.py               CLI 端到端测试
  verify02.py               0.1 缺陷回归矩阵(逐条断言)+ token 代价测量
packages/
  js/src/engine.js          JavaScript 实现(parse / 契约 / 引用 / 规范序列化)
  js/src/fmt.js             JavaScript fmt
  js/bin/hymn.js            JavaScript CLI
  js/bin/conformance.js     同一份语料的 JS 运行器
  js/bin/selfcheck.js       差分通道的 JS 侧结果产出
tools/diff-runner/
  run.py                    跨语言差分:canonical / errors / fmt / md 四路(node 按
                            HYMN_NODE → PATH 解析,缺失即失败,不静默跳过)
  cli-diff.py               CLI 行为差分(含 CRLF 夹具;stdout / stderr / 退出码全比对)
examples/ponytail/          真实 agent 插件重写示例(详见其 README)
build/                      构建产物:语料 + 各类报告(不入库,由验收链生成)
.github/workflows/          验收链 CI(ubuntu + windows 双平台,与 tools/verify.sh 同源)
AGENTS.md                   agent 工作说明:一键验收、安装、修改纪律
pyproject.toml              pip install . → `hymn` CLI(hymn02/hymn_fmt/hymn_render/hymn_cli)
tools/verify.sh / .ps1      一键验收链(8 环,任一失败即非零退出)
LICENSE                     MIT
requirements-dev.txt        可选度量依赖(tiktoken)

状态

项 结果
一致性语料(Python) 74 / 74 + 浮点 15 / 15 + 常量对齐门禁 + 附录 A 冻结字节门禁 + Agent 资产门禁 + 规范示例门禁(49/49)
一致性语料(JavaScript) 74 / 74 + 浮点 15 / 15 + 附录 A + fix 应用(I14)
跨语言差分 320 条输入 × 4 条通道(canonical / errors / fmt / md),差异 0;errors 通道比对 (码, 行, 列, 消息, hint, pointer, fix) 有序序列,含 astral 码点探针
CLI 差分 5 文件 × 8 命令 = 40 组,行为一致(stdout / stderr / 退出码全比对)
0.1 缺陷回归 13 / 13 收敛
属性 / 模糊测试 I1–I14 全部通过(300 生成文件 + 360 次变异,0 崩溃 0 超时;I14 = fix 可执行)
渲染器安全 216 / 216(28 载荷 × 9 槽位 = 252;另 36 格因载荷本身非法被拒,同为安全结果)
Agent 生成侧 agent_schema.json 接受全部 31 份合法语料 AST + 附录 A;grammar.gbnf 落盘与常量对齐
真实示例 examples/ponytail:一份 .hymn → 14 平台 15 文件,契约 0 error

hymn fmt 满足幂等(I9)与语义保持(I10),且两份实现的 fmt 输出逐字节相同——都由属性测试与差分测试强制,不是人工抽查。


用法

# 校验 / 格式化 / 渲染
python spec/hymn_cli.py check examples/ponytail/ponytail.hymn
python spec/hymn_cli.py fmt examples/ponytail/ponytail.hymn --check
python spec/hymn_cli.py render examples/ponytail/ponytail.hymn --format md
python spec/hymn_cli.py parse examples/ponytail/ponytail.hymn --positions

# JavaScript 实现(同一份语料、同一套 CLI 行为)
npm --prefix packages/js test          # 或 node packages/js/bin/conformance.js
node packages/js/bin/hymn.js check examples/ponytail/ponytail.hymn

# 面向 agent(0.5):速查卡、机器修复诊断、生成侧资产
python spec/hymn_cli.py guide                       # 语法摘要 + 全诊断码表(可塞进 prompt)
python spec/hymn_cli.py guide --for gen             # 只给生成侧,1235→580 tok
python spec/hymn_cli.py guide --for fix             # 只给修复侧,1235→946 tok
python spec/hymn_cli.py check bad.hymn --errors json # 诊断带 fix 机器修复指令
python spec/export_grammar.py                       # 重导出 tables/grammar.gbnf + agent_schema.json
python spec/spec_examples.py                        # 单跑规范示例门禁(runner 已内置同一断言)

# 跨语言差分(canonical / errors / fmt / md 四路 + CLI 行为,含 stderr)
# node 解析顺序:环境变量 HYMN_NODE → PATH;找不到即失败,不会静默跳过
python tools/diff-runner/run.py
python tools/diff-runner/cli-diff.py

# 可选:安装度量依赖后,verify02 的 ②③ token 段会真实执行(否则如实跳过)
python -m pip install -r requirements-dev.txt

# 全部验收(任一环失败即非零退出;CI 双平台执行同一脚本)
bash tools/verify.sh

改动 spec/hymn02.py 的错误码或常量后,必须重跑 python spec/export_tables.py 重新生成 spec/tables/,否则 runner.py 的常量对齐门禁会以非零退出失败—— 这正是它要拦的那类漂移(tables/ 曾落后于规范 §11.3 而无人察觉)。


定位(诚实披露)

实测(cl100k_base,同信息量):

承载方式 token 相对 HYMN
HYMN 单文件 216 —
压缩 JSON + Markdown 文档(2 文件) 175 −19.0%
2 空格 JSON + Markdown 文档(2 文件) 265 +22.7%

口径:build/verify02.txt ③ 段,附录 A 同信息量。装好 requirements-dev.txt 后该段 可复算(初版 1.0 复核:216 / 175 / 265,与上表一致)。HYMN 侧按作者书写形态计 (:: ref 不展开),基线两侧各只含一份散文——把解析后的正文也计进 JSON 会教基线为同一份 散文付两次 token。

  • HYMN 数据区(含 meta)121 对压缩 JSON 116,贵 4.3%;相对缩进 JSON(206)的节省全部来自去缩进,压缩 JSON 同样能拿到。
  • 整文件比"压缩 JSON + 独立文档"双文件基线贵约 23%。
  • 以下两条为 0.1 评审期实测,其证据文件已随仓库清理移除、当前验收链无法复算:嵌套深度 ≤ 3 时不如 YAML;小文件固定开销约 21 token。保留是为了不掩盖短板,但请按历史数据对待。

书写形压缩红利 ≈ 0(实测,cl100k_base):对附录 A(216 tok)与 ponytail(2840 tok) 删除全部空行、闭块收紧、行尾清理,节省均为 0 tok——BPE 把 \n\n 并成单 token,删后由 上下文 merge 补回;且全文压空行会改变文档区 AST(markdown 语义),机械 compact 路线不可行。 行尾类型标注全删也仅省 10/216(4.6%)与 26/2840(0.9%,散文占 60%),不值得为它升协议。 agent 场景真正的注入大头是速查卡本身:guide --for gen|fix 按场景裁剪,1235 → 580 / 946 tok。

所以 HYMN 的价值是:一份文件、一次校验、一处渲染。 具体是四件事:

  1. 契约与数据同文件——身份、组件、平台清单由一个 Schema 约束,不靠约定;
  2. 数据与文档可校验关联——:: ref 让"这段数据用的是文档里哪一节"变成可验证的,而不是注释里的约定;
  3. 默认安全渲染——标签白名单、协议白名单、零原始 HTML,且有 216 条结构化安全断言守着;
  4. 跨语言逐字节一致——规范序列化指定了 ECMAScript 浮点算法,而不是"最短往返"这种各实现自行理解的说法。

如果你的需求里这四条都不重要,压缩 JSON 或 Markdown frontmatter 是更省的选择。


版本历程

版本 做了什么
0.1 设计草案。评审发现 5 项阻断缺陷 + 9 项必须澄清(逐条见规范 §0 变更表)
0.2 修复全部 P0/P1:围栏长度匹配、markdown 条目、数组显式化、引号强制 str、零静默、规范序列化指定算法
0.3 兑现两个缺口:key: | 块状字面量、:: ref 引用 + HYMN016;属性/模糊测试成为规范要求
0.4 合并完整版;补旁挂表、fmt、渲染器、CLI;不变量扩展到 I1–I13;JS 实现落地,跨语言差分零差异
1.0(初版) 实现落版(协议保持 hymn=0.4)。闭合 0.4 评审期"待推进"全部 9 项:诊断消息/hint/pointer 进入 errors 通道并统一为 JSON.stringify 口径(规范 §11.2);CLI 差分含 stderr;附录 A 期望字节冻结为入库真相文件(防自证循环);长度/列口径统一为 Unicode 码点并加 astral 探针(§4.7);差分器去硬编码路径、缺 node 即失败;CI + npm test + git 初始化;keysOf 文档顺序修复;token 度量可复算
1.1.1 实现落版(协议保持 hymn=0.5,零协议改动)。agent 一键配置:AGENTS.md + tools/verify.sh/.ps1(8 环链单条命令,CI 收敛同源)+ pyproject.toml(pip install . 得 hymn CLI)+ MIT。规范 CommonMark 化重排为 spec/HYMN-0.5-规范.md:记法与约定(RFC 2119、字符=码点、示例读法)+ 50 个连续编号示例,示例即测试(spec_examples.py 提取执行,runner 新示例门禁,注入假码实测红灯);§编号保持为稳定引用锚。另:guide --for gen|fix 场景裁剪(1235→580/946 tok)与"书写形压缩红利 ≈ 0"实测入档
0.5 / v1.1.0 协议升次版本(向后兼容,全部 0.4 文件逐字节同结果)。面向 AI agent 的三个表面:诊断带 fix 机器修复字段 + 不变量 I14(可执行,§11.2.1);hymn guide 作者速查卡(从常量渲染,Python 独占,JS 明确拒绝);生成侧资产 grammar.gbnf + agent_schema.json(常量导出 + 落盘门禁,兑现架构 §7.3)。附带把 §4.7「围栏 ≤32」这条写了却从未强制的上限落地(frame-006 → HYMN007)。设计见 spec/HYMN-0.5-agent体验-提案.md

0.4 相对 0.1 的逐条变更见 spec/HYMN-0.5-规范.md §0;0.5 相对 0.4 见其 §0.1。

第二个实现抓到的三个问题(都是"规范没写清的宿主环境假设",单实现永远发现不了):

  1. 语料从没被字节校验过——Python 运行器比较的是解析后的对象(顺序无关),期望字符串里 blocks 写在 data 前面也照样通过;
  2. Python CLI 在 Windows 上会把 \r\n 静默转成 \n,导致 fmt --check 对 CRLF 文件误报"已规范";
  3. JS 里整数若用 Number,旁挂表的行列坐标会序列化成 3.0 而非 3。

三条都已修,并各自固化成了用例或差分夹具(规范 §12.5、§14.2)。


尚未实现

规范先行必须如实标注落差(完整表见规范 §18):

  • Rust 实现 —— 未开始(架构文档 M3);
  • JS 的 HTML 渲染 —— JS 侧只提供 Markdown 降级;HTML 严格层由 Python 参考实现提供,node hymn.js render --format html 会明确报错,而不是给一个不同的结果;
  • hymn from-json(JSON → HYMN)—— 未实现;
  • relaxed 渲染 —— 有意不提供(无 sanitizer 时提供该模式只是把风险换个地方;声明 safe: relaxed 会得到明确警告并降级为 strict)。

初版闭合与遗留边界

0.4 评审期的"待推进"9 项已在 1.0 全部闭合(高/中/低全修,逐项见版本历程 1.0 行与 git 提交记录)。诚实记录仍然遗留的边界,防止"修完=没有短板"的错觉:

遗留 事实 为什么可接受
语料期望 AST 的序列化字节仍出自 Python 规范序列化器 手写期望 AST 是独立信息;附录 A 已冻结为入库真相文件 序列化器另有双实现逐字节一致 + 浮点语料锚定;彻底独立要等第三实现(Rust,M3)
列口径的 astral 覆盖是代表路径 key/行/字面块/url 四路有探针与用例;围栏属性等解析位置的列仅 fuzz 随机覆盖 码点口径已写入 §4.7/§8.4,属规范要求;覆盖面随 fuzz 种子扩大
minimum/maximum/enum 诊断不再携带数值参数 §11.2 规定消息参数只允许字符串 数值跨语言格式化无一致定义(BigInt/浮点/-0.0),定位由 pointer + range 承担
fix 只覆盖三个机械唯一形态 HYMN001/011/014(FIX_CODES 单点声明) 「宁可不修也不猜意图」;新增 op 走次版本,消费者必须忽略未知 op
GBNF 未经 llama.cpp 实机回放验证 导出与常量逐条对齐 + schema 通道有 31/31 JSON Schema 验证证据 grammar 是旁路生成资产,不参与解析判定;接入方跑通后补回归
CI 文件已就位,但远端尚未挂 本地验收链 8 环全绿;build/ 新鲜度现由 git 提交时间戳佐证 push 后 .github/workflows/acceptance.yml 即生效(ubuntu + windows 双平台)

About

HYMN Yields Markdown Notation - spec-first Markdown data notation with executable Schema contracts and byte-identical Python/JS implementations.

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages