核心包开发Skill core-development

---

name: core-development description: 核心包开发（类型、验证、规范化、差异计算）。用于修改DSL处理逻辑或数据流时。

核心包开发

核心包 (packages/core/) 是无依赖的，处理所有DSL处理。

数据流

DSL (YAML输入) → validate() → normalize() → IR → diff() → 补丁

关键文件

文件	用途	导出内容
types.ts	类型定义	DSL*, IR*, 补丁, WebSocket协议
validate.ts	YAML验证	validate(dsl): ValidationResult
normalize.ts	DSL → IR 转换	normalize(dsl): IRDocument
diff.ts	IR差异计算	diff(prev, next): Patch

类型层次结构

DSL 类型 (用户输入)      IR 类型 (规范化后)
─────────────────────       ────────────────────
DSLDocument                 IRDocument
  ├─ version: number          ├─ version: number
  ├─ docId: string            ├─ docId: string
  ├─ title?: string           ├─ title: string
  ├─ nodes: DSLNode[]         ├─ nodes: Record<string, IRNode>
  └─ edges?: DSLEdge[]        └─ edges: Record<string, IREdge>

DSLNode                     IRNode
  ├─ id: string               ├─ id: string
  ├─ provider: string         ├─ provider: string
  ├─ kind: string             ├─ kind: string
  ├─ label?: string           ├─ label: string (默认: id)
  ├─ parent?: string          ├─ parent: string | null
  └─ layout: DSLLayout        └─ layout: { x, y, w, h }

DSLEdge                     IREdge
  ├─ id: string               ├─ id: string
  ├─ from: string             ├─ from: string
  ├─ to: string               ├─ to: string
  └─ label?: string           └─ label: string (默认: "")

补丁操作

type PatchOp =
  | { op: "upsertNode"; node: IRNode }
  | { op: "removeNode"; id: string }
  | { op: "upsertEdge"; edge: IREdge }
  | { op: "removeEdge"; id: string };

interface Patch {
  baseRev: number;
  nextRev: number;
  ops: PatchOp[];
}

WebSocket协议类型

// 插件 → CLI
interface HelloMessage {
  type: "hello";
  docId: string;
  secret?: string;
}

interface RequestFullMessage {
  type: "requestFull";
  docId: string;
}

// CLI → 插件
interface FullMessage {
  type: "full";
  rev: number;
  ir: IRDocument;
}

interface PatchMessage {
  type: "patch";
  baseRev: number;
  nextRev: number;
  ops: PatchOp[];
}

interface ErrorMessage {
  type: "error";
  message: string;
}

开发工作流

1. 修改类型 → 更新 types.ts
2. 更新验证 → 确保 validate.ts 捕获无效输入
3. 更新规范化 → 在 normalize.ts 中处理新字段/默认值
4. 更新差异计算 → 在 diff.ts 中处理新的补丁场景
5. 添加测试 → 同位置的 *.test.ts 文件
6. 运行测试 → bun test packages/core/

测试

# 所有核心测试
bun test packages/core/

# 特定测试文件
bun test packages/core/src/diff.test.ts
bun test packages/core/src/validate.test.ts
bun test packages/core/src/normalize.test.ts

# 监视模式
bun test --watch packages/core/

常见模式

添加新节点属性

1. 在 types.ts 中添加到 DSLNode 和 IRNode
2. 在 validate.ts 中添加验证
3. 在 normalize.ts 中添加默认值处理
4. 如果属性影响相等性，则更新差异计算逻辑
5. 为验证、规范化和差异计算添加测试用例

添加新边属性

1. 在 types.ts 中添加到 DSLEdge 和 IREdge
2. 在 validate.ts 中添加验证
3. 在 normalize.ts 中添加默认值处理
4. 更新边相等性检查的差异计算逻辑
5. 添加测试用例