--- name: harness-codebase-map description: "分析现有代码库并生成 .harness/codebase/map/ 下的结构化代码库地图。用于陌生项目理解、重大改造前梳理、harness-sync 提示 map 过期后的人工刷新。" --- # harness-codebase-map — 代码库地图 ## Purpose 生成 hunter-harness 自有代码库地图 → `.harness/codebase/map/`（7 类文档）+ `map-summary.md` + `map-manifest.json`。供 plan/run/review 快速理解项目结构。 ## 核心边界 - **内容只写** `.harness/codebase/map/`、`map-summary.md`、`map-manifest.json`、`.harness/reports/codebase-map-*.md`；平台同步只更新 Harness 协议状态 - **禁止** `.planning/`、Git 写操作、修改 `.codegraph/`、自动 commit 或 Git push - `harness-sync` 只**建议**刷新，不自动跑全量 map ## When to Use 首次接入、map 过期（sync 提示）、大型重构前、用户说「刷新 codebase map」。跳过：空项目（<5 源文件）、纯符号查询（用 CodeGraph）。 ## Arguments | 参数 | 含义 | |------|------| | （无） | 全量 7 文档 | | `--fast` | STACK + STRUCTURE + CONCERNS | | `--focus *` | tech / arch / quality / concerns / tech+arch | | `--paths p1,p2` | 增量路径（非法路径 → WARN，全非法须确认） | | `--status` / `--diff` | 只检查，不刷新 | | `--refresh` | 显式全量刷新 | ## Workflow（薄编排） | Phase | 动作 | |-------|------| | 0 | 读 SKILL + `reference.md` / `checklist.md` / `templates/` + protocols | | 1 | 解析 `$ARGUMENTS` → 模式与扫描范围 | | 2 | 检查现有 map / manifest → `--status` 可在此结束 | | 3 | `New-Item` 确保输出目录（PowerShell，禁止 Bash mkdir） | | 4 | Glob/Grep/Read 扫描；git 只读查询经 PowerShell | | 5 | 写 7 文档（`templates/` + frontmatter）— 可并行 mapper agents | | 6 | 写 summary + manifest（schema → `templates/map-manifest.schema.json`） | | 7 | 更新 `.harness/context-index.json` codebase 入口（若存在） | | 8 | 控制台 + `.harness/reports/codebase-map-*.md` 报告 | | 9 | 项目已绑定平台时，运行 `npx hunter-harness push --yes --non-interactive --json` 上传受控规则与架构快照；失败只报告“平台同步待重试”，不回滚本地地图 | 逐步细节、frontmatter 字段、git 允许列表 → `reference.md` / `checklist.md` ## Mapper Agent 策略 优先并行 mapper（tech/arch/quality/concerns）；Agent 直写文档，主会话汇总。不可用 → 主会话顺序扫描 + 🟡WARN。 ## P0 执行可信度规则 - 命令结果不得靠猜测；普通 Bash 被拒 → 立即改用等价 PowerShell 重试一次 - 仅 PowerShell 成功且有明确证据（构建/git/测试输出、文件存在、exit 0）时可标 ✅OK；否则 ❌FAIL 或 🟡WARN - 禁止把 hook 拒绝、静态验证、无输出、用户跳过说成成功 → 详见 [[../protocols/powershell-protocol.md|powershell-protocol]]、[[../protocols/evidence-based-reporting-protocol.md|evidence-based-reporting-protocol]] ## 生成内容语言约定 - sync/ingest 等生成的文档、规则、知识条目、架构说明一律**优先使用中文**撰写（标识符、命令、代码、API 字段名保持原文） - 面向平台展示的标题/摘要/正文默认中文；仅当用户明确要求或目标系统强制时才用英文 > 片段：p0-trust · map 额外：文件存在/行数/hash 为证据 ## 关键规则 | # | 规则 | |---|------| | 1 | 唯一输出 `.harness/codebase/map/` | | 2 | `generated_reviewable`，不建议手工改 map 正文 | | 3 | 不做 Git 写操作、不改业务代码；受控平台上传不等于 Git push | | 4 | 不管理 CodeGraph | | 5 | 敏感信息脱敏 → `sensitive-info-protocol` | | 6 | 证据化输出 → `evidence-based-reporting-protocol` | | 7 | 扫描复用 `harness_profile` 的 `excludedRoots`（`DEFAULT_EXCLUDED_ROOTS`：node_modules/target/build/dist/cache 等）与 state snapshot 输入，不重复定义排除集；sync 只建议刷新，不自动触发全量 map（design §3.7） | ## Output Format 模式、范围、7/7 文档路径与行数、manifest/summary、context-index 状态、平台同步状态、WARN/FAIL → `reference.md` 报告模板 ## 渐进披露 - **Read `checklist.md`** — 执行前后检查 - **Read `reference.md`** — manifest、mapper、扫描模式 - **Read `templates/*`** — 各文档模板 ## 交互白名单 **无** blocking user confirmation；参数/默认值 + `decision` 事件 ## 执行日志 `events.ndjson` 为唯一事实源（schema_version 3，兼容读取 v1/v2；`note` 承载人类可读摘要）；`logs/execution-log.md` 由 `harness_events.py` 渲染，**禁止用 Write/Edit 直接维护**。直接修改的内容会在 `phase.end` 或 finalize 时被完整重建覆盖，属于数据丢失；需要保留的详情必须进入事件 `note`。结构 → [[../protocols/report-pipeline-protocol.md|report-pipeline-protocol]] **`phase.start` 由 `harness_gate.py begin` 写，不要再手工追加一次。** 两条同 `run-id` 的 `phase.start` 会让 `plan finalize` 以 `PHASE_START_DUPLICATE` 卡死，而且手工那次会先触发 auto-seal、把正在开始的 attempt 封成 `RECOVERED`。要补触发指令说明就带 `--note` 跑 `gate begin`。 （重复追加现已按 `(phase, run-id)` 判为幂等 no-op，但依赖它不如不写。） ```powershell # 阶段开始：gate begin 负责，note 在这里给 python /scripts/harness_gate.py begin --change-dir ".harness/changes/" --phase --note "<触发指令>" # 阶段中的其他事件才用 append python /scripts/harness_events.py append --change-dir ".harness/changes/" --phase --type --run-id --note "<摘要>" ``` > **脚本接线**：`harness_events.py append`；`harness_archive.py finalize`；`harness_preflight.py check`；`harness_ledger.py can-reuse`；`harness_service.py ensure/stop`（须 `--files`/`serviceStart.inputFiles`）。JSON 输出按 D13 护栏解读。 > **Task 4 §6.1 写入契约**：普通 `append` = 加锁 -> 追加一行 -> fsync -> 解锁，**不 load 历史、不渲染**（O(1)，跨进程锁 `events.ndjson.lock`，UUID 用完整 `uuid4().hex` 无需去重扫描）。仅 `--type phase.end` append 在追加成功后渲染一次 `execution-log.md`；显式 `harness_events.py render` 随时从完整 events 重建；`harness_archive.py finalize` 在 collect 前强制 render 一次。高频 command append 期间 log 可能滞后，phase 边界保持最新。 每个阶段的 `phase.start` 与对应 `phase.end` 必须复用同一 `--run-id` / `--attempt`；阶段结束必须写 `--status OK|WARN|FAIL|BLOCKED`。重试同一阶段时生成新的 run-id 并增加 `--attempt `，不得覆盖或伪装成一次执行。**`attempt` 按 phase 全局递增，不是按 run-id**：一个 run-id 只绑定一个 attempt，重试必须「新 run-id ＋ 下一个 attempt」两者同时换，只换其一会撞 `EVENT_ATTEMPT_CONFLICT` 或 `PHASE_ALREADY_CLOSED`。已发布 plan 的修订通过重跑 `plan evidence-pack` + `plan finalize` 分配新 attempt（`harness_plan_finalize.py republish` 已于 0.3.0 移除）。 阶段跑得久（plan/run 常见）时用 `harness_context.py renew --project . --change --executor ` 续租；租约到期本身不再阻断 `close`（同一 owner 的过期租约不构成冲突，收据里记 `leaseLapsed`），但续租能让 `view` 的状态如实反映在跑。跨工具继续执行时写 `--executor-tool `，并在接棒事件写 `--handoff-from-tool` / `--handoff-reason`；也可由 `HUNTER_HARNESS_TOOL/AGENT/MODEL/RUN_ID` 环境变量统一注入。 > 片段：logging · phase=`codebase-map`；默认写 reports，有未归档变更时另写 change events