@dommaker/harness 0.13.3 → 0.14.0

package/src/cli/commands/__tests__/knowledge.test.ts

@@ -0,0 +1,167 @@
+/**
+ * knowledge 命令测试 — knowledgeAudit
+ */
+
+import { knowledgeAudit, knowledgeStats } from '../knowledge';
+
+// Mock chalk
+jest.mock('chalk', () => ({
+  blue: jest.fn((str: string) => str),
+  bold: jest.fn((str: string) => str),
+  green: jest.fn((str: string) => str),
+  yellow: jest.fn((str: string) => str),
+  red: jest.fn((str: string) => str),
+  gray: jest.fn((str: string) => str),
+}));
+
+// Mock KnowledgeAudit
+const mockRun = jest.fn();
+jest.mock('../../../knowledge/audit', () => ({
+  KnowledgeAudit: jest.fn().mockImplementation(() => ({
+    run: mockRun,
+  })),
+}));
+
+const MOCK_REPORT = {
+  timestamp: '2026-06-02T00:00:00.000Z',
+  totalEntries: 100,
+  issues: [
+    {
+      rule: 'short-content',
+      entryId: 'GUI-001',
+      title: 'Short Entry',
+      severity: 'medium',
+      action: 'flag',
+      detail: 'content 30 chars',
+    },
+  ],
+  summary: {
+    'frontmatter-missing': 0,
+    'test-data-pollution': 0,
+    'daily-audit-noise': 0,
+    'zero-content-proven': 0,
+    'short-content': 1,
+    'maturity-inflation': 0,
+    'title-duplicate': 0,
+    'source-refs-bloat': 0,
+    'promotion-blocked': 0,
+    'orphan-draft': 0,
+    'stale-entry': 0,
+  },
+  dimensions: {
+    structure: { score: 100, issues: 0, details: {} },
+    content: { score: 95, issues: 1, details: {} },
+    dedup: { score: 100, issues: 0, details: {} },
+    maturity: { score: 100, issues: 0, details: {} },
+    freshness: { score: 100, issues: 0, details: {} },
+    flywheel: { score: 50, issues: 0, details: {} },
+  },
+  autoFixed: 0,
+  healthScore: { before: 95, after: 95 },
+};
+
+describe('getKnowledgeDir', () => {
+  const os = require('os');
+  const path = require('path');
+  const storeModule = require('../../../knowledge/store');
+  let storeCtorSpy: jest.SpyInstance;
+
+  beforeEach(() => {
+    delete process.env.KNOWLEDGE_BASE_DIR;
+    storeCtorSpy = jest.spyOn(storeModule, 'KnowledgeStore').mockImplementation(() => ({
+      list: jest.fn().mockReturnValue([]),
+    }));
+  });
+
+  afterEach(() => {
+    storeCtorSpy.mockRestore();
+    delete process.env.KNOWLEDGE_BASE_DIR;
+  });
+
+  it('should use KNOWLEDGE_BASE_DIR env var when set', async () => {
+    process.env.KNOWLEDGE_BASE_DIR = '/custom/knowledge';
+    await knowledgeStats({ json: true });
+    expect(storeCtorSpy).toHaveBeenCalledWith(expect.objectContaining({
+      baseDir: '/custom/knowledge',
+    }));
+  });
+
+  it('should default to ~/.studio/knowledge when no env var', async () => {
+    const expected = path.join(os.homedir(), '.studio', 'knowledge');
+    await knowledgeStats({ json: true });
+    expect(storeCtorSpy).toHaveBeenCalledWith(expect.objectContaining({
+      baseDir: expected,
+    }));
+  });
+
+  it('should use projectPath when provided', async () => {
+    await knowledgeStats({ projectPath: '/my/project', json: true });
+    expect(storeCtorSpy).toHaveBeenCalledWith(expect.objectContaining({
+      baseDir: '/my/project/.harness/knowledge',
+    }));
+  });
+});
+
+describe('knowledgeAudit CLI', () => {
+  let consoleSpy: jest.SpyInstance;
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    consoleSpy = jest.spyOn(console, 'log').mockImplementation();
+    mockRun.mockReturnValue(MOCK_REPORT);
+  });
+
+  afterEach(() => {
+    consoleSpy.mockRestore();
+  });
+
+  it('should output JSON when --json is set', async () => {
+    await knowledgeAudit({ json: true });
+    expect(consoleSpy).toHaveBeenCalledWith(JSON.stringify(MOCK_REPORT, null, 2));
+  });
+
+  it('should call audit.run with autoFix=true when --fix is set', async () => {
+    await knowledgeAudit({ fix: true });
+    expect(mockRun).toHaveBeenCalledWith({ autoFix: true });
+  });
+
+  it('should call audit.run with autoFix falsy when --dry-run is set', async () => {
+    await knowledgeAudit({ dryRun: true });
+    expect(mockRun).toHaveBeenCalledWith({ autoFix: undefined });
+  });
+
+  it('should call audit.run with autoFix falsy by default', async () => {
+    await knowledgeAudit({});
+    expect(mockRun).toHaveBeenCalledWith({ autoFix: undefined });
+  });
+
+  it('should display total entries and health score', async () => {
+    await knowledgeAudit({});
+    const output = consoleSpy.mock.calls.map((c: any[]) => c[0]).join('\n');
+    expect(output).toContain('总条目: 100');
+    expect(output).toContain('95/100');
+  });
+
+  it('should display dimension scores', async () => {
+    await knowledgeAudit({});
+    const output = consoleSpy.mock.calls.map((c: any[]) => c[0]).join('\n');
+    expect(output).toContain('D1 结构完整性');
+    expect(output).toContain('D6 飞轮验证');
+  });
+
+  it('should display autoFixed count when > 0', async () => {
+    mockRun.mockReturnValue({ ...MOCK_REPORT, autoFixed: 5, healthScore: { before: 90, after: 95 } });
+    await knowledgeAudit({ fix: true });
+    const output = consoleSpy.mock.calls.map((c: any[]) => c[0]).join('\n');
+    expect(output).toContain('自动修复: 5');
+    expect(output).toContain('修复后: 95/100');
+  });
+
+  it('should pass custom dir to KnowledgeAudit', async () => {
+    const { KnowledgeAudit } = require('../../../knowledge/audit');
+    await knowledgeAudit({ dir: '/custom/path' });
+    expect(KnowledgeAudit).toHaveBeenCalledWith(expect.objectContaining({
+      baseDir: '/custom/path',
+    }));
+  });
+});

package/src/cli/commands/index.ts

@@ -17,7 +17,7 @@ export { contract, validateSchema, type ContractOptions } from './contract';
 export { review, reviewStatus, type ReviewOptions } from './review';
 export { executeCommand, type CommandCheckOptions } from './command';
 export { syncDocs, type SyncDocsOptions } from './sync-docs';
-export { knowledgeList, knowledgeSearch, knowledgeImport, knowledgeDecay, knowledgeStats, knowledgeUpsert, knowledgeSyncStatus, knowledgeSyncRag, type KnowledgeOptions, type KnowledgeUpsertOptions } from './knowledge';
+export { knowledgeList, knowledgeSearch, knowledgeImport, knowledgeDecay, knowledgeStats, knowledgeUpsert, knowledgeSyncStatus, knowledgeSyncRag, knowledgeAudit, knowledgeSnapshot, knowledgeMigrate, type KnowledgeOptions, type KnowledgeUpsertOptions } from './knowledge';
 export { failureList, failureStats, failureClear, type FailureOptions } from './failure';
 export { postevalPlan, type PostEvalPlanOptions } from './posteval-plan';
 export { release, type ReleaseOptions } from './release';

package/src/cli/commands/knowledge.ts

@@ -6,10 +6,14 @@
 
 import chalk from 'chalk';
 import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
 import { KnowledgeStore } from '../../knowledge/store';
 import { KnowledgeQuery } from '../../knowledge/query';
 import { KnowledgeLifecycle } from '../../knowledge/lifecycle';
 import { ColdStartImporter } from '../../knowledge/import';
+import { KnowledgeAudit } from '../../knowledge/audit';
+import { migrateKnowledgeEntries } from '../../knowledge/migration';
 import type { KnowledgeType, MaturityLevel, QueryFilter } from '../../knowledge/types';
 
 export interface KnowledgeOptions {
@@ -201,6 +205,7 @@ export async function knowledgeDecay(options: KnowledgeOptions): Promise<void> {
 export async function knowledgeStats(options: KnowledgeOptions): Promise<void> {
   const store = new KnowledgeStore({ baseDir: getKnowledgeDir(options.projectPath) });
   const entries = store.list({ excludeArchived: false });
+  const active = entries.filter(e => e.maturity !== 'archived');
 
   const byType: Record<string, number> = {};
   const byMaturity: Record<string, number> = {};
@@ -212,13 +217,31 @@ export async function knowledgeStats(options: KnowledgeOptions): Promise<void> {
     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;
+  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;
+    }
+  } catch { /* best-effort */ }
+
+  const flywheel = { refCoverage, avgRefs, consumptionHitRate };
+
   if (options.json) {
-    console.log(JSON.stringify({ total: entries.length, byType, byMaturity, byLayer }, null, 2));
+    console.log(JSON.stringify({ total: entries.length, byType, byMaturity, byLayer, flywheel }, null, 2));
     return;
   }
 
   console.log(chalk.blue(`📊 知识库统计\n`));
-  console.log(chalk.bold(`  总计: ${entries.length} 条\n`));
+  console.log(chalk.bold(`  总计: ${entries.length} 条 (活跃: ${active.length})\n`));
 
   console.log(chalk.bold('  按类型:'));
   for (const [type, count] of Object.entries(byType)) {
@@ -235,6 +258,11 @@ export async function knowledgeStats(options: KnowledgeOptions): Promise<void> {
   for (const [layer, count] of Object.entries(byLayer)) {
     console.log(`    ${layer}: ${count}`);
   }
+
+  console.log(chalk.bold('\n  飞轮指标:'));
+  console.log(`    引用覆盖: ${refCoverage}%`);
+  console.log(`    平均引用: ${avgRefs}`);
+  console.log(`    消费命中率: ${consumptionHitRate}%`);
 }
 
 export interface KnowledgeUpsertOptions {
@@ -386,6 +414,149 @@ export async function knowledgeSyncStatus(options: KnowledgeOptions): Promise<vo
 }
 
 function getKnowledgeDir(projectPath?: string): string {
-  const base = projectPath || process.cwd();
-  return `${base}/.harness/knowledge`;
+  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');
+}
+
+/**
+ * 知识库质量审计
+ */
+export async function knowledgeAudit(options: KnowledgeOptions & {
+  fix?: boolean;
+  dryRun?: boolean;
+  threshold?: number;
+  dir?: string;
+}): Promise<void> {
+  const audit = new KnowledgeAudit({
+    baseDir: options.dir || getKnowledgeDir(options.projectPath),
+    shortContentThreshold: options.threshold ? parseInt(options.threshold as any, 10) : undefined,
+  });
+
+  const isDryRun = options.dryRun && !options.fix;
+
+  if (!options.json && !isDryRun) {
+    console.log(chalk.blue('🔍 知识库质量审计...\n'));
+  }
+
+  const report = audit.run({ autoFix: options.fix && !isDryRun });
+
+  if (options.json) {
+    console.log(JSON.stringify(report, null, 2));
+    return;
+  }
+
+  // Summary
+  console.log(chalk.bold(`  总条目: ${report.totalEntries}`));
+  console.log(chalk.bold(`  健康分: ${report.healthScore.before}/100`));
+  if (report.autoFixed > 0) {
+    console.log(chalk.green(`  自动修复: ${report.autoFixed} 条`));
+    console.log(chalk.bold(`  修复后: ${report.healthScore.after}/100`));
+  }
+  console.log();
+
+  // Dimension scores
+  const dimLabels: Record<string, string> = {
+    structure: 'D1 结构完整性',
+    content: 'D2 内容质量',
+    dedup: 'D3 去重有效性',
+    maturity: 'D4 成熟度健康',
+    freshness: 'D5 新鲜度',
+    flywheel: 'D6 飞轮验证',
+  };
+  console.log(chalk.bold('  维度评分:'));
+  for (const [key, dim] of Object.entries(report.dimensions)) {
+    const label = dimLabels[key] || key;
+    const scoreColor = dim.score >= 80 ? chalk.green : dim.score >= 60 ? chalk.yellow : chalk.red;
+    console.log(`    ${label}: ${scoreColor(`${dim.score}/100`)} (${dim.issues} 问题)`);
+  }
+  console.log();
+
+  // Issues by rule
+  const ruleLabels: Record<string, string> = {
+    'frontmatter-missing': 'frontmatter 缺失',
+    'test-data-pollution': '测试数据污染',
+    'daily-audit-noise': '每日审计噪音',
+    'zero-content-proven': '零内容 proven',
+    'short-content': '短内容',
+    'maturity-inflation': '成熟度虚高',
+    'title-duplicate': '标题重复',
+    'source-refs-bloat': 'sourceReferences 膨胀',
+    'promotion-blocked': 'promotion 受阻',
+    'orphan-draft': '孤儿 draft',
+    'stale-entry': '过期条目',
+  };
+
+  for (const [rule, count] of Object.entries(report.summary)) {
+    if (count === 0) continue;
+    const label = ruleLabels[rule] || rule;
+    console.log(`  ${chalk.red(`${label}: ${count}`)}`);
+  }
+
+  // Detail (first 20)
+  if (report.issues.length > 0) {
+    console.log(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;
+      console.log(`  ${severityColor(`[${issue.severity}]`)} ${issue.entryId}: ${issue.title}`);
+      console.log(`    ${chalk.gray(issue.detail)} → ${issue.action}`);
+    }
+    if (report.issues.length > 20) {
+      console.log(chalk.gray(`\n  ... 还有 ${report.issues.length - 20} 条`));
+    }
+  }
+
+  if (!options.fix && report.issues.length > 0) {
+    console.log(chalk.yellow(`\n  使用 --fix 自动修复`));
+  }
+}
+
+/**
+ * 知识库快照（KR4 存活率追踪）
+ */
+export function knowledgeSnapshot(options: KnowledgeOptions & { dir?: string }): void {
+  const store = new KnowledgeStore({ baseDir: options.dir || getKnowledgeDir(options.projectPath) });
+  const snapPath = store.snapshot();
+
+  if (options.json) {
+    console.log(JSON.stringify({ snapshotPath: snapPath }));
+    return;
+  }
+
+  console.log(chalk.green(`✅ 快照已保存: ${snapPath}`));
+}
+
+/**
+ * 知识库迁移 — 为现有条目添加 AS-021 新字段
+ */
+export function knowledgeMigrate(options: KnowledgeOptions & { dir?: string }): void {
+  const baseDir = options.dir || getKnowledgeDir(options.projectPath);
+
+  if (options.json) {
+    const result = migrateKnowledgeEntries(baseDir);
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+
+  console.log(chalk.blue('🔄 迁移知识条目（添加 consumptionMode/origin 字段）\n'));
+  const result = migrateKnowledgeEntries(baseDir);
+
+  console.log(chalk.green(`  总计: ${result.total} 条`));
+  console.log(chalk.green(`  已迁移: ${result.migrated} 条`));
+  console.log(chalk.gray(`  已跳过: ${result.skipped} 条`));
+
+  if (result.errors.length > 0) {
+    console.log(chalk.red(`\n  错误: ${result.errors.length} 条`));
+    for (const err of result.errors.slice(0, 5)) {
+      console.log(chalk.red(`    ${err}`));
+    }
+  }
+
+  if (result.migrated === 0 && result.errors.length === 0) {
+    console.log(chalk.green('\n✅ 所有条目已是最新，无需迁移'));
+  } else if (result.migrated > 0) {
+    console.log(chalk.green(`\n✅ 迁移完成`));
+  }
 }

package/src/context/__tests__/knowledge-injector.test.ts

@@ -42,6 +42,9 @@ describe('KnowledgeInjector', () => {
       applicablePhases: [],
       sourceReferences: [],
       referencedBy: [],
+      executionResults: [],
+      consumptionMode: 'reference',
+      origin: 'agent',
       ...overrides,
     });
   }

package/src/core/constraints/definitions.ts

@@ -813,8 +813,10 @@ export const GUIDELINES: Record<string, Constraint> = {
     description: `删除任何代码（包/模块/文件）前，必须：
 1. 查设计文档（CLAUDE.md / roadmap / specs）
 2. 分析是否有可吸收的功能
-3. 记录分析结论（有/无吸收价值，原因）`,
-    promptInjection: '删除任何代码包或模块前，必须先查 CLAUDE.md 和相关设计文档，分析是否有可吸收的功能，并记录分析结论。',
+3. 查替代函数是否丢失了关键设计模式（零引用≠无价值）
+4. 分类：未接线（应接线）/ 被替代但有可吸收设计 / 真正无用
+5. 记录分析结论（有/无吸收价值，原因）`,
+    promptInjection: '删除任何代码前，先查设计意图（JSDoc/commit/spec），分析被替代的函数是否有丢失的关键模式。零引用≠无价值。分类：未接线→接线，被替代→吸收模式，真正无用→才删。',
   },
 
   /**

package/src/dashboard/__tests__/data.test.ts

@@ -22,6 +22,9 @@ function makeEntry(overrides: Partial<KnowledgeEntry> = {}): KnowledgeEntry {
     applicablePhases: [],
     sourceReferences: [],
     referencedBy: [],
+    executionResults: [],
+    consumptionMode: 'reference',
+    origin: 'agent',
     ...overrides,
   };
 }

package/src/dashboard/__tests__/stats.test.ts

@@ -21,6 +21,9 @@ function makeEntry(overrides: Partial<KnowledgeEntry> = {}): KnowledgeEntry {
     applicablePhases: [],
     sourceReferences: [],
     referencedBy: [],
+    executionResults: [],
+    consumptionMode: 'reference',
+    origin: 'agent',
     ...overrides,
   };
 }

package/src/index.ts

@@ -76,7 +76,9 @@ export * from './verification';
 // ========================================
 // 约束分层导出
 // ========================================
-export * from './constraints';
+export * from './constraints/types';
+export { ConstraintRegistry } from './constraints/registry';
+export { ConstraintLifecycleRunner } from './constraints/lifecycle-runner';
 
 // ========================================
 // Dashboard 数据导出

package/src/knowledge/CONTEXT.md

@@ -1,29 +1,51 @@
 # knowledge/
 
 ## 职责
-知识引擎：知识存储(CRUD)、语义查询、引用追踪、质量检查(Linter)、生命周期管理、冷启动导入、健康评分。
+知识引擎：知识存储(CRUD)、语义查询、引用追踪、质量审计(Audit)、质量检查(Linter)、生命周期管理、冷启动导入、健康评分、外部内容摄入。
+
+## 三维分类体系 (AS-021)
+知识由三个正交维度定义：
+- **Topic** — 开放集，用 `tags: string[]` 描述
+- **ConsumptionMode** — 闭集 (rule/reference/context/signal)，驱动注入策略和生命周期
+- **Origin** — 闭集 (human/agent/external/system)，影响信任度和 maturity 起点
+
+## 生命周期按模式分化
+- `rule`: draft → active → deprecated (1 次成功激活, 失败率>=50% 降级)
+- `reference`: draft → verified → proven → archived (现有逻辑)
+- `context`: draft → active → archived (1 次引用激活, 3 个月未引用归档)
+- `signal`: active → archived (消费饱和: ref>=3 + 有更新同标签条目)
+- 所有模式支持 `decayAt` 硬过期
 
 ## 核心导出
 - `KnowledgeStore` — 知识条目 CRUD + 结构化存储
-- `KnowledgeQuery` — 语义搜索 + 类型/标签过滤
-- `KnowledgeLifecycle` — 知识生命周期: draft → candidate → validated → canonical → archived
-- `KnowledgeIngest` — 知识摄取引擎
+- `KnowledgeQuery` — 语义搜索 + 类型/标签过滤 + `queryByMode()` + `consume(taskContext)`
+- `KnowledgeLifecycle` — per-mode 生命周期管理
+- `KnowledgeIngest` — 知识摄取引擎（含 ingest gate 质量门）+ `ingestExternal()` 外部内容摄入
+- `sanitizeExternalContent` — 外部内容安全清洗（过滤注入模式 + 长度限制）
+- `migrateKnowledgeEntries` — AS-021 迁移工具（为现有条目添加 consumptionMode/origin）
+- `KnowledgeAudit` — 6 维度质量审计引擎
 - `ReferenceTracker` — 知识引用关系图谱
 - `KnowledgeLinter` — 知识质量检查(完整性/一致性/时效性)
 - `ColdStartImporter` — 冷启动知识导入
-- `KnowledgeHealthScorer` — 知识健康评分
+- `KnowledgeHealthScorer` — 知识健康评分（doctor.ts）
 - `KnowledgeLifecycleHooks` — 生命周期 hook
 
 ## 依赖关系
 - 依赖 `src/types/` 知识相关类型
 - 依赖 `src/monitoring/` KnowledgeDoctor / KnowledgeEvolver
-- 被 `src/cli/commands/knowledge.ts` CLI 消费
+- 被 `src/cli/commands/knowledge.ts` CLI 消费（含 `migrate` 子命令）
 
 ## 约定
-- 知识条目有明确的生命周期状态
+- 知识条目有明确的生命周期状态（按 consumptionMode 分化）
 - 约束退化时自动写入 KnowledgeStore
 - Linter 检查完整性/一致性/时效性三个维度
+- Audit 6 维度评分：D1结构 D2内容 D3去重 D4成熟度 D5新鲜度 D6飞轮
+- Ingest gate: ingestEntry() 先经 audit.validate() 检查，reject 不入库
+- 外部内容三层防御：ingest sanitization + retrieval marking + prompt constraint
+- 消费饱和度替代固定 TTL 用于 signal 过期判断
 
 ## 注意事项
 - Phase 1+4 实现的知识引擎核心
 - 约束"退化不删除"——降级时保留规则原文 + 退化原因 + 历史数据
+- `MaturityLevel` 包含 6 个值: draft/verified/proven/archived/active/deprecated
+- `excludeArchived` 同时排除 archived 和 deprecated