project-ideas-log

name	project-ideas-log
description	在项目根目录维护以「idea 阶段」为单位的开发日志，解决跨设备、多项目并行时的上下文恢复问题。当用户要求为某个项目初始化这套体系（创建 docs/ideas/ 和第一个 md）、为已有项目补建、新增一个 idea 阶段文件、或归档当前阶段开启新阶段时使用。每个项目独立维护,按 idea 周期累积编号文件，序号最大的文件即为当前进行中。

这个 skill 在每个项目根目录维护 docs/ideas/ 文件夹，按 idea 阶段顺序累积编号 md 文件，每个文件是一个完整的开发周期记录。目标是让一周后回到项目时，10 分钟内恢复完整上下文。

核心原则

四条原则，顺序即优先级，后写的规则不能违反前面的：

1. 位置即状态 — 能用文件名/位置表达的，不开字段
2. 约定优于配置 — 一条规则覆盖所有情况，胜过逐项标注
3. 产物导向 — 描述「做完会得到什么」，不描述「要去做什么」
4. 未来的自己优先 — 文档为一周后的自己而写

每次想新增字段、段落、标记时先用这四条审一遍。

目录结构

项目根/
└── 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 的文件。

归档动作：

1. 把进行中的 [进行中] 改成 [x]
2. 清空「✍️ 当前在做」段落内容
3. 不改文件名，不加完成标记

何时不新建文件

当前阶段有新想法、要修 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` 看锁屏控制能不能弹出。