archgraph-argo 0.10.52 → 0.11.0

package/install-argo.ps1

@@ -26,7 +26,10 @@ param(
     [string]$OpenClawRepoRoot = '',
     [switch]$SkipOpenClaw,
     [string]$McpPath,
-    [string]$GraphMcpUrl = 'https://argo.derekworkspacev5.com/mcp'
+    [string]$GraphMcpUrl = 'https://argo.derekworkspacev5.com/mcp',
+    [switch]$SkipEaWeb,
+    [int]$EaWebPort = 8787,
+    [string]$EaWebRoot = ''
 )
 
 $ErrorActionPreference = 'Stop'
@@ -737,37 +740,37 @@ Write-Host '==> Deploying Argo toolchain'
 
 $schemaSrc = Join-Path $argoDir 'schema'
 $schemaDest = Join-Path $ArgoRoot 'schema'
-Write-Host "[1/22] argo\schema -> $schemaDest"
+Write-Host "[1/23] argo\schema -> $schemaDest"
 Copy-Tree -Source $schemaSrc -Destination $schemaDest
 
 $scriptsSrc = Join-Path $argoDir 'scripts'
 $scriptsDest = Join-Path $ArgoRoot 'scripts'
-Write-Host "[2/22] argo\scripts -> $scriptsDest"
+Write-Host "[2/23] argo\scripts -> $scriptsDest"
 Copy-Tree -Source $scriptsSrc -Destination $scriptsDest
 
 $defaultsSrc = Join-Path $argoDir 'defaults'
 $defaultsDest = Join-Path $ArgoRoot 'defaults'
-Write-Host "[3/22] argo\defaults -> $defaultsDest"
+Write-Host "[3/23] argo\defaults -> $defaultsDest"
 Copy-Tree -Source $defaultsSrc -Destination $defaultsDest
 
 $skillSrc = Join-Path (Join-Path $argoDir 'skills') 'argo-init'
 $skillDest = Join-Path $SkillsRoot 'argo-init'
-Write-Host "[4/22] argo\skills\argo-init -> $skillDest"
+Write-Host "[4/23] argo\skills\argo-init -> $skillDest"
 Copy-Tree -Source $skillSrc -Destination $skillDest
 
 $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"
+Write-Host "[5/23] argo\rules\archgraph.instructions.md -> $ruleDest"
 New-Item -ItemType Directory -Force -Path $PromptsRoot | Out-Null
 Copy-Item -Force -Path $ruleSrc -Destination $ruleDest
 
 $depsSrc = Join-Path $argoDir 'package.json'
 $depsDest = Join-Path $ArgoRoot 'package.json'
-Write-Host "[6/22] argo\package.json -> $depsDest"
+Write-Host "[6/23] argo\package.json -> $depsDest"
 Copy-Item -Force -Path $depsSrc -Destination $depsDest
 
 $cursorSkillDest = Join-Path $CursorSkillsRoot 'argo-init'
-Write-Host "[7/22] argo\skills\argo-init -> $cursorSkillDest (Cursor)"
+Write-Host "[7/23] argo\skills\argo-init -> $cursorSkillDest (Cursor)"
 Copy-Tree -Source $skillSrc -Destination $cursorSkillDest
 
 $mcpBridgeSrc = Join-Path $argoDir 'mcp-bridges'
@@ -776,29 +779,29 @@ Write-Host "  argo\mcp-bridges -> $mcpBridgeDest (Cursor graph-mcp stdio bridge)
 Copy-Tree -Source $mcpBridgeSrc -Destination $mcpBridgeDest
 
 $openCodeSkillDest = Join-Path $OpenCodeSkillsRoot 'argo-init'
-Write-Host "[8/22] argo\skills\argo-init -> $openCodeSkillDest (OpenCode)"
+Write-Host "[8/23] argo\skills\argo-init -> $openCodeSkillDest (OpenCode)"
 Copy-Tree -Source $skillSrc -Destination $openCodeSkillDest
 
-Write-Host "[9/22] argo\rules\archgraph.instructions.md -> $OpenCodeAgentsPath (OpenCode global AGENTS.md)"
+Write-Host "[9/23] argo\rules\archgraph.instructions.md -> $OpenCodeAgentsPath (OpenCode global AGENTS.md)"
 Add-AgentsRule -AgentsPath $OpenCodeAgentsPath -RulePath $ruleSrc
 
 $agentsSrc = Join-Path $argoDir 'agents'
-Write-Host "[10/22] argo\agents -> $CopilotAgentsRoot (Copilot user-level)"
+Write-Host "[10/23] argo\agents -> $CopilotAgentsRoot (Copilot user-level)"
 Copy-Agents -Source $agentsSrc -Destination $CopilotAgentsRoot
 
-Write-Host "[11/22] argo\agents -> $CursorAgentsRoot (Cursor user-level, converted to .md)"
+Write-Host "[11/23] argo\agents -> $CursorAgentsRoot (Cursor user-level, converted to .md)"
 Copy-Agents -Source $agentsSrc -Destination $CursorAgentsRoot -Target cursor
 
-Write-Host "[12/22] argo\agents -> $OpenCodeAgentsRoot (OpenCode user-level, converted to .md)"
+Write-Host "[12/23] argo\agents -> $OpenCodeAgentsRoot (OpenCode user-level, converted to .md)"
 Copy-Agents -Source $agentsSrc -Destination $OpenCodeAgentsRoot -Target opencode
 
 $pluginsSrc = Join-Path $argoDir 'plugins'
-Write-Host "[13/22] argo\plugins -> $PluginsRoot (Argo opencode plugins)"
+Write-Host "[13/23] argo\plugins -> $PluginsRoot (Argo opencode plugins)"
 Copy-Tree -Source $pluginsSrc -Destination $PluginsRoot
 
 $cursorRuleSrc = Join-Path (Join-Path $argoDir 'rules') 'archgraph.instructions.md'
 $cursorRuleDest = Join-Path $CursorRulesRoot 'archgraph.mdc'
-Write-Host "[14/22] argo\rules\archgraph.instructions.md -> $cursorRuleDest (Cursor global rule, alwaysApply)"
+Write-Host "[14/23] argo\rules\archgraph.instructions.md -> $cursorRuleDest (Cursor global rule, alwaysApply)"
 New-Item -ItemType Directory -Force -Path $CursorRulesRoot | Out-Null
 Convert-RuleFile -SourceFile $cursorRuleSrc -DestinationFile $cursorRuleDest
 
@@ -810,16 +813,16 @@ if ($SkipDsh) {
     $patchPath = Join-Path $DshHome 'cordis.patch.yml'
     $argoServer = (Join-Path $ArgoRoot 'scripts\argo-mcp-server.js').Replace('\', '/')
 
-    Write-Host "[15/22] argo\rules\archgraph.instructions.md -> $DshHome\AGENTS.md (DeepSeek Harness user-global rule, frontmatter stripped)"
+    Write-Host "[15/23] argo\rules\archgraph.instructions.md -> $DshHome\AGENTS.md (DeepSeek Harness user-global rule, frontmatter stripped)"
     Write-DshAgentRule -DshHome $DshHome -RuleText $ruleSrcContent
 
-    Write-Host "[16/22] argo\skills\argo-init -> $dshSkillDest (DeepSeek Harness skill)"
+    Write-Host "[16/23] argo\skills\argo-init -> $dshSkillDest (DeepSeek Harness skill)"
     Copy-Tree -Source (Join-Path $argoDir 'skills\argo-init') -Destination $dshSkillDest
 
-    Write-Host "[17/22] argo\rules\<WakeupGuideline> -> $DshHome\plugins\dsh-argo-wakeup\index.js (DeepSeek Harness wakeup plugin)"
+    Write-Host "[17/23] argo\rules\<WakeupGuideline> -> $DshHome\plugins\dsh-argo-wakeup\index.js (DeepSeek Harness wakeup plugin)"
     $wakeupDshPath = New-DshWakeupPlugin -DshHome $DshHome -RuleText $ruleSrcContent
 
-    Write-Host "[18/22] argo-workspace + argo-wakeup rows -> $patchPath (DeepSeek Harness MCP bridge + wakeup plugin)"
+    Write-Host "[18/23] argo-workspace + argo-wakeup rows -> $patchPath (DeepSeek Harness MCP bridge + wakeup plugin)"
     # The generated dsh-argo-workspace bridge connects directly to the argo
     # server (no dsh-mcp-client row), registers every tool as mcp__argo__* and
     # injects the current session's workspace (SessionHeader.cwd) as the
@@ -850,7 +853,7 @@ if ($SkipDsh) {
         Write-DshManagedBlock -Path $patchPath -Block $block -MarkerStart '# BEGIN ArchGraph ARGO deployment' -MarkerEnd '# END ArchGraph ARGO deployment'
     }
 
-    Write-Host "[19/22] argo\agents -> $DshHome\.agent-presets\<id> (DeepSeek Harness agent presets)"
+    Write-Host "[19/23] argo\agents -> $DshHome\.agent-presets\<id> (DeepSeek Harness agent presets)"
     New-DshAgentPresets -DshHome $DshHome -AgentsSrc (Join-Path $argoDir 'agents')
 
     Write-Host "  note: graph-mcp remote ($GraphMcpUrl) is NOT registered for DeepSeek Harness -"
@@ -871,10 +874,10 @@ if ($SkipOpenClaw) {
     $openClawAgentsDest = Join-Path $OpenClawWorkspace 'AGENTS.md'
 
     Write-Host '==> Deploying OpenClaw integration'
-    Write-Host "[20/22] argo\rules\archgraph.instructions.md -> $openClawAgentsDest (OpenClaw workspace AGENTS.md, frontmatter stripped)"
+    Write-Host "[20/23] argo\rules\archgraph.instructions.md -> $openClawAgentsDest (OpenClaw workspace AGENTS.md, frontmatter stripped)"
     Write-OpenClawAgentRule -OpenClawWorkspace $OpenClawWorkspace -RuleText $ruleSrcContent
 
-    Write-Host "[21/22] argo\skills\argo-init -> $openClawSkillDest (OpenClaw managed skill, all agents)"
+    Write-Host "[21/23] argo\skills\argo-init -> $openClawSkillDest (OpenClaw managed skill, all agents)"
     Copy-Tree -Source (Join-Path $argoDir 'skills\argo-init') -Destination $openClawSkillDest
 
     Write-Host '  OpenClaw injects AGENTS.md into Project Context on every session, so the wakeup'
@@ -1043,7 +1046,7 @@ if ($SkipMcp) {
         # location; -OpenClawRepoRoot overrides it (e.g. for tests or when the
         # installer runs from a non-workspace npm-global package dir).
         $openClawRepoRoot = if ($OpenClawRepoRoot) { $OpenClawRepoRoot } else { $repoRoot }
-        Write-Host "[22/22] argo MCP server -> $(Join-Path $OpenClawHome 'openclaw.json') (OpenClaw mcp.servers.argo, env.ARGO_REPO_ROOT pinned)"
+        Write-Host "[22/23] argo MCP server -> $(Join-Path $OpenClawHome 'openclaw.json') (OpenClaw mcp.servers.argo, env.ARGO_REPO_ROOT pinned)"
         Write-OpenClawMcpConfig -OpenClawHome $OpenClawHome -RepoRoot $openClawRepoRoot -ArgoServer $argoServer -GraphMcpServer $openClawGraphMcpServer
     }
 }
@@ -1055,5 +1058,68 @@ if (Test-Path $wakeupPluginPath) {
     Write-Host "argo-wakeup plugin registered -> $OpenCodeConfigPath"
 }
 
+# EA local web service (WP2786): deploy the two service scripts next to the
+# harness scripts (REPO_ROOT = $ArgoRoot keeps the relative layout intact) plus
+# the web/ statics, then start the service in the background. Re-running the
+# installer is idempotent: an occupied port skips the startup.
+$eaServiceSrc = Join-Path $repoRoot 'scripts\ea-web-service.js'
+$eaLayoutStoreSrc = Join-Path $repoRoot 'scripts\ea-layout-store.js'
+$eaWebSrc = Join-Path $repoRoot 'web'
+Write-Host "[23/23] scripts\ea-web-service.js + scripts\ea-layout-store.js + web -> $ArgoRoot (EA local web service)"
+if ((Test-Path $eaServiceSrc) -and (Test-Path $eaLayoutStoreSrc) -and (Test-Path $eaWebSrc)) {
+    Copy-Item -Force -Path $eaServiceSrc -Destination (Join-Path $scriptsDest 'ea-web-service.js')
+    Copy-Item -Force -Path $eaLayoutStoreSrc -Destination (Join-Path $scriptsDest 'ea-layout-store.js')
+    Copy-Tree -Source $eaWebSrc -Destination (Join-Path $ArgoRoot 'web')
+    Write-Host "  service scripts + web statics deployed -> $scriptsDest / $(Join-Path $ArgoRoot 'web')"
+    if ($SkipEaWeb) {
+        Write-Host '  EA web service startup skipped (-SkipEaWeb)'
+    }
+    else {
+        $eaWebRoot = if ($EaWebRoot) { $EaWebRoot } else { $PWD.Path }
+        $eaPortInUse = $false
+        try {
+            $eaProbe = New-Object System.Net.Sockets.TcpClient
+            $eaProbe.Connect('127.0.0.1', $EaWebPort)
+            $eaPortInUse = $true
+            $eaProbe.Close()
+        }
+        catch {
+            $eaPortInUse = $false
+        }
+        if ($eaPortInUse) {
+            Write-Host "  EA web service already listening on 127.0.0.1:$EaWebPort; startup skipped (idempotent re-deploy)"
+        }
+        else {
+            $nodeCmd = Get-Command node -ErrorAction SilentlyContinue
+            if (-not $nodeCmd) {
+                throw 'EA web service startup failed: node not found on PATH'
+            }
+            $eaServiceDest = Join-Path $scriptsDest 'ea-web-service.js'
+            $eaLogOut = Join-Path $ArgoRoot 'ea-web-service.log'
+            $eaLogErr = Join-Path $ArgoRoot 'ea-web-service.err.log'
+            # Start the service through WMI (Win32_Process.Create) instead of
+            # Start-Process: the process is then created by the WMI service and
+            # inherits NONE of this installer's stdio pipe handles. Inherited
+            # pipes would keep spawnSync-based launchers (argo-deploy bin, tests)
+            # blocked until the service exits. cmd.exe is used only to redirect
+            # the service stdout/stderr into log files.
+            $q = [char]34
+            $eaCmdLine = "cmd.exe /S /c $q$q$($nodeCmd.Source)$q $q$eaServiceDest$q --root $q$eaWebRoot$q --port $EaWebPort > $q$eaLogOut$q 2> $q$eaLogErr$q$q"
+            $eaCreate = Invoke-CimMethod -ClassName Win32_Process -MethodName Create -Arguments @{
+                CommandLine      = $eaCmdLine
+                CurrentDirectory = $ArgoRoot
+            }
+            if ($eaCreate.ReturnValue -ne 0) {
+                throw "EA web service startup failed: Win32_Process.Create ReturnValue $($eaCreate.ReturnValue)"
+            }
+            Write-Host "  EA web service started in background (pid $($eaCreate.ProcessId)): http://127.0.0.1:$EaWebPort (root: $eaWebRoot)"
+            Write-Host "  logs: $eaLogOut / $eaLogErr"
+        }
+    }
+}
+else {
+    Write-Host '  EA web service sources not present in this package; step skipped'
+}
+
 Write-Host ''
 Write-Host 'Argo deployment complete.'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "archgraph-argo",
-  "version": "0.10.52",
+  "version": "0.11.0",
   "description": "Deploy the ArchGraph ARGO toolchain, skills, and rules (schema, scripts, argo-init skill, global rule) with one command.",
   "license": "MIT",
   "bin": {
@@ -16,6 +16,9 @@
     "argo/skills/argo-init",
     "argo/rules",
     "argo/package.json",
+    "scripts/ea-web-service.js",
+    "scripts/ea-layout-store.js",
+    "web",
     "vendor",
     "install-argo.ps1",
     "bin",

package/scripts/ea-layout-store.js

@@ -0,0 +1,242 @@
+'use strict';
+
+/**
+ * 布局侧车（Layout Sidecar，WP2785 M1-S2，2026-09-03 修订：默认按项目隔离，AT-2785-L5）
+ * — 图谱画布坐标独立持久化。
+ *
+ * 零第三方依赖（仅 Node 内置 path/fs/crypto）。与 design/KG/SystemArchitecture.json
+ * 完全物理隔离：坐标不进图谱 JSON、不进 schema；本模块永远不读写图谱文件本身。
+ *
+ * 存储根（按优先级）：
+ * 1. 显式覆盖：createLayoutStore({ layoutRoot }) 选项或 EA_LAYOUT_ROOT 环境变量
+ *    → <layoutRoot>/<projectId>/<view_id>.json（测试 / 自定义集中存储根）。
+ * 2. 默认（无任何覆盖）：按项目隔离
+ *    → <projectRoot>/design/KG/ea-layouts/<view_id>.json（仍是独立文件，
+ *      只落在 ea-layouts/ 子目录，绝不触碰 SystemArchitecture.json 本身）。
+ *
+ * 文件内容：{ version, graphKey, view_id, signature, updatedAt, elements: { <elementId>: {x,y} } }
+ *
+ * 失效键 = 视图成员身份签名（成员身份集合的 sha256，只含身份 id，不含任何内容字段）：
+ * signature = sha256(sorted(included_elements) + sorted(included_relationships))。
+ * 图谱内容级修改（元素 name/description/attributes、关系描述等）不改变成员集合
+ * → signature 不变 → 坐标完全不动；仅成员结构变化触发新成员补位/移除成员清理。
+ *
+ * 合并语义（读取时）：以当前图谱视图成员为准——仍有坐标的现存成员原样保留；
+ * 新成员（无坐标）按确定性算法补位（沿用 buildViewGraph 的圆形布局公式）并写回侧车；
+ * 已不在成员中的坐标清理。
+ */
+
+const path = require('node:path');
+const fs = require('node:fs');
+const crypto = require('node:crypto');
+
+const LAYOUT_VERSION = 1;
+// 默认按项目隔离时，侧车相对项目根的存放目录。
+const PROJECT_LAYOUT_DIR = path.join('design', 'KG', 'ea-layouts');
+
+/**
+ * 解析显式存储根覆盖：选项 > EA_LAYOUT_ROOT 环境变量。
+ * 返回 null 表示无覆盖 → 使用默认的按项目隔离存储。
+ */
+function resolveLayoutRoot(explicitRoot) {
+  if (explicitRoot) {
+    return path.resolve(explicitRoot);
+  }
+  if (process.env.EA_LAYOUT_ROOT) {
+    return path.resolve(process.env.EA_LAYOUT_ROOT);
+  }
+  return null;
+}
+
+/**
+ * 视图成员身份签名：仅由 included_elements / included_relationships 的身份 id 集合决定，
+ * 与元素/关系的任何内容字段无关。
+ */
+function computeViewSignature(view) {
+  const elements = Array.from(new Set((view && view.included_elements) || [])).sort();
+  const relationships = Array.from(new Set((view && view.included_relationships) || [])).sort();
+  const payload = `${elements.join('\u0001')}\u0000${relationships.join('\u0001')}`;
+  return crypto.createHash('sha256').update(payload).digest('hex');
+}
+
+// 文件名安全化（服务端路由已限制 [A-Za-z0-9._-]，此处为独立模块的防御性兜底）。
+function safeFileName(segment) {
+  return String(segment).replace(/[^A-Za-z0-9._-]/g, '_');
+}
+
+/**
+ * 确定性补位：沿用 buildViewGraph 的圆形布局公式（成员索引 → 圆周位置）。
+ */
+function defaultPosition(index, count) {
+  const angle = (2 * Math.PI * index) / Math.max(count, 1);
+  return {
+    x: Math.round(80 + 160 * Math.cos(angle)),
+    y: Math.round(80 + 160 * Math.sin(angle)),
+  };
+}
+
+function isValidPosition(pos) {
+  return !!pos
+    && typeof pos === 'object'
+    && !Array.isArray(pos)
+    && Number.isFinite(Number(pos.x))
+    && Number.isFinite(Number(pos.y));
+}
+
+function createLayoutStore(options = {}) {
+  // null → 默认按项目隔离存储；否则为显式集中存储根。
+  const explicitRoot = resolveLayoutRoot(options.layoutRoot);
+
+  /**
+   * 目标解析：target = { project?: {id, root, graphPath}, projectId?, graphKey? }。
+   * 显式根模式用 projectId 分桶；默认模式用 project.root 定位项目内 ea-layouts/ 目录。
+   */
+  function resolveTarget(target, viewId) {
+    const t = target || {};
+    const project = t.project || {};
+    const projectId = t.projectId || project.id || null;
+    const graphKey = t.graphKey || project.graphPath || null;
+    if (explicitRoot) {
+      if (!projectId) {
+        throw new Error('layout store: 显式存储根模式下必须提供 projectId（或 project.id）');
+      }
+      return {
+        projectId,
+        graphKey,
+        filePath: path.join(explicitRoot, safeFileName(projectId), `${safeFileName(viewId)}.json`),
+      };
+    }
+    const projectRoot = project.root;
+    if (!projectRoot) {
+      throw new Error('layout store: 默认按项目隔离存储必须提供 project.root');
+    }
+    return {
+      projectId,
+      graphKey,
+      filePath: path.join(path.resolve(projectRoot), PROJECT_LAYOUT_DIR, `${safeFileName(viewId)}.json`),
+    };
+  }
+
+  function filePathFor(target, viewId) {
+    return resolveTarget(target, viewId).filePath;
+  }
+
+  function readRecord(target, viewId) {
+    let text;
+    try {
+      text = fs.readFileSync(filePathFor(target, viewId), 'utf8');
+    } catch {
+      return null;
+    }
+    try {
+      const record = JSON.parse(text);
+      if (!record || typeof record !== 'object' || Array.isArray(record)) {
+        return null;
+      }
+      if (!record.elements || typeof record.elements !== 'object' || Array.isArray(record.elements)) {
+        record.elements = {};
+      }
+      return record;
+    } catch {
+      return null;
+    }
+  }
+
+  function writeRecord(target, viewId, record) {
+    const filePath = filePathFor(target, viewId);
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    const tempPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+    fs.writeFileSync(tempPath, JSON.stringify(record, null, 2), 'utf8');
+    fs.renameSync(tempPath, filePath);
+    return filePath;
+  }
+
+  /**
+   * 读取合并后的布局（以当前图谱视图成员为准）。
+   * 有补位/清理/签名变化时写回侧车；纯内容级修改（签名不变）不触发写入。
+   * 入参：{ project?: {id, root, graphPath}, projectId?, graphKey?, view }。
+   * 返回 { signature, elements: { <elementId>: {x,y} } }。
+   */
+  function mergeLayout({ project, projectId, graphKey, view }) {
+    if (!view || typeof view.view_id !== 'string') {
+      throw new Error('mergeLayout: view with view_id is required');
+    }
+    const target = { project, projectId, graphKey };
+    const viewId = view.view_id;
+    const signature = computeViewSignature(view);
+    const record = readRecord(target, viewId);
+    const saved = record ? record.elements : {};
+    const members = Array.isArray(view.included_elements) ? view.included_elements : [];
+    const elements = {};
+    let dirty = !record || record.signature !== signature;
+
+    members.forEach((id, index) => {
+      const pos = saved[id];
+      if (isValidPosition(pos)) {
+        elements[id] = { x: Number(pos.x), y: Number(pos.y) };
+      } else {
+        elements[id] = defaultPosition(index, members.length);
+        dirty = true;
+      }
+    });
+    for (const id of Object.keys(saved)) {
+      if (!members.includes(id)) {
+        dirty = true; // 已不在成员中的坐标：清理
+      }
+    }
+    if (dirty) {
+      writeRecord(target, viewId, {
+        version: LAYOUT_VERSION,
+        graphKey: resolveTarget(target, viewId).graphKey,
+        view_id: viewId,
+        signature,
+        updatedAt: new Date().toISOString(),
+        elements,
+      });
+    }
+    return { signature, elements };
+  }
+
+  /**
+   * 全量写入布局（按当前文档计算签名后原子写入侧车文件）。
+   * 入参：{ project?: {id, root, graphPath}, projectId?, graphKey?, view, elements }；
+   * elements: { <elementId>: {x,y} }；非法坐标抛错（由服务端映射为 400）。
+   */
+  function putLayout({ project, projectId, graphKey, view, elements }) {
+    if (!view || typeof view.view_id !== 'string') {
+      throw new Error('putLayout: view with view_id is required');
+    }
+    if (!elements || typeof elements !== 'object' || Array.isArray(elements)) {
+      throw new Error('body.elements 必须是 { <elementId>: {x,y} } 对象');
+    }
+    const normalized = {};
+    for (const [id, pos] of Object.entries(elements)) {
+      if (!isValidPosition(pos)) {
+        throw new Error(`elements['${id}'] 的坐标必须是有限的 {x,y} 数字`);
+      }
+      normalized[id] = { x: Number(pos.x), y: Number(pos.y) };
+    }
+    const target = { project, projectId, graphKey };
+    const signature = computeViewSignature(view);
+    writeRecord(target, view.view_id, {
+      version: LAYOUT_VERSION,
+      graphKey: resolveTarget(target, view.view_id).graphKey,
+      view_id: view.view_id,
+      signature,
+      updatedAt: new Date().toISOString(),
+      elements: normalized,
+    });
+    return { signature, view_id: view.view_id };
+  }
+
+  return { root: explicitRoot, filePathFor, readRecord, writeRecord, mergeLayout, putLayout };
+}
+
+module.exports = {
+  LAYOUT_VERSION,
+  PROJECT_LAYOUT_DIR,
+  resolveLayoutRoot,
+  computeViewSignature,
+  defaultPosition,
+  createLayoutStore,
+};