release

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Release Workflow

发布工作流

Execute a safe, verified npm release for the

agentic-qe

monorepo. STOP after each phase for user confirmation.

为

agentic-qe

monorepo执行安全、经过验证的npm发布。每个阶段结束后暂停，等待用户确认。

Architecture

架构

This project has a dual-package structure — both must stay in sync:

File	Package Name	Role
`package.json` (root)	`agentic-qe`	Published to npm — the installable package
`v3/package.json`	`@agentic-qe/v3`	Actual implementation — CLI, MCP, domains

Root
```
prepublishOnly
```
hook runs
```
cd v3 && npm run build
```
```
npm publish
```
runs from the root directory

GitHub Actions triggers on

release: published

event via

.github/workflows/npm-publish.yml

本项目采用双包结构——两者必须保持同步：

文件	包名称	作用
`package.json` （根目录）	`agentic-qe`	发布至npm —— 可安装的包
`v3/package.json`	`@agentic-qe/v3`	实际实现 —— CLI、MCP、领域逻辑

根目录的
```
prepublishOnly
```
钩子会执行
```
cd v3 && npm run build
```
```
npm publish
```
从根目录执行

GitHub Actions通过

.github/workflows/npm-publish.yml

在

release: published

事件触发

Arguments

参数

```
<version>
```
— Target version (e.g.,
```
3.5.5
```
). If omitted, prompt the user.

```
<version>
```
—— 目标版本（例如：
```
3.5.5
```
）。如果省略，将提示用户输入。

Steps

步骤

1. Pre-Flight: Ensure Clean State

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

bash

git status
git branch --show-current

Verify working directory is clean and you know which branch you're on. If there are uncommitted changes, stop and ask the user. The release prep happens on the current working branch — we PR to main later.

STOP — confirm clean state and current branch.

bash

git status
git branch --show-current

验证工作目录是否干净，且你清楚当前所在分支。如果存在未提交的更改，暂停并询问用户。发布准备工作在当前工作分支进行——之后我们会向main分支提交PR。

暂停 —— 确认干净状态和当前分支。

2. Version Audit

2. 版本审计

Read the current version from

package.json

(source of truth). Then grep the ENTIRE codebase for hardcoded version strings — current version, old versions, and any version-like patterns. Check both package.json files are in sync.

bash

undefined

从

package.json

读取当前版本（权威来源）。然后在整个代码库中搜索硬编码的版本字符串——当前版本、旧版本以及任何类似版本的模式。检查两个package.json文件是否同步。

bash

undefined

Read current version

读取当前版本

node -p "require('./package.json').version" node -p "require('./v3/package.json').version"

Search for version strings in source files

在源码文件中搜索版本字符串

grep -rn --include=".ts" --include=".js" --include="*.json" '"3.[0-9]+.[0-9]+"' .
--exclude-dir=node_modules --exclude-dir=dist --exclude-dir=.git


If any stale version strings are found, fix them ALL before continuing. Both `package.json` and `v3/package.json` must match.

**STOP — show findings and wait for user confirmation.**

grep -rn --include=".ts" --include=".js" --include="*.json" '"3.[0-9]+.[0-9]+"' .
--exclude-dir=node_modules --exclude-dir=dist --exclude-dir=.git


如果发现任何过时的版本字符串，在继续前全部修复。根目录和v3目录的`package.json`版本必须一致。

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

3. Bump Version

3. 版本升级

Update both package.json files to the target version:

bash

undefined

将两个package.json文件更新为目标版本：

bash

undefined

Bump v3 first (no git tag — we tag manually)

先升级v3版本（不生成git标签——我们手动打标签）

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

Bump root to match

升级根目录版本以保持一致

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


Verify both match:
```bash
grep '"version"' package.json v3/package.json

STOP — confirm versions match.

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


验证两者版本一致：
```bash
grep '"version"' package.json v3/package.json

暂停 —— 确认版本一致。

4. Update CHANGELOG

4. 更新CHANGELOG

Add a new section to

v3/CHANGELOG.md

following Keep a Changelog format:

markdown

undefined

按照Keep a Changelog格式在

v3/CHANGELOG.md

中添加新章节：

markdown

undefined

[<version>] - YYYY-MM-DD

Added

新增

Fixed

修复

Changed

变更


Write user-friendly descriptions focused on value, not implementation details.

**STOP — show changelog entry for review.**


撰写用户友好的描述，聚焦价值而非实现细节。

**暂停 —— 展示更新后的CHANGELOG条目供审核。**

4b. Update Release Docs

4b. 更新发布文档

Create a release notes file at

docs/releases/v<version>.md

following the existing format:

markdown

undefined

按照现有格式在

docs/releases/v<version>.md

创建发布说明文件：

markdown

undefined

v<version> Release Notes

v<version> 发布说明

Release Date: YYYY-MM-DD

发布日期： YYYY-MM-DD

Highlights

亮点

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

<1-2句话总结最重要的变更>

Added

新增

Fixed

修复

Changed

变更


Then update `docs/releases/README.md` — add a new row at the TOP of the table:

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

Use existing entries as formatting reference. Keep highlights concise (under 80 chars).


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

```markdown
| [v<version>](v<version>.md) | YYYY-MM-DD | <简短亮点> |

参考现有条目的格式。亮点需简洁（不超过80字符）。

5. Build

5. 构建

bash

npm run build

This runs

cd v3 && npm run build

which executes

tsc && build:cli && build:mcp

. Verify zero errors. If build fails, diagnose and fix.

STOP — show build output.

bash

npm run build

该命令会执行

cd v3 && npm run build

，进而执行

tsc && build:cli && build:mcp

。验证无错误。如果构建失败，诊断并修复问题。

暂停 —— 展示构建输出。

6. Type Check

6. 类型检查

bash

npm run typecheck

This runs

cd v3 && tsc --noEmit

. Must produce zero errors.

STOP — show type check output.

bash

npm run typecheck

该命令会执行

cd v3 && tsc --noEmit

。必须无错误。

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

7. Unit Tests

7. 单元测试

bash

cd /workspaces/agentic-qe-new/v3 && npx vitest run tests/unit/

Run REAL tests against the actual codebase. Do NOT simulate, mock, or skip any tests. ALL unit tests must pass.

STOP — show test results.

bash

cd /workspaces/agentic-qe-new/v3 && npx vitest run tests/unit/

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

暂停 —— 展示测试结果。

8. Artifact & Integration Verification

8. 产物与集成验证

This is the critical pre-release gate. Verify the built package works end-to-end as a user would experience it.

这是发布前的关键关卡。验证构建后的包能否像用户实际使用那样端到端正常工作。

8a. Verify Build Artifacts

8a. 验证构建产物

bash

undefined

bash

undefined

Verify v3/dist/ exists with expected bundles

验证v3/dist/目录存在预期的打包文件

ls -la v3/dist/cli/bundle.js ls -la v3/dist/index.js ls -la v3/dist/mcp/

All three must exist: CLI bundle, main entry point, MCP server.

ls -la v3/dist/cli/bundle.js ls -la v3/dist/index.js ls -la v3/dist/mcp/

必须存在以下三个文件：CLI打包文件、主入口文件、MCP服务器文件。

8b. Test

aqe init --auto

in a Fresh Project

8b. 在新项目中测试

aqe init --auto

bash

undefined

bash

undefined

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-new/v3/dist/cli/bundle.js init --auto

Verify init completes without errors and creates the expected project structure (`.agentic-qe/` directory, config files).

node /workspaces/agentic-qe-new/v3/dist/cli/bundle.js init --auto

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

8c. Verify CLI

8c. 验证CLI

bash

undefined

bash

undefined

Version output

版本输出

node /workspaces/agentic-qe-new/v3/dist/cli/bundle.js --version

System status

系统状态

node /workspaces/agentic-qe-new/v3/dist/cli/bundle.js status

Both must succeed without errors.

node /workspaces/agentic-qe-new/v3/dist/cli/bundle.js status

两者必须无错误执行成功。

8d. Verify Self-Learning & Fleet Capabilities

8d. 验证自学习与集群能力

bash

cd /tmp/aqe-release-test

bash

cd /tmp/aqe-release-test

Verify learning subsystem

验证学习子系统

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

Verify agent listing works

验证Agent列表功能

node /workspaces/agentic-qe-new/v3/dist/cli/bundle.js agent list 2>&1 | head -10

Verify health check

验证健康检查

node /workspaces/agentic-qe-new/v3/dist/cli/bundle.js health 2>&1 | head -10

These should respond (even if empty results) without errors, confirming the subsystems initialize properly.

node /workspaces/agentic-qe-new/v3/dist/cli/bundle.js health 2>&1 | head -10

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

8f. Cleanup

8f. 清理

bash

rm -rf /tmp/aqe-release-test

STOP — show all verification results. Every check must pass before continuing.

bash

rm -rf /tmp/aqe-release-test

暂停 —— 展示所有验证结果。所有检查必须通过才能继续。

9. Local CI Test Suite

9. 本地CI测试套件

Run the same tests that CI runs on PRs and during publish. Skip e2e browser tests unless the user explicitly requests them.

bash

cd /workspaces/agentic-qe-new/v3

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

bash

cd /workspaces/agentic-qe-new/v3

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)

完整test:ci套件（来自npm-publish.yml —— 排除浏览器/端到端测试）

npm run test:ci


Available test scripts: `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`.

All mandatory test suites must pass. Pre-existing MCP handler test failures (tests that need runtime initialization) are acceptable if they also fail on the main branch.

**STOP — show all test results.**

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. Commit & Create PR to Main

10. 提交并创建向Main分支的PR

bash

cd /workspaces/agentic-qe-new

bash

cd /workspaces/agentic-qe-new

Stage version bump + changelog + release docs

暂存版本升级+CHANGELOG+发布文档

git add package.json v3/package.json v3/CHANGELOG.md docs/releases/README.md docs/releases/v<version>.md

Also stage any files that were fixed during version audit

同时暂存版本审计中修复的所有文件

git status

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

git status

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

Create PR to main

创建向main分支的PR

gh pr create
--base main
--title "chore(release): v<version>"
--body "$(cat <<'EOF'

Release v<version>

发布v<version>

Verification Checklist

验证清单

Both package.json versions match
Build succeeds (tsc + CLI + MCP bundles)
Type check passes
All unit tests pass
```
aqe init --auto
```
works in fresh project
CLI commands functional
MCP tools load correctly
Self-learning subsystem initializes
Journey tests pass
Code Intelligence tests pass
Performance gates pass
Full test:ci suite passes

See CHANGELOG for details. EOF )"


**STOP — show PR URL and wait for CI checks to pass.**

两个package.json版本一致
构建成功（tsc + CLI + MCP打包）
类型检查通过
所有单元测试通过
```
aqe init --auto
```
在新项目中正常工作
CLI命令功能正常
MCP工具加载正常
自学习子系统初始化正常
流程测试通过
代码智能测试通过
性能关卡通过
完整test:ci套件通过

详情请见CHANGELOG。 EOF )"


**暂停 —— 展示PR URL并等待CI检查通过。**

11. Merge PR

11. 合并PR

Once CI passes on the PR:

bash

gh pr merge <pr-number> --merge

Pull the merged main:

bash

git checkout main && git pull origin main

STOP — confirm merge successful.

PR上的CI检查通过后：

bash

gh pr merge <pr-number> --merge

拉取合并后的main分支：

bash

git checkout main && git pull origin main

暂停 —— 确认合并成功。

12. Create GitHub Release

12. 创建GitHub Release

bash

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

bash

gh release create v<version> \
  --title "v<version>: <简短标题>" \
  --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 for full details. EOF )"


This automatically:
- Creates a git tag `v<version>`
- Triggers the `npm-publish.yml` GitHub Actions workflow

**STOP — show release URL.**

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

完整详情请见CHANGELOG。 EOF )"


这会自动：
- 创建git标签`v<version>`
- 触发`npm-publish.yml` GitHub Actions工作流

**暂停 —— 展示Release URL。**

13. Monitor Publish Workflow

13. 监控发布工作流

bash

undefined

bash

undefined

Watch the GitHub Actions workflow

查看GitHub Actions工作流

gh run list --workflow=npm-publish.yml --limit 1 gh run watch <run-id>


The workflow:
1. Checks out code, installs deps
2. Runs `npm run typecheck`
3. Runs `npm run build`
4. Verifies `v3/dist/` exists with CLI and MCP bundles
5. Runs `npm run test:ci` (unit tests, excludes browser/e2e)
6. Verifies package version matches git tag
7. Runs `npm publish --access public --provenance`

Wait for the workflow to succeed. If it fails, diagnose from the logs:
```bash
gh run view <run-id> --log-failed

STOP — confirm workflow succeeded.

gh run list --workflow=npm-publish.yml --limit 1 gh run watch <run-id>


该工作流包含以下步骤：
1. 拉取代码、安装依赖
2. 执行`npm run typecheck`
3. 执行`npm run build`
4. 验证`v3/dist/`目录存在CLI和MCP打包文件
5. 执行`npm run test:ci`（单元测试，排除浏览器/端到端测试）
6. 验证包版本与git标签匹配
7. 执行`npm publish --access public --provenance`

等待工作流执行成功。如果失败，从日志诊断问题：
```bash
gh run view <run-id> --log-failed

暂停 —— 确认工作流执行成功。

14. Post-Publish Verification

14. 发布后验证

bash

npm view agentic-qe@<version> name version

Confirm the published version matches. Test install:

bash

npx agentic-qe@<version> --version

bash

npm view agentic-qe@<version> name version

确认发布的版本匹配。测试安装：

bash

npx agentic-qe@<version> --version

Rules

规则

Both package.json files must match — root and v3
Never hardcode version strings — always read from package.json
Always run REAL tests, never simulated
Publish happens via GitHub Actions, not locally (uses
```
--provenance
```
for attestation)
Release notes must be user-friendly — focus on value, not implementation internals
If anything unexpected is found at any step, stop and explain before proceeding
Never push tags or create releases without user confirmation
The
```
prepublishOnly
```
hook must
```
cd v3
```
before building — this is handled by root package.json
No e2e browser tests unless user explicitly requests them
All verification (step 8) must pass before creating the PR — this catches issues before they reach main

两个package.json文件版本必须一致 —— 根目录和v3目录
切勿硬编码版本字符串 —— 始终从package.json读取
始终运行真实测试，切勿模拟
通过GitHub Actions发布，而非本地发布（使用
```
--provenance
```
进行溯源认证）
发布说明必须用户友好 —— 聚焦价值而非实现细节
如果在任何步骤发现意外情况，暂停并说明后再继续
未经用户确认，切勿推送标签或创建Release
```
prepublishOnly
```
钩子必须在构建前
```
cd v3
```
—— 这由根目录的package.json处理
除非用户明确要求，否则不运行端到端浏览器测试
所有验证（步骤8）必须通过后才能创建PR —— 这会在问题进入main分支前发现它们

release

Original

Translation

Release Workflow

发布工作流

Architecture

架构

Arguments

参数

Steps

步骤

1. Pre-Flight: Ensure Clean State

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

2. Version Audit

2. 版本审计

Read current version

读取当前版本

Search for version strings in source files

在源码文件中搜索版本字符串

3. Bump Version

3. 版本升级

Bump v3 first (no git tag — we tag manually)

先升级v3版本（不生成git标签——我们手动打标签）

Bump root to match

升级根目录版本以保持一致

4. Update CHANGELOG

4. 更新CHANGELOG

[<version>] - YYYY-MM-DD

[<version>] - YYYY-MM-DD

Added

新增

Fixed

修复

Changed

变更

4b. Update Release Docs

4b. 更新发布文档

v<version> Release Notes

v<version> 发布说明

Highlights

亮点

Added

新增

Fixed

修复

Changed

变更

5. Build

5. 构建

6. Type Check

6. 类型检查

7. Unit Tests

7. 单元测试

8. Artifact & Integration Verification

8. 产物与集成验证

8a. Verify Build Artifacts

8a. 验证构建产物

Verify v3/dist/ exists with expected bundles

验证v3/dist/目录存在预期的打包文件

8b. Test aqe init --auto in a Fresh Project

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

Create a temporary test project

创建临时测试项目

Run init using the LOCAL build (not published version)

使用本地构建版本（而非已发布版本）执行初始化

8c. Verify CLI

8c. 验证CLI

Version output

版本输出

System status

系统状态

8d. Verify Self-Learning & Fleet Capabilities

8d. 验证自学习与集群能力

Verify learning subsystem

验证学习子系统

Verify agent listing works

验证Agent列表功能

Verify health check

验证健康检查

8f. Cleanup

8b. Test
`aqe init --auto`
in a Fresh Project

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