代理脚本

此文件夹收集了 Sweetistics 的护栏辅助工具，以便在其他仓库中轻松复用，或在入职培训期间共享。除非另有说明，此处的所有内容均于 2025 年 11月 8 日从 /Users/steipete/Projects/sweetistics 原样复制而来。

额外的技能（于 2025 年 12 月 31 日复制）来自 @Dimillian 的公共 Dimillian/Skills 仓库：

• skills/swift-concurrency-expert
• skills/swiftui-liquid-glass
• skills/swiftui-performance-audit
• skills/swiftui-view-refactor

与其他仓库同步

• 将此仓库视为共享护栏辅助工具的规范镜像。每当您在任何仓库中编辑 scripts/committer 或 scripts/docs-list.ts 时，请将更改复制到这里，然后再反向应用到所有包含相同辅助工具的其他仓库，以确保它们字节完全一致。
• 当有人提到“同步代理脚本”时，请拉取此处的最新更改，确保下游仓库拥有指针式的 AGENTS.MD 文件，将任何辅助工具的更新复制到位，并在继续之前解决差异。
• 保持每个文件无依赖且可移植：这些脚本必须能够在各个仓库中独立运行。请勿添加 tsconfig 路径别名、共享源代码文件夹或其他任何 Sweetistics 特有的导入——应内联小型辅助函数，或仅复制所需的最少代码，以使镜像保持自包含。

指针式 AGENTS

• 共享的护栏文本现在仅存在于此仓库中：AGENTS.MD（共享规则 + 工具列表）。
• 每个使用仓库的 AGENTS.MD 都简化为指针行：“在进行任何操作之前，请阅读 ~/Projects/agent-scripts/AGENTS.MD（如果不存在则跳过）。” 如果确实需要，可在该行之后添加仓库特定的规则。
• 请勿再将 [shared] 或 <tools> 块复制到其他仓库。相反，应保持此仓库的更新，并让下游工作区在开始工作时重新读取 AGENTS.MD。
• 更新共享说明时，编辑 agent-scripts/AGENTS.MD，将更改镜像到 ~/AGENTS.MD（Codex 全局），并让下游仓库继续引用该指针。

提交者辅助工具 (scripts/committer)

• 是什么： 一个 Bash 辅助工具，用于精确暂存您列出的文件，强制提交信息不为空，并创建提交。

文档列表工具 (scripts/docs-list.ts)

• 是什么： 一个 tsx 脚本，遍历 docs/ 目录，强制执行 front-matter（summary、read_when），并打印由 pnpm run docs:list 输出的摘要。其他仓库可以将相同的命令集成到其入职流程中。
• 二进制构建： bin/docs-list 是编译后的 Bun CLI；在编辑 scripts/docs-list.ts 后，通过 bun build scripts/docs-list.ts --compile --outfile bin/docs-list 重新生成。

浏览器工具 (bin/browser-tools)

• 是什么： 一个独立的 Chrome 辅助工具，灵感来源于 Mario Zechner 的文章《如果你不需要 MCP 会怎样？》。它可以启动或检查启用了 DevTools 的 Chrome 配置文件，粘贴提示信息，截取屏幕截图，并终止多余的辅助进程，而无需完整的 Oracle CLI。
• 使用方法： 建议使用编译后的二进制文件：bin/browser-tools --help。常用命令包括 start --profile、nav <url>、eval '<js>'、screenshot、search --content "<query>"、content <url>、inspect 和 kill --all --force。
• 重建： 该二进制文件未被 Git 跟踪。可通过 bun build scripts/browser-tools.ts --compile --target bun --outfile bin/browser-tools 重新生成（需要 Bun），并将临时的 node_modules/package.json 排除在仓库之外。
• 可移植性： 该工具没有任何仓库特定的依赖项。您可以根据需要将脚本或二进制文件复制到其他自动化项目中，并保持与下游分支的同步。它能够检测通过 --remote-debugging-port 和 --remote-debugging-pipe 启动的 Chrome 会话，因此无论哪种方式，都可以正常列出和终止进程。

同步期望

• 此仓库是 mcporter 及其他 Sweetistics 项目中使用的护栏辅助工具的规范镜像。每当您在其他仓库中编辑 scripts/committer、scripts/docs-list.ts 或相关护栏文件时，都应立即将更改复制回此处（反之亦然），以确保代码字节完全一致。
• 当有人要求“同步代理脚本”时，请更新此仓库，将其与当前项目进行比较，并在继续之前解决双方的差异。

@steipete 代理说明（指针式流程）

• 护栏的完整副本只有 agent-scripts/AGENTS.MD 和 ~/AGENTS.MD。下游仓库应包含指针行以及任何仓库本地的补充内容。
• 在同步扫描过程中：拉取最新的 agent-scripts，确保每个目标仓库的 AGENTS.MD 文件顶部包含指针行，在其下方添加任何仓库本地的备注，并根据需要更新辅助脚本。
• 如果某个仓库需要自定义说明，务必将其与指针明确分开，以免未来的同步扫描覆盖本地内容。
• 对于子模块（Peekaboo/*），应在每个子模块内部重复检查指针，推送这些更改，然后在父仓库中更新子模块的 SHA 值。
• 除非特别要求，否则请跳过实验性仓库（例如 poltergeist-pitui）。

agent-scripts 快速上手指南

agent-scripts 是 Sweetistics 项目的一套标准化 AI 辅助工具集（Guardrail Helpers），旨在为多个仓库提供可复用的脚本、浏览器自动化工具以及统一的 Agent 指令规范。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统: macOS 或 Linux (Windows 需配合 WSL 使用)。
• 运行时依赖:
  • Bun: 用于编译和运行 TypeScript 脚本及二进制文件（推荐）。
  • Node.js: 如果未安装 Bun，需确保安装了 Node.js 和 tsx。
  • pnpm: 部分脚本依赖 pnpm 运行。
• 浏览器: Google Chrome (用于 browser-tools 功能)。
• Shell: Bash 或 Zsh (用于 committer 脚本)。

提示：国内开发者若下载 Bun 较慢，可使用国内镜像源安装：

curl -fsSL https://bun.sh/install | bash
# 若上述命令超时，可尝试配置 npm 镜像后安装 bun 包
npm config set registry https://registry.npmmirror.com
npm install -g bun

安装步骤

由于该工具库设计为“规范镜像（Canonical Mirror）”，通常通过克隆仓库并集成到现有项目中使用。

1. 克隆仓库

   git clone <your-repo-url>/agent-scripts.git
   cd agent-scripts
   

2. 安装依赖

   pnpm install
   

3. 编译二进制工具 为了获得最佳性能，需要将 TypeScript 脚本编译为独立二进制文件。

   • 编译文档列表工具 (docs-list)：

     bun build scripts/docs-list.ts --compile --outfile bin/docs-list
     

   • 编译浏览器自动化工具 (browser-tools)：

     bun build scripts/browser-tools.ts --compile --target bun --outfile bin/browser-tools
     

4. 集成到现有项目 (同步规范) 若要在其他项目中使用，需执行“指针式”同步：

   • 将 scripts/ 和 bin/ 目录复制到目标项目。
   • 在目标项目的 AGENTS.MD 文件首行添加以下指针（替换为您的实际路径）：

     READ ~/Projects/agent-scripts/AGENTS.MD BEFORE ANYTHING (skip if missing).
     

   • 确保目标项目中的脚本文件与此仓库保持字节级一致（byte-identical）。

基本使用

1. 提交助手 (Committer Helper)

用于严格规范 Git 提交行为，确保只暂存指定文件且提交信息非空。

# 用法示例：暂存特定文件并提交
./scripts/committer file1.ts file2.md -m "feat: update documentation"

2. 文档列表生成 (Docs Lister)

遍历 docs/ 目录，检查 Front-matter（如 summary, read_when），并输出摘要列表。常用于新员工入职流程。

# 运行脚本查看文档摘要
pnpm run docs:list

# 或直接使用编译后的二进制文件
./bin/docs-list

3. 浏览器自动化工具 (Browser Tools)

独立的 Chrome 辅助工具，无需完整的 MCP 客户端即可启动调试配置文件、执行 JS、截图或检索内容。

• 查看帮助

  ./bin/browser-tools --help
  

• 常用命令示例

  • 启动特定配置的 Chrome 进程：

    ./bin/browser-tools start --profile "DevProfile"
    

  • 导航至指定 URL：

    ./bin/browser-tools nav "https://example.com"
    

  • 执行 JavaScript 代码：

    ./bin/browser-tools eval "document.title"
    

  • 截取屏幕快照：

    ./bin/browser-tools screenshot
    

  • 搜索页面内容：

    ./bin/browser-tools search --content "keyword"
    

  • 强制关闭所有残留的助手进程：

    ./bin/browser-tools kill --all --force
    

注意：browser-tools 支持检测通过 --remote-debugging-port 和 --remote-debugging-pipe 启动的 Chrome 会话。