You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: CLAUDE.md
+45-22Lines changed: 45 additions & 22 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,35 +2,40 @@
2
2
3
3
## Project overview
4
4
5
-
agents-radar is a daily digest generator for the AI open-source ecosystem. A GitHub Actions cron job runs at 00:00 UTC (08:00 CST) and produces five Chinese-language reports, published as GitHub Issues and committed Markdown files.
5
+
agents-radar is a daily digest generator for the AI open-source ecosystem. A GitHub Actions cron job runs at 00:00 UTC (08:00 CST) and produces bilingual (Chinese + English) reports, published as GitHub Issues and committed Markdown files.
6
6
7
7
## Commands
8
8
9
9
```bash
10
10
pnpm start # run the full digest locally
11
+
pnpm test# vitest (unit tests)
11
12
pnpm typecheck # tsc --noEmit
12
13
pnpm lint # ESLint
13
14
pnpm lint:fix # ESLint --fix
14
15
pnpm format # Prettier --write src
15
16
pnpm format:check # Prettier --check src
16
17
```
17
18
18
-
Required env vars for local runs (set **one** LLM provider group):
19
+
Required env vars for local runs:
19
20
20
21
```bash
21
22
export GITHUB_TOKEN=ghp_xxxxx
23
+
export DIGEST_REPO=owner/repo # omit to skip GitHub issue creation
22
24
23
-
# Option A — OpenAI-compatible (takes precedence when OPENAI_API_KEY is set)
export DIGEST_REPO=owner/repo # omit to skip GitHub issue creation
32
+
# OpenAI
33
+
# export OPENAI_API_KEY=sk-xxxxx
34
+
35
+
# GitHub Copilot — uses GITHUB_TOKEN
36
+
37
+
# OpenRouter
38
+
# export OPENROUTER_API_KEY=sk-or-xxxxx
34
39
```
35
40
36
41
## Architecture
@@ -40,16 +45,29 @@ The pipeline runs in four sequential phases, each implemented as a named async f
40
45
1.**`fetchAllData`** — all network I/O in parallel: GitHub API (issues/PRs/releases) for 17 repos, Claude Code Skills, Anthropic/OpenAI sitemaps, GitHub Trending HTML + Search API, Hacker News Algolia API.
41
46
2.**`generateSummaries`** — per-repo LLM calls, all in parallel, rate-limited to 5 concurrent requests by a queue in `src/report.ts`.
42
47
3.**Comparisons** — two LLM calls: cross-tool CLI comparison and OpenClaw cross-ecosystem comparison.
|`src/web.ts`| Sitemap-based web content fetching; state persisted to `digests/web-state.json`|
54
72
|`src/trending.ts`| GitHub Trending HTML scraper + Search API topic queries |
55
73
|`src/hn.ts`| Hacker News top AI stories via Algolia HN Search API |
@@ -78,10 +96,13 @@ Files written to `digests/YYYY-MM-DD/`:
78
96
79
97
## Key conventions
80
98
81
-
- All LLM prompts are in `src/prompts.ts`. Each report type has its own builder function. Prompts are written in Chinese and produce Chinese output.
99
+
- All bilingual strings (titles, labels, footers, messages) are centralized in `src/i18n.ts`. Use the `Lang` type (`"zh" | "en"`) and `Record<Lang, string>` maps. Do not add inline bilingual ternaries elsewhere.
100
+
- LLM prompt builders are split across two files: `src/prompts.ts` (repo-level prompts) and `src/prompts-data.ts` (data-source and rollup prompts). Each report type has its own builder function.
82
101
-`callLlm(prompt, maxTokens?)` defaults to 4096 tokens. Web report uses 8192, trending uses 6144. HN report uses the default 4096.
83
102
- On 429 rate-limit errors `callLlm` retries up to 3 times with exponential backoff (5 s / 10 s / 20 s); the concurrency slot is released during the wait.
84
-
- The concurrency limiter (`LLM_CONCURRENCY = 5`) prevents 429s when many parallel LLM calls fire. Do not bypass it by calling the Anthropic SDK directly.
103
+
- The concurrency limiter (`LLM_CONCURRENCY = 5`) prevents 429s when many parallel LLM calls fire. Do not bypass it by calling SDK clients directly.
104
+
- LLM provider is selected via `LLM_PROVIDER` env var (default: `anthropic`). Valid values: `anthropic`, `openai`, `github-copilot`, `openrouter`.
105
+
- Provider implementations live in `src/providers/`. Each file implements the `LlmProvider` interface. The factory in `src/providers/index.ts` validates the provider name and logs only the provider name — never API keys or endpoint URLs.
85
106
- GitHub issue label colors are defined in `LABEL_COLORS` in `src/github.ts`. Add new labels there.
86
107
-`sampleNote(total, sampled)` in `src/prompts.ts` formats the "(共 N 条,展示前 M 条)" note. Reuse it — do not inline the same string format.
87
108
- Web state (`digests/web-state.json`) is committed to git on every run. It is the source of truth for which URLs have been seen.
@@ -91,14 +112,16 @@ Files written to `digests/YYYY-MM-DD/`:
91
112
- Web UI: `index.html` reads `manifest.json` to build the sidebar, then fetches `digests/YYYY-MM-DD/report.md` on demand.
92
113
- RSS Feed: `feed.xml` at the repo root. Generated by `src/generate-manifest.ts` in the same `pnpm manifest` step. Contains the latest 30 items (newest first) across all report types. Item links use hash routing: `https://duanyytop.github.io/agents-radar/#YYYY-MM-DD/report`.
93
114
- Both `manifest.json` and `feed.xml` are committed together in the "Commit manifest and feed" GHA step.
94
-
- The `REPORT_LABELS` map in `generate-manifest.ts` must be kept in sync with the `LABELS` object in `index.html` when adding new report types.
115
+
- The `REPORT_LABELS` map in `src/i18n.ts` must be kept in sync with the `LABELS` object in `index.html` when adding new report types.
95
116
96
117
## Adding a new report type
97
118
98
119
1. Create a data fetcher (or add to an existing one).
99
-
2. Add a `buildXxxPrompt` function in `src/prompts.ts`.
100
-
3. Wire into `fetchAllData`, `generateSummaries`, and a `saveXxxReport` function in `src/index.ts`.
101
-
4. Add a label color entry in `LABEL_COLORS` in `src/github.ts`.
102
-
5. Add the report ID and label to `REPORT_LABELS` in `src/generate-manifest.ts` and `LABELS` in `index.html`.
103
-
6. Add the report file name to `REPORT_FILES` in `src/generate-manifest.ts`.
104
-
7. Update both README files and this file.
120
+
2. Add a `buildXxxPrompt` function in `src/prompts-data.ts` (for data-source prompts) or `src/prompts.ts` (for repo-level prompts).
121
+
3. Add bilingual strings (titles, labels, issue title function) to `src/i18n.ts`.
122
+
4. Add a `saveXxxReport` function in `src/report-savers.ts`.
123
+
5. Wire into `fetchAllData`, `generateSummaries`, and the save phase in `src/index.ts`.
124
+
6. Add a label color entry in `LABEL_COLORS` in `src/github.ts`.
125
+
7. Add the report ID and label to `REPORT_LABELS` in `src/i18n.ts` and `LABELS` in `index.html`.
126
+
8. Add the report file name to `REPORT_FILES` in `src/generate-manifest.ts`.
0 commit comments