Ekko Agent Spike 技能实战：用最小可运行原型验证技术可行性并输出证据化裁决

AI 应用人工智能AI Agent本地部署前端后端工作流自动化【免费下载链接】ekko-studioEkko Studio is a local-first AI workspace for multi-agent chat, coding, and visual workflows, available on desktop and the web.项目地址https://gitcode.com/gh_mirrors/he/ekko-studio点击查看免费下载导读本文围绕 Ekko Agent 内置的spike技能packages/ekko-agent/skills/spike/SKILL.md讲解如何在多智能体工作区中通过一次性原型throwaway prototype快速验证技术想法的可行性、对比多个候选方案、量化风险并输出证据化结论。读完本文你将掌握 spike 的完整五步循环、工作区规范与多问题拆分策略理解VALIDATED / PARTIAL / INVALIDATED三级裁决模板的用法并从源码层面了解 Ekko Agent 的skill_view、skill_manage、code_exec、terminal_exec等工具如何支撑一次可复现的 spike 实验。什么是 Spike先验证再决定要不要正式开发spike是 Ekko Agent 的技能体系中的一类探索性技能。它的定位很明确当用户希望在投入正式生产代码之前先验证一个想法时使用。典型触发场景包括spike this先做技术试点quick prototype快速原型is this possible这个可行吗compare A and B对比方案 A 和 Bbefore we build开工之前与之相对的禁用场景同样清晰如果问题可以通过阅读文档或检查源码直接回答或者用户明确要求的是生产级实现就不应该启动 spike。这个边界写在该技能文档的开头是判断是否调用 spike 的第一道关卡。在 Ekko Agent 的技能路由机制中这个边界会被系统性地执行运行时只会向模型注入当前 Profile 可用的技能名称模型需要把任意语言的请求映射到某个技能名然后调用skill_view加载完整指令。也就是说spike 技能是否被启用取决于模型能否把用户的先做个原型试试这类意图正确路由到spike这个名字上。这与技能发现中的关键字匹配是两套并行的机制——关键字仅用于宿主侧的确定性硬匹配多语言意图路由由主模型承担见 packages/ekko-agent/src/skills/types.ts 与 skill-creator 技能文档。Spike 五步循环从问题陈述到证据化结论spike 技能定义了一个高度收敛的五步循环Loop这是整个技能的灵魂陈述具体的可行性问题State the concrete feasibility question把模糊的试一下收敛成一个可以证伪的、具体的技术问题阅读足够的文档或源码选择可信的技术路线不重复造轮子先从已有资料中确定一个有依据的方向创建能够验证或推翻该想法的最小可运行工件smallest runnable artifact这是 spike 的核心产物验证一个重要的边界情况或失败模式不能只跑快乐路径必须主动触碰风险点输出VALIDATED、PARTIAL或INVALIDATED裁决用证据而非印象下结论。这套循环的设计哲学是小步快跑、证据驱动。第三步中的最小可运行工件是整篇文章的关键判断标准——它的目的是验证而不是交付。最小可运行工件的形态选择该技能文档明确给出了工件形态的优先级建议可运行的 CLI 脚本runnable CLI极简的 HTML 页面tiny HTML page单个接口one endpoint一个聚焦的测试focused test这四种形态恰好对应了 Ekko Agent 运行时内置的执行工具从源码实现看它们形成了天然的支撑链CLI 脚本 / 单条命令由 terminal_exec 工具 承载。它默认 30 秒超时DEFAULT_TERMINAL_EXEC_TIMEOUT_MSstdout 上限 100KB、stderr 上限 25KB并把命令放入 session 工作区的临时目录执行同时注入TMPDIR/TMP/TEMP环境变量见 workspace-temp.ts避免临时文件污染主工作区。一次性的 Node.js / Python 脚本由 code_exec 工具 承载。它把源码写入code-exec-*临时目录后以无 shell 方式执行支持node与python两种语言并且只允许脚本内部回调read_file、write_file、terminal_exec三个白名单工具CODE_EXEC_ALLOWED_TOOLS。这正好支撑一个聚焦的测试这类工件——在 spike 脚本里读输入、执行命令、输出测量结果。聚焦测试既可以用上面的 code_exec 快速跑断言也可以在项目测试体系中落地。刻意排除的重量级手段技能文档同样列出了 spike 应该避免的东西包膨胀package sprawlDocker环境变量文件environment files应用框架app frameworks生产级清理逻辑production cleanup原因很直接这些都会让最小原型膨胀成半个生产系统拖慢验证节奏、模糊实验变量。从 code_exec.ts 的实现看运行时会限制脚本内部的嵌套工具调用数量、限制源码与输出大小、并在超时或中断时强杀子进程这些约束本身就逼迫 spike 保持小。工作区规范一次性工作放哪里spike 技能对工作区使用给出了明确的两种选择默认.tmp/spikes/slug默认情况下spike 的全部临时产物放在相对工作区的.tmp/spikes/slug目录下slug是本次 spike 的简短英文标识例如ffmpeg-seek-accuracy。这个目录是可丢弃的实验结束后不需要维护。值得说明的是Ekko Agent 的运行时层还有一个平行的临时目录机制workspaceTempRoot()会在workspaceRoot下创建.ekko-tmp目录无工作区时回退到系统临时目录terminal_exec与code_exec都会把命令产物、日志工件、脚本暂存区放进这里并自动写入.gitignore防止误提交见 workspace-temp.ts。技能文档约定的.tmp/spikes/slug是 spike 实验自身的产物目录二者职责不同但理念一致临时的东西必须待在明确的、可清理的、不会被版本管理误收的角落里。可选spikes/NNN-slug/受管目录仅当用户明确要求保留原型时才使用受版本管理的spikes/NNN-slug/目录其中NNN是递增编号。保留版的要求更高必须带 README说明问题、结论、如何运行代码保持最小化目录风格与一次性形成对比——一旦进入受管目录就意味着它要接受后续的审阅甚至重写。多问题拆分两到五个独立 spike风险最高的先做真实世界里一次对比 A 和 B的需求往往不止一个问题。技能文档给出的策略是把多个问题拆成2 到 5 个相互独立的 spike先做风险最高的那个——因为只有风险最高的方向被验证后其余问题才有意义保持 A/B 的输入与测量条件完全对等——比较才有说服力当工作不再小时构建每个变体之前先询问用户——避免在用户没有确认的范围里无限扩张。这条策略对应了一个工程常识spike 的数量一旦超过五个或者单个 spike 的规模失控说明问题空间还没有被充分收敛此时应该回到第一步重新陈述可行性问题而不是继续堆原型。Verdict 裁决模板让结论可复现、可引用spike 的最终产出是一个结构化裁决块技能文档给出了完整模板## Verdict: VALIDATED | PARTIAL | INVALIDATED Question: ... Evidence: exact command, output, or measurement. What worked: ... What failed or surprised us: ... Recommendation: ship, adjust, or avoid, with the next production step.逐字段解读其设计意图Question回溯第一步陈述的可行性问题保证结论与问题一一对应Evidence必须给出精确的命令、输出或测量值而不是看起来可以这类印象。这是整个模板的证据核心也是裁决可被他人复核的关键What worked记录验证成功的部分What failed or surprised us记录失败模式与意外发现——spike 的价值往往藏在这里Recommendation给出明确建议ship / adjust / avoid并带上下一步的生产动作。反直觉的结论INVALIDATED 同样有价值技能文档特别强调一个被证伪的 spikeINVALIDATED同样是有价值的产出——它用证据排除了一条路径避免了后续在错误方向上投入生产开发。这与原型失败工作失败的直觉相反正是 spike 方法论的核心价值失败被量化、被记录、被归档而不是被遗忘。一次性代码绝不直接进生产裁决模板之外还有一条铁律可丢弃的 spike 代码未经按生产标准重写绝不并入生产代码。spike 的产物是证据不是交付物。这与 skill-creator 中不要把一个一次性答案变成永久技能的告诫互为镜像——两者都在维护探索产物与持久资产之间的边界。评估第三方依赖时的检查清单当 spike 需要引入第三方依赖时技能文档要求评估四个维度维护活跃度maintenance activity项目是否还在迭代文档质量documentation能否支撑快速上手与排错许可证license是否符合使用场景安装摩擦install friction依赖链是否轻量、是否容易在目标环境安装。这四个维度与 Ekko Agent 自身的依赖策略一致例如文档类技能pdf、docx、xlsx 等都把 Python/LibreOffice/Poppler/OCR 等可选依赖推迟到使用时才检查而不是在启动阶段强制安装见 packages/ekko-agent/README.md。spike 阶段的依赖评估越严格正式阶段踩坑越少。Spike 与后台技能审查探索与沉淀的分工理解 spike 的定位还需要把它放在 Ekko Agent 的整个技能生命周期中看。仓库里存在另一套与 spike 形成对照的机制后台程序性学习审查review.ts。spike 是向前探索面对未知问题产出一次性原型和证据化裁决产出物默认丢弃后台审查是向后沉淀会话每累计 10 次工具调用后运行时会以保守提示词调度一个后台审查只允许使用skill_list、skill_view、skill_manage三个工具判断本轮是否产生了可复用、非一次性的过程知识并据此创建或更新类级别的技能。两者配合的边界在于spike 的结论若要变成可复用资产必须经过审慎的判断而不是直接把原型代码或实验过程灌进技能库。这也解释了为什么 skill-creator 反复强调一个一次性答案、临时 workaround 不应变成永久技能。从源码层面看spike 作为内置技能还受到内置技能保护机制约束它以包自带方式安装到每个 Profile用户改动过的同名技能不会被覆盖且内置技能不可被删除见 builtin-skills.test.ts 与 skills.ts 中archiveSkill对builtIn的检查。一次完整的 spike 会话推演把上述规范串起来一次符合该技能要求的典型 spike 会话如下示意命令以仓库环境为准路由与加载用户说先做个 spike 验证下用 Python 提取 PDF 表格行不行。主模型把意图映射到spike技能名调用skill_view加载 SKILL.md也可先用skill_list兜底发现陈述问题可行性问题被写成用 PyMuPDF 能否从样例 PDF 中无损提取三线表结构查阅资料技能文档、依赖维护情况、许可证与安装方式最小工件用code_exec写一个 Python 片段或先用terminal_exec探测运行环境python3 -c import fitz; print(fitz.__doc__)边界验证换一个带合并单元格、跨页表格的样例再跑一次确认失败模式裁决按模板输出PARTIAL——文本提取可用但合并单元格的坐标关系不稳定建议改为基于标记文本解析的方案并附上精确命令与输出清理临时产物留在.tmp/spikes/pdf-table-extract/不进入受管目录不并入生产代码。关键源码索引技能本体packages/ekko-agent/skills/spike/SKILL.md技能管理器register/view/create/patch/delete 入口packages/ekko-agent/src/skills/manager.ts技能工具实现skill_list/skill_view/skill_manage、读前写保护、备份与归档packages/ekko-agent/src/tools/skills.ts一次性脚本执行Node/Python、白名单工具、超时与输出上限packages/ekko-agent/src/tools/code-exec.ts命令执行与输出工件落盘packages/ekko-agent/src/tools/terminal.ts临时工作区.ekko-tmp与TMPDIR注入packages/ekko-agent/src/tools/workspace-temp.ts后台技能审查与 spike 互补的程序性学习packages/ekko-agent/src/skills/review.ts技能创建与维护规范packages/ekko-agent/skills/skill-creator/SKILL.md技能工具测试关键字硬匹配、读前写保护、备份归档行为tests/ekko-agent/skill-tools.test.ts内置技能同步测试含 spike 的安装与用户改动保护tests/ekko-agent/builtin-skills.test.ts总结Ekko Agent 的 spike 技能把先验证再开发从一句口号变成了一套可执行的工程方法五步循环收敛问题、最小可运行工件作为验证载体、.tmp/spikes/slug与spikes/NNN-slug/两条工作区路径划分一次性与保留产物、VALIDATED / PARTIAL / INVALIDATED三级裁决模板沉淀证据化结论、依赖四维检查清单控制外部风险。它与后台技能审查、skill-creator 共同构成了探索—验证—沉淀的完整闭环让每一次技术可行性判断都有据可查、可复现、可引用。赞分享AI 应用人工智能AI Agent本地部署前端后端工作流自动化【免费下载链接】ekko-studioEkko Studio is a local-first AI workspace for multi-agent chat, coding, and visual workflows, available on desktop and the web.项目地址https://gitcode.com/gh_mirrors/he/ekko-studio点击查看免费下载相关推荐OpenHarness 内置 test 技能指南让 Agent 写出高质量、可运行、可验证的测试OpenHarness 内置 test 技能指南让 Agent 写出高质量、可运行、可验证的测试 本指南以 OpenHarness 内置技能 test.md人工智能AI AgentAgent 框架代码智能体工具调用MCP 服务Agent 记忆多智能体PydanticAI Agent 开发 PRP 模板实战指南用 Context Engineering 构建可验证的最小可行 AgentPydanticAI Agent 开发 PRP 模板实战指南用 Context Engineering 构建可验证的最小可行 Agent 本篇技术指南围绕 c文档教程提示工程人工智能OpenHarness 技能实战diagnose —— 用结构化证据定位 Agent 运行失败与性能回退OpenHarness 技能实战diagnose —— 用结构化证据定位 Agent 运行失败与性能回退 导读 OpenHarness 内置的 diagnos人工智能AI AgentAgent 框架代码智能体工具调用MCP 服务Agent 记忆多智能体创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考