| name | perch |
| description | 多 Topic 个人信息漏斗(v3 · Topic + Prompt 模板)。从 X(List 或用户时间线)采集 数据,按 prompt 模板产出报告 + 概览。**调度由外部决定**(cron / openclaw / agent / 手动),框架只管"采集 → 文件 → LLM 处理 → 文件"。 完整设计见 docs/DESIGN.md,快速入门见 README.md。 |
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-afterPERCH_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 模式):
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 会话里):
- perch.mjs → topic.report(promptName) → 渲染 prompt → 打 stdout
- 当前 Claude 会话读到 stdout 后接棒:读 inputs → 生成 markdown → 用
wiki-write.mjs heredoc pipe(必要时再 summary-write.mjs)
Direct 模式(cron / openclaw / 无会话 runner):
- perch.mjs → topic.report(promptName, { llm: 'direct' }) → 渲染 prompt
lib/llm.mjs::runPromptWithTools 直连 Anthropic Messages API,带 read_file / bash tool- Agent loop:LLM 请求 tool_use → 本地执行 → 回灌 → 直到 stop_reason ≠ 'tool_use'
两种模式 prompt 模板 100% 共享,行为同构。
