用途
gsd-map-codebase 用于对代码库进行分析,通过并行运行的 mapper 智能体探索代码库并产出结构化文档。每个 mapper 智能体负责一个关注区域,并直接将文档写入 .planning/codebase/;编排器只收到确认信息,因此上下文使用量保持最小。
主要能力
- 使用并行 mapper 智能体分析代码库。
- 将结果直接写入 .planning/codebase/ 目录。
- 最终在 .planning/codebase/ 文件夹中生成 7 份关于代码库状态的结构化文档。
- 若存在项目状态文件 .planning/STATE.md,会加载已有上下文。
使用方式
该技能通过提及 $gsd-map-codebase 来调用。$gsd-map-codebase 之后的所有用户文本作为 {{GSD_ARGS}} 处理;如果没有参数,则 {{GSD_ARGS}} 视为空。
技能内含 <codex_skill_adapter> 适配说明,用于在 Codex 环境中进行映射:
- AskUserQuestion → request_user_input 的参数映射:header → header,question → question,选项格式为“Label”——description → {label: "Label", description: "description"};由 header 生成 id(小写、空格替换为下划线)。批量调用 AskUserQuestion([q1, q2]) → 单个 request_user_input,在 questions[] 中包含多个条目。多选变通方案:Codex 没有 multiSelect,可使用连续的单选,或呈现编号的自由列表,让用户输入以逗号分隔的编号。执行模式回退:当 request_user_input 被拒绝(Execute 模式)时,呈现纯文本编号列表并选取合理的默认值。
- Task() → spawn_agent 的映射:Task(subagent_type="X", prompt="Y") → spawn_agent(agent_type="X", message="Y");Task(model="...") → 省略(Codex 使用按角色的配置,而非内联模型选择);fork_context 默认为 false,因为 GSD 智能体通过 <files_to_read> 块加载自身上下文。并行扇出:生成多个智能体 → 收集智能体 ID → wait(ids) 等待全部完成。结果解析:在智能体输出中查找结构化标记,如 CHECKPOINT、PLAN COMPLETE、SUMMARY 等。收集每个智能体的结果后调用 close_agent(id)。
执行上下文引用:@/mnt/local-analysis/workspace-hub/.codex/get-shit-done/workflows/map-codebase.md
适用场景
使用 map-codebase 的情况:
- 既有代码库(brownfield)在初始化前,先理解现有代码。
- 重大变更后刷新代码库地图。
- 上手陌生的代码库。
- 重大重构前,了解当前状态。
- 当 STATE.md 引用的代码库信息过时时。
跳过 map-codebase 的情况:
- 尚无代码的全新项目(没有可映射的内容)。
- 简单的代码库(少于 5 个文件)。
该命令可在以下时机运行:
- $gsd-new-project 之前(既有代码库)——先创建代码库地图。
- $gsd-new-project 之后(全新项目)——随代码演进更新代码库地图。
- 任何时候,用于刷新对代码库的理解。
成功标准
- 已创建 .planning/codebase/ 目录。
- 全部 7 份代码库文档均由 mapper 智能体写入。
- 文档遵循模板结构。
- 并行智能体无错误完成。
- 用户知晓后续步骤。
限制
关于计费、价格、支持的平台、实际效果等具体信息,资料中暂未提供。