Songloft

简体中文

English

简体中文

English

Appearance

AI 开发与复盘流程 ​

本流程用于 Songloft 主仓库及子模块。任务交办后，AI 连续完成调查、方案、实现、验证、自审和交付；你负责产品决定及提交、推送、发布等动作的授权。阶段记录进度，不要求逐阶段确认。用户指定的停点和已有授权优先。

入口与职责 ​

入口职责
AGENTS.md仓库约束和任务文档导航
CLAUDE.md引入规范和经验文件
LESSONS.md有证据、带范围与发生日期的经验
.agents/skills/dev-flow/SKILL.md开发、Issue 排查和复盘执行入口
scripts/ai-review-context.mjs只读收集清单、Issues、提交和工作树标识

主仓库维护后端、公共宿主契约和跨仓库流程。子仓库维护业务、设备、验证矩阵和经验，中英同步。直接提交到 main，子仓库先提交，父仓库再更新指针。未提交的子模块修改只能报告为 dirty。现有规则不整体搬迁；新经验从 LESSONS 开始，成熟后纳入对应规范。

从任务到交付 ​

  1. 检查工作树，读取本地规范、适用经验和业务文档，保留用户已有修改。
  2. 按报告人的平台、部署模式和交互复现，定位根因并查同类调用点。关键缺失信息或产品决定才询问，等待期间继续独立工作。
  3. 完成范围内修改、格式化、生成物及中英文文档同步。代码是事实来源，历史记录链接到权威文档。
  4. 按风险验证、自审。Bug 新测试在隔离副本的旧实现下因目标行为失败、新实现下通过；编译失败或跳过不算反向验证。必要时做破坏检查，低风险文案按需验证。
  5. 在实际界面/平台验证；截图证明渲染，HTTP、状态、进程或设备采样证明动作。模拟数据不冒充真账号/真设备。
  6. 交付变化、验证记录、未验证项、剩余问题和提交信息。必要检查通过才进入提交；缺少必要验证时说明阻塞。
  7. 获授权推送关联 Issue 的修复后，主动准备回复草稿并展示目标 Issue；按下节完成评论确认与回读验证，随 CI 和发布结果更新内容。

调查、编辑、格式化、测试、自审和本次经验更新连续执行。提交、推送、正式发布及 Issue 评论/关闭分别需要明确授权，已有授权不重复询问。实现本流程不代表授权自动领取任意 Issue、7×24 执行或改变生产数据。

关联 Issue 回复 ​

  • 修复关联了用户交办的 Issue 或提交引用的 Issue 时，推送成功后主动准备回复草稿。包含主仓库、子仓库及跨仓库引用，使用完整 owner/repo#编号 和链接；不等用户追问「有没有回复」。准备草稿属于交付工作，无需额外授权。
  • 草稿说明实际解决的行为、已证实根因、修复提交、验证结果与未验证项、剩余问题及用户下一步。分清代码已推送、发布包已包含修复和真机已验收；CI 未完成、发布未包含或试听未运行时如实注明。后续 CI、发布结果改变这些结论时更新草稿。
  • 没有适用的评论授权时，在最终交付中展示完整回复草稿、目标 Issue 和待确认的具体动作（如「确认后将以上内容发表评论到 songloft-org/songloft#495」），等待用户确认后发表。每次确认只对应已展示的具体动作；提交/推送或发布的确认不自动授权评论或关闭 Issue。
  • 当前会话已有适用的评论授权时，直接回复，不重复询问。仅未授权的评论操作等待确认，其他已授权工作继续；评论与关闭分别授权，真实验收或剩余问题未完成时不擅自关闭。
  • 发表前复核最新评论，避免重复或过时内容；发表后回读正文，确认目标与内容正确，并在交付中提供评论链接。无关联 Issue 时不虚构回复对象。

验证记录 ​

每个仓库按以下结构记录到交付说明及适用的提交正文，长期记录链接完整日志，敏感信息先脱敏：

text
仓库 / Issue：完整 owner/repo#编号
代码：基线 SHA；最终 SHA，或未提交工作树差异标识
环境：系统、工具链、部署模式、设备/客户端和后端版本
时间 / 命令 / 结果：通过、失败及预期行为
反向验证 / 破坏检查：实际结果，或不适用及依据
实际使用：平台、交互、可观测结果、日志/截图
Not run：相关未执行检查、原因与后续要求
剩余问题 / 提交信息：

HEAD 不能单独标识未提交代码。commits 模式记录 HEAD、tracked diff、暂存区 diff、untracked 内容的 SHA-256 和状态；工作文件恢复原样也不能掩盖暂存区变更。报告存工作树外、用唯一文件名；脚本拒绝覆盖旧证据。代码、依赖、生成物或子模块变化后重跑受影响检查。失败与未执行分别记录。

推送后追踪同一 SHA 的必要 CI，取消/跳过不算通过。正式版打 tag 前确认目标代码的必要检查完成，版本更新本身也需验证。主仓库 release.yml 的 Quality 作业在构建与发布前运行 Go 格式、vet、测试和脚本测试；dev,lite 后端检查不替代完整嵌入构建、客户端/插件回归与设备验收。正式版继续遵守现有平台构建要求。

排查未解决 Issue ​

在父仓库运行（Node.js 22+、Git，网络模式需已登录的 gh；把示例文件名换成唯一标识）：

bash
node scripts/ai-review-context.mjs inventory --output /tmp/songloft-inventory-20261013-01.json
node scripts/ai-review-context.mjs issues --output /tmp/songloft-issues-20261013-01.json

从 .gitmodules 递归发现仓库，支持 GitHub HTTPS/SSH 和相对子模块 URL，按仓库去重，完整分页获取 open Issues，排除 PR、保留负责人。记录远端默认分支 SHA、本地 HEAD 和父 gitlink，不更新 checkout/指针。

未初始化模块仍查询 Issues，无法读取嵌套清单时报告缺口。非 GitHub 地址、认证/网络失败、Issues 功能关闭与成功但零 Issue 分别记录。complete=false / 退出码 1 表示覆盖不完整，JSON 仍写出；不能以失败或分页截断得出零待办。需要初始化时按授权保留工作树后操作。

收集是待分析清单，不是修复判定。逐项读正文、全部评论、关联提交、复发证据并核对远端最新代码，必要时读相关 closed Issues。独立子仓库 checkout 从父仓库清单补齐范围。报告含完整 owner/repo#编号、路径、链接、判定（未修复/部分修复/已修复但未关闭/等待信息/未验证）、代码 SHA 与验证证据、下一步和未检查项。子仓库修复、父指针同步、发布和实际设备安装分别判断。

open 不等于未修复，closed 不证明没有回归。排查默认产出报告，修复、评论、指派和关闭按授权执行。

复盘与经验升级 ​

任务结束记录有证据的新经验；一天/一段时间的复盘由用户调用：

bash
node scripts/ai-review-context.mjs commits --since 2026-10-12T00:00:00+08:00 --until 2026-10-13T00:00:00+08:00 --output /tmp/songloft-review-20261013-01.json

省略窗口时收集最近 24 小时。包含各子模块的本地历史，固定窗口和 checkout SHA，不证明远端同步；最新远端历史需另行只读核对、标明来源，缺失历史留在报告中。命令只收集证据，不运行 AI 或安装定时任务；本版通过任务结束复盘或用户发起的时间窗口复盘运转。

复盘提示：

text
复盘指定时间窗口内 Songloft 主仓库和所有子模块的提交。
先运行 ai-review-context.mjs commits，报告覆盖、SHA 与缺口。
结合相关 Issue 正文/全部评论、CI 和验证记录，只分析：
1. 修复后返工；2. 不应合入的改动；3. 验证遗漏或证据不足。
提交标题/后续改动只是线索，核对失败、根因与修复证据。
把经验写到所属仓库 LESSONS.md 及英文版，记录正确例子。
同一事件重复复盘不增加 Seen；三个不同日期的独立事件提出规范升级。
已有规范链接权威位置，升级后标记目标并按需加测试/CI 闸门。
无证据推断列为待核实，不虚构次数，不自动提交、推送或操作 Issue。

每条经验含规则、范围、失败事件与后果、修复提交、正确例子和 Seen N× (日期)。三个不同日期的独立事件后提出转入代码/平台规范，标记目标位置避免重复规则漂移。已有铁律立即执行，严重缺陷可立即形成约束。经验不授予新权限、不推翻已决定的产品行为。

日常入口 ​

  • “按 dev-flow 修复这个 Issue”：连续实现、验证、自审并交付。
  • “排查未解决的 Issue”：主仓库与所有子模块一起排查，报告缺口。
  • “复盘昨天的提交”：核对时间窗口证据，更新各仓库经验。