mcpField
D
devcoach

devcoach

本地服务
ultimaphoenix.github.io开发工具53 周前更新

关于 devcoach

devcoach 是面向 AI 编码 Agent 用户的本地辅导 MCP 服务。它记录用户已掌握的知识,并在技术任务完成后提供简短且相关的课程,资料保存在本地 SQLite 文件中。

主要功能

  1. 01根据已完成的技术任务提供课程
  2. 02知识档案避免重复主题
  3. 03本地 SQLite 存储且无遥测
  4. 04提供命令行和网页面板
  5. 05为部分 Agent 提供自动课程钩子

适用场景

  1. 01学习 Agent 编写代码背后的概念
  2. 02复盘任务中的陌生技术内容
  3. 03在本地跨会话追踪课程

MCP 相关

devcoach 作为本地 stdio MCP 服务运行,为兼容 MCP 的 Agent 提供辅导功能。它还为部分 Agent 提供钩子和技能,以自动发送课程。

配置

本地服务的配置在各客户端中通用,复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置
{
"mcpServers": {
"ultimaphoenix-devcoach": {
"command": "npx",
"args": [
"-y",
"devcoach"
]
}
}
}
启动命令npx -y devcoach

本地服务需要在你的电脑上安装运行环境(如 Node.js 18+)。各客户端的配置文件位置不同,请参考客户端文档。

安装包
npmdevcoach2.7.1

工具

还没有获取到工具列表

本地服务需要在你的电脑上运行后才能读取工具,维护者暂未提供工具列表。

详细介绍

devcoach

devcoach — 在 AI Agent 中直接提供渐进式技术指导

npm CI Quality Gate Coverage Node Docs License

AI 替你工作时,保持精进。

devcoach 可连接 Claude Code、Claude Desktop、Gemini CLI (beta)、Codex CLI (beta)、Cursor、Windsurf 及其他兼容 MCP 的工具。Agent 完成任务后,devcoach 会从中教你一件你尚未掌握的知识:它会精确记录你已经知道的内容,从而略过这些知识,并根据你的水平讲解每堂课——没有千篇一律的教程,不重复讲解,也无需打开任何东西。

所有操作都在本地运行。数据不会离开你的设备。所有数据都存放在一个 SQLite 文件 ~/.devcoach/coaching.db 中。

基于官方的 Model Context Protocol TypeScript SDK、Node 内置的 node:sqlite、Hono(Web 仪表板)和 Commander(命令行工具)构建。需要 Node.js ≥ 24。


为什么选择 devcoach?

如今,AI Agent 编写了我们大量的代码——这让我们很容易交付更多代码,却理解得更少。devcoach 会把 Agent 完成的任务转化为简短、贴合上下文的课程,讲解你尚未掌握的内容,让你在工作中持续学习。更深层的考量是:随着 AI 能力不断增强,稀缺的技能将变成验证 AI 产出,而只有持续练习,这项能力才能得以保留。

→ devcoach 的存在意义


工作原理

flowchart TD
    A([Task completed]) --> B{"stop-hook:<br/>paced + rate limit ok?"}
    B -->|not yet| Z(["Silent — counter +1"])
    B -->|due| C["Cue: activate the devcoach skill"]

    subgraph skill["devcoach skill"]
        C --> D{"Technical work?"}
        D -->|no| S[skip_lesson]
        D -->|yes| E[Select topic & depth]
        E --> G[log_lesson]
        G --> F[Print lesson card]
    end

    S --> Y(["Silent — pacing re-armed"])
    F --> H(["Done — counter reset"])
    F -.->|prompts| U(["You: ✅ / 💡 / ❌"])

→ 完整决策流程:会话启动 · 课程选择 · 难度校准


隐私保护设计

所有数据都保留在你的设备上。没有遥测、无需账户,也不会向外发送请求。只有一个 SQLite 文件。

→ 隐私与安全


安装

devcoach 在本地运行 — 它是一个 stdio MCP 服务,会将所有内容存储在 Agent 运行所在机器的 ~/.devcoach/coaching.db 中。它适用于 Claude Code、Claude Desktop、Gemini CLI(beta)和 Codex CLI(beta),但不适用于 claude.ai 网页版(该版本仅支持托管/远程连接器)。

需要 Node.js ≥ 24(devcoach 使用内置的 node:sqlite 模块,该模块仅在 Node 24 及更高版本中提供)。

根据你的工作习惯选择 — 每个章节都包含完整的安装和连接说明:

  • 开发者,熟悉终端 → Homebrew — 只需运行一次 brew install,还会安装 devcoach CLI。
  • 更喜欢一键、无需终端的设置 → Claude Code 插件或.mcpb 扩展。
  • 使用可识别注册表的 MCP 客户端? devcoach 已以 io.github.UltimaPhoenix/devcoach 的名称列入官方 MCP Registry — 可直接从那里安装。
  • 其他情况(npx、手动配置、其他 Agent、claude.ai 网页版)请参阅**其他安装方式**。
Homebrew(推荐开发者使用)

适用于 macOS / Linux。添加并信任 tap 一次,然后安装并连接 — 还会安装 devcoach CLI(因此 devcoach ui 和 CLI 无需 npx 前缀即可使用):

# 1. Add the tap — registers github.com/UltimaPhoenix/homebrew-tap with Homebrew
brew tap UltimaPhoenix/tap

# 2. Trust the whole tap — required when Homebrew enforces HOMEBREW_REQUIRE_TAP_TRUST
brew trust --tap UltimaPhoenix/tap

# 3. Install
brew install devcoach

# 4. Connect (Homebrew puts `devcoach` on your PATH — no `npx -y` prefix needed)
devcoach install

brew tap 会注册第三方仓库;brew trust --tap 会将其标记为可信,这样当设置了 HOMEBREW_REQUIRE_TAP_TRUST 时,Homebrew 就会加载其中的 formula。两者都只需执行一次。之后更新时,运行 brew upgrade devcoach,然后再次运行 devcoach install — Homebrew 只会更新二进制文件;接入 Agent 的 hooks 和 skill 需通过第二条命令刷新(Claude Code 插件会自动完成此操作,因此对于 Claude Code 用户来说,插件 + Homebrew 是最理想的组合:插件负责接入辅导功能,Homebrew 安装 CLI — 这样就不用运行 devcoach install 了)。一行命令安装:brew install UltimaPhoenix/tap/devcoach(如果你的 Homebrew 强制要求信任 tap,请先运行 brew trust --tap UltimaPhoenix/tap)。formula 声明了 depends_on "node",因此 Homebrew 会自动安装较新的 Node。

Claude Code 插件(推荐 Claude Code 用户使用)

将 devcoach 添加到 Claude Code 的最简单方式 — 一键完成,无需配置。插件包含所有内容(MCP 服务 + 自动辅导 Stop hooks + skill),因此不要同时运行 devcoach install(否则 Stop hooks 会被注册两次)。

# Add the marketplace once, then install (you can install any UltimaPhoenix plugin from it later)
/plugin marketplace add UltimaPhoenix/claude-plugins-marketplace
/plugin install devcoach@ultimaphoenix

安装后,MCP 服务、hooks 和 skill 会立即启用 — 无需重启。可直接在 Claude Code 中通过 /devcoach:ui 打开网页控制面板(或直接提出请求 — 使用 open_ui 工具);/devcoach:share 和 /devcoach:import 可用于传递经验;/devcoach:course 会将你没能跟上的经验转化为分步课程。之后可通过 /plugin marketplace update ultimaphoenix 更新。想体验即将推出的功能?beta 通道会将最新的 canary 版本安装为 devcoach@ultimaphoenix-beta。

该插件不会安装 devcoach CLI,但当你想在不通过 Claude 的情况下使用控制面板或访问数据时,CLI 依然很方便 — 使用 npx -y devcoach … 运行 devcoach ui、stats、lessons、share / import、backup;或者安装 Homebrew / 使用 npm i -g devcoach,即可直接运行 devcoach。但绝不要在插件旁边运行 devcoach install — hooks 由插件负责管理。

离线安装(无法访问市场)
# Download devcoach-plugin-<version>.zip from a GitHub Release, unzip, then:
/plugin marketplace add /path/to/unzipped-folder
/plugin install devcoach@devcoach

请参阅 Claude Code 插件,了解其工作原理。

Claude Desktop 扩展(.mcpb)(推荐用于 Claude Desktop)— Beta

一个可在 Claude Desktop 内置运行时中运行的单一捆绑包——无需 Node 或终端。每个 GitHub Release 都会发布一个:

  1. 从最新版本下载 devcoach-<version>.mcpb
  2. Claude Desktop → Settings → Extensions → Install Extension… → 选择 .mcpb

该捆绑包是自签名的,因此 Claude Desktop 会将其作为未验证发布者安装(要获得已验证签名,需要真实的代码签名证书)。想从源代码构建?

npm run mcpb        # → dist-mcpb/devcoach-<version>.mcpb   (npm run mcpb:sign self-signs it)
其他安装方式 — Beta
npx / npm CLI(适用于任何 MCP Agent——无需安装)

无需安装——npx 会按需运行 devcoach。对于 Claude Code 和 Claude Desktop,一条命令即可注册 MCP 服务、设置自动课程推送(Stop hooks),并将辅导技能安装到 ~/.claude/skills/devcoach/:

npx -y devcoach install

之后重启 Agent。更喜欢全局二进制文件?运行 npm install -g devcoach,然后运行 devcoach install(并在所有地方删掉 npx -y 前缀)。升级 devcoach 后,请重新运行 devcoach install 以刷新技能——当技能版本过时时,devcoach stats 会提醒你。

**Canary 构建:**每次合并到 develop 分支的更改都会以 next 标签发布到 npm——运行 npx -y devcoach@next(或 npm install -g devcoach@next)即可使用尚未发布的版本,文档见 ultimaphoenix.github.io/dev-coach/next。latest 始终指向上一个正式版本。

Claude Code 手动配置 MCP(如果无法使用 devcoach install)

选项 A — 通过 claude mcp CLI(推荐):

claude mcp add devcoach npx -- -y devcoach mcp

# all projects (user scope)
claude mcp add --scope user devcoach npx -- -y devcoach mcp

选项 B — 直接编辑 ~/.claude.json:

{ "mcpServers": { "devcoach": { "type": "stdio", "command": "npx", "args": ["-y", "devcoach", "mcp"] } } }

然后将 hooks 添加到 ~/.claude/settings.json,以自动推送课程——stop-hook 会在每轮对话后判断是否该推送课程,prompt-hook 则会在需要推送时预先为模型提供提示:

{
  "hooks": {
    "Stop": [
      { "hooks": [{ "type": "command", "command": "npx -y devcoach stop-hook", "timeout": 60 }] }
    ],
    "UserPromptSubmit": [
      { "hooks": [{ "type": "command", "command": "npx -y devcoach prompt-hook", "timeout": 30 }] }
    ]
  }
}

提示:全局安装会将 devcoach 添加到你的 PATH,因此可以删掉 npx -y 前缀。devcoach install 会自动检测这一点。 正在使用 Claude Code 插件(上文)? 请跳过此处的 hooks——插件已包含它们。

Gemini CLI — 完整辅导循环(hooks + 技能)— Beta

一条命令即可注册 MCP 服务、AfterAgent/BeforeAgent 课程 hooks 和辅导技能:

npx -y devcoach install --gemini

或者安装打包好的 Gemini 扩展:从最新版本下载 devcoach-gemini-extension-<version>.zip,解压,然后运行 gemini extensions install <folder>。两种方式任选其一(两者提供相同的 hooks;devcoach 会检测扩展并跳过重复项)。详情:docs/install/gemini-cli.md。

Codex CLI — 完整辅导循环(hooks + 技能)— Beta

一条命令即可注册 MCP 服务(codex mcp add)、课程 hooks(~/.codex/hooks.json 中的 Stop/UserPromptSubmit)和辅导技能(~/.agents/skills/):

npx -y devcoach install --codex

Codex 会在下次运行时要求你信任新 hooks 一次——请批准,否则辅导功能将无法运行。详情:docs/install/codex.md。

其他 MCP Agent(Cursor、Windsurf、Cline、Continue、Zed…)

将以下内容添加到 Agent 的 MCP 配置文件中(或者,如果你的客户端可以浏览 MCP Registry,也可以从那里安装 io.github.UltimaPhoenix/devcoach):

{
  "mcpServers": {
    "devcoach": {
      "command": "npx",
      "args": ["-y", "devcoach", "mcp"]
    }
  }
}
| Agent | 配置文件 | |-------|-------------| | **Cursor** | `~/.cursor/mcp.json` | | **Windsurf** | `~/.codeium/windsurf/mcp_config.json` | | **Cline**(VS Code) | VS Code 设置 → `cline.mcpServers` | | **Continue.dev** | `~/.continue/config.json` → `mcpServers` | | **Zed** | `.zed/settings.json` → `context_servers` |

Claude Code、Gemini CLI 和 Codex CLI 支持停止钩子(在每项任务后自动发送课程)。此表中的 Agent 可完整访问所有 MCP 工具和资源——可手动触发辅导,也可通过提示词让 Agent 触发。

claude.ai web(复制技能——不使用 MCP)

Claude.ai 不支持 MCP 服务。请改为将辅导说明安装为技能:

  1. 复制 assets/SKILL.md 的内容
  2. 前往 claude.ai → Settings → Custom instructions(或 Skills,具体取决于你的套餐)
  3. 粘贴内容并保存

这样 claude.ai 就能提供辅导行为,但无法使用 MCP 工具(课程记录和个人资料跟踪将无法运行)。

请保持技能为最新版本。 对于 Claude Code / Claude Desktop,技能会自动提供(通过 MCP 提示词或插件),并始终保持最新。如果你手动将其复制到 claude.ai,请在每次 devcoach 更新后重新粘贴最新的 SKILL.md。


入门

Agent 首次连接 devcoach 时,会检测到你的个人资料尚未设置,并在对话中引导你完成设置——无需单独运行命令。(更喜欢在终端操作?运行 devcoach setup 即可启动相同的向导。)

→ 完整入门指南

阶段 1 — 选择如何设置个人资料

devcoach 会扫描你的完整本地 Claude Code 历史记录(Agent 工作过的每个项目,按近期活动排序——仅使用文件和活动元数据,绝不读取提示词文本),并提供四种方式来构建个人资料:

devcoach: Your knowledge profile isn't set up yet. I scanned 9 of your Claude Code
projects and found TypeScript (dev-coach), Java (discordbot), Swift (blueprince).

  1. Automatic (strongly recommended) — build the profile from that, no questions asked
  2. Automatic (Deep)   — also read my local session transcripts for a sharper profile
  3. Guided             — a step-by-step conversation about my stack
  4. Import backup      — restore a devcoach backup zip
阶段 2 — 构建个人资料
自动(强烈推荐)

根据从历史记录中检测到的技术栈,一次性构建完整的个人资料——包括主题、信心分数、分组和辅导笔记本。无需回答问题:之后你可以通过聊天、CLI 或仪表板查看并调整结果。

自动(深度)

可选。包含“自动”模式的所有功能,此外还有一个独立子 Agent,会读取本地 Claude Code 会话记录(~/.claude/projects/)中的真实对话文本,以尽可能准确地生成个人资料和笔记本。首先会在滚动的 3 个月时间范围内进行仅使用元数据的预检;如果发现的项目超过 8 个,devcoach 会询问你是要缩短时间范围、使用最近的 25 个项目继续,还是指定项目。Agent 会事先说明:与仅扫描元数据相比,此操作会向模型分享更多你自己的本地历史记录——仅在此设备上进行一次,作为设置步骤。

引导式

更想自行描述技术栈?devcoach 会询问你使用的每项技术和信心水平(1–3 仍在学习 · 4–6 已熟悉 · 7–9 掌握较好 · 10 专家),与你一起确定主题分组,然后保存个人资料。

导入备份

换了新设备或正在重新安装?提供备份 zip 的路径,即可立即恢复完整的个人资料——包括知识图谱、课程、设置和笔记本。

阶段 3 — 保存个人资料,开始辅导

保存后,Agent 会展示已完成的设置,并按照知识图谱的组织方式进行分组——对于“自动”模式,这是你首次看到它,因此此时可以提出修改要求:

✓ Profile saved — 24 topics across 6 groups.

### Languages
- **typescript** — 7/10
- **java** — 5/10

### DevOps
- **docker** — 7/10
- **github_actions** — 6/10

### Other
- **regex** — 4/10

Change any of this later in chat ("set my Java confidence to 7"), with the
`devcoach` CLI, or in `devcoach ui`.

就这样。继续工作即可。辅导会在后台静默进行。


你的第一堂课

像往常一样处理任务。Agent 回复后,devcoach 会附上一堂课:

You: Refactor this endpoint to handle concurrent requests properly.

Agent: [refactors the code, explains the changes]

### ──────── 🎓 devcoach ────────
**Promise.allSettled vs Promise.all — don't let one failure sink the batch** · TypeScript · Mid

Promise.all rejects the moment any promise rejects, and you lose the results of
the ones that already succeeded. For independent work (fan-out fetches, batch
writes) that's usually the wrong default.

Promise.allSettled always resolves, giving you a status for every promise:

    const results = await Promise.allSettled(ids.map(fetchUser));
    const ok = results.filter(r => r.status === "fulfilled").map(r => r.value);

Use Promise.all when the tasks are genuinely all-or-nothing; reach for
allSettled when partial success is meaningful and you want to report failures.

💡 *Senior tip:* for coordinated work that *should* cancel siblings on failure,
an AbortController shared across the requests gives you all-or-nothing with
prompt cancellation — the structured-concurrency middle ground.
### ──────── typescript · mid ────────

Did that land? ✅ knew it (y) · 💡 understood (u) · ❌ couldn't follow (n)

回复 y(已经知道了——信心提高)、u(新知识且讲解清楚)或 n(内容太密集——保留为循序渐进课程的种子),以便调整后续课程;也可以直接继续:不回复就不会有任何变化。


截图

知识图谱(在此个性化设置)学习历史设置
知识图谱课程设置
一次学习一步
课程页面

上下文与个性化

每节课程都会记录发生地点——你的项目文件夹、代码库、分支、提交哈希和编辑器。你还可以通过 ~/.devcoach/learning-state.md 中的学习笔记本个性化辅导内容,影响 devcoach 优先讲解哪些主题,以及课程的深入程度。

→ 辅导笔记本 · Web 控制面板指南


Web 控制面板

随时打开控制面板,查看进度、编辑个人资料或管理设置:

npx -y devcoach ui          # → http://localhost:7860 (printed as a clickable link; Ctrl+C stops it)
npx -y devcoach ui --open   # …and open it in your browser
npx -y devcoach ui --stop   # stop a running dashboard, e.g. one your agent started

正在使用 Claude Code 插件?在 Claude Code 中输入 /devcoach:ui 即可——无需安装(/devcoach:ui stop 可关闭控制面板)。

页面可执行的操作
知识图谱查看所有主题及其信心条;直接调整分数
课程浏览和筛选完整的学习历史;为课程加星标以便重温;与队友分享课程或导入他们的课程
设置更改速率限制,导入/导出个人资料,创建备份

完整参考:docs/usage/web-ui.md


分享课程

对你有帮助的一节课程,只需一步即可分享给队友——可以分享为可复制的文本(卡片加一行 devcoach:lesson:1:…)、无服务器链接,或 .devcoach.md 文件。接收者将其粘贴、点击或拖入自己的 devcoach 后,课程便会以由你分享的标记加入日志,且不会占用他们的每日限额。除非你附上课程发生的位置,否则只会分享课程内容;本地路径绝不会被分享。

devcoach share --last            # or --link / --file, --with-context, --by "Ada" / --anonymous
devcoach import                  # reads the clipboard; or pass a code, link, URL, file, or - for stdin

在控制面板中:点击课程上的 ↗ 分享,并在“课程”页面点击 + 导入(将 .devcoach.md 拖到任意位置即可)。在你的 Agent 中输入:"分享上一节课程"、"导入这节 devcoach 课程:…"——使用插件时,可输入 /devcoach:share 和 /devcoach:import。完整指南:docs/usage/sharing.md


CLI 参考

CLI 是用于查询和管理辅导数据的辅助界面。Web 控制面板中也提供所有功能。运行 devcoach --help 或 devcoach <command> --help 可查看完整用法。

命令说明
devcoach install注册到 Claude Code(MCP + hooks + skill)/ Claude Desktop
devcoach profile显示带信心条的知识图谱
devcoach stats概览:课程数量、最弱/最强主题
devcoach lessons使用筛选条件浏览学习历史
devcoach lesson <id>完整显示单节课程
devcoach star <id>为课程加星标
devcoach feedback <id> <know|understood|dont_know|clear>记录你对某节课程的回答
devcoach share [id] [--last] [--link] [--file]分享课程给队友(可复制的文本、链接或 .devcoach.md)
devcoach import [source]添加分享的课程——代码、链接、URL 或文件;不带参数时读取剪贴板
devcoach set max_per_day <n>每日课程上限(默认值为 2)
devcoach set min_gap_minutes <n>课程间隔分钟数(默认值为 240)
devcoach backup [file.zip]导出知识、课程、设置和笔记本
devcoach restore <file.zip>从备份恢复
devcoach setup在终端中运行引导向导
devcoach ui打开 Web 控制面板

(如果尚未全局安装,请在命令前加上 npx -y。)完整参考:docs/usage/cli.md


配置

默认情况下:每天最多 2 节课,间隔至少 4 小时。 想要更多指导?想要更少?自行调整。

devcoach set max_per_day 5           # more lessons per day
devcoach set min_gap_minutes 60      # lessons closer together

也可以使用网页仪表盘的「设置」页面。有关所有选项,请参阅 docs/reference/configuration.md。


预期效果

在一个典型工作周内,每天完成 1–2 项任务,你将收到 2–4 节与你的技术栈和信心水平相匹配的课程。 每节课只需 30 秒即可读完。经过一个月的常规 AI 辅助开发,你将积累一本针对自身短板的辅导笔记——记录你难以掌握的具体模式、容易忽略的边缘情况,以及你会不假思索地使用某些工具背后的原因。

强度太高? 调低频率:devcoach set max_per_day 1。想要更多指导? 提高频率:devcoach set max_per_day 5。所有设置都可以调整。

复利效应:在工具不断增强的同时持续学习的开发者,才能掌控最终结果。


故障排除

“Node 版本错误”

devcoach 需要 Node.js ≥ 24。检查你的版本:node --version。如果低于 24,请升级:brew upgrade node(Homebrew)或 nvm install 24(如果使用 nvm)。

“Failed to install plugin devcoach@ultimaphoenix: … invalid manifest … repository: expected string”

1.0.1 及之前版本的插件发布包包含一个当前 Claude Code 无法接受的清单,因此安装在复制任何内容之前就已停止。刷新市场,使其指向最新版本,然后重新安装:

/plugin marketplace update ultimaphoenix
/plugin install devcoach@ultimaphoenix

“MCP 服务未连接”

使用 Claude Code 插件时(plugin:devcoach:devcoach failed to connect):运行 /devcoach:setup——其第一步会显示原因(Node 版本低于 24、npm 不在 PATH 中、首次运行时没有网络)和解决办法;然后从 /mcp 重新连接。使用插件时,不要运行 devcoach install。详情请参阅:插件故障排除。

不使用插件时(npm / Homebrew、Claude Desktop):运行 devcoach doctor:它会检查每个 Agent 启动的命令(Claude Desktop 的命令来自 claude_desktop_config.json,Claude Code 的命令来自 ~/.claude.json)是否存在于该 Agent 使用的 PATH 中、它指定的 Node 是否存在且版本 ≥ 24,以及运行的 devcoach 版本。然后运行 devcoach install --force,用绝对路径命令重新注册,并重启 Agent。在 Claude Desktop 的日志(~/Library/Logs/Claude/mcp-server-devcoach.log)中,Failed to spawn process: No such file or directory 表示 devcoach 从未运行:命令或其背后的 Node 不存在——请参阅devcoach 无法启动时。每次 devcoach 启动时,都会向该日志写入一行,记录其版本、Node 和安装位置。

“辅导没有触发/没有出现课程”

运行 devcoach doctor——它会检查整个配置链路(Node 版本、~/.claude/settings.json 中的 hook 条目——以及存在时的 ~/.gemini/settings.json 和 ~/.codex/hooks.json——技能、MCP 注册、数据库、节奏计数器、速率限制),最后给出结论,准确说明下一次是否会触发课程以及原因。请记住,节奏控制本来就会保持克制:使用默认设置时,只有在会话中达到 nudge_every 次交互且未超出速率限制后才会触发课程——这是有意设计,并非错误。要查看实时跟踪,请设置 DEVCOACH_HOOK_DEBUG=1 并查看 ~/.devcoach/hook.log:每次 hook 运行都会追加一行,记录其决策(paced (3/10)、rate limited: …、cue)。Claude Code、Gemini CLI (beta) 和 Codex CLI (beta) 均提供 hooks;其他 Agent(Cursor、Windsurf、Cline)不支持 hooks——可按需通过 MCP 工具或手动提示来获取辅导。

课程旁边出现“Stop hook error occurred”

这是 Claude Code 当前对任何会阻止操作的 Stop hook 所使用的提示——包括 devcoach 的课程触发(旁边的“🎓 devcoach…”行说明这是辅导,而非失败)。这不会造成影响,而且按设计也很少出现:UserPromptSubmit 预热 hook 会在大多数情况下于当前轮次中提供课程,因此只有在此操作未成功时,才会触发阻止操作的后备机制。

“SQLite 权限错误”

devcoach 会写入 ~/.devcoach/coaching.db。如果遇到权限错误,请检查目录是否存在,以及你是否有写入权限:ls -ld ~/.devcoach。如果目录不存在,请运行 devcoach install 或 devcoach setup 进行初始化。


已知限制

  • claude.ai 网页版: 不支持 MCP 服务。你可以使用技能副本(仅提供辅导行为,不存储数据)。
  • 临时沙盒: 如果你的 Agent 每次重启都在全新的沙盒中运行(例如 GitHub Codespaces),devcoach 就无法跨会话保留数据。当前会话中可以正常使用,但经验不会延续到后续会话。
  • Windows: devcoach 已在 macOS 和 Linux 上经过测试。Windows 支持取决于 Node.js ≥ 24 和 node:sqlite 是否可用(总体表现稳定,但请报告问题)。
  • 多用户计算机: devcoach 会写入 ~/.devcoach/,因此每位用户都有自己的辅导数据库。配置档案不会共享。

卸载

一条命令即可撤销 devcoach install 所做的所有配置,包括 MCP 注册、钩子条目和技能,适用于 Claude Code 和 Claude Desktop(测试版 Agent 可添加 --gemini、--codex 或 --all)。除非你要求删除,否则辅导数据会保留:

devcoach uninstall                 # remove MCP server + hooks + skill (Claude Code + Claude Desktop)
devcoach uninstall --all --data    # every agent, and delete ~/.devcoach (asks first; devcoach backup before)
npm uninstall -g devcoach          # then remove the program (npx: nothing to remove)
brew uninstall devcoach            # or, via Homebrew (brew untap UltimaPhoenix/tap to drop the tap)

请在运行 brew uninstall / npm uninstall 之前运行 devcoach uninstall:Homebrew 公式没有卸载钩子,而二进制文件一旦被移除,留在 ~/.claude/settings.json 中的钩子就会在每轮对话中报错。改用 Claude Code 插件?运行 /plugin uninstall devcoach 即可一次性移除其钩子、技能和服务。


了解更多

完整文档: README 是快速入门指南。详细指南请访问**官方文档**:


社区

  • 给仓库点星 — 帮助更多人发现它
  • GitHub Issues — 功能请求、反馈和问题:提交 issue

贡献

欢迎参与!请参阅 CONTRIBUTING.md 开始贡献。


开发

git clone https://github.com/UltimaPhoenix/dev-coach && cd dev-coach
npm install
npm run dev -- mcp        # run the MCP server from source
npm run dev -- ui         # run the web dashboard from source
npm run lint && npm run typecheck && npm test
npm run build             # tsup → dist/bin.js
npm run mcpb              # build the Claude Desktop .mcpb (npm run mcpb:sign to self-sign)
  • MCP Inspector: npx @modelcontextprotocol/inspector node dist/bin.js mcp
  • 技术栈: @modelcontextprotocol/server(MCP SDK v2)· node:sqlite · Hono · Commander · Zod · Biome · Vitest · tsup
分支与发布
  • develop 是集成分支:每个 PR 都以它为目标,每次合并都会发布一个 canary (npx -y devcoach@next,文档位于 /next/)。
  • main 只接收正式发布,始终对应最新的已发布版本(Claude Code 自有市场从此分支安装)。
  • 发布只需点击一次:在 develop 上运行 CI 工作流(Run workflow → patch / minor / major)。CI 会在 develop 上更新版本号、打标签、将 main 快进合并,然后通过 OIDC 来源证明发布到 npm,将 .mcpb 和插件压缩包附加到 GitHub Release,并更新 Homebrew tap、插件市场和 MCP Registry。首次设置:为 devcoach 包在 npmjs.com 上配置 Trusted Publisher(GitHub Actions,仓库 UltimaPhoenix/dev-coach,工作流 ci.yml)。

许可证

版权所有 (C) 2026 UltimaPhoenix

devcoach 根据 GNU Affero General Public License v3.0(AGPL-3.0-only)授权。 你可以使用、修改和分发它——但前提是,你分发的任何修改版本,或作为网络服务运行的任何修改版本,也必须根据 AGPL 以开源形式发布。目前不提供商业许可证;如果你需要将 devcoach 嵌入闭源产品中, 请提交 issue咨询。

许可常见问题

devcoach 始终完全免费,任何人都可以永久下载、安装和使用,包括在工作中和商业项目中使用。AGPL 不是价格标签:只有当你想在不遵守 AGPL 的情况下,发布 devcoach 本身的专有/闭源衍生版本 时,才需要付费。

使用 devcoach 不会让你的代码受 AGPL 约束。 它通过 stdio/MCP 作为独立进程运行(npx -y devcoach mcp);与它保持独立地交互并不构成衍生作品——这与查询采用 AGPL 许可的数据库完全一样。你自己的项目仍可采用你选择的任何许可证。

  • ✅ “我在使用 Claude Code 开发闭源创业应用时,会用到 devcoach。” — 免费。你的应用仍是专有软件,无需承担任何义务。
  • ✅ “我的整个团队都安装了 devcoach,用来获取内部/商业代码仓库的指导。” — 免费。在公司使用未经修改的工具没有问题。
  • ⚠️ “我 fork 了 devcoach,添加了一项功能,并发布该软件包或将其仪表板托管为公共服务。” — 你必须根据 AGPL 发布 修改后的 devcoach 源代码。
  • 💼 “我想把 devcoach 嵌入付费产品,并对修改内容保密。” — AGPL 不涵盖这种情况——请先提交 issue 咨询。

只要继续将 devcoach 作为工具/可执行程序使用(而非作为导入的库),AGPL 就不会影响你自己的代码。

评论

支持 Markdown

第一次接触 MCP?

从协议是什么,到在客户端里装上第一个服务,这几条回答覆盖了大多数入门问题。

一个开放协议,规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话,MCP 服务负责提供工具、资源和提示模板,两者通过标准消息通信,同一个服务可以被不同客户端复用。