watcha-cli 0.1.0

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "watcha-cli",
+  "version": "0.1.0",
+  "description": "观猹 (watcha.cn) 命令行客户端：搜产品、读猹评、AI 搜索、Markdown 发布、产品方自助；人和 AI agent 共用，非 TTY 默认 JSON，随包附带 Agent Skill",
+  "keywords": [
+    "watcha",
+    "观猹",
+    "猹评",
+    "cli",
+    "command-line",
+    "ai-agent",
+    "agent-skills",
+    "claude-code",
+    "codex",
+    "ai-products",
+    "reviews",
+    "community",
+    "markdown",
+    "prosemirror"
+  ],
+  "homepage": "https://watcha.cn",
+  "bugs": {
+    "email": "support@watcha.cn"
+  },
+  "author": "观猹 (https://watcha.cn)",
+  "license": "SEE LICENSE IN LICENSE",
+  "type": "module",
+  "bin": {
+    "watcha": "./bin/watcha.js"
+  },
+  "files": [
+    "bin",
+    "dist/index.js",
+    "skills",
+    "README.md",
+    "LICENSE",
+    "THIRD-PARTY-NOTICES.txt"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "dev": "tsx src/index.ts",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "test:contract": "WATCHA_CONTRACT_TEST=1 vitest run test/contract",
+    "prepack": "pnpm build"
+  },
+  "devDependencies": {
+    "@types/mdast": "^4.0.4",
+    "@types/node": "^26.2.0",
+    "commander": "^15.0.0",
+    "esbuild": "^0.28.2",
+    "mdast-util-from-markdown": "^2.0.3",
+    "tsx": "^4.23.12",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.11"
+  },
+  "optionalDependencies": {
+    "@napi-rs/keyring": "^1.3.0"
+  }
+}

package/skills/watcha/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: watcha
+description: 用 watcha CLI 逛观猹（watcha.cn，中文 AI 产品评价社区）：搜产品/猹评/帖子、AI 搜索问口碑、看榜单与活动、点赞收藏关注，以及在用户审阅确认后用 Markdown 发帖/发猹评/回复/投反馈、给自己的产品生成徽章与口碑统计。触发词：观猹、watcha、猹评、猹馆、AI 产品口碑、这个 AI 工具评价怎么样。Use when the user mentions watcha.cn / 观猹, asks what Chinese users think of an AI product, wants community reviews or reputation data for an AI tool, or wants to search or post on the Watcha community.
+license: SEE LICENSE IN LICENSE
+compatibility: Requires the watcha CLI on PATH (npm i -g watcha-cli, Node >= 22) and network access to watcha.cn
+metadata:
+  help: "watcha --help"
+  schema: "watcha schema --json"
+allowed-tools: Bash(watcha *)
+---
+
+# watcha CLI
+
+观猹是一个中文 AI 产品评价社区：用户给 AI 产品写「猹评」（带推荐/不推荐表态的评价，只有通过晋级考试的「观猹员」能发），在「猹馆」发帖讨论，产品库叫「图鉴」。`watcha` 是它的命令行客户端，**非 TTY 下默认输出 JSON**，专为 agent 调用设计。
+
+## 先读这两条
+
+```bash
+watcha schema --json      # 全部命令、参数、全局选项、输出契约、退出码、环境变量，一次读完；requires_yes 标出哪些是写操作
+watcha auth status        # 有没有登录、能不能发猹评（这条以退出码 0 报告状态，是否登录看 data.logged_in）
+```
+
+## 输出契约（判成功只看这个）
+
+- 成功：stdout `{"ok":true,"data":...,"meta"?:{...}}`，退出码 0
+- 失败：stderr `{"ok":false,"error":{"type","code"?,"status"?,"message","hint"?,"details"?}}`，退出码非 0。拼错命令名、缺参数、裸跑分组命令（如 `watcha product`）同样是这个信封、退出码 3
+- **不要用 data 里的任何字段判断成败**（唯一例外是 `auth status` 的 `data.logged_in`）；`error.hint` 里写了下一步该做什么，照做即可
+- 退出码：0 成功 · 1 通用 · 2 未登录 · 3 参数/内容不合法 · 4 需要确认 · 5 限流 · 6 需要去网页过验证码 · 7 网络 · 8 无权限 · 9 不存在
+- `--dry-run`：写命令不发请求，stdout 是 `{"ok":true,"data":{"dry_run":true,"request":{method,url,headers,body}}}`（Authorization 已脱敏）。注意未登录时会先拿到退出码 2，`--dry-run` 不能绕过登录
+- 列表命令：`--limit 1-100`、`--skip N` 或 `--page N`；翻页只看 `meta.has_more`（多数端点不给 `total`，有才出现；末页刚好满页时可能多翻一次空页）。`--format ndjson` 一行一条
+- 只在 json / ndjson 下有 JSON 信封；`--format pretty|table` 是给人看的，错误也是人话文本。非 TTY 默认就是 json，不要手动切 pretty
+- 进度提示全部走 stderr，stdout 只有数据
+
+## 登录
+
+读操作（搜索、产品、猹评、帖子、榜单、活动、用户主页）**不需要登录**。AI 搜索、互动、发布需要。
+
+```bash
+watcha auth login                        # 默认：微信小程序码，终端显示或弹出图片，用户用手机微信扫
+watcha auth login --sms --phone 138xxxx  # 短信验证码（交互式输码；非交互要同时带 --code）
+watcha auth login --refresh-token <jwt>  # 导入浏览器登录态：watcha.cn → DevTools → Local Storage → watcha.refreshToken
+WATCHA_REFRESH_TOKEN=<jwt> watcha ...    # CI/agent：环境变量，不落盘
+watcha auth logout                       # 释放登录槽位
+```
+
+登录是给人做的动作：agent 遇到退出码 2 时，把 `error.hint` 原样告诉用户，让用户自己完成登录，不要替用户猜验证码。**观猹每个账号最多 5 个登录态（Web/App/CLI 共用，按最久未用踢出）**，不要反复登录。遇到退出码 6（验证码）同样交给用户去浏览器处理。
+
+## 常见任务
+
+```bash
+# 找产品 / 看口碑
+watcha search "做 PPT 的 AI"                          # 混排搜索：产品/猹评/帖子/用户
+watcha search "AI 搜索" --domain product --score-gte 8 --order-by score:desc
+watcha product show claude-code                     # 详情（id 或 slug 都行）
+watcha product reviews claude-code --limit 20       # 猹评，带 👍/👎 表态
+watcha product posts claude-code                    # 相关帖子
+watcha review show 27222 && watcha review replies 27222 --all
+
+# 让观猹的 AI 基于社区内容回答（需登录，每分钟 2 次，一次约 1-2 分钟）
+watcha ask "Claude Code 和 Codex 哪个更适合写 Swift" --json   # 结束后一次性给 content/tool_calls
+watcha ask "..." --format ndjson                              # 逐帧
+watcha ask --resume <sessionId> "x"                           # 续传/回放
+# 被 Claude Code / Codex / Cursor / OpenClaw 等 agent 调用且请求已被服务端接受时，ask 会把实时视图开到用户终端的新窗口
+# （成功返回里 viewer.opened 为 true；流中途出错时在 error.details 里）。请告诉用户"回答正在新窗口里实时显示"；
+# 不要为了让用户看到过程而改用 ndjson 刷屏。30 秒内只会自动开一次窗，CI 里不开；用户不想弹窗就加 --no-watch
+
+# 逛
+watcha post list --limit 20 / watcha post show 13431 / watcha post floors 13431
+watcha topic hot / watcha topic posts 44
+watcha rank week_product_hot_reviewed --top 10      # 榜单 key 用 watcha rank 列出
+watcha activity list --city 杭州 / watcha activity show <slug>
+watcha user show 10094883 / watcha user reviews 10094883
+watcha feed --limit 10
+
+# 轻互动（需登录；立即生效、对方可见，--undo 是另一次写操作而不是撤销）
+watcha like review 27222 --yes / watcha like post 13431 --undo --yes
+watcha favorite post 13431 --yes / watcha follow 10094883 --yes / watcha react post 13431 🎉 --yes
+```
+
+点赞、收藏、关注、表情、投票、订阅、标记全部已读都是写操作：**只在用户明确要求时做，做之前说一句要做什么**。非交互环境不带 `--yes` 会返回退出码 4；不要替用户「顺手」点赞或关注。
+
+## 发布（必须先给用户看，再加 --yes）
+
+```bash
+watcha draft preview --md post.md        # 本地转换 + 校验，零请求：看标题宽度、正文宽度、图片、问题清单
+watcha post create --md post.md --yes [--topic 44,53] [--product claude-code] [--image a.png b.png]
+watcha review create --product claude-code --vote good --md review.md --yes
+watcha reply review 27222 --text "同感，尤其是…" --yes
+watcha reply post 13431 --parent 5678 --md reply.md --yes
+watcha feedback "描述问题或建议" --type bug --yes     # 投到观猹站内反馈（type: bug | feature | content | other）
+```
+
+规则（CLI 内置，不要试图绕过）：
+
+- 写操作没带 `--yes` 时返回退出码 4 `confirmation_required`。**agent 的正确流程是：先 `draft preview`，把标题和正文摘要展示给用户，用户明确同意后再在原命令末尾加 `--yes`**。不要在用户没看过内容时自行加 `--yes`
+- 只做用户要求的那一条。CLI 没有批量/循环发布命令，60 秒内第 3 条会被本地拦下（后端限 2 条/分钟，超限会触发运营告警）
+- 发猹评需要观猹员资格（`auth status` 的 `can_create_review`）；没有就告诉用户去 watcha.cn/exam 考试或用邀请码，**不要**改发帖子绕过
+- 正文是 Markdown（CommonMark，`~~删除线~~` 不会解析）：支持标题、列表、引用、代码块、加粗/斜体/行内代码/链接、图片，标题里的图片会拆成独立的图；帖子首行 `# 标题` 自动当标题（≤32 个汉字宽度，半角算 0.5）；猹评正文 ≥15 个汉字宽度；Markdown 里的本地图片和外链图片都会自动上传到观猹的对象存储
+- 发布后 CLI 会回查状态：`status 2` 表示被 AI 审核折叠（别人看不到），把原因告诉用户；`status 0` 是审核中
+- 如果内容主要由 AI 生成，加 `--ai-assisted` 在文末追加披露行；是否加由用户决定
+
+## 产品方（自己的产品）
+
+```bash
+watcha product mine                                   # 我提交的 / 我是成员的产品
+watcha product badge claude-code --theme dark         # 可贴 GitHub README 的徽章 Markdown（--as html|url）
+watcha product stats claude-code --weeks 12           # 口碑统计：推荐比、按周趋势、最近猹评
+watcha product launch claude-code --title "v1.2" --md changelog.md --yes
+watcha product update claude-code --slogan "..." --yes
+```
+
+## 其他
+
+- `watcha api GET /products --query limit=3`：没有对应命令时直接调 `/api/v2` 端点；路径不对时 4xx 的 `error.message` 会说明，先用 GET 试探，不要用它绕过发布护栏
+- `--dry-run`：写操作只打印将发送的请求（形状见上面的输出契约）
+- 在 Codex 里遇到退出码 7「沙箱已禁用网络访问」：Codex 默认断网，把 `error.hint` 里的放开方式告诉用户，不要反复重试
+- `--profile <name>` / `WATCHA_PROFILE`：多账号。**除非用户明确要求，不要切换或删除 profile**
+- 榜单、活动、话题等字段由后端决定，CLI 原样透传 `data`；pretty 模式只是人类可读摘要