trendradar
从 GitHub Trending 抓取热门仓库,生成每日摘要并提交到指定仓库 / 开 PR。 核心是 Go 单二进制,通过 IPC 信封与 DSH 插件通信。
安装
go install github.com/morehao/trendradar/cmd/trendradar@latest
命令
trendradar version --json # 握手:version / ipcSchema / digestSchema / providers
trendradar run --config config.yaml # 抓取→解析→摘要→渲染→提交
trendradar run --config config.yaml --dry-run # 只产出文件,不写盘、不提交
trendradar run --config config.yaml --period weekly --date 2026-11-01 # 指定周期
trendradar serve --addr 127.0.0.1:8787 # 以 HTTP 提供 digest
trendradar subscribe add owner/repo # 订阅仓库(可多个),需 --config
trendradar subscribe list # 查看订阅,需 --config
trendradar subscribe remove owner/repo # 取消订阅,需 --config
输出布局
产出按周期分层,日 / 周 / 月三榜可在同一天共存、互不覆盖:
trending/
├── index.md # 日/周/月 分节索引
├── daily/2026-10/2026-10-31.{md,json}
├── weekly/2026/2026-W44.{md,json} # date=2026-11-01(ISO 周)
└── monthly/2026/2026-10.{md,json}
--period 取 daily|weekly|monthly(缺省用 config.trending.since);
--date 传该周期的结束日(周榜周日、月榜月末)。分支名为
trending/<period>/<name>。
开发
make build # -> bin/trendradar
make test # go vet + go test
make test-eval # 真实模型评估(读取 .env 里的 TRENDRADAR_EVAL_*)
摘要外部增强(可选)
默认 summarize.enrich: none,只用仓库名/描述/语言/Star/排名。设为 repo
会额外抓取 GitHub topics;设为 readme 再追加 800 字 README 摘录,用于提升
摘要具体性。抓取走仓库 HTML(topics + 默认分支)与 raw.githubusercontent.com
(README),不消耗 REST 60/h 配额;结果缓存 7 天,仅对摘要缓存未命中的仓库拉取,
单仓库失败逐仓库降级、不影响 run。
summarize:
enrich: repo # none | repo | readme,默认 none
readmeChars: 800 # README 截断字符数
enrichCacheTTLHours: 168
enrichConcurrency: 4
enrichTimeoutSeconds: 5
enrichBudgetSeconds: 8 # readme 模式默认 12
run --json 会新增可选 stages 与 enrich 字段,<repo>/.git/trendradar-usage.jsonl
每行也记录 durationMs、summaryDegraded 与 enrich 计数,便于观测与回退。
完整可复制配置见 config.example.yaml。
- 代码默认
enrich: none;生产是否开启由部署侧config.yaml决定,建议先开repo。 readme在个别仓库可能出现长度/中文率校验降级(summarySource=original);上线前用TRENDRADAR_EVAL_ENRICH=readme make test-eval复测,降级率 > 2% 先回退repo。- 回退判据:
enrich.failed/requested > 5%、usage.totalTokens超过基线约 4 倍、或summaryDegraded明显上升时,把enrich调回none/repo。
仓库发版订阅(可选)
把一批自有仓库加入订阅后,run 会每周一次检查它们的新 Release(没有 Release 时回退 Tag),
每个仓库把这一周的全部新版本合成一段中文总结,写入两类产物,并与 trending 走同一次提交/PR:
| 产物 | 路径 | 用途 |
|---|---|---|
| 周文档(外部 API 的数据面) | <output.dir>/releases/_weekly/<年>/<ISO周>.{md,json} |
GET /api/v2/releases* |
| 每仓文档(人读、面板渲染) | <output.dir>/releases/<owner>/<repo>-01.md |
最新一周在最上面;超过 docMaxLines 后下一次写入开 -02.md(每册都带序号) |
订阅列表是一份数据仓内受版本控制的文件 <output.dir>/subscriptions.yaml
(默认 digests/subscriptions.yaml,示例见 subscriptions.example.yaml),
由 CLI 维护(--config 必填,subscribe 与 run 因此解析到同一个文件),不写进 config.yaml。
trendradar subscribe add morehao/trendradar morehao/golib --config config.yaml
trendradar subscribe list --config config.yaml # 逐行仓库名;--json 额外带 items[]
trendradar subscribe releases morehao/trendradar --config config.yaml # 读该仓的发版记录
trendradar subscribe releases morehao/trendradar --volume 2 --config config.yaml
trendradar subscribe remove morehao/golib --config config.yaml
订阅的写入不碰工作区:add/remove 只把「意图」写进 <repo>/.git/trendradar-subscriptions.pending
(该位置不参与 git status,所以 run 的 IsClean 不会被判脏)。下一次 run 在切到当日分支后
把 pending 合并进 <output.dir>/subscriptions.yaml,随产物走同一次 commit/PR;只有 commit 与
push 都成功后才会清空 pending(push 失败则下次 run 重放,宁可重复一次 commit 也不丢订阅)。
releases:
enabled: true
subscriptionsFile: subscriptions.yaml
period: weekly # 总结周期;本版只支持 weekly
timezone: Asia/Shanghai # ISO 周边界按该时区计算
weekStart: monday # 仅支持 monday(ISO 8601)
fallbackToTags: true
baselineOnFirstRun: true # 首次只记基线,不补发历史
perRepoLimit: 10 # 文档每仓每周最多列出的版本数,其余写「其余 N 个」
summaryMaxChars: 1200 # 每仓每周一段总结的字符上限(500-2000)
docMaxLines: 600 # 每仓文档行数阈值
concurrency: auto # auto = clamp(4, ceil(N/10), 8)
budgetSeconds: auto # auto = min(300, 30 + 3N)
要点:
- 默认
enabled: false,对现有 trending 零影响;enabled: true时才加载订阅。 - 空订阅/文件缺失时
run跳过该阶段并 warning,不报错;订阅文件 YAML 损坏才 fail-fast。 - 周闸门:每个仓库记最近一次总结的 ISO 周键,同一周再跑直接跳过(不请求 GitHub、不调模型、 不改文档)。插件侧的周定时决定「什么时候跑」,核心闸门保证「同一周只写一次」。
- 一周一次模型调用:这一个仓库这一周的全部新版本合成一段总结;失败降级为原文摘录并标记
degraded,游标不前进、下一周重试。 - 切卷只看写入前:写入前当前册行数
> docMaxLines才新开一册;本次章节永远整节写入, 不会被拆到两册,也不会因为「这次会超」而丢记录。 run --stages releases只跑发版阶段:不抓 trending、不渲染榜单、不合并 pending 订阅, 只读subscriptions.yaml,适合独立的周定时。- 发版摘要的 token 消耗在
run --json的releases.usage里(恒存在):calls=0表示没发生模型调用(如全部命中缓存),calls>0 && usageKnown=false表示调用了但供应商没回用量——两者不要混为一谈。 releases.checked/releases.changed恒存在:分别表示本次检查了多少仓、多少仓产出了文档。- 仓库没有 Release 时回退 Tag,并用该 tag 的 commit message 作为摘要依据。
- 状态与摘要缓存放在
<repo>/.git/trendradar-release-*.json,天然不入库。 trendradar-usage.jsonl额外记录一行stage="releases"。- 插件可经 IPC 管理订阅:
trendradar subscribe --json从 stdin 读一个RunRequest({"command":"subscribe","action":"add","repo":"o/r","configPath":"..."}, 读文档用action:"releases"+volume),回写RunResult(列表/文档在subscriptions/subscriptionDoc两个字段里)。configPath必填,保证subscribe与run解析到同一个订阅文件。 serve提供只读接口,与 IPC 一一对应:GET /api/v2/releases、GET /api/v2/releases/{date}、GET /api/v2/subscriptions(含items[])、GET /api/v2/repos/{owner}/{repo}/releases?volume=N。 HTTP 只读、无鉴权,默认绑127.0.0.1;写操作只走 IPC。
本地密钥与测试
不要把 API key 写进 config.yaml。复制 .env.example 为 .env(已被
.gitignore 忽略)并填入:
DEEPSEEK_API_KEY=sk-...
DEEPSEEK_MODEL=deepseek-flash
DEEPSEEK_BASE_URL=https://api.deepseek.com/v1
trendradar 启动时会自动向上查找最近的 .env.local / .env,也可用
TRENDRADAR_ENV_FILE=/path/to/file 指定。真实 shell 环境变量优先于文件。
config.yaml 支持 ${VAR} 引用,例如:
model:
provider: deepseek
name: ${DEEPSEEK_MODEL}
baseURL: ${DEEPSEEK_BASE_URL}
apiKey: ${DEEPSEEK_API_KEY}
评估 harness 也用同一套变量:.env 里放 TRENDRADAR_EVAL_PROVIDER/MODEL/ BASE_URL/API_KEY,然后 make test-eval。加 TRENDRADAR_EVAL_ENRICH=repo|readme
即可复测带外部上下文的 A/B 摘要。
目录
cmd/trendradar— CLI 入口与子命令internal/ipc— 与插件共享的 IPC 信封、错误码、版本信息internal/config— config.yaml 加载与校验internal/subscription— 订阅列表读写与校验internal/releasewatch/internal/releasedigest— 发版订阅抓取、摘要与文档contract/— 四份 schema 与 fixtures(Go 与插件共用,唯一真源).dsh/docs/— 过程性文档(不入库)
No comments yet. Be the first to write one.