openxiangda-devkit-core 2.0.0-alpha.97 → 2.0.0

package/dist/development-lifecycle.js

@@ -0,0 +1,189 @@
+import { inspectDesignReadiness } from './design-readiness.js';
+import { execFileSync } from 'node:child_process';
+import { existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join, relative, resolve } from 'node:path';
+import { tmpdir } from 'node:os';
+import { SCHEMA_VERSIONS } from 'openxiangda-contracts';
+import { inspectAppSpec } from './app-spec.js';
+const APP_SECTIONS = ['业务目标', '角色', '架构与数据关系', '业务任务与页面', '权限矩阵与确认', '性能与容量预算'];
+const CHANGE_SECTIONS = ['为什么', '需求依据', '方案与影响', '任务与实现', '验收', '性能与容量预算'];
+function issue(code, message, path) {
+    return { schemaVersion: SCHEMA_VERSIONS.diagnostic, severity: 'error', retryable: false, code, message, path, remediation: '依据实际业务补齐对应记录；运行 openxiangda spec context --json 查看阶段缺口，不能填写虚假确认或通过结果' };
+}
+function section(content, title) {
+    const source = content.replace(/<!--[\s\S]*?-->/g, '');
+    const start = source.indexOf(`\n## ${title}\n`);
+    if (start < 0)
+        return '';
+    return source.slice(start + title.length + 5).split(/\n## /)[0] || '';
+}
+function meaningful(content) {
+    return content.split('\n').map(line => line.replace(/^\s*[-*]\s*(?:\[[ x]\]\s*)?/, '').trim())
+        .filter(line => line && !line.startsWith('|') && !line.startsWith('#') && !/^(待补充|待确认|TBD|TODO|无。?|一个可观察的正向结果|需要时补充拒绝、异常或权限反例)$/.test(line)).join('\n').length >= 8
+        || content.split('\n').filter(line => line.trim().startsWith('|') && !/^[|\s:-]+$/.test(line)).length >= 2;
+}
+function boundedGit(root, args, maxBuffer = 2 * 1024 * 1024) {
+    return execFileSync('git', ['-C', root, ...args], { encoding: 'utf8', timeout: 10_000, maxBuffer, stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+}
+function headMessage(root) {
+    try {
+        return boundedGit(root, ['log', '-1', '--format=%B']);
+    }
+    catch {
+        return '';
+    }
+}
+/** 按发布阶段评估事实完整性；不推断用户确认，也不将章节存在当作业务验收。 */
+export function developmentLifecycle(root, contract, message = headMessage(root), selector) {
+    const index = inspectAppSpec(root, contract);
+    const explicit = message.match(/^AppSpec:\s*([a-z0-9]+(?:-[a-z0-9]+)*)\s*$/m)?.[1];
+    const changeId = selector || explicit || (index.index.activeChanges.length === 1 ? index.index.activeChanges[0]?.id : undefined);
+    const context = changeId ? inspectAppSpec(root, contract, changeId) : index;
+    const change = [...context.activeChanges, ...context.archivedChanges].find(item => item.id === changeId);
+    const diagnostics = context.diagnostics.filter(item => item.severity === 'error');
+    const app = context.application;
+    if (!app)
+        diagnostics.push(issue('APPSPEC_APPLICATION_REQUIRED', '正式发布需要应用总纲；运行 openxiangda spec init 后填写实际目标、权限、架构和容量', 'appspec/app.md'));
+    else
+        for (const title of APP_SECTIONS) {
+            if (!meaningful(section(app.content, title)))
+                diagnostics.push(issue('APPSPEC_APPLICATION_SECTION_INCOMPLETE', `应用总纲“${title}”尚无具体记录`, `${app.path}#${title}`));
+        }
+    const design = inspectDesignReadiness(context, change);
+    diagnostics.push(...design.diagnostics);
+    const designDiagnostics = [...diagnostics];
+    if (!change)
+        diagnostics.push(issue('APPSPEC_DELIVERY_CHANGE_REQUIRED', '需要关联本轮变更；有多个活动变更或引用历史记录时，在提交说明加入 AppSpec: <变更ID>', 'appspec/changes/active'));
+    else {
+        for (const title of CHANGE_SECTIONS) {
+            if (!meaningful(section(change.content, title)))
+                diagnostics.push(issue('APPSPEC_CHANGE_SECTION_INCOMPLETE', `变更“${title}”尚无具体记录`, `${change.path}#${title}`));
+        }
+        if (change.status === 'draft' || change.status === 'cancelled')
+            diagnostics.push(issue('APPSPEC_CHANGE_NOT_READY', '变更仍是草稿或已取消；先澄清业务含义并记录实际依据，再进入 implementing', change.path));
+    }
+    for (const document of [app, change].filter((item) => !!item)) {
+        if (/^\s*[-*] \[ \]/m.test(section(document.content, '未确认问题'))) {
+            const blocking = issue('APPSPEC_BLOCKING_QUESTIONS', '仍有影响正式交付的未确认问题；非阻断假设单独记录，不冒充用户确认', `${document.path}#未确认问题`);
+            diagnostics.push(blocking);
+            designDiagnostics.push(blocking);
+        }
+    }
+    const acceptanceIds = [...new Set([...(app?.acceptanceIds || []), ...(change?.acceptanceIds || []), ...context.capabilities.flatMap(item => item.acceptanceIds), ...context.designs.flatMap(item => item.acceptanceIds)])];
+    if (change && !acceptanceIds.length)
+        diagnostics.push(issue('APPSPEC_ACCEPTANCE_PLAN_REQUIRED', '至少定义一个 #### AC-* 可观察验收场景，供测试部署后逐项验证', `${change.path}#验收`));
+    const readyForImplementation = design.readyForImplementation && !designDiagnostics.length;
+    return {
+        schemaVersion: 'openxiangda.development-lifecycle/v2',
+        stage: !readyForImplementation ? 'design-incomplete' : diagnostics.length ? 'ready-for-implementation' : 'ready-for-test',
+        readyForImplementation, design,
+        readyForTest: !diagnostics.length, changeId: change?.id || null, acceptanceIds,
+        currentSpecDigest: context.selectionDigest,
+        diagnostics,
+        nextCommand: changeId ? `openxiangda spec context ${changeId} --json` : 'openxiangda spec context --json',
+        context,
+    };
+}
+export function summarizeLifecycle(value) {
+    const { context, ...summary } = value;
+    return summary;
+}
+/** 生产验收按测试版本中的需求计划核对，当前主线后来增加的规则不会冒充已测规则。 */
+export function lifecycleAtCommit(root, commit, contract) {
+    if (!/^[a-f0-9]{40,64}$/.test(commit))
+        throw new Error('APPSPEC_SOURCE_COMMIT_INVALID');
+    const scratch = mkdtempSync(join(tmpdir(), 'openxiangda-spec-source-'));
+    try {
+        const message = boundedGit(root, ['log', '-1', '--format=%B', commit]);
+        const selected = message.match(/^AppSpec:\s*([a-z0-9]+(?:-[a-z0-9]+)*)\s*$/m)?.[1];
+        const paths = boundedGit(root, ['ls-tree', '-r', '--name-only', commit, '--', 'appspec']).split('\n').filter(path => /^appspec\/(?:app\.md|capabilities\/[^/]+\.md|(?:decisions|product|experience|design|reviews)\/[^/]+\.md|changes\/active\/[^/]+\.md)$/.test(path)
+            || (selected && new RegExp(`^appspec/changes/history/[^/]+/${selected}\\.md$`).test(path)));
+        if (paths.length > 128)
+            throw new Error('APPSPEC_SOURCE_FILE_LIMIT');
+        let bytes = 0;
+        for (const path of paths) {
+            const content = execFileSync('git', ['-C', root, 'show', `${commit}:${path}`], { encoding: 'utf8', timeout: 10_000, maxBuffer: 256 * 1024, stdio: ['ignore', 'pipe', 'pipe'] });
+            bytes += Buffer.byteLength(content);
+            if (bytes > 2 * 1024 * 1024)
+                throw new Error('APPSPEC_SOURCE_SIZE_LIMIT');
+            const target = join(scratch, path);
+            mkdirSync(dirname(target), { recursive: true });
+            writeFileSync(target, content);
+        }
+        return developmentLifecycle(scratch, contract, message);
+    }
+    finally {
+        rmSync(scratch, { recursive: true, force: true });
+    }
+}
+export function verifyBusinessAcceptance(root, run, expected, pathInput) {
+    const defaultPath = `appspec/verification/${run.id}.json`;
+    const path = resolve(root, pathInput || defaultPath);
+    const local = relative(root, path).replaceAll('\\', '/');
+    const diagnostics = [];
+    function evidenceExists(value) {
+        if (typeof value !== 'string' || !value.trim())
+            return false;
+        if (value.startsWith('https://')) {
+            try {
+                return !!new URL(value).hostname;
+            }
+            catch {
+                return false;
+            }
+        }
+        const path = resolve(root, value);
+        const local = relative(root, path);
+        if (!local || local.startsWith('..'))
+            return false;
+        try {
+            let current = root;
+            for (const name of local.split(/[\\/]/)) {
+                current = join(current, name);
+                if (lstatSync(current).isSymbolicLink())
+                    return false;
+            }
+            return lstatSync(path).isFile();
+        }
+        catch {
+            return false;
+        }
+    }
+    try {
+        if (!/^appspec\/verification\/[a-zA-Z0-9._-]+\.json$/.test(local))
+            throw new Error('验收报告应位于 appspec/verification/ 中');
+        for (const part of ['appspec', 'appspec/verification', local]) {
+            if (lstatSync(join(root, part)).isSymbolicLink())
+                throw new Error('验收报告路径不能使用符号链接');
+        }
+        if (!existsSync(path) || lstatSync(path).size > 1024 * 1024)
+            throw new Error('验收报告缺失或超过 1 MiB');
+        const report = JSON.parse(readFileSync(path, 'utf8'));
+        if (report.schemaVersion !== 'openxiangda.business-verification/v1' || report.appCode !== run.appCode || report.sourceDeploymentId !== run.id || report.packageDigest !== run.packageDigest || !expected.changeId || report.changeId !== expected.changeId || run.status !== 'succeeded' || run.environment.kind !== 'preproduction')
+            throw new Error('验收报告未绑定指定成功测试运行、包摘要与变更');
+        if (!Number.isFinite(Date.parse(report.recordedAt)) || !Array.isArray(report.scenarios) || !report.scenarios.length || report.scenarios.length > 500 || !Array.isArray(report.performance) || !report.performance.length || report.performance.length > 100)
+            throw new Error('报告需要记录时间、具体场景与性能测量');
+        const seen = new Set();
+        for (const scenario of report.scenarios) {
+            if (!/^AC-[A-Z0-9-]+$/.test(scenario.id) || seen.has(scenario.id) || scenario.status !== 'passed' || !meaningful(String(scenario.observation || '')) || !String(scenario.actor || '').trim() || !Array.isArray(scenario.evidence) || !scenario.evidence.some((value) => typeof value === 'string' && value.trim().length >= 4))
+                throw new Error('验收场景必须有唯一 AC ID、已通过结果、实际角色、观察与证据引用；失败或未测场景不能晋级');
+            seen.add(scenario.id);
+            if (!scenario.evidence.every(evidenceExists))
+                throw new Error('场景证据需要工作区内实际存在的文件或 HTTPS 引用');
+        }
+        if (expected.acceptanceIds.some(id => !seen.has(id)))
+            throw new Error('测试版本计划中的验收场景尚未全部覆盖');
+        for (const measurement of report.performance) {
+            if (!meaningful(String(measurement.scenario || '')) || !meaningful(String(measurement.sample || '')) || typeof measurement.targetMs !== 'number' || !Number.isFinite(measurement.targetMs) || measurement.targetMs <= 0 || typeof measurement.observedMs !== 'number' || !Number.isFinite(measurement.observedMs) || measurement.observedMs < 0 || measurement.observedMs > measurement.targetMs || !Array.isArray(measurement.evidence) || !measurement.evidence.length)
+                throw new Error('性能记录需要真实样本、目标毫秒数、实测毫秒数及证据；超出目标时先评估并修复');
+            if (!measurement.evidence.every(evidenceExists))
+                throw new Error('性能证据需要工作区内实际存在的文件或 HTTPS 引用');
+        }
+        return { ok: true, path: local, sourceDeploymentId: run.id, packageDigest: run.packageDigest, scenarios: report.scenarios.length, diagnostics };
+    }
+    catch (error) {
+        diagnostics.push(issue('APPSPEC_BUSINESS_ACCEPTANCE_REQUIRED', `生产晋级前需要该测试版本的实际验收报告：${error.message}`, local));
+        return { ok: false, path: local, sourceDeploymentId: run.id, packageDigest: run.packageDigest, scenarios: 0, diagnostics };
+    }
+}
+//# sourceMappingURL=development-lifecycle.js.map

package/dist/development-lifecycle.js.map

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

package/dist/documentation.d.ts

@@ -0,0 +1,111 @@
+/** 使用指南的唯一主题目录；正文从同版本根包读取。 */
+export declare const DOCUMENTATION_TOPICS: readonly [{
+    readonly id: "getting-started";
+    readonly title: "安装与开始开发";
+    readonly file: "getting-started.md";
+}, {
+    readonly id: "product-design";
+    readonly title: "对话发现与详细产品设计";
+    readonly file: "product-design.md";
+}, {
+    readonly id: "interaction-patterns";
+    readonly title: "页面交互模式与体验评审";
+    readonly file: "interaction-patterns.md";
+}, {
+    readonly id: "development";
+    readonly title: "需求与开发流程";
+    readonly file: "development.md";
+}, {
+    readonly id: "application-foundation";
+    readonly title: "业务模型与标准 CRUD";
+    readonly file: "application-foundation.md";
+}, {
+    readonly id: "appspec";
+    readonly title: "需求、设计与交付记录";
+    readonly file: "appspec.md";
+}, {
+    readonly id: "concepts";
+    readonly title: "架构与能力所有者";
+    readonly file: "concepts.md";
+}, {
+    readonly id: "frontend";
+    readonly title: "页面与标准组件扩展";
+    readonly file: "frontend.md";
+}, {
+    readonly id: "field-components";
+    readonly title: "字段、表单与移动控件";
+    readonly file: "field-components.md";
+}, {
+    readonly id: "data-authz";
+    readonly title: "数据查询与权限";
+    readonly file: "data-authz.md";
+}, {
+    readonly id: "public-access";
+    readonly title: "无账号的匿名公开访问";
+    readonly file: "public-access.md";
+}, {
+    readonly id: "workflow-events";
+    readonly title: "审批、事件与通知";
+    readonly file: "workflow-events.md";
+}, {
+    readonly id: "backend";
+    readonly title: "按需后端与业务动作";
+    readonly file: "backend.md";
+}, {
+    readonly id: "administration";
+    readonly title: "应用管理与有效配置";
+    readonly file: "administration.md";
+}, {
+    readonly id: "testing";
+    readonly title: "检查与真实业务验收";
+    readonly file: "testing.md";
+}, {
+    readonly id: "delivery";
+    readonly title: "部署、生产晋级与恢复";
+    readonly file: "delivery.md";
+}, {
+    readonly id: "upgrading";
+    readonly title: "版本升级与资料刷新";
+    readonly file: "upgrading.md";
+}, {
+    readonly id: "cli";
+    readonly title: "CLI 命令参考";
+    readonly file: "reference/cli.md";
+}, {
+    readonly id: "mcp";
+    readonly title: "MCP 配置与工具参考";
+    readonly file: "reference/mcp.md";
+}];
+/** Skill 参考文件名直接使用主题 ID，正文由同一中文主题生成。 */
+export declare function documentationReferenceFile(id: string): string;
+export declare function documentationRoot(): string;
+export declare function documentationIndex(root?: string): {
+    schemaVersion: string;
+    topics: {
+        id: "appspec" | "delivery" | "frontend" | "backend" | "getting-started" | "product-design" | "interaction-patterns" | "development" | "application-foundation" | "concepts" | "field-components" | "data-authz" | "public-access" | "workflow-events" | "administration" | "testing" | "upgrading" | "cli" | "mcp";
+        title: "CLI 命令参考" | "安装与开始开发" | "对话发现与详细产品设计" | "页面交互模式与体验评审" | "需求与开发流程" | "业务模型与标准 CRUD" | "需求、设计与交付记录" | "架构与能力所有者" | "页面与标准组件扩展" | "字段、表单与移动控件" | "数据查询与权限" | "无账号的匿名公开访问" | "审批、事件与通知" | "按需后端与业务动作" | "应用管理与有效配置" | "检查与真实业务验收" | "部署、生产晋级与恢复" | "版本升级与资料刷新" | "MCP 配置与工具参考";
+        uri: string;
+        version: string;
+        sha256: string;
+        bytes: number;
+        sections: {
+            id: string;
+            title: string;
+        }[];
+    }[];
+};
+export declare function readDocumentation(id: string, section?: string, root?: string): {
+    schemaVersion: string;
+    topic: string;
+    title: "CLI 命令参考" | "安装与开始开发" | "对话发现与详细产品设计" | "页面交互模式与体验评审" | "需求与开发流程" | "业务模型与标准 CRUD" | "需求、设计与交付记录" | "架构与能力所有者" | "页面与标准组件扩展" | "字段、表单与移动控件" | "数据查询与权限" | "无账号的匿名公开访问" | "审批、事件与通知" | "按需后端与业务动作" | "应用管理与有效配置" | "检查与真实业务验收" | "部署、生产晋级与恢复" | "版本升级与资料刷新" | "MCP 配置与工具参考";
+    version: string;
+    sha256: string;
+    uri: string;
+    sections: {
+        id: string;
+        title: string;
+    }[];
+    content: string;
+};
+export declare function workspaceGuidanceTemplatePath(): string;
+//# sourceMappingURL=documentation.d.ts.map

package/dist/documentation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"documentation.d.ts","sourceRoot":"","sources":["../src/documentation.ts"],"names":[],"mappings":"AAIA,8BAA8B;AAC9B,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAoBvB,CAAC;AAEX,wCAAwC;AACxC,wBAAgB,0BAA0B,CAAC,EAAE,EAAE,MAAM,UAEpD;AAID,wBAAgB,iBAAiB,WAEhC;AA4CD,wBAAgB,kBAAkB,CAAC,IAAI,SAAsB;;;;;;;;;;;;;;EAW5D;AAED,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,IAAI,SAAsB;;;;;;;;;;;;EAWzF;AAED,wBAAgB,6BAA6B,WAI5C"}

package/dist/documentation.js

@@ -0,0 +1,112 @@
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync, realpathSync, statSync } from 'node:fs';
+import { isAbsolute, relative, resolve } from 'node:path';
+/** 使用指南的唯一主题目录；正文从同版本根包读取。 */
+export const DOCUMENTATION_TOPICS = [
+    { id: 'getting-started', title: '安装与开始开发', file: 'getting-started.md' },
+    { id: 'product-design', title: '对话发现与详细产品设计', file: 'product-design.md' },
+    { id: 'interaction-patterns', title: '页面交互模式与体验评审', file: 'interaction-patterns.md' },
+    { id: 'development', title: '需求与开发流程', file: 'development.md' },
+    { id: 'application-foundation', title: '业务模型与标准 CRUD', file: 'application-foundation.md' },
+    { id: 'appspec', title: '需求、设计与交付记录', file: 'appspec.md' },
+    { id: 'concepts', title: '架构与能力所有者', file: 'concepts.md' },
+    { id: 'frontend', title: '页面与标准组件扩展', file: 'frontend.md' },
+    { id: 'field-components', title: '字段、表单与移动控件', file: 'field-components.md' },
+    { id: 'data-authz', title: '数据查询与权限', file: 'data-authz.md' },
+    { id: 'public-access', title: '无账号的匿名公开访问', file: 'public-access.md' },
+    { id: 'workflow-events', title: '审批、事件与通知', file: 'workflow-events.md' },
+    { id: 'backend', title: '按需后端与业务动作', file: 'backend.md' },
+    { id: 'administration', title: '应用管理与有效配置', file: 'administration.md' },
+    { id: 'testing', title: '检查与真实业务验收', file: 'testing.md' },
+    { id: 'delivery', title: '部署、生产晋级与恢复', file: 'delivery.md' },
+    { id: 'upgrading', title: '版本升级与资料刷新', file: 'upgrading.md' },
+    { id: 'cli', title: 'CLI 命令参考', file: 'reference/cli.md' },
+    { id: 'mcp', title: 'MCP 配置与工具参考', file: 'reference/mcp.md' },
+];
+/** Skill 参考文件名直接使用主题 ID，正文由同一中文主题生成。 */
+export function documentationReferenceFile(id) {
+    return `${id}.md`;
+}
+const MAX_TOPIC_BYTES = 128 * 1024;
+export function documentationRoot() {
+    return resolve(process.env.OPENXIANGDA_DOCUMENTATION_ROOT || resolve(import.meta.dirname, '../../../docs'));
+}
+function topicSource(id, root) {
+    const topic = DOCUMENTATION_TOPICS.find(item => item.id === id);
+    if (!topic)
+        throw new Error(`DOCUMENTATION_TOPIC_NOT_FOUND: 未知主题 ${id}。CLI 运行 pnpm openxiangda docs，MCP 调用 docs_read 并省略 topic，按目录中的 id 读取正文`);
+    const path = resolve(root, topic.file);
+    if (!existsSync(path))
+        throw new Error(`DOCUMENTATION_NOT_INSTALLED: 当前安装缺少 ${id}，请通过同版本 openxiangda 根包启动`);
+    const resolved = realpathSync(path);
+    const local = relative(realpathSync(root), resolved);
+    if (local.startsWith('..') || isAbsolute(local))
+        throw new Error('DOCUMENTATION_PATH_FORBIDDEN: 文档不能越过资料目录');
+    if (!statSync(resolved).isFile() || statSync(resolved).size > MAX_TOPIC_BYTES) {
+        throw new Error('DOCUMENTATION_SIZE_EXCEEDED: 单个主题必须是大小不超过 128 KiB 的文本文档');
+    }
+    const text = readFileSync(resolved, 'utf8');
+    const sha256 = createHash('sha256').update(text).digest('hex');
+    const manifestPath = resolve(root, 'manifest.json');
+    const manifest = existsSync(manifestPath)
+        ? JSON.parse(readFileSync(manifestPath, 'utf8'))
+        : undefined;
+    if (manifest && manifest.topics.find(item => item.id === id)?.sha256 !== sha256) {
+        throw new Error(`DOCUMENTATION_DIGEST_MISMATCH: ${id} 与当前根包资料摘要不一致，请重新安装该精确版本`);
+    }
+    return { ...topic, text, sha256, version: manifest?.version || 'development' };
+}
+function sections(text) {
+    const lines = text.split('\n');
+    const found = [];
+    let fenced = false;
+    const used = new Map();
+    lines.forEach((line, index) => {
+        if (/^\s*(```|~~~)/.test(line)) {
+            fenced = !fenced;
+            return;
+        }
+        const match = !fenced && line.match(/^##\s+(.+?)(?:\s+\{#([\w-]+)\})?\s*$/);
+        if (!match)
+            return;
+        const title = match[1];
+        const base = match[2] || title.toLowerCase().replace(/[^\p{L}\p{N}]+/gu, '-').replace(/^-|-$/g, '');
+        const count = used.get(base) || 0;
+        used.set(base, count + 1);
+        if (found.length)
+            found[found.length - 1].end = index;
+        found.push({ id: count ? `${base}-${count + 1}` : base, title, start: index, end: lines.length });
+    });
+    return { lines, found };
+}
+export function documentationIndex(root = documentationRoot()) {
+    const topics = DOCUMENTATION_TOPICS.map(({ id }) => {
+        const source = topicSource(id, root);
+        return {
+            id, title: source.title, uri: `openxiangda://docs/${id}`,
+            version: source.version, sha256: source.sha256,
+            bytes: Buffer.byteLength(source.text),
+            sections: sections(source.text).found.map(({ id, title }) => ({ id, title })),
+        };
+    });
+    return { schemaVersion: 'openxiangda.documentation/v1', topics };
+}
+export function readDocumentation(id, section, root = documentationRoot()) {
+    const source = topicSource(id, root);
+    const parsed = sections(source.text);
+    const selected = section ? parsed.found.find(item => item.id === section) : undefined;
+    if (section && !selected)
+        throw new Error(`DOCUMENTATION_SECTION_NOT_FOUND: ${id} 没有章节 ${section}，先读取该主题的章节目录`);
+    return {
+        schemaVersion: 'openxiangda.documentation/v1', topic: id, title: source.title,
+        version: source.version, sha256: source.sha256, uri: `openxiangda://docs/${id}`,
+        sections: parsed.found.map(({ id, title }) => ({ id, title })),
+        content: selected ? parsed.lines.slice(selected.start, selected.end).join('\n') : source.text,
+    };
+}
+export function workspaceGuidanceTemplatePath() {
+    return process.env.OPENXIANGDA_DOCUMENTATION_ROOT
+        ? resolve(documentationRoot(), 'AGENTS.md')
+        : resolve(import.meta.dirname, '../../../templates/application/AGENTS.md');
+}
+//# sourceMappingURL=documentation.js.map

package/dist/documentation.js.map

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

package/dist/index.d.ts

@@ -2,6 +2,7 @@ export * from './application-services.js';
 export * from './app-spec.js';
 export * from './connected-development.js';
 export * from './compiler/bundle.js';
+export * from './compiler/permission-review.js';
 export * from './command-registry.js';
 export * from './config.js';
 export * from './control-plane-client.js';
@@ -9,9 +10,18 @@ export * from './deployment.js';
 export * from './package-compiler.js';
 export * from './compiler/ai-catalog.js';
 export * from './compiler/schema-composition.js';
+export * from './compiler/application-model.js';
 export * from './workspace.js';
 export * from './workspace-loader.js';
 export * from './session.js';
 export * from './version.js';
 export * from './toolchain-capsule.js';
+export * from './application-ui-contract.js';
+export * from './optional-backend.js';
+export * from './developer-operations.js';
+export * from './operation-progress.js';
+export * from './deployment-observer.js';
+export * from './documentation.js';
+export { developerError } from './developer-errors.js';
+export { withWorkspaceOperation } from './workspace-operation.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,2BAA2B,CAAC;AAC1C,cAAc,eAAe,CAAC;AAC9B,cAAc,4BAA4B,CAAC;AAC3C,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,aAAa,CAAC;AAC5B,cAAc,2BAA2B,CAAC;AAC1C,cAAc,iBAAiB,CAAC;AAChC,cAAc,uBAAuB,CAAC;AACtC,cAAc,0BAA0B,CAAC;AACzC,cAAc,kCAAkC,CAAC;AACjD,cAAc,gBAAgB,CAAC;AAC/B,cAAc,uBAAuB,CAAC;AACtC,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,wBAAwB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,2BAA2B,CAAC;AAC1C,cAAc,eAAe,CAAC;AAC9B,cAAc,4BAA4B,CAAC;AAC3C,cAAc,sBAAsB,CAAC;AACrC,cAAc,iCAAiC,CAAC;AAChD,cAAc,uBAAuB,CAAC;AACtC,cAAc,aAAa,CAAC;AAC5B,cAAc,2BAA2B,CAAC;AAC1C,cAAc,iBAAiB,CAAC;AAChC,cAAc,uBAAuB,CAAC;AACtC,cAAc,0BAA0B,CAAC;AACzC,cAAc,kCAAkC,CAAC;AACjD,cAAc,iCAAiC,CAAC;AAChD,cAAc,gBAAgB,CAAC;AAC/B,cAAc,uBAAuB,CAAC;AACtC,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,wBAAwB,CAAC;AAEvC,cAAc,8BAA8B,CAAC;AAE7C,cAAc,uBAAuB,CAAC;AACtC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,yBAAyB,CAAC;AACxC,cAAc,0BAA0B,CAAC;AACzC,cAAc,oBAAoB,CAAC;AAEnC,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC"}

package/dist/index.js

@@ -2,6 +2,7 @@ export * from './application-services.js';
 export * from './app-spec.js';
 export * from './connected-development.js';
 export * from './compiler/bundle.js';
+export * from './compiler/permission-review.js';
 export * from './command-registry.js';
 export * from './config.js';
 export * from './control-plane-client.js';
@@ -9,9 +10,18 @@ export * from './deployment.js';
 export * from './package-compiler.js';
 export * from './compiler/ai-catalog.js';
 export * from './compiler/schema-composition.js';
+export * from './compiler/application-model.js';
 export * from './workspace.js';
 export * from './workspace-loader.js';
 export * from './session.js';
 export * from './version.js';
 export * from './toolchain-capsule.js';
+export * from './application-ui-contract.js';
+export * from './optional-backend.js';
+export * from './developer-operations.js';
+export * from './operation-progress.js';
+export * from './deployment-observer.js';
+export * from './documentation.js';
+export { developerError } from './developer-errors.js';
+export { withWorkspaceOperation } from './workspace-operation.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,2BAA2B,CAAC;AAC1C,cAAc,eAAe,CAAC;AAC9B,cAAc,4BAA4B,CAAC;AAC3C,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,aAAa,CAAC;AAC5B,cAAc,2BAA2B,CAAC;AAC1C,cAAc,iBAAiB,CAAC;AAChC,cAAc,uBAAuB,CAAC;AACtC,cAAc,0BAA0B,CAAC;AACzC,cAAc,kCAAkC,CAAC;AACjD,cAAc,gBAAgB,CAAC;AAC/B,cAAc,uBAAuB,CAAC;AACtC,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,wBAAwB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,2BAA2B,CAAC;AAC1C,cAAc,eAAe,CAAC;AAC9B,cAAc,4BAA4B,CAAC;AAC3C,cAAc,sBAAsB,CAAC;AACrC,cAAc,iCAAiC,CAAC;AAChD,cAAc,uBAAuB,CAAC;AACtC,cAAc,aAAa,CAAC;AAC5B,cAAc,2BAA2B,CAAC;AAC1C,cAAc,iBAAiB,CAAC;AAChC,cAAc,uBAAuB,CAAC;AACtC,cAAc,0BAA0B,CAAC;AACzC,cAAc,kCAAkC,CAAC;AACjD,cAAc,iCAAiC,CAAC;AAChD,cAAc,gBAAgB,CAAC;AAC/B,cAAc,uBAAuB,CAAC;AACtC,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,wBAAwB,CAAC;AAEvC,cAAc,8BAA8B,CAAC;AAE7C,cAAc,uBAAuB,CAAC;AACtC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,yBAAyB,CAAC;AACxC,cAAc,0BAA0B,CAAC;AACzC,cAAc,oBAAoB,CAAC;AAEnC,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC"}

package/dist/operation-progress.d.ts

@@ -0,0 +1,26 @@
+export interface OperationStage {
+    stage: string;
+    label: string;
+    state: 'running' | 'passed' | 'failed' | 'skipped';
+    startedAt: string;
+    durationMs: number;
+    details?: Record<string, unknown>;
+}
+export interface OperationProgress extends OperationStage {
+    schemaVersion: 'openxiangda.operation-progress/v1';
+    operationId: string;
+    operation: string;
+    sequence: number;
+    elapsedMs: number;
+    heartbeat: boolean;
+}
+export type OperationProgressListener = (event: OperationProgress) => void | Promise<void>;
+/** 每次调用独立；并发 MCP 请求不会共享当前阶段或监听器。 */
+export declare function withOperationProgress<T extends {
+    data?: unknown;
+}>(operation: string, listener: OperationProgressListener | undefined, execute: () => Promise<T>, heartbeatMs?: number): Promise<T>;
+export declare function operationStage<T>(stage: string, label: string, execute: () => Promise<T>): Promise<T>;
+export declare function skippedOperationStage(stage: string, label: string): void;
+/** 平台仍是运行状态权威；此处只刷新本次观察的标题和运行指针。 */
+export declare function updateOperationStage(stage: string, label: string, details: Record<string, unknown>): void;
+//# sourceMappingURL=operation-progress.d.ts.map

package/dist/operation-progress.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"operation-progress.d.ts","sourceRoot":"","sources":["../src/operation-progress.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;IACnD,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AACD,MAAM,WAAW,iBAAkB,SAAQ,cAAc;IACvD,aAAa,EAAE,mCAAmC,CAAC;IACnD,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,OAAO,CAAC;CACpB;AACD,MAAM,MAAM,yBAAyB,GAAG,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAY3F,oCAAoC;AACpC,wBAAsB,qBAAqB,CAAC,CAAC,SAAS;IAAE,IAAI,CAAC,EAAE,OAAO,CAAA;CAAE,EACtE,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,yBAAyB,GAAG,SAAS,EAC/C,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACzB,WAAW,SAAS,GACnB,OAAO,CAAC,CAAC,CAAC,CAuBZ;AAYD,wBAAsB,cAAc,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAwB3G;AAED,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,QAKjE;AAED,oCAAoC;AACpC,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,QAQlG"}