git-summary

把一段提交区间里的 commit message 加工成功能清单，而不是逐条罗列提交。区间只有两个锚点：分支创建点 → 该分支最近一次并入 main 的 merge（未并准则取分支 tip）；默认目标分支为当前分支。

定位：只读汇总类任务。 正文即功能清单，不输出 common-rules 规范一的四件套尾注，只压成一行起止时间（详见第四节）。全程只读，禁止任何改动仓库状态的操作。

零、参数处理

如果用户传入 -h 或 --help，不执行任何操作，直接把下面的帮助信息原样输出在本次回复正文里后结束（斜杠命令把 SKILL.md 注入我的上下文不等于已展示给用户，正文里只回一句"已输出"就是没输出）。-h 与其它参数或说明文字同时出现时，一律只出帮助、忽略其余参数：本轮不猜附加要求，需要同时执行就把 -h 去掉分两次调用：

用法: /git-summary [选项]

选项
  --branch=NAME       目标分支（可选，默认当前分支 = git branch --show-current；
                      支持本地名、origin/xxx，也支持位置参数：/git-summary feat-1.4.7.5）
  --limit=N           只取区间内最近 N 条提交参与加工（可选，正整数；默认不限）
  --raw               输出原始逐条提交列表与统计，不做归并加工
  --domain-map=PATH   自定义功能域词典文件（每行一个域名，覆盖内置词典）
  --with-merges       加工时包含 merge 提交（默认排除，merge 提交不携带功能信息）
  -h, --help          显示本帮助（出现即忽略其它参数，只出帮助）

区间 = 两个锚点之间，只有这一个口径，没有第三个参数：
  起点锚  分支创建时的提交，优先读本机 reflog 的 "branch: Created from"；取不到再退回
          并入 merge 的第一父 / 与主干的 merge-base（并校验其不等于终点，否则视为取不到）
  终点锚  最近一次并入主干的 merge 提交；没有 merge 提交（fast-forward 合并）或尚未并入就取分支 tip
  表头会标明终点属于哪一种：并入 main 的 merge / 已并入 main（fast-forward）/ 分支 tip（仍有提交未并入）
无独有提交或加工后无功能点时输出「区间性质判定」，不渲染空清单；任何情况下都不展开整条历史。

输出形状：表头 → 新增/修复/口径与约定变更三段 →（可选）内部改造 → 未列入 → 要点式总结（修复与产品功能要点 + 计数）→ 起止时间。

示例
  /git-summary                                  # 当前分支：创建点 → 并入主干（或 tip）
  /git-summary feat-1.4.7.5                     # 指定分支，同上（位置参数）
  /git-summary --branch=origin/feat-1.4.8       # 远端分支
  /git-summary --limit=30                       # 只用最近 30 条提交加工

一、参数解析

• 分支名支持位置参数：/git-summary feat-1.3.6 等价 --branch=feat-1.3.6。
• 时间一律东八区：取时命令前置 TZ=Asia/Shanghai；日期口径统一 author date（%ad），不与 committer date 混用。
• 分支 ref 解析：原样 git rev-parse --verify --quiet "<name>^{commit}"，失败再试 refs/heads/<name>、refs/remotes/origin/<name>；仍解析不到 → 报错并 git branch -a --format='%(refname:short)' | head -15 列出候选，不猜测。

二、区间解析（两个锚点，唯一口径）

先定默认主干 BASE：origin/HEAD → 本地/远端 main → master（取第一个存在者）；目标分支 BRANCH （默认当前分支）的最新提交记为 TIP。提交集合恒为 START..TIP，START（起点锚）与终点锚按下面两步确定， 没有第三个参数。

1. 终点锚与它的性质（三种，必须区分）

   git merge-base --is-ancestor "$TIP" "$BASE" && echo 已并入 || echo 未并入
   LAND_MERGE=$(git log --first-parent --merges --reverse --format='%H' "$BASE" \
     | while read -r h; do git merge-base --is-ancestor "$TIP" "$h" && { echo "$h"; break; }; done || true)

   命令末尾的 || true 不能省：没扫到命中时 while 循环的退出码是 1，整条赋值即失败，串在 && 里会中断 后面的锚点解析。

   判定	终点锚	表头「终点」取值
   扫到 LAND_MERGE	$LAND_MERGE	并入 main 的 merge
   TIP ⊆ BASE 但扫不到 merge	$TIP	已并入 main（fast-forward / 无 merge 提交）
   TIP ⊄ BASE	$TIP	分支 tip（仍有提交未并入）

   • 扫 merge 的方向必须是 TIP ⊆ merge；反过来（merge 的第二父落在分支历史里）会把"本分支创建之前刚并入的 别的分支"认成本分支的并入点。分批并入过多次的，命中的正是最后一次带进新提交的那次。
   • 第二行不是兜底摆设：全用 fast-forward 合并的仓库主干上根本没有 merge 提交，必然落到这一行；此时把 性质写成"未并入"就是错标（实测：主干与分支 tip 同为一个 commit、且主干 reflog 全是 merge <分支>: Fast-forward 的仓库必然如此）。
   • 分支并入主干后又继续开发的（TIP ⊄ BASE）走第三行，区间仍是"创建锚 → tip"，含已并入的那部分。

2. 起点锚 START：按优先级取第一个可用者

   a. 本机建分支记录（最可靠，优先用）：git reflog 里 branch: Created from … 那条的值，就是建分支 那一刻分支指向的提交，不受之后是否并入主干影响：

   CREATED=$(git reflog show --format='%H %gs' "$BRANCH" \
     | awk '/branch: Created from/{h=$1} END{print h}')

   reflog 输出新→旧，awk … END{print h} 取到的最后一条命中即建分支动作本身；取到即 START=$CREATED。 局限：reflog 只存在于创建过这条分支的那台机器，换机器 / 重新 clone / 被 gc 掉就取不到，转 b。 b. 并入 merge 的第一父：有 LAND_MERGE 时 START=$(git merge-base "$LAND_MERGE^1" "$TIP")——用第一父 量分叉点，避免并入动作把分叉点推成 TIP。 c. 与主干的分叉点：START=$(git merge-base "$BASE" "$TIP")，且必须校验 START != 终点锚。

3. 起点锚取不到时（a 无记录、b 无 merge、c 与终点锚重合）：走第四节「区间性质判定出口」，定性写 创建锚取不到（分支已整体并入主干，且本机无建分支 reflog 记录），并列出实测核对信息。禁止输出 9b1baec → 9b1baec，0 条 这种两端重合的区间蒙混过去——那说明锚点算错了，不是分支没干活。
4. 时间展示：起始时间取区间内最早一条提交的 author date（%ad）；终点时间取终点锚（merge 取 %cd， TIP 取 %ad）。START 自身的时间只当"创建时刻"参考，不参与区间统计口径。
5. 起点锚有效但区间确为 0 条（建分支后没有独有提交）：也走区间性质判定出口，定性写 分支自创建锚点以来无提交。

禁止改动口径：不沿版本族上探 / 下探（feat-1.4.7.5 → .4 → .3 这类），不自动改用别的分支或 tag 当锚点， 不因"区间只有几条提交"就换起点——区间窄就照实输出几条，取舍交给读者；更不为"总得输出点东西"展开整条仓库 历史（300+ 条的大而全输出没有使用价值）。

取数命令（RANGE="$START..$TIP"，加工输入与 --raw 用同一份数据）：

git log $MERGE_FLAG --reverse --date=format-local:'%Y-%m-%d' --pretty=format:'%h|%ad|%s' $RANGE

• --limit=N 时先去噪（3.2）再截断：从过滤后剩余的提交里按时间取最近 N 条，再正序加工（命令上是 git log $MERGE_FLAG --reverse 取全量后截断，不是 git log -N 先截断，否则小 N 容易被台账类提交占满、清单落空）。
• 取到列表后同时记录：起点锚与终点锚短 hash 及时间、区间提交数、时间跨度（首末条日期）、终点锚性质（见第四节表头取值），供表头与起止行使用。
• 空首行提交（no message）保留在计数里，加工时按 3.2 归入"未列入"。
• 正文按需读取（只对首行判不出对象、或需要核对具体结论的提交执行，属 commit message 范围，不算读 diff）：

git log -1 --date=format-local:'%Y-%m-%d' --format='%h %ad%n%B' <hash>

实测过本仓库存在大量"首行裸词、结论全在正文"的提交（如 48 条台账类里 19 条正文超 200 字符，写着闸门数量、唯一索引名、被跳过行回传旧票号这类实质结论），只读首行会把它们全部屏蔽，判读时按 3.1 的正文参与范围处理。

三、加工算法（五步，全部在本 skill 内由模型执行，不依赖脚本）

拆 → 去噪 → 归并 → 定性 → 溯源

3.1 拆：提交信息切子句

• 分隔符只认：，、；、。、+、①②③④⑤⑥⑦⑧⑨、换行。顿号 、 与斜杠 / 不切——前者是并列名词、后者常在同一个名词里（如 订房/订餐双信封），切开会把一件事拆坏。
• 一个子句 = 一个候选功能点；切出的子句不足 6 个字符或无名词主语的，并回前一句，不单独成项。
• 括号里的 scope（如 feat(chat-style):）只用于判断归属模块，不作为功能名。
• 默认按首行拆句；首行是裸 update、台账留痕、或判不出对象时，必须先读该提交正文再判定（读命令见第二节），正文给出具体对象与结论的按正文入选，不得因首行信息不足直接丢进「未列入」。
• 正文参与范围只有三条：① 救回首行无对象的提交；② 为已入选的功能项补原词（表名、索引名、闸门、错误码、票号等，仍受第五节约束 2 的"原样保留"）；③ 除此之外不得从正文派生出首行完全未涉及的新条目。经正文救回的条数在"未列入"一行注明"其中 x 条经正文补全入选"。

3.2 去噪：不入清单但计数

命中任一条即丢弃，并在末尾"未列入"一行按类别计数：

3.2 与 3.4 同时命中时，以 3.2 为准（提交级前缀封顶）：一条提交首行的类型前缀决定它能进入哪一段， 子句内容不得反过来救回整条提交。

• test: / docs: / chore: 前缀的提交，其任何子句一律不入「新增」与「口径与约定变更」段—— "改判三处判据""补负例断言"这类描述是测试侧判据，不是产品口径，把它抬成口径项就是把测试改动冒充成功能。
• 「口径与约定变更」只由 feat: / fix: 前缀、或无前缀但明确写出外部行为变化（表结构、接口、页面、 计算口径、配置生效范围）的提交支撑。
• 确实只在 test: / docs: 提交里出现、看起来像产品口径的内容：计入对应「未列入」类别、不猜、不抬， 由用户换 --branch 或人工指认提交后再纳入。
• 一条提交含多个子句时逐句判定，但封顶按整条提交的前缀生效（前缀是 test: 就整条不进两段）。

3.3 归并：按功能域聚类

• 归并键 = 子句里的名词主语（表名 / 模块 / 接口路径 / 页面 / 功能名）。同一功能域内"做了同一件事"的子句合成一行。
• 一条提交命中多个功能域时，分别落到各自功能项下（这是多数长提交的正常形态，不要为省事压成一项）。
• 内置功能域词典（--domain-map=<文件> 可整体覆盖，文件每行一个域名）：

库存与签收
申购与采购
退款与余额
核销与履约
订单与支付
会员与登录鉴权
四诊与报告
AI 问诊
商城与商品
门店端与BOSS
数据库与迁移
部署与配置
安全与合规
小程序与移动端

• 落不进任何域的子句归 其它，不得强行塞进现有域。

3.4 定性：每个功能项打一个标签

只有三段——新增 / 修复 / 口径与约定变更（含判定标准、计算口径、字段语义的调整）。refactor 类只在改变外部行为时入清单，且按实际影响归入上述三段之一。先过 3.2 的「提交级前缀封顶」再定性：前缀不允许的提交，子句再像口径变更也不入段。

3.5 溯源：每个功能项必须挂 hash

• 每个功能项末尾挂 ≥1 个 commit 短 hash，形如 （046484a, 513297a）。
• 挂不上 hash 的项不允许存在；一个 hash 可支撑多项，一项也可由多个 hash 共同支撑。

四、输出契约

正文只有清单，不加寒暄、不加建议、不解释过程：

## 功能清单：<BRANCH>（<起点锚短hash> → <终点锚短hash>，终点：<并入 main 的 merge | 分支 tip（未并入）>，N 条提交 → M 个功能点）

### 新增
- **<功能名>**：<做了什么，一到两个分句，保留原文里的数字/错误码/接口路径>（<hash, hash>）

### 修复
- **<问题点>**：<修成什么样>（<hash>）

### 口径与约定变更
- <变更内容>（<hash>）

### 内部改造
<一句话，仅在存在时输出>（<hash>）

> 未列入：a 条台账/留痕、b 条裸 update/空 message、c 条纯取证提交。

总结：<要点 1；要点 2；要点 3>（<N> 条提交 → <M> 个功能点，新增 x / 修复 y / 口径变更 z）

起止：<开始时间> ~ <结束时间>（东八区）

• 「总结」是固定槽位，位于「未列入」之后、起止行之前，格式固定为： 总结：<要点 1；要点 2；要点 3>（N 条提交 → M 个功能点，新增 x / 修复 y / 口径变更 z）
  • 主体是要点，不是计数：从上方清单已渲染的功能项里挑最多 3 条按重要度排序的要点， 优先挑修复类（bug 修复）与影响资金/履约/权限的产品功能，写成名词短语，保留清单里的原词 （表名、错误码、接口路径不泛化成"某接口""某问题"）。例： 总结：修好退款金额重复计算与签到漏记；订房/订餐双信封按 orderType 分列（34 条提交 → 11 个功能点，新增 3 / 修复 7 / 口径变更 1）
  • 只能挑、不能新造：要点必须与清单某一项对应（可缩短措辞，不得引入清单里没有的功能名， 也不得把两项合成一件没做过的事）；顺序与清单排序一致。
  • 括号内计数：N 条提交 → M 个功能点 与表头完全一致，新增 x / 修复 y / 口径变更 z 是清单实际渲染的 功能项数，不是 commit 前缀计数（多数提交没有 type 前缀，按前缀算必然错）。
  • 长度：一行优先，超过 60 字可换到第二行，总计不超过 2 行 / 120 字；不评价质量、不提建议或下一步。
  • M = 0 时不输出该段（走区间性质判定出口，其定性行已承担总结职责，不重复）；--raw 模式不输出该段。
• 「终点」是表头固定槽位，取值只有第二节表格里那三种：并入 main 的 merge / 已并入 main（fast-forward / 无 merge 提交） / 分支 tip（仍有提交未并入）。该字段写在括号内，禁止在括号外另挂一句解释（"不解释过程、形状必须一致"含此意）；区间口径本身不可配置，不要臆造第四种取值。
• 三段（新增 / 修复 / 口径与约定变更）固定渲染，某段无内容时该段写一行 （无）；### 内部改造 与 > 未列入： 两段仅在确有内容时输出。同一区间多次运行，输出形状必须一致。
• 功能项按重要度排序（影响资金/履约/权限的先列），不按 commit 顺序。
• 功能项超过 60 条时截断到 60 条并提示：另有 x 个功能项未渲染，可用 --limit=N 收窄提交范围。
• 最后一行起止时间即本 skill 对 common-rules 规范一的替代尾注：只读汇总任务，不输出影响范围/人工待办/飞书通知段。
• --raw 模式改为输出原始列表与统计：表头（分支、起点锚、终点锚及其性质、区间起始时间、提交数、时间跨度、作者数、类型分布）+ 逐条 短 hash 日期 首行（首行超 72 字符截为 71 + …）。用途是核对底稿——怀疑归并漏项、合并错功能域、或只想要逐条台账时用；它不去噪、不归并、不定性；提交数与功能点数没有固定大小关系（一条提交可拆出多项，一项也可由多条提交支撑），不要拿两者互相校验。区间 0 条时同样走区间性质判定出口，不展开整条历史。

区间性质判定出口（空增量专用，替代三段模板）

命中任一条即输出下面这个形状，不打三段清单、不打两个 （无）——空表会被读成"清单坏了"，而事实往往是"这批提交本来就是台账 + 取证"：

• 区间为 0 条（起点锚有效，但分支自创建锚点以来没有独有提交，或分支即主干本身）；或
• 起点锚取不到（第二节第 3 步：无建分支 reflog、无并入 merge、且 merge-base 结果与终点锚重合）——此时定性必须写 创建锚取不到（分支已整体并入主干，且本机无建分支 reflog 记录），禁止输出两端是同一个 hash 的区间；或
• 入选项功能点 M = 0；或
• 区间内没有任何 feat: / fix: 前缀、也没有写出外部行为变化的提交（全是 test: / docs: / 台账类，按 3.2 封顶后必然为 0）。

## 区间性质：<BRANCH>（<起点锚短hash> → <终点锚短hash>，终点：<并入 main 的 merge | 分支 tip（未并入）>，N 条提交 → 0 个功能点）

本区间为 <一句话定性：分支无独有提交 / 迭代收尾台账 / 纯测试取证>，无产品功能增量。
提交构成：feat a 条 / fix b 条 / test c 条 / docs d 条 / 其它 e 条

如需核对：<该分支上最近一条独有提交的短 hash 与时间> / 相邻分支 <X（实测 n 条）>
本 skill 不接受手工指定区间，需要换分支就直接 /git-summary <分支名>

• 「核对」两行的分支名、短 hash 与条数必须来自本次实测（git branch --format + git rev-list --count + git log -1），只作参考、不自动改跑；没有可给的就写 核对：无相邻分支可参考，禁止编造分支名或条数。
• 该出口只说明"这个分支相对两个锚点没有功能增量、想看别的分支就直接换 --branch"，不展开整条历史、 不另铺别的区间清单。

五、硬约束（防止编造）

1. 信息源只有 commit message（区间内取到的那批，含首行与按 3.1 正文参与范围读取的正文）。禁止读 diff、代码、文档去"补全"功能；禁止用外部知识命名一个提交里没有出现过的功能。
2. 功能项措辞只允许使用提交原文出现过的名词与结论；原文里的数字、错误码、接口路径、表名（如"未知分类判 400"、chat_style_tag_bindings）必须原样保留，不得泛化、不得四舍五入、不得改成"某接口""某表"。
3. 不得跨类型、跨渠道合并表述：原文按 orderType / 渠道 / 端 分句描述不同结论时，归并后必须各留各的，压成一句即判错。
4. 判定不了对象的一律进「未列入」，禁止猜一个功能名凑数；禁止为了三段齐全而把"内部改造"抬成"新增"，同样禁止把 test: / docs: 提交里的测试侧判据抬成"口径与约定变更"（见 3.2 封顶规则）。
5. 输出功能项数不得超过拆出的子句总数；每条必须可 hash 溯源；无增量时走第四节「区间性质判定出口」输出定性 + 实测核对信息（只作参考，不自动改跑别的分支），不铺整条历史。
6. 统计数字（提交数、未列入计数、起止时间）必须来自本次实测命令输出，禁止估算或复用上一轮结果。

六、只读边界与回退

• 允许命令：git rev-parse / rev-list / log / show / merge-base / describe / branch / shortlog / symbolic-ref / reflog show（只读，用于取建分支锚点）。禁止 checkout、switch、fetch、pull、merge、rebase、reset、gc 等任何改状态操作；需要补历史（浅克隆 git rev-parse --is-shallow-repository 为 true）时先征得用户同意。
• 不写文件，结果只输出到对话；用户显式要求导出时才写 <分支名>-features.md 到当前目录并告知路径。
• detached HEAD 且未指定 --branch → 用 HEAD，表头标注"游离 HEAD（非分支）"。
• 分支基于其它特性分支创建（父分支也还没并入主干）→ 区间会含父分支那部分工作，末尾一行注明"起点锚 <短hash> 之前还有未并入的父分支提交"，可用 --raw 核对归属。
• 起点锚来自 reflog 的建分支记录，换机器 / 重新 clone / reflog 被 gc 掉就取不到；同一分支在不同机器上可能给出不同区间，此时按第二节 b/c 回退并在表头如实标注终点性质，不要拿相邻分支去凑。
• 浅克隆算不出分叉点 → 提示结果可能不完整，退化到 git log $BRANCH --not $BASE 并在表头注明"未找到共同祖先"。
• 本 skill 只做"读提交信息、归并成清单"，不判定代码质量、不做发布风险评估、不代替用户决定是否合并。