Doramagic：从GitHub仓库提取项目灵魂，让AI助手成为领域专家

1. 项目概述从代码到灵魂的提取器如果你用过 GitHub Copilot 或者 Claude Code肯定有过这样的体验你让 AI 帮你写一个功能它确实能生成代码但代码背后的设计哲学、社区里踩过的坑、那些文档里永远不会写的“潜规则”AI 一概不知。结果就是代码能跑但总感觉差点意思不够“地道”甚至可能埋下一些只有老手才知道的雷。Doramagic 就是为了解决这个问题而生的。它不是一个代码生成器而是一个“项目灵魂提取器”。它的核心设计哲学引用自哆啦A梦的创造者藤子·F·不二雄的一句话“不要教用户该做什么——给他们工具。” Doramagic 就是这个工具它深入一个开源项目的“灵魂”——不仅仅是代码做了什么更是为什么要这样设计以及那些来之不易的、从未出现在官方文档中的社区智慧。简单来说你把一个 GitHub 仓库的链接扔给 Doramagic它会运行一个七阶段的提取流水线最终产出一个“技能包”Skill Bundle。这个技能包能让你的 AI 助手如 Claude Code、OpenClaw瞬间变成该项目的领域专家在后续的对话和编码中能基于项目的真实设计理念和社区经验来提供建议而不仅仅是基于通用的编程知识。注意Doramagic 是一个必须安装并运行的工具。仅仅阅读它的 README 是无法获得其功能的。你必须将其作为一个技能Skill安装到你的 AI 助手环境中并通过/dora命令来调用它。2. 核心设计思路为什么是“灵魂提取”在深入安装和使用之前我们先拆解一下 Doramagic 的设计思路。理解这个你才能明白它和普通的代码分析工具或 RAG检索增强生成有何本质区别。2.1 传统代码分析的局限性传统的静态代码分析如ast解析、依赖分析或者简单的文档检索能告诉你“有什么”函数、类、API和“怎么用”参数、返回值。但它们回答不了更深层的问题设计取舍为什么这个项目选择 A 方案而不是更流行的 B 方案背后的性能、兼容性或哲学考量是什么社区共识在项目的 Issue 和 Discussion 里哪些是反复被提及的“最佳实践”哪些是新手常踩的“坑”演进脉络某个核心模块经历了怎样的重构每次重构解决了什么历史遗留问题这些信息往往散落在代码注释、提交信息Commit Messages、拉取请求Pull Request的讨论、已关闭的 Issue 以及 Wiki 页面中。它们共同构成了一个项目的“集体智慧”或“灵魂”。2.2. Doramagic 的七阶段提取流水线Doramagic 采用了一个精心设计的、确定性的七阶段流水线来系统化地完成“灵魂提取”。这个流程不是简单的“抓取-总结”而是一个多层次的推理和合成过程。第一阶段输入路由Input Router这是整个流程的入口。Doramagic 支持四种输入类型并会进行确定性路由直接 URL如/dora https://github.com/fastapi/fastapi。这是最直接的路径跳过发现阶段直接进入提取。命名项目如/dora Extract wisdom from Home Assistant。系统会先去 GitHub 搜索最匹配的项目然后进行提取。领域探索如/dora What design wisdom can I learn from PKM projects?。这会触发多项目发现和交叉提取适合你想了解某个领域如个人知识管理的通用智慧。澄清对话如/dora I need something for my team。当输入意图模糊时Doramagic 会先与你进行几轮问答明确需求后再选择上述路径之一。这种路由机制确保了无论用户以何种方式发起请求都能被引导至最合适的处理流程。第二阶段GitHub 发现GitHub Discovery对于非直接 URL 的输入Doramagic 会调用 GitHub API根据项目名或领域描述结合星标数、活跃度、相关性等因素智能地筛选出最值得分析的目标仓库。它可能选择一个也可能选择多个在领域探索模式下进行并行分析。第三阶段并行灵魂提取Fan-out Soul Extraction这是最核心的耗时阶段。Doramagic 会启动最多 3 个独立的“仓库工人”RepoWorker对选定的仓库进行并行、隔离的深度提取。每个工人会克隆仓库获取完整的代码和历史。多源信息采集不仅分析源代码.py,.js,.md等还会爬取README、CONTRIBUTING.md、CHANGELOG以及最重要的——GitHub Issues、Discussions 和 Pull Requests。结构化提取利用 LLM大语言模型的能力从这些非结构化的文本中提取出“设计原则”、“常见陷阱”、“性能考量”、“架构决策原因”等结构化的知识片段。每个片段都会严格标注来源如CODE:utils/logger.py:L15或COMMUNITY:Issue#1234。第四阶段跨项目合成Cross-Project Synthesis当分析多个相关项目时例如分析多个 Markdown 编辑器Doramagic 不会简单地把报告堆在一起。它会进行因果推理和对比分析生成诸如“项目 A 采用 Electron 是因为看重跨平台一致性而项目 B 选择原生开发是为了追求极致的启动速度和内存效率”这样的洞察。这比罗列事实清单有价值得多。第五阶段技能编译Skill Compilation将提取和合成后的结构化知识编译成 AI 助手能理解和执行的“技能”格式。核心产出是一个SKILL.md文件它定义了该领域专家的行为模式、知识边界和对话风格。第六阶段质量门禁Quality GateDoramagic 设有一个严格的五维度、60分阈值质量检查体系。五个维度可能包括信息完整性是否覆盖核心模块、来源可信度是否主要来自官方文档和核心贡献者的讨论、洞察深度是否包含“为什么”、实用性是否包含可操作的技巧、结构清晰度。如果总分低于60分系统会自动触发修订流程回到第五阶段进行知识增强和重组直到达标。第七阶段打包与交付Package Deliver将通过的技能包包含SKILL.md、来源证明PROVENANCE.md等文件打包输出到指定目录供用户安装使用。这个流水线确保了最终产出的技能包不是 AI 的随意发挥而是基于真实项目数据、经过多重验证的、高质量的领域知识结晶。3. 安装与配置详解理解了原理我们来动手安装。Doramagic 提供了多种安装方式以适应不同的 AI 助手环境。3.1 一键安装推荐给大多数用户这是最快的方式脚本会自动检测你的环境OpenClaw 或 Claude Code并进行相应配置。curl -fsSL https://raw.githubusercontent.com/tangweigang-jpg/Doramagic/main/install.sh | bash执行后发生了什么脚本会检查你的系统是否安装了python3要求 3.12和git。它会探测你的 AI 助手环境检查~/.openclaw或~/.claude目录。创建一个 Python 虚拟环境例如使用uv或venv并安装核心依赖pydantic。将 Doramagic 的技能目录复制到你的 AI 助手的技能扫描路径下。提示你设置 API Key 并重启会话。安装完成后你需要设置 LLM 的 API Key至少一个。例如使用 Anthropic 的 Claudeexport ANTHROPIC_API_KEYsk-ant-xxx...你的真实Key...然后完全关闭并重新打开你的终端或 IDE如果 Claude Code 运行在其中以确保 AI 助手重新扫描技能目录。现在你就可以在 AI 助手的聊天框中输入/dora命令了。3.2 直接“积木缝合”v13.3.1 新特性这是 Doramagic 一个非常强大的功能。你甚至不需要指定一个具体的 GitHub 项目。系统内置了一个覆盖50 个知识领域的“知识积木”库这些领域与 ClawHub 技能市场的需求高度对齐。你可以直接描述你想要的功能Doramagic 会从知识库中匹配相关的“积木”快速缝合出一个技能/dora Build a Telegram bot that monitors crypto prices with alerts 帮我构建一个监控加密货币价格并发送警报的 Telegram 机器人技能 /dora Create an email automation skill for inbox triage and auto-reply 创建一个用于收件箱分类和自动回复的邮件自动化技能 /dora 帮我做一个每日信息聚合推送的 skill 中文指令同样支持这个过程仅需两次 LLM 调用几秒钟内即可完成极大地扩展了 Doramagic 的适用场景。你可以把它看作一个“技能生成器”的快速原型工具。3.3 手动安装适合进阶用户和调试如果你想更精细地控制安装过程或者遇到一键安装脚本的问题可以遵循手动步骤。第一步克隆仓库git clone https://github.com/tangweigang-jpg/Doramagic.git ~/Doramagic cd ~/Doramagic第二步安装 Python 依赖强烈建议在虚拟环境中进行以避免污染系统环境。# 使用 uv更快更现代推荐 uv venv source .venv/bin/activate # Linux/macOS # .venv\Scripts\activate # Windows uv pip install pydantic # 根据你使用的 LLM 提供商安装对应的 SDK uv pip install anthropic # 如果用 Claude # uv pip install openai # 如果用 GPT # uv pip install google-genai # 如果用 Gemini第三步安装为技能你需要将skills/doramagic目录复制到你的 AI 助手能识别的技能目录下。关键是要使用-rL参数这能确保复制符号链接指向的实际内容。对于 OpenClawmkdir -p ~/.openclaw/skills cp -rL ~/Doramagic/skills/doramagic ~/.openclaw/skills/dora对于 Claude Codemkdir -p ~/.claude/skills cp -rL ~/Doramagic/skills/doramagic ~/.claude/skills/dora第四步配置模型模型配置文件位于你刚复制的技能目录内。你需要创建一个副本并进行编辑。# 对于 OpenClaw cp ~/.openclaw/skills/dora/models.json.example ~/.openclaw/skills/dora/models.json # 对于 Claude Code cp ~/.claude/skills/dora/models.json.example ~/.claude/skills/dora/models.json用文本编辑器打开models.json。它的核心是按能力而非模型名称来路由任务。以下是一个配置 Claude Sonnet 的示例{ available_models: [ { model_id: claude-3-5-sonnet-20241022, provider: anthropic, capabilities: [deep_reasoning, structured_extraction, tool_calling], cost_tier: medium, api_key_env: ANTHROPIC_API_KEY } ], routing_preference: lowest_sufficient, fallback_strategy: degrade_and_warn }capabilities声明该模型具备哪些能力。Doramagic 会根据任务类型如深度推理、结构化提取选择最合适的模型。routing_preference:lowest_sufficient表示在满足能力要求的前提下优先选择成本最低的模型。fallback_strategy:degrade_and_warn表示当首选模型失败时会降级使用其他可用模型并给出警告确保任务总能完成。一个模型就足够了。配置多个模型可以提供更好的路由灵活性和成本控制。第五步设置 API 密钥并重启在终端中导出你的 API 密钥export ANTHROPIC_API_KEYsk-ant-xxx... # 如果配置了其他模型也需要导出对应的 KEY # export OPENAI_API_KEYsk-...最后重启你的 AI 助手会话让技能加载生效。3.4 安装后的目录结构与清理安装完成后你的文件系统大致如下~/.openclaw/skills/ (或 ~/.claude/skills/) └── dora/ # 这就是安装的技能目录 ├── SKILL.md # Doramagic 自身的技能定义文件 ├── models.json # 你的模型配置文件 ├── packages/ # 核心模块已包含 ├── bricks/ # 知识积木库已包含 └── ... # 其他运行时脚本和配置重要提示一旦使用cp -rL完成复制原始的克隆仓库~/Doramagic就可以安全删除了。因为-L参数已经将符号链接解引用所有必需的文件都已复制到技能目录中。你只需要确保 Python 虚拟环境及其中安装的pydantic和 LLM SDK保持可用。4. 使用实战与输出解析安装配置好后我们来实际使用一下并看看它能产出什么。4.1 基本使用示例假设我们想让我们 AI 助手深刻理解 FastAPI 这个框架的设计哲学以便在后续开发中给出更“地道”的建议。在 AI 助手的聊天框中输入/dora https://github.com/tiangolo/fastapi或者如果你不确定仓库地址/dora Extract wisdom from the FastAPI web frameworkDoramagic 会开始运行。你会在终端或 AI 助手的日志中看到类似这样的进度事件得益于其结构化日志系统{event: phase_start, phase: B, timestamp: ..., repo_count: 1} {event: sub_progress, message: Cloning repository..., progress: 5} {event: sub_progress, message: Analyzing main.py and router patterns..., progress: 30} ...整个提取过程可能需要几分钟到十几分钟取决于仓库大小和网络状况。4.2 输出产物详解运行成功后Doramagic 不会在聊天框里输出大段文本。相反它会在本地生成一个技能包。默认路径通常在~/.doramagic/runs/本次运行ID/delivery/下。这个交付物目录里必定包含以下四个文件缺一不可文件用途为什么重要SKILL.md可执行的技能定义。这是核心告诉 AI 助手如何扮演该领域的专家。这是你最终要安装和使用的东西。它定义了专家的行为、知识范围和对话方式。PROVENANCE.md证据溯源文件。每一个在SKILL.md中出现的论断都链接回其原始出处代码行、Issue 编号等。保证了知识的可信度。你可以随时查验任何一条建议的来源避免 AI “幻觉”。DSD_REPORT.md欺骗性来源检测报告。包含 8 项自动化检查的结果用于识别可能伪造或误导性的信息源。增加了安全层尤其是在分析来源复杂的项目时能过滤掉不可靠的信息。CONFIDENCE_STATS.json置信度统计。以 JSON 格式记录了每条提取出的知识被赋予的置信度等级如高、中、低的分布情况。让你对生成技能的整体可靠性有一个量化的把握。让我们看看一个真实的SKILL.md开头长什么样以分析一个健身应用wger为例# Fitness Tracker Advisor You are an expert advisor on fitness tracking application design, trained on the design philosophy and community wisdom of wger. ## Core Design Principles - **Simplicity over features**: wger deliberately limits dashboard widgets to 3 per view. Community learned that 5 widgets caused 40% of users to stop logging workouts (GitHub Discussion #847). [SOURCE: CODE:dashboard/views.py:L42 COMMUNITY:Discussion#847] - **Data ownership is non-negotiable**: All user data is exportable in open formats (JSON, CSV). The project rejected cloud-sync features that would lock data in, as per founding principle stated in README since v1.0. [SOURCE: README:L15-L20 COMMUNITY:Issue#204] ## Common Pitfalls Anti-Patterns - **DO NOT** create complex workout templates with nested supersets initially. User analytics show 80% of new users abandon templates with 3 steps. Start simple, then guide users to complexity. [SOURCE: COMMUNITY:Issue#561 Analytics commit:a1b2c3d] - **AVOID** real-time sync during exercise entry. wgers 2-second delayed save reduced UI freeze complaints by 70% (Issue #332). Sync in background. [SOURCE: CODE:models/workout.py:L120-L135 COMMUNITY:Issue#332]看到区别了吗这不仅仅是 API 列表。它告诉你设计原则及其原因为什么限制 3 个小组件因为数据表明多了用户会流失。具体的反模式不要一开始就做复杂的嵌套模板用户会跑。数据支撑每一个观点都有明确的、可追溯的来源。可操作的“行话”使用了DO NOT,AVOID等强指导性语言直接塑造 AI 的回复风格。这样的技能被注入 AI 助手后当你问“如何设计一个健身应用的仪表盘”时AI 的回答就会基于wger的真实经验而不再是泛泛而谈。4.3 安装生成的技能生成技能包后你需要手动将其安装到你的 AI 助手环境中。假设运行 ID 是run_20231027_112233# 对于 OpenClaw cp -r ~/.doramagic/runs/run_20231027_112233/delivery/ ~/.openclaw/skills/fitness_tracker_advisor # 对于 Claude Code cp -r ~/.doramagic/runs/run_20231027_112233/delivery/ ~/.claude/skills/fitness_tracker_advisor重启你的 AI 助手现在你就可以像调用其他技能一样调用这个新生成的fitness_tracker_advisor专家了。5. 高级特性与架构深度解析Doramagic 不仅仅是一个脚本它有一个深思熟虑的架构来保证提取过程的高效、可靠和可观测。5.1 确定性路由与有向无环图DAG输入路由阶段本质上是一个 DAG有向无环图。四种输入类型是入口节点通过条件判断如“输入是否是 URL”、“是否包含‘learn from’关键词”流向不同的处理分支。这种设计使得流程逻辑清晰易于调试和扩展。例如未来要增加对 GitLab 或 Bitbucket 的支持只需在“发现”阶段增加新的节点和边即可。5.2 并行提取与隔离“Fan-out Extraction”意味着可以同时分析最多 3 个仓库。每个RepoWorker在独立的进程中运行拥有自己的临时工作目录和 LLM 会话。这带来了两个好处性能提升对于多项目探索提取时间近乎线性减少。故障隔离一个仓库的分析过程崩溃例如遇到一个超大的二进制文件不会影响其他仓库的分析。5.3 五维度质量门禁这是保证产出质量的核心机制。五个维度具体名称可能随版本演进的评估大致如下覆盖度是否涵盖了仓库的核心模块、主要文档和活跃的讨论区深度提取的见解是否超越了表面功能触及了设计决策和权衡实用性知识是否可操作能否直接指导开发或决策一致性不同来源的信息代码 vs Issue是否相互印证没有矛盾结构化产出的SKILL.md是否遵循了清晰的模板便于 AI 解析和执行每个维度有子项总分 60 分是及格线。未达标的技能包会被送回“编译”阶段进行修订系统会尝试补充缺失维度的信息。5.4 四级降级交付策略“4-Tier Degraded Delivery”体现了鲁棒性设计。即使用户的网络、API 或目标仓库出现问题Doramagic 也力求提供某种形式的有用输出而不是直接失败。四级可能包括Tier 1 (完整交付)所有阶段成功通过质量门禁。Tier 2 (部分交付)核心提取完成但某些边缘模块或历史 Issue 分析失败。交付的技能会包含警告说明。Tier 3 (基础交付)仅能分析 README 和基础代码结构。产出是一个基础的功能概述技能。Tier 4 (应急交付)连仓库都无法克隆。Doramagic 会从其内置的“知识积木”库中匹配一个最相关的通用技能交付给用户。这个策略确保了用户体验的连续性始终“有东西可用”。5.5 事件总线与结构化日志所有内部事件阶段开始/结束、子进度、错误、决策点都通过一个中央EventBus发布。同时这些事件会以 JSON Lines (.jsonl) 格式写入run_events.jsonl文件。这为调试和监控提供了极大的便利。你可以像用tail -f看日志一样实时观察提取流程到了哪一步或者事后用jq工具分析运行情况。# 查看最近一次运行的所有阶段事件 jq select(.event phase_start or .event phase_end) run_events.jsonl # 查看所有错误 jq select(.event error) run_events.jsonl6. 常见问题与故障排查在实际使用中你可能会遇到一些问题。以下是一些常见情况及其解决方法。6.1 安装与启动问题问题执行/dora命令无反应或提示“命令未找到”。检查技能目录确认dora技能目录是否被正确复制到了~/.openclaw/skills/或~/.claude/skills/下。检查权限确保技能目录及其内部文件有可执行权限尤其是里面的 Python 脚本。重启会话这是最常见的原因。安装技能后必须完全重启你的 AI 助手关闭终端/IDE再重新打开它才会重新扫描和加载技能。查看宿主日志OpenClaw 或 Claude Code 通常有日志输出。查看是否有关于加载dora技能时的错误信息。问题运行时报错ModuleNotFoundError: No module named pydantic。虚拟环境未激活确保你是在安装依赖的 Python 虚拟环境中运行 AI 助手。有些 IDE 需要手动配置解释器路径。依赖未安装回到 Doramagic 克隆目录或技能目录重新激活虚拟环境并运行uv pip install pydantic anthropic或你需要的 SDK。6.2 API 与网络问题问题提取过程卡在“Cloning repository...”或“Fetching issues...”很久然后超时。网络连接检查是否能正常访问 GitHub。对于大型仓库克隆可能需要时间。GitHub API 限速如果你未提供 GitHub Token会使用匿名 API速率限制很低。建议在环境变量中设置GITHUB_TOKENexport GITHUB_TOKENghp_xxx...你的个人访问令牌...可以在 GitHub 设置中生成一个只需public_repo只读权限即可。问题LLM 调用失败提示Invalid API Key或Rate limit exceeded。检查 API Key确认ANTHROPIC_API_KEY等环境变量已正确设置且未过期。检查模型配置确认models.json中的model_id和provider与你提供的 Key 匹配。额度或频次限制检查你的 LLM 提供商账户是否有足够的额度或是否触发了每分钟调用次数限制。6.3 输出内容问题问题输出的SKILL.md内容看起来很空洞像 AI 自己编的没有具体的源码引用。这很可能意味着 Doramagic 没有真正运行有些 AI 助手在收到/dora指令时可能会直接根据上下文即 Doramagic 自己的 README来“幻想”一个回答。请务必检查是否有进度日志输出是否在~/.doramagic/runs/下生成了新的运行目录生成的PROVENANCE.md文件是否为空或不存在确保命令格式正确对于直接分析仓库务必使用完整的 URL如/dora https://github.com/...。问题质量门禁一直不通过反复在“修订”。目标仓库信息量太少一些非常小、不活跃或文档极差的项目可能无法提取出足够高质量的知识。尝试换一个更成熟、社区活跃的项目。调整质量阈值高级在技能目录的配置中可能有关闭或调整质量门禁的选项请参考INSTALL.md。但这不是推荐做法会降低产出技能的质量。6.4 性能与成本优化问题分析一个大仓库如 Linux Kernel耗时太长费用太高。限制分析范围Doramagic 可能支持通过参数限制分析深度例如只分析最近一年的 Issue或只关注核心目录。查看高级用法文档。使用更经济的模型在models.json中配置多个模型并将成本较低的模型如claude-haiku用于“初步提取”这类能力将昂贵模型如claude-sonnet仅用于“深度推理”和“合成”阶段。利用缓存Doramagic 可能会缓存已克隆的仓库和提取的中间结果。重复分析同一仓库时速度会快很多。6.5 技能使用问题问题安装了生成的技能但 AI 助手好像没有变得更“专家”。技能触发生成的技能通常有特定的触发词或指令。查看SKILL.md的开头部分看它定义的专家角色名称是什么如“Fitness Tracker Advisor”。你可能需要在对话中明确 这个角色或使用其预设的指令。上下文限制AI 助手有上下文长度限制。如果生成的SKILL.md非常长可能无法全部放入上下文。这时需要技能本身设计精良能够摘要核心原则。Doramagic 产出的技能在这方面通常有优化。7. 开发与贡献指南如果你对 Doramagic 本身感兴趣想深入研究或贡献代码这里有一些指引。7.1 项目结构概览Doramagic/ ├── packages/ # 核心功能模块包 │ ├── contracts/ # 数据模型和接口定义 │ ├── controller/ # 七阶段流水线的主控制器 │ ├── executors/ # 具体执行单元如 RepoWorker │ ├── extraction/ # 灵魂提取的核心逻辑 │ └── synthesis/ # 跨项目知识合成 ├── bricks/ # 知识积木库50个领域 ├── skills/doramagic/ # 自包含的技能包这就是被安装的部分 ├── tests/ # 单元测试和端到端测试 └── scripts/ # 构建、发布等实用脚本7.2 搭建开发环境git clone https://github.com/tangweigang-jpg/Doramagic.git cd Doramagic uv venv source .venv/bin/activate # 安装开发依赖包括测试框架等 uv pip install -e .[dev] # 运行测试套件 make test7.3 如何贡献阅读CONTRIBUTING.md里面详细说明了代码风格、提交信息规范、测试要求等。从 Issue 开始查看项目的 Issues 页面寻找标有good first issue或help wanted的任务。扩展知识积木bricks/目录是社区贡献的绝佳场所。你可以为你熟悉的领域例如bricks/web_scraping/添加新的知识积木丰富直接缝合功能的基础材料。改进提取器packages/extraction/下的模块负责从原始数据中提取知识。你可以尝试改进针对特定文件类型如Dockerfile,docker-compose.yml或特定平台如 GitLab的提取逻辑。编写测试高测试覆盖率是项目稳健的基石。为新增的功能编写单元测试或集成测试是极其宝贵的贡献。7.4 调试技巧使用详细日志在运行 Doramagic 前设置环境变量LOG_LEVELDEBUG可以获取最详细的日志输出。分析事件流运行结束后仔细查看run_events.jsonl文件可以精确还原执行流程定位在哪个阶段、哪一步出现了问题。隔离测试packages/下的许多模块是相对独立的。你可以直接编写小脚本导入并测试某个提取器或合成器的功能而不必运行整个流水线。我个人在深度使用 Doramagic 的过程中最大的体会是它改变了我们与 AI 协作的范式。以前我们是“用户-工具”的关系我们给 AI 指令它返回结果。现在通过 Doramagic我们可以让 AI 先成为某个领域的“学徒”汲取人类开源社区数年甚至数十年的集体智慧然后再以“专家”的身份来协助我们。这种“先学习后工作”的模式对于处理复杂、有深厚背景知识的任务比如架构设计、技术选型、规避历史错误有着不可估量的价值。它让 AI 的“智能”真正地扎根于人类实践过的、可验证的土壤之中。