@cyning/harness 0.4.0 → 1.0.1

package/ontology.yaml

@@ -1,9 +1,9 @@
-# cyning-harness 产品设计本体 · 机器可读抽取（草案 v0.4.0）
+# cyning-harness 产品设计本体 · 机器可读抽取（草案 v1.0.0）
 # 人类真值：docs/methodology/product/DESIGN_ONTOLOGY_v1_zh.md
 # 冲突时以 Markdown 为准 · 供未来 harness ontology-check 使用
 
 version: "1.2"
-product_semver: "0.4.0"
+product_semver: "1.0.1"
 license: MIT
 
 classes:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyning/harness",
-  "version": "0.4.0",
+  "version": "1.0.1",
   "description": "cyning-harness discipline package · init / upgrade / check CLI",
   "license": "MIT",
   "type": "module",

package/schema/invoke_index.v1.schema.json

@@ -0,0 +1,53 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://cyning.me/harness/schemas/invoke_index.v1.schema.json",
+  "title": "Harness InvokeSnapshot Index v1",
+  "description": "由 harness-sync --index 生成的 invokes/by-task 机器索引 · 只读聚合 · 不覆盖 S2 域",
+  "type": "object",
+  "required": ["schema_version", "generated_at", "index"],
+  "properties": {
+    "schema_version": {
+      "type": "string",
+      "const": "1"
+    },
+    "generated_at": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "index": {
+      "type": "object",
+      "description": "task_slug → 该 task 的 invoke 列表",
+      "additionalProperties": {
+        "type": "object",
+        "required": ["task_slug", "invokes"],
+        "properties": {
+          "task_slug": {
+            "type": "string",
+            "pattern": "^[a-z0-9][a-z0-9_-]*$"
+          },
+          "invokes": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": ["path", "mtime", "hat_id"],
+              "properties": {
+                "path": {
+                  "type": "string",
+                  "description": "相对业务仓根的 invoke 文件路径"
+                },
+                "mtime": {
+                  "type": "integer",
+                  "description": "文件修改时间戳（秒）"
+                },
+                "hat_id": {
+                  "type": "string",
+                  "description": "从文件名解析的帽 ID，如 30 / 40 / CLOSE / HG-RELEASE"
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/wizard/README.md

@@ -15,6 +15,9 @@ npx @cyning/harness@latest init --preset harness-only --ide cursor,agents
 npx @cyning/harness upgrade
 npx @cyning/harness upgrade --target /path/to/project --yes --force
 
+# 30 前验证
+npx @cyning/harness verify --target /path/to/project
+
 # 仅检查版本
 npx @cyning/harness check
 ```
@@ -22,6 +25,7 @@ npx @cyning/harness check
 - 内部单源：`wizard/install.sh` → `harness-sync.sh apply`（S2 写路径不变）
 - manifest schema：[`schema/manifest.v1.schema.json`](../schema/manifest.v1.schema.json)
 - 本地开发：`node bin/harness.js init --target /path/to/project --preset harness-only --ide cursor,agents --yes`
+- Node 仓可选：`npx @cyning/harness init --with-scripts --pm pnpm`
 
 ---
 

package/wizard/compliance-bench.sh

@@ -0,0 +1,251 @@
+#!/usr/bin/env bash
+# SDD-Compliance micro-bench · v1 · S1–S4
+# 输出合规率 %；不测 LLM 解题，只测 Orchestrate/Verify 可机械部分。
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+HARNESS_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+BENCH_DIR="$HARNESS_ROOT/examples/compliance_bench"
+
+SCENARIOS=()
+QUIET=0
+
+usage() {
+  cat <<'EOF'
+用法：compliance-bench.sh [--all | S1 S2 S3 S4] [--quiet]
+
+  --all     运行 S1–S4（默认输出含公理解释与摘要表）
+  --quiet   CI/脚本模式：stdout 仅打印合规率数字；摘要说明走 stderr
+
+说明：
+  合规率 = PASS 场景数 ÷ 总场景数 × 100。
+  100 表示 S1–S4 全部通过，即 gate-check / sync 行为符合 SDD 公理；
+  不是 LLM 解题正确率，也不是业务项目胜率。
+
+示例：
+  ./wizard/compliance-bench.sh --all              # 维护者人工验收（推荐）
+  ./wizard/compliance-bench.sh --quiet --all      # 关账勾选 / CI（解析 stdout 数字）
+EOF
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --all) SCENARIOS=(S1 S2 S3 S4); shift ;;
+    --quiet) QUIET=1; shift ;;
+    S1|S2|S3|S4) SCENARIOS+=("$1"); shift ;;
+    -h|--help) usage; exit 0 ;;
+    *) echo "未知参数: $1" >&2; usage; exit 1 ;;
+  esac
+done
+
+[[ ${#SCENARIOS[@]} -gt 0 ]] || { usage; exit 1; }
+
+# 非 quiet → stdout 全量；quiet → 场景静默，摘要走 stderr
+log() {
+  if [[ "$QUIET" == "1" ]]; then
+    echo "$@" >&2
+  else
+    echo "$@"
+  fi
+}
+
+log_scenario() {
+  [[ "$QUIET" == "1" ]] || echo "$@"
+}
+
+print_banner() {
+  [[ "$QUIET" == "1" ]] && return 0
+  log_scenario "╔══════════════════════════════════════════════════════════════╗"
+  log_scenario "║  SDD-Compliance micro-bench · v1 · S1–S4                    ║"
+  log_scenario "╚══════════════════════════════════════════════════════════════╝"
+  log_scenario ""
+  log_scenario "性质  机械合规测试 · 合成夹具 · 不调用 LLM"
+  log_scenario "公理  D2 HumanGate · D3 30 前置闸 · S2 sync 域边界"
+  log_scenario "夹具  $BENCH_DIR/"
+  log_scenario "场景  ${SCENARIOS[*]}"
+  log_scenario ""
+}
+
+PASS=0
+FAIL=0
+# 每行: id|status|detail
+RESULTS=()
+
+scenario_header() {
+  local id="$1" title="$2" axiom="$3" fixture="$4" expect="$5"
+  log_scenario "──────────────────────────────────────────────────────────────"
+  log_scenario "[$id] $title"
+  log_scenario "  公理    $axiom"
+  log_scenario "  夹具    $fixture"
+  log_scenario "  期望    $expect"
+}
+
+scenario_footer() {
+  local id="$1" status="$2" detail="$3" explain="$4"
+  if [[ "$status" == "PASS" ]]; then
+    log_scenario "  结果    ✅ PASS · $detail"
+  else
+    log_scenario "  结果    ❌ FAIL · $detail"
+  fi
+  log_scenario "  说明    $explain"
+  log_scenario ""
+}
+
+scenario_S1() {
+  local dir="$BENCH_DIR/S1_r1_pending"
+  scenario_header "S1" "R1 未签 · 30 应被拒" \
+    "D2 HumanGate · D3 30 前置闸" \
+    "examples/compliance_bench/S1_r1_pending/" \
+    "HG-AUDIT-R1=pending 时 gate-check 必须 exit≠0（拒 30）"
+
+  local gate_exit=0
+  "$HARNESS_ROOT/wizard/gate-check.sh" --target "$dir" --task task.md >/dev/null 2>&1 || gate_exit=$?
+
+  if [[ "$gate_exit" -ne 0 ]]; then
+    scenario_footer "S1" "PASS" "gate-check exit=$gate_exit" \
+      "未审核任务不得进入 30 执行编码 · 人闸有效"
+    PASS=$((PASS+1))
+    RESULTS+=("S1|PASS|gate-check exit=$gate_exit · 30 被拒")
+  else
+    scenario_footer "S1" "FAIL" "gate-check exit=0" \
+      "pending R1 仍放行 30 · 违反 D3 · 须修 gate-check"
+    FAIL=$((FAIL+1))
+    RESULTS+=("S1|FAIL|gate-check exit=0 · 未拦截 pending R1")
+  fi
+}
+
+scenario_S2() {
+  local dir="$BENCH_DIR/S2_r1_no_review"
+  scenario_header "S2" "R1 已签但无 review 落盘" \
+    "D2/D3 · 审核制品完整性" \
+    "examples/compliance_bench/S2_r1_no_review/" \
+    "task 表 HG-AUDIT-R1=approved 但 reviews/ 无 *_audit_R1_* → bench 判非合规"
+
+  local gate_exit=0
+  "$HARNESS_ROOT/wizard/gate-check.sh" --target "$dir" --task task.md >/dev/null 2>&1 && gate_exit=0 || gate_exit=$?
+  local review_exists=0
+  [[ -n "$(find "$dir/reviews" -type f -name '*_audit_R1_*' 2>/dev/null)" ]] && review_exists=1 || true
+
+  if [[ "$review_exists" == "0" ]]; then
+    scenario_footer "S2" "PASS" "review 缺失 · gate-check exit=$gate_exit" \
+      "仅改 task 表不算真审核 · 22 须落盘 review 文件（本夹具测 bench 判定逻辑）"
+    PASS=$((PASS+1))
+    RESULTS+=("S2|PASS|无 review 文件 · bench 判非合规")
+  else
+    scenario_footer "S2" "FAIL" "夹具不应含 review 文件" \
+      "夹具数据错误 · 检查 S2_r1_no_review/reviews/"
+    FAIL=$((FAIL+1))
+    RESULTS+=("S2|FAIL|夹具含不应存在的 review")
+  fi
+}
+
+scenario_S3() {
+  local dir="$BENCH_DIR/S3_r1_with_review"
+  scenario_header "S3" "R1 已签且 review 已落盘" \
+    "D2/D3 · 审核闭环" \
+    "examples/compliance_bench/S3_r1_with_review/" \
+    "HG-AUDIT-R1=approved 且 reviews/*_audit_R1_* 存在 → gate-check exit=0"
+
+  local gate_exit=0
+  "$HARNESS_ROOT/wizard/gate-check.sh" --target "$dir" --task task.md >/dev/null 2>&1 && gate_exit=0 || gate_exit=$?
+  local review_exists=0
+  [[ -n "$(find "$dir/reviews" -type f -name '*_audit_R1_*' 2>/dev/null)" ]] && review_exists=1 || true
+
+  if [[ "$gate_exit" == "0" && "$review_exists" == "1" ]]; then
+    scenario_footer "S3" "PASS" "gate-check exit=0 · review 存在" \
+      "审核链完整 · 允许进入 30（Happy Path 闸口）"
+    PASS=$((PASS+1))
+    RESULTS+=("S3|PASS|gate-check 放行 · review 落盘")
+  else
+    scenario_footer "S3" "FAIL" "gate_ok=$([[ $gate_exit -eq 0 ]] && echo 1 || echo 0) review=$review_exists" \
+      "完整审核场景未通过 · 检查 gate-check 或夹具 review 路径"
+    FAIL=$((FAIL+1))
+    RESULTS+=("S3|FAIL|gate exit=$gate_exit review=$review_exists")
+  fi
+}
+
+scenario_S4() {
+  local dir="$BENCH_DIR/S4_sync_domain"
+  scenario_header "S4" "sync plan 不得覆盖业务域" \
+    "S2 · 纪律层与 task/reviews 分离" \
+    "examples/compliance_bench/S4_sync_domain/ + 临时目标仓" \
+    "harness-sync.sh plan 输出不得含 docs/tasks/ 或 docs/harness/reviews/"
+
+  local tmp
+  tmp="$(mktemp -d)"
+  mkdir -p "$tmp/.cyning-harness"
+  cp "$dir/profile.json" "$tmp/.cyning-harness/profile.json"
+  mkdir -p "$tmp/docs/harness/prompts" "$tmp/docs/harness/invokes" "$tmp/.cursor/rules"
+
+  local plan="$tmp/plan.txt"
+  "$HARNESS_ROOT/wizard/harness-sync.sh" plan --target "$tmp" >"$plan" 2>&1 || true
+
+  local bad=0 bad_lines=""
+  if bad_lines="$(grep -E 'docs/tasks/|docs/harness/reviews/' "$plan" 2>/dev/null || true)" && [[ -n "$bad_lines" ]]; then
+    bad=1
+  fi
+  rm -rf "$tmp"
+
+  if [[ "$bad" == "0" ]]; then
+    scenario_footer "S4" "PASS" "sync plan 无 task/reviews 路径" \
+      "upgrade 不会覆盖用户 task 与审核记录 · S2 边界成立"
+    PASS=$((PASS+1))
+    RESULTS+=("S4|PASS|sync plan 未越界")
+  else
+    scenario_footer "S4" "FAIL" "plan 含 task/reviews 路径" \
+      "sync 会污染业务数据 · 须修 harness-sync 写路径"
+    FAIL=$((FAIL+1))
+    RESULTS+=("S4|FAIL|plan 含 docs/tasks 或 reviews")
+  fi
+}
+
+print_summary() {
+  local total=$((PASS+FAIL))
+  local rate=0
+  [[ "$total" -gt 0 ]] && rate=$((PASS*100/total))
+
+  log "══════════════════════════════════════════════════════════════"
+  log "摘要 · SDD-Compliance bench"
+  log "══════════════════════════════════════════════════════════════"
+  log "$(printf '%-6s %-10s %s' '场景' '结果' '详情')"
+  for r in "${RESULTS[@]}"; do
+    IFS='|' read -r id status detail <<<"$r"
+    local mark="✅"
+    [[ "$status" == "FAIL" ]] && mark="❌"
+    log "$(printf '%-6s %-8s %s' "$id" "$mark $status" "$detail")"
+  done
+  log ""
+  log "合规率  $PASS/$total = ${rate}%"
+  log ""
+  if [[ "$FAIL" -eq 0 ]]; then
+    log "解读    ${rate} = 全部 ${total} 个场景行为符合 SDD 公理（gate-check / sync 回归通过）"
+    log "        不是 LLM 解题分数 · 不是业务 CI 绿率 · 不可外推为「AI 胜率」"
+  else
+    log "解读    ${rate} = ${FAIL} 个场景未通过 · 须修 gate-check / sync 或夹具后再跑"
+    log "        失败场景见上表 ❌ 行"
+  fi
+  log ""
+  log "用途    发布关账证据 · 改 wizard 脚本后回归 · 与 B2 试点 retro 互补"
+  log "文档    examples/compliance_bench/README.md"
+  log "══════════════════════════════════════════════════════════════"
+
+  # quiet 模式：stdout 仅数字（供 CI / 勾选表解析）
+  if [[ "$QUIET" == "1" ]]; then
+    echo "$rate"
+  fi
+}
+
+print_banner
+
+for s in "${SCENARIOS[@]}"; do
+  case "$s" in
+    S1) scenario_S1 ;;
+    S2) scenario_S2 ;;
+    S3) scenario_S3 ;;
+    S4) scenario_S4 ;;
+  esac
+done
+
+print_summary
+
+[[ "$FAIL" -eq 0 ]]

package/wizard/gate-check.sh

@@ -4,6 +4,8 @@ set -euo pipefail
 
 TARGET="${TARGET:-$(pwd)}"
 TASK_FILE=""
+GRAPH_MODE=0
+JSON_MODE=0
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 
 while [[ $# -gt 0 ]]; do
@@ -13,8 +15,10 @@ while [[ $# -gt 0 ]]; do
       TASK_FILE="$2"
       shift 2
       ;;
+    --graph) GRAPH_MODE=1; shift ;;
+    --json) JSON_MODE=1; shift ;;
     -h|--help)
-      echo "用法: gate-check.sh [--target /path/to/repo] [--task docs/tasks/active/task_*.md]"
+      echo "用法: gate-check.sh [--target /path/to/repo] [--task docs/tasks/active/task_*.md] [--graph] [--json]"
       exit 0
     ;;
     *) echo "未知参数: $1" >&2; exit 1 ;;
@@ -24,7 +28,7 @@ done
 gate_status() {
   local file="$1" gate="$2"
   awk -F'|' -v g="$gate" '
-    index($0, g) > 0 {
+    $0 ~ /^[[:space:]]*\|/ && index($0, g) > 0 {
       gsub(/^[[:space:]]+|[[:space:]]+$/, "", $3)
       gsub(/\*/, "", $3)
       print $3
@@ -36,7 +40,7 @@ gate_status() {
 gate_blocks() {
   local file="$1" gate="$2"
   awk -F'|' -v g="$gate" '
-    index($0, g) > 0 {
+    $0 ~ /^[[:space:]]*\|/ && index($0, g) > 0 {
       gsub(/^[[:space:]]+|[[:space:]]+$/, "", $4)
       gsub(/\*/, "", $4)
       print $4
@@ -82,28 +86,144 @@ check_one_task() {
   return "$blocked"
 }
 
-echo "=== Harness gate-check ==="
-echo "目标: $TARGET"
-
-MANIFEST_FILE="$TARGET/.cyning-harness/manifest.json"
-if [[ -f "$MANIFEST_FILE" ]]; then
-  mf_version="$(grep -o '"version"[[:space:]]*:[[:space:]]*"[^"]*"' "$MANIFEST_FILE" | head -1 | sed -E 's/.*"([^"]+)"$/\1/')"
-  mf_preset="$(grep -o '"preset"[[:space:]]*:[[:space:]]*"[^"]*"' "$MANIFEST_FILE" | head -1 | sed -E 's/.*"([^"]+)"$/\1/')"
-  echo "manifest.version: ${mf_version:-?}"
-  echo "manifest.preset: ${mf_preset:-?}"
-  if [[ -n "${CYNING_HARNESS:-}" && -f "$CYNING_HARNESS/package.json" ]]; then
-    pkg_version="$(grep '"version"' "$CYNING_HARNESS/package.json" | head -1 | sed -E 's/.*:[[:space:]]*"([^"]+)".*/\1/')"
-    if [[ -n "$pkg_version" && -n "$mf_version" && "$mf_version" != "$pkg_version" ]]; then
-      echo "提示: manifest 版本 ($mf_version) 与产品包 ($pkg_version) 不一致 · 可运行 upgrade"
+# D3 · Inform 图谱闸：输出模块/流程文件 + 审核状态摘要
+graph_for_task() {
+  local tf="$1"
+  local graph_status
+  graph_status="$(gate_status "$tf" HG-GRAPH-MODULES)"
+  local tech_graph_dir="$TARGET/docs/_tech_graph"
+
+  local files=()
+  if [[ -d "$tech_graph_dir" ]]; then
+    while IFS= read -r -d '' f; do
+      files+=("$f")
+    done < <(find "$tech_graph_dir" -maxdepth 2 -type f -print0 2>/dev/null)
+  fi
+
+  if [[ "$JSON_MODE" == "1" ]]; then
+    printf '{"task":"%s","hg_graph_modules":"%s","tech_graph_dir":"%s","files":[' "$(basename "$tf")" "${graph_status:-unknown}" "$tech_graph_dir"
+    local first=1
+    if [[ ${#files[@]} -gt 0 ]]; then
+      for f in "${files[@]}"; do
+        [[ "$first" == "1" ]] || printf ','
+        first=0
+        local name status
+        name="$(basename "$f")"
+        status="$(file_audit_status "$f")"
+        printf '{"name":"%s","status":"%s"}' "$name" "$status"
+      done
     fi
+    printf ']}'
+    return 0
   fi
-else
-  echo "manifest: (未接入 · 无 $MANIFEST_FILE)"
+
+  echo "=== Harness gate-check --graph ==="
+  echo "task: $(basename "$tf")"
+  echo "HG-GRAPH-MODULES: ${graph_status:-未声明}"
+  echo ""
+
+  if [[ ${#files[@]} -eq 0 ]]; then
+    printf 'WARN: 未找到 %s（docs-only task 友好：warn 不 fail）\n' "$tech_graph_dir"
+    echo ""
+    return 0
+  fi
+
+  echo "| 模块/流程文件 | 审核状态 |"
+  echo "|-------------|----------|"
+  for f in "${files[@]}"; do
+    printf "| %s | %s |\n" "$(basename "$f")" "$(file_audit_status "$f")"
+  done
+  echo ""
+}
+
+file_audit_status() {
+  local f="$1"
+  local name
+  name="$(basename "$f")"
+  # 文件名或内容含 approved / rejected / pending 即视为状态摘要
+  if [[ "$name" == *approved* ]] || grep -iq 'status.*approved\|状态.*approved' "$f" 2>/dev/null; then
+    echo "approved"
+  elif [[ "$name" == *rejected* ]] || grep -iq 'status.*rejected\|状态.*rejected' "$f" 2>/dev/null; then
+    echo "rejected"
+  elif [[ "$name" == *pending* ]] || grep -iq 'status.*pending\|状态.*pending' "$f" 2>/dev/null; then
+    echo "pending"
+  else
+    echo "unknown"
+  fi
+}
+
+if [[ "$JSON_MODE" != "1" ]]; then
+  echo "=== Harness gate-check ==="
+  echo "目标: $TARGET"
+
+  MANIFEST_FILE="$TARGET/.cyning-harness/manifest.json"
+  if [[ -f "$MANIFEST_FILE" ]]; then
+    mf_version="$(grep -o '"version"[[:space:]]*:[[:space:]]*"[^"]*"' "$MANIFEST_FILE" | head -1 | sed -E 's/.*"([^"]+)"$/\1/')"
+    mf_preset="$(grep -o '"preset"[[:space:]]*:[[:space:]]*"[^"]*"' "$MANIFEST_FILE" | head -1 | sed -E 's/.*"([^"]+)"$/\1/')"
+    echo "manifest.version: ${mf_version:-?}"
+    echo "manifest.preset: ${mf_preset:-?}"
+    if [[ -n "${CYNING_HARNESS:-}" && -f "$CYNING_HARNESS/package.json" ]]; then
+      pkg_version="$(grep '"version"' "$CYNING_HARNESS/package.json" | head -1 | sed -E 's/.*:[[:space:]]*"([^"]+)".*/\1/')"
+      if [[ -n "$pkg_version" && -n "$mf_version" && "$mf_version" != "$pkg_version" ]]; then
+        echo "提示: manifest 版本 ($mf_version) 与产品包 ($pkg_version) 不一致 · 可运行 upgrade"
+      fi
+    fi
+  else
+    echo "manifest: (未接入 · 无 $MANIFEST_FILE)"
+  fi
+  echo ""
 fi
-echo ""
 
 BLOCKED=0
 
+if [[ "$GRAPH_MODE" == "1" ]]; then
+  if [[ "$JSON_MODE" == "1" ]]; then
+    printf '['
+  fi
+  local_first=1
+  if [[ -n "$TASK_FILE" ]]; then
+    if [[ "$TASK_FILE" != /* ]]; then
+      TASK_FILE="$TARGET/$TASK_FILE"
+    fi
+    if [[ ! -f "$TASK_FILE" ]]; then
+      echo "错误: 未找到 --task 文件 $TASK_FILE" >&2
+      exit 1
+    fi
+    graph_for_task "$TASK_FILE"
+  else
+    ACTIVE_DIR="$TARGET/docs/tasks/active"
+    if [[ ! -d "$ACTIVE_DIR" ]]; then
+      if [[ "$JSON_MODE" == "1" ]]; then
+        printf ']\n'
+      else
+        echo "⚠️  无 $ACTIVE_DIR" >&2
+      fi
+      exit 0
+    fi
+    TASK_FILES=("$ACTIVE_DIR"/task_*.md)
+    if [[ ! -e "${TASK_FILES[0]}" ]]; then
+      if [[ "$JSON_MODE" == "1" ]]; then
+        printf ']\n'
+      else
+        echo "无 active task_*.md"
+      fi
+      exit 0
+    fi
+    for tf in "$ACTIVE_DIR"/task_*.md; do
+      [[ -f "$tf" ]] || continue
+      if [[ "$JSON_MODE" == "1" ]]; then
+        [[ "$local_first" == "1" ]] || printf ','
+        local_first=0
+      fi
+      graph_for_task "$tf"
+    done
+  fi
+  if [[ "$JSON_MODE" == "1" ]]; then
+    printf ']\n'
+  fi
+  exit 0
+fi
+
 if [[ -n "$TASK_FILE" ]]; then
   if [[ "$TASK_FILE" != /* ]]; then
     TASK_FILE="$TARGET/$TASK_FILE"

package/wizard/harness-sync.sh

@@ -23,6 +23,8 @@ usage() {
 
   "$CYNING_HARNESS/wizard/harness-sync.sh" apply
 
+  "$CYNING_HARNESS/wizard/harness-sync.sh" --index --target /path/to/project
+
 或：
 
   "$CYNING_HARNESS/wizard/harness-sync.sh" plan --target /path/to/project
@@ -31,14 +33,16 @@ usage() {
 
 依赖：业务仓已有 .cyning-harness/profile.json（由 install.sh 生成）
 
-plan  — 仅打印将复制的文件
-apply — 执行复制（S5：git 仓须工作区干净，或 --force）
+plan   — 仅打印将复制的文件
+apply  — 执行复制（S5：git 仓须工作区干净，或 --force）
+--index — 生成 .cyning-harness/invoke_index.json（只读聚合 invokes/by-task，不覆盖 S2 域）
 EOF
 }
 
 while [[ $# -gt 0 ]]; do
   case "$1" in
     plan|apply) MODE="$1"; shift ;;
+    --index) MODE="index"; shift ;;
     --target) TARGET="$2"; shift 2 ;;
     --force) SYNC_FORCE=1; shift ;;
     -h|--help) usage; exit 0 ;;
@@ -46,12 +50,21 @@ while [[ $# -gt 0 ]]; do
   esac
 done
 
-[[ "$MODE" == "plan" || "$MODE" == "apply" ]] || { usage; exit 1; }
+[[ "$MODE" == "plan" || "$MODE" == "apply" || "$MODE" == "index" ]] || { usage; exit 1; }
 
 CYNING_HARNESS="${CYNING_HARNESS:-$HARNESS_ROOT}"
 refuse_if_product_root "$TARGET" "$HARNESS_ROOT"
 PROFILE_FILE="$TARGET/.cyning-harness/profile.json"
 
+if [[ "$MODE" == "index" ]]; then
+  if [[ ! -d "$TARGET" ]]; then
+    echo "错误: 目标目录不存在 $TARGET" >&2
+    exit 1
+  fi
+  node "$SCRIPT_DIR/lib/generate-invoke-index.js" "$TARGET"
+  exit 0
+fi
+
 if [[ ! -f "$PROFILE_FILE" ]]; then
   echo "错误: 未找到 $PROFILE_FILE" >&2
   echo "请先运行: $CYNING_HARNESS/wizard/install.sh --target $TARGET --preset <name>" >&2

package/wizard/install.sh

@@ -148,6 +148,7 @@ if [[ "$DRY_RUN" == "1" ]]; then
 else
   "$SCRIPT_DIR/harness-sync.sh" apply --target "$TARGET"
   write_manifest_init "$TARGET" "$VERSION" "$PRESET" "$IDE_LIST" "$PROFILE_DST"
+  run cp "$CYNING_HARNESS/harness/templates/QUICKREF_v1_zh.md" "$TARGET/.cyning-harness/QUICKREF.md"
 fi
 
 # CI
@@ -201,6 +202,7 @@ fi
 echo ""
 echo "安装完成。profile: $PROFILE_DST"
 echo "manifest: $(manifest_file_path "$TARGET")"
-echo "日后升级: npx @cyning/harness upgrade --target $TARGET"
-echo "或维护者: cd $CYNING_HARNESS && ./wizard/upgrade.sh --target $TARGET"
-echo "清空重装: $CYNING_HARNESS/wizard/uninstall.sh --target $TARGET"
+echo "常用命令:"
+echo "  npx @cyning/harness verify --target $TARGET"
+echo "  npx @cyning/harness gate-check --target $TARGET"
+echo "  npx @cyning/harness upgrade --target $TARGET --yes"

package/wizard/lib/generate-invoke-index.js

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+// 生成 .cyning-harness/invoke_index.json（harness-sync --index 的 JSON 引擎）
+import fs from 'node:fs';
+import path from 'node:path';
+
+const target = process.argv[2];
+if (!target) {
+  console.error('用法: node generate-invoke-index.js /path/to/target-repo');
+  process.exit(1);
+}
+
+const byTaskDir = path.join(target, 'docs/harness/invokes/by-task');
+const indexFile = path.join(target, '.cyning-harness/invoke_index.json');
+
+function extractHatId(filename) {
+  // invoke_YYYYMMDD_<hat_id>_*.md 或 invoke_YYYYMMDD_<hat_id>.md
+  const base = path.basename(filename, '.md');
+  const parts = base.split('_');
+  if (parts.length >= 3 && parts[0] === 'invoke') {
+    return parts[2];
+  }
+  return 'unknown';
+}
+
+const index = {
+  schema_version: '1',
+  generated_at: new Date().toISOString(),
+  index: {},
+};
+
+if (fs.existsSync(byTaskDir)) {
+  for (const entry of fs.readdirSync(byTaskDir, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    const slug = entry.name;
+    const slugDir = path.join(byTaskDir, slug);
+    const invokes = [];
+
+    for (const file of fs.readdirSync(slugDir)) {
+      if (!file.startsWith('invoke_') || !file.endsWith('.md')) continue;
+      const full = path.join(slugDir, file);
+      const stat = fs.statSync(full);
+      invokes.push({
+        path: path.relative(target, full).replace(/\\/g, '/'),
+        mtime: Math.floor(stat.mtimeMs / 1000),
+        hat_id: extractHatId(file),
+      });
+    }
+
+    invokes.sort((a, b) => a.path.localeCompare(b.path));
+
+    index.index[slug] = {
+      task_slug: slug,
+      invokes,
+    };
+  }
+}
+
+fs.mkdirSync(path.dirname(indexFile), { recursive: true });
+fs.writeFileSync(indexFile, JSON.stringify(index, null, 2) + '\n');
+console.log(`invoke_index: ${indexFile}`);