1实现原理 · 为什么它能做到
本 skill 的实底是两段确定性 Python：scan_repo.py 做结构/信号扫描，extract_commands.py 从 README 抽命令并分类；SKILL.md 只规定何时用、输出什么。命令抽取不是『让模型读 README 猜』，而是正则 + 标题归属 + 启发式分类的可复现流程。
skills/repo-intake-and-plan/scripts/extract_commands.py
"""Extract shell-like commands from README content and classify them."""
同一文件定义了四类分类词汇：inference / evaluation / training / other，并有 SCRIPT_CATEGORY_HINTS、SETUP_PREFIXES、ASSET_PREFIXES 三组优先级。把『抽命令』变成可测试的纯函数（extract_commands(readme_text, readme_dir)），是这套 skill 可被 CI 反复回归的前提。
扫描范围被白名单固定：只查 9 个关键文件与 7 个高信号目录，不做全仓遍历；其结果与警告直接由脚本产出（如缺 README 会显式告警），而非模型自由描述。
skills/repo-intake-and-plan/scripts/scan_repo.py
KEY_FILES = [ "README.md", "README", "requirements.txt", "environment.yml", "environment.yaml", "pyproject.toml", "setup.py", "setup.cfg", "Dockerfile", ]
SIGNAL_DIRS 为 configs/config/scripts/tools/examples/notebooks/checkpoints；warnings 里会写 'No README file was found at the repository root.' 与 'No common environment or packaging files were detected.'。输出含 readme_path、detected_files、detected_dirs、top_level 计数——都是可被编排器消费的结构化字段（run_json 解析 stdout）。
分类器有明确的优先级与辩解：setup/asset 语法先判（避免把安装写成推理），然后标题语义，再按入口脚本名判定（train*.py / eval*.py / sample|generate|infer*.py），最后才落到关键词扫描。
skills/repo-intake-and-plan/scripts/extract_commands.py
# Unambiguous setup/asset syntax outranks generic headings such as # "Basic Example", which otherwise makes installation look like inference. if lowered.startswith(SETUP_PREFIXES + ASSET_PREFIXES): return "other"
入口脚本名的判定权重写在注释里：'The entrypoint script name is the strongest category signal: flags like --eval_iters on a train.py command must not flip training into evaluation (that would bypass the training-authorization gate downstream).'——说明分类结果会喂给下游的训练授权闸门，误判有真实后果，所以规则刻意保守。
对 README 里引用的 .py 入口做结构级复核：读该脚本（≤512 KiB），按 optimizer.step(/backward(/train()/def train*/epoch 循环打分，≥4 分才把命令由原分类改判为 training，并记录 classification_source='entrypoint-structure' 与证据标签。
skills/repo-intake-and-plan/scripts/extract_commands.py
TRAINING_STRUCTURE_SIGNALS = [ ("optimizer-step", re.compile(r"\boptimizer\s*\.\s*step\s*\(", re.IGNORECASE), 3), ("backward-pass", re.compile(r"\.\s*backward\s*\(", re.IGNORECASE), 3), ("model-train-mode", re.compile(r"\.\s*train\s*\(", re.IGNORECASE), 2), ("train-function", re.compile(r"\bdef\s+train\w*\s*\(", re.IGNORECASE), 1), ("epoch-loop", re.compile(r"\bfor\s+\w*epoch\w*\s+in\b", re.IGNORECASE), 1), ]
读文件前有护栏：referenced_python_script() 用 candidate.relative_to(root) 校验，越出仓库根的路径直接返回 None——杜绝用 README 里的 ../ 路径把脚本读到仓库外。这是本 skill 唯一会读仓库文件内容的代码路径。
『分类可以保守到承认无知』被写进 reference：证据不足时标注为 inferred，宁可记录歧义也不过度承诺；README 明确证据优先于文件名猜测。
skills/repo-intake-and-plan/references/repo-scan-rules.md
## Conservative behavior - prefer explicit README evidence over filename guesses - mark guessed classifications as inferred - record ambiguity instead of overcommitting
此处对应 SKILL.md 的 When to apply 第三条 'When inference, evaluation, and training candidates must be classified conservatively.'，两条互为印证。
职责边界被写死：只扫描与规划，不装环境、不下大资产、不跑实质命令、不决定高风险 patch；输出的是给主编排器的最小可信复现建议。
skills/repo-intake-and-plan/SKILL.md
## Clear boundaries - This skill scans and plans. - This skill is helper-tier and should usually be orchestrator-invoked. - It does not install environments. - It does not prepare large assets. - It does not execute substantive reproduction commands. - It does not decide high-risk patching.
Output expectations 进一步固定交付物：仓库结构摘要、已文档化命令清单、inference/evaluation/training/other 分类、最小可信复现建议、歧义与风险清单。
编排器真的会调用这两个脚本（不是文档里的摆设）：orchestrate_repro.py 解析 skill 目录后以子进程方式跑 scan_repo.py --repo … --json，再拿 readme_path 跑 extract_commands.py --readme … --json，并把结果并入复现流程。
skills/ai-research-reproduction/scripts/orchestrate_repro.py
scan_data = run_json(scan_script, ["--repo", str(repo_path), "--json"]) readme_path = scan_data.get("readme_path") command_data: Dict[str, Any] = {"commands": [], "counts": {}, "warnings": []} if readme_path: command_data = run_json(extract_script, ["--readme", readme_path, "--json"])
同一脚本还把这两个文件打包进 _bundled/skills/repo-intake-and-plan/（见 _bundled/MANIFEST.json 的 source/target/sha256 条目），使主 skill 单独安装也能运行这一阶段；ai-research-explore 的 orchestrate_explore.py 亦复用 scan_repo.py。
2核心能力
01仓库结构扫描（白名单关键文件 + 高信号目录 + 顶层计数 + 缺件告警）
02从 README 代码块/`$ ` 提示行抽取 shell 命令，含反斜杠续行合并与去重
03命令分类为 inference / evaluation / training / other，并另标 kind（setup/asset/smoke/run）
04占位符识别：含 <PATH/TO/DATASET> 之类尖括号占位符的命令被判定为不能原样运行
05Markdown 结构感知：行内代码块内的 # 注释不当标题、裸 > 不当命令提示符（避免把散文变命令）
06入口脚本结构复核 → 必要时把命令升级判为 training（带证据标签）
07输出给主编排的最小可信复现建议 + 歧义/风险清单
3外部依赖
| Kind | Dependency / Endpoint |
|---|---|
| cli | Python 3（脚本解释器；由宿主/编排器调用，脚本自身无子进程外呼） |
4管控建议与判定依据
建议配套管控措施
面向 Agent
分级或逐次授权，建议在沙箱运行
面向管理者
审批流程、可回滚、全程审计
判定依据（文件路径与关键语句摘要）
- scripts/: 执行本地脚本或命令: python3 scripts/scan_repo.py --repo <path> --json（本 skill 自带；只读目录枚举）
审计说明： 。两个脚本均为标准库只读分析器：全目录 token 扫描（https?://、urllib、requests、socket、subprocess、os.environ、open( 写作模式）零命中；不联网、不读环境变量/凭证、不写任何文件、不执行被抽出的命令。路径处理有相对根校验，越界即放弃。唯一需注意的是它读的是不可信仓库的文本与少量源码：清单与分类可被恶意 README 误导（例如把训练命令标成推理），但该结果只是待人工/编排器审阅的建议，真正执行需下游授权闸门，因此判绿。
5第二遍独立确认
- [ok] skill 路径（任务书标『待定位』） — 实际相对路径 skills/repo-intake-and-plan；SKILL.md 位于该目录根。
- [ok] 『helper 脚本』确实存在且被调用（非文档装饰） — orchestrate_repro.py:1162-1167 设定 scan_script/extract_script 并在 1173-1178 以 run_json(...) 执行；_bundled/MANIFEST.json 记录两文件打包目标与 sha256；references/skill-registry.json 的 required_files 列出两者。
- [discrepancy] SKILL.md 未给出脚本调用示例 — SKILL.md 仅在 Notes 写 'Use `references/repo-scan-rules.md` and helper scripts under `scripts/`.'，没有给命令行/参数示例；实际 CLI 契约（--repo/--json、--readme/--json）只能从脚本 argparse 与编排器调用点得到。对模型自助调用不够友好，属可改进项；不影响机制结论，已在 capabilities/how_it_works 中改用编排器调用点为证据。
- [ok] 无网络/无凭证/无写入 — 两脚本 import 仅 argparse/json/re/pathlib/datetime/typing（scan_repo 另有 timezone）；全目录 URL/urllib/requests/socket/subprocess/os.environ 扫描零命中；无写文件调用（仅 print 到 stdout）。
- [ok] 路径越界防护 — referenced_python_script() 先 (root / path).resolve() 再 candidate.relative_to(root)，越界抛 ValueError 返回 None；并有 is_file() 与 524_288 字节上限。
- [ok] 分类优先级与注释一致 — classify() 实际顺序为 setup/asset 前缀 → 章节语义 → SCRIPT_CATEGORY_HINTS → 关键词，与文件内注释 'Unambiguous setup/asset syntax outranks generic headings' 一致；command_kind() 独立返回 setup/asset/run/smoke（--help/-h → smoke）。
- [ok] README 定位与姊妹 helper 分工 — README.md:160 'Two helpers support orchestration: `repo-intake-and-plan` and `paper-context-resolver`.'；tests/trigger_cases.json 中 'expected_top': 'repo-intake-and-plan' 的用例存在（repo_scan_only_en：'Do not run anything yet.'），与 SKILL.md 的『不执行实质命令』一致。
- [ok] 元数据 — 本地 git HEAD bd91195ad73199b95e24532b581ff12c07dcce09（= 任务书 pin）；LICENSE MIT / Copyright (c) 2026 Chengkun Rao；gh api → stars 487、last_push 2026-09-13T13:16:25Z。
6结论
适合： 适合任何 README-first 的 AI/深度学习仓库复现前置：想在动手前拿到一份可信的结构摘要与已文档命令清单、并保守区分推理/评测/训练入口的场合；尤其适合作为复现编排器（ai-research-reproduction）或探索流程（ai-research-explore）的第一个确定性阶段，也适合想给自己仓库做『README 命令可用性』体检的人（用 --json 直接拿机器可读结果）。
不适合： 不适合要装环境、下权重的场景（该用 env-and-assets-bootstrap）；不适合已经开始执行、只想跑某条命令的场景（该用 minimal-run-and-audit / run-train）；不适合只想要论文解读的场景（该用 paper-context-resolver）；不适合把它当作端到端复现器——它只扫描与规划，且不写最终报告。
Install Agent-Ready
① Verified Mirror 2026-09-15
Option A · Direct DownloadDownload repo-intake-and-plan.tar.gz
sha256:
Option B · Copy Guide for Agent1953a875072a9f35…agent 读 JSON 指南后会自动从本站下载安装，无需更多说明。
② Upstream GitHub
GitHub Repo ↗
Pinned to commit bd91195ad7.