feat: 初始化 miot_x TypeScript 工作流构建器项目

openspec/config.yaml

@@ -0,0 +1,21 @@
+schema: spec-driven
+
+context: |
+  - 使用中文（注释、文档、交流），面向中文开发者
+  - openspec文档的关键字按openspec规范使用，不要翻译为中文
+  - **优先阅读README.md**获取项目结构与开发规范，所有代码风格、命名、注解、依赖、API等规范以README为准
+  - 涉及模块结构、API、实体等变更时同步更新README.md
+  - 新增代码优先复用已有组件、工具、依赖库，不引入新依赖
+  - 新增的逻辑必须编写完善的测试，并保证测试的正确性，不允许跳过任何测试
+  - Git提交: 仅中文; 格式"类型: 简短描述", 类型: feat/fix/refactor/docs/style/test/chore; 多行描述空行后写详细说明
+  - 禁止创建git操作task
+  - 积极使用subagents精心设计并行任务，节省上下文空间，加速任务执行
+  - 优先使用提问工具对用户进行提问
+
+rules:
+  proposal:
+    - 仔细审查每一个过往spec判断是否存在Modified Capabilities
+  design:
+    - 先前的讨论技术方案要尽可能体现在设计文档中，便于指导实现阶段不偏离已定的技术路线
+  task:
+    - 一行一个任务，严禁任务内容跨行

openspec/specs/typescript-workflow-authoring/spec.md

@@ -0,0 +1,111 @@
+# Capability: TypeScript Workflow Authoring
+
+## Purpose
+
+Allow users to author 米家极客版 (Mi Home Geek Edition) workflow rules using TypeScript files and a builder API, compile them into backup JSON, and package them as `.bak` files — with validation diagnostics and conservative merge semantics.
+
+## Requirements
+
+### Requirement: TypeScript 规则编写
+系统 SHALL 允许用户在 TypeScript 文件中通过导出的 builder API 定义米家极客版工作流规则，不需要额外的纯文本 DSL 解析器。
+
+#### Scenario: 单文件规则定义
+- **WHEN** 用户在一个 TypeScript 规则文件中定义设备并导出一条规则
+- **THEN** 系统 SHALL 将导出的规则定义加载为工作流编译输入
+
+#### Scenario: 多文件规则定义
+- **WHEN** 用户通过入口模块从多个 TypeScript 文件导出多条规则定义
+- **THEN** 系统 SHALL 将所有导出的规则定义加载为工作流编译输入
+
+### Requirement: 显式设备与能力引用
+系统 SHALL 要求第一版工作流定义使用显式 `did` 和 `urn` 引用设备，并根据能力类型使用显式 `siid/piid/eiid/aiid` 字段引用 MIoT 能力。
+
+#### Scenario: 设备引用包含身份字段
+- **WHEN** 规则使用包含 `did` 和 `urn` 的设备引用
+- **THEN** 编译器 SHALL 在生成的设备节点及其 `cfg.urn` 中使用这些值
+
+#### Scenario: 缺少显式设备身份
+- **WHEN** 规则引用的设备缺少 `did` 或缺少 `urn`
+- **THEN** 编译器 MUST 失败，并给出能定位无效设备引用的诊断信息
+
+### Requirement: 简单设备工作流节点
+系统 SHALL 支持将简单设备工作流操作编译为米家极客版节点 JSON，包括属性触发、事件触发、属性读取、属性写入和动作调用。
+
+#### Scenario: 属性触发后写入属性
+- **WHEN** TypeScript 规则定义设备属性触发，并在触发后执行设备属性写入动作
+- **THEN** 编译器 SHALL 生成一个 `deviceInput` 节点，并通过正确模板端口连接到一个 `deviceOutput` 节点
+
+#### Scenario: 事件触发后调用动作
+- **WHEN** TypeScript 规则定义设备事件触发，并在触发后调用设备动作
+- **THEN** 编译器 SHALL 生成包含 `eiid` 的 `deviceInput` 节点和包含 `aiid` 的 `deviceOutput` 节点
+
+#### Scenario: 动作前检查属性条件
+- **WHEN** TypeScript 规则定义触发器，并在动作前增加设备属性条件
+- **THEN** 编译器 SHALL 生成 `deviceGet` 节点，并将满足条件的输出路径连接到下游动作
+
+### Requirement: 简单逻辑组合
+系统 SHALL 支持第一版工作流中的简单逻辑组合，包括多触发合并、逻辑与、逻辑或、逻辑非和延时。
+
+#### Scenario: 多触发合并
+- **WHEN** 规则定义多个触发器并要求它们启动同一个动作链
+- **THEN** 编译器 SHALL 生成具备足够输入端口的 `signalOr` 节点，并将其输出连接到共享下游链路
+
+#### Scenario: 逻辑条件组合
+- **WHEN** 规则基于受支持的条件节点定义 `all`、`any` 或 `not` 条件
+- **THEN** 编译器 SHALL 生成具有合法输入输出端口的 `logicAnd`、`logicOr` 或 `logicNot` 节点
+
+#### Scenario: 延时动作链
+- **WHEN** 规则在动作前定义延时
+- **THEN** 编译器 SHALL 生成包含 `props.timeout` 和对应 `cfg` 展示字段的 `delay` 节点
+
+### Requirement: 备份 JSON 生成
+系统 SHALL 将工作流定义编译为米家极客版备份 JSON，并满足已知规则与节点导入结构要求。
+
+#### Scenario: 规则 JSON 形态
+- **WHEN** 工作流规则被编译
+- **THEN** 生成的规则 SHALL 包含字符串 `id`、与其匹配的 `cfg.id`、布尔值 `cfg.enable`、规则 `cfg.userData` 和 `nodes` 数组
+
+#### Scenario: 节点 JSON 形态
+- **WHEN** 任一受支持节点被生成
+- **THEN** 该节点 SHALL 包含字符串 `id`、字符串 `type`、对象 `props`、对象 `inputs`、对象 `outputs`、对象 `cfg` 和整数 `cfg.version`
+
+#### Scenario: 连接 JSON 形态
+- **WHEN** 图边被输出到备份 JSON 中
+- **THEN** 每条输出连接 SHALL 使用 `targetNodeId.targetPortName` 字符串格式，并指向存在的节点输入端口
+
+### Requirement: 备份文件打包输出
+系统 SHALL 使用已知文件外壳将生成的备份 JSON 打包为米家极客版 `.bak` 文件。
+
+#### Scenario: 备份文件编码
+- **WHEN** 系统写出备份文件
+- **THEN** 文件 SHALL 以字节 `0x98 0x80 0x01 0x00` 开头，随后写入 raw deflate 压缩后的 UTF-8 JSON
+
+#### Scenario: 备份往返一致
+- **WHEN** 系统解包一个已生成的备份文件
+- **THEN** 解包得到的 JSON SHALL 与压缩前的编译结果 JSON 一致
+
+### Requirement: 保守备份合并
+系统 SHALL 默认保留现有备份内容，只新增或显式替换用户选择的工作流规则。
+
+#### Scenario: 追加生成规则
+- **WHEN** 用户基于现有备份编译新规则且未指定替换策略
+- **THEN** 系统 SHALL 保留所有已有规则，并追加生成的规则
+
+#### Scenario: 按显式身份替换规则
+- **WHEN** 用户指定生成规则按 ID 或唯一名称替换已有规则
+- **THEN** 系统 SHALL 只替换匹配规则，并保持无关规则不变
+
+### Requirement: 校验诊断
+系统 SHALL 在写出最终 `.bak` 前校验生成的工作流，并为无效结构报告可操作的诊断信息。
+
+#### Scenario: 非法节点 ID
+- **WHEN** 生成或用户指定的节点 ID 包含 `0-9a-zA-Z` 之外的字符
+- **THEN** 校验 MUST 失败，并给出能定位非法节点的诊断信息
+
+#### Scenario: 非法连接目标
+- **WHEN** 生成连接指向不存在的节点或不存在的输入端口
+- **THEN** 校验 MUST 失败，并给出能定位非法连接的诊断信息
+
+#### Scenario: 设备资源中不存在的设备
+- **WHEN** 工作流引用的 `did` 不存在于配置的 `devices.json` 资源中
+- **THEN** 校验 MUST 根据所选严格模式失败或警告，且诊断信息 SHALL 包含缺失的 `did`