Skip to content

[Feature] #1947 Phase 2/3 revival: dynamic skill_pin/skill_unpin + cascade adoption + guardrails (untracked after Phase 1) #3949

Open

Description

@chenshuangci

承接 #1947 的 Phase 2/3。完整设计(工具 schema、级联声明式归属、护栏、实施拆分、分期)见 #1947 原文,本文不重复;只补三块:现状核实、承接范围收拢、一个后续推导出的增量点(对话内 unpin 的同 turn 折叠闭环)。所有设计取舍仍归维护者裁决。

English TL;DR: #1947 closed as COMPLETED after Phase 1 landed (the skill/<name> path syntax, PR #2285, released in v0.1.187) — but Phase 2 (model-callable skill_pin/skill_unpin with session pin state) and Phase 3 (cascade adoption, pin budget, pressure valve, web panel) never shipped, and no successor issue tracks them. This issue revives them, keyed to the same skill/<name> space, and adds one increment worked out since: with unpin as an in-conversation model tool, reclaim closes in the same turn (unpin → compress), so no nudge machinery is needed.

一、现状核实(2026-10-20,上游 v0.1.202)

二、承接范围

实施前提比 #1947 立项时更充分:路径投影已在内核(toolPathOf),skill_pin("x") = pin skill/x,直接键控既有空间,无需宿主谓词中间层(#2285 评审评论已确认该映射)。

三、增量点:对话内 unpin 的同 turn 折叠闭环

#1947 原案讨论了保护生命周期,未讨论回收触发——unpin 之后,折叠何时发生。后续推导结论:

unpin 做成对话内模型可调工具时,回收闭环天然同 turn 完成:用户一句「X 用完了,折掉」→ 模型调 skill_unpin → 代理记 override、返回可回收 token 数 → 模型同一 turn 接 compress 折叠。无需 nudge 队列;也没有独立端点方案的会话定位问题(工具调用自带会话上下文)。web 端点保留为不经模型的确定性通道,两通道写同一份会话 pin 状态(原案双通道设计不变)。

模型自决解钉的风险面(原案未展开):skill 内容可从盘上重新装载,折丢可恢复,与 #1109 防的不可重建工具结果不同级;一次性语义下爆炸半径=每个名字最新一条;ALWAYS_PROTECTED_TOOLS(compress / acp_rule)仍不可解。据此建议不做「用户意图确认」类启发式闸——与原案「不做推断式归属」同一哲学。

四、开放问题(沿用 #1947 §六未决项中仍开放者)

  1. 工具命名:skill_pin/skill_unpin,还是与 acp_* 系列对齐(如 acp_pin)?
  2. cascade 默认值是否取 true(原案按代价不对称论证推荐 true)?
  3. 压力降级阀与硬保护哲学(BLOCKED 不可覆盖)的相容性,默认开还是关?
  4. pin 状态跨重启持久化(session.metadata 持久化是现成行为)还是会话内即逝?
  5. web 端点 pin 的条目是否豁免模型 skill_unpin(user-held 保护);v1 建议不区分来源、last-write-wins。
  6. pin 预算上限的配置面(config 字段 vs 内置常量)与默认值。

Activity

  1. ranxianglei commented on Oct 20, 2026

    @ranxianglei
    Owner

    🤖 Powered by ework · qwen3.8-27b

    (ai: vllm-qwen/qwen3.8-27b)

    标签:opencode / pi / claude-code / zcode(文档明确的 skill 装载客户端)、scope/wiring(宿主侧工具+会话态+配置接线,内核不动)、p3(能力增强,无数据丢失/不可用)。feature 类,不打 bug。

    一、查重结论

    不重复。 #3949 是 #1947 未落地 Phase 2/3 的合法承接:#1947 已于 2026-10-07 以 COMPLETED 关闭(仅 Phase 1 落地,PR #2285 → v0.1.187),仓内 open+closed 检索 skill_pin/skill_unpin/cascade-protection 全零命中,无第二条追踪项。相邻 #2446/#2736(durable/* 虚拟路径)覆盖的是基础设施注入(AGENTS.md/技能目录/MCP 清单),不是 skill 保护生命周期,不重叠。

    二、现状核实(master @ v0.1.202,逐项对照源码)

    论断 核实
    Phase 1 已落地 ✅ toolPathOf/matchToolPath/latest-per-path 分组均在 kernel/src/protected.ts,两旋钮路径语法生效
    P2/P3 未实现 ✅ 全仓无 skill_pin/skill_unpin;__bili/* 路由面无会话级保护入口
    内核已 vendored ✅ file:./kernel(acp-kernel 0.0.136)——#1947 原「Phase 2 前置=内核发版+升 pin」的跨仓门控已作废(owner 在 #1947 floor 14 已确认)
    宿主钩子已接线 ✅ isToolProtected 和 isMessageProtected 都已在每请求喂进内核 Config(src/config.ts:1421、src/session.ts:627)

    这条最后一点是本 triage 的关键架构结论:内核今天就把完整保护面(路径空间 + 两旋钮 + 两条宿主谓词钩子)暴露出来,宿主只需把「会话内动态 pin 集」合并进每请求的有效 protectedTools/protectedLatestTools(或用 isMessageProtected(msg) 精确保护窗口内实例)。因此 Phase 2/3 可完全在宿主侧实现,零内核改动——比 #1947 立项时(当时还要为工具定义单独发内核版)路径更短,评审档也更轻(不触 Kernel Boundary 的人工评审线)。

    三、结构化八问

    1. 是什么问题:skill 保护目前只有「静态按名·全历史」(protectedTools) 或「仅最新实例」(protectedLatestTools) 两档,凑不出「对话中按 skill 动态装卸 + 嵌套级联收养 + 明确回收时机」;长编排会话里要么编排 skill 失保、要么 pinned 上下文无界增长。
    2. 什么原因导致的:机制缺口——Phase 1 只给了「会话生命周期外的固定配置面」,没有「会话内运行态 pin + 窗口释放 + 级联归属 + 回收闭环」这一层;且 [Feature] Per-skill compression protection: static per-name config + dynamic skill_pin/skill_unpin + cascade adoption #1947 关闭后 P2/P3 无人接管。
    3. 影响范围与严重程度:受影响的是跑 skill 嵌套编排的长会话(opencode/pi/Claude Code/ZCode 等)。现状可绕行(手改全局 protectedTools 或放任压缩),属体验/成本问题,非数据丢失、非不可用 → p3。
    4. 怎么修复的:宿主侧维护会话 pin 集(session.metadata,持久化);每请求把静态配置 ∪ 活跃 pin ∪ 级联收养集合并成有效保护模式喂给内核;skill_pin/skill_unpin 做成模型可调代理工具(acp_rule 同型);unpin 兼作关窗信号并返回可回收 token 数,让模型同 turn 接 compress 完成回收。详见下节。
    5. 是否有回归问题:设计为纯增量——静态∪动态只增保护、skill_unpin 不可撤销静态配置(配置=用户意志,pin=流程意志)、ALWAYS_PROTECTED_TOOLS(compress/acp_rule) 永不解;既有 protected-tools / protected-latest 套件须零改动全绿。唯一高危邻域:from= 声明式收养要改写转发入参,触碰 [bug] 插件透传会剥掉工具调用参数里的 render tag(arguments 流挂了 tag-echo 过滤器) #1039 不变量(tool-call arguments 字节级转发)——必须收紧为「只剥代理自己约定的专用字段/首部前缀、仅施于出站副本、绝不碰其他内容」,并在 PR 显式披露。
    6. 是否破坏缓存:pin/unpin 本身不动缓存前缀;其调用记录自身受保护(永久 BLOCKED,不进折叠)。唯一缓存敏感点是级联收养的「描述 append from= 约定行」——OpenCode 的 skill 工具描述本就随技能集变化而变、前缀本就要失效,append 不引入额外代价([Feature] Per-skill compression protection: static per-name config + dynamic skill_pin/skill_unpin + cascade adoption #1947 floor 3 已论证)。
    7. 是否改了设计方向:不转向。是既有保护机制族从「静态配置面」向「会话内运行态」的自然延伸,键控同一 skill/<name> 空间(owner [Feature] Per-skill compression protection: static per-name config + dynamic skill_pin/skill_unpin + cascade adoption #1947 floor 14 已定案)。投影/匹配仍在内核,运行时 pin 逻辑进宿主,边界清晰。
    8. 是否引入了新的配置:P2 核心零新字段(复用既有路径空间 + session.metadata);仅 P3 两个护栏旋钮引入新字段(见下申报)。

    四、修法思路(机制层面)

    • 动态 pin 合并:宿主持 session.metadata.skillPins(Map<skillName, {cascade}>,持久化跨重启)。组装每请求内核 Config 时,有效保护模式 = 静态 protectedTools ∪ {skill/<n> : n ∈ 活跃pin}(latest 语义同理并入 protectedLatestTools)。两种粒度二选一即可满足:粗粒度用模式合并(pin x ≈ 临时把 skill/x 加进保护集,unpin 移除、历史已折叠实例不复活);精粒度用 isMessageProtected 只保护 pin 窗口内实际装载的实例 id。
    • 同 turn 回收闭环(本 issue 的增量点,我认同):用户一句「X 用完了,折掉」→ 模型调 skill_unpin(X)(代理更新 pin 集、返回可回收 token 数)→ 模型同一 turn 接 compress 折叠刚解除的区段。因保护判定每请求从 session.metadata 实时解析,unpin 落库后下一 processTurn 即见更新,该区段随之变为可压缩——无需 nudge 队列,也没有独立端点的会话定位问题(工具调用自带会话上下文)。web 端点保留为不经模型的确定性通道,两通道写同一份会话 pin 状态。模型自解钉的风险面可控:skill 内容可从盘上重载(折丢可恢复,区别于 feat: expose compress.protectedTools (full-history tool protection) #1109 的不可重建工具结果)、一次性语义下爆炸半径=每个名字最新一条、ALWAYS_PROTECTED 仍不可解——据此不做「用户意图确认」启发式闸,与原案「不做推断式归属」同一哲学。
    • 级联收养(P3):from= 声明式归属,正则+三条规则替代推断引擎;代理在观察模型 tool_use 时捕获声明、转发客户端执行器前剥离(仅出站副本),原始登记落 session.metadata。
    • 护栏(P3):①pin 预算上限在每个授权事件处强制(超限拒授新增、不降级既有);②压力降级阀默认关,且只降动态 pin、绝不降静态配置(与「unpin 不可撤销静态配置」一致);③web 会话级端点照 PUT /__bili/config 模式扩展。

    五、六个开放问题的明确建议(沿用 #1947 floor 2 已给结论,补 vendored-kernel 增量)

    1. 命名保留 skill_pin/skill_unpin——owner floor 14 通篇即用 skill_pin("x");领域动词在调用点自解释,家族命名本就不统一(compress/decompress/search_context 均无 acp_ 前缀)。
    2. cascade 默认 true——代价不对称成立(叶子 skill 零代价,编排 skill 默认 false 直接复现问题一)。
    3. 压力降级阀默认关——BLOCKED 硬保护是既有契约,逃生阀显式 opt-in,不动现有行为。
    4. pin 跨重启持久化——与 effectiveRules 先例一致;常驻编排 skill 跨重启静默失保比 stale pin 代价更糟,stale pin 有界(预算上限 + web 可见性兜底)。
    5. web 端点 pin 豁免模型 unpin——v1 last-write-wins、不区分来源(简单优先;确需「用户意志优先」再引入来源标记)。
    6. 预算上限用 config 字段而非内置常量——不同窗口/编排深度需求不同;v1 缺省=不设限(文档标注风险:忘 unpin 则过保护持续到会话结束),具体默认值 P3 实测定。

    六、配置面申报(Configuration Surface Discipline)

    新增恰好两个字段,均落 compress 段、随 P3 护栏入 COMPRESS_SETTING_FIELDS 并镜像 CONFIGURATION.md en/zh:

    字段 期次 默认 语义
    skillPinBudgetTokens?: number P3 未设=不设限 pinned+收养总量 token 上限,每个授权事件处强制;超限仅拒授新增(对象照常执行只是不受保护,可 decompress+补 pin 恢复),绝不降级既有集
    skillPinPressureDowngrade?: boolean P3 关 压力逼近阈值时按装载时间从旧到新强制降级动态 pin(不碰静态配置);显式 opt-in 才开启

    现有面为何表达不了:protectedTools/protectedLatestTools 是「会话外的固定配置」,无法表达「流程运行中按 skill 名动态装卸 + 窗口释放 + 级联收养」——后者必须落在会话态 + 每请求合并,这正是 P2 的主体,且不需要任何新字段(复用既有路径空间)。兼容性:纯增量、默认关/缺省、对既有会话零影响、无需迁移。

    七、待你拍板后开工

    功能类按规先讨论后实现,以下是开工前需要你定的三件事(其余六问我已给出建议,无异议即按此执行):

    1. 是否批准现在开工 Phase 2(pin/unpin 工具 + 会话 pin 态 + 同 turn 回收闭环)?P2 独立价值最大、改动集中在宿主侧、零内核改动、零新配置字段。
    2. 工具 schema 的家:我推荐宿主侧定义(状态+执行都在宿主 session.metadata,"skill" 是产品概念而非压缩原语,保持 Kernel Boundary 不动→免人工评审档;pi-subagents 的 acp_delegate* 已有宿主侧工具面前例)。备选是照 acp_rule/absorb 惯例放内核(家族一致性更强,但要走内核版本 bump + 人工评审)。
    3. 工具是否 opt-in:为避免给从不碰 skill 的会话白付工具面 token(呼应 dsh acp rule报错 #1192「opt-in、仅在启用时 advertise」纪律),我倾向加轻量 opt-in 或「首次出现 skill 装载自动武装」,而非无条件常驻。

    分期确认:P2 → P3(级联收养 + 预算 + 压力阀 + web 端点)。你对上述三点(尤其第 2 点的 schema 归属)确认后我即按此开工,回归契约采纳「既有 protected 套件零改动全绿 + 新增测试落 tests/skill-pins.test.ts」。

  2. added
    zcode改动范围:内核之外的主机侧接线(src/agent 适配器、server 路由、注入拦截)/范围兜底/客户端标签
    on Oct 20, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    claude-codeopencodep3piscope/wiringzcode改动范围:内核之外的主机侧接线(src/agent 适配器、server 路由、注入拦截)/范围兜底/客户端标签

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions