volcengine · shushushv · Sep 8, 2026 · Aug 14, 2026 · Aug 17, 2026 · Sep 8, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,6 +7,32 @@
 
 ## 未发布
 
+## 0.0.7
+
+_发布日期：2026-09-08_
+
+### 新增
+
+- `docs fetch` 新增 `--match` 参数，支持重复指定，按关键词提取 Markdown 章节或表格，并返回原文身份元数据、匹配情况和截断状态。
+- InteractAI Skill 支持生成、修改和校验 VoiceChat/Aibot 配置，配置模型、验证流程和输出格式分别放入独立参考文档。
+
+### 修复
+
+- 将 Go 工具链升级至 1.25.13，修复标准库 HTTP、TLS、URL 和 ASN.1 处理中的安全问题。
+- flag 解析或通用位置参数校验失败时，返回当前命令的用法；`docs search/fetch/list` 的参数错误补充位置参数要求和示例。
+- 兼容 RTC 文档 MCP 的 `fetch_doc`、`list_docs` 分页参数及 `list_docs` 过滤参数 schema，校验完整文档标记并移除协议尾部元数据。
+- Skill 命令校验识别 `--` 参数终止符，支持其后的负数错误码参数。
+
+### 改进
+
+- 文档检索优先通过精确专题标题执行 `docs list → fetch --match`，未唯一命中时回退 `docs search → fetch`。
+- Voice Agent 配置以 StartVoiceChat 核心模型为准，可转换为 AibotCreate 配置或 AibotUpdate JSON Merge Patch。
+- 字段范围、枚举和 Provider 兼容性依据当前官方正文或服务端结果验证；证据不足或冲突时返回 `valid=null`，保留候选预览，可执行配置为空。
+- 集成诊断支持快速判断和完整阶段排查，并说明 VoiceChat 事件和客户端音频证据能确认哪些阶段。
+- 调整 CLI 和 Skill 更新提示：用户询问 Runtime、安装或更新时展示，产品咨询、配置和诊断时忽略。
+- 为每次 CLI 调用生成 invocation ID，并写入 User-Agent。
+- 调整 AI 调用方的识别优先级和环境变量匹配范围，修改 User-Agent 超长时的裁剪规则，并支持版本构建元数据。
+
 ## 0.0.6
 
 _发布日期：2026-08-13_

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,5 +1,98 @@
+<a id="zh-cn"></a>
+
+# 为 vertc 贡献代码
+
+[English](#english) | 简体中文
+
+本文说明常见贡献流程。架构和强制规则写在 [AGENTS.md](./AGENTS.md) 中，开始前请先阅读。
+
+## 准备开发环境
+
+```bash
+make tools     # 安装固定版本的 golangci-lint 和 Gitleaks，只需执行一次
+make ci        # 运行完整本地检查，包括公开接口和开源发布检查
+```
+
+从 `main` 创建分支，一次改动只处理一项能力。提交 Pull Request 前确保 `make ci` 通过。格式和 import 可以用 `make fmt` 自动修复。
+
+`make check-change-contract` 会将当前分支与 merge base 对比，检查稳定 CLI 接口是否连同验证一起更新：命令变更需要命令测试或 E2E 测试，错误码变更需要更新 snapshot，模板源变更需要模板测试。在 CI 中，它使用 MR diff base 或 push base；本地运行时使用 `origin/HEAD`。
+
+### Go 单元测试覆盖率
+
+在仓库根目录运行标准覆盖率流程：
+
+```bash
+make coverage        # 生成 coverage.out 和 coverage.html，并输出总覆盖率
+make check-coverage  # 重新生成报告并检查覆盖率下限
+```
+
+覆盖率统计使用不带缓存的 atomic statement profile，范围是 `cmd/` 和 `internal/` 下的生产包及同目录测试。`tests/` 下的子进程 E2E 测试是单独的功能门禁，因为子 CLI 进程中的执行不会进入普通 Go 单元测试 profile。
+
+CI 通过同一个 Make target 检查 70.0% 的总覆盖率，不会给每个包套用同一个阈值。命令入口、平台适配和纯逻辑代码的可测试性不同。新增测试应覆盖可观察的成功、失败、边界、dry-run 或回滚行为，不要只为提高数字而执行代码行。
+
+需要调整本地报告路径或阈值时，可以使用 `COVERAGE_PROFILE`、`COVERAGE_HTML` 和 `COVERAGE_THRESHOLD`。
+
+## 常见改动
+
+### 新增或修改命令
+
+1. 添加 `cmd/<name>.go`，并在 `cmd/root.go` 中注册。
+2. 通过 `output.Writer.Data` 输出结果，保持 **stdout 只写数据**；进度和提示通过 `Progress`/`Warn` 写入 stderr。
+3. 添加 `affordance.Affordance`，写清 when / avoid / prereq / examples。它会显示在 `--help` 中，也会被 Skills 使用。
+4. 有副作用的命令必须支持 `--dry-run`，且该模式下不能写入任何内容。
+5. 添加单元测试；新增公开命令面时，还要在 `tests/` 中补 E2E 用例。
+
+### 新增或修改 `error.code`
+
+1. 在 `internal/errs/catalog.go` 的 `errs.Catalog` 中登记，并写一行摘要。
+2. 通过 `errs.New(...)` 或 `errs.Wrap(...)` 返回，格式为 `vertc.<domain>.<subtype>`。
+3. 重新生成 snapshot：
+
+   ```bash
+   UPDATE_SNAPSHOT=1 go test ./internal/errs/ -run TestCatalogSnapshot
+   ```
+
+4. 删除或重命名错误码属于破坏性契约变更，需要维护者审查、`CHANGELOG.md` 记录和 MAJOR 版本升级。
+
+### 添加 `scene × platform` 模板
+
+1. 将源文件以 `*.tmpl` 形式放在 `internal/template/files/<scene>/<platform>/`。
+2. 在 `internal/template/registry.go` 中注册，设置 `Available: true`，并固定 SDK 版本。
+3. 提供 `vertc.taskfile.yaml.tmpl`，包含 `post_create`、`install` 和 `dev`。
+4. 添加 render 测试，检查文件树和核心链路标记，参考 `render_test.go`。
+5. 填好配置和 Token 后，生成项目必须能通过 `vertc doctor`。
+
+添加模板不需要修改 `cmd/` 或 `internal/errs/`。
+
+### 添加场景 Skill
+
+1. 将 `skill-template/skill-template.md` 复制到 `skills/byted-<product-code>-<skill-name>/SKILL.md`。
+2. Skill 应写成接入流程：识别场景、安排命令顺序、处理失败；不要写成 flag 手册。
+
+## 稳定契约
+
+`error.code`、stdout JSON 信封、退出码语义和 affordance 字段是 Agent 和 Skill 依赖的公开契约。不要随意修改。相关变更属于 MAJOR 版本升级，需要维护者确认，详见 [CHANGELOG.md](./CHANGELOG.md)。
+
+## 安全要求
+
+不要提交凭据、私有端点、本地文件路径或其他环境相关数据。密钥使用文档规定的环境变量。
+
+## Pull Request 检查清单
+
+- [ ] 一次改动只处理一项能力
+- [ ] `make ci` 通过
+- [ ] 已新增或更新测试
+- [ ] 命令面变化时已更新 `README.md`
+- [ ] 已在 `CHANGELOG.md` 的 `Unreleased` 下记录变更
+
+---
+
+<a id="english"></a>
+
 # Contributing to vertc
 
+[简体中文](#zh-cn) | English
+
 Thanks for helping build vertc. This is the *how-to* for common contributions;
 the architecture and hard rules live in [AGENTS.md](./AGENTS.md) — read it first.
 
@@ -67,14 +160,14 @@ when needed with `COVERAGE_PROFILE`, `COVERAGE_HTML`, and
 1. Add sources under `internal/template/files/<scene>/<platform>/` as `*.tmpl`.
 2. Register it in `internal/template/registry.go` (`Available: true`, pin the SDK).
 3. Include a `vertc.taskfile.yaml.tmpl` with `post_create` / `install` / `dev`.
-4. Add a render test asserting the file tree + core链路 markers (see `render_test.go`).
+4. Add a render test asserting the file tree and core workflow markers (see `render_test.go`).
 5. A generated project must pass `vertc doctor` once config + token are filled.
 
 You do not need to touch `cmd/` or `internal/errs/` to add a template.
 
 ### Add a scene skill (low-barrier)
 1. Copy `skill-template/skill-template.md` into `skills/byted-<product-code>-<skill-name>/SKILL.md`.
-2. Keep it an 接入剧本 (scene recognition → command order → failure routing),
+2. Keep it an integration playbook (scene recognition → command order → failure routing),
    not a flag manual.
 
 ## Stable contracts — don't break casually

diff --git a/README.en.md b/README.en.md
@@ -3,7 +3,7 @@
 [![CI](https://github.com/volcengine/VolcEngineRTC_CLI/actions/workflows/ci.yml/badge.svg)](https://github.com/volcengine/VolcEngineRTC_CLI/actions/workflows/ci.yml)
 [![Release](https://img.shields.io/github/v/release/volcengine/VolcEngineRTC_CLI?label=release)](https://github.com/volcengine/VolcEngineRTC_CLI/releases)
 [![npm](https://img.shields.io/npm/v/@volcengine/rtc-cli?label=npm)](https://www.npmjs.com/package/@volcengine/rtc-cli)
-[![Go Version](https://img.shields.io/badge/Go-%3E%3D1.25.12-00ADD8?logo=go)](./go.mod)
+[![Go Version](https://img.shields.io/badge/Go-%3E%3D1.25.13-00ADD8?logo=go)](./go.mod)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
 
 [简体中文](./README.md) | English
@@ -29,7 +29,7 @@ The installer downloads the binary matching the npm package version and current
 
 ### Build locally
 
-Requires Go 1.25.12 or later:
+Requires Go 1.25.13 or later:
 
 ```bash
 git clone https://github.com/volcengine/VolcEngineRTC_CLI.git
@@ -40,7 +40,7 @@ make build
 
 ## Quick start
 
-Before you start, make sure your Volcengine account has an RTC application. A conversational-AI agent is optional; if the account has none, `dev` uses the built-in default scene.
+Before you start, make sure RTC is activated for the account ([activation guide](https://docs.volcengine.com/docs/6348/69865?lang=zh)). A conversational-AI agent is optional; if the account has none, `dev` uses the built-in default scene.
 
 ```bash
 # 1. Create a project
@@ -54,9 +54,9 @@ vertc auth login
 vertc dev
 ```
 
-Open the URL printed in the terminal and click **Start** to join the room and talk. On the first run, `vertc` finds the RTC applications and conversational-AI agents in the account. It prompts only when there is more than one choice. If setup or runtime fails, run `vertc doctor`; it inspects the problem without changing the project.
+Open the URL printed in the terminal and click **Start** to join the room and talk. On the first run, `vertc` selects a sole RTC application automatically and prompts when several applications exist. Any available conversational-AI agent requires user selection, even when there is only one; when none exist, `dev` uses the built-in default scene. If setup or runtime fails, run `vertc doctor`; it inspects the problem without changing the project.
 
-See [Voice-agent projects](./docs/voice-agent.md) for the generated layout, runtime options, and identity management.
+See [Voice-agent projects](./docs/voice-agent.md#english) for the generated layout, runtime options, and identity management.
 
 ## Core capabilities
 
@@ -75,7 +75,7 @@ See [Voice-agent projects](./docs/voice-agent.md) for the generated layout, runt
 | `dev [--web-port N] [--server-port N] [--auto-port]` | Configure RTC resources, check ports, and run the project |
 | `doctor [cli\|project]` | Check CLI and project readiness without changing the project |
 | `explain-error <code>` | Look up SDK and conversational-AI errors offline |
-| `docs search/fetch/list` | Search, fetch, or browse RTC documentation |
+| `docs search/fetch/list` | Search, fetch, or browse RTC documentation; `fetch --match` extracts matching sections/tables |
 | `skills list/read/sync` | Inspect or synchronize the official Skill embedded in the current release |
 | `update [--check\|--force]` | Check or update an npm-managed installation |
 
@@ -95,7 +95,7 @@ To match the Skill to the current `vertc` version or repair an existing installa
 vertc skills sync
 ```
 
-Agents and automation scripts should pass `--format json` explicitly so output does not depend on the terminal environment. stdout contains data only, while progress and warnings go to stderr. Failures return a non-zero exit code and a stable `error.code`. See [Automation and structured output](./docs/automation.md) for headless authorization, non-interactive resource selection, error handling, and notification settings.
+Agents and automation scripts should pass `--format json` explicitly so output does not depend on the terminal environment. stdout contains data only, while progress and warnings go to stderr. Failures return a non-zero exit code and a stable `error.code`. See [Automation and structured output](./docs/automation.md#english) for headless authorization, non-interactive resource selection, error handling, and notification settings.
 
 ## Configuration and security
 
@@ -104,16 +104,16 @@ Agents and automation scripts should pass `--format json` explicitly so output d
 - Signin credentials are stored in the protected `$VERTC_HOME/auth.json` file by default. You can choose the operating-system keyring instead.
 - `RTC_APP_KEY` is never written to project configuration, `VITE_*` frontend variables, logs, command arguments, or structured output; never provide AppKey in chat.
 
-See [Automation and structured output](./docs/automation.md) for authentication modes, credential storage, and automation safety boundaries. See [SECURITY.md](./SECURITY.md) for vulnerability reporting.
+See [Automation and structured output](./docs/automation.md#english) for authentication modes, credential storage, and automation safety boundaries. See [SECURITY.md](./SECURITY.md#english) for vulnerability reporting.
 
 ## Documentation
 
-- [Voice-agent projects](./docs/voice-agent.md) — generated layout, first-run configuration, runtime modes, and identity behavior
-- [Automation and structured output](./docs/automation.md) — authentication, JSON envelopes, error routing, dry runs, notices, and Skills
-- [Troubleshooting](./docs/troubleshooting.md) — installation, authentication, templates, credentials, and runtime recovery
+- [Voice-agent projects](./docs/voice-agent.md#english) — generated layout, first-run configuration, runtime modes, and identity behavior
+- [Automation and structured output](./docs/automation.md#english) — authentication, JSON envelopes, error routing, dry runs, notices, and Skills
+- [Troubleshooting](./docs/troubleshooting.md#english) — installation, authentication, templates, credentials, and runtime recovery
 - [CHANGELOG.md](./CHANGELOG.md) — release changes
-- [SUPPORT.md](./SUPPORT.md) — where to ask questions or report bugs
-- [CONTRIBUTING.md](./CONTRIBUTING.md) — development setup and contribution workflow
+- [SUPPORT.md](./SUPPORT.md#english) — where to ask questions or report bugs
+- [CONTRIBUTING.md](./CONTRIBUTING.md#english) — development setup and contribution workflow
 
 ## Development and contributing
 
@@ -123,4 +123,4 @@ make test
 make ci
 ```
 
-Read [CONTRIBUTING.md](./CONTRIBUTING.md) before opening a pull request. This project is licensed under the [MIT License](./LICENSE).
+Read [CONTRIBUTING.md](./CONTRIBUTING.md#english) before opening a pull request. This project is licensed under the [MIT License](./LICENSE).
diff --git a/README.md b/README.md
@@ -3,7 +3,7 @@
 [![CI](https://github.com/volcengine/VolcEngineRTC_CLI/actions/workflows/ci.yml/badge.svg)](https://github.com/volcengine/VolcEngineRTC_CLI/actions/workflows/ci.yml)
 [![Release](https://img.shields.io/github/v/release/volcengine/VolcEngineRTC_CLI?label=release)](https://github.com/volcengine/VolcEngineRTC_CLI/releases)
 [![npm](https://img.shields.io/npm/v/@volcengine/rtc-cli?label=npm)](https://www.npmjs.com/package/@volcengine/rtc-cli)
-[![Go Version](https://img.shields.io/badge/Go-%3E%3D1.25.12-00ADD8?logo=go)](./go.mod)
+[![Go Version](https://img.shields.io/badge/Go-%3E%3D1.25.13-00ADD8?logo=go)](./go.mod)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
 
 [English](./README.en.md) | 简体中文
@@ -29,7 +29,7 @@ vertc version
 
 ### 本地编译
 
-需要 Go 1.25.12 或更高版本：
+需要 Go 1.25.13 或更高版本：
 
 ```bash
 git clone https://github.com/volcengine/VolcEngineRTC_CLI.git
@@ -40,7 +40,7 @@ make build
 
 ## 快速开始
 
-开始前，请确保账号下已有 RTC 应用。对话式 AI 智能体可选；如果没有，`dev` 会使用内置默认 Scene。
+开始前，请确保账号已开通 RTC 服务（[开通指引](https://docs.volcengine.com/docs/6348/69865?lang=zh)）。对话式 AI 智能体可选；如果没有，`dev` 会使用内置默认场景。
 
 ```bash
 # 1. 创建项目
@@ -54,7 +54,7 @@ vertc auth login
 vertc dev
 ```
 
-打开终端中的地址，点击 **Start** 进房对话。首次运行时，`vertc` 会查询账号下的 RTC 应用和智能体；只有存在多个候选时才会提示选择。配置或运行失败时，运行 `vertc doctor` 检查；该命令不会修改项目。
+打开终端中的地址，点击 **Start** 进房对话。首次运行时，`vertc` 会查询账号下的 RTC 应用和智能体：只有一个 RTC 应用时自动选择，存在多个应用时请用户选择；只要账号下存在智能体，即使只有一个，也需要用户确认。没有智能体时使用内置默认场景。配置或运行失败时，运行 `vertc doctor` 检查；该命令不会修改项目。
 
 项目结构、运行方式和身份管理见[语音智能体项目](./docs/voice-agent.md)。
 
@@ -75,7 +75,7 @@ vertc dev
 | `dev [--web-port N] [--server-port N] [--auto-port]` | 配置 RTC 资源、检查端口并运行项目         |
 | `doctor [cli\|project]`                            | 检查 CLI 和项目是否就绪，不修改项目        |
 | `explain-error <code>`                             | 离线查询 SDK 与对话式 AI 错误码        |
-| `docs search/fetch/list`                           | 搜索、读取或浏览 RTC 文档             |
+| `docs search/fetch/list`                           | 搜索、读取或浏览 RTC 文档；`fetch --match` 可定向提取章节/表格 |
 | `skills list/read/sync`                            | 查看或同步当前 Release 内嵌的官方 Skill |
 | `update [--check\|--force]`                        | 检查或更新 npm 管理的安装             |
 

diff --git a/SECURITY.md b/SECURITY.md
@@ -1,5 +1,47 @@
+<a id="zh-cn"></a>
+
+# 安全策略
+
+[English](#english) | 简体中文
+
+## 支持的版本
+
+首个稳定版本发布前，安全修复只进入最新发布的 `0.x` 版本。稳定版本发布后，本节会明确列出仍受支持的版本线。
+
+## 报告漏洞
+
+不要通过公开 Issue、Discussion、Pull Request 或聊天消息报告疑似漏洞。请使用仓库的 GitHub 私密漏洞报告：
+
+<https://github.com/volcengine/VolcEngineRTC_CLI/security/advisories/new>
+
+条件允许时，请提供：
+
+- 受影响的版本、平台和安装方式；
+- 涉及的命令或工作流；
+- 复现步骤或最小 PoC；
+- 安全影响和已知前置条件；
+- 建议的缓解方式或补丁；
+- 该问题是否已经在其他地方披露。
+
+不要提供真实生产凭据。请使用测试值，并对 AppKey、AccessKey、Signin Token、RTC Token、私有端点、账号标识和控制台数据脱敏。
+
+维护者会尽快确认报告、开展调查，并与报告人协调修复和披露时间。在修复版本发布前，请不要公开漏洞细节。
+
+## 安全边界
+
+- Signin access token 和 refresh token 默认保存在权限受限的用户级文件 `$VERTC_HOME/auth.json`。只有用户显式选择 `--store=keyring` 后，CLI 才使用操作系统凭据库。
+- `RTC_APP_KEY` 可以保存在 Git 已忽略的 `.env.local` 中，但不能进入 `vertc.config.yaml`、`VITE_*` 变量、前端代码、日志或命令输出。
+- 远程 Release 和模板制品必须通过固定 SHA-256 摘要校验后才能使用。
+- 分享或部署生成项目之前，应检查项目内容和场景配置。
+
+---
+
+<a id="english"></a>
+
 # Security Policy
 
+[简体中文](#zh-cn) | English
+
 ## Supported versions
 
 Before the first stable release, security fixes are applied to the latest
@@ -33,8 +75,9 @@ for a fix and release before publishing details.
 
 ## Security boundaries
 
-- Signin access and refresh tokens belong in the operating-system credential
-  store.
+- Signin access and refresh tokens use the protected user-level
+  `$VERTC_HOME/auth.json` file by default. The CLI uses the operating-system
+  credential store only after the user explicitly selects `--store=keyring`.
 - `RTC_APP_KEY` may be stored in the gitignored `.env.local` file but must not
   enter `vertc.config.yaml`, `VITE_*` variables, frontend code, logs, or command
   output.