技能使用指南

dialyzer-analysis（Erlang/Elixir代码类型分析）Skill 是什么？怎么用？

dialyzer-analysis 技能专注解读并修复 Erlang/Elixir 中的 Dialyzer 警告与类型差异，覆盖 @spec 规范写法、模式匹配覆盖、no_return、联合类型与不透明类型建模，并给出 mix dialyzer 调试命令与分层修复路径，帮助开发者快速消除类型警告、提升代码可靠性。

Erlang/Elixir代码类型分析技能Skilldialyzer-analysis
8 个章节 约 17 分钟阅读 AI 智能生成

Erlang/Elixir代码类型分析技能Skill：把 Dialyzer 警告读成可执行的修复清单

  • 它是什么：一个专注于 Dialyzer 警告解读与类型差异修复的 AI 技能，覆盖类型规范编写、常见警告定位、类型分析模式与调试命令，英文名 dialyzer-analysis，技能 ID 为 13875。
  • 它解决什么：Dialyzer 的警告文本往往只给出一句"模式匹配不完整"“函数没有局部返回”，新手很难从警告直接跳到修复方案，这个技能把"看懂警告 → 写出正确 @spec → 改对代码"这条链路补全。
  • 核心能力：基本/复杂/泛型类型规范写法、四类高频警告的成因与修法、联合类型与不透明类型/远程类型的建模方式，以及 mix dialyzer 的格式化、解释与单文件检查技巧。
  • 使用方式：它属于由 AI 助手在识别到 Dialyzer 相关任务时自动匹配的能力包，用户不需要记命令，只要把代码和警告贴进对话、描述目标即可。
  • 适合谁：正在给 Erlang/Elixir 项目补类型规范的后端工程师、做代码评审的 Tech Lead，以及刚接触 Dialyzer"成功类型"模型、被误报困扰的开发者。

该技能叫什么？如何下载安装 AI 技能提升开发效率？

这个技能的中文名是「Erlang/Elixir代码类型分析技能Skill」，英文名是 dialyzer-analysis，技能 ID 为 13875。从技能详情来看，它被标注为"用户可调用: false"，允许工具列表为空——这意味着它不是一个需要你手动敲命令调起的独立工具，而是一个由 AI 助手在识别到相关任务时自动加载的知识型能力包。你描述"帮我看看这段 Elixir 代码的 Dialyzer 警告怎么修"，它就会被匹配进来提供分析。

它要解决的问题非常具体：Erlang/Elixir 是动态类型语言，Dialyzer 基于"成功类型"（success typing）做推断，理论上不会误报，但它的输出对人不友好。一条"模式匹配不完整"的警告背后，可能是 case 少了分支，也可能是 @spec 写错了；一条"函数没有局部返回"的警告，只需补一个 no_return() 规范就能消除。没有经验的人容易陷入两个极端：要么无视全部警告，要么为了消警告把类型全写成 any()，结果类型信息形同虚设。这个技能的价值就是给出中间路线——用更严格的类型代替 any()，用规范记录假设，逐步收敛警告。

关于一键安装 AI 技能提升开发效率的思路，通用做法如下（具体命令、下载地址与入口以官方说明为准）：

  1. 确认安装前提：你的 AI 编程助手需要支持"技能 / 插件 / 能力包"这类扩展机制；同时本地应有可运行的 Erlang/OTP 与 Elixir 环境，否则技能分析出的结论你无法验证。
  2. 获取技能包：通过官方技能市场、插件仓库或组织内部下发的技能包获取 dialyzer-analysis，注意核对技能 ID 13875 与英文名，避免装错同名技能。
  3. 放入技能目录并启用：多数客户端支持把技能包导入到指定的 skills / plugins 目录，或在设置面板中开启。导入后通常需要重启客户端或刷新会话，让技能索引重新加载。
  4. 验证是否生效：新开一个对话，贴一段带 Dialyzer 警告的 Elixir 代码（例如一个缺分支的 case），询问"这个警告的原因和修法"。如果回答能指出缺失的匹配分支、并给出补全后的代码和 @spec 建议，说明技能已正常加载；如果回复泛泛而谈、没有任何 Erlang/Elixir 术语，则需要检查技能是否被正确索引。

需要提醒的是：该技能本身不直接执行 dialyzer 命令（允许工具为空），它提供的是分析判断与修复方案。真正跑分析仍需你在本地用 mix dialyzer 完成，两者是"AI 解读 + 本地执行"的配合关系。

该技能的主要功能和特点

  • 类型规范书写指导：覆盖从基础规范 @spec add(integer(), integer()) :: integer()，到复杂类型（如用 %{id: pos_integer(), name: String.t(), role: :admin | :user | :guest} 描述结构体），再到泛型类型 @spec filter_list([t], (t -> boolean())) :: [t] when t: any() 的完整写法。
  • 四类高频警告的定向修复：针对"模式匹配覆盖不全"“函数没有局部返回”“返回值未被匹配”"未知函数"这四类最常见警告，各自给出错误示例与修复后代码，可直接对照修改。
  • 类型分析模式库：提供联合类型（:ok | {:ok, any()} | {:error, String.t()}）、不透明类型（@opaque，用于隐藏内部状态结构）、远程类型（如 Plug.Conn.t()、Date.t()）三种建模思路，帮助在"暴露太多"和"信息不足"之间取舍。
  • 讲清"成功类型"这个反直觉概念：明确 Dialyzer 推断的是"函数可以成功执行的内容"，与传统类型系统不同——它可能漏掉一些错误，但理论上不产生误报。理解这一点，才不会把"没报警告"误当成"代码绝对正确"。
  • 可执行的调试命令：mix dialyzer --format dialyzer 输出原始格式、mix dialyzer --explain 解释警告成因、mix dialyzer lib/my_module.ex 只检查指定文件，方便在大项目里做增量排查。
  • 与普通工具相比强在哪：mix dialyzer 只告诉你"哪里可能有问题"，Code Review 只告诉你"这段写得不好看"，而这个技能把两者之间的空白填上了——它给出的是带类型签名的、可直接粘贴回代码库的修复方案，并且解释为什么这样改，而不是让你照抄。

如何使用该技能？

由于技能由 AI 助手自动匹配，使用方式本质是"用自然语言把上下文喂给它"。推荐按以下步骤操作：

第 1 步：准备最小可复现上下文。 不要只贴一行警告。至少提供：出问题的函数完整代码、对应的 @spec（如果有）、Dialyzer 的原始警告文本，以及你的 Erlang/OTP 与 Elixir 版本。

输入示例：

这段代码 Dialyzer 报了 "The pattern 'ok' can never match since previous clauses completely covered the type 'error'"：

@spec fetch_config(atom()) :: :ok | :error
def fetch_config(key) do
  case Application.fetch_env(:my_app, key) do
    {:ok, _} -> :ok
    :error -> :error
  end
end

第 2 步：明确你的目标。 是"消掉警告"、“补全类型规范”，还是"重构让类型推断更准"？目标不同，技能给出的建议方向也不同。

第 3 步：读取技能给出的分析。 正常情况下，输出会包含三部分：警告的真实成因、修正后的代码（含 @spec）、以及为什么这样改。例如针对上面的例子，它会指出 @spec 的返回类型与实际返回的 :ok | :error 存在差异，需要让规范与实现对齐。

第 4 步：在本地验证修改。 把建议改动应用后，运行：

mix dialyzer --format dialyzer

如果想只验证单个文件，用 mix dialyzer lib/my_module.ex；如果警告仍然存在但看不懂，用 mix dialyzer --explain 让 Dialyzer 输出更详细的推断过程，再把这部分输出贴回对话继续追问。

第 5 步：按最佳实践迭代。 技能给出的顺序建议是：先从核心公共 API 开始加规范 → 优先用具体类型而非 any() → 用规范把隐含假设写成文档 → 确保规范与真实行为一致 → 逐批修复而非一次全改。这个顺序很重要，一次性给整个老项目加 @spec 往往会引入大量新警告。

输出说明：典型输出是"诊断 + 代码块 + 说明"三段式。需注意，技能的判断基于你提供的代码片段，如果实际项目中还有宏展开、行为（behaviour）回调等上下文，务必一并提供，否则结论可能有偏差。

同类型竞品对比分析

方案名称 定位 核心功能 安装/使用门槛 适用场景 优势与不足
dialyzer-analysis 技能 AI 辅助的类型分析知识包 解读警告成因、生成修复代码与 @spec、提供类型建模模式与调试命令建议 低：接入 AI 助手后在对话中描述问题即可，无需额外配置 警告看不懂、不知道该写什么类型、需要快速产出修复方案 优势是能解释"为什么"并给出可粘贴的代码；不足是不直接执行分析，结论依赖你提供的上下文完整度
Dialyzer + dialyxir（原生方案） 官方静态分析工具链 基于成功类型推断做全项目类型检查，输出警告列表 中：需配置依赖、首次构建 PLT 耗时较长 CI 中做类型门禁、长期维护的项目 优势是权威、无第三方依赖；不足是警告文本抽象，缺少修复建议，学习成本高
Gradualizer Erlang 生态的渐进式类型检查器 依据 -spec 做更接近传统类型系统的检查 中高：需单独引入，对规范完备度要求更高 规范覆盖率高、希望更早发现类型错误的 Erlang 项目 优势是检查更主动；不足是生态与 Elixir 结合度不如 Dialyzer，规范不全时噪音较多
Credo Elixir 代码风格与一致性检查工具 风格规范、复杂度提示、部分代码异味检测 低：作为 Mix 依赖引入即可运行 代码评审前的自动化规范检查 优势是上手快、规则可配置；不足是基本不涉及类型层，无法替代 Dialyzer 的类型分析

选择建议：把 Dialyzer + dialyxir 作为基线（它是这个技能的分析对象），把 本技能作为解读与修复加速器，把 Credo 作为风格层补充。如果你的项目类型规范已经非常完整、且希望获得更严格的前置检查，可以再评估 Gradualizer。

该技能的典型应用场景与实际体验情况

场景一：老项目首次接入 Dialyzer，警告多到无从下手。 一位维护三四年历史 Elixir 项目的后端工程师，第一次跑 mix dialyzer 后拿到几百条警告，完全不知道先改哪个。他的做法是把警告按类型分组（模式匹配、返回值、未知函数），先挑"未知函数"这一组交给技能分析——因为这类警告往往意味着真实缺陷。技能会提示用 Code.ensure_loaded?/1 配合 function_exported?/3 做防御式调用，或确认模块是否漏了依赖声明。 实际体验：上手几乎零成本，因为不需要学新工具，只要会描述问题。效果最明显的是"从警告到修复"的转化速度；注意事项是不要一次性把几百条警告全贴进去，分组、分批处理，回答质量和可操作性都会更高。

场景二：补 @spec 时不确定该用多严的类型。 一位给核心模块补类型规范的中级开发者，纠结 get_user/1 的参数该写 integer() 还是 pos_integer()，返回值该不该加入错误分支。技能给出的建议是先按真实行为建模为 {:ok, User.t()} | {:error, atom()}，再考虑用 pos_integer() 收紧参数，并用规范把"ID 必须为正"这个隐含假设显式记录下来。 实际体验：这类问题的回答质量取决于你给的上下文。如果只贴函数签名，技能只能给通用建议；如果连调用方和数据库层一起贴，它才能判断收紧类型后会不会在别处引发新警告。建议养成"贴调用链"的习惯。

场景三：遇到"函数没有局部返回"这类看起来莫名其妙的警告。 一位开发者写的函数只有 raise，被 Dialyzer 提示没有正常返回路径，他一度以为要加一个假的返回值。技能直接指出正确做法是补 @spec always_raises :: no_return()，让规范告诉 Dialyzer"这个函数本来就不返回"。 实际体验：这是最能体现"知识型技能"价值的场景——答案很短，但没人事先知道。类似的知识点还有 @opaque 用于隐藏内部状态、@type 联合类型用于收敛 case 分支，都属于"知道就一秒、不知道就卡一天"的类型。

场景四：Code Review 时快速判断一段代码的类型风险。 Tech Lead 在评审一个新模块，看到某处 case 只处理了 :ok 分支，怀疑会漏 :error。他把片段交给技能，确认这确实是典型的"模式匹配不完整"，并拿到了补全 _ -> :unknown 兜底分支的写法。 实际体验：作为评审辅助非常顺手，但要注意技能是基于片段的静态判断，不能替代真实的 mix dialyzer 执行。最终是否真的消除警告，仍要以本地运行结果为准。

该技能能为用户带来的价值

第一，把"看得见但看不懂"的警告变成可执行动作。 Dialyzer 的警告从不缺，缺的是"这条警告对应哪一行、该怎么改"。技能提供的四类高频警告对照表，本质上是一份"警告 → 修法"的速查表，让开发者不必每次都去翻文档或在论坛里搜同类问题。

第二，降低类型规范的学习门槛。 对刚接触 Erlang/Elixir 的开发者来说，@spec、@type、@opaque、when t: any() 这些语法和它们背后的语义模型是一道坎。技能用"错误示例 + 修复后代码"的成对呈现方式，比单纯读语法文档快得多——你看到的不是语法定义，而是"这段代码为什么错、改成什么才对"。

第三，纠正对 Dialyzer 的错误预期。 "成功类型"这个概念反直觉：没有警告不等于代码绝对正确，报警也不等于一定有 bug。技能把这一点讲在前面，能帮团队避免两种常见误用——把 Dialyzer 当成完备的单元测试替代品，或者因为"报了几个查不出的警告"就整体放弃类型检查。

第四，形成可持续的类型治理路径。 技能给出的五条最佳实践（从核心模块开始、用严格类型、文档化假设、测试规范、迭代修复）本身就是一个可落地的工作流。团队可以据此制定规范：新代码必须带 @spec、禁止无理由使用 any()、CI 中把 Dialyzer 设为门禁。长期看，类型规范完备度提升后，IDE 补全、重构安全性、新人理解成本都会同步受益。

第五，把类型知识沉淀到对话里。 相比"某位资深同事口头告诉你"，技能输出的分析可以被复制进 PR 描述、团队 wiki 或代码注释，成为可检索的组织知识。

常见问题 FAQ

Q1：这个技能怎么安装？需要付费吗？ 它属于 AI 助手的技能/能力包，通常通过官方技能市场、插件仓库或组织内部下发获取，导入后在客户端启用并刷新会话即可。具体下载入口、命令与是否收费，以官方说明为准。安装前建议确认本地已有 Erlang/OTP 与 Elixir 环境，便于验证分析结论。

Q2：技能 ID 是 13875，但我看到它标注"用户可调用: false"，那我到底怎么用它？ "用户可调用: false"意味着你不需要（也不能）像调用函数那样手动唤起它，它由 AI 助手在识别到 Dialyzer 相关任务时自动加载。你只需在对话中贴出代码、警告文本和你的目标，正常情况下技能就会参与回答。

Q3：它能直接帮我跑 mix dialyzer 吗？ 不能。该技能的允许工具列表为空，它提供的是分析判断与修复方案，不执行外部命令。你需要自己在本地运行 mix dialyzer、mix dialyzer --explain 或 mix dialyzer lib/my_module.ex，再把结果贴回对话继续分析。两者配合使用效果最好。

Q4：和直接用 Dialyzer、Credo 相比，它值得用吗？ 它们不是替代关系。Dialyzer 负责"发现问题"，Credo 负责"风格一致性"，本技能负责"解释问题并给出修法"。如果你已经能熟练阅读 Dialyzer 警告并自己写出准确的 @spec，它的边际价值有限；如果你正被警告卡住、或团队里多数人对类型规范不熟，它的提速效果会非常明显。

Q5：为什么我改完代码，Dialyzer 还是报同样的警告？ 常见原因有三类：一是改了实现但没同步更新 @spec，导致规范与真实行为不一致；二是项目 PLT 未更新，需要在依赖变更后重建；三是只检查了单个文件而全项目仍存在关联问题。建议先用 mix dialyzer --explain 看清 Dialyzer 的推断依据，再把完整输出贴回对话定位。