Symgliph 将文件语料库编译为**可验证的视觉字形制品**。 该字形并非神奇的压缩算法，也不假装包含每一个源字节。它结合了： - 包含文件的确定性清单； - 域分离的 BLAKE3 语料库根； - 单独版本化的语义图和语义根； - 其身份标记源自该根的紧凑 SVG； - 源自语料库和符号度量的结构几何；以及 - 仅在验证其文件后才解析字节范围的源索引。 这是一个更大构想的首次验证：**编译的上下文**——语料库的视觉身份、压缩理论和精确展开路径。 ## 正式规范 规范协议发布为 [`Symgliph Context Glyph Protocol 0.1`](spec/symgliph-context-glyph-v0.1.md)。 其包包含 JSON Schema、确定性的跨实现测试向量、负向 fail-closed 用例，以及一个可执行的符合性门控： ``` spec/validate.sh ``` 协议符合性与模型质量声明是有意分离的。规范证明了兼容的构建和验证；基准测试证明了声明数据集和模型配置的检索和回答行为。 ## 快速开始 ``` cargo run -- build ./my-corpus cargo run -- verify ./my-corpus cargo run -- inspect ./my-corpus --kind function cargo run -- references ./my-corpus --kind calls cargo run -- references ./my-corpus --unresolved cargo run -- pack ./my-corpus --query "how is the glyph rendered?" --max-tokens 4000 cargo run -- prove-context ./my-corpus --query "how is the glyph rendered?" ``` 构建命令写入： ``` my-corpus/.symglyph/ ├── glyph.svg ├── manifest.json └── manifest.symglyph ``` 默认情况下会排除隐藏路径，因此生成的 `.symglyph` 目录不会意外包含在后续构建中。仅在输出目录位于语料库之外时，才使用 `--include-hidden`。 ## 库 API ``` use symgliph::{CorpusBuilder, GlyphRenderer, SourceIndex}; let manifest = CorpusBuilder::new("./my-corpus").build()?; let svg = GlyphRenderer::default().render(&manifest); let function = manifest.semantics.nodes .iter() .find(|node| node.kind == "function") .expect("the corpus contains a function") .id .clone(); let index = SourceIndex::new("./my-corpus", manifest); let evidence = index.read_node(&function)?; # Ok::<(), symgliph::Error>(()) ``` ## AI 上下文和 token 成本 SVG 或哈希本身无法教会模型语料库。节省 token 的方法是将该制品用作经过验证的检索地址空间：Symgliph 选择与问题相关的语义节点，展开图邻居，根据清单验证当前源字节，并仅输出符合严格 token 上限的证据。 ``` use symgliph::{ContextEngine, ContextRequest, CorpusBuilder}; let manifest = CorpusBuilder::new("./my-corpus").build()?; let engine = ContextEngine::new("./my-corpus", manifest); let packet = engine.pack(&ContextRequest::new("where is authorization checked?"))?; assert!(packet.prompt_tokens <= packet.max_tokens); // Send packet.prompt to the model and retain packet.evidence for citations. # Ok::<(), symgliph::Error>(()) ``` `prompt_tokens` 使用 `o200k_base` 计算，而不是根据字符估算。 每个摘录都带有其节点 ID、精确的字节范围、完整文件摘要和摘录摘要。如果所选文件在编译后发生了更改，打包将失败，而不会发送陈旧或未验证的上下文。 对于本地模型/工具桥接，`symgliph serve` 从 stdin 读取换行符分隔的 JSON-RPC，并每行写入一个响应： ``` {"jsonrpc":"2.0","id":1,"method":"context.pack","params":{"query":"render glyph","max_tokens":2000,"max_nodes":8}} ``` 可用方法有 `context.describe`、`context.pack` 和 `context.proof`。 proof 方法将数据包与发送每个非二进制语料库文件的确定性基线进行比较。这衡量了输入 token 的减少量；实际的 API 成本取决于提供商、模型、缓存输入策略、工具调用开销以及后续展开的次数。 确切的契约、威胁模型和当前测量结果位于 [`docs/context.md`](docs/context.md)。 针对此项目或其他语料库运行 fail-closed proof 门控： ``` scripts/context-proof.sh . "How does CorpusBuilder build and verify the semantic graph?" ``` 要通过多个 OpenRouter 模型进行付费的端到端 A/B 验证，请启用可选的 HTTP 功能并显式提供凭证文件： ``` cargo run --features openrouter --bin symgliph-openrouter-proof -- . \ --env-file /path/to/openrouter.env ``` 运行器使用完整和打包的上下文，向 Claude Haiku 4.5、Gemini 2.5 Flash 和 GPT-4.1 Mini 发送相同的三个源代码问题。盲审评分员根据固定的评分标准对两个答案进行打分。报告包含原生提供商 token 使用情况、计费额度、延迟、答案、来源以及每个单独的通过/失败断言。此命令会消耗 API 额度；其默认报告路径为 `.symglyph/openrouter-proof.json`。 ## 制品契约 对于语料库 `X`，此版本生成： ``` A(X) = (corpus root, semantic graph, semantic root, SVG glyph, source index) ``` 语料库根提交到包含策略、排序的可移植路径、文件大小和精确的文件摘要。语义根独立提交到分析器版本、定义、引用、解析的图边以及精确的源范围。SVG 将两个根和 schema 作为机器可读属性嵌入。其内部解析环显示了提取的引用中无歧义链接的比例。清单是紧凑视觉对象和精确源之间的桥梁。 `manifest.json` 旨在用于检查和交换。 `manifest.symglyph` 是一个带有显式 payload 长度和 BLAKE3 校验和的版本化 Postcard 制品。CLI 更倾向于使用二进制制品进行验证，并通过 `--manifest` 接受任一格式。 内置的 Tree-sitter Rust 分析器目前提取函数、结构体、枚举、trait、类型别名、常量、静态变量、模块、实现、宏和导入。嵌套定义通过 `contains` 边连接。调用、宏调用和导入目标作为引用保留。仅当语料库包含一个明确的目标时，引用才会成为边；否则，它将明确保持未解析状态。 当语料库根包含 `Cargo.toml` 时，Symgliph 使用 `cargo metadata --no-deps` 为工作区符号命名空间，解析 `crate::` 路径和本地导入别名，并区分直接依赖项引用与未知引用。 不执行任何项目代码或构建脚本。使用 `CorpusBuilder::discover_cargo(false)` 进行仅语法构建。 [`Analyzer`](https://docs.rs/symgliph/latest/symgliph/trait.Analyzer.html) 是用于附加语言和特定领域分析的扩展边界。 内置的 Markdown 分析器创建一个文档节点和精确的标题分隔的章节节点。这允许大型 prompt 库检索后期约束和输出指令，而无需将 Markdown 视为代码。 要使用本地 Fabric 检出和 OpenRouter 凭证文件重现外部 Fabric 模式实验： ``` scripts/fabric-proof.sh /path/to/Fabric /path/to/openrouter.env ``` 该脚本确定性地选择 24 个模式，将它们作为单独的语料库进行编译，并通过三个模型提供商运行六个模式恢复问题。 它会消耗 API 额度，并在 `.symglyph/` 下保留子集来源和详细报告。 要运行更强的盲发现变体（回答者仅接收未命名的用户目标）： ``` scripts/fabric-discovery-proof.sh /path/to/Fabric /path/to/openrouter.env ``` 这将在编译的模式文档上增加一次批处理的语义搜索过程，仅将前三个候选名称注入到已验证的上下文打包中，并断言语义召回、源检索、精确的最终选择、token 和成本降低、完成度以及质量非劣性。六案例基准测试是 [`benchmarks/fabric-discovery.json`](benchmarks/fabric-discovery.json)；方法论和测量结果见 [`docs/context.md`](docs/context.md)。 ## 语义路由黄金数据集 可选的 `golden` 功能为盲路由构建和验证链接的 Hugging Face 数据集包，而不是将所有内容展平为 prompt/答案对： ``` cargo run --features golden --bin symgliph-golden -- build-fabric \ --subset .symglyph/fabric-subsets/befdfeefb2402db706f4b54165b8a47ef2cedbad-24 \ --proof .symglyph/fabric-discovery-openrouter-proof-befdfeefb240.json ``` 已提交的 Fabric 种子包含语料库、查询、qrels、精确证据、困难负样本、来源、确定性数据集根和 fail-closed 验证报告。它被明确指定为 `collection_tier: gold`，而专家裁决仍保持独立状态。`scripts/toolret-golden.sh` 在本地导入固定的 44,453 个工具的 ToolRet 语料库，但将其标记为不可发布，因为其聚合的 Hub 存储库未声明许可证。完整的 schema、当前计数、合并工作流和专家裁决路径位于 [`docs/golden-set.md`](docs/golden-set.md)。 ## 百万行规模门控 ``` scripts/scale-gate.sh ``` 该门控确定性地生成一百万行 Rust 代码，构建并往返完整的制品，测量 JSON 和二进制大小，构建二级索引，运行 100,000 次名称和 ID 查询，并捕获峰值 RSS。 可以使用脚本中定义的 `SYMGLIPH_SCALE_*` 和 `SYMGLIPH_MAX_*` 环境变量覆盖阈值和语料库大小。 方法论、当前测量结果和注意事项记录在 [`docs/scale.md`](docs/scale.md)。 ## 设计原则 1. **诚实：** 不会声称仅凭像素即可重构语料库。 2. **确定性：** 未更改的包含字节和策略生成一个根。 3. **可验证：** 解析的证据根据其记录的摘要进行检查。 4. **可移植：** 清单使用有序记录和正斜杠路径。 5. **可检查：** JSON 和 SVG 是开放的纯文本格式。 6. **小核心：** 可视化代码使用标准库，而不是庞大的图形框架。 ## 许可证 根据您的选择，根据 Apache License 2.0 或 MIT 许可证获得许可。 ## 社区和安全 欢迎通过 [`CONTRIBUTING.md`](CONTRIBUTING.md) 贡献。请按照 [`SECURITY.md`](SECURITY.md) 中的说明，使用私密的 GitHub Security Advisories 报告漏洞。参与受 [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md) 管理。

标签：IaC 扫描, Rust, SOC Prime, 人工智能上下文, 代码分析, 凭证管理, 可视化界面, 密码哈希, 开发工具, 数据压缩, 编译器, 网络流量审计, 语义图, 通知系统