# Starter 模板采用指南

本指南说明如何将插件 starter 模板定制为项目本地权威模板，以及后续模板升级时的评审流程。

## 概述

`artifact-chain-assistant` 提供的 starter 模板是**入门指导**，不是项目权威。项目采用扩展制品类型时，必须将 starter 模板复制到本地并定制，定制后的模板成为项目权威。

```
插件 starter 模板（入门指导）
    ↓ 复制 + 定制
项目本地模板（权威）
```

## 采用流程

### 步骤 1：评估是否需要该类型

在采用前，确认项目有对应的本地证据：

| 制品类型 | 启用证据 |
|---------|---------|
| `api_contract` | 存在 OpenAPI spec、API 文档或 REST 端点代码 |
| `cli_contract` | 存在 CLI 入口代码或命令定义 |
| `data_contract` | 存在数据模型定义或 schema 文件 |
| `domain_model` | 存在 DDD 聚合、实体或值对象代码 |
| `database_migration` | 存在数据库 schema 或迁移脚本 |
| `security_review` | 存在安全审查流程、安全相关代码或 Spring Security 配置 |
| `performance_budget` | 存在性能测试脚本、监控配置或性能基线文档 |
| `migration_plan` | 存在迁移规划文档、架构演进方案或系统过渡计划 |
| `runbook` | 存在运维流程或操作手册 |
| `deployment_manifest` | 存在部署配置（K8s、Docker 等） |
| `agent_skill` | 存在 Agent 技能定义文件 |
| `hook_policy` | 存在 CI/CD hook 配置 |

**规则**：仅当本地证据存在时才启用对应类型。不要因为插件提供了模板就启用。

### 步骤 2：复制 starter 模板到项目本地

扩展模板的真实来源包含分类层，例如 `templates/extended/contracts/api_contract/`、`templates/extended/agent/agent_skill/`。只为新采用的类型，或项目选定但缺失的模板，复制 starter 与 checklist。已有且有效的项目内路径不搬迁，不用上游目录整体覆盖。

```bash
# 示例：复制含分类层的 api_contract starter 与清单
cp plugins/artifact-chain-assistant/templates/extended/contracts/api_contract/starter.md \
   artifacts/templates/api_contract/starter.md

cp plugins/artifact-chain-assistant/templates/extended/contracts/api_contract/review-checklist.md \
   artifacts/templates/api_contract/review-checklist.md
```

**建议落点**（已有有效路径保持不动）：

```
artifacts/templates/api_contract/starter.md
artifacts/templates/api_contract/review-checklist.md
```

复制后在 `artifact-profiles/project.yaml` 绑定本地文件。下面只示例一种类型，不是完整配置：

```yaml
schema_version: 1
project:
  id: sample-project
  language: zh-CN
workflows:
  generate:
    api-contract:
      templates:
        - artifacts/templates/api_contract/starter.md
  review:
    api-contract:
      checklists:
        - artifacts/templates/api_contract/review-checklist.md
```

普通消费者绑定项目内文件，不把插件安装缓存路径写入 profile。`candidate_types[].template_available` 只表示上游 starter 存在。有显式 generate 映射时，`artifacts[].template.ready` 与 `path` 只反映映射中全部实际可用的模板；缺失、空映射、部分可用或非法路径不回退插件 starter。

### 步骤 3：定制模板内容

定制四个维度：

#### 3.1 定制路径

修改 `artifact-graph.config.yaml` 中的 `types.{type}.paths`，匹配项目实际目录结构：

```yaml
types:
  api_contract:
    paths: ["artifacts/contracts/api/**/*.md"]  # 按项目实际路径调整
```

#### 3.2 定制 ID 模式

修改 `artifact-graph.config.yaml` 中的 `idPatterns.{type}`，匹配项目命名规范：

```yaml
idPatterns:
  api_contract: "^API-\\d+$"  # 或 "{service}-API-{version}" 等项目特定模式
```

#### 3.3 定制 frontmatter

修改模板中的 frontmatter 字段，匹配项目需求：

```markdown
---
id: {API_ID}           # 替换为项目 ID 模式，如 API-001
title: {API 名称}       # 替换为实际标题
status: draft           # 按项目状态值调整
version: {v1}           # 替换为实际版本
base_url: {基础 URL}    # 替换为实际 URL
related_features: []    # 填入关联的功能特性 ID
---
```

**必须保留的字段**：`id`、`title`、`status`（artifact-graph 依赖这些字段索引）

**可扩展的字段**：根据制品类型添加项目特定字段（如 `api_contract` 的 `base_url`、`version`）

#### 3.4 定制 review checklist

修改审查清单，添加项目特定检查项：

```markdown
## 项目特定检查项

- [ ] 与项目 API 网关集成点一致
- [ ] 符合项目安全认证规范
- [ ] 响应时间满足 SLA 要求
```

**规则**：项目本地审查规则覆盖插件通用基线。

### 步骤 4：在 artifacts/README.md 中记录模板来源

在项目 `artifacts/README.md` 或模板目录的 README 中记录：

```markdown
## 扩展制品模板

本项目采用以下扩展制品类型，模板来自插件 `templates/extended/`，已定制为本地权威：

| 制品类型 | 模板路径 | 定制日期 | 定制摘要 |
|---------|---------|---------|---------|
| api_contract | artifacts/templates/api_contract.md | 2026-07-09 | 添加项目认证规范、调整 ID 模式 |
| runbook | artifacts/templates/runbook.md | 2026-07-09 | 添加告警关联规则 |
```

### 步骤 5：更新 config 并验证

```bash
# 1. 更新 config
# 编辑 artifact-graph.config.yaml 添加新类型

# 2. 验证图
artifact-graph validate --root . --warning-only

# 3. 刷新版本锁
artifact-graph version-lock refresh --all --format markdown

# 4. 审计版本锁
artifact-graph version-lock audit --root . --strict-missing-lock
```

### 步骤 6：核对实际结果

重读实际配置、模板和 profile。运行：

```bash
artifact-graph validate --root . --warning-only
artifact-graph version-lock refresh --all --format markdown
artifact-graph version-lock audit --root . --strict-missing-lock
```

已有定义变化用 `refresh --all`。不得运行 `artifact-graph version-lock bootstrap --force`。提交不是本指南的必做步骤。只有用户明确授权时，才由项目自己的发布流程处理；本指南不写入固定的 `git commit` 命令，也不把某次旧提交差异写成必须同步的步骤。

## 模板升级评审流程

当 `artifact-chain-assistant` 发布新版本且更新了 starter 模板时，已采用项目需要评审是否同步更新本地模板。

### 步骤 1：确定对比来源

上游发版只提供可选的对比来源，不强制更新项目。先确认旧采用来源是否还能核验，以及维护者本次选定的新来源。不要把某一次固定旧提交差异写成必做步骤。

### 步骤 2：对比本地模板

旧来源可核验时，比较原采用版本、当前本地、选定新版本。旧来源缺失时，只比较当前本地与选定新来源的可见差异，不虚称三方合并。

```bash
diff plugins/artifact-chain-assistant/templates/extended/contracts/api_contract/starter.md \
     artifacts/templates/api_contract/starter.md
```

**diff 关注点**：
- 插件新增的章节是否对项目有用
- 插件修改的审查点是否应纳入项目审查清单
- 插件删除的章节是否项目仍在使用

### 步骤 3：评审决策

| 情况 | 决策 |
|------|------|
| 插件新增了有用的章节 | 选择性合入本地模板 |
| 插件修改了通用审查点 | 评估是否提升项目审查标准 |
| 插件删除了项目使用的章节 | 保留本地版本，不跟随删除 |
| 插件模板与本地模板冲突 | 以本地模板为准，插件仅作参考 |

**核心原则**：项目本地模板是权威，插件 starter 是参考。不要盲目同步。

### 步骤 4：选择性合并

在授权写集内手动合并选定变更，不直接复制覆盖。

示例：项目本地模板已有自行增加的“恢复步骤”。选定上游新增“兼容影响”，且本次变更涉及兼容性时，把“兼容影响”及对应清单合入，同时保留“恢复步骤”。上游删除的章节，如果项目仍在使用，就保留。合入后重读实际文件，检查受影响正文并重新评审。身份迁移衔接 `artifact-chain-restructure`。不自动重写全部历史正文。

```bash
# 不要直接复制覆盖。编辑本地模板，保留“恢复步骤”，按需合入“兼容影响”。
```

### 步骤 5：更新审查清单

如果插件更新了 review-checklist.md，评估并选择性合入：

```bash
# 对比审查清单
diff plugins/artifact-chain-assistant/templates/extended/contracts/api_contract/review-checklist.md \
     artifacts/templates/api_contract-review-checklist.md
```

### 步骤 6：记录升级

在模板目录 README 中记录升级历史：

```markdown
## 升级历史

| 日期 | 插件版本 | 变更摘要 |
|------|---------|---------|
| 2026-07-09 | v1.2.0 | 合入插件新增的"安全认证"章节 |
```

## 常见问题

### Q: 可以直接引用插件 starter 模板吗？

**A: 不可以。** 插件 starter 是入门指导，不是权威。必须复制到本地定制后使用。

### Q: 插件更新时需要同步吗？

**A: 不需要自动同步。** 评审插件变更，选择性合入有用的部分。本地模板是权威。

### Q: 如何确认模板已定制完成？

**A: 检查清单**：
- [ ] 模板已复制到 `artifacts/templates/` 或等价位置
- [ ] frontmatter 字段符合项目 ID 模式
- [ ] 审查清单包含项目特定检查项
- [ ] `artifacts/README.md` 已记录模板来源
- [ ] `artifact-graph.config.yaml` 已添加类型定义
- [ ] `artifact-graph validate` 通过

### Q: 多个项目可以共享本地模板吗？

**A: 可以，但需各自定制。** 每个项目有独立的 `artifact-graph.config.yaml` 和本地模板，即使内容相似，也是各自维护的权威。

## 与三层权威模型的关系

本指南执行 D-ACA-07 定义的三层权威模型：

| 层级 | 对模板的职责 | 本指南动作 |
|------|------------|-----------|
| artifact-graph | 从 config 读取类型定义，索引制品 | 更新 config 的 types 和 idPatterns |
| artifact-chain-assistant | 提供 starter 模板作入门指导 | 复制 starter 到本地 |
| 目标项目 | 维护本地模板作权威 | 定制模板、记录来源、建立审查规则 |

## 相关文档

- [templates/extended/README.md](README.md) - Starter 模板目录
- [扩展制品目录](../../EXTENDED-ARTIFACT-CATALOG.md) - 类型分类、路径/ID 模式、生命周期规则
- [INSTALL.md](../../INSTALL.md) - 插件安装指南