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

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

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[]  # 文件系统/网络/状态变更

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
    
    # detect循环依赖
    cycles = detect_cycles(graph)
    if cycles:
        raise MOD_002(f"Circular dependency: {' -> '.join(cycles)}")
    
    return graph

def extract_shared_logic(modules: list[Module], threshold: float = 0.3) -> list[SharedModule]:
    """
    threshold: 若代码重复率 > threshold，trigger提取
    """
    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

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

# Module: {module-name}

## Version
{module_version}

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

## Interface
{inputs/outputs/errors YAML}

## Dependencies
{external_modules_required}

## Provides
{what_this_module_provides_to_other_modules}

## Test Coverage
{covered_test_cases}

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

# 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

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

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"

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

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[]

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

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

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

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