soia-env-claude-cli-install
安装和验证独立的 Anthropic Claude Code CLI（命令 claude）。Agent 负责终端操作；客户只需说明目标，并在官方浏览器或系统授权界面完成登录。
客户可读说明
这个技能可以做什么
| 客户想要 | 技能会做 | 客户能看到 |
|---|---|---|
| 安装 Claude Code | 检查系统和已有来源，使用官方用户级渠道安装 | 当前版本、来源、安装目录和验证结果 |
| 检查或更新 | 比较当前版与官方最新版；明确授权后沿原来源更新 | “无需更新”“可更新，未执行”或“已更新” |
| 登录 Claude | 启动 claude 官方登录流程 |
浏览器授权步骤，不显示凭据 |
| 命令不可用 | 检查 PATH、重复安装和 claude doctor |
阻塞原因与安全修复方案 |
客户如何使用
- 客户直接说“帮我安装 Claude Code CLI”；不要求客户复制终端命令。
- Agent 先执行只读检查并展示计划。客户的安装请求只授权安装缺失的 CLI，不授权更新已有版本。
- 只说“更新 Claude”时先显示两个版本并询问是否更新到最新；只有“更新到最新版本”等明确表述才调用更新器。
- 需要登录时 Agent 启动流程，客户只在 Anthropic 官方页面点击授权；不得让客户把授权码、API key 或密码发到聊天中。
- 安装、更新和登录后分别验证独立 CLI 的版本、帮助命令、诊断结果和登录状态。
首次登录与真实配置验证
配置文件目录只显示候选目录；技能必须同时读取config_status和config_file_status，不能把默认路径当成“已配置”。- 如果
~/.claude或settings.json尚未创建，Agent 在客户选定的项目中启动claude，由 Claude Code 展示官方登录选项；客户只在 Anthropic 官方页面或 Claude 官方应用完成授权。 - 如果客户选择 Anthropic API 方式，客户自行在 Anthropic Console 创建并保管 API key；Agent 只检查“存在/可认证”的结果，不接收、不回显密钥。
- 登录完成后重新运行
claude doctor和技能检查脚本；没有完成浏览器授权时，处理结果必须写“等待首次登录”，不能写“运行正常”。
依赖与安装
| 依赖 | 类型 | 缺失时怎么处理 |
|---|---|---|
| macOS、Linux 或 Windows | 强依赖 | 只使用官方文档支持的系统和架构 |
| Node.js/npm | npm 渠道依赖 | 官方独立安装不需要；选择 npm 时才调用 soia-env-node-install |
| 网络诊断 | 可选前置 | 官方站点失败时调用 soia-env-network-diagnose，不自动修改网络 |
| Anthropic 账号 | 登录依赖 | 客户在官方浏览器完成授权，Agent 不读取凭据 |
官方来源、包名、配置和自动更新事实见 official-sources.md。
国内网络环境提示：npm 渠道安装超时、下载失败时，可先切换 npmmirror 国内镜像源再重试，完成后按需切回官方源；最新版查询走 npm 官方 registry，受限网络下如实写「未取得」，不猜测：
npm config set registry https://registry.npmmirror.com # 切国内镜像
npm config set registry https://registry.npmjs.org # 切回官方源
标准流程
- 执行
python3 scripts/inspect_cli.py --json，只读取得独立命令、当前版本、实际路径、安装方式、配置目录以及配置目录/文件是否真实存在。 - 执行
python3 scripts/check_latest.py --json，从 npm 官方发布元数据取得最新版；失败时写“未取得”，不猜测。 - 已安装且可运行：
当前状态始终写“已安装”。没有最新版授权就停止，不重复安装、不更新。 - 未安装：优先官方独立安装；客户选择 npm 时才使用
npm install -g @anthropic-ai/claude-code。安装网络脚本时先下载到系统临时目录、检查来源和内容，再执行本地副本；不直接执行网络响应。 - 更新到最新：官方独立来源使用
claude update；npm 来源使用npm install -g @anthropic-ai/claude-code@latest；Homebrew 来源先识别实际 cask，再沿该 cask 更新。不得顺便切换来源。 - 验证同一绝对路径的
--version、--help和doctor。登录状态不明时启动官方登录流程；登录由客户在浏览器完成。 - 重新执行两个检查脚本，以
scripts/render_status.py生成一行客户状态列表。
产品自动更新边界
- 本技能“默认不更新”是指 Agent 不调用安装器或更新器。Claude Code 产品自身可能启用自动更新，必须在状态说明中披露。
- 只读检查不得修改
autoUpdates、DISABLE_AUTOUPDATER或任何配置。 - 客户明确要求关闭或开启产品自动更新时，先展示影响，再按官方设置修改并复核；该配置授权不等于本次更新授权。
客户状态列表（强制）
回复必须以以下十列表格开头，只输出一行 Claude Code CLI：
| 技能 | 当前状态 | 当前版本 | 最新版本 | 运行状态 | 安装方式 | 安装目录 | 配置文件目录 | 更新时间 | 处理结果 |
|---|---|---|---|---|---|---|---|---|---|
| Claude Code CLI | <已安装/未安装/被阻塞> | <版本或未取得> | <版本或未取得> | <正常/异常/未验证> | <官方独立安装/Homebrew 安装/npm 全局安装/未取得> | <目录或未取得> | <目录或未取得> | <RFC3339-with-timezone> | <已安装/已是最新/可更新，未执行/等待确认是否更新到最新/已更新/被阻塞：原因> |
- 用户只问 Claude Code CLI 时，不增加 Node.js、npm、Codex、Claude 桌面产品或其他技能行。
更新时间必须在最终验证后生成；安装目录和配置目录优先显示~相对路径，避免暴露用户名。- 已更新后
当前状态仍写“已安装”，更新结果只放在处理结果。 - 发现多个
claude时汇报当前登录 shell 实际生效的副本，并提示冲突；不删除其他副本。 - 无法取得最新版时写“未取得”；不得用缓存、记忆或其他产品版本代替。
config_status=未创建或config_file_status=未创建时，处理结果写“等待首次登录/配置”，并给出启动命令和官方授权方式；不得只打印一个不存在的路径。
安装与更新的中间状态
真正改变机器时，为本次运行生成随机 run_id，在每个实际阶段立即调用 scripts/record_install_progress.py，并同步展示阶段列表。只读检查不创建记录。
checking → planning → [waiting_confirmation] → installing/updating → verifying → completed/failed/blocked
| 阶段 | 当前状态 | 更新时间 | 处理结果 |
|---|---|---|---|
| <检查/计划/等待确认/安装或更新/验证/完成或失败> | <进行中/等待/已完成/失败/被阻塞> | <RFC3339-with-timezone> | <脱敏结果> |
- 安装使用
--action install；更新使用--action update。 - 只有客户明确要求最新版时，更新阶段才能传
--customer-requested-latest；记录器会拒绝未授权更新。 - 记录只保存固定
result_code、阶段和时间，不保存命令全文、账号、token、响应正文或客户私有绝对路径。
权限与回滚
- 优先用户级安装，不默认使用
sudo。需要管理员权限、修改 shell profile、切换来源或覆盖现有命令时先展示计划并取得单独确认。 - 更新前记录旧版本和来源；失败时保留原安装，不自动卸载、降级、清理配置或关闭自动更新。
- 网络脚本和安装包只存于每次运行独立的系统临时目录，成功、失败或取消都清理。
私密信息与中间数据
- 登录凭据由 Claude 官方登录态或系统凭据库管理；不读取或复制
~/.claude中的凭据内容。 - 非秘密配置留在官方配置目录；SOIA 不另建密钥文件。
- 机器变更的脱敏阶段记录保存在用户 state 目录，默认按仓库存储规范轮转；只读流程默认不落盘。
- 不在仓库、普通配置、日志或回执中保存 API key、授权码、cookie、session、账号或私有路径。
日志与完成回执
最终回执包含固定十列表格、验证过的命令类别、是否需要浏览器授权，以及失败时可恢复的原版本。正常依赖不展开为额外行。
样例：一次真实检查
2026-08-08 在 macOS（arm64）真机执行标准流程第 1、2 步的实际结果（路径经 ~ 脱敏，数据逐字保留）：
inspect_cli.py --json 关键字段：
| 字段 | 实际值 |
|---|---|
| current_status | 已安装 |
| current_version | 2.1.226 |
| install_method | Homebrew 安装 |
| install_dir | /opt/homebrew/Caskroom/claude-code@latest/2.1.226 |
| config_status / config_file_status | 已创建 / 已存在 |
| runtime_status | 正常 |
check_latest.py --json：latest_version 2.1.226（source: npm）。
最终十列客户状态表（render_status.py 实际渲染）：
| 技能 | 当前状态 | 当前版本 | 最新版本 | 运行状态 | 安装方式 | 安装目录 | 配置文件目录 | 更新时间 | 处理结果 |
|---|---|---|---|---|---|---|---|---|---|
| Claude Code CLI | 已安装 | 2.1.226 | 2.1.226 | 正常 | Homebrew 安装 | /opt/homebrew/Caskroom/claude-code@latest/2.1.226 | ~/.claude | 2026-08-08T16:25:10+08:00 | 已是最新 |
真实细节一则：这台机器当天 14:40 检查时版本还是 2.1.224，16:25 已是 2.1.226——Homebrew claude-code@latest 通道的产品自动更新在工作，这正是「产品自动更新边界」一节要求必须披露的情形。
不负责什么（能力边界）
- 不代客户完成登录与授权：浏览器授权、验证码、API key 创建都由客户在 Anthropic 官方页面完成；不读取、不接收、不回显任何凭据
- 默认不更新已装版本：「帮我安装」只授权装缺失的；更新需要「更新到最新版本」级别的明确表述
- 不动系统：不默认
sudo，不改 shell profile 与 PATH，不卸载或清理机器上的其他claude副本（发现多副本只汇报冲突） - 不负责 Claude 桌面应用与账号计费：只管 CLI 的安装、检查、更新与登录引导
前向测试
用临时 fake claude 覆盖未安装、已安装、版本异常和 PATH 多副本；mock npm 最新版响应；验证十列渲染、~ 路径脱敏、默认不更新，以及没有明确最新版授权时记录器拒绝 updating。
装整个域（Claude Code 与 Codex 共用同一份域插件）：
claude plugin marketplace add soia-team/soia-open-skills
claude plugin install soia-env@soia
只装这一个技能：
npx skills add soia-team/soia-open-env-skills -g -a '*' -s soia-env-claude-cli-install -y
WorkBuddy 的装载单位是角色化专家而不是插件，npx skills add -a '*' 覆盖不到它，需要单独安装，见 docs/install/workbuddy.md。
