session-start

你的任务

运行完整的会话启动流程，并向用户报告项目状态。

---

会话启动技能

执行 8 步会话启动流程，以初始化工作会话。

---

步骤 1：验证设置

快速检查依赖项：

~/.bitwize-music/venv/bin/python3 -c "import mcp.server.mcpserver" 2>/dev/null || ~/.bitwize-music/venv/bin/python3 -c "import mcp.server.fastmcp" 2>/dev/null && echo "MCP ready" || echo "MCP unusable"        # macOS/Linux/WSL
~/.bitwize-music/venv/Scripts/python.exe -c "import mcp.server.mcpserver" 2>/dev/null || ~/.bitwize-music/venv/Scripts/python.exe -c "import mcp.server.fastmcp" 2>/dev/null && echo "MCP ready" || echo "MCP unusable" # Windows (Git Bash; cmd/PowerShell: %USERPROFILE%\.bitwize-music\venv\Scripts\python.exe)

• 如果 MCP 无法使用：立即停止，并建议运行：/bitwize-music:setup mcp（缺少 SDK，或 SDK 版本早于 1.28.1）。探测两个服务模块，切勿直接使用 import mcp：2.x 从 mcp.server.mcpserver 提供 MCPServer，1.x 从 mcp.server.fastmcp 提供 FastMCP，服务接受其中任一种；但即使两个模块都不存在，直接使用 import mcp 仍会成功，导致在服务无法启动的安装环境中误报健康
• 如果缺少配置文件（~/.bitwize-music/config.yaml 不存在）：建议运行 /bitwize-music:configure
• 设置完成前不要继续

步骤 1.5：健康检查

使用 health_check MCP 工具（一次调用即可检查虚拟环境包、技能注册和专辑 slug 冲突）：

虚拟环境结果（来自 result.venv）：

• status: "ok" → 静默继续
• status: "stale" → 警告并列出不匹配项和修复命令，然后继续会话
• status: "no_venv" → 停止，并建议运行 /bitwize-music:setup
• status: "error" → 发出警告并继续

技能注册结果（来自 result.skills）：

• status: "ok" → 静默继续
• status: "stale" → 发出警告：列出缺失和无效的技能名称，并显示修复信息
• status: "no_cache" → 警告插件缓存未找到，然后继续

专辑 slug 冲突结果（来自 result.collisions）：

• status: "ok" → 静默继续
• status: "collision" → 发出警告：列出每个 slug 及其保留和被覆盖的流派，显示修复方法（使用 /bitwize-music:rename 重命名一张专辑或移动其目录，然后运行 rebuild_state），然后继续会话

步骤 2：加载配置

读取 ~/.bitwize-music/config.yaml。

如果缺少该文件，告知用户运行 /bitwize-music:configure。

步骤 3：加载覆盖项

从配置中读取 paths.overrides（默认值：{content_root}/overrides）：

• 检查是否存在 {overrides}/CLAUDE.md — 如果存在，则遵循其中的指示
• 检查是否存在 {overrides}/pronunciation-guide.md — 如果存在，则记录
• 如果缺少，则静默跳过（覆盖项为可选项）

步骤 4：加载状态缓存

读取 ~/.bitwize-music/cache/state.json：

• 如果文件缺失、损坏、架构不匹配或配置已更改：通过 MCP 重新构建

  rebuild_state()
  

步骤 4.5：检查插件升级

调用 get_pending_migrations MCP 工具。该工具会将已安装的插件版本与状态中的 last_migrated_version（上次处理迁移的版本，与仅记录已安装版本以供显示的 plugin_version 不同）进行比较，并返回已解析和排序的待处理说明。

1. 如果 pending 为空（reason: "current"，或因无法从 plugin.json 读取已安装版本而出现 reason: "unknown"）：无需操作。
2. 如果 pending 不为空（reason: "upgrade" 或 "untracked"）：按顺序处理每项迁移中的 actions：
   • auto：静默执行（先运行 check；如果返回 0，则跳过）
   • action：显示说明，并在执行前征求用户确认
   • info：向用户显示
   • manual：向用户显示操作说明
3. 处理完所有说明后，调用 acknowledge_migrations（不传参数即确认截至已安装版本的所有迁移），避免这些说明在下次会话中再次出现。
4. 报告：“已升级至 Y”，并概述已采取的操作。

reason: "untracked" 表示该状态早于迁移跟踪机制；截至已安装版本的完整待处理记录会显示一次，然后由 acknowledge_migrations 清除。不要仅通过重新构建状态来清除迁移——重新构建会保留待处理状态；只有 acknowledge_migrations 会记录你已处理这些迁移。

第 5 步：（已移除）

技能模型检查不再是会话启动流程的一部分。技能使用层级别名（opus/sonnet/haiku），会自动跟踪前沿模型；测试套件（/bitwize-music:test）会确保模型/effort 规范，因此发布新的 Claude 模型时无需手动检查模型。

第 6 步：根据状态缓存生成报告

使用 state.json 中的数据，报告：

专辑创意

根据 state.ideas.counts，按状态显示数量（待处理、进行中等）。

进行中的专辑

筛选 state.albums 中状态为 "In Progress"、"Research Complete"、"Complete" 的专辑。

对于每张专辑，显示：

• 专辑名称、流派、状态
• 曲目进度（已完成/总数）

待处理的来源核验

从 state.albums 中查找 sources_verified 为 "Pending" 的曲目。

如果找到任何曲目，发出警告："这些曲目的来源尚未核验——核验完成前无法生成。"

上次会话上下文

根据 state.session 显示：

• 上次处理的专辑
• 上次所处阶段
• 待处理操作

第 7 步：显示情境提示

根据状态显示一条相关提示：

条件	提示
不存在专辑	"试试 /bitwize-music:tutorial，创建你的第一张专辑"
存在创意但没有专辑	"你有专辑创意！使用 /bitwize-music:album-ideas list 查看"
存在进行中的专辑	"从上次离开的地方继续：/bitwize-music:resume <album-name>"
已加载覆盖项	"已从 {overrides}/ 加载自定义覆盖项"
缺少覆盖项	"使用覆盖文件自定义工作流——请参阅 /reference/overrides/"
存在待处理核验	"继续生成前需要核验来源"

另外，随机显示一条通用提示（依次轮换）：

• "询问“我接下来该做什么？”以获取工作流指导"
• "使用 /bitwize-music:resume 快速返回专辑"
• "研究员技能会协调 10 个专用子技能，开展深入研究"
• "生成前检查发音——Suno 无法根据上下文推断发音"
• "使用 /bitwize-music:clipboard 复制歌词/提示词到 Suno"
• "使用 /bitwize-music:mastering-engineer 母带处理音频，获得专业效果"

第 8 步：询问

以这句话结尾："你想处理什么？"

---

报告格式

SESSION START
=============

Setup: MCP ready, config loaded
Health: [venv ok, skills ok, no collisions | warnings listed]
Overrides: [loaded from {path} | not found (optional)]
State: [loaded | rebuilt | error]

ALBUM IDEAS
  Pending: X | In Progress: Y

IN-PROGRESS ALBUMS
  [album-name] (genre) - Status [X/Y tracks]
  [album-name] (genre) - Status [X/Y tracks]

PENDING VERIFICATIONS
  [album-name]: track-01, track-05

LAST SESSION
  Album: [name] | Phase: [phase]
  Pending: [actions]

TIP: [contextual tip]

What would you like to work on?

---

请记住

1. 不要跳过步骤——每个步骤都关系到会话完整性
2. 必要时重建状态——过时的状态会导致错误建议
3. 保持简洁——这是状态报告，不是对话
4. 提醒核验事项——未经核验的来源会阻止生成
5. 只给一条提示，而不是五条——选择与当前状态最相关的提示