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详情端点——名字按租户视界解析(查不到与「别的租户的同名」同回 404116001,存在性不跨租户泄漏)、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与 runlogtool_call/tool_resultpayload 加同名字段(帧与历史行同一套配对键);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/resulttoolCallId成对、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 一律被判「命令在围栏外」(503111411)。落点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/…、按 Pythonrealpath存进 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.md60,500 字节全文返回、bytes与wc -c一致,big.md71,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 在入口 400111002(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 403111203),未登录 401111102;禁用与恢复各发一条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(超了 413116118)→ 名字白名单^[a-z0-9][a-z0-9-]{0,63}$+拒bash/sh/env+拒空文件(400116117)→ReserveStorage先占额度(不足 429113001)→ 写.staging/<rand>/bin/<name>0755 → C1 同一把锁内「旧前缀进.trash/<name>-<ts>+ rename」。上传/删除只给owner/admin(viewer 403),列表所有成员可读;删除前名字过同一套白名单(..会拼成租户根);不存在回 404116119;成功后发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后下一场 runhello→ 退出码 127command 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依赖旁一个「上传 <名字>」,点后切到工具区并预填命令名、聚焦输入框(SkillsViewemitupload-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.pycore 112/112、全量(含 model tier)138/138;spotcheck.sh37/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.RenameENOENT,用户读到安装失败: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→「查看技能文件: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、改一次要发版;塞记忆是「事实召回」,不是「按需展开的步骤」。
技能要解决的就是这件事:平时只让模型看见一行「有这个技能、什么时候用」,真要用时再把整篇正文递进去。
不做的后果,用六个会真实发生的失败讲:
- 全量正文进 prompt。团队攒到 100 个技能,每个正文 3 千字,每次模型调用先付 30 万字上下文;而且改一个技能文件要重启引擎才生效。→ 必须有「目录/正文」两层:目录只放名字与描述,而且只进 manager 的 prompt;正文只在被选中时才进上下文(
use_skill一次),读完由 manager 自己按正文建看板任务(程序不代建,D32);普通子代理两样都看不到。 - 截断目录。如果程序把描述切到 250 字,模型看到「当医生提供或更新称谓、地区、医院、科室…」却看不到后半句「或要求停用、删除订阅数据时使用」,该用时就不用;作者也不知道自己哪句被切了。→ 目录不截断;成本靠减少条目来控制,而减少条目的手段只有两把闸——作用域(
skills:/exclude_skills:)与禁用。不做技能搜索(2026-10-28 拍,理由见 §3 D28),所以目录体积是个已知天花板:技能数上百时,每个技能一行描述进每一次模型调用,涨到撑不住时没有第三把闸兜底(§9-33 记录了它)。 - 装完才发现跑不了,而且没处补。技能正文写「运行
ffmpeg -i raw.mp4 …」,这台机器没有ffmpeg。模型调 bash 才拿到command not found,这一轮 token 已经烧了;更难受的是知道了也补不上——工具根在共享 PVC 上,只有运维能往里放文件,普通团队要么等,要么放弃这个技能。→ 两件事分开做:①安装与check时检查声明的依赖,缺什么当场告诉用户(D11);②给租户开一个工具上传口——owner/admin在管理页自己传一个可执行文件进<tenant>/tools/,不用等运维(D36,§7)。仍不自动装:不跑pip/apt、不替用户下载二进制。 - 技能真身放在项目目录里,项目一删就没了。项目删除会
os.RemoveAll项目目录,再逐个删会话目录(yk-tako-eino/internal/runengine/product_api.go:315、:324)。技能真身若在项目里,别的项目通过符号链接引用它,删项目后链接全断;而链接指向项目外又会被现有围栏挡住(filetools.go:41、:49的rejectSymlinkEscape只允许落点在 workspace 内)。→ 真身放租户根,项目里只放受控链接;围栏要加「技能只读白名单」。 - 覆盖安装时读到半截文件。直接往正在被读的技能目录里解压,某个 run 可能读到新旧混合的
SKILL.md。→ 先写 staging,再整体换目录;旧目录进 trash,延迟清理。 - 用户手里的东西是命令,不是 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`,再按下面的步骤写入……name:技能标识;必须与目录名(或平铺文件名)一致。description:作者写的「什么时候用我」,不是程序摘要。目录里原样展示(只做 XML 转义与空白折叠,不截字)。requires:可选的依赖声明,元素是 PATH 里的可执行名(§7)。- 正文:整篇
SKILL.md去掉 frontmatter 后的内容;references/、scripts/等资源由正文按需引用,tako 不预读。 - 平铺形态只有正文,没有资源:
<name>.md自己就是技能根,所在目录不是它的资源目录(否则能读到隔壁技能的正文)。要带资源就打成目录形态。 - 未知 frontmatter 键:v1 忽略,不报错;不把它们塞进目录。
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):
read_skill({name})读正文(只读):按名字查最新行,打开行里记的入口文件(目录形态<name>/SKILL.md,平铺形态<name>.md),把去掉 frontmatter 的正文整篇返回。没有任何副作用——不建看板任务、不设执行状态、不动 bash 白名单;它就是「翻一下说明书」。use_skill({name})读正文并声明执行:返回同一份正文;差别只在副作用——程序把「本 run 在用这个技能」记进 run 级状态,manager 随后自己TaskCreate时,行上带这个技能名(D32)。要办事就用它,不要先read_skill:先读后用会让正文进两次上下文(D33 下一枪才把两处一起换掉)。read_skill_file({name, path})读资源:path是相对该技能根的路径,调用方自己选文件。
三个工具的参数都全必填,没有可选字段。 前两个的地址是「技能本身」,第三个是「技能 + 调用方选的文件」——这不是「前两个没有 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 读不到技能真身」不再是目标——它本来就该读到正文。真正的边界变成两条:
- 普通子代理仍技能盲:它们的池里没有
read_skill/use_skill/read_skill_file,也没有<available_skills>目录;它们的 bash 也看不到任何技能根(§4.4 的「委派时去掉」)。 - 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 行进执行者的活跃上下文。所以上限不能按字节猜,要按引擎真实的上下文机制算:
- 引擎默认声明窗口 256,000 token(
cmd/yktako/main.go:59-61defaultCompactWindow);fold 线 =window − min(window/5, 16384)= 239,616 token(compact.go:138)。 - trim 预算 =
clamp(window/5, 8192, 32768)= 32,768 token(compact.go:601常量trimBudgetMax、:610-619toolTrimBudget)。这是「所有工具结果加起来」在裁剪时能占的额度。 - 裁剪算法(
compact.go:638-682):全部工具结果先换 marker → 预算内从最新往回还原原文 → 第一条放不下的给「头 1/4 + 尾 3/4 预览夹」(compact.go:694-695;比例是对二分搜出的保留量keep分,不是对原文长度分),更老的只剩 marker。
由此得出两条必须写死的规则:
- 一条正文若超过 trim 预算,长 run 一旦触发裁剪,它必然被换成 marker 或缺中段的夹子,而且没有任何信号告诉执行者内容被切过(要重读得靠它自己想到);同时这条超大结果会挤掉其它工具结果的还原额度——trim 从最新往回还原,第一条塞不下的拿夹子,比它更老的全部只剩 marker。窗口多大都救不了:trim 预算是 32768 的硬上限(
compact.go:601、:615-616,1M 窗口也是),而一条 256KB 的正文或资源 ≈ 6 万~9 万 token,永远大于它(这也正是第十三轮把资源上限收到与正文同一条判据的理由,§9-31)。这是静默降级,比 provider 回 400 难查得多(两条代价的完整说明见 §2.5 第 4 条)。 - 所以正文上限必须小于 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 里只算一次。没有锁、没有句柄、没有失效通知。真实情况只有两件事:
- 目录是派生视图:run 装配时从
skill_rows读一次(system + 本租户,扣掉禁用与 manager 作用域),拼成字符串放进这场执行尝试的sys。没有目录文件、没有全局缓存、没有锁。 - 字符串进
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 的闸不靠「模型守规矩」成立。这条要写死,否则后来会有人拿目录做鉴权。
- resume 按新的执行尝试处理(本方案取):崩溃后续跑会重新装配、重算目录;同一
runId的两次尝试可能看到不同目录——续跑发生在几分钟后,文件可能已经变了。 - 没有技能时不输出空标签,manager 的 system prompt 里不出现这段。
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),但不改存储 |
在这个前提下,技能在压缩期有四件事要定:
正文进的是 manager 的上下文(2026-10-28 翻案,§3 D29),不是子代理的。所以根 run 的 compact 会碰到它。
正文被折掉不要紧——看板任务不折。执行进度在
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 就继续跑,还没生成就重新加载。折掉时要留下「用过它」的记录。manager 的目录在 system prompt 里,compact 不重建 system prompt,所以技能名一直在——但**「这场用过它、正文已折」这条执行状态不在目录里。做法是程序侧钉块**(§2.9),不靠 LLM 写进摘要。
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 两个成本控制
- 作用域(只作用于 manager):根助手的规格(tenant agent 的 md)里写
skills:(只给这些)或exclude_skills:(从全集减去这些),二选一,沿用tools:/exclude_tools:的口径(parseAgentSpec同写即拒载)。普通子代理没有目录,这两个字段对它们无意义;子代理规格里写了直接拒载——拒在入口:JSON 新建/更新与 md 导入回 400111002,出厂规格在 seed 时记日志跳过该条(E1;装配期永远见不到这两字段,所以没有「静默忽略」这一态)。显式写inherit放行:GET 回读总带这一份,客户端原样 PUT 回来不该被拒。 - 禁用:管理端把某个技能从「有效集」里拿掉,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 自觉):
- 目录只拼进 manager 的 system prompt。普通子代理的
instruction里没有<available_skills>这一段。 read_skill/use_skill/read_skill_file/skill_install只进 manager 的工具池。普通子代理装配时从继承池里剔除这几个名字;tools:里写了也挑不到。它们是保留名(与tool_search同一路数)。skill_install是提议工具——它只解析并挂起等人确认,写盘在确认端点的处理器里(§6.6),所以「子代理没有这把工具」等于「子代理连提议都不能提」。- 普通子代理的 bash 看不到任何技能根。沙箱 profile 只放行项目根 + 系统路径(
sandbox.go:60-73),租户技能根与系统技能根不在其中;装配子代理时还要显式去掉根 run 带来的那条放行(§4.4、D25)——否则子代理继承的是 manager 的 ctx。 - 技能根任何角色都没有写权限:文件工具的根是项目目录(
scope.go:75-80、:99-105),技能根只以只读方式进 bash 的 profile。
两条边界:
- manager 能问用户,也能做方案审批——它本来就是根助手,
ask_user/submit_plan/enter_plan_mode都在它池里,不需要为技能另设例外。技能要用户输入时,manager 直接问(追问帧就在父 run 帧面,doc/47 §165)。 - 重活仍然派给普通子代理。技能正文若要求「读 40 份文件汇总」「跑批处理」,manager 把它作为一条任务派给 coder/researcher——
researcher之所以存在,正是因为主线程读 40 个文件会把主上下文灌满(doc/23)。技能本身不新造一套并行机制:要并行拆活,由 manager 在外面拆。
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 不带这两个属性(纯读正文、零副作用)。
四条理由:
- 正文要原样进消息历史——JSON 会把换行转义成
\n字面量,折叠器不好定位。 - 属性里带
name:摘要模型看到的工具结果截到 2000 runes(compact.go:783),但name在最前面 → 截断了也还记得用的是哪个技能。 - 正文里的
<&要转义(代码片段、HTML 会撞结构);目录那边已有转义做法(§2.2),正文这边新增。转义顺带买到一件事:正文里不可能出现真的</skill>,所以按内容标记认块是安全的(D30,fold 与 trim 两条路都靠它)。代价(2026-10-28 用户拍:要的就是「看起来一致」):正文里的代码片段在上下文里是<div>这种形态,模型往产物里抄时要自己还原;验收因此比的是反转义后逐字一致(§11.2),不是原始字节。 - 给「整块替换」一个边界:一旦要它走(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;运维同步或租户上传)
- 系统技能是出厂内容。版本库里的副本在
yk-tako-eino/skills/,但它只是发布同步的来源,不是运行时真源;运行时真源只有 PVC 上的system-skills/。发布流程(CI / 一次性 Job / 运维脚本,§9-29)把那份副本同步到卷上,之后进程只读卷。镜像不承担技能分发——镜像每次发布整体替换、每个副本各有一份,进程不读镜像里的任何技能路径,任何 Pod 也不许在启动时往卷上写技能(否则旧 Pod 重启会把旧内容盖回共享卷)。技能根通过-system-skills-dir指定,默认<workspace>/system-skills;团队与项目技能根由-workspace推导,不另设旗标。系统技能根是 PVC 上的普通目录,不是软链;软链只出现在项目层,由 §4.4 的白名单约束。 - 团队技能是主要落点。一个员工 = 一个项目的形态下(doc/42),团队就是租户;技能是团队资产。
- 项目技能是可选层。它适合「只对这个项目有效」的流程;项目删除时随之消失是预期行为。真身不要放这里再由别的项目引用——要共享就放团队层,项目里放链接(§4.4)。
- 目录名以
.开头(.staging、.trash)rescan时一律跳过。
4.3 名字在租户视界内唯一(不做三层覆盖)
2026-10-28 第二轮复审改:旧口径是「合并顺序 system → tenant → project,同名后者覆盖前者」,改成不做跨层同名。第十三轮再把「唯一」的范围从全表收到「一个租户的视界」:视界 = 系统层 + 本租户的行(含本租户的项目层行);别的租户的行既看不见、也不参与判断。安装、对话里 skill_install 的解析期、rescan 撞到视界内已有的同名技能,一律按冲突处理:安装回 116106(解析期就能判出来,不用等人点确认),rescan 写 valid=false + reason(写清与哪一层撞名),不静默挑一个。每个视界里每个名字只有一条,source 字段告诉 UI 它来自哪层。
- 为什么:三层同名会让
/api/skills/:name指不到确定的一行(GET/PATCH/DELETE三个端点都要靠名字定位),还会让「删掉上层」静默暴露下层。具体故事:管理员禁用了团队层的pdf(这份坏了)→ 后来删掉团队层那行 → 按 §4.5 又必须把pdf从禁用名单里摘掉 → 系统层同名的pdf立刻出现在目录里并生效 → manager 开始用那份出厂pdf,而管理员的本意是「这个技能别用」。名字唯一后,这条陷阱和 API 歧义一起消失。 - 用户的正规做法(也是唯一做法):觉得自己的版本比出厂的新,就换个名字装(例如
pdf-v2),再把出厂的pdf禁用。「用哪一份」由禁用与作用域(skills:/exclude_skills:)两把闸控制,不由覆盖控制。 - 同一层内撞名(目录形态与平铺形态撞名、或两个目录同名)同样是安装错误,写
valid=false的行。同租户的跨层撞名(租户层 vs 本租户项目层)同一处理——它们落在同一个桶里,数据库唯一索引直接挡(§4.7)。 :name端点按视界解析:GET/PATCH/DELETE /api/skills/:name与POST /api/skills/:name/update都只在「系统行 + 本租户行」里找那唯一一行,不许裸 name 全表查——名字已经不再是全表唯一,裸查会改到别的租户的行。删行同理:DELETE ... WHERE tenant_id = ? AND name = ?,清skill_disables也带tenant_id(§4.5)。- 先占名字的那一行生效,后来者 invalid:租户装
pdf时系统层已有pdf→ 当场116106(安装期就能查到,用户立刻换名);反过来,租户先装了pdf、之后发布流程同步出厂pdf→rescan把系统那行记成valid=false。这是发布流程要检查的一件事:rescan返回体里的invalid[]非空就说明有出厂技能被租户占了名字,运维要么改名,要么联系租户改名——不检查的话,出厂能力会静默缺一块。出厂行全集群只有一行,占名的是哪个租户都一样,所以看见了就赶紧改、别拖。
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 沙箱 profile(
sandbox.go:60-73)只放行「项目根 subpath(可读写)」+「系统路径(只读)」;租户技能根<workspace>/tenants/<tid>/skills/与系统技能根<workspace>/system-skills/是项目根的兄弟,两者都不在放行范围里。文件工具的根也是项目目录(scope.go:75-80、:99-105)——默认状态下,技能真身对任何角色都不在地址空间里。 - 翻案后的口径:manager 自己读正文并执行(D29),它本来就通过
read_skill/use_skill拿到全文,所以给它 bash 放行它声明过的那一个技能根不新增内容泄漏——新增的能力只是「能跑这个技能自带的scripts/*.py」(执行技能必需),以及读它自己的references/;隔壁技能仍然看不见(放行整个根会连带放开cat,见下面的「复审发现」)。反过来,普通子代理必须仍然看不到技能根:它们继承的是 manager 的 ctx,所以要去掉。 - 实现落点:要改一处签名,不是「现成」(2026-10-28 第二轮复审按真实代码改写;旧文说「落点现成」是错的)。真实调用链是:
newBashTool的闭包 →runBash(ctx, activeRoot(ctx, workspace), …)(bash.go:82)→startBash(ctx, workspace, command, timeout, requireSandbox)(sandbox.go:117)→ 写临时.sb文件时调sandboxProfile(workspace)(sandbox.go:140)→sandbox-exec -p。而sandboxProfile的真实签名是func sandboxProfile(root string) string(sandbox.go:53)——单入参,没有任何可扩展的 ctx 形态。要动的是这几处:sandboxProfile(root string, extraReadRoots []string) string:多拼若干条(allow file-read* (subpath …))。每条同样要先filepath.EvalSymlinks解析真实路径——sandbox.go:50-52那条注释讲的就是这个坑:seatbelt 的 subpath 走真实路径,macOS 的/tmp是/private/tmp的软链,不解析就匹配不上,agent 会连自己项目里的文件都读不到。startBash内部从 ctx 取白名单再传给sandboxProfile——它本来就收 ctx,所以runBash与newBashTool的签名都不用动。scope.go加一对withSkillReadRoots/skillReadRootsFrom,与既有的withWorkspace(scope.go:66,由worker.go:524调用)并排。- 根 run 装配时写入这个键——挂的是一个 run 内可变的盒子(不是静态清单):起点为空,
use_skill成功时 append 该技能自己的根;续跑/跨 run 装配时按 D35 从看板补回已有的那几条。工具根不走这个键(第十四轮):<tenant>/tools按租户常开,startBash里直接拼进 profile 与PATH(D36、§7)。 - 装配普通子代理时显式去掉这个键(
assembleSubagentTool,agents.go:351)。这一步是必需的:子代理执行时的 ctx 直接从父 run 派生(agents.go:338-345把同一个 ctx 递给装配与内层),父 ctx 里的 workspace / principal / scope 它全看得见——不去掉,「普通子代理技能盲」当场破功。补一句事实核对(2026-10-28):子代理不是没有 bash——agents/coder.md的tools:里就写着bash,只有researcher.md用exclude_tools: [bash]把它排除。所以「技能根只对 manager 可见」这条边界完全落在这一步装配代码上,工具池不兜底。 sandboxWrap(cmd, root)(sandbox.go:81,租户 MCP 用)不动:MCP 不需要读技能根,保持只放行租户存储根。
- 于是:manager 的 bash 只看得见它这场声明过(或按 D35 接着办)的那些技能根(只读),能
cat自己那份references/x.md、能跑自己那份scripts/*.py;隔壁技能与普通子代理的 bash 都看不见任何技能真身。这条口子只读不给写。工具根不在这个收窄里(第十四轮,D36):<tenant>/tools是租户环境,任何角色(含普通子代理)的 bash 都能读、bin都在PATH前面——它里面没有技能正文,收窄它换不来任何东西(§7)。 - 跑起来的脚本继承围栏,但围栏内是宽权限(2026-10-28 补,用户问「不怕运行了其他不授权目录的吗」):seatbelt 作用在进程树上,
python3和它 fork 的子进程都在同一个围栏里——所以「脚本自己去找别的目录」不会发生,围栏外照旧Operation not permitted(~/.ssh、别的租户目录、全盘都在外面)。但围栏内的权限要说明白:项目根可读可写((allow file-read* file-write* (subpath root)),sandbox.go:71),系统路径只读且很宽(/usr/opt/Library/private/var等,:70),出站网络开着、入站不开(2026-10-28 第十五轮,D37:profile 加(allow network-outbound))。于是运行一份技能脚本的准确含义是:第三方写的代码,以「能改用户整个项目、能出网下载与外发」的权限在跑,但写不到围栏外。这与今天 bash 的权限是同一档(模型本来就能改项目文件),差别只在代码出处;装的时候我们拒绝执行任何东西(§7「明确不做」),因为那时没有围栏、跑的是引擎进程本身的权限——这条不对称是有理由的,不是遗漏。 - Linux 无沙箱时 bash 仍 fail closed(§9、D16)——这条口子只在有沙箱的机器上开。
复审发现:放行「整个技能根」会让 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 原子安装 / 更新
- 上传包先落到
<tenant skills>/.staging/<random>/,在 staging 内完成全部校验(zip 路径穿越、符号链接项、文件数、总字节、frontmatter、正文 token 上限 D26)。 - 校验通过后,把现有同名目录 rename 到
.trash/<name>-<unixnano>/,再把 staging 目录 rename 成正式名字。 - 失败就把 staging 删掉,正式目录没动过。
.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 审计补拍。)- 锁按「改哪块地方」分两级(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)。 - 并发安装同名:两个请求都可能把旧目录移走,后到的 rename 可能失败;失败方回 409,不重试覆盖。不用 flock(NFS 语义未测)——串行化靠第 5 条那把库锁,不是文件系统锁。
- 读侧窗口:两次 rename 之间路径可能短暂不存在。三个技能工具遇到「找不到」时重试一次,仍失败就返回结构化错误。正在读的旧文件即使被 rename 也能读完(POSIX 已打开的 fd 不受影响),坏情况只落在「换目录那一瞬才开始读」。
- 行在盘落定之后写:rename 成功才 upsert
skill_rows。崩在两者之间会留下「目录在、行不在」——这个技能暂时不进目录;安装入口遇到同名目录但没有行时认领它(补行),不返回116106;rescan也能补。
4.7 存储模型:文件是正文,表是目录
前提是部署形态:引擎跑在容器里,业务文件全部落在共享 PVC 上,所有副本同时挂(RWX,如 SFS/NAS 一类),挂载点一致。这条决定了文件边界:
- 镜像只装程序:二进制、前端静态文件;容器层可写但随 Pod 销毁,不承载任何业务状态。进程运行时不读镜像里的任何业务路径,也不借镜像层做持久化。构建上下文若把仓库的
skills/带进镜像,那是死文件,没有任何代码读它(部署仓可用.dockerignore排掉)。 - Pod 挂卷:滚动发布时新旧 Pod 挂同一块卷、同一个挂载点;
-workspace与-system-skills-dir都指向卷上的路径(后者默认就落在前者里面)。 - 系统技能由发布流程写卷:CI / 一次性 Job 从仓库或发布产物同步
system-skills/,不进 Pod 启动流程;运行中的 Pod 不写它。技能正文、租户目录、媒体产物同样只在卷上。 - 状态在 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上加一列disabled:出厂技能的行是全集群一行(scope=system、tenant_id空串),租户 A 把pdf标禁用会让所有租户一起禁用。禁用是租户级动作,挂不到共享行上。 - 塞进租户的
config那段 JSON:那段文本只有四个已登记的格子(modelRef/mcpServers/secrets/sandbox,product_store.go:777-782),读和写各有一道闸把它挡掉,两头都不报错——读是json.Unmarshal进四字段结构体(product_store.go:818-819),没登记的键读不出来;写是json.Marshal之后整列覆盖(product_store.go:847-855),下一次谁改模型配置就把它抹掉。 - 所以单独一张两列的表:
(tenant_id, name)做主键,重复禁用撞主键即无事(闸就是主键);删技能时DELETE ... WHERE tenant_id = ? AND name = ?一次清干净(名字只在租户视界内唯一,别的租户可能有同名行,必须带租户);它和skill_rows在同一个库,删技能那件事的事务里就能一起提交——§4.5 那条「删除要顺带清禁用项」因此不再是「记得跑去另一个存储清一遍」,而是同一事务里的第二条语句。
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 的行(下一段),和别租户的安装本来就不碰同一批行,两者并行不出错。
写点与崩溃窗口:
- 安装/更新:先 rename 落盘,再 upsert 行(§4.6 第 7 条)。崩在中间 → 盘上有、表里没有 → 技能暂时不可见;安装入口认领无行的同名目录,
rescan也能补。 - 删除:先 rename 进
.trash,再删行。崩在中间 → 表里有、盘上没 → 目录列着、调用回116001;rescan会删掉这个行。 - 改正文而没走 update(手工改文件)→ 目录还是旧描述,
read_skill/use_skill读到新正文;要一致就rescan。
没有启动扫描:进程启动不读技能根、不写 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 行 | 折叠后无法恢复正文 |
关键实现点:
- 目录注入在
instructionFrom(ctx)之后、且只对 manager 做。绑定助手(tenant agent)会用规格正文覆盖h.system;如果先拼目录再被覆盖,manager 就看不到技能。正确顺序是:先取基础 system(默认或绑定规格),再拼本次 run 的目录,再拼快照。普通子代理的Instruction走spec.Prompt + 快照段,不拼目录。 - 目录只按 manager 的一份生成(
skills:/exclude_skills:只在这里生效)。不存在「每个子代理一份过滤后的目录」——普通子代理没有目录。 - run 装配不扫盘:只读
skill_rows与skill_disables两张表,目录字符串不缓存。盘上的变化要进目录,必须经过写入口或rescan(§4.7);三个技能工具查行后打开文件,所以「表里有、盘上没有」会以116001暴露出来,不会静默。 - 读工具按调用时刻查行,不查目录快照:快照只决定「模型看见了什么」,不决定「能读什么」;行决定路径,文件决定字节。新装/删除/改名的生效时机见 §2.4 的表;作用域不是权限闸。
- 执行权要跨 run 补,但只按看板补(D35)。bash 盒子是 run 内状态(
worker.go:488起手新建),续跑与新 run 都从空开始;装配时按run_tasks.skill_name查一次(索引run_tasks_scope=(tenant_id, session_id)),命中的技能把根补回去,manager 才能「接着上次继续跑」。没建过任务的技能不补——那说明还没开始办事,凭「上次用过」恢复等于把执行权发给一场手里没正文的 run。补之前逐项重判当前状态(valid、未禁用、盘上还在),禁用绝不靠恢复绕过116107;恢复只给执行权,正文仍要read_skill(D34)。 - 程序不判断技能有没有「索引」:只读入口正文;正文里写「先读 references/fields.md」是作者的选择,tako 不做结构识别、不预读资源。
- 读取不经过模型。三个技能工具的 handler 都只做「解析 → 读文件 → 返回正文」,不调用 LLM、不摘要、不改写;正文原样进上下文,由 manager 自己执行。
- 正文是说明书,任务是替身(D32)。看板上的行只有 manager 自己调
TaskCreate才存在——程序不代建:read_skill零副作用,use_skill只把技能记进 run 内的执行态(用来给后续TaskCreate盖skill_name),两者都不写run_tasks。「用户问这个技能是干什么的」因此不会在看板上留下一条永远没人收尾的行(旧口径的鬼任务,§3-D32)。任务住在run_tasks(PG 表),compact 只动 mh → 同一场 run 内正文可折、任务不折;跨 run 的续做也走看板(D34:TaskList带「上一场」未完成行及说明,§2.5 第 2 条)。用户说的「第 N 步」是看板的#N,不是正文的 step 号——定位用看板,要「这一步怎么做」再调read_skill({name})。 - 正文用完就走(D33)。每枪重写一次(
BeforeModelRewriteState,与滤思考同处、在数输入之前):某条read_skill/use_skill的 tool 结果之后(行序更晚的 assistant 行)出现了TaskCreate调用 → 下一枪把该技能的<skill>块换成<skill name=… folded="true" reload="read_skill" tasks="见看板"/>。判据只看 assistant 行的ToolCalls。压缩关掉(-compact-window=0)时同样执行——它不是压缩档。连带后果:mh 里存的是 marker(模型实际看到的形态),逐字原文在盘上、发射时的全文在 runlog 的payload.output(§2.5 存储层一行)。 - 资源走
read_skill_file,不返回技能根。path以技能根为基准(目录形态是.../<name>/;平铺形态没有资源,根就是那个.md文件);工具解析后必须仍在该技能根内(绝对路径、..、EvalSymlinks后跳出的一律116001)。不把dir交给执行者,避免它绕开这个入口用文件工具拼路径。 - bash 的可见范围按角色注入(D25)。沙箱 profile 每次调用现算(
sandbox.go:140);根 run 的 ctx 挂一个 run 内可变的只读盒子——use_skill成功时 append 该技能的根,续跑/新 run 装配时按看板补回(D35);装配普通子代理时整个去掉(agents.go的assembleSubagentTool处一次去标记)。普通子代理的 bash 看不到任何技能真身(§2.8 第 3 条、§4.4)。工具根不进盒子:<tenant>/tools按租户常开、所有角色都有(D36),见下一条。 - 正文进上下文有上限(D26)。
read_skill/use_skill返回前用 cl100k 量正文(≤ 16,384 token 且 ≤ 64KB 字节),超了报116116——不让它走到「长 run 裁剪时被换成半截」那一步(§2.3)。安装期用同一判据,避免装得上、读不得。 - 写路径按租户分锁、全量重扫独占(D27):普通写取「全局共享 + 本租户独占」,全量
rescan取全局独占;锁内只做搬目录与写行(rescan另含本地扫盘),网络抓取与校验在锁外(§4.6 第 5 条);写入口唯一(§6.1)。 - 正文进上下文用
<skill>包裹(D30):成功走 XML 原文、失败走 JSON 信封;D33 的每枪重写、fold、trim 三条路认出它都整块替换成指向看板的记录,不走头尾夹、也不截成 2000 runes 进摘要(§2.10)。 - 折叠时留下技能记录块(D31):从被折行的 assistant 行
tool_calls提取,钉在摘要末尾(§2.9)。compact 不碰 DB——任务号交给看板回答。
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 权限
- 安装/更新/删除/禁用:租户
owner/admin(与成员管理同档,server.go的RequireTenantRole已有先例)。 - 工具上传/删除(D36):同档
owner/admin;工具列表所有成员可读。普通成员能看见「缺ffmpeg」,但不能往共享卷上放可执行文件。 rescan:租户owner/admin只能重扫本租户根与项目根,并且只比对本租户的行(扫描范围=比对范围,§4.7);系统技能根只随系统管理员(RequireSystemAdmin,运维账号)的重扫更新。部署流程用系统管理员账号调它。- 列表/详情:租户内所有成员可读。
- 系统技能:UI 只读;要改就复制到团队层改,不改卷上的
system-skills/(那边走走发布同步)。 - 项目技能(如果 v1 做):项目属主可管;项目删除即消失。
6.4 UI
新增「技能」页(与项目、成员同级):
- 列表:名字、描述(全文,可折叠)、来源徽标(系统/团队/项目)、依赖状态(缺依赖显示琥珀色)、启用开关、更新时间。
- 安装:一个输入框 + 「预览」按钮,三种输入都从这里进——粘来源(
owner/repo、GitHub/GitLab URL、.zip/.tar.gz直链)、粘整条npx skills add …命令、或选本地文件上传。预览卡片列候选技能的名字/描述/字节/依赖,勾选后「安装」;错误按业务码显示原文(缺描述、超长、zip 穿越、命令不支持等)。 - 安装入口对齐社区命令:
--list等于预览,-g/-a等目标参数被忽略并在卡片上给一条说明(tako 只有一个落点:租户技能根)。 - 详情抽屉:frontmatter + 正文预览(只读),路径可复制;「检查依赖」按钮;缺依赖时旁边给一个「上传工具」入口(只对
owner/admin显示,点了跳到工具区并预填这个名字)。 - 工具区(与技能页并列,D36):列表(工具名、字节、更新时间、被哪些技能的
requires引用);「上传」=一个名字输入框 + 选文件;覆盖同名给一句确认(「会替换现有ffmpeg,正在跑的 run 从下一次调用起用新版本」);删除复用ConfirmDialog。没有「检查」「探测」按钮——装的时候不执行任何东西,能不能跑由 run 里的 bash 回答(§7)。 - 安装确认卡(D24):
kind=install的提问帧渲染成一张程序卡片——来源 + ref、候选全表(未选中的也列,标出选中集)、每个候选的描述/字节/文件数/依赖、「此来源在本会话中未出现」,加「安装」「取消」两个按钮。卡片只从帧渲染,模型正文里输出的按钮不算;只有owner/admin能点,其他角色看到「已提交,等管理员确认」。 - 删除:复用
ConfirmDialog,文案写清「正在跑的对话不受影响,下一次 run 起不再出现」。 - invalid 区:显示盘上坏掉的文件与原因,不提供「修复」。
- 对话页:manager 的
use_skill调用显示成「使用技能:」卡片, read_skill显示成「查看技能:」卡片(同一份正文,两张卡片只有标题与「是否声明执行」的差异); read_skill_file结果单独一行、可展开该资源;失败显示结构化message。toolCallId用来把 call/result 配对(§8)。卡片展开的是模型实际看到的那段——按 §2.10 的<skill>形态渲染(属性里的 name 显示成标题);如果它后来被 D33 换成 marker,卡片显示的就是 marker(「已折叠,正文重读」),不是回盘重读的原文。逐字原文是低概率需求,走管理页的技能详情,不进对话卡片。
目录本身不做编辑界面——它是派生视图,改了会被安装或 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:
- 自己分词:按空白切,认单/双引号;引号不配对 →
116109。 - token 里出现
;|<>`$()或换行 →116109(URL 内的?、&允许)。 - 结果是一个结构体(
{source, kind, owner, repo, ref, subpath, skills, all, preview}),从不拼回字符串、从不交给exec。 - 服务端本地路径(
./x、/abs、~/x、file://)→116109:HTTP 面读服务端路径等于越权浏览引擎主机;本机目录请打包上传(运维手工拷目录仍然可用,rescan后进目录)。
抓取:
| 来源 | 抓取地址 | 备注 |
|---|---|---|
| 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) |
- 只支持公开源:SSH(
git@…)、ssh://、私有仓 URL、npm 包名 →116109(要私有就先本地打包上传)。 - 出口约束:只 http/https;解析出的每个 IP 都不能是 loopback/私网/链路本地/ULA/
169.254.169.254/100.64.0.0/10;解析与真正连接用同一个检查(DialContext里解析、验完直连验过的 IP,防 DNS rebinding);禁用环境代理(否则代理进程替我们解析域名,检查失效);重定向 ≤5 跳且每跳重验。不做的后果:任何能改来源的人都能让引擎去读内网服务。 - 字节上限:下载 ≤50MB、解压总量 ≤200MB、条目 ≤20000(超
116113);单技能仍按 §9-10(≤10MB / ≤200 文件 / ≤5 层 / 正文 ≤16,384 token 且 ≤64KB,D26),仓库归档解开后逐候选再核一次(整仓预算不覆盖到单个技能)。 - 归档宽容度:tar 的
pax_global_header/ PAX 扩展头是元数据,跳过(GitHub 的 codeload tarball 第一条就是它);仓库归档里的软链跳过、不落 staging(上传包里的软链仍是116105,那是 zip slip 的写法)。
从归档里找技能:
- 候选 = 归档里所有含
SKILL.md的目录(任意深度);技能名取 frontmattername。上传包里与目录名不同 →116101(目录名就是作者给的名字);仓库来源以 frontmatter 为准(真实仓库常用带前缀的名字,如skills/composition-patterns/里写name: vercel-composition-patterns),不一致只进warnings,落盘目录用name——装完目录名=名字,rescan不会判 invalid。 - 平铺
.md只在「上传包里只有一个.md」时认;仓库里不猜。 - frontmatter、1024 字符、
requires在校验阶段对每个候选跑一遍;preview 只报结果,不落盘。 - 选择:1 个候选且没指定 → 装它;多个且没
--skill/--all→116108+ 候选清单;--skill支持通配,一个都没匹配到 →116111。 - 只把选中的技能目录 rename 成
<技能根>/<name>/,其余解压内容随 staging 删除。整仓不进技能根——否则rescan会把 README、CI、package.json都当资源,还会和同名技能打架。 - frontmatter 认折行:
description:换行缩进、>/|块标量、requires:的- x块序列都要读全——只读第一行会把真实仓库里的合法技能判成「缺少 description」,整仓装不上。
落盘复用 §4.6:staging 里跑完校验 → 旧同名目录进 .trash → rename 到位 → 发 skills_changed(§8.2-9)。失败时正式目录一个字节没动。
6.6 对话里的入口
两条路径,由「消息里有没有别的话」分工。共同点是:写盘都由人的动作触发,不由模型触发。
整条消息就是命令(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);它省掉的是模型往返与输出波动,不是模型配置。命令夹在自然语言里(「帮我装 https://github.com/x/y 这个技能」):manager 有
skill_install,它是提议工具,四拍与ask_user同构(waittools.go那套:落行 → 发帧 → 轮询 → 结果回同一轮):- 解析:resolver 抓取、校验、算候选,只落
.staging/<rand>/。不碰技能根、不写skill_rows、不发skills_changed。preview:true只返回候选、不落行。 - 落行:
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)。 - 人点:前端只按
args里的结构化字段渲染确认卡——来源、ref、每个候选的名字/描述/字节/文件数/依赖、哪些被选中、未被选中的也列出来(否则模型挑一个恶意兄弟包,人以为装的是那个正经的),外加一行「此来源在本会话中未出现」。按钮打到现有答案端点(questions.go已按kind分支,:218)。 - 程序写:
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 不做扫描)。
- 解析:resolver 抓取、校验、算候选,只落
7. 依赖检查
三层,分开说:
- 声明:技能 frontmatter 里可选
requires: [python3, ffmpeg],元素是可执行名,不是包名、不是版本约束。 - 安装时检查:在接收安装请求的副本上
exec.LookPath(用 D39 那条过滤后的PATH:工具根bin在前、围栏读不到的目录已剔除),把每个依赖的found与解析到的路径写进响应。缺失不阻断安装(默认),只回琥珀色警告——因为团队可能先装技能、后补环境,也可能只在某些节点用;阻断会把「安装」和「这台机器现在能不能跑」绑死。若租户策略要求「缺依赖即失败」,那是后续策略开关,不在 v1。 - 运行时:不做启动前检查。依赖缺失时,技能正文让模型调 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 上(全副本一致)、可以只读放行。
四件:
- 目录约定:一个工具一个前缀,
<tenant>/tools/<name>/bin/<exe>(照 Homebrew / pyenv 的 prefix 形状)。 - 解析顺序:
requires里的名字先在同租户工具根找(<tenant>/tools/*/bin/<name>),找不到再走过滤后的宿主PATH(D39:围栏读不到的目录已剔除);安装期检查按同一顺序,响应里的path写明解析到的是哪个可执行文件(PATH里也是这个顺序,见第 4 条)。不问解释器「你的前缀在哪」——那要跑python3 -c 'import sys; print(sys.prefix)',等于执行一个由技能声明的可执行文件;装/装配时没有围栏、跑的是引擎进程的权限,正是 D22 拒绝的事,所以只能从路径找。 - 沙箱:工具根不随技能进盒子(2026-10-28 第十四轮,D36)——
<tenant>/tools按租户常开:startBash里把整棵工具根加进只读白名单(先EvalSymlinks,与sandbox.go:50-52同一条规矩),所有角色(含普通子代理)的 bash 都拿得到;技能根才走 §9-34 的盒子、按证据收窄。工具根在围栏外,所以天然不可写——run 改不了自己的解释器。 - 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) |
多标签页的工具列表不同步 |
三条边界写明白:
- 只做文件级校验,不执行、不探测(与 D22 同一条线):装的时候还没有围栏,跑的是引擎进程的权限,所以
file、otool -L、--version一律不调。代价是「格式不对」「架构不对」(arm64 机器上放了 x86_64 的二进制)当场看不出来——run 里 bash 会原样报Exec format error/Bad CPU type,与 D11「不假装成功」同口径。 - 这一拍只收单文件(
<name>/bin/<name>就一个文件)。整包前缀(解释器那一类几万个文件)走运维同步或软链(上一段「开发机怎么装」)。多文件上传是方案内的后置阶段,启动条件是出现必须多文件落的工具(现在没有这种实例);到时校验直接复用 C2 那套 zip 检查(路径穿越/软链/文件数/总字节)。 - 工具没有版本:同名上传即覆盖,列表只给
bytes与updatedAt。不做版本历史与回滚(§12)。
上传之后怎么被用起来: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 表达即可。
两个必须写清的边界:
- 「安装时检查通过」只是那一刻的结论。 声明的工具先查
<tenant>/tools/——那在共享 PVC 上,全副本一致;只有回落到宿主PATH时,结论才只对「那一台副本」成立。UI 显示checkedOn与path(看前缀就知道是工具根还是宿主PATH),提供check端点按当前副本重查。不要在目录或响应里写「依赖已满足」这种跨节点承诺。 - 没写
requires不等于依赖齐全。 响应里dependencies是空数组(没有独立的dependencyCheck字段:[]本身就区分不出「没声明」与「声明了空表」,再加一个字段只是把同一件事写两遍),UI 对空数组显示「这个技能没有声明依赖」,不画绿色对勾。
明确不做:自动 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="")。
toolCallId贯穿:Frame加toolCallId,omitempty;runlog 的 tool payload 加toolCallId。帧 kind 词表不变(contract_test.go:162不用改),但帧字节与 runlog payload 变了 → 同批更新19v6-01、19v6-04、expected.json。读工具的返回形态(成功走 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。技能加载列表:
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 为准。时间:runlog 的
created_at是 EndRun 时间,不能用来排「哪次调用先发生」。v1 用seq/eventOffset排序;如果 UI 需要墙钟时间,在 tool payload 里加eventAt(帧产生时的time.Now()),这是一处存储字节变更,单独拍。不做因果归因:不给后续工具打「由技能 X 导致」的标。程序无法从文本判断「模型是因为读了技能才调 bash」;硬标就是编。能说的是:这场 run 加载过哪些技能(精确)、加载发生在哪些工具调用前后(顺序)、之后调了什么工具(记录)。仅此而已。
没有 007/009 这种编号:一次加载的稳定标识就是
toolCallId;要落库审计时再带 runlog 行 id。不用「第几次技能调用」这种随批次变化的序号。不做全局计数器/自动淘汰。doc/16 §2b 的 Hermes
skill_usage自动淘汰不在本期;先把「加载事件可查」做出来,淘汰是策略问题,不是观测问题。任务看板复用:技能步骤走既有的
run_tasks与kind=task帧(doc/41),不新增技能专用任务表;run_tasks加skill_name列(D32),TaskList返回带skillName字段——「哪几条任务属于哪个技能」由看板回答,compact 不碰 DB(D31)。变更事件:安装/删除/禁用/恢复成功后
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 时照抄)
会红的测试——同批改,别当意外
- 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)。 Frame加ToolCallID,omitempty不会红:两处逐字节测试(contract_test.go:68的 frames 响应、:89的 usage 帧)钉的帧都不带这个字段,omitempty下字节一字不变;kind 词表(:162)也不变——§8.2-1 这条说对了。run_tasks加skill_name列(D32)→ 建表与RunTask结构体(tasktools.go:29-44)同批改;看板相关单测若逐字段比对也要跟。
要同批改的文档
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),但散文要改,否则散文与实现各说一套。- 帧字节与 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 的规矩是「两台机器各管一段」,只写散文等于没有。
落点:哪些是现成的,哪些要新增
- 沙箱白名单已落地(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 条),两类根都只读。 - 「此来源在本会话中未出现」那行要查的是整个会话的 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')。它是提示不是闸:判中了不额外拦截,判不中只是少一行文案。 - 权限判定不在工具层,在答案端点的
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 词表与帧面说明。 - 禁用落
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)。 - 技能侧的计数器自己构造(
main.go那个只在-compact-window > 0时造,:179-183;关掉压缩时是 nil),安装路径与read_skill/use_skill/read_skill_file共用这一把(第十三轮把资源也收进同一判据,§9-31);别把 nil 传下去,也别在 nil 时静默跳过字数判据(§2.3)。-compact-window的0保留(调试逃生口),施工时不要顺手把这个取值删掉。 - 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里留档。 - 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)不要动——普通子代理没有技能工具,改它只多一次空跑。 - 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 更误导。 - mh 的存储形态变了(D33 的代价):tool 行的
Text可能是 marker,不再是工具输出全文。现有单测里若有「落库行文本 = 工具输出」这类断言,要改成「= 模型实际看到的形态」;runlog的payload.output仍是发射时的全文——这两处别当同一个东西。
拍粒度
- 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)。
零碎落点(第二轮之后陆陆续续拍的,都已收口)
.trash清扫的张力已收口:只在安装/删除的锁内做,启动时不扫盘(§4.6 第 4 条),.staging同一条规则、按 mtime 24h 判定。所以「进程启动不写盘」(§4.7)这条口径保持干净;对话内安装挂起太久 → staging 被清 → 确认时回「安装已过期」(§6.6)。(批准那一枪不清自己的源:正在被 rename 的 staging 豁免,见 §4.6 第 4 条——否则先清扫后 rename 会把自己要搬的目录删掉,用户读到裸 ENOENT 而不是「安装已过期」。)(rescan的空盘保护见 §9-35,已按第六轮拍定——只对系统技能根:系统根本身不存在或读不出来才整次中止;租户根与项目根不存在=这个归属还没装技能,视同空、照常按盘删行;系统根读出 0 条只报数不删行。别把「根不存在就中止」写成对所有根都成立——那会让新租户的第一次rescan直接失败。)- 技能脚本的工作目录是项目根,不是技能目录: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的验收用例时别用「脚本读同目录文件」的写法当正例。 - 子进程 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 说没装」。 - 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)」。 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 拍建表时就按这个写,别等验收才发现。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 那条「读了不建任务」的机器断言)。- 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 再抢独占,也不会死锁。别把顺序写成「先租户再全局」:那样全量重扫持独占等租户锁、租户写持租户锁等共享,就是死锁。 rescan的扫盘必须在锁内(2026-10-28 第十一轮):锁外扫完再进锁写,等于拿一份过期快照去删行——扫完到取到锁之间别人新装的技能会被当成「盘上没有」删掉,正是 §4.7 那个静默消失的场景换了个入口。租户级扫盘只是本租户根(+ 项目根)的一次WalkDir,毫秒级到百毫秒级,包进锁不影响体验;全量rescan扫三处根、可能跨很多租户,是这条规则里唯一会长时间持锁的路径——它是运维低频动作,可接受,但要在返回roots[].count里让运维看见扫了多少(§6.1)。真正要挪出锁外的是网络 IO(抓取仓库、下载 zip),它们发生在.staging里,本来就不冲突。
A 拍的护栏(写 A 的 todos 时照抄)
- 三条都不是新规则,是不写就会卡在第一条验收上的事:①
-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)也在这一拍。
开工前的闸
B 拍开工前没有待拍项了(2026-10-28 第十三轮):§9-31 已拍——资源与正文同一条判据(16,384 token / 64KB)、超了报
116115、不截断,不做整块替换、不做分块读,所以 B 的资源验收字节是确定的(§11.1 那条「正文超限 →116116」对资源就是116115)。§9-34(第十二轮)与 §9-35(第六轮)也已拍。B 可以写 todos 了。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 跑它的脚本被围栏拒。工具写面(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那套盘表漂移问题引进来,而工具目录里没有需要解析的正文。沙箱放宽网络(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,逐字节)
GET /api/skills:空目录 →{"code":0,"message":"","data":{"skills":[],"invalid":[]}}。- 装一个合法包 → 列表出现一条,
source:"tenant",missing:[];rescan再跑一次不产生重复行(唯一键幂等)。 - 手工把一个合法技能目录拷进团队根 →
GET /api/skills不出现 →POST /api/skills/rescan→ 出现,source:"tenant";手工删掉一个技能目录 →rescan后从列表消失。 rescan遇到坏 frontmatter / 软链越界 →data.invalid有它,GET的invalid[]同样有,目录里没有。- 缺
description→116102;描述 1025 字符 →116103;frontmatter 坏 →116104;zip 含../→116105;重复同名 →116106。 - 同一租户视界内名字唯一(§4.3):系统层已有
pdf时装一个租户层的pdf→116106(不是覆盖);反过来,租户层先有x,再手工把出厂x拷进系统技能根 →POST /api/skills/rescan的data.invalid里有系统那行、reason指明与租户层撞名,GET /api/skills的skills[]里x仍是source:"tenant"那一条(先占名字的生效,不静默覆盖)。 - 两个租户装同名互不影响(§4.3、§4.7,2026-10-28 第十三轮):租户 A 装
pdf成功 → 换租户 B 的账号装同名pdf→ 也成功(不是116106),两边的GET /api/skills各自只看到自己那一行(source:"tenant"、path在各自租户根下);A 把pdf禁用 → B 的目录里pdf仍启用(skill_disables按(tenant_id, name)存)。 - 重扫只管自己那几处根(§4.7、§9-35):先在系统根放一个技能、用系统管理员重扫建行;再以租户
owner调POST /api/skills/rescan→data.roots[]只含本租户根与项目根,data.removed里没有系统技能,GET /api/skills里那个系统技能仍在(比对范围按归属过滤,不是"盘上找不到就删")。 - 系统技能根读出 0 条不删行(§9-35):把
system-skills/里的内容清空(目录保留)→ 系统管理员重扫 →roots[]里该条exists:true,count:0,removed里没有系统技能的行,GET /api/skills里系统技能仍在;把整个目录删掉再重扫 → 整次失败(非code:0),表一行没动。 - 同名的 invalid 行能入库(§4.7 部分唯一索引):租户层已有生效的
x,把出厂x拷进系统根 →rescan后表里同时有「x生效(tenant)」和「xinvalid(system)」两行;unique (tenant_id, name) where valid不挡后者(这两行本来也不同桶)。同桶的那一例:本租户已装x,再往本租户的项目根里放一份x→rescan写出一行同桶的xinvalid,索引同样不挡。 - 正文超 16,384 token(或超 64KB 字节)→
116116,不截断(装不上就是装不上;不会装一个半截正文的技能进去)。 PATCH {enabled:false}→ 列表enabled:false;再true恢复。DELETE→ 列表消失;磁盘进.trash;下一次 run 目录里没有它。- 系统技能
DELETE→116106(只读)。 POST /api/skills/preview吃{"command":"npx skills add <owner>/<repo> --list"}→ 返回候选(name/description/bytes/requires),磁盘无新增。- 多技能仓库不选 →
116108且data.skills列候选;带{"skills":["a"]}→ 只装 a。 {"command":"npx skills remove x"}、{"command":"npx skills add x; rm -rf /"}、{"source":"git@github.com:o/r.git"}、{"source":"http://127.0.0.1/a.zip"}→ 全部116109。- 上游 404/连接超时 →
116110;归档里没有含SKILL.md的目录 →116111;超下载/解压上限 →116113。 - 同一条命令装第二次 →
116106(同名);覆盖只能走POST /api/skills/:name/update。 - 工具上传(D36):
curl -F name=hello -F file=@./hello /api/tools→{"code":0,…,"data":{"tool":{"name":"hello","path":"…/tenants/<tid>/tools/hello/bin/hello","bytes":<文件字节>}}};盘上该文件存在且权限-rwxr-xr-x。curl /api/tools的tools[]里有它,没有.staging/.trash这些条目。 - 同名再传一次(换一个不同大小的文件)→ 覆盖成功、
bytes变;tools/.trash/里出现旧的hello-<ts>目录。 -F name=../evil、-F name=bash、-F name=Bash、空文件 →116117,盘上无新增;传 >128MB →116118;租户额度不足 → 429codeQuota。- viewer 账号传工具 →
111203,但GET /api/tools仍 200(成员可读);DELETE /api/tools/nope→116119。 DELETE /api/tools/hello→{"status":"deleted"};列表里没有它,tools/.trash/hello-<ts>/在。
11.2 运行链路
- 起一场 run,
GET /api/sessions/:id/log能看到 manager 侧的use_skill调用(agent="");不再有agent="skill"的行(2026-10-28 翻案后没有内置 skill agent 了);每对 call/result 的toolCallId相同。 read_skill/use_skill的tool_result.output是<skill name="…" source="…" bytes="…">…</skill>的 XML 原文(成功形态,§2.10);use_skill的标签另带requires/missing(D38),剥掉这两个属性后两份逐字节相同;正文反转义后与盘上逐字一致(2026-10-28 第二轮复审改口径:D30 要求把正文里的<&转义,所以原始字节本来就不同;这条验收比的是「看起来一致」——把<&还原回去之后逐字相同。断言器要按这个口径写,别去比原始字节),返回体里没有path;失败时是 JSON 信封({"code":116001,…})。GET /api/runs/:id/skills只列三个技能工具行(read_skill/use_skill/read_skill_file,agent="");tool是工具名,path只在read_skill_file的行出现;失败调用ok:false且code正确。- 资源上限与正文同一条判据(§9-31):把一个
references/big.md做到 20,000 token(或 70KB)→read_skill_file({name, path:"references/big.md"})回{"code":116115,…},不返回任何部分内容;换成 15,000 token 的references/ok.md→ 正常返回全文,bytes与盘上一致。同一工具:path指向目录 → 不递归条目列表(§8.2-2);path含..或EvalSymlinks后跳出技能根 →116114(不说根外有没有东西)。 - 普通子代理是技能盲:让 manager 把一段普通任务派给 coder,并要求 coder 报告「你手里有哪些技能/技能工具」——它应回答没有;runlog 里不存在
agent="coder"的read_skill/use_skill/read_skill_file,也不存在它的目录注入痕迹。 - 技能根的可见范围是结构性的(D25 + §9-34):manager 在
use_skill之前,cat <租户技能根>/<name>/SKILL.md被拒(Operation not permitted);use_skill成功之后,它自己那一份能cat、能跑scripts/*.py(只读);隔壁技能即使同在一台机器、同在一个根下,仍然被拒。普通子代理的 bash 对技能根一律被拒(它爹的盒子里有也不行)——不是「读到了但模型没用」,是根本读不到;工具根不在此列(D36:<tenant>/tools是租户环境,普通子代理照样能读,见下两条)。 - 续跑与新 run 的执行权恢复(D35):一场 run 用
pdf建了任务、跑脚本成功 →kill -9后POST /api/runs/:id/resume→ 不调use_skill直接python3 <pdf 根>/scripts/x.py应当成功(装配时按本 run 已重放的skill_name补回盒子);同一条规则在下一场 run 里成立(按 D34 那个「上一场」补)。反向三条:①一场 run 只use_skill没建任务 → 下一场 run 不调use_skill跑它的脚本 → 被拒;②上一场有任务、但技能在这期间被PATCH禁用 → 新 run 里盒子不含它,跑脚本被拒、use_skill报116107;③上一场有任务、但技能目录被手工删掉 → 装配不失败(run 正常起来),use_skill报116001。 - 技能根只读不给写:manager 的 bash 能读本场用过的技能根,但不能往里写(profile 只加
file-read*)。 - 工具按租户常开(D36,F2 已验 2026-10-28):
POST /api/tools传一个hello→ 起 run,不调任何技能直接hello→ 成功;装一个requires: [hello]的技能后GET /api/skills/:name/check里它found:true、path指向工具根;manageruse_skill那个技能、跑它正文里的命令 → 成功。 - 普通子代理也能用工具(与技能根正好相反,F2 已验 2026-10-28):让 manager 派一个普通子代理跑
hello→ 成功(工具根常开、bin在PATH前面);同一个子代理cat <技能根>/SKILL.md仍被拒(技能根那套收窄没变)。 - 技能脚本能出网(D37):技能正文里写一条
curl -sS https://example.com -o out.html→ manager 跑它成功、out.html落在项目根;反过来,脚本起一个监听端口(python3 -m http.server 8801)→ 从围栏外连不进去(入站没开);bind 本身可能成功,被拒的是进来的连接,以实测为准回填这条。护栏回归:脚本curl一个二进制到项目根并chmod +x后能跑,但cp进<tenant>/tools/仍Operation not permitted。 - 缺依赖在
use_skill那一刻就说(D38):装一个requires: [definitely-missing-tool]的技能 →use_skill返回的标签带requires="definitely-missing-tool" missing="definitely-missing-tool",正文照常返回;read_skill同一技能的标签没有这两个属性。再让它执行正文里那条命令 → bash 回command not found,run 不因此变 error;模型回复里应说明缺哪个工具、请管理员上传,而不是自己curl一个装进系统目录。全部依赖都在的技能(requires: [python3])→requires="python3" missing=""。 - 围栏外的工具报「没装」,不报权限(D39):起引擎前把
~/bin塞进PATH、并在里面放一个可执行fake-py→ run 里fake-py回command not found(不是Operation not permitted);echo $PATH里不含~/bin、含<tenant>/tools/*/bin;/usr/bin/python3 -V照常能跑。给一个requires: [fake-py]的技能 →use_skill的missing="fake-py"(检查与 bash 用同一条过滤后的PATH);正文用绝对路径点名~/bin/fake-py时仍报Operation not permitted,这条不用改。 - 覆盖与删除不影响在位 run 的装配(F2 已验 2026-10-28):一场 run 跑到一半时用 API 覆盖
hello→ 同一场 run 的下一枪hello输出新版本(PATH里的路径没变、rename 是原子的);DELETE掉它 → 下一枪command not found,run 不因此变 error。 - manager 自己读正文并执行:根 run 的
use_skill结果里就是正文本体(<skill>包裹),manager 照它做事;正文不再只出现在某个子代理的上下文里。 - 只为看看内容而读,看板一行都不会多(D32 的反向验收):让 manager 调
read_skill({name})然后什么都不建(用户问「这个技能是干什么的」就是这个场景)→run_tasks里没有任何新行,也没有skill_name的记录;同一场 run 紧接着再read_skill一次,仍然一行都不多。反过来,manager 调use_skill后建任务 → 该任务的skill_name是它;use_skill之后不建任务,同样一行都不多(程序不代建)。 - 正文用完就走(D33):让 manager 调
use_skill读一个多步技能、并按正文建至少一条TaskCreate→ 下一枪的输入里该技能的<skill>块已换成<skill name="…" folded="true" reload="read_skill" tasks="见看板"/>(从 mh 或 turn 记录看)。此时 mh 里那条 tool 行也是 marker,而runlog的payload.output仍是发射时的全文——两处要能分别看到。TaskList仍返回该技能的任务;需要细节时再read_skill一次仍拿到全文(marker 不阻止重读),且看板行数不变(重读不会多出任务)。 - 跨 run 续做(D34):一场 run 里用技能建 3 条任务、只完成
#1→ 用户发下一条消息(新 run)→ 第一枪调TaskList:当前看板为空,输出里带「上一场」段,列出#2/#3的主题与说明(已完成的不列);写操作回执里没有这一段。上一场全部完成时,同一次调用只给一行「上一场已全部完成」、不带说明。用户接着说「第 3 步改一下」,manager 能答出这一步要做什么(从#3的说明,不是编的)。 - 只读不办事也能收回正文:
read_skill之后一条TaskCreate都没有(读了正文就干别的)→ 下一枪正文仍在(D33 的判据是TaskCreate调用,不是「读过了」)。 - compact 后:先让 manager 用技能完成一次,再逼出根 run 压缩,再问细节;manager 重调一次
read_skill(日志出现第二次read_skill)而不是凭空编;看板任务仍在(run_tasks不参与折叠)且行数没变;摘要末尾出现技能记录块(<!-- tako:skill-ops v1 -->,块里有技能名)。 - 并发同名工具调用:UI 按
toolCallId配对,不错位。 - 装完当场可用、下一轮才进目录:manager 在对话里提议、人确认、程序装完之后,同一场 run 里直接
use_skill({name})能成功;这场 run 的目录里没有它;发送下一条消息(新 run)后目录出现它。 - 提议 ≠ 安装:模型调完
skill_install、人还没点的时候,GET /api/skills里没有它、skill_rows没有行、技能根上没有目录(只有.staging/<rand>/);人点取消后.staging里的东西没有任何一行进表。 - 目录不中途换:一场 run 进行中通过管理 API 删掉一个已列出的技能,manager 本轮仍看得到名字,但
use_skill返回116001;下一条消息起目录里消失。 - 目录来自表,正文来自盘:手工改
SKILL.md里的描述、不动表 → 下一次 run 目录仍是旧描述,read_skill返回新正文;POST /api/skills/rescan后再起 run,目录换成新描述。
11.3 文件与删除
- 项目删除后:项目技能目录不存在;团队技能仍可读;项目里的软链在删除前能读、删除后随目录消失。
- 软链指向白名单外 →
rescan记为valid=false,不读、不报 run 失败。 - 更新同名技能期间读:读工具重试一次后成功;不会返回新旧混合正文。
- 删除会清掉同名禁用项:
PATCH禁用x→DELETE x→ 重装x→GET /api/skills里x是enabled:true,下一次 run 的目录里出现它。 - 改模型配置不会把禁用项冲掉(这条直接验收「禁用为什么不放
configJSON」):PATCH禁用x→PUT /api/tenants/:id/runtime-config只改模型 ref →GET /api/skills里x仍是enabled:false,下一次 run 的目录里仍然没有它。旧方案(塞config)在这条上会红。 - 并发写不互踩(D27):两个请求并发装同一个技能 → 一个成功、一个 409(库锁串行,不是碰巧);
rescan与安装同时跑 → 装好的技能不会从列表里消失(不出现「目录在、表里没行、目录里也不列」的静默丢失)。 - 工具目录的删除与清扫(D36):
DELETE /api/tools/hello→<tenant>/tools/.trash/hello-<ts>/;24 小时后下一次写操作时被清掉,.staging里的半截上传同理。删完之后GET /api/skills/:name/check里requires: [hello]那条变found:false、path不出现。G1 已验 2026-10-28:两个根下各造一个 25 小时前的.trash/.staging条目与一个新建条目 → 一次租户rescan(技能根)与一次工具删除(工具根,回116119)之后旧条目消失、新条目留下;规则单测TestSweepTempDirsByMtime/TestSweepTempDirsNoDirs。审计补拍(同日):工具上传的在途 staging 与技能安装同享那条豁免(sweepTempDirsKeeping+stagingKeep),活体证据与单测名见文档头 G1 段④。 rescan对账(G1 已验 2026-10-28):手工在技能根造一个合法技能目录 → 第一次rescan的added有它;删掉目录 → 第二次removed有它一次;第三次removed: [],表里没有重复行。并发rescan与安装同时跑三轮 → 每轮安装都成功、rescan的removed: []、装好的技能仍在列表(锁串行,不静默丢)。- 跨租户不排队(D27 第十一轮):租户 A 与租户 B 同时装各自的技能 → 两边都立刻成功,没有一方在等锁(验法是给 A 的安装关一个慢速上游、量 B 的耗时不受影响);系统管理员的全量
rescan同时跑 → 它等两边做完才开始、且这段时间新的租户写拿到 409 而不是插进中间。
11.4 UI(Playwright)
- 列表/详情/安装/删除/禁用五条路径各点一遍;坏包显示业务码文案。
- 技能页输入框粘
npx skills add … --list→ 出预览卡片(名称/描述/依赖),勾选后安装、列表刷新。 - 粘
npx skills remove x→ 显示「只支持 add」(116109文案),不写盘。 - 依赖缺失显示琥珀色,不显示「全部就绪」。
- 工具区(D36):上传
hello→ 列表出现、字节与磁盘一致;重名上传先出确认再覆盖;删掉后列表消失;viewer 账号看不到「上传」按钮,但仍能看见列表。 - 对话里的技能卡片展开的是模型实际看到的那段(可能是
<skill>块,也可能是 D33 之后的 marker),不是回盘重读的原文;失败显示message。 - 对话里的技能卡片按
use_skill(「使用技能」)/read_skill(「查看技能」)/read_skill_file(资源单独一行)分开显示;普通子代理的段落里没有任何技能卡片或技能工具。 - 安装确认卡(D24):对话里让 manager 调
skill_install→ 出现程序渲染的确认卡(来源、ref、候选全表与选中集、依赖、文件数/字节、「此来源在本会话中未出现」);用 viewer 账号点「安装」→ 提示需要管理员且列表不变;换 admin 点「安装」→ 列表出现该技能、对话里这张卡变成「已安装」;另一场点「取消」→ 卡变「已取消」、列表不变。模型正文里写一个假的「安装」按钮不应响应。前提是答案端点先改一道闸:今天denyRunWrite(server.go:561-573)只放accessOwner,admin 答别人的 run 会在角色判定之前就 403——不先按 §10.1-8 把kind=install分到这道闸前面,这条验收的第一行(viewer 得到 111203、admin 装成功)都不成立。 - 多标签页:A 标签删技能,B 标签收到
skills_changed后列表刷新。
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. 明确不做
- run 装配时的全盘扫描:目录来自
skill_rows,盘上的偏离靠写入口与rescan收。 - 技能市场/目录站、私有仓库(SSH/token)、版本仓库与回滚历史。
- 技能版本号与回滚(表里只有当前一行,没有历史)。
- 目录描述截断(任何长度都不切)。
- 把技能目录解析成结构化索引、批量预读、只把正文读回来摘要给 manager 的中间子代理。
- 每个子代理一份技能目录;普通子代理发现或执行技能(它们是技能盲的执行单元,§2.8)。
- 技能搜索(
skill_search)与「目录太大时切搜索模式」(2026-10-28 拍,D28)——目录体积只有作用域 + 禁用两把闸可控,这是已知天花板(§2.7、§9-33),不是遗漏。 - 给所有技能根一把钥匙(D25)——放行是按角色、按技能的:根 run 只读本场声明过(或按 D35 接着办)的那几个根,隔壁技能与普通子代理都够不到;不是一把钥匙发给所有人。(工具根不在这条里:它按租户常开、所有角色都能用,因为二进制里没有技能正文,D36。)
- 技能内部并行拆活(由 manager 在外面拆,§2.8 边界二)。
- 技能正文的资源句柄与「钉住/释放」生命周期。
- 安装时用 LLM 摘要描述、补全缺失描述。
- 自动安装依赖、安装期执行包内脚本、执行
npx/npm子进程或包内postinstall、HTTP 面读服务端本地路径。 - 多文件工具前缀上传(这一拍只收单文件;解释器整包走运维同步或软链——方案内后置阶段,触发条件见 §9-37)、从 URL 装工具(工具根只收上传,不替租户下载二进制;run 里 curl 落项目根不算工具)、上传时执行或探测工具(
Exec format error/Bad CPU type只能在 run 里看到)、工具的版本历史与回滚(同名即覆盖)。 - 后续工具的因果归因、全局技能计数器、自动淘汰低效技能。
- 技能正文的 PII/密钥扫描(v1 不做;安装权限收紧)。
- 跨文件系统与 PG 的原子提交:文件系统不在事务里,装/删/改可能留下一边;不建分布式事务,靠
rescan补偿(§4.7 已记录,本期不处理)。 - Linux 沙箱(单独 loop,不在本篇施工面)。
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 按租户常开、所有角色(含普通子代理)都能用——正因为它收的是可执行文件、不是说明书,收窄它只会让派下去的重活跑不动。