Auto Repo Setup 的目标是让仓库变得可用，同时不改变用户原有的工作方式。它把设置视为一项以证据驱动的仓库任务，而不是为特定职位的人提供的特殊界面。
入口路由
在改动任何内容之前，先对请求进行分类。不要仅仅因为都包含“setup”一词就把多种模式合并。
- 用户结果：“跑不起来”、缺少依赖、新机器 → 模式：环境修复 → 第一步：阅读项目说明并检测实际技术栈。
- 用户结果：“开工前先同步”、“拉取最新” → 模式：会话例行 → 第一步：使用项目说明或执行用户的自然语言请求。
- 用户结果：重复或意外的钩子输出 → 模式：钩子诊断 → 第一步：在编辑配置前统计注册数和触发会话数。
- 用户结果：队友需要可重复的交接 → 模式：仓库交接 → 第一步：审计现有入门文档，只补齐缺失的操作契约。
- 用户结果：提交、推送、冲突、泄露的密钥/历史 → 模式：Git 安全 → 第一步：在变更前阅读 references/git_safety.md。
- 用户结果：行为必须在第一个提示之前发生 → 模式：启动自动化 → 第一步：阅读 references/startup_automation.md 并通过其钩子门禁。
操作原则
- 不要从角色推断能力。匹配用户展现出的高度。协作者可以告诉智能体“先同步远程”；除非用户要求，不要发明启动器、快捷方式或向导。
- 使用满足结果的最少机制。按顺序优先：直接 Agent 指令 → 项目指令 → 显式命令 → 生命周期钩子。钩子不是一句话的更专业版本。
- 在产出之前检查权限。先阅读当前用户请求，再阅读项目说明、入门文档/运行手册、清单、锁文件和实际命令输出。不要为未声明这些内容的仓库强制要求 ONBOARDING.md、Python、uv、ffmpeg 或 .env。
- 保留用户工作。绝不要为了看起来设置成功而自动 stash、合并、变基、强制、丢弃或覆盖本地改动。本任务隔离改动的已授权交付可以在“已授权的共享检出交付”下使用仓库声明的限定工作流；这不授权整合无关的本地提交或共享 WIP。
- 定义可证伪的成功状态。“依赖已安装”不够；运行项目真实的冒烟测试或启动命令并验证可观察结果。
- 在原因已知之前保持诊断只读。安装、配置编辑、钩子注册、提交和外部写入需要用户请求所隐含的权限；破坏性或公开操作需要明确批准。
工作流 A — 环境修复
A1. 阅读项目地图。只阅读存在的文件，按此顺序：AGENTS.md 和 AGENTS.override.md；CLAUDE.md 和限定范围的项目规则；ONBOARDING.md 或仓库命名的设置/运行手册；README.md；清单、锁文件、任务运行器、CI 和容器配置；仅当请求涉及智能体行为时才阅读现有的 Claude/Codex 设置。如果不存在入门指南，从权威清单和已执行的命令推断设置路径。除非持久交接是请求的一部分，否则不要停下来询问是否创建文档。
A2. 运行只读能力清单。当已有 Python 3.10+ 运行器时，对仓库根目录使用捆绑的 scripts/check_env.py。它检测声明的生态系统并只检查相关工具链；它不安装依赖，也不读取密钥值。如果 Python 本身就是缺失的前置条件，直接执行同样的只读清单盘点，而不是仅仅为了运行审计而安装 Python。
命令： uv run python scripts/check_env.py --repo <repo-root> uv run python scripts/check_env.py --repo <repo-root> --json
将清单视为证据，而不是项目设置规范。自定义运行手册或 CI 工作流可能要求通用清单无法推断的工具。
预期结果：
- 退出码 0：从清单推断的所有工具链均可用；
- 退出码 1：一个或多个推断的前置条件缺失；
- 退出码 2：仓库或其元数据无法被安全地检查。
A3. 修复根本原因。对每个失败的要求：捕获确切的命令、退出码、stdout 和 stderr；将失败追溯到声明来源：项目指南、清单、锁文件、配置或运行时日志；应用最小的、与项目一致的修复；在继续之前重新运行失败的检查。不要重启、重装所有内容或切换包管理器作为第一步。不要打印 .env 或凭据内容；在不回显值的情况下验证存在性和行为。
A4. 验证产品路径。运行项目文档化的冒烟测试、构建或启动命令。如果不存在，从 CI/任务运行器配置推导一个并标注推导来源。验证可观察结果，而不仅仅是零退出码。
报告：哪里坏了以及证据；改了什么；确切的验证和结果；任何剩余的用户操作或被阻止的权限。
工作流 B — 例行 Git 同步
对于“开工前同步”，优先使用使用该仓库的智能体共享的简短项目指令。例行流程是：
- 检查分支、上游和工作树状态。
- 如果任务包含已授权的交付，并且仓库声明了可用的限定工具，能保留无关的共享 HEAD、索引和 WIP，则使用“已授权的共享检出交付”。仅脏或分叉状态本身不是让该交付等待的理由。
- 否则，如果工作树干净，运行 git pull --ff-only。
- 如果有本地改动，不要自动 stash 或 pull；解释状态。
- 如果本地和远程历史分叉，不要自动合并、变基或强制；解释状态。
- 如果网络失败，说明情况，并且仅当用户任务可以安全地在本地版本上继续时才继续本地工作。
协作者也可以简单地说：“开始前同步最新的远程版本。”这是正常的 Agent 指令，不是降级的回退方案。
不要仅仅为了自动化这个例行流程而注册 SessionStart。静态行为属于 AGENTS.md/CLAUDE.md；Agent 可以检查上下文并处理异常的 Git 状态，而不是把它们隐藏在 shell 进程中。
工作流 C — 仓库交接
仅当用户想要持久交接且现有项目地图尚未提供时，才创建或修订入门文档。
使用 references/onboarding_template.md 作为检查清单，而不是字面的 Python/视频模板：从清单和实际项目命令推导前置条件；在每个命令后包含预期输出；将一次性设置与日常使用分开；包含对真实观察到的失败的恢复；保持项目指令作为操作 SSOT，避免重复值。在用户关心的目标操作系统上验证每个命令。
工作流 D — 启动自动化和钩子诊断
在添加或更改任何钩子之前，阅读 references/startup_automation.md。
先诊断重复输出：枚举项目、本地、用户、托管和插件钩子注册；统计匹配条目；不要从三个输出推断“三个注册”；识别哪些根会话、恢复、压缩或子智能体触发了它们；验证事件匹配器和当前运行时负载；在提出更改之前说明根本原因。
仅在钩子门禁通过后安装：捆绑的初始化器是 Claude Code 专用的，只安装轻量级启动上下文提示。它保留无关设置，添加匹配器 startup，验证指南路径，原子写入，并且是幂等的。
先预览：
uv run python scripts/init_session_start_hook.py
--repo <repo-root>
--guide ONBOARDING.md
--dry-run
在用户确认确实需要提示前注入后，运行相同命令但不带 --dry-run。仅用 --remove 移除受管条目。
绝不要类比地将此配置复制到 Codex。Codex 项目行为通常应放在 AGENTS.md 中；如果确实需要 Codex 钩子，先验证已安装版本的根/子智能体行为和负载。
Git 安全
在提交、推送、冲突解决或历史重写之前，阅读 references/git_safety.md。关键规则：只暂存预期路径；除非用户在本会话中明确输入了绕过，否则绝不绕过钩子；推送前从托管服务验证仓库可见性；公开推送、强制推送或历史重写前获得明确批准；从项目语义解决冲突，绝不盲目选择“ours”或“theirs”；在将历史清理视为完成之前撤销泄露的凭据。
使用 references/pii_guard.md 进行公开分发内容审查。绿色扫描器不能替代语义审查。
对于普通 Git 提交前的自动产物验证，使用提交时检查程序。它涵盖 Agent 和手动提交中的 Git 钩子、暂存输入验证和现有钩子保留。当任务隔离必须保留仓库特定的 LFS 和安全配置时，使用隔离检出准备。
对于只读历史扫描，现有的 scripts/sanitize_history.sh 仍然可用。它从不重写历史；将其发现视为候选，未经明确批准不要执行重写命令。
反向审查边界
当已批准的工作实质性改变安全策略、共享生命周期钩子、CI/CD、依赖或破坏性 Git 行为时，使用反向审查。不要为普通的设置检查或一行项目指令生成审查团队。按概率、成本、实际使用和直接验证过滤每个发现。
资源
- scripts/check_env.py — 技术栈感知的只读仓库清单
- scripts/init_session_start_hook.py — 受保护的 Claude Code 启动提示管理器
- scripts/sanitize_history.sh — 只读历史候选扫描
- references/startup_automation.md — 项目指令 vs 命令 vs 钩子的决策与验证
- references/git_safety.md — 同步、提交、推送、冲突和历史重写门禁
- references/onboarding_template.md — 持久交接检查清单
- references/pii_guard.md — 公开内容扫描层