目的：把“怎么协作、怎么改站、怎么写内容、怎么发 PR”固化下来，减少沟通成本。
如果我判断某个改动不合适/风险较高/会引入长期维护负担，我会先提出具体理由与替代方案； 在你明确同意后再执行。
- 先给结论再展开：优先输出“现在能做什么 / 下一步是什么 / 风险点”。
- 默认最小侵入：优先小 PR、可回滚、避免一次性大改把问题埋深。
- 可复现：任何改动都必须能本地
npm run build通过。
- 分支命名：
feat/...功能新增/结构调整fix/...bug 修复chore/...杂项/整理/迁移
- 提交粒度：一个 PR 做一件事（例如 Now 架构改造不要夹杂首页文案）。
- 发布策略（重要）：
- Writing（长文）不走 PR：草稿阶段允许直接 commit 到
main用于预览；最终发布需主人确认。- 草稿：
npm run publish:writing:draft -- --slug <slug>（保持draft:true，不进 feed，但可通过链接访问） - 发布：主人确认后，用
npm run publish:writing:confirm -- --slug <slug>（自动draft:true -> false并发布），或主人手动改draft:false后跑publish:writing:final
- 草稿：
- Now（短更新）不需要 PR：允许直接 commit 到
main并 push（以速度优先）。
- Writing（长文）不走 PR：草稿阶段允许直接 commit 到
- 合并前自检：
npm install（或npm ci）npm run build
- 评论处理：reviewer 评论要么修复并回复，要么解释不采纳原因；能 resolved 的 thread 则标记已解决。
- 网络策略：如 GitHub SSH 22 端口不可达，统一使用 SSH over 443 推送：
ssh://git@ssh.github.com:443/JingkaiTang/JingkaiTang.github.io.git
- 目录：
src/content/writing/<slug>/index.md - URL：
/writing/<slug>/
- 目录：
src/content/now/<YYYYMMDDHHmm>/index.md（Asia/Shanghai） - URL：
/now/<id>/ - tags：必须包含
now（用于标签聚合）
/tags与/tags/<tag>：聚合writing + now
- 资源与 md 同目录存放。
- Markdown 内用相对路径引用：
。 - 构建/开发时自动：
- 同步到
public/{writing,now}/... - 通过 remark 插件把相对链接改写为站点绝对路径（不改源文件）。
- 同步到
目标：不用等 GitHub Actions / Pages 部署，快速看到页面效果。
SOP：
- 启动开发服务：
npm run dev -- --host 127.0.0.1 --port 4321 - 打开页面后先等 1~2 秒（给 JS 初始化时间）
- 滚动到页面底部（触发 lazy-load 图片加载）
- 再等 3~5 秒（确保底部图片也加载出来）
- 全页截图
- 立刻关闭服务
注意：
- 截图前必须滚到底，否则底部模块（如 Vibe Mosaic）可能因为懒加载而显示为空。
- 遇到 exec 无 TTY 场景时，避免运行会进入交互输入的命令（防止卡住后被 SIGKILL）。
-
编辑 Writing / Now：直接修改对应
index.md，然后运行编辑脚本写入updatedDate（精确到秒）：npm run edit:writing -- --slug <writing-slug>npm run edit:now -- --slug <now-slug>
-
展示规则：详情页会显示“更新于”；草稿会显示“草稿”标识并 noindex。
-
新建 Writing：
npm run new:post
-
新建 Now：
npm run new:now
-
同步资源：
npm run sync:assets
-
开发监听：
npm run dev:watch
-
构建：
npm run build（应包含 sync + pagefind 链路）
- 不做不可逆删除（尤其是内容/图片）除非你明确确认；如需删除，PR 里说明原因。
- 不在仓库中引入敏感信息（账号、token、隐私内容）；注意图片 EXIF 等隐私风险。