f2s-git-commit - SKILL.md Agent Skill

name: f2s-git-commit description: 代码写完后提交 Git：默认检查变更与知识库覆盖；用户明确要求“快捷提交”时跳过知识库覆盖检查；生成带 emoji 首行的提交说明后可直接 commit（须在当条回复展示首行，不要求用户单独确认 commit）；git pull 类拉取须用户先确认。触发：f2s-git-commit、提交代码、快捷提交、git commit、帮我提交

执行口径：本技能代用户执行 git 操作；不使用 git add -A / git add .，不跳过 hooks（--no-verify），不自动 push。git pull / git fetch 合并入本地前必须取得用户对「拉取」的明确确认；git commit 不要求单独一轮「确认」交互（见步骤 3–4）。用户明确要求“快捷提交”时，仅跳过步骤 2 知识库覆盖检查，其余安全步骤照常执行。

编排（主 / 子 agent）

subAgent / switchAgentVerification 语义以统一入口为唯一事实源：Cursor/Claude 读配置根 rules/f2s-flow2spec-unified-entry.*；Codex 读 .codex/topics/f2s-flow2spec-unified-entry.md。
本技能全程在主 agent 完成（pull 的确认不可下放子 agent；git commit 不要求单独一轮用户确认，见步骤 3–4）。

f2s-git-commit（提交代码）

强制流程

快捷提交模式

当用户本轮明确说出 “快捷提交”、“快速提交” 或 “quick commit” 时，进入快捷提交模式：

跳过 步骤 2：知识库覆盖检查，不读取 .Knowledge/topics/ / .Knowledge/stock-docs/ 做覆盖判断。
不提示用户先运行 f2s-kb-sync / f2s-kb-feat。
不跳过步骤 1 的变更读取与冲突标记检查。
不跳过步骤 3 的提交信息生成与展示。
不跳过步骤 4 的精确 git add <文件列表>、正常 git commit 与 git hooks。
不得因快捷提交使用 git add -A / git add . / --no-verify / 自动 push。

步骤 1：读取变更（只读）

git status --short
git diff HEAD

从 git status --short 区分三类文件：
- Staged：已 git add，前缀为 M 、A 、D （首列非空）
- Unstaged：已追踪但未 add，前缀为 M、 D（次列非空）
- Untracked：?? 前缀，新文件尚未追踪
若三类均为空（nothing to commit），直接告知用户并结束。

冲突检查（必须，先于一切）：

扫描所有变更文件内容，若任意文件包含 <<<<<<<、=======、>>>>>>> 冲突标记，立即终止并提示：

❌ 检测到未解决的 merge conflict：
  - <文件路径>

请先解决冲突后再提交。

步骤 2：知识库覆盖检查（默认必须；快捷提交跳过）

若处于快捷提交模式，本步骤直接跳过，并在步骤 5 收尾提示中说明“已按快捷提交跳过知识库覆盖检查”。

先判断 .Knowledge/ 是否存在：

若 .Knowledge/manifest-routing.json 不存在：跳过本步骤，在步骤 5 收尾提示「项目尚未初始化 Flow2Spec 知识库，建议运行 flow2spec init」，继续步骤 3。

存在时执行覆盖检查：

从 git diff HEAD 及 untracked 文件路径推断本次变更涉及的功能模块（以仓库内目录/包名为准，勿臆测未出现的业务名）。
读取 .Knowledge/topics/ 目录列表与 .Knowledge/stock-docs/ 目录列表。
对比步骤 1 推断出的功能模块，判断对应文档是否已在知识库中登记。
得出结论：已覆盖 / 部分覆盖 / 未覆盖。

判断粗粒度即可：有对应 topic 或 stock-docs 文档即视为已覆盖；若知识库为空或找不到相关文档则视为未覆盖。

未覆盖或部分覆盖时（必须提示）：

⚠️  本次变更涉及以下能力尚未入知识库：
  - <能力描述>

建议在提交前同步知识库，可选：
  A) 现在运行 f2s-kb-sync 补录，完成后自动继续提交流程
  B) 先提交，稍后手动补录（输入 B 确认）
  C) 取消本次提交（输入 C）

选 A：提示用户运行 f2s-kb-sync 或 f2s-kb-feat 补录；用户补录完成后在同一会话声明已补录或再次触发本技能时，从步骤 1 或步骤 3 继续（不要求为「继续 commit」单独打字确认，与步骤 3–4 一致）。
选 B：记录未覆盖能力描述，在步骤 5 收尾提示中输出。
选 C：终止本技能。

步骤 3：生成提交信息草稿（必须）

读取 git diff HEAD（内容过长时取前 300 行），基于实际变更内容生成提交信息。

首行格式（必须）：类型图标 + Conventional Commits

首行须同时满足：

以一个 emoji 开头（与下表 type 对应，禁止用多个装饰 emoji 堆叠）。
紧跟 一个 ASCII 空格，再写 小写 type、英文冒号 :、一个空格、中文或英文简述。
可选 scope：使用 Conventional 的 type(scope):，紧跟在 type 之后、冒号之前，例如 🐛 fix(auth): 修复登录态丢失。
首行总长度建议 ≤ 72 个字符（含 emoji；过宽时优先缩短描述）。

推荐模板（单行）：

<emoji> <type>[(scope)]: <简述>

无 scope 时省略括号段，例如：🚀 feat: 简述。

type → 首字符 emoji（固定选用下表，便于检索与发布说明）：

`type`	emoji	典型场景
`feat`	🚀	新功能、对用户可见的能力增量
`fix`	🐛	缺陷修复、线上/测试问题
`docs`	📚	仅文档、注释、README、知识库正文类
`style`	💄	纯格式、缩进、分号等不改变行为的排版
`refactor`	♻️	重构、改名、无行为变化的结构调整
`perf`	⚡	性能优化
`test`	🧪	测试用例、测试桩、快照
`build`	🏗️	打包、依赖、编译脚本、artifact
`ci`	👷	CI 配置、流水线、自动化脚本
`chore`	🔧	杂项、工具脚本、非 build/ci 的维护性改动
`revert`	↩️	回滚某次提交

示例：

🚀 feat: 支持xxx活动缓存预热
🐛 fix(coupon): 领券窗口边界条件错误
📚 docs: 补充公共模块 QConfig 说明
♻️ refactor: 提取拼团校验为独立函数
🔧 chore: 升级 ESLint 配置

正文（可选）：第二行起可为列表或段落，不要求每行再加 emoji；若需条目，用 - 即可。

用户已给出首行时：若已含上表之一且 emoji 与 type 一致，尊重用户文案；若仅有 type: 无 emoji，须补全 emoji 再进入步骤 4。

与 git commit 的确认策略（必须）：

在同一条 assistant 回复中：先展示拟提交说明的首行（及可选正文），随后立即执行步骤 4（git add 逐项 + git commit）。不要求用户再回复「确认」才允许 commit。
若用户在该轮对话中已先写明提交说明且合规，可直接使用并进入步骤 4，仍须在执行前复述首行再 commit。
用户若明确表示「改提交说明 / 换一个 type」：改稿后仍在本策略下展示即提交，不增加「请回复确认」门槛。

步骤 4：执行提交（展示说明后立即执行）

根据步骤 1 的三类文件分别处理：

# 1. Unstaged 文件：需先 add
git add <unstaged 文件列表>

# 2. Untracked 文件：需先 add
git add <untracked 文件列表>

# 3. Staged 文件：已 add，无需重复操作

# 执行提交
git commit -m "<步骤 3 定稿的完整提交信息>"

禁止使用 git add -A / git add .，仅 add 步骤 1 中明确列出的文件。
若 pre-commit hook 失败：输出完整错误信息，提示用户修复后重新触发本技能，不使用 --no-verify 绕过。
若 commit 成功：读取 commit hash（git rev-parse --short HEAD）并进入步骤 5。

步骤 5：收尾提示

✅ commit <hash> 完成
   <提交信息首行>

[若步骤 2 选了 B]
📌 提醒：以下能力仍未入知识库，建议在合并前补录：
  - <能力描述>
  可运行：f2s-kb-sync 或 f2s-kb-feat

[若跳过了步骤 2（.Knowledge 不存在）]
💡 项目尚未初始化 Flow2Spec 知识库，如需接入可运行：flow2spec init

[若快捷提交跳过了步骤 2]
⚡ 已按快捷提交跳过知识库覆盖检查。

约束

禁止使用 git add -A / git add .，只 add 已确认的变更文件。
禁止 --no-verify，hook 失败须修复后重试。
禁止 --amend 已推送的 commit，除非用户明确要求。
禁止自动 push，commit 完成后停止。
默认模式下知识库未覆盖时必须提示，但最终是否补录由用户决定（选 B 不阻塞）；快捷提交模式下跳过知识库覆盖检查，不提示补录选项。
git pull / git pull --rebase / 会改写当前分支工作区内容的 git fetch 后续合并操作：必须先向用户说明目的与风险，取得用户对「拉取」的明确确认（如用户回复「确认 pull」）后再执行；禁止为 commit 而顺带静默 pull。
git commit：不要求用户单独回复「确认」；但禁止完全不展示拟提交首行就执行 commit（须在当条回复中可见首行后再执行）。
提交信息首行须符合步骤 3 的 emoji + type 格式（用户已合规给出时可保留）。
存在 merge conflict 标记时必须终止，不得继续。

完成后自检

步骤 1 是否检查了 merge conflict（必须为是）。
是否区分了 staged / unstaged / untracked 三类文件（必须为是）。
是否用了 git add -A / git add .（必须为否）。
知识库检查是否执行或有明确跳过理由（快捷提交 / .Knowledge 不存在）（必须为是）。
步骤 3 是否基于 git diff 实际内容生成提交信息（必须为是，而非仅 --stat）。
执行 commit 前是否在当条回复中展示了拟提交首行（必须为是）；不得要求用户单独「确认 commit」才执行（与策略一致）。
提交信息首行是否为 <emoji> <type>[(scope)]: <简述> 且 emoji 与 type 与上表一致（合并 revert 等例外须在展示中说明）。
若 pre-commit 失败，是否跳过了 hook（必须为否）。
若步骤 2 选 B，收尾提示是否包含未补录提醒。
若步骤 2 选 A，是否在用户补录或再次触发后继续流程（不要求为继续 commit 单独要确认）。
若本流程中曾需要 git pull：是否在执行前取得用户对 pull 的明确确认（必须为是）；未涉及 pull 则标 N/A。