tako 文档 GitHub

技能谁读谁执行

模块:技能(internal/runengine/skill*.go、worker.go 装配)| 状态:A1–A4 + B1–B4 已落地未提交(2026-10-28;余下施工拍待做)| 证据:doc/52-技能.md §2.8、§3 D19/D29/D32/D33、§4.4、tmp/52-技能/planning.md

1. 场景与病灶

用户装了一份「医生登记」技能:SKILL.md 写着「先读 references/fields.md,再按步骤写库,最后跑 scripts/validate.py」。用户说「按这个技能把张三登记了」。

第一版设计是:manager 派活 → 内置的 skill agent 读正文并执行 → 只交终稿。这条链上「读」和「用」被切开:读正文的是一个中间角色,它看不到用户后续的追问,也不能问用户,最后只交回一份被 50KB 上限裁过的终稿;manager 手里没有正文,用户问「第 3 步为什么那么做」时只能重派一轮。

第二个病灶是正文寿命:一份 16k token 的正文读进来后,每一枪都原样重发,直到 fold 把它折掉;折掉时又只把头 2000 runes 送进摘要,看起来像一段正常摘要,模型不知道被切过,也就不会想到重读。

第三个病灶是执行权:正文让跑 scripts/validate.py,但 bash 的只读白名单每场 run 从空开始——读得到正文 ≠ 跑得了脚本;下一场照着看板「第 3 步」再跑,当场 Operation not permitted。

2. 候选与代价

问题 候选 好处 代价
谁读正文、谁执行 A 内置 skill agent 读并执行(原设计) manager 上下文干净 读与用被切开;多一次委派 + 50KB 回传裁剪;中间角色不能问人、不能再委派
B manager 自己读、自己执行(2026-10-28 翻案,定案) 知识留在能用它的上下文;追问只需重读一条 tool 行 正文进主上下文,必须靠上限与主动 marker 兜住
正文怎么读 A 解析成步骤、只给索引 省 token 步骤与正文不保证对应,执行时仍要原文;解析器是新的一层可腐化真源
B 整篇读(定案) 无中间表示 正文大小必须设上限(见下)
正文读完后留不留 A 钉在上下文里 随时可查 每枪重付;16k token 正文会把别的工具结果挤成 marker
B 建出看板任务后换成 marker(D33,定案) 常态成本有界 追问要重调一次 read_skill;判据只看 TaskCreate 工具名,可能误触发(多一次重读即可)
要不要 skill_search A 做(程序侧 BM25) 技能上百时省 token 目录本来就全文注入,搜索搜不出新东西;只有「不注入目录」才需要它,那是另一种设计与风险
B 不做(D28,定案) 少一个可腐化面 目录体积只剩作用域 + 禁用两把闸 → 已知天花板
谁有权装技能 A 模型直接调安装工具写盘 对话里一句话装好 模型整天读 PDF/网页/技能正文,分不清「我要装」是自己想的还是刚读到的;写盘权限必须留在人手里
B 模型只提议、人点确认,写盘由确认端点执行(D24,定案) 授权真身 = 人的一次点击 多一次 HITL 交互;确认卡必须渲染程序解析出的事实,不能信模型文案

裁定:B / B / B / B / B。

3. 同族小裁定

小问题 裁定 代价 / 备注
正文与目录存哪? 正文/资源是卷上的文件;目录(名字/描述/路径/依赖/可用性)进 skill_rows;租户禁用进 skill_disables 文件是正文、表是目录;禁用不能挂共享系统行(会一租户禁用、全租户生效)
名字冲突怎么办? 不做三层覆盖;名字在租户视界内唯一,DB 部分唯一索引 (tenant_id, name) WHERE valid 三层覆盖会让 GET /api/skills/:name 指不到确定一行;「删上层露出下层」是静默事故
目录什么时候重算? run 装配时读一次 skill_rows,拼进 sys;运行中不换菜单;resume 重算 写盘不走入口 → 下次 run 也不知道,兜底是管理页 rescan
目录是不是调用白名单? 不是;能不能读由调用那一刻查行 + 禁用名单决定 否则会有人拿目录做鉴权;省 token 的闸不靠模型守规矩
read_skill 与 use_skill 差在哪? read_skill 纯读、零副作用;use_skill 另外声明「本 run 按它办事」,把技能根放进 bash 只读盒子 只读一眼不该获得执行权;程序不自动建任务(会留下没人收尾的鬼任务)
正文里的 < & 要转义吗? 要,以 <skill name=… source=… bytes=…>…</skill> 进历史 转义后正文里不可能出现真的 </skill>,按内容标记认块才安全;代价是模型抄代码时要自己还原
fold/trim 碰到正文怎么办? 两条路都认 <skill> 块,整块替换成 folded="true" reload="read_skill",不走近头尾夹、不进摘要 夹子是静默的;一个超大结果还会挤掉其它工具结果的还原额度
折掉后怎么知道「用过它」? 程序从被折 assistant 行的 tool_calls 提取技能名,钉在摘要末尾(与 fileOps 块并排) 摘要模型是 LLM,细节可能漏;程序块给确定性、可继承
跨 run 怎么续做? TaskList 除当前 run 外带「上一场」未完成行(含 description);看板是续做正本 description 要模型写细,是自觉不是闸;兜底是重读正文
跨 run 怎么恢复执行权? 装配时按看板里已有的 skill_name 把技能根补回盒子;没建过任务就要求重新 use_skill 判定用「有没有建过任务」这个确定性信号,不用「上一场用过」这种历史
子代理能读技能吗? 不能:无目录、无技能工具、bash 看不到技能根(装配普通子代理时显式去掉 ctx 里的盒子) 子代理继承父 ctx,不去掉这道边界当场破功
缺依赖什么时候知道? use_skill 成功结果里现查 requires 的 LookPath,写 missing="…",不阻断正文 不自动安装(装的时候没有围栏、跑的是引擎进程权限);缺的由人上传或运维同步
子进程 PATH? 按围栏只读根过滤,只留围栏内目录;LookPath 用同一份过滤后的 PATH 否则「说找到、跑起来 not found」会打架;HOME 下的工具从「找到但跑不了」变成「找不到」——它本来也跑不了

4. 证据

5. 现状

主链路(A1–A4 + B1–B4)已落地但未提交;剩余 16 拍(含 B5 skill_name 起)。两处仍是最小实现:项目层技能可后置;skill_rows 的 project_id 列先留空。与相邻方案的交界:bash 围栏(doc/35 Linux 沙箱、doc/52 D37 出站网络)决定「脚本真能跑」;看板(doc/41)承载跨 run 续做;doc/34 的 RunProfile 承载 SkillPolicy。