1实现原理 · 为什么它能做到
环境修复是『证据驱动』而非『重装一切』：先按固定顺序读 AGENTS.md/CLAUDE.md/ONBOARDING/README/manifest/CI，用只读清单脚本推断真实技术栈，再最小修复。
auto-repo-setup/SKILL.md
Use the bundled scripts/check_env.py against the repository root when a Python 3.10+ runner is already available. It detects the declared ecosystem and checks only the relevant toolchain; it does not install dependencies or read secret values.
这里在做什么：把『仓库跑不起来』这类模糊问题收敛成可验证的清单差距——check_env 只查 manifests 声明的工具链是否在 PATH 上，退出码 0/1/2 三态表达 可用/缺失/无法安全检查，作为后续修复与验证的基线。
check_env.py 的探测逻辑是从显式锁文件/清单（uv.lock、package-lock.json、go.mod 等）推断包管理器与运行时，然后跑只读命令保留退出码与 stdout/stderr。
auto-repo-setup/scripts/check_env.py
def detect_toolchains(repo: Path) -> list[ToolRequirement]: """Infer package managers and runtimes from explicit manifests/lockfiles."""
run_cmd 的 docstring 是『Run one read-only command and preserve its three observable outputs.』——所有检测命令 15 秒超时、check=False 强断、捕获三路输出，保证脚本本身不做任何安装/同步/变更。
『最少机制』排序 + hook 门禁：日常启动同步归 AGENTS.md/CLAUDE.md 或自然语言指令，只有『必须在首个 prompt 前发生』且宿主已验证时才装 SessionStart hook，且必须先 dry-run 预览。
auto-repo-setup/SKILL.md
Prefer, in order: direct Agent instruction → project instruction → explicit command → lifecycle hook. A hook is not a more professional version of a sentence.
Workflow D 再叠加两重保险：『Diagnose repeated output first』（先数注册数与触发会话，别凭三条输出推断三个注册）与『Install only after the hook gate passes』（Preview first → --dry-run → 用户确认后同命令去掉 --dry-run）。
init_session_start_hook.py 是受管且幂等的 hook 安装器：只加一个带 [auto-repo-setup] 标记的 SessionStart 条目（matcher startup + echo 引导语），校验 guide 路径、保留无关设置、原子写、可 --remove。
auto-repo-setup/SKILL.md
The bundled initializer is Claude Code-specific and installs only a lightweight startup context nudge. It preserves unrelated settings, adds matcher startup, validates the guide path, writes atomically, and is idempotent.
脚本侧可见同一纪律：MANAGED_MARKER = "[auto-repo-setup]" 标记受管条目；validate_guide 拒绝绝对路径与 '..'，并对 '"'$;&|<>!()% 与反引号字符集（FORBIDDEN_GUIDE_CHARS）抛 ConfigError——从源头防止把用户路径拼进 hook 命令造成注入。
Git 流程是『规则门禁 + 状态解释』而非自动操作：clean 才 ff-only pull；有本地改动或历史分叉时禁止自动 stash/merge/rebase/force，改为解释状态。
auto-repo-setup/SKILL.md
If the working tree is clean, run git pull --ff-only.
Operating principles 同步约束：『Never auto-stash, merge, rebase, force, discard, or overwrite local changes to make setup look successful.』破坏性/公开动作（public push、force push、history rewrite）都需要显式批准。
历史敏感信息清理只做只读候选扫描，修复动作交给人工：sanitize_history.sh 自述『只辅助检查』，SKILL.md 要求扫描结果当候选、绝不未经批准执行改写命令。
auto-repo-setup/scripts/sanitize_history.sh
# 注意：此脚本只辅助检查，最终修复（orphan branch / BFG）需要人工确认后执行。
脚本四段扫描：常见密钥模式（如 sk- 前缀）、个人绝对路径、私有域名、当前工作区，输出问题数与修复建议，--check-only 只读退出。
2核心能力
01只读、栈感知的仓库能力清单（check_env.py，退出码 0/1/2 表达可用/缺失/无法检查）
02根因修复闭环：先录失败命令三路输出→溯源声明源→最小修复→重跑验证→跑真实 smoke/启动命令
03常规 Git 同步（clean 才 pull --ff-only；脏树/分叉只解释不自动处理）
04受管 SessionStart hook 的注册/诊断/移除（幂等、原子写、--dry-run 预览、--remove）
05仓库交接/onboarding 审计：以 onboarding_template.md 为清单补齐缺失的操作契约
06git 历史敏感信息只读扫描（sanitize_history.sh）与公发内容复核指引（pii_guard.md）
07反审查边界：影响安全策略/共享 hook/CI/依赖/破坏性 Git 行为时才派 counter-review，普通 setup 不派审团队
3外部依赖
| Kind | Dependency / Endpoint |
|---|---|
| cli | git |
| cli | python3 / uv |
| cli | sh/bash |
4管控建议与判定依据
建议配套管控措施
面向 Agent
分级或逐次授权，建议在沙箱运行
面向管理者
审批流程、可回滚、全程审计
判定依据（文件路径与关键语句摘要）
- scripts/: 执行本地脚本或命令: auto-repo-setup/scripts/check_env.py
- 本地工作目录: 文件读写与工件输出: init_session_start_hook.py 经用户确认后写仓库内 .claude/settings.json（受管 SessionStart
审计说明： 。自带 stdlib/本地脚本（check_env 只读检测、sanitize_history 只读扫描）+ 写本地配置（.claude/settings.json、.gitignore），零网络外发、零凭证接触（check_env docstring 明示 never reads secret values）。hook 注册虽改动用户配置，但有 dry-run 预览、幂等原子写与 --remove，且 SKILL.md 要求先诊断、用户确认后才装。唯一注意：SKILL 允许 agent 执行 git 提交/推送类操作，破坏性动作须显式批准；sanitize_history 的启发式匹配可能误报漏报，结果只当候选。
5第二遍独立确认
- [ok] check_env.py 只读且不碰 secret — docstring 含『reads secret values』否定句 + 代码仅 git rev-parse/which/shutil.which 探测 + token 扫描零命中。
- [ok] init_session_start_hook.py 行为与 SKILL.md 描述一致（幂等/保留无关设置/原子写） — 脚本 load_settings 校验 JSON 结构并保留 hooks 其余键；update_settings/atomic_write 存在；SKILL.md 原文含『preserves unrelated settings … writes atomically, and is idempotent』同义描述。
- [ok] sanitize_history.sh 永不改写历史 — 脚本头注释『此脚本只辅助检查，最终修复（orphan branch / BFG）需要人工确认后执行』；修复建议仅 echo 输出。
- [ok] Git 门禁（ff-only/不自动 stash/显式批准）有源码依据 — SKILL.md Workflow B 逐条原文存在；Operating principle 4『Never auto-stash, merge, rebase, force, discard, or overwrite local changes…』存在。
- [ok] 无网络外发声明 — scripts/ 三文件 token 扫描仅命中 BFG 文档 URL（输出文案），无任何 fetch/request/curl 调用点。
- [ok] 外部依赖清单（git/python/uv/sh）真实存在 — git：check_env run_cmd 数组含 git；python/uv：SKILL.md 命令与脚本 shebang；sh：sanitize_history.sh shebang。
- [ok] 功能声明 vs 夸大检查 — description 承诺的『Diagnose, repair, and standardize repository setup and safe Git workflows』全部由路由表+脚本+门禁兑现；反例扫描未见越界承诺（无自动破坏性操作、无网络工具）。
- [ok] 元数据（license/stars/commit） — 仓库根 LICENSE 为 MIT (c) 2025 daymade；GitHub API stars=1385、pushed_at=2026-09-09T12:33:29Z；本地 HEAD==pin d5c4678cb5d4fd6acc9c922690df035dbd33d247。
6结论
适合： 适合：仓库在新机跑不起来、同事 onboarding 需要可重复交接、启动输出重复需诊断 hook、以及提交/推送/冲突/历史清理需要受控工作流的 Claude Code 或 Codex 用户；也适合团队把『sync before work』这类例行启动行为沉淀进 AGENTS.md/CLAUDE.md 而非堆 hook。
不适合： 不适合已由 AGENTS.md/CLAUDE.md 完全覆盖的仓库（skill 会建议直接走项目说明）；不适合希望全自动无确认的 CI 式修复（它坚持只读诊断、显式批准与解释状态）；不适合把 Claude hook 配置照搬进 Codex 的用法（skill 明令禁止，Codex 侧应先读 startup_automation 验证宿主语义）。
Install Agent-Ready
① Verified Mirror 2026-09-09
Option A · Direct DownloadDownload auto-repo-setup.tar.gz
sha256:
Option B · Copy Guide for Agentf95bf84548251fa7…agent 读 JSON 指南后会自动从本站下载安装，无需更多说明。
② Upstream GitHub
GitHub Repo ↗
Pinned to commit d5c4678cb5.