存量代码迁移不是问一句答一句：用 Skill / SubAgent / Agent Team 三层架构管住 AI

# skill_handler_to_coroutine.py — 一个 Skill 的 prompt 构建模板

SKILL_PROMPT = """你是一个 Android→KMP 代码迁移执行器。

## 输入
- 原始 Android 代码片段（下方 SOURCE_BLOCK）
- 所属模块：{module_name}
- 目标平台：KMP（Android + iOS 共享模块）

## 约束规则
1. 只做语法和 API 映射，不重构业务逻辑。
2. Handler.postDelayed → CoroutineScope.launch { delay(ms) }，保持原延迟时长。
3. Handler.sendMessage / handleMessage → 用 Channel 或 Flow 替代，优先 Flow。
4. 不引入新第三方依赖，只用 kotlinx.coroutines 标准库。
5. 输出必须可编译——不要留 TODO 或占位符。

## 输出格式
```kotlin
// 迁移后的 KMP 代码
...

这个模板里 `{module_name}` 和 `{source_code}` 由调度层动态填充。Skill 本身不关心"这段代码从哪来"，它只关心"拿到这段代码后怎么稳定地执行转换"。

---

## SubAgent：调度不失控的中间层

一个 Skill 只能处理一个原子任务。但一次迁移可能涉及"先读文件 → 分析依赖 → 拆分子任务 → 逐个 Skill 执行 → 合并结果"这条链路。SubAgent 就是这条链路的调度器。

核心职责：

- **任务拆分**：拿到一个模块级迁移需求后，SubAgent 先做依赖分析，把大任务拆成 Skill 级子任务队列。
- **上下文管理**：每个 Skill 执行时需要的上下文（比如"这个类被另外三个类引用"）由 SubAgent 凇备好再喂进去，而不是让 Skill 自己去猜。
- **失败兜底**：某个 Skill 输出编译失败时，SubAgent 决定是重试、降级（比如换一个更保守的映射策略），还是标记为人工介入点。

我们踩过的一个坑：早期让 SubAgent "自由规划执行顺序"，结果它经常先改底层工具类、再改上层调用——编译中间态全是错的，后续 Skill 的输入就脏了。后来改成**自底向上的拓扑排序**，先迁移叶子节点（无内部依赖的工具类），再逐层往上，中间态始终可编译。

```yaml
# subagent_config.yaml — SubAgent 调度策略配置示例

subagent:
  name: module_migration_scheduler
  description: "负责单个模块的 KMP 迁移调度"

  scheduling_strategy:
    order: dependency_topological  # 拉依赖图，自底向上
    max_concurrent_skills: 3       # 最多并行 3 个 Skill
    retry_limit: 2                 # 单个 Skill 失败最多重试 2 次
    fallback: mark_for_human       # 重试耗尽后标记人工介入

  context_preparation:
    include_imports: true           # 喂给 Skill 时带上 import 声明
    include_callers: true           # 带上调用方代码片段（最多 3 层）
    max_context_tokens: 8000        # 上下文 token 上限，防止溢出

  validation:
    compile_check: true             # 每个 Skill 输出做编译检查
    lint_check: true                # 跑 KMP lint 规则
    diff_review: true               # 对比原代码，确认只做映射不做重构

# agent_team_orchestrator.py — 简化版 Team 层调度逻辑

import json
from pathlib import Path

def load_dependency_matrix(path: str) -> dict:
    """加载静态分析生成的模块依赖矩阵"""
    with open(path) as f:
        return json.load(f)

def compute_migration_order(dep_matrix: dict) -> list[str]:
    """根据依赖数量排序：被依赖最多的模块先迁（共享层优先）"""
    # dep_matrix 格式: {"module_a": ["module_b", "module_c"], ...}
    # 被依赖次数
    depend_count = {}
    for mod, deps in dep_matrix.items():
        depend_count.setdefault(mod, 0)
        for d in deps:
            depend_count.setdefault(d, 0)
            depend_count[d] += 1

    # 按被依赖次数降序排列——共享底层先迁
    return sorted(depend_count.keys(), key=lambda m: depend_count[m], reverse=True)

def dispatch_module_to_subagent(module_name: str, dep_matrix: dict):
    """把单个模块交给 SubAgent 执行迁移"""
    # 构造 SubAgent 输入：模块名 + 该模块的依赖列表
    subagent_input = {
        "module": module_name,
        "internal_deps": dep_matrix.get(module_name, []),
        "strategy": "dependency_topological",
    }
    # 这里对接你的 SubAgent 调度引擎
    print(f"[Team] 分发模块 {module_name} → SubAgent，内部依赖: {subagent_input['internal_deps']}")
    return subagent_input

# —— 主流程 ——
dep_matrix = load_dependency_matrix("module_deps.json")
order = compute_migration_order(dep_matrix)

print(f"迁移顺序: {order}")
for mod in order:
    dispatch_module_to_subagent(mod, dep_matrix)

{
  "shared_core": ["file_list", "upload", "download", "settings"],
  "file_list": ["shared_core"],
  "upload": ["shared_core", "file_list"],
  "download": ["shared_core", "file_list"],
  "settings": ["shared_core"]
}