Squashed 'docs/standards/playbook/' changes from e504a68..b529012

b529012 ✅ test(tests): avoid hardcoded missing path 07583c8 🐛 fix(tests): make doc link check awk-portable 6244aa3 🔧 chore(ci): relax gitattributes check 31dd0c5 🐛 fix(scripts): require existing project root 15d4d63 🔧 chore(ci): install python3-pip 90c6313 🔧 chore(ci): run tests in a single job d84eff0 🔧 chore(ci): make actions base url configurable 395598d 🔧 chore(ci): fix yaml step names 4ae2733 ✨ feat(sync_standards): auto-detect existing languages e97fb00 ✨ feat(sync_standards): default gitattributes to append da0ef2b ✅ test: add automated tests and ci workflow 99bef30 🎨 style(markdown): format all markdown files with prettier 7e96bc8 ♻️ refactor(tsl): split function.md into 44 modular files 0d6b2a0 📝 docs(readme): add quick decision table and TL;DR for distribution methods 3b2188f 🎨 style(markdown): format markdown files with prettier 41fc43b 📝 docs(tsl): document {Unit.}Type source annotation 3dceaf7 📝 docs(tsl): clarify tsf-only top-level rules and type annotations 3a63829 📝 docs(skills): add create-plan skill f02a707 🐛 fix(scripts): escape markdown backticks in vendor_playbook 064aa92 🐛 fix(scripts): correct bat scripts 4881feb 🔧 chore(gitattributes): enforce crlf for bat files 1fa3e2a 🐛 fix(scripts): escape parentheses in sync_standards output 3958cad 📝 docs(vendor_playbook): mention ci templates 9d059cf ✨ feat(templates): add gitea ci example a52bb24 📝 docs(codex_skills): normalize markdown formatting cc8ad4c 📝 docs(skills): slim commit-message 2a98e15 🐛 fix(skills): quote YAML descriptions 8f78d22 🐛 fix(sync_standards): generate minimal AGENTS.md 5547665 ✨ feat(skills): add commit-message suggestion skill 3fe8bd7 🔧 chore(sync_standards): create AGENTS.md on sync 283d311 ✨ feat(playbook): add syntax book and codex skills tooling 5b97ed5 📝 docs(tsl): clarify syntax references 27e0700 ✨ feat(skills): add pdf/docx/pptx/xlsx wrapper workflows 5551363 ✨ feat(skills): add debugging and bulk refactor workflows 1d4f548 ✨ feat(skills): add built-in workflow skills c0895dd 📝 docs(skills): add anthropics document-skills integration cf9f80d 🔧 chore(playbook): add Claude Code skills guide and align python templates git-subtree-dir: docs/standards/playbook git-subtree-split: b529012c59c5d67c3073884d7b617763647417fd
2026-01-08 15:56:36 +08:00
parent eada742d75
commit ac794a6a70
113 changed files with 254751 additions and 176 deletions
@@ -0,0 +1,75 @@
+@echo off
+setlocal enabledelayedexpansion
+
+rem Install Codex skills from this Playbook snapshot into CODEX_HOME.
+rem - Source: <snapshot>\codex\skills\<skill-name>\
+rem - Dest:   %CODEX_HOME%\skills\<skill-name>\  (default CODEX_HOME=%USERPROFILE%\.codex)
+rem
+rem Usage:
+rem   install_codex_skills.bat
+rem   install_codex_skills.bat style-cleanup code-review-workflow
+rem
+rem Notes:
+rem - Codex loads skills at startup; restart `codex` after installation.
+rem - Existing destination skill dirs are backed up with a random suffix.
+
+set "SCRIPT_DIR=%~dp0"
+for %%I in ("%SCRIPT_DIR%..") do set "SRC=%%~fI"
+set "SKILLS_SRC_ROOT=%SRC%\\codex\\skills"
+
+set "CODEX_HOME=%CODEX_HOME%"
+if "%CODEX_HOME%"=="" set "CODEX_HOME=%USERPROFILE%\\.codex"
+set "SKILLS_DST_ROOT=%CODEX_HOME%\\skills"
+
+if not exist "%SKILLS_SRC_ROOT%" (
+  echo ERROR: skills source dir not found: "%SKILLS_SRC_ROOT%"
+  exit /b 1
+)
+
+if not exist "%SKILLS_DST_ROOT%" mkdir "%SKILLS_DST_ROOT%"
+
+set "HAS_ARGS=0"
+if not "%~1"=="" set "HAS_ARGS=1"
+
+if "%HAS_ARGS%"=="1" (
+  for %%S in (%*) do call :InstallOne "%%~S"
+  goto Done
+)
+
+for /d %%D in ("%SKILLS_SRC_ROOT%\\*") do (
+  set "NAME=%%~nD"
+  if not "!NAME!"=="" if not "!NAME:~0,1!"=="." call :InstallOne "!NAME!"
+)
+
+:Done
+echo Done. Skills installed to: "%SKILLS_DST_ROOT%"
+endlocal
+exit /b 0
+
+:InstallOne
+set "NAME=%~1"
+set "SRC_DIR=%SKILLS_SRC_ROOT%\\%NAME%"
+set "DST_DIR=%SKILLS_DST_ROOT%\\%NAME%"
+
+if not exist "%SRC_DIR%" (
+  echo ERROR: skill not found: %NAME% "%SRC_DIR%"
+  exit /b 1
+)
+
+if exist "%DST_DIR%" (
+  set "RAND=%RANDOM%"
+  pushd "%SKILLS_DST_ROOT%"
+  ren "%NAME%" "%NAME%.bak.!RAND!"
+  popd
+  echo Backed up existing skill: %NAME% -> %NAME%.bak.!RAND!
+)
+
+xcopy "%SRC_DIR%\\*" "%DST_DIR%\\" /e /i /y >nul
+if errorlevel 1 (
+  echo ERROR: failed to copy skill: %NAME%
+  exit /b 1
+)
+
+echo Installed: %NAME%
+exit /b 0
+
@@ -0,0 +1,70 @@
+# Install Codex skills from this Playbook snapshot into CODEX_HOME.
+# - Source: <snapshot>\codex\skills\<skill-name>\
+# - Dest:   $env:CODEX_HOME\skills\<skill-name>\  (default CODEX_HOME=$HOME\.codex)
+#
+# Usage:
+#   powershell -File scripts/install_codex_skills.ps1
+#   powershell -File scripts/install_codex_skills.ps1 style-cleanup code-review-workflow
+#
+# Notes:
+# - Codex loads skills at startup; restart `codex` after installation.
+# - Existing destination skill dirs are backed up with a timestamp suffix.
+
+[CmdletBinding()]
+param(
+  [Parameter(Mandatory = $false, ValueFromRemainingArguments = $true)]
+  [string[]]$Skills
+)
+
+$ErrorActionPreference = "Stop"
+$ScriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
+$Src = (Resolve-Path (Join-Path $ScriptDir "..")).Path
+$SkillsSrcRoot = Join-Path $Src "codex/skills"
+
+if (-not (Test-Path $SkillsSrcRoot)) {
+  throw "Skills source dir not found: $SkillsSrcRoot"
+}
+
+$CodexHome = $env:CODEX_HOME
+if (-not $CodexHome) {
+  $homeDir = $HOME
+  if (-not $homeDir) { $homeDir = $env:USERPROFILE }
+  $CodexHome = (Join-Path $homeDir ".codex")
+}
+$SkillsDstRoot = Join-Path $CodexHome "skills"
+New-Item -ItemType Directory -Path $SkillsDstRoot -Force | Out-Null
+
+$timestamp = Get-Date -Format "yyyyMMddHHmmss"
+
+function Install-One([string]$Name) {
+  $srcDir = Join-Path $SkillsSrcRoot $Name
+  $dstDir = Join-Path $SkillsDstRoot $Name
+
+  if (-not (Test-Path $srcDir)) {
+    throw "Skill not found: $Name ($srcDir)"
+  }
+
+  if (Test-Path $dstDir) {
+    $bak = Join-Path $SkillsDstRoot "$Name.bak.$timestamp"
+    Move-Item $dstDir $bak
+    Write-Host "Backed up existing skill: $Name -> $(Split-Path -Leaf $bak)"
+  }
+
+  Copy-Item $srcDir $dstDir -Recurse -Force
+  Write-Host "Installed: $Name"
+}
+
+if ($Skills -and $Skills.Count -gt 0) {
+  foreach ($name in $Skills) {
+    if (-not $name) { continue }
+    Install-One $name
+  }
+} else {
+  foreach ($dir in (Get-ChildItem -Path $SkillsSrcRoot -Directory)) {
+    if ($dir.Name.StartsWith(".")) { continue }
+    Install-One $dir.Name
+  }
+}
+
+Write-Host "Done. Skills installed to: $SkillsDstRoot"
+
@@ -0,0 +1,64 @@
+#!/usr/bin/env sh
+set -eu
+
+# Install Codex skills from this Playbook snapshot into CODEX_HOME.
+# - Source: <snapshot>/codex/skills/<skill-name>/
+# - Dest:   $CODEX_HOME/skills/<skill-name>/  (default CODEX_HOME=~/.codex)
+#
+# Usage:
+#   sh scripts/install_codex_skills.sh            # install all skills
+#   sh scripts/install_codex_skills.sh style-cleanup code-review-workflow
+#
+# Notes:
+# - Codex loads skills at startup; restart `codex` after installation.
+# - Existing destination skill dirs are backed up with a timestamp suffix.
+
+SCRIPT_DIR="$(CDPATH= cd -- "$(dirname -- "$0")" && pwd -P)"
+SRC="$(CDPATH= cd -- "$SCRIPT_DIR/.." && pwd -P)"
+SKILLS_SRC_ROOT="$SRC/codex/skills"
+
+CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
+SKILLS_DST_ROOT="$CODEX_HOME/skills"
+
+if [ ! -d "$SKILLS_SRC_ROOT" ]; then
+  echo "ERROR: skills source dir not found: $SKILLS_SRC_ROOT" >&2
+  exit 1
+fi
+
+mkdir -p "$SKILLS_DST_ROOT"
+timestamp="$(date +%Y%m%d%H%M%S 2>/dev/null || echo bak)"
+
+install_one() {
+  name="$1"
+  src_dir="$SKILLS_SRC_ROOT/$name"
+  dst_dir="$SKILLS_DST_ROOT/$name"
+
+  if [ ! -d "$src_dir" ]; then
+    echo "ERROR: skill not found: $name ($src_dir)" >&2
+    exit 1
+  fi
+  if [ -e "$dst_dir" ]; then
+    mv "$dst_dir" "$SKILLS_DST_ROOT/$name.bak.$timestamp"
+    echo "Backed up existing skill: $name -> $name.bak.$timestamp"
+  fi
+  cp -R "$src_dir" "$dst_dir"
+  echo "Installed: $name"
+}
+
+if [ "$#" -gt 0 ]; then
+  for name in "$@"; do
+    install_one "$name"
+  done
+else
+  for dir in "$SKILLS_SRC_ROOT"/*; do
+    [ -d "$dir" ] || continue
+    name="$(basename -- "$dir")"
+    case "$name" in
+      ""|.*) continue ;;
+    esac
+    install_one "$name"
+  done
+fi
+
+echo "Done. Skills installed to: $SKILLS_DST_ROOT"
+
@@ -3,7 +3,7 @@ setlocal enabledelayedexpansion

 rem Sync standards snapshot to project root.
 rem - Copies <snapshot>\.agents\<AGENTS_NS> -> <project-root>\.agents\<AGENTS_NS>
-rem - Updates <project-root>\.gitattributes (managed block by default)
+rem - Updates <project-root>\.gitattributes (append missing rules by default)
 rem Existing targets are backed up before overwrite.
 rem
 rem Multi rulesets:
@@ -12,7 +12,8 @@ rem Notes:
 rem - When syncing multiple rulesets, .gitattributes is synced only once (first ruleset).

 set "SCRIPT_DIR=%~dp0"
-for /f "delims=" %%R in ('git -C "%SCRIPT_DIR%" rev-parse --show-toplevel 2^>nul') do set "ROOT=%%R"
+set "ROOT=%SYNC_ROOT%"
+if "%ROOT%"=="" for /f "delims=" %%R in ('git -C "%SCRIPT_DIR%" rev-parse --show-toplevel 2^>nul') do set "ROOT=%%R"
 if "%ROOT%"=="" set "ROOT=%cd%"
 for %%I in ("%ROOT%") do set "ROOT=%%~fI"

@@ -20,27 +21,30 @@ for %%I in ("%SCRIPT_DIR%..") do set "SRC=%%~fI"
 set "AGENTS_SRC_ROOT=%SRC%\.agents"
 set "GITATTR_SRC=%SRC%\.gitattributes"
 set "AGENTS_NS=%AGENTS_NS%"
-if "%AGENTS_NS%"=="" set "AGENTS_NS=tsl"
-echo %AGENTS_NS%| findstr /r "[\\/]" >nul && (
-  echo ERROR: invalid AGENTS_NS=%AGENTS_NS%
-  exit /b 1
-)
-echo %AGENTS_NS%| findstr /c:".." >nul && (
-  echo ERROR: invalid AGENTS_NS=%AGENTS_NS%
-  exit /b 1
-)
-set "AGENTS_ROOT=%ROOT%\.agents"
-set "AGENTS_DST=%AGENTS_ROOT%\%AGENTS_NS%"
 set "GITATTR_DST=%ROOT%\.gitattributes"
 set "SYNC_GITATTR_MODE=%SYNC_GITATTR_MODE%"
-if "%SYNC_GITATTR_MODE%"=="" set "SYNC_GITATTR_MODE=block"
+if "%SYNC_GITATTR_MODE%"=="" set "SYNC_GITATTR_MODE=append"

 rem Multi rulesets: only on outer invocation.
 if "%SYNC_STANDARDS_INNER%"=="" (
-  if not "%~1"=="" (
+  set "LANG_LIST="
+  if not "%~1"=="" set "LANG_LIST=%*"
+  if "%LANG_LIST%"=="" (
+    if "%AGENTS_NS%"=="" (
+      if exist "%ROOT%\.agents" (
+        for /d %%D in ("%ROOT%\.agents\*") do (
+          set "CAND=%%~nxD"
+          if exist "%AGENTS_SRC_ROOT%\!CAND!\" (
+            if defined LANG_LIST (set "LANG_LIST=!LANG_LIST! !CAND!") else set "LANG_LIST=!CAND!"
+          )
+        )
+      )
+    )
+  )
+  if not "%LANG_LIST%"=="" (
    set "FIRST=1"
    set "SYNC_FIRST=%SYNC_GITATTR_MODE%"
-    for %%L in (%*) do (
+    for %%L in (!LANG_LIST!) do (
      if "!FIRST!"=="1" (
        set "FIRST=0"
        set "SYNC_STANDARDS_INNER=1"
@@ -58,14 +62,26 @@ if "%SYNC_STANDARDS_INNER%"=="" (
  )
 )

+if "%AGENTS_NS%"=="" set "AGENTS_NS=tsl"
+echo %AGENTS_NS%| findstr /r "[\\/]" >nul && (
+  echo ERROR: invalid AGENTS_NS=%AGENTS_NS%
+  exit /b 1
+)
+echo %AGENTS_NS%| findstr /c:".." >nul && (
+  echo ERROR: invalid AGENTS_NS=%AGENTS_NS%
+  exit /b 1
+)
+set "AGENTS_ROOT=%ROOT%\.agents"
+set "AGENTS_DST=%AGENTS_ROOT%\%AGENTS_NS%"
+
 set "AGENTS_SRC=%AGENTS_SRC_ROOT%\%AGENTS_NS%"
 if not exist "%AGENTS_SRC%" (
-  rem Backward-compatible fallback: older snapshots used <snapshot>\.agents\* directly.
+  rem Backward-compatible fallback: older snapshots used ^<snapshot^>\.agents\* directly.
  if exist "%AGENTS_SRC_ROOT%\index.md" if exist "%AGENTS_SRC_ROOT%\auth.md" (
    set "AGENTS_SRC=%AGENTS_SRC_ROOT%"
  ) else (
    echo ERROR: Standards snapshot not found at "%AGENTS_SRC%".
-    echo Hint: set AGENTS_NS to one of the subdirs under "%AGENTS_SRC_ROOT%" (e.g. tsl/cpp).
+    echo Hint: set AGENTS_NS to one of the subdirs under "%AGENTS_SRC_ROOT%" ^(e.g. tsl/cpp^).
    exit /b 1
  )
 )
@@ -119,6 +135,15 @@ if not exist "%AGENTS_ROOT%\index.md" (
  echo Created .agents\index.md
 )

+if not exist "%ROOT%\AGENTS.md" (
+  > "%ROOT%\AGENTS.md" echo # Agent Instructions
+  >> "%ROOT%\AGENTS.md" echo.
+  >> "%ROOT%\AGENTS.md" echo 请以 `.agents/` 下的规则为准：
+  >> "%ROOT%\AGENTS.md" echo.
+  >> "%ROOT%\AGENTS.md" echo - 入口：`.agents/index.md`
+  echo Created AGENTS.md
+)
+
 :SyncGitAttr
 if exist "%GITATTR_SRC%" (
  if /I "%SYNC_GITATTR_MODE%"=="skip" (
@@ -145,8 +170,84 @@ if exist "%GITATTR_SRC%" (
    goto AfterGitAttr
  )

+  if /I "%SYNC_GITATTR_MODE%"=="append" (
+    for %%I in ("%GITATTR_SRC%") do set "GITATTR_SRC_F=%%~fI"
+    for %%I in ("%GITATTR_DST%") do set "GITATTR_DST_F=%%~fI"
+    if /I "!GITATTR_SRC_F!"=="!GITATTR_DST_F!" (
+      echo Skip: .gitattributes source equals destination.
+      goto AfterGitAttr
+    )
+
+    set "TMP_DST=%TEMP%\\gitattributes.dst.%RANDOM%.tmp"
+    set "TMP_MISS=%TEMP%\\gitattributes.missing.%RANDOM%.tmp"
+    if exist "!TMP_DST!" del /q "!TMP_DST!" >nul 2>nul
+    if exist "!TMP_MISS!" del /q "!TMP_MISS!" >nul 2>nul
+    type nul > "!TMP_DST!"
+    type nul > "!TMP_MISS!"
+
+    if exist "%GITATTR_DST%" (
+      for /f "usebackq delims=" %%L in ("%GITATTR_DST%") do (
+        set "LINE=%%L"
+        for /f "tokens=* delims= " %%A in ("!LINE!") do set "LINE=%%A"
+        if not "!LINE!"=="" (
+          if /I not "!LINE:~0,1!"=="#" (
+            echo(!LINE!>>"!TMP_DST!"
+          )
+        )
+      )
+    )
+
+    for /f "usebackq delims=" %%L in ("%GITATTR_SRC%") do (
+      set "LINE=%%L"
+      for /f "tokens=* delims= " %%A in ("!LINE!") do set "LINE=%%A"
+      if not "!LINE!"=="" (
+        if /I not "!LINE:~0,1!"=="#" (
+          findstr /x /l /c:"!LINE!" "!TMP_DST!" >nul || (
+            findstr /x /l /c:"!LINE!" "!TMP_MISS!" >nul || echo(!LINE!>>"!TMP_MISS!"
+          )
+        )
+      )
+    )
+
+    set "MISS_SIZE=0"
+    if exist "!TMP_MISS!" for %%S in ("!TMP_MISS!") do set "MISS_SIZE=%%~zS"
+    if "!MISS_SIZE!"=="0" (
+      del /q "!TMP_DST!" "!TMP_MISS!" >nul 2>nul
+      echo No missing .gitattributes rules to append.
+      goto AfterGitAttr
+    )
+
+    if exist "%GITATTR_DST%" (
+      set "RAND=%RANDOM%"
+      set "BAK_NAME=.gitattributes.bak.!RAND!"
+      ren "%GITATTR_DST%" "!BAK_NAME!"
+      echo Backed up existing .gitattributes -> !BAK_NAME!
+      set "DST_IN=%ROOT%\\!BAK_NAME!"
+    ) else (
+      set "DST_IN="
+    )
+
+    set "TMP_OUT=%TEMP%\\gitattributes.out.%RANDOM%.tmp"
+    if exist "!TMP_OUT!" del /q "!TMP_OUT!" >nul 2>nul
+
+    if not "!DST_IN!"=="" (
+      type "!DST_IN!" > "!TMP_OUT!"
+      for %%S in ("!DST_IN!") do set "DST_SIZE=%%~zS"
+      if not "!DST_SIZE!"=="0" echo.>>"!TMP_OUT!"
+    )
+
+    set "SOURCE_NOTE=%GITATTR_SRC%"
+    >>"!TMP_OUT!" echo # Added from playbook .gitattributes ^(source: !SOURCE_NOTE!^)
+    type "!TMP_MISS!" >> "!TMP_OUT!"
+
+    copy /y "!TMP_OUT!" "%GITATTR_DST%" >nul
+    del /q "!TMP_DST!" "!TMP_MISS!" "!TMP_OUT!" >nul 2>nul
+    echo Appended missing .gitattributes rules from standards.
+    goto AfterGitAttr
+  )
+
  if /I not "%SYNC_GITATTR_MODE%"=="block" (
-    echo ERROR: invalid SYNC_GITATTR_MODE=%SYNC_GITATTR_MODE% ^(use block^|overwrite^|skip^) 
+    echo ERROR: invalid SYNC_GITATTR_MODE=%SYNC_GITATTR_MODE% ^(use block^|overwrite^|append^|skip^) 
    exit /b 1
  )

@@ -1,6 +1,6 @@
 # Sync standards snapshot to project root.
 # - Copies <snapshot>/.agents/<AGENTS_NS> -> <project-root>/.agents/<AGENTS_NS>
-# - Updates <project-root>/.gitattributes (managed block by default)
+# - Updates <project-root>/.gitattributes (append missing rules by default)
 # Existing targets are backed up before overwrite.
 [CmdletBinding()]
 param(
@@ -15,8 +15,11 @@ $ErrorActionPreference = "Stop"
 $ScriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
 $Src = (Resolve-Path (Join-Path $ScriptDir "..")).Path

-$Root = (git -C $ScriptDir rev-parse --show-toplevel 2>$null)
-if (-not $Root) { $Root = (Get-Location).Path }
+$Root = $env:SYNC_ROOT
+if (-not $Root) {
+  $Root = (git -C $ScriptDir rev-parse --show-toplevel 2>$null)
+  if (-not $Root) { $Root = (Get-Location).Path }
+}
 $Root = (Resolve-Path $Root).Path

 $AgentsSrcRoot = Join-Path $Src ".agents"
@@ -28,6 +31,17 @@ if (-not (Test-Path $AgentsSrcRoot)) {

 $timestamp = Get-Date -Format "yyyyMMddHHmmss"

+# Auto-detect languages from existing .agents when no args are provided.
+if (-not $env:SYNC_STANDARDS_INNER -and (-not $Langs -or $Langs.Count -eq 0) -and -not $env:AGENTS_NS) {
+  $agentsRoot = Join-Path $Root ".agents"
+  if (Test-Path $agentsRoot) {
+    $autoLangs = @(Get-ChildItem -Path $agentsRoot -Directory | ForEach-Object { $_.Name } | Where-Object { Test-Path (Join-Path $AgentsSrcRoot $_) })
+    if ($autoLangs.Count -gt 0) {
+      $Langs = $autoLangs
+    }
+  }
+}
+
 # Multi rulesets: only on the outer invocation.
 if (-not $env:SYNC_STANDARDS_INNER -and $Langs -and $Langs.Count -gt 0) {
  $oldInner = $env:SYNC_STANDARDS_INNER
@@ -35,7 +49,7 @@ if (-not $env:SYNC_STANDARDS_INNER -and $Langs -and $Langs.Count -gt 0) {
  $oldMode = $env:SYNC_GITATTR_MODE

  $syncModeFirst = $env:SYNC_GITATTR_MODE
-  if (-not $syncModeFirst) { $syncModeFirst = "block" }
+  if (-not $syncModeFirst) { $syncModeFirst = "append" }

  $first = $true
  foreach ($ns in $Langs) {
@@ -118,10 +132,22 @@ if (-not (Test-Path $AgentsIndex)) {
  Write-Host "Created .agents/index.md"
 }

+$AgentsMd = Join-Path $Root "AGENTS.md"
+if (-not (Test-Path $AgentsMd)) {
+@'
+# Agent Instructions
+
+请以 `.agents/` 下的规则为准：
+
+- 入口：`.agents/index.md`
+'@ | Set-Content -Path $AgentsMd -Encoding UTF8
+  Write-Host "Created AGENTS.md"
+}
+
 $GitAttrDst = Join-Path $Root ".gitattributes"
 if (Test-Path $GitAttrSrc) {
  $mode = $env:SYNC_GITATTR_MODE
-  if (-not $mode) { $mode = "block" }
+  if (-not $mode) { $mode = "append" }
  switch ($mode.ToLowerInvariant()) {
    "skip" {
      Write-Host "Skip: .gitattributes sync (SYNC_GITATTR_MODE=skip)."
@@ -141,6 +167,65 @@ if (Test-Path $GitAttrSrc) {
      Write-Host "Synced .gitattributes from standards (overwrite)."
      break
    }
+    "append" {
+      if ($GitAttrSrc -ieq $GitAttrDst) {
+        Write-Host "Skip: .gitattributes source equals destination."
+        break
+      }
+
+      $dstLines = @{}
+      if (Test-Path $GitAttrDst) {
+        Get-Content $GitAttrDst | ForEach-Object {
+          $line = $_.Trim()
+          if ($line -eq "" -or $line.StartsWith("#")) { return }
+          $dstLines[$line] = $true
+        }
+      }
+
+      $missing = New-Object System.Collections.Generic.List[string]
+      Get-Content $GitAttrSrc | ForEach-Object {
+        $line = $_.Trim()
+        if ($line -eq "" -or $line.StartsWith("#")) { return }
+        if (-not $dstLines.ContainsKey($line)) {
+          $dstLines[$line] = $true
+          $missing.Add($line)
+        }
+      }
+
+      if ($missing.Count -eq 0) {
+        Write-Host "No missing .gitattributes rules to append."
+        break
+      }
+
+      $bak = $null
+      if (Test-Path $GitAttrDst) {
+        $bak = "$GitAttrDst.bak.$timestamp"
+        Move-Item $GitAttrDst $bak -Force
+        Write-Host "Backed up existing .gitattributes -> $bak"
+      }
+
+      $sourceNote = $GitAttrSrc
+      $rootPrefix = "$Root\"
+      if ($sourceNote.StartsWith($rootPrefix)) {
+        $sourceNote = $sourceNote.Substring($rootPrefix.Length)
+      }
+      $header = "# Added from playbook .gitattributes (source: $sourceNote)"
+
+      $content = @()
+      if ($bak -and (Test-Path $bak)) {
+        $existing = Get-Content $bak
+        if ($existing.Count -gt 0) {
+          $content += $existing
+          $content += ""
+        }
+      }
+      $content += $header
+      $content += $missing
+      $content | Set-Content -Path $GitAttrDst -Encoding UTF8
+
+      Write-Host "Appended missing .gitattributes rules from standards."
+      break
+    }
    "block" {
      $begin = "# BEGIN playbook .gitattributes"
      $end = "# END playbook .gitattributes"
@@ -171,7 +256,7 @@ if (Test-Path $GitAttrSrc) {
      break
    }
    default {
-      throw "Invalid SYNC_GITATTR_MODE=$mode (use block|overwrite|skip)"
+      throw "Invalid SYNC_GITATTR_MODE=$mode (use block|overwrite|append|skip)"
    }
  }
 }
@@ -3,7 +3,7 @@ set -eu

 # Sync standards snapshot to project root.
 # - Copies <snapshot>/.agents/<AGENTS_NS> -> <project-root>/.agents/<AGENTS_NS>
-# - Updates <project-root>/.gitattributes (managed block by default)
+# - Updates <project-root>/.gitattributes (append missing rules by default)
 # Existing targets are backed up before overwrite.
 #
 # Multi rulesets:
@@ -14,7 +14,11 @@ set -eu

 SCRIPT_DIR="$(CDPATH= cd -- "$(dirname -- "$0")" && pwd -P)"
 SRC="$(CDPATH= cd -- "$SCRIPT_DIR/.." && pwd -P)"
-ROOT="$(git -C "$SCRIPT_DIR" rev-parse --show-toplevel 2>/dev/null || pwd)"
+if [ -n "${SYNC_ROOT:-}" ]; then
+  ROOT="$SYNC_ROOT"
+else
+  ROOT="$(git -C "$SCRIPT_DIR" rev-parse --show-toplevel 2>/dev/null || pwd)"
+fi
 ROOT="$(CDPATH= cd -- "$ROOT" && pwd -P)"
 AGENTS_SRC_ROOT="$SRC/.agents"
 GITATTR_SRC="$SRC/.gitattributes"
@@ -43,8 +47,23 @@ if [ "${SYNC_STANDARDS_INNER:-}" != "1" ]; then
  if [ -z "${langs:-}" ] && [ "$#" -gt 0 ]; then
    langs="$*"
  fi
+  if [ -z "${langs:-}" ] && [ "$#" -eq 0 ] && [ -z "${AGENTS_NS:-}" ]; then
+    auto_langs=""
+    if [ -d "$ROOT/.agents" ]; then
+      for dir in "$ROOT/.agents"/*; do
+        [ -d "$dir" ] || continue
+        ns="$(basename "$dir")"
+        if [ -d "$AGENTS_SRC_ROOT/$ns" ]; then
+          auto_langs="${auto_langs:+$auto_langs }$ns"
+        fi
+      done
+    fi
+    if [ -n "$auto_langs" ]; then
+      langs="$auto_langs"
+    fi
+  fi
  if [ -n "${langs:-}" ]; then
-    sync_mode_first="${SYNC_GITATTR_MODE:-block}"
+    sync_mode_first="${SYNC_GITATTR_MODE:-append}"

    first=1
    old_ifs="${IFS}"
@@ -121,11 +140,23 @@ EOF
  echo "Created .agents/index.md"
 fi

+AGENTS_MD="$ROOT/AGENTS.md"
+if [ ! -f "$AGENTS_MD" ]; then
+  cat >"$AGENTS_MD" <<'EOF'
+# Agent Instructions
+
+请以 `.agents/` 下的规则为准：
+
+- 入口：`.agents/index.md`
+EOF
+  echo "Created AGENTS.md"
+fi
+
 echo "Synced agents ruleset to $AGENTS_DST."

 GITATTR_DST="$ROOT/.gitattributes"
 if [ -f "$GITATTR_SRC" ]; then
-  : "${SYNC_GITATTR_MODE:=block}"
+  : "${SYNC_GITATTR_MODE:=append}"
  case "$SYNC_GITATTR_MODE" in
    skip)
      echo "Skip: .gitattributes sync (SYNC_GITATTR_MODE=skip)."
@@ -142,6 +173,75 @@ if [ -f "$GITATTR_SRC" ]; then
        echo "Synced .gitattributes from standards (overwrite)."
      fi
      ;;
+    append)
+      if [ "$(CDPATH= cd -- "$(dirname -- "$GITATTR_SRC")" && pwd -P)/$(basename -- "$GITATTR_SRC")" = "$GITATTR_DST" ]; then
+        echo "Skip: .gitattributes source equals destination."
+      else
+        missing_tmp="$(mktemp 2>/dev/null || echo "$ROOT/.gitattributes.missing.$timestamp")"
+        if [ -f "$GITATTR_DST" ]; then
+          awk '
+            function norm(line) {
+              gsub(/^[ \t]+|[ \t]+$/, "", line)
+              return line
+            }
+            FNR==NR {
+              line=norm($0)
+              if (line == "" || line ~ /^#/) next
+              seen[line]=1
+              next
+            }
+            {
+              line=norm($0)
+              if (line == "" || line ~ /^#/) next
+              if (!seen[line] && !out[line]++) print line
+            }
+          ' "$GITATTR_DST" "$GITATTR_SRC" >"$missing_tmp"
+        else
+          awk '
+            function norm(line) {
+              gsub(/^[ \t]+|[ \t]+$/, "", line)
+              return line
+            }
+            {
+              line=norm($0)
+              if (line == "" || line ~ /^#/) next
+              if (!out[line]++) print line
+            }
+          ' "$GITATTR_SRC" >"$missing_tmp"
+        fi
+
+        if [ ! -s "$missing_tmp" ]; then
+          rm -f "$missing_tmp"
+          echo "No missing .gitattributes rules to append."
+          echo "Done."
+          exit 0
+        fi
+
+        if [ -e "$GITATTR_DST" ]; then
+          mv "$GITATTR_DST" "$ROOT/.gitattributes.bak.$timestamp"
+          echo "Backed up existing .gitattributes -> .gitattributes.bak.$timestamp"
+        fi
+
+        source_note="$GITATTR_SRC"
+        case "$GITATTR_SRC" in
+          "$ROOT"/*) source_note="${GITATTR_SRC#$ROOT/}" ;;
+        esac
+        header="# Added from playbook .gitattributes (source: $source_note)"
+
+        {
+          if [ -f "$ROOT/.gitattributes.bak.$timestamp" ]; then
+            cat "$ROOT/.gitattributes.bak.$timestamp"
+            if [ -s "$ROOT/.gitattributes.bak.$timestamp" ]; then
+              printf "\n"
+            fi
+          fi
+          printf "%s\n" "$header"
+          cat "$missing_tmp"
+        } >"$GITATTR_DST"
+        rm -f "$missing_tmp"
+        echo "Appended missing .gitattributes rules from standards."
+      fi
+      ;;
    block)
      begin="# BEGIN playbook .gitattributes"
      end="# END playbook .gitattributes"
@@ -191,7 +291,7 @@ if [ -f "$GITATTR_SRC" ]; then
      echo "Updated .gitattributes from standards (managed block)."
      ;;
    *)
-      echo "ERROR: invalid SYNC_GITATTR_MODE=$SYNC_GITATTR_MODE (use block|overwrite|skip)" >&2
+      echo "ERROR: invalid SYNC_GITATTR_MODE=$SYNC_GITATTR_MODE (use block|overwrite|append|skip)" >&2
      exit 1
      ;;
  esac
@@ -0,0 +1,264 @@
+@echo off
+setlocal enabledelayedexpansion
+
+rem Vendor a trimmed Playbook snapshot into a target project (offline copy),
+rem then run sync_standards to materialize .agents\<lang>\ and .gitattributes in
+rem the target project root.
+rem
+rem Usage:
+rem   scripts\vendor_playbook.bat <project-root>             (default: tsl)
+rem   scripts\vendor_playbook.bat <project-root> tsl cpp
+rem   scripts\vendor_playbook.bat <project-root> --langs tsl,cpp
+rem
+rem Notes:
+rem - Snapshot is written to: <project-root>\docs\standards\playbook\
+rem - Existing snapshot is backed up before overwrite.
+
+set "SCRIPT_DIR=%~dp0"
+for %%I in ("%SCRIPT_DIR%..") do set "SRC=%%~fI"
+
+if "%~1"=="" goto Usage
+if "%~1"=="-h" goto Usage
+if "%~1"=="--help" goto Usage
+
+set "DEST_ROOT=%~1"
+shift /1
+
+set "LANGS="
+if "%~1"=="--langs" (
+  set "LANGS=%~2"
+  shift /1
+  shift /1
+) else (
+  set "LANGS=%1 %2 %3 %4 %5 %6 %7 %8 %9"
+)
+
+if "%LANGS%"=="" set "LANGS=tsl"
+set "LANGS=%LANGS:,= %"
+
+if not exist "%DEST_ROOT%" mkdir "%DEST_ROOT%"
+for %%I in ("%DEST_ROOT%") do set "DEST_ROOT_ABS=%%~fI"
+
+set "STANDARDS_DIR=%DEST_ROOT_ABS%\\docs\\standards"
+set "DEST_PREFIX=%STANDARDS_DIR%\\playbook"
+
+if not exist "%STANDARDS_DIR%" mkdir "%STANDARDS_DIR%"
+
+if exist "%DEST_PREFIX%" (
+  set "RAND=%RANDOM%"
+  pushd "%STANDARDS_DIR%"
+  ren "playbook" "playbook.bak.!RAND!"
+  popd
+  echo Backed up existing snapshot -^> docs\\standards\\playbook.bak.!RAND!
+)
+
+if not exist "%DEST_PREFIX%" mkdir "%DEST_PREFIX%"
+
+copy /y "%SRC%\\.gitattributes" "%DEST_PREFIX%\\.gitattributes" >nul
+copy /y "%SRC%\\SKILLS.md" "%DEST_PREFIX%\\SKILLS.md" >nul
+
+xcopy "%SRC%\\scripts\\*" "%DEST_PREFIX%\\scripts\\" /e /i /y >nul
+if errorlevel 1 (
+  echo ERROR: failed to copy scripts
+  exit /b 1
+)
+
+xcopy "%SRC%\\codex\\*" "%DEST_PREFIX%\\codex\\" /e /i /y >nul
+if errorlevel 1 (
+  echo ERROR: failed to copy codex
+  exit /b 1
+)
+
+xcopy "%SRC%\\docs\\common\\*" "%DEST_PREFIX%\\docs\\common\\" /e /i /y >nul
+if errorlevel 1 (
+  echo ERROR: failed to copy docs\\common
+  exit /b 1
+)
+
+if not exist "%DEST_PREFIX%\\.agents" mkdir "%DEST_PREFIX%\\.agents"
+copy /y "%SRC%\\.agents\\index.md" "%DEST_PREFIX%\\.agents\\index.md" >nul
+
+if not exist "%DEST_PREFIX%\\templates" mkdir "%DEST_PREFIX%\\templates"
+
+if exist "%SRC%\\templates\\ci" (
+  xcopy "%SRC%\\templates\\ci\\*" "%DEST_PREFIX%\\templates\\ci\\" /e /i /y >nul
+  if errorlevel 1 (
+    echo ERROR: failed to copy templates\\ci
+    exit /b 1
+  )
+)
+
+set "LANGS_CSV="
+for %%L in (%LANGS%) do (
+  echo %%~L| findstr /r "[\\/]" >nul && (
+    echo ERROR: invalid lang=%%~L
+    exit /b 1
+  )
+  echo %%~L| findstr /c:".." >nul && (
+    echo ERROR: invalid lang=%%~L
+    exit /b 1
+  )
+
+  if not exist "%SRC%\\docs\\%%~L" (
+    echo ERROR: docs not found for lang=%%~L "%SRC%\\docs\\%%~L"
+    exit /b 1
+  )
+  if not exist "%SRC%\\.agents\\%%~L" (
+    echo ERROR: agents ruleset not found for lang=%%~L "%SRC%\\.agents\\%%~L"
+    exit /b 1
+  )
+
+  xcopy "%SRC%\\docs\\%%~L\\*" "%DEST_PREFIX%\\docs\\%%~L\\" /e /i /y >nul
+  if errorlevel 1 (
+    echo ERROR: failed to copy docs for lang=%%~L
+    exit /b 1
+  )
+
+  xcopy "%SRC%\\.agents\\%%~L\\*" "%DEST_PREFIX%\\.agents\\%%~L\\" /e /i /y >nul
+  if errorlevel 1 (
+    echo ERROR: failed to copy agents for lang=%%~L
+    exit /b 1
+  )
+
+  if exist "%SRC%\\templates\\%%~L" (
+    xcopy "%SRC%\\templates\\%%~L\\*" "%DEST_PREFIX%\\templates\\%%~L\\" /e /i /y >nul
+    if errorlevel 1 (
+      echo ERROR: failed to copy templates for lang=%%~L
+      exit /b 1
+    )
+  )
+
+  if "!LANGS_CSV!"=="" (
+    set "LANGS_CSV=%%~L"
+  ) else (
+    set "LANGS_CSV=!LANGS_CSV!,%%~L"
+  )
+)
+
+set "DOC_INDEX=%DEST_PREFIX%\\docs\\index.md"
+> "%DOC_INDEX%" echo # 文档导航（Docs Index）
+>> "%DOC_INDEX%" echo.
+>> "%DOC_INDEX%" echo 本快照为裁剪版 Playbook（langs: %LANGS_CSV%）。
+>> "%DOC_INDEX%" echo.
+>> "%DOC_INDEX%" echo ## 跨语言（common）
+>> "%DOC_INDEX%" echo.
+>> "%DOC_INDEX%" echo - 提交信息与版本号：`common/commit_message.md`
+
+for %%L in (%LANGS%) do call :AppendDocsSection "%%~L"
+
+set "COMMIT="
+for /f "delims=" %%H in ('git -C "%SRC%" rev-parse HEAD 2^>nul') do set "COMMIT=%%H"
+if "%COMMIT%"=="" set "COMMIT=N/A"
+
+set "README=%DEST_PREFIX%\\README.md"
+> "%README%" echo # Playbook（裁剪快照）
+>> "%README%" echo.
+>> "%README%" echo 本目录为从 Playbook vendoring 的裁剪快照（langs: %LANGS_CSV%）。
+>> "%README%" echo.
+>> "%README%" echo ## 使用
+>> "%README%" echo.
+>> "%README%" echo 在目标项目根目录执行（多语言一次同步）：
+>> "%README%" echo.
+>> "%README%" echo ```sh
+>> "%README%" echo sh docs/standards/playbook/scripts/sync_standards.sh %LANGS_CSV%
+>> "%README%" echo ```
+>> "%README%" echo.
+>> "%README%" echo 查看规范入口：
+>> "%README%" echo.
+>> "%README%" echo - `docs/standards/playbook/docs/index.md`
+>> "%README%" echo - `.agents/index.md`
+>> "%README%" echo.
+>> "%README%" echo ## Codex skills（可选）
+>> "%README%" echo.
+>> "%README%" echo 安装到本机（需要先在 `~/.codex/config.toml` 启用 skills；见 `docs/standards/playbook/SKILLS.md`）：
+>> "%README%" echo.
+>> "%README%" echo ```sh
+>> "%README%" echo sh docs/standards/playbook/scripts/install_codex_skills.sh
+>> "%README%" echo ```
+>> "%README%" echo.
+>> "%README%" echo ## CI templates（可选）
+>> "%README%" echo.
+>> "%README%" echo 目标项目可复制启用的 CI 示例模板（如 Gitea Actions）：`templates/ci/`。
+
+set "SOURCE=%DEST_PREFIX%\\SOURCE.md"
+> "%SOURCE%" echo # SOURCE
+>> "%SOURCE%" echo.
+>> "%SOURCE%" echo - Source: %SRC%
+>> "%SOURCE%" echo - Commit: %COMMIT%
+>> "%SOURCE%" echo - Date: %DATE% %TIME%
+>> "%SOURCE%" echo - Langs: %LANGS_CSV%
+>> "%SOURCE%" echo - Generated-by: scripts/vendor_playbook.bat
+
+echo Vendored snapshot -^> %DEST_PREFIX%
+
+set "PROJECT_AGENTS_ROOT=%DEST_ROOT_ABS%\\.agents"
+set "PROJECT_AGENTS_INDEX=%PROJECT_AGENTS_ROOT%\\index.md"
+if not exist "%PROJECT_AGENTS_ROOT%" mkdir "%PROJECT_AGENTS_ROOT%"
+if not exist "%PROJECT_AGENTS_INDEX%" (
+  > "%PROJECT_AGENTS_INDEX%" echo # .agents（多语言）
+  >> "%PROJECT_AGENTS_INDEX%" echo.
+  >> "%PROJECT_AGENTS_INDEX%" echo 本目录用于存放仓库级/语言级的代理规则集。
+  >> "%PROJECT_AGENTS_INDEX%" echo.
+  >> "%PROJECT_AGENTS_INDEX%" echo 本项目已启用的规则集：
+  for %%L in (%LANGS%) do (
+    if /I "%%~L"=="tsl" >> "%PROJECT_AGENTS_INDEX%" echo - .agents/tsl/：TSL 相关规则集（适用于 .tsl/.tsf）
+    if /I "%%~L"=="cpp" >> "%PROJECT_AGENTS_INDEX%" echo - .agents/cpp/：C++ 相关规则集（C++23，含 Modules）
+    if /I "%%~L"=="python" >> "%PROJECT_AGENTS_INDEX%" echo - .agents/python/：Python 相关规则集
+  )
+  >> "%PROJECT_AGENTS_INDEX%" echo.
+  >> "%PROJECT_AGENTS_INDEX%" echo 入口建议从：
+  for %%L in (%LANGS%) do >> "%PROJECT_AGENTS_INDEX%" echo - .agents/%%~L/index.md
+  >> "%PROJECT_AGENTS_INDEX%" echo.
+  >> "%PROJECT_AGENTS_INDEX%" echo 标准快照文档入口：
+  >> "%PROJECT_AGENTS_INDEX%" echo.
+  >> "%PROJECT_AGENTS_INDEX%" echo - docs/standards/playbook/docs/index.md
+)
+
+set "OLD_SYNC_ROOT=%SYNC_ROOT%"
+set "SYNC_ROOT=%DEST_ROOT_ABS%"
+pushd "%DEST_ROOT_ABS%"
+call "%DEST_PREFIX%\\scripts\\sync_standards.bat" %LANGS%
+popd
+set "SYNC_ROOT=%OLD_SYNC_ROOT%"
+
+echo Done.
+endlocal
+exit /b 0
+
+:AppendDocsSection
+set "LANG=%~1"
+if /I "%LANG%"=="tsl" (
+  >> "%DOC_INDEX%" echo.
+  >> "%DOC_INDEX%" echo ## TSL（tsl）
+  >> "%DOC_INDEX%" echo.
+  >> "%DOC_INDEX%" echo - 代码风格：`tsl/code_style.md`
+  >> "%DOC_INDEX%" echo - 命名规范：`tsl/naming.md`
+  >> "%DOC_INDEX%" echo - 语法手册：`tsl/syntax_book/index.md`
+  >> "%DOC_INDEX%" echo - 工具链与验证命令（模板）：`tsl/toolchain.md`
+)
+if /I "%LANG%"=="cpp" (
+  >> "%DOC_INDEX%" echo.
+  >> "%DOC_INDEX%" echo ## C++（cpp）
+  >> "%DOC_INDEX%" echo.
+  >> "%DOC_INDEX%" echo - 代码风格：`cpp/code_style.md`
+  >> "%DOC_INDEX%" echo - 命名规范：`cpp/naming.md`
+  >> "%DOC_INDEX%" echo - 工具链与验证命令（模板）：`cpp/toolchain.md`
+  >> "%DOC_INDEX%" echo - 第三方依赖（Conan）：`cpp/dependencies_conan.md`
+  >> "%DOC_INDEX%" echo - clangd 配置：`cpp/clangd.md`
+)
+if /I "%LANG%"=="python" (
+  >> "%DOC_INDEX%" echo.
+  >> "%DOC_INDEX%" echo ## Python（python）
+  >> "%DOC_INDEX%" echo.
+  >> "%DOC_INDEX%" echo - 代码风格：`python/style_guide.md`
+  >> "%DOC_INDEX%" echo - 工具链：`python/tooling.md`
+  >> "%DOC_INDEX%" echo - 配置清单：`python/configuration.md`
+)
+exit /b 0
+
+:Usage
+echo Usage:
+echo   scripts\vendor_playbook.bat ^<project-root^>             ^(default: tsl^)
+echo   scripts\vendor_playbook.bat ^<project-root^> tsl cpp
+echo   scripts\vendor_playbook.bat ^<project-root^> --langs tsl,cpp
+exit /b 1
@@ -0,0 +1,242 @@
+# Vendor a trimmed Playbook snapshot into a target project (offline copy),
+# then run sync_standards to materialize .agents\<lang>\ and .gitattributes in
+# the target project root.
+#
+# Usage:
+#   powershell -File scripts/vendor_playbook.ps1 -DestRoot <project-root>
+#   powershell -File scripts/vendor_playbook.ps1 -DestRoot <project-root> -Langs tsl,cpp
+#   powershell -File scripts/vendor_playbook.ps1 -DestRoot <project-root> -Langs @("tsl","cpp")
+#
+# Notes:
+# - Snapshot is written to: <project-root>\docs\standards\playbook\
+# - Existing snapshot is backed up before overwrite.
+
+[CmdletBinding()]
+param(
+  [Parameter(Mandatory = $true)]
+  [string]$DestRoot,
+
+  [Parameter(Mandatory = $false)]
+  [string[]]$Langs
+)
+
+$ErrorActionPreference = "Stop"
+
+function Normalize-Langs([string[]]$InputLangs) {
+  if (-not $InputLangs -or $InputLangs.Count -eq 0) { return @("tsl") }
+
+  $result = New-Object System.Collections.Generic.List[string]
+  foreach ($item in $InputLangs) {
+    if (-not $item) { continue }
+    foreach ($part in $item.Split(@(',', ' '), [System.StringSplitOptions]::RemoveEmptyEntries)) {
+      if (-not $part) { continue }
+      $result.Add($part)
+    }
+  }
+  if ($result.Count -eq 0) { return @("tsl") }
+  return $result.ToArray()
+}
+
+$Langs = Normalize-Langs $Langs
+
+foreach ($lang in $Langs) {
+  if ($lang -match '[\\/]' -or $lang -match '\.\.') {
+    throw "Invalid lang=$lang"
+  }
+}
+
+$ScriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
+$Src = (Resolve-Path (Join-Path $ScriptDir "..")).Path
+
+New-Item -ItemType Directory -Path $DestRoot -Force | Out-Null
+$DestRootAbs = (Resolve-Path $DestRoot).Path
+
+$StandardsDir = Join-Path $DestRootAbs "docs/standards"
+$DestPrefix = Join-Path $StandardsDir "playbook"
+
+New-Item -ItemType Directory -Path $StandardsDir -Force | Out-Null
+
+$timestamp = Get-Date -Format "yyyyMMddHHmmss"
+if (Test-Path $DestPrefix) {
+  $bak = Join-Path $StandardsDir "playbook.bak.$timestamp"
+  Move-Item $DestPrefix $bak
+  Write-Host "Backed up existing snapshot -> docs\\standards\\$(Split-Path -Leaf $bak)"
+}
+
+New-Item -ItemType Directory -Path $DestPrefix -Force | Out-Null
+
+Copy-Item (Join-Path $Src ".gitattributes") (Join-Path $DestPrefix ".gitattributes") -Force
+Copy-Item (Join-Path $Src "scripts") $DestPrefix -Recurse -Force
+Copy-Item (Join-Path $Src "codex") $DestPrefix -Recurse -Force
+Copy-Item (Join-Path $Src "SKILLS.md") (Join-Path $DestPrefix "SKILLS.md") -Force
+
+$DocsDir = Join-Path $DestPrefix "docs"
+New-Item -ItemType Directory -Path $DocsDir -Force | Out-Null
+Copy-Item (Join-Path $Src "docs/common") $DocsDir -Recurse -Force
+
+$AgentsDir = Join-Path $DestPrefix ".agents"
+New-Item -ItemType Directory -Path $AgentsDir -Force | Out-Null
+Copy-Item (Join-Path $Src ".agents/index.md") (Join-Path $AgentsDir "index.md") -Force
+
+$TemplatesDir = Join-Path $DestPrefix "templates"
+New-Item -ItemType Directory -Path $TemplatesDir -Force | Out-Null
+
+$ciTplSrc = Join-Path (Join-Path $Src "templates") "ci"
+if (Test-Path $ciTplSrc) {
+  Copy-Item $ciTplSrc $TemplatesDir -Recurse -Force
+}
+
+foreach ($lang in $Langs) {
+  $docsSrc = Join-Path (Join-Path $Src "docs") $lang
+  if (-not (Test-Path $docsSrc)) { throw "Docs not found for lang=$lang ($docsSrc)" }
+  Copy-Item $docsSrc $DocsDir -Recurse -Force
+
+  $agentsSrc = Join-Path (Join-Path $Src ".agents") $lang
+  if (-not (Test-Path $agentsSrc)) { throw "Agents ruleset not found for lang=$lang ($agentsSrc)" }
+  Copy-Item $agentsSrc $AgentsDir -Recurse -Force
+
+  $tplSrc = Join-Path (Join-Path $Src "templates") $lang
+  if (Test-Path $tplSrc) {
+    Copy-Item $tplSrc $TemplatesDir -Recurse -Force
+  }
+}
+
+$langsCsv = ($Langs -join ",")
+
+$docLines = New-Object System.Collections.Generic.List[string]
+$docLines.Add("# 文档导航（Docs Index）")
+$docLines.Add("")
+$docLines.Add("本快照为裁剪版 Playbook（langs: $langsCsv）。")
+$docLines.Add("")
+$docLines.Add("## 跨语言（common）")
+$docLines.Add("")
+$docLines.Add('- 提交信息与版本号：`common/commit_message.md`')
+
+function Append-DocsSection([string]$Lang) {
+  switch ($Lang) {
+    "tsl" {
+      $docLines.Add("")
+      $docLines.Add("## TSL（tsl）")
+      $docLines.Add("")
+      $docLines.Add('- 代码风格：`tsl/code_style.md`')
+      $docLines.Add('- 命名规范：`tsl/naming.md`')
+      $docLines.Add('- 语法手册：`tsl/syntax_book/index.md`')
+      $docLines.Add('- 工具链与验证命令（模板）：`tsl/toolchain.md`')
+      break
+    }
+    "cpp" {
+      $docLines.Add("")
+      $docLines.Add("## C++（cpp）")
+      $docLines.Add("")
+      $docLines.Add('- 代码风格：`cpp/code_style.md`')
+      $docLines.Add('- 命名规范：`cpp/naming.md`')
+      $docLines.Add('- 工具链与验证命令（模板）：`cpp/toolchain.md`')
+      $docLines.Add('- 第三方依赖（Conan）：`cpp/dependencies_conan.md`')
+      $docLines.Add('- clangd 配置：`cpp/clangd.md`')
+      break
+    }
+    "python" {
+      $docLines.Add("")
+      $docLines.Add("## Python（python）")
+      $docLines.Add("")
+      $docLines.Add('- 代码风格：`python/style_guide.md`')
+      $docLines.Add('- 工具链：`python/tooling.md`')
+      $docLines.Add('- 配置清单：`python/configuration.md`')
+      break
+    }
+  }
+}
+
+foreach ($lang in $Langs) {
+  Append-DocsSection $lang
+}
+
+($docLines -join "`n") | Set-Content -Path (Join-Path $DocsDir "index.md") -Encoding UTF8
+
+$commit = ""
+try {
+  $commit = (git -C $Src rev-parse HEAD 2>$null)
+} catch {
+  $commit = ""
+}
+if (-not $commit) { $commit = "N/A" }
+
+@"
+# Playbook（裁剪快照）
+
+本目录为从 Playbook vendoring 的裁剪快照（langs: $langsCsv）。
+
+## 使用
+
+在目标项目根目录执行（多语言一次同步）：
+
+```sh
+sh docs/standards/playbook/scripts/sync_standards.sh $langsCsv
+```
+
+查看规范入口：
+
+- `docs/standards/playbook/docs/index.md`
+- `.agents/index.md`
+
+## Codex skills（可选）
+
+安装到本机（需要先在 `~/.codex/config.toml` 启用 skills；见 `docs/standards/playbook/SKILLS.md`）：
+
+```sh
+sh docs/standards/playbook/scripts/install_codex_skills.sh
+```
+
+## CI templates（可选）
+
+目标项目可复制启用的 CI 示例模板（如 Gitea Actions）：`templates/ci/`。
+"@ | Set-Content -Path (Join-Path $DestPrefix "README.md") -Encoding UTF8
+
+@"
+# SOURCE
+
+- Source: $Src
+- Commit: $commit
+- Date: $(Get-Date).ToUniversalTime().ToString("yyyy-MM-ddTHH:mm:ssZ")
+- Langs: $langsCsv
+- Generated-by: scripts/vendor_playbook.ps1
+"@ | Set-Content -Path (Join-Path $DestPrefix "SOURCE.md") -Encoding UTF8
+
+Write-Host "Vendored snapshot -> $DestPrefix"
+
+$ProjectAgentsRoot = Join-Path $DestRootAbs ".agents"
+$ProjectAgentsIndex = Join-Path $ProjectAgentsRoot "index.md"
+New-Item -ItemType Directory -Path $ProjectAgentsRoot -Force | Out-Null
+if (-not (Test-Path $ProjectAgentsIndex)) {
+  $agentLines = New-Object System.Collections.Generic.List[string]
+  $agentLines.Add("# .agents（多语言）")
+  $agentLines.Add("")
+  $agentLines.Add("本目录用于存放仓库级/语言级的代理规则集。")
+  $agentLines.Add("")
+  $agentLines.Add("本项目已启用的规则集：")
+  foreach ($lang in $Langs) {
+    switch ($lang) {
+      "tsl" { $agentLines.Add("- .agents/tsl/：TSL 相关规则集（适用于 .tsl/.tsf）"); break }
+      "cpp" { $agentLines.Add("- .agents/cpp/：C++ 相关规则集（C++23，含 Modules）"); break }
+      "python" { $agentLines.Add("- .agents/python/：Python 相关规则集"); break }
+    }
+  }
+  $agentLines.Add("")
+  $agentLines.Add("入口建议从：")
+  foreach ($lang in $Langs) { $agentLines.Add("- .agents/$lang/index.md") }
+  $agentLines.Add("")
+  $agentLines.Add("标准快照文档入口：")
+  $agentLines.Add("")
+  $agentLines.Add("- docs/standards/playbook/docs/index.md")
+  ($agentLines -join "`n") | Set-Content -Path $ProjectAgentsIndex -Encoding UTF8
+}
+
+$oldSyncRoot = $env:SYNC_ROOT
+$env:SYNC_ROOT = $DestRootAbs
+try {
+  & (Join-Path $DestPrefix "scripts/sync_standards.ps1") -Langs $Langs
+} finally {
+  $env:SYNC_ROOT = $oldSyncRoot
+}
+
+Write-Host "Done."
@@ -0,0 +1,269 @@
+#!/usr/bin/env sh
+set -eu
+
+# Vendor a trimmed Playbook snapshot into a target project (offline copy),
+# then run sync_standards to materialize .agents/<lang>/ and .gitattributes in
+# the target project root.
+#
+# Usage:
+#   sh scripts/vendor_playbook.sh <project-root>                 # default: tsl
+#   sh scripts/vendor_playbook.sh <project-root> tsl cpp
+#   sh scripts/vendor_playbook.sh <project-root> --langs tsl,cpp
+#
+# Notes:
+# - Snapshot is written to: <project-root>/docs/standards/playbook/
+# - Existing snapshot is backed up before overwrite.
+
+SCRIPT_DIR="$(CDPATH= cd -- "$(dirname -- "$0")" && pwd -P)"
+SRC="$(CDPATH= cd -- "$SCRIPT_DIR/.." && pwd -P)"
+
+usage() {
+  cat <<'EOF' >&2
+Usage:
+  sh scripts/vendor_playbook.sh <project-root>                 # default: tsl
+  sh scripts/vendor_playbook.sh <project-root> tsl cpp
+  sh scripts/vendor_playbook.sh <project-root> --langs tsl,cpp
+EOF
+}
+
+if [ "$#" -lt 1 ]; then
+  usage
+  exit 1
+fi
+
+if [ "${1:-}" = "-h" ] || [ "${1:-}" = "--help" ]; then
+  usage
+  exit 0
+fi
+
+PROJECT_ROOT="$1"
+shift
+
+langs=""
+if [ "${1:-}" = "--langs" ]; then
+  langs="${2:-}"
+  shift 2 || true
+fi
+if [ -z "${langs:-}" ] && [ "$#" -gt 0 ]; then
+  langs="$*"
+fi
+
+if [ -z "${langs:-}" ]; then
+  langs="tsl"
+fi
+
+timestamp="$(date +%Y%m%d%H%M%S 2>/dev/null || echo bak)"
+
+if [ ! -d "$PROJECT_ROOT" ]; then
+  echo "ERROR: project root does not exist: $PROJECT_ROOT" >&2
+  exit 1
+fi
+PROJECT_ROOT_ABS="$(CDPATH= cd -- "$PROJECT_ROOT" && pwd -P)"
+DEST_PREFIX="$PROJECT_ROOT_ABS/docs/standards/playbook"
+DEST_STANDARDS="$PROJECT_ROOT_ABS/docs/standards"
+
+mkdir -p "$DEST_STANDARDS"
+
+if [ -e "$DEST_PREFIX" ]; then
+  mv "$DEST_PREFIX" "$DEST_STANDARDS/playbook.bak.$timestamp"
+  echo "Backed up existing snapshot -> docs/standards/playbook.bak.$timestamp"
+fi
+
+mkdir -p "$DEST_PREFIX"
+
+# Always include: scripts + gitattributes + docs/common + codex/skills
+cp "$SRC/.gitattributes" "$DEST_PREFIX/.gitattributes"
+cp -R "$SRC/scripts" "$DEST_PREFIX/"
+cp -R "$SRC/codex" "$DEST_PREFIX/"
+cp "$SRC/SKILLS.md" "$DEST_PREFIX/SKILLS.md"
+
+mkdir -p "$DEST_PREFIX/docs"
+cp -R "$SRC/docs/common" "$DEST_PREFIX/docs/"
+
+mkdir -p "$DEST_PREFIX/.agents"
+cp "$SRC/.agents/index.md" "$DEST_PREFIX/.agents/index.md"
+
+mkdir -p "$DEST_PREFIX/templates"
+if [ -d "$SRC/templates/ci" ]; then
+  cp -R "$SRC/templates/ci" "$DEST_PREFIX/templates/"
+fi
+
+old_ifs="${IFS}"
+IFS=', '
+set -- $langs
+IFS="${old_ifs}"
+
+langs_csv=""
+for lang in "$@"; do
+  [ -n "$lang" ] || continue
+
+  case "$lang" in
+    ""|*/*|*\\*|*..*)
+      echo "ERROR: invalid lang=$lang" >&2
+      exit 1
+      ;;
+  esac
+
+  if [ ! -d "$SRC/docs/$lang" ]; then
+    echo "ERROR: docs not found for lang=$lang ($SRC/docs/$lang)" >&2
+    exit 1
+  fi
+  if [ ! -d "$SRC/.agents/$lang" ]; then
+    echo "ERROR: agents ruleset not found for lang=$lang ($SRC/.agents/$lang)" >&2
+    exit 1
+  fi
+
+  cp -R "$SRC/docs/$lang" "$DEST_PREFIX/docs/"
+  cp -R "$SRC/.agents/$lang" "$DEST_PREFIX/.agents/"
+  if [ -d "$SRC/templates/$lang" ]; then
+    cp -R "$SRC/templates/$lang" "$DEST_PREFIX/templates/"
+  fi
+
+  if [ -n "$langs_csv" ]; then
+    langs_csv="$langs_csv,$lang"
+  else
+    langs_csv="$lang"
+  fi
+done
+
+cat >"$DEST_PREFIX/docs/index.md" <<EOF
+# 文档导航（Docs Index）
+
+本快照为裁剪版 Playbook（langs: ${langs_csv}）。
+
+## 跨语言（common）
+
+- 提交信息与版本号：\`common/commit_message.md\`
+EOF
+
+append_docs_section() {
+  lang="$1"
+  case "$lang" in
+    tsl)
+      cat >>"$DEST_PREFIX/docs/index.md" <<'EOF'
+
+## TSL（tsl）
+
+- 代码风格：`tsl/code_style.md`
+- 命名规范：`tsl/naming.md`
+- 语法手册：`tsl/syntax_book/index.md`
+- 工具链与验证命令（模板）：`tsl/toolchain.md`
+EOF
+      ;;
+    cpp)
+      cat >>"$DEST_PREFIX/docs/index.md" <<'EOF'
+
+## C++（cpp）
+
+- 代码风格：`cpp/code_style.md`
+- 命名规范：`cpp/naming.md`
+- 工具链与验证命令（模板）：`cpp/toolchain.md`
+- 第三方依赖（Conan）：`cpp/dependencies_conan.md`
+- clangd 配置：`cpp/clangd.md`
+EOF
+      ;;
+    python)
+      cat >>"$DEST_PREFIX/docs/index.md" <<'EOF'
+
+## Python（python）
+
+- 代码风格：`python/style_guide.md`
+- 工具链：`python/tooling.md`
+- 配置清单：`python/configuration.md`
+EOF
+      ;;
+  esac
+}
+
+for lang in "$@"; do
+  [ -n "$lang" ] || continue
+  append_docs_section "$lang"
+done
+
+commit=""
+if command -v git >/dev/null 2>&1; then
+  commit="$(git -C "$SRC" rev-parse HEAD 2>/dev/null || true)"
+fi
+
+cat >"$DEST_PREFIX/README.md" <<EOF
+# Playbook（裁剪快照）
+
+本目录为从 Playbook vendoring 的裁剪快照（langs: ${langs_csv}）。
+
+## 使用
+
+在目标项目根目录执行（多语言一次同步）：
+
+\`\`\`sh
+sh docs/standards/playbook/scripts/sync_standards.sh ${langs_csv}
+\`\`\`
+
+查看规范入口：
+
+- \`docs/standards/playbook/docs/index.md\`
+- \`.agents/index.md\`
+
+## Codex skills（可选）
+
+安装到本机（需要先在 \`~/.codex/config.toml\` 启用 skills；见 \`docs/standards/playbook/SKILLS.md\`）：
+
+\`\`\`sh
+sh docs/standards/playbook/scripts/install_codex_skills.sh
+\`\`\`
+
+## CI templates（可选）
+
+目标项目可复制启用的 CI 示例模板（如 Gitea Actions）：\`templates/ci/\`。
+EOF
+
+cat >"$DEST_PREFIX/SOURCE.md" <<EOF
+# SOURCE
+
+- Source: $SRC
+- Commit: ${commit:-N/A}
+- Date: $(date -u +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || date)
+- Langs: ${langs_csv}
+- Generated-by: scripts/vendor_playbook.sh
+EOF
+
+echo "Vendored snapshot -> $DEST_PREFIX"
+
+PROJECT_AGENTS_ROOT="$PROJECT_ROOT_ABS/.agents"
+PROJECT_AGENTS_INDEX="$PROJECT_AGENTS_ROOT/index.md"
+mkdir -p "$PROJECT_AGENTS_ROOT"
+if [ ! -f "$PROJECT_AGENTS_INDEX" ]; then
+  cat >"$PROJECT_AGENTS_INDEX" <<EOF
+# .agents（多语言）
+
+本目录用于存放仓库级/语言级的代理规则集。
+
+本项目已启用的规则集：
+EOF
+
+  for lang in "$@"; do
+    case "$lang" in
+      tsl) printf '%s\n' "- .agents/tsl/：TSL 相关规则集（适用于 .tsl/.tsf）" >>"$PROJECT_AGENTS_INDEX" ;;
+      cpp) printf '%s\n' "- .agents/cpp/：C++ 相关规则集（C++23，含 Modules）" >>"$PROJECT_AGENTS_INDEX" ;;
+      python) printf '%s\n' "- .agents/python/：Python 相关规则集" >>"$PROJECT_AGENTS_INDEX" ;;
+    esac
+  done
+
+  cat >>"$PROJECT_AGENTS_INDEX" <<'EOF'
+
+入口建议从：
+EOF
+
+  for lang in "$@"; do
+    printf '%s\n' "- .agents/$lang/index.md" >>"$PROJECT_AGENTS_INDEX"
+  done
+
+  cat >>"$PROJECT_AGENTS_INDEX" <<'EOF'
+
+标准快照文档入口：
+
+- docs/standards/playbook/docs/index.md
+EOF
+fi
+
+SYNC_ROOT="$PROJECT_ROOT_ABS" sh "$DEST_PREFIX/scripts/sync_standards.sh" "$@"
+echo "Done."