DeerFlow github-deep-research 报告模板全解析：结构化研究产出的骨架设计、占位符规范与 GitHub API 数据源映射

skills/public/github-deep-research/assets/report_template.md 是 DeerFlow 内置 github-deep-research 技能的最终产出物模板，规定了多轮深度研究报告的完整章节骨架：从元数据块、仓库信息、执行摘要、分阶段时间线，到 Mermaid 架构图、指标对比表、四分类来源列表与三级置信度评估。读完本文，你可以完整理解该模板每个占位符的填充来源与格式约束，并结合 SKILL.md 与 github_api.py 复现"GitHub API 取数 → 多轮网络研究 → 按模板成文"的完整链路。

模板在技能中的位置与整体设计

github-deep-research 是一个"针对任意 GitHub 仓库进行多轮深度研究"的技能。其 SKILL.md 声明的研究流程为四轮：

1. Round 1: GitHub API —— 直接执行 scripts/github_api.py 获取仓库结构化数据；
2. Round 2: Discovery —— 3~5 次 web_search 建立概览、识别关键术语与竞品；
3. Round 3: Deep Investigation —— 5~10 次 web_search + web_fetch，深挖架构、事件时间线、社区情绪；
4. Round 4: Deep Dive —— 分析提交历史、issues/PR 演进与贡献者活跃度。

report_template.md 正是这四轮研究的"落地容器"：SKILL.md 明确要求 "Follow template in assets/report_template.md"，并列出模板九大要素（Metadata Block、Executive Summary、Chronological Timeline、Key Analysis、Metrics & Comparisons、Strengths & Weaknesses、Sources、Confidence Assessment、Methodology）。模板的第一行还带有一条 NOTE 指令："Generate this report in user's own language"，即最终报告必须使用用户自己的语言（中文用户得到中文报告）生成。

模板采用 {UPPER_SNAKE} 风格的占位符体系，所有动态内容都收敛为可枚举的槽位，静态章节（如 Methodology 的六步描述、页脚签名）则固化在模板中直接输出。这种"固定骨架 + 变量槽位"的设计，让 Agent 在合成阶段只需做"填槽"而非"创作结构"，从而保证每份报告结构一致、可被程序化解析与横向对比。

逐章拆解：模板的完整结构与占位符

1. 元数据块（Metadata Block）

模板正文开头定义了报告的四个头部字段：

占位符	含义	填充来源
{TITLE}	报告标题（作为 H1）	研究主题
{DATE} / {TIMESTAMP}	研究日期与时间戳	执行时间
{CONFIDENCE_LEVEL}	整体置信度等级	置信度评分（见后文）
{SUBJECT_DESCRIPTION}	研究对象描述	Round 2 Discovery 结论

2. Repository Information：与 API 取数一一映射

模板的 "Repository Information" 小节定义了 13 个仓库元数据字段：{REPOSITORY_NAME}、{REPOSITORY_DESCRIPTION}、{REPOSITORY_URL}、{REPOSITORY_STARS}、{REPOSITORY_FORKS}、{REPOSITORY_OPEN_ISSUES}、{REPOSITORY_LANGUAGES}、{REPOSITORY_LICENSE}、{REPOSITORY_CREATED_AT}、{REPOSITORY_UPDATED_AT}、{REPOSITORY_PUSHED_AT}、{REPOSITORY_TOPICS}。

这些字段并非凭空要求——它们与 github_api.py 中 summarize_repo() 的返回字典几乎逐一对应。summarize_repo() 先调用 get_repo_info() 拿到 full_name、stargazers_count、forks_count、open_issues_count、created_at、pushed_at、topics 等字段，再补充：

• 语言明细：get_languages()（对应 /languages 端点），失败时降级为空字典；
• 贡献者数：get_contributors(owner, repo, limit=100) 的列表长度做近似（注释中说明 GitHub 通过 Link 头返回总数，此处以 100 为上限近似）；
• 最新 Release：get_releases(owner, repo, limit=1) 的首条，取 tag_name、name、published_at。

值得注意的容错设计：summarize_repo() 对 languages、contributor_count、latest_release 三段均包裹 try/except，单项失败不会拖垮整个摘要（贡献者失败时返回字符串 "N/A"），这与模板中字段"缺失也要有占位"的鲁棒性意图一致。此外 get_tree() 在默认分支 main 拉取失败时会自动回退尝试 master，format_tree() 则按路径深度缩进输出目录结构并截断至前 100 行，控制单次工具输出体积。

3. Executive Summary 与强制行内引用

模板在执行摘要节给出了硬性规则：每条来自外部来源的论断后必须紧跟 citation:Title 形式的行内引用，并附示例：

"The project gained 10k stars in 3 months citation:GitHub Stats."

SKILL.md 的 "Citation Examples" 一节用正反两个对照强化了这一规则：带引用的版本为 "Good"，裸陈述的 "The project gained 10,000 stars within 3 months of launch." 被明确标注为 "Bad - Without citations"。同时 Best Practices 第 7 条指出 web_search 返回 {title, url, snippet} 结构，要求"always use the URL field"——即引用链接必须取自搜索结果的 url 字段而非记忆拼写。这一约定保证了报告中的每个可溯源主张都能被下游读者或 Agent 二次验证。

4. Complete Chronological Timeline：分阶段时间线

模板预设了三个 PHASE 块，每个块含 {PHASE_N_NAME}（阶段名）、{PHASE_N_PERIOD}（时间段，作为 H4 标题）与 {PHASE_N_CONTENT}（阶段叙述）。SKILL.md 补充了时间线的可视化增强手段——当内容适合时嵌入 Mermaid Gantt 图：

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

时间线的可信度要求来自 SKILL.md 的最佳实践："Verify dates from commits/PRs - More reliable than articles"，即优先用 GitHub 提交与 PR 的时间戳校验日期，而非依赖文章转述。这正是 Round 4 直接调用 commits、prs、issues 命令的原因。

5. Key Analysis 与 Architecture：Mermaid 三类图

Key Analysis 小节由两个可复制的 ### 标题块（{ANALYSIS_SECTION_1_TITLE} 等）组成，是围绕研究对象自拟主题的深挖章节，且模板再次用 "IMPORTANT" 标注"每个分析点需支持行内引用"。

Architecture / System Overview 节内置了一个 Mermaid flowchart TD 骨架示例（A[Component A] --> B[Component B] ...），配合 {ARCHITECTURE_DESCRIPTION} 文字说明。SKILL.md 中给出了该技能实际会产出的三种 Mermaid 图范式：

• Gantt：项目时间线（如上）；
• Flowchart：如 User → Coordinator → Planner → Research Team → Reporter 的协作架构；
• Pie/Bar：如市场份额对比 pie title Market Share。

6. Metrics & Impact：增长轨迹 + 指标表

该节由两部分构成：

1. Growth Trajectory：一个普通代码块内的 {METRICS_TIMELINE}，用于放 ASCII 化的增长曲线/里程碑序列；
2. Key Metrics：三列表格 | Metric | Value | Assessment |，每行一个指标（{METRIC_1} / {VALUE_1} / {ASSESSMENT_1}……）。"Assessment" 列是关键设计——它要求不止报数，还要给出对该指标含义的定性判断，这与"区分事实与观点"的最佳实践（Distinguish fact vs opinion）相呼应。

7. Comparative Analysis：功能对比表与市场定位

模板给出 Feature | {SUBJECT} | {COMPETITOR_1} | {COMPETITOR_2} 四列功能对比表（每行一个 feature），以及自由文本的 {MARKET_POSITIONING} 小节。竞品列表本身来自 Round 2 Discovery 阶段"Identify main players/competitors"的产出。查询策略（Query Strategy）也围绕对比展开，SKILL.md 给出了逐轮收窄的查询式：

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}"

8. 定性评估节：Strengths & Weaknesses / Key Success Factors

• Strengths（{STRENGTHS}）与 Areas for Improvement（{WEAKNESSES}）成对出现，SKILL.md 称之为 "Balanced assessment"（平衡评估），要求避免单方面吹捧；
• Key Success Factors（{SUCCESS_FACTORS}）提炼项目成功要素；
• 模板要求"Note conflicting info - Don't hide contradictions"——冲突信息要显式记录而不是掩盖。

9. Sources：四分类来源列表

模板把 References 拆成四个子节，每个对应一类来源槽位：

子节	占位符	对应来源优先级（SKILL.md）
Primary Sources	{PRIMARY_SOURCES}	官方文档/仓库（最高权重）
Media Coverage	{MEDIA_SOURCES}	新闻（可核实媒体）
Academic / Technical Sources	{ACADEMIC_SOURCES}	技术博客（Medium、Dev.to 等）
Community Sources	{COMMUNITY_SOURCES}	社区讨论（Reddit、HN）；社媒权重最低，仅用于情绪判断

这个分类直接映射 SKILL.md 的 "Source Prioritization" 五级权重，让读者一眼看出每条结论的"来源质地"。

10. Confidence Assessment：三级置信度分档

模板将全部论断按置信度分三档陈列：

• High Confidence (90%+)：{HIGH_CONFIDENCE_CLAIMS}
• Medium Confidence (70-89%)：{MEDIUM_CONFIDENCE_CLAIMS}
• Lower Confidence (50-69%)：{LOW_CONFIDENCE_CLAIMS}

分档标准来自 SKILL.md 的置信度评分表：

Confidence	判据
High (90%+)	官方文档、GitHub 数据、多个独立来源相互印证
Medium (70-89%)	单一可靠来源、近期文章
Low (50-69%)	社交媒体、未核实说法、过时信息

配合头部元数据中的 {CONFIDENCE_LEVEL} 字段（整份报告的总置信度），形成了"单条主张有分档、整份报告有总评"的双层可信度体系。这是该模板区别于普通 Markdown 模板的核心设计：它把"信息可信度"当作与内容同等重要的一等公民输出。

11. Research Methodology 与页脚

Methodology 节的正文是模板固化内容，列出六步方法：Multi-source web search → GitHub repository analysis（commits/issues/PRs/活动指标）→ Content extraction（官方文档、技术文章、媒体报道）→ Cross-referencing（跨独立来源验证）→ Chronological reconstruction（基于带时间戳数据重建时间线）→ Confidence scoring（按来源可靠性加权）。其下还有三个范围声明槽位：{RESEARCH_DEPTH}（研究深度）、{TIME_SCOPE}（时间范围）、{GEOGRAPHIC_SCOPE}（地域范围），用于交代本次研究的边界条件。

页脚为固定签名块：

**Report Prepared By:** Github Deep Research by DeerFlow
**Date:** {REPORT_DATE}
**Report Version:** 1.0
**Status:** Complete

数据源实现：github_api.py 的十个子命令

模板中 "Repository Information"、时间线与指标节的数字，全部可以由 github_api.py 的 CLI 直接产出。SKILL.md 规定 Round 1 应"直接执行而不 read_file()"，典型用法：

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

脚本 main() 支持的完整命令集（作为第三个位置参数，缺省为 summary）：

命令	底层方法	GitHub 端点	说明
info	get_repo_info()	/repos/{owner}/{repo}	仓库基础信息
readme	get_readme()	/readme（application/vnd.github.raw）	README 原文，缺失时返回 [README not found: ...]
tree	get_tree() + format_tree()	/git/trees/{branch}?recursive=1	目录树文本，深度上限 3 层、输出限 100 行，main 失败回退 master
languages	get_languages()	/languages	各语言字节数
contributors	get_contributors(limit=30)	/contributors	per_page 上限 100
commits	get_recent_commits(limit=50, since=None)	/commits	支持 ISO 日期 since 过滤，服务于时间线重建
issues	get_issues(state="all", limit=30, labels=None)	/issues	支持 open/closed/all 与 label 过滤
prs	get_pull_requests(limit=30)	/pulls	PR 演进分析
releases	get_releases(limit=10)	/releases	发版节奏
summary	summarize_repo()	聚合调用	综合摘要，直接对齐模板 Repository Information 字段

实现层面还有两个值得注意的工程细节：

1. 依赖降级：脚本优先 import requests，失败时回退到内置的 RequestsFallback 类——用 urllib 手工实现了一个最小 requests.get() 接口（含 status_code、text、json()、raise_for_status()），使脚本在无第三方依赖的沙箱环境中依然可用；
2. 认证与限流：main() 从环境变量读取 GITHUB_TOKEN（token = os.getenv("GITHUB_TOKEN")）并注入 Authorization: token ... 头；请求统一带 User-Agent: Deep-Research-Bot/1.0 与 Accept: application/vnd.github.v3+json，超时 30 秒。未认证时 GitHub 匿名限流较严，DeerFlow 的配置文档 CONFIGURATION.md（"GitHub API Token" 一节）明确建议：在 .env.example 中取消注释 # GITHUB_TOKEN=your-github-token 并填入只读 PAT，然后重启 DeerFlow 服务即可提升研究频率上限。

输出规范与成文约束

模板之外，SKILL.md 还规定了报告落盘与排版规则，这些规则共同定义了模板的"最终形态"：

• 命名规则：research_{topic}_{YYYYMMDD}.md；
• 中文排版：中文内容使用全角标点（，。：；！？）；
• 术语首现：技术术语首次出现时附带 Wiki/文档 URL；
• 表格用于指标与对比，代码块用于技术示例，Mermaid 用于架构/时间线/流程；
• 增量合成："Update as you go - Don't wait until end to synthesize"，即每轮研究结束就更新对应章节，而不是最后一次性写作。

仓库中保留了一份真实运行记录可作为端到端参照：演示线程 thread.json 记录了 Agent 分析 bytedance/deer-flow 仓库的完整过程——先读取技能目录与 SKILL.md，再依次执行 github_api.py bytedance deer-flow summary、readme、tree、languages、contributors、commits 等命令，最后读取 assets/report_template.md 作为成文骨架。从该记录可推断，实际执行时 tree 等命令的参数位置与 SKILL.md 的 <owner> <repo> <command> 三参约定一致。

设计要点小结

回看整份模板，它的价值不在于章节本身，而在于三组机制的叠加：

1. 固定骨架 + 槽位变量：13 个仓库字段、三个 PHASE、两组分析节、四分类 Sources 全部预置，Agent 只填槽，报告结构天然一致、可被程序解析；
2. 证据链强制：行内 citation:Title 引用 + 四分类来源列表 + "commits/PRs 时间戳优先于文章"的日期校验规则，使每个论断可回溯；
3. 双层置信度：报告级 {CONFIDENCE_LEVEL} 与论断级三档分档（90%+ / 70-89% / 50-69%）配合来源权重表，把"多可靠"变成报告的一等输出。

配合 github_api.py 的取数能力与 GITHUB_TOKEN 限流配置，这套"模板 + 脚本 + 四轮工作流"的组合，就构成了 DeerFlow 中把一次开放式调研收敛为可验证、可复现、可对比的结构化研究报告的完整方案。