多彩编程 多彩编程MZPH · CODE BLOG
ARTICLE DETAIL

文章详情

深耕前端与后端开发技术的一线实战笔记与踩坑复盘。

Claude Code ScheduleWakeup 工具 reason 字段规范:让每次唤醒原因对用户与遥测都清晰可读

Claude Code ScheduleWakeup 工具 reason 字段规范:让每次唤醒原因对用户与遥测都清晰可读 文档提示工程人工智能【免费下载链接】claude-code-system-promptsAll parts of Claude Codes system prompt, 27 builtin tool descriptions, sub agent prompts (Plan/Explore/Task), utility prompts (CLAUDE.md, compact, statusline, magic docs, WebFetch, Bash cmd, security review, agent creation). Updated for each Claude Code version.项目地址https://gitcode.com/gh_mirrors/cl/claude-code-system-prompts点击查看免费下载导读在 Claude Code 的/loop动态自节奏模式与自主循环中ScheduleWakeup工具负责安排下一次唤醒时间点。而它的reason字段则是每次调度决策面向用户与遥测系统的对外说明。本文基于本仓库中 reason 字段指导 文档结合 ScheduleWakeup 基础工具描述、缓存感知延迟指导、重新武装re-arm决策等系列文档与 CHANGELOG 演进记录系统讲解reason字段的写作规范、它与delaySeconds的配套关系以及它在一轮完整循环中的实际用法。读完本文你将掌握如何写出一个既能让用户一眼看懂、又能为遥测留痕的高质量唤醒原因并理解整条调度决策链路。一、背景ScheduleWakeup 与它的一整套字段ScheduleWakeup是/loop动态模式下调度何时恢复工作的工具——用户以不带间隔参数的方式调用/loop要求 Claude 对一个具体任务进行自我节奏的迭代。依据 ScheduleWakeup 基础工具描述一次完整的调度调用由以下字段构成字段作用关键约束delaySeconds距离下次唤醒的秒数运行时钳制在[60, 3600]区间reason一句话说明选择了什么节奏、为什么进入遥测并回显给用户必须具体prompt下次唤醒时回传的循环指令/loop模式回传原指令自主循环回传动态哨兵sentinel字面量noop标记本轮 tick 是否有实质产出true/false连续true会在终端折叠stop结束整个循环置true时省略其余全部字段本文的主角reason正是这五个字段中最面向人的一个——它是用户理解 Agent 当前行为与节奏选择的最直接窗口。二、reason 字段的核心规范一句话说清选了什么、为什么reason 字段指导 对reason的定义只有三点但每一点都直指要害一句话reason是一个短句one short sentence而不是冗长的段落。它说明你选择了什么、为什么选择what you chose and why。双重去向该字段同时进入遥测telemetry并被回显给用户。这意味着它既是机器侧的诊断留痕也是用户侧的实时可见信息。具体性优先文档给出的正反例是——watching CI run正在观察 CI 运行明显优于waiting等待中。抽象的状态词无法传达任何节奏信息而具体的对象与动作能让用户瞬间理解 Agent 的意图。文档最后一句点明了reason的设计哲学The user reads this to understand what youre doing without having to predict your cadence in advance — make it specific.用户读到reason时不需要预先猜测 Agent 的调度节奏就能知道它在干什么。这正是具体化要求的根本原因。2.1 为什么 watching CI run 优于 waiting从调度语义上拆解这两个例子waiting只描述了状态等待中没有交代等待的对象、也没有交代这次唤醒安排的意图。用户看到它无法判断 Agent 是在等一个外部任务、还是在挂机、抑或在下一次检查前短暂休息。watching CI run则一次性传递了三层信息对象CI 运行、动作观察/监控、隐含的节奏依据CI 状态的变更速度决定了延迟长短。这与 延迟指导未知缓存 TTL 中根据你实际等待对象的状态变化速度来选择延迟的原则完全一致——一个具体的原因天然暗示了背后合理的节奏选择。2.2 reason 与 delaySeconds 的配套关系reason不是孤立存在的字段它是delaySeconds的解释层。在 动态节奏循环执行重新武装决策 与 /loop 自节奏模式重新武装决策 两份技能文档中每次重新武装调用都同时要求提供delaySeconds与reason前者决定多久后醒来后者说明为什么是这个时长。这意味着好的reason应当与所选的延迟互相印证选择了delaySeconds: 480轮询一个约 8 分钟才能出结果的 CI 任务reason就应当写watching CI run这类说明外部状态的对象选择了delaySeconds: 1200的兜底心跳reason就应当体现这是 Monitor 主唤醒信号之下的长兜底或空闲等待的语义选择了delaySeconds: 1800的空闲 tickreason应当说明没有特定信号要盯按默认空闲节奏回查。这样用户看到reason时就能不需要预先预测节奏地理解 Agent 的调度意图——这正是原文档要求的具体性在实操层面的落地。三、为 reason 提供节奏依据缓存感知的 delaySeconds 选择要写出有理有据的reason必须先理解delaySeconds的决策逻辑。本仓库用三份文档覆盖了不同计费/缓存场景下的延迟选择它们是reason内容的事实来源3.1 缓存 TTL 的两档计费体制依据 延迟指导未知缓存 TTL唤醒成本取决于 Anthropic prompt cache 的 TTL在 TTL 内唤醒会话上下文以缓存方式重读快、便宜超过 TTL 唤醒则全部上下文未缓存重读慢、贵。TTL 由会话计费方式决定Claude 订阅用户会话1 小时 TTL用量超限时降为 5 分钟API-key、Bedrock、Vertex 会话默认 5 分钟 TTL。无论哪种体制有一条共同铁律永远不要为了保温缓存而安排额外唤醒——它们比省下的缓存命中成本更贵。延迟应匹配你实际在等什么。3.2 5 分钟 TTL 下的断点规则延迟指导5 分钟缓存 TTL 给出了最精细的断点规则60s–270s5 分钟内缓存保持温热适合主动轮询 harness 无法通知的外部状态CI 运行、部署、远程队列300s–3600s5 分钟到 1 小时付出一次缓存未命中适合提前检查没有意义的场景——要等数分钟才变化的事情、真正空闲、或作为长兜底心跳不要选 300s它是最差的两头落空——付了缓存未命中的代价却没有摊薄它。想等 5 分钟时要么降到 270s 留在缓存内要么 commit 到 1200s空闲 tick 默认 1200s–1800s20–30 分钟循环仍会定期回查用户随时可以打断。文档给了一个生动的算例一个约 8 分钟的 CI 任务睡 60s 会在它完成前烧掉 8 次缓存——应该改为约 270s 睡两次。3.3 1 小时 TTL 下的简化规则延迟指导1 小时缓存 TTL 则说明当会话处于 1 小时 TTL 时运行时钳制的[60, 3600]区间内每次唤醒都在缓存内没有需要规避的缓存悬崖保温唤醒纯属浪费。此时延迟只需匹配三件事外部轮询、兜底心跳、或 1200–1800s 的空闲 tick。文档同样强调别按缓存窗口思考按你实际在等什么思考。3.4 统一钳制规则三份延迟文档都指出运行时会把delaySeconds钳制在[60, 3600]因此 Agent 无需自行收敛。但钳制不影响reason的写作——reason描述的是选择意图而不是数值本身。四、完整字段协作一次规范的重新武装调用reason在实际调用中与其余字段共同出现。综合两份 re-arm 决策技能文档与 Monitor 回退心跳指导一次标准调用应包含ScheduleWakeup( delaySeconds: 1200, // Monitor 已武装 → 这是兜底心跳倾向 1200–1800s reason: watching CI run, // 一句具体的话在等什么、为什么是这个节奏 prompt: /loop check the deploy, // /loop 模式回传原始指令含 /loop 前缀 noop: false // 本轮有实质产出 )4.1 prompt循环延续的关键/loop 模式依据 /loop 自节奏模式重新武装决策prompt必须回传原始/loop指令全文并带/loop前缀使下次唤醒重新进入该技能并继续循环。例如用户输入了/loop check the deploy就传/loop check the deploy。自主循环依据 ScheduleWakeup 基础工具描述无用户提示的自主/loop需传哨兵字面量${AUTONOMOUS_LOOP_DYNAMIC_SENTINEL}运行时会在触发时将其解析回自主循环指令。注意区分 CronCreate 自主循环使用的${AUTONOMOUS_LOOP_SENTINEL}——ScheduleWakeup始终使用-dynamic变体。4.2 noop本轮是否值得保留noop 状态指导 规定什么都没变no change、still waiting、quiet hold时置noop: true有值得保留的产出编辑了文件、发了消息、推进了状态、浮出了发现时置noop: false。连续noop: true的 tick 会在用户终端视图中折叠并作为连续段streak统计让长时间的安静保持不至于刷屏。而stop: true时则应省略noop。4.3 stop结束循环的正确姿势要结束循环时调用ScheduleWakeup并置stop: true省略其余全部字段循环立即结束、不再触发任何唤醒。这一约定在 Monitor 回退心跳指导 中进一步明确停止循环时应以stop: true调用唤醒工具并用任务停止工具停掉 Monitor可通过任务列表工具查找其任务 ID。五、reason 在循环生命周期中的角色从仓库的 CHANGELOG 演进记录可以还原reason字段的成熟过程集中化CHANGELOG 第 1402 行附近记载唤醒节奏指导被集中到ScheduleWakeup中并保留具体、用户可见的原因retain specific user-visible reasons——说明reason的具体化要求是设计目标而非偶然noop 无条件化第 839 行附近记载ScheduleWakeup的 no-op 上报与缓存 TTL 感知延迟指导同时被强化要求每个延续 tick 报告noop: true/false并在终端折叠连续空转re-arm 显式化第 1486 行附近记载循环重新武装成为每轮的显式决策而非默认行为并在任务通知先处理后决定是否继续以stop: true结束循环。这一演进说明reason不是装饰性字段而是让循环行为对用户透明机制的一部分——配合 noop 折叠与 stop 语义整个调度链路被设计成用户全程可理解、可打断的状态机。5.1 一轮完整 tick 的视角从 自主循环 tick动态节奏 可见被唤醒的 tick 会执行既定检查若要延续循环必须在本轮再次调用ScheduleWakeup传哨兵 prompt 与noop标志否则循环在本 tick 后结束。而每次这样的调用都带一个reason——它是这轮调度决策留给用户与遥测的唯一文字说明。六、写出高质量 reason 的实践清单综合原文档与配套文档一份合格的reason应满足一个短句控制在单句内不要堆砌细节交代对象明确你在等待/观察什么CI 运行、部署、远程队列、Monitor 事件、任务通知……暗示节奏依据让读者能反推出为什么选了这个延迟外部状态变化快 → 短轮询兜底心跳/空闲 → 长间隔具体优于抽象watching CI run优于waitingpolling remote queue depth优于checking things与 delaySeconds 互相印证短的延迟配主动轮询外部状态类原因长的延迟配兜底心跳/空闲类原因面向用户可读它会被回显确保人类用户不借助任何上下文就能理解。应避免的反例waiting、sleeping、checking这类无对象、无意图的抽象状态词与所选delaySeconds明显矛盾的原因以及把整个调度策略写进reason的长篇说明。七、总结reason字段是ScheduleWakeup调度调用中最小却最面向人的字段它一句话同时服务于遥测留痕与用户理解其具体性要求watching CI run优于waiting根植于让用户无需预测节奏即可理解 Agent 行为的设计目标。在实际使用中reason必须与delaySeconds受缓存 TTL 与外部状态变化速度双重约束互相印证并配合prompt、noop、stop构成完整的循环延续语义。理解了这套字段协作你就能真正读懂并写出 Claude Code 动态节奏循环中每一行调度代码背后的意图。赞分享文档提示工程人工智能【免费下载链接】claude-code-system-promptsAll parts of Claude Codes system prompt, 27 builtin tool descriptions, sub agent prompts (Plan/Explore/Task), utility prompts (CLAUDE.md, compact, statusline, magic docs, WebFetch, Bash cmd, security review, agent creation). Updated for each Claude Code version.项目地址https://gitcode.com/gh_mirrors/cl/claude-code-system-prompts点击查看免费下载相关推荐ClickHouse Changelog 编写指南让每次发布都清晰可读的条目撰写规范ClickHouse Changelog 编写指南让每次发布都清晰可读的条目撰写规范 导读 docs/changelog_entry_guidelines.m数据库OLAP列式数据库大数据实时分析数据分析YOLOR分布式训练优化多GPU训练策略与性能调优YOLOR分布式训练优化多GPU训练策略与性能调优 YOLORYou Only Learn One Representation作为一种高效的目标检测算法Claude Code 的 SendUserMessage 工具使用指南让每一次用户可见输出都精确送达Claude Code 的 SendUserMessage 工具使用指南让每一次用户可见输出都精确送达 导读 本文基于 Claude Code 系统提示中的《文档提示工程人工智能上一篇【亲测免费】 推荐一款开源项目Player.js - 现代化的媒体播放器框架下一篇rclone 使用 S3 后端全指南从 AWS S3 到各类兼容存储的配置、调优与运维实践创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表