explain-code

用途

explain-code 是一个代码解释技能，用于在讲解代码工作原理、教学代码库，或用户询问“这是怎么工作的”时，给出结构清晰、易于理解的解释。它的核心目标是让读者先建立直觉，再深入细节。

主要能力

该技能要求每次解释代码时都包含四个必备要素：

先给类比：把代码比作日常生活中的事物，在深入细节前先建立直觉。对于复杂概念，可以使用多个类比。
画图：使用 ASCII 艺术或 Mermaid 图表展示流程、结构或组件之间的关系。复杂流程和类关系优先用 Mermaid，简单快速的示意用 ASCII。
走查代码：逐步解释发生了什么。
指出一个坑：点出与该代码相关的常见错误或误解。

输出模板

技能提供按对象类型组织的解释结构：

文件/类：用途、关键概念、结构、工作原理、依赖与交互、值得注意的细节。
函数/方法：用途、参数与返回值、工作原理、边界情况与错误处理、用法。
目录/模块：用途、架构、关键文件、外部接口、数据流。

Spring Boot 等价映射

当被解释的代码不是 Java/Kotlin + Spring Boot 时，技能会读取 references/spring-boot-mapping.md，并在解释中附上等价的 Spring Boot 映射，方便 Java/Kotlin 读者对照理解。

核对库与框架用法

由于模型训练数据存在知识截止，技能要求在解释使用库或框架的代码时主动核对当前 API 与行为：

识别版本：检查 pom.xml、build.gradle.kts、package.json 等依赖文件，确定库和框架的确切版本。
查阅当前文档：使用 Context7（mcp__claude_ai_Context7__resolve-library-id 然后 mcp__claude_ai_Context7__query-docs）获取最新文档，适用于版本比模型训练数据更新、不确定某个 API/配置属性/模式是否仍有效或已被弃用替换、代码使用了高级或不常见特性的情况。
搜索网络：使用 WebSearch 和 WebFetch 检查特定版本的破坏性变更或迁移指南、版本间影响代码行为的已知变化、已被新版本替换的弃用 API。
检查 GitHub：需要时用 gh CLI 查看依赖的发布说明、变更日志或 issue，例如 gh api repos/{owner}/{repo}/releases/latest。

技能明确要求：不要仅凭模型知识就假定某个 API 或模式是正确的，有疑问就查。

解释准则

使用 file_path:line_number 格式引用具体行号。
点名设计模式，例如“这里使用了策略模式来……”。

完整示例

技能给出了一个端到端示例，解释一小段 JavaScript，并附上面向 Java/Kotlin 读者的 Spring Boot 等价映射。

被解释的代码（src/middleware/auth.js:1-22）：

const jwt = require('jsonwebtoken');

function authMiddleware(secret) {
  return (req, res, next) => {
    const header = req.headers.authorization;
    if (!header || !header.startsWith('Bearer ')) {
      return res.status(401).json({ error: 'missing token' });
    }
    const token = header.slice(7);
    try {
      req.user = jwt.verify(token, secret);
      next();
    } catch (err) {
      return res.status(401).json({ error: 'invalid token' });
    }
  };
}

module.exports = authMiddleware;

1. 类比

俱乐部门口的保安。每位客人（请求）都必须出示手环（JWT）。保安并不认识客人本人——只检查手环是否由场馆签发（用正确的密钥签名）。没有手环 → 被拒。伪造手环 → 被拒。手环有效 → 保安记住你是谁（把信息挂到 req.user），放你进下一个房间（next()）。

2. 图表

sequenceDiagram
    participant Client
    participant Auth as authMiddleware
    participant JWT as jsonwebtoken
    participant Handler as Next handler

    Client->>Auth: GET /resource (Authorization: Bearer …)
    alt header missing or malformed
        Auth-->>Client: 401 missing token
    else header present
        Auth->>JWT: verify(token, secret)
        alt verify throws
            JWT-->>Auth: error
            Auth-->>Client: 401 invalid token
        else verify succeeds
            JWT-->>Auth: payload
            Auth->>Handler: next() with req.user
            Handler-->>Client: 200 OK
        end
    end

3. 走查

auth.js:3 — authMiddleware 是一个工厂：接收签名密钥并返回真正的 Express 中间件。柯里化让你在应用启动时一次性绑定密钥。
auth.js:5-8 — 取出 Authorization 头。如果缺失或不以 Bearer 开头，直接短路返回 401。这个提前返回使它成为守卫，而不是转换器。
auth.js:9 — header.slice(7) 去掉字面量 'Bearer '（7 个字符），只留下 token。
auth.js:11 — jwt.verify 做两件事：确认签名是用 secret 生成的，并解码 payload。成功后 payload 被挂到 req.user 供下游处理器使用。
auth.js:12 — next() 把控制权交给 Express 链中的下一个中间件/处理器。没有它，请求会挂起。
auth.js:13-15 — 任何验证错误（签名错误、过期、格式错误）都会被捕获并转成带通用消息的 401。

4. 坑

catch 块吞掉了原始错误，对任何失败都返回同样的通用 401——包括过期 token。生产环境通常需要区分“token 过期”和“token 被篡改”，以便客户端刷新；检查 err.name === 'TokenExpiredError' 并相应响应。另外：绝不要在错误路径中记录 token 本身。

Spring Boot 等价映射

对 Java/Kotlin 读者来说，Spring 中的同一模式是一个 OncePerRequestFilter（或在 Spring Security 中是一个自定义 AuthenticationFilter），它取出 Authorization 头，调用 JwtDecoder，填充 SecurityContext，然后继续链或抛出 BadCredentialsException，由 ExceptionTranslationFilter 转成 401。Spring Security 的 oauth2ResourceServer().jwt() 以声明式方式端到端配置这一流程，因此大多数应用不需要手写该过滤器。

适用场景

讲解代码如何工作。
教学代码库。
用户询问“这是怎么工作的？”等类似问题。

限制

资料未提供该技能的具体安装方式、收费模式、支持平台或运行环境要求，这些信息暂未提供。