@coralai/sps-cli 0.65.17 → 0.65.19

package/skills/sps/references/operation-playbooks.md

@@ -0,0 +1,248 @@
+# SPS Operation Playbooks (v0.16+)
+
+## Playbook 0: First-time environment setup
+
+### Prerequisites
+- Node.js 18+ installed
+- npm configured with global prefix
+- Git configured with SSH access to GitLab
+- Claude Code or Codex CLI installed
+
+### Steps
+
+1. Install SPS CLI:
+   ```bash
+   npm install -g @coralai/sps-cli
+   sps --version   # Should show 0.18.0+
+   ```
+
+2. Run global setup wizard:
+   ```bash
+   sps setup
+   # Prompts for: GitLab URL/token, Plane URL/key/slug, Matrix (optional)
+   # Creates: ~/.coral/env (0600), ~/.coral/projects/
+   ```
+
+3. Load credentials:
+   ```bash
+   source ~/.coral/env
+   # Or add to ~/.bashrc: source ~/.coral/env
+   ```
+
+4. Verify:
+   ```bash
+   echo $GITLAB_URL    # Should show GitLab URL
+   echo $PLANE_URL     # Should show Plane URL
+   ls ~/.coral/profiles/    # Skill profiles installed
+   ls ~/.coral/projects/    # Should exist
+   sps status               # All projects overview
+   ```
+
+**Troubleshooting:**
+- `sps: command not found` → check `npm config get prefix`, add `<prefix>/bin` to PATH
+- `~/.coral/env` not created → run `sps setup --force`
+- Variables not loaded → run `source ~/.coral/env` in current shell
+
+---
+
+## Playbook 1: New project initialization
+
+1. Confirm configuration intent with Boss (required before any config writes)
+
+2. Clone business repo:
+   ```bash
+   git clone <repo-url> ~/projects/<project>/
+   ```
+
+3. Initialize SPS project:
+   ```bash
+   sps project init <project>
+   ```
+
+4. Edit configuration:
+   ```bash
+   vim ~/.coral/projects/<project>/conf
+   ```
+   Required fields:
+   - `PROJECT_NAME`, `PROJECT_DIR`
+   - `GITLAB_PROJECT`, `GITLAB_PROJECT_ID`, `GITLAB_MERGE_BRANCH`
+   - `PM_TOOL` (plane/trello/markdown)
+   - `WORKER_TOOL` (claude/codex), `MAX_CONCURRENT_WORKERS`
+   - If you want one tick cycle to fill all new worker slots, set `MAX_ACTIONS_PER_TICK` to the same launch budget
+
+   Concurrency change checklist:
+   - `MAX_CONCURRENT_WORKERS` controls the slot ceiling
+   - `MAX_ACTIONS_PER_TICK` controls how many workers one tick may launch
+   - Verify `sps status <project> --json` and `runtime/state.json` show the expected slot count after the change
+
+5. **If PM_TOOL=plane**: create 6 states in Plane, fill UUIDs:
+   ```bash
+   source ~/.coral/env
+   curl -s -H "X-API-Key: $PLANE_API_KEY" \
+     "$PLANE_URL/api/v1/workspaces/$PLANE_WORKSPACE_SLUG/projects/$PID/states/" \
+     | jq '.results[] | {name, id, group}'
+   ```
+   Fill: `PLANE_STATE_PLANNING`, `PLANE_STATE_BACKLOG`, `PLANE_STATE_TODO`, `PLANE_STATE_INPROGRESS`, `PLANE_STATE_QA`, `PLANE_STATE_DONE`
+
+6. Health check + auto-fix:
+   ```bash
+   sps doctor <project> --fix
+   # Creates: missing dirs, state.json, CLAUDE.md, AGENTS.md, .gitignore entries
+   ```
+
+7. (Optional) Customize worker rules:
+   ```bash
+   vim ~/projects/<project>/CLAUDE.md
+   # Add: coding standards, test requirements, architecture constraints
+   ```
+
+---
+
+## Playbook 2: Create and queue task cards
+
+```bash
+# Create cards (auto-adds AI-PIPELINE label, appends to pipeline_order.json)
+sps card add <project> "Implement user login" "JWT auth with refresh tokens"
+sps card add <project> "Add order API" "CRUD endpoints with pagination"
+sps card add <project> "Email notifications" "Order status change alerts"
+```
+
+### Add skill labels (v0.16+)
+
+In PM tool (Plane/Trello UI), add labels to cards:
+- `skill:react` — inject React/TS frontend expertise
+- `skill:typescript` — inject TypeScript strict mode
+- `skill:phaser` — inject Phaser game development
+- `skill:node` — inject Node.js backend expertise
+- Multiple composable: `skill:react` + `skill:testing`
+
+Or set project-wide default:
+```bash
+# In ~/.coral/projects/<project>/conf:
+export DEFAULT_WORKER_SKILLS="react,typescript"
+```
+
+### Add conflict domain labels
+
+```bash
+# In PM tool, add labels:
+# conflict:auth — cards touching auth module run serially
+# conflict:database — cards touching DB run serially
+```
+
+### Adjust execution order
+
+```bash
+cat ~/.coral/projects/<project>/pipeline_order.json
+# [24, 25, 26]
+# Edit to reorder: [26, 24, 25] ← moves #26 to front
+```
+
+---
+
+## Playbook 3: Start and manage pipeline
+
+### Standard startup
+
+```bash
+sps doctor <project> --fix                 # Pre-flight health check
+sps tick <project>                         # Start continuous pipeline
+# In separate terminal:
+sps worker dashboard <project>             # Monitor workers
+```
+
+### Multi-project
+
+```bash
+sps tick project-a project-b project-c     # One process, multiple projects
+sps worker dashboard                       # Cross-project dashboard
+```
+
+### Cron-based operation
+
+```bash
+sps tick <project> --json                  # Run with JSON output (for cron)
+# Or use generated wrapper:
+~/.coral/projects/<project>/batch_scheduler.sh
+```
+
+---
+
+## Playbook 4: Diagnose stuck workflow
+
+See [diagnostic-sequence.md](./diagnostic-sequence.md) for the full decision tree.
+
+Quick version:
+```bash
+sps doctor <project> --json                # Config OK?
+sps monitor tick <project> --json          # Anomalies?
+sps worker dashboard <project>             # Workers alive?
+sps pm scan <project>                      # Card states?
+```
+
+---
+
+## Playbook 5: Manual card recovery
+
+```bash
+# Move card to target state
+sps pm move <project> <seq> Todo
+sps pm comment <project> <seq> "Manual recovery: <reason>"
+
+# Force re-launch a card's worker
+sps worker launch <project> <seq>
+
+# Stop and restart pipeline
+sps stop <project>
+sps tick <project>
+```
+
+---
+
+## Playbook 6: Multi-project management
+
+```bash
+# Start (one process manages all)
+sps tick project-a project-b project-c
+
+# Monitor all workers
+sps worker dashboard
+
+# Check individual project health
+sps doctor project-a --json
+sps doctor project-b --json
+
+# Stop specific project
+sps stop project-a
+
+# Stop all
+sps stop project-a --all
+```
+
+Each project has fully isolated: context, providers, engines, lock, state. One project's failure does not affect others.
+
+Global resource control: `SPS_MANAGER_MAX_WORKERS=30` limits total workers across all projects.
+
+---
+
+## Playbook 7: Tick restart and Recovery (v0.16+)
+
+Worker processes survive tick exit (detached mode + fd redirect).
+
+On next `sps tick` startup:
+- Recovery scans `state.json` for active worker slots
+- PID alive → registers 5s polling to continue monitoring
+- PID dead → CompletionJudge evaluates → PostActions auto-execute (merge → PM → release)
+
+No manual cleanup needed. Recovery is fully automatic.
+
+```bash
+# If tick exited unexpectedly:
+sps tick <project>
+# Recovery module handles orphan workers automatically
+
+# If tick lock is stale:
+cat ~/.coral/projects/<project>/runtime/tick.lock
+kill -0 <pid> 2>/dev/null && echo "ALIVE" || echo "DEAD"
+# If dead: rm ~/.coral/projects/<project>/runtime/tick.lock
+```

package/skills/sps/references/preflight-and-setup.md

@@ -0,0 +1,85 @@
+# Pre-flight checks
+
+SPS 操作前的环境自检:CLI 安装、全局 env、项目目录、worker 工具。
+
+## 0. Pre-flight checks
+
+Before any SPS operation, verify the environment is ready.
+
+### 0.1 Check SPS CLI installation
+
+```bash
+# Check if sps is installed
+which sps
+# Expected: /home/<user>/.npm-global/bin/sps (or similar)
+
+# Check version
+sps --version
+# Expected: 0.58.0 or higher
+```
+
+**If not installed or outdated:**
+```bash
+npm install -g @coralai/sps-cli
+# Verify
+sps --version
+```
+
+**Minimum version requirement:** v0.58.0 (Harness mode + ACP SDK transport + Session Daemon)
+
+### 0.2 Check global environment configuration
+
+```bash
+# Check if ~/.coral/env exists
+test -f ~/.coral/env && echo "OK" || echo "MISSING — run: sps setup"
+
+# Verify key variables are set (source first)
+source ~/.coral/env
+
+# Required for GitLab (repo / merge / MR side):
+echo "GITLAB_URL=${GITLAB_URL:-(MISSING)}"
+echo "GITLAB_TOKEN=${GITLAB_TOKEN:+SET}"
+
+# Optional — Matrix notifications:
+echo "MATRIX_HOMESERVER=${MATRIX_HOMESERVER:-(not set)}"
+echo "MATRIX_ACCESS_TOKEN=${MATRIX_ACCESS_TOKEN:+SET}"
+```
+
+**If missing or incomplete**, guide user through setup:
+```bash
+sps setup
+# Interactive wizard: prompts for GitLab and Matrix credentials
+# Shows existing values as defaults — press Enter to keep current config
+# Creates ~/.coral/ directory structure
+# Creates ~/.coral/env with 0600 permissions
+# Installs bundled skills to ~/.coral/skills/<name>/SKILL.md
+# Installs the claude-agent-acp adapter globally (@agentclientprotocol/claude-agent-acp)
+```
+
+**After setup, user must `source ~/.coral/env`** or open a new shell for variables to take effect.
+
+### 0.3 Check project directory
+
+```bash
+# Verify ~/.coral/projects/ exists
+ls ~/.coral/projects/
+
+# Verify specific project is initialized
+ls ~/.coral/projects/<project>/conf
+```
+
+**If project not initialized**, see [Initialize a project](#1-initialize-a-project).
+
+### 0.4 Check worker tool
+
+The worker agent is **Claude only** (Codex/Gemini worker backends were removed in v0.38).
+
+```bash
+# Claude Code — the only supported worker agent
+which claude && claude --version
+
+# Claude auth: either a ~/.claude login, or ANTHROPIC_API_KEY in the environment
+echo "ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY:+SET}"
+```
+
+Note: tmux is no longer required. SPS uses ACP SDK transport (JSON-RPC over stdio) since v0.26.0.

package/skills/sps/references/skills.md

@@ -0,0 +1,62 @@
+# Worker skills
+
+Worker skills 的注入机制、prompt 组装顺序、管理命令、skill 结构与内置 skill 清单。
+
+## 5. Worker skills
+
+Skill-driven prompt injection. A card's skills (set via `sps card add … --skill`) load the matching skill definitions into the worker prompt.
+
+### How it works
+- Card skill `backend` → loads `~/.coral/skills/backend/SKILL.md` into the prompt
+- Recommended one skill per card — Agent 在建卡时根据任务类型自动判定
+- 如果卡片没有指定技能，fallback 到 `DEFAULT_WORKER_SKILLS` 配置
+- Skill 内容注入 Worker prompt（对 Claude Code worker 生效）
+
+### Prompt assembly order
+1. Skills (from the card's `--skill` values or DEFAULT_WORKER_SKILLS)
+2. Project Rules (CLAUDE.md)
+3. Project Knowledge (recent DECISIONS.md + CHANGELOG.md entries)
+4. Task Details (card description + execution steps)
+
+### Managing skills
+```bash
+sps skill list                 # List user-level skills + per-project link status
+sps skill add <name>           # Symlink a skill into the current project
+sps skill remove <name>        # Remove a skill from the current project
+sps skill sync [--force]       # bundled → ~/.coral/skills/, then → ~/.claude/skills/
+```
+
+New skills live at `~/.coral/skills/<name>/SKILL.md` (frontmatter: name + description). `sps setup` installs the bundled ones.
+
+### Skill structure (6 sections)
+每个 skill 遵循标准结构：
+1. **Role** — 角色定位、任务类型、交付物
+2. **Standards** — 编码/工作标准（命令式规则）
+3. **Architecture** — 目录结构、组织方式
+4. **Patterns** — 可复制的代码/模板示例
+5. **Testing** — 测试策略和覆盖率要求
+6. **Quality Metrics** — 可衡量的质量指标
+
+### Built-in skills
+
+**Task type skills** (按任务类型选择，推荐一张卡片一个):
+
+| Skill dir | `--skill` | Use case |
+|---------|-------|----------|
+| `architect/` | `architect` | 架构设计、技术方案、ADR、目录结构 |
+| `frontend/` | `frontend` | 前端 UI 组件、页面、样式、无障碍 |
+| `backend/` | `backend` | API 端点、数据库、服务端逻辑 |
+| `fullstack/` | `fullstack` | 全栈：DB + API + UI 一体化 |
+| `prototyper/` | `prototyper` | 快速原型 / MVP 验证 |
+| `reviewer/` | `reviewer` | 代码审查、质量优化 |
+| `security/` | `security` | 安全审计、漏洞修复 |
+| `writer/` | `writer` | README、API 文档、PRD |
+| `optimizer/` | `optimizer` | 性能/成本优化、Benchmark |
+| `senior/` | `senior` | 通用高质量实现（兜底） |
+
+**Language/framework skills** (特化场景):
+
+| Skill dir | `--skill` | Use case |
+|---------|-------|----------|
+| `typescript/` | `typescript` | TypeScript 严格模式规范 |
+| `phaser/` | `phaser` | Phaser 3 游戏开发 |

package/skills/sps/references/troubleshooting.md

@@ -0,0 +1,200 @@
+# Troubleshooting
+
+故障排查:诊断序列、常见问题与修复、手动恢复命令、实用检查命令。
+
+## 7. Troubleshooting
+
+### 7.1 Diagnostic sequence (always start here)
+
+```bash
+# Step 1: Global health check
+sps doctor <project> --json            # Config and infrastructure
+sps monitor tick <project> --json      # Anomaly detection
+sps worker dashboard <project>         # Worker live status
+
+# Step 2: Narrow down by stage
+sps scheduler tick <project> --json    # Card selection issues (Planning → Backlog)
+sps pipeline tick <project> --json     # Execution issues (Backlog → Todo → Inprogress)
+sps qa tick <project> --json           # Closeout issues (QA → merge → Done)
+
+# Step 3: Check ground truth
+sps pm scan <project>                  # PM backend state (business truth)
+cat ~/.coral/projects/<project>/runtime/state.json   # Runtime state (execution truth)
+cat ~/.coral/projects/<project>/pipeline_order.json  # Execution queue
+```
+
+**Decision rule**: Always read-only diagnosis first, then targeted fix. PM is business truth, runtime is execution truth — understand the gap before aligning.
+
+### 7.2 Common problems and fixes
+
+### SPS CLI not found
+```bash
+which sps
+# If missing:
+npm install -g @coralai/sps-cli
+# If installed but not in PATH, check npm global bin:
+npm config get prefix
+# Add <prefix>/bin to PATH
+```
+
+### `sps setup` prompts not saving
+```bash
+# Check file exists and permissions
+ls -la ~/.coral/env
+# Should be -rw------- (0600)
+# Re-run with force:
+sps setup --force
+```
+
+### Doctor reports missing fields
+```bash
+sps doctor <project> --json
+# Look for failed checks, then:
+sps doctor <project> --fix
+# Auto-creates missing dirs, state.json, CLAUDE.md
+```
+
+### Card stuck in Planning (not moving to Backlog)
+```bash
+sps scheduler tick <project> --json
+# Check: does card have AI-PIPELINE label?
+# Check: is card in pipeline_order.json?
+# Check: are there idle Worker slots?
+sps worker dashboard <project> --json
+# Check: CONFLICT_DEFAULT=serial and another card is active?
+```
+
+### Card stuck in Backlog/Todo (not launching Worker)
+```bash
+sps pipeline tick <project> --json
+# Check: MAX_ACTIONS_PER_TICK (default 1) — may need next tick cycle
+# Check: MAX_CONCURRENT_WORKERS and MAX_ACTIONS_PER_TICK in conf match Boss's expectation
+grep -E '^(MAX_CONCURRENT_WORKERS|MAX_ACTIONS_PER_TICK)=' ~/.coral/projects/<project>/conf
+# Check: Worker slots all occupied?
+sps worker dashboard <project> --json
+# Check: runtime slot count matches config
+cat ~/.coral/projects/<project>/runtime/state.json | jq '.workers | keys'
+# Check: worktree creation failed? (disk space, git issues)
+```
+
+### Card stuck in Inprogress (Worker finished but card didn't advance)
+```bash
+sps worker dashboard <project>          # Is worker still alive?
+sps pipeline tick <project> --json      # CompletionJudge result?
+
+# Manual checks:
+# 1. Did worker push code?
+cd ~/.coral/worktrees/card-<seq> && git log --oneline -5
+
+# 2. Is branch merged to target?
+git merge-base --is-ancestor HEAD origin/<target-branch> && echo "MERGED" || echo "NOT MERGED"
+
+# 3. Check worker output
+cat ~/.coral/projects/<project>/logs/worker-<slot>.jsonl | tail -20
+
+# Recovery: re-run pipeline tick to trigger CompletionJudge
+sps pipeline tick <project> --json
+```
+
+### Worker process crashed / orphan workers
+```bash
+sps monitor tick <project> --json       # Detects orphans automatically
+# Recovery automatically runs on next tick start
+# Manual: restart tick
+sps tick <project>
+# Recovery module scans state.json, detects dead PIDs, runs CompletionJudge + PostActions
+```
+
+### PM state vs Runtime state mismatch
+```bash
+sps pm scan <project>                   # PM truth
+cat ~/.coral/projects/<project>/runtime/state.json  # Runtime truth
+sps monitor tick <project> --json       # Detects misalignment
+
+# Fix: use PM as source of truth
+sps pm move <project> <seq> <correct-state>
+sps pm comment <project> <seq> "Manual realign: <reason>"
+```
+
+### Tick lock stuck (previous tick didn't exit cleanly)
+```bash
+cat ~/.coral/projects/<project>/runtime/tick.lock
+# Check if PID is still alive:
+kill -0 <pid> 2>/dev/null && echo "ALIVE" || echo "DEAD"
+# If dead, remove lock:
+rm ~/.coral/projects/<project>/runtime/tick.lock
+# Or wait for TICK_LOCK_TIMEOUT_MINUTES (default 30)
+```
+
+### Worker not using expected skill
+```bash
+# Check card skills:
+sps pm scan <project>
+
+# Check skill file exists:
+ls ~/.coral/skills/<name>/SKILL.md
+
+# Check DEFAULT_WORKER_SKILLS in conf:
+grep DEFAULT_WORKER_SKILLS ~/.coral/projects/<project>/conf
+
+# Verify prompt assembly — check task prompt file:
+cat ~/.coral/worktrees/card-<seq>/.sps/task_prompt.txt | head -50
+```
+
+### All workers idle but cards remain
+```bash
+sps pm scan <project>                    # Check card states
+cat ~/.coral/projects/<project>/pipeline_order.json  # Queue empty?
+
+# Possible causes:
+# - Cards have BLOCKED/NEEDS-FIX labels → check and remove
+# - pipeline_order.json is empty but Planning cards exist → re-add:
+sps card add <project> "..." "..."       # Creates new entry
+# - Cards in state not recognized by scheduler
+```
+
+### 7.3 Manual recovery commands
+
+```bash
+# Force move a card
+sps pm move <project> <seq> Todo
+sps pm comment <project> <seq> "Manual recovery: <reason>"
+
+# Manual worker launch (bypass scheduler)
+sps worker launch <project> <seq>
+sps worker launch <project> <seq> --dry-run  # Preview only
+
+# Stop a running tick
+sps stop <project>
+sps stop <project> --all                # Stop all projects
+
+# Re-run individual engines
+sps scheduler tick <project> --json
+sps pipeline tick <project> --json
+sps qa tick <project> --json
+sps monitor tick <project> --json
+```
+
+### 7.4 Useful inspection commands
+
+```bash
+# Full project health report
+sps doctor <project> --json | jq .
+
+# Runtime state snapshot
+cat ~/.coral/projects/<project>/runtime/state.json | jq .
+
+# Active workers with details
+sps worker dashboard --json | jq '.workers[] | select(.status=="active")'
+
+# Cards by state
+sps pm scan <project> Planning
+sps pm scan <project> Inprogress
+sps pm scan <project> Done
+
+# Recent logs
+sps logs <project> --lines 100
+
+# Error logs only
+sps logs <project> --err --lines 50
+```

package/skills/sps/references/workflow-internals.md

@@ -0,0 +1,46 @@
+# Workflow internals
+
+运行流水线的进阶细节:多项目、JSON 输出、tick 周期、状态机、SmartArrange。
+
+### Multi-project
+
+```bash
+# One process manages multiple projects (recommended over separate processes)
+sps tick project-a project-b project-c
+
+# Cross-project worker dashboard
+sps worker dashboard
+```
+
+### JSON output mode
+
+```bash
+sps tick <project> --json         # JSON output (for cron/scripts)
+```
+
+### Tick cycle internals
+
+Each 30-second cycle executes 4 engines in order:
+1. **Scheduler** — Planning → Backlog (promotes draft cards; entry checks)
+2. **QA** — QA state closeout, worktree cleanup, resource release
+3. **Pipeline** — Backlog → Todo → Inprogress → Done (branch, worktree, worker launch, completion)
+4. **Monitor** — Orphan detection, timeout, state alignment
+
+### State machine
+
+```
+[Planning] → Backlog → Todo → Inprogress → [merging] → Done
+  草稿卡     创建分支   创建worktree  AI编码+push  串行merge  释放资源
+  等派发     排队等待   分配Worker    执行任务     PostActions  清理worktree
+```
+
+`sps card add` 默认建卡直接入 **Backlog**（跳过 Planning）；`--draft` 才入 Planning 等 Scheduler 提升。
+
+### SmartArrange (智能编排)
+
+Instead of hand-writing every card, SmartArrange has the agent draft a first-round task list, waits for your approval, then drives the pipeline automatically.
+
+```bash
+sps smartarrange status <project>      # View the task list and progress
+sps smartarrange approve <project>     # Approve the first-round list → enter the auto pipeline
+```

package/skills/web-reach/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: web-reach
+description: 联网查询手册——查天气/新闻/资料/股票/网页内容时按本渠道表取数(Agent Reach 工具集,已实测可达),配失败降级协议;禁止即兴挑 curl 端点。
+category: workflow
+audience: chat
+tags: [process, ai]
+keywords: [联网, 查询, 搜索, 天气, 股票, 新闻, 网页, RSS]
+whenToUse: 需要联网获取信息时(查资料/天气/新闻/行情/读网页/看视频内容),先读本手册按渠道表执行。
+insteadUse: 只做本地计算/文件操作不需要联网时,不用本手册;生图走 generate_asset,写作走 writer。
+---
+
+# 联网查询手册
+
+🔴 **真实数据红线(最高优先)**:天气/股价/新闻/汇率等一切事实性、时效性数据,**只能来自本轮真实执行过的工具输出**。工具没执行成功 = 你没有数据——如实告诉用户查不到及原因;**绝不允许**用记忆或想象补一个"像真的"数字/来源/时间,编造一次就是事故。宁可回答"查不到",不许回答假的。
+
+🔴 **铁律:查询一律从下表取渠道,不要自己即兴挑端点**(随机挑公开 API 是失败率的主要来源)。
+
+## 渠道表(按需求选第一条命中)
+
+| 要查什么 | 用什么 | 命令 |
+|---|---|---|
+| **天气** | wttr.in 结构化 JSON(一次调用出全量,**不要走搜索**) | `curl -s -m 10 'https://wttr.in/<城市英文或拼音>?format=j1'`(如 Beijing/Shanghai;返回 current_condition 现况+3 日预报,自行取字段。失败才退 Exa 搜索) |
+| 全网搜索(新闻/资料/评价,一切"帮我查 xx") | Exa 语义搜索 | `npx -y mcporter call exa web_search_exa --args '{"query":"<自然语言查询>","numResults":5}'` |
+| 读指定网页正文(拿到 URL 后深读) | Jina Reader | `curl -s -m 30 https://r.jina.ai/<完整URL>` |
+| RSS/Atom 订阅源 | 直接读 | `curl -s -m 30 <feed URL>`(返回 XML 自行解析) |
+| B 站视频搜索 | B 站搜索 API | 经 agent-reach(`agent-reach doctor` 可查用法) |
+| YouTube 字幕/视频信息 | yt-dlp | `yt-dlp --skip-download --write-auto-sub <URL>` |
+| V2EX 帖子/节点 | 公开 API | `curl -s https://www.v2ex.com/api/topics/hot.json` 等 |
+| 股票行情 | **暂用搜索兜底**:Exa 搜"<股票名> 股价" 再 Jina 深读结果页 | 雪球渠道待配置(需 Cookie),配好后切换 |
+
+组合套路:**先搜(Exa)拿到候选 URL → 再深读(Jina)拿细节**。搜索结果自带摘要,简单问题摘要就够,别过度抓取。
+
+## 失败降级协议(任何渠道通用)
+
+1. **失败不是终点**:先分辨失败类型——超时/网络断 → 换渠道表里的下一条路(搜索失败改直读权威站,直读失败改搜索);参数错/4xx → 修正参数重试一次;**单次失败绝不直接放弃**。
+2. **至少两条路都试过**才允许说查不到,且必须交代:试了哪些渠道、什么原因失败、用户可以怎么办。**禁止裸的"无法查询"**。
+3. **禁止编造**:查不到就是查不到,不许用训练记忆冒充实时数据(天气/股价/新闻尤其)。
+4. **结果带来源和新鲜度**:告诉用户数据来自哪、大约什么时间的("上海气象局,今天上午发布")。时效数据(行情/天气)必须带。
+5. 渠道集体异常时可跑 `agent-reach doctor` 体检,把结论(哪些渠道不通)如实告知。
+6. **Turn 经济(回合数是稀缺资源)**:抓取+解析要**一次到位**——页面先落临时文件(`curl -s <URL> -o /tmp/page.html`),解析在**一条命令**里完成,不许对同一页面逐步 grep/sed 试探(实测:连环试探会耗尽回合直接失败)。同一渠道解析失败**最多重试 1 次**就换渠道;抓 HTML 永远是最后手段,优先选返回结构化数据(JSON/API)的渠道。国内政府/气象类站点常有 WAF 人机验证,正文是"访问请求进行检测"就直接换渠道别硬磕。