@tea-agent/loop-agent 0.37.0 → 0.38.0

package/AGENTS.md

@@ -40,6 +40,7 @@
 6. 后端/接口/pytest → `taskKind: "backend-test"`（不是 `--profile`）；知识回写 `knowledge-sync`；图谱开荒 `knowledge-graph-bootstrap`。`--profile` 仅 `auto|minimal|standard|reviewed|supervised`。
 7. 看板/observe → `agent-worker console`（默认 repo=当前目录、port=8790；listen 成功后默认打开系统浏览器，`--no-open` 禁止）（`/inspect/` 只读）；`observe serve` 已下线（`OBSERVE_SERVE_REMOVED` + exit 2）；`observe snapshot` 仍可用。
 8. 分支合并 → 先读 `docs/operations/branch-merge-guideline.md`。
+9. 涉及版本发布、npm 渠道、release 分支、GitHub Actions 发布链或 dist-tag → 先读 `docs/operations/version-and-release-management.md`。
 
 ## 会话协议
 
@@ -62,6 +63,7 @@ DAG 执行期间，主 agent 不得修改 writeSet 外的任何工作区文件
 - `skills/`：源仓库/npm 内置 skills；目标项目只生成 `.agents/skills/`
 - `.harness/`：运行态（tasks/dag-runs/runs 等；init 会 gitignore 运行事实，保留 prompts 与占位）
 - `docs/`：治理；`website/`：用户文档站；`scripts/`：检查与 CI
+- 版本发布链（next / release-x.y / latest 手工 promote）：`docs/operations/version-and-release-management.md`
 
 ## 工作规则（增量约束）
 

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## [Unreleased]
 
+### 新增
+
+- 版本发布改为三渠道：main 自动发布 npm `next`（`x.y.0-next.N`）、release 分支自动发布正式 patch 到 `release-x.y`、`latest` 仅由人工 GitHub Actions promotion 移动（支持 dry-run 与 CAS 校验）
+- 新增 `next-release.yml` / `cut-release-line.yml` / `release-line-publish.yml` / `promote-npm-latest.yml`，删除旧每日自动 latest 发布入口
+- 发布策略改为 branch + version + channel 矩阵（`scripts/release-channel-policy.mjs`），fail closed
+- 双周 Release Train：可从选定 next 的精确 source SHA 创建版本化 release 分支，带幂等恢复与单 tarball SHA-256 绑定
+
 ## [0.37.0] - 2026-08-16
 
 ### 新增

package/README.md

@@ -29,6 +29,18 @@ npm install -g @tea-agent/loop-agent@latest
 loop-agent --version
 ```
 
+渠道说明（普通用户默认 `latest`；开发/测试用 `next`；固定某条版本线用
+`release-x.y`；正式 dogfood 用精确版本）：
+
+```bash
+npm install -g @tea-agent/loop-agent                 # 推荐稳定版本
+npm install -g @tea-agent/loop-agent@next            # main 高频开发构建
+npm install -g @tea-agent/loop-agent@release-0.37    # 0.37 版本线最新 patch
+npm install -g @tea-agent/loop-agent@0.37.5          # 精确、可复现
+```
+
+完整发布治理见 `docs/operations/version-and-release-management.md`。
+
 ### 初始化当前项目
 
 ```bash

package/dist/build-stamp.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "version": "0.37.0",
-  "gitSha": "7b2fcb1072e85a7dbe0d92311d4b457cc34e7735",
-  "builtAt": "2026-08-16T20:27:37.113Z"
+  "version": "0.38.0",
+  "gitSha": "cc01c2ec09b56080f4c32416bddcc911feaa0e7a",
+  "builtAt": "2026-08-17T01:42:05.218Z"
 }

package/docs/README.md

@@ -34,6 +34,8 @@
 | 分阶段推进 agent-worker Production Readiness v1 | `exec-plans/active/2026-08-09-agent-worker-production-readiness-v1-program.md`、`exec-plans/active/README.md` |
 | 合并分支并留下 source-SHA 报告 | `operations/branch-merge-guideline.md` |
 | 使用仓库内 GitHub 协作方式 | `operations/github-collaboration.md` |
+| 发布版本、npm 渠道、release 分支或手工 latest promotion | `operations/version-and-release-management.md` |
+| 版本发布、npm 渠道、release 分支与 latest promote | `operations/version-and-release-management.md` |
 | 排查本机开发环境问题 | `operations/local-development-environment.md` |
 | 使用明确的 Cursor one-shot sidecar | `runtime/cursor-prompt-sidecar.md` |
 | 审查 npm 包与目标项目初始化文件面 | `init-surface.manifest.json` |

package/docs/operations/README.md

@@ -6,7 +6,8 @@
 
 - [`local-development-environment.md`](local-development-environment.md)：本地环境、Windows 差异和常见排障。
 - [`branch-merge-guideline.md`](branch-merge-guideline.md)：按风险选择合并模式并留下 source-SHA 证据。
-- [`github-collaboration.md`](github-collaboration.md)：仓库内 GitHub 协作约定及自动/人工发布通道。
+- [`github-collaboration.md`](github-collaboration.md)：仓库内 GitHub 协作约定及发布通道。
+- [`version-and-release-management.md`](version-and-release-management.md)：版本发布管理——next / release-x.y / latest 渠道、workflow 与 promote 手册。
 - [`production-readiness.md`](production-readiness.md)：交付前的生产就绪判断。
 - [`agent-worker-production-readiness.md`](agent-worker-production-readiness.md)：agent-worker Feature/Task Pool 外层编排的 Production Readiness v1 操作合同。
 - [`backend-test-jacoco-coverage.md`](backend-test-jacoco-coverage.md)：Java 被测服务挂载 JaCoCo tcpserver agent 的 Maven、`java -jar` 与 Docker 操作手册。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tea-agent/loop-agent",
-  "version": "0.37.0",
+  "version": "0.38.0",
   "type": "module",
   "bin": {
     "loop-agent": "bin/loop-agent.js",

package/skills/loop-agent/references/command-reference.md

@@ -12,7 +12,7 @@
 loop-agent <command> ...
 ```
 
-面向自举迭代和日常使用时，全局 CLI 应来自 npm 上已发布的安装包。首次安装或有意升级使用 `@latest`：
+面向自举迭代和日常使用时，全局 CLI 应来自 npm 上已发布的安装包。首次安装或有意升级使用 `@latest`（当前推荐稳定版；`@next` 仅用于测试 main 构建；`release-0.x` 固定某条版本线；正式 dogfood 用精确版本）：
 
 ```bash
 npm install -g @tea-agent/loop-agent@latest
@@ -21,6 +21,8 @@ loop-agent --version
 loop-agent doctor
 ```
 
+发布渠道（当前真源：`docs/operations/version-and-release-management.md`）：`latest` 是人工确认后的推荐稳定版本；`@next` 是 main 高频开发构建（仅测试）；`@release-0.37` 是 0.37 版本线最新自动发布版本；正式 dogfood / 自举任务应安装精确版本（如 `@tea-agent/loop-agent@0.37.5`）而非浮动 tag。
+
 一次自举任务启动后不要中途升级控制器；记录 `npm list -g` 显示的实际版本。不要在 DAG 节点中反复用 `npx @latest` 拉取，也不要使用当前工作区的 `npm link` 或 `npm run dev` 作为控制器去修改 loop-agent 本仓库的 CLI、DAG runtime、executor、package metadata 或 build output。`npm run dev -- <command> ...` 只用于源码调试和聚焦 CLI 开发。
 
 发布包入口加载 `dist/cli.js`；开发入口加载 `src/cli.ts`。

package/skills/loop-agent/references/harness-policy.md

@@ -72,7 +72,7 @@ loop-agent task status <task-id> --json [--repo-root <target-repo>]
 
 The `--verify` command should reference verification commands registered in the project's `AGENTS.md` or its governance verification-matrix.md; do not assume `npm run typecheck` exists. `--verify` is optional; when omitted, suggestions are auto-derived from `package.json` scripts or existing managed `task.json.verifyCommands`.
 
-`loop-agent` is the preferred global CLI. For self-hosting loop-agent development, the controller must be an installed npm-published package. Use `npm install -g @tea-agent/loop-agent@latest` for first install or intentional upgrades, then treat the installed version as frozen for the current task and record `npm list -g @tea-agent/loop-agent --depth=0`. Do not repeatedly fetch `npx @latest` inside DAG nodes, and do not use the current working tree's `npm link` or `npm run dev` to control tasks that may edit CLI, DAG runtime, executors, package metadata, or build output. Use `npm run dev -- <args>` only for source debugging and focused CLI development.
+`loop-agent` is the preferred global CLI. For self-hosting loop-agent development, the controller must be an installed npm-published package. Use `npm install -g @tea-agent/loop-agent@latest` for first install or intentional upgrades (`@next` is the main dev channel for testing only; `release-0.x` pins a version line), then treat the installed version as frozen for the current task and record `npm list -g @tea-agent/loop-agent --depth=0`. Do not repeatedly fetch `npx @latest` inside DAG nodes, and do not use the current working tree's `npm link` or `npm run dev` to control tasks that may edit CLI, DAG runtime, executors, package metadata, or build output. Use `npm run dev -- <args>` only for source debugging and focused CLI development.
 
 The npm package carries static capability assets: `skills/` (bundled in-package, containing `loop-agent` and `agent-worker`; `loop-agent init` mirrors them into the target project's `.agents/skills/`), `docs/templates/`, `docs/architecture/`, `docs/skills/`, `examples/`, `harness.json`, `AGENTS.md`, `README.md`, and `CHANGELOG.md`. `loop-agent init` creates `ai_workspace/loop-agent/` (the default governanceRoot) in the target project with `progress/`, `reports/`, `exec-plans/`, and `decisions/` directories plus their README files; the actual files under those directories belong to the target repository and are not shipped by the npm package.
 

package/skills/loop-agent/references/task-workflow.md

@@ -18,7 +18,7 @@ loop-agent task status <task-id> --json
 
 默认 DAG 草稿仍为 `.harness/tasks/<task-id>/dag.json`。repo-relative 示例用 `/`；Windows 由 Node 解析本地路径。何时必须 PRD / `plan create`：见 `source-and-plan-practice.md`。
 
-当目标仓库是 loop-agent 本仓库时，`loop-agent` 命令必须来自 npm 上已发布的安装包。首次安装或有意升级可用 `@tea-agent/loop-agent@latest`，但一次自举任务启动后不要中途升级控制器，并记录 `npm list -g @tea-agent/loop-agent --depth=0` 显示的实际版本。不要用当前工作区的 `npm link` 或 `npm run dev` 控制会改动 CLI、DAG runtime、executor、package metadata 或 build output 的任务；源码开发和 focused debugging 才使用 `npm run dev -- <args>`。
+当目标仓库是 loop-agent 本仓库时，`loop-agent` 命令必须来自 npm 上已发布的安装包。首次安装或有意升级可用 `@tea-agent/loop-agent@latest`（当前推荐稳定版；`@next` 仅用于尝鲜/测试 main 构建，`release-0.x` 固定某条版本线），但一次自举任务启动后不要中途升级控制器，并记录 `npm list -g @tea-agent/loop-agent --depth=0` 显示的实际版本。不要用当前工作区的 `npm link` 或 `npm run dev` 控制会改动 CLI、DAG runtime、executor、package metadata 或 build output 的任务；源码开发和 focused debugging 才使用 `npm run dev -- <args>`。
 
 主会话默认是 **Compatibility / Operator Assist**：实现工作必须走上方 DAG CLI。低风险的文档/index/task-source 元数据修正仅作 operator 维护，须记录 scope、跑验证，且**不得**扩展为业务实现或 CLI 失败后的救火写码；见 `orchestrator-and-interventions.md`。