changelog

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

changelog

Generate or update the changelog entry for the current branch under

changelog/YYYYMMDD-HHMMSS-<slug>.md

: derive its metadata from git and the diff, write the frontmatter and a grouped, categorised body, run the deterministic enrichment scripts, then validate the result.

This skill is the single source of truth for what a valid changelog entry is — the frontmatter schema, the field-ownership boundaries, idempotent update-vs-create, and the validation gate. The same contract is enforced downstream by a consumer repo's CI and relied on by a release-orchestrator that finalises the post-merge fields, so the authoring rules live here once.

It is invoked two ways:

Standalone (
```
/changelog
```
) — author, refresh, or repair this branch's entry and leave it uncommitted in the working tree for review. No commit, push, or PR.
Inside a ship flow (e.g. a
```
/send-it
```
) — the changelog step that runs before push; the ship flow commits the entry, pushes, and opens the PR.

生成或更新当前分支的changelog条目，存储在

changelog/YYYYMMDD-HHMMSS-<slug>.md

路径下：从git和差异中提取元数据，编写前置内容和分组分类的正文，运行确定性增强脚本，然后验证结果。

该技能是有效changelog条目标准的唯一权威来源——包括前置内容 schema、字段归属边界、幂等更新/创建逻辑以及验证机制。下游消费仓库的CI会强制执行同一标准，发布编排工具也会依赖该标准来完善合并后的字段，因此编写规则仅在此处定义一次。

它有两种调用方式：

独立调用（
```
/changelog
```
）——撰写、刷新或修复当前分支的条目，将其未提交地留在工作区供审核。不会执行提交、推送或创建PR操作。
嵌入发布流程（例如
```
/send-it
```
）——在推送前运行的changelog步骤；发布流程会提交该条目、推送代码并创建PR。

Configuration

配置

Config lives in

config.json

beside this file; the bundled scripts read it automatically. Edit your copied

config.json

to match the consuming repo (a neutral

config.example.json

ships as a template).

issueKeys

and

linearWorkspaceSlug

are required — they have no default, so a missing

config.json

or either key absent makes the scripts fail loudly rather than silently inherit ACME's identity. The rest are structural and keep generic, overridable defaults:

Key	Meaning	Default
`issueKeys`	Team-key prefixes used to recognise issue IDs in the branch and body. The issue-ID regex is built from these.	required
`linearWorkspaceSlug`	Linear workspace slug used to build issue links ( `https://linear.app/<slug>/issue/<id>` ).	required
`baseBranch`	The trunk the branch diff is taken against ( `origin/<baseBranch>` ). Overridable per-run via the `BASE_REF` env var.	`"main"`
`changelogDir`	Directory the dated entries live in (scanned by the enrichment + validation scripts).	`"changelog"`
`packageRoots`	Monorepo dir prefixes mapping `<root>/<x>/…` → package `<x>` when deriving `affected_packages` .	`["apps", "packages", "services"]`
`fallbackPackage`	Package name for changed paths matching no `packageRoots` prefix.	`"infrastructure"`
`affectedPackages`	Whether to emit the `affected_packages` field at all. Leave `false` for single-package repos (the field is write-only and redundant there — entries stay clean); set `true` in genuine monorepos. `initialise-skills` flips it on when it detects a workspace config.	`false`

All bundled scripts use only Node built-ins — no

npm install

, no build step. They operate on the consumer repo's root
changelog/
directory (run them from the repo root).

配置文件为该技能旁的

config.json

；捆绑脚本会自动读取该文件。编辑你复制的

config.json

以匹配消费仓库的需求（附带一个中立的

config.example.json

作为模板）。

issueKeys

和

linearWorkspaceSlug

为必填项——它们没有默认值，因此缺失

config.json

或任一必填项会导致脚本直接报错，而非默认继承ACME的标识。其余配置为结构性设置，带有可覆盖的通用默认值：

配置项	说明	默认值
`issueKeys`	用于识别分支和正文中问题ID的团队密钥前缀。问题ID正则表达式将基于这些前缀构建。	必填
`linearWorkspaceSlug`	用于构建问题链接的Linear工作区标识（格式： `https://linear.app/<slug>/issue/<id>` ）。	必填
`baseBranch`	分支差异对比的基准主干分支（ `origin/<baseBranch>` ）。可通过 `BASE_REF` 环境变量在每次运行时覆盖。	`"main"`
`changelogDir`	日期化条目存储的目录（增强和验证脚本会扫描该目录）。	`"changelog"`
`packageRoots`	单仓多包项目的目录前缀，用于将 `<root>/<x>/…` 路径映射为包 `<x>` ，以提取 `affected_packages` 字段。	`["apps", "packages", "services"]`
`fallbackPackage`	当变更路径不匹配任何 `packageRoots` 前缀时使用的默认包名。	`"infrastructure"`
`affectedPackages`	是否输出 `affected_packages` 字段。单包项目请设为 `false` （该字段在此场景下冗余，可保持条目简洁）；多包项目请设为 `true` 。 `initialise-skills` 工具检测到工作区配置时会自动开启该选项。	`false`

所有捆绑脚本仅使用Node内置模块——无需

npm install

，也无需构建步骤。它们操作的是消费仓库根目录下的
changelog/
目录（请在仓库根目录运行脚本）。

Running it

运行步骤

Step 1 — Detect an existing entry (idempotency)

步骤1——检测现有条目（幂等性）

Grep

changelog/

for a file whose frontmatter contains

branch: "<current-branch>"

. If exactly one matches, you are in update mode: preserve its

created_at

and filename, rewrite the rest. Otherwise you are in create mode.

在

changelog/

目录中查找前置内容包含

branch: "<current-branch>"

的文件。如果找到恰好一个匹配文件，则进入更新模式：保留其

created_at

字段和文件名，重写其余内容。否则进入创建模式。

Step 2 — Analyse the branch

步骤2——分析分支

```
git log origin/<base>..HEAD --pretty=full
```
— full commit list including bodies and trailers.
```
git diff origin/<base>...HEAD --name-only
```
— changed files, for grouping the body by package.

<base>

config.json

baseBranch

(default

main

). Fetch it first (

git fetch origin <base>

) so the diff is accurate — skip the fetch if the caller already did it (e.g. a ship flow fetches in its preflight step).

```
git log origin/<base>..HEAD --pretty=full
```
——包含正文和尾部信息的完整提交列表。
```
git diff origin/<base>...HEAD --name-only
```
——变更文件列表，用于按包分组正文内容。

<base>

为

config.json

中的

baseBranch

（默认值为

main

）。请先拉取该分支（

git fetch origin <base>

）以确保差异准确——如果调用方已执行拉取操作（例如发布流程在预检步骤中已拉取），则可跳过此步骤。

Step 3 — Derive metadata

步骤3——提取元数据

Field	How to derive
`issues`	Match the issue-ID regex (built from `issueKeys` ) against the branch name (upper-cased) and against commit subjects/bodies. Deduplicate.
`author`	`git config user.email` .
`co_authors`	Parse `Co-authored-by: Name <email>` trailers across all branch commits. Store the email or `Name <email>` form. Empty array if none.
`category`	Infer from commit subjects and diff: `feature` , `fix` , `chore` , `docs` , `refactor` , `perf` . If ambiguous, ask the user to confirm.
`breaking`	Infer from `BREAKING CHANGE:` trailers, `!` in conventional-commit subjects, or removal of public surfaces. If unclear, ask the user. Default `false` .
`release_note`	One-sentence user-facing summary distinct from `title` . Optional — leave blank if the change has no public-facing impact (chore, internal refactor).

Field ownership — what this skill authors vs. what it must leave alone is the crux of the contract; see

references/changelog-contract.md

for the full rules. In short:

Authored here:
```
title
```
,
```
release_note
```
,
```
category
```
,
```
breaking
```
,
```
issues
```
,
```
co_authors
```
,
```
author
```
, and — only when
affectedPackages
is on —
```
affected_packages
```
(written by the enrichment script in Step 5, not hand-edited). Single-package repos leave
```
affectedPackages: false
```
(the default) and omit the field entirely.
created_at
is sacred — set once on create (UTC time of first run); on update, preserve it verbatim.
Never authored here:
```
stats
```
(
```
files_changed
```
,
```
loc_added
```
,
```
loc_removed
```
,
```
commits
```
) and the post-merge fields
```
merged_at
```
/
```
commit
```
/
```
pr
```
/
```
merge_strategy
```
. A release step finalises them from canonical GitHub PR data after merge —
```
pr
```
included, resolved from the merged PR by its
```
branch:
```
(never written by the ship flow). Emit them as blank placeholders on create; leave existing values untouched on update.

The skill emits the derived
issues
array as a handoff — a ship flow reuses it for the PR body and any Linear writeback (e.g. via a

linear-sync

skill).

字段	提取方式
`issues`	基于 `issueKeys` 构建的正则表达式，匹配分支名称（大写）以及提交主题/正文中的问题ID，并进行去重。
`author`	取自 `git config user.email` 。
`co_authors`	解析所有分支提交中的 `Co-authored-by: Name <email>` 尾部信息。存储格式为邮箱或 `Name <email>` 。若无协作者则为空数组。
`category`	从提交主题和差异中推断： `feature` 、 `fix` 、 `chore` 、 `docs` 、 `refactor` 、 `perf` 。若存在歧义，则询问用户确认。
`breaking`	从 `BREAKING CHANGE:` 尾部信息、规范提交主题中的 `!` 或公共接口的移除操作中推断。若无法确定，则询问用户。默认值为 `false` 。
`release_note`	面向用户的单句摘要，与 `title` 区分开。可选字段——若变更无面向用户的影响（例如chore、内部重构），则留空。

字段归属——该技能负责撰写哪些字段、必须保留哪些字段是契约的核心；完整规则请参阅

references/changelog-contract.md

。简而言之：

在此处撰写：
```
title
```
、
```
release_note
```
、
```
category
```
、
```
breaking
```
、
```
issues
```
、
```
co_authors
```
、
```
author
```
，以及——仅当
affectedPackages
开启时——
```
affected_packages
```
（由步骤5中的增强脚本写入，而非手动编辑）。单包项目请设置
```
affectedPackages: false
```
（默认值），并完全省略该字段。
created_at
为只读字段——仅在创建时设置一次（首次运行的UTC时间）；更新时需完全保留原始值。
绝不在此处撰写：
```
stats
```
（
```
files_changed
```
、
```
loc_added
```
、
```
loc_removed
```
、
```
commits
```
）以及合并后的字段
```
merged_at
```
/
```
commit
```
/
```
pr
```
/
```
merge_strategy
```
。发布步骤会在合并后从GitHub PR的标准数据中完善这些字段——包括
```
pr
```
字段，它会通过合并PR的
```
branch:
```
字段解析（绝不会由发布流程写入）。创建条目时将这些字段作为空白占位符输出；更新时保留现有值不变。

该技能会输出提取到的
issues
数组作为传递数据——发布流程可将其复用至PR正文以及任何Linear回写操作（例如通过

linear-sync

技能）。

Step 4 — Generate the body

步骤4——生成正文

Group bullets by package, categorised under

## Added

## Changed

## Fixed

. Only include headings that have entries. For multi-package changes use

**<pkg-name>:**

subheaders.

breaking: true

, the body MUST start with a

## Breaking

section describing the change and the migration path.

Write the

title

release_note

, and body prose in the consuming repo's documented prose language. Across this estate that is British English (

colour

behaviour

-ise

-yse

) — prose only, never identifiers, dependency names, or upstream API field names.

按包分组项目符号，归类到

## Added

## Changed

## Fixed

标题下。仅保留包含内容的标题。对于多包变更，请使用

**<pkg-name>:**

子标题。

若

breaking: true

，正文必须以

## Breaking

部分开头，描述变更内容和迁移路径。

title

、

release_note

和正文的 prose 需使用消费仓库指定的语言。在本环境中为英式英语（例如

colour

、

behaviour

、

-ise

-yse

）——仅适用于prose，标识符、依赖名称或上游API字段名称除外。

Step 5 — Write or update the file

步骤5——写入或更新文件

Filename:

changelog/YYYYMMDD-HHMMSS-<slug>.md

, where the timestamp is

created_at

(UTC time of first run) and the slug derives from

title

(lowercase, non-alphanumerics →

, collapse repeats, ~60-char cap on a word boundary).

Always quote timestamp strings in YAML (

created_at: "2026-04-26T13:24:00Z"

). Unquoted ISO timestamps parse as Date objects and gain

.000Z

millis on the enrichment round-trip; quoting keeps them lossless.

On update: preserve

created_at

and the filename; rewrite

title

release_note

category

breaking

co_authors

issues

, and the body; leave

merged_at

commit

pr

merge_strategy

stats

alone (the release/enrich step fills them post-merge,

pr

branch-resolved).

Use the frontmatter field order shown in

references/changelog-contract.md

. Only when
affectedPackages
is on, emit

affected_packages: []

as a placeholder — the script fills it in place. When it is off (the single-package default), omit the field;

set-affected-packages.mjs

is a no-op.

Then run the two deterministic enrichment scripts from the consumer repo root (both idempotent; they match the entry by its

branch:

frontmatter and leave the post-merge fields blank):

bash

node skills/changelog/scripts/set-affected-packages.mjs   # writes affected_packages from the branch diff
node skills/changelog/scripts/add-links.mjs               # rewrites bare issue IDs in the current branch's entry to Linear URLs

Adjust the path prefix if you installed the skill to a different location.

Both enrichment scripts also accept

--check

(alias

--dry-run

) — a read-only preview that reports what would change and writes nothing, exiting

when the entry is already up to date and

when a rewrite is needed (prettier-

--check

style, so CI can gate on it):

bash

node skills/changelog/scripts/set-affected-packages.mjs --check   # current branch's entry only
node skills/changelog/scripts/add-links.mjs --check               # ALL entries in the changelog dir

Both enrichers are branch-scoped by default (A-603):

add-links.mjs

with no arguments rewrites only the entry/entries whose

branch:

frontmatter matches the current git branch, so authoring a new entry never churns unrelated, already-merged ones. Two modes still scan the whole directory:

--all

(a deliberate full-directory rewrite) and

--check

--dry-run

(the completeness gate, which can exit

on a historical entry). Use

--check

to confirm the directory is fully enriched; use the default for the per-PR pass on one branch's entry. (When git is unavailable the default falls back to the full sweep.)

文件名：

changelog/YYYYMMDD-HHMMSS-<slug>.md

，其中时间戳为

created_at

（首次运行的UTC时间），

slug

由

title

派生而来（小写，非字母数字字符替换为

，合并重复符号，在单词边界处限制约60字符）。

YAML中的时间戳字符串必须加引号（例如

created_at: "2026-04-26T13:24:00Z"

）。未加引号的ISO时间戳会被解析为Date对象，在增强脚本往返过程中会添加

.000Z

毫秒；加引号可确保数据无损失。

更新时：保留

created_at

和文件名；重写

title

、

release_note

、

category

、

breaking

、

co_authors

、

issues

和正文；保留

merged_at

commit

pr

merge_strategy

stats

不变（这些字段由发布/增强步骤在合并后填充，

pr

字段通过分支解析）。

请遵循

references/changelog-contract.md

中所示的前置内容字段顺序。仅当
affectedPackages
开启时，输出

affected_packages: []

作为占位符——脚本会自动填充该字段。当

affectedPackages

关闭时（单包项目默认值），省略该字段；

set-affected-packages.mjs

将不执行任何操作。

然后在消费仓库根目录运行两个确定性增强脚本（均支持幂等性；它们通过前置内容中的

branch:

字段匹配条目，并保留合并后的字段为空）：

bash

node skills/changelog/scripts/set-affected-packages.mjs   # 从分支差异中写入affected_packages字段
node skills/changelog/scripts/add-links.mjs               # 将当前分支条目中的裸问题ID重写为Linear URL

如果技能安装在其他位置，请调整路径前缀。

两个增强脚本均支持

--check

（别名

--dry-run

）——只读预览模式，报告将要进行的变更但不写入任何内容，当条目已为最新时返回

，当需要重写时返回

（与prettier的

--check

风格一致，因此CI可基于此进行校验）：

bash

node skills/changelog/scripts/set-affected-packages.mjs --check   # 仅检查当前分支的条目
node skills/changelog/scripts/add-links.mjs --check               # 检查changelog目录中的所有条目

两个增强脚本默认按分支范围处理（A-603）：无参数的

add-links.mjs

仅重写前置内容中

branch:

字段匹配当前git分支的条目，因此撰写新条目时绝不会修改已合并的无关条目。仍有两种模式会扫描整个目录：

--all

（主动重写整个目录）和

--check

--dry-run

（完整性校验，可能因历史条目不符合要求而返回

）。使用

--check

确认目录已完全增强；默认模式用于PR流程中对单个分支条目的处理。（当git不可用时，默认模式会回退为扫描整个目录。）

Step 6 — Validate against the contract

步骤6——根据契约验证

This is the gate:

bash

node scripts/preflight-changelog-ci.mjs   # optional: checks Node vs engines/.nvmrc, then pnpm install --frozen-lockfile
node scripts/validate-changelog.mjs       # validates frontmatter schema, filename format, field types, ISO timestamps, Breaking section, issue IDs

preflight-changelog-ci.mjs

is optional and pnpm-specific — skip it if the consumer repo doesn't use pnpm. On failure, stop and fix the entry before continuing — do not hand a malformed entry to the ship flow.

这是校验关卡：

bash

node scripts/preflight-changelog-ci.mjs   # 可选：检查Node版本与engines/.nvmrc是否匹配，然后执行pnpm install --frozen-lockfile
node scripts/validate-changelog.mjs       # 验证前置内容schema、文件名格式、字段类型、ISO时间戳、Breaking部分、问题ID

preflight-changelog-ci.mjs

为可选且仅适用于pnpm——如果消费仓库不使用pnpm，请跳过该脚本。若验证失败，请停止并修复条目后再继续——不要将格式错误的条目提交至发布流程。

Standalone vs inside a ship flow

独立调用 vs 嵌入发布流程

Standalone (
/changelog
) runs Steps 1–6 and then reports, leaving the entry uncommitted in the working tree for the user to review and commit. It never pushes or opens a PR.
Inside a ship flow the same steps run before push; the ship flow then commits the entry (
```
docs(changelog): <title>
```
), pushes, and opens or updates the PR. It leaves
```
pr
```
blank — the release/enrich step fills it post-merge, branch-resolved from the merged PR.

独立调用（
/changelog
）运行步骤1-6后生成报告，将条目未提交地留在工作区供用户审核和提交。绝不会执行推送或创建PR操作。
嵌入发布流程时，相同步骤会在推送前运行；发布流程随后会提交该条目（提交信息为
```
docs(changelog): <title>
```
）、推送代码并创建或更新PR。
```
pr
```
字段留空——发布/增强步骤会在合并后通过分支解析填充该字段。

Implementation

实现细节

All the scripts the changelog lifecycle needs live under

scripts/

in this bundle and run on plain Node (no npm dependencies, no build step). They cover the whole lifecycle the bundle owns — authoring (run by this skill) and finalisation (wired into the consumer's

package.json

/ CI / release orchestrator). Each takes

--help

(usage, exit 0) and

--self-test

(an offline smoke test of its pure logic); the file-writing scripts also take

--check

--dry-run

(report, write nothing).

Authoring — run by this skill (the
/changelog
flow):

```
scripts/set-affected-packages.mjs
```
— writes
```
affected_packages
```
from the branch diff (monorepo consumers only; a no-op when
```
affectedPackages
```
is off).
```
scripts/add-links.mjs
```
— rewrites bare issue IDs in the body to Linear URLs.
```
scripts/preflight-changelog-ci.mjs
```
— optional Node/lockfile CI-parity check (pnpm).
```
scripts/validate-changelog.mjs
```
— validates the entry against the contract.

Finalisation and the CI gate — run by the consumer, not by this skill. These ship in the bundle too, and an adopter wiring up the orchestrator/CI gate needs them. They are referenced from the consumer's

package.json

scripts and workflows rather than invoked during authoring:

```
scripts/finalise-changelog.mjs
```
— release-time enrichment + version-stamping for npm targets, run by the release orchestrator right after
```
release-please release-pr
```
(the consumer exposes it as the
```
changelog:finalise
```
script). For each un-finalised entry it resolves the merged PR via
```
gh
```
/
```
git
```
, fills the post-merge fields (
```
merged_at
```
/
```
commit
```
/
```
pr
```
/
```
merge_strategy
```
/
```
stats
```
, the last including the merge-excluded
```
commits
```
count from the PR commits API), stamps
```
version
```
with the just-bumped
```
package.json
```
version, and links bare Linear IDs. It composes
```
lib/enrich.mjs
```
(the PR-metadata fill),
```
lib/commit-count.mjs
```
(the merge-excluded commit count) and
```
lib/stamp.mjs
```
(the version stamp).
```
scripts/enrich-changelog.mjs
```
— post-merge enrichment for deploy targets (octavo, shared-workflows), which are never checked out during the release flow and so can't finalise inline. Run by the release orchestrator's daily
enrich-changelogs.yml
cron on the checked-out target (the consumer exposes it as the
```
changelog:enrich
```
script). It reads one merged PR's data from an env-var interface (
```
BRANCH_NAME
```
/
```
MERGED_AT
```
/
```
MERGE_SHA
```
/
```
MERGE_STRATEGY
```
/
```
PR_NUMBER
```
/
```
ADDITIONS
```
/
```
DELETIONS
```
/
```
CHANGED_FILES
```
), finds the entry by its
```
branch:
```
, and fills the same post-merge field group as finalise (minus
```
version
```
, which a deploy target's own tag flow owns, and minus
```
commits
```
, which the cron doesn't resolve). A thin wrapper over
```
lib/enrich.mjs
```
; fill-once and idempotent, so the cron can re-run safely.
```
--check
```
exits 1 when an entry still needs enriching;
```
--dry-run
```
previews.
```
scripts/check-changelog-completeness.mjs
```
— the CI completeness gate, run by the consumer's validation workflow: a release-triggering (
```
feat
```
/
```
fix
```
/breaking) PR title must carry a dated
```
changelog/
```
entry, or the build fails.
```
scripts/backfill-commits.mjs
```
— a one-off backfill of
```
stats.commits
```
across the existing
```
changelog/
```
backlog (for adopting the count after the fact). Resolves each entry's merged PR via
```
gh
```
, splices in only the
```
commits
```
line (no re-serialise), and is idempotent;
```
--dry-run
```
previews. Not part of authoring or the release flow.

They share helpers under

scripts/lib/

(

changelog.mjs

derive-packages.mjs

frontmatter.mjs

config.mjs

enrich.mjs

commit-count.mjs

stamp.mjs

). So while this skill itself stops at authoring + validation and leaves the post-merge fields blank, the finalisation and completeness scripts that fill them are part of this bundle — the consumer's

package.json

/ CI / release orchestrator run them, not the

/changelog

flow.

Note for adopters: unit tests for these scripts are maintained in the
agent-skills
repo (not bundled into the skill). See the skill's README.

changelog生命周期所需的所有脚本均位于此捆绑包的

scripts/

目录下，可在纯Node环境运行（无npm依赖，无需构建步骤）。它们覆盖了捆绑包负责的整个生命周期——撰写（由该技能运行）和完善（集成到消费仓库的

package.json

/CI/发布编排工具中）。每个脚本均支持

--help

（显示用法，返回0）和

--self-test

（离线冒烟测试纯逻辑）；写入文件的脚本还支持

--check

--dry-run

（报告变更但不写入）。

撰写阶段——由该技能运行（
/changelog
流程）：

```
scripts/set-affected-packages.mjs
```
——从分支差异中写入
```
affected_packages
```
字段（仅适用于多包项目；当
```
affectedPackages
```
关闭时不执行任何操作）。
```
scripts/add-links.mjs
```
——将正文中的裸问题ID重写为Linear URL。
```
scripts/preflight-changelog-ci.mjs
```
——可选的Node/锁文件CI一致性检查（适用于pnpm）。
```
scripts/validate-changelog.mjs
```
——根据契约验证条目。

完善阶段和CI校验——由消费仓库运行，而非该技能。这些脚本也包含在捆绑包中，集成编排工具/CI校验的用户需要它们。它们会被引用到消费仓库的

package.json

脚本和工作流中，而非在撰写阶段调用：

```
scripts/finalise-changelog.mjs
```
——针对npm目标的发布时增强和版本标记，由发布编排工具在
release-please release-pr
之后运行（消费仓库将其暴露为
```
changelog:finalise
```
脚本）。对于每个未完善的条目，它通过
```
gh
```
/
```
git
```
解析合并后的PR，填充合并后的字段（
```
merged_at
```
/
```
commit
```
/
```
pr
```
/
```
merge_strategy
```
/
```
stats
```
，其中
```
stats
```
包含PR提交API中排除合并提交的
```
commits
```
计数），用刚更新的
```
package.json
```
版本标记
```
version
```
字段，并链接裸Linear ID。它整合了
```
lib/enrich.mjs
```
（填充PR元数据）、
```
lib/commit-count.mjs
```
（排除合并提交的计数）和
```
lib/stamp.mjs
```
（版本标记）。
```
scripts/enrich-changelog.mjs
```
——针对部署目标（octavo、shared-workflows）的合并后增强，这些目标在发布流程中不会被检出，因此无法在线完善。由发布编排工具的每日
enrich-changelogs.yml
定时任务在检出的目标上运行（消费仓库将其暴露为
```
changelog:enrich
```
脚本）。它从环境变量接口（
```
BRANCH_NAME
```
/
```
MERGED_AT
```
/
```
MERGE_SHA
```
/
```
MERGE_STRATEGY
```
/
```
PR_NUMBER
```
/
```
ADDITIONS
```
/
```
DELETIONS
```
/
```
CHANGED_FILES
```
）读取单个合并PR的数据，通过
```
branch:
```
字段找到对应条目，并填充与finalise脚本相同的合并后字段组（不含
```
version
```
，该字段由部署目标自身的标签流程负责；不含
```
commits
```
，定时任务不会解析该字段）。它是
```
lib/enrich.mjs
```
的轻量封装；支持一次性填充且幂等，因此定时任务可安全重跑。
```
--check
```
在条目仍需增强时返回1；
```
--dry-run
```
提供预览。
```
scripts/check-changelog-completeness.mjs
```
——CI完整性校验关卡，由消费仓库的验证工作流运行：触发发布的PR标题（
```
feat
```
/
```
fix
```
/破坏性变更）必须包含
```
changelog/
```
目录下的日期化条目，否则构建失败。
```
scripts/backfill-commits.mjs
```
——一次性回填现有
```
changelog/
```
历史条目中的
```
stats.commits
```
字段（用于在事后采用该计数）。它通过
```
gh
```
解析每个条目的合并PR，仅插入
```
commits
```
字段（不重新序列化），且支持幂等；
```
--dry-run
```
提供预览。不属于撰写或发布流程的一部分。

这些脚本共享

scripts/lib/

目录下的工具模块（

changelog.mjs

、

derive-packages.mjs

、

frontmatter.mjs

、

config.mjs

、

enrich.mjs

、

commit-count.mjs

、

stamp.mjs

）。因此，尽管该技能仅负责撰写+验证，并保留合并后的字段为空，但填充这些字段的完善和完整性脚本也属于该捆绑包——由消费仓库的

package.json

/CI/发布编排工具运行，而非

/changelog

流程。

**适配者注意事项：**这些脚本的单元测试维护在
agent-skills
仓库中（未包含在技能捆绑包内）。请参阅技能的README文档。",