Workspace Delta

​

目的

这页用于汇总 当前工作区 相对各代码仓库本地 main 分支的结构性差异，方便在合并前统一更新技术文档。

​

快照

​

跨仓库主题

​

1. 音频从“附属能力”升级为一等媒体类型

• 后端新增 generateMusic、generateInstrumental、addVocals 三个工具，以及 /music/task、/music/submit 管理接口。
• thread_version 的 audios JSONB 成为音频状态单一事实来源，和视频的 videos JSONB 角色一致。
• Feed、Timeline、Rewind、Generator、详情页都开始显式区分 image / video / audio 三类媒体。
• 前端不再只把音乐当作聊天消息卡片，而是有独立播放器、工具栏、媒体选择器和发布链路。

​

2. Feed 从图片/视频扩展为 mixed-media

• feed.media_type 现在稳定支持 audio。
• 发布音频时，会将音频文件和封面从 message storage 复制到 feed storage，再由 feed API 动态补签名 URL。
• Feed 列表、Feed 详情、用户主页 feed、分享 metadata 都增加了音频分支。
• Feed 详情页不再使用原生 <audio> 作为唯一播放方式，而是切到统一的 AudioPlayerCard。

​

3. Generator 壳层出现明显移动端重构

• 新增移动端专用 mobile-header、mobile-tool-panel、mobile-audio-tool-bar。
• 画布安全区从静态高度推断改为基于 header / bottom bar 的动态计算。
• 移动端聊天输入栏使用单独的 collapsed-height 语义；展开输入不再影响主画布安全区。
• 多个 selector 统一为底部弹层风格，并针对移动端补了固定底部留白。

​

Kira Backend

​

AI / 模型 / 计费

• ultra 档位的主 LLM 路由被收敛到 pa/grok-4-1-fast-reasoning，不再保留单独的 xAI 分支语义。
• analytics 和 billing 扩展了音乐工具类型，覆盖 generateMusic、generateInstrumental、addVocals。
• tool 集合从“图像 + 视频”为主，扩展为“图像 + 视频 + 音频”。

建议对照文档：

• /kira-be/model-selection
• /analytics/backend

​

音乐任务与 NATS

• 新增音乐工具：
  • generateMusic
  • generateInstrumental
  • addVocals
• agent onFinish 会把 pending 音乐任务发布到 tasks.music.{provider}.{taskId}。
• 新增 musicCleanup，与视频清理逻辑对齐，用于 rewind / thread 删除时清理音乐任务与存储文件。
• hono/music 新增任务查询和重新提交入口，职责上与 video 模块对齐。

建议对照文档：

• /kira-be/music-pipeline
• /kira-nats/index
• /kira-be/api/music/task
• /kira-be/api/music/submit

​

Feed / Timeline / User Feed

• feed API、user feed API、thread timelines API 都新增音频分支。
• ResponseFeedAudioSchema / FeedAudioSchema 扩展了音频标题、歌词、封面、时长、同步歌词等字段。
• Timeline 不再只聚合图片/视频；当前工作区会返回服务端排好序的 mixed-media mediaItems。
• publish/audio 现在和 publish/video 一样，执行复制、审核、embedding、落表、埋点这整条链路。

建议对照文档：

• /kira-be/feed-pipeline
• /kira-be/api/feed/list
• /kira-be/api/feed/get
• /kira-be/api/user/feed
• /kira-be/api/thread/timelines

​

Kira Web

​

音频工作区

• 新增核心组件：
  • AudioPlayerCard
  • AudioPlayerControls
  • CanvasAudioPlayer
  • useAudioPlayer
  • music-generation-card
• 生成器页和 rewind 页都能在主画布中渲染完整音频播放器。
• 音频播放器支持封面/CD 动画、歌词视图、同步歌词、导出和 mixed-media 切换。

建议对照文档：

• /kira-web/audio
• /kira-web/generator

​

Selector / Toolbar 体系

• 新增 selector：
  • MusicSelector
  • InstrumentalSelector
  • AddVocalsSelector
  • GenerateImageSelector
• 新增音频工具按钮：
  • music-generate
  • instrumental-generate
  • add-vocals
  • audio-export
• PC 和移动端都增加了音频工具栏分支。

建议对照文档：

• /kira-web/selector
• /kira-web/ui

​

Feed / Timeline / Rewind / 分享页

• Feed 列表卡片和详情页都新增了音频分支。
• Feed 详情页现在通过 FeedAudioPlayer 复用生成器里的 AudioPlayerCard。
• Timeline 卡片的媒体展示不再只依赖前端本地拼接排序，而是开始消费服务端 mixed-media 聚合结果。
• Rewind 页面支持将音频作为当前主媒体切换与回放。

建议对照文档：

• /kira-web/routes
• /kira-web/audio

​

移动端壳层与安全区

• GeneratorThreadLayout 的移动端结构基本重排。
• 新增动态 safe-area 计算，避免移动端 header、chat bottom bar、tool panel 与主画布互相挤压。
• 聊天输入栏、移动端工具面板、音频播放器预览都围绕这一套安全区重新适配。
• 移动端 feed 详情页也补上了与 PC 对齐的音频播放器体验。

建议对照文档：

• /kira-web/responsive
• /kira-web/generator

​

Kira Music Worker

当前工作区相对本地 main 没有额外结构性偏差，因此这轮文档更新无需单独再写一份“worker 分支 delta”。 但在系统行为上，kira-be 与 kira-web 当前都已经依赖以下 worker 能力：

• 音乐任务 provider：suno_unofficial / suno_instrumental / suno_add_vocals
• 后处理：封面、歌词、ID3、上传、通知
• audio_status 实时推送

深度说明仍以这些页面为准：

• /kira-be/music-pipeline
• /analytics/backend

​

建议优先回补的细分文档

如果要继续把增量信息拆回专题页，建议按这个顺序补：

1. /kira-be/music-pipeline
2. /kira-be/feed-pipeline
3. /kira-be/model-selection
4. /kira-web/audio
5. /kira-web/generator
6. /kira-web/responsive
7. /kira-web/selector

​

本页用途

这页不是永久架构真相，而是 当前工作区相对 main 的差异清单。等相关改动合并后，建议把本页中的条目回填到各专题文档，再把这里收缩成简短变更记录。