explain-c-module 插件

skill + hook + local MCP 自动化工作流：git commit、git pull/merge 或 rebase 触碰 C/C++ 源码 → 自动生成并审查面向初级嵌入式工程师的中文讲解文档（v2.5）。支持本地 MCP、Claude Code 原生插件 Hook、Codex 全局 PostToolUse Hook，以及仓库级 Git 更新 Hook。

不止"做了什么"，更讲清为什么这样写——引用真实工程证据，配 Mermaid 图表，附生僻语法小课堂。

English summary: Explain embedded C/C++ modules, RTOS tasks, drivers, interrupts, DMA, low-power paths and call graphs; generate Chinese Markdown and interactive HTML documentation.

适合搜索的关键词：embedded C、firmware analysis、RTOS task、driver analysis、interrupt/ISR、DMA、low-power、call graph、C 代码讲解、嵌入式驱动分析、低功耗代码分析。

它解决什么问题

AI 时代初级工程师常能"看懂每行代码"，却缺乏"手把手开发"才能积累的底层直觉。这个插件在每次 commit C 代码后，自动让 Claude 讲透新实现的模块。

安装 Git 更新 Hook 后，merge/rebase 也会触发同一套“增量生成 → 文档审查 → 修订复审”流程；纯文档变更会被过滤，避免自触发循环。

插件自带无第三方依赖的本地 MCP Server，可独立完成变更检测、源码结构分析、证据检索、文档安全写入和 Markdown/HTML/Mermaid 校验；explain-c-module 与 review-explain-doc 变为可选增强。

v2.5 质量铁律（深度契约 + 本地 MCP）

实例优先，三级递降：工程真实日志证据 → 行业经典案例 → 构造最小示例；禁止只讲抽象结论
每函数至少一图或一表：时序图/状态图/流程图按内容选型；MD 用 ASCII，HTML 用 Mermaid 交互版
HTML 发挥 Web 优势：Mermaid 可缩放图表、<details> 折叠深挖面板、三色语义提示框、证据框——禁止做成 MD 的换肤
反事实讲法：每个关键设计补"如果不这样写会怎样"，工程历史 bug 是现成教材
生僻语法进小课堂：函数指针/container_of/__attribute__ 等逐个四段式详解（语法拆解→发明动机→本代码用法→常见误用），禁止一句白话带过

工作原理

git commit（触碰 .c/.h）
  │
  ▼
PostToolUse hook (scripts/explain-commit.cjs)
  ├─ 正则识别真实 commit（git 须为命令段开头；排除 commit-tree/--no-commit/引号内文本）
  ├─ git rev-parse HEAD 取 sha；与 .claude/explain-commit.state 比对去重
  │  （同一 HEAD 只注入一次——命令文本里恰好含 "git commit" 字样的 echo/grep 不再反复误触发）
  ├─ git diff-tree --root HEAD 列出本次提交文件
  ├─ 过滤 C 源文件；>30 个视为批量导入，静默跳过（防 init 风暴）
  │
  ▼ 注入 additionalContext 指令文本
Claude 解析指令 → 调用 explain-c-module skill
  │
  ▼
按 SKILL.md 执行：读代码 → 匹配知识清单 → 生成文档
  ├─ doc/explain/md/<模块名>.md      （源文档）
  └─ doc/explain/html/<模块名>.html  （交互阅读版，Mermaid 图表 + highlight.js 高亮）

Git 更新后的自动闭环（可选）

# 在目标仓库根目录执行一次，保留已有 hook 内容
node /path/to/explain-c-module-plugin/scripts/install-git-update-hook.cjs

安装器追加 post-merge 与 post-rebase，由 scripts/explain-update.cjs 检测所有 C/C++ 变化（单次最多 30 个文件）。检测到变化后调用 codex exec，要求依次运行 explain-c-module 与 review-explain-doc，只修改文档，不提交 Git。试运行或暂停：

EXPLAIN_C_MODULE_UPDATE_DRY_RUN=1 node scripts/explain-update.cjs
EXPLAIN_C_MODULE_UPDATE_ENABLED=0 git pull

该流程需要本机已登录 Codex CLI；Codex 不可用或任务失败时 hook 返回非零并输出错误，不会伪造“审核通过”。

核心设计：hook 提供"时机 + 事实"（何时 commit、改了哪些文件），skill 提供"方法"（怎么讲），中间靠注入的自然语言指令衔接。hook 无法直接调用 skill——这是 Claude Code 的架构约束，也是职责分离的体现。

本地 MCP 扩展

根目录的 .mcp.json 声明 explain-c-module-local（Codex 配置使用 mcpServers 包装；Claude 配置同步内嵌在清单）。客户端启动后可调用 repo_info、changed_files、analyze_module、trace_flow、extract_protocol、search_code、read_document、 write_document 和严格深度校验的 validate_documents。Server 通过 stdio 运行在本机，不需要公网服务器、数据库或第三方 npm 包；写入接口被限制在 doc/explain/，不会修改 C/C++ 源码。

详细工具清单和安全边界见 docs/local-mcp.md。

安装（三选一）

方式一：marketplace 安装（推荐，可自动更新）

# 在目标仓库根目录的 Claude Code 里执行（GitHub，国际用户）：
/plugin marketplace add gc9768/explain-c-module-plugin
/plugin install explain-c-module@explain-c-module-market

# 或 Gitee 镜像（.git 后缀走 git 协议；不带 .git 的 raw 直连在部分网络下会因
# CDN 签名跳转报 "Invalid marketplace schema"，此时用下面的本地方式）：
/plugin marketplace add https://gitee.com/gc9768/explain-c-module-plugin.git
/plugin install explain-c-module@explain-c-module-market

安装后如未生效，运行 /reload-plugins（会话中途安装需重载）。

国内网络排障：Gitee raw 直连失败（Invalid marketplace schema: expected object / HTTP 404）通常是 Gitee 的签名 CDN 跳转所致，不是仓库问题。解决办法见方式二—— 先 git clone 再 add 本地目录，最稳。

方式二：本地试用（国内网络推荐）

# 先克隆（Gitee 直连快），再把本地目录添加为 marketplace：
git clone https://gitee.com/gc9768/explain-c-module-plugin
# 在 Claude Code 里：
/plugin marketplace add <克隆到的路径>/explain-c-module-plugin
/plugin install explain-c-module@explain-c-module-market

插件被拷贝到 ~/.claude/plugins/cache，对源目录的后续修改不影响已安装版本，需重装刷新。

方式三：其他 agent（Codex / Cursor / OpenCode 等）

本 skill 符合 agentskills.io 开放标准（SKILL.md 格式），可跨工具使用。仓库同时包含 .codex-plugin/plugin.json，可作为 Codex plugin 的源目录；但本地 MCP 可通过根目录的 .mcp.json 由支持 MCP 的 Agent 启动，Git 更新 Hook 仍需显式安装。 Claude Code 会展开 ${CLAUDE_PLUGIN_ROOT}；其他客户端若不支持该变量，请改用绝对路径。

# Codex：拷贝 skill 到其加载目录，新开会话自动加载
git clone https://gitee.com/gc9768/explain-c-module-plugin
mkdir -p ~/.codex/skills
cp -r explain-c-module-plugin/skills/explain-c-module ~/.codex/skills/

# 之后可以使用本地 MCP 工具，或在对话中说："用 explain-c-module 讲解 xxx 目录"

# 如果使用 Codex plugin 工作流，则保留仓库根目录的 .codex-plugin/plugin.json，
# 通过 Codex 的本地 plugin/marketplace 安装流程安装；不要使用 Claude 的
# /plugin marketplace add 或 .claude-plugin/marketplace.json 作为 Codex manifest。

能力	Claude Code（插件）	Codex（插件/skill）	其他 agent（纯 skill）
手动触发讲解	✅ `/explain-c-module`	✅ 对话中说 skill 名	✅ 对话中说 skill 名
commit 自动触发	✅ hook 注入	✅ 可选全局 PostToolUse 适配	❌ hook 机制各异，未内置
merge/rebase 自动生成+审查	✅ 仓库 Git Hook（显式安装）	✅ 仓库 Git Hook（显式安装）	❌
大提交守卫	✅ MAX_C_FILES=30	✅ MAX_C_FILES=30	—（无自动触发即无此问题）
sha 去重	✅ 同一 HEAD 只讲一次	✅ 同一 HEAD 只讲一次	—

Codex Hook 适配（可选）

Codex 支持全局 PreToolUse / PostToolUse Hook，但插件清单目前不能直接声明并自动注册插件 Hook。因此本仓库提供“插件脚本 + 配置合并器”适配层：

# 在 Codex 中明确执行一次；会把本插件的 PostToolUse(Bash) 条目合并到 ~/.codex/hooks.json
node /path/to/explain-c-module-plugin/scripts/install-codex-hook.cjs

安装器会把 Hook 脚本复制到 ~/.codex/hooks/explain-c-module/，然后让 ~/.codex/hooks.json 指向这个稳定副本；安装完成后可以删除原始下载目录。重复运行会迁移旧版本的源码绝对路径并避免重复注册。卸载使用：

node /path/to/explain-c-module-plugin/scripts/install-codex-hook.cjs --uninstall

也可以手动把 hooks/codex-hooks.json 的 PostToolUse 条目合并到 ~/.codex/hooks.json，并将 <EXPLAIN_C_MODULE_PLUGIN_ROOT> 替换为插件绝对路径；这种手动方式仍会依赖插件目录，不适合安装后删除下载包。安装后需新开 Codex 会话（或按当前版本要求重新加载配置）。该 Hook 只在成功的 git commit 触碰不超过 30 个 C/C++ 文件时注入上下文，状态写入仓库私有的 .codex/explain-commit.state，不会阻断提交。

这不是 Claude hooks/hooks.json 的直接复用：Claude 使用 ${CLAUDE_PLUGIN_ROOT} 和 Claude 专用上下文协议；Codex 使用 ~/.codex/hooks.json、tool_name/tool_input/tool_output 输入字段。两套脚本并存，互不覆盖。若团队不希望修改全局 Codex 配置，则继续手动调用 skill 即可。

依赖

Node.js（hook 脚本运行环境；Claude Code 本身基于 Node，装了 Claude Code 就有）
无 npm 依赖，纯 Node 内置模块（fs/child_process）

使用

自动触发（装完即生效）

正常开发 commit 即可：

git add project/baidu_interaction/ui/ui_camera.c
git commit -m "feat: 摄像头预览优化"
# → Claude 自动收到指令，讲解 ui_camera.c 并产出文档

大提交守卫：单次 commit 触碰 >30 个 C/H 文件时静默跳过。这防止 git init && git add . && git commit 导入存量大代码库时触发几百份讲解文档——那不是"新写的代码"，不在 skill 服务范围内。阈值在 scripts/explain-commit.cjs 顶部 MAX_C_FILES 可调。

sha 去重（v2.3）：同一 HEAD 只注入一次讲解指令，已讲解的 sha 记在 <仓库>/.claude/explain-commit.state（建议把 .claude/ 加入 .gitignore）。防的是：命令文本里恰好含 "git commit" 字样的 echo/grep/cat（没有真的 commit）反复误触发，对同一个旧提交一遍遍讲解。

手动触发

/explain-c-module              # 讲解当前目录的模块
/explain-c-module src/drivers/uart.c
/explain-c-module src/drivers/

注意：插件 skill 的调用名带命名空间，可能显示为 explain-c-module:explain-c-module，以 / 前缀补全列表实际显示为准。

常见自然语言触发方式

不必记住命令名，以下说法都适合作为 skill 请求：

解释这个 C 文件的调用链和线程关系
分析这个 RTOS 任务为什么这样设计
讲解这个驱动的中断、DMA 和资源生命周期
分析这个嵌入式工程的低功耗睡眠与唤醒流程
生成这个 C 模块的中文 Markdown 和 HTML 架构文档

英文也可以直接使用：Explain this embedded C module、Analyze this RTOS driver、Trace the call graph and low-power wakeup path。

产物

文件	README 说明（详见模板）
`doc/explain/md/<模块名>.md`	源文档（进 git 做 diff 评审；8+1 节结构）
`doc/explain/html/<模块名>.html`	交互阅读版（Mermaid 可缩放图表、`<details>` 折叠深挖面板、三色语义提示框、证据框、highlight.js 高亮）

生成后可调用 review-explain-doc 做只读质量审核，检查源码证据、调用链、图表语法、Markdown/HTML 一致性、路径/行号和硬件结论的不确定性。审核最多推动 2 轮修订；没有子 agent 时由主 agent 按清单自审，不修改源代码。

生成效果示例

以一个 IPC 摄像头工程的 ipc_record.c（录像/回放模块）为例，v2.5 生成的文档包含：

5 段真实工程证据（带来源标注的崩溃断言、心跳日志、时间线）
4 张 Mermaid 图（数据流/竞态崩溃时序/录像状态机/回放切换时序）
2.5 节语法小课堂（函数指针四段式详解等）
9 处反事实（每个设计决策的"不这样会怎样"，均有实测事故背书）

适用场景

团队里有新人接手大型嵌入式 C 代码库（SDK/RTOS/驱动）
想把"只有老员工脑子里的为什么"沉淀成文档
代码审查/交接时快速生成某个模块的深度导读

环境要求

Claude Code CLI（claude.ai/code）
（HTML 阅读版）浏览器联网加载 highlight.js/Mermaid CDN；离线时仅无高亮，内容完整

维护契约（改 skill 名必读）

skill 与 hook 是松耦合文本契约，改名需同步 5 处：

skills/explain-c-module/ 目录名
SKILL.md frontmatter name:（解析主键）
SKILL.md 正文标题、description、用法示例
hooks/hooks.json 的 description（Claude 专用 hook，建议同步）
scripts/explain-commit.cjs 注入文本中的 skill 名引用（漏掉即静默失效，commit 后不再自动讲解，无任何报错）

验证：grep -ri "旧名" 插件目录 应只剩 doc/explain/ 输出路径（产物目录不改，改了孤儿化历史文档）。

另注：hook 的去重状态文件 <仓库>/.claude/explain-commit.state 里存的是 sha，不含 skill 名，改名无需清理。

文件清单

explain-c-module-plugin/
├── .codex-plugin/
│   └── plugin.json         # Codex 插件清单
├── .mcp.json               # 本地 MCP Server 配置
├── .claude-plugin/
│   ├── plugin.json        # 插件清单
│   └── marketplace.json   # marketplace 目录（单插件仓库专用）
├── skills/
│   ├── explain-c-module/  # 讲解方法论（可独立运行的 skill，v2.5）
│   │   ├── SKILL.md
│   │   └── references/    # 3 个模板/清单
│   └── review-explain-doc/ # 生成文档后的只读质量审核 skill
│       ├── SKILL.md
│       └── references/review-checklist.md
├── examples/
│   └── README.md           # Embedded C、RTOS、驱动、低功耗示例提示词
├── hooks/
│   ├── hooks.json         # Claude Code hook 注册
│   └── codex-hooks.json   # Codex hook 配置模板（需合并到 ~/.codex/hooks.json）
├── scripts/
    ├── explain-commit.cjs        # Claude hook 脚本
    ├── explain-commit-codex.cjs  # Codex PostToolUse 适配脚本
    ├── install-codex-hook.cjs    # 合并 Codex 全局 Hook 配置（显式执行）
    ├── explain-update.cjs       # merge/rebase 后增量生成+审查
    └── install-git-update-hook.cjs # 安装 post-merge/post-rebase（显式执行）
└── mcp/
    └── server.cjs          # 无第三方依赖的 stdio MCP Server

License

MIT — 随便用，改了更好欢迎 PR。

Navigation Menu

Repository navigation

About

Repository files navigation

explain-c-module 插件

它解决什么问题

v2.5 质量铁律（深度契约 + 本地 MCP）

工作原理

Git 更新后的自动闭环（可选）

本地 MCP 扩展

安装（三选一）

方式一：marketplace 安装（推荐，可自动更新）

方式二：本地试用（国内网络推荐）

方式三：其他 agent（Codex / Cursor / OpenCode 等）

Codex Hook 适配（可选）

依赖

使用

自动触发（装完即生效）

手动触发

常见自然语言触发方式

产物

生成效果示例

适用场景

环境要求

维护契约（改 skill 名必读）

文件清单

License

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
.claude-plugin		.claude-plugin
.codex-plugin		.codex-plugin
.github/workflows		.github/workflows
docs		docs
examples		examples
hooks		hooks
mcp		mcp
scripts		scripts
skills		skills
.mcp.json		.mcp.json
LICENSE		LICENSE
README.md		README.md

Latest commit

History

Folders and files

Repository files navigation

explain-c-module 插件

它解决什么问题

v2.5 质量铁律（深度契约 + 本地 MCP）

工作原理

Git 更新后的自动闭环（可选）

本地 MCP 扩展

安装（三选一）

方式一：marketplace 安装（推荐，可自动更新）

方式二：本地试用（国内网络推荐）

方式三：其他 agent（Codex / Cursor / OpenCode 等）

Codex Hook 适配（可选）

依赖

使用

自动触发（装完即生效）

手动触发

常见自然语言触发方式

产物

生成效果示例

适用场景

环境要求

维护契约（改 skill 名必读）

文件清单

License

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages