Signals 库文档说明

@type-dom/signals - TypeDOM 响应式系统核心库

📁 目录结构

libs/signals/
├── .ai/
│   └── rules/
│       ├── agent-workflow.md      # AI Agent 工作流程规则 ⭐
│       └── coding-standards.md    # Signals 编码规范 ⭐
├── AI-D2C/                      # 📚 AI 学习文档
│   ├── AI-README.md             # AI-D2C 总索引
│   ├── DOCS-NAVIGATION.md       # 完整文档导航
│   ├── SIGNALS-BASICS-GUIDE.md  # 基础入门指南
│   ├── QUICK-REFERENCE.md       # 快速参考卡片
│   ├── AI-OPTIMIZATION-GUIDE.md # 概念完全指南
│   ├── ADVANCED-PATTERNS.md     # 高级模式指南
│   ├── TRIGGER-COMPLETE-GUIDE.md # Trigger API 指南
│   ├── TROUBLESHOOTING-GUIDE.md # 问题排查指南
│   ├── AI-CODE-CHECKLIST.md     # 代码检查清单
│   ├── ADVANCED/                # 🔬 高级技术文档
│   │   └── SIGNALS_DETAILED_ANALYSIS.md # 深度技术分析
│   └── ARCHIVES/                # 📦 历史归档
│       ├── README.md
│       ├── COMPLETION-REPORT.md
│       ├── TEST-ADDITION-REPORT.md
│       └── DOCUMENT-INTEGRATION-REPORT.md
├── src/                          # 💻 源代码（仅 3 个文件）
│   ├── index.ts                 # 主入口：Signal/Computed 类 + 全部工厂函数 (524 行)
│   ├── system.ts                # 底层系统：ReactiveNode / Link / propagate (282 行)
│   └── batch.ts                 # batch() / batchEffect() 批处理封装 (33 行)
├── tests/                        # 🧪 单元测试与基准（vitest）
│   ├── api-coverage.spec.ts     # API 覆盖测试
│   ├── conformance.spec.ts      # 语义一致性测试
│   ├── bench/                   # 跨框架性能基准（32 场景 × 6 框架）
│   └── ...
├── benchmarks/                   # 📊 生成的 HTML 性能报告
└── README.md                     # 本文件

⚠️ 注意：signal.ts / computed.ts / effect.ts / types.ts / utils.ts 在当前版本中不存在。 Signal 与 Computed 以类形式定义在 src/index.ts 内。测试框架为 vitest（非 bun test）。

🎯 文档分类

Rules (规则) - .ai/rules/

目标: 指导 AI Agent 的工作流程和编码标准

包含内容:

• ✅ AI Agent 如何阅读和理解代码
• ✅ 开发流程和最佳实践
• ✅ Signal/Computed/Effect API 使用规范
• ✅ 测试编写标准和模板
• ✅ 性能优化最佳实践
• ✅ 搜索和调试技巧

当前文件:

• agent-workflow.md - AI Agent 工作流程规则
• coding-standards.md - Signals 编码规范

特点:

• 都有 trigger: always_on 元数据
• AI Agent 处理 signals 代码时自动加载
• 包含"怎么做"和"做什么"

Standards (规范) - 已整合到 Rules 中

在 signals 项目中,编码规范已整合到 coding-standards.md 中,与 agent-workflow.md 一起作为 Rules 的一部分。

这与 Claude Code 项目的模式一致:

• agent-workflow.md - 工作流程规则
• coding-standards.md - 编码规范规则

两者都有 trigger: always_on,AI Agent 会自动加载。

📖 如何使用

AI Agent 使用 Rules

当 AI Agent 处理 signals 相关代码时:

1. 自动加载: agent-workflow.md (因为有 trigger: always_on)
2. 遵循流程: 按照文档中的工作流程执行
3. 参考源码: 优先阅读 src/ 和 tests/
4. 查阅文档: 需要详细信息时参考 AI-D2C/

人类开发者使用 Standards

当人类开发者需要:

1. 学习 API: 阅读 docs/API-SPECIFICATION.md
2. 编写测试: 参考 docs/TESTING-GUIDE.md
3. 优化性能: 查看 docs/PERFORMANCE-GUIDE.md
4. 理解架构: 阅读 docs/ARCHITECTURE.md
5. 深入原理: 研究 docs/IMPLEMENTATION-DETAILS.md

🔗 快速链接

Rules (AI Agent)

• agent-workflow.md - AI Agent 工作流程规则
• coding-standards.md - Signals 编码规范

Standards (人类开发者)

已整合到 Rules 中,通过 coding-standards.md 提供:

• ✅ API 使用规范
• ✅ 测试编写标准
• ✅ 性能优化指南
• ✅ 常见陷阱和反模式

源码（仅 3 个文件）

• src/index.ts - 主入口：Signal/Computed 类 + 全部工厂函数（524 行）
• src/system.ts - 底层系统：ReactiveNode / Link / propagate（282 行）
• src/batch.ts - batch() / batchEffect() 批处理封装（33 行）

测试（vitest，非 bun test）

• tests/api-coverage.spec.ts - API 覆盖测试
• tests/conformance.spec.ts - 语义一致性测试
• tests/effect.spec.ts - Effect 测试
• tests/effectScope.spec.ts - EffectScope 测试
• tests/batch.spec.ts - Batch / batchEffect 测试
• tests/trigger.spec.ts - Trigger 测试
• tests/bench/ - 跨框架性能基准（32 场景 × 6 框架）

📊 性能基准报告（跨框架对比）

数据来源：tests/cross-framework.bench.ts + tests/cross-framework.report.ts，由 nx run signals:bench-report 生成的 benchmarks/report-*.html。 下文为 2026-08-28T13-04-17 一次运行的快照，共 32 个场景，对比 6 个响应式框架。 数值单位 hz（每秒操作数，越高越好）。

运行方式

# 生成 HTML 报告（含数据矩阵、内存表、总结评价）
nx run signals:bench-report
# 等同于 vitest run --config vitest.report.mts

总览（综合排名）

| 框架 | 胜场（32 场景） | 平均名次 | 几何均值速度 | |------|:---:|:---:|:---:| | @type-dom/signals | 28 | 1.3 | 0.964 | | @preact/signals-core | 1 | 2.3 | 0.667 | | alien-signals | 3 | 2.7 | 0.611 | | @vue/reactivity | 0 | 4.3 | 0.325 | | solid-js | 0 | 4.9 | 0.172 | | mobx | 0 | 5.7 | 0.099 |

signals 在 32 个场景中拿下 28 项第一（胜率 87.5%），且从不垫底，是测试集里综合最快的框架。

性能数据矩阵（hz，越高越好）

| 场景 | @type-dom/signals | @vue/reactivity | @preact/signals-core | alien-signals | solid-js | mobx | 第一名 | |------|---:|---:|---:|---:|---:|---:|:---:| | createSignals: create 1000 signals | 25,296 | 15,280 | 26,815 | 26,479 | 19,956 | 9,669 | @preact/signals-core | | updateSignals: 10000 writes (no subscribers) | 155,165 | 6,871 | 16,066 | 27,909 | 13,700 | 3,596 | @type-dom/signals | | noOpWrites: 10000 writes of same value (short-circuit) | 193,567 | 6,966 | 26,241 | 12,980 | 14,739 | 4,325 | @type-dom/signals | | readSignals: 10000 reads | 83,799 | 25,732 | 29,084 | 27,371 | 22,965 | 22,968 | @type-dom/signals | | createComputations: build 100-deep computed chain | 170,130 | 107,890 | 159,375 | 154,884 | 69,676 | 23,639 | @type-dom/signals | | computedRecompute: 10000 cold recomputes (cache miss) | 2,069 | 786 | 1,476 | 1,633 | 223 | 174 | @type-dom/signals | | computedCache: 10000 cached reads | 68,005 | 13,358 | 14,845 | 14,259 | 9,005 | 1,608 | @type-dom/signals | | untrackedReads: 10000 untracked reads | 9,226 | 1,261 | 5,849 | 2,007 | 5,892 | 2,164 | @type-dom/signals | | diamond: A → (B, C) → D, 1000 cycles | 12,184 | 6,551 | 11,534 | 7,711 | 1,481 | 1,171 | @type-dom/signals | | triangle: glitch-free redundant edge, 1000 cycles | 16,269 | 9,681 | 14,851 | 9,942 | 2,409 | 1,886 | @type-dom/signals | | broadPropagation: 1 → 100 computeds fan-out | 5,020 | 2,606 | 3,760 | 2,737 | 791 | 1,372 | @type-dom/signals | | deepPropagation: 100-level chain updates | 4,182 | 2,562 | 3,600 | 3,433 | 547 | 303 | @type-dom/signals | | mux: two signals fan-in, 1000 cycles | 7,911 | 3,646 | 6,865 | 5,343 | 942 | 830 | @type-dom/signals | | avoidablePropagation: constant computed cuts propagation | 20,978 | 8,884 | 19,414 | 14,347 | 3,085 | 2,553 | @type-dom/signals | | molBench: ring of 10 atoms, 1000 cycles | 3,156 | 1,261 | 1,647 | 1,873 | 465 | 107 | @type-dom/signals | | cellx1000: 1000-deep computation chain, 100 cycles | 372 | 272 | 349 | 353 | 53 | 30 | @type-dom/signals | | effectFanout: 1 signal → 100 effects, 1000 writes | 456 | 283 | 324 | 300 | 101 | 52 | @type-dom/signals | | dynamicDeps: branch switch, 1000 cycles | 5,207 | 2,394 | 4,873 | 3,844 | 813 | 670 | @type-dom/signals | | randomGraph: 10x10x5, lazy 80%, 200 cycles | 5,004 | 2,644 | 4,313 | 3,973 | 866 | 164 | @type-dom/signals | | randomGraph: 10x10x5, dyn 25%, lazy 80%, 200 cycles | 4,859 | 2,220 | 4,368 | 3,972 | 794 | 674 | @type-dom/signals | | randomGraph: 6x20x5, dyn 50%, lazy 50%, 100 cycles | 3,913 | 1,951 | 3,622 | 3,263 | 598 | 514 | @type-dom/signals | | unstable: 1 source switches routed deps every cycle | 5,900 | 2,579 | 4,782 | 4,126 | 927 | 738 | @type-dom/signals | | batchedWrites: batch of 100 writes → 1 flush | 568,988 | 5,372 | 314,996 | 354,134 | 100,583 | 134,718 | @type-dom/signals | | nestedBatch: 10 inner batches x 5 writes | 850,996 | 20,166 | 543,883 | 585,805 | 187,289 | 201,469 | @type-dom/signals | | repeatedObservers: create + dispose 1000 effects | 13,196 | 6,915 | 14,922 | 18,850 | 2,222 | 1,453 | alien-signals | | effectScope: create 1000 effects in scope, dispose once | 10,373 | 8,739 | 13,408 | 14,839 | 1,971 | 1,541 | alien-signals | | [LARGE] churn: create + dispose 100000 effects (GC pressure) | 129 | 70 | 140 | 194 | 22 | 16 | alien-signals | | [LARGE] deepChain: 1000-level chain, 30 cycles | 1,231 | 791 | 1,124 | 1,043 | 177 | 99 | @type-dom/signals | | [LARGE] wideFanout: 1 → 1000 computeds, 30 cycles | 1,312 | 897 | 1,107 | 888 | 259 | 446 | @type-dom/signals | | [LARGE] bigGraph: 20x100x4, dyn 10%, 30 cycles | 4,251 | 2,333 | 3,059 | 3,634 | 1,010 | 148 | @type-dom/signals | | [LARGE] effectFanout: 1 signal → 1000 effects, 100 writes | 387 | 256 | 311 | 302 | 91 | 50 | @type-dom/signals | | [LARGE] wideGraph: 25x1000x5, dyn 5%, 10 cycles | 486 | 262 | 375 | 407 | 97 | 29 | @type-dom/signals |

内存占用（每对象堆字节 + 规模峰值，越小越好）

| 框架 | 每 Signal | 每 Effect | 10 万 Signal 峰值 | |------|---:|---:|---:| | @type-dom/signals | 371.5 B | 598.5 B | −16.1 MB | | @vue/reactivity | 379.7 B | 786.8 B | −3.9 MB | | @preact/signals-core | 306.1 B | 406.0 B | −210.3 MB | | alien-signals | 345.2 B | 592.8 B | 3.1 MB | | solid-js | 426.4 B | 1270.4 B | 11.4 MB | | mobx | 562.7 B | 764.7 B | 32.5 MB |

⚠️ 「10 万 Signal 峰值」列基于 process.memoryUsage().heapUsed 前后差值，受 V8 GC 时机影响噪声较大（负值即采样期间发生回收），仅作量级参考；「每 Signal / 每 Effect」列取 3 次平均更可靠。signals 每 Signal 371.5 B 与 alien 345.2 B 仅差 ~9%，差距被 Link 连接边开销稀释。

总结与对 @type-dom/signals 的评价

结论：综合最强梯队。 在 32 个场景中拿下 28 项第一（胜率 87.5%），几何均值速度全场最高，平均名次 1.3，从不垫底，是测试集中综合最快的框架。

核心优势（碾压级）：

• 写入 / 批处理：updateSignals 是 Vue 的 21×、MobX 的 43×；batchedWrites 是 Vue 的 125×，nestedBatch 是 Vue 的 47×。Signal.set 的 if (this.pendingValue !== value) 同值短路在 noOpWrites 直接体现（193,567 hz，是 Vue 的 24×、alien 的 15×）。
• computed 计算：createComputations / computedRecompute / computedCache 全部第一；缓存命中是 MobX 的 35×、Vue 的 5.6×。
• 图传播 / 大规模：diamond / triangle / mux / molBench / 随机动态图 / deepChain / wideFanout / bigGraph / wideGraph 全胜；[LARGE] bigGraph 是 MobX 的 28×，规模越大优势越明显。
• 动态依赖：dynamicDeps 及全部随机图场景第一，相对第二名约 1.2× 稳定优势；unstable（依赖图重建）也第一。

真实短板（仅相对理论最优，非工程缺陷）：

• GC 压力：Lifecycle 三场景系统性落后 alien-signals——repeatedObservers 1.34×、effectScope 1.52×、[LARGE] churn（10 万次创建+销毁）1.65×。根因是类实例模型（Signal/Computed/EffectNode 必进堆）vs alien 的字面量（可被逃逸分析栈分配）。但相对 Vue/Preact/MobX 仍占优（churn 是 Preact 的 1.2×、Vue 的 1.6×）。
• 超深链：cellx1000（1000 层）以 372 hz 小幅落后 Preact 的 349（约 1.06×）——唯一被非 alien 框架反超的场景，极深链逐层传播有微小优化空间。
• 内存自动化：内存已纳入自动化（每 Signal 371.5 B，alien 345.2 B，差 ~9%；10 万 Signal 峰值见上表），但 GC 次数 / 对象存活时长等长周期指标仍依赖手动采样，未做分代统计。

结论：@type-dom/signals 是一套生产级、综合最强的响应式库：写入、批处理、计算缓存、图传播与大规模场景全面碾压 Vue / Preact / MobX / Solid，且从不垫底。其唯一相对弱点是高频创建+销毁的 GC 压力（类实例 vs 字面量），以及极深链传播的微小落后——这两点相对主流框架依然占优，属于「与理论最优实现的差距」而非工程缺陷。后续优化应优先聚焦 Lifecycle / churn 场景的对象分配与回收（约 1.65× 差距）。

⚠️ 注：alien-signals 用纯字面量节点（可被 V8 逃逸分析栈分配），在高频创建+销毁场景 GC 压力更小；signals 用 Signal/Computed 类实例换取类型安全与生产可维护性，代价是单次创建/销毁成本略高。两者定位不同：alien = 算法参考实现，signals = 带生产级优化的完整库。

💡 核心原则

Rules vs Standards 的关系

在 signals 项目中,Rules 包含 Standards:

| 文件 | 内容类型 | trigger | |------|---------|--------| | agent-workflow.md | 工作流程规则 | ✅ always_on | | coding-standards.md | 编码规范规则 | ✅ always_on |

两者都是 Rules,都有 trigger,AI Agent 都会自动加载。

这与 Claude Code 项目的模式一致。

📝 维护指南

添加新的 Rule 文件

1. 在 .ai/rules/ 创建 .md 文件
2. 必须添加 trigger: always_on 元数据
3. 聚焦特定主题 (如: testing-guide.md, performance-tips.md)
4. 保持与现有文件职责不重叠

更新现有 Rules

• agent-workflow.md: 更新工作流程、策略、技巧
• coding-standards.md: 更新 API 规范、测试标准、最佳实践
• 保持两者职责清晰,不重叠

文档组织原则

• 小而专注: 每个文件聚焦一个主题
• 交叉引用: 相关文档互相链接
• 易于查找: 清晰的命名和结构

🚀 下一步计划

短期 (1-2 周)

• [ ] 创建 docs/API-SPECIFICATION.md
• [ ] 创建 docs/TESTING-GUIDE.md
• [ ] 验证 AI Agent 正确加载 rules

中期 (1-2 月)

• [ ] 创建 docs/PERFORMANCE-GUIDE.md
• [ ] 创建 docs/ARCHITECTURE.md
• [ ] 创建 docs/IMPLEMENTATION-DETAILS.md

长期 (持续)

• [ ] 根据反馈优化 rules
• [ ] 完善 standards 文档
• [ ] 保持文档与代码同步

最后更新: 2026-04-07
维护者: TypeDOM Core Team