把 AI Agent 变成本地服务，而不是黑盒网页：Sprocket 的工作区、API-only 与权限边界
很多 AI 编码工具把“开一个对话框”当作起点，但一旦任务跨过代码编辑、目录上下文和可复用会话，真正的问题就变成：状态放在哪里？谁能连到本地服务？一个可被其他程序调用的 Agent 又该怎样收住权限？
Sprocket 是一个 Apache-2.0 许可的 TypeScript 项目。它的 README 将自己定义为能够创建硬件设计并编写代码的轻量 Agent，并列出 React 原理图、BOM（物料清单）与装配说明等硬件相关产物。这里更值得开发者研究的，不是把它当成“全能 Agent”的宣传样本，而是它把交互界面、工作区记忆和本地服务拆开后的运行方式：同一套 CLI 可重新连接目录，也可以只启动本地 /api 服务。
先把工作区当成状态边界
临时在浏览器里问一个问题，并不需要稳定工作区；但让 Agent 反复参与某个机器人、固件或 Web 项目时，目录就是最自然的上下文边界。Sprocket 支持直接把目录交给 CLI：
npm i -g @spikonado/sprocket sprocket . sprocket --web ../my-robot
README 说明它会记住已连接的工作区和本地 server session；默认本地状态目录是 $HOME/.sprocket，也可用 SPROCKET_DATA_DIR 改写。这个细节看似普通，却决定了可维护性：项目目录保存可提交的源代码、原理图与文档，用户目录保存配对、会话和工作区状态。两者不要混为一谈。
例如在 CI 临时机、共享开发机或容器中，应该为每次运行指定独立状态目录，避免不同项目和不同用户意外复用会话；需要保留诊断现场时，则应把该目录纳入受控备份，而不是只保存 Git 仓库。
export SPROCKET_DATA_DIR="$HOME/.local/state/sprocket-robot-a" sprocket --web ./robot-a
目录隔离并不等于权限隔离。若状态中包含配对信息或会话数据，就应按敏感运行数据处理：限制本机账户访问，避免把 .sprocket 内容直接复制进镜像、上传到公共制品库，排查问题时也不要把其中内容不加筛选地贴进工单。
serve 的价值：让 UI 与本地运行时解耦
Sprocket 的 CLI 还提供两种服务模式：sprocket serve 在前台运行本地 server 而不启动客户端；sprocket serve --api-only 则只提供 /api，README 明确将后者标为面向开发用途。于是它可以被理解为一条很小的本地控制面：交互客户端是否启动，与 server 是否存活不再绑定。
export SPROCKET_DATA_DIR="$HOME/.local/state/sprocket-dev" export SPROCKET_HOST="127.0.0.1" export SPROCKET_PORT="17731" sprocket serve --api-only
对于已安装模式，README 给出的默认端口是 17731，默认绑定主机是 127.0.0.1。这两个默认值适合本机开发：浏览器、编辑器插件或测试程序可以通过本地服务协作，同时不必一开始就把端口暴露到局域网。
如果只是评估工具而不希望先改变全局环境，也可以使用 README 提供的免安装入口：
npx @spikonado/sprocket
README 说明，这条命令会经由浏览器运行 Sprocket（若已安装桌面应用则行为会随桌面应用存在而变化）。它适合快速确认本机能否启动和建立工作区，但不应把一次性 npx 试运行误当作可长期运维的部署方式。长期使用时，固定 CLI 版本、显式设置状态目录，并记录启动参数，才能让问题复现不依赖某台开发机遗留的 shell 配置。
一个可复现实验可按下面的顺序进行：先在无敏感数据的测试目录启动 --api-only，保留终端日志；然后另开终端检查端口仅监听在 loopback 地址；最后停止进程并检查状态目录实际创建了哪些文件。这里的网络检查不需要猜测 Sprocket 的 HTTP 路由或认证方式，只验证 README 已声明的主机与端口覆盖项是否按预期生效：
ss -ltnp | grep ':17731'
若输出显示监听地址不是 127.0.0.1，先回看环境变量、父进程注入的配置以及启动命令，再继续接入其他本地工具。若端口被占用，也应换用一个明确的 SPROCKET_PORT 值并记录下来，而不是让多个开发服务争抢默认端口。这样做的目的不是增加流程，而是把“Agent 无法连接”拆成目录状态、进程存活、端口绑定三类可独立排查的问题。
但不要从“存在 /api”推断出未在文档中列出的端点、认证模型或自动化协议。把 --api-only 用于开发，不等于它天然适合作为团队共享的生产 API。若确有远程访问需求，应先确认实际接口与认证能力；再以反向代理、网络策略和最小权限账户分层保护，而不是简单把 SPROCKET_HOST 改成全网监听地址。
把本地服务纳入日常排错，而非只在失效时猜测
本地 Agent 的问题常被笼统归为“模型没响应”，实际上至少可能发生在四层：CLI 没有启动、server 已退出、端口绑定与预期不符、工作区状态指向了旧会话。把这些层次分开，能显著缩短排错时间。
首先，在启动 sprocket serve --api-only 的终端保留完整标准输出；不要为了后台运行而立刻丢弃日志。其次，在另一个终端确认进程和监听地址，重点看服务是否真的仍在运行、是否仍只绑定 loopback。第三，遇到工作区表现异常时，不要直接删除整个状态目录：先复制一份 SPROCKET_DATA_DIR 作为诊断快照，再新建一个空目录对照启动。这样可以区分“工具本身无法启动”和“旧会话、配对或工作区元数据造成的状态问题”。
这种对照方式同样适合升级。npm registry 当前将 @spikonado/sprocket 的 latest 标记指向 0.3.0，但测试升级时仍应先在临时目录验证启动与工作区连接，再迁移日常状态目录。版本升级、状态迁移和网络暴露是三件不同的事；把它们放进同一次变更，会让回滚和定位都变得困难。
对于团队协作，推荐把启动命令、状态目录约定和端口约定写进项目的开发文档；但不要把用户级会话状态提交到 Git。代码仓库应记录可复现的配置意图，用户目录负责承载具体会话。这个分工既避免机密与个人上下文进入版本历史，也让新的开发者能以新的本地状态加入同一项目。
硬件任务为什么更需要人工确认
Sprocket 的定位跨越软件和硬件。README 将生成原理图、BOM、装配说明列为能力，也宣称可按指令在网站购买物品。这类流程的价值在于把“找资料—整理零件—形成实施步骤”连成链，但风险也比普通代码补全更具体：BOM 中的料号、封装、替代料、交期和电压规格都可能影响成本或安全；采购动作还会触及账户、支付和不可逆订单。
因此，一个稳妥的落地流程应该把 Agent 输出放在“建议层”，而不是直接变成“执行层”：
- 让 Agent 在项目工作区产出候选原理图、BOM 或装配清单，并把来源与假设写清楚；
- 由硬件负责人复核关键规格、兼容性、库存和替代料，尤其检查电源、接口与封装；
- 采购前由拥有审批权限的人在独立页面确认数量、收货地址和总价；
- 将最终 BOM、评审记录和变更原因提交到项目版本库，确保后续能追溯。
这不是对某个产品额外附会的功能要求，而是把“能生成建议”与“允许花钱或接触外部系统”拆成两道门。Agent 的会话能力越连续，本地状态和工作区越持久，越需要这种显式的人工确认点。
适合把它放在哪一层
Sprocket 当前最适合被当作本机开发工作流中的实验性运行时：用目录恢复项目上下文，用独立状态目录隔离会话，用 serve --api-only 探索本地集成。若项目既有软件又有硬件资料，这种以工作区为中心的组织方式也比在多个孤立聊天标签之间复制粘贴更容易沉淀交付物。
相反，如果你的需求是无人工介入的远程采购、面向公网的通用 Agent API，或对硬件输出承担直接生产责任，就不能仅依据 README 的能力描述上线。先核验接口、身份认证、审计记录、工具调用范围与异常恢复方式，再决定是否扩大网络暴露和执行权限。把 Agent 当成本地服务来运维，关键不在于让它“能做更多”，而在于让状态、网络和最终动作都保留可见、可控的边界。