OpenViking TRAE CLI 内存 Hooks 适配器生命周期钩子、URI 守卫与 MCP 集成详解【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking本文是 OpenViking 项目中examples/trae-cli-memory-hooks目录的技术指南核心讲解如何通过 TRAE CLI 生命周期 HooksSessionStart/UserPromptSubmit/Stop/PreToolUseopenviking-memoryMCP 服务器将 TRAE CLI 接入 OpenViking 的 Agent 记忆体系实现会话开始时注入上下文、用户提问时自动召回、对话停止时自动捕获回写以及拦截对viking://虚拟路径的非法工具调用。读完本文你将掌握这套适配器的安装/卸载方式、Hook 事件与输出协议、共享运行时的组装模型以及 TRAE CLI 与 Codex 插件格式的兼容边界。一、背景与定位这是一个被标记为废弃Deprecated的适配器examples/trae-cli-memory-hooks是 OpenViking 为TRAE CLITraeCode CLI提供的生命周期适配器目录包含三个生命周期 Hook、一个PreToolUseURI 守卫以及openviking-memoryMCP 服务器。需要特别注意的是该目录在 README 开头即声明DeprecatedTraeCode CLI 2.0 已支持直接加载 Codex 格式插件。新安装统一走 examples/codex-memory-plugin通过trae-cli命令别名安装本适配器仅保留用于兼容性测试与存量托管安装的清理。因此本文的主线应理解为两部分存量视角理解这套独立 Hooks 适配器当年如何工作对排障、清理、迁移到新方案至关重要演进视角明确“废弃的是独立 Hooks 适配器而不是trae-cli这个 harness”新装用户应通过 examples/memory-plugin-shared/install.sh 的--harness trae-cli安装 Codex 格式插件。目录内的 openviking.integration.json 清单也明确记录了这一状态{ schemaVersion: 1, id: openviking-memory, version: 0.1.0, deprecated: true, replacement: examples/codex-memory-plugin (install through the trae-cli Codex-format alias), clients: [trae-cli], capabilities: [hooks, mcp] }其中replacement字段指向新方案clients表明本适配器仅面向trae-cli这一个客户端区别于 TRAE / TRAE CN 的tr-、trcn-前缀分支。二、运行时边界目录里只有适配器共享运行时由安装器组装理解本包的第一步是认清它的运行时边界examples/trae-cli-memory-hooks目录内只包含 TRAE CLI 特有的适配层没有自带lib/目录共享运行时是在安装时由安装器从examples/memory-plugin-shared/lib组装进去的。三个核心共享模块及其职责如下共享模块职责lib/agent-hook-runtime.mjs处理 profile 注入、recall、capture、commit、session 状态、文件锁、凭据加载与 pending retry 重放lib/mcp-proxy-core.mjs处理 stdio 到 OpenViking/mcp的代理lib/agent-uri-guard.mjs处理PreToolUse阶段对本地文件/Shell 工具收到viking://虚拟路径的拦截这套目录结构与examples/trae-memory-hooks保持一致。安装器的目标布局为将examples/trae-cli-memory-hooks复制到$OV_HOME/agent-integrations/trae-cli将共享运行时组装到$OV_HOME/agent-integrations/memory-plugin-shared/lib。三、安装与卸载一条命令完成3.1 安装由于 TraeCode CLI 2.0 原生支持 Codex 格式插件官方推荐的安装方式是直接使用共享安装器并将trae-cli作为用户可见的 harness 名称bash examples/memory-plugin-shared/install.sh --harness trae-cli在 install.sh 中harness 参数说明为--harness LIST逗号分隔的 harness 列表claude, codex, cursor, trae, trae-cn, trae-cli, zcode, opencode, pi, dsh。使用trae-cli表示 TraeCode CLI 2.0通过其 Codex 兼容插件格式安装。安装器会探测本机的 TRAE CLI 可执行文件trae-cli/traecli/traex任一存在即视为已安装并将其规范命名为trae-cli。3.2 历史安装行为本适配器时代在独立适配器时代安装器过去的行为是将共享运行时组装到$OPENVIKING_HOME/agent-integrations/memory-plugin-shared/lib将本适配器安装到$OPENVIKING_HOME/agent-integrations/trae-cli将 Hook 合并进${TRAECLI_HOME:-${TRAE_HOME:-~/.trae}/cli}/hooks.json在${TRAE_HOME:-~/.trae}/traecli.toml中注册openviking-memoryMCP 服务器。现在的安装器不再安装本适配器而是走 Codex 格式插件路径但保留了trae-cli这个 harness 名称。3.3 卸载bash examples/memory-plugin-shared/install.sh --harness trae-cli --uninstall --yes卸载逻辑在 install.sh 附近当检测到$OV_HOME/agent-integrations/trae-cli目录存在、或traecli.toml中已含[mcp_servers.openviking-memory]时会调用agent_remove_trae_cli_configs清理 hooks 配置与traecli.toml中对应的 MCP 段落并移除已安装的目录。四、Hook 与 MCP 表面四个事件、三种输出形态4.1 四个 Hook 事件本包注册了四个 Hook 事件定义在 hooks/hooks.jsonEventEntry复用评估SessionStartscripts/session-start.mjs复用共享的 thin-harness profile 注入路径要求 TRAE CLI 提供稳定的 session id 或等价的 cwd 兜底UserPromptSubmitscripts/auto-recall.mjs复用共享 recall 路径要求 TRAE CLI 将用户输入暴露为prompt、user_prompt、message或textStopscripts/auto-capture.mjs复用共享 session append 与 commit 辅助要求 TRAE CLI 的 stop 输入将助手回复暴露为last_assistant_message、assistant_message、response、output或text_contentPreToolUsescripts/uri-guard.mjs遵循 Codex Hook 输出风格返回permissionDecision: deny复用共享agent-uri-guard求值器完整的 hooks 模板如下注意命令中的__OPENVIKING_TRAE_CLI_ROOT__占位符安装时会被替换为该目录的绝对路径{ hooks: { SessionStart: [ { matcher: clear|startup|resume, hooks: [ { type: command, command: node __OPENVIKING_TRAE_CLI_ROOT__/scripts/session-start.mjs, timeout: 70 } ] } ], UserPromptSubmit: [ { matcher: *, hooks: [ { type: command, command: node __OPENVIKING_TRAE_CLI_ROOT__/scripts/auto-recall.mjs, timeout: 130 } ] } ], Stop: [ { matcher: *, hooks: [ { type: command, command: node __OPENVIKING_TRAE_CLI_ROOT__/scripts/auto-capture.mjs, timeout: 30 } ] } ], PreToolUse: [ { matcher: Read|Glob|Grep|Bash|RunCommand|Shell, hooks: [ { type: command, command: node __OPENVIKING_TRAE_CLI_ROOT__/scripts/uri-guard.mjs, timeout: 5 } ] } ] } }值得注意的细节SessionStart的 matcher 是clear|startup|resume即只在会话启动/恢复/清空时触发超时 70 秒profile 构建 pending 重放可能较慢UserPromptSubmit与Stop的 matcher 是*所有输入超时分别为 130 秒recall 检索与 30 秒PreToolUse的 matcher 精确限定在Read|Glob|Grep|Bash|RunCommand|Shell这几类本地文件与 Shell 工具上超时仅 5 秒——因为它只需做一次 URI 判定必须足够快。4.2 TRAE CLI 的 Hook 输出协议TRAE CLI 生命周期 Hooks不使用TRAE / TRAE CN 的decision: approve输出风格其输出约定如下无操作的生命周期 Hook 输出{}上下文注入只输出hookSpecificOutput.hookEventName加hookSpecificOutput.additionalContext工具调用的放行/拒绝属于PreToolUse通过hookSpecificOutput.permissionDecision表达权限审批属于PermissionRequest通过hookSpecificOutput.decision.behavior表达。这一点在 trae-cli-hook.mjs 中得到印证emitLifecycleOutput只有在有additionalContext时才写hookSpecificOutput否则输出空对象{}而 uri-guard.mjs 则以 Codex 风格输出hookSpecificOutput.permissionDecision deny并附带permissionDecisionReason。4.3 MCP 服务器注册MCP 服务器名为openviking-memory与 Codex 内存插件同名。本包保持与其他原生 Hook 集成相同的.mcp.json源形状共享安装器会将等价的 Node 代理条目写入 TRAE CLI 的traecli.toml{ mcpServers: { openviking-memory: { command: node, args: [servers/mcp-proxy.mjs], cwd: ., startup_timeout_sec: 30 } } }从源码看安装器实际写入的 TOML 形态更完整——见 install.sh它生成[mcp_servers.openviking-memory]段落并注入OPENVIKING_INTEGRATION_ID、OPENVIKING_INTEGRATION_VERSION、OPENVIKING_HOOK_SOURCEtrae-cli三个环境变量到env字段供 Hook 与 MCP 代理运行时读取。五、源码级剖析三个包装脚本如何汇聚到统一适配器5.1 事件分发的三个薄包装session-start.mjs、auto-recall.mjs、auto-capture.mjs三个文件是极薄的入口只做一件事——设置OPENVIKING_HOOK_EVENT环境变量后动态导入统一适配器// session-start.mjs process.env.OPENVIKING_HOOK_EVENT session-start; await import(./trae-cli-hook.mjs);// auto-recall.mjs process.env.OPENVIKING_HOOK_EVENT user-prompt-submit; await import(./trae-cli-hook.mjs);// auto-capture.mjs process.env.OPENVIKING_HOOK_EVENT stop; await import(./trae-cli-hook.mjs);这样三个 Hook 事件共享同一份逻辑trae-cli-hook.mjs只负责按事件名走不同分支。5.2 统一适配器trae-cli-hook.mjstrae-cli-hook.mjs 是整个适配器的核心从源码结构看其关键设计如下固定身份使用固定的clientId trae-cli与 OpenViking session 前缀trcli-见第 25-26 行刻意不携带 TRAE / TRAE CN 的tr-、trcn-分支。会话 ID 通过共享的deriveAgentSessionId(prefix, input)派生原生会话 ID 由resolveNativeSessionId(input)解析。SessionStart 分支第 55-70 行先取withAgentHookLock文件锁避免并发触发用lastSessionStartAt做 2000ms 的节流去重调用replayAgentPending重放上次失败未提交的 pending 消息断点续传调用buildAgentProfile构建 Agent profile有 profile 时以openviking-context sourcesession-start标签注入。UserPromptSubmit 分支第 72-102 行用resolveTraeCliPrompt(input)从 Hook 输入中提取用户提问对同一次提问做双维度去重优先用generation_id/request_id/message_id/prompt_id事件 ID 判重缺失时退回promptHash 500ms 时间窗口通过共享recallForPrompt执行召回结果缓存在 hook state 中以便 Stop 分支组装对话轮次时对齐提问命中相同提问但无新 recall 块时复用state.recallBlock避免重复检索。Stop 分支第 104-134 行受cfg.autoCapture开关控制用buildTraeCliTurns(input, state)从输入与 state 中还原「用户提问 助手回复」轮次用stableHash(turnKey, role, content)计算轮次哈希并与capturedHashes最多保留 1000 条比对去重通过共享addAgentMessages写入 session随后commitAgentSession提交capturedSinceCommit统计自上次提交以来的累积捕获量。异常兜底main().catch保证任何异常都被记录logError(uncaught, error)并输出{}不会因 Hook 失败阻塞 TRAE CLI 主流程。5.3 字段映射trae-cli-turns.mjstrae-cli-turns.mjs 负责 TRAE CLI Hook 输入字段的适配核心是两个容忍性很强的解析函数resolveTraeCliPrompt(input)按prompt→user_prompt→userPrompt→message→text顺序取用户提问resolveTraeCliResponse(input)按last_assistant_message→lastAssistantMessage→assistant_message→assistantMessage→response→output→text_content顺序取助手回复。cleanTraeCliText会剥离上一轮注入的openviking-context ....../openviking-context与relevant-memories.../relevant-memories标签避免上下文标签被当作真实对话内容回写。buildTraeCliTurns则把解析出的内容组装成[{role:user},{role:assistant}]两元组并过滤空内容。5.4 URI 守卫uri-guard.mjsuri-guard.mjs 在PreToolUse阶段拦截危险的工具调用工具名兼容tool_name/toolName/name/tool工具输入兼容tool_input/toolInput/input/arguments核心判定委托给共享的evaluateAgentUriGuard(toolName, toolInput)当本地文件工具Read/Glob/Grep或 Shell 工具Bash/RunCommand/Shell收到viking://虚拟路径时返回permissionDecision: deny并附上permissionDecisionReason该文件同时具备“直接执行”与“模块导入”双形态通过import.meta.url与process.argv[1]的 realpath 比较判断是否为入口执行被测试导入时仅导出evaluateTraeCliUriGuard。5.5 测试覆盖目录内附带了 trae-cli-hooks.test.mjs用于验证字段映射与 Hook 分支逻辑。如果你要扩展 TRAE CLI 的字段兼容面这是回归测试的锚点。六、用户级安装形态hooks.json 与 traecli.toml6.1 Hook 配置文件安装器渲染 hooks/hooks.json 时把__OPENVIKING_TRAE_CLI_ROOT__替换为本目录的绝对路径然后合并进当前TRAECLI_HOME/hooks.json。常见本地路径为~/.trae/cli/hooks.json从 install.sh 的合并逻辑看写入前会先过滤掉旧的 OpenViking Hook 条目通过isOpenVikingHook识别openviking_integration_id或session-start.mjs/auto-recall.mjs/auto-capture.mjs/uri-guard.mjs/trae-cli-hook.mjs特征并以原子写.bak备份 临时文件 rename落盘。TRAE CLI 也支持在活动traecli.toml的[hooks]段配置 Hook但TUI 的/hooks命令显示的源才是真相source of truth。集成安装时优先使用用户级 hooks 文件这样配置不绑定到单一工作区。6.2 MCP 配置MCP 应添加到活动traecli.toml的[mcp_servers.openviking-memory]段。项目级 MCP 文件如workspace/.trae/.mcp.json或workspace/.trae/mcp.jsonTRAE CLI 虽然支持但不是本集成推荐的写入目标。生效配置可用/mcp或traecli mcp list确认。6.3 排障与验证/hooks查看 TUI 中生效的 Hook 条目/mcp或traecli mcp list查看生效的 MCP 服务器若已安装过旧版 OpenViking TRAE Hook 集应替换或禁用旧条目而不是把新草案并排在旁边——同时运行两套会导致 recall 与 capture 重复每条提问被召回两次、每轮对话被捕获两次。安装器本身也会校验已安装的 Hook 入口与 MCP 配置。七、与 Codex 不重用的部分本适配器刻意隔离了 Codex 插件生态特有的机制保持「仅 TRAE CLI 适配层」的纯净边界不复用 Codex 插件市场的元数据与安装命令不做 Codex 特有的${PLUGIN_ROOT}变量替换不复用 Codex 特有的PreCompact提交流程不解析 Codex transcript 的 JSONL 格式也不使用cx-session_id会话前缀不做 Codex 本地压缩器的启动检测。这也是该目录在 Codex 插件格式出现后走向废弃的根本原因TraeCode CLI 2.0 直接兼容 Codex 格式插件后独立的 TRAE CLI 适配层就失去了存在价值。八、当前兼容性说明与扩展指引三个生命周期 Hook 条目在设计上是可以复用的——只要 TRAE CLI 发送的 Hook 输入 JSON 贴近现有 thin harness 约定。各事件需要的关键字段如下用途可接受字段按优先级会话身份conversation_id、session_id、sessionId、generation_id工作区cwd、workspace_roots、workspaceRoots用户提问prompt、user_prompt、userPrompt、message、text助手回复stoplast_assistant_message、lastAssistantMessage、assistant_message、assistantMessage、response、output、text_content工具调用名称tool_name、toolName、name、tool输入tool_input、toolInput、input、arguments如果 TRAE CLI 后续版本改用其他字段名只需适配 trae-cli-hook.mjs 或本地的文本清理/轮次解析逻辑 trae-cli-turns.mjs共享的 OpenViking 运行时与 MCP 代理可以保持不变——这正是「适配层薄、共享层厚」这一架构的容错红利。九、总结examples/trae-cli-memory-hooks是 OpenViking 与 TRAE CLI 集成演进史上的一个重要过渡节点它证明了「四个 Hook 事件 共享运行时 独立适配层」这套集成模型可以低成本覆盖新的 CLI 客户端——新增一个客户端只需写字段映射、事件分支与薄包装脚本它明确区分了 TRAE CLItrcli-前缀与 TRAE / TRAE CNtr-/trcn-前缀的生命周期 Hook 输出协议差异它的废弃并非架构失败而是 TraeCode CLI 2.0 原生支持 Codex 插件格式后的自然收敛——存量用户应通过 install.sh 的--harness trae-cli迁移到 examples/codex-memory-plugin并借助/hooks、/mcp、traecli mcp list完成新旧配置的核对与清理。如果你正在排查旧安装的残留 Hook、迁移到新插件格式或研究 OpenViking 的 CLI 集成模式本目录的源码与本文的剖析可作为完整的参考基线。【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 OpenViking TRAE CLI 内存 Hooks 适配器：生命周期钩子、URI 守卫与 MCP 集成详解
OpenViking TRAE CLI 内存 Hooks 适配器生命周期钩子、URI 守卫与 MCP 集成详解【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking本文是 OpenViking 项目中examples/trae-cli-memory-hooks目录的技术指南核心讲解如何通过 TRAE CLI 生命周期 HooksSessionStart/UserPromptSubmit/Stop/PreToolUseopenviking-memoryMCP 服务器将 TRAE CLI 接入 OpenViking 的 Agent 记忆体系实现会话开始时注入上下文、用户提问时自动召回、对话停止时自动捕获回写以及拦截对viking://虚拟路径的非法工具调用。读完本文你将掌握这套适配器的安装/卸载方式、Hook 事件与输出协议、共享运行时的组装模型以及 TRAE CLI 与 Codex 插件格式的兼容边界。一、背景与定位这是一个被标记为废弃Deprecated的适配器examples/trae-cli-memory-hooks是 OpenViking 为TRAE CLITraeCode CLI提供的生命周期适配器目录包含三个生命周期 Hook、一个PreToolUseURI 守卫以及openviking-memoryMCP 服务器。需要特别注意的是该目录在 README 开头即声明DeprecatedTraeCode CLI 2.0 已支持直接加载 Codex 格式插件。新安装统一走 examples/codex-memory-plugin通过trae-cli命令别名安装本适配器仅保留用于兼容性测试与存量托管安装的清理。因此本文的主线应理解为两部分存量视角理解这套独立 Hooks 适配器当年如何工作对排障、清理、迁移到新方案至关重要演进视角明确“废弃的是独立 Hooks 适配器而不是trae-cli这个 harness”新装用户应通过 examples/memory-plugin-shared/install.sh 的--harness trae-cli安装 Codex 格式插件。目录内的 openviking.integration.json 清单也明确记录了这一状态{ schemaVersion: 1, id: openviking-memory, version: 0.1.0, deprecated: true, replacement: examples/codex-memory-plugin (install through the trae-cli Codex-format alias), clients: [trae-cli], capabilities: [hooks, mcp] }其中replacement字段指向新方案clients表明本适配器仅面向trae-cli这一个客户端区别于 TRAE / TRAE CN 的tr-、trcn-前缀分支。二、运行时边界目录里只有适配器共享运行时由安装器组装理解本包的第一步是认清它的运行时边界examples/trae-cli-memory-hooks目录内只包含 TRAE CLI 特有的适配层没有自带lib/目录共享运行时是在安装时由安装器从examples/memory-plugin-shared/lib组装进去的。三个核心共享模块及其职责如下共享模块职责lib/agent-hook-runtime.mjs处理 profile 注入、recall、capture、commit、session 状态、文件锁、凭据加载与 pending retry 重放lib/mcp-proxy-core.mjs处理 stdio 到 OpenViking/mcp的代理lib/agent-uri-guard.mjs处理PreToolUse阶段对本地文件/Shell 工具收到viking://虚拟路径的拦截这套目录结构与examples/trae-memory-hooks保持一致。安装器的目标布局为将examples/trae-cli-memory-hooks复制到$OV_HOME/agent-integrations/trae-cli将共享运行时组装到$OV_HOME/agent-integrations/memory-plugin-shared/lib。三、安装与卸载一条命令完成3.1 安装由于 TraeCode CLI 2.0 原生支持 Codex 格式插件官方推荐的安装方式是直接使用共享安装器并将trae-cli作为用户可见的 harness 名称bash examples/memory-plugin-shared/install.sh --harness trae-cli在 install.sh 中harness 参数说明为--harness LIST逗号分隔的 harness 列表claude, codex, cursor, trae, trae-cn, trae-cli, zcode, opencode, pi, dsh。使用trae-cli表示 TraeCode CLI 2.0通过其 Codex 兼容插件格式安装。安装器会探测本机的 TRAE CLI 可执行文件trae-cli/traecli/traex任一存在即视为已安装并将其规范命名为trae-cli。3.2 历史安装行为本适配器时代在独立适配器时代安装器过去的行为是将共享运行时组装到$OPENVIKING_HOME/agent-integrations/memory-plugin-shared/lib将本适配器安装到$OPENVIKING_HOME/agent-integrations/trae-cli将 Hook 合并进${TRAECLI_HOME:-${TRAE_HOME:-~/.trae}/cli}/hooks.json在${TRAE_HOME:-~/.trae}/traecli.toml中注册openviking-memoryMCP 服务器。现在的安装器不再安装本适配器而是走 Codex 格式插件路径但保留了trae-cli这个 harness 名称。3.3 卸载bash examples/memory-plugin-shared/install.sh --harness trae-cli --uninstall --yes卸载逻辑在 install.sh 附近当检测到$OV_HOME/agent-integrations/trae-cli目录存在、或traecli.toml中已含[mcp_servers.openviking-memory]时会调用agent_remove_trae_cli_configs清理 hooks 配置与traecli.toml中对应的 MCP 段落并移除已安装的目录。四、Hook 与 MCP 表面四个事件、三种输出形态4.1 四个 Hook 事件本包注册了四个 Hook 事件定义在 hooks/hooks.jsonEventEntry复用评估SessionStartscripts/session-start.mjs复用共享的 thin-harness profile 注入路径要求 TRAE CLI 提供稳定的 session id 或等价的 cwd 兜底UserPromptSubmitscripts/auto-recall.mjs复用共享 recall 路径要求 TRAE CLI 将用户输入暴露为prompt、user_prompt、message或textStopscripts/auto-capture.mjs复用共享 session append 与 commit 辅助要求 TRAE CLI 的 stop 输入将助手回复暴露为last_assistant_message、assistant_message、response、output或text_contentPreToolUsescripts/uri-guard.mjs遵循 Codex Hook 输出风格返回permissionDecision: deny复用共享agent-uri-guard求值器完整的 hooks 模板如下注意命令中的__OPENVIKING_TRAE_CLI_ROOT__占位符安装时会被替换为该目录的绝对路径{ hooks: { SessionStart: [ { matcher: clear|startup|resume, hooks: [ { type: command, command: node __OPENVIKING_TRAE_CLI_ROOT__/scripts/session-start.mjs, timeout: 70 } ] } ], UserPromptSubmit: [ { matcher: *, hooks: [ { type: command, command: node __OPENVIKING_TRAE_CLI_ROOT__/scripts/auto-recall.mjs, timeout: 130 } ] } ], Stop: [ { matcher: *, hooks: [ { type: command, command: node __OPENVIKING_TRAE_CLI_ROOT__/scripts/auto-capture.mjs, timeout: 30 } ] } ], PreToolUse: [ { matcher: Read|Glob|Grep|Bash|RunCommand|Shell, hooks: [ { type: command, command: node __OPENVIKING_TRAE_CLI_ROOT__/scripts/uri-guard.mjs, timeout: 5 } ] } ] } }值得注意的细节SessionStart的 matcher 是clear|startup|resume即只在会话启动/恢复/清空时触发超时 70 秒profile 构建 pending 重放可能较慢UserPromptSubmit与Stop的 matcher 是*所有输入超时分别为 130 秒recall 检索与 30 秒PreToolUse的 matcher 精确限定在Read|Glob|Grep|Bash|RunCommand|Shell这几类本地文件与 Shell 工具上超时仅 5 秒——因为它只需做一次 URI 判定必须足够快。4.2 TRAE CLI 的 Hook 输出协议TRAE CLI 生命周期 Hooks不使用TRAE / TRAE CN 的decision: approve输出风格其输出约定如下无操作的生命周期 Hook 输出{}上下文注入只输出hookSpecificOutput.hookEventName加hookSpecificOutput.additionalContext工具调用的放行/拒绝属于PreToolUse通过hookSpecificOutput.permissionDecision表达权限审批属于PermissionRequest通过hookSpecificOutput.decision.behavior表达。这一点在 trae-cli-hook.mjs 中得到印证emitLifecycleOutput只有在有additionalContext时才写hookSpecificOutput否则输出空对象{}而 uri-guard.mjs 则以 Codex 风格输出hookSpecificOutput.permissionDecision deny并附带permissionDecisionReason。4.3 MCP 服务器注册MCP 服务器名为openviking-memory与 Codex 内存插件同名。本包保持与其他原生 Hook 集成相同的.mcp.json源形状共享安装器会将等价的 Node 代理条目写入 TRAE CLI 的traecli.toml{ mcpServers: { openviking-memory: { command: node, args: [servers/mcp-proxy.mjs], cwd: ., startup_timeout_sec: 30 } } }从源码看安装器实际写入的 TOML 形态更完整——见 install.sh它生成[mcp_servers.openviking-memory]段落并注入OPENVIKING_INTEGRATION_ID、OPENVIKING_INTEGRATION_VERSION、OPENVIKING_HOOK_SOURCEtrae-cli三个环境变量到env字段供 Hook 与 MCP 代理运行时读取。五、源码级剖析三个包装脚本如何汇聚到统一适配器5.1 事件分发的三个薄包装session-start.mjs、auto-recall.mjs、auto-capture.mjs三个文件是极薄的入口只做一件事——设置OPENVIKING_HOOK_EVENT环境变量后动态导入统一适配器// session-start.mjs process.env.OPENVIKING_HOOK_EVENT session-start; await import(./trae-cli-hook.mjs);// auto-recall.mjs process.env.OPENVIKING_HOOK_EVENT user-prompt-submit; await import(./trae-cli-hook.mjs);// auto-capture.mjs process.env.OPENVIKING_HOOK_EVENT stop; await import(./trae-cli-hook.mjs);这样三个 Hook 事件共享同一份逻辑trae-cli-hook.mjs只负责按事件名走不同分支。5.2 统一适配器trae-cli-hook.mjstrae-cli-hook.mjs 是整个适配器的核心从源码结构看其关键设计如下固定身份使用固定的clientId trae-cli与 OpenViking session 前缀trcli-见第 25-26 行刻意不携带 TRAE / TRAE CN 的tr-、trcn-分支。会话 ID 通过共享的deriveAgentSessionId(prefix, input)派生原生会话 ID 由resolveNativeSessionId(input)解析。SessionStart 分支第 55-70 行先取withAgentHookLock文件锁避免并发触发用lastSessionStartAt做 2000ms 的节流去重调用replayAgentPending重放上次失败未提交的 pending 消息断点续传调用buildAgentProfile构建 Agent profile有 profile 时以openviking-context sourcesession-start标签注入。UserPromptSubmit 分支第 72-102 行用resolveTraeCliPrompt(input)从 Hook 输入中提取用户提问对同一次提问做双维度去重优先用generation_id/request_id/message_id/prompt_id事件 ID 判重缺失时退回promptHash 500ms 时间窗口通过共享recallForPrompt执行召回结果缓存在 hook state 中以便 Stop 分支组装对话轮次时对齐提问命中相同提问但无新 recall 块时复用state.recallBlock避免重复检索。Stop 分支第 104-134 行受cfg.autoCapture开关控制用buildTraeCliTurns(input, state)从输入与 state 中还原「用户提问 助手回复」轮次用stableHash(turnKey, role, content)计算轮次哈希并与capturedHashes最多保留 1000 条比对去重通过共享addAgentMessages写入 session随后commitAgentSession提交capturedSinceCommit统计自上次提交以来的累积捕获量。异常兜底main().catch保证任何异常都被记录logError(uncaught, error)并输出{}不会因 Hook 失败阻塞 TRAE CLI 主流程。5.3 字段映射trae-cli-turns.mjstrae-cli-turns.mjs 负责 TRAE CLI Hook 输入字段的适配核心是两个容忍性很强的解析函数resolveTraeCliPrompt(input)按prompt→user_prompt→userPrompt→message→text顺序取用户提问resolveTraeCliResponse(input)按last_assistant_message→lastAssistantMessage→assistant_message→assistantMessage→response→output→text_content顺序取助手回复。cleanTraeCliText会剥离上一轮注入的openviking-context ....../openviking-context与relevant-memories.../relevant-memories标签避免上下文标签被当作真实对话内容回写。buildTraeCliTurns则把解析出的内容组装成[{role:user},{role:assistant}]两元组并过滤空内容。5.4 URI 守卫uri-guard.mjsuri-guard.mjs 在PreToolUse阶段拦截危险的工具调用工具名兼容tool_name/toolName/name/tool工具输入兼容tool_input/toolInput/input/arguments核心判定委托给共享的evaluateAgentUriGuard(toolName, toolInput)当本地文件工具Read/Glob/Grep或 Shell 工具Bash/RunCommand/Shell收到viking://虚拟路径时返回permissionDecision: deny并附上permissionDecisionReason该文件同时具备“直接执行”与“模块导入”双形态通过import.meta.url与process.argv[1]的 realpath 比较判断是否为入口执行被测试导入时仅导出evaluateTraeCliUriGuard。5.5 测试覆盖目录内附带了 trae-cli-hooks.test.mjs用于验证字段映射与 Hook 分支逻辑。如果你要扩展 TRAE CLI 的字段兼容面这是回归测试的锚点。六、用户级安装形态hooks.json 与 traecli.toml6.1 Hook 配置文件安装器渲染 hooks/hooks.json 时把__OPENVIKING_TRAE_CLI_ROOT__替换为本目录的绝对路径然后合并进当前TRAECLI_HOME/hooks.json。常见本地路径为~/.trae/cli/hooks.json从 install.sh 的合并逻辑看写入前会先过滤掉旧的 OpenViking Hook 条目通过isOpenVikingHook识别openviking_integration_id或session-start.mjs/auto-recall.mjs/auto-capture.mjs/uri-guard.mjs/trae-cli-hook.mjs特征并以原子写.bak备份 临时文件 rename落盘。TRAE CLI 也支持在活动traecli.toml的[hooks]段配置 Hook但TUI 的/hooks命令显示的源才是真相source of truth。集成安装时优先使用用户级 hooks 文件这样配置不绑定到单一工作区。6.2 MCP 配置MCP 应添加到活动traecli.toml的[mcp_servers.openviking-memory]段。项目级 MCP 文件如workspace/.trae/.mcp.json或workspace/.trae/mcp.jsonTRAE CLI 虽然支持但不是本集成推荐的写入目标。生效配置可用/mcp或traecli mcp list确认。6.3 排障与验证/hooks查看 TUI 中生效的 Hook 条目/mcp或traecli mcp list查看生效的 MCP 服务器若已安装过旧版 OpenViking TRAE Hook 集应替换或禁用旧条目而不是把新草案并排在旁边——同时运行两套会导致 recall 与 capture 重复每条提问被召回两次、每轮对话被捕获两次。安装器本身也会校验已安装的 Hook 入口与 MCP 配置。七、与 Codex 不重用的部分本适配器刻意隔离了 Codex 插件生态特有的机制保持「仅 TRAE CLI 适配层」的纯净边界不复用 Codex 插件市场的元数据与安装命令不做 Codex 特有的${PLUGIN_ROOT}变量替换不复用 Codex 特有的PreCompact提交流程不解析 Codex transcript 的 JSONL 格式也不使用cx-session_id会话前缀不做 Codex 本地压缩器的启动检测。这也是该目录在 Codex 插件格式出现后走向废弃的根本原因TraeCode CLI 2.0 直接兼容 Codex 格式插件后独立的 TRAE CLI 适配层就失去了存在价值。八、当前兼容性说明与扩展指引三个生命周期 Hook 条目在设计上是可以复用的——只要 TRAE CLI 发送的 Hook 输入 JSON 贴近现有 thin harness 约定。各事件需要的关键字段如下用途可接受字段按优先级会话身份conversation_id、session_id、sessionId、generation_id工作区cwd、workspace_roots、workspaceRoots用户提问prompt、user_prompt、userPrompt、message、text助手回复stoplast_assistant_message、lastAssistantMessage、assistant_message、assistantMessage、response、output、text_content工具调用名称tool_name、toolName、name、tool输入tool_input、toolInput、input、arguments如果 TRAE CLI 后续版本改用其他字段名只需适配 trae-cli-hook.mjs 或本地的文本清理/轮次解析逻辑 trae-cli-turns.mjs共享的 OpenViking 运行时与 MCP 代理可以保持不变——这正是「适配层薄、共享层厚」这一架构的容错红利。九、总结examples/trae-cli-memory-hooks是 OpenViking 与 TRAE CLI 集成演进史上的一个重要过渡节点它证明了「四个 Hook 事件 共享运行时 独立适配层」这套集成模型可以低成本覆盖新的 CLI 客户端——新增一个客户端只需写字段映射、事件分支与薄包装脚本它明确区分了 TRAE CLItrcli-前缀与 TRAE / TRAE CNtr-/trcn-前缀的生命周期 Hook 输出协议差异它的废弃并非架构失败而是 TraeCode CLI 2.0 原生支持 Codex 插件格式后的自然收敛——存量用户应通过 install.sh 的--harness trae-cli迁移到 examples/codex-memory-plugin并借助/hooks、/mcp、traecli mcp list完成新旧配置的核对与清理。如果你正在排查旧安装的残留 Hook、迁移到新插件格式或研究 OpenViking 的 CLI 集成模式本目录的源码与本文的剖析可作为完整的参考基线。【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考