Refly PTC 调试模式增强从布尔开关到 opt-in/opt-out 标题过滤的配置优先级设计【免费下载链接】reflyThe first open-source agent skills builder. Define skills by vibe workflow, run on Claude Code, Cursor, Codex more. Build Clawdbot · APIs for Lovable · Bots for Slack Lark/Feishu · Skills are infrastructure, not prompts.项目地址: https://gitcode.com/GitHub_Trending/re/refly本文基于 Refly 仓库中的变更规格 20260228-ptc-debug-mode-enhancement讲解 PTCProgrammatic Tool Calling调试过滤器PTC_DEBUG的增强设计如何从只能true/false的布尔开关扩展为opt-in/opt-out两种命名模式如何修复“调试开关意外覆盖PTC_MODE权限”的优先级 Bug以及这些改动在 ptc-config.ts、skill-invoker.service.ts 和 ptc-env.service.ts 中的具体落地方式。读完后你将理解 Refly 分层权限判定链中“调试过滤”这一层的设计原则并掌握在生产与本地调试环境中正确配置PTC_DEBUG的方法。背景PTC 调试开关原来存在的问题PTC 是 Refly 的核心能力之一模型不通过 JSON Schema 的 function-calling 直接调工具而是编写 Python 代码在沙箱中 import 自动生成的 SDK以类方法的形式调用工具沙箱再通过POST /v1/tool/execute回调 Refly API 完成真实执行。这套机制的完整架构可参考 PTC 参考文档。在增强之前PTC_DEBUG只有true/false两个取值。根据规格中的问题陈述旧实现存在两个具体缺陷表达力不足PTC_DEBUGtrue时PTC 只对标题包含 ptc 的节点生效并且会覆盖override其他所有配置。开发者无法表达“除了少数几个节点外全部节点都启用 PTC”这种场景只能去改动PTC_MODE。优先级 Bug旧的覆盖逻辑跳过了PTC_MODE/PTC_USER_ALLOWLIST的权限检查——即使PTC_MODEoff只要PTC_DEBUGtrue仍然能激活 PTC。这意味着一个本应“只用于调试”的开关可以绕过全局硬关闭kill switch。增强目标Goals有三条将PTC_DEBUG扩展为两个命名模式opt-in 与 opt-out用于基于节点标题的过滤修复优先级调试过滤器只在基础权限检查isPtcEnabledForToolsets已经返回true之后才生效当PTC_DEBUG未设置或为空时行为与之前完全一致无回归。范围Scope上本次变更不改动PTC_MODE、PTC_USER_ALLOWLIST以及工具集toolset允许/阻止列表的逻辑——调试模式只是权限链最末端的一层“细筛”不重构前面的任何环节。PTC_DEBUG 取值语义四种状态的行为定义增强后PTC_DEBUG的完整取值表如下继承自规格文档的 Design 一节值行为未设置 / 空字符串调试过滤关闭完全由PTC_MODE 用户允许列表 rollout 决定opt-in仅当节点标题包含 useptc 时才启用 PTC默认禁用按节点选择启用opt-out所有节点都启用 PTC除非其标题包含 nonptc默认启用按节点选择排除true遗留值等价于opt-in向后兼容旧开发环境两种模式对应两种典型的调试姿势opt-in白名单式调试本地开发时大多数节点走传统的 JSON tool calling只给标题里写了useptc的个别节点开 PTC便于对照同一条工作流在两种执行路径下的行为差异opt-out黑名单式调试想让整条工作流默认走 PTC 以压测或验证 SDK 集成但某几个已知有问题的节点暂时排除——把它们标题里加上nonptc即可。两种模式都不改变上游的权限语义如果用户本来就没有 PTC 权限标题里写useptc也不会生效。优先级模型调试过滤只在基础检查通过后运行这是本次增强最核心的设计点。规格中用伪代码明确定义了新的判定顺序PTC_MODEoff 或 用户不在 PTC_USER_ALLOWLIST 中 → ptcEnabled false 调试过滤根本不会运行 PTC_MODEon/partial 且用户被允许 → ptcEnabled true → 若 PTC_DEBUGopt-in: ptcEnabled title.includes(useptc) → 若 PTC_DEBUGopt-out: ptcEnabled !title.includes(nonptc) → 否则: ptcEnabled 保持 true对照 PTC 参考文档 中的环境变量优先级总表可以看到PTC_DEBUG位于整条链的Priority 5最低排在PTC_MODE、PTC_USER_ALLOWLIST、PTC_TOOLSET_BLOCKLIST/PTC_TOOLSET_ALLOWLIST、PTC_ROLLOUT_PERCENT之后并且文档明确注明“Has no effect if PTC is disabled”若 PTC 被禁用则无任何效果。这个顺序在源码中可以得到直接印证。ptc-config.ts 中的isPtcEnabledForToolsets()按三步短路求值isPtcEnabledForUsermodeoff直接返回falsemodeon返回truemodepartial检查userAllowlist.has(user.uid)所有 toolset key 必须通过isToolsetAllowedblocklist 优先于 allowlist最后应用 rollout 闸门isPtcEnabledForRolloutSHA-256(uid salt) % 100 rolloutPercent的确定性分桶。注意这个函数里完全不涉及debugMode——调试逻辑被刻意放在它之外。实际的过滤发生在 skill-invoker.service.ts 的 PTC 决策点核心代码为// Calculate PTC status based on user and toolsets (highest priority) const ptcConfig getPtcConfig(this.config); const toolsetKeys toolsets.map((t) t?.toolset?.key ?? t?.id ?? ); let ptcEnabled isPtcEnabledForToolsets(user, toolsetKeys, ptcConfig); // Debug mode: title-based filtering, applied only when base check already permits PTC. // opt-in → enable only if title contains useptc // opt-out → disable only if title contains nonptc if (ptcEnabled ptcConfig.debugMode ! null) { const title data.title?.toLowerCase() ?? ; if (ptcConfig.debugMode PtcDebugMode.OPT_IN) { ptcEnabled title.includes(useptc); } else if (ptcConfig.debugMode PtcDebugMode.OPT_OUT) { ptcEnabled !title.includes(nonptc); } }if (ptcEnabled ptcConfig.debugMode ! null)这一行守卫就是优先级修复的直接体现基础检查不通过时debugMode分支根本不进入PTC_MODEoff永远是硬关闭标题在比较前先经toLowerCase()归一化实现了规格 Notes 一节声明的“大小写不敏感匹配”。配置解析层PtcDebugMode 枚举与 parsePtcDebugMode本次变更对配置数据模型做了两处结构调整新增PtcDebugMode枚举PtcConfig接口中的debug: boolean字段被替换为debugMode: PtcDebugMode | null并移到接口末尾。ptc-config.ts 中的枚举定义及其文档注释export enum PtcDebugMode { /** * Opt-in: PTC is disabled by default; enable per-node by adding useptc to its title. * Equivalent to the legacy PTC_DEBUGtrue behaviour. */ OPT_IN opt-in, /** * Opt-out: PTC is enabled by default; disable per-node by adding nonptc to its title. */ OPT_OUT opt-out, }解析函数parsePtcDebugMode()ptc-config.ts的容错策略分三层未设置或空字符串!value?.trim()→ 返回null即调试过滤关闭归一化trim().toLowerCase()后为true→ 映射为PtcDebugMode.OPT_IN这是为不破坏既有开发环境而保留的遗留别名值命中Object.values(PtcDebugMode)之一 → 返回对应枚举值否则记录 warning 日志“Invalid PTC_DEBUG value: … valid values are: opt-in, opt-out. Disabling debug mode.”并返回null——即非法值等价于关闭调试而不是抛错或猜测。这一“非法值安全降级为关闭”的策略与同文件中parsePtcMode()对非法PTC_MODE值降级为OFF的风格一致调试类配置出错时宁可不动作也不引入非预期的 PTC 行为。环境变量到配置对象的入口在 app.config.tsmode: process.env.PTC_MODE || off, debug: process.env.PTC_DEBUG || , userAllowlist: process.env.PTC_USER_ALLOWLIST || , toolsetAllowlist: process.env.PTC_TOOLSET_ALLOWLIST || , toolsetBlocklist: process.env.PTC_TOOLSET_BLOCKLIST || , sequential: process.env.PTC_SEQUENTIAL true, rolloutPercent: Number(process.env.PTC_ROLLOUT_PERCENT ?? 100), rolloutSalt: process.env.PTC_ROLLOUT_SALT || ptc-rollout,可以看到PTC_DEBUG缺省为空字符串而非false这正好与parsePtcDebugMode的第一层判断对齐空值 未启用调试过滤。沙箱环境注入REFLY_PTC_DEBUG 只表达“是否处于调试运行”规格中“Files changed”一节列出的第三个文件是ptc-env.service.ts其职责是准备沙箱执行所需的环境变量。增强后的规则是只要设置了任何非空调试模式就向沙箱注入REFLY_PTC_DEBUGtrue。ptc-env.service.ts 的实现const ptcDebugRaw this.config.getstring(ptc.debug) ?? ; const isPtcDebugEnabled ptcDebugRaw.trim().length 0; return { REFLY_TOOL_SERVICE_API_URL: toolServiceApiUrl, REFLY_TOOL_SERVICE_API_KEY: toolServiceApiKey, REFLY_PTC_DEBUG: String(isPtcDebugEnabled), REFLY_CANVAS_ID: req.context?.canvasId ?? undefined, REFLY_RESULT_ID: req.context?.parentResultId ?? undefined, REFLY_RESULT_VERSION: req.context?.version ? String(req.context?.version) : undefined, REFLY_PTC_CALL_ID: req.context?.toolCallId ?? undefined, };判断依据是原始配置字符串是否非空trim().length 0而不是枚举值本身。规格 Notes 一节解释了这样做的意图沙箱中的REFLY_PTC_DEBUG反映的是“是否有任何调试模式处于激活状态”而不是“哪种模式”——沙箱侧的 Python SDK 只需要知道当前是一次调试运行即可不需要按模式分支。这里有一个值得注意的细微差别沙箱里拿到REFLY_PTC_DEBUGtrue不等于“这个节点的 PTC 一定被启用了”。getPtcEnvVars在会话/沙箱环境准备阶段按全局配置注入而标题过滤是按节点data.title在 skill-invoker 里逐次求值的。也就是说这个沙箱变量是“本次进程配置了调试模式”的标记粒度比节点级判定更粗。单元测试解析行为与权限链的验证测试文件 ptc-config.spec.ts 按照规格 Plan 最后一项的要求用四个用例覆盖了debugMode的解析分支测试用例输入ptc.debug期望config.debugMode遗留布尔值truePtcDebugMode.OPT_IN显式 opt-inopt-inPtcDebugMode.OPT_IN显式 opt-outopt-outPtcDebugMode.OPT_OUT非法值invalid-valuenull关闭对应源码中的用例ptc-config.spec.tsit(should parse debugMode as OPT_IN when set to true (legacy), () { // ... ptc.debug: true const config getPtcConfig(mockConfigService as ConfigService); expect(config.debugMode).toBe(PtcDebugMode.OPT_IN); }); it(should return null debugMode for invalid value, () { // ... ptc.debug: invalid-value const config getPtcConfig(mockConfigService as ConfigService); expect(config.debugMode).toBeNull(); });除了解析测试该文件还完整覆盖了权限链其余环节可作为理解优先级模型的“活文档”isPtcEnabledForUsermodeoff恒 falsemodeon恒 truemodepartial按userAllowlist判定isToolsetAllowedblocklist 优先级高于 allowlist未配置 allowlist 时toolsetAllowlist null除被 block 的 toolset 外全部放行isPtcEnabledForToolsets任一 toolset 不通过即整体 falsemodeoff时在 rollout 检查之前就已短路对应测试 “should not apply rollout gate when mode is OFF (fails earlier)”isPtcEnabledForRollout同一 uid salt 分桶结果确定两次调用一致改变 salt 会重新分桶20 个用户样本中至少出现一次不同的分配。这些测试与实现代码相互印证了规格的核心承诺调试过滤是一个旁路的、后置的细筛层任何上游的失败都不会被它“救活”。实战配置场景结合 PTC 参考文档 的 Environment Variables 一节与调试模式相关的可复制场景如下本地开发 — opt-in 调试只有标题含 useptc 的节点触发 PTCPTC_MODEon PTC_DEBUGopt-in本地开发 — opt-out 调试所有节点触发 PTC标题含 nonptc 的除外PTC_MODEon PTC_DEBUGopt-out测试环境 — 指定用户 opt-out 调试PTC_DEBUG不会为白名单之外的用户“开洞”PTC_MODEpartial PTC_USER_ALLOWLISTu-user1,u-user2 PTC_DEBUGopt-out遗留写法仍可用等价于PTC_DEBUGopt-in避免破坏既有.envPTC_MODEon PTC_DEBUGtrue几个适用前提与限制需要明确标题匹配是子串包含且大小写不敏感toLowerCase()后includes关键词 useptcopt-in与 nonptcopt-out被特意选为互不包含、无歧义的子串避免一个标题同时触发两条规则时语义混乱标题来源于节点执行数据skill-invoker 决策点中的data.title修改工作流节点的标题即可调整该节点在调试模式下的 PTC 归属无需改代码或重启若PTC_DEBUG填了非法值如debug、1解析会降级为null关闭调试并打 warning但注意沙箱侧的REFLY_PTC_DEBUG注入判断的是原始字符串非空——即非法值不会让任何节点“多出” PTC但沙箱里仍可能看到REFLY_PTC_DEBUGtrue标记本变更明确不改PTC_MODE、PTC_USER_ALLOWLIST与 toolset 列表逻辑rolloutPTC_ROLLOUT_PERCENT闸门也不受调试模式影响生产上仍可先用PTC_ROLLOUT_PERCENT0做 kill switch。变更文件清单与实现状态规格“Files changed”一节列出的四个文件均已在仓库中落地规格 frontmatter 标记status: implementedPlan 清单全部勾选文件变更内容仓库路径ptc-config.ts新增PtcDebugMode枚举PtcConfig.debug → debugModeparsePtcDebugMode()ptc-config.tsskill-invoker.service.ts修复优先级处理opt-in/opt-out两种模式skill-invoker.service.tsptc-env.service.ts任意非空调试模式时注入REFLY_PTC_DEBUGtrueptc-env.service.tsptc-config.spec.ts用opt-in/opt-out/ 遗留true/ 非法值用例替换原布尔测试ptc-config.spec.ts小结调试开关的正确分层位置这次增量的价值在于把“调试”从权限链的旁路覆盖者收敛为链尾细筛器表达力opt-in/opt-out两种模式覆盖了调试中“挑节点验证”与“全量验证挑节点排除”两个高频场景且与遗留true值无缝兼容安全性if (ptcEnabled ptcConfig.debugMode ! null)的单点守卫保证了PTC_MODEoff等上游禁用永远成立调试配置不能再“复活” PTC可观测性非法值降级 warning 日志、沙箱侧REFLY_PTC_DEBUG布尔标记使一次调试运行在 API 与沙箱两侧都有迹可循边界清晰明确声明不改PTC_MODE/ 用户允许列表 / toolset 列表逻辑后续演进如 PTC 参考文档 中的 rollout 百分比可以独立叠加。对于维护者而言若需要在调试模式下按节点灰度 PTC只需调整节点标题中的 useptc / nonptc 标记对于部署者而言PTC_DEBUG只应出现在开发/测试环境——它的设计语义是“权限已放行之后的调试细筛”而非权限授予机制本身。【免费下载链接】reflyThe first open-source agent skills builder. Define skills by vibe workflow, run on Claude Code, Cursor, Codex more. Build Clawdbot · APIs for Lovable · Bots for Slack Lark/Feishu · Skills are infrastructure, not prompts.项目地址: https://gitcode.com/GitHub_Trending/re/refly创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考