wx/hl-api-changelog
1
0
派生 0
代码 工单 合并请求 工作流 软件包 项目 发布 百科 活动
2,975 提交 29 分支 0 Git 标签
78ca3f1ee3a0cf7abb16f01e70508545291d58c0
提交图
10 次代码提交
作者 SHA1 备注 提交日期
API Changelog Bot和Claude Opus 5 78ca3f1ee3 feat(guard): E_WAIT_LANGUAGE 补第四类——把「什么时候上线」写成派给前端的动作项
changelog-filename-gate / validate (push) Failing after 1s
详情 
今天上午装这条守卫时只想到「等/待/另发」这一种形态，当天下午就被另一种形态绕过去了：
20_7443 正文写着「上生产前请与后端确认这个开关的状态」与「生产环境未开」，
mmg 据此来问上线时间、并要求「后端把生产开关打开」——而守卫全绿，因为这两句
一个词表词都没用上。它们把不确定性包装成了「请你去确认」，语法换了，作用一样：
读者只能停在那里等一个他查不到的状态。

判据仍是那一句：这条影响他「怎么写代码」，还是只影响他「什么时候开始写」。
上线时点属后者。前端需不需要同步上线，由 frontend_action_required 与模板里
「前端是否必须同步上线」那个结构化字段承载，正文自由文本里不该再出现。

词表先对全仓 1068 份 changelog 实跑，只留零命中且零正当用法的 12 个词。剔除两个：
  「何时开」  —— 误伤「保护何时开始生效」「窗口何时开过」
  「生产上线」—— 误伤 07_5640「生产上线需配 annual-direct-plan-id」，那是真契约边界

部署时间戳没做成规则：该形态全仓 0 命中，分辨力无从验证，而必须放行的
「带时刻实测取证句」有 690 处——判据的误伤面远大于收益时，门禁只会教人绕开它。
这一类只能靠 §2.1 的条文和复盘接住，机器接不住，如实记在注释里。

测试：新增 2 条阳性 + 1 条阴性对照，阴性那条与阳性只差一个「上生产前」，
用来钉住分界线（「收到 809009 找后端确认该环境的开关」是运维处置，必须放行）。
npm test 59 项 58 绿；唯一的红是存量的 E_ALIAS_STATE（11_7510，与本次无关）。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-09-21 16:23:33 +08:00
API Changelog Bot和Claude Opus 5 455d9da1af fix(gate): E_WAIT_LANGUAGE 撤掉「暂不可用」族——实测几乎全是错误码表文案
changelog-filename-gate / validate (push) Failing after 2s
详情 
对全仓 1968 份 changelog 跑新规则做存量抽样,命中里「暂时不可用 / 暂不可用」这一族
几乎全部落在错误码表与响应示例的**文案**上,例如:

  | `584105` | 结算字典暂时不可用，请稍后重试 | 字典服务失败、空响应或无启用项 |
  | `584100` | 车辆费用暂时不可用 | 车辆费用来源调用失败…… |

这正是本规则必须放行的契约内容——它影响前端「怎么写代码」(要认这个错误码),
不影响他「什么时候开始写」。判据没有分辨力时,门禁只会教人绕开它,或者逼作者
为了过门禁把该写的错误码说明一起删掉。已在代码里写明不要加回来及其依据。

撤掉后存量命中从 54 份(2.7%)降到 29 份(1.5%),剩下的按措辞分布:
未部署 20、等待…后端 7、待部署 5、另行通知 3、后续订正 3、等待…上线 2、
后端部署后 1、等待…部署 1、以后续 1、暂不要对接 1 —— 都是真的在让前端等。
存量不回填(门禁只跑 push diff),谁编辑旧文件谁负责当场改掉。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-09-21 15:29:27 +08:00
API Changelog Bot和Claude Opus 5 047a4be4fd feat(gate): 新增 E_WAIT_LANGUAGE——交接件正文禁「让前端等我们」的措辞
changelog-filename-gate / validate (push) Failing after 2s
详情 
2026-09-21 wx 第二次点名：「不要在changelog里写让前端等待部署 这不是你第一回犯错了
工作流是你部署完测试环境推送changelog」。

§2.1 的 backend_status 门禁挡得住预告式推送，挡不住这一类：20_7443 的 frontmatter
已经是 deployed、CI 全绿，但正文 status_note 结尾写着「该缺陷已在修……修好后另发
交接件」。mmg 因此一直没动工，隔天才来问「这个是有啥问题吗 还是没做到呢」——门禁
只看 frontmatter，看不见自由文本里的这句话，所以「deployed + 校验绿」并不代表这份
交接件可执行。消费方也没有能力消解这种不确定性：他查不了我们的部署状态、看不到
dev-v3、不知道「另发」是哪天，读到「等」就只能等，而且是静默地等。

- scripts/validate-changelog-frontmatter.mjs：新增 validateNoWaitLanguage，对所有
  v2 文档逐行扫描（与 change_type 无关，前端条目同样适用）。三类措辞：部署状态对冲、
  未来交付承诺、直接叫停对接；「等待」做共现判定而非裸词匹配，避免把「前端需轮询
  等待支付回调」这类业务语义一起拦掉。前向引用（「以后续订正为准」「见后续订正」）
  一并封住——它和「修好后另发」是同一件事换个说法，实测被绕过一次。
- tests：4 个用例，含 1 个阴性对照（灰度开关状态、已知缺口工单号、业务流程里的等待
  必须放行），防止作者为了过门禁把该写的契约边界一起删掉。
- BACKEND_CHANGELOG_DELIVERY_GUIDE.md §2.1：写明规则、背景与那条分界线——这条影响
  他「怎么写代码」，还是只影响他「什么时候开始写」？后者一律删。

阳性对照：对已推送的 HEAD 版 20_7443 跑新规则，命中 2 处（第 308、451 行「修好后另发」），
即它能抓住真实发生过的那次。既有 changelog-path-aliases 测试对 11_7510 的 2 条
E_ALIAS_STATE 红是本次改动之前就存在的，与本提交无关，pre-push 钩子也不跑该用例。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-09-21 15:27:37 +08:00
API Changelog Bot和Claude Opus 5 ae069b00a9 fix: frontmatter 未转义的引号让元数据对所有消费方隐形——修 19_7443 + 给校验器补语法层
changelog-filename-gate / validate (push) Failing after 1s
详情 
现象：Gitea 上打开这份 changelog 看不到元数据表，页面表现就是「这份文件没有元数据」，
而文件里其实写着完整的 16 个键。

根因：status_note 是 YAML 双引号标量，正文里夹着未转义的 ASCII 双引号
（...请勿据此对外宣称"确认/改派已验证可用"）。YAML 在第一个内部引号处截断，
整块 frontmatter 解析失败，Gitea 于是静默不渲染。

为什么一直没人发现：本仓校验器的 parseFrontmatter 是朴素行解析——按第一个冒号切开、
两端引号成对就剥掉——它对「这份 YAML 下游读不读得了」零分辨力。于是这类文件长期处于
「校验器 PASS，而 Gitea 与任何 YAML 解析器都读不到」的状态，没有任何一处报错。
校验器回答的是自己那套宽松读法，不是消费方的读法。

改动两部分：
一、修 19_7443 那两个引号。转义只改字节不改语义，验过三条：改后 yaml.safe_load 成功、
    解析出的值与作者本意逐字相同、正文一个字节没动。
二、给校验器补上它完全没有的那一层：validateFrontmatterSyntax，新错误码
    E_FRONTMATTER_SYNTAX。本仓刻意零依赖，所以不引 YAML 库，按实际出过的三类伤写
    定向判据：内部未转义双引号 / 收尾引号丢失 / 非法转义序列。语法校验排在所有按键
    取值的校验之前——frontmatter 读不了的话，后面那些校验都是在校验一份只有本脚本
    能读的东西。

自验两个方向：三种人造伤各自被拦（exit=1）；全仓 1030 份逐批跑完，新增错误码
E_FRONTMATTER_SYNTAX 命中 0 次，无连带误伤；独立口径用真 YAML 解析器扫全仓，
546 份带 frontmatter 的全部可解析。

⚠️ 同一毛病另有 7 份存量文件未修（05_5530 / 08_5592 / 06_7149 / 10_7328 / 13_7625 /
15_7327 / 15_fund-account）。它们的元数据同样对 Gitea 隐形，修法已验证可行，
但每份都带着 1~3 条与本次无关的历史门禁错误（E_FRONTEND_STATE「verified 必须填写
target_release」为主，另有 E_AUTHOR / E_API_TEMPLATE / E_BACKEND_STATUS），
推不上去。补那些字段需要编造内容，不做。
🔴 值得记一笔的因果：正是门禁这个严格度让这 8 份一直坏着——谁想顺手修一下，
就会撞上一堆与自己无关的历史错误然后放弃。修复脚本留在
D:/work2/_scratch/changelog-fm-fix/，等 wx 决定是给存量文件开豁免还是补齐字段。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-09-20 11:04:32 +08:00
API Changelog Bot和Claude Opus 5 5a24c71fe0 feat(scripts): 校验器加 --verbose，成功路径也打印逐端点命中行
changelog-filename-gate / validate (push) Failing after 2s
详情 
背景：changelog 校验器的端点解析结果原本只在「清单与详情对不上」时才进 errors，
成功路径零输出（只有一行 PASS）。于是「每个端点都被校验过」这件事**无法取证**——
#7439 AC-19 要求「贴校验器输出里逐端点的命中行、端点数对得上」，判据字面不可达成。

改法：模块级开关 VERBOSE_ENDPOINTS，main 识别 --verbose 后从 argv 剔除再走原解析
（避免打乱 argv[0] === '--files' 的判断）。打印格式：

  [endpoint] <file> #<n> <METHOD> <path>
  [endpoint-count] <file> <n>

硬约束：**默认行为一个字节都不变**。它是提交门禁，加日志不得影响判定。
已验：同一组文件在改前/改后不带 --verbose 跑，stdout+stderr 逐字节 diff 为空；
仓内 14 条测试改前改后均 14 pass / 0 fail。

为什么值得改而不是改判据：逐端点证据对所有 changelog 都有用，
而「手工用同一条正则再枚举一遍」产出的不是校验器输出，等于用一个未经检验的
复制品去证明原件跑过了。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-09-13 13:04:22 +08:00
API Changelog Bot和Claude Fable 5.1 7f634e509d gate: 占位符检测忽略代码围栏与反引号内文本——接口枚举值本身可能叫 TODO（团期芯片聚合态，#7204） 
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01N7Xpgcv9nncadAXQtWhg4P
 2026-09-06 20:33:05 +08:00
API Changelog Bot和Claude Fable 5.1 354d9083a7 scripts: validate-changelog-frontmatter 增加 --files 提交前自检模式（与 pre-push 门禁同规则，供作者/Agent 与 hl-workflow lint 复用）
changelog-filename-gate / validate (push) Successful in 2s
详情 
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

Claude-Session: https://claude.ai/code/session_01XYL5S9SsBtkg7aGyFAbrrQ
 2026-09-06 16:18:27 +08:00
lc 3d6f6245a0 补齐行政区划三级联动接口文档与模板门禁（#6422）
changelog-filename-gate / validate (pull_request) Successful in 2s
详情
2026-08-26 16:23:19 +08:00
API Changelog Bot和Claude Fable 5 65ddaae00f fix(scripts): 校验规则去假阳性——前端/修复类条目合法化+路径参数不误判占位符 
- CHANGE_TYPES 扩:修复/前端缺陷/前端优化/前端修复(文件名+frontmatter 同步);纯前端条目 issue 段允许 frontend 字面量、backend_status 允许 not_required(接口类仍禁)
- E_PLACEHOLDER 只拦双花括号/TODO/待补充,不再误杀 {orderId} 等 REST 路径参数
- E_SECTIONS 仅约束接口类条目,章节名宽匹配(变更接口/变更清单/接口变化/行为变化等)
- 核心门禁保持硬:接口类必须 backend_status=deployed 才允许发布(E_BACKEND_PENDING)
- 背景:规则假阳性致 CI 长期常红被忽略,真违规(未部署即推送)淹没其中;npm test 46/46 绿

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
 2026-08-10 16:36:48 +08:00
wx 6cbe22f40a feat: track frontend changelog consumption (#5218)
changelog-filename-gate / validate (pull_request) Successful in 2s
详情
2026-07-24 15:22:10 +08:00