@viceme-ai/cli 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## [0.2.0] - 2026-07-19
+
+### Features
+
+- notify Feishu after CLI releases (`1584c09`)
+- simplify CLI region and output contract (`021704e`)
+
+### Fixes
+
+- publish through repository GitHub App (`7db30af`)
+- prepare only on release intent (`a28c0b5`)
+- use scoped deploy key for dev (`fcc7a0b`)
+- support protected dev automation (`5f490fd`)
+- make npm tests version agnostic (`01ef51f`)
+- return direct CLI device authorization link (`6f125f3`)
+- default CLI API to viceme.cn (`8ac5172`)
+- retry npm registry reads after publish (`2c757af`)
+
+### Other Changes
+
+- explain direct browser device authorization (`07a1cd9`)
+- clarify Agent Skills and AI quick start (`60672b2`)
+- add Chinese CLI guide (`aa892e0`)
+- improve CLI quick start and safety guide (`3f5e9e3`)
+
 ## [0.1.0] - 2026-07-18
 
 ### Features

package/README.md

@@ -1,70 +1,313 @@
 # Viceme CLI
 
-`viceme` is the deterministic client used by the bundled Viceme Agent Skill. Source parsing, LLM compilation, BuildRun materialization, and share publication stay server-side.
+[![npm version](https://img.shields.io/npm/v/@viceme-ai/cli.svg)](https://www.npmjs.com/package/@viceme-ai/cli)
+[![Go Version](https://img.shields.io/badge/go-%3E%3D1.23-blue.svg)](https://go.dev/)
+[![CLI quality gates](https://github.com/ViceMe-AI/cli/actions/workflows/ci.yml/badge.svg)](https://github.com/ViceMe-AI/cli/actions/workflows/ci.yml)
 
-## Install
+[中文版](./README.zh.md) | [English](./README.md)
 
-Node.js 18.20 or newer is required for the npm launcher.
+The official command-line client and Agent Skill for publishing external Skills as stable, shareable Viceme Agents. It is built for AI coding tools such as Codex and Claude Code: the Agent Skill understands user intent, while the CLI provides the deterministic authentication, upload, publication, and status protocol.
+
+[Install](#installation--quick-start) · [AI Agent Skills](#agent-skills) · [Auth](#authentication) · [Regions](#regions) · [Commands](#command-overview) · [Output contract](#json-output-contract) · [Security](#security-and-risk-controls) · [Development](#development)
+
+> **Rollout status:** the Core publication transport and stable-link path are implemented behind a controlled allowlist. Public rollout remains blocked until the exact Candidate preview, test run, and result-confirmation gate is complete. The current `--yes` confirms the publication request; it is not proof that the user reviewed the final Candidate.
+
+## Why Viceme CLI?
+
+- **Agent-native** — ships together with the official Viceme Agent Skill for Codex and Claude Code.
+- **Deterministic boundary** — the CLI performs typed protocol actions; it does not start another conversational Agent loop.
+- **Server-side compilation** — source parsing, LLM compilation, BuildRun materialization, and Release publication stay on Viceme infrastructure.
+- **Stable publishing** — later releases of the same logical Agent keep the same share URL.
+- **Multiple source types** — accepts GitHub Skills, pasted Xiaohongshu/RedSkill expressions, archives, and local Skill folders.
+- **Secure by default** — credentials use the operating-system keychain, public mutations require confirmation, and downloaded binaries are checksum-verified.
+- **Machine-stable output** — every data command uses the same JSON success/error envelope without an output-format flag.
+
+## Installation & Quick Start
+
+### Requirements
+
+- Node.js 18.20 or newer
+- macOS or Linux on `amd64`/`arm64`, or Windows on `amd64`/`arm64`
+
+### Quick Start (Human Users)
+
+> **Note for AI assistants:** If you are an AI Agent helping the user install Viceme, jump directly to [Quick Start (AI Agent)](#quick-start-ai-agent). It defines the required cross-turn device login flow.
+
+#### Install
+
+Choose one of the following methods.
+
+**Option 1 — One-shot npm install (recommended):**
+
+```bash
+npx --yes @viceme-ai/cli@latest install
+```
+
+**Option 2 — Install the npm launcher globally:**
 
 ```bash
 npm install --global @viceme-ai/cli
 viceme install
 ```
 
-For a one-shot bootstrap without a prior global install, use
-`npx --yes @viceme-ai/cli@latest install`.
+Both methods persist the npm launcher, download the matching checksum-verified Go binary, and install the bundled Viceme Agent Skill. They default to the China service. For the international service:
+
+```bash
+npx --yes @viceme-ai/cli@latest install --region global
+```
+
+#### Authenticate and verify
+
+If the installation result says authentication is required, start device login:
+
+```bash
+viceme auth login --no-wait
+```
+
+Open the returned `verification_url`; it normally links directly to the matching prefilled device request. Complete authorization, and then continue with the returned device code:
+
+```bash
+viceme auth login --device-code <device-code>
+viceme auth status
+viceme skills doctor
+```
+
+## Quick Start (AI Agent)
+
+> The following steps are for AI Agents. Browser authorization must be completed by the user in a separate turn; never wait indefinitely or ask the user for a token.
+
+**Step 1 — Install**
+
+Use the complete bootstrap command from the bundled Skill. The explicit npm registries are part of the installation trust boundary:
+
+```bash
+npx --yes --registry=https://registry.npmjs.org --@viceme-ai:registry=https://registry.npmjs.org --package=@viceme-ai/cli@latest -- viceme install
+```
+
+Read `data.authenticated` and `data.next_step` from the result. If authentication is already valid, continue to Step 4.
+
+**Step 2 — Start device login when required**
+
+```bash
+viceme auth login --no-wait
+```
+
+Return the exact `data.verification_url`; the CLI normalizes it to the prefilled `verification_url_complete` browser link when available. Include `data.user_code` only as a fallback if the browser asks for it. Preserve `data.device_code` for the continuation command, then stop the current turn. Do not request, print, or place an access token in the conversation.
+
+**Step 3 — Continue the same login in a later turn**
+
+After the user confirms browser authorization:
+
+```bash
+viceme auth login --device-code <device-code>
+```
+
+If authorization is still pending, reuse the same device code before it expires. Do not start a second device flow unless the original one has expired.
+
+**Step 4 — Verify**
+
+```bash
+viceme auth status
+viceme skills doctor
+viceme skills list
+```
+
+Continue only when authentication is valid and `skills doctor` reports a healthy, compatible installation.
+
+**Step 5 — Inspect the first source**
+
+```bash
+viceme skill inspect https://github.com/acme/poster-skill
+```
+
+Inspection is read-only. Follow the bundled `viceme` Skill for source-specific handling, Target selection, confirmation, bounded job waiting, and result reporting. Public publication remains blocked until the exact Candidate confirmation gate described above is complete.
+
+## Regions
+
+Viceme exposes one product-level region choice during installation:
+
+| Region | Install command | API endpoint |
+|---|---|---|
+| China | `viceme install` | `https://api.viceme.cn` |
+| International | `viceme install --region global` | `https://api.viceme.ai` |
+
+The selected value is persisted as `region=cn|global`; later commands use it automatically. Credentials are isolated by region, so a China token is never reused against the international API, or vice versa.
+
+There is no public API URL, profile, or output-format configuration. For local development only, set `VICEME_API_BASE_URL` in the terminal environment.
+
+## Agent Skills
+
+The current release deliberately ships one platform-level Agent Skill:
+
+| Skill | Description | Supported hosts |
+|---|---|---|
+| `viceme` | Install, inspect, convert, publish, update, or share external Skills as stable Viceme Agents; enforces authentication, source, Target, confirmation, job, and safety rules | Codex, Claude Code |
+
+GitHub, Xiaohongshu/RedSkill, ZIP, and folder inputs are source types handled by the same `viceme` publication workflow, not separate Agent Skills. This keeps one consistent safety and stable-link contract across providers.
+
+The CLI and `viceme` Agent Skill are released from this repository at the same version. `viceme install` installs the complete Skill bundle into detected supported hosts, while the binary embeds the agent-readable subset needed for deterministic self-inspection.
+
+```bash
+viceme skills list
+viceme skills read viceme
+viceme skills read viceme references/commands.md
+viceme skills doctor
+```
+
+`skills doctor` checks the CLI version, Skill version, compatibility range, full bundle digest, and embedded-content digest independently. A modified or incompatible installation fails closed.
+
+## Authentication
+
+| Command | Purpose |
+|---|---|
+| `viceme auth status` | Show whether the current region is authenticated |
+| `viceme auth login --no-wait` | Start device authorization and return immediately |
+| `viceme auth login --device-code <code>` | Complete a previously started authorization |
+| `viceme auth logout` | Revoke and remove the current region credential |
+
+Tokens are stored only in the operating-system keychain. There is no plaintext token fallback, and successful login output never contains the access or refresh token.
+
+## Supported Sources
+
+### GitHub or trusted provider
+
+```bash
+viceme skill inspect https://github.com/acme/poster-skill
+viceme skill publish --resolution-id <resolution-id> --yes
+```
+
+### Xiaohongshu or RedSkill copied expression
 
-The root `install` command performs the complete bootstrap: it atomically installs the matching Viceme Skill into Codex and/or Claude Code, creates a non-sensitive local config, checks authentication without printing credentials, and returns the device-login command when needed.
+```bash
+viceme skill inspect --expression-stdin
+viceme skill publish --resolution-id <resolution-id> --yes
+```
 
-The npm package is intentionally a small launcher, not six copies of the Go executable. It downloads the binary for the package's exact version from the corresponding GitHub Release, verifies the published SHA-256 checksum, writes a complete pair into a unique staging directory, and atomically publishes that directory as an immutable cache generation before executing it. Concurrent cold starts may repeat a download, but never share, overwrite, or delete a mutable binary/checksum pair; an interrupted process leaves only ignored staging state. Supported release targets are macOS and Linux on `amd64`/`arm64`, plus Windows on `amd64`/`arm64`.
+The copied expression is untrusted data. Viceme extracts a locator and fetches the source through an approved connector; it never executes marketplace installation text.
 
-## Authenticate and publish
+### Archive or local Skill folder
 
-The current Core records `--yes` as a versioned publication-admission confirmation and remains an internal, default-off allowlist probe. That admission permits the background compile, but it is not proof that the user reviewed the resulting immutable Release Candidate. Do not expose it as the public product flow: external rollout is blocked until T2 adds exact-candidate preview and confirmation before commit. The commands below exercise the transport and stable-link Core while that gate is implemented.
+```bash
+viceme skill publish --file ./poster-skill.zip --new-target --target-alias poster --yes
+viceme skill publish --dir ./poster-skill --new-target --target-alias poster --yes
+```
+
+For later releases, resolve the existing Target and use optimistic concurrency. Never turn a conflict into a new share link:
 
 ```bash
-viceme auth login --no-wait --json
-viceme skill inspect https://github.com/acme/poster-skill --json
-viceme skill publish --resolution-id <resolution-id> --yes --json
-viceme job wait <publication-id> --timeout 60s --json
+viceme skill target get target_123
+viceme skill publish --file ./poster-skill-v2.zip \
+  --target-id target_123 --expected-target-version 4 --yes
 ```
 
-Credentials are stored only in the operating-system keychain. There is no plaintext token fallback.
+## Command Overview
+
+| Command group | Purpose |
+|---|---|
+| `viceme install` | Install the persistent launcher, Agent Skill, and region configuration |
+| `viceme auth` | Start, complete, inspect, or revoke device authentication |
+| `viceme skill inspect` | Freeze and inspect a source candidate without publishing |
+| `viceme skill publish` | Create or update a stable Skill Agent publication |
+| `viceme skill target` | Resolve existing logical Agent Targets and versions |
+| `viceme job` | Read, wait for, resume, or cancel a durable publication |
+| `viceme skills` | Read, install, and diagnose the bundled Agent Skill |
+| `viceme update` | Update the npm launcher, verified binary, and bundled Skill together |
+
+Use `viceme <command> --help` for the exact flags. The release-checked machine-readable surface is stored in [`skills/viceme/references/command-manifest.json`](skills/viceme/references/command-manifest.json).
+
+## JSON Output Contract
 
-## Diagnose and update
+All data commands emit a stable JSON envelope by default.
+
+Success is written to **stdout** with exit code `0`:
+
+```json
+{
+  "ok": true,
+  "data": {},
+  "meta": {
+    "cli_version": "0.1.0",
+    "skill_version": "0.1.0"
+  }
+}
+```
+
+CLI execution errors are written to **stderr** with a non-zero exit code:
+
+```json
+{
+  "ok": false,
+  "error": {
+    "type": "validation",
+    "subtype": "source_required",
+    "message": "provide exactly one source argument or --expression-stdin"
+  },
+  "meta": {
+    "cli_version": "0.1.0",
+    "skill_version": "0.1.0"
+  }
+}
+```
+
+Determine command success from the process exit code or `ok == true`. A successfully read publication may still contain a business terminal status such as `unsupported`, `rejected`, or `failed`; inspect `data.status` instead of treating those states as CLI transport failures.
+
+| Exit code | Meaning |
+|---|---|
+| `0` | Command completed; inspect returned business status when applicable |
+| `2` | Validation failure |
+| `3` | Authentication or authorization failure |
+| `4` | Retryable network failure |
+| `5` | Internal or protocol failure |
+| `6` | Policy rejection before publication creation |
+| `10` | Explicit confirmation required |
+
+## Security and Risk Controls
+
+- **No source execution** — the CLI and compiler do not execute third-party scripts, binaries, shell fragments, marketplace commands, or copied instructions.
+- **Explicit public mutation** — publishing and cancellation require `--yes`; exit code `10` means the Agent must obtain confirmation, not silently retry.
+- **Safe preview** — use `--dry-run` on inspect or publish when the user needs to review the planned request without network or publication side effects.
+- **Credential isolation** — credentials stay in the OS keychain and are namespaced by region.
+- **Immutable inputs** — inspection binds publication to an immutable source snapshot rather than re-reading a floating URL later.
+- **Bounded waiting** — `job wait` has a maximum duration and returns the latest durable state without cancelling the workflow.
+- **Verified distribution** — the npm launcher downloads the binary for its exact package version and verifies the published SHA-256 checksum before activation.
+
+## Diagnose and Update
 
 ```bash
-viceme skills doctor --json
-viceme update --check --json
-viceme update --json
+viceme skills doctor
+viceme update --check
+viceme update
 ```
 
-Every Skill installation records its CLI version, Skill version, minimum compatible CLI version, full bundle digest, and agent-readable embedded digest. `skills doctor` validates each item independently.
+`viceme update` installs one exact npm package version, acquires its verified Go binary, and refreshes the bundled Skill from that same release. A standalone development binary is never silently replaced.
 
-`viceme update` is supported for the npm launcher. It resolves the latest version, globally installs that exact package with lifecycle scripts disabled, and then invokes the same exact package to acquire its verified binary and reinstall its bundled Skill. A standalone development binary is not silently replaced; bootstrap it through npm first. Homebrew and signed standalone update manifests remain future distribution channels.
+## Development
 
-## Development and quality gates
+Go 1.23 or newer is required when building from source.
 
 ```bash
 make build
 make test
 make check
+make skill-check
 make npm-package-check
 make quality-check
 ```
 
-`make npm-package-check` does not require a published GitHub Release. It injects the locally built Go executable through `VICEME_BINARY_PATH`, packs the npm tarball, and runs the real npm launcher through `install` in an isolated temporary home. The override is for development and CI only.
+The main checked-in quality artifacts are:
+
+- [`skills/viceme/references/command-manifest.json`](skills/viceme/references/command-manifest.json), generated from the Cobra command tree;
+- [`quality/example-dry-runs.json`](quality/example-dry-runs.json), which executes documented source paths without network access;
+- [`quality/release-manifest.json`](quality/release-manifest.json), which pins CLI/Skill compatibility and content digests.
 
-The checked-in quality artifacts are:
+`make npm-package-check` builds the Go executable, packs the real npm tarball, and runs the launcher in isolated temporary homes. It does not require an already-published GitHub Release.
 
-- `skills/viceme/references/command-manifest.json`, generated from the Cobra command tree;
-- `quality/example-dry-runs.json`, which executes the documented inspect/publish paths without network access;
-- `quality/release-manifest.json`, which pins CLI/Skill compatibility and both Skill digests.
+## Releases
 
-Set `VICEME_API_BASE_URL` for local integration. Release asset names are fixed as `viceme_<version>_<goos>_<goarch>[.exe]` with a sibling `.sha256`. The workflow checks that exactly all six binary/checksum pairs exist and blocks npm publication until they have been uploaded to a completed GitHub Release.
+Maintainers merge normal changes into `dev`; they do not manually edit versions, create tags, write changelog entries, or run `npm publish`. GitHub Actions maintains a single automated `dev -> main` Release PR. Merging that PR authorizes the reviewed version, tag, immutable GitHub Release assets, and npm trusted publication.
 
-Releases do not require a maintainer to edit versions, write a changelog, create a tag, or run `npm publish`. A push to `dev` runs `.github/workflows/release-pr.yml`, which selects the next stable semantic version from Conventional Commits, synchronizes npm/Go/Skill metadata and generated digests, updates `CHANGELOG.md`, runs the release quality gates, and creates or updates the `dev` to `main` Release PR. Merge that PR to approve the release; `.github/workflows/release.yml` then tags the exact reviewed head, reconnects the merged `main` commit into `dev`, creates or verifies the immutable GitHub Release, and publishes or verifies the npm package. See [`docs/releasing.md`](docs/releasing.md) for setup, recovery, and versioning details.
+See [`docs/releasing.md`](docs/releasing.md) for repository setup, OIDC trusted publishing, recovery, and integrity rules.
 
-npm publishing uses a pinned OIDC-capable npm CLI and provenance. The steady-state authentication path is GitHub Actions trusted publishing (`id-token: write`): configure `@viceme-ai/cli` to trust `ViceMe-AI/cli` and `.github/workflows/release.yml`. If npm requires a credential for the package's first-ever publication, temporarily configure a granular publish token as the `NPM_TOKEN` repository secret; the workflow exposes it only as `NODE_AUTH_TOKEN` to the final publish-or-verify step. Remove the secret after trusted publishing is configured.
+## Contributing
 
-Release reruns are fail-closed. If the GitHub Release already exists, the workflow byte-compares every existing asset with the binaries/checksums rebuilt from the tag, uploads only assets missing after an interrupted release, and then verifies the complete 12-asset set. It never overwrites an existing asset. npm publication accepts stable `x.y.z` versions only. If the exact version already exists, its registry integrity must equal the local `npm pack` integrity; an older `latest` tag is safely promoted to that exact version, while rerunning an older release never demotes a newer `latest`. This lets either publication stage be retried without deleting or replacing immutable content.
+Issues and pull requests are welcome. Changes to the public command surface must update the generated command manifest, bundled Skill examples, quality fixtures, and tests in the same PR.

package/README.zh.md

@@ -0,0 +1,313 @@
+# Viceme CLI
+
+[![npm version](https://img.shields.io/npm/v/@viceme-ai/cli.svg)](https://www.npmjs.com/package/@viceme-ai/cli)
+[![Go Version](https://img.shields.io/badge/go-%3E%3D1.23-blue.svg)](https://go.dev/)
+[![CLI quality gates](https://github.com/ViceMe-AI/cli/actions/workflows/ci.yml/badge.svg)](https://github.com/ViceMe-AI/cli/actions/workflows/ci.yml)
+
+[中文版](./README.zh.md) | [English](./README.md)
+
+Viceme 官方命令行客户端与 Agent Skill，用于将外部 Skill 发布为稳定、可分享的 Viceme Agent。它面向 Codex、Claude Code 等 AI 编程工具：Agent Skill 负责理解用户意图，CLI 负责确定性的认证、上传、发布和状态协议。
+
+[安装](#安装与快速开始) · [AI Agent Skills](#agent-skills) · [认证](#认证) · [区域](#区域) · [命令](#命令概览) · [输出契约](#json-输出契约) · [安全](#安全与风险控制) · [开发](#开发)
+
+> **开放状态：** Core 发布传输和稳定链接链路已在受控白名单后实现。正式对外开放仍取决于精确 Candidate 预览、试运行和结果确认门的完成。当前 `--yes` 只确认发起发布请求，并不代表用户已经审阅最终 Candidate。
+
+## 为什么选择 Viceme CLI？
+
+- **为 Agent 原生设计** — 与 Codex、Claude Code 可使用的官方 Viceme Agent Skill 一起发布。
+- **确定性边界** — CLI 执行类型化协议操作，不会再启动一层对话式 Agent Loop。
+- **服务端编译** — 来源解析、LLM 编译、BuildRun 固化和 Release 发布均在 Viceme 基础设施中完成。
+- **稳定发布** — 同一个逻辑 Agent 后续发布新版本时继续使用同一个分享链接。
+- **支持多种来源** — 支持 GitHub Skill、小红书或 RedSkill 复制口令、压缩包和本地 Skill 目录。
+- **默认安全** — 凭证保存在操作系统密钥链中，公开变更需要确认，下载的二进制文件必须通过校验和验证。
+- **机器稳定输出** — 所有数据命令统一使用 JSON 成功或错误信封，不需要输出格式参数。
+
+## 安装与快速开始
+
+### 环境要求
+
+- Node.js 18.20 或更高版本
+- macOS 或 Linux `amd64`/`arm64`，或 Windows `amd64`/`arm64`
+
+### 快速开始（人类用户）
+
+> **AI 助手注意：** 如果你是正在帮助用户安装 Viceme 的 AI Agent，请直接跳转到[快速开始（AI Agent）](#快速开始ai-agent)。该章节定义了必须遵循的跨回合设备登录流程。
+
+#### 安装
+
+以下两种方式任选其一。
+
+**方式一 — 通过 npm 一次性安装（推荐）：**
+
+```bash
+npx --yes @viceme-ai/cli@latest install
+```
+
+**方式二 — 全局安装 npm 启动器：**
+
+```bash
+npm install --global @viceme-ai/cli
+viceme install
+```
+
+两种方式都会持久化 npm 启动器、下载匹配且通过校验和验证的 Go 二进制文件，并安装随包发布的 Viceme Agent Skill。默认使用中国区服务。使用国际区服务：
+
+```bash
+npx --yes @viceme-ai/cli@latest install --region global
+```
+
+#### 认证并验证
+
+如果安装结果提示需要认证，启动设备登录：
+
+```bash
+viceme auth login --no-wait
+```
+
+打开返回的 `verification_url`；它通常会直接进入已预填对应设备码的授权请求。完成授权，然后使用返回的 device code 继续：
+
+```bash
+viceme auth login --device-code <device-code>
+viceme auth status
+viceme skills doctor
+```
+
+## 快速开始（AI Agent）
+
+> 以下步骤面向 AI Agent。浏览器授权必须由用户在另一个回合完成；不要无限等待，也不要向用户索取令牌。
+
+**第 1 步 — 安装**
+
+使用随包 Skill 中定义的完整引导命令。显式 npm registry 是安装信任边界的一部分：
+
+```bash
+npx --yes --registry=https://registry.npmjs.org --@viceme-ai:registry=https://registry.npmjs.org --package=@viceme-ai/cli@latest -- viceme install
+```
+
+读取结果中的 `data.authenticated` 和 `data.next_step`。如果认证已经有效，直接进入第 4 步。
+
+**第 2 步 — 需要时启动设备登录**
+
+```bash
+viceme auth login --no-wait
+```
+
+向用户返回准确的 `data.verification_url`；存在 `verification_url_complete` 时，CLI 会把这个已预填设备码的浏览器直达链接规范化为 `verification_url`。只有浏览器要求输入时，才把 `data.user_code` 作为备用信息提供。保留 `data.device_code` 供后续命令使用，然后结束当前回合。不要在对话中索取、打印或传递访问令牌。
+
+**第 3 步 — 在后续回合继续同一个登录流程**
+
+用户确认已在浏览器完成授权后：
+
+```bash
+viceme auth login --device-code <device-code>
+```
+
+如果授权仍处于等待状态，应在过期前继续使用同一个 device code。只有原流程已过期时才能重新发起设备登录。
+
+**第 4 步 — 验证**
+
+```bash
+viceme auth status
+viceme skills doctor
+viceme skills list
+```
+
+只有认证有效且 `skills doctor` 报告安装健康、版本兼容时，才能继续。
+
+**第 5 步 — 检查第一个来源**
+
+```bash
+viceme skill inspect https://github.com/acme/poster-skill
+```
+
+inspect 是只读操作。后续应按照随包发布的 `viceme` Skill 处理不同来源、Target 选择、用户确认、有界任务等待和结果返回。在上方所述的精确 Candidate 确认门完成前，公开发布流程仍保持关闭。
+
+## 区域
+
+Viceme 在安装时只提供一个产品级区域选择：
+
+| 区域 | 安装命令 | API 地址 |
+|---|---|---|
+| 中国区 | `viceme install` | `https://api.viceme.cn` |
+| 国际区 | `viceme install --region global` | `https://api.viceme.ai` |
+
+选择结果保存为 `region=cn|global`，后续命令会自动使用。不同区域的凭证彼此隔离，中国区令牌不会用于国际区 API，反之亦然。
+
+CLI 不提供公开的 API 地址、profile 或输出格式配置。本地开发时可以在终端环境中设置 `VICEME_API_BASE_URL`。
+
+## Agent Skills
+
+当前版本有意只提供一个平台级 Agent Skill：
+
+| Skill | 说明 | 支持的宿主 |
+|---|---|---|
+| `viceme` | 将外部 Skill 安装、检查、转换、发布、更新或分享为稳定的 Viceme Agent；统一约束认证、来源、Target、确认、任务和安全规则 | Codex、Claude Code |
+
+GitHub、小红书/RedSkill、ZIP 和目录是同一个 `viceme` 发布流程处理的来源类型，不是相互独立的 Agent Skills。这样可以让不同来源共享一致的安全边界和稳定链接合同。
+
+CLI 与 `viceme` Agent Skill 从同一个仓库以相同版本发布。`viceme install` 会把完整 Skill Bundle 安装到检测到的受支持宿主中；二进制文件同时嵌入用于确定性自检、可供 Agent 阅读的内容子集。
+
+```bash
+viceme skills list
+viceme skills read viceme
+viceme skills read viceme references/commands.md
+viceme skills doctor
+```
+
+`skills doctor` 会分别校验 CLI 版本、Skill 版本、兼容范围、完整 Bundle 摘要和嵌入内容摘要。安装内容被修改或版本不兼容时会直接失败。
+
+## 认证
+
+| 命令 | 用途 |
+|---|---|
+| `viceme auth status` | 查看当前区域是否已认证 |
+| `viceme auth login --no-wait` | 启动设备授权并立即返回 |
+| `viceme auth login --device-code <code>` | 完成之前启动的设备授权 |
+| `viceme auth logout` | 撤销并删除当前区域的凭证 |
+
+令牌只保存在操作系统密钥链中，不会回退到明文存储；登录成功的输出也不会包含访问令牌或刷新令牌。
+
+## 支持的来源
+
+### GitHub 或可信来源平台
+
+```bash
+viceme skill inspect https://github.com/acme/poster-skill
+viceme skill publish --resolution-id <resolution-id> --yes
+```
+
+### 小红书或 RedSkill 复制口令
+
+```bash
+viceme skill inspect --expression-stdin
+viceme skill publish --resolution-id <resolution-id> --yes
+```
+
+复制口令属于不可信数据。Viceme 只从中提取定位信息，并通过允许的连接器获取来源；不会执行市场安装文案中的命令。
+
+### 压缩包或本地 Skill 目录
+
+```bash
+viceme skill publish --file ./poster-skill.zip --new-target --target-alias poster --yes
+viceme skill publish --dir ./poster-skill --new-target --target-alias poster --yes
+```
+
+后续发布新版本时，应先解析现有 Target 并使用乐观并发控制。发生冲突时不能创建新的分享链接：
+
+```bash
+viceme skill target get target_123
+viceme skill publish --file ./poster-skill-v2.zip \
+  --target-id target_123 --expected-target-version 4 --yes
+```
+
+## 命令概览
+
+| 命令组 | 用途 |
+|---|---|
+| `viceme install` | 安装持久化启动器、Agent Skill 和区域配置 |
+| `viceme auth` | 启动、完成、检查或撤销设备认证 |
+| `viceme skill inspect` | 固化并检查来源候选，不执行发布 |
+| `viceme skill publish` | 创建或更新具有稳定链接的 Skill Agent 发布 |
+| `viceme skill target` | 解析现有逻辑 Agent Target 及其版本 |
+| `viceme job` | 读取、等待、恢复或取消持久化发布任务 |
+| `viceme skills` | 读取、安装和诊断随包发布的 Agent Skill |
+| `viceme update` | 同时更新 npm 启动器、已校验二进制文件和随包发布的 Skill |
+
+使用 `viceme <command> --help` 查看准确参数。经过发布检查的机器可读命令面存放在 [`skills/viceme/references/command-manifest.json`](skills/viceme/references/command-manifest.json)。
+
+## JSON 输出契约
+
+所有数据命令默认输出稳定的 JSON 信封。
+
+成功结果写入 **stdout**，退出码为 `0`：
+
+```json
+{
+  "ok": true,
+  "data": {},
+  "meta": {
+    "cli_version": "0.1.0",
+    "skill_version": "0.1.0"
+  }
+}
+```
+
+CLI 执行错误写入 **stderr**，退出码非零：
+
+```json
+{
+  "ok": false,
+  "error": {
+    "type": "validation",
+    "subtype": "source_required",
+    "message": "provide exactly one source argument or --expression-stdin"
+  },
+  "meta": {
+    "cli_version": "0.1.0",
+    "skill_version": "0.1.0"
+  }
+}
+```
+
+应根据进程退出码或 `ok == true` 判断命令是否成功。成功读取发布任务时，业务状态仍可能是 `unsupported`、`rejected` 或 `failed`；这时应检查 `data.status`，不能把这些状态当成 CLI 传输失败。
+
+| 退出码 | 含义 |
+|---|---|
+| `0` | 命令完成；适用时继续检查返回的业务状态 |
+| `2` | 参数校验失败 |
+| `3` | 认证或授权失败 |
+| `4` | 可重试的网络失败 |
+| `5` | 内部或协议失败 |
+| `6` | 创建发布前被策略拒绝 |
+| `10` | 需要明确确认 |
+
+## 安全与风险控制
+
+- **不执行来源内容** — CLI 和编译器不会执行第三方脚本、二进制文件、shell 片段、市场命令或复制口令中的指令。
+- **公开变更需要明确确认** — 发布和取消操作需要 `--yes`；退出码 `10` 表示 Agent 必须向用户取得确认，不能静默重试。
+- **安全预览** — 用户需要检查计划请求时，可以对 inspect 或 publish 使用 `--dry-run`，不会产生网络请求或发布副作用。
+- **凭证隔离** — 凭证保存在操作系统密钥链中，并按区域隔离。
+- **不可变输入** — inspect 会把发布绑定到不可变来源快照，而不是在之后重新读取浮动 URL。
+- **有界等待** — `job wait` 有最大等待时间；超时后返回最新持久化状态，不会取消工作流。
+- **可信分发** — npm 启动器下载与其准确包版本匹配的二进制文件，并在启用前验证发布的 SHA-256 校验和。
+
+## 诊断与更新
+
+```bash
+viceme skills doctor
+viceme update --check
+viceme update
+```
+
+`viceme update` 会安装一个准确的 npm 包版本，获取对应的已校验 Go 二进制文件，并从同一版本刷新随包发布的 Skill。独立开发版二进制文件不会被静默替换。
+
+## 开发
+
+从源码构建需要 Go 1.23 或更高版本。
+
+```bash
+make build
+make test
+make check
+make skill-check
+make npm-package-check
+make quality-check
+```
+
+仓库中主要的质量产物包括：
+
+- [`skills/viceme/references/command-manifest.json`](skills/viceme/references/command-manifest.json)：从 Cobra 命令树生成；
+- [`quality/example-dry-runs.json`](quality/example-dry-runs.json)：在没有网络请求的情况下执行文档中的来源路径；
+- [`quality/release-manifest.json`](quality/release-manifest.json)：固定 CLI/Skill 兼容范围和内容摘要。
+
+`make npm-package-check` 会构建 Go 可执行文件、打包真实 npm tarball，并在相互隔离的临时主目录中运行启动器，不依赖已经发布的 GitHub Release。
+
+## 发布
+
+维护者将普通改动合入 `dev`；不需要手工修改版本、创建 tag、编写 changelog 或执行 `npm publish`。GitHub Actions 持续维护唯一的 `dev -> main` 自动 Release PR。合并该 PR 即授权发布经过审阅的版本、tag、不可变 GitHub Release 产物及 npm trusted publication。
+
+仓库设置、OIDC trusted publishing、恢复和完整性规则参见 [`docs/releasing.md`](docs/releasing.md)。
+
+## 贡献
+
+欢迎提交 Issue 和 Pull Request。公共命令面发生变化时，必须在同一个 PR 中更新生成的命令清单、随包发布的 Skill 示例、质量样例和测试。

package/docs/releasing.md

@@ -6,31 +6,60 @@ files, create tags, write changelog entries, or run npm commands locally.
 
 ## Normal flow
 
-1. A non-bot push to `dev` starts `Prepare Release PR`.
-2. `npm/scripts/prepare-release.mjs` finds the newest reachable stable tag and
+1. Feature and fix PRs can merge into `dev` without starting release
+   preparation.
+2. A maintainer explicitly opens or marks ready a repository-owned `dev` to
+   `main` PR. That release intent starts `Prepare Release PR`.
+3. `npm/scripts/prepare-release.mjs` finds the newest reachable stable tag and
    reads all unreleased non-merge commits.
-3. Conventional Commits select the next version:
+4. Conventional Commits select the next version:
    - a `BREAKING CHANGE` footer or `type!:` selects major;
    - `feat:` selects minor;
    - every other releasable change selects patch.
-4. The workflow synchronizes `package.json`, `package-lock.json`, Go build
+5. The workflow synchronizes `package.json`, `package-lock.json`, Go build
    metadata, bundled Skill metadata, command manifest, release digests, and
    `CHANGELOG.md`.
-5. It runs `make check` and `make npm-package-check`, commits the generated
-   release files to `dev`, and creates or updates one `dev` to `main` PR titled
-   `chore(release): vX.Y.Z`.
-6. A maintainer reviews and merges that PR using the repository's preferred
-   merge method.
-7. `Release CLI and npm launcher` tags the exact reviewed PR head, reconnects
-   the merged `main` commit into `dev` when necessary, reruns the quality gates,
-   builds six platform binaries and six checksums, creates the GitHub Release,
-   and publishes the npm launcher.
+6. It runs `make check` and `make npm-package-check`, creates a short-lived
+   installation token for the repository-scoped ViceMe Release GitHub App, and
+   commits only the generated files directly to protected `dev`.
+7. The existing `dev` to `main` PR synchronizes, runs its required quality
+   checks, and is updated to `chore(release): vX.Y.Z` with exact run and commit
+   evidence. No internal preparation PR is created.
+8. A maintainer reviews and merges that same Release PR.
+9. `Release CLI and npm launcher` tags the exact reviewed `dev` head, reruns
+   the quality gates, builds six platform binaries and six checksums, creates
+   the GitHub Release, publishes the npm launcher, and then sends an
+   AI-generated release summary to the release notification group in Feishu.
 
 ## One-time repository setup
 
-GitHub Actions needs `Read and write permissions` and permission to create pull
-requests so the built-in `GITHUB_TOKEN` can update `dev` and maintain the
-Release PR. No maintainer PAT is required by these workflows.
+Register a private organization-owned GitHub App named `ViceMe CLI Release Bot`.
+Install it only on `ViceMe-AI/cli` with repository `Contents: read and write`;
+leave every other optional permission disabled. Webhooks and user authorization
+are not required. Configure:
+
+- repository variable `RELEASE_APP_ID`: the numeric App ID;
+- repository secret `RELEASE_APP_PRIVATE_KEY`: the complete generated PEM key.
+
+Protect `dev` with an active branch ruleset that retains the normal pull request,
+one approving review, four CLI quality checks, deletion protection, and force
+push protection. Add `ViceMe CLI Release Bot` and the organization-admin role to
+the bypass list with `Always allow`; the latter preserves the legacy rule's
+existing `enforce_admins: false` behavior. Do not leave the legacy
+branch-protection rule active beside the ruleset because it cannot recognize the
+ruleset's App bypass.
+
+The App installation token is scoped to the current repository and
+`Contents: write`, expires after at most one hour, and is revoked automatically
+when the job finishes. The workflow still stages an explicit allowlist of
+generated files and validates the complete release before pushing. No
+maintainer PAT or Deploy Key is used.
+
+The general CLI quality workflow runs for pull requests, not branch pushes. A
+Release App push synchronizes the already-open `dev` to `main` PR, producing one
+set of required checks for the exact prepared commit without duplicate generic
+push and pull-request runs. The synchronize event may run release preparation a
+second time; that run is intentionally idempotent and produces no new commit.
 
 Configure npm trusted publishing for:
 
@@ -44,9 +73,23 @@ its first release, add a repository secret named `NPM_TOKEN` containing a
 granular automation token limited to `@viceme-ai/cli` publication. Remove that
 secret after the package exists and trusted publishing is confirmed.
 
-No release-specific environment variables are required. `GITHUB_TOKEN` is
-provided by Actions. `NPM_TOKEN` is optional and should only be retained when
-the npm account policy requires it.
+`GITHUB_TOKEN` is provided by Actions and is used only to maintain the Release
+PR. `RELEASE_APP_ID` and `RELEASE_APP_PRIVATE_KEY` authenticate the narrowly
+scoped Release App. `NPM_TOKEN` is optional and should only be retained when the
+npm account policy requires it.
+
+The release notification job uses the same repository secrets as Viceme Web,
+API, and Engine:
+
+- `FEISHU_RELEASE_WEBHOOK`: webhook for the release notification group;
+- `AI_API_KEY`: API key used to generate the release summary;
+- `AI_MODEL`: optional model override, defaulting to `deepseek-chat`;
+- `AI_BASE_URL`: optional OpenAI-compatible endpoint override, defaulting to
+  `https://api.deepseek.com/v1`.
+
+The notification runs only after the GitHub Release and npm publication have
+both succeeded, so a failed or incomplete release is not announced as
+successful.
 
 ## Recovery
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@viceme-ai/cli",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Install and run the Viceme CLI and Viceme Agent Skill",
   "type": "module",
   "bin": {
@@ -10,6 +10,7 @@
     "npm/bin/",
     "npm/lib/",
     "README.md",
+    "README.zh.md",
     "CHANGELOG.md",
     "docs/releasing.md"
   ],