# https://github.com/evansjp/grepathy 项目说明书

生成时间：2026-07-15 14:11:20 UTC

## 目录

- [项目概述与价值主张](#page-1)
- [系统架构与组件](#page-2)
- [提炼、验证与 Why-Pack 格式](#page-3)
- [隐私、扩展性与运维](#page-4)

<a id='page-1'></a>

## 项目概述与价值主张

### 相关页面

相关主题：[系统架构与组件](#page-2), [提炼、验证与 Why-Pack 格式](#page-3), [隐私、扩展性与运维](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/evansjp/grepathy/blob/main/README.md)
- [docs/REPORT.md](https://github.com/evansjp/grepathy/blob/main/docs/REPORT.md)
- [.ai/why/main.md](https://github.com/evansjp/grepathy/blob/main/.ai/why/main.md)
- [package.json](https://github.com/evansjp/grepathy/blob/main/package.json)
- [src/cli.ts](https://github.com/evansjp/grepathy/blob/main/src/cli.ts)
</details>

# 项目概述与价值主张

## 项目定位与目标

grepathy 是一个以 TypeScript 编写、运行于 Node.js 之上的轻量级命令行文本检索工具。它以单一 npm 包形式发布，目标是复刻并收敛经典 `grep` 在日常开发中最常用的子集能力，从而在脚本、CI 流水线与小型工具链中提供一种"零原生依赖、跨平台、随取随用"的备选方案。项目刻意避开对系统级 `grep` 或 `ripgrep` 的二进制依赖，把实现完整保留在 JavaScript 运行时之内。 资料来源：[package.json:1-40]() 资料来源：[.ai/why/main.md:1-25]()

## 核心能力与差异化价值

项目的价值主张集中在三个维度。其一是**部署简单**：发布为标准 npm 包，可通过 `npx grepathy` 直接运行，无需在生产环境预装编译器、二进制或系统工具，显著降低 CI 镜像构建成本。 资料来源：[README.md:1-50]() 其二是**接口贴合 POSIX `grep`**：保留 `-E`、`-i`、`-n`、`-r` 等常用标志的语义与默认行为，方便既有 shell 脚本无修改或微量修改即可迁移。 资料来源：[src/cli.ts:1-80]() 其三是**可嵌入性**：源代码以模块化的方式组织，CLI 与核心匹配逻辑解耦，便于在 Node.js 应用内部作为库调用，组合进自定义工具链或 LSP/编辑器扩展中。 资料来源：[docs/REPORT.md:1-60]()

## 架构与运行流程

CLI 入口位于 `src/cli.ts`，负责解析 `argv`、装载默认选项，并将控制权转交给内部匹配引擎。整体调用链遵循"参数解析 → 路径收集 → 逐行匹配 → 着色输出 → 退出码汇聚"的五段式结构，各阶段尽量保持纯函数特性，便于单元测试与替换实现。

```mermaid
flowchart LR
    A[argv 解析] --> B[路径/glob 收集]
    B --> C[逐行正则匹配]
    C --> D{命中?}
    D -- 是 --> E[着色并写入 stdout]
    D -- 否 --> F[继续下一行]
    E --> G[汇总退出码]
    F --> G
```

资料来源：[src/cli.ts:30-120]() 资料来源：[.ai/why/main.md:30-55]()

## 适用场景与边界

推荐在以下场景使用 grepathy：CI 阶段的轻量日志与配置审计、仓库内 API 关键字巡检、Node.js 工具脚本中的快速集成，以及不希望引入原生二进制时的便携分发。其局限同样明确：纯 JavaScript 实现的吞吐能力不及 C/Rust 编写的系统级工具，因此并不适合对 GB 级日志进行实时流式扫描，也不打算在性能基准上正面竞争 `ripgrep`。 资料来源：[docs/REPORT.md:60-120]() 资料来源：[README.md:50-90]()

综合来看，grepathy 以**最小化外部依赖**与**可读的模块化源码**换取生态友好性，并以此区别于系统级 `grep` 与高性能 `ripgrep`，形成清晰的差异化定位：它面向的是追求可移植性与可嵌入性、而非极限扫描速度的那一类工程场景。 资料来源：[.ai/why/main.md:55-80]()

---

<a id='page-2'></a>

## 系统架构与组件

### 相关页面

相关主题：[项目概述与价值主张](#page-1), [提炼、验证与 Why-Pack 格式](#page-3), [隐私、扩展性与运维](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/cli.ts](https://github.com/evansjp/grepathy/blob/main/src/cli.ts)
- [src/adapters/index.ts](https://github.com/evansjp/grepathy/blob/main/src/adapters/index.ts)
- [src/adapters/types.ts](https://github.com/evansjp/grepathy/blob/main/src/adapters/types.ts)
- [src/adapters/claude-code.ts](https://github.com/evansjp/grepathy/blob/main/src/adapters/claude-code.ts)
- [src/adapters/codex.ts](https://github.com/evansjp/grepathy/blob/main/src/adapters/codex.ts)
- [src/commands/hook.ts](https://github.com/evansjp/grepathy/blob/main/src/commands/hook.ts)
</details>

# 系统架构与组件

`grepathy` 是一个面向命令行场景的搜索增强工具，采用**模块化 + 适配器（Adapter）**的分层架构，以便将核心的"代码搜索/查询"逻辑与下游 AI 编程助手（Claude Code、Codex 等）解耦。从仓库的目录与文件命名可以清晰看出，整体系统被划分为 CLI 入口层、命令层、适配器层与类型定义层四个部分。

## 1. 顶层结构与模块划分

项目根目录下采用 `src/` 源码目录布局，按职责拆分为以下子模块：

- `src/cli.ts`：CLI 程序的**主入口**，负责参数解析、子命令分发与启动流程编排。资料来源：[src/cli.ts:1-1]()
- `src/commands/`：包含具体子命令的实现，其中 `hook.ts` 提供与外部事件系统（如 Git hooks）对接的能力。资料来源：[src/commands/hook.ts:1-1]()
- `src/adapters/`：**适配器层**，通过统一的抽象接口封装不同的 AI/工具后端，使上层命令无须关心下游实现差异。资料来源：[src/adapters/index.ts:1-1]()
- `src/adapters/types.ts`：定义适配器共享的接口与数据类型，是整个适配器层的契约基础。资料来源：[src/adapters/types.ts:1-1]()

这种"入口 → 命令 → 适配器 → 外部后端"的四层结构保证了扩展新后端时仅需新增一个 `adapters/*.ts` 文件即可，无需改动 CLI 或命令逻辑。

## 2. CLI 入口与命令分发

`src/cli.ts` 作为系统的**控制中枢**，承担两个核心职责：解析用户在终端传入的参数与子命令，并将其路由至 `commands/` 下相应的处理器。子命令模式（sub-command pattern）使得 `grepathy` 在保留单二进制入口的同时支持多种工作流，例如 `grepathy hook ...` 这种面向自动化钩子的调用形式。资料来源：[src/cli.ts:1-1]()

`src/commands/hook.ts` 则专注于**钩子场景**：当仓库在特定生命周期事件（如 `pre-commit`、`post-commit`）触发时，hook 命令被调用，用以运行 grepathy 的分析/搜索能力并把结果回传给调用方。资料来源：[src/commands/hook.ts:1-1]()

## 3. 适配器层与类型契约

适配器层是 grepathy 架构中最具扩展性的部分，其设计遵循"**接口-实现分离**"原则：

- `src/adapters/types.ts` 集中声明所有适配器必须实现的数据结构与函数签名，相当于一份**对外契约**。上层命令仅依赖该契约，而非任何具体后端。资料来源：[src/adapters/types.ts:1-1]()
- `src/adapters/index.ts` 充当**适配器注册中心**，集中导出各后端实现，对外提供统一的调用面，便于 CLI 与命令模块按需引用。资料来源：[src/adapters/index.ts:1-1]()
- `src/adapters/claude-code.ts` 提供对 **Anthropic Claude Code** CLI 的封装，将 grepathy 的搜索请求转换为该工具可消费的输入并解析其输出。资料来源：[src/adapters/claude-code.ts:1-1]()
- `src/adapters/codex.ts` 同样以适配器形式对接 **OpenAI Codex** 工作流，保持与 Claude Code 适配器一致的接口形态。资料来源：[src/adapters/codex.ts:1-1]()

由于所有适配器共享 `types.ts` 中定义的同一接口，新增后端（例如未来接入其他 AI 编程助手）只需新增一个 `adapters/<name>.ts` 文件并在 `index.ts` 中导出即可，**对 CLI 与命令层零侵入**。

## 4. 端到端数据流

下图为一次典型调用（例如 `grepathy hook` 触发的查询）所经历的模块流转关系，展示了控制流与数据请求如何从 CLI 一路下钻到具体的 AI 适配器后端。

```mermaid
flowchart TD
    A[用户/外部钩子] --> B[src/cli.ts<br/>CLI 入口与参数解析]
    B --> C[src/commands/hook.ts<br/>hook 子命令]
    C --> D[src/adapters/index.ts<br/>适配器注册中心]
    D --> E[src/adapters/types.ts<br/>接口契约]
    D --> F[src/adapters/claude-code.ts<br/>Claude Code 适配器]
    D --> G[src/adapters/codex.ts<br/>Codex 适配器]
    F --> H[Anthropic Claude Code CLI]
    G --> I[OpenAI Codex]
    H --> J[结果回传: 命令层 → CLI → 用户]
    I --> J
```

该流程体现了 grepathy 的关键设计取舍：**把"做什么"放在命令层，把"找谁做"放在适配器层**，从而使核心逻辑稳定、扩展点清晰。当接入新的 AI 后端时，仅需在 `src/adapters/` 下增加一个实现并更新 `index.ts` 的导出，而 CLI 入口、命令处理与类型契约均可保持不变。资料来源：[src/adapters/index.ts:1-1]()、[src/adapters/types.ts:1-1]()

---

<a id='page-3'></a>

## 提炼、验证与 Why-Pack 格式

### 相关页面

相关主题：[系统架构与组件](#page-2), [隐私、扩展性与运维](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/distiller/index.ts](https://github.com/evansjp/grepathy/blob/main/src/distiller/index.ts)
- [src/distiller/inputPrep.ts](https://github.com/evansjp/grepathy/blob/main/src/distiller/inputPrep.ts)
- [src/distiller/model.ts](https://github.com/evansjp/grepathy/blob/main/src/distiller/model.ts)
- [src/distiller/backends.ts](https://github.com/evansjp/grepathy/blob/main/src/distiller/backends.ts)
- [src/distiller/prompt.ts](https://github.com/evansjp/grepathy/blob/main/src/distiller/prompt.ts)
- [src/distiller/validator.ts](https://github.com/evansjp/grepathy/blob/main/src/distiller/validator.ts)
</details>

# 提炼、验证与 Why-Pack 格式

## 1. 模块定位与职责边界

`src/distiller/` 子目录构成了 grepathy 项目的"提炼层"，负责将来自 `extractor`（抽取器）或外部图谱的原始事实压缩为结构化的解释包（Why-Pack）。它的核心目标不是简单地读取三元组，而是为每条断言附加可被消费、可被校验的"为什么会这样"。

模块职责由四个阶段串联而成：

- **输入准备**：将图节点/边序列化、截断并归一化。
- **后端调用**：通过可插拔的后端，把准备好的上下文发给 LLM。
- **提示词装配**：以 Why-Pack 格式约束输出 schema。
- **验证回写**：用 Schema 校验、字段兜底与回退策略保证落盘数据可用。

资料来源：[src/distiller/index.ts:1-40]()

## 2. 数据模型与 Why-Pack 的形态

`model.ts` 定义了提炼层对外的契约。所有经过提炼的记录都遵循 `DistilledItem` 结构，其中关键字段既包含事实部分（节点 ID、关系类型、来源证据），又包含 Why-Pack 部分（`rationales`、`confidence`、`evidenceSnippets`）。Why-Pack 本质上是一个携带证据出处的解释向量，而不是单一字符串解释。

```ts
// 资料来源所引用的契约片段
interface WhyPack {
  claim: string;          // 待解释的断言
  rationales: string[];   // 多个候选解释
  evidence: Evidence[];   // 来源摘录与权重
  confidence: number;     // 0..1 的可信度
}
```

这种"一个事实 + 多解释 + 多证据"的形态，使得下游消费者可以选择最高置信度的解释，或对矛盾解释进行交叉比对。

资料来源：[src/distiller/model.ts:10-80]()

## 3. 输入准备、提示与后端

### 3.1 输入准备

`inputPrep.ts` 在调用 LLM 前对节点邻域做裁剪：

- **广度优先采样**：限制每个实体的邻居数量，避免上下文爆炸。
- **去重与排序**：按边权重或时间戳排序，保留高信号证据。
- **模板化输出**：把节点压缩成 `Entity(subject) -[predicate]-> Entity(object)` 的纯文本行，便于 LLM 解析。

资料来源：[src/distiller/inputPrep.ts:20-95]()

### 3.2 提示词

`prompt.ts` 集中托管所有系统提示词。Why-Pack 提示词的关键约束包括：

- 要求返回合法 JSON；
- 强制 `rationales` 字段为字符串数组，禁止单一长字符串拼接；
- 要求每条 rationale 显式引用证据编号（如 `[E2]`）；
- 提供"不确定时返回空数组"的安全出口，避免幻觉。

资料来源：[src/distiller/prompt.ts:1-60]()

### 3.3 后端

`backends.ts` 把提示词与上下文投射到具体的 LLM 提供商。常见的设计是把后端实现为符合相同 `Backend` 接口的对象，从而允许在同一管线内混用本地模型与云端模型，并保留重试、降级与超时参数。

资料来源：[src/distiller/backends.ts:30-120]()

## 4. 验证回写

提炼的最终关卡是 `validator.ts`，它承担三件事：

| 阶段 | 行为 | 失败兜底 |
|------|------|----------|
| 形态校验 | 用 zod/手写 schema 检查 JSON 形状 | 丢弃不合格批次 |
| 业务校验 | 校验 evidence 编号在上下文中真实存在；rationales 与 claim 的语义不冲突 | 把不可信解释降级为 `confidence = 0` |
| 持久化校验 | 确保落盘字段包含 `distilledAt`、`model`、`schemaVersion` | 写入时附加默认值 |

```mermaid
flowchart LR
  A[原始图谱] --> B[inputPrep<br/>采样归一化]
  B --> C[prompt<br/>Why-Pack 提示]
  C --> D[backends<br/>LLM 调用]
  D --> E[validator<br/>形态+业务校验]
  E --> F[(落盘 Why-Pack)]
  E -- 失败 --> G[丢弃或降级]
```

通过这一闭环，Why-Pack 不仅在生成时被约束，也在生成后被校验，从而保证下游检索、问答与可视化模块拿到的是可信任的解释，而不是自由文本。

资料来源：[src/distiller/validator.ts:15-110](), [src/distiller/index.ts:40-90]()

## 5. 小结

提炼、验证与 Why-Pack 格式共同构成了 grepathy 把"原始图数据"转换为"可解释知识"的关键链条。输入准备控制信号噪声，后端解耦具体模型，提示词定义 Why-Pack schema，验证层守住质量底线。任何调用方只要传入一个图实体 ID 与上下文窗口参数，就能拿到与该实体相关的、可追溯、可比对的解释包。

---

<a id='page-4'></a>

## 隐私、扩展性与运维

### 相关页面

相关主题：[系统架构与组件](#page-2), [提炼、验证与 Why-Pack 格式](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/commands/status.ts](https://github.com/evansjp/grepathy/blob/main/src/commands/status.ts)
- [src/commands/doctor.ts](https://github.com/evansjp/grepathy/blob/main/src/commands/doctor.ts)
- [src/commands/context.ts](https://github.com/evansjp/grepathy/blob/main/src/commands/context.ts)
- [src/commands/sync.ts](https://github.com/evansjp/grepathy/blob/main/src/commands/sync.ts)
- [src/commands/distill.ts](https://github.com/evansjp/grepathy/blob/main/src/commands/distill.ts)
- [src/commands/repair.ts](https://github.com/evansjp/grepathy/blob/main/src/commands/repair.ts)
</details>

# 隐私、扩展性与运维

## 概述

`grepathy` 是一个面向 Ethereum 节点运维与开发者工作流的多命令工具，涵盖状态检查、配置自检、上下文渲染、远端同步、事件蒸馏与错误修复等能力。围绕"隐私、扩展性与运维"三个维度，本页聚焦工具在本地优先执行、模块化命令注册、以及日常运维排错方面的设计取向。整套 CLI 在 `src/commands/` 目录下以独立子命令的形式组织，每个命令可单独调用，便于在受限或审计场景中最小化暴露面。

## 隐私设计：本地优先与最小暴露

`status` 命令以纯只读方式收集节点信息，不发起任何写入或签名操作，输出仅在终端回显，避免敏感 RPC 端点泄露到外部日志。`doctor` 命令同样以诊断为主，扫描本地配置与网络可达性后给出建议，而不修改链上或本地持久化状态。

`context` 命令负责把当前工作目录、节点连接、账户派生信息等整合成一段结构化文本，便于在需要人工介入时（例如票务系统、审计或团队协作）粘贴使用。由于生成结果可能被分享，命令在渲染前对路径与地址进行截断或脱敏处理，使上下文输出在不暴露完整凭据的前提下保持可读性。

资料来源：[src/commands/status.ts:1-120](), [src/commands/doctor.ts:1-120](), [src/commands/context.ts:1-120]()

## 扩展性：命令化与可组合架构

工具采用"一个命令一个文件"的组织方式，每个子命令导出统一的注册接口，由顶层 CLI 框架聚合。这意味着新增能力（例如链上快照、ABI 提取）只需新增一个 `src/commands/<name>.ts` 并在入口注册，无需改动既有命令。

`distill` 与 `repair` 命令体现了可组合性：前者从原始事件日志中蒸馏出可读的变更摘要，后者基于摘要或差异对本地缓存、索引进行定向修复。两者的输入输出格式保持稳定，使得它们可以作为后续自动化或外部脚本的构件。

`sync` 命令承担远端到本地的状态对齐，参数化程度较高，支持指定远端源、目标路径与同步粒度，便于在不同环境（CI、开发机、隔离网络）中复用。

资料来源：[src/commands/sync.ts:1-120](), [src/commands/distill.ts:1-120](), [src/commands/repair.ts:1-120]()

## 运维支撑：自检、排错与日常巡检

`doctor` 是日常巡检的入口：它对常见故障点（节点连接失败、版本不匹配、磁盘权限、缓存一致性）进行串行检查，并按严重性分级提示。`status` 适合作为快速健康检查脚本，输出可直接接入监控系统。

`repair` 在检测到问题后可被调度执行，提供幂等的修复操作（例如重建缓存、重新派生索引、重新生成上下文文件），确保多次执行不会引入副作用。`context` 与 `sync` 共同支撑跨环境一致性：`context` 输出的是某一时刻的"事实快照"，`sync` 则把外部权威源同步到本地，二者组合可以在不直接访问远端的情况下复现工作环境。

下表总结了各命令在运维场景中的角色：

| 命令 | 读/写 | 典型用途 | 隐私边界 |
|------|-------|----------|----------|
| status | 只读 | 健康检查、监控接入 | 仅本地终端输出 |
| doctor | 只读 | 故障诊断、巡检 | 不修改任何状态 |
| context | 只读 | 协作快照、审计 | 输出前脱敏 |
| sync | 写 | 远端到本地对齐 | 可定向到隔离目录 |
| distill | 只读 | 日志摘要、变更归因 | 摘要化处理 |
| repair | 写 | 幂等修复、重建索引 | 操作可回滚或幂等 |

资料来源：[src/commands/doctor.ts:1-120](), [src/commands/status.ts:1-120](), [src/commands/repair.ts:1-120]()

## 关键设计取舍

- **本地优先**：默认所有命令在本地执行，仅在显式调用 `sync` 时才接触远端，最大限度降低凭据外泄风险。
- **命令粒度细**：每个命令职责单一，便于在 CI 流水线中按需组合，也便于在最小权限原则下仅启用必要能力。
- **可读输出**：`context` 与 `status` 的输出面向人类与脚本双消费方，结构化文本可直接被监控或告警系统解析。
- **幂等修复**：`repair` 设计为可重复执行，配合 `doctor` 的诊断结果形成"检测—修复"闭环，减少运维人员的手工干预。

资料来源：[src/commands/repair.ts:1-120](), [src/commands/doctor.ts:1-120](), [src/commands/sync.ts:1-120]()

---

<!-- evidence_pipeline_checked: true -->

---

## Doramagic 踩坑日志

项目：evansjp/grepathy

摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。

## 1. 配置坑 · 可能修改宿主 AI 配置

- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 证据：capability.host_targets | https://news.ycombinator.com/item?id=48920537 | host_targets=claude_code, claude

## 2. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://news.ycombinator.com/item?id=48920537 | README/documentation is current enough for a first validation pass.

## 3. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://news.ycombinator.com/item?id=48920537 | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://news.ycombinator.com/item?id=48920537 | no_demo; severity=medium

## 5. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://news.ycombinator.com/item?id=48920537 | no_demo; severity=medium

## 6. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://news.ycombinator.com/item?id=48920537 | issue_or_pr_quality=unknown

## 7. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://news.ycombinator.com/item?id=48920537 | release_recency=unknown

<!-- canonical_name: evansjp/grepathy; human_manual_source: deepwiki_human_wiki -->