企业官网建设流程全解析

Evolver主机运行时适配器开发指南：hookAdapter模式完整教程

【免费下载链接】evolverThe GEP-powered self-evolving engine for AI agents. Auditable evolution with Genes, Capsules, and Events. | evomap.ai项目地址: https://gitcode.com/GitHub_Trending/evolv/evolver

Evolver 是一个基于 GEP（Genes、Capsules、Events）的 AI Agent 自进化引擎，它通过"钩子（Hooks）"机制嵌入到 Cursor、Claude Code、Codex、Kiro、opencode 等主机运行时中，在会话开始、文件编辑、会话结束时自动采集进化信号。本文以hookAdapter 模式为主线，手把手讲解如何为 Evolver 编写一个新的主机运行时适配器：从平台注册、安装/卸载接口，到安全守卫与测试规范，一次讲透。

全局认知：hookAdapter 模式是怎么分工的

Evolver 的适配器层位于 src/adapters/ 目录，核心设计思想是"一份共享基础设施 + N 个轻量平台适配器"：

• 共享中枢src/adapters/hookAdapter.js：封装了平台检测、配置文件合并、钩子脚本拷贝、卸载清理、符号链接安全守卫等所有平台通用的能力，每个函数都单独导出，供各适配器直接require复用。
• 平台适配器：如 src/adapters/cursor.js、src/adapters/claudeCode.js、src/adapters/codex.js、src/adapters/kiro.js、src/adapters/opencode.js，每个文件只需关心"这个平台把钩子写到哪里、文件格式长什么样"。
• 钩子脚本本体src/adapters/scripts/：evolver-session-start.js、evolver-signal-detect.js、evolver-session-end.js等真正干活的脚本，安装时被拷贝到目标平台的配置目录。

这个模式带来的好处是：新增一个平台时，你几乎不用写底层逻辑，只需声明"平台元数据 + 安装/卸载差异点"。

新增平台适配器五步走：完整开发清单

第一步：在 PLATFORMS 表登记平台元数据

打开 src/adapters/hookAdapter.js，找到PLATFORMS常量，它决定了平台 ID、显示名称、配置目录和检测标记：

cursor → 配置目录 .cursor，检测标记 .cursor claude-code → 配置目录 .claude，检测标记 .claude codex → 配置目录 .codex，检测标记 .codex kiro → 配置目录 .kiro，检测标记 .kiro opencode → 配置目录 .opencode，检测标记 .opencode

为新平台追加一条记录即可。detector字段用于"项目目录 → 用户主目录"两级探测，判断当前工作区或全局是否安装了对应运行时。

第二步：编写平台适配器的 install / uninstall 接口

新建src/adapters/myplatform.js，参考 src/adapters/cursor.js 这个最简范例，只需导出两个函数：

install({ configRoot, evolverRoot, force }) uninstall({ configRoot, evolverRoot })

install的典型套路（以 Cursor 适配器为例）：

1. 安全预检：调用assertSafeConfigDir()确认配置目录不是符号链接，防止恶意仓库把写入重定向到项目外。
2. 幂等检查：若目标配置已带_evolver_managed标记，直接返回skipped: true，提示用户加--force。
3. 写入钩子配置：用mergeJsonFile()合并 JSON——它内置"钩子并集合并"，会保留用户已安装的钩子、只刷新 Evolver 自己的条目（通过命令中是否包含evolver-session/evolver-signal等关键字识别）。
4. 拷贝钩子脚本：调用copyHookScripts()，它负责把 src/adapters/scripts/ 下的全部脚本（含_开头的辅助模块）落到目标目录，并逐文件拒绝"预置符号链接"。
5. 返回结果：{ ok: true, platform, files: [...] }，files列表会由 CLI 打印给用户。

uninstall则对称地使用removeEvolverHooks()（只删 Evolver 自己的条目）、removeHookScripts()、removeMarkedSection()（清理 CLAUDE.md / AGENTS.md 中带标记的注入段落）。

💡 不同平台的差异点：Codex 还需要在config.toml里打开codex_hooks特性开关并注入AGENTS.md说明段（见 src/adapters/codex.js）；opencode 走插件文件形态并额外提供verify()只读自检（见 src/adapters/opencode.js）。你的适配器只需在通用流程上叠加这类"平台特有步骤"。

第三步：在 loadAdapter 路由中注册

仍在 src/adapters/hookAdapter.js 的loadAdapter()函数中，按平台 ID 增加一个require分支：

case 'myplatform': return require('./myplatform');

setupHooks()是 CLI 的统一入口：它先detectPlatform()自动探测平台（无法探测时才报错提示--platform=参数），再loadAdapter()取出适配器并分发install/uninstall。注册完成后，node index.js setup-hooks --platform=myplatform就能直接跑通。

第四步（可选）：补充平台环境信号识别

detectPlatformFromEnv()通过环境变量强信号优先于目录探测来判断运行时（例如CURSOR_TRACE_ID指向 Cursor、CODEX_CI指向 Codex）。如果你的平台运行时也会导出专属环境变量，按现有"强信号 → 弱信号"的优先级插入判断，可避免.claude与.cursor目录同时存在时的误判。

第五步：补上回归测试

测试集中在 test/adapters.test.js，新适配器至少覆盖四件事：

• 安装正确性：在临时目录调用install()，断言配置文件与脚本齐全；
• 卸载对称性：uninstall()后不留孤儿文件（历史上曾因"装了没删"产生过回归）;
• 用户钩子保全：预置用户自己的钩子条目，重装后确认未被覆盖;
• 符号链接拒绝：把配置目录或其子目录换成符号链接，断言install/uninstall抛错拒绝执行——这是 test/adapters.test.js 中symlinkIt用例组的核心。

另外该测试文件还会扫描源脚本中所有require('./_*')，断言其目标都出现在copyHookScripts的拷贝清单里。如果你给钩子脚本新增辅助模块，记得同步两处清单。

值得学习的三个安全与工程细节

• 命令注入免疫：buildSafeNodeHookCommand()把脚本绝对路径 base64 编码进node -e包装器，用shell:false方式执行，路径中的空格、$()、反引号、%VAR%都无从被 shell 展开。
• 原子写文件：所有 JSON 写入都走"写.tmp→rename"两步，避免半截文件。
• 卸载即清理：isEvolverHookCommand()统一识别 Evolver 命令（含已废弃的旧守护进程钩子），保证重装不重复、卸载无残留。

快速上手：用 CLI 验证你的适配器

node index.js setup-hooks --platform=myplatform node index.js setup-hooks --platform=myplatform --uninstall

setup-hooks命令的完整分发逻辑在 index.js 中，支持--force（覆盖重装）与--verify（只读健康检查，仅对实现了verify()的适配器可用）。各平台的标准接入命令速查可参考 README.md 中的集成表格。

常见坑位自查清单

按这份清单走完五步，你就能为 Evolver 稳定接入任意新的 AI Agent 主机运行时，且与现有五个平台适配器共享同一套安全基线。

【免费下载链接】evolverThe GEP-powered self-evolving engine for AI agents. Auditable evolution with Genes, Capsules, and Events. | evomap.ai项目地址: https://gitcode.com/GitHub_Trending/evolv/evolver