# LintLang

> 仓库地址：https://github.com/roli-lpci/lintlang
> 作者/组织：roli-lpci
> 成熟度：beta
> 分析日期：2026-04-15

## 一句话总结
一个面向 AI agent 配置文件的静态分析工具，在编写阶段检测 tool description 歧义、schema 不匹配、role confusion 等"语言 bug"，无需 LLM 调用。

## 项目定位与架构
LintLang 的核心观点是："Most AI agent bugs aren't code bugs — they're language bugs." 它对标 eslint 在 JavaScript 生态中的角色，专注于 agent 配置的静态结构检查，与 promptfoo（runtime eval）、guardrails-ai（output validation）、NeMo（live dialogue rails）形成差异化定位。

架构简洁：基于 Python 3.10+，唯一依赖是 pyyaml，零网络调用，零 API 依赖。自动检测文件格式（YAML/JSON/plain text），应用模式匹配规则。

## 关键技术特性
- **七个结构化检测器（H1-H7）**：tool description 歧义、缺失约束、schema 不匹配、context boundary 侵蚀、implicit instruction 失败、template 违规、role confusion
- **Verdict 机制**：PASS/REVIEW/FAIL 判定，而非数值评分
- **具体修复建议**：每个发现附带具体重写方案
- **CI/CD 集成**：`--fail-on fail`（CRITICAL/HIGH 退出码 1）、`--fail-on review`（MEDIUM+ 退出码 1）
- **多格式支持**：YAML、JSON、plain text、auto-detection
- **Programmatic API**：`from lintlang import scan_file, compute_verdict`

## 设计亮点与创新
"语言 bug"的概念定位精准——agent 配置中的歧义、遗漏确实是导致 agent 行为不可预测的主要原因。将这一问题类比为代码 linting 非常直觉。Verdict-based 判定比数值评分更适合 CI/CD pipeline 中的二元决策。Apache 2.0 许可也利于企业采用。

## 局限性与风险
仅能做静态结构分析，无法评估运行时行为。检测规则基于模式匹配，对复杂语义问题的覆盖有限。目前七个检测器能否覆盖实际 agent 配置中的主要问题模式需要实践验证。

## 与生态系统的关联
属于 Hermes Labs 生态的质量工具链，可与 hermes-council（运行时对抗性评估）互补——lintlang 在配置编写阶段检查，hermes-council 在运行时通过多视角辩论评估。可集成到任何使用 YAML/JSON 配置的 agent 框架的 CI/CD pipeline 中。