SuperAPI AI 工具集

terraphim-hooks

通用与其它

查看项目

更新于 10-16 06:07

技能介绍

Terraphim Hooks 是基于知识图谱的文本替换能力,通过在关键节点拦截文本并应用知识图谱中定义的转换规则来工作。它适用于在设置或使用 Terraphim 知识图谱替换功能时使用。

一、用途 Terraphim 钩子会在关键节点拦截文本,例如 CLI 命令和提交信息,并使用由知识图谱定义构建的 Aho-Corasick 自动机来应用转换。典型场景是把某个包管理器命令替换成另一个,例如将 npm、yarn、pnpm、npx 等替换为 bun,或将测试命令别名替换为 cargo test 等。

二、主要能力与组件

  • terraphim-agent replace:用于文本替换的 CLI 命令。
  • PreToolUse 钩子:在 Claude Code 工具调用执行前进行拦截。
  • Git 钩子:通过 prepare-commit-msg 转换提交信息。
  • MCP 工具 replace_matches:提供与命令行相同的替换功能,接收 text 和 role 参数。
  • Rust 编程接口:引用 terraphim_hooks 中的 ReplacementService 与 HookResult,以及 terraphim_types 的 Thesaurus,可从知识图谱加载词表后执行替换。

匹配行为:使用 Aho-Corasick 的 LeftmostLongest 匹配策略,较长的模式会先于较短的模式匹配,默认区分大小写。

三、安装与使用方式 安装方式一(使用已发布二进制):通过 GitHub Releases 下载 terraphim-agent,例如 macOS ARM64 使用 terraphim-agent-aarch64-apple-darwin,Linux x86_64 使用 terraphim-agent-x86_64-unknown-linux-gnu,下载后赋予可执行权限并放入 ~/.cargo/bin。注意 crates.io 上的版本(cargo install terraphim_agent)是旧版 v1.0.0,缺少 hook/guard 命令,建议使用 GitHub Releases 获取最新功能。

安装方式二(从源码构建):克隆 terraphim-ai 仓库,执行 cargo build -p terraphim_agent --release,将 target/release/terraphim-agent 复制到 ~/.cargo/bin/。

配置知识图谱:创建 ~/.config/terraphim/docs/src/kg 目录,并在其中创建 Markdown 替换规则文件。文件格式中,标题行(# 后内容)成为替换文本,需使用空格而非下划线;synonyms 行列出需要被替换的别名。例如创建 bun install.md,标题为 bun install,synonyms 为 npm install, yarn install, pnpm install, npm i。

配置 Claude Code 钩子:创建 ~/.claude/hooks/pre_tool_use.sh 脚本,读取 JSON 输入并调用 terraphim-agent hook --hook-type pre-tool-use --json,然后在 ~/.claude/settings.local.json 中为 PreToolUse 配置 matcher 为 Bash 的命令钩子。

CLI 用法:echo "npm install package" | terraphim-agent replace 输出替换结果;加 --json 可输出结构化结果(包含 result、original、replacements、changed);加 --fail-open 在出错时返回原文。

Git 钩子模式:读取提交信息文件,用 terraphim-agent replace --fail-open 处理,若有变化则写回文件。

Agent 可用性检测:可通过 command -v terraphim-agent 检查,或检测 ./target/release/terraphim-agent 与 $HOME/.cargo/bin/terraphim-agent。

四、适用场景

  • 在 Claude Code 中自动把 npm 等命令转换为 bun。
  • 在 Git 提交前转换提交信息中的术语或署名。
  • 在 pre-commit 阶段阻止不需要的模式。
  • 通过 MCP 工具或 Rust 代码在程序化流程中复用同一替换逻辑。

五、限制与错误处理 钩子采用 fail-open 语义:如果找不到 terraphim-agent,则原样传递;如果替换失败,则返回原始文本;错误仅在 verbose 模式下写入 stderr。可设置环境变量 TERRAPHIM_VERBOSE=1 启用 verbose 模式。知识图谱文件使用带 frontmatter 的 Markdown 格式。验证时可通过 ./scripts/test-terraphim-hooks.sh 运行测试脚本,或手动以 JSON 输入测试钩子。常见问题包括钩子未触发(检查 .claude/settings.local.json 配置)、未发生替换(确认 docs/src/kg/ 下存在知识图谱文件)、未找到 agent(用 cargo build -p terraphim_agent --release 构建)、权限被拒绝(对钩子脚本执行 chmod +x)、未安装 jq(用 brew install jq 或 apt install jq 安装)。