For AI agents: the complete documentation index is available at https://a3s-lab.github.io/ash/llms.txt, the full documentation bundle is available at https://a3s-lab.github.io/ash/llms-full.txt, and this page is available as Markdown at https://a3s-lab.github.io/ash/guide/protocol.md.
  • 简体中文
  • next
  • ASH/1 协议

    ASH/1 是 Coding Agent Harness 与 ash 之间的本地机器协议。它不是 POSIX Shell 语言,也不解析 Bash、Zsh、PowerShell 或 CMD 语法。

    两种传输

    • ash rpc:长驻会话。每个 ASON 文档前有 4 字节大端长度,先握手,再并发处理请求。
    • ash run:从标准输入读取一个裸规范 ASON 文档,执行后退出。

    rpc 的第一个帧必须是握手请求。服务端选择兼容协议版本、限制与能力交集,返回唯一 规范握手响应;非规范 ASON、超长帧和未知必需字段在分配大缓冲区前拒绝。

    核心操作

    操作作用
    execexecutable + argv 直接启动、环境差量、stdin、超时与进程树取消
    read有界字节或行范围读取与投影
    list稳定顺序目录遍历和元数据
    search有界文本搜索、匹配上下文与完整结果引用
    patch带 preimage 摘要的 compare-and-swap 多文件补丁
    fscreate/copy/move/remove 文件事务
    snapshot工作区清单与基于引用的 delta
    batch有向无环依赖图、就绪节点并发和失败后代跳过
    / # ? - | >对保留结果执行切片、搜索、释放、投影与安全落盘
    cancel取消排队或运行中的请求及其后代

    数据公式

    引用操作直接把数学符号作为操作码,不再使用通用 ref 包装或第二层判别字段:

    o:|
    a:[@7,d,0,64,p,l,t]

    它是 @7π_{p,l,t}(d[0:64]) 的紧凑线性编码。/ # ? - | > 分别表示字节切片、行切片、搜索、释放、表格投影和工作区落盘。每个公式的参数数量固定;> 还要求工作区写权限,并复用带日志、禁止覆盖的文件事务。六条公式在锁定的两种 tokenizer 中均为 80 Token,与直接 ASCII 字母的最低值相同,低于希腊字形的 86/86 和旧包装结构的 97/98。

    无损进程证据

    exec 并发排空 stdout 与 stderr。每路最多在内存保留 4 MiB,超过后把完整原始字节 溢写到会话私有临时文件,只留下有界首尾样本供即时投影。两路 Alias 原子发布,/ 公式可直接读取所需磁盘范围;会话额度不足时返回 601,不产生半截引用。释放引用或 结束会话后,会在最后一个活动租约结束时删除对应临时文件。

    完整 UTF-8 输出会先把 CRLF 归一化为 LF,再将连续相同行 ℓ^N 投影成首行 和 计数标记 ×NN 包含保留的首行,并且只有标记比被省略内容更短时才折叠。Rayon 可以并行查找大输入中的重复段,但边界按源顺序归并;Worker 数不会改变结果。任何归一化 或折叠都会设置结果标志并保留完整源引用,所以 ×N 无需承担可逆转义语法。

    第二遍处理重复块:含 K 行的块 B 连续出现 N 次时投影为一个 B×N#K, 其中 2 <= K <= 32。每个位置先选节省字节最多的候选,再按更小 K、更大 N 决胜; 不节省字节就保持原文。候选搜索与大范围验证进入 Rayon,但每个被省略的块最终都与保留块 逐字节相等。哈希碰撞和 Worker 数都不能改变结果,完整源引用仍是权威证据。

    非成功原生退出(非零码或信号)会进行第三遍诊断聚焦。它只处理完整 UTF-8 stdout/stderr,固定保留首尾各两行, 并保留每个错误锚点之前两行、之后六行。其余连续区间只有在节省字节时才替换为 ⋯NN 是被省略的逻辑行数。ASCII 诊断词按完整词匹配;TypeErrorIOException 这类标识符 按精确 ErrorException 后缀识别。分类可进入 Rayon,窗口并集和编码仍按源顺序。 没有锚点就不归约;成功、超时、取消、二进制和磁盘首尾样本维持原路径。任何已聚焦流都 保留完整原始引用。

    每个 spool 都带版本所有权标记和生命周期锁。后续进程只回收超过一小时、已无活动锁且 全部内容可识别的 ash 目录;无法证明安全时不修改目录。

    超时或取消会终止并等待整个 Unix 进程组或 Windows Job Object,再等待两路管道 EOF。 终止类型 3 表示所属子孙进程与管道已完成清理,不只是已经发出取消信号。

    并发与顺序

    长驻 RPC 可以同时运行相互独立的请求。最终帧仍按输入序列稳定输出,因此模型端不需要 为调度竞争增加排序 Token。取消控制帧可以越过最终响应排序,及时终止目标工作。

    能力与 Permit

    握手只协商双方都支持的能力位。策略需要批准时,ash 返回结构化 Challenge;可信 Harness 签发的一次性 Permit 绑定会话、请求、规范动作、策略指纹和过期时间。重放、 跨会话复用或动作修改都会失败。

    完整字段与规范 Fixture 位于 docs/protocol.mdspec/fixtures/ason