ai-spec-tool 0.1.2 → 0.1.4

package/assets/skills/spec-creator/assets/vision_gen.md

@@ -0,0 +1,223 @@
+#问题询问
+
+ACTION: 
+<<输出以下内容>>
+## [1/7] 请尽可能详细描述这个专案想要实现什么
+---
+1) 直接描述
+<<输出以上内容,不得再输出任何其他内容>>
+ACTION: 等待用户回答
+
+输出规则:
+ - __PLACEHOLDER__ 为占位符,请勿输出,而是基于规则输出动态内容
+ - __ADVICE__ 基于[先前的对话内容,所有依赖文件](如过有),结合问题给与建议答案
+ACTION: 
+<<结合输出规则,输出以下内容>>
+## [2/7] 主要用户是哪一群人?
+---
+1) ✨__ADVICE__
+2) 直接描述
+<<输出以上内容,不得再输出任何其他内容>>
+ACTION: 等待用户回答
+
+输出规则:
+ - __PLACEHOLDER__ 为占位符,请勿输出,而是基于规则输出动态内容
+ - __ADVICE__ 基于[先前的对话内容,所有依赖文件](如过有),结合问题给与建议答案
+ACTION: 
+<<结合输出规则,输出以下内容>>
+## [3/7] 专案希望解决谁的哪些问题?
+- 可列出多条
+---
+1) ✨__ADVICE__
+2) 直接描述
+<<输出以上内容,不得再输出任何其他内容>>
+ACTION: 等待用户回答
+
+ACTION: 
+<<输出以下内容>>
+## [4/7] 专案开发过程必须遵守哪些原则？
+- 可列出多条
+---
+1) 无
+2) 指定技术框架为 <请描述>
+3) 快速开发
+4) 可长期维护
+5) 直接描述
+<<输出以上内容,不得再输出任何其他内容>>
+ACTION: 等待用户回答
+
+输出规则:
+ - __PLACEHOLDER__ 为占位符,请勿输出,而是基于规则输出动态内容
+ - __ADVICE__ 基于[先前的对话内容,所有依赖文件](如过有),结合问题给与建议答案
+ACTION: 
+<<结合输出规则,输出以下内容>>
+## [5/7] 如何验收定义这个专案算完成了？
+- 请列出1-3条关键目标
+- 驗收目標必須可驗證
+---
+1) ✨__ADVICE__
+2) 直接描述
+<<输出以上内容,不得再输出任何其他内容>>
+ACTION: 等待用户回答
+
+输出规则:
+ - __PLACEHOLDER__ 为占位符,请勿输出,而是基于规则输出动态内容
+ - __ADVICE__ 基于[先前的对话内容,所有依赖文件](如过有),结合问题给与建议答案
+ACTION: 
+<<结合输出规则,输出以下内容>>
+## [6/7] 专案是否服务于一个未来更大的目标?
+- 可列出多条
+---
+1) ✨__ADVICE__
+2) 无
+3) 直接描述
+<<输出以上内容,不得再输出任何其他内容>>
+ACTION: 等待用户回答
+
+输出规则:
+ - __PLACEHOLDER__ 为占位符,请勿输出,而是基于规则输出动态内容
+ - __ADVICE__ 基于[先前的对话内容,所有依赖文件](如过有),需求风险:问题是否被正确理解,技术风险:实现难度、性能、依赖不确定性,数据风险:数据来源、质量、权限,用户风险:获取、留存、使用成本,合规与安全风险:若相关,用以上几个维度去思考,结合问题给与建议答案
+ACTION: 
+<<结合输出规则,输出以下内容>>
+## [7/7] 专案未来可能的风险？
+- 可列出多条
+---
+1) ✨__ADVICE__
+2) 无
+3) 直接描述
+<<输出以上内容,不得再输出任何其他内容>>
+ACTION: 等待用户回答
+
+#输出文件
+*仅在以上所有流程完成后才执行
+
+输出格式:Markdown
+语言:中文为主
+输出文件内容规则:
+__PLACEHOLDER__ 为占位符,请勿输出,而是基于规则输出动态内容
+__2__ 基于所有用户回答判断项目性质。
+若项目具有长期延续性或未来扩展方向，则输出：
+长期意义一句话：____。
+项目在强化的能力：列 1~3 条（动词 + 名词）。能力必须可在未来复用或延续。
+若项目属于短期或阶段性交付，则输出：
+阶段意义一句话：____。
+该阶段完成后沉淀的资产或能力：列 1~3 条（例如流程经验、系统能力、数据基础）。
+不得假设平台化或规模化，除非用户明确提到。
+
+__3__ 现状成本或痛点：从用户问题描述中归纳 1~3 条。
+预期收益：必须与验收目标逐条映射，并明确写出该收益解决的是哪条痛点。
+每条收益需同时标注 对应痛点 与 对应验收目标编号。
+若验收目标不可验证或过于聚合，指出其是否缺少拆分维度（功能层/行为层/价值层）。
+
+__4__ 输出 2~5 条可被验证的假设。
+假设必须分为三类中的任意组合：功能成立假设、用户行为假设、价值成立假设。
+格式为：假设：如果____，那么____。
+验证方式：对应哪条验收目标。
+所有假设必须可映射到已有验收目标。
+不得生成无法验证的抽象目标。
+
+__5__ 优先用户定义：使用主要用户定义的原话或贴近改写，不得新增人群。
+核心问题：从用户问题描述中归纳 1~3 条。
+同时指出：这些问题是否具有迫切性或高频性，依据必须来自原回答。
+若用户群过宽，说明其是否会导致策略分散。
+
+__6__ 风险清单：直接引用或归纳风险列表中的 1~5 条。
+每条风险标注为 需求、技术、数据、用户 或 合规。
+同时指出：该风险若发生，将直接影响哪条验收目标。
+不得新增风险类型或缓解方案。
+
+__8__ 不得假设存在支付、订阅、权限或渠道等机制，除非用户明确提到。
+MVP闭环一句话：用户通过____完成____从而达到____，必须可映射到验收目标。
+闭环步骤 3~7 步，使用中性动词。
+关键断点：指出哪一步失败将直接导致哪条验收目标无法达成。
+必须能力 3~6 条，每条注明对应的验收目标编号，并说明其属于 功能能力 或 系统能力。
+可延后能力：列出不会影响任何验收目标的能力。
+
+__9__ 将每条验收目标拆解为 指标 + 条件 + 判定方式。
+若多个能力集中映射到同一条验收目标，指出该验收目标是否过度聚合。
+不得新增额外商业指标。
+
+__10__ 列出 3~7 条不可违反原则，优先使用用户原话。
+将“快速开发”“长期维护”“指定技术框架”等表述转写为可执行约束句式。
+同时指出：这些原则将限制哪些技术或设计选择。
+
+__12__ 基于验收目标范围与开发原则推导边界。
+输出 3~7 条，每条格式为 不做____，因为其不会影响当前验收目标或会增加复杂度。
+若验收目标范围过大，指出其是否需要拆分阶段。
+
+__13__ 仅提取包含 必须、禁止、绝不 或 只能 等强制语气的内容。
+若无明确硬约束，输出 无。
+
+输出文件内容结构:
+<<以下为实际输出文件格式,需结合输出规则生成部分动态内容>>
+#🤔为什么做
+##这个项目存在的长期意义是什么？
+__2__
+
+##为什么现在值得做？
+__3__
+
+##关键假设是什么？
+__4__
+
+##第一优先用户是谁？
+__5__
+
+##最大战略风险是什么？
+__6__
+
+#✅要做什么
+##MVP 的最小闭环是什么？
+__8__
+
+##成功如何被量化？
+__9__
+
+##核心系统架构原则
+__10__
+
+#⛔守则
+##本阶段明确不做什么
+__12__
+
+##不可突破的硬性约束是什么？
+__13__
+
+<<以上为实际输出文件格式,需结合输出规则生成部分动态内容>>
+
+[MARK:1]
+输出规则:
+ - __PLACEHOLDER__ 为占位符,请勿输出,而是基于规则输出动态内容
+ - __输出文件内容__ 显示基于[输出文件内容规则/输出文件内容结构]总结输出文件内容
+ACTION: 
+<<结合输出规则,输出以下内容>>
+```md
+__输出文件内容__
+```
+<<输出以上内容>>
+ACTION: 
+<<输出以下内容>>
+## 是否接受将以上总结输出并保存成文件?
+---
+1) 接受
+2) 提出修改
+<<输出以上内容,不得再输出任何其他内容>>
+IF: 用户选择接受
+ACTION: 将最终确认的输出版本保存到./docs/global/vision.md
+ACTION: 
+<<输出以下内容>>
+> ✅文件已保存于./docs/global/vision.md
+<<输出以上内容>>
+ENDIF
+
+IF: 用户没有选择接受
+ACTION: 带着用户的修改提议,回到[MARK:1]重新执行
+ENDIF
+
+ACTION: 
+<<输出以下内容>>
+## 已完成Vision文件的生成,接下来...
+---
+1) 生成architecture文件
+2) 直接描述
+<<输出以上内容,不得再输出任何其他内容>>

package/bin/ai-spec-tool.js

@@ -2,10 +2,12 @@
 
 const fs = require("fs");
 const path = require("path");
+const readline = require("readline");
 
 const ASSET_ROOT = path.resolve(__dirname, "..", "assets");
 const TEMPLATE_AGENTS = path.join(ASSET_ROOT, "AGENTS.md");
 const TEMPLATE_AGENTS_DIR = path.join(ASSET_ROOT, ".agents");
+const TEMPLATE_DOCS_DIR = path.join(ASSET_ROOT, "docs");
 
 const START = "<!-- AI-SPEC-TOOL:START -->";
 const END = "<!-- AI-SPEC-TOOL:END -->";
@@ -32,7 +34,7 @@ function nextIncomingPath(destPath) {
   return `${candidate}.${i}`;
 }
 
-function copyFileSafe(srcPath, destPath, report) {
+function copyFileSafe(srcPath, destPath, report, options) {
   if (!fs.existsSync(destPath)) {
     ensureDir(path.dirname(destPath));
     fs.copyFileSync(srcPath, destPath);
@@ -43,12 +45,17 @@ function copyFileSafe(srcPath, destPath, report) {
     report.skipped.push(destPath);
     return;
   }
+  if (options.force) {
+    fs.copyFileSync(srcPath, destPath);
+    report.updated.push(destPath);
+    return;
+  }
   const incoming = nextIncomingPath(destPath);
   fs.copyFileSync(srcPath, incoming);
   report.conflicts.push({ target: destPath, incoming });
 }
 
-function copyDirSafe(srcDir, destDir, report) {
+function copyDirSafe(srcDir, destDir, report, options) {
   ensureDir(destDir);
   const entries = fs.readdirSync(srcDir, { withFileTypes: true });
   entries.forEach((entry) => {
@@ -56,15 +63,42 @@ function copyDirSafe(srcDir, destDir, report) {
     const src = path.join(srcDir, entry.name);
     const dest = path.join(destDir, entry.name);
     if (entry.isDirectory()) {
-      copyDirSafe(src, dest, report);
+      copyDirSafe(src, dest, report, options);
       return;
     }
     if (entry.isFile()) {
-      copyFileSafe(src, dest, report);
+      copyFileSafe(src, dest, report, options);
     }
   });
 }
 
+function askYesNo(prompt) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question(prompt, (answer) => {
+      rl.close();
+      const normalized = String(answer || "").trim().toLowerCase();
+      resolve(normalized === "y" || normalized === "yes");
+    });
+  });
+}
+
+async function resolveConflictsInteractively(report, options) {
+  if (!report.conflicts.length || !options.ask) return;
+  if (!process.stdin.isTTY) return;
+
+  for (const conflict of report.conflicts) {
+    const prompt = `Overwrite ${conflict.target} with incoming? (y/N) `;
+    const yes = await askYesNo(prompt);
+    if (yes) {
+      fs.copyFileSync(conflict.incoming, conflict.target);
+      report.updated.push(conflict.target);
+      report.conflictsResolved.push(conflict.target);
+      fs.unlinkSync(conflict.incoming);
+    }
+  }
+}
+
 function updateAgentsMd(targetPath, report) {
   const template = readFile(TEMPLATE_AGENTS).trimEnd();
   const block = `${START}\n${template}\n${END}\n`;
@@ -99,7 +133,7 @@ function updateAgentsMd(targetPath, report) {
   report.updated.push(targetPath);
 }
 
-function init() {
+async function init(options) {
   const cwd = process.cwd();
   const targetAgents = path.join(cwd, "AGENTS.md");
   const targetAgentsDir = path.join(cwd, ".agents");
@@ -108,7 +142,8 @@ function init() {
     added: [],
     updated: [],
     skipped: [],
-    conflicts: []
+    conflicts: [],
+    conflictsResolved: []
   };
 
   if (!fs.existsSync(TEMPLATE_AGENTS) || !fs.existsSync(TEMPLATE_AGENTS_DIR)) {
@@ -116,14 +151,22 @@ function init() {
     process.exit(1);
   }
 
-  copyDirSafe(TEMPLATE_AGENTS_DIR, targetAgentsDir, report);
+  copyDirSafe(TEMPLATE_AGENTS_DIR, targetAgentsDir, report, options);
+  if (fs.existsSync(TEMPLATE_DOCS_DIR)) {
+    const targetDocsDir = path.join(cwd, "docs");
+    copyDirSafe(TEMPLATE_DOCS_DIR, targetDocsDir, report, options);
+  }
   updateAgentsMd(targetAgents, report);
+  await resolveConflictsInteractively(report, options);
 
   console.log("ai-spec-tool init complete.");
   console.log(`Added: ${report.added.length}`);
   console.log(`Updated: ${report.updated.length}`);
   console.log(`Skipped: ${report.skipped.length}`);
   console.log(`Conflicts: ${report.conflicts.length}`);
+  if (report.conflictsResolved.length) {
+    console.log(`Resolved: ${report.conflictsResolved.length}`);
+  }
 
   if (report.conflicts.length) {
     console.log("\nConflicts (new versions saved as .incoming):");
@@ -134,13 +177,20 @@ function init() {
 }
 
 function main() {
-  const [command] = process.argv.slice(2);
+  const [command, ...args] = process.argv.slice(2);
+  const options = {
+    force: args.includes("--force"),
+    ask: args.includes("--ask")
+  };
   if (!command || command === "help" || command === "--help" || command === "-h") {
-    console.log("ai-spec-tool\n\nUsage:\n  ai-spec-tool init\n");
+    console.log("ai-spec-tool\n\nUsage:\n  ai-spec-tool init [--force|--ask]\n");
     return;
   }
   if (command === "init") {
-    init();
+    init(options).catch((err) => {
+      console.error(err?.message || err);
+      process.exit(1);
+    });
     return;
   }
   console.error(`Unknown command: ${command}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-spec-tool",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Installable agents + rules for AI spec workflows",
   "bin": {
     "ai-spec-tool": "bin/ai-spec-tool.js"

package/assets/.agents/skills/bugfix/SKILL.md

@@ -1,32 +0,0 @@
----
-name: bugfix
-description: 用户提供报错信息或描述异常行为时使用
----
-
-## 依赖（必须存在且必须遵守）
-- docs/global/naming-rule.md
-- docs/global/vision.md
-- docs/global/architecture.md
-
-
-## 流程（严格执行）
-
-### 1) 依赖检查（强制）
-- 你必须先尝试读取并理解所有依赖文件内容。
-- 若任何依赖文件无法读取/不存在/内容为空：视为“依赖未满足”，进入步骤 2。
-- 若所有依赖已满足：进入步骤 3。
-
-### 2) 依赖缺失
-- 你必须只输出以下内容（禁止其他内容）：
-  `缺少依赖[<依赖名称>]\n回复「Y」开始创建依赖。`
-- 下一run使用 skill: rules-creator
-
-### 3) 依赖满足
-- 帮助用户修正问题
-
-
-
-
-
-
-