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 Studio 仓库根目录的 AGENTS.md 展开。这份文件不是普通的项目说明而是一份面向编码 Agentcoding agent的导航地图它用最小篇幅告诉 Agent 先读哪些文档、跑哪些命令、代码归谁所有、哪些规则不可违背以及卡住时如何改进 Harness 而不是重复提问。读完本文你将理解这份 Agent 地图的设计哲学、每个条目的落点与依据并能直接在本仓库中按图索骥完成一次从读文档、跑校验到提 PR 的完整 Agent 工作流。一、AGENTS.md 的定位为什么 Agent 需要一张地图而不是一份长文档AGENTS.md 开篇即点明了它的设计目标This file is a short map for coding agents. Keep detailed guidance indocs/and keep this file small enough to fit into every task context.这句话包含两条核心设计原则短小到能放进每个任务上下文编码 Agent 的上下文窗口是有限资源AGENTS.md 必须足够精简让 Agent 在每一个任务开始时都能完整读到它而不至于因内容过长被截断或忽略。详细内容下沉到docs/AGENTS.md 只负责指路具体规则、校验矩阵、运行手册全部放在 docs/harness/README.md 及同级文档中用链接而不是内联正文来承载深度。从仓库结构看这套根地图 深度文档 机械校验脚本的组合正是 Ekko Studio 的Harness测试/约束框架的入口。scripts/harness-check.mjs是整个 Harness 的唯一公开入口它把仓库文档、workflow、包脚本、桌面发布/运行时、后端模块边界等不变式统一机械化校验对应命令为npm run harness:check换句话说AGENTS.md 是人读的地图而npm run harness:check是机器执行的地图校验——文档描述的约束最终都能在脚本里得到可验证的落点。二、First ReadsAgent 的必读清单与仓库文档体系AGENTS.md 为 Agent 指定了七个首次必读入口全部集中在仓库根目录与 docs/harness/ 下。下表整理了每个文档的主题定位对应 docs/harness/README.md 的 Entry Points 章节文档仓库相对路径定位与内容DEVELOPMENT.md项目命令、编码规则、测试规则与 PR 形态ARCHITECTURE.md包边界、数据所有权与运行时请求流docs/harness/README.mdHarness 概览仓库如何为 Agent 工作做准备docs/harness/validation.md每种变更类型应跑的校验命令矩阵docs/harness/worktree-runbook.md隔离的本地开发与测试环境搭建docs/harness/pr-review.md推送前自查清单docs/harness/server-module-boundaries.md后端目标模块、所有权与依赖规则这套分层设计的用意在于让 Agent 在不依赖聊天历史的情况下仅凭文件系统就能自行发现并理解项目约束。任何未来 Agent 需要知道的事实、反复出现在 PR review 意见里的检查项、能快速失败fail fast的仓库级不变式都被固化成文档、测试、脚本或 CI而不是留在某次对话的记忆里。值得注意的是 docs/harness/startup-tasks.md 也是 Harness 文档体系的组成部分它规定了启动期一次性数据升级任务必须注册在packages/server/src/bootstrap/startup-tasks.ts执行记录写入config.appHome下的startup-tasks.json路径由HERMES_WEB_UI_HOME、HERMES_WEBUI_STATE_DIR决定默认~/.hermes-web-ui并明确了任务 ID 永久化、按数据目录 scope 记录完成状态、失败可重试等约束——这体现了同一原则一次性知识变成带执行记录的机械任务而非提示词。三、Common Commands从最小校验到全面发布前校验AGENTS.md 给出的常用命令是 Agent 在仓库中的标准操作集npm ci --ignore-scripts npm run harness:check npm run test npm run test:e2e npm run build各命令在 package.json 中的实际落点如下npm ci --ignore-scripts按package-lock.json干净安装依赖跳过 install scripts避免执行任意生命周期脚本这是 docs/harness/worktree-runbook.md 中 worktree 安装的标准做法桌面端依赖需单独安装npm ci --prefix packages/desktop --no-audit --no-fund。npm run harness:check即node scripts/harness-check.mjs npm --prefix packages/ekko-agent run api:docs:check统一校验仓库文档、workflow、包脚本与后端模块边界不变式同时校验 ekko-agent 的 API 文档。npm run test运行全部 Vitest 单元/集成测试vitest run。npm run test:e2e运行 Playwright 浏览器端到端测试playwright test针对模拟的 BFF API 运行见 DEVELOPMENT.md。npm run build依次执行 OpenAPI 生成、vue-tsc -b类型检查、Vite 构建、服务端tsc --noEmit类型检查并用scripts/build-server.mjs打包服务端产物同时覆盖类型检查与生产构建。AGENTS.md 特别强调了两条节奏准则迭代时使用最小相关校验Use the smallest relevant check while iterating宽泛 PR 前运行全套npm run harness:check、npm run test:coverage、npm run test:e2e、npm run build。其中test:coverage对应 DEVELOPMENT.md 中Build workflow 在npm run build之前运行覆盖率的说明也是 CI 中 ARCHITECTURE.md 所描述的 Validation Surfaceharness:check仓库不变式→ 聚焦 Vitest本地逻辑→test:e2e浏览器可见回归→build类型与生产包。变更类型与最小校验矩阵docs/harness/validation.md 进一步把最小相关校验展开成一张可查表这里摘录核心行变更类型最小本地校验仅文档npm run harness:check客户端组件/store/API聚焦npm run test -- pattern然后npm run build浏览器可见流程聚焦 Vitest 加npm run test:e2e服务端 controller/service/db聚焦npm run test -- tests/server/file服务端模块迁移或依赖变更聚焦服务端边界测试然后npm run harness:check认证/Profile/凭据行为聚焦服务端测试加相关 e2e 认证测试Chat、Socket.IO、群聊聚焦服务端测试加相关 e2e 聊天测试桌面打包npm run harness:check、npm run build条件允许时做平台相关桌面构建GitHub workflownpm run harness:check有actionlint时运行它这套矩阵正是 AGENTS.md Use the smallest relevant check 的可执行化版本变更类型决定校验命令Agent 无需猜测该跑什么。四、Code Ownership Map代码所有权一览AGENTS.md 用六个条目划定了仓库的核心所有权边界与 ARCHITECTURE.md 的 Package Boundaries 表格一一对应路径责任范围架构定位来自 ARCHITECTURE.mdpackages/client/srcVue 3 客户端stores、routes、i18n、API 辅助浏览器可见 UI 状态views/、components/、stores/、api/、i18n/、styles/分层packages/server/srcKoa API、Socket.IO、持久化、Hermes 集成HTTP API、认证、SQLite stores、文件访问、Hermes 运行时集成packages/ekko-agent规范 Ekko 运行时profiles、providers、tools、memory、skills、包文档Canonical Ekko runtime、profile facade、conversations、包 APIpackages/desktopElectron 外壳、捆绑的 Python/Hermes 运行时、发布产物Electron shell、本地 Web UI server 引导、updater、捆绑运行时tests/client、tests/server、tests/sharedVitest 覆盖单元/集成测试tests/e2ePlaywright 浏览器覆盖mock 后端服务浏览器端到端测试其中server 的所有权在 docs/harness/server-module-boundaries.md 中被进一步细化为一个强约束的目录契约所有服务端 TypeScript 源码只能存在于modules/studio、hermes、ekko、coding-agents四个模块根或bootstrap/唯一的组合根只有它允许依赖所有模块以及入口index.ts。四个模块根之间遵循一张有向依赖矩阵From \ ToStudioHermesEkkoCoding AgentsbootstrapyesyesyesyesStudioyesnononoHermescontracts/publicyesnonoEkkocontracts/publicnoyesnoCoding Agentscontracts/publicnonoyes核心语义是Studio 永不 import 具体 Agent 实现跨 Agent 执行必须通过 Studio 拥有的 port契约接口由bootstrap注入具体适配器从而保证模块图无环。scripts/server-module-boundaries.mjs会在npm run harness:check时机械校验这张矩阵与route 不直接调用 service/repository、controller 不 import route等分层规则。五、Hard Rules十条不可违背的硬约束AGENTS.md 的 Hard Rules 是全篇最具操作价值的清单逐条展开如下含仓库中的依据路由保持薄请求处理放 controller可复用行为放 service。对应 DEVELOPMENT.md 与 ARCHITECTURE.md 的层职责划分也对应边界文档中routes do not call services or repositories directly的机械校验。新服务端代码必须落入四个模块之一modules/studio、modules/hermes、modules/ekko、modules/coding-agents只能由bootstrap组装模块。新增顶层模块属于架构变更需要同步修改 docs/harness/server-module-boundaries.md 及其机械检查器。Web UI 状态保持在HERMES_WEB_UI_HOME或HERMES_WEBUI_STATE_DIR之下默认~/.hermes-web-ui通过config.appHome提供。运行时数据目录也必须位于 Web UI home 之下不得放在构建产物dist旁边。Hermes Agent 状态与 Web UI 状态严格分离Hermes 数据走 profile 目录及 profile helpers如getActiveProfileDir()不得与 Web UI home 混用也不得手写拼接路径。本地 API 路由注册必须先于代理 catch-all 路由否则本地接口会被代理规则吞掉。使用结构化 API 与参数数组而不是拼接 shell 字符串调用子进程优先execFile/spawn配合参数数组DEVELOPMENT.md Server Rules 的明确要求避免注入与转义问题。面向用户文案必须写入每个 locale 文件客户端的可见文本需要覆盖全部语言文件前端规则Add user-facing strings to all locale files。不要在同一提交里混入无关重构bug fix 与 refactor 分离保持变更范围聚焦DEVELOPMENT.md Commit And PR Rules 同样强调。其中第 3、4 条在 docs/harness/validation.md 中还有一个值得注意的衍生约束Studio 注入的每个受管 MCP server 必须在其自身 launchenv中显式设置ELECTRON_RUN_AS_NODE: 1包括选择了独立 Node 可执行文件的情况且绝不能依赖父进程环境继承也不能在桌面 GUI 全局开启。这是 Hermes/Ekko/Coding Agent 三类 MCP 注入路径共用的启动环境护栏npm run harness:check会检查全部三个配置工厂。六、When The Agent Gets Stuck卡住时的正确姿势——改进 Harness 而非重复提问AGENTS.md 的最后一段是它最有方法论价值的部分Improve the harness instead of repeating the same prompt. Add missing docs, tests, logs, scripts, or CI checks so the next agent can see and verify the constraint directly.这句话的含义是当 Agent 反复在同一类问题上失败比如反复违反某条未写明的约束正确的做法不是在下一次对话里把提示词写得更长而是把约束固化为 Agent 可直接发现与验证的资产——补文档、补测试、补日志、补脚本或补 CI 检查。这正好呼应 docs/harness/README.md 的 Operating Model操作模型阅读根地图与任务相关的具体文档做最小范围的改动行为变化时补充聚焦测试运行npm run harness:check及相关校验命令若同类失败反复出现用文档、测试、脚本或 CI 改进 Harness而不是依赖更长的提示词。以及它定义的Harness 该装什么What Belongs In The Harness未来 Agent 必须知道才能安全工作的事实能阻止 PR review 重复意见的检查清单能对仓库级不变式快速失败的脚本本地、CI、发布与桌面打包流程的运行手册runbook。相反长实现笔记不应放进 AGENTS.md应放入docs/并从地图中链接出去——这保证地图始终短小、可完整进入每个任务上下文。七、把地图走通一遍一次完整的 Agent 工作流示例综合以上各节一个编码 Agent 在 Ekko Studio 仓库中处理任务的推荐路径是读地图先读 AGENTS.md 获取所有权与硬规则再按 First Reads 清单读 DEVELOPMENT.md、ARCHITECTURE.md 及对应 docs/harness/ 文档。搭环境如需隔离开发遵循 docs/harness/worktree-runbook.mdgit worktree add -b codex/short-topic ../worktrees/hermes-web-ui-short-topic origin/main然后npm ci --ignore-scripts、npm rebuild node-pty桌面依赖单独npm ci --prefix packages/desktop --no-audit --no-fund。用每 worktree 独立的端口与状态目录避免冲突export PORT18648 export HERMES_WEB_UI_HOME$PWD/.tmp/hermes-web-ui export HERMES_WEBUI_STATE_DIR$HERMES_WEB_UI_HOME export UPLOAD_DIR$PWD/.tmp/uploads npm run dev最小变更按所有权地图把改动落在正确的包/模块内遵守硬规则薄路由、参数数组、全 locale、状态目录分离。跑最小校验按 docs/harness/validation.md 的变更类型矩阵选择聚焦测试涉及共享行为、认证、持久化或 chat 时升级到npm run test:coverage、npm run test:e2e、npm run build。自查与提 PR对照 docs/harness/pr-review.md 的 Scope / Architecture / Tests And Validation / Release And CI / Before Merge 五个清单自查PR 描述按 DEVELOPMENT.md 的模板写明 Summary、Closes #123与 Validation 命令。收尾PR 推送后清理自己创建的 worktreegit worktree remove只清理自己创建的那个。八、总结Ekko Studio 的 AGENTS.md 展示了一种Agent-first的仓库组织方式以一张短小的根地图为入口把知识分层存放于 docs/harness/ 深度文档把约束机械化为npm run harness:check与各类聚焦测试把重复失败转化为 Harness 资产的持续改进。它同时回答了三个关键问题Agent 该读什么First Reads、该跑什么Common Commands validation 矩阵、什么绝对不能做Hard Rules 模块边界依赖矩阵。对任何希望让 AI 协作开发更可预测、可验证的仓库而言这套地图 Harness 机械校验的模式都值得直接借鉴。赞分享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点击查看免费下载相关推荐Learn Harness Engineering 中的 AGENTS.md为长时运行编码 Agent 打造可持续的仓库根指令文件Learn Harness Engineering 中的 AGENTS.md为长时运行编码 Agent 打造可持续的仓库根指令文件 本篇文章聚焦 learnlearn-harness-engineering 仓库实战为 Agent 编写可执行、可路由的 ARCHITECTURE.md 系统地图learn harness engineering 仓库实战为 Agent 编写可执行、可路由的 ARCHITECTURE.md 系统地图 导读 本指南以AGENTS.md 实战指南为长期运行的编码 Agent 构建可无缝续接的工作仓库learn-harness-engineeringAGENTS.md 实战指南为长期运行的编码 Agent 构建可无缝续接的工作仓库learn harness engineering 导读 本篇文章以创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考