tako 文档 GitHub

52 · 技能(Agent Skills)

性质:已落地(2026-10-28;A1–A4、B1–B8、C1–C5、D1、E1、E2、F1–F3、G1 全部施工并验收)。 状态:✅ 已落地(2026-10-28,24 拍全部施工并验收)。施工台账 tmp/52-技能/{planning.md,todos.md} 已写并经用户检查通过(24 拍)。A1 落地内容:skill_rows + skill_disables 两张表(含部分唯一索引 (tenant_id, name) WHERE valid)、GET /api/skills(空实例回 {"skills":[],"invalid":[]};租户从 token 取);落点 internal/runengine/skills.go、pgstore.go、server.go;契约字节是 scripts/acceptance/expected.json 用例 14 + doc/19-v6/19v6-04-验收-curl.md 同号散文。A2 已落地:POST /api/skills/rescan(租户 owner/admin;扫盘在库级两级锁内:全局共享 + 租户独占,pg_advisory_lock 会话级)、frontmatter 最小解析(name/description/requires)、扫盘跳过 . 开头的目录、根不存在视同空而读失败中止;-system-skills-dir 旗标(默认 <workspace>/system-skills)。A3 已落地:系统管理员全量重扫(-bootstrap-admin-email 起;全局独占锁;扫系统根 + 每个租户根、比对全部行;系统行落空串 tenant_id 桶)——系统根读失败 → 整次中止、什么都不改(500,表行仍在),系统根读到 0 条 → 只报数不删系统层行;租户级重扫只扫本租户根、只比对本租户的行(系统行不参与);跨桶同名按「先占的生效」显式比(系统行 vs 租户行,索引管不到);同根两份同名 → 按路径序先占的生效、后来者 invalid;平铺形态 <name>.md 也进扫描。A4 已落地:GET /api/skills/:name 详情端点——名字按租户视界解析(查不到与「别的租户的同名」同回 404 116001,存在性不跨租户泄漏)、body 是盘上 SKILL.md 逐字原文(不转义不截断)、missing 字段从本拍起恒空数组(D1 拍填);skillBodyOf 收口成列表/详情共用一份拼装;行在盘无(手工删目录未重扫)回 500 并记日志。契约字节进 expected.json 用例 17 + 19v6-04 同号散文(A 段四条收口,check-expected.sh 绿)。B1 已落地(2026-10-28):<available_skills> 目录只拼 manager 的 Instruction(只放 valid 且本租户未禁用的行、描述原样全拼、空集时不加一个字节);read_skill/use_skill/read_skill_file 三个工具进 manager 池(本拍占位统一回 116001,B2/B4 换真实现);普通子代理在入口快照里剔掉四个保留名(skill_install 从本拍就含,晚一拍就有一拍是泄漏);Frame.toolCallId与 runlog tool_call/tool_result payload 加同名字段(帧与历史行同一套配对键);GET /api/runs/:id/skills 空实现(loads:[],B4 填派生);落点 skilltools.go、profile.go、agents.go、worker.go、store.go、types.go、server.go、auth.go(116001);契约字节进 expected.json 用例 18 + 用例 1 末步(真 run 上的 loads:[]),19v6-04 同号散文,check-expected.sh 绿;活体:manager 回复逐字出现 demo(目录只来自 Instruction)、read_skill 的 call/result toolCallId 成对、coder 子代理回复「没有技能工具」且 runlog 无其技能行。B2 已落地(2026-10-28):read_skill 换真身——按名字取本租户视界内的行(GetSkill;别的租户的同名走「表里没有」,字节与查一个不存在的名字完全一样)、禁用闸 116107、读盘后剥 frontmatter(stripSkillFrontmatter,与扫盘认同一套边界)、正文里的 &/< 转义后包成 <skill name="…" source="…" bytes="…">…</skill>(不带 path,bytes 是技能目录里普通文件之和,与列表/详情同一个数);超 16,384 token(cl100k)或 64KB 回 116116 信封、不截断;计数器由技能工具自己持(skillToolbox.tokenCounter 懒构造——不复用 -compact-window>0 时 main 造的那把,-compact-window=0 时照判,词表拉不到就让这次调用失败而不是跳过判据);use_skill/read_skill_file 仍是占位(B3/B4)。同拍补了 B1 目录的转义缺口(名字/描述/location 过 escapeSkillXML、描述折叠空白——不转义时描述里一段 <skill> 示例就能顶开目录块边界);落点 skilltools.go、auth.go(116107/116116)、worker.go(newSkillTools(store))、skilltools_test.go;契约进 expected.json 的 declared_not_asserted 用例 19(工具结果字节只有真跑模型才造得出;纯函数侧由 go test 钉住)与 19v6-04 用例 19 散文(成功/转义/116116/116001/116107 五组实跑字节),check-expected.sh 绿;活体在隔离引擎 8943(tako_b2 库)。B3 已落地(2026-10-28):use_skill 换真身——与 read_skill 走同一条读路(loadByName:租户视界取行 → 禁用闸 → 读盘剥 frontmatter → 转义渲染),成功回执与 read_skill 逐字相同(活体按 runlog 的 tool_result.payload.output 原文比对),差别只在成功时把 {name, root} 记进本场 run 的技能盒子(skillbox.go:skillBox 带 mu、按根去重、list() 回快照;withSkillBox/skillBoxFrom/skillReadRoots;装配点在 worker.go 的 withTaskBox 之后)。围栏那半边:sandboxProfile(root string, extraReadRoots []string)——盒子里每个技能根只加一条 (allow file-read* (subpath …))(只读:技能脚本能跑、能读自己的 references,改不了正文;隔壁没 use_skill 过的技能根仍看不见),写仍只在项目根;sandboxWrap(租户 MCP)传 nil、不吃技能根;普通子代理在 runSubagentGuarded(派发与续跑共用的那道口)拿空盒子,不继承爹的根(D25)。同拍放开网络出口(D37):profile 加 (allow network-outbound)、不开入站;实测口径修正——台账原写「宿主监听端口连不上」是错的,loopback 的 connect 属出站,围栏里 curl 127.0.0.1:8931 回 LOOPBACK 200,入站被拒的证据是围栏里 socket.bind/listen 回 PermissionError: [Errno 1] Operation not permitted。出站开了之后 curl https://example.com 仍报 LibreSSL「Auto configuration failed」(起手要读 /private/etc/ssl/openssl.cnf 与 CA 包),补 (allow file-read* (subpath "/private/etc/ssl")) 后回 HTTP 200——只放证书与配置,/etc/passwd 的显式拒绝照旧。顺带修掉一个既有隐藏 bug:commandInsideRoot 与 sandboxRealPath 两侧先 Abs()——-workspace 传相对路径(../tmp/workspace-b2)时 EvalSymlinks 回相对结果,filepath.Rel(相对, 绝对) 报错 → 租户 MCP 一律被判「命令在围栏外」(503 111411)。落点 skillbox.go(新)、skilltools.go、worker.go、agents.go、sandbox.go;单测 skillbox_test.go、skillfence_test.go、mcpfence_test.go(相对根用例);活体验收夹具 scripts/acceptance/mcp_fetch_server.py(stdio MCP、工具 fetch_probe 在围栏里 curl,sink 写脚本旁——/dev/null 在围栏里写不进);契约进 expected.json 的 declared_not_asserted 用例 20 与 19v6-04 用例 20 散文,check-expected.sh 绿;活体(隔离引擎 8943)四组:use_skill 后 cat/python3 scripts/x.py 通、写被拒;新 run 与隔壁技能被拒;coder 子代理被拒;curl 与租户 MCP 都回 200。本拍超 80 行,拆成两拍施工(B3a 工具+盒子、B3b profile+网络+路径修复);read_skill_file 仍是占位(B4)。另一条实测观察未修:macOS 大小写不敏感盘上,Go 的 Abs() 给出 /users/…、按 Python realpath 存进 MCP 配置的命令是 /Users/…,字节比较把它们判成两个路径(验收里按小写存命令绕开)——B4 已落地(2026-10-28):read_skill_file 换真身——按名字取行(GetSkill)、同一道禁用闸(116107),然后在这个技能的资源根内解析 path:根 = 目录形态的入口文件所在目录,平铺形态(<name>.md)没有资源目录、一律 116114;cleanSkillRel 先拒空/绝对/任何一段 ..(不靠 Clean 折叠),再 EvalSymlinks 后 filepath.Rel 判包含,软链跳出根也是 116114,文案与「文件不存在」完全相同(不透露根外存在性);path 命中入口 SKILL.md 用 os.SameFile 认出、回 116114 并指向 read_skill;目录回不递归条目列表(os.ReadDir,目录条目不带 bytes、悬空软链跳过),文件回 {"code":0,…,"data":{"name","path","type":"file","content","bytes"}};上限与正文同一条判据(64KB 先判、cl100k 16,384 后判),超了 116115、一个字节都不带(§9-31)。同一批把 GET /api/runs/:id/skills 换成真派生:Store.SkillLoads 取本 run 的 tool_call/tool_result 行按 seq 排序,loadsFromEntries 用 toolCallId 配对,成功判定 = XML 前缀 <skill 或 JSON 信封 code==0,配对不上的 call 记 ok:false 不带 code;一行字节序 {toolCallId,name,tool,path,agent,seq,ok,code},path 只在 read_skill_file 行。落点 skilltools.go、skills.go、server.go、auth.go(116114/116115)、skillresource_test.go(新);活体(隔离引擎 8943):references/ok.md 60,500 字节全文返回、bytes 与 wc -c 一致,big.md 71,699 字节回 116115 无部分内容,../x/../../../etc/passwd/SKILL.md 三条都是 116114,目录列 big.md/nested/ok.md 且不递归,GET /api/runs/<rid>/skills 回八行、path 只在六条 read_skill_file 上,三条失败码 116115/116114/116114 与 ok:false 对齐。契约进 expected.json 的 declared_not_asserted 用例 21 与 19v6-04 用例 21 散文,check-expected.sh 绿;用例 18 的 loads:[] 实跑字节换成 B4 代码上的无技能 run。真实配置一般由同一台机器生成,暂不为此加折叠。E1 已落地(2026-10-28):manager 规格的 skills:/exclude_skills:(与 tools:/exclude_tools: 同形,parse 层同写即拒载「二选一」;skills: [] 靠指针非 nil 表示「一个都不要」)落成 tenant_agents/agent_defaults 上的 skill_policy 列(JSON 面 {"mode":"allow|exclude|inherit","names":[…]},agent 读写与导入都认 skillPolicy);作用域在四处解析时点生效——装配期目录过滤(scopeSkillRows)、read_skill/use_skill 共用的 loadByName、read_skill_file、D35 看板恢复(作用域外的技能不借「看板里有任务」把根补回 bash 围栏);作用域外的名字与「表里没有」回同一个 116001 字节,模型把目录名字念歪也读不到;普通子代理写 allow/exclude 在入口 400 111002(JSON 新建/更新与 md 导入同判),出厂规格写了在 seed 日志拒载——显式 inherit 放行,因为 GET 回读总带这一份、客户端原样 PUT 回来不该被拒。落点 agents.go、product_store.go、product_api.go、skills.go、profile.go、worker.go、skilltools.go、skillrestore.go、新文件 skillscope.go;测试 skillscope_test.go(策略判据/目录过滤/ctx/JSON/解析闸/更新落库)与 agents_test.go 的 TestParseAgentSpecSkillScope。活体(隔离引擎 8943、deepseek-flash):allow ["dep-demo"] 目录只列 dep-demo、作用域内读正文成功、调表里存在但范围外的 dep-check 回 116001;改 exclude ["dep-demo"] 后同一调用回同一字节;skills: [] 目录为空。活体验收抓到一处真洞:UpdateAgent 的 Updates map 漏了 skill_policy,PUT 只改了内存行(响应看着成功、库里没动、下一场 run 仍是旧作用域),已补列 + TestUpdateAgentPersistsSkillPolicy 回归。契约进 expected.json 用例 29(7 步)与 19v6-04 同号散文,check-expected.sh 绿,core 活体 78/78。E2 已落地(2026-10-28):禁用收口成「可撤销、按租户、不被吞」的开关——PATCH /api/skills/:name 只写 skill_disables(SetSkillDisabled 两方向幂等:false = FirstOrCreate、true = Delete),不碰 skill_rows、不碰盘;目录装配与 read_skill/use_skill/read_skill_file 读同一张禁用表(禁用后目录无它、工具回 116107「这个技能已被禁用,请先在管理页恢复」);正在跑的 run 盒子不回缩——盒子只在 use_skill 成功时登记,禁用不碰盒子,已开的执行权不中途收回;owner/admin 才可写(viewer 403 111203),未登录 401 111102;禁用与恢复各发一条 skills_changed,字节按 doc/46 §7.6 的 {seq,type,id,at}——台账原写的 {action,name} 作废:action 是状态,事件带状态就会诱导客户端就地改本地副本而不重拉,与「事件只通知、状态永远重拉」冲突,名字也已由 id 承担;DELETE 同事务清禁用行(重装同名后列表回 enabled:true,行为可证)。验收工具补两个原语:invite_viewer(owner 发邀请 → 时间戳邮箱注册 → 登录 → 切到邀请方租户,拿真 viewer token;不切租户时名字解析落在个人租户,实际回 404 而非 403)与 tokenVar(用另一个身份打一条请求)——「有身份但角色不够」不能用 401 代替。契约字节 expected.json 用例 30(15 步)与 19v6-04 同号散文(run 侧目录/116107/事件实录进 declared_not_asserted),check-expected.sh 绿,core 活体 93/93。F1 已落地(2026-10-28):工具上传写面——GET/POST/DELETE /api/tools 三个端点,工具根 <tenant>/tools/<name>/bin/<name>,不进表(列表就是 os.ReadDir,跳过 . 开头:.staging 里在途上传的 bin/<name> 被列出来等于半成品先用)。上传五步:MaxBytesReader 卡 128MB(超了 413 116118)→ 名字白名单 ^[a-z0-9][a-z0-9-]{0,63}$+拒 bash/sh/env+拒空文件(400 116117)→ ReserveStorage 先占额度(不足 429 113001)→ 写 .staging/<rand>/bin/<name> 0755 → C1 同一把锁内「旧前缀进 .trash/<name>-<ts> + rename」。上传/删除只给 owner/admin(viewer 403),列表所有成员可读;删除前名字过同一套白名单(.. 会拼成租户根);不存在回 404 116119;成功后发 tools_changed(与 skills_changed 同形的 {seq,type,id,at},type 分开是为了让客户端知道重拉哪一页)。落点 toolroots.go、events.go、auth.go、server.go,测试 toolroots_test.go;契约字节用例 31(19 步)与 19v6-04 同号散文,core 活体 138/138。F2 已落地(2026-10-28):工具根对所有角色常开(含普通子代理),与技能根的证据闸方向相反。①围栏:sandboxReadRoots(projectRoot, toolsRoot) 把 <tenant>/tools 整棵加进只读白名单,startBash 的 profile 读面 = 本场 use_skill 过的技能根 ∪ 工具根,写面仍只有项目根——run 改不了自己的解释器(实测 echo x > <tools>/hello/bin/hello 回 Operation not permitted)。②PATH:subprocessPath(projectRoot, toolsRoot) = 每个 <tools>/<name>/bin(跳过 .staging/.trash 这些 . 开头的目录、必须真有 bin、逐段 EvalSymlinks)前置,再拼宿主 PATH 里过 sandboxReadRoots 的那些段(保序去重);bash.go 的 cmd.Env 只从这个函数取,D1 的依赖检查(skillDependencies/missingSkillDependencies)也走它——which hello 指向 <tenant>/tools/hello/bin/hello,which python3 仍是宿主排最前的那个,围栏外目录照旧 command not found。③租户根怎么找:HTTP 侧从目录形状 <tenant>/{workspaces,sessions}/<id> 上溯两级,run 侧优先 ctx 的 WorkspaceRef.TenantRoot,两条路落在同一个 <tenant>/tools(不然检查说「找到了」、bash 却解析不到)。落点 sandbox.go、subprocesspath.go、bash.go、skilldeps.go、skills.go、skillinstall.go、skilltools.go,测试 subprocesspath_test.go(工具 bin 前置、点目录剔除、相对根)。活体(隔离引擎 8943、deepseek-flash):不调技能直接 hello → hello-from-tenant-tool;coder 子代理跑 hello → 同一行输出,同一子代理 cat <技能根>/tool-consumer/SKILL.md → Operation not permitted(两条闸方向相反);requires: [hello, no-such-tool-f2] 的技能 GET /api/skills/tool-consumer/check → hello 的 found:true 且 path 在 <tools>/hello/bin/hello、另一个 found:false;一场 run 里第一枪读旧版,期间 POST /api/tools 覆盖,第二枪输出 hello-from-tenant-tool-v2(原子 rename、PATH 里的路径没变);DELETE /api/tools/hello 后下一场 run hello → 退出码 127 command not found,lastRunStatus=complete(工具没了不把 run 变 error)。偏差:D1 留的「checkedOn 到 F2 再区分来源」不成立——检查始终在接单副本的宿主上做,工具根也在这块宿主盘上,没有第二个来源,仍恒 "host"。另一条实测观察(不属本拍、未修):围栏写面只有项目根,主 run 与子代理里 cmd 2>/dev/null 都会在 /dev/null 上报 Operation not permitted(既有行为)。F3 已落地(2026-10-28):工具区前端——新页 web/src/ToolsView.vue:列表(名字、字节、更新时间、路径、被技能引用——从 GET /api/skills 的 requires 现算,盘上工具没有反向索引)、上传(命令名输入 + 选文件,名字白名单在页面上先挡一道,服务端仍是裁判)、同名覆盖与删除两个确认框;没有「检测」「试跑」按钮(能不能跑由 run 里的 bash 回答,D22 同一条线)。入口两处:App.vue 的 Page 加 tools 与导航按钮;技能详情里每个 missing 依赖旁一个「上传 <名字>」,点后切到工具区并预填命令名、聚焦输入框(SkillsView emit upload-tool → App.openToolsFor → ToolsView.prefillName)。协议层 api.ts 加 listTools/uploadTool/deleteTool;mutation.ts 的 MutationEvent.type 补 tools_changed——F1 起服务端就在发这个事件,前端词表漏了它,SSE 到达时会被类型挡在 handler 外(tsc 在 F3 抓到);ConfirmDialog 加 tone/busyText 两个可选 prop,覆盖动作不再用红色「删除」按钮与「正在删除…」文案。浏览器验收(Vite 5174 代理到隔离引擎 8943、owner 账号):页面上传 hello → 行出现(38 B、被技能引用:tool-consumer、真实路径);同名再传 v2 → 出现「替换同名工具?」(正文写明「正在跑的对话不受影响,下一次调用起用新版本」)→ 替换后 41 B;对话里让模型跑 hello → hello-from-tenant-tool-v2(该轮模型还派了子代理,顺带复证 F2);删除 → 确认后行消失、已上传 0;技能详情 tool-consumer 的两个缺失依赖旁出现「上传 hello/no-such-tool-f2」,点前者落在工具区且命令名已填 hello、输入框聚焦;npm run typecheck 与 npm run build 绿。偏差:本轮 in-app Browser 没有可见视口(NATIVE_BROWSER_VIEWPORT_UNAVAILABLE,pointer click 被拒),改用 evaluate_script 触发 DOM click、并把隐藏的文件输入临时解除 hidden 后用 upload_file 注入——页面结构与提交路径都是真的,只是操作入口不是鼠标。本拍只改前端,契约字节未动(expected.json 不变)。G1 已落地(2026-10-28):清扫与对账收口。①过期清扫:新文件 tempsweep.go——tempDirTTL = 24h、sweepTempDirs(root, now) 读 <root>/.staging 与 <root>/.trash,条目 mtime 超过 24 小时就 os.RemoveAll,读目录失败只记日志(点目录不存在是常态),启动时不扫盘;调用点全部落在已有的锁内(§4.6 第 4 条):技能安装 installSkillCandidates、技能删除、租户 rescan、全量 rescan(每个租户根 + 系统根各清一次)、工具上传、工具删除——技能根与工具根同一条规则、同一个函数。活体(隔离引擎 8943):两个根各造 25 小时前的 .trash/.staging 条目与一个刚建的 → 一次租户 rescan 后技能根的旧条目消失、一次工具删除(回 116119)后工具根的旧条目消失,刚建的两条都留着;单测 TestSweepTempDirsByMtime(25h 删/23h 留/未来 mtime 留)与 TestSweepTempDirsNoDirs(不建目录)。②行/盘对账:手工造 g1-manual 目录 → rescan 的 added 有它;删目录 → 下一次 removed 有它一次、第三次 removed: [],skill_rows 无重复行;并发 rescan + 安装三轮(g1-race 包)→ 每轮安装 code 0/installed:["g1-race"]、rescan 的 removed: []、技能仍在列表。③全量回归(2026-10-28):assert_contract.py core 112/112、全量(含 model tier)138/138;spotcheck.sh 37/37;taskboard_crash.sh 通过 9 条(kill -9 → resume → 看板 5→8 行、崩前 0 丢失、lease_epoch=2、terminal);go test ./internal/runengine + go vet 绿;npm run typecheck/build 绿;check-expected.sh 与 check-master-plan.sh 绿。④审计补拍(同日,用户要求「不限于已有测试项」复查时发现):sweepTempDirs 会删掉同一段临界区正要 rename 走的那份 staging——对话内安装的提议挂起超过 24 小时、用户点头批准时,锁内先清扫再 rename,源目录已被自己当垃圾清掉,os.Rename ENOENT,用户读到 安装失败:rename …: no such file or directory 而不是设计好的「安装已过期」。修法是唯一豁免:sweepTempDirsKeeping(root, now, keepStaging) + stagingKeep(root, staging)(只认「本根 .staging 直下」的目录名,工作区在符号链接下时也认;别处的路径一律不豁免),技能安装与工具上传这两个消费 staging 的点传自己在途的那份,删除/重扫那四个点不传。豁免不攒垃圾:在途 staging 由调用方的 defer os.RemoveAll 收走。活体(隔离引擎 8943):造两个 48 小时前的 staging(一个被 pending 的 kind=install 行指向、一个没人认领)→ 批准那一枪回 已安装技能:g1-aged。、技能目录与 skill_rows 行都在、.staging 清空(没人认领的那个被同一枪清掉——证明清扫真跑了,豁免是精确的而不是「没执行」)。单测 TestSweepTempDirsKeepsInFlightStaging、TestStagingKeep。D37(出站网络)的活体状态仍登记在 expected.json 用例 20 的 declared_not_asserted(租户 MCP 同一条 profile),不另立断言。

B5 已落地(2026-10-28):run_tasks 加 skill_name(not null;default:,空串 = 非技能任务),写入点只有 TaskCreate——它读 skill 盒子的末尾项(usedSkillName;盒子对重复 use_skill 挪到末尾,所以末尾 = 最近一次),read_skill 不写盒子、use_skill 之后没 TaskCreate 就一行都不多;taskBoardView 每行带「(技能:名字)」(TaskList、写回执、kind=task 帧同源),TaskGet 多一行技能名;kind=task 帧加顶层 skillName(omitempty = 触发写入的那一行所属技能,UpdatedAt 最新、同刻取 task_no 大)。落点 tasktools.go、skillbox.go(usedSkillName 与挪尾)、types.go(Frame.SkillName)、tasktools_test.go/skillbox_test.go;活体(隔离引擎 8943,真模型):use_skill(demo) → 两条 TaskCreate → task 帧 skillName:"demo"、text 两行都带「(技能:demo)」;同场再 use_skill(other) 不建任务 → run_tasks 仍两行、skill_name 都是 demo;新 run 只 read_skill 后 TaskCreate → 帧不带 skillName、行 skill_name 为空。契约进 expected.json 的 declared_not_asserted 用例 22 与 19v6-04 用例 22 散文。2026-10-27 立项;2026-10-28 复审拍板 10 条(bash 沙箱白名单按角色注入、不做技能搜索、写操作单入口 + 库级分布式锁、正文上限收口、v1 不管 111408、项目技能后置;外加执行模型翻案:manager 自己读正文自己执行、取消内置 skill agent、正文 XML 包裹、折叠留痕、任务替身)——见 §3 的 D25–D32 与 §9 的「已拍」标记。2026-10-28 第二轮复审(把全文的代码引用逐条拿真实代码核对之后):①按用户裁定改口径 4 处——D7 改成不做三层覆盖(当时写成「名字全局唯一」,第十三轮已按租户收窄到「租户视界内唯一」)(连带 §4.3、§4.7 唯一键、§4.5、§6.2、§11.1)、D32 兜底任务按 (run_id, skill_name) 幂等、§2.5 第 2 条的「任务是正文的替身」只在同一场 run 内成立(跨 run 靠会继承的 skill-ops 块 + 重读)、§2.3 删掉「词表拉不到就退化」这条走不到的分支(真实场景是 -compact-window=0 时计数器为 nil);②清扫 D25 翻案的两处残留(§2.2、§9-32 的「manager 读不到技能根」已作废);③按真实签名改写 §4.4 的沙箱落点(sandboxProfile(root string) string 单入参,要改签名,不是「现成」),并记下复审发现的绕过口子(§4.4「复审发现」、§9-34 待拍;随后第三次核对 bash.go,把「一次绕过五条」修正为「绕过三条」——正文上限被 bash 自己的 32KB 输出上限兜住且会明说截断,<skill> 整块替换只损失一层有限的暴露面);④补 §8.2-2 的目录返回形状、§11.2 的「反转义后逐字一致」验收口径、§9-1 的禁用落点(该轮的「塞进租户 config」结论已被第五轮推翻)、§9-31 与 §9-35 两条待拍、§10.1 施工提醒。2026-10-28 第三轮(正文的去留):新增 D33——看板出现该技能的 TaskCreate 之后,下一枪就把 <skill> 块换成 marker(每枪重写,压缩关掉也执行);D30 从「trim 认得」扩成「fold/trim 都认得」(fold 那路会把正文截成 2000 runes 塞进摘要,比 marker 更误导)。连带改:§2.5 存储层一行(mh 存的是模型实际看到的形态,不是原文档案)、§6.4 对话卡片(展开模型看到的那段,不回盘重读)、D19/D29/§2.8/§13 的理由句(「manager 手里一直有正文」不再成立——追问重读 load_skill、逐字原文 grep 即可)。同日追加:技能脚本的工具根拍为 <tenant>/tools/(不放项目内、不放 HOME),含目录约定、解析顺序(工具根优先于宿主 PATH)、只读放行、PATH 前置、计入租户存储额度五条,见 §4.2、§7、§10.1-18。同日再补(用户指出「skill 里的第 3 步未必是 todos 的第 3 步」):看板任务的 task_no 是 COALESCE(MAX(task_no),0)+1 在 run 内按创建顺序自增,与正文步骤编号没有对应关系,run_tasks 也不记 step 号——所以折叠 marker 从 steps="见看板任务" 改成 reload="load_skill" tasks="见看板"(「正文从哪拿回来」与「进度在哪」是两件事),并连带改 §0、§2.5 第 2 条(新增「看板任务不是正文步骤的编号副本」一段)、§2.5 第 4 条、§2.9、§2.10、§5、§6.4、D29、D32、D33、§9-17、§10.1-B2、§13 的「展开成看板任务/步骤进看板」措辞。2026-10-28 第四轮(跨 run 续做,D34):用户指出看板本来就有说明字段(摘要 + details),「用户说改第 3 步」应当去查本会话最近一场的看板第 3 条、读它的说明、重建计划再确认。核实:description 字段在,但 schema 写的是「可选补充说明」、TaskList 只渲染主题(tasktools.go:156)、TaskGet 只查本场 run——三件事今天都做不到。已拍 D34(TaskList 带「上一场」未完成行及说明、写回执不带;description 语义升级;确认只在步骤增删换序时走 submit_plan),并把 §2.5 第 2 条的跨 run 载体从「摘要记录块 + 重读」翻成「看板为主、正文重读为兜底」,同时定下「用户说的第 3 步 = 看板的 #3,不是正文的 step 号」;连带改 §2.9(记录块降为提示)、§5、§11.2、§13,并在 doc/41 §3.3/§5.1 记了读口与字段语义。2026-10-28 第五轮(用户裁定「禁用状态另建一张小表」):禁用从「塞进租户 config JSON 的 disabledSkills」改为 skill_disables(tenant_id, name) 独立表,连带改 D6、§2.7、§4.5、§4.7、§6.1、§9-1、§10.1;两条被否掉的路(挂 skill_rows.disabled 会被出厂技能的全集群共享行放大成「一个租户禁、全租户禁」;塞 config JSON 会被读(json.Unmarshal 进四字段结构体,product_store.go:818-819)与写(整列覆盖,:847-855)两道闸静默吞掉)写在 §4.7 表后。2026-10-28 第六轮(rescan 的边界):①取消 force 保护(人点重扫被拒时不知道盘为什么空;部署流程自动调它时没有人能点确认,撞上就卡死发布),改成两条结构性口径——根不存在则整次中止;系统技能根读出 0 条则只报数、不删系统层行(租户根 0 条是正常的,照常删),§9-35 因此从「待拍」翻成「已拍」;②rescan 返回体加 roots[](每个根读到几条),让运维看得见盘的状态,不必猜 removed 那个数字(§6.1);③唯一键从全表 (name) 改成部分唯一 (name) WHERE valid——全表唯一与「同名的后来者要存成 valid=false 行」(D7/§4.3/§4.7「invalid 进表」)互斥,两行同名插不进去(§4.7);④写明扫描范围=比对范围,按 scope/tenant_id 过滤——这不是新规则,是这两列本来就在表里的理由(§4.7、§11.1 加三条验收)。2026-10-28 第七轮(读与用分开):用户指出 D32「load_skill 成功就自动建看板任务」把「读一下说明书」记成了一件事——用户只想问「这个技能是干什么的」,看板会多一条没人做的幽灵任务,下一场还会被 D34 当成「上一场没干完的活」拎给模型。裁定:加一个只读工具 read_skill,把「读并执行」改名为 use_skill,并取消程序自动建兜底任务;run_tasks.skill_name 改由 TaskCreate 时按「本 run 最近一次 use_skill」盖戳。连带改 §0、§1、§2.2、§2.3(标题与全节)、§2.4、§2.5、§2.7、§2.8、§2.9、§2.10、D14/D19/D25/D26/D29/D31/D32/D33、§4.4、§4.7、§5、§6.1、§6.2、§6.4、§8、§9-7/§9-17/§9-19/§9-32/§9-34、§10、§10.1、§11.2、§11.4、§13。2026-10-28 第八轮(对话内安装改 HITL):旧 D24 的「本轮逐字校验」被判定两头都漏——用户把 PDF/邮件正文贴进对话框时那串字就在他的 user 消息里(放行),而模型给的是解析后的来源、用户原话是命令串(误拒);同时本仓已有「模型提议 → 程序落行 → 人答 → 答案作为 tool_result 回同一轮」的原语(ask_user 四拍,waittools.go:1-8、:44-58,答案端点已按 kind 分支,questions.go:218)。裁定:skill_install 不再是写工具——只解析(staging)+ 落 run_questions(kind=install) 行 + 挂起;写盘由确认端点在人工点击后由程序执行,模型全程没有写路径;卡片事实由程序从 resolver 输出渲染(含「此来源在本会话未出现」一行,原逐字校验降级为提示不是闸);owner/admin 才能点,取消是正常 tool_result 而非错误码。连带改:D20/D24(D24 整条重写)、§6.6(整节重写)、删 116112、§6.1 写入口段、§4.3、§4.6 第 4 条(.staging 一并清扫、确认时不在=过期)、§5、§2.4 表、§2.8、§10.1-7/-8/-9/-16、C3 验收、§11.2、§9-26。2026-10-28 第九轮(压缩开关):拍下保留 -compact-window 的 0(调试逃生口,不是产品能力,今天也没有脚本用它),技能侧因此自己持有一把计数器、不看压缩旗标,并明确禁止「nil 时静默跳过字数判据」(§2.3、§10.1-10)。2026-10-28 第十轮(施工提醒按当时代码重核):§10.1 最后一轮整节修订是第二轮,之后几轮只点状改了 -7/-8/-9/-10/-16/-18 的口径,机制段落没跟着翻。重核发现两处照着做会做错:① item 7 的「新增一个 ctx 键拿本轮 user 原文」是旧设计——文案口径是「本会话」,读源应是 run_model_messages 的会话级查询,且不能带 compacted = false(pgstore.go:743 那条过滤正好把要查的旧历史滤掉);② item 8 漏了 denyRunWrite 只放 accessOwner(server.go:561-573)——D24 的「成员提议、管理员点头」在权限层根本没有落地,管理员点别人的 run 在这一步就被 403 挡死,kind=install 必须在这道闸之前分出来(改既有权限语义,要单独拍)。另修五处:item 6/18/21 统一到「一个 run 内可变盒子」,并纠正「别塞进 taskBox」(普通子代理也用它);item 12 的落点是 midfoldHandler(midfold.go:537)而不是子代理那个 agentFoldHandler;item 11/13 改用工具名判(names 表在 renderFold 里已经建好),不再嗅内容标记;item 16 的「根不存在就中止」只对系统根成立;item 19 的挂点是 TaskList 的闭包而不是共用的 taskBoardView。新增 A 拍的护栏(旗标/空目录夹具/跳过点目录/按归属比对/roots[])与「B 拍开工前必须先拍 §9-34/§9-31」两条,第十一轮因再插两条顺延为 24/25。2026-10-28 第十一轮(锁粒度,用户授权由我裁定,不再等拍):D27 从「整个技能面一把锁、包住全流程」改成两级——普通写取「全局共享 + 本租户独占」,全量 rescan 取全局独占;锁内只做搬目录与写行(rescan 另含本地扫盘),网络抓取/解压/校验/落 staging 在锁外。连带改 D27、§4.6 第 5 条、§4.7「多副本下的互踩」、§5、§6.1、§6.6 第 4 步、§10-C 验收、§11.3(新增跨租户不排队一条)、§13;§10.1 新增 22(advisory lock 是连接级、要拿住同一条连接、两级取锁顺序)与 23(rescan 扫盘必须在锁内,只有网络 IO 挪出锁外)。2026-10-28 第十二轮(bash 白名单的粒度与恢复,用户裁定):新增 D35——盒子每场 run 从空开始,恢复执行权按看板判、不按历史判:run_tasks.skill_name 里已有该技能的任务(续跑看本 run,新 run 看 D34 的「上一场」)就把它的根与工具根补回盒子(「已经生成 todos 就继续跑」);没有任务就要求重新 use_skill(「还没生成就重新加载」);补之前逐项重判 valid/未被禁用/盘上还在。同时把 §9-34 从待拍翻成已拍「只放本场 use_skill 过的技能根」(D25 整条重写:从「根 run 准读整个技能根」改成「run 内可变盒子」;cat 隔壁正文这条审计/策略洞随之关闭)。连带改 §2.2、§2.5(执行权也跟着看板走)、§2.8、§4.4(可见范围段 + 「复审发现」整节改成已拍 + 恢复段落)、§5(装配链路加恢复一步、新增一条关键实现点)、§9-32/§9-34、§10.1-25(只剩 §9-31 待拍)与新增 -26(D35 的落点与反向单测)、§11.2(D25 那条改写、新增 D35 三段反向验收)、§13。2026-10-28 第十三轮(唯一键按租户收窄):用户裁定「就是按多租户的方式」——skill_rows 的唯一索引从 (name) WHERE valid(=全表唯一)改成 (tenant_id, name) WHERE valid。原口径下两个不同租户各自装 pdf 会互撞 116106,而两家的技能根/目录/禁用项本来就互不可见。收窄后:同租户内的冲突(租户层 vs 本租户项目层、同层重复)仍由索引兜住;「系统行 vs 某租户行」这一对跨桶索引表达不了,由安装(含 skill_install 解析期)与两个 rescan 在 D27 的锁内显式查一次。连带改 D7、§4.3(标题、正文、新增「:name 端点按视界解析」与同租户跨层撞名)、§2.2、§4.5(删行与清禁用项都必须带 tenant_id:三处)、§4.7(列说明、唯一键两段、新增「为什么按租户收窄」与「这不是把闸降成提示」)、§6.1 DELETE 端点、§6.2、116106、§9-1/§9-27、§10.1-20/-24、§11.1(新增「两个租户装同名互不影响」一条、invalid 行那条补同桶例子)。同轮另拍 §9-31(资源读取上限):read_skill_file 单文件与正文走同一条判据(≤16,384 token 且 ≤64KB,同一把计数器、同一个判定函数),超了报 116115、不截断;不做「资源也走整块替换」、不给分块读加参数、安装期不扫资源——超上限的大文件由 manager 用 bash 分段读(输出 32KB/流 上限且明说截断)。连带改 §2.2、§2.3 对比表「超限」行与 trim 预算那段、§6.2 116115、§9-31、§10.1-10/-25、§13 缺口③。2026-10-28 第十四轮(缺依赖的补装通道):用户指出「缺一个 ffmpeg 只有运维能装」必须进方案解决(原话:「我觉得在方案里面解决这个」)。新增 D36——租户工具根开一个上传写面(POST /api/tools,owner/admin,单个可执行文件 → <tenant>/tools/<name>/bin/<name>;列表扫盘、删除进 .trash;只做文件级校验,不执行不探测;原子性复用 D10、锁复用 D27)。同轮把工具根与技能根两条边界分开:工具根是租户环境、按租户常开(所有角色的 bash 都可读,bin 前置进 PATH);技能根仍按 D25/D35 按证据收窄。requires 从此只服务「安装时检查」,不再决定「工具能不能用」。连带改 §1-3、D25、D35、§4.2、§4.4、§4.6-4、§5、§6.1/§6.2/§6.3/§6.4、§7(工具装在哪/解析顺序/沙箱/PATH/谁装,并新增「缺一个工具怎么补」)、§9-9/§9-15/§9-34/新增 §9-37、§10 新增 F 拍、§10.1-27、§11.1/§11.2/§11.3/§11.4、§12、§13。2026-10-28 第十五轮(网络出口与「工具没装」几时知道):用户指示「记得补上 agent 可以访问网络」(原文写作 magent),落 D37——sandboxProfile 加 (allow network-outbound)、不开入站;同一条 profile 也喂租户 MCP(sandboxWrap),所以 bash/技能脚本/子代理/租户 MCP 一起放开;代价明写:围栏不再阻止「下载并执行」,但下载物只能落项目根,系统目录与 <tenant>/tools 仍只读,自动装依赖仍不做(D11)。用户又问「skill 如果执行到某个工具无法执行因为根本没安装,怎么办」,落 D38——use_skill 成功结果的 <skill> 标签现查 requires,带 requires/missing 属性(不缓存、不阻断正文),模型见缺项就停下请管理员上传(D36)或运维同步、不自行安装;read_skill 保持零副作用。连带改 §2.10、D30、§7(围栏两处)、§9-38/§9-39、§10.1-28、§11.2、§12。 B6 已落地(2026-10-28):①跨 run 续做(D34)——TaskList 的读侧在空看板后再拼一段「上一场」:PreviousBoardRun 取同租户同会话最近一场(status <> deleted、按 created_at 倒序),ListOpenTasks 只取 pending/in_progress(按 task_no),渲染成 上一场(r_…)还有 N 项没完成: + 每行 #N [status] subject + 说明:description(description 非空才写);上一场没有未完成行 → 一行 上一场(r_…)已全部完成;TaskCreate/TaskUpdate 的回执与 kind=task 帧都不带这段(只有读侧拼,写侧视图函数签名不动)。工具描述与 taskBoardPrompt 同步要求 description 写「这一步具体做什么」——下一场只能靠它续上。②执行权恢复(D35)——worker.run 在 withSkillBox 之后调 restoreSkillRoots:续跑查本 run 已重放的任务行、新 run 查上一场,按 skill_name 逐项重判(行仍 valid、未被禁用、根仍在盘上),命中就把技能根补进 bash 盒子;任一条件不成立只跳过这一条,装配不失败、run 照起。落点 tasktools.go、skillrestore.go(新)、worker.go、tasktools_test.go、skillrestore_test.go(新)、skillbox_test.go;活体(隔离引擎 8943,真模型;租户 t_01M6117H7V22FYA900R3B7XT1D):run A 用 demo 建 3 条、完成 #1 → run B 第一枪 TaskList 含「上一场(r_01M6117H99…)还有 2 项没完成」与 #2/#3 的说明、写回执不带这段,且不调 use_skill 直接 python3 …/scripts/x.py resumed 成功(输出 X.PY-OK ['resumed'])→ run C 回「已全部完成」;反向:run D 只 use_skill 不建任务 → run E 的 bash 被围栏拒(Operation not permitted)、TaskList 无「上一场」;run F 建 1 条任务后跑慢脚本中途 kill -9 → 租约过期后 POST /api/runs/<rid>/resume 202 → 恢复后 SLOW-DONE、use_skill 只调过一次;run G 禁用后 use_skill 回 116107、bash 被拒,run H 删目录后回 116001 且 run 照常终态。契约进 expected.json 的 declared_not_asserted 用例 23 与 19v6-04 用例 23 散文。 B7 已落地(2026-10-28):正文用完让位(D33)——skillslim.go 的 skillSlimPlan 从行序算「哪些 toolCallId 的正文该换 marker」:从后往前扫,见到 assistant 行的 TaskCreate 就记下「更晚的地方建过任务」,之后遇到的 read_skill/use_skill 结果只要还是正文块就进集合;slimSkillBlocks 挂在 midfoldHandler.BeforeModelRewriteState 最上面(数输入与落库都看到 marker:同时改 state.Messages 与 box.base,convertState 的老行从 base 取),-compact-window=0 也执行;marker 逐字 <skill name="demo" folded="true" reload="read_skill" tasks="见看板"/>,reload 指回 read_skill(重读只要正文,不该顺手再声明一次执行)。fold 转录(renderFoldRow)与 trim(trimCandidate)两条消费点同形:fold 里技能行直接写 marker、不走 2000 runes 截断;trim 里技能块不进工具结果预算、不进还原队列,真动手时按 D30 做整块替换。判据只看 ToolCalls、不查库——所以「只 read_skill 不建任务」下一枪仍是全文(活体 r_01M611KX6:mh 41985 字节全文),跨 run 已用过的技能在新 run 里也仍是全文(新 run 的建任务落在正文之后,不满足「之后出现」)。落点 skillslim.go(新)、midfold.go、compact.go;单测 skillslim_test.go(新)。B8 已落地(2026-10-28):技能记录块(D31)+ trim 整块替换(D30)——skillops.go 从被折 assistant 行的 use_skill/read_skill 调用提取 {name,tool,runID}(坏 JSON 跳过、资源读取不算、同名取先进的),inheritSkillOps 解析旧摘要里已有的块并入池、mergeSkillOps 新旧并一批(旧条目在前、新提取排后,同名跨批去重),renderSkillOpsBlock 渲染 <!-- tako:skill-ops v1 -->(用过组在前、看过组在后、空组整段省略)。钉块在 foldInput 的 converge:与 file-ops 块并排接在摘要末尾(fileOps 在前、skillOps 在后),三档收口共用——全量钉 → 两表各砍 50 重渲染 → 仍超回 errStillOver(错误文案改成「fileOps/skillOps 块」,单测同步)。compact 不碰 DB、块里不写看板任务号(任务号归看板回答)。单测 skillops_test.go(新):提取/去重/往返/继承合并/与 D33 marker 共存。活体(隔离引擎 8943):建过任务之后 mh 的 tool 行是 66 字节 marker、同位置 runlog payload.output 仍是 42025 字节全文;两次压缩后的摘要(1047、943 字符)里都没有正文、块里都有 demo(use_skill,r_…)。契约进 expected.json 的 declared_not_asserted 用例 24 与 19v6-04 用例 24 散文。 C1 已落地(2026-10-28):安装/更新/删除(§4.6/§6.1)——skillinstall.go 新建:multipart zip/tar.gz 按魔数判格式,包在 <tenant>/skills/.staging/<rand>/ 里解完、校验完(zip slip/绝对路径/../层级 >5/文件数 >200/总字节 >10MB/软链/非普通文件全拒;frontmatter 与正文上限走与 B2 同一套判据,超 16,384 token 或 64KB 回 116116),校验在锁外、锁内只搬目录与写行(D27 普通写档:全局共享 + 租户独占)。落点:extractSkillPackage 按魔数分流到 extractZipPackage/extractTarGzPackage,findSkillCandidates 认任意含 SKILL.md 的目录,整包恰好一个 .md 时按平铺候选(装进标准目录形态);selectCandidates 支持 skills=a,b 与尾 * 前缀、all=true,多候选无选择回 116108。锁内:查冲突(install 用 skillNameTaken——同桶同名也算冲突,想换内容走 update;update 用 nameTakenInView——同桶同名那行就是它自己)→ 旧同名目录与 <name>.md 挪进 .trash/<name>-<unixnano>/ → os.Rename 搬目录 → upsertSkillRow 写行。崩在 rename 与写行之间 = 「目录在、行不在」:安装入口只看行,再装同名不会 116106,会重装并补回行(活体:手工删行留下目录 → 201、结局 1 行)。DELETE /api/skills/:name:锁内 GetSkill(无 → 404 116001;系统技能 → 409 116106「系统技能只读,不能删」)→ 目录进 .trash → 同一事务删 skill_rows 与 skill_disables(都带 tenant_id)→ {"status":"deleted"}。.staging/.trash 只创建,24h 清扫归 G1。契约:expected.json 新增 用例 25(清单现打 zip 走 harness.call_upload,十步全绿)+ 19v6-04 用例 25 散文;活体(隔离引擎 8943、workspace-c1)十二组:zip/tar.gz 各 201、列表与盘上落点、坏包四连(116105/116102/116101/116116 413)、同名再装 116106、update 200 换代进 .trash、update 未知名 116111、同租户并发 201+116106、跨租户并发双 201、viewer 403 111203、删除 200/再删 404/删后重装 201。

C2 已落地(2026-10-28):来源解析与预览(§6.1/§6.5)——skillsource.go 把三种输入(owner/repo、GitHub/GitLab 链接、整条 npx skills add …)分完词、验完白名单后变成结构体,从不拼回字符串、从不交给 exec;skillfetch.go 是抓取层:DialContext 里解析域名、拒 loopback/私网/链路本地/169.254.169.254/100.64/10 后直连验过的 IP(防 DNS rebinding),代理置 nil、重定向 ≤5 跳且每跳重走同一检查、下载 ≤50MB;GitHub 直连 codeload.github.com/<o>/<r>/tar.gz/<ref|HEAD>(github.com/archive 只是 302,少一跳也少一个可能打不开的域名),GitLab 先查 default_branch 再拼归档;skillresolve.go 把抓到的包落到 .staging/<rand>/、用仓库预算解开(200MB/20000 条目/12 层)、找候选、按 /tree/<ref>/<subpath> 过滤、再按单技能的 10MB/200 文件/5 层复核。POST /api/skills/preview 返回 {source,skills,ambiguous,warnings} 且不写正式目录;POST /api/skills/install 按 Content-Type 分流 multipart / JSON,同一落点、同一把锁;多候选未选择回 116108 时 data.skills 带候选清单(键序 name→description→bytes→requires)。真实仓库带来的四处兼容修正:① tar 的 pax_global_header/PAX 头是元数据,跳过而不当成非普通文件;② 仓库归档里的软链(如 CLAUDE.md → AGENTS.md)跳过、不落 staging,上传包里的软链仍回 116105;③ 仓库来源以 frontmatter name 为准,与目录名不同只进 warnings(装完目录名=名字,rescan 不会判 invalid),上传包仍按 116101 拒;④ frontmatter 认折行、>/| 块标量与 requires: 块序列——只读第一行会把合法技能判成「缺少 description」。落点:skillsource.go、skillfetch.go、skillresolve.go、skillinstall.go(解包器参数化 + readSkillUpload)、skills_scan.go(frontmatter)、server.go。契约:expected.json 用例 26(拒绝路径全在本地判红:remove、SSH、本地路径、shell 元字符、私网直链、双输入、无 token)+ 19v6-04 同号散文;成功抓取要公网,活体字节记在散文里(真实仓库 9 候选、树链接 1 候选、116108 候选表、安装 201/冲突 409)。go test ./internal/runengine 绿。

C3 已落地(2026-10-28):对话内安装(HITL,D20/D24)——skillask.go 新建。skill_install 工具没有写路径:它把来源解析(C2 的 parseSkillInput → resolveSkillSource)后的包留在 .staging/<rand>/,把选择结果拼成 skillInstallProposal{source,staging,skills,candidates,warnings} 写进 run_questions(kind=install) 的 args,发一条 kind=question(name=skill_install)帧,然后按既有的等人机器挂起(每 1.5 s 轮询、租约照续、run 仍是 running)。落盘由答案端点在人工点击后执行:answerQuestion 对 kind=install 先按 denyRunRead 判可见性(不用 denyRunWrite——那条只放 accessOwner,会把「成员提议、管理员点头」挡死),再要求 roleRank>=admin(或 SystemAdmin),viewer 回 403 111203「只有管理员能确认技能安装」;decision 只认 approve/cancel(revise 拒)。CAS 先行(UPDATE … WHERE status='pending',approve 先写空 answer=「正在装」),CAS 成功后才 installApprovedProposal:重新按 staging 路径复核(Abs + 路径包含 + EvalSymlinks 两侧,必须落在 <root>/.staging 之下)→ 重扫候选 → 按提案里的 skills 选 → installSkillCandidates(与上传/来源安装同一落点、同一把 D27 锁)→ 删 staging → 发 skills_changed 事件;最后 SetQuestionAnswer 把结果文本写回行,挂起的工具把它当 tool_result 返回。三种非成功文本各有分工:用户取消了安装。(cancel,顺手删 staging)、安装已过期(暂存目录已被清理),请重新发起安装。(staging 没了——审批期间 G1 清扫或另一实例已处理)、安装结果未知(执行者中途退出),请查看技能列表;没出现就重新发起安装。(resume 读到 approve 但 answer 仍空:续跑不重装,写盘与 SetQuestionAnswer 之间的崩溃窗口只能报未知,绝不猜「装过了」)。waitForAnswer 对 install 行在 answered 但 answer 仍空时继续等(两阶段:CAS 是批准、answer 是结果),避免把「正在装」当成终态交回模型。落点:skillask.go(新)、skillask_test.go(新)、questions.go(questionKindInstall/questionDecisionCancel/角色闸/settleInstallAnswer/SetQuestionAnswer)、waittools.go(questionToolName 映射 + reconcileResumeWaits 的 install 分支)、skilltools.go(newSkillTools(store, mediaRoot) 追加第四个工具)、skillinstall.go(installCandidates 抽成包级 installSkillCandidates + publishSkillEvents)、skillresolve.go(newSkillStaging/resolveSkillSource 改包级函数)、events.go(eventSkillsChanged + Store.PublishEvent)、worker.go、server.go(115101)——doc/46 §7 的事件类型词表因此多一项 skills_changed(同批更新)。活体(隔离引擎 8943、tako_b2、workspace-c1):pending 行带 staging 路径与候选、盘上只有 .staging/<rand>、GET /api/skills 仍空 → viewer approve 回 403 {"code":111203,…}、owner approve 回 200 → 技能目录落位、.staging 清空、列表出现该技能、run 收口、runlog tool_result 逐字 已安装技能:vercel-react-best-practices。 → 下一场 use_skill 回 <skill name="vercel-react-best-practices" source="tenant" bytes="230383">;cancel 场 tool_result 用户取消了安装。 且不多一行;staging 手工清空后 approve 回 200、重复 approve 回 409 {"code":115101,"message":"这个问题已经答过了"}、tool_result 是过期文本;SSE 上 DELETE 与重装各收到一条 skills_changed(id=技能名)。契约进 expected.json 的 declared_not_asserted 用例 27 与 19v6-04 同号散文(工具与 pending 行只有真跑模型才造得出),check-expected.sh 绿。§6.6/§7 的「提议—确认—程序落盘」三段与「谁有权点头」以本节口径为准(D24 第八轮已整条重写)。

C4 已落地(2026-10-28):技能页(web/src/SkillsView.vue)——列表(名字、描述两行折叠+「展开全文」、来源徽标、已禁用/缺依赖徽标、大小与更新时间)、详情抽屉(状态/大小/更新/依赖/路径复制+正文只读,ESC 或点遮罩关闭)、上传(<input type=file> 选 .zip/.tar.gz,可填「只装这些名字」或勾「全装」,走 POST /api/skills/install 的 multipart)、删除(ConfirmDialog,文案写明「正在跑的对话不受影响」)、invalid 区(只列路径与原因,不给修复按钮)、重扫按钮;导航在「助手」之后加「技能」(Page = … | 'skills',sessionStorage 记住落点)。开关按钮先调 PATCH /api/skills/:name、用回包整行就地替换,再让 skills_changed 事件触发一次重拉(mutation.ts 的 MutationEvent 加该类型;两窗口/两副本不会各说一套)。本拍把 PATCH 端点的服务端半也落了(C4 的开关没有它点不动):patchSkill 按租户视界解析名字(查不到 404 116001)、{enabled} 缺字段 400、写/删 skill_disables 一行(SetSkillDisabled,两个方向幂等)、成功发 skills_changed、回 data.skill;路由挂 RequireTenantRole("admin"),viewer 403 111203。E2 剩下的口径(skills:/exclude_skills: 只认 manager、事件 payload 是否带 action、契约用例)已在 E2 收口(payload 不带 action,理由见 §8.2-9;作用域见上文 E1)。落点:web/src/SkillsView.vue(新)、web/src/api.ts(技能类型与五个调用)、web/src/mutation.ts、web/src/App.vue(import/Page/导航/模板分支)、internal/runengine/skills.go(SetSkillDisabled、patchSkill)、server.go(路由)。活体(隔离引擎 8943 + Vite 5174,浏览器登录 owner):技能页列出 vercel-react-best-practices(225.0 KB,更新时间对得上);点名字抽屉读到正文 7251 字符(--- 开头、原文逐字);点「禁用」→ 列表出现「已禁用」、按钮变「启用」、GET /api/skills 的 enabled:false;上传 c4-demo.zip → 提示「已安装:c4-demo」、列表多一行;删除 → 确认框文案正确 → 行消失、提示「已删除技能:c4-demo」;重扫 → 「新增 0、更新 0、移除 0(扫了 1 个根)」;恢复启用后两条命令回归。npm run typecheck 与 npm run build 绿。与台账的差异:详情抽屉里的「检查依赖」按钮未画——GET /api/skills/:name/check 属 D1,画一个当下必 404 的按钮比没有更糟,D1 落端点时同拍补按钮。 C5 已落地(2026-10-28):预览卡与安装确认卡(D24,前端)。技能页的安装只剩一个输入框+「预览」:粘来源、粘整条 npx skills add …、或「选本地包」(multipart)都走同一张预览卡;--list 等价预览,-g/-p/--copy/-y/-a/--agent/--all-agents 由服务端收进 warnings(「已忽略 …(tako 只有一个落点:租户技能根)」)原样列在卡片底部。预览卡列全部候选(名字、描述、字节 · N 个文件、requires),选中的打 ✓ 与「已选」,未选中的也列;底部「将安装 N 个」+「安装」,一个都没选时按钮禁用并提示先勾选(或命令里给 --skill)。契约补充(相对 §6.1 与 C2 的落地):POST /api/skills/preview 的 data 加 selected:[名字]——它和执行时的选择走同一个 selectedNames(单候选且未指定时默认选中),预览与执行不会再各说一套;候选条目加 files(文件数;bytes 本来就是整目录普通文件之和)。安装确认卡(web/src/SkillInstallCard.vue)只吃 AskQuestion.install(即 kind=install 帧/行的 args):来源(github 显示 owner/repo、gitlab 显示 namespace/repo、直链显示 URL、上传显示「本地上传的包」)+ref、下载地址、候选全表(✓/○、名字、字节 · 文件数、已选、描述、依赖)、warnings;「此来源在本会话中未出现」由前端拿当前会话的 user 气泡文本比来源(owner/repo、namespace/repo、URL 小写包含;multipart: 不算),只作提示不做闸——用户把 PDF/邮件正文贴进来也会命中,这是 §6.6 已经接受的代价。按钮只出现在输入区那张卡上,且 role ∈ {owner, admin}:其他角色看到「已提交,等管理员确认」,无按钮;同一张卡出现在历史气泡里时不带按钮(输入区才是操作面,run 还活着时历史卡写「等待确认中——操作在下方输入区」)。取消直接写结果文案;安装由答案端点同步执行,结果写回行 answer(响应 data.answer,刷新后卡底复述「已安装技能:…」)。偏离与已知缺口:① GET /api/runs/:id/questions 列表对 kind=install 行多带 answer(只此一种 kind;answered 的问题/方案行仍不补建,卡会只剩半截);② 已答完且 run 已收口的会话刷新后不重建安装卡(与其他 question/plan 行一致,答案只在 runlog 的工具结果里);③ 详情抽屉的「检查依赖」按钮仍未画(GET /api/skills/:name/check 属 D1,同拍补)。对话页工具卡:use_skill→「使用技能:」、read_skill→「查看技能:」、read_skill_file→「查看技能文件: / 」,call/result 按 toolCallId 配对,失败显示结构化 message,展开是 tool_result 原文(模型实际看到的那段,不回盘重读);这些卡只从帧/工具行渲染,模型正文没有变成控件的通道。验收:浏览器预览→勾选→安装→列表新增;对话 skill_install→卡→「安装」后行 answer="已安装技能:deploy-to-vercel。"、列表新增,「取消」无新增;viewer 账号打开同一条 tenant 可见的 run 只看到「已提交,等管理员确认」(DOM 里没有安装/取消按钮),POST /api/questions/:id/answer 回 403 111203,owner 回答后装成;grep 证明 v-html 只有 renderSafe(markdown → sanitize)一处使用;npm run typecheck && npm run build 绿。

2026-11-01 翻案(范围):C5 的卡片机制保留,但「只给技能三件建卡」这一层撤销——web_search / web_fetch / bash / read_file / 子代理等全部工具都进气泡,摘要、失败、截断口径见 doc/59。 D1 已落地(2026-10-28):requires 声明从「存着」变成「三处同源地用」——①use_skill 的成功标签多两个属性 <skill name="…" source="…" bytes="…" requires="python3 ffmpeg" missing="ffmpeg">,read_skill 逐字节不带(两条路正文相同,只差这两个属性);没声明 requires 时两条路一字不差,声明了但都在时 missing=""。missing 是调用那一刻现查的,不缓存、不阻断正文。②列表/详情的 missing[] 与它同源(同一个 skillDependencies)。③GET /api/skills/:name/check 回 {"dependencies":[{"name","found","path"?}],"checkedOn":"host"}——条目形状由本拍定(§6.1 只写了 dependencies:[…]):path 是本副本解析到的真实路径、只在 found 时出现;安装/更新的 installed[].dependencies 换成同一形状(scripts/acceptance/expected.json 用例 25 同步改)。PATH 收成一条(D39):sandboxProfile 的系统读根抽成 sandboxReadRoots(/usr /bin /sbin /opt /System /Library /dev /private/var + 项目根;F2 起再加租户工具根),subprocessPath 用它过滤宿主 PATH(逐段 EvalSymlinks、保序去重、解析不了的段丢掉),runBash 的 PATH 只从这个函数来(不再透传 bashEnvWhitelist),依赖检查的 lookPathIn 用同一条——围栏外的 ~/.pyenv/shims、~/.local/bin 从「找到但 EPERM」变成「command not found」,检查说找到的路径与 bash 解析到的是同一个。判断只看路径前缀、不试跑(D22)。前端:技能详情抽屉的「依赖」一行加「检查依赖」按钮(data-testid="dep-check"),结果列 ✓/缺 与真实路径,只对本次抽屉有效。落点:sandbox.go(sandboxReadRoots/profile)、新文件 subprocesspath.go/skilldeps.go、bash.go、skilltools.go、skills.go、skillinstall.go、server.go、web/src/{api.ts,SkillsView.vue};单测 subprocesspath_test.go/skilldeps_test.go(去重、EvalSymlinks、序稳定、标签字节);契约字节进 expected.json 用例 28(+ 用例 25 的形状改动)与 19v6-04 同号散文,check-expected.sh 绿;core 活体 71/71。偏差:台账例子里写的 "path":"/usr/bin/python3" 只是示意——本机 python3 解析到 /Library/Frameworks/Python.framework/Versions/3.13/bin/python3.13,机器真源只断 name/found(path 是每台主机的事实,写死会把契约变成验机器);checkedOn 恒 "host"(F2 加了工具根后仍不变:检查在接单副本的宿主上做,工具根也在这块宿主盘上,没有第二个来源可区分)。

2026-10-28 第十六轮(子进程 PATH 只留围栏读得到的目录):用户先问「围栏外的解释器为什么报 EPERM」、再问「你如何判断」,最后裁定「报错当然越准确越好」。落 D39——把 sandboxProfile 的只读根抽成共用的 sandboxReadRoots;继承来的 PATH 逐段 EvalSymlinks 后按它过滤(~/.pyenv/shims、~/miniconda3/bin、~/.local/bin 全部丢掉),工具根 bin 仍前置;requires 的 LookPath(D11 安装期、D38 use_skill)用同一条 PATH,避免「检查说找到、bash 说没装」。连带改 §7(LookPath 表、PATH 条目、「检查通过」的含义)、§10.1-18、§11.2、§9-40;旧口径「不要顺手删宿主 PATH」作废——要删的是围栏读不到的那几段,/usr/bin 之类照旧保留。 本文只定方案;施工台账见 tmp/52-技能/{planning.md,todos.md}(用户已检查通过),代码从 A1 起逐拍落地(当前:A1–A4、B1–B8、C1–C5)。

来源:2026-10-27 与用户逐项讨论(包形态、安装入口与命令解析、目录生成时机、校验、长度、依赖、存储、删除、观测、UI、搜索、Linux 沙箱);参考实现 ref-agent/pi、ref-agent/deepseek-harness(下称 DSH)、ref-agent/kimi-code、ref-agent/WeKnora、ref-agent/Octop、ref-agent/hermes-agent;安装命令形态参考 vercel-labs/skills(npx skills add)。 真源关系:文件围栏与项目删除看 doc/35、doc/37;压缩看 doc/19-v6/19v6-07、19v6-10;子代理规格与折叠看 doc/23、doc/25、doc/26;追问与人工审批看 doc/47;响应信封与业务码看 doc/40;变更事件看 doc/46;任务看板看 doc/41。


0. 一句话

tako 的「技能」是一堆本地 Markdown 包:安装时校验 frontmatter,run 装配时从 skill_rows 读出一份目录,只塞进 manager(根助手,即主代理) 的 system prompt。manager 自己读正文、自己执行:use_skill 取正文并声明「按它办事」(只想看看内容用 read_skill,不建任何任务)、read_skill_file 取资源;正文里的步骤由 manager 自己拆成看板任务(run_tasks,doc/41;拆几刀由它定,与正文的步骤编号不对应,§2.5;程序不代建,D32)——正文是说明书,任务才是要完成的东西,所以任务一建好正文就整块换成 marker、不再每枪重付(D33),压缩时也是任务不折正文折(§2.5、§2.9)。正文要求的重活(读几十份文件、跑批处理)仍派给已有的普通子代理(doc/23/doc/26 那套),而普通子代理本身技能盲(§2.8)。安装入口既认上传包,也认用户从 GitHub 复制来的 npx skills add … 命令串(严格解析、原生抓取,不在引擎主机执行 npx)。不做技能市场、不做技能搜索、不截断目录、不做因果归因。


1. 背景与病灶

tako 现在有项目、会话、子代理、记忆、任务看板,但**「怎么做事」的流程知识没有地方放**。比如「医生登记要收称谓/地区/医院/科室/职称五项」「周报按固定小节写」「某类 PDF 先用 read_pdf_text 再抽表」——这些不是事实(记忆),是操作手册。今天只能塞进 system prompt 或某条记忆里:塞 prompt 每个会话都付 token、改一次要发版;塞记忆是「事实召回」,不是「按需展开的步骤」。

技能要解决的就是这件事:平时只让模型看见一行「有这个技能、什么时候用」,真要用时再把整篇正文递进去。

不做的后果,用六个会真实发生的失败讲:

  1. 全量正文进 prompt。团队攒到 100 个技能,每个正文 3 千字,每次模型调用先付 30 万字上下文;而且改一个技能文件要重启引擎才生效。→ 必须有「目录/正文」两层:目录只放名字与描述,而且只进 manager 的 prompt;正文只在被选中时才进上下文(use_skill 一次),读完由 manager 自己按正文建看板任务(程序不代建,D32);普通子代理两样都看不到。
  2. 截断目录。如果程序把描述切到 250 字,模型看到「当医生提供或更新称谓、地区、医院、科室…」却看不到后半句「或要求停用、删除订阅数据时使用」,该用时就不用;作者也不知道自己哪句被切了。→ 目录不截断;成本靠减少条目来控制,而减少条目的手段只有两把闸——作用域(skills:/exclude_skills:)与禁用。不做技能搜索(2026-10-28 拍,理由见 §3 D28),所以目录体积是个已知天花板:技能数上百时,每个技能一行描述进每一次模型调用,涨到撑不住时没有第三把闸兜底(§9-33 记录了它)。
  3. 装完才发现跑不了,而且没处补。技能正文写「运行 ffmpeg -i raw.mp4 …」,这台机器没有 ffmpeg。模型调 bash 才拿到 command not found,这一轮 token 已经烧了;更难受的是知道了也补不上——工具根在共享 PVC 上,只有运维能往里放文件,普通团队要么等,要么放弃这个技能。→ 两件事分开做:①安装与 check 时检查声明的依赖,缺什么当场告诉用户(D11);②给租户开一个工具上传口——owner/admin 在管理页自己传一个可执行文件进 <tenant>/tools/,不用等运维(D36,§7)。仍不自动装:不跑 pip/apt、不替用户下载二进制。
  4. 技能真身放在项目目录里,项目一删就没了。项目删除会 os.RemoveAll 项目目录,再逐个删会话目录(yk-tako-eino/internal/runengine/product_api.go:315、:324)。技能真身若在项目里,别的项目通过符号链接引用它,删项目后链接全断;而链接指向项目外又会被现有围栏挡住(filetools.go:41、:49 的 rejectSymlinkEscape 只允许落点在 workspace 内)。→ 真身放租户根,项目里只放受控链接;围栏要加「技能只读白名单」。
  5. 覆盖安装时读到半截文件。直接往正在被读的技能目录里解压,某个 run 可能读到新旧混合的 SKILL.md。→ 先写 staging,再整体换目录;旧目录进 trash,延迟清理。
  6. 用户手里的东西是命令,不是 zip。用户在 GitHub README 上看到 npx skills add vercel-labs/agent-skills --skill pdf,复制到 tako 的对话框或安装框里,系统回「请上传 zip」。团队里往往只有管理员能登服务器、能往租户目录里拷文件,普通成员既不会打包也不会解压——技能于是只能靠管理员手工装、手工更新,README 上那句「安装」等于没写。→ 命令串本身作为输入格式被认下来:严格解析成结构化参数,走同一条原生安装路径(抓取 → 校验 → 原子落盘),但不执行 npx,也不执行包里的任何脚本。注意这条只解一半:写盘仍是 owner/admin 的动作(管理页自己点、或在对话里点确认卡),普通成员能做的是提议——把包和程序解析出的事实一起摆到管理员面前,管理员点一下(§6.6)。

还有一条不属于技能本身、但技能会撞上的:Linux 上没有沙箱。bash 与租户 MCP 在无沙箱机器上已经 fail closed(bash.go:86-88、mcp.go:111-113)。技能正文可以读,但「按技能跑脚本」在 Linux 上不能假装能跑。这条单独开 loop,见 §9。


2. 术语与真身

先把词和真实字节对上,后文不再重新解释。

2.1 包形态

两种都认,扫描只看技能根目录的下一层,不递归:

skills/
  doctor-registration/
    SKILL.md            ← 目录形态
    scripts/build.py    ← 资源,按正文里的相对路径读
  weekly-report.md      ← 平铺形态,正文就在这个文件

SKILL.md(或平铺 .md)开头是 YAML frontmatter,后面是正文:

---
name: doctor-registration
description: 当医生提供或更新称谓、地区、医院、科室、职称这5项登记信息,变更科室/地区/职称,或要求停用、删除订阅数据时使用。
requires: [python3]
---

# 医生登记

先读 `references/fields.md`,再按下面的步骤写入……

2.2 目录(<available_skills>)

目录是程序生成的派生视图,不是作者写的文件。一个技能一条,描述全文,路径是PVC 上的绝对路径(各副本挂载点一致)。它只注入 manager(根助手)的 system prompt;普通子代理没有目录(§2.8)。

<available_skills>
  <skill>
    <name>doctor-registration</name>
    <description>当医生提供或更新称谓、地区、医院、科室、职称这5项登记信息,变更科室/地区/职称,或要求停用、删除订阅数据时使用。</description>
    <location>/srv/tako/workspace/tenants/t_01M.../skills/doctor-registration/SKILL.md</location>
  </skill>
</available_skills>

为什么带路径:manager 读正文靠名字不靠路径——read_skill({name}) 只读正文、use_skill({name}) 读正文并声明执行、read_skill_file({name, path}) 读资源(§2.3),路径只用于追溯与 UI 展示。路径由当前副本生成,不跨副本持久化。为什么不做「描述摘要」:摘要要 LLM,安装时多一步不确定的输出;作者写的描述才是选技能的判据。

这个路径是展示与审计用的字符串,不是读取入口(2026-10-28 第二轮复审改写:旧口径「给出去 manager 也读不到」已随 D25 作废,见 §4.4)。D25 之后根 run 的 bash 准读技能根(只读),所以 manager 拿这个路径 cat 是读得到的——「读不到」不再是事实。但读正文的入口仍然只有这三个工具(read_skill({name})、use_skill({name})、read_skill_file({name, path})),因为只有走它们才有折后留痕(D31)、执行声明与看板归属盖戳(D32)与禁用闸(116107),cat 绕开的正是这三条。正文上限(D26)基本绕不过:bash 自己的输出上限是 32KB 且会写明被截断(bash.go:23、:55-60),比正文的 64KB 上限更严;<skill> 包裹与 trim 整块替换(D30)享受不到,但一条 cat 结果最多约 1 万 token,暴露面小于正文。<location> 留着是为了 UI 能显示「技能装在哪、哪份副本」;那条口子已在第十二轮处置:bash 只放行本场 use_skill 过的技能根,cat 隔壁正文够不到(§4.4「复审发现」、§9-34 已拍、D35)。

校验在安装时,渲染只拼字符串:长度上限在写入前判(§3 D2),渲染目录时把描述原样拼进去,不再切字、不再调 LLM。所谓「渲染的时候截断」在本方案里不存在。

2.3 读正文与读资源:三个工具

manager 的工具池里有三个技能工具,都是普通工具(只进 manager 的池;普通子代理不给,见 §2.8):

三个工具的参数都全必填,没有可选字段。 前两个的地址是「技能本身」,第三个是「技能 + 调用方选的文件」——这不是「前两个没有 path」:入口文件确实有路径,但它是行里那条绝对路径,服务端自己用来打开,不放进返回体。理由:返回体里的字段得有人能用;"SKILL.md" 这种相对名离开 name 就指不到任何东西,重新读正文也不靠路径、还是按名字调。记录里区分读法靠 tool 这个名字(read_skill / use_skill / read_skill_file),不靠某个字段空不空。

为什么不合成一个 {name, path?}:那等于用「path 写没写」表示两种读法;而写了的那个值还得让调用方知道包形态(SKILL.md 还是 <name>.md)。拆开后三个 schema 都没有可选字段,判断依据变成「调的是哪个工具」——工具名本来就是显式字段。

为什么「读」和「用」也拆成两个工具、而不是一个 mode 参数(2026-10-28 拍,D32):同一条理由。「读一下」和「按它办事」的区别必须被程序读到,而 assistant 行 ToolCalls 里的工具名是结构事实;换成 mode: "read"|"use" 就得信模型把枚举填对,还多一个「填错也算数」的失败面。两个工具参数完全相同,程序只在 use_skill 上多做一件事:设 run 级状态、给随后建的任务盖技能名。

没有任何一种读法会自动建看板任务(2026-10-28 第七轮拍):用户问「这个技能是干什么的」时 manager 调 read_skill 就够了,看板一行都不该多;看板上只有 manager 真按正文拆出来的任务(D32、§2.5 第 2 条)。旧口径「load_skill 成功就由程序建一条兜底任务」作废——那等于把「读了一下说明书」记成了一件工作,而且下一场会被 D34 当成「上一场没干完的活」再拎给模型。

manager 读正文,也执行正文(2026-10-28 复审翻案,见 §3 D29)。不做分段、不做索引、也不派一个「只把正文读回来、摘要给 manager」的中间层——那只是多一跳,正文仍然不进执行上下文。复杂技能自己写成「索引 + 资源」:正文告诉执行者先读哪个文件,执行者再用 read_skill_file 去读——资源不走普通文件工具拼绝对路径。程序不按「目录里有几个文件」判断有没有索引——一个文件也可能是索引,十个文件也可能全是正文;判断权在作者写的正文里。tako 只负责把入口递到手上。

资源边界就是这个技能的根:绝对路径、含 .. 的路径、EvalSymlinks 后跳出技能根的目标,一律按「读不到」处理(116114,不告诉调用方根外有没有东西);单个文件与正文走同一条判据(≤16,384 token 且 ≤64KB,D26 同一把计数器、同一个判定函数),超了报 116115、不截断(2026-10-28 第十三轮拍,§9-31);path 指向目录时返回不递归的条目列表(方便正文只说「看 references/」的技能;返回形状见 §8.2-2,模式由显式的 type 字段承载)。围栏目标是「读不到别的技能,也读不到宿主机任意文件」——注意这道围栏是工具契约:manager 对本场声明过的技能根另有 bash 只读访问(范围同样是那个根,但不走这条路径规则;§4.4「复审发现」、§9-34 已拍)。

入口文件不在 read_skill_file 的地址空间里:目录形态下 path 解析到 <name>/SKILL.md 时回 116114,message 指向 read_skill/use_skill。否则同一个文件会有三种表示——两个正文工具给出去掉 frontmatter 的正文,这里给原样文件——模型读到 YAML 头会当成正文内容。一个文件只留一条读法。

平铺形态没有资源:<name>.md 自己就是根,工具只认这一个文件;read_skill_file 对它一律回 116114,不会把所在目录当技能根——否则 path:"别的技能.md" 就能读到隔壁技能。

执行者会多次调用:use_skill 一次读正文,之后每读一个资源调一次 read_skill_file;没有「把所有资源一起返回」的模式,避免把不知道多大的目录一次灌进上下文。多次调用之间如果技能恰好被更新,后读的资源来自新版本——没有 pin,这是已知代价(§2.4)。

为什么资源走 read_skill_file 而不是 bash(2026-10-28 复审拍板)

技能正文里常写「先读 references/fields.md」「运行 python3 scripts/build.py」。执行者要碰到这些文件,看起来用 bash cat 最省事,但 bash 与 read_skill_file 是两类东西:

bash read_skill_file
动作 执行任意命令(cat / python / rm / 重定向写盘) 只读一个文件(无执行、无写入、无 shell 语法)
范围 沙箱 profile 现算:项目根可读写 + 系统路径可读(sandbox.go:60-73) 路径先拼到该技能根下,EvalSymlinks 后检查不越界 → 读不到隔壁技能、读不到宿主机任意文件
谁的工具 manager 也有(worker.go:217 把 bash 装进基础池),普通子代理也继承 只进 manager 的池;普通子代理不给(§2.8)
边界性质 运行时算出来的(root 从 ctx 取,sandbox.go:140),不是工具的承诺 工具契约里的代码,不依赖沙箱、不依赖谁在调
返回 一段文本,模型自己解析、自己判断截断 结构化 JSON:{name, path, content, bytes}
超限 无专门上限(模型自己看着办;输出另有 32KB/流 上限且明说截断) 单文件超 16,384 token 或 64KB 报 116115,不截断——截断的正文会让执行者拿着半截步骤干活

一句话:bash 是钥匙(在某个目录里执行命令,权限是目录级的、动作是任意的),read_skill_file 是门(按名字打开某个技能里的某一个文件,动作只有读、结果结构化、门自带锁)。 钥匙发给谁取决于谁的工具池;门自带锁,谁来开都开不出界。

这条差别决定了读资源的入口只有一个:技能要碰的文件只能从 read_skill/use_skill(正文)与 read_skill_file(资源)这几扇门进来——bash 不是读技能的第二条路,它只是执行的路(跑技能自带的脚本)。

2026-10-28 拍(§3 D29/D25):manager 自己读正文、自己执行(不再有内置 skill agent)。于是「manager 读不到技能真身」不再是目标——它本来就该读到正文。真正的边界变成两条:

  1. 普通子代理仍技能盲:它们的池里没有 read_skill/use_skill/read_skill_file,也没有 <available_skills> 目录;它们的 bash 也看不到任何技能根(§4.4 的「委派时去掉」)。
  2. manager 的 bash 只读它执行技能时需要的东西:正文它已经通过 read_skill/use_skill 读过了,所以给它的 bash 放行它自己声明过的那一个技能根不新增任何泄漏——新增的能力只有「能跑这个技能自带的 scripts/*.py」;隔壁技能不放行(粒度见 §9-34)。

代价与补丁见 §4.4(D25/D35):根 run 的 ctx 挂一个 run 内可变的盒子(use_skill 成功时 append、续跑按看板补),装配子代理时整个去掉。

正文的大小约束(不是文件大小,是上下文预算)

read_skill/use_skill 返回的是整篇正文,它会作为一条 tool 行进执行者的活跃上下文。所以上限不能按字节猜,要按引擎真实的上下文机制算:

由此得出两条必须写死的规则:

  1. 一条正文若超过 trim 预算,长 run 一旦触发裁剪,它必然被换成 marker 或缺中段的夹子,而且没有任何信号告诉执行者内容被切过(要重读得靠它自己想到);同时这条超大结果会挤掉其它工具结果的还原额度——trim 从最新往回还原,第一条塞不下的拿夹子,比它更老的全部只剩 marker。窗口多大都救不了:trim 预算是 32768 的硬上限(compact.go:601、:615-616,1M 窗口也是),而一条 256KB 的正文或资源 ≈ 6 万~9 万 token,永远大于它(这也正是第十三轮把资源上限收到与正文同一条判据的理由,§9-31)。这是静默降级,比 provider 回 400 难查得多(两条代价的完整说明见 §2.5 第 4 条)。
  2. 所以正文上限必须小于 trim 预算并给它留一半余量:正文 ≤ 16,384 token(cl100k 计),另加一条字节粗护栏 ≤ 64KB(防 zip bomb / 超长包,纯本地判定)。两条取更严的。真正生效的通常是 token 那条:64KB 的中文正文(UTF-8 每字 3 字节)≈ 2 万字,远超 16,384 token;字节那条只管住「包大得离谱」,管不住上下文。

判据放在读取期(read_skill/use_skill 返回前用 cl100k 量一次)与安装期(同一函数、同一判据,避免「装的时候过了、跑的时候才拒」)。计数器用引擎已有的 runengine.NewCl100kCounter() 构造(词表首次从 openaipublic 拉取并落盘缓存,之后启动即命中),但技能自己持有一份实例,不借用 worker 那个——理由见下段。

「词表拉不到就退化为只看字节」是一条走不到的分支(2026-10-28 删):词表取不到时 cmd/yktako/main.go:181-183 直接 log.Fatalf,进程根本起不来——「压不动」不能在超窗后才发现。真正要处理的是另一个场景:worker 那把计数器只在 -compact-window > 0 时构造(main.go:179-183),关掉压缩时它是 nil。

这个取值 0 保留(2026-10-28 拍):它是调试用的逃生口——想看清模型到底收到什么、不让折叠搅局时用;它不是产品能力(产品里没有「关掉压缩」这个选项),今天也没有任何脚本使用它,只有人手打。所以技能这一侧自己持有一把计数器:启动时用同一个 NewCl100kCounter() 构造(词表有磁盘缓存,成本是一次文件读),安装路径与 read_skill/use_skill 共用它,不看压缩旗标。

不许把 worker 那把可能为 nil 的传下来,也不许判空即跳过字数判据:判空跳过不会崩,但会装进去一个超标正文而返回成功,谁也不知道——这比崩更坏。而「判空即跳过」正是这套代码现有的口径(web_search 描述段 websearch.go:292、worker 长度自测 worker.go:1091),照抄它就等于把 D26 的上限做成摆设。

正文太长时的正确姿势是作者拆包:正文只留「摘要 + 指针」,细节放资源里逐个 read_skill_file 读。程序不强制,但安装期正文超限时在响应里给一条软提示。

2.4 目录什么时候变

本方案没有「pin」这个机制;如果沿用这个词,它只指一件事:目录在这场 run 里只算一次。没有锁、没有句柄、没有失效通知。真实情况只有两件事:

  1. 目录是派生视图:run 装配时从 skill_rows 读一次(system + 本租户,扣掉禁用与 manager 作用域),拼成字符串放进这场执行尝试的 sys。没有目录文件、没有全局缓存、没有锁。
  2. 字符串进 sys 之后,每次模型调用原样复用(notes.go:731:state.Messages[0].Content = sys + "\n\n" + snap 是整段赋值,不是追加)。所以「同一场 run 里目录不变」不是某个机制保证的,是它只被算过一次的自然结果。

于是「目录什么时候更新」只有一个答案:下一次 run 装配时。产品上就是「装完下一次 run 看见,运行中不中途换菜单」。变化能进目录,前提是经过写入口:安装/更新/删除/禁用,或者 rescan。绕过入口直接改卷上的文件,下一次 run 不会知道——这是「装配不扫盘」换来的代价,兜底是管理页的「重扫」(§4.7)。

读正文不经过目录:三个技能工具都在调用那一刻按名字查最新行(名字在租户视界内唯一,一条 SELECT ... WHERE name=? AND valid AND (scope='system' OR tenant_id=?);再扣 skill_disables),拿 path 再打开文件,读到什么返回什么。因此:

运行中发生 本次 run 的目录 调用 read_skill / use_skill / read_skill_file
删技能 还列着 116001
禁用 还列着 116107
新建(含对话里提议、人确认后装上的,§6.6) 不出现 当场可读
改正文 描述还是旧的 正文是新的

表格说的是「这一场 run 内」;下一次装配按表重算:删除的不再列、禁用的过滤掉、新建的出现、走 update 的换新描述。手工拷进来或手工改过的文件,要等 rescan 才会变成表里的行——在那之前不仅目录里没有,read_skill/use_skill 也找不到(116001)。

目录只是发现用的提示,不是「允许调用」的白名单。 能不能读由调用那一刻的磁盘与禁用名单决定;作用域(skills:/exclude_skills:)也不是权限闸——它收窄的是「这只 manager 这一场看得见哪些」,管理员照旧能用 API 改技能表。但 E1 起作用域同时判在解析那一刻(loadByName/readSkillFile/看板恢复):目录里没有的名字,模型照着念也只会拿到 116001,与「表里没有」同字节——省 token 的闸不靠「模型守规矩」成立。这条要写死,否则后来会有人拿目录做鉴权。

2.5 compact(压缩)与 fold 不是一回事

tako 里有三个容易混的名字:compact(compact.go)是整轮压缩;mid-run fold(midfold.go)是 run 中途把工具结果折起来;子代理还有一层进程内折叠(doc/25)。本文说「技能正文在压缩后消失」指的是 compact。

compact 丢掉旧 run 的行、在 seq=0 写一条摘要行,被丢的行标 compacted=true 但原件仍留在表里。摘要模型输入里工具结果会截到 2000 runes(compact.go:188、:783),但这只影响「喂给摘要模型的副本」,不改存储行;裁剪(trim)同理是写时复制——「留档原文(frames / mh 原文行 / 容器 base)永不被 trim 改写」(compact.go:636-637)。所以三层要分清:

层 是什么 技能正文在那儿的状态
存储层(PG run_model_messages) 模型下一次实际看到的输入(§2.6) 模型看到什么就存什么:D33 之前是全文,被折或被主动 marker 之后就是 marker/摘要。逐字原文不在这层——它在盘上(文件是正文),发射时的完整输出在 runlog 的 payload.output
摘要模型输入层(renderFold 的产物) 喂给摘要 LLM 的那段文本 tool 结果截到 2000 runes(compact.go:783)——只影响这份副本
发送候选层(assembled) 这一轮真正发给模型的消息列表 trim 可能把 tool 结果换成 marker/头尾夹(compact.go:638-682),但不改存储

在这个前提下,技能在压缩期有四件事要定:

  1. 正文进的是 manager 的上下文(2026-10-28 翻案,§3 D29),不是子代理的。所以根 run 的 compact 会碰到它。

  2. 正文被折掉不要紧——看板任务不折。执行进度在 run_tasks(PG 表,doc/41),compact 只动 run_model_messages,所以同一场 run 内正文折了、任务还在,manager 看任务继续跑;某条任务要细节时重调一次 read_skill({name})(比重跑一整轮委派轻得多)。没有「钉住/释放」的资源句柄:读完就是读完——D33 之后更彻底,照着正文建出任务后正文就换成 marker,不用等折叠。

    用户说的「第 3 步」是看板的 #3,不是正文的第 3 步(2026-10-28 第四轮定)。页面看板显示的就是 task_no(#%d [%s] %s,tasktools.go:156),用户照着念的必然是它。两边编号不保证对齐:task_no 是 COALESCE(MAX(task_no),0)+1 按创建顺序自增(tasktools.go:87-89),manager 照着正文自己决定拆几刀——可以把三步并成一条、也可以把一步拆成三条,也可能一条都不拆(单步技能)。所以分工是:定位「哪一步」用看板,取「这一步怎么做」用正文(read_skill/use_skill + read_skill_file)。run_tasks 不存正文的 step 号,也不该存。

    跨 run:看板负责「做到哪」,正文负责「怎么干」(2026-10-28 拍,D34)。原口径是「替身只在同一场 run 内成立」,因为 TaskList 按 run_id 查(tasktools.go:135)——用户发下一条消息就是新 run,上一场的看板在新 run 里看不见。D34 把这个读口补上:TaskList 除当前这场,再带一段「上一场」——取本会话里最近一个(排除当前 run)有任务的 run,只列未完成的行,每行带 description。于是「用户说改第 3 步」有了一条确定的路:读上一场 #3 的说明 → 知道这一步要做什么 → 重新规划 → 改动涉及步骤增删换序时走 submit_plan 让用户确认,小改直接做。上一场全完成时只给一行「上一场已全部完成」、不带说明——此时用户要的不是续做而是重做,manager 重调 read_skill 拿正文(那份副本可能已被 compact 折掉,原文永远在盘上)。

    成本边界:这段「上一场」只出现在显式调 TaskList 的输出里;写操作回执(taskReceipt)仍只渲染当前这场,否则每建一条任务就把上一场的说明重付一遍。

    description 因此升级语义:从「可选补充说明」变成「这一步具体做什么;下一场靠它续上」(doc/41 §5.1)。这是 schema 文案 + 提示词约定,靠模型自觉、不是结构闸——模型没写细时,兜底仍是重读正文。

    顺带钉死两个容易混的前提:①看板没有文件形态——RunTask 是 gorm 模型、TableName() 返回 run_tasks(tasktools.go:29-44),四把工具全走 PG,submit_plan 也不落盘;tmp/<方案名>/{planning,todos}.md 是本仓库的开发台账(AGENTS.md),不是产品里的东西。②步骤本身确实在文件里(SKILL.md),但 compact 只动 run_model_messages,既不碰盘上的正文、也不碰 PG 里的任务。所以「写在 file 里的东西 compact 碰不到」这句在产品侧是成立的,只是这里的 file 指 SKILL.md 而不是 todos 台账;唯一会被折的是已经进入消息历史的那一份正文副本(read_skill/use_skill 的 tool 结果),原文永远在盘上。

    执行权也跟着看板走(2026-10-28 第十二轮,D35)。上一段的「换一场 run 也能接着做」还差半截:能读正文 ≠ 能跑它的脚本。bash 的只读盒子是 run 内状态、每场从空开始(§9-34),所以新 run/续跑里 manager 即使从看板读到「第 3 步:跑 python3 scripts/build.py」,那条命令也会撞上 Operation not permitted。D35 补的就是这一步:装配时按看板里已有的 skill_name 把对应技能根补回盒子——判定用「有没有建过任务」,不用「上一场用过」:前者是「确实按它办过事」的确定性证据(与 D33 同一信号),后者只是历史。一眼能背的规则是用户给的那句——已经生成 todos 就继续跑,还没生成就重新加载。

  3. 折掉时要留下「用过它」的记录。manager 的目录在 system prompt 里,compact 不重建 system prompt,所以技能名一直在——但**「这场用过它、正文已折」这条执行状态不在目录里。做法是程序侧钉块**(§2.9),不靠 LLM 写进摘要。

  4. fold 那档也必须认得技能块(2026-10-28 第二轮复审扩:D30 从「trim 认得」扩到「两条路都认得」)。两条路都要说:

    • trim 档:所有老 run 折完、摘要也写了、组装后仍超限时,trim 对**保留区(近期行)**里的工具结果瘦身,第一条塞不下的给「头 1/4 + 尾 3/4 预览夹」。
    • fold 档:当前 run 的单位被折进摘要时,renderFold 把每条 tool 结果截到 2000 runes(compact.go:188、:783)——正文只以头 2000 字进摘要,后面所有步骤从上下文和摘要里一起消失,而摘要里那半段看起来像一段正常摘要。这比 marker 更误导。

    正文以 <skill> 标记进上下文(§2.10),两条路认出它都整块替换成一条指针记录(<skill name=… folded="true" reload="read_skill" tasks="见看板"/>),不走夹子、也不进摘要渲染。

    整块替换真正的价值(2026-10-28 第二轮复审改口径):旧文写的是「夹子切碎了流程的中间步骤,manager 照着残缺正文执行、不报错」——用户指出这条戏不成立:执行时看的是看板任务,不是正文原文(任务替身就是这个意思)。所以整块替换要解决的是另外两件事:①夹子是静默的,模型看不出内容被切过,也就不会想到重调一次 read_skill;换成一条明写「已折叠、正文要重读」的记录,折叠这件事对模型是可见的,重读才会发生。②一条超大结果会挤掉别人的额度:trim 是从最新往回还原、预算 32,768 封顶(compact.go:601),一条塞不下的结果拿到夹子,比它更老的全部只剩 marker——正文越大,这场 run 里其它工具结果(bash 输出、read_file 结果)被抹成 marker 的越多。D26 的上限与 D30 的整块替换都是为了这两件事,不是为了「防止照残缺正文办事」。

2.6 三个存储面

面 是什么 技能相关字段 今天缺什么
帧(Redis runlive) 流式给页面的增量 kind=tool_call/tool_result、name、args、output 没有 toolCallId,没有时间戳;同名并行调用无法配对
runlog(PG runlog_entries) 审计与历史;tool/assistant/usage 行在 EndRun 一次写入(user 行例外:在 AcquireRun 的事务里就写了,store.go:275-278) role=tool_call/tool_result,payload={name,args}/{name,output} payload 没有 tool_call_id;created_at 是 EndRun 时间,不是事件时间
mh(PG run_model_messages) 模型下一次实际看到的输入 tool 行有 tool_call_id 不对外暴露;不能当审计面

这三个面今天各说一套,技能观测要补的第一件事就是 toolCallId 贯穿帧与 runlog(§8)。

2.7 两个成本控制

  1. 作用域(只作用于 manager):根助手的规格(tenant agent 的 md)里写 skills:(只给这些)或 exclude_skills:(从全集减去这些),二选一,沿用 tools:/exclude_tools: 的口径(parseAgentSpec 同写即拒载)。普通子代理没有目录,这两个字段对它们无意义;子代理规格里写了直接拒载——拒在入口:JSON 新建/更新与 md 导入回 400 111002,出厂规格在 seed 时记日志跳过该条(E1;装配期永远见不到这两字段,所以没有「静默忽略」这一态)。显式写 inherit 放行:GET 回读总带这一份,客户端原样 PUT 回来不该被拒。
  2. 禁用:管理端把某个技能从「有效集」里拿掉,manager 的目录与安装列表都不再出现它;文件还在,随时可恢复。它是一条名字级策略,不是沙箱(2026-10-28 澄清,防一种常见误读):禁用就是 skill_disables 表里的一行(租户 id + 名字,§9-1),读它的是两处——run 装配(过滤目录)与 read_skill/use_skill(命中报 116107);沙箱(sandbox.go)只认路径,profile 里能写「放行这个目录」,写不出「除了 pdf 以外」,所以沙箱既不能替代禁用闸、也不会替它兜底。两边的冲突见 §4.4「复审发现」。

不做第三把闸(2026-10-28 拍):曾设计 skill_search(程序侧 BM25,{query} → 排好序的 name + description + source),本期不做(理由见 §3 D28)。所以目录体积只有上面两把闸可控——技能数上百时,每个技能一行描述进每一次模型调用,涨到撑不住时没有第三把闸兜底。这是个已知天花板,不是遗漏;§9-33 记下了它与将来可能的出路。

2.8 角色分工:manager 读正文并执行,子代理盲执行

角色按位置定,不按规格名定:同一个规格(例如 coder)当根助手时是 manager,被委派时就是普通执行单元。

2026-10-28 翻案(§3 D29):原设计是「manager 派活 → 内置 skill agent 读正文并执行 → 只交终稿」。现在改成 manager 自己读正文、自己执行——技能是知识(一份说明书),不是一类特殊任务;知识该留在能用它的上下文里,否则「读」和「用」被切开,中间那一跳只多一道委派、一份 50KB 回传裁剪、和「不能问人/不能委派」两条边界。

正文不是要长期留住的东西(2026-10-28 拍,D33):照着正文建出看板任务之后,正文就换成 marker(不是「步骤搬去了看板」——任务与正文步骤不对应,§2.5)。用户事后追问「第 3 步为什么那么做」时,manager 重调一次 read_skill(一条 tool 行)比重新委派轻得多;真要逐字原文,那是低概率事件,需要时直接 grep 文件即可——不为此把正文钉在上下文里。「读和用不被切开」仍然是翻案的理由,「manager 手里一直有正文」不是。

角色 看目录 能读正文 能读资源 干什么
manager(根助手 / 主代理) 是 是(read_skill / use_skill) 是(read_skill_file) 看目录选技能 → 读正文 → 自己按正文建看板任务(程序不代建,D32) → 自己执行 → 重的部分派给普通子代理
普通子代理(coder、researcher 等) 否 否 否 只做 manager 交代的具体工作;工具池里没有技能工具,也看不见技能根

没有第三个角色:不做技能搜索(「找技能」这个角色整体取消,§3 D28),也没有内置 skill agent——它被 manager 取代了。

四条结构性闸门(靠工具池与装配点,不靠 prompt 自觉):

  1. 目录只拼进 manager 的 system prompt。普通子代理的 instruction 里没有 <available_skills> 这一段。
  2. read_skill / use_skill / read_skill_file / skill_install 只进 manager 的工具池。普通子代理装配时从继承池里剔除这几个名字;tools: 里写了也挑不到。它们是保留名(与 tool_search 同一路数)。skill_install 是提议工具——它只解析并挂起等人确认,写盘在确认端点的处理器里(§6.6),所以「子代理没有这把工具」等于「子代理连提议都不能提」。
  3. 普通子代理的 bash 看不到任何技能根。沙箱 profile 只放行项目根 + 系统路径(sandbox.go:60-73),租户技能根与系统技能根不在其中;装配子代理时还要显式去掉根 run 带来的那条放行(§4.4、D25)——否则子代理继承的是 manager 的 ctx。
  4. 技能根任何角色都没有写权限:文件工具的根是项目目录(scope.go:75-80、:99-105),技能根只以只读方式进 bash 的 profile。

两条边界:

2.9 技能记录块:折掉之后留下「用过它」

compact 折掉老行时,manager 的技能正文随之离开活跃上下文。要留下「这场用过哪些技能」这条执行状态,做法是程序侧钉块——与 fileOps 块平行的一条管线(设计同源:LLM 做取舍、程序做保管;出处见 19v6-07 §5)。

它的职责在 D34 之后降为「提示」(2026-10-28):跨 run 的续做正本是看板(run_tasks 带 skill_name、按会话可读,§2.5 第 2 条)。记录块剩下的价值是让 manager 不必先调一次工具就知道「这场会话用过哪个技能」——看到它才想得起来去看板核对进度、或重读正文。所以块里只需要技能名;不记任务号、不记正文片段。

数据从哪来:被折掉的行里,assistant 行的 tool_calls(read_skill/use_skill 调用 + 参数里的技能名)。不解析正文——正文会被截断、被夹、被折,参数不会(renderToolArgs 每 value 封顶 400 runes,技能名远小于此,一定完整)。

落在哪:摘要末尾,与 fileOps 块并排(summary + fileOpsBlockSep + block,compact.go:472)。不靠 LLM 写进摘要——摘要模型是 LLM,它写的是「这轮干了什么」的自然语言,技能名这种细节可能被省掉。程序块的价值是三件事:确定性、跨次继承(旧摘要里的块被认回来继承,同 inheritFileOps)、三档收口(超限砍条目、再超就 fold 失败,同 fileOps)。

形状(照 fileOps 块的格式:稳定标记 + 逐行条目 + 来源注记):

<!-- tako:skill-ops v1 -->
用过的技能:
- doctor-registration(use_skill,r_01M…)
<!-- /tako:skill-ops -->

块里不写看板任务号(2026-10-28 拍,取「选项乙」):把「技能 → 任务号范围」的映射塞进 compact,会让折叠热路径多一次 DB 查询;而这件事本来就该由看板回答——run_tasks 加 skill_name 列、TaskList 返回带 skillName 字段,manager 一调就知道哪几条任务属于哪个技能。compact 不碰 DB。

2.10 正文在上下文里的形态:<skill> 标记

read_skill/use_skill 成功时返回 XML 原文(失败才走 JSON 信封,D15 只规定失败是结构化 JSON):

<skill name="doctor-registration" source="tenant" bytes="4213" requires="python3" missing="">
# 医生登记

先读 references/fields.md,再按下面的步骤写入……
</skill>

requires/missing 只在 use_skill 上出现(2026-10-28 第十五轮,D38):两个属性都是 LookPath 现算的运行时事实,不缓存;技能没声明 requires 就两个都不写,声明了但都在就写 missing=""。read_skill 不带这两个属性(纯读正文、零副作用)。

四条理由:

  1. 正文要原样进消息历史——JSON 会把换行转义成 \n 字面量,折叠器不好定位。
  2. 属性里带 name:摘要模型看到的工具结果截到 2000 runes(compact.go:783),但 name 在最前面 → 截断了也还记得用的是哪个技能。
  3. 正文里的 < & 要转义(代码片段、HTML 会撞结构);目录那边已有转义做法(§2.2),正文这边新增。转义顺带买到一件事:正文里不可能出现真的 </skill>,所以按内容标记认块是安全的(D30,fold 与 trim 两条路都靠它)。代价(2026-10-28 用户拍:要的就是「看起来一致」):正文里的代码片段在上下文里是 &lt;div&gt; 这种形态,模型往产物里抄时要自己还原;验收因此比的是反转义后逐字一致(§11.2),不是原始字节。
  4. 给「整块替换」一个边界:一旦要它走(D33 的每枪重写、或者 fold/trim 兜底),整块换成 <skill name="doctor-registration" folded="true" reload="read_skill" tasks="见看板"/>,而不是「头 1/4 + 尾 3/4 夹子」、也不是截成 2000 runes 塞进摘要——夹子是静默的(模型看不出被切过,不会想到重读),而且一条超大结果会挤掉这场 run 里其它工具结果的还原额度(§2.5 第 4 条)。

顺带给模型一个作用域提示:<skill> 块 =「这段是外部提供的说明书,照它做」,与 §9-13「技能正文视为管理员授权的指令」是一条线。


3. 拍板表

编号 决策 取值 为什么 / 代价
D1 包形态 目录 name/SKILL.md 或平铺 name.md;只扫一层 与 Agent Skills 事实标准一致;资源留在技能目录里
D2 安装校验 name、description 必填;description ≤ 1024 字符(rune);超长/缺失直接拒装 Pi 的硬上限是 1024(skills.ts 的 MAX_DESCRIPTION_LENGTH);DSH 的 500 只是目录展示截断,Kimi 的 250/240 也只是列表截断——按最大的 1024 做安装校验,目录展示全文
D3 目录展示 描述不截断;只做 XML 转义与空白折叠 截断会静默丢信息:模型不知道被切了什么,作者也不知道
D4 目录生成 run 装配时从 skill_rows 读一次、拼成目录(派生视图,不缓存字符串);运行中安装/禁用/删除不改变本次 run 的目录;resume 重算;读正文按调用时刻查行、再打开文件,不看目录快照 目录查询是一条 SELECT,装配不扫盘;盘上的变化经写入口或 rescan 进表(§4.7);目录不是调用白名单
D5 读法 整篇读 SKILL.md 正文,由 manager 读并执行(2026-10-28 翻案,见 D19);不做索引解析、不批量读、不派「只读回正文、摘要给 manager」的中间层 正文必须进执行者的上下文;只读给 manager 听的那一跳既费 token 又不产生执行
D6 存储 建 skill_rows 存目录(名字/描述/路径/依赖/可用性);建 skill_disables 存租户级禁用(tenant_id + name 做主键);正文与资源仍是卷上的文件 系统技能与团队技能都在共享 PVC 上,全集群只有一份,不存在镜像版本错位;目录与禁用都进表后 run 装配不扫盘,只两条 SELECT;代价是每处写盘都要配一次写行,外加一个 rescan 兜底(§4.7)。禁用为什么不挂在 skill_rows 上、也不塞进租户 config:见 §4.7 表后的两段
D7 同名 不允许跨层同名;名字在「一个租户的视界」内唯一(2026-10-28 第十三轮按租户收窄——第二轮写的「全局唯一」在多租户下是 bug):视界 = 系统层 + 本租户的行(含本租户的项目层行)。安装(含对话里 skill_install 的解析期——不等人点完才报冲突)、rescan 撞到视界内已有的同名技能 → 安装回 116106、rescan 写 valid=false + reason。别的租户装同名不冲突。想改出厂技能的做法是换个名字装(如 pdf-v2),再把系统那个 pdf 禁用 三层覆盖会让 GET/PATCH/DELETE /api/skills/:name 指不到确定的一行(现有路由没有 :name 先例),还会让「删掉上层」静默暴露下层——管理员禁用并删掉团队层的 pdf,系统层的 pdf 就冒出来生效,而他的本意是「这个技能别用」。名字在视界内唯一后这两件事都不存在,闸落在数据库唯一索引上((tenant_id, name) WHERE valid,§4.3、§4.7);只有「系统行 vs 某租户行」这一对跨桶索引表达不了,由写入口与 rescan 在 D27 的锁下显式比(§4.7「为什么按租户收窄」)
D8 真身位置 系统 <workspace>/system-skills/(PVC,部署时从仓库 skills/ 同步);团队 <workspace>/tenants/<tid>/skills/;项目 <项目>/.tako/skills/(v1 可后置) 系统技能放共享卷才全集群一份;项目删除会 RemoveAll 项目目录,真身放租户根才活得比项目久
D9 删除语义 删项目 → 项目技能随目录消失;删会话 → 不影响技能;团队技能随租户 与 doc/37 的级联一致;不额外造「技能引用计数」
D10 原子更新 staging 写满 → 旧目录移 trash → 新目录 rename 到位;trash 延迟清理;不原地覆盖 避免读到新旧混合;NFS 上只依赖 rename 原子性,不用 flock
D11 依赖 可选 requires: [可执行名];安装时 LookPath(按 D39 过滤后的 PATH);缺失写进响应与 UI;不自动安装(缺的由人上传或运维同步,见 D36) 声明与检查都是数据,安装期不需要在引擎主机执行任何东西
D12 成本控制 作用域(只作用于 manager)+ 禁用都做;BM25 搜索不做(2026-10-28 拍,见 D28) 目录全文展示的代价必须靠「减少条目」而不是「截字」来控;两把闸之外没有第三把 → 目录体积是已知天花板,涨到撑不住时无解(§2.7、§9-33)
D13 生命周期 一次性整篇读,没有「钉住/释放」;fold/compact 后需要就重读 正文不是资源句柄;重读只多一条 tool 行
D14 观测 帧与 runlog 补 toolCallId;技能加载事件从 runlog 的 name="read_skill" / name="use_skill" / name="read_skill_file" 行派生(agent="",即 manager 侧;2026-10-28 翻案后不再有 agent="skill" 的行);不做因果归因 并行工具调用必须能配对;「后面的工具是哪个技能导致的」程序判断不了
D15 失败面 技能工具失败 = 正常 tool result,结构化 JSON {code,message,data};管理 API 用 HTTP 信封;SSE 帧不进信封 与 doc/40 一致;模型能读到失败原因并改道
D16 Linux 沙箱 2026-11-03 已落地:Debian 12 用 bwrap(与 seatbelt 同口径,出站开、入站关);probe 失败仍 fail closed,裸 bash 不放开 不假装已隔离(bash.go/mcp.go 同口径);活体脚本 scripts/acceptance/linux_sandbox.sh
D17 存储假设 workspace 挂共享 PVC(RWX,NFS 一类语义);没有 MinIO;flock/rename 语义后续实测 用户 2026-10-27 明确的前提:系统技能在 PVC 上
D18 管理面 必须有管理 API + UI(列表/安装/更新/删除/禁用/依赖状态) 不能只靠手工往目录里拷文件;团队要能看见装了什么
D19 角色模型 manager(根助手 / 主代理)自己读正文、自己执行;普通子代理不读也不执行技能;取消内置 skill agent(2026-10-28 翻案,§2.8) 技能是知识不是一类特殊任务:知识留在能用它的上下文里,读和用不被切开,也省掉一次委派与回传裁剪。追问细节靠重调 read_skill,不靠钉住正文(D33 之后正文在看板任务出现时即换成 marker)。代价:正文进主上下文(用 D26 的上限、D33 的主动 marker 兜住;任务由 manager 自己建,D32 不代建)、重活要 manager 自己派给普通子代理(§2.8 边界二)
D20 增加技能的入口 两个:管理 API(上传包、来源串或 npx skills add 命令串,人工触发,同一请求里就写盘)、对话里 manager 的 skill_install(只提议不写盘:解析 → 落 run_questions(kind=install) 行 → 挂起等人确认 → 由确认端点在人工点击后执行安装,§6.6)。删除/禁用/覆盖更新只有管理 API,不给模型工具;skill_install 只建新名字,撞名在解析期就回 116106 新建是加法,管理页随时可删;删除会毁团队资产,提示注入不该能触发。模型能判断「用户想装」,但不能握写盘的手——它整天读 PDF/网页/技能正文,分不清「我要装」是自己想的还是刚读到的;写盘只由人的一次点击触发(D24)。工具复用安装的校验与 staging→rename,不另写一套写盘
D21 安装来源 三种输入归一:multipart 上传包;来源串(owner/repo、owner/repo@skill、owner/repo#ref、GitHub/GitLab URL、.zip/.tar.gz URL);npx skills add … 命令串(原样粘贴)。三者走同一个 resolver、同一套校验与原子安装 用户手里拿到的就是命令串;逼他先翻译成 zip 是白加的转录成本,也是普通成员装不上技能的直接原因
D22 命令怎么处理 当字符串解析,不当命令执行:不启 npx/npm 子进程、不跑包内 postinstall/scripts/;只认 add 子命令;带 shell 元字符、未知子命令、SSH 来源、私网地址、服务端本地路径一律拒 解析只是数据,执行才是权限面。一开子进程,postinstall 就能在引擎主机跑任意代码,还绕过文件围栏与沙箱
D23 仓库里的技能怎么取 来源是仓库时,只装 resolver 找到的技能目录(含 SKILL.md 的目录),不把整仓塞进技能根;仓里多于一个且没指定 --skill/--all 时回 116108 + 候选清单 整仓入根会让扫描把 README、CI、测试当资源,同名覆盖也不可预测
D24 对话内安装 = HITL(原「逐字校验」作废,2026-10-28 第八轮) 模型只能提议。skill_install({command?|source?, skills?, all?, preview?}) 四拍与 ask_user 同构:① resolver 抓取+校验,只落 .staging/<rand>/,不碰技能根、不写 skill_rows → ② 落 run_questions 一行(kind=install;question 一行人话,args 存 resolver 的结构化输出:来源、候选全表、选中集、staging、warnings(「本会话出现过」由前端比 user 气泡,只作提示))并发帧 → ③ 前端只按 args 里的结构化字段渲染确认卡(未选中的候选也要列出来),人点「安装」/「取消」→ 打到现有答案端点 → ④ kind=install 分支由程序执行安装(D27 锁 → rename → 写行 → skills_changed),结果作为 tool_result 回同一轮。点「安装」要 owner/admin;取消是正常结果(「用户取消了安装」),不是错误码 原逐字校验两头都漏:用户把 PDF/邮件正文贴进对话框时那串字就在他的 user 消息里(放行),模型给的是解析后的来源而用户原话是命令串(误拒)。「谁授权」只有一个真答案——人的一次点击,且这次点击必须看见程序解析出来的事实(repo、ref、文件数、字节、依赖、选中/未选中),不是模型写的文案;确认按钮以帧为准,模型正文里的假按钮不算。写盘不能是模型第二次调工具:那模型仍握着写权限,只是先说了句话。边界:HITL 解决「谁授权」,不解决「包是否安全」——恶意包被管理员点了照样装进去,靠详情页可见 + 禁用/删除兜(§12 不做扫描)
D25 bash 沙箱白名单 按角色注入,但方向反过来(2026-10-28 翻案,§4.4):根 run 的 ctx 里挂一个 run 内可变的只读盒子——里面是本场 run use_skill 成功过的技能根,不是整个技能根(粒度 2026-10-28 第十二轮拍定,§9-34);装配普通子代理时显式去掉。工具根不在这个盒子里(第十四轮):它按租户常开、所有角色都能用(D36) manager 本来就能读正文(read_skill/use_skill),所以给它 bash 放行它自己声明执行的技能不新增内容泄漏,补上的是「能跑技能自带 scripts/*.py」这条执行能力;而隔壁技能必须看不见——放行整个根会让 cat 绕开留痕(D31)/任务归属(D32)/禁用闸(116107)三条(§4.4「复审发现」);普通子代理继承的是 manager 的 ctx,去掉是必需的一步。工具根为什么不一起收窄:二进制里没有指令,cat 它得不到任何技能正文,上面三条理由一条都不成立;把它按技能收窄,还会让普通子代理连 ffmpeg 都跑不了——重活派不下去(§7「缺一个工具怎么补」)
D26 正文上限 正文 ≤ 16,384 token(cl100k)且 ≤ 64KB 字节,取更严的(中文场景生效的通常是 token 那条);安装期与读取期(read_skill/use_skill)用同一判据同一函数;超了报 116116。资源文件(read_skill_file)走同一条判据,超了报 116115(第十三轮,§9-31) 正文是整篇进上下文的;trim 预算硬上限 32,768 token(compact.go:601、:610-619),超它的正文在长 run 裁剪时被换成 marker 或「头 1/4 + 尾 3/4 夹」,折叠对模型是静默的,而且会挤掉其它工具结果的还原额度(§2.3、§2.5 第 4 条)
D27 写操作并发 库级分布式锁,按「改哪块地方」分两级(2026-10-28 第十一轮改;旧口径「整个技能面一把锁、包住全流程」作废,用户授权由我裁定):①普通写(安装/更新/删除/租户 rescan)= 全局共享锁 + 本租户独占锁(pg_advisory_lock_shared / pg_advisory_lock,绑在同一条连接上);②只有系统管理员的全量 rescan 取全局独占锁。锁内只做「rename 搬目录 + 写行」(rescan 另含本地扫盘);锁外做网络抓取、解压、校验、上传落 .staging/<rand>/。锁放数据库、不放进程内;写操作只有一个 API 入口 按租户分是因为两个租户装技能不碰同一个目录、同一批行——全局排队只是白等,而且一个慢仓库会把所有租户堵死。全局独占只留给全量重扫:租户级重扫已按归属过滤(§4.7),只有它删得到别租户的行。共享/独占两级而不是两把互不相干的锁:租户写取全局 shared、全量重扫取全局 exclusive,才能既让租户间并行、又让全量重扫等到所有人做完。锁外做 IO:staging 是随机目录,写它不冲突;包进锁里等于下载慢就全站排队。代价:锁键一把变两把、必须拿住同一条连接(连接池换连接会漏锁),见 §10.1-22
D28 技能搜索 不做 skill_search(2026-10-28 拍) 目录总是全文注入时,搜索没有可省的地方——manager 看得见全部,搜不出新东西;真要省 token 得改成「不注入目录、只给工具」,那是另一种设计与另一种风险。代价:目录体积只有作用域 + 禁用两把闸可控,是已知天花板(§2.7)
D29 执行模型 manager 自己读正文、自己执行;并照着正文建看板任务(run_tasks,拆几刀由它定,不与正文步骤编号对应);正文要求的重活按任务派给普通子代理;取消内置 skill agent(2026-10-28 翻案,§2.8) 技能是知识不是任务:知识留主上下文,读与用不被切开;省掉一次委派、50KB 回传裁剪、以及「不能问人/不能委派」两条边界。追问细节重调 read_skill 即可——正文不承担任何长期承诺(D33 会在看板任务出现后把它换成 marker)。代价:正文进主上下文(用 D26 上限 + D33 主动 marker 兜住;任务由 manager 自己建,D32)
D30 正文形态与去留 正文以 <skill name=… source=… bytes=…>…</skill> 进消息历史(use_skill 的标签另带 requires/missing,D38)(成功走 XML 原文、失败走 JSON 信封);正文里的 < & 转义;两条路都认这个块、整块替换成指向看板的记录——① 每枪重写:看板出现该技能的任务后的第一枪就换(D33);② fold/trim:被折或被裁时换,不走「头 1/4 + 尾 3/4 夹」、也不把半个正文送进摘要 夹子是静默的(模型看不出被切过、不会想到重读),而且一条超大结果会挤掉这场 run 里其它工具结果的还原额度(§2.5 第 4 条)。fold 那路更糟:被折的正文只以头 2000 runes 送进摘要(compact.go:188、:783),摘要里出现半段正文比一条明写「已折叠」的 marker 更误导。整篇转义顺带买到一件事——正文里不可能出现真的 </skill>,所以按内容标记认块是安全的,不会被「正文里写了 <skill> 示例」的技能误触发(落点见 §10.1)。代价:替换发生在 state.Messages 上,AfterAgent 存进 mh 的就是替换后的形态(§2.5 存储层一行)——所以对话卡片展示的是模型看到的,不是回盘原文(§6.4)
D31 折后留痕 程序侧钉块:从被折行的 assistant 行 tool_calls 里提取 read_skill/use_skill 调用与技能名(不解析正文),拼成技能块钉在摘要末尾(与 fileOps 块并排,同继承机制、同三档收口);块里不写看板任务号 摘要模型是 LLM,技能名这种细节可能不写进摘要;程序块给的是确定性。任务号交给看板回答(run_tasks.skill_name + TaskList 返回带 skillName)→ compact 不碰 DB(选项乙,§2.9)
D32 读与用分开 两个正文工具:read_skill({name}) 只读正文、零副作用;use_skill({name}) 正文相同,并声明「本 run 按它办事」——把该技能记进 run 内的执行态。程序不自动建任何看板任务(2026-10-28 第七轮翻案,旧口径「load_skill 成功就建一条兜底任务」作废);看板上只有 manager 自己调 TaskCreate 建的行;run_tasks 加 skill_name 列,程序在 TaskCreate 时按「本 run 最近一次 use_skill」盖戳;任务按 run 写入(行带自己的 run_id),但按会话可读上一场(D34) 「读一下说明书」不是一件工作:自动建任务会让「用户问这个技能是干什么的」在看板上留一条永远没人收尾的行,下一场还被 D34 当成未完成的活拎给模型(2026-10-28 第七轮用户指出的鬼任务)。差别的代码侧可见:工具名就在 assistant 行 ToolCalls 里,程序不用猜意图。任务住在 PG 表里、compact 不动它 → 同一场 run 内正文可折、任务不折(§2.5 第 2 条);「用了哪个技能」的痕迹交给 runlog 的 tool 行(D14)与 D31 的钉块,不需要一条假任务来承载
D33 正文什么时候走 每枪重写(BeforeModelRewriteState,与滤思考同一处):某条 read_skill/use_skill 的 tool 结果之后(行序更晚的 assistant 行)出现了 TaskCreate 调用 → 下一枪把该技能的 <skill> 块换成 <skill name=… folded="true" reload="read_skill" tasks="见看板"/>。判据只看 assistant 行 ToolCalls 里的工具名(compact.go:765) 常态成本不能靠罕见的 trim 档来收:正文读进来就是一条 tool 行,之后每一枪原样重发,一份 16k token 正文 / 一份满额资源(6–9 万 token)会一直重付到折叠为止。「已经按正文建过任务」是唯一确定性的「用完了」信号(不是「步骤都搬到看板上了」——任务与正文步骤不保证一一对应),且不需要新表新列。压缩关闭(-compact-window=0)时同样执行——它不是压缩档。代价三条:① mh 存的是 marker 不是原文(§2.5 存储层);② 只读过、没建任务的技能不触发,留到 fold 档才换(D30 ②);③ 判据不区分任务是用哪个技能建的(skill_name 只记在任务行上,不在 TaskCreate 的参数里),所以一场 run 里先后读了两个技能、只给第一个建任务时,第二个的正文也会一起被标记——需要细节时重读一次即可(marker 不阻止重读);同理,一条根本与正文无关的 TaskCreate 也会触发换 marker,代价同样只是多一次重读
D34 跨 run 的续做 看板是会话内跨 run 的续做正本:TaskList 除当前 run 的看板,再带一段「上一场」——本会话里最近一个(排除当前 run)有任务的 run,只列未完成行、每行带 description;全完成时只给一行提示。写操作回执(taskReceipt)不带这一段。description 语义同步升级为「这一步具体做什么;下一场靠它续上」 用户续做时说的是页面上的「第 3 步」(= task_no),而正文只回答「怎么做」。没有这条读口,新 run 里上一场的计划完全看不见(ListTasks WHERE run_id = ?),只能靠摘要里的模糊记叙。三条代价:① description 要靠模型写细,是自觉不是闸(模型没写细时兜底是重读正文);② 多一条按 (tenant_id, session_id) 的查询(索引现成,tasktools.go:32-35);③ 只进显式 TaskList、不进回执——否则每写一条任务就把上一场的说明重付一遍
D35 执行权的恢复条件(2026-10-28 第十二轮,用户裁定) 盒子每场 run 从空开始,恢复看板不看历史:run 装配时(盒子建好之后、第一枪之前)查一次「这场要接着办的事里,哪些技能已经建过任务」——续跑查当前 run_id,新 run 查 D34 选出的那个「上一场」run(SELECT DISTINCT skill_name FROM run_tasks WHERE tenant_id=? AND session_id=? AND run_id=? AND skill_name <> '' AND status <> 'deleted',走现成索引 run_tasks_scope = (tenant_id, session_id),tasktools.go:32-35);命中哪个技能,就把它的根直接补进盒子(工具根不用补——它按租户常开,D36),manager 不必再调 use_skill——「已经生成 todos 就继续跑」。没命中就不补,要执行就得调 use_skill 重新加载正文并声明执行——「还没 todos 就重新加载」。补之前逐项重判当前状态:行仍 valid、skill_disables 里没有它、技能根仍在盘上;任一不成立就跳过这一条(不报错、不中止 run)。恢复只补执行权,不补正文(要细节仍 read_skill,D34) 盒子是 run 内状态,装配一次就从零开始,不补则「续跑/隔一场接着做」当场断在执行这一步——看板上明明有第 3 步,python3 scripts/x.py 却 Operation not permitted。判据只能用看板,不能用「上一场用过」:TaskCreate 盖过 skill_name 正是「确实按它办过事」的确定性证据(与 D33 同一个信号),而「上一场用过」是历史结论,不是本 run 的声明。没建过任务就恢复,等于把执行权发给一场手里还没有正文的 run——它只会瞎跑。三条边界:① 恢复在装配时做一次,run 中途新建其它技能的任务不会回头补盒子(本 run 里用了就走过 use_skill,盒子那时已经长了);② 盒子只增不减,run 中途被禁用不缩(下一次装配重新判);③ 跨 run 恢复挑的那个 run 就是 D34 的「上一场」,两处读同一块看板——不会出现「TaskList 显示第 3 步、执行权却没补」的错位
D36 缺依赖的补装通道(2026-10-28 第十四轮,用户指示「在方案里面解决」) 租户工具根开一个上传写面:POST /api/tools(multipart name + file,owner/admin)把一个可执行文件落到 <tenant>/tools/<name>/bin/<name>(0755);GET /api/tools 扫盘列出、DELETE /api/tools/:name 移入 .trash。校验只做文件级:名字 ^[a-z0-9][a-z0-9-]{0,63}$、保留名(bash/sh/env)拒、非空、单文件 ≤128MB、占租户存储额度(ReserveStorage);不执行、不探测格式与架构(与 D22 同一条线:装的时候没有围栏,跑的是引擎进程的权限)。原子性复用 D10(staging → .trash → rename,覆盖=更新),锁复用 D27 的「全局共享 + 本租户独占」;不进表、不 rescan(盘就是真源)。同时把工具根从技能盒子里拿出来:<tenant>/tools 按租户常开(各 <name>/bin 前置进 PATH、整棵只读进 profile),**所有角色(含普通子代理)**都能用;requires 从此只服务安装期检查与 UI 提示 三条:①§1-3 原本只做了一半——检查告诉你缺什么,却没有任何补的办法,普通团队只能等运维;②二进制里没有指令,cat 它得不到技能正文,所以 D25 收窄的三条理由(D31 留痕/D32 归属/116107 禁用)一条都不成立,常开反而少掉「按技能解析工具根」这个分支,也让派给子代理的重活(批量跑 ffmpeg)跑得动;③装的时候不能验证它能不能跑,所以只做文件级校验——command not found/Exec format error/Bad CPU type 由 run 里的 bash 原样报出(与 D11「不假装成功」同口径)。边界:这是租户往自己机器上放的东西,不是市场;恶意二进制与技能脚本同一档(沙箱内、能改本项目、无网络)。F1 已落 2026-10-28:三个端点、五步落盘、额度与角色闸;F2 已落 2026-10-28:工具根常开——整棵只读进 profile、每个 <name>/bin 前置进 PATH(与宿主 PATH 共用同一条 sandboxReadRoots 过滤),普通子代理同样可用
D37 网络出口(2026-10-28 第十五轮,用户指示「记得补上 agent 可以访问网络」,原文写作 magent) bash 围栏放开出站网络:sandboxProfile 加 (allow network-outbound),不开入站(network-inbound);实测若 DNS 仍被拒,再补 (allow system-socket)。这条 profile 同时是 manager bash、子代理 bash、技能脚本、租户 MCP(sandboxWrap)的围栏,所以四者一起生效;不按角色分——技能脚本跑的就是 agent 的 bash,同一个围栏没法只给 agent 不给脚本 技能正文里的 curl/下载数据集/调外部 API 是常见步骤,断网等于把这些技能判死;顺带补上租户 MCP 也连不上网这个既有缺口。代价:围栏不再阻止「下载并执行」——二进制可以被 curl 到项目根再跑(项目根本来就可读写);挡得住的仍是系统目录与 <tenant>/tools(只读,.staging/.trash 也在其内),所以下载物进不了工具根、不会变成全租户可用的工具;「自动装依赖」仍不做(D11)。Linux 无沙箱时 bash 仍 fail closed,这条只在有沙箱的机器上成立
D38 技能要的工具没装,几时知道(2026-10-28 第十五轮,用户问「skill 如果执行到某个工具无法执行因为根本没安装,怎么办」) use_skill 成功结果里现查一次 requires:<skill name=… source=… bytes=… requires="python3 ffmpeg" missing="ffmpeg">…</skill>(没声明 requires 就不写这两个属性);missing 用 LookPath 现算、不缓存、不阻断正文返回。模型看到 missing,在执行依赖它的命令前停下、说明「缺 X,请管理员在工具区上传(D36)或运维同步」;不自行安装、不反复重试;真跑到 command not found 就照原样报给用户(D11 不假装成功)。read_skill 不加这两个属性(保持零副作用、纯正文) 缺依赖今天要等 bash 跑那一枪才暴露,token 已经烧了;LookPath 是纯读、成本可忽略,正好放在「声明执行」这一刻。D39 之后 LookPath 与 bash 用同一条过滤后的 PATH,所以不会出现「说找到、跑起来 not found」的错位;仍然判不出的只剩「读得到但跑不起来」(架构不符、缺动态库、解释器自己的 stdlib 在 HOME 下)——那类错误只能由 bash 原样给出,正文要写清(§7)。不阻断是因为正文可能只用不需要它的那部分(§9-13 同一条线)
D39 子进程 PATH 只留围栏读得到的目录(2026-10-28 第十六轮,用户裁定「报错当然越准确越好」) 按围栏的只读根过滤 PATH:把 sandboxProfile 里写死的那组根抽成共用的 sandboxReadRoots(/usr /bin /sbin /opt /System /Library /dev /private/var + 项目根 + <tenant>/tools),profile 与 PATH 都从它读;继承来的每一段先 EvalSymlinks(/bin → /usr/bin),落在某个根之下才保留,否则丢弃;保序、去重,再在最前面拼 <tenant>/tools/*/bin(D36)。同一份过滤后的 PATH 也用于 requires 的 LookPath(D11 安装期、D38 的 use_skill),否则「说找到」与「跑起来 not found」会打架 现在子进程原样继承引擎的 PATH:~/.pyenv/shims/python3 会被 LookPath 找到、执行时被围栏拒 → 报 Operation not permitted,模型会当成路径或权限写错、反复换路径;丢掉围栏外目录后同一条命令报 command not found,模型的正确反应是「机器没装,请管理员上传」(D36)。判断只看路径前缀、不试跑(D22 同一条线)。代价:装在 HOME 的工具从「找到但跑不了」变成「找不到」——它本来也跑不起来;绝对路径点名的仍会 EPERM(~/.pyenv/.../python3),这类留给 bash 原样报

4. 目录与生命周期

4.1 今天的目录

<workspace>/                         # -workspace,默认 yk-tako-eino/workspace
  tenants/<tid>/
    workspaces/<wid>/                # 项目真文件(scope.go:89)
      .media/                        # 入口媒体(doc/32)
      .tako/                         # 搜索落盘、子代理 wire 等内部目录
    sessions/<sid>/                  # 会话作业根(scope.go:123)
      .tako/subagents/               # 子代理持久档案(doc/39)

.media 与 .tako 在文件列表里被隐藏(product_api.go:159 的 workspaceInternalDirs),所以 .tako/skills/ 不会出现在项目文件页。

4.2 技能放哪

<workspace>/system-skills/                        # 系统技能(PVC;部署时从仓库 skills/ 同步;应用只读)
<workspace>/tenants/<tid>/skills/                 # 团队技能(管理 API 安装;可写)
<workspace>/tenants/<tid>/workspaces/<wid>/.tako/skills/   # 项目技能(可选;v1 可后置)

<workspace>/tenants/<tid>/tools/                  # 工具根(§7、D36;不是技能,不进 skill_rows;运维同步或租户上传)

4.3 名字在租户视界内唯一(不做三层覆盖)

2026-10-28 第二轮复审改:旧口径是「合并顺序 system → tenant → project,同名后者覆盖前者」,改成不做跨层同名。第十三轮再把「唯一」的范围从全表收到「一个租户的视界」:视界 = 系统层 + 本租户的行(含本租户的项目层行);别的租户的行既看不见、也不参与判断。安装、对话里 skill_install 的解析期、rescan 撞到视界内已有的同名技能,一律按冲突处理:安装回 116106(解析期就能判出来,不用等人点确认),rescan 写 valid=false + reason(写清与哪一层撞名),不静默挑一个。每个视界里每个名字只有一条,source 字段告诉 UI 它来自哪层。

4.4 符号链接与围栏

项目里放技能链接时,链接目标必须落在技能只读白名单内:系统技能根、本租户技能根、本项目技能根。实现上不能直接复用 rejectSymlinkEscape(它的 root 是 workspace,目标指向租户技能根会被判越界);需要一个技能专用的解析器,先 EvalSymlinks,再判断落点是否在白名单内,不在就记为 invalid 并跳过。

read_skill_file 的资源边界是该技能解析后的真实目录:项目层的整目录软链先被解析,资源只要落在解析后的技能根内就行;技能内部再指向根外的软链按 invalid 处理。平铺形态的根就是那个 .md 文件本身,它下面没有资源。注意这里的「只在本技能内」是工具契约,不是沙箱边界——bash 的可见范围比它宽(见下)。

bash 的可见范围(2026-10-28 改口径并翻案,D25 + D29;第十二轮把「整个技能根」收窄成「本场用过的」,§9-34 + D35):根 run 准读本场 use_skill 过的技能根,子代理看不到。

复审发现:放行「整个技能根」会让 bash 绕过技能工具(已拍 2026-10-28 第十二轮:只放本场用过的,§9-34 + D35)

D25 的第一版口径是准读技能根——根是整个目录(<workspace>/tenants/<tid>/skills/、<workspace>/system-skills/),不是「manager 已经加载的那个技能」。按那个口径,manager 的 bash 可以 ls 技能根、cat 任何技能的 SKILL.md(第十二轮已收窄成「本场用过的那些」,下面是当时的对照)。逐条核过之后,真正绕得掉的是三条,不是五条(2026-10-28 第二次核对 bash.go 之后修正:上一稿写「一次绕过五条」把 D26 写重了),这也是收窄的理由:

保护 cat 能不能绕 依据
正文上限(D26) 基本不能 bash 自己的 stdout 上限是 32KB(bash.go:23 的 bashOutputCap),比正文的 64KB 上限更严;而且超了会写一句「超 32 KB 已截断,把需要的内容写进文件再读」(bash.go:55-60)——不是静默的,与 trim 那种夹子不同
<skill> 包裹 + trim 整块替换(D30) 能,但暴露面小 cat 的结果是普通 tool 行,trim 不认它、会给头尾夹;不过一条最多约 1 万 token,真到挤占时先被换掉的是更老的结果
折后 skill-ops 留痕(D31) 能 钉块的来源是 assistant 行里 read_skill/use_skill 调用的参数,bash 这个名字进不了那段提取
任务归属盖戳(D32) 能 没走 use_skill,TaskCreate 时就没有技能名可盖,任务在库里不带 skill_name
禁用闸(116107) 能 闸查在 read_skill/use_skill 里,cat 不经过它——被禁用的技能不进目录,但文件还躺在根下

所以这条口子的性质要说准:它不是「安全洞」——读的是管理员自己装进来的内容,读者是根助手,沙箱仍然挡着技能根以外的一切(别的租户目录、~/.ssh、全盘);它是「审计与策略洞」:两条记录(留痕、任务归属)没了,禁用从「读不到」退化成「不主动递给你」。

具体的戏(第一版口径下会发生,第十二轮收窄就是为了掐掉它):管理员禁用了 pdf(这份正文有问题)→ manager 的目录里没有它 → 但 manager 在某轮里 ls /srv/tako/workspace/tenants/t_01/skills/ 看到 pdf/,cat 了它的 SKILL.md → 照着那份有问题的正文办事;看板上那些任务不带 skill_name、摘要里没有留痕,事后查不出这场 run 用过 pdf,也没人知道那份正文是从禁用名单后面翻出来的。

两个选项:

放行整个技能根(第一版口径,已不取) 只放行「本场 run use_skill 成功过的技能根」(已拍,D25 + D35)
能跑技能自带脚本 能 能(正文让跑的就是它自己那一份)
能 cat 隔壁技能正文 能(绕开留痕/任务归属/禁用闸) 不能
禁用闸 可绕(文件还在根下) 生效(禁用报 116107,进不了白名单)
实现 ctx 里一个静态清单 ctx 里一个 run 内可变的盒子,use_skill 成功时 append、装配时按看板补(D35);先例是仓库里已有的 foldBox(定义 midfold.go:57,消费 guard.go:105、media_send.go:188),而「沙箱根从 ctx 取」也已是既有形态(activeRoot,scope.go:75;startBash 每次写一个新的 tako-sb-*.sb,sandbox.go:135,所以盒子在两次调用之间长大是生效的)
代价 D31/D32 对 manager 形同建议 白名单随 run 增长;续跑/跨 run 要靠看板补回,多一次装配期查询(D35);read_skill_file 不受影响(它不走 bash)

2026-10-28 第十二轮已拍:取后者。 它把「manager 能读到什么」重新绑回技能工具,D31/D32 与禁用闸因此是结构性的(靠工具池与装配点,不靠模型自觉,§2.8)。改动量其实只有一处——白名单本来就要「改签名 + 从 ctx 取」(上面第 1–3 步),两个选项的差别只在「清单从哪来」:静态列表 vs 一个 mutex 保护的可变集合(foldBox 同款,约二十行;定义在 midfold.go:57,withFoldBox/foldBoxFrom 在 :308/:313,装配点在 worker.go:488)。它带来的新规矩是「先 use_skill 声明执行,才能跑它的脚本」——这本来也是自然顺序(只 read_skill 看了一眼正文的,没有理由去跑它带的脚本)。

收窄之后多出一个必须回答的问题:盒子从空开始,「接着上次继续跑」怎么办? 答案是 D35:装配时看板(run_tasks.skill_name)里已经有这个技能的任务,就直接把它的根补回盒子,manager 不必再声明一次;没有任务才要求重新 use_skill。所以「先声明才能跑脚本」这条规矩的完整表述是——本场声明过,或本场要接着办它已经建过任务的活。

4.5 删除与清扫

动作 代码路径 技能后果
删项目 product_api.go:315 删项目目录,:324 逐个删会话目录 项目技能随目录消失、对应行一并删;团队/系统技能不受影响。同一事务里删掉这些名字在本租户 skill_disables 里的行(tenant_id = ? AND name = ?,理由见下)
删会话 只删会话的 .tako/.media 不影响任何技能
删团队技能 管理 API:目录移入 .trash/<name>-<ts>、删 skill_rows 行(按 tenant_id + name)、同一事务里删掉该名字在本租户 skill_disables 里的行 下一次 run 起手不再出现;正在跑的 run 的目录仍列着它,读时返回「找不到」;事件见 §8.2-9
删租户 不在本期 —

行与目录不是一次原子提交:删除崩在中间会留下「行在、目录不在」——目录列着、调用回 116001,由 rescan 清掉(§4.7)。表与表之间是原子的:删技能行与删它的禁用行在同一个 PG 事务里,不会出现「技能删了、禁用项还留着」。

为什么删除要顺带清禁用项:skill_disables 按名字存(§9-1),不记来源。不清就会留下一个看不见的陷阱——删掉 pdf(它处于禁用态)→ 之后重新装一个 pdf → 装成功了,但目录里永远不出现,用户看到的是「装了但模型不会用」,没有任何报错。清掉之后重新装是启用态,这次是显式的,用户要禁用再点一次。(旧文这里还有一条「项目层同名技能被残留禁用项静默盖住」的顾虑,已随 §4.3 的「不做跨层同名」消失——同一视界里不可能有跨层同名,所以这条清理只服务「删了又重装同名」这一个场景。)

4.6 原子安装 / 更新

  1. 上传包先落到 <tenant skills>/.staging/<random>/,在 staging 内完成全部校验(zip 路径穿越、符号链接项、文件数、总字节、frontmatter、正文 token 上限 D26)。
  2. 校验通过后,把现有同名目录 rename 到 .trash/<name>-<unixnano>/,再把 staging 目录 rename 成正式名字。
  3. 失败就把 staging 删掉,正式目录没动过。
  4. .trash 与 .staging 都在安装/删除的锁内清扫(不在启动时——§4.7「进程启动不扫盘」),超过 24 小时的按 mtime 删除;清理失败只记日志。对话内安装挂起的 .staging 也照这条清,所以确认时发现 stagingPath 不在 → 「安装已过期,请重新发起」(§6.6)。按 mtime 判、不按「有没有 pending 行」判:不跨表依赖,也不会误删刚建的在途 staging(在途的一定是新的)。工具根下面那两个点目录(<tenant>/tools/.staging、.trash,D36)用同一条规则、同一个清扫点。唯一的豁免:本次操作正要 rename 走的那份 staging 不删(sweepTempDirsKeeping + stagingKeep,只认「本根 .staging 直下」的目录名)。没它会怎样——挂起超过 24 小时的安装提议被批准时,同一段临界区先清扫、再 rename,源目录被自己清掉,用户读到裸 ENOENT 而不是「安装已过期」;在途 staging 由调用方的 defer os.RemoveAll 收走,豁免不会攒垃圾。(2026-10-28 G1 审计补拍。)
  5. 锁按「改哪块地方」分两级(2026-10-28 第十一轮改,D27;旧「整个技能面一把锁」作废):普通写(安装/更新/删除/租户 rescan/工具上传与删除 D36)取全局共享锁 + 本租户独占锁——不同租户的写互不阻塞,同一租户串行;全量 rescan(系统管理员扫三处根、比对所有行)取全局独占锁,等所有在途的租户写做完。锁放数据库(pg_advisory_lock_shared / pg_advisory_lock 一类),不放进程内——多副本下进程内的闸上线即失效。锁内只做两件事:rename 搬目录 + 写行(rescan 另含本地扫盘——它必须在锁内扫,否则扫完到写行之间别人新装的会被按过期快照删掉)。锁外做网络抓取、解压、校验、上传落 .staging/<rand>/:staging 是随机目录名,写它不跟任何人冲突,包进锁里等于一个慢仓库把全站装删堵死。取不到锁就等或回 409,不强抢。PG advisory lock 是连接级的:必须 pool.Acquire 拿住同一条连接再 lock/unlock,换连接就漏锁(_xact_ 变体随事务自动释放,但文件操作不在事务里,所以这里用显式 unlock + defer)。
  6. 并发安装同名:两个请求都可能把旧目录移走,后到的 rename 可能失败;失败方回 409,不重试覆盖。不用 flock(NFS 语义未测)——串行化靠第 5 条那把库锁,不是文件系统锁。
  7. 读侧窗口:两次 rename 之间路径可能短暂不存在。三个技能工具遇到「找不到」时重试一次,仍失败就返回结构化错误。正在读的旧文件即使被 rename 也能读完(POSIX 已打开的 fd 不受影响),坏情况只落在「换目录那一瞬才开始读」。
  8. 行在盘落定之后写:rename 成功才 upsert skill_rows。崩在两者之间会留下「目录在、行不在」——这个技能暂时不进目录;安装入口遇到同名目录但没有行时认领它(补行),不返回 116106;rescan 也能补。

4.7 存储模型:文件是正文,表是目录

前提是部署形态:引擎跑在容器里,业务文件全部落在共享 PVC 上,所有副本同时挂(RWX,如 SFS/NAS 一类),挂载点一致。这条决定了文件边界:

  1. 镜像只装程序:二进制、前端静态文件;容器层可写但随 Pod 销毁,不承载任何业务状态。进程运行时不读镜像里的任何业务路径,也不借镜像层做持久化。构建上下文若把仓库的 skills/ 带进镜像,那是死文件,没有任何代码读它(部署仓可用 .dockerignore 排掉)。
  2. Pod 挂卷:滚动发布时新旧 Pod 挂同一块卷、同一个挂载点;-workspace 与 -system-skills-dir 都指向卷上的路径(后者默认就落在前者里面)。
  3. 系统技能由发布流程写卷:CI / 一次性 Job 从仓库或发布产物同步 system-skills/,不进 Pod 启动流程;运行中的 Pod 不写它。技能正文、租户目录、媒体产物同样只在卷上。
  4. 状态在 PG / Redis:目录行、禁用开关、run 记录在 PG;runlive 帧在 Redis。镜像零状态。

skill_rows.path 因此是卷上的绝对路径,只用于打开文件,不参与鉴权。

现在(本地 / 测试环境单机):没有 PVC、没有多副本、没有 Job。-workspace ./workspace 就是本地目录,系统技能根默认 ./workspace/system-skills/。本地不自动同步系统技能:要用就手动把示例目录放进去、调一次 rescan(跟部署同样的两步,只是由人手动做);不装系统技能也能用租户技能验证整条链路——但 system-skills/ 目录本身要建出来(可以是空的),因为「系统技能根读失败」按「盘没挂上」处理、整次重扫会中止(§9-35 口径①)。scripts/dev.sh 只管起依赖和服务,不碰技能。进程启动不扫盘、不写表;所有技能根默认在 workspace 里,但即使指到外面,read_skill_file 的资源读取也只看本技能目录。

三份东西各管一件事:

存什么 落在哪 谁写 谁读
正文与资源(字节) PVC 上的技能目录 安装、部署 read_skill/use_skill(正文)、read_skill_file(资源);文件工具只做 workspace 里的活
目录(名字、描述、路径、依赖、可用性) PG 表 skill_rows 安装/更新/删除、rescan(部署同步系统技能后调用) run 装配、列表
这个租户用不用 PG 表 skill_disables(tenant_id + name) 管理 API run 装配、技能工具

为什么禁用要单独一张表(2026-10-28 拍):两条更省事的路都不通,才落到小表上。

skill_rows 一行一个技能:

列 含义
scope system / tenant(项目层开了再加 project)
tenant_id 团队行为租户 id;系统行写空串(不用 NULL——同一个「没有」只留一种表示,查询不用在 = '' 和 IS NULL 之间分叉)。这一列同时是唯一键的桶:系统行自成一桶(空串),每个租户一桶(它的项目层行也在本桶)
project_id 项目行为项目 id;其余空串
name 生效名,与目录名一致
path 入口文件的绝对路径:目录形态是 <name>/SKILL.md,平铺形态是 <name>.md(PVC 上的路径,各副本一致)。资源读取的根由它推导:目录形态取所在目录,平铺形态就是该文件、没有资源
description 作者写的描述,全文(安装时校验 ≤1024 rune)
requires 声明的可执行名列表(JSON);只存声明,不存检查结果
bytes 技能目录里普通文件之和(安装或 rescan 时 WalkDir 算)
valid / reason 是否通过校验;不通过时记原因(坏 frontmatter、软链越界、同桶重名)
updated_at / updated_by 展示与审计

唯一键是 (tenant_id, name) WHERE valid(部分唯一索引)——同一个桶内生效名字唯一,数据库层就是闸(§4.3、D7;2026-10-28 第十三轮按租户收窄):桶就是 tenant_id,系统行(tenant_id 空串)是它自己的桶、全集群一行,每个租户是各自的桶(租户层行与本租户的项目层行同桶)。同桶插入生效行撞唯一索引,插入失败本身就是拒装。「系统行 vs 某租户行」跨桶,索引管不到,由两个写入口显式比(下一段)。scope / tenant_id / project_id 仍用于展示来源、权限判定,以及**rescan 的比对范围**——租户级的重扫只按 scope + tenant_id 过滤出本租户的行来比对,系统技能的行和别租户的行根本不参与,所以「扫描范围」和「比对范围」天生是同一个集合(它们读的是同一组归属列)。

为什么按租户收窄、不再全局唯一(2026-10-28 第十三轮,用户裁「就是按多租户的方式」):全局唯一在多租户下是 bug——租户 A 装了 pdf,租户 B 再装一个同名 pdf 会撞 116106,可两家的技能根、目录、禁用项本来就互不可见,没有任何互斥的理由。收窄之后还剩三种冲突,各归各的闸:①同租户内的重复(租户层 vs 本租户项目层、同层两个目录同名)——同一个桶,唯一索引直接挡,不用写代码;②「系统行 vs 某租户行」——跨桶,索引表达不了,落到写入口:安装(含 skill_install 的解析期)落盘前查 SELECT 1 FROM skill_rows WHERE scope='system' AND name=$1 AND valid,命中就 116106;系统 rescan 写生效行前查 WHERE name=$1 AND valid 有没有租户已经占了这个名字,命中就把系统那行记 invalid(§4.3「先占的生效」);租户 rescan 写生效行前也要先查系统行;③别的租户——不看、不管,天然互不影响。

这不是把闸降成提示:②那三处检查确实在应用层,但它们都在 D27 的锁下——租户级写持「全局共享 + 本租户独占」,全量 rescan 持全局独占,两者互斥;所以「查完到写入」之间没有别的副本插进来的窗口。唯一的代价是:只读路径(read_skill 等)依赖「写入时已经检查过」,如果将来有人绕过三个写入口直接改表,索引拦不住跨桶同名——这也是「写操作只有一个入口」(D27)要继续守住的理由。

为什么是部分唯一、不是全表唯一(2026-10-28 第六轮;第十三轮改成带 tenant_id 的三列形式):D7 要求同名冲突时把后来者记成 valid=false 一行,而 §4.7 又要求 invalid 必须进表(否则管理页看不见盘上有这么个东西)。同桶里迟早会撞上:租户已经装过 pdf(租户层生效),有人又往项目根里放一份 pdf → rescan 要把项目那行记成 invalid,两行的桶和名字都一样。不带 WHERE valid 的唯一键这时插不进去——两条要求直接互斥。加 WHERE valid 之后:同一个桶内生效行仍只有一个名字(闸还在,且仍然是「插入失败即拒装」),同名的 invalid 行可以有多条(盘上有几份同名东西就记几条)。rescan 把一条 invalid 转成生效时,在同一事务里先删旧 invalid 行再插,不会撞。

为什么现在可以进表:之前否掉它的理由是「系统技能随镜像,滚动发布时新旧镜像的集合不同,共享表会被两个版本互相增删」。现在系统技能放在 PVC 上,全集群只有一份,跟镜像版本无关;团队技能本来就在同一块卷上。两个副本读到的是同一批文件和同一张表,没有需要版本维度的地方。

为什么需要 rescan:它不是一个事务。装/删/改一次要动两个系统——盘上的文件、PG 里的行。普通写库有事务兜底,这一笔跨了文件系统和数据库,没有能同时提交两边的机制:rename 成功了、写行失败,就留下一边。所以「两边一起改」只在顺利时成立;rescan 是补偿动作,把表重新对齐到盘,不是日常步骤,也不是启动任务。

多副本下的互踩(2026-10-28 拍,D27;第十一轮改锁粒度):上面只说了「崩在中间」,没说并发——而并发才是多副本的真问题。时序:副本 A 的全量 rescan 扫完盘、正要执行「删掉表里盘上没有的行」,副本 B 刚 rename 完目录并 upsert 了行 → A 把 B 刚写的行删掉 → 目录里有技能、表里没有 → 这个技能从目录里消失,没有任何报错,直到下次 rescan 才回来。修法是 §4.6 第 5 条那两级锁:普通写取「全局共享 + 本租户独占」,全量 rescan 取全局独占——所以上面这个时序被全局那把挡住;而租户级 rescan 只比对 scope='tenant' AND tenant_id=$1 的行(下一段),和别租户的安装本来就不碰同一批行,两者并行不出错。

写点与崩溃窗口:

没有启动扫描:进程启动不读技能根、不写 skill_rows。系统技能由部署流程在同步文件之后调用 POST /api/skills/rescan(系统管理员)写行——这是部署自己的第二步,不是应用启动的一部分;本地不跑这段流程,要用就手动做同样两步。这样表只有显式写入口,不会出现「每个副本启动都写一次」「已删行被重启复活」「启动扫描与 rescan 两套解析逻辑」这些副作用。首启空表照常起服务,目录为空,直到第一次 rescan。

rescan 是唯一的「以盘为准」入口:系统管理员扫三处技能根、比对全部行;租户 owner/admin 只扫本租户根与项目根、只比对本租户的行(§6.3)。按唯一键 upsert 或删除行,返回 {added, updated, removed, invalid, roots};管理页的「重扫/导入」按钮就是它。run 装配不做这件事。扫描范围与比对范围必须一致——扫哪几个根,就只动那几个归属的行;这条不是额外规则,是上表 scope/tenant_id 两列存在的理由(2026-10-28 第六轮)。

依赖不进表:requires 只存声明;missing 由 GET /api/skills/:name/check 在当前副本现算——LookPath 是每台主机的事实,存进表就是让副本 B 展示副本 A 的结论。

invalid 进表:坏文件、软链越界、同桶重名也写行(valid=false + reason)。否则它们既不在目录里、也不在管理页上,用户只会看到「放进去没反应」。

前提:PVC 必须是 RWX 且各副本挂载点一致。若 PVC 是 RWO(一次只能挂一个 Pod),多副本根本共不了盘——那不是这张表能修的,得先换存储。

5. 加载链路(端到端)

装技能(上传包 / 来源串 / `npx skills add` 命令 / 拷目录;或对话里 manager **提议、人确认**后由确认端点安装)
  → <tenant>/skills/<name>/SKILL.md                  [PVC,正文正本]
  → 同一请求里 upsert skill_rows 一行                 [PG,目录]
  → 用户发消息 POST /api/runs
  → worker 起 run,装配阶段两条 SELECT:skill_rows(system + 本租户)+ skill_disables(本租户)
  → 执行权恢复(D35):查一次 run_tasks.skill_name(续跑看本 run 已重放的行,新 run 看 D34 的「上一场」),
     命中的技能把「根」补进 bash 盒子(逐项重判:仍 valid / 未被禁用 / 盘上还在;工具根按租户常开,不在这里)
  → 盒子之外的技能要执行,仍得本场 use_skill(盒子从空开始,不补历史)
  → 按 manager 作用域过滤、渲染 <available_skills>(视界内名字唯一,没有「覆盖同名」这一步,§4.3)
  → manager 的 system prompt(本次 run 只算一次;普通子代理不注入)
  → manager 看目录选中技能:要办事调 use_skill({name})(只想看看内容调 read_skill)
  → tool_call / tool_result 帧 + TurnEntry            [agent=""]
  → 正文以 <skill name=…>…</skill> 进 manager 的上下文    [mh 的 tool 行]
  → manager 自己按正文把步骤拆成看板任务(TaskCreate,程序在此时按本 run 最近一次 use_skill 盖 skill_name)
  → **下一枪**:该技能的 <skill> 块整块换成 marker(D33)——正文不再每枪重付
  → manager 照任务执行;重活派给普通子代理(coder/researcher)
  → tool_call / tool_result 帧 + TurnEntry            [agent="coder"](若是子代理)
  → EndRun:mh 行(可能已是 marker)+ runlog 行(带 agent,payload 里是发射时全文)
  → 根 compact / mid-run fold 后:技能记录块钉进摘要末尾;万一正文还在,也整块换 marker 而不是截成 2000 runes
  → 需要细节时 manager 重调一次 read_skill({name})(marker 不阻止重读)

把每一步拆成四问:

步 做什么 输入从哪来 输出去哪 不做会怎样
1 安装 校验 frontmatter/包安全,落团队技能目录并写行 上传包、来源串或 npx skills add 命令(解析后同一条路径) PVC 上的目录 + skill_rows;GET /api/skills 可查 只能手工拷文件:普通成员装不上,坏包在 run 时才炸,目录里也看不见
2 起 run 认证、选项目、建 run 行 POST /api/runs worker 装配 —
3 读表/渲染 读 skill_rows(system + 本租户)与 skill_disables(本租户)、扣禁用、按 manager 作用域过滤、拼 XML PG 两条 SELECT + manager 规格 内存里的目录字符串 没有目录,manager 不知道有技能
4 注入 每次模型调用把 sys + "\n\n" + 目录 + "\n\n" + snap 赋给 manager 的 Messages[0] 第 3 步的字符串 manager 的模型请求 目录只生成不使用,等于没做
5 选择 manager 读目录,决定用哪个技能、以及是「办事」还是「看看」 模型判断 tool_call 帧 + TurnEntry(name="use_skill" 或 "read_skill"、agent="") —
6 读取 use_skill/read_skill 整篇读正文;需要资源时调 read_skill_file({name, path})。三次都按调用时刻查行:正文开行里的入口文件,资源在技能根内解析 技能名(+ 相对路径)+ skill_rows + 磁盘 tool_result 帧 + TurnEntry(agent="")+ mh 的 tool 行(正文原样,<skill> 包裹) 只给名字不给正文,执行者只能猜;只给正文不给资源入口,附件就得到处拼路径
7 展开 manager 按正文把步骤拆成看板任务(TaskCreate,程序此时按本 run 最近一次 use_skill 盖 skill_name);下一枪正文整块换成 marker(D33,判据是这之后有没有 TaskCreate) 第 6 步的正文 + 本 run 的 ToolCalls run_tasks 行;mh 里那条 tool 行变成 marker 步骤只活在上下文里,一压缩就丢,manager 不知道做到哪;正文不走则每枪重付一份全文
8 执行 manager 照任务做事;重活按任务派给普通子代理 正文 + 任务 工作结果 读了不执行,等于只做摘要
9 落库 EndRun 写 mh 与 runlog(带 agent) TurnEntry PG 下一页/下一次调用看不到结果
10 续用 下一次模型调用从 mh 重建输入 mh 模型请求 结果只活在内存,第二枪就丢
11 折叠 根 compact 标旧行;mid-run fold 折近期行 旧行 摘要行(末尾钉技能记录块) 正文明细被折掉
12 重读 manager 重调一次 read_skill({name}) 目录里的名字 新 mh 行 折叠后无法恢复正文

关键实现点:


6. 管理 API 与 UI

6.1 端点

全部走 {code,message,data} 信封(doc/40);SSE 帧不进信封。

方法/路径 作用 成功体 data
GET /api/skills 读 skill_rows 列出生效技能 + invalid 行 {skills:[…], invalid:[…]}
GET /api/skills/:name 单条详情(frontmatter、来源、路径、字节数、依赖、正文预览) {skill:{…}, body:"…"}
POST /api/skills/preview 只解析不写盘:{source} 或 {command} → 候选技能清单(§6.5) `{source:{…}, skills:[{name,description,bytes,files,requires}], selected:[…], ambiguous:true
POST /api/skills/install 安装:multipart 包,或 JSON {source}/{command},可带 skills:["a"]/all:true {installed:[{name, dependencies:[{name,found,path?}], warnings:[…]}], warnings:[…]}
POST /api/skills/:name/update 覆盖更新(multipart 或 JSON 同上) 同上
PATCH /api/skills/:name {enabled:false} 禁用/恢复(写 skill_disables 一行/删一行,不碰 skill_rows,§9-1;owner/admin,viewer 403 111203) {skill:{…}}
DELETE /api/skills/:name 删除团队技能(同一事务里按 tenant_id + name 删 skill_rows 行、并删该名字在本租户 skill_disables 里的行,§4.5) {status:"deleted"}
GET /api/skills/:name/check 在当前副本重查依赖 {dependencies:[{name,found,path?}], checkedOn:"host"}
GET /api/tools 扫盘列出本租户工具根(不进表;跳过 . 开头的目录) {tools:[{name, exe, path, bytes, updatedAt}]}
POST /api/tools 上传一个可执行文件:multipart name + file;同名=覆盖更新(staging → .trash → rename) {tool:{name, exe, path, bytes, updatedAt}}
DELETE /api/tools/:name 工具目录移入 <tenant>/tools/.trash/<name>-<ts> {status:"deleted"}
POST /api/skills/rescan 以盘为准重扫:系统管理员扫三处根、比对全部行;租户 owner/admin 只扫本租户根与项目根、只比对本租户的行。管理页的「重扫/导入」(§4.7、§9-35) {added:[…], updated:[…], removed:[…], invalid:[…], roots:[{path, scope, exists, count, error}]}
GET /api/runs/:id/skills 这场 run 加载过哪些技能、读了哪些文件(从 runlog 的 read_skill/use_skill/read_skill_file 行派生,见 §8) {runId, loads:[…]}

技能的写操作只有一个入口(2026-10-28 拍,D27):上表里带写语义的是 POST /api/skills/install、POST /api/skills/:name/update、PATCH /api/skills/:name、DELETE /api/skills/:name、POST /api/skills/rescan 五个端点——它们是唯一改盘或改表的入口(对话内确认端点的 kind=install 分支与「整条消息=命令」的装配期分流最终都调到这里;skill_install 自己不写盘,§6.6)。所有写路径走同一套两级锁(§4.6 第 5 条):普通写取「全局共享 + 本租户独占」,全量 rescan 取全局独占——并发写不互踩,不同租户也不互相排队;rescan 的本地扫盘在锁内、网络抓取在锁外。工具写面是第二个写入口(POST /api/tools、DELETE /api/tools/:name,D36):它改的是 <tenant>/tools/、不碰表,所以不在这五个端点里;但走同一把锁的普通写那一档——与技能安装、全量 rescan 排同一个队,不另造一套并发规则。

skills[] 一行至少包含:

{
  "name": "doctor-registration",
  "description": "当医生提供或更新称谓……",
  "source": "tenant",
  "path": "/srv/tako/workspace/tenants/t_01.../skills/doctor-registration/SKILL.md",
  "enabled": true,
  "bytes": 4213,
  "requires": ["python3"],
  "missing": [],
  "updatedAt": "2026-10-27T10:00:00Z",
  "valid": true
}

invalid[] 是「盘上有东西但没通过校验」的条目:{path, reason},来源是 valid=false 的行。这是手工拷目录绕过 API 的兜底——rescan 是第二道闸,不信任「能放进来就一定是好的」。

roots[] 是这次扫了哪几个根、每个根读到几条:{path, scope, exists, count, error}。它不是保护机制,是让返回体说人话——盘出问题时运维不必猜 removed:37 是什么意思,直接看得见「系统技能根:0 条」(§9-35)。

bytes 是技能目录里所有普通文件之和(平铺形态就是该文件大小),在安装或 rescan 时由 WalkDir 算并写入行,不从 description 或 SKILL.md 单文件猜。

6.2 业务码(提案,施工时进 doc/40 §4)

116 段目前空闲:

码 HTTP 含义
116001 404 找不到这个技能
116101 400 技能名/markdown 结构不合法
116102 400 缺 description
116103 400 description 超过 1024 字符
116104 400 frontmatter 解析失败
116105 400 安装包不合法(zip 穿越/软链/超限/坏 frontmatter)
116106 409 同名冲突(本租户视界内已有同名:本租户装过,或撞了出厂技能;别的租户用同名不算,§4.3)或目标是系统技能(只读)
116107 409 技能已禁用(read_skill/use_skill 调用时)
116108 400 来源里有多个技能,必须选(skills 或 all)
116109 400 来源/命令不支持(未知子命令、shell 元字符、SSH、私网地址、服务端本地路径、私有仓库)
116110 400 拉取来源失败(网络、上游 4xx/5xx、超时)
116111 400 包里没找到技能(没有含 SKILL.md 的目录)
116113 413 安装包超限(下载字节、解压总量、文件数、层级)
116114 404 这个路径在 read_skill_file 里读不到(入口文件请用 read_skill/use_skill;含路径越界、平铺形态没有资源目录)
116115 413 资源文件超过单次读取上限(16,384 token 或 64KB,与正文同一条判据,不截断)
116116 413 正文超过上下文预算(超 16,384 token 或 64KB 字节;整篇进上下文会超 trim 预算,详见 §2.3)
116117 400 工具上传参数不合法(名字不合规则、预留名 bash/sh/env、空文件)
116118 413 工具文件超限(单文件 >128MB)
116119 404 找不到这个工具

额度不足不新造工具码:仍走现成的 codeQuota(429,「这个工作区的额度用完了」)。

权限不足仍用现成的 111203(403),不为技能新造权限码。116112 已作废(对话内安装改为 HITL,见 §6.6)——码值不复用:它曾经的含义「来源没在用户原话里逐字出现」对新施工者就是误导。

码值在施工时以 doc/40 §4 为准,施工拍必须同批更新码表与 scripts/acceptance/expected.json。

6.3 权限

6.4 UI

新增「技能」页(与项目、成员同级):

目录本身不做编辑界面——它是派生视图,改了会被安装或 rescan 重算覆盖。

6.5 安装来源与 npx skills add 命令

用户在 GitHub README 上按「复制」,拿到的是 npx skills add owner/repo --skill x。tako 不装 Node,也不该为装一个 Markdown 包引入一个执行面——所以这条命令在 tako 里的角色是输入格式,不是要执行的程序。

三种输入走同一个入口、同一条安装路径:

输入 请求体 谁产生
上传包 multipart:file=*.zip / *.tar.gz 技能页「上传」、curl
来源串 {"source":"owner/repo@skill#ref"} 技能页输入框、curl
命令串 {"command":"npx skills add …"} 从 README 复制、对话

POST /api/skills/preview 与 POST /api/skills/install 都吃这三种输入。区别只有一处:preview 解析、抓取、校验完就停;install 多做原子落盘(§4.6)。

命令语法(v1 白名单):

片段 认什么 映射到
npx skills add / skills add 唯一前缀 其他子命令(list find remove/rm update check init use,以及裸 npx skills)→ 116109
第一个非 flag 参数 owner/repo、owner/repo@skill、owner/repo#ref、https://github.com/…(含 /tree/<ref>/<subpath>)、https://gitlab.com/…、https://…/x.zip|.tar.gz|.tgz resolver 的 source
--skill <名> / -s <名>(可重复;值可含 *) 选技能 skills[]
--all 全装 all:true
--list 只预览 preview:true
--ref <ref> 分支/标签/提交 ref(与 #ref 同义,两处都给以 flag 为准)
-g --global -p --project --copy -y --yes 社区 CLI 的作用域/安装方式/交互开关 接受并忽略,进 warnings
-a <agent> --agent <agent> --all-agents 目标 agent 目录 接受并忽略(tako 只有一个落点:租户技能根)

矛盾组合(--all 与 --skill 同给、#ref 与 --ref 不一致)→ 116109。

解析不经过 shell:

抓取:

来源 抓取地址 备注
GitHub https://codeload.github.com/<owner>/<repo>/tar.gz/<ref|HEAD> HEAD 走默认分支,不调 API、不吃 rate limit;直连 codeload 是因为 github.com/…/archive/… 只是 302(字节本来就由 codeload 提供),少一跳也少一个可能打不开的域名;/tree/<ref>/<subpath> 只在该子目录里找技能
GitLab https://gitlab.com/api/v4/projects/<urlencoded> 取 default_branch,归档 https://gitlab.com/<path>/-/archive/<ref>/<repo>-<ref>.tar.gz 公开项目即可,不带 token
直链 原样 GET,必须 .zip / .tar.gz / .tgz 不跟随到非 http(s)

从归档里找技能:

落盘复用 §4.6:staging 里跑完校验 → 旧同名目录进 .trash → rename 到位 → 发 skills_changed(§8.2-9)。失败时正式目录一个字节没动。

6.6 对话里的入口

两条路径,由「消息里有没有别的话」分工。共同点是:写盘都由人的动作触发,不由模型触发。

  1. 整条消息就是命令(trim 后匹配 ^(npx\s+)?skills\s+add\s+…):worker 在装配阶段分流,不调模型。用同一个 resolver 执行预览或安装,把结果写成一条 assistant 消息——装了什么、缺哪个依赖、候选清单、或错误原文;run 正常 complete,帧面是 start + 一条 delta(整段文本)+ terminal,没有 usage。权限不够就回「只有 owner/admin 能安装技能」,不写盘。 为什么不交给模型:装包是写操作,结果要可复现;让模型判断「这看起来像安装命令」会把路由变成概率事件——同一条命令重试一次可能换个说法或干脆不装。这条路不需要再确认:人打/粘这条消息并按下发送,本身就是那次点击。这条路仍要求 run 能起(assembleRun 在 AcquireRun 之前解析模型,租户没模型时 POST /api/runs 先回 111408);它省掉的是模型往返与输出波动,不是模型配置。

  2. 命令夹在自然语言里(「帮我装 https://github.com/x/y 这个技能」):manager 有 skill_install,它是提议工具,四拍与 ask_user 同构(waittools.go 那套:落行 → 发帧 → 轮询 → 结果回同一轮):

    1. 解析:resolver 抓取、校验、算候选,只落 .staging/<rand>/。不碰技能根、不写 skill_rows、不发 skills_changed。preview:true 只返回候选、不落行。
    2. 落行:run_questions 一行,kind=install;question 存一行人话(「安装 2 个技能:pdf、xlsx(来源 owner/repo@abc1234,12 个文件,48KB)」),args 存 resolver 的结构化输出(source、候选全表 candidates、选中集 skills、staging、warnings)。「来源在本会话出现过没有」不进 args:由前端拿当前会话的 user 气泡文本比来源,只作卡片上的一行提示(下面「为什么」那段解释了它为什么不能当闸)。发 kind=question 帧(name=skill_install)。
    3. 人点:前端只按 args 里的结构化字段渲染确认卡——来源、ref、每个候选的名字/描述/字节/文件数/依赖、哪些被选中、未被选中的也列出来(否则模型挑一个恶意兄弟包,人以为装的是那个正经的),外加一行「此来源在本会话中未出现」。按钮打到现有答案端点(questions.go 已按 kind 分支,:218)。
    4. 程序写:kind=install 分支里执行安装——抓取与校验在第 1 步就做完了(锁外),这里只做 D27 的锁 → rename → 写 skill_rows → 发 skills_changed;结果字符串写进行、作为 tool_result 回到同一轮,模型继续。注意 staging 有 24 小时清扫:从提议到点击之间可能被清掉,所以先看 stagingPath 还在不在。

    为什么不能是「模型问一句、然后模型再调一个写工具」:那模型仍然握着写权限,只是先说了句话——它可以跳过、可以误报答案。写盘必须发生在点击处理器里,模型全程没有写路径。 为什么也不能是「比对用户原话」:用户把 PDF/邮件正文贴进对话框时,那串字就在他的消息里,比对会放行;而模型给的是解析后的来源(https://github.com/owner/repo)、用户原话是命令串(npx skills add owner/repo),比对又会误拒。两头都漏/误伤的规则不是闸,是额外的一层字符串约定。所以「来源在本会话出现过没有」只作卡片上的一行提示:它恰好是点击前最有用的一条信息,但不拒绝任何东西。

    唯一消费:同一行只能被一次点击消费(AnswerQuestion 的 CAS,输的那次回 409 且不装)。安装结果写入行的 answer,所以顺序是「先认领行 → 再装 → 把结果写回行」;崩在中间是已知窗口(行已答、盘未动),tool_result 报「确认已消费但安装没有完成,请重试」——比「两次点击装两遍」好。

    取消与过期:人点「取消」→ 行 answered、tool_result 写「用户取消了安装」,不是错误码;.staging 按 mtime 24 小时清扫(在安装/删除的锁内做,§4.6 第 4 条),确认时 stagingPath 不在了 → 「安装已过期,请重新发起」(24h 这个数值待定)。

    权限:点「安装」要 owner/admin(答案端点的 kind=install 分支判 principal.Role),普通成员点了回 111203 并提示「等管理员确认」。工具本身不做权限判定——它不写盘。 这是 §1 病灶 6 只解一半的地方:普通成员能提议(把包摆到管理员面前、附程序解析出的事实,管理员点一下即可),但点头仍然必须是 owner/admin。

    边界:HITL 解决「谁授权」,不解决「包是否安全」。管理员点了恶意包,它照样装进去;那是供应链问题,靠详情页可见 + 禁用/删除兜(§12 不做扫描)。


7. 依赖检查

三层,分开说:

  1. 声明:技能 frontmatter 里可选 requires: [python3, ffmpeg],元素是可执行名,不是包名、不是版本约束。
  2. 安装时检查:在接收安装请求的副本上 exec.LookPath(用 D39 那条过滤后的 PATH:工具根 bin 在前、围栏读不到的目录已剔除),把每个依赖的 found 与解析到的路径写进响应。缺失不阻断安装(默认),只回琥珀色警告——因为团队可能先装技能、后补环境,也可能只在某些节点用;阻断会把「安装」和「这台机器现在能不能跑」绑死。若租户策略要求「缺依赖即失败」,那是后续策略开关,不在 v1。
  3. 运行时:不做启动前检查。依赖缺失时,技能正文让模型调 bash 会拿到 command not found,这是正常工具错误;不假装成功。Linux 无沙箱时 bash 本身 fail closed,见 §9。

LookPath 通过 ≠ 沙箱里跑得起来(2026-10-28 补,用户问「Python3 会不会本身就因为权限问题无法执行」)。依赖检查只证明「这台机器上有个叫 python3 的东西」,真正执行时命令跑在 seatbelt 里,围栏只放行「项目根(可读写)+ /usr /bin /sbin /opt /System /Library /dev /private/var(只读)+ 技能根(只读,D25)」,(deny default) 打底(sandbox.go:60-73)。第十六轮起(D39)LookPath 用的就是过滤后的 PATH,所以「围栏外被找到」这一格已经不会发生;剩下的是「找得到、读得到,但跑不起来」:

装在哪 LookPath 沙箱里执行 失败长什么样
/usr/bin/python3(系统 / Xcode 命令行工具) 找到 能跑 —
/opt/homebrew/bin/python3、/usr/local/bin/python3 找到 能跑 —
~/.pyenv/shims/python3、~/miniconda3/bin/python3、asdf 一类 不找到(D39 起围栏外目录已从 PATH 剔除) 跑不起来 command not found;若正文用绝对路径点名调用,则是 Operation not permitted
脚本自身(scripts/build.py) — 需要 D25 没有 D25 时 can't open file '…': [Errno 1] Operation not permitted

另外两条由围栏直接决定、写正文时要想清楚:①网络是「出站开、入站不开」(2026-10-28 第十五轮,D37)——curl、下载数据集、调外部 API 都能用;但 pip install 默认装到 ~/.local 会失败(HOME 不在白名单),要装就 pip install -t ./vendor(目标必须在围栏根内)。tako 仍不替你装依赖(D11):能联网不等于会自动补环境。②技能根只读(D25 只给 file-read*)——Python 写 __pycache__ 会被静默跳过(不致命),但脚本把产物写在自己旁边会失败,产物要落到 cwd(项目根)。

所以「依赖检查通过」的准确含义是「围栏读得到一个同名可执行文件,但它能不能跑没验证」(架构、动态库、解释器自己的 stdlib 都可能不成立)。v1 不做围栏内探测(那要真跑一条命令、还要定超时);这条是作者须知,也意味着验收用例不能拿 HOME 下的解释器当正例。

工具装在哪:<tenant>/tools/(2026-10-28 拍)。位置与 skills/ 平级:<workspace>/tenants/<tid>/tools/。不放项目里:项目根就是围栏根(可读写),把解释器放进去等于让这场 run 能改自己的解释器;要堵住这个口子就得同时改 bash 的 profile 和文件工具的根(resolveInWorkspace 一样能写到它),两条规则换不来什么。也不放项目目录的上一级:那是 .../workspaces/,装着同租户的所有项目,放行它等于让一场 run 能读写别的项目的代码。租户根在围栏外,只读放行就够了。三条理由:删项目不带走、在共享 PVC 上(全副本一致)、可以只读放行。

四件:

  1. 目录约定:一个工具一个前缀,<tenant>/tools/<name>/bin/<exe>(照 Homebrew / pyenv 的 prefix 形状)。
  2. 解析顺序:requires 里的名字先在同租户工具根找(<tenant>/tools/*/bin/<name>),找不到再走过滤后的宿主 PATH(D39:围栏读不到的目录已剔除);安装期检查按同一顺序,响应里的 path 写明解析到的是哪个可执行文件(PATH 里也是这个顺序,见第 4 条)。不问解释器「你的前缀在哪」——那要跑 python3 -c 'import sys; print(sys.prefix)',等于执行一个由技能声明的可执行文件;装/装配时没有围栏、跑的是引擎进程的权限,正是 D22 拒绝的事,所以只能从路径找。
  3. 沙箱:工具根不随技能进盒子(2026-10-28 第十四轮,D36)——<tenant>/tools 按租户常开:startBash 里把整棵工具根加进只读白名单(先 EvalSymlinks,与 sandbox.go:50-52 同一条规矩),所有角色(含普通子代理)的 bash 都拿得到;技能根才走 §9-34 的盒子、按证据收窄。工具根在围栏外,所以天然不可写——run 改不了自己的解释器。
  4. PATH:两层改动(第十六轮,D39)。①前置:把每个工具前缀的 bin(<tenant>/tools/*/bin,跳过 .staging/.trash 这些 . 开头的目录)拼在子进程 PATH 最前面——F2 之前是原样透传引擎的 PATH,不前置的话 python3 还是解析到宿主那个;F2 起 subprocessPath 统一拼(bash.go 只调它)。跳过点目录不是洁癖:在途上传的 staging 里也可能有 bin/<name>,拼进 PATH 就等于半成品抢先被解析。②过滤:继承来的每一段先 EvalSymlinks,只保留落在 sandboxReadRoots 之下(/usr /bin /sbin /opt /System /Library /dev /private/var、项目根、<tenant>/tools)的目录,其余(~/.pyenv/shims、~/.local/bin)丢掉;保序、去重。这一步是为了让围栏外的东西报 command not found 而不是 Operation not permitted(见上一段的表)。过滤表与 profile 共用同一个函数——抄两份就会漂,漂回去又是 EPERM。

开发机怎么装:把 <tenant>/tools/<name> 做成指向宿主工具链的软链就行——解析发生在 EvalSymlinks 那一步,落到 /opt/homebrew/...、/usr/... 这些本来就在白名单的路径上。直接用 pyenv / conda 的 prefix 当软链目标也可以;不要把 HOME 本身加进白名单。

谁装、占多少空间(2026-10-28 第十四轮改写,D36):两条路——①owner/admin 在管理页「工具」区上传一个可执行文件(下一段);②部署/运维直接同步进 PVC(与系统技能同一套「同步文件」步骤;工具没有行,不需要 rescan)。工具占的字节计入租户存储额度——directoryBytes 走的是整棵 <tenant>/(scope.go:145-157),一个几百 MB 的解释器会吃掉额度;上传时先用现成的 ReserveStorage 按字节占额度再落盘(filetools.go:74-104,调用形状见 server.go:417-424)。

缺一个工具怎么补(D36)

POST /api/tools(multipart:name + file)——owner/admin 上传一个可执行文件,落到 <tenant>/tools/<name>/bin/<name>,权限 0755。五步:

步 做什么 不做会怎样
1 收 gin 的 MaxBytesReader 卡住请求体;名字按 ^[a-z0-9][a-z0-9-]{0,63}$ 校验;bash/sh/env 三个名字拒;空文件拒 不卡体积,一个大文件能顶爆 PVC;不拒预留名,租户误传一个 bash 会让这个租户所有脚本都用上它
2 占额度 ReserveStorage 按字节先占住,失败回 429 codeQuota 先写后算,超额的字节已经在卷上了
3 落 staging 写到 <tenant>/tools/.staging/<rand>/bin/<name>,chmod 0755 直接写目标目录 = 某场 run 可能 exec 到写了一半的文件
4 换目录 锁内:同名旧目录 → .trash/<name>-<ts>/,再把 staging rename 到位 原地覆盖会让正在跑的 run 读到新旧混合
5 报 回 {tool:{name, exe, path, bytes, updatedAt}},发一个 tools_changed(与 skills_changed 同一条 publishEvent,字节同形 {seq,type,id,at}、id = 工具名,不带 action——理由见 §8.2-9) 多标签页的工具列表不同步

三条边界写明白:

上传之后怎么被用起来:GET /api/skills/:name/check 里那些声明的名字变 found、path 指向工具根里的那个文件;任何 run 的 bash 都能直接调用它,不必等某个技能 use_skill——这就是 D36 把「技能根按证据给、工具根按租户给」两条边界分开的直接结果。普通成员能看见它、能用它,但不能传(§6.3)。

生产(Linux)今天不适用:那边没有沙箱、bash fail closed(§9、D16),脚本一行都跑不了;等 Linux 沙箱 loop 落地,同一条「只绑工具根」的原则换 bwrap 的 --ro-bind 表达即可。

两个必须写清的边界:

明确不做:自动 pip install/apt install;安装期执行包内脚本;执行 npx/npm 本身;从 URL 装工具(工具根只收上传——要下载就自己下好再传,引擎不替租户抓二进制;D37 之后 run 里 curl 到项目根是项目文件,不落工具根、别的项目也用不到)上传时执行或探测工具(Exec format error 这类留给 run 里的 bash)。命令串只被解析、来源只被抓取,包里的 postinstall、scripts/ 永远不运行——这正是「认命令」与「跑安装器」的分界线(§6.5、§6.6)。给 npx 指定本地路径也不改变这条:路径只解决「找得到」,执行包里的代码才是权限面;HTTP 面因此连服务端路径都不收。

依赖检查全程不调用 LLM、不向用户追问:LookPath 是程序在做,结果直接进安装响应;用户看到的是「缺 python3」,不是模型在猜。


8. 观测:今天能看见什么,要补什么

8.1 今天的事实

面 技能调用长什么样 缺口
帧(manager 侧) 读正文:{kind:"tool_call", agent:"", name:"read_skill"} 或 name:"use_skill"(两者 args 都是 {"name":"x"});读资源:{kind:"tool_call", agent:"", name:"read_skill_file", args:"{\"name\":\"x\",\"path\":\"references/a.md\"}"};结果同名为 tool_result(worker.go:821、:734) 没有 toolCallId;并行同名调用只能靠到达顺序猜
runlog role=tool_call,payload {name,args};role=tool_result,payload {name,output}(store.go:418、:403);行上有 agent 列 payload 没有 tool_call_id;created_at 是 EndRun 的 now(),不是调用发生时刻
mh tool 行有 tool_call_id(types.go:70);正文整篇存在 tool 行的 Text 里 内部面,不对 UI/API 暴露,不能当审计面
页面 按名字/顺序把 call 与 result 拼起来 同名并行会错配

8.2 要补的

技能不新增帧类型:read_skill/use_skill/read_skill_file 都是普通工具,kind 仍是 tool_call / tool_result。页面靠 name 识别(2026-10-28 翻案后不再有 agent="skill" 的行——没有内置 skill agent 了,读工具与委派都在 manager 侧,agent="")。

  1. toolCallId 贯穿:Frame 加 toolCallId,omitempty;runlog 的 tool payload 加 toolCallId。帧 kind 词表不变(contract_test.go:162 不用改),但帧字节与 runlog payload 变了 → 同批更新 19v6-01、19v6-04、expected.json。

  2. 读工具的返回形态(成功走 XML 原文、失败走 JSON 信封,见 §2.10):

    成功(read_skill/use_skill,两者返回体逐字节相同):

    <skill name="doctor-registration" source="tenant" bytes="4213">
    # 医生登记
    ……
    </skill>

    读资源(read_skill_file)成功,path 指到文件:

    {"code":0,"message":"","data":{"name":"doctor-registration","path":"references/checklist.md","type":"file","content":"…","bytes":812}}

    path 指到目录(§2.3 承诺的「不递归的条目列表」,2026-10-28 第二轮复审补形状):

    {"code":0,"message":"","data":{"name":"doctor-registration","path":"references","type":"dir","entries":[{"name":"checklist.md","type":"file","bytes":812},{"name":"old","type":"dir"}]}}

    两种形态由显式的 type 字段承载(file / dir),不靠「content 写没写」「entries 空不空」来表示模式。dir 那次没有 content 与 bytes(条目里的 bytes 是各文件自己的大小,目录不递归所以不汇总);file 那次没有 entries。目录列表不递归,正文只说「看 references/」的技能靠它先看清有哪几份,再逐个读。

    正文那次不给 path:入口文件的绝对路径是服务端内部地址,不往外给;要重读正文还是按名字调 read_skill。只有 read_skill_file 的返回体带 path,值就是调用方传的那个相对路径。

    失败:

    {"code":116001,"message":"找不到这个技能,可能已被删除或改名","data":{"name":"doctor-registration"}}

    manager 读到失败能改道(例如换一条目录里描述相近的技能,或直接告诉用户「这个技能装不上」);UI 用 toolCallId 找到对应调用并弹 message。

  3. 技能加载列表:GET /api/runs/:id/skills,从 runlog 派生——筛 role=tool_call、payload.name 为 read_skill/use_skill/read_skill_file,按 seq 排序,配上同 toolCallId 的 result 判断成功/失败。返回 {runId, loads:[{toolCallId, name, tool, path, agent, seq, ok, code}]}:name 是技能名,tool 是 read_skill/use_skill/read_skill_file;path 只在 read_skill_file 的行出现(omitempty,值就是调用参数),两个正文工具的行没有这个字段——模式由 tool 承载,不用空串表示正文。这是精确记录,不是猜因果。注意 runlog 在 EndRun 才写:run 未结束时这个端点返回空,live 页面用帧面里的 tool_call/tool_result 配对展示,run 结束后再以 runlog 为准。

  4. 时间:runlog 的 created_at 是 EndRun 时间,不能用来排「哪次调用先发生」。v1 用 seq/eventOffset 排序;如果 UI 需要墙钟时间,在 tool payload 里加 eventAt(帧产生时的 time.Now()),这是一处存储字节变更,单独拍。

  5. 不做因果归因:不给后续工具打「由技能 X 导致」的标。程序无法从文本判断「模型是因为读了技能才调 bash」;硬标就是编。能说的是:这场 run 加载过哪些技能(精确)、加载发生在哪些工具调用前后(顺序)、之后调了什么工具(记录)。仅此而已。

  6. 没有 007/009 这种编号:一次加载的稳定标识就是 toolCallId;要落库审计时再带 runlog 行 id。不用「第几次技能调用」这种随批次变化的序号。

  7. 不做全局计数器/自动淘汰。doc/16 §2b 的 Hermes skill_usage 自动淘汰不在本期;先把「加载事件可查」做出来,淘汰是策略问题,不是观测问题。

  8. 任务看板复用:技能步骤走既有的 run_tasks 与 kind=task 帧(doc/41),不新增技能专用任务表;run_tasks 加 skill_name 列(D32),TaskList 返回带 skillName 字段——「哪几条任务属于哪个技能」由看板回答,compact 不碰 DB(D31)。

  9. 变更事件:安装/删除/禁用/恢复成功后 publishEvent 一个 skills_changed(doc/46 Loop B),其他标签页收到后重拉列表;事件字节是 {seq,type:"skills_changed",id:"<技能名>",at}(doc/46 §7.6),不带 action——installed/deleted/disabled/enabled 都是状态,事件一旦带状态,客户端就会想「就地改本地副本」而不重拉,正好破掉 §3.1「事件只通知、状态永远重拉」的纪律;名字也已经由 id 承担(租户视界内唯一,§4.3)。2026-10-28 E2 施工按 doc/46 收口,原 {action:"installed|deleted|disabled", name} 写法作废。管理 API 与对话内确认端点的安装分支发同一个事件;skill_install 本身不发——它不写盘(§6.6)。这保证多标签页不会一边显示已删技能、一边还能点。工具写面走同一个机制、但用自己的事件名(第十四轮,D36):POST/DELETE /api/tools 成功后发 tools_changed(同样 {seq,type,id,at},id = 工具名,不带 action)——工具不是技能,让它复用 skills_changed 会逼前端按名字猜资源类型,也会让技能列表在无关变更上重拉。


9. 未决与待拍

这些不影响方案骨架,但施工前必须逐条拍;每条给默认建议。

# 问题 建议默认 拍点
1 禁用状态放哪 已拍 2026-10-28:单独建 skill_disables 表——两列 (tenant_id, name) 做主键,重复禁用撞主键即无事(闸就是主键)。两条更省事的路都被否掉:挂 skill_rows.disabled 会让「一个租户禁用出厂技能」变成「全租户都禁用」(出厂行全集群共享);塞进租户 config 那段 JSON 会被读(json.Unmarshal 进四字段结构体)和写(整列覆盖)两道闸静默吞掉。完整理由见 §4.7 表后两段 删技能时同一事务 DELETE WHERE tenant_id = ? AND name = ?(§4.5);不需要「按来源禁用」——名字在租户视界内唯一,按 (tenant_id, name) 存正好
2 作用域只挂在 manager 已拍并落地 2026-10-28(E1):skills: / exclude_skills: 只认 manager(tenant agent 的 md;JSON 面 skillPolicy),与 tools:/exclude_tools: 同形,同写拒载;普通子代理写 allow/exclude 在入口 400 111002(md 导入与 JSON 同判),显式 inherit 放行(GET 回读带它) skills: [] =「一个都不要」(指针非 nil 区分「没写」)——已按此落地,活体验证目录为空
3 项目技能 v1 做不做 先不做;团队层够用,等有真实「项目专属流程」再开 做的话,项目里只允许软链还是也允许真文件。(2026-10-28 备忘:开启那拍必须把 .tako/skills 从 read_file 的可读范围剔掉——read_file 的围栏根就是项目目录,.tako 只在文件列表里被隐藏(product_api.go:159、:222),挡不住读;不剔掉的话「普通子代理技能盲」当场破功**)**
4 技能名规则 ^[a-z0-9][a-z0-9-]{0,63}$,必须与目录/文件名一致,大小写敏感 是否允许下划线与点;是否做 Unicode 归一化
5 搜索触发 已拍 2026-10-28:不做搜索模式(D28)——目录恒为全量注入,没有「切模式」这回事 —(已拍)
6 搜索索引范围 已拍 2026-10-28:随搜索一起不做(D28)——没有索引,只有全量目录 —(已拍)
7 工具名与参数 manager 池里三个技能工具:read_skill({name}) 只读正文、use_skill({name}) 读正文并声明执行、read_skill_file({name, path}) 读资源;三个参数集都全必填,没有可选字段(不设 mode 参数);不再有 skill 委派工具(2026-10-28 翻案,角色取消) 已拍 2026-10-28(D29/D19,D32):工作对象拆成三个工具,不用「path 写没写」「mode 填什么」区分——模式由工具名承载,它是 assistant 行 ToolCalls 里的结构事实(理由见 §2.3);委派工具整体取消,所以不需要 per-spec 参数
8 帧里是否加 skill 对象 不加;技能工具结果 JSON 的 data.name 已足够,UI 解析 若 UI 不想解析工具输出,再加结构化字段
9 系统技能更新 部署时同步到 PVC,再 rescan(系统管理员);不监听文件、不在启动时扫描 是否要文件监听(会绕开 rescan 这个审计面)
10 安装包大小/文件数上限 单包 ≤ 10MB、≤ 200 个文件、≤ 5 层目录;SKILL.md 正文 ≤ 16,384 token(cl100k)且 ≤ 64KB 字节,取更严的(超了拒装,报 116116,不截断) 已拍 2026-10-28(D26):正文上限不是文件大小问题,是 trim 预算问题——预算硬上限 32,768 token(compact.go:601),超它的正文在长 run 裁剪时被换成 marker 或缺中段的夹子,折叠对模型静默(不会想到重读),还会挤掉其它工具结果的还原额度(§2.3、§2.5 第 4 条)。字节那条只防 zip bomb
11 坏技能怎么办 写 valid=false + reason 的行,不进目录;不阻断 run 管理页要不要显示「本次 run 少了哪些」
12 描述里的换行/Markdown 折叠为单空格进 XML,不做 Markdown 渲染 是否允许描述里写 < 等字符(转义后安全)
13 技能正文的信任级别 视为管理员授权的指令,不是用户输入;安装权限收紧 是否需要在正文注入前做 PII/密钥扫描(v1 不做)
14 Linux 沙箱 单独 loop:bwrap + 容器内验收;完成前 bash/MCP 继续 fail closed 沙箱 profile 的技能只读白名单、网络出口策略
15 管理 API 的 multipart 限制 Gin 默认 + 显式 MaxBytesReader;技能包错误走 116105,工具上传走 116118(D36) 与反向代理的上限对齐
16 「找技能」要不要真是一个 LLM 子代理 已拍 2026-10-28:不存在「找技能」这个角色——skill_search 整个不做(D28),manager 只能从目录里挑技能 —(已拍)
17 manager 能不能自己读正文 已拍 2026-10-28:能,而且这是翻案(D19/D29)——manager 自己 use_skill 读正文并声明执行、自己执行、照着正文建看板任务(拆几刀由它定,D32),任务一建好正文就换成 marker(D33),压缩时任务不折;只想看看内容用 read_skill,看板一行不多 —(已拍)
18 技能执行要不要独立角色 已拍 2026-10-28:不要(D29)——取消内置 skill agent,没有「能不能再委派」这个问题;技能是知识不是任务,知识留在主上下文 —(已拍)
19 技能执行角色的模型与工具池 已拍 2026-10-28:该角色不存在(D29)——由 manager 承担,用它自己的池(基座池 + 三个技能工具);普通子代理的池里剔除这三个名字(§2.8 第 2 条) —(已拍)
20 需要用户输入的技能怎么跑 已拍 2026-10-28:manager 直接问(D29)——它本来就是根助手,ask_user 在池里,追问帧就在父 run 帧面(doc/47 §165);不需要为技能另设例外 —(已拍)
21 命令认哪些子命令 v1 只认 add;list/find/remove/update/check/init/use 一律 116109 是否把 remove/update 映射到 DELETE/覆盖安装(会多出两个写入口,默认不开)
22 私有仓库 不做;只公开源(GitHub/GitLab/直链),要私有就先本地打包上传 是否支持租户级 token——等于把凭据放进引擎主机与出口请求
23 仓库里怎么找技能 只认「目录里有 SKILL.md」(任意深度);平铺 .md 只在单包上传里认 是否也优先扫 .claude/skills/**、.agents/skills/** 这类约定目录(快,但只覆盖一部分仓)
24 「整条消息=命令」的拦截点 worker 装配前分流(不调模型、无 usage) 是否改成前端发送前识别——规则要复制到前端,且 curl 打不到,默认不做
25 仓库归档的下载上限 下载 ≤50MB、解压总量 ≤200MB、条目 ≤20000;单技能仍按本表第 10 条 数值待定;防的是大仓拖垮副本,不是防 zip bomb(那是第 10 条)
26 安装审计 v1 不建审计表:管理 API 走现有访问日志;对话内安装看 run_questions 那行(args 是程序解析出的事实、answer 是程序写回的安装结果、decision 是人的批准/取消、answered_at 是时间、tool_call_id 对回 journal),再配 skill_rows.updated_at/updated_by 是否需要「谁在什么时候装了哪个版本」的可查表(会引入技能版本概念)
27 skill_rows 表名与列 按 §4.7;唯一键 (tenant_id, name) WHERE valid(部分唯一索引:同一个桶内生效名字唯一,同名 invalid 行可以并存;系统行落在空串桶里。2026-10-28 第十三轮从 (name) WHERE valid 按租户收窄,§4.3、D7、§4.7);「系统行 vs 某租户行」跨桶,索引管不到,由写入口与 rescan 显式比 列名与 doc/40 的码表同批落
28 孤儿目录认领 安装遇「目录在、无行」→ 认领补行,不返回 116106 认领时若内容和安装包不一致,是否以安装包为准覆盖
29 系统技能怎么同步到 PVC 部署流程(CI / Job / 运维脚本)写 system-skills/,来源是仓库或发布产物,不能是运行中的 Pod 镜像;应用只读。同步完成后用系统管理员账号调一次 rescan,失败则发布重试或回滚 用 Job、CI 步骤还是 kubectl cp;rescan 放在 Job 里还是 CI 的发布后钩子
30 PVC 访问模式 远期部署前提,不阻塞现在:本地 / 测试环境单机就是本地目录;上多副本时要求 RWX、挂载点一致 若只能 RWO,先换存储,技能表的事往后放
31 技能资源读取上限 单文件与正文同一条判据:≤16,384 token(cl100k)且 ≤64KB,超了报 116115、不截断——同一把计数器、同一个判定函数(2026-10-28 第十三轮拍;用户口径「附件也收到 1 万字左右,要写大表就拆成几份」) 原 256KB 的两条后果都成立:①一条大资源会把这场 run 里其它工具结果的还原额度全挤掉(trim 从最新往回还原,compact.go:638-682);②夹子是静默的。拍「对齐正文」之后:单条资源最多吃掉 trim 预算(32,768)的一半,挤占被限死;上限同时成为作者规则——大表拆成几份 references/。「资源也走整块替换」不单独做:D30 只保护 read_skill/use_skill 的正文,资源在 16k 以内、被裁时夹子给「头 1/4 + 尾 3/4」,损失有界。「分块读」不做:read_skill_file 保持「一次一个文件、参数只有 name+path」;真遇到超上限的大文件,manager 对自己那份技能根有 bash 只读,可用 sed -n '1,400p' 分段取——bash 输出有自己的 32KB/流 上限且明说截断,不为少数情况给工具加参数。另:安装期不扫资源大小(大资源可能从不被读,正文才是每场必进上下文的)
32 目录里是否保留 location 保留(展示与追溯),读取入口不按它——正文靠 read_skill/use_skill({name})、资源靠 read_skill_file({name, path}),都按名字定位(§2.2、§2.3)。⚠️ D25 之后 manager 的 bash 准读本场用过的技能根(§9-34),所以它对自己那份技能用得上这个路径(cat 得到);隔壁技能与其它角色都够不到 去掉则目录只剩 name+description,断掉 UI 上「装在哪」的追溯
33 目录体积撑不住时怎么办 v1 无解——这是已知天花板,不是不做(D28 的代价):只剩作用域 + 禁用两把闸;技能数上百时,每个技能一行描述进每一次模型调用 将来要不要第三把闸(换发现接口/分层目录/按需生成目录)——本期不排期,等真的撑不住再说
34 bash 放行的粒度:整个技能根,还是「本场 run 已加载的那个技能根」 已拍 2026-10-28(第十二轮,D25 + D35):只放行本场 use_skill 成功过的技能根(工具根不在这个收窄里——按租户常开,第十四轮 D36)——ctx 里挂一个 run 内可变的盒子(foldBox 同款,midfold.go:57),use_skill 成功时 append;续跑与跨 run 由 D35 按看板补回(有任务就补、没任务就要求重新 use_skill)。禁用的技能报 116107、进不了盒子,禁用闸因此仍然是结构性的;盒子每场从空开始,装配普通子代理时整个去掉(§4.4 第 5 步)。第一版「放行整个技能根」作废——它让 cat 绕开折后留痕(D31)、任务归属(D32)、禁用闸三条(正文上限 D26 基本被 bash 自己的 32KB 输出上限兜住,更严且会明说截断;<skill> 整块替换 D30 享受不到但暴露面小) 对照表见 §4.4「复审发现」;性质是审计与策略洞,不是安全洞。代价:白名单随 run 增长;恢复多一次装配期查询(D35);read_skill_file 不受影响(它不走 bash)
35 rescan 遇到「盘看起来是空的」怎么办 已拍 2026-10-28(第六轮):不做 force——它两头都不成立。人点重扫被拒时不知道盘为什么空(只能瞎点确定);部署流程同步完出厂技能是自动调它的,那里没有一双手能点确定,撞上这个拒绝就卡死发布(§9-29 的「失败重试或回滚」需要它是真失败,不是要人签字)。改成两条结构性口径:①系统技能根读失败 → 中止整次重扫,什么都不改(os.ReadDir 返错是唯一可靠的「我没看到盘」信号);租户根与项目根不存在则是正常状态(这个归属下还没装技能),视同空、不中止,安装入口本来就会建目录;②系统技能根读出 0 条 → 不删系统层任何行,只把条数写进 roots[]。理由:出厂技能由发布同步保证非空,所以「读出来 0 条」只能是盘坏了或挂错了,不能当成「系统技能都没了」。租户根 0 条是正常的(新租户就是空的),照常按盘删行,不特判。③「租户重扫删掉系统技能行」这个隐患由比对范围按归属过滤从根上排除(§4.7):租户级重扫只比对 scope='tenant' AND tenant_id=$1 的行,系统行不参与 不需要 force、不需要新端点、不需要确认弹窗。判断权交给人,前提是信息也在人手上——roots[] 让运维一眼看到「系统技能根:0 条」(§6.1)。代价:系统技能根真被清空时,表里的行要等盘修好后再扫一次才回得来——但那时 read_skill/use_skill 本来就全在报「找不到」,根因会先喊出来
36 跨 run 续做时「第 3 步」怎么定位 已拍 2026-10-28(D34):看板是会话内的续做正本——TaskList 带「上一场」未完成行及说明(description 升级为「这一步具体做什么」),写回执与 task 帧都不带;用户说的「第 N 步」= 看板的 #N,正文只回答「怎么做」(重读 read_skill) —(已拍)
37 缺依赖时谁来补 已拍 2026-10-28(第十四轮,D36;用户指示「我觉得在方案里面解决这个」):给租户开一个工具上传口——POST /api/tools 传单个可执行文件 → <tenant>/tools/<name>/bin/<name>,只有 owner/admin 能传;只做文件级校验(名字/预留名 bash/sh/env/非空/≤128MB/租户额度),不执行不探测;staging → .trash → rename,共用 D27 那对锁。同时把两条边界分开:工具根按租户常开(所有角色可读、各前缀 bin 前置进 PATH),技能根仍按 D35 按证据收窄;requires 只服务安装期检查与 UI 提示 后置(方案内阶段):多文件前缀(解释器整包)上传——启动条件是有真实的「必须多文件落的工具」要装;现在没有这种实例。工具也没有版本历史与回滚(§12)
38 bash 围栏能不能出网(技能脚本要装依赖、调 API) 已拍 2026-10-28(第十五轮,D37;用户指示「记得补上 agent 可以访问网络」):放开出站(sandboxProfile 加 (allow network-outbound)),不开入站;同一条 profile 管 manager bash、子代理 bash、技能脚本与租户 MCP,四者一起生效。代价明写:围栏不再阻止「下载并执行」,但下载物只能落项目根,系统目录与 <tenant>/tools 仍只读,工具根不会因此长出工具;自动装依赖仍不做(D11)。Linux 无沙箱仍 fail closed
39 技能要的工具根本没装,什么时候知道、谁来补 已拍 2026-10-28(第十五轮,D38;用户问「skill 如果执行到某个工具无法执行因为根本没安装,怎么办」):use_skill 成功结果里现查 requires,标签带 requires="…" missing="…"(不缓存、不阻断);模型见 missing 就停下说明「请管理员上传或运维同步」,不自行安装、不重试;read_skill 不带这两个属性;真跑到 command not found/Operation not permitted 由 bash 原样报出(D11、§7)
40 围栏外的工具为什么报 EPERM 而不是「没装」 已拍 2026-10-28(第十六轮,D39;用户裁定「报错当然越准确越好」):子进程 PATH 按 sandboxReadRoots 过滤——继承来的每一段 EvalSymlinks 后只保留落在 /usr /bin /sbin /opt /System /Library /dev /private/var、项目根、<tenant>/tools 之下的,其余丢掉;工具根 bin 仍前置;requires 的 LookPath 用同一条 PATH。于是 ~/.pyenv/shims 那类报 command not found(不是 Operation not permitted),模型才会想到「没装,请管理员上传」;绝对路径点名的仍 EPERM。过滤表与 profile 共用一份,不做两份

10. 施工顺序草案(不是 todos)

真正开工会先写 tmp/52-技能/planning.md + todos.md 交审。下面是依赖顺序,第一个 action 必须能被 curl 打到。

拍 做什么 为什么在这个位置 验收第一行
A 存储骨架:建 skill_rows + rescan + GET /api/skills(含一个示例系统技能;验收时把它放进 <workspace>/system-skills/ 后调 rescan,这是测试夹具,不是运行时步骤) 先证明盘上的目录能进表、能从表读出来;后面每一拍都靠它 curl -X POST /api/skills/rescan 再 curl /api/skills 看字节
B 角色闭环:目录只注入 manager + manager 自己的三个技能工具(read_skill/use_skill/read_skill_file)+ 普通子代理剔除技能工具 + bash 沙箱白名单按角色注入(D25:根 run 挂一个 run 内可变的只读盒子、use_skill 成功时 append,装配子代理时整个去掉;粒度按 §9-34 只放本场用过的)+ toolCallId 技能真正被用起来的最小闭环,同时把「普通子代理技能盲」这道结构闸落下来;toolCallId 与帧字节同批改 curl 起 run,拉帧看 manager 的 use_skill 调用与 <skill> 包裹的正文;另起一个普通子代理,确认它没有技能工具、且它那条 cat <技能根>/SKILL.md 的 bash 被沙箱拒绝(Operation not permitted)
B2 任务归属与折叠留痕:run_tasks 加 skill_name 列 + TaskCreate 时按本 run 最近一次 use_skill 盖戳 + TaskList 返回带 skillName(D32,程序不代建任务);TaskList 的会话续做读(D34:带「上一场」未完成行及 description、回执与 task 帧不带、description 的 jsonschema 文案升级)+ 执行权恢复(D35:装配时按 run_tasks.skill_name 把已有任务的技能根补回 bash 盒子——依赖本拍的 skill_name 列,所以跟 B2 走、不跟 B);技能记录块管线(提取/继承/渲染/钉块)+ <skill> 包裹 + trim 整块替换(D30、D31) 正文是说明书、任务是替身——这一步不落,正文不敢进主上下文(压缩时正文副本会丢,步骤只能回盘重读);D34 让这个替身跨 run 可读(用户续做时说的是看板的 #N),记录块则是「折了也知道用过它」的兜底(与「程序代建任务」不是一回事:那一条已作废,§3-D32) curl 起一场 run 让 manager 用技能做件事 → 拉帧看 kind=task 帧里带技能来源;再发一条消息起新 run,看 TaskList 输出里有「上一场」段(§11.2);再逼出一次 compact → 摘要末尾出现 <!-- tako:skill-ops v1 --> 块且块里有技能名
C 写路径:安装/更新/删除 API + 校验(含正文 token 判据 D26)+ 写行 + 库级分布式锁(D27:全局共享 + 租户独占,全量重扫全局独占)+ 技能页 UI(先只认 multipart 上传) 人得能装;校验错误要在 API 上可验,不靠 UI 猜;写行是「装配不扫盘」的前提;锁必须和第一个写路径同拍上,晚一拍就有一拍是裸奔的 curl -F 上传坏包看 11610x,装好后 curl /api/skills 看新行;两个 curl 并发装同一个技能,看一个 409、一个成功(库锁串行);换第二个租户的账号并发装,看两边都立刻成功(不该排队,§11.3)
C2 来源解析:preview、install 吃 {source}/{command};仓库候选识别与选择;抓取安全边界(SSRF/zip slip/上限) 用户手里的入口是来源串与命令串;先有解析与预览,下一拍的对话拦截才有东西可调 curl -d '{"command":"npx skills add <repo> --list"}' /api/skills/preview 看候选;curl -d '{"command":"npx skills remove x"}' 看 116109
C3 对话入口:整条消息=命令的装配期分流 + skill_install 提议并挂起(run_questions.kind=install)+ 确认端点里由程序执行安装(D24) 模型不能握写盘的手;粘贴即装的可靠路径不在模型里;人的点击是唯一的授权动作 ① 起 run 发一整条 npx skills add <repo> --skill x,看 assistant 回复与「无 usage 帧」;② 再起一场让模型调 skill_install → 帧面出现 pending 的 kind=question(name=skill_install),且技能根没有被写;③ curl 用 viewer 账号答 approve → 111203;④ 用 admin 答 approve → curl /api/skills 出现新行、skill_rows 有新行、skills_changed 已发、tool_result 是安装结果;⑤ 同流程答 cancel → 没有新行、tool_result 是「用户取消了安装」;⑥ 提议后手工删掉 staging 再 approve → tool_result 是「安装已过期」
D 依赖声明与 LookPath 装完知道能不能跑;与 C 的响应形状一起定 curl 装带 requires 的包看 dependencies
E 作用域(只 manager)+ 禁用 + skills_changed 事件 控制目录体积的第一、二把闸;事件避免多标签页不一致 curl PATCH + 拉目录/列表
F 工具写面:GET/POST/DELETE /api/tools + staging/.trash + 额度预留 + 工具根常开(profile 只读 + PATH 前置,D36;F1/F2/F3 已落 2026-10-28) 依赖 B 的沙箱落点与 C 的 staging/锁形状;排在 D/E 之后——先有「检查告诉你缺什么」,才轮到「自己补得上」,也不与目录/禁用那条闸抢同一批文件 curl -F name=hello -F file=@./hello /api/tools → GET /api/tools 有条目、盘上 0755;再起 run 让 manager 跑 hello,看输出
G 收口:trash 清扫 + 行/盘对账(rescan 在锁内跑)+ 文档/契约收口(G1 已落 2026-10-28) 最后补耐久性;此时已有真实读写路径可测 curl 连续更新同名技能,再 rescan 看没有重复行;并发 rescan 与安装不互踩(技能不消失)

每拍 ≤80 行 diff,做完停下汇报,不连续推进。

10.1 施工提醒(2026-10-28 第二轮复审加;第十轮按当时代码重核修订;不改方案,写 todos 时照抄)

会红的测试——同批改,别当意外

  1. runlog payload 加 toolCallId(§8.2-1)→ 两个既有测试的 payload 逐字比对会红:TestEndRunLandsTurnRows(store_test.go:900,断言在 :958、:962)与 TestEndRunLandsDelegationRows(:981,断言在 :1059、:1062)。同文件的 TestEndRunLandsUsagePayload(:1081)只看 payload 非空/为 NULL、不逐字比,加字段碰不到它——别把它也改一遍。采集链路不用动:TurnEntry 已经有 ToolCallID(types.go:91)、tool_call 行的 id 就在 tc.ID 里——只给两个 payload 结构体各加一个字段(store.go:404 的 toolResultPayload、:421 的 toolCallPayload)。
  2. Frame 加 ToolCallID,omitempty 不会红:两处逐字节测试(contract_test.go:68 的 frames 响应、:89 的 usage 帧)钉的帧都不带这个字段,omitempty 下字节一字不变;kind 词表(:162)也不变——§8.2-1 这条说对了。
  3. run_tasks 加 skill_name 列(D32)→ 建表与 RunTask 结构体(tasktools.go:29-44)同批改;看板相关单测若逐字段比对也要跟。

要同批改的文档

  1. doc/19-v6/19v6-04-验收-curl.md:112 与 :150 两处散文写着「run 以 usage 帧收尾」。§6.6 的「整条消息=命令」run 没有 usage 帧——这与机器真源不冲突(scripts/acceptance/expected.json 里 usage 出现 0 次;帧断言只有 frame_kinds_contains: ["start","terminal"];done 判据是「存在 terminal 帧」,server.go:1012、:1099),但散文要改,否则散文与实现各说一套。
  2. 帧字节与 runlog payload 变了 → 19v6-01、19v6-04、expected.json 同批(§8.2-1 已写);业务码进 doc/40 §4(§6.2 已写)。新增的管理端点本身也是契约字节:A 拍落 POST /api/skills/rescan 与 GET /api/skills 时,就要把用例与期望字节登记进 scripts/acceptance/expected.json 和人读版 19v6-04,别只写在 doc/52 §11.1 里——AGENTS.md 的规矩是「两台机器各管一段」,只写散文等于没有。

落点:哪些是现成的,哪些要新增

  1. 沙箱白名单已落地(B3b,2026-10-28),下面这段是按当时代码写的「要改什么」,保留作历史:sandboxProfile 原只收一个 root(sandbox.go:53),真实调用链是 newBashTool → runBash(bash.go:82)→ startBash(sandbox.go:117)→ 写 .sb 时调 sandboxProfile(workspace);租户 MCP 走 sandboxWrap。落地后的形状:签名是 sandboxProfile(root string, extraReadRoots []string),startBash 写 profile 时传 skillReadRoots(ctx),盒子在 skillbox.go(withSkillBox/skillBoxFrom/skillReadRoots),根 run 装配在 worker.go 的 withTaskBox 之后写入、普通子代理在 runSubagentGuarded 换成空盒;sandboxWrap 传 nil。每条根都过 sandboxRealPath(EvalSymlinks 后 Abs,sandbox.go 那条注释讲的就是「/tmp 是 /private/tmp 的软链」这个坑)。工具根不进这个盒子(第十四轮,D36):<tenant>/tools 按租户常开,F 拍在 startBash 里直接拼(§7 第 3 条),两类根都只读。
  2. 「此来源在本会话中未出现」那行要查的是整个会话的 user 原文,不是一个 ctx 键能给的:现有 ctx key(principal / scope / workspace / taskBox / foldBox / journalTarget / planGate / runProfile)都不带历史文本。别新挂 ctx 键——读源是现成的:run_model_messages WHERE session_id = ? AND role = 'user'。两个容易踩的地方:① 不要复用 ModelMessages(pgstore.go:740),它带 compacted = false(:743),正好把你要查的旧历史滤掉;被压行的 text 仍在库里(:738 注释:压掉=不回模型输入,只在库里留档)。② 会话 id 也不用新键,workspaceFrom(ctx).SessionID 已有(scope.go:56-73);当前这轮的用户原文也不必等 run 跑起来,它在 AcquireRun 的事务里就落了行(store.go:268,seq=1, role='user')。它是提示不是闸:判中了不额外拦截,判不中只是少一行文案。
  3. 权限判定不在工具层,在答案端点的 kind=install 分支(HTTP 层,principal.Role 是字符串 owner/admin/member/viewer)。答案路由是全员可用的(成员要能答自己 run 的追问与方案),所以不能给路由挂 RequireTenantRole,要在分支里判角色(roleRank(p.Role) >= roleRank("admin"),auth.go:575-587 是同一把尺),不够回 111203。但这条分支今天到不了:answerQuestion 先调 denyRunWrite(questions.go:214),它只放 accessOwner(server.go:561-573,非 owner 一律 403「只有本人能修改」),而 D24 的形态是「成员提议、管理员点头」——管理员去看别人的 run,在这里就被挡了。所以 kind=install 必须在 denyRunWrite 之前分出来:档位用 denyRunRead(accessRead 够,server.go:576 起),角色再按上面那条判。这是改既有权限语义的一处,动手前先请用户拍。 另两件同批:① cancel 现在不存在——questions.go:33-34 只有 approve/revise,且 decision 白名单在 :199-204 就把它 400 掉了;要加 questionDecisionCancel 常量,并按 kind 放行取值。② CAS 的顺序:AnswerQuestion(:112-115)是把 answer 一起写进 answered 的,而 waitForAnswer(waittools.go:259-261)一看到 answered 就把行里的 answer 当 tool_result 交回去——所以不能「先 CAS 再装」。正确顺序是:取锁 → 重读仍是 pending(挡「已答过」,锁挡并发)→ 装 → 最后 CAS 把结果字符串写回。反过来写的话,装失败时那一轮的工具结果是一句占位,重答又被 409 挡死。 还有一处列语义要写明:run_questions.Args 的既有含义是「工具原始参数 JSON」(questions.go:37-40),kind=install 把它存成 resolver 的输出——这是按 kind 变化的列语义(kind=plan 时 question 列存方案全文,已是同类先例),要在 questions.go 的注释里写清,免得后来的人以为前端拿到的是模型原始参数;同批更新 doc/47 的 kind 词表与帧面说明。
  4. 禁用落 skill_disables 表(§9-1),不要碰租户 config 那段 JSON:那段文本只认四个已登记字段,读(json.Unmarshal 进结构体,product_store.go:818-819)和写(整列覆盖,:847-855)两道闸都会把第五个键静默吞掉。建表与 skill_rows 同批;PATCH /api/skills/:name 只写这张表,DELETE 的事务里同时删 skill_rows 与 skill_disables 两边的行(§4.5)。
  5. 技能侧的计数器自己构造(main.go 那个只在 -compact-window > 0 时造,:179-183;关掉压缩时是 nil),安装路径与 read_skill/use_skill/read_skill_file 共用这一把(第十三轮把资源也收进同一判据,§9-31);别把 nil 传下去,也别在 nil 时静默跳过字数判据(§2.3)。-compact-window 的 0 保留(调试逃生口),施工时不要顺手把这个取值删掉。
  6. trim 认 <skill> 块的挂载点是 trimCandidate 的收集循环(compact.go:638-649)。判据用工具名、不要嗅内容:候选里的 assistant 行带 ToolCalls、tool 行带 ToolCallID,照 renderFold 那段(compact.go:729-735)先建一张 id→name 表,命中 read_skill/use_skill 的 tool 行既不计入 total(:644)、也不进还原队列(:653 那个循环)——它们不占别人的还原额度,也不该拿通用的「原 N 字节」marker(trimMarkerFormat,:604),而该换成 D30 的指针 marker;原文只在 runlog.payload.output 里留档。
  7. D33 的每枪重写只有一处落点:midfoldHandler.BeforeModelRewriteState(midfold.go:537)。它今天有五个出口(box == nil :539、休眠 :543-546、救援采用 :552-560、未超线 :581-583、折完 :603),所以把重写放在最上面(只吃 state.Messages),五个出口自动都带上——比在每个出口前各调一次稳,也顺手满足「压缩关掉也要执行」(D33 不是压缩档,休眠分支照样要吃)。两条硬要求:① 放在数输入之前(:570-580),否则数的是没改过的形状;② 判据全在 state.Messages 里、不查库:assistant 行的 ToolCalls(形状 compact.go:765-771)给出 id→name,tool 行的 ToolCallID 对回去,命中 read_skill/use_skill 之后再看有没有更晚的 assistant 行调用 TaskCreate。子代理那条 agentFoldHandler.BeforeModelRewriteState(midfold.go:680)不要动——普通子代理没有技能工具,改它只多一次空跑。
  8. fold 渲染的挂载点是 renderFoldRow(compact.go:757-790):它已经收着 names(id→name,renderFold 在 :729-735 建好),case "tool" 里先按名字判 read_skill/use_skill,命中就直接写 D30 的 marker 行,不要走 truncateRunes(:783)——否则正文会被截成 2000 runes 塞进摘要,模型读到半截说明书,比 marker 更误导。
  9. mh 的存储形态变了(D33 的代价):tool 行的 Text 可能是 marker,不再是工具输出全文。现有单测里若有「落库行文本 = 工具输出」这类断言,要改成「= 模型实际看到的形态」;runlog 的 payload.output 仍是发射时的全文——这两处别当同一个东西。

拍粒度

  1. B 拍与 C 拍都超「≤80 行 diff」,写 todos 时再拆。B 拍至少含:目录注入(instructionFrom(ctx) 之后)、三个技能工具(read_skill/use_skill/read_skill_file)、普通子代理剔除四个保留名(再加 skill_install,§2.8 第 2 条)、sandboxProfile 改签名 + 盒子(压在 §9-34 上)、Frame.ToolCallID + runlog payload + 上面第 1 条那两个会红的测试。C 拍至少含:三个写端点(install/update/delete)、校验(含 D26 的 token 判据)、写行、库级锁、技能页 UI。skill_install 不在 B 拍也不在 C 拍:它只提议、不写盘,属 C3(§6.6)。

零碎落点(第二轮之后陆陆续续拍的,都已收口)

  1. .trash 清扫的张力已收口:只在安装/删除的锁内做,启动时不扫盘(§4.6 第 4 条),.staging 同一条规则、按 mtime 24h 判定。所以「进程启动不写盘」(§4.7)这条口径保持干净;对话内安装挂起太久 → staging 被清 → 确认时回「安装已过期」(§6.6)。(批准那一枪不清自己的源:正在被 rename 的 staging 豁免,见 §4.6 第 4 条——否则先清扫后 rename 会把自己要搬的目录删掉,用户读到裸 ENOENT 而不是「安装已过期」。)(rescan 的空盘保护见 §9-35,已按第六轮拍定——只对系统技能根:系统根本身不存在或读不出来才整次中止;租户根与项目根不存在=这个归属还没装技能,视同空、照常按盘删行;系统根读出 0 条只报数不删行。别把「根不存在就中止」写成对所有根都成立——那会让新租户的第一次 rescan 直接失败。)
  2. 技能脚本的工作目录是项目根,不是技能目录:bash 的 cmd.Dir = workspace(sandbox.go:149),而 workspace 来自 activeRoot(ctx, …)(bash.go:82)——所以 python3 /srv/.../skills/pdf/scripts/build.py 里的相对路径(open("template.html"))会以项目根为基准解析,不是脚本所在目录。脚本自己 Path(__file__).parent 就对;正文若让脚本读同目录的数据文件,得在正文里写清这一点。写 use_skill 的验收用例时别用「脚本读同目录文件」的写法当正例。
  3. 子进程 PATH 要改,不只是白名单(§7 第 4 条):bashEnvWhitelist 现在把引擎的 PATH 原样拷进子进程(bash.go:27、:93-97),所以租户工具根里的 python3 永远抢不过宿主的。落点:runBash 组装 cmd.Env 时把 <tenant>/tools/*/bin(跳过 . 开头的目录)拼在 PATH 最前面;同一批目录必须同时出现在 sandboxProfile 的只读白名单里——拼进 PATH 却不在白名单里,执行照样被围栏拒。第十四轮起这条不再依赖技能盒子(工具根按租户常开,D36),所以「拼 PATH 的集合」与「白名单的集合」都只有一个来源:工具根目录本身。注意不要把宿主 PATH 整条删掉——技能可能要用 /usr/bin 里的 sed、gzip;要删的是围栏读不到的那几段(第十六轮,D39):逐段 EvalSymlinks 后按 sandboxReadRoots 前缀过滤,~/.pyenv/shims 这类丢掉。过滤表与 sandboxProfile 的只读根必须是同一份(抽成 sandboxReadRoots),否则 profile 放行了、PATH 却把它删掉(或反过来),又会回到「找到但 EPERM」。requires 的 LookPath(D11/D38)也走这份过滤后的 PATH,否则同一台机器上「检查说找到、bash 说没装」。
  4. D34 的落点:TaskList 多渲染一段「上一场」,另外两个出口不许带。taskBoardView(tasktools.go:149)同时喂三处:newTaskListTool 的闭包(:290-291)、taskReceipt(写操作回执,:173)、emitTaskFrame(页面看板,:188,帧的 Text 在 :196)。D34 只改第一处、且改在闭包里,别给 taskBoardView 加参数——那是三个出口的共用体,加开关等于逼另外两处也写一遍「不带」。新增段落只列未完成行、每行带 description;box.session 就在手上(:250 的用法)。查询走 run_tasks_scope 复合索引(tenant_id, session_id,tasktools.go:32/:35)、排除当前 run_id、按 created_at DESC 找最近一个有任务的 run,再取它未完成的行(doc/41 §5.1 有原句 SQL)。文案两处要改:taskCreateInput.Description 的 jsonschema(:222 现写「可选补充说明」)与 TaskCreate 的工具说明(:242-243)——都补「这一步具体做什么;下一场靠它续上」。验收见 §11.2「跨 run 续做(D34)」。
  5. skill_rows 的唯一索引是 (tenant_id, name) WHERE valid(§4.7;2026-10-28 第十三轮从 (name) WHERE valid 收窄)。三个坑:①别写成不带条件的三列唯一——rescan 把「同名但冲突」的条目记成 valid=false 时插不进去,而 §4.3/§4.7 都要求 invalid 进表,§11.1 那条「同名的 invalid 行能入库」会当场红;②别把 tenant_id 漏掉——漏掉就是两个租户装同名互撞 116106,也就是这一轮修的那个 bug;③这条索引管不到「系统行 vs 某租户行」(不同桶),安装与两个 rescan 必须在锁内各查一次(§4.7「为什么按租户收窄」)。A 拍建表时就按这个写,别等验收才发现。
  6. TaskCreate 盖 skill_name(D32)与 use_skill 放行技能根(§9-34)是同一件事实的两个用途——「本 run 最近一次 use_skill 是谁」。落点是一个 run 内可变的盒子(形状抄 taskBox:tasktools.go:60-79,已经带 mu),里面存技能名 + 该技能的只读根;use_skill 成功时覆盖写,两处读。bash 的 PATH 前置不在这个盒子里(第十四轮,D36):工具根按租户常开,见 item 18。别塞进 taskBox:普通子代理也在用它(researcher 从基座池继承四把看板工具,worker.go:247-258),而技能盒子必须在装配子代理时整个删掉(agents.go:351)——删掉一举满足「技能盲」「不盖戳」两件事,删漏一项就漏一项。(工具根不在盒子里,所以子代理照样有工具,这是第十四轮要的效果,见 §11.2。)不要改成「查 runlog 最近一条 use_skill」——runlog 在 EndRun 才写,run 进行中查不到。反向单测同批:read_skill 成功 → TaskCreate → 行里 skill_name 为空;只 use_skill 不建任务 → run_tasks 一行都没有(这是 §11.2 那条「读了不建任务」的机器断言)。
  7. D27 的两级锁是「连接级」的,不是「事务级」的(2026-10-28 第十一轮)。pg_advisory_lock_shared / pg_advisory_lock 的存活范围是一条连接,不是一次事务——从 pgxpool 里每次 QueryRow 可能换一条连接,于是 unlock 落在另一条连接上,锁永远不释放(要等那条连接被池回收)。所以实现必须是:conn, err := pool.Acquire(ctx) → defer conn.Release() → 在 conn 上 SELECT pg_advisory_lock_shared($1) / pg_advisory_lock($2) → 干活 → 同一 conn 上 pg_advisory_unlock*。事务级变体(pg_advisory_xact_lock*)随事务自动释放、不会漏,但本方案的「搬目录 + 写行」跨文件系统与 PG、不是一个事务能包的,所以用显式 unlock + defer(崩在中间由连接断开/池回收兜底,PG 在会话结束时释放该会话所有 advisory lock)。 键的取法:全局键一个固定常量;租户键用 hashtext(tenant_id) 或 hashtext('skill:' || tenant_id) 折成 bigint(pg_advisory_lock 吃 bigint)。两级要按固定顺序取(先全局共享、再租户独占)——全量重扫只取全局独占,所以不存在环;同租户两个写都先拿 shared 再抢独占,也不会死锁。别把顺序写成「先租户再全局」:那样全量重扫持独占等租户锁、租户写持租户锁等共享,就是死锁。
  8. rescan 的扫盘必须在锁内(2026-10-28 第十一轮):锁外扫完再进锁写,等于拿一份过期快照去删行——扫完到取到锁之间别人新装的技能会被当成「盘上没有」删掉,正是 §4.7 那个静默消失的场景换了个入口。租户级扫盘只是本租户根(+ 项目根)的一次 WalkDir,毫秒级到百毫秒级,包进锁不影响体验;全量 rescan 扫三处根、可能跨很多租户,是这条规则里唯一会长时间持锁的路径——它是运维低频动作,可接受,但要在返回 roots[].count 里让运维看见扫了多少(§6.1)。真正要挪出锁外的是网络 IO(抓取仓库、下载 zip),它们发生在 .staging 里,本来就不冲突。

A 拍的护栏(写 A 的 todos 时照抄)

  1. 三条都不是新规则,是不写就会卡在第一条验收上的事:① -system-skills-dir 旗标要真落地(默认 <workspace>/system-skills,§4.2),并且本机验收前先把 system-skills/ 目录建出来(可以是空的)——按 §9-35 口径①,系统根读不出来按「盘没挂上」处理,整次重扫会失败;② rescan 跳过以 . 开头的目录(§4.2 最后一条)——.staging/.trash 就在技能根底下,不跳会被当成两个坏技能写进 invalid;③ 扫描范围=比对范围,按 scope/tenant_id 过滤后再比(§9-35 口径③),返回体带 roots[](§6.1)。唯一索引 (tenant_id, name) WHERE valid 与「系统行 vs 租户行」那三处显式检查(item 20)也在这一拍。

开工前的闸

  1. B 拍开工前没有待拍项了(2026-10-28 第十三轮):§9-31 已拍——资源与正文同一条判据(16,384 token / 64KB)、超了报 116115、不截断,不做整块替换、不做分块读,所以 B 的资源验收字节是确定的(§11.1 那条「正文超限 → 116116」对资源就是 116115)。§9-34(第十二轮)与 §9-35(第六轮)也已拍。B 可以写 todos 了。

  2. D35 的恢复查询落在 run 装配,与 D34 的「上一场」同一个选 run 规则(2026-10-28 第十二轮,属 B2 拍)。三条实现要点:① 位置在盒子建好之后、第一枪之前——worker.run 里 newFoldBox 那一带(worker.go:488),与 withWorkspace(:524)同批;续跑走同一条路(RunResume 也进 run),所以不要在 resume 分支里另写一份。② 查询只取「有任务」的技能名:SELECT DISTINCT skill_name FROM run_tasks WHERE tenant_id=? AND session_id=? AND run_id=? AND skill_name <> '' AND status <> 'deleted'——新 run 的 run_id 用 D34 选出的那个「上一场」(item 19 的 SQL 复用),续跑用自己的;走 run_tasks_scope((tenant_id, session_id),tasktools.go:32/:35)。③ 补之前逐项重判:skill_rows 里该名仍 valid、skill_disables 里没有它、技能根与 requires 工具根 os.Stat 都在——任何一条不成立只跳过这一条,不能让装配失败(盘上少一个技能不该让整场 run 打不开);跳过不影响「模型还能自己 use_skill」。反向单测:上一场有 pdf 的任务、本 run 没调 use_skill → 装配后盒子里有 pdf 根;把 pdf 禁用后再装配 → 盒子里没有它,且 bash 跑它的脚本被围栏拒。

  3. 工具写面(D36,属 F 拍):三处别写错——①POST /api/tools 必须先 staging 再 rename,且 name 是用户给的字段、不是上传的文件名(浏览器可能把路径带进来);拼 filepath.Join(toolsDir, name, "bin", name) 之前按白名单校验 name,别只靠前端。②PATH 前置与 profile 只读取自同一个目录:tenantStorageRoot(workspace, tenantID)(media.go 已有)下的 tools/,两边都先 EvalSymlinks;枚举时跳过 . 开头的目录——否则 .staging/<rand>/bin 会进 PATH,半成品在 rename 之前就被 exec。③额度用 ReserveStorage(filetools.go:74-104),不要自己 directoryBytes 算一次就开写——两个并发上传会同时通过。另外:工具没有表,列表就是 os.ReadDir,别顺手加一张 tool_rows——那会把 rescan 那套盘表漂移问题引进来,而工具目录里没有需要解析的正文。

  4. 沙箱放宽网络(D37)改的是共享 profile,不是 bash 专属:sandboxProfile 同时喂 startBash(sandbox.go:140)与 sandboxWrap(:81,租户 MCP)。所以加 (allow network-outbound) 会让租户 MCP 一起出网——这是想要的(MCP 连不上网本就是缺口),但验收要把两条路都打一遍:bash 里 curl 成功、租户 MCP 的 server 能连出去。别只加 (allow network*) 图省事:它连 network-inbound 一起放开,等于把围栏里的监听端口暴露到宿主网络。DNS 若仍失败,先补 (allow system-socket) 再怀疑别的。验收口径见 §11.2「技能脚本能出网」;internal/runengine/contract_test.go 不覆盖沙箱行为,这条只能活体验。


11. 验收清单

11.1 管理 API(curl,逐字节)

11.2 运行链路

11.3 文件与删除

11.4 UI(Playwright)

11.5 收尾命令

cd yk-tako-eino
PATH="$HOME/sdk/go1.27.0/bin:$PATH" go test ./internal/runengine
PATH="$HOME/sdk/go1.27.0/bin:$PATH" go vet ./internal/runengine
cd web && npm run typecheck && npm run build

改了帧字节 → 额外跑 scripts/acceptance/assert_contract.py 与 check-expected.sh。


12. 明确不做


13. 所以这解决了什么

它把「流程知识」从 system prompt 和记忆里拆出来,变成可安装、可禁用、可作用域、可审计的本地文件:平时只在 manager 的 prompt 里占一行目录,要用时整篇进 manager 的上下文(2026-10-28 翻案,见 D29),读完按正文建看板任务——正文是说明书,任务才是要完成的东西,所以同一场 run 内压缩时正文可以折、任务不折;跨 run 的续做靠看板(D34:TaskList 带上一场未完成行与说明),需要「这一步怎么做」时再重读一次正文(§2.5 第 2 条、§2.9);普通子代理全程技能盲;安装时就把格式与依赖问题挡住,用户从 GitHub 复制的 npx skills add … 能直接粘进来、被解析成同一套原生安装(不在引擎主机跑任何安装器代码),项目删除不会误伤真身,覆盖更新不会让 run 读到半截文件。对话里装技能是「提议」,不是「执行」:模型把要装的包摆成一张卡片(事实由程序解析、渲染),人点了才由程序写盘(D24)——模型读到的文字永远变不成一次写。

「读和用不被切开」是结构性的,不是约定(2026-10-28 翻案,D19/D29):技能是知识不是一类特殊任务——所以没有内置 skill agent,manager 自己 use_skill 读正文、自己执行,中间不隔一层只转述不执行的委派;只想看看内容就 read_skill,它不建任何东西。「能执行」也是按证据给的,不是按历史给的:bash 的只读白名单是 run 内状态,use_skill 成功才长出来,续跑/换一场 run 要接着做则按看板里已建的 skill_name 补回(D35:「已经生成 todos 就继续跑,还没生成就重新加载」),没建过任务的技能不会被历史顺手放进来。但「正文一直留在上下文里」不是承诺:建出看板任务后正文即换成 marker(D33),追问细节时重调 read_skill;逐字原文是低概率需求,需要时 grep 文件即可,不为它把正文钉住。而**「普通子代理技能盲」仍然是结构性的**:它们的池里没有 read_skill/use_skill/read_skill_file,装配时也去掉了 bash 对技能根的放行(§2.8、§4.4)——子代理继承的是 manager 的 ctx,去掉是必需的一步。「读一下说明书不是一件工作」也是结构性的:看板行只由 manager 自己的 TaskCreate 产生,程序从不代建(D32),所以「用户问这个技能干什么」不会在看板上留一条没人收尾的行。

代价是:多了一个管理面、一张 skill_rows(每处写盘配一次写行)、一个 rescan 兜底、一个「命令解析 + 安全抓取」的入口、一个工具上传口(缺的 ffmpeg 团队自己补,不用等运维,D36)、放开的出站网络(技能脚本能下载、能调 API,代价是项目根里可以出现下载来的可执行文件;工具根与系统目录仍只读,D37)、一把按租户分级的库级锁(否则并发写会让技能无声消失;租户之间并行,只有全量重扫独占全局)、一条挂起行与一张确认卡(对话内安装,复用 run_questions 与答案端点,不新造机制,D24);正文进了主上下文,所以多了两条约束——正文有上限(16,384 token / 64KB,D26)与折叠时会留记录(程序侧钉块,D31,不靠 LLM 自觉);还有四个明说的缺口——①不做技能搜索,所以目录体积只有两把闸可控、技能数上百时会撑(§2.7、§9-33);②「Linux 上能读不能跑」(单独开 loop,不在这篇里假装解决);③资源上限已收到与正文同一条判据(16,384 token / 64KB,第十三轮拍,§9-31):单条资源最多吃掉 trim 预算的一半、超了当场 116115 不截断——代价是作者必须把大表拆成多份,且超上限的大文件只能靠 bash 分段读(sed -n,输出有 32KB/流 上限并明说截断);④bash 的放行范围虽然已经收到「本场 use_skill 过的技能根」(第十二轮,§9-34/D35),代价是白名单随 run 增长、续跑与跨 run 要按看板补一次;隔壁技能与子代理仍然够不到(§4.4「复审发现」)。工具根是这条收窄之外的第二个集合(D36):<tenant>/tools 按租户常开、所有角色(含普通子代理)都能用——正因为它收的是可执行文件、不是说明书,收窄它只会让派下去的重活跑不动。