Template System

模板系统

ai-coding-ok 模板系统的工作原理——双语模板架构、占位符系统和将模板转化为项目文件的安装过程。

---

概述

ai-coding-ok 的核心产品是一套模板文件，安装到用户项目中。模板包含 {{占位符}}，安装时替换为项目特定值。

graph TD
    subgraph "模板（源）"
        EN[templates/en/<br/>18 个文件含占位符]
        ZH[templates/zh/<br/>18 个文件含占位符]
    end
    subgraph "安装过程"
        DETECT[检测语言]
        COPY[复制文件]
        ASK[询问：你想做什么？]
        INFER[推断技术栈]
        REPLACE[替换占位符]
        BOOT[初始化记忆]
    end
    subgraph "已安装（输出）"
        PROJECT[用户项目<br/>18 个文件含真实值]
    end
    EN --> DETECT
    ZH --> DETECT
    DETECT --> COPY --> ASK --> INFER --> REPLACE --> BOOT --> PROJECT

Loading

---

双语架构

自 v3.0.0 起，ai-coding-ok 维护两套平行模板：

templates/
├── en/    ← 英文模板
└── zh/    ← 中文模板

为什么两套独立？

方案	优点	缺点
单一模板 + 运行时翻译	只需维护一套	翻译质量不稳定；占位符逻辑复杂
双语独立模板（已选）	质量可控；可独立测试	需同步维护两套

规则： templates/en/ 的变更必须同步到 templates/zh/，反之亦然。由约定强制执行（ADR-001）。

语言检测

安装时（Mode A），AI 检测用户语言：

• 请求中含中文字符 → templates/zh/
• 否则 → templates/en/
• 不确定时 → 询问用户

---

占位符系统

什么是占位符？

模板文件中的 {{双花括号}} 标记，安装时替换：

# 替换前（模板）
# {{项目名称}} — 架构

这是一个 {{项目类型}}，用 {{编程语言}} + {{框架}} 构建。

# 替换后（已安装）
# 记账工具 — 架构

这是一个个人财务管理工具，用 Python 3.12 + FastAPI 构建。

占位符分类

类别	示例	推断来源
标识	{{项目名称}}、{{项目类型}}	用户的一句话描述
技术栈	{{编程语言}}、{{框架}}、{{数据库}}	从项目类型推断
约定	{{测试框架}}、{{包管理器}}	从技术栈推断
设计	{{设计原则}}、{{架构模式}}	从项目类型推断
日期	{{YYYY-MM-DD}}	当天日期
Hooks	{{SOURCE_DIR_PATTERN}}	用户对"源码目录在哪"的回答

推断逻辑

AI 从用户的一句话描述推断占位符：

输入："一个给自己用的每日记账工具，能分类统计每月花销"

推断：
  项目类型：个人财务管理工具
  语言：Python 3.12（个人工具默认）
  框架：Click（CLI 工具）
  数据库：SQLite（单用户，无需服务器）
  设计原则：极简、实用、离线优先
  用户规模：单用户

不确定时 → 选更简单的方案并记录为 ADR-001

---

模板文件清单

#	文件	用途	有占位符？
1	AGENTS.md	架构速查、PDCA 强制要求	✅
2	CLAUDE.md	Claude Code 自动加载 shim	✅
3	.claude/settings.local.json	Claude Code hooks	✅
4	.cursor/rules/ai-coding-ok.mdc	Cursor alwaysApply 规则	✅
5	.github/copilot-instructions.md	Copilot 行为规则	✅
6-12	.github/ 其他文件	CI、PR 模板、Issue 模板	✅
13-16	.github/agent/ 规范文件	角色、编码规范、工作流	✅
17-19	.github/agent/memory/	三层记忆文件	✅

---

添加新模板

当 ai-coding-ok 需要新功能且涉及模板变更时：

1. 添加模板文件到 templates/en/ 和 templates/zh/
2. 尽量复用现有占位符；仅在必要时添加新占位符
3. 更新 SKILL.md：安装文件列表和占位符替换清单
4. 更新 install.sh / install.py：复制列表和冲突检查
5. 更新 verify.sh：必需文件检查
6. 更新所有模板文件的版本标记

---

模板约束

约束	原因
安装时绝不修改模板	模板是源码，不是配置
始终同步 en/ 和 zh/	双语一致性（ADR-001）
第一行版本标记	升级系统依赖
不含硬编码的项目特定值	模板必须通用

---

下一步

• 文件结构 — 模板在整体结构中的位置
• 占位符系统 — 详细占位符参考
• 自定义模板 — 创建你自己的模板变体