archgraph-argo 0.12.1 → 0.12.3

package/argo/scripts/argo-mcp-server.js

@@ -33,8 +33,8 @@ const EA_TEMPLATE_PATH_CANDIDATES = [
   ['.opencode', 'EA-model-template.qea'],
   ['eatool', 'EA-model-template.qea'],
   ['EA-model-template.qea'],
-  ['Argo.feap'],
 ];
+const EA_MODEL_EXTENSIONS = new Set(['.qea', '.feap', '.eap']);
 const WINDOWS_RESERVED_NAMES = new Set([
   'CON', 'PRN', 'AUX', 'NUL',
   'COM1', 'COM2', 'COM3', 'COM4', 'COM5', 'COM6', 'COM7', 'COM8', 'COM9',
@@ -379,7 +379,7 @@ async function callTool(name, args = {}, progressToken = null, dependencies = un
     return toolResult({
       status: report.status,
       workspaceRoot: workspace.workspaceRoot,
-      targetFeapName: workspace.targetFeapName,
+      targetEaName: workspace.targetEaName,
       createdFiles: workspace.createdFiles,
       updatedFiles: workspace.updatedFiles,
       removedFiles: workspace.removedFiles,
@@ -387,7 +387,7 @@ async function callTool(name, args = {}, progressToken = null, dependencies = un
       workspaceBootstrap: {
         status: 'ok',
         workspaceRoot: workspace.workspaceRoot,
-        targetFeapName: workspace.targetFeapName,
+        targetEaName: workspace.targetEaName,
         createdFiles: workspace.createdFiles,
         updatedFiles: workspace.updatedFiles,
         removedFiles: workspace.removedFiles,
@@ -481,13 +481,18 @@ async function initializeWorkspace(workspaceRoot) {
   }
 
   const templateSourcePath = resolveTemplateSourcePath(workspaceRoot);
-  const targetFeapName = buildTargetFileName(workspaceName);
-  const targetFeapPath = path.join(workspaceRoot, targetFeapName);
-  if (!fs.existsSync(targetFeapPath)) {
-    await fs.promises.copyFile(templateSourcePath, targetFeapPath);
-    createdFiles.push(normalizeRelativePath(targetFeapName));
+  const targetEaName = buildEaTargetFileName(workspaceName);
+  const targetEaPath = path.join(workspaceRoot, targetEaName);
+  const existingEaFiles = listExistingEaModelFiles(workspaceRoot);
+  if (existingEaFiles.length === 0) {
+    // No EA model file in the workspace: bootstrap a project-named .qea from the
+    // template (EA 17.2+ .qea/SQLite). Never generate a legacy .feap anymore.
+    await fs.promises.copyFile(templateSourcePath, targetEaPath);
+    createdFiles.push(normalizeRelativePath(targetEaName));
+  } else if (existingEaFiles.includes(targetEaName)) {
+    skippedSteps.push(`${normalizeRelativePath(targetEaName)} already exists`);
   } else {
-    skippedSteps.push(`${normalizeRelativePath(targetFeapName)} already exists`);
+    skippedSteps.push(`EA model already present (${existingEaFiles.join(', ')}); skip bootstrapping ${normalizeRelativePath(targetEaName)}`);
   }
 
   for (const handoffPath of HANDOFF_FILES_TO_RESET) {
@@ -509,7 +514,7 @@ async function initializeWorkspace(workspaceRoot) {
   return {
     workspaceRoot,
     qeaFullProjection,
-    targetFeapName,
+    targetEaName,
     createdFiles,
     updatedFiles,
     removedFiles,
@@ -543,12 +548,24 @@ function resolveGraphDefaultSourcePath() {
   throw new Error(`Unable to locate default SystemArchitecture template. Checked: bundled ${BUNDLED_GRAPH_DEFAULT_SEGMENTS.join('/')}`);
 }
 
-function buildTargetFileName(workspaceName) {
+function listExistingEaModelFiles(workspaceRoot) {
+  let names = [];
+  try {
+    names = fs.readdirSync(workspaceRoot).filter(name =>
+      EA_MODEL_EXTENSIONS.has(path.extname(name).toLowerCase()),
+    );
+  } catch {
+    /* treat an unreadable root as having no EA model file */
+  }
+  return names.sort();
+}
+
+function buildEaTargetFileName(workspaceName) {
   const sanitized = sanitizeFileName(workspaceName) || 'workspace';
   const safeBaseName = WINDOWS_RESERVED_NAMES.has(sanitized.toUpperCase())
     ? `${sanitized}_workspace`
     : sanitized;
-  return `${safeBaseName}.feap`;
+  return `${safeBaseName}.qea`;
 }
 
 function sanitizeFileName(value) {

package/argo/scripts/ensureArgoHarnessEnvironment.js

@@ -135,7 +135,7 @@ async function ensureWorkspaceBootstrap({ checkOnly, workspaceRoot }) {
     return {
       status: 'ok',
       workspaceRoot: workspace.workspaceRoot,
-      targetFeapName: workspace.targetFeapName,
+      targetEaName: workspace.targetEaName,
       createdFiles: workspace.createdFiles,
       updatedFiles: workspace.updatedFiles,
       removedFiles: workspace.removedFiles,

package/argo/skills/argo-init/SKILL.md

@@ -1,22 +1,25 @@
 ---
 name: argo-init
-description: "通过 ARGO MCP 的 initializeWorkspace 接口完成工作区确定性的初始化（NEO4J 初始同步 + 语义生命周期 + canonical 校验 + subdiagram_views 一致性），无需执行 WORKSPACE 外脚本。Use when the user asks to verify Argo MCP readiness and perform or verify the canonical JSON-to-Neo4j initial sync plus semantic lifecycle init. Keywords: ARGO INIT, harness init, initializeWorkspace, Neo4j initial sync, semantic lifecycle."
+description: "通过 ARGO MCP 的 initializeWorkspace 接口完成工作区确定性的初始化（NEO4J 初始同步 + .qea 全量投影 + 语义生命周期 + canonical 校验 + subdiagram_views 一致性），无需执行 WORKSPACE 外脚本。Use when the user asks to verify Argo MCP readiness and perform or verify the canonical JSON-to-Neo4j initial sync, .qea full projection (target file must be this repo's own .qea), plus semantic lifecycle init. Keywords: ARGO INIT, harness init, initializeWorkspace, Neo4j initial sync, qea projection, semantic lifecycle."
 argument-hint: scope-or-mode
 disable-model-invocation: true
 ---
 
 # ARGO INIT
 
-`argo-init` 通过 ARGO MCP 的 `initializeWorkspace` 接口完成确定性初始化：工作区 bootstrap（缺 `SystemArchitecture.json` / `.feap` 自动生成）+ Neo4j 结构投影同步 + 语义生命周期初始化 + canonical 校验 + subdiagram_views 一致性，并返回完整报告。**不需要也不应执行任何 WORKSPACE 外脚本**——所有确定性步骤都在 MCP 进程内完成，避免扩大访问面。
+`argo-init` 通过 ARGO MCP 的 `initializeWorkspace` 接口完成确定性初始化：工作区 bootstrap（缺 `SystemArchitecture.json` / EA 模型文件（`.qea`）自动生成）+ Neo4j 结构投影同步 + **.qea 全量投影（整库清空重建，逻辑同 Neo4j init）** + 语义生命周期初始化 + canonical 校验 + subdiagram_views 一致性，并返回完整报告。**不需要也不应执行任何 WORKSPACE 外脚本**——所有确定性步骤都在 MCP 进程内完成，避免扩大访问面。
 
-- 工作区缺少 `design/KG/SystemArchitecture.json` 时自动从部署的 `defaults` 拷贝默认模板；缺 `.feap` 时以当前项目名拷贝默认模板。
-- 本机 Neo4j 连接可用，canonical 意图图完成至少一次 JSON -> Neo4j 初始同步并通过一致性校验。
+- 工作区缺少 `design/KG/SystemArchitecture.json` 时自动从部署的 `defaults` 拷贝默认模板；缺 EA 模型文件（仓库根无 `.qea`/`.feap`/`.eap`）时以当前项目名拷贝默认 `.qea` 模板（不再补建遗留 `.feap`）。
+- 本机 Neo4j 连接可用，canonical 意图图完成至少一次 JSON -> Neo4j 初始同步并通过一致性校验；**投影到的 Neo4j 数据库名称必须与本仓库名称一致**（如仓库 archgraph → 库 archgraph），不一致须报告为告警/失败。
+- **.qea 投影**：init 对仓库 EA 文件（仓库根 `.qea`，经 `ARGO_EA_QEA` 或仓库根唯一 `*.qea` 解析）执行整库清空后全量重建；**必须确认投影目标是本仓库自己的 `.qea` 文件**，并报告投影成功/失败与耗时。
 - 语义生命周期：双 gate 未开启时记录 skipped/disabled；开启时执行全量 embedding backfill 与 readiness 对齐。
 
 ## Rules
 
 - **MUST** 调用 ARGO MCP 工具 `initializeWorkspace`（传当前工作区根）执行确定性初始化，并以其返回报告为最终判断依据。
-- **MUST** 报告 `mcp` / `systemArchitecture` / `neo4j` / `semanticLifecycle` / `subdiagramViews` 与整体 `status`。
+- **MUST** 报告 `mcp` / `systemArchitecture` / `neo4j` / `qeaFullProjection` / `semanticLifecycle` / `subdiagramViews` 与整体 `status`。
+- **MUST** 核验并报告：① `.qea` 投影是否成功（`qeaFullProjection.status`），且投影目标 `qeaFullProjection.qea` 是否为**本仓库自己的 .qea 文件**（解析自 `ARGO_EA_QEA` 或仓库根唯一 `*.qea`）；目标不是本仓库文件或投影失败 → 报告为告警/失败，不得视为 init 成功。
+- **MUST** 核验并报告：Neo4j 投影目标数据库名（`neo4j.database`）是否**与本仓库名一致**（仓库 basename == 数据库名）；不一致 → 报告为告警/失败。
 - **MUST NOT** 读取、打印或复述 `.env` 中的 secret 值；排查时只允许报告 key 是否存在、ACL 主体。
 - **MUST NOT** 通过 shell 手工执行 WORKSPACE 外的初始化脚本或一组无关命令来替代 `initializeWorkspace`（除非报告显示底层脚本自身失败需要排查）。
 
@@ -26,17 +29,21 @@ disable-model-invocation: true
 
 调用 ARGO MCP 工具 `initializeWorkspace`（传入当前工作区根 `workspaceRoot`）。该接口在 MCP 进程内完成全部确定性步骤并返回报告：
 
-- `workspaceBootstrap`：缺 `SystemArchitecture.json` / `.feap` 时自动生成（createdFiles / skippedSteps）
+- `workspaceBootstrap`：缺 `SystemArchitecture.json` / EA 模型文件时自动生成 `.qea`（createdFiles / skippedSteps；仓库根已有 `.qea`/`.feap` 时不重复补建）
 - `mcp`：ARGO MCP 健康（协议 / tools-list / ping）
 - `systemArchitecture`：canonical 校验（元素/关系/视图计数）
 - `subdiagramViews`：subdiagram_views 一致性检查/修复
-- `neo4j`：Neo4j 连通 + 结构投影初始同步 + 一致性校验（initialSync / verification）
+- `neo4j`：Neo4j 连通 + 结构投影初始同步 + 一致性校验（initialSync / verification）；**并核验投影目标数据库名 == 本仓库名**
+- `qeaFullProjection`：仓库 EA（.qea）整库清空重建 + 一致性（status / qea 目标路径 / ms）；**核验 qea 目标 == 本仓库自己的 .qea 文件**
 - `semanticLifecycle`：语义生命周期初始化（state / alignment / readiness；未开 gate 时 skipped/disabled）
 
 ### 2. Interpret The Report
 
 - 整体 `status=ok`：环境就绪。
-- 任一 section `status=failed` → 整体 `status=failed`，指出失败阶段：`mcp` / `systemArchitecture` / `neo4j` / `semanticLifecycle` / `subdiagramViews`。
+- 任一 section `status=failed` → 整体 `status=failed`，指出失败阶段：`mcp` / `systemArchitecture` / `neo4j` / `qeaFullProjection` / `semanticLifecycle` / `subdiagramViews`。
+- **目标一致性核验（在报告中明确给出）**：
+  - `qeaFullProjection.qea` 是否为**本仓库自己的 .qea 文件**（== 解析自 `ARGO_EA_QEA`/仓库根唯一 `*.qea` 的路径）；投影成功且目标为本仓库文件才算该 section ok；投影失败或目标非本仓库文件 → 报告告警/失败。
+  - `neo4j.database` 是否**与本仓库名（仓库根目录名）一致**；不一致 → 报告告警/失败。
 
 ### 3. Handle Secret File Blockers（仅当报告含 secret 相关失败）
 
@@ -57,7 +64,7 @@ icacls "$env:USERPROFILE\.argo\.env"
 
 ### 4. Report Concisely
 
-输出应直接说明：`mcp` 是否正常、`SystemArchitecture.json` 是否正常、Neo4j 是否连通、是否完成一次初始同步、语义生命周期状态与 alignment、报告路径（`.argo/temp/argo-harness-init-report.json`）。
+输出应直接说明：`mcp` 是否正常、`SystemArchitecture.json` 是否正常、Neo4j 是否连通且**投影数据库名是否与本仓库名一致**、`.qea` 全量投影是否成功且**目标是否为本仓库 .qea 文件**、是否完成一次初始同步、语义生命周期状态与 alignment、报告路径（`.argo/temp/argo-harness-init-report.json`）。
 
 ## Output
 
@@ -67,11 +74,14 @@ icacls "$env:USERPROFILE\.argo\.env"
 - overall status: ok / failed
 - whether mcp health passed
 - whether neo4j health passed
+- whether .qea full projection passed
 
 ### 2. Sync Status
 - whether initial sync was executed
 - whether verification matched JSON and Neo4j
 - current counts summary when available
+- **neo4j 投影数据库名 == 本仓库名？**（是/否，给出名称）
+- **qea 投影目标文件 == 本仓库 .qea？**（是/否，给出路径）；投影耗时 ms
 
 ### 3. Semantic Lifecycle Status
 - whether semantic lifecycle init ran, skipped, or failed

package/package.json

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