企业官网建设流程全解析

Claude Code 会话预热命令 prime_tts 实战解析：代码库上下文加载与 TTS 语音总结

【免费下载链接】claude-code-hooks-masteryMaster Claude Code Hooks项目地址: https://gitcode.com/GitHub_Trending/cl/claude-code-hooks-mastery

prime_tts是 claude-code-hooks-mastery 仓库中一个面向"新会话快速上手"的 Claude Code 斜杠命令（slash command）：它通过分析代码库结构、读取项目 README 与核心文档，为刚启动的 Agent 会话注入必要的上下文，并在上下文加载完成后自动交接给 TTS 总结 Agent，以语音方式向用户播报"我已就绪"。读完本文，你将掌握这类"预热命令"的 frontmatter 写法、内联上下文绑定（Bash 命令 / @file 引用）机制，以及其背后由文件锁队列、LLM 总结器与 SubagentStop Hook 构成的一整套语音播报基础设施，可直接迁移到自己的 Claude Code 项目中复用。

命令定位：为什么需要"预热"一个新的 Agent 会话

Claude Code 的每一次新会话（session）都是相对独立的：Agent 不会自动携带上次会话的记忆，也不会主动知道当前仓库里有哪些文件、项目是干什么的。如果直接让 Agent 开工，它往往需要反复ls、find、读文档，才能建立起对代码库的基本认知，既浪费时间又容易产生错误的上下文推断。

prime_tts 命令 的设计目标正是解决这个问题：在会话初期一次性完成"结构扫描 + 文档阅读 + 概览汇报"，把项目上下文以可验证的方式注入 Agent 的视野，最后再通过 TTS 语音告知用户准备工作已完成。仓库中同目录下还有一个更基础的 prime 命令，两者的差异恰好体现了 prime_tts 的两个增强点：

• prime只做"收集信息 → 阅读文档 → 汇报理解"三步，报告形式为纯文本；
• prime_tts在此基础上额外绑定了两份文档、更完整的目录树命令，并在收尾处明确要求"运行 tts summary agent，并告知用户你已准备好开始构建"，即把"就绪通知"从文字升级为语音。

命令结构逐节拆解

prime_tts的完整文件内容可分为三段：YAML frontmatter、Instructions 指令节、Context 上下文节。下面逐节说明其作用与写法。

frontmatter：声明权限与命令简介

--- allowed-tools: Bash, Read description: Load context for a new agent session by analyzing codebase structure and README ---

• allowed-tools: Bash, Read：声明该命令执行期间允许 Agent 使用的工具白名单。Bash用于运行git ls-files、eza等结构扫描命令，Read用于读取 README 与文档。这既是一种权限收敛（避免预热阶段误用 Write/Edit 等工具），也是向模型明确"你此刻只需要观察和阅读"。
• description：用于向模型说明该命令的用途，是 Claude Code 在命令列表中展示并决定何时建议使用该命令的依据。

Instructions：三步入场流程

## Instructions - Run `git ls-files` to understand the codebase structure and file organization - Read the README.md to understand the project purpose, setup instructions, and key information - Provide a concise overview of the project based on the gathered context

三条指令对应三条明确的动作：

1. 运行git ls-files获取被 Git 跟踪的文件清单，快速摸清代码库结构——注意这里选择git ls-files而非find/ls，其优势是只列出受版本控制的文件，天然排除node_modules、构建产物等噪声目录；
2. 阅读根目录README.md，理解项目目的、安装方式与关键信息；
3. 基于前两步产出精炼的项目概览，作为整个预热流程的输出。

Context：内联上下文绑定语法

## Context - Codebase structure git accessible: !`git ls-files` - Codebase structure all: !`eza . --tree` - Project README: @README.md - Documentation: - @ai_docs/cc_hooks_docs.md - @ai_docs/uv-single-file-scripts.md

Context 节展示了 Claude Code 命令文件中两种核心的上下文注入语法：

• !前缀 + 反引号命令：如!git ls-files``，表示把该 Bash 命令的执行输出直接内联进上下文。eza . --tree用于生成带缩进的完整目录树（eza是ls的现代化替代，需要系统已安装）；两条命令形成互补——git ls-files给出受控文件清单，eza --tree给出可视化的目录层级全貌。
• @前缀 + 文件路径：如@README.md、@ai_docs/cc_hooks_docs.md，表示把对应文件的完整内容加载进上下文。这里选定的两份文档与项目主题强相关：cc_hooks_docs.md 是本仓库 Hooks 体系的权威说明，uv-single-file-scripts.md 则解释了本仓库几乎所有 Python 脚本采用的uv run --script单文件脚本模式——这两份文档能让新会话在预热阶段就理解整个仓库的两种核心技术约定（Hooks 事件机制与 uv 脚本规范）。

从源码结构看，这套"Instructions + Context"的组合是该仓库所有命令文件的通用模板：prime.md、build.md、plan.md等命令均遵循同一编排方式，prime_tts只是在其上增加了 TTS 收尾环节。

收尾交接：tts summary agent

命令最后一行是关键的设计转折点：

When you finish run the tts summary agent, and let the user know you're ready to build.

即：预热完成后，不再以纯文本汇报，而是调用 work-completion-summary Agent，把"上下文已加载、准备就绪"这一信息以极简语音形式播报给用户。该 Agent 的 frontmatter 定义如下：

name: work-completion-summary description: Proactively triggered when work is completed to provide concise audio summaries and suggest next steps. If they say 'tts' or 'tts summary' or 'audio summary' use this agent. ... tools: Bash, mcp__ElevenLabs__text_to_speech, mcp__ElevenLabs__play_audio color: green

其内部指令包含五个步骤：分析已完成的工作（限 1 句）、生成超精简总结（限 1 句）、追加 1 条下一步建议、调用mcp__ElevenLabs__text_to_speech生成语音文件（固定voice_id为WejK3H1m7MI9CHnIjW9K，保存到{current_directory}/output/work-summary-{timestamp}.mp3）、再用mcp__ElevenLabs__play_audio自动播放。它强调"ruthlessly concise"（每个词都必须有价值）、不要客套话、语态自然口语化——这些约束直接服务于语音播报场景。

这与仓库中定义的 tts-summary 输出风格 一脉相承：该风格要求"在每条回复末尾附上针对用户的音频总结"，并且给出可直接执行的命令行示例：

uv run .claude/hooks/utils/tts/elevenlabs_tts.py "Dan, I've created three new output styles to customize how you receive information."

两者共同构成"任务完成 → 语音播报"这一体验的完整闭环：tts-summary.md定义风格规范，work-completion-summary定义专用 Agent，prime_tts则在会话预热场景中实际触发它。

纵深：支撑语音总结的三层基础设施

prime_tts触发的 TTS 交接并非孤立功能，它建立在仓库 subagent-tts-summary-queue 方案 所规划、并已落地实现的三层基础设施之上。理解它们，才能真正掌握"预热 + 语音就绪"背后"如何保证多个 Agent 同时完成时不吵成一团"的工程细节。

第一层：文件锁队列 tts_queue.py

当多个子代理并行运行时，可能在同一时刻完成并触发语音播报，导致多条音频重叠播放。方案采用"文件锁 + 轮询重试"实现跨进程互斥，避免引入数据库或 Redis 等外部依赖。tts_queue.py 的核心 API 如下：

实现细节值得注意：

• 锁文件固定为.claude/data/tts_queue/tts.lock，与仓库既有的.claude/data/sessions/会话数据目录保持同一模式；
• 获取锁后会把{agent_id, timestamp, pid}以 JSON 写入锁文件，用于调试定位"谁在说话"；
• cleanup_stale_locks会先用os.kill(pid, 0)探测持有进程是否还活着——进程仍存活则即使超龄也不清理，避免误删活跃锁；只有确认进程已消亡才删除锁文件；
• 脚本同时提供命令行入口：tts_queue.py status|acquire <id>|release <id>|cleanup，便于人工诊断。

第二层：LLM 任务总结器 task_summarizer.py

仅播报"Subagent Complete"没有信息量，因此引入 task_summarizer.py 用 LLM 把子代理的任务描述转成口语化、个性化的完成播报。其核心函数：

def summarize_subagent_task(task_description: str, agent_name: Optional[str] = None) -> str:

• 模型选用claude-haiku-4-5-20251001（Haiku 4.5），max_tokens=100、temperature=0.7——方案文档明确说明选型理由是"快速且成本低，总结是适合 Haiku 的简单任务"；
• 提示词约束严格：直接称呼用户 "Dan"、控制在 20 词以内、聚焦"结果与交付价值"、禁止引号/格式/解释、只返回一句话；提示词中还内置了示例句式（如"Dan, authentication is ready with secure JWT token support."）；
• 容错策略完整：缺少ANTHROPIC_API_KEY时返回兜底文案"Subagent task completed"，API 抛异常时同样降级，绝不因总结失败而让语音播报中断（对应方案文档中的 Fallback Strategy）；
• 输出会做二次清洗（剥掉首尾引号、只取首行），并通过logs/subagent_debug.log记录每次调用的入参与结果，便于排查。

第三层：SubagentStop Hook 的集成编排

subagent_stop.py 是语音播报的总调度：它在 settings.json 中被注册为SubagentStop事件钩子：

"SubagentStop": [ { "matcher": "", "hooks": [ { "type": "command", "command": "uv run $CLAUDE_PROJECT_DIR/.claude/hooks/subagent_stop.py --notify" } ] } ]

其主流程（--notify模式下）依次执行：

1. 上下文提取：extract_task_context()从事件数据中取agent_transcript_path（缺省回退transcript_path），逐行解析 JSONL 转录文件，优先提取首条type == "user"消息的文本（支持字符串与 content blocks 两种形态，超 200 字符截断），拿不到则返回兜底"completed a task"；
2. LLM 总结：将提取到的任务上下文交给summarize_subagent_task(task_context, agent_name=agent_id)生成口语播报；命令行同时支持--summarize（默认开启）与--no-summarize（降级为固定文案"Subagent Complete"）两种模式，保证向后兼容；
3. 排队播音：先cleanup_stale_locks(max_age_seconds=60)清理孤儿锁，再acquire_tts_lock(agent_id, timeout=30)抢锁，抢到后调用播音函数，最后在finally中release_tts_lock确保异常时也不留锁；抢锁超时（30 秒）时仍会播音，但会写日志告警——这是"宁可重叠也不漏报"的工程取舍；
4. TTS 引擎降级链：get_tts_script_path()按ELEVENLABS_API_KEY→OPENAI_API_KEY→ 无密钥兜底的顺序选择引擎，对应 elevenlabs_tts.py、openai_tts.py、pyttsx3_tts.py三个脚本；播音以subprocess.run(["uv", "run", tts_script, message], timeout=10)方式调用，任何异常静默失败。

其中 elevenlabs_tts.py 使用 ElevenLabseleven_turbo_v2_5模型、固定音色WejK3H1m7MI9CHnIjW9K、输出mp3_44100_128，并把文本作为命令行参数直接合成播放——这正是prime_tts命令中"run the tts summary agent"最终落到用户耳边的技术链路。

将 prime_tts 模式迁移到自己的项目

结合本仓库的既有实现，你可以在自己的 Claude Code 项目中复刻这套"预热 + 语音就绪"模式，只需四步：

1. 编写预热命令：在.claude/commands/下新建 Markdown 命令，frontmatter 声明allowed-tools: Bash, Read与description；Instructions 节写"结构扫描 → 读 README → 汇报概览"；Context 节用!命令`` 与@文件语法绑定你的项目关键路径；
2. 准备 TTS 引擎：在.env中配置ELEVENLABS_API_KEY（或OPENAI_API_KEY），复用或仿写 elevenlabs_tts.py 这类uv run --script单文件脚本，即插即用；
3. 收尾交接：在命令末尾让模型调用你定义的 TTS 总结 Agent（可参考 work-completion-summary 的写法：固定音色、输出到output/work-summary-{timestamp}.mp3、播完即止）；
4. （可选）扩展到子代理：如果你有并行子代理场景，直接把 tts_queue.py + task_summarizer.py 集成进自己的SubagentStop钩子，即可获得"并发完成但逐个播报"的语音体验。

需要注意的是，上述脚本均依赖uv运行时（仓库内所有 Python 脚本采用uv run --script模式，依赖声明在脚本头部的# /// script块中），且fcntl文件锁仅适用于 Linux/macOS 类 Unix 环境；Windows 上需要替换锁实现。所有前提条件都以本仓库当前代码为准，迁移时请按你的实际环境验证。

【免费下载链接】claude-code-hooks-masteryMaster Claude Code Hooks项目地址: https://gitcode.com/GitHub_Trending/cl/claude-code-hooks-mastery