system-design-primer-skill 1.2.0 → 2.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (128) hide show
  1. package/README.md +114 -60
  2. package/SKILL.md +437 -93
  3. package/VERSION +1 -1
  4. package/evals/README.md +1022 -0
  5. package/evals/system-design-cases.json +414 -0
  6. package/package.json +46 -4
  7. package/references/03-data-and-storage.md +8 -2
  8. package/references/04-caching.md +3 -3
  9. package/references/05-async-and-messaging.md +4 -0
  10. package/references/06-distributed-systems.md +2 -2
  11. package/references/07-reliability-and-resilience.md +7 -3
  12. package/references/08-api-security-observability.md +4 -0
  13. package/references/10-workflows-and-checklists.md +1 -1
  14. package/references/13-architecture-intelligence.md +91 -0
  15. package/references/14-api-and-data-contracts.md +80 -0
  16. package/references/15-failure-analysis.md +88 -0
  17. package/references/16-multi-agent-architecture.md +76 -0
  18. package/references/17-agent-harness-and-runtime.md +87 -0
  19. package/references/18-mcp-architecture.md +67 -0
  20. package/references/19-agent-security-and-permissions.md +90 -0
  21. package/references/20-agent-state-and-memory.md +76 -0
  22. package/references/21-agent-evaluation-and-observability.md +90 -0
  23. package/references/22-kubernetes-and-container-platforms.md +29 -0
  24. package/references/23-service-mesh-and-traffic-management.md +21 -0
  25. package/references/24-multi-region-and-disaster-recovery.md +28 -0
  26. package/references/25-platform-engineering-and-developer-experience.md +26 -0
  27. package/references/26-finops-and-cloud-cost.md +29 -0
  28. package/references/27-production-observability-and-slo.md +33 -0
  29. package/references/28-event-streaming-and-kafka-pulsar.md +33 -0
  30. package/references/29-event-sourcing-and-cqrs.md +23 -0
  31. package/references/30-change-data-capture-and-debezium.md +27 -0
  32. package/references/31-data-lakehouse-and-stream-batch.md +24 -0
  33. package/references/32-workflow-orchestration-and-temporal.md +28 -0
  34. package/references/33-schema-registry-and-event-governance.md +22 -0
  35. package/references/34-postgresql-internals-and-performance.md +45 -0
  36. package/references/35-mysql-innodb-and-performance.md +29 -0
  37. package/references/36-sharding-and-distributed-sql.md +22 -0
  38. package/references/37-consensus-and-distributed-transactions.md +29 -0
  39. package/references/38-search-architecture-elasticsearch-opensearch.md +24 -0
  40. package/references/39-vector-databases-and-hybrid-retrieval.md +31 -0
  41. package/references/40-zero-downtime-database-migrations.md +27 -0
  42. package/references/41-api-gateway-and-edge-architecture.md +23 -0
  43. package/references/42-rest-api-design-and-lifecycle.md +23 -0
  44. package/references/43-graphql-architecture-and-governance.md +16 -0
  45. package/references/44-grpc-and-service-contracts.md +16 -0
  46. package/references/45-websocket-sse-and-realtime-systems.md +16 -0
  47. package/references/46-realtime-collaboration-ot-crdt.md +16 -0
  48. package/references/47-api-security-rate-limiting-and-abuse.md +16 -0
  49. package/references/48-oauth-oidc-and-passkeys.md +20 -0
  50. package/references/49-iam-rbac-abac-rebac.md +20 -0
  51. package/references/50-zero-trust-and-workload-identity.md +16 -0
  52. package/references/51-secrets-kms-pki-and-key-management.md +20 -0
  53. package/references/52-supply-chain-security-sbom-slsa.md +78 -0
  54. package/references/53-threat-modeling-stride-and-attack-trees.md +16 -0
  55. package/references/54-privacy-engineering-and-data-governance.md +20 -0
  56. package/references/55-opentelemetry-and-instrumentation.md +54 -0
  57. package/references/56-distributed-tracing-and-context-propagation.md +47 -0
  58. package/references/57-continuous-profiling-and-performance-diagnostics.md +45 -0
  59. package/references/58-load-stress-soak-testing-and-workload-modeling.md +44 -0
  60. package/references/59-capacity-planning-and-performance-modeling.md +38 -0
  61. package/references/60-chaos-engineering-and-resilience-experiments.md +45 -0
  62. package/references/61-incident-management-and-postmortems.md +38 -0
  63. package/references/62-dns-and-service-discovery.md +35 -0
  64. package/references/63-load-balancing-and-global-traffic-management.md +31 -0
  65. package/references/64-cdn-and-edge-caching.md +34 -0
  66. package/references/65-cloud-networking-and-connectivity.md +34 -0
  67. package/references/66-edge-computing-architecture.md +33 -0
  68. package/references/67-storage-infrastructure-and-storage-systems.md +34 -0
  69. package/references/68-tcp-quic-and-network-performance.md +27 -0
  70. package/references/69-task-routing-and-evidence.md +115 -0
  71. package/scripts/audit_chain.py +36 -0
  72. package/scripts/compare_reports.py +43 -0
  73. package/scripts/evaluate.py +475 -0
  74. package/scripts/evaluation_catalog.py +129 -0
  75. package/scripts/evaluation_fingerprints.py +20 -0
  76. package/scripts/evidence_archive.py +79 -0
  77. package/scripts/evidence_signing.py +98 -0
  78. package/scripts/evidence_timestamp.py +441 -0
  79. package/scripts/install.ps1 +12 -3
  80. package/scripts/install.sh +15 -8
  81. package/scripts/report_integrity.py +184 -0
  82. package/scripts/review_consensus.py +77 -0
  83. package/scripts/review_evidence.py +105 -0
  84. package/scripts/review_provenance.py +44 -0
  85. package/scripts/reviewer_calibration.py +215 -0
  86. package/scripts/rubric_compatibility.py +134 -0
  87. package/scripts/run_evals.py +130 -0
  88. package/scripts/run_manifest.py +179 -0
  89. package/scripts/statistical_analysis.py +308 -0
  90. package/scripts/tsa_attestation.py +709 -0
  91. package/scripts/tsa_validation_report.py +627 -0
  92. package/scripts/validate.py +356 -11
  93. package/scripts/verify_build_provenance.py +625 -0
  94. package/scripts/verify_tsa_ocsp.py +962 -0
  95. package/scripts/verify_tsa_revocation.py +782 -0
  96. package/scripts/windows_broker_protocol.py +274 -0
  97. package/scripts/windows_broker_transport.py +141 -0
  98. package/scripts/windows_broker_win32.py +713 -0
  99. package/templates/agent-evaluation-plan-template.md +57 -0
  100. package/templates/agent-security-review-template.md +46 -0
  101. package/templates/agent-system-design-template.md +74 -0
  102. package/templates/api-architecture-design-template.md +33 -0
  103. package/templates/api-security-and-rate-limit-review-template.md +29 -0
  104. package/templates/architecture-decision-matrix-template.md +48 -0
  105. package/templates/architecture-review-scorecard-template.md +36 -0
  106. package/templates/cdc-data-pipeline-template.md +41 -0
  107. package/templates/cdn-and-edge-strategy-template.md +36 -0
  108. package/templates/chaos-experiment-template.md +39 -0
  109. package/templates/cloud-cost-model-template.md +37 -0
  110. package/templates/database-architecture-review-template.md +33 -0
  111. package/templates/edge-computing-readiness-template.md +36 -0
  112. package/templates/event-sourcing-cqrs-template.md +41 -0
  113. package/templates/event-streaming-design-template.md +47 -0
  114. package/templates/failure-analysis-template.md +36 -0
  115. package/templates/identity-and-access-architecture-template.md +29 -0
  116. package/templates/incident-postmortem-template.md +39 -0
  117. package/templates/multi-region-disaster-recovery-template.md +43 -0
  118. package/templates/network-architecture-design-template.md +38 -0
  119. package/templates/observability-architecture-template.md +52 -0
  120. package/templates/performance-test-plan-template.md +52 -0
  121. package/templates/privacy-data-governance-template.md +24 -0
  122. package/templates/production-readiness-checklist-template.md +52 -0
  123. package/templates/realtime-system-design-template.md +28 -0
  124. package/templates/security-threat-model-template.md +26 -0
  125. package/templates/sharding-distributed-sql-design-template.md +34 -0
  126. package/templates/storage-architecture-design-template.md +35 -0
  127. package/templates/supply-chain-security-review-template.md +20 -0
  128. package/templates/zero-downtime-database-migration-template.md +32 -0
package/README.md CHANGED
@@ -2,134 +2,188 @@
2
2
 
3
3
  ![CI](https://github.com/jack-001-a/system-design-primer-skill/actions/workflows/ci.yml/badge.svg) ![Latest Release](https://img.shields.io/github/v/release/jack-001-a/system-design-primer-skill)
4
4
 
5
- 面向软件架构设计、架构审查、性能优化、技术选型和迁移规划的可安装 Agent Skill。以 Donne Martin 的 System Design Primer 为知识主题起点,并补充现代生产工程实践。
5
+ An installable Agent Skill for software architecture design, architecture reviews, performance optimization, technology evaluation, and migration planning. It uses Donne Martin's System Design Primer as its knowledge foundation and adds modern production engineering practices.
6
6
 
7
- - **版本:** 1.2.0
8
- - **语言:** 中文说明,保留常用英文技术术语
9
- - **运行依赖:** Skill 本身无第三方运行依赖;安装/校验仅需 Bash、PowerShell 或 Python 3
7
+ - **Version:** 2.4.0
8
+ - **Language:** English, with standard technical terminology
9
+ - **Runtime dependencies:** The Skill itself has no third-party runtime dependencies. Installation and validation require only Bash, PowerShell, or Python 3.
10
10
 
11
- ## 内容结构
11
+ ## Repository structure
12
12
 
13
13
  system-design-primer/
14
14
  ├── SKILL.md
15
15
  ├── README.md / ATTRIBUTION.md / LICENSE / VERSION
16
- ├── references/ 13 份渐进式知识参考
17
- ├── templates/ 架构设计、架构审查、ADR 模板
18
- └── scripts/ Linux/macOS、Windows 安装器和校验器
16
+ ├── references/ 70 progressive knowledge references
17
+ ├── templates/ Design, review, ADR, decision, scorecard, failure, agent, production-readiness, disaster-recovery, FinOps, event-streaming, event-sourcing, CDC, database architecture, sharding, zero-downtime migration, API architecture, real-time systems, identity, threat modeling, supply chain, privacy, observability, performance testing, chaos engineering, incident response, network architecture, CDN/edge strategy, storage architecture, and edge computing templates
18
+ └── scripts/ Linux/macOS and Windows installers and validators
19
19
 
20
- ## 下载
20
+ ## Quality, task routing, and evaluation
21
21
 
22
- 推荐从 [GitHub Releases](https://github.com/jack-001-a/system-design-primer-skill/releases) 下载版本化 ZIP。仓库主分支源码 ZIP 也可从 [main.zip](https://github.com/jack-001-a/system-design-primer-skill/archive/refs/heads/main.zip) 获取。
22
+ Version 2.4.0 adds a provider-neutral evaluation runner, a seventeen-case regression catalog, human-reviewed scoring with a separate security gate, reproducibility manifests, review provenance, integrity chains, and cryptographic evidence verification. The validator checks the evaluation dataset structure and keeps the README, Skill metadata, package manifest, changelog, and VERSION aligned.
23
23
 
24
- 发布 ZIP 内含 system-design-primer/ 目录、嵌入式 MANIFEST.sha256.json 和同名 .sha256 校验文件。校验文件按 SHA-256 生成;Release 只会在 Git tag 与 VERSION 一致、CI 通过后发布。
24
+ The evaluation workflow includes a provider-neutral model runner, a dependency-free human-review aggregator, reproducibility manifests, review-provenance records, and optional evidence signing and RFC 3161 timestamp verification. Run the seventeen fixture prompts through a user-supplied Python adapter, then review and aggregate the responses:
25
25
 
26
- ## 通过 npm 安装
26
+ python scripts/run_evals.py --adapter ./adapter.py --model provider/model-and-version --output evals/responses.jsonl
27
+ python scripts/evaluate.py --responses evals/responses.jsonl --output evals/report.json
27
28
 
28
- 本项目也发布为 npm 包,包名为 `system-design-primer-skill`。npm 包直接包含 `SKILL.md`、13 份参考文档、模板和跨平台安装脚本;不引入第三方运行依赖。
29
+ See [evals/README.md](evals/README.md) for the adapter protocol, JSONL schema, scoring rubric, comparison controls, and limitations. The runner invokes only the adapter you supply; the aggregator validates human annotations and does not automatically judge model correctness or claim benchmark performance.
29
30
 
30
- 在目标项目根目录执行:
31
+ ## Observability and performance engineering
32
+
33
+ Version 2.1.0 adds OpenTelemetry instrumentation and Collector architecture, distributed tracing and context propagation, continuous profiling, realistic load/stress/soak workload models, capacity planning, controlled chaos experiments, and incident management/postmortems. Four templates support observability architecture, performance test plans, chaos experiments, and incident postmortems.
34
+
35
+ ## Networking, edge, and infrastructure architecture
36
+
37
+ Version 2.2.0 adds DNS and service discovery, load balancing and global traffic management, CDN and edge caching, cloud networking and connectivity, edge computing, storage infrastructure, and TCP/QUIC performance engineering. Four templates support network architecture, CDN/edge strategy, storage design, and edge readiness reviews.
38
+
39
+ ## Downloads
40
+
41
+ We recommend downloading the versioned ZIP from [GitHub Releases](https://github.com/jack-001-a/system-design-primer-skill/releases). You can also download the source ZIP from the [main branch](https://github.com/jack-001-a/system-design-primer-skill/archive/refs/heads/main.zip).
42
+
43
+ The release ZIP contains a `system-design-primer/` directory, an embedded `MANIFEST.sha256.json`, and a matching `.sha256` checksum file. Checksums use SHA-256. A Release is published only after the Git tag matches `VERSION`, its commit is reachable from `main`, and all three platform validation jobs pass.
44
+
45
+ ## Install via npm
46
+
47
+ This project is also published as the npm package `system-design-primer-skill`. The package includes `SKILL.md`, 70 reference documents, templates, and cross-platform installation scripts, with no third-party runtime dependencies. CI submits npm versions through OIDC-backed staged publishing; a maintainer must review and approve the staged version before it becomes public.
48
+
49
+ Run the following in the target project root:
31
50
 
32
51
  npm install --save-dev system-design-primer-skill skills
33
52
  npx skills experimental_sync --yes
34
53
 
35
- `skills experimental_sync` 会从已安装的 npm 依赖中发现包根目录的 `SKILL.md`,并将 Skill 链接到当前项目的 Agent Skill 目录。需要指定宿主时,可追加 `--agent codex`、`--agent claude-code` 或其他受支持的 Agent 标识。此同步命令目前属于 Skills CLI 的实验性功能,具体支持范围以其最新文档为准。
54
+ `skills experimental_sync` discovers the `SKILL.md` at the root of installed npm dependencies and links the Skill into the current project's Agent Skill directory. To specify a host, append `--agent codex`, `--agent claude-code`, or another supported Agent identifier. This sync command is currently an experimental feature of the Skills CLI; consult its latest documentation for supported hosts and behavior.
36
55
 
37
- 也可以直接从 GitHub 安装,无需 npm:
56
+ You can also install directly from GitHub without npm:
38
57
 
39
58
  npx skills add jack-001-a/system-design-primer-skill
40
59
 
41
- npm 包页面:[system-design-primer-skill](https://www.npmjs.com/package/system-design-primer-skill)。
60
+ npm package: [system-design-primer-skill](https://www.npmjs.com/package/system-design-primer-skill).
42
61
 
43
- ## 支持的 Agent 目录
62
+ ## Supported Agent directories
44
63
 
45
- | Agent | 项目级目录 | 用户级目录 |
64
+ | Agent | Project-level directory | User-level directory |
46
65
  |---|---|---|
47
- | OpenAI Codex | .agents/skills/ | ~/.agents/skills/ |
48
- | Claude Code | .claude/skills/ | ~/.claude/skills/ |
49
- | Cursor | .cursor/skills/ 或 .agents/skills/ | ~/.cursor/skills/ 或 ~/.agents/skills/ |
50
- | GitHub Copilot | .github/skills/、.claude/skills/ 或 .agents/skills/ | ~/.copilot/skills/ 或 ~/.agents/skills/ |
66
+ | DeepSeek Harness (DSH) | `.dsh/skills/` | `~/.dsh/skills/` |
67
+ | OpenAI Codex | `.agents/skills/` | `~/.agents/skills/` |
68
+ | Claude Code | `.claude/skills/` | `~/.claude/skills/` |
69
+ | Cursor | `.cursor/skills/` or `.agents/skills/` | `~/.cursor/skills/` or `~/.agents/skills/` |
70
+ | GitHub Copilot | `.github/skills/`, `.claude/skills/`, or `.agents/skills/` | `~/.copilot/skills/` |
51
71
 
52
- Cursor Cloud Agents 个人 Skill 应安装到 `~/.cursor/skills/` 并在 Cursor Settings → Agents 中开启 Sync Skills。`~/.agents/skills/` 可用于本地 Cursor 兼容发现,但不会自动同步到 Cloud Agents。项目级 Skill 可放在仓库的 `.cursor/skills/` 或 `.agents/skills/`。GitHub Copilot Cloud Agent 的个人 Skill 则需要放入个人 dotfiles 仓库的 `.copilot/skills/`,并在 Copilot Cloud settings 中配置该 dotfiles 仓库;此方式适用于 cloud sandbox,不适用于 GitHub Actions 会话。参考 [Cursor Cloud Skills](https://cursor.com/docs/skills) 和 [GitHub Copilot Cloud sessions](https://docs.github.com/en/copilot/how-tos/copilot-on-github/customize-copilot/customize-cloud-agent/personalize-cloud-sessions)。
72
+ DeepSeek Harness's filesystem Skill provider discovers directory bundles containing `<skill-name>/SKILL.md` under `.dsh/skills` in a project or `$DSH_HOME/skills` for a user. If `DSH_HOME` is unset, the user-level default is `~/.dsh`. The Skill bundle format used here is compatible; the references and templates remain alongside `SKILL.md`. DSH also scans `.agents/skills` for shared Agent Skills. When the same Skill is installed in both locations, DSH's documented source ranking prefers the native `.dsh/skills` copy; use `--agent dsh` for a DSH-only install if you want to avoid registering a duplicate copy with other hosts.
53
73
 
54
- 目录依据:[Codex Skill 指南](https://learn.chatgpt.com/docs/build-skills)、[Claude Agent Skills](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview)、[Cursor Skills](https://cursor.com/docs/skills)、[GitHub Copilot Skills](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-skills)。
74
+ For Cursor Cloud Agents, install personal Skills in `~/.cursor/skills/` and enable **Sync Skills** in Cursor Settings → Agents. The `~/.agents/skills/` directory may be discovered by local Cursor installations for compatibility, but it does not automatically sync to Cloud Agents. Project-level Skills can live in `.cursor/skills/` or `.agents/skills/` in the repository.
55
75
 
56
- ## 安装
76
+ For GitHub Copilot Cloud Agent, personal Skills must be placed in the `.copilot/skills/` directory of a personal dotfiles repository, and that dotfiles repository must be configured in Copilot Cloud settings. This applies to cloud sandboxes, not GitHub Actions sessions. See [Cursor Cloud Skills](https://cursor.com/docs/skills) and [GitHub Copilot Cloud sessions](https://docs.github.com/en/copilot/how-tos/copilot-on-github/customize-copilot/customize-cloud-agent/personalize-cloud-sessions).
57
77
 
58
- 先解压 ZIP。**在目标代码仓库根目录执行安装命令**;脚本会根据当前目录决定项目级安装位置。示例假设解压后的文件夹为 /opt/system-design-primer。
78
+ Directory references: [Codex Skills guide](https://learn.chatgpt.com/docs/build-skills), [Claude Agent Skills](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview), [Cursor Skills](https://cursor.com/docs/skills), [GitHub Copilot Skills](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-skills), and [DeepSeek Harness Skills](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/subsystems/skills.md).
79
+
80
+ ## Installation
81
+
82
+ Extract the ZIP first. **Run the installation command from the root of the target code repository**; the script determines the project-level installation location from the current directory. The examples below assume the extracted folder is `/opt/system-design-primer`.
59
83
 
60
84
  ### macOS / Linux
61
85
 
62
86
  cd /path/to/your-project
63
87
 
64
- # 只装 Codex
88
+ # Install for DeepSeek Harness only
89
+ bash /opt/system-design-primer/scripts/install.sh --agent dsh --scope project
90
+
91
+ # Install for Codex only
65
92
  bash /opt/system-design-primer/scripts/install.sh --agent codex --scope project
66
93
 
67
- # 只装 Claude Code
94
+ # Install for Claude Code only
68
95
  bash /opt/system-design-primer/scripts/install.sh --agent claude --scope project
69
96
 
70
- # 只装 Cursor(使用 Cursor 专用目录)
97
+ # Install for Cursor only (uses the Cursor-specific directory)
71
98
  bash /opt/system-design-primer/scripts/install.sh --agent cursor --scope project
72
99
 
73
- # 只装 GitHub Copilot
100
+ # Install for GitHub Copilot only
74
101
  bash /opt/system-design-primer/scripts/install.sh --agent copilot --scope project
75
102
 
76
- # 一次安装多种宿主目录
103
+ # Install for multiple hosts at once, including DeepSeek Harness
77
104
  bash /opt/system-design-primer/scripts/install.sh --agent all --scope project
78
105
 
79
- # 安装到当前用户目录
106
+ # Install into the current user's home directory
80
107
  bash /opt/system-design-primer/scripts/install.sh --agent all --scope user
81
108
 
109
+ # Install DSH under a custom DSH_HOME root (contains the skills/ directory)
110
+ DSH_HOME="$HOME/.config/deepseek-harness" bash /opt/system-design-primer/scripts/install.sh --agent dsh --scope user
111
+
82
112
  ### Windows PowerShell
83
113
 
84
114
  Set-Location C:\path\to\your-project
85
115
 
86
- # 根据需要选择 codex、claude、cursor、copilot 或 all
87
- & C:\path\to\system-design-primer\scripts\install.ps1 -Agent codex -Scope project
116
+ # Choose dsh, codex, claude, cursor, copilot, or all as needed
117
+ & C:\path\to\system-design-primer\scripts\install.ps1 -Agent dsh -Scope project
88
118
 
89
- # 安装到用户级目录
119
+ # Install into the user-level directories for all supported hosts
90
120
  & C:\path\to\system-design-primer\scripts\install.ps1 -Agent all -Scope user
91
121
 
92
- ## 安装器行为与安全
122
+ ## Installer behavior and security
93
123
 
94
- - 默认不覆盖已存在的 Skill;需要更新时显式使用 --force 或 -Force。
95
- - --dry-run / -WhatIf 仅预览目标路径,不创建或修改文件。
96
- - 安装器先检查全部目标,再使用同目录 staging 目录替换;失败时尽力恢复原目录。
97
- - 只复制 SKILL.md、references、templates、scripts、ATTRIBUTION.md、LICENSE 和 VERSION,不复制 .git、GitHub Actions、测试或开发工具。
98
- - --agent all 的项目级目标为 .agents/skills、.claude/skills、.github/skills;用户级目标为 ~/.agents/skills、~/.claude/skills、~/.copilot/skills。
99
- - Cursor 也会兼容发现 .agents/skills 和 .claude/skills。若同时启用多个宿主,建议用对应的单宿主安装参数,避免同一 Skill 被重复发现。
100
- - 安装脚本不会安装依赖,也不会自动执行 Skill 中的脚本。
124
+ - Existing Skills are not overwritten by default. Use `--force` or `-Force` explicitly to update them.
125
+ - `--dry-run` / `-WhatIf` previews target paths without creating or modifying files.
126
+ - The installer checks all targets first, then stages replacements in a same-directory staging folder. If installation fails, it makes a best effort to restore the previous directory.
127
+ - It copies only `SKILL.md`, `references`, `templates`, `evals`, `ATTRIBUTION.md`, `LICENSE`, `VERSION`, and the two installer entry points (`scripts/install.sh` and `scripts/install.ps1`). Repository-only validation and packaging tools are not installed. It does not copy `.git`, GitHub Actions, tests, or development tools.
128
+ - With `--agent all`, project-level targets are `.dsh/skills`, `.agents/skills`, `.claude/skills`, and `.github/skills`; user-level targets are `$DSH_HOME/skills`, `~/.agents/skills`, `~/.claude/skills`, and `~/.copilot/skills`. If `DSH_HOME` is unset, the DSH root defaults to `~/.dsh`.
129
+ - DeepSeek Harness scans both its native `.dsh/skills` directory and the shared `.agents/skills` directory. Installing with `--agent all` therefore makes the same Skill available through both discovery paths; DSH's source ranking prefers the native DSH copy. Use `--agent dsh` when only DSH should discover this installation.
130
+ - Cursor can also discover `.agents/skills` and `.claude/skills` for compatibility. If multiple hosts are enabled, prefer the corresponding single-host installation option to avoid duplicate discovery of the same Skill.
131
+ - The installation scripts do not install dependencies or automatically execute scripts included in the Skill.
101
132
 
102
- ## 校验与开发
133
+ ## Validation and development
103
134
 
104
- 在仓库根目录运行:
135
+ Run the following from the repository root:
105
136
 
106
137
  python scripts/validate.py
107
138
  python -m unittest discover -s tests -v
108
139
  bash -n scripts/install.sh
109
140
  bash tests/test_install.sh
110
141
  python tools/package.py --output-dir dist
142
+ python tools/verify_package.py dist/system-design-primer-v$(tr -d '[:space:]' < VERSION).zip
111
143
 
112
- Windows 还可运行:
144
+ On Windows, you can also run:
113
145
 
114
146
  .\tests\test_install.ps1
115
147
 
116
- GitHub Actions 会在 Ubuntu、macOS 和 Windows 上运行校验/测试。正式发布仅由版本 Tag 触发:先更新 VERSION 和 CHANGELOG.md,合并到 main 并等待 CI 通过,再创建与 VERSION 完全一致的 v* Tag。Release 工作流会在三个平台完成验证后构建 ZIP、SHA-256 并发布 GitHub Release;release/** 分支不会直接触发正式发布。
148
+ GitHub Actions runs validation and tests on Ubuntu, macOS, and Windows. Formal releases are triggered only by version tags: update `VERSION` and `CHANGELOG.md`, merge into `main`, wait for CI to pass, and then create a `v*` tag that exactly matches `VERSION`. The Release workflow validates on all three platforms before building the ZIP, generating SHA-256 checksums, and publishing the GitHub Release. Branches matching `release/**` do not trigger formal releases directly.
149
+
150
+ ## Usage examples
151
+
152
+ Use the system-design-primer Skill to review this repository's overall architecture.
153
+ Focus on critical business flows, data models, transaction boundaries, caching,
154
+ asynchronous jobs, reliability, security, and observability. Sort findings by
155
+ severity and include file-level evidence. Review only; do not modify code.
156
+
157
+ Use the system-design-primer Skill to design a multi-tenant subscription billing system.
158
+ First clarify FRs/NFRs, capacity assumptions, data models, idempotency, reconciliation,
159
+ and failure recovery. Then provide an architecture diagram, alternatives, an ADR,
160
+ and a phased rollout plan.
161
+
162
+ Use the system-design-primer Skill to design a multi-agent research assistant.
163
+ Compare a single-agent baseline with supervisor/worker and pipeline topologies.
164
+ Define agent contracts, tool permissions, MCP boundaries, checkpoint/recovery,
165
+ evaluation datasets, and measurable quality, latency, and cost objectives.
166
+
167
+ ## Attribution and license
168
+
169
+ This is an independent, unofficial Skill. Its knowledge topics are based on [Donne Martin/System Design Primer](https://github.com/donnemartin/system-design-primer), with original workflows and modern engineering practices added. Original explanations, templates, and reference text are licensed under CC BY 4.0. Third-party linked content remains under its respective copyright and license; see [ATTRIBUTION.md](ATTRIBUTION.md) for details.
170
+
171
+ Architecture decision matrices, evidence-based review scorecards, API/data contracts, and failure-analysis workflows are documented in [references/13-architecture-intelligence.md](references/13-architecture-intelligence.md), [references/14-api-and-data-contracts.md](references/14-api-and-data-contracts.md), and [references/15-failure-analysis.md](references/15-failure-analysis.md). Matching fill-in templates are available under `templates/`.
172
+
173
+ For in-depth AI systems architecture, see [references/12-ai-systems-architecture.md](references/12-ai-systems-architecture.md). Agent-specific architecture guidance is split into [multi-agent architecture](references/16-multi-agent-architecture.md), [agent harness and runtime](references/17-agent-harness-and-runtime.md), [MCP architecture](references/18-mcp-architecture.md), [agent security and permissions](references/19-agent-security-and-permissions.md), [agent state and memory](references/20-agent-state-and-memory.md), and [agent evaluation and observability](references/21-agent-evaluation-and-observability.md). Use the matching templates in `templates/` to create a system design, security review, or evaluation plan.
174
+
175
+ Production architecture guidance covers [Kubernetes and container platforms](references/22-kubernetes-and-container-platforms.md), [service mesh and traffic management](references/23-service-mesh-and-traffic-management.md), [multi-region architecture and disaster recovery](references/24-multi-region-and-disaster-recovery.md), [platform engineering](references/25-platform-engineering-and-developer-experience.md), [FinOps and cloud cost](references/26-finops-and-cloud-cost.md), and [production observability and SLOs](references/27-production-observability-and-slo.md). Matching templates support production readiness reviews, multi-region recovery plans, and cloud cost models.
176
+
177
+ Data-intensive and event-driven architecture guidance covers [Kafka and Pulsar event streaming](references/28-event-streaming-and-kafka-pulsar.md), [Event Sourcing and CQRS](references/29-event-sourcing-and-cqrs.md), [CDC and Debezium](references/30-change-data-capture-and-debezium.md), [data lakehouse and stream/batch processing](references/31-data-lakehouse-and-stream-batch.md), [durable workflow orchestration](references/32-workflow-orchestration-and-temporal.md), and [schema registry and event governance](references/33-schema-registry-and-event-governance.md). Matching templates support event-streaming designs, event-sourced domains, and CDC data pipelines.
117
178
 
118
- ## 使用示例
179
+ API and real-time architecture guidance covers [API gateway and edge architecture](references/41-api-gateway-and-edge-architecture.md), [REST API design and lifecycle](references/42-rest-api-design-and-lifecycle.md), [GraphQL architecture](references/43-graphql-architecture-and-governance.md), [gRPC and service contracts](references/44-grpc-and-service-contracts.md), [WebSocket, SSE, and real-time systems](references/45-websocket-sse-and-realtime-systems.md), [real-time collaboration with OT/CRDT](references/46-realtime-collaboration-ot-crdt.md), and [API security, rate limiting, and abuse prevention](references/47-api-security-rate-limiting-and-abuse.md). Matching templates support API design, real-time system design, and API security reviews.
119
180
 
120
- 使用 system-design-primer Skill 审查此仓库的整体架构。
121
- 重点分析关键业务流、数据模型、事务边界、缓存、异步任务、
122
- 可靠性、安全和可观测性。按严重程度排序,每条发现附文件证据。
123
- 先只审查,不要修改代码。
181
+ Database and distributed-data guidance covers [PostgreSQL internals and performance](references/34-postgresql-internals-and-performance.md), [MySQL/InnoDB](references/35-mysql-innodb-and-performance.md), [sharding and Distributed SQL](references/36-sharding-and-distributed-sql.md), [consensus and distributed transactions](references/37-consensus-and-distributed-transactions.md), [Elasticsearch/OpenSearch search architecture](references/38-search-architecture-elasticsearch-opensearch.md), [vector databases and hybrid retrieval](references/39-vector-databases-and-hybrid-retrieval.md), and [zero-downtime database migrations](references/40-zero-downtime-database-migrations.md). Matching templates support database architecture reviews, sharding decisions, and migration plans.
124
182
 
125
- 使用 system-design-primer Skill 设计多租户订阅计费系统。
126
- 先明确 FR/NFR、容量假设、数据模型、幂等、对账和失败恢复,
127
- 再给出架构图、替代方案、ADR 和分阶段上线计划。
128
183
 
129
- ## 归属与许可
130
184
 
131
- 本项目为独立、非官方 Skill。知识主题参考 [Donne Martin/System Design Primer](https://github.com/donnemartin/system-design-primer),并加入原创工作流与现代工程实践。原创说明、模板和参考文字采用 CC BY 4.0;第三方链接内容保留其各自版权和许可,详见 ATTRIBUTION.md。
185
+ Networking and infrastructure architecture guidance covers [DNS and service discovery](references/62-dns-and-service-discovery.md), [load balancing and global traffic management](references/63-load-balancing-and-global-traffic-management.md), [CDN and edge caching](references/64-cdn-and-edge-caching.md), [cloud networking and connectivity](references/65-cloud-networking-and-connectivity.md), [edge computing](references/66-edge-computing-architecture.md), [storage infrastructure](references/67-storage-infrastructure-and-storage-systems.md), and [TCP/QUIC network performance](references/68-tcp-quic-and-network-performance.md). Matching templates support network designs, CDN strategies, storage architecture, and edge readiness.
132
186
 
133
- AI 系统架构的深入内容见 [references/12-ai-systems-architecture.md](references/12-ai-systems-architecture.md)。
187
+ Security and identity architecture guidance covers [OAuth/OIDC and passkeys](references/48-oauth-oidc-and-passkeys.md), [IAM and authorization models](references/49-iam-rbac-abac-rebac.md), [Zero Trust and workload identity](references/50-zero-trust-and-workload-identity.md), [secrets, KMS, and PKI](references/51-secrets-kms-pki-and-key-management.md), [software supply chain security](references/52-supply-chain-security-sbom-slsa.md), [STRIDE threat modeling](references/53-threat-modeling-stride-and-attack-trees.md), and [privacy engineering and data governance](references/54-privacy-engineering-and-data-governance.md). Matching templates support identity architecture, threat models, supply-chain reviews, and privacy governance.
134
188
 
135
- 更多信息见 [CHANGELOG.md](CHANGELOG.md)、[CONTRIBUTING.md](CONTRIBUTING.md) 和 [SECURITY.md](SECURITY.md)。
189
+ For more information, see [CHANGELOG.md](CHANGELOG.md), [CONTRIBUTING.md](CONTRIBUTING.md), and [SECURITY.md](SECURITY.md).