Pin Comments · 多人评论 Skill

给任意 HTML demo 加「贴 Pin 写评论」的多人协作能力。可视化形态参考 Figma 评论：右下角三个圆 icon FAB（评论 / 清单 / 隐藏 Pin），鼠标点页面任意位置落 Pin，写评论 → 所有人实时看到。支持 Figma 风格键盘快捷键（C / V / L / H / Esc）。

何时启用

• 用户说「给这个 demo 加评论」「加 pin-comments」「让别人能评论」「多人在线评论」「Figma 那种评论」
• 用户做完 demo 想发出去给同事 / 老板 / 业务方评审，需要他们能直接在页面上标注问题
• 已有 demo 缺少反馈通道，用户希望最低成本接入

关键概念（先对齐再动手）

接入前必须问用户的事

接到「加评论」需求时，先用一条消息问清楚以下四件事，不要直接动手：

1. 是否已有 Supabase 项目可用？
   • 已有 → 让用户提供 Project URL 和 anon public key
   • 没有 → 走 ~/.cursor/skills/pin-comments/SUPABASE_SETUP.md 的引导
2. projectKey 起什么名？ 给一个建议（按当前文件夹/项目名取 kebab-case），让用户确认
3. 要给项目里哪些页面接？ 列出仓库里所有 HTML 页面，问「全部都加，还是只加某几个？」
4. 每个页面的 <title> 是否都已经写得清楚？ v0.4 起跨页清单会展示页面标题，title 是 "Document" 这种默认值会让别人没法分辨。如果用户嫌麻烦，至少建议给每个页面一个人话 title。

只有四个答案都明确了再动手。

接入步骤

1. 复制脚本和 Supabase 客户端到目标项目

把 ~/.cursor/skills/pin-comments/assets/pin-comments.js 复制到目标项目，建议路径 <project>/shared/pin-comments.js（如果项目结构不同，跟用户确认放哪）。

2. 在每个要接评论的 HTML 页面底部插入接入代码

参考 ~/.cursor/skills/pin-comments/assets/snippet.html，在 </body> 前插入：

<!-- pin-comments: 多人评论 -->
<script>
  window.PIN_COMMENTS = {
    url: 'https://YOUR-PROJECT.supabase.co',     // Supabase Project URL
    anonKey: 'YOUR_ANON_KEY',                     // anon public key
    projectKey: 'your-project-slug'               // 按项目命名，同一项目所有页面用同一个值
    // pageKey: 自动取 location.pathname，无需手动设
  };
</script>
<script src="https://cdn.jsdelivr.net/npm/@supabase/supabase-js@2"></script>
<script src="./shared/pin-comments.js"></script>

注意：

• projectKey 的值在同一仓库的所有页面里必须保持一致，否则评论无法跨页面汇总
• 路径 ./shared/pin-comments.js 视项目结构调整
• 绝不把 anonKey 硬编码到 README / 公开文档里。anon key 本身可公开，但建议用户知情同意

3. 让用户初始化 / 升级 Supabase

根据用户当前情况选不同的 SQL：

判断方法：让用户在 SQL Editor 跑 select column_name from information_schema.columns where table_name='comment_pins';，看里面有没有 page_title。没有就跑 v0.3→v0.4 增量迁移；连 project_key 都没有就跑全量重建。

重要：v0.3 → v0.4 迁移会改 page_key 的存储格式（/some/path/page.html → page.html），目的是让同一页面在多环境部署下评论不分裂。如果用户 v0.3 时代用过显式 pageKey（不带 / 的字符串），不会被影响。

4. 验证清单

接入完成后，主动告诉用户验证步骤：

FAB 与快捷键

• 打开页面，右下角应出现 3 个白底圆 icon 按钮（💬 评论 / ☰ 清单 / 👁 隐藏 Pin），垂直排列
• hover 任一按钮 ~250ms 后，左侧浮出黑底 tooltip，带 kbd 键帽样式的快捷键（如「评论清单 [L]」）
• 按键盘 C 进入评论模式（💬 按钮变蓝、icon 切成箭头光标、鼠标变十字），再按 C 或 V 或 Esc 退出
• 按 L 打开/关闭清单抽屉；按 H 切换隐藏所有本页 Pin（👁 切成 eye-off 灰色）
• 在评论 textarea 里输入「c v l h」不会触发快捷键（防误触验证）

评论与跨页

• 进评论模式 → 任意位置点击 → 弹出输入框 → 填昵称、写评论、按 ⌘/Ctrl+Enter 发送
• 用另一个浏览器（或无痕窗口）打开同一页面，5 秒内应能看到刚才的 Pin
• 打开抽屉，标题行右侧应有视图 dropdown「全项目 N ▾」，默认停在「全项目」；点开 dropdown 切换到「本页」
• 状态筛选 chip 在第二行，数字为 0 的状态（如「已修改」「不做」）只显示标签 + 字色变浅，但仍可点
• 在 A 页面留一条评论，跳到 B 页面打开抽屉，「全项目」视图应能看到 A 的那条，且带「↗ A 页面标题」的橙色徽章
• 点 B 页面抽屉里 A 的那条评论 → 浏览器跳到 A 页面 → A 页面自动滚到对应位置并弹出评论卡片（URL 带 ?pc=<pinId>，跳转完成后会自动清掉）
• FAB 💬 上的橙色徽章只显示本页待修改数（>0 时显示，0 时隐藏），不会被全项目几十条吓到

跨环境（关键）

• 本地 dev server 留的评论，部署到 GitHub Pages 后同事在 GH Pages 上点这条评论也能跳转且不出现两份相同页面的评论。原因：v0.4 把 page_key 默认值改成了文件名，new URL(pageKey, location.href) 让浏览器以当前页为 base 自动算相对路径，三种部署形态（本地 / GH Pages 子路径 / file://）都 OK

常见问题（用户问起时回答）

Q: 抽屉里跨页评论太多看花眼怎么办？ A: 标题行右侧 dropdown 切回「本页」即可只看当前页。状态筛选 chip 独立生效，可以在「全项目 + 待修改」组合下专门刷待办。

Q: 视图切换为什么用 dropdown 而不是 segmented？ A: 早期版本是 segmented，但实际使用中：(1) 副标题/segmented/状态筛选三层信息冗余、占用一半抽屉头部高度；(2)「视图切换」是低频操作（多数人停在一种视图扫一段时间），不必常驻成胖按钮。改成 dropdown 后头部从 4 行缩成 2 行。状态筛选保留 chip 是因为它高频（评审最关心「待修改还有几条」），不能藏。

Q: 快捷键 C/V/L/H 怎么让用户发现？ A: 三个 FAB 按钮 hover 250ms 后会自动浮出 tooltip，带 macOS 风格 kbd 键帽 chip 显示快捷键。这是发现入口。如果还需要更强的引导（首次访问时 5 秒强提示），可以让用户提需求再加。

Q: 跨页跳转怎么实现的？刷新会丢吗？ A: 用 ?pc=<pinId> query 参数跳转。URL 通过 new URL(pageKey, location.href) 以当前页为 base 自动相对解析，所以本地 dev server / GitHub Pages 子路径 / file:// 三种形态都能正确算出目标 URL。落地页加载完数据后自动 openCard 并把 query 清掉（history.replaceState），不污染浏览历史，刷新当前页也不会再次弹出。如果 pin 在数据库已被删，会安静地清掉 query，不报错。

Q: 我本地 dev 写的评论 push 到 GitHub Pages 后能正常显示吗？ A: 能，前提是已经升到 v0.4。v0.4 把 page_key 默认值由 location.pathname（带路径前缀）改为「文件名」，避免了同一页面在两种环境下生成两个不同 page_key 的分裂问题。如果你之前在 v0.3 写过评论，跑 migrate-v0.3-to-v0.4.sql（幂等）会把老数据 page_key 自动归一成文件名。

Q: 清单里页面名显示成 /03-wiki-entry.html 太丑？ A: 给页面 <title> 起个人话名（如「Wiki 详情页」），新评论自动带上；或者在配置里显式 pageTitle: '...'。老评论的 page_title 是 null，会回落显示 pageKey，不会报错。

Q: anon key 公开了别人能删我评论吗？ A: 能。匿名 RLS 允许任何持 anon key 的人删评论。这套方案只适合评审型 demo，不要用在生产数据上。如果担心，可以临时设置 expires_at 或 IP 限制，详见 SUPABASE_SETUP.md。

Q: 我把 anon key 提交到 GitHub 了会出事吗？ A: anon key 本身设计上就是可公开的（前端必须暴露），不算泄露。真正敏感的是 service_role key，那个绝不能进前端。

Q: 多个 demo 共用一个 Supabase 项目，免费额度够吗？ A: 够。Supabase 免费层 500MB DB / 200 万 Realtime 消息每月。按一条评论 200 字节算，能存 200 万条；按一个用户每天打开 demo 看评论触发 50 条 Realtime 计算，免费额度能撑 1300 个日活用户/月。评审型 demo 远远够。

Q: 怎么删除某个 projectKey 下的所有评论？ A: Supabase SQL Editor 跑 delete from comment_pins where project_key = 'xxx';（messages 会因为 on delete cascade 自动清掉）。

不要做

• 不要让用户把 service_role key 放前端
• 不要没问清四件事（Supabase / projectKey / 接哪些页 / 页面 title 是否人话）就动手改文件
• 不要为每个 demo 都建独立 Supabase 项目（费时间且免费层够共用）
• 不要把 pin-comments.js 改得跟当前 demo 强耦合（保持通用，未来其他 demo 还要用同一份）
• 不要在不带 projectKey 配置时静默运行——脚本会 console.warn 并不上云，要主动提醒用户
• 不要给抽屉里再加更多 tooltip 和引导浮层——克制是这套 UI 的核心准则，已有 hover tooltip 足够

文件清单

给「想公开发布这套 skill」的用户

如果用户想把这套 skill 公开到 GitHub 让别人用：

1. 把整个 ~/.cursor/skills/pin-comments/ 目录复制到一个新仓库
2. 仓库根放 README.md（已有），公开仓库可命名为 pin-comments 或类似
3. 不要带任何真实 anonKey / projectUrl，全部用占位符
4. 提示用户：每个使用者需自己注册 Supabase 免费账号（按 SUPABASE_SETUP.md 走一次）