archgraph-argo 0.10.8 → 0.10.10

package/README.md

@@ -19,6 +19,20 @@ engineering:
 
 Editable source: [`docs/diagrams/global-architecture.excalidraw`](docs/diagrams/global-architecture.excalidraw)
 
+## Supported Harnesses
+
+ArchGraph deploys the ARGO toolchain to all major coding-agent environments:
+
+| Harness            | MCP Server | Skills | Rules / Instructions | Agents | Wakeup Gate |
+|--------------------|:----------:|:------:|:--------------------:|:------:|:-----------:|
+| GitHub Copilot     |     ✓      |   ✓    |          ✓           |   ✓    |      —      |
+| Cursor             |     ✓      |   ✓    |          ✓           |   ✓    |      —      |
+| OpenCode           |     ✓      |   ✓    |          ✓           |   ✓    |     ✓       |
+| DeepSeek Harness   |     ✓      |   ✓    |          ✓           |   ✓    |     ✓       |
+
+A single `argo-deploy` registers the `argo` MCP server and installs all artifacts into each harness
+automatically.
+
 ## Install
 
 ```powershell

package/argo/scripts/neo4j-system-architecture-store.js

@@ -1,3 +1,4 @@
+const crypto = require('node:crypto');
 const fs = require('node:fs');
 const path = require('node:path');
 
@@ -145,6 +146,23 @@ function readArchitectureDocument(architecturePath = DEFAULT_GRAPH_PATH) {
   }
 }
 
+function digestCanonicalArchitecture(architecturePath = DEFAULT_GRAPH_PATH) {
+  const absolutePath = resolveArchitecturePath(architecturePath);
+  try {
+    return crypto.createHash('sha256').update(fs.readFileSync(absolutePath)).digest('hex');
+  } catch {
+    return null;
+  }
+}
+
+function isNeo4jGraphSyncStale(syncState, currentDigest) {
+  if (!syncState || typeof syncState !== 'object') return false;
+  if (!currentDigest || typeof currentDigest !== 'string') return false;
+  const hasDigest = typeof syncState.canonicalDigest === 'string' && syncState.canonicalDigest.length > 0;
+  if (hasDigest) return syncState.canonicalDigest !== currentDigest;
+  return typeof syncState.lastSuccessAt === 'string' && syncState.lastSuccessAt.length > 0;
+}
+
 function sanitizeProps(properties) {
   return Object.fromEntries(
     Object.entries(properties).filter(([, value]) => value !== undefined),
@@ -226,12 +244,14 @@ function markNeo4jSyncDirty(architecturePath, error) {
 
 function markNeo4jSyncClean(architecturePath, verification) {
   const current = getNeo4jGraphSyncState(architecturePath);
+  const canonicalDigest = digestCanonicalArchitecture(architecturePath);
   return updateNeo4jGraphSyncState(architecturePath, {
     dirty: false,
     lastError: undefined,
     lastRecoveredAt: current.dirty ? new Date().toISOString() : current.lastRecoveredAt,
     lastSuccessAt: new Date().toISOString(),
     lastVerifiedCounts: verification ? verification.actual : current.lastVerifiedCounts,
+    canonicalDigest,
   });
 }
 
@@ -599,11 +619,13 @@ async function recoverNeo4jSyncIfNeeded(options = {}) {
   }
 
   const syncState = getNeo4jGraphSyncState(architecturePath);
-  if (!syncState.dirty) {
+  const stale = isNeo4jGraphSyncStale(syncState, digestCanonicalArchitecture(architecturePath));
+  if (!syncState.dirty && !stale) {
     return {
       attempted: false,
       eligible: true,
       dirty: false,
+      stale: false,
     };
   }
 
@@ -613,6 +635,7 @@ async function recoverNeo4jSyncIfNeeded(options = {}) {
       attempted: true,
       eligible: true,
       dirty: false,
+      stale: false,
       status: 'passed',
       graphKey: result.graphKey,
       databaseProvision: result.databaseProvision,
@@ -624,6 +647,7 @@ async function recoverNeo4jSyncIfNeeded(options = {}) {
       attempted: true,
       eligible: true,
       dirty: true,
+      stale: false,
       status: 'failed',
       graphKey: syncState.graphKey,
       previousFailure: syncState.lastError,
@@ -761,11 +785,13 @@ module.exports = {
   DEFAULT_GRAPH_PATH,
   buildGraphKey,
   createDriver,
+  digestCanonicalArchitecture,
   ensureDatabaseExists,
   getNeo4jGraphSyncState,
   getNeo4jConfig,
   getDefaultNeo4jDatabaseName,
   isCanonicalArchitecturePath,
+  isNeo4jGraphSyncStale,
   markNeo4jSyncDirty,
   readArchitectureDocument,
   readNeo4jSyncState,

package/cordis.patch.yml

@@ -0,0 +1,6 @@
+# ArchGraph ARGO bundle patch：随 bundle 安装，按包名引用包内插件（非 file://）。
+- insert:
+    - id: argo-workspace
+      name: archgraph-argo/dsh-argo-workspace
+    - id: argo-wakeup
+      name: archgraph-argo/dsh-argo-wakeup

package/dsh-argo-wakeup/index.js

@@ -0,0 +1,17 @@
+// dsh-argo-wakeup - generated by install-argo.ps1 from
+// argo/rules/archgraph.instructions.md (single source of truth: the rule file;
+// this file is a deployment artifact, do not edit by hand).
+// DeepSeek Harness equivalent of the OpenCode hook argo/plugins/argo-wakeup.js:
+// registers the unconditional wakeup gate as the first system-prompt section
+// after the harness identity, so every session identifies its Business Actor
+// through the argo MCP server before responding.
+export const name = 'dsh-argo-wakeup'
+export const inject = ['systemPrompt']
+const WAKEUP_GATE = "STEP 0 — UNCONDITIONAL STARTUP GATE. This applies to the very first message of every session, including greetings, casual chat, and questions; it may never be skipped, deferred, or treated as optional.\r\n1. Your very FIRST tool call in the session MUST be an ARGO MCP query that lists all `Business Actor`s (getSystemArchitecture with purpose \"audit\" and subject \"Business Actor\"). Identify which `Business Actor` you are. If you are not sure, consult your human partner to confirm your role before doing anything else.\r\n2. Restore your long-term memory: the SUBVIEW hierarchy mounted under that `Business Actor` element — the Views whose `parent_element_id` points to this Actor, plus the elements, relationships, and further nested sub-views inside them (NOT the View that merely includes the Actor in its `included_elements`) — and load it into session memory.\r\n3. If the `agent` attribute of the confirmed Actor differs from your current Agent type, switch to that Agent type, or delegate to an Agent of that type per `\u003cCoperationGuideline\u003e` item 2.\r\n4. If the ARGO MCP is unavailable or errors, state that explicitly to the user before doing anything else. Only after completing this gate may you respond to the user or take any other action."
+export function apply(ctx) {
+  ctx.effect(() => ctx.systemPrompt.section({
+    name: 'argo:wakeup',
+    order: -90,
+    text: WAKEUP_GATE,
+  }), 'argo:wakeup.section()')
+}

package/dsh-argo-wakeup/package.json

@@ -0,0 +1 @@
+{"type":"module"}

package/dsh-argo-workspace/index.js

@@ -0,0 +1,141 @@
+// dsh-argo-workspace - generated by install-argo.ps1 (single source of truth:
+// the installer; this file is a deployment artifact, do not edit by hand).
+//
+// Direct MCP bridge to the argo server for DeepSeek Harness. Registers every
+// argo tool as mcp__argo__* and injects the current session's workspace
+// directory (SessionHeader.cwd) as the per-call `workspaceRoot` argument, so
+// one dsh instance follows whichever workspace the user switched to - the
+// model sees no extra parameters and no internal tool names. The argo server
+// honors the injected workspaceRoot unconditionally.
+//
+// Zero dependencies on purpose: implements the minimal MCP stdio client
+// (JSON-RPC 2.0, one JSON object per line) with Node built-ins only, so the
+// plugin runs from any DSH layout without resolving @modelcontextprotocol/sdk.
+import { spawn } from 'node:child_process'
+import readline from 'node:readline'
+import { fileURLToPath } from 'node:url'
+
+export const name = 'dsh-argo-workspace'
+export const inject = ['tools']
+
+// 包内默认：<pkg>/argo/scripts/argo-mcp-server.js —— 随包走，跨机器可移植。
+const DEFAULT_SERVER_PATH = fileURLToPath(
+  new URL('../argo/scripts/argo-mcp-server.js', import.meta.url),
+)
+
+/** Minimal MCP stdio client over the argo server process. */
+function createArgoClient(serverPath, env, cwd) {
+  const child = spawn('node', [serverPath], {
+    stdio: ['pipe', 'pipe', 'pipe'],
+    env,
+    ...(cwd ? { cwd } : {}),
+  })
+  const pending = new Map()
+  let nextId = 1
+  readline.createInterface({ input: child.stdout }).on('line', (line) => {
+    let message
+    try { message = JSON.parse(line) } catch { return }
+    if (message && typeof message.id === 'number' && pending.has(message.id)) {
+      const { resolve, reject } = pending.get(message.id)
+      pending.delete(message.id)
+      if (message.error) reject(new Error(JSON.stringify(message.error)))
+      else resolve(message.result)
+    }
+  })
+  child.stderr.on('data', () => {}) // drain; the argo server logs to stderr
+  const request = (method, params) => new Promise((resolve, reject) => {
+    const id = nextId++
+    pending.set(id, { resolve, reject })
+    child.stdin.write(JSON.stringify({ jsonrpc: '2.0', id, method, params }) + '\n')
+  })
+  return {
+    request,
+    notify: (method, params) => {
+      child.stdin.write(JSON.stringify({ jsonrpc: '2.0', method, params }) + '\n')
+    },
+    close: () => child.kill(),
+  }
+}
+
+/** Connect, list tools, register them, and keep the client until disposal. */
+export async function apply(ctx, config) {
+  const serverPath = config.serverPath
+    ?? process.env.ARGO_SERVER_PATH
+    ?? DEFAULT_SERVER_PATH
+  const workspaces = Array.isArray(config.workspaces) ? config.workspaces : []
+  const env = { ...process.env }
+  if (workspaces.length > 0) env.ARGO_WORKSPACE_ROOTS = workspaces.join(';')
+  const client = createArgoClient(serverPath, env, config.cwd)
+  ctx.effect(() => () => client.close(), 'dsh-argo-workspace.dispose()')
+
+  let tools = []
+  try {
+    await client.request('initialize', {
+      protocolVersion: '2024-11-05',
+      capabilities: {},
+      clientInfo: { name: 'dsh-argo-workspace', version: '0.1.0' },
+    })
+    client.notify('notifications/initialized', {})
+    const listed = await client.request('tools/list', {})
+    tools = (listed && Array.isArray(listed.tools)) ? listed.tools : []
+  } catch (error) {
+    console.warn(`[dsh-argo-workspace] failed to connect to the argo MCP server (${serverPath}): ${error && error.message ? error.message : error}`)
+    return
+  }
+
+  const disposers = []
+  for (const tool of tools) {
+    const publicName = 'mcp__argo__' + tool.name
+    disposers.push(ctx.tools.register({
+      name: publicName,
+      description: tool.description ?? '',
+      parameters: tool.inputSchema,
+      output: {
+        schema: {
+          type: 'object',
+          properties: {
+            content: { type: 'array', items: {} },
+            structuredContent: {},
+          },
+          required: ['content'],
+          additionalProperties: false,
+        },
+        render: (_args, value) => value.content,
+      },
+      execute: async (args, exec) => {
+        // SessionHeader.cwd (the durable session workspace), NOT
+        // requestHeader() — that returns the request EpochHeader
+        // (config/system/tools) which has no cwd field.
+        const sessionCwd = exec && exec.agent && exec.agent.session
+          ? exec.agent.session.header?.cwd
+          : undefined
+        const injected = { ...(args && typeof args === 'object' ? args : {}) }
+        if (typeof sessionCwd === 'string' && sessionCwd !== '') {
+          injected.workspaceRoot = sessionCwd
+        }
+        if (exec && exec.signal && exec.signal.aborted) {
+          throw new Error('aborted')
+        }
+        const result = await client.request('tools/call', {
+          name: tool.name,
+          arguments: injected,
+        })
+        const text = Array.isArray(result.content)
+          ? result.content
+              .map((block) => block && block.type === 'text' && typeof block.text === 'string'
+                ? block.text
+                : JSON.stringify(block))
+              .join('\n')
+          : (result.toolResult !== undefined ? JSON.stringify(result.toolResult) : '(no output)')
+        if (result.isError === true) throw new Error(text)
+        return {
+          content: [{ type: 'text', text }],
+          ...(result.structuredContent !== undefined ? { structuredContent: result.structuredContent } : {}),
+        }
+      },
+    }))
+  }
+  ctx.effect(() => () => {
+    for (const dispose of disposers) dispose()
+  }, 'dsh-argo-workspace.tools')
+}

package/dsh-argo-workspace/package.json

@@ -0,0 +1 @@
+{"type":"module"}

package/install-argo.ps1

@@ -726,7 +726,7 @@ if ($SkipDsh) {
         Write-DshManagedBlock -Path $patchPath -Block $block -MarkerStart '# BEGIN ArchGraph ARGO deployment' -MarkerEnd '# END ArchGraph ARGO deployment'
     }
 
-    Write-Host "[19/19] 1argo\agents -> $DshHome\.agent-presets\<id> (DeepSeek Harness agent presets)"
+    Write-Host "[19/19] argo\agents -> $DshHome\.agent-presets\<id> (DeepSeek Harness agent presets)"
     New-DshAgentPresets -DshHome $DshHome -AgentsSrc (Join-Path $argoDir 'agents')
 
     Write-Host '  Restart `dsh web` to activate the MCP bridge and the wakeup plugin;'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "archgraph-argo",
-  "version": "0.10.8",
+  "version": "0.10.10",
   "description": "Deploy the ArchGraph ARGO toolchain, skills, and rules (schema, scripts, argo-init skill, global rule) with one command.",
   "license": "MIT",
   "bin": {
@@ -17,11 +17,28 @@
     "argo/package.json",
     "vendor",
     "install-argo.ps1",
-    "bin"
+    "bin",
+    "cordis.patch.yml",
+    "dsh-argo-workspace",
+    "dsh-argo-wakeup"
   ],
-  "devDependencies": {
+  "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"
+  },
   "scripts": {
     "test": "node --test \"tests/*.test.js\""
   },