archgraph-argo 0.26.0 → 0.26.2

package/argo/scripts/agentSearchDiagnose.js

@@ -46,16 +46,27 @@ function backendOf(tool) {
 
 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 (GRAPH_WRITE_TOOLS.some(t => n.includes(t))) return 'write';
+  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);
@@ -93,6 +104,31 @@ function eventTime(e) {
   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 = [];
@@ -150,13 +186,18 @@ function diagnose(session, opts = {}) {
   const byQueryClass = {};
   const sigCount = {};
   const pathReads = {};
-  let toolMs = 0; let errors = 0; let empty = 0;
+  let toolMs = 0; let humanWaitMs = 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 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;
@@ -185,17 +226,19 @@ function diagnose(session, opts = {}) {
   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;
+  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,
+      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 },
@@ -207,12 +250,13 @@ function diagnose(session, opts = {}) {
     },
     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) }),
+    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} 处 → 考虑读取缓存或先摘要后精读。`);
@@ -238,7 +282,7 @@ function renderDiagnosis(m, meta) {
   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(`| 墙钟 | ${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('');
@@ -264,6 +308,12 @@ function renderDiagnosis(m, meta) {
   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}`);
@@ -281,7 +331,8 @@ function fmtMs(ms) {
 
 function writeBundle(opts) {
   const workspace = opts.workspace || process.cwd();
-  const sessionText = fs.readFileSync(opts.session, 'utf8');
+  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);
@@ -351,6 +402,6 @@ function main(argv) {
   return 0;
 }
 
-module.exports = { BUNDLE_VERSION, SCHEMA_VERSION, parseSession, classifyQuery, backendOf, signature, diagnose, renderDiagnosis, writeBundle, sliceCostLog, main };
+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,55 @@ 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 byteLenLocal(value) {
+  try { return Buffer.byteLength(JSON.stringify(value)); } catch (_) { return 0; }
+}
+
+function projectAgentFields(record, opts = {}) {
+  const value = clone(record);
+  let omittedAttributes = 0;
+  let omittedTestcases = 0;
+  let omittedBytes = 0;
+  if (!opts.includeAttributes && Array.isArray(value.attributes) && value.attributes.length) {
+    omittedAttributes = value.attributes.length;
+    omittedBytes += byteLenLocal(value.attributes);
+    delete value.attributes;
+  }
+  if (!opts.includeTestcases && Array.isArray(value.testcases) && value.testcases.length) {
+    omittedTestcases = value.testcases.length;
+    omittedBytes += byteLenLocal(value.testcases);
+    delete value.testcases;
+  }
+  return { value, omittedAttributes, omittedTestcases, omittedBytes };
+}
+
+function buildAgentProjection(omitted) {
+  if (!omitted || (omitted.attributes === 0 && omitted.testcases === 0)) {
+    return null;
+  }
+  // Only attach the explanation when the omission actually saves more than the
+  // note costs, so trimming a read can NEVER make it larger (cross-scenario
+  // no-degradation). The opt-in flags are documented in the tool description.
+  if ((omitted.bytes || 0) < 160) {
+    return null;
+  }
+  return {
+    attributesOmitted: omitted.attributes,
+    testcasesOmitted: omitted.testcases,
+    note: 'includeAttributes/includeTestcases=true to include (omitted by default; semantic hits keep them).',
+  };
+}
+
 function buildIntentElementContext(context, args = {}) {
   const profile = args.profile || 'generic-agent';
   const focusResult = resolveFocusElement(context.document, args);
@@ -697,7 +750,29 @@ 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, bytes: 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;
+      omitted.bytes += projected.omittedBytes;
+      return projected.value;
+    });
+    subgraph.relationships = subgraph.relationships.map((relationship) => {
+      const projected = projectAgentFields(relationship, { includeAttributes });
+      omitted.attributes += projected.omittedAttributes;
+      omitted.bytes += projected.omittedBytes;
+      return projected.value;
+    });
+  }
+  const result = {
     status: 'passed',
     query: {
       architecturePath: context.graphPath.relativePath,
@@ -711,12 +786,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 +864,23 @@ 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, bytes: 0 };
+  const project = (record) => {
+    const projected = projectAgentFields(record, { includeAttributes, includeTestcases });
+    omitted.attributes += projected.omittedAttributes;
+    omitted.testcases += projected.omittedTestcases;
+    omitted.bytes += projected.omittedBytes;
+    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 +891,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 +901,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 +936,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 +2841,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 +2854,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 +2874,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 +3388,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 +3806,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 +3878,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 +3901,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 +3928,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 +3967,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 +4447,7 @@ module.exports = {
   GET_SYSTEM_ARCHITECTURE_OUTPUT_SCHEMA,
   TOOLS,
   applyMutations,
+  buildBusinessSemanticSummary,
   buildSemanticDedupAdvisory,
   selectCreatedElementAdds,
   evaluateSemanticDedupGate,

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

@@ -39,6 +39,7 @@ node ~/.argo/scripts/agentSearchDiagnose.js --session <session.ndjson> \
 ```
 
 脚本**只读**会话与日志，写出上面的 bundle 目录，输出概览与启发式 hints。
+支持两种输入：`opencode export` 的会话 JSON（`{info, messages}`）与 `opencode run --format json` 的事件流 NDJSON。
 
 ### 3. 复核并补充诊断总结（Agent）
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "archgraph-argo",
-  "version": "0.26.0",
+  "version": "0.26.2",
   "description": "Deploy the ArchGraph ARGO toolchain, skills, and rules (schema, scripts, argo-init skill, global rule) with one command.",
   "license": "MIT",
   "bin": {