csh/playbook
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

📝 docs(playbook): add contributing and multi-language standards

Browse Source 
Introduce C++ and Python docs/templates and split .agents rulesets by language (tsl/cpp/python).

Move commit message guidance to CONTRIBUTING.md (full spec remains in docs/common/commit_message.md).
This commit is contained in:
csh
2025-12-14 17:32:50 +08:00
parent 380228caca
commit e504a689dc
47 changed files with 1521 additions and 162 deletions
Download Patch File Download Diff File Expand all files Collapse all files
scripts/sync_standards.bat
+60 -7
View File
@@ -2,9 +2,14 @@
setlocal enabledelayedexpansion
rem Sync standards snapshot to project root.
rem - Copies <snapshot>\.agents -> <project-root>\.agents\tsl
rem - Copies <snapshot>\.agents\<AGENTS_NS> -> <project-root>\.agents\<AGENTS_NS>
rem - Updates <project-root>\.gitattributes (managed block by default)
rem Existing targets are backed up before overwrite.
rem
rem Multi rulesets:
rem sync_standards.bat tsl cpp
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"
@@ -12,7 +17,7 @@ if "%ROOT%"=="" set "ROOT=%cd%"
for %%I in ("%ROOT%") do set "ROOT=%%~fI"
for %%I in ("%SCRIPT_DIR%..") do set "SRC=%%~fI"
set "AGENTS_SRC=%SRC%\.agents"
set "AGENTS_SRC_ROOT=%SRC%\.agents"
set "GITATTR_SRC=%SRC%\.gitattributes"
set "AGENTS_NS=%AGENTS_NS%"
if "%AGENTS_NS%"=="" set "AGENTS_NS=tsl"
@@ -30,9 +35,43 @@ set "GITATTR_DST=%ROOT%\.gitattributes"
set "SYNC_GITATTR_MODE=%SYNC_GITATTR_MODE%"
if "%SYNC_GITATTR_MODE%"=="" set "SYNC_GITATTR_MODE=block"
rem Multi rulesets: only on outer invocation.
if "%SYNC_STANDARDS_INNER%"=="" (
if not "%~1"=="" (
set "FIRST=1"
set "SYNC_FIRST=%SYNC_GITATTR_MODE%"
for %%L in (%*) do (
if "!FIRST!"=="1" (
set "FIRST=0"
set "SYNC_STANDARDS_INNER=1"
set "AGENTS_NS=%%~L"
set "SYNC_GITATTR_MODE=!SYNC_FIRST!"
call "%~f0"
) else (
set "SYNC_STANDARDS_INNER=1"
set "AGENTS_NS=%%~L"
set "SYNC_GITATTR_MODE=skip"
call "%~f0"
)
)
exit /b 0
)
)
set "AGENTS_SRC=%AGENTS_SRC_ROOT%\%AGENTS_NS%"
if not exist "%AGENTS_SRC%" (
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).
exit /b 1
)
)
if not exist "%AGENTS_SRC%" (
echo ERROR: Standards snapshot not found at "%AGENTS_SRC%".
echo Run: git subtree add --prefix ^<your-prefix^> ^<standards-url^> ^<branch^> --squash
echo Run: git subtree add --prefix docs/standards/playbook ^<standards-url^> ^<branch^> --squash
exit /b 1
)
@@ -67,14 +106,16 @@ if not exist "%AGENTS_ROOT%\index.md" (
>> "%AGENTS_ROOT%\index.md" echo 建议约定：
>> "%AGENTS_ROOT%\index.md" echo.
>> "%AGENTS_ROOT%\index.md" echo - `.agents/tsl/`：TSL 相关规则集（由 `sync_standards.*` 同步；适用于 `.tsl`/`.tsf`）
>> "%AGENTS_ROOT%\index.md" echo - `.agents/cpp/`、`.agents/python/` 等：其他语言的规则集（按需增加）
>> "%AGENTS_ROOT%\index.md" echo - `.agents/cpp/`：C++ 相关规则集（由 `sync_standards.*` 同步；适用于 C++23/Modules）
>> "%AGENTS_ROOT%\index.md" echo - `.agents/python/` 等：其他语言的规则集（按需增加）
>> "%AGENTS_ROOT%\index.md" echo.
>> "%AGENTS_ROOT%\index.md" echo 规则发生冲突时，建议以“更靠近代码的目录规则更具体”为准。
>> "%AGENTS_ROOT%\index.md" echo.
>> "%AGENTS_ROOT%\index.md" echo 入口建议从：
>> "%AGENTS_ROOT%\index.md" echo.
>> "%AGENTS_ROOT%\index.md" echo - `.agents/tsl/index.md`（TSL 规则集入口）
>> "%AGENTS_ROOT%\index.md" echo - `docs/standards/tsl/docs/tsl/`（TSL 人类开发规范快照，推荐 subtree/vendoring 到该路径）
>> "%AGENTS_ROOT%\index.md" echo - `.agents/cpp/index.md`（C++ 规则集入口）
>> "%AGENTS_ROOT%\index.md" echo - `docs/standards/playbook/docs/`（人类开发规范快照：`tsl/`、`cpp/`、`python/`、`common/`）
echo Created .agents\index.md
)
@@ -110,8 +151,10 @@ if exist "%GITATTR_SRC%" (
)
rem block mode: maintain a managed block inside the destination file
set "BEGIN=# BEGIN tsl-playbook .gitattributes"
set "END=# END tsl-playbook .gitattributes"
set "BEGIN=# BEGIN playbook .gitattributes"
set "END=# END playbook .gitattributes"
set "BEGIN_OLD=# BEGIN tsl-playbook .gitattributes"
set "END_OLD=# END tsl-playbook .gitattributes"
set "TMP_FILE=%TEMP%\\gitattributes.%RANDOM%.tmp"
if exist "%GITATTR_DST%" (
@@ -139,8 +182,18 @@ if exist "%GITATTR_SRC%" (
set "DONE=1"
)
set "IN_BLOCK=1"
) else if "!LINE!"=="%BEGIN_OLD%" (
if "!DONE!"=="0" (
echo %BEGIN%
type "%GITATTR_SRC%"
echo %END%
set "DONE=1"
)
set "IN_BLOCK=1"
) else if "!LINE!"=="%END%" (
set "IN_BLOCK=0"
) else if "!LINE!"=="%END_OLD%" (
set "IN_BLOCK=0"
) else (
if "!IN_BLOCK!"=="0" echo(!LINE!
)
scripts/sync_standards.ps1
+62 -10
View File
@@ -1,9 +1,17 @@
# Sync standards snapshot to project root.
# - Copies <snapshot>/.agents -> <project-root>/.agents/tsl
# - Copies <snapshot>/.agents/<AGENTS_NS> -> <project-root>/.agents/<AGENTS_NS>
# - Updates <project-root>/.gitattributes (managed block by default)
# Existing targets are backed up before overwrite.
$ErrorActionPreference = "Stop"
[CmdletBinding()]
param(
# Sync multiple rulesets in one run:
# -Langs tsl,cpp
# -Langs @("tsl","cpp")
[Parameter(Mandatory = $false)]
[string[]]$Langs
)
$ErrorActionPreference = "Stop"
$ScriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
$Src = (Resolve-Path (Join-Path $ScriptDir "..")).Path
@@ -11,20 +19,60 @@ $Root = (git -C $ScriptDir rev-parse --show-toplevel 2>$null)
if (-not $Root) { $Root = (Get-Location).Path }
$Root = (Resolve-Path $Root).Path
$AgentsSrc = Join-Path $Src ".agents"
$AgentsSrcRoot = Join-Path $Src ".agents"
$GitAttrSrc = Join-Path $Src ".gitattributes"
if (-not (Test-Path $AgentsSrc)) {
throw "Standards snapshot not found at $AgentsSrc. Run git subtree add first (choose any prefix)."
if (-not (Test-Path $AgentsSrcRoot)) {
throw "Standards snapshot not found at $AgentsSrcRoot. Run: git subtree add --prefix docs/standards/playbook <url> <branch> --squash"
}
$timestamp = Get-Date -Format "yyyyMMddHHmmss"
# 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
$oldAgentsNs = $env:AGENTS_NS
$oldMode = $env:SYNC_GITATTR_MODE
$syncModeFirst = $env:SYNC_GITATTR_MODE
if (-not $syncModeFirst) { $syncModeFirst = "block" }
$first = $true
foreach ($ns in $Langs) {
if (-not $ns) { continue }
$env:SYNC_STANDARDS_INNER = "1"
$env:AGENTS_NS = $ns
if ($first) {
$first = $false
$env:SYNC_GITATTR_MODE = $syncModeFirst
} else {
$env:SYNC_GITATTR_MODE = "skip"
}
& $MyInvocation.MyCommand.Path
}
$env:SYNC_STANDARDS_INNER = $oldInner
$env:AGENTS_NS = $oldAgentsNs
$env:SYNC_GITATTR_MODE = $oldMode
exit 0
}
$AgentsNs = $env:AGENTS_NS
if (-not $AgentsNs) { $AgentsNs = "tsl" }
if ($AgentsNs -match '[\\/]' -or $AgentsNs -match '\.\.') {
throw "Invalid AGENTS_NS=$AgentsNs"
}
$AgentsSrc = Join-Path $AgentsSrcRoot $AgentsNs
if (-not (Test-Path $AgentsSrc)) {
# Backward-compatible fallback: older snapshots used <snapshot>/.agents/* directly.
if ((Test-Path (Join-Path $AgentsSrcRoot "index.md")) -and (Test-Path (Join-Path $AgentsSrcRoot "auth.md"))) {
$AgentsSrc = $AgentsSrcRoot
} else {
throw "Agents ruleset not found: $AgentsSrc (set AGENTS_NS to one of the subdirs under $AgentsSrcRoot, e.g. tsl/cpp)."
}
}
$AgentsRoot = Join-Path $Root ".agents"
$AgentsDst = Join-Path $AgentsRoot $AgentsNs
@@ -56,14 +104,16 @@ if (-not (Test-Path $AgentsIndex)) {
建议约定：
- `.agents/tsl/`：TSL 相关规则集（由 `sync_standards.*` 同步；适用于 `.tsl`/`.tsf`）
- `.agents/cpp/`、`.agents/python/` 等：其他语言的规则集（按需增加）
- `.agents/cpp/`：C++ 相关规则集（由 `sync_standards.*` 同步；适用于 C++23/Modules）
- `.agents/python/` 等：其他语言的规则集（按需增加）
规则发生冲突时，建议以“更靠近代码的目录规则更具体”为准。
入口建议从：
- `.agents/tsl/index.md`（TSL 规则集入口）
- `docs/standards/tsl/docs/tsl/`（TSL 人类开发规范快照，推荐 subtree/vendoring 到该路径）
- `.agents/cpp/index.md`（C++ 规则集入口）
- `docs/standards/playbook/docs/`（人类开发规范快照：`tsl/`、`cpp/`、`python/`、`common/`）
'@ | Set-Content -Path $AgentsIndex -Encoding UTF8
Write-Host "Created .agents/index.md"
}
@@ -92,8 +142,10 @@ if (Test-Path $GitAttrSrc) {
break
}
"block" {
$begin = "# BEGIN tsl-playbook .gitattributes"
$end = "# END tsl-playbook .gitattributes"
$begin = "# BEGIN playbook .gitattributes"
$end = "# END playbook .gitattributes"
$beginOld = "# BEGIN tsl-playbook .gitattributes"
$endOld = "# END tsl-playbook .gitattributes"
$src = Get-Content -Path $GitAttrSrc -Raw
$block = $begin + "`r`n" + $src.TrimEnd() + "`r`n" + $end + "`r`n"
@@ -105,7 +157,7 @@ if (Test-Path $GitAttrSrc) {
$dst = Get-Content -Path $bak -Raw
}
$pattern = "(?ms)^" + [regex]::Escape($begin) + "\\R.*?^" + [regex]::Escape($end) + "\\R?"
$pattern = "(?ms)^(" + [regex]::Escape($begin) + "|" + [regex]::Escape($beginOld) + ")\\R.*?^(" + [regex]::Escape($end) + "|" + [regex]::Escape($endOld) + ")\\R?"
if ($dst -and ($dst -match $pattern)) {
$new = [regex]::Replace($dst, $pattern, $block)
} elseif ($dst) {
scripts/sync_standards.sh
+66 -12
View File
@@ -2,20 +2,26 @@
set -eu
# Sync standards snapshot to project root.
# - Copies <snapshot>/.agents -> <project-root>/.agents/tsl
# - Copies <snapshot>/.agents/<AGENTS_NS> -> <project-root>/.agents/<AGENTS_NS>
# - Updates <project-root>/.gitattributes (managed block by default)
# Existing targets are backed up before overwrite.
#
# Multi rulesets:
# sh .../sync_standards.sh tsl cpp
# sh .../sync_standards.sh --langs tsl,cpp
# Notes:
# - When syncing multiple rulesets, .gitattributes is synced only once (first ruleset).
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)"
ROOT="$(CDPATH= cd -- "$ROOT" && pwd -P)"
AGENTS_SRC="$SRC/.agents"
AGENTS_SRC_ROOT="$SRC/.agents"
GITATTR_SRC="$SRC/.gitattributes"
if [ ! -d "$AGENTS_SRC" ]; then
echo "ERROR: Standards snapshot not found at $AGENTS_SRC" >&2
echo "Run: git subtree add --prefix <your-prefix> <standards-url> <branch> --squash" >&2
if [ ! -d "$AGENTS_SRC_ROOT" ]; then
echo "ERROR: Standards snapshot not found at $AGENTS_SRC_ROOT" >&2
echo "Run: git subtree add --prefix docs/standards/playbook <standards-url> <branch> --squash" >&2
exit 1
fi
@@ -27,6 +33,38 @@ if [ "$SRC" = "$ROOT" ]; then
exit 0
fi
# Parse multi rulesets only on the outer invocation.
if [ "${SYNC_STANDARDS_INNER:-}" != "1" ]; then
langs=""
if [ "${1:-}" = "--langs" ]; then
langs="${2:-}"
shift 2
fi
if [ -z "${langs:-}" ] && [ "$#" -gt 0 ]; then
langs="$*"
fi
if [ -n "${langs:-}" ]; then
sync_mode_first="${SYNC_GITATTR_MODE:-block}"
first=1
old_ifs="${IFS}"
IFS=', '
set -- $langs
IFS="${old_ifs}"
for ns in "$@"; do
[ -n "$ns" ] || continue
if [ "$first" -eq 1 ]; then
first=0
SYNC_STANDARDS_INNER=1 AGENTS_NS="$ns" SYNC_GITATTR_MODE="$sync_mode_first" sh "$0"
else
SYNC_STANDARDS_INNER=1 AGENTS_NS="$ns" SYNC_GITATTR_MODE=skip sh "$0"
fi
done
exit 0
fi
fi
: "${AGENTS_NS:=tsl}"
case "$AGENTS_NS" in
""|*/*|*\\*|*..*)
@@ -35,6 +73,18 @@ case "$AGENTS_NS" in
;;
esac
AGENTS_SRC="$AGENTS_SRC_ROOT/$AGENTS_NS"
if [ ! -d "$AGENTS_SRC" ]; then
# Backward-compatible fallback: older snapshots used <snapshot>/.agents/* directly.
if [ -f "$AGENTS_SRC_ROOT/index.md" ] && [ -f "$AGENTS_SRC_ROOT/auth.md" ]; then
AGENTS_SRC="$AGENTS_SRC_ROOT"
else
echo "ERROR: agents ruleset not found: $AGENTS_SRC" >&2
echo "Hint: set AGENTS_NS to one of the subdirs under $AGENTS_SRC_ROOT (e.g. tsl/cpp)." >&2
exit 1
fi
fi
AGENTS_ROOT="$ROOT/.agents"
AGENTS_DST="$AGENTS_ROOT/$AGENTS_NS"
mkdir -p "$AGENTS_ROOT"
@@ -57,14 +107,16 @@ if [ ! -f "$AGENTS_INDEX" ]; then
建议约定：
- `.agents/tsl/`：TSL 相关规则集（由 `sync_standards.*` 同步；适用于 `.tsl`/`.tsf`）
- `.agents/cpp/`、`.agents/python/` 等：其他语言的规则集（按需增加）
- `.agents/cpp/`：C++ 相关规则集（由 `sync_standards.*` 同步；适用于 C++23/Modules）
- `.agents/python/` 等：其他语言的规则集（按需增加）
规则发生冲突时，建议以“更靠近代码的目录规则更具体”为准。
入口建议从：
- `.agents/tsl/index.md`（TSL 规则集入口）
- `docs/standards/tsl/docs/tsl/`（TSL 人类开发规范快照，推荐 subtree/vendoring 到该路径）
- `.agents/cpp/index.md`（C++ 规则集入口）
- `docs/standards/playbook/docs/`（人类开发规范快照：`tsl/`、`cpp/`、`python/`、`common/`）
EOF
echo "Created .agents/index.md"
fi
@@ -91,8 +143,10 @@ if [ -f "$GITATTR_SRC" ]; then
fi
;;
block)
begin="# BEGIN tsl-playbook .gitattributes"
end="# END tsl-playbook .gitattributes"
begin="# BEGIN playbook .gitattributes"
end="# END playbook .gitattributes"
begin_old="# BEGIN tsl-playbook .gitattributes"
end_old="# END tsl-playbook .gitattributes"
if [ -e "$GITATTR_DST" ]; then
mv "$GITATTR_DST" "$ROOT/.gitattributes.bak.$timestamp"
@@ -107,7 +161,7 @@ if [ -f "$GITATTR_SRC" ]; then
fi
if [ -n "$src_dst" ]; then
awk -v begin="$begin" -v end="$end" -v src="$GITATTR_SRC" '
awk -v begin="$begin" -v end="$end" -v begin_old="$begin_old" -v end_old="$end_old" -v src="$GITATTR_SRC" '
function emit_src() {
print begin
while ((getline line < src) > 0) print line
@@ -115,8 +169,8 @@ if [ -f "$GITATTR_SRC" ]; then
print end
}
BEGIN { in_block=0; done=0 }
$0 == begin { in_block=1; if (!done) { emit_src(); done=1 } ; next }
$0 == end { in_block=0; next }
$0 == begin || $0 == begin_old { in_block=1; if (!done) { emit_src(); done=1 } ; next }
$0 == end || $0 == end_old { in_block=0; next }
!in_block { print }
END {
if (!done) {