System Design Workbench 1.0 是一个 Agent-first、离线优先的文档转换与系统设计证据工具。Agent 可以把多份 Markdown、文本或结构化资料组织成受约束的 manifest，确定性生成可搜索 HTML、Markdown、结构化 bundle 和验证 receipt；原有系统设计画布、分析、评分与故障推演继续保留。
它不内置 LLM，也不声称首段提取就是语义理解。Agent 负责选择材料、组织阅读路线并明确写入总结；工具负责路径安全、来源追踪、确定性转换和人类阅读展示。系统设计分数仍只是透明启发式，不是生产容量证明。
- Agent-first
transformCLI：多文档 manifest →bundle.json、report.md、report.html、receipt.json。 - 文档角色、阅读顺序、Agent 摘要/要点与可追溯 source-extract fallback。
- root 内路径、realpath/symlink、扩展名、文件数与字节数安全门；默认拒绝覆盖已有派生文件。
- 零依赖独立 HTML：全文筛选、角色筛选、折叠章节、来源复制、移动端和打印视图。
- 成功与失败均输出单一 JSON envelope；支持机器可读版本和 transform schema 查询。
- 三个原创练习场景：短链接、通知流水线、多模型 AI 网关。
- 可在 JSON 中嵌入经过 allowlist 校验的自定义场景、速率单位和成本单位。
- 可拖动组件画布、方向连线、流量比例和节点属性编辑。
- 可区分关键/非关键节点与必需/可选连线，避免旁路失败被误算成全系统不可用。
- 确定性流量传播、容量热点、关键路径延迟、可靠性和成本启发式分析。
- 使用固定种子的单节点/单副本故障推演，相同输入得到相同结果。
- 需求、拓扑、容量、可靠性、决策证据五维透明评分；每一分都能追到规则。
- 面试阶段 checklist 与“选择—备选—理由”权衡日志。
- 本地自动保存，严格校验 JSON 导入，支持撤销/重做。
- JSON、Mermaid 和带思考题的 Markdown 证据报告导出。
- 无运行时依赖的 Node CLI，便于脚本、CI 和其他知识仓库复用。
要求 Node.js 20 或更高版本。
npm install --ignore-scripts
node bin/sdw.mjs version
node bin/sdw.mjs schema transform
node bin/sdw.mjs transform examples/reading-bundle.json \
--root . \
--output .tmp/reading-example打开 .tmp/reading-example/report.html 即可阅读。完整 manifest、安全和证据合同见 document-transform-contract.md。
浏览器系统设计练习台仍可运行：
npm run dev浏览器打开 http://127.0.0.1:4173。项目没有第三方运行时依赖；npm install 只用于核对锁文件与标准工作流。
运行检查：
npm test
npm run checkAgent 转换入口：
node bin/sdw.mjs transform <manifest.json> --root <document-root> --output <directory>
node bin/sdw.mjs schema transform
node bin/sdw.mjs version系统设计兼容入口：
node bin/sdw.mjs validate examples/url-shortener.json
node bin/sdw.mjs score examples/url-shortener.json
node bin/sdw.mjs mermaid examples/url-shortener.json
node bin/sdw.mjs report examples/url-shortener.json
node bin/sdw.mjs incident examples/url-shortener.json --node cache
node bin/sdw.mjs score examples/custom-content-pipeline.json命令行为：
| 命令 | 输出 | 适合场景 |
|---|---|---|
transform |
单一 JSON 收据 + 四文件阅读包 | Agent 批量转换文档给人阅读 |
schema transform |
manifest 协议 JSON | Agent 构造输入前发现合同 |
version |
产品版本 JSON | 宿主兼容性检查 |
validate |
schema、节点和连线摘要 | 提交前门禁 |
score |
机器可读 JSON | CI、学习进度对比 |
mermaid |
文本架构图 | Markdown、Wiki |
report |
完整 Markdown 证据报告 | 复盘、评审、提问 |
incident |
可重复的基线/退化 JSON | 定点或固定 seed 故障推演 |
- 选择场景并先写流量、延迟、可用性与预算约束。
- 从客户端入口开始，只加入当前数据流需要的组件。
- 给每条分支设置流量比例，调整容量、延迟、副本与成本假设。
- 查看热点与评分规则；不要为了得分盲目堆组件。
- 记录至少两条权衡，每条都写出被放弃的备选与代价。
- 运行故障推演，解释退化路径和恢复策略。
- 导出 JSON 作为源真相，导出 Markdown/Mermaid 作为可重建证据。
flowchart LR
Docs["Agent 选择的多份文档"] --> Manifest["受约束 manifest"]
Manifest --> Readable["JSON / Markdown / HTML / receipt"]
Scenario["原创场景与约束"] --> Design["版本化 JSON 设计"]
UI["静态浏览器 UI"] --> Design
CLI["Node CLI"] --> Design
Design --> Validate["严格校验与归一化"]
Validate --> Analyze["确定性启发式分析"]
Analyze --> Score["透明规则评分"]
Analyze --> Export["JSON / Mermaid / Markdown"]
Score --> Export
核心模块保持与 UI 分离：
src/model.js：schema、组件目录、创建与导入校验。src/analyzer.js：可达图、流量传播、容量/延迟/可靠性估算、故障推演。src/scoring.js：五个各 20 分的可解释规则。src/exporters.js：确定性派生工件。src/document-bundle.js：manifest 校验、可追溯文本提取与阅读模型。src/transform.js：root 边界、文件读取、原子写入和 receipt。src/reading-exporters.js：独立 Markdown/HTML 阅读视图。src/app.js：浏览器状态、画布交互、本地保存和导入导出。bin/sdw.mjs：不依赖浏览器的复用入口。
当前分析有意采用简单、透明的模型：
- 副本容量按线性扩展估算；未模拟锁竞争、共享依赖、数据倾斜或分片热点。
- 每条边按
trafficPercent转发流量；分支总和可以低于或高于 100%，用来表达过滤或放大。 required=false的连线不进入关键延迟/可靠性路径；端到端 SLO 由关键且没有必需下游的端点决定。可选分支仍保留流量、成本和局部瓶颈。- 延迟使用确定性排队压力近似；没有采样真实延迟分布。
- 可用性假设副本故障相互独立；没有共同故障域和相关性模型。
- 有环图只报告环，不伪造未计算部分的结果。
因此：构建通过只证明软件门禁；评分变化只证明规则结果；真实架构仍需要压测、故障注入、成本账单和业务验收。
本项目来自对系统设计内容库、课程、模式目录、模拟器、图编辑器和学习平台的横向研究。具体吸收矩阵、许可证约束和放弃项见 research-to-design.md。
所有场景、文案、schema、分析器和 UI 都是独立实现。未复制 CC BY-NC-ND 内容、无许可证项目代码或限制性许可证项目实现。
本项目不要求宿主引入前端依赖。宿主保存 document manifest 或 design JSON，并按需调用 CLI 生成阅读包、检查结果或设计报告。intern-journal 的具体接入方式见 intern-journal-integration.md。
- 不提供账户、云同步、付费、排行榜或多人实时协作。
- 不在工具内部调用 LLM，也不把自动提取文本冒充 Agent 总结。
- 不把整仓所有文件默认交给转换器；Agent 必须提交有限 manifest。
- 不用 LLM 给架构打黑盒分；未来接入 AI 也必须保留本地确定性规则作为基线。
- 不托管或复制第三方系统设计文章。
- 不模拟数据库一致性协议、队列内部实现或真实云厂商定价。
- 不把面试评分当作工程师能力认证。