LintLang · 简体中文2026-09-29 核对

LintLang 简体中文快速上手

英文文档是权威版本：本页只是精简的中文入门，若与英文内容不一致，以英文为准。

本页不写版本号：已发布版本以 PyPI 页面和 lintlang --version 的输出为准。命令与标识符保持原样，不翻译。

§ 01

LintLang 是什么

LintLang 是一个本地运行、结果确定的静态检查工具，检查对象是交给 AI 智能体的指令和工具接口。它会在智能体运行之前，指出工具选择有歧义、输出格式混杂、schema 缺口、缺少边界约束等配置问题。

它能在你已有的文件里找到受支持的、面向智能体的内容，包括：

典型问题包括：

工具描述有歧义：同级工具功能重叠，模型没有明确理由选其一
缺少边界：重试、循环或工具调用没有明确的停止或进展条件
schema 不匹配：缺少必填字段、参数含义不清
输出格式混杂与优先级缺失：一个提示词里提到不止一种输出格式（只要识别到两种格式就会报告，即使各自限定了适用场景），以及较长的指令列表没有说明优先级；LintLang 不检测两条指令之间的语义矛盾，例如「总是做 X」与「绝不做 X」并存
SKILL.md 缺陷：元数据缺失或无效、使用条件不清、技能名与目录名不一致
上下文与消息错误：过期的项目引用、无限期持久化、角色格式错误、工具消息顺序断裂
内嵌逻辑：受支持的 Python 提示词、字面量工具定义、部分流水线阈值

§ 02

§ 03

需要 Python 3.10+。

不安装，直接运行一次：

uvx lintlang scan .

用 pip 安装：

pip install lintlang
lintlang scan .

macOS 上用 Homebrew：

brew install hermes-labs-ai/tap/lintlang
lintlang scan .

§ 04

在项目目录下运行上面的 uvx lintlang scan .，或指定单个配置来源：

uvx lintlang scan AGENTS.md
uvx lintlang scan SKILL.md
uvx lintlang scan agent.yaml

如何解读结果：

每条结果都会说明 LintLang 实际检查了什么。
没有识别到任何面向智能体的结构的文件不会被计为 PASS：目录扫描会把它列为已跳过，单个文件扫描会报错，并提示可用 --allow-uninspected。Markdown 文件会被当作指令文本来检查。
工具之间的比较只发生在同一个被解析的输入内；扫描目录时，不会把不同文件里的工具合并到同一个选择命名空间。
默认情况下，检查结果仅供参考，不会让命令失败。
扫描干净只表示：所选的静态检查在被识别的内容中没有发现所覆盖的缺陷。

§ 05

遇到 HIGH 或 CRITICAL 级别的发现时让命令失败：

lintlang scan . --fail-on fail

把 MEDIUM 级别也纳入门禁：

lintlang scan . --fail-on review

生成固定版本的 GitHub Actions 工作流，扫描整个仓库目录：

lintlang init --github --path .

生成的 Action 默认对 HIGH 或 CRITICAL 级别的发现设置门禁。如果 CI 只需检查某一个配置来源，请改用更窄的路径。请在仓库根目录运行该命令：工作流文件会写到所在 Git 仓库的根目录。

对于已有历史发现的仓库，可以先记录一份经过评审的基线：

lintlang scan . --write-baseline .lintlang-baseline.json

之后只对新增或变更的发现设置门禁：

lintlang scan . --baseline .lintlang-baseline.json --fail-on review

§ 06