@dommaker/harness 0.7.3 → 0.7.4

package/dist/architecture/cross-project-checker.js

@@ -0,0 +1,260 @@
+"use strict";
+/**
+ * 跨工程接口契约检查
+ *
+ * 检测多工程开发时的接口不一致问题
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkCrossProjectContracts = checkCrossProjectContracts;
+exports.checkDocCodeConsistency = checkDocCodeConsistency;
+const child_process_1 = require("child_process");
+const path = __importStar(require("path"));
+// 工程依赖关系图
+const PROJECT_DEPENDENCIES = {
+    'agent-studio': ['agent-runtime', 'harness'],
+    'agent-runtime': ['harness', 'agent-workflows'],
+    'agent-workflows': ['harness'],
+    'harness': [],
+};
+// 接口契约定义位置
+const CONTRACT_LOCATIONS = {
+    'studio-runtime': [
+        'agent-runtime/src/api/types.ts', // runtime 导出的 API 类型
+        'agent-studio/src/services/runtime-client.ts', // studio 调用 runtime 的客户端
+    ],
+    'runtime-harness': [
+        'harness/src/index.ts', // harness 导出
+        'agent-runtime/src/core/harness-adapter.ts', // runtime 使用 harness
+    ],
+};
+/**
+ * 检查跨工程接口一致性
+ */
+async function checkCrossProjectContracts(context) {
+    const violations = [];
+    // 1. 检查 API 变更是否同步到调用方
+    violations.push(...await checkApiSync(context));
+    // 2. 检查类型定义一致性
+    violations.push(...await checkTypeConsistency(context));
+    // 3. 检查破坏性变更
+    violations.push(...await checkBreakingChanges(context));
+    return violations;
+}
+/**
+ * 检查 API 变更同步
+ * 场景：改了 runtime API，studio 没更新
+ */
+async function checkApiSync(context) {
+    const violations = [];
+    // 检查 runtime API 变更
+    if (context.changedProjects.includes('agent-runtime')) {
+        const runtimeApiChanges = getApiChanges('agent-runtime', context.baseBranch);
+        for (const change of runtimeApiChanges) {
+            // 检查 studio 是否同步更新
+            const studioUpdated = context.changedFiles.some(f => f.includes('agent-studio/src/services/') ||
+                f.includes('agent-studio/src/api/'));
+            if (!studioUpdated && isPublicApi(change)) {
+                violations.push({
+                    type: 'api-mismatch',
+                    severity: 'error',
+                    message: `Runtime API '${change.name}' 变更未同步到 Studio`,
+                    fromProject: 'agent-runtime',
+                    toProject: 'agent-studio',
+                    details: {
+                        interfaceName: change.name,
+                        location: change.file,
+                    },
+                });
+            }
+        }
+    }
+    return violations;
+}
+/**
+ * 检查类型定义一致性
+ * 场景：同一接口在不同工程定义不一致
+ */
+async function checkTypeConsistency(context) {
+    const violations = [];
+    // 检查 harness 类型是否在 runtime 中一致使用
+    const harnessTypes = extractExportedTypes('harness');
+    const runtimeUsage = extractTypeUsage('agent-runtime', harnessTypes);
+    for (const [typeName, usage] of Object.entries(runtimeUsage)) {
+        if (usage.hasMismatch) {
+            violations.push({
+                type: 'doc-code-mismatch',
+                severity: 'error',
+                message: `类型 '${typeName}' 在 runtime 中的使用与 harness 定义不一致`,
+                fromProject: 'harness',
+                toProject: 'agent-runtime',
+                details: {
+                    interfaceName: typeName,
+                    expectedType: usage.expected,
+                    actualType: usage.actual,
+                },
+            });
+        }
+    }
+    return violations;
+}
+/**
+ * 检查破坏性变更
+ */
+async function checkBreakingChanges(context) {
+    const violations = [];
+    for (const project of context.changedProjects) {
+        const dependents = getDependents(project);
+        for (const change of getApiChanges(project, context.baseBranch)) {
+            if (isBreakingChange(change)) {
+                // 检查所有依赖方是否已适配
+                for (const dependent of dependents) {
+                    const adapted = context.changedProjects.includes(dependent);
+                    if (!adapted) {
+                        violations.push({
+                            type: 'breaking-change',
+                            severity: 'error',
+                            message: `破坏性变更 '${change.name}' 需要 ${dependent} 适配`,
+                            fromProject: project,
+                            toProject: dependent,
+                            details: {
+                                interfaceName: change.name,
+                                location: change.file,
+                            },
+                        });
+                    }
+                }
+            }
+        }
+    }
+    return violations;
+}
+/**
+ * 检查文档-代码一致性
+ * 场景：文档写了接口，代码没实现
+ */
+async function checkDocCodeConsistency(docPath, projects) {
+    const violations = [];
+    // 解析文档中的接口定义
+    const docInterfaces = parseDocInterfaces(docPath);
+    for (const [project, interfaces] of Object.entries(docInterfaces)) {
+        if (!projects.includes(project))
+            continue;
+        const actualExports = extractExportedApis(project);
+        for (const docInterface of interfaces) {
+            const implemented = actualExports.find(e => e.name === docInterface.name);
+            if (!implemented) {
+                violations.push({
+                    type: 'missing-implementation',
+                    severity: 'error',
+                    message: `文档接口 '${docInterface.name}' 在 ${project} 中未实现`,
+                    fromProject: 'documentation',
+                    toProject: project,
+                    details: {
+                        interfaceName: docInterface.name,
+                        location: docPath,
+                    },
+                });
+            }
+            else if (!isCompatible(docInterface, implemented)) {
+                violations.push({
+                    type: 'doc-code-mismatch',
+                    severity: 'warning',
+                    message: `接口 '${docInterface.name}' 实现与文档不一致`,
+                    fromProject: 'documentation',
+                    toProject: project,
+                    details: {
+                        interfaceName: docInterface.name,
+                        expectedType: JSON.stringify(docInterface.signature),
+                        actualType: JSON.stringify(implemented.signature),
+                    },
+                });
+            }
+        }
+    }
+    return violations;
+}
+// ============ 辅助函数 ============
+function getApiChanges(project, baseBranch) {
+    try {
+        const output = (0, child_process_1.execSync)(`git diff ${baseBranch}...HEAD --name-only -- "projects/${project}/src/api/**/*"`, { encoding: 'utf-8' });
+        return output.trim().split('\n').filter(f => f).map(f => ({
+            file: f,
+            name: extractApiName(f),
+            changeType: detectChangeType(f),
+        }));
+    }
+    catch {
+        return [];
+    }
+}
+function isPublicApi(change) {
+    // 检查是否为公开 API（导出、非内部）
+    return !change.name.startsWith('_') && !change.file.includes('/internal/');
+}
+function isBreakingChange(change) {
+    // 检测是否为破坏性变更
+    return change.changeType === 'remove' ||
+        change.changeType === 'signature-change' ||
+        change.changeType === 'rename';
+}
+function getDependents(project) {
+    return Object.entries(PROJECT_DEPENDENCIES)
+        .filter(([_, deps]) => deps.includes(project))
+        .map(([name, _]) => name);
+}
+// 占位函数（需要具体实现）
+function extractApiName(file) {
+    return path.basename(file, '.ts');
+}
+function detectChangeType(file) {
+    return 'modify';
+}
+function extractExportedTypes(project) {
+    return [];
+}
+function extractTypeUsage(project, types) {
+    return {};
+}
+function parseDocInterfaces(docPath) {
+    return {};
+}
+function extractExportedApis(project) {
+    return [];
+}
+function isCompatible(doc, actual) {
+    return JSON.stringify(doc.signature) === JSON.stringify(actual.signature);
+}
+//# sourceMappingURL=cross-project-checker.js.map

package/dist/architecture/cross-project-checker.js.map

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

package/dist/context/progressive-loader.d.ts

@@ -0,0 +1,110 @@
+/**
+ * @spec HZ-002
+ * @implements HZ-002-C1
+ * @acceptance AC-001-1, AC-001-4
+ *
+ * Progressive Content Loader
+ *
+ * 通用内容分片加载能力
+ * - 支持大数据集分片加载
+ * - 支持 Token 预算管理
+ * - 零业务逻辑，可被任意系统使用
+ */
+export interface ChunkLoadOptions<T = any> {
+    /** 每片大小 */
+    chunkSize: number;
+    /** 每片加载回调 */
+    onChunk?: (chunk: T[], index: number) => Promise<void> | void;
+    /** 进度回调 (loaded, total) */
+    onProgress?: (loaded: number, total: number) => void;
+    /** 是否并行加载 */
+    parallel?: boolean;
+    /** 延迟（毫秒），用于节流 */
+    delay?: number;
+}
+export interface TokenBudgetOptions<T = any> {
+    /** Token 预算 */
+    budget: number;
+    /** Token 估算函数 */
+    estimator: (item: T) => number;
+    /** 预算超限策略 */
+    onBudgetExceeded?: 'truncate' | 'error' | 'skip';
+    /** 最小保留项数（即使超预算） */
+    minItems?: number;
+}
+export interface LoadResult<T> {
+    /** 加载的项 */
+    items: T[];
+    /** 实际消耗的 Token */
+    tokensUsed: number;
+    /** 是否被截断 */
+    truncated: boolean;
+    /** 跳过的项数 */
+    skipped: number;
+}
+/**
+ * 渐进式内容加载器
+ *
+ * 提供通用的内容分片加载和 Token 预算管理能力
+ */
+export declare class ProgressiveLoader {
+    /**
+     * 分片加载
+     *
+     * 将大数据集分片加载，避免一次性加载全部内容
+     *
+     * @example
+     * ```typescript
+     * const loader = new ProgressiveLoader();
+     * const largeData = Array.from({ length: 1000 }, (_, i) => ({ id: i }));
+     *
+     * await loader.loadInChunks(largeData, {
+     *   chunkSize: 100,
+     *   onChunk: async (chunk, index) => {
+     *     console.log(`Loaded chunk ${index}: ${chunk.length} items`);
+     *   },
+     *   onProgress: (loaded, total) => {
+     *     console.log(`Progress: ${loaded}/${total}`);
+     *   }
+     * });
+     * ```
+     */
+    loadInChunks<T>(items: T[], options: ChunkLoadOptions<T>): Promise<void>;
+    /**
+     * Token 预算加载
+     *
+     * 在 Token 预算范围内加载内容，超预算时按策略处理
+     *
+     * @example
+     * ```typescript
+     * const loader = new ProgressiveLoader();
+     * const items = [
+     *   { content: 'short text' },
+     *   { content: 'long text '.repeat(100) }
+     * ];
+     *
+     * const result = await loader.loadWithBudget(items, {
+     *   budget: 1000,
+     *   estimator: (item) => item.content.length,
+     *   onBudgetExceeded: 'truncate'
+     * });
+     *
+     * console.log(`Loaded ${result.items.length} items, used ${result.tokensUsed} tokens`);
+     * ```
+     */
+    loadWithBudget<T>(items: T[], options: TokenBudgetOptions<T>): Promise<LoadResult<T>>;
+    /**
+     * 创建流式加载器
+     *
+     * 支持大文件/大内容的流式分片加载
+     */
+    createStream<T>(source: AsyncIterable<T>, chunkSize: number): AsyncIterable<T[]>;
+    /**
+     * 批量处理（带并发控制）
+     */
+    processBatch<T, R>(items: T[], processor: (item: T) => Promise<R>, concurrency?: number): Promise<R[]>;
+    private processChunk;
+    private sleep;
+}
+export declare const progressiveLoader: ProgressiveLoader;
+//# sourceMappingURL=progressive-loader.d.ts.map

package/dist/context/progressive-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"progressive-loader.d.ts","sourceRoot":"","sources":["../../src/context/progressive-loader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,MAAM,WAAW,gBAAgB,CAAC,CAAC,GAAG,GAAG;IACvC,WAAW;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa;IACb,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC9D,2BAA2B;IAC3B,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACrD,aAAa;IACb,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,kBAAkB;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,kBAAkB,CAAC,CAAC,GAAG,GAAG;IACzC,eAAe;IACf,MAAM,EAAE,MAAM,CAAC;IACf,iBAAiB;IACjB,SAAS,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,MAAM,CAAC;IAC/B,aAAa;IACb,gBAAgB,CAAC,EAAE,UAAU,GAAG,OAAO,GAAG,MAAM,CAAC;IACjD,oBAAoB;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,UAAU,CAAC,CAAC;IAC3B,WAAW;IACX,KAAK,EAAE,CAAC,EAAE,CAAC;IACX,kBAAkB;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY;IACZ,SAAS,EAAE,OAAO,CAAC;IACnB,YAAY;IACZ,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;GAIG;AACH,qBAAa,iBAAiB;IAC5B;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,YAAY,CAAC,CAAC,EAClB,KAAK,EAAE,CAAC,EAAE,EACV,OAAO,EAAE,gBAAgB,CAAC,CAAC,CAAC,GAC3B,OAAO,CAAC,IAAI,CAAC;IAgChB;;;;;;;;;;;;;;;;;;;;;OAqBG;IACG,cAAc,CAAC,CAAC,EACpB,KAAK,EAAE,CAAC,EAAE,EACV,OAAO,EAAE,kBAAkB,CAAC,CAAC,CAAC,GAC7B,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;IAkDzB;;;;OAIG;IACI,YAAY,CAAC,CAAC,EACnB,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC,EACxB,SAAS,EAAE,MAAM,GAChB,aAAa,CAAC,CAAC,EAAE,CAAC;IAkBrB;;OAEG;IACG,YAAY,CAAC,CAAC,EAAE,CAAC,EACrB,KAAK,EAAE,CAAC,EAAE,EACV,SAAS,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,EAClC,WAAW,GAAE,MAAU,GACtB,OAAO,CAAC,CAAC,EAAE,CAAC;YAwBD,YAAY;IAiB1B,OAAO,CAAC,KAAK;CAGd;AAGD,eAAO,MAAM,iBAAiB,mBAA0B,CAAC"}

package/dist/context/progressive-loader.js

@@ -0,0 +1,183 @@
+"use strict";
+/**
+ * @spec HZ-002
+ * @implements HZ-002-C1
+ * @acceptance AC-001-1, AC-001-4
+ *
+ * Progressive Content Loader
+ *
+ * 通用内容分片加载能力
+ * - 支持大数据集分片加载
+ * - 支持 Token 预算管理
+ * - 零业务逻辑，可被任意系统使用
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.progressiveLoader = exports.ProgressiveLoader = void 0;
+/**
+ * 渐进式内容加载器
+ *
+ * 提供通用的内容分片加载和 Token 预算管理能力
+ */
+class ProgressiveLoader {
+    /**
+     * 分片加载
+     *
+     * 将大数据集分片加载，避免一次性加载全部内容
+     *
+     * @example
+     * ```typescript
+     * const loader = new ProgressiveLoader();
+     * const largeData = Array.from({ length: 1000 }, (_, i) => ({ id: i }));
+     *
+     * await loader.loadInChunks(largeData, {
+     *   chunkSize: 100,
+     *   onChunk: async (chunk, index) => {
+     *     console.log(`Loaded chunk ${index}: ${chunk.length} items`);
+     *   },
+     *   onProgress: (loaded, total) => {
+     *     console.log(`Progress: ${loaded}/${total}`);
+     *   }
+     * });
+     * ```
+     */
+    async loadInChunks(items, options) {
+        const { chunkSize, onChunk, onProgress, parallel = false, delay = 0 } = options;
+        const total = items.length;
+        const chunks = [];
+        // 分片
+        for (let i = 0; i < total; i += chunkSize) {
+            chunks.push(items.slice(i, i + chunkSize));
+        }
+        // 加载
+        if (parallel) {
+            // 并行加载
+            await Promise.all(chunks.map(async (chunk, index) => {
+                if (delay > 0) {
+                    await this.sleep(delay * index);
+                }
+                await this.processChunk(chunk, index, onChunk, onProgress, total);
+            }));
+        }
+        else {
+            // 串行加载
+            for (let i = 0; i < chunks.length; i++) {
+                if (delay > 0 && i > 0) {
+                    await this.sleep(delay);
+                }
+                await this.processChunk(chunks[i], i, onChunk, onProgress, total);
+            }
+        }
+    }
+    /**
+     * Token 预算加载
+     *
+     * 在 Token 预算范围内加载内容，超预算时按策略处理
+     *
+     * @example
+     * ```typescript
+     * const loader = new ProgressiveLoader();
+     * const items = [
+     *   { content: 'short text' },
+     *   { content: 'long text '.repeat(100) }
+     * ];
+     *
+     * const result = await loader.loadWithBudget(items, {
+     *   budget: 1000,
+     *   estimator: (item) => item.content.length,
+     *   onBudgetExceeded: 'truncate'
+     * });
+     *
+     * console.log(`Loaded ${result.items.length} items, used ${result.tokensUsed} tokens`);
+     * ```
+     */
+    async loadWithBudget(items, options) {
+        const { budget, estimator, onBudgetExceeded = 'truncate', minItems = 1 } = options;
+        const result = {
+            items: [],
+            tokensUsed: 0,
+            truncated: false,
+            skipped: 0
+        };
+        let currentBudget = budget;
+        for (const item of items) {
+            const itemTokens = estimator(item);
+            // 检查预算
+            if (itemTokens > currentBudget) {
+                // 预算超限
+                if (result.items.length >= minItems) {
+                    // 已达到最小项数，按策略处理
+                    switch (onBudgetExceeded) {
+                        case 'truncate':
+                            result.truncated = true;
+                            return result;
+                        case 'error':
+                            throw new Error(`Token budget exceeded: need ${itemTokens}, remaining ${currentBudget}`);
+                        case 'skip':
+                            result.skipped++;
+                            continue;
+                    }
+                }
+                // 未达到最小项数，强制添加（可能超预算）
+            }
+            // 添加项
+            result.items.push(item);
+            result.tokensUsed += itemTokens;
+            currentBudget -= itemTokens;
+        }
+        return result;
+    }
+    /**
+     * 创建流式加载器
+     *
+     * 支持大文件/大内容的流式分片加载
+     */
+    async *createStream(source, chunkSize) {
+        let chunk = [];
+        for await (const item of source) {
+            chunk.push(item);
+            if (chunk.length >= chunkSize) {
+                yield chunk;
+                chunk = [];
+            }
+        }
+        //  yield remaining items
+        if (chunk.length > 0) {
+            yield chunk;
+        }
+    }
+    /**
+     * 批量处理（带并发控制）
+     */
+    async processBatch(items, processor, concurrency = 5) {
+        const results = [];
+        const executing = [];
+        for (const item of items) {
+            const promise = processor(item).then(result => {
+                results.push(result);
+            });
+            executing.push(promise);
+            if (executing.length >= concurrency) {
+                await Promise.race(executing);
+                executing.splice(executing.findIndex(p => p === promise), 1);
+            }
+        }
+        await Promise.all(executing);
+        return results;
+    }
+    async processChunk(chunk, index, onChunk, onProgress, total) {
+        if (onChunk) {
+            await onChunk(chunk, index);
+        }
+        if (onProgress) {
+            const loaded = Math.min((index + 1) * chunk.length, total);
+            onProgress(loaded, total);
+        }
+    }
+    sleep(ms) {
+        return new Promise(resolve => setTimeout(resolve, ms));
+    }
+}
+exports.ProgressiveLoader = ProgressiveLoader;
+// 默认实例
+exports.progressiveLoader = new ProgressiveLoader();
+//# sourceMappingURL=progressive-loader.js.map

package/dist/context/progressive-loader.js.map

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