@dommaker/harness 0.12.5 → 0.12.9

package/bin/harness-knowledge-capture.js

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+/**
+ * Harness Knowledge Capture Hook
+ *
+ * Runs as an afterTurn hook in Claude Code.
+ * Detects deep analysis (≥3 source files read) without knowledge-doc output,
+ * and warns the user that knowledge may need to be captured.
+ *
+ * Usage (in settings.json):
+ *   "hooks": {
+ *     "afterTurn": [{
+ *       "command": "node ~/projects/harness/bin/harness-knowledge-capture.js"
+ *     }]
+ *   }
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// Read turn data from stdin
+let input = '';
+process.stdin.setEncoding('utf-8');
+process.stdin.on('data', (chunk) => input += chunk);
+
+process.stdin.on('end', () => {
+  try {
+    const turn = JSON.parse(input);
+    const result = checkTurn(turn);
+    if (result.shouldWarn) {
+      process.stderr.write(`\n${'='.repeat(60)}\n`);
+      process.stderr.write('  ⚠️  可能遗漏了知识沉淀\n');
+      process.stderr.write(`${'='.repeat(60)}\n`);
+      process.stderr.write(`  本回合读取了 ${result.fileReads} 个文件\n`);
+      process.stderr.write(`  但未写入 .harness/knowledge-docs/\n`);
+      process.stderr.write(`\n`);
+      process.stderr.write(`  如果这是深度分析，请执行：\n`);
+      process.stderr.write(`    npx harness knowledge upsert --scope <scope> --file <file> --source claude\n`);
+      process.stderr.write(`${'='.repeat(60)}\n\n`);
+    }
+  } catch (e) {
+    // Silently ignore parse errors — non-JSON input is fine
+  }
+});
+
+function checkTurn(turn) {
+  let fileReads = 0;
+  let knowledgeWrites = 0;
+
+  // Walk through messages looking for tool calls
+  const messages = turn.messages || [turn];
+  for (const msg of messages) {
+    // Claude Code format: tool_uses array
+    if (msg.role === 'assistant' && msg.tool_uses) {
+      for (const tool of msg.tool_uses) {
+        if (isFileRead(tool)) fileReads++;
+        if (isKnowledgeWrite(tool)) knowledgeWrites++;
+      }
+    }
+    // Plain tool_calls format
+    if (msg.tool_calls) {
+      for (const tool of msg.tool_calls) {
+        if (isFileRead(tool)) fileReads++;
+        if (isKnowledgeWrite(tool)) knowledgeWrites++;
+      }
+    }
+    // Messages content with tool use markers
+    if (msg.content && typeof msg.content === 'string') {
+      const readMatches = msg.content.match(/\bRead\b.*/g);
+      if (readMatches) fileReads += readMatches.length;
+    }
+  }
+
+  return {
+    fileReads,
+    knowledgeWrites,
+    shouldWarn: fileReads >= 3 && knowledgeWrites === 0,
+  };
+}
+
+function isFileRead(tool) {
+  const name = (tool.name || tool.function?.name || '').toLowerCase();
+  const isReadTool = ['read', 'glob', 'grep', 'agent'].includes(name);
+  if (!isReadTool) return false;
+
+  const params = tool.parameters || tool.function?.arguments || {};
+  const filePath = params.file_path || params.path || params.pattern || '';
+  // Only count actual source file reads, not config/memory/docs
+  const isSource = /\/(src|packages|apps)\/|\.(ts|tsx|js|jsx|py|go|rs)$/.test(filePath);
+  return isSource;
+}
+
+function isKnowledgeWrite(tool) {
+  const name = (tool.name || tool.function?.name || '').toLowerCase();
+  if (name !== 'write') return false;
+
+  const params = tool.parameters || tool.function?.arguments || {};
+  const filePath = params.file_path || '';
+  return filePath.includes('.harness/knowledge-docs/') || filePath.includes('.harness/knowledge/');
+}

package/bin/harness-knowledge-check.js

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+/**
+ * Stop hook — check if deep analysis happened without knowledge capture
+ *
+ * Reads state file written by harness-knowledge-track.js.
+ * If EnterPlanMode was called, or Agent(Explore) was spawned, or 10+ unique
+ * directories were Read — and no knowledge files were Written — warn.
+ *
+ * Output: JSON with systemMessage (shown to user)
+ */
+
+const fs = require('fs');
+const STATE_FILE = '/tmp/claude-knowledge-capture-state.json';
+const LOG_FILE = '/tmp/claude-knowledge-hooks.log';
+const UNIQUE_DIR_THRESHOLD = 10;
+
+function log(level, message, data) {
+  try {
+    const entry = JSON.stringify({ ts: new Date().toISOString(), level, message, ...data }) + '\n';
+    fs.appendFileSync(LOG_FILE, entry, 'utf-8');
+  } catch {}
+}
+
+try {
+  if (!fs.existsSync(STATE_FILE)) process.exit(0);
+
+  const state = JSON.parse(fs.readFileSync(STATE_FILE, 'utf-8'));
+  const deepAnalysis = state.planned || state.explored || state.readDirs.length >= UNIQUE_DIR_THRESHOLD;
+  const missingCapture = !state.captured;
+
+  log('info', 'stop-check', {
+    planned: state.planned, explored: state.explored,
+    readDirsCount: state.readDirs.length, captured: state.captured,
+    deepAnalysis, missingCapture,
+  });
+
+  if (deepAnalysis && missingCapture) {
+    const signals = [];
+    if (state.planned) signals.push('EnterPlanMode called');
+    if (state.explored) signals.push('Agent(Explore) spawned');
+    if (state.readDirs.length >= UNIQUE_DIR_THRESHOLD) signals.push(`${state.readDirs.length} unique directories Read`);
+
+    log('warn', 'missing-capture', { signals });
+
+    const message = [
+      '⚠️  Deep analysis detected but no knowledge captured.',
+      `   Signals: ${signals.join(', ')}`,
+      '',
+      '   To capture:',
+      '   1. Write .harness/knowledge-docs/<scope>.md',
+      '   2. npx harness knowledge upsert --scope <scope> --file <file> --source claude',
+      '',
+      '   Or run `harness knowledge sync-status` to check staleness.',
+    ].join('\n');
+
+    console.log(JSON.stringify({ systemMessage: message }));
+  }
+} catch (e) {
+  // Silently ignore errors
+} finally {
+  // Clean up state file for next session
+  try { fs.unlinkSync(STATE_FILE); } catch {}
+}

package/bin/harness-knowledge-track.js

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+/**
+ * PostToolUse hook — track deep analysis signals
+ *
+ * Updates state file with:
+ *   - planned: EnterPlanMode was called
+ *   - explored: Agent(Explore) was spawned
+ *   - readDirs: Set of unique directories Read was called on
+ *   - captured: Write to .harness/knowledge-docs/ or .harness/knowledge/
+ *   - turnCount: session turn counter
+ *
+ * Usage: PostToolUse hook with matcher "EnterPlanMode|Agent|Read|Write|Write"
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const STATE_FILE = '/tmp/claude-knowledge-capture-state.json';
+const LOG_FILE = '/tmp/claude-knowledge-hooks.log';
+
+function log(level, message, data) {
+  try {
+    const entry = JSON.stringify({ ts: new Date().toISOString(), level, message, ...data }) + '\n';
+    fs.appendFileSync(LOG_FILE, entry, 'utf-8');
+  } catch {}
+}
+
+// Read hook input from stdin
+let input = '';
+process.stdin.setEncoding('utf-8');
+process.stdin.on('data', (chunk) => input += chunk);
+
+process.stdin.on('end', () => {
+  try {
+    const event = JSON.parse(input);
+    const state = loadState();
+    updateState(state, event);
+    saveState(state);
+  } catch (e) {
+    // Silently ignore parse errors
+  }
+});
+
+function loadState() {
+  try {
+    if (fs.existsSync(STATE_FILE)) {
+      return JSON.parse(fs.readFileSync(STATE_FILE, 'utf-8'));
+    }
+  } catch {}
+  return { planned: false, explored: false, readDirs: [], captured: false };
+}
+
+function updateState(state, event) {
+  const toolName = event.tool_name || '';
+
+  if (toolName === 'EnterPlanMode') {
+    state.planned = true;
+    log('info', 'planned', { tool: toolName });
+  }
+
+  if (toolName === 'Agent') {
+    const input = event.tool_input || {};
+    if (input.subagent_type === 'Explore') {
+      state.explored = true;
+      log('info', 'explored', { tool: toolName, subagent_type: input.subagent_type });
+    }
+  }
+
+  if (toolName === 'Read') {
+    const input = event.tool_input || {};
+    const filePath = input.file_path || '';
+    const dir = path.dirname(filePath);
+    if (dir && dir !== '.' && dir !== '/' && !state.readDirs.includes(dir)) {
+      state.readDirs.push(dir);
+    }
+  }
+
+  if (toolName === 'Write') {
+    const input = event.tool_input || {};
+    const filePath = input.file_path || '';
+    if (filePath.includes('.harness/knowledge-docs/') || filePath.includes('.harness/knowledge/')) {
+      state.captured = true;
+      log('info', 'captured', { file: filePath });
+    }
+  }
+}
+
+function saveState(state) {
+  try {
+    fs.writeFileSync(STATE_FILE, JSON.stringify(state), 'utf-8');
+  } catch {}
+}

package/bin/harness-knowledge-track.sh

@@ -0,0 +1,34 @@
+#!/bin/bash
+# PostToolUse hook — track deep analysis signals
+# Replaces Node.js version. Bash: <1ms vs Node: 33ms cold start.
+# Matcher: Read|Write (most frequent tools, covers all signals needed)
+
+STATE_FILE=/tmp/claude-knowledge-capture-state.json
+INPUT=$(cat)
+
+tool_name=$(echo "$INPUT" | jq -r '.tool_name // ""')
+file_path=$(echo "$INPUT" | jq -r '.tool_input.file_path // ""')
+
+# Init state file if missing
+[ -f "$STATE_FILE" ] || echo '{"planned":false,"explored":false,"readDirs":[],"captured":false}' > "$STATE_FILE"
+
+case "$tool_name" in
+  EnterPlanMode)
+    jq '.planned = true' "$STATE_FILE" > "${STATE_FILE}.tmp" && mv "${STATE_FILE}.tmp" "$STATE_FILE"
+    ;;
+  Read)
+    if [ -n "$file_path" ]; then
+      dir=$(dirname "$file_path")
+      if [ "$dir" != "." ] && [ "$dir" != "/" ]; then
+        jq --arg d "$dir" '.readDirs += [$d] | .readDirs |= unique' "$STATE_FILE" > "${STATE_FILE}.tmp" && mv "${STATE_FILE}.tmp" "$STATE_FILE"
+      fi
+    fi
+    ;;
+  Write)
+    case "$file_path" in
+      *.harness/knowledge-docs/*|*.harness/knowledge/*)
+        jq '.captured = true' "$STATE_FILE" > "${STATE_FILE}.tmp" && mv "${STATE_FILE}.tmp" "$STATE_FILE"
+        ;;
+    esac
+    ;;
+esac

package/bin/harness.js

@@ -36,9 +36,16 @@ const {
   knowledgeImport,
   knowledgeDecay,
   knowledgeStats,
+  knowledgeUpsert,
+  knowledgeSyncStatus,
+  knowledgeSyncRag,
   failureList,
   failureStats,
   failureClear,
+  postevalPlan,
+  analyzeSessions,
+  updateUserModel,
+  release,
 } = require('../dist/cli/commands/index');
 
 const program = new Command();
@@ -353,6 +360,11 @@ program
   .option('--sources <sources>', '导入源（逗号分隔: code,git,docs）')
   .option('--limit <n>', '结果数量限制', '20')
   .option('--reset', '重置导入状态', false)
+  .option('--scope <scope>', '知识范围（用于 upsert 去重）')
+  .option('--title <title>', '知识标题（用于 upsert）')
+  .option('--content <content>', '知识内容 Markdown（用于 upsert）')
+  .option('--file <path>', '从文件读取内容（用于 upsert）')
+  .option('--source <source>', '知识来源 (analyst/cli/design)', 'cli')
   .option('--json', 'JSON 格式输出', false)
   .action(async (subcommand, arg, options) => {
     const opts = { projectPath: options.projectPath, json: options.json };
@@ -378,6 +390,24 @@ program
       case 'st':
         await knowledgeStats(opts);
         break;
+      case 'sync-rag':
+        await knowledgeSyncRag(opts);
+        break;
+      case 'sync-status':
+      case 'sync':
+        await knowledgeSyncStatus(opts);
+        break;
+      case 'upsert':
+      case 'up':
+        await knowledgeUpsert({
+          scope: options.scope || '',
+          title: options.title || '',
+          content: options.content || '',
+          file: options.file || '',
+          type: options.type || 'architecture',
+          source: options.source || 'cli',
+        });
+        break;
       default:
         // 无子命令时显示帮助
         if (!subcommand) {
@@ -424,5 +454,56 @@ program
     }
   });
 
+// ========================================
+// harness posteval-plan
+// ========================================
+program
+  .command('posteval-plan <planPath>')
+  .description('验证 plan 文件的 checklist items 是否都有对应的 staged diff')
+  .action(async (planPath) => {
+    await postevalPlan({ planPath });
+  });
+
+// ========================================
+// harness update-user-model
+// ========================================
+program
+  .command('update-user-model')
+  .description('从新对话中提取信号，更新用户思维模型（增量演化）')
+  .alias('uum')
+  .option('--json', 'JSON 格式输出', false)
+  .option('--dry-run', '只显示变化，不更新状态', false)
+  .action(async (options) => {
+    await updateUserModel({ json: options.json, dryRun: options.dryRun });
+  });
+
+// ========================================
+// harness release
+// ========================================
+program
+  .command('release')
+  .description('npm 发布流水线：tsc → dist 验证 → npm version → git push → npm publish → gh release。不依赖 Studio API。')
+  .option('--bump <type>', '版本递增类型', 'patch')
+  .option('--dry-run <bool>', '仅模拟执行', 'false')
+  .action(async (options) => {
+    await release({ bumpType: options.bump, dryRun: options.dryRun });
+  });
+
+// ========================================
+// harness analyze-sessions
+// ========================================
+program
+  .command('analyze-sessions')
+  .description('分析 Claude Code 对话，挖掘纠正模式和高频概念，生成规则候选')
+  .alias('analyze')
+  .option('-d, --days <n>', '分析最近 N 天的会话', '7')
+  .option('--json', 'JSON 格式输出', false)
+  .action(async (options) => {
+    await analyzeSessions({
+      days: parseInt(options.days, 10),
+      json: options.json,
+    });
+  });
+
 // 解析命令行参数
 program.parse();

package/dist/cli/commands/analyze-sessions.d.ts

@@ -0,0 +1,17 @@
+/**
+ * harness analyze-sessions — 对话模式发现引擎
+ *
+ * 扫描 transcript 文件，不预设关键词，挖掘：
+ *   1. 纠正信号（用户反复指出的问题）
+ *   2. 高频 N-gram（跨会话重复出现的概念）
+ *   3. 规则缺口（高频模式未被现有 memory 覆盖）
+ *
+ * 输出候选规则建议，供用户审核后写入 memory。
+ */
+export interface AnalyzeSessionsOptions {
+    days?: number;
+    projectPath?: string;
+    json?: boolean;
+}
+export declare function analyzeSessions(options: AnalyzeSessionsOptions): Promise<void>;
+//# sourceMappingURL=analyze-sessions.d.ts.map

package/dist/cli/commands/analyze-sessions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyze-sessions.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/analyze-sessions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAOH,MAAM,WAAW,sBAAsB;IACrC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAmDD,wBAAsB,eAAe,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC,CAwCpF"}