auto-repo-setup

Auto Repo Setup

让代码仓库能够正常使用，同时不改变用户的日常工作方式。 将设置视为一项以证据为依据的代码仓库任务，而不是为特定职称的人设计的特殊界面。

入口路由

在进行任何更改前，先对请求分类。不要仅仅因为几种模式都包含“设置”一词，就把它们合并。

用户想要的结果	模式	首要操作
“无法运行”、缺少依赖、换了新机器	环境修复	阅读项目说明并检测实际技术栈
“开始工作前先同步一下”、“拉取最新内容”	会话例行操作	遵循项目说明，或执行用户以自然语言提出的请求
Hook 输出反复出现或出乎意料	Hook 诊断	编辑配置前，先统计注册数量和触发会话次数
队友需要可重复执行的交接流程	代码仓库交接	审查现有入门指南，只补齐缺失的操作约定
提交、推送、冲突、泄露的密钥/历史记录	Git 安全	修改前阅读 references/git_safety.md
首条提示词前必须执行某项行为	启动自动化	阅读 references/startup_automation.md 并通过其 Hook 门槛

操作原则

1. 不要根据角色推断能力。 根据用户展现出的熟练程度来调整。 协作者可以直接告诉 Agent“先同步远程内容”；除非用户要求，否则不要擅自添加启动器、快捷方式或向导。
2. 只采用满足目标所需的最简机制。 优先顺序为：直接指示 Agent → 项目说明 → 明确命令 → 生命周期 Hook。Hook 并不是更专业的句子。
3. 先检查权威信息，再采取行动。 先阅读当前用户请求，再查看项目说明、入门指南/操作手册、清单文件、锁文件和实际命令输出。对于未声明需要 ONBOARDING.md、Python、uv、ffmpeg 或 .env 的代码仓库，不要将它们设为必需项。
4. 保护用户的工作。 绝不要为了让设置看起来成功而自动暂存、合并、变基、强制操作、丢弃或覆盖本地更改。已获授权的本任务独立更改交付，可使用代码仓库在 Authorized shared-checkout delivery 中声明的范围限定工作流；但这不代表获准整合无关的本地提交或共享的未提交工作。
5. 定义可证伪的成功状态。 “已安装依赖”并不足够；要运行项目实际的冒烟测试或启动命令，并验证可观察到的结果。
6. 在查明原因前，只进行只读诊断。 安装、编辑配置、注册 Hook、提交和外部写入，都必须有用户请求所赋予的授权；破坏性操作或公开操作必须获得明确批准。

工作流 A — 环境修复

A1. 阅读项目地图

仅阅读实际存在的文件，并按以下顺序进行：

1. AGENTS.md 和 AGENTS.override.md
2. CLAUDE.md 和适用范围内的项目规则
3. ONBOARDING.md 或代码仓库指定的设置指南/操作手册
4. README.md
5. 清单文件、锁文件、任务运行器、CI 和容器配置
6. 仅在请求涉及 Agent 行为时，查看现有 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. 修复根本原因

对于每项失败的要求：

1. 记录确切的命令、退出码、标准输出和标准错误。
2. 沿着声明来源追查故障：项目指南、清单、锁文件、配置或运行时日志。
3. 根据启动配置和只读探测，确认受影响命令实际使用的运行环境：适用时包括解释器和包环境、容器映像或服务启动器。将隔离的验证环境与该使用方环境区分开来。如果使用方环境已满足要求，请保留它并继续执行 A4，不要重新安装。
4. 更改该环境之前，检查受影响的进行中工作和现有授权。设置授权并不代表可以中断其他工作；如果更改会造成干扰，请先协调或等待，并报告尚未解决的确切激活步骤，不要终止或重启相关进程。
5. 通过项目现有的更新途径，实施与项目一致且范围最小的修复，同时保留有效的非目标依赖项和配置。
6. 继续之前，重新运行失败的检查。

不要一开始就重启、全部重装或更换包管理器。不要输出 .env 或凭据内容；请在不回显值的情况下验证其存在性和行为。

A4. 验证产品路径

运行项目文档所述的冒烟测试、构建或启动命令。如果没有此类命令，请根据 CI／任务运行器配置推导一条命令，并标明这是推导所得。请验证可观察到的结果，而不只是确认退出码为 0。

对于依赖修复，请在已确定的使用方环境中启动新进程，读取已安装版本并运行该产品检查。锁文件已更改或隔离安装成功，并不能证明使用方环境已更新。除非另行验证，否则不要将已运行的进程和其他机器纳入结论；不要仅为扩大结论范围而重启它们。声称托管依赖项警报已关闭之前，请单独读取该警报。

报告：

• 哪些内容出现故障，以及相关证据；
• 哪些内容已更改；
• 确切的验证方式及结果；
• 任何仍需用户执行的操作或尚未取得的授权。

工作流 B — 常规 Git 同步

对于“开始工作前同步”，优先使用一段供使用该仓库的 Agent 共享的简短项目指令。常规流程如下：

1. 检查分支、上游和工作树状态。
2. 如果任务包含已获授权的交付，并且仓库声明了可用的作用域工具，能够保留无关的共享 HEAD、索引和 WIP，则使用授权的共享检出交付。仅有未提交或分歧状态，并不是让交付继续等待的理由。
3. 否则，如果工作树干净，则运行 git pull --ff-only。
4. 如果存在本地更改，不要自动暂存或拉取；说明当前状态。
5. 如果本地和远程历史已分歧，不要自动合并、变基或强制操作；说明当前状态。
6. 如果网络故障，说明情况；只有当用户的任务可以安全地基于本地版本继续时，才在本地继续。

协作者也可以简单地说：

开始前同步最新的远程版本。

这是正常的 Agent 指令，不是降级的备用方案。

不要仅仅为了自动执行此常规流程而注册 SessionStart。静态行为应写入 AGENTS.md/CLAUDE.md；Agent 可以检查上下文并处理异常 Git 状态，而不是将其隐藏在 shell 进程中。

工作流 C — 仓库交接

只有当用户需要长期有效的交接资料，且现有项目地图尚未提供此类资料时，才创建或修订入门指南。

将 references/onboarding_template.md 用作检查清单，而不是照搬 Python/视频模板：

• 根据清单文件和实际项目命令确定前置条件；
• 在每条命令后注明预期输出；
• 将一次性设置与日常使用分开；
• 针对实际观察到的问题提供恢复方法；
• 将项目指令作为操作层面的 SSOT，避免重复记录取值。

在用户关心的目标操作系统上验证每条命令。

工作流 D — 启动自动化与钩子诊断

添加或更改任何钩子前，请先阅读 references/startup_automation.md。

先诊断重复输出

1. 枚举项目、本地、用户、托管和插件级的钩子注册项。
2. 统计匹配项；不要仅凭出现了三次输出，就推断存在“三个注册项”。
3. 确定是哪些根会话、恢复、压缩或子 Agent 触发了这些钩子。
4. 验证事件匹配器和当前运行时负载。
5. 提出更改前，先说明根本原因。

仅在通过钩子准入检查后安装

捆绑的初始化程序仅适用于 Claude Code，只安装轻量级的启动上下文提示。它会保留无关设置、添加启动匹配器、验证指南路径、以原子方式写入，并且支持幂等操作。

先预览：

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 钩子，先核实已安装版本中根会话和子 Agent 的行为及负载。

Git 安全

在提交、推送、解决冲突或重写历史记录之前，请阅读 references/git_safety.md。关键规则如下：

• 仅暂存预期的路径；
• 除非用户在本次会话中明确输入了绕过命令，否则绝不绕过钩子；
• 推送前，通过托管服务确认仓库的可见性；
• 公开推送、强制推送或重写历史记录前，必须获得明确批准；
• 根据项目语义解决冲突，绝不能盲目选择“ours”或“theirs”；
• 撤销泄露的凭据后，才能将历史清理视为完成。

公开分发内容审查请使用 references/pii_guard.md。扫描器显示通过，不代表可以跳过语义审查。

普通 Git 提交前进行自动制品验证，请使用提交时检查流程。 该流程涵盖 Agent 和手动提交的 Git 钩子、暂存输入验证，以及现有钩子的保留。当任务隔离需要保留仓库专属的 LFS 和安全配置时，请使用隔离检出准备流程。

只读历史扫描仍可使用现有脚本 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 — 项目说明、命令与钩子的选择及验证
• references/git_safety.md — 同步、提交、推送、冲突和历史重写的审批关卡
• references/onboarding_template.md — 持久化交接清单
• references/pii_guard.md — 公开内容扫描层