[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7F71MDG2AYP2CK3K48MRQNH":3,"skill-same:01M7F71MDG2AYP2CK3K48MRQNH":100},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":42,"commitSha":43,"skillDirectory":44,"forksCount":14,"repositoryHtmlUrl":45,"repositoryHomepageUrl":6,"ownerHtmlUrl":46,"ownerBlogUrl":47,"ownerDescription":48,"updatedAt":49,"install":50,"resources":63},"01M7F71MDG2AYP2CK3K48MRQNH","github-trending-collector",null,"Scrape GitHub Trending (daily\u002Fweekly\u002Fmonthly), enrich via gh api, analyze for new\u002Fhot projects, generate Feishu reports and HTML→PDF visual reports. Use when collecting, scheduling, analyzing, or reporting on GitHub trending project data.","chaorenex1\u002Fhermes-home-content","chaorenex1","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F23194925?v=4","01M7F5NA1D1D02R2MEMYQN2NZT","chan chan","01M7F5NA20KTHMTY2015CYM1TZ",0,"MIT","https:\u002F\u002Fgithub.com\u002Fchaorenex1\u002Fhermes-home-content\u002Fblob\u002Fmain\u002Fskills\u002Fgithub\u002Fgithub-trending-collector\u002FSKILL.md",[],[],"2026-11-16 10:05:34",false,"---\r\nname: github-trending-collector\r\ndescription: \"Scrape GitHub Trending (daily\u002Fweekly\u002Fmonthly), enrich via gh api, analyze for new\u002Fhot projects, generate Feishu reports and HTML→PDF visual reports. Use when collecting, scheduling, analyzing, or reporting on GitHub trending project data.\"\r\nversion: 1.0.0\r\nauthor: Hermes Agent\r\nlicense: MIT\r\nplatforms: [linux, macos, windows]\r\nmetadata:\r\n  hermes:\r\n    tags: [GitHub, Trending, Data Collection, Cron, Scraping, gh CLI]\r\n    related_skills: [github-repo-management, github-auth]\r\n---\r\n\r\n# GitHub Trending Data Collector\r\n\r\nCollect GitHub Trending repository data across three time periods (daily, weekly, monthly), enrich each repo with full GitHub API metadata, and save as structured JSON files. Designed for scheduled (cron) execution.\r\n\r\n## When to Use\r\n\r\n- User asks to collect\u002Fscrape GitHub trending repos\r\n- User wants scheduled trending data collection (cron job)\r\n- User asks for trending project popularity\u002Fheat data\r\n- User needs repo data fields: name, ID, URL, language breakdown, stars, forks, description, README summary, owner info\r\n- User wants to analyze trending data (new projects, categories, hot projects)\r\n- User wants Feishu reports or PDF visual reports from trending data\r\n- User asks to set up automated trending report pipeline (cron + Feishu + PDF)\r\n\r\n## When NOT to Use\r\n\r\n- Querying a single known repo → use `gh api repos\u002Fowner\u002Frepo` directly\r\n- General repo CRUD (clone\u002Fcreate\u002Ffork) → use `github-repo-management`\r\n- GitHub PR\u002Fissue workflows → use `github-pr-workflow` \u002F `github-issues`\r\n\r\n## Architecture\r\n\r\n```\r\nGitHub Trending HTML → parse repo list → gh api enrichment per repo → structured JSON\r\n         ↑                                    ↓\r\n    urllib.request                   \u002Frepos\u002F{repo}           → stars, forks, description, topics, owner\r\n    (trending page only)             \u002Frepos\u002F{repo}\u002Flanguages  → language byte counts → percentage\r\n                                     \u002Frepos\u002F{repo}\u002Freadme     → README (base64) → detailed summary\r\n                                     \u002Fusers\u002F{owner}           → owner GitHub ID + URL\r\n```\r\n\r\n## Critical Decision: `gh api` over `urllib` on Windows\r\n\r\n**Always use `gh api` (subprocess) for GitHub API calls on Windows.** `urllib.request` fails with intermittent SSL\u002FTLS errors (`UNEXPECTED_EOF_WHILE_READING`, `TLS handshake timeout`) against `api.github.com`. The `gh` CLI handles SSL, auth, and retries internally and is dramatically more reliable.\r\n\r\nThe trending **HTML page** itself can be fetched via `urllib.request` — only the API endpoint has SSL issues.\r\n\r\n### Token Redaction Pitfall\r\n\r\nThe Hermes `terminal` tool **redacts** `gh auth token` output — it appears as `gho_6L...427S` (truncated). Do NOT attempt to capture the token into a Python variable via `terminal()`. Instead, call `gh api` as a subprocess from Python:\r\n\r\n```python\r\nresult = subprocess.run([\"gh\", \"api\", endpoint], capture_output=True, text=True, timeout=30)\r\ndata = json.loads(result.stdout)\r\n```\r\n\r\n## File Path Convention\r\n\r\nData is saved under `~\u002F.hermes\u002Fgithub_trending_data\u002FYYYY-M\u002F`:\r\n\r\n| Period   | Filename Pattern             | Example                     | When Updated          |\r\n|----------|------------------------------|-----------------------------|-----------------------|\r\n| Daily    | `YYYY-M-D.json`             | `2026-7\u002F2026-7-5.json`      | Every day             |\r\n| Weekly   | `YYYY-M-W.json` (W=week #)  | `2026-7\u002F2026-7-1.json`      | Every Monday (or first run in week) |\r\n| Monthly  | `YYYY-M.json`                | `2026-7\u002F2026-7.json`        | 1st of month (or first run) |\r\n\r\nWeek-of-month = `((day - 1) \u002F\u002F 7) + 1` — so days 1-7 = week 1, 8-14 = week 2, etc.\r\n\r\nThe script has built-in skip logic: if the target file already exists, that period is skipped (prevents redundant re-collection within the same day\u002Fweek\u002Fmonth). Use `--force` to override.\r\n\r\n## Output Data Schema\r\n\r\nEach JSON file contains:\r\n\r\n```json\r\n{\r\n  \"period\": \"daily|weekly|monthly\",\r\n  \"collected_at\": \"2026-07-05T12:45:15.205702\",\r\n  \"total_repos\": 18,\r\n  \"repos\": [\r\n    {\r\n      \"repo_name\": \"codex-plugin-cc\",\r\n      \"repo_id\": \"openai\u002Fcodex-plugin-cc\",\r\n      \"repo_url\": \"https:\u002F\u002Fgithub.com\u002Fopenai\u002Fcodex-plugin-cc\",\r\n      \"languages\": {\"JavaScript\": 100.0},\r\n      \"stars\": 24691,\r\n      \"forks\": 1495,\r\n      \"short_description\": \"Use Codex from Claude Code to review code or delegate tasks.\",\r\n      \"detailed_summary\": \"# Codex plugin for Claude Code\\n...(README, truncated to 5000 chars)\",\r\n      \"owner\": {\r\n        \"login\": \"openai\",\r\n        \"github_id\": 14957082,\r\n        \"github_url\": \"https:\u002F\u002Fgithub.com\u002Fopenai\"\r\n      },\r\n      \"topics\": [],\r\n      \"homepage\": \"\",\r\n      \"license\": \"Apache License 2.0\",\r\n      \"created_at\": \"2026-03-30T15:29:52Z\",\r\n      \"updated_at\": \"2026-07-05T04:39:04Z\",\r\n      \"period_stars\": 718\r\n    }\r\n  ]\r\n}\r\n```\r\n\r\n## Running the Collector\r\n\r\n### One-time \u002F manual run\r\n\r\n```bash\r\n# Collect all periods (skips existing files)\r\npython \u003CHERMES_HOME>\u002Fscripts\u002Fgithub_trending.py --period all\r\n\r\n# Force re-collect all periods\r\npython \u003CHERMES_HOME>\u002Fscripts\u002Fgithub_trending.py --period all --force\r\n\r\n# Collect only daily\r\npython \u003CHERMES_HOME>\u002Fscripts\u002Fgithub_trending.py --period daily\r\n```\r\n\r\n### Scheduled (cron)\r\n\r\nCreate a daily cron job at 09:00:\r\n\r\n```\r\nSchedule: 0 9 * * *\r\nPrompt: Run `python \u003CHERMES_HOME>\u002Fscripts\u002Fgithub_trending.py --period all`\r\n```\r\n\r\nThe script's skip logic means daily data updates every day, weekly data updates on the first run of each week, and monthly data updates on the first run of each month — all from the same daily cron trigger.\r\n\r\n> **Note:** Cron jobs in Hermes TUI sessions are local-only. Output is saved but not delivered to the session. For notifications, set `deliver` to a gateway-connected platform (e.g., `telegram`).\r\n\r\n## Performance Notes\r\n\r\n- ~18-25 repos per trending page (daily\u002Fweekly\u002Fmonthly vary)\r\n- 4 API calls per repo (details + languages + readme + owner) = ~80-100 calls total\r\n- 0.5s delay between API calls = ~1-2 minutes per period\r\n- Total runtime for all 3 periods: ~5-7 minutes\r\n- GitHub API rate limit: 5000 req\u002Fhour with auth (well within limits)\r\n\r\n## Files\r\n\r\n### Skill scripts\r\n- `scripts\u002Fgithub_trending.py` — the complete collector script (standalone, re-runnable)\r\n\r\n### Pipeline scripts (in `~\u002F.hermes\u002Fscripts\u002F`)\r\n- `trending_analyzer.py` — analysis engine (new projects, categorization, hot projects)\r\n- `ai_classify_prepare.py` — splits analysis repos into batches of 6, outputs batch paths for AI delegation\r\n- `ai_classify_merge.py` — merges AI classification results back into analysis JSON, recomputes distributions\r\n- `feishu_report.py` — Feishu document creation + IM notification\r\n- `generate_html.py` — HTML report generator (Python, Linear dark theme design system) — **replaces `generate_ppt.js`**\r\n- `html2pdf.js` — HTML→PDF converter (puppeteer-core + system Edge browser, 1280×720px pages) — **replaces LibreOffice PPTX conversion**\r\n- `pdf2img.py` — PDF→JPEG image converter (PyMuPDF, for vision QA)\r\n- `trending_orchestrator.py` — main orchestrator for cron jobs\r\n- `trending_run.sh` — bash wrapper (sets up environment and calls orchestrator)\r\n\r\n### References\r\n- `references\u002Ftrending-page-structure.md` — HTML parsing details, API endpoints, Windows SSL workaround\r\n- `references\u002Fpipeline-scripts.md` — detailed design decisions for all pipeline scripts (analyzer, feishu, PPT, orchestrator)\r\n- `references\u002Fai-classification-workflow.md` — AI delegation taxonomy, prompt template, and merge script for accurate repo classification\r\n- `references\u002Fpipeline-test-procedure.md` — step-by-step end-to-end test procedure (reset → prepare → delegate → merge → verify → cleanup) with expected timing and troubleshooting\r\n- `references\u002Ffeishu-drive-folder-management.md` — Feishu Drive folder hierarchy (root + monthly subfolders), local token cache, required OAuth scopes, and `ensure_report_folder()` design\r\n\r\n### Templates\r\n- `templates\u002Fcron-prompt-template.md` — full tested cron job prompt (3-step pipeline) ready to copy, with cron config table and validation results\r\n\r\n## Full Report Pipeline (Collect → Analyze → Feishu → HTML\u002FPDF Report)\r\n\r\nThe collector is the first stage of a full trending report pipeline. After data collection, three additional scripts process the data into Feishu documents and PPT reports. All pipeline scripts live in `~\u002F.hermes\u002Fscripts\u002F`.\r\n\r\n### Pipeline Architecture\r\n\r\n```\r\ngithub_trending.py  →  trending_analyzer.py  →  feishu_report.py\r\n(collect data)          (analyze + classify)     (Feishu doc + IM notify)\r\n                                                   ↓\r\n                                             generate_html.py\r\n                                             (Linear dark theme HTML report)\r\n                                                   ↓\r\n                                             html2pdf.js\r\n                                             (puppeteer-core + Edge → PDF)\r\n                                                   ↓\r\n                                             trending_orchestrator.py\r\n                                             (orchestrates all of the above)\r\n```\r\n\r\n### Analysis (`trending_analyzer.py`)\r\n\r\nThe analyzer reads collected JSON and produces structured analysis:\r\n\r\n- **New project detection**: Scans all previous period data files to identify repos that have never appeared before. A repo is \"new\" if its `repo_id` doesn't exist in any prior same-period file.\r\n- **Categorization**: Classifies each repo into categories (AI\u002FML, Developer Tools, Web\u002FFramework, Data\u002FDatabase, Security, DevOps\u002FInfra, Mobile\u002FApp, Game\u002FMedia, Blockchain, System\u002FLow-level) and scenes (代码生成与辅助, 模型推理与部署, etc.) using **word-boundary regex matching** (`\\b...\\b`) against a two-tier text source: first high-signal text (repo name, topics, short description), then a cleaned README excerpt as fallback. HTML tags are stripped from the README before matching. See `references\u002Fpipeline-scripts.md` for the full classification design and the pitfalls of naive substring matching.\r\n- **Hot project detection**: Flags repos with `period_stars ≥ threshold`. Thresholds: daily ≥1000, weekly ≥5000, monthly ≥10000.\r\n- **Project summary generation**: Extracts capabilities from cleaned (HTML-stripped) README, identifies primary language, categories, and scenes.\r\n\r\n```bash\r\n# Analyze a specific date\r\npython trending_analyzer.py --period daily --date 2026-7-5 --save\r\n# Output: ~\u002F.hermes\u002Fgithub_trending_data\u002F2026-7\u002Fanalysis\u002F2026-7-5_analysis.json\r\n```\r\n\r\n### Feishu Report (`feishu_report.py`)\r\n\r\nCreates a Feishu document with the analysis and sends a notification message:\r\n\r\n- **Drive folder management**: Documents are organized in a hierarchical folder structure in Feishu Drive — root folder \"GitHub Trending\" → monthly subfolder (e.g., \"2026-7\"). Folder tokens are cached locally in `~\u002F.hermes\u002Fgithub_trending_data\u002Ffeishu_folders.json` to avoid repeated API calls. The `ensure_report_folder()` function is called before document creation to get the target folder token. **Important:** `docs +create --parent-token` does NOT reliably place documents into folders (Feishu API limitation). The `create_feishu_doc()` function uses a create-then-move pattern: creates the doc without `--parent-token`, then immediately calls `drive +move` to move it into the target folder. See `references\u002Ffeishu-drive-folder-management.md` for the full implementation and scope requirements.\r\n- **Document**: XML content with sections: 总体概览 (overview + **Mermaid pie charts** for language\u002Fcategory\u002Fscene distributions + hot projects), 项目列表 (full repo list with **structured multi-line fields**), 新秀项目 (new projects).\r\n- **Mermaid pie charts**: Three `\u003Cwhiteboard type=\"mermaid\">` blocks render as native Feishu whiteboards:\r\n  - 📊 语言分布 — top 10 languages + \"其他\" group (pie chart)\r\n  - 📊 分类分布 — AI category counts (pie chart)\r\n  - 📊 场景分布 — scene counts (pie chart)\r\n- **Structured summary fields**: Each repo's info is displayed as separate `\u003Cp>\u003Cb>field\u003C\u002Fb>：value\u003C\u002Fp>` lines:\r\n  - 主语言 \u002F 语言分布 \u002F 分类 \u002F 场景 \u002F 一句话概括 \u002F 核心能力\r\n  - **All fields use Chinese AI-generated text** — `one_line_zh` replaces the English `short_description`, and `core_capability_zh` replaces the old `extract_capabilities()` English README extraction\r\n  - The `extract_capabilities()` import is no longer needed in `feishu_report.py`; only `strip_html` is imported from `trending_analyzer`\r\n- **Notification**: `--content` + `--msg-type post` JSON message via Feishu IM (NOT `--markdown`, NOT `--text`). Each line is a separate content element; title goes in `title` field. Includes summary stats, categories\u002Fscenes, and document link. See Pitfall 19 for the full pattern.\r\n\r\n```bash\r\npython feishu_report.py --analysis ~\u002F.hermes\u002Fgithub_trending_data\u002F2026-7\u002Fanalysis\u002F2026-7-5_analysis.json\r\n```\r\n\r\n### Report Generation (`generate_html.py` + `html2pdf.js`)\r\n\r\n**Architecture: HTML → PDF (not PptxGenJS).** The report is generated as a self-contained HTML file with a Linear-inspired dark design system, then rendered to PDF via puppeteer-core + system Edge browser headless. This replaced the old `generate_ppt.js` (PptxGenJS) pipeline because HTML\u002FCSS provides far more layout control and the user explicitly requested the switch.\r\n\r\n- **Design system**: Linear dark theme — `#08090a` background, Inter font with `cv01`\u002F`ss03` OpenType features, semi-transparent white borders (`rgba(255,255,255,0.08)`), indigo-violet accent (`#7170ff`). GitHub Linguist language colors for bar charts and card accent bars.\r\n- **Page system**: Each `.page` div is exactly 1280×720px with `overflow: hidden` and `page-break-after: always`, producing one PDF page per div. Fixed `height` (not `min-height`) is critical — `min-height` allows content overflow that creates extra blank pages.\r\n- **Slide layout**:\r\n  1. Cover — GitHub Octocat SVG + title + 3 stat cards (blue\u002Fgreen\u002Forange accent)\r\n  2. Overview — dual bar charts (language distribution Top 10 + category breakdown)\r\n  3-N. Project cards — 6 cards per page (2-column grid), with language accent bar, star count, AI Chinese descriptions, hot\u002Fcategory badges\r\n  N+1. Summary ranking table — all repos in a compact table (18 rows fit on one page with 3px row padding + 11px font)\r\n- **Card sizing**: `min-height: 140px; max-height: 165px` per card. Six cards (3 rows × 2 columns) at this height fit within the 720px page minus header\u002Ffooter. Gap reduced to 12px.\r\n- **Long project names**: CSS `text-overflow: ellipsis` with `white-space: nowrap` and `max-width: 220px` handles truncation natively — no JS truncation needed.\r\n\r\n```bash\r\n# Step 1: Generate HTML from analysis JSON\r\npython3 generate_html.py \u003Canalysis.json> \u003Coutput.html>\r\n\r\n# Step 2: Render HTML to PDF via Edge headless\r\nnode html2pdf.js \u003Coutput.html> \u003Coutput.pdf>\r\n\r\n# Step 3 (optional QA): Convert PDF pages to images for vision_analyze\r\npython3 pdf2img.py \u003Coutput.pdf>\r\n```\r\n\r\n### Orchestrator (`trending_orchestrator.py`)\r\n\r\nMain entry point for cron jobs. Determines target date (previous day\u002Fweek\u002Fmonth), collects data if missing, runs analysis, creates Feishu report, generates HTML+PDF report.\r\n\r\n```bash\r\npython trending_orchestrator.py --mode daily     # Analyze yesterday\r\npython trending_orchestrator.py --mode weekly    # Analyze last week\r\npython trending_orchestrator.py --mode monthly   # Analyze last month\r\npython trending_orchestrator.py --mode daily --skip-collect  # Use existing data only\r\n```\r\n\r\nThe orchestrator Step 3 calls `generate_html.py` (Python) then `html2pdf.js` (Node.js) to produce the PDF report.\r\n\r\n### Cron Schedule\r\n\r\n| Mode   | Cron          | Target                    |\r\n|--------|---------------|---------------------------|\r\n| Daily  | `0 9 * * *`   | Yesterday's data          |\r\n| Weekly | `0 10 * * 1`  | Last week's data          |\r\n| Monthly| `0 11 1 * *`  | Last month's data         |\r\n\r\n### Report Output\r\n\r\nReports are saved to `~\u002F.hermes\u002Fgithub_trending_data\u002Fppt\u002F`:\r\n- HTML: `Github项目{display_label}热度.html`\r\n- PDF: `Github项目{display_label}热度.pdf`\r\n- (e.g., `Github项目2026年7月5号热度.pdf`)\r\n\r\n## AI-Powered Classification (Recommended over Keyword Matching)\r\n\r\nThe keyword-based classification in `trending_analyzer.py` (word-boundary regex against topics\u002Fdescription\u002FREADME) produces **poor results in practice**: every repo gets tagged with 3-6 categories and multiple scenes, and the assignments are often nonsensical (e.g., a ROM manager tagged as \"前端开发\u002F安全审计\"; a photo manager tagged as \"Web\u002FFramework\u002FMobile\u002FApp\u002FGame\u002FMedia\u002FSystem\u002FLow-level\"). This makes the category\u002Fscene distribution counts meaningless for reports and PPT generation.\r\n\r\n**When to use AI classification instead:** any time you need accurate, human-quality category + scene + one-line Chinese description for the analysis output. The keyword classifier is acceptable as a fast first pass for bulk processing, but for published reports (Feishu docs, PPTs), always upgrade to AI classification.\r\n\r\n### Workflow: Parallel AI Delegation\r\n\r\n1. **Split repos into batches of 6** (18 repos → 3 batches). This balances parallelism against per-subagent token limits.\r\n2. **Write each batch to a temp JSON file** with compact fields: `repo_id`, `repo_name`, `stars`, `period_stars`, `languages`, `short_description`, `topics`, `detailed_summary_excerpt` (truncate README to ~800 chars).\r\n3. **Dispatch 3 parallel `delegate_task` subagents**, each classifying one batch. Each subagent reads its batch file and writes results to a `result_N.json` file. Output fields: `repo_id`, `category`, `scene`, `one_line_zh` (≤40 chars Chinese one-liner), `core_capability_zh` (≤60 chars Chinese core capability).\r\n4. **Merge results** back into the analysis JSON, replacing the keyword-based `categories`\u002F`scenes` fields with `ai_category`, `ai_scene`, `one_line_zh`, and `core_capability_zh`. Use `ai_classify_merge.py` for this.\r\n5. **Clean up temp files** (batch + result JSONs).\r\n\r\nThe full cron prompt template (tested on 2026-07-05, ready to copy) is in `templates\u002Fcron-prompt-template.md`. A step-by-step pipeline test procedure (reset → prepare → delegate → merge → verify → cleanup) is in `references\u002Fpipeline-test-procedure.md`.\r\n\r\n### Automated Pipeline (Cron Jobs)\r\n\r\nThe AI classification step is now baked into all three cron jobs (daily\u002Fweekly\u002Fmonthly). The cron prompt has a 3-step structure:\r\n\r\n| Step | Action | Toolset |\r\n|------|--------|---------|\r\n| 1 | Collect data + keyword analysis + HTML\u002FPDF generation (`trending_run.sh`) | terminal |\r\n| 2 | AI delegation classification (2a prepare → 2b parallel delegate → 2c merge) | terminal + delegation |\r\n| 3 | Report already generated in Step 1 (HTML→PDF) | — |\r\n\r\n**Critical cron config:** `enabled_toolsets` must include `\"delegation\"` alongside `\"terminal\"`. Without the delegation toolset, the cron agent cannot call `delegate_task` and will silently fall back to keyword-only classification.\r\n\r\n**Cron prompt structure for Step 2:**\r\n\r\n```\r\n### 2a. Prepare batches\r\npython3 ~\u002F.hermes\u002Fscripts\u002Fai_classify_prepare.py \u003Canalysis_json_path>\r\n\r\n### 2b. Delegate subagents (parallel)\r\nUse delegate_task with tasks=[...]. Each task reads \u003CBATCH_n_PATH> and writes result to \u003CRESULT_DIR>\u002Fresult_\u003Cn>.json\r\n\r\n### 2c. Merge results\r\npython3 ~\u002F.hermes\u002Fscripts\u002Fai_classify_merge.py \u003Canalysis_json_path> \u003CRESULT_DIR>\r\n```\r\n\r\n**Fallback:** If delegation fails, the keyword-based analysis from Step 1 is still usable — the analysis JSON will have `categories`\u002F`scenes` (multi-tag) but no `ai_category`\u002F`ai_scene`\u002F`one_line_zh`.\r\n\r\n### Taxonomy (8 categories, 10 scenes)\r\n\r\nThe AI classification uses a fixed taxonomy designed for GitHub trending repos. Each repo gets exactly ONE category and ONE scene (no multi-tagging):\r\n\r\n**Categories:** AI\u002FAgent生态, 开发工具, 安全\u002F隐私, 教育\u002F知识, 媒体\u002F娱乐, Web\u002F前端, 系统\u002F底层, 基础设施\r\n\r\n**Scenes:** AI编程助手, Agent技能与编排, 安全渗透与审计, 隐私保护与本地化, 学习与教育, 媒体管理与播放, 开发效率工具, 浏览器与Web自动化, 游戏开发, 系统提示词与AI研究\r\n\r\nSee `references\u002Fai-classification-workflow.md` for the full delegation prompt template, taxonomy definitions, and merge script pattern.\r\n\r\n## Pitfalls\r\n\r\n1. **Keyword classification floods categories** — Using `kw in text` for classification causes every repo to match every category, because short keywords like `\"ai\"`, `\"model\"`, `\"api\"`, `\"tool\"` appear as substrings inside common English words (`available`, `domain`, `capital`, etc.) and inside large README text. **Always use word-boundary regex** (`re.search(r'\\b' + re.escape(kw) + r'\\b', text)`) and match against high-signal text first (repo name + topics + description), only falling back to README if no high-signal match. **However, even with word-boundary regex, keyword classification still produces multi-category noise** — prefer AI delegation for published reports. See `references\u002Fai-classification-workflow.md` for the AI-based alternative.\r\n2. **Token redaction** — Hermes terminal tool redacts `gh auth token` output. Never try to capture the token string into Python; call `gh api` directly as a subprocess.\r\n3. **`\u002Ftmp` path mismatch** — On Windows git-bash, `\u002Ftmp` maps to `C:\\Users\\\u003Cuser>\\AppData\\Local\\Temp`, but Windows Python doesn't understand `\u002Ftmp`. Use `os.environ['TEMP']` or `os.path.expanduser()` in Python scripts.\r\n4. **README base64** — The `\u002Frepos\u002F{repo}\u002Freadme` endpoint returns base64-encoded content in the `content` field. Decode with `base64.b64decode()` before using.\r\n5. **Language percentages** — The `\u002Frepos\u002F{repo}\u002Flanguages` endpoint returns byte counts, not percentages. Divide each by the total byte count × 100.\r\n6. **`gh api` timeout** — Set subprocess timeout to 30s and retry 3 times with exponential backoff for transient TLS handshake timeouts.\r\n7. **PPT generation needs NODE_PATH** — `pptxgenjs` is installed globally via npm. Set `NODE_PATH=$(npm root -g)` before running `node generate_ppt.js`, or the module won't be found.\r\n8. **README content in summaries** — The README extraction pulls raw markdown including HTML tags. When building summaries, strip HTML tags from the first few lines to avoid cluttering output with `\u003Cp>`, `\u003Cimg>`, `\u003Ca>` tags.\r\n9. **Whitespace collapse destroys feature-list extraction** — `re.sub(r'\\s+', ' ', clean)` merges all newlines into a single line, which breaks downstream regex patterns that expect `^`\u002F`$` anchors or `\\n` delimiters (e.g., feature-list extraction `r'(?:^|\\n)#+\\s*Features?\\s*\\n(...)'`). Use `re.sub(r'[^\\S\\n]+', ' ', clean)` to collapse horizontal whitespace while preserving newlines.\r\n10. **HTML in detailed_summary** — The `detailed_summary` field contains the raw README which often includes inline HTML (`\u003Cp>`, `\u003Ca>`, `\u003Cimg>`, `\u003Cpicture>`, `\u003Csource>`). Always run `strip_html()` (tag removal + entity decode) before using the README text for classification, capability extraction, or summary generation.\r\n11. **lark-cli `.CMD` on Windows** — Python's `subprocess.run([\"lark-cli\", ...])` fails on Windows because lark-cli is a `.CMD` shim. Use `shutil.which(\"lark-cli\")` to resolve the full path (returns `lark-cli.CMD`), then pass that to subprocess.\r\n12. **lark-cli `@file` requires relative paths** — The `--content @file` flag in lark-cli docs requires a path relative to CWD, NOT an absolute temp path. Write temp content files to `os.getcwd()` and reference them by filename only.\r\n13. **Duplicate `\u003Ctitle>` tag** — `build_feishu_doc_content()` must NOT include `\u003Ctitle>...\u003C\u002Ftitle>` in the XML content body. The `--title` flag in `lark-cli docs +create` already prepends `\u003Ctitle>` automatically. Adding it in both places causes a duplicate title tag and the API may reject the document.\r\n14. **`extract_capabilities` no longer needed in `feishu_report.py`** — After switching to AI-generated `core_capability_zh`, the `extract_capabilities()` import was removed from `feishu_report.py`. Only `strip_html` is still imported from `trending_analyzer`. If you re-add English capability extraction, add `sys.path.insert(0, SCRIPTS_DIR)` + `from trending_analyzer import extract_capabilities, strip_html`.\r\n15. **lark-cli identity scope split** — The Feishu app has a split scope situation: `user` identity can create documents (`docx:document:create`) but CANNOT send IM messages (missing `im:message.send_as_user` scope); `bot` identity can send IM messages but CANNOT create documents (missing `docx:document` scope). Both `create_feishu_doc()` and `send_notification()` must try `user` first, then fall back to `bot`. Do NOT assume a single identity works for both operations.\r\n16. **`patch` tool doubles backslash-quote in f-strings** — When using the `patch` tool to edit Python f-strings containing `href=\\\"...\\\"` patterns, the tool can introduce extra backslash escaping (`href=\\\\\\\"...\\\\\\\"` instead of `href=\\\"...\\\"`). After patching Python files with quoted XML attributes, verify the result with `python3 -c \"import module\"` and fix any doubled backslashes with `execute_code` byte-level replacement if needed.\r\n17. **Feishu Mermaid pie charts need `\u003Cwhiteboard type=\"mermaid\">`** — To render pie charts in Feishu documents, wrap Mermaid `pie` syntax in `\u003Cwhiteboard type=\"mermaid\">...\u003C\u002Fwhiteboard>`. Do NOT use `\u003Cpre>` or `\u003Ccode>` blocks for Mermaid — they render as plain text, not charts. The Mermaid syntax is: `pie title \u003Ctitle>\\n    \"Label\" : \u003Cvalue>\\n    ...`.\r\n18. **Content size shrinks dramatically after AI Chinese fields** — Switching from English README excerpts to AI-generated `one_line_zh` + `core_capability_zh` reduced document content from ~30K chars to ~19.6K chars while improving readability. This is expected — the English `detailed_summary` and `extract_capabilities()` output was verbose and noisy.\r\n19. **Feishu IM notification: `--content` + post JSON is the ONLY reliable method (user corrected 5+ times)** — When sending IM notifications via `lark-cli im +messages-send --as bot`, there are three content flag options:\r\n    - `--text` — sends `msg_type=text`. **Collapses to title-only** on both mobile and desktop. Multi-line content is NOT visible. **Never use for multi-line notifications.**\r\n    - `--markdown` — sends `msg_type=post` wrapping content as a single `{\"tag\":\"md\",\"text\":\"line1\\nline2\"}` element. **ALSO collapses to title-only** on some Feishu clients. **Do NOT use `--markdown` for multi-line notifications** — user explicitly rejected this multiple times.\r\n    - `--content` with `--msg-type post` — **THE ONLY RELIABLE METHOD.** Each line MUST be a separate content element. The title goes in the `title` field, NOT duplicated in the content body. The correct pattern:\r\n      ```python\r\n      def build_post_json(title, text):\r\n          lines = text.strip().split(\"\\n\")\r\n          content = []\r\n          for line in lines:\r\n              if not line.strip():\r\n                  continue\r\n              if line.startswith(\"http\"):\r\n                  content.append([{\"tag\": \"a\", \"text\": line, \"href\": line}])\r\n              else:\r\n                  content.append([{\"tag\": \"text\", \"text\": line}])\r\n          return {\"zh_cn\": {\"title\": title, \"content\": content}}\r\n\r\n      post_json = build_post_json(\"标题\", text)\r\n      # Send:\r\n      lark_cli(\"im\", \"+messages-send\", \"--as\", \"bot\", \"--user-id\", ou_xxx,\r\n               \"--msg-type\", \"post\",\r\n               \"--content\", json.dumps(post_json, ensure_ascii=False))\r\n      ```\r\n    **Key rules:** (1) Each line of text MUST be a separate `[{\"tag\":\"text\",\"text\":\"...\"}]` array — putting `\\n`-separated text in a single element does NOT work. (2) URL lines use `{\"tag\":\"a\",\"text\":\"url\",\"href\":\"url\"}`. (3) Title goes in `title` field only, do NOT repeat it as the first content line.\r\n    **Verified 2026-07-05:** User mobile + desktop screenshots confirmed `--content` + post JSON with per-line elements renders full multi-line content reliably. `--markdown` and `--text` both collapsed to title-only. User explicitly demanded `--content + 完整 post JSON` and rejected `--markdown` 5+ times.\r\n20. **Notification content should use AI Chinese fields** — The `build_notification_text()` function should use `one_line_zh` (not `short_description`) for project descriptions in the IM notification, and should filter categories\u002Fscenes to non-zero counts only (`[k for k,v in analysis[\"categories\"].items() if v > 0]`). Include hot projects in the notification (not just new projects) since hot projects have `period_stars` data users care about.\r\n21. **`hot_projects` and `new_projects` lack AI fields after merge** — The `ai_classify_merge.py` script only enriches `analysis[\"repos\"]` with `ai_category`\u002F`ai_scene`\u002F`one_line_zh`\u002F`core_capability_zh`. The `analysis[\"hot_projects\"]` and `analysis[\"new_projects\"]` arrays are separate references built by `trending_analyzer.py` and do NOT automatically inherit AI fields. After merging, **you must manually enrich these arrays** by looking up each project's `repo_id` in the main `repos` list and copying the AI fields:\r\n    ```python\r\n    repos_map = {r[\"repo_id\"]: r for r in analysis[\"repos\"]}\r\n    for p in analysis.get(\"hot_projects\", []) + analysis.get(\"new_projects\", []):\r\n        r = repos_map.get(p[\"repo_id\"])\r\n        if r:\r\n            p[\"one_line_zh\"] = r.get(\"one_line_zh\", \"\")\r\n            p[\"core_capability_zh\"] = r.get(\"core_capability_zh\", \"\")\r\n    ```\r\n    Without this step, `build_notification_text()` and `format_repo_summary_lines()` will fall back to English `short_description` for hot\u002Fnew projects even though AI Chinese fields exist on the main repos.\r\n22. **pptxgenjs `wrap: false` does NOT clip text** — It only prevents line breaks within the textbox. Text still renders beyond the textbox boundary horizontally, causing overlap with adjacent elements (star icons, shapes). Fix by manually truncating long strings (`name.substring(0, 14) + \"…\"`) and reducing font size. Do NOT rely on `autoFit: true` — it is unreliable in LibreOffice rendering.\r\n23. **Vision QA false positives at 1440x811 resolution** — Vision models at low render resolution misidentify truncated text as full text, and small font differences as identical. When vision QA reports issues that seem wrong, verify by unzipping the .pptx and inspecting slide XML: `re.findall(r'\u003Ca:t>([^\u003C]*)\u003C\u002Fa:t>', xml)` for text content, `sz=\"(\\d+)\"` for font size (1200=12pt), `\u003Ca:ext cx=\"(\\d+)\"` for textbox width in EMUs (914400 per inch). XML is ground truth.\r\n24. **LibreOffice locks .pptx after conversion** — After `soffice --headless --convert-to pdf`, the soffice process may keep a file lock. Regenerating the same file fails with `EBUSY`. Kill the process first (`taskkill \u002F\u002FF \u002F\u002FIM soffice.bin` on Windows) or output to a different filename.\r\n25. **PyMuPDF as pdftoppm alternative** — When Poppler's `pdftoppm` is unavailable, use `pip install pymupdf` then `fitz.open(\"file.pdf\")` + `page.get_pixmap(dpi=150)` to convert PDF slides to images for visual QA.\r\n26. **PPT icon colors must match accent bars** — Each stat card icon must be rendered in the same color as its accent bar. A mismatch (e.g., orange rocket icon on a green-accented card) is immediately visible. Pass the hex color to `iconToBase64Png(IconComponent, iconColor, 256)`.\r\n27. **HTML→PDF pagination: use fixed `height` not `min-height`** — When generating PDFs from HTML with puppeteer-core, `.page` divs must use `height: 720px; overflow: hidden` (NOT `min-height`). `min-height` allows content to grow beyond the page boundary, creating extra blank PDF pages. The `page-break-after: always` CSS property handles page splitting between `.page` divs.\r\n28. **Card pagination: 6 per page at 140-165px height** — For a 1280×720px page with ~60px header + ~30px footer, 6 project cards (3 rows × 2 columns) fit at `min-height: 140px; max-height: 165px` with 12px gap. More than 6 cards per page causes overflow; fewer wastes space.\r\n29. **Table fitting: compact row padding for 18 rows** — An 18-row summary table fits on one 720px page with `td padding: 3px 10px; font-size: 11px; line-height: 1.3`. Default `padding: 8px 16px` causes the table to overflow to a second page, losing rows.\r\n30. **puppeteer-core requires explicit `executablePath`** — `puppeteer.launch()` without `executablePath` fails with \"No Chrome\u002FEdge executable found\". On Windows, detect Edge at `C:\\Program Files (x86)\\Microsoft\\Edge\\Application\\msedge.exe` and pass it to `launch()`. No `npm install puppeteer` needed — `puppeteer-core` uses the system browser.\r\n31. **HTML report replaces PptxGenJS** — The old `generate_ppt.js` pipeline (PptxGenJS → .pptx → LibreOffice → PDF) is deprecated. The new pipeline is `generate_html.py` (Python) → `html2pdf.js` (puppeteer-core + Edge). The HTML\u002FCSS approach provides better layout control (CSS Grid, flexbox, `overflow: hidden`), native text truncation via `text-overflow: ellipsis`, and eliminates the LibreOffice rendering inconsistencies that plagued the PptxGenJS pipeline (wrap:false not working, autoFit unreliable, icon color mismatches).\r\n32. **Feishu Drive folder management requires additional OAuth scopes** — Creating folders (`drive +create-folder`) and listing folder contents (`drive files list`) require scopes not included in the default auth: `drive:drive` + `space:folder:create` (for folder creation), `space:document:retrieve` (for listing folder contents). Run `lark-cli auth login --scope \"drive:drive\" --scope \"space:folder:create\" --scope \"space:document:retrieve\"` and have the user authorize via QR code. **Do NOT use `drive +search`** — it requires `search:docs:read` which is an admin-managed scope that cannot be self-authorized. Use `drive files list --folder-token \u003Ctoken>` instead (only needs `space:document:retrieve`).\r\n33. **Folder token cache prevents redundant API calls** — `feishu_folders.json` at `~\u002F.hermes\u002Fgithub_trending_data\u002F` stores `{ \"root\": \"\u003Ctoken>\", \"month_2026-7\": \"\u003Ctoken>\" }`. The `ensure_folder()` function checks the cache first before listing\u002Fcreating. If a cached token becomes stale (e.g., folder deleted manually), the doc creation with `--parent-token` will fail — delete the cache file to force a fresh search.\r\n34. **`docs +create --parent-token` does NOT reliably place docs in folders — use `drive +move` after creation**\r\n35. **Check for existing docs before creating — delete duplicates first** — Before creating a new Feishu document, list the target folder contents via `drive files list --folder-token \u003Ctoken>` and look for a child with the same name. If found, delete it with `drive +delete --file-token \u003Ctoken> --type docx --yes` before creating the new one. This prevents duplicate documents accumulating in the folder across re-runs. The `create_feishu_doc()` function calls `find_child_by_name(parent_token, title, child_type=\"docx\")` and `delete_file_by_token()` before creating.\r\n36. **Use `drive files list` NOT `drive +search` for folder\u002Ffile checks** — `drive +search` requires `search:docs:read` scope (admin-managed, cannot self-authorize). `drive files list --folder-token \u003Ctoken>` only needs `space:document:retrieve` scope (user-authorizable). The `list_folder_contents()` function wraps `drive files list` and returns `[{name, token, type, ...}]`. Use `find_child_by_name(folder_token, name, child_type)` to check for existing folders or docs by name within a specific folder. — The Feishu API accepts the `--parent-token` parameter (visible in `--dry-run` output as `parent_token` in the request body), but the created document is **NOT** actually placed inside the specified folder. Verified 2026-07-05: three test documents created with `--parent-token` all landed in Drive root, not the target folder. **The reliable method is a two-step sequence:**\r\n    ```python\r\n    # Step 1: Create doc WITHOUT --parent-token\r\n    result = run_lark_cli([\"docs\", \"+create\", \"--as\", identity,\r\n                          \"--title\", title, \"--content\", f\"@{tmp_name}\"])\r\n    doc_id = result[\"data\"][\"document\"][\"document_id\"]\r\n\r\n    # Step 2: Move doc into target folder\r\n    if parent_token and doc_id:\r\n        run_lark_cli([\"drive\", \"+move\", \"--as\", identity,\r\n                      \"--file-token\", doc_id, \"--type\", \"docx\",\r\n                      \"--folder-token\", parent_token])\r\n    ```\r\n    This is a Feishu API-level limitation, not a lark-cli bug. The `feishu_report.py` `create_feishu_doc()` function implements this create-then-move pattern.","# GitHub Trending Data Collector\r\n\r\nCollect GitHub Trending repository data across three time periods (daily, weekly, monthly), enrich each repo with full GitHub API metadata, and save as structured JSON files. Designed for scheduled (cron) execution.\r\n\r\n## When to Use\r\n\r\n- User asks to collect\u002Fscrape GitHub trending repos\r\n- User wants scheduled trending data collection (cron job)\r\n- User asks for trending project popularity\u002Fheat data\r\n- User needs repo data fields: name, ID, URL, language breakdown, stars, forks, description, README summary, owner info\r\n- User wants to analyze trending data (new projects, categories, hot projects)\r\n- User wants Feishu reports or PDF visual reports from trending data\r\n- User asks to set up automated trending report pipeline (cron + Feishu + PDF)\r\n\r\n## When NOT to Use\r\n\r\n- Querying a single known repo → use `gh api repos\u002Fowner\u002Frepo` directly\r\n- General repo CRUD (clone\u002Fcreate\u002Ffork) → use `github-repo-management`\r\n- GitHub PR\u002Fissue workflows → use `github-pr-workflow` \u002F `github-issues`\r\n\r\n## Architecture\r\n\r\n```\r\nGitHub Trending HTML → parse repo list → gh api enrichment per repo → structured JSON\r\n         ↑                                    ↓\r\n    urllib.request                   \u002Frepos\u002F{repo}           → stars, forks, description, topics, owner\r\n    (trending page only)             \u002Frepos\u002F{repo}\u002Flanguages  → language byte counts → percentage\r\n                                     \u002Frepos\u002F{repo}\u002Freadme     → README (base64) → detailed summary\r\n                                     \u002Fusers\u002F{owner}           → owner GitHub ID + URL\r\n```\r\n\r\n## Critical Decision: `gh api` over `urllib` on Windows\r\n\r\n**Always use `gh api` (subprocess) for GitHub API calls on Windows.** `urllib.request` fails with intermittent SSL\u002FTLS errors (`UNEXPECTED_EOF_WHILE_READING`, `TLS handshake timeout`) against `api.github.com`. The `gh` CLI handles SSL, auth, and retries internally and is dramatically more reliable.\r\n\r\nThe trending **HTML page** itself can be fetched via `urllib.request` — only the API endpoint has SSL issues.\r\n\r\n### Token Redaction Pitfall\r\n\r\nThe Hermes `terminal` tool **redacts** `gh auth token` output — it appears as `gho_6L...427S` (truncated). Do NOT attempt to capture the token into a Python variable via `terminal()`. Instead, call `gh api` as a subprocess from Python:\r\n\r\n```python\r\nresult = subprocess.run([\"gh\", \"api\", endpoint], capture_output=True, text=True, timeout=30)\r\ndata = json.loads(result.stdout)\r\n```\r\n\r\n## File Path Convention\r\n\r\nData is saved under `~\u002F.hermes\u002Fgithub_trending_data\u002FYYYY-M\u002F`:\r\n\r\n| Period   | Filename Pattern             | Example                     | When Updated          |\r\n|----------|------------------------------|-----------------------------|-----------------------|\r\n| Daily    | `YYYY-M-D.json`             | `2026-7\u002F2026-7-5.json`      | Every day             |\r\n| Weekly   | `YYYY-M-W.json` (W=week #)  | `2026-7\u002F2026-7-1.json`      | Every Monday (or first run in week) |\r\n| Monthly  | `YYYY-M.json`                | `2026-7\u002F2026-7.json`        | 1st of month (or first run) |\r\n\r\nWeek-of-month = `((day - 1) \u002F\u002F 7) + 1` — so days 1-7 = week 1, 8-14 = week 2, etc.\r\n\r\nThe script has built-in skip logic: if the target file already exists, that period is skipped (prevents redundant re-collection within the same day\u002Fweek\u002Fmonth). Use `--force` to override.\r\n\r\n## Output Data Schema\r\n\r\nEach JSON file contains:\r\n\r\n```json\r\n{\r\n  \"period\": \"daily|weekly|monthly\",\r\n  \"collected_at\": \"2026-07-05T12:45:15.205702\",\r\n  \"total_repos\": 18,\r\n  \"repos\": [\r\n    {\r\n      \"repo_name\": \"codex-plugin-cc\",\r\n      \"repo_id\": \"openai\u002Fcodex-plugin-cc\",\r\n      \"repo_url\": \"https:\u002F\u002Fgithub.com\u002Fopenai\u002Fcodex-plugin-cc\",\r\n      \"languages\": {\"JavaScript\": 100.0},\r\n      \"stars\": 24691,\r\n      \"forks\": 1495,\r\n      \"short_description\": \"Use Codex from Claude Code to review code or delegate tasks.\",\r\n      \"detailed_summary\": \"# Codex plugin for Claude Code\\n...(README, truncated to 5000 chars)\",\r\n      \"owner\": {\r\n        \"login\": \"openai\",\r\n        \"github_id\": 14957082,\r\n        \"github_url\": \"https:\u002F\u002Fgithub.com\u002Fopenai\"\r\n      },\r\n      \"topics\": [],\r\n      \"homepage\": \"\",\r\n      \"license\": \"Apache License 2.0\",\r\n      \"created_at\": \"2026-03-30T15:29:52Z\",\r\n      \"updated_at\": \"2026-07-05T04:39:04Z\",\r\n      \"period_stars\": 718\r\n    }\r\n  ]\r\n}\r\n```\r\n\r\n## Running the Collector\r\n\r\n### One-time \u002F manual run\r\n\r\n```bash\r\n# Collect all periods (skips existing files)\r\npython \u003CHERMES_HOME>\u002Fscripts\u002Fgithub_trending.py --period all\r\n\r\n# Force re-collect all periods\r\npython \u003CHERMES_HOME>\u002Fscripts\u002Fgithub_trending.py --period all --force\r\n\r\n# Collect only daily\r\npython \u003CHERMES_HOME>\u002Fscripts\u002Fgithub_trending.py --period daily\r\n```\r\n\r\n### Scheduled (cron)\r\n\r\nCreate a daily cron job at 09:00:\r\n\r\n```\r\nSchedule: 0 9 * * *\r\nPrompt: Run `python \u003CHERMES_HOME>\u002Fscripts\u002Fgithub_trending.py --period all`\r\n```\r\n\r\nThe script's skip logic means daily data updates every day, weekly data updates on the first run of each week, and monthly data updates on the first run of each month — all from the same daily cron trigger.\r\n\r\n> **Note:** Cron jobs in Hermes TUI sessions are local-only. Output is saved but not delivered to the session. For notifications, set `deliver` to a gateway-connected platform (e.g., `telegram`).\r\n\r\n## Performance Notes\r\n\r\n- ~18-25 repos per trending page (daily\u002Fweekly\u002Fmonthly vary)\r\n- 4 API calls per repo (details + languages + readme + owner) = ~80-100 calls total\r\n- 0.5s delay between API calls = ~1-2 minutes per period\r\n- Total runtime for all 3 periods: ~5-7 minutes\r\n- GitHub API rate limit: 5000 req\u002Fhour with auth (well within limits)\r\n\r\n## Files\r\n\r\n### Skill scripts\r\n- `scripts\u002Fgithub_trending.py` — the complete collector script (standalone, re-runnable)\r\n\r\n### Pipeline scripts (in `~\u002F.hermes\u002Fscripts\u002F`)\r\n- `trending_analyzer.py` — analysis engine (new projects, categorization, hot projects)\r\n- `ai_classify_prepare.py` — splits analysis repos into batches of 6, outputs batch paths for AI delegation\r\n- `ai_classify_merge.py` — merges AI classification results back into analysis JSON, recomputes distributions\r\n- `feishu_report.py` — Feishu document creation + IM notification\r\n- `generate_html.py` — HTML report generator (Python, Linear dark theme design system) — **replaces `generate_ppt.js`**\r\n- `html2pdf.js` — HTML→PDF converter (puppeteer-core + system Edge browser, 1280×720px pages) — **replaces LibreOffice PPTX conversion**\r\n- `pdf2img.py` — PDF→JPEG image converter (PyMuPDF, for vision QA)\r\n- `trending_orchestrator.py` — main orchestrator for cron jobs\r\n- `trending_run.sh` — bash wrapper (sets up environment and calls orchestrator)\r\n\r\n### References\r\n- `references\u002Ftrending-page-structure.md` — HTML parsing details, API endpoints, Windows SSL workaround\r\n- `references\u002Fpipeline-scripts.md` — detailed design decisions for all pipeline scripts (analyzer, feishu, PPT, orchestrator)\r\n- `references\u002Fai-classification-workflow.md` — AI delegation taxonomy, prompt template, and merge script for accurate repo classification\r\n- `references\u002Fpipeline-test-procedure.md` — step-by-step end-to-end test procedure (reset → prepare → delegate → merge → verify → cleanup) with expected timing and troubleshooting\r\n- `references\u002Ffeishu-drive-folder-management.md` — Feishu Drive folder hierarchy (root + monthly subfolders), local token cache, required OAuth scopes, and `ensure_report_folder()` design\r\n\r\n### Templates\r\n- `templates\u002Fcron-prompt-template.md` — full tested cron job prompt (3-step pipeline) ready to copy, with cron config table and validation results\r\n\r\n## Full Report Pipeline (Collect → Analyze → Feishu → HTML\u002FPDF Report)\r\n\r\nThe collector is the first stage of a full trending report pipeline. After data collection, three additional scripts process the data into Feishu documents and PPT reports. All pipeline scripts live in `~\u002F.hermes\u002Fscripts\u002F`.\r\n\r\n### Pipeline Architecture\r\n\r\n```\r\ngithub_trending.py  →  trending_analyzer.py  →  feishu_report.py\r\n(collect data)          (analyze + classify)     (Feishu doc + IM notify)\r\n                                                   ↓\r\n                                             generate_html.py\r\n                                             (Linear dark theme HTML report)\r\n                                                   ↓\r\n                                             html2pdf.js\r\n                                             (puppeteer-core + Edge → PDF)\r\n                                                   ↓\r\n                                             trending_orchestrator.py\r\n                                             (orchestrates all of the above)\r\n```\r\n\r\n### Analysis (`trending_analyzer.py`)\r\n\r\nThe analyzer reads collected JSON and produces structured analysis:\r\n\r\n- **New project detection**: Scans all previous period data files to identify repos that have never appeared before. A repo is \"new\" if its `repo_id` doesn't exist in any prior same-period file.\r\n- **Categorization**: Classifies each repo into categories (AI\u002FML, Developer Tools, Web\u002FFramework, Data\u002FDatabase, Security, DevOps\u002FInfra, Mobile\u002FApp, Game\u002FMedia, Blockchain, System\u002FLow-level) and scenes (代码生成与辅助, 模型推理与部署, etc.) using **word-boundary regex matching** (`\\b...\\b`) against a two-tier text source: first high-signal text (repo name, topics, short description), then a cleaned README excerpt as fallback. HTML tags are stripped from the README before matching. See `references\u002Fpipeline-scripts.md` for the full classification design and the pitfalls of naive substring matching.\r\n- **Hot project detection**: Flags repos with `period_stars ≥ threshold`. Thresholds: daily ≥1000, weekly ≥5000, monthly ≥10000.\r\n- **Project summary generation**: Extracts capabilities from cleaned (HTML-stripped) README, identifies primary language, categories, and scenes.\r\n\r\n```bash\r\n# Analyze a specific date\r\npython trending_analyzer.py --period daily --date 2026-7-5 --save\r\n# Output: ~\u002F.hermes\u002Fgithub_trending_data\u002F2026-7\u002Fanalysis\u002F2026-7-5_analysis.json\r\n```\r\n\r\n### Feishu Report (`feishu_report.py`)\r\n\r\nCreates a Feishu document with the analysis and sends a notification message:\r\n\r\n- **Drive folder management**: Documents are organized in a hierarchical folder structure in Feishu Drive — root folder \"GitHub Trending\" → monthly subfolder (e.g., \"2026-7\"). Folder tokens are cached locally in `~\u002F.hermes\u002Fgithub_trending_data\u002Ffeishu_folders.json` to avoid repeated API calls. The `ensure_report_folder()` function is called before document creation to get the target folder token. **Important:** `docs +create --parent-token` does NOT reliably place documents into folders (Feishu API limitation). The `create_feishu_doc()` function uses a create-then-move pattern: creates the doc without `--parent-token`, then immediately calls `drive +move` to move it into the target folder. See `references\u002Ffeishu-drive-folder-management.md` for the full implementation and scope requirements.\r\n- **Document**: XML content with sections: 总体概览 (overview + **Mermaid pie charts** for language\u002Fcategory\u002Fscene distributions + hot projects), 项目列表 (full repo list with **structured multi-line fields**), 新秀项目 (new projects).\r\n- **Mermaid pie charts**: Three `\u003Cwhiteboard type=\"mermaid\">` blocks render as native Feishu whiteboards:\r\n  - 📊 语言分布 — top 10 languages + \"其他\" group (pie chart)\r\n  - 📊 分类分布 — AI category counts (pie chart)\r\n  - 📊 场景分布 — scene counts (pie chart)\r\n- **Structured summary fields**: Each repo's info is displayed as separate `\u003Cp>\u003Cb>field\u003C\u002Fb>：value\u003C\u002Fp>` lines:\r\n  - 主语言 \u002F 语言分布 \u002F 分类 \u002F 场景 \u002F 一句话概括 \u002F 核心能力\r\n  - **All fields use Chinese AI-generated text** — `one_line_zh` replaces the English `short_description`, and `core_capability_zh` replaces the old `extract_capabilities()` English README extraction\r\n  - The `extract_capabilities()` import is no longer needed in `feishu_report.py`; only `strip_html` is imported from `trending_analyzer`\r\n- **Notification**: `--content` + `--msg-type post` JSON message via Feishu IM (NOT `--markdown`, NOT `--text`). Each line is a separate content element; title goes in `title` field. Includes summary stats, categories\u002Fscenes, and document link. See Pitfall 19 for the full pattern.\r\n\r\n```bash\r\npython feishu_report.py --analysis ~\u002F.hermes\u002Fgithub_trending_data\u002F2026-7\u002Fanalysis\u002F2026-7-5_analysis.json\r\n```\r\n\r\n### Report Generation (`generate_html.py` + `html2pdf.js`)\r\n\r\n**Architecture: HTML → PDF (not PptxGenJS).** The report is generated as a self-contained HTML file with a Linear-inspired dark design system, then rendered to PDF via puppeteer-core + system Edge browser headless. This replaced the old `generate_ppt.js` (PptxGenJS) pipeline because HTML\u002FCSS provides far more layout control and the user explicitly requested the switch.\r\n\r\n- **Design system**: Linear dark theme — `#08090a` background, Inter font with `cv01`\u002F`ss03` OpenType features, semi-transparent white borders (`rgba(255,255,255,0.08)`), indigo-violet accent (`#7170ff`). GitHub Linguist language colors for bar charts and card accent bars.\r\n- **Page system**: Each `.page` div is exactly 1280×720px with `overflow: hidden` and `page-break-after: always`, producing one PDF page per div. Fixed `height` (not `min-height`) is critical — `min-height` allows content overflow that creates extra blank pages.\r\n- **Slide layout**:\r\n  1. Cover — GitHub Octocat SVG + title + 3 stat cards (blue\u002Fgreen\u002Forange accent)\r\n  2. Overview — dual bar charts (language distribution Top 10 + category breakdown)\r\n  3-N. Project cards — 6 cards per page (2-column grid), with language accent bar, star count, AI Chinese descriptions, hot\u002Fcategory badges\r\n  N+1. Summary ranking table — all repos in a compact table (18 rows fit on one page with 3px row padding + 11px font)\r\n- **Card sizing**: `min-height: 140px; max-height: 165px` per card. Six cards (3 rows × 2 columns) at this height fit within the 720px page minus header\u002Ffooter. Gap reduced to 12px.\r\n- **Long project names**: CSS `text-overflow: ellipsis` with `white-space: nowrap` and `max-width: 220px` handles truncation natively — no JS truncation needed.\r\n\r\n```bash\r\n# Step 1: Generate HTML from analysis JSON\r\npython3 generate_html.py \u003Canalysis.json> \u003Coutput.html>\r\n\r\n# Step 2: Render HTML to PDF via Edge headless\r\nnode html2pdf.js \u003Coutput.html> \u003Coutput.pdf>\r\n\r\n# Step 3 (optional QA): Convert PDF pages to images for vision_analyze\r\npython3 pdf2img.py \u003Coutput.pdf>\r\n```\r\n\r\n### Orchestrator (`trending_orchestrator.py`)\r\n\r\nMain entry point for cron jobs. Determines target date (previous day\u002Fweek\u002Fmonth), collects data if missing, runs analysis, creates Feishu report, generates HTML+PDF report.\r\n\r\n```bash\r\npython trending_orchestrator.py --mode daily     # Analyze yesterday\r\npython trending_orchestrator.py --mode weekly    # Analyze last week\r\npython trending_orchestrator.py --mode monthly   # Analyze last month\r\npython trending_orchestrator.py --mode daily --skip-collect  # Use existing data only\r\n```\r\n\r\nThe orchestrator Step 3 calls `generate_html.py` (Python) then `html2pdf.js` (Node.js) to produce the PDF report.\r\n\r\n### Cron Schedule\r\n\r\n| Mode   | Cron          | Target                    |\r\n|--------|---------------|---------------------------|\r\n| Daily  | `0 9 * * *`   | Yesterday's data          |\r\n| Weekly | `0 10 * * 1`  | Last week's data          |\r\n| Monthly| `0 11 1 * *`  | Last month's data         |\r\n\r\n### Report Output\r\n\r\nReports are saved to `~\u002F.hermes\u002Fgithub_trending_data\u002Fppt\u002F`:\r\n- HTML: `Github项目{display_label}热度.html`\r\n- PDF: `Github项目{display_label}热度.pdf`\r\n- (e.g., `Github项目2026年7月5号热度.pdf`)\r\n\r\n## AI-Powered Classification (Recommended over Keyword Matching)\r\n\r\nThe keyword-based classification in `trending_analyzer.py` (word-boundary regex against topics\u002Fdescription\u002FREADME) produces **poor results in practice**: every repo gets tagged with 3-6 categories and multiple scenes, and the assignments are often nonsensical (e.g., a ROM manager tagged as \"前端开发\u002F安全审计\"; a photo manager tagged as \"Web\u002FFramework\u002FMobile\u002FApp\u002FGame\u002FMedia\u002FSystem\u002FLow-level\"). This makes the category\u002Fscene distribution counts meaningless for reports and PPT generation.\r\n\r\n**When to use AI classification instead:** any time you need accurate, human-quality category + scene + one-line Chinese description for the analysis output. The keyword classifier is acceptable as a fast first pass for bulk processing, but for published reports (Feishu docs, PPTs), always upgrade to AI classification.\r\n\r\n### Workflow: Parallel AI Delegation\r\n\r\n1. **Split repos into batches of 6** (18 repos → 3 batches). This balances parallelism against per-subagent token limits.\r\n2. **Write each batch to a temp JSON file** with compact fields: `repo_id`, `repo_name`, `stars`, `period_stars`, `languages`, `short_description`, `topics`, `detailed_summary_excerpt` (truncate README to ~800 chars).\r\n3. **Dispatch 3 parallel `delegate_task` subagents**, each classifying one batch. Each subagent reads its batch file and writes results to a `result_N.json` file. Output fields: `repo_id`, `category`, `scene`, `one_line_zh` (≤40 chars Chinese one-liner), `core_capability_zh` (≤60 chars Chinese core capability).\r\n4. **Merge results** back into the analysis JSON, replacing the keyword-based `categories`\u002F`scenes` fields with `ai_category`, `ai_scene`, `one_line_zh`, and `core_capability_zh`. Use `ai_classify_merge.py` for this.\r\n5. **Clean up temp files** (batch + result JSONs).\r\n\r\nThe full cron prompt template (tested on 2026-07-05, ready to copy) is in `templates\u002Fcron-prompt-template.md`. A step-by-step pipeline test procedure (reset → prepare → delegate → merge → verify → cleanup) is in `references\u002Fpipeline-test-procedure.md`.\r\n\r\n### Automated Pipeline (Cron Jobs)\r\n\r\nThe AI classification step is now baked into all three cron jobs (daily\u002Fweekly\u002Fmonthly). The cron prompt has a 3-step structure:\r\n\r\n| Step | Action | Toolset |\r\n|------|--------|---------|\r\n| 1 | Collect data + keyword analysis + HTML\u002FPDF generation (`trending_run.sh`) | terminal |\r\n| 2 | AI delegation classification (2a prepare → 2b parallel delegate → 2c merge) | terminal + delegation |\r\n| 3 | Report already generated in Step 1 (HTML→PDF) | — |\r\n\r\n**Critical cron config:** `enabled_toolsets` must include `\"delegation\"` alongside `\"terminal\"`. Without the delegation toolset, the cron agent cannot call `delegate_task` and will silently fall back to keyword-only classification.\r\n\r\n**Cron prompt structure for Step 2:**\r\n\r\n```\r\n### 2a. Prepare batches\r\npython3 ~\u002F.hermes\u002Fscripts\u002Fai_classify_prepare.py \u003Canalysis_json_path>\r\n\r\n### 2b. Delegate subagents (parallel)\r\nUse delegate_task with tasks=[...]. Each task reads \u003CBATCH_n_PATH> and writes result to \u003CRESULT_DIR>\u002Fresult_\u003Cn>.json\r\n\r\n### 2c. Merge results\r\npython3 ~\u002F.hermes\u002Fscripts\u002Fai_classify_merge.py \u003Canalysis_json_path> \u003CRESULT_DIR>\r\n```\r\n\r\n**Fallback:** If delegation fails, the keyword-based analysis from Step 1 is still usable — the analysis JSON will have `categories`\u002F`scenes` (multi-tag) but no `ai_category`\u002F`ai_scene`\u002F`one_line_zh`.\r\n\r\n### Taxonomy (8 categories, 10 scenes)\r\n\r\nThe AI classification uses a fixed taxonomy designed for GitHub trending repos. Each repo gets exactly ONE category and ONE scene (no multi-tagging):\r\n\r\n**Categories:** AI\u002FAgent生态, 开发工具, 安全\u002F隐私, 教育\u002F知识, 媒体\u002F娱乐, Web\u002F前端, 系统\u002F底层, 基础设施\r\n\r\n**Scenes:** AI编程助手, Agent技能与编排, 安全渗透与审计, 隐私保护与本地化, 学习与教育, 媒体管理与播放, 开发效率工具, 浏览器与Web自动化, 游戏开发, 系统提示词与AI研究\r\n\r\nSee `references\u002Fai-classification-workflow.md` for the full delegation prompt template, taxonomy definitions, and merge script pattern.\r\n\r\n## Pitfalls\r\n\r\n1. **Keyword classification floods categories** — Using `kw in text` for classification causes every repo to match every category, because short keywords like `\"ai\"`, `\"model\"`, `\"api\"`, `\"tool\"` appear as substrings inside common English words (`available`, `domain`, `capital`, etc.) and inside large README text. **Always use word-boundary regex** (`re.search(r'\\b' + re.escape(kw) + r'\\b', text)`) and match against high-signal text first (repo name + topics + description), only falling back to README if no high-signal match. **However, even with word-boundary regex, keyword classification still produces multi-category noise** — prefer AI delegation for published reports. See `references\u002Fai-classification-workflow.md` for the AI-based alternative.\r\n2. **Token redaction** — Hermes terminal tool redacts `gh auth token` output. Never try to capture the token string into Python; call `gh api` directly as a subprocess.\r\n3. **`\u002Ftmp` path mismatch** — On Windows git-bash, `\u002Ftmp` maps to `C:\\Users\\\u003Cuser>\\AppData\\Local\\Temp`, but Windows Python doesn't understand `\u002Ftmp`. Use `os.environ['TEMP']` or `os.path.expanduser()` in Python scripts.\r\n4. **README base64** — The `\u002Frepos\u002F{repo}\u002Freadme` endpoint returns base64-encoded content in the `content` field. Decode with `base64.b64decode()` before using.\r\n5. **Language percentages** — The `\u002Frepos\u002F{repo}\u002Flanguages` endpoint returns byte counts, not percentages. Divide each by the total byte count × 100.\r\n6. **`gh api` timeout** — Set subprocess timeout to 30s and retry 3 times with exponential backoff for transient TLS handshake timeouts.\r\n7. **PPT generation needs NODE_PATH** — `pptxgenjs` is installed globally via npm. Set `NODE_PATH=$(npm root -g)` before running `node generate_ppt.js`, or the module won't be found.\r\n8. **README content in summaries** — The README extraction pulls raw markdown including HTML tags. When building summaries, strip HTML tags from the first few lines to avoid cluttering output with `\u003Cp>`, `\u003Cimg>`, `\u003Ca>` tags.\r\n9. **Whitespace collapse destroys feature-list extraction** — `re.sub(r'\\s+', ' ', clean)` merges all newlines into a single line, which breaks downstream regex patterns that expect `^`\u002F`$` anchors or `\\n` delimiters (e.g., feature-list extraction `r'(?:^|\\n)#+\\s*Features?\\s*\\n(...)'`). Use `re.sub(r'[^\\S\\n]+', ' ', clean)` to collapse horizontal whitespace while preserving newlines.\r\n10. **HTML in detailed_summary** — The `detailed_summary` field contains the raw README which often includes inline HTML (`\u003Cp>`, `\u003Ca>`, `\u003Cimg>`, `\u003Cpicture>`, `\u003Csource>`). Always run `strip_html()` (tag removal + entity decode) before using the README text for classification, capability extraction, or summary generation.\r\n11. **lark-cli `.CMD` on Windows** — Python's `subprocess.run([\"lark-cli\", ...])` fails on Windows because lark-cli is a `.CMD` shim. Use `shutil.which(\"lark-cli\")` to resolve the full path (returns `lark-cli.CMD`), then pass that to subprocess.\r\n12. **lark-cli `@file` requires relative paths** — The `--content @file` flag in lark-cli docs requires a path relative to CWD, NOT an absolute temp path. Write temp content files to `os.getcwd()` and reference them by filename only.\r\n13. **Duplicate `\u003Ctitle>` tag** — `build_feishu_doc_content()` must NOT include `\u003Ctitle>...\u003C\u002Ftitle>` in the XML content body. The `--title` flag in `lark-cli docs +create` already prepends `\u003Ctitle>` automatically. Adding it in both places causes a duplicate title tag and the API may reject the document.\r\n14. **`extract_capabilities` no longer needed in `feishu_report.py`** — After switching to AI-generated `core_capability_zh`, the `extract_capabilities()` import was removed from `feishu_report.py`. Only `strip_html` is still imported from `trending_analyzer`. If you re-add English capability extraction, add `sys.path.insert(0, SCRIPTS_DIR)` + `from trending_analyzer import extract_capabilities, strip_html`.\r\n15. **lark-cli identity scope split** — The Feishu app has a split scope situation: `user` identity can create documents (`docx:document:create`) but CANNOT send IM messages (missing `im:message.send_as_user` scope); `bot` identity can send IM messages but CANNOT create documents (missing `docx:document` scope). Both `create_feishu_doc()` and `send_notification()` must try `user` first, then fall back to `bot`. Do NOT assume a single identity works for both operations.\r\n16. **`patch` tool doubles backslash-quote in f-strings** — When using the `patch` tool to edit Python f-strings containing `href=\\\"...\\\"` patterns, the tool can introduce extra backslash escaping (`href=\\\\\\\"...\\\\\\\"` instead of `href=\\\"...\\\"`). After patching Python files with quoted XML attributes, verify the result with `python3 -c \"import module\"` and fix any doubled backslashes with `execute_code` byte-level replacement if needed.\r\n17. **Feishu Mermaid pie charts need `\u003Cwhiteboard type=\"mermaid\">`** — To render pie charts in Feishu documents, wrap Mermaid `pie` syntax in `\u003Cwhiteboard type=\"mermaid\">...\u003C\u002Fwhiteboard>`. Do NOT use `\u003Cpre>` or `\u003Ccode>` blocks for Mermaid — they render as plain text, not charts. The Mermaid syntax is: `pie title \u003Ctitle>\\n    \"Label\" : \u003Cvalue>\\n    ...`.\r\n18. **Content size shrinks dramatically after AI Chinese fields** — Switching from English README excerpts to AI-generated `one_line_zh` + `core_capability_zh` reduced document content from ~30K chars to ~19.6K chars while improving readability. This is expected — the English `detailed_summary` and `extract_capabilities()` output was verbose and noisy.\r\n19. **Feishu IM notification: `--content` + post JSON is the ONLY reliable method (user corrected 5+ times)** — When sending IM notifications via `lark-cli im +messages-send --as bot`, there are three content flag options:\r\n    - `--text` — sends `msg_type=text`. **Collapses to title-only** on both mobile and desktop. Multi-line content is NOT visible. **Never use for multi-line notifications.**\r\n    - `--markdown` — sends `msg_type=post` wrapping content as a single `{\"tag\":\"md\",\"text\":\"line1\\nline2\"}` element. **ALSO collapses to title-only** on some Feishu clients. **Do NOT use `--markdown` for multi-line notifications** — user explicitly rejected this multiple times.\r\n    - `--content` with `--msg-type post` — **THE ONLY RELIABLE METHOD.** Each line MUST be a separate content element. The title goes in the `title` field, NOT duplicated in the content body. The correct pattern:\r\n      ```python\r\n      def build_post_json(title, text):\r\n          lines = text.strip().split(\"\\n\")\r\n          content = []\r\n          for line in lines:\r\n              if not line.strip():\r\n                  continue\r\n              if line.startswith(\"http\"):\r\n                  content.append([{\"tag\": \"a\", \"text\": line, \"href\": line}])\r\n              else:\r\n                  content.append([{\"tag\": \"text\", \"text\": line}])\r\n          return {\"zh_cn\": {\"title\": title, \"content\": content}}\r\n\r\n      post_json = build_post_json(\"标题\", text)\r\n      # Send:\r\n      lark_cli(\"im\", \"+messages-send\", \"--as\", \"bot\", \"--user-id\", ou_xxx,\r\n               \"--msg-type\", \"post\",\r\n               \"--content\", json.dumps(post_json, ensure_ascii=False))\r\n      ```\r\n    **Key rules:** (1) Each line of text MUST be a separate `[{\"tag\":\"text\",\"text\":\"...\"}]` array — putting `\\n`-separated text in a single element does NOT work. (2) URL lines use `{\"tag\":\"a\",\"text\":\"url\",\"href\":\"url\"}`. (3) Title goes in `title` field only, do NOT repeat it as the first content line.\r\n    **Verified 2026-07-05:** User mobile + desktop screenshots confirmed `--content` + post JSON with per-line elements renders full multi-line content reliably. `--markdown` and `--text` both collapsed to title-only. User explicitly demanded `--content + 完整 post JSON` and rejected `--markdown` 5+ times.\r\n20. **Notification content should use AI Chinese fields** — The `build_notification_text()` function should use `one_line_zh` (not `short_description`) for project descriptions in the IM notification, and should filter categories\u002Fscenes to non-zero counts only (`[k for k,v in analysis[\"categories\"].items() if v > 0]`). Include hot projects in the notification (not just new projects) since hot projects have `period_stars` data users care about.\r\n21. **`hot_projects` and `new_projects` lack AI fields after merge** — The `ai_classify_merge.py` script only enriches `analysis[\"repos\"]` with `ai_category`\u002F`ai_scene`\u002F`one_line_zh`\u002F`core_capability_zh`. The `analysis[\"hot_projects\"]` and `analysis[\"new_projects\"]` arrays are separate references built by `trending_analyzer.py` and do NOT automatically inherit AI fields. After merging, **you must manually enrich these arrays** by looking up each project's `repo_id` in the main `repos` list and copying the AI fields:\r\n    ```python\r\n    repos_map = {r[\"repo_id\"]: r for r in analysis[\"repos\"]}\r\n    for p in analysis.get(\"hot_projects\", []) + analysis.get(\"new_projects\", []):\r\n        r = repos_map.get(p[\"repo_id\"])\r\n        if r:\r\n            p[\"one_line_zh\"] = r.get(\"one_line_zh\", \"\")\r\n            p[\"core_capability_zh\"] = r.get(\"core_capability_zh\", \"\")\r\n    ```\r\n    Without this step, `build_notification_text()` and `format_repo_summary_lines()` will fall back to English `short_description` for hot\u002Fnew projects even though AI Chinese fields exist on the main repos.\r\n22. **pptxgenjs `wrap: false` does NOT clip text** — It only prevents line breaks within the textbox. Text still renders beyond the textbox boundary horizontally, causing overlap with adjacent elements (star icons, shapes). Fix by manually truncating long strings (`name.substring(0, 14) + \"…\"`) and reducing font size. Do NOT rely on `autoFit: true` — it is unreliable in LibreOffice rendering.\r\n23. **Vision QA false positives at 1440x811 resolution** — Vision models at low render resolution misidentify truncated text as full text, and small font differences as identical. When vision QA reports issues that seem wrong, verify by unzipping the .pptx and inspecting slide XML: `re.findall(r'\u003Ca:t>([^\u003C]*)\u003C\u002Fa:t>', xml)` for text content, `sz=\"(\\d+)\"` for font size (1200=12pt), `\u003Ca:ext cx=\"(\\d+)\"` for textbox width in EMUs (914400 per inch). XML is ground truth.\r\n24. **LibreOffice locks .pptx after conversion** — After `soffice --headless --convert-to pdf`, the soffice process may keep a file lock. Regenerating the same file fails with `EBUSY`. Kill the process first (`taskkill \u002F\u002FF \u002F\u002FIM soffice.bin` on Windows) or output to a different filename.\r\n25. **PyMuPDF as pdftoppm alternative** — When Poppler's `pdftoppm` is unavailable, use `pip install pymupdf` then `fitz.open(\"file.pdf\")` + `page.get_pixmap(dpi=150)` to convert PDF slides to images for visual QA.\r\n26. **PPT icon colors must match accent bars** — Each stat card icon must be rendered in the same color as its accent bar. A mismatch (e.g., orange rocket icon on a green-accented card) is immediately visible. Pass the hex color to `iconToBase64Png(IconComponent, iconColor, 256)`.\r\n27. **HTML→PDF pagination: use fixed `height` not `min-height`** — When generating PDFs from HTML with puppeteer-core, `.page` divs must use `height: 720px; overflow: hidden` (NOT `min-height`). `min-height` allows content to grow beyond the page boundary, creating extra blank PDF pages. The `page-break-after: always` CSS property handles page splitting between `.page` divs.\r\n28. **Card pagination: 6 per page at 140-165px height** — For a 1280×720px page with ~60px header + ~30px footer, 6 project cards (3 rows × 2 columns) fit at `min-height: 140px; max-height: 165px` with 12px gap. More than 6 cards per page causes overflow; fewer wastes space.\r\n29. **Table fitting: compact row padding for 18 rows** — An 18-row summary table fits on one 720px page with `td padding: 3px 10px; font-size: 11px; line-height: 1.3`. Default `padding: 8px 16px` causes the table to overflow to a second page, losing rows.\r\n30. **puppeteer-core requires explicit `executablePath`** — `puppeteer.launch()` without `executablePath` fails with \"No Chrome\u002FEdge executable found\". On Windows, detect Edge at `C:\\Program Files (x86)\\Microsoft\\Edge\\Application\\msedge.exe` and pass it to `launch()`. No `npm install puppeteer` needed — `puppeteer-core` uses the system browser.\r\n31. **HTML report replaces PptxGenJS** — The old `generate_ppt.js` pipeline (PptxGenJS → .pptx → LibreOffice → PDF) is deprecated. The new pipeline is `generate_html.py` (Python) → `html2pdf.js` (puppeteer-core + Edge). The HTML\u002FCSS approach provides better layout control (CSS Grid, flexbox, `overflow: hidden`), native text truncation via `text-overflow: ellipsis`, and eliminates the LibreOffice rendering inconsistencies that plagued the PptxGenJS pipeline (wrap:false not working, autoFit unreliable, icon color mismatches).\r\n32. **Feishu Drive folder management requires additional OAuth scopes** — Creating folders (`drive +create-folder`) and listing folder contents (`drive files list`) require scopes not included in the default auth: `drive:drive` + `space:folder:create` (for folder creation), `space:document:retrieve` (for listing folder contents). Run `lark-cli auth login --scope \"drive:drive\" --scope \"space:folder:create\" --scope \"space:document:retrieve\"` and have the user authorize via QR code. **Do NOT use `drive +search`** — it requires `search:docs:read` which is an admin-managed scope that cannot be self-authorized. Use `drive files list --folder-token \u003Ctoken>` instead (only needs `space:document:retrieve`).\r\n33. **Folder token cache prevents redundant API calls** — `feishu_folders.json` at `~\u002F.hermes\u002Fgithub_trending_data\u002F` stores `{ \"root\": \"\u003Ctoken>\", \"month_2026-7\": \"\u003Ctoken>\" }`. The `ensure_folder()` function checks the cache first before listing\u002Fcreating. If a cached token becomes stale (e.g., folder deleted manually), the doc creation with `--parent-token` will fail — delete the cache file to force a fresh search.\r\n34. **`docs +create --parent-token` does NOT reliably place docs in folders — use `drive +move` after creation**\r\n35. **Check for existing docs before creating — delete duplicates first** — Before creating a new Feishu document, list the target folder contents via `drive files list --folder-token \u003Ctoken>` and look for a child with the same name. If found, delete it with `drive +delete --file-token \u003Ctoken> --type docx --yes` before creating the new one. This prevents duplicate documents accumulating in the folder across re-runs. The `create_feishu_doc()` function calls `find_child_by_name(parent_token, title, child_type=\"docx\")` and `delete_file_by_token()` before creating.\r\n36. **Use `drive files list` NOT `drive +search` for folder\u002Ffile checks** — `drive +search` requires `search:docs:read` scope (admin-managed, cannot self-authorize). `drive files list --folder-token \u003Ctoken>` only needs `space:document:retrieve` scope (user-authorizable). The `list_folder_contents()` function wraps `drive files list` and returns `[{name, token, type, ...}]`. Use `find_child_by_name(folder_token, name, child_type)` to check for existing folders or docs by name within a specific folder. — The Feishu API accepts the `--parent-token` parameter (visible in `--dry-run` output as `parent_token` in the request body), but the created document is **NOT** actually placed inside the specified folder. Verified 2026-07-05: three test documents created with `--parent-token` all landed in Drive root, not the target folder. **The reliable method is a two-step sequence:**\r\n    ```python\r\n    # Step 1: Create doc WITHOUT --parent-token\r\n    result = run_lark_cli([\"docs\", \"+create\", \"--as\", identity,\r\n                          \"--title\", title, \"--content\", f\"@{tmp_name}\"])\r\n    doc_id = result[\"data\"][\"document\"][\"document_id\"]\r\n\r\n    # Step 2: Move doc into target folder\r\n    if parent_token and doc_id:\r\n        run_lark_cli([\"drive\", \"+move\", \"--as\", identity,\r\n                      \"--file-token\", doc_id, \"--type\", \"docx\",\r\n                      \"--folder-token\", parent_token])\r\n    ```\r\n    This is a Feishu API-level limitation, not a lark-cli bug. The `feishu_report.py` `create_feishu_doc()` function implements this create-then-move pattern.",{"name":5,"author":24,"license":15,"version":25,"metadata":26,"platforms":38,"description":7},"Hermes Agent","1.0.0",{"hermes":27},{"tags":28,"related_skills":35},[29,30,31,32,33,34],"GitHub","Trending","Data Collection","Cron","Scraping","gh CLI",[36,37],"github-repo-management","github-auth",[39,40,41],"linux","macos","windows","main","a3f3199bb87ec3c91248f68a39d88527e1847ae9","skills\u002Fgithub\u002Fgithub-trending-collector","https:\u002F\u002Fgithub.com\u002Fchaorenex1\u002Fhermes-home-content","https:\u002F\u002Fgithub.com\u002Fchaorenex1","https:\u002F\u002Fblog.aduib.com","A programmer whose only hobby in life is coding","2026-10-20 00:34:32",{"source":8,"skillName":5,"commands":51,"prompt":61,"zipAvailable":62},[52,55,58],{"tool":53,"command":54},"npx","npx skills add chaorenex1\u002Fhermes-home-content --skill github-trending-collector",{"tool":56,"command":57},"bunx","bunx skills add chaorenex1\u002Fhermes-home-content --skill github-trending-collector",{"tool":59,"command":60},"pnpm","pnpm dlx skills add chaorenex1\u002Fhermes-home-content --skill github-trending-collector","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fchaorenex1\u002Fhermes-home-content\u002Fblob\u002Fmain\u002Fskills\u002Fgithub\u002Fgithub-trending-collector\u002FSKILL.md",true,[64,70,74,78,82,86,90,96],{"path":65,"resourceType":66,"resourceTypeDesc":67,"sizeBytes":68,"sourceHtmlUrl":69},"references\u002Fai-classification-workflow.md","REFERENCE","参考文档",9352,"https:\u002F\u002Fgithub.com\u002Fchaorenex1\u002Fhermes-home-content\u002Fblob\u002Fmain\u002Fskills\u002Fgithub\u002Fgithub-trending-collector\u002Freferences\u002Fai-classification-workflow.md",{"path":71,"resourceType":66,"resourceTypeDesc":67,"sizeBytes":72,"sourceHtmlUrl":73},"references\u002Ffeishu-drive-folder-management.md",9233,"https:\u002F\u002Fgithub.com\u002Fchaorenex1\u002Fhermes-home-content\u002Fblob\u002Fmain\u002Fskills\u002Fgithub\u002Fgithub-trending-collector\u002Freferences\u002Ffeishu-drive-folder-management.md",{"path":75,"resourceType":66,"resourceTypeDesc":67,"sizeBytes":76,"sourceHtmlUrl":77},"references\u002Fhtml-report-pipeline.md",7306,"https:\u002F\u002Fgithub.com\u002Fchaorenex1\u002Fhermes-home-content\u002Fblob\u002Fmain\u002Fskills\u002Fgithub\u002Fgithub-trending-collector\u002Freferences\u002Fhtml-report-pipeline.md",{"path":79,"resourceType":66,"resourceTypeDesc":67,"sizeBytes":80,"sourceHtmlUrl":81},"references\u002Fpipeline-scripts.md",14848,"https:\u002F\u002Fgithub.com\u002Fchaorenex1\u002Fhermes-home-content\u002Fblob\u002Fmain\u002Fskills\u002Fgithub\u002Fgithub-trending-collector\u002Freferences\u002Fpipeline-scripts.md",{"path":83,"resourceType":66,"resourceTypeDesc":67,"sizeBytes":84,"sourceHtmlUrl":85},"references\u002Fpipeline-test-procedure.md",6445,"https:\u002F\u002Fgithub.com\u002Fchaorenex1\u002Fhermes-home-content\u002Fblob\u002Fmain\u002Fskills\u002Fgithub\u002Fgithub-trending-collector\u002Freferences\u002Fpipeline-test-procedure.md",{"path":87,"resourceType":66,"resourceTypeDesc":67,"sizeBytes":88,"sourceHtmlUrl":89},"references\u002Ftrending-page-structure.md",5040,"https:\u002F\u002Fgithub.com\u002Fchaorenex1\u002Fhermes-home-content\u002Fblob\u002Fmain\u002Fskills\u002Fgithub\u002Fgithub-trending-collector\u002Freferences\u002Ftrending-page-structure.md",{"path":91,"resourceType":92,"resourceTypeDesc":93,"sizeBytes":94,"sourceHtmlUrl":95},"scripts\u002Fgithub_trending.py","SCRIPT","脚本",13423,"https:\u002F\u002Fgithub.com\u002Fchaorenex1\u002Fhermes-home-content\u002Fblob\u002Fmain\u002Fskills\u002Fgithub\u002Fgithub-trending-collector\u002Fscripts\u002Fgithub_trending.py",{"path":97,"resourceType":66,"resourceTypeDesc":67,"sizeBytes":98,"sourceHtmlUrl":99},"templates\u002Fcron-prompt-template.md",3766,"https:\u002F\u002Fgithub.com\u002Fchaorenex1\u002Fhermes-home-content\u002Fblob\u002Fmain\u002Fskills\u002Fgithub\u002Fgithub-trending-collector\u002Ftemplates\u002Fcron-prompt-template.md",[101,108,115,122,129,136],{"skillNo":102,"name":103,"nameZh":6,"description":104,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":105,"categories":106,"keywords":107,"publishedAt":19},"01M7F8GF32YD5MBQW2TGSRH1YP","web-retrieval-resilience","Web tools fail or search rules break: repair or fall back.","https:\u002F\u002Fgithub.com\u002Fchaorenex1\u002Fhermes-home-content\u002Fblob\u002Fmain\u002Fskills\u002Fweb\u002Fweb-retrieval-resilience\u002FSKILL.md",[],[],{"skillNo":109,"name":110,"nameZh":6,"description":111,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":112,"categories":113,"keywords":114,"publishedAt":19},"01M7F8FP46QESQMCZ1KBT3TW3R","blocked-page-recovery","Use when a fetch fails: 403\u002F429, paywall, WAF, bot wall.","https:\u002F\u002Fgithub.com\u002Fchaorenex1\u002Fhermes-home-content\u002Fblob\u002Fmain\u002Fskills\u002Fweb\u002Fblocked-page-recovery\u002FSKILL.md",[],[],{"skillNo":116,"name":117,"nameZh":6,"description":118,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":119,"categories":120,"keywords":121,"publishedAt":19},"01M7F8ER6VXHBNVRQBZS7X08SE","verification-loop","Run a six-phase verification of a Claude Code session's work — build, type check, lint, tests with coverage, security grep, and diff review — then produce a PASS\u002FFAIL verification report. Use when verifying work after completing a feature or refactor, before creating a PR, or when quality gates must pass.","https:\u002F\u002Fgithub.com\u002Fchaorenex1\u002Fhermes-home-content\u002Fblob\u002Fmain\u002Fskills\u002Fverification-loop\u002FSKILL.md",[],[],{"skillNo":123,"name":124,"nameZh":6,"description":125,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":126,"categories":127,"keywords":128,"publishedAt":19},"01M7F8E4BQJ38KVQVM3MT20PYV","unreal-world-builder","开放世界与环境专家——精通 UE5 World Partition、Landscape、程序化植被、HLOD 和大规模关卡流式加载，打造无缝开放世界体验","https:\u002F\u002Fgithub.com\u002Fchaorenex1\u002Fhermes-home-content\u002Fblob\u002Fmain\u002Fskills\u002Funreal-engine\u002Funreal-world-builder\u002FSKILL.md",[],[],{"skillNo":130,"name":131,"nameZh":6,"description":132,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":133,"categories":134,"keywords":135,"publishedAt":19},"01M7F8D747SQW2FTP7GBSX38BR","unreal-technical-artist","Unreal Engine 视觉管线专家——精通材质编辑器、Niagara 特效、程序化内容生成和 UE5 项目的美术到引擎管线","https:\u002F\u002Fgithub.com\u002Fchaorenex1\u002Fhermes-home-content\u002Fblob\u002Fmain\u002Fskills\u002Funreal-engine\u002Funreal-technical-artist\u002FSKILL.md",[],[],{"skillNo":137,"name":138,"nameZh":6,"description":139,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":140,"categories":141,"keywords":142,"publishedAt":19},"01M7F8CKHYJVZVBTN0321J88T2","unreal-systems-engineer","性能与混合架构专家——精通 C++\u002FBlueprint 边界、Nanite 几何体、Lumen GI 和 Gameplay Ability System，面向 AAA 级 Unreal Engine 项目","https:\u002F\u002Fgithub.com\u002Fchaorenex1\u002Fhermes-home-content\u002Fblob\u002Fmain\u002Fskills\u002Funreal-engine\u002Funreal-systems-engineer\u002FSKILL.md",[],[]]