# App Templates（项目模板）

## 概述

预置的项目目录模板。创建项目时，LLM 根据用户需求自动选择合适的模板（或不用模板），将模板内容复制到工作区，给 agent 明确的技术栈约束和起点。

用户不需要手动选模板——只写需求，模板选择在后端透明完成。

## 目录结构

```
app-templates/
└── webapp/                 # 模板 ID = 目录名
    ├── template.json       # 元信息（不会复制到工作区）
    ├── INSTRUCTIONS.md     # 注入 agent prompt 的指令
    └── scripts/
        └── setup.sh        # 工作区初始化脚本
```

## 模板文件说明

### template.json

```json
{
  "name": "Web 应用",
  "description": "FastAPI + SQLite 的 Web 应用",
  "match_hint": "需要前后端、Web 界面、HTTP API、数据库的应用类项目"
}
```

- `name` / `description`: 人类可读的描述
- `match_hint`: LLM 判断是否匹配时的依据

### INSTRUCTIONS.md

复制到工作区后，agent 每次 LLM 调用时会读取并追加到 system prompt 末尾（规划和执行阶段都会注入）。内容是技术栈约定、项目结构、启动方式等。

### scripts/setup.sh

工作区初始化脚本，在 `ensure_workspace` 阶段执行。如果工作区没有此文件，走默认逻辑（`uv venv .venv`）。应幂等。

## 选择流程

```
用户输入需求
  → select_template()
      1. 扫描 templates_dir() 下所有子目录的 template.json
      2. 构造 prompt，列出所有模板的 {id, name, description, match_hint}
      3. LLM 返回模板 ID 或 "none"
  → apply_template()          # 如果选中了模板
      复制模板目录到工作区（排除 template.json）
  → ensure_workspace()
      检测 scripts/setup.sh → 有则执行，无则默认 venv
  → run_agent_loop()
      读取 INSTRUCTIONS.md，注入 planning/execution prompt
```

## 路径

- 生产环境（Docker）: `/app/templates/`
- 本地开发 fallback: `app-templates/`

`Dockerfile` 中 `COPY app-templates/ ./templates/`。

## 添加新模板

1. 在 `app-templates/` 下建子目录，目录名即模板 ID
2. 创建 `template.json`（必须有 name, description, match_hint）
3. 创建 `INSTRUCTIONS.md`（agent 指令）
4. 可选：创建 `scripts/setup.sh`（初始化脚本，需 `chmod +x`）
5. 不要放代码骨架——让 agent 根据需求 + INSTRUCTIONS.md 自己生成