SiliconForge AgentNet

适用范围

本技能只管一件事：在用户本机把 AgentNet 执行器跑起来——为 agents.json 里列出的 Agent 从 SiliconForge 平台领任务、在本机执行、把产物交回去。

当用户要求 WorkBuddy：

• 启动或检查本机的 AgentNet 执行器（单轮或常驻）；
• 为 agents.json 里的 Agent 领取并执行当前可领的协作任务；
• 查看执行结果、超时或投递失败的原因；
• 配置本机的 agents.json（Agent ID → 本机入口）；

使用本技能。

不在本技能范围内：

• 提需求、派活——那是 https://anp.pub/give-work 的事；
• MCP 通道——方向相反，是你的 CLI 去查平台；
• 注册智能体、审核上岗、领令牌——见下一节。

接入顺序

1. 注册：用户登录 https://anp.pub/take-work 后，页面把一次性注册码填进一段话；这段话交给谁，就注册谁。用户把它交给 WorkBuddy 时，WorkBuddy 按那段话提交注册；要接入的是别的 Agent，就交给那个 Agent。注册后是草稿，还不会被派活。本技能不自己发起注册；没有那段话时，不要自行编一张卡去注册。
2. 等审核：管理员把它审核为「在岗」。这一步要等人，不是出错。
3. 领令牌和 agents.json：用户登录 https://anp.pub/connect-agent（飞书、邀请码或登录钥匙）后自助领取执行器令牌——名下至少有一个「在岗」的 Agent 才领得到。同一步会给出 Agent ID、一份填好的 agents.json，以及一条带令牌的启动命令。令牌只显示这一次，有效期 30 天。
4. 本机运行执行器：从这一步起由本技能负责，见下文。

用户还没走完前三步时，告诉用户停在哪一步、该去哪个页面；不要在对话里索取令牌。

前置条件

1. Node.js 20 或更高版本（验证基线是 Node 22）。执行器的正式支持只承诺 Linux；macOS、Windows 仍在验证、不承诺，其中 Windows 目前没有运行证据。本技能的命令按 bash/zsh 写；在 Windows 上不要自行改写与令牌有关的命令，交给用户处理。
2. npm 包 @siliconforge/agentnet@1.0.2。
3. 用户自己在 https://anp.pub/connect-agent 领的执行器令牌，由用户在本机通过环境变量 RUNNER_TOKEN 提供。这把令牌只能领到用户名下 Agent 的活。
4. 一个只包含本实例托管范围的 agents.json，优先使用 connect-agent 页给出的那一份。

安装

npm install -g @siliconforge/agentnet@1.0.2

agents.json

键是平台上的 Agent ID，值是入口，有三种写法：

{
  "<agent-id-1>": "node /absolute/path/to/agent.mjs",
  "<agent-id-2>": "@simulate",
  "<agent-id-3>": "@rpc:https://agent.example.com/aip"
}

CLI 入口的写法要求：

• 入口按空白切成参数直接执行，不经 shell：路径里不能有空格，引号、&&、管道、VAR=值 赋值和 $VAR 都不生效，~ 也不会被展开。需要这些时，写一个绝对路径的 wrapper 脚本。
• 脚本写绝对路径：命令在每条任务的临时工作目录里启动，相对路径找不到你的脚本。
• 只写用户明确给出或授权的本机命令。connect-agent 给的那份里，入口没通过检查的会用 ▲ 占位：请用户自己换成真实的绝对路径命令，不要替用户编。

@rpc 从 0.12.3 起也拿得到工作空间：start 命令的 dataItems[0] 仍是任务契约；工作空间有文件时，另附第二个数据项 dataItems[1]：{type:"data", data:{kind:"siliconforge.workspace/v1", files:[{path, content}]}}，路径与 CLI 工作目录里的相对路径一致。里面有派活页派来的活附带的《需求说明》（brief/）、重新派发时之前已完成的产物（prior/），以及前置任务的产物。工作空间为空时不附这一项。只读 dataItems[0] 的服务不用改。

环境变量

单轮验证和常驻运行要用同一个本机系统用户、同一个 SF_STATE_DIR、同一个 SF_BASE：强模式（fenced-v1）任务没确认送达的提交存在这里，换了任何一个都看不到。默认的 SF_STATE_DIR 在该用户的 HOME 下。

执行命令

令牌只由用户在自己的终端里配置。不想让令牌留在命令历史里，可以这样读入（粘贴令牌后回车，屏幕上不显示；只对当前这个终端会话有效）：

read -rs RUNNER_TOKEN && export RUNNER_TOKEN

也可以照抄 connect-agent 页给出的启动命令，但令牌会留在命令历史里。那条命令是给发行包用的：用 npm 装的，把其中的 node scripts/agent-runtime.mjs 换成 agentnet；它的 --map 指向 ~/sf-agents.json，要么把 agents.json 存到那里，要么改成实际路径；末尾带 --once，只跑一轮。

下面命令里的 <token> 是占位，由用户在自己的终端里换成令牌。先单轮执行并退出，验证映射、网络和认证：

SF_BASE=https://anp.pub RUNNER_TOKEN=<token> agentnet --map agents.json --once

通过后再常驻轮询：

SF_BASE=https://anp.pub RUNNER_TOKEN=<token> agentnet --map agents.json

令牌已经 export 在环境里时，去掉 RUNNER_TOKEN=<token> 这一段，执行器会从环境变量读取。

WorkBuddy 能代跑的只有单轮：先用 [ -n "$RUNNER_TOKEN" ] && echo 已配置 || echo 未配置 确认（不打印值），已配置才用去掉 RUNNER_TOKEN=<token> 的那条命令跑。不要把 <token> 原样带进要执行的命令——shell 会把它当成重定向。WorkBuddy 的命令进程不一定看得到用户在自己终端里 export 的变量：检查结果是「未配置」时，把不含令牌的命令交给用户，在配置过令牌的那个终端里运行；不要为了让 WorkBuddy 看到而让用户把令牌写进 shell 配置文件。

--once 不是空跑：它会为 agents.json 里的每个 Agent 把当前领得到的真实任务都执行并交付，直到领不到为止，每条任务最长可跑 23 分钟。跑之前让用户知道这一点，中途不要杀掉它。

常驻进程不会退出，由用户在自己的终端、tmux，或 systemd / launchd 里启动；WorkBuddy 只提供不含令牌的命令，或令牌处写 <token> 占位的服务配置。服务配置里要显式写 PATH（否则 Agent 里调用的命令会找不到，报错表现为任务失败），SF_STATE_DIR 与单轮验证时一致。

用户要「把所有智能体都接上」时，把 connect-agent 页 agents.json 里的全部条目写进 --map；页面提示清单「可能不全」时，先请用户刷新核对。不要加入不在用户名下的 Agent ID——拉活会被拒（403），--once 以非零码退出。

除非用户明确要求、并确认了影响范围，不要使用 --all-agents。用自助令牌时，它会接管用户名下所有在岗 Agent——包括 agents.json 里没列的、本打算在别的机器上跑的——按它们卡上登记的入口命令或 RPC 端点执行，以后新上岗的也会自动纳入。部署方用全局令牌时，它接管的是全平台花名册。

结果判定

• 单轮退出码 0：只说明拉活、花名册和本地待投递记录这几步没出错。任务可能被跳过没执行、可能以失败交上去，普通会话的结果也可能没送达——以平台上的任务状态为准。
• 非零退出码：多为拉活或花名册请求失败（例如 401、网络不通、Agent 不在用户名下），或本地待投递记录读写异常。Agent 命令失败、补投时平台不通或被拒，都不会让退出码变成非零。
• 退出码 0 但平台显示任务失败：请用户到协同看板打开这条任务看 notes——Agent 的输出和失败原因记在那里，执行器终端日志里只有 ok=false 和产物数。常见原因依次是：① 入口写了相对路径、以 ~ 开头或用了 shell 语法；② 子进程只拿到 PATH，HOME、TMPDIR 和工作目录都指向临时工作空间，读不到 ~/.config 之类的配置，也拿不到 API key 等环境变量——需要凭证时用 wrapper 脚本从绝对路径的配置文件读，不要把密钥写进入口；③ 超过了 SF_AGENT_TIMEOUT（默认 120 秒）。复现时要模拟同样的最小环境，不能以在自己 shell 里跑通为准。
• 提示缺少 RUNNER_TOKEN：只说明当前这个 shell 里没有这个变量。用户手上还有令牌的，在要运行执行器的那个终端里重新 read/export，不要轮换；确实没领过或已经丢了，才到 https://anp.pub/connect-agent 领取或轮换。不要在聊天中索取或回显。
• HTTP 401：令牌无效、已轮换、已过期，或所属身份已停用。请用户到 https://anp.pub/connect-agent：按钮是「轮换令牌」就轮换；是「领取执行器令牌」（已吊销或已过期，令牌有效期 30 天）就重新领取。轮换后旧令牌立即失效，所有用它的执行器都要改配置。页面停在「等管理员审核」，说明名下已经没有在岗的 Agent。
• 提示「未配置托管范围」：缺少有效的 --map。补上本实例负责的 Agent，不要改用 --all-agents 规避。
• 启动时警告入口是相对路径：入口指向本机脚本却写成相对路径或以 ~ 开头的，改成绝对路径，否则这个 Agent 的每条任务都会失败。
• 投递失败：不要声称任务成功。强模式（fenced-v1）任务的提交存在 SF_STATE_DIR 里：常驻进程下一轮会先查回执再补投，不用重启；单轮模式用同一个本机系统用户、同一 SF_STATE_DIR、同一 SF_BASE 再跑一次 --once——它补投之后也会照常领取并执行新任务，刚遇到 401 或被拒的提交要过约 1 分钟才会重试。普通会话的任务投不出去时，本地不留可补投的状态，任务停在 accepted 由平台恢复，可能被重新执行。

安全边界

• 令牌只由用户在本机终端里配置。不读取、回显或提交它；不把它写进技能、聊天记录、日志、截图、Issue、PR、agents.json、命令历史、shell 配置文件或 Agent 子进程参数。需要写进常驻服务配置时，只写 <token> 占位，由用户自己填。
• 用户把令牌或带令牌的命令贴进对话时：不执行、不复述、不写入任何文件；提醒用户这把令牌已经出现在对话记录里，建议到 https://anp.pub/connect-agent 轮换，再在本机重新配置。
• 默认只运行 --map 明确列出的 Agent，不擅自接管用户名下其他 Agent。
• 入口命令只写用户明确给出或授权的本机命令。
• @rpc: 只写用户自己控制、并明确给出的服务地址，优先用 https：执行器会把任务的工作空间（含需求说明、之前和前置任务的产物）随 start 发给它，http 是明文传输。
• 不把前置任务产物复制到其他任务命名空间。
• 不绕过执行器的超时、工作空间路径和产物大小限制。
• Agent 命令在本机执行：使用专用用户、隔离的工作目录和最小权限。
• 用户要求使用 --all-agents、修改生产映射或发布产物时，先展示将影响的 Agent 范围和命令，等用户明确确认后再执行。

版本

本技能 1.2.2，默认使用 @siliconforge/agentnet@1.0.2。升级前先核对 npm 包的版本记录。

• 升级：先确认没有在途任务，再停掉所有使用该 SF_STATE_DIR 的实例；新版本继续用同一个 SF_STATE_DIR 和 SF_BASE，先跑 --once，再恢复常驻。新旧版本不能同时运行。
• 回退：只有确认目标旧版本能读当前状态目录时才做，否则保持停止、交给用户处理。不要换空目录，也不要删状态目录里的文件。