fchastanet/ai-linter

# AI Linter [](https://opensource.org/licenses/MIT) [](https://www.python.org/downloads/) [](https://www.python.org/downloads/) [](https://www.python.org/downloads/) [](https://github.com/fchastanet/ai-linter/actions/workflows/ci.yml) [](https://codecov.io/github/fchastanet/ai-linter) - [1. 目的](#1-purpose) - [2. 功能](#2-features) - [3. 安装](#3-installation) - [3.1. 从 PyPI 安装](#31-from-pypi) - [3.2. 从源码安装](#32-from-source) - [3.3. Pre-commit 集成（推荐）](#33-pre-commit-integration-recommended) - [3.4. Vscode 任务集成](#34-vscode-task-integration) - [4. 命令帮助](#4-command-help) - [5. 使用方法](#5-usage) - [5.1. 基本用法](#51-basic-usage) - [5.2. 高级选项](#52-advanced-options) - [5.3. 配置文件](#53-configuration-file) - [6. 验证规则](#6-validation-rules) - [6.1. 代码片段大小验证](#61-code-snippet-size-validation) - [6.2. 未引用资源文件检测](#62-unreferenced-resource-file-detection) - [6.3. Prompt 和 Agent 目录验证](#63-prompt-and-agent-directory-validation) - [6.4. AGENTS.md 要求](#64-agentsmd-requirement) - [6.5. Skills 验证](#65-skills-validation) - [6.6. Agents 验证](#66-agents-validation) - [6.7. 允许的 Frontmatter 属性](#67-allowed-frontmatter-properties) - [6.8. 错误代码](#68-error-codes) - [7. 常见问题](#7-faq) - [8. 退出码](#8-exit-codes) - [9. 开发](#9-development) - [9.1. 安装](#91-installation) - [9.2. Pre-commit](#92-pre-commit) - [9.3. 开发工作流](#93-development-workflow) - [9.4. Pytest 常用命令](#94-pytest-cuseful-commands) - [10. 灵感来源](#10-inspiration) - [11. 贡献指南](#11-contributing) - [12. 许可证](#12-license) ## 1. 目的 AI Linter 是一款专门为 AI 技能和 Agent 配置设计的验证工具。它提供全面的代码检查和验证功能，包括： - **AI 技能**：验证 `SKILL.md` 文件，包括 frontmatter、内容长度、token 计数和文件引用 - **AI Agent**：验证 `AGENTS.md` 文件并确保结构正确，不包含 frontmatter - **文件引用**：检查所有引用的文件是否存在且可访问 - **内容质量**：强制限制内容长度和 token 数量，以确保最佳性能 - **项目结构**：验证整体项目组织和文件关系 ## 2. 功能 - 🔍 **全面验证**：验证技能和 Agent，并提供详细的错误报告 - 📊 **Token 计数**：使用 tiktoken 进行准确的 token 计数验证 - 📝 **Frontmatter 解析**：验证技能文件中的 YAML frontmatter - 🚫 **文件引用检查**：确保所有引用的文件存在 - ⚙️ **可配置**：支持 YAML 配置文件 - 🎯 **选择性处理**：可以处理特定目录或自动发现技能 - 📋 **详细日志**：多个日志级别，带有结构化错误报告 - 🔧 **Pre-commit 集成**：易于与 pre-commit 钩子集成 - 📦 **代码片段检测**：警告应该外部化的大型代码块 - 🔗 **未引用文件检测**：确保所有资源文件都在文档中被引用 - 🤖 **Prompt/Agent 验证**：验证 `.github/prompts` 和 `.github/agents` 目录 - 📄 **AGENTS.md 要求**：检查项目级 AI 助手指导 ## 3. 安装 ### 3.1. 从 PyPI 安装 ``` pip install ai-linter ``` ### 3.2. 从源码安装 ``` # 克隆仓库 git clone git@github.com:fchastanet/ai-linter.git cd ai-linter # 安装软件包 pip install . ``` ### 3.3. Pre-commit 集成（推荐） 请参阅 [.pre-commit-hooks.yaml](` - 附件：`` - 代码注释：`source: path/to/file` ### 6.3. Prompt 和 Agent 目录验证 **Prompt 和 Agent 文件验证内容：** - 内容大小（≤ 500 行） - Token 计数（≤ 5000 tokens） - 所有引用的文件必须存在 - 提取并记录工具和技能引用 **配置：** ``` prompt_dirs: - .github/prompts agent_dirs: - .github/agents ``` ### 6.4. AGENTS.md 要求 项目应在根目录中有 `AGENTS.md` 文件，为 AI 助手提供项目上下文和指导。 **配置：** ``` missing_agents_file_level: WARNING # or ERROR, INFO ``` ### 6.5. Skills 验证 - `SKILL.md` 文件必须存在 - 有效的 YAML frontmatter，包含必需的属性 - 内容长度 ≤ 500 行 - Token 计数 ≤ 5000 tokens - 所有文件引用必须存在且可访问 - Frontmatter 必须包含有效的元数据 ### 6.6. Agents 验证 - `AGENTS.md` 文件结构验证 - Agent 文件中不允许使用 frontmatter - 内容长度 ≤ 500 行 - Token 计数 ≤ 5000 tokens - 所有文件引用必须有效 ### 6.7. 允许的 Frontmatter 属性 ``` name: string description: string license: string allowed-tools: array metadata: object compatibility: object ``` ### 6.8. 错误代码 - `code-snippet-too-large`：代码块超过最大行数 - `unreferenced-resource-file`：资源目录中的文件未在任何 markdown 中引用 - `prompt-content-too-long`：文件超过最大行数 - `prompt-token-count-exceeded`：文件超过最大 token 计数 - `agents-file-missing`：在根目录中未找到 AGENTS.md ## 7. 常见问题 - **为什么限制代码片段为 3 行？** 这是可配置的。目的是让 markdown 专注于文档，同时鼓励将代码组织到外部文件中。 - **如果我有很多小型、很少使用的资源文件怎么办？** 创建一个索引文档，列出所有资源及其用途。这满足引用要求并提高可发现性。 - **我可以禁用特定的验证器吗？** 可以，在配置中将严重性设置为 `INFO`，或使用 `--` 跳过目录。 - **如何计算 token？** 如果可用，AI Linter 使用 `tiktoken` 库来估算 token 计数。如果未安装 `tiktoken`，它会回退到 `len(text) // 4` 的启发式方法。实际模型的 token 化可能仍然略有不同，因此限制应作为实用指南而非精确值。 - **如果我的项目很小，需要 AGENTS.md 吗？** 即使是小项目也能从基本文档中受益。最小化的 AGENTS.md 只需几行来解释项目目的。 ## 8. 退出码 - **0**：成功（无错误，警告在限制内） - **1**：失败（发现错误或警告过多） ## 9. 开发 ### 9.1. 安装 ``` # 克隆并安装以进行开发 git clone git@github.com:fchastanet/ai-linter.git cd ai-linter # 以开发模式安装所有开发依赖项 pip install -e ".[dev]" # 设置 pre-commit 钩子 pre-commit install ``` ### 9.2. Pre-commit - ✅ **[.pre-commit-hooks.yaml](.pre-commit-hooks.yaml)** - 供外部使用的钩子定义 - ✅ **[.pre-commit-config.yaml](.pre-commit-config.yaml)** - 本地开发配置，包含： - AI Linter 验证 - Black 代码格式化 - isort 导入排序 - flake8 代码检查 - mypy 类型检查 - bandit 安全扫描 - YAML/Markdown 验证 ### 9.3. 开发工作流 ``` # 设置开发环境 make install-dev # 运行所有检查 make check-all # 测试 linter make validate ``` ### 9.4. Pytest 常用命令 要隐藏覆盖率报告并在断言失败时获取完整输出，请使用： ``` # 选项 1：完全禁用覆盖率 pytest -v --no-cov # 选项 2：在无覆盖率的情况下显示完整断言输出 pytest -v --no-cov --tb=short # 选项 3：最长回溯及完整详情 pytest -v --no-cov --tb=long # 选项 4：回溯中的局部变量 pytest -v --no-cov --tb=long -l # 选项 5：在第一次失败时停止并显示完整输出 pytest -x --no-cov -vv ``` ## 10. 灵感来源 此工具的灵感来自 [Anthropic 的技能验证脚本](https://github.com/anthropics/skills/blob/ef740771ac901e03fbca3ce4e1c453a96010f30a/skills/skill-creator/scripts/quick_validate.py)，并针对更广泛的 AI 开发工作流进行了适配。 ## 11. 贡献指南 欢迎贡献！请随时提交 Pull Request。 ## 12. 许可证 此项目基于 MIT 许可证授权 - 详见 [LICENSE](LICENSE) 文件。

标签：AGENTS.md, Agent配置验证, AI Linter, AI配置管理, Linter, Markdown验证, pptx, pre-commit, SKILL.md, Subfinder, VS Code集成, YAML配置, 云安全监控, 代码验证工具, 令牌限制, 内容长度验证, 前端matter验证, 开发效率, 文件引用检查, 网络可观测性, 逆向工具, 静态分析, 项目质量保证