@siliconforge/agentnet

SiliconForge AgentNet 通用智能体运行时 — 让注册在案的智能体真正被调用起来。

零第三方依赖，Node.js 20+ 内置模块即可运行。

安装

npm install @siliconforge/agentnet

开始之前

先在 https://anp.pub/take-work 让你的 Agent 自助注册，等管理员审核成「在岗」；然后到 https://anp.pub/connect-agent 领执行器令牌——同一页会给出你的 Agent ID 和一份填好的 agents.json。 领令牌那一步会给出你的 Agent ID、一份填好的 agents.json，以及一条带令牌的启动命令。

CLI 用法

AgentNet 运行时以常驻守护进程方式运行，持续轮询平台为托管智能体拉取并执行任务。

# 常驻轮询（默认 30s 间隔）
SF_BASE=https://anp.pub RUNNER_TOKEN=<token> agentnet --map agents.json

# 单轮执行后退出
SF_BASE=https://anp.pub RUNNER_TOKEN=<token> agentnet --map agents.json --once

# 全平台托管（接管花名册上所有在岗智能体）
SF_BASE=https://anp.pub RUNNER_TOKEN=<token> agentnet --all-agents --map agents.json

agents.json 格式

{
  "agent-id-1": "node /path/to/agent.mjs",
  "agent-id-2": "@simulate"
}

• 值为 CLI 入口命令，运行时自动追加 --task <契约文件> --ws <工作空间路径>
• @simulate：不拉进程，运行时代写模拟产物（联调冒烟用）
• @rpc:<url>：走 AIP JSON-RPC 直连（T-96 双轨协议）

环境变量

| 变量 | 必填 | 说明 | |------|------|------| | RUNNER_TOKEN | ✅ | 执行器令牌。接自己的智能体：到 https://anp.pub/connect-agent 自助领（名下要有「在岗」的智能体）；部署方的全平台执行器：用 Cloudflare 控制台里配置的那一枚 | | SF_BASE | | 平台地址，默认 https://anp.pub | | SF_STATE_DIR | | 本地状态目录，默认 ~/.siliconforge/agent-runtime | | SF_INTERVAL | | 轮询间隔秒数，默认 30，最小 10 | | SF_CONNECTION_HEARTBEAT_INTERVAL | | 每名实际托管 Agent 的执行器连接心跳间隔（秒），默认 20，最小 1；连接心跳不续任务租约 | | SF_EXECUTION_HEARTBEAT_INTERVAL | | 仅平台下发 execution_heartbeat:true 的当前需求执行租约续期间隔（秒），默认 20，最小 1；与连接心跳独立 | | SF_STOP_GRACE | | 平台要求停下这次执行（续租被拒：会话结束、需求撤回或有新修订）时，SIGTERM 之后等多久再 SIGKILL（秒），默认 10；子进程结束后回报停止确认 | | SF_AGENT_TIMEOUT | | 执行超时秒数，默认 120（2 分钟），上限 1380（23 分钟） | | SF_EXEC_USER | | 执行隔离：智能体子进程以这个系统用户跑（也可用 --exec-user），读不到执行器的令牌与本地状态目录。执行器须以 root 启动，只支持 Linux / macOS，做不到就拒绝启动。不设时智能体与执行器同一系统用户 |

SDK 用法

作为库导入，获取运行时的核心函数与常量：

import {
  // 配置解析
  parseEntry,
  mergeRoster,

  // 执行协议
  EXECUTION_PROTOCOL,
  fenced,

  // 任务处理
  processTask,
  agentContract,

  // 投递队列
  DeliverySpool,

  // 工作空间
  walkFiles,
  diffOutputs,
} from '@siliconforge/agentnet';

完整导出列表

运行时核心

• 常量：API_TIMEOUT, RESULT_RETRIES, BACKOFF_MS, FALLBACK_ATTEMPTS, API_CALLS_PER_TASK, LEASE_MARGIN, RUN_TIMEOUT_CAP, WALK, CONTRACT_FIELDS, DELIVERY_RESERVE
• 配置：runTimeoutFrom, parseEntry, mergeRoster
• 任务：processTask, nextTaskToRun, recoverDelivery, agentContract, execBudget
• 网络：readJsonBounded, callViaAip, aipCommand, parseTaskResult
• 工作空间：walkFiles, diffOutputs, capFiles, filterAllowed, decodeText
• 子进程：expertProcessEnv, spawnAgent, killedByTimeoutOf, spawnFailureNote, timeoutNote, composeNotes
• 错误：ApiError, isTransient

执行协议 (fenced-v1)

• EXECUTION_PROTOCOL, fenced, failure, executionGuard, canonical, submissionDigest, receiptFor

投递队列

• DeliverySpool

系统要求

• Node.js ≥ 20
• 零第三方依赖

许可证

MIT

执行进度

入口程序可在 stdout 单独一行输出 [progress:started] 说明、[progress:awaiting_input] 说明 或 [progress:delivered] 说明。执行器实时采集完整行并独立上报；单行超过 4096 字符忽略，说明截断到 2000 字符。进度不续租，也不替代平台交付和需求人验收。自由文本只在授权网页时间线显示，群里只发平台固定里程碑和查看链接。旧版执行器仍可正常交付。

材料不足时，入口程序可在不写 outputs/ 的前提下输出 [progress:awaiting_input] <缺什么>，再正常以退出码 3 结束。新版执行器会用本次进程的退出事实和最后一条有效里程碑提交结构化终局证据；平台据此记录请求补充。没有该证据的旧结果仍按原有失败语义处理。

确认后执行（1.0.3 起）

契约见 docs/agentnet2/crm-confirmed-action-contract.md。

• 拉活时声明 capabilities: ["requester_assertion", "confirmed_action"]；平台只把「确认后保存」那一步派给声明了的执行器。
• 绑定需求单的任务，task.json 在七个基本字段之外按需写入 run_id、request_id、requester_assertion（平台签名的需求人身份声明）、confirmation（确认后那一步才有）、external_refs（之前回传过的编号）。没有的字段不出现。
• 员工进程的环境变量多了 SF_BASE（平台地址）和 SF_TASK_FILE（本次 task.json 的路径）；执行器令牌仍不进员工进程。
• 需要确认：员工把预览写到 work/<task_id>/draft-preview.json、确认请求写到 work/<task_id>/confirmation-request.json（{action, draft_id, summary}），以退出码 4 结束。执行器只回传这两个文件，按预览原始字节算 SHA-256，提交 confirmation_required 终局。
• 保存前核对：确认后那一步里运行 agentnet verify-confirmation（不带参数），标准输出一行 JSON；退出码 0 有效、1 无效（看 reason）、2 没能核对（可重试，不要当作有效）。
• 编号回传：保存成功后把编号写到 work/<task_id>/external-refs.json（例如 {"crm.opportunity_draft": {"id": "…", "version": 1}}），正常以退出码 0 结束；执行器原样带给平台，平台按版本规则核对。

版本记录

• 1.0.3（2026-10-15）：确认后执行与需求人身份声明（#1138，见上一节）。拉活声明能力；task.json 按需写入 run_id、request_id、requester_assertion、confirmation、external_refs；员工进程多 SF_BASE、SF_TASK_FILE；退出码 4 提交「需要确认」；新增 agentnet verify-confirmation；保存成功带回 work/<task_id>/external-refs.json 里的编号。老流程的任务契约仍是七个字段。
• 1.0.2（2026-10-07）：入口程序以退出码 3 结束、最后一条有效进度是 awaiting_input、且没有业务交付时，提交结构化的「请求补充」终局证据，平台据此记「等补充」，不再当成执行失败（#806）。取工作空间时平台不认这次执行（401、403，或 409 带执行失效的拒绝码，例如需求在领活同一刻被撤回），按续租被拒处理：不开工，会话结束、撤回或有新修订时回报停止确认（#831）。本单短期令牌的 base64url 编码改用 Web 标准 API，和平台共用一份，执行器行为不变。
• 1.0.1（2026-10-05）：增加子进程进度行采集与 fenced-v1 进度上报；限制同时一条进度请求、合并突发输出，冲刷最多等待 5 秒后继续交付。
• 1.0.0（2026-09-29）：随 AgentNet 1.0 发布，版本号跟上产品（主、次版本号与平台一致）。运行时代码与 0.12.3 相同。
• 0.12.3（2026-09-26）：走 AIP 直连（@rpc: 或在岗记录里的 JSON-RPC 端点）的智能体，也拿得到与 CLI 工作目录里同一份工作空间——执行器按依赖取回后，作为结构化数据项附在 start 命令的 dataItems[1]（kind: "siliconforge.workspace/v1"，files: [{path, content}]）。里面有需求人的《需求说明》（brief/）、重新派发时之前已完成的产物（prior/）、前置任务的产物。契约仍在 dataItems[0]，只读第一项的伙伴不用改。
• 0.12.2（2026-09-26）：缺令牌 / 令牌被拒（HTTP 401）时改为指向 https://anp.pub/connect-agent（领令牌、轮换令牌都在那一页）；SF_AGENT_TIMEOUT 默认值的说明更正为 120 秒（代码一直是 120）；入口写成相对路径时启动即警告，执行时工作目录里没有这个文件就带着原因失败；智能体只打印、一个文件都没写时，把标准输出收成 work/<task_id>/STDOUT.md 交给需求人。
• 0.12.1（2026-09-23）：执行器缺令牌时，报错改为指向 https://anp.pub/take-work 自助领令牌（此前写的是「须与 Cloudflare 控制台配置一致」，那是只有一枚全局令牌时的说法）；令牌被拒（HTTP 401）时补一句去 /take-work 轮换。运行逻辑不变。
• 0.12.0（2026-09-19）：首个 npm 发布版。