create-yss-spec 2.2.7 → 2.2.8

package/template/docs/user-guide//345/244/226/351/203/250/345/221/275/344/273/244/350/241/214/345/267/245/345/205/267/345/256/236/350/267/265/346/214/207/345/215/227.md

@@ -1,117 +0,0 @@
-# `create-yss-spec` 外部 CLI 实践指南
-
-本文面向需要基于 YSS Spec Project Template 初始化、接管已有项目或持续同步研发管理资产的使用者。CLI 源码、测试和发布由独立项目 [iloveZzz/create-yss-spec](https://github.com/iloveZzz/create-yss-spec) 维护；本模板仓库只记录使用方法和跨仓库契约。
-
-## 适用范围
-
-`create-yss-spec` 用于生成或补齐包含 Spec、架构、OpenAPI、Ticket 和 Agent 协作基线的模板实例仓库。它不负责生成前后端运行时工程，也不会代替你创建远程 Git 仓库、CI 或 Ticket Board。
-
-“最新模板”指用户执行的 `npx create-yss-spec@latest` 所携带的最新已发布快照。CLI 运行时不会直接拉取模板仓库；每个实例 metadata 都记录绑定的 `templateCommit`，便于审计、升级和回滚。
-
-## 空目录初始化
-
-推荐使用 npm create 入口：
-
-```bash
-npm create yss-spec@latest
-```
-
-也可直接通过 npx 执行：
-
-```bash
-npx create-yss-spec@latest \
-  --project-name "项目名称" \
-  --business-domain "业务领域" \
-  --target-dir "./project" \
-  --git-init
-```
-
-初始化会把模板源身份转换为 `repository_mode: project-instance`，并写入 metadata schema v2。`--dry-run` 只预览，不创建目录、不删除文件。
-
-## 接管已有项目
-
-在已有项目根目录执行 `attach`，只补齐 manifest 声明的研发管理资产，包括根规则文档、`docs/`、skills、投影、校验脚本和 metadata。前后端运行时代码、业务目录、用户文件和 `.git` 原样保留。
-
-先预演：
-
-```bash
-npx create-yss-spec@latest attach \
-  --target-dir . \
-  --project-name "项目名称" \
-  --business-domain "业务领域" \
-  --dry-run
-```
-
-确认计划后写入：
-
-```bash
-npx create-yss-spec@latest attach \
-  --target-dir . \
-  --project-name "项目名称" \
-  --business-domain "业务领域" \
-  --apply [--force]
-```
-
-约束：
-
-- `--dry-run` 与 `--apply` 互斥，且必须显式选择其中一个。
-- 已有 `.yss-template.json` 时拒绝重复接管，请使用 `sync`。
-- 合法 `template-source` 会转换为 `project-instance`；合法 `project-instance` 保留并校验；身份文件字段、schema 或 mode 非法时阻断。
-- 受管路径计划分为 `missing`、`matched`、`conflict`、`unsafe`。`--force` 只允许覆盖 conflict，不能绕过 unsafe、迁移冲突或无法归属的扁平 Ticket。
-- 覆盖前会在目标目录外创建临时备份；验证失败自动回滚，metadata 不更新。成功后备份默认保留，并输出恢复路径和清理命令。
-- Git worktree 有脏改动时允许继续，但会强提醒；CLI 不自动 stash 或提交。
-
-## 持续同步模板
-
-已初始化或已 attach 的项目根目录存在 `.yss-template.json` 后，可以先预演：
-
-```bash
-npx create-yss-spec@latest sync \
-  --target-dir . \
-  --dry-run
-```
-
-确认后执行：
-
-```bash
-npx create-yss-spec@latest sync \
-  --target-dir . [--force]
-```
-
-普通同步会新增缺失文件，更新 baseline 未被本地修改的文件，并报告冲突。`sync --force` 会先备份，再覆盖所有受管 conflict；模板删除的文件默认只报告不删除，模板无关文件始终不覆盖。旧路径只有在固定迁移计划安全完成时才移动或删除。
-
-同步结束会重新运行：
-
-```bash
-scripts/sync-skills --check
-scripts/update-skill-lock --check
-scripts/verify-template
-```
-
-任一门禁失败都会回滚本轮文件变更，并保留旧 metadata 版本。
-
-## 生成后检查
-
-初始化、attach 或 sync 后，至少完成以下检查：
-
-1. 运行 `git status --short`，确认实际变更范围。
-2. 检查 `AGENTS.md`、`CONTEXT.md`、`README.md`、`yss-project.yaml` 和 `docs/`。
-3. 确认 `.yss-template.json` 的 `templateCommit` 为 40 位 commit，并核对 `managedFilesManifestVersion`。
-4. 确认 `.qoder/skills`、其他 skills projection 和 `skills-lock.json` 门禁通过。
-5. 人工处理冲突和只报告未删除的文件，确认无误后再创建 Git checkpoint。
-
-## 问题定位边界
-
-- CLI 安装、参数解析、初始化、attach、同步、npm 发布或 CLI 测试问题：在 [create-yss-spec 独立仓库](https://github.com/iloveZzz/create-yss-spec) 追踪。
-- 模板内容、流程文档、Agent skills 或 `scripts/verify-template` 问题：在本模板仓库追踪。
-
-## 发布与验证
-
-模板修复并通过 fresh verification 后，CLI 发布前必须绑定确定模板 commit：
-
-```bash
-YSS_SPEC_TEMPLATE_REF=<pinned-commit> npm test
-YSS_SPEC_TEMPLATE_REF=<pinned-commit> npm pack --dry-run
-```
-
-发布顺序为：模板修复与验证 → CLI 绑定 commit 并完成跨仓库测试 → 独立审查 → 发布 CLI `2.1.6`。任一仓库未通过共同验证时，不声明整体可发布。