archgraph-argo 0.24.3 → 0.26.0

package/argo/plugins/argo-cost-collector.js

@@ -0,0 +1,35 @@
+// Argo agent-cost collector plugin for opencode.
+//
+// The framework records ONE consolidated agent-cost log per workspace at
+// <workspace>/.argo/temp/agent-cost-log.ndjson, so the user fetches a single
+// file instead of stitching logs from several places. This plugin is the ONLY
+// collector: it sees EVERY tool call the agent makes — MCP interface calls
+// (e.g. getSystemArchitecture), graph writes (e.g. applySystemArchitectureMutation)
+// and repository calls (read / grep / glob) alike — plus assistant token/cost
+// usage, which an MCP-side hook could never observe completely.
+//
+// Recording only observes; it never changes retrieval. Disable with
+// ARGO_COST_PROFILER=0.
+
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+let log = null;
+try {
+  log = require('../scripts/graph-rag/agentCostLog.js');
+} catch {
+  // The shared log module ships next to the plugins under ~/.argo; if it is
+  // missing this plugin is a no-op so it can never break a session.
+  log = null;
+}
+
+export default async function argoCostCollector(input) {
+  if (!log) return {};
+  const workspaceRoot = (input && (input.directory || input.worktree)) || process.cwd();
+  const hooks = log.createHostCollectorHooks(workspaceRoot);
+  return {
+    "tool.execute.before": async (i) => { try { hooks.before(i); } catch { /* best-effort */ } },
+    "tool.execute.after": async (i, o) => { try { hooks.after(i, o); } catch { /* best-effort */ } },
+    event: async (payload) => { try { hooks.event(payload); } catch { /* best-effort */ } },
+  };
+}

package/argo/scripts/agentSearchDiagnose.js

@@ -0,0 +1,356 @@
+'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('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('read')) return 'file-read';
+  if (n.includes('grep')) return 'grep';
+  if (n.includes('glob') || n.includes('list')) return 'list';
+  if (GRAPH_WRITE_TOOLS.some(t => n.includes(t))) return 'write';
+  return 'other';
+}
+
+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 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 errors = 0; let empty = 0;
+  for (const c of tc) {
+    const b = byBackend[c.backend] || (byBackend[c.backend] = { calls: 0, ms: 0 });
+    b.calls += 1; b.ms += c.durationMs || 0;
+    toolMs += c.durationMs || 0;
+    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 (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) : null;
+
+  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,
+      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,
+    },
+    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) }),
+  };
+}
+
+function buildHints(m) {
+  const hints = [];
+  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)} |`);
+  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('');
+  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 sessionText = fs.readFileSync(opts.session, 'utf8');
+  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, main };
+
+if (require.main === module) process.exit(main());

package/argo/scripts/graph-rag/agentCostLog.js

@@ -0,0 +1,179 @@
+'use strict';
+
+// Agent cost LOG (framework, zero-config, background) — the single consolidated
+// store for everything needed to reason about an agent's retrieval cost.
+//
+// WHY ONE FILE: in a real project the agent's scope is the whole repository (an
+// unbounded content source) plus the curated intent graph (KG, only a semantic
+// index / routing layer). Cost is dominated by the agent's round-trips BETWEEN
+// the two backends (graph: getSystemArchitecture / getIntentElementContext /
+// getArchitectureViewContext / queryNeo4jGraph / memory_search; repository:
+// read / grep / glob), not by the size of either backend. To optimise without
+// hurting recall we must measure that — in ONE place the user fetches once:
+//
+//     <workspace>/.argo/temp/agent-cost-log.ndjson
+//
+// WHO WRITES: the OpenCode plugin argo/plugins/argo-cost-collector.js. Every
+// tool call the agent makes — MCP interface calls, graph writes, and repository
+// calls alike — is a host tool, so the plugin records ALL of them, plus the
+// assistant's token/cost usage. There is deliberately NO MCP-side instrumentation
+// (a record without the host side would be incomplete and thus misleading).
+//
+// Posture (mirrors mcpCrashDiagnostics): best-effort, never throws, never logs
+// secret values, and NEVER changes retrieval (it observes results only).
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const LOG_FILE_NAME = 'agent-cost-log.ndjson';
+const DEFAULT_MAX_BYTES = 5 * 1024 * 1024;
+
+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 enabled() {
+  return process.env.ARGO_COST_PROFILER !== '0';
+}
+
+function maxBytes() {
+  const n = Number(process.env.ARGO_COST_TRACE_MAX_BYTES);
+  return Number.isFinite(n) && n > 0 ? n : DEFAULT_MAX_BYTES;
+}
+
+function tempDir(workspaceRoot) {
+  return path.join(workspaceRoot, '.argo', 'temp');
+}
+
+function logFilePath(workspaceRoot) {
+  return path.join(tempDir(workspaceRoot), LOG_FILE_NAME);
+}
+
+// Pure, total classification. Host tool names may be prefixed (e.g.
+// mcp__argo__getSystemArchitecture), so match by substring.
+function classifyTool(tool) {
+  const name = String(tool || '');
+  const hit = (list) => list.some(t => name.includes(t));
+  if (hit(GRAPH_WRITE_TOOLS)) return { backend: 'graph', kind: 'write' };
+  if (hit(GRAPH_TOOLS)) return { backend: 'graph', kind: 'read' };
+  if (hit(VALIDATOR_TOOLS)) return { backend: 'framework', kind: 'framework' };
+  if (hit(REPO_TOOLS)) return { backend: 'repo', kind: 'read' };
+  return { backend: 'other', kind: 'other' };
+}
+
+// Deterministic coarse token estimate: CJK ≈ 1 token/char, else ≈ 1/4 chars.
+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 rotateIfNeeded(file, limit) {
+  try {
+    if (fs.statSync(file).size >= limit) fs.renameSync(file, `${file}.1`);
+  } catch (_) { /* no existing log */ }
+}
+
+// Append one record to the single consolidated log. Best-effort: any failure is
+// swallowed so logging can never affect a tool call.
+function appendRecord(workspaceRoot, record) {
+  if (!enabled() || !workspaceRoot || !record || typeof record !== 'object') return;
+  try {
+    const file = logFilePath(workspaceRoot);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    rotateIfNeeded(file, maxBytes());
+    const line = JSON.stringify({ at: new Date().toISOString(), pid: process.pid, ...record }) + '\n';
+    fs.appendFileSync(file, line, 'utf8');
+  } catch (_) {
+    // best-effort only
+  }
+}
+
+function readLog(workspaceRoot) {
+  const file = logFilePath(workspaceRoot);
+  let raw = '';
+  try { raw = fs.readFileSync(file, 'utf8'); } catch (_) { return { file, records: [] }; }
+  const records = [];
+  for (const line of raw.split('\n')) {
+    const t = line.trim();
+    if (!t.startsWith('{')) continue;
+    try { records.push(JSON.parse(t)); } catch (_) { /* skip malformed */ }
+  }
+  return { file, records };
+}
+
+function byteLen(value) {
+  try {
+    const s = JSON.stringify(value);
+    return (typeof Buffer !== 'undefined') ? Buffer.byteLength(s) : s.length;
+  } catch (_) { return 0; }
+}
+
+function keysOf(value) {
+  return (value && typeof value === 'object' && !Array.isArray(value)) ? Object.keys(value).sort() : [];
+}
+
+// Host-collector hook logic (used by the OpenCode plugin; unit-tested in CJS).
+// It records EVERY host tool call — MCP interface calls, graph writes, and
+// repository calls alike — plus assistant token/cost usage into the single log.
+function createHostCollectorHooks(workspaceRoot) {
+  const starts = new Map();
+  const seenUsage = new Set();
+  return {
+    before(input) {
+      if (!input || !input.callID) return;
+      const args = input.args || {};
+      starts.set(input.callID, { t: Date.now(), keys: keysOf(args), bytes: byteLen(args) });
+    },
+    after(input, output) {
+      if (!input) return;
+      const s = starts.get(input.callID) || {};
+      const cls = classifyTool(input.tool);
+      const out = (output && output.output) || '';
+      appendRecord(workspaceRoot, {
+        source: 'host',
+        type: 'tool',
+        sessionID: input.sessionID,
+        callID: input.callID,
+        tool: input.tool,
+        backend: cls.backend,
+        kind: cls.kind,
+        durationMs: s.t ? (Date.now() - s.t) : 0,
+        ok: true,
+        args: { keys: s.keys || keysOf(input.args), bytes: s.bytes != null ? s.bytes : byteLen(input.args) },
+        resultBytes: String(out).length,
+        resultTokens: estimateTokens(out),
+      });
+      starts.delete(input.callID);
+    },
+    event(payload) {
+      const event = payload && payload.event;
+      const props = (event && event.properties) || {};
+      const info = props.info || (event && event.info) || null;
+      if (info && info.role === 'assistant' && info.tokens && info.id && !seenUsage.has(info.id)) {
+        seenUsage.add(info.id);
+        appendRecord(workspaceRoot, {
+          source: 'host',
+          type: 'usage',
+          sessionID: info.sessionID,
+          messageID: info.id,
+          tokens: info.tokens,
+          cost: info.cost,
+        });
+      }
+    },
+  };
+}
+
+module.exports = {
+  LOG_FILE_NAME,
+  enabled, tempDir, logFilePath, classifyTool, estimateTokens,
+  appendRecord, readLog, createHostCollectorHooks,
+};

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

@@ -0,0 +1,59 @@
+---
+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。
+
+### 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'
@@ -1109,5 +1120,14 @@ if (Test-Path $wakeupPluginPath) {
     Write-Host "argo-wakeup plugin registered -> $OpenCodeConfigPath"
 }
 
+# Agent-cost collector: the complete host-side writer of the single consolidated
+# agent-cost log (<workspace>/.argo/temp/agent-cost-log.ndjson).
+$costCollectorPath = Join-Path $PluginsRoot 'argo-cost-collector.js'
+if (Test-Path $costCollectorPath) {
+    Write-Host '==> Registering argo-cost-collector plugin in OpenCode'
+    Register-OpenCodePlugin -ConfigPath $OpenCodeConfigPath -PluginFilePath $costCollectorPath
+    Write-Host "argo-cost-collector plugin registered -> $OpenCodeConfigPath"
+}
+
 Write-Host ''
 Write-Host 'Argo deployment complete.'

package/package.json

@@ -1,52 +1,53 @@
-{
-  "name": "archgraph-argo",
-  "version": "0.24.3",
-  "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.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/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"
+  }
+}