artifact-integrator

工件集成器

用途

分析新建或修改的工件，找出集成缺口，并提出后续任务，确保工件与整个生态系统充分集成。

使用时机

• 任意工件创建器技能完成后
• Router Step 0.5 检测到集成队列中有未处理条目时
• 手动检查集成状况时
• 审查工件完整性时

协议

步骤 1：读取集成队列

读取 .claude/context/runtime/integration-queue.jsonl 筛选 "processed": false 的条目 如果没有未处理条目，请检查是否提供了 artifactId 参数以进行直接分析。

步骤 2：分析每个工件

对于每个未处理条目（或直接指定的工件）：

1. 加载工件图谱：require('.claude/lib/workflow/artifact-graph.cjs')
2. 加载影响分析器：require('.claude/lib/workflow/integration-impact.cjs')
3. 调用 analyzeImpact({ artifactId, changeType, graphPath })
4. 检查 missingIntegrations 和 proposedTasks

步骤 3：生成集成计划

对于存在集成缺口的每个工件：

必须项（P1）— 立即创建任务：

• 缺少目录条目 → TaskCreate：「将 {name} 添加到 {catalog}」
• 缺少 Agent 分配 → TaskCreate：「将 {name} 分配给相关 Agent」
• 缺少路由条目 → TaskCreate：「更新 {name} 的路由」
• 缺少钩子注册 → TaskCreate：「在 settings.json 中注册 {name}」

应做项（P2）— 创建较低优先级的任务：

• 缺少文档 → TaskCreate：「在 {doc} 中编写 {name} 的文档」
• 缺少执行钩子 → TaskCreate：「为 {name} 创建执行机制」
• 缺少测试 → TaskCreate：「为 {name} 编写测试」

可选项 — 记录但不创建任务：

• 缺少模板、可选文档

步骤 3.1：伴随项矩阵分析（交织式创建器生态系统）

对于每个已分析的工件，运行伴随项矩阵验证，找出缺失的生态系统伴随项：

分析：

1. 使用 .claude/lib/creators/companion-check.cjs 中的 companion-check.cjs
2. 调用 checkCompanions(artifactType, artifactName) 获取伴随项矩阵
3. 将伴随项检查清单解析为以下类别：
   • 必需伴随项（工件完整性所必需）
   • 推荐伴随项（最佳实践所需）
   • 可选伴随项（实现完整集成的理想选项）

任务生成：

• 对于每个缺失的必需伴随项 → 创建 P1 任务：「为 {artifact-name} 创建 {companion-type}:{companion-name}」
• 对于每个缺失的推荐伴随项 → 创建 P2 任务：「考虑为 {artifact-name} 创建 {companion-type}:{companion-name}」
• 对于缺失的可选伴随项 → 在报告中记录，但不创建任务

安全限制（SEC-ICE-002）：

• 每个工件自动创建的任务上限：3 个（防止级联创建）
• 每次集成运行的伴随项任务总数上限：10 个（防止批量任务爆发）
• 如果超出限制，将其余伴随项加入队列供人工审查，并在报告中发出警告

示例：

### Companion Matrix Analysis: skill:rate-limiter

**Required Companions (MISSING):**

- [ ] hook:rate-limit-validator (validates rate limit headers) — **TASK CREATED** (P1)
- [ ] schema:rate-limit-config (validates configuration) — **TASK CREATED** (P1)

**Recommended Companions (MISSING):**

- [ ] template:rate-limit-pattern (template for rate limiting implementations) — **TASK CREATED** (P2)

**Optional Companions (MISSING):**

- [ ] workflow:rate-limit-setup (onboarding workflow) — noted for future consideration

**Safety Check:**

- Auto-spawned tasks: 3 (within limit of 3 per artifact)
- Total companion tasks this run: 8 (within limit of 10)

与 Companion Check 的集成：

• 伴随项矩阵数据来自 ecosystem-impact-graph.json
• 使用创建器技能在步骤 0.5 调用的同一个 companion-check.cjs 库
• 确保双向一致性：创建器在创建时检查伴随项，集成器在创建后验证伴随项

步骤 3.5：反向传播处理（ADR-100 第 3.1-3.3 阶段）

处理来自 code-reviewer 或 architect 的反向传播信号时：

检测：

• changeType: "backward-propagation" 的队列条目
• 包含 BACKWARD_PROPAGATION 部分的审查发现
• 指示系统性重复的模式报告

验证：

1. 确认模式确实存在（检查提及的文件/组件）

   • 阅读每个受影响的文件，确认模式重复
   • 统计实际实例数（而非仅依赖声称的实例数）
   • 验证模式的相似性（而非仅表面相似）

2. 评估是否需要创建新工件

   • 阈值：存在至少 3 个相同或近乎相同的模式实例
   • 影响：工件能否减少 50% 以上的重复代码行数？
   • 可维护性：集中管理能否提高可维护性？

3. 如果确有必要，加入创建队列：

   • 向 integration-queue.jsonl 写入 changeType: "backward-propagation" 条目
   • 设置 proposedArtifact 字段，注明类型和建议名称
   • 根据影响设置优先级：
     • P1（3-5 个实例、安全/关键模式）
     • P2（6 个以上实例、质量/一致性模式）
   • 附上验证证据（文件路径、代码行数、模式摘录）

4. 在集成分析报告中反馈：

## Backward Propagation Analysis

**Pattern**: <validated pattern description>
**Instances Found**: <actual count> (claimed: <original count>)
**Proposed Artifact**: <type>:<name>
**Justification**: <why centralization is beneficial>
**Priority**: P1 | P2
**Next Steps**: Queued for creator skill invocation

队列条目示例：

{
  "artifactId": "hook:jwt-validation",
  "changeType": "backward-propagation",
  "timestamp": "2026-02-08T10:30:00Z",
  "processed": false,
  "source": "code-reviewer",
  "pattern": "Manual JWT validation logic duplicated in 4 route handlers",
  "affectedFiles": [
    "routes/auth.ts",
    "routes/api.ts",
    "routes/admin.ts",
    "routes/user.ts"
  ],
  "validatedInstances": 4,
  "estimatedLOCReduction": 120,
  "priority": "P1",
  "proposedArtifact": {
    "type": "hook",
    "name": "jwt-validation",
    "rationale": "Centralize JWT validation for consistent security enforcement"
  }
}

拒绝条件：

• 模式出现在少于 3 个文件中（重复不足）
• 模式差异过大（并非真正重复）
• 现有工件已处理此模式（孤立/利用不足）
• 减少的代码行数少于 30 行（收益不足）

与 Creator 技能的集成：

• 通过验证的反向传播条目会触发 Creator 技能调用
• Creator 技能（skill-creator、hook-creator、template-creator、schema-creator）会处理队列条目
• 创建完成后，artifact-integrator 会按标准流程处理新建工件的集成

步骤 4：更新图

创建集成任务后：

• 为新发现的关系添加边
• 根据当前状态更新节点的 integrationStatus
• 保存图

步骤 5：标记已处理的队列条目

对于每个已处理的条目，更新 JSONL，将 processed: true 标记为已处理

步骤 6：报告

输出摘要：

## Integration Analysis Report

Processed: {count} artifacts
Tasks created: {count}
Must-have gaps: {count}
Should-have gaps: {count}

### Details
[artifact-by-artifact breakdown]

参数

• artifactId（可选）— 分析特定工件，而不是队列
• mode（可选）— 'queue'（默认）| 'single' | 'health-check'

按工件类型划分的集成规则

类型	必须具备	建议具备
Skill	Catalog + Agent 分配	Hook、工作流引用
Agent	Registry + 路由关键词	Skills、模型配置
Hook	settings.json 注册	文档条目
Workflow	Registry + Agent 映射	文档条目
Template	Catalog 条目	使用方引用
Schema	Catalog 条目	使用方接线

使用示例

Skill({ skill: 'artifact-integrator' });
// Processes queue, creates tasks, updates graph

Skill({ skill: 'artifact-integrator', args: 'skill:rate-limiter' });
// Analyzes specific artifact

实现参考

核心库：

• .claude/lib/workflow/integration-impact.cjs - 影响分析和任务生成
• .claude/lib/workflow/artifact-graph.cjs - 图的 CRUD 操作

数据源：

• .claude/context/runtime/integration-queue.jsonl - 需要集成的工件队列
• .claude/context/data/artifact-graph.json - 工件关系图

集成队列格式：

{"artifactId":"skill:rate-limiter","changeType":"created","timestamp":"2026-02-07T10:30:00Z","processed":false}
{"artifactId":"agent:security-architect","changeType":"updated","timestamp":"2026-02-07T10:35:00Z","processed":false}

工作流集成

以下场景会调用此技能：

• Router 步骤 0.5（存在队列条目时自动调用）
• Creator 技能（工件创建后）
• 手动运行健康检查

自动调用模式：

// Router Step 0.5 pseudocode
if (integrationQueueHasUnprocessedEntries()) {
  Task({
    task_id: 'task-1',
    subagent_type: 'developer',
    prompt: 'Invoke Skill({ skill: "artifact-integrator" })',
  });
}

铁律

1. 在开始创建任何新产物前，始终检查集成队列 — 步骤 0.5 是强制步骤；未处理的条目会不断累积，悄然形成孤立债务。
2. 每个产物绝不创建超过 3 个自动生成的配套任务 — SEC-ICE-002 规定了硬性上限；超过上限会使 Agent 流水线不堪重负；将剩余配套任务留待人工审核。
3. 始终根据实际代码验证反向传播声明 — 排队前必须确认至少 3 个重复实例，且代码行数减少至少 30 行；绝不排入未经验证的声明。
4. 在报告完成前，始终将队列条目标记为 processed: true — 未处理的条目会一直保留，并在每次后续调用时重试。
5. 报告集成缺口时，绝不遗漏更新产物图谱 — 图谱是产物关系的记录依据；未更新图谱的缺口报告对未来运行不可见。

反模式

反模式	失败原因	正确做法
跳过集成队列检查	未处理的条目会悄然累积	始终在步骤 1 读取 integration-queue.jsonl
每个产物创建超过 3 个配套任务	任务激增会使 Agent 流水线不堪重负	执行 SEC-ICE-002：每个产物最多 3 个，总计 10 个
未经代码验证就排入反向传播	假阳性会产生不必要的产物	确认至少 3 个实例，且代码行数减少至少 30 行
未将队列条目标记为已处理	条目会在下次调用时无限期重试	在报告完成前设置 processed: true
报告缺口但不更新产物图谱	图谱会过时；未来分析会使用错误数据	缺口分析后始终更新图谱边
对未经验证的产物 ID 运行集成	无效 ID 会导致无声失败	分析前确认产物文件存在

相关技能

• research-synthesis - 创建产物前的研究阶段
• agent-creator - 创建 Agent（触发集成分析）
• skill-creator - 创建技能（触发集成分析）
• hook-creator - 创建钩子（触发集成分析）
• workflow-creator - 创建工作流（触发集成分析）

记忆协议（强制）

开始前： 读取 .claude/context/memory/learnings.md

完成后：

• 新的集成模式 → .claude/context/memory/learnings.md
• 发现问题 → .claude/context/memory/issues.md
• 做出决策 → .claude/context/memory/decisions.md

假设任务会被中断：如果没有记录在记忆中，就等于没有发生。