209 lines
6.8 KiB
Markdown
209 lines
6.8 KiB
Markdown
# 项目架构模板
|
||
|
||
本目录包含项目架构的模板文件，用于快速初始化新项目的 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**：
|
||
- 默认：追加路由链接（`<!-- playbook:templates:start/end -->`）
|
||
- `--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 标记**（用于自动更新）：
|
||
|
||
| 标记 | 用途 | 管理脚本 |
|
||
| --------------------------------------- | ----------------------- | -------------- |
|
||
| `<!-- playbook:agents:start/end -->` | 语言规则链接 | sync_standards |
|
||
| `<!-- playbook:templates:start/end -->` | 路由链接（默认追加） | sync_templates |
|
||
| `<!-- playbook:framework:start/end -->` | 完整框架（--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
|