tiny-runtime — agent batch and progress tools by AVRG3

tiny-runtime — 用于 API 分页、重试循环和工具进度的 MCP 工具

由 AVRG3 为 Agent 开发者打造的三个确定性辅助工具：完成分页任务、中断没有进展的重复工作，以及向缓存调度器报告工具进度。不会调用模型、训练、创建账户或收集遥测数据。

版本 0.1.1： 库、CLI 和独立的三工具 MCP 服务。不会调用模型或收集遥测数据。缓存桥接需要兼容的推理服务集成；它本身无法控制托管模型的缓存，也无法控制原版 vLLM。

按任务查找工具并查看输入示例 · 实际工具 schema · 公开安装。

公开安装

需要 Node.js 20+。无需 npm 账户或检出源码。

Claude Code：

claude mcp add tiny-runtime -- npx -y -p https://github.com/Warddamn/tiny-tools/releases/download/runtime-v0.1.1/tiny-runtime-0.1.1.tgz tiny-runtime-mcp

**Cursor、Claude Desktop 和其他 stdio MCP 客户端：**添加此服务配置。VS Code 使用 servers，而不是 mcpServers。

{"mcpServers":{"tiny-runtime":{"command":"npx","args":["-y","-p","https://github.com/Warddamn/tiny-tools/releases/download/runtime-v0.1.1/tiny-runtime-0.1.1.tgz","tiny-runtime-mcp"]}}}

**兼容 MCPB 的客户端：**下载便携包并打开。它包含适用于 macOS、Windows 和 Linux 的依赖项；需要 Node.js 运行时。软件包未签名；发布校验和与注册表哈希可用于验证完整性。较小的 npx tarball 会在安装时下载第三方依赖项。

**Claude Code 插件：**运行 /plugin marketplace add Warddamn/tiny-tools，然后运行 /plugin install tiny-runtime@tiny-tools。这也会添加用法指南。请选择插件或手动配置 MCP。

三个附带预期答案的完整示例 · GitHub 下载 · 官方 MCP 注册表

**JavaScript/TypeScript 库：**使用 npm install https://github.com/Warddamn/tiny-tools/releases/download/runtime-v0.1.1/tiny-runtime-0.1.1.tgz 安装同一个公开 tarball，然后从 @tiny_tools_pw/runtime 导入 collectPages、RepeatGuard 或 ProgressBridge。这是托管在 GitHub 上的软件包，不是 npm 注册表条目。

各部分的作用

• **collect_pages / collectPages：**跟踪已配置的游标源，验证完整页面，根据可选的记录 ID 去重，汇总精确整数型字段，并返回 complete、partial 或 failed。持久化检查点可让新一轮运行从最后一个已提交页面之后继续。
• **check_progress / RepeatGuard / runGuarded：**将操作与可信状态指纹进行比较。默认会阻止第四次重复停滞；在实际编辑后允许再次测试，并能识别重复的状态转换。跟踪分析仅供参考；SDK 封装器会在执行工具前强制执行判定。
• **plan_cache / ProgressReporter / ProgressBridge：**报告经过测量的工作单元，不向模型发送工具内容。它会保守估算剩余时间，综合考虑并行调用，并发出会过期的 retain、prefetch 或 release 提示。宿主适配器会应用这些提示；MCP 工具只会写入计划。

这些功能解决的是已知的工程问题，而非此前尚未覆盖的类别。MCPProxy 已提供批处理和分页方案；其他项目也实现了循环检测和缓存。此软件包专注于明确的失败语义、可复用的集成和测试。它不是适用于所有 MCP 服务的通用代理。

从检出目录运行

需要 Node.js 20+。在仓库根目录中运行：

npm ci
npm run build
npm run demo:runtime
node packages/runtime/dist/cli.js collect packages/runtime/examples/collect.json --output-dir /tmp/runtime-results
node packages/runtime/dist/cli.js check packages/runtime/examples/guard-trace.json --output-dir /tmp/runtime-results
node packages/runtime/dist/cli.js plan packages/runtime/examples/progress-trace.json --output-dir /tmp/runtime-results

每个任务都会创建自己的目录，并返回绝对制品路径。CLI 成功完成工作时退出代码为 0；发生错误或采集不完整时为 1。部分记录及其检查点仍会保留。不会覆盖任何输入文件。在支持的系统上，任务输出文件仅所有者可访问；但仍需注意父目录的权限。

对于 MCP 客户端，请将示例路径替换为你实际检出目录的路径：

{"mcpServers":{"tiny-runtime":{"command":"node","args":["/absolute/path/tiny-tools/packages/runtime/dist/mcp.js"]}}}

将这段 8 行的用法代码片段添加到 Agent 指令中。若要在不增加额外模型轮次的情况下自动运行，请集成 SDK，而不是让模型反复调用跟踪分析工具。

批量采集

随附的 examples/collect.json 会读取本地合成页面清单。文件源是一个包含 pages 的对象；每个页面都包含请求 cursor（第一页为 null）以及一个含有 items 和必需的 nextCursor 的 page。只有显式设置 nextCursor: null 才表示源已耗尽。空页面仍可能有下一个游标。配置中的文件路径相对于该配置文件解析。

已配置的 HTTP 源只使用 GET，且仅限于提供的确切来源／路径。示例（此处的域名是占位符，并非真实服务）：

{
  "source": {
    "type": "http",
    "url": "https://api.example.com/records?status=open",
    "itemsPath": "data.records",
    "nextCursorPath": "pagination.next_cursor",
    "cursorParam": "cursor",
    "totalPath": "pagination.total",
    "snapshotPath": "snapshot_id",
    "bearerEnv": "RECORDS_API_TOKEN",
    "scope": "account-and-filter-identity"
  },
  "key": "id",
  "sumFields": ["amount_cents"],
  "maxPages": 100,
  "maxRecords": 10000,
  "maxBytes": 16000000,
  "timeoutMs": 30000
}

totalPath、snapshotPath 和 bearerEnv 均为可选项。若已配置，元数据缺失会导致页面失败。路径使用以点分隔的对象自有键；不支持包含点号的字面键。API 映射必须显式指定，绝不猜测。返回的游标会作为不透明的查询参数值处理，而不是 URL。重定向会被拒绝。请将身份验证信息保留在工具宿主环境中；配置和检查点绝不会存储解析后的 bearer 令牌。除明确用于本地测试的端点外，请使用 HTTPS。请勿将密钥放入 URL 查询参数中。

优先使用提供方端的聚合／筛选，避免获取不必要的记录。使用 Link 标头、偏移量、GraphQL POST 或特定工具协议的 API 需要一个小型 SDK 适配器：

import { collectPages } from '@tiny_tools_pw/runtime';
const result = await collectPages({
  sourceId: 'account/dataset/filter/version',
  key: 'id',
  sumFields: ['amount_cents'],
  fetchPage: async (cursor, signal) => {
    const response = await yourReadOnlyClient.list({ cursor, signal });
    return { items: response.records, nextCursor: response.next ?? null };
  }
});

仅当提供方的文档约定明确规定缺少 response.next 表示结束时，才将其映射为 null。回调必须遵循 AbortSignal，以停止自身的 I/O。即使适配器忽略取消操作，采集器也会及时返回，但无法终止任意回调工作。

恢复 CLI 采集：

node packages/runtime/dist/cli.js collect /absolute/path/job.json --checkpoint /absolute/path/tiny-runtime-abc/checkpoint.json

每个已接受的页面都会先保存为检查点，然后才会请求下一页。timeoutMs 覆盖数据采集、获取数据和等待回调所需的时间；作业设置、验证和安全的文件系统收尾操作会带来额外开销。无法中断任意同步回调，超时的自定义适配器必须自行停止工作。请求进度通知的 MCP 客户端会收到已提交页面的通知；取消操作会停止后续请求，并保留已提交的工作。恢复操作会创建新目录，同时保留原始检查点。maxPages 适用于每次调用；记录数和字节数预算会计入此前已提交的页面。若要接受超大页面，请提高限制；采集器绝不会保存半页。HTTP 响应页面大小的默认上限为 1 MB（硬上限为 8 MB），记录数为 10,000（硬上限为 100,000），采集字节数为 16 MB（硬上限为 64 MB），超时时间为 30 秒（硬上限为 5 分钟）。不会自动重试、退避、并行获取数据或写入源数据。

使用 key 时，相同的重复项只计数一次，同一 ID 的冲突版本会导致整个新页面失败。不使用 key 时，会保留所有行。使用键时，声明的 total 必须指唯一记录数；否则必须指所有行数，且该值必须保持不变。求和时内部使用 BigInt，并以字符串形式返回；请使用分等整数单位（如分）或整数形式的字符串，而不要使用经过四舍五入的十进制数。处理十进制数或统计数据时，请使用 tiny-context 的 query_table。

完整性有明确的限度：complete 表示配置的源明确结束，且所有配置的元数据检查均已通过。它无法揭示提供方隐藏的限制、虚报的总数或源中缺失的记录。稳定的快照或总数能提供更充分的依据。恢复操作要求源、映射、范围和聚合方式相同；账户或筛选条件变更时，请更新范围。检查点 SHA-256 用于检测意外损坏，而非恶意篡改。检查点包含记录和游标，应像源数据一样妥善保护。CLI/MCP 作业会为每个页面写入一个不可变的增量文件和一个小型原子提交指针，返回时再写入一个兼容的版本 1 快照。中断的作业会保留版本 2 日志；请将整个作业目录放在一起，并通过 CLI/MCP 或 readCheckpoint(path) 恢复。旧版版本 1 快照仍可使用。日志恢复读取的 JSON 总字节数上限为 128 MB（每个文件 64 MB），此限制独立于不可信的元数据计数器；SDK 可以请求更小的读取预算。SDK 用户可以将 new CheckpointStore(freshDirectory).save 作为 onPage 传入，并在此之前调用 initialize(checkpoint)；完成收尾前请调用 drain()。较旧的 onCheckpoint 回调仍基于快照，长时间作业中开销可能较大。

重复工作防护

追踪记录的格式为 { "observations": [...], "nextAttempt": {...}, "options": {...} }；请参阅 examples/guard-trace.json。每条观察记录都包含 attempt（scope、tool、JSON args 和可选的 state）、outcome 以及可选的 stateAfter。请对测得的文件或仓库状态、etag 或源版本使用 fingerprint()。纳入所有可能影响操作能否成功的依赖项。不完整的指纹可能导致误报。绝不要将模型自行声称的“我取得了进展”当作证据。

import { RepeatGuard, runGuarded, fingerprint } from '@tiny_tools_pw/runtime';
const guard = new RepeatGuard({ threshold: 3, window: 100 });
const attempt = { scope: workflowId, tool: 'run_tests', args: { suite: 'unit' }, state: fingerprint(await measuredInputs()) };
const result = await runGuarded(guard, attempt, () => runTests(), async () => fingerprint(await measuredInputs()), result => result.exitCode === 0);
if (!result.executed) reportBlocked(result.decision);

runGuarded 不会重试或吞掉执行异常。请在每个工作流中串行使用；它不是并发调用去重器。没有可信的状态指纹时，重复失败只会产生建议，不会阻止操作。经主机批准的轮询可以使用 repeatableTools；请在可信的主机代码中配置此项。对未变化状态的成功读取仍会被允许，并会重置先前的失败尝试。状态变化会自然允许新的尝试。guard.clear(scope) 会显式重置历史记录。快照包含有界哈希，不包含参数或原始输出；但对可预测输入进行哈希并不等于匿名化。将快照作为构造函数的第二个参数传入即可恢复。检测采用有界启发式方法，并不能证明每次重复操作都没有必要。

实时进度与缓存桥接

请参阅 examples/demo.mjs，其中包含可执行的组合式集成示例。实时 SDK 路径如下：

import { CachePlanner, ProgressReporter, ProgressBridge, httpCacheAdapter } from '@tiny_tools_pw/runtime';
const planner = new CachePlanner();
const reporter = new ProgressReporter(sessionId, uniqueCallId, event => planner.ingest(event));
const bridge = new ProgressBridge(planner, httpCacheAdapter('http://127.0.0.1:8089/cache-hints'));
reporter.report('running', 0, 100);
// Tool adapter reports actual units as work advances.
reporter.report('running', 90, 100);
await bridge.tick(Date.now(), 4); // capacity is session slots, not GPU bytes
reporter.report('done', 100, 100);
await bridge.tick(Date.now(), 4);

该桥接会合并同时发生的 tick 和未变更的提示，并在已确认租约期限过半时续租。投递采用有界并发（默认值为 4），截止时间为 2 秒，且不会超过租约到期时间；它会在派发前和收到确认后检查是否到期。失败或延迟的确认不会报告为已应用。适配器必须强制执行租约到期时间并遵循取消操作；不配合的适配器可能会继续执行自己的工作。HTTP 适配器要求使用 Unix 毫秒时间戳。

工作运行期间，宿主会定期调用 tick，并在完成时再调用一次；请在运行时管理生命周期。始终报告 done、failed 或 cancelled 终态事件。会话 ID 和调用 ID 应是不透明的；不会发送提示词、文件路径、结果或文档内容。时间戳使用控制器的毫秒时钟域；请在可信边界处对远程时钟进行归一化。每次调用的事件序号必须单调递增。重复、乱序、未来时间戳和过期报告都会被拒绝。每次调用的 ID 必须唯一。

规划器需要有两个总量相同且持续推进的测量值，才能估算剩余时间。停滞、回退、总量未知和预测超时都会回退为未知。finishing 是明确的即将完成提示；只有可信的插桩代码才应发出此提示。对于并行调用，最后一个活跃调用决定就绪状态。默认值：5 秒后视为过期、1 秒内视为即将完成、租约最长 2 秒、最多 1,000 个会话／5,000 次调用。请根据工作负载设置合理的保留容量、tick 频率和配额。

自定义服务适配器契约： httpCacheAdapter 会向明确配置的端点 POST {version:1, session, action, reason, estimatedRemainingMs, validUntilMs}，并要求响应状态为 2xx。服务集成会将不透明的会话 ID 映射到自身的 KV 缓存状态，强制执行自身的内存预算和授权，并将 validUntilMs 视为硬性租约到期时间，即使释放请求投递失败也不例外。release 仅表示撤回我们的提示；不得销毁正确性所需的状态。未知或过期的会话会回退到引擎的常规策略。retain 和 prefetch 都只是建议优先级，并非无限量预留。错误会按会话返回。POST 请求有超时限制；重定向已禁用。2xx 仅表示端点已接受请求，并不代表 GPU 性能已实测。

这是我们的集成协议，并非现有的 vLLM API。此软件包不包含 GPU 引擎补丁。它实现了报告器／控制器／适配器端，并通过真实的本地 HTTP 端点进行测试；部署时必须提供引擎端。托管模型客户通常无法控制此缓存。底层研究报告的延迟提升并非本实现的测试结果。工具工作单元不等、误导性进度、资源争用和对抗性会话都需要针对具体工作负载进行验证，并在引擎层设置配额。

验证与体积

npm test 覆盖库故障、真实本地 HTTP 源、检查点续跑、CLI 退出行为，以及通过真实 MCP stdio 客户端测试全部三个工具。npm run demo:runtime 会展示这三个工具的协同运行情况。npm run bench:runtime 使用合成数据，将采集器与普通且正确的脚本进行比较。

在这台开发机器上，对 10,000 行 / 100 页合成数据运行五次，两者的求和结果均为 495,000 美分：普通脚本耗时 0.46–1.07 ms，采集器耗时 30.68–39.62 ms。结果不包含网络延迟、磁盘检查点 I/O 或模型调用。验证会消耗 CPU；在这个简单场景中，已有的正确脚本速度更快。合成的故障未变化场景会在 100 次尝试调用中执行 3 次并阻止 97 次；这展示的是策略行为，并非实测的现实节省效果。目前尚无该软件包降低 Token / API 成本的实测数据、广泛采用 Agent 的证据或生产环境 GPU 测试结果。

没有新增依赖系列或原生二进制文件：Zod 用于验证不可信数据；现有的官方 MCP SDK 提供 stdio；Commander 提供 CLI 解析。即使此服务只公开 stdio，SDK 的传递依赖 HTTP 软件包仍会安装。实际软件包大小和生产安装大小会在 docs/VALIDATION.md 记录，验证时会执行全新安装。

由 AVRG3 构建 · MIT