智能体编辑为何需要语义身份：用 Rust 构建 SEMAPRAX

编码智能体应按照声明的身份和预期语义进行编辑，而不是依赖可能已经过时的行号。在 SEMAPRAX 中，持久声明 ID 不受普通源码移动影响，已检查 HIR 集中保存解析后的语义，绑定修订版的补丁则会在源码快照改变时封闭失败。Rust 类型系统让这些区别在编译器中变得明确。

本文讲解 pre-alpha 研究编译器中已经实现的设计。即使你不采用这种语言，这些边界也适用于重构引擎、编译器服务和需要把意图转化为可审查变更的智能体工具。

为什么行号和字节偏移不是可靠的编辑目标？

文本编辑通常表达为“替换第 418 到 463 字节”。这个地址只描述某个文件快照，而不是智能体真正想修改的程序实体。格式化、注释或并发编辑都会使它漂移。名称稍好，但作用域、重载和重命名也会让名称依赖上下文。

因此，SEMAPRAX 契约把人类可读的 .spx 源码作为规范 Git 投影，并把版本化语义图作为首选智能体接口。公共声明携带持久 @id 身份。表达式身份只在修订版内有效，因为让每个瞬时语法节点跨任意重写保持身份，会做出超出编译器能力的承诺。SEMAPRAX 语言与编译器契约规定了这一区分。

Rust 如何编码身份边界？

HIR 并非到处传递裸字符串，而是定义了不同的 newtype：

pub struct DeclarationId(String);
pub struct ExpressionId(String);

pub struct ResolvedFunction {
    pub id: DeclarationId,
    // 已检查的签名、函数体和效果
}

这个缩短后的示例对应已审计修订版 src/hir.rs 中的类型。需要持久声明目标的函数无法意外收到表达式地址。编译器必须执行显式转换，否则拒绝操作。

同一模块用 BTreeMap 保存声明索引，用 BTreeSet 保存关系集合。有序集合本身不足以保证确定性，但可以消除随机哈希迭代造成的输出漂移。在顺序影响执行时，仍必须保留语义顺序。

为什么只解析一次并生成已检查 HIR？

如果图导出器、原生后端和 Wasm 后端各自从语法重建含义，它们可能对类型、所有权或调用目标产生不同解释。SEMAPRAX 先解析和验证，再让下游投影使用已检查表示。公开的架构与信任边界文档描述了该流程，并区分已实现通道与未来权限。

1. 解析人类可读源码。
2. 把名称和持久身份解析为 HIR。
3. 验证当前语言子集允许的类型、效果、所有权规则和契约。
4. 从已检查语义生成确定性图 JSON 或目标产物。
5. 把变更绑定到源码修订版和预期语义目标。

图是编译器投影，不是第二个事实来源。Git 仍然审查源码，智能体则获得结构化上下文。

语义图如何做到确定性？

确定性是整个流水线的属性。如果边的顺序每次运行都变化，稳定节点 ID 也无济于事。SEMAPRAX 的 Rust 图投影使用有序索引、显式序列化、受限遍历和规范输出规则。

不能为了让 JSON 更美观而重新排序执行向量。求值和清理顺序属于语义。规范排序只适用于数学上无序的集合。

证据如何约束智能体补丁？

序列化证据胶囊应说明补丁为何可接受，但持有胶囊不能自动获得写权限。SEMAPRAX 将证明数据与拥有提交权限的组件分开。补丁路径先取得普通锁，独立重放精确且受限的证据，检查当前源码快照，然后才暂存候选变更。补丁证据实现清楚地区分重放与应用。

• 过期意图：补丁只对旧修订版有效。
• 错误目标：文本仍然匹配，但现在指向另一项声明。
• 伪造置信：调用方给出貌似可信的报告，却没有复现检查。

独立重放不能证明某项功能值得实现。它证明一个更窄且可测试的事实：受限提案仍满足其证据所绑定的编译器检查。

Rust 编译器和智能体工具可以借鉴什么？

1. 使用领域 newtype：在类型层区分持久实体、修订版局部节点、摘要和能力。
2. 保持单一已检查语义核心：让图和后端使用解析后的含义。
3. 明确设计确定性：规定顺序、序列化、诊断与失败行为，并逐字节比较重复运行。
4. 把编辑绑定到快照：没有源码摘要的语义目标仍会漂移。
5. 让证据不带权限：在权限边界内重放证据，然后才能暂存变更。
6. 公开限制：完成矩阵可以避免把单一通道的证据扩张为针对所有目标的声明。

SEMAPRAX 通过证据门控的完成矩阵实践最后一项。

SEMAPRAX 尚未证明什么？

SEMAPRAX v0.2 是实验性 pre-alpha 研究。当前仓库记录了受限的原生 C11/Clang 与 WebAssembly Core 通道、确定性语义工具和不断扩展的已验证子集。它不声称生产就绪、完整内存安全、支持所有操作系统、完整所有权系统、全面生态互操作、公开 Component Model 运行时或真实经济权限。

评估项目时应检查源码与带日期的证据，而不是从远期目标推断。请从 SEMAPRAX 架构概览开始，并将公开声明与固定编译器修订版对照。

如何复现本文过程？

git clone https://github.com/wavect/semaprax.git
cd semaprax
git checkout ca339feffcadf77a679abe2f159376287cf2e22c
cargo run -- graph examples/hello.spx

该命令检查本文所用精确修订版的图投影。只有运行仓库记录的质量门后，才能把本地修改视为证据。

编辑披露：OpenAI Codex 协助了起草和翻译。Wavect 对照 SEMAPRAX 提交 ca339fe核查了技术声明与代码引用。本文没有从模型输出推断性能或安全声明。