AI Company Modularization — ClawHub Schema v1.0

AI Company 模块化流程 Skill。将单体式 Skill 分解为原子化、可独立测试、可组合的模块单元。

概述

模块化（Modularization） 是 Skill 架构演进的关键步骤。它将一个大的、复杂的 Skill 分解为多个小的、专注的模块，每个模块：

• 独立负责一个明确的功能
• 有清晰的输入/输出接口
• 可以独立测试和版本控制
• 可以被其他模块或 Skill 复用

目标

• 将单体 Skill 分解为可独立管理的模块
• 消除模块间隐藏依赖（spaghetti coupling）
• 实现模块级独立测试
• 支持模块级版本控制和独立发布
• 为 Skill 组合（composition）提供基础

模块化原则

模块化六步流程

Step 1 — 模块边界识别

目标： 找到 Skill 中自然的功能边界。

方法：

1. 职责分析：列出 Skill 中所有功能点
2. 变更频率分析：哪些功能经常一起变更？哪些独立变化？
3. 复用分析：哪些功能可能被其他 Skill 复用？
4. 边界绘制：画出功能依赖图，识别自然切割点

识别启发式规则：

✅ 自然模块边界：
  - 完全不同的输入类型 → 独立模块
  - 完全不同的输出类型 → 独立模块
  - 不同的更新频率 → 独立模块
  - 可被其他 Skill 复用 → 优先拆分为模块

❌ 不应拆分：
  - 只是代码长，但没有功能差异 → 不要拆分
  - 两个功能紧耦合无法独立 → 保持单体
  - 拆分后模块 < 50 行 → 合并而非拆分

Step 2 — 接口定义

每个模块必须定义清晰的接口：

module_name:
  description: string
  version: semver
  inputs:
    param1:
      type: string | number | boolean | object | array
      required: boolean
      description: string
      default?: any
      validation?: string  # e.g. "range: 0-100"
  outputs:
    result:
      type: object
      description: string
      schema: string  # JSON Schema
  errors:
    - code: MODULE_001
      cause: string
      remediation: string
  side_effects: string[]  # 文件系统/网络/状态变更

接口设计原则：

• 输入参数类型明确，无隐式类型转换
• 输出结构完整描述，有 JSON Schema
• 错误码统一前缀：{MODULE_ABBR}_{CODE}
• 避免副作用；若不可避免，明确声明

Step 3 — 依赖分析

构建模块依赖图：

def build_dependency_graph(modules: list[Module]) -> DependencyGraph:
    graph = {}
    for module in modules:
        deps = []
        for dep in module.imports:
            if dep in all_modules:
                deps.append(dep)
        graph[module.name] = deps
    
    # 检测循环依赖
    cycles = detect_cycles(graph)
    if cycles:
        raise MOD_002(f"Circular dependency: {' -> '.join(cycles)}")
    
    return graph

依赖耦合度评分：

目标： 所有模块间依赖 ≤ 特征耦合（分数 ≤ 2）

Step 4 — 共享逻辑提取

目标： 消除重复代码，建立可复用工具库。

提取策略：

def extract_shared_logic(modules: list[Module], threshold: float = 0.3) -> list[SharedModule]:
    """
    threshold: 若代码重复率 > threshold，触发提取
    """
    shared = []
    duplication_map = find_duplication(modules)
    
    for dup_set in duplication_map:
        if dup_set.duplication_ratio > threshold:
            shared_module = SharedModule(
                name=dup_set.common_name,
                code=dup_set.extracted_code,
                used_by=[m.name for m in dup_set.affected_modules],
                interface=dup_set.shared_interface,
            )
            shared.append(shared_module)
            # 从各模块中移除重复代码，替换为调用
    
    return shared

共享模块命名规范：

Step 5 — 目录结构

{skill-name}/
├── SKILL.md              # 主 Skill（编排模块）
├── MODULES.md            # 模块索引 + 依赖图
├── modules/
│   ├── module-alpha/
│   │   ├── module.md      # 模块定义 + 接口
│   │   └── tests/
│   │       └── module-alpha.test.yaml  # 模块级测试
│   ├── module-beta/
│   │   ├── module.md
│   │   └── tests/
│   │       └── module-beta.test.yaml
│   └── shared/
│       ├── utils/
│       │   └── shared-utils.md
│       └── types/
│           └── shared-types.md
├── scripts/               # 可执行脚本（如有）
│   └── run-module-alpha.sh
└── references/
    ├── architecture.md    # 模块架构文档
    └── dependency-graph.dot

每个 module.md 的最小内容：

# Module: {module-name}

## Version
{module_version}

## Responsibility
{一句话描述模块负责什么}

## Interface
{inputs/outputs/errors YAML}

## Dependencies
{external_modules_required}

## Provides
{what_this_module_provides_to_other_modules}

## Test Coverage
{covered_test_cases}

## Known Limitations
{边界情况/已知问题}

Step 6 — 测试与集成

模块级测试套件（YAML）：

# module-alpha.test.yaml
module: module-alpha
version: "1.0.0"
test_cases:
  - name: happy_path
    input:
      param1: valid_value
    expected:
      status: success
      result: expected_output
  
  - name: edge_case_null
    input:
      param1: null
    expected:
      status: error
      code: MODULE_003
  
  - name: invalid_input_type
    input:
      param1: 999
    expected:
      status: error
      code: MODULE_002

集成测试策略：

接口定义

decompose-skill

将单体 Skill 分解为模块。

Input:

skill_path: string                    # 目标 Skill 路径
proposed_modules: string[] | null     # 建议的模块名称列表，null = 自动识别
shared_threshold: number              # 0-1，重复率 > 此值则提取共享模块

Output:

status: success | failed
skill_name: string
proposed_modules:
  - name: string
    size_lines: number
    responsibility: string
    interface: object
    dependencies: string[]
    cohesion_score: 0-100
    coupling_score: 0-100
shared_modules:
  - name: string
    extracted_from: string[]
    duplication_ratio: 0-1
    interface: object
dependency_graph: object
warnings:
  - message: string
    severity: high | medium | low
    suggestion: string
estimated_modularization_effort: string  # e.g. "2-3 hours"

compose-modules

将多个模块组合为复合 Skill。

Input:

module_paths: string[]                # 模块 .md 文件路径列表
skill_name: string                    # 生成的 Skill 名称
orchestration_order: string[] | null  # 执行顺序，null = 自动推导

Output:

composite_skill_path: string
interface_contracts:
  - module_a: string
    module_b: string
    contract_valid: boolean
    conflicts: string[]
generated_orchestrator: object
test_coverage: number
warnings: string[]

extract-shared

从多个模块中提取共享逻辑。

Input:

module_paths: string[]
extraction_type: utils | types | validators | templates
naming_convention: string  # 命名规范

Output:

shared_module:
  name: string
  path: string
  size_lines: number
  used_by: string[]
  deduplication_saved: number  # 减少的重复代码行数
updated_modules: string[]
interface: object

validate-modularization

验证模块化结果的质量。

Input:

modularized_skill_path: string
strict: boolean  # 若 true，耦合度 > 2 即报错

Output:

valid: boolean
scores:
  modularity: 0-100
  cohesion: 0-100
  coupling: 0-100
  testability: 0-100
issues:
  - type: circular_dependency | high_coupling | low_cohesion | missing_interface
    modules: string[]
    message: string
    fix: string
compliance:
  no_circular_deps: boolean
  all_interfaces_defined: boolean
  all_modules_tested: boolean

模块化质量评分

变更日志