@mcptoolshop/style-dataset-lab 2.1.0 → 2.2.0

package/README.zh.md

@@ -13,158 +13,187 @@
 
 # style-dataset-lab
 
-一个用于创建视觉数据集的生产流水线，从规范规则到结构化提示，再到 ComfyUI 生成，最终得到经过筛选、符合规范的训练数据。
+将已批准的视觉素材转化为版本控制、经过审核的数据集、分片、导出包和评估包。
 
 ## 这是什么
 
-一个用于构建结构化视觉训练数据集的**流水线**。 您可以编写风格规则（规范），编写提示，使用 ComfyUI 生成图像，并根据每个维度进行评分进行筛选，将判断结果与规范规则关联，并通过 [`@mcptoolshop/repo-dataset`](https://github.com/mcp-tool-shop-org/repo-dataset) 以 10 种格式导出。
+一个用于视觉数据规范和数据集生成的**流水线**。明确您的项目外观。根据既定规则进行筛选。生成可重复的数据集包，并确保数据分割的安全性。生成评估数据集，用于未来模型的验证。
 
-该流水线不依赖于特定的游戏。 每个游戏都有自己的数据目录，位于 `games/<name>/` 目录下；13 个脚本和空白模板是共享的。 每个生成的资源都包含以下三项：
+流水线会生成四个产出物：
 
-1. **图像像素**：由 ComfyUI 生成，包含完整的溯源信息（检查点、LoRA、种子、采样器、CFG）。
-2. **规范解释**：解释为什么该图像符合或不符合风格，并基于风格规范进行说明。
-3. **质量判断**：通过批准/拒绝，并根据每个维度的评分引用相关规则。
+| 文物。 | 它是什么。 |
+|----------|-----------|
+| **Snapshot** | 经过筛选，符合条件的记录已冻结，并进行了指纹识别。所有被选入的记录都有明确的纳入理由。 |
+| **Split** | 安全的训练/验证/测试数据集划分，防止数据泄露。共享相同主题的数据记录始终会被划分到同一个子集。 |
+| **Export package** | 自包含的数据集：包含清单、元数据、图像、数据集划分、数据集描述文档以及校验和。 |
+| **Eval pack** | 符合佳能标准的验证任务包括：车道覆盖、禁止漂移、锚点/黄金区域、主体连续性。 |
 
-## 安全模型
-
-**仅本地运行。** `style-dataset-lab` 只与本地 `localhost:8188` 上的 ComfyUI 进行通信，不会进行任何外部网络请求。 没有遥测数据，没有分析功能，不会向外部发送数据。 图像生成完全在您的 GPU 上进行。 记录和规范数据都存储在您的文件系统中。
-
-## npm 包包含的内容
-
-`npm install @mcptoolshop/style-dataset-lab` 会为您提供：
+流水线中的每个资产都包含以下三个要素：
 
-- **13 个脚本**：用于生成、筛选、比较、与规范关联、生成绘画风格图像、生成身份图像、使用 ControlNet/IP-Adapter 生成图像、批量筛选、数据迁移。
-- **空白模板**：位于 `templates/` 目录下，包含起始规范、审查标准和示例提示包。
+1. **来源信息** -- 完整的生成历史记录（检查点、LoRA、种子、采样器、配置参数、生成时间）。
+2. **合规性** -- 指示该资产是否符合相关规定，以及是否完全符合、不符合或部分符合。
+3. **质量评估** -- 采用每维度的评分标准，对质量进行评估，结果分为：通过/未通过/临界。
 
-该 npm 包**不包含**游戏数据。 如果您想使用 Star Freight 示例，请克隆该仓库（包含 1182 条记录，28 个提示集，18 个视觉类别）。
+主要从事游戏美术、角色设计、生物设计、建筑设计、车辆/机械概念设计等工作，以及任何需要保持视觉风格一致性的领域。
 
-## 安装
+## 快速入门
 
 ```bash
-# Get the pipeline scripts + templates
-npm install @mcptoolshop/style-dataset-lab
+# Install the CLI + pipeline
+npm install -g @mcptoolshop/style-dataset-lab
 
-# Or clone the repo for the Star Freight example data
-git clone https://github.com/mcp-tool-shop-org/style-dataset-lab
-cd style-dataset-lab
-npm install
+# Scaffold a new project
+sdlab init my-project --domain character-design
+
+# Validate the project structure
+sdlab project doctor --project my-project
 ```
 
-要从模板开始一个新的游戏：
+可用的领域包括：`game-art`（游戏美术）、`character-design`（角色设计）、`creature-design`（生物设计）、`architecture`（架构）、`vehicle-mech`（车辆机械设计）或`generic`（通用）。
+
+## 命令行界面
 
 ```bash
-# Copy templates into your game directory
-mkdir -p games/my-game/{records,comparisons,inputs/prompts,outputs/{candidates,approved,rejected,borderline,painterly},exports}
-cp -r templates/canon games/my-game/canon
-cp templates/inputs/prompts/example-wave.json games/my-game/inputs/prompts/wave1.json
-# Edit the canon and prompts, then generate
+sdlab init <name> [--domain <domain>]     # Scaffold a new project
+sdlab project doctor [--project <name>]   # Validate project config
+
+sdlab generate <pack> [--project <name>]  # Generate candidates via ComfyUI
+sdlab generate:identity <packet>          # Named-subject identity images
+sdlab generate:controlnet                 # ControlNet-guided generation
+sdlab generate:ipadapter                  # IP-Adapter reference-guided
+
+sdlab curate <id> <status> <explanation>  # Record review judgment
+sdlab compare <a> <b> <winner> <reason>   # Pairwise A-vs-B comparison
+sdlab bind [--project <name>]             # Bind records to constitution rules
+sdlab painterly [--project <name>]        # Post-processing style pass
+
+sdlab snapshot create [--profile <name>]  # Create frozen dataset snapshot
+sdlab snapshot list                       # List all snapshots
+sdlab snapshot diff <a> <b>               # Compare two snapshots
+sdlab eligibility audit                   # Audit record training eligibility
+sdlab split build [--snapshot <id>]       # Build train/val/test split
+sdlab split audit <id>                    # Audit split for leakage + balance
+sdlab card generate                       # Generate dataset card (md + JSON)
+sdlab export build [--snapshot <id>]      # Build versioned export package
+sdlab eval-pack build                     # Build canon-aware eval pack
 ```
 
-## 单仓库结构
+所有命令都支持 `--project <名称>` 参数，默认值为 `star-freight`。
+
+## 项目模型
 
-流水线位于 `scripts/` 和 `templates/` 目录下。 每个游戏位于 `games/<name>/` 目录下，包含自己的规范、记录和资源。 脚本接受 `--game <name>` 参数（默认为 `star-freight`）。
+每个项目都位于 `projects/` 目录下，作为一个独立的目录，拥有自己的规范、配置文件和数据。
 
 ```
-style-dataset-lab/
-  scripts/                  13 pipeline scripts (generate, curate, compare, etc.)
-  templates/                Blank starting point for new games
-    canon/                  Starter constitution + review rubric
-    inputs/prompts/         Example prompt pack
-  games/
-    star-freight/           Star Freight example (1,182 records, repo-only)
-      canon/                Style constitution, review rubric, species canon
-      records/              Per-asset JSON (provenance + judgment + canon)
-      comparisons/          A-vs-B preference judgments
-      inputs/               Prompt packs, identity packets, references
-      outputs/              Generated images (gitignored)
-      exports/              repo-dataset output (gitignored)
-    <your-game>/            Add more games with the same structure
+projects/
+  my-project/
+    project.json            Project identity + generation defaults
+    constitution.json       Rules array with rationale templates
+    lanes.json              Subject lanes with detection patterns
+    rubric.json             Scoring dimensions + thresholds
+    terminology.json        Group vocabulary + detection order
+    canon/                  Style constitution (markdown)
+    records/                Per-asset JSON (provenance + judgment + canon)
+    inputs/prompts/         Prompt packs (JSON)
+    outputs/                Generated images (gitignored)
+    comparisons/            A-vs-B preference judgments
+    snapshots/              Frozen dataset snapshots
+    splits/                 Train/val/test partitions
+    exports/                Versioned export packages
+    eval-packs/             Canon-aware eval instruments
 ```
 
-## 流水线工作流程
+## 流水线
 
-从规范到训练数据导出的完整流水线：
-
-```bash
-# 1. Write your canon -- style constitution + review rubric
-#    (start from templates/ or write from scratch)
+```
+canon → generate → curate → bind → snapshot → split → export → eval
+  |        |          |        |        |         |        |       |
+rules   ComfyUI   judgment  rules   frozen    subject  package  verify
+                                    selection isolation
+```
 
-# 2. Create prompt packs in inputs/prompts/
-#    (see templates/inputs/prompts/example-wave.json)
+1. **定义规范**：编写您的风格指南和评估标准。
+2. **生成**：ComfyUI 生成具有完整溯源信息的候选结果。
+3. **筛选**：根据每个维度的评分和失败模式，进行批准/拒绝。
+4. **关联**：将每个资源与规范规则关联，并给出通过/失败/部分通过的判定。
+5. **快照**：将符合条件的记录冻结为具有确定性和唯一标识的选择。
+6. **划分**：划分为训练集/验证集/测试集，同时进行主题隔离和类别平衡。
+7. **导出**：构建一个独立的软件包，包含清单、元数据、图像和校验和。
+8. **评估**：生成符合规范要求的测试工具，用于模型验证。
 
-# 3. Start ComfyUI and generate candidates
-npm run generate -- --game star-freight inputs/prompts/wave1.json
-npm run generate -- --game star-freight inputs/prompts/wave1.json --dry-run
+下游格式转换（例如：TRL、LLaVA、Parquet等）由[`repo-dataset`](https://github.com/mcp-tool-shop-org/repo-dataset) 负责。`sdlab` 拥有数据集的原始数据，而 `repo-dataset` 将其转换为各种特定格式。
 
-# 4. Generate identity-packet characters (named subjects)
-npm run generate:identity -- --game star-freight inputs/identity-packets/wave27a.json
+## 域名模板
 
-# 5. Curate -- approve, reject, or mark borderline
-npm run curate -- --game star-freight <asset_id> approved "explanation"
-npm run curate -- --game star-freight <asset_id> rejected "explanation" --failures "too_clean"
+每个领域模板都包含针对特定生产环境设计的车道定义、规则、评分标准和术语结构。
 
-# 6. Generate painterly variants of approved assets
-npm run painterly -- --game star-freight
+| 域名。 | 车道。 | 主要关注点。 |
+|--------|-------|-------------|
+| **game-art** | 角色、环境、道具、用户界面、飞船、内部、设备。 | 游戏中的角色轮廓、阵营区分、以及磨损/老化效果。 |
+| **character-design** | 人像、全身照、360度展示图、表情图、动作姿势图。 | 比例准确性、服装的合理性、人物性格的刻画、动作的清晰度。 |
+| **creature-design** | 概念、正字法、详细研究、动作、比例参考、栖息地。 | 解剖学上的合理性、进化逻辑、轮廓的独特性。 |
+| **architecture** | 外观、内部、街道景观、结构细节、废墟、景观。 | 结构合理性、材料一致性、视角、时代背景的协调性。 |
+| **vehicle-mech** | 外观、驾驶舱、部件、示意图、轮廓图、损坏类型。 | 机械逻辑，功能性设计语言，访问点，损坏描述。 |
 
-# 7. Bind canon explanations to curated assets
-npm run canon-bind -- --game star-freight
+## 数据集生成
 
-# 8. Record pairwise comparisons
-npm run compare -- --game star-freight <asset_a> <asset_b> a "A has better faction read"
+完整的数据集流程：快照、分割、导出、评估。
 
-# 9. Export training data via repo-dataset
-repo-dataset visual generate ./games/star-freight --format trl
-repo-dataset visual inspect ./games/star-freight
+```
+snapshot  -->  split  -->  export  -->  eval-pack
+   |            |            |             |
+  frozen     subject      package       canon-aware
+  selection  isolation    (manifest,    test instruments
+             + lane       metadata,     (4 task types)
+             balance      images,
+                          checksums,
+                          card)
 ```
 
-## 添加新的游戏
+**快照**：冻结符合条件的记录的确定性选择。每个包含记录都有其原因的追踪。配置指纹确保可重复性。
+
+**分割**：将记录分配到训练集/验证集/测试集，同时保证样本隔离（同一个样本家族不会出现在多个分割中），并实现通道平衡的分布。使用种子伪随机数生成器，确保从相同的种子生成相同的结果。
+
+**导出包**：是自包含的：清单、metadata.jsonl、图像（符号链接或复制）、分割、数据集卡（Markdown + JSON）以及 BSD 格式的校验和。 包含重建数据集所需的所有内容。
+
+**评估包**：是考虑规范的测试工具，包含四种任务类型：通道覆盖、禁止漂移、锚定/黄金标准、以及样本连续性。 它们证明数据集流程正在为未来的模型评估提供支持，而不仅仅是导出文件。
+
+通过 [`repo-dataset`](https://github.com/mcp-tool-shop-org/repo-dataset) 导出到下游格式（TRL, LLaVA, Qwen2-VL, JSONL, Parquet 等）。 `repo-dataset` 负责格式转换；`sdlab` 负责数据集的真实性。
+
+## Star Freight 示例
+
+克隆仓库以获取完整的示例：1182 条记录，28 个提示序列，5 个派系，7 个通道，24 条宪法规则，以及来自一个硬核科幻角色扮演游戏的 892 个已批准的资源。
 
 ```bash
-# Create structure and copy blank templates
-mkdir -p games/my-game/{records,comparisons,inputs/prompts,outputs/{candidates,approved,rejected,borderline,painterly},exports}
-cp -r templates/canon games/my-game/canon
-cp templates/inputs/prompts/example-wave.json games/my-game/inputs/prompts/wave1.json
+git clone https://github.com/mcp-tool-shop-org/style-dataset-lab
+cd style-dataset-lab
+
+# Validate the project
+sdlab project doctor --project star-freight
 
-# Edit your canon/constitution.md and canon/review-rubric.md
-# Edit your prompt pack, then run the pipeline with --game my-game
+# Run the full dataset spine
+sdlab snapshot create --project star-freight    # 839 eligible records
+sdlab split build --project star-freight        # ~80/10/10, zero leakage
+sdlab export build --project star-freight       # package with checksums
+sdlab eval-pack build --project star-freight    # 78 eval records
 ```
 
-## 每个游戏目录的布局
+## 从 v1.x 迁移
 
-每个 `games/<name>/` 目录包含：
+v2.0 将 `games/` 重命名为 `projects/`，并将 `--game` 重命名为 `--project`。
 
-```
-canon/                  Style constitution, review rubric, species canon, identity gates
-inputs/
-  prompts/              Prompt packs per wave (JSON: subjects, variations, defaults)
-  references/           IP-Adapter reference images
-  control-guides/       ControlNet guide overlays
-  identity-packets/     Named character identity spines
-outputs/
-  candidates/           Raw generations (gitignored)
-  approved/             Curated approved (gitignored)
-  rejected/             Curated rejected (gitignored)
-  borderline/           Curated borderline (gitignored)
-  painterly/            Painterly-style variants (gitignored)
-records/                Per-asset JSON (provenance + judgment + canon binding)
-comparisons/            A-vs-B preference judgments
-exports/                repo-dataset output (gitignored)
-```
+```bash
+# Rename your data directory
+mv games projects
 
-## 生成设置
-
-```yaml
-checkpoint: dreamshaperXL_v21TurboDPMSDE.safetensors
-lora: classipeintxl_v21.safetensors (weight: 1.0)
-resolution: 1024x1024
-steps: 8
-cfg: 2.0
-sampler: dpmpp_sde
-scheduler: karras
-speed: ~9s per image (RTX 5080)
+# --game still works with a deprecation warning (removed in v3.0)
+sdlab bind --game star-freight   # works, prints warning
+sdlab bind --project star-freight # canonical form
 ```
 
-其他生成模式：ControlNet（姿势/深度引导）、IP-Adapter（参考驱动）和身份包（用于保持角色一致性）。
+## 安全模型
+
+**仅本地。** 与运行在 `localhost:8188` 上的 ComfyUI 通信。 没有遥测，没有分析，没有外部请求。 图像保留在您的 GPU 和文件系统中。
 
 ## 要求
 

package/bin/sdlab.js

@@ -26,6 +26,12 @@ const COMMANDS = {
   'card':                '../scripts/card.js',
   'export':              '../scripts/export.js',
   'eval-pack':           '../scripts/eval-pack.js',
+  'training-profile':    '../scripts/training-profile.js',
+  'training-manifest':   '../scripts/training-manifest.js',
+  'training-package':    '../scripts/training-package.js',
+  'eval-run':            '../scripts/eval-run.js',
+  'implementation-pack': '../scripts/implementation-pack.js',
+  'reingest':            '../scripts/reingest.js',
 };
 
 // Two-word commands under "project" namespace
@@ -70,6 +76,26 @@ function printHelp() {
   console.log('  eval-pack list       List eval packs');
   console.log('  eval-pack show <id>  Show eval pack details');
   console.log('');
+  console.log('Training:');
+  console.log('  training-profile list              List training profiles');
+  console.log('  training-profile show <id>         Show training profile');
+  console.log('  training-manifest create            Create training manifest');
+  console.log('  training-manifest validate <id>     Validate manifest integrity');
+  console.log('  training-manifest show <id>         Show manifest details');
+  console.log('  training-manifest list              List all manifests');
+  console.log('  training-package build              Build trainer-ready package');
+  console.log('  training-package show <id>          Show package details');
+  console.log('  training-package list               List all packages');
+  console.log('  eval-run create                    Create eval run');
+  console.log('  eval-run score <id> --outputs <p>  Score against eval pack');
+  console.log('  eval-run show <id>                 Show eval run details');
+  console.log('  eval-run list                      List all eval runs');
+  console.log('  implementation-pack build           Build implementation example pack');
+  console.log('  implementation-pack show <id>       Show pack details');
+  console.log('  implementation-pack list            List all packs');
+  console.log('  reingest generated --source <dir>  Re-ingest generated outputs');
+  console.log('  reingest audit                     Audit re-ingested record status');
+  console.log('');
   console.log('Options:');
   console.log('  --project <name>     Project to operate on (default: star-freight)');
   console.log('  --game <name>        Deprecated alias for --project');

package/lib/adapters/diffusers-lora.js

@@ -0,0 +1,110 @@
+/**
+ * Diffusers LoRA adapter.
+ *
+ * Produces a layout compatible with diffusers fine-tuning scripts:
+ * - dataset/<partition>/ with image files
+ * - dataset/<partition>/<image>.txt caption sidecar files
+ * - metadata/<partition>.jsonl with structured rows
+ *
+ * Does not mutate inclusion or split truth.
+ */
+
+import { writeFile, mkdir, symlink, copyFile } from 'node:fs/promises';
+import { join, relative, basename } from 'node:path';
+import { existsSync } from 'node:fs';
+
+/**
+ * Build a diffusers-style caption from record metadata.
+ */
+function buildCaption(record, lane, group, profile) {
+  const parts = [];
+
+  // Trigger word for LoRA activation
+  if (profile.prompt_strategy === 'trigger-word' && profile.profile_id) {
+    parts.push(profile.profile_id.replace(/-/g, '_'));
+  }
+
+  // Subject identity if available
+  if (record.identity?.subject_name) {
+    parts.push(record.identity.subject_name.replace(/_/g, ' '));
+  }
+
+  // Faction / group
+  if (group && group !== 'unknown') {
+    parts.push(`${group} faction`);
+  }
+
+  // Lane context
+  if (lane) parts.push(lane);
+
+  // Use original prompt if available, otherwise build from ID
+  const prompt = record.provenance?.prompt;
+  if (prompt) {
+    parts.push(prompt.slice(0, 300));
+  } else {
+    parts.push(record.id.replace(/_/g, ' '));
+  }
+
+  return parts.join(', ');
+}
+
+/**
+ * Build training package in diffusers LoRA format.
+ */
+export async function buildPackage({ packageDir, partitions, profile, manifest, config, projectRoot, copy }) {
+  let imageCount = 0;
+
+  for (const [partition, records] of Object.entries(partitions)) {
+    const datasetDir = join(packageDir, 'dataset', partition);
+    const metadataDir = join(packageDir, 'metadata');
+    await mkdir(datasetDir, { recursive: true });
+    await mkdir(metadataDir, { recursive: true });
+
+    const metadataRows = [];
+
+    for (const { record, lane, group } of records) {
+      if (!record.asset_path) continue;
+
+      const sourcePath = join(projectRoot, record.asset_path);
+      if (!existsSync(sourcePath)) continue;
+
+      const filename = record.asset_path.split('/').pop();
+      const stem = filename.replace(/\.[^.]+$/, '');
+      const destPath = join(datasetDir, filename);
+
+      try {
+        if (copy) {
+          await copyFile(sourcePath, destPath);
+        } else {
+          await symlink(relative(datasetDir, sourcePath), destPath);
+        }
+        imageCount++;
+      } catch {
+        continue;
+      }
+
+      // Write caption sidecar (.txt next to image)
+      const caption = buildCaption(record, lane, group, profile);
+      await writeFile(join(datasetDir, `${stem}.txt`), caption + '\n');
+
+      metadataRows.push({
+        file: `dataset/${partition}/${filename}`,
+        caption_file: `dataset/${partition}/${stem}.txt`,
+        record_id: record.id,
+        caption,
+        lane,
+        group,
+        subject: record.identity?.subject_name || null,
+        pass_ratio: record.canon?.assertion_count > 0
+          ? +(record.canon.pass_count / record.canon.assertion_count).toFixed(3) : null,
+      });
+    }
+
+    await writeFile(
+      join(metadataDir, `${partition}.jsonl`),
+      metadataRows.map(r => JSON.stringify(r)).join('\n') + '\n'
+    );
+  }
+
+  return { imageCount };
+}

package/lib/adapters/generic-image-caption.js

@@ -0,0 +1,94 @@
+/**
+ * Generic image+caption adapter.
+ *
+ * Simple, inspectable, durable baseline:
+ * - dataset/<partition>/ with image files
+ * - metadata/<partition>.jsonl with one row per image
+ *
+ * Does not mutate inclusion or split truth.
+ */
+
+import { writeFile, mkdir, symlink, copyFile } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+import { existsSync } from 'node:fs';
+
+/**
+ * Build a caption string from a record and profile.
+ */
+function buildCaption(record, lane, group, profile) {
+  const parts = [];
+
+  if (profile.prompt_strategy === 'trigger-word' && profile.profile_id) {
+    parts.push(profile.profile_id.replace(/-/g, '_'));
+  }
+
+  if (group) parts.push(group);
+  if (lane) parts.push(lane);
+
+  // Add key provenance if available
+  const prompt = record.provenance?.prompt;
+  if (prompt) {
+    // Use first 200 chars of prompt as caption body
+    parts.push(prompt.slice(0, 200));
+  } else {
+    parts.push(record.id.replace(/_/g, ' '));
+  }
+
+  return parts.join(', ');
+}
+
+/**
+ * Build training package in generic image+caption format.
+ */
+export async function buildPackage({ packageDir, partitions, profile, manifest, config, projectRoot, copy }) {
+  let imageCount = 0;
+
+  for (const [partition, records] of Object.entries(partitions)) {
+    const datasetDir = join(packageDir, 'dataset', partition);
+    const metadataDir = join(packageDir, 'metadata');
+    await mkdir(datasetDir, { recursive: true });
+    await mkdir(metadataDir, { recursive: true });
+
+    const metadataRows = [];
+
+    for (const { record, lane, group } of records) {
+      if (!record.asset_path) continue;
+
+      const sourcePath = join(projectRoot, record.asset_path);
+      if (!existsSync(sourcePath)) continue;
+
+      const filename = record.asset_path.split('/').pop();
+      const destPath = join(datasetDir, filename);
+
+      try {
+        if (copy) {
+          await copyFile(sourcePath, destPath);
+        } else {
+          await symlink(relative(datasetDir, sourcePath), destPath);
+        }
+        imageCount++;
+      } catch {
+        continue; // skip duplicates or broken links
+      }
+
+      const caption = buildCaption(record, lane, group, profile);
+
+      metadataRows.push({
+        file: `dataset/${partition}/${filename}`,
+        record_id: record.id,
+        caption,
+        lane,
+        group,
+        pass_ratio: record.canon?.assertion_count > 0
+          ? +(record.canon.pass_count / record.canon.assertion_count).toFixed(3) : null,
+      });
+    }
+
+    await writeFile(
+      join(metadataDir, `${partition}.jsonl`),
+      metadataRows.map(r => JSON.stringify(r)).join('\n') + '\n'
+    );
+  }
+
+  return { imageCount };
+}