perch

# Perch > 互联网数据处理框架。每个 Topic = 一组数据源 + 任意多份 prompt 模板。 ## ⚠️ 必读 **完整架构、风险、术语全部在 `docs/DESIGN.md`。任何实现前请先读。** ## 当前状态(v3) v3 退化成纯工具集:框架不做调度,prompt 是数据。slot / window / 凌晨 wrap 这些抽象 **全部消失**。 ## 核心概念 | 概念 | 含义 | |---|---| | **Topic** | 配置容器(sources + prompts + 数据目录),通过 method 触发行为 | | **Prompt 模板** | `templates/topics/<slug>/<name>.md`,任意数量、任意命名 | | **Section** | wiki 内部 `## section: <name>` 分段;名字由 `--section` 决定 | | **Daily Wiki** | 归属日 1 份文件,按 section 分段;report 维护 | | **Summaries** | 当月日概览(`## YYYY-MM-DD`),时间倒序 prepend | ## 角色与命令 所有命令统一入口 `scripts/perch.mjs`: | 命令 | 角色 | 工作模式 | |---|---|---| | `/perch ingest [--topic <slug>] [--out path] [--dry] [--limit N]` | Ingest | 纯自动化:抓 X → 跨源去重 → 全局重排 → 写 raw | | `/perch report --topic <slug> --prompt <name> [--llm skill\|direct] [--inputs paths] [--date YYYY-MM-DD] [--section <name>]` | Report | **Skill** 或 **Direct** 模式(见下) | | `/perch enrich [--topic <slug>] --url <status_url>` | Enrich | 纯自动化:CDP 抓 Twitter Article → 月度缓存 | | `/perch archive [--topic <slug>] [--dry-run]` | Archive | 纯自动化:非当月 raw / wiki / cache → archive/YYYY-MM/ | | `/perch admin list` / `/perch admin create [--from-json spec.json]` | Admin | 纯自动化:Topic 配置 CRUD | ### Report 的两种 LLM 模式 | 模式 | 触发 | 适用场景 | |---|---|---| | **Skill**(默认) | `--llm skill` 或缺省 | 在 Claude Code 会话里跑;脚本打 prompt → 当前会话接棒 | | **Direct** | `--llm direct` 或 `PERCH_LLM_MODE=direct` | cron / openclaw / 任意无会话 runner;脚本直连 Anthropic Messages API + agent loop | Direct 模式 env: - `PERCH_LLM_PROVIDER`(`anthropic`(默认) / `openai` / `stub`) - Provider key: - **anthropic**: `ANTHROPIC_API_KEY`(默认模型 `claude-sonnet-4-5`) - **openai**: `OPENAI_API_KEY` + 可选 `PERCH_LLM_BASE_URL`(默认 `https://api.openai.com/v1`,可指 OpenRouter / Together / 本地 vLLM 等 OpenAI-compatible 端点;默认模型 `gpt-4o`) - `PERCH_LLM_MODEL`(覆盖默认模型) - `PERCH_LLM_MAX_TOKENS`(默认 16384) - `PERCH_LLM_MAX_RETRIES`(默认 5)/ `PERCH_LLM_INITIAL_BACKOFF_MS`(默认 1000):429 / 5xx / 网络抖动 exponential backoff + jitter,respect `retry-after` - `PERCH_LLM_DEBUG=1`(打印 API request/response 简要) **两种模式共享同一份 prompt 模板** —— Direct 模式的 agent loop 给 LLM 暴露 `read_file` / `bash` 工具,行为和 Claude Code 会话同构。 Agent tools(prompt 内 Claude Bash 调用): | 工具 | 调用时机 | |---|---| | `scripts/wiki-write.mjs` | report 阶段 Claude 生成完 markdown 后 pipe(`--section <name>`) | | `scripts/summary-write.mjs` | evening 类 prompt 生成完日概览后 pipe | | `scripts/fetch-article.mjs` | report 阶段 Claude 按需深抓 article | ## 默认值约定 - `--topic` 缺省 → `config.json` 的 `default_topic` - `--inputs` 缺省 → today raw 单文件(`raw/daily/$(today).md`) - `--date` 缺省 → today(topic.timezone) - `--section` 缺省 → 与 `--prompt` 同名 调度典型形态(cron + Direct 模式): ```bash # /etc/cron.d/perch (示例) ANTHROPIC_API_KEY=sk-ant-... PERCH_LLM_MODE=direct 0 8 * * * cd /path/to/perch && node scripts/perch.mjs ingest --topic ai-radar && node scripts/perch.mjs report --topic ai-radar --prompt morning 0 13 * * * cd /path/to/perch && node scripts/perch.mjs ingest --topic ai-radar && node scripts/perch.mjs report --topic ai-radar --prompt noon 0 19 * * * cd /path/to/perch && node scripts/perch.mjs ingest --topic ai-radar && node scripts/perch.mjs report --topic ai-radar --prompt evening ``` Skill 模式(Claude Code 内手动跑)不需要 env:`perch report --topic ai-radar --prompt morning` 即可。 凌晨补跑昨天:`perch report ... --date $(date -d yesterday +%F) --inputs raw/daily/$(date -d yesterday +%F).md`,shell 一行,框架不做特殊处理。 ## v2 → v3 命令对照 | v2 | v3 | 备注 | |---|---|---| | `perch analyze --slot evening` | `perch report --prompt evening` | Slot 概念消失,prompt 是数据 | | `perch analyze --slot now` | (无直接等价) | cron 自己根据时间选 prompt | | `perch digest` | (合并回 evening prompt 的双产出) | 一次 LLM 调用同时输出 wiki + summary | | 其他 | 行为等价 | ## v3 不实现 - Schedule 自动驱动(v3 哲学就是不做调度;Direct 模式 + cron / openclaw 已覆盖) - Topic Wiki stale / rebuild - 跨 topic 查询 - summaries 月度切分归档 ## Skill 模式 vs Direct 模式 `ingest` / `archive` / `enrich` / `admin` 是确定性任务,脚本自己跑完即可。`report` 需要 LLM 智能,有两条路径: **Skill 模式**(在 Claude Code 会话里): 1. perch.mjs → topic.report(promptName) → 渲染 prompt → 打 stdout 2. **当前 Claude 会话读到 stdout 后接棒**:读 inputs → 生成 markdown → 用 `wiki-write.mjs` heredoc pipe(必要时再 `summary-write.mjs`) **Direct 模式**(cron / openclaw / 无会话 runner): 1. perch.mjs → topic.report(promptName, { llm: 'direct' }) → 渲染 prompt 2. `lib/llm.mjs::runPromptWithTools` 直连 Anthropic Messages API,带 `read_file` / `bash` tool 3. Agent loop:LLM 请求 tool_use → 本地执行 → 回灌 → 直到 stop_reason ≠ 'tool_use' 两种模式 prompt 模板 100% 共享,行为同构。