feat: add type annotations to all 117 functions across 14 modules (#7)

- 100% coverage: all function parameters and return values annotated
- Add  to all modules that need it
- Python 3.9+ compatible: use Optional[X] not X | None, list[str] not List[str]
- Include nested functions (_run_one, parse_and_log, _on_interrupt, etc.)
- 163 tests pass with no regressions

Closes #7

Author: jinsongwang

agent_go/api.py

@@ -2,6 +2,7 @@
 from concurrent.futures import ThreadPoolExecutor, as_completed
 from pathlib import Path
 from datetime import datetime
+from typing import Any, Optional
 
 from .config import get_api_key, log_event, DECOMPOSE_RULES, AGENT_GO_DIR
 from .git_utils import analyze_project, get_git_info, get_resource_map
@@ -15,7 +16,7 @@
     "list_cache_entries", "clean_expired_cache",
 ]
 
-def call_api(config, messages, logger):
+def call_api(config: dict[str, Any], messages: list[dict[str, Any]], logger: logging.Logger) -> str:
     api_cfg = config["plan_api"]
     provider = api_cfg.get("provider", "anthropic")
     base_url = api_cfg["base_url"]
@@ -94,7 +95,7 @@ def call_api(config, messages, logger):
         })
         raise RuntimeError(f"连接超时或 IO 错误 ({provider}): {e}") from e
 
-def generate_plan(task, repo, config, logger, supplement="", reference_docs="", iteration=1, skill_context="", no_cache=False) -> dict:
+def generate_plan(task: str, repo: Path, config: dict[str, Any], logger: logging.Logger, supplement: str = "", reference_docs: str = "", iteration: int = 1, skill_context: str = "", no_cache: bool = False) -> dict[str, Any]:
     plan_start = time.time()
     logger.info("[PLAN] ═══ PLAN MODE ═══")
     logger.info(f"[PLAN]  第 {iteration} 次生成")
@@ -247,7 +248,7 @@ def generate_plan(task, repo, config, logger, supplement="", reference_docs="",
         save_cached_plan(cache_key, plan, task, repo, config)
     return plan
 
-def decompose_fallback(task, repo, config, logger):
+def decompose_fallback(task: str, repo: Path, config: dict[str, Any], logger: logging.Logger) -> list[dict[str, Any]]:
     logger.warning("Plan Mode 失败，降级")
     local_url = config.get("fallback", {}).get("local_model_url", "http://localhost:8000/v1/chat/completions")
     local_name = config.get("fallback", {}).get("local_model_name", "qwen")
@@ -284,13 +285,13 @@ def decompose_fallback(task, repo, config, logger):
 # Plan Cache
 # ═══════════════════════════════════════════════════════════════
 
-def _cache_dir():
+def _cache_dir() -> Path:
     d = AGENT_GO_DIR / "cache" / "plans"
     d.mkdir(parents=True, exist_ok=True)
     return d
 
 
-def get_cache_key(task, repo):
+def get_cache_key(task: str, repo: Path) -> str:
     """SHA256(task + project_files[0:100] + remote + branch)。"""
     project_files = analyze_project(repo)
     git_info = get_git_info(repo)
@@ -304,7 +305,7 @@ def get_cache_key(task, repo):
     return hashlib.sha256("|".join(key_parts).encode()).hexdigest()
 
 
-def load_cached_plan(cache_key, config, logger):
+def load_cached_plan(cache_key: str, config: dict[str, Any], logger: logging.Logger) -> Optional[dict[str, Any]]:
     cache_dir = _cache_dir()
     cache_file = cache_dir / cache_key[:2] / f"{cache_key}.json"
     if not cache_file.exists():
@@ -343,7 +344,7 @@ def load_cached_plan(cache_key, config, logger):
     return plan
 
 
-def save_cached_plan(cache_key, plan, task, repo, config):
+def save_cached_plan(cache_key: str, plan: dict[str, Any], task: str, repo: Path, config: dict[str, Any]) -> None:
     cache_cfg = config.get("cache", {})
     if not cache_cfg.get("enabled", True):
         return
@@ -367,7 +368,7 @@ def save_cached_plan(cache_key, plan, task, repo, config):
         json.dumps(entry, indent=2, ensure_ascii=False), encoding="utf-8")
 
 
-def _format_age(iso_str):
+def _format_age(iso_str: str) -> str:
     try:
         age = time.time() - datetime.strptime(iso_str, "%Y-%m-%dT%H:%M:%S").timestamp()
         if age < 3600:
@@ -379,7 +380,7 @@ def _format_age(iso_str):
         return "?"
 
 
-def list_cache_entries():
+def list_cache_entries() -> list[dict[str, Any]]:
     entries = []
     cache_dir = _cache_dir()
     for subdir in sorted(cache_dir.glob("*")):
@@ -393,7 +394,7 @@ def list_cache_entries():
     return sorted(entries, key=lambda e: e.get("meta", {}).get("created_at", ""), reverse=True)
 
 
-def clean_expired_cache(config):
+def clean_expired_cache(config: dict[str, Any]) -> int:
     ttl = config.get("cache", {}).get("plan_ttl", 86400)
     now = time.time()
     removed = 0

agent_go/cli.py

@@ -2,6 +2,7 @@
 from concurrent.futures import ThreadPoolExecutor, as_completed
 from pathlib import Path
 from datetime import datetime
+from typing import Any, Optional
 
 from .config import load_config, safe_input, setup_logger, AGENT_GO_DIR
 from .api import generate_plan, decompose_fallback
@@ -19,7 +20,7 @@
     "cmd_status", "cmd_config", "cmd_clean", "cmd_pr", "cmd_review",
 ]
 
-def cmd_run():
+def cmd_run() -> None:
     # 解析参数
     repo_idx = 2
     task_idx = 3
@@ -249,7 +250,7 @@ def cmd_run():
 
     _run_pipeline(confirmed, repo, task_dir, logger, config, headless, parallel, issue_ref, meta, remote_url=remote_url)
 
-def cmd_resume():
+def cmd_resume() -> None:
     """恢复被中断的任务。"""
     if len(sys.argv) < 3:
         print("Usage: agent_go resume <task-id> [--yes] [--headless] [--parallel N] [--remote <url>]")
@@ -329,7 +330,7 @@ def cmd_resume():
     _run_pipeline(confirmed, repo, task_dir, logger, config, headless, parallel, issue_ref, meta,
                   worktree_map, results_map, completed_ids, remote_url=remote_url)
 
-def cmd_list():
+def cmd_list() -> None:
     tasks = sorted(AGENT_GO_DIR.glob("task-*"))
     if not tasks:
         print("暂无任务")
@@ -346,7 +347,7 @@ def cmd_list():
         docs = ",".join(meta.get("reference_docs", []))[:15]
         print(f"{t.name:<25} {icon} {status:<10} {len(meta.get('subtasks',[])):<8} {docs:<12} {meta.get('task','')[:30]}")
 
-def cmd_show():
+def cmd_show() -> None:
     if len(sys.argv) < 3:
         print("Usage: agent_go show <task-id>")
         sys.exit(1)
@@ -382,7 +383,7 @@ def cmd_show():
         if r:
             print(f"       📊 {r['summary']}")
 
-def cmd_review():
+def cmd_review() -> None:
     """代码审查：使用 Claude 审查项目变更。"""
     if len(sys.argv) < 3:
         print("Usage: agent_go review <repo-path> [--pr <N>] [--yes]")
@@ -415,7 +416,7 @@ def cmd_review():
         subprocess.run(["claude", str(repo)])
 
 
-def cmd_pr():
+def cmd_pr() -> None:
     """根据已完成任务的 meta.json + git log 生成 PR 描述。"""
     if len(sys.argv) < 3:
         print("Usage: agent_go pr <task-id> [--offline]")
@@ -481,20 +482,20 @@ def cmd_pr():
             print(f"PR 描述已备份到 {task_dir}/PR.md")
         os.unlink(pr_file)
 
-def cmd_status():
+def cmd_status() -> None:
     """实时监控所有任务状态。默认 TUI 模式。--no-tui 回退文本模式。"""
     if "--no-tui" in sys.argv:
         _cmd_status_text()
     else:
         cmd_status_tui()
 
 
-def _cmd_status_text():
+def _cmd_status_text() -> None:
     """文本模式（原有实现）。--watch 持续刷新，--verbose 显示 Claude 事件。"""
     watch = "--watch" in sys.argv or "-w" in sys.argv
     verbose = "--verbose" in sys.argv or "-v" in sys.argv
 
-    def _get_task_tail_lines(log_path, count=2):
+    def _get_task_tail_lines(log_path: Path, count: int = 2) -> list[str]:
         """从执行日志尾部提取最后 count 条 Claude 事件。"""
         if not log_path.exists():
             return []
@@ -506,7 +507,7 @@ def _get_task_tail_lines(log_path, count=2):
                         or "[tool_result]" in l or "[result]" in l]
         return claude_lines[-count:]
 
-    def _get_task_status(task_dir):
+    def _get_task_status(task_dir: Path) -> Optional[dict[str, Any]]:
         meta_path = task_dir / "meta.json"
         if not meta_path.exists():
             return None
@@ -599,11 +600,11 @@ def _get_task_status(task_dir):
             break
         time.sleep(5)
 
-def cmd_config():
+def cmd_config() -> None:
     config = load_config()
     print(json.dumps(config, indent=2, ensure_ascii=False))
 
-def cmd_clean():
+def cmd_clean() -> None:
     import shutil as _shutil
     tasks = sorted(AGENT_GO_DIR.glob("task-*"))
     if not tasks:
@@ -647,7 +648,7 @@ def cmd_clean():
     else:
         print("已取消")
 
-def cmd_skills():
+def cmd_skills() -> None:
     """列出所有可用的 Skill。"""
     skills = list_skills()
     if not skills:
@@ -661,7 +662,7 @@ def cmd_skills():
         print(f"  {s['name']:<30} {desc}")
     print("─" * 55)
 
-def cmd_cache():
+def cmd_cache() -> None:
     """Plan 缓存管理。"""
     from .api import list_cache_entries, clean_expired_cache
 
@@ -708,7 +709,7 @@ def cmd_cache():
         print(f"未知子命令: {sub}。可用: list, clean, clear, stats")
 
 
-def _cache_size():
+def _cache_size() -> str:
     from .api import _cache_dir
     d = _cache_dir()
     total = 0
@@ -721,7 +722,7 @@ def _cache_size():
     return f"{total / 1024 / 1024:.1f}MB"
 
 
-def cmd_agents():
+def cmd_agents() -> None:
     """列出所有可用的 Agent 类型。"""
     agents = list_agent_types()
     print(f"\n🤖 Agent 类型 ({len(agents)} 种)")
@@ -732,7 +733,7 @@ def cmd_agents():
         print(f"  {a['type']:<25} [{src}] {desc}")
     print("─" * 55)
 
-def main():
+def main() -> None:
     try:
         cmd = sys.argv[1] if len(sys.argv) > 1 else "help"
         if cmd == "run": cmd_run()

agent_go/config.py

@@ -2,6 +2,7 @@
 from concurrent.futures import ThreadPoolExecutor, as_completed
 from pathlib import Path
 from datetime import datetime
+from typing import Any
 
 __all__ = [
     "AGENT_GO_DIR", "CONFIG_PATH", "DEFAULT_CONFIG", "DECOMPOSE_RULES",
@@ -66,15 +67,15 @@
     },
 ]
 
-def safe_input(prompt=""):
+def safe_input(prompt: str = "") -> str:
     """包装 input()，在非交互模式下返回空字符串（触发默认确认路径）。"""
     try:
         return input(prompt)
     except EOFError:
         print()
         return ""
 
-def load_config():
+def load_config() -> dict[str, Any]:
     if CONFIG_PATH.exists():
         saved = json.loads(CONFIG_PATH.read_text(encoding="utf-8"))
         merged = json.loads(json.dumps(DEFAULT_CONFIG))  # deep copy
@@ -89,10 +90,10 @@ def load_config():
     print(f"⚙️  已创建默认配置: {CONFIG_PATH}")
     return DEFAULT_CONFIG
 
-def get_api_key(config):
+def get_api_key(config: dict[str, Any]) -> str:
     return os.environ.get("AGENT_GO_API_KEY", "") or config.get("plan_api", {}).get("api_key", "")
 
-def setup_logger(task_id, task_dir):
+def setup_logger(task_id: str, task_dir: Path) -> logging.Logger:
     logger = logging.getLogger(f"agent_go.{task_id}")
     logger.setLevel(logging.DEBUG)
     for h in list(logger.handlers):
@@ -108,5 +109,5 @@ def setup_logger(task_id, task_dir):
     logger.addHandler(ch)
     return logger
 
-def log_event(logger, event, data):
+def log_event(logger: logging.Logger, event: str, data: dict[str, Any]) -> None:
     logger.debug(json.dumps({"timestamp": datetime.now().isoformat(), "event": event, **data}, ensure_ascii=False))