npm run db:init          # 初始化 SQLite 数据库
npm run auth             # 打开浏览器扫码登录（首次或登录失效时）

npm run interactions:scan -- --type all --json    # 采集评论和点赞
npm run interactions:scan -- --type comment --json # 只采集评论通知
npm run interactions:scan -- --type like --json    # 只采集点赞通知
npm run actions:pending -- --type comment --json   # 查看待处理评论摘要
npm run actions:pending -- --json                  # 查看全部待处理互动

# 步骤 0：评论决策（Agent 内部完成，可参考 prompts/comment-reply-policy.md）
# 输出格式参见 prompts/comment-reply-policy.md → "决策输出格式"
 
# 步骤 1：创建回复候选（需携带决策结果）
npm run comments:prepare -- --event-id <id> --reply-text "<回复内容>" \
    --decision reply --risk-level low \
    --relevance relevant --decision-reason "<理由>" \
    --work-context-id <作品ID> --json

# 阶段 1: 候选分流（纯数据，不进主页）
npm run actions:plan -- --json       # 从 new 事件生成 replyCommentCandidates + visitWorkCandidates
 
# 阶段 2 (phase3): 主页发现 + 点赞检查（浏览器进入主页/视频页）
npm run visits:discover -- --json --max-items 5   # 进入好友主页找最新作品，检查点赞状态
 
# 阶段 3 (phase4): 待审核回访候选预览（与 visits:discover 同样进浏览器，仅输出未点赞候选 + 评论草稿）
npm run visits:review -- --json --max-items 5    # 输出 reviewCandidates，包含 commentDrafts
 
# 阶段 4 (phase5): 现场审核模式（交互式终端，逐条选择 + 执行）
npm run visits:live-review -- --max-items 5                    # dry-run 模式：选择草稿仅预览
npm run visits:live-review -- --execute --max-items 5          # execute 模式：选择草稿后立即点赞+评论
 
# 阶段 5: 真实执行（MVP 阶段硬阻断）
npm run likes:reciprocate -- --execute   # FEATURE_DISABLED

{
  "replyMode": "agent_generated_review_required",
  "riskLevel": "medium",
  "autoExecuteAllowed": false
}

{
  "replyMode": "auto_simple",
  "riskLevel": "low",
  "autoExecuteAllowed": false
}

{
  "generatedCommentCandidates": [
    {
      "text": "这个主题挺温柔的～",
      "commentCategory": "contextual_praise",
      "replyMode": "agent_generated_review_required",
      "riskLevel": "medium",
      "reason": "基于作品标题和话题生成",
      "sourceSignals": ["targetWorkTitle", "hashtags"],
      "autoExecuteAllowed": false
    }
  ]
}

{
  "generatedCommentCandidates": [
    {
      "text": "内容不错",
      "commentCategory": "generic_support",
      "replyMode": "auto_simple",
      "riskLevel": "low",
      "reason": "作品上下文不足，使用固定低风险模板",
      "sourceSignals": ["fallback_template"],
      "autoExecuteAllowed": false
    }
  ]
}

re-check like state
  ├── already_liked → skipped，不评论
  ├── not_liked → 点赞 + 评论
  └── unknown → blocked，不执行

{
  "selectedCommentText": "这个主题挺温柔的～",
  "commentCategory": "contextual_praise",
  "replyMode": "agent_generated_review_required",
  "riskLevel": "medium",
  "manualReviewMethod": "user_selected_agent_comment",
  "autoExecuteAllowed": false,
  "actionResults": {
    "like": "confirmed",
    "comment": "confirmed"
  }
}

{
  "actionResults": {
    "like": "confirmed",
    "comment": "unconfirmed",
    "commentReason": "comment_not_confirmed"
  }
}

npm run likes:plan -- --json       # 旧版浏览器回访计划（不推荐）
npm run visits:plan -- --json       # 旧版统一回访计划（不推荐）

用户请求查看评论
  ↓
npm run interactions:scan -- --type comment --json
  ↓
npm run actions:pending -- --type comment --json
  ↓
Skill 展示待处理评论摘要（昵称、作品、评论内容、当前状态）
  ↓
用户指定回复某条评论："给第 N 条拟回复：xxx"
  ↓
npm run comments:prepare -- --event-id <id> --reply-text "xxx" \
    --decision reply --risk-level low \
    --relevance relevant --decision-reason "<理由>" \
    --work-context-id <作品ID> --json
  ↓
Skill 展示预览：目标用户 / 作品 / 原评论 / 回复文本 / 决策 / 风险 / 相关性 / 作品上下文
  ↓
用户说 "确认"
  ↓
npm run actions:approve -- --action-id <id> --json
  ↓
npm run comments:execute -- --action-id <id> --dry-run --json
  ↓
dry-run 成功 → 告知用户定位成功（原评论已找到，回复框已打开）
dry-run 失败 → 报告 blocked，停止
  ↓
用户说 "发送"
  ↓
npm run actions:confirm-execute -- --action-id <id> --json
  ↓
npm run comments:execute -- --action-id <id> --execute --max-items 1 --json
  ↓
成功 → 告知用户已发送 + 审计记录已保存
失败 → 报告原因 + 证据路径

阶段 1: 候选分流 (actions:plan)
  用户请求查看好友回访候选
    ↓
  npm run actions:plan -- --json
    ↓
  Skill 展示分流结果：
    - replyCommentCandidates（评论候选回复）
    - visitWorkCandidates（好友回访候选，按 actorProfileKey 合并）
    - skipped（不进入候选的原因）
 
阶段 2: 主页发现 (visits:discover, phase3)
  用户说 "进入主页看看"
    ↓
  npm run visits:discover -- --json --max-items 5
    ↓
  对每个 visitWorkCandidate（仅 friend/mutual）：
    → page.goto(actorProfileUrl)
    → findLatestNonPinnedVideo
    → navigateToVideo
    → checkLikeState
    ↓
  输出 visitDiscoveries：
    - pending_review: 未点赞 → plannedActions=["like_work","comment_work"], executeAllowed=false
    - skipped: 已点赞 → reason="already_liked_skip_comment", plannedActions=[]
    - blocked: 无法确认 → reason 说明原因 (no_actor_profile_url / LIKE_STATE_UNKNOWN / ...)
 
阶段 3: 待审核候选 (visits:review, phase4)
  用户说 "看看哪些需要回复"、"生成回访审核列表"
    ↓
  npm run visits:review -- --json --max-items 5
    ↓
  复用 visits:discover 的浏览器流程（进入主页→找作品→检查点赞）
    ↓
  仅输出 pending_review 候选，每条附带 3 条评论草稿
    ↓
  输出 reviewCandidates（selectedCommentDraft=null, executeAllowed=false）
 
阶段 4: 现场审核 (visits:live-review, phase5)
  用户说 "逐条审核回访候选"、"现场确认回访"
    ↓
  三种评论模式：--comment-mode local|agent|skill（默认 skill）
    ↓
  local:  npm run visits:live-review -- --comment-mode local --execute --max-items 5
  agent:  npm run visits:live-review -- --comment-mode agent --max-items 5  (当前 FEATURE_DISABLED)
  skill:  npm run visits:live-review -- --comment-mode skill --json --max-items 1
    ↓
  local 模式：提取上下文 → generateVisitCommentCandidates → 展示 1/2/3 → 用户选择 → 执行
  agent 模式：预留 LLM 接口，当前 FEATURE_DISABLED
  skill 模式：提取上下文 → 输出 needsAgentComment + commentContext + constraints → 外部 Agent 生成评论
  skill 执行：npm run visits:live-review -- --selected-comment-text "xxx" --execute --max-items 1
    ↓
  选择或传入 --selected-comment-text 即代表人工审核通过当前条，不需要 YES
  skill + selected-comment-text 时必须 --max-items 1，一条评论只对应一个作品
  执行前当前页 re-check like state
    ↓
  输出 reviewCandidates（含 generatedCommentCandidates/needsAgentComment/commentContext/constraints/selectedCommentText 等）
 
阶段 5: 旧版真实执行保留 (likes:reciprocate, MVP 硬阻断)
  用户说 "给这个候选点赞"
    ↓
  npm run likes:reciprocate -- --execute ...
    ↓
  FEATURE_DISABLED（代码层硬阻断）