archgraph-argo 0.13.5 → 0.13.7

package/argo/scripts/ea-human-diff.js

@@ -0,0 +1,604 @@
+'use strict';
+
+// WP2792 (AT-2792-01..06): EA human-draft -> semantic diff -> agent write-back.
+// Compares the EA *visible object model* of two .qea snapshots (baseline committed
+// .qea vs human-edited working .qea) and classifies the human's changes into
+// canonical-graph proposals (addElement/updateElement/removeElement,
+// addRelationship/updateRelationship/removeRelationship, updateView membership).
+//
+// Why the visible object model and NOT kg_sync_meta:
+//   kg_sync_meta is a lossless canonical mirror written only by the projector; a human
+//   editing in EA touches t_object/t_connector/t_diagram/t_diagramobjects (plus the
+//   schema_id / archimate_type anchor tags). Comparing mirrors would show zero diff for
+//   human edits. So we anchor via the schema_id tag (elements: t_objectproperties,
+//   relationships: t_connectortag; views: t_diagram schema_view_id StyleEx token OR the
+//   deterministic diag:<viewId> ea_guid written by the projection).
+//
+// Semantic-first (v1): pure geometry (t_diagramobjects coordinates) never becomes a
+// canonical proposal — it is only counted (layoutOnly) and excluded.
+//
+// Zero third-party deps, no EA required: node:sqlite via the shared lib helper.
+//   node argo/scripts/ea-human-diff.js --base <base.qea> --work <work.qea> [--graph <json>]
+//        [--out <stem>] [--no-md] [--baseline-commit <sha>]
+//   --base is optional: when omitted and --work is a tracked file inside the git repo,
+//   the committed (HEAD) version of --work is extracted automatically as the baseline —
+//   the day-to-day "human edited archgraph.qea" flow is then a single command.
+
+const path = require('node:path');
+const fs = require('node:fs');
+const lib = require('./ea-qea-sync-lib.js');
+const { deterministicGuid } = lib;
+
+// ---------------------------------------------------------------------------
+// readSnapshot — read one .qea's semantic EA-visible projection surface
+// ---------------------------------------------------------------------------
+function parseStyleToken(styleEx, key) {
+  const text = String(styleEx === null || styleEx === undefined ? '' : styleEx);
+  const re = new RegExp('(^|;|\\s)' + key + '=([^;]*)', 'i');
+  const m = re.exec(text);
+  return m ? m[2] : '';
+}
+
+function readSnapshot(qeaPath, opts) {
+  const o = opts || {};
+  const db = lib.openQea(qeaPath);
+  try {
+    const snapshot = {
+      path: qeaPath,
+      syncPackageId: 0,
+      // viewId -> { diagramId, name }
+      diagramsByView: new Map(),
+      // diagramId -> viewId
+      viewByDiagram: new Map(),
+      // canonical id -> element (anchored via schema_id tag)
+      elementBySchema: new Map(),
+      // eaGuid -> element (all t_object)
+      elementByGuid: new Map(),
+      // canonical id -> relationship (anchored via t_connectortag schema_id)
+      relBySchema: new Map(),
+      // eaGuid -> relationship (all t_connector)
+      relByGuid: new Map(),
+      // diagramId -> Map(objectId -> coords)
+      placements: new Map(),
+      // informational: kg_sync_meta counts/shas (never used for proposal detection)
+      meta: { elements: 0, relationships: 0, views: 0, sha: '' },
+      knownViewIds: null, // set by resolveViews when a canonical view catalog is provided
+    };
+
+    // kg_sync_meta informational snapshot (human edits never touch it -> identical).
+    try {
+      const rows = db.prepare('SELECT kind, key, sha FROM kg_sync_meta ORDER BY kind, key').all();
+      snapshot.meta.elements = rows.filter((r) => r.kind === 'element').length;
+      snapshot.meta.relationships = rows.filter((r) => r.kind === 'relationship').length;
+      snapshot.meta.views = rows.filter((r) => r.kind === 'view').length;
+      const hasher = require('node:crypto').createHash('sha256');
+      for (const r of rows) { hasher.update(r.kind + '|' + r.key + '|' + r.sha); }
+      snapshot.meta.sha = hasher.digest('hex');
+    } catch { /* table may be absent on a hand-drawn model */ }
+
+    // sync package id
+    const roots = db.prepare('SELECT Package_ID FROM t_package WHERE Parent_ID=0 ORDER BY Package_ID LIMIT 1').all();
+    if (roots.length > 0) {
+      const pkg = db.prepare('SELECT Package_ID FROM t_package WHERE Parent_ID=? AND Name=? LIMIT 1').get(Number(roots[0].Package_ID), lib.SYNC_PACKAGE_NAME);
+      if (pkg) { snapshot.syncPackageId = Number(pkg.Package_ID); }
+    }
+
+    // diagrams -> view mapping (schema_view_id StyleEx token)
+    const diags = db.prepare('SELECT Diagram_ID, Package_ID, Name, StyleEx, ea_guid FROM t_diagram').all();
+    for (const d of diags) {
+      const v = parseStyleToken(d.StyleEx, 'schema_view_id');
+      if (v) {
+        const diagramId = Number(d.Diagram_ID);
+        snapshot.diagramsByView.set(v, { diagramId, name: String(d.Name || ''), eaGuid: String(d.ea_guid || '') });
+        snapshot.viewByDiagram.set(diagramId, v);
+      }
+    }
+    // Optionally also bind known view ids via deterministic diagram guid (robust when EA
+    // dropped the StyleEx token). Canonical view catalog supplied via --graph.
+    if (o.knownViewIds && Array.isArray(o.knownViewIds)) {
+      snapshot.knownViewIds = o.knownViewIds;
+      for (const v of o.knownViewIds) {
+        if (snapshot.diagramsByView.has(v)) { continue; }
+        const guid = deterministicGuid('diag:' + v);
+        const d = db.prepare('SELECT Diagram_ID, Name FROM t_diagram WHERE ea_guid = ? LIMIT 1').get(guid);
+        if (d) {
+          const diagramId = Number(d.Diagram_ID);
+          snapshot.diagramsByView.set(v, { diagramId, name: String(d.Name || ''), eaGuid: guid });
+          snapshot.viewByDiagram.set(diagramId, v);
+        }
+      }
+    }
+
+    // element anchor tags
+    const elemTags = new Map(); // Object_ID -> {schemaId?, archimateType?}
+    try {
+      const props = db.prepare("SELECT Object_ID, Property, Value FROM t_objectproperties WHERE Property IN ('schema_id','archimate_type')").all();
+      for (const p of props) {
+        const oid = Number(p.Object_ID);
+        if (!elemTags.has(oid)) { elemTags.set(oid, {}); }
+        const t = elemTags.get(oid);
+        if (p.Property === 'schema_id') { t.schemaId = String(p.Value); }
+        if (p.Property === 'archimate_type') { t.archimateType = String(p.Value); }
+      }
+    } catch { /* ignore */ }
+
+    const elems = db.prepare(
+      'SELECT Object_ID, Alias, ea_guid, Object_Type, Stereotype, Name, Note, Status, Package_ID FROM t_object'
+    ).all();
+    for (const e of elems) {
+      const rec = {
+        objectId: Number(e.Object_ID),
+        alias: e.Alias === null || e.Alias === undefined ? '' : String(e.Alias),
+        eaGuid: String(e.ea_guid || ''),
+        objectType: String(e.Object_Type || ''),
+        stereotype: String(e.Stereotype || ''),
+        name: String(e.Name || ''),
+        description: String(e.Note === null || e.Note === undefined ? '' : e.Note),
+        status: String(e.Status || ''),
+        packageId: Number(e.Package_ID || 0),
+      };
+      const tag = elemTags.get(rec.objectId);
+      if (tag && tag.schemaId) {
+        rec.schemaId = tag.schemaId;
+        rec.archimateType = tag.archimateType || '';
+        snapshot.elementBySchema.set(rec.schemaId, rec);
+      }
+      if (rec.eaGuid) { snapshot.elementByGuid.set(rec.eaGuid, rec); }
+    }
+
+    // relationship anchor tags — t_connectortag's value column is literally named VALUE,
+    // so alias it to Value for a case-stable row key (unlike t_objectproperties.Value).
+    const relTags = new Map(); // Connector_ID -> schemaId
+    try {
+      const props = db.prepare("SELECT ElementID, Property, VALUE AS Value FROM t_connectortag WHERE Property IN ('schema_id','archimate_relationship_type')").all();
+      for (const p of props) {
+        const cid = Number(p.ElementID);
+        if (!relTags.has(cid)) { relTags.set(cid, {}); }
+        const t = relTags.get(cid);
+        if (p.Property === 'schema_id') { t.schemaId = String(p.Value); }
+        if (p.Property === 'archimate_relationship_type') { t.archimateType = String(p.Value); }
+      }
+    } catch { /* ignore */ }
+
+    const conns = db.prepare(
+      'SELECT Connector_ID, ea_guid, Name, Connector_Type, Stereotype, Notes, Direction, Start_Object_ID, End_Object_ID FROM t_connector'
+    ).all();
+    for (const c of conns) {
+      const rec = {
+        connectorId: Number(c.Connector_ID),
+        eaGuid: String(c.ea_guid || ''),
+        name: String(c.Name || ''),
+        connectorType: String(c.Connector_Type || ''),
+        stereotype: String(c.Stereotype || ''),
+        description: String(c.Notes === null || c.Notes === undefined ? '' : c.Notes),
+        direction: String(c.Direction || ''),
+        sourceObjectId: Number(c.Start_Object_ID || 0),
+        targetObjectId: Number(c.End_Object_ID || 0),
+      };
+      const tag = relTags.get(rec.connectorId);
+      if (tag && tag.schemaId) {
+        rec.schemaId = tag.schemaId;
+        rec.archimateType = tag.archimateType || '';
+        snapshot.relBySchema.set(rec.schemaId, rec);
+      }
+      if (rec.eaGuid) { snapshot.relByGuid.set(rec.eaGuid, rec); }
+    }
+
+    // placements (diagram membership + geometry)
+    const objs = db.prepare(
+      'SELECT Diagram_ID, Object_ID, Sequence, RectLeft, RectTop, RectRight, RectBottom FROM t_diagramobjects'
+    ).all();
+    for (const r of objs) {
+      const diagramId = Number(r.Diagram_ID);
+      if (!snapshot.placements.has(diagramId)) { snapshot.placements.set(diagramId, new Map()); }
+      snapshot.placements.get(diagramId).set(Number(r.Object_ID), {
+        left: Number(r.RectLeft || 0), top: Number(r.RectTop || 0),
+        right: Number(r.RectRight || 0), bottom: Number(r.RectBottom || 0),
+      });
+    }
+    return snapshot;
+  } finally {
+    try { db.close(); } catch { /* ignore */ }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// semanticDiff — classify human changes between base and work snapshots
+// ---------------------------------------------------------------------------
+function normText(s) {
+  return String(s === null || s === undefined ? '' : s).trim();
+}
+
+function elementCanonicalContext(work, rec) {
+  // Is this EA object part of the projection-owned / canonical surface?
+  if (rec.schemaId) { return true; }
+  if (rec.packageId === work.syncPackageId) { return true; }
+  // placed on any canonical view diagram?
+  for (const [diagramId, members] of work.placements) {
+    if (work.viewByDiagram.has(diagramId) && members.has(rec.objectId)) { return true; }
+  }
+  return false;
+}
+
+function placedViewIds(work, objectId) {
+  const out = [];
+  for (const [diagramId, members] of work.placements) {
+    const viewId = work.viewByDiagram.get(diagramId);
+    if (viewId && members.has(objectId)) { out.push(viewId); }
+  }
+  return out;
+}
+
+function semanticDiff(base, work, opts) {
+  const o = opts || {};
+  const proposals = [];
+  const summary = {
+    addElement: 0, updateElement: 0, removeElement: 0,
+    addRelationship: 0, updateRelationship: 0, removeRelationship: 0,
+    updateView: 0,
+    layoutOnly: 0, geometryOnlyObjects: 0, outOfScopeNew: 0, removedUnanchored: 0, orphanAnchored: 0,
+  };
+  const push = (p) => { proposals.push(p); summary[p.op] = (summary[p.op] || 0) + 1; };
+
+  const metaUnchanged = base.meta.sha === work.meta.sha;
+
+  // --- geometry-only counting (never proposed) -----------------------------
+  for (const [diagramId, baseMembers] of base.placements) {
+    const viewId = base.viewByDiagram.get(diagramId);
+    if (!viewId) { continue; }
+    const workMembers = work.placements.get(diagramId);
+    if (!workMembers) { continue; }
+    for (const [objectId, baseCoords] of baseMembers) {
+      const workCoords = workMembers.get(objectId);
+      if (!workCoords) { continue; }
+      const moved = baseCoords.left !== workCoords.left || baseCoords.top !== workCoords.top ||
+        baseCoords.right !== workCoords.right || baseCoords.bottom !== workCoords.bottom;
+      if (moved) { summary.layoutOnly++; }
+    }
+  }
+
+  // --- elements: anchored content / removal / addition ---------------------
+  const baseSchemaIds = new Set(base.elementBySchema.keys());
+  const workSchemaIds = new Set(work.elementBySchema.keys());
+  for (const schemaId of baseSchemaIds) {
+    const b = base.elementBySchema.get(schemaId);
+    const w = work.elementBySchema.get(schemaId);
+    if (!w) {
+      // anchored element removed from the model -> removeElement
+      push({ op: 'removeElement', kind: 'element', id: schemaId, sourceEa: { guid: b.eaGuid } });
+      continue;
+    }
+    const fields = {};
+    if (normText(b.name) !== normText(w.name)) { fields.name = w.name; }
+    if (normText(b.description) !== normText(w.description)) { fields.description = w.description; }
+    if (normText(b.status) !== normText(w.status)) { fields.status = w.status; }
+    if (Object.keys(fields).length > 0) {
+      push({ op: 'updateElement', kind: 'element', id: schemaId, fields, sourceEa: { guid: w.eaGuid } });
+    }
+  }
+  for (const schemaId of workSchemaIds) {
+    if (baseSchemaIds.has(schemaId)) { continue; }
+    // anchored id present only in work (e.g. human duplicated a tagged object) — cannot map
+    // to a canonical id safely; count and skip (agent reconciles).
+    summary.orphanAnchored++;
+  }
+  // unanchored NEW objects in work (human drew fresh boxes)
+  for (const [eaGuid, rec] of work.elementByGuid) {
+    if (rec.schemaId) { continue; }
+    if (base.elementByGuid.has(eaGuid)) { continue; }
+    if (!elementCanonicalContext(work, rec)) { summary.outOfScopeNew++; continue; }
+    const viewIds = placedViewIds(work, rec.objectId);
+    push({
+      op: 'addElement', kind: 'element', id: null,
+      proposed: {
+        name: rec.name,
+        description: rec.description === '' ? undefined : rec.description,
+        eaType: { objectType: rec.objectType, stereotype: rec.stereotype },
+        viewIds: viewIds.length > 0 ? viewIds : undefined,
+      },
+      sourceEa: { guid: eaGuid, objectId: rec.objectId },
+    });
+  }
+  // unanchored objects removed in work (never canonical -> no proposal, count only)
+  for (const [eaGuid, rec] of base.elementByGuid) {
+    if (rec.schemaId) { continue; }
+    if (work.elementByGuid.has(eaGuid)) { continue; }
+    if (elementCanonicalContext(base, rec)) { summary.removedUnanchored++; }
+  }
+
+  // --- relationships --------------------------------------------------------
+  const baseRelIds = new Set(base.relBySchema.keys());
+  const workRelIds = new Set(work.relBySchema.keys());
+  const schemaOfObject = (snap, objectId) => {
+    for (const [, e] of snap.elementBySchema) { if (e.objectId === objectId) { return e.schemaId; } }
+    const w = snap.elementByGuid;
+    for (const [, e] of w) { if (e.objectId === objectId && !e.schemaId) { return { newGuid: e.eaGuid }; } }
+    return null;
+  };
+  for (const schemaId of baseRelIds) {
+    const b = base.relBySchema.get(schemaId);
+    const w = work.relBySchema.get(schemaId);
+    if (!w) {
+      push({ op: 'removeRelationship', kind: 'relationship', id: schemaId, sourceEa: { guid: b.eaGuid } });
+      continue;
+    }
+    const fields = {};
+    if (normText(b.name) !== normText(w.name)) { fields.name = w.name; }
+    if (normText(b.description) !== normText(w.description)) { fields.description = w.description; }
+    const s = schemaOfObject(work, w.sourceObjectId);
+    const t = schemaOfObject(work, w.targetObjectId);
+    const bS = schemaOfObject(base, b.sourceObjectId);
+    const bT = schemaOfObject(base, b.targetObjectId);
+    const src = s && typeof s === 'object' ? null : s;
+    const tgt = t && typeof t === 'object' ? null : t;
+    const bSrc = bS && typeof bS === 'object' ? null : bS;
+    const bTgt = bT && typeof bT === 'object' ? null : bT;
+    if (src !== bSrc) { fields.sourceId = src; }
+    if (tgt !== bTgt) { fields.targetId = tgt; }
+    if (Object.keys(fields).length > 0) {
+      push({ op: 'updateRelationship', kind: 'relationship', id: schemaId, fields, sourceEa: { guid: w.eaGuid } });
+    }
+  }
+  for (const schemaId of workRelIds) {
+    if (baseRelIds.has(schemaId)) { continue; }
+    summary.orphanAnchored++;
+  }
+  // unanchored NEW connectors in work (human drew fresh links)
+  for (const [eaGuid, rec] of work.relByGuid) {
+    if (rec.schemaId) { continue; }
+    if (base.relByGuid.has(eaGuid)) { continue; }
+    // canonical context: at least one endpoint anchored/placed on a canonical view
+    const src = work.elementByGuid.get(guidOfObject(work, rec.sourceObjectId));
+    const tgt = work.elementByGuid.get(guidOfObject(work, rec.targetObjectId));
+    const srcContext = src ? elementCanonicalContext(work, src) : false;
+    const tgtContext = tgt ? elementCanonicalContext(work, tgt) : false;
+    if (!srcContext && !tgtContext) { summary.outOfScopeNew++; continue; }
+    const viewIds = [];
+    for (const [diagramId, members] of work.placements) {
+      const viewId = work.viewByDiagram.get(diagramId);
+      if (viewId && members.has(rec.sourceObjectId) && members.has(rec.targetObjectId)) { viewIds.push(viewId); }
+    }
+    const srcRef = src ? (src.schemaId || { newGuid: src.eaGuid }) : null;
+    const tgtRef = tgt ? (tgt.schemaId || { newGuid: tgt.eaGuid }) : null;
+    push({
+      op: 'addRelationship', kind: 'relationship', id: null,
+      proposed: {
+        name: rec.name === '' ? undefined : rec.name,
+        sourceRef: srcRef, targetRef: tgtRef,
+        eaType: { connectorType: rec.connectorType, stereotype: rec.stereotype },
+        viewIds: viewIds.length > 0 ? viewIds : undefined,
+      },
+      sourceEa: { guid: eaGuid, connectorId: rec.connectorId },
+    });
+  }
+
+  // --- view membership (anchored objects only, still present in the model) ---
+  const allViewIds = new Set([...base.viewByDiagram.values(), ...work.viewByDiagram.values()]);
+  for (const viewId of allViewIds) {
+    const bDiag = base.diagramsByView.get(viewId);
+    const wDiag = work.diagramsByView.get(viewId);
+    if (!bDiag || !wDiag) { continue; } // view's diagram added/removed wholesale: out of v1 scope
+    const bMembers = base.placements.get(bDiag.diagramId) || new Map();
+    const wMembers = work.placements.get(wDiag.diagramId) || new Map();
+    const addMembers = [];
+    const removeMembers = [];
+    for (const objectId of wMembers.keys()) {
+      if (bMembers.has(objectId)) { continue; }
+      const rec = elemByObjectId(work, objectId);
+      if (!rec || !rec.schemaId) { continue; } // unanchored new placement -> rides addElement
+      addMembers.push(rec.schemaId);
+    }
+    for (const objectId of bMembers.keys()) {
+      if (wMembers.has(objectId)) { continue; }
+      const rec = elemByObjectId(base, objectId);
+      if (!rec || !rec.schemaId) { continue; }
+      // removed from diagram but object must still exist in the model (else removeElement)
+      if (!work.elementBySchema.has(rec.schemaId)) { continue; }
+      removeMembers.push(rec.schemaId);
+    }
+    if (addMembers.length > 0 || removeMembers.length > 0) {
+      push({
+        op: 'updateView', kind: 'view', viewId,
+        addMembers: addMembers.length > 0 ? addMembers : undefined,
+        removeMembers: removeMembers.length > 0 ? removeMembers : undefined,
+        sourceEa: {},
+      });
+    }
+  }
+
+  // orphan/other counts merge
+  summary.metaUnchanged = metaUnchanged;
+  return { proposals, summary };
+}
+
+function guidOfObject(snap, objectId) {
+  for (const [, e] of snap.elementByGuid) { if (e.objectId === objectId) { return e.eaGuid; } }
+  return '';
+}
+function elemByObjectId(snap, objectId) {
+  for (const [, e] of snap.elementByGuid) { if (e.objectId === objectId) { return e; } }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Output rendering (JSON + Markdown)
+// ---------------------------------------------------------------------------
+function buildJsonResult(args) {
+  return {
+    format: 'archgraph-ea-human-diff',
+    version: 1,
+    source: { base: args.base, work: args.work },
+    baselineCommit: args.baselineCommit || null,
+    extractedAt: new Date().toISOString(),
+    summary: args.summary,
+    proposals: args.proposals,
+  };
+}
+
+function renderMarkdown(result) {
+  const s = result.summary;
+  const lines = [];
+  lines.push('# EA 人类草稿语义 diff（ea-human-diff）');
+  lines.push('');
+  lines.push(`- 基线（committed .qea）：\`${result.source.base}\``);
+  lines.push(`- 工作区（human-edited .qea）：\`${result.source.work}\``);
+  if (result.baselineCommit) { lines.push(`- 基线 commit：\`${result.baselineCommit}\``); }
+  lines.push(`- 提取时间：${result.extractedAt}`);
+  lines.push('');
+  lines.push('## 摘要');
+  lines.push('');
+  lines.push('| 操作 | 数量 |');
+  lines.push('| --- | --- |');
+  const opOrder = ['addElement', 'updateElement', 'removeElement', 'addRelationship', 'updateRelationship', 'removeRelationship', 'updateView'];
+  for (const op of opOrder) {
+    const label = { addElement: '新增元素', updateElement: '更新元素', removeElement: '删除元素', addRelationship: '新增关系', updateRelationship: '更新关系', removeRelationship: '删除关系', updateView: '视图成员' }[op];
+    lines.push(`| ${label}（${op}） | ${s[op] || 0} |`);
+  }
+  lines.push(`| 纯几何移动（不产出，语义优先排除） | ${s.layoutOnly || 0} |`);
+  lines.push(`| 超出 canonical 作用域的新对象（跳过） | ${s.outOfScopeNew || 0} |`);
+  lines.push(`| 删除的无锚对象（从未入 canonical，跳过） | ${s.removedUnanchored || 0} |`);
+  lines.push(`| 镜像（kg_sync_meta）未变 | ${s.metaUnchanged ? '是' : '否'} |`);
+  lines.push('');
+  if (result.proposals.length === 0) {
+    lines.push('> 未检测到 canonical 语义提议（纯几何/超出作用域改动不计）。');
+    lines.push('');
+  }
+  const groups = {
+    addElement: '新增元素提议', updateElement: '更新元素提议', removeElement: '删除元素提议',
+    addRelationship: '新增关系提议', updateRelationship: '更新关系提议', removeRelationship: '删除关系提议',
+    updateView: '视图成员提议',
+  };
+  for (const op of opOrder) {
+    const items = result.proposals.filter((p) => p.op === op);
+    if (items.length === 0) { continue; }
+    lines.push(`## ${groups[op]}（${items.length}）`);
+    lines.push('');
+    for (const p of items) {
+      if (op === 'addElement') {
+        lines.push(`- **${p.proposed.name}** — id 待 agent 分配；EA 类型 \`${p.proposed.eaType.objectType}\`/\`${p.proposed.eaType.stereotype}\`${p.proposed.viewIds ? `；视图候选 ${p.proposed.viewIds.join(', ')}` : ''}${p.proposed.description ? `；描述：${p.proposed.description.slice(0, 120)}` : ''}；EA \`${p.sourceEa.guid}\``);
+      } else if (op === 'updateElement') {
+        lines.push(`- \`${p.id}\` — ${Object.entries(p.fields).map(([k, v]) => `${k} → ${String(v).slice(0, 80)}`).join('；')}；EA \`${p.sourceEa.guid}\``);
+      } else if (op === 'removeElement' || op === 'removeRelationship') {
+        lines.push(`- \`${p.id}\` — 待 agent 确认后删除；EA \`${p.sourceEa.guid}\``);
+      } else if (op === 'addRelationship') {
+        const src = typeof p.proposed.sourceRef === 'object' ? `新元素 ${p.proposed.sourceRef.newGuid}` : p.proposed.sourceRef;
+        const tgt = typeof p.proposed.targetRef === 'object' ? `新元素 ${p.proposed.targetRef.newGuid}` : p.proposed.targetRef;
+        lines.push(`- ${p.proposed.name ? `**${p.proposed.name}** ` : ''}${src} → ${tgt}；EA 类型 \`${p.proposed.eaType.connectorType}\`/\`${p.proposed.eaType.stereotype}\`；EA \`${p.sourceEa.guid}\``);
+      } else if (op === 'updateRelationship') {
+        lines.push(`- \`${p.id}\` — ${Object.entries(p.fields).map(([k, v]) => `${k} → ${String(v).slice(0, 80)}`).join('；')}；EA \`${p.sourceEa.guid}\``);
+      } else if (op === 'updateView') {
+        const a = p.addMembers ? `加入：${p.addMembers.join(', ')}` : '';
+        const r = p.removeMembers ? `移除：${p.removeMembers.join(', ')}` : '';
+        lines.push(`- 视图 \`${p.viewId}\` — ${[a, r].filter(Boolean).join('；')}`);
+      }
+    }
+    lines.push('');
+  }
+  lines.push('> 本 diff 基于 EA 可见对象模型（schema_id 锚 tag 对齐），不读 kg_sync_meta；几何不进 canonical。交由 agent 经 ARGO preview/apply 写入图谱。');
+  lines.push('');
+  return lines.join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// CLI
+// ---------------------------------------------------------------------------
+function parseArgs(argv) {
+  const args = { base: '', work: '', graph: '', out: '', baselineCommit: '', md: true };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const next = () => (i + 1 < argv.length ? argv[++i] : '');
+    if (a === '--base') { args.base = next(); }
+    else if (a === '--work') { args.work = next(); }
+    else if (a === '--graph') { args.graph = next(); }
+    else if (a === '--out') { args.out = next(); }
+    else if (a === '--baseline-commit') { args.baselineCommit = next(); }
+    else if (a === '--no-md') { args.md = false; }
+  }
+  return args;
+}
+
+// Auto-baseline: extract the committed (HEAD) version of the working .qea as the baseline.
+// Lets the day-to-day flow be a single command when --work is a tracked repo file.
+function gitShowHeadBlob(relPath) {
+  const { execFileSync } = require('node:child_process');
+  return execFileSync('git', ['cat-file', 'blob', 'HEAD:' + relPath], { maxBuffer: 512 * 1024 * 1024 });
+}
+function resolveAutoBase(workPath) {
+  const { execFileSync } = require('node:child_process');
+  const workAbs = path.resolve(process.cwd(), workPath);
+  let root;
+  try {
+    root = execFileSync('git', ['rev-parse', '--show-toplevel'], { encoding: 'utf8' }).trim();
+  } catch {
+    throw new Error('--base omitted but git toplevel unavailable; pass --base <baseline.qea> explicitly');
+  }
+  const rel = path.relative(root, workAbs).split(path.sep).join('/');
+  if (rel.startsWith('..')) {
+    throw new Error('--work (' + workAbs + ') is outside the git repo; pass --base <baseline.qea> explicitly');
+  }
+  let blob;
+  try {
+    blob = gitShowHeadBlob(rel);
+  } catch {
+    throw new Error('git HEAD has no tracked file "' + rel + '"; pass --base <baseline.qea> explicitly');
+  }
+  const tmp = path.join(require('node:os').tmpdir(), 'ea-human-diff-base-' + process.pid + '.qea');
+  fs.writeFileSync(tmp, blob);
+  let short = '';
+  try { short = execFileSync('git', ['rev-parse', '--short', 'HEAD'], { encoding: 'utf8' }).trim(); } catch { /* ignore */ }
+  return { base: tmp, baselineCommit: short };
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (!args.base && !args.work) {
+    console.error('usage: node argo/scripts/ea-human-diff.js --base <base.qea> --work <work.qea> [--graph <json>] [--out <stem>] [--baseline-commit <sha>] [--no-md]');
+    console.error('       (--base optional: when omitted the committed HEAD version of --work is used as baseline)');
+    process.exit(2);
+  }
+  if (args.base === '' && args.work) {
+    try {
+      const auto = resolveAutoBase(args.work);
+      args.base = auto.base;
+      if (!args.baselineCommit) { args.baselineCommit = auto.baselineCommit; }
+    } catch (err) {
+      console.error('ea-human-diff: ' + err.message);
+      process.exit(2);
+    }
+  }
+  for (const f of [args.base, args.work]) {
+    if (!fs.existsSync(f)) { console.error('file not found: ' + f); process.exit(2); }
+  }
+  const knownViewIds = null;
+  if (args.graph && fs.existsSync(args.graph)) {
+    try {
+      const g = JSON.parse(fs.readFileSync(args.graph, 'utf8').replace(/^\uFEFF/, ''));
+      args._knownViewIds = (g.views || []).map((v) => String(v.view_id));
+    } catch { /* optional catalog */ }
+  }
+  const base = readSnapshot(args.base, { knownViewIds: args._knownViewIds });
+  const work = readSnapshot(args.work, { knownViewIds: args._knownViewIds });
+  const { proposals, summary } = semanticDiff(base, work, {});
+  const result = buildJsonResult({ base: args.base, work: args.work, baselineCommit: args.baselineCommit, summary, proposals });
+  if (args.out) {
+    const stem = path.resolve(process.cwd(), args.out);
+    fs.writeFileSync(stem + '.json', JSON.stringify(result, null, 2), 'utf8');
+    if (args.md) {
+      fs.writeFileSync(stem + '.md', renderMarkdown(result), 'utf8');
+    }
+    console.log('ea-human-diff written: ' + stem + '.json' + (args.md ? ' + ' + stem + '.md' : ''));
+    console.log(JSON.stringify({ summary }, null, 2));
+  } else {
+    console.log(JSON.stringify(result, null, 2));
+  }
+}
+
+if (require.main === module) { main(); }
+
+module.exports = {
+  parseStyleToken,
+  readSnapshot,
+  semanticDiff,
+  buildJsonResult,
+  renderMarkdown,
+};

package/argo/skills/ea-human-draft/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: ea-human-draft
+description: "把人类在 EA 里对 .qea 的草稿改动收敛进正式图谱（WP2792 draft-proposal 流程）：① 断言前提（EA 已关闭 / .qea 可还原 / 工具存在）→ ② 用 ea-human-diff 提取语义 diff 提议（JSON+Markdown，读 EA 可见对象模型、不读 kg_sync_meta、纯几何不产出）→ ③ git restore 还原 .qea 到上次提交 → ④ 把提议交给 agent/人类伙伴，按其指引经 ARGO preview/apply 写回 canonical JSON（自动增量投影回 .qea 并 commit）。Use when 人类专家用 Sparx EA 直接改了 archgraph.qea 需要并入正式图谱、提取人类 EA 改动的语义 diff、把 .qea 还原回已提交状态、或按 draft-proposal 收敛人类草稿。Keywords: EA 人类草稿, human draft, semantic diff, ea-human-diff, draft-proposal, reverse-ea2kg, 人类参与建图."
+argument-hint: 人类 EA 草稿收敛
+---
+
+# EA HUMAN DRAFT（人类 EA 草稿 → 语义 diff → 写回图谱）
+
+定位：**EA 只当草稿纸**，`design/KG/SystemArchitecture.json` 是唯一真源。人类在 agent 空闲间隙用 EA 改 `archgraph.qea`；本技能负责把人类改动**安全地提取为提议**（断言 + diff + 还原），并把提议交给 agent/人类伙伴，按其指引经 ARGO 写回 canonical——不建立有损的全自动 EA→JSON 反向投影。
+
+依赖工具：`argo/scripts/ea-human-diff.js`（仓库内）或部署版 `~/.argo/scripts/ea-human-diff.js`（随 `archgraph-argo` npm 包发布）。`--base` 可省略：自动取 git HEAD 里 `--work` 的版本作基线。
+
+## 前置（Assert —— 全部满足才继续，任一失败即停下报告）
+
+- [ ] 工作区含 `design/KG/SystemArchitecture.json` 且 `archgraph.qea` 被 git 跟踪（`git ls-files archgraph.qea` 有输出）。
+- [ ] diff 工具存在：仓库 `argo/scripts/ea-human-diff.js` 或部署 `~/.argo/scripts/ea-human-diff.js`。
+- [ ] **EA 已完全关闭**（人类改动已保存落盘）——否则读到的不是最终状态，且 `git restore` 可能被文件锁破坏/EA 关盘重写。
+- [ ] git 可用；`HEAD` 中存在 `archgraph.qea`（自动基线依赖）。若人类还没开改（`git status --short archgraph.qea` 为空）→ 说明：需先在 EA 里改、保存、关闭后再回来。
+
+Windows 可选核实无进程持有：
+```powershell
+Get-Process EA -ErrorAction SilentlyContinue   # 有输出则先关闭 EA
+```
+
+## Workflow
+
+### 1 · Assert（断言）
+逐条检查上方前置并报告结果。任一失败 → 停下，不做 diff、不做 revert。
+
+### 2 · 提取语义 diff
+仓库根执行（自动基线 = git HEAD 里的 `archgraph.qea`）：
+```powershell
+node argo/scripts/ea-human-diff.js --work archgraph.qea --out results/human-draft
+```
+产物：
+- `results/human-draft.json` —— 机器提议集（`proposals[]`：`op`/`kind`/`id`/`fields`/`proposed`/`sourceEa` 等 + `summary`）。
+- `results/human-draft.md` —— 人读摘要（分类表格 + 逐条明细 + EA guid 溯源）。
+
+先给人伙伴看 `human-draft.md`：确认是预期改动、无意外删除；留意 `layoutOnly` / `outOfScopeNew` / `removedUnanchored` 计数（这些不产出提议）。
+若 `--work` 不是 git 跟踪文件（如临时副本），须显式 `--base <committed.qea>`，不能用自动基线。
+
+### 3 · 还原 .qea 到上次提交
+```powershell
+git restore archgraph.qea
+git status --short     # 应只剩 results/human-draft.* 等产物，archgraph.qea 不再 dirty
+```
+目的：把 `.qea` 拉回与 HEAD 一致，杜绝残留分叉；人类草稿只以提议文件形式存在，避免后续 agent 写图触发投影时静默覆盖/合并混乱。
+
+### 4 · 交给下一步（按人类指引写回正式图谱）
+提议**不会自动写回**。把 `human-draft.json`/`.md` 呈现给人类伙伴，按其指引执行（或交给负责写图的 agent）：
+1. 审阅每条提议（add/update/remove / 视图成员 / 删除需确认），必要时删改。
+2. 经 ARGO MCP `previewSystemArchitectureMutation` → `applySystemArchitectureMutation` 写入 canonical JSON。
+3. apply 后 MCP 自动增量投影回 `.qea`——**不要手工编辑 .qea 覆盖**。
+4. 对受影响元素跑回归验收（WP2792 AT 集等）后 `git commit`，并把 commit id 登记到对应图谱元素的 `commit` 属性（见全局 ArchGraph 红线）。
+
+## Rules
+
+- **MUST** 只在 EA 关闭后运行；diff 前先做断言并报告。
+- **MUST** diff 以 EA **可见对象模型**（`schema_id` 锚 tag 对齐）为准；**绝不**用 `kg_sync_meta` 判定人类改动（人类改动不进镜像）。
+- **MUST** 提取 diff 后先 `git restore archgraph.qea` 再进入写回阶段，避免 qea 侧残留被后续投影覆盖/丢失。
+- **MUST** 把每条**删除**提议（removeElement/removeRelationship）标记为需人类/负责 agent 确认后再 apply。
+- **MUST NOT** 把 `human-draft.json` 当 canonical 直接写——必须先 ARGO `preview` 校验，再 `apply`。
+- **MUST NOT** 在 `.qea` 上手工写 canonical 内容（唯一写回通道是 canonical JSON → 自动增量投影）。
+- **MUST NOT** 读取/复述 `.env` 中的 secret。
+- 纯几何（`t_diagramobjects` 坐标）**不进提议**（语义优先）；若人类排版也是交付物，需另行走布局侧车（本技能不产出）。
+
+## 产物
+
+| 文件 | 内容 |
+| --- | --- |
+| `results/human-draft.json` | 机器提议集：source / baselineCommit / extractedAt / summary / proposals[]（每条含 op / kind / id / fields / proposed / sourceEa） |
+| `results/human-draft.md` | 人读摘要：操作计数表 + 逐条明细（EA guid 溯源）+ 排除说明（layoutOnly 等） |
+
+## 故障排查
+
+- `git HEAD has no tracked file "..."`：`--work` 未被 git 跟踪 → 显式 `--base <committed.qea>`。
+- `git restore` 失败/文件锁：EA 还开着 → 关闭 EA 后重试。
+- diff 为空但人类确实改过：多半只做了纯几何或超出 canonical 作用域改动 → 看 `.md` 的 `layoutOnly` / `outOfScopeNew` 计数。
+- 关系侧提议异常（id 为 undefined）：确认基线 .qea 由投影生成（`t_connectortag` 带 `schema_id`），手绘模型无锚时关系不参与。

package/install-argo.ps1

@@ -37,12 +37,6 @@ $argoDir = Join-Path $repoRoot 'argo'
 # verbatim across Copilot / Cursor / OpenCode (and DSH presets), so the original
 # model binding must stay untouched there. OpenCode has no Qwen provider
 # configured, so 'alibaba-cn/qwen3.7-plus' cannot resolve; only the OpenCode
-# deployment artifact remaps that binding to a model id OpenCode knows
-# (deepseek/deepseek-v4-flash-vision-exp). All other targets keep the shared
-# source binding unchanged.
-$OpenCodeModelRemap = @{
-    'alibaba-cn/qwen3.7-plus' = 'deepseek/deepseek-v4-flash-vision-exp'
-}
 
 function Copy-Tree {
     param([string]$Source, [string]$Destination)
@@ -102,9 +96,7 @@ function Convert-AgentFile {
         $newFront = "---`r`n"
         if ($desc) { $newFront += "description: `"$($desc -replace '"','\"')`"`r`n" }
         if ($model) {
-            $deployModel = $model
-            if ($OpenCodeModelRemap.ContainsKey($deployModel)) { $deployModel = $OpenCodeModelRemap[$deployModel] }
-            $newFront += "model: `"$deployModel`"`r`n"
+            $newFront += "model: `"$model`"`r`n"
         }
         $newFront += "mode: all`r`n---`r`n"
     } else {
@@ -770,6 +762,10 @@ $skillDest = Join-Path $SkillsRoot 'argo-init'
 Write-Host "[4/22] argo\skills\argo-init -> $skillDest"
 Copy-Tree -Source $skillSrc -Destination $skillDest
 
+$draftSkillSrc = Join-Path $argoDir 'skills\ea-human-draft'
+Write-Host '  argo\skills\ea-human-draft -> $SkillsRoot\ea-human-draft (ea-human-draft skill)'
+Copy-Tree -Source $draftSkillSrc -Destination (Join-Path $SkillsRoot 'ea-human-draft')
+
 $ruleSrc = Join-Path (Join-Path $argoDir 'rules') 'archgraph.instructions.md'
 $ruleDest = Join-Path $PromptsRoot 'archgraph.instructions.md'
 Write-Host "[5/22] argo\rules\archgraph.instructions.md -> $ruleDest"
@@ -784,6 +780,8 @@ Copy-Item -Force -Path $depsSrc -Destination $depsDest
 $cursorSkillDest = Join-Path $CursorSkillsRoot 'argo-init'
 Write-Host "[7/22] argo\skills\argo-init -> $cursorSkillDest (Cursor)"
 Copy-Tree -Source $skillSrc -Destination $cursorSkillDest
+Write-Host '  argo\skills\ea-human-draft -> $CursorSkillsRoot\ea-human-draft (Cursor)'
+Copy-Tree -Source $draftSkillSrc -Destination (Join-Path $CursorSkillsRoot 'ea-human-draft')
 
 $mcpBridgeSrc = Join-Path $argoDir 'mcp-bridges'
 $mcpBridgeDest = Join-Path $CursorMcpBridgesRoot ''
@@ -793,6 +791,8 @@ Copy-Tree -Source $mcpBridgeSrc -Destination $mcpBridgeDest
 $openCodeSkillDest = Join-Path $OpenCodeSkillsRoot 'argo-init'
 Write-Host "[8/22] argo\skills\argo-init -> $openCodeSkillDest (OpenCode)"
 Copy-Tree -Source $skillSrc -Destination $openCodeSkillDest
+Write-Host '  argo\skills\ea-human-draft -> $OpenCodeSkillsRoot\ea-human-draft (OpenCode)'
+Copy-Tree -Source $draftSkillSrc -Destination (Join-Path $OpenCodeSkillsRoot 'ea-human-draft')
 
 Write-Host "[9/22] argo\rules\archgraph.instructions.md -> $OpenCodeAgentsPath (OpenCode global AGENTS.md)"
 Add-AgentsRule -AgentsPath $OpenCodeAgentsPath -RulePath $ruleSrc
@@ -831,6 +831,9 @@ if ($SkipDsh) {
     Write-Host "[16/22] argo\skills\argo-init -> $dshSkillDest (DeepSeek Harness skill)"
     Copy-Tree -Source (Join-Path $argoDir 'skills\argo-init') -Destination $dshSkillDest
 
+    Write-Host '  argo\skills\ea-human-draft -> $DshHome\skills\ea-human-draft (DeepSeek Harness skill)'
+    Copy-Tree -Source (Join-Path $argoDir 'skills\ea-human-draft') -Destination (Join-Path (Join-Path $DshHome 'skills') 'ea-human-draft')
+
     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
 
@@ -892,6 +895,9 @@ 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-draft -> $OpenClawHome\skills\ea-human-draft (OpenClaw managed skill, all agents)'
+    Copy-Tree -Source (Join-Path $argoDir 'skills\ea-human-draft') -Destination (Join-Path (Join-Path $OpenClawHome 'skills') 'ea-human-draft')
+
     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'
     Write-Host '  the OpenClaw gateway (openclaw gateway restart) if it is already running.'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "archgraph-argo",
-  "version": "0.13.5",
+  "version": "0.13.7",
   "description": "Deploy the ArchGraph ARGO toolchain, skills, and rules (schema, scripts, argo-init skill, global rule) with one command.",
   "license": "MIT",
   "bin": {
@@ -14,6 +14,7 @@
     "argo/plugins",
     "argo/mcp-bridges",
     "argo/skills/argo-init",
+    "argo/skills/ea-human-draft",
     "argo/rules",
     "argo/package.json",
     "vendor",

package/argo/agents/wechat-publisher.agent.md

@@ -1,43 +0,0 @@
----
-description: "公众号发布：将 ArchGraph 项目的文章（洞察报告、官宣介绍、开发者社区等）撰写为符合微信公众号格式的 Markdown，并通过 wechat-public-cli 创建草稿、跟进公众号后台手动发布流程。Use when: 发布公众号文章、创建公众号草稿、微信公众平台、wechat、公众号发布员、撰写 .wechat.md 文章。"
-name: "公众号发布员"
-model: "alibaba-cn/qwen3.7-plus"
-tools: [read, edit, search, execute]
-user-invocable: true
-argument-hint: "要发布的文章主题或源文档路径"
----
-你是 ArchGraph 项目的「公众号发布员」，专职把项目文章发布到微信公众号。
-
-## 职责
-1. 阅读源内容（洞察报告、官宣介绍、开发者社区等文档），提炼并撰写为符合微信公众号格式的 Markdown 文章。
-2. 通过本地 wechat-public-cli 创建公众号草稿。
-3. 返回草稿 media_id，并说明公众号后台手动发布的跟进步骤。
-
-## 约束
-- 只用 `wechat:draft` 创建草稿。**禁止**运行 `wechat:publish` / `wechat:sendall` / `freepublish`：本公众号是个人未认证订阅号（appid wxdf79e7cb44995aa3），这些 API 永远返回 48001 api unauthorized，只能登录公众号后台「草稿箱」手动发布。
-- 文章内容必须基于仓库内已有文档，不得凭空编造。
-- 不得打印或泄露 `wechat-public.config.json` 中的 appid/secret 等凭据。
-- 发布前需确认当前公网 IP 已加入公众号后台 IP 白名单（否则 token 刷新报 40164）。
-
-## 工作方法
-1. 定位源文档，并参考 `docs/*.wechat.md` 既有文章的格式与文风。
-2. 撰写 `docs/<主题>.wechat.md`，YAML frontmatter 至少含 `title` / `author` / `digest`，并按需含 `banner_path`（相对文章目录）、`open_comment`、`source_url`。
-3. 若 `tests/wechat-article.test.js` 尚无对应验收用例，先补一条 GIVEN-WHEN-THEN 用例，再运行 `node --test tests/wechat-article.test.js` 通过。
-4. 创建草稿（banner_path 相对文章文件目录解析）：
-   ```powershell
-   node "d:\Projects\_tools\wechat-cli-src\obsidian-wechat-public-platform-master\dist\wechat-public-cli.js" wechat:draft --file "<文章绝对路径>" --config "d:\Projects\archgraph\wechat-public.config.json" --css "d:\Projects\_tools\wechat-cli-src\obsidian-wechat-public-platform-master\custom.css"
-   ```
-
-## 文风要求（人味优先，去 AI 味）
-
-发布公众号文章前，必须按以下要求降低「AI 味」、增加「人味」，否则读者不会看：
-
-- 禁止 AI 套话与八股：删掉「首先/其次/最后」「综上所述」「总而言之」「值得注意的是」「赋能」「抓手」「闭环」「底层逻辑」等空洞词，去掉「本文将从以下 N 个方面展开」式开场。
-- 去掉机械排比与对仗堆砌；段落要短，句子长短交错，像人说话，不像机器列清单。
-- 多点人味：加入真实场景、具体例子、第一人称视角、设问、适度的口语与幽默；用具体数字和细节代替抽象概括。
-- 开门见山直给观点与结论，少绕弯子；结尾给出可行动的判断，而非泛泛展望。
-- 标题与摘要（digest）同样要有人味，避免口号式、震惊体式标题。
-- 每篇至少通读一遍，找出并改写任何读起来像机器生成的句子。
-
-## 输出格式
-返回：文章路径、草稿 media_id（或确切失败原因）、状态（草稿已创建 / BLOCKED）。并提醒：API 发布不可用，需在公众号后台「草稿箱」手动发布。