很多 AI 编码 Agent 的问题不是“不知道”，而是太容易把“读到的信息”当成“已经验证的事实”。

Doramagic 要做的不是再整理一批 prompt，也不是把开源 README 改写成文章。它更像一种可以被 AI 宿主加载的能力资源包：把来源、宿主指令、启动任务、坑点、验收脚本、边界声明、人工接管点、测试日志和反馈路径放在一起，让 Agent 不只是生成代码，还知道自己什么时候应该验证、什么时候应该停止、什么时候应该把失败反馈回来。

这篇文章用 CSDN 更适合的技术拆解方式，说明 Doramagic 的核心形态。

1. 为什么单个 prompt 不够

假设你让一个 AI Agent 完成这样的任务：

帮我接入一个向量数据库，并做一个最小 RAG 检索。

一个普通 Agent 很可能会直接生成：

安装命令
-> client 初始化
-> collection 创建
-> document 写入
-> query 调用
-> RAG 代码骨架

这看起来很完整，但还有一个关键问题：

它生成得出来，不代表它验证过。

真正危险的不是代码少了几行，而是 Agent 在没有证据的情况下写出：

已接入完成。
查询结果可信。
环境可用。

这就是 Doramagic 要解决的问题。

2. Doramagic 资源包的完整链路

一个 Doramagic pack 不是单点技巧。它至少应该包含这条能力链路：

source map
-> host instructions
-> prompt preview
-> pitfall log
-> smoke check / eval
-> boundary card
-> human manual
-> test log
-> feedback path

每一环都有明确作用。

source map

说明这个能力来自哪里，上游项目是谁，Doramagic pack 和上游是什么关系。

它防止 Agent 把独立整理的资源包误说成官方产物。

host instructions

告诉不同 AI 宿主应该如何加载和执行，例如 AGENTS.md、CLAUDE.md、GEMINI.md 或其他宿主说明。

它约束 Agent 的行动顺序，而不是只给它一段背景材料。

prompt preview

给人和 Agent 一个最小启动任务。

它不是最终能力，而是进入能力包的入口。

pitfall log

记录已知错误路径。

它不是“经验贴”，而是把容易出错的路径变成停止条件。

smoke check / eval

要求 Agent 用最小可执行检查证明关键链路真的可用。

没有执行证据，就不能写成已验证结论。

boundary card

列出不能夸大的部分，例如权限、版本、宿主兼容性、license、运行环境、真实测试覆盖。

human manual

告诉人类什么时候应该接管。

这避免 Agent 在失败时继续猜。

test log

暴露资源包自己已经验证了什么、没有验证什么、当前是否 GO、HOLD 或 NO-GO。

feedback path

把失败、修复、平台反馈、用户反馈重新进入资源包迭代。

这一步决定它是不是能持续进步，而不是一次性文档。

3. 三个例子：同一个方法，不同项目

例子一：openai-agents-python

对 Agent 来说，关键不是“能不能写一个 agent demo”。

关键是：

当前包名、仓库、版本、运行入口是否对应？
handoff、tool、trace、guardrail 是否有最小验收？
失败路径是否能被明确记录？

如果这些没有验证，Agent 只能写：

待验证。

不能写：

已经完成 OpenAI Agents SDK 能力接入。

例子二：Chroma

对 Chroma 这类向量数据库来说，关键不是“写出几行 query 代码”。

关键是把链路拆清楚：

install
-> client
-> collection
-> write
-> query
-> result check
-> optional persistence

一个最小验收不是“README 里有示例”，而是 Agent 至少能说明：

我实际验证了哪一步？
哪一步没有验证？
query 返回的 ids/documents 是否符合预期？
如果没有运行证据，结论是否保持为待验证？

例子三：chrome-devtools-mcp

对浏览器自动化和调试能力来说，关键不是“打开浏览器看了一眼”。

关键是证据链：

console
-> network
-> runtime error
-> DOM state
-> trace or reproduction step
-> fix
-> re-check

如果没有 console/network/runtime 证据，Agent 不应该直接说：

浏览器问题已经修复。

它最多只能说：

已提出一个可能修复方向，仍缺少浏览器侧证据。

4. Doramagic 和普通技术文章的区别

普通技术文章通常回答：

这个工具怎么用？

Doramagic pack 要回答：

AI Agent 应该如何可靠地使用这个工具？
它应该先查什么？
先验证什么？
遇到什么情况必须停止？
哪些结论不能声称？
失败后如何回到资源包改进？

所以文章只是外部表达形式。

真正的产品是可携带、可加载、可验收、可反馈的能力资产。

5. 一个合格 pack 的最低标准

如果一个资源包只包含：

README 摘要
常用命令
一个 prompt

它不够。

一个更接近 Doramagic 标准的资源包，至少应该能回答：

1. 上游项目是什么？
2. 资源包和上游是什么关系？
3. Agent 加载哪个 host instruction？
4. 第一个任务如何启动？
5. 已知 pitfall 是什么？
6. 最小 smoke check 是什么？
7. 哪些结论必须保持 HOLD 或 NO-GO？
8. 人类什么时候接管？
9. 测试日志证明了什么？
10. 失败反馈如何进入下一轮资源包改进？

这些内容一起出现，才像一个 AI Agent 能力资源包。

6. 为什么要明确 GO / HOLD / NO-GO

Doramagic 不应该承诺：

这个资源包一定能让 Agent 成功。
这个平台一定不会限制账号。
这个项目一定已经验证完成。

更稳妥的表达是：

GO：当前证据足够执行下一步。
HOLD：缺少关键信息，暂不扩大结论。
NO-GO：当前不应执行或发布。

这不是把事情复杂化，而是避免 Agent 把“看过资料”伪装成“完成能力”。

7. 对开发者的实际价值

如果你在团队里使用 AI 编码工具，Doramagic 这种资源包的价值不是多给 Agent 一篇文章。

它的价值是减少这些问题：

Agent 没验证就声称完成。
Agent 把上游 README 当成当前环境事实。
Agent 不区分安装成功、调用成功、验收成功。
Agent 遇到失败继续猜。
Agent 修复一次后没有留下可复用的经验。

换句话说，它把 AI Agent 的工作从：

生成答案

推进到：

按证据链交付能力。

8. 当前边界

这仍然是试点阶段。

需要明确的是：

Doramagic pack 不是上游官方发布。
不是所有 pack 都已经完成真实宿主 dogfooding。
不是所有平台都适合同一种内容结构。
没有任何平台发布可以承诺 100% 无审核或账号风险。

所以外部发布也应该按 GO / HOLD / NO-GO 执行，而不是批量铺内容。

9. 一句话总结

Doramagic 的核心不是“提示词库”，也不是“开源项目摘要”。

它要把开源项目和实际经验整理成 AI Agent 能带走、能加载、能验证、能暴露边界、能反馈修复的完整能力资源包。

文章只是入口。

能力资产才是本体。

非官方声明

Doramagic 资源包由 Doramagic 独立整理，用于帮助 AI 编码 Agent 携带可复用上下文、检查项、guardrail、验收方式和避坑经验。除非上游项目明确声明，否则它不是任何上游项目的官方产物，也不代表上游项目立场。

链接

• Doramagic GitHub 账号：https://github.com/tangweigang-jpg
• 示例 pack：https://github.com/tangweigang-jpg/doramagic-openai-agents-python-pack
• 示例 pack：https://github.com/tangweigang-jpg/doramagic-chroma-pack
• 示例 pack：https://github.com/tangweigang-jpg/doramagic-chrome-devtools-mcp-pack