Gryph：为AI编程助手打造本地化行为审计与可观测性工具

1. 项目概述：为AI编程助手戴上“行车记录仪”

如果你和我一样，在日常开发中重度依赖Claude Code、Cursor这类AI编程助手，那你一定经历过这样的“惊魂时刻”：你让它重构一个模块，它噼里啪啦一顿操作，然后你跑测试——挂了。这时候你脑子里会蹦出无数个问号：它刚才到底干了什么？它读了哪些文件？有没有偷偷执行什么危险的rm -rf命令？有没有动我的.env配置文件？在Gryph出现之前，这些问题基本无解，你只能对着最终被改得面目全非的代码干瞪眼，或者靠git diff那点有限的信息去猜。

Gryph，这个由SafeDep团队开源的工具，就是为了解决这个痛点而生的。你可以把它理解成AI编程助手的“行车记录仪”或“黑匣子”。它通过轻量级的钩子（Hook）技术，无缝嵌入到主流的AI编程助手（如Claude Code、Cursor、Gemini CLI等）中，实时、无感地记录下助手每一次的“动作”——无论是读取文件、写入文件，还是执行Shell命令。所有这些记录都会被安全地存储在你本地的SQLite数据库中，你可以随时查询、回放、审计，甚至进行统计分析。最关键的是，它完全在本地运行，没有任何云端组件或遥测数据，你的代码和操作隐私得到了最大程度的保护。

简单来说，Gryph在AI助手和你之间建立了一个透明的安全与可观测层。它不阻止AI做任何事，但它记下了AI做的每一件事。当出现问题需要排查，或者你单纯想了解AI的工作模式时，Gryph就是你最可靠的“回放”工具。对于任何严肃使用AI辅助编程的开发者、团队安全负责人，或是想深入研究AI Agent行为模式的研究者，Gryph都是一个不可或缺的利器。

2. 核心问题与设计思路：为什么我们需要AI助手的行为审计？

在深入Gryph的安装和使用之前，我们有必要先厘清它要解决的核心问题。AI编程助手带来的效率提升是颠覆性的，但随之而来的是一种全新的、隐形的“信任危机”。

2.1 AI编程助手的“权限黑洞”

传统的开发工具，权限是清晰且受控的。文本编辑器只能读写你打开的文件，终端命令需要你明确输入并回车确认。但AI编程助手打破了这一切。以Claude Code为例，在一个典型的会话中：

• 无边界文件访问：它可以读取你项目目录下（甚至之外）的任何文件，作为它决策的上下文。
• 任意文件写入：它可以直接修改源代码、配置文件、文档，而无需你逐条确认。
• 命令执行权：它可以调用系统Shell，执行npm install、git commit、curl甚至更危险的命令。

更关键的是，这一切发生得极快。一次中等复杂度的重构，AI可能在几十秒内发起数十次工具调用（Tool Calls）。作为人类，你根本来不及，也不可能实时监控每一个动作。这就形成了一个“权限黑洞”：AI拥有极高的、不受实时监督的操作权限。

2.2 传统排查手段的无力

当AI的操作导致问题时，我们现有的排查工具显得捉襟见肘：

• git diff：只能展示最终的文件状态差异，无法还原操作序列。你不知道AI是先读了A文件再改B文件，还是执行了某个命令后才进行的修改。
• 终端历史：AI执行的命令可能不会完整地显示在你的终端历史记录中，特别是那些通过内部API调用的命令。
• 文件系统监控：工具如inotify可以监控文件变化，但无法关联到具体的AI会话，也无法捕获命令执行和文件读取行为。

结果就是，问题排查变成了“猜谜游戏”。你失去了对开发环境所发生变化的完整感知和控制力。

2.3 Gryph的设计哲学：可观测性而非限制

面对这个问题，Gryph选择了一条非常务实的路径：它不试图去限制或审批AI的每一个动作（那会严重拖慢交互速度，违背使用AI的初衷），而是致力于提供完整的可观测性（Observability）。

它的设计思路清晰而有力：

1. 无侵入接入：通过各AI助手官方或社区支持的钩子机制进行集成，无需修改AI助手本体代码。
2. 全生命周期捕获：钩子安装在“工具调用前”（PreToolUse）和“工具调用后”（PostToolUse），从而能捕获一个动作的完整上下文，包括输入参数和输出结果。
3. 本地化与隐私优先：所有数据存储在本地SQLite数据库，无任何数据外传。对敏感文件（如.env,*.pem）的访问会被特殊标记，且内容不会被存储。
4. 强大的查询能力：提供类似日志查询系统的CLI工具，可以按时间、会话、Agent类型、操作类型、文件路径等维度进行灵活检索和统计分析。

这个设计完美地平衡了效率与安全。开发者依然可以享受AI助手带来的“YOLO模式”（快速尝试）的高效，但同时拥有了事后的“复盘”和“审计”能力。从团队协作和安全合规的角度看，这更是为AI辅助开发引入了一层必要的治理。

3. 安装与初始配置：十分钟内搭建你的审计层

Gryph的安装过程被设计得极其简单，几乎是一键式的。但作为资深用户，我建议你花几分钟了解其背后的机制，这有助于后续的问题排查和深度定制。

3.1 一键安装与原理剖析

最推荐的安装方式是使用官方安装脚本：

curl -fsSL https://raw.githubusercontent.com/safedep/gryph/main/install.sh | sh

执行这条命令后，脚本会：

1. 检测你的操作系统（macOS, Linux, Windows）和架构。
2. 从GitHub Releases下载对应平台的最新预编译二进制文件。
3. 将gryph可执行文件安装到系统的可执行路径下（通常是/usr/local/bin或~/.local/bin）。
4. 你可以立即运行gryph --version来验证安装。

注意：如果你对直接通过curl执行远程脚本有安全顾虑（这是良好的安全习惯），可以采取分步操作：先下载安装脚本curl -O https://raw.githubusercontent.com/safedep/gryph/main/install.sh，审查其内容后，再运行sh install.sh。

安装完成后，核心的步骤是让Gryph“嵌入”到你的AI助手中。这通过gryph install命令完成：

gryph install

这个命令是Gryph的魔法所在。它会自动扫描你的系统，检测已安装的、受支持的AI编程助手（如Claude Code、Cursor等），然后为每一个检测到的助手安装钩子。

钩子安装的底层原理： 以Claude Code为例，其配置通常位于~/.claude/settings.json。gryph install会在这个配置文件的hooks部分添加新的条目。这些条目指向Gryph本地启动的一个HTTP服务端点。当Claude Code即将执行一个工具调用（如file_read）时，它会按照配置，向Gryph的钩子端点发送一个包含操作详情的JSON事件。Gryph接收并记录这个事件后，Claude Code才继续执行实际的操作。post-tool钩子则在操作完成后被触发，用于记录操作结果。这种方式对AI助手的性能影响微乎其微，但实现了全量的行为捕获。

3.2 安装验证与多Agent管理

安装完成后，强烈建议运行以下命令进行验证：

gryph status

这个命令会输出一个清晰的表格，展示：

• 检测到的所有AI助手（Agent）。
• 每个助手的钩子安装状态（如installed,not installed,outdated）。
• 钩子类型（如pre-tool,post-tool）是否齐全。
• Gryph守护进程的运行状态。

如果某个你常用的助手显示not installed，你可以单独为其安装钩子：

gryph install --agent claude-code # 仅为Claude Code安装 gryph install --agent cursor # 仅为Cursor安装

有时你可能想先预览一下install命令会做什么，避免直接修改配置文件。这时可以使用--dry-run（试运行）标志：

gryph install --dry-run

这个命令会模拟安装过程，列出它会检测到哪些Agent，以及会修改哪些配置文件，但不会实际进行任何写入操作。这对于在团队中推广或编写自动化脚本时非常有用。

3.3 关键配置调优：让日志信息更丰富

默认配置下的Gryph已经可以记录所有关键操作。但如果你想进行深度调试或分析，调整日志级别是首要任务。

通过gryph config show可以查看所有当前配置。其中，logging.level是最重要的配置项之一。它有三个等级：

• minimal（默认）：记录最基本的元数据，如操作类型、文件路径、时间戳、会话ID。不记录文件内容差异和命令输出。
• standard：在minimal基础上，增加文件变更的统计信息（如增删行数）、命令的退出码，以及截断后的命令输出（防止日志过大）。
• full：记录最完整的信息，包括文件内容的完整差异（diff）、原始的未加工的事件数据，以及更多的会话上下文。这是调试复杂问题时的利器，但日志量会显著增大。

我个人的经验是，在日常开发中将级别设为standard，这是一个很好的平衡点。当遇到棘手的问题需要复盘AI的完整思考链条时，再临时切换到full级别。

# 设置日志级别为 standard gryph config set logging.level standard # 如果需要深度调试，临时切换到 full gryph config set logging.level full # ... 进行你的调试会话 ... gryph config set logging.level standard # 调试完成后改回来

另一个需要注意的配置是数据保留策略。默认情况下，Gryph会保留90天内的所有事件。你可以通过gryph retention status查看当前数据库大小和保留策略。如果磁盘空间紧张，可以手动清理更早的数据：

# 预览哪些旧数据会被清理 gryph retention cleanup --dry-run # 实际执行清理 gryph retention cleanup

4. 核心功能实战：像侦探一样审查AI的一举一动

安装配置妥当后，Gryph就化身为一个静默的观察者。现在，让我们来看看如何利用它强大的查询能力，将记录的数据转化为洞察。

4.1 实时监控与日志查看

最直接的需求就是看看AI助手刚刚做了什么。gryph logs命令是你的第一站。

• 查看最近活动：直接运行gryph logs会默认显示过去24小时内的所有事件，以清晰易读的表格形式呈现，包括时间、Agent、操作类型、目标文件/命令等。
• 实时流式监控：这可能是最酷的功能之一。打开一个终端，运行：

  gryph logs --follow

  然后，在另一个窗口中使用AI助手进行编程。你会看到第一个终端里像电影《黑客帝国》的字符流一样，实时滚动出AI的每一个动作。这对于理解AI的工作节奏和模式非常有帮助。
• 按需过滤：如果你只关心某个特定助手或今天的活动，可以使用过滤器：

  gryph logs --today # 只看今天 gryph logs --agent cursor # 只看Cursor助手的活动 gryph logs --action file_write # 只看文件写入操作 gryph logs --follow --agent claude-code --action exec # 实时监控Claude Code执行的命令

4.2 深度历史查询与场景分析

gryph logs适合看近期概况，而gryph query则是用于对历史数据进行“掘金”的瑞士军刀。它的查询能力非常灵活，支持多种过滤条件和输出格式。

场景一：追查“神秘”的文件变更你的一个配置文件突然不起作用了，你怀疑是AI助手之前某次会话误改了它，但不确定是什么时候。

# 查询过去一周内，对 `config/` 目录下任何文件的写入操作 gryph query --file "config/**" --action file_write --since "1w" # 如果你记得大概的文件名，可以更精确 gryph query --file "config/database.yml" --action file_write --since "2w"

这条命令会列出所有匹配的事件。每个事件都有唯一的ID，你可以用这个ID进一步查看这次写入的具体差异。

场景二：审计AI执行的命令AI助手有时会“自作主张”地运行一些安装或清理命令，这些命令不会体现在git历史中。

# 查看过去3天所有执行过的命令 gryph query --action exec --since "3d" # 特别关注可能安装依赖的命令 gryph query --command "npm *" --since "1w" gryph query --command "pip *" or "python -m pip *" --since "1w" gryph query --command "go get *" --since "1w"

这对于管理项目依赖和排查环境问题至关重要。你可能会惊讶地发现AI在你不注意的时候更新了某个库的版本。

场景三：安全审查——谁动了我的敏感文件？Gryph内置了敏感文件检测模式（匹配如.env,*.pem,*secret*,.ssh/,.aws/等模式）。任何对这类文件的访问（无论是读还是写）都会被特殊标记。

# 查询所有涉及敏感文件的操作（默认查询会排除敏感事件详情，需用--sensitive显示） gryph query --sensitive --since "30d"

更重要的是，Gryph的隐私设计是：它只记录对敏感文件的访问“行为”和路径，但永远不会存储这些文件的实际内容。这既满足了审计需求，又彻底杜绝了敏感信息泄露的风险。

场景四：会话回放与问题复盘这是Gryph的杀手级功能。当你的测试因为AI的修改而失败时，不再需要盲目猜测。

1. 首先，找到导致问题的AI会话。gryph sessions命令可以列出所有会话及其时间、使用的Agent。
2. 复制你怀疑的那个会话ID。
3. 使用gryph session <session-id>来完整回放该会话。这会按时间顺序列出该会话中的所有事件。
4. 为了更清晰地看到代码变化，加上--show-diff参数：

   gryph session abc123def456 --show-diff

   现在，你就像在看一部慢放电影，AI在会话中先读了哪个文件，然后基于那个上下文执行了什么命令，最后如何修改了你的代码，每一步的差异都清晰可见。绝大多数“灵异”问题在这个回放面前都会真相大白。

4.3 数据导出与集成

Gryph的数据价值不仅限于CLI查看。你可以将数据导出，集成到更庞大的可观测性体系中。

# 将过去一周的数据导出为JSON Lines格式，便于用jq等工具处理 gryph export --since "1w" -o gryph_audit_last_week.jsonl # 一个实用的例子：统计过去一天各种操作类型的频率 gryph export --since "1d" | jq -r '.action_type' | sort | uniq -c | sort -rn

导出的JSONL格式每一行都是一个完整的事件对象，遵循项目提供的JSON Schema。这意味着你可以轻松地将这些数据导入到Elasticsearch、OpenSearch、Datadog等监控平台，构建自定义的仪表盘，甚至设置告警规则（例如，“如果AI在1小时内对生产配置文件进行了超过3次写入，则触发告警”）。

5. 高级技巧与最佳实践：从使用者到专家

经过一段时间的使用，我总结出一些能让你更高效、更安全地利用Gryph的技巧和策略。

5.1 利用统计面板进行宏观洞察

除了查看单条日志，Gryph内置的统计面板gryph stats能给你一个宏观的视角。运行后，它会进入一个交互式的终端用户界面（TUI），展示诸如：

• 活动概览：事件总数、会话数、涉及的Agent数量。
• 操作类型分布：读文件、写文件、执行命令各自的比例。
• 最活跃的Agent：哪个AI助手“话”最多。
• 最常访问的文件/目录：AI最关注你项目的哪些部分。
• 成本估算（如果事件中包含Token信息）：不同模型、不同会话的大致开销。

你可以用参数过滤特定范围的数据，例如gryph stats --since 7d --agent claude-code来查看过去一周Claude Code的独家报告。这个功能对于团队管理者评估AI工具的使用情况和ROI非常有价值。

5.2 文件差异对比与内容追溯

当gryph query或gryph session显示了一个文件写入事件时，事件ID旁边通常会有一个[DIFF]标记（如果日志级别不是minimal）。你可以使用gryph diff <event-id>命令来查看这次写入导致的精确代码变更。

gryph diff abc123def456_789

输出会以标准diff格式展示文件在写入前后的变化。这对于理解AI的修改意图、审查代码质量，或者简单地回滚某个不需要的更改，提供了最直接的依据。

5.3 敏感信息处理与隐私加固

Gryph在隐私保护上做了深思熟虑的设计，但作为用户，我们也可以主动加固：

1. 审查敏感文件模式：Gryph的默认敏感文件列表是保守的。你可以根据项目实际情况，考虑将更多包含机密的文件路径加入你的本地.gitignore或通过脚本排除，但请注意Gryph本身不存储内容，所以主要风险在于事件日志的路径信息泄露。确保你的工作电脑本身是安全的。
2. 定期清理数据：虽然默认保留90天，但对于高度敏感的项目，你可能希望缩短这个周期。可以创建一个定时任务（Cron job或Systemd timer），定期执行gryph retention cleanup，只保留最近7天或30天的数据。
3. 数据库加密：Gryph使用SQLite。对于有极端安全需求的用户，可以考虑使用支持加密的SQLite版本，或者将Gryph的数据目录（~/.local/share/gryph/on Linux）放在一个加密的磁盘卷上。

5.4 故障诊断与“医生”模式

如果发现Gryph没有记录到某个AI助手的事件，或者gryph logs没有输出，可以按以下步骤排查：

1. 运行健康检查：gryph doctor命令会进行一系列诊断，检查二进制文件、数据库连接、钩子配置等，并给出修复建议。
2. 检查Agent状态：再次运行gryph status，确认目标Agent的钩子显示为installed且状态正常。有时AI助手更新后会重置配置文件，需要重新运行gryph install。
3. 查看Gryph自身日志：Gryph也会记录自己的操作。gryph self-log可以查看这些内部日志，有助于发现服务启动或事件接收过程中的错误。
4. 验证钩子端点：Gryph会启动一个本地HTTP服务来接收钩子事件。你可以检查这个服务是否在运行（默认端口可能在gryph status中显示），或者尝试手动发送一个测试事件（具体方法可参考项目文档的Advanced部分）。

6. 团队协作与安全治理实践

将Gryph从个人工具扩展到团队环境，能发挥更大的价值，特别是在安全合规要求严格的金融、医疗或大型科技公司。

6.1 统一部署与配置管理

在团队中推广Gryph，建议采用一致化的部署方式：

• 使用包管理器：如果团队使用Homebrew（macOS/Linux）或Chocolatey（Windows），可以将Gryph加入内部软件仓库，方便成员一键安装。

  # 例如，通过内部Homebrew Tap brew install your-company/tap/gryph

• 共享配置模板：创建一个团队共享的Gryph基础配置模板（例如，通过gryph config show > team_gryph_config.yaml导出，进行适当修改后分发）。可以统一设置较高的日志级别（如standard）、定义团队统一的敏感文件模式、设置合理的数据保留策略（如30天）。
• 自动化安装钩子：在员工入职环境设置脚本中，加入gryph install命令，确保所有开发机器上的AI助手都被默认监控。

6.2 构建集中式审计流水线

虽然Gryph数据默认存储在本地，但团队可以建立一个轻量级的集中审计流程：

1. 定期导出与上报：编写一个简单的脚本，让开发者的机器定期（例如每天）将Gryph的审计日志（使用gryph export）加密后发送到一个安全的内部日志收集服务（如Fluentd, Vector, 或直接到S3）。
2. 集中分析与告警：在日志平台（如OpenSearch, Splunk）中，对上报的Gryph事件进行分析。可以创建仪表盘，监控：
   • 异常行为：短时间内大量文件删除操作、频繁访问非项目路径、执行高危命令（如chmod,dd,rm -rf /等模式匹配）。
   • 成本监控：汇总各团队、各项目的AI Token使用量，优化资源分配。
   • 合规性报告：定期生成报告，证明对AI编码活动的审计覆盖，满足内部或外部审计要求。
3. 安全事件响应：当集中监控系统发现可疑模式时，可以触发告警，安全团队能够迅速定位到相关开发者和会话ID，结合本地的gryph session回放进行深入调查。

6.3 制定AI助手使用安全规范

Gryph提供了技术手段，团队还需要配套的管理规范：

• 明确使用场景：规定AI助手可用于哪些类型的任务（如代码补全、生成测试、文档编写），不推荐或禁止用于哪些任务（如直接操作生产数据库连接字符串、处理未脱敏的批量用户数据）。
• 代码审查关注点：在Code Review中，对于由AI生成或大幅修改的代码，审查者可以要求作者提供相关的Gryph会话ID或关键事件ID，作为理解变更上下文和验证安全性的辅助材料。
• 事故复盘工具：当由AI助手引入的缺陷导致线上事故时，Gryph的记录成为复盘环节的关键证据，帮助厘清是需求理解偏差、生成了错误代码，还是执行了不当操作，从而改进使用流程。

7. 常见问题与故障排除实录

在实际使用中，你可能会遇到一些典型问题。以下是我和社区成员遇到过的情况及解决方法。

7.1 钩子安装失败或无效

问题：运行gryph install后，gryph status显示某个Agent的钩子为not installed或error。

• 可能原因1：配置文件路径不标准。某些AI助手的便携版或自定义安装可能将其配置文件放在非标准位置。
  • 排查：手动检查该Agent的配置目录是否存在（如~/.claude/,~/.cursor/）。运行gryph install --dry-run --agent <agent-name>查看Gryph尝试修改的具体文件路径。
  • 解决：如果路径不对，可以尝试创建符号链接，或者向Gryph项目提Issue，请求支持新的配置路径。
• 可能原因2：配置文件权限问题。Gryph需要写入这些配置文件。
  • 排查：检查目标配置文件是否可写（ls -la ~/.claude/settings.json）。
  • 解决：调整文件权限，或使用sudo（不推荐，可能引发其他问题）运行安装命令。更好的方式是以正确的用户身份运行。
• 可能原因3：Agent不支持或版本过旧。
  • 排查：查看Gryph官方文档的“Supported Agents”列表，确认你的Agent版本是否在支持范围内。
  • 解决：更新你的AI助手到最新版本，然后重新运行gryph install。

7.2 无法看到实时日志（gryph logs --follow无输出）

问题：启动了实时日志跟随，但使用AI助手时没有任何输出。

• 可能原因1：Gryph服务未运行。钩子需要将事件发送到Gryph的本地服务。
  • 排查：运行gryph status，查看“Gryph Daemon”状态。运行ps aux | grep gryph查看相关进程。
  • 解决：尝试重启Gryph服务。有时可以通过gryph doctor命令获取修复建议。最彻底的方法是重启电脑或手动结束相关进程后重新操作。
• 可能原因2：钩子事件未被触发。
  • 排查：确认AI助手确实在执行会产生事件的操作（如文件读写、命令执行）。有些简单的补全操作可能不触发工具调用。
  • 解决：尝试让AI助手执行一个明确会写入文件的操作（如“创建一个新文件test.py”），看是否有日志产生。
• 可能原因3：过滤器设置过严。
  • 排查：你是否在gryph logs --follow后面加了--agent或--action过滤器，而当前活动不符合过滤条件？
  • 解决：先运行不加过滤的gryph logs --follow进行测试。

7.3 数据库文件过大或性能下降

问题：使用一段时间后，发现~/.local/share/gryph/data/gryph.db文件变得很大（例如超过几个GB），或者查询命令变慢。

• 可能原因：积累了大量的full级别日志事件。full级别会记录完整的文件差异，数据量增长很快。
  • 解决：
    1. 调整日志级别：长期使用建议设为standard。gryph config set logging.level standard。
    2. 清理历史数据：运行gryph retention cleanup，默认会清理90天前的数据。你可以通过--keep-days参数调整，例如gryph retention cleanup --keep-days 30只保留最近30天数据。
    3. 手动清理数据库（进阶）：如果急需释放空间，可以备份后删除数据库文件，Gryph会在下次启动时自动创建新的。但会丢失所有历史记录。rm ~/.local/share/gryph/data/gryph.db。
    4. 考虑更激进的保留策略：对于纯个人使用，可能只需要保留最近几天的数据用于问题排查。可以设置一个每周运行的定时任务来清理旧数据。

7.4 与其他工具或插件的冲突

问题：安装Gryph后，AI助手本身或其他插件出现异常。

• 可能原因：钩子配置冲突。某些AI助手可能已经配置了其他插件或自定义钩子。
  • 排查：检查被修改的配置文件（如~/.claude/settings.json），查看hooks部分，确认Gryph的条目是否正确插入，且JSON格式有效。
  • 解决：
    1. 使用gryph uninstall暂时卸载钩子，观察问题是否消失，以确认冲突源。
    2. 如果问题消失，可以尝试gryph install --dry-run查看Gryph的修改，然后手动编辑配置文件，确保Gryph的钩子条目与其他条目正确共存（注意JSON数组的逗号分隔）。
    3. Gryph在安装时会自动备份原文件。在极端情况下，可以使用gryph uninstall --restore-backup还原到安装前的配置状态。

7.5 无法识别特定AI助手

问题：你使用的一个AI助手不在Gryph的官方支持列表中，gryph install检测不到它。

• 可能原因：该助手可能比较新，或者使用了非标准的钩子机制。
  • 解决：
    1. 查阅该AI助手的官方文档，看是否公开了插件或钩子API。
    2. 在Gryph的GitHub仓库的Issues中搜索或提问，询问社区是否有人已经实现了对该助手的支持。
    3. 如果你是开发者，可以考虑参考Gryph现有的钩子实现（通常在项目internal/hooks/目录下），为其贡献一个新的钩子实现。Gryph项目是开源的，欢迎社区贡献。

Gryph作为一个正在快速发展的项目，其社区非常活跃。遇到任何文档中未涵盖的奇怪问题，去项目的GitHub Issues页面搜索或提问，通常是解决问题最快的方式。开发者们通常很乐意帮助用户解决集成和使用中的困难。