Templetry

Templetry Engine

Templetry 的核心：一个纯 Go 库和轻量 CLI，可根据可编译模板生成可直接使用的代码仓库。

_{生成脚手架、编辑，然后更新：模板的新提交会通过三方合并（基础渲染结果、你的项目、新渲染结果）合并，因此模板的更改会应用到项目中，同时保留你的编辑。此演示通过真实 CLI 对小型样例模板录制（参见开发）。}

状态：🚀 v1 稳定版（最新发布） — 清单、指令、答案文件和注册表的架构，以及 CLI 接口，均为稳定的公共 API，并遵循兼容性政策（ADR-0013）。

v1.0 以来：templetry update（三方合并）、在 Docker 中运行的 templetry verify、惰性组件（pieces/add）、YAML/TOML 补丁、功能的 requires/conflicts 和 presets、多 Forge 模板托管（github:、gitlab:、gitea: 源方案）以及 templetry-mcp 服务。v1.10 起，表单支持分类体系（kinds/languages/frameworks），且 templetry list 可按其筛选。输出路径已针对路径逃逸和平台差异加固；指令扫描器已通过模糊测试。

原则（摘自 wiki）

• 引擎不了解什么是框架——所有知识都存放在各模板的 template.yml 中（ADR-0002）。
• 模板可编译——通过三种转换机制实现：恒等映射式重命名、注释指令、结构化补丁（ADR-0003）。
• 纯粹核心，有副作用的边缘——结果具有确定性：相同输入会产生字节完全一致的输出。

架构

包	职责
manifest	解析并验证 template.yml，推导大小写形式
source	将模板载入内存中的 FileSet
planner	(清单、输入、FileSet) → Plan — 纯函数
ops	将操作类型表示为数据
render	在虚拟文件树上执行 Plan
verify	在 Docker 中运行模板的验证命令
update	更新周期：使用记录的输入重新渲染、比较差异并进行三方合并
answers	.templetry-answers.yml 记录：统一且确定性的读取器/生成器
piece	惰性组件（ADR-0014）：具有独立生命周期的解耦单元
cmd/templetry	轻量 CLI：list、init、plan、render、verify、update、pieces、add、version
cmd/templetry-mcp	MCP 服务（stdio）：将引擎的动词作为工具提供给 AI Agent

设计依据：研究 I · 研究 II。

安装

任选一种方式（Homebrew、Scoop、安装脚本和发布归档中也包含 templetry-mcp）：

1. Homebrew（macOS、Linux）— brew install Templetry/tap/templetry（tap）。
2. Scoop（Windows）— scoop bucket add templetry https://github.com/Templetry/scoop-bucket，然后运行 scoop install templetry（bucket）。
3. 安装脚本（macOS、Linux）— curl -fsSL https://raw.githubusercontent.com/Templetry/engine/main/install.sh | sh（参见 install.sh；TEMPLETRY_VERSION 用于固定版本标签，TEMPLETRY_BIN_DIR 用于指定目录）。
4. 二进制文件 — 从 Releases 下载适用于你平台的可执行文件，将其重命名为 templetry（或 templetry.exe），并放入 PATH 中。
5. Go 工具链 — go install github.com/Templetry/engine/cmd/templetry@latest（安装到 $(go env GOPATH)/bin）。
6. 从源代码安装 — 克隆仓库并运行 go build -o templetry ./cmd/templetry。

然后：

templetry list                                  # browse the official catalog
templetry list --kind database --language go --tags   # filter it
templetry init kmp/single-module --out my-app \
  --set "project_name=My App" --set "base_package=com.me.myapp"
templetry plan --template <dir> --set key=value --feature name
templetry render --template <dir> --out <dir> --set key=value
templetry verify --template <dir> --set key=value    # render to a temp dir and compile it in Docker
templetry update ./my-app                            # preview a template update (--apply to write)
templetry pieces ./my-app                            # lazy pieces the template ships
templetry add axios-api ./my-app --set api_base=/v2  # adopt a piece into a living project

MCP 服务（AI Agent）

templetry-mcp（包含在相同的发布版本中）通过 stdio 使用模型上下文协议，无需依赖，也无需配置。它提供七种工具：list_templates、get_form_schema、plan、render、update、list_pieces 和 add_piece，让 Agent 可以浏览目录、搭建可直接开始工作的项目、采用组件并持续更新项目。下面提供了常见客户端的复制粘贴配置；该服务是一个普通的可执行文件，因此任何其他 MCP 客户端也可用同样的方式运行。它以 io.github.Templetry/templetry-mcp 的名称列在官方 MCP 注册表中，并在每次发布后自动发布。

二进制文件的位置

如果 templetry-mcp 位于 PATH 中，可直接使用命令名 templetry-mcp。某些应用（尤其是 Claude Desktop）不会继承你的 shell PATH，因此需要提供绝对路径：

安装方式	路径
Homebrew，Apple Silicon	/opt/homebrew/bin/templetry-mcp
Homebrew，Intel Mac / Linux	/usr/local/bin/templetry-mcp（Linux brew：/home/linuxbrew/.linuxbrew/bin/templetry-mcp）
install.sh	~/.local/bin/templetry-mcp（以 root 身份运行时为 /usr/local/bin/templetry-mcp）；在 JSON 中填写完整的主目录路径，~ 不会展开
Scoop（Windows）	C:\Users\<you>\scoop\shims\templetry-mcp.exe
下载的发布版二进制文件	你放置它的位置

运行 where templetry-mcp（Windows）或 command -v templetry-mcp 即可显示对应路径。

Claude Code

claude mcp add templetry -- templetry-mcp            # this project, private to you
claude mcp add --scope user templetry -- templetry-mcp   # every project
claude mcp list

Claude Desktop

编辑 claude_desktop_config.json（Settings > Developer > Edit Config；macOS 路径为 ~/Library/Application Support/Claude/，Windows 路径为 %APPDATA%\Claude\），然后重启应用：

{
  "mcpServers": {
    "templetry": {
      "command": "/opt/homebrew/bin/templetry-mcp"
    }
  }
}

在 Windows 上使用 "command": "C:\Users\<you>\scoop\shims\templetry-mcp.exe"。

Cursor

项目中的 .cursor/mcp.json，或适用于所有项目的 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "templetry": {
      "command": "templetry-mcp"
    }
  }
}

VS Code

工作区中的 .vscode/mcp.json（或在每个工作区中使用 "MCP: Open User Configuration"）。注意键名是 servers，而不是 mcpServers：

{
  "servers": {
    "templetry": {
      "type": "stdio",
      "command": "templetry-mcp"
    }
  }
}

该服务不需要参数或环境变量；要使用私有目录，Agent 需要在每次工具调用时传入 registry。

文档

使用指南位于 wiki 中：快速入门、使用模板、使用组件、保持项目更新、编写模板、AI Agent 和 MCP。规范性行为见 spec/。

开发

go build ./...
go test ./...          # CI also runs -race and golangci-lint v2

update 使用 git merge-file 进行合并，因此运行相关测试时，git 必须位于 PATH 中。没有测试会访问网络或需要 Docker：

• internal/forgetest 通过 http.DefaultClient 提供一个内存中的 GitHub（codeload tarball 和 commits API），因此，init → 编辑 → update 会逐个提交地，针对测试发布的模板端到端运行。
• internal/fakedocker 会将测试二进制文件的副本放到 PATH 中并命名为 docker，记录 verify 会运行的内容。
• 两个二进制文件都在进程内测试：templetry 通过 run(args, stdout, stderr) 测试，templetry-mcp 则通过 serve(in, out) 测试，该函数会通过管道建立 JSON-RPC 会话。

上面的演示也以相同方式录制，因此始终展示真实输出。要重新生成它：

TEMPLETRY_DEMO_CAST=$PWD/docs/demo.cast go test ./cmd/templetry -run TestRecordDemo -count=1
npx [email protected] --in docs/demo.cast --out docs/demo.svg --window --no-cursor

许可证

Apache License 2.0 — 可将其用于任何用途，包括商业用途，并明确授予专利许可。模板和桌面应用分别位于采用 MIT 许可证的独立仓库中。