1. 项目概述Kraken一个让AI代理成为可靠工作伙伴的框架如果你和我一样在日常工作中深度依赖像ChatGPT、Claude这类大语言模型LLM来辅助编码、写文档、拆解任务那你一定也经历过那种“薛定谔的准确率”带来的焦虑。你写了一个详细的提示词让它生成一个功能模块它可能前两步做得很好第三步就开始自由发挥凭空捏造一个不存在的API或者把逻辑搞得一团糟。你不得不像个监工一样时刻盯着它的输出手动纠正每一个偏离轨道的细节。这种工作模式与其说是“智能辅助”不如说是“人工纠错”效率低下且充满不确定性。这正是Kraken框架要解决的核心痛点。它不是一个全新的AI模型而是一个工作流框架一种工程化思维。它的核心理念非常直接既然LLM天生是概率性的、擅长规划和决策但容易在执行细节上“幻觉”那我们就把“规划决策”和“具体执行”彻底分开。让AI做它最擅长的事——理解意图、拆解任务、做出判断而把那些需要精确、确定、可重复的操作交给由我们人类编写的、确定性的脚本去完成。简单来说Kraken帮你建立了一套“人机协作”的标准化流程。你不再是那个对着聊天窗口不停追问和纠正的“唠叨老板”而是变成了一个制定战略方针的“指挥官”。你负责在指令层Directive用Markdown写下清晰的目标和规则“我们要攻下这个山头注意东侧有河流必须在三日内完成”AI代理在编排层Orchestration解读你的指令决定每一步该调用什么工具“派工兵架桥步兵从侧翼包抄”最后具体的执行层Execution由你预先写好的Python、TypeScript等脚本可靠地运行“架桥脚本”、“包抄路线计算脚本”。这套架构带来的最大好处是可信度。一个复杂的项目往往包含数十个步骤。如果每个步骤LLM的独立准确率是90%这已经非常乐观了那么连续5个步骤都正确的概率会骤降到约59%。如果是10个步骤成功率会跌到35%以下。Kraken通过将关键执行步骤固化到脚本中将这个概率游戏的链条打断确保每一个“动作”都是100%可靠的。AI的“幻觉”被限制在了规划和决策环节而这个环节的错误更容易通过结构化的指令和规则Kraken内置的Guardrails来防范和纠正。无论你是需要管理复杂产品需求的产品经理是每天与代码搏斗的开发者还是利用AI进行创意工作的设计师只要你希望将AI从“一个有时靠谱的聊天伙伴”升级为“一个可预测、可管理、可集成的生产系统组件”Kraken都值得你花时间深入了解。它提供的不是魔法而是一套让你能稳定释放AI潜力的工程学工具箱。2. 核心架构解析三层分离如何根治AI的“不靠谱”Kraken的威力根植于其清晰的三层架构设计。理解这三层各自的责任和交互方式是掌握这个框架的关键。这不仅仅是三个文件夹而是三种截然不同的责任边界是“人机共舞”的舞台分区。2.1 指令层人类智慧的结晶区指令层是你的“作战指挥部”。它位于/vaults/领域/projects/项目名/plans/目录下其载体是纯文本的Markdown文件。在这里你不需要任何编程知识只需要用清晰、结构化的人类语言描述清楚以下几件事目标与愿景这个项目最终要达成什么状态成功的画面是什么样的输入与约束我们手头有什么材料数据、API、现有代码有哪些不可逾越的红线技术栈限制、截止日期、性能要求输出与验收标准我们具体要交付哪些东西功能列表、API文档、测试用例如何判断每项交付物是合格的非功能性需求安全性、可维护性、性能指标等。为什么是Markdown因为它足够简单、通用且能被AI很好地理解。你写下的每一个标题、列表和加粗文本都是在为AI代理构建一个清晰的心智模型。一个优秀的指令文件读起来应该像一份精简版的PRD产品需求文档或技术方案它定义了“做什么”和“为什么做”但不涉及“怎么做”。实操心得在编写指令时我习惯采用“背景-问题-解决方案-验收标准”的经典叙事结构。避免使用模糊的形容词如“快速的”、“友好的”而是使用可量化的描述如“API响应时间P95 200ms”、“错误提示文案需在10个词以内”。这能极大减少AI的理解偏差。2.2 编排层AI代理的决策引擎这一层是Kraken框架的“大脑”由AI代理在Cursor或Claude Code中运行主动运作。它的工作流程是确定性的解析指令读取你写在plans/目录下的Markdown文件理解整体目标和所有约束条件。任务分解将宏大的目标拆解成一系列具体的、可执行的原子任务Task。每个任务会包含明确的输入、操作步骤和预期输出描述。工具调用决策为每个原子任务判断应该调用哪个执行层脚本。例如任务描述是“在数据库表X中插入测试数据”代理就会决定调用execution/目录下的populate_test_data.py脚本。错误处理与状态管理执行过程中如果脚本报错代理不会不知所措而是会根据预定义的规则Rules尝试分析错误日志决定是重试、回滚还是上报给人类。同时它会更新任务状态如“进行中”、“阻塞”、“已完成”。这一层的核心价值在于“路由”和“协调”。它像一个经验丰富的项目经理虽然自己不写代码但知道每个任务该派给哪个专家脚本并能处理任务间的依赖和异常。Kraken通过大量的预置规则Rules和技能Skills来“武装”这个代理让它具备代码审查、系统调试、TDD引导等专业能力。2.3 执行层确定性脚本的堡垒这是整个系统的“手脚”是可靠性的基石。它位于/vaults/领域/projects/项目名/execution/目录里面存放的是标准的、你亲手编写或审核过的程序脚本Python、JavaScript/TypeScript、Shell等。这些脚本的特点是确定性给定相同的输入永远产生相同的输出。没有随机性没有“大概可能也许”。可测试你可以为它们编写单元测试和集成测试确保其行为符合预期。专注单一职责一个脚本最好只做一件事并且把它做好。例如generate_api_client.py就只负责根据OpenAPI规范生成客户端代码不负责启动服务器。当编排层的AI代理决定调用execution/下的某个脚本时它会以子进程的方式运行该脚本并捕获其输出标准输出、标准错误和退出码。脚本执行的成功与否完全由脚本自身的逻辑和退出码决定AI无法篡改结果。三层之间的数据流可以用一个简单的例子串联你想搭建一个博客系统。指令层你在plans/blog-setup.md中写下“目标搭建一个基于Node.js的Markdown博客。需求支持文章列表、分页、代码高亮。约束使用SQLite数据库UI简洁。”编排层AI代理读取该指令将其分解为任务T1-初始化项目T2-创建数据库模式T3-实现文章CRUD APIT4-实现前端列表页……执行层对于任务T2代理调用你预先写好的execution/init_database.sql脚本这个脚本包含创建posts表的确定SQL语句。执行成功代理将T2标记为完成并继续T3。通过这种分离你将AI的创造力规划、拆解、决策与机器的精确性脚本执行完美结合同时将风险AI幻觉隔离在了可控的、高层次的决策环节。3. 从零开始搭建你的第一个Kraken项目理论说得再多不如亲手跑一遍。下面我将带你完整地走一遍初始化并运行一个Kraken项目的流程其中会穿插我踩过的一些坑和总结的技巧。3.1 环境准备与框架安装Kraken的设计是IDE/编辑器无关的但它深度集成了Cursor和Claude Code这两个目前对AI编码辅助支持最好的工具。你需要至少准备其中一个。基础环境Node.js ( 18.x)和Python ( 3.10)这是运行许多自动化脚本的基石。建议使用nvm和pyenv来管理版本避免全局冲突。Git代码版本管理必不可少。Cursor IDE从官网下载安装。它内置了优秀的AI助手是运行Kraken的“主战场”之一。Claude Code (可选)Anthropic提供的命令行工具如果你更喜欢在终端里工作它是绝佳选择。安装Kraken框架安装过程极其简单因为它本质上是一套配置文件和约定。# 克隆仓库到本地 git clone https://github.com/luisabwk/kraken.git cd kraken # 复制环境变量示例文件如果需要配置API密钥等 cp .env.example .env # 编辑 .env 文件填入你的OpenAI或Anthropic API密钥如果你需要代理使用特定的模型此时你的kraken目录下已经包含了完整的框架结构.cursor和.claude配置文件夹、示例的vaults等。关键一步启动Boot在Cursor中打开这个kraken项目根目录。然后在Chat面板中简单地输入命令/boot这个命令是Kraken的“开机键”。它会做以下几件事检查项目目录结构是否符合预期。加载所有预定义的规则Rules、技能Skills和防护栏Hooks。向AI代理“灌输”Kraken的工作哲学和操作指南。输出当前可用的命令列表和项目状态。如果你看到代理回复了一系列可用的命令如/execute,/prp-new和一个友好的欢迎信息恭喜你Kraken已经成功唤醒。3.2 创建项目结构与第一个“产品需求提示”Kraken用“保险库”Vault来组织不同领域的工作。我们从一个简单的“工作”领域项目开始。手动创建结构理解原理虽然可以用命令生成但手动创建一次能帮你理解其组织逻辑。# 在kraken目录下执行 mkdir -p vaults/work/projects/my-first-blog/{plans,tasks,execution,project} touch vaults/work/projects/my-first-blog/AGENTS.mdplans/: 存放你的指令文件.md。tasks/: 由AI代理自动生成的详细任务文件。execution/: 你编写的确定性脚本。project/: 实际的项目源代码、资源文件等。AGENTS.md: 该项目级别的代理指令文件可选用于覆盖或补充根目录的全局指令。使用/prp-new命令推荐实践现在在Cursor的Chat中输入/prp-newAI代理会启动一个交互式向导问你一系列结构化的问题来帮你定义需求。这个过程模拟了产品经理和技术负责人的对话代理问“Qual problema você quer resolver?” (你想解决什么问题)你答“我想创建一个个人博客系统用来发布技术文章避免依赖第三方平台。”代理问“É feature nova, bug fix, refatoração ou documentação?” (是新功能、修复Bug、重构还是文档)你答“新功能。”代理问“O que já existe hoje?” (现在有什么)你答“只有一个空的Node.js项目目录。”代理问“Tem restrições de prazo, orçamento ou tecnologia?” (有工期、预算或技术限制吗)你答“技术栈用Node.js Express SQLite 一个简单的前端如EJS或React。本周内完成核心功能。”代理问“Como você vai saber que está pronto?” (你怎么知道它完成了)你答“1. 能通过网页发布和查看Markdown文章。2. 支持代码高亮。3. 有简单的文章列表分页。”问答结束后代理会在plans/目录下生成一个类似prp_my-first-blog_20231027.md的文件。打开它你会看到一个非常专业的PRP文档包含了背景、目标、用户故事、功能需求、非功能需求、约束条件、成功标准和非需求等章节。注意事项/prp-new向导是葡萄牙语界面因为作者是巴西人但你可以直接用英语或中文回答AI都能理解。生成的文档语言取决于你回答使用的语言。这个交互过程的价值在于强迫你结构化地思考需求而不是东一榔头西一棒子地给AI下指令。3.3 任务分解与执行有了PRP之后AI代理就可以开始它的核心工作——分解。自动任务分解在Chat中你可以对代理说“基于刚生成的PRP请将其分解为可执行的任务。”或者直接使用相关的任务创建技能。代理会分析PRP中的功能点。识别任务间的依赖关系例如必须先创建数据库表才能实现文章创建API。为每个任务估算复杂度通常用故事点如1, 3, 5, 8。生成一系列task_*.md文件到tasks/目录。每个任务文件会描述具体步骤、输入、输出和验收标准。执行任务输入命令/execute代理会进入执行模式。它会扫描tasks/目录找到状态为“待办”的任务。按依赖顺序开始处理第一个任务。对于任务中的每个步骤它会判断是需要调用执行层脚本还是需要自己生成一些代码/配置。如果需要调用脚本它会去execution/目录寻找匹配的脚本并运行。如果脚本不存在它会提示你创建。如果需要生成代码它会在project/目录下创建或修改文件并给出解释。每一步执行后它会检查结果。如果运行脚本出错它会尝试分析日志并根据内置的调试技能给出修复建议。一个任务的所有步骤完成后将其标记为“完成”并自动开始下一个任务。在这个过程中你就像一个项目总监只需要在关键节点进行审查比如AI生成的代码架构是否合理而不需要介入每一个琐碎的细节比如创建package.json文件、写基本的CRUD路由。3.4 核心命令与防护栏实战Kraken提供了一系列开箱即用的命令它们是与AI代理协作的“快捷指令”。常用命令速查命令功能描述使用场景示例/boot初始化代理加载框架配置新打开项目时或感觉代理行为“失忆”时。/execute执行任务队列中的任务当你写好PRP和任务后启动自动化流程。/code-review对指定代码进行质量审查并打分在提交Git前检查AI生成的代码质量。/commit生成符合约定式提交的Git提交信息完成一个功能模块后快速规范化提交。/prp-new交互式创建产品需求提示开始任何一个新项目或新功能时。/prp-review评审并给已有的PRP打分让AI评估你的需求文档是否清晰、完整。/context status查看当前上下文存储使用情况当对话历史很长感觉AI反应变慢时。/context clean清理旧的上下文缓存文件定期维护释放磁盘空间。防护栏Guardrails——你的安全网这是Kraken最贴心的设计之一。它内置了一系列钩子Hooks在代理行动前后自动检查防止常见灾难。例如危险命令拦截如果AI生成的代码或建议的命令中包含rm -rf /或DROP TABLE users这种毁灭性操作会被立刻阻止并警告。调试代码检测提交代码前会自动检查是否有console.log、debugger等调试语句被意外留下。密钥泄露扫描会检查代码中是否硬编码了类似API_KEYsk-...的字符串。大文件预警如果一个文件超过500行代理会建议你进行拆分保持代码简洁。踩坑实录我曾让AI代理帮我清理一个临时目录它生成的命令是rm -rf ./tmp/*。这看起来没问题但Kraken的防护栏仍然弹出了警告要求我确认。我检查后发现当前工作目录符号链接指向了用户主目录而./tmp解析后变成了~/tmp里面有一些重要配置文件。防护栏的这次警告避免了一次数据丢失事故。教训是永远不要完全信任AI生成的任何文件操作命令防护栏是你的最后一道防线。4. 进阶技巧技能、上下文管理与自我增强当你熟悉了基础流程后Kraken的一些高级特性将能极大提升你的长期工作效率和系统健壮性。4.1 技能库为AI注入专业领域知识技能Skills是Kraken框架中比规则Rules更重量级的知识包。规则是简单的“该做”和“不该做”如“不要使用any”而技能是一整套解决特定问题的工作流程和深度指南。Kraken预置了十多个技能存放在.cursor/skills/目录下。每个技能都是一个详细的Markdown文件教导AI代理如何像专家一样处理某类问题。例如test-driven-development.md详细说明了TDD的红-绿-重构循环并给出了在具体语言如JavaScript/Python中的操作示例。systematic-debugging.md教导代理一套系统化的调试方法论1. 复现问题2. 定位范围3. 提出假设4. 实验验证5. 实施修复。code-simplifier.md指导代理在实现功能后如何审视代码进行重构以提升可读性和可维护性同时确保行为不变。如何使用技能你不需要主动调用。当AI代理在完成任务过程中遇到相关场景时它会自动去加载和参考对应的技能文件。比如当你要求它“用TDD的方式开发这个功能”它会去查阅test-driven-development.md技能然后按照里面描述的步骤来引导你或执行操作。创建自定义技能这是Kraken框架扩展性的体现。假设你团队有一套独特的API设计规范你可以将其封装成一个技能。# 使用内置的“技能创建器”技能 python3 .cursor/skills/skill-creator/scripts/init_skill.py our-api-guidelines --path .cursor/skills/这会在技能目录下创建一个our-api-guidelines.md的模板。你只需要用Markdown填写你的规范端点命名规则、状态码使用、错误响应格式、版本控制策略等。之后当代理需要设计API时就会遵循这份指南。4.2 动态上下文管理突破Token限制的智慧所有LLM都有上下文窗口限制。当对话和生成的内容太长时最早的信息会被“遗忘”。Kraken设计了一套巧妙的“上下文卸载”系统来解决这个问题。工作原理自动卸载当AI代理需要输出很长的内容如一份完整的项目报告、一大段生成的代码超过预设行数如50行时它不会把这些内容全部塞进回复里污染聊天上下文。外部存储它会将这些冗长的输出保存到context/目录下的特定文件中例如context/mcp/project_analysis_20231027.md。摘要引用在聊天中它只提供一个简短的摘要和一个指向该文件的引用链接如[完整报告已保存至: context/mcp/project_analysis_20231027.md]。按需读取当后续对话需要参考那份完整报告时代理可以主动去读取那个文件将必要的信息重新加载到上下文中。相关命令/context status查看context/目录下存储了哪些文件以及它们的大小和日期。帮你了解“记忆”的使用情况。/context clean清理超过一定天数如7天的旧上下文文件避免磁盘空间被无用历史占用。/context log手动记录一条重要的决策或结论到上下文历史中确保关键信息不被后续对话冲掉。这套机制使得Kraken能够处理非常复杂的、长周期的项目而不用担心AI“失忆”。4.3 自我增强从错误中学习的系统Kraken的“自我增强”Self-Annealing理念是其长期价值的核心。普通的AI助手今天犯的错明天还会再犯。但Kraken致力于让系统“越用越强”。自我增强循环错误发生一个执行层脚本运行失败或AI生成了不符合规则的代码。分析与修复AI代理借助调试技能分析错误原因。如果是脚本bug它可能会尝试修复脚本如果是自己的指令理解有误它会调整后续行动。更新资产关键一步代理不仅修复当前问题还会提议更新相关的“资产”。这可能包括更新执行脚本修复脚本中的Bug。更新指令在plans/的Markdown文件中增加一条新的约束或说明防止未来犯同样的错误。例如增加一条“注意调用XX API前必须检查网络连通性示例见execution/check_network.py。”创建新规则如果这是一个普遍性的问题甚至可以提议创建一条新的防护栏规则Rule。系统强化经过这个循环系统的知识库指令、脚本、规则都得到了增强。下次遇到类似情况犯错概率就会降低。这个过程不是完全自动的通常需要你的审核和确认。但它的意义在于将一次性的“故障修复”变成了系统性的“知识沉淀”。你的项目仓库不再仅仅是代码更是一个不断进化的、包含项目特定知识和经验的“智能体训练库”。5. 常见问题与故障排查指南在实际使用Kraken的过程中你可能会遇到一些典型问题。以下是我和社区成员遇到过的一些情况及其解决方案。5.1 代理不响应或命令无效症状在Cursor中输入/boot或其他命令没有反应或者AI回复说“我不理解这个命令”。排查步骤检查工作目录确保你的Cursor或Claude Code打开的是kraken框架的根目录而不是其子目录。命令和配置是从根目录加载的。确认配置文件检查.cursor/rules/或.claude/目录是否存在且包含文件。如果目录为空可能是克隆仓库不完整尝试重新git clone。重启AI会话有时IDE的AI会话会卡住。在Cursor中尝试关闭并重新打开Chat面板或者使用“New Chat”开始一个新的会话然后先输入/boot。检查API连接如果你在.env中配置了特定模型的API密钥确保网络通畅且API密钥有效、有余额。5.2 任务执行卡住或循环症状使用/execute后代理卡在某个步骤不断重复尝试或没有任何进展。排查步骤查看任务文件打开tasks/目录下对应的task_*.md文件检查该任务的步骤描述是否清晰、无歧义。模糊的指令会导致AI困惑。检查执行脚本如果任务步骤是调用execution/下的脚本请手动运行该脚本看是否能成功。脚本本身的Bug如语法错误、缺少依赖会导致代理一直收到失败反馈。审查代理的思考过程在Cursor中通常可以要求AI“展示你的思考步骤”或“为什么卡在这里了”。AI可能会输出它遇到的错误信息或逻辑困境。手动干预你可以直接修改任务文件将卡住的步骤描述得更具体或者暂时将其标记为“手动完成”然后让代理继续后续任务。5.3 生成的代码质量不高症状AI代理生成的代码虽然能运行但结构混乱、不符合最佳实践、或存在安全隐患。解决方案强化指令在plans/的指令文件中增加对代码质量的明确要求。例如“所有函数必须包含JSDoc/类型注解”、“遵循Airbnb JavaScript风格指南”、“必须进行错误处理”。使用/code-review命令生成代码后不要急着用先对相关文件运行/code-review命令。代理会使用内置的代码审查技能从可读性、性能、安全性等多个维度打分并提出修改建议。这是一个极好的学习机会。利用技能确保code-simplifier和documentation-standards等技能已被加载。你可以在Chat中明确要求“在实现后请应用代码简化技能优化一下。”迭代改进不要期望AI一次生成完美代码。将其视为一个“初级工程师”的初稿然后通过清晰的指令和审查引导它迭代改进。Kraken的流程支持这种快速迭代。5.4 上下文混乱或代理“失忆”症状在长时间、多任务的项目中AI代理似乎忘记了之前定好的规则或决策。解决方案善用/context命令定期使用/context status查看并使用/context log记录重要的架构决策或规则到context/history/中。这些记录可以被后续对话主动读取。结构化指令文件将长期有效的规则和约束写在plans/目录下的顶层指令文件里而不是仅仅在聊天中提及。AI在每次任务开始时都会重新读取这些文件。项目级 AGENTS.md在vaults/work/projects/你的项目/下创建AGENTS.md文件写入本项目特有的、需要AI始终牢记的指令。这个文件的优先级很高。适时重启对于超大型项目如果感觉代理状态不佳简单地输入/boot重新初始化可以刷新其上下文重新加载所有规则和技能。5.5 在团队中协作使用Kraken挑战如何让团队多个成员共享同一套Kraken配置和项目知识建议实践共享框架配置将定制化的.cursor/rules/、.cursor/skills/以及.claude/配置纳入团队代码库的版本控制。确保所有成员拉取最新配置后运行/boot。标准化Vault结构在团队内部约定vaults/目录的结构。例如可以按团队team-a/,team-b/或产品线product-x/,product-y/来划分领域。将指令文件作为需求文档plans/下的Markdown文件本身就是优秀的需求和设计文档。鼓励团队成员通过修改和评审这些文件来协作定义需求而不是依赖独立的需求管理工具。代码审查集成将/code-review作为团队代码提交前的强制步骤。可以将其集成到Git的pre-commit钩子中或者作为CI/CD流水线的一环。积累团队技能将团队在特定技术栈如内部框架、微服务通信规范上的最佳实践封装成自定义技能Skills放入共享的技能库中。新成员加入后AI代理也能立即具备这些“团队知识”。Kraken不仅仅是一个个人生产力工具当它的模式、指令和技能成为团队共识后它能有效地将团队的最佳实践固化下来并通AI代理这个“永不疲倦的助手”传递给每一个成员从而提升整个团队的交付质量和效率。它带来的是一种工作范式的转变从人与机器的简单问答升级为一种基于清晰契约和自动化流程的深度协作。
Kraken框架：三层架构实现AI代理的确定性工作流
1. 项目概述Kraken一个让AI代理成为可靠工作伙伴的框架如果你和我一样在日常工作中深度依赖像ChatGPT、Claude这类大语言模型LLM来辅助编码、写文档、拆解任务那你一定也经历过那种“薛定谔的准确率”带来的焦虑。你写了一个详细的提示词让它生成一个功能模块它可能前两步做得很好第三步就开始自由发挥凭空捏造一个不存在的API或者把逻辑搞得一团糟。你不得不像个监工一样时刻盯着它的输出手动纠正每一个偏离轨道的细节。这种工作模式与其说是“智能辅助”不如说是“人工纠错”效率低下且充满不确定性。这正是Kraken框架要解决的核心痛点。它不是一个全新的AI模型而是一个工作流框架一种工程化思维。它的核心理念非常直接既然LLM天生是概率性的、擅长规划和决策但容易在执行细节上“幻觉”那我们就把“规划决策”和“具体执行”彻底分开。让AI做它最擅长的事——理解意图、拆解任务、做出判断而把那些需要精确、确定、可重复的操作交给由我们人类编写的、确定性的脚本去完成。简单来说Kraken帮你建立了一套“人机协作”的标准化流程。你不再是那个对着聊天窗口不停追问和纠正的“唠叨老板”而是变成了一个制定战略方针的“指挥官”。你负责在指令层Directive用Markdown写下清晰的目标和规则“我们要攻下这个山头注意东侧有河流必须在三日内完成”AI代理在编排层Orchestration解读你的指令决定每一步该调用什么工具“派工兵架桥步兵从侧翼包抄”最后具体的执行层Execution由你预先写好的Python、TypeScript等脚本可靠地运行“架桥脚本”、“包抄路线计算脚本”。这套架构带来的最大好处是可信度。一个复杂的项目往往包含数十个步骤。如果每个步骤LLM的独立准确率是90%这已经非常乐观了那么连续5个步骤都正确的概率会骤降到约59%。如果是10个步骤成功率会跌到35%以下。Kraken通过将关键执行步骤固化到脚本中将这个概率游戏的链条打断确保每一个“动作”都是100%可靠的。AI的“幻觉”被限制在了规划和决策环节而这个环节的错误更容易通过结构化的指令和规则Kraken内置的Guardrails来防范和纠正。无论你是需要管理复杂产品需求的产品经理是每天与代码搏斗的开发者还是利用AI进行创意工作的设计师只要你希望将AI从“一个有时靠谱的聊天伙伴”升级为“一个可预测、可管理、可集成的生产系统组件”Kraken都值得你花时间深入了解。它提供的不是魔法而是一套让你能稳定释放AI潜力的工程学工具箱。2. 核心架构解析三层分离如何根治AI的“不靠谱”Kraken的威力根植于其清晰的三层架构设计。理解这三层各自的责任和交互方式是掌握这个框架的关键。这不仅仅是三个文件夹而是三种截然不同的责任边界是“人机共舞”的舞台分区。2.1 指令层人类智慧的结晶区指令层是你的“作战指挥部”。它位于/vaults/领域/projects/项目名/plans/目录下其载体是纯文本的Markdown文件。在这里你不需要任何编程知识只需要用清晰、结构化的人类语言描述清楚以下几件事目标与愿景这个项目最终要达成什么状态成功的画面是什么样的输入与约束我们手头有什么材料数据、API、现有代码有哪些不可逾越的红线技术栈限制、截止日期、性能要求输出与验收标准我们具体要交付哪些东西功能列表、API文档、测试用例如何判断每项交付物是合格的非功能性需求安全性、可维护性、性能指标等。为什么是Markdown因为它足够简单、通用且能被AI很好地理解。你写下的每一个标题、列表和加粗文本都是在为AI代理构建一个清晰的心智模型。一个优秀的指令文件读起来应该像一份精简版的PRD产品需求文档或技术方案它定义了“做什么”和“为什么做”但不涉及“怎么做”。实操心得在编写指令时我习惯采用“背景-问题-解决方案-验收标准”的经典叙事结构。避免使用模糊的形容词如“快速的”、“友好的”而是使用可量化的描述如“API响应时间P95 200ms”、“错误提示文案需在10个词以内”。这能极大减少AI的理解偏差。2.2 编排层AI代理的决策引擎这一层是Kraken框架的“大脑”由AI代理在Cursor或Claude Code中运行主动运作。它的工作流程是确定性的解析指令读取你写在plans/目录下的Markdown文件理解整体目标和所有约束条件。任务分解将宏大的目标拆解成一系列具体的、可执行的原子任务Task。每个任务会包含明确的输入、操作步骤和预期输出描述。工具调用决策为每个原子任务判断应该调用哪个执行层脚本。例如任务描述是“在数据库表X中插入测试数据”代理就会决定调用execution/目录下的populate_test_data.py脚本。错误处理与状态管理执行过程中如果脚本报错代理不会不知所措而是会根据预定义的规则Rules尝试分析错误日志决定是重试、回滚还是上报给人类。同时它会更新任务状态如“进行中”、“阻塞”、“已完成”。这一层的核心价值在于“路由”和“协调”。它像一个经验丰富的项目经理虽然自己不写代码但知道每个任务该派给哪个专家脚本并能处理任务间的依赖和异常。Kraken通过大量的预置规则Rules和技能Skills来“武装”这个代理让它具备代码审查、系统调试、TDD引导等专业能力。2.3 执行层确定性脚本的堡垒这是整个系统的“手脚”是可靠性的基石。它位于/vaults/领域/projects/项目名/execution/目录里面存放的是标准的、你亲手编写或审核过的程序脚本Python、JavaScript/TypeScript、Shell等。这些脚本的特点是确定性给定相同的输入永远产生相同的输出。没有随机性没有“大概可能也许”。可测试你可以为它们编写单元测试和集成测试确保其行为符合预期。专注单一职责一个脚本最好只做一件事并且把它做好。例如generate_api_client.py就只负责根据OpenAPI规范生成客户端代码不负责启动服务器。当编排层的AI代理决定调用execution/下的某个脚本时它会以子进程的方式运行该脚本并捕获其输出标准输出、标准错误和退出码。脚本执行的成功与否完全由脚本自身的逻辑和退出码决定AI无法篡改结果。三层之间的数据流可以用一个简单的例子串联你想搭建一个博客系统。指令层你在plans/blog-setup.md中写下“目标搭建一个基于Node.js的Markdown博客。需求支持文章列表、分页、代码高亮。约束使用SQLite数据库UI简洁。”编排层AI代理读取该指令将其分解为任务T1-初始化项目T2-创建数据库模式T3-实现文章CRUD APIT4-实现前端列表页……执行层对于任务T2代理调用你预先写好的execution/init_database.sql脚本这个脚本包含创建posts表的确定SQL语句。执行成功代理将T2标记为完成并继续T3。通过这种分离你将AI的创造力规划、拆解、决策与机器的精确性脚本执行完美结合同时将风险AI幻觉隔离在了可控的、高层次的决策环节。3. 从零开始搭建你的第一个Kraken项目理论说得再多不如亲手跑一遍。下面我将带你完整地走一遍初始化并运行一个Kraken项目的流程其中会穿插我踩过的一些坑和总结的技巧。3.1 环境准备与框架安装Kraken的设计是IDE/编辑器无关的但它深度集成了Cursor和Claude Code这两个目前对AI编码辅助支持最好的工具。你需要至少准备其中一个。基础环境Node.js ( 18.x)和Python ( 3.10)这是运行许多自动化脚本的基石。建议使用nvm和pyenv来管理版本避免全局冲突。Git代码版本管理必不可少。Cursor IDE从官网下载安装。它内置了优秀的AI助手是运行Kraken的“主战场”之一。Claude Code (可选)Anthropic提供的命令行工具如果你更喜欢在终端里工作它是绝佳选择。安装Kraken框架安装过程极其简单因为它本质上是一套配置文件和约定。# 克隆仓库到本地 git clone https://github.com/luisabwk/kraken.git cd kraken # 复制环境变量示例文件如果需要配置API密钥等 cp .env.example .env # 编辑 .env 文件填入你的OpenAI或Anthropic API密钥如果你需要代理使用特定的模型此时你的kraken目录下已经包含了完整的框架结构.cursor和.claude配置文件夹、示例的vaults等。关键一步启动Boot在Cursor中打开这个kraken项目根目录。然后在Chat面板中简单地输入命令/boot这个命令是Kraken的“开机键”。它会做以下几件事检查项目目录结构是否符合预期。加载所有预定义的规则Rules、技能Skills和防护栏Hooks。向AI代理“灌输”Kraken的工作哲学和操作指南。输出当前可用的命令列表和项目状态。如果你看到代理回复了一系列可用的命令如/execute,/prp-new和一个友好的欢迎信息恭喜你Kraken已经成功唤醒。3.2 创建项目结构与第一个“产品需求提示”Kraken用“保险库”Vault来组织不同领域的工作。我们从一个简单的“工作”领域项目开始。手动创建结构理解原理虽然可以用命令生成但手动创建一次能帮你理解其组织逻辑。# 在kraken目录下执行 mkdir -p vaults/work/projects/my-first-blog/{plans,tasks,execution,project} touch vaults/work/projects/my-first-blog/AGENTS.mdplans/: 存放你的指令文件.md。tasks/: 由AI代理自动生成的详细任务文件。execution/: 你编写的确定性脚本。project/: 实际的项目源代码、资源文件等。AGENTS.md: 该项目级别的代理指令文件可选用于覆盖或补充根目录的全局指令。使用/prp-new命令推荐实践现在在Cursor的Chat中输入/prp-newAI代理会启动一个交互式向导问你一系列结构化的问题来帮你定义需求。这个过程模拟了产品经理和技术负责人的对话代理问“Qual problema você quer resolver?” (你想解决什么问题)你答“我想创建一个个人博客系统用来发布技术文章避免依赖第三方平台。”代理问“É feature nova, bug fix, refatoração ou documentação?” (是新功能、修复Bug、重构还是文档)你答“新功能。”代理问“O que já existe hoje?” (现在有什么)你答“只有一个空的Node.js项目目录。”代理问“Tem restrições de prazo, orçamento ou tecnologia?” (有工期、预算或技术限制吗)你答“技术栈用Node.js Express SQLite 一个简单的前端如EJS或React。本周内完成核心功能。”代理问“Como você vai saber que está pronto?” (你怎么知道它完成了)你答“1. 能通过网页发布和查看Markdown文章。2. 支持代码高亮。3. 有简单的文章列表分页。”问答结束后代理会在plans/目录下生成一个类似prp_my-first-blog_20231027.md的文件。打开它你会看到一个非常专业的PRP文档包含了背景、目标、用户故事、功能需求、非功能需求、约束条件、成功标准和非需求等章节。注意事项/prp-new向导是葡萄牙语界面因为作者是巴西人但你可以直接用英语或中文回答AI都能理解。生成的文档语言取决于你回答使用的语言。这个交互过程的价值在于强迫你结构化地思考需求而不是东一榔头西一棒子地给AI下指令。3.3 任务分解与执行有了PRP之后AI代理就可以开始它的核心工作——分解。自动任务分解在Chat中你可以对代理说“基于刚生成的PRP请将其分解为可执行的任务。”或者直接使用相关的任务创建技能。代理会分析PRP中的功能点。识别任务间的依赖关系例如必须先创建数据库表才能实现文章创建API。为每个任务估算复杂度通常用故事点如1, 3, 5, 8。生成一系列task_*.md文件到tasks/目录。每个任务文件会描述具体步骤、输入、输出和验收标准。执行任务输入命令/execute代理会进入执行模式。它会扫描tasks/目录找到状态为“待办”的任务。按依赖顺序开始处理第一个任务。对于任务中的每个步骤它会判断是需要调用执行层脚本还是需要自己生成一些代码/配置。如果需要调用脚本它会去execution/目录寻找匹配的脚本并运行。如果脚本不存在它会提示你创建。如果需要生成代码它会在project/目录下创建或修改文件并给出解释。每一步执行后它会检查结果。如果运行脚本出错它会尝试分析日志并根据内置的调试技能给出修复建议。一个任务的所有步骤完成后将其标记为“完成”并自动开始下一个任务。在这个过程中你就像一个项目总监只需要在关键节点进行审查比如AI生成的代码架构是否合理而不需要介入每一个琐碎的细节比如创建package.json文件、写基本的CRUD路由。3.4 核心命令与防护栏实战Kraken提供了一系列开箱即用的命令它们是与AI代理协作的“快捷指令”。常用命令速查命令功能描述使用场景示例/boot初始化代理加载框架配置新打开项目时或感觉代理行为“失忆”时。/execute执行任务队列中的任务当你写好PRP和任务后启动自动化流程。/code-review对指定代码进行质量审查并打分在提交Git前检查AI生成的代码质量。/commit生成符合约定式提交的Git提交信息完成一个功能模块后快速规范化提交。/prp-new交互式创建产品需求提示开始任何一个新项目或新功能时。/prp-review评审并给已有的PRP打分让AI评估你的需求文档是否清晰、完整。/context status查看当前上下文存储使用情况当对话历史很长感觉AI反应变慢时。/context clean清理旧的上下文缓存文件定期维护释放磁盘空间。防护栏Guardrails——你的安全网这是Kraken最贴心的设计之一。它内置了一系列钩子Hooks在代理行动前后自动检查防止常见灾难。例如危险命令拦截如果AI生成的代码或建议的命令中包含rm -rf /或DROP TABLE users这种毁灭性操作会被立刻阻止并警告。调试代码检测提交代码前会自动检查是否有console.log、debugger等调试语句被意外留下。密钥泄露扫描会检查代码中是否硬编码了类似API_KEYsk-...的字符串。大文件预警如果一个文件超过500行代理会建议你进行拆分保持代码简洁。踩坑实录我曾让AI代理帮我清理一个临时目录它生成的命令是rm -rf ./tmp/*。这看起来没问题但Kraken的防护栏仍然弹出了警告要求我确认。我检查后发现当前工作目录符号链接指向了用户主目录而./tmp解析后变成了~/tmp里面有一些重要配置文件。防护栏的这次警告避免了一次数据丢失事故。教训是永远不要完全信任AI生成的任何文件操作命令防护栏是你的最后一道防线。4. 进阶技巧技能、上下文管理与自我增强当你熟悉了基础流程后Kraken的一些高级特性将能极大提升你的长期工作效率和系统健壮性。4.1 技能库为AI注入专业领域知识技能Skills是Kraken框架中比规则Rules更重量级的知识包。规则是简单的“该做”和“不该做”如“不要使用any”而技能是一整套解决特定问题的工作流程和深度指南。Kraken预置了十多个技能存放在.cursor/skills/目录下。每个技能都是一个详细的Markdown文件教导AI代理如何像专家一样处理某类问题。例如test-driven-development.md详细说明了TDD的红-绿-重构循环并给出了在具体语言如JavaScript/Python中的操作示例。systematic-debugging.md教导代理一套系统化的调试方法论1. 复现问题2. 定位范围3. 提出假设4. 实验验证5. 实施修复。code-simplifier.md指导代理在实现功能后如何审视代码进行重构以提升可读性和可维护性同时确保行为不变。如何使用技能你不需要主动调用。当AI代理在完成任务过程中遇到相关场景时它会自动去加载和参考对应的技能文件。比如当你要求它“用TDD的方式开发这个功能”它会去查阅test-driven-development.md技能然后按照里面描述的步骤来引导你或执行操作。创建自定义技能这是Kraken框架扩展性的体现。假设你团队有一套独特的API设计规范你可以将其封装成一个技能。# 使用内置的“技能创建器”技能 python3 .cursor/skills/skill-creator/scripts/init_skill.py our-api-guidelines --path .cursor/skills/这会在技能目录下创建一个our-api-guidelines.md的模板。你只需要用Markdown填写你的规范端点命名规则、状态码使用、错误响应格式、版本控制策略等。之后当代理需要设计API时就会遵循这份指南。4.2 动态上下文管理突破Token限制的智慧所有LLM都有上下文窗口限制。当对话和生成的内容太长时最早的信息会被“遗忘”。Kraken设计了一套巧妙的“上下文卸载”系统来解决这个问题。工作原理自动卸载当AI代理需要输出很长的内容如一份完整的项目报告、一大段生成的代码超过预设行数如50行时它不会把这些内容全部塞进回复里污染聊天上下文。外部存储它会将这些冗长的输出保存到context/目录下的特定文件中例如context/mcp/project_analysis_20231027.md。摘要引用在聊天中它只提供一个简短的摘要和一个指向该文件的引用链接如[完整报告已保存至: context/mcp/project_analysis_20231027.md]。按需读取当后续对话需要参考那份完整报告时代理可以主动去读取那个文件将必要的信息重新加载到上下文中。相关命令/context status查看context/目录下存储了哪些文件以及它们的大小和日期。帮你了解“记忆”的使用情况。/context clean清理超过一定天数如7天的旧上下文文件避免磁盘空间被无用历史占用。/context log手动记录一条重要的决策或结论到上下文历史中确保关键信息不被后续对话冲掉。这套机制使得Kraken能够处理非常复杂的、长周期的项目而不用担心AI“失忆”。4.3 自我增强从错误中学习的系统Kraken的“自我增强”Self-Annealing理念是其长期价值的核心。普通的AI助手今天犯的错明天还会再犯。但Kraken致力于让系统“越用越强”。自我增强循环错误发生一个执行层脚本运行失败或AI生成了不符合规则的代码。分析与修复AI代理借助调试技能分析错误原因。如果是脚本bug它可能会尝试修复脚本如果是自己的指令理解有误它会调整后续行动。更新资产关键一步代理不仅修复当前问题还会提议更新相关的“资产”。这可能包括更新执行脚本修复脚本中的Bug。更新指令在plans/的Markdown文件中增加一条新的约束或说明防止未来犯同样的错误。例如增加一条“注意调用XX API前必须检查网络连通性示例见execution/check_network.py。”创建新规则如果这是一个普遍性的问题甚至可以提议创建一条新的防护栏规则Rule。系统强化经过这个循环系统的知识库指令、脚本、规则都得到了增强。下次遇到类似情况犯错概率就会降低。这个过程不是完全自动的通常需要你的审核和确认。但它的意义在于将一次性的“故障修复”变成了系统性的“知识沉淀”。你的项目仓库不再仅仅是代码更是一个不断进化的、包含项目特定知识和经验的“智能体训练库”。5. 常见问题与故障排查指南在实际使用Kraken的过程中你可能会遇到一些典型问题。以下是我和社区成员遇到过的一些情况及其解决方案。5.1 代理不响应或命令无效症状在Cursor中输入/boot或其他命令没有反应或者AI回复说“我不理解这个命令”。排查步骤检查工作目录确保你的Cursor或Claude Code打开的是kraken框架的根目录而不是其子目录。命令和配置是从根目录加载的。确认配置文件检查.cursor/rules/或.claude/目录是否存在且包含文件。如果目录为空可能是克隆仓库不完整尝试重新git clone。重启AI会话有时IDE的AI会话会卡住。在Cursor中尝试关闭并重新打开Chat面板或者使用“New Chat”开始一个新的会话然后先输入/boot。检查API连接如果你在.env中配置了特定模型的API密钥确保网络通畅且API密钥有效、有余额。5.2 任务执行卡住或循环症状使用/execute后代理卡在某个步骤不断重复尝试或没有任何进展。排查步骤查看任务文件打开tasks/目录下对应的task_*.md文件检查该任务的步骤描述是否清晰、无歧义。模糊的指令会导致AI困惑。检查执行脚本如果任务步骤是调用execution/下的脚本请手动运行该脚本看是否能成功。脚本本身的Bug如语法错误、缺少依赖会导致代理一直收到失败反馈。审查代理的思考过程在Cursor中通常可以要求AI“展示你的思考步骤”或“为什么卡在这里了”。AI可能会输出它遇到的错误信息或逻辑困境。手动干预你可以直接修改任务文件将卡住的步骤描述得更具体或者暂时将其标记为“手动完成”然后让代理继续后续任务。5.3 生成的代码质量不高症状AI代理生成的代码虽然能运行但结构混乱、不符合最佳实践、或存在安全隐患。解决方案强化指令在plans/的指令文件中增加对代码质量的明确要求。例如“所有函数必须包含JSDoc/类型注解”、“遵循Airbnb JavaScript风格指南”、“必须进行错误处理”。使用/code-review命令生成代码后不要急着用先对相关文件运行/code-review命令。代理会使用内置的代码审查技能从可读性、性能、安全性等多个维度打分并提出修改建议。这是一个极好的学习机会。利用技能确保code-simplifier和documentation-standards等技能已被加载。你可以在Chat中明确要求“在实现后请应用代码简化技能优化一下。”迭代改进不要期望AI一次生成完美代码。将其视为一个“初级工程师”的初稿然后通过清晰的指令和审查引导它迭代改进。Kraken的流程支持这种快速迭代。5.4 上下文混乱或代理“失忆”症状在长时间、多任务的项目中AI代理似乎忘记了之前定好的规则或决策。解决方案善用/context命令定期使用/context status查看并使用/context log记录重要的架构决策或规则到context/history/中。这些记录可以被后续对话主动读取。结构化指令文件将长期有效的规则和约束写在plans/目录下的顶层指令文件里而不是仅仅在聊天中提及。AI在每次任务开始时都会重新读取这些文件。项目级 AGENTS.md在vaults/work/projects/你的项目/下创建AGENTS.md文件写入本项目特有的、需要AI始终牢记的指令。这个文件的优先级很高。适时重启对于超大型项目如果感觉代理状态不佳简单地输入/boot重新初始化可以刷新其上下文重新加载所有规则和技能。5.5 在团队中协作使用Kraken挑战如何让团队多个成员共享同一套Kraken配置和项目知识建议实践共享框架配置将定制化的.cursor/rules/、.cursor/skills/以及.claude/配置纳入团队代码库的版本控制。确保所有成员拉取最新配置后运行/boot。标准化Vault结构在团队内部约定vaults/目录的结构。例如可以按团队team-a/,team-b/或产品线product-x/,product-y/来划分领域。将指令文件作为需求文档plans/下的Markdown文件本身就是优秀的需求和设计文档。鼓励团队成员通过修改和评审这些文件来协作定义需求而不是依赖独立的需求管理工具。代码审查集成将/code-review作为团队代码提交前的强制步骤。可以将其集成到Git的pre-commit钩子中或者作为CI/CD流水线的一环。积累团队技能将团队在特定技术栈如内部框架、微服务通信规范上的最佳实践封装成自定义技能Skills放入共享的技能库中。新成员加入后AI代理也能立即具备这些“团队知识”。Kraken不仅仅是一个个人生产力工具当它的模式、指令和技能成为团队共识后它能有效地将团队的最佳实践固化下来并通AI代理这个“永不疲倦的助手”传递给每一个成员从而提升整个团队的交付质量和效率。它带来的是一种工作范式的转变从人与机器的简单问答升级为一种基于清晰契约和自动化流程的深度协作。
