Agented — 代理的

agented（二进制：ae） ae 是一个由命令行动词控制的有状态编辑器。状态在会话之间保持在一个 SQLite 支持的工作空间中（.agented/state.db）。每个编辑都是版本化的，存在于一个撤消树中 —— 你可以分支、跳转到任何过去的状态，并且永远不会丢失工作。 使用此工具时： 你需要在一个仓库中跨多个步骤编辑一个或多个文件，并且想要一个持久的历史记录。 你想要为你的未来自己或其他代理（注释）留下笔记，这些笔记附加到特定的文件中。 你想要安全的多文件重构，具有全部或无事务语义。 不要使用此工具进行： 仓库概览/架构的阅读（使用普通的 cat/grep）。 单次编辑，你不关心历史记录（使用平台的内置编辑器）。 任何非文本内容（不支持二进制文件）。 编辑器如何为你强制正确性： 每个读取操作都返回一个 state_token。将其传递给你的下一个写入操作，使用 --expect。如果文件在你下面更改了，写入操作将被拒绝（退出代码 3），并且响应将包含新的内容和新的令牌。使用新的令牌重试。你不需要“查看然后写入”—— 编辑器将告诉你你的假设是否过时。你不需要“分支然后撤消”—— 撤消的错误包含分支，如果存在歧义。你不需要“状态然后编辑”—— 每个操作的响应都包含你想要检查的状态。 默认情况下，concurrency.require_expect：警告：没有 --expect 的写入操作将成功并发出 stderr 警告。对于多代理设置，设置 require_expect：写入 .agented/config.json 中以强制执行严格的预写检查。在任一模式下，实际冲突（过时的 --expect 值）将被拒绝，退出代码为 3，并包含恢复有效负载 —— 树永远不会默默地丢失工作。 在代理上下文中，短形式是默认的。长形式存在于文档和人类读者中；代理调用应该使用较短的形式来节省令牌。 ae s foo.go -r 12:14 -w "..." -x ab12cd34 是规范形状，而不是 ae replace foo.go --range 12:14 --with "..." --expect ab12cd34。 对于多行内容，通过 -i（--from-stdin）管道或使用 -f （--text-file）。当管道时，stdin 会自动检测，因此 cat patch.txt | ae s foo.go -r 12:14 -i 和 echo "..." | ae i foo.go -A 0 -i 可以正常工作，而无需引用技巧。 第一次触摸规则： 你第一次在会话中触摸一个文件时，必须通过 ae open 进行。不是 Read，也不是 Edit，也不是 cat。响应是会话其余部分的输入。ae open 返回六件事情：文件的 id、行数、head_edit_id、内容哈希、state_token 和任何活动的内联注释。将该响应视为权威的。 注释是由之前的会话为你留下的。阅读它们。state_token 线程向前到你的下一个写入操作中。line_count 告诉你你的文件形状假设是否匹配。ae open 也是文件创建原语。如果路径在磁盘上不存在，ae 将在那里创建一个空文件并在工作空间中注册它。没有 touch 首先，没有 --create 标志。新文件流是 ae open foo.go → ae i foo.go -A 0 -i（从 stdin 插入内容）→ ae w foo.go。相同的调用同时涵盖“打开此现有文件”和“创建此新文件”；响应形状在两种情况下都是相同的。跳过此步骤会使你付出代价。如果你首先读取，代理运行时具有字节，但编辑器不知道你已经看到该文件。随后的写入操作通过 ae 将以新鲜的行为者身份对待你，并可能出现原本不会发生的冲突。如果你通过 ae open 读取，编辑器知道你的起点，你的写入操作将清晰地线程化，并且工作空间历史记录将显示你的会话作为一系列编辑的连贯序列，而不是陌生人的驱动。 训练习惯（“阅读然后写入以确保安全”）在这里不适用。ae 通过全内容拒绝有效负载报告漂移。会话开始时只读取一次。编辑向前。往返经济：不要过度获取。 大多数 LLM 都是在 Read → Edit → Read → Edit 的基础上训练的，并且会以相同的形状使用 ae。不要这样做。ae 的合同消除了几乎每个“先查看以确保安全”的往返。 特定的反模式： 不要在 ae replace/insert/delete 之前使用 ae view。你已经从 ae open（或 ae search）中知道了行范围。如果你错了，写入操作将被拒绝，附带当前内容（退出代码 3）；你可以调和并重试。成功或冲突只需一次往返。先查看会在每次成功或失败时都浪费一次往返。 不要在 ae search 之前使用 ae view。搜索返回每个匹配的行\tcol\ttext。这就是答案。如果你需要周围的上下文，只有在之后才查看。 不要在读取之前加载。自动加载在默认情况下已启用。每个写入操作都使用 stat 文件并在自身中调和磁盘更改。ae load 仅用于你特意想要捕获磁盘快照作为编辑而不修改其他内容的罕见情况。 不要仅仅为了重新获取 state_token 而调用 ae status。每个写入操作都返回结果中的新令牌。将其线程化向前。调用 ae status 的唯一原因是当你明确需要工作时。