visual-spec 0.1.8 → 0.1.9

package/docs/zh-CN/ai-platform-installation.md

@@ -0,0 +1,39 @@
+# 多 AI 平台安装指南
+
+推荐使用 skills.sh 的官方安装器（skills CLI）进行安装：同一套命令可面向不同 AI 平台（Trae / Claude Code / Cursor / GitHub Copilot 等）把 Skill 安装到对应的 skills 目录。
+
+## 方式一：skills.sh（推荐）
+
+安装器会自动检测本机支持的 agent，并提示选择安装位置与范围（项目级或全局）。
+
+```bash
+npx skills add visual-req/visual-spec --skill visual-spec-skill
+```
+
+指定安装到某个 AI 平台（示例）：
+
+```bash
+# Trae（项目级）
+npx skills add visual-req/visual-spec --skill visual-spec-skill -a trae
+
+# Claude Code（项目级）
+npx skills add visual-req/visual-spec --skill visual-spec-skill -a claude-code
+
+# Cursor（项目级）
+npx skills add visual-req/visual-spec --skill visual-spec-skill -a cursor
+
+# GitHub Copilot（项目级）
+npx skills add visual-req/visual-spec --skill visual-spec-skill -a github-copilot
+```
+
+全局安装（对当前用户所有项目生效）：
+
+```bash
+npx skills add visual-req/visual-spec --skill visual-spec-skill -g
+```
+
+查看该仓库包含的 skills：
+
+```bash
+npx skills add visual-req/visual-spec --list
+```

package/docs/zh-CN/commands.md

@@ -5,20 +5,23 @@
 | `/vspec:new` | 从原始需求生成第一版规格产物 | 原始需求文本 + 交互式问答 | `/specs/`（original、stakeholders、roles、terms、flows、scenarios、scenario_details、dependencies、functions、questions）+ 初始化 `/docs/*` 输入归档目录 |
 | `/vspec:refine` | 应用补充/澄清材料，并同步更新详情与原型 | `/docs/refine/*`（或命令参数）+ `/specs/background/original.md` + 前置条件 `/specs/details/` | 追加更新到 `/specs/background/original.md`（变更清单 + 最新口径）+ 更新受影响的 `/specs/details/` 与 `/specs/prototypes/` |
 | `/vspec:refine-q` | 将已回答的问题合并回需求并形成新口径 | `/specs/background/original.md` + `/specs/background/questions.md` | 追加到 `/specs/background/original.md`（采纳项 + 变更清单 + 最新口径） |
+| `/vspec:more-q` | 追加更多“待确认问题”到 questions 清单 | `/specs/background/original.md` + `/specs/background/questions.md` | 追加写入 `/specs/background/questions.md`（新增问题 + 回答指引） |
 | `/vspec:detail` | 展开到“可实现”的单功能详细规格 | `/specs/functions/*` + 支撑产物（background/flows/roles；models 若已存在） | `/specs/details/<function_slug>/*`（RBAC、交互、校验、日志、通知、MQ、导入导出、定时任务等） |
 | `/vspec:verify` | 快速验证：生成模型与可运行原型用于评审 | 现有 `/specs/` 产物（functions + details + roles） | `/specs/models/*.md`、`/specs/prototypes/`（按 `scheme.yaml` 选栈生成可运行原型 + `scenario.html` 评审页） |
 | `/vspec:accept` | 生成验收用例 | functions/scenarios/details/roles/models | `/specs/acceptance/<function_slug>/acceptance_cases.md`、`/specs/acceptance/index.md` |
 | `/vspec:append-test` | 生成自动化测试代码 | 验收用例 + 仓库测试技术栈 | 写入既有测试目录或 `/tests/` |
 | `/vspec:impl` | 生成后端 + 前端联调实现代码 | specs/details/models/dependencies | 写入集成实现代码（API 合同、后端、前端对接） |
 | `/vspec:upgrade` | 基于遗留材料做升级/重构分析并生成新规格 | `/docs/current/file_list.md` + `/docs/legacy/*`（可选 templates/texts/assets）+ 既有 `/specs/background/original.md`（可选） | 生成/更新 `/specs/`（沿用 `/vspec:new` 结构）+ 同步技术选型到 `/scheme.yaml` |
-| `/vspec:qc` | 对 `/specs/` 产物做质量检查 | 内置标准 + 可选 `quality_standard.md` + `/specs/` | `/specs/qc_report.md` |
+| `/vspec:qc` | 对 `/specs/` 产物做质量检查 | 内置标准 + 可选 `domain_quality_standard.md` + 可选 `quality_standard.md` + `/specs/` | `/specs/qc_report.md` |
 | `/vspec:plan` | 估算与排期 | functions/roles/flows/dependencies/details | `/specs/plan/plan_estimate.md`、`/specs/plan/plan_schedule.html` |
+| `/vspec:mrd` | 生成 MRD：市场/竞品/用户/产品设计 | `/specs/background/*` + `/specs/flows/*` + `/specs/functions/*`（如有） | `/docs/market/*.md`（market/competitors/users/product_design） |
 
 ## `/vspec:new`
 
 - 适用场景：刚拿到需求且信息不完整，需要快速形成“可评审的共同语言”
 - 关键输出：干系人、角色、术语、流程、场景、功能清单、开放问题
-- 目录初始化：创建 `/docs/` 及其子目录（legacy/current/change/refine/templates/texts/assets）用于输入归档与后续命令使用
+- 目录初始化：创建 `/docs/` 及其子目录（legacy/current/refine/templates/texts/assets）用于输入归档与后续命令使用
+- 提示：生成“开放问题/待确认问题”后，你可以把回答工作委托给 AI 先给出建议答案，你只需要逐条确认/修改即可（推荐做法：先让 AI 代答一版，再由业务确认口径）
 
 ## `/vspec:refine`
 
@@ -36,6 +39,15 @@
 - 适用场景：业务已在 `/specs/background/questions.md` 填写答案，需要合并回需求并形成新口径
 - 关键输出：采纳的 Q&A 项 + 变更清单 + 最新口径
 
+## `/vspec:more-q`
+
+- 适用场景：问题清单还不够，或需求发生变更，需要补充更多“待确认问题”
+- 关键输出：追加到 `/specs/background/questions.md` 末尾的新问题条目（延续编号、不重复），并提供“回答指引”
+- 推荐用法：
+  - 先执行 `/vspec:more-q` 生成/补充问题
+  - 业务按编号逐条填写问题的“回答/回答者/回答时间/状态”
+  - 再执行 `/vspec:refine-q` 合并答案进入 `original.md`
+
 ## `/vspec:detail`
 
 - 适用场景：在设计/实现前，需要把每个功能点展开到“可实现”的规格粒度

package/docs/zh-CN/getting-started.md

@@ -4,39 +4,22 @@
 
 ### 1. 安装
 
-先全局安装 npm 包，再把 Skill 安装到 AI 编辑器的配置目录：
+把 Skill 安装到 AI 编辑器的配置目录：
 
 - 安装与校验：`installation.md`
 
-安装/更新（npm）：
+安装/更新（skills.sh）：
 
 ```bash
-npm install -g visual-spec@latest
-```
-
-安装/更新（pnpm）：
-
-```bash
-pnpm add -g visual-spec@latest
-```
-
-安装/更新（yarn）：
-
-Yarn Classic：
-
-```bash
-yarn global add visual-spec@latest
-```
-
-Yarn Berry（v2+）：
-
-```bash
-yarn dlx -p visual-spec@latest vspec
+npx skills add visual-req/visual-spec --skill visual-spec-skill
 ```
 
 ### 2. 推荐流程
 
 - 初始规格：`/vspec:new`
+  - 可选语言：
+    - 单语言：`/vspec:new lang=zh-CN`（或 `lang=en`、`lang=ja`），会把 `/scheme.yaml` 的 `selected.language` 设为该值，并让后续文档产物全程按该语言输出
+    - 多语言（原型可切换）：`/vspec:new lang=zh-CN,en`，文档默认输出 `zh-CN`，并把 `/scheme.yaml` 的 `selected.languages` 设为可切换语言集合
   - 执行中会先生成需求口径文件（`/specs/background/original.md`），并在该步骤提出若干澄清问题
   - 你需要先在对话中回答这些问题，然后输入“继续”才能完成 `/vspec:new` 全流程（这些澄清回答不写入 `questions.md`）
   - 执行过程中还会生成开放问题清单（`/specs/background/questions.md`），用于后续合并
@@ -51,7 +34,7 @@ yarn dlx -p visual-spec@latest vspec
 
 ### 3. 关键目录
 
-- `/docs/`：输入归档（legacy/current/change/refine/templates/texts/assets）
+- `/docs/`：输入归档（legacy/current/refine/templates/texts/assets）
 - `/specs/`：生成产物（background/details/models/prototypes/acceptance 等）
 - `/scheme.yaml`：技术栈与包管理器选择（原型与实现必须遵循）
 
@@ -72,11 +55,6 @@ yarn dlx -p visual-spec@latest vspec
 - 运行：`/vspec:refine`
 - 结果：向 `/specs/background/original.md` 追加更新，并同步更新受影响的 `/specs/details/` 与 `/specs/prototypes/`
 
-#### 变更（`change`）
-
-- 把变更材料放到 `/docs/change/`（可选 `file_list.md`）
-- 结果：做影响分析并更新产物（优先 `/specs/details/<module_slug>/`），同时更新变更日志
-
 #### 升级/重构（`upgrade`）
 
 - 在 `/docs/current/file_list.md` 中列出输入材料（遗留系统在 `/docs/legacy/`，新增输入在 `/docs/current/`）

package/docs/zh-CN/installation.md

@@ -1,53 +1,18 @@
 ## 安装到支持 Skill 的 AI 编辑器
 
-本包使用脚本把内置的 Skill 目录复制到你的 AI 编辑器配置目录（Trae / Qwen / Kiro 等）。不同编辑器的配置路径可能不同，但安装逻辑一致：把 `visual-spec-skill` 安装到目标目录的 `skills/` 下。
+推荐使用 skills.sh 的官方安装器（skills CLI）安装到支持 Skill 的 AI 编辑器（Trae / Qwen / Kiro 等）。安装器会自动识别可用的 agent，并把 `visual-spec-skill` 安装到对应的 `skills/` 目录。
 
 ### 前置条件
 
 - Node.js >= 14
 
-### 安装/更新（npm）
+### 安装/更新（推荐：skills.sh）
 
 ```bash
-npm install -g visual-spec@latest
-```
-
-### 安装/更新（pnpm）
-
-```bash
-pnpm add -g visual-spec@latest
-```
-
-### 安装/更新（yarn）
-
-Yarn Classic：
-
-```bash
-yarn global add visual-spec@latest
-```
-
-Yarn Berry（v2+）：
-
-```bash
-yarn dlx -p visual-spec@latest vspec
-```
-
-### 指定安装目录（`--target-skills-dir`）
-
-默认情况下，安装脚本会把 Skill 安装到当前目录的 `.trae/skills/visual-spec-skill`。如果你需要安装到自定义的 `skills/` 目录（例如统一放在某个编辑器配置目录），可以在安装后执行：
-
-```bash
-vspec --target-skills-dir /path/to/skills --force
-```
-
-说明：
-- `--target-skills-dir` 传入的是“skills 目录”，脚本会自动追加子目录 `visual-spec-skill/`
-- 你也可以使用 `--target-skill-dir` 传入完整目标目录（包含 `visual-spec-skill`）：
-
-```bash
-vspec --target-skill-dir /path/to/skills/visual-spec-skill --force
+npx skills add visual-req/visual-spec --skill visual-spec-skill
 ```
 
 ### 下一步
 
 - 快速开始：`getting-started.md`
+- 多 AI 平台安装指南：`ai-platform-installation.md`

package/docs/zh-CN/quality_check.md

@@ -0,0 +1,33 @@
+## 需求质量检查（独立使用）
+
+本节说明如何不依赖 `/vspec:qc`，单独利用内置的质量标准文件，对“Word/Markdown/文档库”等任意格式的需求文档进行质量扫描，并生成质量问题表格。
+
+### 准备
+
+- 质量标准文件路径（任选其一，取当前环境存在者）：
+  - Skill 根目录：`/prompts/vspec_qc/quality_standard.md`
+  - 源码路径：`skills/visual-spec-skill/prompts/vspec_qc/quality_standard.md`
+- 你的需求文档（PRD、功能说明、规格等），支持 Word/PDF/Markdown 等
+
+### 使用方式（以 DeepSeek 聊天式 AI 为例）
+
+1. 在聊天窗口上传两份文件：
+   - `quality_standard.md`（质量标准）
+   - 你的需求文档（Word/PDF/Markdown 等）
+2. 在输入框键入：
+
+   请按照质量标准对需求文档进行质量检查，并生成质量检查结果的表格。
+
+3. 若需要结构化表格，可补充表头要求，例如：
+   - 编号
+   - 问题分类/标题
+   - 是否通过（是/否/部分）
+   - 问题摘要
+   - 涉及位置（章节/段落/页码）
+   - 修复建议
+
+### 建议
+
+- 对于“上下限、时间口径、公式精度、权限与数据权限、外部依赖失败策略”等容易遗漏的部分，可在提问中强调“请重点覆盖边界/异常/幂等/回滚/审计/对账”等关键维度
+- 如果发现高频问题，可将其沉淀到你项目根目录的 `domain_quality_standard.md`，作为领域补充标准，供 `/vspec:qc` 合并使用
+

package/docs/zh-CN/scheme.example.yaml

@@ -7,7 +7,8 @@ selected:
   prototype_backend_stack: java17_springboot3
   prototype_database: mysql8
   package_manager: npm
-  language: zh-CN
+  language: en # 文档默认语言：en | zh-CN | ja
+  languages: [en] # 可选：原型可切换语言集合，例如 [zh-CN, en]
 
 prototype_options:
   calendar_view:

package/docs/zh-CN/structure.md

@@ -13,8 +13,7 @@ Skill 会按命令阶段逐步在 `/specs/` 下生成产物，并维护少量项
 │  ├─ legacy/                             # 遗留系统材料（功能、权限、交互、API 等）
 │  ├─ current/                            # 本次迭代新增/补充材料（目标、差异、流程、UI 约束等）
 │  │  └─ file_list.md                     # upgrade 入口清单（/vspec:upgrade 读取/生成）
-│  ├─ change/                             # 变更输入归档（可选）
-│  │  └─ file_list.md                     # 可选：有序输入清单
+│  ├─ dependencies/                       # 外部依赖系统文档库（已有依赖系统说明，推荐）
 │  ├─ refine/                             # 补充/澄清输入（/vspec:refine 读取）
 │  │  └─ file_list.md                     # 可选：有序输入清单
 │  ├─ templates/                          # 模板（PRD/文案/UI/表格模板，可选）
@@ -65,7 +64,7 @@ Skill 会按命令阶段逐步在 `/specs/` 下生成产物，并维护少量项
 ```
 
 说明：
-- `docs/`：归档业务输入与交付对齐材料。建议使用 `legacy/current/change/refine/templates/texts/assets` 等子目录，并在文件名中包含来源/版本信息。
+- `docs/`：归档业务输入与交付对齐材料。建议使用 `legacy/current/dependencies/refine/templates/texts/assets` 等子目录，并在文件名中包含来源/版本信息。
 - `scheme.yaml`：选择 `/vspec:verify` 与 `/vspec:impl` 使用的技术栈与选项。读取顺序为项目根目录的 `scheme.yaml` 优先，其次 `/specs/scheme.yaml`。若都不存在则生成默认 `scheme.yaml`。
 
 下一步：

package/docs/zh-CN/workflows.md

@@ -54,8 +54,32 @@
   - `/specs/plan/plan_estimate.md`
   - `/specs/plan/plan_schedule.html`
 
-## 安装（npm）
+## 独立使用质量规范（不依赖 `/vspec:qc`）
 
-- 推荐在目标项目根目录安装：`npm install <git-url>`
-- 安装后 Skill 会被复制到：`<your-project>/.trae/skills/visual-spec-skill/`
-- 需要时可手动安装：`npx vspec --force`
+内置质检标准文件位于（任选其一，取你当前环境中存在的路径）：
+- Skill 根目录下：`/prompts/vspec_qc/quality_standard.md`
+- 本仓库源码路径：`skills/visual-spec-skill/prompts/vspec_qc/quality_standard.md`
+
+你可以把它作为“通用需求质检标准”，独立用于检查其他方式写出来的需求文档（不要求必须由 `/vspec:*` 生成）。
+
+以 DeepSeek 聊天窗口为例（其他大模型/聊天产品同理）：
+1. 上传 2 份文件：
+   - `quality_standard.md`（质检标准）
+   - 你的需求文档（例如 PRD/需求说明/功能规格）
+2. 在聊天窗口输入以下指令：
+
+   请按照质量标准对需求文档进行质量检查，并生成质量检查结果的表格。
+
+建议输出表格列（可选）：
+- 检查项编号
+- 检查项标题
+- 是否通过（是/否/部分）
+- 发现的问题摘要
+- 涉及的文档位置（章节/段落）
+- 修复建议
+
+## 安装（skills.sh）
+
+```bash
+npx skills add visual-req/visual-spec --skill visual-spec-skill
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "visual-spec",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "AI skill: visual-spec-skill (/vspec:* commands) for requirement analysis, prototyping, detailing, testing, and planning.",
   "license": "MIT",
   "type": "commonjs",
@@ -10,15 +10,19 @@
   "scripts": {
     "postinstall": "node scripts/postinstall.cjs",
     "install-skill": "node scripts/postinstall.cjs --force",
-    "dry-run": "node scripts/postinstall.cjs --dry-run"
+    "dry-run": "node scripts/postinstall.cjs --dry-run",
+    "build-skill": "node scripts/build_skill.cjs"
   },
   "files": [
     "skills/visual-spec-skill/SKILL.md",
     "skills/visual-spec-skill/SKILL-zh-CN.md",
+    "skills/visual-spec-skill/SKILL-ja-JP.md",
     "skills/visual-spec-skill/prompts/vspec_accept/",
     "skills/visual-spec-skill/prompts/vspec_detail/",
     "skills/visual-spec-skill/prompts/vspec_impl/",
     "skills/visual-spec-skill/prompts/vspec_new/",
+    "skills/visual-spec-skill/prompts/vspec_more_q/",
+    "skills/visual-spec-skill/prompts/vspec_mrd/",
     "skills/visual-spec-skill/prompts/vspec_plan/",
     "skills/visual-spec-skill/prompts/vspec_qc/",
     "skills/visual-spec-skill/prompts/vspec_refine/",

package/scripts/build_skill.cjs

@@ -0,0 +1,57 @@
+const { spawnSync } = require("node:child_process");
+const fs = require("node:fs");
+const path = require("node:path");
+
+function getRepoRoot() {
+  return path.resolve(__dirname, "..");
+}
+
+function readPackageJson(repoRoot) {
+  const packageJsonPath = path.join(repoRoot, "package.json");
+  return JSON.parse(fs.readFileSync(packageJsonPath, "utf-8"));
+}
+
+function ensureDir(dirPath) {
+  fs.mkdirSync(dirPath, { recursive: true });
+}
+
+function main() {
+  const repoRoot = getRepoRoot();
+  const pkg = readPackageJson(repoRoot);
+
+  const skillDir = path.join(repoRoot, "skills", "visual-spec-skill");
+  if (!fs.existsSync(skillDir)) {
+    throw new Error(`Skill dir not found: ${skillDir}`);
+  }
+
+  const distDir = path.join(repoRoot, "dist");
+  ensureDir(distDir);
+
+  const version = pkg.version || "0.0.0";
+  const outputPath = path.join(distDir, `visual-spec-skill-${version}.skill`);
+
+  if (fs.existsSync(outputPath)) {
+    fs.rmSync(outputPath);
+  }
+
+  const result = spawnSync(
+    "zip",
+    ["-r", outputPath, ".", "-x", "*.DS_Store", "-x", "*/.DS_Store"],
+    { cwd: skillDir, stdio: "inherit" }
+  );
+
+  if (result.error) {
+    throw new Error(
+      `Failed to run 'zip'. Please ensure 'zip' is installed and available in PATH. ${result.error.message}`
+    );
+  }
+
+  if (result.status !== 0) {
+    process.exit(result.status);
+  }
+
+  process.stdout.write(`${outputPath}\n`);
+}
+
+main();
+