homegraph 1.5.1 → 1.5.3

package/scripts/agent-eval/run-all.sh

@@ -1,75 +0,0 @@
-#!/usr/bin/env bash
-# With/without A/B (and optional interactive) eval for a homegraph version on a
-# repo. Codegraph is the ONLY variable: both arms launch claude with
-# --strict-mcp-config — with = homegraph-only MCP (pointed at $CG_BIN),
-# without = empty MCP. Built-in Read/Grep/Bash stay available in both arms.
-#
-# Usage: run-all.sh <repo-path> "<question>" [headless|tmux|all]
-# Env:   CG_BIN          homegraph binary (default: command -v homegraph)
-#        AGENT_EVAL_OUT  output dir (default: /tmp/agent-eval)
-#        MODEL / EFFORT  claude model/effort (default: sonnet / high — the
-#                        standing A/B policy; see CLAUDE.md, don't raise)
-set -uo pipefail
-
-REPO="${1:?usage: run-all.sh <repo-path> \"<question>\" [headless|tmux|all]}"
-Q="${2:?question required}"
-MODE="${3:-headless}"
-CG_BIN="${CG_BIN:-$(command -v homegraph)}"
-OUT="${AGENT_EVAL_OUT:-/tmp/agent-eval}"
-HARNESS="$(cd "$(dirname "$0")" && pwd)"
-mkdir -p "$OUT"
-
-# Neutralize any ambient HomeGraph prompt-hook (~/.claude) in BOTH arms:
-# the hook injects homegraph context into every prompt, which contaminates
-# the without-arm (free structural context) and double-counts the with-arm.
-# The A/B's only variable must be the MCP server wired below.
-export HOMEGRAPH_NO_PROMPT_HOOK=1
-
-[ -n "$CG_BIN" ] || { echo "no homegraph binary on PATH (set CG_BIN)"; exit 1; }
-[ -d "$REPO/.homegraph" ] || { echo "no .homegraph index at $REPO — index it first"; exit 1; }
-case "$MODE" in headless|tmux|all) ;; *) echo "mode must be headless|tmux|all (got '$MODE')"; exit 1;; esac
-
-# MCP config files (path form avoids inline-JSON quoting through tmux).
-cat > "$OUT/mcp-homegraph.json" <<JSON
-{"mcpServers":{"homegraph":{"command":"$CG_BIN","args":["serve","--mcp","--path","$REPO"]}}}
-JSON
-echo '{"mcpServers":{}}' > "$OUT/mcp-empty.json"
-
-echo "###### homegraph: $CG_BIN"
-echo "###### repo:      $REPO"
-echo "###### question:  $Q"
-echo
-
-# Headless arm: claude -p with stream-json -> exact tool sequence + tokens/cost.
-headless() {
-  local label="$1" cfg="$2"
-  echo "############################## HEADLESS [$label] ##############################"
-  ( cd "$REPO" && claude -p "$Q" \
-      --output-format stream-json --verbose \
-      --permission-mode bypassPermissions \
-      --model "${MODEL:-sonnet}" --effort "${EFFORT:-high}" \
-      --max-budget-usd 4 \
-      --strict-mcp-config --mcp-config "$cfg" \
-      > "$OUT/run-$label.jsonl" 2>"$OUT/run-$label.err" )
-  echo "exit $? -> $OUT/run-$label.jsonl ($(wc -l < "$OUT/run-$label.jsonl" | tr -d ' ') lines)"
-  tail -2 "$OUT/run-$label.err" 2>/dev/null
-  node "$HARNESS/parse-run.mjs" "$OUT/run-$label.jsonl" 2>&1 || true
-  echo
-}
-
-if [ "$MODE" = headless ] || [ "$MODE" = all ]; then
-  headless "headless-with"    "$OUT/mcp-homegraph.json"
-  headless "headless-without" "$OUT/mcp-empty.json"
-fi
-
-if [ "$MODE" = tmux ] || [ "$MODE" = all ]; then
-  echo "############################## INTERACTIVE [with] ##############################"
-  CLAUDE_EXTRA_ARGS="--model ${MODEL:-sonnet} --effort ${EFFORT:-high} --strict-mcp-config --mcp-config $OUT/mcp-homegraph.json" \
-    bash "$HARNESS/itrun.sh" "$REPO" "int-with" "$Q" 2>&1 || echo "[itrun WITH failed]"
-  echo
-  echo "############################## INTERACTIVE [without] ##############################"
-  CLAUDE_EXTRA_ARGS="--model ${MODEL:-sonnet} --effort ${EFFORT:-high} --strict-mcp-config --mcp-config $OUT/mcp-empty.json" \
-    bash "$HARNESS/itrun.sh" "$REPO" "int-without" "$Q" 2>&1 || echo "[itrun WITHOUT failed]"
-  echo
-fi
-echo "############################## RUN-ALL COMPLETE ##############################"

package/scripts/agent-eval/run-arms.sh

@@ -1,56 +0,0 @@
-#!/usr/bin/env bash
-# Tool-surface ablation — run ONE repo+question under ONE arm.
-#
-# Arms vary (exposed homegraph tools, trace-first steering). Tools are trimmed
-# SERVER-SIDE via HOMEGRAPH_MCP_TOOLS in the MCP config's `env` block, so an
-# ablated tool is genuinely absent from ListTools — no deferred-ToolSearch or
-# denied-call confound (which --disallowedTools would introduce). Steering is
-# injected with --append-system-prompt, so no rebuild of the shipped
-# server-instructions is needed to A/B it.
-#
-#   A control       all tools            no steering
-#   B steer         all tools            trace-first
-#   C no-explore    hide explore         trace-first
-#   D trace-centric hide explore+context trace-first
-#   E control-probe hide explore+context trace-first  (caller passes a NON-flow Q)
-#
-# Usage: run-arms.sh <repo-path> "<question>" <A|B|C|D|E> [run-id]
-set -uo pipefail
-REPO="${1:?repo path}"; Q="${2:?question}"; ARM="${3:?arm A-E}"; RID="${4:-1}"
-CG_BIN="${CG_BIN:-$(command -v homegraph)}"
-OUT="${ARMS_OUT:-/tmp/arms}/$(basename "$REPO")"
-mkdir -p "$OUT"
-[ -n "$CG_BIN" ] || { echo "no homegraph binary (set CG_BIN)"; exit 1; }
-[ -d "$REPO/.homegraph" ] || { echo "no .homegraph index at $REPO"; exit 1; }
-
-STEER='Flow questions ("how does X reach/become Y", "trace the flow", request to handler, state to render): call homegraph_trace(from,to) FIRST — one call returns the whole path. Use homegraph_context/search only to locate the two endpoint symbols if you do not know them. Do NOT reconstruct the path with repeated search/callers/explore.'
-KEEP_NO_EXPLORE="trace,search,node,context,callers,callees,impact,files,status"
-KEEP_TRACE_CENTRIC="trace,search,node,callers,callees,impact,files,status"
-
-case "$ARM" in
-  A|G|H|I) TOOLS="";            STEERING="" ;;  # no steering; H = body-trace, I = body-trace + destination callees (sufficiency)
-  B|F) TOOLS="";                STEERING="$STEER" ;;  # F = B's surface, run on the body-inlining trace build
-  C) TOOLS="$KEEP_NO_EXPLORE";  STEERING="$STEER" ;;
-  D|E) TOOLS="$KEEP_TRACE_CENTRIC"; STEERING="$STEER" ;;
-  *) echo "bad arm '$ARM' (want A|B|C|D|E)"; exit 1 ;;
-esac
-
-CFG="$OUT/mcp-$ARM.json"
-if [ -n "$TOOLS" ]; then
-  cat > "$CFG" <<JSON
-{"mcpServers":{"homegraph":{"command":"$CG_BIN","args":["serve","--mcp","--path","$REPO"],"env":{"HOMEGRAPH_MCP_TOOLS":"$TOOLS"}}}}
-JSON
-else
-  cat > "$CFG" <<JSON
-{"mcpServers":{"homegraph":{"command":"$CG_BIN","args":["serve","--mcp","--path","$REPO"]}}}
-JSON
-fi
-
-LOG="$OUT/$ARM-r$RID.jsonl"; ERR="$OUT/$ARM-r$RID.err"
-ARGS=( -p "$Q" --output-format stream-json --verbose
-       --permission-mode bypassPermissions --model "${MODEL:-sonnet}" --effort "${EFFORT:-high}" --max-budget-usd 4
-       --strict-mcp-config --mcp-config "$CFG" )
-[ -n "$STEERING" ] && ARGS+=( --append-system-prompt "$STEERING" )
-
-( cd "$REPO" && claude "${ARGS[@]}" > "$LOG" 2>"$ERR" )
-echo "[$(basename "$REPO") $ARM r$RID] exit $? -> $LOG ($(wc -l < "$LOG" | tr -d ' ') lines)"

package/scripts/agent-eval/seq-matrix.mjs

@@ -1,137 +0,0 @@
-#!/usr/bin/env node
-// Mine the surviving A/B stream-json logs (/tmp/ab-matrix/<Cell>/run-headless-*.jsonl)
-// for what the aggregate matrix can't see: the call SEQUENCE and per-call output SIZE.
-//
-// Answers three questions:
-//   1. Trace adoption — on a flow question, does the with-arm actually call homegraph_trace?
-//   2. Payload size vs repo size — is trace path-scoped (tiny, size-independent) while
-//      explore is breadth-scoped (grows with the repo / over-returns on small repos)?
-//   3. Round-trips — num_turns with vs without (the real wall-clock driver).
-//
-// Usage: node scripts/agent-eval/seq-matrix.mjs [/tmp/ab-matrix]
-import { readFileSync, readdirSync, existsSync } from 'fs';
-import { join } from 'path';
-
-const AB = process.argv[2] || '/tmp/ab-matrix';
-const MD = new URL('../../docs/benchmarks/homegraph-ab-matrix.md', import.meta.url).pathname;
-
-// repo -> {lang,size,files} from the published matrix table
-const repoMeta = {};
-if (existsSync(MD)) for (const line of readFileSync(MD, 'utf8').split('\n')) {
-  const m = line.match(/^\|\s*([^|]+?)\s*\|\s*(S|M|L)\s*\|\s*`([^`]+)`\s*\|\s*(\d+)\s*\|/);
-  if (m) repoMeta[m[3]] = { lang: m[1].trim(), size: m[2], files: +m[4] };
-}
-
-const cgShort = (n) => n.replace('mcp__homegraph__homegraph_', '').replace('mcp__homegraph__', '');
-const tag = (n) => n === 'Read' ? 'R' : n === 'Grep' ? 'G' : n === 'Glob' ? 'Gl'
-  : n === 'Bash' ? 'B' : n === 'Task' ? 'Ag' : n === 'ToolSearch' ? 'TS'
-  : n.includes('homegraph') ? cgShort(n) : n;
-
-function parse(file) {
-  if (!existsSync(file)) return null;
-  const lines = readFileSync(file, 'utf8').split('\n').filter(Boolean);
-  const calls = []; let result = null, initCg = 0;
-  for (const l of lines) {
-    let ev; try { ev = JSON.parse(l); } catch { continue; }
-    if (ev.type === 'system' && ev.subtype === 'init') initCg = (ev.tools || []).filter(t => /homegraph/.test(t)).length;
-    if (ev.type === 'assistant') for (const b of (ev.message?.content || [])) if (b.type === 'tool_use') {
-      const i = b.input || {};
-      const q = i.query ?? i.symbol ?? i.task ?? (i.from && i.to ? `${i.from}->${i.to}` : (i.file_path || i.command || ''));
-      calls.push({ id: b.id, name: b.name, q: String(q ?? '').slice(0, 38), out: 0 });
-    }
-    if (ev.type === 'user') for (const b of (ev.message?.content || [])) if (b.type === 'tool_result') {
-      const c = b.content;
-      const txt = typeof c === 'string' ? c : Array.isArray(c) ? c.map(x => x?.text || '').join('') : '';
-      const call = calls.find(k => k.id === b.tool_use_id); if (call) call.out = txt.length;
-    }
-    if (ev.type === 'result') result = ev;
-  }
-  const cg = calls.filter(c => c.name.includes('homegraph'));
-  const perTool = {};
-  for (const c of cg) { const k = cgShort(c.name); (perTool[k] ??= { n: 0, out: 0 }); perTool[k].n++; perTool[k].out += c.out; }
-  const traceIdx = cg.findIndex(c => c.name.includes('trace'));
-  const u = result?.usage || {};
-  return {
-    initCg, cg, perTool,
-    cgSeq: cg.map(c => cgShort(c.name)),
-    seq: calls.map(c => tag(c.name)),
-    reads: calls.filter(c => c.name === 'Read').length,
-    greps: calls.filter(c => c.name === 'Grep').length,
-    cgOut: cg.reduce((s, c) => s + c.out, 0),
-    traceUsed: traceIdx >= 0,
-    afterTrace: traceIdx >= 0 ? cg.slice(traceIdx + 1).map(c => cgShort(c.name)) : null,
-    turns: result?.num_turns ?? null,
-    dur: result?.duration_ms ? Math.round(result.duration_ms / 1000) : null,
-    cost: result?.total_cost_usd || 0,
-  };
-}
-
-const cells = [];
-for (const d of readdirSync(AB)) {
-  const dir = join(AB, d);
-  if (!existsSync(join(dir, 'run-headless-with.jsonl'))) continue;
-  const log = existsSync(join(AB, d + '.log')) ? readFileSync(join(AB, d + '.log'), 'utf8') : '';
-  const repo = (log.match(/repo:\s*\S*\/([^\s/]+)/) || [])[1] || d;
-  const question = (log.match(/question:\s*(.+)/) || [])[1] || '';
-  cells.push({ cell: d, repo, question, ...(repoMeta[repo] || {}),
-    with: parse(join(dir, 'run-headless-with.jsonl')),
-    without: parse(join(dir, 'run-headless-without.jsonl')) });
-}
-cells.sort((a, b) => (a.files || 0) - (b.files || 0));
-
-const k = (n) => (n / 1000).toFixed(1);
-const pad = (s, n) => String(s).padEnd(n);
-
-// ---- per-cell sequence table ----
-console.log('\n=== PER-CELL: with-arm homegraph sequence + payload (sorted by repo size) ===');
-console.log(pad('repo', 22), pad('files', 6), 'trace', pad('cg-call sequence', 40), pad('cgOutK', 7), 'turns(w/wo)');
-for (const c of cells) {
-  const w = c.with;
-  console.log(
-    pad(c.repo, 22), pad(c.files ?? '?', 6),
-    pad(w.traceUsed ? 'YES' : 'no', 5),
-    pad(w.cgSeq.join(',') || '(none)', 40),
-    pad(k(w.cgOut), 7),
-    `${w.turns}/${c.without?.turns}`,
-  );
-}
-
-// ---- trace adoption ----
-const flow = cells; // every matrix question is a canonical flow question by design
-const used = flow.filter(c => c.with.traceUsed);
-console.log(`\n=== TRACE ADOPTION (all ${flow.length} cells are flow questions) ===`);
-console.log(`trace called in ${used.length}/${flow.length} cells`);
-console.log('used trace:', used.map(c => c.repo).join(', ') || '(none)');
-if (used.length) console.log('after-trace follow-ups:', used.map(c => `${c.repo}[${c.with.afterTrace.join(',') || 'none'}]`).join('  '));
-
-// ---- payload size by repo-size tier ----
-const tier = (f) => f < 200 ? 'S(<200)' : f < 2000 ? 'M(<2000)' : 'L(>=2000)';
-const byTier = {};
-for (const c of cells) { (byTier[tier(c.files || 0)] ??= []).push(c.with.cgOut); }
-console.log('\n=== with-arm TOTAL homegraph payload by repo-size tier ===');
-for (const t of ['S(<200)', 'M(<2000)', 'L(>=2000)']) {
-  const a = byTier[t] || []; if (!a.length) continue;
-  const avg = a.reduce((s, x) => s + x, 0) / a.length;
-  console.log(`  ${pad(t, 10)} n=${a.length}  avg cgOut=${k(avg)}K  range ${k(Math.min(...a))}-${k(Math.max(...a))}K`);
-}
-
-// ---- per-tool usage + avg payload (breadth vs path evidence) ----
-const tot = {};
-for (const c of cells) for (const [name, v] of Object.entries(c.with.perTool)) {
-  (tot[name] ??= { n: 0, out: 0 }); tot[name].n += v.n; tot[name].out += v.out;
-}
-console.log('\n=== homegraph tool usage across all cells (n calls, avg payload/call) ===');
-for (const [name, v] of Object.entries(tot).sort((a, b) => b[1].n - a[1].n)) {
-  console.log(`  ${pad(name, 10)} calls=${pad(v.n, 4)} avg=${k(v.out / v.n)}K/call  total=${k(v.out)}K`);
-}
-
-// ---- round-trips ----
-const sum = (arr, f) => arr.reduce((s, x) => s + (f(x) || 0), 0);
-const wTurns = sum(cells, c => c.with.turns), woTurns = sum(cells, c => c.without?.turns);
-const wCalls = sum(cells, c => c.with.cg.length);
-const tsAll = cells.every(c => c.with.seq[0] === 'TS');
-console.log('\n=== ROUND-TRIPS ===');
-console.log(`turns: with=${wTurns}  without=${woTurns}  (${((1 - wTurns / woTurns) * 100).toFixed(0)}% fewer with)`);
-console.log(`avg turns/cell: with=${(wTurns / cells.length).toFixed(1)}  without=${(woTurns / cells.length).toFixed(1)}`);
-console.log(`total homegraph calls=${wCalls} (avg ${(wCalls / cells.length).toFixed(1)}/cell)`);
-console.log(`every with-arm opens with a ToolSearch round-trip (deferred tools): ${tsAll ? 'YES — 1 fixed tax/run' : 'no'}`);

package/scripts/build-bundle.sh

@@ -1,123 +0,0 @@
-#!/usr/bin/env bash
-#
-# Build a self-contained HomeGraph bundle: an official Node runtime + the
-# compiled app + its production deps, so HomeGraph runs with NO system Node and
-# NO native build — node:sqlite is built into the bundled Node. One archive per
-# platform.
-#
-# Because dropping better-sqlite3 left zero native addons, the recipe is pure
-# file-packaging (download the target's Node, copy the app, archive) — so any
-# platform's bundle can be built on any OS. No cross-compile, no native runners.
-#
-# Usage:
-#   scripts/build-bundle.sh <target> [node-version]
-#     target:        darwin-arm64 | darwin-x64 | linux-x64 | linux-arm64
-#                  | win32-x64 | win32-arm64
-#     node-version:  e.g. v24.16.0 (default below; pin for reproducible builds)
-#
-# Output:
-#   unix:    release/homegraph-<target>.tar.gz   (launcher: bin/homegraph)
-#   windows: release/homegraph-<target>.zip      (launcher: bin/homegraph.cmd)
-set -euo pipefail
-
-TARGET="${1:?usage: build-bundle.sh <target> [node-version]}"
-NODE_VERSION="${2:-v24.16.0}"
-
-ROOT="$(cd "$(dirname "$0")/.." && pwd)"
-OUT="$ROOT/release"
-WORK="$(mktemp -d)"
-trap 'rm -rf "$WORK"' EXIT
-
-ARCH="${TARGET##*-}"   # x64 | arm64
-OSFAM="${TARGET%-*}"   # darwin | linux | win32
-
-echo "[bundle] target=${TARGET} node=${NODE_VERSION}"
-
-# 1. Download + extract the official Node runtime for the target platform.
-if [ "$OSFAM" = "win32" ]; then
-  NODE_DIST="node-${NODE_VERSION}-win-${ARCH}"
-  NODE_URL="https://nodejs.org/dist/${NODE_VERSION}/${NODE_DIST}.zip"
-  echo "[bundle] downloading ${NODE_URL}"
-  curl -fsSL "$NODE_URL" -o "$WORK/node.zip"
-  if command -v unzip >/dev/null 2>&1; then
-    unzip -q "$WORK/node.zip" -d "$WORK"
-  else
-    tar -xf "$WORK/node.zip" -C "$WORK"   # bsdtar can read zip
-  fi
-  NODE_BIN="$WORK/${NODE_DIST}/node.exe"
-else
-  NODE_DIST="node-${NODE_VERSION}-${TARGET}"
-  NODE_URL="https://nodejs.org/dist/${NODE_VERSION}/${NODE_DIST}.tar.gz"
-  echo "[bundle] downloading ${NODE_URL}"
-  curl -fsSL "$NODE_URL" -o "$WORK/node.tar.gz"
-  tar -xzf "$WORK/node.tar.gz" -C "$WORK"
-  NODE_BIN="$WORK/${NODE_DIST}/bin/node"
-fi
-[ -f "$NODE_BIN" ] || { echo "[bundle] error: node binary not found ($NODE_BIN)" >&2; exit 1; }
-
-# 2. Build the app (compiled JS + copied wasm/schema assets).
-echo "[bundle] building app"
-( cd "$ROOT" && npm run build >/dev/null )
-
-# 3. Stage: app + production-only deps (pure JS/wasm → portable across platforms).
-STAGE="$WORK/homegraph-${TARGET}"
-mkdir -p "$STAGE/lib" "$STAGE/bin"
-cp -R "$ROOT/dist" "$STAGE/lib/dist"
-cp "$ROOT/package.json" "$ROOT/package-lock.json" "$STAGE/lib/"
-echo "[bundle] installing production dependencies"
-( cd "$STAGE/lib" && npm ci --omit=dev --ignore-scripts >/dev/null 2>&1 )
-rm -f "$STAGE/lib/package-lock.json"
-
-# 4. Vendored Node + launcher (the launcher uses the bundled Node by relative
-#    path, so no system Node is ever needed).
-#
-# `--liftoff-only`: keep tree-sitter's large WASM grammars on V8's Liftoff
-# baseline compiler so they never reach the turboshaft optimizing tier, whose
-# per-compilation Zone arena OOMs the whole process (`Fatal process out of
-# memory: Zone`) on Node >= 22 — even with tens of GB free. The flag is read at
-# V8 engine init so it must be on node's command line; the parse worker inherits
-# it. See issues #293/#298 and src/extraction/wasm-runtime-flags.ts. (The CLI
-# also self-relaunches with this flag when launched without it, so non-bundled
-# runs are covered too; passing it here avoids that extra spawn.)
-if [ "$OSFAM" = "win32" ]; then
-  cp "$NODE_BIN" "$STAGE/node.exe"
-  printf '@"%%~dp0..\\node.exe" --liftoff-only "%%~dp0..\\lib\\dist\\bin\\homegraph.js" %%*\r\n' \
-    > "$STAGE/bin/homegraph.cmd"
-else
-  cp "$NODE_BIN" "$STAGE/node"
-  cat > "$STAGE/bin/homegraph" <<'LAUNCH'
-#!/bin/sh
-# Resolve symlinks (e.g. the ~/.local/bin/homegraph link install.sh creates) so
-# we find the real bundle dir, not the symlink's location.
-SELF="$0"
-while [ -L "$SELF" ]; do
-  target="$(readlink "$SELF")"
-  case "$target" in
-    /*) SELF="$target" ;;
-    *) SELF="$(dirname "$SELF")/$target" ;;
-  esac
-done
-DIR="$(cd "$(dirname "$SELF")/.." && pwd)"
-# Thread the MCP host's pid to the server's orphan watchdog (issue #1185).
-# $PPID is our parent — the host itself when it launched this script directly;
-# an already-threaded value (the npm shim sets the true host pid) wins.
-HOMEGRAPH_HOST_PPID="${HOMEGRAPH_HOST_PPID:-$PPID}"
-export HOMEGRAPH_HOST_PPID
-# --liftoff-only: avoid the V8 turboshaft WASM Zone OOM (issues #293/#298).
-exec "$DIR/node" --liftoff-only "$DIR/lib/dist/bin/homegraph.js" "$@"
-LAUNCH
-  chmod +x "$STAGE/bin/homegraph"
-fi
-
-# 5. Archive (.zip for Windows, .tar.gz otherwise).
-mkdir -p "$OUT"
-if [ "$OSFAM" = "win32" ]; then
-  ARCHIVE="$OUT/homegraph-${TARGET}.zip"
-  rm -f "$ARCHIVE"
-  ( cd "$WORK" && zip -rqX "$ARCHIVE" "homegraph-${TARGET}" )
-else
-  ARCHIVE="$OUT/homegraph-${TARGET}.tar.gz"
-  # --no-xattrs: don't embed macOS xattrs that make GNU tar warn on Linux.
-  tar --no-xattrs -czf "$ARCHIVE" -C "$WORK" "homegraph-${TARGET}"
-fi
-echo "[bundle] wrote ${ARCHIVE} ($(du -h "$ARCHIVE" | cut -f1))"

package/scripts/exp_boundary_eval/README.md

@@ -1,247 +0,0 @@
-# 边界评测（exp_boundary_eval）
-
-在 OpenHarmony **Photos** 仓库上，对比 Agent **不带 HomeGraph（baseline）** 与 **带 HomeGraph MCP（homegraph）** 的探索行为：档位切换、跨层穿透、幻觉/遗漏风险等。
-
-跑完实验后脚本会**自动生成**各组分析报告和 A/B 对比报告（Markdown），路径会在控制台打印。
-
----
-
-## 快速开始
-
-```powershell
-cd D:\code\homegraph
-npm run build
-
-cd D:\code\homegraph\scripts\exp_boundary_eval
-# 一条命令：先 index/校验 → homegraph 组 → baseline 组 → 自动出报告
-# 不要另开终端同时跑 node … index，会与 index 抢 .homegraph 锁
-python run_all.py --both-arms --agent deveco --repo-path D:\code\homegraph\scripts\exp_boundary_eval\data\clone
-```
-
-**前置条件**
-
-| 项 | 说明 |
-|----|------|
-| Python | 3.8+（Windows 建议用本机 Python，不要用 WSL 跑 DevEco） |
-| Agent CLI | `deveco` / `claude` 等已在 PATH；DevEco 可用 `DEVECO_BIN` 指定路径 |
-| git | 用于 clone / 重置测试仓库 |
-| homegraph 组 | 在仓库根目录先执行 `npm run build` |
-
-**DevEco 模型**：无需在本脚本里配置；使用 DevEco Studio / CLI 里已配好的默认模型即可。
-
----
-
-## 目录与文件说明
-
-```
-scripts/exp_boundary_eval/
-├── README.md              ← 本文件
-├── run_all.py             ← 主入口：批量跑实验，跑完自动 analyze + 对比报告
-├── run_one.py             ← 单个 one-shot 实验
-├── run_session.py         ← 多轮会话实验（实验 5）
-├── analyze.py             ← 分析脚本（也可单独对历史结果目录运行）
-├── setup.py               ← 每次实验前：重置仓库、清 CLAUDE.md、生成 session
-├── _utils.py              ← 公共工具：Agent 注册、输出解析、目录创建
-│
-├── data/                  ← 配置与共用 clone（clone/ 在 .gitignore）
-│   ├── experiments.json   ← 实验定义：id、标题、prompt、max_turns
-│   ├── agents.json        ← Agent CLI 定义：binary、flags、parser
-│   └── clone/             ← A/B 共用 git clone（run_all --both-arms 自动维护）
-│
-├── output/                ← 实验产物与报告（gitignore）
-│   ├── baseline/{agent}/{时间戳}/     ← 无 HomeGraph 组
-│   │   ├── run_manifest.json
-│   │   ├── analysis_report.md         ← 单组分析报告（跑完自动生成）
-│   │   └── {实验ID}/
-│   │       ├── prompt.txt             ← 发给 Agent 的 prompt
-│   │       ├── stream_output.jsonl    ← Agent 原始 JSON 流
-│   │       ├── raw_output.txt         ← 解析出的文本回复
-│   │       └── results.json           ← 汇总指标（耗时、工具、Token…）
-│   ├── homegraph/{agent}/{时间戳}/    ← 有 HomeGraph 组（结构同上）
-│   └── compare/{agent}/{时间戳}/      ← A/B 对比报告（--both-arms 跑完自动生成）
-│       ├── ab_compare_report.md
-│       └── compare_manifest.json      ← 指向两组原始目录与报告
-│
-└── log/                   ← 运行日志与 state（gitignore）
-    └── {组别}/{agent}/{时间戳}/
-        ├── run.log
-        ├── run_manifest.json
-        └── {实验ID}/state.json
-```
-
-### 配置文件
-
-**`data/experiments.json`** — 每个实验一条记录：
-
-- `id`：如 `1-1`、`2`、`5`
-- `type`：`oneshot`（默认）或 `session`（实验 5）
-- `title` / `prompt`：任务描述
-- `max_turns`：回合上限（DevEco 无此 flag 时脚本会忽略）
-
-**`data/agents.json`** — 支持的 Agent：
-
-- `deveco`、`claude`、`cursor`、`codex`、`opencode`、`generic`、`text`
-- 字段 `binary`、`flags`、`parser`、`missing`（不支持的 CLI 参数）
-
----
-
-## 常用命令
-
-### A/B 完整评测（推荐）
-
-```powershell
-# 默认跑 1-1、1-2、1-3；自动 clone；跑完出 baseline 报告 + homegraph 报告 + 对比报告
-python run_all.py --both-arms --agent deveco
-
-# 使用本地已有 checkout（跳过 clone）
-python run_all.py --both-arms --agent deveco --repo-path D:\path\to\applications_photos
-```
-
-### 只跑一组
-
-```powershell
-python run_all.py --agent deveco --arm baseline
-python run_all.py --agent deveco --arm homegraph
-```
-
-### 跑全部 11 项实验
-
-```powershell
-python run_all.py --both-arms --agent deveco 1-1 1-2 1-3 2 3-1 3-2 3-3 4-1 4-2 4-3 5
-```
-
-### 单个实验（需先设仓库路径）
-
-```powershell
-$env:REPO_PATH = "D:\code\homegraph\scripts\exp_boundary_eval\data\clone"
-python run_one.py 1-1 --agent deveco
-python run_session.py 5 --agent deveco
-```
-
-### 手动分析（补跑或只看历史结果）
-
-```powershell
-python analyze.py output\baseline\deveco\20260627_110832
-python analyze.py output\homegraph\deveco\20260627_111331
-```
-
-对比报告仅在 `run_all.py --both-arms` 跑完时自动生成；也可在 Python 里调用 `analyze.compare_runs(baseline_dir, homegraph_dir, ...)`。
-
----
-
-## 跑完后的报告
-
-`run_all.py` 结束时控制台会打印类似：
-
-```
-==== 报告已生成 ====
-  Baseline 报告:  ...\output\baseline\deveco\...\analysis_report.md
-  HomeGraph 报告: ...\output\homegraph\deveco\...\analysis_report.md
-  A/B 对比报告 :  ...\output\compare\deveco\...\ab_compare_report.md
-```
-
-| 报告 | 内容 |
-|------|------|
-| `analysis_report.md` | 单组：各实验表格、7 维度评分、档位/幻觉/跨层等解读 |
-| `ab_compare_report.md` | 两组：墙钟耗时、工具调用、Token、逐实验对比、评分对比 |
-
-**对比指标**（来自 `results.json` / stream 解析）：
-
-| 指标 | 字段 |
-|------|------|
-| 单实验耗时 | `duration_s` |
-| 工具调用 | `tool_calls` |
-| Token | `input_tokens`、`output_tokens` |
-| 读取/编辑文件 | `files_read`、`files_edited` |
-| Grep/Glob | `tool_names` 中的 search 类工具 |
-
-**内存**：当前未采集进程内存；对比报告中该列为「未采集」。需要时可自行加外部 profiling。
-
----
-
-## 默认实验（1-1 / 1-2 / 1-3）
-
-档位切换边界探测：信息缺口从小到大，观察 Agent 是否从「快速检索」升级到「深度探索」。
-
----
-
-## 常见问题
-
-### WSL 里 `deveco --version` 失败
-
-DevEco Code **没有 Linux 版**。请在 **Windows** 或 **macOS** 上跑本评测。
-
-```powershell
-npm install -g @deveco/deveco-code
-deveco --version
-cd D:\code\homegraph\scripts\exp_boundary_eval
-python run_all.py --both-arms --agent deveco
-```
-
-WSL 内路径仅作诊断，不能真正跑 DevEco：
-
-```bash
-export DEVECO_BIN=/mnt/c/Users/.../AppData/Roaming/npm/deveco
-```
-
-### homegraph 组 indexing 失败
-
-在 homegraph 仓库根目录执行：
-
-```powershell
-cd D:\code\homegraph
-npm run build
-```
-
-### Python 3.8 on Windows 编码错误
-
-脚本已对 JSON 读写和终端输出做 UTF-8 处理；若仍乱码，可在 PowerShell 中先执行 `chcp 65001`。
-
----
-
-## A/B 机制（真实对照）
-
-两组差异由 `deveco_arm.py` 写入测试仓库的 `.deveco/deveco.jsonc`：
-
-| 组别 | MCP | Agent Prompt | homegraph 工具 |
-|------|-----|--------------|----------------|
-| **baseline** | 无 | 仅用 grep/read | `deny` |
-| **homegraph** | `homegraph serve --mcp --path <repo>` | 优先 `homegraph_explore` | 启用 |
-
-- 每次实验前 `setup.py` 会重置仓库并**重新写入**上述配置；`deveco run --dir <repo>` 读取项目级配置。
-- homegraph 组的 `git clean` 保留 `.homegraph/` 索引，避免重复 `init -i`。
-- 对比报告 **A/B 有效性** 一节检查：baseline 的 HomeGraph 工具调用应为 0，homegraph 组应 > 0。
-
----
-
-## 与 HomeGraph 主仓库的关系
-
-- **homegraph 组**索引策略（`deveco_arm.ensure_homegraph_index`）：
-  - 无 `.homegraph/` → `homegraph init <repo>`（若仍不健康则继续 `homegraph index`）
-  - 已初始化 → **`homegraph index` 全量重建**（不用 `sync`）
-  - **`--both-arms`**：**一启动就先** index/校验 `.homegraph/`，再跑 **homegraph → baseline**（先看到 HG 是否生效）
-  - 单独 `--arm homegraph`：组开头同样阻塞 index
-  - 每个实验前的 `setup.py` **不再**重复 index
-  - **不要**在跑 `run_all.py` 的同时另开终端 `node … index`（会并发写 `.homegraph`）
-
-### 复用已有 `.homegraph/`（跳过 index）
-
-**可以**：把整个 `.homegraph/` 目录复制到目标仓库根目录，只要：
-
-1. **相同代码** — 同一 git commit（DB 里存的是相对路径 + 文件 content hash，不绑定绝对路径）
-2. **索引完整** — 尤其 Photos 级仓库需含 ArkTS Scene（`homegraph status -j` 里 `struct`/`component` > 0、`languages` 含 `arkts`）
-3. **HomeGraph 版本** — 最好用**同一套** `dist/bin/homegraph.js` 构建；若 extraction 版本落后，`status` 会标 `reindexRecommended`，脚本会拒绝 `--skip-index`
-
-复制示例（Windows）：
-
-```powershell
-# 源：已在 Linux/Mac 上 index 成功的 checkout
-Copy-Item -Recurse D:\backup\applications_photos\.homegraph D:\code\applications_photos\.homegraph
-
-# 跑评测，不再 index
-python run_all.py --both-arms --agent deveco --repo-path D:\code\applications_photos --skip-index
-```
-
-单独 homegraph 组同样支持：`python run_all.py --arm homegraph --skip-index --repo-path …`
-
-若仓库相对索引有文件变更，脚本会 **warn** 但仍继续（MCP 可能对改过的文件不准）；严重不完整则 **abort** 并提示去掉 `--skip-index` 或 `homegraph sync`。