Agent 工坊
一句话点子 → 可确认的 PRD 与架构方案 → 你的 AI 写出能跑的骨架 → 引擎对照 PRD 验收 → 按新需求持续迭代
一个本地运行的 Agent 产品推导引擎。它不替你写代码，而是先把「该做什么、该用哪些机制、哪里还没想清楚」推导清楚，交给你自己的 AI 编程工具去写骨架，再对照 PRD 验收，陪你一轮轮把骨架做对。
教学版和网页版 · 快速开始 · 先看效果 · 使用引导 · 教程视频
教学版和网页版
上课的同学请下载教学版（下表第一行的链接），不要下载本页的网页版；课堂流程、结课检查表都写在教学版里。
两个版本都下载到自己电脑上运行，不是网站。教学版由 AI 在终端里运行命令，用法看教学版的 README「课堂上这样用」；网页版双击 启动界面.command，第一次双击如果被 macOS 拦下，看常见问题。
它能帮你做什么
核心：产品循环
做 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/。
- 你负责判断：回答待确认问题、亲手跑骨架、决定下一轮要什么。迭代记录里的「人工验证结论」只能由你来填。
引擎里的 agent
引擎外层是固定流程：步骤顺序写死，组件选型由规则计算，费用有上限。其中需要「自己判断下一步」的四处交给 agent，每一处都有代码兜底：
agent 需要模型支持工具调用。模型不支持、调用出错或费用上限快用完时，这一步自动退回固定流程，报告或方案开头会写明原因，不会让你卡住。
先看效果
下面是引擎对一段话需求的真实输出节选，没有人工修改。输入是：「家长拍一张玩具合影，AI 生成可以亲子共同演绎的剧情脚本……照片涉及隐私，默认不保存……未来希望记住孩子的年龄和偏好。」
它同时会列出你还没想清楚的问题，例如「目标孩子的年龄段是多少」「交互形态是小程序、App 还是网页」，答不上来的就是风险点。
完整版：正向方案 · 反向差距报告 · 示例说明
快速开始
开始前准备两样东西：
用方式一或方式三推导完方案后，把下面这段话交给你的 AI 编程工具，让它写骨架：
引擎目录：/你的路径/agent-workshop
先读这个目录里的《使用引导.md》，按「产品循环」工作。
产品 酒馆搭子 的方案已经在 out/酒馆搭子/方案.md，请按方案把代码骨架写进 out/酒馆搭子/skeleton/。
🍎 方式一：Mac 双击（零命令行）
浏览器界面（推荐给不用终端的人）：双击 启动界面.command，浏览器会自动打开引擎界面。第一次双击如果提示「无法打开」，按常见问题里的步骤放行一次即可。
- 「模型设置」里选服务商、粘贴 API Key，点「测试连接并保存」。
- 「新建产品」像聊天一样说出想法，AI 追问给谁用、怎么用、什么不能做，信息够了就停（想法说完整了就不再问，只说一句话的一般问三个左右），整理成需求草稿给你确认。确认后开始推导，进度直接显示在对话里。
- 推导完在产品页看方案：组件选型及理由、七层架构、工具清单、系统提示词、测试设计、审稿意见。
- 方案里还没想清楚的问题，在「回答问题」里一题一题答。问题都改成了大白话，只有工程师能判断的技术备注单独放着，不用你答；拿不准的点「帮我想想」，AI 给几个方向。答完自动写进 PRD 并重新推导。
- 在「试玩」里扮演自己产品的使用者（比如来问面包的顾客）和它聊几句，看它按现在的方案会怎么回应。它会按方案里的工具清单一步步做事，每做一步就多一张卡片；查资料、通知店主这些工具不会真的执行，结果是模拟的。方案里要先问人的操作会停下来等确认，禁止的操作调不了，这些地方都单独标出来。哪里不对就点回复下面的「这里不对」记下，最后一起带去「加新需求」。
- 点「导出交接包」，把 zip 发给帮你做产品的开发者：里面有需求、方案、还没定下来的问题、第一版组件的参考代码，以及一段交给 AI 编程工具的提示词。
- 有了新想法，在「加新需求」里说一句，AI 最多再问一个问题，整理成草稿给你确认；确认后需求文档升一版、方案重新推导，自动跳到「版本历史」，告诉你哪些组件的选型变了。每一版的需求文档都能回看。
- 手上已经有一个 Agent 项目，点左栏「检查一个项目」，选它的文件夹（会弹出 Mac 自带的选文件夹窗口，也可以粘贴路径），几分钟后得到差距报告和一份它本该有的需求文档，结果列在左栏「检查过的项目」里。代码改过后点「重新检查」再查一次：「这个项目该有什么」沿用上次的判断，两次的差别只来自代码；项目定位变了再点「重新判断」。
产品页左栏底部会显示这个产品累计调用了多少次模型、用了多少 tokens（推导和对话都算，新建产品时的追问不算）。用的时候别关启动它的那个终端窗口。检查产品的代码骨架、对照 PRD 检查外部项目暂时还要用下面的终端问答。
终端问答：双击 启动引擎.command，终端里一问一答走完全程：
- 选模型服务商，粘贴 API Key，自动测试连接。
- 选「开始一个产品」，输入产品名和一句话想法。之后也可以选「加新需求」「检查骨架」「只生成方案」「检查外部项目」。
- 推导完成后自动打开结果文件。
没装 Python 3.10+ 时，两个启动文件都会下载并打开 Python 安装器，装好后重新双击即可。
🤖 方式二：交给能读本地文件的 AI（零安装）
把下面任意一段交给 Codex、Claude Code、Kimi Code、pi 这类能读写本地文件、能运行命令的 AI，替换路径和内容：
引擎目录：/你的路径/agent-workshop
先读这个目录里的《使用引导.md》，按「产品循环」工作。
产品名：酒馆搭子
我的点子是：……
请建立工作区、生成方案，列出要我回答的问题；我确认后再把代码骨架生成到 skeleton/。
引擎目录：/你的路径/agent-workshop
产品 酒馆搭子，新需求：……
请按产品循环升版 PRD、重推方案，再增量更新骨架。
引擎目录：/你的路径/agent-workshop
先读《使用引导.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 # 只重算选型，最多 3 次调用
.venv/bin/python -m blueprint handoff out/酒馆搭子 # 打包交接包，交给会写代码的人
# 浏览器界面
.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
检查项目（audit、verify）默认由 agent 读代码核实，每条结论都附它读过的代码行；一次检查最多调用模型 40 次。想省钱或排查问题时加 --fast，只按关键词扫描，可能误判。
任何一步中断，原命令加 --resume 续跑，已完成的阶段不重复调用模型。
配置模型
在 .env 里填三项即可，向导会帮你写好：
ANTHROPIC_API_KEY=你的 Key
MODEL_ID=deepseek-v4-flash
ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic
用 GPT（OpenAI 官方，或 OpenAI 格式的中转）时改填这几项。网页「模型设置」和终端问答里选「OpenAI（GPT）」或「OpenAI 格式的中转或其他服务」，也会帮你写好：
API_FORMAT=openai
OPENAI_API_KEY=你的 Key
MODEL_ID=gpt-6-luna
OPENAI_BASE_URL=https://你的中转地址/v1 # 用 OpenAI 官方接口时不填
各家完整的 Base URL 见 .env.example。
agent 需要模型支持工具调用。DeepSeek 实测支持（Anthropic 格式和 OpenAI 格式都试过）；其他服务商或模型中转可以先测一下，三项都通过就能用 agent（这个测试脚本目前只测 Anthropic 格式）：
.venv/bin/python tools/probe_tools.py # 测 .env 里配的模型
.venv/bin/python tools/probe_tools.py --model 模型名 # 换个模型测
几个开关，需要时在启动前设置：
参考用量：
每次运行默认最多 40 次调用、150 万 tokens（检查项目加 --fast 时是 16 次、40 万），超出会停下并提示续跑，不会无限扣费。实际用量通常远低于上限。
产出放在哪
引擎孵化的产品，所有东西都在 out/<产品名>/ 一个文件夹里，不会写到桌面或别的地方：
引擎不负责部署上线和上线后的运行。
你已有的外部项目保持在原位，只把路径告诉引擎做检查。
17 个 Harness 组件
模型是驾驶者，Harness 是载具。 你构建的是载具，不是智能。
引擎内置 17 个组件，每个都带说明、生产级要点和可运行的参考实现 sNN_*/code.py。选型由固定规则完成：模型只判断需求有没有某个特征，选不选哪个组件由 rules.py 决定，同样的判断永远得到同样的选型。原则是只选需要的，不为完整而选。
完整的推导方法和选型表见 BLUEPRINT.md。
以上為 README 的開頭部分。其餘內容請閱讀原文。 檢視完整 README ↗
