@dommaker/harness 1.2.3 → 1.4.0

package/dist/cli/commands/knowledge.js

@@ -43,6 +43,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.knowledgeList = knowledgeList;
 exports.knowledgeSearch = knowledgeSearch;
+exports.knowledgeSearchCommand = knowledgeSearchCommand;
 exports.knowledgeImport = knowledgeImport;
 exports.knowledgeDecay = knowledgeDecay;
 exports.knowledgeStats = knowledgeStats;
@@ -63,13 +64,15 @@ const query_1 = require("../../knowledge/query");
 const lifecycle_1 = require("../../knowledge/lifecycle");
 const import_1 = require("../../knowledge/import");
 const audit_1 = require("../../knowledge/audit");
+const flywheel_metrics_1 = require("../../knowledge/flywheel-metrics");
 const migration_1 = require("../../knowledge/migration");
 const index_generator_1 = require("../../knowledge/index-generator");
+const command_contract_1 = require("../command-contract");
 /**
  * 知识库列表
  */
-async function knowledgeList(options) {
-    const store = new store_1.FileKnowledgeStore({ baseDir: getKnowledgeDir(options.projectPath) });
+async function knowledgeList(options, io = command_contract_1.processIO) {
+    const store = new store_1.FileKnowledgeStore({ baseDir: getKnowledgeDir(options.projectPath, io) });
     const filter = { excludeArchived: false };
     if (options.type) {
         filter.types = options.type.split(',');
@@ -82,54 +85,72 @@ async function knowledgeList(options) {
     }
     const entries = store.list(filter);
     if (options.json) {
-        console.log(JSON.stringify({ total: entries.length, entries }, null, 2));
-        return;
+        (0, command_contract_1.log)(io, JSON.stringify({ total: entries.length, entries }, null, 2));
+        return { kind: 'ok' };
     }
     if (entries.length === 0) {
-        console.log(chalk_1.default.yellow('知识库为空'));
-        return;
+        (0, command_contract_1.log)(io, chalk_1.default.yellow('知识库为空'));
+        return { kind: 'ok' };
     }
-    console.log(chalk_1.default.blue(`📚 知识库 (${entries.length} 条)\n`));
+    (0, command_contract_1.log)(io, chalk_1.default.blue(`📚 知识库 (${entries.length} 条)\n`));
     for (const entry of entries) {
         const maturityColor = entry.maturity === 'proven' ? chalk_1.default.green
             : entry.maturity === 'verified' ? chalk_1.default.cyan
                 : entry.maturity === 'archived' ? chalk_1.default.gray
                     : chalk_1.default.yellow;
-        console.log(`  ${maturityColor(`[${entry.maturity}]`)} ${chalk_1.default.bold(entry.title)}`);
-        console.log(`    ${chalk_1.default.gray(`id: ${entry.id} | type: ${entry.type} | layer: ${entry.layer}`)}`);
+        (0, command_contract_1.log)(io, `  ${maturityColor(`[${entry.maturity}]`)} ${chalk_1.default.bold(entry.title)}`);
+        (0, command_contract_1.log)(io, `    ${chalk_1.default.gray(`id: ${entry.id} | type: ${entry.type} | layer: ${entry.layer}`)}`);
         if (entry.tags.length > 0) {
-            console.log(`    ${chalk_1.default.gray(`tags: ${entry.tags.join(', ')}`)}`);
+            (0, command_contract_1.log)(io, `    ${chalk_1.default.gray(`tags: ${entry.tags.join(', ')}`)}`);
         }
     }
+    return { kind: 'ok' };
 }
 /**
  * 知识库搜索
  */
-async function knowledgeSearch(query, options) {
-    const store = new store_1.FileKnowledgeStore({ baseDir: getKnowledgeDir(options.projectPath) });
+async function knowledgeSearch(query, options, io = command_contract_1.processIO) {
+    const store = new store_1.FileKnowledgeStore({ baseDir: getKnowledgeDir(options.projectPath, io) });
     const queryEngine = new query_1.KnowledgeQuery(store);
     const matched = queryEngine.search(query, { limit: options.limit || 20 });
     if (options.json) {
-        console.log(JSON.stringify({ query, total: matched.length, entries: matched }, null, 2));
-        return;
+        (0, command_contract_1.log)(io, JSON.stringify({ query, total: matched.length, entries: matched }, null, 2));
+        return { kind: 'ok' };
     }
     if (matched.length === 0) {
-        console.log(chalk_1.default.yellow(`未找到匹配 "${query}" 的知识条目`));
-        return;
+        (0, command_contract_1.log)(io, chalk_1.default.yellow(`未找到匹配 "${query}" 的知识条目`));
+        return { kind: 'ok' };
     }
-    console.log(chalk_1.default.blue(`🔍 搜索 "${query}" (${matched.length} 条结果)\n`));
+    (0, command_contract_1.log)(io, chalk_1.default.blue(`🔍 搜索 "${query}" (${matched.length} 条结果)\n`));
     for (const entry of matched) {
-        console.log(`  ${chalk_1.default.bold(entry.title)} ${chalk_1.default.gray(`[${entry.maturity}]`)}`);
+        (0, command_contract_1.log)(io, `  ${chalk_1.default.bold(entry.title)} ${chalk_1.default.gray(`[${entry.maturity}]`)}`);
         const preview = entry.content.slice(0, 100).replace(/\n/g, ' ');
-        console.log(`    ${chalk_1.default.gray(preview)}${entry.content.length > 100 ? '...' : ''}`);
+        (0, command_contract_1.log)(io, `    ${chalk_1.default.gray(preview)}${entry.content.length > 100 ? '...' : ''}`);
     }
+    return { kind: 'ok' };
+}
+/**
+ * knowledge search 子命令入口（候选7）：缺参闸门 + limit 强转编组，
+ * 自 definitions.ts 的 args 复印块移回命令模块（interface/测试面所在）。
+ */
+async function knowledgeSearchCommand(positionals, options, io = command_contract_1.processIO) {
+    const query = positionals[0];
+    if (!query) {
+        (0, command_contract_1.logError)(io, '请提供搜索关键词');
+        return { kind: 'usage-error', reason: 'knowledge search 缺少关键词位置参数' };
+    }
+    return knowledgeSearch(String(query), {
+        projectPath: options.projectPath,
+        json: options.json,
+        limit: parseInt(String(options.limit), 10),
+    });
 }
 /**
  * 知识库导入（冷启动）
  */
-async function knowledgeImport(options) {
+async function knowledgeImport(options, io = command_contract_1.processIO) {
     const projectPath = options.projectPath || process.cwd();
-    const store = new store_1.FileKnowledgeStore({ baseDir: getKnowledgeDir(options.projectPath) });
+    const store = new store_1.FileKnowledgeStore({ baseDir: getKnowledgeDir(options.projectPath, io) });
     const sources = options.sources
         ? options.sources.split(',')
         : ['code', 'git', 'docs'];
@@ -141,60 +162,62 @@ async function knowledgeImport(options) {
     if (options.reset) {
         importer.resetState();
         if (!options.json) {
-            console.log(chalk_1.default.yellow('🔄 已重置导入状态'));
+            (0, command_contract_1.log)(io, chalk_1.default.yellow('🔄 已重置导入状态'));
         }
     }
     if (!options.json) {
-        console.log(chalk_1.default.blue(`📥 开始导入知识 (源: ${sources.join(', ')})...`));
+        (0, command_contract_1.log)(io, chalk_1.default.blue(`📥 开始导入知识 (源: ${sources.join(', ')})...`));
     }
     const results = await importer.importAll();
     const totalImported = results.reduce((sum, r) => sum + r.entries.length, 0);
     const totalErrors = results.reduce((sum, r) => sum + r.errors.length, 0);
     if (options.json) {
-        console.log(JSON.stringify({ totalImported, totalErrors, results }, null, 2));
-        return;
+        (0, command_contract_1.log)(io, JSON.stringify({ totalImported, totalErrors, results }, null, 2));
+        return { kind: 'ok' };
     }
     for (const result of results) {
         if (result.entries.length > 0) {
-            console.log(chalk_1.default.green(`  ✅ ${result.source.type}: ${result.entries.length} 条`));
+            (0, command_contract_1.log)(io, chalk_1.default.green(`  ✅ ${result.source.type}: ${result.entries.length} 条`));
         }
         if (result.errors.length > 0) {
             for (const err of result.errors) {
-                console.log(chalk_1.default.red(`  ❌ ${result.source.type}: ${err.message}`));
+                (0, command_contract_1.log)(io, chalk_1.default.red(`  ❌ ${result.source.type}: ${err.message}`));
             }
         }
     }
-    console.log(chalk_1.default.green(`\n✅ 导入完成: ${totalImported} 条，${totalErrors} 个错误`));
+    (0, command_contract_1.log)(io, chalk_1.default.green(`\n✅ 导入完成: ${totalImported} 条，${totalErrors} 个错误`));
+    return { kind: 'ok' };
 }
 /**
  * 知识库衰减周期
  */
-async function knowledgeDecay(options) {
-    const store = new store_1.FileKnowledgeStore({ baseDir: getKnowledgeDir(options.projectPath) });
+async function knowledgeDecay(options, io = command_contract_1.processIO) {
+    const store = new store_1.FileKnowledgeStore({ baseDir: getKnowledgeDir(options.projectPath, io) });
     const lifecycle = new lifecycle_1.KnowledgeLifecycle(store);
     if (!options.json) {
-        console.log(chalk_1.default.blue('🔄 运行衰减周期...'));
+        (0, command_contract_1.log)(io, chalk_1.default.blue('🔄 运行衰减周期...'));
     }
     const changes = lifecycle.runDecayCycle();
     if (options.json) {
-        console.log(JSON.stringify({ changes }, null, 2));
-        return;
+        (0, command_contract_1.log)(io, JSON.stringify({ changes }, null, 2));
+        return { kind: 'ok' };
     }
     if (changes.length === 0) {
-        console.log(chalk_1.default.green('✅ 没有需要衰减的知识条目'));
-        return;
+        (0, command_contract_1.log)(io, chalk_1.default.green('✅ 没有需要衰减的知识条目'));
+        return { kind: 'ok' };
     }
-    console.log(chalk_1.default.yellow(`📉 ${changes.length} 条知识发生衰减:\n`));
+    (0, command_contract_1.log)(io, chalk_1.default.yellow(`📉 ${changes.length} 条知识发生衰减:\n`));
     for (const change of changes) {
-        console.log(`  ${change.entryId}: ${chalk_1.default.red(change.from)} → ${chalk_1.default.green(change.to)}`);
-        console.log(`    ${chalk_1.default.gray(change.reason)}`);
+        (0, command_contract_1.log)(io, `  ${change.entryId}: ${chalk_1.default.red(change.from)} → ${chalk_1.default.green(change.to)}`);
+        (0, command_contract_1.log)(io, `    ${chalk_1.default.gray(change.reason)}`);
     }
+    return { kind: 'ok' };
 }
 /**
  * 知识库统计
  */
-async function knowledgeStats(options) {
-    const store = new store_1.FileKnowledgeStore({ baseDir: getKnowledgeDir(options.projectPath) });
+async function knowledgeStats(options, io = command_contract_1.processIO) {
+    const store = new store_1.FileKnowledgeStore({ baseDir: getKnowledgeDir(options.projectPath, io) });
     const entries = store.list({ excludeArchived: false });
     const active = entries.filter(e => e.maturity !== 'archived');
     const byType = {};
@@ -205,53 +228,52 @@ async function knowledgeStats(options) {
         byMaturity[entry.maturity] = (byMaturity[entry.maturity] || 0) + 1;
         byLayer[entry.layer] = (byLayer[entry.layer] || 0) + 1;
     }
-    // D6 flywheel metrics
-    const withRefs = active.filter(e => e.referencedBy.length > 0).length;
-    const refCoverage = active.length > 0 ? Math.round(withRefs / active.length * 100) : 0;
-    const avgRefs = active.length > 0
-        ? Math.round(active.reduce((sum, e) => sum + e.referencedBy.length, 0) / active.length * 10) / 10
-        : 0;
-    let consumptionHitRate = 0;
+    // 飞轮指标：计算唯一实现在 knowledge/flywheel-metrics，此处只做 fs 读取 + 展示层单位映射
+    let dailyConsumptionEvents = 0;
     try {
         const statsPath = path.join(store.getBaseDir(), '.consumption-stats.json');
         if (fs.existsSync(statsPath)) {
             const stats = JSON.parse(fs.readFileSync(statsPath, 'utf-8'));
-            const dailyEvents = stats.dailyEvents || 0;
-            consumptionHitRate = active.length > 0 ? Math.min(Math.round(dailyEvents / active.length * 100), 100) : 0;
+            dailyConsumptionEvents = stats.dailyEvents || 0;
         }
     }
     catch { /* best-effort */ }
+    const metrics = (0, flywheel_metrics_1.evaluateFlywheel)({ entries: active, dailyConsumptionEvents });
+    const refCoverage = Math.round(metrics.refCoverage * 100);
+    const avgRefs = Math.round(metrics.avgRefs * 10) / 10;
+    const consumptionHitRate = Math.round(metrics.consumptionHitRate * 100);
     const flywheel = { refCoverage, avgRefs, consumptionHitRate };
     if (options.json) {
-        console.log(JSON.stringify({ total: entries.length, byType, byMaturity, byLayer, flywheel }, null, 2));
-        return;
+        (0, command_contract_1.log)(io, JSON.stringify({ total: entries.length, byType, byMaturity, byLayer, flywheel }, null, 2));
+        return { kind: 'ok' };
     }
-    console.log(chalk_1.default.blue(`📊 知识库统计\n`));
-    console.log(chalk_1.default.bold(`  总计: ${entries.length} 条 (活跃: ${active.length})\n`));
-    console.log(chalk_1.default.bold('  按类型:'));
+    (0, command_contract_1.log)(io, chalk_1.default.blue(`📊 知识库统计\n`));
+    (0, command_contract_1.log)(io, chalk_1.default.bold(`  总计: ${entries.length} 条 (活跃: ${active.length})\n`));
+    (0, command_contract_1.log)(io, chalk_1.default.bold('  按类型:'));
     for (const [type, count] of Object.entries(byType)) {
-        console.log(`    ${type}: ${count}`);
+        (0, command_contract_1.log)(io, `    ${type}: ${count}`);
     }
-    console.log(chalk_1.default.bold('\n  按成熟度:'));
+    (0, command_contract_1.log)(io, chalk_1.default.bold('\n  按成熟度:'));
     for (const [maturity, count] of Object.entries(byMaturity)) {
         const color = maturity === 'proven' ? chalk_1.default.green : maturity === 'archived' ? chalk_1.default.gray : chalk_1.default.yellow;
-        console.log(`    ${color(maturity)}: ${count}`);
+        (0, command_contract_1.log)(io, `    ${color(maturity)}: ${count}`);
     }
-    console.log(chalk_1.default.bold('\n  按层级:'));
+    (0, command_contract_1.log)(io, chalk_1.default.bold('\n  按层级:'));
     for (const [layer, count] of Object.entries(byLayer)) {
-        console.log(`    ${layer}: ${count}`);
+        (0, command_contract_1.log)(io, `    ${layer}: ${count}`);
     }
-    console.log(chalk_1.default.bold('\n  飞轮指标:'));
-    console.log(`    引用覆盖: ${refCoverage}%`);
-    console.log(`    平均引用: ${avgRefs}`);
-    console.log(`    消费命中率: ${consumptionHitRate}%`);
+    (0, command_contract_1.log)(io, chalk_1.default.bold('\n  飞轮指标:'));
+    (0, command_contract_1.log)(io, `    引用覆盖: ${refCoverage}%`);
+    (0, command_contract_1.log)(io, `    平均引用: ${avgRefs}`);
+    (0, command_contract_1.log)(io, `    消费命中率: ${consumptionHitRate}%`);
+    return { kind: 'ok' };
 }
 /**
  * 设计时知识沉淀：写入 KnowledgeStore + 同步 Prisma Document（Studio UI 可见）
  *
  * 调用 Studio API POST /api/knowledge/upsert（内部端点，无 auth）
  */
-async function knowledgeUpsert(options) {
+async function knowledgeUpsert(options, io = command_contract_1.processIO) {
     const apiPort = process.env.API_PORT || '3001';
     const url = `http://localhost:${apiPort}/api/knowledge/upsert`;
     // Read content from file if --file specified
@@ -261,14 +283,14 @@ async function knowledgeUpsert(options) {
             content = fs.readFileSync(options.file, 'utf-8');
         }
         catch (e) {
-            console.error(chalk_1.default.red(`Failed to read file: ${options.file}`));
-            console.error(chalk_1.default.red(String(e)));
-            process.exit(1);
+            (0, command_contract_1.logError)(io, chalk_1.default.red(`Failed to read file: ${options.file}`));
+            (0, command_contract_1.logError)(io, chalk_1.default.red(String(e)));
+            return { kind: 'fail', reason: `无法读取 --file ${options.file}: ${String(e)}` };
         }
     }
     if (!options.scope || !options.title || !content) {
-        console.error(chalk_1.default.red('--scope, --title, and --content (or --file) are required'));
-        process.exit(1);
+        (0, command_contract_1.logError)(io, chalk_1.default.red('--scope, --title, and --content (or --file) are required'));
+        return { kind: 'usage-error', reason: '--scope/--title/--content(--file) 缺一不可' };
     }
     try {
         const res = await fetch(url, {
@@ -284,100 +306,103 @@ async function knowledgeUpsert(options) {
         });
         if (!res.ok) {
             const err = await res.json().catch(() => ({ error: res.statusText }));
-            console.error(chalk_1.default.red(`API error ${res.status}: ${err.error || res.statusText}`));
-            process.exit(1);
+            (0, command_contract_1.logError)(io, chalk_1.default.red(`API error ${res.status}: ${err.error || res.statusText}`));
+            return { kind: 'fail', reason: `upsert API error ${res.status}: ${err.error || res.statusText}` };
         }
         const result = await res.json();
-        console.log(chalk_1.default.green(`✅ Knowledge upserted`));
-        console.log(`   KnowledgeStore: ${result.knowledgeStore?.action} → ${result.knowledgeStore?.entryId}`);
-        console.log(`   Studio UI: ${result.prismaDocument?.action} → ${result.prismaDocument?.docId || 'skipped'}`);
+        (0, command_contract_1.log)(io, chalk_1.default.green(`✅ Knowledge upserted`));
+        (0, command_contract_1.log)(io, `   KnowledgeStore: ${result.knowledgeStore?.action} → ${result.knowledgeStore?.entryId}`);
+        (0, command_contract_1.log)(io, `   Studio UI: ${result.prismaDocument?.action} → ${result.prismaDocument?.docId || 'skipped'}`);
+        return { kind: 'ok' };
     }
     catch (e) {
         if (e?.code === 'ECONNREFUSED') {
-            console.error(chalk_1.default.red(`Cannot reach Studio API at ${url}. Is the API running?`));
+            (0, command_contract_1.logError)(io, chalk_1.default.red(`Cannot reach Studio API at ${url}. Is the API running?`));
         }
         else {
-            console.error(chalk_1.default.red(`Upsert failed: ${e.message}`));
+            (0, command_contract_1.logError)(io, chalk_1.default.red(`Upsert failed: ${e.message}`));
         }
-        process.exit(1);
+        return { kind: 'fail', reason: `knowledge upsert 失败: ${e?.code === 'ECONNREFUSED' ? `Studio API 不可达 ${url}` : e.message}` };
     }
 }
 /**
 /**
  * RAG 同步：扫描 .harness/knowledge-docs/ 输出需要 ingest 的文件列表
  */
-async function knowledgeSyncRag(options) {
+async function knowledgeSyncRag(options, io = command_contract_1.processIO) {
     const projectPath = options.projectPath || process.cwd();
     const docsDir = `${projectPath}/.harness/knowledge-docs`;
     if (!fs.existsSync(docsDir)) {
-        console.log(chalk_1.default.yellow('No .harness/knowledge-docs/ directory'));
-        return;
+        (0, command_contract_1.log)(io, chalk_1.default.yellow('No .harness/knowledge-docs/ directory'));
+        return { kind: 'ok' };
     }
     const files = fs.readdirSync(docsDir).filter(f => f.endsWith('.md'));
     if (files.length === 0) {
-        console.log(chalk_1.default.gray('No knowledge docs found'));
-        return;
+        (0, command_contract_1.log)(io, chalk_1.default.gray('No knowledge docs found'));
+        return { kind: 'ok' };
     }
     if (options.json) {
-        console.log(JSON.stringify({ directory: docsDir, files }, null, 2));
-        return;
+        (0, command_contract_1.log)(io, JSON.stringify({ directory: docsDir, files }, null, 2));
+        return { kind: 'ok' };
     }
-    console.log(chalk_1.default.blue(`📄 RAG sync candidates: ${files.length} files in ${docsDir}\n`));
+    (0, command_contract_1.log)(io, chalk_1.default.blue(`📄 RAG sync candidates: ${files.length} files in ${docsDir}\n`));
     for (const file of files) {
-        console.log(chalk_1.default.cyan(`  ${file}`));
+        (0, command_contract_1.log)(io, chalk_1.default.cyan(`  ${file}`));
     }
-    console.log();
-    console.log(chalk_1.default.gray('Run `mcp__local-rag__ingest_file` for each to sync to RAG'));
+    (0, command_contract_1.log)(io);
+    (0, command_contract_1.log)(io, chalk_1.default.gray('Run `mcp__local-rag__ingest_file` for each to sync to RAG'));
+    return { kind: 'ok' };
 }
 /**
  * 知识同步状态：检测所有 tracked scope 的新鲜度
  */
-async function knowledgeSyncStatus(options) {
+async function knowledgeSyncStatus(options, io = command_contract_1.processIO) {
     const apiPort = process.env.API_PORT || '3001';
     const url = `http://localhost:${apiPort}/api/knowledge/sync-status`;
     try {
         const res = await fetch(url);
         if (!res.ok) {
             const err = await res.json().catch(() => ({ error: res.statusText }));
-            console.error(chalk_1.default.red(`API error ${res.status}: ${err.error || res.statusText}`));
-            process.exit(1);
+            (0, command_contract_1.logError)(io, chalk_1.default.red(`API error ${res.status}: ${err.error || res.statusText}`));
+            return { kind: 'fail', reason: `sync-status API error ${res.status}: ${err.error || res.statusText}` };
         }
         const data = await res.json();
         if (options.json) {
-            console.log(JSON.stringify(data, null, 2));
-            return;
+            (0, command_contract_1.log)(io, JSON.stringify(data, null, 2));
+            return { kind: 'ok' };
         }
-        console.log(chalk_1.default.blue(`🔄 KnowledgeSync Status\n`));
-        console.log(chalk_1.default.bold(`Tracked scopes: ${data.trackedScopes?.join(', ') || 'none'}`));
-        console.log(chalk_1.default.bold(`Stale entries: ${data.stale?.length || 0}`));
+        (0, command_contract_1.log)(io, chalk_1.default.blue(`🔄 KnowledgeSync Status\n`));
+        (0, command_contract_1.log)(io, chalk_1.default.bold(`Tracked scopes: ${data.trackedScopes?.join(', ') || 'none'}`));
+        (0, command_contract_1.log)(io, chalk_1.default.bold(`Stale entries: ${data.stale?.length || 0}`));
         if (data.stale?.length > 0) {
-            console.log(chalk_1.default.yellow(`\n⚠️  Stale knowledge:\n`));
+            (0, command_contract_1.log)(io, chalk_1.default.yellow(`\n⚠️  Stale knowledge:\n`));
             for (const s of data.stale) {
-                console.log(chalk_1.default.yellow(`  ${s.scope} (${s.title}): ${s.stalenessHours}h old, files changed: ${s.changedFiles.join(', ')}`));
+                (0, command_contract_1.log)(io, chalk_1.default.yellow(`  ${s.scope} (${s.title}): ${s.stalenessHours}h old, files changed: ${s.changedFiles.join(', ')}`));
             }
         }
         else {
-            console.log(chalk_1.default.green('\n✅ All knowledge fresh'));
+            (0, command_contract_1.log)(io, chalk_1.default.green('\n✅ All knowledge fresh'));
         }
         if (data.healed?.length > 0) {
-            console.log(chalk_1.default.cyan(`\n🩹 Auto-healed: ${data.healed.join(', ')}`));
+            (0, command_contract_1.log)(io, chalk_1.default.cyan(`\n🩹 Auto-healed: ${data.healed.join(', ')}`));
         }
     }
     catch (e) {
         if (e?.code === 'ECONNREFUSED') {
-            console.error(chalk_1.default.red(`Cannot reach Studio API at ${url}`));
+            (0, command_contract_1.logError)(io, chalk_1.default.red(`Cannot reach Studio API at ${url}`));
         }
         else {
-            console.error(chalk_1.default.red(`Sync check failed: ${e.message}`));
+            (0, command_contract_1.logError)(io, chalk_1.default.red(`Sync check failed: ${e.message}`));
         }
-        process.exit(1);
+        return { kind: 'fail', reason: `knowledge sync status 检查失败: ${e?.code === 'ECONNREFUSED' ? `Studio API 不可达 ${url}` : e.message}` };
     }
+    return { kind: 'ok' };
 }
 /**
  * 飞轮健康检查 — 零 token 检测知识飞轮数据流状态
  */
-async function knowledgeHealth(options) {
-    const baseDir = options.dir || getKnowledgeDir(options.projectPath);
+async function knowledgeHealth(options, io = command_contract_1.processIO) {
+    const baseDir = options.dir || getKnowledgeDir(options.projectPath, io);
     const store = new store_1.FileKnowledgeStore({ baseDir });
     const entries = store.list({ excludeArchived: true });
     const issues = [];
@@ -409,18 +434,16 @@ async function knowledgeHealth(options) {
     else {
         issues.push({ severity: 'info', entry: '-', detail: `消费追踪数据不存在（${statsPath}）` });
     }
-    // D4: 飞轮指标
-    const withRefs = entries.filter(e => e.referencedBy.length > 0).length;
-    const refCoverage = entries.length > 0 ? Math.round(withRefs / entries.length * 100) : 0;
-    const avgRefs = entries.length > 0
-        ? Math.round(entries.reduce((sum, e) => sum + e.referencedBy.length, 0) / entries.length * 10) / 10
-        : 0;
+    // D4: 飞轮指标（计算唯一实现在 knowledge/flywheel-metrics；人口为本命令的 excludeArchived 切片）
+    const metrics = (0, flywheel_metrics_1.evaluateFlywheel)({ entries });
+    const refCoverage = Math.round(metrics.refCoverage * 100);
+    const avgRefs = Math.round(metrics.avgRefs * 10) / 10;
     // 健康分计算
     const totalIssues = issues.filter(i => i.severity === 'error').length * 3
         + issues.filter(i => i.severity === 'warn').length * 1;
     const healthScore = Math.max(0, 100 - totalIssues);
     if (options.json) {
-        console.log(JSON.stringify({
+        (0, command_contract_1.log)(io, JSON.stringify({
             healthScore,
             summary: {
                 total: entries.length,
@@ -432,70 +455,94 @@ async function knowledgeHealth(options) {
             },
             issues: issues.slice(0, 50),
         }, null, 2));
-        return;
-    }
-    console.log(chalk_1.default.blue('🏥 飞轮健康检查\n'));
-    console.log(chalk_1.default.bold(`  健康分: ${healthScore >= 80 ? chalk_1.default.green(healthScore) : healthScore >= 60 ? chalk_1.default.yellow(healthScore) : chalk_1.default.red(healthScore)}/100`));
-    console.log(chalk_1.default.bold(`  活跃条目: ${entries.length}`));
-    console.log();
-    console.log(chalk_1.default.bold('  数据流状态:'));
-    console.log(`    引用密度: ${lowRefEntries === 0 ? chalk_1.default.green('✓') : chalk_1.default.yellow(`⚠ ${lowRefEntries} 个零引用 verified`)}`);
-    console.log(`    新鲜度: ${staleEntries === 0 ? chalk_1.default.green('✓') : chalk_1.default.yellow(`⚠ ${staleEntries} 个过期 draft`)}`);
-    console.log(`    消费追踪: ${consumptionData ? chalk_1.default.green('✓') : chalk_1.default.gray('○ 未启用')}`);
-    console.log();
-    console.log(chalk_1.default.bold('  飞轮指标:'));
-    console.log(`    引用覆盖: ${refCoverage}%`);
-    console.log(`    平均引用: ${avgRefs}`);
-    console.log();
+        return { kind: 'ok' };
+    }
+    (0, command_contract_1.log)(io, chalk_1.default.blue('🏥 飞轮健康检查\n'));
+    (0, command_contract_1.log)(io, chalk_1.default.bold(`  健康分: ${healthScore >= 80 ? chalk_1.default.green(healthScore) : healthScore >= 60 ? chalk_1.default.yellow(healthScore) : chalk_1.default.red(healthScore)}/100`));
+    (0, command_contract_1.log)(io, chalk_1.default.bold(`  活跃条目: ${entries.length}`));
+    (0, command_contract_1.log)(io);
+    (0, command_contract_1.log)(io, chalk_1.default.bold('  数据流状态:'));
+    (0, command_contract_1.log)(io, `    引用密度: ${lowRefEntries === 0 ? chalk_1.default.green('✓') : chalk_1.default.yellow(`⚠ ${lowRefEntries} 个零引用 verified`)}`);
+    (0, command_contract_1.log)(io, `    新鲜度: ${staleEntries === 0 ? chalk_1.default.green('✓') : chalk_1.default.yellow(`⚠ ${staleEntries} 个过期 draft`)}`);
+    (0, command_contract_1.log)(io, `    消费追踪: ${consumptionData ? chalk_1.default.green('✓') : chalk_1.default.gray('○ 未启用')}`);
+    (0, command_contract_1.log)(io);
+    (0, command_contract_1.log)(io, chalk_1.default.bold('  飞轮指标:'));
+    (0, command_contract_1.log)(io, `    引用覆盖: ${refCoverage}%`);
+    (0, command_contract_1.log)(io, `    平均引用: ${avgRefs}`);
+    (0, command_contract_1.log)(io);
     if (issues.length > 0) {
-        console.log(chalk_1.default.bold(`  问题 (前 20):`));
+        (0, command_contract_1.log)(io, chalk_1.default.bold(`  问题 (前 20):`));
         for (const issue of issues.slice(0, 20)) {
             const sevColor = issue.severity === 'error' ? chalk_1.default.red
                 : issue.severity === 'warn' ? chalk_1.default.yellow
                     : chalk_1.default.gray;
-            console.log(`    ${sevColor(`[${issue.severity}]`)} ${issue.entry}: ${issue.detail}`);
+            (0, command_contract_1.log)(io, `    ${sevColor(`[${issue.severity}]`)} ${issue.entry}: ${issue.detail}`);
         }
         if (issues.length > 20) {
-            console.log(chalk_1.default.gray(`    ... 还有 ${issues.length - 20} 条`));
+            (0, command_contract_1.log)(io, chalk_1.default.gray(`    ... 还有 ${issues.length - 20} 条`));
         }
     }
     else {
-        console.log(chalk_1.default.green('  ✓ 无问题'));
+        (0, command_contract_1.log)(io, chalk_1.default.green('  ✓ 无问题'));
+    }
+    return { kind: 'ok' };
+}
+/** 缺省知识库数据根（相对用户 home） */
+const KNOWLEDGE_DATA_DIR = path.join('.harness', 'knowledge');
+/** 旧缺省数据根（曾寄居 studio home），仍有数据时兼容沿用，免迁移 */
+const LEGACY_KNOWLEDGE_DATA_DIR = path.join('.studio', 'knowledge');
+let legacyKnowledgeDirNotified = false;
+function hasKnowledgeData(dir) {
+    try {
+        return fs.existsSync(dir) && fs.readdirSync(dir).length > 0;
+    }
+    catch {
+        return false;
     }
 }
-function getKnowledgeDir(projectPath) {
+function getKnowledgeDir(projectPath, io) {
     if (projectPath)
         return `${projectPath}/.harness/knowledge`;
     if (process.env.KNOWLEDGE_BASE_DIR)
         return process.env.KNOWLEDGE_BASE_DIR;
-    return path.join(os.homedir(), '.studio', 'knowledge');
+    const defaultDir = path.join(os.homedir(), KNOWLEDGE_DATA_DIR);
+    const legacyDir = path.join(os.homedir(), LEGACY_KNOWLEDGE_DATA_DIR);
+    if (hasKnowledgeData(legacyDir)) {
+        if (!legacyKnowledgeDirNotified) {
+            legacyKnowledgeDirNotified = true;
+            // stderr：不污染 --json 的 stdout 输出
+            (0, command_contract_1.logError)(io, chalk_1.default.yellow(`⚠ 缺省知识库根已改为 ${defaultDir}；旧目录 ${legacyDir} 仍有数据，本次沿用（免迁移，可用 KNOWLEDGE_BASE_DIR 覆盖）`));
+        }
+        return legacyDir;
+    }
+    return defaultDir;
 }
 /**
  * 知识库质量审计
  */
-async function knowledgeAudit(options) {
+async function knowledgeAudit(options, io = command_contract_1.processIO) {
     const audit = new audit_1.KnowledgeAudit({
-        baseDir: options.dir || getKnowledgeDir(options.projectPath),
+        baseDir: options.dir || getKnowledgeDir(options.projectPath, io),
         shortContentThreshold: options.threshold ? parseInt(options.threshold, 10) : undefined,
     });
     const isDryRun = options.dryRun && !options.fix;
     if (!options.json && !isDryRun) {
-        console.log(chalk_1.default.blue('🔍 知识库质量审计...\n'));
+        (0, command_contract_1.log)(io, chalk_1.default.blue('🔍 知识库质量审计...\n'));
     }
     const report = audit.run({ autoFix: options.fix && !isDryRun });
     if (options.json) {
-        console.log(JSON.stringify(report, null, 2));
-        return;
+        (0, command_contract_1.log)(io, JSON.stringify(report, null, 2));
+        return { kind: 'ok' };
     }
     // Summary
-    console.log(chalk_1.default.bold(`  总条目: ${report.totalEntries}`));
-    console.log(chalk_1.default.bold(`  健康分: ${report.healthScore.before}/100`));
+    (0, command_contract_1.log)(io, chalk_1.default.bold(`  总条目: ${report.totalEntries}`));
+    (0, command_contract_1.log)(io, chalk_1.default.bold(`  健康分: ${report.healthScore.before}/100`));
     if (report.autoFixed > 0) {
-        console.log(chalk_1.default.green(`  自动修复: ${report.autoFixed} 条`));
-        console.log(chalk_1.default.bold(`  修复后: ${report.healthScore.after}/100`));
+        (0, command_contract_1.log)(io, chalk_1.default.green(`  自动修复: ${report.autoFixed} 条`));
+        (0, command_contract_1.log)(io, chalk_1.default.bold(`  修复后: ${report.healthScore.after}/100`));
     }
-    console.log();
-    // Dimension scores
+    (0, command_contract_1.log)(io);
+    // Dimension scores（Record 全键标注 → 编译期闭环，#109）
     const dimLabels = {
         structure: 'D1 结构完整性',
         content: 'D2 内容质量',
@@ -503,105 +550,95 @@ async function knowledgeAudit(options) {
         maturity: 'D4 成熟度健康',
         freshness: 'D5 新鲜度',
         flywheel: 'D6 飞轮验证',
+        incremental: 'D7 增量存活',
     };
-    console.log(chalk_1.default.bold('  维度评分:'));
+    (0, command_contract_1.log)(io, chalk_1.default.bold('  维度评分:'));
     for (const [key, dim] of Object.entries(report.dimensions)) {
-        const label = dimLabels[key] || key;
+        const label = dimLabels[key];
         const scoreColor = dim.score >= 80 ? chalk_1.default.green : dim.score >= 60 ? chalk_1.default.yellow : chalk_1.default.red;
-        console.log(`    ${label}: ${scoreColor(`${dim.score}/100`)} (${dim.issues} 问题)`);
-    }
-    console.log();
-    // Issues by rule
-    const ruleLabels = {
-        'frontmatter-missing': 'frontmatter 缺失',
-        'test-data-pollution': '测试数据污染',
-        'daily-audit-noise': '每日审计噪音',
-        'zero-content-proven': '零内容 proven',
-        'short-content': '短内容',
-        'maturity-inflation': '成熟度虚高',
-        'title-duplicate': '标题重复',
-        'source-refs-bloat': 'sourceReferences 膨胀',
-        'fragment-cluster': '碎片集群',
-        'promotion-blocked': 'promotion 受阻',
-        'orphan-draft': '孤儿 draft',
-        'stale-entry': '过期条目',
-    };
+        (0, command_contract_1.log)(io, `    ${label}: ${scoreColor(`${dim.score}/100`)} (${dim.issues} 问题)`);
+    }
+    (0, command_contract_1.log)(io);
+    // Issues by rule（label 正本在 audit.ts 规则定义，AUDIT_RULE_LABELS 编译期闭环，#109）
     for (const [rule, count] of Object.entries(report.summary)) {
         if (count === 0)
             continue;
-        const label = ruleLabels[rule] || rule;
-        console.log(`  ${chalk_1.default.red(`${label}: ${count}`)}`);
+        const label = audit_1.AUDIT_RULE_LABELS[rule];
+        (0, command_contract_1.log)(io, `  ${chalk_1.default.red(`${label}: ${count}`)}`);
     }
     // Detail (first 20)
     if (report.issues.length > 0) {
-        console.log(chalk_1.default.bold(`\n  问题详情 (前 20 条):\n`));
+        (0, command_contract_1.log)(io, chalk_1.default.bold(`\n  问题详情 (前 20 条):\n`));
         for (const issue of report.issues.slice(0, 20)) {
             const severityColor = issue.severity === 'critical' ? chalk_1.default.red
                 : issue.severity === 'high' ? chalk_1.default.yellow
                     : chalk_1.default.gray;
-            console.log(`  ${severityColor(`[${issue.severity}]`)} ${issue.entryId}: ${issue.title}`);
-            console.log(`    ${chalk_1.default.gray(issue.detail)} → ${issue.action}`);
+            (0, command_contract_1.log)(io, `  ${severityColor(`[${issue.severity}]`)} ${issue.entryId}: ${issue.title}`);
+            (0, command_contract_1.log)(io, `    ${chalk_1.default.gray(issue.detail)} → ${issue.action}`);
         }
         if (report.issues.length > 20) {
-            console.log(chalk_1.default.gray(`\n  ... 还有 ${report.issues.length - 20} 条`));
+            (0, command_contract_1.log)(io, chalk_1.default.gray(`\n  ... 还有 ${report.issues.length - 20} 条`));
         }
     }
     if (!options.fix && report.issues.length > 0) {
-        console.log(chalk_1.default.yellow(`\n  使用 --fix 自动修复`));
+        (0, command_contract_1.log)(io, chalk_1.default.yellow(`\n  使用 --fix 自动修复`));
     }
     // Auto-rebuild index after audit (files may have changed)
-    const baseDir = options.dir || getKnowledgeDir(options.projectPath);
+    const baseDir = options.dir || getKnowledgeDir(options.projectPath, io);
     const idxGen = new index_generator_1.KnowledgeIndexGenerator(baseDir);
     idxGen.regenerate();
     if (!options.json) {
-        console.log(chalk_1.default.gray(`  📇 索引已重建`));
+        (0, command_contract_1.log)(io, chalk_1.default.gray(`  📇 索引已重建`));
     }
+    return { kind: 'ok' };
 }
 /**
  * 知识库快照（KR4 存活率追踪）
  */
-function knowledgeSnapshot(options) {
-    const store = new store_1.FileKnowledgeStore({ baseDir: options.dir || getKnowledgeDir(options.projectPath) });
+function knowledgeSnapshot(options, io = command_contract_1.processIO) {
+    const store = new store_1.FileKnowledgeStore({ baseDir: options.dir || getKnowledgeDir(options.projectPath, io) });
     const snapPath = store.snapshot();
     if (options.json) {
-        console.log(JSON.stringify({ snapshotPath: snapPath }));
-        return;
+        (0, command_contract_1.log)(io, JSON.stringify({ snapshotPath: snapPath }));
+        return { kind: 'ok' };
     }
-    console.log(chalk_1.default.green(`✅ 快照已保存: ${snapPath}`));
+    (0, command_contract_1.log)(io, chalk_1.default.green(`✅ 快照已保存: ${snapPath}`));
+    return { kind: 'ok' };
 }
 /**
  * 知识库迁移 — 为现有条目添加 AS-021 新字段
  */
-function knowledgeMigrate(options) {
-    const baseDir = options.dir || getKnowledgeDir(options.projectPath);
+function knowledgeMigrate(options, io = command_contract_1.processIO) {
+    const baseDir = options.dir || getKnowledgeDir(options.projectPath, io);
     if (options.json) {
         const result = (0, migration_1.migrateKnowledgeEntries)(baseDir);
-        console.log(JSON.stringify(result, null, 2));
-        return;
+        (0, command_contract_1.log)(io, JSON.stringify(result, null, 2));
+        return { kind: 'ok' };
     }
-    console.log(chalk_1.default.blue('🔄 迁移知识条目（添加 consumptionMode/origin 字段）\n'));
+    (0, command_contract_1.log)(io, chalk_1.default.blue('🔄 迁移知识条目（添加 consumptionMode/origin 字段）\n'));
     const result = (0, migration_1.migrateKnowledgeEntries)(baseDir);
-    console.log(chalk_1.default.green(`  总计: ${result.total} 条`));
-    console.log(chalk_1.default.green(`  已迁移: ${result.migrated} 条`));
-    console.log(chalk_1.default.gray(`  已跳过: ${result.skipped} 条`));
+    (0, command_contract_1.log)(io, chalk_1.default.green(`  总计: ${result.total} 条`));
+    (0, command_contract_1.log)(io, chalk_1.default.green(`  已迁移: ${result.migrated} 条`));
+    (0, command_contract_1.log)(io, chalk_1.default.gray(`  已跳过: ${result.skipped} 条`));
     if (result.errors.length > 0) {
-        console.log(chalk_1.default.red(`\n  错误: ${result.errors.length} 条`));
+        (0, command_contract_1.log)(io, chalk_1.default.red(`\n  错误: ${result.errors.length} 条`));
         for (const err of result.errors.slice(0, 5)) {
-            console.log(chalk_1.default.red(`    ${err}`));
+            (0, command_contract_1.log)(io, chalk_1.default.red(`    ${err}`));
         }
     }
     if (result.migrated === 0 && result.errors.length === 0) {
-        console.log(chalk_1.default.green('\n✅ 所有条目已是最新，无需迁移'));
+        (0, command_contract_1.log)(io, chalk_1.default.green('\n✅ 所有条目已是最新，无需迁移'));
     }
     else if (result.migrated > 0) {
-        console.log(chalk_1.default.green(`\n✅ 迁移完成`));
+        (0, command_contract_1.log)(io, chalk_1.default.green(`\n✅ 迁移完成`));
     }
+    return { kind: 'ok' };
 }
 /**
  * 知识库索引重建 — 生成 _index.md 供 Agent grep 使用，同时同步 index.json
  */
-function knowledgeIndex(options) {
-    const baseDir = options.dir || getKnowledgeDir(options.projectPath);
+function knowledgeIndex(options, io = command_contract_1.processIO) {
+    const baseDir = options.dir || getKnowledgeDir(options.projectPath, io);
     const gen = new index_generator_1.KnowledgeIndexGenerator(baseDir);
     const beforeSize = (() => {
         const indexPath = path.join(baseDir, '_index.md');
@@ -614,20 +651,21 @@ function knowledgeIndex(options) {
     const afterSize = Buffer.byteLength(output, 'utf-8');
     const lineCount = output.split('\n').filter(l => !l.startsWith('#')).length;
     if (options.json) {
-        console.log(JSON.stringify({
+        (0, command_contract_1.log)(io, JSON.stringify({
             path: path.join(baseDir, '_index.md'),
             entries: lineCount,
             size: afterSize,
             previousSize: beforeSize,
         }));
-        return;
+        return { kind: 'ok' };
     }
-    console.log(chalk_1.default.blue(`📇 索引已重建`));
-    console.log(chalk_1.default.gray(`  路径: ${path.join(baseDir, '_index.md')}`));
-    console.log(chalk_1.default.green(`  条目: ${lineCount}`));
-    console.log(chalk_1.default.green(`  大小: ${(afterSize / 1024).toFixed(1)} KB`));
+    (0, command_contract_1.log)(io, chalk_1.default.blue(`📇 索引已重建`));
+    (0, command_contract_1.log)(io, chalk_1.default.gray(`  路径: ${path.join(baseDir, '_index.md')}`));
+    (0, command_contract_1.log)(io, chalk_1.default.green(`  条目: ${lineCount}`));
+    (0, command_contract_1.log)(io, chalk_1.default.green(`  大小: ${(afterSize / 1024).toFixed(1)} KB`));
     if (beforeSize > 0) {
-        console.log(chalk_1.default.gray(`  旧大小: ${(beforeSize / 1024).toFixed(1)} KB`));
+        (0, command_contract_1.log)(io, chalk_1.default.gray(`  旧大小: ${(beforeSize / 1024).toFixed(1)} KB`));
     }
+    return { kind: 'ok' };
 }
 //# sourceMappingURL=knowledge.js.map