feat: 为所有 117 个函数添加类型注解

[urika]

Summary

Fixes #7

为 14 个模块的所有 117 个函数添加完整的参数和返回值类型注解，覆盖率从 11% 提升到 100%。

变更内容

• 每个模块添加 from typing import Any, Optional（按需）
• 所有函数参数和返回值添加类型注解
• 包含嵌套函数（_run_one, parse_and_log, _on_interrupt 等）
• Python 3.9+ 兼容：Optional[X] 而非 X | None，list[str] 而非 List[str]

Before / After

维度	重构前	重构后
有返回值注解的函数	15/117 (13%)	117/117 (100%)
有参数注解的函数	37/117 (32%)	117/117 (100%)

Test

163 passed in 4.06s

🤖 Generated with Claude Code

[urika]

Review — PR #30: 为所有 117 个函数添加类型注解

🔴 Critical — 错误的类型注解

1. _set_gc_auto 返回值类型标注错误

agent_go/git_utils.py

# PR 标注:
def _set_gc_auto(repo: Path, value: str = "0") -> tuple[bool, str]:

# 实际返回 (3 个值):
return original, set_result.returncode == 0, err_msg
# 即 (str, bool, str)

函数返回 (original_value: str, success: bool, error_message: str) 共 3 个值，但标注为 tuple[bool, str]（2 个值，类型也错）。调用方 pipeline.py 已正确解构为 original_gc_value, ok, _ = _set_gc_auto(...)。

修复: -> tuple[str, bool, str]

2. confirm_plan 返回值类型标注错误

agent_go/ui.py

# PR 标注:
def confirm_plan(...) -> Optional[dict[str, Any]]:

# 实际返回值（docstring 已说明）:
#   return plan, reference_doc_paths       → (dict, list)
#   return None, reference_doc_paths       → (None, list)
#   return ("__FALLBACK__", None)          → (str, None)

函数返回的是 tuple，不是单个 dict。标注 Optional[dict] 完全不匹配。

修复: -> tuple[Optional[dict[str, Any]], Optional[list[str]]] 或定义更精确的 Union 类型

🟡 Major

3. 本 PR 改了 14 个模块文件，会与几乎所有其他 open PR 产生合并冲突

• 与 PR refactor: 拆分 run_subtask 为多个辅助函数 (Issue #3) #21（executor.py 重构）冲突
• 与 PR fix(security): 验证命令参数级白名单 + 资源限制 + 审计日志 #27（executor.py + utils.py 安全加固）冲突
• 与 PR feat: CLI 参数解析迁移至 argparse (Issue #2) #20（cli.py argparse）冲突

建议: 等其他 PR 合并后再 rebase 合并本 PR，避免反复冲突。

4. __all__: list[str] = [] 类型标注不寻常

pipeline.py 和 subtask.py 中 __all__ 被标注为 list[str]。虽然语法正确，但 __all__ 惯例上不加类型标注。这可能让一些静态分析工具（如 isort、pylint）误判。

5. _make_skill_dir 辅助函数在两个测试文件中重复

test_skills.py 和 test_integration.py 各自定义了完全相同的 _make_skill_dir 静态方法。建议提取到 conftest.py 共享。

🟢 Minor

6. 部分注解精度可提升

• active_pids: Optional[set] → 建议 Optional[set[int]]
• tui_main(stdscr: Any) → 建议 Any 加注释说明是 curses.window
• config: dict[str, Any] 到处使用，可考虑定义 ConfigDict = dict[str, Any] 类型别名

7. 测试修复很有价值

修复了 test_skills.py 和 test_integration.py 在 CI 中的失败问题（用 tmp_path + patch("AGENT_GO_SKILLS_DIR") 替代全局目录依赖）。新增了 test_load_skills_missing_skipped 和 test_list_skills_empty 用例。这些修复可以独立于类型注解提交。

---

总结: 需修复 Critical #1-2（错误的返回值类型注解）后，等 #21/#27/#20 合并完成再 rebase 合并。测试修复部分建议可提前独立提交。

[urika]

✅ 类型注解已修复

1. ✅ _set_gc_auto: tuple[bool, str] → tuple[str, bool, str]（函数实际返回3个值）
2. ✅ confirm_plan: Optional[dict[str, Any]] → tuple[Optional[dict[str, Any]], Optional[list[str]]]（函数返回tuple）

测试结果：165 passed