release

发布工作流

为 agentic-qe 包执行安全且经过验证的 npm 发布。每个阶段结束后都要停止并等待用户确认。

架构

本项目采用扁平的单包结构（v3.7.4 之后已扁平化）：

文件	包名	作用
package.json（根目录）	agentic-qe	发布到 npm — 可安装的软件包

• npm run build 执行 tsc && build:cli && build:mcp，在根目录生成 dist/
• npm publish 从根目录运行
• GitHub Actions 通过 .github/workflows/npm-publish.yml 在 release: published 事件触发

重要：不存在 v3/ 子目录。所有源文件都在根目录（src/、dist/、tests/）。

参数

• <version> — 目标版本（例如 3.7.5）。如果省略，请提示用户。

步骤

1. 发布前检查：确保状态干净

git status
git branch --show-current

确认工作目录干净，并确认当前所在分支。如果存在未提交的更改，请停止并询问用户。发布准备工作在当前工作分支上进行——稍后再向 main 提交 PR。

停止 — 确认状态干净且当前分支已明确。

2. 版本审计

从 package.json 读取当前版本（唯一可信来源）。然后在整个代码库中搜索硬编码的版本字符串——包括当前版本、旧版本以及任何类似版本号的模式。

# Read current version
node -p "require('./package.json').version"

# Search for version strings in source files (exclude node_modules, dist, .git, docs/releases)
grep -rn --include="*.ts" --include="*.js" --include="*.json" '"3\.[0-9]\+\.[0-9]\+"' . \
  --exclude-dir=node_modules --exclude-dir=dist --exclude-dir=.git --exclude-dir=releases

同时检查 .claude/skills/skills-manifest.json 中的 fleetVersion — 必须更新为一致的版本。

如果在源文件中发现任何过时的版本字符串，请全部修正后再继续。

停止 — 展示检查结果并等待用户确认。

3. 更新版本

将 package.json 更新为目标版本：

cd /workspaces/agentic-qe && npm version <version> --no-git-tag-version

同时更新 .claude/skills/skills-manifest.json 中的 fleetVersion。

npm version 会运行 version 生命周期脚本（scripts/sync-plugin-versions.cjs），该脚本也会更新 Claude Code 插件相关位置：.claude-plugin/plugin.json（版本和 agentic-qe@<version> MCP 固定版本）、plugins/agentic-qe-fleet/.claude-plugin/plugin.json（版本）以及 plugins/agentic-qe-fleet/.mcp.json（agentic-qe@<version> 固定版本）。如果插件本身有变更，请在 plugins/agentic-qe-fleet/CHANGELOG.md 中添加 ## <version> — <date> 条目。

验证：

grep '"version"' package.json
node scripts/sync-plugin-versions.cjs --check   # must print "in sync"
bash plugins/agentic-qe-fleet/scripts/smoke.sh  # plugin contract incl. MCP pin

停止 — 确认版本正确。

4. 更新 CHANGELOG

按照 Keep a Changelog 格式，在根目录的 CHANGELOG.md 中添加新章节：

## [<version>] - YYYY-MM-DD

### Added
- ...

### Fixed
- ...

### Changed
- ...

描述应便于用户理解，重点说明带来的价值，而不是实现细节。

停止 — 展示 CHANGELOG 条目供审核。

4b. 更新发布文档

按照现有格式，在 docs/releases/v<version>.md 创建发布说明文件：

# v<version> Release Notes

**Release Date:** YYYY-MM-DD

## Highlights

<1-2 sentence summary of the most important changes>

## Added
- ...

## Fixed
- ...

## Changed
- ...

然后更新 docs/releases/README.md — 在表格顶部添加新行：

| [v<version>](v<version>.md) | YYYY-MM-DD | <Short highlights> |

参照现有条目的格式。亮点描述保持简洁（少于 80 个字符）。

5. 构建

npm run build

执行 tsc && build:cli && build:mcp。确认没有错误。如果构建失败，请诊断并修复。

停止 — 展示构建输出。

6. 类型检查

npm run typecheck

运行 tsc --noEmit。必须没有错误。

停止 — 展示类型检查输出。

7. 单元测试

npx vitest run tests/unit/

针对实际代码库运行真正的测试。不得模拟、mock 或跳过任何测试。所有单元测试都必须通过。

停止 — 展示测试结果。

8. 构件与集成验证

这是发布前的关键关卡。验证构建后的包能够像用户实际使用时那样端到端运行。

8a. 验证构建产物

# Verify dist/ exists with expected bundles
ls -la dist/cli/bundle.js
ls -la dist/index.js
ls -la dist/mcp/bundle.js

以下三项都必须存在：CLI bundle、主入口点、MCP 服务。

8b. 在全新项目中测试 aqe init --auto

# Create a temporary test project
mkdir -p /tmp/aqe-release-test && cd /tmp/aqe-release-test

# Run init using the LOCAL build (not published version)
node /workspaces/agentic-qe/dist/cli/bundle.js init --auto

确认初始化无错误完成，并创建预期的项目结构（.agentic-qe/ 目录、配置文件）。

8c. 验证 CLI

# Version output
node /workspaces/agentic-qe/dist/cli/bundle.js --version

# System status
node /workspaces/agentic-qe/dist/cli/bundle.js status

两项都必须成功运行且无错误。

8d. 验证自学习与 Fleet 功能

cd /tmp/aqe-release-test

# Verify learning subsystem
node /workspaces/agentic-qe/dist/cli/bundle.js learning stats 2>&1 | head -10

# Verify agent listing works
node /workspaces/agentic-qe/dist/cli/bundle.js agent list 2>&1 | head -10

# Verify health check
node /workspaces/agentic-qe/dist/cli/bundle.js health 2>&1 | head -10

这些功能应能正常响应（即使结果为空），且无错误，以确认子系统已正确初始化。

8e. 隔离依赖检查（捕获缺失的外部依赖）

# Pack and install in a clean temp directory to simulate real user install
CLEAN_DIR=$(mktemp -d)
npm pack --pack-destination "$CLEAN_DIR" 2>&1 | tail -2
cd "$CLEAN_DIR"
npm init -y > /dev/null 2>&1
npm install ./agentic-qe-<version>.tgz 2>&1 | tail -3
node node_modules/.bin/aqe --version 2>&1
EXIT=$?
echo "Exit code: $EXIT"
cd /workspaces/agentic-qe
rm -rf "$CLEAN_DIR"

必须以状态码 0 退出并打印正确的版本。如果因 ERR_MODULE_NOT_FOUND 崩溃，则说明某个依赖在构建脚本中被标记为外部依赖，却没有列在 dependencies 中。可通过将其打包、延迟加载或添加到 dependencies 中修复。

8f. 清理

rm -rf /tmp/aqe-release-test

停止——显示所有验证结果。继续之前，每项检查都必须通过。

9. 本地 CI 测试套件

运行 CI 在 PR 上和发布期间执行的相同测试。除非用户明确要求，否则跳过端到端浏览器测试。

cd /workspaces/agentic-qe

# Performance gates (fast — validates perf thresholds)
npm run performance:gate

# Regression tests (runs full unit suite)
npm run test:regression

# Full test:ci suite (from npm-publish.yml — excludes browser/e2e)
npm run test:ci

可用的测试脚本：test:unit、test:unit:fast、test:unit:heavy、test:unit:mcp、test:ci、test:regression、test:safe、test:perf、test:e2e、test:coverage、performance:gate。

所有必需的测试套件都必须通过。预先存在的 MCP 处理程序测试失败（需要运行时初始化的测试）可以接受，前提是它们在主分支上也会失败。

停止——显示所有测试结果。

10. 提交并创建指向 Main 的 PR

重要：PR 正文必须遵循 .github/PULL_REQUEST_TEMPLATE.md。CI 会通过 scripts/check-pr-body.cjs 强制执行此要求（issue #401）。两项硬性要求：

1. 包含 ### Required check (issue #401) 部分，并将 failure-modes 复选框标记为 [x]
2. 不得使用被禁止的否定性措辞（例如 "I believe it's unlikely"、"can't see how this would fail" 等），除非在同一段落中引用了跟踪 issue

cd /workspaces/agentic-qe

# Stage version bump + changelog + release docs + any version audit fixes
git add package.json package-lock.json CHANGELOG.md docs/releases/README.md docs/releases/v<version>.md
git add .claude/skills/skills-manifest.json  # if fleetVersion was updated
git add .claude-plugin/plugin.json plugins/agentic-qe-fleet/.claude-plugin/plugin.json \
  plugins/agentic-qe-fleet/.mcp.json plugins/agentic-qe-fleet/CHANGELOG.md
git status

git commit -m "chore(release): bump version to v<version>"
git push origin <current-branch>

# Create PR to main
gh pr create \
  --base main \
  --title "chore(release): v<version>" \
  --body "$(cat <<'EOF'
## Summary

<1-3 sentences: what changed and why, from the CHANGELOG>

## Verification

<Paste actual command output from steps 5-9: build, typecheck, test counts,
aqe init --auto result, CLI --version, performance gate results.
Real output, not summaries.>

## Failure modes

<List any failure modes this release introduces, mitigates, or doesn't cover.
Be honest about what wasn't tested. If none, say "No new failure modes introduced.">

---

### Required check (issue #401)

- [x] **Every failure mode mentioned in this PR description has either (a) a test that exercises it, or (b) a linked tracking issue.** "Unlikely" is not an acceptable substitute. If you wrote "I don't think this can happen but...", that sentence is a failure mode and needs a test or an issue link.

### Optional context

- Linked issues: #
- Trust tier change (if any): none
- Affects published API or CLI surface: yes / no
- Touches the init flow / `npm-publish.yml` / `tests/fixtures/init-corpus/`: yes / no
  - If yes: did you run `./tests/fixtures/init-corpus/run-gate.sh` locally? yes / no / not applicable

See [CHANGELOG](CHANGELOG.md) for details.
EOF
)"

停止——显示 PR URL，并等待 CI 检查通过。

11. 合并 PR

PR 上的 CI 通过后：

gh pr merge <pr-number> --merge

拉取已合并的 main：

git checkout main && git pull origin main

停止——确认合并成功。

12. 创建 GitHub Release

gh release create v<version> \
  --title "v<version>: <Short Title>" \
  --notes "$(cat <<'EOF'
## What's New

<User-friendly summary — focus on value, not technical details>

## Getting Started

\`\`\`bash
npx agentic-qe init --auto
\`\`\`

See [CHANGELOG](CHANGELOG.md) for full details.
EOF
)"

此操作会自动：

• 创建 git 标签 v<version>
• 触发 npm-publish.yml GitHub Actions 工作流

停止——显示 Release URL。

13. 监控发布工作流

# Watch the GitHub Actions workflow
gh run list --workflow=npm-publish.yml --limit 1
gh run watch <run-id>

该工作流会：

1. 检出代码并安装依赖
2. 运行 npm run typecheck
3. 运行 npm run build
4. 验证 dist/ 中存在 CLI 和 MCP 包
5. 运行 npm run test:ci（单元测试，不包括浏览器测试/端到端测试）
6. 验证软件包版本与 git 标签一致
7. 运行 npm publish --access public --provenance

等待工作流成功。如果失败，请根据日志诊断：

gh run view <run-id> --log-failed

停止——确认工作流成功。

14. 发布后验证

npm view agentic-qe@<version> name version

确认已发布的版本一致。在本地环境中测试安装：

npx agentic-qe@<version> --version

15. 隔离安装验证（关键）

此步骤可捕获仅在干净环境中才会出现的缺失/外部依赖问题（例如，全局安装时无法使用 typescript）。在宣布发布成功之前，必须通过此步骤。

# Create a completely isolated install — no access to project node_modules
CLEAN_DIR=$(mktemp -d)
npm install --prefix "$CLEAN_DIR" agentic-qe@<version> 2>&1 | tail -5

# Test CLI commands using ONLY the isolated install's dependencies
NODE_PATH="$CLEAN_DIR/node_modules" node "$CLEAN_DIR/node_modules/.bin/aqe" --version
NODE_PATH="$CLEAN_DIR/node_modules" node "$CLEAN_DIR/node_modules/.bin/aqe" --help 2>&1 | head -5

# Cleanup
rm -rf "$CLEAN_DIR"

如果 --version 崩溃（例如出现 ERR_MODULE_NOT_FOUND），说明发布版本存在依赖问题。请判断缺失的软件包应当：

• 打包进 CLI（添加到构建脚本中，并从外部依赖中移除）
• 添加到 package.json 的 dependencies 中（如果它是实际的运行时依赖）
• 延迟加载并使用 try/catch 包装（如果仅用于可选功能）

如果此步骤失败，请修复、重新构建并重新发布。切勿发布会在运行 --version 时崩溃的 CLI。

停止——确认隔离安装可正常工作。

规则

• 根目录下只有一个 package.json — 不存在 v3/ 子目录
• 不要硬编码版本字符串 — 始终从 package.json 读取
• 还要更新 .claude/skills/skills-manifest.json 中的 fleetVersion
• 始终运行真实测试，绝不运行模拟测试
• 通过 GitHub Actions 发布，而不是在本地发布（使用 --provenance 进行证明）
• 发布说明必须方便用户理解 — 重点说明价值，而非实现细节
• 如果在任何步骤发现意外情况，请先停止并说明，再继续
• 未经用户确认，绝不推送标签或创建发布
• 除非用户明确要求，否则不要运行端到端浏览器测试
• 创建 PR 前，必须通过所有验证（第 8 步）— 这能在问题进入 main 之前发现问题
• PR 正文必须包含 ### Required check (issue #401) 部分，并勾选 failure-modes 复选框 [x]。CI 通过 scripts/check-pr-body.cjs 强制执行此要求。完整模板请参阅 .github/PULL_REQUEST_TEMPLATE.md。
• 不要使用“I believe it's unlikely”或“can't see how this would fail”之类的淡化风险措辞，除非同一段中包含跟踪问题引用（#NNN）