别把整个仓库塞给 AI:用 Python 生成安全的代码上下文清单

让 AI 帮忙分析老项目,最省事的做法似乎是把整个目录直接丢进去。

但项目里往往混着 .env、密钥、依赖目录、构建产物和大体积文件。全部提交不仅浪费上下文,还可能把不该出现的信息一起带出去。

我更建议先生成一份"仓库上下文清单":只列出适合分析的文件路径和大小,人工看一遍,再决定下一步让 AI 读取哪些文件。

这个脚本会做什么

脚本默认执行以下处理:

  • 忽略 .git、node_modules、dist、.venv 等目录;

  • 排除 .env、私钥和常见凭据文件;

  • 跳过软链接,避免扫描到项目外部;

  • 只保留常见代码、配置和文档文件;

  • 跳过超过指定大小的文件;

  • 只生成文件清单,不读取文件内容;

  • 自动排除生成的报告本身。

脚本使用 Python 标准库,不需要安装第三方依赖。

完整代码

将下面代码保存为 repo_context.py:

bash 复制代码
from __future__ import annotations

import argparse
import os
from collections import Counter
from pathlib import Path


IGNORE_DIRS = {
    ".git",
    ".idea",
    ".vscode",
    "node_modules",
    "dist",
    "build",
    "coverage",
    "__pycache__",
    ".venv",
    "venv",
}

SENSITIVE_NAMES = {
    ".env",
    ".env.local",
    ".env.production",
    "id_rsa",
    "id_ed25519",
    "credentials.json",
    "secrets.json",
}

ALLOWED_SUFFIXES = {
    ".py",
    ".js",
    ".jsx",
    ".ts",
    ".tsx",
    ".java",
    ".go",
    ".rs",
    ".php",
    ".vue",
    ".sql",
    ".md",
    ".json",
    ".yaml",
    ".yml",
    ".toml",
}


def collect_files(
    root: Path,
    max_bytes: int,
    excluded: set[Path] | None = None,
) -> tuple[list[tuple[Path, int]], Counter[str]]:
    files: list[tuple[Path, int]] = []
    skipped: Counter[str] = Counter()
    excluded = excluded or set()

    for current_dir, dir_names, file_names in os.walk(
        root,
        followlinks=False,
    ):
        dir_names[:] = sorted(
            name
            for name in dir_names
            if name not in IGNORE_DIRS
            and not name.startswith(".")
        )

        current = Path(current_dir)

        for name in sorted(file_names):
            path = current / name

            if path.resolve() in excluded:
                skipped["output"] += 1
                continue

            if name in SENSITIVE_NAMES or name.startswith(".env."):
                skipped["sensitive"] += 1
                continue

            if path.is_symlink():
                skipped["symlink"] += 1
                continue

            if path.suffix.lower() not in ALLOWED_SUFFIXES:
                skipped["unsupported"] += 1
                continue

            try:
                size = path.stat().st_size
            except OSError:
                skipped["unreadable"] += 1
                continue

            if size > max_bytes:
                skipped["too_large"] += 1
                continue

            files.append((path.relative_to(root), size))

    return files, skipped


def build_report(
    root: Path,
    files: list[tuple[Path, int]],
    skipped: Counter[str],
) -> str:
    suffix_counts = Counter(
        path.suffix.lower() or "[no suffix]"
        for path, _ in files
    )

    lines = [
        "# Repository Context",
        "",
        f"- Root: `{root.name}`",
        f"- Included files: {len(files)}",
        f"- Skipped files: {sum(skipped.values())}",
        "",
        "## File types",
        "",
    ]

    if suffix_counts:
        lines.extend(
            f"- `{suffix}`: {count}"
            for suffix, count in sorted(suffix_counts.items())
        )
    else:
        lines.append("- No matching files")

    lines.extend(["", "## Files", ""])

    if files:
        lines.extend(
            f"- `{path.as_posix()}` ({size} bytes)"
            for path, size in files
        )
    else:
        lines.append("- No matching files")

    lines.extend(["", "## Skip summary", ""])

    if skipped:
        lines.extend(
            f"- `{reason}`: {count}"
            for reason, count in sorted(skipped.items())
        )
    else:
        lines.append("- Nothing skipped")

    return "\n".join(lines) + "\n"


def parse_args() -> argparse.Namespace:
    parser = argparse.ArgumentParser(
        description="Generate a safe repository context manifest."
    )
    parser.add_argument(
        "root",
        type=Path,
        help="Project root directory",
    )
    parser.add_argument(
        "-o",
        "--output",
        type=Path,
        default=Path("REPO_CONTEXT.md"),
    )
    parser.add_argument(
        "--max-kb",
        type=int,
        default=200,
        help="Maximum size per file",
    )
    return parser.parse_args()


def main() -> int:
    args = parse_args()
    root = args.root.expanduser().resolve()

    if not root.is_dir():
        raise SystemExit(
            f"Project directory does not exist: {root}"
        )

    if args.max_kb <= 0:
        raise SystemExit(
            "--max-kb must be greater than 0"
        )

    output = args.output.expanduser().resolve()

    files, skipped = collect_files(
        root,
        args.max_kb * 1024,
        excluded={output},
    )

    report = build_report(root, files, skipped)
    output.write_text(report, encoding="utf-8")

    print(f"Wrote {len(files)} files to {output}")
    return 0


if __name__ == "__main__":
    raise SystemExit(main())

运行方法

macOS 或 Linux:

bash 复制代码
python repo_context.py /path/to/project \
  -o REPO_CONTEXT.md \
  --max-kb 200

Windows PowerShell:

bash 复制代码
python repo_context.py "D:\work\demo" `
  -o REPO_CONTEXT.md `
  --max-kb 200

执行完成后会得到类似下面的文件:

bash 复制代码
# Repository Context

- Root: `demo`
- Included files: 18
- Skipped files: 326

## File types

- `.json`: 2
- `.md`: 3
- `.py`: 13

## Files

- `README.md` (1820 bytes)
- `src/main.py` (963 bytes)
- `src/config.json` (218 bytes)

## Skip summary

- `sensitive`: 2
- `too_large`: 3
- `unsupported`: 321

拿到这份清单后,先人工检查一次,再让 AI 按模块分析:

bash 复制代码
这是项目文件清单。请先判断项目类型、主要入口和核心模块,
暂时不要生成代码,也不要假设你已经看到文件内容。

请告诉我:
1. 第一批需要读取哪些文件;
2. 每个文件的分析目的;
3. 哪些配置文件可能包含敏感信息,不应该直接提供。

这样做比一次上传整个项目更可控。AI 不需要先看到几百个依赖文件,也不会因为目录太杂而忽略真正的入口。

还需要注意两个边界

第一,这个脚本只按文件名、扩展名和大小过滤,不是专业的密钥扫描工具。即使文件通过过滤,也要在提交前人工检查内容。

第二,脚本默认忽略所有以点开头的目录。如果项目需要分析 .github/workflows,可以删除 not name.startswith("."),然后单独检查工作流里是否存在密钥、令牌或部署信息。

如果你长期使用 ChatGPT、Claude、Cursor 或 Kiro,会员充值问题也可以了解 gpt68.com。它是第三方 AI 会员充值平台,使用前应看清套餐说明、账号要求和售后规则。工具是否好用是一方面,能不能把项目上下文整理清楚,往往更影响最终结果。

本文脚本基于 Python 标准库 pathlib 和 os.walk 实现。pathlib 用于跨平台路径处理,可参考 Python 官方文档。

相关推荐
东莞市云毅网络有限公司3 小时前
用 Playwright 搭一套问答平台引用监测的最小骨架
python·数据清洗·rag·企业知识库·文档解析
Thanks_ks3 小时前
【第 010 讲】全面掌握 Python 变量与常量:变量的定义与赋值 | 标识符与命名规范 | 变量的底层机制 | 常量与魔术数字
python·内存·变量·标识符·常量·赋值·命名规范
飞Link4 小时前
灵巧手是什么?从机械结构、驱动方式到控制原理,认识机器人的精细操作能力
人工智能·python·机器人
用户0332126663674 小时前
使用 Python 快速查找并高亮 PDF 中的文本
python
用户019027581614 小时前
用 pandas-ta 给 A 股算技术指标(配合 AlphaFeed)
python
2601_967980115 小时前
python+appium自动化测试如何控制App的启动和退出
android·自动化测试·python·appium·设备调试
威哥爱编程6 小时前
模拟面试智能体开发实战 12:每篇都能跑不等于接起来能跑,端到端联调收官把十一块拼图合成一个能用的智能体
python·agent·harmonyos
威哥爱编程6 小时前
模拟面试智能体开发实战 11:报告只躺在后端怎么复盘,把总评搬上手机还要适配大小屏
python·agent·harmonyos
2601_967987377 小时前
Python 实现行为驱动开发 (BDD) 自动化测试详解
自动化测试·python·bdd·behave·gherkin
数字融合8 小时前
透明化视频驱动化工生产动态三维重建管控技术
大数据·人工智能·python