Name: 核心包开发Skill
Rating: 5 (11 reviews)
Author: aiskillstore


名称	core-development
描述	核心包开发工作（类型、验证、规范化、差异计算）。用于修改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;
}

开发工作流

修改类型 → 更新 types.ts
更新验证 → 确保 validate.ts 捕获无效输入
更新规范化 → 在 normalize.ts 中处理新字段/默认值
更新差异计算 → 在 diff.ts 中处理新的补丁场景
添加测试 → 同目录下的 *.test.ts 文件
运行测试 → 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/

常见模式

添加新节点属性

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

添加新边属性

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