---
description: harness-sync 的能力契约、统一状态模型、报告收据和安全恢复参考。
---

# harness-sync 参考

## 1. 能力握手

工作流 family manifest 声明 `minimumCliVersion` 和 `capabilities`。`sync` 在任何高成本
阶段之前自行核对版本与能力；Skill 不要再运行独立的 `capabilities` 子进程。缺失时返回：

```json
{
  "status": "BLOCKED",
  "reasonCode": "BLOCKED_CAPABILITY_MISMATCH"
}
```

不得通过直接运行内部脚本绕过该阻塞。打包 smoke 会从已发布 Skill 文档抽取所有 `hunter-harness` 命令，并验证安装后的 CLI 能力清单和 `--help`。

## 2. Python runtime

CLI 按以下顺序解析 Python，并在详细报告中记录来源：

1. `HUNTER_HARNESS_PYTHON`
2. 项目受管 runtime（`.harness/runtime/python`、`.venv`）
3. `uv run python`
4. Windows `py -3`
5. `python3`
6. `python`

所有探测都必须有超时。完全不可用时返回 `PYTHON_RUNTIME_UNAVAILABLE`，并跳过仍依赖 Python 的变更状态阶段；远端知识和指令审计不允许回退到本地 Python 实现。

## 3. 统一同步

交互式：

```powershell
npx hunter-harness sync --project <项目路径> --progress jsonl --json
```

CI/非交互式：

```powershell
npx hunter-harness sync --check --project <项目路径> --progress jsonl --json
```

`--check` 是严格只读检查；`--dry-run` 是兼容别名。两者都不生成持久报告、receipt 或
投影。普通模式可以执行明确请求的 Adapter 事务，但同样不写持久同步报告。每个长阶段
通过 stderr 输出受限 heartbeat；stdout 默认只输出：

```json
{
  "status": "WARN",
  "runId": "<run-id>",
  "components": {"ok": 7, "advisory": 1, "warn": 0, "fail": 0, "blocked": 0, "unknown": 0},
  "versions": {
    "cliVersion": "0.0.0",
    "workflowBundleVersion": "0.0.0",
    "adapterBundleVersions": {}
  },
  "remediations": [],
  "reportPath": null,
  "reportSha256": null
}
```

所有模式的 `reportPath` 和 `reportSha256` 固定为 `null`。只有显式 `--verbose` 才把每个
组件的 `status`、`reasonCode`、`observedAt`、`durationMs`、证据、是否自动修复及
`nextAction` 写到 stdout。`sync` 不写 `.harness/runtime/sync/`，不追加 change 生命周期
事件，也不上传运行监控。

### 结构化修复

- `remediations[]` 含稳定 `id`、风险、写入范围、备份/回滚说明、预计耗时、是否需确认、
  `previewCommand` 与 `applyCommand`。
- `--apply safe` 只执行低风险、无需确认的修复。
- `--fix <id>` 只执行该项；需要覆盖受管 Adapter 时必须加 `--yes`。
- 指定修复时，其他组件仍参与诊断但保持只读。
- Adapter 覆盖由 refresh 事务执行，before snapshot 位于最新 committed refresh
  transaction；事务失败会自动回滚。预览永远不得产生写入。

## 4. 组件状态

| 组件 | 核心证据 | 失败/警告原则 |
|---|---|---|
| capability | CLI 版本、必需能力 | 不匹配立即 `BLOCKED` |
| projection | 事务后的实际文件 hash | 使用 post-transaction 校验 |
| knowledge | 远端职责声明 | 固定报告 `remote-only`、`fallback=false`、`localIndex=false`；不运行本地 ingest |
| codebase map | manifest 文档清单、hash、生成时间 | 真实文件校验，不复用旧 display status |
| instruction graph | 入口、include 边、环、主题可达性 | 缺失引用或循环为 `FAIL` |
| config origins | canonical/projection 路径与 hash | 漂移 `WARN`，不静默覆盖 |
| changes | 五态分类及归档收据 | `INVALID`/`ORPHAN` 不自动删除 |
| CodeGraph | `codegraph status --json` 的 pending、数据库观察时间、watcher 可达性 | 输出 `CURRENT/PENDING/STALE/INDEX_PRESENT_UNVERIFIED/MISSING/UNKNOWN`；日志 mtime 只证明 watcher 活动，不证明索引完成；不自动全量 reindex |

全局状态优先级：`BLOCKED` → `FAIL` → `WARN` → `ADVISORY` → `OK`。任一 `UNKNOWN`
至少使全局结果为 `WARN`。远端知识可用性由实际 query/upload 收据判断，`sync` 不伪造本地 freshness。

## 5. Git 与 CodeGraph

增量基线只使用当前分支的 upstream merge-base；没有 upstream 时仅收集当前 HEAD 和有界文件统计。不得读取旧 `.harness/runtime/sync/last-success.json`，也禁止固定使用 `HEAD~5`。

CodeGraph 状态探测优先读取 `codegraph status --json` 的权威 pending 列表；只有该 API
不可用时才退回受限文件扫描，并把来源标成 `database-scan` 或 `unverified`。`.agents/`、
`.codebuddy/` 等投影和 Markdown 文档不计入源码 pending。daemon log
mtime 只写入 `watcherObservedAt`，不能冒充 `indexObservedAt`。服务可达、watcher 已启用
且权威 `pendingFileCount=0` 时为 `CURRENT`。如果 API 不可用，但本地索引存在且受限扫描
确认 `pendingFileCount=0`，返回 `ADVISORY / INDEX_PRESENT_UNVERIFIED`：索引仍可用于查询，
只是无法证明 watcher 正在持续运行。存在待同步源码，或已确认 watcher 停用/服务不可达，
才返回 `WARN`。不要在 sync 内执行全量索引。

## 6. Instruction graph

v1.0 指令文件收敛为 `AGENTS.md` 单入口：只验证它是否存在、Harness 管理段（核心段与
经验规则段）是否完整；`CLAUDE.md`/`CODEBUDDY.md` 不再由 Harness 生成或验证（用户手写
的 CLAUDE.md 属于用户文件，`sync` 不触碰）。

- 最多读取 64 个文件、深度 8、总量 512 KiB。
- 入口可以很薄；主题只需通过引用图可达，不要求复制到入口。

## 7. Config origins

典型 canonical 来源位于 `docs/ai/harness/`，`.harness/config/` 为生成投影。报告同时给出两侧路径、hash、来源类型与 drift，不把投影误判成真源。

## 8. Change 五态与清理

- `ACTIVE`：合法活动变更。
- `ARCHIVED_LEFTOVER`：已由可验证 receipt 归档，但活动目录残留。
- `RECOVERABLE`：残留可安全隔离恢复。
- `ORPHAN`：缺少可信归档证据。
- `INVALID`：结构或收据不合法。

先预览：

```powershell
npx hunter-harness doctor --managed-blocks --json
```

change cleanup 由同步报告提供具体动作。只允许已验证的 `ARCHIVED_LEFTOVER` 进入删除路径；`RECOVERABLE` 只能移入隔离区；`ORPHAN`/`INVALID` 保持原状并提示人工处理。

## 9. 经验规则自动学习

经验规则由归档（archive finalize）自动学习：高置信、通过注入过滤的候选幂等写入
AGENTS.md 的"经验规则"受管段，随归档自动刷新。无人工评审队列，无 instructions
audit/apply 提案流；`sync` 只校验该受管段的完整性。
近期变更中的经验只形成 rule candidates，`instructions apply` 也不得自动写入这些候选。

## 10. 完成判定

只有以下条件同时满足才能宣称同步成功：

- stdout 摘要完整给出全局状态；使用 `--verbose` 时包含组件结果；
- 没有 `FAIL` 或 `BLOCKED`；
- 所有自动修复均有 post-transaction 证据；
- knowledge 组件明确为 remote-only，且未创建或刷新本地索引；
- 文档和规则组件未直接改写项目文件；
- 未写持久 sync 报告、change 事件或监控上传记录；
- 未把 `UNKNOWN` 描述成已验证；
- 第二次无输入变化的运行不产生投影 churn。