@yss123/cage-cli 0.1.0 → 0.2.0

package/README.md

@@ -1,6 +1,6 @@
 # @yss123/cage-cli
 
-cage 命令行：gen、check、impact、test、verify、budget、sync、upgrade、dev、migrate
+cage 命令行：init、gen、check、graph、context、impact、test、verify、budget、sync、upgrade、dev、migrate
 
 Cage 是通过 TypeScript 声明业务、由框架统一执行权限和数据规则的中后台框架。此包是框架的一部分。
 
@@ -12,6 +12,28 @@ pnpm add -D @yss123/cage-cli
 
 首次使用建议通过脚手架创建完整项目，所需依赖由模板统一配置。需要 Node.js 24 或更新版本。
 
+`pnpm exec cage create my-app` 交互选择空白业务项目或采购示例项目；也可显式指定 `--template blank` 或 `--template purchase`。省略目录时可交互输入，非交互终端必须同时提供目录与模板。`--framework-path F:/cage` 可链接已构建的本地框架。
+
+自 `0.2.0` 起，两种产物都包含根目录 `AGENTS.md`、`docs/ai` 业务开发教材和 `docs/errors` 离线错误码册。空白项目只运行组织模型，采购参考代码在 `docs/examples/purchase-admin`；采购项目运行完整演示链路。让 Codex 等编程工具先读 `AGENTS.md`，无需另行克隆框架源码。
+
+`cage sync` 更新 AGENTS 框架托管区，保留标记外的项目业务约定；它不自动覆盖业务代码或学习资料。
+
+## 用本体图开发业务
+
+在应用根目录执行：
+
+```powershell
+pnpm exec cage context "修改采购单取消逻辑"
+pnpm exec cage graph search "取消" --kind command
+pnpm exec cage graph inspect command:PurchaseOrder.cancel
+pnpm exec cage graph path command:PurchaseOrder.cancel command:InventoryLock.release
+pnpm exec cage context command:PurchaseOrder.cancel --format json --out .cage/context.json
+```
+
+CLI 每次重新抽取，不需要数据库；报告包含中文候选与依据、业务关系解释、源码位置、契约/前端/测试候选、迁移和授权提示。默认 Markdown；查询支持 `--format json`、`--out`，context 可用 `--depth` / `--limit` 控制范围。图规则错误仍输出可用上下文并返回非零；无命中、精确节点歧义或深度内无路径也非零。Web 节点详情可复制同源 AI 上下文，修改代码后先重新抽取。
+
+名称、SQL 字段和测试匹配是线索；具体执行条件需阅读源码。上述命令自 `0.2.0` 提供，完整流程随新项目分发在 `docs/ai/ontology-context.md`。
+
 - [完整使用说明](https://github.com/shunshunyue/cage/blob/main/docs/使用说明.md)
 - [框架源码与范例](https://github.com/shunshunyue/cage)
 - [问题反馈](https://github.com/shunshunyue/cage/issues)

package/dist/analyze.js

@@ -5,9 +5,11 @@ import { loadRegistry } from './load.js';
 import { extract } from './ontology.js';
 import { runRules } from './rules.js';
 import { staticCheck, unexportedFindings } from './static-check.js';
+import { checkProjectStructure } from './project-structure.js';
 /** 静态检查先于模块求值；发现动态声明或 IO 时不执行模块。 */
 export async function analyze(cfg, opts = {}) {
     const source = staticCheck(cfg);
+    source.findings.push(...checkProjectStructure(cfg));
     if (errorsOnly(source.findings).length)
         return { source, findings: source.findings };
     const { mod, registry } = await loadRegistry(abs(cfg, cfg.domain));

package/dist/analyze.js.map

@@ -1 +1 @@
-{"version":3,"file":"analyze.js","sourceRoot":"","sources":["../src/analyze.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,GAAG,EAAmB,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,UAAU,EAAgB,MAAM,eAAe,CAAC;AACzD,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,EAAE,OAAO,EAAiB,MAAM,eAAe,CAAC;AACvD,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAEpE,oCAAoC;AACpC,MAAM,CAAC,KAAK,UAAU,OAAO,CAAC,GAAe,EAAE,OAA6C,EAAE;IAC5F,MAAM,MAAM,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC;IAChC,IAAI,UAAU,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,MAAM;QAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,CAAC;IACrF,MAAM,EAAE,GAAG,EAAE,QAAQ,EAAE,GAAG,MAAM,YAAY,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC;IACnE,MAAM,KAAK,GAAG,OAAO,CAAC,QAAQ,EAAE,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,WAAW,CAAC,CAAC;IAClE,MAAM,QAAQ,GAAc;QAC1B,GAAG,MAAM,CAAC,QAAQ;QAClB,GAAG,kBAAkB,CAAC,MAAM,CAAC,KAAK,EAAE,IAAI,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;QAC9D,GAAG,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC,IAAI,CAAC;KAC9B,CAAC;IACF,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;QACf,SAAS,CAAC,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAClD,aAAa,CAAC,GAAG,CAAC,GAAG,EAAE,qBAAqB,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IACxF,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC;AAC/C,CAAC"}
+{"version":3,"file":"analyze.js","sourceRoot":"","sources":["../src/analyze.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,GAAG,EAAmB,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,UAAU,EAAgB,MAAM,eAAe,CAAC;AACzD,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,EAAE,OAAO,EAAiB,MAAM,eAAe,CAAC;AACvD,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACpE,OAAO,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAE/D,oCAAoC;AACpC,MAAM,CAAC,KAAK,UAAU,OAAO,CAAC,GAAe,EAAE,OAA6C,EAAE;IAC5F,MAAM,MAAM,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC;IAChC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,qBAAqB,CAAC,GAAG,CAAC,CAAC,CAAC;IACpD,IAAI,UAAU,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,MAAM;QAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,CAAC;IACrF,MAAM,EAAE,GAAG,EAAE,QAAQ,EAAE,GAAG,MAAM,YAAY,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC;IACnE,MAAM,KAAK,GAAG,OAAO,CAAC,QAAQ,EAAE,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,WAAW,CAAC,CAAC;IAClE,MAAM,QAAQ,GAAc;QAC1B,GAAG,MAAM,CAAC,QAAQ;QAClB,GAAG,kBAAkB,CAAC,MAAM,CAAC,KAAK,EAAE,IAAI,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;QAC9D,GAAG,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC,IAAI,CAAC;KAC9B,CAAC;IACF,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;QACf,SAAS,CAAC,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAClD,aAAa,CAAC,GAAG,CAAC,GAAG,EAAE,qBAAqB,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IACxF,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC;AAC/C,CAAC"}

package/dist/config.d.ts

@@ -16,8 +16,8 @@ export interface CageConfig {
     typecheck: string[];
     /** lint 与依赖规则检查的目录 */
     lint: string[];
-    /** 本地开发数据库端口；用于 Docker 初始配置及未配置外部连接时的内嵌实例 */
-    devDbPort: number;
+    /** 新脚手架启用模块目录约束；旧项目可整理后显式开启，不因升级 CLI 被迫迁移。 */
+    structure?: 'modular';
     /** 图谱的显示文案独立于业务标识；键为“节点类型:节点 ID”，不影响路由、
      * 数据表、能力点和影响分析。可用短标题覆盖较长的声明 description。 */
     graph?: {

package/dist/config.js

@@ -37,7 +37,6 @@ export function loadConfig(start) {
         web: 'apps/web',
         typecheck: ['packages/domain', 'packages/contracts', 'apps/api', 'apps/web'],
         lint: ['packages/domain/src', 'apps/api/src', 'apps/web/src'],
-        devDbPort: 54329,
         ...pkg.cage,
         ...user,
     };

package/dist/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,6CAA6C;AAC7C,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA2BnD,MAAM,UAAU,QAAQ,CAAC,KAAK,GAAG,OAAO,CAAC,GAAG,EAAE;IAC5C,IAAI,GAAG,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;IACzB,SAAS,CAAC;QACR,IAAI,UAAU,CAAC,IAAI,CAAC,GAAG,EAAE,kBAAkB,CAAC,CAAC;YAAE,OAAO,GAAG,CAAC;QAC1D,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,cAAc,CAAC,CAAC;QACtC,IAAI,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;YACpB,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,CAAC;YAChD,IAAI,CAAC,CAAC,eAAe,EAAE,CAAC,kBAAkB,CAAC,IAAI,CAAC,CAAC,YAAY,EAAE,CAAC,kBAAkB,CAAC,IAAI,CAAC,CAAC,IAAI;gBAAE,OAAO,GAAG,CAAC;QAC5G,CAAC;QACD,MAAM,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;QACxB,IAAI,EAAE,KAAK,GAAG;YAAE,OAAO,OAAO,CAAC,KAAK,CAAC,CAAC;QACtC,GAAG,GAAG,EAAE,CAAC;IACX,CAAC;AACH,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,KAAc;IACvC,MAAM,IAAI,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;IAC7B,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,EAAE,kBAAkB,CAAC,CAAC;IAC5C,MAAM,IAAI,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAC5E,MAAM,GAAG,GAAG,UAAU,CAAC,IAAI,CAAC,IAAI,EAAE,cAAc,CAAC,CAAC;QAChD,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,EAAE,cAAc,CAAC,EAAE,MAAM,CAAC,CAAC;QAC9D,CAAC,CAAC,EAAE,CAAC;IACP,MAAM,CAAC,GAAG;QACR,IAAI,EAAE,GAAG,CAAC,IAAI,IAAI,UAAU;QAC5B,MAAM,EAAE,8BAA8B;QACtC,SAAS,EAAE,wBAAwB;QACnC,gBAAgB,EAAE,gBAAgB;QAClC,UAAU,EAAE,eAAe;QAC3B,SAAS,EAAE,WAAW;QACtB,QAAQ,EAAE,sBAAsB;QAChC,WAAW,EAAE,wBAAwB;QACrC,GAAG,EAAE,UAAU;QACf,SAAS,EAAE,CAAC,iBAAiB,EAAE,oBAAoB,EAAE,UAAU,EAAE,UAAU,CAAC;QAC5E,IAAI,EAAE,CAAC,qBAAqB,EAAE,cAAc,EAAE,cAAc,CAAC;QAC7D,SAAS,EAAE,KAAK;QAChB,GAAG,GAAG,CAAC,IAAI;QACX,GAAG,IAAI;KACR,CAAC;IACF,OAAO,EAAE,GAAG,CAAC,EAAE,IAAI,EAAE,CAAC;AACxB,CAAC;AAED,MAAM,CAAC,MAAM,GAAG,GAAG,CAAC,GAAe,EAAE,CAAS,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC"}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,6CAA6C;AAC7C,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA2BnD,MAAM,UAAU,QAAQ,CAAC,KAAK,GAAG,OAAO,CAAC,GAAG,EAAE;IAC5C,IAAI,GAAG,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;IACzB,SAAS,CAAC;QACR,IAAI,UAAU,CAAC,IAAI,CAAC,GAAG,EAAE,kBAAkB,CAAC,CAAC;YAAE,OAAO,GAAG,CAAC;QAC1D,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,cAAc,CAAC,CAAC;QACtC,IAAI,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;YACpB,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,CAAC;YAChD,IAAI,CAAC,CAAC,eAAe,EAAE,CAAC,kBAAkB,CAAC,IAAI,CAAC,CAAC,YAAY,EAAE,CAAC,kBAAkB,CAAC,IAAI,CAAC,CAAC,IAAI;gBAC3F,OAAO,GAAG,CAAC;QACf,CAAC;QACD,MAAM,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;QACxB,IAAI,EAAE,KAAK,GAAG;YAAE,OAAO,OAAO,CAAC,KAAK,CAAC,CAAC;QACtC,GAAG,GAAG,EAAE,CAAC;IACX,CAAC;AACH,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,KAAc;IACvC,MAAM,IAAI,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;IAC7B,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,EAAE,kBAAkB,CAAC,CAAC;IAC5C,MAAM,IAAI,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAC5E,MAAM,GAAG,GAAG,UAAU,CAAC,IAAI,CAAC,IAAI,EAAE,cAAc,CAAC,CAAC;QAChD,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,EAAE,cAAc,CAAC,EAAE,MAAM,CAAC,CAAC;QAC9D,CAAC,CAAC,EAAE,CAAC;IACP,MAAM,CAAC,GAAG;QACR,IAAI,EAAE,GAAG,CAAC,IAAI,IAAI,UAAU;QAC5B,MAAM,EAAE,8BAA8B;QACtC,SAAS,EAAE,wBAAwB;QACnC,gBAAgB,EAAE,gBAAgB;QAClC,UAAU,EAAE,eAAe;QAC3B,SAAS,EAAE,WAAW;QACtB,QAAQ,EAAE,sBAAsB;QAChC,WAAW,EAAE,wBAAwB;QACrC,GAAG,EAAE,UAAU;QACf,SAAS,EAAE,CAAC,iBAAiB,EAAE,oBAAoB,EAAE,UAAU,EAAE,UAAU,CAAC;QAC5E,IAAI,EAAE,CAAC,qBAAqB,EAAE,cAAc,EAAE,cAAc,CAAC;QAC7D,GAAG,GAAG,CAAC,IAAI;QACX,GAAG,IAAI;KACR,CAAC;IACF,OAAO,EAAE,GAAG,CAAC,EAAE,IAAI,EAAE,CAAC;AACxB,CAAC;AAED,MAAM,CAAC,MAAM,GAAG,GAAG,CAAC,GAAe,EAAE,CAAS,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC"}

package/dist/context.d.ts

@@ -0,0 +1,72 @@
+import { type CageConfig } from './config.js';
+import type { GraphSnapshot } from './graph-snapshot.js';
+import { type GraphNodeInfo } from './graph-query.js';
+export declare function buildContext(cfg: CageConfig, snapshot: GraphSnapshot, query: string, options?: {
+    depth?: number;
+    limit?: number;
+    freshness?: 'fresh-extraction' | 'displayed-snapshot';
+}): {
+    operation: "context";
+    status: "ok" | "not-found";
+    query: string;
+    selection: {
+        mode: string;
+        roots: string[];
+        candidates: import("./graph-search.js").GraphSearchHit[];
+        candidateTotal: number;
+        candidatesTruncated: boolean;
+        note: string;
+    };
+    coverage: {
+        depth: number;
+        limit: number;
+        selectedNodes: number;
+        truncated: boolean;
+        omittedByLimit: number;
+        depthBoundary: string[];
+        note: string;
+    };
+    nodes: GraphNodeInfo[];
+    relations: import("./graph-query.js").GraphRelationInfo[];
+    resources: {
+        sourceFiles: string[];
+        contracts: {
+            exists: boolean;
+            generated: boolean;
+            file: string;
+            reason: string;
+        }[];
+        migrations: {
+            directory: string;
+            note: string;
+        };
+        tests: {
+            basis: string;
+            derived: import("./derive.js").DerivedTest[];
+            project: string[];
+            derivedTotal: number;
+            truncated: boolean;
+        };
+        frontend: {
+            candidates: {
+                file: string;
+                matches: string[];
+                basis: "text-match";
+            }[];
+            total: number;
+            truncated: boolean;
+            note: string;
+        };
+    };
+    review: string[];
+    nextSteps: string[];
+    schemaVersion: 1;
+    project: string;
+    domain: string;
+    extractedAt: string;
+    freshness: "fresh-extraction" | "displayed-snapshot";
+    graphHash: string;
+    findings: import("./findings.js").Finding[];
+    limitations: string[];
+};
+export declare function formatContext(report: ReturnType<typeof buildContext>): string;

package/dist/context.js

@@ -0,0 +1,202 @@
+// 开发前的上下文包：沿声明截取一小块业务图，并列出继续阅读的源码及检查线索。
+// 这里只读取工程源码、文件名和已抽取元数据，不读取 .env，不连接业务数据库。
+import { existsSync, globSync, readFileSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { kebab, lowerFirst } from '@yss123/cage-kernel';
+import { abs } from './config.js';
+import { deriveTests } from './derive.js';
+import { selectRelatedTests } from './impact.js';
+import { graphReader, relationMarkdown, reportFooter, reportHeader, sourceText, } from './graph-query.js';
+/** 只去掉实现哈希，保留输入、状态、约束、范围等可读事实。要看完整原始属性用 inspect。 */
+function compactNode(node) {
+    const attrs = Object.fromEntries(Object.entries(node.attrs).filter(([key]) => !['src', 'invariantSrc', 'sql', 'build'].includes(key) || (key === 'sql' && node.kind === 'field')));
+    return { ...node, attrs };
+}
+function contextResources(cfg, snapshot, nodes, roots) {
+    const sourceFiles = [...new Set(nodes.flatMap((node) => (node.source ? [node.source.file] : [])))].sort();
+    const aggregates = [
+        ...new Set(nodes
+            .filter((node) => ['aggregate', 'command', 'field', 'state', 'capability'].includes(node.kind))
+            .map((node) => node.id.split('.')[0])),
+    ];
+    const contracts = aggregates.map((id) => ({
+        file: join(cfg.contracts, 'aggregates', kebab(id), 'index.ts').replace(/\\/g, '/'),
+        reason: `聚合 ${id} 的生成 API、类型和 hooks；通过 gen 更新`,
+    }));
+    if (nodes.some((node) => node.kind === 'query'))
+        contracts.push({
+            file: join(cfg.contracts, 'queries/index.ts').replace(/\\/g, '/'),
+            reason: '生成查询 API；通过 gen 更新',
+        });
+    const testFiles = globSync(['packages/**/src/**/*.{test,spec}.{ts,tsx}', 'apps/api/**/*.{test,spec}.{ts,tsx}'], {
+        cwd: cfg.root,
+        exclude: ['**/node_modules/**', '**/dist/**'],
+    }).sort();
+    // 所属聚合只是附带资料时，不把该聚合的全部派生测试都塞进来；命令按 subject 挑选。
+    const subjects = new Set(nodes.filter((node) => node.kind !== 'aggregate' || roots.includes(node.key)).map((node) => node.id));
+    const tests = selectRelatedTests(subjects, deriveTests(cfg, snapshot.graph).tests, testFiles.map((file) => abs(cfg, file)));
+    const terms = [
+        ...new Set([
+            ...aggregates.flatMap((id) => [id, lowerFirst(id)]),
+            ...nodes.filter((node) => node.kind === 'query').map((node) => node.id),
+        ]),
+    ];
+    const frontend = existsSync(abs(cfg, cfg.web))
+        ? globSync('src/**/*.{ts,tsx}', {
+            cwd: abs(cfg, cfg.web),
+            exclude: ['**/node_modules/**', '**/dist/**'],
+        })
+            .sort()
+            .flatMap((file) => {
+            const text = readFileSync(abs(cfg, join(cfg.web, file)), 'utf8');
+            const matches = terms.filter((term) => text.includes(term));
+            return matches.length
+                ? [{ file: join(cfg.web, file).replace(/\\/g, '/'), matches, basis: 'text-match' }]
+                : [];
+        })
+        : [];
+    return {
+        sourceFiles,
+        contracts: contracts.map((ref) => ({ ...ref, exists: existsSync(abs(cfg, ref.file)), generated: true })),
+        migrations: {
+            directory: cfg.migrations,
+            note: '字段/关联存储变化时生成并审查新迁移；不改写已执行迁移。本命令不比较真实数据库。',
+        },
+        tests: {
+            basis: '派生测试按 subject 选择，项目测试按源码名称匹配；只是候选，未执行。',
+            derived: tests.derived.slice(0, 20),
+            project: tests.project.map((file) => relative(cfg.root, file).replace(/\\/g, '/')),
+            derivedTotal: tests.derived.length,
+            truncated: tests.derived.length > 20,
+        },
+        frontend: {
+            candidates: frontend.slice(0, 12),
+            total: frontend.length,
+            truncated: frontend.length > 12,
+            note: '仅按聚合/查询的代码名称查找引用，不是完整的前端依赖分析。',
+        },
+    };
+}
+export function buildContext(cfg, snapshot, query, options = {}) {
+    const reader = graphReader(snapshot, options.freshness);
+    const depth = options.depth ?? 3, limit = options.limit ?? 40;
+    const resolution = reader.resolve(query);
+    const candidates = reader.search(query);
+    // 完整 key / 唯一名称可精确定位；其余用得分接近的最多三个候选作为入口，报告中
+    // 明示选择依据。用户可复制某个 key 再请求上下文，不让关键词匹配冒充需求确认。
+    const roots = resolution.status === 'ok'
+        ? resolution.candidates.map((hit) => hit.key)
+        : candidates
+            .filter((hit) => hit.score >= (candidates[0]?.score ?? 0) * 0.8)
+            .slice(0, Math.min(3, limit))
+            .map((hit) => hit.key);
+    const selected = new Set(roots);
+    const rootSet = new Set(roots);
+    const queue = roots.map((key) => ({ key, distance: 0 }));
+    const omitted = new Set();
+    // 实际业务链优先于归属和字段结构，避免聚合这个高连接度节点挤掉取消→释放链。
+    const edges = [...reader.model.edges].sort((a, b) => Number(a.derived) - Number(b.derived) || Number(a.kind === 'field') - Number(b.kind === 'field'));
+    const participants = (edge) => [
+        edge.from,
+        edge.to,
+        ...(edge.kind === 'transition' && reader.byKey.has(`command:${edge.via}`) ? [`command:${edge.via}`] : []),
+    ];
+    for (const current of queue) {
+        for (const edge of edges) {
+            const keys = participants(edge);
+            if (!keys.includes(current.key))
+                continue;
+            for (const key of keys) {
+                if (selected.has(key))
+                    continue;
+                if (current.distance >= depth)
+                    continue;
+                if (selected.size >= limit) {
+                    omitted.add(key);
+                    continue;
+                }
+                selected.add(key);
+                const node = reader.byKey.get(key);
+                // 读依赖指向的表、命令所属对象、状态和字段作为阅读资料收进来；只有业务
+                // 行为继续扩展，避免经“所属采购单”顺带把全部用户/部门和无关命令都展开。
+                if (rootSet.has(key) || !['aggregate', 'field', 'state', 'entry', 'capability'].includes(node.kind))
+                    queue.push({ key, distance: current.distance + 1 });
+            }
+        }
+    }
+    const boundary = queue
+        .filter((current) => current.distance >= depth &&
+        edges.some((edge) => {
+            const keys = participants(edge);
+            return keys.includes(current.key) && keys.some((key) => !selected.has(key));
+        }))
+        .map((current) => current.key);
+    const nodes = [...selected].map((key) => compactNode(reader.nodeInfo(reader.byKey.get(key))));
+    const relations = reader.model.edges
+        .filter((edge) => participants(edge).every((key) => selected.has(key)))
+        .map(reader.relationInfo);
+    const review = [];
+    if (nodes.some((n) => n.kind === 'command' || n.kind === 'capability'))
+        review.push('涉及命令能力、数据范围或额度时复核管理员授权；新增能力不自动授予生产角色。');
+    if (nodes.some((n) => n.kind === 'approval'))
+        review.push('复核 start/cancelOn、审批分支、选人、结论命令和额度约束；取消审批与释放资源分别检查。');
+    if (nodes.some((n) => n.kind === 'reaction' && (n.attrs.acquires || n.attrs.releases)))
+        review.push('资源获取/释放标签只证明声明配对；阅读 map 的执行条件、null 返回以及同事务/异步方式。');
+    if (nodes.some((n) => n.kind === 'event'))
+        review.push('已部署事件保持兼容；核对载荷字段和所有订阅方。');
+    if (nodes.some((n) => ['connector', 'outbound', 'inbound'].includes(n.kind)))
+        review.push('复核外部请求/回调协议、字段映射和幂等；fake 或声明通过不等于真实外部联调通过。');
+    return {
+        ...reader.meta,
+        operation: 'context',
+        status: roots.length ? 'ok' : 'not-found',
+        query,
+        selection: {
+            mode: resolution.status === 'ok' ? 'exact' : 'keyword-candidates',
+            roots,
+            candidates: candidates.slice(0, 8),
+            candidateTotal: candidates.length,
+            candidatesTruncated: candidates.length > 8,
+            note: resolution.status === 'ok'
+                ? '精确节点入口。'
+                : '按名称与中文词片段匹配的候选入口；请核对需求，可复制完整 key 缩小到单个节点。',
+        },
+        coverage: {
+            depth,
+            limit,
+            selectedNodes: nodes.length,
+            truncated: omitted.size > 0,
+            omittedByLimit: omitted.size,
+            depthBoundary: boundary,
+            note: '仅输出相关子图；附带的表/字段/状态不继续展开。边界和截断不代表外部没有其他依赖。',
+        },
+        nodes,
+        relations,
+        resources: contextResources(cfg, snapshot, nodes, roots),
+        review,
+        nextSteps: [
+            '先按源码位置阅读实现，确认候选入口符合需求；不要仅凭箭头推断条件与运行结果。',
+            '改动前 cage analyze，并将 .cage/ontology.json 另存为 .cage/before-change.json；后续抽取会覆盖当前图。',
+            '修改后运行 cage check、cage gen，审查契约/迁移，再 cage impact --base-file .cage/before-change.json。',
+            '阅读候选测试，按实际风险运行必要验证；报告通过、跳过、未执行项。',
+        ],
+    };
+}
+export function formatContext(report) {
+    const lines = reportHeader(report, 'Cage 业务开发上下文');
+    lines.push(`需求/节点：${report.query}`, '', report.selection.note, '', '## 候选入口与匹配依据', '');
+    for (const hit of report.selection.candidates)
+        lines.push(`- ${report.selection.roots.includes(hit.key) ? '【本次入口】' : '候选'} **${hit.label}** \`${hit.key}\`（得分 ${hit.score}）`, `  - ${hit.matches.map((m) => `${m.field}=${m.value}，命中 ${m.terms.join('、')}`).join('；')}`);
+    if (!report.nodes.length)
+        lines.push('未找到相关声明；尝试更短的中文词或代码标识。空白模板不会注册参考资料中的采购业务。');
+    lines.push('', '## 子图范围', '', `深度 ${report.coverage.depth}，节点 ${report.nodes.length}/${report.coverage.limit}；${report.coverage.truncated ? '已截断，请提高 --limit 或缩小入口' : '节点上限未截断'}。`, report.coverage.note, ...(report.coverage.depthBoundary.length
+        ? [`深度边界：${report.coverage.depthBoundary.join('、')}；需要时提高 --depth。`]
+        : []), '', '## 业务事实与源码', '');
+    for (const node of report.nodes)
+        lines.push(`### ${node.label} · ${node.key}`, '', `源码：${sourceText(node.source)}`, '', '```json', JSON.stringify(node.attrs, null, 2), '```', '');
+    lines.push('## 关系：为什么连接、有什么用', '', ...report.relations.flatMap(relationMarkdown), '', '## 继续阅读的文件', '', ...report.resources.sourceFiles.map((file) => `- 源码：${file}`), ...report.resources.contracts.map((ref) => `- 契约：${ref.file}${ref.exists ? '' : '（尚未生成）'}；${ref.reason}`), ...report.resources.frontend.candidates.map((ref) => `- 前端候选：${ref.file}；文本命中 ${ref.matches.join('、')}`), report.resources.frontend.note, ...(report.resources.frontend.truncated ? ['前端候选已截断。'] : []), '', `迁移目录：${report.resources.migrations.directory}；${report.resources.migrations.note}`, '', '## 验证候选与审查提示', '', report.resources.tests.basis, ...report.resources.tests.project.map((file) => `- 项目测试候选：${file}`), ...report.resources.tests.derived.map((test) => `- 派生测试候选：${test.file} · ${test.name}`), ...(report.resources.tests.truncated
+        ? [`派生测试候选共 ${report.resources.tests.derivedTotal} 项，仅列前 20 项。`]
+        : []), ...report.review.map((item) => `- ${item}`), '', '## 接下来', '', ...report.nextSteps.map((step, i) => `${i + 1}. ${step}`));
+    return [...lines, ...reportFooter(report)].join('\n');
+}
+//# sourceMappingURL=context.js.map

package/dist/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA,wCAAwC;AACxC,0CAA0C;AAC1C,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAC7D,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAAE,GAAG,EAAmB,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAGjD,OAAO,EACL,WAAW,EACX,gBAAgB,EAChB,YAAY,EACZ,YAAY,EACZ,UAAU,GAEX,MAAM,kBAAkB,CAAC;AAE1B,oDAAoD;AACpD,SAAS,WAAW,CAAC,IAAmB;IACtC,MAAM,KAAK,GAAG,MAAM,CAAC,WAAW,CAC9B,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,CAC/B,CAAC,CAAC,GAAG,CAAC,EAAE,EAAE,CACR,CAAC,CAAC,KAAK,EAAE,cAAc,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,KAAK,KAAK,IAAI,IAAI,CAAC,IAAI,KAAK,OAAO,CAAC,CACrG,CACF,CAAC;IACF,OAAO,EAAE,GAAG,IAAI,EAAE,KAAK,EAAE,CAAC;AAC5B,CAAC;AAED,SAAS,gBAAgB,CAAC,GAAe,EAAE,QAAuB,EAAE,KAAsB,EAAE,KAAe;IACzG,MAAM,WAAW,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAC1G,MAAM,UAAU,GAAG;QACjB,GAAG,IAAI,GAAG,CACR,KAAK;aACF,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,WAAW,EAAE,SAAS,EAAE,OAAO,EAAE,OAAO,EAAE,YAAY,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;aAC9F,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CACxC;KACF,CAAC;IACF,MAAM,SAAS,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;QACxC,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,YAAY,EAAE,KAAK,CAAC,EAAE,CAAC,EAAE,UAAU,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC;QAClF,MAAM,EAAE,MAAM,EAAE,8BAA8B;KAC/C,CAAC,CAAC,CAAC;IACJ,IAAI,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,KAAK,OAAO,CAAC;QAC7C,SAAS,CAAC,IAAI,CAAC;YACb,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,kBAAkB,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC;YACjE,MAAM,EAAE,oBAAoB;SAC7B,CAAC,CAAC;IACL,MAAM,SAAS,GAAG,QAAQ,CACxB,CAAC,2CAA2C,EAAE,oCAAoC,CAAC,EACnF;QACE,GAAG,EAAE,GAAG,CAAC,IAAI;QACb,OAAO,EAAE,CAAC,oBAAoB,EAAE,YAAY,CAAC;KAC9C,CACF,CAAC,IAAI,EAAE,CAAC;IACT,+CAA+C;IAC/C,MAAM,QAAQ,GAAG,IAAI,GAAG,CACtB,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,KAAK,WAAW,IAAI,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,CACrG,CAAC;IACF,MAAM,KAAK,GAAG,kBAAkB,CAC9B,QAAQ,EACR,WAAW,CAAC,GAAG,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAC,KAAK,EACtC,SAAS,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,CACxC,CAAC;IACF,MAAM,KAAK,GAAG;QACZ,GAAG,IAAI,GAAG,CAAC;YACT,GAAG,UAAU,CAAC,OAAO,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC;YACnD,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,KAAK,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;SACxE,CAAC;KACH,CAAC;IACF,MAAM,QAAQ,GAAG,UAAU,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC;QAC5C,CAAC,CAAC,QAAQ,CAAC,mBAAmB,EAAE;YAC5B,GAAG,EAAE,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,CAAC;YACtB,OAAO,EAAE,CAAC,oBAAoB,EAAE,YAAY,CAAC;SAC9C,CAAC;aACC,IAAI,EAAE;aACN,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE;YAChB,MAAM,IAAI,GAAG,YAAY,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;YACjE,MAAM,OAAO,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC;YAC5D,OAAO,OAAO,CAAC,MAAM;gBACnB,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,YAAqB,EAAE,CAAC;gBAC5F,CAAC,CAAC,EAAE,CAAC;QACT,CAAC,CAAC;QACN,CAAC,CAAC,EAAE,CAAC;IACP,OAAO;QACL,WAAW;QACX,SAAS,EAAE,SAAS,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,GAAG,EAAE,MAAM,EAAE,UAAU,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACxG,UAAU,EAAE;YACV,SAAS,EAAE,GAAG,CAAC,UAAU;YACzB,IAAI,EAAE,0CAA0C;SACjD;QACD,KAAK,EAAE;YACL,KAAK,EAAE,wCAAwC;YAC/C,OAAO,EAAE,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC;YACnC,OAAO,EAAE,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;YAClF,YAAY,EAAE,KAAK,CAAC,OAAO,CAAC,MAAM;YAClC,SAAS,EAAE,KAAK,CAAC,OAAO,CAAC,MAAM,GAAG,EAAE;SACrC;QACD,QAAQ,EAAE;YACR,UAAU,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC;YACjC,KAAK,EAAE,QAAQ,CAAC,MAAM;YACtB,SAAS,EAAE,QAAQ,CAAC,MAAM,GAAG,EAAE;YAC/B,IAAI,EAAE,+BAA+B;SACtC;KACF,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,YAAY,CAC1B,GAAe,EACf,QAAuB,EACvB,KAAa,EACb,UAAqG,EAAE;IAEvG,MAAM,MAAM,GAAG,WAAW,CAAC,QAAQ,EAAE,OAAO,CAAC,SAAS,CAAC,CAAC;IACxD,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,CAAC,EAC9B,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,EAAE,CAAC;IAC9B,MAAM,UAAU,GAAG,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IACzC,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACxC,4CAA4C;IAC5C,2CAA2C;IAC3C,MAAM,KAAK,GACT,UAAU,CAAC,MAAM,KAAK,IAAI;QACxB,CAAC,CAAC,UAAU,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC;QAC7C,CAAC,CAAC,UAAU;aACP,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,KAAK,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,KAAK,IAAI,CAAC,CAAC,GAAG,GAAG,CAAC;aAC/D,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;aAC5B,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC/B,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC;IAChC,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC;IAC/B,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IACzD,MAAM,OAAO,GAAG,IAAI,GAAG,EAAU,CAAC;IAClC,wCAAwC;IACxC,MAAM,KAAK,GAAG,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,IAAI,CACxC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CACP,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,MAAM,CAAC,CAAC,CAAC,IAAI,KAAK,OAAO,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,IAAI,KAAK,OAAO,CAAC,CACnG,CAAC;IACF,MAAM,YAAY,GAAG,CAAC,IAAc,EAAE,EAAE,CAAC;QACvC,IAAI,CAAC,IAAI;QACT,IAAI,CAAC,EAAE;QACP,GAAG,CAAC,IAAI,CAAC,IAAI,KAAK,YAAY,IAAI,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,WAAW,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,WAAW,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;KAC1G,CAAC;IACF,KAAK,MAAM,OAAO,IAAI,KAAK,EAAE,CAAC;QAC5B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,MAAM,IAAI,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;YAChC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC;gBAAE,SAAS;YAC1C,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;gBACvB,IAAI,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC;oBAAE,SAAS;gBAChC,IAAI,OAAO,CAAC,QAAQ,IAAI,KAAK;oBAAE,SAAS;gBACxC,IAAI,QAAQ,CAAC,IAAI,IAAI,KAAK,EAAE,CAAC;oBAC3B,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;oBACjB,SAAS;gBACX,CAAC;gBACD,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;gBAClB,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAE,CAAC;gBACpC,qCAAqC;gBACrC,uCAAuC;gBACvC,IAAI,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,YAAY,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC;oBACjG,KAAK,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,GAAG,CAAC,EAAE,CAAC,CAAC;YACxD,CAAC;QACH,CAAC;IACH,CAAC;IACD,MAAM,QAAQ,GAAG,KAAK;SACnB,MAAM,CACL,CAAC,OAAO,EAAE,EAAE,CACV,OAAO,CAAC,QAAQ,IAAI,KAAK;QACzB,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE;YAClB,MAAM,IAAI,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;YAChC,OAAO,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;QAC9E,CAAC,CAAC,CACL;SACA,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACjC,MAAM,KAAK,GAAG,CAAC,GAAG,QAAQ,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,WAAW,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAE,CAAC,CAAC,CAAC,CAAC;IAC/F,MAAM,SAAS,GAAG,MAAM,CAAC,KAAK,CAAC,KAAK;SACjC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;SACtE,GAAG,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;IAC5B,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,IAAI,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,SAAS,IAAI,CAAC,CAAC,IAAI,KAAK,YAAY,CAAC;QACpE,MAAM,CAAC,IAAI,CAAC,uCAAuC,CAAC,CAAC;IACvD,IAAI,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,UAAU,CAAC;QAC1C,MAAM,CAAC,IAAI,CAAC,oDAAoD,CAAC,CAAC;IACpE,IAAI,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,UAAU,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,IAAI,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;QACpF,MAAM,CAAC,IAAI,CAAC,kDAAkD,CAAC,CAAC;IAClE,IAAI,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,OAAO,CAAC;QAAE,MAAM,CAAC,IAAI,CAAC,yBAAyB,CAAC,CAAC;IAClF,IAAI,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,WAAW,EAAE,UAAU,EAAE,SAAS,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QAC1E,MAAM,CAAC,IAAI,CAAC,4CAA4C,CAAC,CAAC;IAC5D,OAAO;QACL,GAAG,MAAM,CAAC,IAAI;QACd,SAAS,EAAE,SAAkB;QAC7B,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC,CAAE,IAAc,CAAC,CAAC,CAAE,WAAqB;QAC/D,KAAK;QACL,SAAS,EAAE;YACT,IAAI,EAAE,UAAU,CAAC,MAAM,KAAK,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,oBAAoB;YACjE,KAAK;YACL,UAAU,EAAE,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC;YAClC,cAAc,EAAE,UAAU,CAAC,MAAM;YACjC,mBAAmB,EAAE,UAAU,CAAC,MAAM,GAAG,CAAC;YAC1C,IAAI,EACF,UAAU,CAAC,MAAM,KAAK,IAAI;gBACxB,CAAC,CAAC,SAAS;gBACX,CAAC,CAAC,2CAA2C;SAClD;QACD,QAAQ,EAAE;YACR,KAAK;YACL,KAAK;YACL,aAAa,EAAE,KAAK,CAAC,MAAM;YAC3B,SAAS,EAAE,OAAO,CAAC,IAAI,GAAG,CAAC;YAC3B,cAAc,EAAE,OAAO,CAAC,IAAI;YAC5B,aAAa,EAAE,QAAQ;YACvB,IAAI,EAAE,2CAA2C;SAClD;QACD,KAAK;QACL,SAAS;QACT,SAAS,EAAE,gBAAgB,CAAC,GAAG,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,CAAC;QACxD,MAAM;QACN,SAAS,EAAE;YACT,wCAAwC;YACxC,kFAAkF;YAClF,uFAAuF;YACvF,kCAAkC;SACnC;KACF,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,MAAuC;IACnE,MAAM,KAAK,GAAG,YAAY,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IACnD,KAAK,CAAC,IAAI,CAAC,SAAS,MAAM,CAAC,KAAK,EAAE,EAAE,EAAE,EAAE,MAAM,CAAC,SAAS,CAAC,IAAI,EAAE,EAAE,EAAE,cAAc,EAAE,EAAE,CAAC,CAAC;IACvF,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,SAAS,CAAC,UAAU;QAC3C,KAAK,CAAC,IAAI,CACR,KAAK,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,MAAM,GAAG,CAAC,KAAK,QAAQ,GAAG,CAAC,GAAG,SAAS,GAAG,CAAC,KAAK,GAAG,EAClH,OAAO,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAC3F,CAAC;IACJ,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM;QACtB,KAAK,CAAC,IAAI,CAAC,2CAA2C,CAAC,CAAC;IAC1D,KAAK,CAAC,IAAI,CACR,EAAE,EACF,SAAS,EACT,EAAE,EACF,MAAM,MAAM,CAAC,QAAQ,CAAC,KAAK,OAAO,MAAM,CAAC,KAAK,CAAC,MAAM,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,IAAI,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC,uBAAuB,CAAC,CAAC,CAAC,SAAS,GAAG,EACpJ,MAAM,CAAC,QAAQ,CAAC,IAAI,EACpB,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,aAAa,CAAC,MAAM;QACtC,CAAC,CAAC,CAAC,QAAQ,MAAM,CAAC,QAAQ,CAAC,aAAa,CAAC,IAAI,CAAC,GAAG,CAAC,iBAAiB,CAAC;QACpE,CAAC,CAAC,EAAE,CAAC,EACP,EAAE,EACF,YAAY,EACZ,EAAE,CACH,CAAC;IACF,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,KAAK;QAC7B,KAAK,CAAC,IAAI,CACR,OAAO,IAAI,CAAC,KAAK,MAAM,IAAI,CAAC,GAAG,EAAE,EACjC,EAAE,EACF,MAAM,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,EAC/B,EAAE,EACF,SAAS,EACT,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,EACnC,KAAK,EACL,EAAE,CACH,CAAC;IACJ,KAAK,CAAC,IAAI,CACR,kBAAkB,EAClB,EAAE,EACF,GAAG,MAAM,CAAC,SAAS,CAAC,OAAO,CAAC,gBAAgB,CAAC,EAC7C,EAAE,EACF,YAAY,EACZ,EAAE,EACF,GAAG,MAAM,CAAC,SAAS,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,QAAQ,IAAI,EAAE,CAAC,EAC7D,GAAG,MAAM,CAAC,SAAS,CAAC,SAAS,CAAC,GAAG,CAC/B,CAAC,GAAG,EAAE,EAAE,CAAC,QAAQ,GAAG,CAAC,IAAI,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,IAAI,GAAG,CAAC,MAAM,EAAE,CACvE,EACD,GAAG,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,UAAU,CAAC,GAAG,CACzC,CAAC,GAAG,EAAE,EAAE,CAAC,UAAU,GAAG,CAAC,IAAI,SAAS,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAC5D,EACD,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,EAC9B,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,EAC5D,EAAE,EACF,QAAQ,MAAM,CAAC,SAAS,CAAC,UAAU,CAAC,SAAS,IAAI,MAAM,CAAC,SAAS,CAAC,UAAU,CAAC,IAAI,EAAE,EACnF,EAAE,EACF,cAAc,EACd,EAAE,EACF,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,KAAK,EAC5B,GAAG,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,YAAY,IAAI,EAAE,CAAC,EACnE,GAAG,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,YAAY,IAAI,CAAC,IAAI,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC,EACvF,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,SAAS;QAClC,CAAC,CAAC,CAAC,WAAW,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,YAAY,cAAc,CAAC;QAChE,CAAC,CAAC,EAAE,CAAC,EACP,GAAG,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,KAAK,IAAI,EAAE,CAAC,EAC3C,EAAE,EACF,QAAQ,EACR,EAAE,EACF,GAAG,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,IAAI,EAAE,CAAC,CAC1D,CAAC;IACF,OAAO,CAAC,GAAG,KAAK,EAAE,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACxD,CAAC"}

package/dist/create-prompt.d.ts

@@ -0,0 +1,5 @@
+import { type AppTemplate } from './create.js';
+export declare function chooseApp(target?: string, template?: string): Promise<{
+    target: string;
+    template: AppTemplate;
+} | null>;

package/dist/create-prompt.js

@@ -0,0 +1,50 @@
+// 交互只收集创建选项，所有问题结束后才复制文件；Ctrl+C 不会留下半个项目。
+import { cancel, intro, isCancel, select, text } from '@clack/prompts';
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { appTemplates, isAppTemplate } from './create.js';
+export async function chooseApp(target, template) {
+    if (template !== undefined && !isAppTemplate(template))
+        throw new Error('[CAGE-CREATE-001] --template 只能是 blank 或 purchase');
+    // 管道和 CI 没有可操作的终端，不隐式选择业务模板，也不让安装任务挂在提示上。
+    if ((!target || !template) && (!process.stdin.isTTY || !process.stdout.isTTY))
+        throw new Error('[CAGE-CREATE-001] 非交互终端请指定目录和模板，例如：create-cage-app my-app --template blank');
+    if (!target || !template)
+        intro('创建 Cage 业务应用');
+    if (!target) {
+        const answer = await text({
+            message: '项目目录',
+            placeholder: 'my-cage-app',
+            defaultValue: 'my-cage-app',
+            validate: (value) => {
+                if (!value?.trim())
+                    return '请输入项目目录';
+                if (existsSync(resolve(value.trim())))
+                    return '目标路径已存在，请选择新目录';
+            },
+        });
+        if (isCancel(answer)) {
+            cancel('已取消创建');
+            return null;
+        }
+        target = answer.trim();
+    }
+    if (!template) {
+        const answer = await select({
+            message: '选择项目模板（↑↓ 选择，Enter 确认）',
+            initialValue: 'blank',
+            options: Object.entries(appTemplates).map(([value, option]) => ({
+                value: value,
+                label: option.label,
+                hint: option.hint,
+            })),
+        });
+        if (isCancel(answer)) {
+            cancel('已取消创建');
+            return null;
+        }
+        template = answer;
+    }
+    return { target, template: template };
+}
+//# sourceMappingURL=create-prompt.js.map

package/dist/create-prompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-prompt.js","sourceRoot":"","sources":["../src/create-prompt.ts"],"names":[],"mappings":"AAAA,0CAA0C;AAC1C,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AACvE,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,YAAY,EAAE,aAAa,EAAoB,MAAM,aAAa,CAAC;AAE5E,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,MAAe,EACf,QAAiB;IAEjB,IAAI,QAAQ,KAAK,SAAS,IAAI,CAAC,aAAa,CAAC,QAAQ,CAAC;QACpD,MAAM,IAAI,KAAK,CAAC,mDAAmD,CAAC,CAAC;IAEvE,0CAA0C;IAC1C,IAAI,CAAC,CAAC,MAAM,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC;QAC3E,MAAM,IAAI,KAAK,CACb,4EAA4E,CAC7E,CAAC;IAEJ,IAAI,CAAC,MAAM,IAAI,CAAC,QAAQ;QAAE,KAAK,CAAC,cAAc,CAAC,CAAC;IAChD,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC;YACxB,OAAO,EAAE,MAAM;YACf,WAAW,EAAE,aAAa;YAC1B,YAAY,EAAE,aAAa;YAC3B,QAAQ,EAAE,CAAC,KAAK,EAAE,EAAE;gBAClB,IAAI,CAAC,KAAK,EAAE,IAAI,EAAE;oBAAE,OAAO,SAAS,CAAC;gBACrC,IAAI,UAAU,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;oBAAE,OAAO,gBAAgB,CAAC;YACjE,CAAC;SACF,CAAC,CAAC;QACH,IAAI,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;YACrB,MAAM,CAAC,OAAO,CAAC,CAAC;YAChB,OAAO,IAAI,CAAC;QACd,CAAC;QACD,MAAM,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC;IACzB,CAAC;IACD,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,MAAM,MAAM,GAAG,MAAM,MAAM,CAAc;YACvC,OAAO,EAAE,wBAAwB;YACjC,YAAY,EAAE,OAAO;YACrB,OAAO,EAAE,MAAM,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,EAAE,MAAM,CAAC,EAAE,EAAE,CAAC,CAAC;gBAC9D,KAAK,EAAE,KAAoB;gBAC3B,KAAK,EAAE,MAAM,CAAC,KAAK;gBACnB,IAAI,EAAE,MAAM,CAAC,IAAI;aAClB,CAAC,CAAC;SACJ,CAAC,CAAC;QACH,IAAI,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;YACrB,MAAM,CAAC,OAAO,CAAC,CAAC;YAChB,OAAO,IAAI,CAAC;QACd,CAAC;QACD,QAAQ,GAAG,MAAM,CAAC;IACpB,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAuB,EAAE,CAAC;AACvD,CAAC"}

package/dist/create.d.ts

@@ -1 +1,18 @@
-export declare function createApp(target: string, frameworkPath?: string): string;
+/** 两种模板共用框架基础能力，只让用户选择是否带业务演示。目录名与命令参数分开，
+ * 保留已有 templates/app 作为采购模板，避免改写它已分发的迁移历史。 */
+export declare const appTemplates: {
+    readonly blank: {
+        readonly directory: "blank";
+        readonly label: "空白业务项目";
+        readonly hint: "保留登录、权限和系统管理，从自己的业务开始";
+    };
+    readonly purchase: {
+        readonly directory: "app";
+        readonly label: "采购示例项目";
+        readonly hint: "包含采购单、库存、审批和 fake ERP 完整链路";
+    };
+};
+export type AppTemplate = keyof typeof appTemplates;
+export declare function isAppTemplate(value: string): value is AppTemplate;
+/** 创建本身不负责交互，供 CLI、自动化和测试复用。第三个参数保留原有本地框架路径调用方式。 */
+export declare function createApp(target: string, frameworkPath?: string, template?: AppTemplate): string;

package/dist/create.js

@@ -1,29 +1,46 @@
-import { cpSync, existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { cpSync, existsSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
 import { basename, dirname, join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { VERSION, projectManifests } from './upgrade.js';
-export function createApp(target, frameworkPath) {
+/** 两种模板共用框架基础能力，只让用户选择是否带业务演示。目录名与命令参数分开，
+ * 保留已有 templates/app 作为采购模板，避免改写它已分发的迁移历史。 */
+export const appTemplates = {
+    blank: { directory: 'blank', label: '空白业务项目', hint: '保留登录、权限和系统管理，从自己的业务开始' },
+    purchase: { directory: 'app', label: '采购示例项目', hint: '包含采购单、库存、审批和 fake ERP 完整链路' },
+};
+export function isAppTemplate(value) {
+    return Object.hasOwn(appTemplates, value);
+}
+/** 创建本身不负责交互，供 CLI、自动化和测试复用。第三个参数保留原有本地框架路径调用方式。 */
+export function createApp(target, frameworkPath, template = 'blank') {
+    if (!isAppTemplate(template))
+        throw new Error('[CAGE-CREATE-001] --template 只能是 blank 或 purchase');
     const root = resolve(target);
     if (existsSync(root))
         throw new Error('[CAGE-CREATE-001] 目标路径已存在，请选择新目录');
     const here = dirname(fileURLToPath(import.meta.url));
-    const template = [resolve(here, '../templates/app'), resolve(here, '../../../templates/app')].find(existsSync);
-    if (!template)
-        throw new Error('[CAGE-CREATE-001] CLI 发布包缺少模板');
-    cpSync(template, root, {
+    const directory = appTemplates[template].directory;
+    const source = [
+        resolve(here, '../templates', directory),
+        resolve(here, '../../../templates', directory),
+    ].find(existsSync);
+    if (!source)
+        throw new Error(`[CAGE-CREATE-001] CLI 发布包缺少 ${template} 模板`);
+    cpSync(source, root, {
         recursive: true,
         filter: (p) => {
             // 安装后的模板本身就在 node_modules 中，只排除模板内部的运行目录。
             // 若检查绝对路径，npm 安装场景下连模板根目录都会被过滤，产生空项目。
-            const local = relative(template, p);
-            return !/(^|[\\/])(node_modules|dist|\.cage|generated)([\\/]|$)/.test(local) &&
-                (!/^\.env(?:\..+)?$/.test(basename(p)) || basename(p) === '.env.example');
+            const local = relative(source, p);
+            return (!/(^|[\\/])(node_modules|dist|\.cage|generated)([\\/]|$)/.test(local) &&
+                (!/^\.env(?:\..+)?$/.test(basename(p)) || basename(p) === '.env.example'));
         },
     });
-    // 报错链接在新项目中也能直接打开，不要求用户另行克隆框架文档。
-    const errors = [resolve(here, '../managed/errors'), resolve(here, '../../../docs/errors')].find(existsSync);
-    if (errors)
-        cpSync(errors, join(root, 'docs/errors'), { recursive: true });
+    // npm 不分发 .gitignore，因此模板保存为 _gitignore。创建后恢复文件名，
+    // 使源码创建和 npm 创建都能忽略 .env、依赖和运行缓存。
+    renameSync(join(root, '_gitignore'), join(root, '.gitignore'));
+    // 模板本身包含所有学习资料。这里不另找框架仓库补文档，
+    // 确保本地试用与从 npm 安装得到的是同一份完整业务项目。
     for (const path of projectManifests(root)) {
         const p = JSON.parse(readFileSync(path, 'utf8'));
         // 发布后使用统一版本号；源码试用用 link 指向已构建的本地框架，不要求先发 npm。

package/dist/create.js.map

@@ -1 +1 @@
-{"version":3,"file":"create.js","sourceRoot":"","sources":["../src/create.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"create.js","sourceRoot":"","sources":["../src/create.ts"],"names":[],"mappings":"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"}