@dommaker/harness 1.7.0 → 1.8.1

package/src/cli/commands/knowledge.ts

@@ -1,24 +1,41 @@
 /**
  * harness knowledge 命令
  *
- * 知识库管理：list、search、import、decay、stats
+ * 知识库管理 11 子操作（list/search/import/decay/stats/sync-rag/audit/snapshot/migrate/index/health）。
+ * 本文件只做「取数 + 声明两投影」：json 面正本在 `data`，人读排版在 `human()` 的
+ * display model。上色、label 映射、json/人读分派、退出码、路径解析与 store 构造
+ * 统一在 knowledge-view.ts（harness#133，架构评审候选4）。
  */
 
-import chalk from 'chalk';
 import * as fs from 'fs';
-import * as os from 'os';
 import * as path from 'path';
-import { FileKnowledgeStore as KnowledgeStore } from '../../knowledge/store';
 import { KnowledgeQuery } from '../../knowledge/query';
 import { KnowledgeLifecycle } from '../../knowledge/lifecycle';
 import { ColdStartImporter } from '../../knowledge/import';
-import { KnowledgeAudit, AUDIT_RULE_LABELS } from '../../knowledge/audit';
-import type { AuditReport, AuditRuleName } from '../../knowledge/audit';
+import { KnowledgeAudit } from '../../knowledge/audit';
+import type { AuditReport, AuditRuleName, DimensionMetrics } from '../../knowledge/audit-scoring';
 import { evaluateFlywheel } from '../../knowledge/flywheel-metrics';
 import { migrateKnowledgeEntries } from '../../knowledge/migration';
 import { KnowledgeIndexGenerator } from '../../knowledge/index-generator';
-import type { KnowledgeSubsystem, MaturityLevel, QueryFilter } from '../../knowledge/types';
-import { log, logError, processIO, type CommandIO, type CommandResult } from '../command-contract';
+import type { KnowledgeEntry, KnowledgeSubsystem, MaturityChange, MaturityLevel, QueryFilter } from '../../knowledge/types';
+import { logError, processIO, type CommandIO, type CommandResult } from '../command-contract';
+import { numericFlagMessage, parseNumericFlag } from '../../utils/numeric-flag';
+import {
+  announce,
+  blankLine,
+  dimensionLabel,
+  emitKnowledgeView,
+  openKnowledgeStore,
+  resolveKnowledgeBaseDir,
+  ruleLabel,
+  toneForMaturity,
+  toneForScore,
+  toneForSeverity,
+  type DisplayModel,
+  type DisplayRow,
+  type DisplaySection,
+  type KnowledgeView,
+} from './knowledge-view';
 
 export interface KnowledgeOptions {
   /** 项目路径 */
@@ -27,89 +44,121 @@ export interface KnowledgeOptions {
   json?: boolean;
 }
 
-/**
- * 知识库列表
- */
-export async function knowledgeList(options: KnowledgeOptions & {
+/** 子操作共用的入参面：知识库目录覆盖（audit/snapshot/migrate/index/health 收） */
+type KnowledgeDirOption = { dir?: string };
+
+// ========================================
+// list
+// ========================================
+
+function listFilter(options: KnowledgeListOptions): QueryFilter {
+  const filter: QueryFilter = { excludeArchived: false };
+  if (options.type) filter.types = options.type.split(',') as KnowledgeSubsystem[];
+  if (options.maturity) filter.maturity = options.maturity.split(',') as MaturityLevel[];
+  if (options.tag) filter.tags = options.tag.split(',');
+  return filter;
+}
+
+export interface KnowledgeListOptions extends KnowledgeOptions {
   type?: string;
   maturity?: string;
   tag?: string;
-}, io: CommandIO = processIO): Promise<CommandResult> {
-  const store = new KnowledgeStore({ baseDir: getKnowledgeDir(options.projectPath, io) });
-
-  const filter: QueryFilter = { excludeArchived: false };
-  if (options.type) {
-    filter.types = options.type.split(',') as KnowledgeSubsystem[];
-  }
-  if (options.maturity) {
-    filter.maturity = options.maturity.split(',') as MaturityLevel[];
-  }
-  if (options.tag) {
-    filter.tags = options.tag.split(',');
-  }
+}
 
-  const entries = store.list(filter);
+export function knowledgeListView(options: KnowledgeListOptions, io: CommandIO) {
+  const entries = openKnowledgeStore(options, io).list(listFilter(options));
+  const data = { total: entries.length, entries };
 
-  if (options.json) {
-    log(io, JSON.stringify({ total: entries.length, entries }, null, 2));
-    return { kind: 'ok' };
-  }
+  return { data, human: (): DisplayModel => ({ sections: [{ rows: listRows(entries) }] }) };
+}
 
+function listRows(entries: KnowledgeEntry[]): DisplayRow[] {
   if (entries.length === 0) {
-    log(io, chalk.yellow('知识库为空'));
-    return { kind: 'ok' };
-  }
-
-  log(io, chalk.blue(`📚 知识库 (${entries.length} 条)\n`));
-  for (const entry of entries) {
-    const maturityColor = entry.maturity === 'proven' ? chalk.green
-      : entry.maturity === 'verified' ? chalk.cyan
-      : entry.maturity === 'archived' ? chalk.gray
-      : chalk.yellow;
-    log(io, `  ${maturityColor(`[${entry.maturity}]`)} ${chalk.bold(entry.title)}`);
-    log(io, `    ${chalk.gray(`id: ${entry.id} | type: ${entry.type} | layer: ${entry.layer}`)}`);
+    return [{ cells: [{ label: '知识库为空', tone: 'warn' }] }];
+  }
+  const rows: DisplayRow[] = [
+    { cells: [
+      { label: '📚 知识库 (', tone: 'heading' },
+      { field: 'total', text: String(entries.length), tone: 'heading' },
+      { label: ' 条)', tone: 'heading' },
+    ] },
+    blankLine(),
+  ];
+  entries.forEach((entry, i) => {
+    rows.push({ cells: [
+      { field: `entries.${i}.maturity`, text: `  [${entry.maturity}]`, tone: toneForMaturity(entry.maturity) },
+      { field: `entries.${i}.title`, text: ` ${entry.title}`, tone: 'emph' },
+    ] });
+    rows.push({ cells: [
+      { field: `entries.${i}.id`, text: `    id: ${entry.id}`, tone: 'muted' },
+      { field: `entries.${i}.type`, text: ` | type: ${entry.type}`, tone: 'muted' },
+      { field: `entries.${i}.layer`, text: ` | layer: ${entry.layer}`, tone: 'muted' },
+    ] });
     if (entry.tags.length > 0) {
-      log(io, `    ${chalk.gray(`tags: ${entry.tags.join(', ')}`)}`);
+      rows.push({ cells: [{ field: `entries.${i}.tags`, text: `    tags: ${entry.tags.join(', ')}`, tone: 'muted' }] });
     }
-  }
-  return { kind: 'ok' };
+  });
+  return rows;
 }
 
-/**
- * 知识库搜索
- */
-export async function knowledgeSearch(
+export async function knowledgeList(options: KnowledgeListOptions, io: CommandIO = processIO): Promise<CommandResult> {
+  return emitKnowledgeView(io, options, knowledgeListView(options, io));
+}
+
+// ========================================
+// search
+// ========================================
+
+export function knowledgeSearchView(
   query: string,
   options: KnowledgeOptions & { limit?: number },
-  io: CommandIO = processIO,
-): Promise<CommandResult> {
-  const store = new KnowledgeStore({ baseDir: getKnowledgeDir(options.projectPath, io) });
-  const queryEngine = new KnowledgeQuery(store);
+  io: CommandIO,
+) {
+  const store = openKnowledgeStore(options, io);
+  const matched = new KnowledgeQuery(store).search(query, { limit: options.limit ?? 20 });
+  const data = { query, total: matched.length, entries: matched };
 
-  const matched = queryEngine.search(query, { limit: options.limit || 20 });
-
-  if (options.json) {
-    log(io, JSON.stringify({ query, total: matched.length, entries: matched }, null, 2));
-    return { kind: 'ok' };
-  }
+  return { data, human: (): DisplayModel => ({ sections: [{ rows: searchRows(query, matched) }] }) };
+}
 
+function searchRows(query: string, matched: KnowledgeEntry[]): DisplayRow[] {
   if (matched.length === 0) {
-    log(io, chalk.yellow(`未找到匹配 "${query}" 的知识条目`));
-    return { kind: 'ok' };
-  }
+    return [{ cells: [{ label: `未找到匹配 "${query}" 的知识条目`, tone: 'warn' }] }];
+  }
+  const rows: DisplayRow[] = [
+    { cells: [
+      { label: '🔍 搜索 "', tone: 'heading' },
+      { field: 'query', text: query, tone: 'heading' },
+      { label: '" (', tone: 'heading' },
+      { field: 'total', text: String(matched.length), tone: 'heading' },
+      { label: ' 条结果)', tone: 'heading' },
+    ] },
+    blankLine(),
+  ];
+  matched.forEach((entry, i) => {
+    const preview = entry.content.slice(0, 100).replace(/\n/g, ' ') + (entry.content.length > 100 ? '...' : '');
+    rows.push({ cells: [
+      { field: `entries.${i}.title`, text: `  ${entry.title}`, tone: 'emph' },
+      { field: `entries.${i}.maturity`, text: ` [${entry.maturity}]`, tone: 'muted' },
+    ] });
+    rows.push({ cells: [{ field: `entries.${i}.content`, text: `    ${preview}`, tone: 'muted' }] });
+  });
+  return rows;
+}
 
-  log(io, chalk.blue(`🔍 搜索 "${query}" (${matched.length} 条结果)\n`));
-  for (const entry of matched) {
-    log(io, `  ${chalk.bold(entry.title)} ${chalk.gray(`[${entry.maturity}]`)}`);
-    const preview = entry.content.slice(0, 100).replace(/\n/g, ' ');
-    log(io, `    ${chalk.gray(preview)}${entry.content.length > 100 ? '...' : ''}`);
-  }
-  return { kind: 'ok' };
+export async function knowledgeSearch(
+  query: string,
+  options: KnowledgeOptions & { limit?: number },
+  io: CommandIO = processIO,
+): Promise<CommandResult> {
+  return emitKnowledgeView(io, options, knowledgeSearchView(query, options, io));
 }
 
 /**
- * knowledge search 子命令入口（候选7）：缺参闸门 + limit 强转编组，
+ * knowledge search 子命令入口（候选7）：缺参闸门 + limit 装配窄化，
  * 自 definitions.ts 的 args 复印块移回命令模块（interface/测试面所在）。
+ * `--limit` 给到的恒是字符串（缺省 '20' 也是），脏输入 fail-loud（harness#154，
+ * 原先 parseInt 出 NaN 被下游 `|| 20` 静默兜成缺省量）。
  */
 export async function knowledgeSearchCommand(
   positionals: (string | undefined)[],
@@ -121,112 +170,138 @@ export async function knowledgeSearchCommand(
     logError(io, '请提供搜索关键词');
     return { kind: 'usage-error', reason: 'knowledge search 缺少关键词位置参数' };
   }
+  const limit = parseNumericFlag(options.limit as string | undefined, 'int');
+  if (!limit.ok) {
+    logError(io, numericFlagMessage('--limit', limit.raw, 'int'));
+    return { kind: 'usage-error', reason: `knowledge search --limit 非法限制: "${limit.raw}"` };
+  }
   return knowledgeSearch(String(query), {
     projectPath: options.projectPath as string | undefined,
     json: options.json as boolean | undefined,
-    limit: parseInt(String(options.limit), 10),
-  });
+    limit: limit.value,
+  }, io);
 }
 
-/**
- * 知识库导入（冷启动）
- */
-export async function knowledgeImport(
+// ========================================
+// import（冷启动）
+// ========================================
+
+export async function knowledgeImportView(
   options: KnowledgeOptions & { sources?: string; reset?: boolean },
-  io: CommandIO = processIO,
-): Promise<CommandResult> {
+  io: CommandIO,
+) {
   const projectPath = options.projectPath || process.cwd();
-  const store = new KnowledgeStore({ baseDir: getKnowledgeDir(options.projectPath, io) });
-
+  const store = openKnowledgeStore(options, io);
   const sources = options.sources
     ? options.sources.split(',') as Array<'code' | 'git' | 'docs' | 'manual'>
     : ['code', 'git', 'docs'] as Array<'code' | 'git' | 'docs'>;
 
-  const importer = new ColdStartImporter({
-    projectRoot: projectPath,
-    store,
-    sources,
-  });
+  const importer = new ColdStartImporter({ projectRoot: projectPath, store, sources });
 
   if (options.reset) {
     importer.resetState();
-    if (!options.json) {
-      log(io, chalk.yellow('🔄 已重置导入状态'));
-    }
-  }
-
-  if (!options.json) {
-    log(io, chalk.blue(`📥 开始导入知识 (源: ${sources.join(', ')})...`));
+    announce(io, options.json, '🔄 已重置导入状态', 'warn');
   }
+  announce(io, options.json, `📥 开始导入知识 (源: ${sources.join(', ')})...`);
 
   const results = await importer.importAll();
+  const data = {
+    totalImported: results.reduce((sum, r) => sum + r.entries.length, 0),
+    totalErrors: results.reduce((sum, r) => sum + r.errors.length, 0),
+    results,
+  };
 
-  const totalImported = results.reduce((sum, r) => sum + r.entries.length, 0);
-  const totalErrors = results.reduce((sum, r) => sum + r.errors.length, 0);
+  return { data, human: (): DisplayModel => ({ sections: [{ rows: importRows(data) }] }) };
+}
 
-  if (options.json) {
-    log(io, JSON.stringify({ totalImported, totalErrors, results }, null, 2));
-    return { kind: 'ok' };
-  }
+type ImportOutcome = Awaited<ReturnType<ColdStartImporter['importAll']>>;
 
-  for (const result of results) {
+function importRows(data: { totalImported: number; totalErrors: number; results: ImportOutcome }): DisplayRow[] {
+  const rows: DisplayRow[] = [];
+  data.results.forEach((result, i) => {
     if (result.entries.length > 0) {
-      log(io, chalk.green(`  ✅ ${result.source.type}: ${result.entries.length} 条`));
-    }
-    if (result.errors.length > 0) {
-      for (const err of result.errors) {
-        log(io, chalk.red(`  ❌ ${result.source.type}: ${err.message}`));
-      }
+      rows.push({ cells: [
+        { field: `results.${i}.source.type`, text: `  ✅ ${result.source.type}: `, tone: 'ok' },
+        { field: `results.${i}.entries.length`, text: `${result.entries.length} 条`, tone: 'ok' },
+      ] });
     }
-  }
-
-  log(io, chalk.green(`\n✅ 导入完成: ${totalImported} 条，${totalErrors} 个错误`));
-  return { kind: 'ok' };
+    result.errors.forEach((err, j) => {
+      rows.push({ cells: [
+        { field: `results.${i}.source.type`, text: `  ❌ ${result.source.type}: `, tone: 'error' },
+        { field: `results.${i}.errors.${j}.message`, text: err.message, tone: 'error' },
+      ] });
+    });
+  });
+  rows.push(blankLine(), { cells: [
+    { label: '✅ 导入完成: ', tone: 'ok' },
+    { field: 'totalImported', text: String(data.totalImported), tone: 'ok' },
+    { label: ' 条，', tone: 'ok' },
+    { field: 'totalErrors', text: String(data.totalErrors), tone: 'ok' },
+    { label: ' 个错误', tone: 'ok' },
+  ] });
+  return rows;
 }
 
-/**
- * 知识库衰减周期
- */
-export async function knowledgeDecay(options: KnowledgeOptions, io: CommandIO = processIO): Promise<CommandResult> {
-  const store = new KnowledgeStore({ baseDir: getKnowledgeDir(options.projectPath, io) });
-  const lifecycle = new KnowledgeLifecycle(store);
+export async function knowledgeImport(
+  options: KnowledgeOptions & { sources?: string; reset?: boolean },
+  io: CommandIO = processIO,
+): Promise<CommandResult> {
+  return emitKnowledgeView(io, options, await knowledgeImportView(options, io));
+}
 
-  if (!options.json) {
-    log(io, chalk.blue('🔄 运行衰减周期...'));
-  }
+// ========================================
+// decay
+// ========================================
 
+export function knowledgeDecayView(options: KnowledgeOptions, io: CommandIO) {
+  const lifecycle = new KnowledgeLifecycle(openKnowledgeStore(options, io));
+  announce(io, options.json, '🔄 运行衰减周期...');
   const changes = lifecycle.runDecayCycle();
+  const data = { changes };
 
-  if (options.json) {
-    log(io, JSON.stringify({ changes }, null, 2));
-    return { kind: 'ok' };
-  }
+  return { data, human: (): DisplayModel => ({ sections: [{ rows: decayRows(changes) }] }) };
+}
 
+function decayRows(changes: MaturityChange[]): DisplayRow[] {
   if (changes.length === 0) {
-    log(io, chalk.green('✅ 没有需要衰减的知识条目'));
-    return { kind: 'ok' };
-  }
+    return [{ cells: [{ label: '✅ 没有需要衰减的知识条目', tone: 'ok' }] }];
+  }
+  const rows: DisplayRow[] = [
+    { cells: [
+      { label: '📉 ', tone: 'warn' },
+      { field: 'changes.length', text: String(changes.length), tone: 'warn' },
+      { label: ' 条知识发生衰减:', tone: 'warn' },
+    ] },
+    blankLine(),
+  ];
+  changes.forEach((change, i) => {
+    rows.push({ cells: [
+      { field: `changes.${i}.entryId`, text: `  ${change.entryId}: ` },
+      { field: `changes.${i}.from`, text: change.from, tone: 'error' },
+      { label: ' → ' },
+      { field: `changes.${i}.to`, text: change.to, tone: 'ok' },
+    ] });
+    rows.push({ cells: [{ field: `changes.${i}.reason`, text: `    ${change.reason}`, tone: 'muted' }] });
+  });
+  return rows;
+}
 
-  log(io, chalk.yellow(`📉 ${changes.length} 条知识发生衰减:\n`));
-  for (const change of changes) {
-    log(io, `  ${change.entryId}: ${chalk.red(change.from)} → ${chalk.green(change.to)}`);
-    log(io, `    ${chalk.gray(change.reason)}`);
-  }
-  return { kind: 'ok' };
+export async function knowledgeDecay(options: KnowledgeOptions, io: CommandIO = processIO): Promise<CommandResult> {
+  return emitKnowledgeView(io, options, knowledgeDecayView(options, io));
 }
 
-/**
- * 知识库统计
- */
-export async function knowledgeStats(options: KnowledgeOptions, io: CommandIO = processIO): Promise<CommandResult> {
-  const store = new KnowledgeStore({ baseDir: getKnowledgeDir(options.projectPath, io) });
+// ========================================
+// stats
+// ========================================
+
+export function knowledgeStatsView(options: KnowledgeOptions, io: CommandIO) {
+  const store = openKnowledgeStore(options, io);
   const entries = store.list({ excludeArchived: false });
   const active = entries.filter(e => e.maturity !== 'archived');
 
   const byType: Record<string, number> = {};
   const byMaturity: Record<string, number> = {};
   const byLayer: Record<string, number> = {};
-
   for (const entry of entries) {
     byType[entry.type] = (byType[entry.type] || 0) + 1;
     byMaturity[entry.maturity] = (byMaturity[entry.maturity] || 0) + 1;
@@ -244,84 +319,380 @@ export async function knowledgeStats(options: KnowledgeOptions, io: CommandIO =
   } catch { /* best-effort */ }
 
   const metrics = 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: Math.round(metrics.refCoverage * 100),
+    avgRefs: Math.round(metrics.avgRefs * 10) / 10,
+    consumptionHitRate: Math.round(metrics.consumptionHitRate * 100),
+  };
 
-  const flywheel = { refCoverage, avgRefs, consumptionHitRate };
+  const data = { total: entries.length, byType, byMaturity, byLayer, flywheel };
+  const activeCount = active.length;
+
+  return {
+    data,
+    human: (): DisplayModel => ({
+      sections: [
+        {
+          rows: [
+            { cells: [{ label: '📊 知识库统计', tone: 'heading' }] },
+            blankLine(),
+            {
+              cells: [
+                { label: '  总计: ', tone: 'emph' },
+                { field: 'total', text: String(data.total), tone: 'emph' },
+                { label: ' 条 (活跃: ', tone: 'emph' },
+                { derived: 'activeCount', text: String(activeCount), tone: 'emph' },
+                { label: ')', tone: 'emph' },
+              ],
+            },
+            blankLine(),
+          ],
+        },
+        { title: '  按类型:', rows: [...countRows('byType', byType), blankLine()] },
+        {
+          title: '  按成熟度:',
+          rows: [...Object.entries(byMaturity).map(([maturity, count]) => ({
+            cells: [
+              { field: `byMaturity.${maturity}`, text: `    ${maturity}`, tone: toneForMaturity(maturity as MaturityLevel) },
+              { field: `byMaturity.${maturity}`, text: `: ${count}` },
+            ],
+          })), blankLine()],
+        },
+        { title: '  按层级:', rows: [...countRows('byLayer', byLayer), blankLine()] },
+        {
+          title: '  飞轮指标:',
+          rows: [
+            { cells: [{ label: '    引用覆盖: ' }, { field: 'flywheel.refCoverage', text: `${flywheel.refCoverage}%` }] },
+            { cells: [{ label: '    平均引用: ' }, { field: 'flywheel.avgRefs', text: String(flywheel.avgRefs) }] },
+            { cells: [{ label: '    消费命中率: ' }, { field: 'flywheel.consumptionHitRate', text: `${flywheel.consumptionHitRate}%` }] },
+          ],
+        },
+      ],
+    }),
+  };
+}
 
-  if (options.json) {
-    log(io, JSON.stringify({ total: entries.length, byType, byMaturity, byLayer, flywheel }, null, 2));
-    return { kind: 'ok' };
-  }
+function countRows(field: string, counts: Record<string, number>): DisplayRow[] {
+  return Object.entries(counts).map(([key, count]) => ({
+    cells: [
+      { label: '    ' },
+      { field: `${field}.${key}`, text: `${key}: ${count}` },
+    ],
+  }));
+}
 
-  log(io, chalk.blue(`📊 知识库统计\n`));
-  log(io, chalk.bold(`  总计: ${entries.length} 条 (活跃: ${active.length})\n`));
+export async function knowledgeStats(options: KnowledgeOptions, io: CommandIO = processIO): Promise<CommandResult> {
+  return emitKnowledgeView(io, options, knowledgeStatsView(options, io));
+}
 
-  log(io, chalk.bold('  按类型:'));
-  for (const [type, count] of Object.entries(byType)) {
-    log(io, `    ${type}: ${count}`);
-  }
+// ========================================
+// sync-rag
+// ========================================
 
-  log(io, chalk.bold('\n  按成熟度:'));
-  for (const [maturity, count] of Object.entries(byMaturity)) {
-    const color = maturity === 'proven' ? chalk.green : maturity === 'archived' ? chalk.gray : chalk.yellow;
-    log(io, `    ${color(maturity)}: ${count}`);
-  }
+export function knowledgeSyncRagView(options: KnowledgeOptions) {
+  const projectPath = options.projectPath || process.cwd();
+  const docsDir = `${projectPath}/.harness/knowledge-docs`;
+  const docsPresent = fs.existsSync(docsDir);
+  const files = docsPresent ? fs.readdirSync(docsDir).filter(f => f.endsWith('.md')) : [];
+  const data = { directory: docsDir, files };
 
-  log(io, chalk.bold('\n  按层级:'));
-  for (const [layer, count] of Object.entries(byLayer)) {
-    log(io, `    ${layer}: ${count}`);
-  }
+  return { data, human: (): DisplayModel => ({ sections: [{ rows: syncRagRows(docsPresent, docsDir, files) }] }) };
+}
+
+function syncRagRows(docsPresent: boolean, docsDir: string, files: string[]): DisplayRow[] {
+  if (!docsPresent) return [{ cells: [{ label: 'No .harness/knowledge-docs/ directory', tone: 'warn' }] }];
+  if (files.length === 0) return [{ cells: [{ label: 'No knowledge docs found', tone: 'muted' }] }];
+  return [
+    { cells: [
+      { label: '📄 RAG sync candidates: ', tone: 'heading' },
+      { field: 'files.length', text: String(files.length), tone: 'heading' },
+      { label: ' files in ', tone: 'heading' },
+      { field: 'directory', text: docsDir, tone: 'heading' },
+    ] },
+    blankLine(),
+    ...files.map((file, i) => ({ cells: [{ field: `files.${i}`, text: `  ${file}`, tone: 'accent' as const }] })),
+    blankLine(),
+    { cells: [{ label: 'Run `mcp__local-rag__ingest_file` for each to sync to RAG', tone: 'muted' }] },
+  ];
+}
 
-  log(io, chalk.bold('\n  飞轮指标:'));
-  log(io, `    引用覆盖: ${refCoverage}%`);
-  log(io, `    平均引用: ${avgRefs}`);
-  log(io, `    消费命中率: ${consumptionHitRate}%`);
-  return { kind: 'ok' };
+export async function knowledgeSyncRag(options: KnowledgeOptions, io: CommandIO = processIO): Promise<CommandResult> {
+  return emitKnowledgeView(io, options, knowledgeSyncRagView(options));
 }
 
+// ========================================
+// audit（知识库质量审计）
+// ========================================
+
+export type KnowledgeAuditOptions = KnowledgeOptions & KnowledgeDirOption & {
+  fix?: boolean;
+  dryRun?: boolean;
+  /**
+   * `--threshold <n>` 的 commander 原值。旗帜给到的恒是字符串（缺省 '50' 也是），
+   * 声明跟着运行时走（harness#152）；窄化在 `knowledgeAudit` 装配点做一次。
+   */
+  threshold?: string;
+};
+
+/** `knowledgeAuditView` 的入参面：threshold 已过装配窄化，引擎槽位要的是数值 */
+export type KnowledgeAuditViewOptions = Omit<KnowledgeAuditOptions, 'threshold'> & {
+  threshold?: number;
+};
+
+/** 阈值装配结果：`ok: false` = 脏输入，由命令入口 fail-loud（不得往判定槽塞 NaN） */
+type ThresholdAssembly = { ok: true; value?: number } | { ok: false; raw: string };
+
 /**
- * RAG 同步：扫描 .harness/knowledge-docs/ 输出需要 ingest 的文件列表
+ * `--threshold` 的装配点窄化（harness#152）：非负整数字符串 → 数值，转不出来即脏输入。
+ * `undefined` = 未传，落引擎缺省（50）；`'0'` 是显式零值，不当「未传」兜掉。
+ * 判定规则正本是 `parseNumericFlag`（harness#154 统一解析器），此处保留 #152 的
+ * 函数面与报错文案（冻结测试钉死），只做委派。
  */
-export async function knowledgeSyncRag(options: KnowledgeOptions, io: CommandIO = processIO): Promise<CommandResult> {
-  const projectPath = options.projectPath || process.cwd();
-  const docsDir = `${projectPath}/.harness/knowledge-docs`;
+function assembleShortContentThreshold(raw: string | undefined): ThresholdAssembly {
+  return parseNumericFlag(raw, 'int');
+}
 
-  if (!fs.existsSync(docsDir)) {
-    log(io, chalk.yellow('No .harness/knowledge-docs/ directory'));
-    return { kind: 'ok' };
+export function knowledgeAuditView(options: KnowledgeAuditViewOptions, io: CommandIO) {
+  const audit = new KnowledgeAudit(openKnowledgeStore(options, io), {
+    shortContentThreshold: options.threshold,
+  });
+  const isDryRun = options.dryRun && !options.fix;
+  if (!isDryRun) announce(io, options.json, '🔍 知识库质量审计...\n');
+  const report = audit.run({ autoFix: options.fix && !isDryRun });
+  const showFixHint = !options.fix && report.issues.length > 0;
+
+  return {
+    data: report,
+    human: (): DisplayModel => ({ sections: auditSections(report, showFixHint) }),
+  };
+}
+
+function auditSections(report: AuditReport, showFixHint: boolean): DisplaySection[] {
+  const sections: DisplaySection[] = [{
+    rows: [
+      { cells: [{ label: '  总条目: ', tone: 'emph' }, { field: 'totalEntries', text: String(report.totalEntries), tone: 'emph' }] },
+      { cells: [{ label: '  健康分: ', tone: 'emph' }, { field: 'healthScore.before', text: `${report.healthScore.before}/100`, tone: 'emph' }] },
+    ],
+  }];
+
+  if (report.autoFixed > 0) {
+    sections[0].rows.push(
+      { cells: [{ label: '  自动修复: ', tone: 'ok' }, { field: 'autoFixed', text: String(report.autoFixed), tone: 'ok' }] },
+      { cells: [{ label: '  修复后: ', tone: 'emph' }, { field: 'healthScore.after', text: `${report.healthScore.after}/100`, tone: 'emph' }] },
+    );
+  }
+  sections[0].rows.push(blankLine());
+
+  const dimensions: DisplayRow[] = [];
+  for (const [key, dim] of Object.entries(report.dimensions) as Array<[keyof AuditReport['dimensions'], DimensionMetrics]>) {
+    dimensions.push({ cells: [
+      { field: `dimensions.${key}`, text: `    ${dimensionLabel(key)}: ` },
+      { field: `dimensions.${key}.score`, text: `${dim.score}/100`, tone: toneForScore(dim.score) },
+      { field: `dimensions.${key}.issues`, text: ` (${dim.issues} 问题)` },
+    ] });
+  }
+  dimensions.push(blankLine());
+  sections.push({ title: '  维度评分:', rows: dimensions });
+
+  // 规则 label 正本在 audit.ts 的规则定义上（#109 编译期闭环经 ruleLabel 转发）
+  const rules: DisplayRow[] = [];
+  for (const [rule, count] of Object.entries(report.summary) as Array<[AuditRuleName, number]>) {
+    if (count === 0) continue;
+    rules.push({ cells: [{ field: `summary.${rule}`, text: `  ${ruleLabel(rule)}: ${count}`, tone: 'error' }] });
+  }
+  if (report.issues.length > 0) {
+    rules.push(blankLine()); // 「问题详情」标题前的空行（原排版是 `\n` 前缀）
+  }
+  sections.push({ rows: rules });
+
+  if (report.issues.length > 0) {
+    const issues: DisplayRow[] = [blankLine()];
+    for (const [i, issue] of report.issues.slice(0, 20).entries()) {
+      issues.push({ cells: [
+        { field: `issues.${i}.severity`, text: `  [${issue.severity}]`, tone: toneForSeverity(issue.severity) },
+        { field: `issues.${i}.entryId`, text: ` ${issue.entryId}: ` },
+        { field: `issues.${i}.title`, text: issue.title },
+      ] });
+      issues.push({ cells: [
+        { field: `issues.${i}.detail`, text: `    ${issue.detail}`, tone: 'muted' },
+        { label: ' → ' },
+        { field: `issues.${i}.action`, text: issue.action },
+      ] });
+    }
+    if (report.issues.length > 20) {
+      issues.push(blankLine(), { cells: [
+        { label: '  ... 还有 ', tone: 'muted' },
+        { field: 'issues.length', text: String(report.issues.length - 20), tone: 'muted' },
+        { label: ' 条', tone: 'muted' },
+      ] });
+    }
+    sections.push({ title: '  问题详情 (前 20 条):', rows: issues });
   }
 
-  const files = fs.readdirSync(docsDir).filter(f => f.endsWith('.md'));
-  if (files.length === 0) {
-    log(io, chalk.gray('No knowledge docs found'));
-    return { kind: 'ok' };
+  if (showFixHint) {
+    sections.push({ rows: [blankLine(), { cells: [{ label: '  使用 --fix 自动修复', tone: 'warn' }] }] });
   }
+  return sections;
+}
 
-  if (options.json) {
-    log(io, JSON.stringify({ directory: docsDir, files }, null, 2));
-    return { kind: 'ok' };
+export async function knowledgeAudit(options: KnowledgeAuditOptions, io: CommandIO = processIO): Promise<CommandResult> {
+  const threshold = assembleShortContentThreshold(options.threshold);
+  if (!threshold.ok) {
+    logError(io, `错误：--threshold 需要非负整数阈值（字符数），收到 "${threshold.raw}"；短内容判定未执行`);
+    return { kind: 'usage-error', reason: `knowledge audit --threshold 非法阈值: "${threshold.raw}"` };
   }
+  const result = emitKnowledgeView(io, options, knowledgeAuditView({ ...options, threshold: threshold.value }, io));
+  // 审计可能改文件，人读路径收尾重建索引；--json 保持不写盘（现状冻结，#133 不动这条策略）
+  if (!options.json) {
+    new KnowledgeIndexGenerator(resolveKnowledgeBaseDir(options, io)).regenerate();
+    announce(io, options.json, '  📇 索引已重建', 'muted');
+  }
+  return result;
+}
+
+// ========================================
+// snapshot（KR4 存活率追踪）
+// ========================================
+
+export function knowledgeSnapshotView(options: KnowledgeOptions & KnowledgeDirOption, io: CommandIO) {
+  const snapshotPath = openKnowledgeStore(options, io).snapshot();
+  const data = { snapshotPath };
+
+  return {
+    data,
+    human: (): DisplayModel => ({
+      sections: [{
+        rows: [{
+          cells: [
+            { label: '✅ 快照已保存: ', tone: 'ok' },
+            { field: 'snapshotPath', text: snapshotPath, tone: 'ok' },
+          ],
+        }],
+      }],
+    }),
+  };
+}
+
+export function knowledgeSnapshot(options: KnowledgeOptions & KnowledgeDirOption, io: CommandIO = processIO): CommandResult {
+  return emitKnowledgeView(io, options, knowledgeSnapshotView(options, io));
+}
+
+// ========================================
+// migrate（为现有条目补 AS-021 新字段）
+// ========================================
+
+/** migrateKnowledgeEntries 的返回面 = migrate 的 json 正本（该类型未从 knowledge/migration 导出，此处同构声明） */
+type MigrateResult = { total: number; migrated: number; skipped: number; errors: string[] };
+
+export function knowledgeMigrateView(options: KnowledgeOptions & KnowledgeDirOption, io: CommandIO): KnowledgeView<MigrateResult> {
+  const result = migrateKnowledgeEntries(resolveKnowledgeBaseDir(options, io));
+
+  return {
+    data: result,
+    human: (): DisplayModel => ({ sections: [{ rows: migrateRows(result) }] }),
+  };
+}
 
-  log(io, chalk.blue(`📄 RAG sync candidates: ${files.length} files in ${docsDir}\n`));
-  for (const file of files) {
-    log(io, chalk.cyan(`  ${file}`));
+function migrateRows(result: MigrateResult): DisplayRow[] {
+  const rows: DisplayRow[] = [
+    { cells: [{ label: '🔄 迁移知识条目（添加 consumptionMode/origin 字段）', tone: 'heading' }] },
+    blankLine(),
+    { cells: [{ label: '  总计: ', tone: 'ok' }, { field: 'total', text: String(result.total), tone: 'ok' }, { label: ' 条', tone: 'ok' }] },
+    { cells: [{ label: '  已迁移: ', tone: 'ok' }, { field: 'migrated', text: String(result.migrated), tone: 'ok' }, { label: ' 条', tone: 'ok' }] },
+    { cells: [{ label: '  已跳过: ', tone: 'muted' }, { field: 'skipped', text: String(result.skipped), tone: 'muted' }, { label: ' 条', tone: 'muted' }] },
+  ];
+  if (result.errors.length > 0) {
+    rows.push(
+      blankLine(),
+      { cells: [{ label: '  错误: ', tone: 'error' }, { field: 'errors.length', text: String(result.errors.length), tone: 'error' }, { label: ' 条', tone: 'error' }] },
+    );
+    result.errors.slice(0, 5).forEach((err, i) => {
+      rows.push({ cells: [{ label: '    ' }, { field: `errors.${i}`, text: err, tone: 'error' }] });
+    });
+  }
+  // 两种收尾语各自带一个前导空行；migrated=0 且有错误时历史上两句都不打
+  if (result.migrated === 0 && result.errors.length === 0) {
+    rows.push(blankLine(), { cells: [{ label: '✅ 所有条目已是最新，无需迁移', tone: 'ok' }] });
+  } else if (result.migrated > 0) {
+    rows.push(blankLine(), { cells: [{ label: '✅ 迁移完成', tone: 'ok' }] });
   }
-  log(io);
-  log(io, chalk.gray('Run `mcp__local-rag__ingest_file` for each to sync to RAG'));
-  return { kind: 'ok' };
+  return rows;
 }
 
-/**
- * 飞轮健康检查 — 零 token 检测知识飞轮数据流状态
- */
-export async function knowledgeHealth(options: KnowledgeOptions & { dir?: string }, io: CommandIO = processIO): Promise<CommandResult> {
-  const baseDir = options.dir || getKnowledgeDir(options.projectPath, io);
-  const store = new KnowledgeStore({ baseDir });
+export function knowledgeMigrate(options: KnowledgeOptions & KnowledgeDirOption, io: CommandIO = processIO): CommandResult {
+  return emitKnowledgeView(io, options, knowledgeMigrateView(options, io));
+}
+
+// ========================================
+// index（重建 _index.md 供 Agent grep，并同步 index.json）
+// ========================================
+
+export function knowledgeIndexView(options: KnowledgeOptions & KnowledgeDirOption, io: CommandIO) {
+  const baseDir = resolveKnowledgeBaseDir(options, io);
+  const indexPath = path.join(baseDir, '_index.md');
+  const beforeSize = fs.existsSync(indexPath) ? fs.statSync(indexPath).size : 0;
+
+  const output = new KnowledgeIndexGenerator(baseDir).regenerate();
+  // Sync index.json from disk files (removes ghost entries from manual mv/rm)
+  openKnowledgeStore({ dir: baseDir }, io).rebuildIndex();
+
+  const afterSize = Buffer.byteLength(output, 'utf-8');
+  const lineCount = output.split('\n').filter(l => !l.startsWith('#')).length;
+  const data = { path: indexPath, entries: lineCount, size: afterSize, previousSize: beforeSize };
+
+  return {
+    data,
+    human: (): DisplayModel => ({ sections: [{ rows: indexRows({ indexPath, afterSize, lineCount, beforeSize }) }] }),
+  };
+}
+
+function indexRows(shape: { indexPath: string; afterSize: number; lineCount: number; beforeSize: number }): DisplayRow[] {
+  const rows: DisplayRow[] = [
+    { cells: [{ label: '📇 索引已重建', tone: 'heading' }] },
+    { cells: [{ label: '  路径: ', tone: 'muted' }, { field: 'path', text: shape.indexPath, tone: 'muted' }] },
+    { cells: [{ label: '  条目: ', tone: 'ok' }, { field: 'entries', text: String(shape.lineCount), tone: 'ok' }] },
+    { cells: [{ label: '  大小: ', tone: 'ok' }, { field: 'size', text: `${(shape.afterSize / 1024).toFixed(1)} KB`, tone: 'ok' }] },
+  ];
+  if (shape.beforeSize > 0) {
+    rows.push({ cells: [{ label: '  旧大小: ', tone: 'muted' }, { field: 'previousSize', text: `${(shape.beforeSize / 1024).toFixed(1)} KB`, tone: 'muted' }] });
+  }
+  return rows;
+}
+
+export function knowledgeIndex(options: KnowledgeOptions & KnowledgeDirOption, io: CommandIO = processIO): CommandResult {
+  return emitKnowledgeView(io, options, knowledgeIndexView(options, io));
+}
+
+// ========================================
+// health（飞轮健康检查 — 零 token 检测数据流状态）
+// ========================================
+
+interface HealthIssue {
+  severity: 'error' | 'warn' | 'info';
+  entry: string;
+  detail: string;
+}
+
+/** health 的 json 面正本（字段清单冻结在 __tests__/knowledge-view.test.ts） */
+interface HealthData {
+  healthScore: number;
+  summary: {
+    total: number;
+    lowRefEntries: number;
+    staleEntries: number;
+    consumptionData: boolean;
+    refCoverage: number;
+    avgRefs: number;
+  };
+  issues: HealthIssue[];
+}
+
+export function knowledgeHealthView(options: KnowledgeOptions & KnowledgeDirOption, io: CommandIO) {
+  const store = openKnowledgeStore(options, io);
+  const baseDir = store.getBaseDir();
   const entries = store.list({ excludeArchived: true });
 
-  const issues: Array<{ severity: 'error' | 'warn' | 'info'; entry: string; detail: string }> = [];
+  const issues: HealthIssue[] = [];
 
   // D1: 引用密度检查（低引用 = 可能孤立）
   let lowRefEntries = 0;
@@ -345,11 +716,9 @@ export async function knowledgeHealth(options: KnowledgeOptions & { dir?: string
   }
 
   // D3: 消费数据检查
-  let consumptionData = false;
   const statsPath = path.join(baseDir, '.consumption-stats.json');
-  if (fs.existsSync(statsPath)) {
-    consumptionData = true;
-  } else {
+  const consumptionData = fs.existsSync(statsPath);
+  if (!consumptionData) {
     issues.push({ severity: 'info', entry: '-', detail: `消费追踪数据不存在（${statsPath}）` });
   }
 
@@ -358,268 +727,94 @@ export async function knowledgeHealth(options: KnowledgeOptions & { dir?: string
   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) {
-    log(io, JSON.stringify({
-      healthScore,
-      summary: {
-        total: entries.length,
-        lowRefEntries,
-        staleEntries,
-        consumptionData,
-        refCoverage,
-        avgRefs,
-      },
-      issues: issues.slice(0, 50),
-    }, null, 2));
-    return { kind: 'ok' };
-  }
-
-  log(io, chalk.blue('🏥 飞轮健康检查\n'));
-  log(io, chalk.bold(`  健康分: ${healthScore >= 80 ? chalk.green(healthScore) : healthScore >= 60 ? chalk.yellow(healthScore) : chalk.red(healthScore)}/100`));
-  log(io, chalk.bold(`  活跃条目: ${entries.length}`));
-  log(io);
-
-  log(io, chalk.bold('  数据流状态:'));
-  log(io, `    引用密度: ${lowRefEntries === 0 ? chalk.green('✓') : chalk.yellow(`⚠ ${lowRefEntries} 个零引用 verified`)}`);
-  log(io, `    新鲜度: ${staleEntries === 0 ? chalk.green('✓') : chalk.yellow(`⚠ ${staleEntries} 个过期 draft`)}`);
-  log(io, `    消费追踪: ${consumptionData ? chalk.green('✓') : chalk.gray('○ 未启用')}`);
-  log(io);
-
-  log(io, chalk.bold('  飞轮指标:'));
-  log(io, `    引用覆盖: ${refCoverage}%`);
-  log(io, `    平均引用: ${avgRefs}`);
-  log(io);
-
-  if (issues.length > 0) {
-    log(io, chalk.bold(`  问题 (前 20):`));
-    for (const issue of issues.slice(0, 20)) {
-      const sevColor = issue.severity === 'error' ? chalk.red
-        : issue.severity === 'warn' ? chalk.yellow
-        : chalk.gray;
-      log(io, `    ${sevColor(`[${issue.severity}]`)} ${issue.entry}: ${issue.detail}`);
-    }
-    if (issues.length > 20) {
-      log(io, chalk.gray(`    ... 还有 ${issues.length - 20} 条`));
-    }
-  } else {
-    log(io, chalk.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: string): boolean {
-  try {
-    return fs.existsSync(dir) && fs.readdirSync(dir).length > 0;
-  } catch {
-    return false;
-  }
-}
-
-function getKnowledgeDir(projectPath: string | undefined, io: CommandIO): string {
-  if (projectPath) return `${projectPath}/.harness/knowledge`;
-  if (process.env.KNOWLEDGE_BASE_DIR) return process.env.KNOWLEDGE_BASE_DIR;
-  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 输出
-      logError(io, chalk.yellow(`⚠ 缺省知识库根已改为 ${defaultDir}；旧目录 ${legacyDir} 仍有数据，本次沿用（免迁移，可用 KNOWLEDGE_BASE_DIR 覆盖）`));
-    }
-    return legacyDir;
-  }
-  return defaultDir;
-}
-
-/**
- * 知识库质量审计
- */
-export async function knowledgeAudit(options: KnowledgeOptions & {
-  fix?: boolean;
-  dryRun?: boolean;
-  threshold?: number;
-  dir?: string;
-}, io: CommandIO = processIO): Promise<CommandResult> {
-  const audit = new KnowledgeAudit({
-    baseDir: options.dir || getKnowledgeDir(options.projectPath, io),
-    shortContentThreshold: options.threshold ? parseInt(options.threshold as any, 10) : undefined,
-  });
-
-  const isDryRun = options.dryRun && !options.fix;
-
-  if (!options.json && !isDryRun) {
-    log(io, chalk.blue('🔍 知识库质量审计...\n'));
-  }
-
-  const report = audit.run({ autoFix: options.fix && !isDryRun });
-
-  if (options.json) {
-    log(io, JSON.stringify(report, null, 2));
-    return { kind: 'ok' };
-  }
-
-  // Summary
-  log(io, chalk.bold(`  总条目: ${report.totalEntries}`));
-  log(io, chalk.bold(`  健康分: ${report.healthScore.before}/100`));
-  if (report.autoFixed > 0) {
-    log(io, chalk.green(`  自动修复: ${report.autoFixed} 条`));
-    log(io, chalk.bold(`  修复后: ${report.healthScore.after}/100`));
-  }
-  log(io);
-
-  // Dimension scores（Record 全键标注 → 编译期闭环，#109）
-  const dimLabels: Record<keyof AuditReport['dimensions'], string> = {
-    structure: 'D1 结构完整性',
-    content: 'D2 内容质量',
-    dedup: 'D3 去重有效性',
-    maturity: 'D4 成熟度健康',
-    freshness: 'D5 新鲜度',
-    flywheel: 'D6 飞轮验证',
-    incremental: 'D7 增量存活',
+  const data: HealthData = {
+    healthScore,
+    summary: { total: entries.length, lowRefEntries, staleEntries, consumptionData, refCoverage, avgRefs },
+    issues: issues.slice(0, 50),
   };
-  log(io, chalk.bold('  维度评分:'));
-  for (const [key, dim] of Object.entries(report.dimensions)) {
-    const label = dimLabels[key as keyof AuditReport['dimensions']];
-    const scoreColor = dim.score >= 80 ? chalk.green : dim.score >= 60 ? chalk.yellow : chalk.red;
-    log(io, `    ${label}: ${scoreColor(`${dim.score}/100`)} (${dim.issues} 问题)`);
-  }
-  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 = AUDIT_RULE_LABELS[rule as AuditRuleName];
-    log(io, `  ${chalk.red(`${label}: ${count}`)}`);
-  }
-
-  // Detail (first 20)
-  if (report.issues.length > 0) {
-    log(io, chalk.bold(`\n  问题详情 (前 20 条):\n`));
-    for (const issue of report.issues.slice(0, 20)) {
-      const severityColor = issue.severity === 'critical' ? chalk.red
-        : issue.severity === 'high' ? chalk.yellow
-        : chalk.gray;
-      log(io, `  ${severityColor(`[${issue.severity}]`)} ${issue.entryId}: ${issue.title}`);
-      log(io, `    ${chalk.gray(issue.detail)} → ${issue.action}`);
-    }
-    if (report.issues.length > 20) {
-      log(io, chalk.gray(`\n  ... 还有 ${report.issues.length - 20} 条`));
-    }
-  }
-
-  if (!options.fix && report.issues.length > 0) {
-    log(io, chalk.yellow(`\n  使用 --fix 自动修复`));
-  }
 
-  // Auto-rebuild index after audit (files may have changed)
-  const baseDir = options.dir || getKnowledgeDir(options.projectPath, io);
-  const idxGen = new KnowledgeIndexGenerator(baseDir);
-  idxGen.regenerate();
-  if (!options.json) {
-    log(io, chalk.gray(`  📇 索引已重建`));
-  }
-  return { kind: 'ok' };
+  return { data, human: (): DisplayModel => ({ sections: healthSections(data) }) };
 }
 
-/**
- * 知识库快照（KR4 存活率追踪）
- */
-export function knowledgeSnapshot(options: KnowledgeOptions & { dir?: string }, io: CommandIO = processIO): CommandResult {
-  const store = new KnowledgeStore({ baseDir: options.dir || getKnowledgeDir(options.projectPath, io) });
-  const snapPath = store.snapshot();
-
-  if (options.json) {
-    log(io, JSON.stringify({ snapshotPath: snapPath }));
-    return { kind: 'ok' };
-  }
-
-  log(io, chalk.green(`✅ 快照已保存: ${snapPath}`));
-  return { kind: 'ok' };
+function healthSections(data: HealthData): DisplaySection[] {
+  const { healthScore, summary, issues } = data;
+  const scoreTone = toneForScore(healthScore);
+  return [
+    {
+      rows: [
+        { cells: [{ label: '🏥 飞轮健康检查', tone: 'heading' }] },
+        blankLine(),
+        { cells: [
+          { label: '  健康分: ', tone: 'emph' },
+          { field: 'healthScore', text: String(healthScore), tone: scoreTone },
+          { label: '/100', tone: 'emph' },
+        ] },
+        { cells: [
+          { label: '  活跃条目: ', tone: 'emph' },
+          { field: 'summary.total', text: String(summary.total), tone: 'emph' },
+        ] },
+        blankLine(),
+      ],
+    },
+    {
+      title: '  数据流状态:',
+      rows: [
+        densityRow('    引用密度: ', 'summary.lowRefEntries', summary.lowRefEntries, ' 个零引用 verified'),
+        densityRow('    新鲜度: ', 'summary.staleEntries', summary.staleEntries, ' 个过期 draft'),
+        { cells: [
+          { label: '    消费追踪: ' },
+          summary.consumptionData
+            ? { label: '✓', tone: 'ok' }
+            : { field: 'summary.consumptionData', text: '○ 未启用', tone: 'muted' },
+        ] },
+        blankLine(),
+      ],
+    },
+    {
+      title: '  飞轮指标:',
+      rows: [
+        { cells: [{ label: '    引用覆盖: ' }, { field: 'summary.refCoverage', text: `${summary.refCoverage}%` }] },
+        { cells: [{ label: '    平均引用: ' }, { field: 'summary.avgRefs', text: String(summary.avgRefs) }] },
+        blankLine(),
+      ],
+    },
+    {
+      title: '  问题 (前 20):',
+      rows: issues.length === 0
+        ? [{ cells: [{ label: '  ✓ 无问题', tone: 'ok' }] }]
+        : [
+          ...issues.slice(0, 20).map((issue, i) => ({
+            cells: [
+              { field: `issues.${i}.severity`, text: `    [${issue.severity}]`, tone: toneForSeverity(issue.severity) },
+              { field: `issues.${i}.entry`, text: ` ${issue.entry}: ` },
+              { field: `issues.${i}.detail`, text: issue.detail },
+            ],
+          })),
+          // 溢出计数取全量数组，而 json 面的 issues 已截 50 条 → 无字段可锚，登记派生量
+          ...(issues.length > 20
+            ? [{ cells: [{ derived: 'healthIssuesOverflow', text: `    ... 还有 ${issues.length - 20} 条`, tone: 'muted' as const }] }]
+            : []),
+        ],
+    },
+  ];
 }
 
-/**
- * 知识库迁移 — 为现有条目添加 AS-021 新字段
- */
-export function knowledgeMigrate(options: KnowledgeOptions & { dir?: string }, io: CommandIO = processIO): CommandResult {
-  const baseDir = options.dir || getKnowledgeDir(options.projectPath, io);
-
-  if (options.json) {
-    const result = migrateKnowledgeEntries(baseDir);
-    log(io, JSON.stringify(result, null, 2));
-    return { kind: 'ok' };
-  }
-
-  log(io, chalk.blue('🔄 迁移知识条目（添加 consumptionMode/origin 字段）\n'));
-  const result = migrateKnowledgeEntries(baseDir);
-
-  log(io, chalk.green(`  总计: ${result.total} 条`));
-  log(io, chalk.green(`  已迁移: ${result.migrated} 条`));
-  log(io, chalk.gray(`  已跳过: ${result.skipped} 条`));
-
-  if (result.errors.length > 0) {
-    log(io, chalk.red(`\n  错误: ${result.errors.length} 条`));
-    for (const err of result.errors.slice(0, 5)) {
-      log(io, chalk.red(`    ${err}`));
-    }
-  }
-
-  if (result.migrated === 0 && result.errors.length === 0) {
-    log(io, chalk.green('\n✅ 所有条目已是最新，无需迁移'));
-  } else if (result.migrated > 0) {
-    log(io, chalk.green(`\n✅ 迁移完成`));
-  }
-  return { kind: 'ok' };
+function densityRow(prefix: string, field: string, count: number, suffix: string): DisplayRow {
+  if (count === 0) return { cells: [{ label: prefix }, { label: '✓', tone: 'ok' }] };
+  return {
+    cells: [
+      { label: prefix },
+      { label: '⚠ ', tone: 'warn' },
+      { field, text: String(count), tone: 'warn' },
+      { label: suffix, tone: 'warn' },
+    ],
+  };
 }
 
-/**
- * 知识库索引重建 — 生成 _index.md 供 Agent grep 使用，同时同步 index.json
- */
-export function knowledgeIndex(options: KnowledgeOptions & { dir?: string }, io: CommandIO = processIO): CommandResult {
-  const baseDir = options.dir || getKnowledgeDir(options.projectPath, io);
-  const gen = new KnowledgeIndexGenerator(baseDir);
-
-  const beforeSize = (() => {
-    const indexPath = path.join(baseDir, '_index.md');
-    return fs.existsSync(indexPath) ? fs.statSync(indexPath).size : 0;
-  })();
-
-  const output = gen.regenerate();
-
-  // Sync index.json from disk files (removes ghost entries from manual mv/rm)
-  const store = new KnowledgeStore({ baseDir });
-  store.rebuildIndex();
-
-  const afterSize = Buffer.byteLength(output, 'utf-8');
-  const lineCount = output.split('\n').filter(l => !l.startsWith('#')).length;
-
-  if (options.json) {
-    log(io, JSON.stringify({
-      path: path.join(baseDir, '_index.md'),
-      entries: lineCount,
-      size: afterSize,
-      previousSize: beforeSize,
-    }));
-    return { kind: 'ok' };
-  }
-
-  log(io, chalk.blue(`📇 索引已重建`));
-  log(io, chalk.gray(`  路径: ${path.join(baseDir, '_index.md')}`));
-  log(io, chalk.green(`  条目: ${lineCount}`));
-  log(io, chalk.green(`  大小: ${(afterSize / 1024).toFixed(1)} KB`));
-  if (beforeSize > 0) {
-    log(io, chalk.gray(`  旧大小: ${(beforeSize / 1024).toFixed(1)} KB`));
-  }
-  return { kind: 'ok' };
+export async function knowledgeHealth(options: KnowledgeOptions & KnowledgeDirOption, io: CommandIO = processIO): Promise<CommandResult> {
+  return emitKnowledgeView(io, options, knowledgeHealthView(options, io));
 }