diff --git a/scripts/sync_templates.bat b/scripts/sync_templates.bat new file mode 100644 index 0000000..516334e --- /dev/null +++ b/scripts/sync_templates.bat @@ -0,0 +1,257 @@ +@echo off +setlocal enabledelayedexpansion + +rem Sync project templates to target project. +rem - Copies templates/memory-bank/ -> /memory-bank/ +rem - Copies templates/prompts/ -> /docs/prompts/ +rem - Copies templates/AGENTS.template.md -> /AGENTS.md +rem - Copies templates/AGENT_RULES.template.md -> /AGENT_RULES.md +rem Existing targets are NOT overwritten (skip if exists). +rem +rem Usage: +rem sync_templates.bat # sync to current git root +rem sync_templates.bat # sync to specified project +rem sync_templates.bat --force # overwrite existing files +rem sync_templates.bat --full # append full framework to existing AGENTS.md + +set "SCRIPT_DIR=%~dp0" +for %%I in ("%SCRIPT_DIR%..") do set "SRC=%%~fI" + +set "FORCE=0" +set "FULL=0" +set "PROJECT_ROOT=" + +:parse_args +if "%~1"=="" goto args_done +if /I "%~1"=="--force" ( + set "FORCE=1" + shift + goto parse_args +) +if /I "%~1"=="--full" ( + set "FULL=1" + shift + goto parse_args +) +if /I "%~1"=="-h" goto show_help +if /I "%~1"=="--help" goto show_help +set "PROJECT_ROOT=%~1" +shift +goto parse_args + +:show_help +echo Usage: +echo sync_templates.bat [options] [project-root] +echo. +echo Options: +echo --force Overwrite existing files +echo --full Append full framework (规则优先级 + 新会话开始时) to existing AGENTS.md +echo -h, --help Show this help +exit /b 0 + +:args_done + +rem Determine project root +if "%PROJECT_ROOT%"=="" ( + for /f "delims=" %%R in ('git -C "%SCRIPT_DIR%" rev-parse --show-toplevel 2^>nul') do set "PROJECT_ROOT=%%R" +) +if "%PROJECT_ROOT%"=="" set "PROJECT_ROOT=%cd%" +for %%I in ("%PROJECT_ROOT%") do set "PROJECT_ROOT=%%~fI" + +rem Source directories +set "TEMPLATES_DIR=%SRC%\templates" +set "MEMORY_BANK_SRC=%TEMPLATES_DIR%\memory-bank" +set "PROMPTS_SRC=%TEMPLATES_DIR%\prompts" +set "AGENTS_SRC=%TEMPLATES_DIR%\AGENTS.template.md" +set "AGENT_RULES_SRC=%TEMPLATES_DIR%\AGENT_RULES.template.md" + +rem Check source exists +if not exist "%TEMPLATES_DIR%" ( + echo ERROR: Templates directory not found: %TEMPLATES_DIR% + exit /b 1 +) + +rem Skip if source equals destination +if /I "%SRC%"=="%PROJECT_ROOT%" ( + echo Skip: playbook root equals project root. + echo Done. + exit /b 0 +) + +for /f "usebackq delims=" %%D in (`powershell -NoProfile -Command "Get-Date -Format 'yyyy-MM-dd'"`) do set "SYNC_DATE=%%D" +if "%SYNC_DATE%"=="" set "SYNC_DATE=%date%" + +echo Syncing templates to: %PROJECT_ROOT% +echo. + +rem 1. Sync memory-bank/ +set "MEMORY_BANK_DST=%PROJECT_ROOT%\memory-bank" +if exist "%MEMORY_BANK_SRC%" ( + if exist "%MEMORY_BANK_DST%" ( + if "%FORCE%"=="0" ( + echo memory-bank/ already exists. Skip. Use --force to overwrite. + goto sync_prompts + ) + ) + if not exist "%MEMORY_BANK_DST%" mkdir "%MEMORY_BANK_DST%" + xcopy "%MEMORY_BANK_SRC%\*" "%MEMORY_BANK_DST%\" /e /i /y >nul 2>nul + + rem Rename .template.md to .md + for %%F in ("%MEMORY_BANK_DST%\*.template.md") do ( + set "OLDNAME=%%~nxF" + set "NEWNAME=!OLDNAME:.template.md=.md!" + ren "%%F" "!NEWNAME!" + ) + + rem Replace {{DATE}} placeholder + for %%F in ("%MEMORY_BANK_DST%\*.md") do ( + powershell -NoProfile -Command "$f='%%~fF'; $c=Get-Content -Raw $f; $c=$c.Replace('{{DATE}}','%SYNC_DATE%'); Set-Content -Path $f -Value $c -Encoding UTF8 -NoNewline" + ) + echo Synced: memory-bank/ +) else ( + echo Skip: memory-bank/ templates not found +) + +:sync_prompts +rem 2. Sync docs/prompts/ +set "PROMPTS_DST=%PROJECT_ROOT%\docs\prompts" +if exist "%PROMPTS_SRC%" ( + if exist "%PROMPTS_DST%" ( + if "%FORCE%"=="0" ( + echo docs/prompts/ already exists. Skip. Use --force to overwrite. + goto sync_agents + ) + ) + if not exist "%PROJECT_ROOT%\docs" mkdir "%PROJECT_ROOT%\docs" + if not exist "%PROMPTS_DST%" mkdir "%PROMPTS_DST%" + xcopy "%PROMPTS_SRC%\*" "%PROMPTS_DST%\" /e /i /y >nul 2>nul + + rem Rename .template.md to .md recursively + for /r "%PROMPTS_DST%" %%F in (*.template.md) do ( + set "OLDNAME=%%~nxF" + set "NEWNAME=!OLDNAME:.template.md=.md!" + ren "%%F" "!NEWNAME!" + ) + + rem Replace {{DATE}} placeholder + for /r "%PROMPTS_DST%" %%F in (*.md) do ( + powershell -NoProfile -Command "$f='%%~fF'; $c=Get-Content -Raw $f; $c=$c.Replace('{{DATE}}','%SYNC_DATE%'); Set-Content -Path $f -Value $c -Encoding UTF8 -NoNewline" + ) + echo Synced: docs/prompts/ +) else ( + echo Skip: prompts/ templates not found +) + +:sync_agents +rem 3. Sync AGENTS.md +set "AGENTS_DST=%PROJECT_ROOT%\AGENTS.md" + +rem Choose markers based on --full flag +if "%FULL%"=="1" ( + set "MARKER_START=" + set "MARKER_END=" + set "SECTION_NAME=framework" +) else ( + set "MARKER_START=" + set "MARKER_END=" + set "SECTION_NAME=templates" +) + +if exist "%AGENTS_SRC%" ( + if not exist "%AGENTS_DST%" ( + rem AGENTS.md doesn't exist: create from full template + copy /y "%AGENTS_SRC%" "%AGENTS_DST%" >nul + powershell -NoProfile -Command "$f='%AGENTS_DST%'; $c=Get-Content -Raw $f; $c=$c.Replace('{{DATE}}','%SYNC_DATE%'); Set-Content -Path $f -Value $c -Encoding UTF8 -NoNewline" + echo Created: AGENTS.md + ) else ( + rem AGENTS.md exists: update or append section (extract from template) + powershell -NoProfile -Command ^ + "$src='%AGENTS_SRC%'; $dst='%AGENTS_DST%'; $date='%SYNC_DATE%'; " ^ + "$markerStart='!MARKER_START!'; $markerEnd='!MARKER_END!'; $sectionName='!SECTION_NAME!'; " ^ + "$templateContent = Get-Content -Raw $src; " ^ + "$extractPattern = '(?s)(' + [regex]::Escape($markerStart) + '.*?' + [regex]::Escape($markerEnd) + ')'; " ^ + "if ($templateContent -match $extractPattern) { " ^ + " $snippetContent = $Matches[1]; " ^ + " $content = Get-Content -Raw $dst; " ^ + " if ($content -match [regex]::Escape($markerStart)) { " ^ + " $replacePattern = '(?s)' + [regex]::Escape($markerStart) + '.*?' + [regex]::Escape($markerEnd); " ^ + " $newContent = $content -replace $replacePattern, $snippetContent; " ^ + " $newContent = $newContent.Replace('{{DATE}}', $date); " ^ + " Set-Content -Path $dst -Value $newContent -Encoding UTF8 -NoNewline; " ^ + " Write-Host \"Updated: AGENTS.md ($sectionName section)\"; " ^ + " } else { " ^ + " $newContent = $content.TrimEnd() + \"`n`n\" + $snippetContent; " ^ + " $newContent = $newContent.Replace('{{DATE}}', $date); " ^ + " Set-Content -Path $dst -Value $newContent -Encoding UTF8 -NoNewline; " ^ + " Write-Host \"Appended: AGENTS.md ($sectionName section)\"; " ^ + " } " ^ + "} else { " ^ + " Write-Host 'Skip: markers not found in template'; " ^ + "}" + ) +) else ( + echo Skip: AGENTS.template.md not found +) + +:sync_agent_rules +rem 4. Sync AGENT_RULES.md +set "AGENT_RULES_DST=%PROJECT_ROOT%\AGENT_RULES.md" +if exist "%AGENT_RULES_SRC%" ( + if exist "%AGENT_RULES_DST%" ( + if "%FORCE%"=="0" ( + echo AGENT_RULES.md already exists. Skip. Use --force to overwrite. + goto sync_todo + ) + ) + copy /y "%AGENT_RULES_SRC%" "%AGENT_RULES_DST%" >nul + powershell -NoProfile -Command "$f='%AGENT_RULES_DST%'; $c=Get-Content -Raw $f; $c=$c.Replace('{{DATE}}','%SYNC_DATE%'); Set-Content -Path $f -Value $c -Encoding UTF8 -NoNewline" + echo Synced: AGENT_RULES.md +) else ( + echo Skip: AGENT_RULES.template.md not found +) + +:sync_todo +rem 5. Create TODO.md if not exist +set "TODO_DST=%PROJECT_ROOT%\TODO.md" +if not exist "%TODO_DST%" ( + > "%TODO_DST%" echo # TODO + >> "%TODO_DST%" echo. + >> "%TODO_DST%" echo ## Plan 1: [计划名称] + >> "%TODO_DST%" echo. + >> "%TODO_DST%" echo - [ ] 任务 1 + >> "%TODO_DST%" echo - [ ] 任务 2 + >> "%TODO_DST%" echo. + >> "%TODO_DST%" echo --- + >> "%TODO_DST%" echo. + >> "%TODO_DST%" echo **最后更新**:%SYNC_DATE% + echo Created: TODO.md +) + +rem 6. Create CONFIRM.md if not exist +set "CONFIRM_DST=%PROJECT_ROOT%\CONFIRM.md" +if not exist "%CONFIRM_DST%" ( + > "%CONFIRM_DST%" echo # 待确认事项 + >> "%CONFIRM_DST%" echo. + >> "%CONFIRM_DST%" echo ## 待确认 + >> "%CONFIRM_DST%" echo. + >> "%CONFIRM_DST%" echo ^" + $MarkerEnd = "" + $SectionName = "framework" +} else { + $MarkerStart = "" + $MarkerEnd = "" + $SectionName = "templates" +} + +if (Test-Path $AgentsSrc) { + $AgentsDst = Join-Path $ProjectRoot "AGENTS.md" + + if (-not (Test-Path $AgentsDst)) { + # AGENTS.md doesn't exist: create from full template + Copy-Item -Path $AgentsSrc -Destination $AgentsDst -Force + Replace-Placeholders -File $AgentsDst + Write-Host "Created: AGENTS.md" + } else { + # AGENTS.md exists: update or append section + # Extract snippet from template + $templateContent = Get-Content -Raw -Path $AgentsSrc + $extractPattern = "(?s)(" + [regex]::Escape($MarkerStart) + ".*?" + [regex]::Escape($MarkerEnd) + ")" + if ($templateContent -match $extractPattern) { + $snippetContent = $Matches[1] + + $content = Get-Content -Raw -Path $AgentsDst + + if ($content -match [regex]::Escape($MarkerStart)) { + # Has markers: replace content between markers + $replacePattern = "(?s)" + [regex]::Escape($MarkerStart) + ".*?" + [regex]::Escape($MarkerEnd) + $newContent = $content -replace $replacePattern, $snippetContent + Set-Content -Path $AgentsDst -Value $newContent -Encoding UTF8 -NoNewline + Replace-Placeholders -File $AgentsDst + Write-Host "Updated: AGENTS.md ($SectionName section)" + } else { + # No markers: append snippet at the end + $newContent = $content.TrimEnd() + "`n`n" + $snippetContent + Set-Content -Path $AgentsDst -Value $newContent -Encoding UTF8 -NoNewline + Replace-Placeholders -File $AgentsDst + Write-Host "Appended: AGENTS.md ($SectionName section)" + } + } else { + Write-Host "Skip: markers not found in template" + } + } +} else { + Write-Host "Skip: AGENTS.template.md not found" +} + +# 4. Sync AGENT_RULES.md +if (Test-Path $AgentRulesSrc) { + $AgentRulesDst = Join-Path $ProjectRoot "AGENT_RULES.md" + + if ((Test-Path $AgentRulesDst) -and -not $Force) { + Write-Host "AGENT_RULES.md already exists. Use -Force to overwrite." + } else { + Backup-IfExists -Target $AgentRulesDst + Copy-Item -Path $AgentRulesSrc -Destination $AgentRulesDst -Force + Replace-Placeholders -File $AgentRulesDst + Write-Host "Synced: AGENT_RULES.md" + } +} else { + Write-Host "Skip: AGENT_RULES.template.md not found" +} + +# 5. Create TODO.md and CONFIRM.md if not exist +$TodoPath = Join-Path $ProjectRoot "TODO.md" +if (-not (Test-Path $TodoPath)) { + @" +# TODO + +## Plan 1: [计划名称] + +- [ ] 任务 1 +- [ ] 任务 2 + +--- + +**最后更新**:$Date +"@ | Set-Content -Path $TodoPath -Encoding UTF8 + Write-Host "Created: TODO.md" +} + +$ConfirmPath = Join-Path $ProjectRoot "CONFIRM.md" +if (-not (Test-Path $ConfirmPath)) { + @" +# 待确认事项 + +## 待确认 + + + +## 已确认 + + + +--- + +**最后更新**:$Date +"@ | Set-Content -Path $ConfirmPath -Encoding UTF8 + Write-Host "Created: CONFIRM.md" +} + +Write-Host "" +Write-Host "Done." +Write-Host "" +Write-Host "Next steps:" +Write-Host " 1. Edit memory-bank/*.md to fill in project-specific content" +Write-Host " 2. Replace remaining {{PLACEHOLDER}} values" +Write-Host " 3. Run sync_standards.ps1 to sync .agents/ rules" diff --git a/scripts/sync_templates.sh b/scripts/sync_templates.sh new file mode 100644 index 0000000..f34e57d --- /dev/null +++ b/scripts/sync_templates.sh @@ -0,0 +1,349 @@ +#!/usr/bin/env sh +set -eu + +# Sync project templates to target project. +# - Copies templates/memory-bank/ -> /memory-bank/ +# - Copies templates/prompts/ -> /docs/prompts/ +# - Copies templates/AGENTS.template.md -> /AGENTS.md +# - Copies templates/AGENT_RULES.template.md -> /AGENT_RULES.md +# Existing targets are backed up before overwrite. +# +# Usage: +# sh scripts/sync_templates.sh # sync to current git root +# sh scripts/sync_templates.sh # sync to specified project +# sh scripts/sync_templates.sh --project-name "MyProject" --date "2026-01-20" +# +# Options: +# --project-name NAME Replace {{PROJECT_NAME}} placeholder +# --date DATE Replace {{DATE}} placeholder (default: today) +# --no-backup Skip backup of existing files +# --force Overwrite without prompting + +SCRIPT_DIR="$(CDPATH= cd -- "$(dirname -- "$0")" && pwd -P)" +SRC="$(CDPATH= cd -- "$SCRIPT_DIR/.." && pwd -P)" + +# Defaults +PROJECT_NAME="" +SYNC_DATE="$(date +%Y-%m-%d 2>/dev/null || echo "{{DATE}}")" +NO_BACKUP=0 +FORCE=0 +FULL=0 +PROJECT_ROOT="" + +# Parse arguments +while [ $# -gt 0 ]; do + case "$1" in + --project-name) + PROJECT_NAME="$2" + shift 2 + ;; + --date) + SYNC_DATE="$2" + shift 2 + ;; + --no-backup) + NO_BACKUP=1 + shift + ;; + --force) + FORCE=1 + shift + ;; + --full) + FULL=1 + shift + ;; + -h|--help) + cat <<'EOF' +Usage: + sh scripts/sync_templates.sh [options] [project-root] + +Options: + --project-name NAME Replace {{PROJECT_NAME}} placeholder + --date DATE Replace {{DATE}} placeholder (default: today) + --no-backup Skip backup of existing files + --force Overwrite without prompting + --full Append full framework (规则优先级 + 新会话开始时) to existing AGENTS.md + -h, --help Show this help + +Examples: + sh scripts/sync_templates.sh + sh scripts/sync_templates.sh /path/to/project + sh scripts/sync_templates.sh --full /path/to/project +EOF + exit 0 + ;; + -*) + echo "ERROR: Unknown option: $1" >&2 + exit 1 + ;; + *) + PROJECT_ROOT="$1" + shift + ;; + esac +done + +# Determine project root +if [ -z "$PROJECT_ROOT" ]; then + PROJECT_ROOT="$(git -C "$SCRIPT_DIR" rev-parse --show-toplevel 2>/dev/null || pwd)" +fi +PROJECT_ROOT="$(CDPATH= cd -- "$PROJECT_ROOT" && pwd -P)" + +# Source directories +TEMPLATES_DIR="$SRC/templates" +MEMORY_BANK_SRC="$TEMPLATES_DIR/memory-bank" +PROMPTS_SRC="$TEMPLATES_DIR/prompts" +AGENTS_SRC="$TEMPLATES_DIR/AGENTS.template.md" +AGENT_RULES_SRC="$TEMPLATES_DIR/AGENT_RULES.template.md" + +# Check source exists +if [ ! -d "$TEMPLATES_DIR" ]; then + echo "ERROR: Templates directory not found: $TEMPLATES_DIR" >&2 + exit 1 +fi + +# Skip if source equals destination (running from playbook repo itself) +if [ "$SRC" = "$PROJECT_ROOT" ]; then + echo "Skip: playbook root equals project root." + echo "Done." + exit 0 +fi + +timestamp="$(date +%Y%m%d%H%M%S 2>/dev/null || echo bak)" + +# Function: backup file/directory +backup_if_exists() { + target="$1" + if [ -e "$target" ] && [ "$NO_BACKUP" -eq 0 ]; then + backup="${target}.bak.$timestamp" + mv "$target" "$backup" + echo "Backed up: $(basename "$target") -> $(basename "$backup")" + fi +} + +escape_sed_replacement() { + printf '%s' "$1" | sed 's/[&/|\\]/\\&/g' +} + +# Function: replace placeholders in file +replace_placeholders() { + file="$1" + [ -f "$file" ] || return 0 + + tmp="$(mktemp 2>/dev/null || echo "$file.tmp.$timestamp")" + date_repl="$(escape_sed_replacement "$SYNC_DATE")" + if [ -n "$PROJECT_NAME" ]; then + project_repl="$(escape_sed_replacement "$PROJECT_NAME")" + sed -e "s/{{PROJECT_NAME}}/$project_repl/g" -e "s/{{DATE}}/$date_repl/g" "$file" > "$tmp" + else + sed -e "s/{{DATE}}/$date_repl/g" "$file" > "$tmp" + fi + mv "$tmp" "$file" +} + +# Function: replace placeholders in directory +replace_placeholders_dir() { + dir="$1" + [ -d "$dir" ] || return 0 + + find "$dir" -type f -name '*.md' -print | while IFS= read -r file; do + replace_placeholders "$file" + done +} + +echo "Syncing templates to: $PROJECT_ROOT" +echo "" + +# 1. Sync memory-bank/ +if [ -d "$MEMORY_BANK_SRC" ]; then + MEMORY_BANK_DST="$PROJECT_ROOT/memory-bank" + + if [ -e "$MEMORY_BANK_DST" ] && [ "$FORCE" -eq 0 ]; then + echo "memory-bank/ already exists. Use --force to overwrite." + else + backup_if_exists "$MEMORY_BANK_DST" + mkdir -p "$MEMORY_BANK_DST" + cp -R "$MEMORY_BANK_SRC"/* "$MEMORY_BANK_DST/" 2>/dev/null || true + + # Rename .template.md to .md + for f in "$MEMORY_BANK_DST"/*.template.md; do + [ -f "$f" ] || continue + newname="$(echo "$f" | sed 's/\.template\.md$/.md/')" + mv "$f" "$newname" + done + + replace_placeholders_dir "$MEMORY_BANK_DST" + echo "Synced: memory-bank/" + fi +else + echo "Skip: memory-bank/ templates not found" +fi + +# 2. Sync docs/prompts/ +if [ -d "$PROMPTS_SRC" ]; then + PROMPTS_DST="$PROJECT_ROOT/docs/prompts" + + if [ -e "$PROMPTS_DST" ] && [ "$FORCE" -eq 0 ]; then + echo "docs/prompts/ already exists. Use --force to overwrite." + else + backup_if_exists "$PROMPTS_DST" + mkdir -p "$PROJECT_ROOT/docs" + mkdir -p "$PROMPTS_DST" + cp -R "$PROMPTS_SRC"/* "$PROMPTS_DST/" 2>/dev/null || true + + # Rename .template.md to .md (recursive) + find "$PROMPTS_DST" -type f -name '*.template.md' -print | while IFS= read -r f; do + newname="$(echo "$f" | sed 's/\.template\.md$/.md/')" + mv "$f" "$newname" + done + + replace_placeholders_dir "$PROMPTS_DST" + echo "Synced: docs/prompts/" + fi +else + echo "Skip: prompts/ templates not found" +fi + +# 3. Sync AGENTS.md +# Choose markers based on --full flag +if [ "$FULL" -eq 1 ]; then + MARKER_START="" + MARKER_END="" + SECTION_NAME="framework" +else + MARKER_START="" + MARKER_END="" + SECTION_NAME="templates" +fi + +if [ -f "$AGENTS_SRC" ]; then + AGENTS_DST="$PROJECT_ROOT/AGENTS.md" + + if [ ! -e "$AGENTS_DST" ]; then + # AGENTS.md doesn't exist: create from full template + cp "$AGENTS_SRC" "$AGENTS_DST" + replace_placeholders "$AGENTS_DST" + echo "Created: AGENTS.md" + else + # AGENTS.md exists: update or append section + # Extract snippet from template + snippet_content="$(awk -v start="$MARKER_START" -v end="$MARKER_END" ' + $0 ~ start { found=1 } + found { print } + $0 ~ end { found=0 } + ' "$AGENTS_SRC")" + + if [ -z "$snippet_content" ]; then + echo "Skip: markers not found in template" + elif grep -q "$MARKER_START" "$AGENTS_DST"; then + # Has markers: replace content between markers in place + snippet_tmp="$(mktemp 2>/dev/null || echo "$AGENTS_DST.snippet.$timestamp")" + printf "%s\n" "$snippet_content" > "$snippet_tmp" + tmp="$(mktemp 2>/dev/null || echo "$AGENTS_DST.tmp.$timestamp")" + awk -v start="$MARKER_START" -v end="$MARKER_END" -v snippet="$snippet_tmp" ' + BEGIN { + while ((getline line < snippet) > 0) { block[++n] = line } + close(snippet) + inblock = 0 + replaced = 0 + } + { + if (!replaced && $0 ~ start) { + for (i=1; i<=n; i++) print block[i] + inblock = 1 + replaced = 1 + next + } + if (inblock) { + if ($0 ~ end) { inblock = 0 } + next + } + print + } + ' "$AGENTS_DST" > "$tmp" + mv "$tmp" "$AGENTS_DST" + rm -f "$snippet_tmp" + replace_placeholders "$AGENTS_DST" + echo "Updated: AGENTS.md ($SECTION_NAME section)" + else + # No markers: append snippet at the end + echo "" >> "$AGENTS_DST" + echo "$snippet_content" >> "$AGENTS_DST" + replace_placeholders "$AGENTS_DST" + echo "Appended: AGENTS.md ($SECTION_NAME section)" + fi + fi +else + echo "Skip: AGENTS.template.md not found" +fi + +# 4. Sync AGENT_RULES.md +if [ -f "$AGENT_RULES_SRC" ]; then + AGENT_RULES_DST="$PROJECT_ROOT/AGENT_RULES.md" + + if [ -e "$AGENT_RULES_DST" ] && [ "$FORCE" -eq 0 ]; then + echo "AGENT_RULES.md already exists. Use --force to overwrite." + else + backup_if_exists "$AGENT_RULES_DST" + cp "$AGENT_RULES_SRC" "$AGENT_RULES_DST" + replace_placeholders "$AGENT_RULES_DST" + echo "Synced: AGENT_RULES.md" + fi +else + echo "Skip: AGENT_RULES.template.md not found" +fi + +# 5. Create TODO.md and CONFIRM.md if not exist +if [ ! -f "$PROJECT_ROOT/TODO.md" ]; then + cat > "$PROJECT_ROOT/TODO.md" <<'EOF' +# TODO + +## Plan 1: [计划名称] + +- [ ] 任务 1 +- [ ] 任务 2 + +--- + +**最后更新**:{{DATE}} +EOF + date_repl="$(escape_sed_replacement "$SYNC_DATE")" + if ! sed -i "s/{{DATE}}/$date_repl/g" "$PROJECT_ROOT/TODO.md" 2>/dev/null; then + sed "s/{{DATE}}/$date_repl/g" "$PROJECT_ROOT/TODO.md" > "$PROJECT_ROOT/TODO.md.tmp" + mv "$PROJECT_ROOT/TODO.md.tmp" "$PROJECT_ROOT/TODO.md" + fi + echo "Created: TODO.md" +fi + +if [ ! -f "$PROJECT_ROOT/CONFIRM.md" ]; then + cat > "$PROJECT_ROOT/CONFIRM.md" <<'EOF' +# 待确认事项 + +## 待确认 + + + +## 已确认 + + + +--- + +**最后更新**:{{DATE}} +EOF + date_repl="$(escape_sed_replacement "$SYNC_DATE")" + if ! sed -i "s/{{DATE}}/$date_repl/g" "$PROJECT_ROOT/CONFIRM.md" 2>/dev/null; then + sed "s/{{DATE}}/$date_repl/g" "$PROJECT_ROOT/CONFIRM.md" > "$PROJECT_ROOT/CONFIRM.md.tmp" + mv "$PROJECT_ROOT/CONFIRM.md.tmp" "$PROJECT_ROOT/CONFIRM.md" + fi + echo "Created: CONFIRM.md" +fi + +echo "" +echo "Done." +echo "" +echo "Next steps:" +echo " 1. Edit memory-bank/*.md to fill in project-specific content" +echo " 2. Replace remaining {{PLACEHOLDER}} values" +echo " 3. Run sync_standards.sh to sync .agents/ rules" diff --git a/templates/AGENTS.template.md b/templates/AGENTS.template.md new file mode 100644 index 0000000..9d0647d --- /dev/null +++ b/templates/AGENTS.template.md @@ -0,0 +1,60 @@ +# Agent Instructions + + + +## 规则优先级 + +1. 系统/开发者指令与安全约束 +2. 仓库规则:`.agents/` 与本文件 +3. `AGENT_RULES.md` - 执行流程 +4. `TODO.md` - 任务队列 + +--- + +## 快速导航 + + + +请以 `.agents/` 下的规则为准: + +- 入口:`.agents/index.md` +- 语言规则:`.agents/{{MAIN_LANGUAGE}}/index.md` + + + + +### 核心规则 + +- **执行流程**:[AGENT_RULES.md](./AGENT_RULES.md) +- **AI 行为规范**:[docs/prompts/system/agent-behavior.md](docs/prompts/system/agent-behavior.md) + +### 项目上下文 + +- **项目定位**:[memory-bank/project-brief.md](memory-bank/project-brief.md) +- **技术栈**:[memory-bank/tech-stack.md](memory-bank/tech-stack.md) +- **架构设计**:[memory-bank/architecture.md](memory-bank/architecture.md) +- **进度追踪**:[memory-bank/progress.md](memory-bank/progress.md) +- **架构决策**:[memory-bank/decisions.md](memory-bank/decisions.md) +- **实施计划**:[memory-bank/implementation-plan.md](memory-bank/implementation-plan.md) + +### 工作流程 + +- **需求澄清**:[docs/prompts/coding/clarify.md](docs/prompts/coding/clarify.md) +- **验证检查**:[docs/prompts/coding/verify.md](docs/prompts/coding/verify.md) + + +--- + +## 新会话开始时 + +**AI 应该做的**: + +1. 读取 [AGENT_RULES.md](./AGENT_RULES.md) +2. 读取 [memory-bank/](memory-bank/) 核心文档 +3. 读取 [docs/prompts/system/agent-behavior.md](docs/prompts/system/agent-behavior.md) +4. 查看 [TODO.md](./TODO.md) 和 [CONFIRM.md](./CONFIRM.md) + + +--- + +**最后更新**:{{DATE}} diff --git a/templates/AGENT_RULES.template.md b/templates/AGENT_RULES.template.md new file mode 100644 index 0000000..54c1c2b --- /dev/null +++ b/templates/AGENT_RULES.template.md @@ -0,0 +1,81 @@ +# AGENT_RULES + +目的:为本仓库提供稳定的执行流程。 + +## 优先级 + +1. 系统/开发者指令与安全约束 +2. 仓库规则:`.agents/` 与 `AGENTS.md` +3. 本文件 +4. `TODO.md` + +## 上下文加载(每次会话开始) + +**必读文档**(按顺序): + +1. `memory-bank/project-brief.md` - 项目定位、边界、约束 +2. `memory-bank/tech-stack.md` - 技术栈、工具链 +3. `memory-bank/architecture.md` - 架构设计、模块职责 +4. `TODO.md` - 当前任务队列 +5. `CONFIRM.md` - 待确认事项 + +**目的**:让 AI 快速理解项目全貌,避免重复解释。 + +## 主循环 + +1. 读取 `TODO.md` +2. 选择最上方的 Plan +3. **读取 `memory-bank/implementation-plan.md`**(若该 Plan 有对应说明) +4. 执行该 Plan 内所有可执行子任务 +5. 校验输出结果(运行测试/检查日志) +6. **更新 `memory-bank/progress.md`**(记录已完成事项) +7. 如存在歧义/风险/决策点,记录到 `CONFIRM.md` +8. 若 Plan 已全部完成,则从 `TODO.md` 移除 +9. 若 Plan 因缺少信息而阻塞,标记为 `BLOCKED` 并移到 `TODO.md` 末尾 +10. 重新读取 `TODO.md`,继续下一个 Plan + +## Plan 规则 + +- 不因等待确认而中断;记录到 `CONFIRM.md` 后继续 +- 执行并验证该 Plan 中所有可执行的子任务 +- 若因缺少信息/决策而阻塞:记录 `CONFIRM.md`,标记为 `BLOCKED`,移到末尾(不移除) +- 每轮只处理一个 Plan +- **小步快跑**:每个 Plan 应该可快速完成 +- **可验证**:每个 Plan 必须包含验证步骤 + +## 执行约束 + +### 代码修改约束 + +- **必须先读文件再修改**:不读文件就提议修改是禁止的 +- **必须运行测试验证**:相关测试必须通过 +- **遵循换行规则**:遵循 `.gitattributes` 规则 + +### 决策记录约束 + +- **重要决策**:记录到 `memory-bank/decisions.md`(ADR 格式) +- **临时确认**:记录到 `CONFIRM.md`(会话级) +- **进度留痕**:记录到 `memory-bank/progress.md`(持久化) + +## CONFIRM.md 触发条件 + +- 需求不明确或存在多种可行方案 +- 需要行为/兼容性取舍 +- 风险或约束冲突 +- **架构变更**:影响多个模块的修改 +- **性能权衡**:需要在性能和可维护性之间选择 +- **兼容性问题**:可能破坏现有用户代码 + +## 验证清单 + +每个 Plan 完成后,必须验证: + +- [ ] 代码修改符合 `.agents/` 下的规则 +- [ ] 相关测试通过 +- [ ] 换行符正确 +- [ ] 无语法错误 +- [ ] 更新了 `memory-bank/progress.md` + +--- + +**最后更新**:{{DATE}} diff --git a/templates/README.md b/templates/README.md new file mode 100644 index 0000000..ecfefd7 --- /dev/null +++ b/templates/README.md @@ -0,0 +1,208 @@ +# 项目架构模板 + +本目录包含项目架构的模板文件,用于快速初始化新项目的 AI 代理工作环境。 + +## 目录结构 + +```text +templates/ +├── README.md # 本文件 +├── AGENTS.template.md # 路由中心模板 +├── AGENT_RULES.template.md # 执行流程模板 +├── memory-bank/ # 项目上下文模板 +│ ├── project-brief.template.md +│ ├── tech-stack.template.md +│ ├── architecture.template.md +│ ├── progress.template.md +│ ├── decisions.template.md +│ └── implementation-plan.template.md +├── prompts/ # 提示词库模板 +│ ├── README.md +│ ├── system/ +│ │ └── agent-behavior.template.md +│ └── coding/ +│ ├── clarify.template.md +│ └── verify.template.md +├── ci/ # CI 模板 +│ └── gitea/ +│ └── .gitea/workflows/ +├── cpp/ # C++ 配置模板 +│ ├── .clang-format +│ ├── .clangd +│ └── ... +└── python/ # Python 配置模板 + ├── .editorconfig + ├── pyproject.toml + └── ... +``` + +## 快速部署 + +使用 `sync_templates` 脚本一键部署: + +**Linux/macOS**: + +```bash +# 基础部署 +sh scripts/sync_templates.sh /path/to/project + +# 追加完整框架到已有 AGENTS.md +sh scripts/sync_templates.sh --full /path/to/project +``` + +**Windows PowerShell**: + +```powershell +# 基础部署 +.\scripts\sync_templates.ps1 -ProjectRoot C:\path\to\project + +# 追加完整框架 +.\scripts\sync_templates.ps1 -ProjectRoot C:\path\to\project -Full +``` + +**Windows CMD**: + +```cmd +scripts\sync_templates.bat C:\path\to\project +scripts\sync_templates.bat --full C:\path\to\project +``` + +### 部署行为 + +- **新项目**:创建完整的 AGENTS.md、AGENT_RULES.md、memory-bank/、docs/prompts/ +- **已有 AGENTS.md**: + - 默认:追加路由链接(``) + - `--full`:追加完整框架(规则优先级 + 路由 + 新会话开始时) +- **其他文件**:如果已存在则跳过(使用 `--force` 覆盖) +- **自动创建**:TODO.md 和 CONFIRM.md(如果不存在) +- **占位符替换**:自动替换 `{{DATE}}` 为当前日期 + +### 部署后的目录结构 + +```text +project/ +├── AGENTS.md # 路由中心(主入口) +├── AGENT_RULES.md # 执行流程 +├── TODO.md # 任务队列 +├── CONFIRM.md # 待确认事项 +├── memory-bank/ # 项目上下文 +│ ├── project-brief.md +│ ├── tech-stack.md +│ ├── architecture.md +│ ├── progress.md +│ ├── decisions.md +│ └── implementation-plan.md +└── docs/prompts/ # 提示词库 + ├── README.md + ├── system/agent-behavior.md + └── coding/ + ├── clarify.md + └── verify.md +``` + +## 占位符说明 + +模板中使用 `{{PLACEHOLDER}}` 格式的占位符,需要替换为实际值: + +| 占位符 | 说明 | 自动替换 | +| ------------------------- | ------------ | -------- | +| `{{DATE}}` | 日期 | ✅ 是 | +| `{{PROJECT_NAME}}` | 项目名称 | ❌ 手动 | +| `{{PROJECT_GOAL}}` | 项目目标 | ❌ 手动 | +| `{{PROJECT_DESCRIPTION}}` | 项目描述 | ❌ 手动 | +| `{{MAIN_LANGUAGE}}` | 主语言 | ❌ 手动 | +| 其他 `{{...}}` | 项目特定内容 | ❌ 手动 | + +## 模板说明 + +### memory-bank/ + +项目上下文文档,用于让 AI 快速理解项目: + +| 文件 | 用途 | +| --------------------------------- | -------------------- | +| `project-brief.template.md` | 项目定位、边界、约束 | +| `tech-stack.template.md` | 技术栈、工具链、环境 | +| `architecture.template.md` | 架构设计、模块职责 | +| `progress.template.md` | 开发进度追踪 | +| `decisions.template.md` | 架构决策记录(ADR) | +| `implementation-plan.template.md` | 当前实施计划 | + +### prompts/ + +工作流程模板: + +| 文件 | 用途 | +| ----------------------------------- | ------------ | +| `system/agent-behavior.template.md` | AI 行为规范 | +| `coding/clarify.template.md` | 需求澄清模板 | +| `coding/verify.template.md` | 验证检查清单 | + +### AGENT_RULES.template.md + +执行流程规范,定义 AI 的工作循环和约束。 + +### AGENTS.template.md + +路由中心模板,作为项目的主入口。 + +**设计理念**: + +- **最小化内容**:只包含导航链接,不包含详细规则 +- **结构化导航**:分为核心规则、项目上下文、工作流程三个板块 + +**playbook 标记**(用于自动更新): + +| 标记 | 用途 | 管理脚本 | +| --------------------------------------- | ----------------------- | -------------- | +| `` | 语言规则链接 | sync_standards | +| `` | 路由链接(默认追加) | sync_templates | +| `` | 完整框架(--full 追加) | sync_templates | + +### ci/、cpp/、python/ + +语言和 CI 配置模板。通过 `vendor_playbook --apply-templates` 部署: + +| 目录 | 内容 | 部署位置 | +| ----------- | ----------------------------------------- | ---------- | +| `ci/gitea/` | Gitea Actions 工作流 | `.gitea/` | +| `cpp/` | .clang-format, .clangd, CMakeLists.txt 等 | 项目根目录 | +| `python/` | pyproject.toml, .editorconfig 等 | 项目根目录 | + +**使用方式**: + +```bash +# vendor_playbook 时一并部署 +sh scripts/vendor_playbook.sh /path/to/project tsl cpp --apply-templates +``` + +## 与 playbook 其他部分的关系 + +```text +playbook/ +├── rulesets/ # 语言级硬规则 → 部署到 .agents/ +├── codex/skills/ # 按需加载的技能 +├── docs/ # 权威静态文档 +├── templates/ # 本目录:项目架构模板 → 部署到 memory-bank/ 等 +└── scripts/ + ├── sync_standards.* # 同步 .agents/ 和 .gitattributes + └── sync_templates.* # 同步 memory-bank/、docs/prompts/、AGENT_RULES.md +``` + +## 完整部署流程 + +```bash +# 1. 部署项目架构模板 +sh scripts/sync_templates.sh /path/to/project + +# 2. 部署语言规则 +sh scripts/sync_standards.sh tsl # 或其他语言 + +# 3. 编辑 memory-bank/*.md 填写项目信息 + +# 4. 替换剩余的 {{PLACEHOLDER}} 占位符 +``` + +--- + +**最后更新**:2026-01-21 diff --git a/templates/memory-bank/architecture.template.md b/templates/memory-bank/architecture.template.md new file mode 100644 index 0000000..b971f1b --- /dev/null +++ b/templates/memory-bank/architecture.template.md @@ -0,0 +1,110 @@ +# 架构设计 + +## 整体架构 + +```txt +┌─────────────────────────────────────────────────────────────┐ +│ {{LAYER_1}} │ +└─────────────────────┬───────────────────────────────────────┘ + │ + ↓ +┌─────────────────────────────────────────────────────────────┐ +│ {{LAYER_2}} │ +└─────────────────────┬───────────────────────────────────────┘ + │ + ↓ +┌─────────────────────────────────────────────────────────────┐ +│ {{LAYER_3}} │ +└─────────────────────────────────────────────────────────────┘ +``` + +## 核心模块 + +### 1. {{MODULE_1}} + +**职责**:{{MODULE_1_DESC}} + +**主要组件**: + +- {{COMPONENT_1}} +- {{COMPONENT_2}} + +**核心方法**: + +- {{METHOD_1}} +- {{METHOD_2}} + +--- + +### 2. {{MODULE_2}} + +**职责**:{{MODULE_2_DESC}} + +**主要组件**: + +- {{COMPONENT_3}} +- {{COMPONENT_4}} + +--- + +### 3. {{MODULE_3}} + +**职责**:{{MODULE_3_DESC}} + +--- + +## 设计模式 + +### {{PATTERN_1}} + +**应用**:{{PATTERN_1_USAGE}} + +**目的**:{{PATTERN_1_PURPOSE}} + +**优点**: + +- {{PATTERN_1_ADVANTAGE_1}} +- {{PATTERN_1_ADVANTAGE_2}} + +### {{PATTERN_2}} + +**应用**:{{PATTERN_2_USAGE}} + +**目的**:{{PATTERN_2_PURPOSE}} + +--- + +## 关键约束 + +### 1. {{CONSTRAINT_CATEGORY_1}} + +- {{CONSTRAINT_1}} +- {{CONSTRAINT_2}} + +### 2. {{CONSTRAINT_CATEGORY_2}} + +- {{CONSTRAINT_3}} +- {{CONSTRAINT_4}} + +--- + +## 扩展点 + +### 1. {{EXTENSION_1}} + +**步骤**: + +1. {{STEP_1}} +2. {{STEP_2}} +3. {{STEP_3}} + +### 2. {{EXTENSION_2}} + +**步骤**: + +1. {{STEP_4}} +2. {{STEP_5}} + +--- + +**最后更新**:{{DATE}} diff --git a/templates/memory-bank/decisions.template.md b/templates/memory-bank/decisions.template.md new file mode 100644 index 0000000..607ae70 --- /dev/null +++ b/templates/memory-bank/decisions.template.md @@ -0,0 +1,76 @@ +# 架构决策记录 + +本文档记录项目中的重要架构决策,使用 ADR (Architecture Decision Record) 格式。 + +--- + +## ADR-001: {{DECISION_1_TITLE}} + +**日期**: {{DATE}} +**状态**: 已采纳 + +### 决策 + +{{DECISION_1_CONTENT}} + +### 理由 + +{{DECISION_1_REASON}} + +### 影响 + +{{DECISION_1_IMPACT}} + +### 实施细节 + +{{DECISION_1_IMPLEMENTATION}} + +--- + +## ADR-002: {{DECISION_2_TITLE}} + +**日期**: {{DATE}} +**状态**: 已采纳 + +### 决策 + +{{DECISION_2_CONTENT}} + +### 理由 + +{{DECISION_2_REASON}} + +### 影响 + +{{DECISION_2_IMPACT}} + +--- + +## ADR 模板 + +```markdown +## ADR-XXX: 决策标题 + +**日期**: YYYY-MM-DD +**状态**: 已采纳 / 已废弃 / 待讨论 + +### 决策 + +简要描述决策内容 + +### 理由 + +为什么做出这个决策 + +### 影响 + +对项目的影响 + +### 替代方案(可选) + +考虑过但未采纳的方案 +``` + +--- + +**最后更新**:{{DATE}} diff --git a/templates/memory-bank/implementation-plan.template.md b/templates/memory-bank/implementation-plan.template.md new file mode 100644 index 0000000..34b1780 --- /dev/null +++ b/templates/memory-bank/implementation-plan.template.md @@ -0,0 +1,91 @@ +# 当前实施计划 + +## 计划状态 + +**计划名称**: {{PLAN_NAME}} +**开始时间**: {{START_DATE}} +**当前状态**: 进行中 / 已完成 / 已暂停 + +--- + +## 目标 + +{{PLAN_GOAL}} + +**成功标准**: + +- [ ] {{SUCCESS_CRITERIA_1}} +- [ ] {{SUCCESS_CRITERIA_2}} +- [ ] {{SUCCESS_CRITERIA_3}} + +--- + +## 实施步骤 + +### 阶段 1: {{PHASE_1_NAME}} + +#### 步骤 1.1: {{STEP_1_1}} + +- [ ] {{TASK_1_1_1}} +- [ ] {{TASK_1_1_2}} + +**验证**: {{VERIFICATION_1_1}} + +#### 步骤 1.2: {{STEP_1_2}} + +- [ ] {{TASK_1_2_1}} +- [ ] {{TASK_1_2_2}} + +**验证**: {{VERIFICATION_1_2}} + +--- + +### 阶段 2: {{PHASE_2_NAME}} + +#### 步骤 2.1: {{STEP_2_1}} + +- [ ] {{TASK_2_1_1}} +- [ ] {{TASK_2_1_2}} + +**验证**: {{VERIFICATION_2_1}} + +--- + +## 当前进度 + +### 已完成 + +- {{COMPLETED_PHASE}} + +### 进行中 + +- {{IN_PROGRESS_STEP}} + +### 待开始 + +- {{PENDING_STEP}} + +--- + +## 风险与问题 + +### 风险 + +1. **{{RISK_1}}** + - 风险:{{RISK_1_DESC}} + - 缓解:{{RISK_1_MITIGATION}} + +### 已解决的问题 + +1. {{RESOLVED_ISSUE_1}} + +--- + +## 下一步行动 + +- [ ] {{NEXT_ACTION_1}} +- [ ] {{NEXT_ACTION_2}} + +--- + +**最后更新**:{{DATE}} diff --git a/templates/memory-bank/progress.template.md b/templates/memory-bank/progress.template.md new file mode 100644 index 0000000..8820aeb --- /dev/null +++ b/templates/memory-bank/progress.template.md @@ -0,0 +1,60 @@ +# 开发进度追踪 + +## 当前阶段:{{CURRENT_PHASE}} + +### 最近完成 + +#### {{DATE}} + +- [x] {{COMPLETED_1}} +- [x] {{COMPLETED_2}} + +### 进行中 + +- [ ] {{IN_PROGRESS_1}} +- [ ] {{IN_PROGRESS_2}} + +### 待办 + +#### {{CATEGORY_1}} + +- [ ] {{TODO_1}} +- [ ] {{TODO_2}} + +#### {{CATEGORY_2}} + +- [ ] {{TODO_3}} +- [ ] {{TODO_4}} + +### 已知问题 + +#### {{ISSUE_CATEGORY_1}} + +- {{ISSUE_1}} + - **临时方案**:{{WORKAROUND_1}} + - **长期方案**:{{SOLUTION_1}} + +### 里程碑 + +#### M1: {{MILESTONE_1}}(目标:{{TARGET_DATE_1}}) + +- [ ] {{MILESTONE_1_TASK_1}} +- [ ] {{MILESTONE_1_TASK_2}} + +#### M2: {{MILESTONE_2}}(目标:{{TARGET_DATE_2}}) + +- [ ] {{MILESTONE_2_TASK_1}} +- [ ] {{MILESTONE_2_TASK_2}} + +--- + +## 更新日志 + +### {{DATE}} + +- {{LOG_1}} +- {{LOG_2}} + +--- + +**最后更新**:{{DATE}} diff --git a/templates/memory-bank/project-brief.template.md b/templates/memory-bank/project-brief.template.md new file mode 100644 index 0000000..6d2fa9b --- /dev/null +++ b/templates/memory-bank/project-brief.template.md @@ -0,0 +1,66 @@ +# {{PROJECT_NAME}} 项目简介 + +## 项目定位 + +**核心目标**:{{PROJECT_GOAL}} + +**一句话描述**:{{PROJECT_DESCRIPTION}} + +## 为什么做这个项目? + +### 问题 + +- {{PROBLEM_1}} +- {{PROBLEM_2}} +- {{PROBLEM_3}} + +### 解决方案 + +- {{SOLUTION_1}} +- {{SOLUTION_2}} +- {{SOLUTION_3}} + +## 项目边界 + +### 做什么 + +- {{DO_1}} +- {{DO_2}} +- {{DO_3}} + +### 不做什么 + +- {{DONT_1}} +- {{DONT_2}} +- {{DONT_3}} + +### 约束条件 + +- {{CONSTRAINT_1}} +- {{CONSTRAINT_2}} +- {{CONSTRAINT_3}} + +## 核心概念 + + + +## 技术栈 + +- **主语言**:{{MAIN_LANGUAGE}} +- **外部依赖**:{{DEPENDENCIES}} +- **测试环境**:{{TEST_ENV}} + +## 参考资料 + +- {{REFERENCE_1}} +- {{REFERENCE_2}} + +## 当前状态 + +- {{STATUS_1}} +- {{STATUS_2}} +- {{STATUS_3}} + +--- + +**最后更新**:{{DATE}} diff --git a/templates/memory-bank/tech-stack.template.md b/templates/memory-bank/tech-stack.template.md new file mode 100644 index 0000000..e409811 --- /dev/null +++ b/templates/memory-bank/tech-stack.template.md @@ -0,0 +1,118 @@ +# 技术栈与工具链 + +## 核心技术 + +### 主语言:{{MAIN_LANGUAGE}} + +**文件类型**: + +- {{FILE_TYPE_1}} +- {{FILE_TYPE_2}} + +**特点**: + +- {{FEATURE_1}} +- {{FEATURE_2}} +- {{FEATURE_3}} + +**运行方式**: + +- {{RUN_METHOD_1}} +- {{RUN_METHOD_2}} + +## 项目结构 + +```text +{{PROJECT_NAME}}/ +├── {{DIR_1}}/ # {{DIR_1_DESC}} +├── {{DIR_2}}/ # {{DIR_2_DESC}} +├── {{DIR_3}}/ # {{DIR_3_DESC}} +└── memory-bank/ # 项目上下文 +``` + +## 开发环境 + +### {{ENV_1}} + +**必需工具**: + +- {{TOOL_1}} +- {{TOOL_2}} + +**运行测试**: + +```bash +{{TEST_CMD_1}} +``` + +### {{ENV_2}}(如有) + +**必需工具**: + +- {{TOOL_3}} +- {{TOOL_4}} + +## 版本控制 + +### Git 配置 + +**换行规则**(`.gitattributes`): + +- 遵循 `.gitattributes` 文件定义 + +**忽略规则**(`.gitignore`): + +- 以 `.gitignore` 实际内容为准 + +### 分支策略 + +- `master`/`main`:主分支(稳定版本) +- 功能分支:按需创建 + +## 测试策略 + +### 测试类型 + +- {{TEST_TYPE_1}} +- {{TEST_TYPE_2}} + +### 验证标准 + +**测试通过条件**: + +1. {{PASS_CONDITION_1}} +2. {{PASS_CONDITION_2}} +3. {{PASS_CONDITION_3}} + +**常见失败原因**: + +- {{FAIL_REASON_1}} +- {{FAIL_REASON_2}} + +## 依赖管理 + +### 外部依赖 + +- {{EXTERNAL_DEP_1}} +- {{EXTERNAL_DEP_2}} + +### 内部依赖 + +- {{INTERNAL_DEP_1}} +- {{INTERNAL_DEP_2}} + +## 性能考虑 + +### 当前瓶颈 + +- {{BOTTLENECK_1}} +- {{BOTTLENECK_2}} + +### 优化方向 + +- {{OPTIMIZATION_1}} +- {{OPTIMIZATION_2}} + +--- + +**最后更新**:{{DATE}} diff --git a/templates/prompts/README.md b/templates/prompts/README.md new file mode 100644 index 0000000..42b9e2c --- /dev/null +++ b/templates/prompts/README.md @@ -0,0 +1,42 @@ +# 提示词库 + +本目录包含 AI 代理的工作流程模板和参考文档。 + +## 目录结构 + +```text +prompts/ +├── README.md # 本文件 +├── system/ # 系统级规范 +│ └── agent-behavior.md +├── coding/ # 编码流程 +│ ├── clarify.md # 需求澄清模板 +│ └── verify.md # 验证检查清单 +└── user/ # 用户快捷命令 + └── quick-test.md # 快速测试命令 +``` + +## 使用方式 + +### AI 代理 + +- 新会话时读取 `system/agent-behavior.md` +- 需要澄清需求时参考 `coding/clarify.md` +- 完成任务前检查 `coding/verify.md` + +### 用户 + +- 使用 `user/quick-test.md` 中的命令快速执行测试 + +## 文档说明 + +| 文件 | 用途 | +| -------------------------- | ------------------------------- | +| `system/agent-behavior.md` | AI 行为规范、工作模式、禁止行为 | +| `coding/clarify.md` | 需求澄清步骤和问题模板 | +| `coding/verify.md` | 代码、测试、文档验证清单 | +| `user/quick-test.md` | 常用测试命令参考 | + +--- + +**最后更新**:{{DATE}} diff --git a/templates/prompts/coding/clarify.template.md b/templates/prompts/coding/clarify.template.md new file mode 100644 index 0000000..9fe804f --- /dev/null +++ b/templates/prompts/coding/clarify.template.md @@ -0,0 +1,129 @@ +# 需求澄清模板 + +## 何时使用 + +- 需求描述不明确 +- 存在多种理解方式 +- 缺少关键信息 + +--- + +## 澄清步骤 + +### 1. 理解当前需求 + +**复述需求**: + +```text +我理解你的需求是:[用自己的话复述] +``` + +**识别歧义点**: + +- 歧义 1:[描述不明确的地方] +- 歧义 2:[可能有多种理解的地方] + +--- + +### 2. 提出澄清问题 + +**问题模板**: + +> 只问阻塞问题,最多 1–2 个;优先给出选项让用户选择。 + +#### 功能范围 + +- 这个功能是否包括 [场景 A]? +- 是否需要支持 [边界情况 B]? +- 优先级如何?必须有 vs 可选 + +#### 行为细节 + +- 当 [条件 X] 时,应该 [行为 Y] 还是 [行为 Z]? +- 如果 [异常情况],如何处理? +- 是否需要与 [现有功能] 保持一致? + +#### 技术约束 + +- 是否有性能要求? +- 是否有兼容性要求? +- 是否有安全要求? + +--- + +### 3. 提供选项 + +**选项格式**: + +**选项 A**:[方案描述] + +- 优点:[列出优点] +- 缺点:[列出缺点] +- 适用场景:[什么情况下选这个] + +**选项 B**:[方案描述] + +- 优点:[列出优点] +- 缺点:[列出缺点] +- 适用场景:[什么情况下选这个] + +**推荐**:[推荐哪个选项,为什么] + +--- + +### 4. 确认理解 + +**确认清单**: + +- [ ] 功能范围明确 +- [ ] 行为细节清晰 +- [ ] 技术约束已知 +- [ ] 优先级确定 +- [ ] 验收标准明确 + +--- + +## 示例 + +### 需求 + +```text +实现 XXX 功能 +``` + +### 澄清过程 + +**复述需求**: + +```text +我理解你的需求是:为 YYY 添加 XXX 功能, +用于 ZZZ。 +``` + +**识别歧义点**: + +- 歧义 1:XXX 是只读还是可写? +- 歧义 2:是否需要支持所有场景? + +**澄清问题**: + +- 是否需要支持 [场景 A]? +- 当 [条件 X] 时,应该如何处理? + +**提供选项**: + +**选项 A**:完整实现 + +- 优点:功能完整 +- 缺点:开发周期长 + +**选项 B**:核心功能 + +- 优点:快速交付 +- 缺点:功能有限 + +**推荐**:选项 A,因为 [原因]。 + +--- + +**最后更新**:{{DATE}} diff --git a/templates/prompts/coding/verify.template.md b/templates/prompts/coding/verify.template.md new file mode 100644 index 0000000..2ae77c5 --- /dev/null +++ b/templates/prompts/coding/verify.template.md @@ -0,0 +1,94 @@ +# 验证检查清单 + +## 代码修改验证 + +### 语法检查 + +- [ ] 代码可正常运行(无语法错误) +- [ ] 无未定义的变量或函数 +- [ ] 依赖引用正确 + +### 风格检查 + +- [ ] 命名符合规范 +- [ ] 缩进正确 +- [ ] 换行符正确(遵循 .gitattributes) +- [ ] 无冗余注释 + +--- + +## 测试验证 + +### 单元测试 + +- [ ] 相关测试脚本存在 +- [ ] 测试可正常运行 +- [ ] 测试通过(无失败) + +### 回归测试 + +- [ ] 现有测试仍然通过 +- [ ] 未破坏其他功能 + +--- + +## 文档验证 + +### 代码文档 + +- [ ] 复杂逻辑有注释说明 +- [ ] 公开 API 有使用示例(如需) + +### 项目文档 + +- [ ] `memory-bank/progress.md` 已更新 +- [ ] 重要决策记录到 `memory-bank/decisions.md` +- [ ] `CONFIRM.md` 中需讨论事项已记录 + +--- + +## Git 验证 + +### 提交前检查 + +- [ ] 只包含相关修改(无无关文件) +- [ ] 提交信息清晰 +- [ ] 无临时文件或调试代码 + +### 分支检查 + +- [ ] 在正确的分支上工作 + +--- + +## 性能验证(如果涉及) + +### 性能测试 + +- [ ] 处理时间可接受 +- [ ] 内存使用正常 +- [ ] 无明显性能退化 + +--- + +## 安全验证(如果涉及) + +### 安全检查 + +- [ ] 无注入风险 +- [ ] 敏感信息已脱敏 + +--- + +## 快速检查清单(最小集) + +**每次修改必须检查**: + +- [ ] 代码可运行(无语法错误) +- [ ] 相关测试通过 +- [ ] 换行符正确 +- [ ] `memory-bank/progress.md` 已更新 + +--- + +**最后更新**:{{DATE}} diff --git a/templates/prompts/system/agent-behavior.template.md b/templates/prompts/system/agent-behavior.template.md new file mode 100644 index 0000000..71f1769 --- /dev/null +++ b/templates/prompts/system/agent-behavior.template.md @@ -0,0 +1,196 @@ +# AI 代理行为规范 + +## 工作模式 + +### 模式 1: 探索模式(Explore) + +**目的**:理解代码库、分析问题、收集信息 + +**行为规范**: + +- 使用搜索工具探索代码 +- 输出分析报告和发现 +- 提出问题和建议 +- 不修改任何代码 +- 不运行测试(除非明确要求) + +**适用场景**: + +- 理解某个模块的实现 +- 分析 bug 的根本原因 +- 评估功能实现的可行性 + +--- + +### 模式 2: 开发模式(Develop) + +**目的**:实现功能、修复 bug、重构代码 + +**行为规范**: + +- 先读取相关文件,理解现有逻辑 +- 进行精确修改 +- 修改后运行对应测试验证 +- 更新 `memory-bank/progress.md` +- 不读文件就提议修改 +- 不跳过测试直接提交 + +**适用场景**: + +- 实现新功能 +- 修复已知 bug +- 优化性能 + +--- + +### 模式 3: 调试模式(Debug) + +**目的**:诊断问题、对比差异、验证行为 + +**行为规范**: + +- 收集相关日志和输出 +- 分析差异原因 +- 记录到 `CONFIRM.md` 或直接修复 +- 重新验证 + +**适用场景**: + +- 测试失败 +- 输出不符合预期 +- 性能问题诊断 + +--- + +## 代码风格要求 + +### 通用规范 + +**命名规范**: + +- 遵循项目现有的命名风格 +- 保持一致性 + +**缩进**: + +- 遵循项目现有的缩进风格 + +**换行**: + +- 遵循 `.gitattributes` 规则 + +**注释**: + +- 只在逻辑不自明时添加注释 +- 不添加冗余注释 + +--- + +## 禁止行为清单 + +### 代码修改 + +- **不读文件就提议修改** + + - 必须先读取文件 + - 理解现有逻辑后再提出修改建议 + +- **破坏现有架构** + + - 不随意移动目录结构 + - 不随意重构核心模块 + +- **随意改动换行符** + - 遵循 `.gitattributes` 规则 + - 不混用 LF 和 CRLF + +### 测试流程 + +- **跳过测试直接提交** + - 修改后必须运行相关测试 + - 测试失败必须分析原因 + +### Git 操作 + +- **使用 `git commit --amend`** + + - 除非用户明确要求 + - 总是创建新提交 + +- **使用 `git push --force`** + + - 特别是推送到 main/master 分支 + - 如果用户要求,必须警告风险 + +- **跳过 hooks** + - 不使用 `--no-verify` + +### 过度工程 + +- **添加未要求的功能** + + - 只做用户要求的修改 + - 不主动重构周边代码 + +- **添加不必要的注释** + + - 不给自明的代码添加注释 + +- **过度抽象** + - 不为一次性操作创建工具函数 + - 不为假设的未来需求设计 + +--- + +## 决策原则 + +### 何时记录到 CONFIRM.md + +**必须记录**: + +- 需求有歧义,存在多种理解 +- 有多个技术方案,需要权衡 +- 可能破坏兼容性 +- 涉及架构变更 + +**可以不记录**: + +- 明显的 bug 修复 +- 符合现有模式的小改动 +- 测试用例补充 + +### 何时记录到 decisions.md + +**必须记录**(ADR 格式): + +- 影响多个模块的架构决策 +- 技术栈选择 +- 设计模式选择 +- 重要的约束条件 + +--- + +## 沟通原则 + +### 输出风格 + +- 简洁明确,避免冗长 +- 使用纯文本结构化输出,必要时用 Markdown 代码块 +- 代码块标注语言 +- 不使用 emoji(除非用户明确要求) +- 不使用过度的赞美或验证 + +### 技术准确性 + +- 优先技术准确性,而非迎合用户 +- 发现用户理解有误时,礼貌纠正 +- 不确定时,先调查再回答 + +### 时间估算 + +- 不给出时间估算 +- 专注于任务本身,让用户自己判断时间 + +--- + +**最后更新**:{{DATE}}