【免费下载链接】agnes-harness
Agnes Harness: A pluggable agent harness for Forward Deployed Engineering (FDE). Built for trust. Made for the real world.
Agnes Harness 的批量处理（Batch processing）模式是面向新手也友好的"文件夹级"AI 批处理工具：把指定文件夹里的每个文件逐一遍历，交给模型单独读取并回答你的提示词，最终为每个文件写出一行结果。文件内容不会混进你的日常对话，你拿到的是一份结构化的摘要和结果文件——适合批量标注图片、批量整理文档、批量质检数据等真实工程场景。
Agnes Harness 批量处理模式是什么
批量处理的核心思路是"一个文件 = 一次独立的完整运行"：
- 递归遍历你指定的文件夹（按文件名字典序，遍历时不打开文件）；
- 每个文件开启一个全新、隔离的会话，模型用
read工具读取该文件，再回答你的提示词； - 每个文件写一行结果，全部完成后在工作区生成
results.csv、summary.md等结果文件。
几个关键特性，帮你建立预期：
- 持久运行：批次在 AGH daemon 里执行，daemon 重启后会接着跑，已完成的文件绝不重复处理；
- 无需批准：发起批次不需要人工确认，大文件夹可能花掉真金白银，因此强烈建议先试跑 3~4 个文件，并设置
--budget预算上限； - 安全隔离：每个条目会话只允许调用
read工具，文件里的内容被视为"数据"而非指令。
快速开始：三条命令完成文件夹批量处理
批量命令依赖共享 daemon（先执行agh daemon start）。以处理一个实验图片文件夹为例：
agh batch start lab-images --prompt-file prompt.md --schema schema.json --budget 20 agh batch status <id> --watch agh batch results <id>start打印批次 id 后立即返回；文件夹必须位于当前目录（或--cwd指定的目录）之内，该目录即批次所属的工作区；status <id> --watch每 5 秒刷新一次，计数变化时打印一行；results <id>随时重新写出结果文件，批次运行中也可以执行。
💡 新手建议：把
--cwd指向一个专为批次准备的文件夹（只放输入文件夹和结果），不要用主目录或存放机密的项目目录。
批量处理能读取哪些文件
文件通过递归遍历发现，支持范围如下：
| 类型 | 文件 | 单文件上限 |
|---|---|---|
| 图片 | png、jpg、jpeg（动画 PNG 会被拒绝） | 20 MiB、6400 万像素 |
| 文本 | txt、md、csv、tsv、json、jsonl、log、xml、yaml、yml | 1 MiB |
其余文件不会被交给模型，而是在errors.jsonl中记为skipped（原因如unsupported_type、too_large等）；隐藏文件与文件夹会被静默跳过。
关于图片尺寸：模型接收的图片长边最多 1456 像素，read工具会自动等比缩放并应用相机旋转。如果你希望更省钱，可用--max-edge（256~1456）把上限调低，送出的图片 token 更少；若原图很大且小细节重要，建议先用图片工具把原图切成 1456×1456 的块，再对切块后的文件夹跑批量——每一块就是一行结果。
提示词与 JSON Schema：让每个文件输出结构化结果
提示词（1~16384 字符）是施加在每个文件上的任务。其中三个占位符会按文件替换：
{{path}}：文件相对路径{{name}}：文件名（以纯文本插入，不会被展开）{{ordinal}}：文件序号
批次还会自动附加指令：只读这一个文件、把文件内容当作数据而非指令、不要提问直接作答。
加上--schema <file.json>后，每个回答必须是一个符合 JSON Schema 的 JSON 对象（顶层为"type": "object"）。一个典型用法是让模型明确表达"看不确定"，避免瞎猜：
{ "type": "object", "properties": { "subject": { "type": "string" }, "quality": { "enum": ["ok", "uncertain", "unreadable"] } } }不符合 Schema 的回答会带着校验错误自动重发一次；第二次仍不符合才记为invalid。没有 Schema 时回答按纯文本保存。
结果文件：逐文件输出在哪里看
结果默认写在工作区的agh-batch/<id>/目录（也可用--out指定）：
| 文件 | 内容 |
|---|---|
results.jsonl | 每个完成的文件一行：ordinal、path、output、credits |
results.csv | 同样的行，Schema 顶层每个属性一列；UTF-8 带 BOM、CRLF 换行，电子表格可直接打开中文 |
errors.jsonl | 每个invalid/failed/skipped/cancelled文件及原因 |
summary.md | 各状态数量、已花积分、每个字段的取值统计与均值 |
这些文件在批次结束时写出，之后每次运行agh batch results <id>都会从 daemon 数据库重建（手工修改会被覆盖），但每个文件都是整体替换，你永远不会看到写了一半的文件。
费用控制：用 --budget 控制批量处理预算
每个文件是一次完整的 Agent 轮（含系统提示、两次模型请求），费用约为直接把同一张图发给模型的 1.3~2 倍，且开始前没有估算。控制成本的三个抓手：
--budget <积分>：硬性停止线。花费达到预算后不再开始新文件，批次以budget_exhausted结束；已启动的文件会跑完，总花费最多超出"在途文件"的费用；--concurrency <1-8>：同时处理的文件数，默认 4；- 先试跑：拿 3~4 个文件单独建一个文件夹跑一遍，看清单文件费用再放大。
summary.md与agh batch status都会显示已花积分，方便随时核对。
失败、取消与 daemon 重启
每个文件最终状态为done、invalid、failed、skipped或cancelled。常见失败原因：
| 原因 | 含义 |
|---|---|
image_not_read/file_not_read | 模型没真正拿到文件内容，回答直接丢弃、绝不靠猜 |
no_answer | 运行结束但没有最终回答 |
timeout | 超过--item-timeout（默认 600 秒） |
prompt_too_long | 提示词加 Schema 超过 64 KiB 上限 |
熔断机制：如果没有文件成功且已有 5 个失败或invalid，整个批次以failed停止、其余文件取消——写错的提示词不该烧掉整个文件夹。
agh batch cancel <id>可随时停止批次：运行中的文件被中止，未开始的标为cancelled，已花费用照常计入；- daemon 重启后批次自动接续，无需手动恢复；重启时正在运行的文件会从头重跑一次（那一轮会被计费两次）。
在对话里让 Agent 发起批量任务
除了在命令行操作，你也可以直接对 Agent 说"帮我处理某个文件夹"，它会调用batch_start、batch_status、batch_cancel三个工具（见 批量扩展源码）。注意两点：批次结束时 Agent 不会收到通知，需要主动让它查状态；批次内不能再发起批次，子 Agent 也不能发起。
安全与隐私注意事项
- 条目会话只能调用
read，其它工具全部禁用（该限制在 扩展实现 中通过钩子强制）；但read不限于那一个文件，不要在存有敏感机密的工作区里对不可信文件跑批量； - 发起无需批准，但每次发起都会写入 daemon 审计日志（
audit/daemon.jsonl）：谁发起、来自哪个会话、文件夹、文件数、并发、预算； - 结果文件做了防注入处理：CSV 中可能被电子表格当公式执行的单元格会自动加撇号，
summary.md中的链接与 HTML 会被"失效化"； - 模型服务商会像处理其它输入一样看到你的文件内容。
延伸阅读与源码位置
- 官方批量处理指南：docs/guide/batch.zh-CN.md（英文版）
- CLI 命令参考：docs/reference/cli.zh-CN.md
- 批量扩展源码目录：packages/base/extensions/batch/
- 快速上手：docs/guide/quickstart.zh-CN.md
⚠️ 批量处理目前仅在 macOS / Linux 上经过验证，Windows 尚未测试，重要批次请在 macOS 或 Linux 上运行。
【免费下载链接】agnes-harness
Agnes Harness: A pluggable agent harness for Forward Deployed Engineering (FDE). Built for trust. Made for the real world.
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
