@hunter-harness/workflow-harness 0.2.49 → 0.2.51

package/harness/bundles/general/codebuddy/scripts/harness_events_sync.py

@@ -119,12 +119,19 @@ def post_json(endpoint: dict[str, str], path: str, body: dict[str, Any]) -> dict
         return json.loads(response.read().decode("utf-8"))
 
 
-def sync_change(project: Path, change_dir: Path, *, heartbeat_only: bool = False) -> dict[str, Any]:
+def sync_change(
+    project: Path,
+    change_dir: Path,
+    *,
+    heartbeat_only: bool = False,
+    run_id: str | None = None,
+    change_key: str | None = None,
+) -> dict[str, Any]:
     endpoint = load_endpoint(project)
     if endpoint is None:
         return {"ok": True, "skipped": True, "reason": "remote credentials not configured"}
-    change_key = change_dir.name
-    rid = run_id_for(change_dir)
+    resolved_key = change_key or change_dir.name
+    rid = run_id or run_id_for(change_dir)
     project_id = endpoint["project_id"]
 
     # Always heartbeat so the console can separate connection vs run status.
@@ -138,20 +145,26 @@ def sync_change(project: Path, change_dir: Path, *, heartbeat_only: bool = False
             {
                 "protocol_version": "hunter-progress-sync/v1",
                 "run_id": rid,
-                "change_key": change_key,
+                "change_key": resolved_key,
                 "client_time": client_time,
-                "title": change_key,
+                "title": resolved_key,
             },
         )
     except (urllib.error.URLError, TimeoutError, OSError, json.JSONDecodeError) as exc:
         return {"ok": False, "error": f"heartbeat failed: {exc}", "run_id": rid}
 
     if heartbeat_only:
-        return {"ok": True, "heartbeat": True, "run_id": rid}
+        return {"ok": True, "heartbeat": True, "run_id": rid, "change_key": resolved_key}
 
     events_file = change_dir / "events.ndjson"
     if not events_file.is_file():
-        return {"ok": True, "run_id": rid, "uploaded": 0, "reason": "no events.ndjson"}
+        return {
+            "ok": True,
+            "run_id": rid,
+            "change_key": resolved_key,
+            "uploaded": 0,
+            "reason": "no events.ndjson",
+        }
 
     lines = events_file.read_text(encoding="utf-8").splitlines()
     acked = load_cursor(change_dir)
@@ -167,7 +180,7 @@ def sync_change(project: Path, change_dir: Path, *, heartbeat_only: bool = False
             continue
         if not isinstance(event, dict):
             continue
-        event_id = str(event.get("id") or f"{change_key}:{acked + offset}")
+        event_id = str(event.get("id") or f"{resolved_key}:{acked + offset}")
         payload = sanitize(event)
         batch.append(
             {
@@ -181,7 +194,13 @@ def sync_change(project: Path, change_dir: Path, *, heartbeat_only: bool = False
         )
     if not batch:
         save_cursor(change_dir, len(lines))
-        return {"ok": True, "run_id": rid, "uploaded": 0, "acked_lines": len(lines)}
+        return {
+            "ok": True,
+            "run_id": rid,
+            "change_key": resolved_key,
+            "uploaded": 0,
+            "acked_lines": len(lines),
+        }
 
     # Drop None phase keys for strict schema.
     for item in batch:
@@ -195,8 +214,8 @@ def sync_change(project: Path, change_dir: Path, *, heartbeat_only: bool = False
             {
                 "protocol_version": "hunter-progress-sync/v1",
                 "run_id": rid,
-                "change_key": change_key,
-                "title": change_key,
+                "change_key": resolved_key,
+                "title": resolved_key,
                 "events": batch,
             },
         )
@@ -222,6 +241,7 @@ def sync_change(project: Path, change_dir: Path, *, heartbeat_only: bool = False
     return {
         "ok": accepted == len(batch),
         "run_id": rid,
+        "change_key": resolved_key,
         "uploaded": accepted,
         "batch_size": len(batch),
         "acked_lines": acked_lines,
@@ -229,10 +249,62 @@ def sync_change(project: Path, change_dir: Path, *, heartbeat_only: bool = False
     }
 
 
+def auto_events_sync(
+    project_root: Path,
+    change_dir: Path,
+    *,
+    heartbeat_only: bool = False,
+    run_id: str | None = None,
+    change_key: str | None = None,
+) -> dict[str, Any]:
+    """Best-effort platform events sync (same style as auto_push_archive_core).
+
+    Failures become warnings so the caller never rolls back the main workflow.
+    """
+    project_root = project_root.resolve()
+    change_dir = change_dir.resolve()
+    if load_endpoint(project_root) is None:
+        return {"skipped": True, "reason": "no remote credentials"}
+    try:
+        result = sync_change(
+            project_root,
+            change_dir,
+            heartbeat_only=heartbeat_only,
+            run_id=run_id,
+            change_key=change_key,
+        )
+    except Exception as exc:  # noqa: BLE001 — best-effort never blocks caller
+        return {
+            "skipped": False,
+            "ok": False,
+            "warning": f"events-sync deferred: {exc}",
+        }
+    if result.get("skipped"):
+        return {"skipped": True, "reason": result.get("reason") or "skipped"}
+    if result.get("ok"):
+        return {"skipped": False, "ok": True, **{
+            key: result[key]
+            for key in ("run_id", "change_key", "uploaded", "acked_lines", "heartbeat")
+            if key in result
+        }}
+    return {
+        "skipped": False,
+        "ok": False,
+        "warning": str(result.get("error") or "events-sync failed"),
+        **{
+            key: result[key]
+            for key in ("run_id", "change_key")
+            if key in result
+        },
+    }
+
+
 def main(argv: list[str] | None = None) -> int:
     parser = argparse.ArgumentParser(description="Sync events.ndjson to platform Run monitoring")
     parser.add_argument("--project", default=".", help="Project root")
     parser.add_argument("--change-dir", help="Specific change directory")
+    parser.add_argument("--run-id", help="Override stable run_id (archive finalize continuity)")
+    parser.add_argument("--change-key", help="Override change_key sent to the platform")
     parser.add_argument("--heartbeat-only", action="store_true")
     parser.add_argument("--json", action="store_true")
     args = parser.parse_args(argv)
@@ -243,7 +315,13 @@ def main(argv: list[str] | None = None) -> int:
         root = project / ".harness" / "changes"
         changes = sorted(path for path in root.glob("*") if path.is_dir()) if root.is_dir() else []
     results = [
-        sync_change(project, change_dir, heartbeat_only=args.heartbeat_only)
+        sync_change(
+            project,
+            change_dir,
+            heartbeat_only=args.heartbeat_only,
+            run_id=args.run_id,
+            change_key=args.change_key,
+        )
         for change_dir in changes
     ]
     ok = all(item.get("ok") for item in results) if results else True

package/harness/bundles/general/codebuddy/scripts/harness_gate.py

@@ -31,6 +31,7 @@ if str(SCRIPTS_DIR) not in sys.path:
 
 import harness_change as hc  # noqa: E402
 import harness_events as he  # noqa: E402
+import harness_events_sync as hes  # noqa: E402
 import harness_ledger as hl  # noqa: E402
 import harness_paths as hp  # noqa: E402
 import harness_plan_finalize as hpf  # noqa: E402
@@ -2213,6 +2214,22 @@ def cmd_begin(args: argparse.Namespace) -> int:
         "gateSeverityMode": severity_mode,
         "gateWarnings": gate_warnings,
     }
+    # C3: best-effort start platform run monitoring (register + running via heartbeat/events).
+    try:
+        monitor = hes.auto_events_sync(project, change_dir)
+        payload["platformMonitor"] = monitor
+        if monitor.get("warning"):
+            warnings_msg = str(monitor["warning"])
+            gate_warnings.append({
+                "code": "PLATFORM_EVENTS_SYNC_WARN",
+                "message": warnings_msg,
+            })
+            payload["gateWarnings"] = gate_warnings
+    except Exception as exc:  # noqa: BLE001 — never block phase begin
+        payload["platformMonitor"] = {
+            "ok": False,
+            "warning": f"events-sync hook failed: {exc}",
+        }
     emit(payload, as_json=as_json)
     return 0
 

package/harness/bundles/general/codebuddy/scripts/harness_profile.py

@@ -852,7 +852,6 @@ def _node_commands(project: Path) -> dict[str, Any]:
         inputs.extend(
             [
                 "harness/scripts/*.py",
-                "harness/harness-knowledge-ingest/scripts/*.py",
                 "harness/harness-test/scripts/*.mjs",
                 "harness/harness-test/scripts/tests/*.mjs",
                 "scripts/*.mjs",

package/harness/bundles/general/codebuddy/scripts/harness_state.py

@@ -218,11 +218,9 @@ def discover_segment_files(
         project / "harness.json",
     ]
     codebase_map = list((project / ".harness/codebase/map").glob("**/*"))
-    knowledge = [
-        project / ".harness/knowledge/index.json",
-        project / ".harness/knowledge/status.json",
-        project / ".harness/knowledge/config.json",
-    ]
+    # Knowledge is remote-only. Keep the segment for schema compatibility, but
+    # do not discover or fingerprint local indexes/fallback state.
+    knowledge: list[Path] = []
     change_inputs: list[Path] = []
     for folder in ("spec", "plans", "meta"):
         change_inputs.extend((change_dir / folder).glob("**/*"))

package/harness/bundles/general/codex/.harness-build.json

@@ -2,5 +2,5 @@
   "schemaVersion": 1,
   "overlay": "none",
   "agent": "codex",
-  "coreHash": "45d6a7410e5db82b"
+  "coreHash": "58d36d8a7da29845"
 }

package/harness/bundles/general/codex/README.md

@@ -56,8 +56,8 @@
 | harness-review | `[Read, Write, Edit, Glob, Grep, Agent, Bash(powershell.exe:*)]` | 同上 |
 | harness-sync | `[Read, Glob, Grep, Edit, Write, Bash(powershell.exe:*)]` | 同上 |
 | harness-codebase-map | `[Read, Glob, Grep, Write, Edit, Agent, Bash(powershell.exe:*)]` | 同上 |
-| harness-knowledge-query | `[Bash(powershell.exe:*), Read, Write, Edit, Glob, Grep]` | 同上 |
-| harness-knowledge-ingest | `[Bash(powershell.exe:*), Read, Write, Edit, Glob, Grep]` | 同上 |
+| harness-knowledge-query | `[Bash(powershell.exe:*), Read, Glob, Grep]` | 同上 |
+| harness-knowledge-ingest | `[Bash(powershell.exe:*), Read, Glob, Grep]` | 同上 |
 
 > **blocking user confirmation 不预批准**：各 skill 需要向用户确认时通过普通权限提示调用 `blocking user confirmation`（adapter 映射到 `AskUserQuestion`/`request_user_input`/普通对话），不在 `allowed-tools` 中预批准（遵循 skill-optimizer 规则）。`harness-codebase-map` 额外预批准 `Agent` 用于派发并行 mapper。
 
@@ -227,8 +227,8 @@ harness-skills/
 | harness-review | `/harness-review` | 6维度参考性审查（不阻塞后续流程） | `test` | 手动 | `.harness/changes/<cn>/reports/review/` |
 | harness-submit | `/harness-submit` 或 `/harness-merge`（别名） | commit+push（主目录）/ worktree：本地 commit→--no-ff 合并→push 主分支 | `review` | 手动 | ledger `mergeFinalHash` + 控制台报告 |
 | harness-archive | `/harness-archive` | 归档产出到 archive/YYYY-MM-DD-<cn>，释放工作区 | `submit` | 手动 | `.harness/archive/YYYY-MM-DD-<cn>/` |
-| harness-knowledge-query | `/harness-knowledge-query` | 查询 .harness/knowledge 历史上下文，生成需求 context pack | `sync`/独立 | ✅ | `.harness/knowledge/context-packs/` |
-| harness-knowledge-ingest | `/harness-knowledge-ingest` | 从 archive 整理/同步/维护知识索引（promote/demote/audit） | `archive` | ✅ | `.harness/knowledge/index.json` |
+| harness-knowledge-query | `/harness-knowledge-query` | 只查询平台语义知识；无本地索引或离线回退 | 独立 | ✅ | CLI JSON（不落本地知识文件） |
+| harness-knowledge-ingest | `/harness-knowledge-ingest` | 确认归档 ZIP 已由平台保存、解包并 ingest | `archive` | ✅ | 服务端 package/knowledge 收据 |
 
 > 生命周期 skill（plan → run → test → review → submit → archive）为**手动触发**：单阶段结束后停止，不自动接续下一阶段（已设 `disable-model-invocation`）。sync / codebase-map / knowledge 等辅助 skill 仍可按需被调用。`harness-run`、`harness-submit`、`harness-archive` 涉及 git 写操作、文件移动或归档，调用前必须确保前置条件已满足。
 > `<cn>` = change-name，由 harness-plan 阶段7确定。其他 skill 自动扫描未归档变更定位。

package/harness/bundles/general/codex/harness-archive/SKILL.md

@@ -3,7 +3,7 @@ name: harness-archive
 description: 归档所有变更产出（计划/测试报告/审查/SQL/API文档）到 .harness/archive/，含归档元数据。仅当用户显式调用
   /harness-archive 时使用；不得被其他阶段 skill 自动接续触发。
 ---
-<!-- generated by harness_deploy.py; core=45d6a7410e5db82b; overlay=none; agent=codex; do not edit -->
+<!-- generated by harness_deploy.py; core=58d36d8a7da29845; overlay=none; agent=codex; do not edit -->
 # harness-archive — 变更归档
 
 ## Purpose
@@ -58,7 +58,7 @@ description: 归档所有变更产出（计划/测试报告/审查/SQL/API文档
 6. **implementation-detail** — 自适应执行参考；legacy 缺失 🟡WARN，不阻断
 7. **test-scenarios** — 测试真相源：`plans/<change>-test-scenarios.md`
 8. **禁止读取 `docs/superpowers/` 作为正式输入** — 旧草稿仅人工线索
-9. **每个 skill 边界只刷新一次状态快照** — 先运行 `python <skills-root>/scripts/harness_state.py capture --project . --change-dir ".harness/changes/<change-name>" --base <baseCommit> --json`；`changedSegments=[]` 时复用已有 profile/rules/map/knowledge/change/code 指纹，不再重复跑全量 `harness-sync`、知识重建或代码库扫描。只有对应 segment 变化或缺失时才定向刷新；快照不能替代源码读取和验证门禁。
+9. **每个 skill 边界只刷新一次状态快照** — 先运行 `python <skills-root>/scripts/harness_state.py capture --project . --change-dir ".harness/changes/<change-name>" --base <baseCommit> --json`；`changedSegments=[]` 时复用已有 profile/rules/map/change/code 指纹，不再重复跑全量 `harness-sync` 或代码库扫描。`knowledge` 段仅为兼容空段，知识始终按需远端查询；快照不能替代源码读取和验证门禁。
 
 状态目录分层：新路径优先，旧路径兼容 → [[../protocols/state-layout-protocol.md|state-layout-protocol]]
 > 片段：read-protocol
@@ -100,7 +100,10 @@ description: 归档所有变更产出（计划/测试报告/审查/SQL/API文档
 
 1. 运行 `python <skills-root>/scripts/harness_archive.py status --change-dir ".harness/changes/<change-name>" --intent release-candidate --json` 前置检查。无 CI 项目若已有完整全量 ledger，先运行 `certify-local`；若用户明确只封存事实，则 status/finalize 均使用 `--intent record-only`。
 2. `meta/archive-meta.md` **由 `harness_archive.py finalize` 自动生成**（与 summary-data `finalStatus` 同源）；**禁止 agent 手写**该文件，手写视为数据丢失。维护者结论写入 events（decision/issue）即可，finalize 会汇总到 summary / archive-meta。
-3. 运行 `python <skills-root>/scripts/harness_archive.py finalize --change-dir ".harness/changes/<change-name>" --archive-root ".harness/archive" --intent <release-candidate|record-only> --json`；读 JSON（cleanup、事件、移动、collect、render、validate、manifest 比对、archive-meta）。finalize 内部负责且仅负责一次 `phase.start` / `phase.end`，调用者不得重复追加。**finalize 不再同步执行知识维护**（§8.2）：它写一个 `pending` maintenance-outbox 项即返回，`knowledgeMaintenance=QUEUED`；写 outbox 失败时 `NOT_QUEUED`（warning，不回滚 archive，总状态 CONDITIONAL）。后续由 `harness-sync` / `harness_knowledge.py maintain` 异步推进 outbox。**finalize 失败或 validate 报错时不删除原目录**。
+3. 运行 `python <skills-root>/scripts/harness_archive.py finalize --change-dir ".harness/changes/<change-name>" --archive-root ".harness/archive" --intent <release-candidate|record-only> --json`；读 JSON（cleanup、事件、移动、collect、render、validate、manifest 比对、archive-meta、ZIP package、上传与服务端 knowledge status）。finalize 内部负责且仅负责一次 `phase.start` / `phase.end`，调用者不得重复追加。**本地不再执行知识维护，也不写 maintenance-outbox**；服务端在归档 ZIP 持久保存并解包后 ingest。**finalize 失败或 validate 报错时不删除原目录**。
+   - **归档包上传**：始终先生成一个确定性 ZIP；有远程凭据时再调用 `npx hunter-harness archive upload`。ZIP 仅包含 `summary-data.json`、`spec/**/*.md`、`plans/**/*.md`、`archive-meta.md`、`change-context.json` 和稳定 manifest；明确排除 logs、review/test 报告、HTML、缓存、备份、凭据和临时文件。
+   - **失败可恢复**：无论远端凭据是否齐全，都先生成 ZIP 与 `<change-key>.upload.json`；上传或服务端 ingest 失败不破坏本地归档。待上传 ZIP 与逐 change 回执保留在 `.harness/state/local/archive-packages/`，可枚举独立重试。只有 CLI 核验 package hash 且服务端同时返回 `archive_status=durable`、`knowledge_status=ready` 后，才清理对应 ZIP 与回执；`indexing` 记为 pending，不记为失败。
+   - **监控终态（C3）**：auto-upload 之后自动 `events-sync`，用归档前 change 路径派生的 `run_id` + 原 `change_key` 上报；失败只记 warning。
 
 - **Read `reference.md`** — finalize 输出字段、archive-meta 格式、CONDITIONAL_OK 规则
 - **Read `templates/summary-data-template.json`** — summary-data 数据结构
@@ -117,6 +120,11 @@ description: 归档所有变更产出（计划/测试报告/审查/SQL/API文档
 - 命令结果不得靠猜测；普通 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
 
 ## 关键规则（硬门禁速查）

package/harness/bundles/general/codex/harness-codebase-map/SKILL.md

@@ -3,7 +3,7 @@ name: harness-codebase-map
 description: 分析现有代码库并生成 .harness/codebase/map/
   下的结构化代码库地图。用于陌生项目理解、重大改造前梳理、harness-sync 提示 map 过期后的人工刷新。
 ---
-<!-- generated by harness_deploy.py; core=45d6a7410e5db82b; overlay=none; agent=codex; do not edit -->
+<!-- generated by harness_deploy.py; core=58d36d8a7da29845; overlay=none; agent=codex; do not edit -->
 # harness-codebase-map — 代码库地图
 
 ## Purpose
@@ -56,6 +56,11 @@ description: 分析现有代码库并生成 .harness/codebase/map/
 - 命令结果不得靠猜测；普通 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 为证据
 
 ## 关键规则

package/harness/bundles/general/codex/harness-knowledge-ingest/SKILL.md

@@ -1,263 +1,75 @@
 ---
 name: harness-knowledge-ingest
-description: 从 .harness/archive 归档整理、同步和维护项目知识索引。适用场景：ingest knowledge、sync
-  knowledge、rebuild knowledge index、promote knowledge、确认知识条目、检查知识库是否过期。
+description: 确认归档 ZIP 已上传并由 Hunter Platform 在服务端解包、校验和入库。客户端不再构建或维护本地知识索引。
 ---
-<!-- generated by harness_deploy.py; core=45d6a7410e5db82b; overlay=none; agent=codex; do not edit -->
+<!-- generated by harness_deploy.py; core=58d36d8a7da29845; overlay=none; agent=codex; do not edit -->
 # harness-knowledge-ingest
 
-从 `.harness/archive/**/reports/final/summary-data.json` 抽取项目知识，生成并维护本地 `.harness/knowledge/` 索引。
+知识 ingest 完全由 Hunter Platform 负责。归档完成时，客户端生成一个确定性 ZIP；
+服务端收到后保存原包、安全解包、发布核心文件，并根据其中的 Markdown 与摘要重建
+项目语义索引。
 
-当前实现是本地、离线、无 LLM、无外部服务的 SQLite FTS MVP，已经支持基础生命周期：`candidate`、`stale`、`active`、`superseded`、`conflicted`。按新需求查询历史由独立的 `harness-knowledge-query` 负责。
+客户端不得生成 `.harness/knowledge`、SQLite 索引、候选条目、视图、报告或本地裁决。
+本地知识处理脚本已从分发包移除；历史版本数据只由升级兼容逻辑识别，不再执行。
 
-## Triggers
+## 归档包边界
 
-- ingest knowledge
-- sync knowledge
-- rebuild knowledge index
-- promote knowledge
-- 确认知识条目
-- 从归档生成知识索引
-- 刷新项目知识库
-- 检查知识库是否过期
+允许上传的核心内容只有：
 
-## Required context
+- `reports/final/summary-data.json`
+- `spec/**/*.md`
+- `plans/**/*.md`
+- `archive-meta.md`
+- `change-context.json`
+- 包内 `archive-manifest.json`（由 CLI 生成）
 
-- AGENTS.md / CLAUDE.md
-- `.harness/archive/**/reports/final/summary-data.json`
-- `.harness/knowledge/index.json`
-- `.harness/codebase/map-summary.md`（如存在）
-- design.md
+日志、测试报告、审查报告、HTML、缓存、备份、凭据和临时文件不得进入归档包。
 
-## Purpose
+## Normal Workflow
 
-解决两个问题：
-
-1. **整理知识库内容**：把归档里的 `businessGoal`、`changedFiles`、`maintenanceNotes`、`knownRisks`、`manualActions`、`verification`、`reviewSummary` 抽成知识条目。
-2. **维护知识生命周期**：检查索引是否过期，保留 active 条目；高置信 candidate 由 `autoPromote` 自动提升；其余 candidate/conflicted 由 **Agent judge** 闭环裁决，不再默认输出人工待办清单。
-
-## Outputs
-
-```text
-.harness/knowledge/index.json
-.harness/knowledge/index.sqlite
-.harness/knowledge/entries/candidate/*.json
-.harness/knowledge/entries/active/*.json
-.harness/knowledge/entries/stale/*.json
-.harness/knowledge/entries/superseded/*.json
-.harness/knowledge/entries/conflicted/*.json
-.harness/knowledge/cache/archive-entries/*.json
-.harness/knowledge/reports/ingest-report-*.md
-.harness/knowledge/reports/verification-report-*.md
-.harness/knowledge/reports/audit-report-*.md
-.harness/knowledge/reports/judge-export-<content-sha256>.json
-.harness/knowledge/reports/judgements-<content-sha256>.json
-.harness/knowledge/reports/latest.json
-.harness/knowledge/views/knowledge-dashboard.md
-.harness/knowledge/views/by-file.md
-.harness/knowledge/views/stale-items.md
-.harness/knowledge/views/superseded-items.md
-.harness/knowledge/views/conflicted-items.md
-.harness/knowledge/views/active-review.md
-.harness/knowledge/views/knowledge.base
-.harness/knowledge/context-packs/*.md
-```
-
-## Commands
-
-`<skill-dir>` 指本 skill 目录。所有 python 脚本命令通过 `powershell.exe -Command "..."` 执行。完整命令示例与 config.json 配置见 `reference.md`「Commands 详细」。
-
-| 命令 | 用途 |
-|---|---|
-| 无参数 / `auto` | 一键防腐：首建 config、sync --update、**默认**写回 validator 建议、verify、audit；随后由 **Agent** 执行 judge 闭环 |
-| `status` | 严格只读地返回 freshness 与 health |
-| `repair all` | 修复可证明的 legacy gate、归一化重复、冲突与报告保留；不确定项返回 `needsConfirmation` |
-| `ingest` | 重建/刷新知识索引，抽取 candidate；`--no-incremental` 强制全量重抽取 |
-| `sync --check` | 只读检查 index 与 archive/HEAD 一致性；`--update` 自动刷新 |
-| `promote` | candidate→active（显式 promote 或 autoPromote / judge 触发） |
-| `demote` | active→stale/candidate（显式 demote 或自动降级策略触发） |
-| `audit` | 生成 Candidate/Stale/Superseded/Conflict/Active Review 报告 |
-| `verify` | 执行 entry validators，刷新 lifecycle.validation，生成 verification-report |
-| `suggest-validators` | 生成 file_exists/file_contains validator 建议；`--apply` 写回 entry |
-| `admin <旧命令>` | 旧管理命令兼容入口 |
-| `mcp` | FastMCP stdio 入口，暴露 9 个工具（见 reference.md） |
-
-config.json 配置项（autoPromote / confidence / activeLifecycle / knowledgeValidation）详见 `reference.md`「Commands 详细」。
-
-## Workflow
-
-### Phase 0：确认项目根目录
-
-项目根目录必须包含 `.harness/`。如果 `.harness/archive/` 不存在或没有 `summary-data.json`，报告当前项目暂无可索引归档，不要伪造知识。
-
-### Phase 1：重建本地知识索引
-
-运行：
-
-```powershell
-powershell.exe -Command "python '<skill-dir>\scripts\harness_knowledge.py' ingest --project '<project-root>'"
-```
-
-生成：
-
-- `index.json`：人类可读 manifest。
-- `index.sqlite`：SQLite FTS5 检索索引。
-- `entries/candidate/`：自动抽取、待确认知识。
-- `entries/stale/`：来源 commit 缺失、无法比较，或来源 commit 后相关文件变化的知识。
-- `entries/active/`：人工确认后可长期引用的知识。
-- `views/`：Obsidian 友好的浏览视图。
-- `reports/`：本次 ingest 报告。
-
-### Phase 2：一键 auto（推荐入口）
-
-```powershell
-powershell.exe -Command "python '<skill-dir>\scripts\harness_knowledge.py' auto --project '<project-root>'"
-```
-
-不传子命令时等价于 `auto`。`auto` 输出必须分别报告：
-
-- `freshness`：archive、HEAD、manifest、entry、SQLite 是否一致。
-- `health`：各 lifecycle、publication、validation 与待裁决工作量。
-
-`auto` 默认会写回确定性 validator 建议（`--no-apply-suggestions` 可关闭）。JSON 返回含 `lifecycle` 摘要（validatorsApplied、autoPromote、pendingAgentJudge 等）。
-
-### Phase 3：Agent judge 闭环（auto 之后必须执行）
-
-当 `lifecycle.pendingAgentJudge > 0`、存在 `pending-judge` outbox，或 `judge export` 的
-`counts.requiredDecisionCount > 0` 时：
-
-1. `judge export`（或读 maintain 产出的 pending judgements）
-2. Agent 读取 export JSON，按 `reference.md`「Agent judge 启发式」批量写 `reports/judge-decisions-<ts>.json`
-3. `judge apply --apply <decisions.json>`（`knowledge.manualReview=true` 时需用户显式 `--force`）
-4. 向用户输出 **已处理报告**（promoted/dropped/superseded/kept/skipped 计数 + 报告路径）
-
-**禁止**默认输出「请人工确认 N 条 candidate」类五步待办清单。拿不准的 candidate 保持 `candidate` 状态留待下轮，记入 `skippedCandidates` 即可。
-
-`pendingAgentJudge`/`requiredDecisionCount` 是完整待裁决总量；`previewCount` 才受
-`config.judge.maxCandidatesPerRun`（默认 100）限制。已被 publication gate 阻断的条目
-只进入 `quarantinedCount`，不得混入 judge export。`defer` 必须保存证据指纹；来源、
-validator、冲突关系或 publication 证据变化后即使未到 `reviewAfter` 也重新进入裁决。
-
-### Phase 4：同步检查（可选）
+1. `harness-archive` 的 finalize 生成确定性 ZIP，并调用：
 
 ```powershell
-powershell.exe -Command "python '<skill-dir>\scripts\harness_knowledge.py' status --project '<project-root>'"
+powershell.exe -Command "npx hunter-harness archive upload --file '<archive.zip>' --change-key '<change-key>' --yes --non-interactive --json"
 ```
 
-当 `upToDate=false` 时，运行 `sync --update` 或重新 `auto`，再交给 `harness-knowledge-query` 查询。
-
-### Phase 5：显式 promote/demote（例外路径）
-
-仅在用户点名单条、或 `manualReview=true` 需人工确认时使用 `promote` / `demote`。日常归档后不要逐条人工复核。
-
-**发布门禁**：knowledge publication 与 archive release status 独立。promote / judge apply /
-autoPromote 校验 authoritative pointer/hash 与 `reportPipeline.sourceConsistency`；即使归档
-最终状态为 WARN，只要知识来源一致也可发布，但保留 release advisory。旧归档只有在
-summary/hash/source commit 可独立证明时才自动生成 attestation；否则保持 quarantined 并
-返回 `needsConfirmation`（详见 `reference.md`「发布门禁」）。
-
-### Phase 6：解释同步结果
-
-回复用户或交给后续 skill 前，应说明：
-
-- 索引是否最新。
-- 如需刷新，具体原因是 archive 增删、checksum 变化、sqlite 缺失，还是 HEAD 改变。
-- 本次是否自动刷新。
-- 当前 `active` / `candidate` / `stale` 的数量。
-- 分别报告 `freshness` 与 `health`，不要用一个 `status` 覆盖
-  lifecycle/review/publication/validation 四个正交维度。
-
-## Knowledge extraction rules
-
-- 优先读取归档显式 `knowledgeCandidates[]`；维护流水线、测试计数等
-  `category=process-observation` 不进入长期知识。
-- Duplicate content 使用 Unicode、空白、标点与大小写归一化指纹，并在全量重建时迁移。
-- 冲突必须同时有相同实体、共享来源范围和双方证据；仅关键词相反不得判为冲突。
-- Keep project-local entries excluded from any global index unless explicitly selected.
-- Validate lifecycle relationships.
-- Default generated entries are `candidate`; only config-gated `autoPromote` may promote high-confidence long-lived entries to `active`.
-- Preserve provenance: every entry must include source archive, summary path, source commit, and source files when available.
-- Do not edit `.harness/archive/**` during ingest.
-- Do not copy secrets into `.harness/knowledge`.
-
-## Lifecycle rules
-
-- `candidate`：自动抽取；高置信 + 白名单类型可由 autoPromote 提升；其余由 Agent judge 裁决或保持 candidate。
-- `active`：autoPromote、judge promote，或显式 promote 后可用。
-- `stale`：来源 commit 缺失、来源 commit 后相关文件变化，或当前代码无法证明旧结论仍有效。
-- `superseded`：被后续归档/决策取代。
-- `conflicted`：与另一条 active/candidate 知识冲突。
+2. 检查响应中的包哈希、服务端保存状态和 `knowledge_status`。
+3. 只有服务端确认原 ZIP 已持久保存且知识状态为 ready，才删除本地待上传 ZIP。
+4. 上传或 ingest 失败时保留 ZIP 与失败收据；修复连接后重试同一个 ZIP，不重新拼散文件。
 
-## Forbidden actions
+## Ownership Rules
 
-- auto_promote_candidate_knowledge_without_config_and_confidence_gate
-- erase_conflicts
-- include_project_local_by_default
-- mutate_archive_evidence
-- store_secrets
-- treat_stale_knowledge_as_current_fact
+- 客户端：选择核心文件、生成稳定 manifest/ZIP、校验包哈希、上传与保留失败重试材料。
+- 服务端：敏感信息扫描、ZIP 安全校验、原包持久化、解包、制品发布、知识 ingest、状态查询和下载恢复。
+- 远端不可用：知识不可用；不得启动本地替代索引。
+- 面向人的知识、提案、规则和说明默认使用中文。
 
-## Allowed capabilities
+## Forbidden Actions
 
-- read
-- search
-- write_candidate_knowledge
-- write_active_knowledge_after_manual_confirmation
-- write_confidence_scores
-- auto_promote_high_confidence_knowledge_when_configured
-- agent_judge_knowledge_lifecycle
-- write_knowledge_index
-- write_obsidian_views
+- build_or_refresh_local_knowledge
+- write_dot_harness_knowledge
+- upload_logs_reviews_tests_or_temp_files
+- call_legacy_python_ingest
+- treat_upload_acceptance_without_durable_status_as_success
+- delete_pending_zip_after_failed_upload
 
 ## Verification
 
-本 skill 自带最小测试：
-
-```powershell
-powershell.exe -Command "python 'harness\scripts\harness_test_runner.py' unittest --profile safe --tests-dir '<skill-dir>\tests' --timeout-seconds 300 --verbosity 1"
-```
-
-完成脚本修改后必须至少运行该测试。若在真实项目中验证，还应运行：
-
-```powershell
-powershell.exe -Command "python '<skill-dir>\scripts\harness_knowledge.py' auto --project '<real-project-root>'"
-powershell.exe -Command "python '<skill-dir>\scripts\harness_knowledge.py' ingest --project '<real-project-root>'"
-powershell.exe -Command "python '<skill-dir>\scripts\harness_knowledge.py' suggest-validators --project '<real-project-root>' --limit 20"
-powershell.exe -Command "python '<skill-dir>\scripts\harness_knowledge.py' verify --project '<real-project-root>'"
-powershell.exe -Command "python '<skill-dir>\scripts\harness_knowledge.py' sync --project '<real-project-root>'"
-```
-
-并确认 `index.json`、`index.sqlite`、`views/knowledge-dashboard.md`、`reports/verification-report-*.md` 存在，且 sync 输出 `upToDate=true`。
+确认归档命令的 JSON 结果同时包含：服务端 package 哈希、保存状态和知识状态。
+若失败，确认 `.harness/state/local/archive-packages/` 中仍保留可重试 ZIP；若成功，确认
+ZIP 已按收据策略清理，且平台下载接口可以恢复原包。
 
 ## 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]]
-> 片段：p0-trust · ingest/sync 须绑定 `upToDate`/产物路径证据
-
-## Output Format
-
-执行完成后展示：
-
-- 本次命令（ingest/sync/promote）与目标项目根。
-- `upToDate` 及 `reasons`（sync）或新增/覆盖条目数（ingest/promote）。
-- 当前 `active` / `candidate` / `stale` 数量统计。
-- 产物路径（`index.json`、`index.sqlite`、`views/`、`reports/`）。
-- `lifecycle` 摘要：`validatorsApplied`、`candidateAutoPromoted`、兼容整数
-  `pendingAgentJudge`，以及
-  `pendingAgentJudgeSummary.requiredDecisionCount/previewCount/quarantinedCount` 等。
-- validator 摘要：`eligible/selected/applied/remaining/unavailable`，不得只报告本轮抽样数。
-- **已处理报告**（auto + judge 后）：promoted/dropped/superseded/kept/deferred/skipped 计数与 `reports/judge-decisions-*.json`、`judgements-*.json` 路径；人工判断还会追加到 `judgements/decisions.json`，后续 ingest 不得抹除。`defer` 必须带 `reviewAfter`，到期前不重复进入待判断清单。
-- 仅当 `upToDate=false` 时建议 `sync --update`；查询历史 → `/harness-knowledge-query`。**禁止**默认列出「请人工确认 N 条 candidate」待办。
-
-## 渐进披露
-
-- **Read `reference.md`** 仅在执行命令或查阅 config.json 配置时 — 含 Commands 详细示例、config.json 配置与兼容说明。
 
-## 交互白名单
+## 生成内容语言约定
 
-**仅当** `.harness/config/harness.json` 中 `knowledge.manualReview=true` 时，promote/demote 高价值条目需 blocking user confirmation；否则按 skill 默认策略 + `decision` 事件。
+- sync/ingest 等生成的文档、规则、知识条目、架构说明一律**优先使用中文**撰写（标识符、命令、代码、API 字段名保持原文）
+- 面向平台展示的标题/摘要/正文默认中文；仅当用户明确要求或目标系统强制时才用英文
+> 片段：p0-trust · 只有服务端持久化与 ingest 收据可证明知识已入库
 
 ## 执行日志
 
@@ -272,4 +84,4 @@ python <skills-root>/scripts/harness_events.py append --change-dir ".harness/cha
 > **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 <n>`，不得覆盖或伪装成一次执行。跨工具继续执行时写 `--executor-tool <codex|claude-code|codebuddy|cursor>`，并在接棒事件写 `--handoff-from-tool` / `--handoff-reason`；也可由 `HUNTER_HARNESS_TOOL/AGENT/MODEL/RUN_ID` 环境变量统一注入。
-> 片段：logging · phase=`knowledge-ingest` · 默认控制台报告；变更上下文写 phase/decision/issue/artifact
+> 片段：logging · phase=`knowledge-ingest` · 记录 package hash、服务端状态与失败重试路径