feat: add kit project initializer

skiff/README.md

@@ -65,6 +65,7 @@ skiff bootstrap
 | 命令 | 说明 |
 |------|------|
 | `skiff bootstrap` | 将本项目的 `skiff` skill 全局安装到所有 Agent |
+| `skiff kit init <name> [--project DIR] [--copy]` | 在项目的 `docs/<name>/` 初始化规范包；默认软链接到 SSOT |
 
 ### 全局安装（自研 skill）
 

skiff/cli.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import argparse
 import re
+import shutil
 import subprocess
 import sys
 from datetime import datetime
@@ -17,6 +18,7 @@ from skiff.paths import (
     DRAFTS_DIR,
     EXTERNALS_DIR,
     CONFIG_FILE,
+    KITS_DIR,
     SKILLS_DIR,
     SKILLS_HOME,
     TEMPLATE_DIR,
@@ -80,6 +82,13 @@ def _project_root(explicit: str | None = None) -> Path:
     return find_repo_root() or Path.cwd()
 
 
+def _render_kit_template(source: Path, destination: Path, values: dict[str, str]) -> None:
+    content = source.read_text(encoding="utf-8")
+    for placeholder, value in values.items():
+        content = content.replace(placeholder, value)
+    destination.write_text(content, encoding="utf-8")
+
+
 def _collect_skill_names(positional: list[str] | None, flagged: list[str] | None) -> list[str]:
     names = list(positional or [])
     if flagged:
@@ -1039,6 +1048,71 @@ def cmd_doctor(args: argparse.Namespace) -> None:
         sys.exit(1)
 
 
+def cmd_kit_init(args: argparse.Namespace) -> None:
+    """将 owned kit 初始化到目标项目。"""
+    ensure_skills_home()
+    kit_source = KITS_DIR / args.name
+    if not kit_source.is_dir():
+        available = sorted(path.name for path in KITS_DIR.iterdir() if path.is_dir()) if KITS_DIR.is_dir() else []
+        suffix = f"；可用 kit: {', '.join(available)}" if available else ""
+        raise SystemExit(f"kit 不存在: {args.name}{suffix}")
+
+    project = _project_root(args.project)
+    if not project.is_dir():
+        raise SystemExit(f"项目目录不存在: {project}")
+    destination = project / "docs" / args.name
+    kit_target = destination / "kit"
+    project_file = destination / "project.md"
+    tasks_file = destination / "tasks.yaml"
+    managed_targets = (kit_target, project_file, tasks_file)
+    existing = [path for path in managed_targets if path.exists() or path.is_symlink()]
+    if existing:
+        paths = ", ".join(str(path.relative_to(project)) for path in existing)
+        raise SystemExit(f"拒绝覆盖已有路径: {paths}")
+
+    project_template = kit_source / "templates" / "project.template.md"
+    tasks_template = kit_source / "templates" / "tasks.template.yaml"
+    missing = [path for path in (project_template, tasks_template) if not path.is_file()]
+    if missing:
+        paths = ", ".join(str(path.relative_to(SKILLS_HOME)) for path in missing)
+        raise SystemExit(f"kit 缺少初始化模板: {paths}")
+
+    destination.mkdir(parents=True, exist_ok=True)
+    if args.copy:
+        shutil.copytree(kit_source, kit_target)
+        mode = "copy"
+    else:
+        kit_target.symlink_to(kit_source.resolve(), target_is_directory=True)
+        mode = "symlink"
+
+    version_file = kit_source / "VERSION"
+    kit_version = version_file.read_text(encoding="utf-8").strip() if version_file.is_file() else "unknown"
+    now = datetime.now().astimezone().isoformat(timespec="seconds")
+    values = {
+        "<project_name>": project.name,
+        "<repo_path>": str(project),
+        "<dev_worktree>": str(project),
+        "<overlay_file_path>": f"docs/{args.name}/project.md",
+        "<kit_version>": kit_version,
+        "<接入时的 ack 版本，见 kit 根 VERSION>": kit_version,
+        "<YYYY-MM-DDTHH:mm:ss+TZ>": now,
+    }
+    _render_kit_template(project_template, project_file, values)
+    _render_kit_template(tasks_template, tasks_file, values)
+
+    validator = kit_target / "scripts" / "validate_tasks.py"
+    if validator.is_file():
+        subprocess.run([sys.executable, str(validator), str(tasks_file)], check=True)
+
+    _print(f"✓ kit 初始化完成: {args.name}")
+    _print(f"  项目: {project}")
+    _print(f"  模式: {mode}")
+    _print(f"  kit: {kit_target}")
+    _print(f"  覆盖层: {project_file}")
+    _print(f"  任务板: {tasks_file}")
+    _print("下一步: 填写 project.md 中的项目命令、路径权限和 Base URL")
+
+
 def _add_common_flags(parser: argparse.ArgumentParser) -> None:
     parser.add_argument(
         "-a",
@@ -1207,6 +1281,18 @@ def build_parser() -> argparse.ArgumentParser:
     p_doctor.add_argument("--fix", action="store_true", help="自动修复可修复的软链")
     p_doctor.set_defaults(func=cmd_doctor)
 
+    p_kit = sub.add_parser("kit", help="管理项目规范包")
+    kit_sub = p_kit.add_subparsers(dest="kit_command", required=True)
+    p_kit_init = kit_sub.add_parser("init", help="在项目中初始化 kit")
+    p_kit_init.add_argument("name", help="kit 名称")
+    p_kit_init.add_argument("--project", help="项目根目录（默认自动检测或当前目录）")
+    p_kit_init.add_argument(
+        "--copy",
+        action="store_true",
+        help="复制 kit，而不是创建指向 SSOT 的软链接",
+    )
+    p_kit_init.set_defaults(func=cmd_kit_init)
+
     return parser
 
 

skiff/paths.py

@@ -7,6 +7,7 @@ from pathlib import Path
 HOME = Path.home()
 SKILLS_HOME = HOME / ".skills"
 SKILLS_DIR = SKILLS_HOME / "skills"
+KITS_DIR = SKILLS_HOME / "kits"
 TEMPLATE_DIR = SKILLS_DIR / "_template"
 DRAFTS_DIR = SKILLS_HOME / ".drafts"
 REGISTRY_FILE = SKILLS_HOME / "registry.yaml"