1. 项目概述从“魔法咒语”到“工程框架”如果你和我一样在过去一年里深度使用过 Cursor 或 Claude Code那你一定经历过这种场景你给 AI 助手写了一段精心设计的提示词Prompt让它帮你写个功能。它噼里啪啦写了几百行代码看起来有模有样。你满怀期待地运行结果要么是报错要么是逻辑跑偏要么是它“自由发挥”加了一堆你不需要的东西。你不得不回头像教一个聪明但粗心的实习生一样一遍遍纠正“不这里不是这个意思”“那个变量名错了”“等等你怎么把整个数据库结构都改了”这种体验我称之为“提示词赌博”。你把复杂的、多步骤的业务逻辑寄托在一段可能被 AI 误解的自然语言描述上然后祈祷它能一次性做对。问题在于大型语言模型LLM本质上是概率性的。它根据你给的上下文预测最可能的下一个词。“最可能”不等于“正确”更不等于“符合你的业务规则”。当一个任务被拆解成 5 个、10 个步骤时每一步哪怕有 90% 的准确率最终整体成功的概率也会呈指数级下降90%^5 ≈ 59%。这根本不是 AI 能力的问题而是工作流设计的问题。Kraken的出现就是为了终结这种赌博。它不是一个新模型也不是一个魔法工具而是一个开源的工作流框架。它的核心思想极其简单却非常有力将“决策”What Why与“执行”How彻底分离。让 AI 去做它最擅长的事——理解意图、规划步骤、做出判断而让确定性的、由你控制的脚本去完成具体的、无歧义的操作。这就像一位经验丰富的项目经理AI和一支纪律严明的工程团队你的脚本协同工作。项目经理负责解读蓝图、拆分任务、协调资源工程团队则严格按照施工手册完成每一块砖的砌筑。这个框架非常适合产品经理、产品负责人、独立开发者、AI 应用构建者以及任何希望将 AI 从“偶尔灵光一现的聊天伙伴”升级为“稳定可靠的工作副驾驶”的人。它不是为了替代你的思考而是为了将你的思考工程化、流程化、可复用化让 AI 的协作变得可预测、可调试、可积累。2. 核心架构解析三层模型如何根治“AI幻觉”Kraken 的威力根植于其清晰的三层架构。理解这三层你就理解了它如何系统性解决 AI 协作的不可靠问题。2.1 第一层指令层 - 用 Markdown 定义“做什么”这是整个系统的“宪法”和“蓝图”完全由你掌控。它位于/vaults/领域/projects/项目名/plans/目录下通常是一个或多个 Markdown 文件。为什么是 Markdown因为它对人类和 AI 都友好。你不需要学习任何新的 DSL领域特定语言就用写文档的方式清晰地定义目标这个项目/任务要达成什么输入需要哪些资源、数据、上下文输出最终交付物是什么样子例如一个 API 端点、一个数据库 schema、一份测试报告约束技术栈、性能要求、截止日期等。成功标准如何验证任务完成了实操示例一个用户登录功能的需求指令# 项目用户认证模块 ## 目标 实现一个安全的用户登录和注册 RESTful API。 ## 输入 - 现有的用户数据库表结构见 schema.sql - JWT 密钥已配置在环境变量中 ## 输出 1. POST /api/auth/register 端点处理用户注册。 2. POST /api/auth/login 端点处理用户登录并返回 JWT。 3. 相应的数据模型和 Service 层代码。 ## 约束 - 使用 NestJS 框架。 - 密码必须加盐哈希存储使用 bcrypt。 - 注册需验证邮箱格式和密码强度。 - 登录失败需有通用的错误提示防止用户枚举。 ## 成功标准 - 所有端点能通过 Postman 测试。 - 密码不以明文形式存储或传输。 - 有基础的输入验证。注意这一层的关键是精确和无歧义。避免使用“快速的”、“友好的”这类模糊词汇。多用“响应时间 200ms”、“返回标准化的错误 JSON”这样的具体描述。AI 会根据这份指令来规划任务模糊的指令必然导致跑偏的执行。2.2 第二层编排层 - AI 作为“决策指挥官”这一层是 AI 代理Agent的主场。它的工作不是写代码而是阅读理解解析你在指令层写的 Markdown 计划。任务分解将宏观目标拆解成一系列具体的、可执行的子任务Task。工具调用判断每个子任务应该调用哪个“执行层”的脚本来完成。状态管理与错误处理跟踪任务进度当脚本执行出错时分析日志决定是重试、回滚还是上报给你。它的核心价值是“判断”和“路由”。比如面对“实现登录API”的指令AI 会判断出需要先后调用“生成 NestJS 控制器骨架脚本”、“生成用户实体脚本”、“生成密码哈希服务脚本”、“生成 JWT 策略脚本”。它自己不去写这些脚本的具体逻辑而是知道该在什么时候、用什么参数去启动它们。2.3 第三层执行层 - 确定性脚本负责“怎么做”这是系统的“肌肉”位于/vaults/领域/projects/项目名/execution/目录。这里存放的是一个个具体的、确定性的脚本Python、TypeScript、Bash 等。这些脚本的特点单一职责每个脚本只做一件很小、很具体的事。例如generate_controller.py、hash_password.ts、run_migration.sh。确定性输出给定相同的输入永远产生相同的输出。没有随机性没有“大概”。由你编写或审核你可以自己写也可以用 AI 生成后仔细审查、固化下来。一旦入库它们就是可靠的“积木”。当编排层的 AI 决定要“生成一个 NestJS 控制器”时它就会调用generate_controller.py这个脚本并传入参数如控制器名、路由前缀。脚本运行生成确切的代码文件。即使 AI 的理解有细微偏差只要脚本的逻辑是确定的最终产出就是可靠的。三层联动的威力你通过 Markdown 下达精确指令指令层AI 将其分解并规划执行路径编排层最终由一个个经过验证的脚本完成实际工作执行层。AI 的“创造力”和“理解力”被用于高级规划而“粗心大意”和“幻觉”被确定性的脚本排除在外。这才是人机协作的工程化范式。3. 从零开始手把手搭建你的第一个 Kraken 项目理论说得再多不如动手做一遍。让我们以一个真实的场景——为一个简单的待办事项Todo后端 API 创建项目骨架——来演示 Kraken 的全流程。3.1 环境准备与初始化首先确保你的环境符合要求编辑器/IDE强烈推荐 Cursor IDE它对 Kraken 的支持最原生。Claude CodeAnthropic 的 CLI 工具也可用。运行环境Node.js (18)Python (3.10)Git。安装与启动# 1. 克隆仓库 git clone https://github.com/luisabwk/kraken.git cd kraken # 2. 可选配置环境变量。如果需要接入 OpenAI、Anthropic 等外部模型 API才需要配置。 cp .env.example .env # 编辑 .env 文件填入你的 API keys。如果只用本地模型或 Cursor 内置能力可跳过。 # 3. 在 Cursor 中打开克隆下来的 kraken 目录。 # 在 Cursor 的聊天框中输入魔法命令 /boot输入/boot后Kraken 代理会被激活。它会检查目录结构、加载所有规则Rules和技能Skills并在聊天框输出一个欢迎信息和可用命令列表。这表示你的 Kraken 环境已经就绪。3.2 创建项目结构与核心指令Kraken 用“保险库”Vault来组织不同领域的工作。我们为“工作”相关项目创建一个。# 在终端中于 kraken 目录下执行 mkdir -p vaults/work/projects/todo-api/{plans,tasks,execution,project} touch vaults/work/projects/todo-api/AGENTS.md这创建了一个标准的项目结构plans/存放我们的项目计划PRP。tasks/存放由计划分解出的具体任务卡。execution/存放确定性的执行脚本。project/最终生成的项目代码文件会放在这里。AGENTS.md项目级的 AI 代理指令文件会继承根目录的设置并可以覆盖项目特定规则。3.3 撰写产品需求提示与 AI 进行结构化对话现在我们开始与 AI 协作的核心步骤。在 Cursor 聊天框输入/prp-newAI 不会立刻开始写代码而是会像一位专业的产品顾问向你提出一系列结构化问题来澄清需求“你想解决什么问题”我需要一个简单的 RESTful API 来管理待办事项支持增删改查。“这是新功能、Bug 修复、重构还是文档”我新功能。“当前已经存在什么”我这是一个全新的项目从零开始。技术栈我选 Node.js Express Prisma SQLite。“有任何时间、预算或技术限制吗”我希望今天能跑通基础功能。使用 SQLite 方便本地开发代码结构要清晰便于后续加用户认证。“你如何知道它已经完成了”我我能用 Postman 或 curl 成功调用GET /todos、POST /todos、PUT /todos/:id、DELETE /todos/:id这四个端点并且数据能持久化到数据库。AI 会根据你的回答在plans/目录下生成一份名为todo-api-prp.md的产品需求提示文档。这份文档远比你随口一说的“写个 Todo API”要详细得多它包含了上下文、功能需求、非功能需求、约束条件和明确的验收标准。这份文档将成为后续所有工作的唯一事实来源避免了因口头沟通不清导致的返工。3.4 任务分解与估算从蓝图到施工图有了 PRP 之后AI 会主动询问你是否要进行任务分解。你同意后它会运行任务分解技能。 AI 会分析 PRP然后输出一个任务列表类似这样任务ID描述复杂度依赖状态T1初始化 Node.js 项目安装 Express, Prisma, Zod 等依赖1点无待办T2配置 Prisma定义Todo数据模型3点T1待办T3实现GET /todos端点列表查询3点T2待办T4实现POST /todos端点创建5点T2待办T5实现PUT /todos/:id端点更新5点T2, T3待办T6实现DELETE /todos/:id端点删除3点T2, T3待办T7编写基础的集成测试8点T3-T6待办T8创建 API 文档 (OpenAPI/Swagger)5点T3-T6待办复杂度点数1, 3, 5, 8是斐波那契数列的变体用于粗略估算工作量。AI 会将这些任务保存到tasks/目录下每个任务一个 Markdown 文件详细描述了实现步骤和验收条件。至此一个模糊的想法已经变成了一个可追踪、可执行的项目计划。3.5 执行与自动化让 AI 驱动工作流最激动人心的部分来了。在聊天框输入/executeAI 会进入“自动驾驶”模式。它会读取plans/todo-api-prp.md和tasks/下的所有任务。将第一个任务 T1 的状态更新为“进行中”。关键动作它不会直接去写package.json而是去execution/目录下寻找或建议创建一个名为init_node_project.py的脚本。如果这个脚本不存在它会基于它的知识生成这个脚本的代码建议并询问你是否创建。你拥有最终决定权。一旦脚本就位AI 会调用它传入项目名、路径、依赖列表等参数。脚本运行生成package.json安装依赖创建基础目录。AI 检查脚本输出如果成功将 T1 标记为“完成”并自动开始 T2。这个过程会一直持续直到所有任务完成或遇到需要你干预的阻塞问题。在整个过程中AI 的角色是“工头”而实际拧螺丝、砌砖的“工人”是你预先认可或审核过的确定性脚本。3.6 代码审查与质量守护即使一切顺利在最终合并前运行一次代码审查也是好习惯。输入/code-reviewKraken 的审查不是简单的风格检查。它会运行一个带有“置信度评分”的审查高置信度问题≥80%比如发现了未处理的 Promise 拒绝、一个明显的 SQL 注入漏洞、硬编码的密码。它会明确报告。低置信度建议80%比如“这个函数名也许可以更达意”、“这里可以考虑用解构赋值”。这类建议会被过滤或弱化提示避免产生信息噪音。这个功能极大地提升了审查效率让你专注于真正有风险的问题而不是在代码风格偏好上争论。4. 进阶技巧与深度配置释放框架全部潜力掌握了基础流程后以下几个进阶特性能让你的 Kraken 体验从“好用”升级到“不可或缺”。4.1 技能库封装可复用的专家经验技能Skills是 Kraken 的知识库。它们位于.cursor/skills/目录下是一些详细的 Markdown 指南教导 AI 如何完成特定类型的复杂工作。比如test-driven-development技能会一步步教 AI 如何遵循“红-绿-重构”的循环。如何利用技能当 AI 遇到一个它知道有对应技能的任务时它会自动加载该技能文档作为上下文。例如当你在 PRP 中强调“必须采用 TDD”AI 在执行编码任务时就会参考tdd技能中的步骤先写一个失败测试再实现代码让测试通过最后重构。创建自定义技能这是 Kraken 的精华。假设你的团队有一套独特的 API 响应格式规范你可以创建一个api-response-format技能。# 使用内置的 skill-creator 工具 python3 .cursor/skills/skill-creator/scripts/init_skill.py api-response-format --path .cursor/skills/这会在技能目录下创建一个模板。你编辑这个 Markdown 文件详细定义目标确保所有 API 端点返回统一的 JSON 结构。格式规范{ success: boolean, data: any, message?: string, code: number }示例给出成功和错误的响应示例。实施步骤如何在中间件或拦截器中实现。检查清单AI 在完成开发后需要自查的项。创建后AI 在处理任何与 API 相关的任务时都会自动参考这份指南确保产出符合你的团队标准。技能是将团队最佳实践和领域知识“固化”到 AI 工作流中的最强手段。4.2 动态上下文管理突破 Token 限制的智慧LLM 有上下文窗口限制。长会话、大量代码输出很快就会占满窗口导致模型“忘记”之前的内容。Kraken 内置了一套优雅的上下文管理系统。自动卸载当 AI 生成的输出如一个完整的脚本代码、一个长列表超过 50 行时它不会全部塞进聊天历史。而是会将其保存到context/mcp/或context/terminal/下的一个文件中并在聊天中给你一个引用链接比如[输出已保存至 context/mcp/output_20231027_1023.md]。按需读取当后续对话需要参考之前那份输出时AI 知道去那个文件里读取特定部分而不是要求你重新粘贴。会话历史context/history/目录会记录 AI 在本次会话中做出的关键决策和推理过程即使聊天窗口被清理这些“记忆”依然存在。你可以通过命令管理这些上下文/context status # 查看当前上下文存储的使用情况 /context clean # 清理超过7天的旧上下文文件 /context log 决定将数据库从 MongoDB 迁移到 PostgreSQL原因是... # 手动记录一个重要决策这个系统保证了在复杂的、多步骤的项目中AI 始终能保持对项目状态的清晰认知而不受技术性上下文限制的困扰。4.3 守护规则你的自动化安全网守护规则Guardrails是预定义的钩子Hooks在 AI 行动前后自动触发防止常见错误。它们是你的“安全网”。部分强大的守护规则包括危险命令拦截如果 AI 试图生成包含rm -rf /、DROP DATABASE等危险命令的脚本会被立即阻止。敏感信息检测在代码中检测到类似API_KEYsk-live-xxx的硬编码密钥会发出强烈警告并建议使用环境变量。巨型文件预警当 AI 试图创建一个超过 500 行的单文件时会建议将其拆分为更小、更模块化的文件。TODO 跟踪检测到代码中的// TODO: 添加错误处理注释会提示你将其记录到正式的任务跟踪系统中避免遗忘。强制测试提醒在标记一个涉及代码的任务为“完成”前会检查是否有对应的测试被运行或创建。这些规则被动生效默默为你扫雷。你可以在.cursor/hooks/目录下查看和自定义它们使其更符合你的团队规范。4.4 自我增强从错误中学习的系统这是 Kraken 最具前瞻性的特性之一。当执行层的脚本运行出错时编排层的 AI 不会仅仅报告错误。它会分析错误日志尝试理解根本原因。修复问题可能会修改调用脚本的参数或者对脚本本身提出修正建议。更新指令如果发现错误源于最初的计划PRP描述不清它会建议你修改plans/下的 Markdown 文件使其更精确。记录学习将这次错误和解决方案记录下来形成经验。下次遇到类似情况处理起来会更高效。这个过程被称为“Self-Annealing”自我退火。系统不是在重复犯错而是在每一次迭代中变得更强健、更智能。你的项目知识库指令和脚本随着时间推移会变得越来越可靠。5. 工程实践与避坑指南在实际使用 Kraken 几个月后我积累了一些在官方文档里找不到的实战心得和避坑指南。5.1 脚本设计原则打造可靠的“执行层”执行层脚本是系统的基石设计好坏直接决定稳定性。原则一极度单一职责。一个脚本只做一件事并且做好。generate_model.py就只负责根据输入生成数据模型定义不要让它顺便去连接数据库。这降低了复杂度便于测试和复用。原则二幂等性。脚本可以安全地多次运行。比如一个创建目录结构的脚本应该先判断目录是否存在避免重复创建报错。这让你可以放心地重新运行工作流。原则三丰富的日志输出。脚本应该清晰地输出它正在做什么、用了什么参数、结果如何。这为 AI 分析和调试提供了宝贵信息。使用不同的日志级别INFO, WARNING, ERROR。原则四参数化输入。不要将配置硬编码在脚本里。通过命令行参数、环境变量或配置文件传入。这样同一个脚本才能被用于不同的场景。反面案例一个名为setup_project.sh的脚本里面依次安装了依赖、创建了数据库、跑了迁移、还启动了开发服务器。一旦中间某步失败整个状态就混乱不堪。正面案例拆分成install_deps.sh、init_db.sh、run_migrations.sh、start_dev_server.sh四个脚本。每个脚本独立、可重试、日志清晰。5.2 指令撰写艺术如何与 AI 清晰沟通指令层Markdown的质量决定了 AI 理解的精度。使用肯定句避免否定句。AI 对“不要做什么”的理解有时会偏差。与其说“不要使用全局变量”不如说“所有状态必须通过函数参数传递或从类属性中访问”。提供结构化示例。在定义 API 响应格式时不要只描述直接给一个完整的 JSON 示例。AI 模仿示例的能力极强。明确边界条件。特别是对于错误处理。说“需要处理错误”是模糊的。应该说“当数据库查询失败时应记录错误日志到app.log并向客户端返回 HTTP 500 状态码及{ error: ‘Internal server error’ }的 JSON 响应”。利用清单。在成功标准部分使用清单列出所有验收项。这为 AI 提供了清晰的检查表。5.3 常见问题与排查问题一AI 似乎忽略了我的项目特定指令AGENTS.md。排查检查你的工作目录是否正确。在 Cursor 中确保打开的是项目根目录或vaults/work/projects/your-project/目录。AI 会优先读取当前目录及其父目录下的AGENTS.md文件。解决在项目目录的AGENTS.md开头使用明确的指令如“本项目优先遵循本文件中的规则忽略上级目录中的冲突指令”。问题二/execute命令卡住了或者一直在重复同一个步骤。排查这通常是执行层脚本出了问题但 AI 没有成功处理错误。打开终端手动运行 AI 最后尝试调用的那个脚本可以在context/terminal/里找到日志查看具体的错误输出。解决根据错误修复脚本。然后你可以在聊天框里告诉 AI“脚本xyz.py在第 N 行有错误原因是……我已经修复了请继续。” AI 会更新上下文并继续。问题三AI 生成的代码风格不符合团队要求。解决不要每次都在 PRP 里重复写代码风格要求。创建一个名为code-style-guide的技能Skill。在其中详细定义缩进、命名规范、注释要求、导入顺序等。然后在项目的AGENTS.md中引用这个技能“在编写任何代码前请务必阅读并应用code-style-guide技能中的规范。”问题四上下文似乎丢失了AI 忘记了之前讨论的细节。排查可能是上下文窗口满了Kraken 的自动卸载机制将部分内容存到了文件里。解决使用/context status查看。如果 AI 需要之前的信息你可以提示它“关于数据库连接配置的讨论之前保存在context/mcp/下的某个文件里了请查一下。” AI 知道如何去检索。5.4 与现有工作流整合Kraken 不是一个孤岛它可以融入你现有的开发流程。版本控制整个kraken/目录包括vaults/下的计划、任务和脚本都应该纳入 Git 管理。这让你能追踪项目需求和自动化流程的演变。CI/CD你可以在 CI 流水线中让 Kraken 执行一些自动化任务。例如在合并请求前自动运行/code-review进行质量检查在发布后自动运行某个脚本来更新部署文档。团队协作将共享的技能库.cursor/skills/和经过验证的执行脚本execution/下的通用部分放在一个共享的 Git 子模块或独立仓库中供整个团队使用确保协作的一致性。从最初的怀疑到如今的依赖Kraken 彻底改变了我与 AI 协作的方式。它把那种“提示词玄学”变成了可管理、可预测的软件工程流程。最大的体会是它迫使你更早、更清晰地思考。为了写出好的指令你必须先想清楚到底要什么。为了编写可靠的脚本你必须深入理解每一个操作步骤。这个过程本身就是对项目和问题理解的巨大深化。它可能不会让你瞬间十倍速开发但它能显著降低返工率提升产出质量并将你的经验和知识沉淀为可复用的资产。如果你受够了 AI 的“幻觉”和不可靠厌倦了在模糊的对话中来回拉扯那么是时候“释放 Kraken”了。这不是关于让 AI 替你工作而是关于为你和 AI 设计一套能稳定产出成果的工作系统。