上下文审计 (Context Audit)
采用此约定的仓库会保留一小部分持久文件，这样代理就不必在每个会话中重新推导相同的内容：项目的约定（AGENTS.md）、已经决定的事项及其原因（memory.md）、以及代码库的大致组织方式（.agent/graph.md）。本技能会检查这些文件是否存在且是最新的，在你依赖它们之前，或者在你回退到手动扫描仓库之前。
触发短语
会话开始 / 信任检查
- "让我快速了解这个仓库"
- "关于这个项目你知道什么"
- "我应该信任 AGENTS.md / memory.md 吗"
- "上下文文件是最新的吗"
- "检查上下文" / "上下文审计"
过时
- "AGENTS.md 过时了吗" / "memory.md 过时了吗"
- "上次同步之后有多少次提交"
- "我的代理文件是最新的吗"
- "检查上下文是否过时"
代币成本
- "上下文文件能节省多少代币"
- "代币节省" / "上下文成本"
- "基准测试代币节省"
- "基准代币对比精选代币"
设置 / 上手
- "搭建 AGENTS.md" / "初始化上下文"
- "安装 ctx-audit" / "配置上下文钩子"
- "设置 AI 上下文" / "这个项目支持 AI 吗"
CI / 自动化
- "将 ctx-audit 加入 CI"
- "添加预推送钩子"
- "在 CI 中强制上下文文件保持最新"
架构
- "我有架构图吗"
- "生成 graph.md" / "运行 graphify"
如何运行
运行 ctx-audit 的推荐方式：
npx ctx-audit
或者，如果已作为技能安装：
node <path-to-this-skill-folder>/../scripts/audit.mjs
标志：
--json— 机器可读的输出（如果你要以编程方式处理结果，请使用此选项）。--strict— 如果任何文件缺失或过时，退出码为 1。--ci—--strict --json的别名。--help— 显示用法并退出。
子命令
# 搭建 AGENTS.md + memory.md（交互式——直接写入仓库根目录的文件）
npx ctx-audit init
# 一键安装：将技能复制到 ~/.claude/skills/，并在 CLAUDE.md 中注册
npx ctx-audit install
# Git 钩子：每次推送时以 --strict 模式运行审计
npx ctx-audit hook install
npx ctx-audit hook status
npx ctx-audit hook uninstall
# 项目的 CLAUDE.md：为代理添加指令块
npx ctx-audit claude install
npx ctx-audit claude uninstall
# 代币节省报告（集中、可共享的格式）
npx ctx-audit benchmark
代理决策表
| 状态 | 含义 | 操作 |
|---|---|---|
| FRESH | 自上次同步以来的提交次数少于过时阈值的一半 | 信任该文件——读取它而不是扫描原始源码 |
| STALE? | 接近阈值（可能过时） | 适度谨慎——在依赖关键声明之前进行抽查 |
| STALE! | 超过阈值，视为失败 | 将声明视为未经验证；对照实际代码进行抽查；会话后更新 |
| STALE | 严重落后，视为失败 | 与 STALE! 相同，但更紧急；会话后立即更新 |
| MISSING（必需） | 文件不存在 | 运行 npx ctx-audit init；不要假定约定已到位而继续 |
| absent（可选） | 可选文件不存在 | 可以接受；考虑运行 /graphify 生成 graph.md |
| over budget | 代币数量超过 maxTokens | 文件过于臃肿——需要精简；读取它可能得不偿失 |
| dead reference | 文件中反引号路径或 dir/file.ext 在磁盘上不存在 | 更新引用；文件引用了过时的结构 |
| SHA bumped | last_synced_commit 已更新但内容未变 | 验证文件是否真正反映了最近的更改；可能只是机械性地更新了哈希值 |
结果解读
- MISSING（必需文件）：不要假定约定已到位而继续。建议搭建一个起始文件（运行
npx ctx-audit init），而不是在没有文件的情况下工作，或默默采用旧的“手动探索一切”的方式。 - FRESH：文件是最新的。读取它而不是扫描原始源码。
- STALE?（可能过时）：接近阈值。抽查关键声明。
- STALE!（很可能过时）：将其声明视为未经验证。对照实际代码抽查任何关键部分，在会话结束后更新文件及其
last_synced_commit。 - STALE：严重落后。处理方式与 STALE! 相同，但更紧急。
- 代币计数是一个约 3.5 字符/代币的启发式方法——方向上可用，但不精确。如果某个文件被标记为“over budget”，说明它变得臃肿，读取它所花费的代价开始超过它能节省的代价；建议进行精简。
- dead reference 警告：上下文文件中提到的路径在磁盘上已不存在。表明文件引用了过时的结构。
工作示例
会话开始时进行基本审计：
npx ctx-audit
CI 门控（如果上下文过时则构建失败）：
# .github/workflows/ctx-audit.yml
- name: 审计上下文新鲜度
run: npx ctx-audit --strict
供程序化使用的 JSON 输出：
npx ctx-audit --json | jq '.checks[] | {file, stalenessLevel, stale}'
一键上手：
npx ctx-audit install # 复制技能，在 CLAUDE.md 中注册
npx ctx-audit hook install # 添加预推送保护
npx ctx-audit claude install # 在项目 CLAUDE.md 中添加说明
npx ctx-audit init # 搭建 AGENTS.md + memory.md
仅检查特定子系统的过时状态（通过 frontmatter）：
---
last_synced_commit: abc1234
watches: src/auth/**, src/api/**
---
只有触及 src/auth/ 或 src/api/ 的提交才会计入该文件的过时状态。
基准测试代币节省：
npx ctx-audit benchmark
配置
在仓库根目录放置 .ctx-audit.json 以自定义行为：
{
"files": [{ "id": "...", "file": "...", "label": "...", "maxTokens": N, "required": true }],
"sourceDirs": ["src", "packages/core"],
"staleThreshold": 10,
"baselineFileCap": 300
}
Frontmatter
每个上下文文件应以 frontmatter 开头：
---
last_synced_commit: <git sha>
watches: src/auth/**, src/api/**
---
watches 字段（可选）将过时检查范围限制为仅触及这些路径的提交，而不是所有源目录。
如果必需文件缺失——进行搭建
运行 npx ctx-audit init 以生成模板。在 TTY 中，它会直接将文件写入仓库根目录；当通过管道传输时，它会将内容打印到 stdout 以供重定向。旧的 --init 标志仍然支持，作为向后兼容的别名。
AGENTS.md — 稳定的项目约定：构建/测试/检查命令、文件布局规则、代理绝对不能做的事情。应该很少更改。
memory.md — 运行时的决策日志，不是当前代码的复述。每个条目：尝试了什么、决定了什么、为什么决定、以及在情况变化时应该重新考虑什么。追加，不要重写历史。
.agent/graph.md（可选，但在仓库增长后推荐）— 每个主要模块用一段描述其职责和与之通信的其他模块。不是文件内容，也不是详尽的树状结构——只要足够让代理能够导航，而无需重新读取所有内容。 提示：运行 /graphify 可以根据代码库自动生成此文件，而不是手动编写。
在搭建或更新上述任何文件后，将其 last_synced_commit 更新为当前的 HEAD，这样下次审计就不会立即将其标记为过时。