内容
# .sarib — 原生AI知识语言
*单一纯文本源。人类像Markdown一样编写它。代理像数据库一样编辑它。每个视图——文档、提纲、面板、图表、时间线、上下文窗口——都是一个投影。*
**状态：v0.1 — 工作参考实现；规格完成；基准测试后冻结。** 5个关卡绿色且已测量；**G2测量结果混合** （4个模型完成，5个速率限制 — [`bench/g2-results.md`](bench/g2-results.md)）；G3因人类评分者受阻；G8部分待重新运行开放权重标记器。这是研究级开放标准提案，在开放中构建，其完整设计历史——包括反对它的结果。
```markdown
# Q3 计划
## 迁移发票 {.task} ^t1
状态:: 待办
截止日期:: 2026-08-01
负责人:: [[爱丽丝]]
必须等待我们 [依赖于:: [[采用新的计费提供商]]。
```
这是一个有效的 `.sarib` 文件。它在任何地方都渲染为普通的Markdown，*并且*它是一个标记的属性图：`t1`是一个具有属性的`task`节点，`owner`和`depends-on`是类型化的边，代理可以查询和原子编辑。
## 为什么
每种知识格式都服务于一个主人：Markdown服务于文档，JSON服务于机器，数据库服务于查询。今天的AI代理会花费数千个令牌重新生成整个文档以更改一个单词，并重新推断在编写时显而易见的关系。`.sarib` 将知识存储为一个标识的图，其包含树*是*可读文档，然后让两个物种原生地处理它：
- **人类**编写散文 + 轻微标记（Markdown超集；不需要标记 — 纯散文有效）。
- **代理**查询有界子图并应用ID寻址的原子操作 — 从不重新生成。
**测量，不承诺。** 一次点编辑的成本为 **0.50%** 重新生成一个10k令牌文件的成本 — 比整个文档重新生成减少200倍（[`bench/gate-report.md`](bench/gate-report.md)，G1；自己运行 `python bench/run_gates.py`）。针对该项目的真实70风险注册的定向问题，上下文成本为 **230令牌** 而不是6,652（[`bench/g2-g3-protocol.md`](bench/g2-g3-protocol.md) — 还记录了一个胜利缩窄至1.8倍的情况）。并发编辑合并顺序无关（SEC，CRDT收敛操作）。通过一致性语料库强制执行完整的往返无损性。一致性表面 — 解析器、规范化器、模型、操作引擎、查询引擎、投影、CLI、MCP服务器 — 是 **891行Python**，在测量前声明的≤1000-LOC预算内；Markdown导入器是另外249行，作为消费者报告在预算之外。
## 安装和尝试（60秒）
只需 `pip` — 这会创建自己的演示文件，因此它适用于任何空目录：
```bash
pip install sarib # 零依赖核心；安装`sarib`命令
cat > demo.sarib <<'EOF'
# Q3 计划
## 迁移发票 {.task} ^t1
状态:: 待办
截止日期:: 2026-08-01
负责人:: [[爱丽丝]]
必须等待我们 [依赖于:: [[采用新的计费提供商]]。
## 采用新的计费提供商 {.decision} ^d1
状态:: 已接受
EOF
sarib validate demo.sarib
sarib render demo.sarib --view outline # 空间提示
sarib render demo.sarib --view board # 看板投影
sarib render demo.sarib --view mermaid # 依赖图
sarib query demo.sarib --type task # 有界查询 → 小图
sarib query demo.sarib --from t1 --edges depends-on # 什么阻止了t1
sarib set demo.sarib t1 status=done --dry-run # 属性编辑，按ID
```
`validate` 将报告一个 `unresolved-reference: 'Alice'` — 这是设计，不是失败。没有名为Alice的节点，因此解析器留下链接未解析并说明，而不是猜测你指的是哪个节点（D-024）。诊断是 lint，从不致命；每个字节字符串都是有效的 `.sarib` 文件。
代理通过面向机器的形式使用相同的引擎 — 完整的查询规范或操作为JSON：
```bash
sarib query demo.sarib --spec '{"select":"none","filter":{"type":"task"}}'
sarib apply demo.sarib --op '{"kind":"set-property","target":"t1","args":{"key":"status","value":"done"}}'
```
*（在Windows `cmd.exe`上，将外部单引号替换为双引号并转义内部引号 — 或使用上面的标志形式。）*
### 从存储库克隆
`git clone` 此存储库以获取工作示例、一致性语料库和基准：
```bash
sarib render examples/A-prose-native.sarib --view board
python impl/tests/run_corpus.py # 一致性：6/6，无依赖
python bench/run_gates.py # 测量的关卡（需要：npm i gpt-tokenizer）
```
### 导入您自己的笔记：`sarib import`
将现有的Markdown转换为 `.sarib` 知识图：
```bash
sarib import notes/*.md -o knowledge.sarib # 确定性：标题->节点，[[引用]]->边
sarib import notes/*.md -o knowledge.sarib --extract-edges # + 类型边（约束 + 验证）
```
默认构建是确定性和无依赖的。 `--extract-edges` 添加类型边代理建议，但代理被限制在只能*选择和引用*，不能发明：封闭边词汇表和现有ID目标（在解码时按模式强制），逐字引用要求和每次边的独立蕴涵检查；不支持的内容被丢弃，保持的边带有`inferred`出处。这是高精度和故意保守的 — **辅助，验证提取，不是完美的自动图。** （默认使用本地Ollama模型； `--model` / `--endpoint` 指向其他地方。方法和引用： [`research/importer-extraction.md`](research/importer-extraction.md).)
**看到它，而不是只是阅读它：** `sarib-preview knowledge.sarib` （或 `python -m sarib.preview …` ；随pip包一起提供，因此在任何文件夹中都有效）打开一个本地页面，显示每个投影作为选项卡 — 文档、提纲、面板、依赖图、规范的机器形式。VS Code扩展在编辑器旁边显示相同的页面（`Ctrl+Shift+V`）。
**代理原生：** MCP服务器为`.sarib`文件目录下的任何MCP客户端（Claude Desktop，Claude Code，Cursor，…）提供五个工具： `sarib_query / sarib_apply / sarib_render / sarib_validate / sarib_canon`。
```bash
pip install "sarib[mcp]" # 添加MCP服务器（需要Python 3.10+；核心运行在3.9上）
```
然后在客户端中注册它（Claude Desktop： `claude_desktop_config.json` ；Claude Code：项目 `.mcp.json`）：
```json
{ "mcpServers": { "sarib": {
"command": "sarib-mcp",
"args": ["<.sarib文件目录>"] } } }
```
重启客户端，批准服务器，然后直接对话： *"哪些任务是开放的？"* 运行有界查询； *"标记t1完成"* 应用ID寻址的操作 — 文件通过增量更改，而不是重写。
**VS Code：** `editors/vscode-sarib/` 提供语法高亮和实时预览面板（`Ctrl+Shift+V`）。从发行版安装预构建的`.vsix`，或构建它： `npx @vscode/vsce package && code --install-extension vscode-sarib-0.3.0.vsix`。面板从安装的包调用预览器，因此 `pip install "sarib>=0.1.4"` 就是它需要的 — `.sarib` 文件在任何文件夹中预览，无需克隆，无需配置。
## 设计，五项承诺
1. **一张图。** 节点 + 类型边；文档是有序遍历的包含树。线性、树状和非线性读取是相同的数据。
2. **ID，而不是位置。** 每个节点/边都有一个持久ID；所有编辑都寻址ID；重命名不会破坏任何内容。
3. **操作是更改的单位。** 创建/撤销/设置/链接/移动 — 收敛（顺序无关折叠），由乐观前提条件保护，不会删除。
4. **每个状态只有一个字节形式。** 用于哈希、差异和缓存的规范JSON范式；操作日志是追加的（缓存稳定的前缀）。
5. **投影可能会隐藏，但不会删除。** 视图是实时窗口（编辑通过ID流动）或声明的终端导出 — 从不模糊的中间状态。
## 仓库地图
| 路径 | 内容 |
|---|---|
| `stages/14-language-specification.md` | **规范** （从这里开始） |
| `stages/01…15-*.md` | 完整的分阶段设计历史 — 每个阶段都批评其前身 |
| `impl/` | 参考实现（Python，891行一致性表面）+ 一致性语料库 |
| `examples/` | 规范语法候选（A）；候选B在 `stages/10` 中指定，但未作为文件提供 |
| `bench/` | 冻结门基准 + 标记器验证 + 测量的G2运行 |
| `docs/` | 关于其工作原理的纯语言解释 |
| `research/` | 9篇引用研究文件（格式为什么会赢/失败，LLM格式证据，往返法则） |
| `decisions/` · `risks/` | 61个记录的决定和逆转条件 · 动态风险注册 |
| `dogfood/` | 项目自己的决策日志和风险注册为`.sarib`，通过操作管理 |
## 真实状态和下一步
**G2已经运行，诚实读数混合** （[`bench/g2-results.md`](bench/g2-results.md)，包含原始每调用记录）。从有界查询回答击败粘贴整个Markdown **+27.8分在7B模型上** （88.9% vs 60.2%，McNemar p=0.002）并在 **~⅓输入令牌的120B模型上达到同等** （100% vs 99.1%，420 vs 1,325令牌）。但在模型汇总中，增益 **不显著** （Δ=+0.083，p=0.065），一个模型（`llama3.2`，3B） **直接失败** 标准低于-0.111，并且 — 最重要的结果 — **向模型提供整个`.sarib`文件并不比整个Markdown更好** ，大约46%更多的令牌。因此，胜利是 **有界检索和原子编辑架构** ，不是语法密度。这是D-002预测的结果，这就是为什么语法不是推销点。
仍然未完成： **G3** （冷人可读性，需要评分员）和开放权重标记器重新运行。只有当关卡为绿色时，规范才会冻结 — 如果它们失败，设计会更改，而不是基准。贡献运行协议、移植解析器（TS/Rust）或破坏一致性语料库是最有价值的。
许可证：代码MIT，规格CC-BY-4.0。一致性由 `impl/tests/corpus/` 定义，而不是由任何实现定义。
