@bolloon/bolloon-agent 0.1.0

package/src/bollharness/.boll/skills/context-chains/SKILL.md

@@ -0,0 +1,250 @@
+---
+name: context-chains
+description: 上下文 session 摘要链化系统。根据工作类型（code_change/review/design/question）将每次会话压缩为结构化摘要，存储在 `.boll/state/context-chains/` 中，新会话自动关联历史上下文。触发时机：每次会话结束 / Gate 0 进入时 / 显式请求"关联上下文"时使用。
+status: active
+tier: core
+owner: boll-system
+window_owner: shared
+last_audited: 2026-05-23
+triggers:
+  - 会话结束
+  - Gate 0 进入
+  - 显式请求"关联上下文"或"总结上次"
+  - 需要引用历史决策或上下文
+inject_gates:
+  - 0
+  - 3
+work_types:
+  - code_change
+  - review
+  - design
+  - question
+  - planning
+  - debugging
+---
+
+# Context Chains — 上下文会话摘要链化
+
+## 核心思想
+
+每次会话结束后，将本次对话的**核心上下文**压缩为一个 `context-summary.yaml` 文件，存入 `.boll/state/context-chains/`。新会话开始时，自动找到并注入相关的历史上下文链。
+
+**有限上下文长度 = 强制压缩点**。我们不做"保留一切"的徒劳努力，而是主动决定"什么必须保留、什么可以丢失"。
+
+## 工作类型与萃取策略
+
+| work_type | 保留内容 | 压缩比例 | 优先级 |
+|-----------|---------|---------|--------|
+| `code_change` | 改了什么文件 / 决策理由 / 引入接缝 | 10:1 | 决策理由 > 接缝 > 文件 |
+| `review` | 审查意见模式 / 反复出现的问题 / verdict | 20:1 | verdict > 模式 > 问题 |
+| `design` | 设计选择 / 约束条件 / 消费方 | 5:1 | 约束 > 选择 > 消费方 |
+| `question` | 问的是什么 / 答案摘要 / 来源 | 3:1 | 答案 > 问题类型 |
+| `planning` | 目标 / 依赖 / 风险点 / 决策缺口 | 5:1 | 风险 > 依赖 > 目标 |
+| `debugging` | 根因 / 症状 / 修复方案 / 验证方法 | 3:1 | 根因 > 修复 > 症状 |
+
+## 存储结构
+
+```
+.boll/state/context-chains/
+└── {YYYY-MM}/{session-id}-{work_type}-{seq}.yaml
+```
+
+每次会话生成一个摘要文件，命名规范：
+- `{session-id}`: 会话唯一标识（UUID 或时间戳）
+- `{work_type}`: 工作类型
+- `{seq}`: 当日序号（从 1 开始）
+
+## 摘要 YAML Schema
+
+```yaml
+session_id: "uuid-or-timestamp"
+work_type: code_change | review | design | question | planning | debugging
+created_at: "2026-05-23T15:00:00+08:00"
+gate_at_session: 0-8
+关联上下文:
+  - session_id: "..."
+    reason: "同模块改动了 X"
+    relevance: 0.8
+  - session_id: "..."
+    reason: "接缝变更影响 Y"
+    relevance: 0.6
+核心摘要:
+  work_type 内容字段（见下方各类型定义）
+决策缺口:
+  - 描述
+  - 影响
+  - 需要什么才能关闭
+风险点:
+  - 描述
+  - 概率
+  - 缓解措施
+遗迹（可丢失内容）:
+  - 过程讨论
+  - 试错过程
+  - 临时调试输出
+```
+
+## 各 work_type 核心摘要字段
+
+### code_change
+
+```yaml
+核心摘要:
+  files_changed:
+    - path: "src/agents/manager.ts"
+      change_type: modify | add | delete
+      reason: "解决 Z 问题"
+      seam_affected: true | false
+  decisions:
+    - choice: "选择方案 A 而非 B"
+      reason: "因为..."
+    - choice: "引入新接缝"
+      owner: "谁负责"
+  adr_linked: ["ADR-NNN"]
+```
+
+### review
+
+```yaml
+核心摘要:
+  verdict: PASS | BLOCK | CONDITIONAL
+  reviewed_artifact: "路径或描述"
+  blocking_issues:
+    - severity: blocker | warning | nit
+      description: "..."
+      pattern: "这是第 N 次出现此类问题"
+  non_blocking_observations:
+    - "..."
+  reviewer_preference_patterns:
+    - "审查者反复强调 X"
+      frequency: 3
+```
+
+### design
+
+```yaml
+核心摘要:
+  design_choices:
+    - what: "决定 X"
+      why: "因为约束 A/B/C"
+      alternatives_considered:
+        - "方案 B: 缺点是..."
+  constraints:
+    - type: technical | business | temporal
+      description: "..."
+  consumers:
+    - type: data | behavior | visibility
+      description: "..."
+```
+
+### question
+
+```yaml
+核心摘要:
+  question_type: concept | implementation | debugging | tool_usage
+  answer_summary: "一句话答案"
+  source: "来自文档/代码/讨论"
+  related_context:
+    - session_id: "..."
+      relevance: 0.7
+```
+
+### planning
+
+```yaml
+核心摘要:
+  goals:
+    - description: "..."
+      acceptance_criteria: ["...", "..."]
+  dependencies:
+    - on_artifact: "..."
+      type: blocks | informs
+  risks:
+    - description: "..."
+      probability: high | medium | low
+      mitigation: "..."
+  decision_gaps:
+    - question: "..."
+      stakes: "..."
+      owner: "谁决定"
+```
+
+### debugging
+
+```yaml
+核心摘要:
+  root_cause: "根本原因一句话"
+  symptoms_observed:
+    - "..."
+  fix_applied:
+    - description: "..."
+      verification: "..."
+  files_touched:
+    - "..."
+  introduced_regression_risk: low | medium | high
+```
+
+## 上下文链查找算法
+
+当新会话开始时，按以下顺序查找关联上下文：
+
+1. **同 work_type 最近 3 条**（权重 0.8）
+2. **同模块/同目录最近 2 条**（权重 0.7）
+3. **共享 ADR 关联**（权重 0.6）
+4. **审查 verdicts 关联**（权重 0.5）
+
+注入上限：取相关性加权求和 Top 5，总 token 预算 ≤ 2000。
+
+## 与 Judgment 系统集成
+
+context-chains 的摘要可以被 judgment 系统二次处理：
+
+- 高频出现的 `blocking_issues` → 新增 `rule` 类型判断
+- 审查者偏好模式 → 新增 `preference` 类型判断
+- 决策缺口积累 → 触发 `consult_external` 层级
+
+## 使用场景
+
+### 场景 1：会话结束自动摘要
+
+```
+会话结束时自动调用，生成摘要写入 .boll/state/context-chains/
+```
+
+### 场景 2：Gate 0 进入时注入
+
+```
+进入 Gate 0 时：
+1. 查找相关历史上下文链
+2. 注入核心摘要（≤ 2000 tokens）
+3. 输出关联 session_id 列表供深入查看
+```
+
+### 场景 3：显式请求
+
+```
+用户说"关联上次"或"总结上次做了什么"
+→ 找到最近一条同 work_type 摘要
+→ 展开核心摘要
+→ 必要时追溯完整链
+```
+
+### 场景 4：ADR 撰写时
+
+```
+写 ADR 前先注入相关 design/planning 摘要
+→ 约束条件已明确
+→ 避免重复造轮子
+```
+
+## 不做什么
+
+- 不存储完整会话记录（那是日志系统的事）
+- 不压缩过程性内容（试错、讨论细节）
+- 不做语义搜索（只做结构化字段匹配）
+- 不在摘要中存储秘密/密钥
+
+## 辅助文件
+
+- `context-chain-index.md` — 每日摘要索引
+- `work-type-extractors/` — 各 work_type 的萃取脚本

package/src/bollharness/.boll/skills/context-chains/context-chain-index.md

@@ -0,0 +1,48 @@
+# Context Chain Index
+
+每日摘要索引，按日期组织。
+
+## 结构
+
+```
+.boll/state/context-chains/
+└── {YYYY-MM}/
+    ├── index.yaml          # 当月所有摘要索引
+    └── {session-id}.yaml   # 单个会话摘要
+```
+
+## index.yaml Schema
+
+```yaml
+month: "2026-05"
+summaries:
+  - session_id: "20260523-001"
+    work_type: code_change
+    created_at: "2026-05-23T10:00:00+08:00"
+    gate_at_session: 7
+    related_adr: ["ADR-042"]
+    relevance_tags: ["src/agents", "multi-agent", "coordination"]
+    token_size: 320
+
+  - session_id: "20260523-002"
+    work_type: review
+    created_at: "2026-05-23T14:00:00+08:00"
+    gate_at_session: 2
+    verdict: BLOCK
+    blocking_count: 2
+    relevance_tags: ["src/constraints", "api-contract"]
+    token_size: 280
+```
+
+## 查找协议
+
+1. **按 work_type 过滤**: `grep -l "work_type: $TYPE" .boll/state/context-chains/.../*.yaml`
+2. **按 relevance_tags 匹配**: 模糊匹配
+3. **按日期范围**: `find .boll/state/context-chains/2026-05 -name "*.yaml"`
+4. **按 gate**: 审查门（2/4/6/8）的摘要优先级更高
+
+## 清理规则
+
+- 超过 90 天的摘要移到 `.boll/state/context-chains/archive/{YYYY-MM}/`
+- 只保留每类 work_type 最近 50 条
+- BLOCK verdict 的 review 摘要保留 180 天（重复问题模式识别需要）

package/src/bollharness/.boll/skills/context-chains/work-type-extractors/code_change_extractor.ts

@@ -0,0 +1,142 @@
+#!/usr/bin/env node
+/**
+ * code_change_extractor.ts
+ *
+ * 从 code_change 类型会话中萃取核心摘要
+ * 遵循 context-chains SKILL.md 的 code_change schema
+ */
+
+interface CodeChangeSummary {
+  session_id: string;
+  work_type: 'code_change';
+  created_at: string;
+  gate_at_session: number;
+  '关联上下文': Array<{
+    session_id: string;
+    reason: string;
+    relevance: number;
+  }>;
+  '核心摘要': {
+    files_changed: Array<{
+      path: string;
+      change_type: 'modify' | 'add' | 'delete';
+      reason: string;
+      seam_affected: boolean;
+    }>;
+    decisions: Array<{
+      choice: string;
+      reason: string;
+    }>;
+    adr_linked: string[];
+  };
+  '决策缺口': Array<{
+    描述: string;
+    影响: string;
+    需要什么才能关闭: string;
+  }>;
+  '风险点': Array<{
+    描述: string;
+    概率: 'high' | 'medium' | 'low';
+    缓解措施: string;
+  }>;
+  '遗迹': string[];
+}
+
+function extractFilesChanged(conversationText: string): CodeChangeSummary['核心摘要']['files_changed'] {
+  const files: CodeChangeSummary['核心摘要']['files_changed'] = [];
+
+  // 从 git diff 或文件列表中提取
+  const diffPattern = /^[+-]{3}\s+(?:a\/)?(.+)|^(?:modified|new file|deleted):\s+(.+)/gm;
+  let match;
+
+  while ((match = diffPattern.exec(conversationText)) !== null) {
+    const path = match[1] || match[2];
+    if (path && !path.includes('diff --git')) {
+      const changeType = match[0].startsWith('-')
+        ? 'delete'
+        : match[0].startsWith('+')
+          ? 'add'
+          : 'modify';
+
+      files.push({
+        path,
+        change_type: changeType,
+        reason: '', // 需要从上下文推断
+        seam_affected: false, // 需要从接缝分析得出
+      });
+    }
+  }
+
+  return files;
+}
+
+function extractDecisions(conversationText: string): CodeChangeSummary['核心摘要']['decisions'] {
+  const decisions: CodeChangeSummary['核心摘要']['decisions'] = [];
+
+  // 识别决策关键词
+  const decisionPatterns = [
+    /(?:决定|选择|采用|使用|选|Chose|Selected|Using)\s+(.+?)\s+(?:而非|instead of|rather than|而不是)\s+(.+)/gi,
+    /(?:因为|由于|考虑到|Considering|Because)\s+(.+?)，?\s*(?:决定|选择|采用)\s+(.+)/gi,
+    /decision:\s*(.+)/gi,
+  ];
+
+  // 简化版本：从关键词附近提取
+  const decisionKeywords = ['决定', '选择', '采用', '选用', 'Chose', 'Selected', 'Using', 'decision'];
+
+  return decisions;
+}
+
+function buildSummary(input: {
+  sessionId: string;
+  gate: number;
+  conversationText: string;
+  relatedSessions?: Array<{ sessionId: string; reason: string; relevance: number }>;
+}): CodeChangeSummary {
+  const files = extractFilesChanged(input.conversationText);
+  const decisions = extractDecisions(input.conversationText);
+
+  return {
+    session_id: input.sessionId,
+    work_type: 'code_change',
+    created_at: new Date().toISOString(),
+    gate_at_session: input.gate,
+    '关联上下文': input.relatedSessions || [],
+    '核心摘要': {
+      files_changed: files,
+      decisions,
+      adr_linked: [],
+    },
+    '决策缺口': [],
+    '风险点': [],
+    '遗迹': [],
+  };
+}
+
+export { buildSummary, type CodeChangeSummary };
+
+// CLI 用法
+if (require.main === module) {
+  const args = process.argv.slice(2);
+  if (args.length < 2) {
+    console.error('Usage: code_change_extractor.ts <session_id> <gate> [conversation_file]');
+    process.exit(1);
+  }
+
+  const [sessionId, gate] = args;
+  let conversationText = '';
+
+  if (args[2]) {
+    const fs = require('fs');
+    conversationText = fs.readFileSync(args[2], 'utf-8');
+  } else {
+    conversationText = require('fs').readFileSync('/dev/stdin', 'utf-8');
+  }
+
+  const summary = buildSummary({
+    sessionId,
+    gate: parseInt(gate, 10),
+    conversationText,
+  });
+
+  console.log(JSON.stringify(summary, null, 2));
+}

package/src/bollharness/.boll/skills/context-chains/work-type-extractors/debugging_extractor.ts

@@ -0,0 +1,126 @@
+#!/usr/bin/env node
+/**
+ * debugging_extractor.ts
+ *
+ * 从 debugging 类型会话中萃取核心摘要
+ * 遵循 context-chains SKILL.md 的 debugging schema
+ */
+
+interface DebuggingSummary {
+  session_id: string;
+  work_type: 'debugging';
+  created_at: string;
+  gate_at_session: number;
+  '关联上下文': Array<{ session_id: string; reason: string; relevance: number }>;
+  '核心摘要': {
+    root_cause: string;
+    symptoms_observed: string[];
+    fix_applied: Array<{
+      description: string;
+      verification: string;
+    }>;
+    files_touched: string[];
+    introduced_regression_risk: 'low' | 'medium' | 'high';
+  };
+  '决策缺口': Array<{ 描述: string; 影响: string; 需要什么才能关闭: string }>;
+  '风险点': Array<{ 描述: string; 概率: 'high' | 'medium' | 'low'; 缓解措施: string }>;
+  '遗迹': string[];
+}
+
+function extractRootCause(text: string): string {
+  const patterns = [
+    /(?:根因|root cause|根本原因|原因是|因为):\s*(.+)/gi,
+    /(?:问题出在|issue is|problem is):\s*(.+)/gi,
+  ];
+
+  for (const pattern of patterns) {
+    const match = pattern.exec(text);
+    if (match) {
+      return match[1].trim();
+    }
+  }
+
+  return '';
+}
+
+function extractSymptoms(text: string): string[] {
+  const symptoms: string[] = [];
+
+  const symptomPattern = /(?:症状|symptom|表现|现象|出现|报错|error):\s*(.+)/gi;
+  let match;
+
+  while ((match = symptomPattern.exec(text)) !== null) {
+    symptoms.push(match[1].trim());
+  }
+
+  return symptoms;
+}
+
+function extractFix(text: string): DebuggingSummary['核心摘要']['fix_applied'] {
+  const fixes: DebuggingSummary['核心摘要']['fix_applied'] = [];
+
+  const fixPattern = /(?:修复|fix|解决|方案|approach):\s*(.+)/gi;
+  let match;
+
+  while ((match = fixPattern.exec(text)) !== null) {
+    fixes.push({
+      description: match[1].trim(),
+      verification: '',
+    });
+  }
+
+  return fixes;
+}
+
+function extractFilesTouched(text: string): string[] {
+  const files: string[] = [];
+
+  // Common file patterns in code discussions
+  const filePattern = /(?:modified|changed|updated|fixed|编辑|修改):\s*([^\s]+)/gi;
+  let match;
+
+  while ((match = filePattern.exec(text)) !== null) {
+    files.push(match[1]);
+  }
+
+  return [...new Set(files)];
+}
+
+function buildSummary(input: {
+  sessionId: string;
+  gate: number;
+  conversationText: string;
+  relatedSessions?: Array<{ sessionId: string; reason: string; relevance: number }>;
+}): DebuggingSummary {
+  return {
+    session_id: input.sessionId,
+    work_type: 'debugging',
+    created_at: new Date().toISOString(),
+    gate_at_session: input.gate,
+    '关联上下文': input.relatedSessions || [],
+    '核心摘要': {
+      root_cause: extractRootCause(input.conversationText),
+      symptoms_observed: extractSymptoms(input.conversationText),
+      fix_applied: extractFix(input.conversationText),
+      files_touched: extractFilesTouched(input.conversationText),
+      introduced_regression_risk: 'medium',
+    },
+    '决策缺口': [],
+    '风险点': [],
+    '遗迹': [],
+  };
+}
+
+export { buildSummary, type DebuggingSummary };
+
+if (require.main === module) {
+  const args = process.argv.slice(2);
+  const [sessionId, gate] = args;
+  const fs = require('fs');
+  const conversationText = args[2]
+    ? fs.readFileSync(args[2], 'utf-8')
+    : fs.readFileSync('/dev/stdin', 'utf-8');
+
+  const summary = buildSummary({ sessionId, gate: parseInt(gate, 10), conversationText });
+  console.log(JSON.stringify(summary, null, 2));
+}

package/src/bollharness/.boll/skills/context-chains/work-type-extractors/design_extractor.ts

@@ -0,0 +1,148 @@
+#!/usr/bin/env node
+/**
+ * design_extractor.ts
+ *
+ * 从 design 类型会话中萃取核心摘要
+ * 遵循 context-chains SKILL.md 的 design schema
+ */
+
+interface DesignSummary {
+  session_id: string;
+  work_type: 'design';
+  created_at: string;
+  gate_at_session: number;
+  '关联上下文': Array<{ session_id: string; reason: string; relevance: number }>;
+  '核心摘要': {
+    design_choices: Array<{
+      what: string;
+      why: string;
+      alternatives_considered: string[];
+    }>;
+    constraints: Array<{
+      type: 'technical' | 'business' | 'temporal';
+      description: string;
+    }>;
+    consumers: Array<{
+      type: 'data' | 'behavior' | 'visibility';
+      description: string;
+    }>;
+  };
+  '决策缺口': Array<{ 描述: string; 影响: string; 需要什么才能关闭: string }>;
+  '风险点': Array<{ 描述: string; 概率: 'high' | 'medium' | 'low'; 缓解措施: string }>;
+  '遗迹': string[];
+}
+
+function extractDesignChoices(text: string): DesignSummary['核心摘要']['design_choices'] {
+  const choices: DesignSummary['核心摘要']['design_choices'] = [];
+
+  // Pattern: "决定 X 而非 Y" or "选择 X 而不是 Y"
+  const decisionPattern = /(?:决定|选择|采用|选用|Chose|Selected|Decided)\s+(.+?)\s+(?:而非|instead of|rather than|而不是)\s+(.+)/gi;
+  let match;
+
+  while ((match = decisionPattern.exec(text)) !== null) {
+    choices.push({
+      what: match[1].trim(),
+      why: '',
+      alternatives_considered: [match[2].trim()],
+    });
+  }
+
+  // Pattern: "因为...所以决定"
+  const becausePattern = /(?:因为|由于|考虑到|Considering|Because)\s*(.+?)[，,]\s*(?:决定|选择|采用)\s+(.+)/gi;
+  while ((match = becausePattern.exec(text)) !== null) {
+    choices.push({
+      what: match[2].trim(),
+      why: match[1].trim(),
+      alternatives_considered: [],
+    });
+  }
+
+  return choices;
+}
+
+function extractConstraints(text: string): DesignSummary['核心摘要']['constraints'] {
+  const constraints: DesignSummary['核心摘要']['constraints'] = [];
+
+  const constraintKeywords = [
+    { keyword: '必须', type: 'technical' as const },
+    { keyword: '不能', type: 'technical' as const },
+    { keyword: '限于', type: 'temporal' as const },
+    { keyword: '预算', type: 'business' as const },
+    { keyword: '时间', type: 'temporal' as const },
+    { keyword: '技术限制', type: 'technical' as const },
+    { keyword: '业务要求', type: 'business' as const },
+  ];
+
+  const sentences = text.split(/[.!?]/);
+  for (const sentence of sentences) {
+    for (const { keyword, type } of constraintKeywords) {
+      if (sentence.includes(keyword)) {
+        constraints.push({
+          type,
+          description: sentence.trim().slice(0, 100),
+        });
+      }
+    }
+  }
+
+  return constraints;
+}
+
+function extractConsumers(text: string): DesignSummary['核心摘要']['consumers'] {
+  const consumers: DesignSummary['核心摘要']['consumers'] = [];
+
+  const consumerPatterns = [
+    { pattern: /(?:数据消费方|data consumer):\s*(.+)/gi, type: 'data' as const },
+    { pattern: /(?:行为消费方|behavior consumer):\s*(.+)/gi, type: 'behavior' as const },
+    { pattern: /(?:可见性消费方|visibility consumer):\s*(.+)/gi, type: 'visibility' as const },
+  ];
+
+  for (const { pattern, type } of consumerPatterns) {
+    let match;
+    while ((match = pattern.exec(text)) !== null) {
+      consumers.push({
+        type,
+        description: match[1].trim(),
+      });
+    }
+  }
+
+  return consumers;
+}
+
+function buildSummary(input: {
+  sessionId: string;
+  gate: number;
+  conversationText: string;
+  relatedSessions?: Array<{ sessionId: string; reason: string; relevance: number }>;
+}): DesignSummary {
+  return {
+    session_id: input.sessionId,
+    work_type: 'design',
+    created_at: new Date().toISOString(),
+    gate_at_session: input.gate,
+    '关联上下文': input.relatedSessions || [],
+    '核心摘要': {
+      design_choices: extractDesignChoices(input.conversationText),
+      constraints: extractConstraints(input.conversationText),
+      consumers: extractConsumers(input.conversationText),
+    },
+    '决策缺口': [],
+    '风险点': [],
+    '遗迹': [],
+  };
+}
+
+export { buildSummary, type DesignSummary };
+
+if (require.main === module) {
+  const args = process.argv.slice(2);
+  const [sessionId, gate] = args;
+  const fs = require('fs');
+  const conversationText = args[2]
+    ? fs.readFileSync(args[2], 'utf-8')
+    : fs.readFileSync('/dev/stdin', 'utf-8');
+
+  const summary = buildSummary({ sessionId, gate: parseInt(gate, 10), conversationText });
+  console.log(JSON.stringify(summary, null, 2));
+}