内容
# Claude 智能层
> Claude 代码的高效上下文运行时
[](https://www.npmjs.com/package/@hautc.it/cil)
[](https://github.com/HauTC2415/cil/actions/workflows/ci.yml)
[](LICENSE)
[](https://nodejs.org)
Claude 智能层（CIL）为 Claude 代码提供**持久内存**、**自动输出压缩**和**结构化工作流**，确保上下文在会话间存活，令 token 使用量可预测。灵感来自 [context-mode](https://github.com/mksglu/context-mode)、[pro-workflow](https://github.com/rohitg00/pro-workflow)、[caveman](https://github.com/JuliusBrussee/caveman)、[RTK](https://github.com/rtk-ai/rtk) 和 [Andrej Karpathy Skills](https://github.com/forrestchang/andrej-karpathy-skills)。
---
## 安装
```bash
npm install -g @hautc.it/cil
```
> **要求：** Node.js >= 20 · [Claude 代码](https://claude.ai/code)
> **注意：** MCP 内存服务器使用 `better-sqlite3`（原生插件）。已为 Windows x64、macOS 和 Linux x64 包含预构建二进制文件。如果您的平台不受支持，`npm install` 将尝试从源代码编译 — 需要 Python 和 C++ 编译器。
---
## 快速开始
```bash
# 1. 全局安装
npm install -g @hautc.it/cil
# 2. 在您的项目中初始化
cd my-project
cil init
# 3. 验证一切正常
cil doctor
# 4. 打开 Claude 代码
claude
# 5. 在 Claude 代码中使用斜杠命令
/develop implement OAuth2 login
/review
/commit
/wrap-up
```
---
## `cil init` 安装的内容
| 内容 | 位置 | 目的 |
|---|---|---|
| `CLAUDE.md` | `./CLAUDE.md` | 工程原则，由 Claude 代码自动加载 |
| 斜杠命令 | `./.claude/commands/` | `/spec` `/develop` `/test` `/review` `/commit` `/wrap-up` `/learn` `/retrieve` `/auto-setup` `/handoff` `/onboard` |
| 技能 | `./.claude/skills/<name>/SKILL.md` | 调试、测试、架构、性能、API 设计、数据库迁移、安全设计、数据库设计 — 由 Claude 代码通过 frontmatter 自动加载 |
| 代理 | `./.claude/agents/<name>.md` | 研究者、规划者、实施者、评审者 — 由 Claude 代码的代理工具通过 frontmatter 自动路由 |
| 钩子 | `./.claude/settings.json` | PreToolUse、PostToolUse、PreCompact、Stop、UserPromptSubmit |
| MCP 服务器 | `~/.claude.json`（用户范围） | Claude 的持久内存工具 |
| 内存数据库 | `~/.cil/memory.db` | SQLite FTS5 — 跨所有项目共享 |
对于全局斜杠命令（在每个项目中无需重新运行 `cil init` 即可使用）：
```bash
cil init --global
```
**标志：**
- `--global` — 将斜杠命令安装到 `~/.claude/commands/`（跨所有项目可用）
- `--skip-mcp` — 跳过 MCP 服务器注册（手动注册或在 CI 中使用时有用）
- `--skip-hooks` — 跳过将钩子配置写入 `.claude/settings.json`
---
## 斜杠命令
### `/spec <feature>`
BA 帽 — 在实施前捕获可测试的验收标准（Given/When/Then）。范围明确界定；显式呈现模糊性；规范持续到内存中，以便 `/develop` 和 `/test` 可以引用它。
```
/spec password reset via email link
```
### `/develop <task>`
结构化开发周期：研究 → 可行性评分 → 计划 → 实现 → 验证。
- 在开始前搜索内存 — 不重复推导已知上下文
- **重放固定规则** 来自标记为 `feedback` 的记忆（之前会话的纠正）
- 在编写任何代码之前评估五个维度的可行性
- 在实施前等待批准
- 每 5 次编辑记录一次
```
/develop implement user authentication with JWT
```
### `/test <file or fn>`
TDD 助手 — 生成遵循 `testing` 技能协议的测试脚手架（边界 → 愉快 → 边缘 → 错误）。从 `package.json` 自动检测框架（vitest/jest/pytest/go test）并匹配现有测试布局。
```
/test src/lib/auth.ts
/test verifyToken
```
### `/review`
系统化检查清单：正确性、回归、安全（注入、暴露的秘密）、性能（N+1、阻塞 I/O）、样式。
### `/commit`
生成约定提交消息（`feat:`、`fix:`、`refactor:`...）。在暂存前检查敏感文件。
### `/wrap-up`
会话结束协议。将决策、学习和约束保存到持久内存中。为连续性创建会话快照，以便在下一会话中使用。
### `/learn <insight>`
存储洞察并附带类别（`decision`/`constraint`/`learning`/`task`/`architecture`）**和主题标签** 来自固定分类法（`navigation`/`editing`/`testing`/`git`/`quality`/`context`/`architecture`/`performance`/`claude-code`/`prompting`/`debugging`）— 以便未来的 `/retrieve` 查询可以按主题筛选。
```
/learn JWT refresh tokens need a separate DB table — access token is stateless
```
### `/retrieve <query>`
跨会话的所有存储记忆的全文搜索。
```
/retrieve auth decisions
/retrieve database schema constraints
```
### `/auto-setup`
检查项目根目录的 `package.json` / `pyproject.toml` / `Cargo.toml` / `go.mod` / `pom.xml`，从实际存在的脚本中识别 lint/typecheck/test 命令，并建议将其添加到 `CLAUDE.md` 和 `.claude/settings.json` 中。**在明确批准之前不应用任何更改** — 纯粹是诊断 + 差异预览。
```
/auto-setup
```
### `/handoff`
快速会话交接 — 生成一个可以直接粘贴的 resume 命令，用于下一个会话。在上下文填充完毕且您希望在 `/compact` 之前保存状态时使用。比 `/wrap-up` 更轻量（无完整审计检查清单）；以输出为中心。
```
/handoff
```
### `/onboard`
在对不熟悉的项目进行更改之前进行结构化的代码库定位。映射入口点、约定、最近的 git 活动，并检索有关该项目的先前内存。在您之前未触摸过的任何仓库（或长时间未触摸）上运行此命令。
```
/onboard
```
---
## 代理
由 `cil init` 安装到 `.claude/agents/`，由 Claude 代码的代理工具通过 frontmatter 自动路由：
| 代理 | 使用场景 |
|---|---|
| `researcher` | 修改前映射现有代码、调用图、之前决策 |
| `planner` | 将功能分解为有序的子任务，附带受影响的文件 + 风险 |
| `implementer` | 执行明确规定的子任务，无需架构决策 |
| `reviewer` | 审核差异的正确性、安全、回归、样式 |
| `debugger` | 再现 → 假设 → 调查 → 根本原因 → 提出修复。**无代码编辑** — 返回报告。在失败的测试或跨多个文件影响的错误（保持 grep 噪音远离主要上下文）时使用 |
---
## 技能
由 `cil init` 安装到 `.claude/skills/`，当其主题相关时由 Claude 代码自动加载：
| 技能 | 使用场景 |
|---|---|
| `debugging` | 再现 bug → 形成排名假设 → 调查代码路径 → 提出最小修复 |
| `testing` | 生成测试脚手架（边界 → 愉快 → 边缘 → 错误）；从 `package.json` 检测框架 |
| `architecture` | 评估设计权衡、组件边界或系统演化决策 |
| `performance` | 在优化前识别和衡量瓶颈（N+1、阻塞 I/O、缓存未命中） |
| `api-design` | 设计或评审公共 API 接口 — REST/GraphQL/gRPC、版本控制、幂等性、错误合约、身份验证边界 |
| `migration` | 安全地更改数据库模式或回填数据 — 影响锁定分析、双写入转换、回滚计划，在运行任何 DDL 之前 |
| `security` | 威胁建模、信任边界、身份验证设计、输入验证、机密管理、依赖风险 — 设计时安全决策（补充 Claude 代码的内置 `/security-review`） |
| `database-design` | 从头设计模式 — 实体建模、规范化、索引策略、SQL 与 NoSQL 决策、模式演化计划 |
---
## MCP 内存服务器
MCP 服务器本地运行，为 Claude 提供结构化、可搜索的内存，跨所有会话和项目持续存在。
**重要：** 仅存储有意义的上下文 — 决策、约束、学习、架构事实。不要存储构建错误、任务日志或临时调试输出。
### 工具
**`memory_store(category, content, tags[])`**
```
类别：decision | constraint | learning | task | architecture | summary
```
示例 — Claude 在 `/wrap-up` 时自动调用：
```
memory_store("decision", "Use JWT stateless auth — no session table needed", ["auth", "jwt"])
memory_store("constraint", "Access token expires in 1h — enforced by API gateway", ["auth"])
memory_store("learning", "Refresh tokens require separate DB table with revocation support", ["auth", "db"])
```
**`memory_search(query, limit?)`**
BM25 全文搜索。由 Claude 在 `/develop` 开始时调用以检索相关先前上下文。
**`session_snapshot(summary, decisions[])`**
保存 ≤2KB 会话状态。在 `/wrap-up` 期间调用。在通过 `PreCompact` 钩子压缩上下文之前自动注入。
**`session_restore()`**
检索上一个快照 + 最近的记忆。在新会话开始时调用，以在不重新解释项目的情况下恢复上下文。
---
## 输出压缩
CIL 包括 RTK 样式的每工具输出压缩，以减少 verbose 命令的 token 使用量。
**模式** (`--mode=lite|full|ultra`，默认为 `full`）：
- `lite` — 仅剥离 ANSI/噪音；无重复或截断
- `full` — 4 支柱管道（过滤、重复数据删除、分组、截断）
- `ultra` — 添加语义重复数据删除（折叠 PASSED 测试为计数等）
**每工具调度：** 压缩器自动检测 `git`、`npm`、`pytest`、`docker`、`cargo`、`tsc` 或 `pip` 输出，并应用工具特定过滤器，然后是通用管道（例如，从 git 差异中删除 `index abc..def` 行，重复数据删除重复的 `npm WARN deprecated`，折叠 Docker 层拉取进度，隐藏 `Compiling crate v…` cargo 噪音，总结每个文件中重复的 TS 错误代码，重复数据删除 `Requirement already satisfied` 来自 pip）。
**手动使用：**
```bash
git diff | cil compress
npm test 2>&1 | cil compress --mode=ultra
git log --oneline -50 | cil compress
```
**自动：** `PreToolUse` 钩子将 **每个 Bash 命令** 的输出通过 `cil compress` 输送到 Claude 看到之前。根据命令自动选择模式：
- `ultra` — 测试运行器和安装程序（`pytest`、`npm test`/`install`、`cargo test`、`vitest`、`jest`、`pip install`、`go test`）。
- `full` — 具有结构化输出的冗长工具（`git diff/log/show`、`npm run build`、`docker`、`eslint`、`make`、`mvn`、`tsc`等）。
- `lite` — 默认适用于任何未识别的命令（仅 ANSI 条带，无重复/截断 — 对任意脚本安全）。
**测量减少量**（运行 `npm run benchmark` 复制）：
| 样本 | 输入行数 | 精简版 | 全功能版 | 超级版 |
|---|---|---|---|---|
| git diff（50 个 hunk） | 500 | 24% | 24% | 24% |
| npm install w/ 弃用噪音 | 38 | 86% | 86% | 86% |
| pytest（200 pass, 3 fail） | 219 | 0% | 0% | 95% |
| docker build（12 steps + layer pulls） | 67 | 48% | 48% | 48% |
| cargo build（50 crates + warnings） | 56 | 87% | 87% | 87% |
| tsc（5 个文件中有 40 个错误） | 41 | 48% | 48% | 48% |
| pip install（50 已满足 + 5 个新） | 61 | 96% | 96% | 96% |
| generic（警告 + 堆栈帧） | 43 | 8% | 86% | 86% |
---
## 钩子
CIL 安装五个 Claude 代码钩子，在后台默默工作：
| 钩子 | 事件 | 它做了什么 |
|---|---|---|
| `PreToolUse` | 每个 Bash 调用 | 重写命令以通过 `cil compress` 输送输出 — 自动保持工具输出的 token 高效 |
| `PostToolUse` | 每个工具之后 | 错误循环检测 + 上下文大小警告（见下文） |
| `PreCompact` | 在 `/compact` 之前 | 将相关记忆和上一个会话快照注入压缩的上下文中，以便 Claude 不会丢失关键决策 |
| `Stop` | 会话结束 | 日志记录到内存 DB 以备将来相关性排名 |
| `UserPromptSubmit` | 每个用户消息 | 检测更正（“不要这样做”，“不，而是…”）并自动将它们存储为 `feedback` 标记的记忆 — 在每个 `/develop` 会话开始时重放。 |
### 更正记忆
当您更正 Claude（“停止添加注释”，“使用制表符而不是空格”，“不要在测试中模拟 DB”），`UserPromptSubmit` 钩子自动捕获规则 — 无需 `/learn`。它存储为 `learning` 记忆，并带有 `feedback` 标签，并在未来 `/develop` 会话开始时重放。中高置信度规则仅限；低置信度短语被忽略。
### 上下文压力信号
两个 `PostToolUse` 信号推动了“错误 → 修复 → 错误 → 修复”循环，这会增加上下文：
**错误循环检测。** 连续 3 次相同会话工具错误后，CIL 注入一次性 `additionalContext` 告诉 Claude 停止迭代并重新思考根本原因。在 6+ 连续错误时，它升级为更强的 STOP 消息和显示给您的 `systemMessage`。每个层级仅触发一次会话 — 无垃圾邮件。
**转录大小警告。** 每次工具调用后，CIL 统计转录文件。当超过阛值（默认为 **420 KB ≈ 120K tokens** — “1M-token 窗口的 12% 和 200K-token 窗口的 60% 的收敛点”），它注入一次性提示，询问 Claude 总结当前任务状态，并提示您运行 `/compact`。通过 env 变量覆盖阛值：`bash` 导出：
```bash
export CIL_CONTEXT_WARN_BYTES=300000 # 提前警告（例如适用于 Haiku 100K）
export CIL_CONTEXT_WARN_BYTES=900000 # 延迟警告（例如适用于 1M 令牌模型）
```
两个信号都是建议性的 — Claude 仍然决定做什么。钩子可以建议 `/compact`；只有您（或 Claude 代表您）可以运行它。
---
## CLI 参考
| 命令 | 描述 |
|---|---|
| `cil init` | 在当前项目中初始化 CIL |
| `cil init --global` | 全局安装斜杠命令 (`~/.claude/commands/`) |
| `cil init --skip-mcp` | 跳过 MCP 服务器注册 |
| `cil init --skip-hooks` | 跳过 `.claude/settings.json` 中的钩子配置 |
| `cil doctor` | 验证所有组件 |
| `cil upgrade` | 检查 npm 的新版本 + 同步模板；如果有更新则运行 `npm install -g` |
| `cil upgrade --check` | 在应用之前预览更改 |
| `cil upgrade --global` | 升级全局安装（影响 `~/.claude/commands/`） |
| `cil uninstall` | 从当前项目中删除 CIL 模板、钩子和 MCP |
| `cil uninstall --global` | 删除全局安装 |
| `cil uninstall --purge` | 同时删除 `~/.cil/` 内存数据库 |
| `cil compact` | 打印当前内存快照 |
| `cil retrieve "query"` | 内存上的全文搜索 |
| `cil retrieve -n 20 "query"` | 限制结果（默认为 8） |
| `cil retrieve -c decision "query"` | 按类别筛选 |
| `cil compress` | 压缩 stdin（管道工具，默认为 `--mode=full`） |
| `cil compress --mode=ultra` | 添加语义重复数据删除（适用于测试输出的最佳选择） |
| `cil compress --mode=lite` | 仅过滤 ANSI/噪音，无重复数据删除 |
| `cil compress -n 100` | 将输出限制为 100 行 |
| `cil export [--out file.json]` | 将内存 + 会话导出为 JSON |
| `cil import <file.json>` | 导入 JSON 导出（按内容哈希去重） |
| `cil prune --older-than=90d` | 删除超过阈值的内存 |
| `cil prune --older-than=60d --dry-run` | 预览删除而不执行 |
| `cil prune --older-than=90d -c task` | 仅限于一个类别 |
| `cil reset --db` | 清除内存数据库 |
| `cil reset --all` | 清除所有 CIL 数据 |
---
## 会话连续性流程
```
会话 1
└── /develop auth
└── /wrap-up
└── memory_store("decision", "use JWT") → ~/.cil/memory.db
└── session_snapshot("implemented auth layer")
[context compaction]
└── PreCompact hook fires
└── injects memory summary into compacted context
会话 2（新的一天）
└── /develop refresh token
└── memory_search("auth") → retrieves prior decisions
└── Claude knows JWT choice, 1h expiry constraint
└── no re-explanation needed
```
---
## 使用流程
CIL 展示的真实端到端场景，演示如何充分利用 CIL。
### 启动新功能
```
/spec add user notifications via email # 捕获验收标准
/develop implement email notifications # 研究 → 计划 → 实现 → 验证
/test src/lib/email.ts # 生成测试脚手架
/review # 系统化检查清单
/commit # 约定提交消息
```
### 进入不熟悉的代码库
```
/onboard # 映射项目，读取约定，检索先前内存
/develop fix the bug # 现在您了解代码库 — 继续上下文
```
### 上下文填充中途
```
/handoff # 捕获状态，生成恢复命令
/compact # PreCompact 钩子自动注入您的快照
# ── next session ──
# 粘贴 Claude 生成的恢复命令
```
### 工作会话结束（彻底关闭）
```
/review # 检查您的工作
/commit # 带有约定消息的提交
/wrap-up # 捕获决策、约束、学习成果 → 内存
```
### 回忆过去的决策
```
/retrieve auth decisions
/retrieve database schema constraints
/retrieve why we chose X
```
### 设计新系统
```
/spec new payment processing feature
# Claude 激活 database-design 技能用于模式，
# api-design 技能用于端点，
# security 技能用于身份验证边界
/develop implement payment processing
/test src/lib/payment.ts
/review
/commit
```
### 发布前安全审查
```
/review # CIL 安全技能：威胁建模、输入验证、机密
# 还要运行 Claude 代码的内置：
/security-review # 代码级漏洞扫描
```
### 完整的项目生命周期
```
# 功能循环：
/spec → /develop → /test → /review → /commit
# 会话管理：
/handoff # 当上下文填充时
/wrap-up # 会话结束时
# 下一会话：
/retrieve [topic] # 在开始前回忆之前的决策
/onboard # 如果长时间未使用，请使用
# 发布：
/release # 升序版本号，更新 CHANGELOG，推送标签
```
---
## 哲学
> 更少的上下文。更多的信号。
> 更少的提示。更多的推理。
> 单一代理优先。仅在需要时升级。
灵感来源：[context-mode](https://github.com/mksglu/context-mode) · [pro-workflow](https://github.com/rohitg00/pro-workflow) · [caveman](https://github.com/JuliusBrussee/caveman) · [RTK](https://github.com/rtk-ai/rtk) · [Andrej Karpathy Skills](https://github.com/forrestchang/andrej-karpathy-skills)
---
## 贡献
参见 [CONTRIBUTING.md](CONTRIBUTING.md)。
## 许可
MIT — 参见 [LICENSE](LICENSE)。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器