visual-spec 0.1.0

package/docs/commands.md

@@ -0,0 +1,84 @@
+## 命令总览
+
+| 命令 | 目的 | 主要输入 | 主要输出 |
+| --- | --- | --- | --- |
+| `/vspec:new` | 从原始需求生成基础规格产物 | 原始需求文本 + 交互问答 | `/specs/`（original、stakeholder、roles、terms、flows、scenarios、scenario_details、dependencies、functions、questions）+ 初始化 `/docs/*` 归档目录 |
+| `/vspec:refine` | 基于修订材料修订需求，并同步更新细节与原型 | `/docs/refine/*`（或命令参数）+ `/specs/background/original.md`（基线）+ `/specs/details/`（前置条件） | 追加写入 `/specs/background/original.md`（变更清单 + Canonical）+ 更新受影响 `/specs/details/` 与 `/specs/prototypes/` |
+| `/vspec:refine-q` | 基于 questions 的已回答内容修订需求 | `/specs/background/original.md` + `/specs/background/questions.md` | 追加写入 `/specs/background/original.md`（采纳条目 + 变更清单 + Canonical） |
+| `/vspec:verify` | 生成模型与原型，用于快速验证 | `/specs/` 产物 | `/specs/models/*.md`、`/specs/prototypes/`（Vue + Ant Design Vue 原型、场景确认页 `scenario.html`） |
+| `/vspec:detail` | 按功能点细化需求细节 | `/specs/functions/*` + 细节/模型/角色 | `/specs/details/<function_slug>/*`（权限/交互/校验/日志/通知/MQ/导入导出/定时任务等） |
+| `/vspec:accept` | 生成验收测试用例 | 功能/场景/细节/角色/模型 | `/specs/acceptance/<function_slug>/acceptance_cases.md`、`/specs/acceptance/index.md` |
+| `/vspec:test` | 生成自动化测试代码 | 验收用例 + 仓库既有测试框架 | 写入既有测试目录或 `/tests/` |
+| `/vspec:impl` | 生成前后端集成代码 | 规格/细节/模型/依赖 | 写入仓库源码（API、后端实现、前端页面与集成） |
+| `/vspec:upgrade` | 基于旧系统材料做升级改造分析并生成新规格 | `/docs/current/file_list.md` + `/docs/legacy/*`（可选 templates/texts/assets）+ 既有 `/specs/background/original.md`（如存在） | 按 `/vspec:new` 结构生成/更新 `/specs/` + 同步技术规格到 `/scheme.yaml` |
+| `/vspec:change` | 基于变更材料做影响分析并更新产物 | `/docs/change/*`（可选 file_list.md）+ 现有产物 `/specs/` | 更新相关文件（优先 `/specs/details/<module_slug>/`）+ `/specs/change_log.md`（更新前需 git 快照提交） |
+| `/vspec:qc` | 对 `/specs/` 产物做质量检查并输出不合格清单 | 内嵌标准 + 项目 `quality_standard.md`（可选） + `/specs/` | `/specs/qc_report.md` |
+| `/vspec:plan` | 估算与排期 | 功能/角色/流程/依赖/细节 | `/specs/plan_estimate.md`、`/specs/plan_schedule.html` |
+
+## `/vspec:new`
+
+- 使用场景：需求刚拿到、信息不完整，需要快速形成统一语言与初版规格
+- 输出重点：干系人/角色/术语/流程/场景/功能清单/待确认问题
+- 目录初始化：会在项目根目录初始化 `/docs/` 及其子目录（legacy/current/change/refine/templates/texts/assets），用于材料归档与后续命令读取
+
+## `/vspec:refine`
+
+- 使用场景：需求在开发/细化过程中出现补充与修订，需要在保留可追溯的前提下，更新“当前生效需求”并同步更新细节与原型
+- 输入来源：
+  - 默认读取：`/docs/refine/`（优先 `/docs/refine/file_list.md`；否则按文件名顺序）
+  - 可选：命令参数指定文件/目录（优先级更高）
+- 前置条件：必须已存在且非空的 `/specs/details/`，否则 refine 不执行（避免只有上游需求变了、下游细节不跟导致产物失配）
+- 输出重点：
+  - 在 `original.md` 末尾追加“变更清单 + 当前生效需求（Canonical）+ 影响分析与产物更新”
+  - 更新受影响的 `/specs/details/`（优先更新既有文件）与 `/specs/prototypes/`（最小可评审 diff）
+
+## `/vspec:refine-q`
+
+- 使用场景：业务已回答 `/specs/background/questions.md`，希望将已回答内容合并回需求并形成新的生效版本
+- 输出重点：采纳的问答条目 + 变更清单 + 当前生效需求（Canonical）
+
+## `/vspec:verify`
+
+- 使用场景：希望尽快验证数据结构与页面形态，降低理解偏差
+- 输出重点：数据模型文件（实体拆分）、可运行原型、场景确认页
+
+## `/vspec:detail`
+
+- 使用场景：进入方案设计/开发前，需要把“每个功能点”拆到可实现的细节级别
+- 输出重点：RBAC 到控件级、数据权限、加载/交互/校验矩阵、提交后处理、日志/通知矩阵、MQ、导入/导出、定时任务
+
+## `/vspec:accept`
+
+- 使用场景：准备验收与交付对齐，形成可执行的用例集合
+- 输出重点：按功能点组织的验收用例表，覆盖主流程/异常/边界/权限/数据权限
+
+## `/vspec:test`
+
+- 使用场景：需要把验收用例落地为可运行的自动化测试（E2E/API/单测）
+- 输出重点：复用仓库既有测试框架与脚本，不引入新依赖
+
+## `/vspec:impl`
+
+- 使用场景：需要把规格产物转为真实可运行的前后端联调代码
+- 输出重点：接口契约、后端实现、前端页面与 API 集成、权限与状态机落地
+
+## `/vspec:change`
+
+- 使用场景：需求发生明确变更，需要可追溯地更新产物并评估影响
+- 输入来源：读取 `/docs/change/` 下材料（可选 `/docs/change/file_list.md` 作为入口按顺序读取；兼容旧路径 `/docs/changes/`）
+- 更新策略：优先更新受影响模块的明细规格目录 `/specs/details/<module_slug>/`，并按需联动 models/functions/prototypes/acceptance
+- 更新前快照：若目标仓库是 git 仓库，写入任何更新前必须先提交一次快照，便于查看本次变更 diff
+- 输出重点：结构化变更清单、影响分析表、变更日志与对应产物更新
+
+## `/vspec:upgrade`
+
+- 使用场景：基于遗留系统材料做“升级改造/重构迁移”分析，从旧内容继承并生成新的规格产物
+- 入口清单：`/docs/current/file_list.md`（不存在则先生成模板），用于列出输入文件及用途、提取要点、是否必须
+- 输入范围：通常来自 `/docs/legacy/*` 与 `/docs/current/*`，可选结合 `/docs/templates/*`、`/docs/texts/*`、`/docs/assets/*`
+- 输出重点：复用 `/vspec:new` 的产物结构生成/更新 `/specs/`，并在功能清单中标注“继承/新增/调整/废弃”
+- 技术规格同步：从“系统技术规格”输入中抽取选型并写入 `/scheme.yaml`，用于后续 `/vspec:verify` 与 `/vspec:impl`
+
+## `/vspec:plan`
+
+- 使用场景：需要对齐交付节奏，按用户故事地图拆解并排期
+- 输出重点：故事拆分与估算（人天）、迭代计划、HTML 用户故事地图

package/docs/concepts.md

@@ -0,0 +1,36 @@
+## 设计理念
+
+### 1. 以产物驱动协作
+
+- 把“讨论”转化为“可评审产物”，减少口头对齐成本
+- 产物按层次递进：原始需求 → 规格（/specs）→ 模型（/specs/models）→ 原型（/specs/prototypes）→ 细节（/specs/details）→ 验收/测试/代码
+
+### 2. 场景化拆解，而不是功能堆砌
+
+- 场景使用节点组合（apply/approve/cancel/change/execute-start/execute-end 等）覆盖主流程与回退路径
+- 通过场景驱动细节：每个功能点最终都能落到“可执行的用户动作 + 可验证的期望结果”
+
+### 3. 权限与数据权限前置
+
+- RBAC 精确到页面区域与控件，避免“页面能看但按钮不该点”的灰区
+- 数据权限独立建模（行/列/范围/状态/组织），并与 RBAC 形成组合关系（先鉴权再过滤）
+
+### 4. 可实现的细节表达
+
+- 页面加载逻辑、交互逻辑、提交后处理都用步骤清单/表格输出，便于工程实现与评审
+- 校验、日志、通知等采用“矩阵形式”，保证覆盖完整、方便回溯与对齐
+
+### 5. 最终一致性与可观测性是默认能力
+
+- 对外部依赖、MQ、重试、DLQ、补偿等给出明确规格
+- 默认要求关键事件可追踪（trace_id/request_id）、可审计（操作日志）、可告警（失败与堆积）
+
+### 6. 从验收到自动化再到集成实现
+
+- 验收用例作为开发与测试共同语言
+- 自动化测试优先复用仓库既有框架与目录约定，减少维护成本
+- 生成代码强调最小可评审差异与可运行闭环
+
+### 7. 便于变更的需求文档
+
+- 生成的需求文档强调可编辑、可阅读、易发现问题、易修正，并能快速适配需求变更。

package/docs/installation.md

@@ -0,0 +1,32 @@
+## 安装到 Trae
+
+本仓库通过脚本把内置的 Skill 目录复制到你的 Trae 配置目录下。
+
+### 前置条件
+
+- Node.js >= 14
+
+### 安装/更新（推荐）
+
+在本仓库根目录执行：
+
+```bash
+node scripts/postinstall.cjs --force --target "$HOME"
+```
+
+说明：
+
+- `--target` 指定 Trae 配置目录的根路径；脚本会安装到：`<target>/.trae/skills/starter-skill`
+- `--force` 会先删除旧目录再覆盖安装
+
+### 验证
+
+确认目录存在：
+
+- `$HOME/.trae/skills/starter-skill`
+
+### 卸载
+
+删除目录即可：
+
+- `$HOME/.trae/skills/starter-skill`

package/docs/structure.md

@@ -0,0 +1,69 @@
+# 目录结构说明
+
+本文说明两类目录结构：
+- 项目内 `/specs/` 产物目录结构：skill 在目标项目中生成的需求与设计产物
+
+
+## 目标项目目录结构
+
+skill 会在目标项目根目录生成 `/specs/` 产物（按命令阶段逐步补齐），并维护少量项目级配置与材料归档目录。典型结构如下：
+
+```text
+<your-project>/
+├─ docs/                                  # 需求材料归档目录（/vspec:new 自动创建）
+│  ├─ legacy/                             # 遗留系统材料（旧系统功能、旧权限、旧交互、旧接口说明等）
+│  ├─ current/                            # 本次新增/补充材料（新目标、差异说明、新流程、新 UI 约束等）
+│  │  └─ file_list.md                     # 升级分析入口清单（/vspec:upgrade 读取/生成）
+│  ├─ change/                             # 变更材料（/vspec:change 读取）
+│  │  └─ file_list.md                     # 变更输入入口清单（可选，存在则按顺序读取）
+│  ├─ refine/                             # 需求修订材料（/vspec:refine 读取）
+│  │  └─ file_list.md                     # 修订输入入口清单（可选，存在则按顺序读取）
+│  ├─ templates/                          # 各类模板（PRD/文案/页面/表格模板等，可选）
+│  ├─ texts/                              # 文案材料（提示语、错误文案、协议文案、消息模板等，可选）
+│  └─ assets/                             # 静态资源（设计稿/截图/原型/图片等，可选）
+├─ scheme.yaml                            # 原型工程技术栈选择（/vspec:verify 使用；不存在会自动创建默认值）
+└─ specs/
+   ├─ background/                         # 背景分析与通用资料
+   │  ├─ original.md                      # 原始需求（或等价输入）
+   │  ├─ stakeholders.md                  # 干系人
+   │  ├─ roles.md                         # 角色与任务
+   │  ├─ terms.md                         # 术语表
+   │  ├─ scenarios.md                     # 场景清单
+   │  ├─ scenario_details/                # 场景细节（按节点拆分：每节点 pre_post.md/constraints.md/variations.md/boundaries.md/symmetry.md）
+   │  ├─ dependencies.md                  # 外部依赖
+   │  └─ questions.md                     # 待确认问题清单（进入 verify 前需清零未回答/允许跳过）
+   ├─ flows/                              # 流程图（PlantUML）
+   │  └─ *.puml
+   ├─ functions/                           # 功能清单（按模块拆分）
+   │  └─ *.md
+   ├─ details/                             # 逐功能点的细节设计（/vspec:detail 输出）
+   │  └─ <module_slug>/
+   │     ├─ rbac/                          # 权限细化
+   │     ├─ data_permission/               # 数据权限
+   │     ├─ page_load/
+   │     ├─ interaction/
+   │     ├─ validation_matrix/
+   │     ├─ logging_matrix/
+   │     ├─ notification_matrix/
+   │     ├─ mq/
+   │     ├─ nfp/                           # 非功能性需求（性能/压测/安全/兼容/容错/稳定）
+   │     ├─ file_import/
+   │     ├─ file_export/
+   │     └─ cron_job/
+   ├─ models/                              # 数据模型（/vspec:verify 输出）
+   │  ├─ *.md
+   │  └─ README.md
+   ├─ prototypes/                          # 原型工程与验证页（/vspec:verify 输出）
+   │  └─ ...
+   ├─ acceptance/                          # 验收用例（/vspec:accept 输出）
+   │  ├─ index.md
+   │  └─ ...
+   ├─ qc_report.md                         # 质量检查报告（/vspec:qc 输出）
+   ├─ plan_estimate.md                     # 估算（/vspec:plan 输出）
+   ├─ plan_schedule.html                   # 排期页面（/vspec:plan 输出）
+   └─ change_log.md                        # 变更日志（/vspec:change 输出）
+```
+
+补充说明：
+- `docs/`：用于存放与本需求相关的业务材料与交付对齐资料；建议统一放入 `legacy/current/change/refine/templates/texts/assets` 等子目录，并在文件名中体现来源与版本。
+- `scheme.yaml`：用于指定 `/vspec:verify` 生成“可运行原型工程”时采用的技术栈与选项；优先读取项目根目录 `scheme.yaml`，若不存在才读取 `/specs/scheme.yaml`，两者都不存在则会创建默认的 `scheme.yaml`。

package/docs/workflows.md

@@ -0,0 +1,69 @@
+## 工作流程
+
+### 0. 准备
+
+- 在你的项目根目录（包含 `.trae/`）安装该 skill
+- 确保 `.trae/skills/starter-skill/` 已出现在项目内（安装方式见下方“安装”）
+
+### 1. 需求分析（/vspec:new）
+
+- 输入原始需求
+- 回答待确认问题（关键假设、范围、规则、依赖）
+- 得到 `/specs/` 下基础规格产物：角色/术语/流程/场景/功能清单/依赖/问题清单
+
+### 2. 方案验证（/vspec:verify）
+
+- 基于 `/specs/` 产物生成：
+  - `/specs/models/*.md`：实体与字段、关系、状态机、索引、外部字段来源
+  - `/specs/prototypes/`：Vue + Ant Design Vue 原型与 `scenario.html` 场景确认页
+- 目标：尽早暴露理解偏差，收敛到可评审方案
+
+补充：原型分段生成（可选）
+
+- 当原型规模较大或希望更可控地按链路落地时，可改用拆分命令增量生成：
+  - `/vspec:proto-apply`：聚焦申请链路页面与工作台差异
+  - `/vspec:proto-approve`：聚焦审批链路页面与工作台差异
+  - `/vspec:proto-execute`：聚焦执行链路页面（含移动端 `/m/*`）
+  - `/vspec:proto-crud`：聚焦配置/主数据类 CRUD 管理页
+
+### 3. 细节梳理（/vspec:detail）
+
+- 以 `/specs/functions/*` 为输入，逐功能点输出 `/specs/details/<function_slug>/`
+- 目标：把“需求”变成可实现的设计输入：
+  - 权限（RBAC 到控件级）与数据权限
+  - 加载/交互/校验矩阵
+  - 提交后检查/处理/跳转
+  - 日志矩阵/通知矩阵/MQ 规格/导入导出/定时任务
+
+### 4. 验收用例（/vspec:accept）
+
+- 生成验收用例到 `/specs/acceptance/`
+- 目标：明确验收口径与覆盖范围（主流程/异常/边界/权限/数据权限）
+
+### 5. 自动化测试（/vspec:test）
+
+- 读取验收用例与仓库现有测试框架
+- 生成最小可运行的 E2E/API/单元测试集合
+
+### 6. 集成开发（/vspec:impl）
+
+- 读取规格、细节、模型与依赖
+- 按仓库现有技术栈与约定生成前后端集成代码（接口契约 → 后端实现 → 前端集成）
+
+### 7. 排期规划（/vspec:plan）
+
+- 从功能与场景拆成用户故事，估算人天并按迭代排期
+- 输出：
+  - `/specs/plan.md`
+  - `/specs/story_map.html`（用户故事地图）
+
+### 8. 变更响应（/vspec:change）
+
+- 输入变更描述
+- 输出影响分析与变更日志，并同步更新受影响产物与用例
+
+## 安装（npm）
+
+- 推荐在你的项目根目录执行：`npm install <git-url>`
+- 安装完成后会将 skill 复制到：`<你的项目>/.trae/skills/starter-skill/`
+- 如需手动执行安装：`npx vreq-skill --force`

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "visual-spec",
+  "version": "0.1.0",
+  "description": "Trae skill: visual-spec-skill (/vspec:* commands) for requirement analysis, prototyping, detailing, testing, and planning.",
+  "license": "MIT",
+  "type": "commonjs",
+  "bin": {
+    "vreq-skill": "bin/vreq-skill.cjs"
+  },
+  "scripts": {
+    "postinstall": "node scripts/postinstall.cjs",
+    "install-skill": "node scripts/postinstall.cjs --force",
+    "dry-run": "node scripts/postinstall.cjs --dry-run"
+  },
+  "files": [
+    ".trae/skills/starter-skill/",
+    "bin/",
+    "docs/",
+    "scripts/",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=14"
+  }
+}

package/scripts/postinstall.cjs

@@ -0,0 +1,116 @@
+const fs = require("node:fs/promises");
+const path = require("node:path");
+
+function parseArgs(argv) {
+  const args = new Set(argv);
+  const getValue = (name) => {
+    const index = argv.indexOf(name);
+    if (index === -1) return undefined;
+    return argv[index + 1];
+  };
+  return {
+    dryRun: args.has("--dry-run"),
+    force: args.has("--force"),
+    target: getValue("--target"),
+  };
+}
+
+async function pathExists(filePath) {
+  try {
+    await fs.stat(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function removeDirRecursive(dirPath) {
+  const stat = await fs.lstat(dirPath);
+  if (!stat.isDirectory()) {
+    await fs.unlink(dirPath);
+    return;
+  }
+
+  const entries = await fs.readdir(dirPath);
+  await Promise.all(
+    entries.map(async (entry) => {
+      const entryPath = path.join(dirPath, entry);
+      await removeDirRecursive(entryPath);
+    }),
+  );
+
+  await fs.rmdir(dirPath);
+}
+
+async function copyDirRecursive(fromDir, toDir) {
+  await fs.mkdir(toDir, { recursive: true });
+  const entries = await fs.readdir(fromDir, { withFileTypes: true });
+
+  await Promise.all(
+    entries.map(async (entry) => {
+      const fromPath = path.join(fromDir, entry.name);
+      const toPath = path.join(toDir, entry.name);
+
+      if (entry.isDirectory()) {
+        await copyDirRecursive(fromPath, toPath);
+        return;
+      }
+
+      if (entry.isSymbolicLink()) {
+        const linkTarget = await fs.readlink(fromPath);
+        try {
+          await fs.unlink(toPath);
+        } catch {}
+        await fs.symlink(linkTarget, toPath);
+        return;
+      }
+
+      await fs.copyFile(fromPath, toPath);
+    }),
+  );
+}
+
+async function main() {
+  const { dryRun, force, target } = parseArgs(process.argv.slice(2));
+
+  const packageRoot = path.resolve(__dirname, "..");
+  const sourceSkillDir = path.join(packageRoot, ".trae", "skills", "starter-skill");
+  const initCwd = target || process.env.INIT_CWD || process.cwd();
+  const targetSkillDir = path.join(initCwd, ".trae", "skills", "starter-skill");
+
+  if (!(await pathExists(sourceSkillDir))) {
+    throw new Error(`Skill source directory not found: ${sourceSkillDir}`);
+  }
+
+  if (!force && path.resolve(initCwd) === packageRoot) {
+    if (!dryRun) return;
+  }
+
+  const targetSkillsDir = path.dirname(targetSkillDir);
+
+  if (dryRun) {
+    process.stdout.write(
+      [
+        "[vreq-skill] dry-run",
+        `- source: ${sourceSkillDir}`,
+        `- target: ${targetSkillDir}`,
+      ].join("\n") + "\n",
+    );
+    return;
+  }
+
+  await fs.mkdir(targetSkillsDir, { recursive: true });
+
+  const targetExists = await pathExists(targetSkillDir);
+  if (targetExists && force) {
+    await removeDirRecursive(targetSkillDir);
+  }
+
+  await copyDirRecursive(sourceSkillDir, targetSkillDir);
+  process.stdout.write(`[vreq-skill] installed to ${targetSkillDir}\n`);
+}
+
+main().catch((error) => {
+  process.stderr.write(`[vreq-skill] install failed: ${error?.message || error}\n`);
+  process.exitCode = 1;
+});