create-yss-spec 2.1.14 → 2.1.15

package/README.md

@@ -14,6 +14,18 @@ npm create yss-spec@latest
 npx create-yss-spec@latest
 ```
 
+查看用法、命令、参数和样例：
+
+```bash
+npx create-yss-spec@latest --help
+```
+
+查看 CLI 版本：
+
+```bash
+npx create-yss-spec@latest --version
+```
+
 ## 当前支持
 
 - 交互式收集 `projectName`、`businessDomain`、`targetDir`
@@ -33,7 +45,7 @@ npx create-yss-spec@latest
 - 旧、新资产内容冲突或清单 schema / mode 非法时 fail closed
 - 保留模板的共享 skill 投影；生成实例可在尚未 `git init` 时运行模板校验
 
-本次模板适配按 `2.1.14` 发布。`templateCommit` 会写入实例 metadata；“最新模板”指用户执行的 `npx create-yss-spec@latest` 所携带的最新已发布快照，CLI 运行时不会拉取模板仓库。
+本次模板适配按 `2.1.15` 发布。`templateCommit` 会写入实例 metadata；“最新模板”指用户执行的 `npx create-yss-spec@latest` 所携带的最新已发布快照，CLI 运行时不会拉取模板仓库。
 
 ## 接管已有项目
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-yss-spec",
-  "version": "2.1.14",
+  "version": "2.1.15",
   "description": "Initialize a YSS spec project template repository",
   "repository": {
     "type": "git",

package/src/cli.js

@@ -33,6 +33,8 @@ const TEMPLATE_METADATA_FILENAME = ".yss-template.json";
 const TEMPLATE_MANIFEST_VERSION = sha256(TEMPLATE_MANIFEST_TEXT);
 const TEMPLATE_SOURCE = "github:iloveZzz/yss-spec-project-template";
 const METADATA_SCHEMA_VERSION = 2;
+const HELP_FLAGS = new Set(["--help", "-h", "-help"]);
+const VERSION_FLAGS = new Set(["--version", "-v", "-version"]);
 const AGENT_SKILL_ROOTS = [
   ".agents/skills",
   ".claude/skills",
@@ -184,8 +186,10 @@ function parseArgs(argv) {
       options.includeExampleDocs = true;
     } else if (current === "--no-example-docs") {
       options.includeExampleDocs = false;
-    } else if (current === "--help" || current === "-h") {
+    } else if (HELP_FLAGS.has(current)) {
       options.help = true;
+    } else if (VERSION_FLAGS.has(current)) {
+      options.version = true;
     } else {
       throw new Error(`不支持的参数：${current}`);
     }
@@ -1539,6 +1543,10 @@ function runInit(argv = []) {
     printHelp();
     return;
   }
+  if (options.version) {
+    printVersion();
+    return;
+  }
   return promptForMissingOptions(options).then((promptedOptions) => {
     assertRequiredOptions(promptedOptions, "init");
     readTemplateSnapshot();
@@ -1592,6 +1600,10 @@ function runAttach(argv = []) {
     printHelp();
     return;
   }
+  if (options.version) {
+    printVersion();
+    return;
+  }
   assertRequiredOptions(options, "attach");
   if (options.dryRun && options.apply) {
     throw new Error("attach 的 --dry-run 与 --apply 互斥");
@@ -1692,6 +1704,10 @@ function runSync(argv = []) {
     printHelp();
     return;
   }
+  if (options.version) {
+    printVersion();
+    return;
+  }
   readTemplateSnapshot();
   const targetDir = normalizeTargetDir(options.targetDir || ".");
   inspectExistingTargetDir(targetDir);
@@ -1782,16 +1798,87 @@ function runSync(argv = []) {
   console.log("3. 确认无误后提交本次模板同步结果");
 }
 
+function argvIncludesFlag(argv, flags) {
+  return argv.some((arg) => flags.has(arg));
+}
+
+function printVersion() {
+  console.log(`create-yss-spec ${PACKAGE_MANIFEST.version}`);
+}
+
 function printHelp() {
   console.log(`create-yss-spec ${PACKAGE_MANIFEST.version}
 
-初始化：create-yss-spec --project-name <name> --business-domain <domain> --target-dir <dir>
-接管已有项目：create-yss-spec attach --target-dir <dir> --project-name <name> --business-domain <domain> --dry-run|--apply [--force]
-同步模板：create-yss-spec sync [--target-dir <dir>] [--dry-run] [--force]
+USAGE
+  $ create-yss-spec [COMMAND] [OPTIONS]
+
+COMMANDS
+  (default)  初始化新的模板实例仓库
+  attach     向已有项目补齐受管研发管理资产
+  sync       同步已有模板实例的受管资产
+
+OPTIONS
+  --project-name <name>              项目名称；init 不传则进入交互输入
+  --business-domain <domain>         业务领域；init 不传则进入交互输入
+  --team-size <size>                 团队规模；init 不传则可留空，默认「待补充」
+  --target-dir <dir>                 目标目录；init 不传则进入交互输入，sync 默认为当前目录
+  --issue-tracker github|gitlab      默认 issue tracker 偏好（默认 github）
+  --dry-run                          只预览计划，不写入文件
+  --apply                            attach 确认执行写入；不能与 --dry-run 同时使用
+  --force                            init：允许清空非空目录后重新生成
+                                     attach / sync：覆盖受管冲突文件；unsafe 路径始终阻断
+  --git-init                         初始化完成后执行 git init
+  --include-example-docs             显式保留示例文档（默认开启）
+  --no-example-docs                  不生成示例文档
+  -h, --help                         显示本帮助信息
+  -v, --version                      显示 CLI 版本
+
+EXAMPLES
+  $ npm create yss-spec@latest
+  $ npx create-yss-spec@latest --help
+  $ npx create-yss-spec@latest --version
+  $ npx create-yss-spec@latest \\
+      --project-name "Acme Spec Repo" \\
+      --business-domain "Investment Research" \\
+      --team-size "12" \\
+      --target-dir "./acme-spec-repo" \\
+      --issue-tracker github \\
+      --git-init
+  $ npx create-yss-spec@latest \\
+      --project-name "Preview Repo" \\
+      --business-domain "Data Platform" \\
+      --target-dir "./preview-repo" \\
+      --dry-run
+  $ npx create-yss-spec@latest attach \\
+      --target-dir . \\
+      --project-name "Acme Application" \\
+      --business-domain "Data Platform" \\
+      --dry-run
+  $ npx create-yss-spec@latest attach \\
+      --target-dir . \\
+      --project-name "Acme Application" \\
+      --business-domain "Data Platform" \\
+      --apply
+  $ npx create-yss-spec@latest sync
+  $ npx create-yss-spec@latest sync --dry-run
+  $ npx create-yss-spec@latest sync --target-dir . --force
+
+LEARN MORE
+  仓库 README：https://github.com/iloveZzz/create-yss-spec#readme
+  使用手册：https://github.com/iloveZzz/create-yss-spec/blob/main/docs/user-guide/create-yss-spec-cli-guide.md
+  模板仓库：https://github.com/iloveZzz/yss-spec-project-template
 `);
 }
 
 async function runCli(argv = []) {
+  if (argvIncludesFlag(argv, HELP_FLAGS)) {
+    printHelp();
+    return;
+  }
+  if (argvIncludesFlag(argv, VERSION_FLAGS)) {
+    printVersion();
+    return;
+  }
   if (argv[0] === "sync") {
     runSync(argv.slice(1));
     return;

package/template.snapshot.json

@@ -12,5 +12,5 @@
     ".gitignore": "__yss_dotfile__.gitignore"
   },
   "snapshotHash": "e15b05f44ef09f9953338c6846345c1197d615f7d31370deb0b3c5cdc3195376",
-  "generatedAt": "2026-08-24T03:44:43.752Z"
+  "generatedAt": "2026-08-24T05:35:24.742Z"
 }