@whobot/cli-test 0.0.0-stage → 0.0.2

package/LICENSE

@@ -0,0 +1,13 @@
+Copyright 2026 Whobot
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -1,3 +1,56 @@
-# Temporary Holding Version
+# @whobot/cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+npm 管理的 Whobot CLI：全局命令 `whobot` 是 JS 启动器，相对自身定位包内 Go 二进制并转发参数、stdin、stdout、stderr 与退出码。日常运行需要 Node >=20；业务仍由原生 CLI 执行。
+
+## 安装
+
+```bash
+npx --yes @whobot/cli@latest install
+```
+
+`postinstall` 按 OS/CPU 从 OSS 下载对应版本 Go 制品，校验 size 与 SHA-256 后放入包内 `bin/whobot` 或 `bin/whobot.exe`。安装生命周期未下载时，第一次业务命令会补齐当前 npm 包版本；普通命令不会因发现新版本而自动升级。补齐日志写在 stderr，不进入业务 JSON stdout。
+
+本包**不内嵌**各平台二进制，只含启动器、安装逻辑、manifest bootstrap、许可证与说明。
+
+全局包已安装而当前 PATH 看不到 `whobot` 时，使用 npm prefix 解析出的全局入口绝对路径，仍经过 JS 启动器；不要枚举 CLI 数据目录下的 Go 文件。
+
+首次从 v1 升级到 v2 时，先从原渠道获取最新稳定版的具体版本，再执行升级提示中的固定版本安装命令，例如目标为 `2.0.0` 时：
+
+```bash
+npx --yes @whobot/cli@2.0.0 install
+```
+
+首次迁移不要运行旧的 `update apply`，也不要直接复用 `npx @whobot/cli@latest install` 或 `@intranet install`。已发布 v1 的全局程序可能软链接到同一标签的 npx 缓存；再次解析同标签可能在安装器启动前覆盖旧程序，使活动检查和原凭据端点校验失去依据。固定的新版本使用独立缓存入口，安装器先检查旧身份、原编译端点和活动通话，再替换程序。新安装的全局包与 npx 缓存分离。
+
+v2 后续更新：
+
+```bash
+whobot update
+# 确认后执行返回的 next.command，包含实际目标版本
+```
+
+更新走 npm，不向数据 Home/bin 写入程序文件。安装成功会核对 npm 注册、实际二进制版本与协议、命令入口；PATH 仍优先解析旧入口时明确失败。存在身份但原程序损坏、端点符号缺失或新旧 API Origin / OAuth Issuer 不同，必须先恢复原程序或使用原端点的发行，不会清空身份来绕过检查。
+
+CLI 软件安装完成后，还需要通过原平台或官方完整包更新 Skill，重载宿主或新建任务，再执行一次预检。安装器不覆盖宿主 Skill，也不将 CLI 完成当作联合升级完成。
+
+## 程序位置与数据目录
+
+程序文件由 npm 管理（包内 `bin/whobot`）。客户端安装身份使用 CLI 数据目录（`WHOBOT_AGENT_CLI_HOME` 或 `~/.whobot-cli`；主目录无法确定时为相对路径 `.whobot-cli`），不写入 npm 包目录，也不会在重装时被清空。Windows 不要求 `APPDATA`。
+
+## 校验
+
+SHA-256 用于核对下载内容与 manifest 一致，不声称提供公开签名或来源认证。
+
+- 只接受已知 `schemaVersion`、OS（darwin/linux/windows）与 arch（amd64/arm64）
+- 解压前核对 size 与 SHA-256
+- 拒绝路径穿越、重名、意外顶层文件、缺失 checksum、制品内脚本
+- 下载校验失败、包内文件无法执行或协议不兼容时明确失败，不解释成未安装，也不报告业务成功
+- 遵守 `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY`
+
+## 测试
+
+```bash
+bun test
+```
+
+发布人员在启用最低版本前，应对实际发行源执行仓库的 `bun deploy/check-upgrade-release.mjs latest`（内网使用 `intranet`），验证两项门槛可满足、完整 Skill 包和说明可取，以及隔离 npm/native 安装成功。配置、先制品后门槛的顺序与用户人工宿主清单见仓库 `docs/releases/skill-cli-v2-cutover.md`；检查通过只覆盖当前平台，不表示真实宿主已验收。