| name | project-ideas-log |
| description | 在项目根目录维护以「idea 阶段」为单位的开发日志，解决跨设备、多项目并行时的上下文恢复问题。当用户要求为某个项目初始化这套体系（创建 docs/ideas/ 和第一个 md）、为已有项目补建、新增一个 idea 阶段文件、或归档当前阶段开启新阶段时使用。每个项目独立维护,按 idea 周期累积编号文件，序号最大的文件即为当前进行中。 |
这个 skill 在每个项目根目录维护 docs/ideas/ 文件夹，按 idea 阶段顺序累积编号 md 文件，每个文件是一个完整的开发周期记录。目标是让一周后回到项目时，10 分钟内恢复完整上下文。
核心原则
四条原则，顺序即优先级，后写的规则不能违反前面的：
- 位置即状态 — 能用文件名/位置表达的，不开字段
- 约定优于配置 — 一条规则覆盖所有情况，胜过逐项标注
- 产物导向 — 描述「做完会得到什么」，不描述「要去做什么」
- 未来的自己优先 — 文档为一周后的自己而写
每次想新增字段、段落、标记时先用这四条审一遍。
目录结构
项目根/
└── docs/
└── ideas/
├── 001-初版MVP.md
├── 002-用户系统重构.md
└── 003-Android适配.md ← 最大序号即当前活跃
序号最大的文件 = 当前进行中，其他全是已完成。不创建 INDEX、不加状态字段、不加 emoji 前缀、不记录结束时间。
文件命名
格式：NNN-简短主题.md
NNN：三位数字，从 001 开始，保证字典序等于时间序简短主题：3–10 个字，能一眼认出在做什么
不使用日期开头（idea 跨度可能从几周到几个月，日期会失真）。不加状态前缀（位置即状态）。
文件结构
每个文件包含四个段落，固定顺序：
# NNN - 简短主题
> 开始：YYYY-MM-DD
## 🎯 这个阶段的产物
## 📋 TODO
## 📖 详细说明
## ✍️ 当前在做
🎯 这个阶段的产物
一段话，描述「这个阶段完成时，项目会得到什么」。
- ✅ "Biu 在 Android 上可安装运行，核心功能（播放/搜索/收藏）和 Mac 端体验一致；锁屏后台播放正常"
- ❌ "适配 Biu 到 Android 平台"（过程描述，不是产物）
产物描述可验证（达成则归档开新阶段），过程描述会无限拖延。
📋 TODO
动态清单，随时增删改。每条用一个中文文本标签开头：
| 标记 | 含义 |
|---|
[ ] | 待做 |
[进行中] | 正在做（同时最多一条） |
[x] | 已完成 |
[等 Win] | 要 Windows 才能验证（按实际平台替换：[等 iOS] / [等服务端] 等） |
[阻塞] | 因其他原因卡住，标签后简短写明原因 |
每条 todo 是一个功能/任务标题，不展开为多个子条目。需要细节去 📖 详细说明 写。
TODO 段开头加一行图例 blockquote，让文件自解释：
> 标记说明：`[ ]` 待做 · `[进行中]` 正在做（同时最多一条）· `[x]` 已完成 ·
> `[等 Win]` 要 Windows 才能验证 · `[阻塞]` 因其他原因卡住
TODO 段是「下一步要做的事」，不是「这个阶段做过的所有事」。已完成的条目处理见下文「维护规则」。
📖 详细说明
只对大功能或有非显然决策的 todo 展开，不需要每条 todo 都写。
每条详细说明三个子段：
### TODO 标题
**目标效果**：用户视角描述能感知到的效果，可量化更好。完成标准。
**复现**（仅 bug / 回归类条目需要）：能让一周后的自己 5 分钟内重现
现场的最短路径。环境、操作步骤、看到的报错原文字串（不用截图，字串
可 grep，截图不行；要截图就放 `docs/screenshots/` 用 markdown 引用）。
**已经做过的事**（避免重新踩坑）：
- 已经落地的关键决策（带 commit hash 更好）
- 已经被否过的方案 / 走过的死路 / 用户明确拒绝过的方向
- 现有约束条件（"PS exit code 必须是 0" / "失败弹窗不能再加按钮" 之类）
「已经做过的事」是 idea log 区别于普通 TODO 列表的核心。它不是"接下来
怎么做的方案"（那是动手时才决策的），而是"已经决策完不要再讨论的事"。
让下次回来翻 git log 找 commit hash 这种低效活能跳过；让下次想出某方案
的自己先扫一眼是否已经被否过。
不写技术实现细节（让代码自己说话）。不预先写修法思路 / 根因方向
（动手时再决策，写在这里要么过时要么误导）。
✍️ 当前在做
一两句话，指向 TODO 里 [进行中] 那一项的具体下一动作。
- ✅ "打开 player_native.ts:88，把 audioFocus 监听接进来"
- ❌ "继续做 Android 播放器适配"（无信息量）
单独成段而非挂在 todo 下，是因为这段是「恢复上下文的入口」，打开文件第一眼看到才有用。
维护规则
何时新建文件
当前文件「🎯 产物」描述的目标达成时，归档当前文件并新建序号 +1 的文件。
归档动作：
- 把进行中的
[进行中] 改成 [x]
- 清空「✍️ 当前在做」段落内容
- 不改文件名，不加完成标记
何时不新建文件
当前阶段有新想法、要修 bug、临时插入小任务 → 加到当前文件 TODO。
判断标准：新事项是否服务于当前文件的「🎯 产物」描述？
- 是 → 加到当前 TODO
- 否 → 这条事项 hold 着，当前阶段完成后再开新文件
已完成的 TODO 怎么处理
TODO 段是「下一步」，不是历史清单。某条 todo 完成时：
- 决策密度高（涉及"已经做过的事"段记载的关键决策） → 留
[x] 当锚点
- 仅是机械工作（一次性脚本、纯 UI 调整） → 直接从 TODO 段移除
整文件归档时所有 [进行中] 必须改 [x]；其他 [x] 留着作为该阶段的成果清单。
已完成的文件
- 不删 — 它们是项目的思考史
- 不改 — 除错别字外，归档后只读
反模式
以下设计不要使用：
INDEX.md — 文件列表本身就是索引- 状态字段 / 状态前缀 / 文件级 emoji 标记 — 位置即状态
- 结束时间 — 下一个文件的开始时间即此文件的结束时间
- 单独的「下次开机第一件事」段落 — 已并入 ✍️ 当前在做
- 单独的「阻塞/卡点」段落 — 已并入 TODO 的
[等 Win] [阻塞] 标记
- 给每条 todo 都写详细说明 — 只对大功能 / 有非显然决策的写
- 在 TODO 里写技术实现步骤 — 颗粒度过细会变成假工作
- 详细说明里预先写修法思路 / 根因方向 — 动手时才决策
- 详细说明里嵌截图 — 字串可 grep，截图不行
- 完成的 todo 全部堆在 TODO 段里 — TODO 是"下一步"，有决策价值的进
"已经做过的事"，没价值的移除
初始化新项目
执行：
mkdir -p docs/ideas
在 docs/ideas/001-<主题>.md 中按下面的完整模板填写四段内容。
完整模板
# 003 - Android 适配
> 开始：2026-05-08
## 🎯 这个阶段的产物
Biu 在 Android 上可安装运行，核心功能（播放/搜索/收藏）和 Mac 端
体验一致；锁屏后台播放正常。用户切到其他 App 时音乐不中断。
## 📋 TODO
> 标记说明：`[ ]` 待做 · `[进行中]` 正在做（同时最多一条）· `[x]` 已完成 ·
> `[等 Win]` 要 Windows 才能验证 · `[阻塞]` 因其他原因卡住
- [x] Android 播放器内核适配
- [进行中] 通知栏 MediaSession
- [等 Win] CapacitorHttp 在 Win 构建产物里的 CORS 行为验证
- [ ] 深色模式适配
- [ ] Release 构建签名
## 📖 详细说明
### Android 播放器内核适配
**目标效果**：锁屏继续播放、通知栏可控制、切歌响应 < 200ms。
**已经做过的事**（避免重新踩坑）：
- a1b2c3d 走原生桥方案 —— Web Audio 在 Android 后台会被挂起,
必须 MediaSession 保活
- 用户明确否过"用 Service Worker 维持播放"，那条路不要再走
- 测试发现 Android 9 以下 MediaSession 行为不一致，最低支持 Android 10
### CapacitorHttp 验证
**目标效果**：搜索 / 收藏请求在 Win 端构建产物里和 Mac 端响应一致。
**复现**：装 Win 端 release apk 后，进搜索页输任意关键词，看
DevTools Console 是否报 CORS 错误。Mac 端不报。
**已经做过的事**（避免重新踩坑）：
- e4f5g6h 迁到 CapacitorHttp 走原生网络栈（fetch 在 Android WebView
里 CORS 行为和 Mac 不一致）
- 默认 X-Requested-With 头会被某些 API 拒，已经在 capacitor.config.ts
里加了白名单
## ✍️ 当前在做
打开 player_native.ts:88，把 audioFocus 监听接进来。
完成后跑 `npm run android:dev` 看锁屏控制能不能弹出。
