它能帮你做什么

核心：产品循环

做 Agent 产品最常见的坑，是骨架跑起来之后有了新想法，直接改代码，PRD 和方案从此跟代码对不上。产品循环把每一轮新需求都先落回 PRD，再推导、再改骨架：

flowchart LR
    A["💡 一句话点子"] -->|blueprint init| B["📄 PRD V1"]
    B -->|blueprint plan| C["📘 方案.md<br/>待确认清单"]
    C -->|你回答问题<br/>AI 生成代码| D["💻 skeleton/<br/>代码骨架"]
    D -->|blueprint verify<br/>+ 你亲手跑一跑| E["🧪 验证"]
    E -->|有新想法| F["blueprint revise"]
    F -->|PRD 升版 V2<br/>重推方案 · 记录选型变化| B

三方各管一段，边界写死在规则里：

• 引擎负责推导和记账：拆需求、按固定规则选组件、出方案、审稿、PRD 升版快照、记录每轮选型变化。
• AI 助手负责写代码：按方案生成骨架，按迭代记录增量修改，只能写进 out/<产品名>/skeleton/。
• 你负责判断：回答待确认问题、亲手跑骨架、决定下一轮要什么。迭代记录里的「人工验证结论」只能由你来填。

先看效果

下面是引擎对一段话需求的真实输出节选，没有人工修改。输入是：「家长拍一张玩具合影，AI 生成可以亲子共同演绎的剧情脚本……照片涉及隐私，默认不保存……未来希望记住孩子的年龄和偏好。」

它同时会列出你还没想清楚的问题，例如「目标孩子的年龄段是多少」「交互形态是小程序、App 还是网页」，答不上来的就是风险点。

完整版：正向方案 · 反向差距报告 · 示例说明

快速开始

开始前准备两样东西：

用方式一或方式三推导完方案后，把下面这段话交给你的 AI 编程工具，让它写骨架：

引擎目录：/你的路径/agent-blueprint
先读这个目录里的《使用引导.md》，按「产品循环」工作。
产品 酒馆搭子 的方案已经在 out/酒馆搭子/方案.md，请按方案把代码骨架写进 out/酒馆搭子/skeleton/。

🍎 方式一：Mac 双击（零命令行）

浏览器界面（推荐给不用终端的人）：双击 启动界面.command，浏览器会自动打开引擎界面：

1. 「模型设置」里选服务商、粘贴 API Key，点「测试连接并保存」。
2. 「新建产品」像聊天一样说出想法，AI 分三轮追问（给谁用、怎么用、什么不能做），整理成需求草稿给你确认。确认后开始推导，进度直接显示在对话里。
3. 推导完在产品页看方案：组件选型及理由、七层架构、工具清单、系统提示词、审稿意见。
4. 方案里还没想清楚的问题，在「回答问题」里一题一题答；拿不准的点「帮我想想」，AI 给几个方向。答完自动写进 PRD 并重新推导。

用的时候别关启动它的那个终端窗口。界面目前覆盖「新建产品 → 推导方案 → 回答待确认问题」，加新需求、检查骨架、检查外部项目暂时还要用下面的终端问答。

终端问答：双击 启动引擎.command，终端里一问一答走完全程：

1. 选模型服务商，粘贴 API Key，自动测试连接。
2. 选「开始一个产品」，输入产品名和一句话想法。之后也可以选「加新需求」「检查骨架」「只生成方案」「检查外部项目」。
3. 推导完成后自动打开结果文件。

没装 Python 3.10+ 时，两个启动文件都会下载并打开 Python 安装器，装好后重新双击即可。

🤖 方式二：交给能读本地文件的 AI（零安装）

把下面任意一段交给 Claude Desktop、Claude Code、Cursor 这类能读写本地文件的 AI，替换路径和内容：

引擎目录：/你的路径/agent-blueprint
先读这个目录里的《使用引导.md》，按「产品循环」工作。
产品名：酒馆搭子
我的点子是：……
请建立工作区、生成方案，列出要我回答的问题；我确认后再把代码骨架生成到 skeleton/。

引擎目录：/你的路径/agent-blueprint
产品 酒馆搭子，新需求：……
请按产品循环升版 PRD、重推方案，再增量更新骨架。

引擎目录：/你的路径/agent-blueprint
先读《使用引导.md》。请检查这个项目缺什么、先补什么：/你的路径/目标项目
先检查，不修改项目代码。

普通网页聊天窗口读不了本地文件，只给路径是不够的。

💻 方式三：命令行

bash setup.sh                         # 建虚拟环境、装依赖、生成 .env

# 产品循环
.venv/bin/python -m blueprint init "酒馆搭子" "一句话点子" --plan   # 建工作区并推导方案
.venv/bin/python -m blueprint verify out/酒馆搭子                  # 用 PRD 对照 skeleton/
.venv/bin/python -m blueprint revise out/酒馆搭子 "新需求：……"     # PRD 升版并重推方案
.venv/bin/python -m blueprint revise out/酒馆搭子 "……" --quick     # 只重算选型，1 次调用

# 浏览器界面
.venv/bin/python -m blueprint ui                                  # 默认 http://127.0.0.1:8765，只允许本机访问

# 单次使用
.venv/bin/python -m blueprint plan "一句话点子或 PRD 文件路径" -o out/my-plan
.venv/bin/python -m blueprint audit /目标项目路径 [--prd 需求.md] -o out/my-audit

任何一步中断，原命令加 --resume 续跑，已完成的阶段不重复调用模型。

配置模型

在 .env 里填三项即可，向导会帮你写好：

ANTHROPIC_API_KEY=你的 Key
MODEL_ID=deepseek-v4-flash
ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic

各家完整的 Base URL 见 .env.example。

参考用量：

每次运行默认最多 16 次调用、40 万 tokens，超出会停下并提示续跑，不会无限扣费。

产出放在哪

引擎孵化的产品，所有东西都在 out/<产品名>/ 一个文件夹里，不会写到桌面或别的地方：

引擎不负责部署上线和上线后的运行。

你已有的外部项目保持在原位，只把路径告诉引擎做检查。

17 个 Harness 组件

模型是驾驶者，Harness 是载具。 你构建的是载具，不是智能。

引擎内置 17 个组件，每个都带说明、生产级要点和可运行的参考实现 sNN_*/code.py。选型由固定规则完成：模型只判断需求有没有某个特征，选不选哪个组件由 rules.py 决定，同样的判断永远得到同样的选型。原则是只选需要的，不为完整而选。

完整的推导方法和选型表见 BLUEPRINT.md。

常见问题

没有 API Key 能用吗？
方式二可以：由你正在用的 AI 按手册分析，报告里会注明「未运行模型管线」。命令行的 --mock 只按关键词占位，用来检查流程能不能跑通，结论不能用于决策。

我的代码会被上传吗？
只会发给你在 .env 里配置的模型服务。正向推导发送你的点子或 PRD；反向检查发送 README、目录结构和扫描命中的代码片段，不会整库上传。.env 和 out/ 都不进 git，学生打包工具也会排除它们。

结果靠谱吗？
特征判断在题库上的一致率约 90%，单次运行会有一两题波动。方案末尾的独立审稿经常给出「未通过」，这是设计如此：审稿就是要把方案里的矛盾挑出来，这些意见就是你下一轮要回答的问题。反向报告的「信号覆盖率」只是关键词命中比例，不是功能完成度。

Windows 能用吗？
引擎本身是纯 Python，但只在 macOS 和 Linux 上测试过。Windows 建议用 WSL 或方式二。s13、s15、s16 的参考实现依赖 fcntl，只能在 macOS 和 Linux 上运行。

项目结构

开发与维护

.venv/bin/python -m pytest -q                 # 全部测试，不需要 Key
.venv/bin/python -m blueprint eval            # 离线题库回归
.venv/bin/python -m blueprint eval --real     # 真实模型特征一致率
.venv/bin/python tools/refresh_examples.py    # 改提示词后重新生成示例
.venv/bin/python tools/package_student.py     # 生成 dist/agent-blueprint-student.zip

改规则、换模型、调提示词前先看 维护手册，题库口径见 evals/README.md，提交 PR 前看 贡献指南。

文档导航