scripts/playbook.py

@@ -626,13 +626,10 @@ def replace_placeholders(
     project_name: str | None,
     date_value: str,
     playbook_scripts: str | None,
-    playbook_root: str | None,
 ) -> str:
     result = text.replace("{{DATE}}", date_value)
     if project_name:
         result = result.replace("{{PROJECT_NAME}}", project_name)
-    if playbook_root:
-        result = result.replace("{{PLAYBOOK_ROOT}}", playbook_root)
     if playbook_scripts:
         result = result.replace("{{PLAYBOOK_SCRIPTS}}", playbook_scripts)
     return result
@@ -652,14 +649,11 @@ def replace_placeholders_in_file(
     project_name: str | None,
     date_value: str,
     playbook_scripts: str | None,
-    playbook_root: str | None,
 ) -> None:
     if file_path.suffix != ".md":
         return
     text = file_path.read_text(encoding="utf-8")
-    updated = replace_placeholders(
+    updated = replace_placeholders(text, project_name, date_value, playbook_scripts)
-        text, project_name, date_value, playbook_scripts, playbook_root
-    )
     if updated != text:
         file_path.write_text(updated, encoding="utf-8", newline="\n")
 
@@ -679,7 +673,6 @@ def sync_directory(
     project_name: str | None,
     date_value: str,
     playbook_scripts: str | None,
-    playbook_root: str | None,
     force: bool,
     no_backup: bool,
 ) -> None:
@@ -700,7 +693,6 @@ def sync_directory(
             project_name,
             date_value,
             playbook_scripts,
-            playbook_root,
         )
 
 
@@ -728,11 +720,10 @@ def update_agents_section(
     project_name: str | None,
     date_value: str,
     playbook_scripts: str | None,
-    playbook_root: str | None,
 ) -> None:
     template_text = template_path.read_text(encoding="utf-8")
     template_text = replace_placeholders(
-        template_text, project_name, date_value, playbook_scripts, playbook_root
+        template_text, project_name, date_value, playbook_scripts
     )
     block = extract_block_lines(template_text, start_marker, end_marker)
     if not block:
@@ -811,7 +802,6 @@ def sync_agents_template(context: dict) -> int:
 
     project_name = resolve_project_name(context)
     playbook_scripts = resolve_playbook_scripts(context)
-    playbook_root = resolve_playbook_root(context)
     date_value = resolve_template_date(context)
 
     agents_dst = project_root / "AGENTS.md"
@@ -838,7 +828,6 @@ def sync_agents_template(context: dict) -> int:
         project_name,
         date_value,
         playbook_scripts,
-        playbook_root,
     )
     sync_claude_md(project_root, context.get("config", {}))
     return 0
@@ -955,15 +944,12 @@ def sync_rules_action(config: dict, context: dict) -> int:
 
     project_name = resolve_project_name(context)
     playbook_scripts = resolve_playbook_scripts(context)
-    playbook_root = resolve_playbook_root(context)
     date_value = config.get("date") or datetime.now().strftime("%Y-%m-%d")
     no_backup = bool(config.get("no_backup", False))
 
     backup_path(rules_dst, no_backup)
     text = rules_src.read_text(encoding="utf-8")
-    text = replace_placeholders(
+    text = replace_placeholders(text, project_name, date_value, playbook_scripts)
-        text, project_name, date_value, playbook_scripts, playbook_root
-    )
     rules_dst.write_text(text.rstrip("\n") + "\n", encoding="utf-8", newline="\n")
     log("Synced: AGENT_RULES.md")
 
@@ -1001,7 +987,6 @@ def sync_memory_bank_action(config: dict, context: dict) -> int:
 
     project_name = config.get("project_name")
     playbook_scripts = resolve_playbook_scripts(context)
-    playbook_root = resolve_playbook_root(context)
     date_value = config.get("date") or datetime.now().strftime("%Y-%m-%d")
     force = bool(config.get("force", False))
     no_backup = bool(config.get("no_backup", False))
@@ -1014,7 +999,6 @@ def sync_memory_bank_action(config: dict, context: dict) -> int:
         project_name,
         date_value,
         playbook_scripts,
-        playbook_root,
         force,
         no_backup,
     )
@@ -1036,7 +1020,6 @@ def sync_prompts_action(config: dict, context: dict) -> int:
 
     project_name = resolve_project_name(context)
     playbook_scripts = resolve_playbook_scripts(context)
-    playbook_root = resolve_playbook_root(context)
     date_value = config.get("date") or datetime.now().strftime("%Y-%m-%d")
     force = bool(config.get("force", False))
     no_backup = bool(config.get("no_backup", False))
@@ -1050,7 +1033,6 @@ def sync_prompts_action(config: dict, context: dict) -> int:
         project_name,
         date_value,
         playbook_scripts,
-        playbook_root,
         force,
         no_backup,
     )

templates/AGENT_RULES.template.md

@@ -41,23 +41,6 @@
 - 只做当前任务需要的改动，不顺手加功能、不顺手重构
 - 不为一次性操作增加抽象，不为假设的未来需求设计
 
-## 项目边界
-
-### Playbook 目录
-
-- `{{PLAYBOOK_ROOT}}/` 是 Playbook 模板/供应商目录，不是业务项目源码、
-  业务文档或当前项目私有规则
-- 除非用户明确要求维护、升级或调试 Playbook 本身，不得修改
-  `{{PLAYBOOK_ROOT}}/` 下内容
-- 当前项目已生效的规则入口是项目根目录的 `AGENT_RULES.md`、
-  `AGENT_RULES.local.md`、`AGENTS.md` 与 `.agents/`
-- `{{PLAYBOOK_ROOT}}/templates/` 与 `{{PLAYBOOK_ROOT}}/rulesets/`
-  是模板源；不要把它们当作当前项目已生效规则
-- 可按 `.agents/` 指向读取 `{{PLAYBOOK_ROOT}}/docs/` 作为标准文档；
-  读取不代表该目录属于业务改动范围
-- 搜索、批量修改、代码审查、归档/提交时，默认排除 `{{PLAYBOOK_ROOT}}/`；
-  只有任务目标明确涉及 Playbook 时才纳入
-
 ## 会话启动
 
 每次新会话开始时，按顺序加载以下上下文：

templates/README.md

@@ -141,7 +141,7 @@ python scripts/playbook.py -config playbook.toml
 - **force**：默认 false，已存在则跳过；设为 true 时覆盖框架文件（会先备份）
 - **no_backup**：默认 false；设为 true 时跳过备份直接覆盖
 - **不删除项目文件**：只更新框架提供的文件，项目新增的文件不会被删除
-- **占位符替换**：自动替换 `{{DATE}}`、`{{PROJECT_NAME}}`、`{{PLAYBOOK_ROOT}}`、`{{PLAYBOOK_SCRIPTS}}`
+- **占位符替换**：自动替换 `{{DATE}}`、`{{PROJECT_NAME}}`、`{{PLAYBOOK_SCRIPTS}}`
 
 ### 典型场景
 
@@ -229,15 +229,11 @@ project/
 | `{{PROJECT_NAME}}`        | 项目名称     | ✅ 可选  |
 | `{{PROJECT_GOAL}}`        | 项目目标     | ❌ 手动  |
 | `{{PROJECT_DESCRIPTION}}` | 项目描述     | ❌ 手动  |
-| `{{PLAYBOOK_ROOT}}`       | Playbook 根  | ✅ 是    |
 | `{{PLAYBOOK_SCRIPTS}}`    | 脚本路径     | ✅ 是    |
 | 其他 `{{...}}`            | 项目特定内容 | ❌ 手动  |
 
 `{{PROJECT_NAME}}` 可通过 `sync_memory_bank.project_name` 自动替换；
 未配置时保持原样。
-`{{PLAYBOOK_ROOT}}` 自动替换为项目内 Playbook 根目录
-（默认 `docs/standards/playbook`，
-也可按项目配置改成 `custom/playbook` 等）。
 `{{PLAYBOOK_SCRIPTS}}` 自动替换为 Playbook 脚本路径
 （默认 `docs/standards/playbook/scripts`，
 也可按项目配置改成 `custom/playbook/scripts` 等）。

tests/README.md

@@ -8,16 +8,15 @@
 tests/
 ├── README.md                       # 本文件：测试文档
 ├── cli/                            # Python CLI 测试（unittest）
-│   ├── test_claude_md_sync.py      # CLAUDE.md 同步与注入测试
-│   ├── test_install_skills.py      # install_skills 与 skill_link 行为测试
-│   ├── test_sync_standards_cli.py  # sync_standards 规则集同步测试
 │   └── test_playbook_cli.py        # playbook.py 基础功能测试
 ├── test_format_md_action.py        # format_md 动作测试
 ├── test_gitea_workflow_bootstrap.py # Gitea workflow 自举顺序回归测试
 ├── test_firstparty_skills_quality.py # first-party skills 元数据与结构质量测试
 ├── test_gitattributes_modes.py     # gitattr_mode 行为测试
 ├── test_no_backup_flags.py         # no_backup 行为测试
+├── test_playbook_typing_imports.py # playbook.py typing 导入兼容性测试
 ├── test_sync_directory_actions.py  # sync_memory_bank/sync_prompts 行为测试
+├── test_vendor_snapshot_templates.py # snapshot 快照模板完整性测试
 ├── test_main_loop_cli.py           # main_loop CLI 测试
 ├── test_thirdparty_skills_pipeline.py # thirdparty skills 流水线配置与同步产物测试
 ├── test_sync_templates_placeholders.py # 占位符替换测试（sync_rules/sync_standards）

tests/cli/test_claude_md_sync.py

@@ -1,163 +0,0 @@
-import subprocess
-import sys
-import tempfile
-import unittest
-from pathlib import Path
-
-ROOT = Path(__file__).resolve().parents[2]
-SCRIPT = ROOT / "scripts" / "playbook.py"
-CUSTOM_DEPLOY_ROOT = "custom/playbook"
-
-
-def run_cli(*args):
-    return subprocess.run(
-        [sys.executable, str(SCRIPT), *args],
-        capture_output=True,
-        text=True,
-    )
-
-
-class ClaudeMdSyncTests(unittest.TestCase):
-    def test_sync_claude_md_creates_when_no_claude_md(self):
-        with tempfile.TemporaryDirectory() as tmp_dir:
-            config_body = f"""
-[playbook]
-project_root = "{tmp_dir}"
-playbook_root = "{CUSTOM_DEPLOY_ROOT}"
-install_mode = "snapshot"
-
-[sync_memory_bank]
-project_name = "Demo"
-"""
-            config_path = Path(tmp_dir) / "playbook.toml"
-            config_path.write_text(config_body, encoding="utf-8")
-
-            result = run_cli("-config", str(config_path))
-
-            self.assertEqual(result.returncode, 0)
-            claude_md = Path(tmp_dir) / "CLAUDE.md"
-            self.assertTrue(claude_md.exists())
-            text = claude_md.read_text(encoding="utf-8")
-            self.assertTrue(text.startswith("# CLAUDE.md\n\n"))
-            self.assertIn("@AGENTS.md", text)
-            self.assertIn("<!-- playbook:claude:start -->", text)
-
-    def test_sync_claude_md_appends_block_to_existing_claude_md(self):
-        with tempfile.TemporaryDirectory() as tmp_dir:
-            claude_md = Path(tmp_dir) / "CLAUDE.md"
-            claude_md.write_text(
-                "# My project\n\nSome existing content.\n", encoding="utf-8"
-            )
-
-            config_body = f"""
-[playbook]
-project_root = "{tmp_dir}"
-playbook_root = "{CUSTOM_DEPLOY_ROOT}"
-install_mode = "snapshot"
-
-[sync_memory_bank]
-project_name = "Demo"
-"""
-            config_path = Path(tmp_dir) / "playbook.toml"
-            config_path.write_text(config_body, encoding="utf-8")
-
-            result = run_cli("-config", str(config_path))
-
-            self.assertEqual(result.returncode, 0)
-            text = claude_md.read_text(encoding="utf-8")
-            self.assertIn("@AGENTS.md", text)
-            self.assertIn("@AGENT_RULES.md", text)
-            self.assertIn("<!-- playbook:claude:start -->", text)
-            self.assertIn("Some existing content.", text)
-
-    def test_sync_claude_md_updates_existing_block(self):
-        with tempfile.TemporaryDirectory() as tmp_dir:
-            claude_md = Path(tmp_dir) / "CLAUDE.md"
-            claude_md.write_text(
-                "# My project\n\n"
-                "<!-- playbook:claude:start -->\n"
-                "@AGENTS.md\n"
-                "<!-- playbook:claude:end -->\n",
-                encoding="utf-8",
-            )
-
-            config_body = f"""
-[playbook]
-project_root = "{tmp_dir}"
-playbook_root = "{CUSTOM_DEPLOY_ROOT}"
-install_mode = "snapshot"
-
-[sync_memory_bank]
-project_name = "Demo"
-"""
-            config_path = Path(tmp_dir) / "playbook.toml"
-            config_path.write_text(config_body, encoding="utf-8")
-
-            result = run_cli("-config", str(config_path))
-
-            self.assertEqual(result.returncode, 0)
-            text = claude_md.read_text(encoding="utf-8")
-            self.assertIn("@AGENTS.md", text)
-            self.assertIn("@AGENT_RULES.md", text)
-            self.assertEqual(text.count("<!-- playbook:claude:start -->"), 1)
-
-    def test_sync_claude_md_adds_heading_to_generated_block(self):
-        with tempfile.TemporaryDirectory() as tmp_dir:
-            claude_md = Path(tmp_dir) / "CLAUDE.md"
-            claude_md.write_text(
-                "<!-- playbook:claude:start -->\n"
-                "\n"
-                "@AGENTS.md\n"
-                "@AGENT_RULES.md\n"
-                "\n"
-                "<!-- playbook:claude:end -->\n",
-                encoding="utf-8",
-            )
-
-            config_body = f"""
-[playbook]
-project_root = "{tmp_dir}"
-playbook_root = "{CUSTOM_DEPLOY_ROOT}"
-install_mode = "snapshot"
-
-[sync_memory_bank]
-project_name = "Demo"
-"""
-            config_path = Path(tmp_dir) / "playbook.toml"
-            config_path.write_text(config_body, encoding="utf-8")
-
-            result = run_cli("-config", str(config_path))
-
-            self.assertEqual(result.returncode, 0)
-            text = claude_md.read_text(encoding="utf-8")
-            self.assertTrue(text.startswith("# CLAUDE.md\n\n"))
-            self.assertIn("@AGENTS.md", text)
-            self.assertIn("@AGENT_RULES.md", text)
-            self.assertEqual(text.count("<!-- playbook:claude:start -->"), 1)
-
-    def test_sync_claude_md_skips_when_already_references_agents(self):
-        with tempfile.TemporaryDirectory() as tmp_dir:
-            claude_md = Path(tmp_dir) / "CLAUDE.md"
-            original = "# My project\n\n@AGENTS.md\n"
-            claude_md.write_text(original, encoding="utf-8")
-
-            config_body = f"""
-[playbook]
-project_root = "{tmp_dir}"
-playbook_root = "{CUSTOM_DEPLOY_ROOT}"
-install_mode = "snapshot"
-
-[sync_memory_bank]
-project_name = "Demo"
-"""
-            config_path = Path(tmp_dir) / "playbook.toml"
-            config_path.write_text(config_body, encoding="utf-8")
-
-            result = run_cli("-config", str(config_path))
-
-            self.assertEqual(result.returncode, 0)
-            self.assertEqual(claude_md.read_text(encoding="utf-8"), original)
-
-
-if __name__ == "__main__":
-    unittest.main()

tests/cli/test_install_skills.py

@@ -1,310 +0,0 @@
-import subprocess
-import sys
-import tempfile
-import unittest
-from pathlib import Path
-
-ROOT = Path(__file__).resolve().parents[2]
-SCRIPT = ROOT / "scripts" / "playbook.py"
-CUSTOM_DEPLOY_ROOT = "custom/playbook"
-
-
-def run_script(script, *args):
-    return subprocess.run(
-        [sys.executable, str(script), *args],
-        capture_output=True,
-        text=True,
-    )
-
-
-def run_cli(*args):
-    return run_script(SCRIPT, *args)
-
-
-def write_config(root: Path, name: str, body: str) -> Path:
-    config_path = root / name
-    config_path.write_text(body, encoding="utf-8")
-    return config_path
-
-
-class InstallSkillsTests(unittest.TestCase):
-    def assert_style_cleanup_tsl_docs_prefix(
-        self, root: Path, agents_home: Path, docs_prefix: str
-    ) -> None:
-        agents_index = (root / ".agents" / "tsl" / "index.md").read_text(
-            encoding="utf-8"
-        )
-        self.assertIn(f"`{docs_prefix}/tsl/index.md`", agents_index)
-        self.assertNotIn("`docs/tsl/index.md`", agents_index)
-
-        skill_file = (agents_home / "skills" / "style-cleanup" / "SKILL.md").read_text(
-            encoding="utf-8"
-        )
-        self.assertIn(f"`{docs_prefix}/tsl/code_style.md`", skill_file)
-        self.assertNotIn("`docs/tsl/code_style.md`", skill_file)
-
-    def test_install_skills(self):
-        with tempfile.TemporaryDirectory() as tmp_dir:
-            target = Path(tmp_dir) / "agents"
-            config_body = f"""
-[playbook]
-project_root = "{tmp_dir}"
-playbook_root = "{CUSTOM_DEPLOY_ROOT}"
-install_mode = "snapshot"
-
-[install_skills]
-agents_home = "{target}"
-mode = "list"
-skills = ["brainstorming"]
-"""
-            config_path = Path(tmp_dir) / "playbook.toml"
-            config_path.write_text(config_body, encoding="utf-8")
-
-            result = run_cli("-config", str(config_path))
-
-            skill_file = target / "skills/brainstorming/SKILL.md"
-            self.assertEqual(result.returncode, 0)
-            self.assertTrue(skill_file.is_file())
-
-    def test_install_skills_installs_generated_thirdparty_skill(self):
-        with tempfile.TemporaryDirectory() as tmp_dir:
-            target = Path(tmp_dir) / "agents"
-
-            config_body = f"""
-[playbook]
-project_root = "{tmp_dir}"
-playbook_root = "{CUSTOM_DEPLOY_ROOT}"
-install_mode = "snapshot"
-
-[install_skills]
-agents_home = "{target}"
-mode = "list"
-skills = ["karpathy-guidelines"]
-"""
-            config_path = Path(tmp_dir) / "playbook.toml"
-            config_path.write_text(config_body, encoding="utf-8")
-
-            result = run_cli("-config", str(config_path))
-
-            skill_file = target / "skills" / "karpathy-guidelines" / "SKILL.md"
-            self.assertEqual(result.returncode, 0, msg=result.stdout + result.stderr)
-            self.assertTrue(skill_file.is_file())
-
-    def test_install_skills_rejects_removed_tsl_guide(self):
-        with tempfile.TemporaryDirectory() as tmp_dir:
-            target = Path(tmp_dir) / "agents"
-            config_body = f"""
-[playbook]
-project_root = "{tmp_dir}"
-playbook_root = "{CUSTOM_DEPLOY_ROOT}"
-install_mode = "snapshot"
-
-[install_skills]
-agents_home = "{target}"
-mode = "list"
-skills = ["tsl-guide"]
-"""
-            config_path = Path(tmp_dir) / "playbook.toml"
-            config_path.write_text(config_body, encoding="utf-8")
-
-            result = run_cli("-config", str(config_path))
-
-            self.assertNotEqual(result.returncode, 0)
-            self.assertIn("skill not found: tsl-guide", result.stdout + result.stderr)
-
-    def test_install_skills_rejects_codex_home(self):
-        with tempfile.TemporaryDirectory() as tmp_dir:
-            target = Path(tmp_dir) / "codex"
-            config_body = f"""
-[playbook]
-project_root = "{tmp_dir}"
-playbook_root = "{CUSTOM_DEPLOY_ROOT}"
-install_mode = "snapshot"
-
-[install_skills]
-codex_home = "{target}"
-mode = "list"
-skills = ["brainstorming"]
-"""
-            config_path = Path(tmp_dir) / "playbook.toml"
-            config_path.write_text(config_body, encoding="utf-8")
-
-            result = run_cli("-config", str(config_path))
-
-            self.assertNotEqual(result.returncode, 0)
-            self.assertIn("codex_home", result.stdout + result.stderr)
-
-    def test_external_clone_flow_rewrites_links_with_configured_playbook_root(self):
-        with tempfile.TemporaryDirectory() as tmp_dir:
-            root = Path(tmp_dir)
-            agents_home = root / "agents-home"
-            config_body = f"""
-[playbook]
-project_root = "{tmp_dir}"
-playbook_root = "{CUSTOM_DEPLOY_ROOT}"
-install_mode = "snapshot"
-
-[sync_standards]
-langs = ["tsl"]
-no_backup = true
-
-[install_skills]
-agents_home = "{agents_home}"
-mode = "list"
-skills = ["style-cleanup"]
-"""
-            config_path = write_config(root, "playbook.toml", config_body)
-
-            result = run_cli("-config", str(config_path))
-
-            self.assertEqual(result.returncode, 0, msg=result.stdout + result.stderr)
-            self.assertTrue((root / CUSTOM_DEPLOY_ROOT / "SOURCE.md").is_file())
-            self.assert_style_cleanup_tsl_docs_prefix(
-                root, agents_home, f"{CUSTOM_DEPLOY_ROOT}/docs"
-            )
-
-    def test_deployed_snapshot_rewrites_links_from_snapshot_location(self):
-        with tempfile.TemporaryDirectory() as tmp_dir:
-            root = Path(tmp_dir)
-            install_config = write_config(
-                root,
-                "install.toml",
-                f"""
-[playbook]
-project_root = "{tmp_dir}"
-playbook_root = "{CUSTOM_DEPLOY_ROOT}"
-install_mode = "snapshot"
-
-[sync_standards]
-langs = ["tsl"]
-""",
-            )
-
-            install_result = run_cli("-config", str(install_config))
-            self.assertEqual(
-                install_result.returncode,
-                0,
-                msg=install_result.stdout + install_result.stderr,
-            )
-
-            snapshot_script = root / CUSTOM_DEPLOY_ROOT / "scripts" / "playbook.py"
-            agents_home = root / "local-agents"
-            sync_config = write_config(
-                root,
-                "sync.toml",
-                f"""
-[playbook]
-project_root = "{tmp_dir}"
-playbook_root = "{CUSTOM_DEPLOY_ROOT}"
-install_mode = "snapshot"
-
-[sync_standards]
-langs = ["tsl"]
-no_backup = true
-
-[install_skills]
-agents_home = "{agents_home}"
-mode = "list"
-skills = ["style-cleanup"]
-""",
-            )
-
-            sync_result = run_script(snapshot_script, "-config", str(sync_config))
-            self.assertEqual(
-                sync_result.returncode, 0, msg=sync_result.stdout + sync_result.stderr
-            )
-            self.assert_style_cleanup_tsl_docs_prefix(
-                root, agents_home, f"{CUSTOM_DEPLOY_ROOT}/docs"
-            )
-
-    def test_install_skills_creates_symlink_when_skill_link_configured(self):
-        with tempfile.TemporaryDirectory() as tmp_dir:
-            root = Path(tmp_dir)
-            agents_home = root / "agents"
-            link_home = root / "claude"
-            config_body = f"""
-[playbook]
-project_root = "{tmp_dir}"
-playbook_root = "{CUSTOM_DEPLOY_ROOT}"
-install_mode = "snapshot"
-
-[install_skills]
-agents_home = "{agents_home}"
-skill_link = "{link_home}"
-mode = "list"
-skills = ["commit-message"]
-"""
-            config_path = root / "playbook.toml"
-            config_path.write_text(config_body, encoding="utf-8")
-
-            result = run_cli("-config", str(config_path))
-
-            self.assertEqual(result.returncode, 0, msg=result.stdout + result.stderr)
-            skills_dst = agents_home / "skills"
-            link_path = link_home / "skills"
-            self.assertTrue(skills_dst.is_dir())
-            self.assertTrue(link_path.is_dir(), "link_path should be accessible as dir")
-            self.assertEqual(link_path.resolve(), skills_dst.resolve())
-            self.assertTrue((link_path / "commit-message" / "SKILL.md").is_file())
-
-    def test_install_skills_symlink_is_idempotent(self):
-        with tempfile.TemporaryDirectory() as tmp_dir:
-            root = Path(tmp_dir)
-            agents_home = root / "agents"
-            link_home = root / "claude"
-            config_body = f"""
-[playbook]
-project_root = "{tmp_dir}"
-playbook_root = "{CUSTOM_DEPLOY_ROOT}"
-install_mode = "snapshot"
-
-[install_skills]
-agents_home = "{agents_home}"
-skill_link = "{link_home}"
-mode = "list"
-skills = ["commit-message"]
-no_backup = true
-"""
-            config_path = root / "playbook.toml"
-            config_path.write_text(config_body, encoding="utf-8")
-
-            run_cli("-config", str(config_path))
-            result = run_cli("-config", str(config_path))
-
-            self.assertEqual(result.returncode, 0, msg=result.stdout + result.stderr)
-            self.assertTrue((link_home / "skills").is_dir())
-
-    def test_install_skills_no_symlink_when_skill_link_absent(self):
-        with tempfile.TemporaryDirectory() as tmp_dir:
-            root = Path(tmp_dir)
-            agents_home = root / "agents"
-            config_body = f"""
-[playbook]
-project_root = "{tmp_dir}"
-playbook_root = "{CUSTOM_DEPLOY_ROOT}"
-install_mode = "snapshot"
-
-[install_skills]
-agents_home = "{agents_home}"
-mode = "list"
-skills = ["commit-message"]
-"""
-            config_path = root / "playbook.toml"
-            config_path.write_text(config_body, encoding="utf-8")
-
-            result = run_cli("-config", str(config_path))
-
-            self.assertEqual(result.returncode, 0, msg=result.stdout + result.stderr)
-            self.assertFalse(
-                any(
-                    p.is_symlink()
-                    for p in (agents_home / "skills").iterdir()
-                    if p.is_symlink()
-                )
-                if (agents_home / "skills").exists()
-                else False
-            )
-
-
-if __name__ == "__main__":
-    unittest.main()

tests/cli/test_playbook_cli.py

@@ -1,3 +1,5 @@
+import json
+import shutil
 import subprocess
 import sys
 import tempfile
@@ -27,7 +29,29 @@ def write_config(root: Path, name: str, body: str) -> Path:
     return config_path
 
 
+def bash_path(path: Path) -> str:
+    resolved = path.resolve()
+    if sys.platform != "win32":
+        return resolved.as_posix()
+    drive = resolved.drive.rstrip(":").lower()
+    rest = resolved.as_posix()[2:]
+    return f"/mnt/{drive}{rest}"
+
+
 class PlaybookCliTests(unittest.TestCase):
+    def assert_style_cleanup_tsl_docs_prefix(
+        self, root: Path, agents_home: Path, docs_prefix: str
+    ) -> None:
+        agents_index = (root / ".agents" / "tsl" / "index.md").read_text(encoding="utf-8")
+        self.assertIn(f"`{docs_prefix}/tsl/index.md`", agents_index)
+        self.assertNotIn("`docs/tsl/index.md`", agents_index)
+
+        skill_file = (agents_home / "skills" / "style-cleanup" / "SKILL.md").read_text(
+            encoding="utf-8"
+        )
+        self.assertIn(f"`{docs_prefix}/tsl/code_style.md`", skill_file)
+        self.assertNotIn("`docs/tsl/code_style.md`", skill_file)
+
     def test_help_shows_usage(self):
         result = run_cli("-h")
         self.assertEqual(result.returncode, 0)
@@ -276,5 +300,592 @@ project_name = "Demo"
             self.assertEqual(result.returncode, 0)
             self.assertTrue(memory_bank.is_file())
 
+    def test_sync_standards_creates_agents(self):
+        with tempfile.TemporaryDirectory() as tmp_dir:
+            config_body = f"""
+[playbook]
+project_root = "{tmp_dir}"
+playbook_root = "{CUSTOM_DEPLOY_ROOT}"
+install_mode = "snapshot"
+
+[sync_standards]
+langs = ["tsl"]
+"""
+            config_path = Path(tmp_dir) / "playbook.toml"
+            config_path.write_text(config_body, encoding="utf-8")
+
+            result = run_cli("-config", str(config_path))
+
+            agents_index = Path(tmp_dir) / ".agents/tsl/index.md"
+            self.assertEqual(result.returncode, 0)
+            self.assertTrue(agents_index.is_file())
+
+    def test_sync_standards_updates_agents_index_when_langs_expand(self):
+        with tempfile.TemporaryDirectory() as tmp_dir:
+            root = Path(tmp_dir)
+
+            first_config = root / "playbook-first.toml"
+            first_config.write_text(
+                f"""
+[playbook]
+project_root = "{tmp_dir}"
+playbook_root = "{CUSTOM_DEPLOY_ROOT}"
+install_mode = "snapshot"
+
+[sync_standards]
+langs = ["tsl"]
+no_backup = true
+""",
+                encoding="utf-8",
+            )
+
+            first_result = run_cli("-config", str(first_config))
+            self.assertEqual(first_result.returncode, 0)
+
+            second_config = root / "playbook-second.toml"
+            second_config.write_text(
+                f"""
+[playbook]
+project_root = "{tmp_dir}"
+playbook_root = "{CUSTOM_DEPLOY_ROOT}"
+install_mode = "snapshot"
+
+[sync_standards]
+langs = ["tsl", "cpp"]
+no_backup = true
+""",
+                encoding="utf-8",
+            )
+
+            second_result = run_cli("-config", str(second_config))
+            self.assertEqual(second_result.returncode, 0)
+
+            agents_index = (root / ".agents" / "index.md").read_text(encoding="utf-8")
+            self.assertIn("`.agents/tsl/index.md`", agents_index)
+            self.assertIn("`.agents/cpp/index.md`", agents_index)
+
+    def test_sync_standards_agents_index_only_lists_configured_langs(self):
+        with tempfile.TemporaryDirectory() as tmp_dir:
+            root = Path(tmp_dir)
+            config_body = f"""
+[playbook]
+project_root = "{tmp_dir}"
+playbook_root = "{CUSTOM_DEPLOY_ROOT}"
+install_mode = "snapshot"
+
+[sync_standards]
+langs = ["tsl", "markdown"]
+"""
+            config_path = write_config(root, "playbook.toml", config_body)
+
+            result = run_cli("-config", str(config_path))
+            self.assertEqual(result.returncode, 0, msg=result.stdout + result.stderr)
+
+            agents_index = (root / ".agents" / "index.md").read_text(encoding="utf-8")
+            self.assertIn("`.agents/tsl/`：TSL 相关规则集", agents_index)
+            self.assertIn("`.agents/markdown/`：Markdown 相关规则集", agents_index)
+            self.assertNotIn("`.agents/cpp/`", agents_index)
+            self.assertNotIn("`.agents/python/`", agents_index)
+            self.assertNotIn("`.agents/typescript/`", agents_index)
+
+    def test_sync_standards_agents_block_has_blank_lines(self):
+        with tempfile.TemporaryDirectory() as tmp_dir:
+            config_body = f"""
+[playbook]
+project_root = "{tmp_dir}"
+playbook_root = "{CUSTOM_DEPLOY_ROOT}"
+install_mode = "snapshot"
+
+[sync_standards]
+langs = ["tsl"]
+"""
+            config_path = Path(tmp_dir) / "playbook.toml"
+            config_path.write_text(config_body, encoding="utf-8")
+
+            result = run_cli("-config", str(config_path))
+            self.assertEqual(result.returncode, 0)
+
+            agents_md = Path(tmp_dir) / "AGENTS.md"
+            lines = agents_md.read_text(encoding="utf-8").splitlines()
+            start_idx = lines.index("<!-- playbook:agents:start -->")
+            end_idx = lines.index("<!-- playbook:agents:end -->")
+            block = lines[start_idx : end_idx + 1]
+            self.assertEqual(block[1], "")
+            bullet_idx = next(i for i, line in enumerate(block) if line.startswith("- "))
+            self.assertEqual(block[bullet_idx - 1], "")
+
+    def test_install_skills(self):
+        with tempfile.TemporaryDirectory() as tmp_dir:
+            target = Path(tmp_dir) / "agents"
+            config_body = f"""
+[playbook]
+project_root = "{tmp_dir}"
+playbook_root = "{CUSTOM_DEPLOY_ROOT}"
+install_mode = "snapshot"
+
+[install_skills]
+agents_home = "{target}"
+mode = "list"
+skills = ["brainstorming"]
+"""
+            config_path = Path(tmp_dir) / "playbook.toml"
+            config_path.write_text(config_body, encoding="utf-8")
+
+            result = run_cli("-config", str(config_path))
+
+            skill_file = target / "skills/brainstorming/SKILL.md"
+            self.assertEqual(result.returncode, 0)
+            self.assertTrue(skill_file.is_file())
+
+    def test_install_generated_thirdparty_karpathy_skill_after_sync(self):
+        with tempfile.TemporaryDirectory() as tmp_dir:
+            tmp_root = Path(tmp_dir)
+            mirror = tmp_root / "origin.git"
+            repo = tmp_root / "repo"
+            target = tmp_root / "agents"
+
+            clone_mirror = subprocess.run(
+                ["git", "clone", "--mirror", str(ROOT), str(mirror)],
+                capture_output=True,
+                text=True,
+            )
+            self.assertEqual(clone_mirror.returncode, 0, msg=clone_mirror.stderr)
+
+            thirdparty_ref = subprocess.run(
+                [
+                    "git",
+                    f"--git-dir={mirror}",
+                    "rev-parse",
+                    "refs/remotes/origin/thirdparty/skill",
+                ],
+                capture_output=True,
+                text=True,
+            )
+            self.assertEqual(thirdparty_ref.returncode, 0, msg=thirdparty_ref.stderr)
+            expose_thirdparty_branch = subprocess.run(
+                [
+                    "git",
+                    f"--git-dir={mirror}",
+                    "update-ref",
+                    "refs/heads/thirdparty/skill",
+                    thirdparty_ref.stdout.strip(),
+                ],
+                capture_output=True,
+                text=True,
+            )
+            self.assertEqual(
+                expose_thirdparty_branch.returncode,
+                0,
+                msg=expose_thirdparty_branch.stderr,
+            )
+
+            clone_repo = subprocess.run(
+                ["git", "clone", str(mirror), str(repo)],
+                capture_output=True,
+                text=True,
+            )
+            self.assertEqual(clone_repo.returncode, 0, msg=clone_repo.stderr)
+
+            set_remote = subprocess.run(
+                ["git", "-C", str(repo), "remote", "set-url", "origin", bash_path(mirror)],
+                capture_output=True,
+                text=True,
+            )
+            self.assertEqual(set_remote.returncode, 0, msg=set_remote.stderr)
+
+            manifest_src = ROOT / ".gitea" / "ci" / "thirdparty_skills.json"
+            manifest_dst = repo / ".gitea" / "ci" / "thirdparty_skills.json"
+            manifest_data = json.loads(manifest_src.read_text(encoding="utf-8"))
+            manifest_data["sources"] = [
+                entry
+                for entry in manifest_data["sources"]
+                if entry["id"] == "andrej-karpathy-skills"
+            ]
+            manifest_dst.write_text(
+                json.dumps(manifest_data, indent=2) + "\n",
+                encoding="utf-8",
+            )
+            sync_src = ROOT / ".gitea" / "ci" / "sync_thirdparty_skills.sh"
+            sync_dst = repo / ".gitea" / "ci" / "sync_thirdparty_skills.sh"
+            shutil.copy2(sync_src, sync_dst)
+
+            sync_result = subprocess.run(
+                ["bash", ".gitea/ci/sync_thirdparty_skills.sh"],
+                cwd=repo,
+                capture_output=True,
+                text=True,
+            )
+            self.assertEqual(
+                sync_result.returncode, 0, msg=sync_result.stdout + sync_result.stderr
+            )
+
+            config_body = f"""
+[playbook]
+project_root = "{tmp_root}"
+playbook_root = "{CUSTOM_DEPLOY_ROOT}"
+install_mode = "snapshot"
+
+[install_skills]
+agents_home = "{target}"
+mode = "list"
+skills = ["karpathy-guidelines"]
+"""
+            config_path = tmp_root / "playbook.toml"
+            config_path.write_text(config_body, encoding="utf-8")
+
+            result = run_script(repo / "scripts" / "playbook.py", "-config", str(config_path))
+
+            skill_file = target / "skills" / "karpathy-guidelines" / "SKILL.md"
+            self.assertEqual(result.returncode, 0, msg=result.stdout + result.stderr)
+            self.assertTrue(skill_file.is_file())
+
+    def test_install_skills_rejects_removed_tsl_guide(self):
+        with tempfile.TemporaryDirectory() as tmp_dir:
+            target = Path(tmp_dir) / "agents"
+            config_body = f"""
+[playbook]
+project_root = "{tmp_dir}"
+playbook_root = "{CUSTOM_DEPLOY_ROOT}"
+install_mode = "snapshot"
+
+[install_skills]
+agents_home = "{target}"
+mode = "list"
+skills = ["tsl-guide"]
+"""
+            config_path = Path(tmp_dir) / "playbook.toml"
+            config_path.write_text(config_body, encoding="utf-8")
+
+            result = run_cli("-config", str(config_path))
+
+            self.assertNotEqual(result.returncode, 0)
+            self.assertIn("skill not found: tsl-guide", result.stdout + result.stderr)
+
+    def test_install_skills_rejects_codex_home(self):
+        with tempfile.TemporaryDirectory() as tmp_dir:
+            target = Path(tmp_dir) / "codex"
+            config_body = f"""
+[playbook]
+project_root = "{tmp_dir}"
+playbook_root = "{CUSTOM_DEPLOY_ROOT}"
+install_mode = "snapshot"
+
+[install_skills]
+codex_home = "{target}"
+mode = "list"
+skills = ["brainstorming"]
+"""
+            config_path = Path(tmp_dir) / "playbook.toml"
+            config_path.write_text(config_body, encoding="utf-8")
+
+            result = run_cli("-config", str(config_path))
+
+            self.assertNotEqual(result.returncode, 0)
+            self.assertIn("codex_home", result.stdout + result.stderr)
+
+    def test_external_clone_flow_rewrites_links_with_configured_playbook_root(self):
+        with tempfile.TemporaryDirectory() as tmp_dir:
+            root = Path(tmp_dir)
+            agents_home = root / "agents-home"
+            config_body = f"""
+[playbook]
+project_root = "{tmp_dir}"
+playbook_root = "{CUSTOM_DEPLOY_ROOT}"
+install_mode = "snapshot"
+
+[sync_standards]
+langs = ["tsl"]
+no_backup = true
+
+[install_skills]
+agents_home = "{agents_home}"
+mode = "list"
+skills = ["style-cleanup"]
+"""
+            config_path = write_config(root, "playbook.toml", config_body)
+
+            result = run_cli("-config", str(config_path))
+
+            self.assertEqual(result.returncode, 0, msg=result.stdout + result.stderr)
+            self.assertTrue((root / CUSTOM_DEPLOY_ROOT / "SOURCE.md").is_file())
+            self.assert_style_cleanup_tsl_docs_prefix(
+                root, agents_home, f"{CUSTOM_DEPLOY_ROOT}/docs"
+            )
+
+    def test_deployed_snapshot_rewrites_links_from_snapshot_location(self):
+        with tempfile.TemporaryDirectory() as tmp_dir:
+            root = Path(tmp_dir)
+            install_config = write_config(
+                root,
+                "install.toml",
+                f"""
+[playbook]
+project_root = "{tmp_dir}"
+playbook_root = "{CUSTOM_DEPLOY_ROOT}"
+install_mode = "snapshot"
+
+[sync_standards]
+langs = ["tsl"]
+""",
+            )
+
+            install_result = run_cli("-config", str(install_config))
+            self.assertEqual(
+                install_result.returncode,
+                0,
+                msg=install_result.stdout + install_result.stderr,
+            )
+
+            snapshot_script = root / CUSTOM_DEPLOY_ROOT / "scripts" / "playbook.py"
+            agents_home = root / "local-agents"
+            sync_config = write_config(
+                root,
+                "sync.toml",
+                f"""
+[playbook]
+project_root = "{tmp_dir}"
+playbook_root = "{CUSTOM_DEPLOY_ROOT}"
+install_mode = "snapshot"
+
+[sync_standards]
+langs = ["tsl"]
+no_backup = true
+
+[install_skills]
+agents_home = "{agents_home}"
+mode = "list"
+skills = ["style-cleanup"]
+""",
+            )
+
+            sync_result = run_script(snapshot_script, "-config", str(sync_config))
+            self.assertEqual(sync_result.returncode, 0, msg=sync_result.stdout + sync_result.stderr)
+            self.assert_style_cleanup_tsl_docs_prefix(
+                root, agents_home, f"{CUSTOM_DEPLOY_ROOT}/docs"
+            )
+
+    def test_sync_claude_md_creates_when_no_claude_md(self):
+        with tempfile.TemporaryDirectory() as tmp_dir:
+            config_body = f"""
+[playbook]
+project_root = "{tmp_dir}"
+playbook_root = "{CUSTOM_DEPLOY_ROOT}"
+install_mode = "snapshot"
+
+[sync_memory_bank]
+project_name = "Demo"
+"""
+            config_path = Path(tmp_dir) / "playbook.toml"
+            config_path.write_text(config_body, encoding="utf-8")
+
+            result = run_cli("-config", str(config_path))
+
+            self.assertEqual(result.returncode, 0)
+            claude_md = Path(tmp_dir) / "CLAUDE.md"
+            self.assertTrue(claude_md.exists())
+            text = claude_md.read_text(encoding="utf-8")
+            self.assertTrue(text.startswith("# CLAUDE.md\n\n"))
+            self.assertIn("@AGENTS.md", text)
+            self.assertIn("<!-- playbook:claude:start -->", text)
+
+    def test_sync_claude_md_appends_block_to_existing_claude_md(self):
+        with tempfile.TemporaryDirectory() as tmp_dir:
+            claude_md = Path(tmp_dir) / "CLAUDE.md"
+            claude_md.write_text("# My project\n\nSome existing content.\n", encoding="utf-8")
+
+            config_body = f"""
+[playbook]
+project_root = "{tmp_dir}"
+playbook_root = "{CUSTOM_DEPLOY_ROOT}"
+install_mode = "snapshot"
+
+[sync_memory_bank]
+project_name = "Demo"
+"""
+            config_path = Path(tmp_dir) / "playbook.toml"
+            config_path.write_text(config_body, encoding="utf-8")
+
+            result = run_cli("-config", str(config_path))
+
+            self.assertEqual(result.returncode, 0)
+            text = claude_md.read_text(encoding="utf-8")
+            self.assertIn("@AGENTS.md", text)
+            self.assertIn("@AGENT_RULES.md", text)
+            self.assertIn("<!-- playbook:claude:start -->", text)
+            self.assertIn("Some existing content.", text)
+
+    def test_sync_claude_md_updates_existing_block(self):
+        with tempfile.TemporaryDirectory() as tmp_dir:
+            claude_md = Path(tmp_dir) / "CLAUDE.md"
+            claude_md.write_text(
+                "# My project\n\n"
+                "<!-- playbook:claude:start -->\n"
+                "@AGENTS.md\n"
+                "<!-- playbook:claude:end -->\n",
+                encoding="utf-8",
+            )
+
+            config_body = f"""
+[playbook]
+project_root = "{tmp_dir}"
+playbook_root = "{CUSTOM_DEPLOY_ROOT}"
+install_mode = "snapshot"
+
+[sync_memory_bank]
+project_name = "Demo"
+"""
+            config_path = Path(tmp_dir) / "playbook.toml"
+            config_path.write_text(config_body, encoding="utf-8")
+
+            result = run_cli("-config", str(config_path))
+
+            self.assertEqual(result.returncode, 0)
+            text = claude_md.read_text(encoding="utf-8")
+            self.assertIn("@AGENTS.md", text)
+            self.assertIn("@AGENT_RULES.md", text)
+            self.assertEqual(text.count("<!-- playbook:claude:start -->"), 1)
+
+    def test_sync_claude_md_adds_heading_to_generated_block(self):
+        with tempfile.TemporaryDirectory() as tmp_dir:
+            claude_md = Path(tmp_dir) / "CLAUDE.md"
+            claude_md.write_text(
+                "<!-- playbook:claude:start -->\n"
+                "\n"
+                "@AGENTS.md\n"
+                "@AGENT_RULES.md\n"
+                "\n"
+                "<!-- playbook:claude:end -->\n",
+                encoding="utf-8",
+            )
+
+            config_body = f"""
+[playbook]
+project_root = "{tmp_dir}"
+playbook_root = "{CUSTOM_DEPLOY_ROOT}"
+install_mode = "snapshot"
+
+[sync_memory_bank]
+project_name = "Demo"
+"""
+            config_path = Path(tmp_dir) / "playbook.toml"
+            config_path.write_text(config_body, encoding="utf-8")
+
+            result = run_cli("-config", str(config_path))
+
+            self.assertEqual(result.returncode, 0)
+            text = claude_md.read_text(encoding="utf-8")
+            self.assertTrue(text.startswith("# CLAUDE.md\n\n"))
+            self.assertIn("@AGENTS.md", text)
+            self.assertIn("@AGENT_RULES.md", text)
+            self.assertEqual(text.count("<!-- playbook:claude:start -->"), 1)
+
+    def test_sync_claude_md_skips_when_already_references_agents(self):
+        with tempfile.TemporaryDirectory() as tmp_dir:
+            claude_md = Path(tmp_dir) / "CLAUDE.md"
+            original = "# My project\n\n@AGENTS.md\n"
+            claude_md.write_text(original, encoding="utf-8")
+
+            config_body = f"""
+[playbook]
+project_root = "{tmp_dir}"
+playbook_root = "{CUSTOM_DEPLOY_ROOT}"
+install_mode = "snapshot"
+
+[sync_memory_bank]
+project_name = "Demo"
+"""
+            config_path = Path(tmp_dir) / "playbook.toml"
+            config_path.write_text(config_body, encoding="utf-8")
+
+            result = run_cli("-config", str(config_path))
+
+            self.assertEqual(result.returncode, 0)
+            self.assertEqual(claude_md.read_text(encoding="utf-8"), original)
+
+
+    def test_install_skills_creates_symlink_when_skill_link_configured(self):
+        with tempfile.TemporaryDirectory() as tmp_dir:
+            root = Path(tmp_dir)
+            agents_home = root / "agents"
+            link_home = root / "claude"
+            config_body = f"""
+[playbook]
+project_root = "{tmp_dir}"
+playbook_root = "{CUSTOM_DEPLOY_ROOT}"
+install_mode = "snapshot"
+
+[install_skills]
+agents_home = "{agents_home}"
+skill_link = "{link_home}"
+mode = "list"
+skills = ["commit-message"]
+"""
+            config_path = root / "playbook.toml"
+            config_path.write_text(config_body, encoding="utf-8")
+
+            result = run_cli("-config", str(config_path))
+
+            self.assertEqual(result.returncode, 0, msg=result.stdout + result.stderr)
+            skills_dst = agents_home / "skills"
+            link_path = link_home / "skills"
+            self.assertTrue(skills_dst.is_dir())
+            self.assertTrue(link_path.is_dir(), "link_path should be accessible as dir")
+            self.assertEqual(link_path.resolve(), skills_dst.resolve())
+            self.assertTrue((link_path / "commit-message" / "SKILL.md").is_file())
+
+    def test_install_skills_symlink_is_idempotent(self):
+        with tempfile.TemporaryDirectory() as tmp_dir:
+            root = Path(tmp_dir)
+            agents_home = root / "agents"
+            link_home = root / "claude"
+            config_body = f"""
+[playbook]
+project_root = "{tmp_dir}"
+playbook_root = "{CUSTOM_DEPLOY_ROOT}"
+install_mode = "snapshot"
+
+[install_skills]
+agents_home = "{agents_home}"
+skill_link = "{link_home}"
+mode = "list"
+skills = ["commit-message"]
+no_backup = true
+"""
+            config_path = root / "playbook.toml"
+            config_path.write_text(config_body, encoding="utf-8")
+
+            run_cli("-config", str(config_path))
+            result = run_cli("-config", str(config_path))
+
+            self.assertEqual(result.returncode, 0, msg=result.stdout + result.stderr)
+            self.assertTrue((link_home / "skills").is_dir())
+
+    def test_install_skills_no_symlink_when_skill_link_absent(self):
+        with tempfile.TemporaryDirectory() as tmp_dir:
+            root = Path(tmp_dir)
+            agents_home = root / "agents"
+            config_body = f"""
+[playbook]
+project_root = "{tmp_dir}"
+playbook_root = "{CUSTOM_DEPLOY_ROOT}"
+install_mode = "snapshot"
+
+[install_skills]
+agents_home = "{agents_home}"
+mode = "list"
+skills = ["commit-message"]
+"""
+            config_path = root / "playbook.toml"
+            config_path.write_text(config_body, encoding="utf-8")
+
+            result = run_cli("-config", str(config_path))
+
+            self.assertEqual(result.returncode, 0, msg=result.stdout + result.stderr)
+            self.assertFalse(any(
+                p.is_symlink() for p in (agents_home / "skills").iterdir()
+                if p.is_symlink()
+            ) if (agents_home / "skills").exists() else False)
+
+
 if __name__ == "__main__":
     unittest.main()

tests/cli/test_sync_standards_cli.py

@@ -1,143 +0,0 @@
-import subprocess
-import sys
-import tempfile
-import unittest
-from pathlib import Path
-
-ROOT = Path(__file__).resolve().parents[2]
-SCRIPT = ROOT / "scripts" / "playbook.py"
-CUSTOM_DEPLOY_ROOT = "custom/playbook"
-
-
-def run_cli(*args):
-    return subprocess.run(
-        [sys.executable, str(SCRIPT), *args],
-        capture_output=True,
-        text=True,
-    )
-
-
-def write_config(root: Path, name: str, body: str) -> Path:
-    config_path = root / name
-    config_path.write_text(body, encoding="utf-8")
-    return config_path
-
-
-class SyncStandardsCliTests(unittest.TestCase):
-    def test_sync_standards_creates_agents(self):
-        with tempfile.TemporaryDirectory() as tmp_dir:
-            config_body = f"""
-[playbook]
-project_root = "{tmp_dir}"
-playbook_root = "{CUSTOM_DEPLOY_ROOT}"
-install_mode = "snapshot"
-
-[sync_standards]
-langs = ["tsl"]
-"""
-            config_path = Path(tmp_dir) / "playbook.toml"
-            config_path.write_text(config_body, encoding="utf-8")
-
-            result = run_cli("-config", str(config_path))
-
-            agents_index = Path(tmp_dir) / ".agents/tsl/index.md"
-            self.assertEqual(result.returncode, 0)
-            self.assertTrue(agents_index.is_file())
-
-    def test_sync_standards_updates_agents_index_when_langs_expand(self):
-        with tempfile.TemporaryDirectory() as tmp_dir:
-            root = Path(tmp_dir)
-
-            first_config = root / "playbook-first.toml"
-            first_config.write_text(
-                f"""
-[playbook]
-project_root = "{tmp_dir}"
-playbook_root = "{CUSTOM_DEPLOY_ROOT}"
-install_mode = "snapshot"
-
-[sync_standards]
-langs = ["tsl"]
-no_backup = true
-""",
-                encoding="utf-8",
-            )
-
-            first_result = run_cli("-config", str(first_config))
-            self.assertEqual(first_result.returncode, 0)
-
-            second_config = root / "playbook-second.toml"
-            second_config.write_text(
-                f"""
-[playbook]
-project_root = "{tmp_dir}"
-playbook_root = "{CUSTOM_DEPLOY_ROOT}"
-install_mode = "snapshot"
-
-[sync_standards]
-langs = ["tsl", "cpp"]
-no_backup = true
-""",
-                encoding="utf-8",
-            )
-
-            second_result = run_cli("-config", str(second_config))
-            self.assertEqual(second_result.returncode, 0)
-
-            agents_index = (root / ".agents" / "index.md").read_text(encoding="utf-8")
-            self.assertIn("`.agents/tsl/index.md`", agents_index)
-            self.assertIn("`.agents/cpp/index.md`", agents_index)
-
-    def test_sync_standards_agents_index_only_lists_configured_langs(self):
-        with tempfile.TemporaryDirectory() as tmp_dir:
-            root = Path(tmp_dir)
-            config_body = f"""
-[playbook]
-project_root = "{tmp_dir}"
-playbook_root = "{CUSTOM_DEPLOY_ROOT}"
-install_mode = "snapshot"
-
-[sync_standards]
-langs = ["tsl", "markdown"]
-"""
-            config_path = write_config(root, "playbook.toml", config_body)
-
-            result = run_cli("-config", str(config_path))
-            self.assertEqual(result.returncode, 0, msg=result.stdout + result.stderr)
-
-            agents_index = (root / ".agents" / "index.md").read_text(encoding="utf-8")
-            self.assertIn("`.agents/tsl/`：TSL 相关规则集", agents_index)
-            self.assertIn("`.agents/markdown/`：Markdown 相关规则集", agents_index)
-            self.assertNotIn("`.agents/cpp/`", agents_index)
-            self.assertNotIn("`.agents/python/`", agents_index)
-            self.assertNotIn("`.agents/typescript/`", agents_index)
-
-    def test_sync_standards_agents_block_has_blank_lines(self):
-        with tempfile.TemporaryDirectory() as tmp_dir:
-            config_body = f"""
-[playbook]
-project_root = "{tmp_dir}"
-playbook_root = "{CUSTOM_DEPLOY_ROOT}"
-install_mode = "snapshot"
-
-[sync_standards]
-langs = ["tsl"]
-"""
-            config_path = Path(tmp_dir) / "playbook.toml"
-            config_path.write_text(config_body, encoding="utf-8")
-
-            result = run_cli("-config", str(config_path))
-            self.assertEqual(result.returncode, 0)
-
-            agents_md = Path(tmp_dir) / "AGENTS.md"
-            lines = agents_md.read_text(encoding="utf-8").splitlines()
-            start_idx = lines.index("<!-- playbook:agents:start -->")
-            end_idx = lines.index("<!-- playbook:agents:end -->")
-            block = lines[start_idx : end_idx + 1]
-            self.assertEqual(block[1], "")
-            bullet_idx = next(i for i, line in enumerate(block) if line.startswith("- "))
-            self.assertEqual(block[bullet_idx - 1], "")
-
-
-if __name__ == "__main__":
-    unittest.main()

tests/test_deployment_routes_e2e.py

@@ -169,28 +169,11 @@ no_backup = true
             snapshot_root = project_root / CUSTOM_DEPLOY_ROOT
             self.assertTrue((snapshot_root / "SOURCE.md").is_file())
             self.assertTrue((snapshot_root / "scripts" / "playbook.py").is_file())
-            self.assertTrue(
-                (snapshot_root / "templates" / "AGENTS.template.md").is_file()
-            )
-            self.assertTrue(
-                (snapshot_root / "templates" / "AGENT_RULES.template.md").is_file()
-            )
             self.assertTrue((snapshot_root / "templates" / "README.md").is_file())
-            self.assertTrue((snapshot_root / "templates" / "memory-bank").is_dir())
-            self.assertTrue((snapshot_root / "templates" / "prompts").is_dir())
-            self.assertTrue((snapshot_root / "skills").is_dir())
-            self.assertFalse((snapshot_root / "codex").exists())
 
             self.assert_core_project_files(project_root)
             self.assert_docs_prefix(project_root, "custom/playbook/docs")
 
-            rules_text = (project_root / "AGENT_RULES.md").read_text(encoding="utf-8")
-            self.assertIn(
-                "`custom/playbook/` 是 Playbook 模板/供应商目录",
-                rules_text,
-            )
-            self.assertNotIn("{{PLAYBOOK_ROOT}}", rules_text)
-
             text = claude_md.read_text(encoding="utf-8")
             self.assertIn("Keep this.", text)
             self.assertIn("@../AGENTS.md", text)

tests/test_playbook_typing_imports.py

@@ -0,0 +1,32 @@
+import ast
+import unittest
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[1]
+PLAYBOOK_SCRIPT = ROOT / "scripts" / "playbook.py"
+
+
+class PlaybookTypingImportTests(unittest.TestCase):
+    def test_optional_annotation_names_are_imported(self):
+        tree = ast.parse(PLAYBOOK_SCRIPT.read_text(encoding="utf-8"))
+
+        imported_names: set[str] = set()
+        referenced_names: set[str] = set()
+
+        for node in ast.walk(tree):
+            if isinstance(node, ast.Import):
+                for alias in node.names:
+                    imported_names.add(alias.asname or alias.name.split(".")[0])
+            elif isinstance(node, ast.ImportFrom):
+                for alias in node.names:
+                    imported_names.add(alias.asname or alias.name)
+            elif isinstance(node, ast.Name):
+                referenced_names.add(node.id)
+
+        if "Optional" in referenced_names:
+            self.assertIn("Optional", imported_names)
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_readme_language_lists.py

@@ -0,0 +1,15 @@
+import unittest
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+README = ROOT / "README.md"
+
+
+class ReadmeLanguageListsTests(unittest.TestCase):
+    def test_rulesets_list_includes_typescript(self):
+        text = README.read_text(encoding="utf-8")
+        self.assertIn("- `rulesets/typescript/index.md`：TypeScript 核心约定", text)
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_sync_templates_placeholders.py

@@ -27,7 +27,7 @@ def run_script(script_path: Path, *args, cwd: Path | None = None):
 
 
 class SyncTemplatesPlaceholdersTests(unittest.TestCase):
-    def test_project_templates_drop_legacy_language_placeholders(self):
+    def test_templates_no_longer_expose_main_language_placeholder(self):
         example_text = (ROOT / "playbook.toml.example").read_text(encoding="utf-8")
         self.assertNotIn("main_language", example_text)
 
@@ -62,7 +62,6 @@ class SyncTemplatesPlaceholdersTests(unittest.TestCase):
         ).read_text(encoding="utf-8")
         self.assertIn("## 成功定义", project_brief_template)
 
-    def test_memory_bank_templates_capture_short_lived_context_contracts(self):
         progress_template = (
             ROOT / "templates" / "memory-bank" / "progress.template.md"
         ).read_text(encoding="utf-8")
@@ -81,7 +80,6 @@ class SyncTemplatesPlaceholdersTests(unittest.TestCase):
         )
         self.assertIn("整理/替换旧上下文，不做无限追加", active_context_template)
 
-    def test_prompt_templates_point_to_current_superpowers_flow(self):
         update_memory_template = (
             ROOT / "templates" / "prompts" / "coding" / "update-memory.template.md"
         ).read_text(encoding="utf-8")
@@ -175,13 +173,10 @@ class SyncTemplatesPlaceholdersTests(unittest.TestCase):
             "项目上下文与执行状态写入 `memory-bank/`", agent_behavior_template
         )
 
-    def test_agent_rules_template_defines_plan_and_archival_contracts(self):
         rules_template = (ROOT / "templates" / "AGENT_RULES.template.md").read_text(
             encoding="utf-8"
         )
         self.assertIn("唯一流程约束中心", rules_template)
-        self.assertIn("{{PLAYBOOK_ROOT}}", rules_template)
-        self.assertIn("Playbook 模板/供应商目录", rules_template)
         self.assertIn("唯一设计与计划产物中心", rules_template)
         self.assertIn("memory-bank/progress.md", rules_template)
         self.assertIn("已有 `in-progress` 优先恢复", rules_template)
@@ -260,14 +255,6 @@ langs = [\"cpp\", \"tsl\"]
                 "docs/standards/playbook/scripts/main_loop.py claim",
                 rules_text,
             )
-            self.assertIn(
-                "`docs/standards/playbook/` 是 Playbook 模板/供应商目录",
-                rules_text,
-            )
-            self.assertIn(
-                "默认排除 `docs/standards/playbook/`",
-                rules_text,
-            )
             self.assertIn("docs/superpowers/plans", rules_text)
             self.assertNotIn("plan_progress.py", rules_text)
             self.assertIn("记录 `phase=planning` 与 `spec=<path>`", rules_text)
@@ -279,7 +266,6 @@ langs = [\"cpp\", \"tsl\"]
             self.assertIn("默认执行使用 `$executing-plans`", rules_text)
             self.assertIn("不是默认执行器", rules_text)
             self.assertNotIn("{{PLAYBOOK_SCRIPTS}}", rules_text)
-            self.assertNotIn("{{PLAYBOOK_ROOT}}", rules_text)
             self.assertFalse(rules_text.endswith("\n\n"))
 
     def test_sync_standards_rewrites_typescript_docs_prefix_for_snapshot_playbook(self):

tests/test_tsl_entrypoints_consistency.py

@@ -65,7 +65,6 @@ class TslEntrypointsConsistencyTests(unittest.TestCase):
         text = README.read_text(encoding="utf-8")
         self.assertIn("方式一：git subtree", text)
         self.assertIn("方式二：外部 clone 后执行部署", text)
-        self.assertIn("- `rulesets/typescript/index.md`：TypeScript 核心约定", text)
         self.assertIn("`project_root`：目标项目根目录", text)
         self.assertIn("`playbook_root`：相对于 `project_root` 的项目内 Playbook 根目录", text)
         self.assertIn("不是外部 clone 出来的 Playbook 仓库路径", text)

tests/test_vendor_snapshot_templates.py

@@ -0,0 +1,49 @@
+import subprocess
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+SCRIPT = ROOT / "scripts" / "playbook.py"
+DEFAULT_DEPLOY_ROOT = "docs/standards/playbook"
+
+
+def run_cli(*args):
+    return subprocess.run(
+        [sys.executable, str(SCRIPT), *args],
+        capture_output=True,
+        text=True,
+    )
+
+
+class SnapshotTemplatesTests(unittest.TestCase):
+    def test_snapshot_install_includes_core_templates(self):
+        with tempfile.TemporaryDirectory() as tmp_dir:
+            config_body = f"""
+[playbook]
+project_root = "{tmp_dir}"
+playbook_root = "{DEFAULT_DEPLOY_ROOT}"
+install_mode = "snapshot"
+
+[sync_standards]
+langs = ["tsl"]
+"""
+            config_path = Path(tmp_dir) / "playbook.toml"
+            config_path.write_text(config_body, encoding="utf-8")
+
+            result = run_cli("-config", str(config_path))
+            self.assertEqual(result.returncode, 0, msg=result.stderr)
+
+            snapshot = Path(tmp_dir) / "docs/standards/playbook"
+            self.assertTrue((snapshot / "templates/AGENTS.template.md").is_file())
+            self.assertTrue((snapshot / "templates/AGENT_RULES.template.md").is_file())
+            self.assertTrue((snapshot / "templates/README.md").is_file())
+            self.assertTrue((snapshot / "templates/memory-bank").is_dir())
+            self.assertTrue((snapshot / "templates/prompts").is_dir())
+            self.assertTrue((snapshot / "skills").is_dir())
+            self.assertFalse((snapshot / "codex").exists())
+
+
+if __name__ == "__main__":
+    unittest.main()