paperfit-cli 1.0.0

package/scripts/state_manager.py

@@ -0,0 +1,352 @@
+#!/usr/bin/env python3
+"""
+PaperFit 状态管理器
+
+管理 VTO 闭环中的状态持久化，包括读取、更新、备份和归档。
+状态文件 state.json 记录了当前任务的所有关键信息，支持中断恢复和多轮迭代。
+
+用法:
+    python state_manager.py init <main_tex> [--task <type>] [--target-pages <n>]
+    python state_manager.py get <key>
+    python state_manager.py set <key> <value>
+    python state_manager.py update "<json_patch>"
+    python state_manager.py next-round
+    python state_manager.py archive
+    python state_manager.py show
+"""
+
+import os
+import json
+import shutil
+import argparse
+import sys
+from pathlib import Path
+from datetime import datetime
+from typing import Any, Dict, Optional
+
+
+class StateManager:
+    """状态管理器"""
+
+    DEFAULT_STATE_PATH = "data/state.json"
+    BACKUP_DIR = "data/backups"
+    ARCHIVE_DIR = "data/archives"
+    CASE_DIR = "data/benchmarks/case"  # Benchmark case directory
+
+    def __init__(self, state_path: str = DEFAULT_STATE_PATH):
+        self.state_path = Path(state_path)
+        self.backup_dir = self.state_path.parent / "backups"
+        self.archive_dir = self.state_path.parent / "archives"
+        self.case_dir = self.state_path.parent / "benchmarks" / "case"
+        self.state: Dict[str, Any] = {}
+
+    def init_state(
+        self,
+        main_tex: str,
+        task_type: str = "full_vto",
+        target_pages: Optional[int] = None,
+        template: Optional[str] = None,
+        strict_mode: bool = False,
+        max_rounds: int = 10
+    ) -> Dict[str, Any]:
+        """初始化新任务的状态文件"""
+        self.backup_dir.mkdir(parents=True, exist_ok=True)
+        self.archive_dir.mkdir(parents=True, exist_ok=True)
+
+        self.state = {
+            "project": "PaperFit",
+            "version": "1.0",
+            "created_at": datetime.now().isoformat(),
+            "updated_at": datetime.now().isoformat(),
+            "main_tex": main_tex,
+            "task": {
+                "type": task_type,
+                "target_pages": target_pages,
+                "template": template,
+                "strict_mode": strict_mode
+            },
+            "current_round": 0,
+            "max_rounds": max_rounds,
+            "status": "INITIALIZED",
+            "compile_success": None,
+            "page_images_rendered": False,
+            "defect_summary": {
+                "initial_total": 0,
+                "resolved": 0,
+                "remaining": 0
+            },
+            "agents_this_round": [],
+            "last_gatekeeper_decision": None,
+            "next_actions": [],
+            "history": []
+        }
+
+        self._save()
+        return self.state
+
+    def load(self) -> Dict[str, Any]:
+        """加载当前状态"""
+        if not self.state_path.exists():
+            raise FileNotFoundError(f"State file not found: {self.state_path}")
+
+        with open(self.state_path, 'r', encoding='utf-8') as f:
+            self.state = json.load(f)
+
+        return self.state
+
+    def save(self) -> None:
+        """保存状态（自动备份旧版本）"""
+        if self.state_path.exists():
+            self._backup()
+        self._save()
+
+    def _save(self) -> None:
+        """内部保存方法"""
+        self.state["updated_at"] = datetime.now().isoformat()
+        self.state_path.parent.mkdir(parents=True, exist_ok=True)
+
+        with open(self.state_path, 'w', encoding='utf-8') as f:
+            json.dump(self.state, f, indent=2, ensure_ascii=False)
+
+    def _backup(self) -> None:
+        """备份当前状态文件和 case 目录"""
+        if not self.state_path.exists():
+            return
+
+        timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+
+        # 备份状态文件
+        backup_name = f"state_{timestamp}.json"
+        backup_path = self.backup_dir / backup_name
+        shutil.copy2(self.state_path, backup_path)
+
+        # 备份 case 目录（如果存在）
+        if self.case_dir.exists():
+            case_backup_name = f"case_{timestamp}"
+            case_backup_path = self.backup_dir / case_backup_name
+            self._backup_directory(self.case_dir, case_backup_path)
+
+        # 保留最近 20 个备份
+        self._cleanup_old_files(self.backup_dir, "state_*.json", keep=20)
+        self._cleanup_old_files(self.backup_dir, "case_*", keep=20)
+
+    def _backup_directory(self, src: Path, dst: Path) -> None:
+        """递归备份目录，跳过大型文件和临时文件"""
+        dst.mkdir(parents=True, exist_ok=True)
+        skipped_extensions = {'.pdf', '.png', '.jpg', '.jpeg', '.log', '.aux', '.bbl', '.blg', '.out'}
+
+        for item in src.rglob('*'):
+            if item.is_file():
+                # 跳过大型文件和临时文件
+                if item.suffix in skipped_extensions:
+                    continue
+                if item.name.startswith('.'):
+                    continue
+
+                relative_path = item.relative_to(src)
+                dst_path = dst / relative_path
+                dst_path.parent.mkdir(parents=True, exist_ok=True)
+                shutil.copy2(item, dst_path)
+
+    def get(self, key: str) -> Any:
+        """获取状态中的指定键值（支持点号访问嵌套字段）"""
+        if not self.state:
+            self.load()
+
+        keys = key.split('.')
+        value = self.state
+        for k in keys:
+            if isinstance(value, dict):
+                value = value.get(k)
+            else:
+                return None
+        return value
+
+    def set(self, key: str, value: Any) -> None:
+        """设置状态中的指定键值（支持点号访问嵌套字段）"""
+        if not self.state:
+            self.load()
+
+        keys = key.split('.')
+        target = self.state
+        for k in keys[:-1]:
+            if k not in target:
+                target[k] = {}
+            target = target[k]
+
+        target[keys[-1]] = value
+        self.save()
+
+    def update(self, patch: Dict[str, Any]) -> None:
+        """批量更新状态（深度合并）"""
+        if not self.state:
+            self.load()
+
+        self._deep_update(self.state, patch)
+        self.save()
+
+    def _deep_update(self, target: Dict, source: Dict) -> None:
+        """递归深度合并字典"""
+        for key, value in source.items():
+            if key in target and isinstance(target[key], dict) and isinstance(value, dict):
+                self._deep_update(target[key], value)
+            else:
+                target[key] = value
+
+    def next_round(self) -> Dict[str, Any]:
+        """进入下一轮迭代"""
+        if not self.state:
+            self.load()
+
+        self.state["current_round"] += 1
+        self.state["status"] = "EVALUATING"
+        self.state["agents_this_round"] = []
+        self.state["compile_success"] = None
+        self.state["page_images_rendered"] = False
+        self.save()
+
+        return self.state
+
+    def archive(self) -> str:
+        """归档当前状态（任务完成时调用）"""
+        if not self.state:
+            self.load()
+
+        self.archive_dir.mkdir(parents=True, exist_ok=True)
+        timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+        archive_name = f"state_final_{timestamp}.json"
+        archive_path = self.archive_dir / archive_name
+
+        # 更新状态标记
+        self.state["status"] = "ARCHIVED"
+        self.state["archived_at"] = datetime.now().isoformat()
+
+        with open(archive_path, 'w', encoding='utf-8') as f:
+            json.dump(self.state, f, indent=2, ensure_ascii=False)
+
+        # 可选：删除当前状态文件表示任务完成
+        # self.state_path.unlink(missing_ok=True)
+
+        return str(archive_path)
+
+    def _cleanup_old_files(self, directory: Path, pattern: str, keep: int) -> None:
+        """清理旧文件，仅保留最近 keep 个"""
+        files = sorted(directory.glob(pattern), key=os.path.getmtime, reverse=True)
+        for old_file in files[keep:]:
+            old_file.unlink()
+
+    def add_history_entry(self, entry: Dict[str, Any]) -> None:
+        """添加一轮历史记录"""
+        if not self.state:
+            self.load()
+
+        if "history" not in self.state:
+            self.state["history"] = []
+
+        entry["timestamp"] = datetime.now().isoformat()
+        self.state["history"].append(entry)
+        self.save()
+
+    def update_defect_summary(self, resolved: int, remaining: int, initial: Optional[int] = None) -> None:
+        """更新缺陷摘要"""
+        if not self.state:
+            self.load()
+
+        if initial is not None:
+            self.state["defect_summary"]["initial_total"] = initial
+        self.state["defect_summary"]["resolved"] = resolved
+        self.state["defect_summary"]["remaining"] = remaining
+        self.save()
+
+
+def main():
+    parser = argparse.ArgumentParser(description="PaperFit State Manager")
+    subparsers = parser.add_subparsers(dest="command", help="Commands")
+
+    # init 命令
+    init_parser = subparsers.add_parser("init", help="Initialize new state")
+    init_parser.add_argument("main_tex", help="Main .tex file path")
+    init_parser.add_argument("--task", default="full_vto", help="Task type")
+    init_parser.add_argument("--target-pages", type=int, help="Target page count")
+    init_parser.add_argument("--template", help="Template name")
+    init_parser.add_argument("--strict", action="store_true", help="Strict mode")
+    init_parser.add_argument("--max-rounds", type=int, default=10, help="Max iterations")
+
+    # get 命令
+    get_parser = subparsers.add_parser("get", help="Get value by key")
+    get_parser.add_argument("key", help="Key path (e.g., 'task.target_pages')")
+
+    # set 命令
+    set_parser = subparsers.add_parser("set", help="Set value by key")
+    set_parser.add_argument("key", help="Key path")
+    set_parser.add_argument("value", help="Value (JSON string)")
+
+    # update 命令
+    update_parser = subparsers.add_parser("update", help="Batch update with JSON patch")
+    update_parser.add_argument("patch", help="JSON patch string")
+
+    # next-round 命令
+    subparsers.add_parser("next-round", help="Increment round counter")
+
+    # archive 命令
+    subparsers.add_parser("archive", help="Archive current state")
+
+    # show 命令
+    subparsers.add_parser("show", help="Display current state")
+
+    args = parser.parse_args()
+    manager = StateManager()
+
+    try:
+        if args.command == "init":
+            state = manager.init_state(
+                args.main_tex,
+                task_type=args.task,
+                target_pages=args.target_pages,
+                template=args.template,
+                strict_mode=args.strict,
+                max_rounds=args.max_rounds
+            )
+            print(f"State initialized: {manager.state_path}")
+            print(json.dumps(state, indent=2))
+
+        elif args.command == "get":
+            value = manager.get(args.key)
+            print(json.dumps(value, indent=2, ensure_ascii=False))
+
+        elif args.command == "set":
+            try:
+                parsed_value = json.loads(args.value)
+            except json.JSONDecodeError:
+                parsed_value = args.value
+            manager.set(args.key, parsed_value)
+            print(f"Set {args.key} = {json.dumps(parsed_value, ensure_ascii=False)}")
+
+        elif args.command == "update":
+            patch = json.loads(args.patch)
+            manager.update(patch)
+            print("State updated")
+
+        elif args.command == "next-round":
+            state = manager.next_round()
+            print(f"Advanced to round {state['current_round']}")
+
+        elif args.command == "archive":
+            archive_path = manager.archive()
+            print(f"State archived to {archive_path}")
+
+        elif args.command == "show":
+            state = manager.load()
+            print(json.dumps(state, indent=2, ensure_ascii=False))
+
+        else:
+            parser.print_help()
+            sys.exit(1)
+
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

package/scripts/test_commands.py

@@ -0,0 +1,187 @@
+#!/usr/bin/env python3
+"""
+PaperFit Commands 测试脚本
+
+验证所有 commands/*.md 文件是否存在且格式正确，
+并检查它们引用的 agent 文件是否存在。
+"""
+
+import json
+from pathlib import Path
+from typing import List, Tuple
+
+
+class CommandTester:
+    """Commands 测试器"""
+
+    def __init__(self, root_dir: str = "."):
+        self.root = Path(root_dir)
+        self.commands_dir = self.root / ".claude" / "commands"
+        self.agents_dir = self.root / "agents"
+        self.skills_dir = self.root / "skills"
+        self.results: List[Tuple[str, bool, str]] = []
+
+    def check_command_file(self, cmd_path: Path) -> bool:
+        """检查单个命令文件"""
+        if not cmd_path.exists():
+            self.results.append((str(cmd_path), False, "文件不存在"))
+            return False
+
+        content = cmd_path.read_text()
+
+        # 检查必需字段
+        checks = []
+        if "# /" not in content:
+            checks.append("缺少命令标题 (# /command-name)")
+        if "作用" not in content:
+            checks.append("缺少'作用'描述")
+        if "用法" not in content:
+            checks.append("缺少'用法'说明")
+        if "执行流程" not in content:
+            checks.append("缺少'执行流程'")
+
+        # 检查是否包含参数（不应该有）
+        if "<" in content and ">" in content:
+            # 可能是参数占位符，需要人工审查
+            pass
+
+        if checks:
+            self.results.append((str(cmd_path), False, "; ".join(checks)))
+            return False
+
+        self.results.append((str(cmd_path), True, "格式正确"))
+        return True
+
+    def check_agent_references(self, cmd_path: Path) -> bool:
+        """检查命令文件中引用的 agent 是否存在"""
+        content = cmd_path.read_text()
+        missing_agents = []
+
+        # 查找 agent 引用
+        for line in content.split("\n"):
+            if "agents/" in line and ".md" in line:
+                # 提取 agent 文件名
+                start = line.find("agents/")
+                end = line.find(".md", start) + 3
+                if end > start:
+                    agent_ref = line[start:end].strip()
+                    agent_path = self.root / agent_ref
+                    if not agent_path.exists():
+                        missing_agents.append(agent_ref)
+
+        if missing_agents:
+            self.results.append((
+                str(cmd_path),
+                False,
+                f"引用不存在的 agent: {', '.join(missing_agents)}"
+            ))
+            return False
+
+        self.results.append((str(cmd_path), True, "agent 引用正确"))
+        return True
+
+    def check_skill_directories(self) -> bool:
+        """检查 skills 目录结构"""
+        required_skills = [
+            "taxonomy-vto",
+            "space-util-fixer",
+            "float-optimizer",
+            "consistency-polisher",
+            "overflow-repair",
+            "template-migrator",
+            "visual-inspector",
+            "writing-polish"
+        ]
+
+        for skill in required_skills:
+            skill_path = self.skills_dir / skill
+            if not skill_path.exists():
+                self.results.append((
+                    f"skills/{skill}",
+                    False,
+                    "Skill 目录不存在"
+                ))
+            elif not (skill_path / "SKILL.md").exists():
+                self.results.append((
+                    f"skills/{skill}",
+                    False,
+                    "缺少 SKILL.md 文件"
+                ))
+            else:
+                self.results.append((f"skills/{skill}", True, "OK"))
+
+        return all(r[1] for r in self.results if r[0].startswith("skills/"))
+
+    def run_all_tests(self) -> bool:
+        """运行所有测试"""
+        print("=" * 60)
+        print("PaperFit Commands 测试报告")
+        print("=" * 60)
+
+        # 检查 commands 目录
+        if not self.commands_dir.exists():
+            print(f"\n错误：commands 目录不存在：{self.commands_dir}")
+            return False
+
+        # 测试每个命令文件
+        cmd_files = list(self.commands_dir.glob("*.md"))
+        print(f"\n发现 {len(cmd_files)} 个命令文件\n")
+
+        for cmd_file in cmd_files:
+            print(f"检查：{cmd_file.name}")
+            self.check_command_file(cmd_file)
+            self.check_agent_references(cmd_file)
+
+        # 检查 skills
+        print("\n检查 Skills 目录:")
+        self.check_skill_directories()
+
+        # 输出结果摘要
+        print("\n" + "=" * 60)
+        print("测试结果摘要")
+        print("=" * 60)
+
+        passed = sum(1 for r in self.results if r[1])
+        failed = sum(1 for r in self.results if not r[1])
+
+        print(f"\n通过：{passed}")
+        print(f"失败：{failed}")
+
+        if failed > 0:
+            print("\n失败详情:")
+            for path, success, msg in self.results:
+                if not success:
+                    print(f"  ✗ {path}: {msg}")
+
+        # 输出命令列表
+        print("\n" + "=" * 60)
+        print("可用命令列表")
+        print("=" * 60)
+
+        for cmd_file in cmd_files:
+            content = cmd_file.read_text()
+            # 提取命令名称
+            for line in content.split("\n"):
+                if line.startswith("# /"):
+                    cmd_name = line.replace("# /", "").strip().split(" ")[0]
+                    # 提取作用描述
+                    desc_line = ""
+                    for desc in content.split("\n"):
+                        if desc.startswith("**作用**"):
+                            desc_line = desc.replace("**作用**:", "").strip()
+                            break
+                    print(f"  /{cmd_name} - {desc_line}")
+                    break
+
+        print("\n" + "=" * 60)
+
+        return failed == 0
+
+
+if __name__ == "__main__":
+    import sys
+
+    root = sys.argv[1] if len(sys.argv) > 1 else "."
+    tester = CommandTester(root)
+    success = tester.run_all_tests()
+    sys.exit(0 if success else 1)