universal-dev-standards 5.2.0 → 5.3.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.
- package/bundled/ai/options/release/publish-mode-github-actions.ai.yaml +65 -0
- package/bundled/ai/standards/cd-deployment-strategies.ai.yaml +73 -0
- package/bundled/ai/standards/no-cicd-deployment.ai.yaml +134 -0
- package/bundled/ai/standards/pipeline-security-gates.ai.yaml +71 -0
- package/bundled/ai/standards/push-standards.ai.yaml +105 -0
- package/bundled/ai/standards/rollback-standards.ai.yaml +68 -0
- package/bundled/core/cd-deployment-strategies.md +121 -0
- package/bundled/core/no-cicd-deployment.md +205 -0
- package/bundled/core/pipeline-security-gates.md +109 -0
- package/bundled/core/rollback-standards.md +104 -0
- package/bundled/locales/zh-CN/CHANGELOG.md +14 -3
- package/bundled/locales/zh-CN/README.md +48 -9
- package/bundled/locales/zh-TW/CHANGELOG.md +14 -3
- package/bundled/locales/zh-TW/README.md +47 -8
- package/bundled/locales/zh-TW/skills/deploy-assistant/SKILL.md +178 -0
- package/bundled/skills/deploy-assistant/SKILL.md +183 -0
- package/package.json +1 -1
- package/standards-registry.json +59 -3
|
@@ -0,0 +1,205 @@
|
|
|
1
|
+
# No-CI/CD Deployment Strategy
|
|
2
|
+
|
|
3
|
+
> **補充**: 本文件補充 `deployment-standards.md`,專注於無 CI/CD 平台(GitHub Actions / GitLab CI)環境下的可靠部署設計。
|
|
4
|
+
|
|
5
|
+
## 核心三層架構
|
|
6
|
+
|
|
7
|
+
```
|
|
8
|
+
Layer 1: 防止錯誤部署
|
|
9
|
+
└─ set -euo pipefail、版本 tag 強制、deploy.lock
|
|
10
|
+
|
|
11
|
+
Layer 2: 驗證部署正確
|
|
12
|
+
└─ Smoke Test、健康檢查、版本號比對、自動 rollback
|
|
13
|
+
|
|
14
|
+
Layer 3: 快速回復能力
|
|
15
|
+
└─ Blue-Green 切換、< 30 秒 rollback
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
## Layer 1:防止錯誤部署
|
|
19
|
+
|
|
20
|
+
### Shell 腳本強制執行
|
|
21
|
+
|
|
22
|
+
所有部署腳本必須以下列標頭開始:
|
|
23
|
+
|
|
24
|
+
```bash
|
|
25
|
+
#!/usr/bin/env bash
|
|
26
|
+
set -euo pipefail
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
- `set -e`:任何命令失敗立即退出
|
|
30
|
+
- `set -u`:引用未定義變數視為錯誤
|
|
31
|
+
- `set -o pipefail`:管線中任何命令失敗都會傳播錯誤
|
|
32
|
+
|
|
33
|
+
### 強制部署順序
|
|
34
|
+
|
|
35
|
+
```bash
|
|
36
|
+
echo "[1/4] 執行測試..."
|
|
37
|
+
npm test
|
|
38
|
+
|
|
39
|
+
echo "[2/4] 建置產物..."
|
|
40
|
+
npm run build
|
|
41
|
+
|
|
42
|
+
echo "[3/4] 推送到伺服器..."
|
|
43
|
+
rsync -avz --delete ./dist/ user@server:/app/
|
|
44
|
+
|
|
45
|
+
echo "[4/4] 驗證部署..."
|
|
46
|
+
./verify.sh || { echo "驗證失敗,執行 rollback..."; ./rollback.sh; exit 1; }
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
### deploy.lock 防並發
|
|
50
|
+
|
|
51
|
+
```bash
|
|
52
|
+
LOCK_FILE="/tmp/deploy.lock"
|
|
53
|
+
trap "rm -f $LOCK_FILE" EXIT
|
|
54
|
+
|
|
55
|
+
if [ -f "$LOCK_FILE" ]; then
|
|
56
|
+
echo "❌ 部署進行中(PID: $(cat $LOCK_FILE)),請等待完成"
|
|
57
|
+
exit 1
|
|
58
|
+
fi
|
|
59
|
+
|
|
60
|
+
echo $$ > "$LOCK_FILE"
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
### 版本 Tag 強制
|
|
64
|
+
|
|
65
|
+
```bash
|
|
66
|
+
CURRENT_TAG=$(git describe --exact-match --tags HEAD 2>/dev/null || echo "")
|
|
67
|
+
if [ -z "$CURRENT_TAG" ]; then
|
|
68
|
+
echo "❌ 當前 commit 沒有版本 tag,請先執行:"
|
|
69
|
+
echo " git tag v$(cat VERSION) && git push --tags"
|
|
70
|
+
exit 1
|
|
71
|
+
fi
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
## Layer 2:驗證部署正確
|
|
75
|
+
|
|
76
|
+
### Smoke Test 腳本 (verify.sh)
|
|
77
|
+
|
|
78
|
+
```bash
|
|
79
|
+
#!/usr/bin/env bash
|
|
80
|
+
set -euo pipefail
|
|
81
|
+
|
|
82
|
+
HEALTH_URL="${HEALTH_URL:-https://example.com/health}"
|
|
83
|
+
EXPECTED_VERSION=$(cat VERSION)
|
|
84
|
+
MAX_RETRIES=3
|
|
85
|
+
RETRY_INTERVAL=5
|
|
86
|
+
|
|
87
|
+
for i in $(seq 1 $MAX_RETRIES); do
|
|
88
|
+
RESPONSE=$(curl -sf --max-time 10 "$HEALTH_URL" 2>/dev/null) && break
|
|
89
|
+
echo "健康檢查失敗 ($i/$MAX_RETRIES),等待 ${RETRY_INTERVAL}s..."
|
|
90
|
+
sleep $RETRY_INTERVAL
|
|
91
|
+
done
|
|
92
|
+
|
|
93
|
+
ACTUAL_VERSION=$(echo "$RESPONSE" | python3 -c "import json,sys; print(json.load(sys.stdin)['version'])")
|
|
94
|
+
|
|
95
|
+
if [ "$ACTUAL_VERSION" != "$EXPECTED_VERSION" ]; then
|
|
96
|
+
echo "❌ 版本不符!預期 $EXPECTED_VERSION,實際 $ACTUAL_VERSION"
|
|
97
|
+
exit 1
|
|
98
|
+
fi
|
|
99
|
+
|
|
100
|
+
echo "✅ 版本驗證通過:$ACTUAL_VERSION"
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
### 健康檢查端點規格
|
|
104
|
+
|
|
105
|
+
應用程式必須提供 `/health` 端點,回應格式:
|
|
106
|
+
|
|
107
|
+
```json
|
|
108
|
+
{
|
|
109
|
+
"status": "ok",
|
|
110
|
+
"version": "1.2.3",
|
|
111
|
+
"timestamp": "2026-04-26T10:00:00Z"
|
|
112
|
+
}
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
## Layer 3:快速回復能力
|
|
116
|
+
|
|
117
|
+
### Blue-Green 架構
|
|
118
|
+
|
|
119
|
+
```
|
|
120
|
+
[Nginx]
|
|
121
|
+
│
|
|
122
|
+
├─── Blue (port 3001) ← 穩定版(當前 active)
|
|
123
|
+
└─── Green (port 3002) ← 新版(部署目標)
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
**Nginx 配置**:
|
|
127
|
+
|
|
128
|
+
```nginx
|
|
129
|
+
upstream app {
|
|
130
|
+
server 127.0.0.1:3001; # blue
|
|
131
|
+
# server 127.0.0.1:3002; # green(切換時啟用此行並停用上一行)
|
|
132
|
+
}
|
|
133
|
+
|
|
134
|
+
server {
|
|
135
|
+
listen 80;
|
|
136
|
+
location / {
|
|
137
|
+
proxy_pass http://app;
|
|
138
|
+
}
|
|
139
|
+
}
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
### Rollback 腳本 (rollback.sh)
|
|
143
|
+
|
|
144
|
+
```bash
|
|
145
|
+
#!/usr/bin/env bash
|
|
146
|
+
set -euo pipefail
|
|
147
|
+
|
|
148
|
+
CURRENT=$(readlink /app/current)
|
|
149
|
+
if [[ "$CURRENT" == *"green"* ]]; then
|
|
150
|
+
TARGET="/app/blue"
|
|
151
|
+
else
|
|
152
|
+
TARGET="/app/green"
|
|
153
|
+
fi
|
|
154
|
+
|
|
155
|
+
ln -sfn "$TARGET" /app/current
|
|
156
|
+
nginx -s reload
|
|
157
|
+
|
|
158
|
+
echo "✅ 已切回 $TARGET($(date -u +%Y-%m-%dT%H:%M:%SZ))"
|
|
159
|
+
|
|
160
|
+
# 記錄 rollback 事件
|
|
161
|
+
echo "{\"timestamp\":\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\",\"event\":\"rollback\",\"from\":\"$CURRENT\",\"to\":\"$TARGET\",\"operator\":\"$(whoami)\"}" >> /var/log/deployments.jsonl
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
### 完整 Makefile
|
|
165
|
+
|
|
166
|
+
```makefile
|
|
167
|
+
.PHONY: deploy rollback verify
|
|
168
|
+
|
|
169
|
+
deploy:
|
|
170
|
+
@./deploy.sh
|
|
171
|
+
|
|
172
|
+
rollback:
|
|
173
|
+
@./rollback.sh
|
|
174
|
+
|
|
175
|
+
verify:
|
|
176
|
+
@./verify.sh
|
|
177
|
+
|
|
178
|
+
status:
|
|
179
|
+
@echo "Current: $$(readlink /app/current)"
|
|
180
|
+
@curl -s $${HEALTH_URL:-http://localhost/health} | python3 -m json.tool
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
## Deployment Log 格式
|
|
184
|
+
|
|
185
|
+
每次部署(成功或失敗)都必須寫入 JSON Lines 格式的日誌:
|
|
186
|
+
|
|
187
|
+
```json
|
|
188
|
+
{"timestamp":"2026-04-26T10:00:00Z","version":"1.2.3","git_commit":"abc1234","operator":"albert","result":"success","duration_seconds":45,"slot":"green"}
|
|
189
|
+
{"timestamp":"2026-04-26T11:30:00Z","version":"1.2.4","git_commit":"def5678","operator":"albert","result":"failure","duration_seconds":12,"slot":"green","error":"version_mismatch"}
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
## 適用場景
|
|
193
|
+
|
|
194
|
+
| 場景 | 建議 |
|
|
195
|
+
|------|------|
|
|
196
|
+
| 個人 VPS / 小型專案 | Layer 1 + Layer 2(無需 Blue-Green) |
|
|
197
|
+
| 自架伺服器(多人團隊) | 三層全套 + deploy.lock |
|
|
198
|
+
| Air-gapped 環境 | 三層全套 + 本地 artifact registry |
|
|
199
|
+
| 容器化部署 | 搭配 `docker compose` 執行 |
|
|
200
|
+
|
|
201
|
+
## 相關標準
|
|
202
|
+
|
|
203
|
+
- `deployment-standards.ai.yaml` — 有 CI/CD 平台的部署策略(本文件的補充前提)
|
|
204
|
+
- `health-check-standards.ai.yaml` — /health 端點設計規範
|
|
205
|
+
- `circuit-breaker.ai.yaml` — 斷路器整合(進階場景)
|
|
@@ -0,0 +1,109 @@
|
|
|
1
|
+
# Pipeline Security Gates(CI Pipeline 安全檢查點)
|
|
2
|
+
|
|
3
|
+
## 概述
|
|
4
|
+
|
|
5
|
+
本標準定義嵌入 CI pipeline 各階段的安全檢查點,涵蓋 SAST、DAST、SCA(含 SBOM)和機密掃描,並明確規定各類發現的阻斷(Block)、警告(Warn)、記錄(Log)行為。
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## 核心原則
|
|
10
|
+
|
|
11
|
+
- **機密掃描在 pre-commit**:所有包含機密的提交都必須被阻擋,不得例外
|
|
12
|
+
- **SAST 在建置後**:Critical 和 High 等級發現阻斷 pipeline
|
|
13
|
+
- **SCA + SBOM 在封包階段**:追蹤相依套件風險並產生物料清單
|
|
14
|
+
- **DAST 在 staging 部署後**:對運行中的應用進行動態掃描
|
|
15
|
+
- **安全閘門失敗 = pipeline 失敗**:不得視為可忽略的警告
|
|
16
|
+
- **任何繞過都需審計軌跡**:禁止靜默跳過安全閘門
|
|
17
|
+
|
|
18
|
+
---
|
|
19
|
+
|
|
20
|
+
## 安全閘門位置與配置
|
|
21
|
+
|
|
22
|
+
### 1. Pre-Commit — 機密掃描
|
|
23
|
+
|
|
24
|
+
| 項目 | 說明 |
|
|
25
|
+
|------|------|
|
|
26
|
+
| 掃描範圍 | 所有 staged 檔案 |
|
|
27
|
+
| 推薦工具 | gitleaks、trufflehog、detect-secrets |
|
|
28
|
+
| 阻斷條件 | 任何機密模式匹配 |
|
|
29
|
+
| 可跳過 | 否(`never_skip: true`) |
|
|
30
|
+
|
|
31
|
+
**重要**:此閘門必須在程式碼進入版本控制前執行,一旦機密進入 git 歷史便需要完整的機密輪換程序。
|
|
32
|
+
|
|
33
|
+
---
|
|
34
|
+
|
|
35
|
+
### 2. Post-Build — SAST(靜態應用安全測試)
|
|
36
|
+
|
|
37
|
+
| 項目 | 說明 |
|
|
38
|
+
|------|------|
|
|
39
|
+
| 掃描範圍 | 原始碼 + 建置產出物 |
|
|
40
|
+
| 推薦工具 | semgrep、codeql、sonarqube |
|
|
41
|
+
| 阻斷條件 | Critical、High |
|
|
42
|
+
| 警告條件 | Medium |
|
|
43
|
+
| 僅記錄 | Low、Info |
|
|
44
|
+
|
|
45
|
+
---
|
|
46
|
+
|
|
47
|
+
### 3. Package Stage — SCA + SBOM
|
|
48
|
+
|
|
49
|
+
| 項目 | 說明 |
|
|
50
|
+
|------|------|
|
|
51
|
+
| 掃描範圍 | 相依套件 + 容器映像 |
|
|
52
|
+
| 推薦工具 | trivy、syft、grype、dependabot |
|
|
53
|
+
| 阻斷條件 | Critical CVE(有可用修復版本) |
|
|
54
|
+
| 警告條件 | High CVE、過時相依套件 |
|
|
55
|
+
| SBOM 格式 | SPDX、CycloneDX |
|
|
56
|
+
|
|
57
|
+
**SBOM 用途**:上傳至 dependency-track 或 grype-db 進行持續監控。
|
|
58
|
+
|
|
59
|
+
---
|
|
60
|
+
|
|
61
|
+
### 4. Post-Staging Deploy — DAST(動態應用安全測試)
|
|
62
|
+
|
|
63
|
+
| 項目 | 說明 |
|
|
64
|
+
|------|------|
|
|
65
|
+
| 掃描範圍 | 運行中的 staging 應用程式 |
|
|
66
|
+
| 推薦工具 | ZAP、nuclei、BurpSuite Enterprise |
|
|
67
|
+
| 阻斷條件 | Critical |
|
|
68
|
+
| 需審核批准 | High |
|
|
69
|
+
| 警告條件 | Medium |
|
|
70
|
+
|
|
71
|
+
---
|
|
72
|
+
|
|
73
|
+
## 嚴重性回應矩陣
|
|
74
|
+
|
|
75
|
+
| 嚴重性 | 動作 | 通知對象 | SLA |
|
|
76
|
+
|--------|------|---------|-----|
|
|
77
|
+
| Critical | 阻斷 pipeline | 資安團隊 | 立即 |
|
|
78
|
+
| High | 阻斷 pipeline | 團隊主管 | 當日 |
|
|
79
|
+
| Medium | 警告 + 需審核批准 | 開發者 | 下個 Sprint |
|
|
80
|
+
| Low | 僅記錄 | 無 | Backlog |
|
|
81
|
+
|
|
82
|
+
---
|
|
83
|
+
|
|
84
|
+
## 繞過政策
|
|
85
|
+
|
|
86
|
+
**預設禁止繞過**。
|
|
87
|
+
|
|
88
|
+
若有特殊情況:
|
|
89
|
+
- **例外流程**:需書面資安審核 + 審計日誌記錄
|
|
90
|
+
- **緊急繞過**:時效性令牌(time-limited token)+ 強制事後審查
|
|
91
|
+
|
|
92
|
+
---
|
|
93
|
+
|
|
94
|
+
## 整合點
|
|
95
|
+
|
|
96
|
+
| 整合項目 | 說明 |
|
|
97
|
+
|---------|------|
|
|
98
|
+
| 機密管理 | 整合 HashiCorp Vault 或 AWS Secrets Manager 進行機密注入 |
|
|
99
|
+
| SBOM 註冊表 | 上傳 SBOM 至 dependency-track 或 grype-db 持續監控 |
|
|
100
|
+
| 事故回應 | Critical 發現自動建立事故單 |
|
|
101
|
+
|
|
102
|
+
---
|
|
103
|
+
|
|
104
|
+
## 相關標準
|
|
105
|
+
|
|
106
|
+
- [security-standards.md](security-standards.md) — 應用安全基礎標準
|
|
107
|
+
- [pipeline-integration-standards.md](pipeline-integration-standards.md) — CI 管線整合標準
|
|
108
|
+
- [deployment-standards.md](deployment-standards.md) — 部署基礎原則
|
|
109
|
+
- AI 格式:[../ai/standards/pipeline-security-gates.ai.yaml](../ai/standards/pipeline-security-gates.ai.yaml)
|
|
@@ -0,0 +1,104 @@
|
|
|
1
|
+
# Rollback Standards(回滾標準)
|
|
2
|
+
|
|
3
|
+
## 概述
|
|
4
|
+
|
|
5
|
+
本標準定義回滾觸發條件矩陣、自動 vs 手動回滾決策流程,以及與錯誤預算的整合方式。確保每一次部署都有明確、可量化的回滾策略,而非依賴主觀判斷。
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## 核心原則
|
|
10
|
+
|
|
11
|
+
- **可量化觸發條件**:回滾觸發必須有明確的數值門檻,絕不使用「看起來有問題」等主觀描述
|
|
12
|
+
- **三層決策模型**:自動回滾(Auto)→ 輔助回滾(Assisted)→ 手動回滾(Manual)
|
|
13
|
+
- **錯誤預算整合**:當錯誤預算低於 10% 時,自動將輔助回滾升級為自動回滾
|
|
14
|
+
- **強制事件記錄**:每次回滾都必須寫入部署日誌並觸發事故回應流程
|
|
15
|
+
|
|
16
|
+
---
|
|
17
|
+
|
|
18
|
+
## 觸發條件矩陣
|
|
19
|
+
|
|
20
|
+
### 自動回滾(Auto-Rollback)
|
|
21
|
+
|
|
22
|
+
系統自動執行,無需人工干預:
|
|
23
|
+
|
|
24
|
+
| 指標 | 觸發門檻 |
|
|
25
|
+
|------|---------|
|
|
26
|
+
| 錯誤率 | > 2× 基線,持續 5 分鐘 |
|
|
27
|
+
| 健康檢查失敗 | 連續 3 次 |
|
|
28
|
+
| P99 延遲 | > 5× 基線,持續 3 分鐘 |
|
|
29
|
+
|
|
30
|
+
### 輔助回滾(Assisted-Rollback)
|
|
31
|
+
|
|
32
|
+
系統發出警報,由值班工程師確認後執行:
|
|
33
|
+
|
|
34
|
+
| 條件 | 說明 |
|
|
35
|
+
|------|------|
|
|
36
|
+
| SLO 違反 | 非關鍵路徑的 SLO 違反 |
|
|
37
|
+
| 錯誤預算剩餘 | < 10%(此時升級為自動回滾) |
|
|
38
|
+
|
|
39
|
+
### 手動回滾(Manual-Rollback)
|
|
40
|
+
|
|
41
|
+
由開發者評估後決定是否執行:
|
|
42
|
+
|
|
43
|
+
| 條件 | 說明 |
|
|
44
|
+
|------|------|
|
|
45
|
+
| 延遲惡化 | 仍在 SLO 範圍內的效能下降 |
|
|
46
|
+
| 外觀問題 | 使用者可見但不影響功能的問題 |
|
|
47
|
+
|
|
48
|
+
---
|
|
49
|
+
|
|
50
|
+
## 嚴重性矩陣
|
|
51
|
+
|
|
52
|
+
| 等級 | 觸發方式 | 處理時限 | 通知對象 |
|
|
53
|
+
|------|---------|---------|---------|
|
|
54
|
+
| P0 | 自動 | < 2 分鐘 | 全體相關人員 |
|
|
55
|
+
| P1 | 自動 | < 5 分鐘 | 值班工程師 |
|
|
56
|
+
| P2 | 輔助 | < 15 分鐘 | 團隊主管 |
|
|
57
|
+
| P3 | 手動 | < 1 小時 | 開發者 |
|
|
58
|
+
|
|
59
|
+
---
|
|
60
|
+
|
|
61
|
+
## 錯誤預算整合
|
|
62
|
+
|
|
63
|
+
當錯誤預算剩餘 < 10% 時:
|
|
64
|
+
|
|
65
|
+
1. 輔助回滾自動升級為自動回滾
|
|
66
|
+
2. 觸發事故事件記錄
|
|
67
|
+
3. 暫停後續部署,直到預算恢復
|
|
68
|
+
|
|
69
|
+
---
|
|
70
|
+
|
|
71
|
+
## 回滾方法比較
|
|
72
|
+
|
|
73
|
+
| 方法 | 執行時間 | 風險 | 前置條件 |
|
|
74
|
+
|------|---------|------|---------|
|
|
75
|
+
| Blue-Green 切換 | < 30 秒 | 低 | 雙環境基礎設施 |
|
|
76
|
+
| Feature Flag 關閉 | < 5 秒 | 極低 | Feature Flag 系統 |
|
|
77
|
+
| DNS 切換 | 60-120 秒 | 中 | 多區域設定 |
|
|
78
|
+
| 程式碼 Revert | 數分鐘 | 中 | 乾淨的 git 歷史 |
|
|
79
|
+
| 資料庫還原 | 數小時 | 高 | 已驗證的備份 |
|
|
80
|
+
|
|
81
|
+
---
|
|
82
|
+
|
|
83
|
+
## 回滾前後檢查清單
|
|
84
|
+
|
|
85
|
+
### 回滾前(Pre-Rollback)
|
|
86
|
+
|
|
87
|
+
- [ ] 確認回滾目標版本是健康的
|
|
88
|
+
- [ ] 確認資料庫遷移向後相容
|
|
89
|
+
- [ ] 通知相關利害關係人
|
|
90
|
+
|
|
91
|
+
### 回滾後(Post-Rollback)
|
|
92
|
+
|
|
93
|
+
- [ ] 確認健康檢查在目標版本通過
|
|
94
|
+
- [ ] 將回滾事件寫入部署日誌
|
|
95
|
+
- [ ] 開立事故單進行根因分析
|
|
96
|
+
- [ ] 更新錯誤預算追蹤
|
|
97
|
+
|
|
98
|
+
---
|
|
99
|
+
|
|
100
|
+
## 相關標準
|
|
101
|
+
|
|
102
|
+
- [deployment-standards.md](deployment-standards.md) — 部署基礎策略
|
|
103
|
+
- [cd-deployment-strategies.md](cd-deployment-strategies.md) — 部署策略選用矩陣
|
|
104
|
+
- AI 格式:[../ai/standards/rollback-standards.ai.yaml](../ai/standards/rollback-standards.ai.yaml)
|
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
---
|
|
2
2
|
source: ../../CHANGELOG.md
|
|
3
|
-
source_version: 5.
|
|
4
|
-
translation_version: 5.
|
|
5
|
-
last_synced: 2026-04-
|
|
3
|
+
source_version: 5.3.0
|
|
4
|
+
translation_version: 5.3.0
|
|
5
|
+
last_synced: 2026-04-26
|
|
6
6
|
status: current
|
|
7
7
|
---
|
|
8
8
|
|
|
@@ -17,6 +17,17 @@ status: current
|
|
|
17
17
|
|
|
18
18
|
## [Unreleased]
|
|
19
19
|
|
|
20
|
+
## [5.3.0] - 2026-04-26
|
|
21
|
+
|
|
22
|
+
> **次版本发布**:四个新标准 + 一个新 Skill(XSPEC-085/064)—— `no-cicd-deployment`、`rollback-standards`、`cd-deployment-strategies`、`pipeline-security-gates`,以及无 CI/CD 环境的 `/deploy` Skill。标准总数:136。
|
|
23
|
+
|
|
24
|
+
### 新增
|
|
25
|
+
- **`no-cicd-deployment.ai.yaml`**(XSPEC-085 Phase 1):无 CI/CD 平台的三层部署架构 — `set -euo pipefail` + deploy.lock + 版本 tag 强制;Smoke Test + 自动 rollback;Blue-Green 切换 <30 秒。
|
|
26
|
+
- **`rollback-standards.ai.yaml`**(XSPEC-064 Phase 1):Rollback 触发条件矩阵 — 自动(error rate >2× baseline)、辅助(SLO 违反)、手动(延迟在 SLO 内)。Error budget <10% 升级为自动。P0–P3 严重级别与 SLA。
|
|
27
|
+
- **`cd-deployment-strategies.ai.yaml`**(XSPEC-064 Phase 1):部署策略选用矩阵 — blue-green / canary / rolling / recreate 决策树(流量 × 风险 × 成本)。含无 CI/CD 兼容性说明。
|
|
28
|
+
- **`pipeline-security-gates.ai.yaml`**(XSPEC-064 Phase 1):CI 安全检查点 — pre-commit secrets 扫描、post-build SAST、post-staging DAST、package 阶段 SCA+SBOM。Critical/High 阻断 pipeline;Medium 需要审核。
|
|
29
|
+
- **`/deploy` Skill**(`skills/deploy-assistant/`,XSPEC-085 Phase 1b):无 CI/CD 交互式部署脚本生成器,含繁体中文本地化翻译。
|
|
30
|
+
|
|
20
31
|
## [5.2.0] - 2026-04-24
|
|
21
32
|
|
|
22
33
|
> **次版本发布**:三项新标准/技能(XSPEC-080/081/082)—— `/release package` 子命令、`/push` 质量守门 Skill、以及 `agent-behavior-discipline` 标准(Karpathy 四大原则:问/减/准/测)。Bundle 一致性加固。文档集中至 dev-platform。标准总数:74。
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
source: ../../README.md
|
|
3
|
-
source_version: 5.
|
|
4
|
-
translation_version: 5.
|
|
3
|
+
source_version: 5.2.0
|
|
4
|
+
translation_version: 5.2.0
|
|
5
5
|
last_synced: 2026-04-22
|
|
6
6
|
status: current
|
|
7
7
|
---
|
|
@@ -14,7 +14,7 @@ status: current
|
|
|
14
14
|
|
|
15
15
|
> **语言**: [English](../../README.md) | [繁體中文](../zh-TW/README.md) | 简体中文
|
|
16
16
|
|
|
17
|
-
**版本**: 5.
|
|
17
|
+
**版本**: 5.3.0 | **发布日期**: 2026-04-13 | **授权**: [双重授权](../../LICENSE) (CC BY 4.0 + MIT)
|
|
18
18
|
|
|
19
19
|
语言无关、框架无关的软件项目文档标准。通过 AI 原生工作流,确保不同技术栈之间的一致性、质量和可维护性。
|
|
20
20
|
|
|
@@ -63,7 +63,7 @@ npx universal-dev-standards init
|
|
|
63
63
|
<!-- UDS_STATS_TABLE_START -->
|
|
64
64
|
| 类别 | 数量 | 说明 |
|
|
65
65
|
|----------|-------|-------------|
|
|
66
|
-
| **核心标准** |
|
|
66
|
+
| **核心标准** | 78 | 通用开发准则 |
|
|
67
67
|
| **AI Skills** | 48 | 互动式技能 |
|
|
68
68
|
| **斜线命令** | 48 | 快速操作 |
|
|
69
69
|
| **CLI 命令** | 6 | list, init, configure, check, update, skills |
|
|
@@ -80,8 +80,8 @@ UDS 采用 **双层执行模型 (Dual-Layer Execution Model)**,专为高速互
|
|
|
80
80
|
```mermaid
|
|
81
81
|
graph TD
|
|
82
82
|
A[AI 助手 / 开发者] --> B{执行层}
|
|
83
|
-
B -- "日常任务" --> C[技能层 Skills (.ai.yaml)]
|
|
84
|
-
B -- "深度审查" --> D[标准层 Standards (.md)]
|
|
83
|
+
B -- "日常任务" --> C["技能层 Skills (.ai.yaml)"]
|
|
84
|
+
B -- "深度审查" --> D["标准层 Standards (.md)"]
|
|
85
85
|
|
|
86
86
|
C --> C1[Token 优化]
|
|
87
87
|
C --> C2[互动式引导]
|
|
@@ -104,14 +104,14 @@ graph TD
|
|
|
104
104
|
|
|
105
105
|
| AI 工具 | 状态 | Skills | 斜线命令 | 配置文件 |
|
|
106
106
|
| :--- | :--- | :---: | :---: | :--- |
|
|
107
|
-
| **Claude Code** | ✅ 完整支持 | **
|
|
108
|
-
| **OpenCode** | ✅ 完整支持 | **
|
|
107
|
+
| **Claude Code** | ✅ 完整支持 | **29** | **33** | `CLAUDE.md` |
|
|
108
|
+
| **OpenCode** | ✅ 完整支持 | **29** | **33** | `AGENTS.md` |
|
|
109
109
|
| **Gemini CLI** | 🧪 预览版 | **18+** | **20+** | `GEMINI.md` |
|
|
110
110
|
| **Cursor** | ✅ 完整支持 | **核心** | **模拟支持** | `.cursorrules` |
|
|
111
111
|
| **Cline / Roo Code**| 🔶 部分支持 | **核心** | **工作流** | `.clinerules` |
|
|
112
112
|
| **Windsurf** | 🔶 部分支持 | ✅ | **规则书** | `.windsurfrules` |
|
|
113
113
|
|
|
114
|
-
> **状态图例**:✅ 完整支持 | 🧪
|
|
114
|
+
> **状态图例**:✅ 完整支持 | 🧪 预览版 | 🔶 部分支持 | ⏳ 计划中
|
|
115
115
|
|
|
116
116
|
---
|
|
117
117
|
|
|
@@ -153,6 +153,28 @@ uds uninstall # 从项目移除标准
|
|
|
153
153
|
|
|
154
154
|
---
|
|
155
155
|
|
|
156
|
+
## 🌐 生态系统
|
|
157
|
+
|
|
158
|
+
UDS 是 AsiaOstrich 三层产品架构中的**标准定义层**:
|
|
159
|
+
|
|
160
|
+
```
|
|
161
|
+
UDS(定义什么) → DevAP(代理如何执行) → VibeOps(完整生命周期)
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
| 层级 | 产品 | 角色 | 授权 |
|
|
165
|
+
|------|------|------|------|
|
|
166
|
+
| 标准 | **UDS** | 开发方法论框架 | MIT + CC BY 4.0 |
|
|
167
|
+
| 编排 | [DevAP](https://github.com/AsiaOstrich/dev-autopilot) | 代理无关的编排引擎 | MIT |
|
|
168
|
+
| 生命周期 | [VibeOps](https://github.com/AsiaOstrich/vibeops360) | AI 驱动的软件工厂 | AGPL-3.0-only |
|
|
169
|
+
|
|
170
|
+
- **UDS** 定义开发标准 → 供 DevAP(质量 Gate)和 VibeOps(代理管线)使用
|
|
171
|
+
- **DevAP** 使用 UDS 标准编排 AI 代理 → VibeOps 是其消费者之一
|
|
172
|
+
- **VibeOps** 提供完整软件生命周期 → 通过 `uds init` 集成 UDS(一次复制)
|
|
173
|
+
|
|
174
|
+
UDS 保持**工具无关性**:支持 Claude Code、OpenCode、Gemini CLI、Cursor、Cline 和 Windsurf。DevAP 和 VibeOps 是消费者,并非必要依赖。
|
|
175
|
+
|
|
176
|
+
---
|
|
177
|
+
|
|
156
178
|
## 📄 授权
|
|
157
179
|
|
|
158
180
|
| 组件 | 授权 |
|
|
@@ -160,6 +182,23 @@ uds uninstall # 从项目移除标准
|
|
|
160
182
|
| **文档内容** | [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) |
|
|
161
183
|
| **CLI 工具** | [MIT](../../cli/LICENSE) |
|
|
162
184
|
|
|
185
|
+
## 致谢
|
|
186
|
+
|
|
187
|
+
UDS 的架构灵感来自以下杰出的开源项目:
|
|
188
|
+
|
|
189
|
+
| 项目 | 借鉴概念 | 授权 |
|
|
190
|
+
|------|---------|------|
|
|
191
|
+
| [Superpowers](https://github.com/obra/superpowers) | 系统性调试、代理调度、验证证据 | MIT |
|
|
192
|
+
| [GSD](https://github.com/gsd-build/get-shit-done) | 结构化任务定义、可追溯性矩阵、验证循环上限 | MIT |
|
|
193
|
+
| [PAUL](https://github.com/ChristopherKahler/paul) | Plan-Apply-Unify 循环、验收驱动开发 | MIT |
|
|
194
|
+
| [CARL](https://github.com/ChristopherKahler/carl) | 上下文感知加载、动态规则注入 | MIT |
|
|
195
|
+
| [CrewAI](https://github.com/crewAIInc/crewAI) | 多代理通信协议、上下文预算追踪 | MIT |
|
|
196
|
+
| [LangGraph](https://github.com/langchain-ai/langgraph) | 工作流状态协议、HITL 中断检查点 | MIT |
|
|
197
|
+
| [OpenHands](https://github.com/All-Hands-AI/OpenHands) | 事件溯源、动作-观察流模式 | MIT |
|
|
198
|
+
| [DSPy](https://github.com/stanfordnlp/dspy) | 代理签名、结构化 I/O 契约 | MIT |
|
|
199
|
+
|
|
200
|
+
> **注意**:UDS 仅借鉴概念与方法论,不包含上述项目的任何源代码。
|
|
201
|
+
|
|
163
202
|
---
|
|
164
203
|
|
|
165
204
|
**由开源社区用 ❤️ 维护**
|
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
---
|
|
2
2
|
source: ../../CHANGELOG.md
|
|
3
|
-
source_version: 5.
|
|
4
|
-
translation_version: 5.
|
|
5
|
-
last_synced: 2026-04-
|
|
3
|
+
source_version: 5.3.0
|
|
4
|
+
translation_version: 5.3.0
|
|
5
|
+
last_synced: 2026-04-26
|
|
6
6
|
status: current
|
|
7
7
|
---
|
|
8
8
|
|
|
@@ -17,6 +17,17 @@ status: current
|
|
|
17
17
|
|
|
18
18
|
## [Unreleased]
|
|
19
19
|
|
|
20
|
+
## [5.3.0] - 2026-04-26
|
|
21
|
+
|
|
22
|
+
> **次版本發布**:四個新標準 + 一個新 Skill(XSPEC-085/064)—— `no-cicd-deployment`、`rollback-standards`、`cd-deployment-strategies`、`pipeline-security-gates`,以及無 CI/CD 環境的 `/deploy` Skill。標準總數:136。
|
|
23
|
+
|
|
24
|
+
### 新增
|
|
25
|
+
- **`no-cicd-deployment.ai.yaml`**(XSPEC-085 Phase 1):無 CI/CD 平台的三層部署架構 — `set -euo pipefail` + deploy.lock + 版本 tag 強制;Smoke Test + 自動 rollback;Blue-Green 切換 <30 秒。
|
|
26
|
+
- **`rollback-standards.ai.yaml`**(XSPEC-064 Phase 1):Rollback 觸發條件矩陣 — 自動(error rate >2× baseline)、輔助(SLO 違反)、手動(延遲在 SLO 內)。Error budget <10% 升級為自動。P0–P3 嚴重級別與 SLA。
|
|
27
|
+
- **`cd-deployment-strategies.ai.yaml`**(XSPEC-064 Phase 1):部署策略選用矩陣 — blue-green / canary / rolling / recreate 決策樹(流量 × 風險 × 成本)。含無 CI/CD 相容性說明。
|
|
28
|
+
- **`pipeline-security-gates.ai.yaml`**(XSPEC-064 Phase 1):CI 安全檢查點 — pre-commit secrets 掃描、post-build SAST、post-staging DAST、package 階段 SCA+SBOM。Critical/High 阻擋 pipeline;Medium 需要審核。
|
|
29
|
+
- **`/deploy` Skill**(`skills/deploy-assistant/`,XSPEC-085 Phase 1b):無 CI/CD 互動式部署腳本生成器,含繁體中文本地化翻譯。
|
|
30
|
+
|
|
20
31
|
## [5.2.0] - 2026-04-24
|
|
21
32
|
|
|
22
33
|
> **次版本發布**:三項新標準/技能(XSPEC-080/081/082)—— `/release package` 子命令、`/push` 品質守門 Skill、以及 `agent-behavior-discipline` 標準(Karpathy 四大原則:問/減/準/測)。Bundle 一致性加固。文件集中至 dev-platform。標準總數:74。
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
source: ../../README.md
|
|
3
|
-
source_version: 5.
|
|
4
|
-
translation_version: 5.
|
|
3
|
+
source_version: 5.2.0
|
|
4
|
+
translation_version: 5.2.0
|
|
5
5
|
last_synced: 2026-04-22
|
|
6
6
|
status: current
|
|
7
7
|
---
|
|
@@ -14,7 +14,7 @@ status: current
|
|
|
14
14
|
|
|
15
15
|
> **語言**: [English](../../README.md) | 繁體中文 | [简体中文](../zh-CN/README.md)
|
|
16
16
|
|
|
17
|
-
**版本**: 5.
|
|
17
|
+
**版本**: 5.3.0 | **發布日期**: 2026-04-13 | **授權**: [雙重授權](../../LICENSE) (CC BY 4.0 + MIT)
|
|
18
18
|
|
|
19
19
|
語言無關、框架無關的軟體專案文件標準。透過 AI 原生工作流,確保不同技術堆疊之間的一致性、品質和可維護性。
|
|
20
20
|
|
|
@@ -63,7 +63,7 @@ npx universal-dev-standards init
|
|
|
63
63
|
<!-- UDS_STATS_TABLE_START -->
|
|
64
64
|
| 類別 | 數量 | 說明 |
|
|
65
65
|
|----------|-------|-------------|
|
|
66
|
-
| **核心標準** |
|
|
66
|
+
| **核心標準** | 78 | 通用開發準則 |
|
|
67
67
|
| **AI Skills** | 48 | 互動式技能 |
|
|
68
68
|
| **斜線命令** | 48 | 快速操作 |
|
|
69
69
|
| **CLI 指令** | 6 | list, init, configure, check, update, skills |
|
|
@@ -80,8 +80,8 @@ UDS 採用 **雙層執行模型 (Dual-Layer Execution Model)**,專為高速互
|
|
|
80
80
|
```mermaid
|
|
81
81
|
graph TD
|
|
82
82
|
A[AI 助手 / 開發者] --> B{執行層}
|
|
83
|
-
B -- "日常任務" --> C[技能層 Skills (.ai.yaml)]
|
|
84
|
-
B -- "深度審查" --> D[標準層 Standards (.md)]
|
|
83
|
+
B -- "日常任務" --> C["技能層 Skills (.ai.yaml)"]
|
|
84
|
+
B -- "深度審查" --> D["標準層 Standards (.md)"]
|
|
85
85
|
|
|
86
86
|
C --> C1[Token 最佳化]
|
|
87
87
|
C --> C2[互動式引導]
|
|
@@ -104,8 +104,8 @@ graph TD
|
|
|
104
104
|
|
|
105
105
|
| AI 工具 | 狀態 | Skills | 斜線命令 | 設定檔 |
|
|
106
106
|
| :--- | :--- | :---: | :---: | :--- |
|
|
107
|
-
| **Claude Code** | ✅ 完整支援 | **
|
|
108
|
-
| **OpenCode** | ✅ 完整支援 | **
|
|
107
|
+
| **Claude Code** | ✅ 完整支援 | **29** | **33** | `CLAUDE.md` |
|
|
108
|
+
| **OpenCode** | ✅ 完整支援 | **29** | **33** | `AGENTS.md` |
|
|
109
109
|
| **Gemini CLI** | 🧪 預覽版 | **18+** | **20+** | `GEMINI.md` |
|
|
110
110
|
| **Cursor** | ✅ 完整支援 | **核心** | **模擬支援** | `.cursorrules` |
|
|
111
111
|
| **Cline / Roo Code**| 🔶 部分支援 | **核心** | **工作流** | `.clinerules` |
|
|
@@ -153,6 +153,28 @@ uds uninstall # 從專案移除標準
|
|
|
153
153
|
|
|
154
154
|
---
|
|
155
155
|
|
|
156
|
+
## 🌐 生態系統
|
|
157
|
+
|
|
158
|
+
UDS 是 AsiaOstrich 三層產品架構中的**標準定義層**:
|
|
159
|
+
|
|
160
|
+
```
|
|
161
|
+
UDS(定義什麼) → DevAP(代理人如何執行) → VibeOps(完整生命週期)
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
| 層級 | 產品 | 角色 | 授權 |
|
|
165
|
+
|------|------|------|------|
|
|
166
|
+
| 標準 | **UDS** | 開發方法論框架 | MIT + CC BY 4.0 |
|
|
167
|
+
| 編排 | [DevAP](https://github.com/AsiaOstrich/dev-autopilot) | 代理人無關的編排引擎 | MIT |
|
|
168
|
+
| 生命週期 | [VibeOps](https://github.com/AsiaOstrich/vibeops360) | AI 驅動的軟體工廠 | AGPL-3.0-only |
|
|
169
|
+
|
|
170
|
+
- **UDS** 定義開發標準 → 供 DevAP(品質 Gate)和 VibeOps(代理人管線)使用
|
|
171
|
+
- **DevAP** 使用 UDS 標準編排 AI 代理人 → VibeOps 是其消費者之一
|
|
172
|
+
- **VibeOps** 提供完整軟體生命週期 → 透過 `uds init` 整合 UDS(一次複製)
|
|
173
|
+
|
|
174
|
+
UDS 保持**工具無關性**:支援 Claude Code、OpenCode、Gemini CLI、Cursor、Cline 和 Windsurf。DevAP 和 VibeOps 是消費者,並非必要依賴。
|
|
175
|
+
|
|
176
|
+
---
|
|
177
|
+
|
|
156
178
|
## 📄 授權
|
|
157
179
|
|
|
158
180
|
| 元件 | 授權 |
|
|
@@ -160,6 +182,23 @@ uds uninstall # 從專案移除標準
|
|
|
160
182
|
| **文件內容** | [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) |
|
|
161
183
|
| **CLI 工具** | [MIT](../../cli/LICENSE) |
|
|
162
184
|
|
|
185
|
+
## 致謝
|
|
186
|
+
|
|
187
|
+
UDS 的架構靈感來自以下傑出的開源專案:
|
|
188
|
+
|
|
189
|
+
| 專案 | 借鑑概念 | 授權 |
|
|
190
|
+
|------|---------|------|
|
|
191
|
+
| [Superpowers](https://github.com/obra/superpowers) | 系統性除錯、代理人派遣、驗證證據 | MIT |
|
|
192
|
+
| [GSD](https://github.com/gsd-build/get-shit-done) | 結構化任務定義、可追蹤性矩陣、驗證迴圈上限 | MIT |
|
|
193
|
+
| [PAUL](https://github.com/ChristopherKahler/paul) | Plan-Apply-Unify 迴圈、驗收驅動開發 | MIT |
|
|
194
|
+
| [CARL](https://github.com/ChristopherKahler/carl) | 情境感知載入、動態規則注入 | MIT |
|
|
195
|
+
| [CrewAI](https://github.com/crewAIInc/crewAI) | 多代理人通訊協定、情境預算追蹤 | MIT |
|
|
196
|
+
| [LangGraph](https://github.com/langchain-ai/langgraph) | 工作流程狀態協定、HITL 中斷檢查點 | MIT |
|
|
197
|
+
| [OpenHands](https://github.com/All-Hands-AI/OpenHands) | 事件溯源、動作-觀察串流模式 | MIT |
|
|
198
|
+
| [DSPy](https://github.com/stanfordnlp/dspy) | 代理人簽名、結構化 I/O 契約 | MIT |
|
|
199
|
+
|
|
200
|
+
> **注意**:UDS 僅借鑑概念與方法論,不包含上述專案的任何原始碼。
|
|
201
|
+
|
|
163
202
|
---
|
|
164
203
|
|
|
165
204
|
**由開源社群用 ❤️ 維護**
|