create-yss-spec 1.0.0 → 1.1.0

package/README.md

@@ -1,6 +1,6 @@
 # create-yss-spec
 
-用于初始化 `yss-spec-project-template` 模板实例仓库的 npm CLI。
+用于初始化和同步 `yss-spec-project-template` 模板实例仓库的 npm CLI。
 
 ## 用法
 
@@ -24,6 +24,30 @@ npx create-yss-spec@latest
 - `--issue-tracker github|gitlab`
 - `--include-example-docs`
 - `--no-example-docs`
+- `sync` 子命令
+- 基于 `.yss-template.json` 的模板版本基线
+- 已有模板实例仓库的受管模板资产同步
+
+## 同步已有模板实例仓库
+
+当项目仓库已经由 `create-yss-spec` 初始化，并且根目录存在 `.yss-template.json` 时，可以执行：
+
+```bash
+npx create-yss-spec@latest sync
+```
+
+只预演，不真实写入：
+
+```bash
+npx create-yss-spec@latest sync --dry-run
+```
+
+当前同步能力的边界：
+
+- 只支持带模板元数据的模板实例仓库
+- 默认只更新未被本地修改的受管模板文件
+- 对本地已修改文件只提示和跳过，不自动覆盖
+- 对模板已删除文件只报告，不自动删除
 
 ## 开发验证
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-yss-spec",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Initialize a YSS spec project template repository",
   "files": [
     "bin",

package/src/cli.js

@@ -1,9 +1,13 @@
 const fs = require("node:fs");
 const path = require("node:path");
 const readline = require("node:readline/promises");
+const crypto = require("node:crypto");
 const { spawnSync } = require("node:child_process");
 
 const PACKAGE_ROOT = path.resolve(__dirname, "..");
+const PACKAGE_MANIFEST = JSON.parse(
+  fs.readFileSync(path.join(PACKAGE_ROOT, "package.json"), "utf8"),
+);
 const BUNDLED_TEMPLATE_ROOT = path.join(PACKAGE_ROOT, "template");
 const REPO_TEMPLATE_ROOT = path.resolve(PACKAGE_ROOT, "../..");
 const REPO_MANIFEST_PATH = path.join(REPO_TEMPLATE_ROOT, "template.manifest.json");
@@ -17,18 +21,33 @@ const TEMPLATE_ROOT = IS_REPO_DEVELOPMENT
 const TEMPLATE_MANIFEST_PATH = IS_REPO_DEVELOPMENT
   ? REPO_MANIFEST_PATH
   : BUNDLED_MANIFEST_PATH;
-const TEMPLATE_MANIFEST = JSON.parse(
-  fs.readFileSync(TEMPLATE_MANIFEST_PATH, "utf8"),
-);
+const TEMPLATE_MANIFEST_TEXT = fs.readFileSync(TEMPLATE_MANIFEST_PATH, "utf8");
+const TEMPLATE_MANIFEST = JSON.parse(TEMPLATE_MANIFEST_TEXT);
 const ROOT_EXCLUDED_ENTRIES = new Set(TEMPLATE_MANIFEST.excludeRootEntries);
 const ROOT_EXCLUDED_FILES = new Set(TEMPLATE_MANIFEST.excludeRootFiles);
 const EXCLUDED_RELATIVE_PATHS = new Set(TEMPLATE_MANIFEST.excludePaths);
 const RENDERED_RELATIVE_PATHS = new Set(TEMPLATE_MANIFEST.renderPaths);
 const EXAMPLE_DOC_PATHS = new Set(TEMPLATE_MANIFEST.exampleDocPaths);
+const TEMPLATE_METADATA_FILENAME = ".yss-template.json";
+const TEMPLATE_MANIFEST_VERSION = sha256(TEMPLATE_MANIFEST_TEXT);
 const REPO_TRACKED_STATE = IS_REPO_DEVELOPMENT
   ? loadRepoTrackedState(REPO_TEMPLATE_ROOT)
   : null;
 
+function sha256(value) {
+  return crypto.createHash("sha256").update(value).digest("hex");
+}
+
+function nowIsoString() {
+  return new Date().toISOString();
+}
+
+function getTemplateSource() {
+  return IS_REPO_DEVELOPMENT
+    ? "repo-development"
+    : `npm:${PACKAGE_MANIFEST.name}@${PACKAGE_MANIFEST.version}`;
+}
+
 function loadRepoTrackedState(repoRoot) {
   const result = spawnSync("git", ["ls-files"], {
     cwd: repoRoot,
@@ -259,6 +278,49 @@ function renderTemplateFile(relativePath, content, variables) {
   return content;
 }
 
+function collectManagedFileHashes(operations) {
+  const managedFiles = {};
+
+  for (const operation of operations) {
+    if (operation.type !== "copy" && operation.type !== "render") {
+      continue;
+    }
+
+    managedFiles[operation.relativePath] = {
+      type: operation.type,
+      contentHash: sha256(fs.readFileSync(operation.targetPath)),
+    };
+  }
+
+  return managedFiles;
+}
+
+function writeTemplateMetadata(targetDir, metadata) {
+  const metadataPath = path.join(targetDir, TEMPLATE_METADATA_FILENAME);
+  fs.writeFileSync(metadataPath, `${JSON.stringify(metadata, null, 2)}\n`, "utf8");
+}
+
+function buildTemplateMetadata(targetDir, variables, operations) {
+  const timestamp = nowIsoString();
+
+  return {
+    templateName: PACKAGE_MANIFEST.name,
+    templateVersion: PACKAGE_MANIFEST.version,
+    templateSource: getTemplateSource(),
+    initializedAt: timestamp,
+    lastSyncedAt: timestamp,
+    managedFilesManifestVersion: TEMPLATE_MANIFEST_VERSION,
+    variables: {
+      projectName: variables.projectName,
+      businessDomain: variables.businessDomain,
+      teamSize: variables.teamSize,
+      issueTracker: variables.issueTracker,
+      includeExampleDocs: variables.includeExampleDocs,
+    },
+    managedFiles: collectManagedFileHashes(operations),
+  };
+}
+
 function buildCopyPlan(sourceDir, targetDir, variables, relativeDir = "") {
   const operations = [];
   const entries = fs.readdirSync(sourceDir, { withFileTypes: true });
@@ -405,7 +467,245 @@ function initializeGitRepository(targetDir) {
   }
 }
 
-async function runCli(argv = []) {
+function loadTemplateMetadata(targetDir) {
+  const metadataPath = path.join(targetDir, TEMPLATE_METADATA_FILENAME);
+
+  if (!fs.existsSync(metadataPath)) {
+    throw new Error(
+      `当前目录不是受支持的模板实例仓库，缺少模板元数据文件 ${TEMPLATE_METADATA_FILENAME}`,
+    );
+  }
+
+  return {
+    metadataPath,
+    metadata: JSON.parse(fs.readFileSync(metadataPath, "utf8")),
+  };
+}
+
+function buildSyncVariables(metadata) {
+  const variables = metadata.variables || {};
+
+  return {
+    projectName: variables.projectName,
+    businessDomain: variables.businessDomain,
+    teamSize: variables.teamSize || "待补充",
+    issueTracker: variables.issueTracker || "github",
+    includeExampleDocs:
+      variables.includeExampleDocs === undefined
+        ? true
+        : Boolean(variables.includeExampleDocs),
+  };
+}
+
+function buildDesiredManagedOperations(targetDir, metadata) {
+  const variables = buildSyncVariables(metadata);
+
+  return buildCopyPlan(TEMPLATE_ROOT, targetDir, variables).filter(
+    (operation) => operation.type === "copy" || operation.type === "render",
+  );
+}
+
+function buildDesiredManagedFile(operation, metadata) {
+  const variables = buildSyncVariables(metadata);
+
+  if (operation.type === "render") {
+    const renderedContent = renderTemplateFile(
+      operation.relativePath,
+      fs.readFileSync(operation.sourcePath, "utf8"),
+      variables,
+    );
+
+    return {
+      ...operation,
+      desiredContent: renderedContent,
+      desiredHash: sha256(renderedContent),
+    };
+  }
+
+  return {
+    ...operation,
+    desiredHash: sha256(fs.readFileSync(operation.sourcePath)),
+  };
+}
+
+function classifySyncPlan(targetDir, metadata) {
+  const managedFiles = metadata.managedFiles || {};
+  const desiredOperations = buildDesiredManagedOperations(targetDir, metadata).map(
+    (operation) => buildDesiredManagedFile(operation, metadata),
+  );
+  const desiredPathSet = new Set(
+    desiredOperations.map((operation) => operation.relativePath),
+  );
+
+  const updated = [];
+  const added = [];
+  const unchanged = [];
+  const skipped = [];
+
+  for (const operation of desiredOperations) {
+    const existingRecord = managedFiles[operation.relativePath];
+    const existsOnDisk = fs.existsSync(operation.targetPath);
+
+    if (!existingRecord) {
+      if (!existsOnDisk) {
+        added.push(operation);
+        continue;
+      }
+
+      const currentHash = sha256(fs.readFileSync(operation.targetPath));
+      if (currentHash === operation.desiredHash) {
+        unchanged.push(operation);
+      } else {
+        skipped.push({
+          ...operation,
+          reason: "文件已存在，但不在受管模板文件基线中",
+        });
+      }
+      continue;
+    }
+
+    if (!existsOnDisk) {
+      added.push(operation);
+      continue;
+    }
+
+    const currentHash = sha256(fs.readFileSync(operation.targetPath));
+    if (currentHash !== existingRecord.contentHash) {
+      skipped.push({
+        ...operation,
+        reason: "检测到本地已修改的受管文件",
+      });
+      continue;
+    }
+
+    if (currentHash === operation.desiredHash) {
+      unchanged.push(operation);
+      continue;
+    }
+
+    updated.push(operation);
+  }
+
+  const removed = Object.keys(managedFiles).filter(
+    (relativePath) => !desiredPathSet.has(relativePath),
+  );
+
+  return {
+    updated,
+    added,
+    unchanged,
+    skipped,
+    removed,
+    desiredOperations,
+  };
+}
+
+function printSyncDryRun(targetDir, metadata, syncPlan) {
+  console.log("sync dry-run 预览");
+  console.log(`目标目录：${targetDir}`);
+  console.log(
+    `模板版本：${metadata.templateVersion || "unknown"} -> ${PACKAGE_MANIFEST.version}`,
+  );
+
+  for (const operation of syncPlan.updated) {
+    console.log(`update: ${operation.relativePath}`);
+  }
+
+  for (const operation of syncPlan.added) {
+    console.log(`add: ${operation.relativePath}`);
+  }
+
+  for (const operation of syncPlan.skipped) {
+    console.log(`skip: ${operation.relativePath} (${operation.reason})`);
+  }
+
+  for (const relativePath of syncPlan.removed) {
+    console.log(`remove-report: ${relativePath}`);
+  }
+}
+
+function applyManagedFileOperation(operation) {
+  fs.mkdirSync(path.dirname(operation.targetPath), { recursive: true });
+
+  if (operation.type === "render") {
+    fs.writeFileSync(operation.targetPath, operation.desiredContent, "utf8");
+    return;
+  }
+
+  fs.copyFileSync(operation.sourcePath, operation.targetPath);
+}
+
+function syncTemplateInstance(targetDir, metadata, dryRun) {
+  const syncPlan = classifySyncPlan(targetDir, metadata);
+
+  if (dryRun) {
+    printSyncDryRun(targetDir, metadata, syncPlan);
+    return;
+  }
+
+  for (const operation of [...syncPlan.updated, ...syncPlan.added]) {
+    applyManagedFileOperation(operation);
+  }
+
+  const nextManagedFiles = { ...(metadata.managedFiles || {}) };
+  for (const operation of syncPlan.desiredOperations) {
+    if (!fs.existsSync(operation.targetPath)) {
+      continue;
+    }
+
+    const currentHash = sha256(fs.readFileSync(operation.targetPath));
+    if (currentHash !== operation.desiredHash) {
+      continue;
+    }
+
+    nextManagedFiles[operation.relativePath] = {
+      type: operation.type,
+      contentHash: operation.desiredHash,
+    };
+  }
+
+  const nextMetadata = {
+    ...metadata,
+    templateName: PACKAGE_MANIFEST.name,
+    templateVersion: PACKAGE_MANIFEST.version,
+    templateSource: getTemplateSource(),
+    lastSyncedAt: nowIsoString(),
+    managedFilesManifestVersion: TEMPLATE_MANIFEST_VERSION,
+    managedFiles: nextManagedFiles,
+  };
+
+  writeTemplateMetadata(targetDir, nextMetadata);
+
+  console.log("同步完成");
+  console.log(
+    `模板版本：${metadata.templateVersion || "unknown"} -> ${PACKAGE_MANIFEST.version}`,
+  );
+  console.log(`自动更新：${syncPlan.updated.length}`);
+  console.log(`新增文件：${syncPlan.added.length}`);
+  console.log(`跳过文件：${syncPlan.skipped.length}`);
+  console.log(`删除差异：${syncPlan.removed.length}`);
+
+  if (syncPlan.skipped.length > 0) {
+    console.log("本地已修改，已跳过：");
+    for (const operation of syncPlan.skipped) {
+      console.log(`- ${operation.relativePath}: ${operation.reason}`);
+    }
+  }
+
+  if (syncPlan.removed.length > 0) {
+    console.log("模板已移除但未自动删除：");
+    for (const relativePath of syncPlan.removed) {
+      console.log(`- ${relativePath}`);
+    }
+  }
+
+  console.log("下一步建议：");
+  console.log("1. 运行 git diff 或 git status 检查同步结果");
+  console.log("2. 人工处理被跳过文件和删除差异（如有）");
+  console.log("3. 确认无误后提交本次模板同步结果");
+}
+
+async function runInit(argv = []) {
   const promptedOptions = await promptForMissingOptions(parseArgs(argv));
   assertRequiredOptions(promptedOptions);
 
@@ -421,6 +721,10 @@ async function runCli(argv = []) {
 
   prepareTargetDir(targetDir, targetState);
   executePlan(operations, promptedOptions);
+  writeTemplateMetadata(
+    targetDir,
+    buildTemplateMetadata(targetDir, promptedOptions, operations),
+  );
 
   if (promptedOptions.gitInit) {
     initializeGitRepository(targetDir);
@@ -438,6 +742,22 @@ async function runCli(argv = []) {
   console.log("3. 检查 AGENTS.md、README 和 docs 目录是否符合预期");
 }
 
+function runSync(argv = []) {
+  const options = parseArgs(argv);
+  const targetDir = normalizeTargetDir(options.targetDir || ".");
+  const { metadata } = loadTemplateMetadata(targetDir);
+  syncTemplateInstance(targetDir, metadata, Boolean(options.dryRun));
+}
+
+async function runCli(argv = []) {
+  if (argv[0] === "sync") {
+    runSync(argv.slice(1));
+    return;
+  }
+
+  await runInit(argv);
+}
+
 module.exports = {
   runCli,
 };

package/template/CONTEXT.md

@@ -22,5 +22,8 @@
 | 模板源仓库 | 承载 `yss-spec-project-template` 权威模板内容及其演进规则的仓库。 | 不等同于实例化后的具体项目仓库。 |
 | 模板实例仓库 | 由模板初始化后生成、面向某个具体项目使用的仓库。 | 不要与模板源仓库混用。 |
 | 模板初始化 CLI | 用于把模板源仓库实例化为新项目初始仓库的命令行工具。 | 不等同于业务运行时代码脚手架。 |
+| 模板同步 | 将已有模板实例仓库与某个更新后的模板快照进行对齐的过程。 | 不等同于重新初始化；通常要考虑本地改动保留、冲突提示和可回滚性。 |
+| 模板快照版本 | 某次发布时模板内容的可识别版本标识，通常对应 npm 包版本、Git tag 或 commit。 | 需要用于判断实例仓库当前基线和目标同步版本。 |
+| 受管模板文件 | 被 CLI 明确纳入同步策略的文件或目录集合。 | 只有受管文件才应被自动更新、跳过或冲突提示。 |
 
 只有在计划、分诊、调试或架构讨论中明确沉淀出稳定语言时，才新增术语。

package/template/docs/discovery/yss-spec-cli-template-sync-discovery.md

@@ -0,0 +1,265 @@
+---
+pipeline: yss-spec-cli-template-sync
+stage: discovery
+status: draft
+owner: ai
+---
+
+# yss-spec 模板同步 CLI Discovery 收敛文档
+
+> 目标：围绕“CLI 支持持续同步模板演进到已有模板实例仓库”完成需求澄清，输出可直接进入 `to-prd` 的上游结论。
+
+## 1. 先澄清术语
+
+本轮最容易混淆的是“同步”。
+
+- 不是“新项目初始化”。
+- 不是“把 GitHub 最新代码重新发布到 npm”。
+- 本文默认的“模板同步”是：
+  - 让一个已经由 `yss-spec-project-template` 初始化出来的“模板实例仓库”，在后续某个时点对齐到更新后的模板快照版本。
+
+如果后续用户真正想要的是“只要重新发 npm 包即可”，那属于模板发布流程，不属于这里的“实例仓库同步”能力。
+
+## 2. 输入材料
+
+| 材料 | 路径 / 链接 | 状态 | 备注 |
+|------|-------------|------|------|
+| 模板初始化现状 | `packages/create-yss-spec/` | 已确认 | 当前 CLI 已支持初始化，不支持已有仓库升级 |
+| 上游初始化澄清 | `docs/discovery/yss-spec-cli-init-discovery.md` | 已确认 | 已定义模板源仓库 / 模板实例仓库 / 初始化 CLI |
+| 上游初始化 PRD | `docs/requirements/yss-spec-cli-init-prd.md` | 已确认 | 当前 MVP 明确排除了“更新已有模板实例仓库到最新模板版本” |
+| 当前会话用户指令 | 当前会话 | 已确认 | 用户希望 CLI 支持持续同步模板演进 |
+
+## 3. 目标用户与真实场景
+
+| 用户 / 角色 | 真实场景 | 当前痛点 | 影响范围 |
+|-------------|----------|----------|----------|
+| 模板维护者 | 模板源仓库持续新增流程、文档、脚本、规范后，希望已有项目能跟进 | 只能人工比对目录和文件，容易漏同步、误覆盖 | 模板演进效率、推广成本 |
+| 项目初始化负责人 / Tech Lead | 已用 CLI 初始化过项目，后续希望补齐模板新增资产 | 不知道哪些文件该更新、哪些本地改动不能碰 | 项目仓库一致性、升级风险 |
+| 研发管理使用者 | 希望项目仓库不断跟进新的流程基线 | 模板升级没有标准路径，导致每个项目分叉越来越大 | 过程规范统一性 |
+
+## 4. 核心问题
+
+- 当前 CLI 只解决“第一次初始化”，没有解决“模板演进后如何让既有实例仓库跟进”。
+- 模板实例仓库一旦落地，就会出现本地修改；后续同步不是简单覆盖，而是“受管资产升级 + 本地变更保护 + 冲突可见化”。
+- 如果没有模板版本基线，CLI 无法判断：
+  - 当前实例仓库是从哪个模板快照创建的
+  - 这次准备同步到哪个目标版本
+  - 哪些文件是模板新增、模板修改、用户本地修改
+
+## 5. 关键分歧点
+
+### 5.1 “同步”到底同步什么
+
+推荐默认只同步以下“研发管理模板资产”：
+
+- `docs/templates/`
+- `docs/process/`
+- `docs/agents/`
+- `docs/user-guide/` 中明确标记为模板资产的部分
+- `AGENTS.md`
+- `CONTEXT.md` 中模板占位初始化后的公共段落
+- 辅助脚本（如 `scripts/verify-template`、`scripts/gitworks`）
+
+不建议默认自动同步：
+
+- 项目团队已经开始填写的 PRD 正文
+- 项目自己的 OpenAPI 草稿
+- 已创建的 issue 内容
+- 项目特有 README 大段业务说明
+- 用户新建的非模板文件
+
+结论：模板同步应是“受管模板资产同步”，不是“整个仓库重置”。
+
+### 5.2 命令形态是否继续沿用 `create-*`
+
+这里有一个真实 trade-off：
+
+- 如果继续沿用 `create-yss-spec`
+  - 优点：沿用现有 npm 包，最短路径可做 `npx create-yss-spec@latest sync`
+  - 风险：`create-*` 从语义上更像一次性初始化，不像长期运维命令
+- 如果升级为稳定 CLI（如 `yss-spec init` / `yss-spec sync`）
+  - 优点：命令语义更完整，更适合长期维护
+  - 风险：需要额外处理包迁移、别名兼容、文档迁移
+
+建议：
+
+- MVP 先不拆包，仍在当前仓库和当前 npm 包中实现
+- 命令层采用过渡方案：
+  - `npx create-yss-spec@latest sync`
+- 中期再评估稳定命令：
+  - `yss-spec init`
+  - `yss-spec sync`
+
+### 5.3 同步源来自哪里
+
+候选有三个：
+
+1. 当前执行的 npm 包内置模板快照
+2. GitHub 仓库远程拉取最新模板
+3. 独立模板清单 / 模板版本服务
+
+建议 MVP 选 1：
+
+- 以当前执行的 npm 包版本作为“目标模板快照版本”
+- 好处是发布、复现、回滚最简单
+- 用户执行 `npx create-yss-spec@latest sync` 时，自然拿到最新已发布模板
+
+不建议 MVP 直接读 GitHub 最新默认分支：
+
+- 会让“源码最新”与“已验证可发布模板”混在一起
+- 难以复现问题
+- 不利于回滚
+
+## 6. 推荐的 MVP 边界
+
+| 能力 | 是否进入 MVP | 理由 | 成功信号 |
+|------|---------------|------|----------|
+| 支持在已有模板实例仓库中执行 `sync` | 是 | 这是本轮核心价值 | 用户能标准化升级模板资产 |
+| 为实例仓库写入模板元数据文件 | 是 | 没有基线就无法判断同步关系 | CLI 能识别当前模板版本 |
+| 基于受管文件清单执行同步 | 是 | 避免把整个仓库当成可覆盖对象 | 自动更新范围可控 |
+| 默认只更新“未被本地修改”的受管文件 | 是 | 保护项目局部自定义 | 无意外覆盖 |
+| 对本地已改动的受管文件给出冲突 / 跳过报告 | 是 | 同步必须 fail-closed | 用户知道哪些地方需要人工处理 |
+| 支持 `--dry-run` 预览同步计划 | 是 | 同步比初始化更需要预演 | 用户先看变化再执行 |
+| 支持 `--from` / `--to` 版本识别或展示 | 是 | 便于理解本次升级跨度 | 输出中能看到版本变更 |
+| 支持 `--force` 强制覆盖冲突文件 | 否 | 风险过高，容易伤害项目自定义 | 先人工确认冲突处理 |
+| 支持自动三方合并 | 否 | 实现复杂，且容易产出错误合并 | 后续版本再评估 |
+| 支持同步项目已填写内容（如 PRD 正文） | 否 | 这些内容已脱离模板资产范畴 | 保持边界清晰 |
+| 支持直接从 GitHub 拉取未发布模板 | 否 | 破坏可复现性与发布门禁 | 以后仅作高级模式再评估 |
+
+## 7. 非目标范围
+
+| 非目标 | 排除原因 | 后续观察条件 |
+|--------|----------|--------------|
+| 整仓库覆盖式升级 | 风险极高，会破坏项目本地资产 | 除非未来引入可靠三方合并和备份机制 |
+| 自动解决所有冲突 | 很难保证正确性 | 后续若只针对少量结构化文件可再局部自动化 |
+| 同步项目自定义内容 | 已超出模板资产边界 | 仅处理明确受管文件 |
+| 在线拉取 GitHub 最新源码直接升级 | 不利于发布治理 | 若未来内部需要 canary 模式再评估 |
+| 多模板、多分支、多环境升级平台 | 会显著抬高复杂度 | 等单模板同步路径稳定后再扩展 |
+
+## 8. 推荐的最小产品流
+
+1. 用户在模板实例仓库根目录执行 `npx create-yss-spec@latest sync`
+2. CLI 检查当前目录是否存在模板元数据文件，例如 `.yss-template.json`
+3. CLI 读取当前实例仓库记录的 `currentTemplateVersion`
+4. CLI 以当前 npm 包内模板作为 `targetTemplateVersion`
+5. CLI 计算受管文件差异，分类为：
+   - `unchanged-managed`：本地未改，可自动更新
+   - `modified-managed`：本地已改，需跳过并提示
+   - `new-managed`：模板新增，可安全落盘
+   - `removed-managed`：模板已删除，MVP 先只提示，不自动删
+   - `unmanaged`：不在同步范围内，忽略
+6. 若是 `--dry-run`，只输出计划
+7. 若正式执行，则：
+   - 自动写入 `unchanged-managed`
+   - 新增 `new-managed`
+   - 跳过 `modified-managed`
+   - 报告 `removed-managed`
+8. CLI 输出同步摘要和需人工处理的文件清单
+9. CLI 更新模板元数据中的当前版本
+
+## 9. 模板元数据建议
+
+建议引入一个实例仓库级元数据文件，例如：
+
+- `.yss-template.json`
+
+建议记录：
+
+- `templateName`
+- `templateVersion`
+- `templateSource`
+- `initializedAt`
+- `lastSyncedAt`
+- `managedFilesManifestVersion`
+- 初始化时采集的核心渲染变量摘要
+
+这个文件的价值是：
+
+- 让 CLI 能判断“这个仓库是不是由本模板初始化出来的”
+- 让 CLI 知道“当前仓库上次同步到哪个模板版本”
+- 为后续同步报告、回滚和支持问题定位提供依据
+
+## 10. 风险与待澄清
+
+| 风险 / 问题 | 影响 | 建议处理方式 | 截止点 |
+|-------------|------|--------------|--------|
+| 受管文件范围过大 | 误覆盖项目自定义 | MVP 先只纳入公共模板资产 | PRD 前 |
+| 没有模板元数据基线 | 无法可靠识别同步关系 | 把元数据文件纳入 MVP | PRD 前 |
+| 模板删除策略不清 | 可能误删用户文件 | MVP 对删除只提示不自动执行 | PRD 前 |
+| `create-*` 命令形态长期不适合 sync | UX 心智不清 | PRD 中明确“过渡方案 + 演进路线” | PRD 前 |
+| 老项目没有元数据文件 | 无法直接升级 | 需要设计 onboarding / attach 模式 | PRD 前 |
+
+## 11. 对“老项目”的特殊判断
+
+这是一个必须单独说明的边界：
+
+- 对于已经由早期 CLI 初始化、但还没有 `.yss-template.json` 的项目
+- CLI 不能直接假设它安全可同步
+
+建议：
+
+- MVP 先只支持“带模板元数据的实例仓库”
+- 对老项目提示：
+  - 当前仓库缺少模板基线
+  - 需要先执行显式 `attach` / `adopt` 流程，或人工确认后再纳入同步
+
+这类“老项目补挂模板基线”的能力，不建议直接塞进第一版同步主路径。
+
+## 12. 成功标准
+
+| 指标 / 结果 | 目标 | 验证方式 |
+|-------------|------|----------|
+| 同步安全性 | 默认不覆盖本地已改文件 | 行为测试 + 冲突场景测试 |
+| 升级可见性 | 用户能在执行前看到同步计划 | `--dry-run` 验证 |
+| 同步范围可控 | 仅受管模板资产被自动处理 | 目录快照校验 |
+| 版本可追踪 | 每次同步前后都有模板版本标识 | 元数据文件校验 |
+| 可回滚性 | 用户至少可通过 Git 看见同步改动 | CLI 输出建议 + 验证文档 |
+
+## 13. 实现位置建议
+
+- 建议继续放在当前仓库中实现，不另起独立仓库。
+- 原因：
+  - 模板同步比模板初始化更依赖模板权威内容
+  - 模板、受管清单、同步规则分仓后更容易漂移
+  - 当前仓库本身就是模板源仓库，最适合作为同步规则的单一事实源
+
+目录建议：
+
+- `packages/create-yss-spec/`
+  - 新增 `sync` 子命令实现
+  - 新增同步相关测试
+- `template.manifest.json`
+  - 从“初始化复制 / 渲染清单”演进为“初始化 + 同步共用清单”
+- 可新增：
+  - `docs/implementation/yss-spec-cli-template-sync-routing.md`
+  - `docs/requirements/yss-spec-cli-template-sync-prd.md`
+
+## 14. 推荐结论
+
+### 14.1 推荐的产品定义
+
+- 把这件事定义为：
+  - “模板实例仓库的受管模板资产同步”
+- 不要定义为：
+  - “重新生成整个仓库”
+  - “从 GitHub 拉最新代码强制覆盖”
+
+### 14.2 推荐的命令方向
+
+- MVP：`npx create-yss-spec@latest sync`
+- 中期：演进到 `yss-spec sync`
+
+### 14.3 推荐的同步策略
+
+- 以 npm 已发布版本为同步源
+- 以模板元数据作为实例仓库同步基线
+- 以受管文件清单控制同步范围
+- 默认只更新未被本地修改的受管文件
+- 对删除与冲突先提示，不自动处理
+
+## 15. 下一步门禁
+
+- 结论：Approved with clarifications
+- 下一步：`to-prd`
+- 进入 PRD 前必须明确的唯一高风险问题：
+  - MVP 是否只支持“已有模板元数据的项目”，还是必须兼容历史老项目直接升级

package/template/docs/requirements/issues/yss-spec-cli-template-sync-slice-01-main-path.md

@@ -0,0 +1,69 @@
+# 垂直切片 Issue：模板元数据门禁与 sync 成功主路径
+
+## 同步信息
+
+- 平台：GitHub
+- Issue：[#19](https://github.com/iloveZzz/yss-spec-project-template/issues/19)
+- 同步时间：2026-07-05 20:47:53 +0800
+
+## 父级
+
+- [#18 PRD: yss-spec 模板同步 CLI](https://github.com/iloveZzz/yss-spec-project-template/issues/18)
+
+## 要构建什么
+
+交付模板同步 CLI 的第一条完整主路径：在一个已经由 `create-yss-spec` 初始化、且带有模板元数据的模板实例仓库中，用户可以执行 `npx create-yss-spec@latest sync`，CLI 能识别当前模板快照版本与目标模板快照版本，加载受管模板文件清单，自动更新未被本地修改的受管文件，补齐模板新增的受管文件，并在成功后回写模板元数据。
+
+本切片只覆盖带模板元数据项目的成功路径，不处理历史老项目接管，也不处理本地已修改受管文件的冲突保护细节。它必须是一个可单独验证的纵向路径：用户通过公开 CLI 接口执行同步，看到版本信息、落盘结果和更新后的模板元数据。
+
+## 覆盖的用户故事
+
+- 2, 3, 8, 9, 10, 11, 12, 21, 23
+
+## OpenAPI 影响
+
+- [x] 无
+- [ ] 基于冻结 OpenAPI：`docs/api/specs/<feature>.yaml`
+
+受影响端点：
+
+| 方法 | 路径 | 变更 |
+|---|---|---|
+| 无 | 无 | 无 |
+
+## 验收标准
+
+- [ ] 在带模板元数据的模板实例仓库根目录执行 `sync` 时，CLI 能识别当前模板版本和目标模板版本，并启动同步流程
+- [ ] CLI 能基于受管模板文件清单自动更新未修改的受管文件，并补齐模板新增的受管文件
+- [ ] 同步成功后，模板元数据会更新到新的模板版本并记录最近同步信息
+- [ ] 以上成功主路径具备可重复执行的 CLI 行为测试覆盖
+
+## 测试 Seam
+
+- 主要公共接口：CLI 端到端执行入口
+- 必需测试：
+  - [x] 行为 / 领域测试
+  - [ ] API / 契约测试
+  - [ ] UI / 组件测试
+  - [x] E2E 测试
+
+## 阻塞关系
+
+- 无，可立即开始
+
+## AI / 人工审查点
+
+- [x] 未触碰安全红线
+- [ ] 支付逻辑：`TODO-HUMAN-REVIEW`
+- [ ] 数据库迁移：`TODO-HUMAN-REVIEW`
+- [ ] 认证 / 授权：`TODO-HUMAN-REVIEW`
+- [ ] 加密算法：禁止实现
+- [ ] 原生 SQL：仅生成草案
+- [ ] 公共基础库 API：仅生成草案
+
+## 完成定义
+
+- [ ] sync 主路径实现完成
+- [ ] 模板元数据读取与回写行为稳定
+- [ ] 受管文件自动更新与新增补齐行为可被验证
+- [ ] 已移除临时调试 / 原型代码

package/template/docs/requirements/issues/yss-spec-cli-template-sync-slice-02-safety-controls.md

@@ -0,0 +1,69 @@
+# 垂直切片 Issue：dry-run 预演与本地改动保护
+
+## 同步信息
+
+- 平台：GitHub
+- Issue：[#21](https://github.com/iloveZzz/yss-spec-project-template/issues/21)
+- 同步时间：2026-07-05 20:47:53 +0800
+
+## 父级
+
+- [#18 PRD: yss-spec 模板同步 CLI](https://github.com/iloveZzz/yss-spec-project-template/issues/18)
+
+## 要构建什么
+
+在模板同步主路径已打通的前提下，为 `sync` 命令补齐默认安全的执行控制：支持 `--dry-run` 预演同步计划，并对本地已修改的受管文件采用 fail-closed 的跳过与提示策略。
+
+本切片必须让用户在真正落盘前看到本次同步会处理哪些文件、跳过哪些文件、原因是什么；当受管文件已经在实例仓库中被本地修改时，CLI 不自动覆盖，而是明确报告冲突并继续保护其余安全可更新的文件。
+
+## 覆盖的用户故事
+
+- 13, 14, 15, 17, 18, 28
+
+## OpenAPI 影响
+
+- [x] 无
+- [ ] 基于冻结 OpenAPI：`docs/api/specs/<feature>.yaml`
+
+受影响端点：
+
+| 方法 | 路径 | 变更 |
+|---|---|---|
+| 无 | 无 | 无 |
+
+## 验收标准
+
+- [ ] 当用户执行 `sync --dry-run` 时，CLI 只展示同步计划，不进行真实写入，也不更新模板元数据
+- [ ] 当受管文件存在本地修改时，CLI 会将其识别为需跳过项，并给出可理解的原因提示
+- [ ] 正式执行同步时，CLI 不会自动覆盖本地已修改的受管文件，但仍会继续处理安全可更新的部分
+- [ ] 上述预演与保护路径具备可重复执行的 CLI 行为测试覆盖
+
+## 测试 Seam
+
+- 主要公共接口：CLI 端到端执行入口
+- 必需测试：
+  - [x] 行为 / 领域测试
+  - [ ] API / 契约测试
+  - [ ] UI / 组件测试
+  - [x] E2E 测试
+
+## 阻塞关系
+
+- [#19 Slice 1: 模板元数据门禁与 sync 成功主路径](https://github.com/iloveZzz/yss-spec-project-template/issues/19)
+
+## AI / 人工审查点
+
+- [x] 未触碰安全红线
+- [ ] 支付逻辑：`TODO-HUMAN-REVIEW`
+- [ ] 数据库迁移：`TODO-HUMAN-REVIEW`
+- [ ] 认证 / 授权：`TODO-HUMAN-REVIEW`
+- [ ] 加密算法：禁止实现
+- [ ] 原生 SQL：仅生成草案
+- [ ] 公共基础库 API：仅生成草案
+
+## 完成定义
+
+- [ ] `--dry-run` 预演行为实现完成
+- [ ] 本地已修改受管文件的跳过与提示逻辑实现完成
+- [ ] 安全路径均有自动化验证
+- [ ] 已移除临时调试 / 原型代码

package/template/docs/requirements/issues/yss-spec-cli-template-sync-slice-03-delivery-verification.md

@@ -0,0 +1,69 @@
+# 垂直切片 Issue：删除差异报告与同步交付收口
+
+## 同步信息
+
+- 平台：GitHub
+- Issue：[#20](https://github.com/iloveZzz/yss-spec-project-template/issues/20)
+- 同步时间：2026-07-05 20:47:53 +0800
+
+## 父级
+
+- [#18 PRD: yss-spec 模板同步 CLI](https://github.com/iloveZzz/yss-spec-project-template/issues/18)
+
+## 要构建什么
+
+补齐模板同步 CLI 的最后一公里交付能力：当目标模板版本中移除了某些受管文件时，CLI 能报告这些删除差异而不自动删除；同步完成后输出清晰的结果摘要、人工后续动作建议和 Git 检查提示，并将这套行为沉淀到自动化验证与使用说明中。
+
+本切片确保模板同步不仅能“执行”，还能被团队安全理解和推广使用。它聚焦的是删除差异可见化、同步结果可审查、用户下一步可行动。
+
+## 覆盖的用户故事
+
+- 7, 16, 19, 20, 24, 29, 30
+
+## OpenAPI 影响
+
+- [x] 无
+- [ ] 基于冻结 OpenAPI：`docs/api/specs/<feature>.yaml`
+
+受影响端点：
+
+| 方法 | 路径 | 变更 |
+|---|---|---|
+| 无 | 无 | 无 |
+
+## 验收标准
+
+- [ ] 当模板新版本移除受管文件时，CLI 会将这些文件报告为删除差异，但 MVP 中不会自动删除它们
+- [ ] 同步完成后，CLI 输出包含版本变化、更新数量、跳过数量、删除差异数量以及建议的 Git 后续动作
+- [ ] 使用手册或等价用户说明已补充 `sync` 的执行方式、输出解释和限制边界
+- [ ] 删除差异报告与交付收口路径具备可重复执行的 CLI 行为测试或文档验证覆盖
+
+## 测试 Seam
+
+- 主要公共接口：CLI 端到端执行入口
+- 必需测试：
+  - [x] 行为 / 领域测试
+  - [ ] API / 契约测试
+  - [ ] UI / 组件测试
+  - [x] E2E 测试
+
+## 阻塞关系
+
+- [#19 Slice 1: 模板元数据门禁与 sync 成功主路径](https://github.com/iloveZzz/yss-spec-project-template/issues/19)
+
+## AI / 人工审查点
+
+- [x] 未触碰安全红线
+- [ ] 支付逻辑：`TODO-HUMAN-REVIEW`
+- [ ] 数据库迁移：`TODO-HUMAN-REVIEW`
+- [ ] 认证 / 授权：`TODO-HUMAN-REVIEW`
+- [ ] 加密算法：禁止实现
+- [ ] 原生 SQL：仅生成草案
+- [ ] 公共基础库 API：仅生成草案
+
+## 完成定义
+
+- [ ] 删除差异报告能力实现完成
+- [ ] 同步结果摘要与 Git 后续提示实现完成
+- [ ] 使用手册 / 等价说明完成更新
+- [ ] 已移除临时调试 / 原型代码

package/template/docs/requirements/yss-spec-cli-template-sync-prd.md

@@ -0,0 +1,109 @@
+---
+pipeline: yss-spec-cli-template-sync
+stage: open
+status: draft
+owner: ai
+tracker_platform: github
+tracker_issue_number: 18
+tracker_issue_url: https://github.com/iloveZzz/yss-spec-project-template/issues/18
+tracker_sync_status: published
+tracker_synced_at: 2026-07-05 19:02:00 +0800
+source_discovery: docs/discovery/yss-spec-cli-template-sync-discovery.md
+---
+
+# 产品需求文档：yss-spec 模板同步 CLI
+
+## Problem Statement
+
+当前 `create-yss-spec` 已经能把 `yss-spec-project-template` 初始化为新的模板实例仓库，但模板源仓库后续持续演进时，已有实例仓库缺少标准化的升级路径。
+
+对于模板维护者、项目初始化负责人和 Tech Lead 来说，问题不在“如何再初始化一次”，而在“如何把已有项目安全地同步到新的模板快照版本”。一旦实例仓库已经开始被真实项目使用，就会存在本地修改、项目自定义文档和新增文件。此时如果没有模板基线、受管文件范围和冲突保护机制，升级动作就会退化为人工 diff、手工拷贝和经验判断，容易漏同步、误覆盖，最终导致模板实例仓库不断分叉。
+
+## Solution
+
+在现有 npm 包 `create-yss-spec` 中增加模板同步能力，使用户能够在已有模板实例仓库根目录执行 `npx create-yss-spec@latest sync`，以“受管模板资产同步”的方式，把仓库对齐到新的模板快照版本。
+
+MVP 采用以下原则：
+
+- 以当前 npm 已发布包内置的模板快照作为同步源，而不是直接读取 GitHub 最新源码。
+- 只支持“带模板元数据的模板实例仓库”进入同步主路径。
+- 只自动处理受管模板文件，不把整个仓库当成可覆盖对象。
+- 默认只更新本地未修改的受管文件；对本地已修改文件、模板删除文件和其他风险点给出跳过或提示，不自动强制覆盖。
+- 保留 `--dry-run` 预览能力，让用户先看同步计划再决定是否执行。
+
+## User Stories
+
+1. 作为模板维护者，我希望已有模板实例仓库可以通过统一命令跟进模板演进，这样我不用再逐个项目手工通知和比对。
+2. 作为模板维护者，我希望同步源来自已发布的 npm 包版本，而不是 GitHub 默认分支，这样升级结果可复现、可回滚。
+3. 作为模板维护者，我希望实例仓库记录自己的模板快照版本，这样 CLI 才能知道当前仓库从哪个基线开始同步。
+4. 作为模板维护者，我希望 CLI 记录模板清单版本，这样未来受管范围变化时可以解释升级行为。
+5. 作为模板维护者，我希望受管模板文件范围是显式定义的，这样模板维护不会演变成整仓库覆盖。
+6. 作为模板维护者，我希望模板新增的公共资产可以被自动补齐到实例仓库，这样项目能跟上新的流程基线。
+7. 作为模板维护者，我希望模板删除的文件先被报告而不是自动删除，这样不会误删项目仍在使用的内容。
+8. 作为模板维护者，我希望同步后模板元数据能更新到新的模板版本，这样下一次升级仍然有可靠基线。
+9. 作为项目初始化负责人，我希望在已有模板实例仓库中执行一个统一的 `sync` 命令，这样我不需要记住手工升级步骤。
+10. 作为项目初始化负责人，我希望 CLI 在执行前先检查当前目录是不是一个受支持的模板实例仓库，这样不会在错误目录里误操作。
+11. 作为项目初始化负责人，我希望 CLI 识别仓库缺少模板元数据时直接拒绝进入同步主路径，这样我不会误以为老项目已被安全升级。
+12. 作为项目初始化负责人，我希望 CLI 能告诉我当前模板版本和目标模板版本，这样我能理解这次升级跨度。
+13. 作为项目初始化负责人，我希望先运行 `--dry-run` 看同步计划，这样我可以在落盘前预判风险。
+14. 作为项目初始化负责人，我希望 CLI 告诉我哪些文件会自动更新，这样我可以评估对当前项目的影响。
+15. 作为项目初始化负责人，我希望 CLI 告诉我哪些文件因为本地已改而被跳过，这样我知道后续要人工处理哪些地方。
+16. 作为项目初始化负责人，我希望 CLI 告诉我哪些模板文件已在新版本中被移除，这样我可以决定是否手工清理。
+17. 作为项目初始化负责人，我希望 CLI 默认不要覆盖我已经改过的受管文件，这样项目自定义不会被悄悄抹掉。
+18. 作为项目初始化负责人，我希望 CLI 不会碰我新建的非模板文件，这样项目自己的业务资产始终安全。
+19. 作为项目初始化负责人，我希望同步完成后拿到一个简洁的结果摘要，这样我知道这次升级成功了多少、还剩哪些人工动作。
+20. 作为项目初始化负责人，我希望 CLI 给出建议的 Git 操作提示，这样我可以把同步结果以可审查的方式提交。
+21. 作为内部开发者，我希望同步命令仍然挂在当前 `create-yss-spec` 包下，这样我不用等待新的稳定 CLI 包体系再开始使用。
+22. 作为内部开发者，我希望命令语义清晰地区分初始化和同步，这样我不会把升级误当成重新生成项目。
+23. 作为内部开发者，我希望 CLI 在同步前失败时给出明确原因，比如“缺少模板元数据”或“当前目录不是模板实例仓库”，这样我能快速调整操作。
+24. 作为内部开发者，我希望同步逻辑基于清单驱动，而不是硬编码在多处分支里，这样后续模板扩展时行为更可预测。
+25. 作为内部开发者，我希望模板元数据记录初始化时的关键变量摘要，这样后续需要重新渲染部分受管文件时有依据。
+26. 作为内部开发者，我希望同步只覆盖受管模板资产，不自动改动我已经在 PRD、OpenAPI、Issue 中填写的项目内容，这样业务上下文不会丢失。
+27. 作为内部开发者，我希望 README 这类可能已被项目大幅改写的文件不会被轻率自动覆盖，这样协作入口文档不会被模板版本冲掉。
+28. 作为内部开发者，我希望同步对本地已修改文件采用 fail-closed 策略，这样风险暴露在前面而不是事后发现。
+29. 作为内部开发者，我希望同步行为可以通过现有 CLI 行为测试覆盖，这样工具升级后我能持续相信它。
+30. 作为未来维护者，我希望“老项目补挂模板基线”被明确排除在本版之外，这样 MVP 的目标不会在一开始就失焦。
+
+## Implementation Decisions
+
+- 同步能力继续在现有 `create-yss-spec` npm 包内演进，不为本功能单独新建独立仓库或第二个 CLI 包。
+- 命令入口采用过渡形态 `sync` 子命令，保持与现有初始化命令同包共存；是否演进为 `yss-spec sync` 留待后续版本评估。
+- 模板同步被定义为“受管模板资产同步”，不是整仓库重置，也不是覆盖式重新初始化。
+- 同步源以当前执行的 npm 包内置模板快照为准，目标模板快照版本与 npm 包版本绑定。
+- 模板实例仓库必须具备模板元数据文件才能进入同步主路径。没有元数据的历史项目不在本版支持范围内。
+- 模板元数据至少需要表达模板名称、当前模板快照版本、模板来源、最近一次同步时间、受管清单版本，以及初始化时的关键变量摘要。
+- 受管模板文件清单需要从现有模板清单演进而来，支持同时服务初始化与同步两类场景。
+- MVP 自动处理的文件范围仅限公共模板资产；项目已填写的 PRD 正文、OpenAPI 草稿、Issue 内容、项目特有 README 大段内容和用户新增文件不进入自动同步范围。
+- 同步差异至少分为五类：可安全更新的未修改受管文件、本地已修改的受管文件、模板新增文件、模板已删除文件、非受管文件。
+- CLI 默认只自动更新未修改的受管文件，并新增模板新引入的受管文件。
+- 对本地已修改的受管文件，CLI 仅报告并跳过，不自动覆盖。
+- 对模板已删除文件，CLI 在 MVP 中只提示，不自动删除。
+- `--dry-run` 在同步场景中仍然是必需能力，且应输出版本变化、文件分类和预计执行动作。
+- 同步完成后，CLI 需要更新模板元数据中的当前模板快照版本和最近同步时间。
+- 同步输出中应包含人工后续动作建议，至少包括查看冲突 / 跳过文件、检查 Git diff 和提交同步结果。
+
+## Testing Decisions
+
+- 最高测试 seam 继续采用 CLI 外部行为测试，而不是先拆分大量内部实现级测试。
+- 好测试的标准是：只验证用户可观察行为，例如命令返回码、输出摘要、落盘后的文件集合、元数据变化、跳过与提示行为，不断言内部函数调用或差异算法细节。
+- 首要测试对象是 `sync` 命令的端到端行为，包括成功同步、`--dry-run` 预览、缺少模板元数据拒绝、存在本地已修改受管文件时跳过、模板新增文件补齐、模板删除文件仅提示不删除。
+- 次级测试仅在 CLI 行为测试难以稳定覆盖边界条件时补充，例如模板元数据解析或受管文件分类逻辑，但仍应优先围绕输入输出结果构建。
+- 现有代码库已经有初始化 CLI 的行为测试基线，可延续这种以命令行为核心的测试策略，而不重新建立一套完全不同的 seam。
+
+## Out of Scope
+
+- 支持没有模板元数据的历史老项目直接升级。
+- 提供 `attach`、`adopt` 或其他为老项目补挂模板基线的能力。
+- 自动三方合并或自动解决本地已修改受管文件的冲突。
+- 强制覆盖本地已修改文件的 `--force` 升级模式。
+- 自动删除模板新版本中已移除的受管文件。
+- 直接从 GitHub 最新默认分支或任意 commit 拉取未发布模板进行同步。
+- 同步项目自定义内容、业务文档正文、项目特有 README 段落、OpenAPI 草稿或 Issue 正文。
+- 将该功能扩展成多模板、多分支、多环境的统一升级平台。
+
+## Further Notes
+
+- 上游澄清记录见 `docs/discovery/yss-spec-cli-template-sync-discovery.md`。
+- 本版已经明确采用你确认的边界：MVP 只支持“带模板元数据的模板实例仓库”。
+- 如果后续确实需要覆盖历史老项目，建议把“模板基线接管 / attach”单独立项，不与本次 sync 主路径混做一个需求。
+- 进入 `to-issues` 前，最好补一个实现路由记录，明确现有 `template.manifest.json` 将如何演进为初始化与同步共用的受管清单。

package/template/docs/user-guide/create-yss-spec-cli-guide.md

@@ -17,7 +17,8 @@
 - 生成前端 / 后端运行时代码工程
 - 自动安装依赖
 - 自动创建远端 Git 仓库、CI 或 Issue Board
-- 把已有项目升级到最新模板版本
+- 直接接管没有模板元数据的历史老项目
+- 自动解决本地已修改受管文件的冲突
 
 ## 快速开始
 
@@ -78,6 +79,22 @@ npx create-yss-spec@latest \
 
 `--dry-run` 只展示计划，不会创建目录，也不会删除已有文件。
 
+### 同步已有模板实例仓库
+
+```bash
+npx create-yss-spec@latest sync
+```
+
+适合已经由 `create-yss-spec` 初始化过、并且根目录带有 `.yss-template.json` 的模板实例仓库。
+
+### 只预演同步，不真正写入
+
+```bash
+npx create-yss-spec@latest sync --dry-run
+```
+
+适合在升级前先查看版本变化、将要更新的文件、将被跳过的本地改动文件，以及模板已删除但不会自动删除的文件。
+
 ## 参数说明
 
 | 参数 | 含义 | 默认行为 |
@@ -93,6 +110,12 @@ npx create-yss-spec@latest \
 | `--include-example-docs` | 显式保留示例文档 | 默认开启 |
 | `--no-example-docs` | 不生成示例文档 | 默认关闭 |
 
+`sync` 子命令当前只支持：
+
+- 在模板实例仓库根目录执行
+- 仓库内已存在 `.yss-template.json`
+- 以当前 npm 已发布包内置模板快照作为同步源
+
 ## 输出内容说明
 
 CLI 会根据模板清单把源仓库内容分成三类处理：
@@ -114,6 +137,12 @@ CLI 会根据模板清单把源仓库内容分成三类处理：
 
 如果启用了 `--git-init`，目标目录下还会生成 `.git/`。
 
+初始化完成后，CLI 还会额外生成：
+
+- `.yss-template.json`
+
+这个文件用于记录模板名称、模板版本、模板来源、最近同步时间、受管模板文件基线和关键渲染变量。后续 `sync` 能否安全工作，依赖这份模板元数据。
+
 ## 默认安全策略
 
 为了避免误覆盖，CLI 采用默认安全策略：
@@ -123,6 +152,13 @@ CLI 会根据模板清单把源仓库内容分成三类处理：
 - 目标目录不能位于模板源仓库内部
 - `--dry-run` 没有副作用
 
+对于 `sync`，默认安全策略还包括：
+
+- 当前目录缺少 `.yss-template.json` 时，直接拒绝同步
+- 只自动更新未被本地修改的受管模板文件
+- 本地已修改的受管文件会被跳过并报告
+- 模板新版本已删除的受管文件只报告，不自动删除
+
 ## 示例结果
 
 一次典型执行完成后，你会看到类似输出：
@@ -138,6 +174,25 @@ CLI 会根据模板清单把源仓库内容分成三类处理：
 
 如果已经传了 `--git-init`，第二步会提示执行 `git status` 检查初始化结果。
 
+一次典型同步完成后，你会看到类似输出：
+
+```text
+同步完成
+模板版本：0.9.0 -> 1.0.0
+自动更新：2
+新增文件：1
+跳过文件：1
+删除差异：1
+本地已修改，已跳过：
+- README.md: 检测到本地已修改的受管文件
+模板已移除但未自动删除：
+- docs/legacy-note.md
+下一步建议：
+1. 运行 git diff 或 git status 检查同步结果
+2. 人工处理被跳过文件和删除差异（如有）
+3. 确认无误后提交本次模板同步结果
+```
+
 ## 常见问题
 
 ### 1. 提示“目标目录非空，当前主路径不支持覆盖已有内容”
@@ -170,12 +225,32 @@ printf 'Acme Spec Repo\nInvestment Research\n12\n/tmp/acme-spec-repo\n' \
 
 这是设计上的非目标范围。当前 CLI 只负责初始化研发管理模板实例仓库，组织级权限操作和后续 bootstrap 仍由人工控制。
 
+### 5. 为什么 `sync` 提示缺少模板元数据
+
+说明当前目录不是受支持的模板实例仓库，或者它是一个早期初始化的历史项目，还没有 `.yss-template.json` 基线。
+
+处理方式：
+
+- 先确认当前目录是否真的是由 `create-yss-spec` 初始化出来的项目
+- 当前版本的 `sync` 只支持带模板元数据的项目
+- 历史老项目的接管 / attach 不在本版范围内
+
+### 6. 为什么 `sync` 没有覆盖我改过的文件
+
+这是刻意的默认安全策略。CLI 会把这类文件识别为“本地已修改的受管文件”，只报告、跳过，不自动覆盖。
+
+处理方式：
+
+- 查看输出中的跳过文件列表
+- 用 `git diff` 比较当前项目版本和模板版本的差异
+- 人工决定是否合并模板变更
+
 ## 维护与验证
 
 如果你在维护这个 CLI，本地验证命令是：
 
 ```bash
-npm test
+node --test packages/create-yss-spec/tests/init-cli.test.js
 ```
 
 发布前可检查打包内容：