code2prompt

Code2Prompt

让 code2prompt 在本地遍历、筛选、解析并汇总仓库上下文。 使用精简的结构图选择相关文件，然后一并阅读实现及其测试。对于广泛探索， 优先使用这种方式，而不是反复运行 find、rg --files 并逐个读取文件。

选择最精简且实用的工作流：

• 如果已知相关路径，直接分组读取源文件。
• 对不熟悉的区域，先生成一份实体图，再根据其中的路径和符号选择分组读取。相关源文件发生变化前，重复使用这份图。
• 对于较小的区域，直接读取源文件可能比生成图更省力。
• 如果无法提取实体，可使用目录图作为后备方案。

根据任务和上下文预算调整范围。避免每个问题都重新扫描整个仓库， 也不要在确定相关区域前就输出所有源文件。

安装 CLI

每个环境只检查一次是否可用，不要每次读取前都检查：

code2prompt --version
code2prompt --help

要使用由 sem 支持的实体图，请使用启用了可选 entity-map 功能的 CLI 构建版本。如果已安装 Rust/Cargo，可从 code2prompt 仓库构建：

cargo install --git https://github.com/mufeedvh/code2prompt \
  --locked --features entity-map code2prompt

对于普通目录图和源文件读取，标准安装即可：

# Choose one available package manager:
cargo install code2prompt --locked
brew install code2prompt

现有 CLI 即使在构建时未启用该功能，也可能会在帮助信息中列出 --entity-map；此时提取结果为空。如果无法或无需启用该功能进行构建，请继续直接读取普通源文件。 无需单独配置 sem 可执行文件或服务：code2prompt 在内部使用 sem-core。

预编译二进制文件可从 GitHub releases 获取。 安装此技能会添加说明；CLI 需要单独安装。 pip install code2prompt-rs 安装的是 Python SDK，而不是 CLI。

为不熟悉的区域生成图

在要检查的仓库中运行。将下面的示例路径和模式替换为仓库的实际布局。将 CODE2PROMPT_SKILL_DIR 设置为包含此已安装 SKILL.md 的绝对目录；随附的模板是 assets/code-map.hbs。它是技能资源，不是待分析仓库中的文件。

对于某个源代码区域及其测试：

code2prompt . --include 'src/**' --include 'tests/**' \
  --exclude '**/*.snap' --entity-map \
  --template "$CODE2PROMPT_SKILL_DIR/assets/code-map.hbs" \
  --output-file - --quiet

如果布局未知，请省略包含项并排除生成文件和供应商目录，或者先生成目录图。模板会列出选定的文件路径和提取出的实体：名称、类型、声明片段、父级名称和行范围。它不会渲染完整文件内容；默认模板会渲染 --entity-map。声明片段是实体的首行，可能包含内联代码；请排除生成文件和压缩文件，以保持图的实用性。 不要将实体提取与 --exclude '**' 或 --deselected 结合使用：code2prompt 必须选中这些文件才能解析。

(no extracted entities) 表示提取结果为空，或二进制文件未启用该功能。有些文件会生成通用的 chunk 条目，而不是声明；模板会显示其范围，但不包含内容片段。这两种情况都不意味着文件无关。请视需要直接阅读清单、文档或其他此类文件。这不是依赖关系图，也不是语义文本搜索。

后备方案：生成不含文件内容的目录图：

code2prompt . --full-directory-tree --exclude '**' --output-file - --quiet

完整目录树会保留被排除的路径，同时遵循忽略规则，并默认跳过隐藏条目。若要缩小目录树范围，请分析某个子目录；包含/排除模式不会裁剪完整目录树。

一并读取选定的上下文

同时加载相关实现和测试，并显示行号：

code2prompt . --include 'src/auth/**' --include 'tests/auth/**' \
  --exclude '**/*.snap' --line-numbers --output-file - --quiet

已知文件路径时，读取一小组指定文件：

code2prompt . --include 'README.md' --include 'src/auth/session.ts' \
  --line-numbers --output-file - --quiet

使用映射在一次请求中收集可能的实现、其调用方或接口，以及相关测试。只有当返回的源码显示缺少依赖项，或仍有具体问题未解决时，才添加另一批文件。如果输出过大或被截断，请缩小选择范围。

对于精确内容匹配，或超大文件中的小段行范围，请使用合适的文本搜索或文件读取工具。code2prompt 按路径选择整个文件；它不提供按符号查询或按行范围选择的 CLI 选项。

实用控制选项

• 将 glob 模式括在引号中，避免 shell 对其进行展开。模式相对于所分析的目录；多个模式请重复使用 --include 和 --exclude。使用 **/*.rs 匹配某种语言，或使用 src/** 匹配子树。
• 使用 --output-file - 明确将提示词发送到 stdout，即使配置默认输出到剪贴板也一样。--quiet 会隐藏进度和摘要消息。在自动化 Agent 工作流中避免使用 --tui。
• 对于结构化输出，添加 --output-format json。对于较大的结果，使用 --output-file 将结果写入所分析目录之外的临时文件，然后读取该文件。省略 --quiet 可在 stderr 上查看预估的 token 数量。当前预估包含选定文件的内容，即使模板省略了文件正文；不要将其解读为精简映射的实际 token 大小。
• 隐藏文件需要使用 --hidden。被忽略的文件需要使用 --no-ignore；常规探索时请保留默认的忽略行为，并使用 include 模式明确指定任何额外文件。
• 如果输出与请求的范围不同，请在不使用 --quiet 的情况下重新运行，以查看加载了哪些配置。CLI 会先从工作目录读取 .c2pconfig，然后回退到平台的用户配置目录。提供任何 CLI include/exclude 模式都会替换两组已配置的模式；配置中的 path 可以覆盖位置参数指定的目录。

如需了解更多选项，请参阅 CLI 指南。