机器形态 1：Prompt 前缀（给 AI 编程工具）— 自动注入 Claude Code / Cursor 上下文
# 由编译管线从 ERR-001.yaml 自动生成
# 版本: v1.1.0 | 生成时间: 2026-07-12T13:40:00Z
[SEMANTIC_CONSTRAINTS_START]
你在生成错误状态界面时，必须遵守以下语义分级规则：
1. FATAL（系统级故障）：
- 必须使用红色脉冲 + 八边形警告图标
- 必须提供恢复路径（刷新页面 / 导出历史）
- 禁止仅显示"出错了"等模糊文案
2. TRANSIENT（网络抖动）：
- 必须使用灰色加载 + 旋转图标
- 禁止红色背景
- 必须说明"系统正在自动恢复"
3. RETRYABLE（限流）：
- 必须使用黄色提示 + 时钟图标
- 必须显示倒计时
- 必须提供升级入口
4. DEGRADED（部分可用）：
- 必须使用蓝色提示 + 信息图标
- 必须说明哪些功能仍然可用
- 必须提供"继续生成"选项
不可变边界（强制执行）：
- 禁止所有错误状态共用同一种红色视觉表达
- 每个错误级别必须提供明确的用户行动指引
[SEMANTIC_CONSTRAINTS_END]
机器形态 2：JSON Schema（给结构校验器）— CI 流水线校验组件 Props
// 由编译管线从 ERR-001.yaml 自动生成
// 版本: v1.1.0
{
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "ErrorSeveritySchema",
"type": "object",
"properties": {
"error_severity": {
"type": "string",
"enum": ["fatal", "transient", "retryable", "degraded"],
"description": "错误严重程度级别"
},
"visual_mapping": {
"type": "object",
"properties": {
"color_token": {
"type": "string",
"enum": ["status.critical", "status.neutral", "status.warning", "status.info"]
},
"motion_token": { "type": "string" },
"icon_token": { "type": "string" }
},
"required": ["color_token", "icon_token"]
},
"user_action": {
"type": "array",
"minItems": 1,
"items": {
"type": "object",
"properties": {
"label": { "type": "string" },
"action": { "type": "string" }
},
"required": ["label", "action"]
}
}
},
"required": ["error_severity", "visual_mapping", "user_action"],
"if": {
"properties": { "error_severity": { "const": "retryable" } }
},
"then": {
"properties": {
"visual_mapping": {
"properties": {
"color_token": { "not": { "const": "status.critical" } }
}
}
}
}
}
机器形态 3：Checklist（给设计师走查）— 可打印的逐项核对清单
fatal 级别是否提供恢复路径
合格标准：必须有"刷新页面"或"导出历史"
ERR-001 § fatal.user_action
transient 级别是否使用红色
合格标准：禁止使用红色背景
ERR-001 § transient.llm_constraints
retryable 级别是否显示倒计时
合格标准：必须显示剩余等待时间
ERR-001 § retryable.llm_constraints
degraded 级别是否说明可用功能
合格标准：必须说明哪些功能仍然可用
ERR-001 § degraded.llm_constraints
机器形态 4：CI 规则（给自动化流水线）— GitHub Actions / ESLint 自动拦截
# .github/workflows/semantic-check.yml
# 由编译管线从 ERR-001.yaml 自动生成
name: Semantic Contract Check
on: [pull_request]
jobs:
semantic-check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Load Semantic Contract
run: |
pip install semantic-pipeline
sp-load intent/err-001.yaml
- name: Check Error Severity Colors
run: |
sp-check \
--rule "error_severity_color" \
--forbid "status.critical" for "retryable" \
--forbid "status.critical" for "transient" \
--forbid "status.critical" for "degraded"
failure(): |
echo "❌ 语义违规：错误状态颜色映射不符合契约"
echo "修正建议："
echo " - retryable → status.warning（黄色）"
echo " - transient → status.neutral（灰色）"
echo " - degraded → status.info（蓝色）"
exit 1
- name: Check User Actions
run: |
sp-check \
--rule "user_action_required" \
--min-actions 1 \
--require-labels ["刷新页面", "导出历史", "等待自动恢复"]
failure(): |
echo "❌ 语义违规：错误状态缺少用户行动指引"
exit 1