chore(release): prepare v0.7.0

CHANGELOG-zh.md

@@ -2,6 +2,61 @@
 
 本项目的所有重要更改都将记录在此文件中。
 
+## [0.7.0] - 2026-10-16
+
+### 破坏性变更
+- 部分已有命令的失败结果会返回不同的 `Failure.Code`、`Failure.Kind` 或退出码。
+  依赖这些字段分支的脚本需要更新：
+  - `ClientError.NetworkError` 的 `Kind` 由 `error` 改为 `network`，并附带面向网络
+    连通性的提示和 `agr explain` 说明；退出码仍为 1。
+  - `agr instance mobile connect` 启动失败时，原来返回 `INTERNAL_ERROR`（退出码 1），
+    现在保留后台隧道的分类，例如 `PORT_IN_USE`（退出码 2）、`TUNNEL_AUTH_FAILED`
+    （退出码 4）、`TUNNEL_READY_TIMEOUT`、`TUNNEL_EXITED` 或云 API 错误码。
+  - `agr instance login` 在非交互模式下返回 `TTY_REQUIRED`，不再返回 `CLI_ERROR`；
+    退出码仍为 2。
+  - `agr pre-cache-image-task get` 未提供完整查询条件时返回
+    `MISSING_REQUIRED_INPUT`，不再返回 `INVALID_USAGE` 或 `MISSING_REQUIRED_FLAG`；
+    退出码仍为 2。
+- 未知命令配合 `--help -o json` 时返回 `INVALID_USAGE` 和退出码 2，与文本模式一致，
+  不再输出根命令帮助并以退出码 0 结束。需要列出命令时请使用
+  `agr --help -o json` 或 `agr schema -o json`。
+
+### 新功能
+- 新增 Registry 生命周期命令，覆盖 Registry、Record、版本、审批决策、远程预览与
+  同步、审计日志和 Skill 包传输 URL。
+- 新增 Session 命令，覆盖会话空间（`agr session space`）、会话以及事件追加与查询，
+  支持过滤、分页、结构化事件载荷和可读的文本输出。
+- 新增 Beta 版沙箱快照命令（`agr instance snapshot create`、`list` 和
+  `delete`）。`agr instance create` 现在可以通过 `--source-instance-id` 克隆已有
+  实例，或通过 `--snapshot-id` 将 ACTIVE 状态的纯磁盘快照恢复为新实例。
+- 为 `agr pre-cache-image-task get` 新增 `--pre-cache-image-id`，可替代镜像
+  digest、镜像和镜像仓库类型的组合查询。
+- `--debug` 和 `AGR_DEBUG=1` 现在还会把完整的脱敏调试日志保存到
+  `~/.agr/logs/`，并在退出时打印日志路径；`--debug-log <path>` 会开启调试并追加
+  写入指定文件。失败信息会保留原始错误原因，并替换已知的凭据值。
+- 失败结果新增可选的 `Failure.Details` 上下文，包括阶段、操作、路径、端点、HTTP
+  状态码和请求 ID 等，覆盖配置、文件、云 API、代理和移动端隧道错误。
+  `agr schema -o json` 现在会在 `GlobalFlags` 中列出全局 flag。
+
+### Bug 修复
+- 修复 `agr credential secret get` 和 `agr credential oauth2 acquire` 的 token
+  冲突：业务 WorkloadIdentityToken 改用 `--workload-identity-token`，全局
+  `--token` 统一用于云 API STS 认证；仍可通过 `TENCENTCLOUD_TOKEN` 或配置文件中的
+  `auth.token` 提供 STS token。
+- `agr instance file download` 无法完整写入 stdout 或本地文件时报告失败，不再
+  报告成功。
+- 配置文件解析错误会报告文件路径、行号和列号。
+- 修正 `agr schema` 和 `agr explain` 中 `deployment get` 与 `deployment list`
+  的 `RequiresAuth: true` 及认证失败码。
+- `deployment proxy` 和 `instance proxy` 的失败诊断默认只记录上游 origin，仅在
+  `--verbose` 时包含请求路径，避免默认记录携带凭据的请求路径。
+
+### 文档
+- 在 README 和 README-zh 中补充快照、恢复与克隆工作流、Session 工作流、Registry
+  命令和调试日志排障说明，并将安装示例更新到 v0.7.0。
+- 修正 `agr instance delete` 帮助，说明其 TTY 确认和 `--yes` 行为。
+- CONTRIBUTING 和 PATCH-VERIFICATION 中的 API patch 验证要求改为按变更影响确定。
+
 ## [0.7.0-preview.1] - 2026-09-18
 
 ### 破坏性变更

CHANGELOG.md

@@ -2,6 +2,71 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.7.0] - 2026-10-16
+
+### Breaking Changes
+- Some failures of existing commands now return a different `Failure.Code`,
+  `Failure.Kind`, or exit code. Update scripts that branch on these fields:
+  - `ClientError.NetworkError` now has `Kind=network` instead of `error`, with a
+    connectivity-oriented hint and an `agr explain` entry; the exit code stays 1.
+  - `agr instance mobile connect` startup failures that returned
+    `INTERNAL_ERROR` (exit 1) now keep the background tunnel's classification,
+    such as `PORT_IN_USE` (exit 2), `TUNNEL_AUTH_FAILED` (exit 4),
+    `TUNNEL_READY_TIMEOUT`, `TUNNEL_EXITED`, or the cloud API error code.
+  - `agr instance login` without interactive mode returns `TTY_REQUIRED`
+    instead of `CLI_ERROR`; the exit code stays 2.
+  - `agr pre-cache-image-task get` without a complete selector returns
+    `MISSING_REQUIRED_INPUT` instead of `INVALID_USAGE` or
+    `MISSING_REQUIRED_FLAG`; the exit code stays 2.
+- An unknown command with `--help -o json` now fails with `INVALID_USAGE` and
+  exit code 2, consistent with text mode, instead of printing root help with
+  exit code 0. Use `agr --help -o json` or `agr schema -o json` to list
+  commands.
+
+### Features
+- Add Registry lifecycle commands for registries, records, versions, approval
+  decisions, remote preview/sync, audit logs, and Skill package transfer URLs.
+- Add Session commands for session spaces (`agr session space`), sessions, and
+  event append/list, with filtering, pagination, structured event payloads,
+  and human-readable text output.
+- Add Beta sandbox snapshot commands (`agr instance snapshot create`, `list`,
+  and `delete`). `agr instance create` can now clone an existing instance with
+  `--source-instance-id` or restore an ACTIVE disk-only snapshot into a new
+  instance with `--snapshot-id`.
+- Add `--pre-cache-image-id` to `agr pre-cache-image-task get`, as an
+  alternative to the image digest, image, and registry type selector.
+- `--debug` and `AGR_DEBUG=1` now also save full redacted debug logs to
+  `~/.agr/logs/` and print the log path on exit; `--debug-log <path>` enables
+  debug and appends to a chosen file. Failures keep their original cause, with
+  known credential values redacted.
+- Failures now include optional `Failure.Details` context, such as the stage,
+  operation, path, endpoint, HTTP status, and request ID, for configuration,
+  file, cloud API, proxy, and mobile tunnel errors. `agr schema -o json` now
+  lists the global flags in `GlobalFlags`.
+
+### Bug Fixes
+- Fix token collisions in `agr credential secret get` and
+  `agr credential oauth2 acquire`: use `--workload-identity-token` for the
+  business WorkloadIdentityToken. The global `--token` flag now consistently
+  supplies the cloud STS token, alongside `TENCENTCLOUD_TOKEN` and `auth.token`.
+- Report a failure when `agr instance file download` cannot finish writing to
+  stdout or to the local file, instead of reporting success.
+- Report configuration file parse errors with the file path, line, and column.
+- Report `RequiresAuth: true` and the authentication failure codes for
+  `deployment get` and `deployment list` in `agr schema` and `agr explain`.
+- Limit `deployment proxy` and `instance proxy` failure diagnostics to the
+  upstream origin unless `--verbose` is set, so request paths that carry
+  credentials are not logged by default.
+
+### Docs
+- Add snapshot, restore, and clone workflows, the Session workflow, Registry
+  commands, and debug log troubleshooting to README and README-zh, and update
+  the installation examples to v0.7.0.
+- Correct `agr instance delete` help to describe its TTY confirmation and
+  `--yes` behavior.
+- Base API patch verification requirements in CONTRIBUTING and
+  PATCH-VERIFICATION on the impact of each change.
+
 ## [0.7.0-preview.1] - 2026-09-18
 
 ### Breaking Changes

README-zh.md

@@ -33,7 +33,7 @@ curl -fsSL https://dl.tencentags.com/agr-cli/latest/install.sh | INSTALL_DIR="$H
 安装指定版本：
 
 ```bash
-curl -fsSL https://dl.tencentags.com/agr-cli/latest/install.sh | VERSION=v0.6.2 sh
+curl -fsSL https://dl.tencentags.com/agr-cli/latest/install.sh | VERSION=v0.7.0 sh
 ```
 
 使用 GitHub Releases 作为备用下载源：
@@ -46,12 +46,12 @@ curl -fsSL https://github.com/TencentCloudAgentRuntime/ags-cli/releases/latest/d
 
 从 [GitHub Releases](https://github.com/TencentCloudAgentRuntime/ags-cli/releases) 下载最新版本并手动安装。
 
-将 `VERSION` 设置为目标版本号（如 `0.6.1`）：
+将 `VERSION` 设置为目标版本号（如 `0.7.0`）：
 
 **macOS（Apple Silicon）**
 
 ```bash
-VERSION=0.6.1
+VERSION=0.7.0
 curl -fLO https://github.com/TencentCloudAgentRuntime/ags-cli/releases/download/v${VERSION}/agr-${VERSION}-darwin-arm64.tar.gz
 tar xzf agr-${VERSION}-darwin-arm64.tar.gz
 sudo mv agr /usr/local/bin/agr
@@ -61,7 +61,7 @@ rm agr-${VERSION}-darwin-arm64.tar.gz
 **macOS（Intel）**
 
 ```bash
-VERSION=0.6.1
+VERSION=0.7.0
 curl -fLO https://github.com/TencentCloudAgentRuntime/ags-cli/releases/download/v${VERSION}/agr-${VERSION}-darwin-amd64.tar.gz
 tar xzf agr-${VERSION}-darwin-amd64.tar.gz
 sudo mv agr /usr/local/bin/agr
@@ -71,7 +71,7 @@ rm agr-${VERSION}-darwin-amd64.tar.gz
 **Linux（x86_64）**
 
 ```bash
-VERSION=0.6.1
+VERSION=0.7.0
 curl -fLO https://github.com/TencentCloudAgentRuntime/ags-cli/releases/download/v${VERSION}/agr-${VERSION}-linux-amd64.tar.gz
 tar xzf agr-${VERSION}-linux-amd64.tar.gz
 sudo mv agr /usr/local/bin/agr
@@ -81,7 +81,7 @@ rm agr-${VERSION}-linux-amd64.tar.gz
 **Linux（ARM64）**
 
 ```bash
-VERSION=0.6.1
+VERSION=0.7.0
 curl -fLO https://github.com/TencentCloudAgentRuntime/ags-cli/releases/download/v${VERSION}/agr-${VERSION}-linux-arm64.tar.gz
 tar xzf agr-${VERSION}-linux-arm64.tar.gz
 sudo mv agr /usr/local/bin/agr
@@ -91,7 +91,7 @@ rm agr-${VERSION}-linux-arm64.tar.gz
 **Windows（x86_64）— PowerShell**
 
 ```powershell
-$VERSION = "0.6.1"
+$VERSION = "0.7.0"
 Invoke-WebRequest -Uri "https://github.com/TencentCloudAgentRuntime/ags-cli/releases/download/v${VERSION}/agr-${VERSION}-windows-amd64.zip" -OutFile "agr-${VERSION}-windows-amd64.zip"
 Expand-Archive "agr-${VERSION}-windows-amd64.zip" -DestinationPath .
 Move-Item agr.exe "$env:USERPROFILE\bin\agr.exe"
@@ -103,7 +103,7 @@ Remove-Item "agr-${VERSION}-windows-amd64.zip"
 ### 校验下载文件
 
 ```bash
-VERSION=0.6.1
+VERSION=0.7.0
 curl -fLO https://github.com/TencentCloudAgentRuntime/ags-cli/releases/download/v${VERSION}/checksums.txt
 shasum -a 256 -c checksums.txt --ignore-missing
 ```

README.md

@@ -32,7 +32,7 @@ curl -fsSL https://dl.tencentags.com/agr-cli/latest/install.sh | INSTALL_DIR="$H
 To install a specific version:
 
 ```bash
-curl -fsSL https://dl.tencentags.com/agr-cli/latest/install.sh | VERSION=v0.6.2 sh
+curl -fsSL https://dl.tencentags.com/agr-cli/latest/install.sh | VERSION=v0.7.0 sh
 ```
 
 To use GitHub Releases as a fallback source:
@@ -45,12 +45,12 @@ curl -fsSL https://github.com/TencentCloudAgentRuntime/ags-cli/releases/latest/d
 
 Download the latest release from [GitHub Releases](https://github.com/TencentCloudAgentRuntime/ags-cli/releases) and install manually.
 
-Set `VERSION` to the release you want (e.g. `0.6.1`):
+Set `VERSION` to the release you want (e.g. `0.7.0`):
 
 **macOS (Apple Silicon)**
 
 ```bash
-VERSION=0.6.1
+VERSION=0.7.0
 curl -fLO https://github.com/TencentCloudAgentRuntime/ags-cli/releases/download/v${VERSION}/agr-${VERSION}-darwin-arm64.tar.gz
 tar xzf agr-${VERSION}-darwin-arm64.tar.gz
 sudo mv agr /usr/local/bin/agr
@@ -60,7 +60,7 @@ rm agr-${VERSION}-darwin-arm64.tar.gz
 **macOS (Intel)**
 
 ```bash
-VERSION=0.6.1
+VERSION=0.7.0
 curl -fLO https://github.com/TencentCloudAgentRuntime/ags-cli/releases/download/v${VERSION}/agr-${VERSION}-darwin-amd64.tar.gz
 tar xzf agr-${VERSION}-darwin-amd64.tar.gz
 sudo mv agr /usr/local/bin/agr
@@ -70,7 +70,7 @@ rm agr-${VERSION}-darwin-amd64.tar.gz
 **Linux (x86_64)**
 
 ```bash
-VERSION=0.6.1
+VERSION=0.7.0
 curl -fLO https://github.com/TencentCloudAgentRuntime/ags-cli/releases/download/v${VERSION}/agr-${VERSION}-linux-amd64.tar.gz
 tar xzf agr-${VERSION}-linux-amd64.tar.gz
 sudo mv agr /usr/local/bin/agr
@@ -80,7 +80,7 @@ rm agr-${VERSION}-linux-amd64.tar.gz
 **Linux (ARM64)**
 
 ```bash
-VERSION=0.6.1
+VERSION=0.7.0
 curl -fLO https://github.com/TencentCloudAgentRuntime/ags-cli/releases/download/v${VERSION}/agr-${VERSION}-linux-arm64.tar.gz
 tar xzf agr-${VERSION}-linux-arm64.tar.gz
 sudo mv agr /usr/local/bin/agr
@@ -90,7 +90,7 @@ rm agr-${VERSION}-linux-arm64.tar.gz
 **Windows (x86_64) — PowerShell**
 
 ```powershell
-$VERSION = "0.6.1"
+$VERSION = "0.7.0"
 Invoke-WebRequest -Uri "https://github.com/TencentCloudAgentRuntime/ags-cli/releases/download/v${VERSION}/agr-${VERSION}-windows-amd64.zip" -OutFile "agr-${VERSION}-windows-amd64.zip"
 Expand-Archive "agr-${VERSION}-windows-amd64.zip" -DestinationPath .
 Move-Item agr.exe "$env:USERPROFILE\bin\agr.exe"
@@ -102,7 +102,7 @@ Remove-Item "agr-${VERSION}-windows-amd64.zip"
 ### Verify checksums
 
 ```bash
-VERSION=0.6.1
+VERSION=0.7.0
 curl -fLO https://github.com/TencentCloudAgentRuntime/ags-cli/releases/download/v${VERSION}/checksums.txt
 shasum -a 256 -c checksums.txt --ignore-missing
 ```