# 花生壳CLI 安装与首次使用

## 功能概览（本 CLI 能做什么）
- **文件托管**：把本地文件/静态目录（构建产物、HTML、PDF 等）发布为公网可访问链接
- **内网穿透**：把本地 http 服务（Web 应用/API/WebSocket 等）暴露到公网
- **一键部署**：构建前端项目并自动上传发布
- **长期运行**：需要稳定长连/后台保活时，安装本机引擎并关联账号使用

本 CLI 面向 AI agent 使用：业务命令都要求在向导建立画像后执行（见下方红线）。向导会读取当前运行环境并直接返回「下一步该执行的推荐命令」，按推荐命令执行即可完成发布，无需预先掌握命令细节。

## 红线（2 条，画像与协议层）
- 执行任何 hsk-cli **业务命令**前，必须先跑 `hsk-cli context wizard --format json` 建立画像（wizard 自身除外）
- 所有命令一律 `--format json`（stdout 首行即 JSON，过程日志在 stderr；wizard 回填同样带 `--format json`）

## 执行协议（建立画像）
1. 安装：`npm install -g @aweray/hsk-cli`（不便全局时用 `npx @aweray/hsk-cli`）
2. 版本检测：`npm outdated -g @aweray/hsk-cli` → 有新版 `npm update -g`；再 `hsk-cli update`
   （沙盒无法联网则跳过升级）
3. 建立服务画像：
   a. `hsk-cli context wizard --format json` → 读 `data.known`（已获取）与 `data.ask`（仍需提供）
   b. `data.ask` 非空 → 逐项按 `options` 作答，一次性回填：
      `echo '<answers>' | hsk-cli context wizard --stdin --format json`
      （`<answers>` 结构：`{"schema_version":"<取 data.schema_version 或省略>","answers":[{"field":"<字段>","value":"<options 内取值>"}]}`；wizard 输出 `data.answer_template` 已预填当前版本与全部缺省字段，直接填 `value` 即可；不接受平铺字段）
   c. 回填后一切以 `data.recommendations`（下一步推荐命令）为准；
      会话级字段用 `--context '{"field":"value"}'` 按次传递（值须在问题集 options 内）
4. 业务命令返回 `needs_input`：按 `needs[].resolution_order`
   （① agent_context ② user_handoff ③ alternative）处置后重跑原命令

## 异常兜底
- wizard 不可用（离线/异常）：先重试 `hsk-cli context wizard --format json`；仍不可用再读本地详细参考 `~/.hsk/AGENTS.md`（不存在 = CLI 未装好，回到第 1 步）
- `CONTEXT_INVALID_*`：重跑 `context wizard` 取最新问题集，按 `options` 重新提交