agent-scripts 是由开发者 Peter Steinberger（steipete）发起的一个开源项目，旨在为其多个代码仓库提供统一、可复用的 AI 代理（Agent）脚本和护栏（Guardrail）配置。该项目作为一个“规范镜像（Canonical Mirror）”，解决了在不同项目中重复编写和维护 AI 辅助脚本的问题。

核心内容包括：

1. 同步机制：确立了以该仓库为准的同步原则，要求所有下游项目通过“指针文件”引用此处的规则，确保指令的一致性。
2. 核心工具集：提供了包括 committer（自动化提交）、docs-list（文档管理）以及功能强大的 browser-tools（基于 Chrome 的浏览器自动化工具）在内的多种实用脚本。
3. AI 技能集成：除了作者自研的 Sweetistics 护栏助手，还集成了来自社区（如 Dimillian）的 Swift 并发、SwiftUI 性能审计等高级 AI 技能。
4. 便携性设计：强调脚本的独立性，不依赖特定项目的复杂配置，确保在不同环境下均能开箱即用。

该项目为开发者构建高效、标准化的 AI 辅助开发工作流提供了一套成熟的参考实现。

---

项目定位与同步哲学

agent-scripts 的核心定位是作为多个代码仓库之间共享 AI 代理脚本的“中央处理器”。在 AI 辅助开发的背景下，开发者往往需要在不同项目中使用相似的指令集、约束规则（Guardrails）和辅助工具。为了避免代码冗余和规则冲突，该项目要求将其视为“规范镜像”。

同步原则：

• 字节级一致性：任何对 scripts/committer 或 scripts/docs-list.ts 等核心脚本的修改，必须首先在此仓库完成，然后同步到所有下游仓库，确保各处代码完全一致。
• 独立性要求：所有脚本必须保持“无依赖”和“可移植”。这意味着脚本内部不能包含特定项目的路径别名（如 tsconfig 路径）或特定的源码引用。如果需要某些功能，应采用内联小型助手函数或复制代码的方式，以保证脚本在任何仓库中都能独立运行。
• 同步操作规范：当执行“同步代理脚本”指令时，开发者需拉取此仓库最新代码，检查下游仓库的指针文件，并调和任何潜在的差异。

指针式 AGENTS 配置管理

为了解决大型 AI 指令文件（如 AGENTS.MD）在多个仓库中难以维护的问题，本项目引入了“指针式”管理模式。

核心逻辑：

• 单一事实来源：完整的共享规则和工具列表仅保存在 agent-scripts/AGENTS.MD 以及用户的全局配置 ~/AGENTS.MD 中。
• 引用机制：下游仓库的 AGENTS.MD 文件被极简为一个指针行：READ ~/Projects/agent-scripts/AGENTS.MD BEFORE ANYTHING。AI 代理在启动时会根据此行指令先读取中央规则。
• 局部扩展：如果某个项目有特殊需求，可以在该指针行之后添加特定规则。这种做法既保证了通用规则的统一更新，又保留了项目的灵活性，且在同步过程中不会误删局部配置。
• 禁止冗余：明确禁止将共享的 [shared] 或 <tools> 块直接复制到其他仓库，强制通过引用来维持整洁。

核心辅助工具详解

项目内置了几个关键的自动化工具，涵盖了从代码提交到浏览器交互的多个维度：

1. Committer Helper (scripts/committer)： 这是一个 Bash 脚本，旨在规范化 Git 提交流程。它强制要求列出具体文件并撰写非空的提交信息，从而避免 AI 代理生成模糊或错误的提交记录。

2. Docs Lister (scripts/docs-list.ts)： 基于 tsx 编写，用于管理项目文档。它会遍历 docs/ 目录，强制执行 Front-matter 规范（如必须包含 summary 和 read_when 字段）。通过 pnpm run docs:list，AI 可以快速了解项目文档概况。该工具还支持通过 Bun 编译为二进制文件以提高执行效率。

3. Browser Tools (bin/browser-tools)： 这是一个受“无需 MCP（Model Context Protocol）”理念启发的 Chrome 助手。它允许 AI 代理直接控制 Chrome 配置文件、导航网页、执行 JavaScript、截屏以及抓取网页内容。

   • 功能丰富：支持 start（启动 profile）、nav（导航）、eval（执行脚本）、screenshot（截屏）和 search（内容搜索）等命令。
   • 技术特性：能够检测通过远程调试端口或管道启动的 Chrome 会话，具备强大的进程管理能力（如强制杀死残留进程）。

AI 技能与扩展

项目不仅包含基础脚本，还集成了一系列针对特定技术栈的高级 AI 技能（Skills），这些技能主要来源于作者的 Sweetistics 项目以及社区贡献。

集成技能包括：

• Swift 并发专家：提供关于 Swift Concurrency 的深度指导。
• SwiftUI 性能审计：用于检查 SwiftUI 视图的渲染性能。
• 视图重构与 Liquid Glass：针对 SwiftUI 界面优化和重构的专项指令。

这些技能以 Markdown 或脚本形式存在于 skills/ 目录下，使得 AI 代理在处理相关代码时能够具备更专业的领域知识。

---

问答

问：为什么这个项目强调“指针式”引用而不是直接复制代码？ 答：为了确保“单一事实来源”。直接复制代码会导致不同仓库间的规则随时间产生偏差，而指针式引用确保了只要中央仓库更新，所有关联项目都能立即获得最新的 AI 指令。

问：browser-tools 与常见的 MCP 插件有什么区别？ 答：它更轻量且独立。它不需要复杂的 MCP 服务器架构，而是通过简单的命令行界面直接与 Chrome 的调试接口交互，更易于集成到自定义的自动化脚本中。

问：如何确保脚本在不同仓库中都能运行？ 答：项目强制要求脚本“依赖无关（Dependency-free）”。脚本内不使用项目特定的导入或复杂的构建配置，所有必要的微型助手函数都会被内联到脚本中。

问：如果我需要在某个特定项目里增加额外的 AI 规则怎么办？ 答：在项目的 AGENTS.MD 中，先写上指向中央仓库的引用行，然后在该行下方添加项目特有的规则。同步脚本在更新时会保留这些局部修改。

问：这个项目支持哪些编程语言？ 答：从代码构成看，主要使用 TypeScript (44.1%)、Python (22.1%)、JavaScript (21.1%) 和 Shell (12.7%)，涵盖了主流的脚本编写语言。