--- name: harness-sync description: "Use when the user asks to synchronize, refresh, or validate Harness metadata, projection, remote knowledge ownership, config origins, or CodeGraph status." --- # harness-sync ## Purpose 通过一个有界入口刷新 Harness 投影与元数据、检查远端知识职责和项目状态，并在当前命令输出中给出组件结果。`sync` 是维护命令，不是 change 生命周期阶段：不追加 change 事件、不上传运行监控。`sync` 不直接改写 AGENTS.md 或经验规则；经验规则由归档时自动学习维护。 ## Before running 读取 `reference.md`。`sync` 自身会在任何重操作之前完成能力握手；不要另起一个 `capabilities` 进程。工作流要求 `sync@2`、`knowledge-sync@3`、 `codegraph-status@2`。`BLOCKED_CAPABILITY_MISMATCH` 属环境阻塞， 不得降级为手工拼接旧流程。 ## Run ```powershell npx hunter-harness sync --project <项目路径> --progress jsonl --json ``` CLI 负责 Python runtime 解析、Adapter 事务、远端知识职责、文档审计提示、map、指令图、配置来源、change 状态及 CodeGraph 证据汇总。禁止直接调用旧知识 Python 脚本，禁止使用固定 `HEAD~5`，禁止自动全量重建 CodeGraph。 只读诊断使用 `--check`（`--dry-run` 为兼容别名）；它不得写 receipt 或投影。普通模式只允许执行用户请求的 Adapter 事务，不写入 `.harness/runtime/sync/`。长阶段的 heartbeat 写 stderr；stdout 只保留紧凑摘要。需要组件级证据时显式加 `--verbose`；`reportPath` 和 `reportSha256` 固定为 `null`。 摘要中的 `remediations[]` 是稳定修复契约。先用对应 `previewCommand` 预览；低风险修复用 `--apply safe`，指定修复用 `--fix `。需覆盖受管投影的修复必须同时提供 `--yes`， 并依赖 refresh 事务留下的 before snapshot；不允许绕过确认或无备份覆盖。指定修复时， 无关组件只做只读评估，不得顺带写入。 ## Interpret - `OK`：所有可验证组件通过。 - `ADVISORY`：例如存在可选优化建议；退出码仍为 0，且 `sync` 本身没有改写文档。`CODEGRAPH_SERVICE_UNREACHABLE` 也属此级：daemon 未运行时索引仍可正常查询（CLI/MCP 直读数据库），仅增量自动同步暂停，不需要按 WARN 修复。 - `WARN`：存在过期、冲突、待评审或 `UNKNOWN` 证据；按组件的中文 `nextAction` 处理。 - `FAIL`：组件执行失败；不得宣称同步完成。 - `BLOCKED`：runtime、项目状态或能力契约阻塞；先修复阻塞条件。 - `UNKNOWN`：证据不足，不等于成功，也不触发无界重建。 非交互或 CI 使用 `--check --progress jsonl --json`。经验规则候选由归档自动学习写入 AGENTS.md 受管段，无需人工评审。 ## 交互后续动作 交互式宿主支持选择器时，必须使用**多选复选框**，保持用户熟悉的勾选形式；只显示与本次非 OK 组件对应的选项，再附加“保持现状”。不要改成自由输入或普通编号问答。选项标题和说明优先使用通俗中文，机器原因码只放在技术详情中。 - **生成 Codebase Map**：仅在 `codebase-map` 缺失或过期时显示。说明它会扫描项目的技术栈、外部集成、架构、目录结构、编码约定、测试方式和风险，生成 `.harness/codebase/map/` 下的 `STACK.md`、`INTEGRATIONS.md`、`ARCHITECTURE.md`、`STRUCTURE.md`、`CONVENTIONS.md`、`TESTING.md`、`CONCERNS.md`，以及 `map-summary.md` 和 `map-manifest.json`；不会修改源码。 - **检查 CodeGraph 后台同步**：仅在 watcher 未验证、停用或存在待同步源码时显示。若索引可用且待同步数为 0，应说明当前查询仍可用，检查 watcher 只是为了确认后续源码能否自动增量更新。 - **保持现状**：接受本次提示，不执行任何后续动作。 ## Safety 同步不得直接修改项目指令文档或规则。配置真源与生成投影存在漂移时只报告，不静默覆盖真源。change 清理先 dry-run，仅对已验证归档收据执行安全清理。知识查询和 ingest 均为远端职责，不创建 `.harness/knowledge`。 无论结果如何，`sync` 都不写持久同步报告、不追加 change 事件，也不上传监控；组件详情仅存在于本次 stdout。Adapter 事务本身的必要备份和回滚证据不属于 sync 日志，不得因此禁用。 ## 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