推荐形态一句话:skills 内容经 1.0 入库展示;可被 agent 使用的子集在代码里(runner/skills/),构建期生成两端同源清单; 两个新工具 skill_load(纯函数组)/ skill_run(沙箱执行组,首个 dangerous=TRUE);一个 network_mode: none 的常驻执行容器经 unix socket 被 api 调用; pi 侧 xray-guard / xray-skills 两个扩展把裁决写进既有 34 事件;前端零样式改动、两处投影逻辑改动。

1. 逐条对照:要求 × 现有约束 × 判定

2. 方案(建在 R-SKILLS 1.0 之上)

2.1 总览

规则 9 的三句话各有落点:api 进程仍然不 spawn 任何东西(它只发一个 HTTP 请求);执行发生在独立容器;守卫与观测者只是 pi 扩展,不承担隔离。

2.2 哪些 skill 能被 agent 使用(要求 ①⑤;裁定 5、6)

一个 skill 对 agent 可用,四个条件同时成立(缺一即「只展示」,与 1.0 的默认一致):

1. 在代码里:runner/skills/<name>/ 存在(裁定 6)。构建期生成 apps/api/agent/skills.generated.ts(生成物、入库、不许手改,与 api-client.ts 同口径)与 runner/manifest.json,两端同源;
2. 库里已发布且打开:1.0 的 skills 表里有同名行,且 2.0 新增列 agent_enabled = TRUE(MCP skills_agent_set,默认 FALSE);
3. 展示副本与代码副本一致:库内 skill_files 的每个文件 sha256 与清单逐一相等(集合相等,多一个少一个都算漂移)。漂移 → 不注入、记日志、skills_agent_status 报 drift —— 访客在 Skills 页看到的,就是 agent 用的;
4. 工具闸开着:tool_config 的 skill_load 打开(注入型至少要它);可运行型另需 skill_run 打开 + 服务器 env XRAY_UNLOCK_DANGEROUS_TOOLS=1(R7 双闸,首次真正用上)。

两个档次(由 runner/skills/<name>/xray.json 有没有决定):

准入清单(可运行型),收录进 runner/skills/ 前逐条过,一条不过就只做注入型或只展示:

• 脚本从 stdin 读一个 JSON 对象、结果写 stdout(≤ 64 KB);不读 argv、不读环境变量、不读 stdin 之外的输入;
• 只用标准库或 runner/requirements.txt 里钉住的依赖(新增依赖 = 发版);
• 不 import subprocess / os.system / socket / ctypes,不 eval / exec 动态代码,不写 cwd 之外的路径(容器层面本来也做不到,这一条是审阅口径);
• 确定性、单次 < 超时(默认 30 s)、不 fork;
• egress 档例外(R-WEBFETCH,所有者裁定 2026-09-03):xray.json 声明 network: egress 的 skill 允许 socket / ssl / http.client (仍禁 subprocess / ctypes / eval),「确定性」不要求;代价是审阅多一道 —— codex 审查按 docs/security.md §1 R-WEBFETCH 补记的 七点 SSRF 判据逐条判,且这类 skill 只会被路由到只出公网的 skill-runner-egress 实例;
• xray.json 为每个脚本给 description 与入参 schema(ToolParametersSchema 同一子集:string / integer / boolean、required、长度上界);
• SKILL.md 自包含(不依赖 references/,没有 read 工具读不到);写给 Claude Code 的调用方式(python scripts/x.py --flag)照留,本站的调用方式由 skill_load 按 xray.json 自动追加一段「在本站:skill_run(skill, script, input)」,不要求所有者改写 SKILL.md。

对画板 2f 那九个示例的判定(所有者上传时按此归档,不是硬性清单):

2.3 两个工具(要求 ①②⑤)

为什么 input 是一个 JSON 文本而不是 argv 数组:ToolParametersSchema 目前只认 string / integer,数组要扩类型 + 扩面板;argv 是解析面(引号 / 空格 / --),stdin JSON 没有歧义;脚本从 stdin 读 JSON 最容易写对也最容易审。

2.4 执行容器 skill-runner(要求 ②④⑤;裁定 2、4)

它不是「一次性容器」(裁定 2 已认):同一容器、同一内核命名空间为所有运行服务。得到 read-only + 无网络 + 每次独立进程与目录 + rlimit; 失去「两次运行之间的内核级隔离」。为什么接受:「每次一个容器」要么给 api 挂 docker.sock(等于 root,与第 3 层直接冲突),要么上 gVisor / Firecracker(2 vCPU 轻量服务器不现实)。 升级路径:runner 换 gVisor runtime(runtime: runsc,compose 一行),协议不变。

2.5 pi 侧两个扩展(要求 ③⑥)

两者都是 runtime.ts 里与 makeObserver 同款的 InlineExtension,拿着 rec 闭包,永远注册(不随 skills 开关),注册顺序 [xray-skills, xray-observer, xray-guard]。

xray-guard(守卫) —— 只订阅 tool_call,规则按序判、首条命中即 {block:true, reason}:

1. toolName ∉ 本会话白名单 → 拦(pi 自己也会拒,这是第二道);
2. skill_load / skill_run 的 skill 不在本会话可用集合 → 拦,reason 说「该 skill 未对 agent 开放」;
3. skill_run:script 不在 xray.json / input 不是 JSON 对象 / 不过 schema / 超长 / 含控制字符 → 拦,reason 写清哪一项(给模型改正用);
4. 会话内计数:每 turn ≤ 3 次、每会话 ≤ 12 次(代码常量;turn_start 归零)→ 拦,文案带「不必重试」;
5. 守卫自身抛异常 = 拦截,不是放行(try/catch 兜底为固定 reason;pi 对 handler 异常的处理会把栈信息外泄进错误文案,所以自己兜)。

它不做参考实现里的这些(附 B):不建 venv、不读 process.env、不 registerCommand(访客输入以 / 开头会被 pi 当命令分发,附 A-4)、不 ctx.ui.notify。

xray-skills(注入器) —— 只订阅 before_agent_start:返回 {systemPrompt: event.systemPrompt + <available_skills 目录>}(只列本会话可用集合的 name + description + 档次)。 pi 对多个扩展的 systemPrompt 是链式叠加、下一轮无人返回就回到 base(附 A-3),每轮注入、幂等。 不直接写进 systemPromptFor 的理由:那样注入这件事在轨迹里不存在;放在 chain 事件里,每一轮的 before_agent_start 行都能展开看到「xray-skills 返回了什么」—— 画板 1b 那张 context-injector 卡。

「谁裁决,谁记录」:观测者不再订阅这两个事件,改由守卫 / 注入器在自己的 handler 里调同一个 capture(rec, name, event, handlers)。 原因是实测的短路语义(附 A-2):守卫一旦 block,排在它后面的 handler 看不到事件;把观测者排在前面,它又看不到裁决结果。 让裁决者自己落笔,tool_call 这一行的数据里就带着 handlers: [{extension:"xray-guard", returned:{block:true, reason}}]。

2.6 轨迹与右栏可见性(要求 ⑥),逐事件

后端(events.ts):tool_call 与 before_agent_start 的白名单各加派生字段 handlers([{extension, returned}],returned 是摘要:{block, reason≤200} / {systemPromptDelta:+N, skills:[…]},不放原文)。 前端(trace-view.ts 投影 + TimelineView.tsx 一行文案绑定),零样式改动:

一处事实,免得实测时误判:pi 是先发 tool_execution_start 再问 tool_call(附 A-2),被拦截的调用在 Timeline 上是「start → call[blocked] → end(isError)」,与画板 1a 示例的「call → start」顺序不同。这是现状,不是本轮引入的。

2.7 配置面与限额(MCP)

• 迁移 013(纯追加,依赖 1.0 的 012):skills.agent_enabled BOOLEAN NOT NULL DEFAULT FALSE;sandbox_config 单行表(daily_run_limit 0 = 不限;total_timeout_ms 默认 30000,CHECK 5000–120000);daily_quota.skill_runs;tool_config 两行种子(§2.3)。agent_ro 对新表新列无权限(不写 GRANT 就是答案,1.0 口径不变)。
• MCP 工具 +4(1.0 的 42 → 46):skills_agent_set(name, enabled) · skills_agent_status(代码清单里每个 skill:库里有没有 / 打开没有 / hash 一致还是 drift)· sandbox_config_get / sandbox_config_set。
• 打开顺序:发版(runner 镜像 + api)→ 生产冒烟四条(§2.8)→ tool_config_set skill_load true → skills_agent_set <name> true → 服务器 .env 加 XRAY_UNLOCK_DANGEROUS_TOOLS=1 并重建 api → tool_config_set skill_run true。可用集合的指纹并进 EnabledTools.fingerprint,任一变化下一轮重建会话(R6/R7 规则)。
• 止损:tool_config_set skill_run false 当场停用;skills_agent_set <name> false 单个下线;docker compose stop skill-runner 则工具调用全部以固定文案失败,站点其余照常。

2.8 部署、本机开发与生产冒烟(裁定 7)

• dev.ps1 build 出第三个镜像 xray-runner:<sha>(docker build runner/);ship 三镜像一起 save;compose 加服务 + 命名卷。规则 11 不受影响:runner 不是 JS 运行时,基座 python:3.12-slim 按 digest 钉(境内先 docker pull)。
• 主机预算:3.6 GiB 下现有 128 + 384 + 1024 + 768 = 2304 MB,加 384 MB 后剩 ~900 MB 给 OS 与 cache;docs/deploy-cn-lightweight.md §0 预算表加一行。
• 本机开发拿不到 unix socket(api 在 Windows 宿主,runner 在容器里):runner 有 RUNNER_LISTEN=tcp://0.0.0.0:8000 开发模式,dev.ps1 runner 起 docker run --rm -p 127.0.0.1:8000:8000;api 侧 XRAY_SKILL_RUNNER_URL 只在注册环节读,且只接受 unix: 默认值或 http://127.0.0.1:<port>(代码级闭集)。
• 生产冒烟 +4 条(docs/deploy-environments.md 冒烟清单第 6 步追加;skill_run 双闸关闭状态下跑):① skill-runner healthy;② 容器内 python -c "import socket; socket.create_connection(('1.1.1.1',53),2)" 失败、ip route 为空;③ 容器内 touch /opt/skills/x 失败(只读);④ 经 socket 对 /run 发一个不在清单里的脚本名 → 拒绝。四条过了才走 §2.7 的打开顺序。
• dev.ps1 test:守卫规则 / 清单生成 / schema 校验 / hash 一致性 / 指纹 / 限额是纯逻辑测试;runner 协议用假 HTTP 服务;真跑脚本只在生产冒烟。

3. 与现有规范的冲突清单(本次文档轮已改)

不用改的:画板 1a/1b/1c(拦截徽标、注记、EXTENSION RETURNED 卡、链式步骤都已画着);1.0 的三张表结构与八个 MCP 工具;第 1 层「执行类工具双闸」那条(它就是为这件事准备的)。

4. 安全分析

访客(经模型)能控制的输入面:skill / script(两个闭集里挑)、input(≤ 4 KiB 的 JSON,过 schema)。控不到:解释器、命令行、代码、路径、网络、环境变量、并发数、超时。

5. 不推荐的替代方案

6. 依赖关系与顺序

• 2.0 的迁移 013 依赖 012;skills_agent_set 依赖 1.0 的 skills 表;hash 一致性判据依赖 1.0 的 skill_files。
• spike 不过 → 不进 2.0,回所有者重裁裁定 4(裁定原文:不自行退到共网)。
• 本文档轮(规则 9 先改文档)已合并 main;2.0 代码轮另开 session,从 round-skills-2.md 开工。

7. 代价与工作量(估)

• 新增面:1 个容器(+384 MB 预算)、1 条迁移、2 个工具、2 个 pi 扩展、4 个 MCP 工具、1 个构建期生成器、dev.ps1 3 个子命令、前端 3 处逻辑。
• 量级:大于 R-IMAGEGEN(它没有新容器、没有构建期生成物),小于 R9。
• 长期维护热点:可运行脚本的审阅、dev.ps1 build 的第三个镜像(与 $hostedServices 同类「漏补」热点)、清单生成物的漂移测试、库内副本与代码副本的一致性(skills_agent_status 是给所有者看的那面镜子)。

附 A:pi 0.84.3 内核实测依据(源码位置,主 checkout 的 apps/api/node_modules/@earendil-works/pi-coding-agent)

• A-1 skills 依赖 read:dist/core/system-prompt.js:27–30, 112–114 —— 只有 read 在 selectedTools 里才 formatSkillsForPrompt;dist/core/skills.js:275–296 —— 提示词原文「Use the read tool to load a skill's file」。resource-loader.d.ts 提供 noSkills / additionalSkillPaths / skillsOverride;本站 loader 应显式 noSkills: true。
• A-2 tool_call 否决的完整路径:dist/core/extensions/runner.js:701–719 emitToolCall —— 按注册顺序遍历,result.block 为真立即 return;dist/core/agent-session.js:214–241 _installAgentToolHooks —— beforeToolCall 直连它,handler 抛异常时整段变成「Extension failed, blocking execution」;pi-agent-core/dist/agent-loop.js(嵌套在 pi-coding-agent 自己的 node_modules 里)executeToolCallsSequential —— 先 emit tool_execution_start,再 prepareToolCall;prepareToolCall —— 参数先过 validateToolArguments,再问 beforeToolCall;block → createErrorToolResult(reason),kind:"immediate",isError:true;immediate 结果不经过 finalizeExecutedToolCall,因此 afterToolCall(扩展的 tool_result 事件)不触发;emitToolExecutionEnd 与 toolResult 消息的 message_start/end 照常。
• A-3 before_agent_start 链式语义:runner.js:837–870 —— 每个 handler 收到的 event.systemPrompt 是前一个 handler 修改后的值;agent-session.js:887–907 —— 有人返回 systemPrompt 就覆盖本轮,否则回到 base。sendCustomMessage(:1071–1100)非流式路径会发 message_start/end,本站的历史注入走这条。
• A-4 访客输入以 / 开头会走命令分发:agent-session.js:795–831 prompt() 默认 expandPromptTemplates: true,text.startsWith("/") 先试扩展命令、再试 /skill: 与 prompt template。今天没有任何命令与 skill 被加载所以无害;守卫与注入器都不得 registerCommand,loader 保持 noSkills。
• A-5 类型面:extensions/types.d.ts:699–702 CustomToolCallEvent.input 可就地改写(本方案不改写);:803–812 ToolCallEventResult {block, reason, terminate};sdk.d.ts:33–47 noTools / tools / customTools 三参数即现有闸。

附 B:python-workdir-guard.ts 逐段迁移对照