@dommaker/harness 0.19.0 → 1.1.0

package/src/monitoring/constraint-doctor.ts

@@ -1,12 +1,7 @@
 /**
- * Agent 诊断接口
+ * 约束诊断器
  *
- * 当检测到异常时，提供 Agent 分析 traces 的能力
- *
- * 成本控制：
- * - 仅在有异常时触发
- * - 精简 prompt，不喂全部 traces
- * - ~2000 Token/次
+ * 当检测到异常时，基于预设规则分析 traces 给出诊断（零 Token，不调用 LLM）。
  */
 
 import type {
@@ -15,7 +10,6 @@ import type {
   TraceSummary,
 } from '../types/trace';
 import type { Diagnosis } from '../types/monitoring-types';
-import type { LLMAdapter } from '../llm/types';
 import { DIAGNOSIS_RULES } from './diagnosis-rules';
 
 // 类型定义已归位 types 层（工单 14），此处再导出保持模块公开面不变
@@ -54,9 +48,8 @@ export interface ConstraintDoctorConfig {
 export class ConstraintDoctor {
   private config: ConstraintDoctorConfig;
   private traces: ExecutionTrace[];
-  private llm: LLMAdapter | null;
 
-  constructor(config?: ConstraintDoctorConfig, llm?: LLMAdapter) {
+  constructor(config?: ConstraintDoctorConfig) {
     this.config = {
       enabled: false,
       maxTracesInPrompt: 20,
@@ -64,7 +57,6 @@ export class ConstraintDoctor {
       ...config,
     };
     this.traces = [];
-    this.llm = llm || null;
   }
 
   /**
@@ -83,20 +75,8 @@ export class ConstraintDoctor {
     // 过滤相关 traces
     const relevantTraces = this.filterRelevantTraces(anomaly);
 
-    // 基于规则的初步诊断（不消耗 Token）
-    const ruleBasedDiagnosis = this.ruleBasedDiagnose(anomaly, relevantTraces);
-
-    // 如果 LLM 可用，进行深度分析
-    if (this.config.enabled && this.llm) {
-      try {
-        return await this.agentDiagnose(anomaly, relevantTraces, ruleBasedDiagnosis);
-      } catch {
-        // LLM 调用失败，降级到规则诊断
-        return ruleBasedDiagnosis;
-      }
-    }
-
-    return ruleBasedDiagnosis;
+    // 基于规则的诊断（不消耗 Token）
+    return this.ruleBasedDiagnose(anomaly, relevantTraces);
   }
 
   /**
@@ -147,85 +127,6 @@ export class ConstraintDoctor {
     return diagnosis;
   }
 
-  /**
-   * LLM 深度诊断
-   *
-   * 将异常和相关 traces 构造为 prompt，调用 LLM 分析根因
-   * 成本：~2000 Token/次
-   */
-  private async agentDiagnose(
-    anomaly: TraceAnomaly,
-    traces: ExecutionTrace[],
-    fallback: Diagnosis
-  ): Promise<Diagnosis> {
-    const maxTraces = this.config.maxTracesInPrompt || 20;
-    const traceSummary = traces.slice(0, maxTraces).map(t =>
-      `[${t.result}] ${t.constraintId} | ${t.operation || 'unknown'} | ${t.timestamp ? new Date(t.timestamp).toISOString() : 'no-ts'}`
-    ).join('\n');
-
-    const prompt = `你是约束系统诊断专家。分析以下异常并给出诊断结果。
-
-## 异常信息
-- 约束 ID: ${anomaly.constraintId}
-- 异常类型: ${anomaly.type}
-- 约束层级: ${anomaly.level}
-- 当前数据: ${JSON.stringify(anomaly.data)}
-
-## 相关 Traces（最近 ${Math.min(traces.length, maxTraces)} 条）
-${traceSummary || '无相关 traces'}
-
-## 要求
-以 JSON 格式返回诊断结果，包含以下字段：
-{
-  "rootCause": { "primary": "主要原因", "secondary": ["次要原因1", "次要原因2"] },
-  "impact": { "severity": "low|medium|high", "scope": "single_project|multiple_projects|team", "userImpact": "用户影响描述" },
-  "recommendations": [{ "type": "add_exception|adjust_threshold|modify_constraint|user_training", "content": "建议内容", "expectedOutcome": "预期效果", "implementationCost": "low|medium|high" }],
-  "needsChange": true/false,
-  "urgency": "low|medium|high"
-}
-
-只返回 JSON，不要其他内容。`;
-
-    const response = await this.llm!.complete(prompt, {
-      maxTokens: 1000,
-      temperature: 0.3,
-    });
-
-    // 解析 LLM 响应
-    const parsed = this.parseAgentResponse(response);
-
-    return {
-      ...fallback,
-      rootCause: {
-        primary: parsed.rootCause?.primary || fallback.rootCause.primary,
-        secondary: parsed.rootCause?.secondary || fallback.rootCause.secondary,
-        evidence: fallback.rootCause.evidence,
-      },
-      impact: {
-        severity: parsed.impact?.severity || fallback.impact.severity,
-        scope: parsed.impact?.scope || fallback.impact.scope,
-        userImpact: parsed.impact?.userImpact || fallback.impact.userImpact,
-      },
-      recommendations: parsed.recommendations?.length ? parsed.recommendations : fallback.recommendations,
-      needsChange: parsed.needsChange ?? fallback.needsChange,
-      urgency: parsed.urgency || fallback.urgency,
-    };
-  }
-
-  /**
-   * 解析 LLM 返回的 JSON 诊断结果
-   */
-  private parseAgentResponse(response: string): Partial<Diagnosis> {
-    try {
-      // 提取 JSON（可能被 markdown 代码块包裹）
-      const jsonMatch = response.match(/\{[\s\S]*\}/);
-      if (!jsonMatch) return {};
-      return JSON.parse(jsonMatch[0]);
-    } catch {
-      return {};
-    }
-  }
-
   /**
    * 过滤相关 traces
    *
@@ -333,6 +234,6 @@ ${traceSummary || '无相关 traces'}
 /**
  * 创建诊断器
  */
-export function createDoctor(config?: ConstraintDoctorConfig, llm?: LLMAdapter): ConstraintDoctor {
-  return new ConstraintDoctor(config, llm);
+export function createDoctor(config?: ConstraintDoctorConfig): ConstraintDoctor {
+  return new ConstraintDoctor(config);
 }

package/src/presets/__tests__/standard.test.ts

@@ -48,7 +48,6 @@ describe('applyPreset with string preset names', () => {
     const config = applyPreset('relaxed');
     expect(config.ironLaws).toBeDefined();
     expect(config.ironLaws.no_completion_without_verification).toBeDefined();
-    expect(Object.keys(config.tips).length).toBe(0);
     expect(Object.keys(config.prompts ?? {}).length).toBe(0);
     expect(config.disabled.length).toBeGreaterThan(0);
   });
@@ -75,7 +74,6 @@ describe('applyPreset with PresetConfig object', () => {
       prompts: [],
     });
     expect(Object.keys(config.guidelines).length).toBeGreaterThan(0);
-    expect(Object.keys(config.tips).length).toBe(0);
     expect(Object.keys(config.prompts ?? {}).length).toBe(0);
   });
 

package/src/presets/standard.ts

@@ -3,7 +3,7 @@
  *
  * 预设定义哪些约束被启用
  *
- * ADR-0001：tips 维度退役，替换为 prompts（纯注入层）。
+ * ADR-0001：kind 二元（check + prompt 纯注入层）。
  */
 
 import type { Constraint } from '../types/constraint';
@@ -79,7 +79,6 @@ export function applyPreset(
   return {
     ironLaws: filterByIds(IRON_LAWS, cfg.ironLaws),
     guidelines: filterByIds(GUIDELINES, cfg.guidelines),
-    tips: {},
     prompts: filterByIds(PROMPTS, cfg.prompts),
     disabled,
     custom: [],

package/src/pretool-use-hook.ts

@@ -0,0 +1,68 @@
+/**
+ * PreToolUse 执法脚本 — command-gate hook 固化版（studio#153）
+ *
+ * 内容 = studio-agent provider-hooks.buildHookScriptContent 生成脚本（#147）的固化版，
+ * 归属归位：谁的东西谁发货——CommandGate 是 harness 的，hook 脚本随 harness 包出厂。
+ * 编译产物 = 包内 dist/pretool-use-hook.js，provider hook 配置（codex hooks.json /
+ * kimi config.toml）直接指向 require.resolve('@dommaker/harness') 同目录的该文件，
+ * 不再由 studio-agent 按 worktree 生成、不再内嵌绝对路径。
+ *
+ * 语义（与生成版一致）：
+ * - stdin 收 provider PreToolUse JSON（tool_input.command）；
+ * - CommandGate.isAllowed 判定 block 级黑名单，命中 → stderr 写原因 + exit 2
+ *   （codex/kimi 阻断语义：exit 2 + stderr 阻断，其余 exit code fail-open）；
+ * - fail-open：stdin 非 JSON / 缺字段 / CommandGate 异常一律放行——宁可漏拦
+ *   也不全体 Bash 秒断，拦截层只是纵深防御的一道；
+ * - warn/audit 级命中同样放行（isAllowed 只看 block 级），与生成版行为一致。
+ */
+import { CommandGate } from './gates/command';
+
+/** hook 标识：与 studio-agent 生成版同一 marker（配置幂等检测共用口径） */
+export const HOOK_MARKER = 'harness-command-gate';
+
+interface PreToolUseInput {
+  tool_input?: { command?: string };
+}
+
+/**
+ * 判定一次 PreToolUse 是否放行。
+ * block 级命中 → allowed=false；warn/audit/干净命令/坏输入一律 allowed=true。
+ */
+export function decidePreToolUse(rawStdin: string): { allowed: boolean; command: string } {
+  let input: PreToolUseInput = {};
+  try {
+    input = JSON.parse(rawStdin || '{}') as PreToolUseInput;
+  } catch {
+    // 非 JSON stdin：放行
+  }
+  const command = (input.tool_input && input.tool_input.command) || '';
+  try {
+    const gate = new CommandGate();
+    return { allowed: gate.isAllowed(command), command };
+  } catch {
+    // CommandGate 加载/判定异常：fail-open
+    return { allowed: true, command };
+  }
+}
+
+/**
+ * 执行一次 hook：返回进程 exit code（2 = 阻断，0 = 放行）。
+ * 阻断时原因写 stderr（provider 把 stderr 作为阻断原因回填模型）。
+ */
+export function runPreToolUseHook(rawStdin: string): number {
+  const { allowed, command } = decidePreToolUse(rawStdin);
+  if (!allowed) {
+    console.error(`[${HOOK_MARKER}] blocked: ${command}`);
+    return 2;
+  }
+  return 0;
+}
+
+/* istanbul ignore next -- 进程入口仅做 stdin 收集 + exit，逻辑由 runPreToolUseHook 单测覆盖 */
+if (require.main === module) {
+  let raw = '';
+  process.stdin.on('data', (c) => { raw += c; });
+  process.stdin.on('end', () => {
+    process.exit(runPreToolUseHook(raw));
+  });
+}

package/src/spec/__tests__/annotation-checker.test.ts

@@ -163,12 +163,18 @@ export function noSpecFunc() {}
     });
 
     it('应该跳过 node_modules 和 dist', () => {
-      mockFs.readdirSync.mockReturnValue(['src'] as any);
+      mockFs.readFileSync.mockReturnValue('');
+      mockFs.readdirSync.mockReturnValue([
+        { name: 'node_modules', isDirectory: () => true, isFile: () => false },
+        { name: 'dist', isDirectory: () => true, isFile: () => false },
+        { name: 'file.ts', isDirectory: () => false, isFile: () => true },
+      ] as any);
 
       const results = checkDirectory(tempDir);
 
-      // 应该跳过 node_modules 和 dist
-      expect(Array.isArray(results)).toBe(true);
+      // 只收集 file.ts，跳过 node_modules 与 dist 目录
+      expect(results).toHaveLength(1);
+      expect(results[0].file).toBe('/test/project/file.ts');
     });
 
     it('应该处理空目录', () => {

package/src/spec/annotation-checker.ts

@@ -4,8 +4,9 @@
  * 检查代码中的 @spec 注释是否规范
  */
 
-import { readFileSync, readdirSync, statSync } from 'fs';
+import { readFileSync } from 'fs';
 import * as path from 'path';
+import { walkFiles } from '../utils/file-walk';
 
 export interface AnnotationCheckResult {
   valid: boolean;
@@ -248,36 +249,13 @@ function checkPublicExports(content: string, result: AnnotationCheckResult): voi
 }
 
 /**
- * 递归获取目录下所有文件
+ * 递归获取目录下所有文件（收敛到 utils/file-walk 的 walkFiles，工单 O3）
  */
 function getFilesRecursively(dir: string, extensions: string[]): string[] {
-  const files: string[] = [];
-  
-  try {
-    const items = readdirSync(dir);
-    
-    for (const item of items) {
-      const fullPath = path.join(dir, item);
-      const stat = statSync(fullPath);
-      
-      if (stat.isDirectory()) {
-        // 跳过 node_modules 和 dist
-        if (item === 'node_modules' || item === 'dist') {
-          continue;
-        }
-        files.push(...getFilesRecursively(fullPath, extensions));
-      } else if (stat.isFile()) {
-        const ext = path.extname(item);
-        if (extensions.includes(ext) && !item.endsWith('.d.ts')) {
-          files.push(fullPath);
-        }
-      }
-    }
-  } catch {
-    // 目录不存在或无法访问
-  }
-  
-  return files;
+  return walkFiles(dir, {
+    skipDirs: ['node_modules', 'dist'],
+    filter: (name) => extensions.includes(path.extname(name)) && !name.endsWith('.d.ts'),
+  });
 }
 
 /**

package/src/tools/CONTEXT.md

@@ -1,25 +1,18 @@
 # tools/
 
 ## 职责
-工具管理：工具类型定义、注册表、核心工具实现、加载器、路径管理。
+工具定义目录与路径管理：bundled 工具定义目录（`definitions/`，113 个 yml 能力目录）与路径解析。
 
 ## 核心导出
-- `types.ts` — 工具类型定义
-- `registry.ts` — 工具注册表
-- `core.ts` — 核心工具实现
-- `loader.ts` — 工具加载器
-- `paths.ts` — 工具路径管理
+- `paths.ts` — 工具路径管理（`getToolsDir` / `getRegistryPath`）
 
 ## 依赖关系
-- 依赖 `src/types/` 公共类型
-- 被 `src/safety/tool-guardrail.ts` 消费
-- 被 Agent 工具调用管线消费
+- 仅依赖 Node 内置 `path`
+- 被 studio 消费（`getRegistryPath` / `getToolsDir`，`capabilities/routes.ts`、`capability.service.ts`）
 
 ## 约定
-- 工具通过注册表统一管理
-- 工具路径由 paths 模块解析
-- loader 支持动态加载外部工具
+- 工具定义目录路径由 paths 模块解析
+- `definitions/` 为静态能力目录，构建时复制到 dist
 
 ## 注意事项
-- 工具注册表与 ToolGuardrail 配合使用
-- 路径管理支持多项目工具目录
+- 旧工具注册表/核心工具/加载器/类型定义已随 H1（#40）删除，仅保留路径管理与能力目录

package/src/tools/index.ts

@@ -1,5 +1 @@
-export * from './types';
-export * from './registry';
-export * from './core';
-export * from './loader';
 export * from './paths';

package/src/types/constraint.ts

@@ -6,9 +6,6 @@
  *   - iron_law：绝对禁止，无例外，违背即阻止执行
  *   - guideline：优先建议，有例外，违背发警告但不阻止
  * - prompt：纯文本提示，仅参与 prompt 注入，不占检查位、不产生 trace
- *
- * 'tip' 层级已随 TIPS 退役（ADR-0001），仅保留在类型上以兼容
- * ConstraintCheckResult.tips 等历史结果形态，不再有新定义使用。
  */
 
 /**
@@ -25,9 +22,8 @@ export type ConstraintKind = 'check' | 'prompt';
  * 约束层级
  *
  * check 层只使用 'iron_law' | 'guideline'；prompt 类统一为 'prompt'。
- * 'tip' 已退役，仅为历史结果结构兼容保留。
  */
-export type ConstraintLevel = 'iron_law' | 'guideline' | 'prompt' | 'tip';
+export type ConstraintLevel = 'iron_law' | 'guideline' | 'prompt';
 
 /**
  * 约束触发条件（开放扩展）
@@ -281,9 +277,6 @@ export class ConstraintViolationError extends Error {
 
 /**
  * 约束检查结果（check 层）
- *
- * tips/tipCount 已随 TIPS 退役（ADR-0001），保留字段以兼容历史调用方，
- * 内置约束下恒为空数组 / 0。
  */
 export interface ConstraintCheckResult {
   /** 铁律检查结果（必须全部通过） */
@@ -292,17 +285,11 @@ export interface ConstraintCheckResult {
   /** 指导原则检查结果（警告，不阻止） */
   guidelines: ConstraintResult[];
   
-  /** 提示检查结果（仅提示） */
-  tips: ConstraintResult[];
-  
   /** 是否通过（铁律全部通过） */
   passed: boolean;
   
   /** 警告数量 */
   warningCount: number;
-  
-  /** 提示数量 */
-  tipCount: number;
 }
 
 /**

package/src/types/project-config.ts

@@ -285,9 +285,6 @@ export interface MergedConstraintsConfig {
   /** Guidelines（合并后） */
   guidelines: Record<string, Constraint>;
 
-  /** Tips（合并后）—— 已退役（ADR-0001），内置侧恒为空表，仅兼容历史调用方 */
-  tips: Record<string, Constraint>;
-
   /** Prompts（合并后，ADR-0001 新增；可选以兼容旧调用方，缺省回落内置 PROMPTS） */
   prompts?: Record<string, Constraint>;
 

package/src/utils/file-walk.ts

@@ -1,8 +1,8 @@
 /**
  * 文件遍历工具（工单 19）
  *
- * 收敛此前散落在 sync-docs / cross-project-checker / checker /
- * spec-baseline-check / doc-freshness-check 中的 5 处递归遍历实现。
+ * 收敛此前散落在 sync-docs / checker / spec-baseline-check /
+ * doc-freshness-check / spec/annotation-checker 中的递归遍历实现。
  */
 
 import * as fs from 'fs';

package/dist/architecture/constraint-engine.d.ts

@@ -1,67 +0,0 @@
-/**
- * 架构约束引擎
- *
- * 通用能力：加载规则、执行检查、生成报告
- * 规则定义：由项目提供（.architect/rules.yml）
- */
-export interface ArchitectureContext {
-    files: string[];
-    diff: string;
-    pr?: {
-        number: number;
-        changedFiles: number;
-        additions: number;
-        deletions: number;
-    };
-}
-export interface ArchitectureViolation {
-    ruleId: string;
-    message: string;
-    files?: string[];
-    severity: 'error' | 'warning';
-}
-export interface ArchitectureResult {
-    passed: boolean;
-    violations: ArchitectureViolation[];
-}
-export interface ModuleBoundary {
-    /** 源文件 glob 模式 */
-    from: string;
-    /** 禁止导入的目标 glob 模式 */
-    denyImport: string;
-}
-export interface ArchitectureRule {
-    id: string;
-    type: 'forbidden-pattern' | 'file-count' | 'module-boundary' | 'custom';
-    severity?: 'error' | 'warning';
-    scope?: string;
-    message?: string;
-    patterns?: string[];
-    threshold?: number;
-    boundaries?: ModuleBoundary[];
-    script?: string;
-}
-export declare class ArchitectureConstraintEngine {
-    private rules;
-    constructor(rules: ArchitectureRule[]);
-    check(context: ArchitectureContext): Promise<ArchitectureResult>;
-    private checkRule;
-    private checkForbiddenPattern;
-    private checkFileCount;
-    private checkModuleBoundary;
-    /**
-     * 从 diff 中提取每个文件新增的 import 路径
-     * 只解析 + 开头的行（新增内容）
-     */
-    private extractImportsFromDiff;
-    /**
-     * 解析 import 路径为相对于项目根的路径
-     * 相对路径: ./foo, ../bar → 基于导入文件解析
-     * 非相对路径: @scope/foo → 返回 null（外部依赖）
-     */
-    private resolveImport;
-    private matchGlob;
-}
-export declare function loadArchitectureRules(configPath: string): Promise<ArchitectureRule[]>;
-export declare function runArchitectureCheck(configPath: string, context: ArchitectureContext): Promise<ArchitectureResult>;
-//# sourceMappingURL=constraint-engine.d.ts.map

package/dist/architecture/constraint-engine.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"constraint-engine.d.ts","sourceRoot":"","sources":["../../src/architecture/constraint-engine.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,CAAC,EAAE;QACH,MAAM,EAAE,MAAM,CAAC;QACf,YAAY,EAAE,MAAM,CAAC;QACrB,SAAS,EAAE,MAAM,CAAC;QAClB,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;CACH;AAED,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAC;CAC/B;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,OAAO,CAAC;IAChB,UAAU,EAAE,qBAAqB,EAAE,CAAC;CACrC;AAED,MAAM,WAAW,cAAc;IAC7B,kBAAkB;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,sBAAsB;IACtB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,mBAAmB,GAAG,YAAY,GAAG,iBAAiB,GAAG,QAAQ,CAAC;IACxE,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAE/B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IAEpB,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,UAAU,CAAC,EAAE,cAAc,EAAE,CAAC;IAE9B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,qBAAa,4BAA4B;IAC3B,OAAO,CAAC,KAAK;gBAAL,KAAK,EAAE,gBAAgB,EAAE;IAEvC,KAAK,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,kBAAkB,CAAC;YAcxD,SAAS;IAgBvB,OAAO,CAAC,qBAAqB;IA6B7B,OAAO,CAAC,cAAc;IAkBtB,OAAO,CAAC,mBAAmB;IAiC3B;;;OAGG;IACH,OAAO,CAAC,sBAAsB;IAoC9B;;;;OAIG;IACH,OAAO,CAAC,aAAa;IAoBrB,OAAO,CAAC,SAAS;CA+BlB;AAGD,wBAAsB,qBAAqB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAgB3F;AA4DD,wBAAsB,oBAAoB,CACxC,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,kBAAkB,CAAC,CAI7B"}