Back to Details

project-map-builder

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

项目目录地图构建器

Project Directory Map Builder

为指定目录范围生成或增量更新高信噪比的目录说明文档。
Generate or incrementally update high-signal-to-noise ratio directory documentation for specified directory scopes.

核心规则

Core Rules

  • 必须让用户指定要扫描的文件夹范围，禁止默认全仓库扫描。
  • 若范围过大，提醒上下文风险并让用户确认或缩小范围。
  • 输出语言必须与用户当前语言一致。
  • 文档文件名固定：PROJECT_MAP.md。
  • 若输出位置已存在 PROJECT_MAP.md，进入更新模式（仅增量更新）。
  • 若不存在，进入主动引导模式（先确认范围再新建）。
  • Must ask the user to specify the folder scope to scan; default full-repository scanning is prohibited.
  • If the scope is too large, warn about context risks and ask the user to confirm or narrow the scope.
  • The output language must match the user's current language.
  • The document filename is fixed: PROJECT_MAP.md.
  • If PROJECT_MAP.md already exists at the output location, enter update mode (incremental updates only).
  • If it does not exist, enter active guidance mode (confirm the scope first before creating a new one).

输出位置规则

Output Location Rules

  • 单目录：将 PROJECT_MAP.md 写在该目录根。
  • 多目录：
    • 先询问：生成一个合并文档，还是每个目录各生成一个。
    • 合并：写到项目根目录。
    • 分开：各目录根各写一份 PROJECT_MAP.md。
  • Single directory: Write PROJECT_MAP.md in the root of that directory.
  • Multiple directories:
    • First ask: Generate a merged document, or generate one for each directory separately?
    • Merged: Write to the project root directory.
    • Separate: Write a PROJECT_MAP.md in the root of each directory.

最少需要询问用户的问题

Minimum Questions to Ask the User

  • 要扫描哪些文件夹？
  • 如果是多个文件夹：合并成一个文档，还是分别生成多个？
  • 若范围大或不明确：是否确认范围？
  • Which folders do you want to scan?
  • If multiple folders: Merge into one document, or generate multiple separate documents?
  • If the scope is large or unclear: Confirm the scope?

工作流

Workflow

A) 主动引导模式（不存在 PROJECT_MAP.md）

A) Active Guidance Mode (PROJECT_MAP.md does not exist)

  1. 确认扫描范围与输出策略。
  2. 快速列出指定目录的文件清单。
  3. 识别入口与关键文件（如 manifest、主入口、服务线程、UI、配置、存储、测试、文档）。
  4. 只打开“关键文件”用于解释职责与关系，避免全量读取。
  5. 按结构模板生成 PROJECT_MAP.md。
  6. 不确定处必须显式标注（如“假设”“未确认”）。
  1. Confirm the scanning scope and output strategy.
  2. Quickly list the file inventory of the specified directory.
  3. Identify entry points and key files (e.g., manifest, main entry, service threads, UI, configuration, storage, tests, documentation).
  4. Only open "key files" to explain their responsibilities and relationships; avoid full reading.
  5. Generate PROJECT_MAP.md according to the structure template.
  6. Must explicitly mark uncertain points (e.g., "Assumed", "Unconfirmed").

B) 更新模式（已存在 PROJECT_MAP.md）

B) Update Mode (PROJECT_MAP.md already exists)

  1. 读取既有 PROJECT_MAP.md。
  2. 仅重新扫描用户指定的目录范围。
  3. 结合“当前对话上下文”与文件清单差异，定位需更新的段落。
  4. 只做增量补丁更新，不进行全量重写。
  5. 添加“本次更新”小节（日期 + 范围 + 变更点）。
  1. Read the existing PROJECT_MAP.md.
  2. Only rescan the user-specified directory scope.
  3. Combine "current conversation context" and file inventory differences to locate paragraphs that need updates.
  4. Only perform incremental patch updates; do not rewrite the entire document.
  5. Add a "This Update" section (date + scope + change points).

扫描规则

Scanning Rules

  • 优先使用快速文件列表命令（如 
    rg --files
    或 
    Get-ChildItem
    ）。
  • 不要打开所有文件，只读关键文件。
  • 如需更深入的细节，先向用户确认要深入的子目录。
  • Prioritize using fast file listing commands (e.g., 
    rg --files
    or 
    Get-ChildItem
    ).
  • Do not open all files; only read key files.
  • If deeper details are needed, first confirm with the user which subdirectories to delve into.

文档结构模板（PROJECT_MAP.md）

Document Structure Template (PROJECT_MAP.md)

可按需调整，但建议包含：
  1. 项目概览（一句话）
  2. 作用范围（本次扫描的文件夹列表）
  3. 入口与运行链路（简化版）
  4. 关键配置与存储键（如适用）
  5. 目录与文件说明（按目录层级）
  6. 关键模块关系/调用链
  7. 风险/遗留/不确定点
  8. 本次更新（仅更新模式）
Can be adjusted as needed, but it is recommended to include:
  1. Project Overview (one sentence)
  2. Scope of Application (list of folders scanned this time)
  3. Entry Points and Execution Flow (simplified version)
  4. Key Configurations and Storage Keys (if applicable)
  5. Directory and File Descriptions (by directory hierarchy)
  6. Key Module Relationships/Call Chains
  7. Risks/Legacy Items/Uncertain Points
  8. This Update (update mode only)

多目录输出规则

Multiple Directory Output Rules

  • 合并文档：在“作用范围”列出每个目录，并为每个目录写独立小节。
  • 分开文档：每个目录只描述自身范围，不做跨目录合并。
  • Merged document: List each directory in the "Scope of Application" section, and write independent sections for each directory.
  • Separate documents: Each directory only describes its own scope; no cross-directory merging.

更新模式规则（仅增量）

Update Mode Rules (Incremental Only)

  • 尽量保留已有结构与表述。
  • 只修改与新增/删除文件或新上下文相关的部分。
  • 除非明确错误，否则不删除旧内容。
  • “本次更新”记录日期、范围与变更摘要。
  • Try to retain the existing structure and expressions.
  • Only modify parts related to added/deleted files or new context.
  • Do not delete old content unless it is clearly incorrect.
  • "This Update" records the date, scope, and change summary.

安全与清晰性

Security and Clarity

  • 无法确认的行为或规则必须标注为“假设/未确认”。
  • 看似遗留的文件应标注为“可能遗留”，除非用户要求，否则不建议删除。
  • Must mark unconfirmed behaviors or rules as "Assumed/Unconfirmed".
  • Files that appear to be legacy should be marked as "Potentially Legacy"; do not recommend deletion unless requested by the user.