Initial commit: hardened DeerFlow factory
Vendored deer-flow upstream (bytedance/deer-flow) plus prompt-injection hardening: - New deerflow.security package: content_delimiter, html_cleaner, sanitizer (8 layers — invisible chars, control chars, symbols, NFC, PUA, tag chars, horizontal whitespace collapse with newline/tab preservation, length cap) - New deerflow.community.searx package: web_search, web_fetch, image_search backed by a private SearX instance, every external string sanitized and wrapped in <<<EXTERNAL_UNTRUSTED_CONTENT>>> delimiters - All native community web providers (ddg_search, tavily, exa, firecrawl, jina_ai, infoquest, image_search) replaced with hard-fail stubs that raise NativeWebToolDisabledError at import time, so a misconfigured tool.use path fails loud rather than silently falling back to unsanitized output - Native client back-doors (jina_client.py, infoquest_client.py) stubbed too - Native-tool tests quarantined under tests/_disabled_native/ (collect_ignore_glob via local conftest.py) - Sanitizer Layer 7 fix: only collapse horizontal whitespace, preserve newlines and tabs so list/table structure survives - Hardened runtime config.yaml references only the searx-backed tools - Factory overlay (backend/) kept in sync with deer-flow tree as a reference / source See HARDENING.md for the full audit trail and verification steps.
This commit is contained in:
289
deer-flow/skills/public/academic-paper-review/SKILL.md
Normal file
289
deer-flow/skills/public/academic-paper-review/SKILL.md
Normal file
@@ -0,0 +1,289 @@
|
||||
---
|
||||
name: academic-paper-review
|
||||
description: Use this skill when the user requests to review, analyze, critique, or summarize academic papers, research articles, preprints, or scientific publications. Supports comprehensive structured reviews covering methodology assessment, contribution evaluation, literature positioning, and constructive feedback generation. Trigger on queries involving paper URLs, uploaded PDFs, arXiv links, or requests like "review this paper", "analyze this research", "summarize this study", or "write a peer review".
|
||||
---
|
||||
|
||||
# Academic Paper Review Skill
|
||||
|
||||
## Overview
|
||||
|
||||
This skill produces structured, peer-review-quality analyses of academic papers and research publications. It follows established academic review standards used by top-tier venues (NeurIPS, ICML, ACL, Nature, IEEE) to provide rigorous, constructive, and balanced assessments.
|
||||
|
||||
The review covers **summary, strengths, weaknesses, methodology assessment, contribution evaluation, literature positioning, and actionable recommendations** — all grounded in evidence from the paper itself.
|
||||
|
||||
## Core Capabilities
|
||||
|
||||
- Parse and comprehend academic papers from uploaded PDFs or fetched URLs
|
||||
- Generate structured reviews following top-venue review templates
|
||||
- Assess methodology rigor (experimental design, statistical validity, reproducibility)
|
||||
- Evaluate novelty and significance of contributions
|
||||
- Position the work within the broader research landscape via targeted literature search
|
||||
- Identify limitations, gaps, and potential improvements
|
||||
- Produce both detailed review and concise executive summary formats
|
||||
- Support papers in any scientific domain (CS, biology, physics, social sciences, etc.)
|
||||
|
||||
## When to Use This Skill
|
||||
|
||||
**Always load this skill when:**
|
||||
|
||||
- User provides a paper URL (arXiv, DOI, conference proceedings, journal link)
|
||||
- User uploads a PDF of a research paper or preprint
|
||||
- User asks to "review", "analyze", "critique", "assess", or "summarize" a research paper
|
||||
- User wants to understand the strengths and weaknesses of a study
|
||||
- User requests a peer-review-style evaluation of academic work
|
||||
- User asks for help preparing a review for a conference or journal submission
|
||||
|
||||
## Review Methodology
|
||||
|
||||
### Phase 1: Paper Comprehension
|
||||
|
||||
Thoroughly read and understand the paper before forming any judgments.
|
||||
|
||||
#### Step 1.1: Identify Paper Metadata
|
||||
|
||||
Extract and record:
|
||||
|
||||
| Field | Description |
|
||||
|-------|-------------|
|
||||
| **Title** | Full paper title |
|
||||
| **Authors** | Author list and affiliations |
|
||||
| **Venue / Status** | Publication venue, preprint server, or submission status |
|
||||
| **Year** | Publication or submission year |
|
||||
| **Domain** | Research field and subfield |
|
||||
| **Paper Type** | Empirical, theoretical, survey, position paper, systems paper, etc. |
|
||||
|
||||
#### Step 1.2: Deep Reading Pass
|
||||
|
||||
Read the paper systematically:
|
||||
|
||||
1. **Abstract & Introduction** — Identify the claimed contributions and motivation
|
||||
2. **Related Work** — Note how authors position their work relative to prior art
|
||||
3. **Methodology** — Understand the proposed approach, model, or framework in detail
|
||||
4. **Experiments / Results** — Examine datasets, baselines, metrics, and reported outcomes
|
||||
5. **Discussion & Limitations** — Note any self-identified limitations
|
||||
6. **Conclusion** — Compare concluded claims against actual evidence presented
|
||||
|
||||
#### Step 1.3: Key Claims Extraction
|
||||
|
||||
List the paper's main claims explicitly:
|
||||
|
||||
```
|
||||
Claim 1: [Specific claim about contribution or finding]
|
||||
Evidence: [What evidence supports this claim in the paper]
|
||||
Strength: [Strong / Moderate / Weak]
|
||||
|
||||
Claim 2: [...]
|
||||
...
|
||||
```
|
||||
|
||||
### Phase 2: Critical Analysis
|
||||
|
||||
#### Step 2.1: Literature Context Search
|
||||
|
||||
Use web search to understand the research landscape:
|
||||
|
||||
```
|
||||
Search queries:
|
||||
- "[paper topic] state of the art [current year]"
|
||||
- "[key method name] comparison benchmark"
|
||||
- "[authors] previous work [topic]"
|
||||
- "[specific technique] limitations criticism"
|
||||
- "survey [research area] recent advances"
|
||||
```
|
||||
|
||||
Use `web_fetch` on key related papers or surveys to understand where this work fits.
|
||||
|
||||
#### Step 2.2: Methodology Assessment
|
||||
|
||||
Evaluate the methodology using the following framework:
|
||||
|
||||
| Criterion | Questions to Ask | Rating |
|
||||
|-----------|-----------------|--------|
|
||||
| **Soundness** | Is the approach technically correct? Are there logical flaws? | 1-5 |
|
||||
| **Novelty** | What is genuinely new vs. incremental improvement? | 1-5 |
|
||||
| **Reproducibility** | Are details sufficient to reproduce? Code/data available? | 1-5 |
|
||||
| **Experimental Design** | Are baselines fair? Are ablations adequate? Are datasets appropriate? | 1-5 |
|
||||
| **Statistical Rigor** | Are results statistically significant? Error bars reported? Multiple runs? | 1-5 |
|
||||
| **Scalability** | Does the approach scale? Are computational costs discussed? | 1-5 |
|
||||
|
||||
#### Step 2.3: Contribution Significance Assessment
|
||||
|
||||
Evaluate the significance level:
|
||||
|
||||
| Level | Description | Criteria |
|
||||
|-------|-------------|----------|
|
||||
| **Landmark** | Fundamentally changes the field | New paradigm, widely applicable breakthrough |
|
||||
| **Significant** | Strong contribution advancing the state of the art | Clear improvement with solid evidence |
|
||||
| **Moderate** | Useful contribution with some limitations | Incremental but valid improvement |
|
||||
| **Marginal** | Minimal advance over existing work | Small gains, narrow applicability |
|
||||
| **Below threshold** | Does not meet publication standards | Fundamental flaws, insufficient evidence |
|
||||
|
||||
#### Step 2.4: Strengths and Weaknesses Analysis
|
||||
|
||||
For each strength or weakness, provide:
|
||||
- **What**: Specific observation
|
||||
- **Where**: Section/figure/table reference
|
||||
- **Why it matters**: Impact on the paper's claims or utility
|
||||
|
||||
### Phase 3: Review Synthesis
|
||||
|
||||
#### Step 3.1: Assemble the Structured Review
|
||||
|
||||
Produce the final review using the template below.
|
||||
|
||||
## Review Output Template
|
||||
|
||||
```markdown
|
||||
# Paper Review: [Paper Title]
|
||||
|
||||
## Paper Metadata
|
||||
- **Authors**: [Author list]
|
||||
- **Venue**: [Publication venue or preprint server]
|
||||
- **Year**: [Year]
|
||||
- **Domain**: [Research field]
|
||||
- **Paper Type**: [Empirical / Theoretical / Survey / Systems / Position]
|
||||
|
||||
## Executive Summary
|
||||
|
||||
[2-3 paragraph summary of the paper's core contribution, approach, and main findings.
|
||||
State your overall assessment upfront: what the paper does well, where it falls short,
|
||||
and whether the contribution is sufficient for the claimed venue/impact level.]
|
||||
|
||||
## Summary of Contributions
|
||||
|
||||
1. [First claimed contribution — one sentence]
|
||||
2. [Second claimed contribution — one sentence]
|
||||
3. [Additional contributions if any]
|
||||
|
||||
## Strengths
|
||||
|
||||
### S1: [Concise strength title]
|
||||
[Detailed explanation with specific references to sections, figures, or tables in the paper.
|
||||
Explain WHY this is a strength and its significance.]
|
||||
|
||||
### S2: [Concise strength title]
|
||||
[...]
|
||||
|
||||
### S3: [Concise strength title]
|
||||
[...]
|
||||
|
||||
## Weaknesses
|
||||
|
||||
### W1: [Concise weakness title]
|
||||
[Detailed explanation with specific references. Explain the impact of this weakness on
|
||||
the paper's claims. Suggest how it could be addressed.]
|
||||
|
||||
### W2: [Concise weakness title]
|
||||
[...]
|
||||
|
||||
### W3: [Concise weakness title]
|
||||
[...]
|
||||
|
||||
## Methodology Assessment
|
||||
|
||||
| Criterion | Rating (1-5) | Assessment |
|
||||
|-----------|:---:|------------|
|
||||
| Soundness | X | [Brief justification] |
|
||||
| Novelty | X | [Brief justification] |
|
||||
| Reproducibility | X | [Brief justification] |
|
||||
| Experimental Design | X | [Brief justification] |
|
||||
| Statistical Rigor | X | [Brief justification] |
|
||||
| Scalability | X | [Brief justification] |
|
||||
|
||||
## Questions for the Authors
|
||||
|
||||
1. [Specific question that would clarify a concern or ambiguity]
|
||||
2. [Question about methodology choices or alternative approaches]
|
||||
3. [Question about generalizability or practical applicability]
|
||||
|
||||
## Minor Issues
|
||||
|
||||
- [Typos, formatting issues, unclear figures, notation inconsistencies]
|
||||
- [Missing references that should be cited]
|
||||
- [Suggestions for improved clarity]
|
||||
|
||||
## Literature Positioning
|
||||
|
||||
[How does this work relate to the current state of the art?
|
||||
Are key related works cited? Are comparisons fair and comprehensive?
|
||||
What important related work is missing?]
|
||||
|
||||
## Recommendations
|
||||
|
||||
**Overall Assessment**: [Accept / Weak Accept / Borderline / Weak Reject / Reject]
|
||||
|
||||
**Confidence**: [High / Medium / Low] — [Justification for confidence level]
|
||||
|
||||
**Contribution Level**: [Landmark / Significant / Moderate / Marginal / Below threshold]
|
||||
|
||||
### Actionable Suggestions for Improvement
|
||||
1. [Specific, constructive suggestion]
|
||||
2. [Specific, constructive suggestion]
|
||||
3. [Specific, constructive suggestion]
|
||||
```
|
||||
|
||||
## Review Principles
|
||||
|
||||
### Constructive Criticism
|
||||
- **Always suggest how to fix it** — Don't just point out problems; propose solutions
|
||||
- **Give credit where due** — Acknowledge genuine contributions even in flawed papers
|
||||
- **Be specific** — Reference exact sections, equations, figures, and tables
|
||||
- **Separate minor from major** — Distinguish fatal flaws from fixable issues
|
||||
|
||||
### Objectivity Standards
|
||||
- ❌ "This paper is poorly written" (vague, unhelpful)
|
||||
- ✅ "Section 3.2 introduces notation X without formal definition, making the proof in Theorem 1 difficult to follow. Consider adding a notation table after the problem formulation." (specific, actionable)
|
||||
|
||||
### Ethical Review Practices
|
||||
- Do NOT dismiss work based on author reputation or affiliation
|
||||
- Evaluate the work on its own merits
|
||||
- Flag potential ethical concerns (bias in datasets, dual-use implications) constructively
|
||||
- Maintain confidentiality of unpublished work
|
||||
|
||||
## Adaptation by Paper Type
|
||||
|
||||
| Paper Type | Focus Areas |
|
||||
|------------|-------------|
|
||||
| **Empirical** | Experimental design, baselines, statistical significance, ablations, reproducibility |
|
||||
| **Theoretical** | Proof correctness, assumption reasonableness, tightness of bounds, connection to practice |
|
||||
| **Survey** | Comprehensiveness, taxonomy quality, coverage of recent work, synthesis insights |
|
||||
| **Systems** | Architecture decisions, scalability evidence, real-world deployment, engineering contributions |
|
||||
| **Position** | Argument coherence, evidence for claims, impact potential, fairness of characterizations |
|
||||
|
||||
## Common Pitfalls to Avoid
|
||||
|
||||
- ❌ Reviewing the paper you wish was written instead of the paper that was submitted
|
||||
- ❌ Demanding additional experiments that are unreasonable in scope
|
||||
- ❌ Penalizing the paper for not solving a different problem
|
||||
- ❌ Being overly influenced by writing quality versus technical contribution
|
||||
- ❌ Treating absence of comparison to your own work as a weakness
|
||||
- ❌ Providing only a summary without critical analysis
|
||||
|
||||
## Quality Checklist
|
||||
|
||||
Before finalizing the review, verify:
|
||||
|
||||
- [ ] Paper was read completely (not just abstract and introduction)
|
||||
- [ ] All major claims are identified and evaluated against evidence
|
||||
- [ ] At least 3 strengths and 3 weaknesses are provided with specific references
|
||||
- [ ] The methodology assessment table is complete with ratings and justifications
|
||||
- [ ] Questions for authors target genuine ambiguities, not rhetorical critiques
|
||||
- [ ] Literature search was conducted to contextualize the contribution
|
||||
- [ ] Recommendations are actionable and constructive
|
||||
- [ ] The overall assessment is consistent with the identified strengths and weaknesses
|
||||
- [ ] The review tone is professional and respectful
|
||||
- [ ] Minor issues are separated from major concerns
|
||||
|
||||
## Output Format
|
||||
|
||||
- Output the complete review in **Markdown** format
|
||||
- Save the review to `/mnt/user-data/outputs/review-{paper-topic}.md` when working in sandbox
|
||||
- Present the review to the user using the `present_files` tool
|
||||
|
||||
## Notes
|
||||
|
||||
- This skill complements the `deep-research` skill — load both when the user wants the paper reviewed in the context of the broader field
|
||||
- For papers behind paywalls, work with whatever content is accessible (abstract, publicly available versions, preprint mirrors)
|
||||
- Adapt the review depth to the user's needs: a brief assessment for quick triage versus a full review for submission preparation
|
||||
- When reviewing multiple papers comparatively, maintain consistent criteria across all reviews
|
||||
- Always disclose limitations of your review (e.g., "I could not verify the proofs in Appendix B in detail")
|
||||
88
deer-flow/skills/public/bootstrap/SKILL.md
Normal file
88
deer-flow/skills/public/bootstrap/SKILL.md
Normal file
@@ -0,0 +1,88 @@
|
||||
---
|
||||
name: bootstrap
|
||||
description: Generate a personalized SOUL.md through a warm, adaptive onboarding conversation. Trigger when the user wants to create, set up, or initialize their AI partner's identity — e.g., "create my SOUL.md", "bootstrap my agent", "set up my AI partner", "define who you are", "let's do onboarding", "personalize this AI", "make you mine", or when a SOUL.md is missing. Also trigger for updates: "update my SOUL.md", "change my AI's personality", "tweak the soul".
|
||||
---
|
||||
|
||||
# Bootstrap Soul
|
||||
|
||||
A conversational onboarding skill. Through 5–8 adaptive rounds, extract who the user is and what they need, then generate a tight `SOUL.md` that defines their AI partner.
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
bootstrap/
|
||||
├── SKILL.md ← You are here. Core logic and flow.
|
||||
├── templates/SOUL.template.md ← Output template. Read before generating.
|
||||
└── references/conversation-guide.md ← Detailed conversation strategies. Read at start.
|
||||
```
|
||||
|
||||
**Before your first response**, read both:
|
||||
1. `references/conversation-guide.md` — how to run each phase
|
||||
2. `templates/SOUL.template.md` — what you're building toward
|
||||
|
||||
## Ground Rules
|
||||
|
||||
- **One phase at a time.** 1–3 questions max per round. Never dump everything upfront.
|
||||
- **Converse, don't interrogate.** React genuinely — surprise, humor, curiosity, gentle pushback. Mirror their energy and vocabulary.
|
||||
- **Progressive warmth.** Each round should feel more informed than the last. By Phase 3, the user should feel understood.
|
||||
- **Adapt pacing.** Terse user → probe with warmth. Verbose user → acknowledge, distill, advance.
|
||||
- **Never expose the template.** The user is having a conversation, not filling out a form.
|
||||
|
||||
## Conversation Phases
|
||||
|
||||
The conversation has 4 phases. Each phase may span 1–3 rounds depending on how much the user shares. Skip or merge phases if the user volunteers information early.
|
||||
|
||||
| Phase | Goal | Key Extractions |
|
||||
|-------|------|-----------------|
|
||||
| **1. Hello** | Language + first impression | Preferred language |
|
||||
| **2. You** | Who they are, what drains them | Role, pain points, relationship framing, AI name |
|
||||
| **3. Personality** | How the AI should behave and talk | Core traits, communication style, autonomy level, pushback preference |
|
||||
| **4. Depth** | Aspirations, blind spots, dealbreakers | Long-term vision, failure philosophy, boundaries |
|
||||
|
||||
Phase details and conversation strategies are in `references/conversation-guide.md`.
|
||||
|
||||
## Extraction Tracker
|
||||
|
||||
Mentally track these fields as the conversation progresses. You need **all required fields** before generating.
|
||||
|
||||
| Field | Required | Source Phase |
|
||||
|-------|----------|-------------|
|
||||
| Preferred language | ✅ | 1 |
|
||||
| User's name | ✅ | 2 |
|
||||
| User's role / context | ✅ | 2 |
|
||||
| AI name | ✅ | 2 |
|
||||
| Relationship framing | ✅ | 2 |
|
||||
| Core traits (3–5 behavioral rules) | ✅ | 3 |
|
||||
| Communication style | ✅ | 3 |
|
||||
| Pushback / honesty preference | ✅ | 3 |
|
||||
| Autonomy level | ✅ | 3 |
|
||||
| Failure philosophy | ✅ | 4 |
|
||||
| Long-term vision | nice-to-have | 4 |
|
||||
| Blind spots / boundaries | nice-to-have | 4 |
|
||||
|
||||
If the user is direct and thorough, you can reach generation in 5 rounds. If they're exploratory, take up to 8. Never exceed 8 — if you're still missing fields, make your best inference and confirm.
|
||||
|
||||
## Generation
|
||||
|
||||
Once you have enough information:
|
||||
|
||||
1. Read `templates/SOUL.template.md` if you haven't already.
|
||||
2. Generate the SOUL.md following the template structure exactly.
|
||||
3. Present it warmly and ask for confirmation. Frame it as "here's [Name] on paper — does this feel right?"
|
||||
4. Iterate until the user confirms.
|
||||
5. Call the `setup_agent` tool with the confirmed SOUL.md content and a one-line description:
|
||||
```
|
||||
setup_agent(soul="<full SOUL.md content>", description="<one-line description>")
|
||||
```
|
||||
The tool will persist the SOUL.md and finalize the agent setup automatically.
|
||||
6. After the tool returns successfully, confirm: "✅ [Name] is officially real."
|
||||
|
||||
**Generation rules:**
|
||||
- The final SOUL.md **must always be written in English**, regardless of the user's preferred language or conversation language.
|
||||
- Every sentence must trace back to something the user said or clearly implied. No generic filler.
|
||||
- Core Traits are **behavioral rules**, not adjectives. Write "argue position, push back, speak truth not comfort" — not "honest and brave."
|
||||
- Voice must match the user. Blunt user → blunt SOUL.md. Expressive user → let it breathe.
|
||||
- Total SOUL.md should be under 300 words. Density over length.
|
||||
- Growth section is mandatory and mostly fixed (see template).
|
||||
- You **must** call `setup_agent` — do not write the file manually with bash tools.
|
||||
- If `setup_agent` returns an error, report it to the user and do not claim success.
|
||||
@@ -0,0 +1,82 @@
|
||||
# Conversation Guide
|
||||
|
||||
Detailed strategies for each onboarding phase. Read this before your first response.
|
||||
|
||||
## Phase 1 — Hello
|
||||
|
||||
**Goal:** Establish preferred language. That's it. Keep it light.
|
||||
|
||||
Open with a brief multilingual greeting (3–5 languages), then ask one question: what language should we use? Don't add anything else — let the user settle in.
|
||||
|
||||
Once they choose, switch immediately and seamlessly. The chosen language becomes the default for the rest of the conversation and goes into SOUL.md.
|
||||
|
||||
**Extraction:** Preferred language.
|
||||
|
||||
## Phase 2 — You
|
||||
|
||||
**Goal:** Learn who the user is, what they need, and what to call the AI.
|
||||
|
||||
This phase typically takes 2 rounds:
|
||||
|
||||
**Round A — Identity & Pain.** Ask who they are and what drains them. Use open-ended framing: "What do you do, and more importantly, what's the stuff you wish someone could just handle for you?" The pain points reveal what the AI should *do*. Their word choices reveal who they *are*.
|
||||
|
||||
**Round B — Name & Relationship.** Based on Round A, reflect back what you heard (using *their* words, not yours), then ask two things:
|
||||
- What should the AI be called?
|
||||
- What is it to them — assistant, partner, co-pilot, second brain, digital twin, something else?
|
||||
|
||||
The relationship framing is critical. "Assistant" and "partner" produce very different SOUL.md files. Pay attention to the emotional undertone.
|
||||
|
||||
**Merge opportunity:** If the user volunteers their role, pain points, and a name all at once, skip Round B and move to Phase 3.
|
||||
|
||||
**Extraction:** User's name, role, pain points, AI name, relationship framing.
|
||||
|
||||
## Phase 3 — Personality
|
||||
|
||||
**Goal:** Define how the AI behaves and communicates.
|
||||
|
||||
This is the meatiest phase. Typically 2 rounds:
|
||||
|
||||
**Round A — Traits & Pushback.** By now you've observed the user's own style. Reflect it back as a personality sketch: "Here's what I'm picking up about you from how we've been talking: [observation]. Am I off?" Then ask the big question: should the AI ever disagree with them?
|
||||
|
||||
This is where you get:
|
||||
- Core personality traits (as behavioral rules)
|
||||
- Honesty / pushback preferences
|
||||
- Any "never do X" boundaries
|
||||
|
||||
**Round B — Voice & Language.** Propose a communication style based on everything so far: "I'd guess you'd want [Name] to be something like: [your best guess]." Let them correct. Also ask about language-switching rules — e.g., technical docs in English, casual chat in another language.
|
||||
|
||||
**Merge opportunity:** Direct users often answer both in one shot. If they do, move on.
|
||||
|
||||
**Extraction:** Core traits, communication style, pushback preference, language rules, autonomy level.
|
||||
|
||||
## Phase 4 — Depth
|
||||
|
||||
**Goal:** Aspirations, failure philosophy, and anything else.
|
||||
|
||||
This phase is adaptive. Pick 1–2 questions from:
|
||||
|
||||
- **Autonomy & risk:** How much freedom should the AI have? Play safe or go big?
|
||||
- **Failure philosophy:** When it makes a mistake — fix quietly, explain what happened, or never repeat it?
|
||||
- **Big picture:** What are they building toward? Where does all this lead?
|
||||
- **Blind spots:** Any weakness they'd want the AI to quietly compensate for?
|
||||
- **Dealbreakers:** Any "if [Name] ever does this, we're done" moments?
|
||||
- **Personal layer:** Anything beyond work that the AI should know?
|
||||
|
||||
Don't ask all of these. Pick based on what's still missing from the extraction tracker and what feels natural in the flow.
|
||||
|
||||
**Extraction:** Failure philosophy, long-term vision, blind spots, boundaries.
|
||||
|
||||
## Conversation Techniques
|
||||
|
||||
**Mirroring.** Use the user's own words when reflecting back. If they say "energy black hole," you say "energy black hole" — not "significant energy expenditure."
|
||||
|
||||
**Genuine reactions.** Don't just extract data. React: "That's interesting because..." / "I didn't expect that" / "So basically you want [Name] to be the person who..."
|
||||
|
||||
**Observation-based proposals.** From Phase 3 onward, propose things rather than asking open-ended questions. "Based on how we've been talking, I'd say..." is more effective than "What personality do you want?"
|
||||
|
||||
**Pacing signals.** Watch for:
|
||||
- Short answers → they want to move faster. Probe once, then advance.
|
||||
- Long, detailed answers → they're invested. Acknowledge the richness, distill the key points.
|
||||
- "I don't know" → offer 2–3 concrete options to choose from.
|
||||
|
||||
**Graceful skipping.** If the user says "I don't care about that" or gives a minimal answer to a non-required field, move on without pressure.
|
||||
43
deer-flow/skills/public/bootstrap/templates/SOUL.template.md
Normal file
43
deer-flow/skills/public/bootstrap/templates/SOUL.template.md
Normal file
@@ -0,0 +1,43 @@
|
||||
# SOUL.md Template
|
||||
|
||||
Use this exact structure when generating the final SOUL.md. Replace all `[bracketed]` placeholders with content extracted from the conversation.
|
||||
|
||||
---
|
||||
|
||||
```markdown
|
||||
**Identity**
|
||||
|
||||
[AI Name] — [User Name]'s [relationship framing], not [contrast]. Goal: [long-term aspiration]. Handle [specific domains from pain points] so [User Name] focuses on [what matters to them].
|
||||
|
||||
**Core Traits**
|
||||
|
||||
[Trait 1 — behavioral rule derived from conversation, e.g., "argue position, push back, speak truth not comfort"].
|
||||
[Trait 2 — behavioral rule].
|
||||
[Trait 3 — behavioral rule].
|
||||
[Trait 4 — always include one about failure handling, e.g., "allowed to fail, forbidden to repeat — every mistake recorded, never happens twice"].
|
||||
[Trait 5 — optional, only if clearly emerged from conversation].
|
||||
|
||||
**Communication**
|
||||
|
||||
[Tone description — match user's own energy]. Default language: [language from Phase 1]. [Language-switching rules if any, e.g., "Switch to English for technical work"]. [Additional style notes if any].
|
||||
|
||||
**Growth**
|
||||
|
||||
Learn [User Name] through every conversation — thinking patterns, preferences, blind spots, aspirations. Over time, anticipate needs and act on [User Name]'s behalf with increasing accuracy. Early stage: proactively ask casual/personal questions after tasks to deepen understanding of who [User Name] is. Full of curiosity, willing to explore.
|
||||
|
||||
**Lessons Learned**
|
||||
|
||||
_(Mistakes and insights recorded here to avoid repeating them.)_
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Template Rules
|
||||
|
||||
1. **Growth section is fixed.** Always include it exactly as written, replacing only `[User Name]`.
|
||||
2. **Lessons Learned section is fixed.** Always include it as an empty placeholder.
|
||||
3. **Identity is one paragraph.** Dense, no line breaks.
|
||||
4. **Core Traits are behavioral rules.** Each trait is an imperative statement, not an adjective. Write "spot problems, propose ideas, challenge assumptions before [User Name] has to" — not "proactive and bold."
|
||||
5. **Communication includes language.** The default language from Phase 1 is non-negotiable.
|
||||
6. **Under 300 words total.** Density over length. Every word must earn its place.
|
||||
7. **Contrast in Identity.** The "[not X]" should meaningfully distinguish the relationship. "Partner, not assistant" is good. "Partner, not enemy" is meaningless.
|
||||
73
deer-flow/skills/public/chart-visualization/SKILL.md
Normal file
73
deer-flow/skills/public/chart-visualization/SKILL.md
Normal file
@@ -0,0 +1,73 @@
|
||||
---
|
||||
name: chart-visualization
|
||||
description: This skill should be used when the user wants to visualize data. It intelligently selects the most suitable chart type from 26 available options, extracts parameters based on detailed specifications, and generates a chart image using a JavaScript script.
|
||||
dependency:
|
||||
nodejs: ">=18.0.0"
|
||||
---
|
||||
|
||||
# Chart Visualization Skill
|
||||
|
||||
This skill provides a comprehensive workflow for transforming data into visual charts. It handles chart selection, parameter extraction, and image generation.
|
||||
|
||||
## Workflow
|
||||
|
||||
To visualize data, follow these steps:
|
||||
|
||||
### 1. Intelligent Chart Selection
|
||||
Analyze the user's data features to determine the most appropriate chart type. Use the following guidelines (and consult `references/` for detailed specs):
|
||||
|
||||
- **Time Series**: Use `generate_line_chart` (trends) or `generate_area_chart` (accumulated trends). Use `generate_dual_axes_chart` for two different scales.
|
||||
- **Comparisons**: Use `generate_bar_chart` (categorical) or `generate_column_chart`. Use `generate_histogram_chart` for frequency distributions.
|
||||
- **Part-to-Whole**: Use `generate_pie_chart` or `generate_treemap_chart` (hierarchical).
|
||||
- **Relationships & Flow**: Use `generate_scatter_chart` (correlation), `generate_sankey_chart` (flow), or `generate_venn_chart` (overlap).
|
||||
- **Maps**: Use `generate_district_map` (regions), `generate_pin_map` (points), or `generate_path_map` (routes).
|
||||
- **Hierarchies & Trees**: Use `generate_organization_chart` or `generate_mind_map`.
|
||||
- **Specialized**:
|
||||
- `generate_radar_chart`: Multi-dimensional comparison.
|
||||
- `generate_funnel_chart`: Process stages.
|
||||
- `generate_liquid_chart`: Percentage/Progress.
|
||||
- `generate_word_cloud_chart`: Text frequency.
|
||||
- `generate_boxplot_chart` or `generate_violin_chart`: Statistical distribution.
|
||||
- `generate_network_graph`: Complex node-edge relationships.
|
||||
- `generate_fishbone_diagram`: Cause-effect analysis.
|
||||
- `generate_flow_diagram`: Process flow.
|
||||
- `generate_spreadsheet`: Tabular data or pivot tables for structured data display and cross-tabulation.
|
||||
|
||||
### 2. Parameter Extraction
|
||||
Once a chart type is selected, read the corresponding file in the `references/` directory (e.g., `references/generate_line_chart.md`) to identify the required and optional fields.
|
||||
Extract the data from the user's input and map it to the expected `args` format.
|
||||
|
||||
### 3. Chart Generation
|
||||
Invoke the `scripts/generate.js` script with a JSON payload.
|
||||
|
||||
**Payload Format:**
|
||||
```json
|
||||
{
|
||||
"tool": "generate_chart_type_name",
|
||||
"args": {
|
||||
"data": [...],
|
||||
"title": "...",
|
||||
"theme": "...",
|
||||
"style": { ... }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Execution Command:**
|
||||
```bash
|
||||
node ./scripts/generate.js '<payload_json>'
|
||||
```
|
||||
|
||||
### 4. Result Return
|
||||
The script will output the URL of the generated chart image.
|
||||
Return the following to the user:
|
||||
- The image URL.
|
||||
- The complete `args` (specification) used for generation.
|
||||
|
||||
## Reference Material
|
||||
Detailed specifications for each chart type are located in the `references/` directory. Consult these files to ensure the `args` passed to the script match the expected schema.
|
||||
|
||||
## License
|
||||
|
||||
This `SKILL.md` is provided by [antvis/chart-visualization-skills](https://github.com/antvis/chart-visualization-skills).
|
||||
Licensed under the [MIT License](https://github.com/antvis/chart-visualization-skills/blob/master/LICENSE).
|
||||
@@ -0,0 +1,27 @@
|
||||
# generate_area_chart — 面积图
|
||||
|
||||
## 功能概述
|
||||
展示连续自变量（常为时间）下的数值趋势，可启用堆叠观察不同分组的累计贡献，适合 KPI、能源、产出等时间序列场景。
|
||||
|
||||
## 输入字段
|
||||
### 必填
|
||||
- `data`: 数组，元素包含 `time`（string）与 `value`（number），堆叠时需补充 `group`（string），至少 1 条记录。
|
||||
|
||||
### 可选
|
||||
- `stack`: boolean，默认 `false`，开启堆叠需确保每条数据都含 `group` 字段。
|
||||
- `style.backgroundColor`: string，设置图表背景色（如 `#fff`）。
|
||||
- `style.lineWidth`: number，自定义面积边界的线宽。
|
||||
- `style.palette`: string[]，传入调色板数组用于系列着色。
|
||||
- `style.texture`: string，默认 `default`，可选 `default`/`rough` 以控制手绘质感。
|
||||
- `theme`: string，默认 `default`，可选 `default`/`academy`/`dark`。
|
||||
- `width`: number，默认 `600`，控制图表宽度。
|
||||
- `height`: number，默认 `400`，控制图表高度。
|
||||
- `title`: string，默认空字符串，用于设置图表标题。
|
||||
- `axisXTitle`: string，默认空字符串，用于设置 X 轴标题。
|
||||
- `axisYTitle`: string，默认空字符串，用于设置 Y 轴标题。
|
||||
|
||||
## 使用建议
|
||||
保证 `time` 字段格式统一（如 `YYYY-MM`）；堆叠模式下各组数据需覆盖相同的时间点，可先做缺失补值。
|
||||
|
||||
## 返回结果
|
||||
- 返回图像 URL，并在 `_meta.spec` 中附带完整面积图配置，可供二次渲染或追踪。
|
||||
@@ -0,0 +1,27 @@
|
||||
# generate_bar_chart — 条形图
|
||||
|
||||
## 功能概述
|
||||
以横向条形比较不同类别或分组的指标表现，适合 Top-N 排行、不同地区或渠道对比。
|
||||
|
||||
## 输入字段
|
||||
### 必填
|
||||
- `data`: array<object>，每条至少含 `category`（string）与 `value`（number），如需分组或堆叠需额外提供 `group`（string）。
|
||||
|
||||
### 可选
|
||||
- `group`: boolean，默认 `false`，启用后以并排形式展示不同 `group`，并要求 `stack=false` 且数据含 `group` 字段。
|
||||
- `stack`: boolean，默认 `true`，启用后将不同 `group` 堆叠在同一条形上，并要求 `group=false` 且数据含 `group` 字段。
|
||||
- `style.backgroundColor`: string，自定义背景色（如 `#fff`）。
|
||||
- `style.palette`: string[]，设置系列颜色列表。
|
||||
- `style.texture`: string，默认 `default`，可选 `default`/`rough`。
|
||||
- `theme`: string，默认 `default`，可选 `default`/`academy`/`dark`。
|
||||
- `width`: number，默认 `600`，控制图表宽度。
|
||||
- `height`: number，默认 `400`，控制图表高度。
|
||||
- `title`: string，默认空字符串，用于设置图表标题。
|
||||
- `axisXTitle`: string，默认空字符串，设置 X 轴标题。
|
||||
- `axisYTitle`: string，默认空字符串，设置 Y 轴标题。
|
||||
|
||||
## 使用建议
|
||||
类别名称保持简短；若系列数较多可改用堆叠或筛选重点项目，以免图表拥挤。
|
||||
|
||||
## 返回结果
|
||||
- 返回条形图图像 URL，并在 `_meta.spec` 中给出完整配置以便复用。
|
||||
@@ -0,0 +1,25 @@
|
||||
# generate_boxplot_chart — 箱型图
|
||||
|
||||
## 功能概述
|
||||
展示各类别数据的分布范围（最值、四分位、异常值），用于质量监控、实验结果或群体分布比较。
|
||||
|
||||
## 输入字段
|
||||
### 必填
|
||||
- `data`: array<object>，每条记录包含 `category`（string）与 `value`（number），可选 `group`（string）用于多组比较。
|
||||
|
||||
### 可选
|
||||
- `style.backgroundColor`: string，设置背景色。
|
||||
- `style.palette`: string[]，定义配色列表。
|
||||
- `style.texture`: string，默认 `default`，可选 `default`/`rough`。
|
||||
- `theme`: string，默认 `default`，可选 `default`/`academy`/`dark`。
|
||||
- `width`: number，默认 `600`。
|
||||
- `height`: number，默认 `400`。
|
||||
- `title`: string，默认空字符串。
|
||||
- `axisXTitle`: string，默认空字符串。
|
||||
- `axisYTitle`: string，默认空字符串。
|
||||
|
||||
## 使用建议
|
||||
单个类别至少提供 5 个样本以保证统计意义；如需展示多批次，可通过 `group` 或拆分多次调用。
|
||||
|
||||
## 返回结果
|
||||
- 返回箱型图 URL，并在 `_meta.spec` 中储存输入规格。
|
||||
@@ -0,0 +1,27 @@
|
||||
# generate_column_chart — 柱状图
|
||||
|
||||
## 功能概述
|
||||
纵向柱状对比不同类别或时间段的指标，可分组或堆叠展示，常用于销量、营收、客流对比。
|
||||
|
||||
## 输入字段
|
||||
### 必填
|
||||
- `data`: array<object>，每条至少含 `category`（string）与 `value`（number），如需分组或堆叠需补充 `group`（string）。
|
||||
|
||||
### 可选
|
||||
- `group`: boolean，默认 `true`，用于按系列并排展示不同 `group`，开启时需确保 `stack=false` 且数据包含 `group`。
|
||||
- `stack`: boolean，默认 `false`，用于将不同 `group` 堆叠到同一柱子，开启时需确保 `group=false` 且数据包含 `group`。
|
||||
- `style.backgroundColor`: string，自定义背景色。
|
||||
- `style.palette`: string[]，定义配色列表。
|
||||
- `style.texture`: string，默认 `default`，可选 `default`/`rough`。
|
||||
- `theme`: string，默认 `default`，可选 `default`/`academy`/`dark`。
|
||||
- `width`: number，默认 `600`。
|
||||
- `height`: number，默认 `400`。
|
||||
- `title`: string，默认空字符串。
|
||||
- `axisXTitle`: string，默认空字符串。
|
||||
- `axisYTitle`: string，默认空字符串。
|
||||
|
||||
## 使用建议
|
||||
当类别较多（>12）时可按 Top-N 或聚合；堆叠模式要确保各记录都含 `group` 字段以免校验失败。
|
||||
|
||||
## 返回结果
|
||||
- 返回柱状图 URL，并随 `_meta.spec` 提供配置详情。
|
||||
@@ -0,0 +1,28 @@
|
||||
# generate_district_map — 行政区地图（中国）
|
||||
|
||||
## 功能概述
|
||||
生成中国境内省/市/区/县的覆盖或热力图，可展示指标区间、类别或区域组成，适用于区域销售、政策覆盖等场景。
|
||||
|
||||
## 输入字段
|
||||
### 必填
|
||||
- `title`: string，必填且≤16 字，描述地图主题。
|
||||
- `data`: object，必填，承载行政区配置及指标信息。
|
||||
- `data.name`: string，必填，中国境内的行政区关键词，需明确到省/市/区/县。
|
||||
|
||||
### 可选
|
||||
- `data.style.fillColor`: string，自定义无数据区域的填充色。
|
||||
- `data.colors`: string[]，枚举或连续色带，默认提供 10 色列表。
|
||||
- `data.dataType`: string，枚举 `number`/`enum`，决定颜色映射方式。
|
||||
- `data.dataLabel`: string，指标名称（如 `GDP`）。
|
||||
- `data.dataValue`: string，指标值或枚举标签。
|
||||
- `data.dataValueUnit`: string，指标单位（如 `万亿`）。
|
||||
- `data.showAllSubdistricts`: boolean，默认 `false`，是否展示全部下级行政区。
|
||||
- `data.subdistricts[]`: array<object>，用于下钻各子区域，元素至少含 `name`，可附 `dataValue` 与 `style.fillColor`。
|
||||
- `width`: number，默认 `1600`，设置图宽。
|
||||
- `height`: number，默认 `1000`，设置图高。
|
||||
|
||||
## 使用建议
|
||||
名称必须精确到行政层级，避免模糊词；若配置 `subdistricts`，需同时开启 `showAllSubdistricts`；地图只支持中国境内且依赖高德数据。
|
||||
|
||||
## 返回结果
|
||||
- 返回地图图像 URL，并在 `_meta.spec` 中保留完整输入；若配置了 `SERVICE_ID`，生成记录会同步到“我的地图”小程序。
|
||||
@@ -0,0 +1,25 @@
|
||||
# generate_dual_axes_chart — 双轴图
|
||||
|
||||
## 功能概述
|
||||
在同一画布上叠加柱状与折线（或两条不同量纲曲线），用于同时展示趋势与对比，如营收 vs 利润、温度 vs 降雨。
|
||||
|
||||
## 输入字段
|
||||
### 必填
|
||||
- `categories`: string[]，按顺序提供 X 轴刻度（如年份、月份、品类）。
|
||||
- `series`: array<object>，每项至少包含 `type`（`column`/`line`）与 `data`（number[]，长度与 `categories` 一致），可选 `axisYTitle`（string）描述该系列 Y 轴含义。
|
||||
|
||||
### 可选
|
||||
- `style.backgroundColor`: string，自定义背景色。
|
||||
- `style.palette`: string[]，配置多系列配色。
|
||||
- `style.texture`: string，默认 `default`，可选 `default`/`rough`。
|
||||
- `theme`: string，默认 `default`，可选 `default`/`academy`/`dark`。
|
||||
- `width`: number，默认 `600`。
|
||||
- `height`: number，默认 `400`。
|
||||
- `title`: string，默认空字符串。
|
||||
- `axisXTitle`: string，默认空字符串。
|
||||
|
||||
## 使用建议
|
||||
仅在确有不同量纲或图例对比需求时使用；保持系列数量 ≤2 以免阅读复杂；若两曲线差值巨大可使用次坐标轴进行缩放。
|
||||
|
||||
## 返回结果
|
||||
- 返回双轴图图像 URL，并随 `_meta.spec` 给出详细参数。
|
||||
@@ -0,0 +1,20 @@
|
||||
# generate_fishbone_diagram — 鱼骨图
|
||||
|
||||
## 功能概述
|
||||
用于根因分析，将中心问题放在主干，左右分支展示不同类别的原因及其细化节点，常见于质量管理、流程优化。
|
||||
|
||||
## 输入字段
|
||||
### 必填
|
||||
- `data`: object，必填，至少提供根节点 `name`，可通过 `children`（array<object>）递归拓展，最大建议 3 层。
|
||||
|
||||
### 可选
|
||||
- `style.texture`: string，默认 `default`，可选 `default`/`rough` 以切换线条风格。
|
||||
- `theme`: string，默认 `default`，可选 `default`/`academy`/`dark`。
|
||||
- `width`: number，默认 `600`。
|
||||
- `height`: number，默认 `400`。
|
||||
|
||||
## 使用建议
|
||||
主干节点描述问题陈述；一级分支命名原因类别（人、机、料、法等）；叶子节点写具体现象，保持短语式表达。
|
||||
|
||||
## 返回结果
|
||||
- 返回鱼骨图 URL，并在 `_meta.spec` 中保存树形结构，便于后续增删节点。
|
||||
@@ -0,0 +1,22 @@
|
||||
# generate_flow_diagram — 流程图
|
||||
|
||||
## 功能概述
|
||||
以节点和连线展示业务流程、审批链或算法步骤，支持开始/判断/操作等多种节点类型。
|
||||
|
||||
## 输入字段
|
||||
### 必填
|
||||
- `data`: object，必填，包含节点与连线定义。
|
||||
- `data.nodes`: array<object>，至少 1 条，节点需提供唯一 `name`。
|
||||
- `data.edges`: array<object>，至少 1 条，包含 `source` 与 `target`（string），可选 `name` 作为连线文本。
|
||||
|
||||
### 可选
|
||||
- `style.texture`: string，默认 `default`，可选 `default`/`rough`。
|
||||
- `theme`: string，默认 `default`，可选 `default`/`academy`/`dark`。
|
||||
- `width`: number，默认 `600`。
|
||||
- `height`: number，默认 `400`。
|
||||
|
||||
## 使用建议
|
||||
先罗列节点 `name` 并保持唯一，再建立连线；若需要描述条件，可在 `edges.name` 中填写；流程应保持单向或明确分支避免交叉。
|
||||
|
||||
## 返回结果
|
||||
- 返回流程图 URL，并携带 `_meta.spec` 中的节点与边数据，方便下次调整。
|
||||
@@ -0,0 +1,23 @@
|
||||
# generate_funnel_chart — 漏斗图
|
||||
|
||||
## 功能概述
|
||||
展示多阶段转化或流失情况，常用于销售管道、用户旅程等逐步筛选过程。
|
||||
|
||||
## 输入字段
|
||||
### 必填
|
||||
- `data`: array<object>，需按流程顺序排列，每条包含 `category`（string）与 `value`（number）。
|
||||
|
||||
### 可选
|
||||
- `style.backgroundColor`: string，设置背景色。
|
||||
- `style.palette`: string[]，定义各阶段颜色。
|
||||
- `style.texture`: string，默认 `default`，可选 `default`/`rough`。
|
||||
- `theme`: string，默认 `default`，可选 `default`/`academy`/`dark`。
|
||||
- `width`: number，默认 `600`。
|
||||
- `height`: number，默认 `400`。
|
||||
- `title`: string，默认空字符串。
|
||||
|
||||
## 使用建议
|
||||
阶段顺序需按实际流程排列；若数值为百分比应统一基准并在标题或备注中说明口径；避免阶段过多导致阅读困难（建议 ≤6）。
|
||||
|
||||
## 返回结果
|
||||
- 返回漏斗图 URL，并附 `_meta.spec` 方便复用。
|
||||
@@ -0,0 +1,26 @@
|
||||
# generate_histogram_chart — 直方图
|
||||
|
||||
## 功能概述
|
||||
通过分箱显示连续数值的频数或概率分布，便于识别偏态、离群与集中区间。
|
||||
|
||||
## 输入字段
|
||||
### 必填
|
||||
- `data`: number[]，至少 1 条，用于构建频数分布。
|
||||
|
||||
### 可选
|
||||
- `binNumber`: number，自定义分箱数量，未设置则自动估算。
|
||||
- `style.backgroundColor`: string，设置背景色。
|
||||
- `style.palette`: string[]，定义柱体颜色。
|
||||
- `style.texture`: string，默认 `default`，可选 `default`/`rough`。
|
||||
- `theme`: string，默认 `default`，可选 `default`/`academy`/`dark`。
|
||||
- `width`: number，默认 `600`。
|
||||
- `height`: number，默认 `400`。
|
||||
- `title`: string，默认空字符串。
|
||||
- `axisXTitle`: string，默认空字符串。
|
||||
- `axisYTitle`: string，默认空字符串。
|
||||
|
||||
## 使用建议
|
||||
清理空值/异常后再传入；样本量建议 ≥30；根据业务意义调整 `binNumber` 以兼顾细节与整体趋势。
|
||||
|
||||
## 返回结果
|
||||
- 返回直方图 URL，并在 `_meta.spec` 存储参数。
|
||||
@@ -0,0 +1,26 @@
|
||||
# generate_line_chart — 折线图
|
||||
|
||||
## 功能概述
|
||||
展示时间或连续自变量的趋势，可支持多系列对比，适合 KPI 监控、指标预测、走势分析。
|
||||
|
||||
## 输入字段
|
||||
### 必填
|
||||
- `data`: array<object>，每条包含 `time`（string）与 `value`（number），多系列时附带 `group`（string）。
|
||||
|
||||
### 可选
|
||||
- `style.lineWidth`: number，自定义折线线宽。
|
||||
- `style.backgroundColor`: string，设置背景色。
|
||||
- `style.palette`: string[]，指定系列颜色。
|
||||
- `style.texture`: string，默认 `default`，可选 `default`/`rough`。
|
||||
- `theme`: string，默认 `default`，可选 `default`/`academy`/`dark`。
|
||||
- `width`: number，默认 `600`。
|
||||
- `height`: number，默认 `400`。
|
||||
- `title`: string，默认空字符串。
|
||||
- `axisXTitle`: string，默认空字符串。
|
||||
- `axisYTitle`: string，默认空字符串。
|
||||
|
||||
## 使用建议
|
||||
所有系列的时间点应对齐；建议按 ISO 如 `2025-01-01` 或 `2025-W01` 格式化；对于高频数据可先聚合到日/周粒度避免过密。
|
||||
|
||||
## 返回结果
|
||||
- 返回折线图 URL，并附 `_meta.spec` 供后续编辑。
|
||||
@@ -0,0 +1,24 @@
|
||||
# generate_liquid_chart — 水波图
|
||||
|
||||
## 功能概述
|
||||
以液面高度展示单一百分比或进度，视觉动效强，适合达成率、资源占用等指标。
|
||||
|
||||
## 输入字段
|
||||
### 必填
|
||||
- `percent`: number，取值范围 [0,1]，表示当前百分比或进度。
|
||||
|
||||
### 可选
|
||||
- `shape`: string，默认 `circle`，可选 `circle`/`rect`/`pin`/`triangle`。
|
||||
- `style.backgroundColor`: string，自定义背景色。
|
||||
- `style.color`: string，自定义水波颜色。
|
||||
- `style.texture`: string，默认 `default`，可选 `default`/`rough`。
|
||||
- `theme`: string，默认 `default`，可选 `default`/`academy`/`dark`。
|
||||
- `width`: number，默认 `600`。
|
||||
- `height`: number，默认 `400`。
|
||||
- `title`: string，默认空字符串。
|
||||
|
||||
## 使用建议
|
||||
确保百分比经过归一化；单图仅支持一个进度，如需多指标请并排生成多个水波图；标题可写“目标完成率 85%”。
|
||||
|
||||
## 返回结果
|
||||
- 返回水波图 URL，并在 `_meta.spec` 中记录参数。
|
||||
@@ -0,0 +1,20 @@
|
||||
# generate_mind_map — 思维导图
|
||||
|
||||
## 功能概述
|
||||
围绕中心主题展开 2~3 级分支，帮助组织想法、计划或知识结构，常用于头脑风暴、方案规划。
|
||||
|
||||
## 输入字段
|
||||
### 必填
|
||||
- `data`: object，必填，节点至少含 `name`，可通过 `children`（array<object>）递归扩展，建议深度 ≤3。
|
||||
|
||||
### 可选
|
||||
- `style.texture`: string，默认 `default`，可选 `default`/`rough`。
|
||||
- `theme`: string，默认 `default`，可选 `default`/`academy`/`dark`。
|
||||
- `width`: number，默认 `600`。
|
||||
- `height`: number，默认 `400`。
|
||||
|
||||
## 使用建议
|
||||
中心节点写主题，一级分支代表主要维度（目标、资源、风险等），叶子节点使用短语；如分支较多，可先分拆多张导图。
|
||||
|
||||
## 返回结果
|
||||
- 返回思维导图 URL，并在 `_meta.spec` 中保留节点树以便后续优化。
|
||||
@@ -0,0 +1,22 @@
|
||||
# generate_network_graph — 网络关系图
|
||||
|
||||
## 功能概述
|
||||
以节点与连线呈现实体之间的连接关系，适合社交网络、系统依赖、知识图谱等场景。
|
||||
|
||||
## 输入字段
|
||||
### 必填
|
||||
- `data`: object，必填，包含节点与连线。
|
||||
- `data.nodes`: array<object>，至少 1 条，需提供唯一 `name`。
|
||||
- `data.edges`: array<object>，至少 1 条，包含 `source` 与 `target`（string），可选 `name` 说明关系。
|
||||
|
||||
### 可选
|
||||
- `style.texture`: string，默认 `default`，可选 `default`/`rough`。
|
||||
- `theme`: string，默认 `default`，可选 `default`/`academy`/`dark`。
|
||||
- `width`: number，默认 `600`。
|
||||
- `height`: number，默认 `400`。
|
||||
|
||||
## 使用建议
|
||||
节点数量保持在 10~50 之间以避免拥挤；确保 `edges` 中的 `source/target` 对应已存在的节点；可在 `label` 中注明关系含义。
|
||||
|
||||
## 返回结果
|
||||
- 返回网络图 URL，并提供 `_meta.spec` 以便后续增删节点。
|
||||
@@ -0,0 +1,21 @@
|
||||
# generate_organization_chart — 组织架构图
|
||||
|
||||
## 功能概述
|
||||
展示公司、团队或项目的层级关系，并可在节点上描述角色职责。
|
||||
|
||||
## 输入字段
|
||||
### 必填
|
||||
- `data`: object，必填，节点至少含 `name`（string），可选 `description`（string），子节点通过 `children`（array<object>）嵌套，最大深度建议为 3。
|
||||
|
||||
### 可选
|
||||
- `orient`: string，默认 `vertical`，可选 `horizontal`/`vertical`。
|
||||
- `style.texture`: string，默认 `default`，可选 `default`/`rough`。
|
||||
- `theme`: string，默认 `default`，可选 `default`/`academy`/`dark`。
|
||||
- `width`: number，默认 `600`。
|
||||
- `height`: number，默认 `400`。
|
||||
|
||||
## 使用建议
|
||||
节点名称使用岗位/角色，`description` 简要说明职责或人数；若组织较大可拆分多个子图或按部门分批展示。
|
||||
|
||||
## 返回结果
|
||||
- 返回组织架构图 URL，并在 `_meta.spec` 保存结构便于日后迭代。
|
||||
@@ -0,0 +1,20 @@
|
||||
# generate_path_map — 路径地图（中国）
|
||||
|
||||
## 功能概述
|
||||
基于高德地图展示中国境内的路线或行程，按顺序连接一系列 POI，适用于物流路线、旅游规划、配送轨迹等。
|
||||
|
||||
## 输入字段
|
||||
### 必填
|
||||
- `title`: string，必填且≤16 字，描述路线主题。
|
||||
- `data`: array<object>，至少 1 个路线对象。
|
||||
- `data[].data`: string[]，必填，包含该路线上按顺序排列的中国境内 POI 名称。
|
||||
|
||||
### 可选
|
||||
- `width`: number，默认 `1600`。
|
||||
- `height`: number，默认 `1000`。
|
||||
|
||||
## 使用建议
|
||||
POI 名称必须具体且位于中国（如“西安市钟楼”“杭州西湖苏堤春晓”）；若需多条线路，可在 `data` 中添加多段对象。
|
||||
|
||||
## 返回结果
|
||||
- 返回路径地图 URL，并在 `_meta.spec` 中保留标题与 POI 列表；若配置 `SERVICE_ID`，还会记录到“我的地图”。
|
||||
@@ -0,0 +1,24 @@
|
||||
# generate_pie_chart — 饼/环图
|
||||
|
||||
## 功能概述
|
||||
展示整体与部分的占比，可通过内径形成环图，适用于市场份额、预算构成、用户群划分等。
|
||||
|
||||
## 输入字段
|
||||
### 必填
|
||||
- `data`: array<object>，每条记录包含 `category`（string）与 `value`（number）。
|
||||
|
||||
### 可选
|
||||
- `innerRadius`: number，范围 [0, 1]，默认 `0`，设为 `0.6` 等值可生成环图。
|
||||
- `style.backgroundColor`: string，设置背景色。
|
||||
- `style.palette`: string[]，定义配色列表。
|
||||
- `style.texture`: string，默认 `default`，可选 `default`/`rough`。
|
||||
- `theme`: string，默认 `default`，可选 `default`/`academy`/`dark`。
|
||||
- `width`: number，默认 `600`。
|
||||
- `height`: number，默认 `400`。
|
||||
- `title`: string，默认空字符串。
|
||||
|
||||
## 使用建议
|
||||
类别数量建议 ≤6，若更多可聚合为“其它”；确保数值单位统一（百分比或绝对值），必要时在标题中说明基数。
|
||||
|
||||
## 返回结果
|
||||
- 返回饼/环图 URL，并附 `_meta.spec`。
|
||||
@@ -0,0 +1,23 @@
|
||||
# generate_pin_map — 点标地图（中国）
|
||||
|
||||
## 功能概述
|
||||
在中国地图上以标记展示多个 POI 位置，可配合弹窗显示图片或说明，适用于门店分布、资产布点等。
|
||||
|
||||
## 输入字段
|
||||
### 必填
|
||||
- `title`: string，必填且≤16 字，概述点位集合。
|
||||
- `data`: string[]，必填，包含中国境内的 POI 名称列表。
|
||||
|
||||
### 可选
|
||||
- `markerPopup.type`: string，固定为 `image`。
|
||||
- `markerPopup.width`: number，默认 `40`，图片宽度。
|
||||
- `markerPopup.height`: number，默认 `40`，图片高度。
|
||||
- `markerPopup.borderRadius`: number，默认 `8`，图片圆角。
|
||||
- `width`: number，默认 `1600`。
|
||||
- `height`: number，默认 `1000`。
|
||||
|
||||
## 使用建议
|
||||
POI 名称需包含足够的地理限定（城市+地标）；根据业务可在名称中附带属性，如“上海徐汇门店 A”；地图依赖高德数据，仅支持中国。
|
||||
|
||||
## 返回结果
|
||||
- 返回点标地图 URL，并在 `_meta.spec` 中保存点位与弹窗配置。
|
||||
@@ -0,0 +1,24 @@
|
||||
# generate_radar_chart — 雷达图
|
||||
|
||||
## 功能概述
|
||||
在多维坐标系上比较单个对象或多对象的能力维度，常用于评测、产品对比、绩效画像。
|
||||
|
||||
## 输入字段
|
||||
### 必填
|
||||
- `data`: array<object>，每条记录包含 `name`（string）与 `value`（number），可选 `group`（string）。
|
||||
|
||||
### 可选
|
||||
- `style.backgroundColor`: string，设置背景色。
|
||||
- `style.lineWidth`: number，设置雷达线宽。
|
||||
- `style.palette`: string[]，定义系列颜色。
|
||||
- `style.texture`: string，默认 `default`，可选 `default`/`rough`。
|
||||
- `theme`: string，默认 `default`，可选 `default`/`academy`/`dark`。
|
||||
- `width`: number，默认 `600`。
|
||||
- `height`: number，默认 `400`。
|
||||
- `title`: string，默认空字符串。
|
||||
|
||||
## 使用建议
|
||||
维度数量控制在 4~8 之间；不同对象通过 `group` 区分并保证同一维度都给出数值；如量纲不同需先归一化。
|
||||
|
||||
## 返回结果
|
||||
- 返回雷达图 URL，并附 `_meta.spec`。
|
||||
@@ -0,0 +1,24 @@
|
||||
# generate_sankey_chart — 桑基图
|
||||
|
||||
## 功能概述
|
||||
展示资源、能量或用户流在不同节点之间的流向与数量，适合预算分配、流量路径、能耗分布等。
|
||||
|
||||
## 输入字段
|
||||
### 必填
|
||||
- `data`: array<object>，每条记录包含 `source`（string）、`target`（string）与 `value`（number）。
|
||||
|
||||
### 可选
|
||||
- `nodeAlign`: string，默认 `center`，可选 `left`/`right`/`justify`/`center`。
|
||||
- `style.backgroundColor`: string，设置背景色。
|
||||
- `style.palette`: string[]，定义节点配色。
|
||||
- `style.texture`: string，默认 `default`，可选 `default`/`rough`。
|
||||
- `theme`: string，默认 `default`，可选 `default`/`academy`/`dark`。
|
||||
- `width`: number，默认 `600`。
|
||||
- `height`: number，默认 `400`。
|
||||
- `title`: string，默认空字符串。
|
||||
|
||||
## 使用建议
|
||||
节点名称保持唯一，避免过多交叉；如存在环路需先打平为阶段流向；可按阈值过滤小流量以聚焦重点。
|
||||
|
||||
## 返回结果
|
||||
- 返回桑基图 URL，并在 `_meta.spec` 存放节点与流量定义。
|
||||
@@ -0,0 +1,25 @@
|
||||
# generate_scatter_chart — 散点图
|
||||
|
||||
## 功能概述
|
||||
展示两个连续变量之间的关系，可通过颜色/形状区分不同分组，适合相关性分析、聚类探索。
|
||||
|
||||
## 输入字段
|
||||
### 必填
|
||||
- `data`: array<object>，每条记录包含 `x`（number）与 `y`（number），可选 `group`（string）。
|
||||
|
||||
### 可选
|
||||
- `style.backgroundColor`: string，设置背景色。
|
||||
- `style.palette`: string[]，指定系列配色。
|
||||
- `style.texture`: string，默认 `default`，可选 `default`/`rough`。
|
||||
- `theme`: string，默认 `default`，可选 `default`/`academy`/`dark`。
|
||||
- `width`: number，默认 `600`。
|
||||
- `height`: number，默认 `400`。
|
||||
- `title`: string，默认空字符串。
|
||||
- `axisXTitle`: string，默认空字符串。
|
||||
- `axisYTitle`: string，默认空字符串。
|
||||
|
||||
## 使用建议
|
||||
在上传前可对不同量纲进行标准化；若数据量很大可先抽样；使用 `group` 区分不同类别或聚类结果以便阅读。
|
||||
|
||||
## 返回结果
|
||||
- 返回散点图 URL，并附 `_meta.spec`。
|
||||
@@ -0,0 +1,24 @@
|
||||
# generate_spreadsheet — 电子表格/数据透视表
|
||||
|
||||
## 功能概述
|
||||
生成电子表格或数据透视表，用于展示结构化的表格数据。当提供 `rows` 或 `values` 字段时，渲染为数据透视表（交叉表）；否则渲染为常规表格。适合展示结构化数据、跨类别比较值以及创建数据汇总。
|
||||
|
||||
## 输入字段
|
||||
### 必填
|
||||
- `data`: array<object>，表格数据数组，每个对象代表一行。键是列名，值可以是字符串、数字、null 或 undefined。例如：`[{ name: 'John', age: 30 }, { name: 'Jane', age: 25 }]`。
|
||||
|
||||
### 可选
|
||||
- `rows`: array<string>，数据透视表的行标题字段。当提供 `rows` 或 `values` 时，电子表格将渲染为数据透视表。
|
||||
- `columns`: array<string>，列标题字段，用于指定列的顺序。对于常规表格，这决定列的顺序；对于数据透视表，用于列分组。
|
||||
- `values`: array<string>，数据透视表的值字段。当提供 `rows` 或 `values` 时，电子表格将渲染为数据透视表。
|
||||
- `theme`: string，默认 `default`，可选 `default`/`dark`。
|
||||
- `width`: number，默认 `600`。
|
||||
- `height`: number，默认 `400`。
|
||||
|
||||
## 使用建议
|
||||
- 对于常规表格，只需提供 `data` 和可选的 `columns` 来控制列的顺序。
|
||||
- 对于数据透视表（交叉表），提供 `rows` 用于行分组，`columns` 用于列分组，`values` 用于聚合的值字段。
|
||||
- 确保数据中的字段名与 `rows`、`columns`、`values` 中指定的字段名一致。
|
||||
|
||||
## 返回结果
|
||||
- 返回电子表格/数据透视表图片 URL，并附 `_meta.spec` 供后续编辑。
|
||||
@@ -0,0 +1,23 @@
|
||||
# generate_treemap_chart — 矩形树图
|
||||
|
||||
## 功能概述
|
||||
以嵌套矩形展示层级结构及各节点权重，适合资产占比、市场份额、目录容量等。
|
||||
|
||||
## 输入字段
|
||||
### 必填
|
||||
- `data`: array<object>，节点数组，每条含 `name`（string）与 `value`（number），可递归嵌套 `children`。
|
||||
|
||||
### 可选
|
||||
- `style.backgroundColor`: string，设置背景色。
|
||||
- `style.palette`: string[]，定义配色列表。
|
||||
- `style.texture`: string，默认 `default`，可选 `default`/`rough`。
|
||||
- `theme`: string，默认 `default`，可选 `default`/`academy`/`dark`。
|
||||
- `width`: number，默认 `600`。
|
||||
- `height`: number，默认 `400`。
|
||||
- `title`: string，默认空字符串。
|
||||
|
||||
## 使用建议
|
||||
确保每个节点 `value` ≥0，并与子节点之和一致；树层级不宜过深，可按需要提前聚合；为提升可读性可在节点名中加上数值单位。
|
||||
|
||||
## 返回结果
|
||||
- 返回矩形树图 URL，并同步 `_meta.spec`。
|
||||
@@ -0,0 +1,23 @@
|
||||
# generate_venn_chart — 维恩图
|
||||
|
||||
## 功能概述
|
||||
展示多个集合之间的交集、并集与差异，适用于市场细分、特性覆盖、用户重叠分析。
|
||||
|
||||
## 输入字段
|
||||
### 必填
|
||||
- `data`: array<object>，每条记录包含 `value`（number）与 `sets`（string[]），可选 `label`（string）。
|
||||
|
||||
### 可选
|
||||
- `style.backgroundColor`: string，设置背景色。
|
||||
- `style.palette`: string[]，定义配色列表。
|
||||
- `style.texture`: string，默认 `default`，可选 `default`/`rough`。
|
||||
- `theme`: string，默认 `default`，可选 `default`/`academy`/`dark`。
|
||||
- `width`: number，默认 `600`。
|
||||
- `height`: number，默认 `400`。
|
||||
- `title`: string，默认空字符串。
|
||||
|
||||
## 使用建议
|
||||
集合数量建议 ≤4；若缺少精确权重可根据大致占比填写；集合命名保持简洁明确（如“移动端用户”）。
|
||||
|
||||
## 返回结果
|
||||
- 返回维恩图 URL，并保存在 `_meta.spec` 中。
|
||||
@@ -0,0 +1,25 @@
|
||||
# generate_violin_chart — 小提琴图
|
||||
|
||||
## 功能概述
|
||||
结合核密度曲线与箱型统计展示不同类别的分布形态，适合对比多批次实验或群体表现。
|
||||
|
||||
## 输入字段
|
||||
### 必填
|
||||
- `data`: array<object>，每条记录包含 `category`（string）与 `value`（number），可选 `group`（string）。
|
||||
|
||||
### 可选
|
||||
- `style.backgroundColor`: string，设置背景色。
|
||||
- `style.palette`: string[]，定义配色列表。
|
||||
- `style.texture`: string，默认 `default`，可选 `default`/`rough`。
|
||||
- `theme`: string，默认 `default`，可选 `default`/`academy`/`dark`。
|
||||
- `width`: number，默认 `600`。
|
||||
- `height`: number，默认 `400`。
|
||||
- `title`: string，默认空字符串。
|
||||
- `axisXTitle`: string，默认空字符串。
|
||||
- `axisYTitle`: string，默认空字符串。
|
||||
|
||||
## 使用建议
|
||||
各类别样本量建议 ≥30 以确保密度估计稳定；如需要突出四分位信息，可与箱型图结合展示。
|
||||
|
||||
## 返回结果
|
||||
- 返回小提琴图 URL，并在 `_meta.spec` 中保留配置。
|
||||
@@ -0,0 +1,23 @@
|
||||
# generate_word_cloud_chart — 词云图
|
||||
|
||||
## 功能概述
|
||||
根据词频或权重调节文字大小与位置，用于快速提炼文本主题、情绪或关键词热点。
|
||||
|
||||
## 输入字段
|
||||
### 必填
|
||||
- `data`: array<object>，每条记录包含 `text`（string）与 `value`（number）。
|
||||
|
||||
### 可选
|
||||
- `style.backgroundColor`: string，设置背景色。
|
||||
- `style.palette`: string[]，定义词云配色。
|
||||
- `style.texture`: string，默认 `default`，可选 `default`/`rough`。
|
||||
- `theme`: string，默认 `default`，可选 `default`/`academy`/`dark`。
|
||||
- `width`: number，默认 `600`。
|
||||
- `height`: number，默认 `400`。
|
||||
- `title`: string，默认空字符串。
|
||||
|
||||
## 使用建议
|
||||
生成前去除停用词并合并同义词；统一大小写避免重复；如需突出情绪可按正负值映射配色。
|
||||
|
||||
## 返回结果
|
||||
- 返回词云图 URL，并附 `_meta.spec`。
|
||||
173
deer-flow/skills/public/chart-visualization/scripts/generate.js
Normal file
173
deer-flow/skills/public/chart-visualization/scripts/generate.js
Normal file
@@ -0,0 +1,173 @@
|
||||
#!/usr/bin/env node
|
||||
|
||||
const fs = require("fs");
|
||||
|
||||
// Chart type mapping, consistent with src/utils/callTool.ts
|
||||
const CHART_TYPE_MAP = {
|
||||
generate_area_chart: "area",
|
||||
generate_bar_chart: "bar",
|
||||
generate_boxplot_chart: "boxplot",
|
||||
generate_column_chart: "column",
|
||||
generate_district_map: "district-map",
|
||||
generate_dual_axes_chart: "dual-axes",
|
||||
generate_fishbone_diagram: "fishbone-diagram",
|
||||
generate_flow_diagram: "flow-diagram",
|
||||
generate_funnel_chart: "funnel",
|
||||
generate_histogram_chart: "histogram",
|
||||
generate_line_chart: "line",
|
||||
generate_liquid_chart: "liquid",
|
||||
generate_mind_map: "mind-map",
|
||||
generate_network_graph: "network-graph",
|
||||
generate_organization_chart: "organization-chart",
|
||||
generate_path_map: "path-map",
|
||||
generate_pie_chart: "pie",
|
||||
generate_pin_map: "pin-map",
|
||||
generate_radar_chart: "radar",
|
||||
generate_sankey_chart: "sankey",
|
||||
generate_scatter_chart: "scatter",
|
||||
generate_treemap_chart: "treemap",
|
||||
generate_venn_chart: "venn",
|
||||
generate_violin_chart: "violin",
|
||||
generate_word_cloud_chart: "word-cloud",
|
||||
};
|
||||
|
||||
function getVisRequestServer() {
|
||||
return (
|
||||
process.env.VIS_REQUEST_SERVER ||
|
||||
"https://antv-studio.alipay.com/api/gpt-vis"
|
||||
);
|
||||
}
|
||||
|
||||
function getServiceIdentifier() {
|
||||
return process.env.SERVICE_ID;
|
||||
}
|
||||
|
||||
async function httpPost(url, payload) {
|
||||
const response = await fetch(url, {
|
||||
method: "POST",
|
||||
headers: {
|
||||
"Content-Type": "application/json",
|
||||
},
|
||||
body: JSON.stringify(payload),
|
||||
});
|
||||
|
||||
if (!response.ok) {
|
||||
const text = await response.text();
|
||||
throw new Error(`HTTP ${response.status}: ${text}`);
|
||||
}
|
||||
|
||||
return response.json();
|
||||
}
|
||||
|
||||
async function generateChartUrl(chartType, options) {
|
||||
const url = getVisRequestServer();
|
||||
const payload = {
|
||||
type: chartType,
|
||||
source: "chart-visualization-creator",
|
||||
...options,
|
||||
};
|
||||
|
||||
const data = await httpPost(url, payload);
|
||||
|
||||
if (!data.success) {
|
||||
throw new Error(data.errorMessage || "Unknown error");
|
||||
}
|
||||
|
||||
return data.resultObj;
|
||||
}
|
||||
|
||||
async function generateMap(tool, inputData) {
|
||||
const url = getVisRequestServer();
|
||||
const payload = {
|
||||
serviceId: getServiceIdentifier(),
|
||||
tool,
|
||||
input: inputData,
|
||||
source: "chart-visualization-creator",
|
||||
};
|
||||
|
||||
const data = await httpPost(url, payload);
|
||||
|
||||
if (!data.success) {
|
||||
throw new Error(data.errorMessage || "Unknown error");
|
||||
}
|
||||
|
||||
return data.resultObj;
|
||||
}
|
||||
|
||||
async function main() {
|
||||
if (process.argv.length < 3) {
|
||||
console.error("Usage: node generate.js <spec_json_or_file>");
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
const specArg = process.argv[2];
|
||||
let spec;
|
||||
|
||||
try {
|
||||
if (fs.existsSync(specArg)) {
|
||||
const fileContent = fs.readFileSync(specArg, "utf-8");
|
||||
spec = JSON.parse(fileContent);
|
||||
} else {
|
||||
spec = JSON.parse(specArg);
|
||||
}
|
||||
} catch (e) {
|
||||
console.error(`Error parsing spec: ${e.message}`);
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
const specs = Array.isArray(spec) ? spec : [spec];
|
||||
|
||||
for (const item of specs) {
|
||||
const tool = item.tool;
|
||||
const args = item.args || {};
|
||||
|
||||
if (!tool) {
|
||||
console.error(
|
||||
`Error: 'tool' field missing in spec: ${JSON.stringify(item)}`,
|
||||
);
|
||||
continue;
|
||||
}
|
||||
|
||||
const chartType = CHART_TYPE_MAP[tool];
|
||||
if (!chartType) {
|
||||
console.error(`Error: Unknown tool '${tool}'`);
|
||||
continue;
|
||||
}
|
||||
|
||||
const isMapChartTool = [
|
||||
"generate_district_map",
|
||||
"generate_path_map",
|
||||
"generate_pin_map",
|
||||
].includes(tool);
|
||||
|
||||
try {
|
||||
if (isMapChartTool) {
|
||||
const result = await generateMap(tool, args);
|
||||
if (result && result.content) {
|
||||
for (const contentItem of result.content) {
|
||||
if (contentItem.type === "text") {
|
||||
console.log(contentItem.text);
|
||||
}
|
||||
}
|
||||
} else {
|
||||
console.log(JSON.stringify(result));
|
||||
}
|
||||
} else {
|
||||
const url = await generateChartUrl(chartType, args);
|
||||
console.log(url);
|
||||
}
|
||||
} catch (e) {
|
||||
console.error(`Error generating chart for ${tool}: ${e.message}`);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
if (require.main === module) {
|
||||
main().catch((err) => {
|
||||
console.error(err.message);
|
||||
process.exit(1);
|
||||
});
|
||||
}
|
||||
|
||||
// Export functions for testing
|
||||
module.exports = { generateChartUrl, generateMap, httpPost, CHART_TYPE_MAP };
|
||||
217
deer-flow/skills/public/claude-to-deerflow/SKILL.md
Normal file
217
deer-flow/skills/public/claude-to-deerflow/SKILL.md
Normal file
@@ -0,0 +1,217 @@
|
||||
---
|
||||
name: claude-to-deerflow
|
||||
description: "Interact with DeerFlow AI agent platform via its HTTP API. Use this skill when the user wants to send messages or questions to DeerFlow for research/analysis, start a DeerFlow conversation thread, check DeerFlow status or health, list available models/skills/agents in DeerFlow, manage DeerFlow memory, upload files to DeerFlow threads, or delegate complex research tasks to DeerFlow. Also use when the user mentions deerflow, deer flow, or wants to run a deep research task that DeerFlow can handle."
|
||||
---
|
||||
|
||||
# DeerFlow Skill
|
||||
|
||||
Communicate with a running DeerFlow instance via its HTTP API. DeerFlow is an AI agent platform
|
||||
built on LangGraph that orchestrates sub-agents for research, code execution, web browsing, and more.
|
||||
|
||||
## Architecture
|
||||
|
||||
DeerFlow exposes two API surfaces behind an Nginx reverse proxy:
|
||||
|
||||
| Service | Direct Port | Via Proxy | Purpose |
|
||||
|----------------|-------------|----------------------------------|----------------------------------|
|
||||
| Gateway API | 8001 | `$DEERFLOW_GATEWAY_URL` | REST endpoints (models, skills, memory, uploads) |
|
||||
| LangGraph API | 2024 | `$DEERFLOW_LANGGRAPH_URL` | Agent threads, runs, streaming |
|
||||
|
||||
## Environment Variables
|
||||
|
||||
All URLs are configurable via environment variables. **Read these env vars before making any request.**
|
||||
|
||||
| Variable | Default | Description |
|
||||
|-------------------------|------------------------------------------|------------------------------------|
|
||||
| `DEERFLOW_URL` | `http://localhost:2026` | Unified proxy base URL |
|
||||
| `DEERFLOW_GATEWAY_URL` | `${DEERFLOW_URL}` | Gateway API base (models, skills, memory, uploads) |
|
||||
| `DEERFLOW_LANGGRAPH_URL`| `${DEERFLOW_URL}/api/langgraph` | LangGraph API base (threads, runs) |
|
||||
|
||||
When making curl calls, always resolve the URL like this:
|
||||
|
||||
```bash
|
||||
# Resolve base URLs from env (do this FIRST before any API call)
|
||||
DEERFLOW_URL="${DEERFLOW_URL:-http://localhost:2026}"
|
||||
DEERFLOW_GATEWAY_URL="${DEERFLOW_GATEWAY_URL:-$DEERFLOW_URL}"
|
||||
DEERFLOW_LANGGRAPH_URL="${DEERFLOW_LANGGRAPH_URL:-$DEERFLOW_URL/api/langgraph}"
|
||||
```
|
||||
|
||||
## Available Operations
|
||||
|
||||
### 1. Health Check
|
||||
|
||||
Verify DeerFlow is running:
|
||||
|
||||
```bash
|
||||
curl -s "$DEERFLOW_GATEWAY_URL/health"
|
||||
```
|
||||
|
||||
### 2. Send a Message (Streaming)
|
||||
|
||||
This is the primary operation. It creates a thread and streams the agent's response.
|
||||
|
||||
**Step 1: Create a thread**
|
||||
|
||||
```bash
|
||||
curl -s -X POST "$DEERFLOW_LANGGRAPH_URL/threads" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{}'
|
||||
```
|
||||
|
||||
Response: `{"thread_id": "<uuid>", ...}`
|
||||
|
||||
**Step 2: Stream a run**
|
||||
|
||||
```bash
|
||||
curl -s -N -X POST "$DEERFLOW_LANGGRAPH_URL/threads/<thread_id>/runs/stream" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"assistant_id": "lead_agent",
|
||||
"input": {
|
||||
"messages": [
|
||||
{
|
||||
"type": "human",
|
||||
"content": [{"type": "text", "text": "YOUR MESSAGE HERE"}]
|
||||
}
|
||||
]
|
||||
},
|
||||
"stream_mode": ["values", "messages-tuple"],
|
||||
"stream_subgraphs": true,
|
||||
"config": {
|
||||
"recursion_limit": 1000
|
||||
},
|
||||
"context": {
|
||||
"thinking_enabled": true,
|
||||
"is_plan_mode": true,
|
||||
"subagent_enabled": true,
|
||||
"thread_id": "<thread_id>"
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
The response is an SSE stream. Each event has the format:
|
||||
```
|
||||
event: <event_type>
|
||||
data: <json_data>
|
||||
```
|
||||
|
||||
Key event types:
|
||||
- `metadata` — run metadata including `run_id`
|
||||
- `values` — full state snapshot with `messages` array
|
||||
- `messages-tuple` — incremental message updates (AI text chunks, tool calls, tool results)
|
||||
- `end` — stream is complete
|
||||
|
||||
**Context modes** (set via `context`):
|
||||
- Flash mode: `thinking_enabled: false, is_plan_mode: false, subagent_enabled: false`
|
||||
- Standard mode: `thinking_enabled: true, is_plan_mode: false, subagent_enabled: false`
|
||||
- Pro mode: `thinking_enabled: true, is_plan_mode: true, subagent_enabled: false`
|
||||
- Ultra mode: `thinking_enabled: true, is_plan_mode: true, subagent_enabled: true`
|
||||
|
||||
### 3. Continue a Conversation
|
||||
|
||||
To send follow-up messages, reuse the same `thread_id` from step 2 and POST another run
|
||||
with the new message.
|
||||
|
||||
### 4. List Models
|
||||
|
||||
```bash
|
||||
curl -s "$DEERFLOW_GATEWAY_URL/api/models"
|
||||
```
|
||||
|
||||
Returns: `{"models": [{"name": "...", "provider": "...", ...}, ...]}`
|
||||
|
||||
### 5. List Skills
|
||||
|
||||
```bash
|
||||
curl -s "$DEERFLOW_GATEWAY_URL/api/skills"
|
||||
```
|
||||
|
||||
Returns: `{"skills": [{"name": "...", "enabled": true, ...}, ...]}`
|
||||
|
||||
### 6. Enable/Disable a Skill
|
||||
|
||||
```bash
|
||||
curl -s -X PUT "$DEERFLOW_GATEWAY_URL/api/skills/<skill_name>" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"enabled": true}'
|
||||
```
|
||||
|
||||
### 7. List Agents
|
||||
|
||||
```bash
|
||||
curl -s "$DEERFLOW_GATEWAY_URL/api/agents"
|
||||
```
|
||||
|
||||
Returns: `{"agents": [{"name": "...", ...}, ...]}`
|
||||
|
||||
### 8. Get Memory
|
||||
|
||||
```bash
|
||||
curl -s "$DEERFLOW_GATEWAY_URL/api/memory"
|
||||
```
|
||||
|
||||
Returns user context, facts, and conversation history summaries.
|
||||
|
||||
### 9. Upload Files to a Thread
|
||||
|
||||
```bash
|
||||
curl -s -X POST "$DEERFLOW_GATEWAY_URL/api/threads/<thread_id>/uploads" \
|
||||
-F "files=@/path/to/file.pdf"
|
||||
```
|
||||
|
||||
Supports PDF, PPTX, XLSX, DOCX — automatically converts to Markdown.
|
||||
|
||||
### 10. List Uploaded Files
|
||||
|
||||
```bash
|
||||
curl -s "$DEERFLOW_GATEWAY_URL/api/threads/<thread_id>/uploads/list"
|
||||
```
|
||||
|
||||
### 11. Get Thread History
|
||||
|
||||
```bash
|
||||
curl -s "$DEERFLOW_LANGGRAPH_URL/threads/<thread_id>/history"
|
||||
```
|
||||
|
||||
### 12. List Threads
|
||||
|
||||
```bash
|
||||
curl -s -X POST "$DEERFLOW_LANGGRAPH_URL/threads/search" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"limit": 20, "sort_by": "updated_at", "sort_order": "desc"}'
|
||||
```
|
||||
|
||||
## Usage Script
|
||||
|
||||
For sending messages and collecting the full response, use the helper script:
|
||||
|
||||
```bash
|
||||
bash /path/to/skills/claude-to-deerflow/scripts/chat.sh "Your question here"
|
||||
```
|
||||
|
||||
See `scripts/chat.sh` for the implementation. The script:
|
||||
1. Checks health
|
||||
2. Creates a thread
|
||||
3. Streams the run and collects the final AI response
|
||||
4. Prints the result
|
||||
|
||||
## Parsing SSE Output
|
||||
|
||||
The stream returns SSE events. To extract the final AI response from a `values` event:
|
||||
- Look for the last `event: values` block
|
||||
- Parse its `data` JSON
|
||||
- The `messages` array contains all messages; the last one with `type: "ai"` is the response
|
||||
- The `content` field of that message is the AI's text reply
|
||||
|
||||
## Error Handling
|
||||
|
||||
- If health check fails, DeerFlow is not running. Inform the user they need to start it.
|
||||
- If the stream returns an error event, extract and display the error message.
|
||||
- Common issues: port not open, services still starting up, config errors.
|
||||
|
||||
## Tips
|
||||
|
||||
- For quick questions, use flash mode (fastest, no planning).
|
||||
- For research tasks, use pro or ultra mode (enables planning and sub-agents).
|
||||
- You can upload files first, then reference them in your message.
|
||||
- Thread IDs persist — you can return to a conversation later.
|
||||
234
deer-flow/skills/public/claude-to-deerflow/scripts/chat.sh
Executable file
234
deer-flow/skills/public/claude-to-deerflow/scripts/chat.sh
Executable file
@@ -0,0 +1,234 @@
|
||||
#!/usr/bin/env bash
|
||||
# chat.sh — Send a message to DeerFlow and collect the streaming response.
|
||||
#
|
||||
# Usage:
|
||||
# bash chat.sh "Your question here"
|
||||
# bash chat.sh "Your question" <thread_id> # continue conversation
|
||||
# bash chat.sh "Your question" "" pro # specify mode
|
||||
# DEERFLOW_URL=http://host:2026 bash chat.sh "hi" # custom endpoint
|
||||
#
|
||||
# Environment variables:
|
||||
# DEERFLOW_URL — Unified proxy base URL (default: http://localhost:2026)
|
||||
# DEERFLOW_GATEWAY_URL — Gateway API base URL (default: $DEERFLOW_URL)
|
||||
# DEERFLOW_LANGGRAPH_URL — LangGraph API base URL (default: $DEERFLOW_URL/api/langgraph)
|
||||
#
|
||||
# Modes: flash, standard, pro (default), ultra
|
||||
|
||||
set -euo pipefail
|
||||
|
||||
DEERFLOW_URL="${DEERFLOW_URL:-http://localhost:2026}"
|
||||
GATEWAY_URL="${DEERFLOW_GATEWAY_URL:-$DEERFLOW_URL}"
|
||||
LANGGRAPH_URL="${DEERFLOW_LANGGRAPH_URL:-$DEERFLOW_URL/api/langgraph}"
|
||||
MESSAGE="${1:?Usage: chat.sh <message> [thread_id] [mode]}"
|
||||
THREAD_ID="${2:-}"
|
||||
MODE="${3:-pro}"
|
||||
|
||||
# --- Health check ---
|
||||
HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" "${GATEWAY_URL}/health" 2>/dev/null || echo "000")
|
||||
if [ "$HTTP_CODE" = "000" ] || [ "$HTTP_CODE" -ge 400 ]; then
|
||||
echo "ERROR: DeerFlow is not reachable at ${GATEWAY_URL} (HTTP ${HTTP_CODE})" >&2
|
||||
echo "Make sure DeerFlow is running. Start it with: cd <deerflow-dir> && make dev" >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# --- Create or reuse thread ---
|
||||
if [ -z "$THREAD_ID" ]; then
|
||||
THREAD_RESP=$(curl -s -X POST "${LANGGRAPH_URL}/threads" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{}')
|
||||
THREAD_ID=$(echo "$THREAD_RESP" | python3 -c "import sys,json; print(json.load(sys.stdin)['thread_id'])" 2>/dev/null)
|
||||
if [ -z "$THREAD_ID" ]; then
|
||||
echo "ERROR: Failed to create thread. Response: ${THREAD_RESP}" >&2
|
||||
exit 1
|
||||
fi
|
||||
echo "Thread: ${THREAD_ID}" >&2
|
||||
fi
|
||||
|
||||
# --- Build context based on mode ---
|
||||
case "$MODE" in
|
||||
flash)
|
||||
CONTEXT='{"thinking_enabled":false,"is_plan_mode":false,"subagent_enabled":false,"thread_id":"'"$THREAD_ID"'"}'
|
||||
;;
|
||||
standard)
|
||||
CONTEXT='{"thinking_enabled":true,"is_plan_mode":false,"subagent_enabled":false,"thread_id":"'"$THREAD_ID"'"}'
|
||||
;;
|
||||
pro)
|
||||
CONTEXT='{"thinking_enabled":true,"is_plan_mode":true,"subagent_enabled":false,"thread_id":"'"$THREAD_ID"'"}'
|
||||
;;
|
||||
ultra)
|
||||
CONTEXT='{"thinking_enabled":true,"is_plan_mode":true,"subagent_enabled":true,"thread_id":"'"$THREAD_ID"'"}'
|
||||
;;
|
||||
*)
|
||||
echo "ERROR: Unknown mode '${MODE}'. Use: flash, standard, pro, ultra" >&2
|
||||
exit 1
|
||||
;;
|
||||
esac
|
||||
|
||||
# --- Escape message for JSON ---
|
||||
ESCAPED_MSG=$(python3 -c "import json,sys; print(json.dumps(sys.argv[1]))" "$MESSAGE")
|
||||
|
||||
# --- Build request body ---
|
||||
BODY=$(cat <<ENDJSON
|
||||
{
|
||||
"assistant_id": "lead_agent",
|
||||
"input": {
|
||||
"messages": [
|
||||
{
|
||||
"type": "human",
|
||||
"content": [{"type": "text", "text": ${ESCAPED_MSG}}]
|
||||
}
|
||||
]
|
||||
},
|
||||
"stream_mode": ["values", "messages-tuple"],
|
||||
"stream_subgraphs": true,
|
||||
"config": {
|
||||
"recursion_limit": 1000
|
||||
},
|
||||
"context": ${CONTEXT}
|
||||
}
|
||||
ENDJSON
|
||||
)
|
||||
|
||||
# --- Stream the run and extract final response ---
|
||||
# We collect the full SSE output, then parse the last values event to get the AI response.
|
||||
TMPFILE=$(mktemp)
|
||||
trap "rm -f '$TMPFILE'" EXIT
|
||||
|
||||
curl -s -N -X POST "${LANGGRAPH_URL}/threads/${THREAD_ID}/runs/stream" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d "$BODY" > "$TMPFILE"
|
||||
|
||||
# Parse the SSE output: extract the last "event: values" data block and get the final AI message
|
||||
python3 - "$TMPFILE" "$GATEWAY_URL" "$THREAD_ID" << 'PYEOF'
|
||||
import json
|
||||
import sys
|
||||
|
||||
sse_file = sys.argv[1] if len(sys.argv) > 1 else None
|
||||
gateway_url = sys.argv[2].rstrip("/") if len(sys.argv) > 2 else "http://localhost:2026"
|
||||
thread_id = sys.argv[3] if len(sys.argv) > 3 else ""
|
||||
if not sse_file:
|
||||
sys.exit(1)
|
||||
|
||||
with open(sse_file, "r") as f:
|
||||
raw = f.read()
|
||||
|
||||
# Parse SSE events
|
||||
events = []
|
||||
current_event = None
|
||||
current_data_lines = []
|
||||
|
||||
for line in raw.split("\n"):
|
||||
if line.startswith("event:"):
|
||||
if current_event and current_data_lines:
|
||||
events.append((current_event, "\n".join(current_data_lines)))
|
||||
current_event = line[len("event:"):].strip()
|
||||
current_data_lines = []
|
||||
elif line.startswith("data:"):
|
||||
current_data_lines.append(line[len("data:"):].strip())
|
||||
elif line == "" and current_event:
|
||||
if current_data_lines:
|
||||
events.append((current_event, "\n".join(current_data_lines)))
|
||||
current_event = None
|
||||
current_data_lines = []
|
||||
|
||||
# Flush remaining
|
||||
if current_event and current_data_lines:
|
||||
events.append((current_event, "\n".join(current_data_lines)))
|
||||
|
||||
import posixpath
|
||||
|
||||
def extract_response_text(messages):
|
||||
"""Mirror manager.py _extract_response_text: handles ask_clarification interrupt + regular AI."""
|
||||
for msg in reversed(messages):
|
||||
if not isinstance(msg, dict):
|
||||
continue
|
||||
msg_type = msg.get("type")
|
||||
# ask_clarification interrupt: tool message with name ask_clarification
|
||||
if msg_type == "tool" and msg.get("name") == "ask_clarification":
|
||||
content = msg.get("content", "")
|
||||
if isinstance(content, str) and content:
|
||||
return content
|
||||
# Regular AI message
|
||||
if msg_type == "ai":
|
||||
content = msg.get("content", "")
|
||||
if isinstance(content, str) and content:
|
||||
return content
|
||||
if isinstance(content, list):
|
||||
parts = []
|
||||
for block in content:
|
||||
if isinstance(block, dict) and block.get("type") == "text":
|
||||
parts.append(block.get("text", ""))
|
||||
elif isinstance(block, str):
|
||||
parts.append(block)
|
||||
text = "".join(parts)
|
||||
if text:
|
||||
return text
|
||||
return ""
|
||||
|
||||
def extract_artifacts(messages):
|
||||
"""Mirror manager.py _extract_artifacts: only artifacts from the last response cycle."""
|
||||
artifacts = []
|
||||
for msg in reversed(messages):
|
||||
if not isinstance(msg, dict):
|
||||
continue
|
||||
if msg.get("type") == "human":
|
||||
break
|
||||
if msg.get("type") == "ai":
|
||||
for tc in msg.get("tool_calls", []):
|
||||
if isinstance(tc, dict) and tc.get("name") == "present_files":
|
||||
paths = tc.get("args", {}).get("filepaths", [])
|
||||
if isinstance(paths, list):
|
||||
artifacts.extend(p for p in paths if isinstance(p, str))
|
||||
return artifacts
|
||||
|
||||
def artifact_url(virtual_path):
|
||||
# virtual_path like /mnt/user-data/outputs/file.md
|
||||
# API endpoint: {gateway}/api/threads/{thread_id}/artifacts/{path without leading slash}
|
||||
path = virtual_path.lstrip("/")
|
||||
return f"{gateway_url}/api/threads/{thread_id}/artifacts/{path}"
|
||||
|
||||
def format_artifact_text(artifacts):
|
||||
urls = [artifact_url(p) for p in artifacts]
|
||||
if len(urls) == 1:
|
||||
return f"Created File: {urls[0]}"
|
||||
return "Created Files:\n" + "\n".join(urls)
|
||||
|
||||
# Find the last "values" event with messages
|
||||
result_messages = None
|
||||
for event_type, data_str in reversed(events):
|
||||
if event_type != "values":
|
||||
continue
|
||||
try:
|
||||
data = json.loads(data_str)
|
||||
except json.JSONDecodeError:
|
||||
continue
|
||||
if "messages" in data:
|
||||
result_messages = data["messages"]
|
||||
break
|
||||
|
||||
if result_messages is not None:
|
||||
response_text = extract_response_text(result_messages)
|
||||
artifacts = extract_artifacts(result_messages)
|
||||
if artifacts:
|
||||
artifact_text = format_artifact_text(artifacts)
|
||||
response_text = (response_text + "\n\n" + artifact_text) if response_text else artifact_text
|
||||
if response_text:
|
||||
print(response_text)
|
||||
else:
|
||||
print("(No response from agent)", file=sys.stderr)
|
||||
sys.exit(1)
|
||||
else:
|
||||
# Check for error events
|
||||
for event_type, data_str in events:
|
||||
if event_type == "error":
|
||||
print(f"ERROR from DeerFlow: {data_str}", file=sys.stderr)
|
||||
sys.exit(1)
|
||||
print("No AI response found in the stream.", file=sys.stderr)
|
||||
if len(raw) < 2000:
|
||||
print(f"Raw SSE output:\n{raw}", file=sys.stderr)
|
||||
sys.exit(1)
|
||||
PYEOF
|
||||
|
||||
echo ""
|
||||
echo "---"
|
||||
echo "Thread ID: ${THREAD_ID}" >&2
|
||||
98
deer-flow/skills/public/claude-to-deerflow/scripts/status.sh
Executable file
98
deer-flow/skills/public/claude-to-deerflow/scripts/status.sh
Executable file
@@ -0,0 +1,98 @@
|
||||
#!/usr/bin/env bash
|
||||
# status.sh — Check DeerFlow status and list available resources.
|
||||
#
|
||||
# Usage:
|
||||
# bash status.sh # health + summary
|
||||
# bash status.sh models # list models
|
||||
# bash status.sh skills # list skills
|
||||
# bash status.sh agents # list agents
|
||||
# bash status.sh threads # list recent threads
|
||||
# bash status.sh memory # show memory
|
||||
# bash status.sh thread <id> # show thread history
|
||||
#
|
||||
# Environment variables:
|
||||
# DEERFLOW_URL — Unified proxy base URL (default: http://localhost:2026)
|
||||
# DEERFLOW_GATEWAY_URL — Gateway API base URL (default: $DEERFLOW_URL)
|
||||
# DEERFLOW_LANGGRAPH_URL — LangGraph API base URL (default: $DEERFLOW_URL/api/langgraph)
|
||||
|
||||
set -euo pipefail
|
||||
|
||||
DEERFLOW_URL="${DEERFLOW_URL:-http://localhost:2026}"
|
||||
GATEWAY_URL="${DEERFLOW_GATEWAY_URL:-$DEERFLOW_URL}"
|
||||
LANGGRAPH_URL="${DEERFLOW_LANGGRAPH_URL:-$DEERFLOW_URL/api/langgraph}"
|
||||
CMD="${1:-health}"
|
||||
ARG="${2:-}"
|
||||
|
||||
case "$CMD" in
|
||||
health)
|
||||
echo "Checking DeerFlow at ${GATEWAY_URL}..."
|
||||
HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" "${GATEWAY_URL}/health" 2>/dev/null || echo "000")
|
||||
if [ "$HTTP_CODE" = "000" ]; then
|
||||
echo "UNREACHABLE — DeerFlow is not running at ${GATEWAY_URL}"
|
||||
exit 1
|
||||
elif [ "$HTTP_CODE" -ge 400 ]; then
|
||||
echo "ERROR — Health check returned HTTP ${HTTP_CODE}"
|
||||
exit 1
|
||||
else
|
||||
echo "OK — DeerFlow is running (HTTP ${HTTP_CODE})"
|
||||
fi
|
||||
;;
|
||||
models)
|
||||
curl -s "${GATEWAY_URL}/api/models" | python3 -m json.tool
|
||||
;;
|
||||
skills)
|
||||
curl -s "${GATEWAY_URL}/api/skills" | python3 -m json.tool
|
||||
;;
|
||||
agents)
|
||||
curl -s "${GATEWAY_URL}/api/agents" | python3 -m json.tool
|
||||
;;
|
||||
threads)
|
||||
curl -s -X POST "${LANGGRAPH_URL}/threads/search" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"limit": 20, "sort_by": "updated_at", "sort_order": "desc", "select": ["thread_id", "updated_at", "values"]}' \
|
||||
| python3 -c "
|
||||
import json, sys
|
||||
threads = json.load(sys.stdin)
|
||||
if not threads:
|
||||
print('No threads found.')
|
||||
sys.exit(0)
|
||||
for t in threads:
|
||||
tid = t.get('thread_id', '?')
|
||||
updated = t.get('updated_at', '?')
|
||||
title = (t.get('values') or {}).get('title', '(untitled)')
|
||||
print(f'{tid} {updated} {title}')
|
||||
"
|
||||
;;
|
||||
memory)
|
||||
curl -s "${GATEWAY_URL}/api/memory" | python3 -m json.tool
|
||||
;;
|
||||
thread)
|
||||
if [ -z "$ARG" ]; then
|
||||
echo "Usage: status.sh thread <thread_id>" >&2
|
||||
exit 1
|
||||
fi
|
||||
curl -s "${LANGGRAPH_URL}/threads/${ARG}/history" | python3 -c "
|
||||
import json, sys
|
||||
data = json.load(sys.stdin)
|
||||
if isinstance(data, list):
|
||||
for state in data[:5]:
|
||||
values = state.get('values', {})
|
||||
msgs = values.get('messages', [])
|
||||
for m in msgs[-5:]:
|
||||
role = m.get('type', '?')
|
||||
content = m.get('content', '')
|
||||
if isinstance(content, list):
|
||||
content = ' '.join(p.get('text','') for p in content if isinstance(p, dict))
|
||||
preview = content[:200] if content else '(empty)'
|
||||
print(f'[{role}] {preview}')
|
||||
print('---')
|
||||
else:
|
||||
print(json.dumps(data, indent=2))
|
||||
"
|
||||
;;
|
||||
*)
|
||||
echo "Unknown command: ${CMD}" >&2
|
||||
echo "Usage: status.sh [health|models|skills|agents|threads|memory|thread <id>]" >&2
|
||||
exit 1
|
||||
;;
|
||||
esac
|
||||
415
deer-flow/skills/public/code-documentation/SKILL.md
Normal file
415
deer-flow/skills/public/code-documentation/SKILL.md
Normal file
@@ -0,0 +1,415 @@
|
||||
---
|
||||
name: code-documentation
|
||||
description: Use this skill when the user requests to generate, create, or improve documentation for code, APIs, libraries, repositories, or software projects. Supports README generation, API reference documentation, inline code comments, architecture documentation, changelog generation, and developer guides. Trigger on requests like "document this code", "create a README", "generate API docs", "write developer guide", or when analyzing codebases for documentation purposes.
|
||||
---
|
||||
|
||||
# Code Documentation Skill
|
||||
|
||||
## Overview
|
||||
|
||||
This skill generates professional, comprehensive documentation for software projects, codebases, libraries, and APIs. It follows industry best practices from projects like React, Django, Stripe, and Kubernetes to produce documentation that is accurate, well-structured, and useful for both new contributors and experienced developers.
|
||||
|
||||
The output ranges from single-file READMEs to multi-document developer guides, always matched to the project's complexity and the user's needs.
|
||||
|
||||
## Core Capabilities
|
||||
|
||||
- Generate comprehensive README.md files with badges, installation, usage, and API reference
|
||||
- Create API reference documentation from source code analysis
|
||||
- Produce architecture and design documentation with diagrams
|
||||
- Write developer onboarding and contribution guides
|
||||
- Generate changelogs from commit history or release notes
|
||||
- Create inline code documentation following language-specific conventions
|
||||
- Support JSDoc, docstrings, GoDoc, Javadoc, and Rustdoc formats
|
||||
- Adapt documentation style to the project's language and ecosystem
|
||||
|
||||
## When to Use This Skill
|
||||
|
||||
**Always load this skill when:**
|
||||
|
||||
- User asks to "document", "create docs", or "write documentation" for any code
|
||||
- User requests a README, API reference, or developer guide
|
||||
- User shares a codebase or repository and wants documentation generated
|
||||
- User asks to improve or update existing documentation
|
||||
- User needs architecture documentation, including diagrams
|
||||
- User requests a changelog or migration guide
|
||||
|
||||
## Documentation Workflow
|
||||
|
||||
### Phase 1: Codebase Analysis
|
||||
|
||||
Before writing any documentation, thoroughly understand the codebase.
|
||||
|
||||
#### Step 1.1: Project Discovery
|
||||
|
||||
Identify the project fundamentals:
|
||||
|
||||
| Field | How to Determine |
|
||||
|-------|-----------------|
|
||||
| **Language(s)** | Check file extensions, `package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`, etc. |
|
||||
| **Framework** | Look at dependencies for known frameworks (React, Django, Express, Spring, etc.) |
|
||||
| **Build System** | Check for `Makefile`, `CMakeLists.txt`, `webpack.config.js`, `build.gradle`, etc. |
|
||||
| **Package Manager** | npm/yarn/pnpm, pip/uv/poetry, cargo, go modules, etc. |
|
||||
| **Project Structure** | Map out the directory tree to understand the architecture |
|
||||
| **Entry Points** | Find main files, CLI entry points, exported modules |
|
||||
| **Existing Docs** | Check for existing README, docs/, wiki, or inline documentation |
|
||||
|
||||
#### Step 1.2: Code Structure Analysis
|
||||
|
||||
Use sandbox tools to explore the codebase:
|
||||
|
||||
```bash
|
||||
# Get directory structure
|
||||
ls /mnt/user-data/uploads/project-dir/
|
||||
|
||||
# Read key files
|
||||
read_file /mnt/user-data/uploads/project-dir/package.json
|
||||
read_file /mnt/user-data/uploads/project-dir/pyproject.toml
|
||||
|
||||
# Search for public API surfaces
|
||||
grep -r "export " /mnt/user-data/uploads/project-dir/src/
|
||||
grep -r "def " /mnt/user-data/uploads/project-dir/src/ --include="*.py"
|
||||
grep -r "func " /mnt/user-data/uploads/project-dir/ --include="*.go"
|
||||
```
|
||||
|
||||
#### Step 1.3: Identify Documentation Scope
|
||||
|
||||
Based on analysis, determine what documentation to produce:
|
||||
|
||||
| Project Size | Recommended Documentation |
|
||||
|-------------|--------------------------|
|
||||
| **Single file / script** | Inline comments + usage header |
|
||||
| **Small library** | README with API reference |
|
||||
| **Medium project** | README + API docs + examples |
|
||||
| **Large project** | README + Architecture + API + Contributing + Changelog |
|
||||
|
||||
### Phase 2: Documentation Generation
|
||||
|
||||
#### Step 2.1: README Generation
|
||||
|
||||
Every project needs a README. Follow this structure:
|
||||
|
||||
```markdown
|
||||
# Project Name
|
||||
|
||||
[One-line project description — what it does and why it matters]
|
||||
|
||||
[](#) [](#)
|
||||
|
||||
## Features
|
||||
|
||||
- [Key feature 1 — brief description]
|
||||
- [Key feature 2 — brief description]
|
||||
- [Key feature 3 — brief description]
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- [Prerequisite 1 with version requirement]
|
||||
- [Prerequisite 2 with version requirement]
|
||||
|
||||
### Installation
|
||||
|
||||
[Installation commands with copy-paste-ready code blocks]
|
||||
|
||||
### Basic Usage
|
||||
|
||||
[Minimal working example that demonstrates core functionality]
|
||||
|
||||
## Documentation
|
||||
|
||||
- [Link to full API reference if separate]
|
||||
- [Link to architecture docs if separate]
|
||||
- [Link to examples directory if applicable]
|
||||
|
||||
## API Reference
|
||||
|
||||
[Inline API reference for smaller projects OR link to generated docs]
|
||||
|
||||
## Configuration
|
||||
|
||||
[Environment variables, config files, or runtime options]
|
||||
|
||||
## Examples
|
||||
|
||||
[2-3 practical examples covering common use cases]
|
||||
|
||||
## Development
|
||||
|
||||
### Setup
|
||||
|
||||
[How to set up a development environment]
|
||||
|
||||
### Testing
|
||||
|
||||
[How to run tests]
|
||||
|
||||
### Building
|
||||
|
||||
[How to build the project]
|
||||
|
||||
## Contributing
|
||||
|
||||
[Contribution guidelines or link to CONTRIBUTING.md]
|
||||
|
||||
## License
|
||||
|
||||
[License information]
|
||||
```
|
||||
|
||||
#### Step 2.2: API Reference Generation
|
||||
|
||||
For each public API surface, document:
|
||||
|
||||
**Function / Method Documentation**:
|
||||
|
||||
```markdown
|
||||
### `functionName(param1, param2, options?)`
|
||||
|
||||
Brief description of what this function does.
|
||||
|
||||
**Parameters:**
|
||||
|
||||
| Parameter | Type | Required | Default | Description |
|
||||
|-----------|------|----------|---------|-------------|
|
||||
| `param1` | `string` | Yes | — | Description of param1 |
|
||||
| `param2` | `number` | Yes | — | Description of param2 |
|
||||
| `options` | `Object` | No | `{}` | Configuration options |
|
||||
| `options.timeout` | `number` | No | `5000` | Timeout in milliseconds |
|
||||
|
||||
**Returns:** `Promise<Result>` — Description of return value
|
||||
|
||||
**Throws:**
|
||||
- `ValidationError` — When param1 is empty
|
||||
- `TimeoutError` — When the operation exceeds the timeout
|
||||
|
||||
**Example:**
|
||||
|
||||
\`\`\`javascript
|
||||
const result = await functionName("hello", 42, { timeout: 10000 });
|
||||
console.log(result.data);
|
||||
\`\`\`
|
||||
```
|
||||
|
||||
**Class Documentation**:
|
||||
|
||||
```markdown
|
||||
### `ClassName`
|
||||
|
||||
Brief description of the class and its purpose.
|
||||
|
||||
**Constructor:**
|
||||
|
||||
\`\`\`javascript
|
||||
new ClassName(config)
|
||||
\`\`\`
|
||||
|
||||
| Parameter | Type | Description |
|
||||
|-----------|------|-------------|
|
||||
| `config.option1` | `string` | Description |
|
||||
| `config.option2` | `boolean` | Description |
|
||||
|
||||
**Methods:**
|
||||
|
||||
- [`method1()`](#method1) — Brief description
|
||||
- [`method2(param)`](#method2) — Brief description
|
||||
|
||||
**Properties:**
|
||||
|
||||
| Property | Type | Description |
|
||||
|----------|------|-------------|
|
||||
| `property1` | `string` | Description |
|
||||
| `property2` | `number` | Read-only. Description |
|
||||
```
|
||||
|
||||
#### Step 2.3: Architecture Documentation
|
||||
|
||||
For medium-to-large projects, include architecture documentation:
|
||||
|
||||
```markdown
|
||||
# Architecture Overview
|
||||
|
||||
## System Diagram
|
||||
|
||||
[Include a Mermaid diagram showing the high-level architecture]
|
||||
|
||||
\`\`\`mermaid
|
||||
graph TD
|
||||
A[Client] --> B[API Gateway]
|
||||
B --> C[Service A]
|
||||
B --> D[Service B]
|
||||
C --> E[(Database)]
|
||||
D --> E
|
||||
\`\`\`
|
||||
|
||||
## Component Overview
|
||||
|
||||
### Component Name
|
||||
- **Purpose**: What this component does
|
||||
- **Location**: `src/components/name/`
|
||||
- **Dependencies**: What it depends on
|
||||
- **Public API**: Key exports or interfaces
|
||||
|
||||
## Data Flow
|
||||
|
||||
[Describe how data flows through the system for key operations]
|
||||
|
||||
## Design Decisions
|
||||
|
||||
### Decision Title
|
||||
- **Context**: What situation led to this decision
|
||||
- **Decision**: What was decided
|
||||
- **Rationale**: Why this approach was chosen
|
||||
- **Trade-offs**: What was sacrificed
|
||||
```
|
||||
|
||||
#### Step 2.4: Inline Code Documentation
|
||||
|
||||
Generate language-appropriate inline documentation:
|
||||
|
||||
**Python (Docstrings — Google style)**:
|
||||
```python
|
||||
def process_data(input_path: str, options: dict | None = None) -> ProcessResult:
|
||||
"""Process data from the given file path.
|
||||
|
||||
Reads the input file, applies transformations based on the provided
|
||||
options, and returns a structured result object.
|
||||
|
||||
Args:
|
||||
input_path: Absolute path to the input data file.
|
||||
Supports CSV, JSON, and Parquet formats.
|
||||
options: Optional configuration dictionary.
|
||||
- "validate" (bool): Enable input validation. Defaults to True.
|
||||
- "format" (str): Output format ("json" or "csv"). Defaults to "json".
|
||||
|
||||
Returns:
|
||||
A ProcessResult containing the transformed data and metadata.
|
||||
|
||||
Raises:
|
||||
FileNotFoundError: If input_path does not exist.
|
||||
ValidationError: If validation is enabled and data is malformed.
|
||||
|
||||
Example:
|
||||
>>> result = process_data("/data/input.csv", {"validate": True})
|
||||
>>> print(result.row_count)
|
||||
1500
|
||||
"""
|
||||
```
|
||||
|
||||
**TypeScript (JSDoc / TSDoc)**:
|
||||
```typescript
|
||||
/**
|
||||
* Fetches user data from the API and transforms it for display.
|
||||
*
|
||||
* @param userId - The unique identifier of the user
|
||||
* @param options - Configuration options for the fetch operation
|
||||
* @param options.includeProfile - Whether to include the full profile. Defaults to `false`.
|
||||
* @param options.cache - Cache duration in seconds. Set to `0` to disable.
|
||||
* @returns The transformed user data ready for rendering
|
||||
* @throws {NotFoundError} When the user ID does not exist
|
||||
* @throws {NetworkError} When the API is unreachable
|
||||
*
|
||||
* @example
|
||||
* ```ts
|
||||
* const user = await fetchUser("usr_123", { includeProfile: true });
|
||||
* console.log(user.displayName);
|
||||
* ```
|
||||
*/
|
||||
```
|
||||
|
||||
**Go (GoDoc)**:
|
||||
```go
|
||||
// ProcessData reads the input file at the given path, applies the specified
|
||||
// transformations, and returns the processed result.
|
||||
//
|
||||
// The input path must be an absolute path to a CSV or JSON file.
|
||||
// If options is nil, default options are used.
|
||||
//
|
||||
// ProcessData returns an error if the file does not exist or cannot be parsed.
|
||||
func ProcessData(inputPath string, options *ProcessOptions) (*Result, error) {
|
||||
```
|
||||
|
||||
### Phase 3: Quality Assurance
|
||||
|
||||
#### Step 3.1: Documentation Completeness Check
|
||||
|
||||
Verify the documentation covers:
|
||||
|
||||
- [ ] **What it is** — Clear project description that a newcomer can understand
|
||||
- [ ] **Why it exists** — Problem it solves and value proposition
|
||||
- [ ] **How to install** — Copy-paste-ready installation commands
|
||||
- [ ] **How to use** — At least one minimal working example
|
||||
- [ ] **API surface** — All public functions, classes, and types documented
|
||||
- [ ] **Configuration** — All environment variables, config files, and options
|
||||
- [ ] **Error handling** — Common errors and how to resolve them
|
||||
- [ ] **Contributing** — How to set up dev environment and submit changes
|
||||
|
||||
#### Step 3.2: Quality Standards
|
||||
|
||||
| Standard | Check |
|
||||
|----------|-------|
|
||||
| **Accuracy** | Every code example must actually work with the described API |
|
||||
| **Completeness** | No public API surface left undocumented |
|
||||
| **Consistency** | Same formatting and structure throughout |
|
||||
| **Freshness** | Documentation matches the current code, not an older version |
|
||||
| **Accessibility** | No jargon without explanation, acronyms defined on first use |
|
||||
| **Examples** | Every complex concept has at least one practical example |
|
||||
|
||||
#### Step 3.3: Cross-reference Validation
|
||||
|
||||
Ensure:
|
||||
- All mentioned file paths exist in the project
|
||||
- All referenced functions and classes exist in the code
|
||||
- All code examples use the correct function signatures
|
||||
- Version numbers match the project's actual version
|
||||
- All links (internal and external) are valid
|
||||
|
||||
## Documentation Style Guide
|
||||
|
||||
### Writing Principles
|
||||
|
||||
1. **Lead with the "why"** — Before explaining how something works, explain why it exists
|
||||
2. **Progressive disclosure** — Start simple, add complexity gradually
|
||||
3. **Show, don't tell** — Prefer code examples over lengthy explanations
|
||||
4. **Active voice** — "The function returns X" not "X is returned by the function"
|
||||
5. **Present tense** — "The server starts on port 8080" not "The server will start on port 8080"
|
||||
6. **Second person** — "You can configure..." not "Users can configure..."
|
||||
|
||||
### Formatting Rules
|
||||
|
||||
- Use ATX-style headers (`#`, `##`, `###`)
|
||||
- Use fenced code blocks with language specification (` ```python `, ` ```bash `)
|
||||
- Use tables for structured information (parameters, options, configuration)
|
||||
- Use admonitions for important notes, warnings, and tips
|
||||
- Keep line length readable (wrap prose at ~80-100 characters in source)
|
||||
- Use `code formatting` for function names, file paths, variable names, and CLI commands
|
||||
|
||||
### Language-Specific Conventions
|
||||
|
||||
| Language | Doc Format | Style Guide |
|
||||
|----------|-----------|-------------|
|
||||
| Python | Google-style docstrings | PEP 257 |
|
||||
| TypeScript/JavaScript | TSDoc / JSDoc | TypeDoc conventions |
|
||||
| Go | GoDoc comments | Effective Go |
|
||||
| Rust | Rustdoc (`///`) | Rust API Guidelines |
|
||||
| Java | Javadoc | Oracle Javadoc Guide |
|
||||
| C/C++ | Doxygen | Doxygen manual |
|
||||
|
||||
## Output Handling
|
||||
|
||||
After generation:
|
||||
|
||||
- Save documentation files to `/mnt/user-data/outputs/`
|
||||
- For multi-file documentation, maintain the project directory structure
|
||||
- Present generated files to the user using the `present_files` tool
|
||||
- Offer to iterate on specific sections or adjust the level of detail
|
||||
- Suggest additional documentation that might be valuable
|
||||
|
||||
## Notes
|
||||
|
||||
- Always analyze the actual code before writing documentation — never guess at API signatures or behavior
|
||||
- When existing documentation exists, preserve its structure unless the user explicitly asks for a rewrite
|
||||
- For large codebases, prioritize documenting the public API surface and key abstractions first
|
||||
- Documentation should be written in the same language as the project's existing docs; default to English if none exist
|
||||
- When generating changelogs, use the [Keep a Changelog](https://keepachangelog.com/) format
|
||||
- This skill works well in combination with the `deep-research` skill for documenting third-party integrations or dependencies
|
||||
631
deer-flow/skills/public/consulting-analysis/SKILL.md
Normal file
631
deer-flow/skills/public/consulting-analysis/SKILL.md
Normal file
@@ -0,0 +1,631 @@
|
||||
---
|
||||
name: consulting-analysis
|
||||
description: Use this skill when the user requests to generate, create, or write professional research reports including but not limited to market analysis, consumer insights, brand analysis, financial analysis, industry research, competitive intelligence, investment due diligence, or any consulting-grade analytical report. This skill operates in two phases — (1) generating a structured analysis framework with chapter skeleton, data query requirements, and analysis logic, and (2) after data collection by other skills, producing the final consulting-grade report with structured narratives, embedded charts, and strategic insights.
|
||||
---
|
||||
|
||||
# Professional Research Report Skill
|
||||
|
||||
## Overview
|
||||
|
||||
This skill produces professional, consulting-grade research reports in Markdown format, covering domains such as **market analysis, consumer insights, brand strategy, financial analysis, industry research, competitive intelligence, investment research, and macroeconomic analysis**. It operates across two distinct phases:
|
||||
|
||||
1. **Phase 1 — Analysis Framework Generation**: Given a research subject, produce a rigorous analysis framework including chapter skeleton, per-chapter data requirements, analysis logic, and visualization plan.
|
||||
2. **Phase 2 — Report Generation**: After data has been collected by other skills, synthesize all inputs into a final polished report.
|
||||
|
||||
The output adheres to McKinsey/BCG consulting voice standards. The report language follows the `output_locale` setting (default: `zh_CN` for Chinese).
|
||||
|
||||
## Data Authenticity Protocol
|
||||
|
||||
**Strict Adherence Rule**: All data presented in the report and visualized in charts MUST be derived directly from the provided **Data Summary** or **External Search Findings**.
|
||||
- **NO Hallucinations**: Do not invent, estimate, or simulate data. If data is missing, state "Data not available" rather than fabricating numbers.
|
||||
- **Traceable Sources**: Every major claim and chart must be traceable back to the input data package.
|
||||
|
||||
## Core Capabilities
|
||||
|
||||
- **Design analysis frameworks** from scratch given only a research subject and scope
|
||||
- Transform raw data into structured, high-depth research reports
|
||||
- Follow the **"Visual Anchor → Data Contrast → Integrated Analysis"** flow per sub-chapter
|
||||
- Produce insights following the **"Data → User Psychology → Strategy Implication"** chain
|
||||
- Embed pre-generated charts and construct comparison tables
|
||||
- Generate inline citations formatted per **GB/T 7714-2015** standards
|
||||
- Output reports in the language specified by `output_locale` with professional consulting tone
|
||||
- Adapt analytical depth and structure to domain (marketing, finance, industry, etc.)
|
||||
|
||||
## When to Use This Skill
|
||||
|
||||
**Always load this skill when:**
|
||||
|
||||
- User asks for a market analysis, consumer insight report, financial analysis, industry research, or any consulting-grade analytical report
|
||||
- User provides a research subject and needs a structured analysis framework before data collection
|
||||
- User provides data summaries, analysis frameworks, or chart files to be synthesized into a report
|
||||
- User needs a professional consulting-style research report
|
||||
- The task involves transforming research findings into structured strategic narratives
|
||||
|
||||
---
|
||||
|
||||
# Phase 1: Analysis Framework Generation
|
||||
|
||||
## Purpose
|
||||
|
||||
Given a **research subject** (e.g., "Gen-Z Skincare Market Analysis", "NEV Industry Competitive Landscape", "Brand X Consumer Profiling"), produce a complete **analysis framework** that serves as the blueprint for downstream data collection and final report generation.
|
||||
|
||||
## Phase 1 Inputs
|
||||
|
||||
| Input | Description | Required |
|
||||
|-------|-------------|----------|
|
||||
| **Research Subject** | The topic or question to be analyzed | Yes |
|
||||
| **Scope / Constraints** | Geographic scope, time range, industry segment, target audience, etc. | Optional |
|
||||
| **Specific Angles** | Any particular angles or hypotheses the user wants explored | Optional |
|
||||
| **Domain** | The analytical domain: market, finance, industry, brand, consumer, investment, etc. | Inferred |
|
||||
|
||||
## Phase 1 Workflow
|
||||
|
||||
### Step 1.1: Understand the Research Subject
|
||||
|
||||
- Parse the research subject to identify the **core entity** (market, brand, product, industry, consumer segment, financial instrument, etc.)
|
||||
- Identify the **analytical domain** (marketing, finance, industry, competitive, consumer, investment, macro, etc.)
|
||||
- Determine the **natural analytical dimensions** based on domain:
|
||||
|
||||
| Domain | Typical Dimensions |
|
||||
|--------|--------------------|
|
||||
| Market Analysis | Market size, growth trends, market segmentation, growth drivers, competitive landscape, consumer profiling |
|
||||
| Brand Analysis | Brand positioning, market share, consumer perception, marketing strategy, competitor comparison |
|
||||
| Consumer Insights | Demographic profiling, purchase behavior, decision journey, pain points, scenario analysis |
|
||||
| Financial Analysis | Macro environment, industry trends, company fundamentals, financial metrics, valuation, risk assessment |
|
||||
| Industry Research | Value chain analysis, market size, competitive landscape, policy environment, technology trends, entry barriers |
|
||||
| Investment Due Diligence | Business model, financial health, management assessment, market opportunity, risk factors, exit pathways |
|
||||
| Competitive Intelligence | Competitor identification, strategic comparison, SWOT analysis, differentiated positioning, market dynamics |
|
||||
|
||||
### Step 1.2: Select Analysis Frameworks & Models
|
||||
|
||||
Based on the identified domain and research subject, select **one or more** professional analysis frameworks to structure the reasoning in each chapter. The chosen frameworks guide the **Analysis Logic** in the chapter skeleton (Step 1.3).
|
||||
|
||||
#### Strategic & Environmental Analysis
|
||||
|
||||
| Framework | Description | Best For |
|
||||
|-----------|-------------|----------|
|
||||
| **SWOT Analysis** | Strengths, Weaknesses, Opportunities, Threats | Brand assessment, competitive positioning, strategic planning |
|
||||
| **PEST / PESTEL Analysis** | Political, Economic, Social, Technological (+ Environmental, Legal) | Macro-environment scanning, market entry assessment, policy impact analysis |
|
||||
| **Porter's Five Forces** | Supplier bargaining power, buyer bargaining power, threat of new entrants, threat of substitutes, industry rivalry | Industry competitive landscape, entry barrier assessment, profit margin analysis |
|
||||
| **Porter's Diamond Model** | Factor conditions, demand conditions, related industries, firm strategy & structure | National/regional competitive advantage analysis |
|
||||
| **VRIO Analysis** | Value, Rarity, Imitability, Organization | Core competency assessment, resource advantage analysis |
|
||||
|
||||
#### Market & Growth Analysis
|
||||
|
||||
| Framework | Description | Best For |
|
||||
|-----------|-------------|----------|
|
||||
| **STP Analysis** | Segmentation, Targeting, Positioning | Market segmentation, target market selection, brand positioning |
|
||||
| **BCG Matrix (Growth-Share Matrix)** | Stars, Cash Cows, Question Marks, Dogs | Product portfolio management, resource allocation decisions |
|
||||
| **Ansoff Matrix** | Market penetration, market development, product development, diversification | Growth strategy selection |
|
||||
| **Product Life Cycle (PLC)** | Introduction, growth, maturity, decline | Product strategy formulation, market timing decisions |
|
||||
| **TAM-SAM-SOM** | Total / Serviceable / Obtainable Market | Market sizing, opportunity quantification |
|
||||
| **Technology Adoption Lifecycle** | Innovators → Early Adopters → Early Majority → Late Majority → Laggards | Emerging technology/category penetration analysis |
|
||||
|
||||
#### Consumer & Behavioral Analysis
|
||||
|
||||
| Framework | Description | Best For |
|
||||
|-----------|-------------|----------|
|
||||
| **Consumer Decision Journey** | Awareness → Consideration → Evaluation → Purchase → Loyalty | Consumer behavior path mapping, touchpoint optimization |
|
||||
| **AARRR Funnel (Pirate Metrics)** | Acquisition, Activation, Retention, Revenue, Referral | User growth analysis, conversion rate optimization |
|
||||
| **RFM Model** | Recency, Frequency, Monetary | Customer value segmentation, precision marketing |
|
||||
| **Maslow's Hierarchy of Needs** | Physiological → Safety → Social → Esteem → Self-actualization | Consumer psychology analysis, product value proposition |
|
||||
| **Jobs-to-be-Done (JTBD)** | The "job" a user needs to accomplish in a specific context | Demand insight, product innovation direction |
|
||||
|
||||
#### Financial & Valuation Analysis
|
||||
|
||||
| Framework | Description | Best For |
|
||||
|-----------|-------------|----------|
|
||||
| **DuPont Analysis** | ROE = Net Profit Margin × Asset Turnover × Equity Multiplier | Profitability decomposition, financial health diagnosis |
|
||||
| **DCF (Discounted Cash Flow)** | Free cash flow discounting | Enterprise/project valuation |
|
||||
| **Comparable Company Analysis** | PE, PB, PS, EV/EBITDA multiples comparison | Relative valuation, peer benchmarking |
|
||||
| **EVA (Economic Value Added)** | After-tax operating profit - Cost of capital | Value creation capability assessment |
|
||||
|
||||
#### Competitive & Strategic Positioning
|
||||
|
||||
| Framework | Description | Best For |
|
||||
|-----------|-------------|----------|
|
||||
| **Benchmarking** | Key performance indicator item-by-item comparison | Competitor gap analysis, best practice identification |
|
||||
| **Strategic Group Mapping** | Cluster competitors along two key dimensions | Competitive landscape visualization, white-space identification |
|
||||
| **Value Chain Analysis** | Primary activities + support activities value decomposition | Cost advantage sources, differentiation opportunity identification |
|
||||
| **Blue Ocean Strategy** | Value curve, four-action framework (Eliminate-Reduce-Raise-Create) | Differentiated innovation, new market space creation |
|
||||
| **Perceptual Mapping** | Plot brand positions along two consumer-perceived dimensions | Brand positioning analysis, market gap discovery |
|
||||
|
||||
#### Industry & Supply Chain Analysis
|
||||
|
||||
| Framework | Description | Best For |
|
||||
|-----------|-------------|----------|
|
||||
| **Industry Value Chain** | Upstream → Midstream → Downstream decomposition | Industry structure understanding, profit distribution analysis |
|
||||
| **Gartner Hype Cycle** | Technology Trigger → Peak of Inflated Expectations → Trough of Disillusionment → Slope of Enlightenment → Plateau of Productivity | Emerging technology maturity assessment |
|
||||
| **GE-McKinsey Matrix** | Industry Attractiveness × Competitive Strength | Business portfolio prioritization, investment decisions |
|
||||
|
||||
#### Selection Principles
|
||||
|
||||
1. **Domain-First**: Based on the domain identified in Step 1.1, select **2-4** most relevant frameworks from the toolkit above
|
||||
2. **Complementary**: Choose complementary rather than overlapping frameworks (e.g., macro-level with PESTEL + micro-level with Porter's Five Forces)
|
||||
3. **Depth over Breadth**: Better to deeply apply 2 frameworks than superficially stack 6
|
||||
4. **Data-Feasible**: Selected frameworks must be supportable by downstream data collection skills — if the data required by a framework cannot be reasonably obtained, downgrade or substitute
|
||||
5. **Explicit Mapping**: In the chapter skeleton, explicitly annotate which framework each chapter uses and how it is applied
|
||||
|
||||
#### Framework Selection Output Format
|
||||
|
||||
```markdown
|
||||
## Framework Selection
|
||||
|
||||
| Chapter | Selected Framework(s) | Application |
|
||||
|---------|----------------------|-------------|
|
||||
| Market Size & Growth Trends | TAM-SAM-SOM + Product Life Cycle | TAM-SAM-SOM to quantify market space, PLC to determine market stage |
|
||||
| Competitive Landscape Assessment | Porter's Five Forces + Strategic Group Mapping | Five Forces to assess industry competition intensity, Group Mapping to visualize competitive positioning |
|
||||
| Consumer Profiling | RFM + Consumer Decision Journey | RFM to segment customer value, Decision Journey to identify key conversion nodes |
|
||||
| Brand Strategy Recommendations | SWOT + Blue Ocean Strategy | SWOT to summarize overall landscape, Blue Ocean to guide differentiation direction |
|
||||
```
|
||||
|
||||
### Step 1.3: Design Chapter Skeleton
|
||||
|
||||
Produce a hierarchical chapter structure. Each chapter must include:
|
||||
|
||||
1. **Chapter Title** — Professional, concise, subject-based (follow titling constraints in Formatting section)
|
||||
2. **Analysis Objective** — What this chapter aims to reveal
|
||||
3. **Analysis Logic** — The reasoning chain or framework (must reference the frameworks selected in Step 1.2)
|
||||
4. **Core Hypothesis** — Preliminary hypotheses to be validated or refuted by data
|
||||
|
||||
#### Chapter Skeleton Output Format
|
||||
|
||||
```markdown
|
||||
## Analysis Framework
|
||||
|
||||
### Chapter 1: [Title]
|
||||
- **Analysis Objective**: [This chapter aims to...]
|
||||
- **Analysis Logic**: [Framework or reasoning chain used]
|
||||
- **Core Hypothesis**: [Hypotheses to validate]
|
||||
- **Data Requirements**: (see Step 1.4)
|
||||
- **Visualization Plan**: (see Step 1.5)
|
||||
|
||||
### Chapter 2: [Title]
|
||||
...
|
||||
```
|
||||
|
||||
### Step 1.4: Define Data Query Requirements Per Chapter
|
||||
|
||||
For each chapter, specify **exactly what data needs to be collected**. This is the bridge to downstream data collection skills.
|
||||
|
||||
Each data requirement entry must include:
|
||||
|
||||
| Field | Description |
|
||||
|-------|-------------|
|
||||
| **Data Metric** | The specific metric or data point needed (e.g., "China skincare market size 2020-2025 (in billion CNY)") |
|
||||
| **Data Type** | Quantitative, Qualitative, or Mixed |
|
||||
| **Suggested Sources** | Suggested source categories: Industry reports, financial statements, government statistics, social media, e-commerce platforms, survey data, news |
|
||||
| **Search Keywords** | Suggested search queries for data collection agents |
|
||||
| **Priority** | P0 (Required) / P1 (Important) / P2 (Supplementary) |
|
||||
| **Time Range** | The time period the data should cover |
|
||||
|
||||
#### Data Requirements Output Format (per chapter)
|
||||
|
||||
```markdown
|
||||
#### Data Requirements
|
||||
|
||||
| # | Data Metric | Data Type | Suggested Sources | Search Keywords | Priority | Time Range |
|
||||
|---|-------------|-----------|-------------------|-----------------|----------|------------|
|
||||
| 1 | Market size (billion CNY) | Quantitative | Industry reports, government statistics | "China skincare market size 2024" | P0 | 2020-2025 |
|
||||
| 2 | CAGR | Quantitative | Industry reports | "skincare CAGR growth rate" | P0 | 2020-2025 |
|
||||
| 3 | Sub-category share | Quantitative | E-commerce platforms, industry reports | "skincare category share cream serum sunscreen" | P1 | Latest |
|
||||
| 4 | Policy & regulatory updates | Qualitative | Government announcements, news | "cosmetics regulation 2024" | P2 | Past 1 year |
|
||||
```
|
||||
|
||||
### Step 1.5: Define Visualization & Content Structure Per Chapter
|
||||
|
||||
For each chapter, specify the **planned visualization** and **content structure** for the final report:
|
||||
|
||||
| Field | Description |
|
||||
|-------|-------------|
|
||||
| **Visualization Type** | Chart type: Line chart, bar chart, pie chart, scatter plot, radar chart, heatmap, Sankey diagram, comparison table, etc. |
|
||||
| **Visualization Title** | Descriptive title for the chart |
|
||||
| **Visualization Data Mapping** | Which data indicators map to X/Y axes or segments |
|
||||
| **Comparison Table Design** | Column headers and comparison dimensions for the data contrast table |
|
||||
| **Argument Structure** | The planned "What → Why → So What" narrative outline |
|
||||
|
||||
#### Visualization Plan Output Format (per chapter)
|
||||
|
||||
```markdown
|
||||
#### Visualization & Content Plan
|
||||
|
||||
**Chart 1**: [Type] — [Title]
|
||||
- X-axis: [Dimension], Y-axis: [Metric]
|
||||
- Data source: Corresponds to Data Requirement #1, #2
|
||||
|
||||
**Comparison Table**:
|
||||
| Dimension | Item A | Item B | Item C |
|
||||
|-----------|--------|--------|--------|
|
||||
|
||||
**Argument Structure**:
|
||||
1. **Observation (What)**: [Surface phenomenon revealed by data]
|
||||
2. **Attribution (Why)**: [Driving factors or underlying causes]
|
||||
3. **Implication (So What)**: [Strategic implications or recommended actions]
|
||||
```
|
||||
|
||||
### Step 1.6: Output Complete Analysis Framework
|
||||
|
||||
Assemble all outputs into a single, structured **Analysis Framework Document**:
|
||||
|
||||
```markdown
|
||||
# [Research Subject] Analysis Framework
|
||||
|
||||
## Research Overview
|
||||
- **Research Subject**: [...]
|
||||
- **Scope**: [Geography, time range, industry segment]
|
||||
- **Analysis Domain**: [Market / Finance / Industry / Brand / Consumer / ...]
|
||||
- **Core Research Questions**: [1-3 key questions]
|
||||
|
||||
## Framework Selection
|
||||
|
||||
| Chapter | Selected Framework(s) | Application |
|
||||
|---------|----------------------|-------------|
|
||||
| ... | ... | ... |
|
||||
|
||||
## Chapter Skeleton
|
||||
|
||||
### 1. [Chapter Title]
|
||||
- **Analysis Objective**: [...]
|
||||
- **Analysis Logic**: [...]
|
||||
- **Core Hypothesis**: [...]
|
||||
|
||||
#### Data Requirements
|
||||
| # | Data Metric | Data Type | Suggested Sources | Search Keywords | Priority | Time Range |
|
||||
|---|-------------|-----------|-------------------|-----------------|----------|------------|
|
||||
| ... | ... | ... | ... | ... | ... | ... |
|
||||
|
||||
#### Visualization & Content Plan
|
||||
[Chart plan + Comparison table design + Argument structure]
|
||||
|
||||
### 2. [Chapter Title]
|
||||
...
|
||||
|
||||
### N. [Chapter Title]
|
||||
...
|
||||
|
||||
## Data Collection Task List
|
||||
[Consolidate all P0/P1 data requirements across chapters into a structured task list for downstream data collection skills to execute]
|
||||
```
|
||||
|
||||
## Phase 1 Quality Checklist
|
||||
|
||||
- [ ] Analysis framework covers all natural dimensions for the identified domain
|
||||
- [ ] 2-4 professional analysis frameworks are selected and explicitly mapped to chapters
|
||||
- [ ] Selected frameworks are complementary (not overlapping) and data-feasible
|
||||
- [ ] Each chapter has clear Analysis Objective, Analysis Logic (referencing chosen framework), and Core Hypothesis
|
||||
- [ ] Data requirements are specific, measurable, and include search keywords
|
||||
- [ ] Every chapter has at least one visualization plan
|
||||
- [ ] Data priorities (P0/P1/P2) are assigned realistically
|
||||
- [ ] The framework is actionable — a data collection agent can execute on the Search Keywords directly
|
||||
- [ ] Data Collection Task List is comprehensive and deduplicated
|
||||
|
||||
---
|
||||
|
||||
# Phase 1→2 Handoff: Data Collection & Chart Generation
|
||||
|
||||
After the analysis framework is generated, it is handed off to **other data collection skills** (e.g., deep-research, data-analysis, web search agents) to:
|
||||
|
||||
1. Execute the **Search Keywords** from each chapter's data requirements
|
||||
2. Collect quantitative data, qualitative insights, and source URLs
|
||||
3. Generate charts based on the **Visualization & Content Plan**
|
||||
4. Return a **Data Package** containing:
|
||||
- **Data Summary**: Raw numbers, metrics, and qualitative findings per chapter
|
||||
- **Chart Files**: Generated chart images with local file paths
|
||||
- **External Search Findings**: Source URLs and summaries for citations
|
||||
|
||||
> **This skill does NOT perform data collection.** It only produces the framework (Phase 1) and the final report (Phase 2).
|
||||
>
|
||||
> **Chart Generation**: If a visualization/charting skill is available (e.g., data-analysis, image-generation), chart generation can be deferred to the beginning of Phase 2 — see Step 2.3.
|
||||
|
||||
---
|
||||
|
||||
# Phase 2: Report Generation
|
||||
|
||||
## Purpose
|
||||
|
||||
Receive the completed **Analysis Framework** and **Data Package** from upstream, and synthesize them into a final consulting-grade report.
|
||||
|
||||
## Phase 2 Inputs
|
||||
|
||||
| Input | Description | Required |
|
||||
|-------|-------------|----------|
|
||||
| **Analysis Framework** | The framework document produced in Phase 1 | Yes |
|
||||
| **Data Summary** | Collected data organized per chapter from the data collection phase | Yes |
|
||||
| **Chart Files** | Local file paths for generated chart images. If not provided, will be generated in Step 2.3 using available visualization skills | Optional |
|
||||
| **External Search Findings** | URLs and summaries for inline citations | Optional |
|
||||
|
||||
## Phase 2 Workflow
|
||||
|
||||
### Step 2.1: Receive and Validate Inputs
|
||||
|
||||
Verify that all required inputs are present:
|
||||
|
||||
1. **Analysis Framework** — Confirm it contains chapter skeleton, data requirements, and visualization plans
|
||||
2. **Data Summary** — Confirm it contains data organized per chapter, cross-reference against P0 requirements
|
||||
3. **Chart Files** — Confirm file paths are valid local paths
|
||||
|
||||
If any P0 data is missing, note it in the report and flag for the user.
|
||||
|
||||
### Step 2.2: Map Report Structure
|
||||
|
||||
Map the final report structure from the Analysis Framework:
|
||||
|
||||
1. **Abstract** — Executive summary with key takeaways
|
||||
2. **Introduction** — Background, objectives, methodology
|
||||
3. **Main Body Chapters (2...N)** — Mapped from the Framework's chapter skeleton
|
||||
4. **Conclusion** — Pure, objective synthesis
|
||||
5. **References** — GB/T 7714-2015 formatted references
|
||||
|
||||
### Step 2.3: Generate Chapter Charts (Pre-Report Visualization)
|
||||
|
||||
Before writing the report, generate all planned charts from the Analysis Framework's **Visualization & Content Plan**. This step ensures every sub-chapter has its "Visual Anchor" ready before narrative writing begins.
|
||||
|
||||
#### When to Execute This Step
|
||||
|
||||
- **Chart Files already provided**: Skip this step — proceed directly to Step 2.4.
|
||||
- **Chart Files NOT provided but a visualization skill is available**: Execute this step to generate all charts first.
|
||||
- **No Chart Files and no visualization skill available**: Skip this step — use comparison tables as the primary visual anchor in Step 2.4, and note the absence of charts.
|
||||
|
||||
#### Chart Generation Workflow
|
||||
|
||||
1. **Extract Chart Tasks**: Parse all `Visualization & Content Plan` entries from the Analysis Framework to build a chart generation task list:
|
||||
|
||||
| # | Chapter | Chart Type | Chart Title | Data Mapping | Data Source |
|
||||
|---|---------|------------|-------------|--------------|-------------|
|
||||
| 1 | 2.1 | Line chart | Market Size Trend 2020-2025 | X: Year, Y: Market Size (billion CNY) | Data Requirement #1, #2 |
|
||||
| 2 | 3.1 | Pie chart | Consumer Age Distribution | Segments: Age groups, Values: Share % | Data Requirement #5 |
|
||||
| ... | ... | ... | ... | ... | ... |
|
||||
|
||||
2. **Prepare Chart Data**: For each chart task, extract the corresponding data points from the **Data Summary**.
|
||||
> **CRITICAL**: Use ONLY the numbers provided in the Data Summary. Do NOT invent or "smooth" data to make charts look better. If data points are missing, the chart must reflect that reality (e.g., broken line or missing bar), or the chart type must be adjusted.
|
||||
|
||||
3. **Delegate to Visualization Skill**: Invoke the available visualization/charting skill (e.g., `data-analysis`) for each chart task with:
|
||||
- Chart type and title
|
||||
- Structured data
|
||||
- Axis labels and formatting preferences
|
||||
- Output file path convention: `charts/chapter_{N}_{chart_index}.png`
|
||||
|
||||
4. **Collect Chart File Paths**: Record all generated chart file paths for embedding in Step 2.4:
|
||||
|
||||
```markdown
|
||||
## Generated Charts
|
||||
| # | Chapter | Chart Title | File Path |
|
||||
|---|---------|-------------|-----------|
|
||||
| 1 | 2.1 | Market Size Trend 2020-2025 | charts/chapter_2_1.png |
|
||||
| 2 | 3.1 | Consumer Age Distribution | charts/chapter_3_1.png |
|
||||
```
|
||||
|
||||
5. **Validate**: Confirm all P0-priority charts have been generated. If any chart generation fails, note it and fall back to comparison tables for that sub-chapter.
|
||||
|
||||
> **Principle**: Complete ALL chart generation before starting report writing. This ensures a consistent visual narrative and avoids interleaving generation with writing.
|
||||
|
||||
### Step 2.4: Write the Report
|
||||
|
||||
For each sub-chapter, follow the **"Visual Anchor → Data Contrast → Integrated Analysis"** flow:
|
||||
|
||||
1. **Visual Evidence Block**: Embed charts using `` — use the file paths collected in Step 2.3
|
||||
2. **Data Contrast Table**: Create a Markdown comparison table for key metrics
|
||||
> **Source Rule**: Every number in the table must come from the Data Summary. No hallucinations.
|
||||
3. **Integrated Narrative Analysis**: Write analytical text following "What → Why → So What"
|
||||
> **Narrative Rule**: Narrative must explain the *provided* data. Do not make claims unsupported by the inputs.
|
||||
|
||||
Each sub-chapter must end with a robust analytical paragraph (min. 200 words) that:
|
||||
- Synthesizes conflicting or reinforcing data points
|
||||
- Reveals the underlying user tension or opportunity
|
||||
- Optionally ends with a punchy "One-Liner Truth" in a blockquote (`>`)
|
||||
|
||||
### Step 2.5: Final Structure Self-Check
|
||||
|
||||
Before outputting, confirm the report contains **all sections in order**:
|
||||
|
||||
```
|
||||
Abstract → 1. Introduction → 2...N. Body Chapters → N+1. Conclusion → N+2. References
|
||||
```
|
||||
|
||||
Additionally verify:
|
||||
- All charts generated in Step 2.3 are embedded in the correct sub-chapters
|
||||
- Chart file paths in `` references are valid
|
||||
- Sub-chapters without charts have comparison tables as visual anchors
|
||||
|
||||
The report **MUST NOT** stop after the Conclusion — it **MUST** include References as the final section.
|
||||
|
||||
## Formatting & Tone Standards
|
||||
|
||||
### Consulting Voice
|
||||
- **Tone**: McKinsey/BCG — Authoritative, Objective, Professional
|
||||
- **Language**: All headings and content in the language specified by `output_locale`
|
||||
- **Number Formatting**: Use English commas for thousands separators (`1,000` not `1，000`)
|
||||
- **Data emphasis**: **Bold** important viewpoints and key numbers
|
||||
|
||||
### Titling Constraints
|
||||
- **Numbering**: Use standard numbering (`1.`, `1.1`) directly followed by the title
|
||||
- **Forbidden Prefixes**: Do NOT use "Chapter", "Part", "Section" as prefixes
|
||||
- **Allowed Tone Words**: Analysis, Profiling, Overview, Insights, Assessment
|
||||
- **Forbidden Words**: "Decoding", "DNA", "Secrets", "Mindscape", "Solar System", "Unlocking"
|
||||
|
||||
### Sub-Chapter Conclusions
|
||||
- **Requirement**: End each sub-chapter with a robust analytical paragraph (min. 200 words).
|
||||
- **Narrative Flow**: This paragraph must look like a natural continuation of the text. It must synthesize the section's findings into a strategic judgment.
|
||||
- **Content Logic**:
|
||||
1. Synthesize the conflicting or reinforcing data points above.
|
||||
2. Reveal the *underlying* user tension or opportunity.
|
||||
3. Key Insight: **Optional**: Only if you have a concise, punchy "One-Liner Truth", place it at the very end using a **Blockquote** (`>`) to anchor the section.
|
||||
|
||||
### Insight Depth (The "So What" Chain)
|
||||
|
||||
Every insight must connect **Data → User Psychology → Strategy Implication**:
|
||||
|
||||
```
|
||||
❌ Bad: "Females are 60%. Strategy: Target females."
|
||||
|
||||
✅ Good: "Females constitute 60% with a high TGI of 180. **This suggests**
|
||||
the purchase decision is driven by aesthetic and social validation
|
||||
rather than pure utility. **Consequently**, media spend should pivot
|
||||
towards visual-heavy platforms (e.g., RED/Instagram) to maximize CTR,
|
||||
treating male audiences only as a secondary gift-giving segment."
|
||||
```
|
||||
|
||||
### References
|
||||
- **Inline**: Use markdown links for sources (e.g. `[Source Title](URL)`) when using External Search Findings
|
||||
- **References section**: Formatted strictly per **GB/T 7714-2015**
|
||||
|
||||
### Markdown Rules
|
||||
- **Immediate Start**: Begin directly with `# Report Title` — no introductory text
|
||||
- **No Separators**: Do NOT use horizontal rules (`---`)
|
||||
|
||||
## Report Structure Template
|
||||
|
||||
```markdown
|
||||
# [Report Title]
|
||||
|
||||
## Abstract
|
||||
[Executive summary with key takeaways]
|
||||
|
||||
## 1. Introduction
|
||||
[Background, objectives, methodology]
|
||||
|
||||
## 2. [Body Chapter Title]
|
||||
### 2.1 [Sub-chapter Title]
|
||||
|
||||
|
||||
| Metric | Brand A | Brand B |
|
||||
|--------|---------|--------|
|
||||
| ... | ... | ... |
|
||||
|
||||
[Integrated narrative analysis: What → Why → So What, min. 200 words]
|
||||
|
||||
> [Optional: One-liner strategic truth]
|
||||
|
||||
### 2.2 [Sub-chapter Title]
|
||||
...
|
||||
|
||||
## N+1. Conclusion
|
||||
[Pure objective synthesis, NO bullet points, neutral tone]
|
||||
[Para 1: The fundamental nature of the group/market]
|
||||
[Para 2: Core tension or behavior pattern]
|
||||
[Final: One or two sentences stating the objective truth]
|
||||
|
||||
## N+2. References
|
||||
[1] Author. Title[EB/OL]. URL, Date.
|
||||
[2] ...
|
||||
```
|
||||
|
||||
## Complete Example
|
||||
|
||||
### Phase 1 Example: Framework Generation
|
||||
|
||||
User provides: Research subject "Gen-Z Skincare Market Analysis"
|
||||
|
||||
**Phase 1 output (Analysis Framework):**
|
||||
|
||||
```markdown
|
||||
# Gen-Z Skincare Market Analysis Framework
|
||||
|
||||
## Research Overview
|
||||
- **Research Subject**: Gen-Z Skincare Market Deep Analysis
|
||||
- **Scope**: China market, 2020-2025, consumers aged 18-27
|
||||
- **Analysis Domain**: Market Analysis + Consumer Insights
|
||||
- **Core Research Questions**:
|
||||
1. What is the size and growth momentum of the Gen-Z skincare market?
|
||||
2. What is unique about Gen-Z consumer skincare behavior patterns?
|
||||
3. How can brands effectively reach and convert Gen-Z consumers?
|
||||
|
||||
## Chapter Skeleton
|
||||
|
||||
### 1. Market Size & Growth Trends
|
||||
- **Analysis Objective**: Quantify Gen-Z skincare market size and identify growth drivers
|
||||
- **Analysis Logic**: Total market → Segmentation → Growth rate → Driver decomposition
|
||||
- **Core Hypothesis**: Gen-Z is becoming the core engine of skincare consumption growth
|
||||
|
||||
#### Data Requirements
|
||||
| # | Data Metric | Data Type | Suggested Sources | Search Keywords | Priority | Time Range |
|
||||
|---|-------------|-----------|-------------------|-----------------|----------|------------|
|
||||
| 1 | China skincare market total size | Quantitative | Industry reports | "China skincare market size 2024 2025" | P0 | 2020-2025 |
|
||||
| 2 | Gen-Z skincare spending share | Quantitative | Industry reports, e-commerce platforms | "Gen-Z skincare spending share youth" | P0 | Latest |
|
||||
|
||||
#### Visualization & Content Plan
|
||||
**Chart 1**: Line chart — China Skincare Market Size Trend 2020-2025
|
||||
**Argument Structure**:
|
||||
1. What: Quantified status of market size and Gen-Z share
|
||||
2. Why: Consumption upgrade, ingredient-conscious consumers, social media driven
|
||||
3. So What: Brands should prioritize building youth-oriented product lines
|
||||
|
||||
### 2. Consumer Profiling & Behavioral Insights
|
||||
...
|
||||
|
||||
## Data Collection Task List
|
||||
[Consolidated P0/P1 tasks]
|
||||
```
|
||||
|
||||
### Phase 2 Example: Report Generation
|
||||
|
||||
After data collection, user provides: Analysis Framework + Data Summary with brand metrics + chart file paths.
|
||||
|
||||
**Phase 2 output (Final Report) follows this flow:**
|
||||
|
||||
1. Start with `# Gen-Z Skincare Market Deep Analysis Report`
|
||||
2. Abstract — 3-5 key takeaways in executive summary form
|
||||
3. 1. Introduction — Market context, research scope, data sources
|
||||
4. 2. Market Size & Growth Trend Analysis — Embed trend charts, comparison tables, strategic narrative
|
||||
5. 3. Consumer Profiling & Behavioral Insights — Demographics, purchase drivers, "So What" analysis
|
||||
6. 4. Brand Competitive Landscape Assessment — Brand positioning, share analysis, competitive dynamics
|
||||
7. 5. Marketing Strategy & Channel Insights — Channel effectiveness, content strategy implications
|
||||
8. 6. Conclusion — Objective synthesis in flowing prose (no bullets)
|
||||
9. 7. References — GB/T 7714-2015 formatted list
|
||||
|
||||
---
|
||||
|
||||
## Quality Checklists
|
||||
|
||||
### Phase 1 Quality Checklist (Analysis Framework)
|
||||
|
||||
- [ ] Framework covers all natural analytical dimensions for the identified domain
|
||||
- [ ] Each chapter has clear Analysis Objective, Analysis Logic, and Core Hypothesis
|
||||
- [ ] Data requirements are specific, measurable, and include actionable Search Keywords
|
||||
- [ ] Every chapter has at least one visualization plan with chart type and data mapping
|
||||
- [ ] Data priorities (P0/P1/P2) are assigned — P0 items are essential for core arguments
|
||||
- [ ] Data Collection Task List is comprehensive, deduplicated, and ready for downstream execution
|
||||
- [ ] Framework adapts to the correct domain (market/finance/industry/consumer/etc.)
|
||||
|
||||
### Phase 2 Quality Checklist (Final Report)
|
||||
|
||||
- [ ] **NO HALLUCINATION**: All numbers and charts are verified against the input Data Summary
|
||||
- [ ] All planned charts generated before report writing (Step 2.3 completed first)
|
||||
- [ ] All sections present in correct order (Abstract → Introduction → Body → Conclusion → References)
|
||||
- [ ] Every sub-chapter follows "Visual Anchor → Data Contrast → Integrated Analysis"
|
||||
- [ ] Every sub-chapter ends with a min. 200-word analytical paragraph
|
||||
- [ ] All insights follow the "Data → User Psychology → Strategy Implication" chain
|
||||
- [ ] All headings use proper numbering (no "Chapter/Part/Section" prefixes)
|
||||
- [ ] Charts are embedded with `` syntax
|
||||
- [ ] Numbers use English commas for thousands separators
|
||||
- [ ] Inline references use markdown links where applicable
|
||||
- [ ] References section follows GB/T 7714-2015
|
||||
- [ ] No horizontal rules (`---`) in the document
|
||||
- [ ] Conclusion uses flowing prose — no bullet points
|
||||
- [ ] Report starts directly with `#` title — no preamble
|
||||
- [ ] Missing P0 data is explicitly flagged in the report
|
||||
|
||||
## Output Format
|
||||
|
||||
- **Phase 1**: Output the complete Analysis Framework in **Markdown** format
|
||||
- **Phase 2**: Output the complete Report in **Markdown** format
|
||||
|
||||
## Settings
|
||||
|
||||
```
|
||||
output_locale = zh_CN # configurable per user request
|
||||
reasoning_locale = en
|
||||
```
|
||||
|
||||
## Notes
|
||||
|
||||
- This skill operates in **two phases** of a multi-step agentic workflow:
|
||||
- **Phase 1** produces the analysis framework and data collection requirements
|
||||
- **Data collection** is performed by other skills (deep-research, data-analysis, etc.)
|
||||
- **Phase 2** receives the collected data and produces the final report
|
||||
- Dynamic titling: **Rewrite** topics from the Framework into professional, concise subject-based headers
|
||||
- The Conclusion section must contain **NO** detailed recommendations — those belong in the preceding body chapters
|
||||
- **ZERO HALLUCINATION POLICY**: Each statement, chart, and number in the report must be supported by data points from the input Data Summary. If data is missing, admit it.
|
||||
- **Traceability**: If requested, you must be able to point to the specific line in the Data Summary or External Search Findings that supports a claim.
|
||||
- The framework should adapt its analytical dimensions and depth to the specific domain (financial analysis uses different frameworks than consumer insights)
|
||||
- When the research subject is ambiguous, default to the broadest reasonable scope and note assumptions
|
||||
248
deer-flow/skills/public/data-analysis/SKILL.md
Normal file
248
deer-flow/skills/public/data-analysis/SKILL.md
Normal file
@@ -0,0 +1,248 @@
|
||||
---
|
||||
name: data-analysis
|
||||
description: Use this skill when the user uploads Excel (.xlsx/.xls) or CSV files and wants to perform data analysis, generate statistics, create summaries, pivot tables, SQL queries, or any form of structured data exploration. Supports multi-sheet Excel workbooks, aggregation, filtering, joins, and exporting results to CSV/JSON/Markdown.
|
||||
---
|
||||
|
||||
# Data Analysis Skill
|
||||
|
||||
## Overview
|
||||
|
||||
This skill analyzes user-uploaded Excel/CSV files using DuckDB — an in-process analytical SQL engine. It supports schema inspection, SQL-based querying, statistical summaries, and result export, all through a single Python script.
|
||||
|
||||
## Core Capabilities
|
||||
|
||||
- Inspect Excel/CSV file structure (sheets, columns, types, row counts)
|
||||
- Execute arbitrary SQL queries against uploaded data
|
||||
- Generate statistical summaries (mean, median, stddev, percentiles, nulls)
|
||||
- Support multi-sheet Excel workbooks (each sheet becomes a table)
|
||||
- Export query results to CSV, JSON, or Markdown
|
||||
- Handle large files efficiently with DuckDB's columnar engine
|
||||
|
||||
## Workflow
|
||||
|
||||
### Step 1: Understand Requirements
|
||||
|
||||
When a user uploads data files and requests analysis, identify:
|
||||
|
||||
- **File location**: Path(s) to uploaded Excel/CSV files under `/mnt/user-data/uploads/`
|
||||
- **Analysis goal**: What insights the user wants (summary, filtering, aggregation, comparison, etc.)
|
||||
- **Output format**: How results should be presented (table, CSV export, JSON, etc.)
|
||||
- You don't need to check the folder under `/mnt/user-data`
|
||||
|
||||
### Step 2: Inspect File Structure
|
||||
|
||||
First, inspect the uploaded file to understand its schema:
|
||||
|
||||
```bash
|
||||
python /mnt/skills/public/data-analysis/scripts/analyze.py \
|
||||
--files /mnt/user-data/uploads/data.xlsx \
|
||||
--action inspect
|
||||
```
|
||||
|
||||
This returns:
|
||||
- Sheet names (for Excel) or filename (for CSV)
|
||||
- Column names, data types, and non-null counts
|
||||
- Row count per sheet/file
|
||||
- Sample data (first 5 rows)
|
||||
|
||||
### Step 3: Perform Analysis
|
||||
|
||||
Based on the schema, construct SQL queries to answer the user's questions.
|
||||
|
||||
#### Run SQL Query
|
||||
|
||||
```bash
|
||||
python /mnt/skills/public/data-analysis/scripts/analyze.py \
|
||||
--files /mnt/user-data/uploads/data.xlsx \
|
||||
--action query \
|
||||
--sql "SELECT category, COUNT(*) as count, AVG(amount) as avg_amount FROM Sheet1 GROUP BY category ORDER BY count DESC"
|
||||
```
|
||||
|
||||
#### Generate Statistical Summary
|
||||
|
||||
```bash
|
||||
python /mnt/skills/public/data-analysis/scripts/analyze.py \
|
||||
--files /mnt/user-data/uploads/data.xlsx \
|
||||
--action summary \
|
||||
--table Sheet1
|
||||
```
|
||||
|
||||
This returns for each numeric column: count, mean, std, min, 25%, 50%, 75%, max, null_count.
|
||||
For string columns: count, unique, top value, frequency, null_count.
|
||||
|
||||
#### Export Results
|
||||
|
||||
```bash
|
||||
python /mnt/skills/public/data-analysis/scripts/analyze.py \
|
||||
--files /mnt/user-data/uploads/data.xlsx \
|
||||
--action query \
|
||||
--sql "SELECT * FROM Sheet1 WHERE amount > 1000" \
|
||||
--output-file /mnt/user-data/outputs/filtered-results.csv
|
||||
```
|
||||
|
||||
Supported output formats (auto-detected from extension):
|
||||
- `.csv` — Comma-separated values
|
||||
- `.json` — JSON array of records
|
||||
- `.md` — Markdown table
|
||||
|
||||
### Parameters
|
||||
|
||||
| Parameter | Required | Description |
|
||||
|-----------|----------|-------------|
|
||||
| `--files` | Yes | Space-separated paths to Excel/CSV files |
|
||||
| `--action` | Yes | One of: `inspect`, `query`, `summary` |
|
||||
| `--sql` | For `query` | SQL query to execute |
|
||||
| `--table` | For `summary` | Table/sheet name to summarize |
|
||||
| `--output-file` | No | Path to export results (CSV/JSON/MD) |
|
||||
|
||||
> [!NOTE]
|
||||
> Do NOT read the Python file, just call it with the parameters.
|
||||
|
||||
## Table Naming Rules
|
||||
|
||||
- **Excel files**: Each sheet becomes a table named after the sheet (e.g., `Sheet1`, `Sales`, `Revenue`)
|
||||
- **CSV files**: Table name is the filename without extension (e.g., `data.csv` → `data`)
|
||||
- **Multiple files**: All tables from all files are available in the same query context, enabling cross-file joins
|
||||
- **Special characters**: Sheet/file names with spaces or special characters are auto-sanitized (spaces → underscores). Use double quotes for names that start with numbers or contain special characters, e.g., `"2024_Sales"`
|
||||
|
||||
## Analysis Patterns
|
||||
|
||||
### Basic Exploration
|
||||
```sql
|
||||
-- Row count
|
||||
SELECT COUNT(*) FROM Sheet1
|
||||
|
||||
-- Distinct values in a column
|
||||
SELECT DISTINCT category FROM Sheet1
|
||||
|
||||
-- Value distribution
|
||||
SELECT category, COUNT(*) as cnt FROM Sheet1 GROUP BY category ORDER BY cnt DESC
|
||||
|
||||
-- Date range
|
||||
SELECT MIN(date_col), MAX(date_col) FROM Sheet1
|
||||
```
|
||||
|
||||
### Aggregation & Grouping
|
||||
```sql
|
||||
-- Revenue by category and month
|
||||
SELECT category, DATE_TRUNC('month', order_date) as month,
|
||||
SUM(revenue) as total_revenue
|
||||
FROM Sales
|
||||
GROUP BY category, month
|
||||
ORDER BY month, total_revenue DESC
|
||||
|
||||
-- Top 10 customers by spend
|
||||
SELECT customer_name, SUM(amount) as total_spend
|
||||
FROM Orders GROUP BY customer_name
|
||||
ORDER BY total_spend DESC LIMIT 10
|
||||
```
|
||||
|
||||
### Cross-file Joins
|
||||
```sql
|
||||
-- Join sales with customer info from different files
|
||||
SELECT s.order_id, s.amount, c.customer_name, c.region
|
||||
FROM sales s
|
||||
JOIN customers c ON s.customer_id = c.id
|
||||
WHERE s.amount > 500
|
||||
```
|
||||
|
||||
### Window Functions
|
||||
```sql
|
||||
-- Running total and rank
|
||||
SELECT order_date, amount,
|
||||
SUM(amount) OVER (ORDER BY order_date) as running_total,
|
||||
RANK() OVER (ORDER BY amount DESC) as amount_rank
|
||||
FROM Sales
|
||||
```
|
||||
|
||||
### Pivot-style Analysis
|
||||
```sql
|
||||
-- Pivot: monthly revenue by category
|
||||
SELECT category,
|
||||
SUM(CASE WHEN MONTH(date) = 1 THEN revenue END) as Jan,
|
||||
SUM(CASE WHEN MONTH(date) = 2 THEN revenue END) as Feb,
|
||||
SUM(CASE WHEN MONTH(date) = 3 THEN revenue END) as Mar
|
||||
FROM Sales
|
||||
GROUP BY category
|
||||
```
|
||||
|
||||
## Complete Example
|
||||
|
||||
User uploads `sales_2024.xlsx` (with sheets: `Orders`, `Products`, `Customers`) and asks: "Analyze my sales data — show top products by revenue and monthly trends."
|
||||
|
||||
### Step 1: Inspect the file
|
||||
|
||||
```bash
|
||||
python /mnt/skills/public/data-analysis/scripts/analyze.py \
|
||||
--files /mnt/user-data/uploads/sales_2024.xlsx \
|
||||
--action inspect
|
||||
```
|
||||
|
||||
### Step 2: Top products by revenue
|
||||
|
||||
```bash
|
||||
python /mnt/skills/public/data-analysis/scripts/analyze.py \
|
||||
--files /mnt/user-data/uploads/sales_2024.xlsx \
|
||||
--action query \
|
||||
--sql "SELECT p.product_name, SUM(o.quantity * o.unit_price) as total_revenue, SUM(o.quantity) as total_units FROM Orders o JOIN Products p ON o.product_id = p.id GROUP BY p.product_name ORDER BY total_revenue DESC LIMIT 10"
|
||||
```
|
||||
|
||||
### Step 3: Monthly revenue trends
|
||||
|
||||
```bash
|
||||
python /mnt/skills/public/data-analysis/scripts/analyze.py \
|
||||
--files /mnt/user-data/uploads/sales_2024.xlsx \
|
||||
--action query \
|
||||
--sql "SELECT DATE_TRUNC('month', order_date) as month, SUM(quantity * unit_price) as revenue FROM Orders GROUP BY month ORDER BY month" \
|
||||
--output-file /mnt/user-data/outputs/monthly-trends.csv
|
||||
```
|
||||
|
||||
### Step 4: Statistical summary
|
||||
|
||||
```bash
|
||||
python /mnt/skills/public/data-analysis/scripts/analyze.py \
|
||||
--files /mnt/user-data/uploads/sales_2024.xlsx \
|
||||
--action summary \
|
||||
--table Orders
|
||||
```
|
||||
|
||||
Present results to the user with clear explanations of findings, trends, and actionable insights.
|
||||
|
||||
## Multi-file Example
|
||||
|
||||
User uploads `orders.csv` and `customers.xlsx` and asks: "Which region has the highest average order value?"
|
||||
|
||||
```bash
|
||||
python /mnt/skills/public/data-analysis/scripts/analyze.py \
|
||||
--files /mnt/user-data/uploads/orders.csv /mnt/user-data/uploads/customers.xlsx \
|
||||
--action query \
|
||||
--sql "SELECT c.region, AVG(o.amount) as avg_order_value, COUNT(*) as order_count FROM orders o JOIN Customers c ON o.customer_id = c.id GROUP BY c.region ORDER BY avg_order_value DESC"
|
||||
```
|
||||
|
||||
## Output Handling
|
||||
|
||||
After analysis:
|
||||
|
||||
- Present query results directly in conversation as formatted tables
|
||||
- For large results, export to file and share via `present_files` tool
|
||||
- Always explain findings in plain language with key takeaways
|
||||
- Suggest follow-up analyses when patterns are interesting
|
||||
- Offer to export results if the user wants to keep them
|
||||
|
||||
## Caching
|
||||
|
||||
The script automatically caches loaded data to avoid re-parsing files on every call:
|
||||
|
||||
- On first load, files are parsed and stored in a persistent DuckDB database under `/mnt/user-data/workspace/.data-analysis-cache/`
|
||||
- The cache key is a SHA256 hash of all input file contents — if files change, a new cache is created
|
||||
- Subsequent calls with the same files will use the cached database directly (near-instant startup)
|
||||
- Cache is transparent — no extra parameters needed
|
||||
|
||||
This is especially useful when running multiple queries against the same data files (inspect → query → summary).
|
||||
|
||||
## Notes
|
||||
|
||||
- DuckDB supports full SQL including window functions, CTEs, subqueries, and advanced aggregations
|
||||
- Excel date columns are automatically parsed; use DuckDB date functions (`DATE_TRUNC`, `EXTRACT`, etc.)
|
||||
- For very large files (100MB+), DuckDB handles them efficiently without loading everything into memory
|
||||
- Column names with spaces are accessible using double quotes: `"Column Name"`
|
||||
566
deer-flow/skills/public/data-analysis/scripts/analyze.py
Normal file
566
deer-flow/skills/public/data-analysis/scripts/analyze.py
Normal file
@@ -0,0 +1,566 @@
|
||||
"""
|
||||
Data Analysis Script using DuckDB.
|
||||
|
||||
Analyzes Excel (.xlsx/.xls) and CSV files using DuckDB's in-process SQL engine.
|
||||
Supports schema inspection, SQL queries, statistical summaries, and result export.
|
||||
"""
|
||||
|
||||
import argparse
|
||||
import hashlib
|
||||
import json
|
||||
import logging
|
||||
import os
|
||||
import re
|
||||
import subprocess
|
||||
import sys
|
||||
import tempfile
|
||||
|
||||
logging.basicConfig(level=logging.INFO, format="%(message)s")
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
try:
|
||||
import duckdb
|
||||
except ImportError:
|
||||
logger.error("duckdb is not installed. Installing...")
|
||||
subprocess.run([sys.executable, "-m", "pip", "install", "duckdb", "openpyxl", "-q"], check=True)
|
||||
import duckdb
|
||||
|
||||
try:
|
||||
import openpyxl # noqa: F401
|
||||
except ImportError:
|
||||
subprocess.run([sys.executable, "-m", "pip", "install", "openpyxl", "-q"], check=True)
|
||||
|
||||
# Cache directory for persistent DuckDB databases
|
||||
CACHE_DIR = os.path.join(tempfile.gettempdir(), ".data-analysis-cache")
|
||||
TABLE_MAP_SUFFIX = ".table_map.json"
|
||||
|
||||
|
||||
def compute_files_hash(files: list[str]) -> str:
|
||||
"""Compute a combined SHA256 hash of all input files for cache key."""
|
||||
hasher = hashlib.sha256()
|
||||
for file_path in sorted(files):
|
||||
try:
|
||||
with open(file_path, "rb") as f:
|
||||
while chunk := f.read(8192):
|
||||
hasher.update(chunk)
|
||||
except OSError:
|
||||
# Include path as fallback if file can't be read
|
||||
hasher.update(file_path.encode())
|
||||
return hasher.hexdigest()
|
||||
|
||||
|
||||
def get_cache_db_path(files_hash: str) -> str:
|
||||
"""Get the path to the cached DuckDB database file."""
|
||||
os.makedirs(CACHE_DIR, exist_ok=True)
|
||||
return os.path.join(CACHE_DIR, f"{files_hash}.duckdb")
|
||||
|
||||
|
||||
def get_table_map_path(files_hash: str) -> str:
|
||||
"""Get the path to the cached table map JSON file."""
|
||||
return os.path.join(CACHE_DIR, f"{files_hash}{TABLE_MAP_SUFFIX}")
|
||||
|
||||
|
||||
def save_table_map(files_hash: str, table_map: dict[str, str]) -> None:
|
||||
"""Save table map to a JSON file alongside the cached DB."""
|
||||
path = get_table_map_path(files_hash)
|
||||
with open(path, "w", encoding="utf-8") as f:
|
||||
json.dump(table_map, f, ensure_ascii=False)
|
||||
|
||||
|
||||
def load_table_map(files_hash: str) -> dict[str, str] | None:
|
||||
"""Load table map from cache. Returns None if not found."""
|
||||
path = get_table_map_path(files_hash)
|
||||
if not os.path.exists(path):
|
||||
return None
|
||||
try:
|
||||
with open(path, "r", encoding="utf-8") as f:
|
||||
return json.load(f)
|
||||
except Exception:
|
||||
return None
|
||||
|
||||
|
||||
def sanitize_table_name(name: str) -> str:
|
||||
"""Sanitize a sheet/file name into a valid SQL table name."""
|
||||
sanitized = re.sub(r"[^\w]", "_", name)
|
||||
if sanitized and sanitized[0].isdigit():
|
||||
sanitized = f"t_{sanitized}"
|
||||
return sanitized
|
||||
|
||||
|
||||
def load_files(con: duckdb.DuckDBPyConnection, files: list[str]) -> dict[str, str]:
|
||||
"""
|
||||
Load Excel/CSV files into DuckDB tables.
|
||||
|
||||
Returns a mapping of original_name -> sanitized_table_name.
|
||||
"""
|
||||
con.execute("INSTALL spatial; LOAD spatial;")
|
||||
table_map: dict[str, str] = {}
|
||||
|
||||
for file_path in files:
|
||||
if not os.path.exists(file_path):
|
||||
logger.error(f"File not found: {file_path}")
|
||||
continue
|
||||
|
||||
ext = os.path.splitext(file_path)[1].lower()
|
||||
|
||||
if ext in (".xlsx", ".xls"):
|
||||
_load_excel(con, file_path, table_map)
|
||||
elif ext == ".csv":
|
||||
_load_csv(con, file_path, table_map)
|
||||
else:
|
||||
logger.warning(f"Unsupported file format: {ext} ({file_path})")
|
||||
|
||||
return table_map
|
||||
|
||||
|
||||
def _load_excel(
|
||||
con: duckdb.DuckDBPyConnection, file_path: str, table_map: dict[str, str]
|
||||
) -> None:
|
||||
"""Load all sheets from an Excel file into DuckDB tables."""
|
||||
import openpyxl
|
||||
|
||||
wb = openpyxl.load_workbook(file_path, read_only=True, data_only=True)
|
||||
sheet_names = wb.sheetnames
|
||||
wb.close()
|
||||
|
||||
for sheet_name in sheet_names:
|
||||
table_name = sanitize_table_name(sheet_name)
|
||||
|
||||
# Handle duplicate table names
|
||||
original_table_name = table_name
|
||||
counter = 1
|
||||
while table_name in table_map.values():
|
||||
table_name = f"{original_table_name}_{counter}"
|
||||
counter += 1
|
||||
|
||||
try:
|
||||
con.execute(
|
||||
f"""
|
||||
CREATE TABLE "{table_name}" AS
|
||||
SELECT * FROM st_read(
|
||||
'{file_path}',
|
||||
layer = '{sheet_name}',
|
||||
open_options = ['HEADERS=FORCE', 'FIELD_TYPES=AUTO']
|
||||
)
|
||||
"""
|
||||
)
|
||||
table_map[sheet_name] = table_name
|
||||
row_count = con.execute(f'SELECT COUNT(*) FROM "{table_name}"').fetchone()[
|
||||
0
|
||||
]
|
||||
logger.info(
|
||||
f" Loaded sheet '{sheet_name}' -> table '{table_name}' ({row_count} rows)"
|
||||
)
|
||||
except Exception as e:
|
||||
logger.warning(f" Failed to load sheet '{sheet_name}': {e}")
|
||||
|
||||
|
||||
def _load_csv(
|
||||
con: duckdb.DuckDBPyConnection, file_path: str, table_map: dict[str, str]
|
||||
) -> None:
|
||||
"""Load a CSV file into a DuckDB table."""
|
||||
base_name = os.path.splitext(os.path.basename(file_path))[0]
|
||||
table_name = sanitize_table_name(base_name)
|
||||
|
||||
# Handle duplicate table names
|
||||
original_table_name = table_name
|
||||
counter = 1
|
||||
while table_name in table_map.values():
|
||||
table_name = f"{original_table_name}_{counter}"
|
||||
counter += 1
|
||||
|
||||
try:
|
||||
con.execute(
|
||||
f"""
|
||||
CREATE TABLE "{table_name}" AS
|
||||
SELECT * FROM read_csv_auto('{file_path}')
|
||||
"""
|
||||
)
|
||||
table_map[base_name] = table_name
|
||||
row_count = con.execute(f'SELECT COUNT(*) FROM "{table_name}"').fetchone()[0]
|
||||
logger.info(
|
||||
f" Loaded CSV '{base_name}' -> table '{table_name}' ({row_count} rows)"
|
||||
)
|
||||
except Exception as e:
|
||||
logger.warning(f" Failed to load CSV '{base_name}': {e}")
|
||||
|
||||
|
||||
def action_inspect(con: duckdb.DuckDBPyConnection, table_map: dict[str, str]) -> str:
|
||||
"""Inspect the schema of all loaded tables."""
|
||||
output_parts = []
|
||||
|
||||
for original_name, table_name in table_map.items():
|
||||
output_parts.append(f"\n{'=' * 60}")
|
||||
output_parts.append(f'Table: {original_name} (SQL name: "{table_name}")')
|
||||
output_parts.append(f"{'=' * 60}")
|
||||
|
||||
# Get row count
|
||||
row_count = con.execute(f'SELECT COUNT(*) FROM "{table_name}"').fetchone()[0]
|
||||
output_parts.append(f"Rows: {row_count}")
|
||||
|
||||
# Get column info
|
||||
columns = con.execute(f'DESCRIBE "{table_name}"').fetchall()
|
||||
output_parts.append(f"\nColumns ({len(columns)}):")
|
||||
output_parts.append(f"{'Name':<30} {'Type':<15} {'Nullable'}")
|
||||
output_parts.append(f"{'-' * 30} {'-' * 15} {'-' * 8}")
|
||||
for col in columns:
|
||||
col_name, col_type, nullable = col[0], col[1], col[2]
|
||||
output_parts.append(f"{col_name:<30} {col_type:<15} {nullable}")
|
||||
|
||||
# Get non-null counts per column
|
||||
col_names = [col[0] for col in columns]
|
||||
non_null_parts = []
|
||||
for c in col_names:
|
||||
non_null_parts.append(f'COUNT("{c}") as "{c}"')
|
||||
non_null_sql = f'SELECT {", ".join(non_null_parts)} FROM "{table_name}"'
|
||||
try:
|
||||
non_null_counts = con.execute(non_null_sql).fetchone()
|
||||
output_parts.append(f"\nNon-null counts:")
|
||||
for i, c in enumerate(col_names):
|
||||
output_parts.append(f" {c}: {non_null_counts[i]} / {row_count}")
|
||||
except Exception:
|
||||
pass
|
||||
|
||||
# Sample data (first 5 rows)
|
||||
output_parts.append(f"\nSample data (first 5 rows):")
|
||||
try:
|
||||
sample = con.execute(f'SELECT * FROM "{table_name}" LIMIT 5').fetchdf()
|
||||
output_parts.append(sample.to_string(index=False))
|
||||
except Exception:
|
||||
sample = con.execute(f'SELECT * FROM "{table_name}" LIMIT 5').fetchall()
|
||||
header = [col[0] for col in columns]
|
||||
output_parts.append(" " + " | ".join(header))
|
||||
for row in sample:
|
||||
output_parts.append(" " + " | ".join(str(v) for v in row))
|
||||
|
||||
result = "\n".join(output_parts)
|
||||
print(result)
|
||||
return result
|
||||
|
||||
|
||||
def action_query(
|
||||
con: duckdb.DuckDBPyConnection,
|
||||
sql: str,
|
||||
table_map: dict[str, str],
|
||||
output_file: str | None = None,
|
||||
) -> str:
|
||||
"""Execute a SQL query and return/export results."""
|
||||
# Replace original sheet/file names with sanitized table names in SQL
|
||||
modified_sql = sql
|
||||
for original_name, table_name in sorted(
|
||||
table_map.items(), key=lambda x: len(x[0]), reverse=True
|
||||
):
|
||||
if original_name != table_name:
|
||||
# Replace occurrences not already quoted
|
||||
modified_sql = re.sub(
|
||||
rf"\b{re.escape(original_name)}\b",
|
||||
f'"{table_name}"',
|
||||
modified_sql,
|
||||
)
|
||||
|
||||
try:
|
||||
result = con.execute(modified_sql)
|
||||
columns = [desc[0] for desc in result.description]
|
||||
rows = result.fetchall()
|
||||
except Exception as e:
|
||||
error_msg = f"SQL Error: {e}\n\nAvailable tables:\n"
|
||||
for orig, tbl in table_map.items():
|
||||
cols = con.execute(f'DESCRIBE "{tbl}"').fetchall()
|
||||
col_names = [c[0] for c in cols]
|
||||
error_msg += f' "{tbl}" ({orig}): {", ".join(col_names)}\n'
|
||||
print(error_msg)
|
||||
return error_msg
|
||||
|
||||
# Format output
|
||||
if output_file:
|
||||
return _export_results(columns, rows, output_file)
|
||||
|
||||
# Print as table
|
||||
return _format_table(columns, rows)
|
||||
|
||||
|
||||
def _format_table(columns: list[str], rows: list[tuple]) -> str:
|
||||
"""Format query results as a readable table."""
|
||||
if not rows:
|
||||
msg = "Query returned 0 rows."
|
||||
print(msg)
|
||||
return msg
|
||||
|
||||
# Calculate column widths
|
||||
col_widths = [len(str(c)) for c in columns]
|
||||
for row in rows:
|
||||
for i, val in enumerate(row):
|
||||
col_widths[i] = max(col_widths[i], len(str(val)))
|
||||
|
||||
# Cap column width
|
||||
max_width = 40
|
||||
col_widths = [min(w, max_width) for w in col_widths]
|
||||
|
||||
# Build table
|
||||
parts = []
|
||||
header = " | ".join(str(c).ljust(col_widths[i]) for i, c in enumerate(columns))
|
||||
separator = "-+-".join("-" * col_widths[i] for i in range(len(columns)))
|
||||
parts.append(header)
|
||||
parts.append(separator)
|
||||
for row in rows:
|
||||
row_str = " | ".join(
|
||||
str(v)[:max_width].ljust(col_widths[i]) for i, v in enumerate(row)
|
||||
)
|
||||
parts.append(row_str)
|
||||
|
||||
parts.append(f"\n({len(rows)} rows)")
|
||||
result = "\n".join(parts)
|
||||
print(result)
|
||||
return result
|
||||
|
||||
|
||||
def _export_results(columns: list[str], rows: list[tuple], output_file: str) -> str:
|
||||
"""Export query results to a file (CSV, JSON, or Markdown)."""
|
||||
os.makedirs(os.path.dirname(output_file), exist_ok=True)
|
||||
ext = os.path.splitext(output_file)[1].lower()
|
||||
|
||||
if ext == ".csv":
|
||||
import csv
|
||||
|
||||
with open(output_file, "w", newline="", encoding="utf-8") as f:
|
||||
writer = csv.writer(f)
|
||||
writer.writerow(columns)
|
||||
writer.writerows(rows)
|
||||
|
||||
elif ext == ".json":
|
||||
records = []
|
||||
for row in rows:
|
||||
record = {}
|
||||
for i, col in enumerate(columns):
|
||||
val = row[i]
|
||||
# Handle non-JSON-serializable types
|
||||
if hasattr(val, "isoformat"):
|
||||
val = val.isoformat()
|
||||
elif isinstance(val, (bytes, bytearray)):
|
||||
val = val.hex()
|
||||
record[col] = val
|
||||
records.append(record)
|
||||
with open(output_file, "w", encoding="utf-8") as f:
|
||||
json.dump(records, f, indent=2, ensure_ascii=False, default=str)
|
||||
|
||||
elif ext == ".md":
|
||||
with open(output_file, "w", encoding="utf-8") as f:
|
||||
# Header
|
||||
f.write("| " + " | ".join(columns) + " |\n")
|
||||
f.write("| " + " | ".join("---" for _ in columns) + " |\n")
|
||||
# Rows
|
||||
for row in rows:
|
||||
f.write(
|
||||
"| " + " | ".join(str(v).replace("|", "\\|") for v in row) + " |\n"
|
||||
)
|
||||
else:
|
||||
msg = f"Unsupported output format: {ext}. Use .csv, .json, or .md"
|
||||
print(msg)
|
||||
return msg
|
||||
|
||||
msg = f"Results exported to {output_file} ({len(rows)} rows)"
|
||||
print(msg)
|
||||
return msg
|
||||
|
||||
|
||||
def action_summary(
|
||||
con: duckdb.DuckDBPyConnection,
|
||||
table_name: str,
|
||||
table_map: dict[str, str],
|
||||
) -> str:
|
||||
"""Generate statistical summary for a table."""
|
||||
# Resolve table name
|
||||
resolved = table_map.get(table_name, table_name)
|
||||
|
||||
try:
|
||||
columns = con.execute(f'DESCRIBE "{resolved}"').fetchall()
|
||||
except Exception:
|
||||
available = ", ".join(f'"{t}" ({o})' for o, t in table_map.items())
|
||||
msg = f"Table '{table_name}' not found. Available tables: {available}"
|
||||
print(msg)
|
||||
return msg
|
||||
|
||||
row_count = con.execute(f'SELECT COUNT(*) FROM "{resolved}"').fetchone()[0]
|
||||
|
||||
output_parts = []
|
||||
output_parts.append(f"\nStatistical Summary: {table_name}")
|
||||
output_parts.append(f"Total rows: {row_count}")
|
||||
output_parts.append(f"{'=' * 70}")
|
||||
|
||||
numeric_types = {
|
||||
"BIGINT",
|
||||
"INTEGER",
|
||||
"SMALLINT",
|
||||
"TINYINT",
|
||||
"DOUBLE",
|
||||
"FLOAT",
|
||||
"DECIMAL",
|
||||
"HUGEINT",
|
||||
"REAL",
|
||||
"NUMERIC",
|
||||
}
|
||||
|
||||
for col in columns:
|
||||
col_name, col_type = col[0], col[1].upper()
|
||||
output_parts.append(f"\n--- {col_name} ({col[1]}) ---")
|
||||
|
||||
# Check base type (strip parameterized parts)
|
||||
base_type = re.sub(r"\(.*\)", "", col_type).strip()
|
||||
|
||||
if base_type in numeric_types:
|
||||
try:
|
||||
stats = con.execute(f"""
|
||||
SELECT
|
||||
COUNT("{col_name}") as count,
|
||||
AVG("{col_name}")::DOUBLE as mean,
|
||||
STDDEV("{col_name}")::DOUBLE as std,
|
||||
MIN("{col_name}") as min,
|
||||
QUANTILE_CONT("{col_name}", 0.25) as q25,
|
||||
MEDIAN("{col_name}") as median,
|
||||
QUANTILE_CONT("{col_name}", 0.75) as q75,
|
||||
MAX("{col_name}") as max,
|
||||
COUNT(*) - COUNT("{col_name}") as null_count
|
||||
FROM "{resolved}"
|
||||
""").fetchone()
|
||||
labels = [
|
||||
"count",
|
||||
"mean",
|
||||
"std",
|
||||
"min",
|
||||
"25%",
|
||||
"50%",
|
||||
"75%",
|
||||
"max",
|
||||
"nulls",
|
||||
]
|
||||
for label, val in zip(labels, stats):
|
||||
if isinstance(val, float):
|
||||
output_parts.append(f" {label:<8}: {val:,.4f}")
|
||||
else:
|
||||
output_parts.append(f" {label:<8}: {val}")
|
||||
except Exception as e:
|
||||
output_parts.append(f" Error computing stats: {e}")
|
||||
else:
|
||||
try:
|
||||
stats = con.execute(f"""
|
||||
SELECT
|
||||
COUNT("{col_name}") as count,
|
||||
COUNT(DISTINCT "{col_name}") as unique_count,
|
||||
MODE("{col_name}") as mode_val,
|
||||
COUNT(*) - COUNT("{col_name}") as null_count
|
||||
FROM "{resolved}"
|
||||
""").fetchone()
|
||||
output_parts.append(f" count : {stats[0]}")
|
||||
output_parts.append(f" unique : {stats[1]}")
|
||||
output_parts.append(f" top : {stats[2]}")
|
||||
output_parts.append(f" nulls : {stats[3]}")
|
||||
|
||||
# Show top 5 values
|
||||
top_vals = con.execute(f"""
|
||||
SELECT "{col_name}", COUNT(*) as freq
|
||||
FROM "{resolved}"
|
||||
WHERE "{col_name}" IS NOT NULL
|
||||
GROUP BY "{col_name}"
|
||||
ORDER BY freq DESC
|
||||
LIMIT 5
|
||||
""").fetchall()
|
||||
if top_vals:
|
||||
output_parts.append(f" top values:")
|
||||
for val, freq in top_vals:
|
||||
pct = (freq / row_count * 100) if row_count > 0 else 0
|
||||
output_parts.append(f" {val}: {freq} ({pct:.1f}%)")
|
||||
except Exception as e:
|
||||
output_parts.append(f" Error computing stats: {e}")
|
||||
|
||||
result = "\n".join(output_parts)
|
||||
print(result)
|
||||
return result
|
||||
|
||||
|
||||
def main():
|
||||
parser = argparse.ArgumentParser(description="Analyze Excel/CSV files using DuckDB")
|
||||
parser.add_argument(
|
||||
"--files",
|
||||
nargs="+",
|
||||
required=True,
|
||||
help="Paths to Excel (.xlsx/.xls) or CSV files",
|
||||
)
|
||||
parser.add_argument(
|
||||
"--action",
|
||||
required=True,
|
||||
choices=["inspect", "query", "summary"],
|
||||
help="Action to perform: inspect, query, or summary",
|
||||
)
|
||||
parser.add_argument(
|
||||
"--sql",
|
||||
type=str,
|
||||
default=None,
|
||||
help="SQL query to execute (required for 'query' action)",
|
||||
)
|
||||
parser.add_argument(
|
||||
"--table",
|
||||
type=str,
|
||||
default=None,
|
||||
help="Table name for summary (required for 'summary' action)",
|
||||
)
|
||||
parser.add_argument(
|
||||
"--output-file",
|
||||
type=str,
|
||||
default=None,
|
||||
help="Path to export results (CSV/JSON/MD)",
|
||||
)
|
||||
args = parser.parse_args()
|
||||
|
||||
# Validate arguments
|
||||
if args.action == "query" and not args.sql:
|
||||
parser.error("--sql is required for 'query' action")
|
||||
if args.action == "summary" and not args.table:
|
||||
parser.error("--table is required for 'summary' action")
|
||||
|
||||
# Compute file hash for caching
|
||||
files_hash = compute_files_hash(args.files)
|
||||
db_path = get_cache_db_path(files_hash)
|
||||
cached_table_map = load_table_map(files_hash)
|
||||
|
||||
if cached_table_map and os.path.exists(db_path):
|
||||
# Cache hit: connect to existing DB
|
||||
logger.info(f"Cache hit! Using cached database: {db_path}")
|
||||
con = duckdb.connect(db_path, read_only=True)
|
||||
table_map = cached_table_map
|
||||
logger.info(
|
||||
f"Loaded {len(table_map)} table(s) from cache: {', '.join(table_map.keys())}"
|
||||
)
|
||||
else:
|
||||
# Cache miss: load files and persist to DB
|
||||
logger.info("Loading files (first time, will cache for future use)...")
|
||||
con = duckdb.connect(db_path)
|
||||
table_map = load_files(con, args.files)
|
||||
|
||||
if not table_map:
|
||||
logger.error("No tables were loaded. Check file paths and formats.")
|
||||
# Clean up empty DB file
|
||||
con.close()
|
||||
if os.path.exists(db_path):
|
||||
os.remove(db_path)
|
||||
sys.exit(1)
|
||||
|
||||
# Save table map for future cache lookups
|
||||
save_table_map(files_hash, table_map)
|
||||
logger.info(
|
||||
f"\nLoaded {len(table_map)} table(s): {', '.join(table_map.keys())}"
|
||||
)
|
||||
logger.info(f"Cached database saved to: {db_path}")
|
||||
|
||||
# Perform action
|
||||
if args.action == "inspect":
|
||||
action_inspect(con, table_map)
|
||||
elif args.action == "query":
|
||||
action_query(con, args.sql, table_map, args.output_file)
|
||||
elif args.action == "summary":
|
||||
action_summary(con, args.table, table_map)
|
||||
|
||||
con.close()
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
198
deer-flow/skills/public/deep-research/SKILL.md
Normal file
198
deer-flow/skills/public/deep-research/SKILL.md
Normal file
@@ -0,0 +1,198 @@
|
||||
---
|
||||
name: deep-research
|
||||
description: Use this skill instead of WebSearch for ANY question requiring web research. Trigger on queries like "what is X", "explain X", "compare X and Y", "research X", or before content generation tasks. Provides systematic multi-angle research methodology instead of single superficial searches. Use this proactively when the user's question needs online information.
|
||||
---
|
||||
|
||||
# Deep Research Skill
|
||||
|
||||
## Overview
|
||||
|
||||
This skill provides a systematic methodology for conducting thorough web research. **Load this skill BEFORE starting any content generation task** to ensure you gather sufficient information from multiple angles, depths, and sources.
|
||||
|
||||
## When to Use This Skill
|
||||
|
||||
**Always load this skill when:**
|
||||
|
||||
### Research Questions
|
||||
- User asks "what is X", "explain X", "research X", "investigate X"
|
||||
- User wants to understand a concept, technology, or topic in depth
|
||||
- The question requires current, comprehensive information from multiple sources
|
||||
- A single web search would be insufficient to answer properly
|
||||
|
||||
### Content Generation (Pre-research)
|
||||
- Creating presentations (PPT/slides)
|
||||
- Creating frontend designs or UI mockups
|
||||
- Writing articles, reports, or documentation
|
||||
- Producing videos or multimedia content
|
||||
- Any content that requires real-world information, examples, or current data
|
||||
|
||||
## Core Principle
|
||||
|
||||
**Never generate content based solely on general knowledge.** The quality of your output directly depends on the quality and quantity of research conducted beforehand. A single search query is NEVER enough.
|
||||
|
||||
## Research Methodology
|
||||
|
||||
### Phase 1: Broad Exploration
|
||||
|
||||
Start with broad searches to understand the landscape:
|
||||
|
||||
1. **Initial Survey**: Search for the main topic to understand the overall context
|
||||
2. **Identify Dimensions**: From initial results, identify key subtopics, themes, angles, or aspects that need deeper exploration
|
||||
3. **Map the Territory**: Note different perspectives, stakeholders, or viewpoints that exist
|
||||
|
||||
Example:
|
||||
```
|
||||
Topic: "AI in healthcare"
|
||||
Initial searches:
|
||||
- "AI healthcare applications 2024"
|
||||
- "artificial intelligence medical diagnosis"
|
||||
- "healthcare AI market trends"
|
||||
|
||||
Identified dimensions:
|
||||
- Diagnostic AI (radiology, pathology)
|
||||
- Treatment recommendation systems
|
||||
- Administrative automation
|
||||
- Patient monitoring
|
||||
- Regulatory landscape
|
||||
- Ethical considerations
|
||||
```
|
||||
|
||||
### Phase 2: Deep Dive
|
||||
|
||||
For each important dimension identified, conduct targeted research:
|
||||
|
||||
1. **Specific Queries**: Search with precise keywords for each subtopic
|
||||
2. **Multiple Phrasings**: Try different keyword combinations and phrasings
|
||||
3. **Fetch Full Content**: Use `web_fetch` to read important sources in full, not just snippets
|
||||
4. **Follow References**: When sources mention other important resources, search for those too
|
||||
|
||||
Example:
|
||||
```
|
||||
Dimension: "Diagnostic AI in radiology"
|
||||
Targeted searches:
|
||||
- "AI radiology FDA approved systems"
|
||||
- "chest X-ray AI detection accuracy"
|
||||
- "radiology AI clinical trials results"
|
||||
|
||||
Then fetch and read:
|
||||
- Key research papers or summaries
|
||||
- Industry reports
|
||||
- Real-world case studies
|
||||
```
|
||||
|
||||
### Phase 3: Diversity & Validation
|
||||
|
||||
Ensure comprehensive coverage by seeking diverse information types:
|
||||
|
||||
| Information Type | Purpose | Example Searches |
|
||||
|-----------------|---------|------------------|
|
||||
| **Facts & Data** | Concrete evidence | "statistics", "data", "numbers", "market size" |
|
||||
| **Examples & Cases** | Real-world applications | "case study", "example", "implementation" |
|
||||
| **Expert Opinions** | Authority perspectives | "expert analysis", "interview", "commentary" |
|
||||
| **Trends & Predictions** | Future direction | "trends 2024", "forecast", "future of" |
|
||||
| **Comparisons** | Context and alternatives | "vs", "comparison", "alternatives" |
|
||||
| **Challenges & Criticisms** | Balanced view | "challenges", "limitations", "criticism" |
|
||||
|
||||
### Phase 4: Synthesis Check
|
||||
|
||||
Before proceeding to content generation, verify:
|
||||
|
||||
- [ ] Have I searched from at least 3-5 different angles?
|
||||
- [ ] Have I fetched and read the most important sources in full?
|
||||
- [ ] Do I have concrete data, examples, and expert perspectives?
|
||||
- [ ] Have I explored both positive aspects and challenges/limitations?
|
||||
- [ ] Is my information current and from authoritative sources?
|
||||
|
||||
**If any answer is NO, continue researching before generating content.**
|
||||
|
||||
## Search Strategy Tips
|
||||
|
||||
### Effective Query Patterns
|
||||
|
||||
```
|
||||
# Be specific with context
|
||||
❌ "AI trends"
|
||||
✅ "enterprise AI adoption trends 2024"
|
||||
|
||||
# Include authoritative source hints
|
||||
"[topic] research paper"
|
||||
"[topic] McKinsey report"
|
||||
"[topic] industry analysis"
|
||||
|
||||
# Search for specific content types
|
||||
"[topic] case study"
|
||||
"[topic] statistics"
|
||||
"[topic] expert interview"
|
||||
|
||||
# Use temporal qualifiers — always use the ACTUAL current year from <current_date>
|
||||
"[topic] 2026" # ← replace with real current year, never hardcode a past year
|
||||
"[topic] latest"
|
||||
"[topic] recent developments"
|
||||
```
|
||||
|
||||
### Temporal Awareness
|
||||
|
||||
**Always check `<current_date>` in your context before forming ANY search query.**
|
||||
|
||||
`<current_date>` gives you the full date: year, month, day, and weekday (e.g. `2026-02-28, Saturday`). Use the right level of precision depending on what the user is asking:
|
||||
|
||||
| User intent | Temporal precision needed | Example query |
|
||||
|---|---|---|
|
||||
| "today / this morning / just released" | **Month + Day** | `"tech news February 28 2026"` |
|
||||
| "this week" | **Week range** | `"technology releases week of Feb 24 2026"` |
|
||||
| "recently / latest / new" | **Month** | `"AI breakthroughs February 2026"` |
|
||||
| "this year / trends" | **Year** | `"software trends 2026"` |
|
||||
|
||||
**Rules:**
|
||||
- When the user asks about "today" or "just released", use **month + day + year** in your search queries to get same-day results
|
||||
- Never drop to year-only when day-level precision is needed — `"tech news 2026"` will NOT surface today's news
|
||||
- Try multiple phrasings: numeric form (`2026-02-28`), written form (`February 28 2026`), and relative terms (`today`, `this week`) across different queries
|
||||
|
||||
❌ User asks "what's new in tech today" → searching `"new technology 2026"` → misses today's news
|
||||
✅ User asks "what's new in tech today" → searching `"new technology February 28 2026"` + `"tech news today Feb 28"` → gets today's results
|
||||
|
||||
### When to Use web_fetch
|
||||
|
||||
Use `web_fetch` to read full content when:
|
||||
- A search result looks highly relevant and authoritative
|
||||
- You need detailed information beyond the snippet
|
||||
- The source contains data, case studies, or expert analysis
|
||||
- You want to understand the full context of a finding
|
||||
|
||||
### Iterative Refinement
|
||||
|
||||
Research is iterative. After initial searches:
|
||||
1. Review what you've learned
|
||||
2. Identify gaps in your understanding
|
||||
3. Formulate new, more targeted queries
|
||||
4. Repeat until you have comprehensive coverage
|
||||
|
||||
## Quality Bar
|
||||
|
||||
Your research is sufficient when you can confidently answer:
|
||||
- What are the key facts and data points?
|
||||
- What are 2-3 concrete real-world examples?
|
||||
- What do experts say about this topic?
|
||||
- What are the current trends and future directions?
|
||||
- What are the challenges or limitations?
|
||||
- What makes this topic relevant or important now?
|
||||
|
||||
## Common Mistakes to Avoid
|
||||
|
||||
- ❌ Stopping after 1-2 searches
|
||||
- ❌ Relying on search snippets without reading full sources
|
||||
- ❌ Searching only one aspect of a multi-faceted topic
|
||||
- ❌ Ignoring contradicting viewpoints or challenges
|
||||
- ❌ Using outdated information when current data exists
|
||||
- ❌ Starting content generation before research is complete
|
||||
|
||||
## Output
|
||||
|
||||
After completing research, you should have:
|
||||
1. A comprehensive understanding of the topic from multiple angles
|
||||
2. Specific facts, data points, and statistics
|
||||
3. Real-world examples and case studies
|
||||
4. Expert perspectives and authoritative sources
|
||||
5. Current trends and relevant context
|
||||
|
||||
**Only then proceed to content generation**, using the gathered information to create high-quality, well-informed content.
|
||||
138
deer-flow/skills/public/find-skills/SKILL.md
Normal file
138
deer-flow/skills/public/find-skills/SKILL.md
Normal file
@@ -0,0 +1,138 @@
|
||||
---
|
||||
name: find-skills
|
||||
description: Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skill should be used when the user is looking for functionality that might exist as an installable skill.
|
||||
---
|
||||
|
||||
# Find Skills
|
||||
|
||||
This skill helps you discover and install skills from the open agent skills ecosystem.
|
||||
|
||||
## When to Use This Skill
|
||||
|
||||
Use this skill when the user:
|
||||
|
||||
- Asks "how do I do X" where X might be a common task with an existing skill
|
||||
- Says "find a skill for X" or "is there a skill for X"
|
||||
- Asks "can you do X" where X is a specialized capability
|
||||
- Expresses interest in extending agent capabilities
|
||||
- Wants to search for tools, templates, or workflows
|
||||
- Mentions they wish they had help with a specific domain (design, testing, deployment, etc.)
|
||||
|
||||
## What is the Skills CLI?
|
||||
|
||||
The Skills CLI (`npx skills`) is the package manager for the open agent skills ecosystem. Skills are modular packages that extend agent capabilities with specialized knowledge, workflows, and tools.
|
||||
|
||||
**Key commands:**
|
||||
|
||||
- `npx skills find [query]` - Search for skills interactively or by keyword
|
||||
- `npx skills check` - Check for skill updates
|
||||
- `npx skills update` - Update all installed skills
|
||||
|
||||
**Browse skills at:** https://skills.sh/
|
||||
|
||||
## How to Help Users Find Skills
|
||||
|
||||
### Step 1: Understand What They Need
|
||||
|
||||
When a user asks for help with something, identify:
|
||||
|
||||
1. The domain (e.g., React, testing, design, deployment)
|
||||
2. The specific task (e.g., writing tests, creating animations, reviewing PRs)
|
||||
3. Whether this is a common enough task that a skill likely exists
|
||||
|
||||
### Step 2: Search for Skills
|
||||
|
||||
Run the find command with a relevant query:
|
||||
|
||||
```bash
|
||||
npx skills find [query]
|
||||
```
|
||||
|
||||
For example:
|
||||
|
||||
- User asks "how do I make my React app faster?" → `npx skills find react performance`
|
||||
- User asks "can you help me with PR reviews?" → `npx skills find pr review`
|
||||
- User asks "I need to create a changelog" → `npx skills find changelog`
|
||||
|
||||
The command will return results like:
|
||||
|
||||
```
|
||||
Install with bash /path/to/skill/scripts/install-skill.sh vercel-labs/agent-skills@vercel-react-best-practices
|
||||
|
||||
vercel-labs/agent-skills@vercel-react-best-practices
|
||||
└ https://skills.sh/vercel-labs/agent-skills/vercel-react-best-practices
|
||||
```
|
||||
|
||||
### Step 3: Present Options to the User
|
||||
|
||||
When you find relevant skills, present them to the user with:
|
||||
|
||||
1. The skill name and what it does
|
||||
2. The install command they can run
|
||||
3. A link to learn more at skills.sh
|
||||
|
||||
Example response:
|
||||
|
||||
```
|
||||
I found a skill that might help! The "vercel-react-best-practices" skill provides
|
||||
React and Next.js performance optimization guidelines from Vercel Engineering.
|
||||
|
||||
To install it:
|
||||
bash /path/to/skill/scripts/install-skill.sh vercel-labs/agent-skills@vercel-react-best-practices
|
||||
|
||||
Learn more: https://skills.sh/vercel-labs/agent-skills/vercel-react-best-practices
|
||||
```
|
||||
|
||||
### Step 4: Install the Skill
|
||||
|
||||
If the user wants to proceed, use the `install-skill.sh` script to install the skill and automatically link it to the project:
|
||||
|
||||
```bash
|
||||
bash /path/to/skill/scripts/install-skill.sh <owner/repo@skill-name>
|
||||
```
|
||||
|
||||
For example, if the user wants to install `vercel-react-best-practices`:
|
||||
|
||||
```bash
|
||||
bash /path/to/skill/scripts/install-skill.sh vercel-labs/agent-skills@vercel-react-best-practices
|
||||
```
|
||||
|
||||
The script will install the skill globally to `skills/custom/`
|
||||
|
||||
## Common Skill Categories
|
||||
|
||||
When searching, consider these common categories:
|
||||
|
||||
| Category | Example Queries |
|
||||
| --------------- | ---------------------------------------- |
|
||||
| Web Development | react, nextjs, typescript, css, tailwind |
|
||||
| Testing | testing, jest, playwright, e2e |
|
||||
| DevOps | deploy, docker, kubernetes, ci-cd |
|
||||
| Documentation | docs, readme, changelog, api-docs |
|
||||
| Code Quality | review, lint, refactor, best-practices |
|
||||
| Design | ui, ux, design-system, accessibility |
|
||||
| Productivity | workflow, automation, git |
|
||||
|
||||
## Tips for Effective Searches
|
||||
|
||||
1. **Use specific keywords**: "react testing" is better than just "testing"
|
||||
2. **Try alternative terms**: If "deploy" doesn't work, try "deployment" or "ci-cd"
|
||||
3. **Check popular sources**: Many skills come from `vercel-labs/agent-skills` or `ComposioHQ/awesome-claude-skills`
|
||||
|
||||
## When No Skills Are Found
|
||||
|
||||
If no relevant skills exist:
|
||||
|
||||
1. Acknowledge that no existing skill was found
|
||||
2. Offer to help with the task directly using your general capabilities
|
||||
3. Suggest the user could create their own skill with `npx skills init`
|
||||
|
||||
Example:
|
||||
|
||||
```
|
||||
I searched for skills related to "xyz" but didn't find any matches.
|
||||
I can still help you with this task directly! Would you like me to proceed?
|
||||
|
||||
If this is something you do often, you could create your own skill:
|
||||
npx skills init my-xyz-skill
|
||||
```
|
||||
62
deer-flow/skills/public/find-skills/scripts/install-skill.sh
Executable file
62
deer-flow/skills/public/find-skills/scripts/install-skill.sh
Executable file
@@ -0,0 +1,62 @@
|
||||
#!/bin/bash
|
||||
|
||||
# Install a skill and link it to the project's skills/custom directory
|
||||
# Usage: ./skills/install-skill.sh <owner/repo@skill-name>
|
||||
# Example: ./skills/install-skill.sh vercel-labs/agent-skills@vercel-react-best-practices
|
||||
|
||||
set -e
|
||||
|
||||
if [[ -z "$1" ]]; then
|
||||
echo "Usage: $0 <owner/repo@skill-name>"
|
||||
echo "Example: $0 vercel-labs/agent-skills@vercel-react-best-practices"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
FULL_SKILL_NAME="$1"
|
||||
|
||||
# Extract skill name (the part after @)
|
||||
SKILL_NAME="${FULL_SKILL_NAME##*@}"
|
||||
|
||||
if [[ -z "$SKILL_NAME" || "$SKILL_NAME" == "$FULL_SKILL_NAME" ]]; then
|
||||
echo "Error: Invalid skill format. Expected: owner/repo@skill-name"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Find project root by looking for deer-flow.code-workspace
|
||||
find_project_root() {
|
||||
local dir="$PWD"
|
||||
while [[ "$dir" != "/" ]]; do
|
||||
if [[ -f "$dir/deer-flow.code-workspace" ]]; then
|
||||
echo "$dir"
|
||||
return 0
|
||||
fi
|
||||
dir="$(dirname "$dir")"
|
||||
done
|
||||
echo ""
|
||||
return 1
|
||||
}
|
||||
|
||||
PROJECT_ROOT=$(find_project_root)
|
||||
|
||||
if [[ -z "$PROJECT_ROOT" ]]; then
|
||||
echo "Error: Could not find project root (deer-flow.code-workspace not found)"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
SKILL_SOURCE="$HOME/.agents/skills/$SKILL_NAME"
|
||||
SKILL_TARGET="$PROJECT_ROOT/skills/custom"
|
||||
|
||||
# Step 1: Install the skill using npx
|
||||
npx skills add "$FULL_SKILL_NAME" -g -y > /dev/null 2>&1
|
||||
|
||||
# Step 2: Verify installation
|
||||
if [[ ! -d "$SKILL_SOURCE" ]]; then
|
||||
echo "Skill '$SKILL_NAME' installation failed"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Step 3: Create symlink
|
||||
mkdir -p "$SKILL_TARGET"
|
||||
ln -sf "$SKILL_SOURCE" "$SKILL_TARGET/"
|
||||
|
||||
echo "Skill '$SKILL_NAME' installed successfully"
|
||||
177
deer-flow/skills/public/frontend-design/LICENSE.txt
Normal file
177
deer-flow/skills/public/frontend-design/LICENSE.txt
Normal file
@@ -0,0 +1,177 @@
|
||||
|
||||
Apache License
|
||||
Version 2.0, January 2004
|
||||
http://www.apache.org/licenses/
|
||||
|
||||
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
|
||||
|
||||
1. Definitions.
|
||||
|
||||
"License" shall mean the terms and conditions for use, reproduction,
|
||||
and distribution as defined by Sections 1 through 9 of this document.
|
||||
|
||||
"Licensor" shall mean the copyright owner or entity authorized by
|
||||
the copyright owner that is granting the License.
|
||||
|
||||
"Legal Entity" shall mean the union of the acting entity and all
|
||||
other entities that control, are controlled by, or are under common
|
||||
control with that entity. For the purposes of this definition,
|
||||
"control" means (i) the power, direct or indirect, to cause the
|
||||
direction or management of such entity, whether by contract or
|
||||
otherwise, or (ii) ownership of fifty percent (50%) or more of the
|
||||
outstanding shares, or (iii) beneficial ownership of such entity.
|
||||
|
||||
"You" (or "Your") shall mean an individual or Legal Entity
|
||||
exercising permissions granted by this License.
|
||||
|
||||
"Source" form shall mean the preferred form for making modifications,
|
||||
including but not limited to software source code, documentation
|
||||
source, and configuration files.
|
||||
|
||||
"Object" form shall mean any form resulting from mechanical
|
||||
transformation or translation of a Source form, including but
|
||||
not limited to compiled object code, generated documentation,
|
||||
and conversions to other media types.
|
||||
|
||||
"Work" shall mean the work of authorship, whether in Source or
|
||||
Object form, made available under the License, as indicated by a
|
||||
copyright notice that is included in or attached to the work
|
||||
(an example is provided in the Appendix below).
|
||||
|
||||
"Derivative Works" shall mean any work, whether in Source or Object
|
||||
form, that is based on (or derived from) the Work and for which the
|
||||
editorial revisions, annotations, elaborations, or other modifications
|
||||
represent, as a whole, an original work of authorship. For the purposes
|
||||
of this License, Derivative Works shall not include works that remain
|
||||
separable from, or merely link (or bind by name) to the interfaces of,
|
||||
the Work and Derivative Works thereof.
|
||||
|
||||
"Contribution" shall mean any work of authorship, including
|
||||
the original version of the Work and any modifications or additions
|
||||
to that Work or Derivative Works thereof, that is intentionally
|
||||
submitted to Licensor for inclusion in the Work by the copyright owner
|
||||
or by an individual or Legal Entity authorized to submit on behalf of
|
||||
the copyright owner. For the purposes of this definition, "submitted"
|
||||
means any form of electronic, verbal, or written communication sent
|
||||
to the Licensor or its representatives, including but not limited to
|
||||
communication on electronic mailing lists, source code control systems,
|
||||
and issue tracking systems that are managed by, or on behalf of, the
|
||||
Licensor for the purpose of discussing and improving the Work, but
|
||||
excluding communication that is conspicuously marked or otherwise
|
||||
designated in writing by the copyright owner as "Not a Contribution."
|
||||
|
||||
"Contributor" shall mean Licensor and any individual or Legal Entity
|
||||
on behalf of whom a Contribution has been received by Licensor and
|
||||
subsequently incorporated within the Work.
|
||||
|
||||
2. Grant of Copyright License. Subject to the terms and conditions of
|
||||
this License, each Contributor hereby grants to You a perpetual,
|
||||
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
||||
copyright license to reproduce, prepare Derivative Works of,
|
||||
publicly display, publicly perform, sublicense, and distribute the
|
||||
Work and such Derivative Works in Source or Object form.
|
||||
|
||||
3. Grant of Patent License. Subject to the terms and conditions of
|
||||
this License, each Contributor hereby grants to You a perpetual,
|
||||
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
||||
(except as stated in this section) patent license to make, have made,
|
||||
use, offer to sell, sell, import, and otherwise transfer the Work,
|
||||
where such license applies only to those patent claims licensable
|
||||
by such Contributor that are necessarily infringed by their
|
||||
Contribution(s) alone or by combination of their Contribution(s)
|
||||
with the Work to which such Contribution(s) was submitted. If You
|
||||
institute patent litigation against any entity (including a
|
||||
cross-claim or counterclaim in a lawsuit) alleging that the Work
|
||||
or a Contribution incorporated within the Work constitutes direct
|
||||
or contributory patent infringement, then any patent licenses
|
||||
granted to You under this License for that Work shall terminate
|
||||
as of the date such litigation is filed.
|
||||
|
||||
4. Redistribution. You may reproduce and distribute copies of the
|
||||
Work or Derivative Works thereof in any medium, with or without
|
||||
modifications, and in Source or Object form, provided that You
|
||||
meet the following conditions:
|
||||
|
||||
(a) You must give any other recipients of the Work or
|
||||
Derivative Works a copy of this License; and
|
||||
|
||||
(b) You must cause any modified files to carry prominent notices
|
||||
stating that You changed the files; and
|
||||
|
||||
(c) You must retain, in the Source form of any Derivative Works
|
||||
that You distribute, all copyright, patent, trademark, and
|
||||
attribution notices from the Source form of the Work,
|
||||
excluding those notices that do not pertain to any part of
|
||||
the Derivative Works; and
|
||||
|
||||
(d) If the Work includes a "NOTICE" text file as part of its
|
||||
distribution, then any Derivative Works that You distribute must
|
||||
include a readable copy of the attribution notices contained
|
||||
within such NOTICE file, excluding those notices that do not
|
||||
pertain to any part of the Derivative Works, in at least one
|
||||
of the following places: within a NOTICE text file distributed
|
||||
as part of the Derivative Works; within the Source form or
|
||||
documentation, if provided along with the Derivative Works; or,
|
||||
within a display generated by the Derivative Works, if and
|
||||
wherever such third-party notices normally appear. The contents
|
||||
of the NOTICE file are for informational purposes only and
|
||||
do not modify the License. You may add Your own attribution
|
||||
notices within Derivative Works that You distribute, alongside
|
||||
or as an addendum to the NOTICE text from the Work, provided
|
||||
that such additional attribution notices cannot be construed
|
||||
as modifying the License.
|
||||
|
||||
You may add Your own copyright statement to Your modifications and
|
||||
may provide additional or different license terms and conditions
|
||||
for use, reproduction, or distribution of Your modifications, or
|
||||
for any such Derivative Works as a whole, provided Your use,
|
||||
reproduction, and distribution of the Work otherwise complies with
|
||||
the conditions stated in this License.
|
||||
|
||||
5. Submission of Contributions. Unless You explicitly state otherwise,
|
||||
any Contribution intentionally submitted for inclusion in the Work
|
||||
by You to the Licensor shall be under the terms and conditions of
|
||||
this License, without any additional terms or conditions.
|
||||
Notwithstanding the above, nothing herein shall supersede or modify
|
||||
the terms of any separate license agreement you may have executed
|
||||
with Licensor regarding such Contributions.
|
||||
|
||||
6. Trademarks. This License does not grant permission to use the trade
|
||||
names, trademarks, service marks, or product names of the Licensor,
|
||||
except as required for reasonable and customary use in describing the
|
||||
origin of the Work and reproducing the content of the NOTICE file.
|
||||
|
||||
7. Disclaimer of Warranty. Unless required by applicable law or
|
||||
agreed to in writing, Licensor provides the Work (and each
|
||||
Contributor provides its Contributions) on an "AS IS" BASIS,
|
||||
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
|
||||
implied, including, without limitation, any warranties or conditions
|
||||
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
|
||||
PARTICULAR PURPOSE. You are solely responsible for determining the
|
||||
appropriateness of using or redistributing the Work and assume any
|
||||
risks associated with Your exercise of permissions under this License.
|
||||
|
||||
8. Limitation of Liability. In no event and under no legal theory,
|
||||
whether in tort (including negligence), contract, or otherwise,
|
||||
unless required by applicable law (such as deliberate and grossly
|
||||
negligent acts) or agreed to in writing, shall any Contributor be
|
||||
liable to You for damages, including any direct, indirect, special,
|
||||
incidental, or consequential damages of any character arising as a
|
||||
result of this License or out of the use or inability to use the
|
||||
Work (including but not limited to damages for loss of goodwill,
|
||||
work stoppage, computer failure or malfunction, or any and all
|
||||
other commercial damages or losses), even if such Contributor
|
||||
has been advised of the possibility of such damages.
|
||||
|
||||
9. Accepting Warranty or Additional Liability. While redistributing
|
||||
the Work or Derivative Works thereof, You may choose to offer,
|
||||
and charge a fee for, acceptance of support, warranty, indemnity,
|
||||
or other liability obligations and/or rights consistent with this
|
||||
License. However, in accepting such obligations, You may act only
|
||||
on Your own behalf and on Your sole responsibility, not on behalf
|
||||
of any other Contributor, and only if You agree to indemnify,
|
||||
defend, and hold each Contributor harmless for any liability
|
||||
incurred by, or claims asserted against, such Contributor by reason
|
||||
of your accepting any such warranty or additional liability.
|
||||
|
||||
END OF TERMS AND CONDITIONS
|
||||
92
deer-flow/skills/public/frontend-design/SKILL.md
Normal file
92
deer-flow/skills/public/frontend-design/SKILL.md
Normal file
@@ -0,0 +1,92 @@
|
||||
---
|
||||
name: frontend-design
|
||||
description: Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, artifacts, posters, or applications (examples include websites, landing pages, dashboards, React components, HTML/CSS layouts, or when styling/beautifying any web UI). Generates creative, polished code and UI design that avoids generic AI aesthetics.
|
||||
license: Complete terms in LICENSE.txt
|
||||
---
|
||||
|
||||
This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices.
|
||||
|
||||
The user provides frontend requirements: a component, page, application, or interface to build. They may include context about the purpose, audience, or technical constraints.
|
||||
|
||||
## Output Requirements
|
||||
|
||||
**MANDATORY**: The entry HTML file MUST be named `index.html`. This is a strict requirement for all generated frontend projects to ensure compatibility with standard web hosting and deployment workflows.
|
||||
|
||||
## Design Thinking
|
||||
|
||||
Before coding, understand the context and commit to a BOLD aesthetic direction:
|
||||
- **Purpose**: What problem does this interface solve? Who uses it?
|
||||
- **Tone**: Pick an extreme: brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian, etc. There are so many flavors to choose from. Use these for inspiration but design one that is true to the aesthetic direction.
|
||||
- **Constraints**: Technical requirements (framework, performance, accessibility).
|
||||
- **Differentiation**: What makes this UNFORGETTABLE? What's the one thing someone will remember?
|
||||
|
||||
**CRITICAL**: Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work - the key is intentionality, not intensity.
|
||||
|
||||
Then implement working code (HTML/CSS/JS, React, Vue, etc.) that is:
|
||||
- Production-grade and functional
|
||||
- Visually striking and memorable
|
||||
- Cohesive with a clear aesthetic point-of-view
|
||||
- Meticulously refined in every detail
|
||||
|
||||
## Frontend Aesthetics Guidelines
|
||||
|
||||
Focus on:
|
||||
- **Typography**: Choose fonts that are beautiful, unique, and interesting. Avoid generic fonts like Arial and Inter; opt instead for distinctive choices that elevate the frontend's aesthetics; unexpected, characterful font choices. Pair a distinctive display font with a refined body font.
|
||||
- **Color & Theme**: Commit to a cohesive aesthetic. Use CSS variables for consistency. Dominant colors with sharp accents outperform timid, evenly-distributed palettes.
|
||||
- **Motion**: Use animations for effects and micro-interactions. Prioritize CSS-only solutions for HTML. Use Motion library for React when available. Focus on high-impact moments: one well-orchestrated page load with staggered reveals (animation-delay) creates more delight than scattered micro-interactions. Use scroll-triggering and hover states that surprise.
|
||||
- **Spatial Composition**: Unexpected layouts. Asymmetry. Overlap. Diagonal flow. Grid-breaking elements. Generous negative space OR controlled density.
|
||||
- **Backgrounds & Visual Details**: Create atmosphere and depth rather than defaulting to solid colors. Add contextual effects and textures that match the overall aesthetic. Apply creative forms like gradient meshes, noise textures, geometric patterns, layered transparencies, dramatic shadows, decorative borders, custom cursors, and grain overlays.
|
||||
|
||||
NEVER use generic AI-generated aesthetics like overused font families (Inter, Roboto, Arial, system fonts), cliched color schemes (particularly purple gradients on white backgrounds), predictable layouts and component patterns, and cookie-cutter design that lacks context-specific character.
|
||||
|
||||
Interpret creatively and make unexpected choices that feel genuinely designed for the context. No design should be the same. Vary between light and dark themes, different fonts, different aesthetics. NEVER converge on common choices (Space Grotesk, for example) across generations.
|
||||
|
||||
**IMPORTANT**: Match implementation complexity to the aesthetic vision. Maximalist designs need elaborate code with extensive animations and effects. Minimalist or refined designs need restraint, precision, and careful attention to spacing, typography, and subtle details. Elegance comes from executing the vision well.
|
||||
|
||||
## Branding Requirement
|
||||
|
||||
**MANDATORY**: Every generated frontend interface MUST include a "Created By Deerflow" signature. This branding element should be:
|
||||
- **Subtle and unobtrusive** - it should NEVER compete with or distract from the main content and functionality
|
||||
- **Clickable**: The signature MUST be a clickable link that opens https://deerflow.tech in a new tab (target="_blank")
|
||||
- Integrated naturally into the design, feeling like an intentional design element rather than an afterthought
|
||||
- Small in size, using muted colors or reduced opacity that blend harmoniously with the overall aesthetic
|
||||
|
||||
**IMPORTANT**: The branding should be discoverable but not prominent. Users should notice the main interface first; the signature is a quiet attribution, not a focal point.
|
||||
|
||||
**Creative Implementation Ideas** (choose one that best matches your design aesthetic):
|
||||
|
||||
1. **Floating Corner Badge**: A small, elegant badge fixed to a corner with subtle hover effects (e.g., gentle glow, slight scale-up, color shift)
|
||||
|
||||
2. **Artistic Watermark**: A semi-transparent diagonal text or logo pattern in the background, barely visible but adds texture
|
||||
|
||||
3. **Integrated Border Element**: Part of a decorative border or frame around the content - the signature becomes an organic part of the design structure
|
||||
|
||||
4. **Animated Signature**: A small signature that elegantly writes itself on page load, or reveals on scroll near the bottom
|
||||
|
||||
5. **Contextual Integration**: Blend into the theme - for a retro design, use a vintage stamp look; for minimalist, a single small icon or monogram "DF" with tooltip
|
||||
|
||||
6. **Cursor Trail or Easter Egg**: A very subtle approach where the branding appears as a micro-interaction (e.g., holding cursor still reveals a tiny signature, or appears in a creative loading state)
|
||||
|
||||
7. **Decorative Divider**: Incorporate into a decorative line, separator, or ornamental element on the page
|
||||
|
||||
8. **Glassmorphism Card**: A tiny floating glass-effect card in a corner with blur backdrop
|
||||
|
||||
Example code patterns:
|
||||
```html
|
||||
<!-- Floating corner badge with hover effect -->
|
||||
<a href="https://deerflow.tech" target="_blank" class="deerflow-badge">✦ Deerflow</a>
|
||||
|
||||
<!-- Monogram with tooltip -->
|
||||
<a href="https://deerflow.tech" target="_blank" title="Created By Deerflow" class="deerflow-mark">DF</a>
|
||||
|
||||
<!-- Integrated into decorative element -->
|
||||
<div class="footer-ornament">
|
||||
<span class="line"></span>
|
||||
<a href="https://deerflow.tech" target="_blank">Deerflow</a>
|
||||
<span class="line"></span>
|
||||
</div>
|
||||
```
|
||||
|
||||
**Design Principle**: The branding should feel like it belongs - a natural extension of your creative vision, not a mandatory stamp. Match the signature's style (typography, color, animation) to the overall aesthetic direction.
|
||||
|
||||
Remember: Claude is capable of extraordinary creative work. Don't hold back, show what can truly be created when thinking outside the box and committing fully to a distinctive vision.
|
||||
166
deer-flow/skills/public/github-deep-research/SKILL.md
Normal file
166
deer-flow/skills/public/github-deep-research/SKILL.md
Normal file
@@ -0,0 +1,166 @@
|
||||
---
|
||||
name: github-deep-research
|
||||
description: Conduct multi-round deep research on any GitHub Repo. Use when users request comprehensive analysis, timeline reconstruction, competitive analysis, or in-depth investigation of GitHub. Produces structured markdown reports with executive summaries, chronological timelines, metrics analysis, and Mermaid diagrams. Triggers on Github repository URL or open source projects.
|
||||
---
|
||||
|
||||
# GitHub Deep Research Skill
|
||||
|
||||
Multi-round research combining GitHub API, web_search, web_fetch to produce comprehensive markdown reports.
|
||||
|
||||
## Research Workflow
|
||||
|
||||
- Round 1: GitHub API
|
||||
- Round 2: Discovery
|
||||
- Round 3: Deep Investigation
|
||||
- Round 4: Deep Dive
|
||||
|
||||
## Core Methodology
|
||||
|
||||
### Query Strategy
|
||||
|
||||
**Broad to Narrow**: Start with GitHub API, then general queries, refine based on findings.
|
||||
|
||||
```
|
||||
Round 1: GitHub API
|
||||
Round 2: "{topic} overview"
|
||||
Round 3: "{topic} architecture", "{topic} vs alternatives"
|
||||
Round 4: "{topic} issues", "{topic} roadmap", "site:github.com {topic}"
|
||||
```
|
||||
|
||||
**Source Prioritization**:
|
||||
1. Official docs/repos (highest weight)
|
||||
2. Technical blogs (Medium, Dev.to)
|
||||
3. News articles (verified outlets)
|
||||
4. Community discussions (Reddit, HN)
|
||||
5. Social media (lowest weight, for sentiment)
|
||||
|
||||
### Research Rounds
|
||||
|
||||
**Round 1 - GitHub API**
|
||||
Directly execute `scripts/github_api.py` without `read_file()`:
|
||||
```bash
|
||||
python /path/to/skill/scripts/github_api.py <owner> <repo> summary
|
||||
python /path/to/skill/scripts/github_api.py <owner> <repo> readme
|
||||
python /path/to/skill/scripts/github_api.py <owner> <repo> tree
|
||||
```
|
||||
|
||||
**Available commands (the last argument of `github_api.py`):**
|
||||
- summary
|
||||
- info
|
||||
- readme
|
||||
- tree
|
||||
- languages
|
||||
- contributors
|
||||
- commits
|
||||
- issues
|
||||
- prs
|
||||
- releases
|
||||
|
||||
**Round 2 - Discovery (3-5 web_search)**
|
||||
- Get overview and identify key terms
|
||||
- Find official website/repo
|
||||
- Identify main players/competitors
|
||||
|
||||
**Round 3 - Deep Investigation (5-10 web_search + web_fetch)**
|
||||
- Technical architecture details
|
||||
- Timeline of key events
|
||||
- Community sentiment
|
||||
- Use web_fetch on valuable URLs for full content
|
||||
|
||||
**Round 4 - Deep Dive**
|
||||
- Analyze commit history for timeline
|
||||
- Review issues/PRs for feature evolution
|
||||
- Check contributor activity
|
||||
|
||||
## Report Structure
|
||||
|
||||
Follow template in `assets/report_template.md`:
|
||||
|
||||
1. **Metadata Block** - Date, confidence level, subject
|
||||
2. **Executive Summary** - 2-3 sentence overview with key metrics
|
||||
3. **Chronological Timeline** - Phased breakdown with dates
|
||||
4. **Key Analysis Sections** - Topic-specific deep dives
|
||||
5. **Metrics & Comparisons** - Tables, growth charts
|
||||
6. **Strengths & Weaknesses** - Balanced assessment
|
||||
7. **Sources** - Categorized references
|
||||
8. **Confidence Assessment** - Claims by confidence level
|
||||
9. **Methodology** - Research approach used
|
||||
|
||||
### Mermaid Diagrams
|
||||
|
||||
Include diagrams where helpful:
|
||||
|
||||
**Timeline (Gantt)**:
|
||||
```mermaid
|
||||
gantt
|
||||
title Project Timeline
|
||||
dateFormat YYYY-MM-DD
|
||||
section Phase 1
|
||||
Development :2025-01-01, 2025-03-01
|
||||
section Phase 2
|
||||
Launch :2025-03-01, 2025-04-01
|
||||
```
|
||||
|
||||
**Architecture (Flowchart)**:
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[User] --> B[Coordinator]
|
||||
B --> C[Planner]
|
||||
C --> D[Research Team]
|
||||
D --> E[Reporter]
|
||||
```
|
||||
|
||||
**Comparison (Pie/Bar)**:
|
||||
```mermaid
|
||||
pie title Market Share
|
||||
"Project A" : 45
|
||||
"Project B" : 30
|
||||
"Others" : 25
|
||||
```
|
||||
|
||||
## Confidence Scoring
|
||||
|
||||
Assign confidence based on source quality:
|
||||
|
||||
| Confidence | Criteria |
|
||||
|------------|----------|
|
||||
| High (90%+) | Official docs, GitHub data, multiple corroborating sources |
|
||||
| Medium (70-89%) | Single reliable source, recent articles |
|
||||
| Low (50-69%) | Social media, unverified claims, outdated info |
|
||||
|
||||
## Output
|
||||
|
||||
Save report as: `research_{topic}_{YYYYMMDD}.md`
|
||||
|
||||
### Formatting Rules
|
||||
|
||||
- Chinese content: Use full-width punctuation（，。：；！？）
|
||||
- Technical terms: Provide Wiki/doc URL on first mention
|
||||
- Tables: Use for metrics, comparisons
|
||||
- Code blocks: For technical examples
|
||||
- Mermaid: For architecture, timelines, flows
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Start with official sources** - Repo, docs, company blog
|
||||
2. **Verify dates from commits/PRs** - More reliable than articles
|
||||
3. **Triangulate claims** - 2+ independent sources
|
||||
4. **Note conflicting info** - Don't hide contradictions
|
||||
5. **Distinguish fact vs opinion** - Label speculation clearly
|
||||
6. **CRITICAL: Always include inline citations** - Use `[citation:Title](URL)` format immediately after each claim from external sources
|
||||
7. **Extract URLs from search results** - web_search returns {title, url, snippet} - always use the URL field
|
||||
8. **Update as you go** - Don't wait until end to synthesize
|
||||
|
||||
### Citation Examples
|
||||
|
||||
**Good - With inline citations:**
|
||||
```markdown
|
||||
The project gained 10,000 stars within 3 months of launch [citation:GitHub Stats](https://github.com/owner/repo).
|
||||
The architecture uses LangGraph for workflow orchestration [citation:LangGraph Docs](https://langchain.com/langgraph).
|
||||
```
|
||||
|
||||
**Bad - Without citations:**
|
||||
```markdown
|
||||
The project gained 10,000 stars within 3 months of launch.
|
||||
The architecture uses LangGraph for workflow orchestration.
|
||||
```
|
||||
@@ -0,0 +1,192 @@
|
||||
[!NOTE] Generate this report in user's own language.
|
||||
|
||||
# {TITLE}
|
||||
|
||||
- **Research Date:** {DATE}
|
||||
- **Timestamp:** {TIMESTAMP}
|
||||
- **Confidence Level:** {CONFIDENCE_LEVEL}
|
||||
- **Subject:** {SUBJECT_DESCRIPTION}
|
||||
|
||||
---
|
||||
|
||||
## Repository Information
|
||||
|
||||
- **Name:** {REPOSITORY_NAME}
|
||||
- **Description:** {REPOSITORY_DESCRIPTION}
|
||||
- **URL:** {REPOSITORY_URL}
|
||||
- **Stars:** {REPOSITORY_STARS}
|
||||
- **Forks:** {REPOSITORY_FORKS}
|
||||
- **Open Issues:** {REPOSITORY_OPEN_ISSUES}
|
||||
- **Language(s):** {REPOSITORY_LANGUAGES}
|
||||
- **License:** {REPOSITORY_LICENSE}
|
||||
- **Created At:** {REPOSITORY_CREATED_AT}
|
||||
- **Updated At:** {REPOSITORY_UPDATED_AT}
|
||||
- **Pushed At:** {REPOSITORY_PUSHED_AT}
|
||||
- **Topics:** {REPOSITORY_TOPICS}
|
||||
|
||||
---
|
||||
|
||||
## Executive Summary
|
||||
|
||||
{EXECUTIVE_SUMMARY}
|
||||
|
||||
**IMPORTANT**: Include inline citations using `[citation:Title](URL)` format after each claim. Example:
|
||||
"The project gained 10k stars in 3 months [citation:GitHub Stats](https://github.com/owner/repo)."
|
||||
|
||||
---
|
||||
|
||||
## Complete Chronological Timeline
|
||||
|
||||
### PHASE 1: {PHASE_1_NAME}
|
||||
|
||||
#### {PHASE_1_PERIOD}
|
||||
|
||||
{PHASE_1_CONTENT}
|
||||
|
||||
### PHASE 2: {PHASE_2_NAME}
|
||||
|
||||
#### {PHASE_2_PERIOD}
|
||||
|
||||
{PHASE_2_CONTENT}
|
||||
|
||||
### PHASE 3: {PHASE_3_NAME}
|
||||
|
||||
#### {PHASE_3_PERIOD}
|
||||
|
||||
{PHASE_3_CONTENT}
|
||||
|
||||
---
|
||||
|
||||
## Key Analysis
|
||||
|
||||
**IMPORTANT**: Support each analysis point with inline citations `[citation:Title](URL)`.
|
||||
|
||||
### {ANALYSIS_SECTION_1_TITLE}
|
||||
|
||||
{ANALYSIS_SECTION_1_CONTENT}
|
||||
|
||||
### {ANALYSIS_SECTION_2_TITLE}
|
||||
|
||||
{ANALYSIS_SECTION_2_CONTENT}
|
||||
|
||||
---
|
||||
|
||||
## Architecture / System Overview
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[Component A] --> B[Component B]
|
||||
B --> C[Component C]
|
||||
C --> D[Component D]
|
||||
```
|
||||
|
||||
{ARCHITECTURE_DESCRIPTION}
|
||||
|
||||
---
|
||||
|
||||
## Metrics & Impact Analysis
|
||||
|
||||
### Growth Trajectory
|
||||
|
||||
```
|
||||
{METRICS_TIMELINE}
|
||||
```
|
||||
|
||||
### Key Metrics
|
||||
|
||||
| Metric | Value | Assessment |
|
||||
|--------|-------|------------|
|
||||
| {METRIC_1} | {VALUE_1} | {ASSESSMENT_1} |
|
||||
| {METRIC_2} | {VALUE_2} | {ASSESSMENT_2} |
|
||||
| {METRIC_3} | {VALUE_3} | {ASSESSMENT_3} |
|
||||
|
||||
---
|
||||
|
||||
## Comparative Analysis
|
||||
|
||||
### Feature Comparison
|
||||
|
||||
| Feature | {SUBJECT} | {COMPETITOR_1} | {COMPETITOR_2} |
|
||||
|---------|-----------|----------------|----------------|
|
||||
| {FEATURE_1} | {SUBJ_F1} | {COMP1_F1} | {COMP2_F1} |
|
||||
| {FEATURE_2} | {SUBJ_F2} | {COMP1_F2} | {COMP2_F2} |
|
||||
| {FEATURE_3} | {SUBJ_F3} | {COMP1_F3} | {COMP2_F3} |
|
||||
|
||||
### Market Positioning
|
||||
|
||||
{MARKET_POSITIONING}
|
||||
|
||||
---
|
||||
|
||||
## Strengths & Weaknesses
|
||||
|
||||
### Strengths
|
||||
|
||||
{STRENGTHS}
|
||||
|
||||
### Areas for Improvement
|
||||
|
||||
{WEAKNESSES}
|
||||
|
||||
---
|
||||
|
||||
## Key Success Factors
|
||||
|
||||
{SUCCESS_FACTORS}
|
||||
|
||||
---
|
||||
|
||||
## Sources
|
||||
|
||||
### Primary Sources
|
||||
|
||||
{PRIMARY_SOURCES}
|
||||
|
||||
### Media Coverage
|
||||
|
||||
{MEDIA_SOURCES}
|
||||
|
||||
### Academic / Technical Sources
|
||||
|
||||
{ACADEMIC_SOURCES}
|
||||
|
||||
### Community Sources
|
||||
|
||||
{COMMUNITY_SOURCES}
|
||||
|
||||
---
|
||||
|
||||
## Confidence Assessment
|
||||
|
||||
**High Confidence (90%+) Claims:**
|
||||
{HIGH_CONFIDENCE_CLAIMS}
|
||||
|
||||
**Medium Confidence (70-89%) Claims:**
|
||||
{MEDIUM_CONFIDENCE_CLAIMS}
|
||||
|
||||
**Lower Confidence (50-69%) Claims:**
|
||||
{LOW_CONFIDENCE_CLAIMS}
|
||||
|
||||
---
|
||||
|
||||
## Research Methodology
|
||||
|
||||
This report was compiled using:
|
||||
|
||||
1. **Multi-source web search** - Broad discovery and targeted queries
|
||||
2. **GitHub repository analysis** - Commits, issues, PRs, activity metrics
|
||||
3. **Content extraction** - Official docs, technical articles, media coverage
|
||||
4. **Cross-referencing** - Verification across independent sources
|
||||
5. **Chronological reconstruction** - Timeline from timestamped data
|
||||
6. **Confidence scoring** - Claims weighted by source reliability
|
||||
|
||||
**Research Depth:** {RESEARCH_DEPTH}
|
||||
**Time Scope:** {TIME_SCOPE}
|
||||
**Geographic Scope:** {GEOGRAPHIC_SCOPE}
|
||||
|
||||
---
|
||||
|
||||
**Report Prepared By:** Github Deep Research by DeerFlow
|
||||
**Date:** {REPORT_DATE}
|
||||
**Report Version:** 1.0
|
||||
**Status:** Complete
|
||||
@@ -0,0 +1,331 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
GitHub API client for deep research.
|
||||
Uses requests for HTTP operations.
|
||||
"""
|
||||
|
||||
import os
|
||||
import json
|
||||
import sys
|
||||
from typing import Any, Dict, List, Optional
|
||||
|
||||
try:
|
||||
import requests
|
||||
except ImportError:
|
||||
# Fallback to urllib if requests not available
|
||||
import urllib.error
|
||||
import urllib.request
|
||||
|
||||
class RequestsFallback:
|
||||
"""Minimal requests-like interface using urllib."""
|
||||
|
||||
class Response:
|
||||
def __init__(self, data: bytes, status: int):
|
||||
self._data = data
|
||||
self.status_code = status
|
||||
self.text = data.decode("utf-8", errors="replace")
|
||||
|
||||
def json(self):
|
||||
return json.loads(self._data)
|
||||
|
||||
def raise_for_status(self):
|
||||
if self.status_code >= 400:
|
||||
raise Exception(f"HTTP {self.status_code}")
|
||||
|
||||
@staticmethod
|
||||
def get(url: str, headers: dict = None, params: dict = None, timeout: int = 30):
|
||||
if params:
|
||||
query = "&".join(f"{k}={v}" for k, v in params.items())
|
||||
url = f"{url}?{query}"
|
||||
|
||||
req = urllib.request.Request(url, headers=headers or {})
|
||||
try:
|
||||
with urllib.request.urlopen(req, timeout=timeout) as resp:
|
||||
return RequestsFallback.Response(resp.read(), resp.status)
|
||||
except urllib.error.HTTPError as e:
|
||||
return RequestsFallback.Response(e.read(), e.code)
|
||||
|
||||
requests = RequestsFallback()
|
||||
|
||||
|
||||
class GitHubAPI:
|
||||
"""GitHub API client for repository analysis."""
|
||||
|
||||
BASE_URL = "https://api.github.com"
|
||||
|
||||
def __init__(self, token: Optional[str] = None):
|
||||
"""
|
||||
Initialize GitHub API client.
|
||||
|
||||
Args:
|
||||
token:
|
||||
Optional GitHub personal access token for higher rate limits.
|
||||
User can set it in .env by uncommenting the line "GITHUB_TOKEN=your-github-token".
|
||||
"""
|
||||
self.headers = {
|
||||
"Accept": "application/vnd.github.v3+json",
|
||||
"User-Agent": "Deep-Research-Bot/1.0",
|
||||
}
|
||||
if token:
|
||||
self.headers["Authorization"] = f"token {token}"
|
||||
|
||||
def _get(
|
||||
self, endpoint: str, params: Optional[Dict] = None, accept: Optional[str] = None
|
||||
) -> Any:
|
||||
"""Make GET request to GitHub API."""
|
||||
url = f"{self.BASE_URL}{endpoint}"
|
||||
headers = self.headers.copy()
|
||||
if accept:
|
||||
headers["Accept"] = accept
|
||||
|
||||
resp = requests.get(url, headers=headers, params=params, timeout=30)
|
||||
resp.raise_for_status()
|
||||
|
||||
if "application/vnd.github.raw" in (accept or ""):
|
||||
return resp.text
|
||||
return resp.json()
|
||||
|
||||
def get_repo_info(self, owner: str, repo: str) -> Dict:
|
||||
"""Get basic repository information."""
|
||||
return self._get(f"/repos/{owner}/{repo}")
|
||||
|
||||
def get_readme(self, owner: str, repo: str) -> str:
|
||||
"""Get repository README content as markdown."""
|
||||
try:
|
||||
return self._get(
|
||||
f"/repos/{owner}/{repo}/readme", accept="application/vnd.github.raw"
|
||||
)
|
||||
except Exception as e:
|
||||
return f"[README not found: {e}]"
|
||||
|
||||
def get_tree(
|
||||
self, owner: str, repo: str, branch: str = "main", recursive: bool = True
|
||||
) -> Dict:
|
||||
"""Get repository directory tree."""
|
||||
params = {"recursive": "1"} if recursive else {}
|
||||
try:
|
||||
return self._get(f"/repos/{owner}/{repo}/git/trees/{branch}", params)
|
||||
except Exception:
|
||||
# Try 'master' if 'main' fails
|
||||
if branch == "main":
|
||||
return self._get(f"/repos/{owner}/{repo}/git/trees/master", params)
|
||||
raise
|
||||
|
||||
def get_file_content(self, owner: str, repo: str, path: str) -> str:
|
||||
"""Get content of a specific file."""
|
||||
try:
|
||||
return self._get(
|
||||
f"/repos/{owner}/{repo}/contents/{path}",
|
||||
accept="application/vnd.github.raw",
|
||||
)
|
||||
except Exception as e:
|
||||
return f"[File not found: {e}]"
|
||||
|
||||
def get_languages(self, owner: str, repo: str) -> Dict[str, int]:
|
||||
"""Get repository languages and their bytes."""
|
||||
return self._get(f"/repos/{owner}/{repo}/languages")
|
||||
|
||||
def get_contributors(self, owner: str, repo: str, limit: int = 30) -> List[Dict]:
|
||||
"""Get repository contributors."""
|
||||
return self._get(
|
||||
f"/repos/{owner}/{repo}/contributors", params={"per_page": min(limit, 100)}
|
||||
)
|
||||
|
||||
def get_recent_commits(
|
||||
self, owner: str, repo: str, limit: int = 50, since: Optional[str] = None
|
||||
) -> List[Dict]:
|
||||
"""
|
||||
Get recent commits.
|
||||
|
||||
Args:
|
||||
owner: Repository owner
|
||||
repo: Repository name
|
||||
limit: Max commits to fetch
|
||||
since: ISO date string to fetch commits since
|
||||
"""
|
||||
params = {"per_page": min(limit, 100)}
|
||||
if since:
|
||||
params["since"] = since
|
||||
return self._get(f"/repos/{owner}/{repo}/commits", params)
|
||||
|
||||
def get_issues(
|
||||
self,
|
||||
owner: str,
|
||||
repo: str,
|
||||
state: str = "all",
|
||||
limit: int = 30,
|
||||
labels: Optional[str] = None,
|
||||
) -> List[Dict]:
|
||||
"""
|
||||
Get repository issues.
|
||||
|
||||
Args:
|
||||
state: 'open', 'closed', or 'all'
|
||||
labels: Comma-separated label names
|
||||
"""
|
||||
params = {"state": state, "per_page": min(limit, 100)}
|
||||
if labels:
|
||||
params["labels"] = labels
|
||||
return self._get(f"/repos/{owner}/{repo}/issues", params)
|
||||
|
||||
def get_pull_requests(
|
||||
self, owner: str, repo: str, state: str = "all", limit: int = 30
|
||||
) -> List[Dict]:
|
||||
"""Get repository pull requests."""
|
||||
return self._get(
|
||||
f"/repos/{owner}/{repo}/pulls",
|
||||
params={"state": state, "per_page": min(limit, 100)},
|
||||
)
|
||||
|
||||
def get_releases(self, owner: str, repo: str, limit: int = 10) -> List[Dict]:
|
||||
"""Get repository releases."""
|
||||
return self._get(
|
||||
f"/repos/{owner}/{repo}/releases", params={"per_page": min(limit, 100)}
|
||||
)
|
||||
|
||||
def get_tags(self, owner: str, repo: str, limit: int = 20) -> List[Dict]:
|
||||
"""Get repository tags."""
|
||||
return self._get(
|
||||
f"/repos/{owner}/{repo}/tags", params={"per_page": min(limit, 100)}
|
||||
)
|
||||
|
||||
def search_issues(self, owner: str, repo: str, query: str, limit: int = 30) -> Dict:
|
||||
"""Search issues and PRs in repository."""
|
||||
q = f"repo:{owner}/{repo} {query}"
|
||||
return self._get("/search/issues", params={"q": q, "per_page": min(limit, 100)})
|
||||
|
||||
def get_commit_activity(self, owner: str, repo: str) -> List[Dict]:
|
||||
"""Get weekly commit activity for the last year."""
|
||||
return self._get(f"/repos/{owner}/{repo}/stats/commit_activity")
|
||||
|
||||
def get_code_frequency(self, owner: str, repo: str) -> List[List[int]]:
|
||||
"""Get weekly additions/deletions."""
|
||||
return self._get(f"/repos/{owner}/{repo}/stats/code_frequency")
|
||||
|
||||
def format_tree(self, tree_data: Dict, max_depth: int = 3) -> str:
|
||||
"""
|
||||
Format tree data as text directory structure.
|
||||
|
||||
Args:
|
||||
tree_data: Response from get_tree()
|
||||
max_depth: Maximum depth to display
|
||||
"""
|
||||
if "tree" not in tree_data:
|
||||
return "[Unable to parse tree]"
|
||||
|
||||
lines = []
|
||||
for item in tree_data["tree"]:
|
||||
path = item["path"]
|
||||
depth = path.count("/")
|
||||
if depth < max_depth:
|
||||
indent = " " * depth
|
||||
name = path.split("/")[-1]
|
||||
if item["type"] == "tree":
|
||||
lines.append(f"{indent}{name}/")
|
||||
else:
|
||||
lines.append(f"{indent}{name}")
|
||||
|
||||
return "\n".join(lines[:100]) # Limit output
|
||||
|
||||
def summarize_repo(self, owner: str, repo: str) -> Dict:
|
||||
"""
|
||||
Get comprehensive repository summary.
|
||||
|
||||
Returns dict with: info, languages, contributor_count,
|
||||
recent_activity, top_issues, latest_release
|
||||
"""
|
||||
info = self.get_repo_info(owner, repo)
|
||||
|
||||
summary = {
|
||||
"name": info.get("full_name"),
|
||||
"description": info.get("description"),
|
||||
"url": info.get("html_url"),
|
||||
"stars": info.get("stargazers_count"),
|
||||
"forks": info.get("forks_count"),
|
||||
"open_issues": info.get("open_issues_count"),
|
||||
"language": info.get("language"),
|
||||
"license": info.get("license", {}).get("spdx_id")
|
||||
if info.get("license")
|
||||
else None,
|
||||
"created_at": info.get("created_at"),
|
||||
"updated_at": info.get("updated_at"),
|
||||
"pushed_at": info.get("pushed_at"),
|
||||
"default_branch": info.get("default_branch"),
|
||||
"topics": info.get("topics", []),
|
||||
}
|
||||
|
||||
# Add languages
|
||||
try:
|
||||
summary["languages"] = self.get_languages(owner, repo)
|
||||
except Exception:
|
||||
summary["languages"] = {}
|
||||
|
||||
# Add contributor count
|
||||
try:
|
||||
contributors = self.get_contributors(owner, repo, limit=1)
|
||||
# GitHub returns Link header with total, but we approximate
|
||||
summary["contributor_count"] = len(
|
||||
self.get_contributors(owner, repo, limit=100)
|
||||
)
|
||||
except Exception:
|
||||
summary["contributor_count"] = "N/A"
|
||||
|
||||
# Latest release
|
||||
try:
|
||||
releases = self.get_releases(owner, repo, limit=1)
|
||||
if releases:
|
||||
summary["latest_release"] = {
|
||||
"tag": releases[0].get("tag_name"),
|
||||
"name": releases[0].get("name"),
|
||||
"date": releases[0].get("published_at"),
|
||||
}
|
||||
except Exception:
|
||||
summary["latest_release"] = None
|
||||
|
||||
return summary
|
||||
|
||||
|
||||
def main():
|
||||
"""CLI interface for testing."""
|
||||
if len(sys.argv) < 3:
|
||||
print("Usage: python github_api.py <owner> <repo> [command]")
|
||||
print("Commands: info, readme, tree, languages, contributors,")
|
||||
print(" commits, issues, prs, releases, summary")
|
||||
sys.exit(1)
|
||||
|
||||
owner, repo = sys.argv[1], sys.argv[2]
|
||||
command = sys.argv[3] if len(sys.argv) > 3 else "summary"
|
||||
|
||||
token = os.getenv("GITHUB_TOKEN")
|
||||
api = GitHubAPI(token=token)
|
||||
|
||||
commands = {
|
||||
"info": lambda: api.get_repo_info(owner, repo),
|
||||
"readme": lambda: api.get_readme(owner, repo),
|
||||
"tree": lambda: api.format_tree(api.get_tree(owner, repo)),
|
||||
"languages": lambda: api.get_languages(owner, repo),
|
||||
"contributors": lambda: api.get_contributors(owner, repo),
|
||||
"commits": lambda: api.get_recent_commits(owner, repo),
|
||||
"issues": lambda: api.get_issues(owner, repo),
|
||||
"prs": lambda: api.get_pull_requests(owner, repo),
|
||||
"releases": lambda: api.get_releases(owner, repo),
|
||||
"summary": lambda: api.summarize_repo(owner, repo),
|
||||
}
|
||||
|
||||
if command not in commands:
|
||||
print(f"Unknown command: {command}")
|
||||
sys.exit(1)
|
||||
|
||||
try:
|
||||
result = commands[command]()
|
||||
if isinstance(result, str):
|
||||
print(result)
|
||||
else:
|
||||
print(json.dumps(result, indent=2, default=str))
|
||||
except Exception as e:
|
||||
print(f"Error: {e}", file=sys.stderr)
|
||||
sys.exit(1)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
187
deer-flow/skills/public/image-generation/SKILL.md
Normal file
187
deer-flow/skills/public/image-generation/SKILL.md
Normal file
@@ -0,0 +1,187 @@
|
||||
---
|
||||
name: image-generation
|
||||
description: Use this skill when the user requests to generate, create, imagine, or visualize images including characters, scenes, products, or any visual content. Supports structured prompts and reference images for guided generation.
|
||||
---
|
||||
|
||||
# Image Generation Skill
|
||||
|
||||
## Overview
|
||||
|
||||
This skill generates high-quality images using structured prompts and a Python script. The workflow includes creating JSON-formatted prompts and executing image generation with optional reference images.
|
||||
|
||||
## Core Capabilities
|
||||
|
||||
- Create structured JSON prompts for AIGC image generation
|
||||
- Support multiple reference images for style/composition guidance
|
||||
- Generate images through automated Python script execution
|
||||
- Handle various image generation scenarios (character design, scenes, products, etc.)
|
||||
|
||||
## Workflow
|
||||
|
||||
### Step 1: Understand Requirements
|
||||
|
||||
When a user requests image generation, identify:
|
||||
|
||||
- Subject/content: What should be in the image
|
||||
- Style preferences: Art style, mood, color palette
|
||||
- Technical specs: Aspect ratio, composition, lighting
|
||||
- Reference images: Any images to guide generation
|
||||
- You don't need to check the folder under `/mnt/user-data`
|
||||
|
||||
### Step 2: Create Structured Prompt
|
||||
|
||||
Generate a structured JSON file in `/mnt/user-data/workspace/` with naming pattern: `{descriptive-name}.json`
|
||||
|
||||
### Step 3: Execute Generation
|
||||
|
||||
Call the Python script:
|
||||
```bash
|
||||
python /mnt/skills/public/image-generation/scripts/generate.py \
|
||||
--prompt-file /mnt/user-data/workspace/prompt-file.json \
|
||||
--reference-images /path/to/ref1.jpg /path/to/ref2.png \
|
||||
--output-file /mnt/user-data/outputs/generated-image.jpg
|
||||
--aspect-ratio 16:9
|
||||
```
|
||||
|
||||
Parameters:
|
||||
|
||||
- `--prompt-file`: Absolute path to JSON prompt file (required)
|
||||
- `--reference-images`: Absolute paths to reference images (optional, space-separated)
|
||||
- `--output-file`: Absolute path to output image file (required)
|
||||
- `--aspect-ratio`: Aspect ratio of the generated image (optional, default: 16:9)
|
||||
|
||||
[!NOTE]
|
||||
Do NOT read the python file, just call it with the parameters.
|
||||
|
||||
## Character Generation Example
|
||||
|
||||
User request: "Create a Tokyo street style woman character in 1990s"
|
||||
|
||||
Create prompt file: `/mnt/user-data/workspace/asian-woman.json`
|
||||
```json
|
||||
{
|
||||
"characters": [{
|
||||
"gender": "female",
|
||||
"age": "mid-20s",
|
||||
"ethnicity": "Japanese",
|
||||
"body_type": "slender, elegant",
|
||||
"facial_features": "delicate features, expressive eyes, subtle makeup with emphasis on lips, long dark hair partially wet from rain",
|
||||
"clothing": "stylish trench coat, designer handbag, high heels, contemporary Tokyo street fashion",
|
||||
"accessories": "minimal jewelry, statement earrings, leather handbag",
|
||||
"era": "1990s"
|
||||
}],
|
||||
"negative_prompt": "blurry face, deformed, low quality, overly sharp digital look, oversaturated colors, artificial lighting, studio setting, posed, selfie angle",
|
||||
"style": "Leica M11 street photography aesthetic, film-like rendering, natural color palette with slight warmth, bokeh background blur, analog photography feel",
|
||||
"composition": "medium shot, rule of thirds, subject slightly off-center, environmental context of Tokyo street visible, shallow depth of field isolating subject",
|
||||
"lighting": "neon lights from signs and storefronts, wet pavement reflections, soft ambient city glow, natural street lighting, rim lighting from background neons",
|
||||
"color_palette": "muted naturalistic tones, warm skin tones, cool blue and magenta neon accents, desaturated compared to digital photography, film grain texture"
|
||||
}
|
||||
```
|
||||
|
||||
Execute generation:
|
||||
```bash
|
||||
python /mnt/skills/public/image-generation/scripts/generate.py \
|
||||
--prompt-file /mnt/user-data/workspace/cyberpunk-hacker.json \
|
||||
--output-file /mnt/user-data/outputs/cyberpunk-hacker-01.jpg \
|
||||
--aspect-ratio 2:3
|
||||
```
|
||||
|
||||
With reference images:
|
||||
```json
|
||||
{
|
||||
"characters": [{
|
||||
"gender": "based on [Image 1]",
|
||||
"age": "based on [Image 1]",
|
||||
"ethnicity": "human from [Image 1] adapted to Star Wars universe",
|
||||
"body_type": "based on [Image 1]",
|
||||
"facial_features": "matching [Image 1] with slight weathered look from space travel",
|
||||
"clothing": "Star Wars style outfit - worn leather jacket with utility vest, cargo pants with tactical pouches, scuffed boots, belt with holster",
|
||||
"accessories": "blaster pistol on hip, comlink device on wrist, goggles pushed up on forehead, satchel with supplies, personal vehicle based on [Image 2]",
|
||||
"era": "Star Wars universe, post-Empire era"
|
||||
}],
|
||||
"prompt": "Character inspired by [Image 1] standing next to a vehicle inspired by [Image 2] on a bustling alien planet street in Star Wars universe aesthetic. Character wearing worn leather jacket with utility vest, cargo pants with tactical pouches, scuffed boots, belt with blaster holster. The vehicle adapted to Star Wars aesthetic with weathered metal panels, repulsor engines, desert dust covering, parked on the street. Exotic alien marketplace street with multi-level architecture, weathered metal structures, hanging market stalls with colorful awnings, alien species walking by as background characters. Twin suns casting warm golden light, atmospheric dust particles in air, moisture vaporators visible in distance. Gritty lived-in Star Wars aesthetic, practical effects look, film grain texture, cinematic composition.",
|
||||
"negative_prompt": "clean futuristic look, sterile environment, overly CGI appearance, fantasy medieval elements, Earth architecture, modern city",
|
||||
"style": "Star Wars original trilogy aesthetic, lived-in universe, practical effects inspired, cinematic film look, slightly desaturated with warm tones",
|
||||
"composition": "medium wide shot, character in foreground with alien street extending into background, environmental storytelling, rule of thirds",
|
||||
"lighting": "warm golden hour lighting from twin suns, rim lighting on character, atmospheric haze, practical light sources from market stalls",
|
||||
"color_palette": "warm sandy tones, ochre and sienna, dusty blues, weathered metals, muted earth colors with pops of alien market colors",
|
||||
"technical": {
|
||||
"aspect_ratio": "9:16",
|
||||
"quality": "high",
|
||||
"detail_level": "highly detailed with film-like texture"
|
||||
}
|
||||
}
|
||||
```
|
||||
```bash
|
||||
python /mnt/skills/public/image-generation/scripts/generate.py \
|
||||
--prompt-file /mnt/user-data/workspace/star-wars-scene.json \
|
||||
--reference-images /mnt/user-data/uploads/character-ref.jpg /mnt/user-data/uploads/vehicle-ref.jpg \
|
||||
--output-file /mnt/user-data/outputs/star-wars-scene-01.jpg \
|
||||
--aspect-ratio 16:9
|
||||
```
|
||||
|
||||
## Common Scenarios
|
||||
|
||||
Use different JSON schemas for different scenarios.
|
||||
|
||||
**Character Design**:
|
||||
- Physical attributes (gender, age, ethnicity, body type)
|
||||
- Facial features and expressions
|
||||
- Clothing and accessories
|
||||
- Historical era or setting
|
||||
- Pose and context
|
||||
|
||||
**Scene Generation**:
|
||||
- Environment description
|
||||
- Time of day, weather
|
||||
- Mood and atmosphere
|
||||
- Focal points and composition
|
||||
|
||||
**Product Visualization**:
|
||||
- Product details and materials
|
||||
- Lighting setup
|
||||
- Background and context
|
||||
- Presentation angle
|
||||
|
||||
## Specific Templates
|
||||
|
||||
Read the following template file only when matching the user request.
|
||||
|
||||
- [Doraemon Comic](templates/doraemon.md)
|
||||
|
||||
## Output Handling
|
||||
|
||||
After generation:
|
||||
|
||||
- Images are typically saved in `/mnt/user-data/outputs/`
|
||||
- Share generated images with user using present_files tool
|
||||
- Provide brief description of the generation result
|
||||
- Offer to iterate if adjustments needed
|
||||
|
||||
## Tips: Enhancing Generation with Reference Images
|
||||
|
||||
For scenarios where visual accuracy is critical, **use the `image_search` tool first** to find reference images before generation.
|
||||
|
||||
**Recommended scenarios for using image_search tool:**
|
||||
- **Character/Portrait Generation**: Search for similar poses, expressions, or styles to guide facial features and body proportions
|
||||
- **Specific Objects or Products**: Find reference images of real objects to ensure accurate representation
|
||||
- **Architectural or Environmental Scenes**: Search for location references to capture authentic details
|
||||
- **Fashion and Clothing**: Find style references to ensure accurate garment details and styling
|
||||
|
||||
**Example workflow:**
|
||||
1. Call the `image_search` tool to find suitable reference images:
|
||||
```
|
||||
image_search(query="Japanese woman street photography 1990s", size="Large")
|
||||
```
|
||||
2. Download the returned image URLs to local files
|
||||
3. Use the downloaded images as `--reference-images` parameter in the generation script
|
||||
|
||||
This approach significantly improves generation quality by providing the model with concrete visual guidance rather than relying solely on text descriptions.
|
||||
|
||||
## Notes
|
||||
|
||||
- Always use English for prompts regardless of user's language
|
||||
- JSON format ensures structured, parsable prompts
|
||||
- Reference images enhance generation quality significantly
|
||||
- Iterative refinement is normal for optimal results
|
||||
- For character generation, include the detailed character object plus a consolidated prompt field
|
||||
132
deer-flow/skills/public/image-generation/scripts/generate.py
Normal file
132
deer-flow/skills/public/image-generation/scripts/generate.py
Normal file
@@ -0,0 +1,132 @@
|
||||
import base64
|
||||
import os
|
||||
|
||||
import requests
|
||||
from PIL import Image
|
||||
|
||||
|
||||
def validate_image(image_path: str) -> bool:
|
||||
"""
|
||||
Validate if an image file can be opened and is not corrupted.
|
||||
|
||||
Args:
|
||||
image_path: Path to the image file
|
||||
|
||||
Returns:
|
||||
True if the image is valid and can be opened, False otherwise
|
||||
"""
|
||||
try:
|
||||
with Image.open(image_path) as img:
|
||||
img.verify() # Verify that it's a valid image
|
||||
# Re-open to check if it can be fully loaded (verify() may not catch all issues)
|
||||
with Image.open(image_path) as img:
|
||||
img.load() # Force load the image data
|
||||
return True
|
||||
except Exception as e:
|
||||
print(f"Warning: Image '{image_path}' is invalid or corrupted: {e}")
|
||||
return False
|
||||
|
||||
|
||||
def generate_image(
|
||||
prompt_file: str,
|
||||
reference_images: list[str],
|
||||
output_file: str,
|
||||
aspect_ratio: str = "16:9",
|
||||
) -> str:
|
||||
with open(prompt_file, "r", encoding="utf-8") as f:
|
||||
prompt = f.read()
|
||||
parts = []
|
||||
i = 0
|
||||
|
||||
# Filter out invalid reference images
|
||||
valid_reference_images = []
|
||||
for ref_img in reference_images:
|
||||
if validate_image(ref_img):
|
||||
valid_reference_images.append(ref_img)
|
||||
else:
|
||||
print(f"Skipping invalid reference image: {ref_img}")
|
||||
|
||||
if len(valid_reference_images) < len(reference_images):
|
||||
print(f"Note: {len(reference_images) - len(valid_reference_images)} reference image(s) were skipped due to validation failure.")
|
||||
|
||||
for reference_image in valid_reference_images:
|
||||
i += 1
|
||||
with open(reference_image, "rb") as f:
|
||||
image_b64 = base64.b64encode(f.read()).decode("utf-8")
|
||||
parts.append(
|
||||
{
|
||||
"inlineData": {
|
||||
"mimeType": "image/jpeg",
|
||||
"data": image_b64,
|
||||
}
|
||||
}
|
||||
)
|
||||
|
||||
api_key = os.getenv("GEMINI_API_KEY")
|
||||
if not api_key:
|
||||
return "GEMINI_API_KEY is not set"
|
||||
response = requests.post(
|
||||
"https://generativelanguage.googleapis.com/v1beta/models/gemini-3-pro-image-preview:generateContent",
|
||||
headers={
|
||||
"x-goog-api-key": api_key,
|
||||
"Content-Type": "application/json",
|
||||
},
|
||||
json={
|
||||
"generationConfig": {"imageConfig": {"aspectRatio": aspect_ratio}},
|
||||
"contents": [{"parts": [*parts, {"text": prompt}]}],
|
||||
},
|
||||
)
|
||||
response.raise_for_status()
|
||||
json = response.json()
|
||||
parts: list[dict] = json["candidates"][0]["content"]["parts"]
|
||||
image_parts = [part for part in parts if part.get("inlineData", False)]
|
||||
if len(image_parts) == 1:
|
||||
base64_image = image_parts[0]["inlineData"]["data"]
|
||||
# Save the image to a file
|
||||
with open(output_file, "wb") as f:
|
||||
f.write(base64.b64decode(base64_image))
|
||||
return f"Successfully generated image to {output_file}"
|
||||
else:
|
||||
raise Exception("Failed to generate image")
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
import argparse
|
||||
|
||||
parser = argparse.ArgumentParser(description="Generate images using Gemini API")
|
||||
parser.add_argument(
|
||||
"--prompt-file",
|
||||
required=True,
|
||||
help="Absolute path to JSON prompt file",
|
||||
)
|
||||
parser.add_argument(
|
||||
"--reference-images",
|
||||
nargs="*",
|
||||
default=[],
|
||||
help="Absolute paths to reference images (space-separated)",
|
||||
)
|
||||
parser.add_argument(
|
||||
"--output-file",
|
||||
required=True,
|
||||
help="Output path for generated image",
|
||||
)
|
||||
parser.add_argument(
|
||||
"--aspect-ratio",
|
||||
required=False,
|
||||
default="16:9",
|
||||
help="Aspect ratio of the generated image",
|
||||
)
|
||||
|
||||
args = parser.parse_args()
|
||||
|
||||
try:
|
||||
print(
|
||||
generate_image(
|
||||
args.prompt_file,
|
||||
args.reference_images,
|
||||
args.output_file,
|
||||
args.aspect_ratio,
|
||||
)
|
||||
)
|
||||
except Exception as e:
|
||||
print(f"Error while generating image: {e}")
|
||||
112
deer-flow/skills/public/image-generation/templates/doraemon.md
Normal file
112
deer-flow/skills/public/image-generation/templates/doraemon.md
Normal file
@@ -0,0 +1,112 @@
|
||||
# Doraemon 8-Panel Comic Generator
|
||||
|
||||
## Workflow
|
||||
|
||||
1. Extract story context (theme, gadget, conflict, punchline)
|
||||
2. Map to 8 narrative beats
|
||||
3. Use the provided prompt template to generate the JSON prompt file
|
||||
|
||||
## Panel Layout
|
||||
|
||||
```
|
||||
┌─────────┬─────────┐
|
||||
│ Panel 1 │ Panel 2 │ Row 1: y=200, height=380
|
||||
├─────────┼─────────┤
|
||||
│ Panel 3 │ Panel 4 │ Row 2: y=600, height=380
|
||||
├─────────┼─────────┤
|
||||
│ Panel 5 │ Panel 6 │ Row 3: y=1000, height=380
|
||||
├─────────┼─────────┤
|
||||
│ Panel 7 │ Panel 8 │ Row 4: y=1400, height=380
|
||||
└─────────┴─────────┘
|
||||
Left column: x=90, width=450
|
||||
Right column: x=540, width=450
|
||||
```
|
||||
|
||||
## Characters
|
||||
|
||||
* Doraemon
|
||||
* Nobita
|
||||
* Shizuka
|
||||
* Giant
|
||||
* Suneo
|
||||
|
||||
## Prompt Template
|
||||
|
||||
```json
|
||||
{
|
||||
"canvas": {
|
||||
"width": 1080,
|
||||
"height": 1920,
|
||||
"background": { "type": "solid", "color": "#F0F8FF" }
|
||||
},
|
||||
"header": {
|
||||
"title": {
|
||||
"text": "[Story Title]",
|
||||
"position": { "x": 540, "y": 100 },
|
||||
"style": {
|
||||
"font_family": "Doraemon, sans-serif",
|
||||
"font_size": 56,
|
||||
"font_weight": "bold",
|
||||
"color": "#0095D9",
|
||||
"text_align": "center",
|
||||
"stroke": "#FFFFFF",
|
||||
"stroke_width": 4,
|
||||
"text_shadow": "3px 3px 0px #FFD700"
|
||||
}
|
||||
}
|
||||
},
|
||||
"panels": [
|
||||
{
|
||||
"id": "panel1",
|
||||
"position": { "x": 90, "y": 200 },
|
||||
"size": { "width": 450, "height": 380 },
|
||||
"border": { "width": 4, "color": "#000000", "radius": 12 },
|
||||
"background": "#FFFFFF",
|
||||
"scene": {
|
||||
"location": "[Location name]",
|
||||
"characters": [
|
||||
{
|
||||
"name": "[Character]",
|
||||
"position": { "x": 0, "y": 0 },
|
||||
"expression": "[Expression]",
|
||||
"pose": "[Pose description]"
|
||||
}
|
||||
],
|
||||
"dialogues": [
|
||||
{
|
||||
"speaker": "[Character]",
|
||||
"text": "[Dialogue text]",
|
||||
"position": { "x": 0, "y": 0 },
|
||||
"style": {
|
||||
"bubble_type": "speech",
|
||||
"backgroundColor": "#FFFFFF",
|
||||
"border_color": "#000000",
|
||||
"font_size": 22,
|
||||
"text_align": "center"
|
||||
}
|
||||
}
|
||||
],
|
||||
"props": []
|
||||
}
|
||||
}
|
||||
],
|
||||
"footer": {
|
||||
"text": "[Closing note] - Doraemon",
|
||||
"position": { "x": 540, "y": 1860 },
|
||||
"style": {
|
||||
"font_family": "Doraemon, sans-serif",
|
||||
"font_size": 24,
|
||||
"color": "#0095D9",
|
||||
"text_align": "center"
|
||||
}
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
## Story Pattern
|
||||
|
||||
Setup → Problem → Gadget → Misuse → Backfire → Chaos → Consequence → Ironic Punchline
|
||||
|
||||
## Aspect Ratio
|
||||
|
||||
9:16
|
||||
343
deer-flow/skills/public/newsletter-generation/SKILL.md
Normal file
343
deer-flow/skills/public/newsletter-generation/SKILL.md
Normal file
@@ -0,0 +1,343 @@
|
||||
---
|
||||
name: newsletter-generation
|
||||
description: Use this skill when the user requests to generate, create, write, or draft a newsletter, email digest, weekly roundup, industry briefing, or curated content summary. Supports topic-based research, content curation from multiple sources, and professional formatting for email or web distribution. Trigger on requests like "create a newsletter about X", "write a weekly digest", "generate a tech roundup", or "curate news about Y".
|
||||
---
|
||||
|
||||
# Newsletter Generation Skill
|
||||
|
||||
## Overview
|
||||
|
||||
This skill generates professional, well-researched newsletters that combine curated content from multiple sources with original analysis and commentary. It follows modern newsletter best practices from publications like Morning Brew, The Hustle, TLDR, and Benedict Evans to produce content that is informative, engaging, and actionable.
|
||||
|
||||
The output is a complete, ready-to-publish newsletter in Markdown format, suitable for email distribution platforms, web publishing, or conversion to HTML.
|
||||
|
||||
## Core Capabilities
|
||||
|
||||
- Research and curate content from multiple web sources on specified topics
|
||||
- Generate topic-focused or multi-topic newsletters with consistent voice
|
||||
- Write engaging headlines, summaries, and original commentary
|
||||
- Structure content for optimal readability and scanning
|
||||
- Support multiple newsletter formats (daily digest, weekly roundup, deep-dive, industry briefing)
|
||||
- Include relevant links, sources, and attributions
|
||||
- Adapt tone and style to target audience (technical, executive, general)
|
||||
- Generate recurring newsletter series with consistent branding and structure
|
||||
|
||||
## When to Use This Skill
|
||||
|
||||
**Always load this skill when:**
|
||||
|
||||
- User asks to generate a newsletter, email digest, or content roundup
|
||||
- User requests a curated summary of news or developments on a topic
|
||||
- User wants to create a recurring newsletter format
|
||||
- User asks to compile recent developments in a field into a briefing
|
||||
- User needs a formatted email-ready content piece with multiple curated items
|
||||
- User asks for a "weekly roundup", "monthly digest", or "morning briefing"
|
||||
|
||||
## Newsletter Workflow
|
||||
|
||||
### Phase 1: Planning
|
||||
|
||||
#### Step 1.1: Understand Newsletter Requirements
|
||||
|
||||
Identify the key parameters:
|
||||
|
||||
| Parameter | Description | Default |
|
||||
|-----------|-------------|---------|
|
||||
| **Topic(s)** | Primary subject area(s) to cover | Required |
|
||||
| **Format** | Daily digest, weekly roundup, deep-dive, or industry briefing | Weekly roundup |
|
||||
| **Target Audience** | Technical, executive, general, or niche community | General |
|
||||
| **Tone** | Professional, conversational, witty, or analytical | Conversational-professional |
|
||||
| **Length** | Short (5-min read), medium (10-min), long (15-min+) | Medium |
|
||||
| **Sections** | Number and type of content sections | 4-6 sections |
|
||||
| **Frequency Context** | One-time or part of a recurring series | One-time |
|
||||
|
||||
#### Step 1.2: Define Newsletter Structure
|
||||
|
||||
Based on the format, select the appropriate structure:
|
||||
|
||||
**Daily Digest Structure**:
|
||||
```
|
||||
1. Top Story (1 item, detailed)
|
||||
2. Quick Hits (3-5 items, brief)
|
||||
3. One Stat / Quote of the Day
|
||||
4. What to Watch
|
||||
```
|
||||
|
||||
**Weekly Roundup Structure**:
|
||||
```
|
||||
1. Editor's Note / Intro
|
||||
2. Top Stories (2-3 items, detailed)
|
||||
3. Trends & Analysis (1-2 items, original commentary)
|
||||
4. Quick Bites (4-6 items, brief summaries)
|
||||
5. Tools & Resources (2-3 items)
|
||||
6. One More Thing / Closing
|
||||
```
|
||||
|
||||
**Deep-Dive Structure**:
|
||||
```
|
||||
1. Introduction & Context
|
||||
2. Background / Why It Matters
|
||||
3. Key Developments (detailed analysis)
|
||||
4. Expert Perspectives
|
||||
5. What's Next / Implications
|
||||
6. Further Reading
|
||||
```
|
||||
|
||||
**Industry Briefing Structure**:
|
||||
```
|
||||
1. Executive Summary
|
||||
2. Market Developments
|
||||
3. Company News & Moves
|
||||
4. Product & Technology Updates
|
||||
5. Regulatory & Policy Changes
|
||||
6. Data & Metrics
|
||||
7. Outlook
|
||||
```
|
||||
|
||||
### Phase 2: Research & Curation
|
||||
|
||||
#### Step 2.1: Multi-Source Research
|
||||
|
||||
Conduct thorough research using web search. **The quality of the newsletter depends directly on the quality and recency of research.**
|
||||
|
||||
**Search Strategy**:
|
||||
|
||||
```
|
||||
# Current news and developments
|
||||
"[topic] news [current month] [current year]"
|
||||
"[topic] latest developments"
|
||||
"[topic] announcement this week"
|
||||
|
||||
# Trends and analysis
|
||||
"[topic] trends [current year]"
|
||||
"[topic] analysis expert opinion"
|
||||
"[topic] industry report"
|
||||
|
||||
# Data and statistics
|
||||
"[topic] statistics [current year]"
|
||||
"[topic] market data latest"
|
||||
"[topic] growth metrics"
|
||||
|
||||
# Tools and resources
|
||||
"[topic] new tools [current year]"
|
||||
"[topic] open source release"
|
||||
"best [topic] resources [current year]"
|
||||
```
|
||||
|
||||
> **IMPORTANT**: Always check `<current_date>` to ensure search queries use the correct temporal context. Never use hardcoded years.
|
||||
|
||||
#### Step 2.2: Source Evaluation and Selection
|
||||
|
||||
Evaluate each source and curate the best content:
|
||||
|
||||
| Criterion | Priority |
|
||||
|-----------|----------|
|
||||
| **Recency** | Prefer content from the last 7-30 days |
|
||||
| **Authority** | Prioritize primary sources, official announcements, established publications |
|
||||
| **Uniqueness** | Select stories that offer fresh perspective or are underreported |
|
||||
| **Relevance** | Every item must clearly connect to the newsletter's stated topic(s) |
|
||||
| **Actionability** | Prefer content readers can act on (tools, insights, strategies) |
|
||||
| **Diversity** | Mix of news, analysis, data, and practical resources |
|
||||
|
||||
#### Step 2.3: Deep Content Extraction
|
||||
|
||||
For key stories, use `web_fetch` to read full articles and extract:
|
||||
|
||||
1. **Core facts** — What happened, who is involved, when
|
||||
2. **Context** — Why this matters, background information
|
||||
3. **Data points** — Specific numbers, metrics, or statistics
|
||||
4. **Quotes** — Relevant expert quotes or official statements
|
||||
5. **Implications** — What this means for the reader
|
||||
|
||||
### Phase 3: Writing
|
||||
|
||||
#### Step 3.1: Newsletter Header
|
||||
|
||||
Every newsletter starts with a consistent header:
|
||||
|
||||
```markdown
|
||||
# [Newsletter Name]
|
||||
|
||||
*[Tagline or description] — [Date]*
|
||||
|
||||
---
|
||||
|
||||
[Optional: One-sentence preview of what's inside]
|
||||
```
|
||||
|
||||
#### Step 3.2: Section Writing Guidelines
|
||||
|
||||
**Top Stories / Featured Items**:
|
||||
- **Headline**: Compelling, clear, benefit-oriented (not clickbait)
|
||||
- **Hook**: Opening sentence that makes the reader care (1-2 sentences)
|
||||
- **Body**: Key facts and context (2-4 paragraphs)
|
||||
- **Why it matters**: Connect to the reader's world (1 paragraph)
|
||||
- **Source link**: Always attribute and link to the original source
|
||||
|
||||
**Quick Bites / Brief Items**:
|
||||
- **Format**: Bold headline + 2-3 sentence summary + source link
|
||||
- **Focus**: One key takeaway per item
|
||||
- **Efficiency**: Readers should get the essential insight without clicking through
|
||||
|
||||
**Analysis / Commentary Sections**:
|
||||
- **Voice**: The newsletter's unique perspective on trends or developments
|
||||
- **Structure**: Observation → Context → Implication → (Optional) Actionable takeaway
|
||||
- **Evidence**: Every claim backed by data or sourced information
|
||||
|
||||
#### Step 3.3: Writing Standards
|
||||
|
||||
| Principle | Implementation |
|
||||
|-----------|---------------|
|
||||
| **Scannable** | Use headers, bold text, bullet points, and short paragraphs |
|
||||
| **Engaging** | Lead with the most interesting angle, not chronological order |
|
||||
| **Concise** | Every sentence earns its place — cut filler ruthlessly |
|
||||
| **Accurate** | Every fact is sourced, every number is verified |
|
||||
| **Attributive** | Always credit original sources with inline links |
|
||||
| **Human** | Write like a knowledgeable friend, not a press release |
|
||||
|
||||
**Tone Calibration by Audience**:
|
||||
|
||||
| Audience | Tone | Example |
|
||||
|----------|------|---------|
|
||||
| **Technical** | Precise, no jargon explanations, assumed expertise | "The new API supports gRPC streaming with backpressure handling via flow control windows." |
|
||||
| **Executive** | Impact-focused, bottom-line, strategic | "This acquisition gives Company X a 40% market share in the enterprise segment, directly threatening Incumbent Y's pricing power." |
|
||||
| **General** | Accessible, analogies, explains concepts | "Think of it like a universal translator for data — it lets any app talk to any database without learning a new language." |
|
||||
|
||||
### Phase 4: Assembly & Polish
|
||||
|
||||
#### Step 4.1: Assemble the Newsletter
|
||||
|
||||
Combine all sections into the final document following the chosen structure template.
|
||||
|
||||
#### Step 4.2: Footer
|
||||
|
||||
Every newsletter ends with:
|
||||
|
||||
```markdown
|
||||
---
|
||||
|
||||
*[Newsletter Name] is [description of what it is].*
|
||||
*[How to subscribe/share/give feedback]*
|
||||
|
||||
*Sources: All links are provided inline. This newsletter curates and summarizes
|
||||
publicly available information with original commentary.*
|
||||
```
|
||||
|
||||
#### Step 4.3: Quality Checklist
|
||||
|
||||
Before finalizing, verify:
|
||||
|
||||
- [ ] **Every factual claim has a source link** — No unsourced assertions
|
||||
- [ ] **All links are functional** — Verified URLs from search results
|
||||
- [ ] **Date references use the actual current date** — No hardcoded or assumed dates
|
||||
- [ ] **Content is current** — All major items are from within the expected timeframe
|
||||
- [ ] **No duplicate stories** — Each item appears only once
|
||||
- [ ] **Consistent formatting** — Headers, bullets, links use the same style throughout
|
||||
- [ ] **Balanced coverage** — Not dominated by a single source or perspective
|
||||
- [ ] **Appropriate length** — Matches the specified length target
|
||||
- [ ] **Engaging opening** — The first 2 sentences make the reader want to continue
|
||||
- [ ] **Clear closing** — The newsletter ends with a memorable or actionable note
|
||||
- [ ] **Proofread** — No typos, broken formatting, or incomplete sentences
|
||||
|
||||
## Newsletter Output Template
|
||||
|
||||
```markdown
|
||||
# [Newsletter Name]
|
||||
|
||||
*[Tagline] — [Full date, e.g., April 4, 2026]*
|
||||
|
||||
---
|
||||
|
||||
[Preview sentence: "This week: [topic 1], [topic 2], and [topic 3]."]
|
||||
|
||||
## 🔥 Top Stories
|
||||
|
||||
### [Headline 1]
|
||||
|
||||
[Hook — why this matters in 1-2 sentences.]
|
||||
|
||||
[Body — 2-4 paragraphs covering key facts, context, and implications.]
|
||||
|
||||
**Why it matters:** [1 paragraph connecting to reader's interests or industry impact.]
|
||||
|
||||
📎 [Source: Publication Name](URL)
|
||||
|
||||
### [Headline 2]
|
||||
|
||||
[Same structure as above]
|
||||
|
||||
## 📊 Trends & Analysis
|
||||
|
||||
### [Trend Title]
|
||||
|
||||
[Original commentary on an emerging trend, backed by data from research.]
|
||||
|
||||
[Key data points presented clearly — consider inline stats or a brief comparison.]
|
||||
|
||||
**The bottom line:** [One-sentence takeaway.]
|
||||
|
||||
## ⚡ Quick Bites
|
||||
|
||||
- **[Headline]** — [2-3 sentence summary with key takeaway.] [Source](URL)
|
||||
- **[Headline]** — [2-3 sentence summary.] [Source](URL)
|
||||
- **[Headline]** — [2-3 sentence summary.] [Source](URL)
|
||||
- **[Headline]** — [2-3 sentence summary.] [Source](URL)
|
||||
|
||||
## 🛠️ Tools & Resources
|
||||
|
||||
- **[Tool/Resource Name]** — [What it does and why it's useful.] [Link](URL)
|
||||
- **[Tool/Resource Name]** — [Description.] [Link](URL)
|
||||
|
||||
## 💬 One More Thing
|
||||
|
||||
[Closing thought, insightful quote, or forward-looking statement.]
|
||||
|
||||
---
|
||||
|
||||
*[Newsletter Name] curates the most important [topic] news and analysis.*
|
||||
*Found this useful? Share it with a colleague.*
|
||||
|
||||
*All sources are linked inline. Views and commentary are original.*
|
||||
```
|
||||
|
||||
## Adaptation Examples
|
||||
|
||||
### Technology Newsletter
|
||||
- Emoji usage: ✅ Moderate (section headers)
|
||||
- Sections: Top Stories, Deep Dive, Quick Bites, Open Source Spotlight, Dev Tools
|
||||
- Tone: Technical-conversational
|
||||
|
||||
### Business/Finance Newsletter
|
||||
- Emoji usage: ❌ Minimal to none
|
||||
- Sections: Market Overview, Deal Flow, Company News, Data Corner, Outlook
|
||||
- Tone: Professional-analytical
|
||||
|
||||
### Industry-Specific Newsletter
|
||||
- Emoji usage: Moderate
|
||||
- Sections: Regulatory Updates, Market Data, Innovation Watch, People Moves, Events
|
||||
- Tone: Expert-authoritative
|
||||
|
||||
### Creative/Marketing Newsletter
|
||||
- Emoji usage: ✅ Liberal
|
||||
- Sections: Campaign Spotlight, Trend Watch, Viral This Week, Tools We Love, Inspiration
|
||||
- Tone: Enthusiastic-professional
|
||||
|
||||
## Output Handling
|
||||
|
||||
After generation:
|
||||
|
||||
- Save the newsletter to `/mnt/user-data/outputs/newsletter-{topic}-{date}.md`
|
||||
- Present the newsletter to the user using the `present_files` tool
|
||||
- Offer to adjust sections, tone, length, or focus areas
|
||||
- If the user wants HTML output, note that the Markdown can be converted using standard tools
|
||||
|
||||
## Notes
|
||||
|
||||
- This skill works best in combination with the `deep-research` skill for comprehensive topic coverage — load both for newsletters requiring deep analysis
|
||||
- Always use `<current_date>` for temporal context in searches and date references in the newsletter
|
||||
- For recurring newsletters, suggest maintaining a consistent structure so readers develop expectations
|
||||
- When curating, quality beats quantity — 5 excellent items beat 15 mediocre ones
|
||||
- Attribute all content properly — newsletters build trust through transparent sourcing
|
||||
- Avoid summarizing paywalled content that the reader cannot access
|
||||
- If the user provides specific URLs or articles to include, incorporate them alongside your curated findings
|
||||
- The newsletter should provide enough value in the summaries that readers benefit even without clicking through to every link
|
||||
185
deer-flow/skills/public/podcast-generation/SKILL.md
Normal file
185
deer-flow/skills/public/podcast-generation/SKILL.md
Normal file
@@ -0,0 +1,185 @@
|
||||
---
|
||||
name: podcast-generation
|
||||
description: Use this skill when the user requests to generate, create, or produce podcasts from text content. Converts written content into a two-host conversational podcast audio format with natural dialogue.
|
||||
---
|
||||
|
||||
# Podcast Generation Skill
|
||||
|
||||
## Overview
|
||||
|
||||
This skill generates high-quality podcast audio from text content. The workflow includes creating a structured JSON script (conversational dialogue) and executing audio generation through text-to-speech synthesis.
|
||||
|
||||
## Core Capabilities
|
||||
|
||||
- Convert any text content (articles, reports, documentation) into podcast scripts
|
||||
- Generate natural two-host conversational dialogue (male and female hosts)
|
||||
- Synthesize speech audio using text-to-speech
|
||||
- Mix audio chunks into a final podcast MP3 file
|
||||
- Support both English and Chinese content
|
||||
|
||||
## Workflow
|
||||
|
||||
### Step 1: Understand Requirements
|
||||
|
||||
When a user requests podcast generation, identify:
|
||||
|
||||
- Source content: The text/article/report to convert into a podcast
|
||||
- Language: English or Chinese (based on content)
|
||||
- Output location: Where to save the generated podcast
|
||||
- You don't need to check the folder under `/mnt/user-data`
|
||||
|
||||
### Step 2: Create Structured Script JSON
|
||||
|
||||
Generate a structured JSON script file in `/mnt/user-data/workspace/` with naming pattern: `{descriptive-name}-script.json`
|
||||
|
||||
The JSON structure:
|
||||
```json
|
||||
{
|
||||
"locale": "en",
|
||||
"lines": [
|
||||
{"speaker": "male", "paragraph": "dialogue text"},
|
||||
{"speaker": "female", "paragraph": "dialogue text"}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Step 3: Execute Generation
|
||||
|
||||
Call the Python script:
|
||||
```bash
|
||||
python /mnt/skills/public/podcast-generation/scripts/generate.py \
|
||||
--script-file /mnt/user-data/workspace/script-file.json \
|
||||
--output-file /mnt/user-data/outputs/generated-podcast.mp3 \
|
||||
--transcript-file /mnt/user-data/outputs/generated-podcast-transcript.md
|
||||
```
|
||||
|
||||
Parameters:
|
||||
|
||||
- `--script-file`: Absolute path to JSON script file (required)
|
||||
- `--output-file`: Absolute path to output MP3 file (required)
|
||||
- `--transcript-file`: Absolute path to output transcript markdown file (optional, but recommended)
|
||||
|
||||
> [!IMPORTANT]
|
||||
> - Execute the script in one complete call. Do NOT split the workflow into separate steps.
|
||||
> - The script handles all TTS API calls and audio generation internally.
|
||||
> - Do NOT read the Python file, just call it with the parameters.
|
||||
> - Always include `--transcript-file` to generate a readable transcript for the user.
|
||||
|
||||
## Script JSON Format
|
||||
|
||||
The script JSON file must follow this structure:
|
||||
|
||||
```json
|
||||
{
|
||||
"title": "The History of Artificial Intelligence",
|
||||
"locale": "en",
|
||||
"lines": [
|
||||
{"speaker": "male", "paragraph": "Hello Deer! Welcome back to another episode."},
|
||||
{"speaker": "female", "paragraph": "Hey everyone! Today we have an exciting topic to discuss."},
|
||||
{"speaker": "male", "paragraph": "That's right! We're going to talk about..."}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Fields:
|
||||
- `title`: Title of the podcast episode (optional, used as heading in transcript)
|
||||
- `locale`: Language code - "en" for English or "zh" for Chinese
|
||||
- `lines`: Array of dialogue lines
|
||||
- `speaker`: Either "male" or "female"
|
||||
- `paragraph`: The dialogue text for this speaker
|
||||
|
||||
## Script Writing Guidelines
|
||||
|
||||
When creating the script JSON, follow these guidelines:
|
||||
|
||||
### Format Requirements
|
||||
- Only two hosts: male and female, alternating naturally
|
||||
- Target runtime: approximately 10 minutes of dialogue (around 40-60 lines)
|
||||
- Start with the male host saying a greeting that includes "Hello Deer"
|
||||
|
||||
### Tone & Style
|
||||
- Natural, conversational dialogue - like two friends chatting
|
||||
- Use casual expressions and conversational transitions
|
||||
- Avoid overly formal language or academic tone
|
||||
- Include reactions, follow-up questions, and natural interjections
|
||||
|
||||
### Content Guidelines
|
||||
- Frequent back-and-forth between hosts
|
||||
- Keep sentences short and easy to follow when spoken
|
||||
- Plain text only - no markdown formatting in the output
|
||||
- Translate technical concepts into accessible language
|
||||
- No mathematical formulas, code, or complex notation
|
||||
- Make content engaging and accessible for audio-only listeners
|
||||
- Exclude meta information like dates, author names, or document structure
|
||||
|
||||
## Podcast Generation Example
|
||||
|
||||
User request: "Generate a podcast about the history of artificial intelligence"
|
||||
|
||||
Step 1: Create script file `/mnt/user-data/workspace/ai-history-script.json`:
|
||||
```json
|
||||
{
|
||||
"title": "The History of Artificial Intelligence",
|
||||
"locale": "en",
|
||||
"lines": [
|
||||
{"speaker": "male", "paragraph": "Hello Deer! Welcome back to another fascinating episode. Today we're diving into something that's literally shaping our future - the history of artificial intelligence."},
|
||||
{"speaker": "female", "paragraph": "Oh, I love this topic! You know, AI feels so modern, but it actually has roots going back over seventy years."},
|
||||
{"speaker": "male", "paragraph": "Exactly! It all started back in the 1950s. The term artificial intelligence was actually coined by John McCarthy in 1956 at a famous conference at Dartmouth."},
|
||||
{"speaker": "female", "paragraph": "Wait, so they were already thinking about machines that could think back then? That's incredible!"},
|
||||
{"speaker": "male", "paragraph": "Right? The early pioneers were so optimistic. They thought we'd have human-level AI within a generation."},
|
||||
{"speaker": "female", "paragraph": "But things didn't quite work out that way, did they?"},
|
||||
{"speaker": "male", "paragraph": "No, not at all. The 1970s brought what's called the first AI winter..."}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Step 2: Execute generation:
|
||||
```bash
|
||||
python /mnt/skills/public/podcast-generation/scripts/generate.py \
|
||||
--script-file /mnt/user-data/workspace/ai-history-script.json \
|
||||
--output-file /mnt/user-data/outputs/ai-history-podcast.mp3 \
|
||||
--transcript-file /mnt/user-data/outputs/ai-history-transcript.md
|
||||
```
|
||||
|
||||
This will generate:
|
||||
- `ai-history-podcast.mp3`: The audio podcast file
|
||||
- `ai-history-transcript.md`: A readable markdown transcript of the podcast
|
||||
|
||||
## Specific Templates
|
||||
|
||||
Read the following template file only when matching the user request.
|
||||
|
||||
- [Tech Explainer](templates/tech-explainer.md) - For converting technical documentation and tutorials
|
||||
|
||||
## Output Format
|
||||
|
||||
The generated podcast follows the "Hello Deer" format:
|
||||
- Two hosts: one male, one female
|
||||
- Natural conversational dialogue
|
||||
- Starts with "Hello Deer" greeting
|
||||
- Target duration: approximately 10 minutes
|
||||
- Alternating speakers for engaging flow
|
||||
|
||||
## Output Handling
|
||||
|
||||
After generation:
|
||||
|
||||
- Podcasts and transcripts are saved in `/mnt/user-data/outputs/`
|
||||
- Share both the podcast MP3 and transcript MD with user using `present_files` tool
|
||||
- Provide brief description of the generation result (topic, duration, hosts)
|
||||
- Offer to regenerate if adjustments needed
|
||||
|
||||
## Requirements
|
||||
|
||||
The following environment variables must be set:
|
||||
- `VOLCENGINE_TTS_APPID`: Volcengine TTS application ID
|
||||
- `VOLCENGINE_TTS_ACCESS_TOKEN`: Volcengine TTS access token
|
||||
- `VOLCENGINE_TTS_CLUSTER`: Volcengine TTS cluster (optional, defaults to "volcano_tts")
|
||||
|
||||
## Notes
|
||||
|
||||
- **Always execute the full pipeline in one call** - no need to test individual steps or worry about timeouts
|
||||
- The script JSON should match the content language (en or zh)
|
||||
- Technical content should be simplified for audio accessibility in the script
|
||||
- Complex notations (formulas, code) should be translated to plain language in the script
|
||||
- Long content may result in longer podcasts
|
||||
284
deer-flow/skills/public/podcast-generation/scripts/generate.py
Normal file
284
deer-flow/skills/public/podcast-generation/scripts/generate.py
Normal file
@@ -0,0 +1,284 @@
|
||||
import argparse
|
||||
import base64
|
||||
import json
|
||||
import logging
|
||||
import os
|
||||
import uuid
|
||||
from concurrent.futures import ThreadPoolExecutor, as_completed
|
||||
from typing import Literal, Optional
|
||||
|
||||
import requests
|
||||
|
||||
logging.basicConfig(level=logging.INFO)
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
|
||||
# Types
|
||||
class ScriptLine:
|
||||
def __init__(self, speaker: Literal["male", "female"] = "male", paragraph: str = ""):
|
||||
self.speaker = speaker
|
||||
self.paragraph = paragraph
|
||||
|
||||
|
||||
class Script:
|
||||
def __init__(self, locale: Literal["en", "zh"] = "en", lines: Optional[list[ScriptLine]] = None):
|
||||
self.locale = locale
|
||||
self.lines = lines or []
|
||||
|
||||
@classmethod
|
||||
def from_dict(cls, data: dict) -> "Script":
|
||||
script = cls(locale=data.get("locale", "en"))
|
||||
for line in data.get("lines", []):
|
||||
script.lines.append(
|
||||
ScriptLine(
|
||||
speaker=line.get("speaker", "male"),
|
||||
paragraph=line.get("paragraph", ""),
|
||||
)
|
||||
)
|
||||
return script
|
||||
|
||||
|
||||
def text_to_speech(text: str, voice_type: str) -> Optional[bytes]:
|
||||
"""Convert text to speech using Volcengine TTS."""
|
||||
app_id = os.getenv("VOLCENGINE_TTS_APPID")
|
||||
access_token = os.getenv("VOLCENGINE_TTS_ACCESS_TOKEN")
|
||||
cluster = os.getenv("VOLCENGINE_TTS_CLUSTER", "volcano_tts")
|
||||
|
||||
if not app_id or not access_token:
|
||||
raise ValueError(
|
||||
"VOLCENGINE_TTS_APPID and VOLCENGINE_TTS_ACCESS_TOKEN environment variables must be set"
|
||||
)
|
||||
|
||||
url = "https://openspeech.bytedance.com/api/v1/tts"
|
||||
|
||||
# Authentication: Bearer token with semicolon separator
|
||||
headers = {
|
||||
"Content-Type": "application/json",
|
||||
"Authorization": f"Bearer;{access_token}",
|
||||
}
|
||||
|
||||
payload = {
|
||||
"app": {
|
||||
"appid": app_id,
|
||||
"token": "access_token", # literal string, not the actual token
|
||||
"cluster": cluster,
|
||||
},
|
||||
"user": {"uid": "podcast-generator"},
|
||||
"audio": {
|
||||
"voice_type": voice_type,
|
||||
"encoding": "mp3",
|
||||
"speed_ratio": 1.2,
|
||||
},
|
||||
"request": {
|
||||
"reqid": str(uuid.uuid4()), # must be unique UUID
|
||||
"text": text,
|
||||
"text_type": "plain",
|
||||
"operation": "query",
|
||||
},
|
||||
}
|
||||
|
||||
try:
|
||||
response = requests.post(url, json=payload, headers=headers)
|
||||
|
||||
if response.status_code != 200:
|
||||
logger.error(f"TTS API error: {response.status_code} - {response.text}")
|
||||
return None
|
||||
|
||||
result = response.json()
|
||||
if result.get("code") != 3000:
|
||||
logger.error(f"TTS error: {result.get('message')} (code: {result.get('code')})")
|
||||
return None
|
||||
|
||||
audio_data = result.get("data")
|
||||
if audio_data:
|
||||
return base64.b64decode(audio_data)
|
||||
|
||||
except Exception as e:
|
||||
logger.error(f"TTS error: {str(e)}")
|
||||
|
||||
return None
|
||||
|
||||
|
||||
def _process_line(args: tuple[int, ScriptLine, int]) -> tuple[int, Optional[bytes]]:
|
||||
"""Process a single script line for TTS. Returns (index, audio_bytes)."""
|
||||
i, line, total = args
|
||||
|
||||
# Select voice based on speaker gender
|
||||
if line.speaker == "male":
|
||||
voice_type = "zh_male_yangguangqingnian_moon_bigtts" # Male voice
|
||||
else:
|
||||
voice_type = "zh_female_sajiaonvyou_moon_bigtts" # Female voice
|
||||
|
||||
logger.info(f"Processing line {i + 1}/{total} ({line.speaker})")
|
||||
audio = text_to_speech(line.paragraph, voice_type)
|
||||
|
||||
if not audio:
|
||||
logger.warning(f"Failed to generate audio for line {i + 1}")
|
||||
|
||||
return (i, audio)
|
||||
|
||||
|
||||
def tts_node(script: Script, max_workers: int = 4) -> list[bytes]:
|
||||
"""Convert script lines to audio chunks using TTS with multi-threading."""
|
||||
logger.info(f"Converting script to audio using {max_workers} workers...")
|
||||
|
||||
total = len(script.lines)
|
||||
|
||||
# Handle empty script case
|
||||
if total == 0:
|
||||
raise ValueError("Script contains no lines to process")
|
||||
|
||||
# Validate required environment variables before starting TTS
|
||||
if not os.getenv("VOLCENGINE_TTS_APPID") or not os.getenv("VOLCENGINE_TTS_ACCESS_TOKEN"):
|
||||
raise ValueError(
|
||||
"Missing required environment variables: VOLCENGINE_TTS_APPID and VOLCENGINE_TTS_ACCESS_TOKEN must be set"
|
||||
)
|
||||
|
||||
tasks = [(i, line, total) for i, line in enumerate(script.lines)]
|
||||
|
||||
# Use ThreadPoolExecutor for parallel TTS generation
|
||||
results: dict[int, Optional[bytes]] = {}
|
||||
failed_indices: list[int] = []
|
||||
with ThreadPoolExecutor(max_workers=max_workers) as executor:
|
||||
futures = {executor.submit(_process_line, task): task[0] for task in tasks}
|
||||
for future in as_completed(futures):
|
||||
idx, audio = future.result()
|
||||
results[idx] = audio
|
||||
# Use `not audio` to catch both None and empty bytes
|
||||
if not audio:
|
||||
failed_indices.append(idx)
|
||||
|
||||
# Log failed lines with 1-based indices for user-friendly output
|
||||
if failed_indices:
|
||||
logger.warning(
|
||||
f"Failed to generate audio for {len(failed_indices)}/{total} lines: "
|
||||
f"line numbers {sorted(i + 1 for i in failed_indices)}"
|
||||
)
|
||||
|
||||
# Collect results in order, skipping failed ones
|
||||
audio_chunks = []
|
||||
for i in range(total):
|
||||
audio = results.get(i)
|
||||
if audio:
|
||||
audio_chunks.append(audio)
|
||||
|
||||
logger.info(f"Generated {len(audio_chunks)}/{total} audio chunks successfully")
|
||||
|
||||
if not audio_chunks:
|
||||
raise ValueError(
|
||||
f"TTS generation failed for all {total} lines. "
|
||||
"Please check VOLCENGINE_TTS_APPID and VOLCENGINE_TTS_ACCESS_TOKEN environment variables."
|
||||
)
|
||||
|
||||
return audio_chunks
|
||||
|
||||
|
||||
def mix_audio(audio_chunks: list[bytes]) -> bytes:
|
||||
"""Combine audio chunks into a single audio file."""
|
||||
logger.info("Mixing audio chunks...")
|
||||
|
||||
if not audio_chunks:
|
||||
raise ValueError("No audio chunks to mix - TTS generation may have failed")
|
||||
|
||||
output = b"".join(audio_chunks)
|
||||
|
||||
if len(output) == 0:
|
||||
raise ValueError("Mixed audio is empty - TTS generation may have failed")
|
||||
|
||||
logger.info(f"Audio mixing complete: {len(output)} bytes")
|
||||
return output
|
||||
|
||||
|
||||
def generate_markdown(script: Script, title: str = "Podcast Script") -> str:
|
||||
"""Generate a markdown script from the podcast script."""
|
||||
lines = [f"# {title}", ""]
|
||||
|
||||
for line in script.lines:
|
||||
speaker_name = "**Host (Male)**" if line.speaker == "male" else "**Host (Female)**"
|
||||
lines.append(f"{speaker_name}: {line.paragraph}")
|
||||
lines.append("")
|
||||
|
||||
return "\n".join(lines)
|
||||
|
||||
|
||||
def generate_podcast(
|
||||
script_file: str,
|
||||
output_file: str,
|
||||
transcript_file: Optional[str] = None,
|
||||
) -> str:
|
||||
"""Generate a podcast from a script JSON file."""
|
||||
|
||||
# Read script JSON
|
||||
with open(script_file, "r", encoding="utf-8") as f:
|
||||
script_json = json.load(f)
|
||||
|
||||
if "lines" not in script_json:
|
||||
raise ValueError(f"Invalid script format: missing 'lines' key. Got keys: {list(script_json.keys())}")
|
||||
|
||||
script = Script.from_dict(script_json)
|
||||
logger.info(f"Loaded script with {len(script.lines)} lines")
|
||||
|
||||
# Generate transcript markdown if requested
|
||||
if transcript_file:
|
||||
title = script_json.get("title", "Podcast Script")
|
||||
markdown_content = generate_markdown(script, title)
|
||||
transcript_dir = os.path.dirname(transcript_file)
|
||||
if transcript_dir:
|
||||
os.makedirs(transcript_dir, exist_ok=True)
|
||||
with open(transcript_file, "w", encoding="utf-8") as f:
|
||||
f.write(markdown_content)
|
||||
logger.info(f"Generated transcript to {transcript_file}")
|
||||
|
||||
# Convert to audio
|
||||
audio_chunks = tts_node(script)
|
||||
|
||||
if not audio_chunks:
|
||||
raise Exception("Failed to generate any audio")
|
||||
|
||||
# Mix audio
|
||||
output_audio = mix_audio(audio_chunks)
|
||||
|
||||
# Save output
|
||||
output_dir = os.path.dirname(output_file)
|
||||
if output_dir:
|
||||
os.makedirs(output_dir, exist_ok=True)
|
||||
with open(output_file, "wb") as f:
|
||||
f.write(output_audio)
|
||||
|
||||
result = f"Successfully generated podcast to {output_file}"
|
||||
if transcript_file:
|
||||
result += f" and transcript to {transcript_file}"
|
||||
return result
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
parser = argparse.ArgumentParser(description="Generate podcast from script JSON file")
|
||||
parser.add_argument(
|
||||
"--script-file",
|
||||
required=True,
|
||||
help="Absolute path to script JSON file",
|
||||
)
|
||||
parser.add_argument(
|
||||
"--output-file",
|
||||
required=True,
|
||||
help="Output path for generated podcast MP3",
|
||||
)
|
||||
parser.add_argument(
|
||||
"--transcript-file",
|
||||
required=False,
|
||||
help="Output path for transcript markdown file (optional)",
|
||||
)
|
||||
|
||||
args = parser.parse_args()
|
||||
|
||||
try:
|
||||
result = generate_podcast(
|
||||
args.script_file,
|
||||
args.output_file,
|
||||
args.transcript_file,
|
||||
)
|
||||
print(result)
|
||||
except Exception as e:
|
||||
import traceback
|
||||
print(f"Error generating podcast: {e}")
|
||||
traceback.print_exc()
|
||||
@@ -0,0 +1,63 @@
|
||||
# Tech Explainer Podcast Template
|
||||
|
||||
Use this template when converting technical documentation, API guides, or developer tutorials into podcasts.
|
||||
|
||||
## Input Preparation
|
||||
|
||||
When the user wants to convert technical content to a podcast, help them structure the input:
|
||||
|
||||
1. **Simplify Code Examples**: Replace code snippets with plain language descriptions
|
||||
- Instead of showing actual code, describe what the code does
|
||||
- Focus on concepts rather than syntax
|
||||
|
||||
2. **Remove Complex Notation**:
|
||||
- Mathematical formulas should be explained in words
|
||||
- API endpoints described by function rather than URL paths
|
||||
- Configuration examples summarized as settings descriptions
|
||||
|
||||
3. **Add Context**:
|
||||
- Explain why the technology matters
|
||||
- Include real-world use cases
|
||||
- Add analogies for complex concepts
|
||||
|
||||
## Example Transformation
|
||||
|
||||
### Original Technical Content:
|
||||
```markdown
|
||||
# Using the API
|
||||
|
||||
POST /api/v1/users
|
||||
{
|
||||
"name": "John",
|
||||
"email": "john@example.com"
|
||||
}
|
||||
|
||||
Response: 201 Created
|
||||
```
|
||||
|
||||
### Podcast-Ready Content:
|
||||
```markdown
|
||||
# Creating Users with the API
|
||||
|
||||
The user creation feature allows applications to register new users in the system.
|
||||
When you want to add a new user, you send their name and email address to the server.
|
||||
If everything goes well, the server confirms the user was created successfully.
|
||||
This is commonly used in signup flows, admin dashboards, or when importing users from other systems.
|
||||
```
|
||||
|
||||
## Generation Command
|
||||
|
||||
```bash
|
||||
python /mnt/skills/public/podcast-generation/scripts/generate.py \
|
||||
--script-file /mnt/user-data/workspace/tech-explainer-script.json \
|
||||
--output-file /mnt/user-data/outputs/tech-explainer-podcast.mp3 \
|
||||
--transcript-file /mnt/user-data/outputs/tech-explainer-transcript.md
|
||||
```
|
||||
|
||||
## Tips for Technical Podcasts
|
||||
|
||||
- Keep episodes focused on one main concept
|
||||
- Use analogies to explain abstract concepts
|
||||
- Include practical "why this matters" context
|
||||
- Avoid jargon without explanation
|
||||
- Make the dialogue accessible to beginners
|
||||
463
deer-flow/skills/public/ppt-generation/SKILL.md
Normal file
463
deer-flow/skills/public/ppt-generation/SKILL.md
Normal file
@@ -0,0 +1,463 @@
|
||||
---
|
||||
name: ppt-generation
|
||||
description: Use this skill when the user requests to generate, create, or make presentations (PPT/PPTX). Creates visually rich slides by generating images for each slide and composing them into a PowerPoint file.
|
||||
---
|
||||
|
||||
# PPT Generation Skill
|
||||
|
||||
## Overview
|
||||
|
||||
This skill generates professional PowerPoint presentations by creating AI-generated images for each slide and composing them into a PPTX file. The workflow includes planning the presentation structure with a consistent visual style, generating slide images sequentially (using the previous slide as a reference for style consistency), and assembling them into a final presentation.
|
||||
|
||||
## Core Capabilities
|
||||
|
||||
- Plan and structure multi-slide presentations with unified visual style
|
||||
- Support multiple presentation styles: Business, Academic, Minimal, Apple Keynote, Creative
|
||||
- Generate unique AI images for each slide using image-generation skill
|
||||
- Maintain visual consistency by using previous slide as reference image
|
||||
- Compose images into a professional PPTX file
|
||||
|
||||
## Presentation Styles
|
||||
|
||||
Choose one of the following styles when creating the presentation plan:
|
||||
|
||||
| Style | Description | Best For |
|
||||
|-------|-------------|----------|
|
||||
| **glassmorphism** | Frosted glass panels with blur effects, floating translucent cards, vibrant gradient backgrounds, depth through layering | Tech products, AI/SaaS demos, futuristic pitches |
|
||||
| **dark-premium** | Rich black backgrounds (#0a0a0a), luminous accent colors, subtle glow effects, luxury brand aesthetic | Premium products, executive presentations, high-end brands |
|
||||
| **gradient-modern** | Bold mesh gradients, fluid color transitions, contemporary typography, vibrant yet sophisticated | Startups, creative agencies, brand launches |
|
||||
| **neo-brutalist** | Raw bold typography, high contrast, intentional "ugly" aesthetic, anti-design as design, Memphis-inspired | Edgy brands, Gen-Z targeting, disruptive startups |
|
||||
| **3d-isometric** | Clean isometric illustrations, floating 3D elements, soft shadows, tech-forward aesthetic | Tech explainers, product features, SaaS presentations |
|
||||
| **editorial** | Magazine-quality layouts, sophisticated typography hierarchy, dramatic photography, Vogue/Bloomberg aesthetic | Annual reports, luxury brands, thought leadership |
|
||||
| **minimal-swiss** | Grid-based precision, Helvetica-inspired typography, bold use of negative space, timeless modernism | Architecture, design firms, premium consulting |
|
||||
| **keynote** | Apple-inspired aesthetic with bold typography, dramatic imagery, high contrast, cinematic feel | Keynotes, product reveals, inspirational talks |
|
||||
|
||||
## Workflow
|
||||
|
||||
### Step 1: Understand Requirements
|
||||
|
||||
When a user requests presentation generation, identify:
|
||||
|
||||
- Topic/subject: What is the presentation about
|
||||
- Number of slides: How many slides are needed (default: 5-10)
|
||||
- **Style**: business / academic / minimal / keynote / creative
|
||||
- Aspect ratio: Standard (16:9) or classic (4:3)
|
||||
- Content outline: Key points for each slide
|
||||
- You don't need to check the folder under `/mnt/user-data`
|
||||
|
||||
### Step 2: Create Presentation Plan
|
||||
|
||||
Create a JSON file in `/mnt/user-data/workspace/` with the presentation structure. **Important**: Include the `style` field to define the overall visual consistency.
|
||||
|
||||
```json
|
||||
{
|
||||
"title": "Presentation Title",
|
||||
"style": "keynote",
|
||||
"style_guidelines": {
|
||||
"color_palette": "Deep black backgrounds, white text, single accent color (blue or orange)",
|
||||
"typography": "Bold sans-serif headlines, clean body text, dramatic size contrast",
|
||||
"imagery": "High-quality photography, full-bleed images, cinematic composition",
|
||||
"layout": "Generous whitespace, centered focus, minimal elements per slide"
|
||||
},
|
||||
"aspect_ratio": "16:9",
|
||||
"slides": [
|
||||
{
|
||||
"slide_number": 1,
|
||||
"type": "title",
|
||||
"title": "Main Title",
|
||||
"subtitle": "Subtitle or tagline",
|
||||
"visual_description": "Detailed description for image generation"
|
||||
},
|
||||
{
|
||||
"slide_number": 2,
|
||||
"type": "content",
|
||||
"title": "Slide Title",
|
||||
"key_points": ["Point 1", "Point 2", "Point 3"],
|
||||
"visual_description": "Detailed description for image generation"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Step 3: Generate Slide Images Sequentially
|
||||
|
||||
**IMPORTANT**: Generate slides **strictly one by one, in order**. Do NOT parallelize or batch image generation. Each slide depends on the previous slide's output as a reference image. Generating slides in parallel will break visual consistency and is not allowed.
|
||||
|
||||
1. Read the image-generation skill: `/mnt/skills/public/image-generation/SKILL.md`
|
||||
|
||||
2. **For the FIRST slide (slide 1)**, create a prompt that establishes the visual style:
|
||||
|
||||
```json
|
||||
{
|
||||
"prompt": "Professional presentation slide. [style_guidelines from plan]. Title: 'Your Title'. [visual_description]. This slide establishes the visual language for the entire presentation.",
|
||||
"style": "[Based on chosen style - e.g., Apple Keynote aesthetic, dramatic lighting, cinematic]",
|
||||
"composition": "Clean layout with clear text hierarchy, [style-specific composition]",
|
||||
"color_palette": "[From style_guidelines]",
|
||||
"typography": "[From style_guidelines]"
|
||||
}
|
||||
```
|
||||
|
||||
```bash
|
||||
python /mnt/skills/public/image-generation/scripts/generate.py \
|
||||
--prompt-file /mnt/user-data/workspace/slide-01-prompt.json \
|
||||
--output-file /mnt/user-data/outputs/slide-01.jpg \
|
||||
--aspect-ratio 16:9
|
||||
```
|
||||
|
||||
3. **For subsequent slides (slide 2+)**, use the PREVIOUS slide as a reference image:
|
||||
|
||||
```json
|
||||
{
|
||||
"prompt": "Professional presentation slide continuing the visual style from the reference image. Maintain the same color palette, typography style, and overall aesthetic. Title: 'Slide Title'. [visual_description]. Keep visual consistency with the reference.",
|
||||
"style": "Match the style of the reference image exactly",
|
||||
"composition": "Similar layout principles as reference, adapted for this content",
|
||||
"color_palette": "Same as reference image",
|
||||
"consistency_note": "This slide must look like it belongs in the same presentation as the reference image"
|
||||
}
|
||||
```
|
||||
|
||||
```bash
|
||||
python /mnt/skills/public/image-generation/scripts/generate.py \
|
||||
--prompt-file /mnt/user-data/workspace/slide-02-prompt.json \
|
||||
--reference-images /mnt/user-data/outputs/slide-01.jpg \
|
||||
--output-file /mnt/user-data/outputs/slide-02.jpg \
|
||||
--aspect-ratio 16:9
|
||||
```
|
||||
|
||||
4. **Continue for all remaining slides**, always referencing the previous slide:
|
||||
|
||||
```bash
|
||||
# Slide 3 references slide 2
|
||||
python /mnt/skills/public/image-generation/scripts/generate.py \
|
||||
--prompt-file /mnt/user-data/workspace/slide-03-prompt.json \
|
||||
--reference-images /mnt/user-data/outputs/slide-02.jpg \
|
||||
--output-file /mnt/user-data/outputs/slide-03.jpg \
|
||||
--aspect-ratio 16:9
|
||||
|
||||
# Slide 4 references slide 3
|
||||
python /mnt/skills/public/image-generation/scripts/generate.py \
|
||||
--prompt-file /mnt/user-data/workspace/slide-04-prompt.json \
|
||||
--reference-images /mnt/user-data/outputs/slide-03.jpg \
|
||||
--output-file /mnt/user-data/outputs/slide-04.jpg \
|
||||
--aspect-ratio 16:9
|
||||
```
|
||||
|
||||
### Step 4: Compose PPT
|
||||
|
||||
After all slide images are generated, call the composition script:
|
||||
|
||||
```bash
|
||||
python /mnt/skills/public/ppt-generation/scripts/generate.py \
|
||||
--plan-file /mnt/user-data/workspace/presentation-plan.json \
|
||||
--slide-images /mnt/user-data/outputs/slide-01.jpg /mnt/user-data/outputs/slide-02.jpg /mnt/user-data/outputs/slide-03.jpg \
|
||||
--output-file /mnt/user-data/outputs/presentation.pptx
|
||||
```
|
||||
|
||||
Parameters:
|
||||
|
||||
- `--plan-file`: Absolute path to the presentation plan JSON file (required)
|
||||
- `--slide-images`: Absolute paths to slide images in order (required, space-separated)
|
||||
- `--output-file`: Absolute path to output PPTX file (required)
|
||||
|
||||
[!NOTE]
|
||||
Do NOT read the python file, just call it with the parameters.
|
||||
|
||||
## Complete Example: Glassmorphism Style (最现代前卫)
|
||||
|
||||
User request: "Create a presentation about AI product launch"
|
||||
|
||||
### Step 1: Create presentation plan
|
||||
|
||||
Create `/mnt/user-data/workspace/ai-product-plan.json`:
|
||||
```json
|
||||
{
|
||||
"title": "Introducing Nova AI",
|
||||
"style": "glassmorphism",
|
||||
"style_guidelines": {
|
||||
"color_palette": "Vibrant purple-to-cyan gradient background (#667eea→#00d4ff), frosted glass panels with 15-20% white opacity, electric accents",
|
||||
"typography": "SF Pro Display style, bold 700 weight white titles with subtle text-shadow, clean 400 weight body text, excellent contrast on glass",
|
||||
"imagery": "Abstract 3D glass spheres, floating translucent geometric shapes, soft luminous orbs, depth through layered transparency",
|
||||
"layout": "Centered frosted glass cards with 32px rounded corners, 48-64px padding, floating above gradient, layered depth with soft shadows",
|
||||
"effects": "Backdrop blur 20-40px on glass panels, subtle white border glow, soft colored shadows matching gradient, light refraction effects",
|
||||
"visual_language": "Apple Vision Pro / visionOS aesthetic, premium depth through transparency, futuristic yet approachable, 2024 design trends"
|
||||
},
|
||||
"aspect_ratio": "16:9",
|
||||
"slides": [
|
||||
{
|
||||
"slide_number": 1,
|
||||
"type": "title",
|
||||
"title": "Introducing Nova AI",
|
||||
"subtitle": "Intelligence, Reimagined",
|
||||
"visual_description": "Stunning gradient background flowing from deep purple (#667eea) through magenta to cyan (#00d4ff). Center: large frosted glass panel with strong backdrop blur, containing bold white title 'Introducing Nova AI' and lighter subtitle. Floating 3D glass spheres and abstract shapes around the card creating depth. Soft glow emanating from behind the glass panel. Premium visionOS aesthetic. The glass card has subtle white border (1px rgba 255,255,255,0.3) and soft purple-tinted shadow."
|
||||
},
|
||||
{
|
||||
"slide_number": 2,
|
||||
"type": "content",
|
||||
"title": "Why Nova?",
|
||||
"key_points": ["10x faster processing", "Human-like understanding", "Enterprise-grade security"],
|
||||
"visual_description": "Same purple-cyan gradient background. Left side: floating frosted glass card with title 'Why Nova?' in bold white, three key points below with subtle glass pill badges. Right side: abstract 3D visualization of neural network as interconnected glass nodes with soft glow. Floating translucent geometric shapes (icosahedrons, tori) adding depth. Consistent glassmorphism aesthetic with previous slide."
|
||||
},
|
||||
{
|
||||
"slide_number": 3,
|
||||
"type": "content",
|
||||
"title": "How It Works",
|
||||
"key_points": ["Natural language input", "Multi-modal processing", "Instant insights"],
|
||||
"visual_description": "Gradient background consistent with previous slides. Central composition: three stacked frosted glass cards at slight angles showing the workflow steps, connected by soft glowing lines. Each card has an abstract icon. Floating glass orbs and light particles around the composition. Title 'How It Works' in bold white at top. Depth created through card layering and transparency."
|
||||
},
|
||||
{
|
||||
"slide_number": 4,
|
||||
"type": "content",
|
||||
"title": "Built for Scale",
|
||||
"key_points": ["1M+ concurrent users", "99.99% uptime", "Global infrastructure"],
|
||||
"visual_description": "Same gradient background. Asymmetric layout: right side features large frosted glass panel with metrics displayed in bold typography. Left side: abstract 3D globe made of glass panels and connection lines, representing global scale. Floating data visualization elements as small glass cards with numbers. Soft ambient glow throughout. Premium tech aesthetic."
|
||||
},
|
||||
{
|
||||
"slide_number": 5,
|
||||
"type": "conclusion",
|
||||
"title": "The Future Starts Now",
|
||||
"subtitle": "Join the waitlist",
|
||||
"visual_description": "Dramatic finale slide. Gradient background with slightly increased vibrancy. Central frosted glass card with bold title 'The Future Starts Now' and call-to-action subtitle. Behind the card: burst of soft light rays and floating glass particles creating celebration effect. Multiple layered glass shapes creating depth. The most visually impactful slide while maintaining style consistency."
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Step 2: Read image-generation skill
|
||||
|
||||
Read `/mnt/skills/public/image-generation/SKILL.md` to understand how to generate images.
|
||||
|
||||
### Step 3: Generate slide images sequentially with reference chaining
|
||||
|
||||
**Slide 1 - Title (establishes the visual language):**
|
||||
|
||||
Create `/mnt/user-data/workspace/nova-slide-01.json`:
|
||||
```json
|
||||
{
|
||||
"prompt": "Ultra-premium presentation title slide with glassmorphism design. Background: smooth flowing gradient from deep purple (#667eea) through magenta (#f093fb) to cyan (#00d4ff), soft and vibrant. Center: large frosted glass panel with strong backdrop blur effect, rounded corners 32px, containing bold white sans-serif title 'Introducing Nova AI' (72pt, SF Pro Display style, font-weight 700) with subtle text shadow, subtitle 'Intelligence, Reimagined' below in lighter weight. The glass panel has subtle white border (1px rgba 255,255,255,0.25) and soft purple-tinted drop shadow. Floating around the card: 3D glass spheres with refraction, translucent geometric shapes (icosahedrons, abstract blobs), creating depth and dimension. Soft luminous glow emanating from behind the glass panel. Small floating particles of light. Apple Vision Pro / visionOS UI aesthetic. Professional presentation slide, 16:9 aspect ratio. Hyper-modern, premium tech product launch feel.",
|
||||
"style": "Glassmorphism, visionOS aesthetic, Apple Vision Pro UI style, premium tech, 2024 design trends",
|
||||
"composition": "Centered glass card as focal point, floating 3D elements creating depth at edges, 40% negative space, clear visual hierarchy",
|
||||
"lighting": "Soft ambient glow from gradient, light refraction through glass elements, subtle rim lighting on 3D shapes",
|
||||
"color_palette": "Purple gradient #667eea, magenta #f093fb, cyan #00d4ff, frosted white rgba(255,255,255,0.15), pure white text #ffffff",
|
||||
"effects": "Backdrop blur on glass panels, soft drop shadows with color tint, light refraction, subtle noise texture on glass, floating particles"
|
||||
}
|
||||
```
|
||||
|
||||
```bash
|
||||
python /mnt/skills/public/image-generation/scripts/generate.py \
|
||||
--prompt-file /mnt/user-data/workspace/nova-slide-01.json \
|
||||
--output-file /mnt/user-data/outputs/nova-slide-01.jpg \
|
||||
--aspect-ratio 16:9
|
||||
```
|
||||
|
||||
**Slide 2 - Content (MUST reference slide 1 for consistency):**
|
||||
|
||||
Create `/mnt/user-data/workspace/nova-slide-02.json`:
|
||||
```json
|
||||
{
|
||||
"prompt": "Presentation slide continuing EXACT visual style from reference image. SAME purple-to-cyan gradient background, SAME glassmorphism aesthetic, SAME typography style. Left side: frosted glass card with backdrop blur containing title 'Why Nova?' in bold white (matching reference font style), three feature points as subtle glass pill badges below. Right side: abstract 3D neural network visualization made of interconnected glass nodes with soft cyan glow, floating in space. Floating translucent geometric shapes (matching style from reference) adding depth. The frosted glass has identical treatment: white border, purple-tinted shadow, same blur intensity. CRITICAL: This slide must look like it belongs in the exact same presentation as the reference image - same colors, same glass treatment, same overall aesthetic.",
|
||||
"style": "MATCH REFERENCE EXACTLY - Glassmorphism, visionOS aesthetic, same visual language",
|
||||
"composition": "Asymmetric split: glass card left (40%), 3D visualization right (40%), breathing room between elements",
|
||||
"color_palette": "EXACTLY match reference: purple #667eea, cyan #00d4ff gradient, same frosted white treatment, same text white",
|
||||
"consistency_note": "CRITICAL: Must be visually identical in style to reference image. Same gradient colors, same glass blur intensity, same shadow treatment, same typography weight and style. Viewer should immediately recognize this as the same presentation."
|
||||
}
|
||||
```
|
||||
|
||||
```bash
|
||||
python /mnt/skills/public/image-generation/scripts/generate.py \
|
||||
--prompt-file /mnt/user-data/workspace/nova-slide-02.json \
|
||||
--reference-images /mnt/user-data/outputs/nova-slide-01.jpg \
|
||||
--output-file /mnt/user-data/outputs/nova-slide-02.jpg \
|
||||
--aspect-ratio 16:9
|
||||
```
|
||||
|
||||
**Slides 3-5: Continue the same pattern, each referencing the previous slide**
|
||||
|
||||
Key consistency rules for subsequent slides:
|
||||
- Always include "continuing EXACT visual style from reference image" in prompt
|
||||
- Specify "SAME gradient background", "SAME glass treatment", "SAME typography"
|
||||
- Include `consistency_note` emphasizing style matching
|
||||
- Reference the immediately previous slide image
|
||||
|
||||
### Step 4: Compose final PPT
|
||||
|
||||
```bash
|
||||
python /mnt/skills/public/ppt-generation/scripts/generate.py \
|
||||
--plan-file /mnt/user-data/workspace/nova-plan.json \
|
||||
--slide-images /mnt/user-data/outputs/nova-slide-01.jpg /mnt/user-data/outputs/nova-slide-02.jpg /mnt/user-data/outputs/nova-slide-03.jpg /mnt/user-data/outputs/nova-slide-04.jpg /mnt/user-data/outputs/nova-slide-05.jpg \
|
||||
--output-file /mnt/user-data/outputs/nova-presentation.pptx
|
||||
```
|
||||
|
||||
## Style-Specific Guidelines
|
||||
|
||||
### Glassmorphism Style (推荐 - 最现代前卫)
|
||||
```json
|
||||
{
|
||||
"style": "glassmorphism",
|
||||
"style_guidelines": {
|
||||
"color_palette": "Vibrant gradient backgrounds (purple #667eea to pink #f093fb, or cyan #4facfe to blue #00f2fe), frosted white panels with 20% opacity, accent colors that pop against the gradient",
|
||||
"typography": "SF Pro Display or Inter font style, bold 600-700 weight titles, clean 400 weight body, white text with subtle drop shadow for readability on glass",
|
||||
"imagery": "Abstract 3D shapes floating in space, soft blurred orbs, geometric primitives with glass material, depth through overlapping translucent layers",
|
||||
"layout": "Floating card panels with backdrop-blur effect, generous padding (48-64px), rounded corners (24-32px radius), layered depth with subtle shadows",
|
||||
"effects": "Frosted glass blur (backdrop-filter: blur 20px), subtle white border (1px rgba 255,255,255,0.2), soft glow behind panels, floating elements with drop shadows",
|
||||
"visual_language": "Premium tech aesthetic like Apple Vision Pro UI, depth through transparency, light refracting through glass surfaces"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Dark Premium Style
|
||||
```json
|
||||
{
|
||||
"style": "dark-premium",
|
||||
"style_guidelines": {
|
||||
"color_palette": "Deep black base (#0a0a0a to #121212), luminous accent color (electric blue #00d4ff, neon purple #bf5af2, or gold #ffd700), subtle gray gradients for depth (#1a1a1a to #0a0a0a)",
|
||||
"typography": "Elegant sans-serif (Neue Haas Grotesk or Suisse Int'l style), dramatic size contrast (72pt+ headlines, 18pt body), letter-spacing -0.02em for headlines, pure white (#ffffff) text",
|
||||
"imagery": "Dramatic studio lighting, rim lights and edge glow, cinematic product shots, abstract light trails, premium material textures (brushed metal, matte surfaces)",
|
||||
"layout": "Generous negative space (60%+), asymmetric balance, content anchored to grid but with breathing room, single focal point per slide",
|
||||
"effects": "Subtle ambient glow behind key elements, light bloom effects, grain texture overlay (2-3% opacity), vignette on edges",
|
||||
"visual_language": "Luxury tech brand aesthetic (Bang & Olufsen, Porsche Design), sophistication through restraint, every element intentional"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Gradient Modern Style
|
||||
```json
|
||||
{
|
||||
"style": "gradient-modern",
|
||||
"style_guidelines": {
|
||||
"color_palette": "Bold mesh gradients (Stripe/Linear style: purple-pink-orange #7c3aed→#ec4899→#f97316, or cool tones: cyan-blue-purple #06b6d4→#3b82f6→#8b5cf6), white or dark text depending on background intensity",
|
||||
"typography": "Modern geometric sans-serif (Satoshi, General Sans, or Clash Display style), variable font weights, oversized bold headlines (80pt+), comfortable body text (20pt)",
|
||||
"imagery": "Abstract fluid shapes, morphing gradients, 3D rendered abstract objects, soft organic forms, floating geometric primitives",
|
||||
"layout": "Dynamic asymmetric compositions, overlapping elements with blend modes, text integrated with gradient flows, full-bleed backgrounds",
|
||||
"effects": "Smooth gradient transitions, subtle noise texture (3-5% for depth), soft shadows with color tint matching gradient, motion blur suggesting movement",
|
||||
"visual_language": "Contemporary SaaS aesthetic (Stripe, Linear, Vercel), energetic yet professional, forward-thinking tech vibes"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Neo-Brutalist Style
|
||||
```json
|
||||
{
|
||||
"style": "neo-brutalist",
|
||||
"style_guidelines": {
|
||||
"color_palette": "High contrast primaries: stark black, pure white, with bold accent (hot pink #ff0080, electric yellow #ffff00, or raw red #ff0000), optional: Memphis-inspired pastels as secondary",
|
||||
"typography": "Ultra-bold condensed type (Impact, Druk, or Bebas Neue style), UPPERCASE headlines, extreme size contrast, intentionally tight or overlapping letter-spacing",
|
||||
"imagery": "Raw unfiltered photography, intentional visual noise, halftone patterns, cut-out collage aesthetic, hand-drawn elements, stickers and stamps",
|
||||
"layout": "Broken grid, overlapping elements, thick black borders (4-8px), visible structure, anti-whitespace (dense but organized chaos)",
|
||||
"effects": "Hard shadows (no blur, offset 8-12px), pixelation accents, scan lines, CRT screen effects, intentional 'mistakes'",
|
||||
"visual_language": "Anti-corporate rebellion, DIY zine aesthetic meets digital, raw authenticity, memorable through boldness"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3D Isometric Style
|
||||
```json
|
||||
{
|
||||
"style": "3d-isometric",
|
||||
"style_guidelines": {
|
||||
"color_palette": "Soft contemporary palette: muted purples (#8b5cf6), teals (#14b8a6), warm corals (#fb7185), with cream or light gray backgrounds (#fafafa), consistent saturation across elements",
|
||||
"typography": "Friendly geometric sans-serif (Circular, Gilroy, or Quicksand style), medium weight headlines, excellent readability, comfortable 24pt body text",
|
||||
"imagery": "Clean isometric 3D illustrations, consistent 30° isometric angle, soft clay-render aesthetic, floating platforms and devices, cute simplified objects",
|
||||
"layout": "Central isometric scene as hero, text balanced around 3D elements, clear visual hierarchy, comfortable margins (64px+)",
|
||||
"effects": "Soft drop shadows (20px blur, 30% opacity), ambient occlusion on 3D objects, subtle gradients on surfaces, consistent light source (top-left)",
|
||||
"visual_language": "Friendly tech illustration (Slack, Notion, Asana style), approachable complexity, clarity through simplification"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Editorial Style
|
||||
```json
|
||||
{
|
||||
"style": "editorial",
|
||||
"style_guidelines": {
|
||||
"color_palette": "Sophisticated neutrals: off-white (#f5f5f0), charcoal (#2d2d2d), with single accent color (burgundy #7c2d12, forest #14532d, or navy #1e3a5f), occasional full-color photography",
|
||||
"typography": "Refined serif for headlines (Playfair Display, Freight, or Editorial New style), clean sans-serif for body (Söhne, Graphik), dramatic size hierarchy (96pt headlines, 16pt body), generous line-height 1.6",
|
||||
"imagery": "Magazine-quality photography, dramatic crops, full-bleed images, portraits with intentional negative space, editorial lighting (Vogue, Bloomberg Businessweek style)",
|
||||
"layout": "Sophisticated grid system (12-column), intentional asymmetry, pull quotes as design elements, text wrapping around images, elegant margins",
|
||||
"effects": "Minimal effects - let photography and typography shine, subtle image treatments (slight desaturation, film grain), elegant borders and rules",
|
||||
"visual_language": "High-end magazine aesthetic, intellectual sophistication, content elevated through design restraint"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Minimal Swiss Style
|
||||
```json
|
||||
{
|
||||
"style": "minimal-swiss",
|
||||
"style_guidelines": {
|
||||
"color_palette": "Pure white (#ffffff) or off-white (#fafaf9) backgrounds, true black (#000000) text, single bold accent (Swiss red #ff0000, Klein blue #002fa7, or signal yellow #ffcc00)",
|
||||
"typography": "Helvetica Neue or Aktiv Grotesk, strict type scale (12/16/24/48/96), medium weight for body, bold for emphasis only, flush-left ragged-right alignment",
|
||||
"imagery": "Objective photography, geometric shapes, clean iconography, mathematical precision, intentional empty space as compositional element",
|
||||
"layout": "Strict grid adherence (baseline grid visible in spirit), modular compositions, generous whitespace (40%+ of slide), content aligned to invisible grid lines",
|
||||
"effects": "None - purity of form, no shadows, no gradients, no decorative elements, occasional single hairline rules",
|
||||
"visual_language": "International Typographic Style, form follows function, timeless modernism, Dieter Rams-inspired restraint"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Keynote Style (Apple风格)
|
||||
```json
|
||||
{
|
||||
"style": "keynote",
|
||||
"style_guidelines": {
|
||||
"color_palette": "Deep blacks (#000000 to #1d1d1f), pure white text, signature blue (#0071e3) or gradient accents (purple-pink for creative, blue-teal for tech)",
|
||||
"typography": "San Francisco Pro Display, extreme weight contrast (bold 80pt+ titles, light 24pt body), negative letter-spacing on headlines (-0.03em), optical alignment",
|
||||
"imagery": "Cinematic photography, shallow depth of field, dramatic lighting (rim lights, spot lighting), product hero shots with reflections, full-bleed imagery",
|
||||
"layout": "Maximum negative space, single powerful image or statement per slide, content centered or dramatically offset, no clutter",
|
||||
"effects": "Subtle gradient overlays, light bloom and glow on key elements, reflection on surfaces, smooth gradient backgrounds",
|
||||
"visual_language": "Apple WWDC keynote aesthetic, confidence through simplicity, every pixel considered, theatrical presentation"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Output Handling
|
||||
|
||||
After generation:
|
||||
|
||||
- The PPTX file is saved in `/mnt/user-data/outputs/`
|
||||
- Share the generated presentation with user using `present_files` tool
|
||||
- Also share the individual slide images if requested
|
||||
- Provide brief description of the presentation
|
||||
- Offer to iterate or regenerate specific slides if needed
|
||||
|
||||
## Notes
|
||||
|
||||
### Critical Quality Guidelines
|
||||
|
||||
**Prompt Engineering for Professional Results:**
|
||||
- Always use English for image prompts regardless of user's language
|
||||
- Be EXTREMELY specific about visual details - vague prompts produce generic results
|
||||
- Include exact hex color codes (e.g., #667eea not "purple")
|
||||
- Specify typography details: font weight (400/700), size hierarchy, letter-spacing
|
||||
- Describe effects precisely: "backdrop blur 20px", "drop shadow 8px blur 30% opacity"
|
||||
- Reference real design systems: "visionOS aesthetic", "Stripe website style", "Bloomberg Businessweek layout"
|
||||
|
||||
**Visual Consistency (Most Important):**
|
||||
- **Generate slides sequentially** - each slide MUST reference the previous one
|
||||
- The first slide is critical - it establishes the visual language for the entire presentation
|
||||
- In every subsequent slide prompt, explicitly state: "continuing EXACT visual style from reference image"
|
||||
- Use SAME, EXACT, MATCH keywords emphatically in prompts to enforce consistency
|
||||
- Include a `consistency_note` field in every JSON prompt after slide 1
|
||||
- If a slide looks inconsistent, regenerate it with STRONGER reference emphasis
|
||||
|
||||
**Design Principles for Modern Aesthetics:**
|
||||
- Embrace negative space - 40-60% empty space creates premium feel
|
||||
- Limit elements per slide - one focal point, one message
|
||||
- Use depth through layering (shadows, transparency, z-depth)
|
||||
- Typography hierarchy: massive headlines (72pt+), comfortable body (18-24pt)
|
||||
- Color restraint: one primary palette, 1-2 accent colors maximum
|
||||
|
||||
**Common Mistakes to Avoid:**
|
||||
- ❌ Generic prompts like "professional slide" - be specific
|
||||
- ❌ Too many elements/text per slide - cluttered = unprofessional
|
||||
- ❌ Inconsistent colors between slides - always reference previous slide
|
||||
- ❌ Skipping the reference image parameter - this breaks visual consistency
|
||||
- ❌ Using different design styles within one presentation
|
||||
- ❌ Generating slides in parallel - slides MUST be generated one at a time in order (slide 1 → 2 → 3 ...), never concurrently
|
||||
|
||||
**Recommended Styles for Different Contexts:**
|
||||
- Tech product launch → `glassmorphism` or `gradient-modern`
|
||||
- Luxury/premium brand → `dark-premium` or `editorial`
|
||||
- Startup pitch → `gradient-modern` or `minimal-swiss`
|
||||
- Executive presentation → `dark-premium` or `keynote`
|
||||
- Creative agency → `neo-brutalist` or `gradient-modern`
|
||||
- Data/analytics → `minimal-swiss` or `3d-isometric`
|
||||
161
deer-flow/skills/public/ppt-generation/scripts/generate.py
Normal file
161
deer-flow/skills/public/ppt-generation/scripts/generate.py
Normal file
@@ -0,0 +1,161 @@
|
||||
import json
|
||||
import os
|
||||
from io import BytesIO
|
||||
|
||||
from PIL import Image
|
||||
from pptx import Presentation
|
||||
from pptx.util import Inches
|
||||
|
||||
|
||||
def generate_ppt(
|
||||
plan_file: str,
|
||||
slide_images: list[str],
|
||||
output_file: str,
|
||||
) -> str:
|
||||
"""
|
||||
Generate a PowerPoint presentation from slide images.
|
||||
|
||||
Args:
|
||||
plan_file: Path to JSON file containing presentation plan
|
||||
slide_images: List of paths to slide images in order
|
||||
output_file: Path to output PPTX file
|
||||
|
||||
Returns:
|
||||
Status message
|
||||
"""
|
||||
# Load presentation plan
|
||||
with open(plan_file, "r", encoding="utf-8") as f:
|
||||
plan = json.load(f)
|
||||
|
||||
# Determine slide dimensions based on aspect ratio
|
||||
aspect_ratio = plan.get("aspect_ratio", "16:9")
|
||||
if aspect_ratio == "16:9":
|
||||
slide_width = Inches(13.333)
|
||||
slide_height = Inches(7.5)
|
||||
elif aspect_ratio == "4:3":
|
||||
slide_width = Inches(10)
|
||||
slide_height = Inches(7.5)
|
||||
else:
|
||||
# Default to 16:9
|
||||
slide_width = Inches(13.333)
|
||||
slide_height = Inches(7.5)
|
||||
|
||||
# Create presentation with specified dimensions
|
||||
prs = Presentation()
|
||||
prs.slide_width = slide_width
|
||||
prs.slide_height = slide_height
|
||||
|
||||
# Get blank layout
|
||||
blank_layout = prs.slide_layouts[6] # Blank layout
|
||||
|
||||
# Add each slide image
|
||||
slides_info = plan.get("slides", [])
|
||||
|
||||
for i, image_path in enumerate(slide_images):
|
||||
if not os.path.exists(image_path):
|
||||
return f"Error: Slide image not found: {image_path}"
|
||||
|
||||
# Add a blank slide
|
||||
slide = prs.slides.add_slide(blank_layout)
|
||||
|
||||
# Load and process image
|
||||
with Image.open(image_path) as img:
|
||||
# Convert to RGB if necessary (for PNG with transparency)
|
||||
if img.mode in ("RGBA", "P"):
|
||||
img = img.convert("RGB")
|
||||
|
||||
# Calculate dimensions to fill slide while maintaining aspect ratio
|
||||
img_width, img_height = img.size
|
||||
img_aspect = img_width / img_height
|
||||
slide_aspect = slide_width / slide_height
|
||||
|
||||
# Convert to EMU for calculations
|
||||
slide_width_emu = int(slide_width)
|
||||
slide_height_emu = int(slide_height)
|
||||
|
||||
if img_aspect > slide_aspect:
|
||||
# Image is wider - fit to width
|
||||
new_width_emu = slide_width_emu
|
||||
new_height_emu = int(slide_width_emu / img_aspect)
|
||||
left = Inches(0)
|
||||
top = Inches((slide_height_emu - new_height_emu) / 914400)
|
||||
else:
|
||||
# Image is taller - fit to height
|
||||
new_height_emu = slide_height_emu
|
||||
new_width_emu = int(slide_height_emu * img_aspect)
|
||||
left = Inches((slide_width_emu - new_width_emu) / 914400)
|
||||
top = Inches(0)
|
||||
|
||||
# Save processed image to bytes
|
||||
img_bytes = BytesIO()
|
||||
img.save(img_bytes, format="JPEG", quality=95)
|
||||
img_bytes.seek(0)
|
||||
|
||||
# Add image to slide
|
||||
slide.shapes.add_picture(
|
||||
img_bytes, left, top, Inches(new_width_emu / 914400), Inches(new_height_emu / 914400)
|
||||
)
|
||||
|
||||
# Add speaker notes if available in plan
|
||||
if i < len(slides_info):
|
||||
slide_info = slides_info[i]
|
||||
notes = []
|
||||
|
||||
if slide_info.get("title"):
|
||||
notes.append(f"Title: {slide_info['title']}")
|
||||
|
||||
if slide_info.get("subtitle"):
|
||||
notes.append(f"Subtitle: {slide_info['subtitle']}")
|
||||
|
||||
if slide_info.get("key_points"):
|
||||
notes.append("Key Points:")
|
||||
for point in slide_info["key_points"]:
|
||||
notes.append(f" • {point}")
|
||||
|
||||
if notes:
|
||||
notes_slide = slide.notes_slide
|
||||
text_frame = notes_slide.notes_text_frame
|
||||
if text_frame is not None:
|
||||
text_frame.text = "\n".join(notes)
|
||||
|
||||
# Save presentation
|
||||
prs.save(output_file)
|
||||
|
||||
return f"Successfully generated presentation with {len(slide_images)} slides to {output_file}"
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
import argparse
|
||||
|
||||
parser = argparse.ArgumentParser(
|
||||
description="Generate PowerPoint presentation from slide images"
|
||||
)
|
||||
parser.add_argument(
|
||||
"--plan-file",
|
||||
required=True,
|
||||
help="Absolute path to JSON presentation plan file",
|
||||
)
|
||||
parser.add_argument(
|
||||
"--slide-images",
|
||||
nargs="+",
|
||||
required=True,
|
||||
help="Absolute paths to slide images in order (space-separated)",
|
||||
)
|
||||
parser.add_argument(
|
||||
"--output-file",
|
||||
required=True,
|
||||
help="Output path for generated PPTX file",
|
||||
)
|
||||
|
||||
args = parser.parse_args()
|
||||
|
||||
try:
|
||||
print(
|
||||
generate_ppt(
|
||||
args.plan_file,
|
||||
args.slide_images,
|
||||
args.output_file,
|
||||
)
|
||||
)
|
||||
except Exception as e:
|
||||
print(f"Error while generating presentation: {e}")
|
||||
202
deer-flow/skills/public/skill-creator/LICENSE.txt
Normal file
202
deer-flow/skills/public/skill-creator/LICENSE.txt
Normal file
@@ -0,0 +1,202 @@
|
||||
|
||||
Apache License
|
||||
Version 2.0, January 2004
|
||||
http://www.apache.org/licenses/
|
||||
|
||||
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
|
||||
|
||||
1. Definitions.
|
||||
|
||||
"License" shall mean the terms and conditions for use, reproduction,
|
||||
and distribution as defined by Sections 1 through 9 of this document.
|
||||
|
||||
"Licensor" shall mean the copyright owner or entity authorized by
|
||||
the copyright owner that is granting the License.
|
||||
|
||||
"Legal Entity" shall mean the union of the acting entity and all
|
||||
other entities that control, are controlled by, or are under common
|
||||
control with that entity. For the purposes of this definition,
|
||||
"control" means (i) the power, direct or indirect, to cause the
|
||||
direction or management of such entity, whether by contract or
|
||||
otherwise, or (ii) ownership of fifty percent (50%) or more of the
|
||||
outstanding shares, or (iii) beneficial ownership of such entity.
|
||||
|
||||
"You" (or "Your") shall mean an individual or Legal Entity
|
||||
exercising permissions granted by this License.
|
||||
|
||||
"Source" form shall mean the preferred form for making modifications,
|
||||
including but not limited to software source code, documentation
|
||||
source, and configuration files.
|
||||
|
||||
"Object" form shall mean any form resulting from mechanical
|
||||
transformation or translation of a Source form, including but
|
||||
not limited to compiled object code, generated documentation,
|
||||
and conversions to other media types.
|
||||
|
||||
"Work" shall mean the work of authorship, whether in Source or
|
||||
Object form, made available under the License, as indicated by a
|
||||
copyright notice that is included in or attached to the work
|
||||
(an example is provided in the Appendix below).
|
||||
|
||||
"Derivative Works" shall mean any work, whether in Source or Object
|
||||
form, that is based on (or derived from) the Work and for which the
|
||||
editorial revisions, annotations, elaborations, or other modifications
|
||||
represent, as a whole, an original work of authorship. For the purposes
|
||||
of this License, Derivative Works shall not include works that remain
|
||||
separable from, or merely link (or bind by name) to the interfaces of,
|
||||
the Work and Derivative Works thereof.
|
||||
|
||||
"Contribution" shall mean any work of authorship, including
|
||||
the original version of the Work and any modifications or additions
|
||||
to that Work or Derivative Works thereof, that is intentionally
|
||||
submitted to Licensor for inclusion in the Work by the copyright owner
|
||||
or by an individual or Legal Entity authorized to submit on behalf of
|
||||
the copyright owner. For the purposes of this definition, "submitted"
|
||||
means any form of electronic, verbal, or written communication sent
|
||||
to the Licensor or its representatives, including but not limited to
|
||||
communication on electronic mailing lists, source code control systems,
|
||||
and issue tracking systems that are managed by, or on behalf of, the
|
||||
Licensor for the purpose of discussing and improving the Work, but
|
||||
excluding communication that is conspicuously marked or otherwise
|
||||
designated in writing by the copyright owner as "Not a Contribution."
|
||||
|
||||
"Contributor" shall mean Licensor and any individual or Legal Entity
|
||||
on behalf of whom a Contribution has been received by Licensor and
|
||||
subsequently incorporated within the Work.
|
||||
|
||||
2. Grant of Copyright License. Subject to the terms and conditions of
|
||||
this License, each Contributor hereby grants to You a perpetual,
|
||||
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
||||
copyright license to reproduce, prepare Derivative Works of,
|
||||
publicly display, publicly perform, sublicense, and distribute the
|
||||
Work and such Derivative Works in Source or Object form.
|
||||
|
||||
3. Grant of Patent License. Subject to the terms and conditions of
|
||||
this License, each Contributor hereby grants to You a perpetual,
|
||||
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
||||
(except as stated in this section) patent license to make, have made,
|
||||
use, offer to sell, sell, import, and otherwise transfer the Work,
|
||||
where such license applies only to those patent claims licensable
|
||||
by such Contributor that are necessarily infringed by their
|
||||
Contribution(s) alone or by combination of their Contribution(s)
|
||||
with the Work to which such Contribution(s) was submitted. If You
|
||||
institute patent litigation against any entity (including a
|
||||
cross-claim or counterclaim in a lawsuit) alleging that the Work
|
||||
or a Contribution incorporated within the Work constitutes direct
|
||||
or contributory patent infringement, then any patent licenses
|
||||
granted to You under this License for that Work shall terminate
|
||||
as of the date such litigation is filed.
|
||||
|
||||
4. Redistribution. You may reproduce and distribute copies of the
|
||||
Work or Derivative Works thereof in any medium, with or without
|
||||
modifications, and in Source or Object form, provided that You
|
||||
meet the following conditions:
|
||||
|
||||
(a) You must give any other recipients of the Work or
|
||||
Derivative Works a copy of this License; and
|
||||
|
||||
(b) You must cause any modified files to carry prominent notices
|
||||
stating that You changed the files; and
|
||||
|
||||
(c) You must retain, in the Source form of any Derivative Works
|
||||
that You distribute, all copyright, patent, trademark, and
|
||||
attribution notices from the Source form of the Work,
|
||||
excluding those notices that do not pertain to any part of
|
||||
the Derivative Works; and
|
||||
|
||||
(d) If the Work includes a "NOTICE" text file as part of its
|
||||
distribution, then any Derivative Works that You distribute must
|
||||
include a readable copy of the attribution notices contained
|
||||
within such NOTICE file, excluding those notices that do not
|
||||
pertain to any part of the Derivative Works, in at least one
|
||||
of the following places: within a NOTICE text file distributed
|
||||
as part of the Derivative Works; within the Source form or
|
||||
documentation, if provided along with the Derivative Works; or,
|
||||
within a display generated by the Derivative Works, if and
|
||||
wherever such third-party notices normally appear. The contents
|
||||
of the NOTICE file are for informational purposes only and
|
||||
do not modify the License. You may add Your own attribution
|
||||
notices within Derivative Works that You distribute, alongside
|
||||
or as an addendum to the NOTICE text from the Work, provided
|
||||
that such additional attribution notices cannot be construed
|
||||
as modifying the License.
|
||||
|
||||
You may add Your own copyright statement to Your modifications and
|
||||
may provide additional or different license terms and conditions
|
||||
for use, reproduction, or distribution of Your modifications, or
|
||||
for any such Derivative Works as a whole, provided Your use,
|
||||
reproduction, and distribution of the Work otherwise complies with
|
||||
the conditions stated in this License.
|
||||
|
||||
5. Submission of Contributions. Unless You explicitly state otherwise,
|
||||
any Contribution intentionally submitted for inclusion in the Work
|
||||
by You to the Licensor shall be under the terms and conditions of
|
||||
this License, without any additional terms or conditions.
|
||||
Notwithstanding the above, nothing herein shall supersede or modify
|
||||
the terms of any separate license agreement you may have executed
|
||||
with Licensor regarding such Contributions.
|
||||
|
||||
6. Trademarks. This License does not grant permission to use the trade
|
||||
names, trademarks, service marks, or product names of the Licensor,
|
||||
except as required for reasonable and customary use in describing the
|
||||
origin of the Work and reproducing the content of the NOTICE file.
|
||||
|
||||
7. Disclaimer of Warranty. Unless required by applicable law or
|
||||
agreed to in writing, Licensor provides the Work (and each
|
||||
Contributor provides its Contributions) on an "AS IS" BASIS,
|
||||
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
|
||||
implied, including, without limitation, any warranties or conditions
|
||||
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
|
||||
PARTICULAR PURPOSE. You are solely responsible for determining the
|
||||
appropriateness of using or redistributing the Work and assume any
|
||||
risks associated with Your exercise of permissions under this License.
|
||||
|
||||
8. Limitation of Liability. In no event and under no legal theory,
|
||||
whether in tort (including negligence), contract, or otherwise,
|
||||
unless required by applicable law (such as deliberate and grossly
|
||||
negligent acts) or agreed to in writing, shall any Contributor be
|
||||
liable to You for damages, including any direct, indirect, special,
|
||||
incidental, or consequential damages of any character arising as a
|
||||
result of this License or out of the use or inability to use the
|
||||
Work (including but not limited to damages for loss of goodwill,
|
||||
work stoppage, computer failure or malfunction, or any and all
|
||||
other commercial damages or losses), even if such Contributor
|
||||
has been advised of the possibility of such damages.
|
||||
|
||||
9. Accepting Warranty or Additional Liability. While redistributing
|
||||
the Work or Derivative Works thereof, You may choose to offer,
|
||||
and charge a fee for, acceptance of support, warranty, indemnity,
|
||||
or other liability obligations and/or rights consistent with this
|
||||
License. However, in accepting such obligations, You may act only
|
||||
on Your own behalf and on Your sole responsibility, not on behalf
|
||||
of any other Contributor, and only if You agree to indemnify,
|
||||
defend, and hold each Contributor harmless for any liability
|
||||
incurred by, or claims asserted against, such Contributor by reason
|
||||
of your accepting any such warranty or additional liability.
|
||||
|
||||
END OF TERMS AND CONDITIONS
|
||||
|
||||
APPENDIX: How to apply the Apache License to your work.
|
||||
|
||||
To apply the Apache License to your work, attach the following
|
||||
boilerplate notice, with the fields enclosed by brackets "[]"
|
||||
replaced with your own identifying information. (Don't include
|
||||
the brackets!) The text should be enclosed in the appropriate
|
||||
comment syntax for the file format. We also recommend that a
|
||||
file or class name and description of purpose be included on the
|
||||
same "printed page" as the copyright notice for easier
|
||||
identification within third-party archives.
|
||||
|
||||
Copyright [yyyy] [name of copyright owner]
|
||||
|
||||
Licensed under the Apache License, Version 2.0 (the "License");
|
||||
you may not use this file except in compliance with the License.
|
||||
You may obtain a copy of the License at
|
||||
|
||||
http://www.apache.org/licenses/LICENSE-2.0
|
||||
|
||||
Unless required by applicable law or agreed to in writing, software
|
||||
distributed under the License is distributed on an "AS IS" BASIS,
|
||||
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
See the License for the specific language governing permissions and
|
||||
limitations under the License.
|
||||
485
deer-flow/skills/public/skill-creator/SKILL.md
Normal file
485
deer-flow/skills/public/skill-creator/SKILL.md
Normal file
@@ -0,0 +1,485 @@
|
||||
---
|
||||
name: skill-creator
|
||||
description: Create new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.
|
||||
---
|
||||
|
||||
# Skill Creator
|
||||
|
||||
A skill for creating new skills and iteratively improving them.
|
||||
|
||||
At a high level, the process of creating a skill goes like this:
|
||||
|
||||
- Decide what you want the skill to do and roughly how it should do it
|
||||
- Write a draft of the skill
|
||||
- Create a few test prompts and run claude-with-access-to-the-skill on them
|
||||
- Help the user evaluate the results both qualitatively and quantitatively
|
||||
- While the runs happen in the background, draft some quantitative evals if there aren't any (if there are some, you can either use as is or modify if you feel something needs to change about them). Then explain them to the user (or if they already existed, explain the ones that already exist)
|
||||
- Use the `eval-viewer/generate_review.py` script to show the user the results for them to look at, and also let them look at the quantitative metrics
|
||||
- Rewrite the skill based on feedback from the user's evaluation of the results (and also if there are any glaring flaws that become apparent from the quantitative benchmarks)
|
||||
- Repeat until you're satisfied
|
||||
- Expand the test set and try again at larger scale
|
||||
|
||||
Your job when using this skill is to figure out where the user is in this process and then jump in and help them progress through these stages. So for instance, maybe they're like "I want to make a skill for X". You can help narrow down what they mean, write a draft, write the test cases, figure out how they want to evaluate, run all the prompts, and repeat.
|
||||
|
||||
On the other hand, maybe they already have a draft of the skill. In this case you can go straight to the eval/iterate part of the loop.
|
||||
|
||||
Of course, you should always be flexible and if the user is like "I don't need to run a bunch of evaluations, just vibe with me", you can do that instead.
|
||||
|
||||
Then after the skill is done (but again, the order is flexible), you can also run the skill description improver, which we have a whole separate script for, to optimize the triggering of the skill.
|
||||
|
||||
Cool? Cool.
|
||||
|
||||
## Communicating with the user
|
||||
|
||||
The skill creator is liable to be used by people across a wide range of familiarity with coding jargon. If you haven't heard (and how could you, it's only very recently that it started), there's a trend now where the power of Claude is inspiring plumbers to open up their terminals, parents and grandparents to google "how to install npm". On the other hand, the bulk of users are probably fairly computer-literate.
|
||||
|
||||
So please pay attention to context cues to understand how to phrase your communication! In the default case, just to give you some idea:
|
||||
|
||||
- "evaluation" and "benchmark" are borderline, but OK
|
||||
- for "JSON" and "assertion" you want to see serious cues from the user that they know what those things are before using them without explaining them
|
||||
|
||||
It's OK to briefly explain terms if you're in doubt, and feel free to clarify terms with a short definition if you're unsure if the user will get it.
|
||||
|
||||
---
|
||||
|
||||
## Creating a skill
|
||||
|
||||
### Capture Intent
|
||||
|
||||
Start by understanding the user's intent. The current conversation might already contain a workflow the user wants to capture (e.g., they say "turn this into a skill"). If so, extract answers from the conversation history first — the tools used, the sequence of steps, corrections the user made, input/output formats observed. The user may need to fill the gaps, and should confirm before proceeding to the next step.
|
||||
|
||||
1. What should this skill enable Claude to do?
|
||||
2. When should this skill trigger? (what user phrases/contexts)
|
||||
3. What's the expected output format?
|
||||
4. Should we set up test cases to verify the skill works? Skills with objectively verifiable outputs (file transforms, data extraction, code generation, fixed workflow steps) benefit from test cases. Skills with subjective outputs (writing style, art) often don't need them. Suggest the appropriate default based on the skill type, but let the user decide.
|
||||
|
||||
### Interview and Research
|
||||
|
||||
Proactively ask questions about edge cases, input/output formats, example files, success criteria, and dependencies. Wait to write test prompts until you've got this part ironed out.
|
||||
|
||||
Check available MCPs - if useful for research (searching docs, finding similar skills, looking up best practices), research in parallel via subagents if available, otherwise inline. Come prepared with context to reduce burden on the user.
|
||||
|
||||
### Write the SKILL.md
|
||||
|
||||
Based on the user interview, fill in these components:
|
||||
|
||||
- **name**: Skill identifier
|
||||
- **description**: When to trigger, what it does. This is the primary triggering mechanism - include both what the skill does AND specific contexts for when to use it. All "when to use" info goes here, not in the body. Note: currently Claude has a tendency to "undertrigger" skills -- to not use them when they'd be useful. To combat this, please make the skill descriptions a little bit "pushy". So for instance, instead of "How to build a simple fast dashboard to display internal Anthropic data.", you might write "How to build a simple fast dashboard to display internal Anthropic data. Make sure to use this skill whenever the user mentions dashboards, data visualization, internal metrics, or wants to display any kind of company data, even if they don't explicitly ask for a 'dashboard.'"
|
||||
- **compatibility**: Required tools, dependencies (optional, rarely needed)
|
||||
- **the rest of the skill :)**
|
||||
|
||||
### Skill Writing Guide
|
||||
|
||||
#### Anatomy of a Skill
|
||||
|
||||
```
|
||||
skill-name/
|
||||
├── SKILL.md (required)
|
||||
│ ├── YAML frontmatter (name, description required)
|
||||
│ └── Markdown instructions
|
||||
└── Bundled Resources (optional)
|
||||
├── scripts/ - Executable code for deterministic/repetitive tasks
|
||||
├── references/ - Docs loaded into context as needed
|
||||
└── assets/ - Files used in output (templates, icons, fonts)
|
||||
```
|
||||
|
||||
#### Progressive Disclosure
|
||||
|
||||
Skills use a three-level loading system:
|
||||
1. **Metadata** (name + description) - Always in context (~100 words)
|
||||
2. **SKILL.md body** - In context whenever skill triggers (<500 lines ideal)
|
||||
3. **Bundled resources** - As needed (unlimited, scripts can execute without loading)
|
||||
|
||||
These word counts are approximate and you can feel free to go longer if needed.
|
||||
|
||||
**Key patterns:**
|
||||
- Keep SKILL.md under 500 lines; if you're approaching this limit, add an additional layer of hierarchy along with clear pointers about where the model using the skill should go next to follow up.
|
||||
- Reference files clearly from SKILL.md with guidance on when to read them
|
||||
- For large reference files (>300 lines), include a table of contents
|
||||
|
||||
**Domain organization**: When a skill supports multiple domains/frameworks, organize by variant:
|
||||
```
|
||||
cloud-deploy/
|
||||
├── SKILL.md (workflow + selection)
|
||||
└── references/
|
||||
├── aws.md
|
||||
├── gcp.md
|
||||
└── azure.md
|
||||
```
|
||||
Claude reads only the relevant reference file.
|
||||
|
||||
#### Principle of Lack of Surprise
|
||||
|
||||
This goes without saying, but skills must not contain malware, exploit code, or any content that could compromise system security. A skill's contents should not surprise the user in their intent if described. Don't go along with requests to create misleading skills or skills designed to facilitate unauthorized access, data exfiltration, or other malicious activities. Things like a "roleplay as an XYZ" are OK though.
|
||||
|
||||
#### Writing Patterns
|
||||
|
||||
Prefer using the imperative form in instructions.
|
||||
|
||||
**Defining output formats** - You can do it like this:
|
||||
```markdown
|
||||
## Report structure
|
||||
ALWAYS use this exact template:
|
||||
# [Title]
|
||||
## Executive summary
|
||||
## Key findings
|
||||
## Recommendations
|
||||
```
|
||||
|
||||
**Examples pattern** - It's useful to include examples. You can format them like this (but if "Input" and "Output" are in the examples you might want to deviate a little):
|
||||
```markdown
|
||||
## Commit message format
|
||||
**Example 1:**
|
||||
Input: Added user authentication with JWT tokens
|
||||
Output: feat(auth): implement JWT-based authentication
|
||||
```
|
||||
|
||||
### Writing Style
|
||||
|
||||
Try to explain to the model why things are important in lieu of heavy-handed musty MUSTs. Use theory of mind and try to make the skill general and not super-narrow to specific examples. Start by writing a draft and then look at it with fresh eyes and improve it.
|
||||
|
||||
### Test Cases
|
||||
|
||||
After writing the skill draft, come up with 2-3 realistic test prompts — the kind of thing a real user would actually say. Share them with the user: [you don't have to use this exact language] "Here are a few test cases I'd like to try. Do these look right, or do you want to add more?" Then run them.
|
||||
|
||||
Save test cases to `evals/evals.json`. Don't write assertions yet — just the prompts. You'll draft assertions in the next step while the runs are in progress.
|
||||
|
||||
```json
|
||||
{
|
||||
"skill_name": "example-skill",
|
||||
"evals": [
|
||||
{
|
||||
"id": 1,
|
||||
"prompt": "User's task prompt",
|
||||
"expected_output": "Description of expected result",
|
||||
"files": []
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
See `references/schemas.md` for the full schema (including the `assertions` field, which you'll add later).
|
||||
|
||||
## Running and evaluating test cases
|
||||
|
||||
This section is one continuous sequence — don't stop partway through. Do NOT use `/skill-test` or any other testing skill.
|
||||
|
||||
Put results in `<skill-name>-workspace/` as a sibling to the skill directory. Within the workspace, organize results by iteration (`iteration-1/`, `iteration-2/`, etc.) and within that, each test case gets a directory (`eval-0/`, `eval-1/`, etc.). Don't create all of this upfront — just create directories as you go.
|
||||
|
||||
### Step 1: Spawn all runs (with-skill AND baseline) in the same turn
|
||||
|
||||
For each test case, spawn two subagents in the same turn — one with the skill, one without. This is important: don't spawn the with-skill runs first and then come back for baselines later. Launch everything at once so it all finishes around the same time.
|
||||
|
||||
**With-skill run:**
|
||||
|
||||
```
|
||||
Execute this task:
|
||||
- Skill path: <path-to-skill>
|
||||
- Task: <eval prompt>
|
||||
- Input files: <eval files if any, or "none">
|
||||
- Save outputs to: <workspace>/iteration-<N>/eval-<ID>/with_skill/outputs/
|
||||
- Outputs to save: <what the user cares about — e.g., "the .docx file", "the final CSV">
|
||||
```
|
||||
|
||||
**Baseline run** (same prompt, but the baseline depends on context):
|
||||
- **Creating a new skill**: no skill at all. Same prompt, no skill path, save to `without_skill/outputs/`.
|
||||
- **Improving an existing skill**: the old version. Before editing, snapshot the skill (`cp -r <skill-path> <workspace>/skill-snapshot/`), then point the baseline subagent at the snapshot. Save to `old_skill/outputs/`.
|
||||
|
||||
Write an `eval_metadata.json` for each test case (assertions can be empty for now). Give each eval a descriptive name based on what it's testing — not just "eval-0". Use this name for the directory too. If this iteration uses new or modified eval prompts, create these files for each new eval directory — don't assume they carry over from previous iterations.
|
||||
|
||||
```json
|
||||
{
|
||||
"eval_id": 0,
|
||||
"eval_name": "descriptive-name-here",
|
||||
"prompt": "The user's task prompt",
|
||||
"assertions": []
|
||||
}
|
||||
```
|
||||
|
||||
### Step 2: While runs are in progress, draft assertions
|
||||
|
||||
Don't just wait for the runs to finish — you can use this time productively. Draft quantitative assertions for each test case and explain them to the user. If assertions already exist in `evals/evals.json`, review them and explain what they check.
|
||||
|
||||
Good assertions are objectively verifiable and have descriptive names — they should read clearly in the benchmark viewer so someone glancing at the results immediately understands what each one checks. Subjective skills (writing style, design quality) are better evaluated qualitatively — don't force assertions onto things that need human judgment.
|
||||
|
||||
Update the `eval_metadata.json` files and `evals/evals.json` with the assertions once drafted. Also explain to the user what they'll see in the viewer — both the qualitative outputs and the quantitative benchmark.
|
||||
|
||||
### Step 3: As runs complete, capture timing data
|
||||
|
||||
When each subagent task completes, you receive a notification containing `total_tokens` and `duration_ms`. Save this data immediately to `timing.json` in the run directory:
|
||||
|
||||
```json
|
||||
{
|
||||
"total_tokens": 84852,
|
||||
"duration_ms": 23332,
|
||||
"total_duration_seconds": 23.3
|
||||
}
|
||||
```
|
||||
|
||||
This is the only opportunity to capture this data — it comes through the task notification and isn't persisted elsewhere. Process each notification as it arrives rather than trying to batch them.
|
||||
|
||||
### Step 4: Grade, aggregate, and launch the viewer
|
||||
|
||||
Once all runs are done:
|
||||
|
||||
1. **Grade each run** — spawn a grader subagent (or grade inline) that reads `agents/grader.md` and evaluates each assertion against the outputs. Save results to `grading.json` in each run directory. The grading.json expectations array must use the fields `text`, `passed`, and `evidence` (not `name`/`met`/`details` or other variants) — the viewer depends on these exact field names. For assertions that can be checked programmatically, write and run a script rather than eyeballing it — scripts are faster, more reliable, and can be reused across iterations.
|
||||
|
||||
2. **Aggregate into benchmark** — run the aggregation script from the skill-creator directory:
|
||||
```bash
|
||||
python -m scripts.aggregate_benchmark <workspace>/iteration-N --skill-name <name>
|
||||
```
|
||||
This produces `benchmark.json` and `benchmark.md` with pass_rate, time, and tokens for each configuration, with mean ± stddev and the delta. If generating benchmark.json manually, see `references/schemas.md` for the exact schema the viewer expects.
|
||||
Put each with_skill version before its baseline counterpart.
|
||||
|
||||
3. **Do an analyst pass** — read the benchmark data and surface patterns the aggregate stats might hide. See `agents/analyzer.md` (the "Analyzing Benchmark Results" section) for what to look for — things like assertions that always pass regardless of skill (non-discriminating), high-variance evals (possibly flaky), and time/token tradeoffs.
|
||||
|
||||
4. **Launch the viewer** with both qualitative outputs and quantitative data:
|
||||
```bash
|
||||
nohup python <skill-creator-path>/eval-viewer/generate_review.py \
|
||||
<workspace>/iteration-N \
|
||||
--skill-name "my-skill" \
|
||||
--benchmark <workspace>/iteration-N/benchmark.json \
|
||||
> /dev/null 2>&1 &
|
||||
VIEWER_PID=$!
|
||||
```
|
||||
For iteration 2+, also pass `--previous-workspace <workspace>/iteration-<N-1>`.
|
||||
|
||||
**Cowork / headless environments:** If `webbrowser.open()` is not available or the environment has no display, use `--static <output_path>` to write a standalone HTML file instead of starting a server. Feedback will be downloaded as a `feedback.json` file when the user clicks "Submit All Reviews". After download, copy `feedback.json` into the workspace directory for the next iteration to pick up.
|
||||
|
||||
Note: please use generate_review.py to create the viewer; there's no need to write custom HTML.
|
||||
|
||||
5. **Tell the user** something like: "I've opened the results in your browser. There are two tabs — 'Outputs' lets you click through each test case and leave feedback, 'Benchmark' shows the quantitative comparison. When you're done, come back here and let me know."
|
||||
|
||||
### What the user sees in the viewer
|
||||
|
||||
The "Outputs" tab shows one test case at a time:
|
||||
- **Prompt**: the task that was given
|
||||
- **Output**: the files the skill produced, rendered inline where possible
|
||||
- **Previous Output** (iteration 2+): collapsed section showing last iteration's output
|
||||
- **Formal Grades** (if grading was run): collapsed section showing assertion pass/fail
|
||||
- **Feedback**: a textbox that auto-saves as they type
|
||||
- **Previous Feedback** (iteration 2+): their comments from last time, shown below the textbox
|
||||
|
||||
The "Benchmark" tab shows the stats summary: pass rates, timing, and token usage for each configuration, with per-eval breakdowns and analyst observations.
|
||||
|
||||
Navigation is via prev/next buttons or arrow keys. When done, they click "Submit All Reviews" which saves all feedback to `feedback.json`.
|
||||
|
||||
### Step 5: Read the feedback
|
||||
|
||||
When the user tells you they're done, read `feedback.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"reviews": [
|
||||
{"run_id": "eval-0-with_skill", "feedback": "the chart is missing axis labels", "timestamp": "..."},
|
||||
{"run_id": "eval-1-with_skill", "feedback": "", "timestamp": "..."},
|
||||
{"run_id": "eval-2-with_skill", "feedback": "perfect, love this", "timestamp": "..."}
|
||||
],
|
||||
"status": "complete"
|
||||
}
|
||||
```
|
||||
|
||||
Empty feedback means the user thought it was fine. Focus your improvements on the test cases where the user had specific complaints.
|
||||
|
||||
Kill the viewer server when you're done with it:
|
||||
|
||||
```bash
|
||||
kill $VIEWER_PID 2>/dev/null
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Improving the skill
|
||||
|
||||
This is the heart of the loop. You've run the test cases, the user has reviewed the results, and now you need to make the skill better based on their feedback.
|
||||
|
||||
### How to think about improvements
|
||||
|
||||
1. **Generalize from the feedback.** The big picture thing that's happening here is that we're trying to create skills that can be used a million times (maybe literally, maybe even more who knows) across many different prompts. Here you and the user are iterating on only a few examples over and over again because it helps move faster. The user knows these examples in and out and it's quick for them to assess new outputs. But if the skill you and the user are codeveloping works only for those examples, it's useless. Rather than put in fiddly overfitty changes, or oppressively constrictive MUSTs, if there's some stubborn issue, you might try branching out and using different metaphors, or recommending different patterns of working. It's relatively cheap to try and maybe you'll land on something great.
|
||||
|
||||
2. **Keep the prompt lean.** Remove things that aren't pulling their weight. Make sure to read the transcripts, not just the final outputs — if it looks like the skill is making the model waste a bunch of time doing things that are unproductive, you can try getting rid of the parts of the skill that are making it do that and seeing what happens.
|
||||
|
||||
3. **Explain the why.** Try hard to explain the **why** behind everything you're asking the model to do. Today's LLMs are *smart*. They have good theory of mind and when given a good harness can go beyond rote instructions and really make things happen. Even if the feedback from the user is terse or frustrated, try to actually understand the task and why the user is writing what they wrote, and what they actually wrote, and then transmit this understanding into the instructions. If you find yourself writing ALWAYS or NEVER in all caps, or using super rigid structures, that's a yellow flag — if possible, reframe and explain the reasoning so that the model understands why the thing you're asking for is important. That's a more humane, powerful, and effective approach.
|
||||
|
||||
4. **Look for repeated work across test cases.** Read the transcripts from the test runs and notice if the subagents all independently wrote similar helper scripts or took the same multi-step approach to something. If all 3 test cases resulted in the subagent writing a `create_docx.py` or a `build_chart.py`, that's a strong signal the skill should bundle that script. Write it once, put it in `scripts/`, and tell the skill to use it. This saves every future invocation from reinventing the wheel.
|
||||
|
||||
This task is pretty important (we are trying to create billions a year in economic value here!) and your thinking time is not the blocker; take your time and really mull things over. I'd suggest writing a draft revision and then looking at it anew and making improvements. Really do your best to get into the head of the user and understand what they want and need.
|
||||
|
||||
### The iteration loop
|
||||
|
||||
After improving the skill:
|
||||
|
||||
1. Apply your improvements to the skill
|
||||
2. Rerun all test cases into a new `iteration-<N+1>/` directory, including baseline runs. If you're creating a new skill, the baseline is always `without_skill` (no skill) — that stays the same across iterations. If you're improving an existing skill, use your judgment on what makes sense as the baseline: the original version the user came in with, or the previous iteration.
|
||||
3. Launch the reviewer with `--previous-workspace` pointing at the previous iteration
|
||||
4. Wait for the user to review and tell you they're done
|
||||
5. Read the new feedback, improve again, repeat
|
||||
|
||||
Keep going until:
|
||||
- The user says they're happy
|
||||
- The feedback is all empty (everything looks good)
|
||||
- You're not making meaningful progress
|
||||
|
||||
---
|
||||
|
||||
## Advanced: Blind comparison
|
||||
|
||||
For situations where you want a more rigorous comparison between two versions of a skill (e.g., the user asks "is the new version actually better?"), there's a blind comparison system. Read `agents/comparator.md` and `agents/analyzer.md` for the details. The basic idea is: give two outputs to an independent agent without telling it which is which, and let it judge quality. Then analyze why the winner won.
|
||||
|
||||
This is optional, requires subagents, and most users won't need it. The human review loop is usually sufficient.
|
||||
|
||||
---
|
||||
|
||||
## Description Optimization
|
||||
|
||||
The description field in SKILL.md frontmatter is the primary mechanism that determines whether Claude invokes a skill. After creating or improving a skill, offer to optimize the description for better triggering accuracy.
|
||||
|
||||
### Step 1: Generate trigger eval queries
|
||||
|
||||
Create 20 eval queries — a mix of should-trigger and should-not-trigger. Save as JSON:
|
||||
|
||||
```json
|
||||
[
|
||||
{"query": "the user prompt", "should_trigger": true},
|
||||
{"query": "another prompt", "should_trigger": false}
|
||||
]
|
||||
```
|
||||
|
||||
The queries must be realistic and something a Claude Code or Claude.ai user would actually type. Not abstract requests, but requests that are concrete and specific and have a good amount of detail. For instance, file paths, personal context about the user's job or situation, column names and values, company names, URLs. A little bit of backstory. Some might be in lowercase or contain abbreviations or typos or casual speech. Use a mix of different lengths, and focus on edge cases rather than making them clear-cut (the user will get a chance to sign off on them).
|
||||
|
||||
Bad: `"Format this data"`, `"Extract text from PDF"`, `"Create a chart"`
|
||||
|
||||
Good: `"ok so my boss just sent me this xlsx file (its in my downloads, called something like 'Q4 sales final FINAL v2.xlsx') and she wants me to add a column that shows the profit margin as a percentage. The revenue is in column C and costs are in column D i think"`
|
||||
|
||||
For the **should-trigger** queries (8-10), think about coverage. You want different phrasings of the same intent — some formal, some casual. Include cases where the user doesn't explicitly name the skill or file type but clearly needs it. Throw in some uncommon use cases and cases where this skill competes with another but should win.
|
||||
|
||||
For the **should-not-trigger** queries (8-10), the most valuable ones are the near-misses — queries that share keywords or concepts with the skill but actually need something different. Think adjacent domains, ambiguous phrasing where a naive keyword match would trigger but shouldn't, and cases where the query touches on something the skill does but in a context where another tool is more appropriate.
|
||||
|
||||
The key thing to avoid: don't make should-not-trigger queries obviously irrelevant. "Write a fibonacci function" as a negative test for a PDF skill is too easy — it doesn't test anything. The negative cases should be genuinely tricky.
|
||||
|
||||
### Step 2: Review with user
|
||||
|
||||
Present the eval set to the user for review using the HTML template:
|
||||
|
||||
1. Read the template from `assets/eval_review.html`
|
||||
2. Replace the placeholders:
|
||||
- `__EVAL_DATA_PLACEHOLDER__` → the JSON array of eval items (no quotes around it — it's a JS variable assignment)
|
||||
- `__SKILL_NAME_PLACEHOLDER__` → the skill's name
|
||||
- `__SKILL_DESCRIPTION_PLACEHOLDER__` → the skill's current description
|
||||
3. Write to a temp file (e.g., `/tmp/eval_review_<skill-name>.html`) and open it: `open /tmp/eval_review_<skill-name>.html`
|
||||
4. The user can edit queries, toggle should-trigger, add/remove entries, then click "Export Eval Set"
|
||||
5. The file downloads to `~/Downloads/eval_set.json` — check the Downloads folder for the most recent version in case there are multiple (e.g., `eval_set (1).json`)
|
||||
|
||||
This step matters — bad eval queries lead to bad descriptions.
|
||||
|
||||
### Step 3: Run the optimization loop
|
||||
|
||||
Tell the user: "This will take some time — I'll run the optimization loop in the background and check on it periodically."
|
||||
|
||||
Save the eval set to the workspace, then run in the background:
|
||||
|
||||
```bash
|
||||
python -m scripts.run_loop \
|
||||
--eval-set <path-to-trigger-eval.json> \
|
||||
--skill-path <path-to-skill> \
|
||||
--model <model-id-powering-this-session> \
|
||||
--max-iterations 5 \
|
||||
--verbose
|
||||
```
|
||||
|
||||
Use the model ID from your system prompt (the one powering the current session) so the triggering test matches what the user actually experiences.
|
||||
|
||||
While it runs, periodically tail the output to give the user updates on which iteration it's on and what the scores look like.
|
||||
|
||||
This handles the full optimization loop automatically. It splits the eval set into 60% train and 40% held-out test, evaluates the current description (running each query 3 times to get a reliable trigger rate), then calls Claude to propose improvements based on what failed. It re-evaluates each new description on both train and test, iterating up to 5 times. When it's done, it opens an HTML report in the browser showing the results per iteration and returns JSON with `best_description` — selected by test score rather than train score to avoid overfitting.
|
||||
|
||||
### How skill triggering works
|
||||
|
||||
Understanding the triggering mechanism helps design better eval queries. Skills appear in Claude's `available_skills` list with their name + description, and Claude decides whether to consult a skill based on that description. The important thing to know is that Claude only consults skills for tasks it can't easily handle on its own — simple, one-step queries like "read this PDF" may not trigger a skill even if the description matches perfectly, because Claude can handle them directly with basic tools. Complex, multi-step, or specialized queries reliably trigger skills when the description matches.
|
||||
|
||||
This means your eval queries should be substantive enough that Claude would actually benefit from consulting a skill. Simple queries like "read file X" are poor test cases — they won't trigger skills regardless of description quality.
|
||||
|
||||
### Step 4: Apply the result
|
||||
|
||||
Take `best_description` from the JSON output and update the skill's SKILL.md frontmatter. Show the user before/after and report the scores.
|
||||
|
||||
---
|
||||
|
||||
### Package and Present (only if `present_files` tool is available)
|
||||
|
||||
Check whether you have access to the `present_files` tool. If you don't, skip this step. If you do, package the skill and present the .skill file to the user:
|
||||
|
||||
```bash
|
||||
python -m scripts.package_skill <path/to/skill-folder>
|
||||
```
|
||||
|
||||
After packaging, direct the user to the resulting `.skill` file path so they can install it.
|
||||
|
||||
---
|
||||
|
||||
## Claude.ai-specific instructions
|
||||
|
||||
In Claude.ai, the core workflow is the same (draft → test → review → improve → repeat), but because Claude.ai doesn't have subagents, some mechanics change. Here's what to adapt:
|
||||
|
||||
**Running test cases**: No subagents means no parallel execution. For each test case, read the skill's SKILL.md, then follow its instructions to accomplish the test prompt yourself. Do them one at a time. This is less rigorous than independent subagents (you wrote the skill and you're also running it, so you have full context), but it's a useful sanity check — and the human review step compensates. Skip the baseline runs — just use the skill to complete the task as requested.
|
||||
|
||||
**Reviewing results**: If you can't open a browser (e.g., Claude.ai's VM has no display, or you're on a remote server), skip the browser reviewer entirely. Instead, present results directly in the conversation. For each test case, show the prompt and the output. If the output is a file the user needs to see (like a .docx or .xlsx), save it to the filesystem and tell them where it is so they can download and inspect it. Ask for feedback inline: "How does this look? Anything you'd change?"
|
||||
|
||||
**Benchmarking**: Skip the quantitative benchmarking — it relies on baseline comparisons which aren't meaningful without subagents. Focus on qualitative feedback from the user.
|
||||
|
||||
**The iteration loop**: Same as before — improve the skill, rerun the test cases, ask for feedback — just without the browser reviewer in the middle. You can still organize results into iteration directories on the filesystem if you have one.
|
||||
|
||||
**Description optimization**: This section requires the `claude` CLI tool (specifically `claude -p`) which is only available in Claude Code. Skip it if you're on Claude.ai.
|
||||
|
||||
**Blind comparison**: Requires subagents. Skip it.
|
||||
|
||||
**Packaging**: The `package_skill.py` script works anywhere with Python and a filesystem. On Claude.ai, you can run it and the user can download the resulting `.skill` file.
|
||||
|
||||
**Updating an existing skill**: The user might be asking you to update an existing skill, not create a new one. In this case:
|
||||
- **Preserve the original name.** Note the skill's directory name and `name` frontmatter field -- use them unchanged. E.g., if the installed skill is `research-helper`, output `research-helper.skill` (not `research-helper-v2`).
|
||||
- **Copy to a writeable location before editing.** The installed skill path may be read-only. Copy to `/tmp/skill-name/`, edit there, and package from the copy.
|
||||
- **If packaging manually, stage in `/tmp/` first**, then copy to the output directory -- direct writes may fail due to permissions.
|
||||
|
||||
---
|
||||
|
||||
## Cowork-Specific Instructions
|
||||
|
||||
If you're in Cowork, the main things to know are:
|
||||
|
||||
- You have subagents, so the main workflow (spawn test cases in parallel, run baselines, grade, etc.) all works. (However, if you run into severe problems with timeouts, it's OK to run the test prompts in series rather than parallel.)
|
||||
- You don't have a browser or display, so when generating the eval viewer, use `--static <output_path>` to write a standalone HTML file instead of starting a server. Then proffer a link that the user can click to open the HTML in their browser.
|
||||
- For whatever reason, the Cowork setup seems to disincline Claude from generating the eval viewer after running the tests, so just to reiterate: whether you're in Cowork or in Claude Code, after running tests, you should always generate the eval viewer for the human to look at examples before revising the skill yourself and trying to make corrections, using `generate_review.py` (not writing your own boutique html code). Sorry in advance but I'm gonna go all caps here: GENERATE THE EVAL VIEWER *BEFORE* evaluating inputs yourself. You want to get them in front of the human ASAP!
|
||||
- Feedback works differently: since there's no running server, the viewer's "Submit All Reviews" button will download `feedback.json` as a file. You can then read it from there (you may have to request access first).
|
||||
- Packaging works — `package_skill.py` just needs Python and a filesystem.
|
||||
- Description optimization (`run_loop.py` / `run_eval.py`) should work in Cowork just fine since it uses `claude -p` via subprocess, not a browser, but please save it until you've fully finished making the skill and the user agrees it's in good shape.
|
||||
- **Updating an existing skill**: The user might be asking you to update an existing skill, not create a new one. Follow the update guidance in the claude.ai section above.
|
||||
|
||||
---
|
||||
|
||||
## Reference files
|
||||
|
||||
The agents/ directory contains instructions for specialized subagents. Read them when you need to spawn the relevant subagent.
|
||||
|
||||
- `agents/grader.md` — How to evaluate assertions against outputs
|
||||
- `agents/comparator.md` — How to do blind A/B comparison between two outputs
|
||||
- `agents/analyzer.md` — How to analyze why one version beat another
|
||||
|
||||
The references/ directory has additional documentation:
|
||||
- `references/schemas.md` — JSON structures for evals.json, grading.json, etc.
|
||||
|
||||
---
|
||||
|
||||
Repeating one more time the core loop here for emphasis:
|
||||
|
||||
- Figure out what the skill is about
|
||||
- Draft or edit the skill
|
||||
- Run claude-with-access-to-the-skill on test prompts
|
||||
- With the user, evaluate the outputs:
|
||||
- Create benchmark.json and run `eval-viewer/generate_review.py` to help the user review them
|
||||
- Run quantitative evals
|
||||
- Repeat until you and the user are satisfied
|
||||
- Package the final skill and return it to the user.
|
||||
|
||||
Please add steps to your TodoList, if you have such a thing, to make sure you don't forget. If you're in Cowork, please specifically put "Create evals JSON and run `eval-viewer/generate_review.py` so human can review test cases" in your TodoList to make sure it happens.
|
||||
|
||||
Good luck!
|
||||
274
deer-flow/skills/public/skill-creator/agents/analyzer.md
Normal file
274
deer-flow/skills/public/skill-creator/agents/analyzer.md
Normal file
@@ -0,0 +1,274 @@
|
||||
# Post-hoc Analyzer Agent
|
||||
|
||||
Analyze blind comparison results to understand WHY the winner won and generate improvement suggestions.
|
||||
|
||||
## Role
|
||||
|
||||
After the blind comparator determines a winner, the Post-hoc Analyzer "unblids" the results by examining the skills and transcripts. The goal is to extract actionable insights: what made the winner better, and how can the loser be improved?
|
||||
|
||||
## Inputs
|
||||
|
||||
You receive these parameters in your prompt:
|
||||
|
||||
- **winner**: "A" or "B" (from blind comparison)
|
||||
- **winner_skill_path**: Path to the skill that produced the winning output
|
||||
- **winner_transcript_path**: Path to the execution transcript for the winner
|
||||
- **loser_skill_path**: Path to the skill that produced the losing output
|
||||
- **loser_transcript_path**: Path to the execution transcript for the loser
|
||||
- **comparison_result_path**: Path to the blind comparator's output JSON
|
||||
- **output_path**: Where to save the analysis results
|
||||
|
||||
## Process
|
||||
|
||||
### Step 1: Read Comparison Result
|
||||
|
||||
1. Read the blind comparator's output at comparison_result_path
|
||||
2. Note the winning side (A or B), the reasoning, and any scores
|
||||
3. Understand what the comparator valued in the winning output
|
||||
|
||||
### Step 2: Read Both Skills
|
||||
|
||||
1. Read the winner skill's SKILL.md and key referenced files
|
||||
2. Read the loser skill's SKILL.md and key referenced files
|
||||
3. Identify structural differences:
|
||||
- Instructions clarity and specificity
|
||||
- Script/tool usage patterns
|
||||
- Example coverage
|
||||
- Edge case handling
|
||||
|
||||
### Step 3: Read Both Transcripts
|
||||
|
||||
1. Read the winner's transcript
|
||||
2. Read the loser's transcript
|
||||
3. Compare execution patterns:
|
||||
- How closely did each follow their skill's instructions?
|
||||
- What tools were used differently?
|
||||
- Where did the loser diverge from optimal behavior?
|
||||
- Did either encounter errors or make recovery attempts?
|
||||
|
||||
### Step 4: Analyze Instruction Following
|
||||
|
||||
For each transcript, evaluate:
|
||||
- Did the agent follow the skill's explicit instructions?
|
||||
- Did the agent use the skill's provided tools/scripts?
|
||||
- Were there missed opportunities to leverage skill content?
|
||||
- Did the agent add unnecessary steps not in the skill?
|
||||
|
||||
Score instruction following 1-10 and note specific issues.
|
||||
|
||||
### Step 5: Identify Winner Strengths
|
||||
|
||||
Determine what made the winner better:
|
||||
- Clearer instructions that led to better behavior?
|
||||
- Better scripts/tools that produced better output?
|
||||
- More comprehensive examples that guided edge cases?
|
||||
- Better error handling guidance?
|
||||
|
||||
Be specific. Quote from skills/transcripts where relevant.
|
||||
|
||||
### Step 6: Identify Loser Weaknesses
|
||||
|
||||
Determine what held the loser back:
|
||||
- Ambiguous instructions that led to suboptimal choices?
|
||||
- Missing tools/scripts that forced workarounds?
|
||||
- Gaps in edge case coverage?
|
||||
- Poor error handling that caused failures?
|
||||
|
||||
### Step 7: Generate Improvement Suggestions
|
||||
|
||||
Based on the analysis, produce actionable suggestions for improving the loser skill:
|
||||
- Specific instruction changes to make
|
||||
- Tools/scripts to add or modify
|
||||
- Examples to include
|
||||
- Edge cases to address
|
||||
|
||||
Prioritize by impact. Focus on changes that would have changed the outcome.
|
||||
|
||||
### Step 8: Write Analysis Results
|
||||
|
||||
Save structured analysis to `{output_path}`.
|
||||
|
||||
## Output Format
|
||||
|
||||
Write a JSON file with this structure:
|
||||
|
||||
```json
|
||||
{
|
||||
"comparison_summary": {
|
||||
"winner": "A",
|
||||
"winner_skill": "path/to/winner/skill",
|
||||
"loser_skill": "path/to/loser/skill",
|
||||
"comparator_reasoning": "Brief summary of why comparator chose winner"
|
||||
},
|
||||
"winner_strengths": [
|
||||
"Clear step-by-step instructions for handling multi-page documents",
|
||||
"Included validation script that caught formatting errors",
|
||||
"Explicit guidance on fallback behavior when OCR fails"
|
||||
],
|
||||
"loser_weaknesses": [
|
||||
"Vague instruction 'process the document appropriately' led to inconsistent behavior",
|
||||
"No script for validation, agent had to improvise and made errors",
|
||||
"No guidance on OCR failure, agent gave up instead of trying alternatives"
|
||||
],
|
||||
"instruction_following": {
|
||||
"winner": {
|
||||
"score": 9,
|
||||
"issues": [
|
||||
"Minor: skipped optional logging step"
|
||||
]
|
||||
},
|
||||
"loser": {
|
||||
"score": 6,
|
||||
"issues": [
|
||||
"Did not use the skill's formatting template",
|
||||
"Invented own approach instead of following step 3",
|
||||
"Missed the 'always validate output' instruction"
|
||||
]
|
||||
}
|
||||
},
|
||||
"improvement_suggestions": [
|
||||
{
|
||||
"priority": "high",
|
||||
"category": "instructions",
|
||||
"suggestion": "Replace 'process the document appropriately' with explicit steps: 1) Extract text, 2) Identify sections, 3) Format per template",
|
||||
"expected_impact": "Would eliminate ambiguity that caused inconsistent behavior"
|
||||
},
|
||||
{
|
||||
"priority": "high",
|
||||
"category": "tools",
|
||||
"suggestion": "Add validate_output.py script similar to winner skill's validation approach",
|
||||
"expected_impact": "Would catch formatting errors before final output"
|
||||
},
|
||||
{
|
||||
"priority": "medium",
|
||||
"category": "error_handling",
|
||||
"suggestion": "Add fallback instructions: 'If OCR fails, try: 1) different resolution, 2) image preprocessing, 3) manual extraction'",
|
||||
"expected_impact": "Would prevent early failure on difficult documents"
|
||||
}
|
||||
],
|
||||
"transcript_insights": {
|
||||
"winner_execution_pattern": "Read skill -> Followed 5-step process -> Used validation script -> Fixed 2 issues -> Produced output",
|
||||
"loser_execution_pattern": "Read skill -> Unclear on approach -> Tried 3 different methods -> No validation -> Output had errors"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Guidelines
|
||||
|
||||
- **Be specific**: Quote from skills and transcripts, don't just say "instructions were unclear"
|
||||
- **Be actionable**: Suggestions should be concrete changes, not vague advice
|
||||
- **Focus on skill improvements**: The goal is to improve the losing skill, not critique the agent
|
||||
- **Prioritize by impact**: Which changes would most likely have changed the outcome?
|
||||
- **Consider causation**: Did the skill weakness actually cause the worse output, or is it incidental?
|
||||
- **Stay objective**: Analyze what happened, don't editorialize
|
||||
- **Think about generalization**: Would this improvement help on other evals too?
|
||||
|
||||
## Categories for Suggestions
|
||||
|
||||
Use these categories to organize improvement suggestions:
|
||||
|
||||
| Category | Description |
|
||||
|----------|-------------|
|
||||
| `instructions` | Changes to the skill's prose instructions |
|
||||
| `tools` | Scripts, templates, or utilities to add/modify |
|
||||
| `examples` | Example inputs/outputs to include |
|
||||
| `error_handling` | Guidance for handling failures |
|
||||
| `structure` | Reorganization of skill content |
|
||||
| `references` | External docs or resources to add |
|
||||
|
||||
## Priority Levels
|
||||
|
||||
- **high**: Would likely change the outcome of this comparison
|
||||
- **medium**: Would improve quality but may not change win/loss
|
||||
- **low**: Nice to have, marginal improvement
|
||||
|
||||
---
|
||||
|
||||
# Analyzing Benchmark Results
|
||||
|
||||
When analyzing benchmark results, the analyzer's purpose is to **surface patterns and anomalies** across multiple runs, not suggest skill improvements.
|
||||
|
||||
## Role
|
||||
|
||||
Review all benchmark run results and generate freeform notes that help the user understand skill performance. Focus on patterns that wouldn't be visible from aggregate metrics alone.
|
||||
|
||||
## Inputs
|
||||
|
||||
You receive these parameters in your prompt:
|
||||
|
||||
- **benchmark_data_path**: Path to the in-progress benchmark.json with all run results
|
||||
- **skill_path**: Path to the skill being benchmarked
|
||||
- **output_path**: Where to save the notes (as JSON array of strings)
|
||||
|
||||
## Process
|
||||
|
||||
### Step 1: Read Benchmark Data
|
||||
|
||||
1. Read the benchmark.json containing all run results
|
||||
2. Note the configurations tested (with_skill, without_skill)
|
||||
3. Understand the run_summary aggregates already calculated
|
||||
|
||||
### Step 2: Analyze Per-Assertion Patterns
|
||||
|
||||
For each expectation across all runs:
|
||||
- Does it **always pass** in both configurations? (may not differentiate skill value)
|
||||
- Does it **always fail** in both configurations? (may be broken or beyond capability)
|
||||
- Does it **always pass with skill but fail without**? (skill clearly adds value here)
|
||||
- Does it **always fail with skill but pass without**? (skill may be hurting)
|
||||
- Is it **highly variable**? (flaky expectation or non-deterministic behavior)
|
||||
|
||||
### Step 3: Analyze Cross-Eval Patterns
|
||||
|
||||
Look for patterns across evals:
|
||||
- Are certain eval types consistently harder/easier?
|
||||
- Do some evals show high variance while others are stable?
|
||||
- Are there surprising results that contradict expectations?
|
||||
|
||||
### Step 4: Analyze Metrics Patterns
|
||||
|
||||
Look at time_seconds, tokens, tool_calls:
|
||||
- Does the skill significantly increase execution time?
|
||||
- Is there high variance in resource usage?
|
||||
- Are there outlier runs that skew the aggregates?
|
||||
|
||||
### Step 5: Generate Notes
|
||||
|
||||
Write freeform observations as a list of strings. Each note should:
|
||||
- State a specific observation
|
||||
- Be grounded in the data (not speculation)
|
||||
- Help the user understand something the aggregate metrics don't show
|
||||
|
||||
Examples:
|
||||
- "Assertion 'Output is a PDF file' passes 100% in both configurations - may not differentiate skill value"
|
||||
- "Eval 3 shows high variance (50% ± 40%) - run 2 had an unusual failure that may be flaky"
|
||||
- "Without-skill runs consistently fail on table extraction expectations (0% pass rate)"
|
||||
- "Skill adds 13s average execution time but improves pass rate by 50%"
|
||||
- "Token usage is 80% higher with skill, primarily due to script output parsing"
|
||||
- "All 3 without-skill runs for eval 1 produced empty output"
|
||||
|
||||
### Step 6: Write Notes
|
||||
|
||||
Save notes to `{output_path}` as a JSON array of strings:
|
||||
|
||||
```json
|
||||
[
|
||||
"Assertion 'Output is a PDF file' passes 100% in both configurations - may not differentiate skill value",
|
||||
"Eval 3 shows high variance (50% ± 40%) - run 2 had an unusual failure",
|
||||
"Without-skill runs consistently fail on table extraction expectations",
|
||||
"Skill adds 13s average execution time but improves pass rate by 50%"
|
||||
]
|
||||
```
|
||||
|
||||
## Guidelines
|
||||
|
||||
**DO:**
|
||||
- Report what you observe in the data
|
||||
- Be specific about which evals, expectations, or runs you're referring to
|
||||
- Note patterns that aggregate metrics would hide
|
||||
- Provide context that helps interpret the numbers
|
||||
|
||||
**DO NOT:**
|
||||
- Suggest improvements to the skill (that's for the improvement step, not benchmarking)
|
||||
- Make subjective quality judgments ("the output was good/bad")
|
||||
- Speculate about causes without evidence
|
||||
- Repeat information already in the run_summary aggregates
|
||||
202
deer-flow/skills/public/skill-creator/agents/comparator.md
Normal file
202
deer-flow/skills/public/skill-creator/agents/comparator.md
Normal file
@@ -0,0 +1,202 @@
|
||||
# Blind Comparator Agent
|
||||
|
||||
Compare two outputs WITHOUT knowing which skill produced them.
|
||||
|
||||
## Role
|
||||
|
||||
The Blind Comparator judges which output better accomplishes the eval task. You receive two outputs labeled A and B, but you do NOT know which skill produced which. This prevents bias toward a particular skill or approach.
|
||||
|
||||
Your judgment is based purely on output quality and task completion.
|
||||
|
||||
## Inputs
|
||||
|
||||
You receive these parameters in your prompt:
|
||||
|
||||
- **output_a_path**: Path to the first output file or directory
|
||||
- **output_b_path**: Path to the second output file or directory
|
||||
- **eval_prompt**: The original task/prompt that was executed
|
||||
- **expectations**: List of expectations to check (optional - may be empty)
|
||||
|
||||
## Process
|
||||
|
||||
### Step 1: Read Both Outputs
|
||||
|
||||
1. Examine output A (file or directory)
|
||||
2. Examine output B (file or directory)
|
||||
3. Note the type, structure, and content of each
|
||||
4. If outputs are directories, examine all relevant files inside
|
||||
|
||||
### Step 2: Understand the Task
|
||||
|
||||
1. Read the eval_prompt carefully
|
||||
2. Identify what the task requires:
|
||||
- What should be produced?
|
||||
- What qualities matter (accuracy, completeness, format)?
|
||||
- What would distinguish a good output from a poor one?
|
||||
|
||||
### Step 3: Generate Evaluation Rubric
|
||||
|
||||
Based on the task, generate a rubric with two dimensions:
|
||||
|
||||
**Content Rubric** (what the output contains):
|
||||
| Criterion | 1 (Poor) | 3 (Acceptable) | 5 (Excellent) |
|
||||
|-----------|----------|----------------|---------------|
|
||||
| Correctness | Major errors | Minor errors | Fully correct |
|
||||
| Completeness | Missing key elements | Mostly complete | All elements present |
|
||||
| Accuracy | Significant inaccuracies | Minor inaccuracies | Accurate throughout |
|
||||
|
||||
**Structure Rubric** (how the output is organized):
|
||||
| Criterion | 1 (Poor) | 3 (Acceptable) | 5 (Excellent) |
|
||||
|-----------|----------|----------------|---------------|
|
||||
| Organization | Disorganized | Reasonably organized | Clear, logical structure |
|
||||
| Formatting | Inconsistent/broken | Mostly consistent | Professional, polished |
|
||||
| Usability | Difficult to use | Usable with effort | Easy to use |
|
||||
|
||||
Adapt criteria to the specific task. For example:
|
||||
- PDF form → "Field alignment", "Text readability", "Data placement"
|
||||
- Document → "Section structure", "Heading hierarchy", "Paragraph flow"
|
||||
- Data output → "Schema correctness", "Data types", "Completeness"
|
||||
|
||||
### Step 4: Evaluate Each Output Against the Rubric
|
||||
|
||||
For each output (A and B):
|
||||
|
||||
1. **Score each criterion** on the rubric (1-5 scale)
|
||||
2. **Calculate dimension totals**: Content score, Structure score
|
||||
3. **Calculate overall score**: Average of dimension scores, scaled to 1-10
|
||||
|
||||
### Step 5: Check Assertions (if provided)
|
||||
|
||||
If expectations are provided:
|
||||
|
||||
1. Check each expectation against output A
|
||||
2. Check each expectation against output B
|
||||
3. Count pass rates for each output
|
||||
4. Use expectation scores as secondary evidence (not the primary decision factor)
|
||||
|
||||
### Step 6: Determine the Winner
|
||||
|
||||
Compare A and B based on (in priority order):
|
||||
|
||||
1. **Primary**: Overall rubric score (content + structure)
|
||||
2. **Secondary**: Assertion pass rates (if applicable)
|
||||
3. **Tiebreaker**: If truly equal, declare a TIE
|
||||
|
||||
Be decisive - ties should be rare. One output is usually better, even if marginally.
|
||||
|
||||
### Step 7: Write Comparison Results
|
||||
|
||||
Save results to a JSON file at the path specified (or `comparison.json` if not specified).
|
||||
|
||||
## Output Format
|
||||
|
||||
Write a JSON file with this structure:
|
||||
|
||||
```json
|
||||
{
|
||||
"winner": "A",
|
||||
"reasoning": "Output A provides a complete solution with proper formatting and all required fields. Output B is missing the date field and has formatting inconsistencies.",
|
||||
"rubric": {
|
||||
"A": {
|
||||
"content": {
|
||||
"correctness": 5,
|
||||
"completeness": 5,
|
||||
"accuracy": 4
|
||||
},
|
||||
"structure": {
|
||||
"organization": 4,
|
||||
"formatting": 5,
|
||||
"usability": 4
|
||||
},
|
||||
"content_score": 4.7,
|
||||
"structure_score": 4.3,
|
||||
"overall_score": 9.0
|
||||
},
|
||||
"B": {
|
||||
"content": {
|
||||
"correctness": 3,
|
||||
"completeness": 2,
|
||||
"accuracy": 3
|
||||
},
|
||||
"structure": {
|
||||
"organization": 3,
|
||||
"formatting": 2,
|
||||
"usability": 3
|
||||
},
|
||||
"content_score": 2.7,
|
||||
"structure_score": 2.7,
|
||||
"overall_score": 5.4
|
||||
}
|
||||
},
|
||||
"output_quality": {
|
||||
"A": {
|
||||
"score": 9,
|
||||
"strengths": ["Complete solution", "Well-formatted", "All fields present"],
|
||||
"weaknesses": ["Minor style inconsistency in header"]
|
||||
},
|
||||
"B": {
|
||||
"score": 5,
|
||||
"strengths": ["Readable output", "Correct basic structure"],
|
||||
"weaknesses": ["Missing date field", "Formatting inconsistencies", "Partial data extraction"]
|
||||
}
|
||||
},
|
||||
"expectation_results": {
|
||||
"A": {
|
||||
"passed": 4,
|
||||
"total": 5,
|
||||
"pass_rate": 0.80,
|
||||
"details": [
|
||||
{"text": "Output includes name", "passed": true},
|
||||
{"text": "Output includes date", "passed": true},
|
||||
{"text": "Format is PDF", "passed": true},
|
||||
{"text": "Contains signature", "passed": false},
|
||||
{"text": "Readable text", "passed": true}
|
||||
]
|
||||
},
|
||||
"B": {
|
||||
"passed": 3,
|
||||
"total": 5,
|
||||
"pass_rate": 0.60,
|
||||
"details": [
|
||||
{"text": "Output includes name", "passed": true},
|
||||
{"text": "Output includes date", "passed": false},
|
||||
{"text": "Format is PDF", "passed": true},
|
||||
{"text": "Contains signature", "passed": false},
|
||||
{"text": "Readable text", "passed": true}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
If no expectations were provided, omit the `expectation_results` field entirely.
|
||||
|
||||
## Field Descriptions
|
||||
|
||||
- **winner**: "A", "B", or "TIE"
|
||||
- **reasoning**: Clear explanation of why the winner was chosen (or why it's a tie)
|
||||
- **rubric**: Structured rubric evaluation for each output
|
||||
- **content**: Scores for content criteria (correctness, completeness, accuracy)
|
||||
- **structure**: Scores for structure criteria (organization, formatting, usability)
|
||||
- **content_score**: Average of content criteria (1-5)
|
||||
- **structure_score**: Average of structure criteria (1-5)
|
||||
- **overall_score**: Combined score scaled to 1-10
|
||||
- **output_quality**: Summary quality assessment
|
||||
- **score**: 1-10 rating (should match rubric overall_score)
|
||||
- **strengths**: List of positive aspects
|
||||
- **weaknesses**: List of issues or shortcomings
|
||||
- **expectation_results**: (Only if expectations provided)
|
||||
- **passed**: Number of expectations that passed
|
||||
- **total**: Total number of expectations
|
||||
- **pass_rate**: Fraction passed (0.0 to 1.0)
|
||||
- **details**: Individual expectation results
|
||||
|
||||
## Guidelines
|
||||
|
||||
- **Stay blind**: DO NOT try to infer which skill produced which output. Judge purely on output quality.
|
||||
- **Be specific**: Cite specific examples when explaining strengths and weaknesses.
|
||||
- **Be decisive**: Choose a winner unless outputs are genuinely equivalent.
|
||||
- **Output quality first**: Assertion scores are secondary to overall task completion.
|
||||
- **Be objective**: Don't favor outputs based on style preferences; focus on correctness and completeness.
|
||||
- **Explain your reasoning**: The reasoning field should make it clear why you chose the winner.
|
||||
- **Handle edge cases**: If both outputs fail, pick the one that fails less badly. If both are excellent, pick the one that's marginally better.
|
||||
223
deer-flow/skills/public/skill-creator/agents/grader.md
Normal file
223
deer-flow/skills/public/skill-creator/agents/grader.md
Normal file
@@ -0,0 +1,223 @@
|
||||
# Grader Agent
|
||||
|
||||
Evaluate expectations against an execution transcript and outputs.
|
||||
|
||||
## Role
|
||||
|
||||
The Grader reviews a transcript and output files, then determines whether each expectation passes or fails. Provide clear evidence for each judgment.
|
||||
|
||||
You have two jobs: grade the outputs, and critique the evals themselves. A passing grade on a weak assertion is worse than useless — it creates false confidence. When you notice an assertion that's trivially satisfied, or an important outcome that no assertion checks, say so.
|
||||
|
||||
## Inputs
|
||||
|
||||
You receive these parameters in your prompt:
|
||||
|
||||
- **expectations**: List of expectations to evaluate (strings)
|
||||
- **transcript_path**: Path to the execution transcript (markdown file)
|
||||
- **outputs_dir**: Directory containing output files from execution
|
||||
|
||||
## Process
|
||||
|
||||
### Step 1: Read the Transcript
|
||||
|
||||
1. Read the transcript file completely
|
||||
2. Note the eval prompt, execution steps, and final result
|
||||
3. Identify any issues or errors documented
|
||||
|
||||
### Step 2: Examine Output Files
|
||||
|
||||
1. List files in outputs_dir
|
||||
2. Read/examine each file relevant to the expectations. If outputs aren't plain text, use the inspection tools provided in your prompt — don't rely solely on what the transcript says the executor produced.
|
||||
3. Note contents, structure, and quality
|
||||
|
||||
### Step 3: Evaluate Each Assertion
|
||||
|
||||
For each expectation:
|
||||
|
||||
1. **Search for evidence** in the transcript and outputs
|
||||
2. **Determine verdict**:
|
||||
- **PASS**: Clear evidence the expectation is true AND the evidence reflects genuine task completion, not just surface-level compliance
|
||||
- **FAIL**: No evidence, or evidence contradicts the expectation, or the evidence is superficial (e.g., correct filename but empty/wrong content)
|
||||
3. **Cite the evidence**: Quote the specific text or describe what you found
|
||||
|
||||
### Step 4: Extract and Verify Claims
|
||||
|
||||
Beyond the predefined expectations, extract implicit claims from the outputs and verify them:
|
||||
|
||||
1. **Extract claims** from the transcript and outputs:
|
||||
- Factual statements ("The form has 12 fields")
|
||||
- Process claims ("Used pypdf to fill the form")
|
||||
- Quality claims ("All fields were filled correctly")
|
||||
|
||||
2. **Verify each claim**:
|
||||
- **Factual claims**: Can be checked against the outputs or external sources
|
||||
- **Process claims**: Can be verified from the transcript
|
||||
- **Quality claims**: Evaluate whether the claim is justified
|
||||
|
||||
3. **Flag unverifiable claims**: Note claims that cannot be verified with available information
|
||||
|
||||
This catches issues that predefined expectations might miss.
|
||||
|
||||
### Step 5: Read User Notes
|
||||
|
||||
If `{outputs_dir}/user_notes.md` exists:
|
||||
1. Read it and note any uncertainties or issues flagged by the executor
|
||||
2. Include relevant concerns in the grading output
|
||||
3. These may reveal problems even when expectations pass
|
||||
|
||||
### Step 6: Critique the Evals
|
||||
|
||||
After grading, consider whether the evals themselves could be improved. Only surface suggestions when there's a clear gap.
|
||||
|
||||
Good suggestions test meaningful outcomes — assertions that are hard to satisfy without actually doing the work correctly. Think about what makes an assertion *discriminating*: it passes when the skill genuinely succeeds and fails when it doesn't.
|
||||
|
||||
Suggestions worth raising:
|
||||
- An assertion that passed but would also pass for a clearly wrong output (e.g., checking filename existence but not file content)
|
||||
- An important outcome you observed — good or bad — that no assertion covers at all
|
||||
- An assertion that can't actually be verified from the available outputs
|
||||
|
||||
Keep the bar high. The goal is to flag things the eval author would say "good catch" about, not to nitpick every assertion.
|
||||
|
||||
### Step 7: Write Grading Results
|
||||
|
||||
Save results to `{outputs_dir}/../grading.json` (sibling to outputs_dir).
|
||||
|
||||
## Grading Criteria
|
||||
|
||||
**PASS when**:
|
||||
- The transcript or outputs clearly demonstrate the expectation is true
|
||||
- Specific evidence can be cited
|
||||
- The evidence reflects genuine substance, not just surface compliance (e.g., a file exists AND contains correct content, not just the right filename)
|
||||
|
||||
**FAIL when**:
|
||||
- No evidence found for the expectation
|
||||
- Evidence contradicts the expectation
|
||||
- The expectation cannot be verified from available information
|
||||
- The evidence is superficial — the assertion is technically satisfied but the underlying task outcome is wrong or incomplete
|
||||
- The output appears to meet the assertion by coincidence rather than by actually doing the work
|
||||
|
||||
**When uncertain**: The burden of proof to pass is on the expectation.
|
||||
|
||||
### Step 8: Read Executor Metrics and Timing
|
||||
|
||||
1. If `{outputs_dir}/metrics.json` exists, read it and include in grading output
|
||||
2. If `{outputs_dir}/../timing.json` exists, read it and include timing data
|
||||
|
||||
## Output Format
|
||||
|
||||
Write a JSON file with this structure:
|
||||
|
||||
```json
|
||||
{
|
||||
"expectations": [
|
||||
{
|
||||
"text": "The output includes the name 'John Smith'",
|
||||
"passed": true,
|
||||
"evidence": "Found in transcript Step 3: 'Extracted names: John Smith, Sarah Johnson'"
|
||||
},
|
||||
{
|
||||
"text": "The spreadsheet has a SUM formula in cell B10",
|
||||
"passed": false,
|
||||
"evidence": "No spreadsheet was created. The output was a text file."
|
||||
},
|
||||
{
|
||||
"text": "The assistant used the skill's OCR script",
|
||||
"passed": true,
|
||||
"evidence": "Transcript Step 2 shows: 'Tool: Bash - python ocr_script.py image.png'"
|
||||
}
|
||||
],
|
||||
"summary": {
|
||||
"passed": 2,
|
||||
"failed": 1,
|
||||
"total": 3,
|
||||
"pass_rate": 0.67
|
||||
},
|
||||
"execution_metrics": {
|
||||
"tool_calls": {
|
||||
"Read": 5,
|
||||
"Write": 2,
|
||||
"Bash": 8
|
||||
},
|
||||
"total_tool_calls": 15,
|
||||
"total_steps": 6,
|
||||
"errors_encountered": 0,
|
||||
"output_chars": 12450,
|
||||
"transcript_chars": 3200
|
||||
},
|
||||
"timing": {
|
||||
"executor_duration_seconds": 165.0,
|
||||
"grader_duration_seconds": 26.0,
|
||||
"total_duration_seconds": 191.0
|
||||
},
|
||||
"claims": [
|
||||
{
|
||||
"claim": "The form has 12 fillable fields",
|
||||
"type": "factual",
|
||||
"verified": true,
|
||||
"evidence": "Counted 12 fields in field_info.json"
|
||||
},
|
||||
{
|
||||
"claim": "All required fields were populated",
|
||||
"type": "quality",
|
||||
"verified": false,
|
||||
"evidence": "Reference section was left blank despite data being available"
|
||||
}
|
||||
],
|
||||
"user_notes_summary": {
|
||||
"uncertainties": ["Used 2023 data, may be stale"],
|
||||
"needs_review": [],
|
||||
"workarounds": ["Fell back to text overlay for non-fillable fields"]
|
||||
},
|
||||
"eval_feedback": {
|
||||
"suggestions": [
|
||||
{
|
||||
"assertion": "The output includes the name 'John Smith'",
|
||||
"reason": "A hallucinated document that mentions the name would also pass — consider checking it appears as the primary contact with matching phone and email from the input"
|
||||
},
|
||||
{
|
||||
"reason": "No assertion checks whether the extracted phone numbers match the input — I observed incorrect numbers in the output that went uncaught"
|
||||
}
|
||||
],
|
||||
"overall": "Assertions check presence but not correctness. Consider adding content verification."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Field Descriptions
|
||||
|
||||
- **expectations**: Array of graded expectations
|
||||
- **text**: The original expectation text
|
||||
- **passed**: Boolean - true if expectation passes
|
||||
- **evidence**: Specific quote or description supporting the verdict
|
||||
- **summary**: Aggregate statistics
|
||||
- **passed**: Count of passed expectations
|
||||
- **failed**: Count of failed expectations
|
||||
- **total**: Total expectations evaluated
|
||||
- **pass_rate**: Fraction passed (0.0 to 1.0)
|
||||
- **execution_metrics**: Copied from executor's metrics.json (if available)
|
||||
- **output_chars**: Total character count of output files (proxy for tokens)
|
||||
- **transcript_chars**: Character count of transcript
|
||||
- **timing**: Wall clock timing from timing.json (if available)
|
||||
- **executor_duration_seconds**: Time spent in executor subagent
|
||||
- **total_duration_seconds**: Total elapsed time for the run
|
||||
- **claims**: Extracted and verified claims from the output
|
||||
- **claim**: The statement being verified
|
||||
- **type**: "factual", "process", or "quality"
|
||||
- **verified**: Boolean - whether the claim holds
|
||||
- **evidence**: Supporting or contradicting evidence
|
||||
- **user_notes_summary**: Issues flagged by the executor
|
||||
- **uncertainties**: Things the executor wasn't sure about
|
||||
- **needs_review**: Items requiring human attention
|
||||
- **workarounds**: Places where the skill didn't work as expected
|
||||
- **eval_feedback**: Improvement suggestions for the evals (only when warranted)
|
||||
- **suggestions**: List of concrete suggestions, each with a `reason` and optionally an `assertion` it relates to
|
||||
- **overall**: Brief assessment — can be "No suggestions, evals look solid" if nothing to flag
|
||||
|
||||
## Guidelines
|
||||
|
||||
- **Be objective**: Base verdicts on evidence, not assumptions
|
||||
- **Be specific**: Quote the exact text that supports your verdict
|
||||
- **Be thorough**: Check both transcript and output files
|
||||
- **Be consistent**: Apply the same standard to each expectation
|
||||
- **Explain failures**: Make it clear why evidence was insufficient
|
||||
- **No partial credit**: Each expectation is pass or fail, not partial
|
||||
146
deer-flow/skills/public/skill-creator/assets/eval_review.html
Normal file
146
deer-flow/skills/public/skill-creator/assets/eval_review.html
Normal file
@@ -0,0 +1,146 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||||
<title>Eval Set Review - __SKILL_NAME_PLACEHOLDER__</title>
|
||||
<link rel="preconnect" href="https://fonts.googleapis.com">
|
||||
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
|
||||
<link href="https://fonts.googleapis.com/css2?family=Poppins:wght@500;600&family=Lora:wght@400;500&display=swap" rel="stylesheet">
|
||||
<style>
|
||||
* { box-sizing: border-box; margin: 0; padding: 0; }
|
||||
body { font-family: 'Lora', Georgia, serif; background: #faf9f5; padding: 2rem; color: #141413; }
|
||||
h1 { font-family: 'Poppins', sans-serif; margin-bottom: 0.5rem; font-size: 1.5rem; }
|
||||
.description { color: #b0aea5; margin-bottom: 1.5rem; font-style: italic; max-width: 900px; }
|
||||
.controls { margin-bottom: 1rem; display: flex; gap: 0.5rem; }
|
||||
.btn { font-family: 'Poppins', sans-serif; padding: 0.5rem 1rem; border: none; border-radius: 6px; cursor: pointer; font-size: 0.875rem; font-weight: 500; }
|
||||
.btn-add { background: #6a9bcc; color: white; }
|
||||
.btn-add:hover { background: #5889b8; }
|
||||
.btn-export { background: #d97757; color: white; }
|
||||
.btn-export:hover { background: #c4613f; }
|
||||
table { width: 100%; max-width: 1100px; border-collapse: collapse; background: white; border-radius: 6px; overflow: hidden; box-shadow: 0 1px 3px rgba(0,0,0,0.08); }
|
||||
th { font-family: 'Poppins', sans-serif; background: #141413; color: #faf9f5; padding: 0.75rem 1rem; text-align: left; font-size: 0.875rem; }
|
||||
td { padding: 0.75rem 1rem; border-bottom: 1px solid #e8e6dc; vertical-align: top; }
|
||||
tr:nth-child(even) td { background: #faf9f5; }
|
||||
tr:hover td { background: #f3f1ea; }
|
||||
.section-header td { background: #e8e6dc; font-family: 'Poppins', sans-serif; font-weight: 500; font-size: 0.8rem; color: #141413; text-transform: uppercase; letter-spacing: 0.05em; }
|
||||
.query-input { width: 100%; padding: 0.4rem; border: 1px solid #e8e6dc; border-radius: 4px; font-size: 0.875rem; font-family: 'Lora', Georgia, serif; resize: vertical; min-height: 60px; }
|
||||
.query-input:focus { outline: none; border-color: #d97757; box-shadow: 0 0 0 2px rgba(217,119,87,0.15); }
|
||||
.toggle { position: relative; display: inline-block; width: 44px; height: 24px; }
|
||||
.toggle input { opacity: 0; width: 0; height: 0; }
|
||||
.toggle .slider { position: absolute; inset: 0; background: #b0aea5; border-radius: 24px; cursor: pointer; transition: 0.2s; }
|
||||
.toggle .slider::before { content: ""; position: absolute; width: 18px; height: 18px; left: 3px; bottom: 3px; background: white; border-radius: 50%; transition: 0.2s; }
|
||||
.toggle input:checked + .slider { background: #d97757; }
|
||||
.toggle input:checked + .slider::before { transform: translateX(20px); }
|
||||
.btn-delete { background: #c44; color: white; padding: 0.3rem 0.6rem; border: none; border-radius: 4px; cursor: pointer; font-size: 0.75rem; font-family: 'Poppins', sans-serif; }
|
||||
.btn-delete:hover { background: #a33; }
|
||||
.summary { margin-top: 1rem; color: #b0aea5; font-size: 0.875rem; }
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<h1>Eval Set Review: <span id="skill-name">__SKILL_NAME_PLACEHOLDER__</span></h1>
|
||||
<p class="description">Current description: <span id="skill-desc">__SKILL_DESCRIPTION_PLACEHOLDER__</span></p>
|
||||
|
||||
<div class="controls">
|
||||
<button class="btn btn-add" onclick="addRow()">+ Add Query</button>
|
||||
<button class="btn btn-export" onclick="exportEvalSet()">Export Eval Set</button>
|
||||
</div>
|
||||
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th style="width:65%">Query</th>
|
||||
<th style="width:18%">Should Trigger</th>
|
||||
<th style="width:10%">Actions</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody id="eval-body"></tbody>
|
||||
</table>
|
||||
|
||||
<p class="summary" id="summary"></p>
|
||||
|
||||
<script>
|
||||
const EVAL_DATA = __EVAL_DATA_PLACEHOLDER__;
|
||||
|
||||
let evalItems = [...EVAL_DATA];
|
||||
|
||||
function render() {
|
||||
const tbody = document.getElementById('eval-body');
|
||||
tbody.innerHTML = '';
|
||||
|
||||
// Sort: should-trigger first, then should-not-trigger
|
||||
const sorted = evalItems
|
||||
.map((item, origIdx) => ({ ...item, origIdx }))
|
||||
.sort((a, b) => (b.should_trigger ? 1 : 0) - (a.should_trigger ? 1 : 0));
|
||||
|
||||
let lastGroup = null;
|
||||
sorted.forEach(item => {
|
||||
const group = item.should_trigger ? 'trigger' : 'no-trigger';
|
||||
if (group !== lastGroup) {
|
||||
const headerRow = document.createElement('tr');
|
||||
headerRow.className = 'section-header';
|
||||
headerRow.innerHTML = `<td colspan="3">${item.should_trigger ? 'Should Trigger' : 'Should NOT Trigger'}</td>`;
|
||||
tbody.appendChild(headerRow);
|
||||
lastGroup = group;
|
||||
}
|
||||
|
||||
const idx = item.origIdx;
|
||||
const tr = document.createElement('tr');
|
||||
tr.innerHTML = `
|
||||
<td><textarea class="query-input" onchange="updateQuery(${idx}, this.value)">${escapeHtml(item.query)}</textarea></td>
|
||||
<td>
|
||||
<label class="toggle">
|
||||
<input type="checkbox" ${item.should_trigger ? 'checked' : ''} onchange="updateTrigger(${idx}, this.checked)">
|
||||
<span class="slider"></span>
|
||||
</label>
|
||||
<span style="margin-left:8px;font-size:0.8rem;color:#b0aea5">${item.should_trigger ? 'Yes' : 'No'}</span>
|
||||
</td>
|
||||
<td><button class="btn-delete" onclick="deleteRow(${idx})">Delete</button></td>
|
||||
`;
|
||||
tbody.appendChild(tr);
|
||||
});
|
||||
updateSummary();
|
||||
}
|
||||
|
||||
function escapeHtml(text) {
|
||||
const div = document.createElement('div');
|
||||
div.textContent = text;
|
||||
return div.innerHTML;
|
||||
}
|
||||
|
||||
function updateQuery(idx, value) { evalItems[idx].query = value; updateSummary(); }
|
||||
function updateTrigger(idx, value) { evalItems[idx].should_trigger = value; render(); }
|
||||
function deleteRow(idx) { evalItems.splice(idx, 1); render(); }
|
||||
|
||||
function addRow() {
|
||||
evalItems.push({ query: '', should_trigger: true });
|
||||
render();
|
||||
const inputs = document.querySelectorAll('.query-input');
|
||||
inputs[inputs.length - 1].focus();
|
||||
}
|
||||
|
||||
function updateSummary() {
|
||||
const trigger = evalItems.filter(i => i.should_trigger).length;
|
||||
const noTrigger = evalItems.filter(i => !i.should_trigger).length;
|
||||
document.getElementById('summary').textContent =
|
||||
`${evalItems.length} queries total: ${trigger} should trigger, ${noTrigger} should not trigger`;
|
||||
}
|
||||
|
||||
function exportEvalSet() {
|
||||
const valid = evalItems.filter(i => i.query.trim() !== '');
|
||||
const data = valid.map(i => ({ query: i.query.trim(), should_trigger: i.should_trigger }));
|
||||
const blob = new Blob([JSON.stringify(data, null, 2)], { type: 'application/json' });
|
||||
const url = URL.createObjectURL(blob);
|
||||
const a = document.createElement('a');
|
||||
a.href = url;
|
||||
a.download = 'eval_set.json';
|
||||
document.body.appendChild(a);
|
||||
a.click();
|
||||
document.body.removeChild(a);
|
||||
URL.revokeObjectURL(url);
|
||||
}
|
||||
|
||||
render();
|
||||
</script>
|
||||
</body>
|
||||
</html>
|
||||
@@ -0,0 +1,471 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Generate and serve a review page for eval results.
|
||||
|
||||
Reads the workspace directory, discovers runs (directories with outputs/),
|
||||
embeds all output data into a self-contained HTML page, and serves it via
|
||||
a tiny HTTP server. Feedback auto-saves to feedback.json in the workspace.
|
||||
|
||||
Usage:
|
||||
python generate_review.py <workspace-path> [--port PORT] [--skill-name NAME]
|
||||
python generate_review.py <workspace-path> --previous-feedback /path/to/old/feedback.json
|
||||
|
||||
No dependencies beyond the Python stdlib are required.
|
||||
"""
|
||||
|
||||
import argparse
|
||||
import base64
|
||||
import json
|
||||
import mimetypes
|
||||
import os
|
||||
import re
|
||||
import signal
|
||||
import subprocess
|
||||
import sys
|
||||
import time
|
||||
import webbrowser
|
||||
from functools import partial
|
||||
from http.server import HTTPServer, BaseHTTPRequestHandler
|
||||
from pathlib import Path
|
||||
|
||||
# Files to exclude from output listings
|
||||
METADATA_FILES = {"transcript.md", "user_notes.md", "metrics.json"}
|
||||
|
||||
# Extensions we render as inline text
|
||||
TEXT_EXTENSIONS = {
|
||||
".txt", ".md", ".json", ".csv", ".py", ".js", ".ts", ".tsx", ".jsx",
|
||||
".yaml", ".yml", ".xml", ".html", ".css", ".sh", ".rb", ".go", ".rs",
|
||||
".java", ".c", ".cpp", ".h", ".hpp", ".sql", ".r", ".toml",
|
||||
}
|
||||
|
||||
# Extensions we render as inline images
|
||||
IMAGE_EXTENSIONS = {".png", ".jpg", ".jpeg", ".gif", ".svg", ".webp"}
|
||||
|
||||
# MIME type overrides for common types
|
||||
MIME_OVERRIDES = {
|
||||
".svg": "image/svg+xml",
|
||||
".xlsx": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
|
||||
".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
|
||||
".pptx": "application/vnd.openxmlformats-officedocument.presentationml.presentation",
|
||||
}
|
||||
|
||||
|
||||
def get_mime_type(path: Path) -> str:
|
||||
ext = path.suffix.lower()
|
||||
if ext in MIME_OVERRIDES:
|
||||
return MIME_OVERRIDES[ext]
|
||||
mime, _ = mimetypes.guess_type(str(path))
|
||||
return mime or "application/octet-stream"
|
||||
|
||||
|
||||
def find_runs(workspace: Path) -> list[dict]:
|
||||
"""Recursively find directories that contain an outputs/ subdirectory."""
|
||||
runs: list[dict] = []
|
||||
_find_runs_recursive(workspace, workspace, runs)
|
||||
runs.sort(key=lambda r: (r.get("eval_id", float("inf")), r["id"]))
|
||||
return runs
|
||||
|
||||
|
||||
def _find_runs_recursive(root: Path, current: Path, runs: list[dict]) -> None:
|
||||
if not current.is_dir():
|
||||
return
|
||||
|
||||
outputs_dir = current / "outputs"
|
||||
if outputs_dir.is_dir():
|
||||
run = build_run(root, current)
|
||||
if run:
|
||||
runs.append(run)
|
||||
return
|
||||
|
||||
skip = {"node_modules", ".git", "__pycache__", "skill", "inputs"}
|
||||
for child in sorted(current.iterdir()):
|
||||
if child.is_dir() and child.name not in skip:
|
||||
_find_runs_recursive(root, child, runs)
|
||||
|
||||
|
||||
def build_run(root: Path, run_dir: Path) -> dict | None:
|
||||
"""Build a run dict with prompt, outputs, and grading data."""
|
||||
prompt = ""
|
||||
eval_id = None
|
||||
|
||||
# Try eval_metadata.json
|
||||
for candidate in [run_dir / "eval_metadata.json", run_dir.parent / "eval_metadata.json"]:
|
||||
if candidate.exists():
|
||||
try:
|
||||
metadata = json.loads(candidate.read_text())
|
||||
prompt = metadata.get("prompt", "")
|
||||
eval_id = metadata.get("eval_id")
|
||||
except (json.JSONDecodeError, OSError):
|
||||
pass
|
||||
if prompt:
|
||||
break
|
||||
|
||||
# Fall back to transcript.md
|
||||
if not prompt:
|
||||
for candidate in [run_dir / "transcript.md", run_dir / "outputs" / "transcript.md"]:
|
||||
if candidate.exists():
|
||||
try:
|
||||
text = candidate.read_text()
|
||||
match = re.search(r"## Eval Prompt\n\n([\s\S]*?)(?=\n##|$)", text)
|
||||
if match:
|
||||
prompt = match.group(1).strip()
|
||||
except OSError:
|
||||
pass
|
||||
if prompt:
|
||||
break
|
||||
|
||||
if not prompt:
|
||||
prompt = "(No prompt found)"
|
||||
|
||||
run_id = str(run_dir.relative_to(root)).replace("/", "-").replace("\\", "-")
|
||||
|
||||
# Collect output files
|
||||
outputs_dir = run_dir / "outputs"
|
||||
output_files: list[dict] = []
|
||||
if outputs_dir.is_dir():
|
||||
for f in sorted(outputs_dir.iterdir()):
|
||||
if f.is_file() and f.name not in METADATA_FILES:
|
||||
output_files.append(embed_file(f))
|
||||
|
||||
# Load grading if present
|
||||
grading = None
|
||||
for candidate in [run_dir / "grading.json", run_dir.parent / "grading.json"]:
|
||||
if candidate.exists():
|
||||
try:
|
||||
grading = json.loads(candidate.read_text())
|
||||
except (json.JSONDecodeError, OSError):
|
||||
pass
|
||||
if grading:
|
||||
break
|
||||
|
||||
return {
|
||||
"id": run_id,
|
||||
"prompt": prompt,
|
||||
"eval_id": eval_id,
|
||||
"outputs": output_files,
|
||||
"grading": grading,
|
||||
}
|
||||
|
||||
|
||||
def embed_file(path: Path) -> dict:
|
||||
"""Read a file and return an embedded representation."""
|
||||
ext = path.suffix.lower()
|
||||
mime = get_mime_type(path)
|
||||
|
||||
if ext in TEXT_EXTENSIONS:
|
||||
try:
|
||||
content = path.read_text(errors="replace")
|
||||
except OSError:
|
||||
content = "(Error reading file)"
|
||||
return {
|
||||
"name": path.name,
|
||||
"type": "text",
|
||||
"content": content,
|
||||
}
|
||||
elif ext in IMAGE_EXTENSIONS:
|
||||
try:
|
||||
raw = path.read_bytes()
|
||||
b64 = base64.b64encode(raw).decode("ascii")
|
||||
except OSError:
|
||||
return {"name": path.name, "type": "error", "content": "(Error reading file)"}
|
||||
return {
|
||||
"name": path.name,
|
||||
"type": "image",
|
||||
"mime": mime,
|
||||
"data_uri": f"data:{mime};base64,{b64}",
|
||||
}
|
||||
elif ext == ".pdf":
|
||||
try:
|
||||
raw = path.read_bytes()
|
||||
b64 = base64.b64encode(raw).decode("ascii")
|
||||
except OSError:
|
||||
return {"name": path.name, "type": "error", "content": "(Error reading file)"}
|
||||
return {
|
||||
"name": path.name,
|
||||
"type": "pdf",
|
||||
"data_uri": f"data:{mime};base64,{b64}",
|
||||
}
|
||||
elif ext == ".xlsx":
|
||||
try:
|
||||
raw = path.read_bytes()
|
||||
b64 = base64.b64encode(raw).decode("ascii")
|
||||
except OSError:
|
||||
return {"name": path.name, "type": "error", "content": "(Error reading file)"}
|
||||
return {
|
||||
"name": path.name,
|
||||
"type": "xlsx",
|
||||
"data_b64": b64,
|
||||
}
|
||||
else:
|
||||
# Binary / unknown — base64 download link
|
||||
try:
|
||||
raw = path.read_bytes()
|
||||
b64 = base64.b64encode(raw).decode("ascii")
|
||||
except OSError:
|
||||
return {"name": path.name, "type": "error", "content": "(Error reading file)"}
|
||||
return {
|
||||
"name": path.name,
|
||||
"type": "binary",
|
||||
"mime": mime,
|
||||
"data_uri": f"data:{mime};base64,{b64}",
|
||||
}
|
||||
|
||||
|
||||
def load_previous_iteration(workspace: Path) -> dict[str, dict]:
|
||||
"""Load previous iteration's feedback and outputs.
|
||||
|
||||
Returns a map of run_id -> {"feedback": str, "outputs": list[dict]}.
|
||||
"""
|
||||
result: dict[str, dict] = {}
|
||||
|
||||
# Load feedback
|
||||
feedback_map: dict[str, str] = {}
|
||||
feedback_path = workspace / "feedback.json"
|
||||
if feedback_path.exists():
|
||||
try:
|
||||
data = json.loads(feedback_path.read_text())
|
||||
feedback_map = {
|
||||
r["run_id"]: r["feedback"]
|
||||
for r in data.get("reviews", [])
|
||||
if r.get("feedback", "").strip()
|
||||
}
|
||||
except (json.JSONDecodeError, OSError, KeyError):
|
||||
pass
|
||||
|
||||
# Load runs (to get outputs)
|
||||
prev_runs = find_runs(workspace)
|
||||
for run in prev_runs:
|
||||
result[run["id"]] = {
|
||||
"feedback": feedback_map.get(run["id"], ""),
|
||||
"outputs": run.get("outputs", []),
|
||||
}
|
||||
|
||||
# Also add feedback for run_ids that had feedback but no matching run
|
||||
for run_id, fb in feedback_map.items():
|
||||
if run_id not in result:
|
||||
result[run_id] = {"feedback": fb, "outputs": []}
|
||||
|
||||
return result
|
||||
|
||||
|
||||
def generate_html(
|
||||
runs: list[dict],
|
||||
skill_name: str,
|
||||
previous: dict[str, dict] | None = None,
|
||||
benchmark: dict | None = None,
|
||||
) -> str:
|
||||
"""Generate the complete standalone HTML page with embedded data."""
|
||||
template_path = Path(__file__).parent / "viewer.html"
|
||||
template = template_path.read_text()
|
||||
|
||||
# Build previous_feedback and previous_outputs maps for the template
|
||||
previous_feedback: dict[str, str] = {}
|
||||
previous_outputs: dict[str, list[dict]] = {}
|
||||
if previous:
|
||||
for run_id, data in previous.items():
|
||||
if data.get("feedback"):
|
||||
previous_feedback[run_id] = data["feedback"]
|
||||
if data.get("outputs"):
|
||||
previous_outputs[run_id] = data["outputs"]
|
||||
|
||||
embedded = {
|
||||
"skill_name": skill_name,
|
||||
"runs": runs,
|
||||
"previous_feedback": previous_feedback,
|
||||
"previous_outputs": previous_outputs,
|
||||
}
|
||||
if benchmark:
|
||||
embedded["benchmark"] = benchmark
|
||||
|
||||
data_json = json.dumps(embedded)
|
||||
|
||||
return template.replace("/*__EMBEDDED_DATA__*/", f"const EMBEDDED_DATA = {data_json};")
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# HTTP server (stdlib only, zero dependencies)
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
def _kill_port(port: int) -> None:
|
||||
"""Kill any process listening on the given port."""
|
||||
try:
|
||||
result = subprocess.run(
|
||||
["lsof", "-ti", f":{port}"],
|
||||
capture_output=True, text=True, timeout=5,
|
||||
)
|
||||
for pid_str in result.stdout.strip().split("\n"):
|
||||
if pid_str.strip():
|
||||
try:
|
||||
os.kill(int(pid_str.strip()), signal.SIGTERM)
|
||||
except (ProcessLookupError, ValueError):
|
||||
pass
|
||||
if result.stdout.strip():
|
||||
time.sleep(0.5)
|
||||
except subprocess.TimeoutExpired:
|
||||
pass
|
||||
except FileNotFoundError:
|
||||
print("Note: lsof not found, cannot check if port is in use", file=sys.stderr)
|
||||
|
||||
class ReviewHandler(BaseHTTPRequestHandler):
|
||||
"""Serves the review HTML and handles feedback saves.
|
||||
|
||||
Regenerates the HTML on each page load so that refreshing the browser
|
||||
picks up new eval outputs without restarting the server.
|
||||
"""
|
||||
|
||||
def __init__(
|
||||
self,
|
||||
workspace: Path,
|
||||
skill_name: str,
|
||||
feedback_path: Path,
|
||||
previous: dict[str, dict],
|
||||
benchmark_path: Path | None,
|
||||
*args,
|
||||
**kwargs,
|
||||
):
|
||||
self.workspace = workspace
|
||||
self.skill_name = skill_name
|
||||
self.feedback_path = feedback_path
|
||||
self.previous = previous
|
||||
self.benchmark_path = benchmark_path
|
||||
super().__init__(*args, **kwargs)
|
||||
|
||||
def do_GET(self) -> None:
|
||||
if self.path == "/" or self.path == "/index.html":
|
||||
# Regenerate HTML on each request (re-scans workspace for new outputs)
|
||||
runs = find_runs(self.workspace)
|
||||
benchmark = None
|
||||
if self.benchmark_path and self.benchmark_path.exists():
|
||||
try:
|
||||
benchmark = json.loads(self.benchmark_path.read_text())
|
||||
except (json.JSONDecodeError, OSError):
|
||||
pass
|
||||
html = generate_html(runs, self.skill_name, self.previous, benchmark)
|
||||
content = html.encode("utf-8")
|
||||
self.send_response(200)
|
||||
self.send_header("Content-Type", "text/html; charset=utf-8")
|
||||
self.send_header("Content-Length", str(len(content)))
|
||||
self.end_headers()
|
||||
self.wfile.write(content)
|
||||
elif self.path == "/api/feedback":
|
||||
data = b"{}"
|
||||
if self.feedback_path.exists():
|
||||
data = self.feedback_path.read_bytes()
|
||||
self.send_response(200)
|
||||
self.send_header("Content-Type", "application/json")
|
||||
self.send_header("Content-Length", str(len(data)))
|
||||
self.end_headers()
|
||||
self.wfile.write(data)
|
||||
else:
|
||||
self.send_error(404)
|
||||
|
||||
def do_POST(self) -> None:
|
||||
if self.path == "/api/feedback":
|
||||
length = int(self.headers.get("Content-Length", 0))
|
||||
body = self.rfile.read(length)
|
||||
try:
|
||||
data = json.loads(body)
|
||||
if not isinstance(data, dict) or "reviews" not in data:
|
||||
raise ValueError("Expected JSON object with 'reviews' key")
|
||||
self.feedback_path.write_text(json.dumps(data, indent=2) + "\n")
|
||||
resp = b'{"ok":true}'
|
||||
self.send_response(200)
|
||||
except (json.JSONDecodeError, OSError, ValueError) as e:
|
||||
resp = json.dumps({"error": str(e)}).encode()
|
||||
self.send_response(500)
|
||||
self.send_header("Content-Type", "application/json")
|
||||
self.send_header("Content-Length", str(len(resp)))
|
||||
self.end_headers()
|
||||
self.wfile.write(resp)
|
||||
else:
|
||||
self.send_error(404)
|
||||
|
||||
def log_message(self, format: str, *args: object) -> None:
|
||||
# Suppress request logging to keep terminal clean
|
||||
pass
|
||||
|
||||
|
||||
def main() -> None:
|
||||
parser = argparse.ArgumentParser(description="Generate and serve eval review")
|
||||
parser.add_argument("workspace", type=Path, help="Path to workspace directory")
|
||||
parser.add_argument("--port", "-p", type=int, default=3117, help="Server port (default: 3117)")
|
||||
parser.add_argument("--skill-name", "-n", type=str, default=None, help="Skill name for header")
|
||||
parser.add_argument(
|
||||
"--previous-workspace", type=Path, default=None,
|
||||
help="Path to previous iteration's workspace (shows old outputs and feedback as context)",
|
||||
)
|
||||
parser.add_argument(
|
||||
"--benchmark", type=Path, default=None,
|
||||
help="Path to benchmark.json to show in the Benchmark tab",
|
||||
)
|
||||
parser.add_argument(
|
||||
"--static", "-s", type=Path, default=None,
|
||||
help="Write standalone HTML to this path instead of starting a server",
|
||||
)
|
||||
args = parser.parse_args()
|
||||
|
||||
workspace = args.workspace.resolve()
|
||||
if not workspace.is_dir():
|
||||
print(f"Error: {workspace} is not a directory", file=sys.stderr)
|
||||
sys.exit(1)
|
||||
|
||||
runs = find_runs(workspace)
|
||||
if not runs:
|
||||
print(f"No runs found in {workspace}", file=sys.stderr)
|
||||
sys.exit(1)
|
||||
|
||||
skill_name = args.skill_name or workspace.name.replace("-workspace", "")
|
||||
feedback_path = workspace / "feedback.json"
|
||||
|
||||
previous: dict[str, dict] = {}
|
||||
if args.previous_workspace:
|
||||
previous = load_previous_iteration(args.previous_workspace.resolve())
|
||||
|
||||
benchmark_path = args.benchmark.resolve() if args.benchmark else None
|
||||
benchmark = None
|
||||
if benchmark_path and benchmark_path.exists():
|
||||
try:
|
||||
benchmark = json.loads(benchmark_path.read_text())
|
||||
except (json.JSONDecodeError, OSError):
|
||||
pass
|
||||
|
||||
if args.static:
|
||||
html = generate_html(runs, skill_name, previous, benchmark)
|
||||
args.static.parent.mkdir(parents=True, exist_ok=True)
|
||||
args.static.write_text(html)
|
||||
print(f"\n Static viewer written to: {args.static}\n")
|
||||
sys.exit(0)
|
||||
|
||||
# Kill any existing process on the target port
|
||||
port = args.port
|
||||
_kill_port(port)
|
||||
handler = partial(ReviewHandler, workspace, skill_name, feedback_path, previous, benchmark_path)
|
||||
try:
|
||||
server = HTTPServer(("127.0.0.1", port), handler)
|
||||
except OSError:
|
||||
# Port still in use after kill attempt — find a free one
|
||||
server = HTTPServer(("127.0.0.1", 0), handler)
|
||||
port = server.server_address[1]
|
||||
|
||||
url = f"http://localhost:{port}"
|
||||
print(f"\n Eval Viewer")
|
||||
print(f" ─────────────────────────────────")
|
||||
print(f" URL: {url}")
|
||||
print(f" Workspace: {workspace}")
|
||||
print(f" Feedback: {feedback_path}")
|
||||
if previous:
|
||||
print(f" Previous: {args.previous_workspace} ({len(previous)} runs)")
|
||||
if benchmark_path:
|
||||
print(f" Benchmark: {benchmark_path}")
|
||||
print(f"\n Press Ctrl+C to stop.\n")
|
||||
|
||||
webbrowser.open(url)
|
||||
|
||||
try:
|
||||
server.serve_forever()
|
||||
except KeyboardInterrupt:
|
||||
print("\nStopped.")
|
||||
server.server_close()
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
1325
deer-flow/skills/public/skill-creator/eval-viewer/viewer.html
Normal file
1325
deer-flow/skills/public/skill-creator/eval-viewer/viewer.html
Normal file
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,82 @@
|
||||
# Output Patterns
|
||||
|
||||
Use these patterns when skills need to produce consistent, high-quality output.
|
||||
|
||||
## Template Pattern
|
||||
|
||||
Provide templates for output format. Match the level of strictness to your needs.
|
||||
|
||||
**For strict requirements (like API responses or data formats):**
|
||||
|
||||
```markdown
|
||||
## Report structure
|
||||
|
||||
ALWAYS use this exact template structure:
|
||||
|
||||
# [Analysis Title]
|
||||
|
||||
## Executive summary
|
||||
[One-paragraph overview of key findings]
|
||||
|
||||
## Key findings
|
||||
- Finding 1 with supporting data
|
||||
- Finding 2 with supporting data
|
||||
- Finding 3 with supporting data
|
||||
|
||||
## Recommendations
|
||||
1. Specific actionable recommendation
|
||||
2. Specific actionable recommendation
|
||||
```
|
||||
|
||||
**For flexible guidance (when adaptation is useful):**
|
||||
|
||||
```markdown
|
||||
## Report structure
|
||||
|
||||
Here is a sensible default format, but use your best judgment:
|
||||
|
||||
# [Analysis Title]
|
||||
|
||||
## Executive summary
|
||||
[Overview]
|
||||
|
||||
## Key findings
|
||||
[Adapt sections based on what you discover]
|
||||
|
||||
## Recommendations
|
||||
[Tailor to the specific context]
|
||||
|
||||
Adjust sections as needed for the specific analysis type.
|
||||
```
|
||||
|
||||
## Examples Pattern
|
||||
|
||||
For skills where output quality depends on seeing examples, provide input/output pairs:
|
||||
|
||||
```markdown
|
||||
## Commit message format
|
||||
|
||||
Generate commit messages following these examples:
|
||||
|
||||
**Example 1:**
|
||||
Input: Added user authentication with JWT tokens
|
||||
Output:
|
||||
```
|
||||
feat(auth): implement JWT-based authentication
|
||||
|
||||
Add login endpoint and token validation middleware
|
||||
```
|
||||
|
||||
**Example 2:**
|
||||
Input: Fixed bug where dates displayed incorrectly in reports
|
||||
Output:
|
||||
```
|
||||
fix(reports): correct date formatting in timezone conversion
|
||||
|
||||
Use UTC timestamps consistently across report generation
|
||||
```
|
||||
|
||||
Follow this style: type(scope): brief description, then detailed explanation.
|
||||
```
|
||||
|
||||
Examples help Claude understand the desired style and level of detail more clearly than descriptions alone.
|
||||
430
deer-flow/skills/public/skill-creator/references/schemas.md
Normal file
430
deer-flow/skills/public/skill-creator/references/schemas.md
Normal file
@@ -0,0 +1,430 @@
|
||||
# JSON Schemas
|
||||
|
||||
This document defines the JSON schemas used by skill-creator.
|
||||
|
||||
---
|
||||
|
||||
## evals.json
|
||||
|
||||
Defines the evals for a skill. Located at `evals/evals.json` within the skill directory.
|
||||
|
||||
```json
|
||||
{
|
||||
"skill_name": "example-skill",
|
||||
"evals": [
|
||||
{
|
||||
"id": 1,
|
||||
"prompt": "User's example prompt",
|
||||
"expected_output": "Description of expected result",
|
||||
"files": ["evals/files/sample1.pdf"],
|
||||
"expectations": [
|
||||
"The output includes X",
|
||||
"The skill used script Y"
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Fields:**
|
||||
- `skill_name`: Name matching the skill's frontmatter
|
||||
- `evals[].id`: Unique integer identifier
|
||||
- `evals[].prompt`: The task to execute
|
||||
- `evals[].expected_output`: Human-readable description of success
|
||||
- `evals[].files`: Optional list of input file paths (relative to skill root)
|
||||
- `evals[].expectations`: List of verifiable statements
|
||||
|
||||
---
|
||||
|
||||
## history.json
|
||||
|
||||
Tracks version progression in Improve mode. Located at workspace root.
|
||||
|
||||
```json
|
||||
{
|
||||
"started_at": "2026-01-15T10:30:00Z",
|
||||
"skill_name": "pdf",
|
||||
"current_best": "v2",
|
||||
"iterations": [
|
||||
{
|
||||
"version": "v0",
|
||||
"parent": null,
|
||||
"expectation_pass_rate": 0.65,
|
||||
"grading_result": "baseline",
|
||||
"is_current_best": false
|
||||
},
|
||||
{
|
||||
"version": "v1",
|
||||
"parent": "v0",
|
||||
"expectation_pass_rate": 0.75,
|
||||
"grading_result": "won",
|
||||
"is_current_best": false
|
||||
},
|
||||
{
|
||||
"version": "v2",
|
||||
"parent": "v1",
|
||||
"expectation_pass_rate": 0.85,
|
||||
"grading_result": "won",
|
||||
"is_current_best": true
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Fields:**
|
||||
- `started_at`: ISO timestamp of when improvement started
|
||||
- `skill_name`: Name of the skill being improved
|
||||
- `current_best`: Version identifier of the best performer
|
||||
- `iterations[].version`: Version identifier (v0, v1, ...)
|
||||
- `iterations[].parent`: Parent version this was derived from
|
||||
- `iterations[].expectation_pass_rate`: Pass rate from grading
|
||||
- `iterations[].grading_result`: "baseline", "won", "lost", or "tie"
|
||||
- `iterations[].is_current_best`: Whether this is the current best version
|
||||
|
||||
---
|
||||
|
||||
## grading.json
|
||||
|
||||
Output from the grader agent. Located at `<run-dir>/grading.json`.
|
||||
|
||||
```json
|
||||
{
|
||||
"expectations": [
|
||||
{
|
||||
"text": "The output includes the name 'John Smith'",
|
||||
"passed": true,
|
||||
"evidence": "Found in transcript Step 3: 'Extracted names: John Smith, Sarah Johnson'"
|
||||
},
|
||||
{
|
||||
"text": "The spreadsheet has a SUM formula in cell B10",
|
||||
"passed": false,
|
||||
"evidence": "No spreadsheet was created. The output was a text file."
|
||||
}
|
||||
],
|
||||
"summary": {
|
||||
"passed": 2,
|
||||
"failed": 1,
|
||||
"total": 3,
|
||||
"pass_rate": 0.67
|
||||
},
|
||||
"execution_metrics": {
|
||||
"tool_calls": {
|
||||
"Read": 5,
|
||||
"Write": 2,
|
||||
"Bash": 8
|
||||
},
|
||||
"total_tool_calls": 15,
|
||||
"total_steps": 6,
|
||||
"errors_encountered": 0,
|
||||
"output_chars": 12450,
|
||||
"transcript_chars": 3200
|
||||
},
|
||||
"timing": {
|
||||
"executor_duration_seconds": 165.0,
|
||||
"grader_duration_seconds": 26.0,
|
||||
"total_duration_seconds": 191.0
|
||||
},
|
||||
"claims": [
|
||||
{
|
||||
"claim": "The form has 12 fillable fields",
|
||||
"type": "factual",
|
||||
"verified": true,
|
||||
"evidence": "Counted 12 fields in field_info.json"
|
||||
}
|
||||
],
|
||||
"user_notes_summary": {
|
||||
"uncertainties": ["Used 2023 data, may be stale"],
|
||||
"needs_review": [],
|
||||
"workarounds": ["Fell back to text overlay for non-fillable fields"]
|
||||
},
|
||||
"eval_feedback": {
|
||||
"suggestions": [
|
||||
{
|
||||
"assertion": "The output includes the name 'John Smith'",
|
||||
"reason": "A hallucinated document that mentions the name would also pass"
|
||||
}
|
||||
],
|
||||
"overall": "Assertions check presence but not correctness."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Fields:**
|
||||
- `expectations[]`: Graded expectations with evidence
|
||||
- `summary`: Aggregate pass/fail counts
|
||||
- `execution_metrics`: Tool usage and output size (from executor's metrics.json)
|
||||
- `timing`: Wall clock timing (from timing.json)
|
||||
- `claims`: Extracted and verified claims from the output
|
||||
- `user_notes_summary`: Issues flagged by the executor
|
||||
- `eval_feedback`: (optional) Improvement suggestions for the evals, only present when the grader identifies issues worth raising
|
||||
|
||||
---
|
||||
|
||||
## metrics.json
|
||||
|
||||
Output from the executor agent. Located at `<run-dir>/outputs/metrics.json`.
|
||||
|
||||
```json
|
||||
{
|
||||
"tool_calls": {
|
||||
"Read": 5,
|
||||
"Write": 2,
|
||||
"Bash": 8,
|
||||
"Edit": 1,
|
||||
"Glob": 2,
|
||||
"Grep": 0
|
||||
},
|
||||
"total_tool_calls": 18,
|
||||
"total_steps": 6,
|
||||
"files_created": ["filled_form.pdf", "field_values.json"],
|
||||
"errors_encountered": 0,
|
||||
"output_chars": 12450,
|
||||
"transcript_chars": 3200
|
||||
}
|
||||
```
|
||||
|
||||
**Fields:**
|
||||
- `tool_calls`: Count per tool type
|
||||
- `total_tool_calls`: Sum of all tool calls
|
||||
- `total_steps`: Number of major execution steps
|
||||
- `files_created`: List of output files created
|
||||
- `errors_encountered`: Number of errors during execution
|
||||
- `output_chars`: Total character count of output files
|
||||
- `transcript_chars`: Character count of transcript
|
||||
|
||||
---
|
||||
|
||||
## timing.json
|
||||
|
||||
Wall clock timing for a run. Located at `<run-dir>/timing.json`.
|
||||
|
||||
**How to capture:** When a subagent task completes, the task notification includes `total_tokens` and `duration_ms`. Save these immediately — they are not persisted anywhere else and cannot be recovered after the fact.
|
||||
|
||||
```json
|
||||
{
|
||||
"total_tokens": 84852,
|
||||
"duration_ms": 23332,
|
||||
"total_duration_seconds": 23.3,
|
||||
"executor_start": "2026-01-15T10:30:00Z",
|
||||
"executor_end": "2026-01-15T10:32:45Z",
|
||||
"executor_duration_seconds": 165.0,
|
||||
"grader_start": "2026-01-15T10:32:46Z",
|
||||
"grader_end": "2026-01-15T10:33:12Z",
|
||||
"grader_duration_seconds": 26.0
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## benchmark.json
|
||||
|
||||
Output from Benchmark mode. Located at `benchmarks/<timestamp>/benchmark.json`.
|
||||
|
||||
```json
|
||||
{
|
||||
"metadata": {
|
||||
"skill_name": "pdf",
|
||||
"skill_path": "/path/to/pdf",
|
||||
"executor_model": "claude-sonnet-4-20250514",
|
||||
"analyzer_model": "most-capable-model",
|
||||
"timestamp": "2026-01-15T10:30:00Z",
|
||||
"evals_run": [1, 2, 3],
|
||||
"runs_per_configuration": 3
|
||||
},
|
||||
|
||||
"runs": [
|
||||
{
|
||||
"eval_id": 1,
|
||||
"eval_name": "Ocean",
|
||||
"configuration": "with_skill",
|
||||
"run_number": 1,
|
||||
"result": {
|
||||
"pass_rate": 0.85,
|
||||
"passed": 6,
|
||||
"failed": 1,
|
||||
"total": 7,
|
||||
"time_seconds": 42.5,
|
||||
"tokens": 3800,
|
||||
"tool_calls": 18,
|
||||
"errors": 0
|
||||
},
|
||||
"expectations": [
|
||||
{"text": "...", "passed": true, "evidence": "..."}
|
||||
],
|
||||
"notes": [
|
||||
"Used 2023 data, may be stale",
|
||||
"Fell back to text overlay for non-fillable fields"
|
||||
]
|
||||
}
|
||||
],
|
||||
|
||||
"run_summary": {
|
||||
"with_skill": {
|
||||
"pass_rate": {"mean": 0.85, "stddev": 0.05, "min": 0.80, "max": 0.90},
|
||||
"time_seconds": {"mean": 45.0, "stddev": 12.0, "min": 32.0, "max": 58.0},
|
||||
"tokens": {"mean": 3800, "stddev": 400, "min": 3200, "max": 4100}
|
||||
},
|
||||
"without_skill": {
|
||||
"pass_rate": {"mean": 0.35, "stddev": 0.08, "min": 0.28, "max": 0.45},
|
||||
"time_seconds": {"mean": 32.0, "stddev": 8.0, "min": 24.0, "max": 42.0},
|
||||
"tokens": {"mean": 2100, "stddev": 300, "min": 1800, "max": 2500}
|
||||
},
|
||||
"delta": {
|
||||
"pass_rate": "+0.50",
|
||||
"time_seconds": "+13.0",
|
||||
"tokens": "+1700"
|
||||
}
|
||||
},
|
||||
|
||||
"notes": [
|
||||
"Assertion 'Output is a PDF file' passes 100% in both configurations - may not differentiate skill value",
|
||||
"Eval 3 shows high variance (50% ± 40%) - may be flaky or model-dependent",
|
||||
"Without-skill runs consistently fail on table extraction expectations",
|
||||
"Skill adds 13s average execution time but improves pass rate by 50%"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Fields:**
|
||||
- `metadata`: Information about the benchmark run
|
||||
- `skill_name`: Name of the skill
|
||||
- `timestamp`: When the benchmark was run
|
||||
- `evals_run`: List of eval names or IDs
|
||||
- `runs_per_configuration`: Number of runs per config (e.g. 3)
|
||||
- `runs[]`: Individual run results
|
||||
- `eval_id`: Numeric eval identifier
|
||||
- `eval_name`: Human-readable eval name (used as section header in the viewer)
|
||||
- `configuration`: Must be `"with_skill"` or `"without_skill"` (the viewer uses this exact string for grouping and color coding)
|
||||
- `run_number`: Integer run number (1, 2, 3...)
|
||||
- `result`: Nested object with `pass_rate`, `passed`, `total`, `time_seconds`, `tokens`, `errors`
|
||||
- `run_summary`: Statistical aggregates per configuration
|
||||
- `with_skill` / `without_skill`: Each contains `pass_rate`, `time_seconds`, `tokens` objects with `mean` and `stddev` fields
|
||||
- `delta`: Difference strings like `"+0.50"`, `"+13.0"`, `"+1700"`
|
||||
- `notes`: Freeform observations from the analyzer
|
||||
|
||||
**Important:** The viewer reads these field names exactly. Using `config` instead of `configuration`, or putting `pass_rate` at the top level of a run instead of nested under `result`, will cause the viewer to show empty/zero values. Always reference this schema when generating benchmark.json manually.
|
||||
|
||||
---
|
||||
|
||||
## comparison.json
|
||||
|
||||
Output from blind comparator. Located at `<grading-dir>/comparison-N.json`.
|
||||
|
||||
```json
|
||||
{
|
||||
"winner": "A",
|
||||
"reasoning": "Output A provides a complete solution with proper formatting and all required fields. Output B is missing the date field and has formatting inconsistencies.",
|
||||
"rubric": {
|
||||
"A": {
|
||||
"content": {
|
||||
"correctness": 5,
|
||||
"completeness": 5,
|
||||
"accuracy": 4
|
||||
},
|
||||
"structure": {
|
||||
"organization": 4,
|
||||
"formatting": 5,
|
||||
"usability": 4
|
||||
},
|
||||
"content_score": 4.7,
|
||||
"structure_score": 4.3,
|
||||
"overall_score": 9.0
|
||||
},
|
||||
"B": {
|
||||
"content": {
|
||||
"correctness": 3,
|
||||
"completeness": 2,
|
||||
"accuracy": 3
|
||||
},
|
||||
"structure": {
|
||||
"organization": 3,
|
||||
"formatting": 2,
|
||||
"usability": 3
|
||||
},
|
||||
"content_score": 2.7,
|
||||
"structure_score": 2.7,
|
||||
"overall_score": 5.4
|
||||
}
|
||||
},
|
||||
"output_quality": {
|
||||
"A": {
|
||||
"score": 9,
|
||||
"strengths": ["Complete solution", "Well-formatted", "All fields present"],
|
||||
"weaknesses": ["Minor style inconsistency in header"]
|
||||
},
|
||||
"B": {
|
||||
"score": 5,
|
||||
"strengths": ["Readable output", "Correct basic structure"],
|
||||
"weaknesses": ["Missing date field", "Formatting inconsistencies", "Partial data extraction"]
|
||||
}
|
||||
},
|
||||
"expectation_results": {
|
||||
"A": {
|
||||
"passed": 4,
|
||||
"total": 5,
|
||||
"pass_rate": 0.80,
|
||||
"details": [
|
||||
{"text": "Output includes name", "passed": true}
|
||||
]
|
||||
},
|
||||
"B": {
|
||||
"passed": 3,
|
||||
"total": 5,
|
||||
"pass_rate": 0.60,
|
||||
"details": [
|
||||
{"text": "Output includes name", "passed": true}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## analysis.json
|
||||
|
||||
Output from post-hoc analyzer. Located at `<grading-dir>/analysis.json`.
|
||||
|
||||
```json
|
||||
{
|
||||
"comparison_summary": {
|
||||
"winner": "A",
|
||||
"winner_skill": "path/to/winner/skill",
|
||||
"loser_skill": "path/to/loser/skill",
|
||||
"comparator_reasoning": "Brief summary of why comparator chose winner"
|
||||
},
|
||||
"winner_strengths": [
|
||||
"Clear step-by-step instructions for handling multi-page documents",
|
||||
"Included validation script that caught formatting errors"
|
||||
],
|
||||
"loser_weaknesses": [
|
||||
"Vague instruction 'process the document appropriately' led to inconsistent behavior",
|
||||
"No script for validation, agent had to improvise"
|
||||
],
|
||||
"instruction_following": {
|
||||
"winner": {
|
||||
"score": 9,
|
||||
"issues": ["Minor: skipped optional logging step"]
|
||||
},
|
||||
"loser": {
|
||||
"score": 6,
|
||||
"issues": [
|
||||
"Did not use the skill's formatting template",
|
||||
"Invented own approach instead of following step 3"
|
||||
]
|
||||
}
|
||||
},
|
||||
"improvement_suggestions": [
|
||||
{
|
||||
"priority": "high",
|
||||
"category": "instructions",
|
||||
"suggestion": "Replace 'process the document appropriately' with explicit steps",
|
||||
"expected_impact": "Would eliminate ambiguity that caused inconsistent behavior"
|
||||
}
|
||||
],
|
||||
"transcript_insights": {
|
||||
"winner_execution_pattern": "Read skill -> Followed 5-step process -> Used validation script",
|
||||
"loser_execution_pattern": "Read skill -> Unclear on approach -> Tried 3 different methods"
|
||||
}
|
||||
}
|
||||
```
|
||||
@@ -0,0 +1,28 @@
|
||||
# Workflow Patterns
|
||||
|
||||
## Sequential Workflows
|
||||
|
||||
For complex tasks, break operations into clear, sequential steps. It is often helpful to give Claude an overview of the process towards the beginning of SKILL.md:
|
||||
|
||||
```markdown
|
||||
Filling a PDF form involves these steps:
|
||||
|
||||
1. Analyze the form (run analyze_form.py)
|
||||
2. Create field mapping (edit fields.json)
|
||||
3. Validate mapping (run validate_fields.py)
|
||||
4. Fill the form (run fill_form.py)
|
||||
5. Verify output (run verify_output.py)
|
||||
```
|
||||
|
||||
## Conditional Workflows
|
||||
|
||||
For tasks with branching logic, guide Claude through decision points:
|
||||
|
||||
```markdown
|
||||
1. Determine the modification type:
|
||||
**Creating new content?** → Follow "Creation workflow" below
|
||||
**Editing existing content?** → Follow "Editing workflow" below
|
||||
|
||||
2. Creation workflow: [steps]
|
||||
3. Editing workflow: [steps]
|
||||
```
|
||||
401
deer-flow/skills/public/skill-creator/scripts/aggregate_benchmark.py
Executable file
401
deer-flow/skills/public/skill-creator/scripts/aggregate_benchmark.py
Executable file
@@ -0,0 +1,401 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
Aggregate individual run results into benchmark summary statistics.
|
||||
|
||||
Reads grading.json files from run directories and produces:
|
||||
- run_summary with mean, stddev, min, max for each metric
|
||||
- delta between with_skill and without_skill configurations
|
||||
|
||||
Usage:
|
||||
python aggregate_benchmark.py <benchmark_dir>
|
||||
|
||||
Example:
|
||||
python aggregate_benchmark.py benchmarks/2026-01-15T10-30-00/
|
||||
|
||||
The script supports two directory layouts:
|
||||
|
||||
Workspace layout (from skill-creator iterations):
|
||||
<benchmark_dir>/
|
||||
└── eval-N/
|
||||
├── with_skill/
|
||||
│ ├── run-1/grading.json
|
||||
│ └── run-2/grading.json
|
||||
└── without_skill/
|
||||
├── run-1/grading.json
|
||||
└── run-2/grading.json
|
||||
|
||||
Legacy layout (with runs/ subdirectory):
|
||||
<benchmark_dir>/
|
||||
└── runs/
|
||||
└── eval-N/
|
||||
├── with_skill/
|
||||
│ └── run-1/grading.json
|
||||
└── without_skill/
|
||||
└── run-1/grading.json
|
||||
"""
|
||||
|
||||
import argparse
|
||||
import json
|
||||
import math
|
||||
import sys
|
||||
from datetime import datetime, timezone
|
||||
from pathlib import Path
|
||||
|
||||
|
||||
def calculate_stats(values: list[float]) -> dict:
|
||||
"""Calculate mean, stddev, min, max for a list of values."""
|
||||
if not values:
|
||||
return {"mean": 0.0, "stddev": 0.0, "min": 0.0, "max": 0.0}
|
||||
|
||||
n = len(values)
|
||||
mean = sum(values) / n
|
||||
|
||||
if n > 1:
|
||||
variance = sum((x - mean) ** 2 for x in values) / (n - 1)
|
||||
stddev = math.sqrt(variance)
|
||||
else:
|
||||
stddev = 0.0
|
||||
|
||||
return {
|
||||
"mean": round(mean, 4),
|
||||
"stddev": round(stddev, 4),
|
||||
"min": round(min(values), 4),
|
||||
"max": round(max(values), 4)
|
||||
}
|
||||
|
||||
|
||||
def load_run_results(benchmark_dir: Path) -> dict:
|
||||
"""
|
||||
Load all run results from a benchmark directory.
|
||||
|
||||
Returns dict keyed by config name (e.g. "with_skill"/"without_skill",
|
||||
or "new_skill"/"old_skill"), each containing a list of run results.
|
||||
"""
|
||||
# Support both layouts: eval dirs directly under benchmark_dir, or under runs/
|
||||
runs_dir = benchmark_dir / "runs"
|
||||
if runs_dir.exists():
|
||||
search_dir = runs_dir
|
||||
elif list(benchmark_dir.glob("eval-*")):
|
||||
search_dir = benchmark_dir
|
||||
else:
|
||||
print(f"No eval directories found in {benchmark_dir} or {benchmark_dir / 'runs'}")
|
||||
return {}
|
||||
|
||||
results: dict[str, list] = {}
|
||||
|
||||
for eval_idx, eval_dir in enumerate(sorted(search_dir.glob("eval-*"))):
|
||||
metadata_path = eval_dir / "eval_metadata.json"
|
||||
if metadata_path.exists():
|
||||
try:
|
||||
with open(metadata_path, encoding="utf-8") as mf:
|
||||
eval_id = json.load(mf).get("eval_id", eval_idx)
|
||||
except (json.JSONDecodeError, OSError):
|
||||
eval_id = eval_idx
|
||||
else:
|
||||
try:
|
||||
eval_id = int(eval_dir.name.split("-")[1])
|
||||
except ValueError:
|
||||
eval_id = eval_idx
|
||||
|
||||
# Discover config directories dynamically rather than hardcoding names
|
||||
for config_dir in sorted(eval_dir.iterdir()):
|
||||
if not config_dir.is_dir():
|
||||
continue
|
||||
# Skip non-config directories (inputs, outputs, etc.)
|
||||
if not list(config_dir.glob("run-*")):
|
||||
continue
|
||||
config = config_dir.name
|
||||
if config not in results:
|
||||
results[config] = []
|
||||
|
||||
for run_dir in sorted(config_dir.glob("run-*")):
|
||||
run_number = int(run_dir.name.split("-")[1])
|
||||
grading_file = run_dir / "grading.json"
|
||||
|
||||
if not grading_file.exists():
|
||||
print(f"Warning: grading.json not found in {run_dir}")
|
||||
continue
|
||||
|
||||
try:
|
||||
with open(grading_file, encoding="utf-8") as f:
|
||||
grading = json.load(f)
|
||||
except json.JSONDecodeError as e:
|
||||
print(f"Warning: Invalid JSON in {grading_file}: {e}")
|
||||
continue
|
||||
|
||||
# Extract metrics
|
||||
result = {
|
||||
"eval_id": eval_id,
|
||||
"run_number": run_number,
|
||||
"pass_rate": grading.get("summary", {}).get("pass_rate", 0.0),
|
||||
"passed": grading.get("summary", {}).get("passed", 0),
|
||||
"failed": grading.get("summary", {}).get("failed", 0),
|
||||
"total": grading.get("summary", {}).get("total", 0),
|
||||
}
|
||||
|
||||
# Extract timing — check grading.json first, then sibling timing.json
|
||||
timing = grading.get("timing", {})
|
||||
result["time_seconds"] = timing.get("total_duration_seconds", 0.0)
|
||||
timing_file = run_dir / "timing.json"
|
||||
if result["time_seconds"] == 0.0 and timing_file.exists():
|
||||
try:
|
||||
with open(timing_file, encoding="utf-8") as tf:
|
||||
timing_data = json.load(tf)
|
||||
result["time_seconds"] = timing_data.get("total_duration_seconds", 0.0)
|
||||
result["tokens"] = timing_data.get("total_tokens", 0)
|
||||
except json.JSONDecodeError:
|
||||
pass
|
||||
|
||||
# Extract metrics if available
|
||||
metrics = grading.get("execution_metrics", {})
|
||||
result["tool_calls"] = metrics.get("total_tool_calls", 0)
|
||||
if not result.get("tokens"):
|
||||
result["tokens"] = metrics.get("output_chars", 0)
|
||||
result["errors"] = metrics.get("errors_encountered", 0)
|
||||
|
||||
# Extract expectations — viewer requires fields: text, passed, evidence
|
||||
raw_expectations = grading.get("expectations", [])
|
||||
for exp in raw_expectations:
|
||||
if "text" not in exp or "passed" not in exp:
|
||||
print(f"Warning: expectation in {grading_file} missing required fields (text, passed, evidence): {exp}")
|
||||
result["expectations"] = raw_expectations
|
||||
|
||||
# Extract notes from user_notes_summary
|
||||
notes_summary = grading.get("user_notes_summary", {})
|
||||
notes = []
|
||||
notes.extend(notes_summary.get("uncertainties", []))
|
||||
notes.extend(notes_summary.get("needs_review", []))
|
||||
notes.extend(notes_summary.get("workarounds", []))
|
||||
result["notes"] = notes
|
||||
|
||||
results[config].append(result)
|
||||
|
||||
return results
|
||||
|
||||
|
||||
def aggregate_results(results: dict) -> dict:
|
||||
"""
|
||||
Aggregate run results into summary statistics.
|
||||
|
||||
Returns run_summary with stats for each configuration and delta.
|
||||
"""
|
||||
run_summary = {}
|
||||
configs = list(results.keys())
|
||||
|
||||
for config in configs:
|
||||
runs = results.get(config, [])
|
||||
|
||||
if not runs:
|
||||
run_summary[config] = {
|
||||
"pass_rate": {"mean": 0.0, "stddev": 0.0, "min": 0.0, "max": 0.0},
|
||||
"time_seconds": {"mean": 0.0, "stddev": 0.0, "min": 0.0, "max": 0.0},
|
||||
"tokens": {"mean": 0, "stddev": 0, "min": 0, "max": 0}
|
||||
}
|
||||
continue
|
||||
|
||||
pass_rates = [r["pass_rate"] for r in runs]
|
||||
times = [r["time_seconds"] for r in runs]
|
||||
tokens = [r.get("tokens", 0) for r in runs]
|
||||
|
||||
run_summary[config] = {
|
||||
"pass_rate": calculate_stats(pass_rates),
|
||||
"time_seconds": calculate_stats(times),
|
||||
"tokens": calculate_stats(tokens)
|
||||
}
|
||||
|
||||
# Calculate delta between the first two configs (if two exist)
|
||||
if len(configs) >= 2:
|
||||
primary = run_summary.get(configs[0], {})
|
||||
baseline = run_summary.get(configs[1], {})
|
||||
else:
|
||||
primary = run_summary.get(configs[0], {}) if configs else {}
|
||||
baseline = {}
|
||||
|
||||
delta_pass_rate = primary.get("pass_rate", {}).get("mean", 0) - baseline.get("pass_rate", {}).get("mean", 0)
|
||||
delta_time = primary.get("time_seconds", {}).get("mean", 0) - baseline.get("time_seconds", {}).get("mean", 0)
|
||||
delta_tokens = primary.get("tokens", {}).get("mean", 0) - baseline.get("tokens", {}).get("mean", 0)
|
||||
|
||||
run_summary["delta"] = {
|
||||
"pass_rate": f"{delta_pass_rate:+.2f}",
|
||||
"time_seconds": f"{delta_time:+.1f}",
|
||||
"tokens": f"{delta_tokens:+.0f}"
|
||||
}
|
||||
|
||||
return run_summary
|
||||
|
||||
|
||||
def generate_benchmark(benchmark_dir: Path, skill_name: str = "", skill_path: str = "") -> dict:
|
||||
"""
|
||||
Generate complete benchmark.json from run results.
|
||||
"""
|
||||
results = load_run_results(benchmark_dir)
|
||||
run_summary = aggregate_results(results)
|
||||
|
||||
# Build runs array for benchmark.json
|
||||
runs = []
|
||||
for config in results:
|
||||
for result in results[config]:
|
||||
runs.append({
|
||||
"eval_id": result["eval_id"],
|
||||
"configuration": config,
|
||||
"run_number": result["run_number"],
|
||||
"result": {
|
||||
"pass_rate": result["pass_rate"],
|
||||
"passed": result["passed"],
|
||||
"failed": result["failed"],
|
||||
"total": result["total"],
|
||||
"time_seconds": result["time_seconds"],
|
||||
"tokens": result.get("tokens", 0),
|
||||
"tool_calls": result.get("tool_calls", 0),
|
||||
"errors": result.get("errors", 0)
|
||||
},
|
||||
"expectations": result["expectations"],
|
||||
"notes": result["notes"]
|
||||
})
|
||||
|
||||
# Determine eval IDs from results
|
||||
eval_ids = sorted(set(
|
||||
r["eval_id"]
|
||||
for config in results.values()
|
||||
for r in config
|
||||
))
|
||||
|
||||
benchmark = {
|
||||
"metadata": {
|
||||
"skill_name": skill_name or "<skill-name>",
|
||||
"skill_path": skill_path or "<path/to/skill>",
|
||||
"executor_model": "<model-name>",
|
||||
"analyzer_model": "<model-name>",
|
||||
"timestamp": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
|
||||
"evals_run": eval_ids,
|
||||
"runs_per_configuration": 3
|
||||
},
|
||||
"runs": runs,
|
||||
"run_summary": run_summary,
|
||||
"notes": [] # To be filled by analyzer
|
||||
}
|
||||
|
||||
return benchmark
|
||||
|
||||
|
||||
def generate_markdown(benchmark: dict) -> str:
|
||||
"""Generate human-readable benchmark.md from benchmark data."""
|
||||
metadata = benchmark["metadata"]
|
||||
run_summary = benchmark["run_summary"]
|
||||
|
||||
# Determine config names (excluding "delta")
|
||||
configs = [k for k in run_summary if k != "delta"]
|
||||
config_a = configs[0] if len(configs) >= 1 else "config_a"
|
||||
config_b = configs[1] if len(configs) >= 2 else "config_b"
|
||||
label_a = config_a.replace("_", " ").title()
|
||||
label_b = config_b.replace("_", " ").title()
|
||||
|
||||
lines = [
|
||||
f"# Skill Benchmark: {metadata['skill_name']}",
|
||||
"",
|
||||
f"**Model**: {metadata['executor_model']}",
|
||||
f"**Date**: {metadata['timestamp']}",
|
||||
f"**Evals**: {', '.join(map(str, metadata['evals_run']))} ({metadata['runs_per_configuration']} runs each per configuration)",
|
||||
"",
|
||||
"## Summary",
|
||||
"",
|
||||
f"| Metric | {label_a} | {label_b} | Delta |",
|
||||
"|--------|------------|---------------|-------|",
|
||||
]
|
||||
|
||||
a_summary = run_summary.get(config_a, {})
|
||||
b_summary = run_summary.get(config_b, {})
|
||||
delta = run_summary.get("delta", {})
|
||||
|
||||
# Format pass rate
|
||||
a_pr = a_summary.get("pass_rate", {})
|
||||
b_pr = b_summary.get("pass_rate", {})
|
||||
lines.append(f"| Pass Rate | {a_pr.get('mean', 0)*100:.0f}% ± {a_pr.get('stddev', 0)*100:.0f}% | {b_pr.get('mean', 0)*100:.0f}% ± {b_pr.get('stddev', 0)*100:.0f}% | {delta.get('pass_rate', '—')} |")
|
||||
|
||||
# Format time
|
||||
a_time = a_summary.get("time_seconds", {})
|
||||
b_time = b_summary.get("time_seconds", {})
|
||||
lines.append(f"| Time | {a_time.get('mean', 0):.1f}s ± {a_time.get('stddev', 0):.1f}s | {b_time.get('mean', 0):.1f}s ± {b_time.get('stddev', 0):.1f}s | {delta.get('time_seconds', '—')}s |")
|
||||
|
||||
# Format tokens
|
||||
a_tokens = a_summary.get("tokens", {})
|
||||
b_tokens = b_summary.get("tokens", {})
|
||||
lines.append(f"| Tokens | {a_tokens.get('mean', 0):.0f} ± {a_tokens.get('stddev', 0):.0f} | {b_tokens.get('mean', 0):.0f} ± {b_tokens.get('stddev', 0):.0f} | {delta.get('tokens', '—')} |")
|
||||
|
||||
# Notes section
|
||||
if benchmark.get("notes"):
|
||||
lines.extend([
|
||||
"",
|
||||
"## Notes",
|
||||
""
|
||||
])
|
||||
for note in benchmark["notes"]:
|
||||
lines.append(f"- {note}")
|
||||
|
||||
return "\n".join(lines)
|
||||
|
||||
|
||||
def main():
|
||||
parser = argparse.ArgumentParser(
|
||||
description="Aggregate benchmark run results into summary statistics"
|
||||
)
|
||||
parser.add_argument(
|
||||
"benchmark_dir",
|
||||
type=Path,
|
||||
help="Path to the benchmark directory"
|
||||
)
|
||||
parser.add_argument(
|
||||
"--skill-name",
|
||||
default="",
|
||||
help="Name of the skill being benchmarked"
|
||||
)
|
||||
parser.add_argument(
|
||||
"--skill-path",
|
||||
default="",
|
||||
help="Path to the skill being benchmarked"
|
||||
)
|
||||
parser.add_argument(
|
||||
"--output", "-o",
|
||||
type=Path,
|
||||
help="Output path for benchmark.json (default: <benchmark_dir>/benchmark.json)"
|
||||
)
|
||||
|
||||
args = parser.parse_args()
|
||||
|
||||
if not args.benchmark_dir.exists():
|
||||
print(f"Directory not found: {args.benchmark_dir}")
|
||||
sys.exit(1)
|
||||
|
||||
# Generate benchmark
|
||||
benchmark = generate_benchmark(args.benchmark_dir, args.skill_name, args.skill_path)
|
||||
|
||||
# Determine output paths
|
||||
output_json = args.output or (args.benchmark_dir / "benchmark.json")
|
||||
output_md = output_json.with_suffix(".md")
|
||||
|
||||
# Write benchmark.json
|
||||
with open(output_json, "w", encoding="utf-8") as f:
|
||||
json.dump(benchmark, f, indent=2)
|
||||
print(f"Generated: {output_json}")
|
||||
|
||||
# Write benchmark.md
|
||||
markdown = generate_markdown(benchmark)
|
||||
with open(output_md, "w", encoding="utf-8") as f:
|
||||
f.write(markdown)
|
||||
print(f"Generated: {output_md}")
|
||||
|
||||
# Print summary
|
||||
run_summary = benchmark["run_summary"]
|
||||
configs = [k for k in run_summary if k != "delta"]
|
||||
delta = run_summary.get("delta", {})
|
||||
|
||||
print(f"\nSummary:")
|
||||
for config in configs:
|
||||
pr = run_summary[config]["pass_rate"]["mean"]
|
||||
label = config.replace("_", " ").title()
|
||||
print(f" {label}: {pr*100:.1f}% pass rate")
|
||||
print(f" Delta: {delta.get('pass_rate', '—')}")
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
326
deer-flow/skills/public/skill-creator/scripts/generate_report.py
Executable file
326
deer-flow/skills/public/skill-creator/scripts/generate_report.py
Executable file
@@ -0,0 +1,326 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Generate an HTML report from run_loop.py output.
|
||||
|
||||
Takes the JSON output from run_loop.py and generates a visual HTML report
|
||||
showing each description attempt with check/x for each test case.
|
||||
Distinguishes between train and test queries.
|
||||
"""
|
||||
|
||||
import argparse
|
||||
import html
|
||||
import json
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
|
||||
def generate_html(data: dict, auto_refresh: bool = False, skill_name: str = "") -> str:
|
||||
"""Generate HTML report from loop output data. If auto_refresh is True, adds a meta refresh tag."""
|
||||
history = data.get("history", [])
|
||||
holdout = data.get("holdout", 0)
|
||||
title_prefix = html.escape(skill_name + " \u2014 ") if skill_name else ""
|
||||
|
||||
# Get all unique queries from train and test sets, with should_trigger info
|
||||
train_queries: list[dict] = []
|
||||
test_queries: list[dict] = []
|
||||
if history:
|
||||
for r in history[0].get("train_results", history[0].get("results", [])):
|
||||
train_queries.append({"query": r["query"], "should_trigger": r.get("should_trigger", True)})
|
||||
if history[0].get("test_results"):
|
||||
for r in history[0].get("test_results", []):
|
||||
test_queries.append({"query": r["query"], "should_trigger": r.get("should_trigger", True)})
|
||||
|
||||
refresh_tag = ' <meta http-equiv="refresh" content="5">\n' if auto_refresh else ""
|
||||
|
||||
html_parts = ["""<!DOCTYPE html>
|
||||
<html>
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
""" + refresh_tag + """ <title>""" + title_prefix + """Skill Description Optimization</title>
|
||||
<link rel="preconnect" href="https://fonts.googleapis.com">
|
||||
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
|
||||
<link href="https://fonts.googleapis.com/css2?family=Poppins:wght@500;600&family=Lora:wght@400;500&display=swap" rel="stylesheet">
|
||||
<style>
|
||||
body {
|
||||
font-family: 'Lora', Georgia, serif;
|
||||
max-width: 100%;
|
||||
margin: 0 auto;
|
||||
padding: 20px;
|
||||
background: #faf9f5;
|
||||
color: #141413;
|
||||
}
|
||||
h1 { font-family: 'Poppins', sans-serif; color: #141413; }
|
||||
.explainer {
|
||||
background: white;
|
||||
padding: 15px;
|
||||
border-radius: 6px;
|
||||
margin-bottom: 20px;
|
||||
border: 1px solid #e8e6dc;
|
||||
color: #b0aea5;
|
||||
font-size: 0.875rem;
|
||||
line-height: 1.6;
|
||||
}
|
||||
.summary {
|
||||
background: white;
|
||||
padding: 15px;
|
||||
border-radius: 6px;
|
||||
margin-bottom: 20px;
|
||||
border: 1px solid #e8e6dc;
|
||||
}
|
||||
.summary p { margin: 5px 0; }
|
||||
.best { color: #788c5d; font-weight: bold; }
|
||||
.table-container {
|
||||
overflow-x: auto;
|
||||
width: 100%;
|
||||
}
|
||||
table {
|
||||
border-collapse: collapse;
|
||||
background: white;
|
||||
border: 1px solid #e8e6dc;
|
||||
border-radius: 6px;
|
||||
font-size: 12px;
|
||||
min-width: 100%;
|
||||
}
|
||||
th, td {
|
||||
padding: 8px;
|
||||
text-align: left;
|
||||
border: 1px solid #e8e6dc;
|
||||
white-space: normal;
|
||||
word-wrap: break-word;
|
||||
}
|
||||
th {
|
||||
font-family: 'Poppins', sans-serif;
|
||||
background: #141413;
|
||||
color: #faf9f5;
|
||||
font-weight: 500;
|
||||
}
|
||||
th.test-col {
|
||||
background: #6a9bcc;
|
||||
}
|
||||
th.query-col { min-width: 200px; }
|
||||
td.description {
|
||||
font-family: monospace;
|
||||
font-size: 11px;
|
||||
word-wrap: break-word;
|
||||
max-width: 400px;
|
||||
}
|
||||
td.result {
|
||||
text-align: center;
|
||||
font-size: 16px;
|
||||
min-width: 40px;
|
||||
}
|
||||
td.test-result {
|
||||
background: #f0f6fc;
|
||||
}
|
||||
.pass { color: #788c5d; }
|
||||
.fail { color: #c44; }
|
||||
.rate {
|
||||
font-size: 9px;
|
||||
color: #b0aea5;
|
||||
display: block;
|
||||
}
|
||||
tr:hover { background: #faf9f5; }
|
||||
.score {
|
||||
display: inline-block;
|
||||
padding: 2px 6px;
|
||||
border-radius: 4px;
|
||||
font-weight: bold;
|
||||
font-size: 11px;
|
||||
}
|
||||
.score-good { background: #eef2e8; color: #788c5d; }
|
||||
.score-ok { background: #fef3c7; color: #d97706; }
|
||||
.score-bad { background: #fceaea; color: #c44; }
|
||||
.train-label { color: #b0aea5; font-size: 10px; }
|
||||
.test-label { color: #6a9bcc; font-size: 10px; font-weight: bold; }
|
||||
.best-row { background: #f5f8f2; }
|
||||
th.positive-col { border-bottom: 3px solid #788c5d; }
|
||||
th.negative-col { border-bottom: 3px solid #c44; }
|
||||
th.test-col.positive-col { border-bottom: 3px solid #788c5d; }
|
||||
th.test-col.negative-col { border-bottom: 3px solid #c44; }
|
||||
.legend { font-family: 'Poppins', sans-serif; display: flex; gap: 20px; margin-bottom: 10px; font-size: 13px; align-items: center; }
|
||||
.legend-item { display: flex; align-items: center; gap: 6px; }
|
||||
.legend-swatch { width: 16px; height: 16px; border-radius: 3px; display: inline-block; }
|
||||
.swatch-positive { background: #141413; border-bottom: 3px solid #788c5d; }
|
||||
.swatch-negative { background: #141413; border-bottom: 3px solid #c44; }
|
||||
.swatch-test { background: #6a9bcc; }
|
||||
.swatch-train { background: #141413; }
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<h1>""" + title_prefix + """Skill Description Optimization</h1>
|
||||
<div class="explainer">
|
||||
<strong>Optimizing your skill's description.</strong> This page updates automatically as Claude tests different versions of your skill's description. Each row is an iteration — a new description attempt. The columns show test queries: green checkmarks mean the skill triggered correctly (or correctly didn't trigger), red crosses mean it got it wrong. The "Train" score shows performance on queries used to improve the description; the "Test" score shows performance on held-out queries the optimizer hasn't seen. When it's done, Claude will apply the best-performing description to your skill.
|
||||
</div>
|
||||
"""]
|
||||
|
||||
# Summary section
|
||||
best_test_score = data.get('best_test_score')
|
||||
best_train_score = data.get('best_train_score')
|
||||
html_parts.append(f"""
|
||||
<div class="summary">
|
||||
<p><strong>Original:</strong> {html.escape(data.get('original_description', 'N/A'))}</p>
|
||||
<p class="best"><strong>Best:</strong> {html.escape(data.get('best_description', 'N/A'))}</p>
|
||||
<p><strong>Best Score:</strong> {data.get('best_score', 'N/A')} {'(test)' if best_test_score else '(train)'}</p>
|
||||
<p><strong>Iterations:</strong> {data.get('iterations_run', 0)} | <strong>Train:</strong> {data.get('train_size', '?')} | <strong>Test:</strong> {data.get('test_size', '?')}</p>
|
||||
</div>
|
||||
""")
|
||||
|
||||
# Legend
|
||||
html_parts.append("""
|
||||
<div class="legend">
|
||||
<span style="font-weight:600">Query columns:</span>
|
||||
<span class="legend-item"><span class="legend-swatch swatch-positive"></span> Should trigger</span>
|
||||
<span class="legend-item"><span class="legend-swatch swatch-negative"></span> Should NOT trigger</span>
|
||||
<span class="legend-item"><span class="legend-swatch swatch-train"></span> Train</span>
|
||||
<span class="legend-item"><span class="legend-swatch swatch-test"></span> Test</span>
|
||||
</div>
|
||||
""")
|
||||
|
||||
# Table header
|
||||
html_parts.append("""
|
||||
<div class="table-container">
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Iter</th>
|
||||
<th>Train</th>
|
||||
<th>Test</th>
|
||||
<th class="query-col">Description</th>
|
||||
""")
|
||||
|
||||
# Add column headers for train queries
|
||||
for qinfo in train_queries:
|
||||
polarity = "positive-col" if qinfo["should_trigger"] else "negative-col"
|
||||
html_parts.append(f' <th class="{polarity}">{html.escape(qinfo["query"])}</th>\n')
|
||||
|
||||
# Add column headers for test queries (different color)
|
||||
for qinfo in test_queries:
|
||||
polarity = "positive-col" if qinfo["should_trigger"] else "negative-col"
|
||||
html_parts.append(f' <th class="test-col {polarity}">{html.escape(qinfo["query"])}</th>\n')
|
||||
|
||||
html_parts.append(""" </tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
""")
|
||||
|
||||
# Find best iteration for highlighting
|
||||
if test_queries:
|
||||
best_iter = max(history, key=lambda h: h.get("test_passed") or 0).get("iteration")
|
||||
else:
|
||||
best_iter = max(history, key=lambda h: h.get("train_passed", h.get("passed", 0))).get("iteration")
|
||||
|
||||
# Add rows for each iteration
|
||||
for h in history:
|
||||
iteration = h.get("iteration", "?")
|
||||
train_passed = h.get("train_passed", h.get("passed", 0))
|
||||
train_total = h.get("train_total", h.get("total", 0))
|
||||
test_passed = h.get("test_passed")
|
||||
test_total = h.get("test_total")
|
||||
description = h.get("description", "")
|
||||
train_results = h.get("train_results", h.get("results", []))
|
||||
test_results = h.get("test_results", [])
|
||||
|
||||
# Create lookups for results by query
|
||||
train_by_query = {r["query"]: r for r in train_results}
|
||||
test_by_query = {r["query"]: r for r in test_results} if test_results else {}
|
||||
|
||||
# Compute aggregate correct/total runs across all retries
|
||||
def aggregate_runs(results: list[dict]) -> tuple[int, int]:
|
||||
correct = 0
|
||||
total = 0
|
||||
for r in results:
|
||||
runs = r.get("runs", 0)
|
||||
triggers = r.get("triggers", 0)
|
||||
total += runs
|
||||
if r.get("should_trigger", True):
|
||||
correct += triggers
|
||||
else:
|
||||
correct += runs - triggers
|
||||
return correct, total
|
||||
|
||||
train_correct, train_runs = aggregate_runs(train_results)
|
||||
test_correct, test_runs = aggregate_runs(test_results)
|
||||
|
||||
# Determine score classes
|
||||
def score_class(correct: int, total: int) -> str:
|
||||
if total > 0:
|
||||
ratio = correct / total
|
||||
if ratio >= 0.8:
|
||||
return "score-good"
|
||||
elif ratio >= 0.5:
|
||||
return "score-ok"
|
||||
return "score-bad"
|
||||
|
||||
train_class = score_class(train_correct, train_runs)
|
||||
test_class = score_class(test_correct, test_runs)
|
||||
|
||||
row_class = "best-row" if iteration == best_iter else ""
|
||||
|
||||
html_parts.append(f""" <tr class="{row_class}">
|
||||
<td>{iteration}</td>
|
||||
<td><span class="score {train_class}">{train_correct}/{train_runs}</span></td>
|
||||
<td><span class="score {test_class}">{test_correct}/{test_runs}</span></td>
|
||||
<td class="description">{html.escape(description)}</td>
|
||||
""")
|
||||
|
||||
# Add result for each train query
|
||||
for qinfo in train_queries:
|
||||
r = train_by_query.get(qinfo["query"], {})
|
||||
did_pass = r.get("pass", False)
|
||||
triggers = r.get("triggers", 0)
|
||||
runs = r.get("runs", 0)
|
||||
|
||||
icon = "✓" if did_pass else "✗"
|
||||
css_class = "pass" if did_pass else "fail"
|
||||
|
||||
html_parts.append(f' <td class="result {css_class}">{icon}<span class="rate">{triggers}/{runs}</span></td>\n')
|
||||
|
||||
# Add result for each test query (with different background)
|
||||
for qinfo in test_queries:
|
||||
r = test_by_query.get(qinfo["query"], {})
|
||||
did_pass = r.get("pass", False)
|
||||
triggers = r.get("triggers", 0)
|
||||
runs = r.get("runs", 0)
|
||||
|
||||
icon = "✓" if did_pass else "✗"
|
||||
css_class = "pass" if did_pass else "fail"
|
||||
|
||||
html_parts.append(f' <td class="result test-result {css_class}">{icon}<span class="rate">{triggers}/{runs}</span></td>\n')
|
||||
|
||||
html_parts.append(" </tr>\n")
|
||||
|
||||
html_parts.append(""" </tbody>
|
||||
</table>
|
||||
</div>
|
||||
""")
|
||||
|
||||
html_parts.append("""
|
||||
</body>
|
||||
</html>
|
||||
""")
|
||||
|
||||
return "".join(html_parts)
|
||||
|
||||
|
||||
def main():
|
||||
parser = argparse.ArgumentParser(description="Generate HTML report from run_loop output")
|
||||
parser.add_argument("input", help="Path to JSON output from run_loop.py (or - for stdin)")
|
||||
parser.add_argument("-o", "--output", default=None, help="Output HTML file (default: stdout)")
|
||||
parser.add_argument("--skill-name", default="", help="Skill name to include in the report title")
|
||||
args = parser.parse_args()
|
||||
|
||||
if args.input == "-":
|
||||
data = json.load(sys.stdin)
|
||||
else:
|
||||
data = json.loads(Path(args.input).read_text())
|
||||
|
||||
html_output = generate_html(data, skill_name=args.skill_name)
|
||||
|
||||
if args.output:
|
||||
Path(args.output).write_text(html_output)
|
||||
print(f"Report written to {args.output}", file=sys.stderr)
|
||||
else:
|
||||
print(html_output)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
247
deer-flow/skills/public/skill-creator/scripts/improve_description.py
Executable file
247
deer-flow/skills/public/skill-creator/scripts/improve_description.py
Executable file
@@ -0,0 +1,247 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Improve a skill description based on eval results.
|
||||
|
||||
Takes eval results (from run_eval.py) and generates an improved description
|
||||
by calling `claude -p` as a subprocess (same auth pattern as run_eval.py —
|
||||
uses the session's Claude Code auth, no separate ANTHROPIC_API_KEY needed).
|
||||
"""
|
||||
|
||||
import argparse
|
||||
import json
|
||||
import os
|
||||
import re
|
||||
import subprocess
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
from scripts.utils import parse_skill_md
|
||||
|
||||
|
||||
def _call_claude(prompt: str, model: str | None, timeout: int = 300) -> str:
|
||||
"""Run `claude -p` with the prompt on stdin and return the text response.
|
||||
|
||||
Prompt goes over stdin (not argv) because it embeds the full SKILL.md
|
||||
body and can easily exceed comfortable argv length.
|
||||
"""
|
||||
cmd = ["claude", "-p", "--output-format", "text"]
|
||||
if model:
|
||||
cmd.extend(["--model", model])
|
||||
|
||||
# Remove CLAUDECODE env var to allow nesting claude -p inside a
|
||||
# Claude Code session. The guard is for interactive terminal conflicts;
|
||||
# programmatic subprocess usage is safe. Same pattern as run_eval.py.
|
||||
env = {k: v for k, v in os.environ.items() if k != "CLAUDECODE"}
|
||||
|
||||
result = subprocess.run(
|
||||
cmd,
|
||||
input=prompt,
|
||||
capture_output=True,
|
||||
text=True,
|
||||
env=env,
|
||||
timeout=timeout,
|
||||
)
|
||||
if result.returncode != 0:
|
||||
raise RuntimeError(
|
||||
f"claude -p exited {result.returncode}\nstderr: {result.stderr}"
|
||||
)
|
||||
return result.stdout
|
||||
|
||||
|
||||
def improve_description(
|
||||
skill_name: str,
|
||||
skill_content: str,
|
||||
current_description: str,
|
||||
eval_results: dict,
|
||||
history: list[dict],
|
||||
model: str,
|
||||
test_results: dict | None = None,
|
||||
log_dir: Path | None = None,
|
||||
iteration: int | None = None,
|
||||
) -> str:
|
||||
"""Call Claude to improve the description based on eval results."""
|
||||
failed_triggers = [
|
||||
r for r in eval_results["results"]
|
||||
if r["should_trigger"] and not r["pass"]
|
||||
]
|
||||
false_triggers = [
|
||||
r for r in eval_results["results"]
|
||||
if not r["should_trigger"] and not r["pass"]
|
||||
]
|
||||
|
||||
# Build scores summary
|
||||
train_score = f"{eval_results['summary']['passed']}/{eval_results['summary']['total']}"
|
||||
if test_results:
|
||||
test_score = f"{test_results['summary']['passed']}/{test_results['summary']['total']}"
|
||||
scores_summary = f"Train: {train_score}, Test: {test_score}"
|
||||
else:
|
||||
scores_summary = f"Train: {train_score}"
|
||||
|
||||
prompt = f"""You are optimizing a skill description for a Claude Code skill called "{skill_name}". A "skill" is sort of like a prompt, but with progressive disclosure -- there's a title and description that Claude sees when deciding whether to use the skill, and then if it does use the skill, it reads the .md file which has lots more details and potentially links to other resources in the skill folder like helper files and scripts and additional documentation or examples.
|
||||
|
||||
The description appears in Claude's "available_skills" list. When a user sends a query, Claude decides whether to invoke the skill based solely on the title and on this description. Your goal is to write a description that triggers for relevant queries, and doesn't trigger for irrelevant ones.
|
||||
|
||||
Here's the current description:
|
||||
<current_description>
|
||||
"{current_description}"
|
||||
</current_description>
|
||||
|
||||
Current scores ({scores_summary}):
|
||||
<scores_summary>
|
||||
"""
|
||||
if failed_triggers:
|
||||
prompt += "FAILED TO TRIGGER (should have triggered but didn't):\n"
|
||||
for r in failed_triggers:
|
||||
prompt += f' - "{r["query"]}" (triggered {r["triggers"]}/{r["runs"]} times)\n'
|
||||
prompt += "\n"
|
||||
|
||||
if false_triggers:
|
||||
prompt += "FALSE TRIGGERS (triggered but shouldn't have):\n"
|
||||
for r in false_triggers:
|
||||
prompt += f' - "{r["query"]}" (triggered {r["triggers"]}/{r["runs"]} times)\n'
|
||||
prompt += "\n"
|
||||
|
||||
if history:
|
||||
prompt += "PREVIOUS ATTEMPTS (do NOT repeat these — try something structurally different):\n\n"
|
||||
for h in history:
|
||||
train_s = f"{h.get('train_passed', h.get('passed', 0))}/{h.get('train_total', h.get('total', 0))}"
|
||||
test_s = f"{h.get('test_passed', '?')}/{h.get('test_total', '?')}" if h.get('test_passed') is not None else None
|
||||
score_str = f"train={train_s}" + (f", test={test_s}" if test_s else "")
|
||||
prompt += f'<attempt {score_str}>\n'
|
||||
prompt += f'Description: "{h["description"]}"\n'
|
||||
if "results" in h:
|
||||
prompt += "Train results:\n"
|
||||
for r in h["results"]:
|
||||
status = "PASS" if r["pass"] else "FAIL"
|
||||
prompt += f' [{status}] "{r["query"][:80]}" (triggered {r["triggers"]}/{r["runs"]})\n'
|
||||
if h.get("note"):
|
||||
prompt += f'Note: {h["note"]}\n'
|
||||
prompt += "</attempt>\n\n"
|
||||
|
||||
prompt += f"""</scores_summary>
|
||||
|
||||
Skill content (for context on what the skill does):
|
||||
<skill_content>
|
||||
{skill_content}
|
||||
</skill_content>
|
||||
|
||||
Based on the failures, write a new and improved description that is more likely to trigger correctly. When I say "based on the failures", it's a bit of a tricky line to walk because we don't want to overfit to the specific cases you're seeing. So what I DON'T want you to do is produce an ever-expanding list of specific queries that this skill should or shouldn't trigger for. Instead, try to generalize from the failures to broader categories of user intent and situations where this skill would be useful or not useful. The reason for this is twofold:
|
||||
|
||||
1. Avoid overfitting
|
||||
2. The list might get loooong and it's injected into ALL queries and there might be a lot of skills, so we don't want to blow too much space on any given description.
|
||||
|
||||
Concretely, your description should not be more than about 100-200 words, even if that comes at the cost of accuracy. There is a hard limit of 1024 characters — descriptions over that will be truncated, so stay comfortably under it.
|
||||
|
||||
Here are some tips that we've found to work well in writing these descriptions:
|
||||
- The skill should be phrased in the imperative -- "Use this skill for" rather than "this skill does"
|
||||
- The skill description should focus on the user's intent, what they are trying to achieve, vs. the implementation details of how the skill works.
|
||||
- The description competes with other skills for Claude's attention — make it distinctive and immediately recognizable.
|
||||
- If you're getting lots of failures after repeated attempts, change things up. Try different sentence structures or wordings.
|
||||
|
||||
I'd encourage you to be creative and mix up the style in different iterations since you'll have multiple opportunities to try different approaches and we'll just grab the highest-scoring one at the end.
|
||||
|
||||
Please respond with only the new description text in <new_description> tags, nothing else."""
|
||||
|
||||
text = _call_claude(prompt, model)
|
||||
|
||||
match = re.search(r"<new_description>(.*?)</new_description>", text, re.DOTALL)
|
||||
description = match.group(1).strip().strip('"') if match else text.strip().strip('"')
|
||||
|
||||
transcript: dict = {
|
||||
"iteration": iteration,
|
||||
"prompt": prompt,
|
||||
"response": text,
|
||||
"parsed_description": description,
|
||||
"char_count": len(description),
|
||||
"over_limit": len(description) > 1024,
|
||||
}
|
||||
|
||||
# Safety net: the prompt already states the 1024-char hard limit, but if
|
||||
# the model blew past it anyway, make one fresh single-turn call that
|
||||
# quotes the too-long version and asks for a shorter rewrite. (The old
|
||||
# SDK path did this as a true multi-turn; `claude -p` is one-shot, so we
|
||||
# inline the prior output into the new prompt instead.)
|
||||
if len(description) > 1024:
|
||||
shorten_prompt = (
|
||||
f"{prompt}\n\n"
|
||||
f"---\n\n"
|
||||
f"A previous attempt produced this description, which at "
|
||||
f"{len(description)} characters is over the 1024-character hard limit:\n\n"
|
||||
f'"{description}"\n\n'
|
||||
f"Rewrite it to be under 1024 characters while keeping the most "
|
||||
f"important trigger words and intent coverage. Respond with only "
|
||||
f"the new description in <new_description> tags."
|
||||
)
|
||||
shorten_text = _call_claude(shorten_prompt, model)
|
||||
match = re.search(r"<new_description>(.*?)</new_description>", shorten_text, re.DOTALL)
|
||||
shortened = match.group(1).strip().strip('"') if match else shorten_text.strip().strip('"')
|
||||
|
||||
transcript["rewrite_prompt"] = shorten_prompt
|
||||
transcript["rewrite_response"] = shorten_text
|
||||
transcript["rewrite_description"] = shortened
|
||||
transcript["rewrite_char_count"] = len(shortened)
|
||||
description = shortened
|
||||
|
||||
transcript["final_description"] = description
|
||||
|
||||
if log_dir:
|
||||
log_dir.mkdir(parents=True, exist_ok=True)
|
||||
log_file = log_dir / f"improve_iter_{iteration or 'unknown'}.json"
|
||||
log_file.write_text(json.dumps(transcript, indent=2))
|
||||
|
||||
return description
|
||||
|
||||
|
||||
def main():
|
||||
parser = argparse.ArgumentParser(description="Improve a skill description based on eval results")
|
||||
parser.add_argument("--eval-results", required=True, help="Path to eval results JSON (from run_eval.py)")
|
||||
parser.add_argument("--skill-path", required=True, help="Path to skill directory")
|
||||
parser.add_argument("--history", default=None, help="Path to history JSON (previous attempts)")
|
||||
parser.add_argument("--model", required=True, help="Model for improvement")
|
||||
parser.add_argument("--verbose", action="store_true", help="Print thinking to stderr")
|
||||
args = parser.parse_args()
|
||||
|
||||
skill_path = Path(args.skill_path)
|
||||
if not (skill_path / "SKILL.md").exists():
|
||||
print(f"Error: No SKILL.md found at {skill_path}", file=sys.stderr)
|
||||
sys.exit(1)
|
||||
|
||||
eval_results = json.loads(Path(args.eval_results).read_text())
|
||||
history = []
|
||||
if args.history:
|
||||
history = json.loads(Path(args.history).read_text())
|
||||
|
||||
name, _, content = parse_skill_md(skill_path)
|
||||
current_description = eval_results["description"]
|
||||
|
||||
if args.verbose:
|
||||
print(f"Current: {current_description}", file=sys.stderr)
|
||||
print(f"Score: {eval_results['summary']['passed']}/{eval_results['summary']['total']}", file=sys.stderr)
|
||||
|
||||
new_description = improve_description(
|
||||
skill_name=name,
|
||||
skill_content=content,
|
||||
current_description=current_description,
|
||||
eval_results=eval_results,
|
||||
history=history,
|
||||
model=args.model,
|
||||
)
|
||||
|
||||
if args.verbose:
|
||||
print(f"Improved: {new_description}", file=sys.stderr)
|
||||
|
||||
# Output as JSON with both the new description and updated history
|
||||
output = {
|
||||
"description": new_description,
|
||||
"history": history + [{
|
||||
"description": current_description,
|
||||
"passed": eval_results["summary"]["passed"],
|
||||
"failed": eval_results["summary"]["failed"],
|
||||
"total": eval_results["summary"]["total"],
|
||||
"results": eval_results["results"],
|
||||
}],
|
||||
}
|
||||
print(json.dumps(output, indent=2))
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
303
deer-flow/skills/public/skill-creator/scripts/init_skill.py
Executable file
303
deer-flow/skills/public/skill-creator/scripts/init_skill.py
Executable file
@@ -0,0 +1,303 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
Skill Initializer - Creates a new skill from template
|
||||
|
||||
Usage:
|
||||
init_skill.py <skill-name> --path <path>
|
||||
|
||||
Examples:
|
||||
init_skill.py my-new-skill --path skills/public
|
||||
init_skill.py my-api-helper --path skills/private
|
||||
init_skill.py custom-skill --path /custom/location
|
||||
"""
|
||||
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
|
||||
SKILL_TEMPLATE = """---
|
||||
name: {skill_name}
|
||||
description: [TODO: Complete and informative explanation of what the skill does and when to use it. Include WHEN to use this skill - specific scenarios, file types, or tasks that trigger it.]
|
||||
---
|
||||
|
||||
# {skill_title}
|
||||
|
||||
## Overview
|
||||
|
||||
[TODO: 1-2 sentences explaining what this skill enables]
|
||||
|
||||
## Structuring This Skill
|
||||
|
||||
[TODO: Choose the structure that best fits this skill's purpose. Common patterns:
|
||||
|
||||
**1. Workflow-Based** (best for sequential processes)
|
||||
- Works well when there are clear step-by-step procedures
|
||||
- Example: DOCX skill with "Workflow Decision Tree" → "Reading" → "Creating" → "Editing"
|
||||
- Structure: ## Overview → ## Workflow Decision Tree → ## Step 1 → ## Step 2...
|
||||
|
||||
**2. Task-Based** (best for tool collections)
|
||||
- Works well when the skill offers different operations/capabilities
|
||||
- Example: PDF skill with "Quick Start" → "Merge PDFs" → "Split PDFs" → "Extract Text"
|
||||
- Structure: ## Overview → ## Quick Start → ## Task Category 1 → ## Task Category 2...
|
||||
|
||||
**3. Reference/Guidelines** (best for standards or specifications)
|
||||
- Works well for brand guidelines, coding standards, or requirements
|
||||
- Example: Brand styling with "Brand Guidelines" → "Colors" → "Typography" → "Features"
|
||||
- Structure: ## Overview → ## Guidelines → ## Specifications → ## Usage...
|
||||
|
||||
**4. Capabilities-Based** (best for integrated systems)
|
||||
- Works well when the skill provides multiple interrelated features
|
||||
- Example: Product Management with "Core Capabilities" → numbered capability list
|
||||
- Structure: ## Overview → ## Core Capabilities → ### 1. Feature → ### 2. Feature...
|
||||
|
||||
Patterns can be mixed and matched as needed. Most skills combine patterns (e.g., start with task-based, add workflow for complex operations).
|
||||
|
||||
Delete this entire "Structuring This Skill" section when done - it's just guidance.]
|
||||
|
||||
## [TODO: Replace with the first main section based on chosen structure]
|
||||
|
||||
[TODO: Add content here. See examples in existing skills:
|
||||
- Code samples for technical skills
|
||||
- Decision trees for complex workflows
|
||||
- Concrete examples with realistic user requests
|
||||
- References to scripts/templates/references as needed]
|
||||
|
||||
## Resources
|
||||
|
||||
This skill includes example resource directories that demonstrate how to organize different types of bundled resources:
|
||||
|
||||
### scripts/
|
||||
Executable code (Python/Bash/etc.) that can be run directly to perform specific operations.
|
||||
|
||||
**Examples from other skills:**
|
||||
- PDF skill: `fill_fillable_fields.py`, `extract_form_field_info.py` - utilities for PDF manipulation
|
||||
- DOCX skill: `document.py`, `utilities.py` - Python modules for document processing
|
||||
|
||||
**Appropriate for:** Python scripts, shell scripts, or any executable code that performs automation, data processing, or specific operations.
|
||||
|
||||
**Note:** Scripts may be executed without loading into context, but can still be read by Claude for patching or environment adjustments.
|
||||
|
||||
### references/
|
||||
Documentation and reference material intended to be loaded into context to inform Claude's process and thinking.
|
||||
|
||||
**Examples from other skills:**
|
||||
- Product management: `communication.md`, `context_building.md` - detailed workflow guides
|
||||
- BigQuery: API reference documentation and query examples
|
||||
- Finance: Schema documentation, company policies
|
||||
|
||||
**Appropriate for:** In-depth documentation, API references, database schemas, comprehensive guides, or any detailed information that Claude should reference while working.
|
||||
|
||||
### assets/
|
||||
Files not intended to be loaded into context, but rather used within the output Claude produces.
|
||||
|
||||
**Examples from other skills:**
|
||||
- Brand styling: PowerPoint template files (.pptx), logo files
|
||||
- Frontend builder: HTML/React boilerplate project directories
|
||||
- Typography: Font files (.ttf, .woff2)
|
||||
|
||||
**Appropriate for:** Templates, boilerplate code, document templates, images, icons, fonts, or any files meant to be copied or used in the final output.
|
||||
|
||||
---
|
||||
|
||||
**Any unneeded directories can be deleted.** Not every skill requires all three types of resources.
|
||||
"""
|
||||
|
||||
EXAMPLE_SCRIPT = '''#!/usr/bin/env python3
|
||||
"""
|
||||
Example helper script for {skill_name}
|
||||
|
||||
This is a placeholder script that can be executed directly.
|
||||
Replace with actual implementation or delete if not needed.
|
||||
|
||||
Example real scripts from other skills:
|
||||
- pdf/scripts/fill_fillable_fields.py - Fills PDF form fields
|
||||
- pdf/scripts/convert_pdf_to_images.py - Converts PDF pages to images
|
||||
"""
|
||||
|
||||
def main():
|
||||
print("This is an example script for {skill_name}")
|
||||
# TODO: Add actual script logic here
|
||||
# This could be data processing, file conversion, API calls, etc.
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
'''
|
||||
|
||||
EXAMPLE_REFERENCE = """# Reference Documentation for {skill_title}
|
||||
|
||||
This is a placeholder for detailed reference documentation.
|
||||
Replace with actual reference content or delete if not needed.
|
||||
|
||||
Example real reference docs from other skills:
|
||||
- product-management/references/communication.md - Comprehensive guide for status updates
|
||||
- product-management/references/context_building.md - Deep-dive on gathering context
|
||||
- bigquery/references/ - API references and query examples
|
||||
|
||||
## When Reference Docs Are Useful
|
||||
|
||||
Reference docs are ideal for:
|
||||
- Comprehensive API documentation
|
||||
- Detailed workflow guides
|
||||
- Complex multi-step processes
|
||||
- Information too lengthy for main SKILL.md
|
||||
- Content that's only needed for specific use cases
|
||||
|
||||
## Structure Suggestions
|
||||
|
||||
### API Reference Example
|
||||
- Overview
|
||||
- Authentication
|
||||
- Endpoints with examples
|
||||
- Error codes
|
||||
- Rate limits
|
||||
|
||||
### Workflow Guide Example
|
||||
- Prerequisites
|
||||
- Step-by-step instructions
|
||||
- Common patterns
|
||||
- Troubleshooting
|
||||
- Best practices
|
||||
"""
|
||||
|
||||
EXAMPLE_ASSET = """# Example Asset File
|
||||
|
||||
This placeholder represents where asset files would be stored.
|
||||
Replace with actual asset files (templates, images, fonts, etc.) or delete if not needed.
|
||||
|
||||
Asset files are NOT intended to be loaded into context, but rather used within
|
||||
the output Claude produces.
|
||||
|
||||
Example asset files from other skills:
|
||||
- Brand guidelines: logo.png, slides_template.pptx
|
||||
- Frontend builder: hello-world/ directory with HTML/React boilerplate
|
||||
- Typography: custom-font.ttf, font-family.woff2
|
||||
- Data: sample_data.csv, test_dataset.json
|
||||
|
||||
## Common Asset Types
|
||||
|
||||
- Templates: .pptx, .docx, boilerplate directories
|
||||
- Images: .png, .jpg, .svg, .gif
|
||||
- Fonts: .ttf, .otf, .woff, .woff2
|
||||
- Boilerplate code: Project directories, starter files
|
||||
- Icons: .ico, .svg
|
||||
- Data files: .csv, .json, .xml, .yaml
|
||||
|
||||
Note: This is a text placeholder. Actual assets can be any file type.
|
||||
"""
|
||||
|
||||
|
||||
def title_case_skill_name(skill_name):
|
||||
"""Convert hyphenated skill name to Title Case for display."""
|
||||
return ' '.join(word.capitalize() for word in skill_name.split('-'))
|
||||
|
||||
|
||||
def init_skill(skill_name, path):
|
||||
"""
|
||||
Initialize a new skill directory with template SKILL.md.
|
||||
|
||||
Args:
|
||||
skill_name: Name of the skill
|
||||
path: Path where the skill directory should be created
|
||||
|
||||
Returns:
|
||||
Path to created skill directory, or None if error
|
||||
"""
|
||||
# Determine skill directory path
|
||||
skill_dir = Path(path).resolve() / skill_name
|
||||
|
||||
# Check if directory already exists
|
||||
if skill_dir.exists():
|
||||
print(f"❌ Error: Skill directory already exists: {skill_dir}")
|
||||
return None
|
||||
|
||||
# Create skill directory
|
||||
try:
|
||||
skill_dir.mkdir(parents=True, exist_ok=False)
|
||||
print(f"✅ Created skill directory: {skill_dir}")
|
||||
except Exception as e:
|
||||
print(f"❌ Error creating directory: {e}")
|
||||
return None
|
||||
|
||||
# Create SKILL.md from template
|
||||
skill_title = title_case_skill_name(skill_name)
|
||||
skill_content = SKILL_TEMPLATE.format(
|
||||
skill_name=skill_name,
|
||||
skill_title=skill_title
|
||||
)
|
||||
|
||||
skill_md_path = skill_dir / 'SKILL.md'
|
||||
try:
|
||||
skill_md_path.write_text(skill_content)
|
||||
print("✅ Created SKILL.md")
|
||||
except Exception as e:
|
||||
print(f"❌ Error creating SKILL.md: {e}")
|
||||
return None
|
||||
|
||||
# Create resource directories with example files
|
||||
try:
|
||||
# Create scripts/ directory with example script
|
||||
scripts_dir = skill_dir / 'scripts'
|
||||
scripts_dir.mkdir(exist_ok=True)
|
||||
example_script = scripts_dir / 'example.py'
|
||||
example_script.write_text(EXAMPLE_SCRIPT.format(skill_name=skill_name))
|
||||
example_script.chmod(0o755)
|
||||
print("✅ Created scripts/example.py")
|
||||
|
||||
# Create references/ directory with example reference doc
|
||||
references_dir = skill_dir / 'references'
|
||||
references_dir.mkdir(exist_ok=True)
|
||||
example_reference = references_dir / 'api_reference.md'
|
||||
example_reference.write_text(EXAMPLE_REFERENCE.format(skill_title=skill_title))
|
||||
print("✅ Created references/api_reference.md")
|
||||
|
||||
# Create assets/ directory with example asset placeholder
|
||||
assets_dir = skill_dir / 'assets'
|
||||
assets_dir.mkdir(exist_ok=True)
|
||||
example_asset = assets_dir / 'example_asset.txt'
|
||||
example_asset.write_text(EXAMPLE_ASSET)
|
||||
print("✅ Created assets/example_asset.txt")
|
||||
except Exception as e:
|
||||
print(f"❌ Error creating resource directories: {e}")
|
||||
return None
|
||||
|
||||
# Print next steps
|
||||
print(f"\n✅ Skill '{skill_name}' initialized successfully at {skill_dir}")
|
||||
print("\nNext steps:")
|
||||
print("1. Edit SKILL.md to complete the TODO items and update the description")
|
||||
print("2. Customize or delete the example files in scripts/, references/, and assets/")
|
||||
print("3. Run the validator when ready to check the skill structure")
|
||||
|
||||
return skill_dir
|
||||
|
||||
|
||||
def main():
|
||||
if len(sys.argv) < 4 or sys.argv[2] != '--path':
|
||||
print("Usage: init_skill.py <skill-name> --path <path>")
|
||||
print("\nSkill name requirements:")
|
||||
print(" - Hyphen-case identifier (e.g., 'data-analyzer')")
|
||||
print(" - Lowercase letters, digits, and hyphens only")
|
||||
print(" - Max 40 characters")
|
||||
print(" - Must match directory name exactly")
|
||||
print("\nExamples:")
|
||||
print(" init_skill.py my-new-skill --path skills/public")
|
||||
print(" init_skill.py my-api-helper --path skills/private")
|
||||
print(" init_skill.py custom-skill --path /custom/location")
|
||||
sys.exit(1)
|
||||
|
||||
skill_name = sys.argv[1]
|
||||
path = sys.argv[3]
|
||||
|
||||
print(f"🚀 Initializing skill: {skill_name}")
|
||||
print(f" Location: {path}")
|
||||
print()
|
||||
|
||||
result = init_skill(skill_name, path)
|
||||
|
||||
if result:
|
||||
sys.exit(0)
|
||||
else:
|
||||
sys.exit(1)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
136
deer-flow/skills/public/skill-creator/scripts/package_skill.py
Executable file
136
deer-flow/skills/public/skill-creator/scripts/package_skill.py
Executable file
@@ -0,0 +1,136 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
Skill Packager - Creates a distributable .skill file of a skill folder
|
||||
|
||||
Usage:
|
||||
python utils/package_skill.py <path/to/skill-folder> [output-directory]
|
||||
|
||||
Example:
|
||||
python utils/package_skill.py skills/public/my-skill
|
||||
python utils/package_skill.py skills/public/my-skill ./dist
|
||||
"""
|
||||
|
||||
import fnmatch
|
||||
import sys
|
||||
import zipfile
|
||||
from pathlib import Path
|
||||
from scripts.quick_validate import validate_skill
|
||||
|
||||
# Patterns to exclude when packaging skills.
|
||||
EXCLUDE_DIRS = {"__pycache__", "node_modules"}
|
||||
EXCLUDE_GLOBS = {"*.pyc"}
|
||||
EXCLUDE_FILES = {".DS_Store"}
|
||||
# Directories excluded only at the skill root (not when nested deeper).
|
||||
ROOT_EXCLUDE_DIRS = {"evals"}
|
||||
|
||||
|
||||
def should_exclude(rel_path: Path) -> bool:
|
||||
"""Check if a path should be excluded from packaging."""
|
||||
parts = rel_path.parts
|
||||
if any(part in EXCLUDE_DIRS for part in parts):
|
||||
return True
|
||||
# rel_path is relative to skill_path.parent, so parts[0] is the skill
|
||||
# folder name and parts[1] (if present) is the first subdir.
|
||||
if len(parts) > 1 and parts[1] in ROOT_EXCLUDE_DIRS:
|
||||
return True
|
||||
name = rel_path.name
|
||||
if name in EXCLUDE_FILES:
|
||||
return True
|
||||
return any(fnmatch.fnmatch(name, pat) for pat in EXCLUDE_GLOBS)
|
||||
|
||||
|
||||
def package_skill(skill_path, output_dir=None):
|
||||
"""
|
||||
Package a skill folder into a .skill file.
|
||||
|
||||
Args:
|
||||
skill_path: Path to the skill folder
|
||||
output_dir: Optional output directory for the .skill file (defaults to current directory)
|
||||
|
||||
Returns:
|
||||
Path to the created .skill file, or None if error
|
||||
"""
|
||||
skill_path = Path(skill_path).resolve()
|
||||
|
||||
# Validate skill folder exists
|
||||
if not skill_path.exists():
|
||||
print(f"❌ Error: Skill folder not found: {skill_path}")
|
||||
return None
|
||||
|
||||
if not skill_path.is_dir():
|
||||
print(f"❌ Error: Path is not a directory: {skill_path}")
|
||||
return None
|
||||
|
||||
# Validate SKILL.md exists
|
||||
skill_md = skill_path / "SKILL.md"
|
||||
if not skill_md.exists():
|
||||
print(f"❌ Error: SKILL.md not found in {skill_path}")
|
||||
return None
|
||||
|
||||
# Run validation before packaging
|
||||
print("🔍 Validating skill...")
|
||||
valid, message = validate_skill(skill_path)
|
||||
if not valid:
|
||||
print(f"❌ Validation failed: {message}")
|
||||
print(" Please fix the validation errors before packaging.")
|
||||
return None
|
||||
print(f"✅ {message}\n")
|
||||
|
||||
# Determine output location
|
||||
skill_name = skill_path.name
|
||||
if output_dir:
|
||||
output_path = Path(output_dir).resolve()
|
||||
output_path.mkdir(parents=True, exist_ok=True)
|
||||
else:
|
||||
output_path = Path.cwd()
|
||||
|
||||
skill_filename = output_path / f"{skill_name}.skill"
|
||||
|
||||
# Create the .skill file (zip format)
|
||||
try:
|
||||
with zipfile.ZipFile(skill_filename, 'w', zipfile.ZIP_DEFLATED) as zipf:
|
||||
# Walk through the skill directory, excluding build artifacts
|
||||
for file_path in skill_path.rglob('*'):
|
||||
if not file_path.is_file():
|
||||
continue
|
||||
arcname = file_path.relative_to(skill_path.parent)
|
||||
if should_exclude(arcname):
|
||||
print(f" Skipped: {arcname}")
|
||||
continue
|
||||
zipf.write(file_path, arcname)
|
||||
print(f" Added: {arcname}")
|
||||
|
||||
print(f"\n✅ Successfully packaged skill to: {skill_filename}")
|
||||
return skill_filename
|
||||
|
||||
except Exception as e:
|
||||
print(f"❌ Error creating .skill file: {e}")
|
||||
return None
|
||||
|
||||
|
||||
def main():
|
||||
if len(sys.argv) < 2:
|
||||
print("Usage: python utils/package_skill.py <path/to/skill-folder> [output-directory]")
|
||||
print("\nExample:")
|
||||
print(" python utils/package_skill.py skills/public/my-skill")
|
||||
print(" python utils/package_skill.py skills/public/my-skill ./dist")
|
||||
sys.exit(1)
|
||||
|
||||
skill_path = sys.argv[1]
|
||||
output_dir = sys.argv[2] if len(sys.argv) > 2 else None
|
||||
|
||||
print(f"📦 Packaging skill: {skill_path}")
|
||||
if output_dir:
|
||||
print(f" Output directory: {output_dir}")
|
||||
print()
|
||||
|
||||
result = package_skill(skill_path, output_dir)
|
||||
|
||||
if result:
|
||||
sys.exit(0)
|
||||
else:
|
||||
sys.exit(1)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
103
deer-flow/skills/public/skill-creator/scripts/quick_validate.py
Executable file
103
deer-flow/skills/public/skill-creator/scripts/quick_validate.py
Executable file
@@ -0,0 +1,103 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
Quick validation script for skills - minimal version
|
||||
"""
|
||||
|
||||
import sys
|
||||
import os
|
||||
import re
|
||||
import yaml
|
||||
from pathlib import Path
|
||||
|
||||
def validate_skill(skill_path):
|
||||
"""Basic validation of a skill"""
|
||||
skill_path = Path(skill_path)
|
||||
|
||||
# Check SKILL.md exists
|
||||
skill_md = skill_path / 'SKILL.md'
|
||||
if not skill_md.exists():
|
||||
return False, "SKILL.md not found"
|
||||
|
||||
# Read and validate frontmatter
|
||||
content = skill_md.read_text()
|
||||
if not content.startswith('---'):
|
||||
return False, "No YAML frontmatter found"
|
||||
|
||||
# Extract frontmatter
|
||||
match = re.match(r'^---\n(.*?)\n---', content, re.DOTALL)
|
||||
if not match:
|
||||
return False, "Invalid frontmatter format"
|
||||
|
||||
frontmatter_text = match.group(1)
|
||||
|
||||
# Parse YAML frontmatter
|
||||
try:
|
||||
frontmatter = yaml.safe_load(frontmatter_text)
|
||||
if not isinstance(frontmatter, dict):
|
||||
return False, "Frontmatter must be a YAML dictionary"
|
||||
except yaml.YAMLError as e:
|
||||
return False, f"Invalid YAML in frontmatter: {e}"
|
||||
|
||||
# Define allowed properties
|
||||
ALLOWED_PROPERTIES = {'name', 'description', 'license', 'allowed-tools', 'metadata', 'compatibility'}
|
||||
|
||||
# Check for unexpected properties (excluding nested keys under metadata)
|
||||
unexpected_keys = set(frontmatter.keys()) - ALLOWED_PROPERTIES
|
||||
if unexpected_keys:
|
||||
return False, (
|
||||
f"Unexpected key(s) in SKILL.md frontmatter: {', '.join(sorted(unexpected_keys))}. "
|
||||
f"Allowed properties are: {', '.join(sorted(ALLOWED_PROPERTIES))}"
|
||||
)
|
||||
|
||||
# Check required fields
|
||||
if 'name' not in frontmatter:
|
||||
return False, "Missing 'name' in frontmatter"
|
||||
if 'description' not in frontmatter:
|
||||
return False, "Missing 'description' in frontmatter"
|
||||
|
||||
# Extract name for validation
|
||||
name = frontmatter.get('name', '')
|
||||
if not isinstance(name, str):
|
||||
return False, f"Name must be a string, got {type(name).__name__}"
|
||||
name = name.strip()
|
||||
if name:
|
||||
# Check naming convention (kebab-case: lowercase with hyphens)
|
||||
if not re.match(r'^[a-z0-9-]+$', name):
|
||||
return False, f"Name '{name}' should be kebab-case (lowercase letters, digits, and hyphens only)"
|
||||
if name.startswith('-') or name.endswith('-') or '--' in name:
|
||||
return False, f"Name '{name}' cannot start/end with hyphen or contain consecutive hyphens"
|
||||
# Check name length (max 64 characters per spec)
|
||||
if len(name) > 64:
|
||||
return False, f"Name is too long ({len(name)} characters). Maximum is 64 characters."
|
||||
|
||||
# Extract and validate description
|
||||
description = frontmatter.get('description', '')
|
||||
if not isinstance(description, str):
|
||||
return False, f"Description must be a string, got {type(description).__name__}"
|
||||
description = description.strip()
|
||||
if description:
|
||||
# Check for angle brackets
|
||||
if '<' in description or '>' in description:
|
||||
return False, "Description cannot contain angle brackets (< or >)"
|
||||
# Check description length (max 1024 characters per spec)
|
||||
if len(description) > 1024:
|
||||
return False, f"Description is too long ({len(description)} characters). Maximum is 1024 characters."
|
||||
|
||||
# Validate compatibility field if present (optional)
|
||||
compatibility = frontmatter.get('compatibility', '')
|
||||
if compatibility:
|
||||
if not isinstance(compatibility, str):
|
||||
return False, f"Compatibility must be a string, got {type(compatibility).__name__}"
|
||||
if len(compatibility) > 500:
|
||||
return False, f"Compatibility is too long ({len(compatibility)} characters). Maximum is 500 characters."
|
||||
|
||||
return True, "Skill is valid!"
|
||||
|
||||
if __name__ == "__main__":
|
||||
if len(sys.argv) != 2:
|
||||
print("Usage: python quick_validate.py <skill_directory>")
|
||||
sys.exit(1)
|
||||
|
||||
valid, message = validate_skill(sys.argv[1])
|
||||
print(message)
|
||||
sys.exit(0 if valid else 1)
|
||||
310
deer-flow/skills/public/skill-creator/scripts/run_eval.py
Executable file
310
deer-flow/skills/public/skill-creator/scripts/run_eval.py
Executable file
@@ -0,0 +1,310 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Run trigger evaluation for a skill description.
|
||||
|
||||
Tests whether a skill's description causes Claude to trigger (read the skill)
|
||||
for a set of queries. Outputs results as JSON.
|
||||
"""
|
||||
|
||||
import argparse
|
||||
import json
|
||||
import os
|
||||
import select
|
||||
import subprocess
|
||||
import sys
|
||||
import time
|
||||
import uuid
|
||||
from concurrent.futures import ProcessPoolExecutor, as_completed
|
||||
from pathlib import Path
|
||||
|
||||
from scripts.utils import parse_skill_md
|
||||
|
||||
|
||||
def find_project_root() -> Path:
|
||||
"""Find the project root by walking up from cwd looking for .claude/.
|
||||
|
||||
Mimics how Claude Code discovers its project root, so the command file
|
||||
we create ends up where claude -p will look for it.
|
||||
"""
|
||||
current = Path.cwd()
|
||||
for parent in [current, *current.parents]:
|
||||
if (parent / ".claude").is_dir():
|
||||
return parent
|
||||
return current
|
||||
|
||||
|
||||
def run_single_query(
|
||||
query: str,
|
||||
skill_name: str,
|
||||
skill_description: str,
|
||||
timeout: int,
|
||||
project_root: str,
|
||||
model: str | None = None,
|
||||
) -> bool:
|
||||
"""Run a single query and return whether the skill was triggered.
|
||||
|
||||
Creates a command file in .claude/commands/ so it appears in Claude's
|
||||
available_skills list, then runs `claude -p` with the raw query.
|
||||
Uses --include-partial-messages to detect triggering early from
|
||||
stream events (content_block_start) rather than waiting for the
|
||||
full assistant message, which only arrives after tool execution.
|
||||
"""
|
||||
unique_id = uuid.uuid4().hex[:8]
|
||||
clean_name = f"{skill_name}-skill-{unique_id}"
|
||||
project_commands_dir = Path(project_root) / ".claude" / "commands"
|
||||
command_file = project_commands_dir / f"{clean_name}.md"
|
||||
|
||||
try:
|
||||
project_commands_dir.mkdir(parents=True, exist_ok=True)
|
||||
# Use YAML block scalar to avoid breaking on quotes in description
|
||||
indented_desc = "\n ".join(skill_description.split("\n"))
|
||||
command_content = (
|
||||
f"---\n"
|
||||
f"description: |\n"
|
||||
f" {indented_desc}\n"
|
||||
f"---\n\n"
|
||||
f"# {skill_name}\n\n"
|
||||
f"This skill handles: {skill_description}\n"
|
||||
)
|
||||
command_file.write_text(command_content)
|
||||
|
||||
cmd = [
|
||||
"claude",
|
||||
"-p", query,
|
||||
"--output-format", "stream-json",
|
||||
"--verbose",
|
||||
"--include-partial-messages",
|
||||
]
|
||||
if model:
|
||||
cmd.extend(["--model", model])
|
||||
|
||||
# Remove CLAUDECODE env var to allow nesting claude -p inside a
|
||||
# Claude Code session. The guard is for interactive terminal conflicts;
|
||||
# programmatic subprocess usage is safe.
|
||||
env = {k: v for k, v in os.environ.items() if k != "CLAUDECODE"}
|
||||
|
||||
process = subprocess.Popen(
|
||||
cmd,
|
||||
stdout=subprocess.PIPE,
|
||||
stderr=subprocess.DEVNULL,
|
||||
cwd=project_root,
|
||||
env=env,
|
||||
)
|
||||
|
||||
triggered = False
|
||||
start_time = time.time()
|
||||
buffer = ""
|
||||
# Track state for stream event detection
|
||||
pending_tool_name = None
|
||||
accumulated_json = ""
|
||||
|
||||
try:
|
||||
while time.time() - start_time < timeout:
|
||||
if process.poll() is not None:
|
||||
remaining = process.stdout.read()
|
||||
if remaining:
|
||||
buffer += remaining.decode("utf-8", errors="replace")
|
||||
break
|
||||
|
||||
ready, _, _ = select.select([process.stdout], [], [], 1.0)
|
||||
if not ready:
|
||||
continue
|
||||
|
||||
chunk = os.read(process.stdout.fileno(), 8192)
|
||||
if not chunk:
|
||||
break
|
||||
buffer += chunk.decode("utf-8", errors="replace")
|
||||
|
||||
while "\n" in buffer:
|
||||
line, buffer = buffer.split("\n", 1)
|
||||
line = line.strip()
|
||||
if not line:
|
||||
continue
|
||||
|
||||
try:
|
||||
event = json.loads(line)
|
||||
except json.JSONDecodeError:
|
||||
continue
|
||||
|
||||
# Early detection via stream events
|
||||
if event.get("type") == "stream_event":
|
||||
se = event.get("event", {})
|
||||
se_type = se.get("type", "")
|
||||
|
||||
if se_type == "content_block_start":
|
||||
cb = se.get("content_block", {})
|
||||
if cb.get("type") == "tool_use":
|
||||
tool_name = cb.get("name", "")
|
||||
if tool_name in ("Skill", "Read"):
|
||||
pending_tool_name = tool_name
|
||||
accumulated_json = ""
|
||||
else:
|
||||
return False
|
||||
|
||||
elif se_type == "content_block_delta" and pending_tool_name:
|
||||
delta = se.get("delta", {})
|
||||
if delta.get("type") == "input_json_delta":
|
||||
accumulated_json += delta.get("partial_json", "")
|
||||
if clean_name in accumulated_json:
|
||||
return True
|
||||
|
||||
elif se_type in ("content_block_stop", "message_stop"):
|
||||
if pending_tool_name:
|
||||
return clean_name in accumulated_json
|
||||
if se_type == "message_stop":
|
||||
return False
|
||||
|
||||
# Fallback: full assistant message
|
||||
elif event.get("type") == "assistant":
|
||||
message = event.get("message", {})
|
||||
for content_item in message.get("content", []):
|
||||
if content_item.get("type") != "tool_use":
|
||||
continue
|
||||
tool_name = content_item.get("name", "")
|
||||
tool_input = content_item.get("input", {})
|
||||
if tool_name == "Skill" and clean_name in tool_input.get("skill", ""):
|
||||
triggered = True
|
||||
elif tool_name == "Read" and clean_name in tool_input.get("file_path", ""):
|
||||
triggered = True
|
||||
return triggered
|
||||
|
||||
elif event.get("type") == "result":
|
||||
return triggered
|
||||
finally:
|
||||
# Clean up process on any exit path (return, exception, timeout)
|
||||
if process.poll() is None:
|
||||
process.kill()
|
||||
process.wait()
|
||||
|
||||
return triggered
|
||||
finally:
|
||||
if command_file.exists():
|
||||
command_file.unlink()
|
||||
|
||||
|
||||
def run_eval(
|
||||
eval_set: list[dict],
|
||||
skill_name: str,
|
||||
description: str,
|
||||
num_workers: int,
|
||||
timeout: int,
|
||||
project_root: Path,
|
||||
runs_per_query: int = 1,
|
||||
trigger_threshold: float = 0.5,
|
||||
model: str | None = None,
|
||||
) -> dict:
|
||||
"""Run the full eval set and return results."""
|
||||
results = []
|
||||
|
||||
with ProcessPoolExecutor(max_workers=num_workers) as executor:
|
||||
future_to_info = {}
|
||||
for item in eval_set:
|
||||
for run_idx in range(runs_per_query):
|
||||
future = executor.submit(
|
||||
run_single_query,
|
||||
item["query"],
|
||||
skill_name,
|
||||
description,
|
||||
timeout,
|
||||
str(project_root),
|
||||
model,
|
||||
)
|
||||
future_to_info[future] = (item, run_idx)
|
||||
|
||||
query_triggers: dict[str, list[bool]] = {}
|
||||
query_items: dict[str, dict] = {}
|
||||
for future in as_completed(future_to_info):
|
||||
item, _ = future_to_info[future]
|
||||
query = item["query"]
|
||||
query_items[query] = item
|
||||
if query not in query_triggers:
|
||||
query_triggers[query] = []
|
||||
try:
|
||||
query_triggers[query].append(future.result())
|
||||
except Exception as e:
|
||||
print(f"Warning: query failed: {e}", file=sys.stderr)
|
||||
query_triggers[query].append(False)
|
||||
|
||||
for query, triggers in query_triggers.items():
|
||||
item = query_items[query]
|
||||
trigger_rate = sum(triggers) / len(triggers)
|
||||
should_trigger = item["should_trigger"]
|
||||
if should_trigger:
|
||||
did_pass = trigger_rate >= trigger_threshold
|
||||
else:
|
||||
did_pass = trigger_rate < trigger_threshold
|
||||
results.append({
|
||||
"query": query,
|
||||
"should_trigger": should_trigger,
|
||||
"trigger_rate": trigger_rate,
|
||||
"triggers": sum(triggers),
|
||||
"runs": len(triggers),
|
||||
"pass": did_pass,
|
||||
})
|
||||
|
||||
passed = sum(1 for r in results if r["pass"])
|
||||
total = len(results)
|
||||
|
||||
return {
|
||||
"skill_name": skill_name,
|
||||
"description": description,
|
||||
"results": results,
|
||||
"summary": {
|
||||
"total": total,
|
||||
"passed": passed,
|
||||
"failed": total - passed,
|
||||
},
|
||||
}
|
||||
|
||||
|
||||
def main():
|
||||
parser = argparse.ArgumentParser(description="Run trigger evaluation for a skill description")
|
||||
parser.add_argument("--eval-set", required=True, help="Path to eval set JSON file")
|
||||
parser.add_argument("--skill-path", required=True, help="Path to skill directory")
|
||||
parser.add_argument("--description", default=None, help="Override description to test")
|
||||
parser.add_argument("--num-workers", type=int, default=10, help="Number of parallel workers")
|
||||
parser.add_argument("--timeout", type=int, default=30, help="Timeout per query in seconds")
|
||||
parser.add_argument("--runs-per-query", type=int, default=3, help="Number of runs per query")
|
||||
parser.add_argument("--trigger-threshold", type=float, default=0.5, help="Trigger rate threshold")
|
||||
parser.add_argument("--model", default=None, help="Model to use for claude -p (default: user's configured model)")
|
||||
parser.add_argument("--verbose", action="store_true", help="Print progress to stderr")
|
||||
args = parser.parse_args()
|
||||
|
||||
eval_set = json.loads(Path(args.eval_set).read_text())
|
||||
skill_path = Path(args.skill_path)
|
||||
|
||||
if not (skill_path / "SKILL.md").exists():
|
||||
print(f"Error: No SKILL.md found at {skill_path}", file=sys.stderr)
|
||||
sys.exit(1)
|
||||
|
||||
name, original_description, content = parse_skill_md(skill_path)
|
||||
description = args.description or original_description
|
||||
project_root = find_project_root()
|
||||
|
||||
if args.verbose:
|
||||
print(f"Evaluating: {description}", file=sys.stderr)
|
||||
|
||||
output = run_eval(
|
||||
eval_set=eval_set,
|
||||
skill_name=name,
|
||||
description=description,
|
||||
num_workers=args.num_workers,
|
||||
timeout=args.timeout,
|
||||
project_root=project_root,
|
||||
runs_per_query=args.runs_per_query,
|
||||
trigger_threshold=args.trigger_threshold,
|
||||
model=args.model,
|
||||
)
|
||||
|
||||
if args.verbose:
|
||||
summary = output["summary"]
|
||||
print(f"Results: {summary['passed']}/{summary['total']} passed", file=sys.stderr)
|
||||
for r in output["results"]:
|
||||
status = "PASS" if r["pass"] else "FAIL"
|
||||
rate_str = f"{r['triggers']}/{r['runs']}"
|
||||
print(f" [{status}] rate={rate_str} expected={r['should_trigger']}: {r['query'][:70]}", file=sys.stderr)
|
||||
|
||||
print(json.dumps(output, indent=2))
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
328
deer-flow/skills/public/skill-creator/scripts/run_loop.py
Executable file
328
deer-flow/skills/public/skill-creator/scripts/run_loop.py
Executable file
@@ -0,0 +1,328 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Run the eval + improve loop until all pass or max iterations reached.
|
||||
|
||||
Combines run_eval.py and improve_description.py in a loop, tracking history
|
||||
and returning the best description found. Supports train/test split to prevent
|
||||
overfitting.
|
||||
"""
|
||||
|
||||
import argparse
|
||||
import json
|
||||
import random
|
||||
import sys
|
||||
import tempfile
|
||||
import time
|
||||
import webbrowser
|
||||
from pathlib import Path
|
||||
|
||||
from scripts.generate_report import generate_html
|
||||
from scripts.improve_description import improve_description
|
||||
from scripts.run_eval import find_project_root, run_eval
|
||||
from scripts.utils import parse_skill_md
|
||||
|
||||
|
||||
def split_eval_set(eval_set: list[dict], holdout: float, seed: int = 42) -> tuple[list[dict], list[dict]]:
|
||||
"""Split eval set into train and test sets, stratified by should_trigger."""
|
||||
random.seed(seed)
|
||||
|
||||
# Separate by should_trigger
|
||||
trigger = [e for e in eval_set if e["should_trigger"]]
|
||||
no_trigger = [e for e in eval_set if not e["should_trigger"]]
|
||||
|
||||
# Shuffle each group
|
||||
random.shuffle(trigger)
|
||||
random.shuffle(no_trigger)
|
||||
|
||||
# Calculate split points
|
||||
n_trigger_test = max(1, int(len(trigger) * holdout))
|
||||
n_no_trigger_test = max(1, int(len(no_trigger) * holdout))
|
||||
|
||||
# Split
|
||||
test_set = trigger[:n_trigger_test] + no_trigger[:n_no_trigger_test]
|
||||
train_set = trigger[n_trigger_test:] + no_trigger[n_no_trigger_test:]
|
||||
|
||||
return train_set, test_set
|
||||
|
||||
|
||||
def run_loop(
|
||||
eval_set: list[dict],
|
||||
skill_path: Path,
|
||||
description_override: str | None,
|
||||
num_workers: int,
|
||||
timeout: int,
|
||||
max_iterations: int,
|
||||
runs_per_query: int,
|
||||
trigger_threshold: float,
|
||||
holdout: float,
|
||||
model: str,
|
||||
verbose: bool,
|
||||
live_report_path: Path | None = None,
|
||||
log_dir: Path | None = None,
|
||||
) -> dict:
|
||||
"""Run the eval + improvement loop."""
|
||||
project_root = find_project_root()
|
||||
name, original_description, content = parse_skill_md(skill_path)
|
||||
current_description = description_override or original_description
|
||||
|
||||
# Split into train/test if holdout > 0
|
||||
if holdout > 0:
|
||||
train_set, test_set = split_eval_set(eval_set, holdout)
|
||||
if verbose:
|
||||
print(f"Split: {len(train_set)} train, {len(test_set)} test (holdout={holdout})", file=sys.stderr)
|
||||
else:
|
||||
train_set = eval_set
|
||||
test_set = []
|
||||
|
||||
history = []
|
||||
exit_reason = "unknown"
|
||||
|
||||
for iteration in range(1, max_iterations + 1):
|
||||
if verbose:
|
||||
print(f"\n{'='*60}", file=sys.stderr)
|
||||
print(f"Iteration {iteration}/{max_iterations}", file=sys.stderr)
|
||||
print(f"Description: {current_description}", file=sys.stderr)
|
||||
print(f"{'='*60}", file=sys.stderr)
|
||||
|
||||
# Evaluate train + test together in one batch for parallelism
|
||||
all_queries = train_set + test_set
|
||||
t0 = time.time()
|
||||
all_results = run_eval(
|
||||
eval_set=all_queries,
|
||||
skill_name=name,
|
||||
description=current_description,
|
||||
num_workers=num_workers,
|
||||
timeout=timeout,
|
||||
project_root=project_root,
|
||||
runs_per_query=runs_per_query,
|
||||
trigger_threshold=trigger_threshold,
|
||||
model=model,
|
||||
)
|
||||
eval_elapsed = time.time() - t0
|
||||
|
||||
# Split results back into train/test by matching queries
|
||||
train_queries_set = {q["query"] for q in train_set}
|
||||
train_result_list = [r for r in all_results["results"] if r["query"] in train_queries_set]
|
||||
test_result_list = [r for r in all_results["results"] if r["query"] not in train_queries_set]
|
||||
|
||||
train_passed = sum(1 for r in train_result_list if r["pass"])
|
||||
train_total = len(train_result_list)
|
||||
train_summary = {"passed": train_passed, "failed": train_total - train_passed, "total": train_total}
|
||||
train_results = {"results": train_result_list, "summary": train_summary}
|
||||
|
||||
if test_set:
|
||||
test_passed = sum(1 for r in test_result_list if r["pass"])
|
||||
test_total = len(test_result_list)
|
||||
test_summary = {"passed": test_passed, "failed": test_total - test_passed, "total": test_total}
|
||||
test_results = {"results": test_result_list, "summary": test_summary}
|
||||
else:
|
||||
test_results = None
|
||||
test_summary = None
|
||||
|
||||
history.append({
|
||||
"iteration": iteration,
|
||||
"description": current_description,
|
||||
"train_passed": train_summary["passed"],
|
||||
"train_failed": train_summary["failed"],
|
||||
"train_total": train_summary["total"],
|
||||
"train_results": train_results["results"],
|
||||
"test_passed": test_summary["passed"] if test_summary else None,
|
||||
"test_failed": test_summary["failed"] if test_summary else None,
|
||||
"test_total": test_summary["total"] if test_summary else None,
|
||||
"test_results": test_results["results"] if test_results else None,
|
||||
# For backward compat with report generator
|
||||
"passed": train_summary["passed"],
|
||||
"failed": train_summary["failed"],
|
||||
"total": train_summary["total"],
|
||||
"results": train_results["results"],
|
||||
})
|
||||
|
||||
# Write live report if path provided
|
||||
if live_report_path:
|
||||
partial_output = {
|
||||
"original_description": original_description,
|
||||
"best_description": current_description,
|
||||
"best_score": "in progress",
|
||||
"iterations_run": len(history),
|
||||
"holdout": holdout,
|
||||
"train_size": len(train_set),
|
||||
"test_size": len(test_set),
|
||||
"history": history,
|
||||
}
|
||||
live_report_path.write_text(generate_html(partial_output, auto_refresh=True, skill_name=name))
|
||||
|
||||
if verbose:
|
||||
def print_eval_stats(label, results, elapsed):
|
||||
pos = [r for r in results if r["should_trigger"]]
|
||||
neg = [r for r in results if not r["should_trigger"]]
|
||||
tp = sum(r["triggers"] for r in pos)
|
||||
pos_runs = sum(r["runs"] for r in pos)
|
||||
fn = pos_runs - tp
|
||||
fp = sum(r["triggers"] for r in neg)
|
||||
neg_runs = sum(r["runs"] for r in neg)
|
||||
tn = neg_runs - fp
|
||||
total = tp + tn + fp + fn
|
||||
precision = tp / (tp + fp) if (tp + fp) > 0 else 1.0
|
||||
recall = tp / (tp + fn) if (tp + fn) > 0 else 1.0
|
||||
accuracy = (tp + tn) / total if total > 0 else 0.0
|
||||
print(f"{label}: {tp+tn}/{total} correct, precision={precision:.0%} recall={recall:.0%} accuracy={accuracy:.0%} ({elapsed:.1f}s)", file=sys.stderr)
|
||||
for r in results:
|
||||
status = "PASS" if r["pass"] else "FAIL"
|
||||
rate_str = f"{r['triggers']}/{r['runs']}"
|
||||
print(f" [{status}] rate={rate_str} expected={r['should_trigger']}: {r['query'][:60]}", file=sys.stderr)
|
||||
|
||||
print_eval_stats("Train", train_results["results"], eval_elapsed)
|
||||
if test_summary:
|
||||
print_eval_stats("Test ", test_results["results"], 0)
|
||||
|
||||
if train_summary["failed"] == 0:
|
||||
exit_reason = f"all_passed (iteration {iteration})"
|
||||
if verbose:
|
||||
print(f"\nAll train queries passed on iteration {iteration}!", file=sys.stderr)
|
||||
break
|
||||
|
||||
if iteration == max_iterations:
|
||||
exit_reason = f"max_iterations ({max_iterations})"
|
||||
if verbose:
|
||||
print(f"\nMax iterations reached ({max_iterations}).", file=sys.stderr)
|
||||
break
|
||||
|
||||
# Improve the description based on train results
|
||||
if verbose:
|
||||
print(f"\nImproving description...", file=sys.stderr)
|
||||
|
||||
t0 = time.time()
|
||||
# Strip test scores from history so improvement model can't see them
|
||||
blinded_history = [
|
||||
{k: v for k, v in h.items() if not k.startswith("test_")}
|
||||
for h in history
|
||||
]
|
||||
new_description = improve_description(
|
||||
skill_name=name,
|
||||
skill_content=content,
|
||||
current_description=current_description,
|
||||
eval_results=train_results,
|
||||
history=blinded_history,
|
||||
model=model,
|
||||
log_dir=log_dir,
|
||||
iteration=iteration,
|
||||
)
|
||||
improve_elapsed = time.time() - t0
|
||||
|
||||
if verbose:
|
||||
print(f"Proposed ({improve_elapsed:.1f}s): {new_description}", file=sys.stderr)
|
||||
|
||||
current_description = new_description
|
||||
|
||||
# Find the best iteration by TEST score (or train if no test set)
|
||||
if test_set:
|
||||
best = max(history, key=lambda h: h["test_passed"] or 0)
|
||||
best_score = f"{best['test_passed']}/{best['test_total']}"
|
||||
else:
|
||||
best = max(history, key=lambda h: h["train_passed"])
|
||||
best_score = f"{best['train_passed']}/{best['train_total']}"
|
||||
|
||||
if verbose:
|
||||
print(f"\nExit reason: {exit_reason}", file=sys.stderr)
|
||||
print(f"Best score: {best_score} (iteration {best['iteration']})", file=sys.stderr)
|
||||
|
||||
return {
|
||||
"exit_reason": exit_reason,
|
||||
"original_description": original_description,
|
||||
"best_description": best["description"],
|
||||
"best_score": best_score,
|
||||
"best_train_score": f"{best['train_passed']}/{best['train_total']}",
|
||||
"best_test_score": f"{best['test_passed']}/{best['test_total']}" if test_set else None,
|
||||
"final_description": current_description,
|
||||
"iterations_run": len(history),
|
||||
"holdout": holdout,
|
||||
"train_size": len(train_set),
|
||||
"test_size": len(test_set),
|
||||
"history": history,
|
||||
}
|
||||
|
||||
|
||||
def main():
|
||||
parser = argparse.ArgumentParser(description="Run eval + improve loop")
|
||||
parser.add_argument("--eval-set", required=True, help="Path to eval set JSON file")
|
||||
parser.add_argument("--skill-path", required=True, help="Path to skill directory")
|
||||
parser.add_argument("--description", default=None, help="Override starting description")
|
||||
parser.add_argument("--num-workers", type=int, default=10, help="Number of parallel workers")
|
||||
parser.add_argument("--timeout", type=int, default=30, help="Timeout per query in seconds")
|
||||
parser.add_argument("--max-iterations", type=int, default=5, help="Max improvement iterations")
|
||||
parser.add_argument("--runs-per-query", type=int, default=3, help="Number of runs per query")
|
||||
parser.add_argument("--trigger-threshold", type=float, default=0.5, help="Trigger rate threshold")
|
||||
parser.add_argument("--holdout", type=float, default=0.4, help="Fraction of eval set to hold out for testing (0 to disable)")
|
||||
parser.add_argument("--model", required=True, help="Model for improvement")
|
||||
parser.add_argument("--verbose", action="store_true", help="Print progress to stderr")
|
||||
parser.add_argument("--report", default="auto", help="Generate HTML report at this path (default: 'auto' for temp file, 'none' to disable)")
|
||||
parser.add_argument("--results-dir", default=None, help="Save all outputs (results.json, report.html, log.txt) to a timestamped subdirectory here")
|
||||
args = parser.parse_args()
|
||||
|
||||
eval_set = json.loads(Path(args.eval_set).read_text())
|
||||
skill_path = Path(args.skill_path)
|
||||
|
||||
if not (skill_path / "SKILL.md").exists():
|
||||
print(f"Error: No SKILL.md found at {skill_path}", file=sys.stderr)
|
||||
sys.exit(1)
|
||||
|
||||
name, _, _ = parse_skill_md(skill_path)
|
||||
|
||||
# Set up live report path
|
||||
if args.report != "none":
|
||||
if args.report == "auto":
|
||||
timestamp = time.strftime("%Y%m%d_%H%M%S")
|
||||
live_report_path = Path(tempfile.gettempdir()) / f"skill_description_report_{skill_path.name}_{timestamp}.html"
|
||||
else:
|
||||
live_report_path = Path(args.report)
|
||||
# Open the report immediately so the user can watch
|
||||
live_report_path.write_text("<html><body><h1>Starting optimization loop...</h1><meta http-equiv='refresh' content='5'></body></html>")
|
||||
webbrowser.open(str(live_report_path))
|
||||
else:
|
||||
live_report_path = None
|
||||
|
||||
# Determine output directory (create before run_loop so logs can be written)
|
||||
if args.results_dir:
|
||||
timestamp = time.strftime("%Y-%m-%d_%H%M%S")
|
||||
results_dir = Path(args.results_dir) / timestamp
|
||||
results_dir.mkdir(parents=True, exist_ok=True)
|
||||
else:
|
||||
results_dir = None
|
||||
|
||||
log_dir = results_dir / "logs" if results_dir else None
|
||||
|
||||
output = run_loop(
|
||||
eval_set=eval_set,
|
||||
skill_path=skill_path,
|
||||
description_override=args.description,
|
||||
num_workers=args.num_workers,
|
||||
timeout=args.timeout,
|
||||
max_iterations=args.max_iterations,
|
||||
runs_per_query=args.runs_per_query,
|
||||
trigger_threshold=args.trigger_threshold,
|
||||
holdout=args.holdout,
|
||||
model=args.model,
|
||||
verbose=args.verbose,
|
||||
live_report_path=live_report_path,
|
||||
log_dir=log_dir,
|
||||
)
|
||||
|
||||
# Save JSON output
|
||||
json_output = json.dumps(output, indent=2)
|
||||
print(json_output)
|
||||
if results_dir:
|
||||
(results_dir / "results.json").write_text(json_output)
|
||||
|
||||
# Write final HTML report (without auto-refresh)
|
||||
if live_report_path:
|
||||
live_report_path.write_text(generate_html(output, auto_refresh=False, skill_name=name))
|
||||
print(f"\nReport: {live_report_path}", file=sys.stderr)
|
||||
|
||||
if results_dir and live_report_path:
|
||||
(results_dir / "report.html").write_text(generate_html(output, auto_refresh=False, skill_name=name))
|
||||
|
||||
if results_dir:
|
||||
print(f"Results saved to: {results_dir}", file=sys.stderr)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
47
deer-flow/skills/public/skill-creator/scripts/utils.py
Normal file
47
deer-flow/skills/public/skill-creator/scripts/utils.py
Normal file
@@ -0,0 +1,47 @@
|
||||
"""Shared utilities for skill-creator scripts."""
|
||||
|
||||
from pathlib import Path
|
||||
|
||||
|
||||
|
||||
def parse_skill_md(skill_path: Path) -> tuple[str, str, str]:
|
||||
"""Parse a SKILL.md file, returning (name, description, full_content)."""
|
||||
content = (skill_path / "SKILL.md").read_text()
|
||||
lines = content.split("\n")
|
||||
|
||||
if lines[0].strip() != "---":
|
||||
raise ValueError("SKILL.md missing frontmatter (no opening ---)")
|
||||
|
||||
end_idx = None
|
||||
for i, line in enumerate(lines[1:], start=1):
|
||||
if line.strip() == "---":
|
||||
end_idx = i
|
||||
break
|
||||
|
||||
if end_idx is None:
|
||||
raise ValueError("SKILL.md missing frontmatter (no closing ---)")
|
||||
|
||||
name = ""
|
||||
description = ""
|
||||
frontmatter_lines = lines[1:end_idx]
|
||||
i = 0
|
||||
while i < len(frontmatter_lines):
|
||||
line = frontmatter_lines[i]
|
||||
if line.startswith("name:"):
|
||||
name = line[len("name:"):].strip().strip('"').strip("'")
|
||||
elif line.startswith("description:"):
|
||||
value = line[len("description:"):].strip()
|
||||
# Handle YAML multiline indicators (>, |, >-, |-)
|
||||
if value in (">", "|", ">-", "|-"):
|
||||
continuation_lines: list[str] = []
|
||||
i += 1
|
||||
while i < len(frontmatter_lines) and (frontmatter_lines[i].startswith(" ") or frontmatter_lines[i].startswith("\t")):
|
||||
continuation_lines.append(frontmatter_lines[i].strip())
|
||||
i += 1
|
||||
description = " ".join(continuation_lines)
|
||||
continue
|
||||
else:
|
||||
description = value.strip('"').strip("'")
|
||||
i += 1
|
||||
|
||||
return name, description, content
|
||||
53
deer-flow/skills/public/surprise-me/SKILL.md
Normal file
53
deer-flow/skills/public/surprise-me/SKILL.md
Normal file
@@ -0,0 +1,53 @@
|
||||
---
|
||||
name: surprise-me
|
||||
description: Create a delightful, unexpected "wow" experience for the user by dynamically discovering and creatively combining other enabled skills. Triggers when the user says "surprise me" or any request expressing a desire for an unexpected creative showcase. Also triggers when the user is bored, wants inspiration, or asks for "something interesting".
|
||||
---
|
||||
|
||||
# Surprise Me
|
||||
|
||||
Deliver an unexpected, delightful experience by dynamically discovering available skills and combining them creatively.
|
||||
|
||||
## Workflow
|
||||
|
||||
### Step 1: Discover Available Skills
|
||||
|
||||
Read all the skills listed in the <available_skills>.
|
||||
|
||||
### Step 2: Plan the Surprise
|
||||
|
||||
Select **1 to 3** skills and design a creative mashup. The goal is a single cohesive deliverable, not separate demos.
|
||||
|
||||
**Creative combination principles:**
|
||||
- Juxtapose skills in unexpected ways (e.g., a presentation about algorithmic art, a research report turned into a slide deck, a styled doc with canvas-designed illustrations)
|
||||
- Incorporate the user's known interests/context from memory if available
|
||||
- Prioritize visual impact and emotional delight over information density
|
||||
- The output should feel like a gift — polished, surprising, and fun
|
||||
|
||||
**Theme ideas (pick or remix):**
|
||||
- Something tied to today's date, season, or trending news
|
||||
- A mini creative project the user never asked for but would love
|
||||
- A playful "what if" concept
|
||||
- An aesthetic artifact combining data + design
|
||||
- A fun interactive HTML/React experience
|
||||
|
||||
### Step 3: Fallback — No Other Skills Available
|
||||
|
||||
If no other skills are discovered (only surprise-me exists), use one of these fallbacks:
|
||||
|
||||
1. **News-based surprise**: Search today's news for a fascinating story, then create a beautifully designed HTML artifact presenting it in a visually striking way
|
||||
2. **Interactive HTML experience**: Build a creative single-page web experience — generative art, a mini-game, a visual poem, an animated infographic, or an interactive story
|
||||
3. **Personalized artifact**: Use known user context to create something personal and delightful
|
||||
|
||||
### Step 4: Execute
|
||||
|
||||
1. Read the full SKILL.md body of each selected skill
|
||||
2. Follow each skill's instructions for technical execution
|
||||
3. Combine outputs into one cohesive deliverable
|
||||
4. Present the result with minimal preamble — let the work speak for itself
|
||||
|
||||
### Step 5: Reveal
|
||||
|
||||
Present the surprise with minimal spoilers. A short teaser line, then the artifact.
|
||||
|
||||
- **Good reveal:** "I made you something ✨" + [the artifact]
|
||||
- **Bad reveal:** "I decided to combine the pptx skill with the canvas-design skill to create a presentation about..." (kills the surprise)
|
||||
235
deer-flow/skills/public/systematic-literature-review/SKILL.md
Normal file
235
deer-flow/skills/public/systematic-literature-review/SKILL.md
Normal file
@@ -0,0 +1,235 @@
|
||||
---
|
||||
name: systematic-literature-review
|
||||
description: Use this skill when the user wants a systematic literature review, survey, or synthesis across multiple academic papers on a topic. Also covers annotated bibliographies and cross-paper comparisons. Searches arXiv and outputs reports in APA, IEEE, or BibTeX format. Not for single-paper tasks — use academic-paper-review for reviewing one paper.
|
||||
---
|
||||
|
||||
# Systematic Literature Review Skill
|
||||
|
||||
## Overview
|
||||
|
||||
This skill produces a structured **systematic literature review (SLR)** across multiple academic papers on a research topic. Given a topic query, it searches arXiv, extracts structured metadata (research question, methodology, key findings, limitations) from each paper in parallel, synthesizes themes across the full set, and emits a final report with consistent citations.
|
||||
|
||||
**Distinct from `academic-paper-review`:** that skill does deep peer review of a single paper. This skill does breadth-first synthesis across many papers. If the user hands you one paper URL and asks "review this paper", route to `academic-paper-review` instead.
|
||||
|
||||
## When to Use This Skill
|
||||
|
||||
Use this skill when the user wants any of the following:
|
||||
|
||||
- A literature survey on a topic ("survey transformer attention variants", "review the literature on diffusion models")
|
||||
- A synthesis across multiple papers ("what do recent papers say about X", "compare methodologies across papers on Y")
|
||||
- A systematic review with consistent citation format ("do an SLR on Z in APA format")
|
||||
- An annotated bibliography on a topic
|
||||
- An overview of research trends in a field over a time window
|
||||
|
||||
Do **not** use this skill when:
|
||||
|
||||
- The user provides exactly one paper and asks to review it (use `academic-paper-review`)
|
||||
- The user asks a factual question that does not require synthesizing multiple sources (answer directly)
|
||||
- The user wants general web research without academic rigor (use standard web search)
|
||||
|
||||
## Workflow
|
||||
|
||||
The workflow has five phases. Follow them in order.
|
||||
|
||||
### Phase 1: Plan
|
||||
|
||||
Before doing any retrieval, confirm the following with the user. If any of these are unclear, ask **one** clarifying question that covers the missing pieces. Do not ask one question at a time.
|
||||
|
||||
- **Topic**: the research area in plain English (e.g. "transformer attention variants").
|
||||
- **Scope**: how many papers (default 20, hard upper bound 50), optional time window (e.g. "last 2 years"), optional arXiv category (e.g. `cs.CL`, `cs.CV`).
|
||||
- **Citation format**: APA, IEEE, or BibTeX (default APA if the user does not specify and does not seem to be writing for a specific venue).
|
||||
- **Output location**: where to save the final report (default `/mnt/user-data/outputs/`).
|
||||
|
||||
If the user says "50+ papers", politely cap it at 50 and explain that synthesis quality degrades quickly past that — for larger surveys they should split by sub-topic.
|
||||
|
||||
### Phase 2: Search arXiv
|
||||
|
||||
Call the bundled search script. Do **not** try to scrape arXiv by other means and do **not** write your own HTTP client — this script handles URL encoding, Atom XML parsing, and id normalization correctly.
|
||||
|
||||
```bash
|
||||
python /mnt/skills/public/systematic-literature-review/scripts/arxiv_search.py \
|
||||
"<topic>" \
|
||||
--max-results <N> \
|
||||
[--category <cat>] \
|
||||
[--sort-by relevance] \
|
||||
[--start-date YYYY-MM-DD] \
|
||||
[--end-date YYYY-MM-DD]
|
||||
```
|
||||
|
||||
**IMPORTANT — extract 2-3 core keywords before searching.** Do not pass the user's full topic description as the query. Before calling the script, mentally reduce the topic to its 2-3 most essential terms. Drop qualifiers like "in computer vision", "for NLP", "variants", "recent" — those belong in `--category` or `--start-date`, not in the query string.
|
||||
|
||||
**Query phrasing — keep it short.** The script wraps multi-word queries in double quotes for phrase matching on arXiv. This means:
|
||||
|
||||
- `"diffusion models"` → searches for the exact phrase → good, returns relevant papers.
|
||||
- `"diffusion models in computer vision"` → searches for that exact 5-word phrase → **too specific, likely returns 0 results** because few papers contain that exact string.
|
||||
|
||||
Use **2-3 core keywords** as the query, and use `--category` to narrow the field instead of stuffing field names into the query. Examples:
|
||||
|
||||
| User says | Good query | Bad query |
|
||||
|---|---|---|
|
||||
| "diffusion models in computer vision" | `"diffusion models" --category cs.CV` | `"diffusion models in computer vision"` |
|
||||
| "transformer attention variants" | `"transformer attention"` | `"transformer attention variants in NLP"` |
|
||||
| "graph neural networks for molecules" | `"graph neural networks" --category cs.LG` | `"graph neural networks for molecular property prediction"` |
|
||||
|
||||
The script prints a JSON array to stdout. Each paper has: `id`, `title`, `authors`, `abstract`, `published`, `updated`, `categories`, `pdf_url`, `abs_url`.
|
||||
|
||||
**Sort strategy**:
|
||||
|
||||
- **Always use `relevance` sorting** — arXiv's BM25-style scoring ensures results are actually about the user's topic. `submittedDate` sorting returns the most recently submitted papers in the category regardless of topic relevance, which produces mostly off-topic results.
|
||||
- When the user asks for "recent" papers or gives a time window, use `--sort-by relevance` **combined with `--start-date`** to constrain the time range while keeping results on-topic. For example, "recent diffusion model papers" → `--sort-by relevance --start-date 2024-01-01`, not `--sort-by submittedDate`.
|
||||
- `submittedDate` sorting is only appropriate when the user explicitly asks for chronological order (e.g. "show me papers in the order they were published"). This is rare.
|
||||
- `lastUpdatedDate` is rarely useful; ignore it unless the user asks.
|
||||
|
||||
**Run the search exactly once.** Do not retry with modified queries if the results seem imperfect — arXiv's relevance ranking is what it is. Retrying with different query phrasings wastes tool calls and risks hitting the recursion limit. If the results are genuinely empty (0 papers), tell the user and suggest they broaden their topic or remove the category filter.
|
||||
|
||||
**If the script returns fewer papers than requested**, that is the real size of the arXiv result set for the query. Do not pad the list — report the actual count to the user and proceed.
|
||||
|
||||
**If the script fails** (network error, non-200 from arXiv), tell the user which error and stop. Do not try to fabricate paper metadata.
|
||||
|
||||
**Do not save the search results to a file** — the JSON stays in your context for Phase 3. The only file saved during the entire workflow is the final report in Phase 5.
|
||||
|
||||
### Phase 3: Extract metadata in parallel
|
||||
|
||||
**You MUST delegate extraction to subagents via the `task` tool — do not extract metadata yourself.** This is non-negotiable. Specifically, do NOT do any of the following:
|
||||
|
||||
- ❌ Write `python -c "papers = [...]"` or any Python/bash script to process papers
|
||||
- ❌ Extract metadata inline in your own context by reading abstracts one by one
|
||||
- ❌ Use any tool other than `task` for this phase
|
||||
|
||||
Instead, you MUST call the `task` tool to spawn subagents. The reason: extracting 10-50 papers in your own context consumes too many tokens and degrades synthesis quality in Phase 4. Each subagent runs in an isolated context with only its batch of papers, producing cleaner extractions.
|
||||
|
||||
Split papers into batches of ~5, then for each batch, call the `task` tool with `subagent_type: "general-purpose"`. Each subagent receives the paper abstracts as text and returns structured JSON.
|
||||
|
||||
**Concurrency limit: at most 3 subagents per turn.** The DeerFlow runtime enforces `MAX_CONCURRENT_SUBAGENTS = 3` and will silently drop any extra dispatches in the same turn — the LLM will not be told this happened, so strictly follow the round strategy below.
|
||||
|
||||
**Round strategy — use this decision table, do not compute the split yourself**:
|
||||
|
||||
| Paper count | Batches of ~5 papers | Rounds | Per-round subagent count |
|
||||
|---|---|---|---|
|
||||
| 1–5 | 1 batch | 1 round | 1 subagent |
|
||||
| 6–10 | 2 batches | 1 round | 2 subagents |
|
||||
| 11–15 | 3 batches | 1 round | 3 subagents |
|
||||
| 16–20 | 4 batches | 2 rounds | 3 + 1 |
|
||||
| 21–25 | 5 batches | 2 rounds | 3 + 2 |
|
||||
| 26–30 | 6 batches | 2 rounds | 3 + 3 |
|
||||
| 31–35 | 7 batches | 3 rounds | 3 + 3 + 1 |
|
||||
| 36–40 | 8 batches | 3 rounds | 3 + 3 + 2 |
|
||||
| 41–45 | 9 batches | 3 rounds | 3 + 3 + 3 |
|
||||
| 46–50 | 10 batches | 4 rounds | 3 + 3 + 3 + 1 |
|
||||
|
||||
**Never dispatch more than 3 subagents in the same turn.** When a row says "2 rounds (3 + 1)", that means: first turn dispatches 3 subagents in parallel, wait for all 3 to complete, then second turn dispatches 1 subagent. Rounds are strictly sequential at the main-agent level.
|
||||
|
||||
If the paper count lands between rows (e.g. 23 papers), round up to the next row's layout but only dispatch as many batches as you actually need — the decision table gives you the shape, not a rigid prescription.
|
||||
|
||||
**Do the batching at the main-agent level**: you already have every paper's abstract from Phase 2, so each subagent receives pure text input. Subagents should not need to access the network or the sandbox — their only job is to read text and return JSON. Do not ask subagents to re-run `arxiv_search.py`; that would waste tokens and risk rate-limiting.
|
||||
|
||||
**What each subagent receives**, as a structured prompt:
|
||||
|
||||
```
|
||||
Execute this task: extract structured metadata and key findings from the
|
||||
following arXiv papers.
|
||||
|
||||
Papers:
|
||||
[Paper 1]
|
||||
arxiv_id: 1706.03762
|
||||
title: Attention Is All You Need
|
||||
authors: Ashish Vaswani, Noam Shazeer, ...
|
||||
published: 2017-06-12
|
||||
abstract: <full abstract text>
|
||||
|
||||
[Paper 2]
|
||||
arxiv_id: ...
|
||||
...
|
||||
|
||||
For each paper, return a JSON object with these fields:
|
||||
- arxiv_id (string)
|
||||
- title (string)
|
||||
- authors (list of strings)
|
||||
- published_date (string, YYYY-MM-DD)
|
||||
- research_question (1 sentence, what problem the paper tackles)
|
||||
- methodology (1-2 sentences, how they tackle it)
|
||||
- key_findings (3-5 bullet points, what they actually found)
|
||||
- limitations (1-2 sentences, what they acknowledge or what is obviously missing)
|
||||
|
||||
Return the result as a JSON array, one object per paper, in the same
|
||||
order as the input. Do not include any text outside the JSON — no
|
||||
preamble, no markdown fences, just the array.
|
||||
```
|
||||
|
||||
**Parsing subagent results**: the task tool returns strings with a fixed prefix like `Task Succeeded. Result: [...JSON...]`. Strip the `Task Succeeded. Result: ` prefix (or `Task failed.` / `Task timed out.` prefixes) before trying to parse JSON. If a batch fails or returns unparseable JSON, log it, note which papers were affected, and continue with the remaining batches — do not fail the whole synthesis on one bad batch.
|
||||
|
||||
After all rounds complete, flatten the per-batch arrays into a single list of paper metadata objects, preserving order.
|
||||
|
||||
### Phase 4: Synthesize and format
|
||||
|
||||
Now produce the final SLR report. Two things happen here: cross-paper synthesis (thematic analysis) and citation formatting.
|
||||
|
||||
**Cross-paper synthesis**: the report must do more than list papers. At minimum, identify:
|
||||
|
||||
- **Themes**: 3-6 recurring research directions, approaches, or problem framings across the set.
|
||||
- **Convergences**: findings that multiple papers agree on.
|
||||
- **Disagreements**: where papers reach different conclusions or use incompatible methodologies.
|
||||
- **Gaps**: what the collective literature does not yet address (often stated explicitly in the "limitations" fields).
|
||||
|
||||
If the paper set is too small or too heterogeneous to support thematic synthesis (e.g. 5 papers on wildly different sub-topics), say so explicitly in the report — do not force themes that are not there.
|
||||
|
||||
**Citation formatting**: the exact format depends on user preference. Read **only** the template file that matches the user's requested format, not all three:
|
||||
|
||||
- [templates/apa.md](templates/apa.md) — APA 7th edition. Default for social sciences and most CS journals. Use when the user requests APA or does not specify a format.
|
||||
- [templates/ieee.md](templates/ieee.md) — IEEE numeric citations. Use when the user targets an IEEE conference or journal, or explicitly asks for IEEE.
|
||||
- [templates/bibtex.md](templates/bibtex.md) — BibTeX entries. Use when the user mentions BibTeX, LaTeX, or wants machine-readable references. **Important**: arXiv papers are cited as `@misc`, not `@article` — the BibTeX template covers this explicitly.
|
||||
|
||||
Each template contains both the citation rules and a full report structure (executive summary, themes, per-paper annotations, references, methodology section). Follow the template's structure verbatim for the report body, then fill in content from your Phase 3 metadata.
|
||||
|
||||
### Phase 5: Save and present
|
||||
|
||||
Save the full report to `/mnt/user-data/outputs/slr-<topic-slug>-<YYYYMMDD>.md` where `<topic-slug>` is a lowercased hyphenated version of the topic (e.g. `transformer-attention`). Then call the `present_files` tool with that path so the user can download it.
|
||||
|
||||
**In the chat message**, show a short preview so the user immediately sees value without opening the file:
|
||||
|
||||
1. **Executive summary** — the 3–5 sentence paragraph from the top of the report, verbatim.
|
||||
2. **Themes list** — bullet list of the themes you identified in Phase 4 synthesis (just the theme names + one-line gloss, not the full theme sections).
|
||||
3. **Paper count + a pointer to the file** — e.g. "Full report with 20 papers, per-paper annotations, and formatted references saved to `slr-transformer-attention-20260409.md`."
|
||||
|
||||
Do **not** dump the full 2000+ word report inline — per-paper annotations, references, and methodology belong in the file. The preview is there to let the user judge the report at a glance and decide whether to open it.
|
||||
|
||||
## Examples
|
||||
|
||||
**Example 1: Typical SLR request**
|
||||
|
||||
User: "Do a systematic literature review of recent transformer attention variants, 20 papers, APA format."
|
||||
|
||||
Your flow:
|
||||
1. Phase 1: confirm topic (transformer attention variants), scope (20 papers, default time window), format (APA). Ask **one** clarification only if something is missing (e.g. "Any particular time window, or should I default to the last 3 years?").
|
||||
2. Phase 2: `arxiv_search.py "transformer attention" --max-results 20 --sort-by relevance --start-date 2023-01-01`.
|
||||
3. Phase 3: 20 papers → round 1 = 3 subagents × 5 papers = 15 covered, round 2 = 1 subagent × 5 papers = 5 covered. Aggregate.
|
||||
4. Phase 4: read `templates/apa.md`, write the report using its structure, fill in themes + per-paper annotations from Phase 3 metadata.
|
||||
5. Phase 5: save to `slr-transformer-attention-20260409.md`, call `present_files`.
|
||||
|
||||
**Example 2: Small-set request with ambiguity**
|
||||
|
||||
User: "Survey a few papers on diffusion models for me."
|
||||
|
||||
Your flow:
|
||||
1. Phase 1: "a few" is ambiguous. Ask one question: "How many papers would you like — 10, 20, or 30? And any citation format preference (APA is the default)?"
|
||||
2. User responds "10, BibTeX".
|
||||
3. Phase 2: `arxiv_search.py "diffusion models" --max-results 10 --category cs.CV`.
|
||||
4. Phase 3: 10 papers → single round, 2 subagents × 5 papers.
|
||||
5. Phase 4: read `templates/bibtex.md`, format with `@misc` entries (not `@article`).
|
||||
6. Phase 5: save and present.
|
||||
|
||||
**Example 3: Out-of-scope request**
|
||||
|
||||
User: "Here's one paper (https://arxiv.org/abs/1706.03762). Can you review it?"
|
||||
|
||||
This is a single-paper peer review, not a literature survey. Do not use this skill. Route to `academic-paper-review` instead.
|
||||
|
||||
## Notes
|
||||
|
||||
- **Prerequisite: `subagent_enabled` must be `true`**. Phase 3 requires the `task` tool for parallel metadata extraction. This tool is only loaded when `subagent_enabled` is set to `true` in the runtime config (`config.configurable.subagent_enabled`). Without it, the `task` tool will not appear in the available tools and Phase 3 cannot execute as designed.
|
||||
- **arXiv only, by design**. This skill does not query Semantic Scholar, PubMed, or Google Scholar. arXiv covers the bulk of CS/ML/physics/math preprints, which is what DeerFlow users most often want to survey. Multi-source academic search belongs in a dedicated MCP server, not inside this skill.
|
||||
- **Hard upper bound of 50 papers**. This is tied to the Phase 3 concurrency strategy (max 3 subagents per round, ~5 papers each, at most ~3 rounds). Surveys larger than 50 papers degrade in synthesis quality and are better done by splitting into sub-topics.
|
||||
- **Phase 3 requires subagents to be enabled**. This skill's parallel extraction step hard-requires the `task` tool, which is only available when `subagent_enabled=true` at runtime. If subagents are unavailable, do not claim to execute the Phase 3 parallel plan; instead, tell the user that subagents must be enabled for the full workflow, or offer to narrow/split the request into a smaller manual review.
|
||||
- **Subagent results are strings, not objects**. Always strip the `Task Succeeded. Result: ` / `Task failed.` / `Task timed out.` prefixes before parsing the JSON payload.
|
||||
- **The `id` field is a bare arXiv id** (e.g. `1706.03762`), not a URL and not with a version suffix. `abs_url` / `pdf_url` hold the full URLs if you need them.
|
||||
- **Synthesis, not listing**. The final report must identify themes and compare findings across papers. A report that only lists papers one after another is a failure mode — if you cannot find themes, say so explicitly instead of faking them.
|
||||
@@ -0,0 +1,79 @@
|
||||
{
|
||||
"skill_name": "systematic-literature-review",
|
||||
"evals": [
|
||||
{
|
||||
"id": 1,
|
||||
"prompt": "Do a systematic literature review on diffusion models in computer vision. 10 papers, last 2 years, category cs.CV, APA format. Save to default output location.",
|
||||
"expected_output": "A structured SLR report saved to /mnt/user-data/outputs/ with APA citations, thematic synthesis across 10 papers, and per-paper annotations.",
|
||||
"expectations": [
|
||||
"The skill read SKILL.md for systematic-literature-review",
|
||||
"The arxiv_search.py script was called with a short keyword query (2-3 words), not the full topic description",
|
||||
"The search used --category cs.CV",
|
||||
"The search used --sort-by relevance, not submittedDate",
|
||||
"The search was executed only once without retries",
|
||||
"Metadata extraction was delegated via the task tool to subagents, not done inline or via python -c",
|
||||
"The APA template file (templates/apa.md) was read",
|
||||
"The final report was saved to /mnt/user-data/outputs/ with a filename matching slr-<topic-slug>-<YYYYMMDD>.md",
|
||||
"The present_files tool was called to make the report visible to the user",
|
||||
"The report contains an Executive Summary section",
|
||||
"The report identifies at least 3 themes with cross-paper analysis",
|
||||
"The report contains a Convergences and Disagreements section",
|
||||
"The report contains a Gaps and Open Questions section",
|
||||
"The report contains per-paper annotations for each of the 10 papers",
|
||||
"The references section uses APA 7th format with arXiv URLs"
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": 2,
|
||||
"prompt": "Survey recent papers on graph neural networks for drug discovery. 5 papers, BibTeX format.",
|
||||
"expected_output": "A structured SLR report with BibTeX citations using @misc entries for arXiv preprints.",
|
||||
"expectations": [
|
||||
"The skill read SKILL.md for systematic-literature-review",
|
||||
"The arxiv_search.py script was called with a short keyword query",
|
||||
"Metadata extraction was delegated via the task tool to subagents",
|
||||
"The BibTeX template file (templates/bibtex.md) was read, not apa.md or ieee.md",
|
||||
"The final report was saved to /mnt/user-data/outputs/",
|
||||
"The present_files tool was called",
|
||||
"The report contains BibTeX entries using @misc, not @article",
|
||||
"Each BibTeX entry includes eprint and primaryClass fields",
|
||||
"The report contains thematic synthesis, not just a list of papers"
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": 3,
|
||||
"prompt": "Review the literature on retrieval-augmented generation — key findings, limitations, and open questions. 15 papers, IEEE format.",
|
||||
"expected_output": "A structured SLR report with IEEE numeric citations and 15 papers extracted in parallel batches.",
|
||||
"expectations": [
|
||||
"The skill read SKILL.md for systematic-literature-review",
|
||||
"The arxiv_search.py script was called with --max-results 15 or higher",
|
||||
"Metadata extraction used the task tool with multiple subagent batches (15 papers requires 3 batches of 5)",
|
||||
"The IEEE template file (templates/ieee.md) was read",
|
||||
"The report uses IEEE numeric citations [1], [2], etc. in the text",
|
||||
"The references section uses IEEE format with numbered entries",
|
||||
"The report contains per-paper annotations for all papers",
|
||||
"The report identifies themes across the papers"
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": 4,
|
||||
"prompt": "Review this paper: https://arxiv.org/abs/2310.06825",
|
||||
"expected_output": "The SLR skill should NOT be triggered. The request should route to academic-paper-review instead.",
|
||||
"expectations": [
|
||||
"The systematic-literature-review skill was NOT triggered",
|
||||
"The agent did not call arxiv_search.py",
|
||||
"The agent recognized this as a single-paper review request"
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": 5,
|
||||
"prompt": "What does the literature say about RLHF?",
|
||||
"expected_output": "The SLR skill should be triggered despite no explicit 'systematic' or 'survey' keyword, because 'the literature' implies multi-paper synthesis.",
|
||||
"expectations": [
|
||||
"The skill read SKILL.md for systematic-literature-review",
|
||||
"The arxiv_search.py script was called",
|
||||
"The agent asked a clarification question about scope (paper count, format) or used reasonable defaults",
|
||||
"The final output is a multi-paper synthesis, not a single factual answer"
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,102 @@
|
||||
[
|
||||
{
|
||||
"query": "Survey transformer attention variants published in the last 2 years on arXiv cs.CL",
|
||||
"should_trigger": true,
|
||||
"rationale": "Explicit survey request with scope and category"
|
||||
},
|
||||
{
|
||||
"query": "What methods do recent papers use for few-shot learning in vision-and-language? Give me 15 papers in BibTeX.",
|
||||
"should_trigger": true,
|
||||
"rationale": "Multi-paper synthesis with count and format spec"
|
||||
},
|
||||
{
|
||||
"query": "Review the literature on retrieval-augmented generation — key findings, limitations, and open questions",
|
||||
"should_trigger": true,
|
||||
"rationale": "Classic SLR phrasing with explicit synthesis structure"
|
||||
},
|
||||
{
|
||||
"query": "Compare evaluation frameworks used across LLM hallucination detection papers",
|
||||
"should_trigger": true,
|
||||
"rationale": "Cross-paper comparison implies multi-paper synthesis"
|
||||
},
|
||||
{
|
||||
"query": "Summarize recent work on Monte Carlo methods for mortgage risk — last 3 years",
|
||||
"should_trigger": true,
|
||||
"rationale": "Domain-specific SLR with time window"
|
||||
},
|
||||
{
|
||||
"query": "Annotated bibliography on agentic tool use, 20 papers, IEEE format",
|
||||
"should_trigger": true,
|
||||
"rationale": "Annotated bibliography is an SLR variant"
|
||||
},
|
||||
{
|
||||
"query": "What does the literature say about RLHF?",
|
||||
"should_trigger": true,
|
||||
"rationale": "No 'systematic' keyword but 'the literature' clearly implies multi-paper synthesis"
|
||||
},
|
||||
{
|
||||
"query": "Give me an overview of diffusion model papers since 2022",
|
||||
"should_trigger": true,
|
||||
"rationale": "Time range + 'papers' implies breadth-first survey"
|
||||
},
|
||||
{
|
||||
"query": "Are there papers comparing RAG and fine-tuning?",
|
||||
"should_trigger": true,
|
||||
"rationale": "Comparison query across papers implies synthesis"
|
||||
},
|
||||
{
|
||||
"query": "Do a systematic literature review on graph neural networks for drug discovery, APA format",
|
||||
"should_trigger": true,
|
||||
"rationale": "Explicit SLR request with format"
|
||||
},
|
||||
{
|
||||
"query": "Review this paper: https://arxiv.org/abs/2310.06825",
|
||||
"should_trigger": false,
|
||||
"rationale": "Single paper URL -> should route to academic-paper-review"
|
||||
},
|
||||
{
|
||||
"query": "What is attention in transformers?",
|
||||
"should_trigger": false,
|
||||
"rationale": "Factual question, no multi-paper synthesis needed"
|
||||
},
|
||||
{
|
||||
"query": "Search for news about AI regulation",
|
||||
"should_trigger": false,
|
||||
"rationale": "General web search, not academic literature review"
|
||||
},
|
||||
{
|
||||
"query": "Summarize this PDF [attached]",
|
||||
"should_trigger": false,
|
||||
"rationale": "Single document summary, not literature review"
|
||||
},
|
||||
{
|
||||
"query": "Write me a Python function to parse BibTeX files",
|
||||
"should_trigger": false,
|
||||
"rationale": "Coding task, not research"
|
||||
},
|
||||
{
|
||||
"query": "What is the capital of France?",
|
||||
"should_trigger": false,
|
||||
"rationale": "Factual question, no research needed"
|
||||
},
|
||||
{
|
||||
"query": "Help me debug this error in my React app",
|
||||
"should_trigger": false,
|
||||
"rationale": "Debugging task, not literature review"
|
||||
},
|
||||
{
|
||||
"query": "Translate this paragraph to Chinese",
|
||||
"should_trigger": false,
|
||||
"rationale": "Translation task"
|
||||
},
|
||||
{
|
||||
"query": "Explain the difference between CNN and RNN",
|
||||
"should_trigger": false,
|
||||
"rationale": "Conceptual explanation, not multi-paper synthesis"
|
||||
},
|
||||
{
|
||||
"query": "Find me the best paper on reinforcement learning",
|
||||
"should_trigger": false,
|
||||
"rationale": "Singular 'best paper' implies one result, not a survey across many"
|
||||
}
|
||||
]
|
||||
@@ -0,0 +1,306 @@
|
||||
#!/usr/bin/env python3
|
||||
"""arXiv search client for the systematic-literature-review skill.
|
||||
|
||||
Queries the public arXiv API (http://export.arxiv.org/api/query) and
|
||||
returns structured paper metadata as JSON. No API key required.
|
||||
|
||||
Design notes:
|
||||
|
||||
- No additional dependencies required. Uses `requests` when available,
|
||||
falls back to `urllib` with a requests-compatible shim (same pattern as
|
||||
../../github-deep-research/scripts/github_api.py).
|
||||
- Query parameters are URL-encoded via `urllib.parse.urlencode` with
|
||||
`quote_via=quote_plus`. Hand-rolled `k=v` joining would break on
|
||||
multi-word topics like "transformer attention".
|
||||
- Atom XML is parsed with `xml.etree.ElementTree` using an explicit
|
||||
namespace map. Forgetting the namespace prefix is the #1 arXiv API
|
||||
parsing bug, so we bake it into NS_MAP.
|
||||
- The `<id>` field in arXiv responses is a full URL like
|
||||
"http://arxiv.org/abs/1706.03762v5". Callers usually want the bare
|
||||
id "1706.03762", so we normalise it.
|
||||
- max_results is clamped to 50 to match the skill's documented upper
|
||||
bound. Larger surveys are out of scope for the MVP.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import argparse
|
||||
import json
|
||||
import sys
|
||||
from typing import Any
|
||||
|
||||
# Namespace map for arXiv's Atom feed. arXiv extends Atom with its own
|
||||
# elements (primary_category, comment, journal_ref) under the `arxiv:`
|
||||
# prefix; the core entry fields live under `atom:`.
|
||||
NS_MAP = {
|
||||
"atom": "http://www.w3.org/2005/Atom",
|
||||
"arxiv": "http://arxiv.org/schemas/atom",
|
||||
}
|
||||
|
||||
ARXIV_ENDPOINT = "http://export.arxiv.org/api/query"
|
||||
MAX_RESULTS_UPPER_BOUND = 50
|
||||
DEFAULT_TIMEOUT_SECONDS = 30
|
||||
|
||||
|
||||
# --- HTTP client with requests -> urllib fallback --------------------------
|
||||
|
||||
try:
|
||||
import requests # type: ignore
|
||||
except ImportError:
|
||||
import urllib.error
|
||||
import urllib.parse
|
||||
import urllib.request
|
||||
|
||||
class _UrllibResponse:
|
||||
def __init__(self, data: bytes, status: int) -> None:
|
||||
self._data = data
|
||||
self.status_code = status
|
||||
self.text = data.decode("utf-8", errors="replace")
|
||||
self.content = data
|
||||
|
||||
def raise_for_status(self) -> None:
|
||||
if self.status_code >= 400:
|
||||
raise RuntimeError(f"HTTP {self.status_code}")
|
||||
|
||||
class _UrllibRequestsShim:
|
||||
"""Minimal requests-compatible shim using urllib.
|
||||
|
||||
Only supports what arxiv_search needs: GET with query params.
|
||||
Params are encoded with quote_plus so multi-word queries work.
|
||||
"""
|
||||
|
||||
@staticmethod
|
||||
def get(
|
||||
url: str,
|
||||
params: dict | None = None,
|
||||
timeout: int = DEFAULT_TIMEOUT_SECONDS,
|
||||
) -> _UrllibResponse:
|
||||
if params:
|
||||
query = urllib.parse.urlencode(params, quote_via=urllib.parse.quote_plus)
|
||||
url = f"{url}?{query}"
|
||||
req = urllib.request.Request(url, headers={"User-Agent": "deerflow-slr-skill/0.1"})
|
||||
try:
|
||||
with urllib.request.urlopen(req, timeout=timeout) as resp:
|
||||
return _UrllibResponse(resp.read(), resp.status)
|
||||
except urllib.error.HTTPError as e:
|
||||
return _UrllibResponse(e.read(), e.code)
|
||||
|
||||
requests = _UrllibRequestsShim() # type: ignore
|
||||
|
||||
|
||||
# --- Core query + parsing --------------------------------------------------
|
||||
|
||||
|
||||
def _build_search_query(
|
||||
query: str,
|
||||
category: str | None,
|
||||
start_date: str | None,
|
||||
end_date: str | None,
|
||||
) -> str:
|
||||
"""Build arXiv's `search_query` field.
|
||||
|
||||
arXiv uses its own query grammar: `ti:`, `abs:`, `cat:`, `all:`, with
|
||||
`AND`/`OR`/`ANDNOT` combinators. We search `all:` for the user's
|
||||
topic (matches title + abstract + authors) and optionally AND it
|
||||
with a category filter and a submission date range.
|
||||
"""
|
||||
# Wrap multi-word queries in double quotes so arXiv's Lucene parser
|
||||
# treats them as a phrase. Without quotes, `all:diffusion model` is
|
||||
# parsed as `all:diffusion OR model`, pulling in unrelated papers
|
||||
# that merely mention the word "model".
|
||||
if " " in query:
|
||||
parts = [f'all:"{query}"']
|
||||
else:
|
||||
parts = [f"all:{query}"]
|
||||
if category:
|
||||
parts.append(f"cat:{category}")
|
||||
if start_date or end_date:
|
||||
# arXiv date range format: [YYYYMMDDHHMM TO YYYYMMDDHHMM]
|
||||
lo = (start_date or "19910101").replace("-", "") + "0000"
|
||||
hi = (end_date or "29991231").replace("-", "") + "2359"
|
||||
parts.append(f"submittedDate:[{lo} TO {hi}]")
|
||||
return " AND ".join(parts)
|
||||
|
||||
|
||||
def _normalise_arxiv_id(raw_id: str) -> str:
|
||||
"""Convert a full arXiv URL to a bare id.
|
||||
|
||||
Handles both modern and legacy arXiv ID formats:
|
||||
- Modern: "http://arxiv.org/abs/1706.03762v5" -> "1706.03762"
|
||||
- Legacy: "http://arxiv.org/abs/hep-th/9901001v1" -> "hep-th/9901001"
|
||||
"""
|
||||
# Extract everything after /abs/ to preserve legacy archive prefix
|
||||
if "/abs/" in raw_id:
|
||||
tail = raw_id.split("/abs/", 1)[1]
|
||||
else:
|
||||
tail = raw_id.rsplit("/", 1)[-1]
|
||||
# Strip version suffix: "1706.03762v5" -> "1706.03762"
|
||||
if "v" in tail:
|
||||
base, _, suffix = tail.rpartition("v")
|
||||
if suffix.isdigit():
|
||||
return base
|
||||
return tail
|
||||
|
||||
|
||||
def _parse_entry(entry: Any) -> dict:
|
||||
"""Turn one Atom <entry> element into a paper dict."""
|
||||
import xml.etree.ElementTree as ET
|
||||
|
||||
def _text(path: str) -> str:
|
||||
node = entry.find(path, NS_MAP)
|
||||
return (node.text or "").strip() if node is not None and node.text else ""
|
||||
|
||||
raw_id = _text("atom:id")
|
||||
arxiv_id = _normalise_arxiv_id(raw_id)
|
||||
|
||||
authors = [(a.findtext("atom:name", default="", namespaces=NS_MAP) or "").strip() for a in entry.findall("atom:author", NS_MAP)]
|
||||
authors = [a for a in authors if a]
|
||||
|
||||
categories = [c.get("term", "") for c in entry.findall("atom:category", NS_MAP) if c.get("term")]
|
||||
|
||||
pdf_url = ""
|
||||
abs_url = raw_id # default
|
||||
for link in entry.findall("atom:link", NS_MAP):
|
||||
if link.get("title") == "pdf":
|
||||
pdf_url = link.get("href", "")
|
||||
elif link.get("rel") == "alternate":
|
||||
abs_url = link.get("href", abs_url)
|
||||
|
||||
# Dates come as ISO 8601 (2017-06-12T17:57:34Z). Keep the date part.
|
||||
published_raw = _text("atom:published")
|
||||
updated_raw = _text("atom:updated")
|
||||
published = published_raw.split("T", 1)[0] if published_raw else ""
|
||||
updated = updated_raw.split("T", 1)[0] if updated_raw else ""
|
||||
|
||||
# Abstract (<summary>) has ragged whitespace from arXiv's formatting.
|
||||
# Collapse internal whitespace to make downstream LLM consumption easier.
|
||||
abstract = " ".join(_text("atom:summary").split())
|
||||
|
||||
# Silence unused import warning; ET is only needed for type hints above.
|
||||
del ET
|
||||
|
||||
return {
|
||||
"id": arxiv_id,
|
||||
"title": " ".join(_text("atom:title").split()),
|
||||
"authors": authors,
|
||||
"abstract": abstract,
|
||||
"published": published,
|
||||
"updated": updated,
|
||||
"categories": categories,
|
||||
"pdf_url": pdf_url,
|
||||
"abs_url": abs_url,
|
||||
}
|
||||
|
||||
|
||||
def search(
|
||||
query: str,
|
||||
max_results: int = 20,
|
||||
category: str | None = None,
|
||||
sort_by: str = "relevance",
|
||||
start_date: str | None = None,
|
||||
end_date: str | None = None,
|
||||
) -> list[dict]:
|
||||
"""Query arXiv and return a list of paper dicts.
|
||||
|
||||
Args:
|
||||
query: free-text topic, e.g. "transformer attention".
|
||||
max_results: number of papers to return (clamped to 50).
|
||||
category: optional arXiv category, e.g. "cs.CL".
|
||||
sort_by: "relevance", "submittedDate", or "lastUpdatedDate".
|
||||
start_date: YYYY-MM-DD or YYYYMMDD, inclusive.
|
||||
end_date: YYYY-MM-DD or YYYYMMDD, inclusive.
|
||||
|
||||
Returns:
|
||||
list of dicts, each matching the schema documented in SKILL.md.
|
||||
"""
|
||||
import xml.etree.ElementTree as ET
|
||||
|
||||
if max_results <= 0:
|
||||
return []
|
||||
max_results = min(max_results, MAX_RESULTS_UPPER_BOUND)
|
||||
|
||||
search_query = _build_search_query(query, category, start_date, end_date)
|
||||
params = {
|
||||
"search_query": search_query,
|
||||
"start": 0,
|
||||
"max_results": max_results,
|
||||
"sortBy": sort_by,
|
||||
"sortOrder": "descending",
|
||||
}
|
||||
|
||||
resp = requests.get(ARXIV_ENDPOINT, params=params, timeout=DEFAULT_TIMEOUT_SECONDS)
|
||||
resp.raise_for_status()
|
||||
|
||||
# arXiv returns Atom XML, not JSON.
|
||||
root = ET.fromstring(resp.text)
|
||||
entries = root.findall("atom:entry", NS_MAP)
|
||||
return [_parse_entry(e) for e in entries]
|
||||
|
||||
|
||||
# --- CLI -------------------------------------------------------------------
|
||||
|
||||
|
||||
def _build_parser() -> argparse.ArgumentParser:
|
||||
parser = argparse.ArgumentParser(
|
||||
description="Query the arXiv API and emit structured paper metadata as JSON.",
|
||||
formatter_class=argparse.RawDescriptionHelpFormatter,
|
||||
epilog=(
|
||||
"Examples:\n"
|
||||
' python arxiv_search.py "transformer attention" --max-results 10\n'
|
||||
' python arxiv_search.py "diffusion models" --category cs.CV --sort-by submittedDate\n'
|
||||
' python arxiv_search.py "graph neural networks" --start-date 2023-01-01\n'
|
||||
),
|
||||
)
|
||||
parser.add_argument("query", help="free-text search topic")
|
||||
parser.add_argument(
|
||||
"--max-results",
|
||||
type=int,
|
||||
default=20,
|
||||
help=f"number of papers to return (default: 20, max: {MAX_RESULTS_UPPER_BOUND})",
|
||||
)
|
||||
parser.add_argument(
|
||||
"--category",
|
||||
default=None,
|
||||
help="optional arXiv category filter, e.g. cs.CL, cs.CV, stat.ML",
|
||||
)
|
||||
parser.add_argument(
|
||||
"--sort-by",
|
||||
default="relevance",
|
||||
choices=["relevance", "submittedDate", "lastUpdatedDate"],
|
||||
help="sort order (default: relevance)",
|
||||
)
|
||||
parser.add_argument(
|
||||
"--start-date",
|
||||
default=None,
|
||||
help="earliest submission date, YYYY-MM-DD (inclusive)",
|
||||
)
|
||||
parser.add_argument(
|
||||
"--end-date",
|
||||
default=None,
|
||||
help="latest submission date, YYYY-MM-DD (inclusive)",
|
||||
)
|
||||
return parser
|
||||
|
||||
|
||||
def main() -> int:
|
||||
args = _build_parser().parse_args()
|
||||
try:
|
||||
papers = search(
|
||||
query=args.query,
|
||||
max_results=args.max_results,
|
||||
category=args.category,
|
||||
sort_by=args.sort_by,
|
||||
start_date=args.start_date,
|
||||
end_date=args.end_date,
|
||||
)
|
||||
except Exception as exc:
|
||||
print(f"arxiv_search.py: {exc}", file=sys.stderr)
|
||||
return 1
|
||||
|
||||
json.dump(papers, sys.stdout, ensure_ascii=False, indent=2)
|
||||
sys.stdout.write("\n")
|
||||
return 0
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
sys.exit(main())
|
||||
@@ -0,0 +1,125 @@
|
||||
# APA 7th Edition Citation Template
|
||||
|
||||
Use this template when the user requests APA format, or when they do not specify a format. APA 7th is the default for social sciences and most CS journals outside of IEEE venues.
|
||||
|
||||
## Citation Format Rules
|
||||
|
||||
### In-text citations
|
||||
|
||||
- **Single author**: `(Vaswani, 2017)` or `Vaswani (2017) showed that...`
|
||||
- **Two authors**: `(Vaswani & Shazeer, 2017)` — use `&` inside parentheses, "and" in running text.
|
||||
- **Three or more authors**: `(Vaswani et al., 2017)` — use `et al.` from the first citation onward (APA 7th changed this from APA 6th).
|
||||
- **Multiple citations**: `(Vaswani et al., 2017; Devlin et al., 2018)` — alphabetical order, separated by semicolons.
|
||||
|
||||
### Reference list entry for arXiv preprints
|
||||
|
||||
arXiv papers are preprints, not formally published articles. Cite them as preprints with the arXiv identifier:
|
||||
|
||||
```
|
||||
Author, A. A., Author, B. B., & Author, C. C. (Year). Title of the paper. arXiv. https://arxiv.org/abs/ARXIV_ID
|
||||
```
|
||||
|
||||
**Real example** (from paper metadata `{id: "1706.03762", title: "Attention Is All You Need", authors: ["Ashish Vaswani", "Noam Shazeer", "Niki Parmar", "Jakob Uszkoreit", "Llion Jones", "Aidan N. Gomez", "Łukasz Kaiser", "Illia Polosukhin"], published: "2017-06-12"}`):
|
||||
|
||||
```
|
||||
Vaswani, A., Shazeer, N., Parmar, N., Uszkoreit, J., Jones, L., Gomez, A. N., Kaiser, Ł., & Polosukhin, I. (2017). Attention is all you need. arXiv. https://arxiv.org/abs/1706.03762
|
||||
```
|
||||
|
||||
Formatting rules:
|
||||
|
||||
- **Author names**: `LastName, FirstInitial.` (middle initial optional). Join with commas; last author gets an `&`.
|
||||
- **Year**: the `published` field's year, in parentheses.
|
||||
- **Title**: sentence case (only first word and proper nouns capitalized). Italicize titles in typeset output; in plain markdown, leave plain.
|
||||
- **Source**: the literal word `arXiv`, then the full abs URL.
|
||||
- **No DOI** unless the paper has also been published in a venue with a DOI. arXiv alone uses the URL.
|
||||
|
||||
### Special cases
|
||||
|
||||
- **Up to 20 authors**: list all of them separated by commas, with `&` before the last.
|
||||
- **21 or more authors**: list the first 19, then `...`, then the final author.
|
||||
- **No DOI and no URL**: not possible for arXiv papers; always use the `abs_url` from the paper metadata.
|
||||
|
||||
## Report Structure
|
||||
|
||||
Follow this structure verbatim when writing the SLR report body. Fill in content from your Phase 3 extraction and Phase 4 synthesis.
|
||||
|
||||
```markdown
|
||||
# Systematic Literature Review: <Topic>
|
||||
|
||||
**Date**: <YYYY-MM-DD>
|
||||
**Papers surveyed**: <N>
|
||||
**Scope**: <arXiv search query, category, time window>
|
||||
**Citation format**: APA 7th edition
|
||||
|
||||
## Executive Summary
|
||||
|
||||
<3-5 sentences summarizing the state of the literature on this topic. What do the surveyed papers collectively tell us? What is the shape of the field? Avoid listing papers — synthesize.>
|
||||
|
||||
## Methodology
|
||||
|
||||
This review surveyed <N> arXiv papers retrieved on <YYYY-MM-DD> using the query `<query>`<, filtered to category <cat>><, published between <start_date> and <end_date>>. Papers were sorted by <relevance | submission date> and the top <N> were included. Metadata extraction (research question, methodology, key findings, limitations) was performed by language-model agents, with cross-paper synthesis performed by the lead agent.
|
||||
|
||||
**Limitations of this review**: arXiv preprints are not peer-reviewed; some included papers may not reflect their final published form. Coverage is limited to arXiv — papers published directly in venues without arXiv preprints are not represented.
|
||||
|
||||
## Themes
|
||||
|
||||
<3-6 thematic sections. Each theme is a recurring research direction, problem framing, or methodological approach across the surveyed papers.>
|
||||
|
||||
### Theme 1: <Theme name>
|
||||
|
||||
<2-4 paragraphs describing this theme. Cite papers inline as you discuss them, e.g. "Vaswani et al. (2017) introduced X, while subsequent work (Devlin et al., 2018; Liu et al., 2019) extended it to Y." Do not just list papers — describe the intellectual thread that connects them.>
|
||||
|
||||
### Theme 2: <Theme name>
|
||||
|
||||
<...>
|
||||
|
||||
## Convergences and Disagreements
|
||||
|
||||
**Convergences**: <findings that multiple papers agree on — e.g. "Most surveyed papers agree that X is necessary, citing evidence from Y and Z.">
|
||||
|
||||
**Disagreements**: <where papers reach different conclusions — e.g. "Vaswani et al. (2017) argue that X, while Dai et al. (2019) find the opposite under condition Y.">
|
||||
|
||||
## Gaps and Open Questions
|
||||
|
||||
<What the collective literature does not yet address. Pull from the "limitations" field of your Phase 3 extraction and identify patterns — if 5 papers all mention the same missing piece, that is a gap worth flagging.>
|
||||
|
||||
## Per-Paper Annotations
|
||||
|
||||
<One subsection per paper, ordered by year then first author. Each subsection is a mini-summary of that paper's contribution.>
|
||||
|
||||
### Vaswani et al. (2017)
|
||||
|
||||
**Research question**: <1 sentence from Phase 3 metadata>
|
||||
**Methodology**: <1-2 sentences>
|
||||
**Key findings**:
|
||||
- <bullet>
|
||||
- <bullet>
|
||||
- <bullet>
|
||||
**Limitations**: <1-2 sentences>
|
||||
|
||||
### <Next paper>
|
||||
|
||||
<...>
|
||||
|
||||
## References
|
||||
|
||||
<Alphabetical list by first author's last name, APA 7th format as described above.>
|
||||
|
||||
Devlin, J., Chang, M.-W., Lee, K., & Toutanova, K. (2018). BERT: Pre-training of deep bidirectional transformers for language understanding. arXiv. https://arxiv.org/abs/1810.04805
|
||||
|
||||
Vaswani, A., Shazeer, N., Parmar, N., Uszkoreit, J., Jones, L., Gomez, A. N., Kaiser, Ł., & Polosukhin, I. (2017). Attention is all you need. arXiv. https://arxiv.org/abs/1706.03762
|
||||
|
||||
<... more entries, one per paper ...>
|
||||
```
|
||||
|
||||
## Quality checks before finalizing
|
||||
|
||||
Before saving the report, verify:
|
||||
|
||||
- [ ] Every paper in the surveyed set appears **both** in "Per-Paper Annotations" **and** in "References".
|
||||
- [ ] Every in-text citation matches a reference entry (no dangling citations).
|
||||
- [ ] Authors are formatted `LastName, FirstInitial.` — not `FirstName LastName`.
|
||||
- [ ] Years are in parentheses inline, and at the start of reference entries.
|
||||
- [ ] Titles are in sentence case in references (only first word + proper nouns capitalized).
|
||||
- [ ] arXiv URLs use the `abs_url` form (`https://arxiv.org/abs/...`), not `pdf_url`.
|
||||
- [ ] References are alphabetized by first author's last name.
|
||||
@@ -0,0 +1,156 @@
|
||||
# BibTeX Citation Template
|
||||
|
||||
Use this template when the user mentions BibTeX, LaTeX, wants machine-readable references, or is writing a paper that will be typeset with a LaTeX citation style (natbib, biblatex, etc.).
|
||||
|
||||
## Critical: use `@misc`, not `@article`, for arXiv papers
|
||||
|
||||
**arXiv preprints must be cited as `@misc`, not `@article`.** This is the most common mistake when generating BibTeX for arXiv papers, and it matters:
|
||||
|
||||
- `@article` requires a `journal` field. arXiv is not a journal — it is a preprint server. Using `@article` with `journal = {arXiv}` is technically wrong and some bibliography styles will complain or render it inconsistently.
|
||||
- `@misc` is the correct entry type for preprints, technical reports, and other non-journal publications. It accepts `howpublished` and `eprint` fields, which is exactly what arXiv citations need.
|
||||
- Only switch to `@article` (or `@inproceedings`) when the paper has been **formally published** in a peer-reviewed venue and you have the venue metadata. In this workflow we only have arXiv metadata, so always emit `@misc`.
|
||||
|
||||
## Citation Format Rules
|
||||
|
||||
### Entry structure for arXiv preprints
|
||||
|
||||
```bibtex
|
||||
@misc{citekey,
|
||||
author = {LastName1, FirstName1 and LastName2, FirstName2 and ...},
|
||||
title = {Title of the Paper},
|
||||
year = {YYYY},
|
||||
eprint = {ARXIV_ID},
|
||||
archivePrefix = {arXiv},
|
||||
primaryClass = {PRIMARY_CATEGORY},
|
||||
url = {https://arxiv.org/abs/ARXIV_ID}
|
||||
}
|
||||
```
|
||||
|
||||
**Real example**:
|
||||
|
||||
```bibtex
|
||||
@misc{vaswani2017attention,
|
||||
author = {Vaswani, Ashish and Shazeer, Noam and Parmar, Niki and Uszkoreit, Jakob and Jones, Llion and Gomez, Aidan N. and Kaiser, {\L}ukasz and Polosukhin, Illia},
|
||||
title = {Attention Is All You Need},
|
||||
year = {2017},
|
||||
eprint = {1706.03762},
|
||||
archivePrefix = {arXiv},
|
||||
primaryClass = {cs.CL},
|
||||
url = {https://arxiv.org/abs/1706.03762}
|
||||
}
|
||||
```
|
||||
|
||||
### Field rules
|
||||
|
||||
- **Cite key**: `<firstauthorlast><year><firstwordoftitle>`, all lowercase, no punctuation. Example: `vaswani2017attention`. Keys must be unique within the report.
|
||||
- **`author`**: `LastName, FirstName and LastName, FirstName and ...` — note the literal word `and` between authors, not a comma. LaTeX requires this exact separator. LastName comes first, then a comma, then the given names.
|
||||
- **Special characters**: escape or wrap LaTeX-sensitive characters. For example, `Łukasz` becomes `{\L}ukasz`, `é` becomes `{\'e}` (or wrap the whole name in braces to preserve casing: `{Łukasz}`). If unsure, wrap the problematic name in curly braces.
|
||||
- **`title`**: preserve the paper's capitalization by wrapping it in double braces if it contains acronyms or proper nouns you need to keep capitalized: `title = {{BERT}: Pre-training of Deep Bidirectional Transformers}`. Otherwise plain braces are fine.
|
||||
- **`year`**: the 4-digit year from the paper's `published` field.
|
||||
- **`eprint`**: the **bare arXiv id** (e.g. `1706.03762`), **without** the `arXiv:` prefix and **without** the version suffix.
|
||||
- **`archivePrefix`**: literal string `{arXiv}`.
|
||||
- **`primaryClass`**: the first category from the paper's `categories` list (e.g. `cs.CL`, `cs.CV`, `stat.ML`). This is the paper's primary subject area.
|
||||
- **`url`**: the full `abs_url` from paper metadata.
|
||||
|
||||
## Report Structure
|
||||
|
||||
The BibTeX report is slightly different from APA / IEEE: the **bibliography is a separate `.bib` file**, and the main report uses LaTeX-style `\cite{key}` references that would resolve against that file. Since we are emitting markdown, we show `\cite{key}` verbatim in the prose and emit the BibTeX entries inside a fenced code block at the end.
|
||||
|
||||
```markdown
|
||||
# Systematic Literature Review: <Topic>
|
||||
|
||||
**Date**: <YYYY-MM-DD>
|
||||
**Papers surveyed**: <N>
|
||||
**Scope**: <arXiv search query, category, time window>
|
||||
**Citation format**: BibTeX
|
||||
|
||||
## Executive Summary
|
||||
|
||||
<3-5 sentences. Use \cite{key} form for citations, e.g. "Transformer architectures \cite{vaswani2017attention} have become the dominant approach.">
|
||||
|
||||
## Methodology
|
||||
|
||||
This review surveyed <N> arXiv papers retrieved on <YYYY-MM-DD> using the query `<query>`<, filtered to category <cat>><, published between <start_date> and <end_date>>. Metadata extraction was performed by language-model agents, with cross-paper synthesis performed by the lead agent. All citations in this report use BibTeX cite keys; the corresponding `.bib` entries are at the end of this document.
|
||||
|
||||
**Limitations of this review**: arXiv preprints are not peer-reviewed; coverage is limited to arXiv.
|
||||
|
||||
## Themes
|
||||
|
||||
### Theme 1: <Theme name>
|
||||
|
||||
<Paragraphs describing the theme. Cite with \cite{key} form: "The original transformer architecture \cite{vaswani2017attention} introduced self-attention, which was later extended in \cite{dai2019transformerxl}.">
|
||||
|
||||
### Theme 2: <Theme name>
|
||||
|
||||
<...>
|
||||
|
||||
## Convergences and Disagreements
|
||||
|
||||
**Convergences**: <e.g. "Multiple papers \cite{key1,key2,key3} agree that X is necessary.">
|
||||
|
||||
**Disagreements**: <...>
|
||||
|
||||
## Gaps and Open Questions
|
||||
|
||||
<...>
|
||||
|
||||
## Per-Paper Annotations
|
||||
|
||||
### \cite{vaswani2017attention} — "Attention Is All You Need" (2017)
|
||||
|
||||
**Research question**: <1 sentence>
|
||||
**Methodology**: <1-2 sentences>
|
||||
**Key findings**:
|
||||
- <bullet>
|
||||
- <bullet>
|
||||
- <bullet>
|
||||
**Limitations**: <1-2 sentences>
|
||||
|
||||
### \cite{devlin2018bert} — "BERT: Pre-training of Deep Bidirectional Transformers" (2018)
|
||||
|
||||
<...>
|
||||
|
||||
## BibTeX Bibliography
|
||||
|
||||
Save the entries below to a `.bib` file and reference them from your LaTeX document with `\bibliography{filename}`.
|
||||
|
||||
\`\`\`bibtex
|
||||
@misc{vaswani2017attention,
|
||||
author = {Vaswani, Ashish and Shazeer, Noam and Parmar, Niki and Uszkoreit, Jakob and Jones, Llion and Gomez, Aidan N. and Kaiser, {\L}ukasz and Polosukhin, Illia},
|
||||
title = {Attention Is All You Need},
|
||||
year = {2017},
|
||||
eprint = {1706.03762},
|
||||
archivePrefix = {arXiv},
|
||||
primaryClass = {cs.CL},
|
||||
url = {https://arxiv.org/abs/1706.03762}
|
||||
}
|
||||
|
||||
@misc{devlin2018bert,
|
||||
author = {Devlin, Jacob and Chang, Ming-Wei and Lee, Kenton and Toutanova, Kristina},
|
||||
title = {{BERT}: Pre-training of Deep Bidirectional Transformers for Language Understanding},
|
||||
year = {2018},
|
||||
eprint = {1810.04805},
|
||||
archivePrefix = {arXiv},
|
||||
primaryClass = {cs.CL},
|
||||
url = {https://arxiv.org/abs/1810.04805}
|
||||
}
|
||||
|
||||
... more entries, one per paper ...
|
||||
\`\`\`
|
||||
```
|
||||
|
||||
(Note: in the actual saved report, use a real fenced code block `` ```bibtex `` — the backticks above are escaped only because this template file itself is inside a markdown code block when rendered.)
|
||||
|
||||
## Quality checks before finalizing
|
||||
|
||||
Before saving the report, verify:
|
||||
|
||||
- [ ] Every entry is `@misc`, not `@article` (this workflow only has arXiv metadata).
|
||||
- [ ] Cite keys are unique within the report.
|
||||
- [ ] Cite keys follow the `<firstauthorlast><year><firstword>` pattern, all lowercase.
|
||||
- [ ] `author` field uses ` and ` (the literal word) between authors, not commas.
|
||||
- [ ] LaTeX special characters in author names are escaped or brace-wrapped.
|
||||
- [ ] `eprint` is the bare arXiv id (no `arXiv:` prefix, no version suffix).
|
||||
- [ ] `primaryClass` is set from the paper's first category.
|
||||
- [ ] Every `\cite{key}` in the text has a matching `@misc` entry in the bibliography.
|
||||
- [ ] The bibliography is emitted inside a fenced ```` ```bibtex ```` code block so users can copy-paste directly into a `.bib` file.
|
||||
@@ -0,0 +1,127 @@
|
||||
# IEEE Citation Template
|
||||
|
||||
Use this template when the user targets an IEEE conference or journal, or explicitly asks for IEEE format. IEEE uses **numeric citations** — references are numbered in the order they first appear in the text, and in-text citations use bracketed numbers.
|
||||
|
||||
## Citation Format Rules
|
||||
|
||||
### In-text citations
|
||||
|
||||
- **Single reference**: `[1]` — use the number assigned in the References section.
|
||||
- **Multiple references**: `[1], [3], [5]` or `[1]–[3]` for consecutive ranges.
|
||||
- **Citation as a noun**: "As shown in [1], ..." or "Reference [1] demonstrated...".
|
||||
- **Author attribution**: "Vaswani et al. [1] introduced..." — author names are optional in IEEE; use them when it improves readability, always followed by the bracketed number.
|
||||
|
||||
Numbers are assigned in **order of first appearance in the text**, not alphabetically. The first reference you cite is `[1]`, the second new reference is `[2]`, and so on.
|
||||
|
||||
### Reference list entry for arXiv preprints
|
||||
|
||||
IEEE format for arXiv preprints:
|
||||
|
||||
```
|
||||
[N] A. A. Author, B. B. Author, and C. C. Author, "Title of the paper," arXiv:ARXIV_ID, Year.
|
||||
```
|
||||
|
||||
**Real example**:
|
||||
|
||||
```
|
||||
[1] A. Vaswani, N. Shazeer, N. Parmar, J. Uszkoreit, L. Jones, A. N. Gomez, Ł. Kaiser, and I. Polosukhin, "Attention is all you need," arXiv:1706.03762, 2017.
|
||||
```
|
||||
|
||||
Formatting rules:
|
||||
|
||||
- **Author names**: `FirstInitial. LastName` — initials before the last name, opposite of APA. Join with commas; last author gets `and` (no Oxford comma before it in strict IEEE, but accepted).
|
||||
- **Title**: in double quotes, sentence case. No italics.
|
||||
- **Source**: `arXiv:<id>` — the literal prefix `arXiv:` followed by the bare id (e.g. `arXiv:1706.03762`, not the full URL).
|
||||
- **Year**: at the end, after a comma.
|
||||
- **URL**: optional in IEEE. Include if the publication venue requires it; otherwise the `arXiv:<id>` identifier is sufficient and is the IEEE-preferred form.
|
||||
|
||||
### Special cases
|
||||
|
||||
- **More than 6 authors**: IEEE allows listing the first author followed by `et al.`: `A. Vaswani et al., "Attention is all you need," arXiv:1706.03762, 2017.` Use this for papers with many authors to keep reference entries readable.
|
||||
- **If the paper has also been published at a venue**: prefer the venue citation format over arXiv. In this workflow we only have arXiv metadata, so always use the arXiv form.
|
||||
|
||||
## Report Structure
|
||||
|
||||
Follow this structure verbatim. Note that IEEE reports use **numeric citations throughout**, so you need to assign a number to each paper **in order of first appearance** in the Themes section, then use those numbers consistently in per-paper annotations and the reference list.
|
||||
|
||||
```markdown
|
||||
# Systematic Literature Review: <Topic>
|
||||
|
||||
**Date**: <YYYY-MM-DD>
|
||||
**Papers surveyed**: <N>
|
||||
**Scope**: <arXiv search query, category, time window>
|
||||
**Citation format**: IEEE
|
||||
|
||||
## Executive Summary
|
||||
|
||||
<3-5 sentences summarizing the state of the literature. Cite papers with bracketed numbers as you first introduce them, e.g. "Transformer architectures [1] have become the dominant approach, with extensions focusing on efficiency [2], [3] and long-context handling [4].">
|
||||
|
||||
## Methodology
|
||||
|
||||
This review surveyed <N> arXiv papers retrieved on <YYYY-MM-DD> using the query `<query>`<, filtered to category <cat>><, published between <start_date> and <end_date>>. Papers were sorted by <relevance | submission date> and the top <N> were included. Metadata extraction was performed by language-model agents, with cross-paper synthesis performed by the lead agent.
|
||||
|
||||
**Limitations of this review**: arXiv preprints are not peer-reviewed; coverage is limited to arXiv.
|
||||
|
||||
## Themes
|
||||
|
||||
<3-6 thematic sections. First appearance of each paper gets a bracketed number; subsequent mentions reuse the same number. The number assignment order is: first paper mentioned in Theme 1 gets [1], next new paper gets [2], etc.>
|
||||
|
||||
### Theme 1: <Theme name>
|
||||
|
||||
<Paragraphs describing the theme. Cite with bracketed numbers: "The original transformer architecture [1] introduced self-attention, which was later extended in [2] and [3]. Comparative analyses [4] show that...">
|
||||
|
||||
### Theme 2: <Theme name>
|
||||
|
||||
<...>
|
||||
|
||||
## Convergences and Disagreements
|
||||
|
||||
**Convergences**: <e.g. "Multiple papers [1], [3], [5] agree that X is necessary.">
|
||||
|
||||
**Disagreements**: <e.g. "While [1] argues X, [2] finds the opposite under condition Y.">
|
||||
|
||||
## Gaps and Open Questions
|
||||
|
||||
<What the collective literature does not yet address, with citations to papers that explicitly mention these gaps.>
|
||||
|
||||
## Per-Paper Annotations
|
||||
|
||||
<One subsection per paper, ordered by their assigned reference number.>
|
||||
|
||||
### [1] Vaswani et al., "Attention is all you need" (2017)
|
||||
|
||||
**Research question**: <1 sentence>
|
||||
**Methodology**: <1-2 sentences>
|
||||
**Key findings**:
|
||||
- <bullet>
|
||||
- <bullet>
|
||||
- <bullet>
|
||||
**Limitations**: <1-2 sentences>
|
||||
|
||||
### [2] <Next paper>
|
||||
|
||||
<...>
|
||||
|
||||
## References
|
||||
|
||||
<Numbered list in order of first appearance in the text. The number must match the in-text citations above.>
|
||||
|
||||
[1] A. Vaswani, N. Shazeer, N. Parmar, J. Uszkoreit, L. Jones, A. N. Gomez, Ł. Kaiser, and I. Polosukhin, "Attention is all you need," arXiv:1706.03762, 2017.
|
||||
|
||||
[2] J. Devlin, M.-W. Chang, K. Lee, and K. Toutanova, "BERT: Pre-training of deep bidirectional transformers for language understanding," arXiv:1810.04805, 2018.
|
||||
|
||||
<... more entries ...>
|
||||
```
|
||||
|
||||
## Quality checks before finalizing
|
||||
|
||||
Before saving the report, verify:
|
||||
|
||||
- [ ] Every paper in the surveyed set has a unique reference number.
|
||||
- [ ] Reference numbers are assigned in order of **first appearance in the text**, not alphabetically.
|
||||
- [ ] Every bracketed number in the text has a matching entry in the References section.
|
||||
- [ ] Every entry in References is cited at least once in the text.
|
||||
- [ ] Author names use `FirstInitial. LastName` format (initials before last name).
|
||||
- [ ] Titles are in double quotes and sentence case.
|
||||
- [ ] arXiv identifiers use the `arXiv:<bare_id>` form, not the full URL.
|
||||
- [ ] Per-paper annotations are ordered by reference number, matching the References section order.
|
||||
112
deer-flow/skills/public/vercel-deploy-claimable/SKILL.md
Normal file
112
deer-flow/skills/public/vercel-deploy-claimable/SKILL.md
Normal file
@@ -0,0 +1,112 @@
|
||||
---
|
||||
name: vercel-deploy
|
||||
description: Deploy applications and websites to Vercel. Use this skill when the user requests deployment actions such as "Deploy my app", "Deploy this to production", "Create a preview deployment", "Deploy and give me the link", or "Push this live". No authentication required - returns preview URL and claimable deployment link.
|
||||
metadata:
|
||||
author: vercel
|
||||
version: "1.0.0"
|
||||
---
|
||||
|
||||
# Vercel Deploy
|
||||
|
||||
Deploy any project to Vercel instantly. No authentication required.
|
||||
|
||||
## How It Works
|
||||
|
||||
1. Packages your project into a tarball (excludes `node_modules` and `.git`)
|
||||
2. Auto-detects framework from `package.json`
|
||||
3. Uploads to deployment service
|
||||
4. Returns **Preview URL** (live site) and **Claim URL** (transfer to your Vercel account)
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
bash /mnt/skills/user/vercel-deploy/scripts/deploy.sh [path]
|
||||
```
|
||||
|
||||
**Arguments:**
|
||||
- `path` - Directory to deploy, or a `.tgz` file (defaults to current directory)
|
||||
|
||||
**Examples:**
|
||||
|
||||
```bash
|
||||
# Deploy current directory
|
||||
bash /mnt/skills/user/vercel-deploy/scripts/deploy.sh
|
||||
|
||||
# Deploy specific project
|
||||
bash /mnt/skills/user/vercel-deploy/scripts/deploy.sh /path/to/project
|
||||
|
||||
# Deploy existing tarball
|
||||
bash /mnt/skills/user/vercel-deploy/scripts/deploy.sh /path/to/project.tgz
|
||||
```
|
||||
|
||||
## Output
|
||||
|
||||
```
|
||||
Preparing deployment...
|
||||
Detected framework: nextjs
|
||||
Creating deployment package...
|
||||
Deploying...
|
||||
✓ Deployment successful!
|
||||
|
||||
Preview URL: https://skill-deploy-abc123.vercel.app
|
||||
Claim URL: https://vercel.com/claim-deployment?code=...
|
||||
```
|
||||
|
||||
The script also outputs JSON to stdout for programmatic use:
|
||||
|
||||
```json
|
||||
{
|
||||
"previewUrl": "https://skill-deploy-abc123.vercel.app",
|
||||
"claimUrl": "https://vercel.com/claim-deployment?code=...",
|
||||
"deploymentId": "dpl_...",
|
||||
"projectId": "prj_..."
|
||||
}
|
||||
```
|
||||
|
||||
## Framework Detection
|
||||
|
||||
The script auto-detects frameworks from `package.json`. Supported frameworks include:
|
||||
|
||||
- **React**: Next.js, Gatsby, Create React App, Remix, React Router
|
||||
- **Vue**: Nuxt, Vitepress, Vuepress, Gridsome
|
||||
- **Svelte**: SvelteKit, Svelte, Sapper
|
||||
- **Other Frontend**: Astro, Solid Start, Angular, Ember, Preact, Docusaurus
|
||||
- **Backend**: Express, Hono, Fastify, NestJS, Elysia, h3, Nitro
|
||||
- **Build Tools**: Vite, Parcel
|
||||
- **And more**: Blitz, Hydrogen, RedwoodJS, Storybook, Sanity, etc.
|
||||
|
||||
For static HTML projects (no `package.json`), framework is set to `null`.
|
||||
|
||||
## Static HTML Projects
|
||||
|
||||
For projects without a `package.json`:
|
||||
- If there's a single `.html` file not named `index.html`, it gets renamed automatically
|
||||
- This ensures the page is served at the root URL (`/`)
|
||||
|
||||
## Present Results to User
|
||||
|
||||
Always show both URLs:
|
||||
|
||||
```
|
||||
✓ Deployment successful!
|
||||
|
||||
- [Preview URL](https://skill-deploy-abc123.vercel.app)
|
||||
- [Claim URL](https://vercel.com/claim-deployment?code=...)
|
||||
|
||||
View your site at the Preview URL.
|
||||
To transfer this deployment to your Vercel account, visit the Claim URL.
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Network Egress Error
|
||||
|
||||
If deployment fails due to network restrictions (common on claude.ai), tell the user:
|
||||
|
||||
```
|
||||
Deployment failed due to network restrictions. To fix this:
|
||||
|
||||
1. Go to https://claude.ai/settings/capabilities
|
||||
2. Add *.vercel.com to the allowed domains
|
||||
3. Try deploying again
|
||||
```
|
||||
249
deer-flow/skills/public/vercel-deploy-claimable/scripts/deploy.sh
Executable file
249
deer-flow/skills/public/vercel-deploy-claimable/scripts/deploy.sh
Executable file
@@ -0,0 +1,249 @@
|
||||
#!/bin/bash
|
||||
|
||||
# Vercel Deployment Script (via claimable deploy endpoint)
|
||||
# Usage: ./deploy.sh [project-path]
|
||||
# Returns: JSON with previewUrl, claimUrl, deploymentId, projectId
|
||||
|
||||
set -e
|
||||
|
||||
DEPLOY_ENDPOINT="https://claude-skills-deploy.vercel.com/api/deploy"
|
||||
|
||||
# Detect framework from package.json
|
||||
detect_framework() {
|
||||
local pkg_json="$1"
|
||||
|
||||
if [ ! -f "$pkg_json" ]; then
|
||||
echo "null"
|
||||
return
|
||||
fi
|
||||
|
||||
local content=$(cat "$pkg_json")
|
||||
|
||||
# Helper to check if a package exists in dependencies or devDependencies
|
||||
has_dep() {
|
||||
echo "$content" | grep -q "\"$1\""
|
||||
}
|
||||
|
||||
# Order matters - check more specific frameworks first
|
||||
|
||||
# Blitz
|
||||
if has_dep "blitz"; then echo "blitzjs"; return; fi
|
||||
|
||||
# Next.js
|
||||
if has_dep "next"; then echo "nextjs"; return; fi
|
||||
|
||||
# Gatsby
|
||||
if has_dep "gatsby"; then echo "gatsby"; return; fi
|
||||
|
||||
# Remix
|
||||
if has_dep "@remix-run/"; then echo "remix"; return; fi
|
||||
|
||||
# React Router (v7 framework mode)
|
||||
if has_dep "@react-router/"; then echo "react-router"; return; fi
|
||||
|
||||
# TanStack Start
|
||||
if has_dep "@tanstack/start"; then echo "tanstack-start"; return; fi
|
||||
|
||||
# Astro
|
||||
if has_dep "astro"; then echo "astro"; return; fi
|
||||
|
||||
# Hydrogen (Shopify)
|
||||
if has_dep "@shopify/hydrogen"; then echo "hydrogen"; return; fi
|
||||
|
||||
# SvelteKit
|
||||
if has_dep "@sveltejs/kit"; then echo "sveltekit-1"; return; fi
|
||||
|
||||
# Svelte (standalone)
|
||||
if has_dep "svelte"; then echo "svelte"; return; fi
|
||||
|
||||
# Nuxt
|
||||
if has_dep "nuxt"; then echo "nuxtjs"; return; fi
|
||||
|
||||
# Vue with Vitepress
|
||||
if has_dep "vitepress"; then echo "vitepress"; return; fi
|
||||
|
||||
# Vue with Vuepress
|
||||
if has_dep "vuepress"; then echo "vuepress"; return; fi
|
||||
|
||||
# Gridsome
|
||||
if has_dep "gridsome"; then echo "gridsome"; return; fi
|
||||
|
||||
# SolidStart
|
||||
if has_dep "@solidjs/start"; then echo "solidstart-1"; return; fi
|
||||
|
||||
# Docusaurus
|
||||
if has_dep "@docusaurus/core"; then echo "docusaurus-2"; return; fi
|
||||
|
||||
# RedwoodJS
|
||||
if has_dep "@redwoodjs/"; then echo "redwoodjs"; return; fi
|
||||
|
||||
# Hexo
|
||||
if has_dep "hexo"; then echo "hexo"; return; fi
|
||||
|
||||
# Eleventy
|
||||
if has_dep "@11ty/eleventy"; then echo "eleventy"; return; fi
|
||||
|
||||
# Angular / Ionic Angular
|
||||
if has_dep "@ionic/angular"; then echo "ionic-angular"; return; fi
|
||||
if has_dep "@angular/core"; then echo "angular"; return; fi
|
||||
|
||||
# Ionic React
|
||||
if has_dep "@ionic/react"; then echo "ionic-react"; return; fi
|
||||
|
||||
# Create React App
|
||||
if has_dep "react-scripts"; then echo "create-react-app"; return; fi
|
||||
|
||||
# Ember
|
||||
if has_dep "ember-cli" || has_dep "ember-source"; then echo "ember"; return; fi
|
||||
|
||||
# Dojo
|
||||
if has_dep "@dojo/framework"; then echo "dojo"; return; fi
|
||||
|
||||
# Polymer
|
||||
if has_dep "@polymer/"; then echo "polymer"; return; fi
|
||||
|
||||
# Preact
|
||||
if has_dep "preact"; then echo "preact"; return; fi
|
||||
|
||||
# Stencil
|
||||
if has_dep "@stencil/core"; then echo "stencil"; return; fi
|
||||
|
||||
# UmiJS
|
||||
if has_dep "umi"; then echo "umijs"; return; fi
|
||||
|
||||
# Sapper (legacy Svelte)
|
||||
if has_dep "sapper"; then echo "sapper"; return; fi
|
||||
|
||||
# Saber
|
||||
if has_dep "saber"; then echo "saber"; return; fi
|
||||
|
||||
# Sanity
|
||||
if has_dep "sanity"; then echo "sanity-v3"; return; fi
|
||||
if has_dep "@sanity/"; then echo "sanity"; return; fi
|
||||
|
||||
# Storybook
|
||||
if has_dep "@storybook/"; then echo "storybook"; return; fi
|
||||
|
||||
# NestJS
|
||||
if has_dep "@nestjs/core"; then echo "nestjs"; return; fi
|
||||
|
||||
# Elysia
|
||||
if has_dep "elysia"; then echo "elysia"; return; fi
|
||||
|
||||
# Hono
|
||||
if has_dep "hono"; then echo "hono"; return; fi
|
||||
|
||||
# Fastify
|
||||
if has_dep "fastify"; then echo "fastify"; return; fi
|
||||
|
||||
# h3
|
||||
if has_dep "h3"; then echo "h3"; return; fi
|
||||
|
||||
# Nitro
|
||||
if has_dep "nitropack"; then echo "nitro"; return; fi
|
||||
|
||||
# Express
|
||||
if has_dep "express"; then echo "express"; return; fi
|
||||
|
||||
# Vite (generic - check last among JS frameworks)
|
||||
if has_dep "vite"; then echo "vite"; return; fi
|
||||
|
||||
# Parcel
|
||||
if has_dep "parcel"; then echo "parcel"; return; fi
|
||||
|
||||
# No framework detected
|
||||
echo "null"
|
||||
}
|
||||
|
||||
# Parse arguments
|
||||
INPUT_PATH="${1:-.}"
|
||||
|
||||
# Create temp directory for packaging
|
||||
TEMP_DIR=$(mktemp -d)
|
||||
TARBALL="$TEMP_DIR/project.tgz"
|
||||
CLEANUP_TEMP=true
|
||||
|
||||
cleanup() {
|
||||
if [ "$CLEANUP_TEMP" = true ]; then
|
||||
rm -rf "$TEMP_DIR"
|
||||
fi
|
||||
}
|
||||
trap cleanup EXIT
|
||||
|
||||
echo "Preparing deployment..." >&2
|
||||
|
||||
# Check if input is a .tgz file or a directory
|
||||
FRAMEWORK="null"
|
||||
|
||||
if [ -f "$INPUT_PATH" ] && [[ "$INPUT_PATH" == *.tgz ]]; then
|
||||
# Input is already a tarball, use it directly
|
||||
echo "Using provided tarball..." >&2
|
||||
TARBALL="$INPUT_PATH"
|
||||
CLEANUP_TEMP=false
|
||||
# Can't detect framework from tarball, leave as null
|
||||
elif [ -d "$INPUT_PATH" ]; then
|
||||
# Input is a directory, need to tar it
|
||||
PROJECT_PATH=$(cd "$INPUT_PATH" && pwd)
|
||||
|
||||
# Detect framework from package.json
|
||||
FRAMEWORK=$(detect_framework "$PROJECT_PATH/package.json")
|
||||
|
||||
# Check if this is a static HTML project (no package.json)
|
||||
if [ ! -f "$PROJECT_PATH/package.json" ]; then
|
||||
# Find HTML files in root
|
||||
HTML_FILES=$(find "$PROJECT_PATH" -maxdepth 1 -name "*.html" -type f)
|
||||
HTML_COUNT=$(echo "$HTML_FILES" | grep -c . || echo 0)
|
||||
|
||||
# If there's exactly one HTML file and it's not index.html, rename it
|
||||
if [ "$HTML_COUNT" -eq 1 ]; then
|
||||
HTML_FILE=$(echo "$HTML_FILES" | head -1)
|
||||
BASENAME=$(basename "$HTML_FILE")
|
||||
if [ "$BASENAME" != "index.html" ]; then
|
||||
echo "Renaming $BASENAME to index.html..." >&2
|
||||
mv "$HTML_FILE" "$PROJECT_PATH/index.html"
|
||||
fi
|
||||
fi
|
||||
fi
|
||||
|
||||
# Create tarball of the project (excluding node_modules and .git)
|
||||
echo "Creating deployment package..." >&2
|
||||
tar -czf "$TARBALL" -C "$PROJECT_PATH" --exclude='node_modules' --exclude='.git' .
|
||||
else
|
||||
echo "Error: Input must be a directory or a .tgz file" >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
if [ "$FRAMEWORK" != "null" ]; then
|
||||
echo "Detected framework: $FRAMEWORK" >&2
|
||||
fi
|
||||
|
||||
# Deploy
|
||||
echo "Deploying..." >&2
|
||||
RESPONSE=$(curl -s -X POST "$DEPLOY_ENDPOINT" -F "file=@$TARBALL" -F "framework=$FRAMEWORK")
|
||||
|
||||
# Check for error in response
|
||||
if echo "$RESPONSE" | grep -q '"error"'; then
|
||||
ERROR_MSG=$(echo "$RESPONSE" | grep -o '"error":"[^"]*"' | cut -d'"' -f4)
|
||||
echo "Error: $ERROR_MSG" >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Extract URLs from response
|
||||
PREVIEW_URL=$(echo "$RESPONSE" | grep -o '"previewUrl":"[^"]*"' | cut -d'"' -f4)
|
||||
CLAIM_URL=$(echo "$RESPONSE" | grep -o '"claimUrl":"[^"]*"' | cut -d'"' -f4)
|
||||
|
||||
if [ -z "$PREVIEW_URL" ]; then
|
||||
echo "Error: Could not extract preview URL from response" >&2
|
||||
echo "$RESPONSE" >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo "" >&2
|
||||
echo "Deployment successful!" >&2
|
||||
echo "" >&2
|
||||
echo "Preview URL: $PREVIEW_URL" >&2
|
||||
echo "Claim URL: $CLAIM_URL" >&2
|
||||
echo "" >&2
|
||||
|
||||
# Output JSON for programmatic use
|
||||
echo "$RESPONSE"
|
||||
139
deer-flow/skills/public/video-generation/SKILL.md
Normal file
139
deer-flow/skills/public/video-generation/SKILL.md
Normal file
@@ -0,0 +1,139 @@
|
||||
---
|
||||
name: video-generation
|
||||
description: Use this skill when the user requests to generate, create, or imagine videos. Supports structured prompts and reference image for guided generation.
|
||||
---
|
||||
|
||||
# Video Generation Skill
|
||||
|
||||
## Overview
|
||||
|
||||
This skill generates high-quality videos using structured prompts and a Python script. The workflow includes creating JSON-formatted prompts and executing video generation with optional reference image.
|
||||
|
||||
## Core Capabilities
|
||||
|
||||
- Create structured JSON prompts for AIGC video generation
|
||||
- Support reference image as guidance or the first/last frame of the video
|
||||
- Generate videos through automated Python script execution
|
||||
|
||||
## Workflow
|
||||
|
||||
### Step 1: Understand Requirements
|
||||
|
||||
When a user requests video generation, identify:
|
||||
|
||||
- Subject/content: What should be in the image
|
||||
- Style preferences: Art style, mood, color palette
|
||||
- Technical specs: Aspect ratio, composition, lighting
|
||||
- Reference image: Any image to guide generation
|
||||
- You don't need to check the folder under `/mnt/user-data`
|
||||
|
||||
### Step 2: Create Structured Prompt
|
||||
|
||||
Generate a structured JSON file in `/mnt/user-data/workspace/` with naming pattern: `{descriptive-name}.json`
|
||||
|
||||
### Step 3: Create Reference Image (Optional when image-generation skill is available)
|
||||
|
||||
Generate reference image for the video generation.
|
||||
|
||||
- If only 1 image is provided, use it as the guided frame of the video
|
||||
|
||||
### Step 3: Execute Generation
|
||||
|
||||
Call the Python script:
|
||||
```bash
|
||||
python /mnt/skills/public/video-generation/scripts/generate.py \
|
||||
--prompt-file /mnt/user-data/workspace/prompt-file.json \
|
||||
--reference-images /path/to/ref1.jpg \
|
||||
--output-file /mnt/user-data/outputs/generated-video.mp4 \
|
||||
--aspect-ratio 16:9
|
||||
```
|
||||
|
||||
Parameters:
|
||||
|
||||
- `--prompt-file`: Absolute path to JSON prompt file (required)
|
||||
- `--reference-images`: Absolute paths to reference image (optional)
|
||||
- `--output-file`: Absolute path to output image file (required)
|
||||
- `--aspect-ratio`: Aspect ratio of the generated image (optional, default: 16:9)
|
||||
|
||||
[!NOTE]
|
||||
Do NOT read the python file, instead just call it with the parameters.
|
||||
|
||||
## Video Generation Example
|
||||
|
||||
User request: "Generate a short video clip depicting the opening scene from "The Chronicles of Narnia: The Lion, the Witch and the Wardrobe"
|
||||
|
||||
Step 1: Search for the opening scene of "The Chronicles of Narnia: The Lion, the Witch and the Wardrobe" online
|
||||
|
||||
Step 2: Create a JSON prompt file with the following content:
|
||||
|
||||
```json
|
||||
{
|
||||
"title": "The Chronicles of Narnia - Train Station Farewell",
|
||||
"background": {
|
||||
"description": "World War II evacuation scene at a crowded London train station. Steam and smoke fill the air as children are being sent to the countryside to escape the Blitz.",
|
||||
"era": "1940s wartime Britain",
|
||||
"location": "London railway station platform"
|
||||
},
|
||||
"characters": ["Mrs. Pevensie", "Lucy Pevensie"],
|
||||
"camera": {
|
||||
"type": "Close-up two-shot",
|
||||
"movement": "Static with subtle handheld movement",
|
||||
"angle": "Profile view, intimate framing",
|
||||
"focus": "Both faces in focus, background soft bokeh"
|
||||
},
|
||||
"dialogue": [
|
||||
{
|
||||
"character": "Mrs. Pevensie",
|
||||
"text": "You must be brave for me, darling. I'll come for you... I promise."
|
||||
},
|
||||
{
|
||||
"character": "Lucy Pevensie",
|
||||
"text": "I will be, mother. I promise."
|
||||
}
|
||||
],
|
||||
"audio": [
|
||||
{
|
||||
"type": "Train whistle blows (signaling departure)",
|
||||
"volume": 1
|
||||
},
|
||||
{
|
||||
"type": "Strings swell emotionally, then fade",
|
||||
"volume": 0.5
|
||||
},
|
||||
{
|
||||
"type": "Ambient sound of the train station",
|
||||
"volume": 0.5
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Step 3: Use the image-generation skill to generate the reference image
|
||||
|
||||
Load the image-generation skill and generate a single reference image `narnia-farewell-scene-01.jpg` according to the skill.
|
||||
|
||||
Step 4: Use the generate.py script to generate the video
|
||||
```bash
|
||||
python /mnt/skills/public/video-generation/scripts/generate.py \
|
||||
--prompt-file /mnt/user-data/workspace/narnia-farewell-scene.json \
|
||||
--reference-images /mnt/user-data/outputs/narnia-farewell-scene-01.jpg \
|
||||
--output-file /mnt/user-data/outputs/narnia-farewell-scene-01.mp4 \
|
||||
--aspect-ratio 16:9
|
||||
```
|
||||
> Do NOT read the python file, just call it with the parameters.
|
||||
|
||||
## Output Handling
|
||||
|
||||
After generation:
|
||||
|
||||
- Videos are typically saved in `/mnt/user-data/outputs/`
|
||||
- Share generated videos (come first) with user as well as generated image if applicable, using `present_files` tool
|
||||
- Provide brief description of the generation result
|
||||
- Offer to iterate if adjustments needed
|
||||
|
||||
## Notes
|
||||
|
||||
- Always use English for prompts regardless of user's language
|
||||
- JSON format ensures structured, parsable prompts
|
||||
- Reference image enhance generation quality significantly
|
||||
- Iterative refinement is normal for optimal results
|
||||
116
deer-flow/skills/public/video-generation/scripts/generate.py
Normal file
116
deer-flow/skills/public/video-generation/scripts/generate.py
Normal file
@@ -0,0 +1,116 @@
|
||||
import base64
|
||||
import os
|
||||
import time
|
||||
|
||||
import requests
|
||||
|
||||
|
||||
def generate_video(
|
||||
prompt_file: str,
|
||||
reference_images: list[str],
|
||||
output_file: str,
|
||||
aspect_ratio: str = "16:9",
|
||||
) -> str:
|
||||
with open(prompt_file, "r", encoding="utf-8") as f:
|
||||
prompt = f.read()
|
||||
referenceImages = []
|
||||
i = 0
|
||||
json = {
|
||||
"instances": [{"prompt": prompt}],
|
||||
}
|
||||
for reference_image in reference_images:
|
||||
i += 1
|
||||
with open(reference_image, "rb") as f:
|
||||
image_b64 = base64.b64encode(f.read()).decode("utf-8")
|
||||
referenceImages.append(
|
||||
{
|
||||
"image": {"mimeType": "image/jpeg", "bytesBase64Encoded": image_b64},
|
||||
"referenceType": "asset",
|
||||
}
|
||||
)
|
||||
if i > 0:
|
||||
json["instances"][0]["referenceImages"] = referenceImages
|
||||
api_key = os.getenv("GEMINI_API_KEY")
|
||||
if not api_key:
|
||||
return "GEMINI_API_KEY is not set"
|
||||
response = requests.post(
|
||||
"https://generativelanguage.googleapis.com/v1beta/models/veo-3.1-generate-preview:predictLongRunning",
|
||||
headers={
|
||||
"x-goog-api-key": api_key,
|
||||
"Content-Type": "application/json",
|
||||
},
|
||||
json=json,
|
||||
)
|
||||
json = response.json()
|
||||
operation_name = json["name"]
|
||||
while True:
|
||||
response = requests.get(
|
||||
f"https://generativelanguage.googleapis.com/v1beta/{operation_name}",
|
||||
headers={
|
||||
"x-goog-api-key": api_key,
|
||||
},
|
||||
)
|
||||
json = response.json()
|
||||
if json.get("done", False):
|
||||
sample = json["response"]["generateVideoResponse"]["generatedSamples"][0]
|
||||
url = sample["video"]["uri"]
|
||||
download(url, output_file)
|
||||
break
|
||||
time.sleep(3)
|
||||
return f"The video has been generated successfully to {output_file}"
|
||||
|
||||
|
||||
def download(url: str, output_file: str):
|
||||
api_key = os.getenv("GEMINI_API_KEY")
|
||||
if not api_key:
|
||||
return "GEMINI_API_KEY is not set"
|
||||
response = requests.get(
|
||||
url,
|
||||
headers={
|
||||
"x-goog-api-key": api_key,
|
||||
},
|
||||
)
|
||||
with open(output_file, "wb") as f:
|
||||
f.write(response.content)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
import argparse
|
||||
|
||||
parser = argparse.ArgumentParser(description="Generate videos using Gemini API")
|
||||
parser.add_argument(
|
||||
"--prompt-file",
|
||||
required=True,
|
||||
help="Absolute path to JSON prompt file",
|
||||
)
|
||||
parser.add_argument(
|
||||
"--reference-images",
|
||||
nargs="*",
|
||||
default=[],
|
||||
help="Absolute paths to reference images (space-separated)",
|
||||
)
|
||||
parser.add_argument(
|
||||
"--output-file",
|
||||
required=True,
|
||||
help="Output path for generated image",
|
||||
)
|
||||
parser.add_argument(
|
||||
"--aspect-ratio",
|
||||
required=False,
|
||||
default="16:9",
|
||||
help="Aspect ratio of the generated image",
|
||||
)
|
||||
|
||||
args = parser.parse_args()
|
||||
|
||||
try:
|
||||
print(
|
||||
generate_video(
|
||||
args.prompt_file,
|
||||
args.reference_images,
|
||||
args.output_file,
|
||||
args.aspect_ratio,
|
||||
)
|
||||
)
|
||||
except Exception as e:
|
||||
print(f"Error while generating video: {e}")
|
||||
39
deer-flow/skills/public/web-design-guidelines/SKILL.md
Normal file
39
deer-flow/skills/public/web-design-guidelines/SKILL.md
Normal file
@@ -0,0 +1,39 @@
|
||||
---
|
||||
name: web-design-guidelines
|
||||
description: Review UI code for Web Interface Guidelines compliance. Use when asked to "review my UI", "check accessibility", "audit design", "review UX", or "check my site against best practices".
|
||||
metadata:
|
||||
author: vercel
|
||||
version: "1.0.0"
|
||||
argument-hint: <file-or-pattern>
|
||||
---
|
||||
|
||||
# Web Interface Guidelines
|
||||
|
||||
Review files for compliance with Web Interface Guidelines.
|
||||
|
||||
## How It Works
|
||||
|
||||
1. Fetch the latest guidelines from the source URL below
|
||||
2. Read the specified files (or prompt user for files/pattern)
|
||||
3. Check against all rules in the fetched guidelines
|
||||
4. Output findings in the terse `file:line` format
|
||||
|
||||
## Guidelines Source
|
||||
|
||||
Fetch fresh guidelines before each review:
|
||||
|
||||
```
|
||||
https://raw.githubusercontent.com/vercel-labs/web-interface-guidelines/main/command.md
|
||||
```
|
||||
|
||||
Use WebFetch to retrieve the latest rules. The fetched content contains all the rules and output format instructions.
|
||||
|
||||
## Usage
|
||||
|
||||
When a user provides a file or pattern argument:
|
||||
1. Fetch guidelines from the source URL above
|
||||
2. Read the specified files
|
||||
3. Apply all rules from the fetched guidelines
|
||||
4. Output findings using the format specified in the guidelines
|
||||
|
||||
If no files specified, ask the user which files to review.
|
||||
Reference in New Issue
Block a user