用途
Hirð 是一门运行在 BEAM（Erlang 虚拟机）上的类型化语言，目标是为长期运行的 LLM 智能体系统提供可审计、可重放的开发基础。Python 智能体框架常将副作用隐藏在协程中，而 Hirð 让每次工具调用、每条 Actor 消息和每个监督边界都在类型中可见，并可供工具查询。
主要能力
效应行追踪与工具审计
Hirð 没有环境自带的 print。程序向外界输出必须通过“工具”——一种已声明、有类型、被审计的外部操作。声明 tool Say 会创建效应 Tool<Say> 以及可调用的 say。handle 块提供实现并消除该效应，因此 main 的效应可honestly标注为 ! {}。无论模拟调用还是真实调用，都会以同一种规范 JSON 行格式无条件写入审计流。
记录与回放
由于审计流完整记录每次调用的全部参数和带标签结果，一次记录运行就是一个可重放的环境。回放游标优先于所有 handle 和 install 块，因此回放时不运行任何工具、不接触任何服务，每个调用获得日志中记录的结果（包括失败）。匹配是严格的：每个位置的调用必须与日志记录一致，否则以 replay_divergence 崩溃，并指明位置、记录调用与所提供调用。已检入的记录可作为无需维护 oracle 的回归测试，也可作为固定环境对比程序变体。
类型化 Actor 与 OTP 监督
Hirð 程序不是执行完就退出的脚本：fn main 可以启动监督树并“驻留”，在自己的工作完成后继续让类型化 Actor 提供服务，按时钟能力驱动周期性轮次，在声明的预算内崩溃并重启，每一轮都进入审计流。示例 demo/agent_fleet 演示了三个受监督 Actor 在故意崩溃后继续工作：FleetSup 使用 rest_for_one 策略，崩溃点下游的 auditor 随之重启，planner 保留轮次计数。Actor 状态随进程消亡，审计流是持久记录。监督树本身可查询，其效应图即系统的实时组织图。
MCP 编译器查询
hird-mcp 是覆盖同一编译器管线的 Model Context Protocol 服务器，通过 stdio 通信，为 LLM 智能体提供结构化编译器查询，而非读源码猜测。工具包括：check_file（所有诊断含警告）、list_definitions（模块大纲及各符号 token 成本）、infer_type、lookup_definition、explain_effect_row、render_ir_fragment、explain_actor_protocol、emit_actor_effect_graph、get_context_for_symbol（token 预算感知的符号摘要）和 get_context_budget。错误以结构化形式返回：未定义名称会列出可用名称，解析和类型错误带编码诊断，智能体可仅凭工具输出自我纠正。服务器自描述：将面向智能体的写作指南、解析器代码索引和 phrasebook 作为 MCP 资源提供，并提供一个 prompt（author_supervised_module）来编排“先写后验证”循环。
LSP 与编辑器支持
hird-lsp 是覆盖编译器前端的 Language Server Protocol 服务器，通过 stdio 通信：打开和保存时诊断、悬停显示推断类型与效应行、顶层声明跳转定义。tree-sitter-hird 提供 v0.1 表面语法的 tree-sitter 语法及高亮、缩进、折叠查询。
使用方式
发布版附带 Linux、macOS 和 Windows 预编译二进制。解压对应平台归档，将 hird（编译器）、hird-lsp 和 hird-mcp 放入 PATH。从源码构建需 Rust 1.97 或更新版本；使用 Nix 时三个二进制作为 flake 输出提供（nix run github:no-materials/hird#hird-mcp）。编译和运行程序需要 PATH 中有 Erlang/OTP（apt install erlang、brew install erlang 等）；hird check 不需要。
最小可观察程序示例（保存为 hello.hird）需声明工具、提供 handle 实现并调用，从而产生一次被审计的工具调用。ASCII 操作符拼写（->)在词法阶段会规范化为 Unicode 形式（→），两者均为合法输入。
docs/writing-hird-human.md 是引导式教程，phrasebook.md 是密集语法参考。
仓库附带项目级 .mcp.json，在此启动的 Claude Code 会话会自动拾取该服务器（它启动 nix run .#hird-mcp；先运行一次 nix build .#hird-mcp 可避免首次会话等待冷构建）。其他 MCP 客户端可直接启动 hird-mcp 二进制，无需参数。
运行演示：hird demo 无参数运行，无需安装 Erlang 以外的东西，自己记录 episode 并针对三个变体重放；hird run demo/agent_fleet 运行三守护者持续工作的示例。
适用场景
- LLM 智能体系统的开发与回归测试：通过记录回放实现无需 oracle 的回归测试，以及固定环境下对比程序变体。
- 需要长期驻留、崩溃恢复、周期性作业的智能体服务：利用类型化 Actor 和 OTP 监督。
- 需要审计每一次外部调用的合规或调试场景：审计流完整记录所有工具调用。
- LLM 智能体辅助编程：通过 MCP 工具查询编译器，获取类型、定义、效应行、IR 片段、Actor 协议和效应图，自我验证代码。
- 编辑器内开发：通过 LSP 获得诊断、悬停类型、跳转定义。
限制
项目状态为 pre-1.0 实验性。v0.1 编译器管线端到端可用（演示可类型检查、编译为 Erlang 并在 BEAM 上运行），但语言表面不稳定，未发布到 crates.io，破坏性变更不经过弃用周期。路线图位于仓库内 issue tracker（见 .beads/README.md）。MSRV 为 Rust 1.97（edition 2024）。BEAM 相关测试在 PATH 中无 erlc 时自动跳过。审计流的保证与不保证见 docs/audit-evidence.md；工具效应与回放的规范格式见 docs/tool-effects.md。
