diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 5c342d14..0bb614b4 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -5,166 +5,74 @@ "email": "daymadev89@gmail.com" }, "metadata": { - "description": "Professional Claude Code skills for GitHub operations, document conversion, diagram generation, statusline customization, Teams communication, repomix utilities, skill creation, CLI demo generation, LLM icon access, Cloudflare troubleshooting, UI design system extraction, professional presentation creation, YouTube video downloading, secure repomix packaging, ASR transcription correction, video comparison quality analysis, comprehensive QA testing infrastructure, prompt optimization with EARS methodology, session history recovery, documentation cleanup, format-controlled deep research report generation with evidence tracking, PDF generation with Chinese font support, CLAUDE.md progressive disclosure optimization, CCPM skill registry search and management, Promptfoo LLM evaluation framework, iOS app development with XcodeGen and SwiftUI, fact-checking with automated corrections, Twitter/X content fetching, intelligent macOS disk space recovery, skill quality review and improvement, GitHub contribution strategy, complete internationalization/localization setup, plugin/skill troubleshooting with diagnostic tools, evidence-based competitor analysis with source citations, Windows Remote Desktop (AVD/W365) connection quality diagnosis with transport protocol analysis and log parsing, Tailscale+proxy conflict diagnosis with SSH tunnel SOP for remote development, multi-path parallel product analysis with cross-model test-time compute scaling, real financial data collection for US equities with validation and yfinance pitfall handling, advanced Excel automation for formatted workbook generation and complex xlsm parsing, and macOS programmatic window screenshot capture workflows", - "version": "1.37.0", - "homepage": "https://github.com/daymade/claude-code-skills" + "description": "Professional Claude Code skills marketplace — production-ready skills spanning GitHub and git operations, document conversion and generation (Markdown, PDF, PPTX, DOCX), diagram and UI-design extraction, the full audio pipeline (ASR transcription, TTS, transcript correction, meeting minutes), financial and investment-research data, web scraping and content capture, security/PII tooling and secure repomix packaging, macOS and iOS development, CLI demo and terminal automation, prompt and skill engineering, deep research and fact-checking, QA and LLM-evaluation infrastructure, internationalization, network/Tailscale and remote-desktop diagnostics, and Claude Code operations (session recovery, CLAUDE.md optimization, statusline, troubleshooting, marketplace development, repo health-check). Suite plugins (daymade-audio, daymade-claude-code, daymade-docs, daymade-skill) bundle related skills under shared namespaces, including the StepFun StepAudio 2.5 audio family. See the Available Skills list in the README for the authoritative per-skill breakdown.", + "version": "1.65.0" }, "plugins": [ { - "name": "skill-creator", - "description": "Essential meta-skill for creating effective Claude Code skills with initialization scripts, validation, packaging, marketplace registration, and privacy best practices", - "source": "./", - "strict": false, - "version": "1.4.1", - "category": "developer-tools", - "keywords": [ - "skill-creation", - "claude-code", - "development", - "tooling", - "workflow", - "meta-skill", - "essential" - ], - "skills": [ - "./skill-creator" - ] - }, - { - "name": "github-ops", - "description": "Comprehensive GitHub operations using gh CLI and GitHub API for pull requests, issues, repositories, workflows, and API interactions", - "source": "./", + "name": "bigdata-skill", + "description": "Pull Bigdata.com (RavenPack) financial and news data through the official bigdata-client Python SDK and its /v1/* REST endpoints when the Bigdata MCP server gives you too little — it silently drops per-chunk sentiment, entity character-spans, and the entire structured-financial product line (analyst estimates, earnings/event calendar, earnings surprise, analyst ratings, price targets, company screener). Bundles a verified, cost-guarded toolkit plus the SSL-retry, chunk-billing 52x trap, and entity-query pitfalls already solved in real use. Use whenever the user mentions Bigdata.com, RavenPack, a bd_v2_ API key, the bigdata MCP, rp_entity_id resolution, chunk / query_unit cost, or wants forward estimates, an earnings/event calendar, earnings surprise, price targets, or annotated news sentiment for a ticker — even if they never name the SDK. Reach for it the moment an MCP financial data source returns less than you know the underlying API holds.", + "source": "./bigdata-skill", "strict": false, "version": "1.0.0", "category": "developer-tools", "keywords": [ - "github", - "gh-cli", - "pull-request", - "issues", - "workflows", - "api" - ], - "skills": [ - "./github-ops" - ] - }, - { - "name": "markdown-tools", - "description": "Convert documents (PDFs, Word, PowerPoint) to high-quality markdown with multi-tool orchestration. Supports Quick Mode (fast, single tool) and Heavy Mode (best quality, multi-tool merge with segment-level selection). Features PyMuPDF4LLM for LLM-optimized PDF conversion, pandoc for DOCX/PPTX structure preservation, quality validation with HTML reports, and image extraction with metadata", - "source": "./", - "strict": false, - "version": "1.2.0", - "category": "document-conversion", - "keywords": [ - "markdown", - "pdf", - "docx", - "pptx", - "pymupdf4llm", - "pandoc", - "markitdown", - "heavy-mode", - "quality-validation" - ], - "skills": [ - "./markdown-tools" - ] - }, - { - "name": "mermaid-tools", - "description": "Generate Mermaid diagrams from markdown with automatic PNG/SVG rendering and extraction from documents", - "source": "./", - "strict": false, - "version": "1.0.0", - "category": "documentation", - "keywords": [ - "mermaid", - "diagrams", - "visualization", - "flowchart", - "sequence" - ], - "skills": [ - "./mermaid-tools" + "bigdata", + "bigdata-com", + "ravenpack", + "investment-research", + "financial-data", + "sdk", + "rest-api", + "mcp", + "sentiment-analysis", + "analyst-estimates", + "earnings-calendar", + "rp-entity-id", + "claude-code" ] }, { - "name": "statusline-generator", - "description": "Configure Claude Code statuslines with multi-line layouts, cost tracking via ccusage, git status, and customizable colors", - "source": "./", + "name": "bilibili-source", + "description": "Fetch comprehensive, login-free data for any Bilibili (B站) video — title, UP name and follower count, publish date, partition, tags, per-part cids, live stats (view, like, coin, favorite, share, reply, danmaku), and full danmaku (bullet-comment) text. Use this skill whenever working with a Bilibili video and needing real, citable numbers or metadata — ingesting a Bilibili source into a knowledge base, analyzing why a video performed, verifying a creator's claimed metrics, building a case study, or any time a Bilibili view/like/favorite count is about to be written into a document — fetch it, never hand-type or estimate it. Accepts BVID, av numbers, b23.tv short links, or full URLs. Subtitles are also covered but require the user's Bilibili login.", + "source": "./bilibili-source", "strict": false, "version": "1.0.0", - "category": "customization", + "category": "developer-tools", "keywords": [ - "statusline", - "ccusage", - "git-status", - "customization", - "prompt" - ], - "skills": [ - "./statusline-generator" + "bilibili", + "b站", + "bilibili-api", + "video-stats", + "danmaku", + "view-count", + "content-analysis", + "web-data", + "claude-code" ] }, { - "name": "teams-channel-post-writer", - "description": "Create professional Microsoft Teams channel posts with Adaptive Cards, formatted announcements, and corporate communication standards", - "source": "./", - "strict": false, - "version": "1.0.0", - "category": "communication", - "keywords": [ - "teams", - "microsoft", - "adaptive-cards", - "communication", - "announcements" - ], - "skills": [ - "./teams-channel-post-writer" - ] - }, - { - "name": "repomix-unmixer", - "description": "Extract files from repomix packaged formats (XML, Markdown, JSON) with automatic format detection and validation", - "source": "./", + "name": "capture-screen", + "description": "Programmatic screenshot capture on macOS. Get window IDs via Swift CGWindowListCopyWindowInfo, capture specific windows with screencapture -l, and control application windows via AppleScript. Supports multi-shot workflows for capturing different sections of the same window. Use when taking automated screenshots, capturing application windows, or creating visual documentation", + "source": "./capture-screen", "strict": false, - "version": "1.0.0", + "version": "1.0.1", "category": "utilities", "keywords": [ - "repomix", - "unmix", - "extract", - "xml", - "conversion" - ], - "skills": [ - "./repomix-unmixer" - ] - }, - { - "name": "llm-icon-finder", - "description": "Find and access AI/LLM model brand icons from lobe-icons library in SVG/PNG/WEBP formats", - "source": "./", - "strict": false, - "version": "1.0.0", - "category": "assets", - "keywords": [ - "icons", - "ai-models", - "llm", - "branding", - "lobe-icons" - ], - "skills": [ - "./llm-icon-finder" + "screenshot", + "screencapture", + "macos", + "window-capture", + "swift", + "applescript", + "automation", + "visual-documentation" ] }, { "name": "cli-demo-generator", "description": "Generate professional animated CLI demos and terminal recordings with VHS. Supports automated generation, batch processing, and interactive recording for documentation and tutorials", - "source": "./", + "source": "./cli-demo-generator", "strict": false, "version": "1.0.0", "category": "developer-tools", @@ -177,17 +85,14 @@ "recording", "animation", "documentation" - ], - "skills": [ - "./cli-demo-generator" ] }, { "name": "cloudflare-troubleshooting", "description": "Investigate and resolve Cloudflare configuration issues using API-driven evidence gathering. Use when troubleshooting ERR_TOO_MANY_REDIRECTS, SSL errors, DNS issues, or any Cloudflare-related problems", - "source": "./", + "source": "./cloudflare-troubleshooting", "strict": false, - "version": "1.0.0", + "version": "1.0.2", "category": "developer-tools", "keywords": [ "cloudflare", @@ -197,310 +102,324 @@ "api", "debugging", "devops" - ], - "skills": [ - "./cloudflare-troubleshooting" ] }, { - "name": "ui-designer", - "description": "Extract design systems from reference UI images and generate implementation-ready UI design prompts. Use when users provide UI screenshots/mockups and want to create consistent designs", - "source": "./", + "name": "competitors-analysis", + "description": "Analyze competitor repositories with evidence-based approach. Use when tracking competitors, creating competitor profiles, or generating competitive analysis. All analysis must be based on actual cloned code, never assumptions. Triggers include analyze competitor, add competitor, competitive analysis, or 竞品分析", + "source": "./competitors-analysis", "strict": false, - "version": "1.0.0", - "category": "design", + "version": "1.0.1", + "category": "productivity", "keywords": [ - "ui", - "design-system", - "mockup", - "screenshot", - "design-extraction", - "mvp" - ], - "skills": [ - "./ui-designer" + "competitors", + "competitive-analysis", + "competitor-tracking", + "evidence-based", + "market-research", + "竞品分析", + "code-analysis" ] }, { - "name": "ppt-creator", - "description": "Create professional slide decks from topics or documents. Generates structured content with data-driven charts, speaker notes, and complete PPTX files. Applies persuasive storytelling principles (Pyramid Principle, assertion-evidence). Supports multiple formats (Marp, PowerPoint). Use for presentations, pitches, slide decks, or keynotes", - "source": "./", + "name": "daymade-claude-code", + "description": "Claude Code operations suite that bundles session history recovery, interrupted-work continuation, plugin/skill troubleshooting, CLAUDE.md progressive disclosure optimization, statusline configuration, exported .txt repair, plugin marketplace development, and terminal-output-to-PNG rendering for visual CLI verification under one shared namespace. Install once to get the full Claude Code power-user toolkit.", + "source": "./daymade-claude-code", "strict": false, - "version": "1.0.0", - "category": "productivity", + "version": "1.3.0", + "category": "suite", "keywords": [ - "presentation", - "powerpoint", - "pptx", - "slides", - "marp", - "charts", - "data-visualization", - "pyramid-principle" + "suite", + "claude-code", + "session-recovery", + "claude-md", + "statusline", + "troubleshooting", + "marketplace-dev", + "terminal-screenshot", + "usage-analyst" ], "skills": [ - "./ppt-creator" + "./claude-code-history-files-finder", + "./continue-claude-work", + "./claude-skills-troubleshooting", + "./claude-md-progressive-disclosurer", + "./statusline-generator", + "./claude-export-txt-better", + "./marketplace-dev", + "./terminal-screenshot", + "./claude-usage-analyst" ] }, { - "name": "youtube-downloader", - "description": "Download YouTube videos and HLS streams (m3u8) from platforms like Mux, Vimeo, etc. using yt-dlp and ffmpeg. Use when users request downloading videos, extracting audio, handling protected streams with authentication headers, or troubleshooting download issues like nsig extraction failures, 403 errors, or cookie extraction problems", - "source": "./", + "name": "daymade-docs", + "description": "Documentation suite plugin that exposes document conversion, Mermaid diagram generation, PDF/PPT creation, and documentation cleanup skills under one shared namespace", + "source": "./daymade-docs", "strict": false, - "version": "1.1.0", - "category": "utilities", + "version": "1.2.0", + "category": "suite", "keywords": [ - "youtube", - "yt-dlp", - "video-download", - "audio-extraction", - "mp3", - "download", - "hls", - "m3u8", - "ffmpeg", - "streaming", - "mux", - "vimeo" + "suite", + "documentation", + "markdown", + "mermaid", + "pdf", + "pptx", + "meeting-minutes" ], "skills": [ - "./youtube-downloader" + "./doc-to-markdown", + "./mermaid-tools", + "./pdf-creator", + "./ppt-creator", + "./docs-cleaner", + "./pdf-to-html" ] }, { - "name": "repomix-safe-mixer", - "description": "Safely package codebases with repomix by automatically detecting and removing hardcoded credentials before packing. Use when packaging code for distribution, creating reference packages, or when the user mentions security concerns about sharing code with repomix", - "source": "./", + "name": "daymade-audio", + "description": "Audio processing suite covering the full speech pipeline: ASR transcription (Qwen3, StepFun), transcript error correction, structured meeting minutes generation, and TTS voice synthesis (StepFun). Install once for the complete audio workflow.", + "source": "./daymade-audio", "strict": false, - "version": "1.0.0", - "category": "security", + "version": "1.2.1", + "category": "suite", "keywords": [ - "repomix", - "security", - "credentials", - "secrets-scanning", - "safe-packaging", - "secret-detection", - "code-security" + "suite", + "audio", + "asr", + "tts", + "transcription", + "speech-to-text", + "text-to-speech", + "meeting-minutes", + "voice" ], "skills": [ - "./repomix-safe-mixer" + "./asr-transcribe-to-text", + "./stepfun-asr", + "./transcript-fixer", + "./meeting-minutes-taker", + "./stepfun-tts" ] }, { - "name": "transcript-fixer", - "description": "Corrects speech-to-text (ASR/STT) transcription errors in meeting notes, lecture recordings, interviews, and voice memos through dictionary-based rules and AI corrections. Supports Chinese domain names, AI fallback to Claude Code, and iterative dictionary building. Use when users mention transcript correction, ASR errors, speech-to-text mistakes, homophone errors, or working with transcription files", - "source": "./", + "name": "daymade-skill", + "description": "Daymade skills core suite. Bundles skill creation, quality review, search, and marketplace development tooling under one shared namespace.", + "source": "./daymade-skill", "strict": false, - "version": "1.1.0", - "category": "productivity", + "version": "1.2.0", + "category": "suite", "keywords": [ - "transcription", - "asr", - "stt", - "speech-to-text", - "correction", - "ai", - "meeting-notes", - "nlp" + "suite", + "skill-creation", + "skill-review", + "marketplace-dev", + "development", + "tooling" ], "skills": [ - "./transcript-fixer" + "./skill-creator", + "./skill-reviewer", + "./skills-search" ] }, { - "name": "video-comparer", - "description": "Compare two videos and generate interactive HTML reports with quality metrics (PSNR, SSIM) and frame-by-frame visual comparisons. Use when analyzing compression results, evaluating codec performance, or assessing video quality differences", - "source": "./", + "name": "deep-research", + "description": "Generate format-controlled research reports with evidence tracking, source governance, and multi-pass synthesis. V6.1 adds: source accessibility (circular verification forbidden, exclusive advantage encouraged). Enterprise Research Mode: six-dimension data collection, SWOT/barrier/risk frameworks, and three-level quality control for company research", + "source": "./deep-research", "strict": false, - "version": "1.0.0", - "category": "media", + "version": "2.4.0", + "category": "documentation", "keywords": [ - "video", - "comparison", - "quality-analysis", - "psnr", - "ssim", - "compression", - "ffmpeg", - "codec" - ], - "skills": [ - "./video-comparer" + "research", + "report", + "analysis", + "literature-review", + "market-research", + "citations", + "evidence", + "deepresearch", + "enterprise", + "company-research", + "due-diligence" ] }, { - "name": "qa-expert", - "description": "Comprehensive QA testing infrastructure with autonomous LLM execution, Google Testing Standards (AAA pattern), and OWASP security testing. Use when establishing QA processes, writing test cases, executing test plans, tracking bugs with P0-P4 classification, calculating quality metrics, enforcing quality gates, or preparing third-party QA handoffs. Enables 100x faster test execution via master prompts", - "source": "./", + "name": "douban-skill", + "description": "Export and sync Douban (豆瓣) book/movie/music/game collections to local CSV files via Frodo API. Supports full export (all history) and RSS incremental sync (recent items). Use when the user wants to export Douban reading/watching/listening/gaming history, back up their Douban data, set up incremental sync, or mentions 豆瓣/douban collections. Triggers on: 豆瓣, douban, 读书记录, 观影记录, 书影音, 导出豆瓣, export, backup, sync, collection.", + "source": "./douban-skill", "strict": false, "version": "1.0.0", - "category": "developer-tools", + "category": "productivity", "keywords": [ - "qa", - "testing", - "test-cases", - "bug-tracking", - "google-standards", - "owasp", - "security", - "automation", - "quality-gates", - "metrics" - ], - "skills": [ - "./qa-expert" + "douban", + "豆瓣", + "csv", + "export", + "backup", + "rss", + "frodo" ] }, { - "name": "prompt-optimizer", - "description": "Transform vague prompts into precise, well-structured specifications using EARS (Easy Approach to Requirements Syntax) methodology. Use when users provide loose requirements, ambiguous feature descriptions, need to enhance prompts for AI-generated code/products/documents, request prompt optimization, or want to improve requirements engineering. Applies domain theories (GTD, BJ Fogg, Gestalt, AIDA, Zero Trust) and structured Role/Skills/Workflows/Examples/Formats framework", - "source": "./", + "name": "excel-automation", + "description": "Create, parse, and control Excel files on macOS. Professional formatting with openpyxl (font colors, fills, borders, conditional formatting), complex xlsm parsing with stdlib zipfile+xml for investment bank financial models, and Excel window control via AppleScript (zoom, scroll, select). Use when creating formatted Excel reports, parsing financial models, or automating Excel on macOS", + "source": "./excel-automation", "strict": false, - "version": "1.1.0", + "version": "1.0.0", "category": "productivity", "keywords": [ - "prompt-engineering", - "ears", - "requirements", - "specifications", - "optimization", - "domain-theory", - "prompt-enhancement", - "ai-prompting" - ], - "skills": [ - "./prompt-optimizer" + "excel", + "openpyxl", + "xlsm", + "spreadsheet", + "formatting", + "financial-model", + "applescript", + "macos", + "dcf", + "investment-banking" ] }, { - "name": "claude-code-history-files-finder", - "description": "Find and recover content from Claude Code session history files. Use when searching for deleted files, tracking changes across sessions, analyzing conversation history, or recovering code/documents from previous Claude interactions. Triggers include mentions of session history, recover deleted, find in history, previous conversation, or .claude/projects", - "source": "./", + "name": "fact-checker", + "description": "Verifies factual claims in documents using web search and official sources, then proposes corrections with user confirmation. Use when the user asks to fact-check, verify information, validate claims, check accuracy, or update outdated information in documents. Supports AI model specs, technical documentation, statistics, and general factual statements", + "source": "./fact-checker", "strict": false, "version": "1.0.0", - "category": "developer-tools", + "category": "productivity", "keywords": [ - "session-history", - "recovery", - "deleted-files", - "conversation-history", - "file-tracking", - "claude-code", - "history-analysis" - ], - "skills": [ - "./claude-code-history-files-finder" + "fact-checking", + "verification", + "accuracy", + "sources", + "validation", + "corrections", + "web-search" ] }, { - "name": "docs-cleaner", - "description": "Consolidates redundant documentation while preserving all valuable content. Use when cleaning up documentation bloat, merging redundant docs, reducing documentation sprawl, or consolidating multiple files covering the same topic", - "source": "./", + "name": "feishu-doc-scraper", + "description": "Extract Feishu (Lark) Docs, Wiki pages, Wiki collections/hubs, spreadsheets, and Minutes (妙记) transcripts into clean high-fidelity local Markdown. The primary path is the lark-cli API — programmatic extraction with no LLM rewriting of the body — which recursively follows a collection's reference graph (mention-doc / sheet / cross-tenant links) and uses error codes to resolve permission boundaries precisely; a browser-DOM path is the fallback only when lark-cli cannot reach the content. Use this whenever the source is a Feishu/Lark URL and fidelity matters — including 导出飞书文档/合集/妙记转写, 把飞书 wiki/知识库转 markdown, scraping or archiving a Feishu collection, exporting a Feishu Minutes/妙记 transcript, or saving a Feishu page locally — even if the user only says clipping, archiving, converting, or \"save this\". Also covers the permission-denied path (owner-exported .docx → faithful Markdown with heading/highlight restoration).", + "source": "./feishu-doc-scraper", "strict": false, - "version": "1.0.0", + "version": "1.2.0", "category": "productivity", "keywords": [ - "documentation", - "cleanup", - "consolidation", - "redundancy", - "merge", - "docs" - ], - "skills": [ - "./docs-cleaner" + "feishu", + "lark", + "lark-cli", + "markdown", + "wiki", + "minutes", + "transcript", + "collection", + "api", + "docx", + "scraping", + "browser", + "archival" ] }, { - "name": "pdf-creator", - "description": "Create PDF documents from markdown with proper Chinese font support using weasyprint. Use when converting markdown to PDF, generating formal documents (legal filings, trademark applications, reports), or when Chinese typography is required. Triggers include convert to PDF, generate PDF, markdown to PDF, or printable documents", - "source": "./", + "name": "financial-data-collector", + "description": "Collect real financial data for any US publicly traded company from free public sources (yfinance). Output structured JSON with market data, historical financials, WACC inputs, and analyst estimates. Handles NaN year detection, CapEx sign preservation, and FCF definition mismatches. Use when users request company financials, stock data, DCF inputs, or financial data collection for any US equity ticker", + "source": "./financial-data-collector", "strict": false, "version": "1.0.0", - "category": "document-conversion", + "category": "productivity", "keywords": [ - "pdf", - "markdown", - "weasyprint", - "chinese-fonts", - "document-generation", - "legal", - "reports", - "typography" - ], - "skills": [ - "./pdf-creator" + "finance", + "financial-data", + "yfinance", + "stock-data", + "dcf", + "wacc", + "market-data", + "investment-research", + "sec-filings" ] }, { - "name": "claude-md-progressive-disclosurer", - "description": "Optimize user CLAUDE.md files by applying progressive disclosure principles. This skill should be used when users want to reduce CLAUDE.md bloat, move detailed content to references, extract reusable patterns into skills, or improve context efficiency. Triggers include optimize CLAUDE.md, reduce CLAUDE.md size, apply progressive disclosure, or complaints about CLAUDE.md being too long", - "source": "./", + "name": "gangtise-copilot", + "description": "One-stop installer and companion for the full Gangtise (岗底斯投研) OpenAPI skill suite — 19 official skills covering data retrieval (OHLC 行情, 财务, 估值, 研报, 首席观点, 会议纪要, 调研纪要), research workflows (个股研究 L1-L4, 观点 PK 对抗性分析, 主题研究, 事件复盘), and utility (股票池管理, 公开网页搜索). Zero-config install to Claude Code / OpenClaw / Codex with 4 preset modes (full / workshop / minimal / custom), guides accessKey + secretAccessKey setup with a live validation call against open.gangtise.com, and ships a read-only diagnostic script. Use this skill whenever the user mentions Gangtise, 岗底斯, gangtise-data-client, gangtise-kb-client, gangtise-file-client, gangtise-stock-research, gangtise-opinion-pk, installing any gangtise-* skill, configuring its credentials, or reports errors like 'token is invalid', '接口地址错误', 'the uri can't be accessed'. This is a wrapper around Gangtise's official skills — it installs and orchestrates them rather than replacing them.", + "source": "./gangtise-copilot", "strict": false, "version": "1.2.0", - "category": "productivity", + "category": "developer-tools", "keywords": [ - "claude-md", - "progressive-disclosure", - "optimization", - "context-efficiency", - "configuration", - "token-savings" - ], - "skills": [ - "./claude-md-progressive-disclosurer" + "gangtise", + "岗底斯", + "investment-research", + "financial-data", + "ohlc", + "research-report", + "installer", + "wrapper", + "claude-code", + "openclaw", + "codex" ] }, { - "name": "skills-search", - "description": "Search, discover, install, and manage Claude Code skills from the CCPM registry. Use when users want to find skills for specific tasks, install skills by name, list installed skills, get skill details, or manage their Claude Code skill collection. Triggers include find skills, search for plugins, install skill, list installed skills, or any CCPM registry operations", - "source": "./", + "name": "github-contributor", + "description": "Strategic guide for becoming an effective GitHub contributor. Covers opportunity discovery, project selection, high-quality PR creation, and reputation building. Use when looking to contribute to open-source projects, building GitHub presence, or learning contribution best practices", + "source": "./github-contributor", "strict": false, "version": "1.1.0", "category": "developer-tools", "keywords": [ - "ccpm", - "skills", - "search", - "install", - "registry", - "plugin", - "marketplace", - "discovery", - "skill-management" - ], - "skills": [ - "./skills-search" + "github", + "open-source", + "contribution", + "pull-request", + "reputation", + "contributor", + "oss" ] }, { - "name": "promptfoo-evaluation", - "description": "Configures and runs LLM evaluation using Promptfoo framework. Use when setting up prompt testing, creating evaluation configs (promptfooconfig.yaml), writing Python custom assertions, implementing llm-rubric for LLM-as-judge, or managing few-shot examples in prompts. Triggers on keywords like promptfoo, eval, LLM evaluation, prompt testing, or model comparison", - "source": "./", + "name": "github-ops", + "description": "Comprehensive GitHub operations using gh CLI and GitHub API for pull requests, issues, repositories, workflows, and API interactions", + "source": "./github-ops", "strict": false, - "version": "1.1.0", + "version": "1.0.0", "category": "developer-tools", "keywords": [ - "promptfoo", - "evaluation", - "llm-testing", - "prompt-testing", - "assertions", - "llm-rubric", - "few-shot", - "model-comparison" - ], - "skills": [ - "./promptfoo-evaluation" + "github", + "gh-cli", + "pull-request", + "issues", + "workflows", + "api" + ] + }, + { + "name": "i18n-expert", + "description": "Complete internationalization/localization setup and auditing for UI codebases. Configure i18n frameworks, replace hard-coded strings with translation keys, ensure locale parity between en-US and zh-CN, and validate pluralization and formatting. Use when setting up i18n for React/Next.js/Vue apps, auditing existing implementations, replacing hard-coded strings, ensuring proper error code mapping, or validating pluralization and date/time/number formatting across locales", + "source": "./i18n-expert", + "strict": false, + "version": "1.0.0", + "category": "developer-tools", + "keywords": [ + "i18n", + "internationalization", + "localization", + "translation", + "react-i18next", + "next-intl", + "vue-i18n", + "locale", + "multilingual", + "globalization" ] }, { "name": "iOS-APP-developer", "description": "Develops iOS applications with XcodeGen, SwiftUI, and SPM. Use when configuring XcodeGen project.yml, resolving SPM dependency issues, deploying to devices, handling code signing, debugging camera/AVFoundation, iOS version compatibility issues, or fixing Library not loaded @rpath framework errors. Includes state machine testing patterns for @MainActor classes", - "source": "./", + "source": "./iOS-APP-developer", "strict": false, - "version": "1.1.1", + "version": "1.1.0", "category": "developer-tools", "keywords": [ "ios", @@ -514,58 +433,50 @@ "swift", "xcode", "testing" - ], - "skills": [ - "./iOS-APP-developer" ] }, { - "name": "fact-checker", - "description": "Verifies factual claims in documents using web search and official sources, then proposes corrections with user confirmation. Use when the user asks to fact-check, verify information, validate claims, check accuracy, or update outdated information in documents. Supports AI model specs, technical documentation, statistics, and general factual statements", - "source": "./", + "name": "ima-copilot", + "description": "One-stop companion and installer for the official Tencent IMA skill (ima.qq.com). Installs upstream ima-skill to Claude Code/Codex/OpenClaw via npx skills add, guides API key setup, detects and fixes known issues (including the missing-YAML-frontmatter bug in submodule SKILL.md files) with user consent, and implements a personalized fan-out search strategy with priority-based knowledge base boosting and silent truncation detection", + "source": "./ima-copilot", "strict": false, - "version": "1.0.0", - "category": "productivity", + "version": "1.0.1", + "category": "developer-tools", "keywords": [ - "fact-checking", - "verification", - "accuracy", - "sources", - "validation", - "corrections", - "web-search" - ], - "skills": [ - "./fact-checker" + "ima", + "tencent-ima", + "knowledge-base", + "note-search", + "fan-out-search", + "installer", + "wrapper", + "upstream-fix", + "claude-code", + "codex", + "openclaw" ] }, { - "name": "twitter-reader", - "description": "Fetch Twitter/X post content by URL using jina.ai API to bypass JavaScript restrictions. Use when Claude needs to retrieve tweet content including author, timestamp, post text, images, and thread replies. Supports individual posts or batch fetching from x.com or twitter.com URLs", - "source": "./", + "name": "llm-icon-finder", + "description": "Find and access AI/LLM model brand icons from lobe-icons library in SVG/PNG/WEBP formats", + "source": "./llm-icon-finder", "strict": false, "version": "1.0.0", - "category": "utilities", + "category": "assets", "keywords": [ - "twitter", - "x", - "social-media", - "jina", - "content-fetching", - "api", - "scraping", - "threads" - ], - "skills": [ - "./twitter-reader" + "icons", + "ai-models", + "llm", + "branding", + "lobe-icons" ] }, { "name": "macos-cleaner", "description": "Intelligent macOS disk space analysis and cleanup with safety-first philosophy. Use when users report disk space issues, need to clean their Mac, or want to understand storage consumption. Analyzes system caches, application remnants, large files, and development environments (Docker, Homebrew, npm, pip) with risk categorization (Safe/Caution/Keep) and requires explicit user confirmation before any deletions. Includes Mole visual tool integration for hybrid workflow", - "source": "./", + "source": "./macos-cleaner", "strict": false, - "version": "1.1.1", + "version": "1.2.0", "category": "utilities", "keywords": [ "macos", @@ -578,164 +489,189 @@ "homebrew", "system-maintenance", "safety" - ], - "skills": [ - "./macos-cleaner" ] }, { - "name": "skill-reviewer", - "description": "Reviews and improves Claude Code skills against official best practices. Supports three modes - self-review (validate your own skills), external review (evaluate others' skills), and auto-PR (fork, improve, submit). Use when checking skill quality, reviewing skill repositories, or contributing improvements to open-source skills", - "source": "./", + "name": "product-analysis", + "description": "Multi-path parallel product analysis with cross-model test-time compute scaling. Spawns parallel agents (Claude Code + Codex CLI) for multi-perspective exploration, then synthesizes findings into actionable optimization plans. Supports self-audit, UX audit, API audit, architecture review, and competitive benchmarking via competitors-analysis skill", + "source": "./product-analysis", + "strict": false, + "version": "1.0.1", + "category": "productivity", + "keywords": [ + "product-analysis", + "self-review", + "ux-audit", + "parallel-agents", + "cross-model", + "test-time-compute", + "codex", + "synthesis", + "product-audit", + "information-architecture" + ] + }, + { + "name": "prompt-optimizer", + "description": "Transform vague prompts into precise, well-structured specifications using EARS (Easy Approach to Requirements Syntax) methodology. Use when users provide loose requirements, ambiguous feature descriptions, need to enhance prompts for AI-generated code/products/documents, request prompt optimization, or want to improve requirements engineering. Applies domain theories (GTD, BJ Fogg, Gestalt, AIDA, Zero Trust) and structured Role/Skills/Workflows/Examples/Formats framework", + "source": "./prompt-optimizer", + "strict": false, + "version": "1.1.0", + "category": "productivity", + "keywords": [ + "prompt-engineering", + "ears", + "requirements", + "specifications", + "optimization", + "domain-theory", + "prompt-enhancement", + "ai-prompting" + ] + }, + { + "name": "promptfoo-evaluation", + "description": "Configures and runs LLM evaluation using Promptfoo framework. Use when setting up prompt testing, creating evaluation configs (promptfooconfig.yaml), writing Python custom assertions, implementing llm-rubric for LLM-as-judge, or managing few-shot examples in prompts. Triggers on keywords like promptfoo, eval, LLM evaluation, prompt testing, or model comparison", + "source": "./promptfoo-evaluation", + "strict": false, + "version": "1.1.0", + "category": "developer-tools", + "keywords": [ + "promptfoo", + "evaluation", + "llm-testing", + "prompt-testing", + "assertions", + "llm-rubric", + "few-shot", + "model-comparison" + ] + }, + { + "name": "qa-expert", + "description": "Comprehensive QA testing infrastructure with autonomous LLM execution, Google Testing Standards (AAA pattern), and OWASP security testing. Use when establishing QA processes, writing test cases, executing test plans, tracking bugs with P0-P4 classification, calculating quality metrics, enforcing quality gates, or preparing third-party QA handoffs. Enables 100x faster test execution via master prompts", + "source": "./qa-expert", "strict": false, "version": "1.0.0", "category": "developer-tools", "keywords": [ - "skill-review", - "best-practices", - "claude-code", - "quality-assurance", - "open-source", - "contribution", - "auto-pr" - ], - "skills": [ - "./skill-reviewer" + "qa", + "testing", + "test-cases", + "bug-tracking", + "google-standards", + "owasp", + "security", + "automation", + "quality-gates", + "metrics" ] }, { - "name": "github-contributor", - "description": "Strategic guide for becoming an effective GitHub contributor. Covers opportunity discovery, project selection, high-quality PR creation, and reputation building. Use when looking to contribute to open-source projects, building GitHub presence, or learning contribution best practices", - "source": "./", + "name": "repomix-safe-mixer", + "description": "Safely package codebases with repomix by automatically detecting and removing hardcoded credentials before packing. Use when packaging code for distribution, creating reference packages, or when the user mentions security concerns about sharing code with repomix", + "source": "./repomix-safe-mixer", "strict": false, - "version": "1.0.2", - "category": "developer-tools", + "version": "1.0.1", + "category": "security", "keywords": [ - "github", - "open-source", - "contribution", - "pull-request", - "reputation", - "contributor", - "oss" - ], - "skills": [ - "./github-contributor" + "repomix", + "security", + "credentials", + "secrets-scanning", + "safe-packaging", + "secret-detection", + "code-security" ] }, { - "name": "i18n-expert", - "description": "Complete internationalization/localization setup and auditing for UI codebases. Configure i18n frameworks, replace hard-coded strings with translation keys, ensure locale parity between en-US and zh-CN, and validate pluralization and formatting. Use when setting up i18n for React/Next.js/Vue apps, auditing existing implementations, replacing hard-coded strings, ensuring proper error code mapping, or validating pluralization and date/time/number formatting across locales", - "source": "./", + "name": "repomix-unmixer", + "description": "Extract files from repomix packaged formats (XML, Markdown, JSON) with automatic format detection and validation", + "source": "./repomix-unmixer", "strict": false, "version": "1.0.0", - "category": "developer-tools", + "category": "utilities", "keywords": [ - "i18n", - "internationalization", - "localization", - "translation", - "react-i18next", - "next-intl", - "vue-i18n", - "locale", - "multilingual", - "globalization" - ], - "skills": [ - "./i18n-expert" + "repomix", + "unmix", + "extract", + "xml", + "conversion" ] }, { - "name": "claude-skills-troubleshooting", - "description": "Diagnose and resolve Claude Code plugin and skill configuration issues. Debug plugin installation, enablement, and activation problems with systematic workflows. Use when plugins are installed but not showing in available skills list, skills are not activating as expected, troubleshooting enabledPlugins configuration in settings.json, debugging 'plugin not working' or 'skill not showing' issues, or understanding plugin state architecture and lifecycle", - "source": "./", + "name": "scrapling-skill", + "description": "Install, troubleshoot, and use Scrapling CLI for extracting HTML, Markdown, or text from webpages. Diagnoses missing extras, Playwright browser runtime issues, TLS verification failures, and WeChat public article extraction patterns. Use when users mention Scrapling, `scrapling extract`, `uv tool install scrapling`, or need to decide between static and browser-backed fetching", + "source": "./scrapling-skill", "strict": false, "version": "1.0.0", - "category": "utilities", + "category": "developer-tools", "keywords": [ - "troubleshooting", - "debugging", - "plugins", - "skills", - "diagnostics", - "configuration", - "enabledPlugins", - "settings", - "marketplace" - ], - "skills": [ - "./claude-skills-troubleshooting" + "scrapling", + "web-scraping", + "html", + "markdown", + "playwright", + "wechat", + "extraction", + "cli" ] }, { - "name": "meeting-minutes-taker", - "description": "Transform meeting transcripts into high-fidelity, structured meeting minutes with iterative review. Features speaker identification via feature analysis (word count, speaking style, topic focus) with context.md team directory mapping, intelligent file naming from content, integration with markdown-tools and transcript-fixer for pre-processing, evidence-based recording with speaker quotes, Mermaid diagrams for architecture discussions, and multi-turn parallel generation with UNION merge", - "source": "./", + "name": "slides-creator", + "description": "Narrative-first slide deck creation. Guides users through structured narrative design (ABCDEFG model), then delegates visual generation to baoyu-slide-deck. Triggers on create slides, make a presentation, generate deck, slide deck, PPT, or when user needs to turn content into visual slides.", + "source": "./slides-creator", "strict": false, - "version": "1.1.0", - "category": "productivity", + "version": "1.0.0", + "category": "content-creation", "keywords": [ - "meeting", - "minutes", - "transcript", - "notes", - "speaker-identification", - "mermaid", - "quotes", - "action-items" - ], - "skills": [ - "./meeting-minutes-taker" + "slides", + "presentation", + "ppt", + "deck", + "narrative", + "storytelling", + "ABCDEFG" ] }, { - "name": "deep-research", - "description": "Generate format-controlled research reports with evidence tracking, citations, and iterative review. Use when users request research reports, literature reviews, market or industry analysis, competitive landscapes, policy or technical briefs, or strict report templates and section formatting", - "source": "./", + "name": "teams-channel-post-writer", + "description": "Create professional Microsoft Teams channel posts with Adaptive Cards, formatted announcements, and corporate communication standards", + "source": "./teams-channel-post-writer", "strict": false, "version": "1.0.0", - "category": "documentation", + "category": "communication", "keywords": [ - "research", - "report", - "analysis", - "literature-review", - "market-research", - "citations", - "evidence", - "deepresearch" - ], - "skills": [ - "./deep-research" + "teams", + "microsoft", + "adaptive-cards", + "communication", + "announcements" ] }, { - "name": "competitors-analysis", - "description": "Analyze competitor repositories with evidence-based approach. Use when tracking competitors, creating competitor profiles, or generating competitive analysis. All analysis must be based on actual cloned code, never assumptions. Triggers include analyze competitor, add competitor, competitive analysis, or 竞品分析", - "source": "./", + "name": "terraform-skill", + "description": "Operational traps for Terraform provisioners, multi-environment isolation, and zero-to-deployment reliability. Covers provisioner timing races, SSH connection conflicts, DNS record duplication, volume permissions, database bootstrap gaps, snapshot cross-contamination, Cloudflare credential format errors, hardcoded domains in Caddyfiles/compose, and init-data-only-on-first-boot pitfalls. Activate when writing null_resource provisioners, creating multi-environment Terraform setups, debugging containers that are Restarting/unhealthy after terraform apply, setting up fresh instances with cloud-init, or any IaC code that SSHs into remote hosts. Also activate when the user mentions terraform plan/apply errors, provisioner failures, infrastructure drift, TLS certificate errors, or Caddy/gateway configuration.", + "source": "./terraform-skill", "strict": false, "version": "1.0.1", - "category": "productivity", + "category": "developer-tools", "keywords": [ - "competitors", - "competitive-analysis", - "competitor-tracking", - "evidence-based", - "market-research", - "竞品分析", - "code-analysis" - ], - "skills": [ - "./competitors-analysis" + "terraform", + "iac", + "provisioner", + "devops", + "infrastructure", + "cloud-init", + "cloudflare" ] }, { "name": "tunnel-doctor", - "description": "Diagnoses and fixes conflicts between Tailscale and proxy/VPN tools (Shadowrocket, Clash, Surge) on macOS. Covers five conflict layers: route hijacking, HTTP proxy env var interception, system proxy bypass, SSH ProxyCommand double tunneling, and VM/container proxy propagation. Includes an automated quick-diagnose script plus SOP for remote development via SSH tunnels with proxy-safe Makefile patterns. Use when Tailscale ping works but SSH/HTTP times out, when browser returns 503 but curl works, when local vanity domains fail behind proxy, when git push fails with failed to begin relaying via HTTP, when Docker pull times out behind TUN/VPN, when setting up Tailscale SSH to WSL instances, or when bootstrapping remote dev environments over Tailscale", - "source": "./", + "description": "Diagnoses and fixes conflicts between Tailscale and proxy/VPN tools (Shadowrocket, Clash, Surge) on macOS. Covers six conflict layers: route hijacking, HTTP proxy env var interception, system proxy bypass, SSH ProxyCommand double tunneling, VM/container proxy propagation, and stalled DNS resolver in macOS getaddrinfo chain (dead VPN daemon leaves zombie utun + DNS injection). Includes an automated quick-diagnose script plus SOP for remote development via SSH tunnels with proxy-safe Makefile patterns. Use when Tailscale ping works but SSH/HTTP times out, when browser returns 503 but curl works, when local vanity domains fail behind proxy, when git push fails with failed to begin relaying via HTTP, when Docker pull times out behind TUN/VPN, when setting up Tailscale SSH to WSL instances, when bootstrapping remote dev environments over Tailscale, when ssh/curl/git hang ~60s before resolving a hostname while nslookup returns instantly, or when raw probes give impossibly-fast results under a TUN proxy (nc -z 0.00s or sub-ms ping to overseas nodes, or an IP-geo lookup reporting your proxy exit IP instead of your real home/ISP) — the TUN fabricates them locally", + "source": "./tunnel-doctor", "strict": false, - "version": "1.3.0", + "version": "1.6.1", "category": "developer-tools", "keywords": [ "tailscale", @@ -756,17 +692,69 @@ "makefile", "remote-development", "local-domain" - ], - "skills": [ - "./tunnel-doctor" + ] + }, + { + "name": "twitter-reader", + "description": "Fetch Twitter/X post content including long-form Articles with full images and metadata. Use when Claude needs to retrieve tweet/article content, author info, engagement metrics (likes, retweets, bookmarks), and embedded media. Supports individual posts and X Articles (long-form content). Automatically downloads all images to local attachments folder and generates complete Markdown with proper image references. Preferred over Jina for X Articles with images.", + "source": "./twitter-reader", + "strict": false, + "version": "1.1.0", + "category": "utilities", + "keywords": [ + "twitter", + "x", + "social-media", + "jina", + "content-fetching", + "api", + "scraping", + "threads", + "images", + "attachments", + "markdown" + ] + }, + { + "name": "ui-designer", + "description": "Extract design systems from reference UI images and generate implementation-ready UI design prompts. Use when users provide UI screenshots/mockups and want to create consistent designs", + "source": "./ui-designer", + "strict": false, + "version": "1.0.0", + "category": "design", + "keywords": [ + "ui", + "design-system", + "mockup", + "screenshot", + "design-extraction", + "mvp" + ] + }, + { + "name": "video-comparer", + "description": "Compare two videos and generate interactive HTML reports with quality metrics (PSNR, SSIM) and frame-by-frame visual comparisons. Use when analyzing compression results, evaluating codec performance, or assessing video quality differences", + "source": "./video-comparer", + "strict": false, + "version": "1.0.0", + "category": "media", + "keywords": [ + "video", + "comparison", + "quality-analysis", + "psnr", + "ssim", + "compression", + "ffmpeg", + "codec" ] }, { "name": "windows-remote-desktop-connection-doctor", "description": "Diagnose Windows App (Microsoft Remote Desktop / Azure Virtual Desktop / W365) connection quality issues on macOS. Analyze transport protocol selection (UDP Shortpath vs WebSocket), detect VPN/proxy interference with STUN/TURN negotiation, and parse Windows App logs for Shortpath failures. This skill should be used when VDI connections are slow, when transport shows WebSocket instead of UDP, when RDP Shortpath fails to establish, or when RTT is unexpectedly high.", - "source": "./", + "source": "./windows-remote-desktop-connection-doctor", "strict": false, - "version": "1.0.0", + "version": "1.0.1", "category": "developer-tools", "keywords": [ "rdp", @@ -783,98 +771,125 @@ "vpn", "macos", "networking" - ], - "skills": [ - "./windows-remote-desktop-connection-doctor" ] }, { - "name": "product-analysis", - "description": "Multi-path parallel product analysis with cross-model test-time compute scaling. Spawns parallel agents (Claude Code + Codex CLI) for multi-perspective exploration, then synthesizes findings into actionable optimization plans. Supports self-audit, UX audit, API audit, architecture review, and competitive benchmarking via competitors-analysis skill", - "source": "./", + "name": "youtube-downloader", + "description": "Download YouTube videos and HLS streams (m3u8) from platforms like Mux, Vimeo, etc. using yt-dlp and ffmpeg. Use when users request downloading videos, extracting audio, handling protected streams with authentication headers, or troubleshooting download issues like nsig extraction failures, 403 errors, or cookie extraction problems", + "source": "./youtube-downloader", "strict": false, - "version": "1.0.1", - "category": "productivity", + "version": "1.1.0", + "category": "utilities", "keywords": [ - "product-analysis", - "self-review", - "ux-audit", - "parallel-agents", - "cross-model", - "test-time-compute", - "codex", - "synthesis", - "product-audit", - "information-architecture" - ], - "skills": [ - "./product-analysis" + "youtube", + "yt-dlp", + "video-download", + "audio-extraction", + "mp3", + "download", + "hls", + "m3u8", + "ffmpeg", + "streaming", + "mux", + "vimeo" ] }, { - "name": "excel-automation", - "description": "Create, parse, and control Excel files on macOS. Professional formatting with openpyxl (font colors, fills, borders, conditional formatting), complex xlsm parsing with stdlib zipfile+xml for investment bank financial models, and Excel window control via AppleScript (zoom, scroll, select). Use when creating formatted Excel reports, parsing financial models, or automating Excel on macOS", - "source": "./", + "name": "debugging-network-issues", + "description": "Evidence-driven investigation for network, streaming, and protocol-layer bugs. Use when debugging connection resets, SSE or long-polling stalls, fixed-time connection drops, CDN/proxy/CGNAT idle timeouts, or any incident where symptoms do not match the obvious cause. Applies falsification-first methodology with layered isolation experiments, env-gated runtime instrumentation, and counter-review agent teams. Cognitive-trap catalog includes reverse-path / directional asymmetry — an external probe to a node only proves that node's return direction, not the user's failing outbound direction.", + "source": "./debugging-network-issues", + "strict": false, + "version": "1.2.0", + "category": "developer-tools", + "keywords": [ + "debugging", + "network", + "sse", + "http2", + "rst", + "econnreset", + "cloudflare", + "streaming", + "troubleshooting", + "methodology" + ] + }, + { + "name": "auto-repo-setup", + "description": "Automated repository environment configuration, fault diagnosis, and repair for non-technical users. When someone clones a repo and says 'it won't run', 'how do I set this up', 'environment issues', or 'how do I start the project', this skill reads ONBOARDING.md, audits environment gaps (git, ffmpeg, uv, Python, whisper.cpp, API keys), installs missing dependencies, validates with smoke tests, and safely handles git operations (commit, push, merge conflicts) with PII Guard and Push Safety. Also includes SessionStart hook initialization, counter-review workflows, and git history sanitization for project setup standardization.", + "source": "./auto-repo-setup", "strict": false, "version": "1.0.0", + "category": "developer-tools", + "keywords": [ + "repo-setup", + "environment", + "onboarding", + "git", + "configuration", + "claude-code", + "non-technical", + "session-start", + "pii-guard", + "whisper" + ] + }, + { + "name": "benchmark-due-diligence", + "description": "Adversarial due-diligence on a benchmark you envy (a founder, KOL, company, or product whose claimed success you suspect is inflated). Inline four-phase orchestration: fan-out collection, adversarial verification grading every claim L1-L4 to separate marketing bubble from real signal, attribution weighting (product vs timing vs personal-IP vs luck, and which parts are replicable), then mapping the validated playbook onto the commissioner's own resources with concrete next moves. Use whenever the user wants to 尽调/对标/拆解 a competitor or role-model, suspects 水分/泡沫 in someone's claims (Product Hunt #1, 0-to-1M-users, funding rounds), asks what they can actually steal from a benchmark, or wants to know if a benchmark's wins are real and copyable before betting on the same strategy. Prefer over deep-research when the goal is debunking inflated claims and extracting a replicable playbook, not a neutral briefing.", + "source": "./benchmark-due-diligence", + "strict": false, + "version": "1.0.1", "category": "productivity", "keywords": [ - "excel", - "openpyxl", - "xlsm", - "spreadsheet", - "formatting", - "financial-model", - "applescript", - "macos", - "dcf", - "investment-banking" - ], - "skills": [ - "./excel-automation" + "due-diligence", + "benchmark", + "competitor-teardown", + "对标尽调", + "破泡沫", + "bubble-busting", + "attribution", + "playbook-teardown", + "role-model", + "竞品对标" ] }, { - "name": "capture-screen", - "description": "Programmatic screenshot capture on macOS. Get window IDs via Swift CGWindowListCopyWindowInfo, capture specific windows with screencapture -l, and control application windows via AppleScript. Supports multi-shot workflows for capturing different sections of the same window. Use when taking automated screenshots, capturing application windows, or creating visual documentation", - "source": "./", + "name": "llm-wiki-setup", + "description": "Co-create a personal investment-research LLM Wiki (Andrej Karpathy's pattern) where the user's OWN analysis framework becomes a living CLAUDE.md — by interviewing them, NOT by handing them a template. Use whenever the user wants to build a compounding research knowledge base, 投研第二大脑, 投研知识库, or 个人投研 wiki; instantiate Karpathy's LLM Wiki gist for finance/investing; turn their stock-picking, analyst-tracking, or earnings-watching workflow into a structured markdown vault; or build a wiki tracking companies / industries / macro / analysts over time. Pure markdown + wikilinks, NO RAG / vector DB (Karpathy's core idea — do not over-engineer). Also triggers for ingesting research reports / earnings calls / expert notes into an existing wiki, and for post-earnings prediction→fulfillment reviews. Core value = extracting the user's personal investment preferences into THEIR OWN schema, never imposing a standard one.", + "source": "./llm-wiki-setup", "strict": false, "version": "1.0.0", - "category": "utilities", + "category": "documentation", "keywords": [ - "screenshot", - "screencapture", - "macos", - "window-capture", - "swift", - "applescript", - "automation", - "visual-documentation" - ], - "skills": [ - "./capture-screen" + "llm-wiki", + "karpathy", + "investment-research", + "投研第二大脑", + "knowledge-base", + "markdown-wiki", + "compounding-notes", + "analyst-tracking", + "second-brain", + "投研知识库" ] }, { - "name": "financial-data-collector", - "description": "Collect real financial data for any US publicly traded company from free public sources (yfinance). Output structured JSON with market data, historical financials, WACC inputs, and analyst estimates. Handles NaN year detection, CapEx sign preservation, and FCF definition mismatches. Use when users request company financials, stock data, DCF inputs, or financial data collection for any US equity ticker", - "source": "./", + "name": "marketplace-health-check", + "description": "Run a full 6-dimension health check of this Claude Code skills marketplace repo — code/script safety, documentation/SSOT consistency, security/PII leaks, open-PR triage, open-issue triage, and marketplace-manifest integrity — via a parallel fan-out Dynamic Workflow, then verify the serious findings and report by priority. Use this whenever the user asks to check the repo, run a health check, do a full sweep/audit before a release, 全面体检, 检查仓库状态, 看看仓库健康吗, 审计一下仓库, or asks whether the PRs / issues / docs / versions / PII are in good shape across the board — even if they never say workflow. Reach for it for any broad is-this-whole-repo-OK request, not just one-file checks.", + "source": "./marketplace-health-check", "strict": false, "version": "1.0.0", - "category": "productivity", + "category": "developer-tools", "keywords": [ - "finance", - "financial-data", - "yfinance", - "stock-data", - "dcf", - "wacc", - "market-data", - "investment-research", - "sec-filings" - ], - "skills": [ - "./financial-data-collector" + "health-check", + "audit", + "marketplace", + "workflow", + "pii", + "code-review", + "repo-audit" ] } ] diff --git a/.githooks/pre-commit b/.githooks/pre-commit new file mode 100755 index 00000000..89d8979a --- /dev/null +++ b/.githooks/pre-commit @@ -0,0 +1,53 @@ +#!/bin/bash +# Pre-commit hook: scan staged changes for sensitive data +# Install: git config core.hooksPath .githooks + +set -euo pipefail + +RED='\033[0;31m' +GREEN='\033[0;32m' +YELLOW='\033[1;33m' +NC='\033[0m' + +echo "🔍 Scanning staged changes for sensitive data..." + +FAILED=0 + +# Layer 1: gitleaks (if available) +if command -v gitleaks &>/dev/null; then + if ! gitleaks protect --staged --config .gitleaks.toml --no-banner 2>/dev/null; then + echo -e "${RED}❌ gitleaks found secrets in staged changes${NC}" + FAILED=1 + fi +else + echo -e "${YELLOW}⚠ gitleaks not installed (brew install gitleaks), falling back to pattern scan${NC}" +fi + +# Layer 2: fast regex scan (always runs, catches what gitleaks config might miss) +STAGED_DIFF=$(git diff --cached --diff-filter=ACDMR) + +PATTERNS=( + '/Users/[a-zA-Z][a-zA-Z0-9_-]+/' + '/home/[a-zA-Z][a-zA-Z0-9_-]+/' + 'C:\\Users\\[a-zA-Z]' + 'songtiansheng' + 'tiansheng' + '15366[0-9]+' +) + +for pattern in "${PATTERNS[@]}"; do + MATCHES=$(echo "$STAGED_DIFF" | grep -nE "^\+" | grep -E "$pattern" | grep -v "^+++\|\.gitleaks\.toml\|\.githooks/\|\.gitignore\|placeholder\|example\|CLAUDE\.md" || true) + if [ -n "$MATCHES" ]; then + echo -e "${RED}❌ Found sensitive pattern '${pattern}':${NC}" + echo "$MATCHES" | head -5 + FAILED=1 + fi +done + +if [ $FAILED -eq 1 ]; then + echo "" + echo -e "${RED}Commit blocked. Fix the issues above, or use --no-verify to bypass (not recommended).${NC}" + exit 1 +fi + +echo -e "${GREEN}✅ No sensitive data found in staged changes.${NC}" diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index 51966ef5..7de86f63 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -16,7 +16,7 @@ Which skill is affected? - [ ] skill-creator - [ ] github-ops -- [ ] markdown-tools +- [ ] doc-to-markdown - [ ] mermaid-tools - [ ] statusline-generator - [ ] teams-channel-post-writer diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md index edaf3704..050c3e22 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.md +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -20,7 +20,7 @@ Which skill would this enhance? - [ ] skill-creator - [ ] github-ops -- [ ] markdown-tools +- [ ] doc-to-markdown - [ ] mermaid-tools - [ ] statusline-generator - [ ] teams-channel-post-writer diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 27a4c902..3fb1ce61 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -33,7 +33,7 @@ Which skills are affected by this PR? - [ ] skill-creator - [ ] github-ops -- [ ] markdown-tools +- [ ] doc-to-markdown - [ ] mermaid-tools - [ ] statusline-generator - [ ] teams-channel-post-writer @@ -70,8 +70,8 @@ How has this been tested? - [ ] Scripts are executable (chmod +x) - [ ] No absolute paths or user-specific information - [ ] Tested in actual Claude Code session -- [ ] Passed validation: `skill-creator/scripts/quick_validate.py` -- [ ] Successfully packages: `skill-creator/scripts/package_skill.py` +- [ ] Passed validation: `daymade-skill/skill-creator/scripts/quick_validate.py` +- [ ] Successfully packages: `daymade-skill/skill-creator/scripts/package_skill.py` ### For All PRs diff --git a/.github/workflows/benchmark.yml b/.github/workflows/benchmark.yml new file mode 100644 index 00000000..ba99aae0 --- /dev/null +++ b/.github/workflows/benchmark.yml @@ -0,0 +1,190 @@ +name: Benchmark Tests + +on: + schedule: + # Run weekly on Sundays at 2 AM UTC + - cron: '0 2 * * 0' + workflow_dispatch: + inputs: + test_type: + description: 'Test type to run' + required: true + default: 'all' + type: choice + options: + - all + - scrape + - annotation + - full + +env: + NODE_VERSION: '20' + +jobs: + scrape-benchmark: + name: Scrape Success Rate Benchmark + runs-on: ubuntu-latest + if: github.event.inputs.test_type == 'all' || github.event.inputs.test_type == 'scrape' || github.event.inputs.test_type == 'full' + timeout-minutes: 60 + + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: ${{ env.NODE_VERSION }} + cache: 'npm' + cache-dependency-path: cloud/package-lock.json + + - name: Install dependencies + working-directory: cloud + run: npm ci + + - name: Install Playwright browsers + working-directory: cloud + run: npx playwright install --with-deps chromium + + - name: Run scrape benchmark + working-directory: cloud + env: + JINA_AI_API_KEY: ${{ secrets.JINA_AI_API_KEY }} + OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }} + SUPABASE_URL: ${{ secrets.SUPABASE_URL }} + SUPABASE_ANON_KEY: ${{ secrets.SUPABASE_ANON_KEY }} + run: | + npx vitest run tests/benchmark/scrape-benchmark.ts --reporter=verbose 2>&1 | tee scrape-benchmark.log + + - name: Upload benchmark results + uses: actions/upload-artifact@v4 + if: always() + with: + name: scrape-benchmark-results + path: | + cloud/tests/benchmark/scrape-benchmark-report.json + cloud/scrape-benchmark.log + retention-days: 30 + + - name: Check success rate threshold + working-directory: cloud + run: | + if [ -f tests/benchmark/scrape-benchmark-report.json ]; then + SUCCESS_RATE=$(jq -r '.summary.successRate' tests/benchmark/scrape-benchmark-report.json | sed 's/%//') + echo "Success Rate: ${SUCCESS_RATE}%" + if (( $(echo "$SUCCESS_RATE >= 95" | bc -l) )); then + echo "✅ SUCCESS: Meet target of 95%" + exit 0 + else + echo "❌ FAILURE: Below target of 95%" + exit 1 + fi + else + echo "Report not generated" + exit 1 + fi + + annotation-benchmark: + name: Annotation Accuracy Benchmark + runs-on: ubuntu-latest + if: github.event.inputs.test_type == 'all' || github.event.inputs.test_type == 'annotation' || github.event.inputs.test_type == 'full' + timeout-minutes: 10 + + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: ${{ env.NODE_VERSION }} + cache: 'npm' + cache-dependency-path: cloud/package-lock.json + + - name: Install dependencies + working-directory: cloud + run: npm ci + + - name: Run annotation accuracy test + working-directory: cloud + run: | + npx vitest run tests/benchmark/annotation-accuracy.ts --reporter=verbose 2>&1 | tee annotation-accuracy.log + + - name: Upload benchmark results + uses: actions/upload-artifact@v4 + if: always() + with: + name: annotation-accuracy-results + path: | + cloud/tests/benchmark/annotation-accuracy-report.json + cloud/annotation-accuracy.log + retention-days: 30 + + - name: Check accuracy threshold + working-directory: cloud + run: | + if [ -f tests/benchmark/annotation-accuracy-report.json ]; then + ACCURACY=$(jq -r '.summary.positionAccuracy' tests/benchmark/annotation-accuracy-report.json | sed 's/%//') + echo "Position Accuracy: ${ACCURACY}%" + if (( $(echo "$ACCURACY >= 98" | bc -l) )); then + echo "✅ SUCCESS: Meet target of 98%" + exit 0 + else + echo "❌ FAILURE: Below target of 98%" + exit 1 + fi + else + echo "Report not generated" + exit 1 + fi + + full-benchmark: + name: Full Benchmark Suite + runs-on: ubuntu-latest + if: github.event.inputs.test_type == 'full' + needs: [scrape-benchmark, annotation-benchmark] + timeout-minutes: 90 + + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Download all artifacts + uses: actions/download-artifact@v4 + + - name: Generate combined report + run: | + echo "# 📊 Full Benchmark Report" > benchmark-report.md + echo "" >> benchmark-report.md + echo "Generated at: $(date -u +"%Y-%m-%d %H:%M:%S UTC")" >> benchmark-report.md + echo "" >> benchmark-report.md + + if [ -f scrape-benchmark-results/scrape-benchmark-report.json ]; then + echo "## Scraping Success Rate" >> benchmark-report.md + cat scrape-benchmark-results/scrape-benchmark-report.json | jq -r '.summary | to_entries[] | "- \(.key): \(.value)"' >> benchmark-report.md + echo "" >> benchmark-report.md + fi + + if [ -f annotation-accuracy-results/annotation-accuracy-report.json ]; then + echo "## Annotation Accuracy" >> benchmark-report.md + cat annotation-accuracy-results/annotation-accuracy-report.json | jq -r '.summary | to_entries[] | "- \(.key): \(.value)"' >> benchmark-report.md + fi + + - name: Upload combined report + uses: actions/upload-artifact@v4 + with: + name: full-benchmark-report + path: benchmark-report.md + + - name: Create GitHub Issue on failure + if: failure() + uses: actions/github-script@v7 + with: + script: | + github.rest.issues.create({ + owner: context.repo.owner, + repo: context.repo.repo, + title: `❌ Benchmark Failed - ${new Date().toISOString().split('T')[0]}`, + body: `Benchmark tests failed. Check the [Actions run](${context.payload.repository.html_url}/actions/runs/${context.runId}) for details.`, + labels: ['benchmark', 'automated'] + }); diff --git a/.gitignore b/.gitignore index 27c1cf97..d4dee630 100644 --- a/.gitignore +++ b/.gitignore @@ -59,6 +59,7 @@ Thumbs.db *.tgz *.rar *.7z +*.skill # Build artifacts *.o @@ -81,3 +82,23 @@ INSTALLATION.md # Private/commercial skills (moved to claude-code-skills-pro) seo-expert/ video-creator/ +/jsonl-viewer/ + +# Research output (may contain sensitive data) +deep-research-output/ +recovered_deep_research/ + +# OpenCLI cache +.opencli/ + +# Eval / runtime workspaces (test data, snapshots — never committed) +*-workspace/ +.gstack/ + +# Claude Code local settings +.claude/settings.local.json +.claude/archive/ + +# Generated artifacts +coverage/ +node_modules/ diff --git a/.gitleaks.toml b/.gitleaks.toml new file mode 100644 index 00000000..3ac81bb7 --- /dev/null +++ b/.gitleaks.toml @@ -0,0 +1,57 @@ +# Gitleaks custom rules for claude-code-skills repo +# Catches personal info that shouldn't be in an open source repo + +title = "claude-code-skills sensitive data rules" + +[extend] +useDefault = true + +# Global allowlist: files that are allowed to contain patterns +# (the config file itself, hooks, and contribution guides) +[allowlist] +paths = [ + '''\.gitleaks\.toml$''', + '''\.githooks/''', + '''CONTRIBUTING\.md$''', + '''CLAUDE\.md$''', +] +regexes = [ + # Douban mobile app's public API key (documented as public, hardcoded for zero-config usage) + '''0dad551ec0f84ed02907ff5c42e8ec70''', +] + +[[rules]] +id = "absolute-user-path-macos" +description = "Hardcoded macOS user home directory path" +regex = '''/Users/[a-zA-Z][a-zA-Z0-9_-]+/''' +tags = ["pii", "path"] + +[[rules]] +id = "absolute-user-path-linux" +description = "Hardcoded Linux home directory path" +regex = '''/home/[a-zA-Z][a-zA-Z0-9_-]+/''' +tags = ["pii", "path"] + +[[rules]] +id = "windows-user-path" +description = "Hardcoded Windows user profile path" +regex = '''C:\\Users\\[a-zA-Z][a-zA-Z0-9_-]+\\''' +tags = ["pii", "path"] + +[[rules]] +id = "phone-number-cn" +description = "Chinese mobile phone number" +regex = '''\b1[3-9]\d{9}\b''' +tags = ["pii", "phone"] + +[[rules]] +id = "douban-user-id-literal" +description = "Hardcoded Douban user ID" +regex = '''songtiansheng''' +tags = ["pii", "username"] + +[[rules]] +id = "email-personal" +description = "Personal email address" +regex = '''[a-zA-Z0-9._%+-]+@(gmail|qq|163|126|outlook|hotmail|yahoo|icloud|foxmail)\.[a-zA-Z]{2,}''' +tags = ["pii", "email"] diff --git a/.pii-path-patterns b/.pii-path-patterns new file mode 100644 index 00000000..1898ca40 --- /dev/null +++ b/.pii-path-patterns @@ -0,0 +1,4 @@ +# Repo-specific local/generated artifact paths that must never be committed +(^|/)coverage(/|$) +(^|/)node_modules(/|$) +(^|/).*\.db$ diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml new file mode 100644 index 00000000..370d60a2 --- /dev/null +++ b/.pre-commit-config.yaml @@ -0,0 +1,34 @@ +minimum_pre_commit_version: "3.2.0" +default_install_hook_types: + - pre-commit + - pre-push +default_stages: + - pre-commit + - pre-push + +repos: + - repo: https://github.com/pre-commit/pre-commit-hooks + rev: v5.0.0 + hooks: + - id: check-merge-conflict + - id: check-added-large-files + args: + - --maxkb=1500 + + - repo: https://github.com/gitleaks/gitleaks + rev: v8.30.0 + hooks: + - id: gitleaks + stages: + - pre-commit + + - repo: local + hooks: + - id: repo-path-guard + name: repo path guard + entry: python3 scripts/repo_path_guard.py + language: system + pass_filenames: true + stages: + - pre-commit + - pre-push diff --git a/CHANGELOG.md b/CHANGELOG.md index 14c1c277..243b4a0e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,7 +8,340 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] ### Added -- None +- **marketplace-health-check** v1.0.0: new skill — the 6-dimension repo health-check workflow distilled from a real audit session, fixed as a reusable skill. A parallel fan-out Dynamic Workflow runs six inspectors (code/script safety, documentation/SSOT consistency, security/PII, open-PR triage, open-issue triage, marketplace-manifest integrity); the skill then Counter-Reviews every high/critical finding (agent findings are hypotheses, verified before reporting) and reports by priority. Bundles the proven workflow script + a methodology reference (anti-target PII rule, working-copy-vs-history distinction, scan-marker necessary-not-sufficient, the broken-install-command bug class, promotion-decline default). Inline orchestrator — uses the Workflow tool, so it must not run forked. + +### Changed +- **Doc-governance hardening** (post-v1.65.0 health-check): `check_doc_skill_lists.py` now also asserts the README version badge equals `marketplace.json` metadata.version — that badge silently drifted twice (1.63→1.64, 1.64→1.65) when a metadata bump forgot it, so the drift guard enforces it instead of relying on manual discipline (`daymade-claude-code` suite v1.2.1). Slimmed `marketplace.json` metadata.description from a per-skill enumeration (which had silently fallen ~11 skills behind) to a category-level summary that points to the README for the authoritative breakdown. Removed a duplicate `## [1.56.0]` CHANGELOG header. + +### Fixed +- **cloudflare-troubleshooting** v1.0.2 ([#89](https://github.com/daymade/claude-code-skills/issues/89)): `scripts/fix_ssl_mode.py` now runs in dry-run mode by default, prints the current SSL mode and target mode before writing, and requires `--apply` before changing live Cloudflare SSL settings or purging cache. Updated troubleshooting references so mutating examples include the explicit apply flag. +- **repomix-safe-mixer** v1.0.1: the "before" examples in SKILL.md + `references/common_secrets.md` used a real-looking Supabase project ref + JWT, flagged CRITICAL by the bundled scanner — which had never run on this skill (it shipped with no `.security-scan-passed` marker). Replaced with neutral placeholders. Also backfilled `.security-scan-passed` markers for 20 skills that shipped without a recorded scan (one of which, repomix-safe-mixer, is exactly why — it had a real leak no one had scanned for). +- **Sensitive-info sanitization** (full health-check findings): removed the owner's real private domains from shipped examples — `tunnel-doctor` v1.6.1 (`quick_diagnose.py` default `--host` + SKILL.md example) and `terraform-skill` v1.0.1 (Caddyfile / compose / SQL examples) — and a real personal handle used as a speaker-name example in `transcript-fixer` (`daymade-audio` suite v1.2.1); all replaced with `example.com` / neutral placeholders. These were pre-existing leaks predating the global PII-guard domain rules (which already cover them for future diffs). The repo-local `.gitleaks.toml` is deliberately NOT given the real private values — a public allowlist enumerating real assets would itself be a leak (anti-target principle). +- **Broken flagship install commands** ([#67](https://github.com/daymade/claude-code-skills/issues/67)): `claude plugin install skill-creator@daymade-skills` (plus `skill-reviewer` / `skills-search` / `doc-to-markdown`) failed because those are suite members, not standalone plugins. Corrected every occurrence across README.md, README.zh-CN.md, QUICKSTART.md, QUICKSTART.zh-CN.md to the suite name (`daymade-skill@daymade-skills` / `daymade-docs@daymade-skills`), invoked as `daymade-skill:skill-creator` etc. + +## [1.64.0] - 2026-06-13 + +### Added +- **claude-usage-analyst** (`daymade-claude-code` v1.2.0): new skill — turns local `ccusage` data into an evidence-based, human-readable explanation of Claude Code / Claude Desktop token usage, cost, quota burn, model mix, and cache read/write pressure. Bundled `analyze_claude_usage.py` summarizes any date window/timezone; model-comparison mode weighs token volume against estimated cost (a model can be cheap per token but expensive overall); a 5-hour-block table addresses quota-exhaustion questions. Evidence discipline: numbers are grounded in `ccusage` output and scope is stated explicitly (local Claude Code logs, not a full Claude.ai chat bill). Registered into the `daymade-claude-code` suite (skills[] + suite 1.1.0 → 1.2.0); marketplace catalog 1.63.0 → 1.64.0. +- **skill-creator** (`daymade-skill` v1.2.0): five incident-distilled authoring rules, each placed at the workflow step where it fires: + - *Step 4*: validate immediately after every SKILL.md edit (strict-YAML `quick_validate`, not packaging-time) + block-scalar `>-` convention for descriptions containing `: ` / ` #` — lenient/strict parser divergence and silent ` #` description truncation both shipped undetected before this. + - *Step 5*: sanitization is scoped **by destination** — only the publicly-shipping skill bundle gets redacted; private-repo companion docs (incident reports, runbooks) keep audit-grade real values. Placeholders must not encode the real value they hide; bulk replaces need an explicit file whitelist scoped to the skill directory. + - *Bundled Resources*: user-mutable data (correction dictionaries, learned preferences) lives under `~/./` outside the bundle — installs are wiped on every update/suite-migration, a home-relative store survives untouched. + - *Capture Intent*: mining past-session transcripts must be delegated to subagents with line-by-line truncated extraction — a full-context attempt died 17 tokens over the window limit and killed the session. + - *Privacy & Paths*: cross-skill references — bare relative paths always mean "own bundle" (validators treat them so); name the owner skill in prose and invoke by namespaced `/suite:skill`. Marketplace-entry rename/relocation/removal flagged as a breaking change (dangling installs; mechanics live in marketplace-dev). + - New "Phase 9 实战案例库" in `references/skill-development-methodology.md` preserving the four incident case files behind these rules; `references/schemas.md` gains a table of contents (8 schemas, >100 lines). +- **bilibili-source** v1.0.0: new skill — login-free fetch of comprehensive Bilibili (B站) video data in one `view/detail` call (title, UP follower count, tags, partition, per-part cids, live stats, and full danmaku text), accepting BVID / `av` number / `b23.tv` short link / full URL with the BVID-regex, multi-part-cid, and short-link edge cases all handled. Login-gated subtitles via `yt-dlp` (asks before reading browser cookies — no anonymous path exists, verified). Bundles a `bili-selftest.sh` health-check that detects API drift against a stable fixture, an API reference including the WBI request-signing algorithm, and 4 evals. All examples use synthetic/neutral data; metrics always carry a `fetched_at` timestamp (NO-FABRICATION discipline). +- **pdf-creator** (`daymade-docs` v1.1.0): new `warm-terra-menu` theme — a warm-terra variant hardened for 2-column long-text module menus (full-column wrap removes first-column overflow; a Menlo `unicode-range` keeps CJK inline-code from rendering blank in Preview/Adobe Reader). +- **tunnel-doctor** v1.6.0: Add "TUN Measurement Contamination" diagnostic section — while a proxy runs in TUN/global mode, common probes lie: `nc -z` shows a fabricated `0.00s` handshake (TUN completes it locally), `ping`/`remote_ip` are spoofed, and a foreign IP-geo lookup reports the proxy exit instead of the real home IP. Documents what to trust instead (`time_appconnect`/`time_starttransfer`, an in-region IP-geo source, config-decode + GUI cross-check) and adds matching trigger phrases. +- **debugging-network-issues** v1.2.0: New **Step 0.6 "upload-timeout vs processing-timeout"** recipe for large `POST` bodies behind a CDN — compare `bytes_read` to `Content-Length` in the edge/reverse-proxy log; a `status=0` / "client abort" is often the CDN edge timing out first, not a backend stall. Adds a second case study `references/case-cloudflare-524-upload.md` (a ~6 MB request body uploaded slower than Cloudflare's ~120 s origin read timeout → 524 while every backend was healthy) and cognitive Trap 10 "edge timeouts masquerading as upstream client aborts". Also adds cognitive Trap 12 "Reverse-path / directional asymmetry" — A→B healthy does not imply B→A healthy; an external probe to a node only proves that node's return direction, systematically missing the user's failing outbound direction (and the congested direction is often one an external probe structurally cannot reach). Sibling to Trap 5 (probe self-verification); synced into the SKILL.md trap list; fixed a stale "All nine traps" count in the summary. + +### Fixed +- **skill-creator** (`daymade-skill` v1.2.0): `quick_validate` was failing on skill-creator itself — the marketplace-dev cross-reference was written as a bare `references/cache_and_source_patterns.md` path, which the validator (correctly, per the new cross-skill reference rule) treated as a missing local file; rewritten as a prose owner reference. Also fixed "has wrote" → "has written". +- **SKILL.md frontmatter strict-YAML validity (codex compatibility).** `description:` values are unquoted YAML plain scalars, so a `: ` or ` #` inside them breaks strict parsers — Claude Code's lenient frontmatter parser accepted them, codex did not. + - **tunnel-doctor** v1.5.2: `: ` inside literal ssh output (`"debug2: resolving"`, `"debug1: connect"`) raised a `ScannerError`; wrapped the description in single quotes so the ssh strings stay verbatim. + - **benchmark-due-diligence** v1.0.1: ` #` in `Product Hunt #1` silently truncated the parsed description; reordered to `#1 on Product Hunt` (no keyword loss). + - **pdf-creator** (`daymade-docs` v1.1.0): `**Scope: markdown → PDF only.**` → `**Scope — markdown → PDF only.**`. + +### Changed +- `daymade-skill` suite: 1.1.0 → 1.2.0 (skill-creator authoring rules above; also covers the previously-unversioned "Plugin boundaries are not this skill's domain" SSOT pointer added to skill-creator in the marketplace-dev consolidation). +- **macos-cleaner** v1.1.1 → v1.2.0 ([#84](https://github.com/daymade/claude-code-skills/pull/84), thanks @geniusart): progressive-disclosure refactor — moved Docker deep-analysis (Step 2A-2C), Mole multi-layer TUI exploration, and the object-level/report templates out of SKILL.md into `references/docker_analysis.md`, `references/mole_integration.md`, and `references/report_templates.md` (SKILL.md trimmed ~440 lines, zero content loss). Aligned the Example workflows with Core Principle 9 (provide commands for the user to run + `df -h` verification, never auto-execute `rm -rf`; point to `safe_delete.py` for interactive confirmation) and hardened `cleanup_report.py` exception handling (bare `except:` → specific exception types). + +## [1.62.0] - 2026-06-07 + +### Added +- **terminal-screenshot** v1.0.0 (`daymade-claude-code` suite): render a terminal CLI's colored output to a PNG so Claude can *see* the real visual result (color contrast, alignment, background blocks) instead of raw ANSI codes — for verifying delta/bat/starship/lazygit color config. Capture-then-render discipline (never `freeze --execute` complex CLIs, which degrade in a child pty and drop background blocks); freeze-first renderer with a bundled stdlib ANSI→HTML + headless-Chrome fallback; per-CLI capture recipes. Bundled `render_ansi.sh`, `ansi2html.py`. +- **check_doc_skill_lists.py** (`marketplace-dev`): drift guard comparing the skill lists in CLAUDE.md / README.md / README.zh-CN.md against the authoritative marketplace.json (expanded), reporting MISSING and GHOST entries per doc and exiting non-zero on drift. + +### Changed +- Marketplace version: 1.60.1 → 1.62.0; `daymade-claude-code` suite: 1.0.0 → 1.1.0 (adds terminal-screenshot). +- Synced documentation skill counts to the authoritative 61: README.md / README.zh-CN.md badges + descriptions, CLAUDE.md overview (54 → 61) and plugin-entry count (39 → 43). +- Backfilled the CLAUDE.md Available Skills list to 61 (added marketplace-dev, asr-transcribe-to-text, bigdata-skill, gangtise-copilot, llm-wiki-setup, benchmark-due-diligence, pdf-to-html, terminal-screenshot) and removed the ghost `wechat-article-scraper` entry (skill no longer on disk). +- Backfilled all missing README.md / README.zh-CN.md skill sections (asr-transcribe-to-text, marketplace-dev, skill-creator, feishu-doc-scraper, bigdata-skill, gangtise-copilot, llm-wiki-setup, benchmark-due-diligence, plus auto-repo-setup in zh-CN); all three doc lists (CLAUDE.md / README.md / README.zh-CN.md) now pass `check_doc_skill_lists.py`. + +## [1.60.1] - 2026-06-05 + +### Fixed +- **macos-cleaner** v1.1.0 → v1.1.1: Hardened `safe_delete.py` with forced high-risk path blocking before confirmation and inside `delete_path()`, and updated `find_app_remnants.py` to match installed apps by Bundle Identifier as well as display name. Fixes [#70](https://github.com/daymade/claude-code-skills/issues/70). +- Marketplace version: 1.60.0 → 1.60.1 + +## [1.60.0] - 2026-05-31 + +### Added +- **auto-repo-setup** v1.0.0: Automated repository environment configuration, fault diagnosis, and repair for non-technical users. Reads ONBOARDING.md, audits environment gaps, installs missing dependencies, validates with smoke tests, and safely handles git operations with PII Guard and Push Safety. Includes SessionStart hook initialization, counter-review workflows, and git history sanitization. + +## [1.56.0] - 2026-05-24 + +### Changed +- **All 4 suites are now suite-only.** Removed 17 standalone plugin entries from `marketplace.json` so suite member skills are reachable **only** via their suite. This unifies `daymade-audio`, `daymade-claude-code`, and `daymade-docs` with `daymade-skill` (which has been suite-only since inception). Each skill keeps its own SKILL.md, version, and bundled scripts unchanged on disk under `//`. + - `daymade-audio` (5 removed): `asr-transcribe-to-text`, `stepfun-asr`, `stepfun-tts`, `transcript-fixer`, `meeting-minutes-taker` + - `daymade-claude-code` (7 removed): `claude-code-history-files-finder`, `continue-claude-work`, `claude-skills-troubleshooting`, `claude-md-progressive-disclosurer`, `statusline-generator`, `claude-export-txt-better`, `marketplace-dev` + - `daymade-docs` (5 removed): `doc-to-markdown`, `mermaid-tools`, `pdf-creator`, `ppt-creator`, `docs-cleaner` +- Marketplace plugin entry count: 56 → 39 (17 standalone entries dropped; all 4 suite entries preserved). +- README.md / README.zh-CN.md: removed standalone `claude plugin install @daymade-skills` commands for the 17 affected skills (suite install commands at the top of "Quick Start" remain authoritative); rewrote three "Single-skill plugins remain available" / "instead of the repeating `:` form" sentences that became false after the unification; repaired broken doc links `./transcript-fixer/references/…` and `./daymade-docs/meeting-minutes-taker/SKILL.md` (leftovers from the 1.54.0 suite migration) to `./daymade-audio/…`; removed stale `/daymade-docs:meeting-minutes-taker` listing (meeting-minutes-taker moved to `daymade-audio` in 1.54.0 but the docs suite namespace listing was not updated). +- CLAUDE.md: plugin entry count 56 → 39; replaced "Suite-only members" partial list with an all-suite policy statement plus guidance to NOT create parallel standalone entries when adding new suite member skills. + +### Migration +- **Existing users** of any of the 17 affected standalone plugins (`transcript-fixer@daymade-skills`, `statusline-generator@daymade-skills`, `pdf-creator@daymade-skills`, `ppt-creator@daymade-skills`, `doc-to-markdown@daymade-skills`, `mermaid-tools@daymade-skills`, `docs-cleaner@daymade-skills`, `claude-code-history-files-finder@daymade-skills`, `continue-claude-work@daymade-skills`, `claude-skills-troubleshooting@daymade-skills`, `claude-md-progressive-disclosurer@daymade-skills`, `claude-export-txt-better@daymade-skills`, `marketplace-dev@daymade-skills`, `asr-transcribe-to-text@daymade-skills`, `stepfun-asr@daymade-skills`, `stepfun-tts@daymade-skills`, `meeting-minutes-taker@daymade-skills`) should: + 1. Run `claude plugin marketplace update daymade-skills` + 2. Install the corresponding suite: `claude plugin install daymade-audio@daymade-skills`, `claude plugin install daymade-claude-code@daymade-skills`, or `claude plugin install daymade-docs@daymade-skills` + 3. Update any scripts / docs that invoke skills by namespace: `:` → `:` (e.g., `transcript-fixer:transcript-fixer` → `daymade-audio:transcript-fixer`) +- **Personal data is safe.** Skills that persist user data write to `$HOME` (e.g., `transcript-fixer` dictionary lives at `~/.transcript-fixer/corrections.db`); reinstalling or switching plugin namespaces does not touch user state. +- **`skill-creator` and other single-skill plugins are unaffected.** Only the 17 listed skills (members of the 3 newly-unified suites) need the migration. + +## [1.54.0] - 2026-05-10 + +### Added +- **daymade-audio** suite v1.0.0: Audio processing suite covering the full speech pipeline — ASR transcription (Qwen3, StepFun), transcript error correction, structured meeting minutes generation, and TTS voice synthesis. Bundles 5 skills: `asr-transcribe-to-text`, `stepfun-asr`, `transcript-fixer`, `meeting-minutes-taker`, `stepfun-tts`. + +### Changed +- Move `meeting-minutes-taker` from `daymade-docs` to `daymade-audio` — its core capability is semantic analysis of meeting transcripts, not document format processing. +- Move `asr-transcribe-to-text`, `stepfun-asr`, `stepfun-tts`, `transcript-fixer` from repo root into `daymade-audio/` suite directory. +- Marketplace plugin count: 55 → 56 (4 suites now: `daymade-audio`, `daymade-claude-code`, `daymade-docs`, `daymade-skill`). + +## [1.53.2] - 2026-05-10 + +### Fixed +- Remove `skills: ["./"]` from 13 suite member plugin entries that triggered Claude Code 2.1.x path-escape validator error (`skills path "./" escapes plugin root`). Fixes [#64](https://github.com/daymade/claude-code-skills/issues/64). + +### Changed +- Align all 52 single-skill plugins with official Anthropic marketplace pattern: `source` points directly to the skill directory (e.g., `"./tunnel-doctor"`), `skills` field omitted (auto-discovery). Previously used `source: "./"` with `skills: ["./skill-name"]`. The 3 suite plugins (`daymade-claude-code`, `daymade-docs`, `daymade-skill`) retain explicit `skills` arrays for multi-skill routing. Matches the pattern used by 167 of 168 plugins in `anthropics/claude-plugins-official`. + +## [1.52.0] - 2026-04-30 + +### Added +- **stepfun-asr** v1.0.0: Transcribe audio with StepFun's `stepaudio-2.5-asr` — an SSE endpoint (NOT `/v1/audio/transcriptions`) with 32K context, ~85-101× RTF on long audio, and a single-call ceiling around 30 minutes (no client-side chunking). Split out from `stepfun-tts` so the ASR-specific traps (wrong-endpoint misleading error, Plan vs Normal key silent failure, SSE `error` event handling, repetition-hallucination edge case) live next to the `asr_transcribe.py` script that handles them. Bundled `scripts/asr_transcribe.py` (pure-stdlib CLI: env → `${CLAUDE_PLUGIN_DATA}/config.json` key resolution, base64 + nested JSON body, SSE parsing, censorship + transport error distinction). References cover the full SSE event contract, the legacy-vs-2.5 endpoint comparison table, and the "Plan key cannot call audio" gotcha. Suggests `transcript-fixer` / `meeting-minutes-taker` as natural downstream skills. + +### Changed +- **stepfun-tts** v1.0.0 → v2.0.0 (BREAKING): ASR functionality removed and split into the new `stepfun-asr` skill. The remaining skill focuses purely on Contextual TTS (`stepaudio-2.5-tts`) — `instruction` natural-language tone + inline `()` parentheses + the `voice_label` migration story from `step-tts-2`. SKILL.md, `references/api_reference.md`, and `references/known_issues.md` all stripped of ASR sections; description and keywords updated to TTS-only. `scripts/asr_transcribe.py` removed from this skill (now lives in `stepfun-asr`). +- Marketplace skill count: 51 → 52 (effective listed count; suite member skills not double-counted) +- Marketplace plugin entry count: 55 → 56 +- Marketplace version: 1.51.0 → 1.52.0 +- README.md, README.zh-CN.md: badges, descriptions, skill section #50 (stepfun-tts retitled "TTS only" + description rewritten), new skill section #52 (stepfun-asr), Use Cases entries (split into two), Documentation Quick Links, Requirements (StepFun key applies to both) +- CLAUDE.md: overview count, marketplace plugin count, Available Skills list (entry #50 description rewritten + new entry #52) + +### Note +This release also reconciles a versioning drift: commits `b2003d6` (statusline-generator → v1.1.0) and `ec7c313` (pdf-creator → v1.4.0) bumped their respective `plugins[].version` fields without bumping `metadata.version` and without adding CHANGELOG entries — a violation of the "any commit modifying a skill must bump that skill's version AND the marketplace metadata version" rule from `CLAUDE.md`. Those commits remain in history; v1.52.0 picks up the marketplace catalog version where it should have been after both, then adds the stepfun split on top. CHANGELOG entries for those individual skill bumps will not be retroactively backfilled — the version numbers in `marketplace.json` are authoritative and discoverable via `git log -- `. + +## [1.51.0] - 2026-04-26 + +### Added +- **debugging-network-issues** v1.0.0: Evidence-driven, falsification-first methodology for network, streaming, and protocol-layer bugs where the obvious cause is probably wrong. Built from a real 5-hour production case (SSE RST_STREAM at exactly 130s, traced to a CGNAT idle timeout). Provides layered-isolation experiments (run the same logical request through 3+ paths differing by one hop), env-gated runtime instrumentation patterns, and a counter-review four-question filter to challenge single-cause assumptions before shipping a fix. Bundles probe scripts (`layered-isolation-probe.sh`, `mock-idle-upstream.py`) and reference docs covering counter-review, packet-capture recipes, instrumentation patterns, and cognitive traps. Triggers on `ECONNRESET`, HTTP/2 `RST_STREAM`, `INTERNAL_ERROR`, fixed-time SSE drops, CDN/proxy/CGNAT idle timeouts, and "works sometimes / fails after N seconds" patterns. +- **stepfun-tts** v1.0.0: Generate Chinese/Japanese speech with `stepaudio-2.5-tts` and transcribe long audio with `stepaudio-2.5-asr` (SSE endpoint, 32K context, ~100x RTF, up to 30-minute single call). Encapsulates the three non-obvious StepAudio 2.5 pitfalls that cost hours: `voice_label` removal (replaced by `instruction` + inline `()` prosody), `/v1/audio/asr/sse` endpoint mismatch (returns misleading `model not supported` error otherwise), and stricter censorship rules. Bundled scripts: `tts_generate.py` (with `--batch `), `asr_transcribe.py`, `ab_compare.sh`. API key resolution: `$STEPFUN_API_KEY` → `${CLAUDE_PLUGIN_DATA}/config.json` fallback. Reference docs cover migration from `step-tts-2`, the censorship rewrite list, and the verified-on-2026-04-23 known-issues registry. + +### Changed +- Marketplace skill count: 49 → 51 +- Marketplace plugin entry count: 53 → 55 +- Marketplace version: 1.50.0 → 1.51.0 +- README.md, README.zh-CN.md: badges, descriptions, skill sections (#49 + #50), Use Cases entries, Documentation Quick Links, Requirements +- CLAUDE.md: overview count, marketplace plugin count, Available Skills list + +### Note +Plugin entries for these two skills were inadvertently committed in v1.50.0's path-rewrite operation (the entries existed as uncommitted draft modifications in `marketplace.json` and were carried along when that file was rewritten). v1.51.0 completes the registration that v1.50.0 left half-done by landing the skill directories themselves and synchronizing all documentation surfaces. + +## [1.50.0] - 2026-04-26 + +### Changed +- **Suite directory flattening**: Moved both suite directories from `suites//` to the repo root: `suites/daymade-docs/` → `daymade-docs/` and `suites/daymade-claude-code/` → `daymade-claude-code/`. The `suites/` intermediate directory has been removed. Plugin names, install commands, and skill invocations are unchanged for end users — only the on-disk layout and the `source` paths in `marketplace.json` (and doc links) were affected. `claude plugin update` will re-fetch from the new paths automatically. +- Updated all 15 `source` entries in `.claude-plugin/marketplace.json` from `./suites//...` to `.//...`. +- Updated documentation references in `CLAUDE.md`, `README.md`, `README.zh-CN.md`, `references/new-skill-guide.md`, `daymade-claude-code/marketplace-dev/SKILL.md`, and `daymade-claude-code/marketplace-dev/references/cache_and_source_patterns.md`. +- Fixed pre-existing double-prefix typo (`suites/daymade-claude-code/suites/daymade-claude-code/...`) in two README locations during the path rewrite. + +## [1.49.0] - 2026-04-19 + +### Added +- **slides-creator** v1.0.0: Narrative-first slide deck creation. Guides users through structured narrative design (ABCDEFG model), then delegates visual generation to baoyu-slide-deck. Focuses on what machines can't do — narrative co-design with humans. Six-phase workflow: source collection → narrative discussion → content structuring → prompt generation → image generation → post-processing with directory reorganization and speaker notes extraction. Triggers on "create slides", "make a presentation", "generate deck", "slide deck", "PPT", or when user needs to turn content into visual slides. + +### Changed +- Updated marketplace skills count from 48 to 49 +- Updated marketplace plugin entries from 52 to 53 +- Updated marketplace version from 1.48.0 to 1.49.0 +- Updated README.md badges, skill listings, use cases, and documentation quick links +- Updated README.zh-CN.md badges, skill listings, use cases, and documentation quick links +- Updated CLAUDE.md skill count (48 → 49), plugin entry count (52 → 53), and Available Skills list + +## [1.48.0] - 2026-04-19 + +### Added +- **daymade-claude-code** suite v1.0.0: Claude Code operations suite bundling 7 power-user skills (`claude-code-history-files-finder`, `continue-claude-work`, `claude-skills-troubleshooting`, `claude-md-progressive-disclosurer`, `statusline-generator`, `claude-export-txt-better`, `marketplace-dev`) under one shared namespace. One command gets the full Claude Code toolkit and invocations render as `daymade-claude-code:` instead of the redundant `:` form. + +### Changed +- **Canonical source migration**: The 7 Claude Code-related skills were physically moved from the repo root into `suites/daymade-claude-code//`, mirroring the `daymade-docs` suite pattern. Both the suite and the 7 individual single-skill plugins now install from the same canonical location, keeping plugin caches narrow (only the suite's own files, not the whole repo). Transparent to existing users: plugin names and invocation remain identical; `claude plugin update` fetches from the new path automatically. +- Patch bumps for the 7 migrated skills to reflect the manifest/source change: + - `claude-code-history-files-finder` 1.0.2 → 1.0.3 + - `continue-claude-work` 1.1.1 → 1.1.2 + - `claude-skills-troubleshooting` 1.0.0 → 1.0.1 + - `claude-md-progressive-disclosurer` 1.2.0 → 1.2.1 + - `statusline-generator` 1.0.0 → 1.0.1 + - `claude-export-txt-better` 1.0.0 → 1.0.1 + - `marketplace-dev` 1.2.0 → 1.2.1 (also simplified hook paths from `${CLAUDE_PLUGIN_ROOT}/marketplace-dev/hooks/...` to `${CLAUDE_PLUGIN_ROOT}/hooks/...` now that the cache root is the skill dir itself) +- Updated marketplace version from 1.47.0 to 1.48.0 +- Updated marketplace plugin entries from 51 to 52 +- README / README.zh-CN / CLAUDE.md / references/new-skill-guide.md: all doc links to these 7 skills now point to `suites/daymade-claude-code//` + +## [1.47.0] - 2026-04-12 + +### Added +- **wechat-article-scraper** v2.9.0: World-class WeChat article extraction with 6-level strategy routing (fast→adaptive→stable→reliable→zero_dep→jina_ai), OG metadata fallback, image-paragraph association, lazy loading handling, local image download, and Sogou search discovery. Supports Markdown/JSON/HTML/PDF export. Includes 15 unique/leading features surpassing all competitors. + +### Changed +- Updated marketplace skills count from 47 to 48 +- Updated marketplace version from 1.46.0 to 1.47.0 + +### Added +- **gangtise-copilot** v1.0.0: One-stop installer and companion for the full Gangtise (岗底斯投研) OpenAPI skill suite — 19 official skills covering data retrieval (OHLC 行情, 财务, 估值, 研报, 首席观点, 会议纪要, 调研纪要), research workflows (个股研究 L1-L4, 观点 PK 对抗性分析, 主题研究, 事件复盘, 公告摘要), and utility (股票池管理, 公开网页搜索). Distilled from a 5-round discovery session that reverse-engineered the complete Gangtise skill catalog — the Gangtise OBS bucket has LIST permission disabled, so the full 19-skill inventory is not discoverable from any public manifest. Ships with 4 preset install modes (full / workshop / minimal / custom), zero-config multi-agent distribution to Claude Code / OpenClaw / Codex via symlink from a single canonical install location, shared XDG credential file at `~/.config/gangtise/authorization.json` that rotates all 19 skills in one edit, and a read-only diagnostic script with scoped liveness checks (`auth` scope + `rag` scope). Ships: `scripts/install_gangtise.sh` (408 lines), `scripts/configure_auth.sh` (310 lines), `scripts/diagnose.sh` (320 lines), and 5 reference docs covering installation flow, credentials setup, the complete 19-skill registry with per-script capability matrix, known ecosystem traps (parallel product lines, bundle-only hidden skills, double-Bearer token bug, admin endpoint 1009 errors), and workshop best practices. Target use case: the 2026 Q2 investor Workshop series where students need to install a large skill suite quickly without reverse-engineering the catalog themselves. + +### Changed +- **Renamed**: `markdown-tools` → `doc-to-markdown` — clearer name for DOCX/PDF/PPTX → Markdown conversion +- **doc-to-markdown**: Added 8 DOCX post-processing fixes (grid tables, simple tables, CJK bold spacing, JSON pretty-print, image path flattening, pandoc attribute cleanup, code block detection, bracket fixes) +- **doc-to-markdown**: Added 31 unit tests (`test_convert.py`) +- **doc-to-markdown**: Added 5-tool benchmark report (`references/benchmark-2026-03-22.md`) +- **marketplace-dev** v1.0.0 → v1.1.0: Added evidence intake from Claude Code history, plugin boundary decision guidance, source/cache patterns for single-skill and suite plugins, source+skills resolution validation, and cache footprint testing based on real marketplace debugging sessions. +- **marketplace-dev** v1.1.0 → v1.2.0: Refined against Anthropic's official skill-authoring best practices. Extracted the inline Node.js resolution check and diff pipeline into `scripts/check_marketplace.sh` — a one-shot validator that runs JSON syntax → `claude plugin validate` → source+skills resolution → reverse sync (disk SKILL.md → manifest) in a single command. Moved the two PostToolUse hook scripts from `scripts/` to `hooks/` for semantic clarity (scripts execute during skill workflow, hooks guard the editor) and updated the plugin manifest's hook paths accordingly. Added tables of contents to `anti_patterns.md` and `cache_and_source_patterns.md` (both >100 lines, per best practices). Corrected Phase 0 subagent history-mining paths to `/subagents/agent-*.jsonl`. Documented the auto-activated hook behaviour in a new "Bundled hooks" section. + +## [1.46.0] - 2026-04-11 + +### Added +- **claude-export-txt-better** v1.0.0: Fixes broken line wrapping in Claude Code exported `.txt` conversation files. Reconstructs tables, paragraphs, paths, and tool calls that were hard-wrapped at fixed column widths. Ships with an automated validation suite of 53 generic, file-agnostic checks. Triggers on export files with broken formatting or when the user mentions "fix export" / "fix conversation" / references a `YYYY-MM-DD-HHMMSS-*.txt` file. Bundled: `scripts/fix-claude-export.py`, `scripts/validate-claude-export-fix.py`, `evals/`. +- **douban-skill** v1.0.0: Exports and syncs Douban (豆瓣) book / movie / music / game collections to local CSV files via the reverse-engineered Frodo API. Supports full export and RSS incremental sync. No login, no cookies, no browser. Pre-flight user-ID validation and CSV output with UTF-8 BOM (Excel-compatible). Ships with a complete troubleshooting log of 7 tested scraping approaches and why each failed. Bundled: `scripts/douban-frodo-export.py`, `scripts/douban-rss-sync.py`, `references/troubleshooting.md`, `.gitleaks.toml` (allowlisting the public APK credentials). +- **terraform-skill** v1.0.0: Operational traps for Terraform provisioners, multi-environment isolation, and zero-to-deployment reliability. Every failure pattern documented caused a real incident. Covers provisioner timing races, SSH connection conflicts, DNS record duplication, volume permissions, database bootstrap gaps, snapshot cross-contamination, Cloudflare credential format errors, hardcoded domains in Caddyfiles/compose, and init-data-only-on-first-boot pitfalls. Organised as *exact error → root cause → copy-paste fix*. Bundled: `references/` with detailed remediation patterns. + +### Changed +- Updated marketplace skills count from 44 to 47 +- Updated marketplace version from 1.45.1 to 1.46.0 +- Updated marketplace plugin entries from 47 to 50 +- Updated README.md badges and skill listings (English and Chinese) +- Updated CLAUDE.md skill count (44 → 47) and plugin entry count (47 → 50) + +## [1.45.1] - 2026-04-11 + +### Fixed +- **daymade-docs** v1.0.0 → v1.0.1: Narrowed the suite plugin source to `suites/daymade-docs/` so the installed cache contains only the documentation skills in the suite instead of a full repository snapshot. +- Moved the daymade-docs member skills under `suites/daymade-docs/` as their canonical source and repointed the corresponding single-skill plugin entries to those same directories. +- **doc-to-markdown** v2.1.0 → v2.1.1, **mermaid-tools** v1.0.1 → v1.0.2, **ppt-creator** v1.0.0 → v1.0.1, **pdf-creator** v1.3.1 → v1.3.2, **docs-cleaner** v1.0.0 → v1.0.1, and **meeting-minutes-taker** v1.1.0 → v1.1.1 now install from their suite canonical source paths. + +### Changed +- Updated marketplace version from 1.45.0 to 1.45.1 + +## [1.45.0] - 2026-04-11 + +### Added +- **daymade-docs** v1.0.0: Documentation suite plugin that exposes `doc-to-markdown`, `mermaid-tools`, `pdf-creator`, `ppt-creator`, `docs-cleaner`, and `meeting-minutes-taker` under one namespace. This keeps the existing single-skill plugins available while providing `/daymade-docs:` slash commands for users who want a combined documentation workflow install. + +### Changed +- Updated marketplace version from 1.44.0 to 1.45.0 +- Updated README.md, README.zh-CN.md, and CLAUDE.md to document suite plugin architecture while preserving the existing single-skill plugin model. + +## [1.44.0] - 2026-04-11 + +### Added +- **skill-creator** v1.7.1 → v1.7.2: Completeness pass for the `workflows/wrapper-skill/` methodology within its scope (zip-archive skill packages distributed via `npx skills add`). A fifth adversarial agent review audited the wrapper-skill workflow docs against the canonical `ima-copilot` implementation and surfaced 13 on-scope lessons that were implicit in the reference code but not elevated to named patterns in the workflow. This release lands all 13. + - `patterns.md` install template: replaced the `` placeholder with a concrete defensive block covering `curl --fail` with HTTP-code branching, `wc -c` download-size sanity check rejecting suspiciously small archives before extraction, Node.js ≥18 numeric check (separate from `command -v node`), and a documented zero-agents-detected fallback policy (abort vs silent-skip vs default-to-claude-code, with the session's chosen answer named). Every defensive pattern has an accompanying "Lessons baked into this template" bullet explaining *why* it's there. + - `patterns.md` known_issues template: added `**Why upstream probably hasn't fixed it**` as a required field (the field that keeps repair blocks load-bearing across upstream upgrades), added `Strategy skip` as a first-class documented third option (users on tolerant platforms may legitimately not want the repair and naming the skip path explicit prevents the "did I forget?" failure mode), and added detailed notes on the `[ -f ... ] && \` guard rationale, `sed -i.bak ... && command rm -f *.bak` BSD/GNU portability dance, and backup directory naming convention. + - `patterns.md` diagnose template: added a new "Detection function return-code contract" subsection spelling out the required return codes for every post-repair state (untouched-good, untouched-broken, not-present, each Strategy-applied state, and the dual-state conflicted code). The dual-state code is the single hardest lesson from the ima-copilot session — a detection function that doesn't recognize it silently passes conflicted installs as healthy. + - `patterns.md` diagnose template: added variadic `find_install` rationale explaining that agents whose home-directory layout has not stabilized (like OpenClaw) should be probed against an ordered list of candidate paths, and that designing the helper as variadic from day one avoids a painful refactor when a second candidate path becomes necessary. + - `patterns.md` SKILL.md template: added explicit checklist for the description field (literal error strings from the session, tool name in every language the session used, self-disambiguation clause naming the upstream package to prevent wrapper-vs-upstream trigger fighting, symptoms that triggered the original session), plus a reference to the enforced 1024-character cap in `quick_validate.py:184`. Added "when in doubt → diagnose" as a recommended routing table default since diagnose is the only read-only entry point. + - `patterns.md` credentials section: added explicit guidance that liveness checks must match on **response-body shape**, not just HTTP status. Many APIs return 200 OK with an error JSON body, and a naive `curl --fail` check will pass a credential that fails the first real operation. + - `workflow.md` Step 5: expanded the install-script bullet list with prerequisite-check discipline (curl/unzip/npx loop plus separate Node.js ≥18 parse), download integrity defense in depth (HTTP code branching + size sanity), and the zero-agents fallback policy. + - `workflow.md` Step 6: expanded the known_issues schema to include the `Why upstream probably hasn't fixed it` field and the `Strategy skip` branch, and documented the `sed -i.bak` cross-BSD/GNU portability rule alongside the existing `command cp/mv` guidance. + - `workflow.md` Step 7: replaced the "returns OK / TRIGGERED / N/A / post-fix-state" shorthand with an explicit enumeration of the return-code contract, and added the variadic `find_install` guidance for agents with unstabilized layouts. + +### Changed +- Updated marketplace version from 1.43.0 to 1.44.0 + +## [1.43.0] - 2026-04-11 + +### Fixed +- **ima-copilot** v1.0.0 → v1.0.1: Contract compliance and dogfood-driven fixes + - `SKILL.md`, `references/known_issues.md`, `references/installation_flow.md`: removed hardcoded references to upstream version `1.1.2`. Install script keeps the version as an overridable default which is explicitly allowed by the architecture contract. Fixes a principle 6 (independent evolution) violation that would have forced a skill version bump on every upstream release. + - `references/known_issues.md`: added `command` prefix to the `sed -i.bak` and `rm -f` commands in Strategy A repair block and to the `rm -f` command in Strategy A rollback, matching the contract's alias-safe requirement. Previously, a user shell with `alias rm='rm -i'` or `alias sed='sed -i'` would hang the repair on an interactive prompt. + - `scripts/install_ima_skill.sh`: added a Node.js ≥18 preflight check. The `npx skills add` distribution path needs a modern Node runtime and the failure message on old Node is opaque. + - `scripts/diagnose.sh`: `check_submodule` now recognizes and explicitly warns on the dual-state where both `SKILL.md` and `MODULE.md` exist simultaneously (can happen when a user switched repair strategies mid-session or restored a partial backup). Previously this reported clean while the install was in a conflicted state. + - `scripts/search_fanout.py`: `rank_groups` now sorts tied hit counts by KB name for deterministic byte-identical output. Previously the tie-break depended on `concurrent.futures.ThreadPoolExecutor.map` completion order, which varied with network timing. +- **skill-creator** v1.7.0 → v1.7.1: Wrapper-skill workflow hardening from counter-review findings + - `workflows/wrapper-skill/workflow.md` Step 2: added a "How to access the conversation" subsection with concrete guidance for three cases (same session / follow-up session / neither available) and an explicit "do not fabricate content" rule for the last case. Fresh agents were previously left to guess. + - `workflows/wrapper-skill/workflow.md` Step 1: added an "AskUserQuestion fallback" subsection explaining that the consent requirement is the explicit user choice, not the specific tool name, and showing a plain-text fallback pattern for harnesses without `AskUserQuestion`. + - `workflows/wrapper-skill/patterns.md`: added a new "Runtime-logic patterns shared across wrappers" section with three generalizable insights distilled from ima-copilot's `search_fanout.py` — **capability partitioning** (enumerate vs operate permission asymmetry with four-way result bucketing), **undocumented limit detection** (silent truncation heuristics for APIs that cap results without emitting pagination tokens), and **scoped liveness checks** (probe the lowest-privilege operation the skill actually performs, not the easiest API call). Each pattern includes example code, real-world examples across multiple APIs (GitHub, Slack, Notion, Google Drive), and a cross-reference to the ima-copilot implementation. + - `workflows/wrapper-skill/verification_protocol.md`: restructured into Track 1 (session cross-reference for literal transcriptions) and Track 2 (smoke test / unit test for runtime logic). The previous "verification is not dogfood" dogma was too strict — it correctly applied to Track 1 files but wrongly exempted Track 2 runtime code from end-to-end testing. Track 2 files like `search_fanout.py` now have an explicit mandatory-smoke-test rule. + +### Changed +- Updated marketplace version from 1.42.0 to 1.43.0 + +## [1.42.0] - 2026-04-11 + +### Added +- **skill-creator** v1.6.0 → v1.7.0: New `workflows/wrapper-skill/` specialized workflow for retrospectively distilling an install-and-debug session into a reusable companion skill for a third-party CLI tool + - `workflows/wrapper-skill/workflow.md` — the retrospective distillation workflow with Step 2 conversation mining at its core (install flow, credential setup, bugs encountered and resolved, design decisions made, noise to discard) + - `workflows/wrapper-skill/architecture_contract.md` — seven non-negotiable principles that every generated wrapper skill must follow (never vendor upstream, runtime repair over ship-time patches, explicit user consent for any upstream file modification, idempotent/reversible/alias-safe repair commands, teaching agents over humans, independent evolution from upstream, private preferences stay private) + - `workflows/wrapper-skill/patterns.md` — copy-pasteable templates for SKILL.md, install script, diagnose script, known_issues registry, and credential setup, each annotated with the lessons baked in and cross-referenced to the canonical ima-copilot implementation + - `workflows/wrapper-skill/verification_protocol.md` — post-generation verification focused on cross-referencing generated artifacts against the source conversation rather than re-running the full install (the install already ran in the source session) + - `workflows/wrapper-skill/scripts/init_wrapper_skill.py` — bootstrap scaffold that creates the wrapper skill directory layout with placeholder markers pointing back at specific steps in the workflow + - `SKILL.md` root entry now includes a "Specialized Workflow: Wrapper Skills for Third-Party CLI Tools" routing section between Capture Intent and Prior Art Research that redirects agents to the wrapper workflow when the signals apply + - Canonical reference implementation: [`ima-copilot`](./ima-copilot) — the Tencent IMA wrapper that was the first product of this methodology, distilled during a real session whose lessons (shell alias bypass, root SKILL.md detection, realpath-based symlink dedup, idempotent reversible repairs) were captured in the patterns and propagated into this workflow + +### Changed +- Updated marketplace version from 1.41.0 to 1.42.0 + +## [1.41.0] - 2026-04-11 + +### Added +- **New Skill**: ima-copilot v1.0.0 — One-stop companion and installer for the official Tencent IMA skill (ima.qq.com), with wrapper-layer architecture that never vendors upstream files + - Zero-config installation to Claude Code, Codex, and OpenClaw via `npx skills add` ([vercel-labs/skills](https://github.com/vercel-labs/skills)) with auto-detection of installed agents and default symlink mode, so that a repair or upgrade applied once propagates automatically to every agent that shares the canonical install + - XDG-style credential management at `~/.config/ima/{client_id, api_key}` with env-var fallback (`IMA_OPENAPI_CLIENTID` / `IMA_OPENAPI_APIKEY`) + - Bundled `scripts/diagnose.sh` for read-only health check covering install presence, credential liveness, and known upstream issues with structured `✅/⚠️/❌` report + - Bundled `scripts/install_ima_skill.sh` with version override via `--version` flag or `IMA_VERSION` env var + - Bundled `scripts/search_fanout.py` for client-side cross-knowledge-base search with priority-based KB boosting, skip-list filtering, 100-result silent-truncation detection, and permission-denied KB partitioning (typical for subscribed KBs) + - Detects and repairs ISSUE-001 (submodule SKILL.md files missing YAML frontmatter in upstream v1.1.2) with two user-selectable strategies: Strategy A (rename to `MODULE.md` and patch root references — respects upstream design intent) or Strategy B (prepend minimal frontmatter — smallest diff) + - All repair commands are idempotent, reversible (with automatic timestamped backups to `/tmp/ima-copilot-backups/`), and use `command cp`/`command mv` to bypass interactive shell aliases + - Personalization via `~/.config/ima/copilot.json` with `priority_kbs` and `skip_kbs` lists — template at `config-template/copilot.json.example` uses illustrative-only values so the skill ships with zero real KB names + - Comprehensive reference documentation in `references/` covering installation flow, API key setup, known issues (source of truth for repairs), and search best practices + - Never vendors, forks, or mirrors upstream files — every repair is a runtime instruction executed with explicit user consent + +### Changed +- Updated marketplace skills/plugins count from 43 to 44 +- Updated marketplace version from 1.40.1 to 1.41.0 + +## [1.39.0] - 2026-03-18 + +### Added +- **New Skill**: scrapling-skill v1.0.0 - Reliable Scrapling CLI installation, troubleshooting, and extraction workflows for HTML, Markdown, and text output + - Bundled `diagnose_scrapling.py` script to verify CLI health, detect missing extras, inspect Playwright browser runtime, and run real smoke tests + - Static-first workflow for choosing between `extract get`, `extract fetch`, and `stealthy-fetch` + - Verified WeChat public article extraction pattern using `#js_content` + - Verified recovery path for local TLS trust-store failures via `--no-verify` + - Bundled troubleshooting reference covering extras, browser runtime, and output validation + +### Changed +- **skill-creator** v1.5.0 → v1.5.1: Fixed `scripts/package_skill.py` so it works when invoked directly from the repository root instead of only via `python -m` +- **continue-claude-work** v1.1.0 → v1.1.1: Replaced newer Python-only type syntax in `extract_resume_context.py` so the script runs under the local `python3` environment +- Updated marketplace skills/plugins count from 42 to 43 +- Updated marketplace version from 1.38.0 to 1.39.0 +- Updated marketplace metadata description to include Scrapling CLI extraction workflows +- Updated README.md and README.zh-CN.md badges, installation commands, skill listings, use cases, quick links, and requirements +- Updated CLAUDE.md counts, version reference, and Available Skills list (added #43) + +## [1.38.0] - 2026-03-07 + +### Added +- **New Skill**: continue-claude-work v1.1.0 - Recover local `.claude` session context and continue interrupted work without `claude --resume` + - Bundled Python script (`extract_resume_context.py`) for one-call context extraction + - Compact-boundary-aware extraction using `isCompactSummary` flag (highest-signal context from session compaction summaries) + - Subagent workflow recovery — parses `subagents/` directory to report completed vs interrupted agents with last outputs + - Session end reason detection — classifies clean exit, interrupted (ctrl-c), error cascade, or abandoned + - Size-adaptive reading strategy based on file size and compaction count + - Noise filtering — skips progress/queue-operation/api_error (37-53% of session lines) + - Self-session exclusion, stale index fallback, ghost session warnings + - MEMORY.md and session-memory integration, git workspace state fusion + +### Changed +- **skill-creator** v1.4.1 → v1.5.0: SKILL.md rewrite, added eval benchmarking system (run_eval, run_loop, aggregate_benchmark), agents (analyzer, comparator, grader), eval-viewer, and improve_description script +- **transcript-fixer** v1.1.0 → v1.2.0: `--domain` defaults to all domains, added `get_domain_stats()`, cross-domain listing, and zero-match hints +- **tunnel-doctor** v1.3.0 → v1.4.0: Added Step 2C-1 for local vanity domain proxy interception, bundled `quick_diagnose.py` automated diagnostic script +- **pdf-creator** v1.0.0 → v1.1.0: Replaced Python `markdown` library with pandoc for MD→HTML conversion, removed `_ensure_list_spacing` workaround +- **github-contributor** v1.0.2 → v1.0.3: Fixed gh CLI field name (`stargazersCount` → `stargazerCount`), added Prerequisites section +- Updated marketplace skills/plugins count from 41 to 42 +- Updated marketplace version from 1.37.0 to 1.38.0 +- Updated README.md and README.zh-CN.md badges, installation commands, skill listings, use cases, quick links, and requirements +- Updated CLAUDE.md counts, version reference, and Available Skills list (added #42) ## [1.37.0] - 2026-03-02 diff --git a/CLAUDE.md b/CLAUDE.md index 93c52c7f..a412c65c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co ## Repository Overview -This is a Claude Code skills marketplace containing 41 production-ready skills organized in a plugin marketplace structure. Each skill is a self-contained package that extends Claude's capabilities with specialized knowledge, workflows, and bundled resources. +This is a Claude Code skills marketplace containing 64 production-ready skills organized in a plugin marketplace structure. Most plugins expose one skill for narrow installs; suite plugins expose related skills under shared namespaces for combined installation workflows. **Essential Skill**: `skill-creator` is the most important skill in this marketplace - it's a meta-skill that enables users to create their own skills. Always recommend it first for users interested in extending Claude Code. @@ -61,13 +61,13 @@ claude plugin install skill-creator@daymade-skills ```bash # Quick validation of a skill -skill-creator/scripts/quick_validate.py /path/to/skill +cd daymade-skill/skill-creator && uv run --with PyYAML python -m scripts.quick_validate ../skill-name # Package a skill (includes automatic validation) -skill-creator/scripts/package_skill.py /path/to/skill [output-dir] +cd daymade-skill/skill-creator && uv run --with PyYAML python -m scripts.package_skill ../skill-name [output-dir] # Initialize a new skill from template -skill-creator/scripts/init_skill.py --path +uv run python daymade-skill/skill-creator/scripts/init_skill.py --path ``` ### Testing Skills Locally @@ -89,10 +89,13 @@ In Claude Code, use `/plugin ...` slash commands. In your terminal, use `claude ### Git Operations -This repository uses standard git workflow: +This repository uses standard git workflow, but **always stage files by name**, +never `git add -A` / `git add .`. Multiple agents may have unstaged changes in +the same worktree — a blanket stage piggybacks their work into your commit: + ```bash git status -git add . +git add path/to/file1 path/to/file2 # specific files only git commit -m "message" git push ``` @@ -115,13 +118,29 @@ description: Clear description with activation triggers. This skill should be us --- ``` -### Privacy and Path Guidelines +### Privacy and Path Guidelines (Enforced by Pre-commit Hook) Skills for public distribution must NOT contain: - Absolute paths to user directories (`/home/username/`, `/Users/username/`) - Personal usernames, company names, product names +- Phone numbers, personal email addresses - OneDrive paths or environment-specific absolute paths -- Use relative paths within skill bundle or standard placeholders +- Use relative paths within skill bundle or standard placeholders (`/`, ``) + +**Five-layer defense system:** +1. **CLAUDE.md rules** (this section) — Claude avoids generating sensitive content +2. **Global PII Guard pre-commit hook** (`~/scripts/git-pii-guard/pre-commit`) — blocks staged PII/secrets and generated/local artifact paths +3. **Global PII Guard pre-push hook** (`~/scripts/git-pii-guard/pre-push`) — scans commits about to be pushed, catching bad local history before it hits GitHub +4. **gitleaks** (`.gitleaks.toml`) — deep scan with custom rules for this repo +5. **AI semantic read-through** (the gate the other four structurally cannot be) — layers 1-4 are keyword/regex/gitleaks: they only match patterns someone listed, and are blind to private content with **no keyword** — a real name in another language (gitleaks doesn't cover CJK), a verbatim line from a real transcript, a real example dropped into an illustration. Before publishing, **read the whole skill yourself and judge each concrete name/example/snippet semantically** ("generic placeholder / public entity, or lifted from a real project / person / transcript?"). A green scan is **not** a clean bill of health; "grep found nothing" only means your word list didn't fire. Method: [`daymade-skill/skill-creator/references/sanitization_checklist.md`](./daymade-skill/skill-creator/references/sanitization_checklist.md). + +PII Guard is enabled via `~/scripts/git-pii-guard/manage.sh enable `, which sets `core.hooksPath` to `~/scripts/git-pii-guard`. +For repo-specific additions: +- `.pii-patterns` — extra content regexes +- `.pii-path-patterns` — extra forbidden path regexes +- `.pii-allowpaths` — explicit path allowlist exceptions +- `.pre-commit-config.yaml` — optional repo-local runner that wires `pre-commit` framework to the same path/content rules for contributors who prefer managed hooks +If it fires, fix the issue — do NOT use `--no-verify` to bypass. ### Content Organization @@ -134,9 +153,11 @@ Skills for public distribution must NOT contain: ## Marketplace Configuration The marketplace is configured in `.claude-plugin/marketplace.json`: - - Contains 41 plugins, each mapping to one skill -- Each plugin has: name, description, version, category, keywords, skills array -- Marketplace metadata: name, owner, version, homepage +- Contains 45 plugin entries: single-skill plugins point `source` directly at the skill directory (no `skills` field); suite plugins (`daymade-audio`, `daymade-claude-code`, `daymade-docs`, `daymade-skill`) use explicit `skills` arrays for multi-skill routing +- Each plugin has: name, description, source, version, category, keywords +- Marketplace metadata: name, owner, version +- Single-skill plugins follow the official pattern (167/168 plugins in `anthropics/claude-plugins-official`): `source` points to skill directory, `skills` omitted +- **All 4 suites are suite-only.** `daymade-audio`, `daymade-claude-code`, `daymade-docs`, and `daymade-skill` do NOT register their member skills as standalone plugins. Users install the suite (e.g., `daymade-audio@daymade-skills`) and invoke skills as `:` (e.g., `daymade-audio:transcript-fixer`, `daymade-claude-code:statusline-generator`). When adding a new skill that belongs to a suite, only update the suite entry's `skills` array — do NOT create a parallel standalone plugin entry. ### Versioning Architecture @@ -144,8 +165,7 @@ The marketplace is configured in `.claude-plugin/marketplace.json`: 1. **Marketplace Version** (`.claude-plugin/marketplace.json` → `metadata.version`) - Tracks the marketplace catalog as a whole - - Current: v1.37.0 - - Bump when: Adding/removing skills, major marketplace restructuring + - Bump when: Adding/removing skills, adding/removing suite plugins, major marketplace restructuring - Semantic versioning: MAJOR.MINOR.PATCH 2. **Individual Skill Versions** (`.claude-plugin/marketplace.json` → `plugins[].version`) @@ -179,7 +199,7 @@ This applies when you change ANY file under a skill directory: 1. **skill-creator** ⭐ - **Essential meta-skill** for creating your own skills (with init/validate/package scripts) 2. **github-ops** - GitHub operations via gh CLI and API -3. **markdown-tools** - Document conversion with WSL path handling +3. **doc-to-markdown** - DOCX/PDF/PPTX → Markdown conversion with CJK post-processing 4. **mermaid-tools** - Diagram extraction and PNG generation 5. **statusline-generator** - Claude Code statusline customization 6. **teams-channel-post-writer** - Teams communication templates @@ -212,27 +232,41 @@ This applies when you change ANY file under a skill directory: 33. **meeting-minutes-taker** - Transform meeting transcripts into structured minutes with multi-pass generation, speaker quotes, and iterative human review 34. **deep-research** - Generate format-controlled research reports with evidence mapping, citations, and multi-pass synthesis 35. **competitors-analysis** - Evidence-based competitor tracking and analysis with source citations (file:line_number format) - 36. **tunnel-doctor** - Diagnose and fix Tailscale + proxy/VPN conflicts (four layers: route, HTTP env, system proxy, SSH ProxyCommand) on macOS with WSL SSH support - 37. **windows-remote-desktop-connection-doctor** - Diagnose AVD/W365 connection quality issues with transport protocol analysis and Windows App log parsing - 38. **product-analysis** - Perform structured product audits across UX, API, architecture, and compare mode to produce prioritized optimization recommendations - 39. **financial-data-collector** - Collect real financial data for US public companies via yfinance with validation, NaN detection, and NO FALLBACK principle - 40. **excel-automation** - Create formatted Excel files, parse complex xlsm models, and control Excel windows on macOS via AppleScript - 41. **capture-screen** - Programmatically capture macOS application windows using Swift window ID discovery and screencapture workflows +36. **tunnel-doctor** - Diagnose and fix Tailscale + proxy/VPN conflicts (six layers: route, HTTP env, system proxy, SSH ProxyCommand, VM/container proxy, DNS resolver stall) on macOS with WSL SSH support, plus a TUN measurement-contamination guide (raw probes lie under a global proxy) +37. **windows-remote-desktop-connection-doctor** - Diagnose AVD/W365 connection quality issues with transport protocol analysis and Windows App log parsing +38. **product-analysis** - Perform structured product audits across UX, API, architecture, and compare mode to produce prioritized optimization recommendations +39. **financial-data-collector** - Collect real financial data for US public companies via yfinance with validation, NaN detection, and NO FALLBACK principle +40. **excel-automation** - Create formatted Excel files, parse complex xlsm models, and control Excel windows on macOS via AppleScript +41. **capture-screen** - Programmatically capture macOS application windows using Swift window ID discovery and screencapture workflows +42. **continue-claude-work** - Recover local `.claude` session context via compact-boundary extraction, subagent workflow recovery, and session end reason detection, then continue interrupted work without `claude --resume` +43. **scrapling-skill** - Install, troubleshoot, and use Scrapling CLI for static/dynamic web extraction, WeChat article capture, and verified output validation +44. **ima-copilot** - One-stop companion and installer for the official Tencent IMA skill with zero-config three-agent installation via vercel-labs/skills, XDG credential management, read-only diagnostic, known-issue auto-repair under user consent, and personalized fan-out search with priority-based knowledge base boosting +45. **claude-export-txt-better** - Fixes broken line wrapping in Claude Code exported `.txt` conversation files; reconstructs tables, paragraphs, paths, and tool calls hard-wrapped at fixed column widths; ships with a 53-check automated validation suite +46. **douban-skill** - Exports and syncs Douban (豆瓣) book/movie/music/game collections to local CSV files via the reverse-engineered Frodo API; supports full export and RSS incremental sync with no login, cookies, or browser required +47. **marketplace-dev** - Converts any Claude Code skills repository into an official plugin marketplace — generates spec-conforming marketplace.json, validates with `claude plugin validate`, tests real installation, and opens an upstream PR +48. **terraform-skill** - Operational traps for Terraform provisioners, multi-environment isolation, and zero-to-deployment reliability; covers provisioner timing races, SSH connection conflicts, DNS record duplication, volume permissions, database bootstrap gaps, Cloudflare credential errors, and init-data-only-on-first-boot pitfalls +49. **slides-creator** - Narrative-first slide deck creation guiding users through structured narrative design (ABCDEFG model), then delegating visual generation to baoyu-slide-deck. Triggers on create slides, make a presentation, generate deck, slide deck, PPT, or when user needs to turn content into visual slides +50. **debugging-network-issues** - Evidence-driven, falsification-first methodology for network/streaming/protocol-layer bugs (HTTP/2 RST_STREAM, SSE stalls, fixed-time drops, CDN/proxy/CGNAT idle timeouts). Layered isolation experiments + counter-review filter + a cognitive-traps catalog (incl. reverse-path/directional asymmetry), with bundled probe scripts and a real SSE 130s case study +51. **stepfun-tts** - StepFun stepaudio-2.5-tts (Contextual TTS): natural-language `instruction` (≤200 chars) + inline `()` parentheses for句内 prosody. Captures the two TTS-side breaking changes from step-tts-2 (voice_label removal + stricter 2.5-era censorship) with migration playbook +52. **stepfun-asr** - StepFun stepaudio-2.5-asr (SSE endpoint, 32K context, ~85-101× RTF, 30-min single-call). Hides the #1 trap of the 2.5 ASR family: it does NOT live on `/v1/audio/transcriptions` — the wrong endpoint returns a misleading `model not supported` error. Bundled stdlib CLI handles base64 + nested JSON body + SSE parsing including `error` events +53. **feishu-doc-scraper** - Save Feishu Docs and Feishu Wiki pages as clean Markdown from a live authenticated browser session. Primary path: injectable JS script (`feishu_dom_capture.js`) for TOC-driven DOM capture, image download via session cookie, noise stripping, and clipboard bridge transport. Fallback path: Python SSR extraction (`browser_cookie3` + `requests`) when browser automation is unavailable. Enforces per-document image naming and recovers `[图片: Feishu Docs - Image]` placeholders. Works with both Feishu (feishu.cn) and Lark (larkoffice.com) +54. **auto-repo-setup** - Automated repository environment configuration, fault diagnosis, and repair for non-technical users. Reads ONBOARDING.md, audits environment gaps (git, ffmpeg, uv, Python, API keys), installs missing dependencies, validates with smoke tests, and safely handles git operations with PII Guard and Push Safety. Includes SessionStart hook initialization, counter-review workflows, and git history sanitization. +55. **asr-transcribe-to-text** - Transcribes audio and video files to text using Qwen3-ASR — local MLX inference on Apple Silicon (no API key, 15-27x realtime) or remote vLLM/OpenAI-compatible API, with automatic platform detection +56. **bigdata-skill** - Pull Bigdata.com (RavenPack) financial and news data via the official `bigdata-client` SDK and `/v1/*` REST endpoints — structured financials, prices, analyst estimates, a daily entity-sentiment series, annotated chunk search, and a screener +57. **gangtise-copilot** - Gangtise investment-research OpenAPI skill suite installer and diagnostic tool +58. **llm-wiki-setup** - Co-create a personal investment-research LLM Wiki (Karpathy's pattern) where the user's own analysis framework becomes a living CLAUDE.md, built by interviewing them rather than handing over a template +59. **benchmark-due-diligence** - Runs adversarial due-diligence on a benchmark the user envies (a founder, KOL, company, or product whose claimed success looks inflated), separating marketing bubble from real signal and mapping the validated playbook onto the user's own situation +60. **pdf-to-html** - Converts a PDF into one self-contained, readable HTML file preserving images, tables, charts, and reading order, optionally translating it into another language while keeping every figure +61. **terminal-screenshot** - Render a terminal CLI program's colored output to a PNG so Claude can see the real visual result (color contrast, alignment, background blocks) instead of raw ANSI codes — for verifying delta/bat/starship/lazygit color config +62. **bilibili-source** - Fetch login-free, citable data for a Bilibili (B站) video — stats, UP fans, tags, per-part cids, and full danmaku text — via one view/detail call (accepts BVID/av/b23.tv/URL); login-gated subtitles; ships a self-test for API-drift detection +63. **claude-usage-analyst** - Explain local Claude Code / Claude Desktop token usage, cost, quota burn, model mix, and cache pressure from `ccusage` data — separating observed numbers from interpretation in plain language (daymade-claude-code suite member) +64. **marketplace-health-check** - Run a full 6-dimension health check of this skills marketplace repo (code/script safety, doc/SSOT consistency, security/PII, open-PR triage, open-issue triage, marketplace integrity) via a parallel fan-out Dynamic Workflow, then Counter-Review the serious findings and report by priority **Recommendation**: Always suggest `skill-creator` first for users interested in creating skills or extending Claude Code. ## YouTube Downloader SOP (Internal) -Use this SOP to avoid common yt-dlp failures and confusion: - -1. Quote YouTube URLs in shell commands (zsh treats `?` as glob). Example: `'https://www.youtube.com/watch?v=VIDEO_ID'`. -2. Ensure proxy is active for both yt-dlp and PO Token providers (HTTP_PROXY/HTTPS_PROXY/ALL_PROXY). -3. If you see “Sign in to confirm you’re not a bot”, request cookie permission and use browser cookies. -4. Start the PO Token provider before downloading. Prefer Docker bgutil; fall back to browser-based WPC when Docker is unavailable or fails. -5. Use `web_safari` client when cookies are present; otherwise use `mweb` for PO tokens. -6. Keep the browser window open while WPC is minting tokens and make sure it can reach YouTube through the same proxy. -7. If you see “Only images are available” or “Requested format is not available”, treat it as PO token failure and retry after fixing provider/browser state. -8. If you see SSL EOF or fragment errors, treat it as proxy instability. Retry with progressive formats or switch to a more stable proxy. +See [youtube-downloader/references/internal-sop.md](./youtube-downloader/references/internal-sop.md) for yt-dlp troubleshooting steps (PO tokens, proxy, cookies, etc.). ## Python Development @@ -266,326 +300,52 @@ When creating a new skill: ## Adding a New Skill to Marketplace -**CRITICAL**: When adding a skill to this marketplace, you MUST update all of these files in the correct order. Missing any file will result in incomplete integration. - -### Step-by-Step Process - -#### 1. Refine the Skill (if needed) -```bash -# Ensure skill follows best practices -# - SKILL.md uses imperative/infinitive form -# - Third-person description in YAML frontmatter -# - Progressive disclosure (details in references/) -# - Security scan passed - -cd skill-creator -python3 scripts/security_scan.py ../skill-name --verbose -``` - -#### 2. Package the Skill -```bash -cd skill-creator -python3 scripts/package_skill.py ../skill-name - -# This will: -# - Validate skill structure -# - Check security scan status -# - Create skill-name.zip in skill-creator/ -# - Move zip to skill-name/ directory -``` - -#### 3. Update CHANGELOG.md ⚠️ REQUIRED - -Add new version entry at the top (after [Unreleased]): - -```markdown -## [X.Y.0] - YYYY-MM-DD - -### Added -- **New Skill**: skill-name - Brief description - - Feature 1 - - Feature 2 - - Feature 3 - - Bundled scripts/references/assets - - Key capabilities - -### Changed -- Updated marketplace skills count from N to N+1 -- Updated marketplace version from X.(Y-1).0 to X.Y.0 -- Updated README.md badges (skills count, version) -- Updated README.md to include skill-name in skills listing -- Updated README.zh-CN.md badges (skills count, version) -- Updated README.zh-CN.md to include skill-name in skills listing -- Updated CLAUDE.md skills count from N to N+1 -- Added skill-name use case section to README.md -- Added skill-name use case section to README.zh-CN.md -- Added dependencies to requirements section (if any, both EN and ZH) -``` - -**Version numbering**: Increment MINOR version (e.g., 1.8.0 → 1.9.0) when adding a skill. - -#### 4. Update README.md ⚠️ REQUIRED - -**a. Update badges (top of file):** -```markdown -[![Skills](https://img.shields.io/badge/skills-N-blue.svg)] -[![Version](https://img.shields.io/badge/version-X.Y.0-green.svg)] -``` - -**b. Update description:** -```markdown -Professional Claude Code skills marketplace featuring N production-ready skills... -``` - -**c. Add installation command:** -```markdown -# Brief description -claude plugin install skill-name@daymade-skills -``` - -**d. Add skill section (### N. **skill-name**):** -```markdown -### N. **skill-name** - One-line Title - -Brief description paragraph. - -**When to use:** -- Use case 1 -- Use case 2 -- Use case 3 - -**Key features:** -- Feature 1 -- Feature 2 -- Feature 3 - -**Example usage:** -\`\`\`bash -# Example commands -\`\`\` - -**🎬 Live Demo** - -*Coming soon* (or add demo GIF) - -📚 **Documentation**: See [skill-name/references/](./skill-name/references/)... - -**Requirements**: Dependencies (e.g., Python 3.8+, FFmpeg, etc.) -``` - -**e. Add use case section:** -```markdown -### For [Use Case Category] -Use **skill-name** to [describe primary use case]. Combine with **other-skill** to [describe integration]. -``` - -**f. Add documentation quick link:** -```markdown -- **skill-name**: See `skill-name/references/...` for ... -``` - -**g. Update requirements section (if needed):** -```markdown -- **Tool Name** (for skill-name): `install command` -``` - -#### 5. Update CLAUDE.md ⚠️ REQUIRED - -**a. Update repository overview:** -```markdown -This is a Claude Code skills marketplace containing N production-ready skills... -``` - -**b. Update marketplace configuration:** -```markdown -The marketplace is configured in `.claude-plugin/marketplace.json`: -- Contains N plugins, each mapping to one skill -``` - -**c. Update marketplace version:** -```markdown -1. **Marketplace Version** (`.claude-plugin/marketplace.json` → `metadata.version`) - - Tracks the marketplace catalog as a whole - - Current: vX.Y.0 -``` - -**d. Add skill to Available Skills list:** -```markdown -N. **skill-name** - Brief description with key feature -``` - -#### 6. Update .claude-plugin/marketplace.json ⚠️ CRITICAL - -**MOST IMPORTANT FILE** - This file makes the skill installable! - -**a. Update metadata.description:** -```json -"description": "Professional Claude Code skills for ..., and [new skill capability]" -``` - -**b. Update metadata.version:** -```json -"version": "X.Y.0" -``` - -**c. Add new plugin entry to plugins array:** -```json -{ - "name": "skill-name", - "description": "Clear description with trigger conditions. Use when [scenarios]", - "source": "./", - "strict": false, - "version": "1.0.0", - "category": "appropriate-category", - "keywords": ["keyword1", "keyword2", "keyword3", ...], - "skills": ["./skill-name"] -} -``` - -**Categories:** `developer-tools`, `document-conversion`, `documentation`, `customization`, `communication`, `utilities`, `assets`, `design`, `productivity`, `security`, `media` - -**d. Validate JSON syntax:** -```bash -python3 -m json.tool .claude-plugin/marketplace.json > /dev/null -``` - -#### 7. Update README.zh-CN.md ⚠️ REQUIRED - -**CRITICAL**: Chinese documentation must be kept in sync with English version. - -**a. Update badges (top of file):** -```markdown -[![Skills](https://img.shields.io/badge/skills-N-blue.svg)] -[![Version](https://img.shields.io/badge/version-X.Y.0-green.svg)] -``` - -**b. Update description:** -```markdown -专业的 Claude Code 技能市场，提供 N 个生产就绪的技能，用于增强开发工作流。 -``` - -**c. Add installation command:** -```markdown -# 简短描述 -claude plugin install skill-name@daymade-skills -``` - -**d. Add skill section (### N. **skill-name** - Chinese Title):** -- Translate all content from English README -- Include: 使用场景 (When to use), 主要功能 (Key features), 示例用法 (Example usage) -- Maintain same structure as English version -- Include documentation links and requirements - -**e. Add use case section:** -```markdown -### [Use Case Category in Chinese] -使用 **skill-name** [describe use case in Chinese]. 与 **other-skill** 结合使用以 [describe integration]. -``` - -**f. Add documentation quick link:** -```markdown -- **skill-name**：参见 `skill-name/references/...` 了解 ... -``` - -**g. Update requirements section (if needed):** -```markdown -- **Tool Name**（用于 skill-name）：`install command` -``` - -**Translation tips:** -- Use professional technical Chinese -- Maintain consistency with existing translations -- Keep code examples in English (don't translate variable names, function names) -- Translate user-facing descriptions, features, and use cases - -#### 8. Verification Checklist - -Before committing, verify: - -- [ ] CHANGELOG.md has new version entry -- [ ] README.md badges updated (skills count + version) -- [ ] README.md has skill section with number -- [ ] README.md has use case section -- [ ] README.md has documentation link -- [ ] README.md requirements updated (if needed) -- [ ] README.zh-CN.md badges updated (skills count + version) ⚠️ NEW -- [ ] README.zh-CN.md has skill section with number ⚠️ NEW -- [ ] README.zh-CN.md has use case section ⚠️ NEW -- [ ] README.zh-CN.md has documentation link ⚠️ NEW -- [ ] README.zh-CN.md requirements updated (if needed) ⚠️ NEW -- [ ] README.zh-CN.md installation command added ⚠️ NEW -- [ ] CLAUDE.md skill count updated in 3 places -- [ ] CLAUDE.md has skill in Available Skills list -- [ ] marketplace.json metadata.version updated -- [ ] marketplace.json metadata.description updated -- [ ] marketplace.json has new plugin entry -- [ ] marketplace.json validates (python3 -m json.tool) -- [ ] skill-name.zip package exists -- [ ] Security scan passed - -### Common Mistakes to Avoid - -1. **Forgetting marketplace.json** ⚠️ - The most critical file! Without this, the skill cannot be installed via `claude plugin install` -2. **Forgetting Chinese documentation** ⚠️ - README.zh-CN.md must be updated in sync with README.md (6 locations) -3. **Inconsistent version numbers** - CHANGELOG, README badges (both EN and ZH), CLAUDE.md, and marketplace.json must all match -4. **Inconsistent skill counts** - README description (both EN and ZH), badges, CLAUDE.md must all have same count -5. **Missing skill number in README** - Skills must be numbered sequentially (1, 2, 3, ...) in both EN and ZH versions -6. **Invalid JSON syntax** - Always validate marketplace.json after editing -7. **Forgetting dependencies** - Update README requirements section (both EN and ZH) if skill needs external tools -8. **Incomplete Chinese translation** - Must translate all sections: description, use cases, features, use case section, docs link - -### File Update Summary Template - -When adding a skill, this is the complete file list: +For the full step-by-step guide with templates and examples, see [references/new-skill-guide.md](./references/new-skill-guide.md). + +**Files to update** (all required): + +| File | Locations to update | +|------|-------------------| +| `.claude-plugin/marketplace.json` | metadata.version + metadata.description + new plugin entry | +| `CHANGELOG.md` | New version entry | +| `README.md` | 7 locations: badges (skills-count badge AND version badge — version MUST equal `marketplace.json` metadata.version; it has drifted twice from a metadata bump that forgot the badge), description, install cmd, skill section, use case, docs link, requirements | +| `README.zh-CN.md` | 7 locations: same as above, translated | +| `CLAUDE.md` | 3 locations: overview count, marketplace config count, Available Skills list | +| `skill-name/` | The actual skill directory + packaged .zip | + +**Quick workflow**: +```bash +# 1. Validate & package the skill itself +cd daymade-skill/skill-creator +uv run python -m scripts.security_scan ../skill-name --verbose +uv run --with PyYAML python -m scripts.package_skill ../skill-name + +# 2. Update all files listed above (see references/new-skill-guide.md for the +# detailed step-by-step, including 7 README locations and 3 CLAUDE.md spots) + +# 3. One-shot marketplace validation (ships with marketplace-dev skill) +cd .. && bash daymade-claude-code/marketplace-dev/scripts/check_marketplace.sh +# Runs: JSON syntax → claude plugin validate → source+skills resolution → +# reverse sync (warns when a disk SKILL.md is not registered). A WARN on +# reverse sync is the canary for orphan skills — register them or delete them. +# Then verify the human-facing skill lists match the manifest (counts drift too): +python3 daymade-claude-code/marketplace-dev/scripts/check_doc_skill_lists.py +# Reports MISSING/GHOST per doc (CLAUDE.md / README.md / README.zh-CN.md vs the +# expanded marketplace.json); exits non-zero on drift. Must be green before push. + +# 4. Stage specific files by name, never `git add -A` or `git add .` +# (a parallel agent once piggybacked another session's unstaged changes +# into its commit via `git add -A`; the fix is to stage explicitly) +git add .claude-plugin/marketplace.json CHANGELOG.md README.md README.zh-CN.md \ + CLAUDE.md skill-name/ +git commit -m "Release vX.Y.0: Add skill-name" +git push +# 5. Release +gh release create vX.Y.0 --title "Release vX.Y.0: Add skill-name" --notes "..." ``` -Files to Update: -✅ CHANGELOG.md (Add version entry) -✅ README.md (7 locations: badges, description, install, skill section, use case, docs link, requirements) -✅ README.zh-CN.md (7 locations: badges, description, install, skill section, use case, docs link, requirements) ⚠️ CRITICAL -✅ CLAUDE.md (3 locations: overview, marketplace config, available skills) -✅ .claude-plugin/marketplace.json (CRITICAL: metadata + new plugin entry) -✅ skill-name/ (The actual skill directory) -✅ skill-name/skill-name.zip (Packaged skill) -``` - -**IMPORTANT**: README.zh-CN.md is MANDATORY. Do not skip Chinese documentation updates! - -### Version Numbering Convention - -- **MAJOR.MINOR.PATCH** (Semantic Versioning) -- Increment **MINOR** when adding a new skill: 1.8.0 → 1.9.0 -- Increment **PATCH** for bug fixes or small updates: 1.9.0 → 1.9.1 -- Increment **MAJOR** for breaking changes or major restructuring: 1.9.0 → 2.0.0 - -### Quick Reference Commands - -```bash -# 1. Refine and validate skill -cd skill-creator -python3 scripts/security_scan.py ../skill-name --verbose - -# 2. Package skill -python3 scripts/package_skill.py ../skill-name - -# 3. Validate marketplace.json -cd .. -python3 -m json.tool .claude-plugin/marketplace.json > /dev/null && echo "✅ Valid" - -# 4. Check what needs committing -git status - -# 5. View specific file changes -git diff CHANGELOG.md -git diff README.md -git diff README.zh-CN.md -git diff CLAUDE.md -git diff .claude-plugin/marketplace.json -# 6. Verify Chinese documentation is in sync -grep "skills-[0-9]*" README.md README.zh-CN.md -grep "version-[0-9.]*" README.md README.zh-CN.md -``` +**Top mistakes**: Forgetting to push to GitHub, forgetting README.zh-CN.md, inconsistent version numbers across files, leaving an orphan SKILL.md on disk unregistered (caught by `check_marketplace.sh` reverse sync), using `git add -A` in a repo where multiple agents may have unstaged changes. ## Chinese User Support @@ -599,950 +359,19 @@ See README.md section "🇨🇳 中文用户指南" for details. ## Handling Third-Party Marketplace Promotion Requests -This repository is a **personal curated marketplace**, NOT a community directory or ecosystem hub. All requests to add third-party marketplace links, skill collection references, or "Community Marketplaces" sections should be declined. - -### Policy - -**DO NOT accept:** -- PRs adding "Related Resources" or "Community Marketplaces" sections linking to third-party skill collections -- Issues requesting promotion of external marketplaces -- PRs adding links to other skill repositories in README.md - -**Rationale:** -1. **Scope creep**: Shifts repository purpose from curated skills to ecosystem directory -2. **Implicit endorsement**: Listing implies quality/security review we cannot maintain -3. **Maintenance burden**: Would need to track and vet external projects over time -4. **Precedent setting**: Accepting one creates obligation to accept others - -### Response Template - -When declining, use this approach: - -```markdown -Hi @{username}, - -Thank you for your interest and for sharing {project-name}! {Brief positive acknowledgment of their project}. - -However, I'm keeping this repository focused as a **personal curated marketplace** rather than a directory of external skill collections. Adding third-party references would: - -1. Shift the repository's scope from curated skills to ecosystem directory -2. Create implicit endorsement expectations I can't maintain -3. Set precedent for similar requests (reference other declined requests if applicable) - -**What you can do instead:** - -1. **Standalone marketplace** - Your repo already works as an independent marketplace: - ``` - /plugin marketplace add {owner}/{repo} - ``` - -2. **Community channels** - Promote through: - - Claude Code GitHub discussions/issues (Anthropic's official repo) - - Developer communities (Reddit, Discord, etc.) - - Your own blog/social media - -3. **Official registry** - If/when Anthropic launches an official skill registry, that would be the appropriate place for ecosystem-wide discovery. - -Your marketplace can succeed on its own merits. Good luck with {project-name}! -``` - -### Workflow - -1. **Review the request** - Confirm it's a third-party promotion (not a legitimate contribution) -2. **Add polite comment** - Use template above, customize for their specific project -3. **Close with reason** - Use "not planned" for issues, just close for PRs -4. **Reference precedent** - Link to previously declined requests for consistency (e.g., #7, PR #5) - -### Examples - -- **Issue #7**: "Add Community Marketplaces section - Protocol Thunderdome" → Declined, closed as "not planned" -- **PR #5**: "Add Trail of Bits Security Skills to Related Resources" → Declined, closed - -## Release Workflow - -When adding a new skill or creating a marketplace release: - -### 1. Create the Skill -```bash -# Develop skill in its directory -skill-name/ -├── SKILL.md (no version history!) -├── scripts/ -└── references/ - -# Validate -./skill-creator/scripts/quick_validate.py skill-name - -# Package -./skill-creator/scripts/package_skill.py skill-name -``` - -### 2. Update Marketplace Configuration - -Edit `.claude-plugin/marketplace.json`: - -```json -{ - "metadata": { - "version": "1.x.0" // Bump minor version for new skill - }, - "plugins": [ - { - "name": "new-skill", - "version": "1.0.0", // Skill's initial version - "description": "...", - "category": "...", - "keywords": [...], - "skills": ["./new-skill"] - } - ] -} -``` - -### 3. Update Documentation - -**README.md:** -- Update badges (skills count, marketplace version) -- Add skill description and features -- Create demo GIF using cli-demo-generator -- Add use case section -- Add documentation references -- Add requirements (if applicable) - -**CLAUDE.md:** -- Update skill count in Repository Overview -- Add skill to Available Skills list -- Update Marketplace Configuration count - -### 4. Generate Demo (Optional but Recommended) - -```bash -# Use cli-demo-generator to create demo GIF -./cli-demo-generator/scripts/auto_generate_demo.py \ - -c "command1" \ - -c "command2" \ - -o demos/skill-name/demo-name.gif \ - --title "Skill Demo" \ - --theme "Dracula" -``` - -### 5. Commit and Release - -```bash -# Commit marketplace update -git add .claude-plugin/marketplace.json skill-name/ -git commit -m "Release vX.Y.0: Add skill-name - -- Add skill-name vX.Y.Z -- Update marketplace to vX.Y.0 -..." - -# Commit documentation -git add README.md CLAUDE.md demos/ -git commit -m "docs: Update README for vX.Y.0 with skill-name" - -# Push -git push - -# Create GitHub release -gh release create vX.Y.0 \ - --title "Release vX.Y.0: Add skill-name - Description" \ - --notes "$(cat <<'EOF' -## New Skill: skill-name - -Features: -- Feature 1 -- Feature 2 - -Installation: -```bash -claude plugin install skill-name@daymade-skills -``` - -Changelog: ... -EOF -)" -``` - -### Version Bumping Guide - -**Marketplace version (metadata.version):** -- **MAJOR** (2.0.0): Breaking changes, incompatible marketplace structure -- **MINOR** (1.5.0): New skill added, significant feature addition -- **PATCH** (1.4.1): Bug fixes, documentation updates, skill updates - -**Skill version (plugins[].version):** -- **MAJOR** (2.0.0): Breaking API changes for the skill -- **MINOR** (1.2.0): New features in the skill -- **PATCH** (1.1.1): Bug fixes in the skill - -### Example: v1.5.0 Release (ppt-creator) - -```bash -# 1. Created ppt-creator skill -# 2. Updated marketplace.json: 1.4.0 → 1.5.0 -# 3. Added ppt-creator plugin entry (version: 1.0.0) -# 4. Updated README.md (badges, description, demo) -# 5. Generated demo GIF with cli-demo-generator -# 6. Committed changes -# 7. Created GitHub release with gh CLI -``` +Decline all third-party marketplace promotion requests. For policy, response template, and precedents, see [references/promotion-policy.md](./references/promotion-policy.md). ## Best Practices Reference Always consult Anthropic's skill authoring best practices before creating or updating skills: https://docs.claude.com/en/docs/agents-and-tools/agent-skills/best-practices.md -- remember this release workflow in claude.md ## Plugin and Skill Architecture -This section explains the architecture of Claude Code's extension system and how different components work together. - -### Core Concepts - -#### 1. Skills - -**What**: Functional units that extend Claude's capabilities with specialized knowledge and workflows. - -**Structure**: -``` -skill-name/ -├── SKILL.md (required) # YAML frontmatter + Markdown instructions -├── scripts/ (optional) # Executable code (Python/Bash) -├── references/ (optional) # Documentation loaded as needed -└── assets/ (optional) # Templates and resources -``` - -**Loading mechanism** (Progressive Disclosure): -1. **Metadata** (~100 tokens): Always in context (name + description from YAML frontmatter) -2. **SKILL.md body** (<5k tokens): Loaded when Claude determines the skill applies -3. **Bundled resources**: Loaded only as needed by Claude - -**Location**: -- **Personal**: `~/.claude/skills/` (user-specific, not shared) -- **Project**: `.claude/skills/` (checked into git, shared with team) -- **Plugin cache**: `~/.claude/plugins/cache/{marketplace}/{plugin}/{version}/{skill}/` - -**Example**: When you ask "analyze my disk space", Claude loads the `macos-cleaner` skill's SKILL.md, then reads `references/cleanup_targets.md` as needed. - -#### 2. Plugins - -**What**: Distribution units that package one or more skills for installation via marketplaces. - -**Purpose**: Plugins enable: -- One-command installation (`claude plugin install skill-name@marketplace-name`) -- Version management -- Dependency tracking -- Marketplace distribution - -**Relationship to Skills**: -``` -Plugin (marketplace.json entry) -├── Skill 1 (./skill-name-1/) -├── Skill 2 (./skill-name-2/) -└── Skill 3 (./skill-name-3/) -``` - -**Configuration** (in `.claude-plugin/marketplace.json`): -```json -{ - "name": "my-plugin", - "description": "Use when...", - "version": "1.0.0", - "category": "utilities", - "keywords": ["keyword1", "keyword2"], - "skills": ["./skill-1", "./skill-2"] -} -``` - -**Example**: The `skill-creator` plugin contains one skill (`./skill-creator`), while a hypothetical `developer-tools` plugin might contain multiple skills like `./git-helper`, `./code-reviewer`, `./test-runner`. - -#### 3. Agents (Subagents) - -**What**: Specialized autonomous agents invoked via the `Task` tool for complex, multi-step operations. - -**Types**: -- **Bash**: Command execution specialist -- **general-purpose**: Research, search, multi-step tasks -- **Explore**: Fast codebase exploration -- **Plan**: Software architecture planning -- **skill-creator**: Meta-agent for creating skills -- **Custom**: Domain-specific agents (e.g., `test-runner`, `build-validator`) - -**When to use**: -- Tasks requiring multiple rounds of tool calls -- Open-ended exploration (finding files, searching code) -- Planning before implementation -- Autonomous execution without user intervention - -**Example**: -```python -# Instead of manually searching multiple times: -Task( - subagent_type="Explore", - description="Find error handling code", - prompt="Search the codebase for error handling patterns and list all files that handle HTTP errors" -) -``` - -#### 4. Commands - -**What**: Slash commands (e.g., `/commit`, `/review-pr`) that trigger skills. - -**Relationship**: Commands are shortcuts to invoke skills. -- `/commit` → invokes `commit` skill -- `/review-pr` → invokes `review-pr` skill - -**Configuration**: Defined in plugin's `commands/` directory or skill metadata. - -### Architecture Diagram - -``` -Marketplace (GitHub) - ↓ (git clone) -~/.claude/plugins/marketplaces/{marketplace-name}/ - ↓ (plugin install) -~/.claude/plugins/cache/{marketplace-name}/{plugin}/{version}/ - ├── skill-1/ - │ ├── SKILL.md - │ ├── scripts/ - │ └── references/ - └── skill-2/ - └── SKILL.md - ↓ (Claude loads) -Claude Code Context - ├── Metadata (always loaded) - ├── SKILL.md (loaded when relevant) - └── Resources (loaded as needed) -``` - -### Installation Flow - -#### Step 1: User initiates installation -```bash -claude plugin install macos-cleaner@daymade-skills -``` - -#### Step 2: CLI locates marketplace -```bash -# Check ~/.claude/plugins/marketplaces/daymade-skills/ -# If not exists, git clone from GitHub -``` - -#### Step 3: Read marketplace.json -```json -{ - "plugins": [ - { - "name": "macos-cleaner", - "version": "1.0.0", - "skills": ["./macos-cleaner"] - } - ] -} -``` - -#### Step 4: Download to cache -```bash -# Clone entire marketplace repo to: -~/.claude/plugins/cache/daymade-skills/macos-cleaner/1.0.0/ - -# Extract skill to: -~/.claude/plugins/cache/daymade-skills/macos-cleaner/1.0.0/macos-cleaner/ -``` - -#### Step 5: Record installation -```json -// ~/.claude/plugins/installed_plugins.json -{ - "plugins": { - "macos-cleaner@daymade-skills": [{ - "scope": "user", - "installPath": "~/.claude/plugins/cache/daymade-skills/macos-cleaner/1.0.0", - "version": "1.0.0", - "installedAt": "2026-01-11T08:03:46.593Z" - }] - } -} -``` - -#### Step 6: Claude Code loads skill -``` -When user asks: "My Mac is running out of space" - ↓ -Claude scans installed plugins metadata - ↓ -Finds "macos-cleaner" description matches - ↓ -Loads SKILL.md into context - ↓ -Executes workflow (analyze → report → confirm → cleanup) - ↓ -Loads references/scripts as needed -``` - -### Key Files and Locations - -#### Configuration Files - -| File | Location | Purpose | -|------|----------|---------| -| `marketplace.json` | `~/.claude/plugins/marketplaces/{name}/.claude-plugin/` | Defines available plugins | -| `installed_plugins.json` | `~/.claude/plugins/` | Tracks installed plugins | -| `known_marketplaces.json` | `~/.claude/plugins/` | Lists registered marketplaces | - -#### Directory Structure - -``` -~/.claude/ -├── skills/ # Personal skills (not from marketplace) -├── plugins/ -│ ├── marketplaces/ # Marketplace clones -│ │ ├── daymade-skills/ # Marketplace name -│ │ │ └── .claude-plugin/ -│ │ │ └── marketplace.json -│ │ └── anthropic-agent-skills/ -│ ├── cache/ # Installed plugins -│ │ └── daymade-skills/ -│ │ └── macos-cleaner/ -│ │ └── 1.0.0/ # Version -│ │ └── macos-cleaner/ # Skill directory -│ │ ├── SKILL.md -│ │ ├── scripts/ -│ │ └── references/ -│ ├── installed_plugins.json # Installation registry -│ └── known_marketplaces.json # Marketplace registry -``` - -### Data Flow - -#### Skill Activation -``` -User message - ↓ -Claude analyzes installed plugin metadata - ↓ -Matches description to user intent - ↓ -Loads SKILL.md (progressive disclosure) - ↓ -Executes instructions - ↓ -Loads bundled resources (scripts, references) as needed - ↓ -Generates response -``` - -#### Plugin Update -``` -Local changes to skill - ↓ -git add & commit - ↓ -git push to GitHub - ↓ -User runs: claude plugin marketplace update {marketplace-name} - ↓ -CLI pulls latest from GitHub - ↓ -Updates ~/.claude/plugins/marketplaces/{marketplace-name}/ - ↓ -User runs: claude plugin update {plugin-name@marketplace} - ↓ -Re-downloads to cache with new version number - ↓ -Updates installed_plugins.json -``` - -### Common Misconceptions - -#### ❌ Myth 1: "Updating local files immediately updates the plugin" -**Reality**: Plugins are distributed via GitHub. Local changes require `git push` before users can install updates. - -#### ❌ Myth 2: "Skills and plugins are the same thing" -**Reality**: Skills are functional units (SKILL.md + resources). Plugins are distribution packages (can contain multiple skills). - -#### ❌ Myth 3: "marketplace.json is just metadata" -**Reality**: marketplace.json is the **source of truth** for plugin discovery. Without correct configuration here, `claude plugin install` will fail with "Plugin not found". - -#### ❌ Myth 4: "Cache is just for performance" -**Reality**: Cache (`~/.claude/plugins/cache/`) is where installed plugins actually live. Deleting cache uninstalls all plugins. - -#### ❌ Myth 5: "Skills in ~/.claude/skills/ work the same as plugin skills" -**Reality**: -- `~/.claude/skills/` = Personal skills (manual management, no versioning) -- Plugin cache = Managed by CLI (versioned, updateable, shareable) - -### Best Practices - -#### For Skill Authors - -1. **Clear metadata**: Description should clearly state "Use when..." to help Claude match user intent -2. **Progressive disclosure**: Keep SKILL.md lean, move details to `references/` -3. **Test locally first**: Copy to `~/.claude/skills/` for testing before packaging -4. **Version properly**: Use semver (MAJOR.MINOR.PATCH) in marketplace.json -5. **Document bundled resources**: All scripts and references should be mentioned in SKILL.md - -#### For Marketplace Maintainers - -1. **Git workflow**: Always `git push` after updating marketplace.json -2. **Validate JSON**: Run `python -m json.tool marketplace.json` before committing -3. **Update cache**: Remind users to run `claude plugin marketplace update` after releases -4. **Version consistency**: Marketplace version ≠ plugin versions (they track independently) - -#### For Users - -1. **Update marketplaces**: Run `claude plugin marketplace update {name}` periodically -2. **Check installed plugins**: Inspect `~/.claude/plugins/installed_plugins.json` -3. **Clear cache on issues**: `rm -rf ~/.claude/plugins/cache/{marketplace-name}` then reinstall -4. **Understand scopes**: - - `--scope user`: Only you (default) - - `--scope project`: Shared with team via `.claude/plugins/` - - `--scope local`: Gitignored, local only +For full architecture documentation (core concepts, installation flow, data flow, common misconceptions, best practices), see [references/plugin-architecture.md](./references/plugin-architecture.md). ## Plugin and Skill Troubleshooting -This section provides systematic debugging steps for common plugin and skill installation issues. - -### Understanding the Architecture First - -**CRITICAL**: Before troubleshooting, understand that Claude Code's plugin system is **GitHub-based**, not local-file-based. - -``` -GitHub Repository (source of truth) - ↓ (git clone / git pull) -~/.claude/plugins/marketplaces/{marketplace-name}/ - ↓ (claude plugin install) -~/.claude/plugins/cache/{marketplace-name}/{plugin}/{version}/ - ↓ (Claude Code loads) -Active skill in Claude's context -``` - -**Key insight**: Local file changes are NOT visible to `claude plugin install` until pushed to GitHub. - -### Common Error 1: "Plugin not found in marketplace" - -**Error message**: -``` -Installing plugin "skill-name@marketplace-name"... -✘ Failed to install plugin: Plugin "skill-name" not found in marketplace "marketplace-name" -``` - -**Root causes** (in order of likelihood): - -#### Cause 1.1: Local changes not pushed to GitHub ⭐ **MOST COMMON** - -**Symptoms**: -- `git status` shows modified files or untracked directories -- marketplace.json updated locally but install fails -- All documentation updated but plugin not found - -**Diagnosis**: -```bash -# Check if you have uncommitted changes -git status - -# Check last commit vs remote -git log origin/main..HEAD - -# Verify GitHub has latest marketplace.json -# Open: https://github.com/{owner}/{repo}/blob/main/.claude-plugin/marketplace.json -``` - -**Solution**: -```bash -# 1. Commit all changes -git add -A -git commit -m "Release vX.Y.Z: Add {skill-name}" - -# 2. Push to GitHub -git push - -# 3. Clear local marketplace cache -rm -rf ~/.claude/plugins/cache/{marketplace-name} - -# 4. Update marketplace from GitHub -claude plugin marketplace update {marketplace-name} - -# 5. Retry installation -claude plugin install {skill-name}@{marketplace-name} -``` - -**Why this happens**: You updated marketplace.json locally, but Claude CLI pulls from GitHub, not your local filesystem. - -#### Cause 1.2: marketplace.json configuration error - -**Symptoms**: -- Git is up-to-date but install still fails -- Other plugins from same marketplace install fine - -**Diagnosis**: -```bash -# 1. Check marketplace.json syntax -python3 -m json.tool .claude-plugin/marketplace.json > /dev/null - -# 2. Verify plugin entry exists -cat .claude-plugin/marketplace.json | jq '.plugins[] | select(.name == "skill-name")' - -# 3. Check spelling matches exactly -# Plugin name in marketplace.json MUST match install command -``` - -**Common mistakes**: -```json -// ❌ Wrong: name mismatch -{ - "name": "macos_cleaner", // Underscore - "skills": ["./macos-cleaner"] // Dash -} - -// ✅ Correct: consistent naming -{ - "name": "macos-cleaner", - "skills": ["./macos-cleaner"] -} -``` - -**Solution**: Fix marketplace.json, then commit and push. - -#### Cause 1.3: Skill directory missing - -**Symptoms**: -- marketplace.json has entry -- Git is up-to-date -- Plugin installs but skills don't load - -**Diagnosis**: -```bash -# Check if skill directory exists -ls -la {skill-name}/ - -# Verify SKILL.md exists -ls -la {skill-name}/SKILL.md -``` - -**Solution**: Ensure skill directory and SKILL.md are committed to git. - -### Common Error 2: Marketplace cache is stale - -**Symptoms**: -- GitHub has latest changes -- Install finds plugin but gets old version -- Newly added plugins not visible - -**Diagnosis**: -```bash -# Check cache timestamp -ls -la ~/.claude/plugins/cache/{marketplace-name}/ - -# Compare with last git push -git log -1 --format="%ai" -``` - -**Solution**: -```bash -# Option 1: Update marketplace cache -claude plugin marketplace update {marketplace-name} - -# Option 2: Clear cache and re-fetch -rm -rf ~/.claude/plugins/cache/{marketplace-name} -claude plugin marketplace update {marketplace-name} -``` - -### Common Error 3: JSON syntax error - -**Error message**: -``` -Error parsing marketplace manifest -``` - -**Diagnosis**: -```bash -# Validate JSON syntax -python3 -m json.tool .claude-plugin/marketplace.json - -# Check for common issues: -# - Missing commas -# - Trailing commas (in arrays/objects) -# - Unescaped quotes in strings -# - Missing closing braces -``` - -**Solution**: Fix JSON syntax, validate, commit, push. - -### Systematic Debugging Process - -When facing ANY plugin/skill issue, follow this checklist: - -#### Step 1: Verify marketplace registration - -```bash -# List registered marketplaces -claude plugin marketplace list - -# Expected output should include your marketplace -``` - -If missing, register: -```bash -claude plugin marketplace add https://github.com/{owner}/{repo} -``` - -#### Step 2: Check Git status - -```bash -# Are there uncommitted changes? -git status - -# Is local ahead of remote? -git log origin/main..HEAD - -# Push if needed -git push -``` - -#### Step 3: Verify GitHub has latest - -```bash -# Open in browser or use gh CLI -gh browse .claude-plugin/marketplace.json - -# Or check with curl -curl https://raw.githubusercontent.com/{owner}/{repo}/main/.claude-plugin/marketplace.json | jq '.plugins[] | .name' -``` - -#### Step 4: Clear and update cache - -```bash -# Remove stale cache -rm -rf ~/.claude/plugins/cache/{marketplace-name} - -# Re-fetch from GitHub -claude plugin marketplace update {marketplace-name} -``` - -#### Step 5: Validate configuration - -```bash -# Check marketplace.json is valid JSON -python3 -m json.tool .claude-plugin/marketplace.json > /dev/null && echo "✅ Valid JSON" - -# Check plugin entry exists -cat .claude-plugin/marketplace.json | jq '.plugins[] | select(.name == "skill-name")' || echo "❌ Plugin not found" -``` - -#### Step 6: Inspect installation state - -```bash -# Check if plugin is installed -cat ~/.claude/plugins/installed_plugins.json | jq -r '.plugins | keys[]' | grep "skill-name" - -# If installed, check details -cat ~/.claude/plugins/installed_plugins.json | jq '.plugins["skill-name@marketplace-name"]' - -# Verify files exist -ls ~/.claude/plugins/cache/{marketplace-name}/{skill-name}/{version}/ -``` - -### Debugging Commands Reference - -| Purpose | Command | -|---------|---------| -| List marketplaces | `claude plugin marketplace list` | -| Update marketplace | `claude plugin marketplace update {name}` | -| Install plugin | `claude plugin install {plugin}@{marketplace}` | -| Uninstall plugin | `claude plugin uninstall {plugin}@{marketplace}` | -| Update plugin | `claude plugin update {plugin}@{marketplace}` | -| Validate manifest | `claude plugin validate {path}` | -| Check installed plugins | `cat ~/.claude/plugins/installed_plugins.json \| jq '.plugins \| keys'` | -| Inspect plugin details | `cat ~/.claude/plugins/installed_plugins.json \| jq '.plugins["{plugin}@{marketplace}"]'` | -| Clear marketplace cache | `rm -rf ~/.claude/plugins/cache/{marketplace-name}` | -| Verify JSON syntax | `python3 -m json.tool {file.json}` | - -### Understanding File Locations - -```bash -# Marketplace clones (git repositories) -~/.claude/plugins/marketplaces/{marketplace-name}/ - -# Installed plugin cache -~/.claude/plugins/cache/{marketplace-name}/{plugin-name}/{version}/ - -# Installation registry -~/.claude/plugins/installed_plugins.json - -# Personal skills (not from marketplace) -~/.claude/skills/ - -# Project-scoped skills (shared with team) -.claude/skills/ -``` - -### Common Pitfalls - -#### Pitfall 1: Confusing local skills with plugin skills - -```bash -# ❌ Wrong: Copying skill to personal directory doesn't make it installable -cp -r my-skill ~/.claude/skills/my-skill # Works, but not managed by plugin system - -# ✅ Correct: Install via marketplace for version management -claude plugin install my-skill@my-marketplace -``` - -#### Pitfall 2: Forgetting to push after updating marketplace.json - -```bash -# ❌ Wrong workflow -vim .claude-plugin/marketplace.json # Add new plugin -git add .claude-plugin/marketplace.json -git commit -m "Add plugin" -# FORGOT TO PUSH! -claude plugin install new-plugin@my-marketplace # ❌ Fails: not found - -# ✅ Correct workflow -vim .claude-plugin/marketplace.json -git add -A -git commit -m "Add new plugin" -git push # ← CRITICAL STEP -claude plugin marketplace update my-marketplace -claude plugin install new-plugin@my-marketplace # ✅ Works -``` - -#### Pitfall 3: Expecting instant propagation - -```bash -# ❌ Wrong expectation -git push # Push changes -claude plugin install new-plugin@my-marketplace # ❌ Fails: cache is stale - -# ✅ Correct: Update cache first -git push -claude plugin marketplace update my-marketplace # Fetch latest from GitHub -claude plugin install new-plugin@my-marketplace # ✅ Works -``` - -#### Pitfall 4: Inconsistent naming - -```json -// marketplace.json -{ - "name": "my_plugin", // Underscore - "skills": ["./my-plugin"] // Dash - will cause confusion -} -``` - -```bash -# User tries to install -claude plugin install my-plugin@marketplace # ❌ Not found (name has underscore) -claude plugin install my_plugin@marketplace # ✅ Works, but confusing -``` - -**Best practice**: Use consistent kebab-case for both plugin name and skill directory. - -### Real-World Example: macos-cleaner Installation Issue - -**Scenario**: After creating macos-cleaner skill and updating all documentation, `claude plugin install macos-cleaner@daymade-skills` failed with "Plugin not found". - -**Investigation**: -```bash -# 1. Check git status -git status -# Output: 16 modified/untracked files - -# 2. Check marketplace cache -ls -la ~/.claude/plugins/cache/daymade-skills/ -# Output: Last modified Dec 20 (weeks old!) - -# 3. Check GitHub -# marketplace.json on GitHub: version 1.20.0 (old) -# Local marketplace.json: version 1.21.0 (new) -``` - -**Root cause**: Local changes weren't pushed to GitHub. CLI was pulling from GitHub, not local files. - -**Solution**: -```bash -# 1. Commit and push -git add -A -git commit -m "Release v1.21.0: Add macos-cleaner" -git push - -# 2. Update marketplace -claude plugin marketplace update daymade-skills - -# 3. Install -claude plugin install macos-cleaner@daymade-skills -# ✔ Successfully installed plugin: macos-cleaner@daymade-skills -``` - -**Verification**: -```bash -cat ~/.claude/plugins/installed_plugins.json | jq '.plugins["macos-cleaner@daymade-skills"]' -# Output: Installation details with correct version - -ls ~/.claude/plugins/cache/daymade-skills/macos-cleaner/1.0.0/ -# Output: All skill files present -``` - -**Lesson**: Always remember the GitHub-based architecture. Local changes are invisible until pushed. - -### Advanced: Manual Cache Inspection - -If automated commands don't reveal the issue, manually inspect: - -```bash -# 1. Check marketplace clone -cat ~/.claude/plugins/marketplaces/{marketplace-name}/.claude-plugin/marketplace.json | jq '.metadata.version' - -# 2. Check what's in cache -ls -R ~/.claude/plugins/cache/{marketplace-name}/ - -# 3. Compare with GitHub -curl -s https://raw.githubusercontent.com/{owner}/{repo}/main/.claude-plugin/marketplace.json | jq '.metadata.version' - -# 4. Check installation record -cat ~/.claude/plugins/installed_plugins.json | jq '.plugins' | grep -i "{skill-name}" -``` - -### When All Else Fails - -1. **Complete cache reset**: - ```bash - rm -rf ~/.claude/plugins/cache/* - claude plugin marketplace update {marketplace-name} - ``` - -2. **Re-register marketplace**: - ```bash - # Remove marketplace - # (No direct command, manual edit ~/.claude/plugins/known_marketplaces.json) - - # Re-add - claude plugin marketplace add https://github.com/{owner}/{repo} - ``` - -3. **Check Claude Code version**: - ```bash - claude --version - # Plugins require Claude Code v2.0.12+ - ``` - -4. **Enable verbose logging** (if available): - ```bash - CLAUDE_DEBUG=1 claude plugin install {plugin}@{marketplace} - ``` - -### Getting Help - -If you're still stuck: - -1. **Check GitHub issues**: https://github.com/anthropics/claude-code/issues -2. **Verify marketplace.json**: Run `claude plugin validate .claude-plugin/marketplace.json` -3. **Compare with working marketplace**: Study anthropic's official marketplace structure -4. **Document your debugging**: Include output from all diagnostic commands above +For systematic debugging steps (common errors, debugging process, pitfalls, real-world examples), see [references/plugin-troubleshooting.md](./references/plugin-troubleshooting.md). -For this project specifically, refer to: -- [Plugin and Skill Architecture](#plugin-and-skill-architecture) - Architecture overview (this document) -- [skill-creator/SKILL.md](./skill-creator/SKILL.md) - Skill creation guide -- [CONTRIBUTING.md](./CONTRIBUTING.md) - Development workflow +**Quick fix for most issues**: Commit → push → `claude plugin marketplace update daymade-skills` → retry install. diff --git a/QUICKSTART.md b/QUICKSTART.md index ec254187..79aad6ce 100644 --- a/QUICKSTART.md +++ b/QUICKSTART.md @@ -25,15 +25,15 @@ Then: claude plugin marketplace add https://github.com/daymade/claude-code-skills # Marketplace name: daymade-skills (from marketplace.json) -# Install skill-creator -claude plugin install skill-creator@daymade-skills +# Install the daymade-skill suite (bundles skill-creator) +claude plugin install daymade-skill@daymade-skills ``` ### Step 2: Initialize Your First Skill ```bash # Create a new skill from template -skill-creator/scripts/init_skill.py my-first-skill --path ~/my-skills +daymade-skill/skill-creator/scripts/init_skill.py my-first-skill --path ~/my-skills ``` This generates: @@ -61,7 +61,7 @@ Edit `~/my-skills/my-first-skill/SKILL.md`: ```bash # Check if your skill meets quality standards -skill-creator/scripts/quick_validate.py ~/my-skills/my-first-skill +daymade-skill/skill-creator/scripts/quick_validate.py ~/my-skills/my-first-skill ``` Fix any errors reported, then validate again. @@ -70,7 +70,7 @@ Fix any errors reported, then validate again. ```bash # Create a distributable .zip file -skill-creator/scripts/package_skill.py ~/my-skills/my-first-skill +daymade-skill/skill-creator/scripts/package_skill.py ~/my-skills/my-first-skill ``` This creates `my-first-skill.zip` ready to share! @@ -87,7 +87,7 @@ cp -r ~/my-skills/my-first-skill ~/.claude/skills/ ### Next Steps -- 📖 Read [skill-creator/SKILL.md](./skill-creator/SKILL.md) for comprehensive guidance +- 📖 Read [skill-creator/SKILL.md](./daymade-skill/skill-creator/SKILL.md) for comprehensive guidance - 🔍 Study existing skills in this marketplace for examples - 💡 Check [CONTRIBUTING.md](./CONTRIBUTING.md) to share your skill @@ -122,7 +122,7 @@ claude plugin marketplace add https://github.com/daymade/claude-code-skills # In Claude Code use `/plugin ...`; in your terminal use `claude plugin ...` # Step 2: Install skills you need claude plugin install github-ops@daymade-skills -claude plugin install markdown-tools@daymade-skills +claude plugin install daymade-docs@daymade-skills # ... add more as needed # Step 3: Restart Claude Code @@ -136,7 +136,7 @@ This table is a quick starter list. See [README.md](./README.md) for the full ca |-------|-------------|-------------| | **skill-creator** ⭐ | Create your own skills | Building custom workflows | | **github-ops** | GitHub operations | Managing PRs, issues, workflows | -| **markdown-tools** | Document conversion | Converting docs to markdown | +| **doc-to-markdown** | Document conversion | Converting docs to markdown | | **mermaid-tools** | Diagram generation | Creating PNG diagrams | | **statusline-generator** | Statusline customization | Customizing Claude Code UI | | **teams-channel-post-writer** | Teams communication | Writing professional posts | diff --git a/QUICKSTART.zh-CN.md b/QUICKSTART.zh-CN.md index a188f556..8bb630f7 100644 --- a/QUICKSTART.zh-CN.md +++ b/QUICKSTART.zh-CN.md @@ -25,15 +25,15 @@ claude plugin marketplace add https://github.com/daymade/claude-code-skills # Marketplace 名称：daymade-skills（来自 marketplace.json） -# 安装 skill-creator -claude plugin install skill-creator@daymade-skills +# 安装 daymade-skill 套件（含 skill-creator） +claude plugin install daymade-skill@daymade-skills ``` ### 步骤 2：初始化你的第一个技能 ```bash # 从模板创建一个新技能 -skill-creator/scripts/init_skill.py my-first-skill --path ~/my-skills +daymade-skill/skill-creator/scripts/init_skill.py my-first-skill --path ~/my-skills ``` 这将生成： @@ -61,7 +61,7 @@ skill-creator/scripts/init_skill.py my-first-skill --path ~/my-skills ```bash # 检查你的技能是否符合质量标准 -skill-creator/scripts/quick_validate.py ~/my-skills/my-first-skill +daymade-skill/skill-creator/scripts/quick_validate.py ~/my-skills/my-first-skill ``` 修复报告的任何错误，然后再次验证。 @@ -70,7 +70,7 @@ skill-creator/scripts/quick_validate.py ~/my-skills/my-first-skill ```bash # 创建可分发的 .zip 文件 -skill-creator/scripts/package_skill.py ~/my-skills/my-first-skill +daymade-skill/skill-creator/scripts/package_skill.py ~/my-skills/my-first-skill ``` 这将创建 `my-first-skill.zip`，可以分享了！ @@ -87,7 +87,7 @@ cp -r ~/my-skills/my-first-skill ~/.claude/skills/ ### 下一步 -- 📖 阅读 [skill-creator/SKILL.md](./skill-creator/SKILL.md) 获取全面指导 +- 📖 阅读 [skill-creator/SKILL.md](./daymade-skill/skill-creator/SKILL.md) 获取全面指导 - 🔍 研究此市场中的现有技能以获取示例 - 💡 查看 [CONTRIBUTING.md](./CONTRIBUTING.md) 以分享你的技能 @@ -122,7 +122,7 @@ claude plugin marketplace add https://github.com/daymade/claude-code-skills # 在 Claude Code 内使用 `/plugin ...`，在终端中使用 `claude plugin ...` # 步骤 2：安装你需要的技能 claude plugin install github-ops@daymade-skills -claude plugin install markdown-tools@daymade-skills +claude plugin install daymade-docs@daymade-skills # ... 根据需要添加更多 # 步骤 3：重启 Claude Code @@ -136,7 +136,7 @@ claude plugin install markdown-tools@daymade-skills |-------|-------------|-------------| | **skill-creator** ⭐ | 创建你自己的技能 | 构建自定义工作流 | | **github-ops** | GitHub 操作 | 管理 PR、问题、工作流 | -| **markdown-tools** | 文档转换 | 将文档转换为 markdown | +| **doc-to-markdown** | 文档转换 | 将文档转换为 markdown | | **mermaid-tools** | 图表生成 | 创建 PNG 图表 | | **statusline-generator** | 状态栏定制 | 自定义 Claude Code UI | | **teams-channel-post-writer** | Teams 通信 | 编写专业帖子 | diff --git a/README.md b/README.md index 015a5f52..547cc16b 100644 --- a/README.md +++ b/README.md @@ -6,15 +6,15 @@ [![简体中文](https://img.shields.io/badge/语言-简体中文-red)](./README.zh-CN.md) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) -[![Skills](https://img.shields.io/badge/skills-41-blue.svg)](https://github.com/daymade/claude-code-skills) -[![Version](https://img.shields.io/badge/version-1.37.0-green.svg)](https://github.com/daymade/claude-code-skills) +[![Skills](https://img.shields.io/badge/skills-64-blue.svg)](https://github.com/daymade/claude-code-skills) +[![Version](https://img.shields.io/badge/version-1.65.0-green.svg)](https://github.com/daymade/claude-code-skills) [![Claude Code](https://img.shields.io/badge/Claude%20Code-2.0.13+-purple.svg)](https://claude.com/code) [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](./CONTRIBUTING.md) [![Maintenance](https://img.shields.io/badge/Maintained%3F-yes-green.svg)](https://github.com/daymade/claude-code-skills/graphs/commit-activity) -Professional Claude Code skills marketplace featuring 41 production-ready skills for enhanced development workflows. +Professional Claude Code skills marketplace featuring 64 production-ready skills for enhanced development workflows. ## 📑 Table of Contents @@ -38,13 +38,35 @@ Professional Claude Code skills marketplace featuring 41 production-ready skills The `skill-creator` is the **meta-skill** that enables you to build, validate, and package your own Claude Code skills. It's the most important tool in this marketplace because it empowers you to extend Claude Code with your own specialized workflows. -### Why skill-creator First? +### Why This skill-creator? -- **🎯 Foundation**: Learn how skills work by creating your own -- **🛠️ Complete Toolkit**: Initialization, validation, and packaging scripts included -- **📖 Best Practices**: Learn from production-ready examples -- **🚀 Quick Start**: Generate skill templates in seconds -- **✅ Quality Assurance**: Built-in validation ensures your skills meet standards +This is a **production-hardened fork** of [Anthropic's official skill-creator](https://github.com/anthropics/skills/tree/main/skills/skill-creator), born from building real skills and hitting every wall the official version doesn't warn you about. + +**The official skill-creator tells you _what_ to build. Ours also tells you _what not to try_ — and why.** + +| You're trying to... | Official | This Fork | +|---------------------|----------|-----------| +| Research before building | "Check available MCPs" (5 lines) | 8-channel search protocol with decision matrix: Adopt / Extend / Build | +| Create a skill interactively | Prose-based instructions | 9 structured AskUserQuestion checkpoints — user never loses context | +| Avoid common mistakes | No guidance | Cache edit warnings, prerequisite checks, security scan gate | +| Know the architecture options | Not mentioned | Inline vs Fork decision guide with examples (choosing wrong silently breaks your skill) | +| Validate before shipping | Basic YAML check | Expanded validator (all frontmatter fields, path reference integrity, whitespace issues) | +| Catch security issues | No tooling | `security_scan.py` with gitleaks integration — hard gate before packaging | +| Learn from real failures | No failure cases | Battle-tested methodology with documented failure patterns and gotchas | + +**Quality comparison** (independent audit, 8 dimensions): + +| Dimension | Official | This Fork | +|-----------|----------|-----------| +| Actionability | 7 | 9 | +| Error Prevention | 5 | 9 | +| Prior Art Research | 4 | 9 | +| Counter Review Process | 4 | 8 | +| Real-World Lessons | 3 | 8 | +| User Experience | 4 | 9 | +| **Total (out of 80)** | **42** | **65** | + +> Full methodology: [skill-creator/references/skill-development-methodology.md](./daymade-skill/skill-creator/references/skill-development-methodology.md) ### Quick Install @@ -63,7 +85,7 @@ Then: ```bash claude plugin marketplace add https://github.com/daymade/claude-code-skills # Marketplace name: daymade-skills (from marketplace.json) -claude plugin install skill-creator@daymade-skills +claude plugin install daymade-skill@daymade-skills ``` ### What You Can Do @@ -80,7 +102,7 @@ After installing skill-creator, simply ask Claude Code: Claude Code, with skill-creator loaded, will guide you through the entire skill creation process - from understanding your requirements to packaging the final skill. -📚 **Full documentation**: [skill-creator/SKILL.md](./skill-creator/SKILL.md) +📚 **Full documentation**: [daymade-skill/skill-creator/SKILL.md](./daymade-skill/daymade-skill/skill-creator/SKILL.md) ### Live Demos @@ -137,22 +159,50 @@ In Claude Code, use `/plugin ...` slash commands. In your terminal, use `claude **Essential Skill** (recommended first install): ```bash -claude plugin install skill-creator@daymade-skills +# skill-creator ships inside the daymade-skill suite +claude plugin install daymade-skill@daymade-skills ``` -**Install Other Skills:** +**Documentation Suite** (shared namespace for document workflows): ```bash -# GitHub operations -claude plugin install github-ops@daymade-skills +claude plugin install daymade-docs@daymade-skills +``` -# Document conversion -claude plugin install markdown-tools@daymade-skills +This suite exposes related skills under one namespace, including: -# Diagram generation -claude plugin install mermaid-tools@daymade-skills +```text +/daymade-docs:doc-to-markdown +/daymade-docs:mermaid-tools +/daymade-docs:pdf-creator +/daymade-docs:ppt-creator +/daymade-docs:docs-cleaner +``` -# Statusline customization -claude plugin install statusline-generator@daymade-skills +These skills ship as a bundle — there are no separate single-skill plugins. All documentation skills live under `daymade-docs/` and install together from the suite. + +**Claude Code Operations Suite** (shared namespace for Claude Code power-user workflows): +```bash +claude plugin install daymade-claude-code@daymade-skills +``` + +This suite bundles the skills that extend Claude Code itself — session recovery, CLAUDE.md tuning, troubleshooting, statusline configuration, export repair, and marketplace development: + +```text +/daymade-claude-code:claude-code-history-files-finder +/daymade-claude-code:continue-claude-work +/daymade-claude-code:claude-skills-troubleshooting +/daymade-claude-code:claude-md-progressive-disclosurer +/daymade-claude-code:statusline-generator +/daymade-claude-code:claude-export-txt-better +/daymade-claude-code:marketplace-dev +``` + +Installed names render as `daymade-claude-code:` under a single shared namespace. These skills are bundle-only — install the suite to get all seven. + +**Install Other Skills:** +```bash +# GitHub operations +claude plugin install github-ops@daymade-skills # Teams communication claude plugin install teams-channel-post-writer@daymade-skills @@ -172,17 +222,14 @@ claude plugin install cloudflare-troubleshooting@daymade-skills # UI design system extraction claude plugin install ui-designer@daymade-skills -# Presentation creation -claude plugin install ppt-creator@daymade-skills - # YouTube video/audio downloading claude plugin install youtube-downloader@daymade-skills # Secure repomix packaging claude plugin install repomix-safe-mixer@daymade-skills -# ASR transcript correction -claude plugin install transcript-fixer@daymade-skills +# Full audio suite (ASR + transcript correction + meeting minutes + TTS) +claude plugin install daymade-audio@daymade-skills # Video comparison and quality analysis claude plugin install video-comparer@daymade-skills @@ -193,20 +240,8 @@ claude plugin install qa-expert@daymade-skills # Prompt optimization using EARS methodology claude plugin install prompt-optimizer@daymade-skills -# Session history recovery -claude plugin install claude-code-history-files-finder@daymade-skills - -# Documentation consolidation -claude plugin install docs-cleaner@daymade-skills - -# PDF generation with Chinese font support -claude plugin install pdf-creator@daymade-skills - -# CLAUDE.md progressive disclosure optimization -claude plugin install claude-md-progressive-disclosurer@daymade-skills - # CCPM skill registry search and management -claude plugin install skills-search@daymade-skills +claude plugin install daymade-skill@daymade-skills # Promptfoo LLM evaluation framework claude plugin install promptfoo-evaluation@daymade-skills @@ -218,7 +253,7 @@ claude plugin install iOS-APP-developer@daymade-skills claude plugin install twitter-reader@daymade-skills # Skill quality review and improvement -claude plugin install skill-reviewer@daymade-skills +claude plugin install daymade-skill@daymade-skills # GitHub contribution strategy claude plugin install github-contributor@daymade-skills @@ -237,6 +272,18 @@ claude plugin install excel-automation@daymade-skills # Programmatic macOS screenshot capture workflows claude plugin install capture-screen@daymade-skills + +# Scrapling CLI extraction and troubleshooting +claude plugin install scrapling-skill@daymade-skills + +# Tencent IMA knowledge base companion and installer +claude plugin install ima-copilot@daymade-skills + +# Export Douban (豆瓣) book/movie/music/game collections to CSV +claude plugin install douban-skill@daymade-skills + +# Terraform operational traps and multi-environment reliability patterns +claude plugin install terraform-skill@daymade-skills ``` Each skill can be installed independently - choose only what you need! @@ -288,7 +335,9 @@ Comprehensive GitHub operations using gh CLI and GitHub API. --- -### 2. **markdown-tools** - Document Conversion Suite +### 2. **doc-to-markdown** - Document Conversion Suite + +> **Install**: `claude plugin install daymade-docs@daymade-skills` (suite-only — invoked as `daymade-docs:doc-to-markdown`) Converts documents to markdown with Windows/WSL path handling and PDF image extraction. @@ -307,12 +356,14 @@ Converts documents to markdown with Windows/WSL path handling and PDF image extr **🎬 Live Demo** -![Markdown Tools Demo](./demos/markdown-tools/convert-docs.gif) +![Markdown Tools Demo](./demos/doc-to-markdown/convert-docs.gif) --- ### 3. **mermaid-tools** - Diagram Generation +> **Install**: `claude plugin install daymade-docs@daymade-skills` (suite-only — invoked as `daymade-docs:mermaid-tools`) + Extracts Mermaid diagrams from markdown and generates high-quality PNG images. **When to use:** @@ -336,6 +387,8 @@ Extracts Mermaid diagrams from markdown and generates high-quality PNG images. ### 4. **statusline-generator** - Statusline Customization +> **Install**: `claude plugin install daymade-claude-code@daymade-skills` (suite-only — invoked as `daymade-claude-code:statusline-generator`) + Configures Claude Code statuslines with multi-line layouts and cost tracking. **When to use:** @@ -505,6 +558,8 @@ Extract design systems from reference UI images and generate implementation-read ### 11. **ppt-creator** - Professional Presentation Creation +> **Install**: `claude plugin install daymade-docs@daymade-skills` (suite-only — invoked as `daymade-docs:ppt-creator`) + Create persuasive, audience-ready slide decks from topics or documents with data-driven charts and dual-format PPTX output. **When to use:** @@ -581,6 +636,8 @@ Safely package codebases with repomix by automatically detecting and removing ha ### 14. **transcript-fixer** - ASR Transcription Correction +> **Install**: `claude plugin install daymade-audio@daymade-skills` (suite-only — invoked as `daymade-audio:transcript-fixer`) + Correct speech-to-text (ASR/STT) transcription errors through dictionary-based rules and AI-powered corrections with automatic pattern learning. **When to use:** @@ -616,7 +673,7 @@ uv run scripts/fix_transcription.py --review-learned *Coming soon* -📚 **Documentation**: See [transcript-fixer/references/](./transcript-fixer/references/) for workflow guides, SQL queries, troubleshooting, best practices, team collaboration, and API setup. +📚 **Documentation**: See [daymade-audio/transcript-fixer/references/](./daymade-audio/transcript-fixer/references/) for workflow guides, SQL queries, troubleshooting, best practices, team collaboration, and API setup. **Requirements**: Python 3.6+, uv package manager, GLM API key (get from https://open.bigmodel.cn/) @@ -786,6 +843,8 @@ Transform vague prompts into precise, well-structured specifications using EARS ### 18. **claude-code-history-files-finder** - Session History Recovery +> **Install**: `claude plugin install daymade-claude-code@daymade-skills` (suite-only — invoked as `daymade-claude-code:claude-code-history-files-finder`) + Find and recover content from Claude Code session history files stored in `~/.claude/projects/`. **When to use:** @@ -820,7 +879,7 @@ python3 scripts/analyze_sessions.py stats /path/to/session.jsonl --show-files *Coming soon* -📚 **Documentation**: See [claude-code-history-files-finder/references/](./claude-code-history-files-finder/references/) for: +📚 **Documentation**: See [daymade-claude-code/claude-code-history-files-finder/references/](./daymade-claude-code/claude-code-history-files-finder/references/) for: - `session_file_format.md` - JSONL structure and extraction patterns - `workflow_examples.md` - Detailed recovery and analysis workflows @@ -828,6 +887,8 @@ python3 scripts/analyze_sessions.py stats /path/to/session.jsonl --show-files ### 19. **docs-cleaner** - Documentation Consolidation +> **Install**: `claude plugin install daymade-docs@daymade-skills` (suite-only — invoked as `daymade-docs:docs-cleaner`) + Consolidate redundant documentation while preserving all valuable content. **When to use:** @@ -891,7 +952,7 @@ ccpm install-bundle web-dev # Install web development skills bundle *Coming soon* -📚 **Documentation**: See [skills-search/SKILL.md](./skills-search/SKILL.md) for complete command reference +📚 **Documentation**: See [daymade-skill/skills-search/SKILL.md](./daymade-skill/daymade-skill/skills-search/SKILL.md) for complete command reference **Requirements**: CCPM CLI (`npm install -g @daymade/ccpm`) @@ -899,6 +960,8 @@ ccpm install-bundle web-dev # Install web development skills bundle ### 21. **pdf-creator** - PDF Creation with Chinese Font Support +> **Install**: `claude plugin install daymade-docs@daymade-skills` (suite-only — invoked as `daymade-docs:pdf-creator`) + Create professional PDF documents from markdown with proper Chinese typography using WeasyPrint. **When to use:** @@ -907,28 +970,31 @@ Create professional PDF documents from markdown with proper Chinese typography u - Ensuring correct Chinese font rendering **Key features:** -- WeasyPrint + Markdown conversion pipeline -- Built-in Chinese font fallbacks +- pandoc + WeasyPrint conversion pipeline (dual backend: WeasyPrint or headless Chrome) +- Built-in Chinese/Japanese/Korean (CJK) font fallbacks with auto CJK code-block rendering +- Theme system (default for formal docs, cjk-auto for content-driven tables, warm-terra for training materials, mobile for phone reading) - A4 layout defaults with print-friendly margins - Batch conversion scripts **Example usage:** ```bash -uv run --with weasyprint --with markdown scripts/md_to_pdf.py input.md output.pdf +uv run --with weasyprint scripts/md_to_pdf.py input.md output.pdf ``` **🎬 Live Demo** *Coming soon* -📚 **Documentation**: See [pdf-creator/SKILL.md](./pdf-creator/SKILL.md) for setup and workflow details. +📚 **Documentation**: See [daymade-docs/pdf-creator/SKILL.md](./daymade-docs/pdf-creator/SKILL.md) for setup and workflow details. -**Requirements**: Python 3.8+, `weasyprint`, `markdown` +**Requirements**: Python 3.8+, `pandoc` (system install), `weasyprint` (or Chrome as fallback backend) --- ### 22. **claude-md-progressive-disclosurer** - CLAUDE.md Optimization +> **Install**: `claude plugin install daymade-claude-code@daymade-skills` (suite-only — invoked as `daymade-claude-code:claude-md-progressive-disclosurer`) + Optimize user CLAUDE.md files using progressive disclosure to reduce context bloat while preserving critical rules. **When to use:** @@ -951,7 +1017,7 @@ Optimize user CLAUDE.md files using progressive disclosure to reduce context blo *Coming soon* -📚 **Documentation**: See [claude-md-progressive-disclosurer/SKILL.md](./claude-md-progressive-disclosurer/SKILL.md). +📚 **Documentation**: See [claude-md-progressive-disclosurer/SKILL.md](./daymade-claude-code/claude-md-progressive-disclosurer/SKILL.md). --- @@ -1235,7 +1301,7 @@ Review and improve Claude Code skills against official best practices with three **Example usage:** ```bash # Install the skill -claude plugin install skill-reviewer@daymade-skills +claude plugin install daymade-skill@daymade-skills # Self-review your skill "Validate my skill at ~/my-skills/my-awesome-skill" @@ -1251,10 +1317,9 @@ claude plugin install skill-reviewer@daymade-skills *Coming soon* -📚 **Documentation**: See [skill-reviewer/references/](./skill-reviewer/references/) for: +📚 **Documentation**: See [daymade-skill/skill-reviewer/references/](./daymade-skill/daymade-skill/skill-reviewer/references/) for: - `evaluation_checklist.md` - Complete skill evaluation criteria - `pr_template.md` - Professional PR description template -- `marketplace_template.json` - Marketplace configuration template --- @@ -1368,6 +1433,8 @@ claude plugin install i18n-expert@daymade-skills ### 32. **claude-skills-troubleshooting** - Plugin & Skill Troubleshooting +> **Install**: `claude plugin install daymade-claude-code@daymade-skills` (suite-only — invoked as `daymade-claude-code:claude-skills-troubleshooting`) + Diagnose and resolve Claude Code plugin and skill configuration issues. Debug plugin installation, enablement, and activation problems with systematic workflows. **When to use:** @@ -1388,9 +1455,6 @@ Diagnose and resolve Claude Code plugin and skill configuration issues. Debug pl **Example usage:** ```bash -# Install the skill -claude plugin install claude-skills-troubleshooting@daymade-skills - # Run diagnostic python3 scripts/diagnose_plugins.py @@ -1402,7 +1466,7 @@ python3 scripts/enable_all_plugins.py daymade-skills *Coming soon* -📚 **Documentation**: See [claude-skills-troubleshooting/SKILL.md](./claude-skills-troubleshooting/SKILL.md) for complete troubleshooting workflow and architecture guidance. +📚 **Documentation**: See [claude-skills-troubleshooting/SKILL.md](./daymade-claude-code/claude-skills-troubleshooting/SKILL.md) for complete troubleshooting workflow and architecture guidance. **Requirements**: None (uses Claude Code built-in Python) @@ -1410,6 +1474,8 @@ python3 scripts/enable_all_plugins.py daymade-skills ### 33. **meeting-minutes-taker** - Meeting Minutes Generator +> **Install**: `claude plugin install daymade-audio@daymade-skills` (suite-only — invoked as `daymade-audio:meeting-minutes-taker`) + Transform meeting transcripts into high-fidelity, structured meeting minutes with iterative human review. **When to use:** @@ -1427,8 +1493,8 @@ Transform meeting transcripts into high-fidelity, structured meeting minutes wit **Example usage:** ```bash -# Install the skill -claude plugin install meeting-minutes-taker@daymade-skills +# Install the full audio suite (includes meeting-minutes-taker) +claude plugin install daymade-audio@daymade-skills # Then provide a meeting transcript and request minutes ``` @@ -1437,7 +1503,7 @@ claude plugin install meeting-minutes-taker@daymade-skills *Coming soon* -📚 **Documentation**: See [meeting-minutes-taker/SKILL.md](./meeting-minutes-taker/SKILL.md) for complete workflow and template guidance. +📚 **Documentation**: See [daymade-audio/meeting-minutes-taker/SKILL.md](./daymade-audio/meeting-minutes-taker/SKILL.md) for complete workflow and template guidance. **Requirements**: None @@ -1749,6 +1815,791 @@ claude plugin install capture-screen@daymade-skills --- +### 42. **continue-claude-work** - Resume Interrupted Claude Work + +> **Install**: `claude plugin install daymade-claude-code@daymade-skills` (suite-only — invoked as `daymade-claude-code:continue-claude-work`) + +Recover actionable context from local `~/.claude` session artifacts and continue implementation without reopening the old interactive session. Uses a bundled Python script for intelligent context extraction. + +**When to use:** +- A user provides a Claude session ID and wants the task continued +- You need to inspect local `.claude` JSONL files instead of running `claude --resume` +- A previous session was interrupted and the next concrete step must be reconstructed +- A multi-agent workflow was interrupted and you need to know which subagents completed + +**Key features:** +- Compact-boundary-aware extraction — reads Claude's own session compaction summaries as highest-signal context +- Subagent workflow recovery — reports completed vs. interrupted subagents with last outputs +- Session end reason detection — classifies clean exit, interrupted (ctrl-c), error cascade, or abandoned +- Size-adaptive strategy — different reading approaches for small (<500KB) vs. large (>5MB) sessions +- Noise filtering — skips progress/queue-operation/api_error messages (37-53% of session lines) +- Self-session exclusion, stale index fallback, MEMORY.md integration, git workspace state + +**Example usage:** +```bash +# Then ask Claude to resume from local artifacts +"continue work from session 123e4567-e89b-12d3-a456-426614174000" +"don't resume, just read the .claude files and continue" +"check what I was working on in the last session and keep going" +``` + +📚 **Documentation**: See [continue-claude-work/SKILL.md](./daymade-claude-code/continue-claude-work/SKILL.md). + +**Requirements**: Python 3.8+, `git` for workspace reconciliation. + +--- + +### 43. **scrapling-skill** - Reliable Scrapling CLI Workflows + +Install, troubleshoot, and use Scrapling CLI with a verified static-first workflow for extracting HTML, Markdown, or text from webpages. Includes a diagnostic script for broken extras installs, Playwright browser runtime checks, and smoke tests against real URLs. + +**When to use:** +- Users mention Scrapling, `uv tool install scrapling`, or `scrapling extract` +- You need to choose between static and browser-backed fetching +- You need to extract article bodies from WeChat public pages (`mp.weixin.qq.com`) +- A Scrapling install works partially but fails on missing extras, browser runtime, or TLS verification + +**Key features:** +- Bundled `diagnose_scrapling.py` script for CLI, browser runtime, and live URL smoke tests +- Verified default path: start with `extract get`, escalate to `extract fetch` only when needed +- WeChat extraction pattern using `#js_content` for clean article Markdown +- Troubleshooting guidance for missing `click`, Playwright runtime setup, and `curl: (60)` trust-store failures +- Output validation workflow using file size and content checks instead of exit-code assumptions + +**Example usage:** +```bash +# Install the skill +claude plugin install scrapling-skill@daymade-skills + +# Then ask Claude to work through Scrapling for you +"Install Scrapling CLI and verify the setup" +"Extract this WeChat article into Markdown with Scrapling" +"Decide whether this page needs static or browser-backed fetching" +``` + +**🎬 Live Demo** + +*Coming soon* + +📚 **Documentation**: See [scrapling-skill/SKILL.md](./scrapling-skill/SKILL.md) and [scrapling-skill/references/troubleshooting.md](./scrapling-skill/references/troubleshooting.md). + +**Requirements**: Python 3.6+, `uv`, Scrapling CLI, and Playwright browser runtime for browser-backed fetches. + +--- + +### 44. **ima-copilot** - Tencent IMA Companion & Installer + +One-stop wrapper for the official Tencent IMA skill (`ima.qq.com`). Installs upstream `ima-skill` to Claude Code, Codex, and OpenClaw via `npx skills add`, guides API key setup, detects and repairs known upstream issues under user consent, and implements a personalized fan-out search strategy that floats priority knowledge bases to the top. + +**When to use:** +- Users mention IMA, 腾讯 IMA, ima.qq.com, or need to install the official ima-skill +- Users report `Skipped loading skill(s) due to invalid SKILL.md` warnings related to ima-skill +- You need to search across IMA knowledge bases with KB-priority boosting +- You need to configure or rotate IMA API credentials +- Upstream ima-skill ships a known issue (e.g., missing YAML frontmatter in submodule files) + +**Key features:** +- Zero-config installation to Claude Code / Codex / OpenClaw via [vercel-labs/skills](https://github.com/vercel-labs/skills) with auto-detection and default symlink mode (fix or upgrade once, every agent sees it) +- XDG-style credential management at `~/.config/ima/{client_id, api_key}` with env-var fallback +- `scripts/diagnose.sh` read-only health check (install presence, credential liveness, known issues) +- `scripts/search_fanout.py` client-side cross-KB search with priority lists, subset-skip lists, and 100-hit silent-truncation detection +- Wrapper-only architecture: never vendors upstream files, never forks — every repair is a runtime instruction executed with explicit consent and automatic timestamped backups +- Two user-selectable repair strategies for the frontmatter issue (rename to `MODULE.md` or prepend minimal frontmatter) +- Personalization via `~/.config/ima/copilot.json` with illustrative-only template values + +**Example usage:** +```bash +# Install the skill +claude plugin install ima-copilot@daymade-skills + +# Then ask Claude to drive the flow +"Install ima-skill and configure my IMA API key" +"Run diagnose on my ima-skill and fix whatever is broken" +"Search my IMA knowledge bases for embedding model comparisons, priority to my curated KB" +``` + +**🎬 Live Demo** + +*Coming soon* + +📚 **Documentation**: See [ima-copilot/SKILL.md](./ima-copilot/SKILL.md) and [ima-copilot/references/known_issues.md](./ima-copilot/references/known_issues.md). + +**Requirements**: Node.js 18+ (for `npx skills`), `curl`, `unzip`, Python 3.6+. IMA OpenAPI credentials from [https://ima.qq.com/agent-interface](https://ima.qq.com/agent-interface). + +--- + +### 45. **claude-export-txt-better** - Fix Claude Code Export Formatting + +> **Install**: `claude plugin install daymade-claude-code@daymade-skills` (suite-only — invoked as `daymade-claude-code:claude-export-txt-better`) + +Reconstruct broken line wrapping in Claude Code exported `.txt` conversation files. Rebuilds tables, paragraphs, paths, and tool calls that were hard-wrapped at fixed column widths, and ships with an automated 53-check validation suite (file-agnostic, catches over- and under-merging regressions). + +**When to use:** +- Users have a Claude Code export file where tables, paths, or tool output got mangled by line wrapping +- Users mention "fix export", "fix conversation", "make export readable" +- Users reference a file matching `YYYY-MM-DD-HHMMSS-*.txt` +- Users want to post-process `/export` output before sharing or archiving it + +**Key features:** +- Deterministic Python script (`fix-claude-export.py`) with `--stats` mode for before/after metrics +- 53-check automated validator (`validate-claude-export-fix.py`) that catches regressions +- Evals directory with real fixture cases +- No external dependencies beyond `uv` and Python 3.8+ + +**Example usage:** +```bash +# Fix and show stats +uv run daymade-claude-code/claude-export-txt-better/scripts/fix-claude-export.py broken.txt --stats + +# Custom output path +uv run daymade-claude-code/claude-export-txt-better/scripts/fix-claude-export.py broken.txt -o fixed.txt + +# Validate the fix +uv run daymade-claude-code/claude-export-txt-better/scripts/validate-claude-export-fix.py broken.txt fixed.txt +``` + +**🎬 Live Demo** + +*Coming soon* + +📚 **Documentation**: See [claude-export-txt-better/SKILL.md](./daymade-claude-code/claude-export-txt-better/SKILL.md) and the bundled `evals/` fixtures. + +**Requirements**: Python 3.8+, `uv` package manager. + +--- + +### 46. **douban-skill** - Douban Collection Export & Sync + +Export and sync Douban (豆瓣) book / movie / music / game collections to local CSV files via the reverse-engineered Frodo API. Full export covers all history; RSS incremental sync keeps daily updates current. No login, no cookies, no browser — just a user ID and it works. + +**When to use:** +- Users want to back up their Douban reading/watching/listening/gaming history +- Users mention 豆瓣, douban, 读书记录, 观影记录, 书影音 +- Users need incremental sync of recent Douban activity +- Users want CSV output compatible with Excel (UTF-8 BOM) + +**Key features:** +- Full export of all 4 categories (books/movies/music/games) via Frodo API +- RSS incremental sync for daily updates (last ~10 items per feed) +- Pre-flight user-ID validation (fail-fast on wrong ID) +- UTF-8 BOM CSV output, Excel-compatible, cross-platform +- Bundled troubleshooting log documenting 7 tested scraping approaches and why each failed (Douban PoW challenges block every web-scraping approach — only Frodo API works) +- `.gitleaks.toml` allowlist for the public Android APK credentials + +**Example usage:** +```bash +# Full export of user's collections +uv run douban-skill/scripts/douban-frodo-export.py + +# Incremental RSS sync (last ~10 items per category) +uv run douban-skill/scripts/douban-rss-sync.py +``` + +**🎬 Live Demo** + +*Coming soon* + +📚 **Documentation**: See [douban-skill/SKILL.md](./douban-skill/SKILL.md) and [douban-skill/references/troubleshooting.md](./douban-skill/references/troubleshooting.md) for the complete failure log of rejected approaches. + +**Requirements**: Python 3.8+, `uv` package manager. No login or cookies required. + +--- + +### 47. **terraform-skill** - Terraform Operational Traps + +Failure patterns from real Terraform deployments — every item caused an actual incident. Organized as *exact error → root cause → copy-paste fix*. Covers provisioner timing races, SSH connection conflicts, multi-environment isolation, DNS record duplication, volume permissions, database bootstrap gaps, snapshot cross-contamination, Cloudflare credential format errors, hardcoded domains in Caddyfiles/compose, and init-data-only-on-first-boot pitfalls. + +**When to use:** +- Writing `null_resource` provisioners or `remote-exec` blocks that SSH into fresh instances +- Setting up multi-environment (prod/staging/dev) Terraform with shared modules +- Debugging containers that are Restarting/unhealthy after `terraform apply` +- Hitting "docker: not found" in remote-exec, rsync connection drops in local-exec, or TLS cert errors +- Troubleshooting drift or provisioner failures during re-runs +- Configuring Caddy/gateway resources with Cloudflare credentials + +**Key features:** +- Copy-paste `.hcl` snippets for each trap, not abstract advice +- Coverage spanning cloud-init, Docker, file provisioners, DNS, TLS, snapshots, and cross-env contamination +- Every pattern tagged with the exact symptom so grep finds it fast + +**Example usage:** +```bash +# Trigger the skill naturally during Terraform work +"I'm getting 'docker: not found' in my null_resource provisioner after apply" +"My rsync local-exec is failing with 'connection unexpectedly closed'" +"Help me write a multi-env Terraform setup without snapshot cross-contamination" +``` + +**🎬 Live Demo** + +*Coming soon* + +📚 **Documentation**: See [terraform-skill/SKILL.md](./terraform-skill/SKILL.md) and the bundled `references/` for detailed remediation patterns. + +**Requirements**: None (Terraform-adjacent knowledge only; no runtime dependencies). + +--- + +### 48. **slides-creator** - Narrative-First Slide Deck Creation + +Guides users through structured narrative design (ABCDEFG model), then delegates visual generation to `baoyu-slide-deck`. Focuses on what machines can't do — narrative co-design with humans. + +**When to use:** +- Creating presentations, slide decks, or PPTs from user content +- Turning articles, transcripts, or notes into visual slides +- Designing narrative arcs for talks and workshops + +**Key features:** +- Phase 0: Source material collection (user's own words first) +- Phase 1: Narrative structure discussion using ABCDEFG model +- Phase 2: Content structuring for machine-readable input +- Phase 3-5: Delegates visual generation to baoyu-slide-deck +- Phase 6: Post-processing with directory reorganization and speaker notes extraction + +**Example usage:** +```bash +# Trigger the skill naturally +"Help me turn my article into a slide deck" +"Create a presentation from my talk transcript" +"I need a 20-minute deck for a workshop" +``` + +**Requirements**: baoyu-slide-deck skill for visual generation. + +--- + +### 49. **debugging-network-issues** - Evidence-Driven Network Investigation + +Falsification-first methodology for network, streaming, and protocol-layer bugs where the obvious cause is probably wrong. Built from a real 5-hour SSE incident where assumption-stacking wasted hours that a 10-minute layered experiment would have resolved. + +**When to use:** +- Connection resets (`ECONNRESET`, HTTP/2 `RST_STREAM`, `INTERNAL_ERROR`) +- SSE / long-polling stalls or fixed-time drops (60s, 100s, 130s) +- CDN / proxy / CGNAT idle-timeout incidents +- Any "works sometimes / fails after N seconds" pattern +- Multi-hop systems (client → CDN → LB → reverse proxy → app → upstream) where a symptom could plausibly come from several layers + +**Key features:** +- Layered isolation experiments: run the same logical request through three or more paths differing by exactly one hop +- Env-gated runtime instrumentation patterns (no production-code mutation) +- Counter-review four-question filter to challenge single-cause assumptions +- Bundled probe scripts (`layered-isolation-probe.sh`, `mock-idle-upstream.py`) +- Real case study: SSE RST_STREAM at 130s caused by CGNAT idle timeout + +**Requirements**: None (methodology + portable shell/Python probes). + +--- + +### 50. **stepfun-tts** - StepFun StepAudio 2.5 Contextual TTS + +> **Install**: `claude plugin install daymade-audio@daymade-skills` (suite-only — invoked as `daymade-audio:stepfun-tts`) + +Generate Chinese / Japanese speech with `stepaudio-2.5-tts`. Captures the two non-obvious TTS pitfalls that cost hours otherwise: `voice_label` removal (replaced by natural-language `instruction`) and stricter 2.5-era censorship (死/消失/political terms). + +**When to use:** +- Chinese / Japanese TTS with emotional and prosody control (whisper, pause, stress, mid-sentence pivot) +- Batch-generating game / app voice lines with per-line `censorship_block` fallback +- Migration from `step-tts-2` to `stepaudio-2.5-tts` (`voice_label` → `instruction` breaking change) +- Hitting StepFun censorship blocks on previously-fine content + +**Key features:** +- `stepaudio-2.5-tts` with `instruction` (≤200 chars natural-language mood) + inline `()` prosody +- Bundled `tts_generate.py` (with `--batch `) and `ab_compare.sh` +- API key resolution: `$STEPFUN_API_KEY` → `${CLAUDE_PLUGIN_DATA}/config.json` fallback +- Censorship rewrite playbook in `references/migration_from_v2.md` + +**Requirements**: StepFun API key, "Normal" tier (https://platform.stepfun.com/). For ASR / transcription, use the sibling `stepfun-asr` skill below. + +--- + +### 52. **stepfun-asr** - StepFun StepAudio 2.5 ASR (SSE Endpoint) + +> **Install**: `claude plugin install daymade-audio@daymade-skills` (suite-only — invoked as `daymade-audio:stepfun-asr`) + +Transcribe Chinese / English audio with `stepaudio-2.5-asr`. Hides the #1 trap of the 2.5 ASR family: it does NOT live on `/v1/audio/transcriptions` — the wrong endpoint returns a misleading `model stepaudio-2.5-asr not supported` error that looks identical to a permission/whitelist failure. + +**When to use:** +- Long audio transcription (up to ~30 minutes single-call, 32K context, ~85-101× RTF — no client-side chunking) +- Migration from `step-asr` / `step-asr-1.1` (different endpoint, different body shape, SSE response) +- Hitting the misleading `model stepaudio-2.5-asr not supported` error (= wrong endpoint, not permission) +- Silent 4xx auth failures on audio endpoints (= using a "Plan" key instead of a "Normal" key) + +**Key features:** +- `/v1/audio/asr/sse` SSE streaming with base64 audio + nested JSON body (the script handles all four traps) +- Bundled `asr_transcribe.py` — pure-stdlib CLI, auto-detects mp3/wav/ogg/opus/pcm by extension +- Handles SSE `error` events (censorship can fire on ASR side too — rare but real) +- API key resolution: `$STEPFUN_API_KEY` → `${CLAUDE_PLUGIN_DATA}/config.json` fallback +- Suggests `transcript-fixer` (ASR error correction) and `meeting-minutes-taker` (structured minutes) as natural downstream skills + +**Requirements**: StepFun API key, "Normal" tier (https://platform.stepfun.com/). Plan keys cannot call audio endpoints. + +--- + +### 53. **auto-repo-setup** - Automated Repository Setup & Environment Repair + +Turn "it won't run" into "it's running" without requiring users to understand git, uv, ffmpeg, or API keys. Designed for non-technical teammates (editors, business, ops) who need to clone a repo and get it working — and for technical users who want standardized, handoff-ready project onboarding. + +**When to use:** +- A non-technical user says "跑不起来", "怎么启动", "环境怎么配", or "帮我设置代码库" +- Setting up a new machine or onboarding a teammate to a codebase +- Configuring SessionStart hooks so Claude Code auto-checks environment on entry +- Sanitizing git history after accidental secret/path leaks +- Handling merge conflicts or git push failures for users who don't use git daily + +**Key features:** +- **ONBOARDING.md-first workflow**: reads the project's guide, validates each step, fixes gaps iteratively +- **SessionStart hook generator**: one-command `init_session_start_hook.py` sets up auto-environment-check on every Claude Code session entry +- **Safety guardrails**: Push Safety (visibility verification before any push), PII Guard (4-layer secret scanning), NO FALLBACK principle for env vars, Git Hook Bypass ban +- **Counter-review workflow**: multi-agent security/code-quality/devops/doc review for significant changes +- **Bundled scripts**: `check_env.py` (audit git/ffmpeg/uv/python/.env), `sanitize_history.sh` (scan history for secrets/paths/domains), `init_session_start_hook.py` + +**Example usage:** +```bash +# Install the skill +claude plugin install auto-repo-setup@daymade-skills + +# Then ask Claude naturally +"我跑不起来这个仓库" +"帮我设置一下这个项目的环境" +"初始化 SessionStart hook" +"git push 被拒了" +``` + +**Requirements**: Python 3.8+, `uv` package manager. No external API keys required for the skill itself. + +--- + +### 54. **terminal-screenshot** - See the Real Visual Result of Terminal Output + +Render a terminal CLI program's colored output to a PNG so Claude can actually *see* the rendered result — color contrast, alignment, background blocks, highlighting — instead of only reading plain text and raw ANSI escape codes. Reading a hex value is guessing; seeing the rendered contrast on the real terminal background is verification. + +**When to use:** +- Right after changing any CLI color config (delta / bat / themes / lazygit pager) to visually confirm the result +- Verifying git diff (delta) add/remove contrast, bat syntax highlighting, starship prompt, eza/ls colors, ripgrep matches +- Any time you need to judge "does this color look right / is the contrast enough" instead of guessing from hex codes + +**Key features:** +- **Capture-then-render discipline**: captures full-fidelity ANSI in a normal shell first, then renders — never lets the renderer run complex CLIs (which degrade in a child pty and drop background blocks) +- **freeze-first, zero-dependency fallback**: prefers charmbracelet/freeze for faithful rendering; falls back to a bundled stdlib ANSI→HTML converter + headless Chrome when freeze is unavailable +- **Real terminal background**: renders on the actual terminal background color so dark themes are judged accurately +- **Per-CLI capture recipes**: delta, git, bat, eza, ls, ripgrep, and a generic forced-color path +- **Bundled scripts**: `render_ansi.sh` (freeze/Chrome auto-select), `ansi2html.py` (stdlib renderer) + +**Example usage:** +```bash +# terminal-screenshot lives in the daymade-claude-code suite +claude plugin install daymade-claude-code@daymade-skills + +# Then ask Claude naturally +"verify my delta diff colors" +"看一下这个终端配色的真实效果" +"is the add/remove contrast in git diff strong enough?" +``` + +**Requirements**: macOS. `charmbracelet/freeze` (preferred renderer) or Google Chrome (fallback). Python 3 for the fallback renderer. + +--- + +### 55. **pdf-to-html** - Read a PDF as Faithful HTML (with Optional Translation) + +Convert a PDF into one self-contained, readable HTML file that preserves images, charts and reading order — optionally translating it into another language while keeping every figure. A PDF is a layout, not just a text stream, so the workflow renders each page for you to *see* before building, and renders the HTML for visual verification before delivery. + +**When to use:** +- Reading a PDF as a clean web page or document (especially on a phone) +- Turning a report or whitepaper PDF into styled HTML without losing its figures +- Translating a PDF into another language while keeping its images, charts and tables in place + +**Key features:** +- **Structured extraction** (PyMuPDF): text blocks with font sizes + images, with decorative images (footer logos, rules) auto-detected and dropped +- **Data-driven build**: heading levels inferred from font size, content images compressed and base64-inlined into one portable file +- **Optional parallel translation**: a Dynamic Workflow translates pages concurrently, captions data charts, and reconciles terminology — with fidelity rules (never invent a translated name; copy numbers and proper nouns verbatim) +- **Mandatory visual verification**: adaptive headless-Chrome screenshot sliced into readable segments (works around Chrome's ~16384px screenshot cap) +- **Bundled failure-cases reference**: the real traps (verification, rendering limits, fidelity) so they are not re-discovered + +**Example usage:** +```bash +# pdf-to-html lives in the daymade-docs suite +claude plugin install daymade-docs@daymade-skills + +# Then ask Claude naturally +"把这个 PDF 转成中文网页版" +"make this report readable as HTML" +"translate this PDF to English but keep the charts" +``` + +**Requirements**: `uv`, Google Chrome or Chromium (visual verification). Python packages (PyMuPDF, Pillow, numpy) auto-install via `uv run --with`. + +--- + +### 56. **asr-transcribe-to-text** - Audio/Video Transcription with Qwen3-ASR + +> **Install**: `claude plugin install daymade-audio@daymade-skills` (suite-only — invoked as `daymade-audio:asr-transcribe-to-text`) + +Transcribe audio and video files to text using Qwen3-ASR via two interchangeable inference paths: local MLX on macOS Apple Silicon (no API key, 15-27x realtime) or a remote vLLM/OpenAI-compatible API for any platform. Auto-detects the platform and recommends the best path, persisting the choice in `${CLAUDE_PLUGIN_DATA}/config.json`. + +**When to use:** +- Transcribing meeting recordings, lectures, interviews, podcasts, or screen recordings +- Converting any audio/video file to text (speech-to-text) +- Local, free transcription on an Apple Silicon Mac, or remote API when local is unavailable +- The first stage of a transcribe → correct → minutes pipeline + +**Key features:** +- Dual inference paths — local MLX (15-27x realtime, free) and remote API, with automatic platform detection +- Bundled `transcribe_local_mlx.py` loads the model once and processes files sequentially (no GPU contention) +- Defaults `max_tokens=200000` to defeat the upstream `mlx-audio` 8192-token truncation that silently cuts audio past ~40 minutes +- Remote fallback `overlap_merge_transcribe.py` splits into 18-minute chunks with 2-minute overlap and fuzzy-merges +- ffmpeg video→16kHz mono WAV extraction, truncation verification, and proxy-bypass handling +- Proactively suggests `transcript-fixer` to clean ASR recognition errors on the output + +**Example usage:** +```bash +# asr-transcribe-to-text lives in the daymade-audio suite +claude plugin install daymade-audio@daymade-skills + +# Then ask Claude naturally +"transcribe this meeting recording to text" +"把这个录音转成文字" +"convert lecture.mp4 to a transcript" +``` + +**Requirements**: `uv`, ffmpeg/ffprobe. Local MLX path needs macOS Apple Silicon; remote path needs a reachable vLLM/OpenAI-compatible ASR endpoint. No API key for local mode. + +--- + +### 57. **marketplace-dev** - Skills Repo → Plugin Marketplace + +> **Install**: `claude plugin install daymade-claude-code@daymade-skills` (suite-only — invoked as `daymade-claude-code:marketplace-dev`) + +Convert any Claude Code skills repository into an official plugin marketplace so users can install skills via `claude plugin marketplace add` and get auto-updates. Generates a spec-conforming `.claude-plugin/marketplace.json`, validates with `claude plugin validate`, tests real installation, and opens an upstream PR — encoding hard-won schema, version, and description anti-patterns. + +**When to use:** +- Making a skills repo installable via `claude plugin install` +- Generating or fixing a `marketplace.json` (plugin distribution, one-click install, auto-update) +- Adding a new plugin to an existing marketplace and bumping the right versions +- Debugging schema rejections like `Unrecognized key: "$schema"` or duplicate plugin names + +**Key features:** +- Evidence-intake phase that mines docs and local session history instead of guessing from a template +- Encodes non-obvious schema rules: `$schema` is rejected, `metadata` has only 3 valid fields, `strict: false` semantics, single-skill vs suite `source`/`skills` patterns +- Bundled `check_marketplace.sh` runs four checks (JSON syntax → `claude plugin validate` → source/skills resolution → reverse sync) and exits non-zero on failure +- Installation, cache-footprint, and GitHub-install test recipes to confirm `source` produced the intended snapshot +- Two PostToolUse hooks (validate on `marketplace.json` edit; warn on un-bumped version when a `SKILL.md` changes) that auto-activate with the plugin + +**Example usage:** +```bash +# marketplace-dev lives in the daymade-claude-code suite +claude plugin install daymade-claude-code@daymade-skills + +# Then ask Claude naturally +"turn this skills repo into a plugin marketplace" +"generate a marketplace.json for this repo and validate it" +"add my new skill to the marketplace and open a PR" +``` + +**Requirements**: `claude` CLI (for `claude plugin validate` / install tests), `jq`. Git remotes configured if opening an upstream PR. + +--- + +### 58. **skill-creator** - Create, Improve & Benchmark Skills + +> **Install**: `claude plugin install daymade-skill@daymade-skills` (suite-only — invoked as `daymade-skill:skill-creator`) + +The essential meta-skill for building your own skills. Guides the full create → test → review → improve loop: drafts a SKILL.md, generates realistic test prompts, runs the skill against a baseline, helps evaluate results qualitatively and quantitatively, and iterates. Also optimizes a skill's `description` for better triggering accuracy. + +**When to use:** +- Creating a skill from scratch, or editing/optimizing an existing one +- Running evals to test a skill, or benchmarking performance with variance analysis +- Improving a skill's description so Claude triggers it more reliably +- Wrapping a third-party CLI tool you just got working into a reusable companion skill + +**Key features:** +- Prior-art research across conversation history, local SOPs, installed plugins/MCPs, skills.sh, official plugins, npm/PyPI — to reuse infrastructure and encode only the user's unique methodology +- The inline-vs-`context: fork` decision guide (subagents can't spawn subagents or call skills) and composable/orthogonal skill design +- `init_skill.py` scaffolding, `package_skill.py` (auto-validates), and `security_scan.py` (gitleaks-based secret/PII detection) +- Eval harness: spawn with-skill + baseline runs, draft assertions, grade, aggregate a benchmark, and review in a generated HTML viewer +- Mandatory sanitization read-through for public skills — catches no-keyword leaks scanners miss +- Description-optimization loop (60/40 train/test split, selects best description by held-out score) + +**Example usage:** +```bash +# skill-creator lives in the daymade-skill suite +claude plugin install daymade-skill@daymade-skills + +# Then ask Claude naturally +"create a skill that does X" +"improve this skill's description so it triggers more reliably" +"benchmark this skill against a no-skill baseline" +``` + +**Requirements**: Python 3, `uv`, PyYAML (validation/packaging), gitleaks (security scan). `claude` CLI for eval/description-optimization runs. + +--- + +### 59. **feishu-doc-scraper** - Feishu/Lark → Faithful Markdown + +Extract Feishu (Lark) Docs, Wiki pages/collections, spreadsheets, and Minutes (妙记) transcripts into faithful local Markdown. The primary path uses the `lark-cli` API — it extracts the document body programmatically (no model paraphrasing), recursively follows a collection's reference graph, and reads permission boundaries from error codes; a browser-DOM path is the fallback only when lark-cli cannot reach the content. + +**When to use:** +- The source is a Feishu/Lark URL and fidelity matters (导出飞书文档/合集/妙记转写) +- Converting a Feishu wiki/knowledge base to Markdown, or archiving a Feishu collection +- Exporting a Feishu Minutes (妙记) transcript +- Converting an owner-exported `.docx` into faithful Markdown with heading/highlight restoration + +**Key features:** +- lark-cli API extraction writes the body to disk via `jq` (never retyped by the model — the single most important fidelity rule) +- Recursive reference-graph traversal (BFS) with `feishu_extract_refs.py`, plus a residual rich-media-tag acceptance gate so no referenced doc is silently missed +- Native Minutes transcript export (never re-runs ASR on downloaded media) +- Permission-denied path: owner-exported `.docx` → Markdown with font-size→heading and `w:shd`→highlight restoration, then visual verification +- `LARK_CLI_NO_PROXY=1` discipline for `*.feishu.cn` (avoids credential leak/DNS hijack) and a U+FFFD encoding-corruption final check +- Works with both Feishu (feishu.cn) and Lark (larkoffice.com) + +**Example usage:** +```bash +# Install the skill +claude plugin install feishu-doc-scraper@daymade-skills + +# Then ask Claude naturally +"把这个飞书合集导出成 markdown" +"export this Feishu Minutes transcript" +"save this Lark wiki page as Markdown" +``` + +**Requirements**: `lark-cli` binary (npm `@larksuite/cli`) authenticated to the target tenant; `jq`. Fallback path needs a browser-automation surface; the docx path needs `python-docx` and a docx→md converter (the bundled doc-to-markdown skill or pandoc). + +--- + +### 60. **bigdata-skill** - Bigdata.com (RavenPack) SDK + REST Toolkit + +Pull Bigdata.com (RavenPack) financial and news data through the official `bigdata-client` SDK and its public `/v1/*` REST endpoints — reaching the structured substrate the Bigdata MCP server doesn't hand over. The MCP returns prose chunks and pre-synthesized tearsheets; this toolkit reaches structured financials, prices, analyst estimates, a daily entity-sentiment series, annotated chunk search with sentiment + entity spans, and a screener. + +**When to use:** +- Using Bigdata.com / RavenPack and the MCP result feels thin ("where's the sentiment score?", "I need entity-level data", "the calendar") +- Pulling forward/structured financials: analyst estimates, earnings/event calendar, surprises, ratings, price targets, statements, TTM metrics, a company screener +- Wanting annotated news chunks with numeric sentiment + entity spans, a sentiment time series, or a co-mention graph +- Mentions a `bd_v2_` API key, `rp_entity_id`, `query_unit`/chunk cost, `bigdata-client`, or "the bigdata MCP isn't enough" + +**Key features:** +- One `BigdataClient` exposing both the SDK (search + knowledge graph) and a REST escape hatch (`bd._api.http`) for every `/v1/*` endpoint the SDK never wrapped +- Routing table mapping each question to the right module; `fields_values_to_records()` to flatten `{fields, values}` responses +- Cost discipline: `1 query_unit = 10 chunks`, only chunk-search billed, `ChunkLimit` (never a bare `int`), rerank thresholds, 50%-cheaper batch search, and a `CostModel`/`CostTracker` budget veto +- The "two data faces" guidance — structured financial (works for A-shares via English name/ISIN) vs unstructured Chinese NLP (a data-source-level dead end) +- `rc()` SSL-retry wrapper for the common first-handshake `SSL: UNEXPECTED_EOF`, plus a known-pitfalls reference with reproductions and fixes +- Fail-fast on a missing `BIGDATA_API_KEY` (no plaintext fallback); read-only, never writes/uploads + +**Example usage:** +```bash +# Install the skill +claude plugin install bigdata-skill@daymade-skills +export BIGDATA_API_KEY=bd_v2_xxxxxxxx + +# Then ask Claude naturally +"pull NVIDIA's forward analyst estimates and last earnings surprise from Bigdata" +"give me a daily entity-sentiment series for this ticker" +"the bigdata MCP only gave me a tearsheet — I need the structured fields" +``` + +**Requirements**: A `bd_v2_` Bigdata.com API key (env var, never hardcoded), `uv`, the official `bigdata-client` SDK in an isolated venv. Optional outbound/WSS proxy only if your network needs one to reach `api.bigdata.com`. + +--- + +### 61. **gangtise-copilot** - Gangtise Investment-Research Suite Installer + +One-command installer, credential configurator, and diagnostic layer for the full Gangtise (岗底斯投研) OpenAPI skill suite. Installs all 19 official Gangtise skills (data, research, utility), configures accessKey/secretAccessKey with a live auth check, and runs a read-only health diagnostic — solving the suite's core discoverability problem (no public manifest, listing-disabled OBS bucket, two parallel naming lines). + +**When to use:** +- The user mentions Gangtise / 岗底斯, or any `gangtise-*` skill +- Setting up Gangtise credentials (accessKey / secretAccessKey) +- Errors like `token is invalid` / `接口地址错误`, or "my gangtise install is broken" +- Routing a data question (research reports, chief-analyst opinions, OHLC, valuation) to the right Gangtise skill + +**Key features:** +- `install_gangtise.sh` downloads 4 OBS bundles → extracts 19 skill directories → symlinks them into detected agent skills dirs (Claude Code, OpenClaw, Codex), with `minimal`/`workshop`/`full`/`--only` presets +- `configure_auth.sh` writes one shared XDG credential file (mode 600), runs a live auth call, and symlinks every skill's `.authorization` to it (rotate one file, not 19) +- Read-only `diagnose.sh` reports install state, credential validity, and scoped capability tiers (auth scope vs RAG scope) +- Skill registry routing a data question across the two-dimensional (data tier × operation type) matrix of 19 skills +- Wrapper contract: never vendors/forks upstream files, always re-downloads the canonical OBS artifact, and asks before touching any installed skill + +**Example usage:** +```bash +# Install the skill +claude plugin install gangtise-copilot@daymade-skills + +# Then ask Claude naturally +"装一下 gangtise 的所有 skill 并配置好凭据" +"my gangtise skills report token is invalid — diagnose it" +"宁德时代的研报用哪个 gangtise skill 查" +``` + +**Requirements**: A Gangtise accessKey + secretAccessKey; `bash`, `curl`, network access to the official OBS bucket and `open.gangtise.com`. Works with Claude Code, OpenClaw, and Codex agent layouts. + +--- + +### 62. **llm-wiki-setup** - Co-Create a Personal Investment-Research LLM Wiki + +Co-create a personal investment-research LLM Wiki (Andrej Karpathy's pattern) where the user's OWN analysis framework becomes a living CLAUDE.md — built by interviewing them rather than handing over a template. Pure markdown + `[[wikilinks]]`, NO RAG / vector DB (Karpathy's core idea — do not over-engineer). The value is extracting the user's personal investment preferences into THEIR OWN schema, never imposing a standard one. + +**When to use:** +- Building a compounding research knowledge base (投研第二大脑 / 投研知识库 / 个人投研 wiki) +- Instantiating Karpathy's LLM Wiki pattern for finance/investing +- Turning a stock-picking, analyst-tracking, or earnings-watching workflow into a structured markdown vault +- Ingesting research reports / earnings calls / expert notes into an existing wiki, or running post-earnings prediction→fulfillment reviews + +**Key features:** +- Sharp mechanism-layer vs rule-layer split: the three-level directory + wikilink + lint + git hook scaffold is copyable; the analysis schema is interview-grown, never templated +- `init_vault.py` scaffolds the mechanism layer only (no schema), then an 8-dimension interview builds the user's own CLAUDE.md in their own words +- Anti-corrosion: git hook + `lint-vault.py` keep the vault consistent and fight derived-value drift +- SOPs for ingesting a real source (HITL 5-checkpoint flow) and post-earnings fulfillment reviews +- Runs inline (calls the `analyst-track-record` skill and Bash) and chains into `analyst-track-record` for analyst back-testing — without rebuilding it + +**Example usage:** +```bash +# Install the skill +claude plugin install llm-wiki-setup@daymade-skills + +# Then ask Claude naturally +"帮我搭一个投研第二大脑" +"build me a personal investment-research wiki in Karpathy's style" +"ingest this earnings call into my research vault" +``` + +**Requirements**: Python 3, `uv` (for `init_vault.py` / lint), `git`. Markdown + wikilinks only — no vector DB or embedding service. Pairs with the `analyst-track-record` skill for back-testing. + +--- + +### 63. **benchmark-due-diligence** - Adversarial Teardown of an Envied Benchmark + +Run adversarial due-diligence on a benchmark the user envies — a founder, KOL, company, or product whose claimed success looks inflated — separating marketing bubble from real signal, then mapping the validated playbook onto the user's own resources. The adversarial, decision-oriented cousin of `deep-research`: it assumes the picture is inflated until proven otherwise and ends in "what this means for ME", not a neutral report. + +**When to use:** +- Wanting to 尽调/对标/拆解 a competitor or role-model, or 抄/偷师 someone's playbook +- Suspecting 水分/泡沫 in someone's claims (#1 on Product Hunt, 0-to-1M users, funding, 估值几个亿) +- Asking whether wins are 真本事 vs 运气/时机, or saying someone is 太成功了 and wanting the real story +- Preferring a debunk + replicable playbook over `deep-research`'s neutral briefing + +**Key features:** +- Two strictly-separated injection channels — public FACTS go to every agent; private COMMISSIONER_CONTEXT reaches only the final mapping agent (so client names never leak into open-web searches) +- Phase 0 foundation-by-evidence: verifies the benchmark's real entity graph and headline-claim attribution before any fan-out (don't reason from names/domains) +- Four-phase orchestration — collect → adversarial verify (L1-L4 grading, `坐实/存疑/证伪-水分` verdicts) → due-diligence conclusion (bubble-busting table + attribution breakdown) → commissioner resource-mapping +- Reuses existing plumbing instead of rebuilding it (`deep-research` fan-out, `osint-investigate` identity checks, the `qcc` family for 工商 data, `agent-reach` for social-platform data) +- Runs inline (it's an orchestrator — `context: fork` would silently break the fan-out) + +**Example usage:** +```bash +# Install the skill +claude plugin install benchmark-due-diligence@daymade-skills + +# Then ask Claude naturally +"帮我尽调一下这个创始人，他到底有没有水分" +"tear down this competitor's playbook and tell me what I can actually copy" +"this KOL claims 0-to-1M users — is that real, and is it replicable for me?" +``` + +**Requirements**: Web access for the collection/verification agents. Optionally composes with `deep-research`, `osint-investigate`, the `qcc` skill family, and `agent-reach`; renders a shareable report via `pdf-creator`. + +--- + +### 64. **bilibili-source** - Login-Free Bilibili Video Data + Danmaku Fetcher + +Fetch real, citable data for any Bilibili (B站) video — title, UP follower count, publish date, tags, partition, per-part cids, live stats (view/like/coin/favorite/share/reply/danmaku), and full danmaku (bullet-comment) text — in one `view/detail` call, login-free. Built so engagement numbers are cheap to fetch and impossible to fake, instead of hand-typed into a doc where they rot. + +**When to use:** +- Ingesting a Bilibili video into a knowledge base, or building a "why did this perform" case study +- Verifying a creator's claimed view/like/favorite numbers, or about to write any B站 metric into a document +- Wanting the danmaku text (qualitative audience reactions), not just a reply count +- Pasting a BVID, `av` number, `b23.tv` short link, or full URL — all normalized automatically + +**Key features:** +- One `bili-fetch.sh` returns full metadata + live stats + UP fans + tags + every part's cid; metrics carry a `fetched_at` timestamp because they drift in real time +- `bili-danmaku.sh` pulls and decompresses the danmaku full text; `bili-subs.sh` handles the login-gated subtitle track (asks before touching browser cookies) +- `bili-selftest.sh` health-check verifies every endpoint against the live API, so API drift surfaces as one clear FAIL instead of a silent wrong answer +- NO-FABRICATION discipline: an unfetchable number is marked unverified, never estimated +- Strips the local proxy (Bilibili is a domestic CN service), sends UA+Referer (avoids HTTP 412), retries with backoff +- API reference includes the WBI request-signing algorithm for `space/wbi/*` extension + +**Example usage:** +```bash +# Install the skill +claude plugin install bilibili-source@daymade-skills + +# Then ask Claude naturally +"pull the real view/like/favorite counts for this B站 video so I can cite them" +"这个 B站 视频弹幕里大家在说什么？" +"grab the subtitle transcript from this bilibili video so I can summarize it" +``` + +**Requirements**: `curl`, `jq`, `python3` (danmaku decompression). `yt-dlp` only for the login-gated subtitle path. No login for stats / metadata / danmaku. + +--- + +### 65. **claude-usage-analyst** - Explain Claude Code Token Usage & Quota Burn + +> **Install**: `claude plugin install daymade-claude-code@daymade-skills` (suite-only — invoked as `daymade-claude-code:claude-usage-analyst`) + +Turn local `ccusage` data into an evidence-based, human-readable explanation of where your Claude Code / Claude Desktop tokens, cost, and quota went — separating observed numbers from interpretation instead of guessing. + +**When to use:** +- Asking why a Claude quota or 5-hour block got exhausted +- Wondering whether a model (`fable` / `opus` / `sonnet`) is unusually expensive for your workload +- Needing today's or a historical window's token/cost breakdown, including cache read/write pressure +- Explaining usage to a non-technical reader without unexplained jargon + +**Key features:** +- Bundled `analyze_claude_usage.py` summarizes tokens, cost, input/output, and cache create/read over any date window and timezone +- Model-comparison mode (`--model-a` / `--model-b`) weighs both token volume and estimated cost — a model can be cheap per token but expensive overall +- A 5-hour-block table for quota-exhaustion questions +- Evidence discipline: every numeric claim is grounded in `ccusage` output; cache-read pressure is counted even when you never typed those tokens +- Scope is stated explicitly: `ccusage claude` measures local Claude Code logs, not a full Claude.ai chat bill + +**Example usage:** +```bash +# Install the suite +claude plugin install daymade-claude-code@daymade-skills + +# Then ask Claude naturally +"why did my Claude quota run out today?" +"is opus more expensive than sonnet for what I'm doing?" +"break down my Claude Code token usage for this month" +``` + +**Requirements**: `ccusage` (via `npm i -g ccusage` or `npx ccusage@latest`), `python3`. + +--- + +### 66. **marketplace-health-check** - Full 6-Dimension Repo Health Check + +```bash +claude plugin install marketplace-health-check@daymade-skills +``` + +Run a comprehensive, evidence-based health check of this skills marketplace repo with a parallel fan-out Dynamic Workflow — six inspectors cover code/script safety, documentation/SSOT consistency, security/PII leaks, open-PR triage, open-issue triage, and marketplace-manifest integrity at once — then the serious findings are Counter-Reviewed before they reach the report. + +**When to use:** +- Before a release, or any time you want a full "is this whole repo OK across the board" sweep +- Checking whether docs/versions are consistent, PRs/issues are triaged, or PII has leaked into a public skill +- 全面体检 / 检查仓库状态 / 审计一下仓库 + +**Key features:** +- Six parallel inspectors (one per dimension) via a Dynamic Workflow — fast and focused (~15-20 min) +- Counter-Review: every high/critical finding is verified by hand before it reaches the report (agent findings are hypotheses, not conclusions) — catches false alarms AND wrong fixes +- Priority-ranked report: must-fix / backlog / optional / key insights, each item tagged real vs false-alarm +- Bundles the proven workflow script + a methodology reference (anti-target PII rule, working-copy-vs-history, scan-marker necessary-not-sufficient, the broken-install-command bug class) +- Inline orchestrator — drives the Workflow tool, so it never runs forked + +**Example usage:** +```bash +# Install +claude plugin install marketplace-health-check@daymade-skills + +# Then ask Claude naturally +"do a full health check of this repo before I cut a release" +"audit the marketplace — code, docs, PII, PRs, issues, everything" +"全面体检一下这个仓库" +``` + +**Requirements**: `gh` CLI (authenticated), `git`, `jq`, `python3`; opt-in to the Workflow tool (asking to run the health check is the opt-in). + +--- + ## 🎬 Interactive Demo Gallery Want to see all demos in one place with click-to-enlarge functionality? Check out our [interactive demo gallery](./demos/index.html) or browse the [demos directory](./demos/). @@ -1759,7 +2610,7 @@ Want to see all demos in one place with click-to-enlarge functionality? Check ou Use **github-ops** to streamline PR creation, issue management, and API operations. ### For Documentation -Combine **markdown-tools** for document conversion and **mermaid-tools** for diagram generation to create comprehensive documentation. Use **llm-icon-finder** to add brand icons. +Combine **doc-to-markdown** for document conversion and **mermaid-tools** for diagram generation to create comprehensive documentation. Use **llm-icon-finder** to add brand icons. ### For Research & Analysis Use **deep-research** to produce format-controlled research reports with evidence tables and citations. Combine with **fact-checker** to validate claims or with **twitter-reader** for social-source collection. @@ -1780,7 +2631,7 @@ Use **repomix-unmixer** to extract and validate repomix-packed skills or reposit Use **skill-creator** (see [Essential Skill](#-essential-skill-skill-creator) section above) to build, validate, and package your own Claude Code skills following best practices. ### For Presentations & Business Communication -Use **ppt-creator** to generate professional slide decks with data visualizations, structured storytelling, and complete PPTX output for pitches, reviews, and keynotes. +Use **ppt-creator** to generate professional slide decks with data visualizations, structured storytelling, and complete PPTX output for pitches, reviews, and keynotes. Use **slides-creator** for narrative-first slide design — it guides you through the ABCDEFG storytelling framework, collects your original content first, then delegates visual generation to baoyu-slide-deck. Perfect when you have existing articles, transcripts, or talks that need to become visual slides. ### For Video Quality Analysis Use **video-comparer** to analyze compression results, evaluate codec performance, and generate interactive comparison reports. Combine with **youtube-downloader** to compare different quality downloads. @@ -1812,6 +2663,12 @@ Use **prompt-optimizer** to transform vague feature requests into precise EARS s ### For Session History & File Recovery Use **claude-code-history-files-finder** to recover deleted files from previous Claude Code sessions, search for specific implementations across conversation history, or track file evolution over time. Essential for recovering accidentally deleted code or finding that feature implementation you remember but can't locate. +### For Resuming Interrupted Claude Sessions +Use **continue-claude-work** to recover the last actionable request from local `~/.claude` artifacts and continue implementation without reopening the original session. Combine with **claude-code-history-files-finder** when you need broader cross-session search, statistics, or deleted-file recovery. + +### For Web Extraction & WeChat Articles +Use **scrapling-skill** to install and validate Scrapling CLI, choose between static and browser-backed fetching, and extract clean Markdown from sites like `mp.weixin.qq.com`. Combine with **deep-research** to turn extracted sources into structured reports or with **docs-cleaner** to normalize captured article content. + ### For Documentation Maintenance Use **docs-cleaner** to consolidate redundant documentation while preserving valuable content. Perfect for cleaning up documentation sprawl after rapid development phases or merging overlapping docs into authoritative sources. @@ -1831,7 +2688,7 @@ Use **iOS-APP-developer** to configure XcodeGen projects, resolve SPM dependency Use **macos-cleaner** to intelligently analyze and reclaim disk space on macOS with safety-first approach. Unlike one-click cleaners that blindly delete, macos-cleaner explains what each file is, categorizes by risk level (🟢/🟡/🔴), and requires explicit confirmation before any deletion. Perfect for developers dealing with Docker/Homebrew/npm/pip cache bloat, users wanting to understand storage consumption, or anyone who values transparency over automation. Combines script-based precision with optional Mole visual tool integration for hybrid workflow. ### For Twitter/X Content Research -Use **twitter-reader** to fetch tweet content without JavaScript rendering or authentication. Perfect for documenting social media discussions, archiving threads, analyzing tweet content, or gathering reference material from Twitter/X. Combine with **markdown-tools** to convert fetched content into other formats, or with **repomix-safe-mixer** to package research collections securely. +Use **twitter-reader** to fetch tweet content without JavaScript rendering or authentication. Perfect for documenting social media discussions, archiving threads, analyzing tweet content, or gathering reference material from Twitter/X. Combine with **doc-to-markdown** to convert fetched content into other formats, or with **repomix-safe-mixer** to package research collections securely. ### For Skill Quality & Open-Source Contributions Use **skill-reviewer** to validate your own skills against best practices before publishing, or to review and improve others' skill repositories. Combine with **github-contributor** to find high-impact open-source projects, create professional PRs, and build your contributor reputation. Perfect for developers who want to contribute to the Claude Code ecosystem or any GitHub project systematically. @@ -1840,7 +2697,7 @@ Use **skill-reviewer** to validate your own skills against best practices before Use **i18n-expert** to set up complete i18n infrastructure for React/Next.js/Vue applications, audit existing implementations for missing translation keys, and ensure locale parity between en-US and zh-CN. Perfect for teams launching products to global markets, maintaining multi-language UIs, or replacing hard-coded strings with proper i18n keys. Combine with **skill-creator** to create locale-aware skills, or with **docs-cleaner** to consolidate documentation across multiple languages. ### For Network & VPN Troubleshooting -Use **tunnel-doctor** to diagnose and fix conflicts between Tailscale and proxy/VPN tools on macOS across four independent layers (route hijacking, HTTP env vars, system proxy, SSH ProxyCommand). Essential when Tailscale ping works but TCP connections fail, when git push fails with "failed to begin relaying via HTTP", or when setting up Tailscale SSH to WSL instances alongside Shadowrocket, Clash, or Surge. +Use **tunnel-doctor** to diagnose and fix conflicts between Tailscale and proxy/VPN tools on macOS across multiple independent layers (route hijacking, HTTP env vars, system proxy, SSH ProxyCommand, VM/container proxy propagation, DNS resolver stall). Essential when Tailscale ping works but TCP connections fail, when git push fails with "failed to begin relaying via HTTP", or when setting up Tailscale SSH to WSL instances alongside Shadowrocket, Clash, or Surge. Also covers **TUN measurement contamination** — why raw probes (`nc -z` showing 0.00s, `ping`, a foreign `ip-api` lookup) lie while a global proxy is up, and what to trust instead. ### For Product Audits Use **product-analysis** for structured pre-release and architecture reviews. It combines UX, API, and architecture analysis into measurable findings with priority-ranked recommendations. Add `compare` mode to benchmark against competitor implementations through evidence-backed reports. @@ -1851,6 +2708,27 @@ Use **windows-remote-desktop-connection-doctor** to diagnose Azure Virtual Deskt ### For Plugin & Skill Troubleshooting Use **claude-skills-troubleshooting** to diagnose and resolve Claude Code plugin and skill configuration issues. Debug why plugins appear installed but don't show in available skills, understand the installed_plugins.json vs settings.json enabledPlugins architecture, and batch-enable missing plugins from a marketplace. Essential for marketplace maintainers debugging installation issues, developers troubleshooting skill activation, or anyone confused by the GitHub #17832 auto-enable bug. +### For Tencent IMA Knowledge Base Workflows +Use **ima-copilot** to install the official Tencent IMA skill across Claude Code / Codex / OpenClaw, configure API credentials, detect and repair known upstream issues, and run personalized fan-out searches across all your IMA knowledge bases with priority-based boosting. The wrapper architecture means upstream upgrades never collide with your fixes — every repair is a runtime instruction, not a shipped patch. Perfect for IMA power users who switch between multiple coding agents, or for anyone who has hit the "Skipped loading skill(s) due to invalid SKILL.md" warning. + +### For Post-Processing Claude Code Exports +Use **claude-export-txt-better** to clean up `/export` output before archiving or sharing. The default export format hard-wraps tables, paths, and tool-call blocks at fixed column widths, which breaks readability in any viewer wider than 80 columns. The skill reconstructs the original structure and validates the fix with 53 automated checks so regressions are caught immediately. + +### For Personal Data Backup (Douban) +Use **douban-skill** to back up your Douban 书影音 (book/movie/music/game) history to CSV. Douban has no official export — the public API was shut down in 2018 and all web scraping is blocked by PoW challenges. This skill uses the same Frodo API as the official Android app, so it just works without any login or cookies. Ships with a full failure log of 7 rejected scraping approaches, saving you hours of wasted effort. + +### For Terraform & IaC Troubleshooting +Use **terraform-skill** when your `terraform apply` fails at a provisioner step, when fresh instances hit "docker: not found", or when multi-environment setups accidentally share snapshots. Every pattern in the skill is an *exact error → root cause → copy-paste fix* triple drawn from real incidents. Perfect for anyone who has lost a weekend to timing races in cloud-init, rsync connection drops in local-exec, or hardcoded domains in Caddyfiles. + +### For Network, Streaming & Protocol-Layer Debugging +Use **debugging-network-issues** when symptoms do not match the obvious cause: HTTP/2 `RST_STREAM`, SSE stalls at exactly 60s/100s/130s, "works sometimes but not always" failures, or anything that looks like an idle-timeout incident through CDN / proxy / CGNAT chains. The skill replaces assumption-stacking with **layered isolation experiments** — running the same logical request through three or more paths that differ by one hop — plus a counter-review pattern for shipping fixes only after the hypothesis has been falsified, not just confirmed. The cognitive-trap catalog includes reverse-path / directional asymmetry — measuring from the wrong end (or only one end) systematically misses a directional failure. + +### For Chinese TTS (StepFun StepAudio 2.5) +Use **stepfun-tts** for Chinese / Japanese voice synthesis with emotional control via `instruction` + inline `()` prosody. Captures the two breaking changes that ambush new StepAudio 2.5 users: `voice_label` removal and stricter 2.5-era censorship rules. Pair with `step-tts-2` as a per-line fallback for content that triggers censorship. + +### For Long-Audio Transcription (StepFun StepAudio 2.5) +Use **stepfun-asr** for transcribing up to 30-minute Chinese / English audio in a single SSE call (32K context, ~85-101× RTF, no client-side chunking). Hides the #1 trap — the model does NOT live on `/v1/audio/transcriptions`; the wrong endpoint returns a misleading "model not supported" error. Combine with **transcript-fixer** for ASR error correction or with **meeting-minutes-taker** to turn long recordings into structured minutes. + ## 📚 Documentation Each skill includes: @@ -1862,54 +2740,64 @@ Each skill includes: ### Quick Links - **github-ops**: See `github-ops/references/api_reference.md` for API documentation -- **markdown-tools**: See `markdown-tools/references/conversion-examples.md` for conversion scenarios -- **mermaid-tools**: See `mermaid-tools/references/setup_and_troubleshooting.md` for setup guide -- **statusline-generator**: See `statusline-generator/references/color_codes.md` for customization +- **doc-to-markdown**: See `daymade-docs/doc-to-markdown/references/conversion-examples.md` for conversion scenarios +- **mermaid-tools**: See `daymade-docs/mermaid-tools/references/setup_and_troubleshooting.md` for setup guide +- **statusline-generator**: See `daymade-claude-code/statusline-generator/references/color_codes.md` for customization - **teams-channel-post-writer**: See `teams-channel-post-writer/references/writing-guidelines.md` for quality standards - **repomix-unmixer**: See `repomix-unmixer/references/repomix-format.md` for format specifications -- **skill-creator**: See `skill-creator/SKILL.md` for complete skill creation workflow +- **skill-creator**: See `daymade-skill/skill-creator/SKILL.md` for complete skill creation workflow - **llm-icon-finder**: See `llm-icon-finder/references/icons-list.md` for available icons - **cli-demo-generator**: See `cli-demo-generator/references/vhs_syntax.md` for VHS syntax and `cli-demo-generator/references/best_practices.md` for demo guidelines - **cloudflare-troubleshooting**: See `cloudflare-troubleshooting/references/api_overview.md` for API documentation - **ui-designer**: See `ui-designer/SKILL.md` for design system extraction workflow -- **ppt-creator**: See `ppt-creator/references/WORKFLOW.md` for 9-stage creation process and `ppt-creator/references/ORCHESTRATION_OVERVIEW.md` for automation +- **ppt-creator**: See `daymade-docs/ppt-creator/references/WORKFLOW.md` for 9-stage creation process and `daymade-docs/ppt-creator/references/ORCHESTRATION_OVERVIEW.md` for automation - **youtube-downloader**: See `youtube-downloader/SKILL.md` for usage examples and troubleshooting - **repomix-safe-mixer**: See `repomix-safe-mixer/references/common_secrets.md` for detected credential patterns - **video-comparer**: See `video-comparer/references/video_metrics.md` for quality metrics interpretation and `video-comparer/references/configuration.md` for customization options -- **transcript-fixer**: See `transcript-fixer/references/workflow_guide.md` for step-by-step workflows and `transcript-fixer/references/team_collaboration.md` for collaboration patterns +- **transcript-fixer**: See `daymade-audio/transcript-fixer/references/workflow_guide.md` for step-by-step workflows and `daymade-audio/transcript-fixer/references/team_collaboration.md` for collaboration patterns - **qa-expert**: See `qa-expert/references/master_qa_prompt.md` for autonomous execution (100x speedup) and `qa-expert/references/google_testing_standards.md` for AAA pattern and OWASP testing - **prompt-optimizer**: See `prompt-optimizer/references/ears_syntax.md` for EARS transformation patterns, `prompt-optimizer/references/domain_theories.md` for theory catalog, and `prompt-optimizer/references/examples.md` for complete transformations -- **claude-code-history-files-finder**: See `claude-code-history-files-finder/references/session_file_format.md` for JSONL structure and `claude-code-history-files-finder/references/workflow_examples.md` for recovery workflows -- **docs-cleaner**: See `docs-cleaner/SKILL.md` for consolidation workflows +- **claude-code-history-files-finder**: See `daymade-claude-code/claude-code-history-files-finder/references/session_file_format.md` for JSONL structure and `daymade-claude-code/claude-code-history-files-finder/references/workflow_examples.md` for recovery workflows +- **docs-cleaner**: See `daymade-docs/docs-cleaner/SKILL.md` for consolidation workflows - **deep-research**: See `deep-research/references/research_report_template.md` for report structure and `deep-research/references/source_quality_rubric.md` for source triage -- **pdf-creator**: See `pdf-creator/SKILL.md` for PDF conversion and font setup -- **claude-md-progressive-disclosurer**: See `claude-md-progressive-disclosurer/SKILL.md` for CLAUDE.md optimization workflow -- **skills-search**: See `skills-search/SKILL.md` for CCPM CLI commands and registry operations +- **pdf-creator**: See `daymade-docs/pdf-creator/SKILL.md` for PDF conversion and font setup +- **claude-md-progressive-disclosurer**: See `daymade-claude-code/claude-md-progressive-disclosurer/SKILL.md` for CLAUDE.md optimization workflow +- **skills-search**: See `daymade-skill/skills-search/SKILL.md` for CCPM CLI commands and registry operations - **promptfoo-evaluation**: See `promptfoo-evaluation/references/promptfoo_api.md` for evaluation patterns - **iOS-APP-developer**: See `iOS-APP-developer/references/xcodegen-full.md` for XcodeGen options and project.yml details - **twitter-reader**: See `twitter-reader/SKILL.md` for API key setup and URL format support - **macos-cleaner**: See `macos-cleaner/references/cleanup_targets.md` for detailed cleanup target explanations, `macos-cleaner/references/mole_integration.md` for Mole visual tool integration, and `macos-cleaner/references/safety_rules.md` for comprehensive safety guidelines -- **skill-reviewer**: See `skill-reviewer/references/evaluation_checklist.md` for complete evaluation criteria, `skill-reviewer/references/pr_template.md` for PR templates, and `skill-reviewer/references/marketplace_template.json` for marketplace configuration +- **skill-reviewer**: See `daymade-skill/skill-reviewer/references/evaluation_checklist.md` for complete evaluation criteria and `daymade-skill/skill-reviewer/references/pr_template.md` for PR templates - **github-contributor**: See `github-contributor/references/pr_checklist.md` for PR quality checklist, `github-contributor/references/project_evaluation.md` for project evaluation criteria, and `github-contributor/references/communication_templates.md` for issue/PR templates - **i18n-expert**: See `i18n-expert/SKILL.md` for complete i18n setup workflow, key architecture guidance, and audit procedures -- **claude-skills-troubleshooting**: See `claude-skills-troubleshooting/SKILL.md` for plugin troubleshooting workflow and architecture +- **claude-skills-troubleshooting**: See `daymade-claude-code/claude-skills-troubleshooting/SKILL.md` for plugin troubleshooting workflow and architecture - **fact-checker**: See `fact-checker/SKILL.md` for fact-checking workflow and claim verification process - **competitors-analysis**: See `competitors-analysis/SKILL.md` for evidence-based analysis workflow and `competitors-analysis/references/profile_template.md` for competitor profile template - **windows-remote-desktop-connection-doctor**: See `windows-remote-desktop-connection-doctor/references/windows_app_log_analysis.md` for log parsing patterns and `windows-remote-desktop-connection-doctor/references/avd_transport_protocols.md` for transport protocol details - **product-analysis**: See `product-analysis/SKILL.md` for workflow and `product-analysis/references/synthesis_methodology.md` for cross-agent weighting and recommendation logic - **excel-automation**: See `excel-automation/SKILL.md` for create/parse/control workflows and `excel-automation/references/formatting-reference.md` for formatting standards - **capture-screen**: See `capture-screen/SKILL.md` for CGWindowID-based screenshot workflows on macOS +- **continue-claude-work**: See `daymade-claude-code/continue-claude-work/SKILL.md` for local artifact recovery, drift checks, and resume workflow +- **scrapling-skill**: See `scrapling-skill/SKILL.md` for the CLI workflow and `scrapling-skill/references/troubleshooting.md` for verified Scrapling failure modes +- **ima-copilot**: See `ima-copilot/SKILL.md` for the wrapper architecture and routing, `ima-copilot/references/installation_flow.md` for the install deep dive, `ima-copilot/references/known_issues.md` for the issue registry and repair commands, and `ima-copilot/references/search_best_practices.md` for the fan-out strategy and 100-result truncation details +- **claude-export-txt-better**: See `daymade-claude-code/claude-export-txt-better/SKILL.md` for the workflow, `daymade-claude-code/claude-export-txt-better/scripts/fix-claude-export.py` for the reconstruction algorithm, and `daymade-claude-code/claude-export-txt-better/evals/` for real regression fixtures +- **douban-skill**: See `douban-skill/SKILL.md` for the export workflow and `douban-skill/references/troubleshooting.md` for the complete log of 7 tested scraping approaches and why each failed +- **terraform-skill**: See `terraform-skill/SKILL.md` for the full catalogue of operational traps organised by exact error → root cause → copy-paste fix +- **slides-creator**: See `slides-creator/SKILL.md` for the narrative-first workflow, `slides-creator/references/narrative-design-guide.md` for the ABCDEFG model, and `slides-creator/references/content-creation-first-law.md` for the universal content creation principle +- **debugging-network-issues**: See `debugging-network-issues/SKILL.md` for the falsification-first workflow, `debugging-network-issues/references/layered-isolation-experiment.md` for the multi-hop isolation pattern, and `debugging-network-issues/references/case-sse-rst-130s.md` for the real production case study +- **stepfun-tts**: See `stepfun-tts/SKILL.md` for the Contextual TTS decision tree and `stepfun-tts/references/migration_from_v2.md` for the `voice_label` → `instruction` migration playbook plus the censorship rewrite list +- **stepfun-asr**: See `stepfun-asr/SKILL.md` for the SSE-endpoint workflow and the four ASR-side traps (wrong endpoint, Plan-vs-Normal key, repetition hallucination, SSE `error` event). `stepfun-asr/references/api_reference.md` documents the exact JSON request body and SSE event contract for raw HTTP integration ## 🛠️ Requirements - **Claude Code** 2.0.13 or higher - **Python 3.6+** (for scripts in multiple skills) - **gh CLI** (for github-ops) -- **markitdown** (for markdown-tools) +- **markitdown** (for doc-to-markdown) - **mermaid-cli** (for mermaid-tools) - **yt-dlp** (for youtube-downloader): `brew install yt-dlp` or `pip install yt-dlp` - **FFmpeg/FFprobe** (for video-comparer): `brew install ffmpeg`, `apt install ffmpeg`, or `winget install ffmpeg` -- **weasyprint, markdown** (for pdf-creator) +- **pandoc + weasyprint** (for pdf-creator): `brew install pandoc` + `pip install weasyprint` (or use Chrome as backend) - **VHS** (for cli-demo-generator): `brew install vhs` - **Jina.ai API key** (for twitter-reader): Free tier available at https://jina.ai/ - **asciinema** (optional, for cli-demo-generator interactive recording) @@ -1924,6 +2812,10 @@ Each skill includes: - **Codex CLI** (optional, for product-analysis multi-model mode) - **uv + openpyxl** (for excel-automation): `uv run --with openpyxl ...` - **macOS** (for capture-screen and excel-automation AppleScript control workflows) +- **Python 3.8+** (for continue-claude-work): bundled script for session extraction (no external dependencies) +- **uv + Scrapling CLI** (for scrapling-skill): `uv tool install 'scrapling[shell]'` and `scrapling install` for browser-backed fetches +- **Node.js 18+ + curl + unzip** (for ima-copilot): `npx skills` is fetched on demand from the npm registry; IMA OpenAPI credentials from [https://ima.qq.com/agent-interface](https://ima.qq.com/agent-interface) +- **StepFun API key** (for stepfun-tts and stepfun-asr — must be "Normal" tier, Plan keys silently fail on audio endpoints): Available at [https://platform.stepfun.com/](https://platform.stepfun.com/) → API Keys ## ❓ FAQ @@ -2006,4 +2898,4 @@ If you find these skills useful, please: **Built with ❤️ using the skill-creator skill for Claude Code** -Last updated: 2026-01-22 | Marketplace version 1.23.0 +Last updated: 2026-06-05 | Marketplace version 1.60.1 diff --git a/README.zh-CN.md b/README.zh-CN.md index 5404eaaf..2095e046 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -6,15 +6,15 @@ [![简体中文](https://img.shields.io/badge/语言-简体中文-red)](./README.zh-CN.md) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) -[![Skills](https://img.shields.io/badge/skills-41-blue.svg)](https://github.com/daymade/claude-code-skills) -[![Version](https://img.shields.io/badge/version-1.37.0-green.svg)](https://github.com/daymade/claude-code-skills) +[![Skills](https://img.shields.io/badge/skills-64-blue.svg)](https://github.com/daymade/claude-code-skills) +[![Version](https://img.shields.io/badge/version-1.65.0-green.svg)](https://github.com/daymade/claude-code-skills) [![Claude Code](https://img.shields.io/badge/Claude%20Code-2.0.13+-purple.svg)](https://claude.com/code) [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](./CONTRIBUTING.md) [![Maintenance](https://img.shields.io/badge/Maintained%3F-yes-green.svg)](https://github.com/daymade/claude-code-skills/graphs/commit-activity) -专业的 Claude Code 技能市场，提供 41 个生产就绪的技能，用于增强开发工作流。 +专业的 Claude Code 技能市场，提供 64 个生产就绪的技能，用于增强开发工作流。 ## 📑 目录 @@ -38,13 +38,35 @@ `skill-creator` 是一个**元技能**，它使你能够构建、验证和打包自己的 Claude Code 技能。它是这个市场中最重要的工具，因为它赋予你用自己的专业工作流扩展 Claude Code 的能力。 -### 为什么首选 skill-creator？ +### 为什么选这个 skill-creator？ -- **🎯 基础工具**：通过创建自己的技能来学习技能的工作原理 -- **🛠️ 完整工具包**：包含初始化、验证和打包脚本 -- **📖 最佳实践**：从生产就绪的示例中学习 -- **🚀 快速启动**：在几秒钟内生成技能模板 -- **✅ 质量保证**：内置验证确保你的技能符合标准 +这是 [Anthropic 官方 skill-creator](https://github.com/anthropics/skills/tree/main/skills/skill-creator) 的**生产强化版 fork**——从真实 skill 开发中踩过的坑里长出来的。 + +**官方告诉你"做什么"。我们还告诉你"别试什么"——以及为什么。** + +| 你想要... | 官方版 | 本 Fork | +|----------|--------|---------| +| 造之前先调研 | "Check available MCPs"（5 行） | 8 渠道搜索协议 + Adopt/Extend/Build 决策矩阵 | +| 交互式创建 skill | 纯文字指令 | 9 个结构化 AskUserQuestion 检查点——用户永远不丢上下文 | +| 避免常见错误 | 无指引 | 缓存编辑警告、前置依赖检查、安全扫描门禁 | +| 了解架构选项 | 未提及 | Inline vs Fork 决策指南（选错会静默破坏你的 skill） | +| 发布前验证 | 基本 YAML 检查 | 扩展验证器（全部 frontmatter 字段、路径引用完整性、空白字符问题） | +| 安全审查 | 无工具 | `security_scan.py` + gitleaks 集成——打包前硬门禁 | +| 从真实失败中学习 | 无失败案例 | 实战方法论 + 文档化的失败模式和踩坑记录 | + +**质量对比**（独立审计，8 个维度）： + +| 维度 | 官方版 | 本 Fork | +|------|--------|---------| +| 可操作性 | 7 | 9 | +| 错误预防 | 5 | 9 | +| 前置调研 | 4 | 9 | +| 对抗性审查 | 4 | 8 | +| 实战经验 | 3 | 8 | +| 用户体验 | 4 | 9 | +| **总分（/80）** | **42** | **65** | + +> 完整方法论：[skill-creator/references/skill-development-methodology.md](./daymade-skill/skill-creator/references/skill-development-methodology.md) ### 快速安装 @@ -63,7 +85,7 @@ ```bash claude plugin marketplace add https://github.com/daymade/claude-code-skills # Marketplace 名称：daymade-skills（来自 marketplace.json） -claude plugin install skill-creator@daymade-skills +claude plugin install daymade-skill@daymade-skills ``` ### 你可以做什么 @@ -80,7 +102,7 @@ claude plugin install skill-creator@daymade-skills 加载了 skill-creator 的 Claude Code 将引导你完成整个技能创建过程——从理解你的需求到打包最终技能。 -📚 **完整文档**：[skill-creator/SKILL.md](./skill-creator/SKILL.md) +📚 **完整文档**：[daymade-skill/skill-creator/SKILL.md](./daymade-skill/daymade-skill/skill-creator/SKILL.md) ### 实时演示 @@ -137,22 +159,50 @@ Marketplace 名称是 `daymade-skills`（来自 marketplace.json），安装插 **必备技能**（推荐首先安装）： ```bash -claude plugin install skill-creator@daymade-skills +# skill-creator 是 daymade-skill 套件的成员 +claude plugin install daymade-skill@daymade-skills ``` -**安装其他技能：** +**文档套件**（为文档工作流提供统一命名空间）： ```bash -# GitHub 操作 -claude plugin install github-ops@daymade-skills +claude plugin install daymade-docs@daymade-skills +``` + +这个套件会在同一个命名空间下暴露相关技能： + +```text +/daymade-docs:doc-to-markdown +/daymade-docs:mermaid-tools +/daymade-docs:pdf-creator +/daymade-docs:ppt-creator +/daymade-docs:docs-cleaner +``` -# 文档转换 -claude plugin install markdown-tools@daymade-skills +这些技能以套件形式整体发布，不再提供单独的单技能插件。所有文档技能都在 `daymade-docs/` 下，随套件一起安装。 -# 图表生成 -claude plugin install mermaid-tools@daymade-skills +**Claude Code 操作套件**（为 Claude Code 本体扩展工作流提供统一命名空间）： +```bash +claude plugin install daymade-claude-code@daymade-skills +``` -# 状态栏定制 -claude plugin install statusline-generator@daymade-skills +一次安装即可获得扩展 Claude Code 本体的全部 power-user 技能——会话恢复、CLAUDE.md 调优、故障诊断、statusline 配置、导出修复与 marketplace 开发： + +```text +/daymade-claude-code:claude-code-history-files-finder +/daymade-claude-code:continue-claude-work +/daymade-claude-code:claude-skills-troubleshooting +/daymade-claude-code:claude-md-progressive-disclosurer +/daymade-claude-code:statusline-generator +/daymade-claude-code:claude-export-txt-better +/daymade-claude-code:marketplace-dev +``` + +安装后调用统一显示为 `daymade-claude-code:`，共享同一命名空间。这些技能仅作为套件发布——安装套件即可获得全部 7 个技能。 + +**安装其他技能：** +```bash +# GitHub 操作 +claude plugin install github-ops@daymade-skills # Teams 通信 claude plugin install teams-channel-post-writer@daymade-skills @@ -172,17 +222,14 @@ claude plugin install cloudflare-troubleshooting@daymade-skills # UI 设计系统提取 claude plugin install ui-designer@daymade-skills -# 演示文稿创建 -claude plugin install ppt-creator@daymade-skills - # YouTube 视频/音频下载 claude plugin install youtube-downloader@daymade-skills # 安全 Repomix 打包 claude plugin install repomix-safe-mixer@daymade-skills -# ASR 转录校正 -claude plugin install transcript-fixer@daymade-skills +# 完整语音套件（ASR + 转录校正 + 会议纪要 + TTS） +claude plugin install daymade-audio@daymade-skills # 视频比较和质量分析 claude plugin install video-comparer@daymade-skills @@ -193,20 +240,8 @@ claude plugin install qa-expert@daymade-skills # 使用 EARS 方法论优化提示词 claude plugin install prompt-optimizer@daymade-skills -# 会话历史恢复 -claude plugin install claude-code-history-files-finder@daymade-skills - -# 文档整合 -claude plugin install docs-cleaner@daymade-skills - -# PDF 生成（含中文字体支持） -claude plugin install pdf-creator@daymade-skills - -# CLAUDE.md 渐进式披露优化 -claude plugin install claude-md-progressive-disclosurer@daymade-skills - # CCPM 技能注册表搜索和管理 -claude plugin install skills-search@daymade-skills +claude plugin install daymade-skill@daymade-skills # Promptfoo LLM 评测框架 claude plugin install promptfoo-evaluation@daymade-skills @@ -221,7 +256,7 @@ claude plugin install twitter-reader@daymade-skills claude plugin install macos-cleaner@daymade-skills # 技能质量审查与改进 -claude plugin install skill-reviewer@daymade-skills +claude plugin install daymade-skill@daymade-skills # GitHub 贡献策略 claude plugin install github-contributor@daymade-skills @@ -240,6 +275,18 @@ claude plugin install excel-automation@daymade-skills # macOS 程序化窗口截图工作流 claude plugin install capture-screen@daymade-skills + +# Scrapling CLI 抽取与故障排查 +claude plugin install scrapling-skill@daymade-skills + +# 腾讯 IMA 知识库伴侣与安装器 +claude plugin install ima-copilot@daymade-skills + +# 导出豆瓣书影音游戏收藏到 CSV +claude plugin install douban-skill@daymade-skills + +# Terraform 实操陷阱与多环境可靠性模式 +claude plugin install terraform-skill@daymade-skills ``` 每个技能都可以独立安装 - 只选择你需要的！ @@ -313,7 +360,9 @@ CC-Switch 支持以下中国 AI 服务提供商： --- -### 2. **markdown-tools** - 文档转换套件 +### 2. **doc-to-markdown** - 文档转换套件 + +> **安装**：`claude plugin install daymade-docs@daymade-skills`（仅作为套件成员发布，调用方式 `daymade-docs:doc-to-markdown`） 将文档转换为 markdown，支持 Windows/WSL 路径处理和 PDF 图片提取。 @@ -332,12 +381,14 @@ CC-Switch 支持以下中国 AI 服务提供商： **🎬 实时演示** -![Markdown 工具演示](./demos/markdown-tools/convert-docs.gif) +![Markdown 工具演示](./demos/doc-to-markdown/convert-docs.gif) --- ### 3. **mermaid-tools** - 图表生成 +> **安装**：`claude plugin install daymade-docs@daymade-skills`（仅作为套件成员发布，调用方式 `daymade-docs:mermaid-tools`） + 从 markdown 中提取 Mermaid 图表并生成高质量的 PNG 图像。 **使用场景：** @@ -361,6 +412,8 @@ CC-Switch 支持以下中国 AI 服务提供商： ### 4. **statusline-generator** - 状态栏定制 +> **安装**：`claude plugin install daymade-claude-code@daymade-skills`（仅作为套件成员发布，调用方式 `daymade-claude-code:statusline-generator`） + 配置 Claude Code 状态栏，支持多行布局和成本跟踪。 **使用场景：** @@ -530,6 +583,8 @@ CC-Switch 支持以下中国 AI 服务提供商： ### 11. **ppt-creator** - 专业演示文稿创建 +> **安装**：`claude plugin install daymade-docs@daymade-skills`（仅作为套件成员发布，调用方式 `daymade-docs:ppt-creator`） + 使用金字塔原理和断言-证据框架创建专业幻灯片。 **使用场景：** @@ -561,7 +616,7 @@ CC-Switch 支持以下中国 AI 服务提供商： *即将推出* -📚 **文档**：参见 [ppt-creator/references/WORKFLOW.md](./ppt-creator/references/WORKFLOW.md) 了解 9 阶段创建流程 +📚 **文档**：参见 [daymade-docs/ppt-creator/references/WORKFLOW.md](./daymade-docs/ppt-creator/references/WORKFLOW.md) 了解 9 阶段创建流程 --- @@ -637,6 +692,8 @@ python3 scripts/safe_mix.py /path/to/codebase ### 14. **transcript-fixer** - ASR 转录校正 +> **安装**：`claude plugin install daymade-audio@daymade-skills`（仅作为套件成员发布，调用方式 `daymade-audio:transcript-fixer`） + 通过基于字典的规则和 AI 驱动的校正来纠正语音转文本（ASR/STT）转录错误。 **使用场景：** @@ -666,7 +723,7 @@ python3 scripts/fix_transcript.py transcript.txt --dictionary custom_dict.json *即将推出* -📚 **文档**：参见 [transcript-fixer/references/workflow_guide.md](./transcript-fixer/references/workflow_guide.md) 了解分步工作流 +📚 **文档**：参见 [daymade-audio/transcript-fixer/references/workflow_guide.md](./daymade-audio/transcript-fixer/references/workflow_guide.md) 了解分步工作流 **要求**：Python 3.8+ @@ -829,6 +886,8 @@ python3 scripts/calculate_metrics.py tests/TEST-EXECUTION-TRACKING.csv ### 18. **claude-code-history-files-finder** - 会话历史恢复 +> **安装**：`claude plugin install daymade-claude-code@daymade-skills`（仅作为套件成员发布，调用方式 `daymade-claude-code:claude-code-history-files-finder`） + 从存储在 `~/.claude/projects/` 的 Claude Code 会话历史文件中查找和恢复内容。 **使用场景：** @@ -863,7 +922,7 @@ python3 scripts/analyze_sessions.py stats /path/to/session.jsonl --show-files *即将推出* -📚 **文档**：参见 [claude-code-history-files-finder/references/](./claude-code-history-files-finder/references/)： +📚 **文档**：参见 [daymade-claude-code/claude-code-history-files-finder/references/](./daymade-claude-code/claude-code-history-files-finder/references/)： - `session_file_format.md` - JSONL 结构和提取模式 - `workflow_examples.md` - 详细的恢复和分析工作流 @@ -871,6 +930,8 @@ python3 scripts/analyze_sessions.py stats /path/to/session.jsonl --show-files ### 19. **docs-cleaner** - 文档整合 +> **安装**：`claude plugin install daymade-docs@daymade-skills`（仅作为套件成员发布，调用方式 `daymade-docs:docs-cleaner`） + 整合冗余文档的同时保留所有有价值的内容。 **使用场景：** @@ -934,7 +995,7 @@ ccpm install-bundle web-dev # 安装 Web 开发技能包 *即将推出* -📚 **文档**：参见 [skills-search/SKILL.md](./skills-search/SKILL.md) 了解完整的命令参考 +📚 **文档**：参见 [daymade-skill/skills-search/SKILL.md](./daymade-skill/daymade-skill/skills-search/SKILL.md) 了解完整的命令参考 **要求**：CCPM CLI（`npm install -g @daymade/ccpm`） @@ -942,6 +1003,8 @@ ccpm install-bundle web-dev # 安装 Web 开发技能包 ### 21. **pdf-creator** - PDF 生成（中文字体支持） +> **安装**：`claude plugin install daymade-docs@daymade-skills`（仅作为套件成员发布，调用方式 `daymade-docs:pdf-creator`） + 使用 WeasyPrint 将 markdown 转换为专业 PDF，并提供完善的中文字体支持。 **使用场景：** @@ -952,6 +1015,7 @@ ccpm install-bundle web-dev # 安装 Web 开发技能包 **主要功能：** - WeasyPrint + Markdown 转换管道 - 内置中文字体回退 +- 主题系统（default 正式文档、cjk-auto 内容自适应表格、warm-terra 培训材料、mobile 手机阅读） - A4 版式与打印友好边距 - 批量转换脚本 @@ -964,7 +1028,7 @@ uv run --with weasyprint --with markdown scripts/md_to_pdf.py input.md output.pd *即将推出* -📚 **文档**：参见 [pdf-creator/SKILL.md](./pdf-creator/SKILL.md) 了解设置与工作流。 +📚 **文档**：参见 [daymade-docs/pdf-creator/SKILL.md](./daymade-docs/pdf-creator/SKILL.md) 了解设置与工作流。 **要求**：Python 3.8+，`weasyprint`、`markdown` @@ -972,6 +1036,8 @@ uv run --with weasyprint --with markdown scripts/md_to_pdf.py input.md output.pd ### 22. **claude-md-progressive-disclosurer** - CLAUDE.md 优化 +> **安装**：`claude plugin install daymade-claude-code@daymade-skills`（仅作为套件成员发布，调用方式 `daymade-claude-code:claude-md-progressive-disclosurer`） + 使用渐进式披露原则优化 CLAUDE.md，减少上下文负担但保留关键规则。 **使用场景：** @@ -993,7 +1059,7 @@ uv run --with weasyprint --with markdown scripts/md_to_pdf.py input.md output.pd *即将推出* -📚 **文档**：参见 [claude-md-progressive-disclosurer/SKILL.md](./claude-md-progressive-disclosurer/SKILL.md)。 +📚 **文档**：参见 [claude-md-progressive-disclosurer/SKILL.md](./daymade-claude-code/claude-md-progressive-disclosurer/SKILL.md)。 --- @@ -1277,7 +1343,7 @@ claude plugin install fact-checker@daymade-skills **示例用法：** ```bash # 安装技能 -claude plugin install skill-reviewer@daymade-skills +claude plugin install daymade-skill@daymade-skills # 自检你的技能 "验证 ~/my-skills/my-awesome-skill 的技能" @@ -1293,10 +1359,9 @@ claude plugin install skill-reviewer@daymade-skills *即将推出* -📚 **文档**：参见 [skill-reviewer/references/](./skill-reviewer/references/) 了解： +📚 **文档**：参见 [daymade-skill/skill-reviewer/references/](./daymade-skill/daymade-skill/skill-reviewer/references/) 了解： - `evaluation_checklist.md` - 完整的技能评估标准 - `pr_template.md` - 专业 PR 描述模板 -- `marketplace_template.json` - marketplace 配置模板 --- @@ -1410,6 +1475,8 @@ claude plugin install i18n-expert@daymade-skills ### 32. **claude-skills-troubleshooting** - 插件与技能故障排除 +> **安装**：`claude plugin install daymade-claude-code@daymade-skills`（仅作为套件成员发布，调用方式 `daymade-claude-code:claude-skills-troubleshooting`） + 诊断和解决 Claude Code 插件和技能配置问题。通过系统化工作流程调试插件安装、启用和激活问题。 **使用场景：** @@ -1430,9 +1497,6 @@ claude plugin install i18n-expert@daymade-skills **示例用法：** ```bash -# 安装技能 -claude plugin install claude-skills-troubleshooting@daymade-skills - # 运行诊断 python3 scripts/diagnose_plugins.py @@ -1444,7 +1508,7 @@ python3 scripts/enable_all_plugins.py daymade-skills *即将推出* -📚 **文档**：参见 [claude-skills-troubleshooting/SKILL.md](./claude-skills-troubleshooting/SKILL.md) 了解完整的故障排除工作流程和架构指导。 +📚 **文档**：参见 [claude-skills-troubleshooting/SKILL.md](./daymade-claude-code/claude-skills-troubleshooting/SKILL.md) 了解完整的故障排除工作流程和架构指导。 **要求**：无（使用 Claude Code 内置 Python） @@ -1452,6 +1516,8 @@ python3 scripts/enable_all_plugins.py daymade-skills ### 33. **meeting-minutes-taker** - 会议纪要生成器 +> **安装**：`claude plugin install daymade-audio@daymade-skills`（仅作为套件成员发布，调用方式 `daymade-audio:meeting-minutes-taker`） + 将会议录音转写稿转换为高保真、结构化的会议纪要，支持迭代式人工审核。 **使用场景：** @@ -1469,8 +1535,8 @@ python3 scripts/enable_all_plugins.py daymade-skills **示例用法：** ```bash -# 安装技能 -claude plugin install meeting-minutes-taker@daymade-skills +# 安装完整语音套件（包含 meeting-minutes-taker） +claude plugin install daymade-audio@daymade-skills # 然后提供会议转写稿并请求生成纪要 ``` @@ -1479,7 +1545,7 @@ claude plugin install meeting-minutes-taker@daymade-skills *即将推出* -📚 **文档**：参见 [meeting-minutes-taker/SKILL.md](./meeting-minutes-taker/SKILL.md) 了解完整的工作流程和模板指导。 +📚 **文档**：参见 [daymade-audio/meeting-minutes-taker/SKILL.md](./daymade-audio/meeting-minutes-taker/SKILL.md) 了解完整的工作流程和模板指导。 **要求**：无 @@ -1791,6 +1857,791 @@ claude plugin install capture-screen@daymade-skills --- +### 42. **continue-claude-work** - 续做中断的 Claude 工作 + +> **安装**：`claude plugin install daymade-claude-code@daymade-skills`（仅作为套件成员发布，调用方式 `daymade-claude-code:continue-claude-work`） + +从本地 `~/.claude` 会话产物中恢复可执行上下文，并在不重新打开旧交互会话的前提下继续实现工作。内置 Python 脚本实现智能上下文提取。 + +**使用场景：** +- 用户提供 Claude 会话 ID，希望继续上次的任务 +- 需要直接检查本地 `.claude` JSONL 文件，而不是运行 `claude --resume` +- 上一次会话被中断，需要重建下一步具体动作 +- 多 agent 工作流被中断，需要了解哪些 subagent 已完成 + +**主要功能：** +- Compact-boundary 感知提取 — 读取 Claude 自身的会话压缩摘要作为最高信噪比上下文 +- Subagent 工作流恢复 — 报告已完成与被中断的 subagent 及其最后输出 +- 会话结束原因检测 — 区分正常退出、中断（ctrl-c）、错误级联、废弃会话 +- 大小自适应策略 — 对小型（<500KB）和大型（>5MB）会话采用不同读取方式 +- 噪声过滤 — 跳过 progress/queue-operation/api_error 消息（占会话行数的 37-53%） +- 自会话排除、过期索引回退、MEMORY.md 集成、git 工作区状态 + +**示例用法：** +```bash +# 然后让 Claude 基于本地产物续做 +"continue work from session 123e4567-e89b-12d3-a456-426614174000" +"不用真的 resume，去 .claude 里找上下文继续做" +"查看上次会话做了什么，然后继续" +``` + +📚 **文档**：参见 [continue-claude-work/SKILL.md](./daymade-claude-code/continue-claude-work/SKILL.md)。 + +**要求**：Python 3.8+，用于工作区核对的 `git`。 + +--- + +### 43. **scrapling-skill** - 可靠的 Scrapling CLI 工作流 + +围绕 Scrapling CLI 提供经过验证的安装、排障与网页抽取工作流，用于从网页输出 HTML、Markdown 或纯文本。内置诊断脚本，可检查 extras 安装问题、Playwright 浏览器运行时，以及真实 URL 的烟测结果。 + +**使用场景：** +- 用户提到 Scrapling、`uv tool install scrapling` 或 `scrapling extract` +- 需要判断应该使用静态抓取还是浏览器抓取 +- 需要从微信公众号页面（`mp.weixin.qq.com`）提取正文 +- Scrapling 安装看似成功，但在 extras、浏览器运行时或 TLS 校验上失败 + +**主要功能：** +- 内置 `diagnose_scrapling.py`，检查 CLI、浏览器运行时与真实 URL 烟测 +- 经过验证的默认路径：先用 `extract get`，只有必要时再升级到 `extract fetch` +- 针对微信公众号文章的 `#js_content` 提取模式 +- 覆盖缺少 `click`、Playwright 运行时缺失、`curl: (60)` 证书问题等真实故障 +- 用文件大小和内容验证结果，而不是只看退出码 + +**示例用法：** +```bash +# 安装技能 +claude plugin install scrapling-skill@daymade-skills + +# 然后让 Claude 代你跑 Scrapling +"安装 Scrapling CLI 并验证配置" +"用 Scrapling 把这篇微信公众号文章提取成 Markdown" +"判断这个页面应不应该走浏览器抓取" +``` + +**🎬 实时演示** + +*即将推出* + +📚 **文档**：参见 [scrapling-skill/SKILL.md](./scrapling-skill/SKILL.md) 和 [scrapling-skill/references/troubleshooting.md](./scrapling-skill/references/troubleshooting.md)。 + +**要求**：Python 3.6+、`uv`、Scrapling CLI；如需浏览器抓取，还需要 Playwright 浏览器运行时。 + +--- + +### 44. **ima-copilot** - 腾讯 IMA 伴侣与安装器 + +围绕官方腾讯 IMA skill（`ima.qq.com`）的一站式包装层。通过 `npx skills add` 把官方 `ima-skill` 一键安装到 Claude Code、Codex、OpenClaw 三个平台；引导用户配置 API 凭据；在用户授权下检测并修复上游已知问题；提供按知识库置顶的个人化扇出搜索策略。 + +**使用场景：** +- 用户提到 IMA、腾讯 IMA、ima.qq.com，或需要安装官方 ima-skill +- 用户遇到 `Skipped loading skill(s) due to invalid SKILL.md` 这类 ima-skill 加载告警 +- 需要跨 IMA 知识库搜索并把某些精选库置顶 +- 需要配置或轮换 IMA API 凭据 +- 上游 ima-skill 发布了带 bug 的新版（例如子模块 SKILL.md 缺少 YAML frontmatter） + +**主要功能：** +- 通过 [vercel-labs/skills](https://github.com/vercel-labs/skills) 实现对 Claude Code / Codex / OpenClaw 三个目标的零配置安装，自动探测已安装的 agent，默认走 symlink 模式——修一次或升级一次，所有共享同一 canonical install 的 agent 自动同步 +- 凭据管理走 XDG 风格：`~/.config/ima/{client_id, api_key}`，同时支持 `IMA_OPENAPI_CLIENTID` / `IMA_OPENAPI_APIKEY` 环境变量兜底 +- 内置只读诊断脚本 `scripts/diagnose.sh`，用结构化 `✅/⚠️/❌` 报告覆盖安装状态、凭据 liveness、以及所有已知上游问题 +- 内置 `scripts/search_fanout.py`，实现客户端跨知识库扇出搜索，支持优先库置顶、子集库过滤、100 条静默截断检测，以及订阅只读库的权限差异分组 +- 严格的包装层架构：永不 vendor 上游文件，永不 fork，每一次修复都是运行时指令 + 明确用户授权 + 自动带时间戳的 `/tmp` 备份 +- 针对 frontmatter 缺失问题提供两种可选修复策略：A 策略（把子模块改名为 `MODULE.md` 并 patch 根 SKILL.md 引用，尊重上游设计意图）或 B 策略（仅追加最小 frontmatter，最小化差异） +- 个人化偏好通过 `~/.config/ima/copilot.json` 声明，仓库只提供示例模板 `config-template/copilot.json.example`，不预设任何真实知识库名 + +**示例用法：** +```bash +# 安装技能 +claude plugin install ima-copilot@daymade-skills + +# 然后让 Claude 代你跑完整个流程 +"装一下 ima-skill 并配置我的 IMA API key" +"对我的 ima-skill 做一次诊断，有问题就修" +"在我的 IMA 知识库里搜 embedding 模型对比，精选库置顶" +``` + +**🎬 实时演示** + +*即将推出* + +📚 **文档**：参见 [ima-copilot/SKILL.md](./ima-copilot/SKILL.md) 和 [ima-copilot/references/known_issues.md](./ima-copilot/references/known_issues.md)。 + +**要求**：Node.js 18+（`npx skills` 在按需拉取）、`curl`、`unzip`、Python 3.6+；从 [https://ima.qq.com/agent-interface](https://ima.qq.com/agent-interface) 获取 IMA OpenAPI 凭据。 + +--- + +### 45. **claude-export-txt-better** - 修复 Claude Code 导出文件的断行 + +> **安装**：`claude plugin install daymade-claude-code@daymade-skills`（仅作为套件成员发布，调用方式 `daymade-claude-code:claude-export-txt-better`） + +重建 Claude Code 导出的 `.txt` 对话文件中被硬换行切坏的表格、段落、路径和工具调用输出。附带 53 项自动校验套件（文件无关，能捕捉 over-/under-merge 回归）。 + +**使用场景：** +- 用户的 Claude Code 导出文件被固定列宽换行搞坏了表格、路径或工具输出 +- 用户提到"修复导出""修复对话""让导出可读" +- 用户有匹配 `YYYY-MM-DD-HHMMSS-*.txt` 的文件 +- 用户想在分享或归档前后处理 `/export` 的输出 + +**主要功能：** +- 确定性的 Python 脚本（`fix-claude-export.py`），带 `--stats` 模式查看前后指标 +- 53 项自动校验器（`validate-claude-export-fix.py`），捕捉回归 +- evals 目录带真实 fixture 案例 +- 零外部依赖，只需 `uv` 和 Python 3.8+ + +**示例用法：** +```bash +# 修复并显示统计 +uv run daymade-claude-code/claude-export-txt-better/scripts/fix-claude-export.py broken.txt --stats + +# 自定义输出路径 +uv run daymade-claude-code/claude-export-txt-better/scripts/fix-claude-export.py broken.txt -o fixed.txt + +# 校验修复结果 +uv run daymade-claude-code/claude-export-txt-better/scripts/validate-claude-export-fix.py broken.txt fixed.txt +``` + +**🎬 实时演示** + +*即将推出* + +📚 **文档**：参见 [claude-export-txt-better/SKILL.md](./daymade-claude-code/claude-export-txt-better/SKILL.md) 和打包在内的 `evals/` fixture。 + +**要求**：Python 3.8+、`uv` 包管理器。 + +--- + +### 46. **douban-skill** - 豆瓣收藏导出与同步 + +通过逆向的 Frodo API 导出和同步豆瓣书影音游戏收藏到本地 CSV 文件。全量导出覆盖所有历史，RSS 增量同步保持每日更新。无需登录、无需 cookies、无需浏览器——只要一个用户 ID 就能跑通。 + +**使用场景：** +- 用户想备份自己的豆瓣读书/观影/听歌/游戏历史 +- 用户提到 豆瓣、douban、读书记录、观影记录、书影音 +- 用户需要增量同步最近的豆瓣动态 +- 用户想要 Excel 兼容的 CSV 输出（UTF-8 BOM） + +**主要功能：** +- 全量导出全部 4 类（书/影/音/游）通过 Frodo API +- RSS 增量同步每日更新（每个 feed 最近约 10 条） +- 预检查用户 ID 有效性（错误 ID 立刻失败） +- UTF-8 BOM CSV 输出，Excel 兼容，跨平台 +- 内置故障日志，记录 7 种被测试过的抓取方案以及每种为什么失败（豆瓣的 PoW 挑战封锁所有网页抓取——只有 Frodo API 可行） +- `.gitleaks.toml` allowlist 处理公开的 Android APK 凭据 + +**示例用法：** +```bash +# 全量导出用户收藏 +uv run douban-skill/scripts/douban-frodo-export.py + +# RSS 增量同步（每类最近 10 条左右） +uv run douban-skill/scripts/douban-rss-sync.py +``` + +**🎬 实时演示** + +*即将推出* + +📚 **文档**：参见 [douban-skill/SKILL.md](./douban-skill/SKILL.md) 和 [douban-skill/references/troubleshooting.md](./douban-skill/references/troubleshooting.md) 查看所有被拒方案的完整故障日志。 + +**要求**：Python 3.8+、`uv` 包管理器。无需登录或 cookies。 + +--- + +### 47. **terraform-skill** - Terraform 实操陷阱 + +来自真实 Terraform 部署的失败模式——每一条都对应一次真实事故。组织为*确切报错 → 根本原因 → 复制粘贴修复*。覆盖 provisioner 时序竞争、SSH 连接冲突、多环境隔离、DNS 记录重复、数据卷权限、数据库 bootstrap 缺口、快照跨环境污染、Cloudflare 凭据格式错误、Caddyfile/compose 里的硬编码域名，以及 init-data-only-on-first-boot 陷阱。 + +**使用场景：** +- 写 `null_resource` provisioner 或 `remote-exec` SSH 到新实例 +- 做多环境（prod/staging/dev）Terraform + 共享模块 +- 调试 `terraform apply` 后一直 Restarting/unhealthy 的容器 +- 遇到 remote-exec 的 "docker: not found"、local-exec 的 rsync connection drops、或 TLS 证书错误 +- 重跑时遇到 drift 或 provisioner 失败 +- 配置 Caddy/网关资源和 Cloudflare 凭据 + +**主要功能：** +- 每个陷阱都有可复制粘贴的 `.hcl` 片段，不是抽象建议 +- 覆盖 cloud-init、Docker、file provisioner、DNS、TLS、快照、跨环境污染 +- 每个模式都标了确切症状，方便 grep 快速定位 + +**示例用法：** +```bash +# 在 Terraform 工作中自然触发这个 skill +"我的 null_resource provisioner apply 后报 'docker: not found'" +"我的 rsync local-exec 报 'connection unexpectedly closed'" +"帮我写一个多环境 Terraform setup，避免快照跨环境污染" +``` + +**🎬 实时演示** + +*即将推出* + +📚 **文档**：参见 [terraform-skill/SKILL.md](./terraform-skill/SKILL.md) 和打包在内的 `references/` 查看详细修复模式。 + +**要求**：无（只需要 Terraform 相关知识；无运行时依赖）。 + +--- + +### 48. **slides-creator** - 叙事优先的幻灯片创建 + +引导用户完成结构化叙事设计（ABCDEFG 模型），然后将视觉生成委托给 `baoyu-slide-deck`。专注于机器做不到的事——与人类的叙事共创。 + +**使用场景：** +- 从用户内容创建演示文稿、幻灯片或 PPT +- 将文章、转录稿或笔记转化为视觉幻灯片 +- 为演讲和工作坊设计叙事弧线 + +**主要功能：** +- Phase 0：源材料收集（优先使用用户自己的文字） +- Phase 1：使用 ABCDEFG 模型进行叙事结构讨论 +- Phase 2：机器可读输入的内容结构化 +- Phase 3-5：将视觉生成委托给 baoyu-slide-deck +- Phase 6：目录重组和讲者备注提取的后处理 + +**示例用法：** +```bash +# 自然触发 skill +"帮我把我的文章做成幻灯片" +"从我的演讲转录稿创建演示文稿" +"我需要一个 20 分钟的工作坊演示" +``` + +**要求**：需要 baoyu-slide-deck skill 进行视觉生成。 + +--- + +### 49. **debugging-network-issues** - 证据驱动的网络问题排查 + +针对网络、流式、协议层 bug 的"先证伪、再下结论"方法论。源自一次真实的 5 小时 SSE 生产事故——堆假设浪费的几个小时，10 分钟分层实验就能解决。 + +**使用场景：** +- 连接重置（`ECONNRESET`、HTTP/2 `RST_STREAM`、`INTERNAL_ERROR`） +- SSE / 长轮询挂起或定时断开（60s、100s、130s） +- CDN / 代理 / CGNAT 空闲超时事件 +- "时灵时不灵 / N 秒后必断"模式 +- 多跳系统（client → CDN → LB → reverse proxy → app → upstream）症状可能来自多层 + +**主要功能：** +- 分层隔离实验：让同一逻辑请求走三条以上、每条仅差一跳的路径 +- 环境变量门控的运行时埋点（不污染生产代码） +- 反审查四问过滤器，挑战单因果假设 +- 内置探针脚本（`layered-isolation-probe.sh`、`mock-idle-upstream.py`） +- 真实案例：CGNAT 130s 空闲超时导致的 SSE RST_STREAM + +**要求**：无（方法论 + 可移植的 shell/Python 探针）。 + +--- + +### 50. **stepfun-tts** - 阶跃 StepAudio 2.5 Contextual TTS + +> **安装**：`claude plugin install daymade-audio@daymade-skills`（仅作为套件成员发布，调用方式 `daymade-audio:stepfun-tts`） + +用 `stepaudio-2.5-tts` 做中文 / 日语语音合成。封装了 TTS 部分两个会浪费时间的非显然坑：`voice_label` 被移除（改用自然语言 `instruction`）以及 2.5 时代更严格的审查（死/消失/政治敏感词）。 + +**使用场景：** +- 带情感和韵律控制的中 / 日语 TTS（耳语、停顿、加重、句中情绪转折） +- 批量生成游戏 / 应用语音条目，每条单独处理 `censorship_block` 兜底 +- 从 `step-tts-2` 迁移到 `stepaudio-2.5-tts`（`voice_label` → `instruction` 是破坏性变更） +- 之前能合成的内容现在被审查拦截 + +**主要功能：** +- `stepaudio-2.5-tts`：用 `instruction`（≤200 字自然语言情绪）+ 文中 `()` 行内韵律 +- 内置 `tts_generate.py`（含 `--batch `）、`ab_compare.sh` +- API key 解析顺序：`$STEPFUN_API_KEY` → `${CLAUDE_PLUGIN_DATA}/config.json` 兜底 +- `references/migration_from_v2.md` 给出审查拦截的改写策略 + +**要求**：StepFun API key 的 "Normal" 等级（https://platform.stepfun.com/）。如需 ASR / 转写，使用下方的姊妹技能 `stepfun-asr`。 + +--- + +### 52. **stepfun-asr** - 阶跃 StepAudio 2.5 ASR（SSE 端点） + +> **安装**：`claude plugin install daymade-audio@daymade-skills`（仅作为套件成员发布，调用方式 `daymade-audio:stepfun-asr`） + +用 `stepaudio-2.5-asr` 转写中 / 英文音频。封装 2.5 ASR 系列最坑的一点：模型**不在** `/v1/audio/transcriptions`——错端点返回的 `model stepaudio-2.5-asr not supported` 看起来跟权限被拒一模一样，会让人浪费几小时排查。 + +**使用场景：** +- 长音频转写（单次最长 ~30 分钟、32K context、~85-101× RTF、无需客户端切片） +- 从 `step-asr` / `step-asr-1.1` 迁移（端点不同、请求体不同、响应是 SSE 流） +- 遇到误导性的 `model stepaudio-2.5-asr not supported` 错误（= 端点用错了，不是权限问题） +- 调音频端点遭遇无声 4xx 鉴权失败（= 用了 "Plan" key 而不是 "Normal" key） + +**主要功能：** +- `/v1/audio/asr/sse` SSE 流 + base64 音频 + 嵌套 JSON 请求体（脚本一并处理四个坑） +- 内置 `asr_transcribe.py`——纯 stdlib CLI，按扩展名自动识别 mp3/wav/ogg/opus/pcm +- 处理 SSE `error` 事件（审查在 ASR 端也会触发——罕见但真实存在） +- API key 解析顺序：`$STEPFUN_API_KEY` → `${CLAUDE_PLUGIN_DATA}/config.json` 兜底 +- 推荐 `transcript-fixer`（ASR 纠错）和 `meeting-minutes-taker`（结构化纪要）作为下游技能 + +**要求**：StepFun API key 的 "Normal" 等级（https://platform.stepfun.com/）。Plan key 调不通音频端点。 + +--- + +### 53. **terminal-screenshot** - 看见终端输出的真实视觉效果 + +把终端 CLI 程序的彩色输出渲染成 PNG，让 Claude 真正"看见"渲染后的效果——颜色对比、对齐、背景色块、高亮——而不是只读到纯文本和原始 ANSI 转义码。读 hex 值是猜，看真实终端背景上渲染出的对比才是验证。 + +**何时使用：** +- 改完任何 CLI 配色（delta / bat / 主题 / lazygit pager）后，立即视觉确认效果 +- 验证 git diff（delta）增删对比、bat 语法高亮、starship prompt、eza/ls 配色、ripgrep 匹配 +- 任何需要判断"这配色对不对 / 对比够不够"而不是从 hex 码瞎猜的场景 + +**核心特性：** +- **先捕获再渲染的纪律**：先在正常 shell 捕获完整 ANSI，再渲染——绝不让渲染器代跑复杂 CLI（它们在子 pty 里会降级、丢背景块） +- **freeze 优先 + 零依赖兜底**：优先用 charmbracelet/freeze 忠实渲染；没有时回退到内置的纯 stdlib ANSI→HTML 转换器 + headless Chrome +- **真实终端背景**：用终端实际背景色渲染，深色主题才能判断准确 +- **各 CLI 捕获模板**：delta、git、bat、eza、ls、ripgrep，以及通用强制着色路径 +- **内置脚本**：`render_ansi.sh`（自动选 freeze/Chrome）、`ansi2html.py`（stdlib 渲染器） + +**使用示例：** +```bash +# terminal-screenshot 属于 daymade-claude-code 套件 +claude plugin install daymade-claude-code@daymade-skills + +# 然后自然地让 Claude 做 +"verify my delta diff colors" +"看一下这个终端配色的真实效果" +"git diff 的增删对比够明显吗" +``` + +**要求**：macOS。`charmbracelet/freeze`（首选渲染器）或 Google Chrome（兜底）。兜底渲染器需要 Python 3。 + +--- + +### 54. **pdf-to-html** - 把 PDF 读成保真 HTML（可选翻译） + +把 PDF 转成单文件、可阅读的 HTML，保留图片、图表和阅读顺序——还可选翻译成另一种语言，同时保住每一张图。PDF 是版面而不只是文本流，所以流程会先渲染每一页让你"看"清布局再组装，交付前再渲染 HTML 做视觉验证。 + +**何时使用：** +- 想把 PDF 当干净网页/文档阅读（尤其在手机上） +- 把报告/白皮书 PDF 转成有排版的 HTML 而不丢图表 +- 把 PDF 翻译成另一种语言，同时让图片、图表、表格留在原位 + +**核心特性：** +- **结构化提取**（PyMuPDF）：带字号的文本块 + 图片，自动识别并丢弃装饰图（页脚 logo、分隔线） +- **数据驱动组装**：按字号推断标题层级，内容图压缩后 base64 内嵌成单一可移植文件 +- **可选并行翻译**：用 Dynamic Workflow 并行翻译各页、为数据图表生成译注、统稿统一术语——带忠实度铁律（不给真人编译名，数字与专名照搬） +- **强制视觉验证**：自适应 headless-Chrome 截图并切成可读分段（绕开 Chrome ~16384px 截图上限） +- **内置失败案例参考**：把真实踩过的坑（验证、渲染限制、忠实度）固化，别人不必重踩 + +**使用示例：** +```bash +# pdf-to-html 属于 daymade-docs 套件 +claude plugin install daymade-docs@daymade-skills + +# 然后自然地让 Claude 做 +"把这个 PDF 转成中文网页版" +"make this report readable as HTML" +"把这份 PDF 翻成英文但保留图表" +``` + +**要求**：`uv`、Google Chrome 或 Chromium（视觉验证）。Python 依赖（PyMuPDF、Pillow、numpy）通过 `uv run --with` 自动安装。 + +--- + +### 55. **asr-transcribe-to-text** - 用 Qwen3-ASR 把音视频转文字 + +> **安装**：`claude plugin install daymade-audio@daymade-skills`（仅作为套件成员发布，调用方式 `daymade-audio:asr-transcribe-to-text`） + +用 Qwen3-ASR 把音视频文件转成文字，提供两条可互换的推理路径：macOS Apple Silicon 上的本地 MLX（无需 API key，15-27 倍实时）或任意平台的远端 vLLM/OpenAI 兼容 API。自动检测平台并推荐最佳路径，配置持久化在 `${CLAUDE_PLUGIN_DATA}/config.json`。 + +**使用场景：** +- 转写会议录音、讲座、访谈、播客或屏幕录制 +- 把任意音视频文件转成文字（语音转文字） +- 在 Apple Silicon Mac 上做本地免费转写，或本地不可用时走远端 API +- 作为「转写 → 纠错 → 纪要」流水线的第一步 + +**主要功能：** +- 双推理路径——本地 MLX（15-27 倍实时、免费）与远端 API，自动检测平台 +- 内置 `transcribe_local_mlx.py`：只加载一次模型并顺序处理多个文件（无 GPU 争用） +- 默认 `max_tokens=200000`，规避上游 `mlx-audio` 的 8192 token 截断（会静默截掉 ~40 分钟以上的音频） +- 远端兜底 `overlap_merge_transcribe.py`：切成 18 分钟片段、2 分钟重叠、模糊合并 +- ffmpeg 视频→16kHz 单声道 WAV 提取、截断校验与代理绕过处理 +- 主动建议用 `transcript-fixer` 清理输出中的 ASR 识别错误 + +**示例用法：** +```bash +# asr-transcribe-to-text 属于 daymade-audio 套件 +claude plugin install daymade-audio@daymade-skills + +# 然后自然地让 Claude 做 +"transcribe this meeting recording to text" +"把这个录音转成文字" +"convert lecture.mp4 to a transcript" +``` + +**要求**：`uv`、ffmpeg/ffprobe。本地 MLX 路径需要 macOS Apple Silicon；远端路径需要可达的 vLLM/OpenAI 兼容 ASR 端点。本地模式无需 API key。 + +--- + +### 56. **marketplace-dev** - 把技能仓库变成插件市场 + +> **安装**：`claude plugin install daymade-claude-code@daymade-skills`（仅作为套件成员发布，调用方式 `daymade-claude-code:marketplace-dev`） + +把任意 Claude Code 技能仓库转换成官方插件市场，让用户通过 `claude plugin marketplace add` 安装技能并获得自动更新。生成符合规范的 `.claude-plugin/marketplace.json`，用 `claude plugin validate` 校验，测试真实安装，并向上游仓库提 PR——把来之不易的 schema、版本与 description 反模式固化进流程。 + +**使用场景：** +- 让技能仓库可通过 `claude plugin install` 安装 +- 生成或修复 `marketplace.json`（插件分发、一键安装、自动更新） +- 向已有市场新增插件并正确 bump 版本 +- 排查 schema 报错，如 `Unrecognized key: "$schema"` 或插件名重复 + +**主要功能：** +- 证据采集阶段：挖掘文档与本地会话历史，而不是凭模板猜 +- 固化非显然的 schema 规则：`$schema` 被拒、`metadata` 只有 3 个有效字段、`strict: false` 语义、单技能 vs 套件的 `source`/`skills` 模式 +- 内置 `check_marketplace.sh` 跑四道检查（JSON 语法 → `claude plugin validate` → source/skills 解析 → 反向同步），任一必需项失败即非零退出 +- 安装测试、缓存足迹测试与 GitHub 安装测试配方，确认 `source` 产出的快照符合预期 +- 两个 PostToolUse hook（编辑 `marketplace.json` 时校验；改了 `SKILL.md` 但没 bump 版本时告警），随插件启用自动生效 + +**示例用法：** +```bash +# marketplace-dev 属于 daymade-claude-code 套件 +claude plugin install daymade-claude-code@daymade-skills + +# 然后自然地让 Claude 做 +"turn this skills repo into a plugin marketplace" +"给这个仓库生成 marketplace.json 并校验" +"把我的新 skill 加进市场并提一个 PR" +``` + +**要求**：`claude` CLI（用于 `claude plugin validate` / 安装测试）、`jq`。若要提上游 PR，需配置好 git remote。 + +--- + +### 57. **skill-creator** - 创建、改进与基准测试技能 + +> **安装**：`claude plugin install daymade-skill@daymade-skills`（仅作为套件成员发布，调用方式 `daymade-skill:skill-creator`） + +构建你自己技能的核心元技能。引导完整的「创建 → 测试 → 审阅 → 改进」循环：起草 SKILL.md、生成真实的测试 prompt、把技能跑出来与 baseline 对比、协助做定性与定量评估并迭代。还能优化技能的 `description` 以提升触发准确率。 + +**使用场景：** +- 从零创建技能，或编辑/优化已有技能 +- 跑 eval 测试技能，或做带方差分析的性能基准测试 +- 改进技能 description，让 Claude 更可靠地触发它 +- 把刚调通的第三方 CLI 工具包装成可复用的伴侣技能 + +**主要功能：** +- 跨会话历史、本地 SOP、已装插件/MCP、skills.sh、官方插件、npm/PyPI 的先验调研——复用基础设施，只把用户独有的方法论编码进技能 +- inline vs `context: fork` 决策指引（subagent 不能 spawn subagent 或调 skill）与可组合/正交的技能设计 +- `init_skill.py` 脚手架、`package_skill.py`（自动校验）、`security_scan.py`（基于 gitleaks 的密钥/PII 检测） +- Eval 工具链：并行 spawn 带技能 + baseline 运行、起草断言、评分、聚合基准、在生成的 HTML viewer 里审阅 +- 面向公开技能的强制语义通读——抓住扫描器漏掉的「无关键词」泄漏 +- description 优化循环（60/40 训练/测试切分，按 held-out 分数选最优 description） + +**示例用法：** +```bash +# skill-creator 属于 daymade-skill 套件 +claude plugin install daymade-skill@daymade-skills + +# 然后自然地让 Claude 做 +"create a skill that does X" +"优化这个 skill 的 description，让它更可靠地触发" +"把这个 skill 和无技能 baseline 做基准对比" +``` + +**要求**：Python 3、`uv`、PyYAML（校验/打包）、gitleaks（安全扫描）。eval 与 description 优化需要 `claude` CLI。 + +--- + +### 58. **feishu-doc-scraper** - 飞书/Lark → 保真 Markdown + +把飞书（Lark）文档、Wiki 页面/合集、表格以及妙记转写提取成保真的本地 Markdown。首选路径用 `lark-cli` API——以编程方式提取正文（不经模型改写）、递归跟随合集的引用图、从错误码读取权限边界；浏览器 DOM 路径只在 lark-cli 触达不到内容时作为兜底。 + +**使用场景：** +- 源是飞书/Lark URL 且要求保真（导出飞书文档/合集/妙记转写） +- 把飞书 wiki/知识库转成 Markdown，或归档一个飞书合集 +- 导出飞书妙记转写 +- 把文档所有者导出的 `.docx` 转成保真 Markdown 并恢复标题/高亮 + +**主要功能：** +- lark-cli API 提取通过 `jq` 把正文落盘（绝不经模型转抄——最重要的保真铁律） +- 用 `feishu_extract_refs.py` 做递归引用图遍历（BFS），并设残留富媒体标签验收闸，确保没有被引用的文档被静默漏掉 +- 妙记原生转写导出（绝不对下载的媒体重跑 ASR） +- 权限被拒路径：所有者导出 `.docx` → Markdown，恢复字号→标题、`w:shd`→高亮，再做视觉验证 +- 对 `*.feishu.cn` 强制 `LARK_CLI_NO_PROXY=1`（避免凭据泄漏/DNS 劫持），并做 U+FFFD 编码损坏终检 +- 同时支持飞书（feishu.cn）与 Lark（larkoffice.com） + +**示例用法：** +```bash +# 安装技能 +claude plugin install feishu-doc-scraper@daymade-skills + +# 然后自然地让 Claude 做 +"把这个飞书合集导出成 markdown" +"export this Feishu Minutes transcript" +"把这个 Lark wiki 页面存成 Markdown" +``` + +**要求**：已认证到目标租户的 `lark-cli` 二进制（npm `@larksuite/cli`）、`jq`。兜底路径需要浏览器自动化环境；docx 路径需要 `python-docx` 和一个 docx→md 转换器（内置的 doc-to-markdown 技能或 pandoc）。 + +--- + +### 59. **bigdata-skill** - Bigdata.com（RavenPack）SDK + REST 工具箱 + +通过官方 `bigdata-client` SDK 及其公开的 `/v1/*` REST 端点拉取 Bigdata.com（RavenPack）的金融与新闻数据——触达 Bigdata MCP 服务器不提供的结构化底层数据。MCP 只返回散文片段和预合成的 tearsheet；本工具箱触达结构化财务、行情、分析师预期、按日的实体情绪序列、带情绪 + 实体跨度的标注片段检索，以及选股器。 + +**使用场景：** +- 在用 Bigdata.com / RavenPack 而 MCP 结果太单薄（"情绪分在哪"、"我要实体级数据"、"日历"） +- 拉取前瞻/结构化财务：分析师预期、财报/事件日历、超预期、评级、目标价、三大报表、TTM 指标、选股器 +- 想要带数值情绪 + 实体跨度的标注新闻片段、情绪时序，或共现图 +- 提到 `bd_v2_` API key、`rp_entity_id`、`query_unit`/chunk 计费、`bigdata-client`，或"bigdata MCP 不够用" + +**主要功能：** +- 一个 `BigdataClient` 同时暴露 SDK（检索 + 知识图谱）与 REST 逃生舱（`bd._api.http`），触达 SDK 从未封装的每个 `/v1/*` 端点 +- 路由表把每类问题映射到正确模块；`fields_values_to_records()` 把 `{fields, values}` 响应拍平 +- 成本纪律：`1 query_unit = 10 chunks`、仅片段检索计费、用 `ChunkLimit`（绝不用裸 `int`）、rerank 阈值、便宜 50% 的批量检索，以及 `CostModel`/`CostTracker` 预算否决 +- "两张数据面"指引——结构化财务（A 股可经英文名/ISIN 触达）vs 非结构化中文 NLP（数据源级死路） +- 针对常见首次握手 `SSL: UNEXPECTED_EOF` 的 `rc()` 重试包装，以及带复现与修复的已知坑参考 +- `BIGDATA_API_KEY` 缺失即 fail-fast（无明文兜底）；只读，绝不写入/上传 + +**示例用法：** +```bash +# 安装技能 +claude plugin install bigdata-skill@daymade-skills +export BIGDATA_API_KEY=bd_v2_xxxxxxxx + +# 然后自然地让 Claude 做 +"pull NVIDIA's forward analyst estimates and last earnings surprise from Bigdata" +"给我这个标的按日的实体情绪序列" +"bigdata MCP 只给了 tearsheet——我要结构化字段" +``` + +**要求**：一个 `bd_v2_` Bigdata.com API key（用环境变量，绝不硬编码）、`uv`、隔离 venv 中的官方 `bigdata-client` SDK。仅当网络需要时才配出站/WSS 代理以触达 `api.bigdata.com`。 + +--- + +### 60. **gangtise-copilot** - Gangtise 投研技能套件安装器 + +为完整的 Gangtise（岗底斯投研）OpenAPI 技能套件提供一键安装器、凭据配置器和诊断层。安装全部 19 个官方 Gangtise 技能（数据、研究、工具类），用一次实时鉴权校验配置 accessKey/secretAccessKey，并跑只读健康诊断——解决该套件的核心可发现性问题（无公开 manifest、禁列目录的 OBS bucket、两条并行命名线）。 + +**使用场景：** +- 用户提到 Gangtise / 岗底斯，或任意 `gangtise-*` 技能 +- 配置 Gangtise 凭据（accessKey / secretAccessKey） +- 报错如 `token is invalid` / `接口地址错误`，或"我的 gangtise 装得不对" +- 把数据问题（研报、首席观点、OHLC、估值）路由到正确的 Gangtise 技能 + +**主要功能：** +- `install_gangtise.sh` 下载 4 个 OBS bundle → 解出 19 个技能目录 → 软链进检测到的 agent 技能目录（Claude Code、OpenClaw、Codex），含 `minimal`/`workshop`/`full`/`--only` 预设 +- `configure_auth.sh` 写一份共享 XDG 凭据文件（mode 600），跑实时鉴权调用，并把每个技能的 `.authorization` 软链到它（轮换改一份文件，而非 19 份） +- 只读 `diagnose.sh` 报告安装状态、凭据有效性与作用域能力分层（auth 作用域 vs RAG 作用域） +- 技能注册表把数据问题路由到 19 个技能构成的二维（数据层 × 操作类型）矩阵 +- 包装契约：绝不 vendor/fork 上游文件，始终重新下载规范 OBS 制品，改动任何已装技能前必先询问 + +**示例用法：** +```bash +# 安装技能 +claude plugin install gangtise-copilot@daymade-skills + +# 然后自然地让 Claude 做 +"装一下 gangtise 的所有 skill 并配置好凭据" +"my gangtise skills report token is invalid — diagnose it" +"宁德时代的研报用哪个 gangtise skill 查" +``` + +**要求**：一组 Gangtise accessKey + secretAccessKey；`bash`、`curl`、能访问官方 OBS bucket 和 `open.gangtise.com` 的网络。兼容 Claude Code、OpenClaw、Codex 的 agent 布局。 + +--- + +### 61. **llm-wiki-setup** - 共创个人投研 LLM Wiki + +共创一个个人投研 LLM Wiki（Andrej Karpathy 模式），让用户自己的分析框架长成一份活的 CLAUDE.md——靠访谈用户而不是塞给他一份模板。纯 markdown + `[[wikilink]]`，不用 RAG / 向量库（Karpathy 的核心思想——别过度工程化）。其价值在于把用户的个人投资偏好提炼进他自己的 schema，而非强加一份标准 schema。 + +**使用场景：** +- 搭建随用复利的研究知识库（投研第二大脑 / 投研知识库 / 个人投研 wiki） +- 为金融/投资实例化 Karpathy 的 LLM Wiki 模式 +- 把选股、分析师跟踪或财报观察的工作流变成结构化 markdown 库 +- 把研报 / 电话会 / 专家纪要 ingest 进已有 wiki，或做财报后「预测→兑现」复盘 + +**主要功能：** +- 清晰的机制层 vs 规则层切分：三层目录 + wikilink + lint + git hook 脚手架可照抄；分析 schema 由访谈长出，绝不套模板 +- `init_vault.py` 只 scaffold 机制层（不写 schema），再由 8 维访谈用用户自己的话写出他专属的 CLAUDE.md +- 防腐：git hook + `lint-vault.py` 保持库一致并对抗派生值漂移 +- ingest 真实源（HITL 5 卡点流程）与财报后兑现复盘的 SOP +- inline 运行（调 `analyst-track-record` 技能与 Bash），并链入 `analyst-track-record` 做分析师回测——而不重造它 + +**示例用法：** +```bash +# 安装技能 +claude plugin install llm-wiki-setup@daymade-skills + +# 然后自然地让 Claude 做 +"帮我搭一个投研第二大脑" +"build me a personal investment-research wiki in Karpathy's style" +"把这场电话会 ingest 进我的研究库" +``` + +**要求**：Python 3、`uv`（用于 `init_vault.py` / lint）、`git`。只用 markdown + wikilink——无向量库或 embedding 服务。与 `analyst-track-record` 技能配合做回测。 + +--- + +### 62. **benchmark-due-diligence** - 对标对象的对抗式尽调拆解 + +对一个你眼红的对标对象——创始人、KOL、公司或产品，其宣称的成功看着虚高——做对抗式尽调，把营销泡沫与真实信号分开，再把验证过的打法映射到你自己的资源上。它是 `deep-research` 的对抗式、决策导向版本：默认这幅图是注水的，直到被证明，并以「这对我意味着什么」收尾，而不是一份中立报告。 + +**使用场景：** +- 想尽调/对标/拆解一个竞争对手或榜样，或抄/偷师某人的打法 +- 怀疑某人宣称里有水分/泡沫（Product Hunt #1、0 到 100 万用户、融资、估值几个亿） +- 追问那些战绩是真本事还是运气/时机，或说某人太成功了、想知道真相 +- 相比 `deep-research` 的中立简报，更想要一份「祛魅 + 可复制打法」 + +**主要功能：** +- 两条严格隔离的注入通道——公开 FACTS 发给每个 agent；私有 COMMISSIONER_CONTEXT 只到达最后的映射 agent（这样委托方的客户名绝不泄漏进公网检索） +- Phase 0 以证据立地基：在任何 fan-out 之前核实对标对象的真实实体图与头条声明归属（别从名字/域名推断） +- 四阶段编排——采集 → 对抗式核验（L1-L4 分级，`坐实/存疑/证伪-水分` 裁决）→ 尽调结论（泡沫拆穿表 + 归因拆解）→ 委托方资源映射 +- 复用现有管线而非重造（`deep-research` 扇出、`osint-investigate` 身份核查、`qcc` 系列查工商、`agent-reach` 取社媒数据） +- inline 运行（它是编排器——`context: fork` 会静默打断扇出） + +**示例用法：** +```bash +# 安装技能 +claude plugin install benchmark-due-diligence@daymade-skills + +# 然后自然地让 Claude 做 +"帮我尽调一下这个创始人，他到底有没有水分" +"tear down this competitor's playbook and tell me what I can actually copy" +"这个 KOL 号称 0 到 100 万用户——是真的吗，对我可复制吗" +``` + +**要求**：采集/核验 agent 需要联网。可选与 `deep-research`、`osint-investigate`、`qcc` 技能系列、`agent-reach` 组合；通过 `pdf-creator` 渲染可分享报告。 + +--- + +### 63. **auto-repo-setup** - 自动化仓库配置与环境修复 + +把"跑不起来"变成"已经在跑"，而不要求用户懂 git、uv、ffmpeg 或 API key。为需要克隆仓库并让它跑起来的非技术同事（编辑、商务、运营）设计——也面向想要标准化、可交接的项目上手流程的技术用户。 + +**使用场景：** +- 非技术用户说"跑不起来"、"怎么启动"、"环境怎么配"或"帮我设置代码库" +- 配置新机器，或让同事上手一个代码库 +- 配置 SessionStart hook，让 Claude Code 进入时自动检查环境 +- 误泄漏密钥/路径后清理 git 历史 +- 为不常用 git 的用户处理合并冲突或 git push 失败 + +**主要功能：** +- **ONBOARDING.md 优先工作流**：读项目指南，逐步校验，迭代修补缺口 +- **SessionStart hook 生成器**：一条命令 `init_session_start_hook.py` 设好每次 Claude Code 会话进入时的自动环境检查 +- **安全护栏**：Push Safety（任何 push 前验证可见性）、PII Guard（4 层密钥扫描）、环境变量的 NO FALLBACK 原则、Git Hook Bypass 禁令 +- **对抗审查工作流**：对重大改动做多 agent 安全/代码质量/devops/文档审查 +- **内置脚本**：`check_env.py`（审计 git/ffmpeg/uv/python/.env）、`sanitize_history.sh`（扫历史中的密钥/路径/域名）、`init_session_start_hook.py` + +**示例用法：** +```bash +# 安装技能 +claude plugin install auto-repo-setup@daymade-skills + +# 然后自然地让 Claude 做 +"我跑不起来这个仓库" +"帮我设置一下这个项目的环境" +"初始化 SessionStart hook" +"git push 被拒了" +``` + +**要求**：Python 3.8+、`uv` 包管理器。技能本身无需外部 API key。 + +--- + +### 64. **bilibili-source** - 免登录 B站视频数据 + 弹幕抓取 + +一次 `view/detail` 调用、免登录地拉取任意 B站视频的可引用数据——标题、UP 粉丝数、发布时间、标签、分区、各分P 的 cid、实时互动数据（播放/点赞/投币/收藏/转发/评论/弹幕），以及完整弹幕全文。设计目标：让互动数字"取数便宜、无法伪造"，而不是手敲进文档里慢慢烂掉。 + +**使用场景：** +- 把 B站视频吸收进知识库，或做"它为什么火"的案例拆解 +- 核实创作者宣称的播放/点赞/收藏数，或要把任何 B站指标写进文档时 +- 想要弹幕全文（观众的定性反应），而不只是一个评论数 +- 粘贴 BVID、`av` 号、`b23.tv` 短链或完整 URL——全部自动识别 + +**主要功能：** +- 一个 `bili-fetch.sh` 返回全量元数据 + 实时互动 + UP 粉丝 + 标签 + 每个分P 的 cid；互动数带 `fetched_at` 时间戳（因为实时漂移） +- `bili-danmaku.sh` 拉取并解压弹幕全文；`bili-subs.sh` 处理需登录的字幕轨（动浏览器 cookie 前会先问你） +- `bili-selftest.sh` 健康自检对着真实 API 验每个端点，API 一漂移就报一行清晰 FAIL，而非静默给错数据 +- NO-FABRICATION 纪律：拿不到的数字标"未核实"，绝不估算 +- 自动剥离本地代理（B站是国内服务）、带 UA+Referer（防 HTTP 412）、失败退避重试 +- API 参考含 `space/wbi/*` 扩展所需的 WBI 签名算法 + +**示例用法：** +```bash +# 安装技能 +claude plugin install bilibili-source@daymade-skills + +# 然后自然地让 Claude 做 +"把这个 B站 视频的真实播放/点赞/收藏数拉出来，我要引用" +"这个 B站 视频弹幕里大家在说什么？" +"帮我抓这个 bilibili 视频的字幕逐字稿做总结" +``` + +**要求**：`curl`、`jq`、`python3`（弹幕解压）。`yt-dlp` 仅用于需登录的字幕路径。stats/元数据/弹幕均无需登录。 + +--- + +### 65. **claude-usage-analyst** - 解释 Claude Code Token 用量与额度消耗 + +> **安装**：`claude plugin install daymade-claude-code@daymade-skills`（套件专用——通过 `daymade-claude-code:claude-usage-analyst` 调用） + +把本地 `ccusage` 数据变成有证据、说人话的用量解释，讲清你的 Claude Code / Claude Desktop 的 token、成本、额度都花在哪了——把"观测到的数字"和"解读"分开，而不是靠猜。 + +**使用场景：** +- 想知道 Claude 额度或 5 小时块为什么被用光 +- 怀疑某个模型（`fable` / `opus` / `sonnet`）对你的工作负载是不是格外贵 +- 需要今天或某段历史窗口的 token/成本明细，含 cache 读写压力 +- 要给非技术读者解释用量，不堆没解释的术语 + +**主要功能：** +- 内置 `analyze_claude_usage.py` 按任意日期窗口和时区汇总 token、成本、输入/输出、cache 创建/读取 +- 模型对比模式（`--model-a` / `--model-b`）同时权衡 token 量和估算成本——一个模型可能单 token 便宜但总体更贵 +- 额度耗尽问题给出 5 小时块表格 +- 证据纪律：每条数值主张都以 `ccusage` 输出为准；cache 读取压力即使你没敲那些 token 也计入 +- 明确范围：`ccusage claude` 测的是本地 Claude Code 日志，不是完整的 Claude.ai 聊天账单 + +**示例用法：** +```bash +# 安装套件 +claude plugin install daymade-claude-code@daymade-skills + +# 然后自然地让 Claude 做 +"我今天的 Claude 额度为什么用光了？" +"做我这些活，opus 是不是比 sonnet 贵？" +"把我这个月的 Claude Code token 用量拆解一下" +``` + +**要求**：`ccusage`（用 `npm i -g ccusage` 或 `npx ccusage@latest`）、`python3`。 + +--- + +### 66. **marketplace-health-check** - 仓库 6 维度全面健康体检 + +```bash +claude plugin install marketplace-health-check@daymade-skills +``` + +用并行 fan-out 的 Dynamic Workflow 对这个 skills marketplace 仓库做全面、有证据的健康检查——六个 inspector 同时覆盖代码/脚本安全、文档/SSOT 一致性、安全/PII 泄露、open-PR 分类、open-issue 分类、marketplace 清单完整性——然后对严重发现先做 Counter-Review 再报告。 + +**使用场景：** +- 发版前，或任何想对仓库做一次"整体是否健康"全面扫描时 +- 检查文档/版本是否一致、PR/issue 是否已分类、PII 是否泄露进了 public skill +- 全面体检 / 检查仓库状态 / 审计一下仓库 + +**主要功能：** +- 通过 Dynamic Workflow 六个并行 inspector（每维度一个）——快且聚焦（约 15-20 分钟） +- Counter-Review：每条 high/critical 发现都先手工验证再进报告（agent 发现是假设不是结论）——既抓误报也抓错误的修复建议 +- 按优先级分级报告：必修 / backlog / 可选 / 关键洞察，每项标注真问题 vs 误报 +- 内置已验证的 workflow 脚本 + 方法论 reference（反靶子 PII 原则、当前版本 vs 历史、scan marker necessary-not-sufficient、坏 install 命令 bug 类） +- inline orchestrator——驱动 Workflow 工具，绝不 forked 运行 + +**示例用法：** +```bash +# 安装 +claude plugin install marketplace-health-check@daymade-skills + +# 然后自然地让 Claude 做 +"发版前帮我对这个仓库做一次全面健康检查" +"审计一下 marketplace——代码、文档、PII、PR、issue，全都查" +"全面体检一下这个仓库" +``` + +**要求**：`gh` CLI（已认证）、`git`、`jq`、`python3`；需 opt-in Workflow 工具（让我跑健康检查就是 opt-in）。 + +--- + ## 🎬 交互式演示画廊 想要在一个地方查看所有演示并具有点击放大功能？访问我们的[交互式演示画廊](./demos/index.html)或浏览[演示目录](./demos/)。 @@ -1801,7 +2652,7 @@ claude plugin install capture-screen@daymade-skills 使用 **github-ops** 简化 PR 创建、问题管理和 API 操作。 ### 文档处理 -结合 **markdown-tools** 进行文档转换和 **mermaid-tools** 进行图表生成，创建全面的文档。使用 **llm-icon-finder** 添加品牌图标。 +结合 **doc-to-markdown** 进行文档转换和 **mermaid-tools** 进行图表生成，创建全面的文档。使用 **llm-icon-finder** 添加品牌图标。 ### 调研与分析 使用 **deep-research** 生成格式可控的调研报告，包含证据表与引用。与 **fact-checker** 结合用于验证关键结论，或与 **twitter-reader** 结合收集社媒资料。 @@ -1822,7 +2673,7 @@ claude plugin install capture-screen@daymade-skills 使用 **skill-creator**（参见上面的[必备技能](#-必备技能skill-creator)部分）构建、验证和打包你自己的 Claude Code 技能，遵循最佳实践。 ### 演示文稿与商务沟通 -使用 **ppt-creator** 生成具有数据可视化、结构化叙事和完整 PPTX 输出的专业幻灯片，用于推介、评审和主题演讲。 +使用 **ppt-creator** 生成具有数据可视化、结构化叙事和完整 PPTX 输出的专业幻灯片，用于推介、评审和主题演讲。使用 **slides-creator** 进行叙事优先的幻灯片设计——它引导你完成 ABCDEFG 叙事框架，优先收集你的原始内容，然后将视觉生成委托给 baoyu-slide-deck。非常适合需要将现有文章、转录稿或演讲转化为视觉幻灯片的场景。 ### 视频质量分析 使用 **video-comparer** 分析压缩结果、评估编解码器性能并生成交互式比较报告。与 **youtube-downloader** 结合使用以比较不同质量的下载。 @@ -1854,6 +2705,12 @@ claude plugin install capture-screen@daymade-skills ### 会话历史与文件恢复 使用 **claude-code-history-files-finder** 从之前的 Claude Code 会话中恢复已删除的文件、在对话历史中搜索特定实现，或跟踪文件随时间的演变。对于恢复意外删除的代码或查找你记得但找不到的功能实现至关重要。 +### 续做中断的 Claude 会话 +使用 **continue-claude-work** 从本地 `~/.claude` 产物中恢复最后一个可执行请求，并在不重新打开原始会话的情况下继续实现。若还需要跨会话搜索、统计分析或恢复已删除文件，可与 **claude-code-history-files-finder** 配合使用。 + +### 网页提取与微信公众号文章 +使用 **scrapling-skill** 安装并验证 Scrapling CLI，判断应使用静态抓取还是浏览器抓取，并从 `mp.weixin.qq.com` 等页面提取干净的 Markdown。可与 **deep-research** 配合，将抓取内容整理为结构化报告，或与 **docs-cleaner** 配合清理抽取后的文章内容。 + ### 文档维护 使用 **docs-cleaner** 在保留有价值内容的同时整合冗余文档。非常适合在快速开发阶段后清理文档扩散或将重叠的文档合并为权威来源。 @@ -1867,7 +2724,7 @@ claude plugin install capture-screen@daymade-skills 使用 **iOS-APP-developer** 配置 XcodeGen 项目，处理 SPM 依赖、签名与部署问题。 ### Twitter/X 内容研究 -使用 **twitter-reader** 无需 JavaScript 渲染或身份验证即可获取推文内容。非常适合记录社交媒体讨论、归档话题、分析推文内容或从 Twitter/X 收集参考资料。与 **markdown-tools** 结合可将获取的内容转换为其他格式，或与 **repomix-safe-mixer** 结合安全地打包研究集合。 +使用 **twitter-reader** 无需 JavaScript 渲染或身份验证即可获取推文内容。非常适合记录社交媒体讨论、归档话题、分析推文内容或从 Twitter/X 收集参考资料。与 **doc-to-markdown** 结合可将获取的内容转换为其他格式，或与 **repomix-safe-mixer** 结合安全地打包研究集合。 ### macOS 系统维护与磁盘空间恢复 使用 **macos-cleaner** 以安全优先的方式智能分析和恢复 macOS 上的磁盘空间。与盲目删除的一键清理工具不同，macos-cleaner 解释每个文件是什么、按风险级别分类（🟢/🟡/🔴），并在任何删除前需要明确确认。非常适合处理 Docker/Homebrew/npm/pip 缓存膨胀的开发者、希望了解存储空间消耗的用户，或任何重视透明度而非自动化的人。结合基于脚本的精度和可选的 Mole 可视化工具集成以实现混合工作流。 @@ -1882,7 +2739,7 @@ claude plugin install capture-screen@daymade-skills 使用 **i18n-expert** 为 React/Next.js/Vue 应用程序设置完整的 i18n 基础设施、审计现有实现中缺失的翻译键，并确保 en-US 和 zh-CN 之间的语言环境一致性。非常适合向全球市场推出产品的团队、维护多语言 UI，或将硬编码字符串替换为正确的 i18n 键。与 **skill-creator** 结合使用可创建支持语言环境的技能，或与 **docs-cleaner** 结合使用可整合多种语言的文档。 ### 网络与 VPN 故障排查 -使用 **tunnel-doctor** 诊断和修复 macOS 上 Tailscale 与代理/VPN 工具的四层冲突（路由劫持、HTTP 环境变量、系统代理、SSH ProxyCommand）。当 Tailscale ping 正常但 TCP 连接失败、git push 报 "failed to begin relaying via HTTP"，或在使用 Shadowrocket、Clash、Surge 的同时设置 Tailscale SSH 到 WSL 实例时特别有用。 +使用 **tunnel-doctor** 诊断和修复 macOS 上 Tailscale 与代理/VPN 工具的多层冲突（路由劫持、HTTP 环境变量、系统代理、SSH ProxyCommand、VM/容器代理传播、DNS 解析器卡死）。当 Tailscale ping 正常但 TCP 连接失败、git push 报 "failed to begin relaying via HTTP"，或在使用 Shadowrocket、Clash、Surge 的同时设置 Tailscale SSH 到 WSL 实例时特别有用。还覆盖 **TUN 测量污染**——开着全局代理时，裸探针（`nc -z` 显示 0.00s、`ping`、国外 `ip-api` 查询）为什么会撒谎，以及该信什么。 ### 产品审计与优化 使用 **product-analysis** 进行上线前和例行产品体检，覆盖 UX、API、架构与竞品对比场景。支持 P0/P1/P2 分级建议，并可根据可量化指标输出可执行优化清单。适用于需要跨团队协作验证方向是否合理的复杂产品。 @@ -1893,6 +2750,27 @@ claude plugin install capture-screen@daymade-skills ### 插件与技能故障排除 使用 **claude-skills-troubleshooting** 诊断和解决 Claude Code 插件和技能配置问题。调试为什么插件显示已安装但未显示在可用技能列表中、了解 installed_plugins.json 与 settings.json enabledPlugins 架构，以及批量启用市场中缺失的插件。非常适合市场维护者调试安装问题、开发者调试技能激活，或任何对 GitHub #17832 自动启用 bug 感到困惑的人。 +### 腾讯 IMA 知识库工作流 +使用 **ima-copilot** 把官方腾讯 IMA skill 一键装到 Claude Code / Codex / OpenClaw 三个平台，引导配置 API 凭据，在用户授权下检测与修复上游已知问题，并在所有 IMA 知识库上跑带优先级置顶的个人化扇出搜索。因为整个架构是包装层而不是 fork，上游升级永远不会和你的修复冲突——每一次修复都是运行时指令，不是 shipped patch。特别适合同时使用多个 coding agent 的 IMA 重度用户，或遇到过 "Skipped loading skill(s) due to invalid SKILL.md" 告警的人。 + +### Claude Code 导出后处理 +使用 **claude-export-txt-better** 在归档或分享前清理 `/export` 的输出。默认导出格式在固定列宽硬换行，表格、路径、工具调用块一打开就散架。这个 skill 重建原始结构，并用 53 项自动校验立刻抓到回归。 + +### 个人数据备份（豆瓣） +使用 **douban-skill** 把豆瓣书影音历史备份到 CSV。豆瓣没有官方导出——2018 年公共 API 就关停了，所有网页抓取都被 PoW 挑战卡住。这个 skill 用官方 Android app 同一套 Frodo API，不需要登录也不需要 cookies。内置 7 个被拒方案的完整故障日志，省掉你几个小时的弯路。 + +### Terraform 与 IaC 故障排查 +使用 **terraform-skill** 当 `terraform apply` 在 provisioner 步骤失败、新实例遇到 "docker: not found"、或多环境 setup 意外共享快照时。Skill 里每一条都是*确切报错 → 根本原因 → 复制粘贴修复*三元组，来自真实事故。特别适合曾经被 cloud-init 的时序竞争、local-exec 里 rsync 连接断开、或者 Caddyfile 里硬编码域名搞掉一个周末的人。 + +### 网络、流式与协议层调试 +使用 **debugging-network-issues** 应对症状和"显然原因"对不上的场景：HTTP/2 `RST_STREAM`、SSE 在 60s/100s/130s 整点卡死、"时灵时不灵"故障、或 CDN / 代理 / CGNAT 链路上的空闲超时事件。Skill 用**分层隔离实验**（同一逻辑请求走三条以上、每条仅差一跳的路径）替代假设堆叠，再加一套反审查模式——只在假设被**证伪**而不是单纯被"证实"之后才上 fix。认知陷阱清单含反向路径/方向不对称——从错误的一端（或只从一端）测量会系统性漏掉方向性故障。 + +### 中文 TTS（StepFun 阶跃 StepAudio 2.5） +使用 **stepfun-tts** 进行中 / 日语语音合成（通过 `instruction` + 行内 `()` 控制情绪与韵律）。封装了让 StepAudio 2.5 新用户必踩的两个 TTS 破坏性变更：`voice_label` 移除和 2.5 时代更严的审查规则。可把 `step-tts-2` 作为单条审查兜底来组合使用。 + +### 长音频转写（StepFun 阶跃 StepAudio 2.5） +使用 **stepfun-asr** 单次 SSE 调用转写最长 30 分钟的中 / 英文音频（32K context、~85-101× RTF、无需客户端切片）。封装了 #1 大坑——模型**不在** `/v1/audio/transcriptions`，错端点返回误导性的 "model not supported" 错误。可与 **transcript-fixer** 组合做 ASR 纠错，或与 **meeting-minutes-taker** 把长录音变成结构化纪要。 + ## 📚 文档 每个技能包括： @@ -1904,50 +2782,60 @@ claude plugin install capture-screen@daymade-skills ### 快速链接 - **github-ops**：参见 `github-ops/references/api_reference.md` 了解 API 文档 -- **markdown-tools**：参见 `markdown-tools/references/conversion-examples.md` 了解转换场景 -- **mermaid-tools**：参见 `mermaid-tools/references/setup_and_troubleshooting.md` 了解设置指南 -- **statusline-generator**：参见 `statusline-generator/references/color_codes.md` 了解自定义 +- **doc-to-markdown**：参见 `daymade-docs/doc-to-markdown/references/conversion-examples.md` 了解转换场景 +- **mermaid-tools**：参见 `daymade-docs/mermaid-tools/references/setup_and_troubleshooting.md` 了解设置指南 +- **statusline-generator**：参见 `daymade-claude-code/statusline-generator/references/color_codes.md` 了解自定义 - **teams-channel-post-writer**：参见 `teams-channel-post-writer/references/writing-guidelines.md` 了解质量标准 - **repomix-unmixer**：参见 `repomix-unmixer/references/repomix-format.md` 了解格式规范 -- **skill-creator**：参见 `skill-creator/SKILL.md` 了解完整的技能创建工作流 +- **skill-creator**：参见 `daymade-skill/skill-creator/SKILL.md` 了解完整的技能创建工作流 - **llm-icon-finder**：参见 `llm-icon-finder/references/icons-list.md` 了解可用图标 - **cli-demo-generator**：参见 `cli-demo-generator/references/vhs_syntax.md` 了解 VHS 语法和 `cli-demo-generator/references/best_practices.md` 了解演示指南 - **cloudflare-troubleshooting**：参见 `cloudflare-troubleshooting/references/api_overview.md` 了解 API 文档 - **ui-designer**：参见 `ui-designer/SKILL.md` 了解完整的设计系统提取工作流 -- **ppt-creator**：参见 `ppt-creator/references/WORKFLOW.md` 了解 9 阶段创建流程和 `ppt-creator/references/ORCHESTRATION_OVERVIEW.md` 了解自动化 +- **ppt-creator**：参见 `daymade-docs/ppt-creator/references/WORKFLOW.md` 了解 9 阶段创建流程和 `daymade-docs/ppt-creator/references/ORCHESTRATION_OVERVIEW.md` 了解自动化 - **youtube-downloader**：参见 `youtube-downloader/SKILL.md` 了解使用示例和故障排除 - **repomix-safe-mixer**：参见 `repomix-safe-mixer/references/common_secrets.md` 了解检测到的凭据模式 - **video-comparer**：参见 `video-comparer/references/video_metrics.md` 了解质量指标解释和 `video-comparer/references/configuration.md` 了解自定义选项 -- **transcript-fixer**：参见 `transcript-fixer/references/workflow_guide.md` 了解分步工作流和 `transcript-fixer/references/team_collaboration.md` 了解协作模式 +- **transcript-fixer**：参见 `daymade-audio/transcript-fixer/references/workflow_guide.md` 了解分步工作流和 `daymade-audio/transcript-fixer/references/team_collaboration.md` 了解协作模式 - **qa-expert**：参见 `qa-expert/references/master_qa_prompt.md` 了解自主执行（100 倍加速）和 `qa-expert/references/google_testing_standards.md` 了解 AAA 模式和 OWASP 测试 - **prompt-optimizer**：参见 `prompt-optimizer/references/ears_syntax.md` 了解 EARS 转换模式、`prompt-optimizer/references/domain_theories.md` 了解理论目录和 `prompt-optimizer/references/examples.md` 了解完整转换示例 -- **claude-code-history-files-finder**：参见 `claude-code-history-files-finder/references/session_file_format.md` 了解 JSONL 结构和 `claude-code-history-files-finder/references/workflow_examples.md` 了解恢复工作流 -- **docs-cleaner**：参见 `docs-cleaner/SKILL.md` 了解整合工作流 +- **claude-code-history-files-finder**：参见 `daymade-claude-code/claude-code-history-files-finder/references/session_file_format.md` 了解 JSONL 结构和 `daymade-claude-code/claude-code-history-files-finder/references/workflow_examples.md` 了解恢复工作流 +- **docs-cleaner**：参见 `daymade-docs/docs-cleaner/SKILL.md` 了解整合工作流 - **deep-research**：参见 `deep-research/references/research_report_template.md` 了解报告结构，并参见 `deep-research/references/source_quality_rubric.md` 了解来源分级标准 -- **pdf-creator**：参见 `pdf-creator/SKILL.md` 了解 PDF 转换与字体设置 -- **claude-md-progressive-disclosurer**：参见 `claude-md-progressive-disclosurer/SKILL.md` 了解 CLAUDE.md 优化工作流 -- **skills-search**：参见 `skills-search/SKILL.md` 了解 CCPM CLI 命令和注册表操作 +- **pdf-creator**：参见 `daymade-docs/pdf-creator/SKILL.md` 了解 PDF 转换与字体设置 +- **claude-md-progressive-disclosurer**：参见 `daymade-claude-code/claude-md-progressive-disclosurer/SKILL.md` 了解 CLAUDE.md 优化工作流 +- **skills-search**：参见 `daymade-skill/skills-search/SKILL.md` 了解 CCPM CLI 命令和注册表操作 - **promptfoo-evaluation**：参见 `promptfoo-evaluation/references/promptfoo_api.md` 了解评测模式 - **iOS-APP-developer**：参见 `iOS-APP-developer/references/xcodegen-full.md` 了解 XcodeGen 选项与 project.yml 细节 - **twitter-reader**：参见 `twitter-reader/SKILL.md` 了解 API 密钥设置和 URL 格式支持 - **macos-cleaner**：参见 `macos-cleaner/references/cleanup_targets.md` 了解详细清理目标说明、`macos-cleaner/references/mole_integration.md` 了解 Mole 可视化工具集成、`macos-cleaner/references/safety_rules.md` 了解全面安全指南 -- **skill-reviewer**：参见 `skill-reviewer/references/evaluation_checklist.md` 了解完整评估标准、`skill-reviewer/references/pr_template.md` 了解 PR 模板、`skill-reviewer/references/marketplace_template.json` 了解 marketplace 配置 +- **skill-reviewer**：参见 `daymade-skill/skill-reviewer/references/evaluation_checklist.md` 了解完整评估标准、`daymade-skill/skill-reviewer/references/pr_template.md` 了解 PR 模板 - **github-contributor**：参见 `github-contributor/references/pr_checklist.md` 了解 PR 质量清单、`github-contributor/references/project_evaluation.md` 了解项目评估标准、`github-contributor/references/communication_templates.md` 了解 issue/PR 沟通模板 - **i18n-expert**：参见 `i18n-expert/SKILL.md` 了解完整的 i18n 设置工作流程、键架构指导和审计程序 -- **claude-skills-troubleshooting**：参见 `claude-skills-troubleshooting/SKILL.md` 了解插件故障排除工作流程和架构 +- **claude-skills-troubleshooting**：参见 `daymade-claude-code/claude-skills-troubleshooting/SKILL.md` 了解插件故障排除工作流程和架构 - **fact-checker**：参见 `fact-checker/SKILL.md` 了解事实核查工作流程和声明验证过程 - **competitors-analysis**：参见 `competitors-analysis/SKILL.md` 了解证据驱动的分析工作流程和 `competitors-analysis/references/profile_template.md` 了解竞品档案模板 - **windows-remote-desktop-connection-doctor**：参见 `windows-remote-desktop-connection-doctor/references/windows_app_log_analysis.md` 了解日志解析模式和 `windows-remote-desktop-connection-doctor/references/avd_transport_protocols.md` 了解传输协议详情 - **product-analysis**：参见 `product-analysis/SKILL.md` 了解工作流，参见 `product-analysis/references/synthesis_methodology.md` 了解跨代理加权与推荐逻辑 - **excel-automation**：参见 `excel-automation/SKILL.md` 了解创建/解析/控制工作流，参见 `excel-automation/references/formatting-reference.md` 了解格式规范 - **capture-screen**：参见 `capture-screen/SKILL.md` 了解基于 CGWindowID 的 macOS 截图流程 +- **continue-claude-work**：参见 `daymade-claude-code/continue-claude-work/SKILL.md` 了解本地会话产物恢复、漂移检查与续做流程 +- **scrapling-skill**：参见 `scrapling-skill/SKILL.md` 了解 CLI 工作流，参见 `scrapling-skill/references/troubleshooting.md` 了解已验证的 Scrapling 故障模式 +- **ima-copilot**：参见 `ima-copilot/SKILL.md` 了解包装层架构与路由规则，参见 `ima-copilot/references/installation_flow.md` 了解安装流程细节，参见 `ima-copilot/references/known_issues.md` 了解已知问题清单与修复命令，参见 `ima-copilot/references/search_best_practices.md` 了解扇出搜索策略与 100 条截断处理 +- **claude-export-txt-better**：参见 `daymade-claude-code/claude-export-txt-better/SKILL.md` 了解工作流，参见 `daymade-claude-code/claude-export-txt-better/scripts/fix-claude-export.py` 了解重建算法，参见 `daymade-claude-code/claude-export-txt-better/evals/` 查看真实回归 fixture +- **douban-skill**：参见 `douban-skill/SKILL.md` 了解导出工作流，参见 `douban-skill/references/troubleshooting.md` 查看 7 种被测抓取方案及失败原因的完整日志 +- **terraform-skill**：参见 `terraform-skill/SKILL.md` 查看按确切报错 → 根本原因 → 复制粘贴修复组织的实操陷阱完整目录 +- **slides-creator**：参见 `slides-creator/SKILL.md` 了解叙事优先工作流，参见 `slides-creator/references/narrative-design-guide.md` 了解 ABCDEFG 模型，参见 `slides-creator/references/content-creation-first-law.md` 了解通用内容创作原则 +- **debugging-network-issues**：参见 `debugging-network-issues/SKILL.md` 了解证伪优先工作流，参见 `debugging-network-issues/references/layered-isolation-experiment.md` 了解多跳隔离模式，参见 `debugging-network-issues/references/case-sse-rst-130s.md` 查看真实生产案例 +- **stepfun-tts**：参见 `stepfun-tts/SKILL.md` 了解 Contextual TTS 决策树，参见 `stepfun-tts/references/migration_from_v2.md` 查看 `voice_label` → `instruction` 迁移手册和审查改写清单 +- **stepfun-asr**：参见 `stepfun-asr/SKILL.md` 了解 SSE 端点工作流和 ASR 侧四个坑（错端点、Plan vs Normal key、重复幻觉、SSE `error` 事件）。`stepfun-asr/references/api_reference.md` 给出原始 HTTP 集成所需的 JSON 请求体和 SSE 事件契约 ## 🛠️ 系统要求 - **Claude Code** 2.0.13 或更高版本 - **Python 3.6+**（用于多个技能中的脚本） - **gh CLI**（用于 github-ops） -- **markitdown**（用于 markdown-tools） +- **markitdown**（用于 doc-to-markdown） - **mermaid-cli**（用于 mermaid-tools） - **VHS**（用于 cli-demo-generator）：`brew install vhs` - **asciinema**（可选，用于 cli-demo-generator 交互式录制） @@ -1963,6 +2851,10 @@ claude plugin install capture-screen@daymade-skills - **Mole**（可选，用于 macos-cleaner 可视化清理）：从 https://github.com/tw93/Mole 下载 - **uv + openpyxl**（用于 excel-automation）：`uv run --with openpyxl ...` - **macOS**（用于 capture-screen 与 excel-automation 的 AppleScript 控制流程） +- **Python 3.8+**（用于 continue-claude-work）：内置脚本进行会话提取（无外部依赖） +- **uv + Scrapling CLI**（用于 scrapling-skill）：`uv tool install 'scrapling[shell]'`，浏览器抓取前运行 `scrapling install` +- **Node.js 18+ + curl + unzip**（用于 ima-copilot）：`npx skills` 按需从 npm registry 拉取；IMA OpenAPI 凭据从 [https://ima.qq.com/agent-interface](https://ima.qq.com/agent-interface) 获取 +- **StepFun API key**（用于 stepfun-tts 和 stepfun-asr——必须是 "Normal" 等级，Plan key 调音频端点会无声失败）：在 [https://platform.stepfun.com/](https://platform.stepfun.com/) → API Keys 获取 ## ❓ 常见问题 @@ -2045,4 +2937,4 @@ claude plugin install skill-name@daymade-skills **使用 skill-creator 技能为 Claude Code 精心打造 ❤️** -最后更新：2026-01-22 | 市场版本 1.23.0 +最后更新：2026-06-05 | 市场版本 1.60.1 diff --git a/auto-repo-setup/.security-scan-passed b/auto-repo-setup/.security-scan-passed new file mode 100644 index 00000000..0cc2b8ab --- /dev/null +++ b/auto-repo-setup/.security-scan-passed @@ -0,0 +1,4 @@ +Security scan passed +Scanned at: 2026-05-31T20:17:11.595969 +Tool: gitleaks + pattern-based validation +Content hash: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 diff --git a/auto-repo-setup/SKILL.md b/auto-repo-setup/SKILL.md new file mode 100644 index 00000000..61a22c4a --- /dev/null +++ b/auto-repo-setup/SKILL.md @@ -0,0 +1,367 @@ +--- +name: auto-repo-setup +description: | + 自动化代码库环境配置、故障诊断与修复。当非技术人员（剪辑、商务、运营）拿到仓库说"跑不起来"、"怎么启动"、"环境怎么配"、"帮我设置代码库"、"初始化项目"、"提交代码"、"冲突了怎么办"时，自动读取 ONBOARDING.md、诊断环境缺口、修复依赖、验证可运行，并安全地完成 git 操作。也用于技术用户快速标准化新仓库的 setup 流程（SessionStart hook、PII Guard、历史净化、项目隔离 API key）。 + 只要用户提到"环境"、"配置"、"跑不起来"、"setup"、"启动"、"clone 下来"、"怎么运行"、"依赖"、"装好了吗"、"提交代码"、"merge conflict"、"push 失败"，就触发本 skill。 +argument-hint: "[仓库路径]" +--- + +# Auto Repo Setup — 代码库自助配置与故障修复 + +## 概述 + +本 skill 让 Claude Code 成为非技术用户的"环境医生"：用户把仓库 clone 下来或打开项目后说"跑不起来"，Claude 自动按标准流程诊断、修复、验证，无需用户理解底层技术细节。 + +同时，本 skill 也规范了技术用户搭建可移交仓库的标准动作（ONBOARDING.md、SessionStart hook、PII 安全）。 + +**目标用户**： +- 主要：非技术人员（剪辑师、商务、运营）——他们不知道什么是 uv、ffmpeg、whisper.cpp +- 次要：技术用户——标准化仓库 setup 流程，降低下游维护成本 + +--- + +## 核心工作流 + +### Step 0: 读取项目地图 + +进入任何仓库后，**第一件事**是读取以下文件（按优先级）： + +1. `ONBOARDING.md` — 项目专属 setup 指南（如果存在） +2. `README.md` — _fallback_ +3. `CLAUDE.md` — 项目级规则（如果存在） +4. `.claude/settings.json` — 检查是否有 SessionStart hook + +**如果 ONBOARDING.md 不存在**： +- 询问用户是否需要创建（基于仓库结构自动生成草稿） +- 不要在没有指南的情况下盲目猜测 setup 步骤 + +### Step 1: 环境审计（按 ONBOARDING.md 的验证步骤） + +逐条执行 ONBOARDING.md 中的 "Step X: 验证..." 或类似章节。**每执行一条必须验证输出**，不要假设成功。 + +常见检查项（根据项目类型取舍）： + +| 检查项 | 命令示例 | 失败处理 | +|--------|---------|---------| +| git 状态 | `git status` / `git remote -v` | 提示用户配置 git identity | +| 系统依赖 | `ffmpeg -version` / `which uv` | 按 ONBOARDING.md 安装 | +| Python 环境 | `uv --version` / `python --version` | 用 uv 创建 venv | +| 项目依赖 | `uv sync` / `uv pip install -e .` | 读取 pyproject.toml | +| 模型/二进制 | `ls models/` / `whisper.cpp/whisper-cli -h` | 按文档下载/编译 | +| 环境变量 | `cat .env` 检查 key 是否存在 | 指导用户填入或生成 | + +**注意**： +- 使用 `uv` 管理 Python，**禁止**用系统自带 Python +- 所有 Python 执行必须在虚拟环境或 uv 中 +- 检查命令的**退出码和 stderr**，不要只看 stdout + +### Step 2: 修复迭代 + +**调试先根因后 workaround**（铁律）： +1. 收集证据（读日志/堆栈/配置，不猜） +2. 沿调用链定位 root cause +3. 针对根因修复 +4. （可选）标注「临时」workaround 并说明为何不够 + +**禁止**： +- 看到报错就直接重装/重启 +- 用 `rm -rf` 清理（必须分析文件用途、用户确认、创建备份） +- 静默绕过错误（`|| true`、空的 except 块） + +### Step 3: 运行验证（自我验证闭环） + +修复后必须验证： +- 运行 ONBOARDING.md 中的 smoke test 或测试命令 +- 如果项目有 pytest，跑 `uv run pytest`（最小集合） +- 验证失败 → 回 Step 2，不要告诉用户"应该可以了" + +### Step 4: 交付状态汇报 + +用简洁的非技术语言告诉用户： +- ✅ 已修复什么 +- ⚠️ 还需要用户手动做什么（如填入个人 API key） +- 📋 接下来该运行什么命令（从 ONBOARDING.md 复制） + +--- + +## 安全与合规铁律 + +### 仓库可见性检查（Push Safety） + +**任何 `git push` 之前**，必须验证仓库真实可见性： + +```bash +gh repo view / --json visibility,isPrivate,stargazerCount,forkCount +``` + +- **public + 多 stars/forks** → 默认走 PR 流程（push feature branch + `gh pr create`） +- **public + 0 stars/forks 且用户明确授权** → 可 push main，但仍需 audit 内容 +- **private/internal** → push main 需用户确认，风险降一档 +- **禁止凭 URL 反推可见性**，禁止在汇报里写"私人 repo"除非 API 确认 `isPrivate: true` + +### PII Guard 与 Secret 管理 + +**public repo**（多层扫描）： +1. Layer 1 — gitleaks 标准 secret + 私有域名/IP +2. Layer 2 — 路径扫描（禁止本地生成路径） +3. Layer 3 — bash grep 兜底（中文内容、已知身份） +4. Layer 4 — AI 语义通读（前三层结构漏的无 keyword 语义私有信息） + +**private repo**： +- `.env` 可直接提交（项目隔离的 API key） +- 但仍需清理**个人绝对路径**（`/Users//`） + +**Git Hook Bypass 禁令**： +- ❌ Claude **禁止**主动使用 `--no-verify` / `--no-gpg-sign` +- ✅ 唯一例外：用户本人在当前 session 里**显式输入** `--no-verify` +- Hook 失败 → 修底层问题，不是绕过 + +### NO FALLBACK 原则 + +当系统无法确定一个值（从外部系统获取的关键字段），必须 fail-fast： + +```python +# ❌ 禁止 +apiKey: process.env.KIMI_API_KEY || 'sk-kimi-...' + +# ✅ 正确 +import os +api_key = os.environ["KIMI_API_KEY"] # KeyError if missing +``` + +- 占位符（`"your-key-here"`）只能在 `.env.example` 里，**永不**进真实代码 +- 写完 LLM/API 客户端初始化后自查：`.env` 没加载会发生什么？能看见明文吗？ + +--- + +## 标准模式 + +### ONBOARDING.md 模式 + +可移交仓库必须包含 `ONBOARDING.md`，结构： + +```markdown +# 项目名 Setup 指南 + +## Step 1: 验证系统依赖 +- [ ] git 已安装 +- [ ] ffmpeg 已安装（`ffmpeg -version`） +- [ ] uv 已安装（`uv --version`） + +## Step 2: 初始化 Python 环境 +```bash +uv sync +``` + +## Step 3: 验证安装 +```bash +uv run pytest tests/test_smoke.py -v +``` + +## Step 4: 配置环境变量 +复制 `.env` 中的占位符为真实值（private repo 可直接编辑提交） + +## Step 5: 运行项目 +[具体命令] +``` + +**要求**： +- 所有命令可直接复制执行（无个人路径、无假设） +- 使用相对路径或占位符（``） +- 包含"验证"步骤，不只是"安装"步骤 + +### SessionStart Hook 模式 + +让 Claude Code 打开仓库时自动检查环境： + +**`.claude/settings.json`**： +```json +{ + "hooks": { + "SessionStart": [ + { + "hooks": [ + { + "type": "command", + "command": ".claude/hooks/session-start-check.sh" + } + ] + } + ] + } +} +``` + +**`.claude/hooks/session-start-check.sh`**： +```bash +#!/usr/bin/env bash +CACHE_DIR="$HOME/.claude/cache/env-check" +mkdir -p "$CACHE_DIR" +REPO_HASH=$(cd "$(dirname "$0")/../.." && pwd | sha256sum | cut -d' ' -f1) +CACHE_FILE="$CACHE_DIR/$REPO_HASH" +if [ -f "$CACHE_FILE" ] && [ "$(find "$CACHE_FILE" -mtime -1 2>/dev/null)" ]; then + exit 0 +fi +touch "$CACHE_FILE" +echo "【环境自检】你刚刚进入 [项目名] 仓库。请在执行任何任务前，先阅读 ONBOARDING.md 并按 Step 1-3 验证环境。" +``` + +**一键初始化脚本**： + +Skill 自带 `scripts/init_session_start_hook.py`，可为任意项目自动生成配置： + +```bash +# 基础用法（自动推断项目名，默认读取 ONBOARDING.md） +python scripts/init_session_start_hook.py --repo /path/to/project + +# 完整用法 +python scripts/init_session_start_hook.py \ + --repo /path/to/project \ + --guide ONBOARDING.md \ + --update-gitignore +``` + +**脚本行为**： +1. 创建 `.claude/settings.json`（SessionStart hook 配置） +2. 创建 `.claude/hooks/session-start-check.sh`（24h 缓存 + 自检提示） +3. `--update-gitignore` 时追加规则，允许 `.claude/settings.json` 和 `hooks/` 入 git +4. 自动从 git remote 或目录名推断项目名 +5. 已有配置时默认跳过（`--force-overwrite` 覆盖） + +**设计原则**： +- hook 只负责**戳**agent 检查（输出提示），**不负责**复杂脚本检查 +- 24h TTL 缓存降频（用 repo path sha256 作为 cache key） +- 项目级配置，与全局 settings deep merge + +### Counter-Review Workflow + +当需要**创建新文件、修改核心配置、添加外部依赖、修改 CI/CD、变更安全策略**时，启动多 agent 审查： + +1. **并行启动 4 个 lens**（各一个 subagent）： + - security-lens：PII/secret 泄露、注入风险、权限过度 + - devops-lens：部署影响、依赖冲突、路径硬编码 + - code-quality-lens：可读性、异常处理、测试覆盖 + - doc-consistency-lens：文档与代码同步、ONBOARDING.md 更新 + +2. **Judge agent 过滤**： + - 对每条 finding 用"概率 × 成本 × 现实场景"三维过滤 + - 真实 + 低成本 → 立刻修 + - 真实 + 高成本 → 告诉用户权衡 + - 虚构 / 过度担忧 → 明说"这是过度防御，拒绝" + +3. **给用户分类汇报**：✅ 真问题 / ⚠️ 部分对 / ❌ 虚构 / 🚫 反而有害 + +--- + +## Git 操作规范 + +### 提交代码（非技术用户场景） + +用户说"帮我提交"或"保存一下"时： + +1. `git status` 看改动 +2. `git diff` 确认改动内容（向用户解释改了什么） +3. `git add`（选择性，不要无脑 `git add .`） +4. `git commit -m "..."` + - 信息用中文，描述改了什么、为什么改 + - 结尾加 `Co-Authored-By: Claude ` +5. `git push` 前走 **Push Safety** 验证 + +### 处理冲突 + +用户说"冲突了"时： + +1. `git status` 定位冲突文件 +2. 读取冲突文件的 `<<<<<<<` / `=======` / `>>>>>>>` 区块 +3. **不要自动选择某一侧**——向用户解释两边的差异，让用户决定（或按业务逻辑判断） +4. 修复后 `git add` + `git commit` + +### 历史净化（敏感信息泄露后） + +如果仓库历史中存在敏感信息（个人路径、secret、内部域名）： + +1. **评估影响范围**：哪些 commit 含敏感信息？是否已 push 到 remote？ +2. **Orphan branch + force push**（如果历史可以全部丢弃）： + ```bash + git checkout --orphan new-history + git add -A + git commit -m "Initial commit: sanitized history" + git push --force origin new-history:main + ``` +3. **BFG Repo-Cleaner**（如果需保留部分历史）：用于替换文件中的敏感字符串 +4. **通知用户**：force push 会打断其他协作者，需协调 + +--- + +## 项目隔离规范 + +### API Key 隔离 + +每个项目使用独立的 API key，禁止复用个人/生产 key： + +- 在 provider 后台为每个项目创建独立 key +- `.env` 中只放项目专属 key +- key 命名体现用途（如 `video-rough-cut-dev`） +- 定期轮转（泄露后可单独 revoke） + +### 路径清理 + +仓库中**禁止**出现： +- 个人绝对路径（`/Users//`、`/home//`） +- 内部域名/IP（`.dev`、`.pro` 等） +- 中文真实人名/项目名（用占位符替代） + +**清理方法**： +- 用占位符替换（``、``、``） +- 用相对路径替代绝对路径 +- 用 `.env` 或配置文件存储环境相关值 + +--- + +## 常见故障排查手册 + +### "uv 命令找不到" +- 检查 `~/.local/bin` 是否在 PATH +- 重新安装：`curl -LsSf https://astral.sh/uv/install.sh | sh` + +### "ffmpeg 命令找不到" +- macOS: `brew install ffmpeg` +- 或按项目文档安装 `ffmpeg-full` + +### "whisper.cpp 编译失败" +- 检查 Xcode Command Line Tools: `xcode-select --install` +- 检查 Metal 支持（Apple Silicon） + +### "pytest 大量失败" +- 先跑最小 smoke test，不要一次性跑全量 +- 检查 `.env` 是否配置了必要的 API key +- 检查测试是否依赖本地文件系统路径（应使用临时目录） + +### "git push 被拒绝" +- 检查远程仓库权限 +- 检查是否启用了 branch protection +- 走 Push Safety 流程确认仓库可见性 + +--- + +## Next Step: 代码审查与交付 + +完成环境配置和基础修复后，建议的自然下一步： + +**Options:** +A) **运行 Counter-Review** — 如果用户准备做较大改动，启动多 agent 安全审查（Recommended） +B) **生成操作文档** — 为用户生成简洁的操作指南（下一步该点什么/运行什么） +C) **No thanks** — 当前状态已足够，用户可以直接开始使用 + +--- + +## 资源目录 + +### references/ +- `git_safety.md` — Git 操作安全细则（Push Safety、Hook Bypass、历史净化） +- `pii_guard.md` — PII Guard 规则摘要与应急处理 +- `onboarding_template.md` — ONBOARDING.md 标准模板 + +### scripts/ +- `check_env.py` — 环境检查脚本（ffmpeg、uv、python、git 状态） +- `sanitize_history.sh` — 历史净化辅助脚本（检查敏感信息、生成 orphan branch） diff --git a/auto-repo-setup/references/git_safety.md b/auto-repo-setup/references/git_safety.md new file mode 100644 index 00000000..689d7155 --- /dev/null +++ b/auto-repo-setup/references/git_safety.md @@ -0,0 +1,89 @@ +# Git 操作安全细则 + +## Push Safety — 推送前必须验证仓库可见性 + +**任何 `git push`（特别推到 main/master）之前，必须用 `gh` CLI 验证目标仓库的真实可见性。** + +```bash +gh repo view / --json visibility,isPrivate,stargazerCount,forkCount +``` + +**决策矩阵**： + +| 可见性 | Stars/Forks | 操作 | +|--------|-------------|------| +| public | >0 | 默认走 PR 流程（push feature branch + `gh pr create`） | +| public | 0 + 用户明确授权 | 可 push main，但仍需 audit 内容 | +| private/internal | 任意 | push main 需用户确认，风险降一档 | + +**禁止**： +- 凭 URL 形态反推 private/public +- 凭用户名/目录路径推断 +- 在汇报里写"私人 repo"除非 API 确认 `isPrivate: true` +- 凭历史汇报或 CLAUDE.md 描述推断 + +## Git Hook Bypass 禁令 + +**Claude 禁止主动使用 `--no-verify` / `--no-gpg-sign` / `-c commit.gpgsign=false` 等绕过 git hook 的参数。** + +- ❌ Hook 失败 → 找根因修好 → **不要**"绕过试试看" +- ❌ 过去 session / 文档里的历史授权 → 不作数 +- ❌ 用户没明说，但我觉得"应该跳" → 不行，停下来问 +- ✅ 用户本人在当前 session 里**显式输入** `--no-verify` → 照办（只这一次） + +**Why**：pre-commit hook 是拦住 secret/PII/大文件的最后一道系统性防线。AI 自作主张绕过 = 防线退化为"看 AI 心情"。 + +## 历史净化（敏感信息泄露后） + +### 评估影响 + +1. 哪些 commit 含敏感信息？ +2. 是否已 push 到 remote？ +3. 是否有其他协作者？ + +### 方法选择 + +| 场景 | 方法 | 说明 | +|------|------|------| +| 历史可以全部丢弃 | Orphan branch + force push | 最干净，但打断所有协作者 | +| 需保留部分历史 | BFG Repo-Cleaner | 替换文件中的敏感字符串 | +| 仅单个文件 | `git filter-branch` / `git filter-repo` | 移除特定文件从历史 | + +### Orphan branch 流程 + +```bash +# 1. 创建无历史的新分支 +git checkout --orphan new-history + +# 2. 添加当前工作区内容 +git add -A + +# 3. 提交（注意：此时不要含敏感信息） +git commit -m "Initial commit: sanitized history" + +# 4. 强制推送到 main（会覆盖远程历史） +git push --force origin new-history:main + +# 5. 删除旧分支引用（本地） +git branch -D main +git checkout -b main origin/main +``` + +**⚠️ 警告**： +- Force push 会永久删除远程历史，其他协作者需要重新 clone +- 必须先通知用户并获得确认 +- 如果 secret 已泄露到公开网络，force push 不够——还需 revoke 并轮转 key + +## 提交规范 + +### Commit message + +- 用中文描述改了什么、为什么改 +- 技术细节可附在正文 +- 结尾加 `Co-Authored-By: Claude ` + +### 选择性添加 + +- 不要无脑 `git add .` +- `git status` 后选择性 `git add ` +- 确保 stage 的内容都是意图中的改动 diff --git a/auto-repo-setup/references/onboarding_template.md b/auto-repo-setup/references/onboarding_template.md new file mode 100644 index 00000000..562ade63 --- /dev/null +++ b/auto-repo-setup/references/onboarding_template.md @@ -0,0 +1,103 @@ +# ONBOARDING.md 标准模板 + +## 模板（复制到新项目后修改） + +```markdown +# <项目名称> Setup 指南 + +> 本指南面向非技术用户。遇到任何问题，直接问 Claude Code："跑不起来了"、"环境怎么配"。 + +## Step 1: 验证系统依赖 + +在终端运行以下命令，**每行都要运行并确认输出**： + +```bash +# 1.1 git 状态检查 +git status +# 期望：显示 "On branch main"，无未提交改动 + +# 1.2 ffmpeg 检查 +ffmpeg -version | head -1 +# 期望：显示版本号（如 "ffmpeg version 7.0"） + +# 1.3 uv 检查 +uv --version +# 期望：显示版本号（如 "uv 0.5.x"） +``` + +**任一失败 → 按下方"故障排除"修复，不要跳过。** + +## Step 2: 初始化 Python 环境 + +```bash +# 2.1 进入项目目录（如果还没进） +cd + +# 2.2 同步依赖（根据 pyproject.toml 安装） +uv sync + +# 2.3 验证安装 +uv run python -c "import ; print('OK')" +``` + +## Step 3: 配置环境变量 + +```bash +# 3.1 查看当前 .env +cat .env +``` + +- 如果值是占位符（如 `YOUR_KEY_HERE`），替换为真实值 +- private repo：直接编辑 `.env` 然后 `git add .env && git commit -m "配置环境变量"` +- public repo：**不要提交 .env**，问 Claude Code 如何处理 + +## Step 4: 运行验证测试 + +```bash +# 4.1 运行 smoke test +uv run pytest tests/test_smoke.py -v + +# 或运行项目自带验证脚本 +uv run python scripts/verify_setup.py +``` + +**全部通过 → 环境就绪。** + +## Step 5: 日常使用 + +| 任务 | 命令 | +|------|------| +| 运行项目 | `uv run python main.py` | +| 运行测试 | `uv run pytest` | +| 更新依赖 | `uv sync` | +| 提交代码 | 问 Claude Code "帮我提交" | + +## 故障排除 + +### "命令找不到"（ffmpeg / uv / git） +- macOS: `brew install ffmpeg` / `curl -LsSf https://astral.sh/uv/install.sh | sh` +- 重新打开终端，让 PATH 生效 + +### "uv sync 失败" +- 检查网络连接 +- 检查 `pyproject.toml` 是否存在 +- 问 Claude Code + +### "pytest 失败" +- 检查 `.env` 是否配置正确 +- 先跑 `tests/test_smoke.py`（最小测试），不要一次性跑全量 +- 问 Claude Code + +### "git push 被拒" +- 问 Claude Code "push 失败了" +- 不要强行用 `--force` +``` + +## 设计原则 + +1. **所有命令可直接复制执行** — 无个人路径、无假设 +2. **每步有验证** — 不只是"安装"，而是"安装后检查" +3. **相对路径或占位符** — ``、`` +4. **故障排除独立成节** — 常见问题自助，复杂问题找 Claude +5. **面向非技术用户** — 解释"期望输出是什么"、"失败了怎么办" +6. **与 Claude Code 配合** — 明确说"问 Claude Code"的场景 diff --git a/auto-repo-setup/references/pii_guard.md b/auto-repo-setup/references/pii_guard.md new file mode 100644 index 00000000..bc7ab6f7 --- /dev/null +++ b/auto-repo-setup/references/pii_guard.md @@ -0,0 +1,55 @@ +# PII Guard 规则摘要与应急处理 + +## 三层扫描架构（public repo） + +### Layer 1 — gitleaks + +标准 secret + 私有基础设施域名/IP。 + +**覆盖规则**： +- LLM provider key：`sk-kimi-` (Moonshot)、`sk-or-v1-` (OpenRouter)、`sk-ant-(api|admin)` (Anthropic)、`sk-(proj|svcacct|admin)-` (OpenAI) +- Generic `sk-` 兜底（allowlist 了占位符如 `sk-test-`/`sk-example`/`sk-your-`） +- PII：macOS 绝对路径 `/Users//`、中国手机号、个人邮箱 +- 私有基础设施：内部域名（`.dev`、`.pro` 等）+ 已知生产 IP +- 内置：AWS、GitHub PAT、Stripe 等 + +**⚠️ 注意**：gitleaks 有**熵过滤**——低熵占位符不会拦，只有高熵真实格式才拦。测试时必须用真实格式。 + +### Layer 2 — 路径扫描 + +禁止本地生成路径（coverage、node_modules 等）。 + +### Layer 3 — bash grep 兜底 + +同步 gitleaks 域名/IP 规则 + 已知身份（如中文人名）。gitleaks 不覆盖中文内容，Layer 3 补充拦截。 + +### Layer 4 — AI 语义通读 + +1-3 全是关键词/正则/grep，只命中"有人列进规则的词"。对**无 keyword 的语义私有结构性盲**（中文人名/项目名、真实转录口语片段、随手举的真实例子）——hook 必漏。 + +**push public repo 前除 hook 自动扫，必须自己 AI 通读全文做语义判断**："这名词/例子/片段，像通用占位/公开实体，还是从真实项目/人/转录拿的？" + +"grep/gitleaks 无命中" ≠ 干净。 + +## private repo 规则 + +- `.env` 可直接提交（项目隔离的 API key） +- 但仍需清理**个人绝对路径**（`/Users//`） +- 仍需清理**内部域名/IP** +- 仍需清理**中文真实人名/项目名** + +## 命中后怎么办 + +| 处理方式 | 是否允许 | +|---------|---------| +| 改规则（调 gitleaks.toml）/ 加 allowlist | ✅ | +| `--no-verify` 绕过 | ❌（除非用户本人当场打） | +| 仓库追加 `.pii-patterns` 文件定义仓库特有模式 | ✅ | +| 直接 push 不管 | ❌ | + +## 应急处理（secret 已 push） + +1. **立即 revoke key** — 在 provider 后台 disable key +2. **生成新 key** — 用新 key 替换 `.env` +3. **历史净化** — 按 `git_safety.md` 的 Orphan branch 或 BFG 流程清理 +4. **通知受影响方** — 如果 key 有访问日志，评估影响范围 diff --git a/auto-repo-setup/scripts/check_env.py b/auto-repo-setup/scripts/check_env.py new file mode 100755 index 00000000..08f0e1f1 --- /dev/null +++ b/auto-repo-setup/scripts/check_env.py @@ -0,0 +1,169 @@ +#!/usr/bin/env python3 +"""环境检查脚本 — 验证代码库运行所需的基础设施。 + +用法: + python scripts/check_env.py [--fix] + +返回码: + 0 — 全部通过 + 1 — 有缺失，但 --fix 未指定 + 2 — 修复尝试后仍有失败 +""" + +from __future__ import annotations + +import argparse +import shutil +import subprocess +import sys +from dataclasses import dataclass, field +from typing import List + + +@dataclass +class CheckResult: + name: str + passed: bool + message: str = "" + fix_cmd: str = "" + + +def run_cmd(cmd: list[str]) -> tuple[int, str, str]: + try: + r = subprocess.run(cmd, capture_output=True, text=True, timeout=30) + return r.returncode, r.stdout, r.stderr + except FileNotFoundError: + return 127, "", f"command not found: {cmd[0]}" + except Exception as e: + return 1, "", str(e) + + +def check_git() -> CheckResult: + code, out, err = run_cmd(["git", "--version"]) + if code != 0: + return CheckResult("git", False, err or "git not found", "brew install git") + return CheckResult("git", True, out.strip().split("\n")[0]) + + +def check_ffmpeg() -> CheckResult: + code, out, err = run_cmd(["ffmpeg", "-version"]) + if code != 0: + return CheckResult( + "ffmpeg", False, err or "ffmpeg not found", "brew install ffmpeg" + ) + first = out.strip().split("\n")[0] + return CheckResult("ffmpeg", True, first) + + +def check_uv() -> CheckResult: + code, out, err = run_cmd(["uv", "--version"]) + if code != 0: + return CheckResult( + "uv", + False, + err or "uv not found", + "curl -LsSf https://astral.sh/uv/install.sh | sh", + ) + return CheckResult("uv", True, out.strip()) + + +def check_python_via_uv() -> CheckResult: + code, out, err = run_cmd(["uv", "run", "python", "--version"]) + if code != 0: + return CheckResult( + "python (via uv)", + False, + err or "python not available via uv", + "uv python install", + ) + return CheckResult("python (via uv)", True, out.strip()) + + +def check_pyproject_deps() -> CheckResult: + code, out, err = run_cmd(["uv", "sync", "--locked"]) + if code != 0: + return CheckResult( + "dependencies (uv sync)", + False, + (err or out)[:200], + "uv sync", + ) + return CheckResult("dependencies (uv sync)", True, "lockfile satisfied") + + +def check_dot_env() -> CheckResult: + import os + + if not os.path.exists(".env"): + return CheckResult( + ".env file", + False, + ".env not found", + "cp .env.example .env && edit with real values", + ) + with open(".env") as f: + content = f.read() + placeholders = ["YOUR_KEY_HERE", "REPLACE_ME", "placeholder", "example"] + found = [p for p in placeholders if p.lower() in content.lower()] + if found: + return CheckResult( + ".env file", + False, + f"still contains placeholders: {found}", + "edit .env with real values", + ) + return CheckResult(".env file", True, "configured") + + +def main() -> int: + parser = argparse.ArgumentParser(description="Check repo environment") + parser.add_argument("--fix", action="store_true", help="Attempt to auto-fix issues") + args = parser.parse_args() + + checks: List[CheckResult] = [] + + # Ordered: system deps → python env → project deps → config + checks.append(check_git()) + checks.append(check_ffmpeg()) + checks.append(check_uv()) + checks.append(check_python_via_uv()) + checks.append(check_pyproject_deps()) + checks.append(check_dot_env()) + + passed = [c for c in checks if c.passed] + failed = [c for c in checks if not c.passed] + + print("=" * 50) + print("Environment Check Report") + print("=" * 50) + + for c in passed: + print(f" ✅ {c.name}: {c.message}") + + for c in failed: + print(f" ❌ {c.name}: {c.message}") + if c.fix_cmd: + print(f" Fix: {c.fix_cmd}") + + print("=" * 50) + print(f"Result: {len(passed)}/{len(checks)} passed") + + if not failed: + print("🎉 All checks passed! You're ready to go.") + return 0 + + if args.fix: + print("\n--fix specified, attempting repairs...") + # In practice, auto-fix is limited — we print suggestions + for c in failed: + if c.fix_cmd: + print(f" Run: {c.fix_cmd}") + print("Please re-run after fixing.") + return 2 + + print("\nRun with --fix to see repair commands, or ask Claude Code for help.") + return 1 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/auto-repo-setup/scripts/init_session_start_hook.py b/auto-repo-setup/scripts/init_session_start_hook.py new file mode 100755 index 00000000..d7076e18 --- /dev/null +++ b/auto-repo-setup/scripts/init_session_start_hook.py @@ -0,0 +1,178 @@ +#!/usr/bin/env python3 +"""一键初始化项目的 SessionStart hook。 + +用法: + python init_session_start_hook.py --repo /path/to/project [--guide ONBOARDING.md] [--update-gitignore] + +功能: + 1. 创建 .claude/settings.json（SessionStart hook 配置） + 2. 创建 .claude/hooks/session-start-check.sh（24h 缓存 + 环境自检提示） + 3. 可选更新 .gitignore（允许 .claude/settings.json 和 hooks/ 入 git） + +要求: + - 目标目录必须是 git 仓库（或 --force 跳过检查） + - 不会覆盖已有配置（除非 --force-overwrite） +""" + +from __future__ import annotations + +import argparse +import json +import os +import stat +import sys +from pathlib import Path + + +SETTINGS_JSON = """\ +{ + "hooks": { + "SessionStart": [ + { + "hooks": [ + { + "type": "command", + "command": ".claude/hooks/session-start-check.sh" + } + ] + } + ] + } +} +""" + +HOOK_TEMPLATE = """#!/usr/bin/env bash +# SessionStart hook for {project_name} +# 24h cache + simplified nudge — agent reads {guide_file} for actual commands. + +CACHE_DIR="$HOME/.claude/cache/env-check" +mkdir -p "$CACHE_DIR" + +# Use repo absolute path hash as cache key +REPO_HASH=$(cd "$(dirname "$0")/../.." && pwd | sha256sum | cut -d' ' -f1) +CACHE_FILE="$CACHE_DIR/$REPO_HASH" + +# Silent if checked within 24h +if [ -f "$CACHE_FILE" ] && [ "$(find "$CACHE_FILE" -mtime -1 2>/dev/null)" ]; then + exit 0 +fi + +# Create cache + output concise nudge +touch "$CACHE_FILE" +echo "【环境自检】你刚刚进入 {project_name} 仓库。请在执行任何任务前，先阅读 {guide_file} 并按 Step 1-3 验证环境。任一失败则按 {guide_file} 修复。" +""" + +GITIGNORE_RULES = """ +# Allow project-level Claude Code settings + hooks to be shared +!.claude/settings.json +!.claude/hooks/ +.claude/settings.local.json +.claude/cache/ +.claude/debug/ +""" + + +def detect_project_name(repo_path: Path) -> str: + """从目录名或 git remote 推断项目名称。""" + name = repo_path.name + git_config = repo_path / ".git" / "config" + if git_config.exists(): + try: + text = git_config.read_text(encoding="utf-8", errors="replace") + for line in text.splitlines(): + if "url =" in line: + url = line.split("=", 1)[1].strip() + # Extract repo name from git@host:owner/repo.git or https://host/owner/repo.git + if "/" in url: + part = url.rsplit("/", 1)[1] + if part.endswith(".git"): + part = part[:-4] + if part: + return part + except Exception: + pass + return name + + +def init_hook(repo_path: Path, guide_file: str, update_gitignore: bool, force_overwrite: bool, force_non_git: bool) -> int: + if not repo_path.exists(): + print(f"❌ 目录不存在: {repo_path}", file=sys.stderr) + return 1 + + if not (repo_path / ".git").exists() and not force_non_git: + print(f"❌ {repo_path} 不是 git 仓库。如需继续，加 --force-non-git", file=sys.stderr) + return 1 + + project_name = detect_project_name(repo_path) + claude_dir = repo_path / ".claude" + hooks_dir = claude_dir / "hooks" + settings_file = claude_dir / "settings.json" + hook_file = hooks_dir / "session-start-check.sh" + gitignore_file = repo_path / ".gitignore" + + # Create directories + hooks_dir.mkdir(parents=True, exist_ok=True) + + # Write settings.json + if settings_file.exists() and not force_overwrite: + print(f"⚠️ 已存在，跳过: {settings_file}") + else: + settings_file.write_text(SETTINGS_JSON, encoding="utf-8") + print(f"✅ 创建: {settings_file}") + + # Write hook script + if hook_file.exists() and not force_overwrite: + print(f"⚠️ 已存在，跳过: {hook_file}") + else: + hook_content = HOOK_TEMPLATE.format(project_name=project_name, guide_file=guide_file) + hook_file.write_text(hook_content, encoding="utf-8") + # Make executable + hook_file.chmod(hook_file.stat().st_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH) + print(f"✅ 创建: {hook_file}") + + # Update .gitignore + if update_gitignore: + if gitignore_file.exists(): + existing = gitignore_file.read_text(encoding="utf-8", errors="replace") + # Check if rules already present + if "!.claude/settings.json" in existing: + print(f"ℹ️ .gitignore 已包含 Claude 规则，跳过") + else: + with open(gitignore_file, "a", encoding="utf-8") as f: + f.write(GITIGNORE_RULES) + print(f"✅ 更新: {gitignore_file}") + else: + gitignore_file.write_text(GITIGNORE_RULES.lstrip("\n"), encoding="utf-8") + print(f"✅ 创建: {gitignore_file}") + + print("\n📋 总结:") + print(f" 项目: {project_name}") + print(f" 路径: {repo_path}") + print(f" 指南: {guide_file}") + print(f" Hook: {hook_file}") + if update_gitignore: + print(f" Gitignore: 已更新") + print("\n下次 Claude Code 进入此仓库时，SessionStart hook 会自动触发。") + return 0 + + +def main() -> int: + parser = argparse.ArgumentParser(description="Initialize SessionStart hook for a project") + parser.add_argument("--repo", required=True, help="Target repository path") + parser.add_argument("--guide", default="ONBOARDING.md", help="Guide file name to reference in hook (default: ONBOARDING.md)") + parser.add_argument("--update-gitignore", action="store_true", help="Update .gitignore to allow .claude/ files") + parser.add_argument("--force-overwrite", action="store_true", help="Overwrite existing files") + parser.add_argument("--force-non-git", action="store_true", help="Allow running on non-git directory") + args = parser.parse_args() + + return init_hook( + repo_path=Path(args.repo).resolve(), + guide_file=args.guide, + update_gitignore=args.update_gitignore, + force_overwrite=args.force_overwrite, + force_non_git=args.force_non_git, + ) + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/auto-repo-setup/scripts/sanitize_history.sh b/auto-repo-setup/scripts/sanitize_history.sh new file mode 100755 index 00000000..c4cb1181 --- /dev/null +++ b/auto-repo-setup/scripts/sanitize_history.sh @@ -0,0 +1,141 @@ +#!/usr/bin/env bash +# sanitize_history.sh — 检查并清理 git 历史中的敏感信息 +# 用法: ./sanitize_history.sh [--check-only] [--path ] +# +# 注意：此脚本只辅助检查，最终修复（orphan branch / BFG）需要人工确认后执行。 + +set -euo pipefail + +REPO_ROOT="$(pwd)" +CHECK_ONLY=false + +while [[ $# -gt 0 ]]; do + case "$1" in + --check-only) CHECK_ONLY=true; shift ;; + --path) REPO_ROOT="$2"; shift 2 ;; + *) echo "Unknown arg: $1"; exit 1 ;; + esac +done + +cd "$REPO_ROOT" + +echo "=========================================" +echo "Sanitization Check — $REPO_ROOT" +echo "=========================================" + +# 1. 检查常见敏感模式（全 git 历史） +echo "" +echo "[1/4] Scanning git history for common secrets..." + +PATTERNS=( + 'sk-[a-zA-Z0-9_-]{20,}' # API keys + 'sk-or-v1-[a-zA-Z0-9_-]+' # OpenRouter + 'sk-ant-[a-zA-Z0-9_-]+' # Anthropic + 'sk-proj-[a-zA-Z0-9_-]+' # OpenAI project + 'AK[0-9A-Za-z]{16,}' # Aliyun AK + 'ghp_[a-zA-Z0-9]{36}' # GitHub PAT + '[A-Za-z0-9/+=]{40}' # Generic long base64 +) + +FOUND_ISSUES=0 +for pat in "${PATTERNS[@]}"; do + matches=$(git log --all -p -G "$pat" -- | head -20 || true) + if [[ -n "$matches" ]]; then + echo " ⚠️ Pattern matched: $pat" + echo "$matches" | head -5 + FOUND_ISSUES=$((FOUND_ISSUES + 1)) + fi +done + +if [[ $FOUND_ISSUES -eq 0 ]]; then + echo " ✅ No common secret patterns found in history." +fi + +# 2. 检查个人绝对路径 +echo "" +echo "[2/4] Scanning for personal absolute paths..." + +PATH_PATTERNS=( + '/Users/[a-zA-Z0-9_-]+/' + '/home/[a-zA-Z0-9_-]+/' +) + +PATH_ISSUES=0 +for pat in "${PATH_PATTERNS[@]}"; do + matches=$(git log --all -p -G "$pat" -- | grep -oE "$pat" | sort -u | head -10 || true) + if [[ -n "$matches" ]]; then + echo " ⚠️ Personal paths found:" + echo "$matches" + PATH_ISSUES=$((PATH_ISSUES + 1)) + fi +done + +if [[ $PATH_ISSUES -eq 0 ]]; then + echo " ✅ No personal absolute paths found." +fi + +# 3. 检查私有域名 +echo "" +echo "[3/4] Scanning for private infrastructure domains..." + +# 扩展此列表以匹配你的私有域名 +PRIVATE_DOMAINS=( + '\.dev' + '\.pro' + '\.ai' +) + +DOMAIN_ISSUES=0 +for dom in "${PRIVATE_DOMAINS[@]}"; do + matches=$(git log --all -p -G "$dom" -- | head -10 || true) + if [[ -n "$matches" ]]; then + echo " ⚠️ Private domain found: $dom" + DOMAIN_ISSUES=$((DOMAIN_ISSUES + 1)) + fi +done + +if [[ $DOMAIN_ISSUES -eq 0 ]]; then + echo " ✅ No private domains found." +fi + +# 4. 当前工作区检查 +echo "" +echo "[4/4] Checking current working tree..." + +if git rev-parse --git-dir > /dev/null 2>&1; then + # 检查未提交的文件中是否有敏感信息 + UNCOMMITTED=$(git diff --cached --name-only || true) + if [[ -n "$UNCOMMITTED" ]]; then + echo " ℹ️ Staged files:" + echo "$UNCOMMITTED" | sed 's/^/ /' + fi +else + echo " ⚠️ Not a git repository." +fi + +echo "" +echo "=========================================" +echo "Summary: $((FOUND_ISSUES + PATH_ISSUES + DOMAIN_ISSUES)) potential issues found" +echo "=========================================" + +if [[ "$CHECK_ONLY" == true ]]; then + echo "--check-only specified. No changes made." + exit 0 +fi + +# 如果发现问题，提供修复建议 +if [[ $((FOUND_ISSUES + PATH_ISSUES + DOMAIN_ISSUES)) -gt 0 ]]; then + echo "" + echo "建议修复流程：" + echo "1. 评估影响：哪些 commit 含敏感信息？是否已 push 到 remote？" + echo "2. 在 provider 后台 revoke 已泄露的 key" + echo "3. 生成新 key 替换 .env" + echo "4. 清理历史（选一）：" + echo " A) Orphan branch（历史可全丢）：git checkout --orphan new-history" + echo " B) BFG Repo-Cleaner（保留历史）：https://rtyley.github.io/bfg-repo-cleaner/" + echo "5. 通知其他协作者重新 clone" + exit 1 +fi + +echo "✅ History looks clean." +exit 0 diff --git a/benchmark-due-diligence/.security-scan-passed b/benchmark-due-diligence/.security-scan-passed new file mode 100644 index 00000000..34950f8c --- /dev/null +++ b/benchmark-due-diligence/.security-scan-passed @@ -0,0 +1,4 @@ +Security scan passed +Scanned at: 2026-05-30T19:16:23.677752 +Tool: gitleaks + pattern-based validation +Content hash: 930661d0365e03f3b13c11db2db0a692b2d3db369b8cc184219cfd6189486f05 diff --git a/benchmark-due-diligence/SKILL.md b/benchmark-due-diligence/SKILL.md new file mode 100644 index 00000000..4082f6d5 --- /dev/null +++ b/benchmark-due-diligence/SKILL.md @@ -0,0 +1,109 @@ +--- +name: benchmark-due-diligence +description: > + Runs adversarial due-diligence on a benchmark the user envies — a founder, KOL, + company, or product whose claimed success looks inflated — splitting marketing + bubble from real signal, then mapping the validated playbook onto the user's own + resources. Use whenever the user wants to 尽调/对标/拆解 a competitor or role-model, + 抄/偷师 someone's playbook, suspects 水分/泡沫 in their claims (#1 on Product Hunt, + 0-to-1M users, funding, 估值几个亿), asks whether wins are 真本事 vs 运气/时机, or says + someone is 太成功了/crushing it and wants the real story — even if they never say 尽调. + Prefer over deep-research for debunking inflated claims and extracting a replicable + playbook rather than a neutral briefing. +--- + +# Benchmark Due Diligence + +Take a benchmark the user envies — a founder, KOL, company, or product whose success looks suspiciously shiny — and produce a teardown that ends in **"what this means for ME"**, not a neutral report. The deliverable answers three questions a balanced briefing never does: *How much of this success is real vs marketing bubble? How much is replicable method vs luck/timing? And what, specifically, can the commissioner do with it?* + +This is the adversarial, decision-oriented cousin of `deep-research`. Where deep-research builds a trustworthy picture of the world, this skill **assumes the picture is inflated until proven otherwise** and converts the survivors into the commissioner's own moves. + +## CRITICAL: run inline, never `context: fork` + +This skill is an **orchestrator** — it spawns parallel collection + verification agents (via the `Workflow` tool, or `Task` agents) and may invoke other skills (`deep-research`, `osint-investigate`, `qcc`). Subagents cannot spawn subagents or call skills. Setting `context: fork` would silently break the entire fan-out. **Do not add a `context` field.** (Same constraint osint-investigate documents — it's a hard runtime rule, not a preference.) + +## The one rule that protects the commissioner: two injection channels + +Everything the agents see flows through exactly two channels. Keeping them separate is the single most important discipline in this skill: + +| Channel | Content | Injected into | +|---|---|---| +| **FACTS** | Already-verified *public* facts about the benchmark (relationships, who-owns-what, the headline claim flagged `⚠️ to-verify`) | **Every** agent — collection, verification, synthesis | +| **COMMISSIONER_CONTEXT** | The commissioner's *private* reality — real resources, client names, strategic intent, what they can actually leverage | **Only the final mapping agent (Phase 4)** | + +**Why this split is non-negotiable:** collection and verification agents take their input and run external `WebSearch` on it. If the commissioner's client names or strategy leak into those prompts, they get searched on the open web — a privacy breach. The mapping phase genuinely needs "who is the commissioner"; the collection phase must never see it. Encode this in the orchestration (see `references/workflow_orchestration_template.md`), don't rely on remembering it mid-run. + +## Phase 0 — nail the foundation by evidence, not appearance (do this BEFORE any agent) + +The fastest way to waste a 12-agent fan-out is to build it on a foundation you *inferred from appearances*. Two failure modes recur and both have burned real runs: + +1. **Inferring relationships between entities from names/domains.** "Their content lives at `academy.example.com`, and they're the founder, so they must own that community" — when in reality they were just an invited guest. A shared domain, a similar name, or co-occurrence is an **observation**, not ownership. Verify with an authoritative source before treating any A↔B relationship as fact. +2. **Treating the commissioner's *client* as the commissioner's *asset*.** If the commissioner does service work for an accelerator/brand, that accelerator is the *client's* asset — the commissioner can't leverage its audience or capital. Mapping the benchmark's playbook onto resources the commissioner doesn't actually control produces castles in the air. + +So before fanning out, establish by evidence (not vibes): +- **The benchmark's real entity graph** — who owns whom, who merely partners/guests. Don't reason from names. +- **The headline-claim attribution** — the benchmark's whole narrative usually rests on one trophy stat ("took product X from 0 → 1M users"). Are they the founder, or the *departed growth lead*? This is the **#1 to-verify target**; write it into FACTS with a `⚠️`. +- **What the commissioner truly controls** — separate *owned assets* from *client/partner assets*. + +Write the results into `FACTS` (public half) and `COMMISSIONER_CONTEXT` (private half). A shaky foundation makes every downstream agent confidently wrong. + +## The four-phase orchestration + +Use the `Workflow` tool (preferred — deterministic fan-out, see the ready-to-fill template in `references/workflow_orchestration_template.md`) or `Task` agents. Scale agent count to how thorough the user wants (a few dimensions for a quick read, 6+ with multi-vote verification for a deep audit). + +**Phase 1 + 2 — collect → verify, per dimension, as a pipeline** (each dimension verifies the moment its collection finishes; no global barrier): + +- **Collection agent** — *objective* stance. Every finding carries a source URL and a `source_kind` (`对象自述/营销` vs `第三方独立信源` vs `混合`). Anything not found goes in `gaps` — **never** filled by guessing. +- **Verification agent** — *adversarial, default-skeptical* stance. Grade every claim `L1–L4` and rule `坐实 / 大体可信 / 存疑 / 证伪-水分`. The job is to actively hunt **falsifying** evidence, especially for the headline claims (the trophy stat, "#1 ranking", funding amount, user counts). `bubble_summary` names the biggest water in that dimension. + +Grading rubric, `source_kind`, verdicts, and both JSON schemas → **`references/evidence_grading_rubric.md`**. + +Typical dimensions (tailor to the benchmark type — person / company / product): +1. Subject background **+ headline-claim attribution** (the #1 bubble target) +2. Corporate base — entity, founding, funding/valuation +3. Core product/business **real metrics** — user counts, revenue, rankings, awards, cross-verified against third parties +4. Playbook teardown — platform matrix, persona, content types, how they borrow other people's audiences, how personal IP funnels to the product +5. Comparison sample — a structurally-similar peer or parallel path +6. Sector + how this class of playbook usually wins **and usually fails** + +**Phase 3 — synthesis: due-diligence conclusion** (single agent, consumes all verdicts): +1. Real relationship map (correcting the common misreadings from Phase 0) +2. **Bubble-busting table** — claim | evidence level | verdict | one-line basis, sorted by most-water-first +3. Playbook teardown — concrete, copyable actions +4. **Attribution breakdown (the core)** — what share of the success is product vs market-timing vs personal-IP-marketing vs operations? Give % ranges with reasons, and explicitly split *replicable method* from *luck / timing / non-transferable endowment*. + +**Phase 4 — synthesis: what this means for the commissioner** (single agent; consumes Phase 3 **+ COMMISSIONER_CONTEXT**): +1. **Resource-mapping table** — benchmark's playbook elements × the commissioner's real resources; tag each cell ✅ borrow-able / ⚠️ not-replicable (luck/timing) / 🔄 already-doing / 🚫 bubble-don't-copy, one line each +2. Landing points — exactly how the commissioner uses it (their to-B service / their own IP / their tooling) +3. Action list + open questions (what's still unconfirmed) + +Attribution weighting and the four-tag mapping framework → **`references/attribution_and_resource_mapping.md`**. + +## Don't rebuild what already exists + +This skill's edge is the *adversarial bubble-busting + attribution + commissioner-mapping* layers. The plumbing underneath is not novel — reuse it: + +- **Fan-out collection / source governance** — borrow the lead-agent + subagent pattern from `deep-research`. (What's unique here is the skeptical verification stance and the L1–L4 bubble grading, not the parallelism.) +- **Person-subject identity / footprint checks** — invoke `osint-investigate` (ACH hypothesis matrix, Bellingcat-style pivots) rather than re-deriving identity attribution. +- **Mainland-China corporate registration / funding** — invoke the `qcc` family of skills for 工商 data. +- **Social-platform playbook data** — the `agent-reach` CLI covers B站/小红书/抖音/YouTube/X. + +## Read before you run + +- **`references/evidence_discipline_traps.md`** — the recurring traps (inferring relationships from appearances, headline-claim attribution, client-vs-asset, foundation-before-fan-out, grade-don't-binary, privacy leak) with real teardown war-stories. Read this first; it's where runs actually break. +- **`references/evidence_grading_rubric.md`** — L1–L4, source_kind, verdicts, collection/verification schemas. +- **`references/attribution_and_resource_mapping.md`** — attribution weighting + four-tag mapping + landing-point framework. +- **`references/workflow_orchestration_template.md`** — a ready-to-fill `Workflow` script with the FACTS / COMMISSIONER_CONTEXT injection split already wired in. + +## Next Step + +After the due-diligence conclusion is ready, suggest the natural follow-on (opt-in, never auto-run): + +``` +Due-diligence teardown is done. + +Options: +A) Render it as a shareable PDF report — pdf-creator (Recommended if this goes to a partner/team) +B) One dimension needs deeper neutral background — deep-research on that sub-topic +C) No thanks — the markdown teardown is enough +``` diff --git a/benchmark-due-diligence/references/attribution_and_resource_mapping.md b/benchmark-due-diligence/references/attribution_and_resource_mapping.md new file mode 100644 index 00000000..3e77c852 --- /dev/null +++ b/benchmark-due-diligence/references/attribution_and_resource_mapping.md @@ -0,0 +1,53 @@ +# Attribution & Resource Mapping + +The frameworks for Phase 3 (attribution) and Phase 4 (mapping onto the commissioner). This is where a teardown stops being "interesting research" and becomes "a decision." + +## Contents +- Attribution weighting (Phase 3) +- Replicable vs not +- Four-tag resource mapping (Phase 4) +- Landing points +- The one-line verdict + +## Attribution weighting (Phase 3) + +Once the bubble is busted, the core question is: **of the success that's actually real, how much comes from each factor?** Weight four factors, give each a % range with reasons that cite the verdicts' evidence levels: + +| Factor | What it captures | +|---|---| +| **Product strength** (产品力) | Does the product/service genuinely win on merit? Often the thinnest-evidence factor — moat narratives are usually L1 self-report | +| **Market timing** (赛道时机) | Did they ride a wave (a funding hype cycle, a platform moment)? Timing is **not replicable** | +| **Personal-IP marketing** (创始人IP营销) | The founder/KOL's own audience-building and narrative engine | +| **Operations / community** (运营/社区) | Sustained execution, community flywheel, retention machinery | + +The output is a table of weights + a sharp split between **replicable method** and **non-replicable luck/timing/endowment**. + +**Worked example (anonymized):** an AI-tool founder's growth attributed roughly as — market timing 25-35% (rode a funding hype cycle, *not replicable*) + personal-IP marketing 30-40% (the *moves* are replicable, but the *numbers* were inflated) + product strength 10-20% (narrative exceeds independent validation) + community 5-10%. One-liner: **the moves are real, the numbers are inflated, the timing is unrepeatable.** + +## Replicable vs not + +For every attribution factor, label each component: + +- **Replicable method** (learn-able) — a concrete, transferable action framework +- **Not replicable** (luck / timing / endowment) — hype-cycle dividend, a specific personal background, or **the magnitude of the inflation itself** + +That last point matters: the inflation is a *liability to inherit*, not a method to copy. Replicating "claim 1M users when it was 500K" doesn't transfer the growth — it transfers the reputational risk that collapses when someone checks. + +## Four-tag resource mapping (Phase 4) + +A table: each playbook element (rows) × each of the commissioner's resources (columns). Tag every cell: + +- ✅ **borrow-able** — the commissioner can directly reuse this move +- ⚠️ **not-replicable** — luck / timing / resource mismatch; looks tempting but won't transfer +- 🔄 **already-doing** — the commissioner already has this; confirm, don't "add" it +- 🚫 **bubble-don't-copy** — inflation / reputational backfire; explicitly refuse + +One line of reasoning per cell. The ⚠️ and 🚫 cells are as valuable as the ✅ ones — they stop the commissioner from betting on the parts that won't work. + +## Landing points + +Mapping is abstract until it lands on **exactly how the commissioner uses it**. Organize landing points by the commissioner's resource types (e.g. their to-B service offering, their own personal IP, their tooling). For each, give 3-5 actions the commissioner can execute *next*, not someday. Anything that depends on an asset the commissioner doesn't own (Trap 3) is not a valid landing point. + +## The one-line verdict + +Close every teardown with a single memorable line that compresses bubble + attribution into something the commissioner can repeat from memory. Shape: **"the moves are real, the numbers are inflated; what you can steal is [the 2-3 action frameworks], what you can't is [the timing and the inflation]."** If you can't compress it to one line, the attribution isn't sharp enough yet. diff --git a/benchmark-due-diligence/references/evidence_discipline_traps.md b/benchmark-due-diligence/references/evidence_discipline_traps.md new file mode 100644 index 00000000..56cdaedf --- /dev/null +++ b/benchmark-due-diligence/references/evidence_discipline_traps.md @@ -0,0 +1,53 @@ +# Evidence Discipline Traps + +Real failure modes that have broken benchmark-DD runs. Read this first — it's where runs actually go wrong, and every trap is cheap to avoid and expensive to recover from. + +## Contents +- Trap 1: inferring relationships from appearances +- Trap 2: the headline-claim attribution +- Trap 3: client ≠ commissioner's asset +- Trap 4: foundation before fan-out +- Trap 5: grade, don't binary +- Trap 6: privacy leak into external search + +## Trap 1 — inferring relationships between entities from names/domains + +**The trap:** the benchmark's content lives at `community.example.com`, they're a well-known founder, so you write "they run that community" into FACTS. The downstream agents inherit it and confidently build on a relationship that doesn't exist. + +**War-story (anonymized):** a founder appeared to "own" a popular paid AI community because their viral post lived there. They were in fact an *invited guest*; the community belonged to a different educator entirely. Treating the guest spot as an owned channel inverted the whole competitive picture — and it was caught only because someone re-read the source and noticed the post literally said "[the community host] invited me to share." + +**The rule:** a shared domain / similar name / co-occurrence is an **observation**, not **ownership**. Before any A↔B relationship enters FACTS, verify it against an authoritative source. Always distinguish "I observed X near Y" from "X owns Y." + +## Trap 2 — the headline-claim attribution is the #1 target + +**The trap:** the benchmark's entire IP narrative rests on one trophy stat, and you take it at face value because it's repeated everywhere — but "everywhere" is the same PR reprinted N times. + +**War-story:** the headline was "took product X from 0 → 1M users in a year." Verification found the person was the **departed head of growth**, not the founder; the real founder was someone else (the product's own makers list and registry proved it), and an independent outlet said "3 months to 500K," not "1 year to 1M." The trophy stat was borrowing a former employer's achievement, inflated on top. + +**The rule:** find the one claim the subject's whole story depends on, flag it `⚠️ to-verify` in FACTS, and make verifying its *attribution* (who actually did it) and its *magnitude* the highest-priority task in the whole run. Check the product's own about page, the registry, the Product Hunt makers list, LinkedIn — anything **except** the subject's own bio. + +## Trap 3 — the commissioner's client is not the commissioner's asset + +**The trap:** the commissioner does service work for a big-name platform, so you map the benchmark's "leverage your audience" playbook onto that platform's audience. But the commissioner is a *vendor*, not the owner — they can't pull those levers. + +**War-story:** a teardown mapped a benchmark's community-flywheel playbook onto an accelerator the commissioner appeared associated with. The commissioner was actually a paid service provider to that accelerator — they couldn't touch its enrollment or capital. The whole "what you can do" section was advice the commissioner literally could not execute, and had to be rewritten once the ownership was corrected. + +**The rule:** in Phase 0, hard-split the commissioner's **owned assets** from **client/partner assets**. Only owned assets are valid mapping targets in Phase 4. + +## Trap 4 — establish the foundation before you fan out, not after + +**The trap:** excited to start, you launch the multi-agent fan-out, then discover mid-run that two entities you told the agents were related actually aren't. Every result is now contaminated and the run has to be redone. + +**The rule:** Phase 0 (verify the entity graph + headline attribution + commissioner resources) happens *before* the orchestration. It's a handful of authoritative lookups that save an entire re-run. Foundation first, fan-out second — never the reverse. + +## Trap 5 — grade, don't binary + +**The trap:** the user is suspicious ("it's all bubble"), so the run reflexively debunks everything; or the opposite, it treats the survivors as fully proven. Both lose the signal. + +**The rule:** the deliverable's value is *separating* real signal from water, not picking a side. Apply the L1–L4 + verdict ladder per-claim (see `evidence_grading_rubric.md`). The best teardowns conclude "the moves are real, the numbers are inflated" — a nuance that only exists if you resist judging the subject as a monolith. + +## Trap 6 — never let commissioner context leak into external search + +**The trap:** to give the collection agents "context," you paste the commissioner's situation — including client names and strategy — into their prompts. Those agents then run `WebSearch` on it, and the commissioner's private business becomes a query on the open web. + +**The rule:** the two-channel split (see SKILL.md) is a hard wall. FACTS (public, about the benchmark) → all agents. COMMISSIONER_CONTEXT (private) → only the Phase-4 mapping agent, which does no external search. Wire it into the orchestration so it cannot be forgotten mid-run — don't rely on remembering it. diff --git a/benchmark-due-diligence/references/evidence_grading_rubric.md b/benchmark-due-diligence/references/evidence_grading_rubric.md new file mode 100644 index 00000000..11c934fd --- /dev/null +++ b/benchmark-due-diligence/references/evidence_grading_rubric.md @@ -0,0 +1,113 @@ +# Evidence Grading Rubric + +How collection and verification agents tag and judge every claim. This is the machinery that turns "they say they're #1" into "category award + monthly #1, the annual-#1 claim is debunked." + +## Contents +- Two stances: objective collection vs adversarial verification +- source_kind (set during collection) +- Evidence levels L1–L4 (set during verification) +- Verdicts +- The grading discipline: grade, don't binary +- JSON schemas (collection + verification) + +## Two stances + +Collection and verification run as **separate agents with opposite postures**. Never merge them — an agent told to both gather and judge rationalizes what it found. + +| | Collection agent | Verification agent | +|---|---|---| +| Stance | Objective — gather what's out there | Adversarial — default-skeptical, hunt for water | +| Goal | Coverage + provenance | Falsification | +| Output | findings + source_kind + gaps | verdicts (L1–L4 + ruling) + bubble_summary | +| Tools | WebSearch / WebFetch / agent-reach / qcc | Same, but aimed at finding *disconfirming* evidence | + +## source_kind (set during collection) + +Tag every finding by where it came from — this is what later lets the verifier weight it: + +- `对象自述/营销` (self-reported / marketing) — the subject's own blog, pitch deck, PR wire, founder interview. Treat as **claims**, not facts. +- `第三方独立信源` (independent third party) — registries, audited data, reporting that is not a reprint of the subject's PR. +- `混合` (mixed) — e.g., a media article that quotes the subject's numbers without independent verification. + +## Evidence levels L1–L4 (set during verification) + +| Level | Meaning | +|---|---| +| **L4** | Hard data directly checkable — corporate registry, runtime observation, third-party audited figures, the platform's own official records | +| **L3** | Multiple *independent* sources agree (not reprints of the same press release) | +| **L2** | A single credible third-party source | +| **L1** | Only the subject's own statement / marketing / no independent corroboration | + +Bubble-busting is the act of moving a claim *down* from its self-asserted level. A "#1 of the year" asserted at L1 (the subject's bio) routinely collapses to "category award + a monthly #1" once checked against the platform's own award records at L4. + +## Verdicts + +- `坐实` (confirmed) — L3/L4 backs it +- `大体可信` (largely credible) — plausible, partially corroborated, minor gaps +- `存疑` (doubtful) — single-source / unfalsifiable / internal contradictions +- `证伪-水分` (debunked — water) — falsifying evidence found; the claim is inflated or wrong + +## The grading discipline: grade, don't binary + +The point is **not** to declare the benchmark a fraud. Most envied benchmarks are *real success wrapped in inflated storytelling* — and the trap cuts both ways: naive belief AND reflexive cynicism both destroy the signal. The verdict ladder forces the middle path: confirm what's solid, debunk what's water, mark the rest doubtful. A strong teardown's one-liner is usually shaped like **"the moves are real, the numbers are inflated"** — a nuance that only survives if you grade each claim instead of judging the subject as a monolith. + +## JSON schemas + +Pass these as the `schema` option to each agent so the model is forced to return validated structure. + +**Collection output:** + +```json +{ + "type": "object", + "additionalProperties": false, + "properties": { + "dimension": { "type": "string" }, + "findings": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": false, + "properties": { + "claim": { "type": "string", "description": "one fact or asserted claim" }, + "detail": { "type": "string" }, + "sources": { "type": "array", "items": { "type": "string" }, "description": "source URLs" }, + "source_kind": { "type": "string", "enum": ["对象自述/营销", "第三方独立信源", "混合"] } + }, + "required": ["claim", "detail", "sources", "source_kind"] + } + }, + "gaps": { "type": "string", "description": "not-found / doubtful, to fill later — NEVER guessed" } + }, + "required": ["dimension", "findings", "gaps"] +} +``` + +**Verification output:** + +```json +{ + "type": "object", + "additionalProperties": false, + "properties": { + "dimension": { "type": "string" }, + "verdicts": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": false, + "properties": { + "claim": { "type": "string" }, + "evidence_level": { "type": "string", "enum": ["L4", "L3", "L2", "L1"] }, + "verdict": { "type": "string", "enum": ["坐实", "大体可信", "存疑", "证伪-水分"] }, + "reasoning": { "type": "string" }, + "cross_sources": { "type": "array", "items": { "type": "string" }, "description": "URLs actually checked while verifying" } + }, + "required": ["claim", "evidence_level", "verdict", "reasoning", "cross_sources"] + } + }, + "bubble_summary": { "type": "string", "description": "the biggest water in this dimension" } + }, + "required": ["dimension", "verdicts", "bubble_summary"] +} +``` diff --git a/benchmark-due-diligence/references/workflow_orchestration_template.md b/benchmark-due-diligence/references/workflow_orchestration_template.md new file mode 100644 index 00000000..b72413ae --- /dev/null +++ b/benchmark-due-diligence/references/workflow_orchestration_template.md @@ -0,0 +1,108 @@ +# Workflow Orchestration Template + +A ready-to-fill `Workflow` script for the four-phase fan-out. Fill the placeholders (`AS_OF`, `FACTS`, `COMMISSIONER_CONTEXT`, `DIMENSIONS`), keep the injection split intact, and run it via the `Workflow` tool. The schemas live in `evidence_grading_rubric.md` — paste them in or reference them. + +## The injection split (the thing you must NOT break) + +- `FACTS` → every agent (collection, verification, synthesis A) +- `COMMISSIONER_CONTEXT` → **only** synthesis B (the mapping agent), which does no external search + +Collection/verification agents run `WebSearch` on their prompt. If commissioner context reaches them, it's searched on the open web. This is Trap 6. + +## Template + +```javascript +export const meta = { + name: 'benchmark-dd', + description: '', + phases: [ + { title: '采集' }, { title: '验证' }, + { title: '综合-尽调结论' }, { title: '综合-对你的应用' }, + ], +} + +const AS_OF = '' // stamp freshness; pass it in (Date.now() is unavailable in workflow scripts) + +// PUBLIC verified facts about the benchmark — injected into ALL agents. +// Flag the headline trophy claim with ⚠️ as the #1 to-verify target (Trap 2). +const FACTS = [ + '【已核实地基事实（截至 ' + AS_OF + '）。站在此基础上深挖，不推翻已验证项，但为 ⚠️ 项找独立硬证据】', + '- ', + '- ⚠️ ', +].join('\n') + +// PRIVATE commissioner reality — injected into the Phase-4 mapping agent ONLY. +const COMMISSIONER_CONTEXT = [ + '【委托人真实资源与诉求 —— 仅映射阶段可见，禁入外部搜索】', + '- owned assets (valid mapping targets): <...>', + '- client/partner assets (NOT leverageable — Trap 3): <...>', + '- what they want to steal / the decision they face: <...>', +].join('\n') + +const COLLECT_SCHEMA = { /* see evidence_grading_rubric.md */ } +const VERIFY_SCHEMA = { /* see evidence_grading_rubric.md */ } + +const DIMENSIONS = [ + { key: 'subject-bio', label: 'subject background + headline-claim attribution', focus: '... ★ verify WHO actually did the trophy stat, and its real magnitude' }, + { key: 'corp-base', label: 'corporate base + funding', focus: 'entity, founding, funding/valuation; qcc for mainland-China subjects' }, + { key: 'product-metrics', label: 'core product real metrics (bubble-bust)', focus: 'cross-verify user counts / revenue / rankings / awards against third parties' }, + { key: 'playbook', label: 'playbook teardown', focus: 'platform matrix / persona / how they borrow others’ audiences / IP→product funnel; agent-reach for socials' }, + { key: 'comparison', label: 'comparison sample', focus: 'a structurally-similar peer or parallel path' }, + { key: 'sector-peers', label: 'sector + same-class playbook', focus: 'how this class of playbook usually wins AND usually fails' }, +] + +log('Phase 1+2: fan-out collect → adversarial verify (bubble-bust)') +const verified = await pipeline( + DIMENSIONS, + (d) => agent( + '你是尽职调查研究员，立场客观、只认证据。维度：' + d.label + '\n\n' + FACTS + + '\n\n【本维度要砸实】\n' + d.focus + + '\n\n【工具】优先 WebSearch/WebFetch；可 Bash 调 agent-reach(社媒) / qcc(工商) 增强，调不通回退，不卡死。' + + '\n【纪律】每条 finding 带 source URL + source_kind；查不到写 gaps，禁脑补。', + { label: '采集:' + d.key, phase: '采集', schema: COLLECT_SCHEMA, agentType: 'general-purpose' } + ), + (collected, d) => agent( + '你是对抗性核查员，默认怀疑，专找水分。逐条打证据等级+裁决。\n维度：' + d.label + + '\n采集结果：\n' + JSON.stringify(collected) + + '\n【L4=硬数据可查实 / L3=多独立信源一致 / L2=单一可信第三方 / L1=仅自述营销】' + + '\n【裁决 坐实/大体可信/存疑/证伪-水分】主动找证伪证据，尤其 headline 战绩/榜单/融资/用户量。bubble_summary 点最大水分。', + { label: '验证:' + d.key, phase: '验证', schema: VERIFY_SCHEMA, agentType: 'general-purpose' } + ) +) +const clean = verified.filter(Boolean) + +phase('综合-尽调结论') +const partA = await agent( + '资深行业分析师。基于核查结果产出"尽调结论"(中文 markdown)。\n\n' + FACTS + + '\n核查结果：\n' + JSON.stringify(clean) + + '\n## 一、真实关系图（已核实，纠正常见误解）' + + '\n## 二、破泡沫核查表（宣称|证据等级|裁决|依据，水分从大到小）' + + '\n## 三、打法拆解（可操作动作）' + + '\n## 四、归因拆解（产品/时机/IP/运营各占%；可复制 vs 运气/时机/禀赋）' + + '\n要求：用证据说话引用 evidence_level；不确定标存疑，禁补细节。', + { label: '综合:尽调结论', phase: '综合-尽调结论' } +) + +phase('综合-对你的应用') +const partB = await agent( + '委托人战略顾问，犀利只给能落地的判断。基于尽调结论+委托人资源产出"对你的应用"。\n【尽调结论】\n' + partA + + '\n\n' + COMMISSIONER_CONTEXT + // <-- the ONLY place this is injected + '\n## 五、资源映射表（打法要素 × 委托人资源；✅可借鉴/⚠️不可复制/🔄已在做/🚫泡沫别学）' + + '\n## 六、落点：委托人具体怎么用（每落点 3-5 个可执行动作）' + + '\n## 七、行动建议 + 存疑项' + + '\n要求：紧扣委托人真实资源，禁把客户当委托人自有资产；不说正确的废话。', + { label: '综合:应用建议', phase: '综合-对你的应用' } +) + +return { partA, partB, dimensionsVerified: clean.length } +``` + +## Scaling to thoroughness + +- **Quick read:** 3-4 dimensions, single-vote verification. +- **Deep audit:** 6+ dimensions; add a multi-vote refutation pass on the headline claims (spawn N skeptics per claim, kill if a majority refute) before synthesis. +- **Agent count:** ~2 per dimension (collect + verify) + 2 synthesis. 6 dimensions ≈ 14 agents — a real, token-heavy run. Tell the user the scale before launching. + +## After the run + +The workflow returns `{ partA, partB }`. Stitch them into one markdown file, drop it where research lives, and offer the Next-Step PDF render (see SKILL.md). Strip any agent self-talk preamble before the first `##` heading. diff --git a/bigdata-skill/.security-scan-passed b/bigdata-skill/.security-scan-passed new file mode 100644 index 00000000..9ec7a103 --- /dev/null +++ b/bigdata-skill/.security-scan-passed @@ -0,0 +1,4 @@ +Security scan passed +Scanned at: 2026-06-13T19:44:41.069633 +Tool: gitleaks + pattern-based validation +Content hash: 1dc770d556b9a8d204518f8435cd0ee63398ff7a544faac168b48f397238a9fc diff --git a/bigdata-skill/SKILL.md b/bigdata-skill/SKILL.md new file mode 100644 index 00000000..c0475d8a --- /dev/null +++ b/bigdata-skill/SKILL.md @@ -0,0 +1,266 @@ +--- +name: bigdata-skill +description: >- + Pull Bigdata.com (RavenPack) financial and news data via the official + `bigdata-client` SDK and `/v1/*` REST endpoints — structured financials, + prices, analyst estimates, daily entity-sentiment series, annotated chunk + search, screener — when the Bigdata MCP returns only pre-synthesized tearsheets + but you need the machine-readable substrate. Use when the user mentions + Bigdata.com, RavenPack, a `bd_v2_` key, the bigdata MCP, rp_entity_id, + chunk/query_unit cost, or wants structured financials, fundamentals, prices, + sentiment, or annotated news. +--- + +# Bigdata.com SDK + REST Toolkit + +Get the structured substrate the Bigdata.com MCP server doesn't hand over. The +MCP returns clean prose and pre-synthesized tearsheets, but its search tool +gives chunks with no per-chunk sentiment or entity spans, and its tearsheets +give aggregate values — not the fiscal-period time series, universe screener, or +per-field JSON you'd build a pipeline on. The official `bigdata-client` SDK plus +a thin REST passthrough over the *same backend, same JWT* reach the official +`/v1/*` endpoints that hold it. This skill bundles a toolkit that does exactly +that — already debugged, already cost-guarded — so you don't re-pay the +discovery cost. + +## The core problem this solves (read this first) + +The Bigdata MCP server answers "what's the sentiment around NVIDIA?" with a +readable paragraph or a pre-synthesized tearsheet — genuinely useful for a chat +turn. But the moment you need the **machine-readable substrate** to build a +pipeline on, the MCP doesn't hand it over: + +- its **search** tool returns chunks with text + relevance only — **no per-chunk + sentiment number, no entity character spans**; +- its **tearsheets** give aggregate values (a single sentiment score, a summary + of estimates) — **not** a fiscal-period time series you can compute on, a + universe screener, or per-field JSON. + +The fix is a general pattern, not a Bigdata trick: + +> **When an MCP data source returns only synthesized output but you need the +> structured fields underneath, drop to the vendor SDK or REST.** MCP optimizes +> for a chat turn, not a pipeline. + +Crucially, for Bigdata these structured fields are **official, publicly +documented REST endpoints** (`docs.bigdata.com/api-reference/...`), not a hidden +backend — and Bigdata is **sunsetting the SDK (EOL 2026-12-31) in favour of this +REST API**, so the REST layer here is the forward-compatible path, not a hack. +The SDK (`bigdata_client.Bigdata`) covers search + knowledge-graph; **`bd._api.http`** +reaches every `/v1/*` endpoint the SDK never wrapped. The bundled +`bigdata_toolkit` packages both behind one `BigdataClient`. + +## When to use this skill + +Trigger on any of these, in any language: + +- The user is using **Bigdata.com / RavenPack** and the MCP result feels thin — + "where's the sentiment score?", "I need entity-level data", "the calendar". +- They want **forward / structured** financials for a ticker: analyst + estimates, earnings or event calendar, earnings surprise, analyst ratings, + price targets, a company screener / universe. +- They want **annotated news chunks** with numeric sentiment + entity spans, or + a sentiment time series / co-mention graph. +- They mention a **`bd_v2_` API key**, `rp_entity_id`, `query_unit` / chunk + cost, `bigdata-client`, or "the bigdata MCP isn't enough". +- They're building an **investment-research dataset** and need a reusable, + cost-aware data-pull layer rather than one-off MCP calls. + +## Setup (one time) + +**1 — API key (never hardcode it).** The client fail-fasts if it's missing: + +```bash +export BIGDATA_API_KEY=bd_v2_xxxxxxxx +``` + +**2 — An isolated Python env with the official SDK.** The bundled toolkit +imports `bigdata_client`; install it once: + +```bash +uv venv .venv --python 3.12 +uv pip install --python .venv/bin/python bigdata-client +# Behind a slow/blocked PyPI (e.g. mainland China) add a mirror, and unset any +# outbound proxy for the install step so uv reaches the index directly: +# --index-url https://pypi.tuna.tsinghua.edu.cn/simple +``` + +**3 — Outbound proxy (only if your network needs one to reach +`api.bigdata.com`).** Two equivalent options — the official SDK accepts both: an +env var, or `BigdataClient(proxy=...)` in code. The env var is simplest: + +```bash +export HTTPS_PROXY=http://: # plus WSS_PROXY for chat/WebSocket +``` + +If a proxy does TLS interception (self-signed CA) and you hit SSL handshake +errors, the official fix is `BigdataClient(verify_ssl=".pem")` — not +blind retries. + +**4 — Make the bundled package importable** by putting this skill's `scripts/` +on `PYTHONPATH` (or `sys.path.insert(0, "/scripts")`). + +**Smoke-test the whole path** (entity resolve + quota are free; `--with-search` +adds one ~1 query_unit chunk search): + +```bash +BIGDATA_API_KEY=bd_v2_xxx PYTHONPATH=scripts .venv/bin/python scripts/probe_example.py +``` + +## Quickstart + +```python +import sys +sys.path.insert(0, "/scripts") # so `import bigdata_toolkit` resolves +from bigdata_toolkit import ( + BigdataClient, EntityResolver, AnnotatedSearcher, + StructuredDataREST, CostTracker, CostModel, rc, # rc = SSL-retry wrapper +) + +c = BigdataClient() # SDK + REST escape hatch, one object +er = EntityResolver(c) +nvda = rc(lambda: er.resolve_id("NVIDIA", country="US")) # -> 'E09E2B' (rp_entity_id is the gateway key) + +# --- Structured financials the MCP does NOT expose (REST escape hatch) --- +rest = StructuredDataREST(c) +est = rc(lambda: rest.analyst_estimates(nvda, period="quarter", limit=5)) # forward consensus +surp = rc(lambda: rest.latest_surprise(nvda)) # last EPS/revenue surprise +cal = rc(lambda: rest.events_calendar(nvda, categories=["earnings-call"], + start_date="2026-06-01", end_date="2026-12-31")) + +# --- Annotated chunks the MCP STRIPS: sentiment + entity spans (cost-guarded) --- +s = AnnotatedSearcher(c) +docs = rc(lambda: s.search_entity(nvda, keyword="data center", chunk_limit=10)) +# each chunk dict: {"sentiment": float, "entities": [{"key": rp_id, "start", "end"}], "text", ...} + +# --- Always know your spend (chunk-billed; see Cost discipline) --- +ct = CostTracker(c); ct.snapshot() +# ... run a batch ... +print(ct.delta()) # {'delta_chunks':..., 'delta_query_units':..., 'usd_fast':...} +``` + +Wrap **every** network call in `rc(lambda: ...)` — a first-handshake `SSL: +UNEXPECTED_EOF` is common and the SDK's internal retry doesn't cover it. + +## Routing — which capability answers the question + +| The user wants… | Use | Module | +|---|---|---| +| Company name / ISIN / CUSIP / SEDOL → `rp_entity_id` | `EntityResolver.resolve_id` / `.resolve_by_isin` | `kg.py` (SDK) | +| Forward analyst consensus (revenue/EPS by fiscal period) | `StructuredDataREST.analyst_estimates` | `rest_ext.py` | +| Latest earnings surprise (actual vs estimate) | `.latest_surprise` | `rest_ext.py` | +| Upcoming earnings / event calendar (one name or whole market) | `.events_calendar` | `rest_ext.py` | +| Analyst ratings / price-target consensus | `.analyst_ratings` / `.price_target` | `rest_ext.py` | +| Full financial statements (income / balance / cash-flow, multi-year) | `.income_statement` / `.balance_sheet` / `.cash_flow_statement` | `rest_ext.py` | +| TTM valuation metrics & ratios (EV/EBITDA, ROE, P/E, margins) | `.key_metrics_ttm` / `.company_ratios_ttm` | `rest_ext.py` | +| Company profile (CEO, sector, employees, IPO date) | `.company_profile` | `rest_ext.py` | +| Daily OHLC prices / dividend history | `.daily_prices` / `.dividends` | `rest_ext.py` | +| Revenue by geography / product segment | `.revenue_geographic_segments` / `.revenue_product_segments` | `rest_ext.py` | +| Daily entity-sentiment time series (don't self-aggregate from chunks!) | `.entity_sentiment` | `rest_ext.py` | +| Co-mention graph (supply-chain / competitor / customer — ⚠️ chunk-billed) | `.connected_entities` | `rest_ext.py` | +| Build a universe by market-cap / sector / country | `.company_screener` | `rest_ext.py` | +| News/filing/transcript chunks with sentiment + entity spans | `AnnotatedSearcher.search_entity` | `search.py` (SDK) | +| Bulk-pull many searches 50% cheaper (portfolio backfill) | `BatchSearch` (create→upload→poll→download) | `rest_ext.py` | +| Track / forecast quota spend before a backfill | `CostTracker` / `CostModel` | `cost.py` | +| Hit an endpoint the toolkit hasn't wrapped yet | `client.http.post("v1//query", body)` | `client.py` | + +> `income/balance/cash-flow/daily-prices/dividends/revenue-segments` return +> `{fields, values}` — wrap them in `fields_values_to_records()` to get +> `[{field: value}]`. The `*_ttm` / `company_profile` endpoints are already flat. +> All structured endpoints above are **free** (0 chunks) except +> `connected_entities` and `AnnotatedSearcher` (chunk-billed). + +## The two data faces (do NOT say "Bigdata fails for Chinese / A-shares") + +This split is the most important non-obvious conclusion — state it precisely: + +| Face | Path | A-share / Chinese verdict | +|---|---|---| +| **Structured financial** (estimates, calendar, surprise, ratings, target, screener, **financials, prices, dividends, revenue segments, daily entity-sentiment**) | REST (`rest_ext.py`) | **Works** — via `rp_entity_id` resolved from the **English name or ISIN** (not the Chinese name). Data is fresh. Minor holes (some A-share price-targets return the entity with no numeric target). The daily `entity_sentiment` series lives **here** and works for any resolvable entity — it is **not** the dead end below. | +| **Unstructured Chinese NLP** (Chinese-news entity detection, per-chunk Chinese sentiment) | SDK search (`search.py`) | **Dead end** — a data-source-level gap, not an SDK bug: Chinese entity detection ≈ 0, per-chunk CJK sentiment is a doc-level inherited value, and `language` mislabels Chinese filings as English. Pair Bigdata with a China-domestic source for Chinese-language *chunk* content; use Bigdata for the structured face (incl. aggregate `entity_sentiment`) + ISIN/KG crosswalk + English-language chunk sentiment. | + +## Cost discipline + +`1 query_unit = 10 chunks` (official). **Only chunk-search is billed** — the +structured `/v1/*` endpoints (estimates, financials, prices, calendar, surprise, +ratings, the sentiment time series, screener…) are **free** (0 chunks, +contract-tested). `connected_entities` (co-mentions) and `AnnotatedSearcher` +**are** chunk-billed. + +Three levers when you do pay for chunks: + +1. **`ChunkLimit`, never a bare `int`.** `Search.run(int)` is a *document* limit + billed by the full chunk page; `ChunkLimit(n)` bills per chunk. + `AnnotatedSearcher.search` forces `ChunkLimit` for you. (We observed roughly a + 52x gap once — **a single measured data point, not stated in the official + docs**; treat the exact multiple as indicative. The rule "use `ChunkLimit`" + holds regardless, because `max_chunks` is the official billing unit.) +2. **Rerank bills only the *returned* chunks** (official) — pass a + `rerank_threshold` to recall broadly but pay only for the high-relevance hits. +3. **Batch search is 50% cheaper** (`$0.0075` vs `$0.015` / qu) — use + `BatchSearch` for a large multi-query backfill. + +Use `CostModel` to veto an over-budget job *before* running it, and +`CostTracker.snapshot()` / `delta()` to measure real spend. Full accounting → +`references/cost_accounting.md`. + +## Known pitfalls (already solved — don't re-debug these) + +Each cost real debugging time and is fixed or guarded in the toolkit. Full +reproductions and fixes in **`references/known_pitfalls.md`**: + +1. **First-handshake `SSL: UNEXPECTED_EOF`** → wrap calls in `rc()`; the SDK's + urllib3 retry only covers HTTP status, not the SSL EOF. +2. **`All(entity, Keyword(kw))` raises `TypeError`** → combine with the `&` + operator (`entity & Keyword(kw)`); `All` takes a single iterable. (Fixed in + `AnnotatedSearcher.entity_query`.) +3. **The 52x doc-limit billing trap** → always `ChunkLimit`, never a bare `int`. +4. **Closure capture in loops** → bind loop vars: `rc(lambda q=q, dr=dr: ...)`. +5. **`analyst_estimates(period="quarter")` 400s above `limit≈20`.** +6. **`company_screener` filters must nest under `"filters"`** — flat top-level + keys don't 400, they're silently dropped → unfiltered universe. +7. **`Document.reporting_period` is always `None`** (the SDK model drops a field + present on the REST wire) → `fetch_reporting_period_raw`. + +## What this skill will not do + +- **Never hardcode an API key.** `BigdataClient` reads `BIGDATA_API_KEY` and + fail-fasts if absent — no plaintext fallback (that is exactly the pattern + secret scanners catch). +- **Only ever reads — never writes or uploads.** Every method is a read-only + query (`uploads` is `NotImplementedError` in API-key mode anyway), so the + toolkit can't mutate your account or push data anywhere. +- **Never invent an endpoint or a schema.** Every signature here is runtime + L4-verified or marked L3 (doc-confirmed, not yet run); see + `references/verified_api_signatures.md`. For a new endpoint, confirm the path + via `docs.bigdata.com/llms.txt` rather than guessing. + +## File layout + +``` +bigdata-skill/ +├── SKILL.md # this file — routing + setup + quickstart +├── scripts/ +│ ├── bigdata_toolkit/ # the verified, cost-guarded package +│ │ ├── client.py # BigdataClient: SDK (.bd) + REST escape hatch (.http/.conn) +│ │ ├── kg.py # EntityResolver: name/ISIN/CUSIP/SEDOL → rp_entity_id +│ │ ├── search.py # AnnotatedSearcher: chunks + sentiment + entity spans (SDK) +│ │ ├── rest_ext.py # StructuredDataREST (estimates/financials/prices/dividends/sentiment/co-mentions/screener) + BatchSearch + fields_values_to_records — official REST +│ │ ├── cost.py # CostTracker + CostModel: chunk billing + budget veto +│ │ └── retry.py # rc(): SSL/transient-error retry passthrough +│ └── probe_example.py # runnable end-to-end smoke test +└── references/ + ├── escape_hatch_architecture.md # WHY the MCP is lossy; bd._api.http mechanism; adding endpoints + ├── verified_api_signatures.md # L4/L3-verified signatures + the two data faces, with evidence + ├── cost_accounting.md # chunk billing, the 52x trap, CostModel/CostTracker, budgeting + └── known_pitfalls.md # every pitfall above, with reproduction + fix +``` + +## References + +| Read when you need to… | File | +|---|---| +| Understand *why* the MCP is insufficient and how the REST escape hatch works (and how to wrap a new `/v1/*` endpoint) | `references/escape_hatch_architecture.md` | +| Look up an exact verified method signature + its verification level | `references/verified_api_signatures.md` | +| Budget a backfill or debug a surprise quota burn | `references/cost_accounting.md` | +| Diagnose an error you hit while pulling data | `references/known_pitfalls.md` | diff --git a/bigdata-skill/references/cost_accounting.md b/bigdata-skill/references/cost_accounting.md new file mode 100644 index 00000000..9b2440a9 --- /dev/null +++ b/bigdata-skill/references/cost_accounting.md @@ -0,0 +1,111 @@ +# Cost accounting — chunk billing, the 52x trap, budgeting + +Bigdata bills by **chunk**, not by call. One default argument can silently drain +a whole quota, so cost is a first-class concern in this toolkit, not an +afterthought. + +## The unit + +`1 query_unit = 10 chunks`. Corroborated three independent ways inside the SDK: +the raw `chunks_count` accumulation, `get_usage()` dividing by 10, and +`subscription`'s `query_unit_used = contextual_units_read / 10`. + +The REST raw counter +`get_my_quota().organization_consumed.contextual_units_read` is a **chunk** +count, not a query_unit count. `CostTracker` reads this raw counter so the +chunk semantics are preserved (the SDK's high-level `subscription.get_details()` +pre-divides by 10 and loses the chunk granularity). + +## List pricing + +| Tier | USD / query_unit | +|---|---| +| Fast Search | `0.015` | +| Smart Search | `0.03` | +| Batch (async) | `0.0075` (50% off) | + +Source: `docs.bigdata.com` (public list prices). + +## The doc-limit trap (use `ChunkLimit`, not a bare `int`) + +`Search.run(limit)` accepts either an `int` or a `ChunkLimit(n)`: + +- A bare **`int` is a document limit, billed by the full page of chunks** — the + number of *documents* you ask for barely changes the bill; you pay for the + chunk page either way. +- **`ChunkLimit(n)` bills by chunk**: `ChunkLimit(10) = 1 query_unit`. + +We once measured roughly a **52x gap** (`run(1) ≈ run(10) ≈ 52 query_units`) — +but that is a **single measured data point, not stated in the official pricing +docs**; treat the exact multiple as indicative (it likely varies by ticker / +window / document count). The rule holds regardless: `max_chunks` is the +official billing unit, so always pass `ChunkLimit(n)`. `AnnotatedSearcher.search` +forces it for you; any raw `bd.search.new(...).run(...)` you write must too — +code-review every cold-start backfill for a bare `run(int)`. + +A second, smaller lever: **window width** — at the same limit a narrow date +window costs less than a wide one (we saw ~2.6x once; a single measured point — +narrow the window when you can). + +## What's billed vs free + +Only **chunk-search** counts against your quota (contract-tested 2026-05-30): + +| Billed (chunks) | Free (0 chunks) | +|---|---| +| `AnnotatedSearcher` (SDK search), `connected_entities` (co-mentions), `fetch_reporting_period_raw`, the searches a `BatchSearch` runs | every other `StructuredDataREST` endpoint — estimates, financials, prices, dividends, calendar, surprise, ratings, target, screener, `entity_sentiment`, quotas | + +So a deep single-ticker dossier built from the structured endpoints (financials, +prices, the sentiment series, estimates) is **essentially free** — the cost is in +the annotated chunk evidence you pull on top of it. + +## Two more levers (official) + +- **Rerank bills only the *returned* chunks** — pass a `rerank_threshold` to + `AnnotatedSearcher.search` to recall broadly but pay only for the high-relevance + hits (official: the `rerank_search` how-to). +- **Batch search is 50% off** (`$0.0075` vs `$0.015` / query_unit) — pack a large + multi-query backfill through `BatchSearch` (create → upload jsonl → poll → + download). Official use case: portfolio-wide monitoring. + +## Budgeting a backfill before you run it (`CostModel`) + +`CostModel` is pure arithmetic — use it to veto an over-budget job *before* +spending anything: + +```python +from bigdata_toolkit import CostModel +m = CostModel(chunk_limit_per_query=500, tier="fast") +print(m.estimate(n_entities=20, n_windows=1)) # PoC sample +print(m.estimate(n_entities=100, n_windows=12)) # 100 names x 3yr quarterly +# -> {'usd':..., 'total_query_units':..., 'pct_of_trial_quota':..., ...} +``` + +`trial_query_units` (default `67000`) sets the denominator for +`pct_of_trial_quota`. A typical 1-week full-content trial is ≈ 67000 query_units +≈ $1005 at list — but set it to **your account's actual `max_query_units`** +(from `CostTracker.quota()`) for an accurate percentage. + +**Trial reality:** an institutional universe (100–200 names) doing one multi-year +backfill **approaches or exceeds the entire trial quota** (100 names × 3yr +quarterly ≈ 90%; 200 names ≈ 180%). A trial is only good for a **PoC-grade +sample (≤20 names, single snapshot)**. A full production load needs a larger +(paid) quota — don't plan a full backfill against trial credits. + +## Measuring real spend (`CostTracker`) + +Estimates are for vetoing; measure the real burn to calibrate: + +```python +from bigdata_toolkit import CostTracker +ct = CostTracker(client) +ct.snapshot() # baseline (raises in delta() if you forget — no guessed baseline) +# ... run a batch ... +print(ct.delta()) # {'delta_chunks', 'delta_query_units', 'usd_fast', 'usd_smart', ...} +``` + +`CostTracker.quota_detailed_raw()` hits `v1/subscription/quotas` — a **free** +side-channel (not chunk-billed) with billing-period + per-unit breakdown. Poll +it mid-backfill to measure the real chunk→credit conversion rather than trusting +the estimate. For a long pull, snapshot/delta around each batch and stop when +cumulative spend nears your cap. diff --git a/bigdata-skill/references/escape_hatch_architecture.md b/bigdata-skill/references/escape_hatch_architecture.md new file mode 100644 index 00000000..d0561505 --- /dev/null +++ b/bigdata-skill/references/escape_hatch_architecture.md @@ -0,0 +1,104 @@ +# Why the Bigdata MCP is lossy, and how the REST escape hatch works + +The whole reason this skill exists: the MCP server is not the API. Understanding +the layering tells you exactly where the missing data went and how to get it. + +## The layers + +| Layer | What it is | What it gives you | +|---|---|---| +| **MCP server** | A chat-optimized wrapper | Readable prose + pre-synthesized tearsheets (incl. an aggregate sentiment score and an estimates summary). **Does not expose** numeric per-chunk sentiment, entity character-spans, fiscal-period time series, per-field JSON, or a universe screener. | +| **SDK** (`bigdata_client.Bigdata`) | Official Python client | High-level `search`, `knowledge_graph`, `subscription`, `chat`, `watchlists`, `uploads`. | +| **`bd._api`** (`BigdataConnection`) | The SDK's own transport | Holds `bd._api.http`, a `RateLimitedHTTPWrapper` with `api_url='https://api.bigdata.com/'`, carrying the JWT auth + proxy already. | +| **`/v1/*` REST** | Official, publicly documented structured API (`docs.bigdata.com/api-reference`) — the SDK's **migration target** (SDK EOL 2026-12-31) | estimates, events-calendar, surprise, ratings, price/target, screener, **full financials, prices, dividends, revenue segments, daily entity-sentiment**, subscription/quotas. **No SDK high-level method wraps these** — but the same backend + same JWT serves them, and they outlive the SDK. | + +The MCP and the SDK talk to the same backend. The MCP hands you synthesized +output (prose, tearsheets), not the structured substrate underneath; the SDK's +own `bd._api.http` reaches the `/v1/*` endpoints that hold it. + +> **These `/v1/*` endpoints are official and publicly documented — not a hidden +> backend.** And Bigdata is sunsetting the SDK (EOL **2026-12-31**; the +> SDK-underlying endpoints are to be decommissioned) in favour of this REST API, +> so leaning on `bd._api.http` / REST here is the *forward-compatible* path, not +> a hack. The SDK-only pieces (`kg`, SDK `search`) are the parts with a shelf life. + +## The evidence chain (runtime L4 — not doc inference) + +- `bd._api` is a `bigdata_client.connection.BigdataConnection`. +- It holds `bd._api.http` (`RateLimitedHTTPWrapper`), `api_url='https://api.bigdata.com/'`. +- Every SDK high-level method (`query_chunks`, `by_ids`, `autosuggest`, + `get_my_quota`, …) internally delegates to `self.http.post(endpoint, json=…)` + / `self.http.get(endpoint, params=…)`. +- Therefore hitting an endpoint the SDK never wrapped is just: call + `self.http.(relative_path, …)` yourself. The toolkit exposes this as + `BigdataClient.http` (and `.conn` for `bd._api`). + +## The HTTP wrapper signature (runtime-confirmed) + +```text +http.get(endpoint: str, params: dict = None) -> dict | list +http.post(endpoint: str, json: dict | list[dict]) -> dict | list +http.put / http.patch / http.delete +http.get_chunks(endpoint, chunk_size) -> Iterable[bytes] +http.async_get([...]) -> concurrent GET +``` + +`endpoint` is a **relative path** (e.g. `"v1/events-calendar/query"`); the +wrapper does `urljoin(api_url, endpoint)`. Absolute URLs also work. + +## Route-shape rules (where hours get wasted) + +- **Business face is `POST /v1//query`.** A bare `GET /v1/` + returns **404** — there is no GET route. +- **Platform face is `GET`** — e.g. `GET v1/subscription/quotas`. +- **`403 'Missing Authentication Token'` means the API Gateway has no route on + that path — it is NOT a permission denial.** `404` means the path doesn't + exist at all. Don't read 403 as "my key lacks access". +- Confirm an unfamiliar path against `docs.bigdata.com/llms.txt` before + guessing. Guessing burns time on 403/404 ambiguity. + +## Wrapping a new `/v1/*` endpoint + +1. **Introspect** what the SDK already does so you copy its delegation shape: + + ```python + print(client.introspect_conn()) # lists bd._api methods + source head + ``` + +2. **Ad hoc call** through the escape hatch: + + ```python + resp = client.http.post( + "v1/some-new-resource/query", + {"identifier": {"type": "rp_entity_id", "value": "E09E2B"}}, + ) + quotas = client.http.get("v1/subscription/quotas") # platform GET + ``` + +3. **Field present on the wire but dropped by the SDK model?** (`reporting_period` + is the canonical case — it's ~75% populated on filings over REST, but the + SDK's `ChunkedDocumentResponse` model omits it, so `Document.reporting_period` + is always `None`.) Spy the real payload the SDK sends, then replay it raw: + + ```python + orig = client.http.post + captured = {} + def spy(endpoint, json): + if endpoint == "cqs/query-chunks": + captured["payload"] = json + return orig(endpoint, json) + client.http.post = spy + searcher.search_entity("E09E2B", keyword="revenue", chunk_limit=5) # trigger once + # captured["payload"] is the real schema → adapt → rest.fetch_reporting_period_raw(...) + ``` + +Once you've confirmed a new endpoint works, add a thin method to +`rest_ext.py` so the next caller doesn't rediscover it — that is how the toolkit +grew. Keep returning **raw dict/list** for half-documented endpoints; their +schema can drift, so let the caller defend. + +## The bottom line + +`MCP gave you less than the API has` is the trigger. `bd._api.http` over the +same JWT is the answer. Everything in `rest_ext.py` is just named, verified +shortcuts onto that one escape hatch. diff --git a/bigdata-skill/references/known_pitfalls.md b/bigdata-skill/references/known_pitfalls.md new file mode 100644 index 00000000..86ef3a94 --- /dev/null +++ b/bigdata-skill/references/known_pitfalls.md @@ -0,0 +1,139 @@ +# Known pitfalls (symptom → root cause → fix) + +Every entry here cost real debugging time. Most are already fixed or guarded in +the bundled toolkit; the rest you handle at call sites. When you hit a new one, +add it here with the same shape so the next person doesn't re-debug it. + +## 1. First-handshake `SSL: UNEXPECTED_EOF` + +- **Symptom:** the first call (often entity resolve) throws + `SSLError: UNEXPECTED_EOF` / `Connection reset` / `RemoteDisconnected`, + especially through an outbound proxy. Retrying by hand works. +- **Root cause:** the SDK's HTTP layer (`requests` / `aiohttp`) doesn't retry an + **SSL handshake EOF** — and the official exception hierarchy doesn't even model + it. One network blip becomes a hard exception. +- **Fix:** wrap every network call in `rc()` (bundled in `retry.py`, exported + from the package). It retries only on transient markers + (`SSL`/`EOF`/`Connection`/`Max retries`/`timeout`/`RemoteDisconnected`) and + re-raises everything else immediately — it does not swallow real errors. + + ```python + from bigdata_toolkit import rc + nvda = rc(lambda: er.resolve_id("NVIDIA", country="US")) + ``` + +## 2. `All(entity, Keyword(kw))` → `TypeError: All() takes 1 positional argument` + +- **Symptom:** building an "entity AND keyword" query with + `All(Entity(id), Keyword(kw))` raises `TypeError`. +- **Root cause:** `bigdata_client.query.All` takes a **single iterable**, not + two positional args. +- **Fix:** combine with the overloaded `&` operator. Already fixed in + `AnnotatedSearcher.entity_query`: + + ```python + from bigdata_client.query import Entity, Keyword + q = Entity(id) & Keyword(kw) # not All(Entity(id), Keyword(kw)) + ``` + +## 3. The 52x doc-limit billing trap + +- **Symptom:** a tiny search burned ~52 query_units when you expected ~1. +- **Root cause:** `Search.run(int)` is a document limit billed by the full chunk + page — `run(1) ≈ run(10) ≈ 52 query_units`. +- **Fix:** always `ChunkLimit(n)`. `AnnotatedSearcher.search` does this for you; + any raw `bd.search` must too. Detail: `cost_accounting.md`. + +## 4. Closure capture in a backfill loop + +- **Symptom:** every iteration of a loop pulls the **same** (last) keyword / + window, even though the loop variable changes. +- **Root cause:** `rc(lambda: f(kw))` captures `kw` by reference; by the time + the lambda runs, the loop has advanced. +- **Fix:** bind the loop variables as default args: + + ```python + docs = rc(lambda kw=kw, dr=dr, lim=lim: + s.search_entity(nvda, keyword=kw, chunk_limit=lim, date_range=dr)) + ``` + +## 5. `analyst_estimates(period="quarter")` 400s above `limit≈20` + +- **Symptom:** `limit=30` → HTTP 400 with an unhelpful message; looks like the + endpoint is broken. +- **Root cause:** quarterly estimates cap `limit` at ~20. +- **Fix:** keep `limit ≤ 20`; page if you need more history. + +## 6. `company_screener` filters silently ignored → UNfiltered universe + +- **Symptom:** the screener returns `200` with a `results` list, but the rows + ignore your filters entirely (ask `market_cap_more_than: 1e12`, get a small + Gold ETF back). +- **Root cause:** filters must be **nested under a `"filters"` object** + (`{"filters": {market_cap_more_than, sector, industry, country, exchange, + is_etf}, "limit": n}`). Passing them as **flat top-level keys does NOT 400 — + the backend silently drops them and returns an unfiltered universe.** +- **Fix:** nest them under `filters` (the toolkit's `company_screener` now does). + Contract-tested 2026-05-30: flat `{market_cap_more_than: 1e12}` returned a Gold + ETF; nested `{filters: {market_cap_more_than: 1e12}}` correctly returned NVIDIA + / Alphabet. An earlier note here said "pass flat" — that was wrong; the live + test overrides it. + +## 7. `Document.reporting_period` is always `None` + +- **Symptom:** every document's `reporting_period` is `None` even for filings. +- **Root cause:** the field exists on the REST wire (~75% populated on filings) + but the SDK's `ChunkedDocumentResponse` model omits it, so pydantic drops it. +- **Fix:** read the raw wire via `StructuredDataREST.fetch_reporting_period_raw` + (spy the real `cqs/query-chunks` payload first — see + `escape_hatch_architecture.md`). Note this path **is chunk-billed**. Format is + mixed: absolute `'2026FY'` + relative `'FQ1'`–`'FQ4'`; `'FQ1'` has no year + anchor, so reconcile against the same story's `'YYYYFY'` or timestamp. + +## 8. Chinese company name → 0 hits + +- **Symptom:** `find_companies('贵州茅台')` returns nothing. +- **Root cause:** the data source's Chinese entity layer is empty (not a bug you + can code around). +- **Fix:** resolve via the **English official name** (`'Kweichow Moutai'`) or + **ISIN** (`resolve_by_isin(['CNE0000018R8'])`). Same for topics — Chinese + topic strings (`'人工智能'`) return 0. + +## 9. `kg.autosuggest` → `NotImplementedError` + +- **Symptom:** interactive autosuggest raises `NotImplementedError`. +- **Root cause:** not implemented in **API-key mode** (same family as `uploads`). +- **Fix:** use the `find_*` resolvers; there is no autosuggest in key mode. + +## 10. `403 'Missing Authentication Token'` misread as a permission error + +- **Symptom:** a `/v1/*` call returns 403 and you assume your key lacks access. +- **Root cause:** the API Gateway returns this when **there is no route on that + path** (e.g. you did `GET` where only `POST /query` exists). It is not a + permission denial; `404` means the path doesn't exist. +- **Fix:** use `POST /v1//query` for the business face, `GET` only for + the platform face (`v1/subscription/quotas`). Confirm unfamiliar paths against + `docs.bigdata.com/llms.txt`. + +## 11. Two response shapes: columnar `{fields, values}` vs flat `[{...}]` + +- **Symptom:** `income_statement` / `daily_prices` return `{results: {fields, + values}}` (or `{results: [{fields, values}]}`), not records — `results[0]["REVENUE"]` fails. +- **Root cause:** financials / prices / dividends / revenue-segments use a + columnar `{fields, values}` shape; `*_ttm` / `company_profile` are already flat. +- **Fix:** wrap the columnar ones in `fields_values_to_records()` → + `[{field: value}]` (single-entity results auto-flatten). + +## 12. `entity-sentiment` uses a trailing slash, not `/query` + +- **Symptom:** `POST v1/entity-sentiment/query` 404s. +- **Root cause:** the path is `v1/entity-sentiment/` (trailing slash), unlike the + `v1//query` business-face pattern; body uses `timestamp:{start,end}`, not `date_range`. +- **Fix:** the toolkit's `entity_sentiment()` already uses the right path + shape. + +## 13. `connected_entities` (co-mentions) is chunk-billed; the structured endpoints aren't + +- **Symptom:** a co-mention call increments chunk usage while financials / prices cost 0. +- **Root cause:** co-mentions runs over the search service (response carries + `usage.api_query_units`); the structured `/v1/*` endpoints don't bill chunks. +- **Fix:** keep `connected_entities` limits small and budget for it like a search. diff --git a/bigdata-skill/references/verified_api_signatures.md b/bigdata-skill/references/verified_api_signatures.md new file mode 100644 index 00000000..982c3690 --- /dev/null +++ b/bigdata-skill/references/verified_api_signatures.md @@ -0,0 +1,143 @@ +# Verified API signatures + the two data faces + +Every signature below was either **runtime-tested (L4)** or **doc-confirmed +(L3)**. Treat L3 as "schema confirmed, run a contract test before relying on it +in production". Nothing here is guessed — if you need an endpoint not listed, +confirm it via `docs.bigdata.com/llms.txt` and add it as L3 until you run it. + +## Verification levels + +- **L4** — actually ran it, saw HTTP 200 + real data. +- **L3** — found in the docs/llms.txt index, schema confirmed, not yet run live. + Endpoint path is doc-sourced; verify before production. + +## EntityResolver — `kg.py` (SDK knowledge-graph) + +`rp_entity_id` (a 6-char alphanumeric like Apple `D8442A`) is the **primary key +for almost everything** — search `Entity(id)`, and every `rest_ext` endpoint. + +```text +resolve_id(name, *, country=None) -> str | None # first hit, or None (no fallback) +find_companies(name, *, country=None, limit=5, as_dict=True) +resolve_by_isin(isins: list[str], *, as_dict=True) # crosswalk +resolve_by_cusip(cusips) / resolve_by_sedol(sedols) +find_topics(values, *, limit=5) # ⚠ Chinese topics ≈ 0 hits +get_entities(ids) # resolves COMP + TOPC, not ENTITY-only +``` + +- **A-share rule (L4):** the Chinese name returns **0 hits** + (`find_companies('贵州茅台')` → nothing). Resolve via the **English official + name** (`'Kweichow Moutai'` → `914E1F`) or **ISIN** (`CNE0000018R8` → `914E1F`). +- `country` is ISO-2 (`'CN'` / `'US'` / `'HK'`). +- `kg.autosuggest` raises `NotImplementedError` in API-key mode (same family as + `uploads`); use the `find_*` methods, not interactive autosuggest. + +## AnnotatedSearcher — `search.py` (SDK search) + +```text +search(query, *, chunk_limit=10, date_range=None, + scope=DocumentType.ALL, sortby=SortBy.RELEVANCE, + rerank_threshold=None, as_dict=True) -> list[dict] +search_entity(rp_entity_id, *, keyword=None, chunk_limit=10, **kwargs) +entity_query(rp_entity_id, keyword=None) # Entity(id) [& Keyword(kw)] +``` + +- `chunk_limit` is the **cost-bearing** parameter; internally wrapped in + `ChunkLimit(n)` (never a bare int — see `cost_accounting.md`). +- `date_range`: `AbsoluteDateRange(start, end)` or `RollingDateRange.*`. Narrower + windows cost less at the same limit. +- `scope`: `DocumentType.ALL / NEWS / FILINGS / TRANSCRIPTS`. + +Fields the wrapper flattens (the layer the MCP strips), runtime-confirmed: + +```text +Document: id, headline, sentiment, document_scope, source, timestamp, + language, url, reporting_period (always None — SDK drops it), + reporting_entities, document_type +DocumentChunk: text, chunk, entities, sentences, relevance, sentiment, + section_metadata, speaker +DocumentSentenceEntity: key (rp_entity_id), start, end (char span), query_type +``` + +`text[start:end]` on a chunk yields the annotated entity's surface form. + +## StructuredDataREST — `rest_ext.py` (REST escape hatch) + +Mostly `POST /v1//query` (exceptions noted below: `entity-sentiment/` +takes a **trailing slash**; co-mentions + batch live under `/v1/search/`). All +return **raw dict/list** (half-documented endpoints — defend on the caller side). +Identifier-bearing endpoints use `{"identifier": {"type": "rp_entity_id", +"value": id}}` (spec-confirmed); `events_calendar` uses `{"rp_entity_id": [...]}`. + +| Method | Endpoint | What it returns | Level | +|---|---|---|---| +| `events_calendar(id?, *, categories, start_date, end_date, countries?, limit=5, cursor?)` | `v1/events-calendar/query` | forward earnings/call calendar; pass no entity + `countries` + window to scan the whole market | **L4** | +| `analyst_estimates(id, *, period='quarter', limit=5)` | `v1/analyst-estimates/query` | forward consensus: REVENUE/EBITDA/EBIT/NET_INCOME/SGA/EPS LOW/HIGH/AVG + analyst counts, by fiscal period | **L4** | +| `latest_surprise(id)` | `v1/latest-surprise/query` | most recent reporting_date + eps/revenue actual vs estimated + surprise_pct (single latest period only) | **L4** | +| `analyst_ratings(id)` | `v1/analyst-ratings/query` | strong_buy/buy/hold/sell/strong_sell + consensus | **L4** | +| `price_target(id)` | `v1/price/target/query` | target high/low/consensus/median + currency | **L4** | +| `company_screener(*, market_cap_more_than, sector, industry, country, exchange, is_etf, limit, **extra)` | `v1/company-screener/query` | universe construction | **L4** (filters nested under `filters`, verified) | +| `income_statement(id, *, period, limit)` | `v1/income-statement/query` | income statement fields (REVENUE/GROSS_PROFIT/EBITDA/EBIT/NET_INCOME…), `{fields,values}` | **L4** | +| `balance_sheet(id, *, period, limit)` | `v1/balance-sheet/query` | balance sheet (TOTAL_ASSETS/TOTAL_DEBT/NET_DEBT/EQUITY…), `{fields,values}` | **L4** | +| `cash_flow_statement(id, *, period, limit)` | `v1/cash-flow-statement/query` | cash flow (OPERATING_CASH_FLOW/FREE_CASH_FLOW/CAPEX…), `{fields,values}` | **L4** | +| `key_metrics_ttm(id)` | `v1/key-metrics-ttm/query` | TTM metrics (EV/EBITDA, ROE, ROIC, FCF yield…), flat list | **L4** | +| `company_ratios_ttm(id)` | `v1/company-ratios-ttm/query` | TTM ratios (margins, P/E, P/B, D/E, dividend yield…), flat list | **L4** | +| `company_profile(id)` | `v1/company-profile/query` | profile (name/CEO/sector/website/employees/IPO…), flat list | **L4** | +| `daily_prices(id, *, start_date, end_date)` | `v1/price/daily/query` | daily OHLC (DATE/OPEN/HIGH/LOW/CLOSE/VOLUME/VWAP…), `{fields,values}` | **L4** | +| `dividends(id, *, start_date, end_date)` | `v1/dividends/query` | dividend history (DATE/DIVIDEND/YIELD/FREQUENCY…), `{fields,values}` | **L4** | +| `revenue_geographic_segments(id, *, period, limit)` | `v1/company-revenue-geographic-segments/query` | revenue by region (REGION_SEGMENTS nested) | **L4** | +| `revenue_product_segments(id, *, period, limit)` | `v1/company-revenue-product-segments/query` | revenue by product (PRODUCT_SEGMENTS nested) | **L4** | +| `entity_sentiment(id, *, start_date, end_date)` | `v1/entity-sentiment/` ⚠️ trailing slash | daily sentiment series (daily_sentiment/sentiment_pressure/abnormal_media_attention) | **L4** | +| `connected_entities(id, *, date_range, limit)` | `v1/search/co-mentions/entities` | co-mention graph grouped by category (total_chunks/headlines); optional `date_range` → `query.filters.timestamp` — **chunk-billed** | **L4** | +| `BatchSearch.create_job()` / `.get_status(id)` / `.upload_input` / `.download_results` | `v1/search/batches` (+ `/{id}`) | batch search **50% off**; create/status L4, upload/download wired but end-to-end unverified | **L4 / L3** | +| `fetch_reporting_period_raw(payload)` | `cqs/query-chunks` | raw `stories[].reportingPeriod` the SDK model drops — **chunk-billed** | **L4** | + +Endpoint quirks (all runtime-observed): + +- `analyst_estimates(period='quarter')` caps `limit` at **~20**; `limit=30` + → 400 with an unhelpful message. Don't read it as a dead endpoint. +- `company_screener` filters **must be nested under a `"filters"` object** + (`{"filters": {market_cap_more_than, sector, industry, country, exchange, + is_etf}, "limit": n}`, `limit`≤1000 at top level). Flat top-level filters do + **not** 400 — they are silently dropped and the screener returns an unfiltered + universe (contract-tested 2026-05-30: flat → Gold ETF; nested → NVIDIA/Alphabet). +- `analyst_estimates` identifier shape observed as + `{"identifier": {"type": "rp_entity_id", "value": id}}`; some RavenPack + versions accept a bare `rp_entity_id` array instead. If one 400s, try the other. +- These analyst/events/quota endpoints are **not chunk-billed** (only search's + `query-chunks` increments usage). `fetch_reporting_period_raw` is the one + exception — it goes through `query-chunks` and IS chunk-billed. + +## CostTracker / CostModel — `cost.py` + +```text +CostTracker(client).quota() -> {max_chunks, used_chunks, remaining_chunks, + used/remaining/max_query_units, pct_used} + .snapshot() -> records baseline; .delta() -> spend since baseline + .quota_detailed_raw() -> free REST side-channel (v1/subscription/quotas) +CostModel(chunk_limit_per_query=500, tier='fast', trial_query_units=67000) + .estimate(n_entities, n_windows=1) -> {usd, total_query_units, pct_of_trial_quota, ...} +``` + +## Known entity IDs (worked examples — public companies, safe to reuse) + +| Name | rp_entity_id | Note | +|---|---|---| +| Apple | `D8442A` | resolves from `"Apple"` directly | +| NVIDIA | `E09E2B` | resolves from `"NVIDIA"` (country `US`) | +| Kweichow Moutai (贵州茅台) | `914E1F` | A-share: resolve via `"Kweichow Moutai"` or ISIN `CNE0000018R8`, **not** the Chinese name | + +## The two data faces (the precise conclusion) + +Do not collapse this into "Bigdata doesn't work for A-shares". It's two faces: + +1. **Structured financial face** (`rest_ext.py`): **works for A-shares + HK** via + `rp_entity_id` (English name or ISIN). Data is fresh (recently-updated + surprises observed). Holes: some A-share `price_target` returns + the entity with no numeric target (US names like AAPL are complete). +2. **Unstructured Chinese-NLP face** (`search.py`): **dead end** — a + data-source-level gap, not an SDK bug. Chinese entity detection ≈ 0, CJK chunk + sentiment is a doc-level inherited value (chunk sentiment == doc sentiment), + and `language` mislabels Chinese filings as English. For Chinese-language + content, pair Bigdata with a China-domestic research/news source; use Bigdata + for the structured face, ISIN/KG crosswalk, and English-language sentiment. diff --git a/bigdata-skill/scripts/bigdata_toolkit/__init__.py b/bigdata-skill/scripts/bigdata_toolkit/__init__.py new file mode 100644 index 00000000..2409e934 --- /dev/null +++ b/bigdata-skill/scripts/bigdata_toolkit/__init__.py @@ -0,0 +1,75 @@ +"""bigdata_toolkit —— Bigdata.com 可复用工具库 +================================================ + +一个 class 两种能力：SDK 高层封装 + ``bd._api`` REST 逃生舱直通。 + +基于对 ``bigdata-client`` SDK 的运行时实测（L4）构建，**不编 API**。 +每个能力都标注走 SDK 还是走 REST 逃生舱，见各子模块 docstring。 + +快速开始 +-------- +>>> import os +>>> os.environ["BIGDATA_API_KEY"] = "bd_v2_xxx" # doctest: +SKIP +>>> os.environ["HTTPS_PROXY"] = "http://127.0.0.1:8080" # 仅在需要出站代理时 # doctest: +SKIP +>>> from bigdata_toolkit import BigdataClient, EntityResolver, StructuredDataREST +>>> client = BigdataClient() # doctest: +SKIP +>>> # 1) 实体解析（A 股用英文名/ISIN） +>>> resolver = EntityResolver(client) # doctest: +SKIP +>>> aapl = resolver.resolve_id("Apple") # doctest: +SKIP -> 'D8442A' +>>> # 2) SDK 没有的前瞻日历（走 REST 逃生舱） +>>> rest = StructuredDataREST(client) # doctest: +SKIP +>>> cal = rest.events_calendar(aapl, categories=["earnings-call"], +... start_date="2026-06-01", end_date="2026-12-31") # doctest: +SKIP + +模块速查 +-------- +- :mod:`~bigdata_toolkit.client` —— 统一入口（SDK + REST 逃生舱） +- :mod:`~bigdata_toolkit.search` —— 带标注 chunk 抽取（SDK） +- :mod:`~bigdata_toolkit.kg` —— 实体解析 + ISIN crosswalk（SDK） +- :mod:`~bigdata_toolkit.rest_ext` —— SDK 缺失的结构化金融数据（REST 逃生舱） +- :mod:`~bigdata_toolkit.cost` —— chunk 消耗追踪 + 配额意识 +""" + +from .client import BigdataClient, require_env +from .cost import ( + CHUNKS_PER_QUERY_UNIT, + USD_PER_QUERY_UNIT, + CostModel, + CostTracker, +) +from .kg import EntityResolver, company_to_dict +from .rest_ext import BatchSearch, StructuredDataREST, fields_values_to_records +from .retry import RETRYABLE_MARKERS, rc, with_retry +from .search import ( + AnnotatedSearcher, + chunk_to_dict, + document_to_dict, +) + +__version__ = "0.1.0" + +__all__ = [ + # client + "BigdataClient", + "require_env", + # search + "AnnotatedSearcher", + "chunk_to_dict", + "document_to_dict", + # kg + "EntityResolver", + "company_to_dict", + # rest_ext + "StructuredDataREST", + "BatchSearch", + "fields_values_to_records", + # cost + "CostTracker", + "CostModel", + "CHUNKS_PER_QUERY_UNIT", + "USD_PER_QUERY_UNIT", + # retry + "rc", + "with_retry", + "RETRYABLE_MARKERS", +] diff --git a/bigdata-skill/scripts/bigdata_toolkit/client.py b/bigdata-skill/scripts/bigdata_toolkit/client.py new file mode 100644 index 00000000..5a0d05c5 --- /dev/null +++ b/bigdata-skill/scripts/bigdata_toolkit/client.py @@ -0,0 +1,221 @@ +"""统一入口：一个 BigdataClient 暴露两种能力 +===================================================== + +1. **SDK 高层能力**（`self.bd`）—— 官方 `bigdata_client.Bigdata` + 封装好的 search / knowledge_graph / subscription / chat / watchlists。 + +2. **ad hoc REST 逃生舱**（`self.http`）—— `bd._api.http` + （`RateLimitedHTTPWrapper`，base url = ``https://api.bigdata.com/``）。 + SDK 高层没暴露的 endpoint（events-calendar / analyst-estimates / + latest-surprise / target-price / company-screener / quotas ...）全部 + 走这里。认证（ApiKeyAuth 注 JWT）+ 代理（靠 ``HTTPS_PROXY`` 环境变量） + **自动复用**，无需自己拼 header。 + +为什么需要逃生舱 +---------------- +``bigdata_client`` 的 ``BigdataConnection`` 只 wrap 了 +search / chunks / knowledge-graph / chat / watchlists / uploads。 +一整套 RavenPack 遗留的 ``/v1/*`` 结构化金融数据产品线（前瞻财报日历、 +一致预期、财报 surprise、评级、目标价、screener）SDK 一个高层方法都没写， +但同一后端、同一 JWT，raw http 直达。 + +机制证据链（运行时 L4 实测，非文档推断） +----------------------------------------- +- ``bd._api`` 是 ``bigdata_client.connection.BigdataConnection``。 +- 它持有 ``bd._api.http``（``RateLimitedHTTPWrapper``），``api_url='https://api.bigdata.com/'``。 +- SDK 高层方法（query_chunks / by_ids / autosuggest / get_my_quota ...） + 全都内部 delegate 到 ``self.http.post(endpoint, json=...)`` / + ``self.http.get(endpoint, params=...)``。 +- 所以打 SDK 没暴露的 endpoint = 直接调 ``self.http.(相对路径, ...)``。 + +路由形态规律（避免踩坑） +------------------------ +- 业务面是 ``POST /v1//query``，**裸 ``GET /v1/`` 会 404**。 +- 平台面（quotas）是 ``GET /v1/subscription/quotas``。 +- ``403 'Missing Authentication Token'`` = API Gateway 说该路径上无此路由 + （不是权限拒绝），``404`` = 路径不存在。需用文档（docs.bigdata.com/llms.txt） + 确认确切 path，不要瞎猜。 +""" + +from __future__ import annotations + +import inspect +import os +from typing import Any, Optional, Union + +from bigdata_client import Bigdata + +__all__ = ["BigdataClient", "require_env"] + + +def require_env(name: str) -> str: + """读环境变量，缺失立即 fail-fast（NO FALLBACK 原则）。 + + 禁止用明文 default 兜底 secret —— 这正是会被 scanner 扫到的反模式。 + """ + value = os.environ.get(name) + if not value: + raise RuntimeError( + f"Missing required env var: {name}. " + f"Set it before constructing BigdataClient, e.g. " + f"`export {name}=...`" + ) + return value + + +class BigdataClient: + """Bigdata.com 统一客户端 —— SDK 高层 + REST 逃生舱二合一。 + + Parameters + ---------- + api_key: + Bigdata API key（``bd_v2_...`` 形态）。默认从 ``BIGDATA_API_KEY`` + 环境变量读取（**绝不**硬编码）。 + check_proxy: + 若为 True（默认）且未显式传 ``proxy``，构造时检查 ``HTTPS_PROXY`` + 是否设置，未设则提醒（出站代理可走 env var 或 ``proxy=`` 参数，二选一）。 + verify_ssl: + 透传给官方 ``Bigdata(verify_ssl=...)``（``False`` 关校验，或传 CA 路径 + 字符串，见 ssl_verification.md）。代理做 TLS 拦截 / 自签证书时，传代理 + CA 路径是正道，优于盲重试。默认 None（用 SDK 默认）。⚠️ 不建议 ``False``。 + proxy: + 透传给官方 ``Bigdata(proxy=...)``（构造方式见 proxy_configuration.md）； + 与 ``HTTPS_PROXY`` env 二选一。默认 None（走 env var 路径）。 + + Examples + -------- + >>> import os + >>> os.environ["BIGDATA_API_KEY"] = "bd_v2_xxx" + >>> os.environ["HTTPS_PROXY"] = "http://127.0.0.1:8080" # 仅在需要出站代理时 + >>> client = BigdataClient() # doctest: +SKIP + >>> companies = client.bd.knowledge_graph.find_companies("Apple") # doctest: +SKIP + >>> quota = client.get_quota_raw() # doctest: +SKIP # REST 逃生舱 + """ + + #: REST 业务面路由前缀（仅文档用途，方法里仍传完整 endpoint） + API_BASE = "https://api.bigdata.com/" + + def __init__( + self, + api_key: Optional[str] = None, + *, + check_proxy: bool = True, + verify_ssl: Optional[Union[bool, str]] = None, + proxy: Optional[Any] = None, + ) -> None: + self.api_key = api_key or require_env("BIGDATA_API_KEY") + + if check_proxy and proxy is None and not ( + os.environ.get("HTTPS_PROXY") or os.environ.get("https_proxy") + ): + # 不抛错 —— 海外/无代理环境本就不需要。仅提醒。 + import warnings + + warnings.warn( + "HTTPS_PROXY 未设置。若你的网络需要出站代理才能访问 " + "api.bigdata.com，可 `export HTTPS_PROXY=http://:`，" + "或给 BigdataClient(proxy=...) 传官方 Proxy 对象（二选一，见 " + "proxy_configuration.md）。WebSocket（chat）另需 WSS_PROXY。", + stacklevel=2, + ) + + # ---- SDK 高层入口（verify_ssl / proxy 是官方构造器参数，仅在显式 + # 传入时透传，默认不改 SDK 行为）---- + sdk_kwargs: dict[str, Any] = {"api_key": self.api_key} + if verify_ssl is not None: + sdk_kwargs["verify_ssl"] = verify_ssl + if proxy is not None: + sdk_kwargs["proxy"] = proxy + self.bd = Bigdata(**sdk_kwargs) + + # ------------------------------------------------------------------ # + # REST 逃生舱直通 # + # ------------------------------------------------------------------ # + @property + def http(self): + """``bd._api.http`` —— RateLimitedHTTPWrapper（REST 直通入口）。 + + 签名（运行时确认）:: + + http.get(endpoint: str, params: dict = None) -> dict | list + http.post(endpoint: str, json: dict | list[dict]) -> dict | list + http.put(endpoint: str, json) -> dict | list + http.patch(endpoint: str, json) -> dict | list + http.delete(endpoint: str) -> dict | list + http.get_chunks(endpoint: str, chunk_size: int) -> Iterable[bytes] + http.async_get(list[...]) -> 并发 GET + + endpoint 是相对路径（如 ``"v1/events-calendar/query"``），内部 + ``urljoin(api_url, endpoint)`` 拼成绝对 URL；也接受绝对 URL。 + """ + return self.bd._api.http + + @property + def conn(self): + """``bd._api`` —— BigdataConnection（"for internal use only"）。 + + 除 ``.http`` 外，它还有一批高层封装方法可直接复用： + ``query_chunks`` / ``by_ids`` / ``autosuggest`` / + ``query_discovery_panel`` / ``download_annotated_dict`` / + ``get_my_quota`` / ``get_companies_by_isin`` 等。需要时优先用这些 + （它们内部已处理 request/response model），而非自己拼 raw http。 + """ + return self.bd._api + + def rest_get(self, endpoint: str, params: Optional[dict] = None) -> Any: + """REST GET（平台面，如 quotas）。薄封装 ``self.http.get``。 + + endpoint 形如 ``"v1/subscription/quotas"``（不带前导斜杠）。 + """ + return self.http.get(endpoint, params) + + def rest_post(self, endpoint: str, json: Any) -> Any: + """REST POST（业务面，统一 ``/v1//query`` 形态）。 + + 薄封装 ``self.http.post``。endpoint 形如 + ``"v1/events-calendar/query"``。 + """ + return self.http.post(endpoint, json) + + # ------------------------------------------------------------------ # + # 配额 / 计量（成本意识入口，详见 cost.py） # + # ------------------------------------------------------------------ # + def get_quota_raw(self) -> dict: + """原始 chunk 级配额（走 SDK 的 ``get_my_quota`` 封装方法）。 + + 返回 ``MyBigdataQuotaResponse.model_dump()``，含 + ``organization_quota.contextual_units_max_read`` 和 + ``organization_consumed.contextual_units_read``。 + **这是 chunk 计数器**（1 query_unit = 10 chunks），是成本模型的 + 承重字段。SDK 高层 ``subscription.get_details()`` 把它 ÷10 包装成 + query_unit 会丢失 chunk 语义，所以用这条 raw 路径。 + """ + resp = self.conn.get_my_quota() + return resp.model_dump() + + def get_quotas_v1(self) -> Any: + """实时细分配额（REST GET ``v1/subscription/quotas``）。 + + 返回结构 ``{'results': ..., 'errors': ..., 'metadata': ...}``， + 含 credits limit/usage/remaining + billing 周期 + units 细分 + （search:web_unit_read 等）。**这个 endpoint SDK 完全没有高层方法**， + 是逃生舱能打 SDK 缺失路由的直接证据。可在冷启动中途轮询做 + chunk→credit 换算率实测校准（免费，不按 chunk 计费）。 + """ + return self.rest_get("v1/subscription/quotas") + + # ------------------------------------------------------------------ # + # 调试辅助 # + # ------------------------------------------------------------------ # + def introspect_conn(self, max_chars: int = 2000) -> str: + """introspect ``bd._api`` 的方法 + 源码（开新 REST 路由前先看）。 + + 新 endpoint 不确定怎么打时，先看 ``query_chunks`` 等已有方法是 + 怎么 delegate 到 ``self.http`` 的，照葫芦画瓢。 + """ + methods = [m for m in dir(self.conn) if not m.startswith("_")] + try: + src = inspect.getsource(type(self.conn))[:max_chars] + except (OSError, TypeError): + src = "" + return f"methods={methods}\n\n--- source head ---\n{src}" diff --git a/bigdata-skill/scripts/bigdata_toolkit/cost.py b/bigdata-skill/scripts/bigdata_toolkit/cost.py new file mode 100644 index 00000000..aa2bb267 --- /dev/null +++ b/bigdata-skill/scripts/bigdata_toolkit/cost.py @@ -0,0 +1,192 @@ +"""chunk 消耗追踪 + 配额意识（成本承重模块） +============================================= + +Bigdata 按 **chunk** 计费。这个模块把计量单位、单价、配额查询、消耗 +delta 追踪、冷启动成本外推全部固化下来，让任何批量任务都带成本意识。 + +计量单位（运行时三处独立佐证坐实） +---------------------------------- +- ``1 query_unit = 10 chunks``（精确，SDK 把 raw chunk 数 ÷10 包装）。 + - ``search.py:166``: ``usage += query_chunks_response.chunks_count``（raw chunk 数） + - ``search.py:157``: ``get_usage()`` return ``usage / 10`` + - ``subscription.py:40``: ``query_unit_used = contextual_units_read / 10`` +- REST raw 计数器：``get_my_quota().organization_consumed.contextual_units_read`` + 是 chunk 数（不是 query_unit）。 + +单价（来自 docs.bigdata.com 公开 pricing，均为 list price） +-------------------------------------------------------------------------- +- Fast Search: $0.015 / query_unit +- Smart Search: $0.03 / query_unit +- Batch Search (async): $0.0075 / query_unit（50% 折扣） + +成本铁律（NO FALLBACK 类风险） +------------------------------ +``Search.run(limit)`` 的 ``limit`` 是 ``int`` 时走 **doc-limit**，按"每页 +返回的 chunk 数"计费；``ChunkLimit(n)`` 才按 chunk 计费。我们实测曾见 +run(1) ≈ run(10) ≈ ~52 query_unit 的差距——**但这是单点实测,官方计费文档 +未印证此倍数**,当方向性参考即可（倍数随标的/窗口浮动）。规则本身成立: +``max_chunks`` 是官方计费单位,务必走 ``ChunkLimit`` 而非裸 int。 + +> 一个默认参数就能静默烧光配额。冷启动脚本必须 code-review 保证零裸 +> ``run(int)``，全部走 ``ChunkLimit``。 + +trial 配额现实 +-------------- +一个典型的 1 周 full-content trial ≈ 67000 query_unit = 670000 chunks +≈ $1005（list price 名义值，以你账号实际 quota 为准）。机构级 universe +（100-200 标的）做一次多年回溯 backfill 即接近或超过整个 trial 配额 +（3 年季度 100 标的 = 89.6%；200 标的 = 180%）。**trial 只够 PoC 级 +抽样（≤20 标的单快照）**，全量上线需要更大的付费配额。 +""" + +from __future__ import annotations + +from dataclasses import dataclass, field +from typing import Any, Optional + +from .client import BigdataClient + +__all__ = ["CostTracker", "CostModel", "CHUNKS_PER_QUERY_UNIT", "USD_PER_QUERY_UNIT"] + +#: 计量换算常量（运行时坐实） +CHUNKS_PER_QUERY_UNIT = 10 + +#: 单价表（USD / query_unit，public list price） +USD_PER_QUERY_UNIT = { + "fast": 0.015, + "smart": 0.03, + "batch": 0.0075, +} + + +@dataclass +class CostModel: + """成本外推模型（纯计算，无 IO）。 + + 用于冷启动 backfill 前估算配额消耗，**禁止用代码行数等无关指标**， + 只按 chunk 真实计费口径算。 + """ + + chunk_limit_per_query: int = 500 + """每次 search 的 chunk 上限（必须配合 ChunkLimit 使用，否则估算无效）。""" + + tier: str = "fast" + """计费档：fast / smart / batch。""" + + trial_query_units: int = 67000 + """trial 配额基数（query_unit），用于 ``pct_of_trial_quota`` 估算。默认 + 67000 = 典型 1 周 full-content trial ≈ $1005 list。换成你账号的实际额度 + （看 ``CostTracker.quota()`` 的 max_query_units）即可让百分比准确。""" + + def query_units_per_query(self) -> float: + """单次查询消耗的 query_unit = chunk_limit / 10。""" + return self.chunk_limit_per_query / CHUNKS_PER_QUERY_UNIT + + def estimate( + self, + n_entities: int, + n_windows: int = 1, + ) -> dict: + """估算一次冷启动 backfill 的总成本。 + + Parameters + ---------- + n_entities: + 标的数量。 + n_windows: + 时间窗数量（如 3 年 × 季度 = 12 个窗）。 + + Returns + ------- + dict + total_query_units / total_chunks / usd / pct_of_trial_quota。 + """ + qu_per_query = self.query_units_per_query() + total_queries = n_entities * n_windows + total_qu = qu_per_query * total_queries + unit_price = USD_PER_QUERY_UNIT.get(self.tier, USD_PER_QUERY_UNIT["fast"]) + return { + "n_entities": n_entities, + "n_windows": n_windows, + "chunk_limit_per_query": self.chunk_limit_per_query, + "query_units_per_query": qu_per_query, + "total_queries": total_queries, + "total_query_units": total_qu, + "total_chunks": total_qu * CHUNKS_PER_QUERY_UNIT, + "tier": self.tier, + "usd": round(total_qu * unit_price, 2), + "pct_of_trial_quota": round(total_qu / self.trial_query_units * 100, 1), + } + + +@dataclass +class CostTracker: + """实时配额追踪 + 消耗 delta 计量（带 IO，查真实配额）。 + + 用法：操作前 ``snapshot()`` 记起点，操作后 ``delta()`` 看实际烧了多少 + chunk —— 用真实用量校准 :class:`CostModel` 的外推（替代纯估算）。 + """ + + client: BigdataClient + _baseline_chunks: Optional[int] = field(default=None, init=False) + + # ------------------------------------------------------------------ # + # 配额查询 # + # ------------------------------------------------------------------ # + def quota(self) -> dict: + """当前 chunk 级配额（走 SDK ``get_my_quota`` 封装）。 + + Returns + ------- + dict + max_chunks / used_chunks / remaining_chunks / used_query_units / + remaining_query_units / pct_used。 + """ + raw = self.client.get_quota_raw() + max_chunks = raw["organization_quota"]["contextual_units_max_read"] + used_chunks = raw["organization_consumed"]["contextual_units_read"] + remaining = max_chunks - used_chunks + return { + "max_chunks": max_chunks, + "used_chunks": used_chunks, + "remaining_chunks": remaining, + "used_query_units": round(used_chunks / CHUNKS_PER_QUERY_UNIT, 1), + "remaining_query_units": round(remaining / CHUNKS_PER_QUERY_UNIT, 1), + "max_query_units": round(max_chunks / CHUNKS_PER_QUERY_UNIT, 1), + "pct_used": round(used_chunks / max_chunks * 100, 2) if max_chunks else None, + } + + def quota_detailed_raw(self) -> Any: + """实时细分配额（REST ``v1/subscription/quotas``，免费旁路）。 + + 含 billing 周期 + units 细分。可在冷启动中途轮询此 endpoint 实测 + chunk→credit 换算率做校准。**这个 endpoint SDK 没有高层方法**。 + """ + return self.client.get_quotas_v1() + + # ------------------------------------------------------------------ # + # 消耗 delta 追踪 # + # ------------------------------------------------------------------ # + def snapshot(self) -> int: + """记录当前已用 chunk 数为基线，返回该值。""" + self._baseline_chunks = self.quota()["used_chunks"] + return self._baseline_chunks + + def delta(self) -> dict: + """相对上次 ``snapshot()`` 的消耗 delta（chunk + query_unit + USD 估算）。 + + 必须先调 ``snapshot()``，否则抛错（不猜基线，NO FALLBACK）。 + """ + if self._baseline_chunks is None: + raise RuntimeError("call snapshot() before delta()") + now_chunks = self.quota()["used_chunks"] + delta_chunks = now_chunks - self._baseline_chunks + delta_qu = delta_chunks / CHUNKS_PER_QUERY_UNIT + return { + "delta_chunks": delta_chunks, + "delta_query_units": round(delta_qu, 2), + "usd_fast": round(delta_qu * USD_PER_QUERY_UNIT["fast"], 4), + "usd_smart": round(delta_qu * USD_PER_QUERY_UNIT["smart"], 4), + "baseline_chunks": self._baseline_chunks, + "now_chunks": now_chunks, + } diff --git a/bigdata-skill/scripts/bigdata_toolkit/kg.py b/bigdata-skill/scripts/bigdata_toolkit/kg.py new file mode 100644 index 00000000..fbce6e5a --- /dev/null +++ b/bigdata-skill/scripts/bigdata_toolkit/kg.py @@ -0,0 +1,153 @@ +"""实体解析 + crosswalk（SDK 高层路径） +======================================= + +封装 ``bd.knowledge_graph``，把"公司名 / ISIN / 交易所代码"解析成 +**rp_entity_id**（6 位字母数字，如 Apple = ``D8442A``、贵州茅台 = +``914E1F``）。 + +为什么这是 gateway +------------------ +Bigdata 几乎所有能力都以 rp_entity_id 为主键： +- search 的 ``Entity(id)``（见 search.py） +- rest_ext 的 events-calendar / analyst-estimates / surprise（见 rest_ext.py） + +**A 股标的的唯一可用解析路径**（实测）： +- 中文名直查 ``find_companies('贵州茅台')`` → **0 命中**（数据源中文实体层空） +- 英文官方名 ``find_companies('Kweichow Moutai')`` → 命中 ``914E1F`` +- ISIN crosswalk ``get_companies_by_isin(['CNE0000018R8'])`` → ``914E1F`` + +所以 A 股请用 **英文官方名** 或 **ISIN** 解析，不要用中文名。 + +方法签名（运行时确认） +---------------------- +- ``kg.find_companies(values, /, type=None, country=None, limit=20)`` +- ``kg.find_topics(values, /, limit=20)`` +- ``kg.find_sources(values, /, limit=20, country=None, rank=None, retention=None)`` +- ``kg.get_companies_by_isin(isins: list[str]) -> list[Company | None]`` +- ``kg.get_companies_by_cusip / _by_sedol / _by_listing`` +- ``kg.get_entities(ids: list[str], /)`` —— **同时解 COMP 实体 + TOPC 话题** + （不是 ENTITY-only） +- ``kg.find_topics`` —— 中文话题（如 '人工智能'）实测 0 命中，TOPIC 解析 + 同样卡在中文层 + +注意 +---- +``kg.autosuggest`` 在 API-key 模式下 ``NotImplementedError``（与 uploads +同族），交互式补全用不了；实体解析只能走 ``find_*`` 系列。 +""" + +from __future__ import annotations + +from typing import Any, Optional + +from .client import BigdataClient + +__all__ = ["EntityResolver", "company_to_dict"] + + +def company_to_dict(company: Any) -> dict: + """``Company`` 实体 → 精简 dict（id + 名称 + 国家 + ticker）。 + + 字段名做防御性提取（不同 SDK 版本属性名可能微调）。 + """ + if company is None: + return {} + return { + "id": getattr(company, "id", None), # rp_entity_id + "name": getattr(company, "name", None), + "ticker": getattr(company, "ticker", None), + "country": getattr(company, "country", None), + "sector": getattr(company, "sector", None), + "industry": getattr(company, "industry", None), + "isin": getattr(company, "isin", None), + "entity_type": getattr(company, "entity_type", None), + } + + +class EntityResolver: + """公司 / 话题实体解析（SDK 高层）。""" + + def __init__(self, client: BigdataClient) -> None: + self.client = client + + @property + def kg(self): + return self.client.bd.knowledge_graph + + # ------------------------------------------------------------------ # + # 公司解析 # + # ------------------------------------------------------------------ # + def find_companies( + self, + name: str, + *, + country: Optional[str] = None, + limit: int = 5, + as_dict: bool = True, + ): + """按名称解析公司。 + + ⚠️ A 股请用 **英文官方名**（'Kweichow Moutai' 而非 '贵州茅台'）。 + ``country`` 用 ISO-2（'CN' / 'US' / 'HK'）。 + """ + result = self.kg.find_companies(name, country=country, limit=limit) + # find_companies 单值返回 list；多值返回 dict[str, list] + companies = result if isinstance(result, list) else result.get(name, []) + if as_dict: + return [company_to_dict(c) for c in companies] + return companies + + def resolve_id( + self, + name: str, + *, + country: Optional[str] = None, + ) -> Optional[str]: + """解析公司名 → 单个 rp_entity_id（取第一个命中）。 + + 命中 0 个返回 None（**不猜、不 fallback**，NO FALLBACK 原则）。 + A 股中文名大概率返回 None —— 改用英文名或 ``resolve_by_isin``。 + """ + companies = self.find_companies(name, country=country, limit=1, as_dict=True) + if not companies: + return None + return companies[0].get("id") + + # ------------------------------------------------------------------ # + # crosswalk：ISIN / CUSIP / SEDOL / 交易所代码 → rp_entity_id # + # ------------------------------------------------------------------ # + def resolve_by_isin(self, isins: list[str], *, as_dict: bool = True): + """ISIN crosswalk（A 股最可靠路径，如 茅台 CNE0000018R8 → 914E1F）。 + + 返回与输入等长的 list（未命中位置为 None / {}）。 + """ + companies = self.kg.get_companies_by_isin(isins) + if as_dict: + return [company_to_dict(c) for c in companies] + return companies + + def resolve_by_cusip(self, cusips: list[str], *, as_dict: bool = True): + """CUSIP crosswalk（美股）。""" + companies = self.kg.get_companies_by_cusip(cusips) + return [company_to_dict(c) for c in companies] if as_dict else companies + + def resolve_by_sedol(self, sedols: list[str], *, as_dict: bool = True): + """SEDOL crosswalk。""" + companies = self.kg.get_companies_by_sedol(sedols) + return [company_to_dict(c) for c in companies] if as_dict else companies + + # ------------------------------------------------------------------ # + # 话题 / 通用实体解析 # + # ------------------------------------------------------------------ # + def find_topics(self, values, *, limit: int = 5, as_dict: bool = False): + """解析话题（TOPC）。⚠️ 中文话题实测 0 命中。""" + result = self.kg.find_topics(values, limit=limit) + return result + + def get_entities(self, ids: list[str]): + """按 id 批量解实体。**同时解 COMP（公司）+ TOPC（话题）**，非 ENTITY-only。 + + 实测：传 dotted topic id 返回 ``Topic(...)``，传 rp_entity_id 返回 + ``Company(...)``。 + """ + return self.kg.get_entities(ids) diff --git a/bigdata-skill/scripts/bigdata_toolkit/rest_ext.py b/bigdata-skill/scripts/bigdata_toolkit/rest_ext.py new file mode 100644 index 00000000..e40307d6 --- /dev/null +++ b/bigdata-skill/scripts/bigdata_toolkit/rest_ext.py @@ -0,0 +1,592 @@ +"""SDK 没有的能力：用 bd._api 打 REST（逃生舱） +================================================ + +``bigdata_client`` 的 ``BigdataConnection`` 只 wrap 了 search / chunks / +KG / chat / watchlists / uploads。一整套 RavenPack 遗留的 ``/v1/*`` +**结构化金融数据产品线** SDK 一个高层方法都没写。本模块用 +``client.http.post(endpoint, json)`` 直打这些 endpoint，复用 SDK 的 +JWT 认证 + 代理。 + +覆盖的 endpoint（概览） +---------------------- +本模块用 ``client.http.post`` 直打 SDK 没封的 ``/v1/*`` 结构化金融数据：前瞻 +（estimates / events-calendar / surprise / ratings / target）、财报三表 + TTM +指标比率、公司画像、行情、分红、分部营收、entity-sentiment、co-mention、 +company-screener，加 reporting_period 回填（``cqs/query-chunks``，特殊、按 chunk +计费）。**完整方法清单 + 精确签名 + 验证等级（L3/L4）以 +``references/verified_api_signatures.md`` 为单一权威**——此处只给覆盖范围,不复述 +具体路径与等级（避免改一处漏同步,本周期就因这张复制表漏改过 ratings/target 的等级）。 + +关键修正（推翻早期 "Bigdata 中文/A股一刀切失效" 结论） +------------------------------------------------------ +**必须拆成两个数据面分开讲：** + +1. **结构化金融面**（本模块的 /v1/* 全家桶）——对大陆 A 股 + 港股 **可用**： + - 茅台 ``914E1F`` events-calendar 返回前瞻日历、analyst-estimates 返回 + consensus、latest-surprise 返回 reporting_date + actual vs estimated + （实测 A 股结构面数据有近月更新，非历史陈值）。 + - 经 rp_entity_id（英文名 or ISIN crosswalk 解析，见 kg.py）。 + - ⚠️ A 股结构数据有空洞：茅台 price-target 只返回 entity 无 + target_high/low/consensus（美股 AAPL 完整）。 + +2. **非结构化中文 NLP 面**（中文新闻实体检测 / 中文情绪）—— **确认死路**， + SDK 和 REST 都救不了，数据源真没有。 + +路由 / 报错坑（避免后续踩） +-------------------------- +- 业务面只对 ``POST + /query`` 注册；裸 ``GET /v1/`` 会 404。 +- ``403 'Missing Authentication Token'`` = 该 auth path 上无此路由（不是 + 权限拒绝）；``404`` = 路径不存在。 +- analyst-estimates 的 ``period=quarter`` 实测 ``limit`` 上限约 20， + ``limit=30`` 直接 400（报错信息极不友好，别误判为 endpoint 挂了）。 +- company-screener 的 filter **必须嵌套在 ``"filters"`` 对象**里 + （market_cap_more_than / sector / industry / country / exchange / is_etf）； + ``limit`` 在 top-level,≤1000。平铺 filter 不报错但被静默忽略、返回未过滤结果。 + +成本 +---- +这些 analyst/events/quota endpoint **不按 chunk 计费**（只 search 的 +query-chunks 才 usage += chunks_count）。本模块默认 limit 极小，近乎零成本。 +唯一例外：``fetch_reporting_period`` 走 ``cqs/query-chunks``，**按 chunk 计费**， +故默认 chunk_limit 很小。 + +只读说明 +-------- +本模块全部走只读查询（GET / POST query），无写入、无上传。 +""" + +from __future__ import annotations + +from typing import Any, Optional + +from .client import BigdataClient + +__all__ = ["StructuredDataREST", "fields_values_to_records", "BatchSearch"] + + +def _entity_id_body(rp_entity_id: str | list[str], key: str = "rp_entity_id") -> dict: + """统一构造 entity 维度 body（events-calendar 用 rp_entity_id 数组）。""" + ids = rp_entity_id if isinstance(rp_entity_id, list) else [rp_entity_id] + return {key: ids} + + +def _ident(rp_entity_id: str | list[str]) -> dict: + """单标的 endpoint 的 identifier 形态（analyst / financials / market-data 系列共用）。 + + OpenAPI spec + contract test 确认:这一大批 endpoint 用 + ``{"identifier": {"type": "rp_entity_id", "value": id}}``, + 与 events-calendar 的 ``{"rp_entity_id": [...]}`` 数组形态不同（各自固定）。 + """ + return {"identifier": {"type": "rp_entity_id", "value": rp_entity_id}} + + +def fields_values_to_records(result: Any) -> Any: + """把 ``{fields: [...], values: [[...]]}`` 拼成 ``[{field: val}]`` 方便消费。 + + 财报（income/balance/cash-flow）、行情（daily-prices）、分红、分部营收 + 等 endpoint 的 ``results`` 是 ``{fields, values}``（单实体）或其 list（多实体）。 + TTM / profile 系列已是扁平 ``[{...}]``,原样返回。 + """ + res = result.get("results", result) if isinstance(result, dict) else result + + def _one(d): + if isinstance(d, dict) and d.get("fields") and d.get("values") is not None: + return [dict(zip(d["fields"], row)) for row in d["values"]] + return d + + if isinstance(res, dict): + return _one(res) + if isinstance(res, list): + records = [_one(d) for d in res] + # 单实体（最常见的单标的查询，如 daily_prices / dividends 的 + # ``results`` 是含一个实体的 list）直接 flatten 成记录列表,与 + # dict-results（income/balance 等）行为一致;多实体才返回每实体一组。 + return records[0] if len(records) == 1 else records + return res + + +class StructuredDataREST: + """SDK 缺失的结构化金融数据（全部走 bd._api.http REST 逃生舱）。 + + 所有方法返回 **原始 dict/list**（不做强 schema 解析）——因为这些是 + 半文档化的 RavenPack 遗留 endpoint，schema 可能随后端变更。消费者按 + 实际返回的 key 取值，并自行加 schema 防御。 + """ + + def __init__(self, client: BigdataClient) -> None: + self.client = client + + @property + def http(self): + return self.client.http + + # ------------------------------------------------------------------ # + # 1) 前瞻财报/电话会日历（L4 实打） # + # ------------------------------------------------------------------ # + def events_calendar( + self, + rp_entity_id: Optional[str | list[str]] = None, + *, + categories: Optional[list[str]] = None, + start_date: Optional[str] = None, + end_date: Optional[str] = None, + countries: Optional[list[str]] = None, + limit: int = 5, + cursor: Optional[str] = None, + ) -> Any: + """前瞻财报/电话会日历。``POST v1/events-calendar/query``。 + + 两种用法： + - **单/多标的**：传 ``rp_entity_id``（前瞻该标的财报日历）。 + - **全市场广扫**：不传 entity，传 ``countries=['US']`` + 日期窗， + 配合 ``cursor`` 分页扫全市场（回答"下周谁发财报"/冷启动筛选）。 + + Parameters + ---------- + categories: + 如 ``['earnings-call']`` / ``['conference-call']``。 + start_date, end_date: + ``'YYYY-MM-DD'``。 + limit: + ≤1000。默认 5（成本意识，且本 endpoint 不按 chunk 计费）。 + + Returns + ------- + dict + ``{'results': ..., 'pagination': ...}``（实测顶层 key）。 + event 项含 category / event_datetime / title / fiscal_year / + fiscal_period / updated_at 等（前瞻数据，event_datetime 为未来日期）。 + """ + body: dict[str, Any] = {} + if rp_entity_id is not None: + body.update(_entity_id_body(rp_entity_id)) + if categories is not None: + body["categories"] = categories + if start_date is not None: + body["start_date"] = start_date + if end_date is not None: + body["end_date"] = end_date + if countries is not None: + body["countries"] = countries + if cursor is not None: + body["cursor"] = cursor + body["limit"] = limit + return self.http.post("v1/events-calendar/query", body) + + # ------------------------------------------------------------------ # + # 2) 前瞻一致预期（L4 实打） # + # ------------------------------------------------------------------ # + def analyst_estimates( + self, + rp_entity_id: str, + *, + period: str = "quarter", + limit: int = 5, + ) -> Any: + """前瞻逐期一致预期。``POST v1/analyst-estimates/query``。 + + 返回 FISCAL_PERIOD_END_DATE + REVENUE/EBITDA/EBIT/NET_INCOME/SGA/EPS + 各 LOW/HIGH/AVG + NUM_ANALYSTS_REVENUE/EPS。实测美股可给到 ~2.5 年 + 前瞻（Apple 到 2028Q3）。 + + Parameters + ---------- + period: + ``'quarter'`` 或 ``'annual'``。 + limit: + ⚠️ ``period=quarter`` 实测上限约 20，超出报 400。默认 5。 + + Notes + ----- + OpenAPI spec + contract test 确认 identifier 形态为 + ``{"type": "rp_entity_id", "value": id}``（analyst / financials / + market-data 系列统一,与 events-calendar 的 ``rp_entity_id`` 数组不同, + 各自固定——不是"两种都试")。 + """ + body = { + "identifier": {"type": "rp_entity_id", "value": rp_entity_id}, + "period": period, + "limit": limit, + } + return self.http.post("v1/analyst-estimates/query", body) + + # ------------------------------------------------------------------ # + # 3) 最近一期财报 surprise（L4 实打） # + # ------------------------------------------------------------------ # + def latest_surprise(self, rp_entity_id: str) -> Any: + """最近一期财报 surprise。``POST v1/latest-surprise/query``。 + + 返回 reporting_date + eps_actual/eps_estimated/eps_surprise_pct + + revenue_actual/revenue_estimated/revenue_surprise_pct + last_updated。 + + ⚠️ 名字是 "latest" —— 只返回最近一期（实测单条）。历史 surprise + 序列本方法拿不到（可能需翻 analyst-estimates 历史行自算）。 + """ + body = {"identifier": {"type": "rp_entity_id", "value": rp_entity_id}} + return self.http.post("v1/latest-surprise/query", body) + + # ------------------------------------------------------------------ # + # 4) 分析师评级一致（L3 文档证实，未运行时实打） # + # ------------------------------------------------------------------ # + def analyst_ratings(self, rp_entity_id: str) -> Any: + """买卖评级一致。``POST v1/analyst-ratings/query``。 + + 文档：返回 strong_buy/buy/hold/sell/strong_sell + consensus。 + 验证等级 L4（2026-05-31 实跑确认返回 ``{results}``，升自 L3）。 + identifier 形态同 analyst_estimates（spec 确认的 identifier 对象）。 + """ + body = {"identifier": {"type": "rp_entity_id", "value": rp_entity_id}} + return self.http.post("v1/analyst-ratings/query", body) + + # ------------------------------------------------------------------ # + # 5) 目标价 consensus（L3 文档证实） # + # ------------------------------------------------------------------ # + def price_target(self, rp_entity_id: str) -> Any: + """目标价一致预期。``POST v1/price/target/query``。 + + 文档：返回 target high/low/consensus/median + currency。 + ⚠️ A 股有空洞：部分 A 股只返回 entity 无 target 数值（美股如 AAPL + 则完整返回 target high/low/consensus 数值）。 + 验证等级 L4（2026-05-31 实跑，升自 L3）。identifier 形态同 analyst_estimates（spec 确认的 identifier 对象）。 + """ + body = {"identifier": {"type": "rp_entity_id", "value": rp_entity_id}} + return self.http.post("v1/price/target/query", body) + + # ------------------------------------------------------------------ # + # 6) universe 构建：公司筛选器（L4 endpoint 可达） # + # ------------------------------------------------------------------ # + def company_screener( + self, + *, + market_cap_more_than: Optional[float] = None, + market_cap_lower_than: Optional[float] = None, + sector: Optional[str] = None, + industry: Optional[str] = None, + country: Optional[str] = None, + exchange: Optional[str] = None, + is_etf: Optional[bool] = None, + limit: int = 10, + **extra_filters: Any, + ) -> Any: + """股票池筛选器。``POST v1/company-screener/query``。 + + ⚠️ filter **必须嵌套在 ``"filters"`` 对象**里 + （``{"filters": {...}, "limit": n}``）。平铺在 top-level **不报错但被后端 + 静默忽略、返回未过滤结果**（实测裁决 2026-05-30,见 known_pitfalls #6）。 + ``limit`` 在 top-level,≤1000。 + + ``extra_filters`` 透传其它 flat filter（如 ``beta_more_than`` 等， + 以文档为准）。 + """ + filters: dict[str, Any] = {} + if market_cap_more_than is not None: + filters["market_cap_more_than"] = market_cap_more_than + if market_cap_lower_than is not None: + filters["market_cap_lower_than"] = market_cap_lower_than + if sector is not None: + filters["sector"] = sector + if industry is not None: + filters["industry"] = industry + if country is not None: + filters["country"] = country + if exchange is not None: + filters["exchange"] = exchange + if is_etf is not None: + filters["is_etf"] = is_etf + filters.update(extra_filters) + # ⚠️ filter 必须嵌套在 "filters" 对象里；平铺 top-level 不报错但被后端 + # 静默忽略（返回未过滤结果）。实测裁决 2026-05-30,见 known_pitfalls #6。 + return self.http.post( + "v1/company-screener/query", {"filters": filters, "limit": limit} + ) + + # ================================================================== # + # 历史财务报表（三大表 + 分部营收，identifier + period + limit） # + # 不按 chunk 计费；contract-tested 2026-05-30；results 为 # + # {fields, values}，用 fields_values_to_records() 拼成记录。 # + # ================================================================== # + def income_statement(self, rp_entity_id: str, *, period: str = "annual", limit: int = 5) -> Any: + """历史利润表。``POST v1/income-statement/query``。 + + ``results.fields`` 含 REVENUE / GROSS_PROFIT / OPERATING_INCOME / + EBITDA / EBIT / NET_INCOME / R&D / SG&A 等。``period``: ``annual`` / ``quarter``。 + """ + body = _ident(rp_entity_id) + body.update(period=period, limit=limit) + return self.http.post("v1/income-statement/query", body) + + def balance_sheet(self, rp_entity_id: str, *, period: str = "annual", limit: int = 5) -> Any: + """历史资产负债表。``POST v1/balance-sheet/query``。 + + ``results.fields`` 含 TOTAL_ASSETS / TOTAL_LIABILITIES / TOTAL_DEBT / + NET_DEBT / CASH_AND_CASH_EQUIVALENTS / TOTAL_STOCKHOLDERS_EQUITY 等。 + """ + body = _ident(rp_entity_id) + body.update(period=period, limit=limit) + return self.http.post("v1/balance-sheet/query", body) + + def cash_flow_statement(self, rp_entity_id: str, *, period: str = "annual", limit: int = 5) -> Any: + """历史现金流量表。``POST v1/cash-flow-statement/query``。 + + ``results.fields`` 含 OPERATING_CASH_FLOW / FREE_CASH_FLOW / + CAPITAL_EXPENDITURE / NET_INCOME / STOCK_BASED_COMPENSATION 等。 + """ + body = _ident(rp_entity_id) + body.update(period=period, limit=limit) + return self.http.post("v1/cash-flow-statement/query", body) + + def revenue_geographic_segments(self, rp_entity_id: str, *, period: str = "annual", limit: int = 10) -> Any: + """分地区营收。``POST v1/company-revenue-geographic-segments/query``。 + + ``results.values`` 每行 ``[FISCAL_YEAR, PERIOD, CURRENCY, {地区: 营收}]``。 + """ + body = _ident(rp_entity_id) + body.update(period=period, limit=limit) + return self.http.post("v1/company-revenue-geographic-segments/query", body) + + def revenue_product_segments(self, rp_entity_id: str, *, period: str = "annual", limit: int = 10) -> Any: + """分产品营收。``POST v1/company-revenue-product-segments/query``。 + + ``results.values`` 每行 ``[FISCAL_YEAR, PERIOD, CURRENCY, {产品线: 营收}]`` + （如 NVDA 的 GPU / Tegra ...）。 + """ + body = _ident(rp_entity_id) + body.update(period=period, limit=limit) + return self.http.post("v1/company-revenue-product-segments/query", body) + + # ================================================================== # + # TTM 指标 / 比率 / 公司画像（identifier；results 为扁平 [{...}]） # + # 不按 chunk 计费；contract-tested 2026-05-30。 # + # ================================================================== # + def key_metrics_ttm(self, rp_entity_id: str) -> Any: + """TTM 关键指标。``POST v1/key-metrics-ttm/query``。 + + 扁平字段含 enterprise_value_ttm / ev_to_ebitda_ttm / + return_on_equity_ttm / return_on_invested_capital_ttm / + free_cash_flow_yield_ttm / earnings_yield_ttm 等。 + """ + return self.http.post("v1/key-metrics-ttm/query", _ident(rp_entity_id)) + + def company_ratios_ttm(self, rp_entity_id: str) -> Any: + """TTM 财务比率。``POST v1/company-ratios-ttm/query``。 + + 扁平字段含 gross_profit_margin_ttm / net_profit_margin_ttm / + price_to_earnings_ratio_ttm / price_to_book_ratio_ttm / + debt_to_equity_ratio_ttm / dividend_yield_ttm 等。 + """ + return self.http.post("v1/company-ratios-ttm/query", _ident(rp_entity_id)) + + def company_profile(self, rp_entity_id: str) -> Any: + """公司画像。``POST v1/company-profile/query``。 + + 扁平字段含 company_name / ceo / sector / industry / website / + description / full_time_employees / ipo_date / isin / cusip / exchange 等。 + """ + return self.http.post("v1/company-profile/query", _ident(rp_entity_id)) + + # ================================================================== # + # 市场数据（行情 / 分红，identifier + date_range） # + # 不按 chunk 计费；contract-tested 2026-05-30；results 为 {fields, values}。# + # ================================================================== # + def daily_prices(self, rp_entity_id: str, *, start_date: str, end_date: str) -> Any: + """日线 OHLC。``POST v1/price/daily/query``。 + + ``results.fields`` = DATE / OPEN / LOW / HIGH / CLOSE / VOLUME / + CHANGE / CHANGE_PERCENT / VWAP / CURRENCY。日期 ``YYYY-MM-DD``。 + """ + body = _ident(rp_entity_id) + body["date_range"] = {"start": start_date, "end": end_date} + return self.http.post("v1/price/daily/query", body) + + def dividends(self, rp_entity_id: str, *, start_date: str, end_date: str) -> Any: + """分红历史。``POST v1/dividends/query``（注意:不是 ``v1/price/dividends``）。 + + ``results.fields`` = DATE / DIVIDEND / ADJ_DIVIDEND / RECORD_DATE / + PAYMENT_DATE / DECLARATION_DATE / YIELD / FREQUENCY。 + """ + body = _ident(rp_entity_id) + body["date_range"] = {"start": start_date, "end": end_date} + return self.http.post("v1/dividends/query", body) + + # ================================================================== # + # 聚合情感时间序列（identifier + timestamp，不按 chunk 计费） # + # ================================================================== # + def entity_sentiment(self, rp_entity_id: str, *, start_date: str, end_date: str) -> Any: + """日频聚合情感时间序列。``POST v1/entity-sentiment/``（**尾斜杠，非 /query**）。 + + ``results[].values`` 每点含 date / daily_sentiment（日均事件情感）/ + sentiment_pressure（异常情感强度）/ abnormal_media_attention（异常关注量）。 + **这是官方现成的日频情感序列——不必从 chunk 自聚合**。contract-tested 2026-05-30。 + """ + body = _ident(rp_entity_id) + body["timestamp"] = {"start": start_date, "end": end_date} + return self.http.post("v1/entity-sentiment/", body) + + # ================================================================== # + # 实体共现关系图（⚠️ 走 search 系，**按 chunk 计费**！） # + # ================================================================== # + def connected_entities( + self, + rp_entity_id: str, + *, + date_range: Optional[dict] = None, + limit: int = 10, + ) -> Any: + """实体共现（co-mention）关系图。``POST v1/search/co-mentions/entities``。 + + ``results`` 按类别（places / companies / organizations / people / + products / concepts）分组,每个实体含 ``total_chunks_count`` / + ``total_headlines_count``（按共现量排序）—— 用于建供应链 / 竞品 / 客户 + 共现网络。**要某一类就直接读对应分组**（结果本就按类分好）。 + + Parameters + ---------- + date_range: + 可选,``{"start": "2024-01-01T00:00:00Z", "end": "2024-12-31T23:59:59Z"}`` + （ANSI date-time + UTC,**带时分秒,非 YYYY-MM-DD**）→ 透传到 + ``query.filters.timestamp``,看某时间窗内的共现（关系随时间演化）。 + + ⚠️ **本方法按 chunk 计费**（响应含 ``usage.api_query_units``）,与 + financials / market-data 那批免费 endpoint 不同,默认 limit 小。 + + Notes + ----- + co-mentions/entities 的 body **没有 ``entity_categories`` 参数**（OpenAPI + spec 确认；早期版本曾透传它做类别过滤,实测无效、已移除——按类别就直接读 + 返回的分组）。``date_range`` 走 ``query.filters.timestamp``,contract-tested。 + """ + filters: dict[str, Any] = {"entity": {"any_of": [rp_entity_id]}} + if date_range is not None: + filters["timestamp"] = date_range + body = {"query": {"filters": filters}, "limit": limit} + return self.http.post("v1/search/co-mentions/entities", body) + + # ================================================================== # + # 特殊:reporting_period 回填（SDK 砍字段，REST 有，**按 chunk 计费**！）# + # ================================================================== # + def fetch_reporting_period_raw(self, payload: dict) -> Any: + """直打 ``cqs/query-chunks`` 拿原始 ``stories[].reportingPeriod``。 + + **根因**：``reporting_period`` 在 REST wire 上存在且填充率约 75% + （filings），但 SDK 的 ``ChunkedDocumentResponse`` 模型没有这个字段， + pydantic 默认丢弃 → ``Document.reporting_period`` 永远 None。绕过 + SDK 模型、直读 raw JSON 的 ``reportingPeriod`` 才能回填。 + + 格式两类共存：绝对财年 ``'2026FY'`` + 相对财季 ``'FQ1'-'FQ4'``。 + ⚠️ ``'FQ1'`` 无年份锚点，需结合同 story 的 ``'YYYYFY'`` 或 timestamp + 二次推断，直接当结构化季度键有歧义。 + + ⚠️ **本方法按 chunk 计费**（走 query-chunks）。``payload`` 请自行 + 控制 chunk 规模。payload 即 ``POST cqs/query-chunks`` 的 body + （可先 monkeypatch ``http.post`` 抓 SDK 真实 payload 拿 schema， + 见 examples）。 + + Returns + ------- + dict + 原始 query-chunks 响应；``stories[].reportingPeriod`` / + ``reportingEntities`` / ``documentType`` 为 camelCase wire 字段。 + """ + return self.http.post("cqs/query-chunks", payload) + + +class BatchSearch: + """Batch search 异步流程（chunk 计费，但比 fast 便宜 **50%**）。 + + 适合一次性打包大量 search query（如给单标的做多主题 × 多时间窗的海量 + 证据流回填）—— N 个 search 打成一个 batch，单价从 ``$0.015`` 降到 + ``$0.0075`` / query_unit。 + + 流程（2026-05-31 contract-tested：``create_job`` / ``upload_input`` / + ``get_status`` 轮询 = **L4 实跑**（含 upload 的 Content-Type 403 bug 修复， + 实测状态流转 pending→processing）；``download_results`` 是标准 S3 GET，因 + smart batch 处理 >10min 未跑到 completed 而**未端到端验**——用时若异常照本 + docstring 自查）:: + + bs = BatchSearch(client) + job = bs.create_job() # {batch_id, presigned_url} + jsonl = bs.build_input_jsonl([{...search1...}, {...search2...}]) + bs.upload_input(job["presigned_url"], jsonl) # PUT 到 S3 presigned + st = bs.get_status(job["batch_id"]) # poll 到 completed + rows = bs.download_results(st["output_file_url"]) + + 每行 jsonl = 一个 ``POST v1/search`` 的 body（``search_mode`` fast/smart + + query/filters）。轮询 ``status`` 到 ``completed``（``output_file_url`` 可用） + 或 ``failed``。 + """ + + def __init__(self, client: BigdataClient) -> None: + self.client = client + + @property + def http(self): + return self.client.http + + def create_job(self) -> dict: + """创建 batch job。``POST v1/search/batches``（无需 body）。 + + 返回 ``{batch_id, presigned_url}`` —— 把 .jsonl 输入 PUT 到 presigned_url。 + """ + return self.http.post("v1/search/batches", {}) + + def get_status(self, batch_id: str) -> dict: + """查 batch 状态。``GET v1/search/batches/{batch_id}``。 + + 返回 ``{batch_id, status, output_file_url}``。轮询直到 ``status`` 为 + ``completed``（此时 ``output_file_url`` 可用）或 ``failed``。 + """ + return self.http.get(f"v1/search/batches/{batch_id}") + + @staticmethod + def build_input_jsonl(search_requests: list[dict]) -> str: + """把 search request dict 列表拼成 .jsonl 文本（每行一个 ``v1/search`` body）。""" + import json as _json + + return "\n".join(_json.dumps(r, ensure_ascii=False) for r in search_requests) + + @staticmethod + def upload_input(presigned_url: str, jsonl_text: str) -> int: + """PUT .jsonl 到 ``create_job`` 返回的 presigned_url（S3，非 Bigdata API）。 + + ⚠️ **Content-Type 必须匹配 presigned 签名**：URL query 的 ``content-type`` + 参数（实测后端签的是 ``application/jsonl``）正是 S3 计算签名用的值，PUT + 必须带完全相同的 Content-Type，否则 ``403 SignatureDoesNotMatch``。这里从 + URL query 解析出来用上，不写死（后端若换 type 也跟得上）。contract-tested + 2026-05-31。 + ⚠️ 走裸 ``requests``（presigned 是 S3 直连签名 URL，不经 Bigdata 认证层）； + ``requests`` 读 ``HTTPS_PROXY`` 走代理，代理对 S3 大 host 偶发 ``503 Tunnel``， + 故内置瞬时重试（``rc()`` 的 marker 大小写匹配不到 ``ProxyError``，单独处理）。 + """ + import time + import urllib.parse + + import requests + + qs = urllib.parse.parse_qs(urllib.parse.urlparse(presigned_url).query) + content_type = qs.get("content-type", ["application/jsonl"])[0] + last_exc: Optional[Exception] = None + for _ in range(5): + try: + resp = requests.put( + presigned_url, + data=jsonl_text.encode("utf-8"), + headers={"Content-Type": content_type}, + timeout=120, + ) + resp.raise_for_status() + return resp.status_code + except requests.exceptions.ProxyError as exc: + last_exc = exc # 代理对 S3 偶发 503 Tunnel，退避重试 + time.sleep(2) + raise last_exc # type: ignore[misc] + + @staticmethod + def download_results(output_file_url: str) -> list[dict]: + """GET ``output_file_url``（status=completed 时）下载 .jsonl 结果，解析成 dict 列表。""" + import json as _json + + import requests + + resp = requests.get(output_file_url, timeout=120) + resp.raise_for_status() + return [_json.loads(line) for line in resp.text.splitlines() if line.strip()] diff --git a/bigdata-skill/scripts/bigdata_toolkit/retry.py b/bigdata-skill/scripts/bigdata_toolkit/retry.py new file mode 100644 index 00000000..183d5f2d --- /dev/null +++ b/bigdata-skill/scripts/bigdata_toolkit/retry.py @@ -0,0 +1,129 @@ +"""瞬时网络/SSL 错误重试穿透（无 IO 纯工具） +============================================== + +打海外 API（``api.bigdata.com``）时，**首发握手**常因网络抖动抛 +``SSLError: UNEXPECTED_EOF`` / ``Connection reset`` / ``RemoteDisconnected``—— +尤其经本地出站代理转发时。``bigdata-client`` 的 HTTP 层（直接依赖是 +``requests`` + ``aiohttp``）对 **SSL 握手阶段的 EOF** 不做重试，官方异常 +体系（见 sdk-reference/exceptions）也不建模这类握手错——所以一次抖动 +就直接冒泡成异常，让整个 backfill 中断。 + +``rc()`` 在 SDK/REST 调用外面再包一层：识别这些**瞬时**错误标记就退避重试， +其它错误（400/认证失败/schema 错）立即抛出不掩盖（NO FALLBACK——只重试 +确定瞬时的，不把真错误吞掉）。**限流（429）单独排除**：它该长退避或交给 +调用方降速，固定 ``delay``×N 硬重试只会加剧限流，故命中限流标记直接抛。 + +为什么 marker 用子串匹配 +------------------------ +这些异常跨 ``ssl`` / ``urllib3`` / ``requests`` / ``http.client`` 多层包装， +类型不统一但 ``str(e)`` 里稳定带这些词。子串匹配比 except 一堆具体异常类 +更鲁棒，也不会误吞业务错误（业务错误的文案里不含 'SSL'/'EOF' 这些词）。 + +用法 +---- +>>> from bigdata_toolkit import BigdataClient, EntityResolver, rc +>>> client = BigdataClient() # doctest: +SKIP +>>> er = EntityResolver(client) # doctest: +SKIP +>>> nvda = rc(lambda: er.resolve_id("NVIDIA", country="US")) # doctest: +SKIP + +循环里注意闭包陷阱（务必绑定循环变量）:: + + for kw, dr, lim in jobs: + # ✅ 绑定，否则所有 lambda 共享最后一次的 kw/dr/lim + docs = rc(lambda kw=kw, dr=dr, lim=lim: + searcher.search_entity(nvda, keyword=kw, chunk_limit=lim, date_range=dr)) +""" + +from __future__ import annotations + +import time +from typing import Callable, TypeVar + +__all__ = ["rc", "with_retry", "RETRYABLE_MARKERS"] + +T = TypeVar("T") + +#: ``str(exc)`` 命中任一即视为**瞬时**错误，可退避重试。 +#: 来源：实测打 api.bigdata.com 首发握手抖动的异常文案（SSL/EOF/连接重置/超时）。 +RETRYABLE_MARKERS = ( + "SSL", + "EOF", + "Connection", + "Max retries", + "timeout", + "RemoteDisconnected", +) + +#: 即使 ``str(exc)`` 里含上面的瞬时词，命中这些**限流/配额**标记也**不**重试—— +#: 429 该长退避或交调用方降速，固定 ``delay``×N 硬重试会加剧限流；配额耗尽重试无意义。 +NON_RETRYABLE_MARKERS = ( + "429", + "Too Many Requests", + "rate limit", + "ratelimit", + "quota", +) + + +def _is_retryable(exc: Exception) -> bool: + msg = str(exc) + # 限流/配额优先级高于瞬时：命中即不重试（避免硬重试加剧限流）。 + low = msg.lower() + if any(m in low for m in NON_RETRYABLE_MARKERS): + return False + return any(marker in msg for marker in RETRYABLE_MARKERS) + + +def rc(fn: Callable[[], T], *, tries: int = 8, delay: float = 2.0) -> T: + """跑 ``fn()``，遇到**瞬时**网络/SSL 错误就退避重试，其它错误立即抛。 + + Parameters + ---------- + fn: + 无参 thunk（用 ``lambda: ...`` 包住真正的调用；循环里记得绑定变量）。 + tries: + 最多尝试次数（含首次）。默认 8。 + delay: + 每次重试前 sleep 秒数（固定退避，够穿透首发抖动；不做指数退避避免 + 长尾等待）。默认 2.0。 + + Returns + ------- + ``fn()`` 的返回值。 + + Raises + ------ + 最后一次的原始异常（重试用尽），或任何**非瞬时**异常（立即抛，不掩盖）。 + """ + last_exc: Exception | None = None + for i in range(tries): + try: + return fn() + except Exception as exc: # noqa: BLE001 —— 故意宽捕获后按 marker 区分 + last_exc = exc + if i < tries - 1 and _is_retryable(exc): + time.sleep(delay) + continue + raise + # 理论不可达（循环里要么 return 要么 raise）；为类型完整性兜底。 + assert last_exc is not None + raise last_exc + + +def with_retry(*, tries: int = 8, delay: float = 2.0): + """装饰器版 :func:`rc`，把瞬时重试包到一个函数上。 + + >>> @with_retry(tries=5) + ... def pull(entity_id): # doctest: +SKIP + ... return rest.latest_surprise(entity_id) + """ + + def deco(func: Callable[..., T]) -> Callable[..., T]: + def wrapper(*args, **kwargs) -> T: + return rc(lambda: func(*args, **kwargs), tries=tries, delay=delay) + + wrapper.__name__ = getattr(func, "__name__", "wrapped") + wrapper.__doc__ = func.__doc__ + return wrapper + + return deco diff --git a/bigdata-skill/scripts/bigdata_toolkit/search.py b/bigdata-skill/scripts/bigdata_toolkit/search.py new file mode 100644 index 00000000..b5f7fcaa --- /dev/null +++ b/bigdata-skill/scripts/bigdata_toolkit/search.py @@ -0,0 +1,214 @@ +"""带标注的 chunk 抽取（SDK 高层路径） +===================================== + +封装 ``bd.search`` 的语义检索，把每个返回 chunk 的 **sentiment + 实体 +span + 定位** 拍平成普通 dict，方便下游消费。 + +走 SDK 高层（``bd.search.new(...).run(...)``），不是 REST 逃生舱。 + +⚠️ 中文/A股注意 +---------------- +实测：中文新闻实体检测 ≈0，CJK chunk 的 sentiment 是 doc-level 继承值 +（chunk sentiment == doc sentiment），且 ``language`` 字段会把含中文的 +filing 误标成 English。**这是数据源层硬伤，不是 SDK 封装问题**—— +A 股标的请先用英文官方名 / ISIN 解析成 rp_entity_id（见 kg.py），再做 +entity-scoped 检索；纯中文 keyword 检索基本 0 命中。结构化金融面 +（前瞻日历 / 一致预期 / surprise）走 rest_ext.py，对 A 股可用。 + +字段来源（运行时确认的 SDK model） +----------------------------------- +- ``Document``: id, headline, sentiment, document_scope, source, timestamp, + chunks, language, cluster, reporting_period, document_type, + reporting_entities, url + （注意 ``reporting_period`` 字段存在但 SDK 反序列化时不填，永远 None — + 要拿真值走 rest_ext.fetch_reporting_period） +- ``DocumentChunk``: text, chunk, entities, sentences, relevance, sentiment, + section_metadata, speaker +- ``DocumentSentenceEntity``: key（rp_entity_id）, start, end（字符 span 位置）, + query_type + +成本铁律（详见 cost.py） +------------------------ +``Search.run(limit)`` 接受 ``int``（doc-limit）或 ``ChunkLimit(n)``。 +**doc-limit 不省钱**：run(1) 和 run(10) 成本几乎一样（~52 query_unit）， +因为后端按"每页返回的 chunk 数"计费。真正省钱的是 ``ChunkLimit(n)`` +（实测 ChunkLimit(10) 仅 1 query_unit，52x 差距）。所以本模块默认走 +ChunkLimit，强制成本意识。 +""" + +from __future__ import annotations + +from typing import Any, Optional, Union + +from bigdata_client.daterange import AbsoluteDateRange, RollingDateRange +from bigdata_client.query import Entity, Keyword +from bigdata_client.search import ChunkLimit +from bigdata_client.models.search import DocumentType, SortBy + +from .client import BigdataClient + +__all__ = [ + "AnnotatedSearcher", + "chunk_to_dict", + "document_to_dict", +] + + +def _entity_to_dict(ent: Any) -> dict: + """``DocumentSentenceEntity`` → dict（key + 字符 span + query_type）。""" + return { + "key": getattr(ent, "key", None), # rp_entity_id + "start": getattr(ent, "start", None), # 字符起始位置 + "end": getattr(ent, "end", None), # 字符结束位置 + "query_type": getattr(ent, "query_type", None), + } + + +def chunk_to_dict(chunk: Any) -> dict: + """``DocumentChunk`` → 拍平 dict，保留标注。 + + 每个 entity 的 ``(start, end)`` 是该 chunk ``text`` 内的字符 span，可用 + ``text[start:end]`` 取出被标注的实体表面词。 + """ + entities = [_entity_to_dict(e) for e in (getattr(chunk, "entities", None) or [])] + return { + "chunk_index": getattr(chunk, "chunk", None), + "text": getattr(chunk, "text", None), + "sentiment": getattr(chunk, "sentiment", None), + "relevance": getattr(chunk, "relevance", None), + "speaker": getattr(chunk, "speaker", None), + "section_metadata": getattr(chunk, "section_metadata", None), + "entities": entities, + } + + +def document_to_dict(doc: Any, *, with_chunks: bool = True) -> dict: + """``Document`` → 拍平 dict。 + + ``source`` 是 ``DocumentSource``（key/name/rank），这里展开成可读字段。 + ``reporting_period`` 大概率是 None（SDK 解析 bug，见模块 docstring）。 + """ + source = getattr(doc, "source", None) + out = { + "id": getattr(doc, "id", None), + "headline": getattr(doc, "headline", None), + "sentiment": getattr(doc, "sentiment", None), + "document_scope": getattr(doc, "document_scope", None), + "document_type": getattr(doc, "document_type", None), + "timestamp": getattr(doc, "timestamp", None), + "language": getattr(doc, "language", None), + "url": getattr(doc, "url", None), + "reporting_period": getattr(doc, "reporting_period", None), # 多半 None + "reporting_entities": getattr(doc, "reporting_entities", None), + "source_key": getattr(source, "key", None) if source else None, + "source_name": getattr(source, "name", None) if source else None, + "source_rank": getattr(source, "rank", None) if source else None, + } + if with_chunks: + out["chunks"] = [chunk_to_dict(c) for c in (getattr(doc, "chunks", None) or [])] + return out + + +class AnnotatedSearcher: + """语义检索 + 标注抽取（SDK 高层）。 + + Parameters + ---------- + client: + :class:`~bigdata_toolkit.client.BigdataClient` 实例。 + """ + + def __init__(self, client: BigdataClient) -> None: + self.client = client + + # ------------------------------------------------------------------ # + # 查询构造辅助 # + # ------------------------------------------------------------------ # + @staticmethod + def entity_query(rp_entity_id: str, keyword: Optional[str] = None): + """构造 "实体（+ 可选关键词）" 查询。 + + entity-scoped 检索是 A 股唯一可用路径（纯 keyword 中文检索 ≈0）。 + rp_entity_id 由 kg.py 的实体解析得到。 + """ + ent = Entity(rp_entity_id) + if keyword: + # 用 `&` 运算符组合（SDK 重载的 __and__）；不要用 All(a, b)—— + # All 只接受单个 iterable，传两个位置参数会 TypeError。 + return ent & Keyword(keyword) + return ent + + # ------------------------------------------------------------------ # + # 检索执行 # + # ------------------------------------------------------------------ # + def search( + self, + query, + *, + chunk_limit: int = 10, + date_range: Optional[Union[AbsoluteDateRange, RollingDateRange]] = None, + scope: DocumentType = DocumentType.ALL, + sortby: SortBy = SortBy.RELEVANCE, + rerank_threshold: Optional[float] = None, + as_dict: bool = True, + ): + """跑一次检索，返回 Document 列表（默认拍平成 dict）。 + + Parameters + ---------- + query: + ``bigdata_client.query`` 的 QueryComponent（用 ``entity_query`` + 或自己拼 ``Entity`` / ``Keyword`` / ``All`` / ``Any``）。 + chunk_limit: + **chunk 上限**（成本承重参数）。内部包成 ``ChunkLimit(n)``， + 即 n 个 chunk = n/10 query_unit。默认 10（≈1 qu）。 + **绝不**直接传整数 doc-limit（会 52x 超支，见模块 docstring）。 + date_range: + ``AbsoluteDateRange(start, end)`` 或 ``RollingDateRange.*``。 + 窗口越窄越省钱（同 limit 下 1 天窗 vs 周窗 ~2.6x 差距）。 + scope: + ``DocumentType.ALL / NEWS / FILINGS / TRANSCRIPTS`` 等。 + as_dict: + True 返回拍平 dict（含标注）；False 返回原始 Document 对象。 + + Returns + ------- + list[dict] | list[Document] + """ + search = self.client.bd.search.new( + query=query, + date_range=date_range, + scope=scope, + sortby=sortby, + rerank_threshold=rerank_threshold, + ) + # 关键：用 ChunkLimit 而非裸 int，强制 chunk 计费而非整页计费 + docs = search.run(ChunkLimit(chunk_limit)) + + if as_dict: + return [document_to_dict(d) for d in docs] + return docs + + def search_entity( + self, + rp_entity_id: str, + *, + keyword: Optional[str] = None, + chunk_limit: int = 10, + **kwargs, + ): + """便捷方法：按 rp_entity_id（+ 可选关键词）检索。""" + query = self.entity_query(rp_entity_id, keyword) + return self.search(query, chunk_limit=chunk_limit, **kwargs) + + # ------------------------------------------------------------------ # + # 标注字典下载（SDK 封装方法，按 id 拉完整标注） # + # ------------------------------------------------------------------ # + def download_annotated_dict(self, search_id: str) -> dict: + """对已保存的 search 拉完整标注字典。 + + 走 SDK 封装方法 ``bd._api.download_annotated_dict(id_)``（不是 raw + http）。返回完整的 chunk-level 标注。适合先 save 一个 search 再批量 + 回拉标注的场景。 + """ + return self.client.conn.download_annotated_dict(search_id) diff --git a/bigdata-skill/scripts/probe_example.py b/bigdata-skill/scripts/probe_example.py new file mode 100644 index 00000000..f6a77bb9 --- /dev/null +++ b/bigdata-skill/scripts/probe_example.py @@ -0,0 +1,142 @@ +"""bigdata_toolkit 可跑示例 +============================ + +演示五大能力，全部小样本（成本意识），并用 CostTracker 量化每段消耗。 + +运行 +---- +:: + + export BIGDATA_API_KEY=bd_v2_xxx # 你的 Bigdata API key + export HTTPS_PROXY=http://127.0.0.1:8080 # 仅在需要出站代理时 + # 用装好 bigdata-client 的 Python 环境跑（见 SKILL.md 装包步骤）： + python scripts/probe_example.py # 加 --with-search 额外测 chunk 检索 + +设计原则 +-------- +- 实体解析 / events / estimates / quota 这些 endpoint **不按 chunk 计费**， + 近乎零成本，所以默认演示它们。 +- search（query-chunks）**按 chunk 计费**，示例用 ``chunk_limit=10``（≈1 qu）， + 并用 ``--with-search`` 显式开启，避免误烧配额。 +""" + +from __future__ import annotations + +import argparse +import json +import sys + +from bigdata_toolkit import ( + AnnotatedSearcher, + BigdataClient, + CostModel, + CostTracker, + EntityResolver, + StructuredDataREST, + rc, +) + + +def _show(title: str, obj, max_chars: int = 600) -> None: + print(f"\n{'='*60}\n{title}\n{'='*60}") + try: + s = json.dumps(obj, ensure_ascii=False, default=str) + except TypeError: + s = str(obj) + print(s[:max_chars] + (" ..." if len(s) > max_chars else "")) + + +def main() -> int: + ap = argparse.ArgumentParser(description="bigdata_toolkit probe example") + ap.add_argument( + "--with-search", + action="store_true", + help="额外跑一次 search（按 chunk 计费，~1 query_unit）", + ) + args = ap.parse_args() + + # ---- 0. 统一客户端（key 从 env 读，绝不硬编码） ---- + client = BigdataClient() # 缺 BIGDATA_API_KEY 会 fail-fast + tracker = CostTracker(client) + resolver = EntityResolver(client) + rest = StructuredDataREST(client) + + quota0 = rc(lambda: tracker.quota()) + _show("[0] 起始配额（chunk 级，1 qu = 10 chunks）", quota0) + + # ---- 1. 实体解析（SDK KG）：美股英文名 + A 股 ISIN crosswalk ---- + aapl_id = rc(lambda: resolver.resolve_id("Apple")) + print(f"\n[1a] Apple -> rp_entity_id = {aapl_id}") + + # A 股：中文名直查会 0 命中，演示用 ISIN crosswalk（茅台） + moutai = rc(lambda: resolver.resolve_by_isin(["CNE0000018R8"])) + _show("[1b] 贵州茅台 ISIN(CNE0000018R8) crosswalk", moutai) + moutai_id = moutai[0].get("id") if moutai and moutai[0] else None + + # ---- 2. SDK 缺失的前瞻财报日历（REST 逃生舱） ---- + if aapl_id: + cal = rc(lambda: rest.events_calendar( + aapl_id, + categories=["earnings-call"], + start_date="2026-06-01", + end_date="2026-12-31", + limit=3, + )) + # 只看顶层结构 + 第一条，避免刷屏 + top_keys = list(cal.keys()) if isinstance(cal, dict) else type(cal).__name__ + _show("[2] 前瞻财报日历 events-calendar（REST）顶层 keys", top_keys) + + # ---- 3. SDK 缺失的前瞻一致预期（REST 逃生舱） ---- + if aapl_id: + try: + est = rc(lambda: rest.analyst_estimates(aapl_id, period="quarter", limit=3)) + top = list(est.keys()) if isinstance(est, dict) else type(est).__name__ + _show("[3] 前瞻一致预期 analyst-estimates（REST）顶层 keys", top) + except Exception as e: # endpoint 半文档化，schema 可能漂移 + print(f"\n[3] analyst-estimates 调用异常（半文档化 endpoint）: " + f"{type(e).__name__}: {str(e)[:160]}") + + # ---- 4. A 股结构化数据可用性验证（茅台 surprise） ---- + if moutai_id: + try: + surp = rc(lambda: rest.latest_surprise(moutai_id)) + top = list(surp.keys()) if isinstance(surp, dict) else type(surp).__name__ + _show("[4] 茅台 latest-surprise（REST，验证 A 股结构面可用）顶层 keys", top) + except Exception as e: + print(f"\n[4] 茅台 surprise 异常: {type(e).__name__}: {str(e)[:160]}") + + # ---- 5. 成本外推模型（纯计算，演示冷启动预算否决判断） ---- + model = CostModel(chunk_limit_per_query=500, tier="fast") + est_poc = model.estimate(n_entities=20, n_windows=1) + est_full = model.estimate(n_entities=100, n_windows=12) # 100 标的 × 3 年季度 + _show("[5a] 冷启动成本外推 · PoC（20 标的单快照）", est_poc) + _show("[5b] 冷启动成本外推 · 全量（100 标的 × 3 年季度）", est_full) + if est_full["pct_of_trial_quota"] > 100: + print(f" ⚠️ 全量 backfill 需 {est_full['pct_of_trial_quota']}% trial 配额 " + f"→ trial 做不了，需要更大的付费配额") + + # ---- 6.（可选）带标注 chunk 抽取（按 chunk 计费，显式开启） ---- + if args.with_search and aapl_id: + rc(lambda: tracker.snapshot()) + searcher = AnnotatedSearcher(client) + docs = rc(lambda: searcher.search_entity(aapl_id, keyword="revenue", chunk_limit=10)) + n_chunks = sum(len(d.get("chunks", [])) for d in docs) + print(f"\n[6] search 返回 {len(docs)} docs / {n_chunks} chunks") + if docs and docs[0].get("chunks"): + ch = docs[0]["chunks"][0] + text = ch.get("text") or "" + print(f" 首 chunk sentiment={ch.get('sentiment')} " + f"entities={len(ch.get('entities') or [])} text[:80]={text[:80]!r}") + _show("[6] search 实际消耗 delta", rc(lambda: tracker.delta())) + else: + print("\n[6] search 已跳过（加 --with-search 开启，按 chunk 计费）") + + quota1 = rc(lambda: tracker.quota()) + print(f"\n[*] 结束配额 used_chunks={quota1['used_chunks']} " + f"(起始 {quota0['used_chunks']}, 本次净增 " + f"{quota1['used_chunks'] - quota0['used_chunks']} chunks)") + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/bilibili-source/.security-scan-passed b/bilibili-source/.security-scan-passed new file mode 100644 index 00000000..cd0641f2 --- /dev/null +++ b/bilibili-source/.security-scan-passed @@ -0,0 +1,4 @@ +Security scan passed +Scanned at: 2026-06-08T00:39:32.168530 +Tool: gitleaks + pattern-based validation +Content hash: e8f66e65cb05e73f87f2bf57af3c9bc2c81ba2c560698e35c199f99d5786cb54 diff --git a/bilibili-source/SKILL.md b/bilibili-source/SKILL.md new file mode 100644 index 00000000..dbe9aa4f --- /dev/null +++ b/bilibili-source/SKILL.md @@ -0,0 +1,92 @@ +--- +name: bilibili-source +description: Fetch comprehensive, login-free data for any Bilibili (B站) video — title, UP name and follower count, publish date, partition, tags, per-part cids, live stats (view, like, coin, favorite, share, reply, danmaku), and full danmaku (bullet-comment) text. Use this skill whenever working with a Bilibili video and needing real, citable numbers or metadata — ingesting a Bilibili source into a knowledge base, analyzing why a video performed, verifying a creator's claimed metrics, building a case study, or any time a Bilibili view/like/favorite count is about to be written into a document — fetch it, never hand-type or estimate it. Accepts BVID, av numbers, b23.tv short links, or full URLs. Subtitles are also covered but require the user's Bilibili login. +--- + +# bilibili-source + +Fetch **real, verifiable** data for a Bilibili video so you can cite it instead of guessing. Engagement numbers are the backbone of any honest "why did this do well" analysis, and hand-typed or estimated numbers are the fastest way a knowledge base rots. This skill makes the numbers cheap to fetch — so there is no excuse to invent them. + +## Quick start + +```bash +scripts/bili-fetch.sh BV1xxxxxxxxx +``` + +Returns one JSON object with everything from a single `view/detail` API call: + +```json +{ + "bvid": "BV1xxxxxxxxx", + "aid": 1234567890, + "fetched_at": "2026-06-07T13:54:17Z", + "url": "https://www.bilibili.com/video/BV1xxxxxxxxx", + "title": "