archgraph-argo 0.25.0 → 0.26.1

package/argo/scripts/agentSearchDiagnose.js

@@ -0,0 +1,407 @@
+'use strict';
+/**
+ * Agent search diagnosis (framework, zero-dependency).
+ *
+ * Turns ONE agent session into a self-contained diagnostic bundle so the user
+ * can hand it back for analysis:
+ *
+ *   <workspace>/.argo/temp/diagnosis/<session-id>/
+ *     ├─ diagnosis.md          human-readable summary (incl. heuristic hints)
+ *     ├─ metrics.json          the numbers behind the summary
+ *     ├─ session.ndjson        the raw host session (full tool input/output)
+ *     ├─ cost-log.slice.ndjson the matching slice of the background cost log
+ *     └─ manifest.json         file list + sizes + versions
+ *
+ * Data sources (user's choice: both):
+ *   - PRIMARY:  the host session NDJSON (opencode export / run --format json),
+ *     which carries every tool's full input/output + timestamps + tokens.
+ *   - SUPPLEMENT: the framework cost log <workspace>/.argo/temp/agent-cost-log.ndjson.
+ *
+ * Usage:
+ *   node agentSearchDiagnose.js --session <session.ndjson> [--session-id ID]
+ *                               [--cost-log <path>] [--workspace <root>] [--out <dir>] [--json]
+ *
+ * Read-only except for writing the bundle dir. Never mutates the graph or repo.
+ */
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+
+const BUNDLE_VERSION = 'temp2.2';
+const SCHEMA_VERSION = 1;
+const GRAPH_TOOLS = ['getSystemArchitecture', 'getIntentElementContext', 'getArchitectureViewContext', 'queryNeo4jGraph', 'memory_search'];
+const GRAPH_WRITE_TOOLS = ['previewSystemArchitectureMutation', 'applySystemArchitectureMutation', 'addArchitectureElement', 'updateArchitectureElement', 'removeArchitectureElement', 'addArchitectureRelationship', 'updateArchitectureRelationship', 'removeArchitectureRelationship', 'addArchitectureView', 'updateArchitectureView', 'removeArchitectureView'];
+const VALIDATOR_TOOLS = ['validateSystemArchitecture', 'runArchitectureTests', 'initializeWorkspace'];
+const REPO_TOOLS = ['read', 'grep', 'glob', 'list', 'bash', 'webfetch', 'edit', 'write'];
+
+function backendOf(tool) {
+  const n = String(tool || '');
+  const hit = (l) => l.some(t => n.includes(t));
+  if (hit(GRAPH_WRITE_TOOLS)) return 'graph';
+  if (hit(GRAPH_TOOLS)) return 'graph';
+  if (hit(VALIDATOR_TOOLS)) return 'framework';
+  if (hit(REPO_TOOLS)) return 'repo';
+  return 'other';
+}
+
+function classifyQuery(tool, input) {
+  const n = String(tool || '');
+  if (n.includes('question')) return 'human-wait';
+  if (n.includes('task')) return 'subagent';
+  if (n.includes('bash')) return 'bash';
+  if (n.includes('getSystemArchitecture') || n.includes('memory_search')) return 'semantic';
+  if (n.includes('queryNeo4jGraph')) return 'structured-cypher';
+  if (n.includes('getIntentElementContext') || n.includes('getArchitectureViewContext')) return 'structured-context';
+  if (n.includes('validateSystemArchitecture') || n.includes('runArchitectureTests')) return 'validate';
+  if (n.includes('initializeWorkspace')) return 'init';
+  if (n.includes('previewSystemArchitectureMutation') || GRAPH_WRITE_TOOLS.some(t => n.includes(t))) return 'mutation';
+  if (n.includes('read')) return 'file-read';
+  if (n.includes('grep')) return 'grep';
+  if (n.includes('glob') || n.includes('list')) return 'list';
+  if (n.includes('edit') || n.includes('write')) return 'edit';
+  if (n.includes('todowrite')) return 'todo';
+  return 'other';
+}
+
+// Tools that block on a HUMAN (time spent waiting for the person, not the agent).
+const HUMAN_WAIT_TOOLS = ['question'];
+const CONTEXT_BLOWUP_TOKENS = 100000;
+
+function estimateTokens(text) {
+  if (!text) return 0;
+  const s = String(text);
+  const cjk = (s.match(/[\u4e00-\u9fff\u3400-\u4dbf\u3000-\u303f\uff00-\uffef]/g) || []).length;
+  return cjk + Math.ceil((s.length - cjk) / 4);
+}
+
+function stableStringify(value) {
+  if (value === null || typeof value !== 'object') return JSON.stringify(value);
+  if (Array.isArray(value)) return '[' + value.map(stableStringify).join(',') + ']';
+  return '{' + Object.keys(value).sort().map(k => JSON.stringify(k) + ':' + stableStringify(value[k])).join(',') + '}';
+}
+
+function signature(tool, input) {
+  try { return crypto.createHash('sha1').update(String(tool) + '|' + stableStringify(input || {})).digest('hex').slice(0, 12); }
+  catch (_) { return 'unknown'; }
+}
+
+function inputPreview(tool, input) {
+  if (!input || typeof input !== 'object') return '';
+  const pick = input.query && (input.query.intent || input.query) || input.pattern || input.elementId || input.elementName || input.view_id || input.path || input.filePath || input.cypher || input.intent;
+  const s = typeof pick === 'string' ? pick : (pick ? JSON.stringify(pick) : JSON.stringify(input));
+  return String(s).slice(0, 160);
+}
+
+function eventTime(e) {
+  const cands = [e.time, e.part && e.part.time, e.part && e.part.state && e.part.state.time];
+  for (const t of cands) {
+    if (!t) continue;
+    if (typeof t === 'number') return t;
+    if (typeof t.start === 'number' && typeof t.end === 'number') return t.end;
+    if (typeof t.start === 'number') return t.start;
+    if (typeof t.end === 'number') return t.end;
+  }
+  return typeof e.timestamp === 'number' ? e.timestamp : null;
+}
+
+function isExportJson(text) {
+  const t = String(text || '').trim();
+  if (!t.startsWith('{')) return false;
+  try { const j = JSON.parse(t); return !!(j && Array.isArray(j.messages)); } catch (_) { return false; }
+}
+
+// Accept BOTH the live event stream (opencode run --format json, NDJSON) and the
+// session export JSON (opencode export -> { info, messages:[{info, parts:[...]}] }).
+function exportToNdjson(text) {
+  const j = JSON.parse(text);
+  const ev = [];
+  for (const m of j.messages || []) {
+    const info = m.info || {};
+    const ts = info.time && (info.time.created || info.time.completed);
+    for (const p of m.parts || []) {
+      if (!p || typeof p !== 'object') continue;
+      if (p.type === 'tool') ev.push({ type: 'tool', timestamp: (p.state && p.state.time && p.state.time.end) || ts, part: p });
+      else if (p.type === 'step-start') ev.push({ type: 'step_start', timestamp: ts, part: p });
+      else if (p.type === 'text') ev.push({ type: 'text', timestamp: ts, part: p });
+    }
+    if (info.role === 'assistant' && info.tokens) ev.push({ type: 'step_finish', timestamp: info.time && info.time.completed, part: { tokens: info.tokens, cost: info.cost } });
+  }
+  return ev.map(e => JSON.stringify(e)).join('\n') + '\n';
+}
+
+function parseSession(text) {
+  const raw = String(text || '');
+  const toolCalls = [];
+  const usages = [];
+  let steps = 0; let tMin = null; let tMax = null; let cost = 0;
+  const texts = [];
+  for (const line of raw.split('\n')) {
+    const t = line.trim();
+    if (!t.startsWith('{')) continue;
+    let e; try { e = JSON.parse(t); } catch (_) { continue; }
+    const part = e.part || e;
+    if (part && part.type === 'text' && part.text) texts.push(part.text);
+    if (part && part.type === 'tool') {
+      const tool = part.tool || part.name || (part.state && part.state.tool) || 'tool';
+      const st = part.state || {};
+      const tm = st.time || {};
+      const out = st.output != null ? String(st.output) : '';
+      toolCalls.push({
+        tool, backend: backendOf(tool), queryClass: classifyQuery(tool, st.input),
+        durationMs: (typeof tm.start === 'number' && typeof tm.end === 'number') ? Math.max(0, tm.end - tm.start) : null,
+        ok: st.status ? st.status !== 'error' : true,
+        error: st.error ? String(st.error).slice(0, 200) : null,
+        signature: signature(tool, st.input), inputPreview: inputPreview(tool, st.input),
+        outputBytes: out.length, outputTokens: estimateTokens(out),
+        path: (st.input && (st.input.filePath || st.input.path || st.input.file)) || null,
+      });
+    }
+    if (e.type === 'step_start') steps += 1;
+    if (e.type === 'step_finish') {
+      const fin = (e.part && e.part.finish) ? e.part.finish : (e.part || e);
+      if (fin && typeof fin.cost === 'number') cost += fin.cost;
+      const tk = fin && (fin.tokens || (fin.finish && fin.finish.tokens));
+      if (tk) usages.push({ input: tk.input || 0, output: tk.output || 0, reasoning: tk.reasoning || 0, cacheRead: (tk.cache && tk.cache.read) || 0, cacheWrite: (tk.cache && tk.cache.write) || 0 });
+    }
+    const time = eventTime(e);
+    if (time !== null) { tMin = tMin === null ? time : Math.min(tMin, time); tMax = tMax === null ? time : Math.max(tMax, time); }
+  }
+  const tokensIn = usages.reduce((a, u) => a + u.input, 0);
+  const tokensOut = usages.reduce((a, u) => a + u.output, 0);
+  const tokensReasoning = usages.reduce((a, u) => a + u.reasoning, 0);
+  return { toolCalls, usages, texts, steps, cost, wallMs: (tMin !== null && tMax !== null && tMax >= tMin) ? tMax - tMin : null, tokensIn, tokensOut, tokensReasoning, tokens: tokensIn + tokensOut + tokensReasoning };
+}
+
+function countRoundTrips(toolCalls) {
+  const seq = toolCalls.map(c => c.backend).filter(b => b === 'graph' || b === 'repo');
+  let n = 0;
+  for (let i = 1; i < seq.length; i++) if (seq[i] !== seq[i - 1]) n += 1;
+  return n;
+}
+
+function diagnose(session, opts = {}) {
+  const tc = session.toolCalls;
+  const byTool = {};
+  const byBackend = { graph: { calls: 0, ms: 0 }, repo: { calls: 0, ms: 0 }, framework: { calls: 0, ms: 0 }, other: { calls: 0, ms: 0 } };
+  const byQueryClass = {};
+  const sigCount = {};
+  const pathReads = {};
+  let toolMs = 0; let humanWaitMs = 0; let errors = 0; let empty = 0;
+  for (const c of tc) {
+    const isHuman = c.queryClass === 'human-wait' || HUMAN_WAIT_TOOLS.some(t => String(c.tool).includes(t));
+    const bt = byTool[c.tool] || (byTool[c.tool] = { calls: 0, ms: 0, tokens: 0, errors: 0 });
+    bt.calls += 1; bt.ms += c.durationMs || 0; bt.tokens += c.outputTokens || 0;
+    if (isHuman) {
+      humanWaitMs += c.durationMs || 0; // human time is NOT agent/tool work
+    } else {
+      const b = byBackend[c.backend] || (byBackend[c.backend] = { calls: 0, ms: 0 });
+      b.calls += 1; b.ms += c.durationMs || 0;
+      toolMs += c.durationMs || 0;
+    }
+    if (c.ok === false) { bt.errors += 1; errors += 1; }
+    if ((c.outputBytes || 0) < 2) empty += 1;
+    byQueryClass[c.queryClass] = (byQueryClass[c.queryClass] || 0) + 1;
+    sigCount[c.signature] = (sigCount[c.signature] || 0) + 1;
+    if (c.queryClass === 'file-read' && c.path) pathReads[c.path] = (pathReads[c.path] || 0) + 1;
+  }
+  const duplicates = [];
+  const seen = new Set();
+  for (const c of tc) {
+    if (seen.has(c.signature)) continue;
+    seen.add(c.signature);
+    if (sigCount[c.signature] > 1) duplicates.push({ tool: c.tool, queryClass: c.queryClass, count: sigCount[c.signature], preview: c.inputPreview });
+  }
+  const repeatedReads = Object.entries(pathReads).filter(([, n]) => n > 1).map(([p, n]) => ({ path: p, count: n }));
+  // longest no-progress streak: consecutive calls that were empty/failed/duplicate
+  let streak = 0; let best = 0;
+  for (const c of tc) {
+    const bad = c.ok === false || (c.outputBytes || 0) < 2 || sigCount[c.signature] > 1;
+    streak = bad ? streak + 1 : 0;
+    if (streak > best) best = streak;
+  }
+  const cumulativeInput = [];
+  let acc = 0;
+  for (const u of session.usages) { acc += u.input; cumulativeInput.push(u.input); }
+  const topByMs = [...tc].sort((a, b) => (b.durationMs || 0) - (a.durationMs || 0)).slice(0, 5).map(c => ({ tool: c.tool, ms: c.durationMs, ok: c.ok, preview: c.inputPreview }));
+  const topByTokens = [...tc].sort((a, b) => (b.outputTokens || 0) - (a.outputTokens || 0)).slice(0, 5).map(c => ({ tool: c.tool, tokens: c.outputTokens, preview: c.inputPreview }));
+
+  const wallMs = opts.wallMs != null ? opts.wallMs : session.wallMs;
+  const modelMs = wallMs != null ? Math.max(0, wallMs - toolMs - humanWaitMs) : null;
+  const blowups = cumulativeInput.map((v, i) => ({ step: i, input: v })).filter(x => x.input >= CONTEXT_BLOWUP_TOKENS).sort((a, b) => b.input - a.input);
+
+  return {
+    schemaVersion: SCHEMA_VERSION, bundleVersion: BUNDLE_VERSION, generatedAt: new Date().toISOString(),
+    workspace: opts.workspace || null, sessionId: opts.sessionId || null,
+    overview: {
+      steps: session.steps, toolCalls: tc.length, roundTrips: countRoundTrips(tc),
+      wallMs, modelMs, mcpMs: byBackend.graph.ms, repoToolMs: byBackend.repo.ms, toolMs, humanWaitMs,
+      tokensIn: session.tokensIn, tokensOut: session.tokensOut, tokensReasoning: session.tokensReasoning, tokens: session.tokens,
+      cost: session.cost, toolErrors: errors, emptyResults: empty,
+      distinctSignatures: new Set(tc.map(c => c.signature)).size,
+      contextBlowup: { thresholdTokens: CONTEXT_BLOWUP_TOKENS, count: blowups.length, max: blowups.length ? blowups[0].input : 0, top: blowups.slice(0, 5) },
+    },
+    byTool, byBackend, byQueryClass,
+    tokenGrowth: { perStepInput: cumulativeInput, steps: cumulativeInput.length },
+    overSearch: {
+      duplicateCalls: duplicates,
+      repeatedReads,
+      emptyOrError: errors + empty,
+      noProgressStreak: best,
+    },
+    topOffendersByTime: topByMs,
+    topOffendersByTokens: topByTokens,
+    hints: buildHints({ toolCalls: tc.length, duplicates: duplicates.length, emptyOrError: errors + empty, repeatedReads: repeatedReads.length, noProgressStreak: best, modelMs, mcpMs: byBackend.graph.ms, repoToolMs: byBackend.repo.ms, roundTrips: countRoundTrips(tc), blowups: blowups.length, blowupMax: blowups.length ? blowups[0].input : 0 }),
+  };
+}
+
+function buildHints(m) {
+  const hints = [];
+  if (m.blowups > 0) hints.push(`上下文尖峰 ${m.blowups} 个 step（最大 ${m.blowupMax} tokens）→ 多由大工具输出造成；优先考虑截断/分页/摘要工具输出（observation masking）、先摘要后精读（对所有场景统一生效，勿只针对单会话）。`);
+  if (m.duplicates > 0) hints.push(`重复/近似重复调用 ${m.duplicates} 组 → 考虑结果缓存或查询归一（同参不重搜）。`);
+  if (m.emptyOrError > 0) hints.push(`空结果/失败 ${m.emptyOrError} 次 → 考虑改进查询构造/回退策略，避免"空手→换词→再搜"的循环。`);
+  if (m.repeatedReads > 0) hints.push(`同一文件被重复读 ${m.repeatedReads} 处 → 考虑读取缓存或先摘要后精读。`);
+  if (m.noProgressStreak >= 3) hints.push(`最长"无进展"连续 ${m.noProgressStreak} 次 → 缺停止判据/预算，建议显式设停止条件。`);
+  if (m.roundTrips >= 2) hints.push(`图↔仓往返 ${m.roundTrips} 次 → 检查是否可在一次规划内并发取数。`);
+  if (m.modelMs != null && m.modelMs > (m.mcpMs + m.repoToolMs)) hints.push(`模型耗时主导（${m.modelMs}ms > 工具 ${(m.mcpMs + m.repoToolMs)}ms）→ 考虑上下文压缩/减少轮次。`);
+  if (hints.length === 0) hints.push('未发现明显过度搜索信号。');
+  return hints;
+}
+
+function renderDiagnosis(m, meta) {
+  const L = [];
+  L.push(`# Agent 搜索诊断报告`);
+  L.push('');
+  L.push(`- 生成时间：${m.generatedAt}`);
+  L.push(`- 会话：${m.sessionId || '(unknown)'}　工作区：${m.workspace || '(unknown)'}`);
+  L.push(`- bundle 版本：${m.bundleVersion}　schema：${m.schemaVersion}`);
+  L.push('');
+  L.push(`## 概览`);
+  L.push('');
+  L.push(`| 指标 | 值 |`);
+  L.push(`|---|---|`);
+  L.push(`| 轮次 steps | ${m.overview.steps} |`);
+  L.push(`| 工具调用 | ${m.overview.toolCalls}（去重签名 ${m.overview.distinctSignatures}） |`);
+  L.push(`| 图↔仓往返 | ${m.overview.roundTrips} |`);
+  L.push(`| 墙钟 | ${fmtMs(m.overview.wallMs)} = 模型 ${fmtMs(m.overview.modelMs)} + MCP ${fmtMs(m.overview.mcpMs)} + 仓 ${fmtMs(m.overview.repoToolMs)} + 人类等待 ${fmtMs(m.overview.humanWaitMs)} |`);
+  L.push(`| tokens | 总 ${m.overview.tokens}（in ${m.overview.tokensIn} / out ${m.overview.tokensOut} / reason ${m.overview.tokensReasoning}） |`);
+  L.push(`| 工具失败 / 空结果 | ${m.overview.toolErrors} / ${m.overview.emptyResults} |`);
+  L.push('');
+  L.push(`## 过度搜索信号`);
+  L.push('');
+  L.push(`- 重复调用组：${m.overSearch.duplicateCalls.length}`);
+  for (const d of m.overSearch.duplicateCalls.slice(0, 10)) L.push(`  - ×${d.count} ${d.tool} [${d.queryClass}] ${d.preview}`);
+  L.push(`- 重复读同一文件：${m.overSearch.repeatedReads.length}`);
+  for (const r of m.overSearch.repeatedReads.slice(0, 10)) L.push(`  - ×${r.count} ${r.path}`);
+  L.push(`- 空结果/失败合计：${m.overSearch.emptyOrError}`);
+  L.push(`- 最长无进展连续：${m.overSearch.noProgressStreak}`);
+  L.push('');
+  L.push(`## 后端 / 查询类分布`);
+  L.push('');
+  L.push(`- 后端：` + Object.entries(m.byBackend).map(([k, v]) => `${k}=${v.calls}`).join(' '));
+  L.push(`- 查询类：` + Object.entries(m.byQueryClass).map(([k, v]) => `${k}=${v}`).join(' '));
+  L.push('');
+  L.push(`## 最贵调用（按耗时）`);
+  L.push('');
+  for (const c of m.topOffendersByTime) L.push(`- ${fmtMs(c.ms)} ${c.tool}${c.ok ? '' : ' (error)'} ${c.preview}`);
+  L.push('');
+  L.push(`## token 随轮次`);
+  L.push('');
+  L.push(`每步 input tokens（累计上下文规模）：${m.tokenGrowth.perStepInput.join(', ') || '(无)'}`);
+  L.push('');
+  const cb = m.overview.contextBlowup || { count: 0, max: 0, top: [] };
+  L.push(`## 上下文尖峰（≥ ${cb.thresholdTokens} tokens 的 step）`);
+  L.push('');
+  L.push(`- 尖峰数：${cb.count}　最大：${cb.max} tokens`);
+  for (const b of cb.top) L.push(`  - step ${b.step}: ${b.input} input tokens`);
+  L.push('');
+  L.push(`## 诊断建议（启发式，供 Agent 复核）`);
+  L.push('');
+  for (const h of m.hints) L.push(`- ${h}`);
+  L.push('');
+  L.push(`---`);
+  L.push(`> 本报告由 agentSearchDiagnose 自动生成；请 Agent 结合 metrics.json 与会话片段复核并补充解读。`);
+  L.push('');
+  return L.join('\n');
+}
+
+function fmtMs(ms) {
+  if (ms == null) return 'n/a';
+  return ms >= 1000 ? `${(ms / 1000).toFixed(1)}s` : `${ms}ms`;
+}
+
+function writeBundle(opts) {
+  const workspace = opts.workspace || process.cwd();
+  const rawInput = fs.readFileSync(opts.session, 'utf8');
+  const sessionText = isExportJson(rawInput) ? exportToNdjson(rawInput) : rawInput;
+  const session = parseSession(sessionText);
+  const sessionId = opts.sessionId || inferSessionId(sessionText) || 'session';
+  const outDir = opts.out || path.join(workspace, '.argo', 'temp', 'diagnosis', sessionId);
+  fs.mkdirSync(outDir, { recursive: true });
+
+  const costLogPath = opts.costLog || path.join(workspace, '.argo', 'temp', 'agent-cost-log.ndjson');
+  const costLogText = readMaybe(costLogPath);
+
+  const metrics = diagnose(session, { workspace, sessionId, wallMs: opts.wallMs });
+  const files = [];
+  const write = (name, body) => { const p = path.join(outDir, name); fs.writeFileSync(p, body); files.push({ path: name, bytes: Buffer.byteLength(body) }); };
+
+  write('session.ndjson', sessionText);
+  write('cost-log.slice.ndjson', sliceCostLog(costLogText, sessionId));
+  write('metrics.json', JSON.stringify(metrics, null, 2) + '\n');
+  write('diagnosis.md', renderDiagnosis(metrics, { costLogPath }));
+
+  const manifest = {
+    schemaVersion: SCHEMA_VERSION, bundleVersion: BUNDLE_VERSION, generatedAt: metrics.generatedAt,
+    workspace, sessionId, sources: { session: path.resolve(opts.session), costLog: costLogPath },
+    files,
+  };
+  fs.writeFileSync(path.join(outDir, 'manifest.json'), JSON.stringify(manifest, null, 2) + '\n');
+  return { outDir, metrics, manifest };
+}
+
+function readMaybe(file) { try { return fs.readFileSync(file, 'utf8'); } catch (_) { return ''; } }
+
+function inferSessionId(text) {
+  const m = String(text).match(/"sessionID"\s*:\s*"([^"]+)"/);
+  return m ? m[1] : null;
+}
+
+function sliceCostLog(text, sessionId) {
+  if (!text) return '';
+  const lines = text.split('\n').filter(Boolean);
+  const hit = lines.filter(l => !sessionId || l.includes(sessionId));
+  return (hit.length ? hit : []).join('\n') + (hit.length ? '\n' : '');
+}
+
+function parseArgs(argv) {
+  const a = { session: null, sessionId: null, costLog: null, workspace: process.cwd(), out: null, json: false };
+  for (let i = 0; i < argv.length; i++) {
+    const k = argv[i];
+    if (k === '--session') a.session = argv[++i];
+    else if (k === '--session-id') a.sessionId = argv[++i];
+    else if (k === '--cost-log') a.costLog = argv[++i];
+    else if (k === '--workspace') a.workspace = argv[++i];
+    else if (k === '--out') a.out = argv[++i];
+    else if (k === '--json') a.json = true;
+  }
+  return a;
+}
+
+function main(argv) {
+  const args = parseArgs(argv || process.argv.slice(2));
+  if (!args.session || !fs.existsSync(args.session)) {
+    console.error('agentSearchDiagnose: --session <session.ndjson> is required');
+    return 2;
+  }
+  const { outDir, metrics, manifest } = writeBundle(args);
+  if (args.json) { console.log(JSON.stringify({ outDir, overview: metrics.overview, hints: metrics.hints }, null, 2)); return 0; }
+  console.log(`diagnosis bundle -> ${outDir}`);
+  console.log(`files: ${manifest.files.map(f => f.path).join(', ')}`);
+  console.log(`overview: steps=${metrics.overview.steps} tools=${metrics.overview.toolCalls} roundTrips=${metrics.overview.roundTrips} tokens=${metrics.overview.tokens} model=${fmtMs(metrics.overview.modelMs)} mcp=${fmtMs(metrics.overview.mcpMs)} repo=${fmtMs(metrics.overview.repoToolMs)}`);
+  for (const h of metrics.hints) console.log(`hint: ${h}`);
+  return 0;
+}
+
+module.exports = { BUNDLE_VERSION, SCHEMA_VERSION, parseSession, classifyQuery, backendOf, signature, diagnose, renderDiagnosis, writeBundle, sliceCostLog, isExportJson, exportToNdjson, main };
+
+if (require.main === module) process.exit(main());

package/argo/scripts/argo-mcp-server.js

@@ -330,6 +330,8 @@ function intentElementContextInputSchema() {
       dependentDepth: { type: 'number', description: 'Default: 1. Semantic dependents that rely on the focus element.' },
       associationDepth: { type: 'number', description: 'Default: 1. Association neighbors are expanded at least one layer.' },
       associationNeighborDependencyDepth: { type: 'number', description: 'Default: 0. Optional dependency expansion from association neighbors.' },
+      includeAttributes: { type: 'boolean', description: 'Default: false. Include `attributes` (commit/session/release ledgers) verbatim; omitted by default from this structural read (the focus element always keeps its own).' },
+      includeTestcases: { type: 'boolean', description: 'Default: false. Include member `testcases` verbatim; omitted by default from this structural read.' },
     },
     additionalProperties: false,
   };

package/argo/scripts/systemarchitecture-mcp-server.js

@@ -461,6 +461,8 @@ function intentElementContextInputSchema() {
       dependentDepth: { type: 'number', description: 'Default: 1. Semantic dependents that rely on the focus element.' },
       associationDepth: { type: 'number', description: 'Default: 1. Association neighbors are expanded at least one layer.' },
       associationNeighborDependencyDepth: { type: 'number', description: 'Default: 0. Optional dependency expansion from association neighbors.' },
+      includeAttributes: { type: 'boolean', description: 'Default: false. Include `attributes` (commit/session/release ledgers) verbatim. Omitted by default from this structural read; the focus element always keeps its own. Semantic retrieval embeds attributes, so semantic hits keep them.' },
+      includeTestcases: { type: 'boolean', description: 'Default: false. Include member `testcases` verbatim. Omitted by default from this structural read (bookkeeping); pass true when you need acceptance cases. Semantic retrieval embeds testcase descriptions, so semantic hits keep them.' },
     },
     additionalProperties: false,
   };
@@ -475,6 +477,8 @@ function viewContextInputSchema() {
       view_id: { type: 'string', description: 'The id of the view to resolve.' },
       includeParentElement: { type: 'boolean', description: 'Default: true. Resolve the parent element referenced by the view.' },
       includeChildViews: { type: 'boolean', description: 'Default: false. Include child views declared by member elements through subdiagram_views.' },
+      includeAttributes: { type: 'boolean', description: 'Default: false. Include member/relationship `attributes` (commit/session/release ledgers) verbatim. Omitted by default from this structural read (bookkeeping); pass true when you need provenance.' },
+      includeTestcases: { type: 'boolean', description: 'Default: false. Include member `testcases` verbatim. Omitted by default from this structural read; pass true for acceptance-case lookups.' },
       includeEaGeometry: { type: 'boolean', description: 'Default: false (opt-in). When true, additionally resolve the diagram GEOMETRY (element boxes + connector line routes) for this view from the workspace EA model (.qea) and return it under a `geometry` field aligned by schema id with the resolved members. Each geometry relationship carries: `path` (the EA route from t_diagramlinks.Path, "" when EA auto-routes), `points` (the parsed [{x,y}] waypoints), `edge` (the EDGE route-style token or null) and `geometry` (the raw SX/SY/EX/EY override string, which contains NO waypoints). By default the EA model is never touched and no `geometry` field is returned; a missing EA model/diagram yields geometry.present=false, never an error.' },
     },
     additionalProperties: false,
@@ -615,6 +619,42 @@ function validateDocument(document, schema, options = {}) {
   return errors;
 }
 
+// Agent-facing projection of canonical records for STRUCTURAL reads (view
+// membership / intent-element subgraph). `attributes` (commit/session/release
+// ledgers) and `testcases` are bookkeeping: measured as ~52% of the element
+// bytes but NOT needed to answer structural reads, so they are omitted by
+// default and returned only on opt-in (includeAttributes / includeTestcases).
+//
+// This is NOT summarisation: every retained field is returned verbatim. It is
+// also NOT the semantic match surface — semantic retrieval embeds attributes and
+// testcase descriptions (semanticRecordText.js), so semantic results keep them;
+// and the focus element of an intent-element read always keeps its own.
+function projectAgentFields(record, opts = {}) {
+  const value = clone(record);
+  let omittedAttributes = 0;
+  let omittedTestcases = 0;
+  if (!opts.includeAttributes && Array.isArray(value.attributes) && value.attributes.length) {
+    omittedAttributes = value.attributes.length;
+    delete value.attributes;
+  }
+  if (!opts.includeTestcases && Array.isArray(value.testcases) && value.testcases.length) {
+    omittedTestcases = value.testcases.length;
+    delete value.testcases;
+  }
+  return { value, omittedAttributes, omittedTestcases };
+}
+
+function buildAgentProjection(omitted) {
+  if (!omitted || (omitted.attributes === 0 && omitted.testcases === 0)) {
+    return null;
+  }
+  return {
+    attributesOmitted: omitted.attributes,
+    testcasesOmitted: omitted.testcases,
+    note: 'Member attributes/testcases are bookkeeping (commit/session/release ledgers, acceptance cases) and are omitted from this structural read by default. Pass includeAttributes:true / includeTestcases:true to include them verbatim. Semantic retrieval already embeds their text, so semantic hits keep them.',
+  };
+}
+
 function buildIntentElementContext(context, args = {}) {
   const profile = args.profile || 'generic-agent';
   const focusResult = resolveFocusElement(context.document, args);
@@ -697,7 +737,27 @@ function buildIntentElementContext(context, args = {}) {
     associationDepth,
   });
 
-  return {
+  const subgraph = buildNativeSubgraph(context.document, includedElementIds, includedRelationshipIds);
+  const includeAttributes = args.includeAttributes === true;
+  const includeTestcases = args.includeTestcases === true;
+  const omitted = { attributes: 0, testcases: 0 };
+  if (!(includeAttributes && includeTestcases)) {
+    subgraph.elements = subgraph.elements.map((element) => {
+      if (element.id === focusElement.id) {
+        return element; // the focus element keeps its own bookkeeping
+      }
+      const projected = projectAgentFields(element, { includeAttributes, includeTestcases });
+      omitted.attributes += projected.omittedAttributes;
+      omitted.testcases += projected.omittedTestcases;
+      return projected.value;
+    });
+    subgraph.relationships = subgraph.relationships.map((relationship) => {
+      const projected = projectAgentFields(relationship, { includeAttributes });
+      omitted.attributes += projected.omittedAttributes;
+      return projected.value;
+    });
+  }
+  const result = {
     status: 'passed',
     query: {
       architecturePath: context.graphPath.relativePath,
@@ -711,12 +771,15 @@ function buildIntentElementContext(context, args = {}) {
       traversalMode: 'archimate-semantic',
     },
     focusElementId: focusElement.id,
-    subgraph: buildNativeSubgraph(context.document, includedElementIds, includedRelationshipIds),
+    subgraph,
     boundary,
     explorationHints,
     workContext: {},
     diagnostics: [],
   };
+  const projection = buildAgentProjection(omitted);
+  if (projection) result.projection = projection;
+  return result;
 }
 
 // ---------------------------------------------------------------------------
@@ -786,12 +849,22 @@ function buildViewContext(context, args = {}) {
   const elementById = new Map((document.elements || []).map(element => [element.id, element]));
   const relationshipById = new Map((document.relationships || []).map(relationship => [relationship.id, relationship]));
 
+  const includeAttributes = args.includeAttributes === true;
+  const includeTestcases = args.includeTestcases === true;
+  const omitted = { attributes: 0, testcases: 0 };
+  const project = (record) => {
+    const projected = projectAgentFields(record, { includeAttributes, includeTestcases });
+    omitted.attributes += projected.omittedAttributes;
+    omitted.testcases += projected.omittedTestcases;
+    return projected.value;
+  };
+
   const elements = [];
   const missingElementIds = [];
   for (const elementId of view.included_elements || []) {
     const element = elementById.get(elementId);
     if (element) {
-      elements.push(clone(element));
+      elements.push(project(element));
     } else {
       missingElementIds.push(elementId);
     }
@@ -802,7 +875,7 @@ function buildViewContext(context, args = {}) {
   for (const relationshipId of view.included_relationships || []) {
     const relationship = relationshipById.get(relationshipId);
     if (relationship) {
-      relationships.push(clone(relationship));
+      relationships.push(project(relationship));
     } else {
       missingRelationshipIds.push(relationshipId);
     }
@@ -812,7 +885,7 @@ function buildViewContext(context, args = {}) {
   let parentElement = null;
   if (includeParentElement && view.parent_element_id) {
     const parent = elementById.get(view.parent_element_id);
-    parentElement = parent ? clone(parent) : null;
+    parentElement = parent ? project(parent) : null;
   }
 
   const includeChildViews = args.includeChildViews === true;
@@ -847,6 +920,8 @@ function buildViewContext(context, args = {}) {
   if (args.includeEaGeometry === true) {
     result.geometry = readEaViewGeometry(context.workspaceRoot, viewId);
   }
+  const projection = buildAgentProjection(omitted);
+  if (projection) result.projection = projection;
   return result;
 }
 
@@ -2750,7 +2825,7 @@ async function memorySearchTool(args = {}, dependencies = undefined) {
     .filter(element => element && typeof element.semanticScore === 'number')
     .sort((left, right) => right.semanticScore - left.semanticScore)
     .slice(0, topK)
-    .map(element => Object.freeze(memoryHitCard(element, maxDescLen)));
+    .map(element => Object.freeze(memoryHitCard(element, maxDescLen, query)));
   return {
     status: 'passed',
     query,
@@ -2763,7 +2838,7 @@ async function memorySearchTool(args = {}, dependencies = undefined) {
 // Build one compact memory hit: id/name/type/score + an excerpt of the
 // description bounded by maxDescLen, plus the full text length so the caller
 // knows how much content exists and can decide whether to expand.
-function memoryHitCard(element, maxDescLen) {
+function memoryHitCard(element, maxDescLen, query) {
   const description = typeof element.description === 'string' ? element.description : '';
   const descriptionLength = description.length;
   let excerpt = '';
@@ -2783,6 +2858,13 @@ function memoryHitCard(element, maxDescLen) {
       card.truncated = true;
     }
   }
+  // A memory match may be driven by an attribute/testcase (both are embedded);
+  // surface the matching bookkeeping text so the agent sees WHY it hit without
+  // a second call.
+  const snippet = bookkeepingSnippet(element, 'Element', query);
+  if (snippet) {
+    card.matchedSnippet = snippet;
+  }
   return card;
 }
 
@@ -3290,11 +3372,31 @@ function buildBusinessSemanticSummary(retrieved, query = {}) {
       supplementaryReasons: Array.isArray(item.supplementaryReasons) ? [...item.supplementaryReasons] : [],
     },
   ]));
+  const recordById = new Map();
+  const putRecord = (objectType, record, id) => { if (record && id) recordById.set(`${objectType}:${id}`, record); };
+  for (const element of (source.closure && source.closure.elements) || []) putRecord('Element', element, element.id);
+  for (const view of (source.viewClosure && source.viewClosure.views) || []) {
+    putRecord('View', view, view.view_id);
+    for (const member of view.memberElements || []) putRecord('Element', member, member.id);
+    for (const member of view.memberRelationships || []) putRecord('ArchitectureRelationship', member, member.id);
+  }
+  for (const relationship of (source.endpointClosure && source.endpointClosure.relationships) || []) {
+    putRecord('ArchitectureRelationship', relationship, relationship.id);
+    if (relationship.source) putRecord('Element', relationship.source, relationship.source.id);
+    if (relationship.target) putRecord('Element', relationship.target, relationship.target.id);
+  }
+  const ctx = {
+    query,
+    recordById,
+    hitElementIds: buildHitIdSet(source, 'elements'),
+    hitRelationshipIds: buildHitIdSet(source, 'relationships'),
+    hitViewIds: buildHitIdSet(source, 'views'),
+  };
   const seedLimit = businessSummaryLimit(query);
-  const semanticSeeds = summarizeSeeds(source.seedsByType, hitReasonByKey, seedLimit);
-  const elements = summarizeElements(source, hitReasonByKey, seedLimit * 2);
-  const relationships = summarizeRelationships(source, hitReasonByKey, seedLimit * 2);
-  const views = summarizeViews(source, hitReasonByKey, seedLimit);
+  const semanticSeeds = summarizeSeeds(source.seedsByType, hitReasonByKey, seedLimit, ctx);
+  const elements = summarizeElements(source, hitReasonByKey, seedLimit * 2, ctx);
+  const relationships = summarizeRelationships(source, hitReasonByKey, seedLimit * 2, ctx);
+  const views = summarizeViews(source, hitReasonByKey, seedLimit, ctx);
   const includedObjectIds = Object.freeze([
     ...elements.map(item => item.id),
     ...relationships.map(item => item.id),
@@ -3688,7 +3790,70 @@ function businessSummaryLimit(query) {
   return Number.isInteger(supplied) && supplied > 0 ? Math.min(supplied, 50) : 8;
 }
 
-function summarizeSeeds(seedsByType = {}, hitReasonByKey, limit) {
+// A hit may be driven by an attribute/testcase (both are embedded), so surface
+// the matching bookkeeping text on HIT records only — so the agent sees WHY it
+// matched without a second lookup. Never attached to pruned neighbours.
+function tokenizeForMatch(text) {
+  const tokens = new Set();
+  const s = String(text || '');
+  for (const word of s.toLowerCase().match(/[a-z0-9]{3,}/g) || []) tokens.add(word);
+  for (const run of s.match(/[\u4e00-\u9fff]{2,}/g) || []) {
+    tokens.add(run);
+    for (let i = 0; i + 2 <= run.length; i += 1) tokens.add(run.slice(i, i + 2));
+  }
+  return [...tokens];
+}
+
+function bookkeepingSnippet(record, objectType, query, maxLen = 240) {
+  if (!record || typeof record !== 'object') return null;
+  const candidates = [];
+  if (objectType === 'ArchitectureRelationship' || objectType === 'Relationship') {
+    if (typeof record.statement === 'string' && record.statement.trim()) candidates.push(record.statement.trim());
+    if (typeof record.description === 'string' && record.description.trim()) candidates.push(record.description.trim());
+  }
+  for (const attribute of Array.isArray(record.attributes) ? record.attributes : []) {
+    if (!attribute || typeof attribute.name !== 'string') continue;
+    const text = (typeof attribute.value === 'string' && attribute.value.trim())
+      || (typeof attribute.description === 'string' && attribute.description.trim()) || '';
+    if (text) candidates.push(`${attribute.name}: ${text}`);
+  }
+  for (const testcase of Array.isArray(record.testcases) ? record.testcases : []) {
+    if (!testcase) continue;
+    const text = typeof testcase === 'string'
+      ? testcase
+      : (testcase.description || testcase.coverage || testcase.name || '');
+    if (typeof text === 'string' && text.trim()) candidates.push(`AT ${testcase.name || ''}: ${text.trim()}`.trim());
+  }
+  if (!candidates.length) return null;
+  const q = typeof query === 'string' ? query : (query && query.intent) || '';
+  const tokens = tokenizeForMatch(q);
+  const scored = candidates.map((text, index) => {
+    const lower = text.toLowerCase();
+    let overlap = 0;
+    for (const token of tokens) if (lower.includes(token)) overlap += 1;
+    return { text, overlap, index };
+  }).sort((a, b) => (b.overlap - a.overlap) || (b.text.length - a.text.length) || (a.index - b.index));
+  let out = '';
+  for (const entry of scored) {
+    if (out && out.length + entry.text.length + 2 > maxLen) break;
+    out = out ? `${out} | ${entry.text}` : entry.text;
+    if (out.length >= maxLen) break;
+  }
+  if (!out) return null;
+  return out.length > maxLen ? `${out.slice(0, maxLen - 3)}...` : out;
+}
+
+function buildHitIdSet(source, typeKey) {
+  const set = new Set();
+  const seeds = (source && source.seedsByType && source.seedsByType[typeKey]) || [];
+  for (const seed of Array.isArray(seeds) ? seeds : []) {
+    const raw = seed && (seed.id || seed.objectId || seed.canonicalIdentity);
+    if (typeof raw === 'string' && raw) set.add(raw.includes(':') ? raw.split(':').pop() : raw);
+  }
+  return set;
+}
+
+function summarizeSeeds(seedsByType = {}, hitReasonByKey, limit, ctx = {}) {
   return Object.freeze(Object.fromEntries(Object.entries(seedsByType).map(([type, seeds]) => [
     type,
     Object.freeze((Array.isArray(seeds) ? seeds : [])
@@ -3697,14 +3862,18 @@ function summarizeSeeds(seedsByType = {}, hitReasonByKey, limit) {
       .slice(0, limit)
       .map(seed => {
         const objectType = seed.objectType || seed.channel || inferObjectTypeFromSeedType(type);
-        const objectId = seed.id || seed.objectId || seed.canonicalIdentity;
+        const rawId = seed.id || seed.objectId || seed.canonicalIdentity;
+        const objectId = typeof rawId === 'string' && rawId.includes(':') ? rawId.split(':').pop() : rawId;
         const reasons = hitReasonByKey.get(`${objectType}:${objectId}`) || {};
+        const record = ctx.recordById ? ctx.recordById.get(`${objectType}:${objectId}`) : null;
+        const snippet = record ? bookkeepingSnippet(record, objectType, ctx.query) : null;
         return Object.freeze({
           objectId,
           objectType,
           score: typeof seed.score === 'number' ? seed.score : undefined,
           hitReason: reasons.firstInclusionReason || 'semantic-seed',
           supplementaryReasons: Object.freeze(reasons.supplementaryReasons || []),
+          ...(snippet ? { matchedSnippet: snippet } : {}),
         });
       })),
   ])));
@@ -3716,19 +3885,25 @@ function inferObjectTypeFromSeedType(type) {
   return 'Element';
 }
 
-function summarizeElements(source, hitReasonByKey, limit) {
+function summarizeElements(source, hitReasonByKey, limit, ctx = {}) {
+  // Semantic subgraph rule: the attribute/testcase-DERIVED fields (status /
+  // functionalPoints / testCoverage) and the matchedSnippet are the match
+  // surface for the HIT elements only; closure neighbours drop them
+  // (bookkeepingOmitted) — mirroring the structural-read projection.
+  const hitIds = ctx.hitElementIds || buildHitIdSet(source, 'elements');
   return uniqueById([
     ...(((source.closure && source.closure.elements) || [])),
     ...((((source.viewClosure && source.viewClosure.views) || []).flatMap(view => view.memberElements || []))),
     ...((((source.endpointClosure && source.endpointClosure.relationships) || []).flatMap(relationship => [relationship.source, relationship.target]).filter(Boolean))),
-  ], 'id').slice(0, limit).map(element => summarizeElement(element, hitReasonByKey));
+  ], 'id').slice(0, limit).map(element => summarizeElement(element, hitReasonByKey, hitIds, ctx));
 }
 
-function summarizeRelationships(source, hitReasonByKey, limit) {
+function summarizeRelationships(source, hitReasonByKey, limit, ctx = {}) {
+  const hitIds = ctx.hitRelationshipIds || buildHitIdSet(source, 'relationships');
   return uniqueById([
     ...(((source.endpointClosure && source.endpointClosure.relationships) || [])),
     ...((((source.viewClosure && source.viewClosure.views) || []).flatMap(view => view.memberRelationships || []))),
-  ], 'id').slice(0, limit).map(relationship => summarizeRelationship(relationship, hitReasonByKey));
+  ], 'id').slice(0, limit).map(relationship => summarizeRelationship(relationship, hitReasonByKey, hitIds, ctx));
 }
 
 function summarizeViews(source, hitReasonByKey, limit) {
@@ -3737,27 +3912,38 @@ function summarizeViews(source, hitReasonByKey, limit) {
     .map(view => summarizeView(view, hitReasonByKey));
 }
 
-function summarizeElement(element, hitReasonByKey) {
+function summarizeElement(element, hitReasonByKey, hitIds = null, ctx = {}) {
   const attributes = attributesMap(element);
   const reasons = hitReasonByKey.get(`Element:${element.id}`) || {};
-  return Object.freeze({
+  const isHit = !hitIds || hitIds.size === 0 || hitIds.has(element.id);
+  const base = {
     id: element.id,
     name: element.name,
     type: element.type,
     descriptionSummary: summarizeText(element.description),
-    status: attributes.deliveryStatus || attributes.status,
-    functionalPoints: Object.freeze(Object.entries(attributes)
-      .filter(([name]) => name.startsWith('functionalPoint'))
-      .map(([, value]) => value)),
-    testCoverage: summarizeTestcases(element.testcases),
     hitReason: reasons.firstInclusionReason,
     supplementaryReasons: Object.freeze(reasons.supplementaryReasons || []),
-  });
+  };
+  if (isHit) {
+    const snippet = bookkeepingSnippet(element, 'Element', ctx.query);
+    return Object.freeze({
+      ...base,
+      status: attributes.deliveryStatus || attributes.status,
+      functionalPoints: Object.freeze(Object.entries(attributes)
+        .filter(([name]) => name.startsWith('functionalPoint'))
+        .map(([, value]) => value)),
+      testCoverage: summarizeTestcases(element.testcases),
+      ...(snippet ? { matchedSnippet: snippet } : {}),
+    });
+  }
+  const hasBookkeeping = Object.keys(attributes).length > 0
+    || (Array.isArray(element.testcases) && element.testcases.length > 0);
+  return Object.freeze({ ...base, ...(hasBookkeeping ? { bookkeepingOmitted: true } : {}) });
 }
 
-function summarizeRelationship(relationship, hitReasonByKey) {
+function summarizeRelationship(relationship, hitReasonByKey, hitIds = null, ctx = {}) {
   const reasons = hitReasonByKey.get(`ArchitectureRelationship:${relationship.id}`) || {};
-  return Object.freeze({
+  const base = {
     id: relationship.id,
     name: relationship.name,
     type: relationship.type,
@@ -3765,7 +3951,13 @@ function summarizeRelationship(relationship, hitReasonByKey) {
     target_id: relationship.target_id,
     hitReason: reasons.firstInclusionReason,
     supplementaryReasons: Object.freeze(reasons.supplementaryReasons || []),
-  });
+  };
+  const isHit = !hitIds || hitIds.size === 0 || hitIds.has(relationship.id);
+  if (!isHit) {
+    return Object.freeze(base);
+  }
+  const snippet = bookkeepingSnippet(relationship, 'ArchitectureRelationship', ctx.query);
+  return Object.freeze({ ...base, ...(snippet ? { matchedSnippet: snippet } : {}) });
 }
 
 function summarizeView(view, hitReasonByKey) {
@@ -4239,6 +4431,7 @@ module.exports = {
   GET_SYSTEM_ARCHITECTURE_OUTPUT_SCHEMA,
   TOOLS,
   applyMutations,
+  buildBusinessSemanticSummary,
   buildSemanticDedupAdvisory,
   selectCreatedElementAdds,
   evaluateSemanticDedupGate,

package/argo/skills/agent-search-diagnosis/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: agent-search-diagnosis
+description: "诊断一次 Agent 会话的检索/搜索行为（是否过度搜索、轮次/token/耗时花在哪、是否重复或空手、图↔仓往返），产出一份自包含的『诊断包』（diagnosis.md 总结 + metrics.json + 会话 NDJSON + 插件日志切片 + manifest.json），供人类伙伴打包回传以便进一步分析优化。Use when the user says an agent session searched too many rounds / wants to diagnose retrieval cost or over-search, or asks to produce a diagnostic bundle to send back. Keywords: 过度搜索, 诊断, over-search, search diagnosis, retrieval cost, diagnostic bundle, agent-search-diagnosis."
+---
+
+# Agent Search Diagnosis
+
+把**一次 Agent 会话**变成一份自包含的**诊断包**：现场出诊断总结 + 聚合关键数据到一个目录，用户打包回传即可。
+
+## 数据来源
+
+- **主**：宿主会话 NDJSON（含每个工具的**完整入参/输出**、时间戳、tokens）。
+- **辅**：框架后台日志 `<workspace>/.argo/temp/agent-cost-log.ndjson`（跨会话成本形态）。
+
+## 输出（固定目录）
+
+```
+<workspace>/.argo/temp/diagnosis/<session-id>/
+  ├─ diagnosis.md            # 人读诊断总结（含启发式建议，供 Agent 复核）
+  ├─ metrics.json            # 总结背后的数字
+  ├─ session.ndjson          # 原始会话（全保真）
+  ├─ cost-log.slice.ndjson   # 匹配该会话的后台日志切片
+  └─ manifest.json           # 文件清单 + 大小 + 版本
+```
+
+## Workflow
+
+### 1. 定位并导出会话
+
+- 若用户给出了 sessionID：`opencode export <sessionID> > <tmp>.ndjson`。
+- 若未给出：`opencode session list` 取最近会话，或请用户指定。
+- 宿主不支持导出时：退化为**仅用后台日志**（`agent-cost-log.ndjson`，诊断能力受限，须在报告中注明）。
+
+### 2. 运行诊断脚本（确定性）
+
+```
+node ~/.argo/scripts/agentSearchDiagnose.js --session <session.ndjson> \
+  [--session-id <id>] [--workspace .] [--cost-log <path>] [--json]
+```
+
+脚本**只读**会话与日志，写出上面的 bundle 目录，输出概览与启发式 hints。
+支持两种输入：`opencode export` 的会话 JSON（`{info, messages}`）与 `opencode run --format json` 的事件流 NDJSON。
+
+### 3. 复核并补充诊断总结（Agent）
+
+- 读 `diagnosis.md` 与 `metrics.json`。
+- 在报告末尾追加一节 `## Agent 复核解读`：结合会话片段指出**最可能的过度搜索根因**与**建议的优化方向**（去重/缓存、查询构造、停止判据、上下文压缩、图↔仓往返合并等）。
+- 不臆造：结论必须能从 metrics/会话片段找到依据。
+
+### 4. 交付给用户
+
+- 报告 bundle 目录路径，请用户**打包该目录**回传。
+- 给一段简短结论（轮次/token/耗时拆分 + 主要信号）。
+
+## Rules（MUST / MUST NOT）
+
+- **MUST** 只用确定性脚本 + 会话/日志读取；**MUST NOT** 修改图谱、仓库或任何框架内容。
+- **MUST NOT** 读取或打印 `.env`/凭据；若会话片段疑似含密钥，**MUST** 提醒用户回传前先审查 `session.ndjson`（其中是原始工具 I/O）。
+- **MUST** 在结论中区分「事实（metrics）」与「推断（根因假设）」，推断须标注依据。
+- 若无法导出会话或脚本不可用，**MUST** 如实说明并给出退化方案，不得臆测诊断结果。

package/install-argo.ps1

@@ -788,8 +788,11 @@ $skillDest = Join-Path $SkillsRoot 'argo-init'
 Write-Host "[4/22] argo\skills\argo-init -> $skillDest"
 Copy-Tree -Source $skillSrc -Destination $skillDest
 $reconcileSkillSrc = Join-Path (Join-Path $argoDir 'skills') 'ea-human-reconcile'
+$diagSkillSrc = Join-Path (Join-Path $argoDir 'skills') 'agent-search-diagnosis'
 Write-Host '  argo\skills\ea-human-reconcile -> $SkillsRoot\ea-human-reconcile (EA human draft reconcile skill)'
 Copy-Tree -Source $reconcileSkillSrc -Destination (Join-Path $SkillsRoot 'ea-human-reconcile')
+Write-Host '  argo\skills\agent-search-diagnosis -> $SkillsRoot\agent-search-diagnosis (agent search diagnosis skill)'
+Copy-Tree -Source $diagSkillSrc -Destination (Join-Path $SkillsRoot 'agent-search-diagnosis')
 
 $ruleSrc = Join-Path (Join-Path $argoDir 'rules') 'archgraph.instructions.md'
 $ruleDest = Join-Path $PromptsRoot 'archgraph.instructions.md'
@@ -807,6 +810,8 @@ Write-Host "[7/22] argo\skills\argo-init -> $cursorSkillDest (Cursor)"
 Copy-Tree -Source $skillSrc -Destination $cursorSkillDest
 Write-Host '  argo\skills\ea-human-reconcile -> $CursorSkillsRoot\ea-human-reconcile (Cursor)'
 Copy-Tree -Source $reconcileSkillSrc -Destination (Join-Path $CursorSkillsRoot 'ea-human-reconcile')
+Write-Host '  argo\skills\agent-search-diagnosis -> $CursorSkillsRoot\agent-search-diagnosis (Cursor)'
+Copy-Tree -Source $diagSkillSrc -Destination (Join-Path $CursorSkillsRoot 'agent-search-diagnosis')
 
 $mcpBridgeSrc = Join-Path $argoDir 'mcp-bridges'
 $mcpBridgeDest = Join-Path $CursorMcpBridgesRoot ''
@@ -818,6 +823,8 @@ Write-Host "[8/22] argo\skills\argo-init -> $openCodeSkillDest (OpenCode)"
 Copy-Tree -Source $skillSrc -Destination $openCodeSkillDest
 Write-Host '  argo\skills\ea-human-reconcile -> $OpenCodeSkillsRoot\ea-human-reconcile (OpenCode)'
 Copy-Tree -Source $reconcileSkillSrc -Destination (Join-Path $OpenCodeSkillsRoot 'ea-human-reconcile')
+Write-Host '  argo\skills\agent-search-diagnosis -> $OpenCodeSkillsRoot\agent-search-diagnosis (OpenCode)'
+Copy-Tree -Source $diagSkillSrc -Destination (Join-Path $OpenCodeSkillsRoot 'agent-search-diagnosis')
 
 Write-Host "[9/22] argo\rules\archgraph.instructions.md -> $OpenCodeAgentsPath (OpenCode global AGENTS.md)"
 Add-AgentsRule -AgentsPath $OpenCodeAgentsPath -RulePath $ruleSrc
@@ -857,6 +864,8 @@ if ($SkipDsh) {
     Copy-Tree -Source (Join-Path $argoDir 'skills\argo-init') -Destination $dshSkillDest
     Write-Host '  argo\skills\ea-human-reconcile -> $DshHome\skills\ea-human-reconcile (DeepSeek Harness skill)'
     Copy-Tree -Source (Join-Path $argoDir 'skills\ea-human-reconcile') -Destination (Join-Path (Join-Path $DshHome 'skills') 'ea-human-reconcile')
+    Write-Host '  argo\skills\agent-search-diagnosis -> $DshHome\skills\agent-search-diagnosis (DeepSeek Harness skill)'
+    Copy-Tree -Source $diagSkillSrc -Destination (Join-Path (Join-Path $DshHome 'skills') 'agent-search-diagnosis')
 
     Write-Host "[17/22] argo\rules\<WakeupGuideline> -> $DshHome\plugins\dsh-argo-wakeup\index.js (DeepSeek Harness wakeup plugin)"
     $wakeupDshPath = New-DshWakeupPlugin -DshHome $DshHome -RuleText $ruleSrcContent
@@ -918,8 +927,10 @@ if ($SkipOpenClaw) {
 
     Write-Host "[21/22] argo\skills\argo-init -> $openClawSkillDest (OpenClaw managed skill, all agents)"
     Copy-Tree -Source (Join-Path $argoDir 'skills\argo-init') -Destination $openClawSkillDest
-    Write-Host '  argo\skills\ea-human-reconcile -> $OpenClawHome\skills\ea-human-reconcile (OpenClaw managed skill, all agents)'
-    Copy-Tree -Source (Join-Path $argoDir 'skills\ea-human-reconcile') -Destination (Join-Path (Join-Path $OpenClawHome 'skills') 'ea-human-reconcile')
+Write-Host '  argo\skills\ea-human-reconcile -> $OpenClawHome\skills\ea-human-reconcile (OpenClaw managed skill, all agents)'
+Copy-Tree -Source (Join-Path $argoDir 'skills\ea-human-reconcile') -Destination (Join-Path (Join-Path $OpenClawHome 'skills') 'ea-human-reconcile')
+Write-Host '  argo\skills\agent-search-diagnosis -> $OpenClawHome\skills\agent-search-diagnosis (OpenClaw managed skill, all agents)'
+Copy-Tree -Source $diagSkillSrc -Destination (Join-Path (Join-Path $OpenClawHome 'skills') 'agent-search-diagnosis')
 
     Write-Host '  OpenClaw injects AGENTS.md into Project Context on every session, so the wakeup'
     Write-Host '  gate (UNCONDITIONAL STARTUP GATE) is active on the next OpenClaw session; restart'

package/package.json

@@ -1,52 +1,53 @@
-{
-  "name": "archgraph-argo",
-  "version": "0.25.0",
-  "description": "Deploy the ArchGraph ARGO toolchain, skills, and rules (schema, scripts, argo-init skill, global rule) with one command.",
-  "license": "MIT",
-  "bin": {
-    "argo-deploy": "bin/argo-deploy.js"
-  },
-  "files": [
-    "argo/scripts",
-    "argo/schema",
-    "argo/defaults",
-    "argo/agents",
-    "argo/plugins",
-    "argo/mcp-bridges",
-    "argo/skills/argo-init",
-    "argo/skills/ea-human-reconcile",
-    "argo/rules",
-    "argo/package.json",
-    "argo/.env.example",
-    "vendor",
-    "install-argo.ps1",
-    "bin",
-    "cordis.patch.yml",
-    "dsh-argo-workspace",
-    "dsh-argo-wakeup"
-  ],
-  "exports": {
-    "./dsh-argo-workspace": "./dsh-argo-workspace/index.js",
-    "./dsh-argo-wakeup": "./dsh-argo-wakeup/index.js",
-    "./cordis.patch.yml": "./cordis.patch.yml",
-    "./package.json": "./package.json"
-  },
-  "dsh": {
-    "bundle": {
-      "patch": "./cordis.patch.yml"
-    }
-  },
-  "dependencies": {
-    "neo4j-driver": "^6.2.0"
-  },
-  "devDependencies": {
-    "@resvg/resvg-js": "^2.6.2",
-    "playwright": "1.61.1"
-  },
-  "scripts": {
-    "test": "node --test \"tests/*.test.js\""
-  },
-  "engines": {
-    "node": ">=18"
-  }
-}
+{
+  "name": "archgraph-argo",
+  "version": "0.26.1",
+  "description": "Deploy the ArchGraph ARGO toolchain, skills, and rules (schema, scripts, argo-init skill, global rule) with one command.",
+  "license": "MIT",
+  "bin": {
+    "argo-deploy": "bin/argo-deploy.js"
+  },
+  "files": [
+    "argo/scripts",
+    "argo/schema",
+    "argo/defaults",
+    "argo/agents",
+    "argo/plugins",
+    "argo/mcp-bridges",
+    "argo/skills/argo-init",
+    "argo/skills/ea-human-reconcile",
+    "argo/skills/agent-search-diagnosis",
+    "argo/rules",
+    "argo/package.json",
+    "argo/.env.example",
+    "vendor",
+    "install-argo.ps1",
+    "bin",
+    "cordis.patch.yml",
+    "dsh-argo-workspace",
+    "dsh-argo-wakeup"
+  ],
+  "exports": {
+    "./dsh-argo-workspace": "./dsh-argo-workspace/index.js",
+    "./dsh-argo-wakeup": "./dsh-argo-wakeup/index.js",
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "dependencies": {
+    "neo4j-driver": "^6.2.0"
+  },
+  "devDependencies": {
+    "@resvg/resvg-js": "^2.6.2",
+    "playwright": "1.61.1"
+  },
+  "scripts": {
+    "test": "node --test \"tests/*.test.js\""
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}