Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

简介

什么是PRECC？

PRECC (Claude Code 预测性错误纠正) 是一个Rust工具，通过官方的PreToolUse钩子机制拦截Claude Code的bash命令。它在错误发生之前修复它们，节省token并消除重试循环。

对社区用户免费。

问题

Claude Code在可预防的错误上浪费大量token：

  • 目录错误 – 在没有 Cargo.toml 的父目录中运行 cargo build，然后在读取错误后重试。
  • 重试循环 – 失败的命令产生冗长的输出，Claude读取、推理并重试。每个循环消耗数百个token。
  • 冗长输出 – find 或 ls -R 等命令输出数千行，Claude必须处理这些内容。

四大支柱

上下文修复 (cd-prepend)

检测到 cargo build 或 npm test 等命令在错误的目录中运行时，在执行前添加 cd /正确/路径 &&。

GDB调试

检测附加GDB进行更深入调试的机会，提供结构化的调试信息而不是原始的核心转储。

会话挖掘

挖掘Claude Code会话日志中的失败-修复对。当同样的错误再次发生时，PRECC已经知道修复方法并自动应用。

自动化技能

内置和挖掘技能库，匹配命令模式并重写它们。技能定义为TOML文件或SQLite行，便于检查、编辑和共享。

工作原理（30秒版本）

  1. Claude Code即将运行一个bash命令。
  2. PreToolUse钩子将命令作为JSON通过stdin发送给 precc-hook。
  3. precc-hook 在3毫秒内通过管道（技能、目录修正、压缩）处理命令。
  4. 修正后的命令作为JSON通过stdout返回。
  5. Claude Code执行修正后的命令。

Claude永远看不到错误。没有token浪费。

自适应压缩

如果命令在压缩后失败，PRECC会自动在重试时跳过压缩，以便Claude获得完整的未压缩输出来调试。

实时使用统计

指标值
钩子调用次数–
节省的token–
节省比率–%
RTK重写–
CD修正–
钩子延迟– ms (p50)

数字为估算值。每次预防的失败避免了完整的重试循环：错误输出、模型推理和重试命令。 这些数字会从匿名遥测数据自动更新。

链接

安装

快速安装 (Linux / macOS)

curl -fsSL https://raw.githubusercontent.com/peria-ai/precc-cc/main/scripts/install.sh | bash

这会下载适用于您平台的最新版本二进制文件，验证SHA256校验和，并将其放置在 ~/.local/bin/ 中。

安装后，初始化PRECC：

precc init

precc init 在Claude Code中注册PreToolUse钩子，创建数据目录，并初始化技能数据库。

安装选项

SHA256验证

默认情况下，安装程序会根据已发布的SHA256校验和验证二进制文件。要跳过验证（不推荐）：

curl -fsSL https://raw.githubusercontent.com/peria-ai/precc-cc/main/scripts/install.sh | bash -s -- --no-verify

自定义安装前缀

安装到自定义位置：

curl -fsSL https://raw.githubusercontent.com/peria-ai/precc-cc/main/scripts/install.sh | bash -s -- --prefix /opt/precc

附加工具 (–extras)

PRECC附带可选的附加工具。使用 --extras 安装它们：

curl -fsSL https://raw.githubusercontent.com/peria-ai/precc-cc/main/scripts/install.sh | bash -s -- --extras

这将安装：

工具用途
RTK命令重写工具包
lean-ctxCLAUDE.md和提示文件的上下文压缩
nushell用于高级管道的结构化Shell
cocoindex-code代码索引以加快上下文解析

Windows (PowerShell)

irm https://raw.githubusercontent.com/peria-ai/precc-cc/main/scripts/install.ps1 | iex

然后初始化：

precc init

手动安装

  1. 从 GitHub Releases 下载适用于您平台的发布二进制文件。
  2. 根据版本中的 .sha256 文件验证SHA256校验和。
  3. 将二进制文件放置在 PATH 中的目录中（例如 ~/.local/bin/）。
  4. 运行 precc init。

更新

precc update

强制更新到特定版本：

precc update --force --version 0.3.0

启用自动更新：

precc update --auto

验证安装

$ precc --version
precc 0.3.0

$ precc savings
Session savings: 0 tokens (no commands intercepted yet)

如果找不到 precc，请确保 ~/.local/bin 在您的 PATH 中。

快速入门

5分钟内启动PRECC。

步骤1：安装

curl -fsSL https://raw.githubusercontent.com/peria-ai/precc-cc/main/scripts/install.sh | bash

步骤2：初始化

$ precc init
[precc] Hook registered with Claude Code
[precc] Created ~/.local/share/precc/
[precc] Initialized heuristics.db with 8 built-in skills
[precc] Ready.

步骤3：验证Hook已激活

$ precc skills list
  # Name               Type      Triggers
  1 cargo-wrong-dir    built-in  cargo build/test/clippy outside Rust project
  2 git-wrong-dir      built-in  git * outside a repo
  3 go-wrong-dir       built-in  go build/test outside Go module
  4 make-wrong-dir     built-in  make without Makefile in cwd
  5 npm-wrong-dir      built-in  npm/npx/pnpm/yarn outside Node project
  6 python-wrong-dir   built-in  python/pytest/pip outside Python project
  7 jj-translate       built-in  git * in jj-colocated repo
  8 asciinema-gif      built-in  asciinema rec

步骤4：正常使用Claude Code

打开Claude Code并照常工作。PRECC在后台静默运行。当Claude发出一个会失败的命令时，PRECC会在执行前修正它。

示例：错误目录的Cargo Build

假设你的项目在 ~/projects/myapp/，Claude发出：

cargo build

从 ~/projects/（高了一级，那里没有 Cargo.toml）。

没有PRECC： Claude收到错误 could not find Cargo.toml in /home/user/projects or any parent directory，读取、推理，然后用 cd myapp && cargo build 重试。代价：浪费约2,000个token。

使用PRECC： Hook检测到缺失的 Cargo.toml，在 myapp/ 中找到它，并将命令重写为：

cd /home/user/projects/myapp && cargo build

Claude永远看不到错误。零token浪费。

步骤5：查看节省情况

会话结束后，查看PRECC节省了多少token：

$ precc savings
Session Token Savings
=====================
Total estimated savings: 4,312 tokens

Breakdown:
  Pillar 1 (cd prepends):       2,104 tokens  (3 corrections)
  Pillar 4 (skill activations):   980 tokens  (2 activations)
  RTK rewrites:                 1,228 tokens  (5 rewrites)

后续步骤

  • 技能 – 查看所有可用技能以及如何创建自己的技能。
  • Hook管道 – 了解底层发生了什么。
  • 节省 – 详细的token节省分析。

许可证

PRECC提供两个层级：Community（免费）和Pro。

Community层（免费）

Community层包括：

  • 所有内置技能（错误目录修正、jj翻译等）
  • 支持完整Pillar 1和Pillar 4的Hook管道
  • 基本的 precc savings 摘要
  • 使用 precc ingest 进行会话挖掘
  • 无限本地使用

Pro层

Pro解锁额外功能：

  • 详细节省分析 – precc savings --all 逐命令分析
  • GIF录制 – precc gif 用于创建终端动画GIF
  • IP地理围栏合规 – 适用于受监管的环境
  • 电子邮件报告 – precc mail report 发送分析报告
  • GitHub Actions分析 – precc gha 用于调试失败的工作流
  • 上下文压缩 – precc compress 用于CLAUDE.md优化
  • 优先支持

激活许可证

$ precc license activate XXXX-XXXX-XXXX-XXXX --email you@example.com
[precc] License activated for you@example.com
[precc] Plan: Pro
[precc] Expires: 2027-04-03

检查许可证状态

$ precc license status
License: Pro
Email:   you@example.com
Expires: 2027-04-03
Status:  Active

GitHub Sponsors激活

如果您通过GitHub Sponsors赞助PRECC，您的许可证将通过您的GitHub邮箱自动激活。无需密钥——只需确保您的赞助者邮箱匹配：

$ precc license status
License: Pro (GitHub Sponsors)
Email:   you@example.com
Status:  Active (auto-renewed)

设备指纹

每个许可证都绑定到设备指纹。使用以下命令查看：

$ precc license fingerprint
Fingerprint: a1b2c3d4e5f6...

如果需要将许可证转移到新机器，请先停用：

precc license deactivate

然后在新机器上激活。

许可证过期？

当Pro许可证到期时，PRECC会恢复到Community层。所有内置技能和核心功能继续工作。只有Pro特有功能变为不可用。详情请参阅FAQ。

钩子管道

precc-hook 二进制文件是PRECC的核心。它位于Claude Code和shell之间，在5毫秒内处理每个bash命令。

Claude Code如何调用钩子

Claude Code支持PreToolUse钩子——可以在执行前检查和修改工具输入的外部程序。当Claude即将运行bash命令时，它通过stdin将JSON发送给 precc-hook 并从stdout读取响应。

管道阶段

Claude Code
    |
    v
+---------------------------+
| 1. Parse JSON stdin       |  Read the command from Claude Code
+---------------------------+
    |
    v
+---------------------------+
| 2. Skill matching         |  Query heuristics.db for matching skills (Pillar 4)
+---------------------------+
    |
    v
+---------------------------+
| 3. Directory correction   |  Resolve correct working directory (Pillar 1)
+---------------------------+
    |
    v
+---------------------------+
| 4. GDB check              |  Detect debug opportunities (Pillar 2)
+---------------------------+
    |
    v
+---------------------------+
| 5. RTK rewriting          |  Apply command rewrites for token savings
+---------------------------+
    |
    v
+---------------------------+
| 6. Emit JSON stdout       |  Return modified command to Claude Code
+---------------------------+
    |
    v
  Shell executes corrected command

示例：JSON输入和输出

输入（来自Claude Code）

{
  "tool_input": {
    "command": "cargo build"
  }
}

PRECC检测到当前目录没有 Cargo.toml，但 ./myapp/Cargo.toml 存在。

输出（到Claude Code）

{
  "hookSpecificOutput": {
    "updatedInput": {
      "command": "cd /home/user/projects/myapp && cargo build"
    }
  }
}

如果不需要修改，updatedInput.command 为空，Claude Code使用原始命令。

阶段详情

阶段1：解析JSON

从stdin读取完整的JSON对象。提取 tool_input.command。如果解析失败，钩子立即退出，Claude Code使用原始命令（fail-open设计）。

阶段2：技能匹配

查询SQLite启发式数据库，寻找触发模式与命令匹配的技能。技能按优先级顺序检查。内置TOML技能和挖掘的技能都会被评估。

阶段3：目录修正

对于构建命令（cargo、go、make、npm、python 等），检查预期的项目文件是否存在于当前目录中。如果不存在，扫描附近目录寻找最近匹配并添加 cd <dir> && 前缀。

目录扫描使用缓存的文件系统索引，TTL为5秒，以保持高速。

阶段4：GDB检查

如果命令可能产生崩溃（例如运行调试二进制文件），PRECC可以建议或注入GDB包装器来捕获结构化的调试输出，而不是原始崩溃日志。

阶段5：RTK重写

应用RTK（重写工具包）规则，缩短冗长命令、抑制嘈杂输出或重构命令以提高token效率。

阶段6：输出JSON

将修改后的命令序列化回JSON并写入stdout。如果没有更改，输出信号Claude Code使用原始命令。

性能

整个管道在5毫秒（p99）内完成。关键优化：

  • SQLite使用WAL模式实现无锁并发读取
  • 预编译的正则表达式模式用于技能匹配
  • 缓存的文件系统扫描（5秒TTL）
  • 热路径中无网络调用
  • Fail-open：任何错误都回退到原始命令

手动测试钩子

你可以直接调用钩子：

$ echo '{"tool_input":{"command":"cargo build"}}' | precc-hook
{"hookSpecificOutput":{"updatedInput":{"command":"cd /home/user/myapp && cargo build"}}}

技能

技能是PRECC用来检测和纠正命令的模式匹配规则。它们可以是内置的（作为TOML文件分发）或从会话日志中挖掘的。

内置技能

技能触发条件动作
cargo-wrong-dir在Rust项目外运行 cargo build/test/clippy在命令前添加 cd 到最近的 Cargo.toml 目录
git-wrong-dir在git仓库外运行 git *在命令前添加 cd 到最近的 .git 目录
go-wrong-dir在Go模块外运行 go build/test在命令前添加 cd 到最近的 go.mod 目录
make-wrong-dir当前目录没有Makefile时运行 make在命令前添加 cd 到最近的Makefile目录
npm-wrong-dir在Node项目外运行 npm/npx/pnpm/yarn在命令前添加 cd 到最近的 package.json 目录
python-wrong-dir在Python项目外运行 python/pytest/pip在命令前添加 cd 到最近的Python项目
jj-translate在jj共存仓库中运行 git *重写为等效的 jj 命令
asciinema-gifasciinema rec重写为 precc gif

列出技能

$ precc skills list
  # Name               Type      Triggers
  1 cargo-wrong-dir    built-in  cargo build/test/clippy outside Rust project
  2 git-wrong-dir      built-in  git * outside a repo
  3 go-wrong-dir       built-in  go build/test outside Go module
  4 make-wrong-dir     built-in  make without Makefile in cwd
  5 npm-wrong-dir      built-in  npm/npx/pnpm/yarn outside Node project
  6 python-wrong-dir   built-in  python/pytest/pip outside Python project
  7 jj-translate       built-in  git * in jj-colocated repo
  8 asciinema-gif      built-in  asciinema rec
  9 fix-pytest-path    mined     pytest with wrong test path

显示技能详情

$ precc skills show cargo-wrong-dir
Name:        cargo-wrong-dir
Type:        built-in
Source:      skills/builtin/cargo-wrong-dir.toml
Description: Detects cargo commands run outside a Rust project and prepends
             cd to the directory containing the nearest Cargo.toml.
Trigger:     ^cargo\s+(build|test|clippy|run|check|bench|doc)
Action:      prepend_cd
Marker:      Cargo.toml
Activations: 12

将技能导出为TOML

$ precc skills export cargo-wrong-dir
[skill]
name = "cargo-wrong-dir"
description = "Prepend cd for cargo commands outside a Rust project"
trigger = "^cargo\\s+(build|test|clippy|run|check|bench|doc)"
action = "prepend_cd"
marker = "Cargo.toml"
priority = 10

编辑技能

$ precc skills edit cargo-wrong-dir

这将在您的 $EDITOR 中打开技能定义。保存后，技能会自动重新加载。

Advise 命令

precc skills advise 分析您最近的会话，并根据重复模式建议新技能：

$ precc skills advise
Analyzed 47 commands from the last session.

Suggested skills:
  1. docker-wrong-dir: You ran `docker compose up` outside the project root 3 times.
     Suggested trigger: ^docker\s+compose
     Suggested marker: docker-compose.yml

  2. terraform-wrong-dir: You ran `terraform plan` outside the infra directory 2 times.
     Suggested trigger: ^terraform\s+(plan|apply|init)
     Suggested marker: main.tf

Accept suggestion [1/2/skip]?

聚类技能

$ precc skills cluster

将相似的挖掘技能分组，帮助识别冗余或重叠的模式。

挖掘技能与内置技能

内置技能随PRECC一起分发，定义在 skills/builtin/*.toml 中。它们涵盖了最常见的目录错误。

挖掘技能由 precc ingest 或 precc-learner 守护进程从您的会话日志创建。它们存储在 ~/.local/share/precc/heuristics.db 中，特定于您的工作流程。详情请参阅挖掘。

节省

PRECC追踪每次拦截的估计token节省。使用 precc savings 查看PRECC阻止了多少浪费。

快速摘要

$ precc savings
Session Token Savings
=====================
Total estimated savings: <span data-stat="session_tokens_saved">8,741</span> tokens

Breakdown:
  Pillar 1 (cd prepends):         <span data-stat="session_p1_tokens">3,204</span> tokens  (<span data-stat="session_p1_count">6</span> corrections)
  Pillar 4 (skill activations):   <span data-stat="session_p4_tokens">1,560</span> tokens  (<span data-stat="session_p4_count">4</span> activations)
  RTK rewrites:                   <span data-stat="session_rtk_tokens">2,749</span> tokens  (<span data-stat="session_rtk_count">11</span> rewrites)
  Lean-ctx wraps:                 <span data-stat="session_lean_tokens">1,228</span> tokens  (<span data-stat="session_lean_count">2</span> wraps)

详细分类（Pro）

$ precc savings --all
Session Token Savings (Detailed)
================================
Total estimated savings: <span data-stat="session_tokens_saved">8,741</span> tokens

Command-by-command:
  #  Time   Command                          Saving   Source
  1  09:12  cargo build                      534 tk   cd prepend (cargo-wrong-dir)
  2  09:14  cargo test                       534 tk   cd prepend (cargo-wrong-dir)
  3  09:15  git status                       412 tk   cd prepend (git-wrong-dir)
  4  09:18  npm install                      824 tk   cd prepend (npm-wrong-dir)
  5  09:22  find . -name "*.rs"              387 tk   RTK rewrite (output truncation)
  6  09:25  cat src/main.rs                  249 tk   RTK rewrite (lean-ctx wrap)
  7  09:31  cargo clippy                     534 tk   cd prepend (cargo-wrong-dir)
  ...

Pillar Breakdown:
  Pillar 1 (context resolution):   <span data-stat="session_p1_tokens">3,204</span> tokens  <span data-stat="session_p1_pct">36.6</span>%
  Pillar 2 (GDB debugging):            0 tokens   0.0%
  Pillar 3 (mined preventions):        0 tokens   0.0%
  Pillar 4 (automation skills):    <span data-stat="session_p4_tokens">1,560</span> tokens  <span data-stat="session_p4_pct">17.8</span>%
  RTK rewrites:                    <span data-stat="session_rtk_tokens">2,749</span> tokens  <span data-stat="session_rtk_pct">31.5</span>%
  Lean-ctx wraps:                  <span data-stat="session_lean_tokens">1,228</span> tokens  <span data-stat="session_lean_pct">14.1</span>%

如何估算节省

每种修正类型都有基于没有PRECC时会发生什么的估计token成本：

修正类型估计节省原因
cd prepend~500 tokens错误输出 + Claude推理 + 重试
技能激活~400 tokens错误输出 + Claude推理 + 重试
RTK rewrite~250 tokensClaude需要阅读的冗长输出
Lean-ctx wrap~600 tokens大文件内容被压缩
挖掘预防~500 tokens已知的失败模式被避免

这些是保守估计。实际节省通常更高，因为Claude对错误的推理可能很冗长。

累计节省

节省数据在PRECC数据库中跨会话持久化。随着时间推移，您可以跟踪总体影响：

$ precc savings
Session Token Savings
=====================
Total estimated savings: <span data-stat="session_tokens_saved">8,741</span> tokens

Lifetime savings: <span data-stat="total_tokens_saved">142,389</span> tokens across <span data-stat="total_sessions">47</span> sessions

压缩

precc compress 缩小 CLAUDE.md 和其他上下文文件，以减少 Claude Code 加载时的 token 使用量。这是 Pro 功能。

基本用法

$ precc compress .
[precc] Scanning directory: .
[precc] Found 3 context files:
         CLAUDE.md (2,847 tokens -> 1,203 tokens, -57.7%)
         ARCHITECTURE.md (4,112 tokens -> 2,044 tokens, -50.3%)
         ALTERNATIVES.md (3,891 tokens -> 1,967 tokens, -49.5%)
[precc] Total: 10,850 tokens -> 5,214 tokens (-51.9%)
[precc] Files compressed. Use --revert to restore originals.

试运行

预览将要更改的内容而不修改文件：

$ precc compress . --dry-run
[precc] Dry run -- no files will be modified.
[precc] CLAUDE.md: 2,847 tokens -> 1,203 tokens (-57.7%)
[precc] ARCHITECTURE.md: 4,112 tokens -> 2,044 tokens (-50.3%)
[precc] ALTERNATIVES.md: 3,891 tokens -> 1,967 tokens (-49.5%)
[precc] Total: 10,850 tokens -> 5,214 tokens (-51.9%)

还原

原始文件会自动备份。要恢复它们：

$ precc compress --revert
[precc] Restored 3 files from backups.

压缩了什么

压缩器应用多种转换：

  • 删除冗余空白和空行
  • 缩短冗长的措辞同时保留含义
  • 压缩表格和列表
  • 去除注释和装饰性格式
  • 保留所有代码块、路径和技术标识符

压缩后的输出仍然是人类可读的——它不是压缩化或混淆的。

针对特定文件

$ precc compress CLAUDE.md
[precc] CLAUDE.md: 2,847 tokens -> 1,203 tokens (-57.7%)

报告

precc report 生成一个分析仪表板，总结 PRECC 活动和 token 节省情况。

生成报告

$ precc report
PRECC Report -- 2026-04-03
==========================

Sessions analyzed: 12
Commands intercepted: 87
Total token savings: 42,389

Top skills by activation:
  1. cargo-wrong-dir     34 activations   17,204 tokens saved
  2. npm-wrong-dir       18 activations    9,360 tokens saved
  3. git-wrong-dir       12 activations    4,944 tokens saved
  4. RTK rewrite         15 activations    3,750 tokens saved
  5. python-wrong-dir     8 activations    4,131 tokens saved

Savings by pillar:
  Pillar 1 (context resolution):  28,639 tokens  67.6%
  Pillar 4 (automation skills):    7,000 tokens  16.5%
  RTK rewrites:                    3,750 tokens   8.8%
  Lean-ctx wraps:                  3,000 tokens   7.1%

Recent corrections:
  2026-04-03 09:12  cargo build -> cd myapp && cargo build
  2026-04-03 09:18  npm test -> cd frontend && npm test
  2026-04-03 10:05  git status -> cd repo && git status
  ...

通过电子邮件发送报告

将报告发送到电子邮件地址（需要邮件设置，见 Email）：

$ precc report --email
[precc] Report sent to you@example.com

收件人地址从 ~/.config/precc/mail.toml 读取。您也可以使用 precc mail report EMAIL 发送到特定地址。

报告数据

报告从本地 PRECC 数据库 ~/.local/share/precc/history.db 生成。除非您明确通过电子邮件发送报告，否则没有数据离开您的机器。

挖掘

PRECC挖掘Claude Code会话日志以学习失败-修复模式。当它再次看到同样的错误时，会自动应用修复。

导入会话日志

导入单个文件

$ precc ingest ~/.claude/logs/session-2026-04-03.jsonl
[precc] Parsing session-2026-04-03.jsonl...
[precc] Found 142 commands, 8 failure-fix pairs
[precc] Stored 8 patterns in history.db
[precc] 2 new skill candidates identified

导入所有日志

$ precc ingest --all
[precc] Scanning ~/.claude/logs/...
[precc] Found 23 session files (14 new, 9 already ingested)
[precc] Parsing 14 new files...
[precc] Found 47 failure-fix pairs across 14 sessions
[precc] Stored 47 patterns in history.db
[precc] 5 new skill candidates identified

强制重新导入

要重新处理已导入的文件：

$ precc ingest --all --force
[precc] Re-ingesting all 23 session files...

挖掘的工作原理

  1. PRECC读取会话JSONL日志文件。
  2. 它识别命令对，其中第一个命令失败，第二个是纠正后的重试。
  3. 它提取模式（出了什么问题）和修复（Claude做了什么不同的事）。
  4. 模式存储在 ~/.local/share/precc/history.db 中。
  5. 当模式达到置信阈值（多次出现）时，它成为 heuristics.db 中的挖掘技能。

示例模式

Failure: pytest tests/test_auth.py
Error:   ModuleNotFoundError: No module named 'myapp'
Fix:     cd /home/user/myapp && pytest tests/test_auth.py
Pattern: pytest outside project root -> prepend cd

precc-learner 守护进程

precc-learner 守护进程在后台运行，自动监视新的会话日志：

$ precc-learner &
[precc-learner] Watching ~/.claude/logs/ for new sessions...
[precc-learner] Processing session-2026-04-03-1412.jsonl... 3 new patterns

守护进程使用文件系统通知（Linux上的inotify，macOS上的FSEvents），因此在会话结束时立即做出反应。

从模式到技能

挖掘的模式在满足以下条件时升级为技能：

  • 跨会话至少出现3次
  • 一致的修复模式（每次相同类型的纠正）
  • 未检测到误报

您可以通过以下方式查看技能候选：

$ precc skills advise

有关管理技能的详细信息，请参见 Skills。

数据存储

  • 失败-修复对: ~/.local/share/precc/history.db
  • 升级的技能: ~/.local/share/precc/heuristics.db

两者都是WAL模式的SQLite数据库，用于安全的并发访问。

电子邮件

PRECC可以通过电子邮件发送报告和文件。这需要一次性的SMTP设置。

设置

$ precc mail setup
SMTP host: smtp.gmail.com
SMTP port [587]: 587
Username: you@gmail.com
Password: ********
From address [you@gmail.com]: you@gmail.com
[precc] Mail configuration saved to ~/.config/precc/mail.toml
[precc] Sending test email to you@gmail.com...
[precc] Test email sent successfully.

配置文件

配置存储在 ~/.config/precc/mail.toml：

[smtp]
host = "smtp.gmail.com"
port = 587
username = "you@gmail.com"
password = "app-password-here"
from = "you@gmail.com"
tls = true

您可以直接编辑此文件：

$EDITOR ~/.config/precc/mail.toml

对于Gmail，请使用应用密码而不是您的账户密码。

发送报告

$ precc mail report team@example.com
[precc] Generating report...
[precc] Sending to team@example.com...
[precc] Report sent.

发送文件

$ precc mail send colleague@example.com output.log
[precc] Sending output.log to colleague@example.com...
[precc] Sent (14.2 KB).

SSH中继支持

如果您的机器无法直接访问SMTP服务器（例如，在企业防火墙后面），PRECC支持通过SSH隧道中继：

[smtp]
host = "localhost"
port = 2525

[ssh_relay]
host = "relay.example.com"
user = "you"
remote_port = 587
local_port = 2525

PRECC将在发送前自动建立SSH隧道。

GIF录制

precc gif 从bash脚本创建终端会话的动画GIF录制。这是Pro功能。

基本用法

$ precc gif script.sh 30s
[precc] Recording script.sh (max 30s)...
[precc] Running: echo "Hello, world!"
[precc] Running: cargo build --release
[precc] Running: cargo test
[precc] Recording complete.
[precc] Output: script.gif (1.2 MB, 24s)

第一个参数是包含要运行的命令的bash脚本。第二个参数是最大录制时长。

脚本格式

脚本是标准的bash文件：

#!/bin/bash
echo "Building project..."
cargo build --release
echo "Running tests..."
cargo test
echo "Done!"

输入模拟

对于交互式命令，提供输入值作为额外参数：

$ precc gif interactive-demo.sh 60s "yes" "my-project" "3"

每个额外参数在脚本提示输入时作为一行stdin输入。

输出选项

输出文件默认以脚本命名（script.gif）。GIF使用深色终端主题，标准80x24尺寸。

为什么使用GIF而不是asciinema？

内置技能 asciinema-gif 自动将 asciinema rec 重写为 precc gif。GIF文件更具可移植性——它们可以在GitHub README、Slack和电子邮件中内联显示，无需播放器。

GitHub Actions 分析

precc gha 分析失败的GitHub Actions运行并建议修复方案。这是Pro功能。

用法

传入失败的GitHub Actions运行的URL：

$ precc gha https://github.com/myorg/myrepo/actions/runs/12345678
[precc] Fetching run 12345678...
[precc] Run: CI / build (ubuntu-latest)
[precc] Status: failure
[precc] Failed step: Run cargo test

[precc] Log analysis:
  Error: test result: FAILED. 2 passed; 1 failed
  Failed test: tests::integration::test_database_connection
  Cause: thread 'tests::integration::test_database_connection' panicked at
         'called Result::unwrap() on an Err value: Connection refused'

[precc] Suggested fix:
  The test requires a database connection but the CI environment does not
  start a database service. Add a services block to your workflow:

    services:
      postgres:
        image: postgres:15
        ports:
          - 5432:5432
        env:
          POSTGRES_PASSWORD: test

功能说明

  1. 解析GitHub Actions运行URL以提取所有者、仓库和运行ID。
  2. 通过GitHub API获取运行日志（如果设置了 GITHUB_TOKEN 则使用，否则公开访问）。
  3. 识别失败步骤并提取相关错误行。
  4. 分析错误并根据常见CI失败模式建议修复方案。

支持的失败模式

  • 缺少服务容器（数据库、Redis等）
  • 运行器OS或架构不正确
  • 缺少环境变量或密钥
  • 依赖安装失败
  • 测试超时
  • 权限错误
  • 缓存未命中导致构建缓慢

地理围栏

PRECC包含用于受监管环境的IP地理围栏合规性检查。这是Pro功能。

概述

一些组织要求开发工具仅在批准的地理区域内运行。PRECC的地理围栏功能验证当前机器的IP地址是否在允许的区域列表中。

检查合规性

$ precc geofence check
[precc] Current IP: 203.0.113.42
[precc] Region: US-East (Virginia)
[precc] Status: COMPLIANT
[precc] Policy: us-east-1, us-west-2, eu-west-1

如果机器在允许的区域之外：

$ precc geofence check
[precc] Current IP: 198.51.100.7
[precc] Region: AP-Southeast (Singapore)
[precc] Status: NON-COMPLIANT
[precc] Policy: us-east-1, us-west-2, eu-west-1
[precc] Warning: Current region is not in the allowed list.

刷新地理围栏数据

$ precc geofence refresh
[precc] Fetching updated IP geolocation data...
[precc] Updated. Cache expires in 24h.

查看地理围栏信息

$ precc geofence info
Geofence Configuration
======================
Policy file:    ~/.config/precc/geofence.toml
Allowed regions: us-east-1, us-west-2, eu-west-1
Cache age:      2h 14m
Last check:     2026-04-03 09:12:00 UTC
Status:         COMPLIANT

清除缓存

$ precc geofence clear
[precc] Geofence cache cleared.

配置

地理围栏策略在 ~/.config/precc/geofence.toml 中定义：

[geofence]
allowed_regions = ["us-east-1", "us-west-2", "eu-west-1"]
check_on_init = true
block_on_violation = false

设置 block_on_violation = true 以阻止PRECC在允许区域外运行。

遥测

PRECC支持可选的匿名遥测以帮助改进工具。除非您明确同意，否则不会收集任何数据。

选择加入

$ precc telemetry consent
[precc] Telemetry enabled. Thank you for helping improve PRECC.
[precc] You can revoke consent at any time with: precc telemetry revoke

选择退出

$ precc telemetry revoke
[precc] Telemetry disabled. No further data will be sent.

检查状态

$ precc telemetry status
Telemetry: disabled
Last sent: never

预览将发送的数据

在选择加入之前，您可以查看将收集的确切数据：

$ precc telemetry preview
Telemetry payload (this session):
{
  "version": "0.3.0",
  "os": "linux",
  "arch": "x86_64",
  "skills_activated": 12,
  "commands_intercepted": 87,
  "pillars_used": [1, 4],
  "avg_hook_latency_ms": 2.3,
  "session_count": 1
}

收集的数据

  • PRECC版本、操作系统和架构
  • 汇总计数：拦截的命令、激活的技能、使用的支柱
  • 平均钩子延迟
  • 会话数

不收集的数据

  • 不收集命令文本或参数
  • 不收集文件路径或目录名
  • 不收集项目名称或仓库URL
  • 不收集个人身份信息（PII）
  • 不收集IP地址（服务器不记录它们）

环境变量覆盖

无需运行命令即可禁用遥测（适用于CI或共享环境）：

export PRECC_NO_TELEMETRY=1

这优先于同意设置。

数据目的地

遥测数据通过HTTPS发送到 https://telemetry.peria.ai/v1/precc。数据仅用于了解使用模式和确定开发优先级。

命令参考

所有PRECC命令的完整参考。

precc init

初始化PRECC并向Claude Code注册钩子。

precc init

Options:
  (none)

Effects:
  - Registers PreToolUse:Bash hook with Claude Code
  - Creates ~/.local/share/precc/ data directory
  - Initializes heuristics.db with built-in skills
  - Prompts for telemetry consent

precc ingest

挖掘会话日志中的失败-修复模式。

precc ingest [FILE] [--all] [--force]

Arguments:
  FILE            Path to a session log file (.jsonl)

Options:
  --all           Ingest all session logs from ~/.claude/logs/
  --force         Re-process files that were already ingested

Examples:
  precc ingest session.jsonl
  precc ingest --all
  precc ingest --all --force

precc skills

管理自动化技能。

precc skills list

precc skills list

List all active skills (built-in and mined).

precc skills show

precc skills show NAME

Show detailed information about a specific skill.

Arguments:
  NAME            Skill name (e.g., cargo-wrong-dir)

precc skills export

precc skills export NAME

Export a skill definition as TOML.

Arguments:
  NAME            Skill name

precc skills edit

precc skills edit NAME

Open a skill definition in $EDITOR.

Arguments:
  NAME            Skill name

precc skills advise

precc skills advise

Analyze recent sessions and suggest new skills based on repeated patterns.

precc skills cluster

precc skills cluster

Group similar mined skills to identify redundant or overlapping patterns.

precc report

生成分析报告。

precc report [--email]

Options:
  --email         Send the report via email (requires mail setup)

precc savings

显示token节省。

precc savings [--all]

Options:
  --all           Show detailed per-command breakdown (Pro)

precc compress

压缩上下文文件以减少token使用。

precc compress [DIR] [--dry-run] [--revert]

Arguments:
  DIR             Directory or file to compress (default: current directory)

Options:
  --dry-run       Preview changes without modifying files
  --revert        Restore files from backup

precc license

管理您的PRECC许可证。

precc license activate

precc license activate KEY --email EMAIL

Arguments:
  KEY             License key (XXXX-XXXX-XXXX-XXXX)

Options:
  --email EMAIL   Email address associated with the license

precc license status

precc license status

Display current license status, plan, and expiration.

precc license deactivate

precc license deactivate

Deactivate the license on this machine.

precc license fingerprint

precc license fingerprint

Display the device fingerprint for this machine.

precc mail

电子邮件功能。

precc mail setup

precc mail setup

Interactive SMTP configuration. Saves to ~/.config/precc/mail.toml.

precc mail report

precc mail report EMAIL

Send a PRECC analytics report to the specified email address.

Arguments:
  EMAIL           Recipient email address

precc mail send

precc mail send EMAIL FILE

Send a file as an email attachment.

Arguments:
  EMAIL           Recipient email address
  FILE            Path to the file to send

precc update

将PRECC更新到最新版本。

precc update [--force] [--version VERSION] [--auto]

Options:
  --force             Force update even if already on latest
  --version VERSION   Update to a specific version
  --auto              Enable automatic updates

precc telemetry

管理匿名遥测。

precc telemetry consent

Opt in to anonymous telemetry.

precc telemetry revoke

precc telemetry revoke

Opt out of telemetry. No further data will be sent.

precc telemetry status

precc telemetry status

Show current telemetry consent status.

precc telemetry preview

precc telemetry preview

Display the telemetry payload that would be sent (without sending it).

precc geofence

IP地理围栏合规（Pro）。

precc geofence check

precc geofence check

Check if the current machine is in an allowed region.

precc geofence refresh

precc geofence refresh

Refresh the IP geolocation cache.

precc geofence clear

precc geofence clear

Clear the geofence cache.

precc geofence info

precc geofence info

Display geofence configuration and current status.

precc gif

从bash脚本录制动画GIF（Pro）。

precc gif SCRIPT LENGTH [INPUTS...]

Arguments:
  SCRIPT          Path to a bash script
  LENGTH          Maximum recording duration (e.g., 30s, 2m)
  INPUTS...       Optional input lines for interactive prompts

Examples:
  precc gif demo.sh 30s
  precc gif interactive.sh 60s "yes" "my-project"

precc gha

分析失败的GitHub Actions运行（Pro）。

precc gha URL

Arguments:
  URL             GitHub Actions run URL

Example:
  precc gha https://github.com/org/repo/actions/runs/12345678

precc cache-hint

显示当前项目的缓存提示信息。

precc cache-hint

precc trial

开始Pro试用。

precc trial EMAIL

Arguments:
  EMAIL           Email address for the trial

precc nushell

启动带有PRECC集成的Nushell会话。

precc nushell

常见问题

PRECC安全吗？

是的。PRECC使用Claude Code官方的PreToolUse钩子机制——Anthropic专门为此目的设计的扩展点。该钩子：

  • 完全离线运行（热路径中无网络调用）
  • 在5毫秒内完成
  • 是fail-open的：如果出现任何问题，原始命令将不受修改地运行
  • 只修改命令，从不自己执行它们
  • 将数据存储在本地SQLite数据库中

PRECC能与其他AI编码工具一起使用吗？

PRECC专为Claude Code设计。它依赖于Claude Code提供的PreToolUse钩子协议。它不适用于Cursor、Copilot、Windsurf或其他AI编码工具。

遥测发送什么数据？

遥测仅在选择加入后启用。启用后发送：

  • PRECC版本、操作系统和架构
  • 汇总计数（拦截的命令、激活的技能）
  • 平均钩子延迟

它不发送命令文本、文件路径、项目名称或任何个人身份信息。您可以在选择加入前使用 precc telemetry preview 预览确切的数据。详见遥测。

如何卸载PRECC？

??faq_uninstall_a_intro??

  1. 移除钩子注册：

    # Delete the hook entry from Claude Code's settings
# (precc init added it; removing it disables PRECC)

  2. 删除二进制文件：

    rm ~/.local/bin/precc ~/.local/bin/precc-hook ~/.local/bin/precc-learner

  3. 删除数据（可选）：

    rm -rf ~/.local/share/precc/
rm -rf ~/.config/precc/

我的许可证过期了。会发生什么？

PRECC恢复到社区版。所有核心功能继续正常工作：

  • 内置技能保持活跃
  • 钩子管道正常运行
  • precc savings 显示摘要视图
  • precc ingest 和会话挖掘正常工作

Pro功能在续订前不可用：

  • precc savings --all（详细分类）
  • precc compress
  • precc gif
  • precc gha
  • precc geofence
  • 电子邮件报告

钩子似乎没有运行。如何调试？

??faq_debug_a_intro??

  1. 检查钩子是否已注册：

    precc init

  2. 手动测试钩子：

    echo '{"tool_input":{"command":"cargo build"}}' | precc-hook

  3. 检查二进制文件是否在PATH中：

    which precc-hook

  4. 检查 ~/.claude/settings.json 中的Claude Code钩子配置。

PRECC会减慢Claude Code吗？

不会。钩子在5毫秒内完成（p99）。与Claude推理和生成回复所花费的时间相比，这是不可察觉的。

我可以在CI/CD中使用PRECC吗？

PRECC是为交互式Claude Code会话设计的。在CI/CD中，没有Claude Code实例可以挂钩。但是，precc gha 可以从任何环境分析失败的GitHub Actions运行。

挖掘的技能与内置技能有何不同？

内置技能随PRECC提供，涵盖常见的错误目录模式。挖掘的技能从您的特定会话日志中学习——它们捕获您工作流程中独特的模式。两者都存储在SQLite中，并由钩子管道以相同方式评估。

我可以与团队共享技能吗？

可以。使用 precc skills export NAME 将任何技能导出为TOML并共享文件。团队成员可以将其放在 skills/ 目录中或导入到他们的启发式数据库中。

其他语言