@dommaker/harness 0.18.0 → 0.19.0

package/src/core/constraints/__tests__/agent-prompt-renderer.test.ts

@@ -0,0 +1,129 @@
+/**
+ * trigger 参数化约束分组渲染 API 测试（H6/G6，收编 studio prompt-injection.ts）
+ *
+ * 语义：
+ * - 入参 = 触发条件（单 trigger 或数组），无 role 概念（role→trigger 路由留 studio）
+ * - 数据源 = getEffectiveConstraints（内置 → preset → config.yml 禁用 → custom 追加 → scenes 过滤）
+ * - 输出按层级分组：铁律 → 指导原则 → 行为提示；无 promptInjection 的约束不渲染
+ */
+
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { renderConstraintsByTrigger } from '../agent-prompt-renderer';
+import { renderConstraintsByTrigger as PublicRenderConstraintsByTrigger } from '../../../index';
+
+describe('公开导出（根 barrel）', () => {
+  test('renderConstraintsByTrigger 经 src/index.ts 公开导出', () => {
+    expect(PublicRenderConstraintsByTrigger).toBe(renderConstraintsByTrigger);
+  });
+});
+
+/** 创建临时项目目录，可按相对路径写入 .harness/config.yml 等夹具文件 */
+function makeProject(files: Record<string, string>): string {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'h6-render-'));
+  for (const [rel, content] of Object.entries(files)) {
+    const target = path.join(dir, rel);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.writeFileSync(target, content, 'utf-8');
+  }
+  return dir;
+}
+
+describe('renderConstraintsByTrigger', () => {
+  test('内置约束按层级分组渲染：铁律 → 指导原则 → 行为提示', () => {
+    const projectRoot = makeProject({});
+    const out = renderConstraintsByTrigger('code_implementation', { projectRoot });
+
+    expect(out).toContain('## 行为约束（前置声明）');
+    expect(out).toContain('### 铁律（绝对禁止，无例外）');
+    expect(out).toContain('- **no_completion_without_verification**:');
+    expect(out).toContain('### 指导原则（优先建议）');
+    expect(out).toContain('- **no_hardcoded_credentials**:');
+    expect(out).toContain('### 行为提示');
+    expect(out).toContain('- **no_code_without_test**:');
+
+    // 分组顺序：铁律 < 指导原则 < 行为提示
+    const ironIdx = out.indexOf('### 铁律（绝对禁止，无例外）');
+    const guideIdx = out.indexOf('### 指导原则（优先建议）');
+    const promptIdx = out.indexOf('### 行为提示');
+    expect(ironIdx).toBeGreaterThanOrEqual(0);
+    expect(guideIdx).toBeGreaterThan(ironIdx);
+    expect(promptIdx).toBeGreaterThan(guideIdx);
+  });
+
+  test('无 promptInjection 的约束不渲染（即使 trigger 匹配）', () => {
+    const projectRoot = makeProject({});
+    // docs_freshness / capability_sync / context_doc_sync 无 promptInjection
+    const out = renderConstraintsByTrigger('module_modification', { projectRoot });
+
+    expect(out).not.toContain('- **docs_freshness**:');
+    expect(out).not.toContain('- **capability_sync**:');
+    expect(out).not.toContain('- **context_doc_sync**:');
+  });
+
+  test('支持 trigger 数组入参，仅匹配交集约束', () => {
+    const projectRoot = makeProject({});
+    const out = renderConstraintsByTrigger(['test_creation'], { projectRoot });
+
+    expect(out).toContain('- **no_test_simplification**:');
+    // no_completion_without_verification 的 trigger 为 code_implementation，不匹配
+    expect(out).not.toContain('- **no_completion_without_verification**:');
+  });
+
+  test('无匹配约束返回空字符串', () => {
+    const projectRoot = makeProject({});
+    expect(renderConstraintsByTrigger('nonexistent_trigger_xyz', { projectRoot })).toBe('');
+    expect(renderConstraintsByTrigger([], { projectRoot })).toBe('');
+  });
+
+  test('config.yml 禁用的约束不进入渲染（生效集数据源）', () => {
+    const projectRoot = makeProject({
+      '.harness/config.yml': [
+        'constraints:',
+        '  no_hardcoded_credentials:',
+        '    enabled: false',
+        '',
+      ].join('\n'),
+    });
+    const out = renderConstraintsByTrigger('code_implementation', { projectRoot });
+
+    expect(out).not.toContain('- **no_hardcoded_credentials**:');
+    // 同 trigger 的其它约束仍渲染
+    expect(out).toContain('- **no_completion_without_verification**:');
+  });
+
+  test('custom 约束追加进生效集并参与分组渲染', () => {
+    const projectRoot = makeProject({
+      '.harness/config.yml': [
+        'custom_constraints:',
+        '  my_custom_rule:',
+        '    level: prompt',
+        '    trigger: code_implementation',
+        '    rule: CUSTOM RULE',
+        '    message: 自定义约束消息',
+        '    promptInjection: 自定义行为提示文本',
+        '',
+      ].join('\n'),
+    });
+    const out = renderConstraintsByTrigger('code_implementation', { projectRoot });
+
+    expect(out).toContain('- **my_custom_rule**: 自定义行为提示文本');
+    const promptIdx = out.indexOf('### 行为提示');
+    const customIdx = out.indexOf('- **my_custom_rule**:');
+    expect(customIdx).toBeGreaterThan(promptIdx);
+  });
+
+  test('scenes 过滤：带 appliesTo 的场景专属 prompt 默认不渲染，声明场景后渲染', () => {
+    // no_skill_without_test：appliesTo ['agent-skill']，trigger module_creation
+    const plain = makeProject({});
+    expect(renderConstraintsByTrigger('module_creation', { projectRoot: plain }))
+      .not.toContain('- **no_skill_without_test**:');
+
+    const withScene = makeProject({
+      '.harness/config.yml': 'scenes:\n  - agent-skill\n',
+    });
+    expect(renderConstraintsByTrigger('module_creation', { projectRoot: withScene }))
+      .toContain('- **no_skill_without_test**:');
+  });
+});

package/src/core/constraints/__tests__/check-cache.test.ts

@@ -0,0 +1,227 @@
+/**
+ * CheckCache 测试（H6/G5：TTL 缓存既有行为 + 计数采样扩展）
+ *
+ * 计数采样语义（与 studio runtime/cache.ts 收编对齐）：
+ * - 每个 (namespace, key) 独立计数
+ * - 第 1 次调用必执行（采样轮），此后每 N 次执行 1 次
+ * - 非采样轮：缓存命中（未过期）返回缓存值；未命中/已过期返回 defaultValueOnMiss，不执行 fn
+ */
+
+import { CheckCache } from '../check-cache';
+import { CheckCache as PublicCheckCache } from '../../../index';
+
+describe('公开导出（根 barrel）', () => {
+  test('CheckCache 经 src/index.ts 公开导出', () => {
+    expect(PublicCheckCache).toBe(CheckCache);
+  });
+});
+
+describe('CheckCache', () => {
+  beforeEach(() => {
+    jest.useFakeTimers();
+    jest.setSystemTime(new Date('2026-01-01T00:00:00.000Z'));
+  });
+
+  afterEach(() => {
+    jest.useRealTimers();
+  });
+
+  describe('TTL 缓存（既有行为，不传 sampling 参数）', () => {
+    test('缓存命中不重复执行 fn，过期后重新执行', async () => {
+      const cache = new CheckCache({ ttlMs: 1000 });
+      const fn = jest.fn(async () => 'v1');
+
+      expect(await cache.get('ns', 'k', fn)).toBe('v1');
+      expect(await cache.get('ns', 'k', fn)).toBe('v1');
+      expect(fn).toHaveBeenCalledTimes(1);
+
+      jest.advanceTimersByTime(1001);
+      expect(await cache.get('ns', 'k', fn)).toBe('v1');
+      expect(fn).toHaveBeenCalledTimes(2);
+    });
+
+    test('getSync 命中/过期行为一致', () => {
+      const cache = new CheckCache({ ttlMs: 1000 });
+      const fn = jest.fn(() => 'sync');
+
+      expect(cache.getSync('ns', 'k', fn)).toBe('sync');
+      expect(cache.getSync('ns', 'k', fn)).toBe('sync');
+      expect(fn).toHaveBeenCalledTimes(1);
+
+      jest.advanceTimersByTime(1001);
+      expect(cache.getSync('ns', 'k', fn)).toBe('sync');
+      expect(fn).toHaveBeenCalledTimes(2);
+    });
+
+    test('缺省构造使用默认 TTL 5000ms', async () => {
+      const cache = new CheckCache();
+      const fn = jest.fn(async () => 'v');
+
+      await cache.get('ns', 'k', fn);
+      jest.advanceTimersByTime(4999);
+      await cache.get('ns', 'k', fn);
+      expect(fn).toHaveBeenCalledTimes(1);
+
+      jest.advanceTimersByTime(2); // 累计 5001ms，已过期
+      await cache.get('ns', 'k', fn);
+      expect(fn).toHaveBeenCalledTimes(2);
+    });
+
+    test('命名空间隔离：不同 namespace 相同 key 互不影响', async () => {
+      const cache = new CheckCache({ ttlMs: 1000 });
+      const f1 = jest.fn(async () => 'a');
+      const f2 = jest.fn(async () => 'b');
+
+      expect(await cache.get('ns1', 'k', f1)).toBe('a');
+      expect(await cache.get('ns2', 'k', f2)).toBe('b');
+      expect(f1).toHaveBeenCalledTimes(1);
+      expect(f2).toHaveBeenCalledTimes(1);
+    });
+
+    test('invalidate(namespace) 仅清除指定命名空间', async () => {
+      const cache = new CheckCache({ ttlMs: 1000 });
+      const f1 = jest.fn(async () => 'a');
+      const f2 = jest.fn(async () => 'b');
+
+      await cache.get('ns1', 'k', f1);
+      await cache.get('ns2', 'k', f2);
+      cache.invalidate('ns1');
+
+      expect(await cache.get('ns1', 'k', f1)).toBe('a');
+      expect(await cache.get('ns2', 'k', f2)).toBe('b');
+      expect(f1).toHaveBeenCalledTimes(2);
+      expect(f2).toHaveBeenCalledTimes(1);
+    });
+
+    test('invalidate() 清除全部缓存', async () => {
+      const cache = new CheckCache({ ttlMs: 1000 });
+      const fn = jest.fn(async () => 'v');
+
+      await cache.get('ns', 'k1', fn);
+      await cache.get('ns', 'k2', fn);
+      cache.invalidate();
+
+      await cache.get('ns', 'k1', fn);
+      await cache.get('ns', 'k2', fn);
+      expect(fn).toHaveBeenCalledTimes(4);
+    });
+  });
+
+  describe('计数采样（声明式配置）', () => {
+    test('第 1 次调用必执行，此后每 N 次执行 1 次，其余复用缓存结果', async () => {
+      const cache = new CheckCache({ ttlMs: 60_000 });
+      let runs = 0;
+      const fn = jest.fn(async () => `run-${++runs}`);
+      const sampling = { sampleRate: 3, defaultValueOnMiss: 'skip' };
+
+      // 第 1 次：采样轮 → 执行
+      expect(await cache.get('ns', 'k', fn, sampling)).toBe('run-1');
+      // 第 2、3 次：非采样轮 → 复用缓存
+      expect(await cache.get('ns', 'k', fn, sampling)).toBe('run-1');
+      expect(await cache.get('ns', 'k', fn, sampling)).toBe('run-1');
+      expect(fn).toHaveBeenCalledTimes(1);
+      // 第 4 次：采样轮 → 执行
+      expect(await cache.get('ns', 'k', fn, sampling)).toBe('run-2');
+      expect(fn).toHaveBeenCalledTimes(2);
+    });
+
+    test('非采样轮缓存已过期：返回 defaultValueOnMiss，不执行 fn', async () => {
+      const cache = new CheckCache({ ttlMs: 1000 });
+      const fn = jest.fn(async () => 'fresh');
+      const sampling = { sampleRate: 3, defaultValueOnMiss: 'skip' };
+
+      expect(await cache.get('ns', 'k', fn, sampling)).toBe('fresh'); // 采样轮，TTL=1s 缓存
+      jest.advanceTimersByTime(1001);
+
+      expect(await cache.get('ns', 'k', fn, sampling)).toBe('skip'); // 过期 + 非采样轮
+      expect(await cache.get('ns', 'k', fn, sampling)).toBe('skip');
+      expect(fn).toHaveBeenCalledTimes(1);
+
+      // 第 4 次：采样轮 → 重新执行
+      expect(await cache.get('ns', 'k', fn, sampling)).toBe('fresh');
+      expect(fn).toHaveBeenCalledTimes(2);
+    });
+
+    test('采样计数器按 key 独立', async () => {
+      const cache = new CheckCache({ ttlMs: 60_000 });
+      const f1 = jest.fn(async () => 'a');
+      const f2 = jest.fn(async () => 'b');
+      const sampling = { sampleRate: 3, defaultValueOnMiss: 'x' };
+
+      await cache.get('ns', 'k1', f1, sampling);
+      await cache.get('ns', 'k2', f2, sampling);
+      expect(f1).toHaveBeenCalledTimes(1);
+      expect(f2).toHaveBeenCalledTimes(1);
+
+      await cache.get('ns', 'k1', f1, sampling); // k1 非采样轮
+      expect(f1).toHaveBeenCalledTimes(1);
+    });
+
+    test('invalidate 重置计数器：失效后下一次调用恢复为采样轮', async () => {
+      const cache = new CheckCache({ ttlMs: 60_000 });
+      const fn = jest.fn(async () => 'v');
+      const sampling = { sampleRate: 3, defaultValueOnMiss: 'd' };
+
+      await cache.get('ns', 'k', fn, sampling); // count=1 采样
+      await cache.get('ns', 'k', fn, sampling); // count=2 跳过
+      cache.invalidate('ns');
+      await cache.get('ns', 'k', fn, sampling); // 重置后 count=1 采样
+      expect(fn).toHaveBeenCalledTimes(2);
+    });
+
+    test('invalidate() 全量同样重置计数器', async () => {
+      const cache = new CheckCache({ ttlMs: 60_000 });
+      const fn = jest.fn(async () => 'v');
+      const sampling = { sampleRate: 2, defaultValueOnMiss: 'd' };
+
+      await cache.get('ns', 'k', fn, sampling); // count=1 采样
+      cache.invalidate();
+      await cache.get('ns', 'k', fn, sampling); // 重置后 count=1 采样
+      expect(fn).toHaveBeenCalledTimes(2);
+    });
+
+    test('sampleRate <= 1 视为不采样：回退为普通 TTL 缓存语义', async () => {
+      const cache = new CheckCache({ ttlMs: 60_000 });
+      const fn = jest.fn(async () => 'v');
+
+      await cache.get('ns', 'k', fn, { sampleRate: 1, defaultValueOnMiss: 'd' });
+      await cache.get('ns', 'k', fn, { sampleRate: 0, defaultValueOnMiss: 'd' });
+      expect(fn).toHaveBeenCalledTimes(1); // TTL 命中，无采样短路
+    });
+
+    test('getSync 同样支持计数采样', () => {
+      const cache = new CheckCache({ ttlMs: 60_000 });
+      const fn = jest.fn(() => 'sync');
+      const sampling = { sampleRate: 3, defaultValueOnMiss: 'skip' };
+
+      expect(cache.getSync('ns', 'k', fn, sampling)).toBe('sync'); // 采样轮
+      expect(cache.getSync('ns', 'k', fn, sampling)).toBe('sync'); // 复用缓存
+      expect(cache.getSync('ns', 'k', fn, sampling)).toBe('sync'); // 复用缓存
+      expect(fn).toHaveBeenCalledTimes(1);
+    });
+
+    test('getSync 非采样轮缓存过期返回默认值', () => {
+      const cache = new CheckCache({ ttlMs: 1000 });
+      const fn = jest.fn(() => 'sync');
+      const sampling = { sampleRate: 3, defaultValueOnMiss: 'skip' };
+
+      expect(cache.getSync('ns', 'k', fn, sampling)).toBe('sync'); // 采样轮 @t0
+      jest.advanceTimersByTime(1001);
+      expect(cache.getSync('ns', 'k', fn, sampling)).toBe('skip'); // 过期 + 非采样轮
+      expect(fn).toHaveBeenCalledTimes(1);
+    });
+
+    test('采样轮执行结果以正常 TTL 写入缓存，非采样轮不刷新 TTL', async () => {
+      const cache = new CheckCache({ ttlMs: 1000 });
+      const fn = jest.fn(async () => 'v');
+      const sampling = { sampleRate: 3, defaultValueOnMiss: 'd' };
+
+      await cache.get('ns', 'k', fn, sampling); // 采样轮 @t0
+      jest.advanceTimersByTime(500);
+      await cache.get('ns', 'k', fn, sampling); // 非采样轮 @t0+500（不应刷新过期时间）
+      jest.advanceTimersByTime(600); // t0+1100：若 TTL 被刷新则仍命中
+      expect(await cache.get('ns', 'k', fn, sampling)).toBe('d'); // 已过期 → 默认值
+      expect(fn).toHaveBeenCalledTimes(1);
+    });
+  });
+});

package/src/core/constraints/agent-prompt-renderer.ts

@@ -0,0 +1,71 @@
+/**
+ * Agent prompt 约束段渲染（H6/G6：trigger 参数化分组渲染 API）
+ *
+ * 收编 studio prompt-injection.ts 的渲染层：role→trigger 路由留在 studio，
+ * 本模块只做 trigger 参数化 + 生效集过滤 + 层级分组渲染。
+ *
+ * 数据源 = getEffectiveConstraints（内置 → preset → config.yml 禁用 →
+ * custom 追加 → scenes 过滤），与 init 注入、harness check 同一来源。
+ *
+ * 输出按层级分组：铁律 → 指导原则 → 行为提示；无 promptInjection 的约束
+ * （如 docs_freshness）不渲染。tip 层级已随 TIPS 退役，不参与分组。
+ */
+
+import type { Constraint, ConstraintLevel, ConstraintTrigger } from '../../types/constraint';
+import { normalizeTriggers } from '../../utils/exec';
+import { getEffectiveConstraints } from '../effective-constraints';
+
+/**
+ * renderConstraintsByTrigger 选项
+ */
+export interface RenderConstraintsByTriggerOptions {
+  /** 项目根路径（决定 config.yml 生效集），缺省 process.cwd() */
+  projectRoot?: string;
+}
+
+/** 层级分组定义（渲染顺序即声明顺序） */
+const LEVEL_GROUPS: ReadonlyArray<{ level: ConstraintLevel; heading: string }> = [
+  { level: 'iron_law', heading: '### 铁律（绝对禁止，无例外）' },
+  { level: 'guideline', heading: '### 指导原则（优先建议）' },
+  { level: 'prompt', heading: '### 行为提示' },
+];
+
+/**
+ * 按触发条件渲染约束分组文本（注入 Agent system prompt 用）
+ *
+ * 过滤：生效集内 trigger 与入参存在交集的约束；无 promptInjection 的不渲染。
+ * 分组：按层级 iron_law → guideline → prompt 顺序渲染为标题 + 条目列表；
+ * 无适用约束时返回空字符串。
+ *
+ * @param triggers 触发条件（单个或多个；空数组返回空字符串）
+ * @param options.projectRoot 项目根路径（决定 config.yml 生效集）
+ */
+export function renderConstraintsByTrigger(
+  triggers: ConstraintTrigger | ConstraintTrigger[],
+  options?: RenderConstraintsByTriggerOptions,
+): string {
+  const requested = Array.isArray(triggers) ? triggers : [triggers];
+  if (requested.length === 0) return '';
+
+  const constraints = getEffectiveConstraints(options?.projectRoot);
+  const applicable = constraints.filter(
+    c => c.promptInjection && matchesTrigger(c, requested)
+  );
+  if (applicable.length === 0) return '';
+
+  const lines: string[] = ['\n## 行为约束（前置声明）\n'];
+  for (const group of LEVEL_GROUPS) {
+    const items = applicable.filter(c => c.level === group.level);
+    if (items.length === 0) continue;
+    lines.push(`${group.heading}\n`);
+    for (const c of items) {
+      lines.push(`- **${c.id}**: ${c.promptInjection}`);
+    }
+    lines.push('');
+  }
+  return lines.join('\n');
+}
+
+function matchesTrigger(constraint: Constraint, requested: ConstraintTrigger[]): boolean {
+  return normalizeTriggers<ConstraintTrigger>(constraint.trigger).some(t => requested.includes(t));
+}

package/src/core/constraints/check-cache.ts

@@ -4,10 +4,19 @@
  * 缓存 git diff 和 src/ 递归扫描结果，减少重复 I/O。
  * 同一请求内多次 checkConstraints 调用共享缓存。
  *
+ * 计数采样（H6/G5，收编 studio runtime/cache.ts）：
+ * get/getSync 可传声明式采样配置，对每个 (namespace, key) 独立计数，
+ * 第 1 次调用必执行，此后每 N 次执行 1 次完整检查，其余 N-1 次复用缓存；
+ * 非采样轮缓存未命中（无缓存或已过期）时返回 defaultValueOnMiss，不执行 fn。
+ * invalidate 同时重置对应计数，保证失效后下一次调用恢复为完整检查。
+ *
  * 用法：
  * ```typescript
  * const cache = new CheckCache({ ttlMs: 5000 });
+ * // 普通 TTL 缓存
  * const diff = await cache.get('git_diff', projectPath, () => runCommand('git diff --cached', projectPath));
+ * // 计数采样：每 3 次调用执行 1 次完整检查
+ * const ok = await cache.get('goal_check', key, check, { sampleRate: 3, defaultValueOnMiss: true });
  * ```
  */
 
@@ -16,13 +25,41 @@ interface CacheEntry {
   expiresAt: number;
 }
 
+/**
+ * CheckCache 构造配置
+ */
 export interface CheckCacheConfig {
   /** 缓存 TTL（毫秒），默认 5000 */
   ttlMs: number;
 }
 
+/**
+ * 计数采样配置（声明式）
+ *
+ * 传此配置后，对应 (namespace, key) 启用计数采样：
+ * - 第 1 次调用必执行 fn（采样轮），结果以正常 TTL 写入缓存；
+ * - 其后每 N 次调用执行 1 次（计数独立于普通缓存读写）；
+ * - 非采样轮：缓存命中（未过期）返回缓存值；未命中或已过期
+ *   返回 {@link defaultValueOnMiss}，不执行 fn、不刷新 TTL。
+ */
+export interface CheckSamplingConfig<T> {
+  /** 采样率：每 N 次调用执行 1 次完整检查；N <= 1 视为不采样（回退为普通 TTL 缓存语义） */
+  sampleRate: number;
+  /** 非采样轮且缓存未命中（无缓存或已过期）时的默认返回值 */
+  defaultValueOnMiss: T;
+}
+
+/**
+ * 约束检查缓存：TTL 缓存 + 可选计数采样
+ *
+ * 普通 get/getSync 为 TTL 缓存；传入 sampling 配置后对应 (namespace, key)
+ * 启用计数采样（每 N 次执行 1 次完整检查，其余轮次复用缓存或返回
+ * defaultValueOnMiss）。语义详见 {@link CheckSamplingConfig}。
+ */
 export class CheckCache {
   private store = new Map<string, CacheEntry>();
+  /** 采样计数器（仅启用采样的 key 有计数） */
+  private sampleCounters = new Map<string, number>();
   private ttlMs: number;
 
   constructor(config?: CheckCacheConfig) {
@@ -35,19 +72,28 @@ export class CheckCache {
    * @param namespace 命名空间（如 'git_diff', 'src_scan'）
    * @param key 缓存键（如 projectPath）
    * @param fn miss 时的计算函数
+   * @param sampling 计数采样配置（可选；不传时每次 miss 都执行 fn）
    */
   async get<T>(
     namespace: string,
     key: string,
     fn: () => Promise<T>,
+    sampling?: CheckSamplingConfig<T>,
   ): Promise<T> {
     const cacheKey = `${namespace}:${key}`;
     const entry = this.store.get(cacheKey);
+    const rate = sampling ? Math.max(1, Math.floor(sampling.sampleRate)) : 1;
+    // 采样轮优先于缓存命中：每 N 次调用必执行一次完整检查（第 1 次必执行）
+    const sampleTurn = rate > 1 && this.isSampleTurn(cacheKey, rate);
 
-    if (entry && Date.now() < entry.expiresAt) {
+    if (!sampleTurn && entry && Date.now() < entry.expiresAt) {
       return entry.value as T;
     }
 
+    if (sampling && rate > 1 && !sampleTurn) {
+      return sampling.defaultValueOnMiss;
+    }
+
     const value = await fn();
     this.store.set(cacheKey, {
       value,
@@ -58,19 +104,28 @@ export class CheckCache {
 
   /**
    * 同步版本（用于 readdirSync 等同步操作）
+   *
+   * @param sampling 计数采样配置（语义同 {@link get}）
    */
   getSync<T>(
     namespace: string,
     key: string,
     fn: () => T,
+    sampling?: CheckSamplingConfig<T>,
   ): T {
     const cacheKey = `${namespace}:${key}`;
     const entry = this.store.get(cacheKey);
+    const rate = sampling ? Math.max(1, Math.floor(sampling.sampleRate)) : 1;
+    const sampleTurn = rate > 1 && this.isSampleTurn(cacheKey, rate);
 
-    if (entry && Date.now() < entry.expiresAt) {
+    if (!sampleTurn && entry && Date.now() < entry.expiresAt) {
       return entry.value as T;
     }
 
+    if (sampling && rate > 1 && !sampleTurn) {
+      return sampling.defaultValueOnMiss;
+    }
+
     const value = fn();
     this.store.set(cacheKey, {
       value,
@@ -80,7 +135,8 @@ export class CheckCache {
   }
 
   /**
-   * 使指定命名空间缓存失效
+   * 使指定命名空间缓存失效（同时重置该命名空间的采样计数器，
+   * 保证失效后的下一次调用恢复为采样轮/完整检查）
    */
   invalidate(namespace?: string): void {
     if (namespace) {
@@ -89,8 +145,24 @@ export class CheckCache {
           this.store.delete(key);
         }
       }
+      for (const key of this.sampleCounters.keys()) {
+        if (key.startsWith(`${namespace}:`)) {
+          this.sampleCounters.delete(key);
+        }
+      }
     } else {
       this.store.clear();
+      this.sampleCounters.clear();
     }
   }
+
+  /**
+   * 计数采样判定：计数 +1 后返回是否采样轮（第 1 次必采样，每 N 次 1 次）。
+   * 仅在采样启用（rate > 1）时调用。
+   */
+  private isSampleTurn(cacheKey: string, rate: number): boolean {
+    const count = (this.sampleCounters.get(cacheKey) ?? 0) + 1;
+    this.sampleCounters.set(cacheKey, count);
+    return count % rate === 1;
+  }
 }

package/src/core/constraints/index.ts

@@ -29,6 +29,16 @@ export {
   renderConstraintsSection,
 } from './injection-renderer';
 
+// 约束检查缓存（H6/G5：TTL 缓存 + 计数采样，公开导出）
+export { CheckCache } from './check-cache';
+export type { CheckCacheConfig, CheckSamplingConfig } from './check-cache';
+
+// Agent prompt 约束段渲染（H6/G6：trigger 参数化分组渲染，role 路由留 studio）
+export {
+  renderConstraintsByTrigger,
+} from './agent-prompt-renderer';
+export type { RenderConstraintsByTriggerOptions } from './agent-prompt-renderer';
+
 // 类型导出
 export type {
   ConstraintId,

package/src/index.ts

@@ -107,6 +107,14 @@ export * from './agents';
 // ========================================
 export * from './presets';
 
+// ========================================
+// 约束缓存与渲染导出（H6/G5-G6，#31 收编）
+// ========================================
+export { CheckCache } from './core/constraints/check-cache';
+export type { CheckCacheConfig, CheckSamplingConfig } from './core/constraints/check-cache';
+export { renderConstraintsByTrigger } from './core/constraints/agent-prompt-renderer';
+export type { RenderConstraintsByTriggerOptions } from './core/constraints/agent-prompt-renderer';
+
 // ========================================
 // 便捷 API
 // ========================================