内容
<h1 align="center">ramp</h1>
<p align="center"><em>自适应、基于代码仓库的学习模式，适用于 Claude Code - 它衡量你可以 <strong>做到</strong>什么，而不是你点击了什么。</em></p>
<p align="center">
<a href="https://github.com/gf-labs/ramp"><img src="https://img.shields.io/badge/version-1.1.0-3b82f6?style=flat-square" alt="版本"></a>
<a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-22c55e?style=flat-square" alt="许可证"></a>
<img src="https://img.shields.io/badge/Claude_Code-plugin-d97757?style=flat-square&logo=anthropic&logoColor=white" alt="Claude Code 插件">
<img src="https://img.shields.io/badge/Python-3.11+-3776AB?style=flat-square&logo=python&logoColor=white" alt="Python 3.11+">
<img src="https://img.shields.io/badge/topics-5-6366f1?style=flat-square" alt="主题">
</p>
<p align="center">由 <a href="https://github.com/berniegreen">Bernie Green</a> · <a href="https://github.com/gf-labs">Greenfield Labs</a> 构建</p>
---
## 为什么存在
Claude Code 的采用因一个可预测的原因而停滞：文档很完整，但它不能适应 *你* - 你的代码库，你的当前水平，你已经证明的内容。大多数开发者在基本编辑和多文件更改上停滞不前。钩子、工作树、自定义代理、MCP 服务器和管道集成仍然未被探索。能力差距不断扩大。
`/ramp:up` 解决了这个问题。在任何代码仓库中运行它。它会扫描你的环境 - 不仅仅是代码库，还有你的 Claude Code 配置、git 历史、会话历史和之前的进度。它最多会问 2-3 个有针对性的问题，关于无法检测的事情。然后，它会提供一个个性化、基于代码仓库的学习路径，并在整个会话中作为你的副驾驶。
**这不是报告。这是一种模式。**
> **对于团队来说，这是一个入职引擎。** 公司将 `ramp` 作为项目级命令部署，以便新工程师能够从第一天就开始使用 Claude Code、代码库和团队工作流程 - 从每个人已经知道的内容开始。单独开发者使用它来提升自己。参见 [公司部署](#公司部署)。
---
## 快速开始
```bash
/plugin marketplace add gf-labs/gfl-marketplace
/plugin install ramp@gfl-marketplace
```
然后，在任何代码仓库中：
```bash
/ramp:up
```
就这样。`ramp` 会检测你的水平，渲染你的个性化知识图，并为你提供第一个基于你面前实际文件的掌握任务。
---
## 命令
七个命令，全部命名为 `/ramp:*`。`up` 是引擎；其余的命令读取、强化和维护你的图。
| 命令 | 功能 |
|---------|--------------|
| `/ramp:up [topic]` | **学习模式。** 扫描你的环境，评估你的水平，提供基于代码仓库的路径，并作为会话的副驾驶 |
| `/ramp:tree [topic\|all]` | 只读查看你的知识图 - 无推理，无写入 |
| `/ramp:review [topic]` | 间隔重复复习 `[✓]` 节点 - 通过则推进，失败则重置 |
| `/ramp:cheatsheet [topic]`| 一个可扫描的个人参考，基于你自己的证据轨迹 |
| `/ramp:pin [topic]` | 会话中间检查点 - 状态，保存已证明的节点，可选的 MEMORY 快照 |
| `/ramp:wrap [topic]` | 会话结束收获 - 升级节点，更新复习计划，可选快照 |
| `/ramp:ingest [topic] [src]` | 从外部源生成新的主题模式 - 课程大纲，API 文档或规范（PDF / URL / 文件） |
```bash
/ramp:up # 默认主题：claude-code
/ramp:up 我是一名加入团队的新后端工程师
/ramp:up mcp-development 我正在构建一个服务器
/ramp:up 哪些技能适用于编写好的钩子？ # 顾问模式，会话中
```
---
## 设计原则
**检测后再询问。** 调用时运行超过 80 个 shell 命令 - CLAUDE.md 内容，钩子配置，MCP 服务器，工作树计数，会话历史，头部调用。到你看到问题时，`/ramp:up` 已经确定了你的水平并识别了你的差距。你最多回答三个问题，而且它们是具体的。
**证明优于声称。** 图表区分 `[✓]`（证明）和 `[~]`（自我报告）。`settings.json` 中的钩子是 `[✓|artifact]`。说“是的，我使用过钩子”是 `[~|reported]`。 `[✓]` 需要至少一个可验证的细节 - 一个标志，观察到的行为，导航的权衡。 “我听说过钩子”和“我有一个 PostToolUse 钩子，触发我的 linter”之间的区别是知识和实践之间的整个差距。
**掌握任务，而不是检查清单。** 每个节点都有一个可证伪的掌握标准和一个基于代码仓库的练习。不是“运行你的测试” - 而是“在 `auth_service.py` 上运行 `pytest tests/` 并解释失败。”
**依赖门控进度。** 你不会进入代理，直到你证明了代码更改。门控 * 是 * 教育学。
**会话持久，主题命名空间。** 图表位于 `~/.claude/knowledge-graphs/[topic].md` 并在每个代码仓库中跟随你。返回的用户使用新的图表（≤ 7 天）直接跳过问题。进度永远不会丢失。
**间隔重复。** `[✓]` 节点带有 `| next: YYYY-MM-DD [LN]` 复习计划（1d → 3d → 7d → 21d → 60d → 永久）。 `/ramp:review` 逐步完成当天的节点 - 没有评估，没有新技能，只有强化。
**引擎/课程分离。** `/ramp:up` 是主题无关的。课程 - 节点，检测信号，差距问题，掌握标准，文档链接 - 位于 `topics/` 下的模式文件中。添加主题意味着编写一个文件。引擎永远不会改变。
---
## 主题
| 主题 | 命令 | 节点 | 焦点 |
|-------|---------|-------|-------|
| `claude-code` *(默认)* | `/ramp:up` | 81 | Claude Code 的功能表面 - 一个元主题，包含 5 个子主题 |
| `best-practices` | `/ramp:up best-practices` | 15 | CLAUDE.md 设计，配置模式，会话卫生 |
| `mcp-development` | `/ramp:up mcp-development` | 29 | 构建 MCP 服务器：工具，资源，提示，分布 |
| `anthropic-api` | `/ramp:up anthropic-api` | 18 | Claude API：补全，工具使用，代理循环，生产模式 |
| `claude-code-internals` | `/ramp:up claude-code-internals` | 5 | 经验证的、未记录的 Claude Code 行为 |
| *(你的主题)* | `/ramp:up [topic]` | 任意 | 安装模式 → 它直接起作用 |
`claude-code` 元主题涵盖五个子主题 - **入门 · 构建 · 配置 · 部署 · 管理** - 按顺序排列。
---
## 三种模式
`/ramp:up` 根据它运行时的发现而适应。
| 上下文 | 发生的情况 |
|---------|-------------|
| **现有代码仓库** | 扫描代码库 + 环境 + 历史 → 渲染图表 → 提供掌握任务 → 作为会话副驾驶保持参与 |
| **空/新代码仓库** | 询问要构建的内容 → 与你一起构建 → 在使用每个 Claude Code 功能时进行讲解 → 从演示的内容中渲染图表 |
| **代码仓库目录** | 调查所有代码仓库（名称，栈，最后活动）→ 你选择一个焦点 → 以单代码仓库模式继续 |
---
## 知识图
`claude-code` 的 81 个节点，每个节点都基于 Claude Code 的实际功能表面。
```
[Getting Started] 核心基础
[✓] Claude Code 的功能和用途
[✓] Claude Code 如何使用计算机（工具循环）
[★] 内存类型和范围层次
[Build] 代理和编排
[✓] 子代理基础：生成和工具访问
[~] 前台 vs. 后台子代理
[★] 自定义子代理定义（.claude/agents/.md）
[Build] 钩子系统
[✓] PostToolUse 钩子（linting，reactions）
[★] PreToolUse 钩子（validation，blocking）
[Build] 无头和 MCP
[~] 无头模式（-p 标志，非交互）
[ ] MCP：配置和使用服务器
[配置] 设置基础
[✓] 设置范围层次：全局，项目，本地
[·] 部署 （解锁：完成配置）
[·] 管理 （解锁：完成部署）
你的前沿：→ 内存类型 [★] → CLAUDE.md 作为生活记忆 [★] → PreToolUse 钩子 [★]
水平：Builder - 演示了钩子和命令，正在进入编排
```
标记键： `[✓]` 演示 · `[~]` 自我报告 · `[ ]` 未完成 · `[★]` 掌握目标 · `[·]` 已锁定
每个 `[★]` 成为一个 **掌握任务** - 一个可证伪的标准 + 一个基于代码仓库的练习，使用你的真实文件名和工具链。
> 随时使用 `/ramp:tree`（只读）查看，或使用 `/ramp:cheatsheet` 从你的证据轨迹中构建个人参考。参见 [`docs/tree-format.md`](docs/tree-format.md) 获取注释图表格式。
### 间隔重复复习
`/ramp:review` 在演示的 `[✓]` 节点上运行一个专注的会话，这些节点今天到期 - 没有评估，没有新技能，只有强化。
- 查找所有 `[✓]` 节点，其中 `next: YYYY-MM-DD ≤ today`
- 每个节点询问一个有针对性的问题
- **通过** （具体细节）→ 推进一个级别，下一个日期从间隔阶梯开始
- **失败** （模糊或无）→ 重置为 L1，明天再次复习
间隔阶梯：L1 = 1d · L2 = 3d · L3 = 7d · L4 = 21d · L5 = 60d · L6 = 永久。
---
## 公司部署
`ramp` 旨在促进工程师入职。两个工件协同工作 - 一个静态的，一个活跃的。
### 两个工具，两个目的
| | `ONBOARDING.md` | 自定义主题模式 |
|--|---|---|
| **格式** | 静态 Markdown 文档 | 活动知识图会话 |
| **何时使用** | 第 1 天：“如何运行？” | 第一周：有针对性的入职培训和练习 |
| **个性化？** | 否 - 相同文档适用于所有人 | 是 - 从开发人员已经知道的内容开始 |
| **进度跟踪** | 否 | 是 - 证据轨迹，经验值，间隔重复 |
| **由谁生成** | `/ramp:up` 阶段 4 选项 b | `/ramp:up [your-topic]` |
| **提交到代码仓库？** | 是（可选） | 模式是；知识图谱保留个人 |
使用两者：`ONBOARDING.md` 作为快速入门参考，一个自定义主题用于主动提升。
### 步骤 1 - 提交命令
将命令文件复制到团队代码仓库的 `.claude/commands/` 中，以便工程师在克隆时获取它们：
```bash
cp commands/up.md /your-team-repo/.claude/commands/ramp.md
cp commands/tree.md /your-team-repo/.claude/commands/tree.md
cp commands/review.md /your-team-repo/.claude/commands/review.md
```
知识图谱（`~/.claude/knowledge-graphs/`）保留个人 - 它们存在于每个开发人员的机器上，而不是代码仓库中。
### 步骤 2 - 创建自定义主题模式（推荐）
在团队代码仓库中添加 `.claude/knowledge-graphs/schemas/[your-topic].md`。这是用于入职培训到 *此* 代码库的课程 - 节点，检测信号，差距问题和掌握标准特定于您的项目。
```
.claude/
└── knowledge-graphs/
└── schemas/
└── acme-onboarding.md ← 提交此文件
```
示例节点： `[ROOT] 环境设置`（制作设置，.env，本地运行）， `[A] 架构`（数据流，服务所有权）， `[B] 开发工作流程`（PR 过程，测试套件，部署）， `[C] 团队实践`（升级，监控）。参见 [`topics/claude-code.md`](topics/claude-code.md) 获取完整的模式格式 - 一旦提交，工程师克隆并运行 `/ramp acme-onboarding`。
### 步骤 3 - 将团队上下文添加到 `CLAUDE.md`
`/ramp:up` 读取一个 `## Onboarding` 部分，并将其折入每个会话和生成的 `ONBOARDING.md` 中：
```markdown
## Onboarding
- 运行 `make setup` 而不是其他任何东西
- 阅读 `docs/architecture.md` 获取系统设计上下文
- 认证系统由 @alice 所有，数据管道由 @bob 所有
- 在 #dev-help 中提问 - 在升级前 30 分钟规则
- 部署：PR → staging → 24h 浸泡 → 生产
```
会话结束后，`/ramp:up` 还提供 **引导代码库的 Claude Code 设置** - 创建 `CLAUDE.md`，添加启动钩子，编写自定义命令 - 如果缺少任何一个。
---
## 安装
**从 GFL 市场（推荐）。** `ramp` 通过 [`gf-labs/gfl-marketplace`](https://github.com/gf-labs/gfl-marketplace) 目录发布，与 `tools` 一起：
/plugin marketplace add gf-labs/gfl-marketplace
`/plugin install ramp@gfl-marketplace`
**从本地克隆（开发 / 离线）。** `ramp` 也是其自己的单个插件市场，因此您可以直接添加克隆 - 注意安装名称在此处为 `ramp@ramp` 而不是 `@gfl-marketplace`：
```bash
git clone https://github.com/gf-labs/ramp ~/path/to/ramp
```
`/plugin marketplace add ~/path/to/ramp`
`/plugin install ramp@ramp`
钩子（被动观察器）和主题模式在第一次会话启动时自动设置。更新 `/plugin marketplace update gfl-marketplace`。
**添加社区主题：```bash
cp your-topic.md ~/.claude/knowledge-graphs/schemas/your-topic.md
/ramp:up your-topic
```
---
## 被动观察器
一个钩子监视每个 Claude Code 会话并升级 `~/.claude/knowledge-graphs/claude-code.md`，当它检测到技能证据时 - 无需运行 `/ramp:up`。 `scripts/skill-observer.py` 监听两个事件（`PostToolUse`，`SessionStart`）并检测例如：
- `git worktree add` → Worktrees `[✓|historical]`
- `claude -p` → 无头模式 `[✓|historical]`
- 编写 `.claude/agents/*.md` → 自定义子代理定义 `[✓|historical]`
- 编写 `settings.json` 带有 `hooks` 键 → PostToolUse 钩子 `[✓|historical]`
- 编写 `settings.json` 带有 `mcpServers` 键 → MCP 服务器 `[✓|historical]`
> **它看不到：** 内置 CLI 命令（`help`，`/compact`，`/usage`，`/doctor`) 从未进入工具循环）
观察者随插件安装自动注册。编写后验证 `cat ~/.claude/knowledge-graphs/claude-code.md`。
---
## MCP 服务器 - `knowledge-graph`
`mcp/server.py` 是一个可选的 MCP 服务器，为 `/ramp:up` 提供结构化的读写访问权限 - 原子本地保存 + 跨设备同步和团队/组织层面的客户端（与兼容的后端配合使用，不包含在此存储库中）。
**为什么使用它。** 没有 MCP，`/ramp:up` 通过 bash `cat` 读取图表，通过 `Write` 工具写入。使用它，读写操作通过结构化工具进行 - 使可互换的后端（本地文件 → 主机 API）无需更改 `up.md`。
| 工具 | 描述 |
|------|-------------|
| `read_graph(topic)` | 读取知识图谱 - 返回 Markdown |
| `save_graph(topic, content)` | 原子写入 + 可选的后端同步 |
| `list_topics()` | 带有级别和经验值的主题列表 - 返回 JSON |
| `get_benchmarks(topic)` | 个人统计数据；当配置了后端时，团队/组织数据 |
| `export_delta(topic, since_date)` | 自日期以来演示的节点 - 用于团队共享 |
**设置。** 创建存储库本地虚拟环境（系统 `python3` 配备冲突的 `mcp` 存根，因此服务器必须从 `.venv` 运行）：
```bash
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
```
> 在正常的插件安装中，`setup-mcp.py` 会话启动钩子为您注册服务器（`claude mcp add -s user`）。下面的块用于手动注册。
将以下内容添加到 `~/.claude.json`（全局用户作用域 MCP 配置） - 将 `command` 指向 venv python，或使用 `./mcp/start.sh` 为您解析：
```json
{
"mcpServers": {
"knowledge-graph": {
"type": "stdio",
"command": "/绝对路径/ramp/.venv/bin/python3",
"args": ["/绝对路径/ramp/mcp/server.py"]
}
}
}
```
**托管后端（团队/组织）。** 设置 `KNOWLEDGE_GRAPH_API_URL`，服务器将 `read_graph`/`save_graph` 代理到 `GET/PUT /graphs/{topic}`，将 `get_benchmarks` 代理到 `GET /benchmarks/{topic}`。兼容的后端服务将解锁跨设备同步，团队技能矩阵和组织仪表板；如果没有，后端将回退到本地文件。**此存储库仅包含客户端 - 后端服务未包含。**
---
## 模式 vs. 知识图谱
`~/.claude/knowledge-graphs/` 中存在两种不同的事物：
| | 位置 | 包含 | 由谁创建 |
|--|----------|----------|------------|
| **模式** | `…/schemas/[topic].md` | 课程蓝图：节点，检测信号，差距问题，掌握标准，文档链接 | 插件安装（在第一次会话启动时自动符号链接到 `topics/`） |
| **知识图谱** | `…/[topic].md` | *您的* 进度：节点状态，证据轨迹，复习计划，经验值 | `/ramp:up` |
每个主题一个模式。`topics/claude-code.md` → `schemas/claude-code.md` → 由 `/ramp:up` 使用；您的进度保存在 `~/.claude/knowledge-graphs/claude-code.md`。
---
## 代码仓库结构
```
ramp/
├── .claude-plugin/
│ ├── plugin.json # 插件清单（名称，版本，描述）
│ └── marketplace.json # 单插件市场目录
├── commands/ # 命令源 - up, tree, review, cheatsheet, pin, wrap, ingest
├── topics/ # 模式源 → 符号链接到 ~/.claude/knowledge-graphs/schemas/
├── hooks/hooks.json # 插件钩子（PostToolUse + SessionStart）
├── scripts/ # skill-observer.py, file-size-warn.py, setup-mcp.py
├── mcp/ # knowledge-graph MCP 服务器（server.py, start.sh）
└── docs/ # tree-format.md, docs-map.md
```
### 在 ramp 本身工作
从源代码仓库中的插件加载 - 无需安装，无需缓存重建：
```bash
claude --plugin-dir /path/to/ramp
```
`SessionStart` 触发并将 `topics/` → `~/.claude/knowledge-graphs/schemas/` 自动符号链接。使用 `/reload-plugins` 捕获次要更改。要刷新 **已安装**（缓存）的版本，请删除并重新添加市场目录，然后重新安装 - `/plugin install` 如果插件已经存在，则会静默跳过，`/reload-plugins` 读取缓存，而不是源。 `--plugin-dir` 工作流始终读取实时并完全跳过这一点。
---
## 使用 Claude Code 构建
`ramp` 是 Claude Code 扩展模型的工作演示 — 一个有状态的、适应性的、支持课程的学习系统，**完全由 Markdown 和少量 Python 构建**，无需应用程序运行时。 其工作原理如下：
- **`!bash` 注入** — 80 多个扫描命令在 Claude 读取单个令牌之前运行，注入结构化上下文。预计算，而不是代理工具使用：快速、确定性、低成本。
- **主题模式加载** — bash 命令从 `$ARGUMENTS` 读取请求的主题，并将匹配的模式作为静态文本 `cat` 出来。 引擎 (`up.md`) 持有零主题特定内容。
- **`$ARGUMENTS`** — 主题关键词加上用户在 `/ramp:up` 后输入的自由格式上下文。
- **`allowed-tools`** — 限定为 `Read, Glob, Grep, Bash, Write, Edit`，因此 Claude 可以导航存储库、运行练习、编写 `ONBOARDING.md` 和更新图表 — 而无需无限访问权限。
- **持久文件 I/O** — `~/.claude/knowledge-graphs/[topic].md` 是 YAML 前言 + Markdown：人类可读、机器可解析、可通过复制粘贴共享。
- **间隔重复作为纯文件 I/O** — `| next: YYYY-MM-DD [LN]` 字段编码时间表。 无数据库，无外部状态。
- **钩子** — 跨 `PostToolUse` 和 `SessionStart` 的被动观察者更新图表，无需用户操作。
- **MCP 服务器** — 一个可选的结构化后端，使存储层可交换。
- **一个确定性内核** — `ramp_core.py`（仅限标准库）是 XP、间隔重复梯度和图表验证的单一真实来源。 被动观察者钩子和 MCP 服务器都导入它，因此 Markdown 命令 *渲染* 计算结果而不是重新派生它们 — 无论会话是否有 MCP 服务器，掌握评分都是相同的。
- **自然语言中的分支逻辑** — 阶段结构（检测 → 评估 → 推断 → 输出 → 工件）被表示为指令。 没有解释器，没有状态机。 提示 *就是* 程序。
这是 [自定义斜杠命令](https://docs.anthropic.com/en/docs/claude-code/slash-commands) 功能被推向极限的体现。
---
## 路线图
计划但尚未构建的主题：
| 主题 | 焦点 |
|-------|-------|
| `claude-cli` | CLI 标志 (`-p`, `--model`, `--output-format`, `--resume`)，无头脚本，CI |
| `claude-settings` | settings.json，权限，钩子语法，MCP 配置，CLAUDE.md 层次结构 |
| `claude-features` | 应用程序内模式：计划模式，`/compact`，内存，子代理，技能 |
| `bash` · `react` · `typescript` · `git` · `dsa` | 通用开发者主题 |
要贡献模式，请遵循 [`topics/claude-code.md`](topics/claude-code.md) 中的格式 — 或使用 `/ramp:ingest` 生成初稿。
---
## 准确性和版本控制
课程根据 **2026 年 6 月** 的 [Claude Code 文档](https://code.claude.com/docs) 进行验证。 Claude Code 经常发布 — 事件、设置键和标志不断演变。 如果发现偏差，请打开问题或使用 `/ramp:ingest` 重新生成受影响的模式。
---
## 许可证
[MIT](./LICENSE) © 2026 Greenfield Labs
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器