@epoint-testtech/ep-stage-skill 0.0.3-alpha.1

package/dist/src/context/stage-context.d.ts

@@ -0,0 +1,63 @@
+import type { ObservableStagePayload } from '../contracts/observable-chain.js';
+export type StageContextMode = 'default' | 'glue';
+export type StageContext = {
+    projectName: string;
+    projectDir: string;
+    mode: StageContextMode;
+    envPath: string;
+    envFilePath: string;
+    knowledgeRoot?: string;
+    codeListPaths: string[];
+    stageContextPath?: string;
+};
+export type ProjectIndexEntry = {
+    projectName: string;
+    projectDir: string;
+    mode: StageContextMode;
+    envPath?: string;
+    knowledgeRoot?: string;
+    codeListPaths?: string[];
+    stageContextPath?: string;
+};
+export type ProjectIndex = {
+    version?: 1;
+    projects: ProjectIndexEntry[];
+};
+export type ResolveStageContextInput = {
+    stageContextPath?: string;
+    projectDir?: string;
+    cwd?: string;
+    codeListPath?: string;
+    homeDir?: string;
+};
+export type ResolveStageContextResult = {
+    context: StageContext;
+    trace: ObservableStagePayload;
+};
+/**
+ * 读取项目级 stage-context.md，并将相对路径归一到项目目录。
+ *
+ * @param stageContextPath - stage-context.md 文件路径。
+ * @returns 归一化后的项目上下文。
+ * @throws 当 frontmatter 缺少必要字段或格式不合法时抛出错误。
+ */
+export declare function readStageContext(stageContextPath: string): StageContext;
+/**
+ * 写入用户级 ep-stage 项目索引。
+ *
+ * @param input - HOME 目录和项目列表。
+ * @returns 写入后的索引文件路径。
+ */
+export declare function writeProjectIndex(input: {
+    homeDir?: string;
+    projects: ProjectIndexEntry[];
+}): string;
+/**
+ * 按固定优先级解析 ep-stage 项目上下文，并返回可审阅 trace。
+ *
+ * @param input - 显式路径、当前目录、code_list 路径和可选 HOME。
+ * @returns 解析出的项目上下文与 context-resolution trace。
+ * @throws 当无法定位任何上下文来源时抛出错误。
+ */
+export declare function resolveStageContext(input: ResolveStageContextInput): ResolveStageContextResult;
+//# sourceMappingURL=stage-context.d.ts.map

package/dist/src/context/stage-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stage-context.d.ts","sourceRoot":"","sources":["../../../src/context/stage-context.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,kCAAkC,CAAC;AAE/E,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,MAAM,CAAC;AAElD,MAAM,MAAM,YAAY,GAAG;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,gBAAgB,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,gBAAgB,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG;IACzB,OAAO,CAAC,EAAE,CAAC,CAAC;IACZ,QAAQ,EAAE,iBAAiB,EAAE,CAAC;CAC/B,CAAC;AAEF,MAAM,MAAM,wBAAwB,GAAG;IACrC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,yBAAyB,GAAG;IACtC,OAAO,EAAE,YAAY,CAAC;IACtB,KAAK,EAAE,sBAAsB,CAAC;CAC/B,CAAC;AAWF;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,gBAAgB,EAAE,MAAM,GAAG,YAAY,CAqBvE;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE;IACvC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,iBAAiB,EAAE,CAAC;CAC/B,GAAG,MAAM,CAST;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,wBAAwB,GAAG,yBAAyB,CA6D9F"}

package/dist/src/context/stage-context.js

@@ -0,0 +1,297 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import JSON5 from 'json5';
+import YAML from 'yaml';
+/**
+ * 读取项目级 stage-context.md，并将相对路径归一到项目目录。
+ *
+ * @param stageContextPath - stage-context.md 文件路径。
+ * @returns 归一化后的项目上下文。
+ * @throws 当 frontmatter 缺少必要字段或格式不合法时抛出错误。
+ */
+export function readStageContext(stageContextPath) {
+    const resolvedStageContextPath = path.resolve(stageContextPath);
+    const baseDir = path.dirname(resolvedStageContextPath);
+    const raw = parseStageContextFrontmatter(readFileSync(resolvedStageContextPath, 'utf8'));
+    const projectDir = resolvePath(baseDir, raw.projectDir ?? '.');
+    const envPath = raw.envPath ?? '.env';
+    if (!raw.projectName) {
+        throw new Error(`stage-context.md missing projectName: ${resolvedStageContextPath}`);
+    }
+    return {
+        projectName: raw.projectName,
+        projectDir,
+        mode: raw.mode ?? 'glue',
+        envPath,
+        envFilePath: resolvePath(projectDir, envPath),
+        knowledgeRoot: raw.knowledgeRoot ? resolvePath(projectDir, raw.knowledgeRoot) : undefined,
+        codeListPaths: (raw.codeListPaths ?? []).map((codeListPath) => resolvePath(projectDir, codeListPath)),
+        stageContextPath: resolvedStageContextPath,
+    };
+}
+/**
+ * 写入用户级 ep-stage 项目索引。
+ *
+ * @param input - HOME 目录和项目列表。
+ * @returns 写入后的索引文件路径。
+ */
+export function writeProjectIndex(input) {
+    const indexPath = getProjectIndexPath(input.homeDir);
+    mkdirSync(path.dirname(indexPath), { recursive: true });
+    writeFileSync(indexPath, `${JSON5.stringify({ version: 1, projects: input.projects }, null, 2)}\n`, 'utf8');
+    return indexPath;
+}
+/**
+ * 按固定优先级解析 ep-stage 项目上下文，并返回可审阅 trace。
+ *
+ * @param input - 显式路径、当前目录、code_list 路径和可选 HOME。
+ * @returns 解析出的项目上下文与 context-resolution trace。
+ * @throws 当无法定位任何上下文来源时抛出错误。
+ */
+export function resolveStageContext(input) {
+    if (input.stageContextPath) {
+        const context = readStageContext(input.stageContextPath);
+        return {
+            context,
+            trace: createTrace(context, {
+                sourceLabel: '显式 stage-context.md',
+                sourcePath: context.stageContextPath ?? path.resolve(input.stageContextPath),
+                requestedCodeListPath: input.codeListPath,
+            }),
+        };
+    }
+    const startDir = path.resolve(input.projectDir ?? input.cwd ?? process.cwd());
+    const localStageContextPath = findStageContextPath(startDir);
+    if (localStageContextPath) {
+        const context = readStageContext(localStageContextPath);
+        return {
+            context,
+            trace: createTrace(context, {
+                sourceLabel: '向上查找 stage-context.md',
+                sourcePath: localStageContextPath,
+                requestedCodeListPath: input.codeListPath,
+            }),
+        };
+    }
+    const indexPath = getProjectIndexPath(input.homeDir);
+    const index = readProjectIndex(indexPath);
+    const matched = index.projects.find((entry) => matchesProjectIndexEntry(entry, {
+        projectDir: input.projectDir,
+        cwd: input.cwd,
+        codeListPath: input.codeListPath,
+    }));
+    if (!matched) {
+        if (input.projectDir) {
+            const context = createDebugProjectContext(input.projectDir, input.codeListPath);
+            return {
+                context,
+                trace: createTrace(context, {
+                    sourceLabel: '显式 --project-dir 调试上下文',
+                    sourcePath: context.projectDir,
+                    requestedCodeListPath: input.codeListPath,
+                }),
+            };
+        }
+        throw new Error(`stage context not found from ${startDir} or ${indexPath}`);
+    }
+    const context = matched.stageContextPath
+        ? readStageContext(resolvePath(path.resolve(matched.projectDir), matched.stageContextPath))
+        : normalizeProjectIndexEntry(matched);
+    return {
+        context,
+        trace: createTrace(context, {
+            sourceLabel: '用户级 projects.index.json5',
+            sourcePath: indexPath,
+            requestedCodeListPath: input.codeListPath,
+        }),
+    };
+}
+/**
+ * 根据显式 --project-dir 合成最小调试上下文。
+ *
+ * @param projectDirInput - 用户传入的项目目录。
+ * @param codeListPathInput - 可选 code_list.md 路径。
+ * @returns 最小 StageContext，用于开发调试继续进入 .env gate。
+ */
+function createDebugProjectContext(projectDirInput, codeListPathInput) {
+    const projectDir = path.resolve(projectDirInput);
+    return {
+        projectName: path.basename(projectDir),
+        projectDir,
+        mode: 'glue',
+        envPath: '.env',
+        envFilePath: path.join(projectDir, '.env'),
+        codeListPaths: codeListPathInput ? [path.resolve(codeListPathInput)] : [],
+    };
+}
+/**
+ * 从 markdown frontmatter 中解析原始上下文字段。
+ *
+ * @param markdown - stage-context.md 原文。
+ * @returns 原始上下文字段。
+ * @throws 当文件没有 YAML frontmatter 时抛出错误。
+ */
+function parseStageContextFrontmatter(markdown) {
+    const match = /^---\r?\n([\s\S]*?)\r?\n---/.exec(markdown);
+    if (!match) {
+        throw new Error('stage-context.md missing YAML frontmatter');
+    }
+    return YAML.parse(match[1] ?? '');
+}
+/**
+ * 读取用户级 JSON5 项目索引。
+ *
+ * @param indexPath - 索引文件路径。
+ * @returns 项目索引对象。
+ */
+function readProjectIndex(indexPath) {
+    if (!existsSync(indexPath)) {
+        return { projects: [] };
+    }
+    const parsed = JSON5.parse(readFileSync(indexPath, 'utf8'));
+    return { projects: parsed.projects ?? [] };
+}
+/**
+ * 将用户索引条目归一为 StageContext。
+ *
+ * @param entry - 用户索引中的项目条目。
+ * @returns 归一化后的项目上下文。
+ */
+function normalizeProjectIndexEntry(entry) {
+    const projectDir = path.resolve(entry.projectDir);
+    const envPath = entry.envPath ?? '.env';
+    return {
+        projectName: entry.projectName,
+        projectDir,
+        mode: entry.mode,
+        envPath,
+        envFilePath: resolvePath(projectDir, envPath),
+        knowledgeRoot: entry.knowledgeRoot ? resolvePath(projectDir, entry.knowledgeRoot) : undefined,
+        codeListPaths: (entry.codeListPaths ?? []).map((codeListPath) => resolvePath(projectDir, codeListPath)),
+        stageContextPath: entry.stageContextPath ? resolvePath(projectDir, entry.stageContextPath) : undefined,
+    };
+}
+/**
+ * 判断用户索引条目是否匹配当前 projectDir、cwd 或 code_list 路径。
+ *
+ * @param entry - 用户索引中的项目条目。
+ * @param input - 当前解析输入。
+ * @returns 是否匹配该条目。
+ */
+function matchesProjectIndexEntry(entry, input) {
+    const context = normalizeProjectIndexEntry(entry);
+    const candidateDirs = [input.projectDir, input.cwd]
+        .filter((candidate) => Boolean(candidate))
+        .map((candidate) => path.resolve(candidate));
+    const matchedByDir = candidateDirs.some((candidate) => isSameOrInside(candidate, context.projectDir));
+    if (matchedByDir) {
+        return true;
+    }
+    if (!input.codeListPath) {
+        return false;
+    }
+    const requestedCodeListPath = path.resolve(input.codeListPath);
+    return context.codeListPaths.some((codeListPath) => path.resolve(codeListPath) === requestedCodeListPath);
+}
+/**
+ * 向上查找最近的 stage-context.md。
+ *
+ * @param startDir - 起始目录。
+ * @returns 找到的 stage-context.md 路径，不存在则返回 undefined。
+ */
+function findStageContextPath(startDir) {
+    let currentDir = startDir;
+    while (true) {
+        const candidate = path.join(currentDir, 'stage-context.md');
+        if (existsSync(candidate)) {
+            return candidate;
+        }
+        const parentDir = path.dirname(currentDir);
+        if (parentDir === currentDir) {
+            return undefined;
+        }
+        currentDir = parentDir;
+    }
+}
+/**
+ * 创建 context-resolution trace payload。
+ *
+ * @param context - 已解析上下文。
+ * @param source - 上下文来源信息。
+ * @returns 可观测 trace payload。
+ */
+function createTrace(context, source) {
+    const envExists = existsSync(context.envFilePath);
+    return {
+        stage: 'context-resolution',
+        stageLabel: '项目上下文解析',
+        inputs: [
+            { kind: 'project', path: context.projectDir, description: context.projectName },
+            ...(source.requestedCodeListPath
+                ? [{ kind: 'code_list', path: path.resolve(source.requestedCodeListPath) }]
+                : []),
+            { kind: 'context_source', path: source.sourcePath, description: source.sourceLabel },
+        ],
+        outputs: [
+            ...(context.stageContextPath
+                ? [{ kind: 'stage_context', path: context.stageContextPath }]
+                : []),
+            { kind: 'env', path: context.envFilePath, description: envExists ? '.env 已存在' : '.env 缺失' },
+        ],
+        reasoningSummary: {
+            conclusion: `从${source.sourceLabel}解析项目上下文：${source.sourcePath}`,
+            evidenceChain: [
+                {
+                    source: 'human',
+                    path: source.sourcePath,
+                    text: `项目 ${context.projectName}，模式 ${context.mode}，envPath ${context.envPath}`,
+                },
+                ...context.codeListPaths.map((codeListPath) => ({
+                    source: 'code_list',
+                    path: codeListPath,
+                    text: '上下文声明的 code_list 来源',
+                })),
+            ],
+            alternatives: ['显式 stage-context.md', '向上查找 stage-context.md', '用户级 projects.index.json5'],
+            confidence: 'high',
+            risks: envExists ? [] : ['.env 文件缺失，运行前需要补齐登录配置'],
+            needsHumanReview: !envExists,
+        },
+        candidateCount: 1,
+        unresolvedCount: envExists ? 0 : 1,
+        gate: envExists
+            ? { status: 'confirmed', confirmedBy: 'policy', reason: '.env 文件存在' }
+            : { status: 'needs_review', reason: `.env 文件不存在: ${context.envFilePath}` },
+    };
+}
+/**
+ * 获取用户级项目索引路径。
+ *
+ * @param homeDir - 可选 HOME 目录。
+ * @returns projects.index.json5 绝对路径。
+ */
+function getProjectIndexPath(homeDir) {
+    return path.join(homeDir ?? os.homedir(), '.ep-stage', 'projects.index.json5');
+}
+/**
+ * 解析相对或绝对路径。
+ *
+ * @param baseDir - 相对路径基准目录。
+ * @param targetPath - 待解析路径。
+ * @returns 绝对路径。
+ */
+function resolvePath(baseDir, targetPath) {
+    return path.isAbsolute(targetPath) ? path.resolve(targetPath) : path.resolve(baseDir, targetPath);
+}
+/**
+ * 判断 candidate 是否等于 baseDir 或位于其内部。
+ *
+ * @param candidate - 候选目录。
+ * @param baseDir - 基准目录。
+ * @returns 是否为同一路径或子路径。
+ */
+function isSameOrInside(candidate, baseDir) {
+    const relativePath = path.relative(baseDir, candidate);
+    return relativePath === '' || (!relativePath.startsWith('..') && !path.isAbsolute(relativePath));
+}