企业官网建设流程全解析

ECC 通用开发模式指南：骨架项目、Repository 模式与统一 API 响应信封格式

【免费下载链接】ECCThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.项目地址: https://gitcode.com/GitHub_Trending/ev/ECC

本文基于 ECC（The agent harness performance optimization system）仓库中的 docs/ja-JP/rules/common/patterns.md 规则文档，系统讲解项目开发中三类被反复验证的通用模式：骨架项目（Skeleton Project）驱动的功能实现流程、Repository 数据访问模式，以及统一的 API 响应信封格式。读完本文，你将掌握在 ECC 中从零落地一个新功能的标准流程、如何设计可替换数据源的持久层，以及如何构建前后端与多 Agent 协作都能一致解析的响应契约。

一、骨架项目：以实战验证过的结构为起点

规则文档开篇即强调一个核心立场：实现新功能时，不应当从空目录开始，而应当以"经过实战检验的骨架项目"为基座。这条规则与 ECC 仓库自身的定位一脉相承——仓库中既提供了 scaffolds/cursor/hooks.json、scaffolds/cursor/ecc-agent-data.json 这类可直接落到编辑器环境的骨架配置，也在 docs/ja-JP/AGENTS.md（第 141 行）中将"骨架项目"确立为贯穿开发流程的全局原则。

标准四步流程

1. 搜索：在已有代码库、历史项目或模板库中查找与目标功能匹配、且经过实战测试的骨架项目；
2. 并行评估：使用并行 agent 对候选骨架进行多维度打分：
   • 安全性评估：检查依赖、权限边界与潜在注入面；
   • 可扩展性分析：判断结构是否能承载后续功能增长；
   • 相关性评分：衡量骨架与目标需求的匹配程度；
   • 实施规划：产出从骨架到成品的落地步骤；
3. 克隆：选择综合评分最高的骨架作为实现基础；
4. 迭代：在已被验证的结构内部进行增量开发，而不是推倒重来。

这一步的要点在于"评估先行、多 Agent 并行"。文档中列出的四个评估维度（安全、扩展、相关、规划）恰好与 agents/ 目录下专职评审 agent 的分工一一对应——例如 security-reviewer.md 对应安全性评估、code-architect.md 对应可扩展性分析、planner.md 对应实施规划，说明这套流程在 ECC 中不只是纸面规则，而是有具体 agent 角色可承担的可执行工作流。

骨架项目的典型形态

以仓库自带的 Cursor 骨架为例：

{ "version": 1, "hooks": { "sessionStart": [ { "command": "node .cursor/scripts/hooks/cursor-session-env.js" } ] } }

这是一份最小可用的 scaffolds/cursor/hooks.json：声明了 hook 协议版本，并在sessionStart事件挂载一个环境注入脚本。它展示了骨架项目的核心特征——体积小、结构明确、即拷即用：拿到这份骨架，只需补上node .cursor/scripts/hooks/cursor-session-env.js的实现，就能得到完整的会话环境初始化能力。

配套的 scaffolds/cursor/ecc-agent-data.json 则示范了骨架中"配置与代码分离"的惯例：

{ "$schema": "https://json.schemastore.org/json", "description": "ECC agent data root for this project when using Cursor. Memory hooks read session summaries and learned skills from here instead of ~/.claude.", "agentDataHome": "~/.cursor/ecc" }

通过声明agentDataHome，骨架将记忆数据根目录从默认的~/.claude重定向到~/.cursor/ecc，使 Cursor 环境下的会话摘要与技能读取不再依赖其他 Agent 的数据目录。这个例子说明：好的骨架不仅包含结构，还应在配置中显式表达它"替换了什么默认行为、为什么"。

二、Repository 模式：把数据访问关进统一接口

规则文档对 Repository 模式的定义可以浓缩为一句话：将数据访问封装在一个一致的接口之后，让业务逻辑只依赖抽象，而不是存储机制。

标准操作集

文档规定 Repository 接口至少应暴露五类标准操作：

模式带来的三个收益

• 存储细节被隔离：数据库、API、文件系统等具体实现各自封装，调用方无感知；
• 数据源可替换：切换存储后端（如从 JSON 文件换到数据库）只需替换 Repository 的具体实现，接口与业务代码零改动；
• 测试可模拟：业务逻辑面向接口，测试时可以注入 mock 实现，无需真实存储。

这一模式在 ECC 的scripts/lib层有大量实际对应。以 scripts/lib/session-manager.js 为例，其内部通过parseSessionFilename解析会话文件名提取元数据、用buildSessionRecord(sessionPath, metadata)组装会话记录——这正是"文件系统存储细节"被封装在数据访问层内部的体现：外层逻辑只需要{ ...metadata }这样的记录结构，而不需要关心文件名如何拼接、目录如何扫描。从源码结构可以推断，会话目录扫描、文件名解析、记录组装这些文件存储特有的细节全部收敛在该模块内，为将来替换为数据库存储预留了清晰的边界。

再看 scripts/lib/session-aliases.js：它对会话别名（alias）的增删改查同样收敛为create/delete/lookup一类的操作，并且在每个入口都先做参数校验再操作存储（如空名、超长、保留字、已存在等检查），这正是 Repository 模式中"具体实现处理存储细节、业务逻辑依赖抽象接口"的典型应用——调用方拿到的是明确的成功/失败结果，而非存储层的异常细节。

三、API 响应信封格式：让每个响应都可预测

规则文档要求：所有 API 响应使用一致的信封（envelope）格式，无论成功还是失败，结构都不能变。这是前后端联调与多 Agent 协作时最值得固化的契约。

信封的四个字段

1. 成功/状态指示器：布尔值或状态码，用于快速判断请求结果；
2. 数据载荷：成功时携带业务数据，出错时为null；
3. 错误消息字段：失败时携带可读的错误说明，成功时为null；
4. 分页元数据：对于分页响应，附上total（总数）、page（当前页）、limit（每页条数）。

对应的 JSON 形态：

{ "success": true, "data": { "items": [], "total": 42 }, "error": null, "meta": { "total": 42, "page": 1, "limit": 20 } }

出错时同一信封结构不变，只切换字段的填充方式：

{ "success": false, "data": null, "error": "alias 'foo' already exists", "meta": null }

源码中的落地佐证

在 scripts/lib/session-aliases.js 中可以清楚看到这套约定被严格执行：校验失败时返回{ success: false, error: '...' }，操作成功时返回{ success: true, ... }；scripts/hooks/mcp-health-check.js 中则进一步细化，用{ attempted, success, reason }这样的结构同时表达"是否尝试执行"与"执行是否成功"两个维度，并在不健康状态下记录lastError字段。它们虽然不是网络 API，但内部模块/进程间的数据交换同样遵循"固定结构、成功/失败字段并存"的原则。

值得注意的一致性细节：失败路径里的错误字段始终填充具体、可诊断的信息（如Alias '${alias}' not found、exit ${result.status}），而不是笼统的failed。这保证了消费方即使不打印堆栈，也能从信封字段直接定位问题——这是文档中"错误消息字段"这一要求在实际工程里的正确打开方式。

四、三类模式的协同：在 ECC 中如何组合使用

这三条规则并非孤立的技巧，而是可以串成一条完整的功能落地流水线：

1. 起步：按骨架项目流程，用并行 agent 评估候选骨架，选出安全、可扩展、相关性最高的基座（对应 docs/ja-JP/AGENTS.md 中的骨架项目原则）；
2. 建持久层：按 Repository 模式为数据访问定义findAll/findById/create/update/delete标准接口，具体存储细节下沉到实现模块，参考 scripts/lib/session-manager.js 与 scripts/lib/session-aliases.js；
3. 定响应契约：所有对外暴露的结果统一套用信封格式（success+data+error+meta），让前端、脚本与 Agent 都能用同一套解析逻辑处理成败与分页。

仓库中的 docs/ja-JP/README.md（第 274 行）将 docs/ja-JP/rules/common/patterns.md 定位为"设计模式、骨架项目"的规范文件，rules/common/ 目录下与其并列的还有 coding-style.md、testing.md、security.md 等配套规则——三类模式与编码风格、测试、安全规则共同构成 ECC 的通用开发基线，任何语言栈的评审与开发 agent 都以此为共同语言。

五、何时不要套用

最后补充文档之外的边界意识：

• 骨架项目适用于"有新功能要从零开始"的场景；如果只是在既有模块内修缺陷，直接沿用原结构迭代即可，不必再走搜索与评估流程；
• Repository 模式的价值在于多数据源或需 mock 测试的场合；对一次性脚本、纯计算逻辑强行分层只会增加间接层；
• 信封格式应一以贯之——一旦对外承诺了信封结构，就不要在个别接口上"偷懒"省略字段，否则消费方的统一解析逻辑就会失效。

把这三条模式作为默认选项、同时保留"不套用"的判断力，才是对 docs/ja-JP/rules/common/patterns.md 规则最忠实的执行。

【免费下载链接】ECCThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.项目地址: https://gitcode.com/GitHub_Trending/ev/ECC