Doramagic：AI助手开源项目专家技能提取引擎架构与实战

1. 项目概述Doramagic一个为AI助手注入项目“灵魂”的提取引擎如果你和我一样每天都在和各种各样的开源项目打交道从FastAPI到Home Assistant从Next.js到LangChain那你肯定也遇到过这样的困境文档写得明明白白代码也跑得起来但你就是搞不懂为什么这个项目要这么设计社区里那些老手们心照不宣的“潜规则”到底是什么以及那些官方文档里永远不会写的“坑”都在哪儿。我们读代码读文档但读不到项目的“灵魂”——那些隐藏在Issue讨论、PR评论和社区对话里的设计哲学、心智模型和血泪教训。Doramagic就是为了解决这个问题而生的。它不是一个代码生成器也不是一个简单的文档总结工具它是一个“灵魂提取器”专门从真实的GitHub仓库里把开源项目的精髓、智慧和那些“只可意会不可言传”的经验提炼成一份份可注入AI助手的“专家顾问包”。简单来说Doramagic让你手边的AI助手比如Claude Code、OpenClaw、Cursor里的Agent瞬间变成一个精通某个特定开源项目的领域专家。你想基于FastAPI快速搭建一个微服务但不确定它的依赖注入最佳实践是什么让Doramagic提取一下FastAPI的“灵魂”你的AI助手就能像FastAPI核心贡献者一样给你建议。你想用Home Assistant做智能家居自动化但被复杂的实体和状态管理搞晕了提取Home Assistant的“灵魂”你的助手就能告诉你社区里大家是怎么避免踩坑的。这个工具的核心设计哲学引用自哆啦A梦Doraemon“不要教用户怎么做——给他们工具。” Doramagic就是那个给你工具的工具它把项目的智慧封装起来让你和你的AI助手直接使用。2. 核心设计思路与架构拆解Doramagic的整个工作流程是一个精心设计的七阶段确定性流水线。理解这个架构你就能明白它为什么能稳定地产出高质量、有深度的“灵魂”包而不是一个简单的网页爬虫加LLM总结。2.1 确定性路由与输入处理Phase A B一切从你输入/dora命令开始。Doramagic内置了一个智能路由器它会根据你的输入内容决定走哪条处理路径。这可不是简单的字符串匹配而是一个基于条件判断的有向无环图DAG。目前支持四条主要路径直接URL路径你直接给了一个GitHub仓库链接比如/dora https://github.com/fastapi/fastapi。这是最直接的路径路由器会跳过项目发现阶段直接进入提取流程。命名项目路径你只给了项目名比如/dora Extract wisdom from Home Assistant。路由器会调用GitHub搜索API找到最匹配的那个仓库然后进行提取。这里有个细节它通常会选择星标最多、最活跃的那个官方仓库以确保提取源的质量。领域探索路径你的问题更宽泛比如/dora What design wisdom can I learn from PKM projects?。这时Doramagic会进入“发现模式”在GitHub上搜索与“个人知识管理”PKM相关的多个高星项目通常是2-3个然后并行地对它们进行“灵魂提取”最后再进行跨项目综合提炼出该领域的通用智慧和不同项目的独特见解。澄清路径如果你的输入过于模糊比如/dora I need something for my team路由器会触发一个澄清对话引导你明确具体需求比如是想要项目管理工具、内部沟通工具还是代码审查工具的智慧包。这个路由机制确保了Doramagic能以最合适的方式响应各种需求而不是僵化地要求用户必须提供标准格式的输入。2.2 并行“灵魂提取”引擎Phase C这是Doramagic最核心、最耗时的阶段。对于每一个需要分析的目标仓库它会启动一个独立的RepoWorker仓库工作器。v13.3.1版本支持最多3个RepoWorker并行运行这大大加快了多项目分析的速度。每个RepoWorker的提取过程远不止是克隆代码和读取README。它是一个深度挖掘的过程我称之为“五维扫描”代码结构扫描分析项目的主要目录结构、核心模块、入口文件理解项目的组织方式和架构模式。它会特别关注__init__.py、main.py、app.py等文件以及像src/、lib/、core/这样的关键目录。文档与注释语义分析不只是读README还包括docs/目录下的所有文档、代码中的docstring、模块级和函数级的注释。LLM会尝试理解每个功能模块的设计意图和约束条件。社区活动挖掘这是提取“灵魂”的关键。RepoWorker会爬取并分析GitHub Issues特别是那些高赞、高评论的Issue、Pull Request的讨论、Discussions板块如果项目启用的话以及Wiki页面。在这里它寻找的是“为什么”为什么这个API要这样设计可能因为Issue #123里讨论了性能问题为什么这个配置项默认值是X可能因为PR #456的评论里社区达成了共识哪些是新手常犯的错误那些被标记为good first issue或bug的Issue里往往有答案。依赖与配置解析查看requirements.txt、pyproject.toml、package.json、docker-compose.yml等文件理解项目的技术栈、版本约束和运行环境要求。这能反映出项目的技术选型哲学和兼容性考量。测试用例意图推断浏览tests/目录下的测试文件。测试用例往往揭示了代码的正确使用方式、边界条件处理以及设计者认为重要的功能点。一个健壮的测试套件本身就是一份宝贵的设计文档。所有这些信息被收集、清洗、结构化后形成针对单个仓库的“原始灵魂数据”。注意这个过程对GitHub API的调用非常密集。如果你要分析的是星标数万的大型项目Issues和PR可能成千上万。Doramagic内部有智能节流和分页机制但一次完整的提取仍然可能消耗大量的API配额如果使用GitHub API Token和时间。对于个人使用建议先从中小型项目开始。2.3 因果推理与综合编译Phase D E单仓库的“原始灵魂数据”还只是原材料。Phase D跨项目综合和Phase E技能编译才是点石成金的过程。如果分析的是单个项目Phase D会跳过。如果是多项目分析领域探索路径Doramagic会启动一个“综合器”。这个综合器的目标不是简单合并事实而是进行因果推理。它会对比不同项目在解决类似问题时的不同方案并尝试推导出背后的原因。例如对比两个Web框架它可能总结出“项目A使用了装饰器定义路由因为其设计哲学是显式优于隐式项目B使用了基于文件系统的路由因为其目标是零配置和快速原型开发。如果你的团队注重代码清晰度和类型安全选择A的模式如果追求开发速度和约定大于配置选择B的模式。”接下来进入Phase E技能编译。这是将结构化的“灵魂数据”和推理出的“智慧”编译成最终可执行的SKILL.md文件。这个文件有严格的格式角色定义开篇明义定义这个技能将把AI助手变成什么样的专家。例如“你是一个精通FastAPI应用架构设计的专家顾问你的知识来源于FastAPI官方仓库的设计哲学和社区积累的最佳实践。”核心设计原则以要点形式列出从项目中提炼出的最高层级的哲学和约束。每一条原则都必须附带溯源引用格式如[SOURCE: CODE:file.py:L42 COMMUNITY:Discussion#847]。这是Doramagic可信度的基石确保每一条建议都不是AI的臆想而是有据可查。心智模型解释用户在使用该项目时应具备的思维框架。比如对于Home Assistant心智模型可能是“一切皆实体状态驱动自动化”。常见陷阱与解决方案列出社区中反复出现的问题及其解决方案。这是最具实操价值的部分。进阶模式与模式语言介绍项目的高级用法、插件体系或扩展模式。同时生成的还有PROVENANCE.md完整的溯源证据链、DSD_REPORT.md欺骗性来源检测报告包含8项自动化检查和CONFIDENCE_STATS.json对每条主张的可信度统计。这一套组合拳确保了输出结果不仅是“智能的”更是“可信的”和“可审计的”。2.4 质量门禁与降级交付Phase F G不是所有提取结果都能直接交付。Phase F是一个严格的“质量门禁”从五个维度对产出的技能包进行打分总分需超过60分满分100才能通过溯源完整性核心主张是否都有明确的代码或社区来源引用逻辑一致性提炼出的设计原则之间是否存在矛盾实操相关性建议是否具体、可操作而非泛泛而谈深度与洞察是否超越了表面文档揭示了深层原因和权衡结构清晰度生成的SKILL.md是否组织良好易于理解如果未通过系统会进入“修订”循环针对得分低的维度进行针对性重写返回Phase E。更关键的是Doramagic设计了四级降级交付机制确保用户无论如何都能得到一些有价值的东西Level 1 (完整交付)通过所有质量检查交付完整的技能包。Level 2 (核心交付)某些深度洞察不足但核心原则和陷阱列表完整。Level 3 (要点交付)仅交付最关键的几条设计原则和陷阱省略详细解释。Level 4 (参考交付)提取过程完全失败如仓库无法访问则交付一个基于项目公开描述生成的基础建议框架并明确标注其局限性。这种设计体现了工程思维优先保证系统的鲁棒性和用户体验即使在部分环节失败时也不让用户空手而归。3. 从安装到实战手把手运行你的第一次“灵魂提取”了解了原理我们来实际操作一下。我将以在Claude Code环境中提取https://github.com/tiangolo/fastapi这个著名Python Web框架的“灵魂”为例展示完整流程和你会遇到的真实细节。3.1 环境准备与一键安装Doramagic的安装已经非常简化。官方推荐的一行命令安装脚本确实能处理大部分情况。但作为资深用户我习惯先了解一下这个脚本在背后做了什么这样出问题时才好排查。# 理论上你只需要这一行 curl -fsSL https://raw.githubusercontent.com/tangweigang-jpg/Doramagic/main/install.sh | bash这个脚本大致会执行以下操作环境检测检查当前是在OpenClaw、Claude Code还是其他兼容的AI助手环境中并确定对应的技能目录路径如~/.claude/skills/。克隆仓库将Doramagic的最新代码克隆到一个临时目录。Python环境检查检查是否安装了Python 3.12以及uv包管理器一个更快的Python包管理工具。如果没有它会尝试引导安装。创建虚拟环境并安装依赖在Doramagic项目目录内使用uv创建虚拟环境并安装核心依赖pydantic。注意它不会帮你安装LLM SDK如anthropic,openai。你需要根据自己使用的模型提供商手动安装。复制技能包将Doramagic/skills/doramagic/目录复制到你的AI助手技能目录下并重命名为dora。配置引导提示你设置API密钥和编辑models.json文件。安装完成后你需要手动完成最关键的两步# 1. 设置你的LLM API密钥以Anthropic为例 export ANTHROPIC_API_KEYsk-ant-xxx...你的真实密钥 # 2. 配置模型文件 # 进入技能目录以Claude Code为例 cd ~/.claude/skills/dora # 复制示例配置文件 cp models.json.example models.json # 编辑models.json声明你可用模型让我们仔细看看这个models.json该怎么配置。它不是简单地写个模型名而是基于能力进行路由。{ 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 }, { model_id: gpt-4-turbo-preview, provider: openai, capabilities: [deep_reasoning, structured_extraction], cost_tier: high, api_key_env: OPENAI_API_KEY } ], routing_preference: lowest_sufficient, fallback_strategy: degrade_and_warn }capabilities是关键。Doramagic在运行的不同阶段如深度推理、结构化提取会检查任务所需的能力然后从available_models中选择一个具备该能力且符合routing_preference的模型。lowest_sufficient意味着在能力满足的前提下选择成本层级cost_tier最低的模型这有助于控制API开销。你不需要拥有所有模型的API。哪怕只配置一个模型如Claude 3.5 Sonnet只要它的能力覆盖全面Doramagic就能正常工作。多模型配置主要是为了灵活性和成本优化。3.2 执行提取与解读输出配置好后重启你的Claude Code会话让助手重新扫描技能目录就可以开始提取了。# 在Claude Code的聊天框中输入 /dora https://github.com/tiangolo/fastapi这时你会看到Doramagic开始工作并输出详细的进度事件。这些事件会被实时记录到~/.doramagic/runs/本次运行ID/run_events.jsonl文件中方便你事后复盘或调试。事件流看起来是这样的{event: phase_start, phase: A, timestamp: ..., input: https://github.com/tiangolo/fastapi} {event: route_determined, route: direct_url, repo_url: https://github.com/tiangolo/fastapi} {event: phase_start, phase: C, timestamp: ..., worker_id: worker_fastapi_0} {event: sub_progress, progress: 0.1, message: Cloning repository...} {event: sub_progress, progress: 0.25, message: Analyzing code structure (main modules)...} {event: sub_progress, progress: 0.4, message: Scanning top 50 issues for design discussions...} ... {event: quality_gate, phase: F, score: 78, passed: true} {event: phase_start, phase: G, message: Packaging delivery bundle...} {event: run_complete, status: success, delivery_path: ~/.doramagic/runs/run_2024.../delivery/}整个过程可能需要几分钟到十几分钟取决于项目大小和网络状况。完成后最重要的输出就在delivery_path指向的目录里。我们打开生成的SKILL.md看看以下是基于真实提取结果的模拟# FastAPI 设计哲学与社区智慧顾问 你是一个精通 FastAPI 框架设计与实践原理的专家顾问你的知识来源于 FastAPI 官方仓库的代码设计、维护者意图以及社区沉淀的集体经验。 ## 核心设计原则 - **声明优于指令**FastAPI 重度依赖 Python 类型提示Type Hints和 Pydantic 模型来声明数据结构和接口框架据此自动处理验证、序列化和文档生成。社区早期尝试绕过 Pydantic 手动验证的 Issue如 #267最终都导向了“拥抱声明式”的结论因为手动处理会破坏 OpenAPI 文档的自动同步和编辑器支持。 [SOURCE: CODE:fastapi/param_functions.py COMMUNITY:Issue#267, Discussion#1482] - **依赖注入作为一等公民**Depends() 不仅是获取数据库会话的工具更是组织业务逻辑、实现可测试性和关注点分离的核心模式。代码库显示任何超过 20 行的路由函数都会被鼓励拆解依赖注入是首选工具。社区常见反模式是将大量逻辑直接写在路由函数内导致难以测试和复用。 [SOURCE: CODE:fastapi/dependencies/utils.py COMMUNITY:Issue#859, Discussion#2105] - **默认安全与性能**FastAPI 默认启用 CORS 中间件不它没有。但它的设计是“显式启用所需组件”。在安全方面它强制要求你思考并配置 CORS、Helmet 等。在性能方面它默认使用 Starlette异步但同步代码也不会被阻塞这源于其清晰的线程池设计。许多“性能问题”的 Issue如 #1124最终发现是用户错误地混用了同步/异步或进行了阻塞调用。 [SOURCE: CODE:fastapi/middleware/cors.py COMMUNITY:Issue#1124, PR#3481] ## 心智模型请求生命周期即数据流转换 当你使用 FastAPI 时应在脑中建立以下数据流转换模型 1. **HTTP 请求到达** - 被路径操作函数接收。 2. **路径参数、查询参数、请求体** - 通过 Pydantic 模型和类型提示被**声明、验证、转换**为 Python 对象。 3. **依赖项执行** - 按声明顺序运行产出子结果如数据库会话、当前用户注入到路径操作函数。 4. **业务逻辑** - 在路径操作函数中操作这些已验证的、类型安全的 Python 对象。 5. **响应返回** - 返回的 Python 对象可以是 Pydantic 模型、字典、列表等被自动序列化为 JSON或其他指定格式并遵循响应模型的定义。 打破这个心智模型是大多数困惑的根源。例如试图在 Pydantic 模型验证前访问原始请求体或试图在依赖项中修改路径参数的值。 ## 社区验证的常见陷阱与解决方案 | 陷阱现象 | 根本原因 | 推荐解决方案 | 溯源 | | :--- | :--- | :--- | :--- | | BackgroundTasks 中任务未执行或顺序错乱 | 误将 BackgroundTasks 实例作为依赖项注入而非在路径操作函数参数中声明。依赖项在请求生命周期中过早初始化。 | 始终在路径操作函数参数中直接声明 background_tasks: BackgroundTasks。如需在依赖项中添加任务应将 BackgroundTasks 实例作为参数传递给依赖函数。 | COMMUNITY: Issue#2987, Issue#3315 | | 全局依赖项dependencies参数中的数据库会话在测试时无法回滚 | 全局依赖项在应用启动时被评估一次其生成的依赖图是固定的。测试夹具如 pytest.fixture无法介入其生命周期。 | 避免在全局 dependencies 中声明有状态的、需要测试隔离的依赖如数据库会话。改为在路由层或路径操作函数层声明。或使用更高级的测试模式覆盖数据库。 | COMMUNITY: Discussion#1448, Issue#954 | | 大型列表响应慢内存占用高 | 直接返回包含数千个 Pydantic 模型的列表序列化过程在内存中一次性完成。 | 对于大型数据集使用分页skip/limit 参数或返回生成器/异步生成器让 Starlette 流式传输响应。 | CODE: fastapi/responses.py COMMUNITY: Issue#1672 | ## 进阶模式构建模块化应用 FastAPI 的 APIRouter 不仅是路由分组工具。社区形成的最佳实践是 - **按领域或模块组织路由**每个领域如 users/, products/拥有自己的路由器、依赖项、模型和异常处理器。 - **使用 prefix 和 tags 进行逻辑分组**这能生成清晰分组的 OpenAPI 文档。 - **依赖项的层级覆盖**可以在路由器级别声明该模块通用的依赖项如该模块所需的特定权限检查它们会应用到该路由器下的所有路径操作并且可以被路径操作级别的依赖项扩展或覆盖。 一个常见的错误模式是在主应用文件中导入所有模型和路由导致循环导入和启动缓慢。正确的模式是每个模块在 __init__.py 中导出其路由器主应用仅导入路由器。这就是Doramagic产出的“灵魂”包。它不再是冰冷的API文档而是充满了“为什么”和“怎么办”的实战指南。PROVENANCE.md文件则详细记录了每一条建议具体引用了哪个代码文件的哪一行或者哪个Issue的哪条评论做到了真正的有理有据。4. 高级用法、问题排查与性能调优掌握了基础用法我们来看看如何更高效地使用Doramagic以及遇到问题时如何解决。4.1 “知识砖块”直接缝合不指定项目的技能生成这是v13.3.1版本的一个强大特性。Doramagic在bricks/目录下预置了278个“知识砖块”覆盖了34个常见框架和领域如Web开发、数据科学、DevOps、前端框架等。这些砖块是过去从大量项目中提取出的精华知识片段。你可以不指定具体的GitHub仓库而是直接描述你想要什么技能Doramagic会从知识库中匹配并“缝合”出你需要的技能包。# 在AI助手对话中直接输入 /dora Build a Telegram bot that monitors crypto prices with alerts /dora Create an email automation skill for inbox triage and auto-reply /dora 帮我做一个每日信息聚合推送的 skill这个过程非常快通常只需2次LLM调用几秒钟内完成意图匹配分析你的描述从50个知识类别中匹配最相关的“砖块”。例如“Telegram bot”会匹配到“异步编程”、“网络请求”、“状态管理”、“错误处理”等砖块“crypto prices”会匹配到“API集成”、“数据抓取”、“定时任务”砖块。砖块缝合将匹配到的砖块结合你的具体需求监控、警报编译成一个连贯的、可执行的SKILL.md。这相当于拥有了一个覆盖常见开发场景的“即时技能工厂”。对于快速原型开发或学习某个领域的最佳实践这比从头分析一个仓库要高效得多。4.2 常见问题与排查实录即使工具设计得再完善在实际操作中也会遇到各种问题。以下是我在多次使用中总结的“避坑指南”问题1执行/dora后无反应或提示“Command not found”。可能原因技能未正确安装到AI助手的技能目录。排查步骤确认你的AI助手类型OpenClaw还是Claude Code。找到正确的技能目录。OpenClaw通常是~/.openclaw/skills/Claude Code是~/.claude/skills/。检查目录下是否存在dora文件夹注意是dora不是doramagic。检查dora文件夹内是否有skill.json和main.py等核心文件。关键步骤重启你的AI助手会话。大多数助手只在启动时扫描一次技能目录安装新技能后必须重启才能识别。问题2提取过程开始后很快失败报错“ModuleNotFoundError: No module named anthropic”。可能原因Python依赖未安装或虚拟环境未激活/未正确配置。解决方案确保你已按照安装步骤在Doramagic项目目录或全局的虚拟环境中安装了所需LLM SDK。cd ~/Doramagic # 假设你克隆在这里 source .venv/bin/activate # 激活虚拟环境 uv pip install anthropic # 安装你需要的SDK检查models.json中配置的api_key_env环境变量名是否正确并且该环境变量已在当前shell中设置。对于Claude Code等集成环境有时需要确保技能运行时能访问到系统的Python环境或特定的虚拟环境。可能需要检查AI助手的插件/技能运行配置。问题3提取过程非常缓慢或中途卡住。可能原因网络问题克隆大型仓库或调用GitHub API速度慢。仓库过大目标仓库的Issues、PR数量极多如超过5000个。LLM API速率限制你使用的LLM提供商如OpenAI、Anthropic有每分钟/每天的请求限制。优化策略使用镜像或代理如果克隆仓库慢可以尝试配置git使用镜像源。但注意Doramagic后续仍需访问GitHub API网络问题需综合解决。限制提取深度目前Doramagic没有提供直接的UI参数来限制扫描的Issues数量。但你可以通过分叉Fork仓库并手动清理的方式来间接实现。先Fork目标仓库删除旧的、已关闭的Issues/PR保留最近一年或最热门的几百个然后让Doramagic分析你的Fork。这能大幅减少数据量。使用更快的模型在models.json中为structured_extraction这类数据密集型但推理要求相对较低的任务配置一个cost_tier为low且速度快的模型如果可用。查看日志run_events.jsonl日志文件会记录每个阶段的耗时。找到瓶颈阶段。如果是“Scanning issues...”阶段耗时过长那可能就是仓库太大。问题4生成的SKILL.md感觉比较肤浅像通用总结没有“灵魂”。可能原因项目本身社区不活跃如果项目的Issues和Discussions很少Doramagic就缺乏提取“社区智慧”的原料。LLM能力或提示词限制用于提取和综合的LLM可能未能充分理解代码中的精妙之处。质量门禁分数偏低生成的技能包可能只是“Level 2”或“Level 3”的降级交付。应对方法检查DELIVERY_LEVEL文件如果存在或CONFIDENCE_STATS.json了解本次交付的等级和置信度分布。尝试更换models.json中capabilities包含deep_reasoning的更强模型如Claude 3.5 Sonnet。如果项目社区不活跃可以尝试使用“领域探索”路径让它同时分析2-3个同类型项目通过对比产生更深刻的见解。4.3 性能调优与自定义配置对于高级用户Doramagic提供了一些隐藏的配置选项通常通过环境变量或配置文件可以进行调优控制并行度环境变量DORA_MAX_WORKERS可以设置并行运行的RepoWorker数量默认3。如果你的机器CPU核心多、网络带宽足可以适当调高以加速多项目分析。但注意每个Worker都会消耗内存和LLM API调用。调整GitHub API速率如果遇到GitHub API速率限制可以设置GITHUB_TOKEN环境变量使用个人访问令牌以获得更高的请求限额。在scripts/目录下可能有一些辅助脚本用于处理分页和缓存。自定义知识砖块你可以向bricks/目录添加自己的知识砖块。砖块是结构化的YAML或JSON文件描述了某个特定模式、陷阱或最佳实践。当你使用“直接缝合”功能时Doramagic也会优先使用你的自定义砖块。这是构建团队内部知识库的绝佳方式。最后别忘了Doramagic本身也是一个开源项目。它的代码结构清晰核心逻辑在packages/目录下。如果你对提取流程、提示词工程或质量评估算法有改进想法完全可以阅读源码甚至提交PR。项目采用MIT协议鼓励社区共同完善这个“灵魂提取”的工具。毕竟它的终极目标是让所有开发者和他们的AI助手都能更轻松地汲取开源世界的集体智慧。