acoder.py

#!/usr/bin/env python3
"""
ACoder - 工具脚本
用于项目操作、任务管理等核心功能

混合模式：
- 此脚本负责：创建目录、模板文件、JSON 读写、状态更新
- AI 负责：需求分析、任务拆分、代码编写、测试验证

路径自动检测：
- 自动查找当前目录及父目录下的 .acoder 目录
- 如果不存在，自动在当前目录创建
"""

import json
import sys
import os
import subprocess
from pathlib import Path
from datetime import datetime
from typing import Optional

# 配置
SKILL_PATH = Path.home() / ".claude" / "skills" / "acoder"
CONFIG_FILE = SKILL_PATH / "config.json"
TEMPLATES_PATH = SKILL_PATH / "templates"

# 自动检测的路径缓存
_detected_paths = None


def find_acoder_dir(start_path: Path = None) -> Path:
    """
    查找工作目录

    查找顺序：
    1. 当前工作目录下的 .acoder
    2. 逐级向上查找父目录下的 .acoder
    3. 查找现有的 projects/ 目录（兼容旧版）
    4. 如果都没找到，在当前目录创建 .acoder
    """
    if start_path is None:
        start_path = Path.cwd()

    # 1. 从当前目录开始查找 .acoder
    current = start_path
    while current != current.parent:
        candidate = current / ".acoder"
        if candidate.exists() and candidate.is_dir():
            return candidate
        current = current.parent

    # 检查根目录
    candidate = current / ".acoder"
    if candidate.exists() and candidate.is_dir():
        return candidate

    # 2. 查找现有的 projects/ 目录（兼容旧版结构）
    current = start_path
    while current != current.parent:
        projects_dir = current / "projects"
        if projects_dir.exists() and projects_dir.is_dir():
            # 检查是否有 project.json 文件（确认是 acoder 的 projects 目录）
            has_project = any(
                (p / "project.json").exists()
                for p in projects_dir.iterdir()
                if p.is_dir()
            )
            if has_project:
                # 返回父目录作为工作目录
                return current
        current = current.parent

    # 3. 没找到，在当前工作目录创建 .acoder
    acoder_dir = Path.cwd() / ".acoder"
    acoder_dir.mkdir(parents=True, exist_ok=True)
    (acoder_dir / "projects").mkdir(exist_ok=True)
    return acoder_dir


def detect_paths() -> dict:
    """
    自动检测项目路径

    工作目录为 .acoder/，在当前项目下创建

    返回:
        {
            "acoder_path": ".acoder 目录路径",
            "projects_path": "项目存储目录",
            "code_base_path": "代码库根目录"
        }
    """
    global _detected_paths

    if _detected_paths is not None:
        return _detected_paths

    # 先检查配置文件是否有硬编码路径
    config = load_config()

    if not config.get("auto_detect_paths", True):
        # 使用配置文件中的路径
        _detected_paths = {
            "acoder_path": Path(config.get("acoder_path", Path.cwd() / ".acoder")),
            "projects_path": Path(config.get("projects_path", Path.cwd() / ".acoder" / "projects")),
            "code_base_path": Path(config.get("code_base_path", Path.cwd())),
        }
        return _detected_paths

    # 自动检测：查找或创建 .acoder 目录
    start_path = Path.cwd()
    current = start_path

    # 1. 从当前目录开始向上查找 .acoder
    while current != current.parent:
        candidate = current / ".acoder"
        if candidate.exists() and candidate.is_dir():
            projects_dir = candidate / "projects"
            projects_dir.mkdir(exist_ok=True)
            _detected_paths = {
                "acoder_path": candidate,
                "projects_path": projects_dir,
                "code_base_path": current,
            }
            return _detected_paths
        current = current.parent

    # 2. 没找到，在当前工作目录创建 .acoder
    acoder_dir = Path.cwd() / ".acoder"
    acoder_dir.mkdir(parents=True, exist_ok=True)
    projects_dir = acoder_dir / "projects"
    projects_dir.mkdir(exist_ok=True)

    _detected_paths = {
        "acoder_path": acoder_dir,
        "projects_path": projects_dir,
        "code_base_path": Path.cwd(),
    }

    return _detected_paths


def load_config() -> dict:
    """加载配置"""
    if CONFIG_FILE.exists():
        with open(CONFIG_FILE) as f:
            return json.load(f)
    return {
        "auto_detect_paths": True,
        "auto_commit": True,
        "default_priority": "medium",
    }


def get_project_path(project_name: str) -> Path:
    """获取项目路径"""
    paths = detect_paths()
    return paths["projects_path"] / project_name


def project_exists(project_name: str) -> bool:
    """检查项目是否存在"""
    return get_project_path(project_name).exists()


def create_project(project_name: str, description: str = "", branch: str = None, create_branch: bool = False) -> dict:
    """创建新项目目录结构

    参数:
        project_name: 项目名
        description: 项目描述
        branch: 指定分支名（None 表示使用项目名作为分支名）
        create_branch: 是否创建分支（默认不创建）
    """
    project_path = get_project_path(project_name)

    if project_path.exists():
        return {"success": False, "error": f"项目 '{project_name}' 已存在"}

    # 分支处理逻辑
    branch_name = None
    branch_created = False
    code_base = get_code_base_path()

    # 获取当前分支
    try:
        result = subprocess.run(
            ["git", "branch", "--show-current"],
            cwd=code_base,
            capture_output=True,
            text=True
        )
        current_branch = result.stdout.strip()
    except:
        current_branch = "unknown"

    # 只有明确指定 create_branch=True 时才创建新分支
    if create_branch:
        branch_name = branch if branch else project_name
        try:
            subprocess.run(
                ["git", "checkout", "-b", branch_name],
                cwd=code_base,
                check=True,
                capture_output=True
            )
            branch_created = True
        except subprocess.CalledProcessError as e:
            return {"success": False, "error": f"创建分支失败: {e.stderr}"}
    else:
        # 不创建分支，使用当前分支
        branch_name = current_branch if current_branch else "main"

    # 创建目录结构
    (project_path / "logs").mkdir(parents=True)

    now = datetime.now().strftime("%Y-%m-%d %H:%M:%S")

    # 使用模板文件
    template_project = TEMPLATES_PATH / "project.json"

    # 创建 project.json
    if template_project.exists():
        with open(template_project) as f:
            project_json = json.load(f)
        project_json["id"] = project_name
        project_json["name"] = project_name
        project_json["status"] = "initialized"
        project_json["created_at"] = now
        project_json["updated_at"] = now
        project_json["description"] = description
        project_json["branch"] = branch_name
        project_json["session"] = {
            "phase": "initialized",
            "current_step": 0,
            "total_steps": 0,
            "current_task_id": None
        }
    else:
        project_json = {
            "id": project_name,
            "name": project_name,
            "status": "initialized",
            "created_at": now,
            "updated_at": now,
            "paused_at": None,
            "description": description,
            "target_path": "../../",
            "total_features": 0,
            "completed_features": 0,
            "branch": branch_name,
            "session": {
                "phase": "initialized",
                "current_step": 0,
                "total_steps": 0,
                "current_task_id": None
            }
        }
    with open(project_path / "project.json", "w") as f:
        json.dump(project_json, f, indent=2, ensure_ascii=False)

    # 创建 feature_list.md (Markdown 格式)
    feature_md_content = f"""# Feature List: {project_name}

**Created**: {now}
**Description**: {description}
**Branch**: {branch_name or 'N/A'}

---

## 任务列表

<!-- 任务将由 AI 逐个添加，每个任务包含完整的上下文信息 -->

---

## 统计

- 总任务数: 0
- 已完成: 0
- 进行中: 0
"""
    with open(project_path / "feature_list.md", "w") as f:
        f.write(feature_md_content)

    # 同时保留 JSON 格式用于程序化处理
    feature_json = {
        "features": [],
        "implementation_order": [],
        "phases": [],
        "metadata": {
            "project_name": project_name,
            "created_at": now,
            "description": description,
            "branch": branch_name,
        },
    }
    with open(project_path / "feature_list.json", "w") as f:
        json.dump(feature_json, f, indent=2, ensure_ascii=False)

    # 创建 progress.txt
    progress_content = f"""# Agent Progress Log

## Session 0 - Initialization
- Date: {now}
- Agent: Initializer
- Action: Project initialization

### Completed:
- Created project structure
- Created feature_list.json (empty - waiting for AI analysis)
- Created progress.txt

### Next Steps:
- AI will analyze requirements and populate feature_list.json
- Run /acoder code to start implementation

---
"""
    with open(project_path / "progress.txt", "w") as f:
        f.write(progress_content)

    # 创建 init.sh
    init_sh = """#!/bin/bash
# 项目初始化脚本
# 请根据项目需要修改此脚本

set -e

echo "初始化项目环境..."

# TODO: 添加项目特定的初始化命令
# 例如：
# - 安装依赖
# - 启动开发服务器
# - 运行测试

echo "初始化完成"
"""
    with open(project_path / "init.sh", "w") as f:
        f.write(init_sh)
    os.chmod(project_path / "init.sh", 0o755)

    return {
        "success": True,
        "path": str(project_path),
        "branch": branch_name,
        "branch_created": branch_created,
        "message": f"项目目录已创建" + (f"，分支: {branch_name}" if branch_name else ""),
    }


def update_session(project_name: str, phase: str = None, current_step: int = None,
                   total_steps: int = None, current_task_id: str = None) -> dict:
    """更新会话状态"""
    project_path = get_project_path(project_name)
    project_file = project_path / "project.json"

    if not project_file.exists():
        return {"success": False, "error": "project.json 不存在"}

    with open(project_file) as f:
        data = json.load(f)

    if "session" not in data:
        data["session"] = {}

    if phase is not None:
        data["session"]["phase"] = phase
    if current_step is not None:
        data["session"]["current_step"] = current_step
    if total_steps is not None:
        data["session"]["total_steps"] = total_steps
    if current_task_id is not None:
        data["session"]["current_task_id"] = current_task_id

    data["updated_at"] = datetime.now().strftime("%Y-%m-%d %H:%M:%S")

    with open(project_file, "w") as f:
        json.dump(data, f, indent=2, ensure_ascii=False)

    return {"success": True, "session": data["session"]}


def get_session(project_name: str) -> dict:
    """获取会话状态"""
    data = load_project(project_name)
    if not data.get("success"):
        return {"success": False, "error": data.get("error")}

    project = data.get("project", {})
    return {
        "success": True,
        "session": project.get("session", {
            "phase": "unknown",
            "current_step": 0,
            "total_steps": 0,
            "current_task_id": None
        })
    }


def get_phases_status(project_name: str) -> dict:
    """获取 Phases 状态（用于可视化显示）"""
    data = load_project(project_name)
    if not data.get("success"):
        return {"success": False, "error": data.get("error")}

    features = data.get("features", {}).get("features", [])
    phases_data = data.get("features", {}).get("phases", [])
    implementation_order = data.get("features", {}).get("implementation_order", [])

    # 如果没有 phases，按任务顺序生成默认 phases
    if not phases_data:
        phases_data = [{
            "id": "phase-1",
            "name": "Phase 1",
            "description": "实现阶段",
            "tasks": implementation_order,
            "status": "in_progress" if any(not f.get("passes") for f in features) else "completed"
        }]

    # 更新每个 phase 的状态
    feature_map = {f["id"]: f for f in features}
    phases_status = []
    for phase in phases_data:
        phase_tasks = phase.get("tasks", [])
        completed_in_phase = sum(1 for tid in phase_tasks if feature_map.get(tid, {}).get("passes", False))
        total_in_phase = len(phase_tasks)

        phase_status = {
            "id": phase["id"],
            "name": phase["name"],
            "description": phase.get("description", ""),
            "completed": completed_in_phase,
            "total": total_in_phase,
            "status": "completed" if completed_in_phase == total_in_phase and total_in_phase > 0 else
                      "in_progress" if completed_in_phase > 0 else "pending",
            "tasks": [
                {
                    "id": tid,
                    "description": feature_map.get(tid, {}).get("description", ""),
                    "passes": feature_map.get(tid, {}).get("passes", False)
                }
                for tid in phase_tasks
            ]
        }
        phases_status.append(phase_status)

    return {
        "success": True,
        "phases": phases_status,
        "total_tasks": len(features),
        "completed_tasks": sum(1 for f in features if f.get("passes", False))
    }


def load_project(project_name: str) -> dict:
    """加载项目信息"""
    project_path = get_project_path(project_name)

    if not project_path.exists():
        return {"success": False, "error": f"项目 '{project_name}' 不存在"}

    result = {"success": True, "path": str(project_path)}

    project_file = project_path / "project.json"
    if project_file.exists():
        with open(project_file) as f:
            result["project"] = json.load(f)

    feature_file = project_path / "feature_list.json"
    if feature_file.exists():
        with open(feature_file) as f:
            result["features"] = json.load(f)

    progress_file = project_path / "progress.txt"
    if progress_file.exists():
        result["progress"] = progress_file.read_text()

    return result


def get_next_task(project_name: str) -> Optional[dict]:
    """获取下一个待完成任务"""
    data = load_project(project_name)
    if not data.get("success"):
        return None

    features = data.get("features", {}).get("features", [])
    order = data.get("features", {}).get("implementation_order", [])

    feature_map = {f["id"]: f for f in features}

    # 按 implementation_order 找下一个可执行的任务
    for fid in order:
        if fid in feature_map and not feature_map[fid].get("passes", False):
            deps = feature_map[fid].get("dependencies", [])
            deps_ok = all(feature_map.get(d, {}).get("passes", False) for d in deps)
            if deps_ok:
                return feature_map[fid]

    # 如果没有 order，按顺序找
    for f in features:
        if not f.get("passes", False):
            deps = f.get("dependencies", [])
            deps_ok = all(
                any(x["id"] == d and x.get("passes", False) for x in features)
                for d in deps
            )
            if deps_ok:
                return f

    return None


def update_task_status(project_name: str, task_id: str, passes: bool) -> dict:
    """更新任务状态（同时更新 JSON 和 Markdown）"""
    project_path = get_project_path(project_name)
    feature_file = project_path / "feature_list.json"

    if not feature_file.exists():
        return {"success": False, "error": "feature_list.json 不存在"}

    with open(feature_file) as f:
        data = json.load(f)

    found = False
    for feature in data["features"]:
        if feature["id"] == task_id:
            feature["passes"] = passes
            feature["completed_at"] = datetime.now().strftime("%Y-%m-%d %H:%M:%S") if passes else None
            found = True
            break

    if not found:
        return {"success": False, "error": f"任务 '{task_id}' 不存在"}

    with open(feature_file, "w") as f:
        json.dump(data, f, indent=2, ensure_ascii=False)

    # 同步更新 Markdown 文件
    md_file = project_path / "feature_list.md"
    if md_file.exists():
        with open(md_file) as f:
            md_content = f.read()

        import re

        # 更新任务标题行的状态
        status_pattern = rf"(## {re.escape(task_id)}:.*?\n\n\*\*状态\*:) [^\n]+"
        new_status = "✅ 已完成" if passes else "⬜ 待完成"
        md_content = re.sub(status_pattern, rf"\1 {new_status}", md_content)

        # 更新完成时间
        if passes:
            time_pattern = rf"(## {re.escape(task_id)}:.*?\n\n\*\*状态\*.*?\n)"
            replacement = rf"\1**完成时间**: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}\n"
            md_content = re.sub(time_pattern, replacement, md_content, flags=re.DOTALL)

        # 更新统计
        completed = sum(1 for f in data["features"] if f.get("passes"))
        md_content = update_stats_in_md(md_content, len(data["features"]), completed)

        with open(md_file, "w") as f:
            f.write(md_content)

    # 更新 project.json
    project_file = project_path / "project.json"
    if project_file.exists():
        with open(project_file) as f:
            project_data = json.load(f)

        completed = sum(1 for f in data["features"] if f.get("passes"))
        project_data["completed_features"] = completed
        project_data["updated_at"] = datetime.now().strftime("%Y-%m-%d %H:%M:%S")

        with open(project_file, "w") as f:
            json.dump(project_data, f, indent=2, ensure_ascii=False)

    return {"success": True}


def add_task(
    project_name: str,
    task_id: str,
    description: str,
    category: str = "functional",
    priority: str = "medium",
    steps: list = None,
    files_affected: list = None,
    dependencies: list = None,
) -> dict:
    """添加任务"""
    project_path = get_project_path(project_name)
    feature_file = project_path / "feature_list.json"

    if not feature_file.exists():
        return {"success": False, "error": "feature_list.json 不存在"}

    with open(feature_file) as f:
        data = json.load(f)

    # 检查 ID 是否已存在
    if any(f["id"] == task_id for f in data["features"]):
        return {"success": False, "error": f"任务 ID '{task_id}' 已存在"}

    new_task = {
        "id": task_id,
        "category": category,
        "priority": priority,
        "description": description,
        "steps": steps or [],
        "files_affected": files_affected or [],
        "dependencies": dependencies or [],
        "passes": False,
        "completed_at": None,
    }

    data["features"].append(new_task)
    data["implementation_order"].append(task_id)

    with open(feature_file, "w") as f:
        json.dump(data, f, indent=2, ensure_ascii=False)

    return {"success": True, "task": new_task}


def list_projects() -> list:
    """列出所有项目"""
    paths = detect_paths()
    projects_path = paths["projects_path"]

    if not projects_path.exists():
        return []

    projects = []
    for project_dir in projects_path.iterdir():
        if project_dir.is_dir():
            project_file = project_dir / "project.json"
            feature_file = project_dir / "feature_list.json"

            project_info = {"name": project_dir.name, "path": str(project_dir)}

            if project_file.exists():
                try:
                    with open(project_file) as f:
                        project_info["project"] = json.load(f)
                except json.JSONDecodeError:
                    project_info["project_error"] = "Invalid JSON"

            if feature_file.exists():
                try:
                    with open(feature_file) as f:
                        feature_data = json.load(f)
                        features = feature_data.get("features", [])
                        total = len(features)
                        completed = sum(1 for f in features if f.get("passes", False))
                        project_info["progress"] = f"{completed}/{total}"
                except json.JSONDecodeError:
                    project_info["progress"] = "JSON Error"

            projects.append(project_info)

    return projects


def append_progress(project_name: str, content: str) -> dict:
    """追加进度记录"""
    project_path = get_project_path(project_name)
    progress_file = project_path / "progress.txt"

    if not progress_file.exists():
        return {"success": False, "error": "progress.txt 不存在"}

    with open(progress_file, "a") as f:
        f.write("\n" + content + "\n")

    return {"success": True}


def save_feature_list(project_name: str, feature_list: dict) -> dict:
    """
    保存完整的功能列表（AI 分析需求后调用此函数）

    这是混合模式的核心函数：
    - AI 负责分析需求、拆分任务
    - 调用此函数保存结果
    """
    project_path = get_project_path(project_name)
    feature_file = project_path / "feature_list.json"

    if not project_path.exists():
        return {"success": False, "error": f"项目 '{project_name}' 不存在"}

    # 验证格式
    if "features" not in feature_list:
        return {"success": False, "error": "feature_list 必须包含 'features' 字段"}

    # 确保 implementation_order 存在
    if "implementation_order" not in feature_list:
        feature_list["implementation_order"] = [f["id"] for f in feature_list["features"]]

    # 确保所有任务的 passes 为 false
    for feature in feature_list["features"]:
        feature["passes"] = False
        feature["completed_at"] = None

    # 更新 metadata
    if "metadata" not in feature_list:
        feature_list["metadata"] = {}
    feature_list["metadata"]["updated_at"] = datetime.now().strftime("%Y-%m-%d %H:%M:%S")

    with open(feature_file, "w") as f:
        json.dump(feature_list, f, indent=2, ensure_ascii=False)

    # 同时生成 Markdown 版本
    md_content = generate_feature_list_md(project_name, feature_list)
    with open(project_path / "feature_list.md", "w") as f:
        f.write(md_content)

    # 更新 project.json
    project_file = project_path / "project.json"
    if project_file.exists():
        with open(project_file) as f:
            project_data = json.load(f)

        project_data["total_features"] = len(feature_list["features"])
        project_data["completed_features"] = 0
        project_data["status"] = "ready"
        project_data["updated_at"] = datetime.now().strftime("%Y-%m-%d %H:%M:%S")

        with open(project_file, "w") as f:
            json.dump(project_data, f, indent=2, ensure_ascii=False)

    total = len(feature_list["features"])
    return {
        "success": True,
        "message": f"已保存 {total} 个任务",
        "total_features": total,
    }


def generate_feature_list_md(project_name: str, feature_list: dict) -> str:
    """生成 Markdown 格式的 feature_list"""
    metadata = feature_list.get("metadata", {})
    features = feature_list.get("features", [])
    phases = feature_list.get("phases", [])

    md = f"""# Feature List: {project_name}

**Created**: {metadata.get('created_at', 'N/A')}
**Description**: {metadata.get('description', 'N/A')}
**Branch**: {metadata.get('branch', 'N/A')}

---

"""

    if phases:
        md += "## Phases 概览\n\n"
        for phase in phases:
            md += f"### {phase.get('name', phase.get('id', 'Unknown'))}\n\n"
            md += f"{phase.get('description', '')}\n\n"
            for task_id in phase.get("tasks", []):
                task = next((f for f in features if f["id"] == task_id), None)
                if task:
                    status = "✅" if task.get("passes") else "⬜"
                    md += f"- {status} {task_id}: {task.get('title', task.get('description', 'No title'))}\n"
            md += "\n"
        md += "---\n\n"

    md += "## 任务详情\n\n"

    for feature in features:
        md += generate_task_md(feature)
        md += "\n---\n\n"

    # 统计
    completed = sum(1 for f in features if f.get("passes"))
    md += f"""## 统计

- 总任务数: {len(features)}
- 已完成: {completed}
- 进行中: {len(features) - completed}
"""

    return md


def generate_task_md(task: dict) -> str:
    """生成单个任务的 Markdown 内容"""
    task_id = task.get("id", "Unknown")
    title = task.get("title", task.get("description", "No title"))
    status = "✅ 已完成" if task.get("passes") else "⬜ 待完成"

    md = f"""## {task_id}: {title}

**状态**: {status}
"""

    if task.get("completed_at"):
        md += f"**完成时间**: {task['completed_at']}\n"

    md += "\n"

    # 背景
    if task.get("background"):
        md += f"""### 背景 (Background)

{task['background']}

"""

    # 需求
    if task.get("requirements"):
        md += f"""### 需求 (Requirements)

{task['requirements']}

"""

    # 技术设计
    if task.get("tech_design"):
        md += f"""### 技术设计 (Technical Design)

{task['tech_design']}

"""

    # 验收标准
    if task.get("acceptance_criteria"):
        md += f"""### 验收标准 (Acceptance Criteria)

{task['acceptance_criteria']}

"""

    # 影响文件
    if task.get("files_affected"):
        md += "### 影响文件 (Files Affected)\n\n"
        for f in task["files_affected"]:
            md += f"- `{f}`\n"
        md += "\n"

    # 依赖
    if task.get("dependencies"):
        md += "### 依赖 (Dependencies)\n\n"
        for d in task["dependencies"]:
            md += f"- {d}\n"
        md += "\n"

    return md


def add_task_md(
    project_name: str,
    task_id: str,
    title: str,
    background: str = "",
    requirements: str = "",
    tech_design: str = "",
    acceptance_criteria: str = "",
    files_affected: list = None,
    dependencies: list = None,
    priority: str = "medium",
) -> dict:
    """
    添加任务（Markdown 格式，包含完整上下文）

    这是新的推荐方式，每个任务包含：
    - background: 任务背景
    - requirements: 需求描述
    - tech_design: 技术设计
    - acceptance_criteria: 验收标准
    - files_affected: 影响的文件
    - dependencies: 依赖的任务

    所有字段都应该是自包含的，不应引用外部文档。
    """
    project_path = get_project_path(project_name)

    if not project_path.exists():
        return {"success": False, "error": f"项目 '{project_name}' 不存在"}

    # 读取现有 JSON
    feature_file = project_path / "feature_list.json"
    if feature_file.exists():
        with open(feature_file) as f:
            data = json.load(f)
    else:
        data = {"features": [], "implementation_order": [], "phases": [], "metadata": {}}

    # 检查 ID 是否已存在
    if any(f["id"] == task_id for f in data.get("features", [])):
        return {"success": False, "error": f"任务 ID '{task_id}' 已存在"}

    # 创建新任务
    new_task = {
        "id": task_id,
        "title": title,
        "description": title,  # 保持兼容性
        "background": background,
        "requirements": requirements,
        "tech_design": tech_design,
        "acceptance_criteria": acceptance_criteria,
        "files_affected": files_affected or [],
        "dependencies": dependencies or [],
        "priority": priority,
        "passes": False,
        "completed_at": None,
    }

    data["features"].append(new_task)
    data["implementation_order"].append(task_id)

    # 保存 JSON
    with open(feature_file, "w") as f:
        json.dump(data, f, indent=2, ensure_ascii=False)

    # 更新 Markdown 文件
    md_file = project_path / "feature_list.md"
    if md_file.exists():
        with open(md_file) as f:
            md_content = f.read()

        # 在最后一个 "## 任务" 之前插入新任务（保持正序）
        task_md = generate_task_md(new_task)
        marker = "## 统计"

        if marker in md_content:
            # 在统计部分之前插入新任务
            parts = md_content.rsplit(marker, 1)
            new_content = parts[0] + task_md + "\n---\n\n" + marker + parts[1]
        else:
            # 没有统计部分，直接追加
            new_content = md_content + "\n---\n\n" + task_md + "\n"

        # 更新统计
        new_content = update_stats_in_md(new_content, len(data["features"]), 0)

        with open(md_file, "w") as f:
            f.write(new_content)

    # 更新 project.json
    project_file = project_path / "project.json"
    if project_file.exists():
        with open(project_file) as f:
            project_data = json.load(f)
        project_data["total_features"] = len(data["features"])
        project_data["updated_at"] = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
        with open(project_file, "w") as f:
            json.dump(project_data, f, indent=2, ensure_ascii=False)

    return {"success": True, "task": new_task}


def update_stats_in_md(md_content: str, total: int, completed: int) -> str:
    """更新 Markdown 中的统计信息"""
    import re
    stats_pattern = r"## 统计\s*\n\s*- 总任务数: \d+\s*\n\s*- 已完成: \d+\s*\n\s*- 进行中: \d+"
    new_stats = f"""## 统计

- 总任务数: {total}
- 已完成: {completed}
- 进行中: {total - completed}"""

    return re.sub(stats_pattern, new_stats, md_content)


def get_task_full_context(project_name: str, task_id: str) -> Optional[str]:
    """
    获取任务的完整上下文（Markdown 格式）

    用于执行任务时提供完整上下文给子代理
    """
    project_path = get_project_path(project_name)
    md_file = project_path / "feature_list.md"

    if not md_file.exists():
        return None

    with open(md_file) as f:
        content = f.read()

    # 提取指定任务的内容
    import re
    pattern = rf"## {re.escape(task_id)}:.*?(?=\n---\n|## [A-Z]+-\d+:|$)"
    match = re.search(pattern, content, re.DOTALL)

    if match:
        return match.group(0).strip()

    return None


def update_project_status(project_name: str, status: str) -> dict:
    """更新项目状态"""
    project_path = get_project_path(project_name)
    project_file = project_path / "project.json"

    if not project_file.exists():
        return {"success": False, "error": "project.json 不存在"}

    valid_statuses = ["initialized", "ready", "running", "paused", "completed", "blocked"]
    if status not in valid_statuses:
        return {"success": False, "error": f"无效状态: {status}，有效值: {valid_statuses}"}

    with open(project_file) as f:
        data = json.load(f)

    data["status"] = status
    data["updated_at"] = datetime.now().strftime("%Y-%m-%d %H:%M:%S")

    if status == "paused":
        data["paused_at"] = datetime.now().strftime("%Y-%m-%d %H:%M:%S")

    with open(project_file, "w") as f:
        json.dump(data, f, indent=2, ensure_ascii=False)

    return {"success": True, "status": status}


def get_code_base_path() -> Path:
    """获取代码库根目录路径"""
    paths = detect_paths()
    return paths["code_base_path"]


def get_task_details(project_name: str, task_id: str) -> Optional[dict]:
    """获取任务详情"""
    data = load_project(project_name)
    if not data.get("success"):
        return None

    features = data.get("features", {}).get("features", [])
    for feature in features:
        if feature["id"] == task_id:
            return feature

    return None


def get_project_progress(project_name: str) -> dict:
    """获取项目进度统计"""
    data = load_project(project_name)
    if not data.get("success"):
        return {"success": False, "error": data.get("error")}

    features = data.get("features", {}).get("features", [])
    total = len(features)
    completed = sum(1 for f in features if f.get("passes", False))
    pending = total - completed

    # 按优先级统计
    by_priority = {"high": 0, "medium": 0, "low": 0}
    for f in features:
        if not f.get("passes", False):
            priority = f.get("priority", "medium")
            if priority in by_priority:
                by_priority[priority] += 1

    # 按类别统计
    by_category = {}
    for f in features:
        if not f.get("passes", False):
            category = f.get("category", "functional")
            by_category[category] = by_category.get(category, 0) + 1

    return {
        "success": True,
        "total": total,
        "completed": completed,
        "pending": pending,
        "percentage": round(completed / total * 100, 1) if total > 0 else 0,
        "by_priority": by_priority,
        "by_category": by_category,
    }


def is_project_complete(project_name: str) -> dict:
    """检查项目是否所有任务都已完成"""
    progress = get_project_progress(project_name)
    if not progress.get("success"):
        return progress

    return {
        "success": True,
        "complete": progress["pending"] == 0,
        "pending_count": progress["pending"],
        "total": progress["total"],
    }


def get_all_pending_tasks(project_name: str) -> list:
    """获取所有待完成任务（按执行顺序）"""
    data = load_project(project_name)
    if not data.get("success"):
        return []

    features = data.get("features", {}).get("features", [])
    order = data.get("features", {}).get("implementation_order", [])

    feature_map = {f["id"]: f for f in features}
    pending = []

    # 按 implementation_order 收集待完成任务
    for fid in order:
        if fid in feature_map and not feature_map[fid].get("passes", False):
            pending.append(feature_map[fid])

    return pending


def generate_session_progress_content(
    task_id: str,
    task_desc: str,
    files_changed: list,
    test_results: list,
    next_task_id: str = None,
) -> str:
    """生成会话进度内容模板"""
    now = datetime.now().strftime("%Y-%m-%d %H:%M:%S")

    content = f"""
## Session - Coding
- Date: {now}
- Agent: Coder
- Feature: {task_id} - {task_desc}

### Files Changed:
"""
    for f in files_changed:
        content += f"- {f}\n"

    content += "\n### Test Results:\n"
    for i, result in enumerate(test_results, 1):
        status = "✅ PASS" if result.get("pass") else "❌ FAIL"
        content += f"- Step {i}: {status} - {result.get('description', '')}\n"

    content += "\n### Next Steps:\n"
    if next_task_id:
        content += f"- 继续实现下一个功能: {next_task_id}\n"
    else:
        content += "- 所有任务已完成！\n"

    content += "\n---\n"

    return content


def main():
    """命令行入口"""
    if len(sys.argv) < 2:
        print_help()
        sys.exit(1)

    command = sys.argv[1]

    if command == "create":
        if len(sys.argv) < 3:
            print("用法: acoder.py create <项目名> [描述] [--branch [分支名]]")
            sys.exit(1)
        project_name = sys.argv[2]
        description = ""
        branch = None
        create_branch = False

        # 解析参数
        args = sys.argv[3:]
        i = 0
        while i < len(args):
            if args[i] == "--branch":
                create_branch = True
                # 检查下一个参数是否是分支名（不是以 -- 开头）
                if i + 1 < len(args) and not args[i + 1].startswith("--"):
                    branch = args[i + 1]
                    i += 2
                else:
                    # 没有指定分支名，使用项目名
                    i += 1
            else:
                description = args[i]
                i += 1

        result = create_project(project_name, description, branch, create_branch)
        print(json.dumps(result, ensure_ascii=False, indent=2))

    elif command == "load":
        if len(sys.argv) < 3:
            print("用法: acoder.py load <项目名>")
            sys.exit(1)
        result = load_project(sys.argv[2])
        print(json.dumps(result, ensure_ascii=False, indent=2))

    elif command == "next-task":
        if len(sys.argv) < 3:
            print("用法: acoder.py next-task <项目名>")
            sys.exit(1)
        task = get_next_task(sys.argv[2])
        if task:
            print(json.dumps(task, ensure_ascii=False, indent=2))
        else:
            print(json.dumps({"success": False, "error": "没有待完成任务"}))

    elif command == "update-task":
        if len(sys.argv) < 5:
            print("用法: acoder.py update-task <项目名> <任务ID> <true|false>")
            sys.exit(1)
        passes = sys.argv[4].lower() == "true"
        result = update_task_status(sys.argv[2], sys.argv[3], passes)
        print(json.dumps(result, ensure_ascii=False, indent=2))

    elif command == "add-task":
        if len(sys.argv) < 5:
            print("用法: acoder.py add-task <项目名> <任务ID> <描述> [优先级]")
            sys.exit(1)
        priority = sys.argv[5] if len(sys.argv) > 5 else "medium"
        result = add_task(
            sys.argv[2], sys.argv[3], sys.argv[4], priority=priority
        )
        print(json.dumps(result, ensure_ascii=False, indent=2))

    elif command == "list":
        projects = list_projects()
        print(json.dumps(projects, ensure_ascii=False, indent=2))

    elif command == "progress":
        if len(sys.argv) < 4:
            print("用法: acoder.py progress <项目名> <内容>")
            sys.exit(1)
        result = append_progress(sys.argv[2], sys.argv[3])
        print(json.dumps(result, ensure_ascii=False, indent=2))

    elif command == "save-features":
        if len(sys.argv) < 4:
            print("用法: acoder.py save-features <项目名> <JSON字符串>")
            sys.exit(1)
        try:
            feature_list = json.loads(sys.argv[3])
        except json.JSONDecodeError as e:
            print(json.dumps({"success": False, "error": f"JSON 解析错误: {e}"}))
            sys.exit(1)
        result = save_feature_list(sys.argv[2], feature_list)
        print(json.dumps(result, ensure_ascii=False, indent=2))

    elif command == "update-status":
        if len(sys.argv) < 4:
            print("用法: acoder.py update-status <项目名> <状态>")
            sys.exit(1)
        result = update_project_status(sys.argv[2], sys.argv[3])
        print(json.dumps(result, ensure_ascii=False, indent=2))

    elif command == "task-details":
        if len(sys.argv) < 4:
            print("用法: acoder.py task-details <项目名> <任务ID>")
            sys.exit(1)
        task = get_task_details(sys.argv[2], sys.argv[3])
        if task:
            print(json.dumps(task, ensure_ascii=False, indent=2))
        else:
            print(json.dumps({"success": False, "error": "任务不存在"}))

    elif command == "project-progress":
        if len(sys.argv) < 3:
            print("用法: acoder.py project-progress <项目名>")
            sys.exit(1)
        result = get_project_progress(sys.argv[2])
        print(json.dumps(result, ensure_ascii=False, indent=2))

    elif command == "is-complete":
        if len(sys.argv) < 3:
            print("用法: acoder.py is-complete <项目名>")
            sys.exit(1)
        result = is_project_complete(sys.argv[2])
        print(json.dumps(result, ensure_ascii=False, indent=2))

    elif command == "all-pending":
        if len(sys.argv) < 3:
            print("用法: acoder.py all-pending <项目名>")
            sys.exit(1)
        tasks = get_all_pending_tasks(sys.argv[2])
        print(json.dumps(tasks, ensure_ascii=False, indent=2))

    elif command == "code-base":
        paths = detect_paths()
        print(json.dumps({
            "acoder_path": str(paths["acoder_path"]),
            "projects_path": str(paths["projects_path"]),
            "code_base_path": str(paths["code_base_path"]),
        }, ensure_ascii=False, indent=2))

    elif command == "init-dir":
        """初始化当前目录为 acoder 工作目录"""
        paths = detect_paths()
        print(json.dumps({
            "success": True,
            "message": "已初始化 .acoder 目录",
            "paths": {
                "acoder_path": str(paths["acoder_path"]),
                "projects_path": str(paths["projects_path"]),
                "code_base_path": str(paths["code_base_path"]),
            }
        }, ensure_ascii=False, indent=2))

    elif command == "session":
        """会话状态管理"""
        if len(sys.argv) < 3:
            print("用法: acoder.py session <项目名> [phase] [step] [total]")
            sys.exit(1)
        project_name = sys.argv[2]
        if len(sys.argv) == 3:
            result = get_session(project_name)
        else:
            phase = sys.argv[3] if len(sys.argv) > 3 else None
            step = int(sys.argv[4]) if len(sys.argv) > 4 else None
            total = int(sys.argv[5]) if len(sys.argv) > 5 else None
            result = update_session(project_name, phase, step, total)
        print(json.dumps(result, ensure_ascii=False, indent=2))

    elif command == "phases":
        """获取 phases 状态"""
        if len(sys.argv) < 3:
            print("用法: acoder.py phases <项目名>")
            sys.exit(1)
        result = get_phases_status(sys.argv[2])
        print(json.dumps(result, ensure_ascii=False, indent=2))

    elif command == "add-task-md":
        """添加任务（Markdown 格式，包含完整上下文）"""
        if len(sys.argv) < 5:
            print("用法: acoder.py add-task-md <项目名> <任务ID> <标题> --bg <背景> --req <需求> --tech <技术设计> --accept <验收标准> --files <文件列表>")
            sys.exit(1)
        project_name = sys.argv[2]
        task_id = sys.argv[3]
        title = sys.argv[4]

        # 解析可选参数
        background = ""
        requirements = ""
        tech_design = ""
        acceptance_criteria = ""
        files_affected = []

        args = sys.argv[5:]
        i = 0
        while i < len(args):
            if args[i] == "--bg" and i + 1 < len(args):
                background = args[i + 1]
                i += 2
            elif args[i] == "--req" and i + 1 < len(args):
                requirements = args[i + 1]
                i += 2
            elif args[i] == "--tech" and i + 1 < len(args):
                tech_design = args[i + 1]
                i += 2
            elif args[i] == "--accept" and i + 1 < len(args):
                acceptance_criteria = args[i + 1]
                i += 2
            elif args[i] == "--files" and i + 1 < len(args):
                files_affected = args[i + 1].split(",")
                i += 2
            else:
                i += 1

        result = add_task_md(
            project_name, task_id, title,
            background=background,
            requirements=requirements,
            tech_design=tech_design,
            acceptance_criteria=acceptance_criteria,
            files_affected=files_affected
        )
        print(json.dumps(result, ensure_ascii=False, indent=2))

    elif command == "task-context":
        """获取任务的完整上下文（Markdown 格式）"""
        if len(sys.argv) < 4:
            print("用法: acoder.py task-context <项目名> <任务ID>")
            sys.exit(1)
        context = get_task_full_context(sys.argv[2], sys.argv[3])
        if context:
            print(context)
        else:
            print(json.dumps({"success": False, "error": "任务不存在或 feature_list.md 不存在"}))

    elif command == "help":
        print_help()

    else:
        print(f"未知命令: {command}")
        print_help()
        sys.exit(1)


def print_help():
    """打印帮助信息"""
    help_text = """
ACoder - 工具脚本 v3.0 (Markdown 支持)

路径自动检测:
  脚本会自动查找当前目录及父目录下的 .acoder 目录
  如果不存在，会在当前目录自动创建

命令列表:
  init-dir                        初始化当前目录为工作目录
  code-base                       显示当前检测到的路径

  create <项目名> [描述] [--branch [分支名]]
                                  创建新项目目录结构
                                  默认不创建分支，使用当前分支
                                  --branch: 创建新分支（可选指定分支名）
                                  不指定分支名则使用项目名作为分支名

  load <项目名>                    加载项目信息
  list                             列出所有项目

  next-task <项目名>               获取下一个待完成任务
  all-pending <项目名>             获取所有待完成任务
  update-task <项目名> <任务ID> <true|false>  更新任务状态
  save-features <项目名> <JSON>    保存 AI 生成的功能列表
  update-status <项目名> <状态>    更新项目状态
  task-details <项目名> <任务ID>   获取任务详情 (JSON)
  project-progress <项目名>        获取项目进度统计
  is-complete <项目名>             检查项目是否已完成
  progress <项目名> <内容>         追加进度记录

  === Markdown 任务管理 (推荐) ===
  add-task-md <项目名> <任务ID> <标题> [--bg 背景] [--req 需求] [--tech 技术设计] [--accept 验收标准] [--files 文件列表]
                                  添加任务（Markdown 格式，包含完整上下文）
  task-context <项目名> <任务ID>   获取任务的完整上下文（Markdown 格式）

  === 会话管理 ===
  session <项目名>                 获取会话状态
  session <项目名> <phase> [step] [total]  更新会话状态
  phases <项目名>                  获取 phases 状态（可视化用）

  help                             显示此帮助信息

示例:
  # 创建项目（默认不创建分支，使用当前分支）
  python3 acoder.py create my-project "项目描述"

  # 创建项目并创建新分支（使用项目名作为分支名）
  python3 acoder.py create my-project "项目描述" --branch

  # 创建项目并创建自定义分支名
  python3 acoder.py create my-project "项目描述" --branch feature-login

  # 添加任务（Markdown 格式）
  python3 acoder.py add-task-md my-project TASK-001 "创建用户模型" \\
    --bg "用户认证系统需要持久化的用户数据模型" \\
    --req "用户模型必须包含 id, email, password_hash 字段" \\
    --tech "使用 SQLAlchemy ORM，文件位置: src/models/user.py" \\
    --accept "模型定义完成，单元测试通过" \\
    --files "src/models/user.py,src/models/__init__.py"

  # 获取任务完整上下文
  python3 acoder.py task-context my-project TASK-001
"""
    print(help_text)


if __name__ == "__main__":
    main()