# @groundtrack/hooks 中文文档

规范地址：https://npmcn.com/package/%40groundtrack/hooks/

版本：0\.1\.29
npm 元数据更新时间：2026-11-01T06:44:00.651Z
中文译文更新时间：2026-11-01T07:03:05.581Z
软件包许可：MIT

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40groundtrack/hooks
原文对照：https://npmcn.com/package/%40groundtrack/hooks/?lang=original

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：339 kB，82 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.19
- 运行依赖：3 个
- 首次发布：2026-08-06T05:57:13.659Z
- 最新版本发布：2026-11-01T06:44:00.504Z
- 已发布版本数：30（近 12 个月 30 个）

## 中文简介

用于Groundtrack MCP客户端的生命周期钩子实用程序。

## 安装

```sh
npm install @groundtrack/hooks
```

也可以使用：`pnpm add @groundtrack/hooks`、`yarn add @groundtrack/hooks`、`bun add @groundtrack/hooks`

## README

# @groundtrack /钩子

在一个流程中设置跨Claude Code， Codex， Cursor和OpenCode的Groundtrack。 需要Node.js 18或更新版本。

```sh
npx --yes --package @groundtrack/hooks@latest groundtrack setup
```

选择您使用的代理，检查更改，并完成任何登录或挂钩 每种代理的批准。拾取器检测两个机器安装 以及项目配置。你的选择会被记住；后来添加法典 保留您的工作克劳德和光标连接。

```sh
groundtrack setup --agent codex
groundtrack setup --agent claude --agent codex --agent cursor --yes
groundtrack setup --all-detected --yes
groundtrack setup --agent codex --dry-run
groundtrack status
groundtrack status --json
```

`--agent` 是可重复的。 `--client` 和 `claude-code` 是可接受的别名。 安装程序配置当前项目；它不会在每个地方激活Groundtrack 存储库。使用 `--repo PATH` 选择一个项目和 `--url URL` 为另一个 Groundtrack端点。没有明确的目标，交互式终端显示 选择器。一个无人值守 `--yes` 运行需要先前保存的选择或 显式的 `--agent` / `--all-detected`;它永远不会落在所有已知的特工身上。 空的选择或取消不会产生任何更改。

相同的包提供 `groundtrack-hook`． 安装程序安装这个共享运行时 一次，如果需要，为克劳德，法典，或光标。OpenCode使用 `@groundtrack/opencode-plugin` 代替。重复运行使用已安装的运行时 无需查询NPM以获取每次调用的更新。

CLI验证JSON/JSONC和TOML，保留不相关的设置和注释， 重用现有的Groundtrack别名，并在应用前备份更改的文件 原子写道。备份和选择位于 `$XDG_CONFIG_HOME/groundtrack` (默认 `~/.config/groundtrack`）. 备份可能 包含现有的私有配置，因此它们的目录和文件是私有的。 故障回滚完成的写入，并报告备份 的位置。错误的配置，符号链接，禁用的连接/钩子， 并且报告受影响代理的端点冲突。其他独立 仍然可以配置所选的代理。添加代理不会卸载其他代理。

## 连接与验证

本地检查验证配置，而不是活动的经过身份验证的主机。状态 报告 `configured` 和 `activation: unverified`;它从不推断出一种联系 从生成的文件。每个代理都必须加载连接及其钩子。

交互式设置首先检查本机登录需求。克劳德代码必须 在OAuth之前批准一个新的项目MCP服务器；安装程序将显示该操作 尝试登录失败。Codex可以对选定的端点进行身份验证 在项目和钩子信任保持不变的情况下，使用一个命令的配置重写 明确的用户操作。现有的Claude/OpenCode身份验证被重用 客户端报告它，成功的登录将反映在最终的摘要中。 使用 `--connect` 为选定的客户端重试本机登录。光标, 仅桌面安装将显示其UI步骤。在无人值守的运行中，setup打印指令并且从不阻塞等待 OAuth。 `--json` 返回没有配置内容的结构化结果 凭证;使用 `--yes` 应用显式选择的安装程序。

法典要求审查和信任Groundtrack钩通过 `/hooks` 或其 钩子审批UI。新的法典设置使用 `.codex/hooks.json`;现有的内联 钩子在 `.codex/config.toml` 被识别和修复，没有复制 他们。克劳德的 `CLAUDE.md` 导入共享 `AGENTS.md` 策略。插件是 添加到现有的OpenCode JSON/JSONC配置。

克劳德安装还安装了一个同步 `SessionStart` 签入项目设置。 在启动、恢复、清除或fork时，它会检查本地MCP配置和Claude的配置 自己的 `mcp get` 的地位。如果Groundtrack丢失，残废，等待批准， 未经身份验证或未连接时，Claude显示一个带有修复命令的警告 并给予agent相同的上下文。不完整的OAuth流可能会离开Claude 在 `Needs authentication` 即使 `mcp get` 成功退出;这个状态是 不被视为有联系。检查从不启动OAuth或阻止会话 失败;它的原生探测器有5秒的限制。它需要克劳德项目钩子 启用和信任，而不是实时工具调用的替代品。其他 客户端仍然依赖自己的设置和诊断。

在每个选定的代理中，询问：

> 用search\_experiences验证Groundtrack的连接和钩子上下文。

返回的钩子上下文和指令版本警告决定是否 实时激活需要注意。不需要合成工程事件。

## 医生的兼容性

`groundtrack doctor` 的别名 `status`； `groundtrack doctor --fix` 使用 相同的安装和维修流程。医生检查新发布的钩子包； 如果有可用的策略，请在使用较旧的捆绑策略进行修复之前进行升级。 如果注册表不可用，医生仍然检查本地配置和 保留比自己的模板更新的托管指令。通过调用时 `npx`， Doctor检查全局安装的钩子运行时，而不是 提供的临时可执行文件 `npx`． 现有的单客户端命令继续工作：

```sh
groundtrack doctor --fix --client codex
```

较低级别 `runDoctor` API仍然为现有的消费者服务。新设置使用 客户特定的MCP计划，钩子/插件，和指令，所以它可以预览 并安全修复几种选定的代理商。

## 本地影响力技能（可选择加入）

该包包含一个只读的 `groundtrack-impact` 技能克劳德代码和 法典。它对地方会议进行审计，并就如何进行审查提出一份有证据支持的报告 跑道改变了你的工作。 **安装程序不安装或调用此技能**； 只有当您希望为代理提供对local的访问权限时，才显式地安装它 记录。从这个存储库签出，选择一个代理或两个代理：

```sh
mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
cp -R packages/hooks/skills/groundtrack-impact "${CODEX_HOME:-$HOME/.codex}/skills/"
mkdir -p "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/skills"
cp -R packages/hooks/skills/groundtrack-impact "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/skills/"
```

如果 `@groundtrack/hooks` 安装在另一个项目中，使用 `node_modules/@groundtrack/hooks/skills/groundtrack-impact` 作为复制源 代替。对于Claude Code，将此复制技能设置为 **用户只** 在 `/skills` (或一组 `"groundtrack-impact": "user-invocable-only"` 下 `skillOverrides` 在 克劳德设置)使用前；阻止克劳德把这个装上 自己的转录阅读工作流程。食品的包装 `agents/openai.yaml` 已经 禁用隐式调用。如果需要，重新启动代理，然后显式调用 `$groundtrack-impact` 法典或 `/groundtrack-impact` 在克劳德法典中 授权会话范围。审计显示克劳德 会议从 `CLAUDE_CONFIG_DIR` (默认 `~/.claude`)和法典会议 `CODEX_HOME` (默认 `~/.codex`）; 它从不上传成绩单，也不会运行 session-import命令。代理的模型提供者可以接收选定的本地 分析过程中的上下文。

## 导入编码代理会话

使用在Groundtrack中创建的API密钥导入完成的Codex、Claude Code、Cursor或OpenCode会话 设置。默认作用域是当前Git存储库；修改子代理和文件 在最后五分钟内被排除在外。Groundtrack读取Codex会议 `CODEX_HOME` (默认 `~/.codex`)， Claude sessions从 `CLAUDE_CONFIG_DIR` (默认 `~/.claude`)， 和游标转录本 `CURSOR_HOME` (默认 `~/.cursor`）. 游标元数据来自 其本地 `state.vscdb`;集 `CURSOR_STATE_DB` 以覆盖该数据库路径。光标进口 仅限cli并且需要未标记 `node:sqlite` 支持（Node.js 22.13+， 23.4+或24+）。 OpenCode导入调用已安装的 `opencode` CLI(用 `OPENCODE_BIN`)及用途 用于会话目录和导出的私有临时文件。这避免了OpenCode的大型管道 导出截断，同时确保在本地修剪后删除未消毒的源导出。

```sh
GROUNDTRACK_API_KEY=... groundtrack import --dry-run
GROUNDTRACK_API_KEY=... groundtrack import --yes
GROUNDTRACK_API_KEY=... groundtrack import --agent claude --dry-run
GROUNDTRACK_API_KEY=... groundtrack import --agent claude --all-repos --yes
GROUNDTRACK_API_KEY=... groundtrack import --agent cursor --dry-run
GROUNDTRACK_API_KEY=... groundtrack import --agent cursor --all-repos --yes
GROUNDTRACK_API_KEY=... groundtrack import --agent opencode --dry-run
GROUNDTRACK_API_KEY=... groundtrack import --agent opencode --all-repos --yes
```

该命令在上传前通过确定性隐私过滤器对源文件进行流处理。 推理，系统/开发人员指令，转换上下文而不是模型名称，以及 在本地删除已识别的凭据。上传是顺序的，只能重试 瞬态故障。成功的导入自动记录在 `$XDG_CONFIG_HOME/groundtrack`;收据的范围限定在端点，api密钥指纹， 可见性、源散列和规范化版本。使用 `--json` 对于一个机器可读的 结果对象和 `--url` 用于预览或自托管部署。

默认情况下，导入的脚本是私有的。Groundtrack分析已完成的导入，并可能添加 高可信度提取的经验教训——而不是抄写的内容——是组织的共享知识。 改变成绩单可见性并不能改变这种学习行为；删除导入的 会话收回其派生的知识。

## 观察完成的会话

`groundtrack watch --once` 是未来预定的监视器背后的同步引擎。 一次遍历扫描会话文件元数据，并将其与持久游标进行比较 读取和上传大小或修改时间发生变化的文件。中修改的文件 最后五分钟 `active`;一旦他们安静下来，就把西梅和 使用相同的隐私过滤器和收据上传 `import`.

```sh
GROUNDTRACK_API_KEY=... groundtrack watch --once --agent codex --dry-run
GROUNDTRACK_API_KEY=... groundtrack watch --once --agent codex --all-repos --yes
GROUNDTRACK_API_KEY=... groundtrack watch --once --agent claude --all-repos --yes
```

游标位于 `$XDG_CONFIG_HOME/groundtrack/watch-state-<source>.json` (模式 `0600`）. 未更改的文件不会重新打开、重新散列或重新上传。一个预览 没有 `--yes` 不写入游标状态。每个源只能运行一个watch pass 一次；失效的PID锁自动恢复。循环、文件系统 事件和操作系统计时器故意不属于 `--once`.

Codex分页会话在上传之前被合并。观察员小组开始行动 页面 `session_id`，紧跟着 `history_base.thread_id` 链接，并上传一个 完整的快照。相反，报告一个丢失或仍然存在的页面的链 上传一个片段。

`templates/AGENTS.md` 是托管存储库策略的事实来源。 修改完成后，运行 `pnpm sync:agent-instructions`;测试拒绝两者之间的漂移 安装指南，这个存储库是托管的 `AGENTS.md` 块，以及打包后的模板。

## 开发

Agent id、名称、别名、事件源、富集类型、会话导入 功能是一次性定义的 `src/agents.ts`，出口为 `@groundtrack/hooks/agents`． 命令行、web UI、钩子和服务器都要使用它 目录及其派生类型。保持它不依赖，这样浏览器包就可以 在没有Node-only钩子运行时的情况下加载它。

从存储库构建并测试CLI：

```sh
pnpm --filter @groundtrack/hooks build
node packages/hooks/dist/groundtrack.js setup --repo /path/to/test-project
pnpm --filter @groundtrack/hooks test
```

安装了Claude Code和Codex后，还要运行隔离的本机客户端 飞行前检查（他们不启动OAuth或触摸您的正常代理配置文件）：

```sh
GROUNDTRACK_TEST_NATIVE_CLIENTS=1 pnpm --filter @groundtrack/hooks test
```

这个 `groundtrack-hook` 命令从标准输入读取工具使用前的钩子负载并进行充实 Groundtrack `store_event` 和 `search_experiences` 电话:

-   客户端会话和模型标识符（使用Claude的主机提供的） 当钩子有效载荷忽略模型时，脚本路径)；
-   用于 `store_event`，从主机的工具调用id派生的稳定客户端事件id；和
-   Git收集的存储库、分支、提交和脏工作树上下文。

Git上下文从钩子的工作目录（或单个目录）中收集 游标工作区根)并覆盖模型提供的值。收藏失败 当钩子在Git工作树之外时打开。该命令不发送网络 请求。

更新它：

```bash
npm update -g @groundtrack/hooks
```

## 常见问题

### @groundtrack/hooks 是什么？

用于Groundtrack MCP客户端的生命周期钩子实用程序。

### 如何安装 @groundtrack/hooks？

在项目目录运行 npm install @groundtrack/hooks，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 groundtrack、groundtrack-hook，可以用 npx groundtrack 直接运行。

### @groundtrack/hooks 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @groundtrack/hooks 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @groundtrack/hooks 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22\.19。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @groundtrack/hooks 可以商用吗？

@groundtrack/hooks 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @groundtrack/hooks 还在维护吗？

最新版本 0\.1\.29 发布于 2026/11/01（2 天前）；至今共发布 30 个版本，其中过去 12 个月发布了 30 个；首次发布于 2026/08/06。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。