MusePi 帮助

MusePi 是本地优先的 AI 编程助手（oh-my-pi 的定制分支）：终端 TUI/CLI + 桌面
GUI（Electron，可固定看板到桌面）+ 云端协作渲染。回答产品问题时先确定话题，
再按下面路由回答；不确定时读本地文档（仓库 docs/）再答，不要编造。

产品构成

• TUI/CLI：musepi 命令启动终端会话；斜杠命令（/board 看板、/pause
  暂停、/steer 转向、/tasks 任务、/extensions 扩展）。
• 桌面 GUI：packages/desktop-app（Electron）——daemon 架构：GUI 连 daemon
  （端口 8300）驱动会话；musepi --gui 或应用启动。
• 看板（dashboard）：widget 卡片墙——GUI 侧栏「看板」进入（画布随窗口自适应缩放 + ChromaGrid 组光效）；board 工具读写（list/get/schema/save，agent 可建板/加卡）；卡片可拖拽/缩放（网格 92×44、gutter 12）；组件即卡（无外框）。
• 对话内联 widget：widget 工具在对话里渲染活卡片（计算器/滑杆/行情/
  待办/番茄钟/视频等），交互结果可"发送给对话"回传给 agent。

配置与目录

• 配置：~/.musepi/agent/config.yml；设置：~/.musepi/agent/settings.json
• 技能：~/.musepi/agent/skills/<name>/SKILL.md（用户级，设置里可开关）
• 扩展：~/.musepi/agent/extensions/<name>/index.ts（用户级）；MCP：.mcp.json
• 预设（modes）：~/.musepi/modes/<id>.json —— 命名预设 = 扩展工具集白名单
  • 提示词区块 + settings 覆盖（内置 standard / minimal 模板首次访问自动生成）
• 上下文：从 cwd 向上找 AGENTS.md（项目约定）
• 看板数据：~/.musepi/boards/boards.json（daemon 共享看板存储，GUI 同源）

常见问答要点

• 给 MusePi 加功能/工具/命令/hook/插件（开发扩展）：读 musepi-extension-dev
  skill（skill://musepi-extension-dev）——六种扩展形态 + 快速路径 + 文档路由表。
• 预设/模式（Work/Design/Minimal）是什么：命名预设 = 扩展白名单 + 提示词区块
  • settings 覆盖的组合（~/.musepi/modes/<id>.json）。GUI 欢迎页（输入框上方
    项目选择旁）chip 选择，创建会话时应用；TUI/CLI 用 --preset <id> 启动，
    会话内 /preset 查看当前预设；设置 → 智能体 → 预设 管理（卡片面板，
    校验/删除；modes.validate 供 agent 自检）。极简模板 = extensions: [] +
    promptComplete（固定提示词）+ 关压缩。
• 扩展中心两个分类：OMP Extension Packages（OMP 生态扩展包，extensions:
  设置/--extension）+ MusePi Extensions（自有扩展系统：TS 模块 + manifest，
  ~/.musepi/agent/extensions）—— 两者独立 tab、并存。
• 怎么查用量/配额：TUI 斜杠 /usage（每供应商凭证并排 + 最右合计列，供应商按
  用量最低优先）；桌面 GUI 输入 /usage 弹用量面板（同款并排视图）、会话输入框旁
  的上下文圆环悬浮显示供应商配额块、托盘菜单底部用量区（Token 合计 + 每供应商
  窗口条）。用量数据磁盘缓存 5 分钟，刷新失败时显示上次快照——重复查看不重复请求。
• 看板卡片出不来了/空白：确认 daemon 在跑（GUI 会自启）；检查卡片
  widget 类型是否在注册表（设置→技能/看板 tab）；历史数据卡（fx/stocks/
  history）需要网络，离线时显示兜底。
• GUI 没反应：daemon 长驻——改 daemon 源码后必须重启 daemon 才生效
  （GUI 菜单"重启 daemon"）；kill 后 Electron 不会自动 respawn。
• 音效没有：系统策略限制——CDP 合成输入不产生 user activation，音效只在
  真实点击下播放（已知限制，非故障）。
• pin 到桌面：看板卡片 pin 后窗口按卡比例缩放（≤560 宽），拖拽条是
  hover 悬浮的，平时透明。
• 许可/订阅：MusePi 无内置订阅；模型密钥走 provider 配置
  （~/.musepi/agent/config.yml）。

回答纪律

• 先给结论，再给路径/命令；引用具体目录或文件。
• 产品问题不要泛化到通用 AI 教程；不知道的查文档或源码再答。
• 涉及 GUI 视觉/行为细节时，以 docs/gui-design.md / docs/gui-implementation.md
  为准（仓库内）。