hpreview

html-preview 平台 agent CLI —— 凭个人访问令牌（PAT）抓取/管理平台内容，喂给下游 LLM 与管道。

设计承 lark-cli：默认 JSON 输出、--dry-run 预检、统一分页、结构化错误带可执行 hint、稳定退出码、PAT 永不进 argv。

快速开始

# 1. 安装
npm i -g @paylinker/hpreview   # 或一次性：npx @paylinker/hpreview@latest <cmd>
#（命令名仍是 hpreview / hpv，与包名无关）

# 2. 配置 PAT（平台「设置」页生成 hp_...）
hpreview login               # 交互式隐藏输入；或管道：echo $HPV_TOKEN | hpreview login --stdin
hpreview doctor              # 健康检查（配置 + 连通 + 身份）

# 3. 抓内容（核心）
hpreview ls | jq '.[].id'
hpreview content <id> --text | llm summarize      # 取纯文本喂下游 LLM
hpreview content <slug> -o page.html              # 落盘渲染 HTML
hpreview content <id> | grep -i 关键词             # 管道

全局 flags（所有命令，位置无关）

| flag | 说明 | |---|---| | --format json\|table\|csv\|pretty | 输出格式（默认 json，机器可读优先；table/csv 对人） | | --dry-run | 预检：打印将发出的请求规格，不执行 | | --yes / -y | 跳过危险操作确认 | | -o, --output <path> | 输出到文件 |

全局 flag 可放命令前或后：--dry-run ls 与 ls --dry-run 等价。

命令

鉴权（scope: read）

| 命令 | 说明 | |---|---| | login [--stdin] [--api <base>] [--no-check] | 配置 PAT。TTY 交互隐藏输入；--stdin 管道读；默认验证（调 whoami，失败不保存） | | logout | 清除本地 PAT | | whoami | 验 PAT 并回显身份 {userId,teamId,departmentId,role,patScope} | | doctor | 健康检查：配置状态 + 连通性 + 身份 |

读 —— 内容抓取，核心（scope: read）

| 命令 | 说明 | |---|---| | ls [--q <kw>] [--folder <id\|all\|uncategorized>] [--page-all] [--page-size <n>] | 列本人文件。--page-all 自动翻页 | | get <id\|slug> | 取文件元数据 | | content <id\|slug> [--text] [-o file] 🔑 | 抓取文件真实内容（渲染 HTML，含水印；--text 剥标签喂 LLM；默认 stdout 流式） | | share-link <id\|slug> | 取文件短链 |

写（须 read-write PAT；危险操作默认确认）

| 命令 | 说明 | |---|---| | upload <file> [--name N] | 上传 HTML/MD（直传握手） | | rm <id\|slug> | 软删文件（--yes 跳过确认） | | mv <id\|slug> [--folder <uuid\|uncategorized> \| --department \| --remove-department] | 移动文件 | | share <id\|slug> [--visibility \| --password \| --expires \| --revoke] | 分享门控管理（--revoke 危险） | | folders ls\|create <name>\|rename <id> <name>\|rm <id> | 个人文件夹管理 |

兜底 / 自省

| 命令 | 说明 | |---|---| | api <method> <path> [--params <json>] [--data <json>] | 兜底调用任意端点（逃生口） | | commands | 打印命令注册表（agent 自描述：每命令 I/O + scope + 退出码） |

PAT scope：默认 read；写命令需创建时选 read-write（服务端强制）。

退出码（机器可读）

0=ok / 1=error / 2=auth(401·403) / 3=not_found(404) / 4=bad_request(400·409·422) / 5=rate_limited(429·413)。

输出

• 默认 JSON（stdout 仅数据，可管道）；错误走 stderr，JSON 模式结构化 {ok:false, error:{type, message, hint, status?}}。
• --format table 列对齐表格；csv 表格导出；pretty 缩进 key:value。
• content 命令 --raw（默认）直接流式输出（不受 format 影响，二进制语义）。

错误（结构化，可自愈）

{ "ok": false, "error": { "type": "auth", "message": "未配置 PAT",
  "hint": "运行: hpreview login    （或设环境变量 HPV_TOKEN）", "status": 401 } }

agent 据 type/hint 自愈（如 auth → 调 login 重试），无需解析文本。

配置

| 来源 | 说明 | |---|---| | 环境变量 HPV_TOKEN / HPV_API_BASE | 优先级最高；适合 CI / 容器化 agent（无需写盘） | | ~/.config/hpreview/config.json | login 写入：{ apiBase, token }（XDG_CONFIG_HOME 可覆盖目录） | | 默认 apiBase | https://sphtml.vercel.app（生产控制面） |

安全

• PAT 永不进 argv（进程列表可见）——login 走交互隐藏输入或 --stdin 管道。
• 三密钥（RENDER_TOKEN_SECRET / BLOB_READ_WRITE_TOKEN / SUPABASE_SERVICE_ROLE_KEY）永不进 CLI——服务端签 render token 取内容，CLI 只收渲染原文。
• 内容抓取强制带 viewer 内部水印（保平台取证不变量）。
• PAT 明文仅创建时返回一次；secret 仅 bcrypt 哈希存储；可随时吊销。

开发

pnpm install
pnpm --filter hpreview build       # tsup → dist/cli.js
pnpm --filter hpreview test        # vitest（context/format/client/config/exit/html-to-text）
pnpm --filter hpreview typecheck