@stackonward/cli 0.0.1 → 1.0.0

package/dist/resources/templates/go-backend/.claude/docs/mediagen-provider-quick-reference.md

@@ -0,0 +1,195 @@
+# Mediagen Provider Quick Reference
+
+> **Upstream scope**: this is the complete dated OneX provider snapshot. It is reference material for platform integration, not the generated backend capability inventory or current provider availability.
+
+> 6 个 active providers + admin runtime 配置面板 速查表。完整接入流程见 `mediagen-provider-onboarding-sop.md`。
+> Snapshot date: 2026-04-26 (admin-integrated, commits `f2338a6d` → `211ed024`)
+
+---
+
+## Provider × Endpoint Matrix
+
+| Provider | Base URL | Auth | Transport | Submit Source | Poll Source | Cancel | Quirks |
+|----------|----------|------|-----------|---------------|-------------|--------|--------|
+| `duomi` | `https://duomiapi.com` | submit query `?key=` (secondary)；poll header `Authorization: <raw>` (primary) | `http_json_poll` | `req.Endpoint` (必填) | `firstNonEmpty(req.Endpoint, "/api/video/pix/feed?task_id=%s")` | ✗ | 双凭证；nano-banana 同步走 `sync:<base64>` ExternalID 短路 |
+| `wavespeed` | `https://api.wavespeed.ai` | header `Authorization: Bearer <key>` | `http_json_poll` | `req.Endpoint` (必填) | const `/api/v3/predictions/%s/result` | ✗ | NSFW 走 `has_nsfw_contents[]` 后置探测合成 `nsfw` code |
+| `vidu` | `https://api.vidu.com` | header `Authorization: Token <key>` (字面量 "Token " 前缀) | `http_json_poll` | `req.Endpoint` (必填) | const `/ent/v2/tasks/%s/creations` | ✗ | 错误码 `{code,reason,message}` 字符串枚举 |
+| `wan` | `https://dashscope.aliyuncs.com` | header `Authorization: Bearer <key>` + `X-DashScope-Async: enable` | `http_json_poll` | `req.Endpoint` (必填) | const `/api/v1/tasks/%s` | ✗ | 状态大写枚举；失败 code 在 `output.code` |
+| `pixfree` | `https://app-api.pixverse.ai/creative_platform` | n/a (browser automation) | `browser_automation` | n/a (Temporal stealthActivity) | n/a | ✗ | 唯一非 HTTP；按 model_code 路由 5 种 payload |
+| `yunwu` | `https://yunwu.ai` | header `Authorization: Bearer <key>` | `http_json_poll` | `req.Endpoint` (必填) | const `/v1/video/query?id=%s` | ✗ | HTTP 200 + `error` 非空 → 强制 `Status=Failed` |
+
+---
+
+## Capability Matrix
+
+| Operation | duomi | wavespeed | vidu | wan | pixfree | yunwu |
+|-----------|:-----:|:---------:|:----:|:---:|:-------:|:-----:|
+| `t2i` | ✓ | ✓ | - | - | - | - |
+| `i2i` | ✓ | ✓ | - | - | - | - |
+| `t2v` | ✓ | ✓ | - | ✓ | ✓ | ✓ |
+| `i2v` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| `extend` | - | - | - | - | ✓ | - |
+| `lip_sync` | - | - | - | - | ✓ | - |
+| `v2v` / `upscale` / `frame_extract` | - | - | - | - | - | - |
+
+> 共 27 条 active lanes。
+
+---
+
+## Architectural Invariants（速记）
+
+1. 失败归一化只走 `base.MapProviderFailure(FailureContext)`
+2. 禁止 `strings.Contains` 做错误分类
+3. `req.Endpoint` 是 Submit 路径唯一真相源
+4. `req.FailureMapper` 必须透传到 `MapProviderFailure(LaneMapper: ...)`
+5. `domain.FailureReasonCode` 仅 9 类合法（见下）
+6. 不伪造 idempotency；Provider 真实支持时在 GoDoc 注明
+7. `ProviderTelemetry` 4 字段（HTTPStatus/LatencyMs/QueueMs/CostUSD）成功路径必填
+8. `transport_retry_count = activity.GetInfo(ctx).Attempt - 1`（Temporal SDK 重试计数）
+
+---
+
+## FailureReasonCode 9 类枚举
+
+| Code | Retryable |
+|------|-----------|
+| `prompt_policy_violation` | ✗ |
+| `input_image_policy_violation` | ✗ |
+| `input_image_invalid` | ✗ |
+| `output_policy_violation` | ✗ |
+| `timeout` | ✓ |
+| `rate_limit` | ✓ |
+| `provider_error` | HTTP 5xx 时 ✓ |
+| `internal_error` | ✗ |
+| `user_canceled` | ✗ |
+
+> Auth / billing / bad_input 全部归 `provider_error`。
+
+---
+
+## 接入新 Provider 的高层流程
+
+```
+A. Research (10 questions: base_url, auth, endpoints, status enum, error codes...)
+   ↓
+B. Migration: 注册 Provider + Models + Lane Revisions + failure_mapper
+   ↓
+C. Adapter: <provider>/adapter.go (Submit / Poll / Cancel)
+   ↓ Wire 注册到 providers/registry.go
+D. Capability gating + cost (按需)
+   ↓
+E. Credit deduction (自动继承,无需写代码)
+   ↓
+F. failure mapper 规则细化 (在 lane revision JSON,不改 adapter)
+   ↓
+G. Telemetry (Submit/Poll 已 populated)
+   ↓
+H. Tests (≥10 项最小用例)
+   ↓
+I. make wire
+   ↓
+J. go vet + go build + go test
+   ↓
+K. Migration apply (dev DB)
+```
+
+---
+
+## Reference Implementation 速查
+
+| 类型 | 复制谁 |
+|------|--------|
+| HTTP 异步 + 字符串 error code | `vidu/adapter.go` |
+| HTTP 异步 + 嵌套响应 (`output.*`) | `wan/adapter.go` |
+| HTTP 同步 (立即返回结果) | `duomi/adapter.go` (nano-banana 分支) |
+| 浏览器自动化 / 非 HTTP | `pixfree/adapter.go` |
+| 内容审核是 success flag (非 error) | `wavespeed/adapter.go` |
+| 自定义必填 header | `wan/adapter.go` |
+| Token 前缀 auth | `vidu/adapter.go` |
+| Query string auth | `duomi/adapter.go` |
+| HTTP 200 + error 业务失败 | `yunwu/adapter.go` |
+
+---
+
+## Common Pitfalls（5 大坑）
+
+1. 自创 reason code（只能用 9 类合法值）
+2. 文案匹配错误分类（禁止 `strings.Contains`）
+3. `LaneMapper: nil`（必传 `req.FailureMapper`）
+4. adapter hardcode submit endpoint（`req.Endpoint` 是真相源）
+5. status / error 字段独立处理（error 非空 → 强制 `Status=Failed`）
+
+---
+
+## Admin UI Quick Links
+
+| 路径 | 用途 |
+|------|------|
+| `/ai/runtime/providers` | Provider CRUD（Create/Edit Drawer + AuthProfileBindingEditor + Toggle / Delete 行级操作） |
+| `/ai/runtime/lanes` | Lane CRUD 列表 + Drawer |
+| `/ai/runtime/lanes/:laneCode/revisions` | Lane Revision 编排工作台（XL 页：context strip + RevisionTimeline + 11-tab 编辑器 + Save/Publish/Rollback/Dry-run） |
+| `/ai/runtime/generations` | 跨 product Generations admin 列表 + Detail Drawer |
+| `/ai/runtime/execution-logs` | 顶级 execution log 搜索 + 侧拉 request/response snapshot |
+
+---
+
+## End-to-End Onboarding（admin UI 7 步）
+
+1. `/ai/runtime/providers` → **Create Provider** → 填 name / display_name / base_url / api_key + auth_profiles bindings
+2. `/ai/control-plane/models` → 注册 model（关联 provider_id）
+3. `/ai/runtime/lanes` → **Create Lane** → 填 code / operation / modality / transport_class / provider_id / model_code
+4. `/ai/runtime/lanes/:laneCode/revisions` → **Create Revision** → 走 11 个 tab 用可视化编辑器配置
+5. **Dry-run** → 粘贴 sample input → 校验 normalized_request + applied_transforms + 一键 Copy as cURL
+6. **Publish** → 确认 modal → revision 即刻生效
+7. （故障时）**Rollback** → 确认 modal → 上一 published revision 恢复 active
+
+---
+
+## Admin Endpoints Cheat Sheet
+
+| Method + URL | 权限 | 用途 |
+|-------------|------|------|
+| `POST /admin/ai/providers/:id/toggle` | `ai_provider:write` | Provider 行级灰度开关 |
+| `POST /admin/ai/models/:id/toggle` | `ai_model:write` | Model 行级灰度开关 |
+| `POST /admin/ai/provider-lanes/:id/revisions/:revisionId/rollback` | `ai_lane:rollback` | 回滚到上一 published revision（无 prior published 时返回 `apierror.Conflict`） |
+| `GET /admin/ai/provider-lanes/:id/revisions/:revisionId/diff?against=:other` | `ai_lane:read` | 两 revision 字段级差异（snake_case `{left_revision_id, right_revision_id, changes}`） |
+| `POST /admin/ai/provider-lanes/:id/revisions/:revisionId/dry-run` | `ai_lane:dry_run` | 不调 Provider / 不写库；返回 normalized_request + applied_transforms + cURL |
+| `GET /admin/v1/mediagen/execution-logs` | `mediagen:execution_log:read` | 跨 generation 顶级执行日志搜索（按 lane_code / phase / outcome / 时间窗口） |
+| `POST /admin/ai/provider-lanes/:id/revisions` | `ai_lane:write` | 创建 lane revision；服务端跑 `ValidateLaneRevisionFields`，bad config 返回 `apierror.BadRequest("lane_revision_invalid", "<dot.path>")` |
+| `POST /admin/ai/provider-lanes/:id/revisions/:revisionId/publish` | `ai_lane:publish` | 把 draft revision 设为 active |
+
+> Provider CRUD URL 用**数字 id**（`/admin/ai/providers/:id`），不是 code（`ProviderVO` 同时暴露 `id` 数字 + `code` 字符串）。
+
+---
+
+## 服务端 JSON Schema 强校验（I-9）
+
+`aiconfig.ValidateLaneRevisionFields` 校验 12 个 JSONB 字段：
+
+```
+endpoint_config / auth_config / submit_config / poll_config / cancel_config /
+request_defaults / input_schema / request_mapper / response_normalizer /
+failure_mapper / telemetry_extractor / retry_policy
+```
+
+bad config 在 Save / Publish 阶段直接拒收，前端按 `param` 字段路径精确高亮（Stripe `parameter_invalid` 风格）。
+
+---
+
+## 9 个可视化编辑器（components/platform/）
+
+| 组件 | 编辑字段 | 风格参考 |
+|------|---------|---------|
+| `AuthProfileBindingEditor` | Provider.auth_profiles bindings | AWS IAM |
+| `FailureMapperRuleBuilder` | LaneRevision.failure_mapper.rules | Stripe Radar |
+| `RequestMapperEditor` | LaneRevision.request_mapper.transforms | from→to + transform |
+| `ResponseNormalizerEditor` | LaneRevision.response_normalizer.paths | JSONPath + sample test pane |
+| `RetryPolicyEditor` | LaneRevision.retry_policy | ECharts log-scale 曲线 |
+| `RevisionTimeline` | 全部 revisions | 垂直时间轴 + 状态徽章 |
+| `RevisionDiffViewer` | 两 revision diff | Monaco diff |
+| `LaneRevisionPublishDialog` | publish 操作 | 确认 modal |
+| `LaneRevisionDryRunDrawer` | dry-run 操作 | sample input + Copy as cURL |
+
+---
+
+> **完整 SOP**: `backend/.claude/docs/mediagen-provider-onboarding-sop.md`

package/dist/resources/templates/go-backend/.claude/docs/module-standards.md

@@ -0,0 +1,309 @@
+# Module Structure Templates
+
+> Directory structures and decision tree. Rules are in `CLAUDE.md`.
+
+## File Creation Decision Tree
+
+```
+Request input?        → struct + binding tag            → dto.go (user) / dto_admin.go (admin)
+Response output?      → struct + ToXxxResponse()        → vo.go (user) / vo_admin.go (admin)
+Fixed values?         → string const / iota             → enum.go
+Magic number/prefix?  → const block                     → constants.go
+Internal contract?    → interface                       → 消费方 package 中定义
+Domain model?         → struct                          → model.go (domain/)
+Domain error?         → sentinel var / error type       → errors.go
+Domain event?         → struct                          → internal/sharedevents/events.go
+None of the above?    → Does this file belong in this package at all?
+```
+
+### VO/DTO 受众分离规则
+
+Handler 已按受众分文件（`handler.go` + `handler_admin.go`），VO/DTO 同步对齐：
+
+| 受众 | DTO | VO | Handler |
+|------|-----|----|---------|
+| 用户侧（public/authenticated） | `dto.go` | `vo.go` | `handler.go` |
+| 管理侧（admin） | `dto_admin.go` | `vo_admin.go` | `handler_admin.go` |
+
+**拆分触发规则**：
+- admin 和 user 共享完全相同的 Response struct → 留在 `vo.go`，不拆
+- admin Response 有 3+ 独立字段或独立 struct → 拆到 `vo_admin.go`
+- 新模块一律从分离开始（`dto.go` + `dto_admin.go` + `vo.go` + `vo_admin.go`）
+- 共享的转换函数（如 `ToAssetResponse()` 两边都用）→ 留在 `vo.go`，`vo_admin.go` import 它
+
+## Full DDD Module (identity, notification)
+
+```
+{module}/
+├── domain/
+│   ├── model.go              # 领域模型 (aggregate root + entities)
+│   ├── enum.go               # 领域枚举
+│   ├── repository.go         # Repository 接口定义
+│   ├── valueobject.go        # (optional) DDD Value Objects
+│   └── event.go              # (optional) 领域事件（仅内部事件，跨模块事件在 sharedevents）
+├── application/
+│   ├── service.go            # 主 Service（或多个 {name}_service.go）
+│   ├── handler.go            # 用户侧 HTTP handler
+│   ├── handler_admin.go      # 管理侧 HTTP handler
+│   ├── dto.go                # 用户侧请求 DTO structs
+│   ├── dto_admin.go          # 管理侧请求 DTO structs
+│   ├── vo.go                 # 用户侧响应 VO structs + ToXxxResponse()
+│   ├── vo_admin.go           # 管理侧响应 VO structs + ToAdminXxxResponse()
+│   └── listener.go           # (optional) 事件监听器
+├── infrastructure/
+│   ├── persistence.go        # Repository 接口的 GORM 实现
+│   ├── cache.go              # (optional) 缓存实现
+│   ├── crypto.go             # (optional) 加密实现
+│   └── {provider}.go         # (optional) 外部服务适配器 (email.go, sms.go)
+├── module.go                 # Module facade（手动组装）
+├── provider.go               # Wire ProviderSet 定义
+└── wire.go                   # (optional) Wire injector（仅在独立部署时）
+```
+
+## Full DDD Module with Application Subdivision (identity)
+
+Use this structure when application/ meets subdivision criteria (service files > 6 AND 3+ isolated service groups).
+
+```
+{module}/
+├── domain/
+│   ├── model.go, enum.go, repository.go, interfaces.go, events.go, ...
+├── application/
+│   ├── {subdomain_a}/           # 独立子域包
+│   │   ├── service.go
+│   │   ├── handler.go
+│   │   ├── dto.go
+│   │   └── vo.go
+│   ├── {subdomain_b}/
+│   │   └── ...
+│   ├── admin/                   # 跨子域编排
+│   │   └── handler.go
+│   └── listener.go              # 跨子域事件监听
+├── infrastructure/
+│   └── persistence.go
+├── module.go
+└── provider.go
+```
+
+Sub-package rules:
+- Each sub-package is an independent Go package, package name = subdomain name
+- Standard files: service.go, handler.go, dto.go, vo.go (optional)
+- Shared helper ownership follows the existing consumer boundary: search and reuse the owning helper; keep single-consumer logic private.
+- Cross-subdomain orchestration (admin handler, event listener) stays at application/ root
+- Import direction: admin/ → concrete subdomains/ → domain/, reverse references FORBIDDEN
+
+## Simplified DDD Module (user)
+
+```
+{module}/
+├── domain/
+│   ├── model.go              # 领域模型
+│   ├── enum.go               # 领域枚举
+│   ├── repository.go         # Repository 接口
+│   └── event.go              # (optional) 领域事件
+├── application/
+│   ├── service.go            # Service
+│   ├── dto.go                # 请求 DTO
+│   ├── vo.go                 # 响应 VO
+│   └── listener.go           # (optional) 事件监听
+├── infrastructure/
+│   └── persistence.go        # GORM 实现
+├── handler.go
+└── provider.go
+```
+
+## Flat Module (tenant, audit)
+
+```
+{module}/
+├── model.go                  # 数据模型
+├── enum.go                   # (optional)
+├── service.go                # 业务逻辑
+├── repository.go             # Repository 接口 + 实现（简单模块可合并）
+├── dto.go                    # 请求 DTO
+├── vo.go                     # 响应 VO
+├── handler.go                # HTTP Handler
+└── provider.go               # Wire ProviderSet
+```
+
+### Audit Module (Flat, Three-Table Architecture)
+
+```
+internal/core/audit/          # Flat module (three-table: access/audit/login)
+├── model.go                  # AccessLog + AuditLog + LoginLog + ChangesPayload + MetadataPayload
+├── enum.go                   # ActorType + AuditAction + AuditCategory + RiskLevel + LoginAction + LoginMethod
+├── constants.go              # skipPaths / skipMethods
+├── context.go                # Enrich() / EnrichChanges() / EnrichMetadata() context injection
+├── errors.go                 # ErrAuditBufferFull
+├── dto.go                    # AccessEntry / AuditEntry / LoginEntry (Service input)
+├── dto_admin.go              # AdminListAccessLogsRequest / AdminListAuditLogsRequest / AdminListLoginLogsRequest
+├── vo_admin.go               # AdminAccessLogResponse / AdminAuditLogResponse / AdminLoginLogResponse + transformers
+├── repository.go             # AccessLogRepository + AuditRepository + LoginLogRepository (interface + GORM impl)
+├── service.go                # AuditService (three-buffer async write) + AuditQueryService (read-write separation)
+├── middleware.go             # AuditMiddleware (L1: HTTP → sys_access_logs + conditional sys_audit_logs)
+├── listener.go               # AuditListener (L2: EventBus → sys_audit_logs / sys_login_logs routing, 143 events)
+├── handler.go                # AuditHandler + AccessLogHandler + LoginLogHandler
+├── router.go                 # /audit-logs + /access-logs + /login-logs route registration
+├── partition_job.go          # Partition auto-management (5 cron tasks: create/cleanup partitions)
+└── provider.go               # Wire ProviderSet (12 constructors)
+```
+
+> Audit module uses Flat tier but has more files due to three-table architecture (access/audit/login) and multi-layer collection (L1/L2/L3). Complexity comes from coverage breadth (143 events), not domain depth.
+
+## Platform Base Module (product)
+
+Product registry is a Flat module serving as the platform's product source of truth.
+
+```
+platform/product/
+├── model.go                  # Product 实体
+├── enum.go                   # ProductStatus 枚举
+├── errors.go                 # 错误码
+├── service.go                # CRUD + 查询
+├── handler_admin.go          # Admin API (POST/GET/PUT)
+├── dto.go                    # 请求 DTO
+├── vo.go                     # 响应 VO + ToProductResponse()
+├── router.go                 # 路由注册
+└── provider.go               # Wire ProviderSet
+```
+
+Key rules:
+- `p_products.code` is the **canonical product identifier** across the entire platform
+- ALL other modules reference products via `product_code VARCHAR(50)`
+- NEVER use `product_id`, `app_id`, or any other name for product references
+- Product code format: `snake_case`, regex `^[a-z][a-z0-9_]{1,49}$`
+- Product enums defined ONLY in `common/types.Product`, never duplicated in module enums
+
+## Core Infrastructure Module (config, database, cache, logger)
+
+```
+{module}/
+├── {module}.go               # 主文件：初始化 + 公开 API
+├── options.go                # (optional) 配置选项
+└── {module}_test.go          # 测试
+```
+
+## Common Middleware
+
+```
+middleware/
+├── auth.go                   # JWT 认证
+├── cors.go                   # CORS
+├── logging.go                # 请求日志
+├── recovery.go               # Panic 恢复
+├── requestid.go              # 请求 ID
+└── tenant.go                 # 租户上下文
+```
+
+## Wire Provider Registration
+
+```go
+// internal/platform/user/provider.go
+
+package user
+
+import "github.com/google/wire"
+
+// ProviderSet User 模块的依赖提供集合
+var ProviderSet = wire.NewSet(
+	infrastructure.NewUserRepository,
+	application.NewUserService,
+	NewUserHandler,
+)
+```
+
+```go
+// cmd/admin-api/wire.go
+
+//go:build wireinject
+
+package main
+
+import "github.com/google/wire"
+
+func InitializeApp(cfg *config.Config) (*App, error) {
+	wire.Build(
+		// core
+		database.ProviderSet,
+		cache.ProviderSet,
+		logger.ProviderSet,
+		eventbus.ProviderSet,
+		// platform
+		identity.ProviderSet,
+		user.ProviderSet,
+		product.ProviderSet,
+		// app
+		NewApp,
+	)
+	return nil, nil
+}
+```
+
+## cmd/ Entry Point
+
+```go
+// cmd/admin-api/main.go
+
+func main() {
+	cfg, err := config.Load()
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "load config: %v\n", err)
+		os.Exit(1)
+	}
+
+	app, err := InitializeApp(cfg)
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "initialize app: %v\n", err)
+		os.Exit(1)
+	}
+
+	if err := app.Run(); err != nil {
+		fmt.Fprintf(os.Stderr, "run app: %v\n", err)
+		os.Exit(1)
+	}
+}
+```
+
+```go
+// cmd/admin-api/app.go
+
+// App 应用主体
+type App struct {
+	cfg    *config.Config
+	router *gin.Engine
+	logger *zap.Logger
+}
+
+// NewApp 创建应用实例
+func NewApp(
+	cfg *config.Config,
+	logger *zap.Logger,
+	userHandler *user.UserHandler,
+	productHandler *product.ProductHandler,
+) *App {
+	router := gin.New()
+
+	// 全局中间件
+	router.Use(
+		middleware.RequestID(),
+		middleware.Logging(logger),
+		middleware.Recovery(logger),
+		middleware.CORS(),
+	)
+
+	// API v1 路由组（admin BFF 仅注册 admin 路由）
+	v1 := router.Group("/api/v1")
+	admin := v1.Group("/admin")
+	userHandler.RegisterRoutes(nil, nil, admin)
+	productHandler.RegisterRoutes(nil, nil, admin)
+
+	return &App{cfg: cfg, router: router, logger: logger}
+}
+
+// Run 启动 HTTP 服务
+func (a *App) Run() error {
+	addr := fmt.Sprintf(":%d", a.cfg.App.Port)
+	a.logger.Info("server starting", zap.String("addr", addr))
+	return a.router.Run(addr)
+}
+```

package/dist/resources/templates/go-backend/.claude/docs/openapi-contract.md

@@ -0,0 +1,141 @@
+# OpenAPI 契约规范
+
+> OneX OpenAPI 3.1 契约、中文文档导航、投影和发布规则。
+
+## 所有权
+
+- Canonical source 位于 `api/openapi/services/<service>/`。
+- `openapi.yaml` 拥有服务元数据、文档语言、标签分类以及 path/component 引用。
+- `paths/<owner>.yaml` 按业务责任拥有 operation；`components/<owner>.yaml` 拥有该服务的 transport schema。
+- `conformance/*.arazzo.yaml` 拥有关键业务流程的可执行契约。
+- `dist/`、Scalar browser asset 和质量报告均由构建器拥有，禁止手工修改。
+- Go handler 只拥有运行时行为，禁止用注释或文档专用 struct tag 复制契约元数据。
+
+## 文档语言与导航
+
+当前 canonical 文档语言统一为简体中文：
+
+1. `service-registry.json` 的每个服务必须声明 `documentation_locale: zh-CN`，`display_name` 必须包含中文语义。
+2. 每个 `openapi.yaml` 必须声明 `x-onex-documentation-locale: zh-CN`。
+3. 人类可见的 `title`、`summary`、`description`、Tag Object `name`、`x-tagGroups.name`、contact/license name 必须包含中文语义。
+4. 品牌和行业缩写可以保留，例如 OneX、ProductB、ProductA、API、AI、IAM、OAuth、MFA、KOL、CMS、Webhook；只有缩写或英文名、没有中文职责语义的文案不合格。
+5. path、HTTP method、`operationId`、component/schema 名、JSON property、enum、format、header 和扩展字段属于机器契约，禁止为了本地化改名。
+6. 每个 operation 必须且只能声明一个导航标签；标签必须预先声明在顶层 `tags`。
+7. 顶层 `tags` 按业务阅读顺序排列；每个标签必须在 `x-tagGroups` 中出现且只出现一次，分组展开顺序必须与顶层标签顺序一致。
+8. 分组按稳定业务域命名，禁止使用 HTTP 动作、文件名、临时项目名或实现层名称。新增标签前必须先复用既有资源标签；只有职责边界不同才新增。
+9. Scalar 优先使用原生 `zh-CN` localization。上游组件未提供本地化入口时，只能在锁定版本的 browser asset 构建边界通过 `scalar_asset_localization.mjs` 适配；每条规则必须声明精确匹配次数，任何上游漂移都使构建失败。
+10. 禁止用 CSS、DOM 监听器、页面加载后的字符串替换或隐藏功能修正文案；浏览器只加载已生成、已标记 locale/localization revision 且通过双 SHA-256 校验的同源 asset。
+
+未来发布其他语言时，以同一 canonical contract 为输入，在 Documentation Platform 发布边界应用 OpenAPI Overlay。禁止复制 schema、维护双份 operation 或在业务服务内并行运行多套契约。
+
+## Operation 模板
+
+```yaml
+/api/v1/widgets/{widget_no}:
+  get:
+    operationId: getWidget
+    summary: 查询组件详情
+    tags: [组件]
+    security:
+      - BearerAuth: []
+    parameters:
+      - name: widget_no
+        in: path
+        required: true
+        description: 组件业务编号
+        schema:
+          type: string
+          pattern: '^wdg_[A-Za-z0-9]+$'
+    responses:
+      '200':
+        description: 请求成功
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/WidgetResponse'
+      '404':
+        $ref: '#/components/responses/NotFound'
+    x-onex-audience: public
+    x-onex-owner: widgets
+    x-onex-stability: stable
+    x-onex-lifecycle:
+      introduced: '2026-07-16'
+      deprecated: null
+      sunset: null
+      replacementOperationId: null
+      migrationUrl: null
+```
+
+服务根文档必须显式声明对应导航：
+
+```yaml
+x-onex-documentation-locale: zh-CN
+tags:
+  - name: 组件
+    description: 组件相关接口。
+x-tagGroups:
+  - name: 产品能力
+    tags: [组件]
+```
+
+## 安全契约
+
+- 每个 operation 显式声明 `security`；空数组表示明确匿名，省略无效。
+- Admin 和 internal 路径使用真实 IAM 或 service credential scheme。
+- Webhook 使用所属集成声明的 provider signature scheme。
+- Gin middleware 与 OpenAPI operation 必须描述同一保护边界。
+
+## Schema 契约
+
+- OpenAPI 版本固定为 `3.1.1`，JSON Schema dialect 固定为 2020-12。
+- Nullability 使用 JSON Schema union，禁止 `nullable`。
+- 已知业务对象必须声明明确 properties；外部契约禁止 unconstrained object。
+- 公共业务编号、业务引用、幂等键和第三方 ID 使用不同名称与 schema。
+- media type、status code、required、enum、range 和 format 必须匹配 handler 边界。
+- 只有跨服务语义完全一致的 component 才允许共享。
+
+## 委托契约
+
+- 上游 artifact 与 provenance SHA-256 固定在 service owner 下，artifact 保持不可变。
+- BFF mount、security、audience、lifecycle 和文档本地化通过所属 OpenAPI Overlay 表达。
+- 每个 Overlay action 必须声明精确 `x-onex-expected-match-count`；零匹配或超量匹配均失败。
+- 委托 operation 进入服务后仍必须满足中文文案、单标签和 `x-tagGroups` 完整性规则。
+
+## 投影与一致性
+
+- internal 是 canonical contract；partner/public 只能由 internal source 确定性投影生成。
+- 投影必须同步裁剪 paths、reachable components、顶层 tags 和空的 `x-tagGroups`。
+- `operationId` 在全 catalog 唯一且稳定。
+- registry 中全部 HTTP 服务启动时必须通过 Gin route 与内嵌 internal bundle 的 method/path 精确集合校验。
+- 相同输入必须生成字节一致的 bundle、manifest、quality report 和 SHA-256。
+
+## Conformance 契约
+
+- `dist/conformance-matrix.json` 为每个 internal operation 机械派生 parameter、request body、response、header、security 和 idempotency assertion。
+- Arazzo workflow 必须引用现有 `operationId`，并声明 fixture profile、覆盖行为和成功标准。
+- `dist/runtime.openapi.json` 只包含 workflow operation 及其可达 component，禁止手写替代。
+- 静态 assertion 与真实 HTTP workflow 是不同证据；没有 Respect 请求和检查结果时，禁止声称响应已执行。
+- 运行时执行必须通过 `ONEX_OPENAPI_CONFORMANCE_SERVERS` 提供完整 registry server map，禁止跳过服务或降低失败级别。
+
+## 变更流程
+
+1. 修改 owning modular source。
+2. 新增资源标签时同步更新顶层 `tags` 与 `x-tagGroups`，并确认没有可复用标签。
+3. 关键成功、安全或委托行为变化时更新 Arazzo workflow。
+4. 执行 `make openapi-generate`。
+5. 执行 `make openapi-check`、`make openapi-breaking` 和 `make openapi-clean-deletion`。
+6. 执行受影响 Go tests 和服务启动 route parity。
+7. 运行时或安全边界变化时，在完整服务环境执行 `make openapi-conformance`。
+8. source 与 generated artifacts 必须同一提交交付。
+
+Partner/public 支持承诺只在 production publication 取得执行权时，由 API Contract Platform 在同一 PostgreSQL 事务中写入 append-only lifecycle event 和 immutable publication clearance。候选制品不形成承诺；未发布变更直接修正 canonical source。Git 与构建制品只证明 source、工具链和生成字节，不能提供业务生效时间或当前承诺真相。
+
+## 本地文档
+
+非 production 服务暴露：
+
+- `/docs`
+- `/docs/openapi.json`
+- `/docs/assets/scalar-api-reference.js`
+
+Production 不注册这些路由。页面只消费同源内嵌 internal artifact 和仓库锁定的 Scalar asset，不执行跨域请求；元数据同时记录上游 source SHA-256、中文适配 revision 和输出 SHA-256，输出 SHA-256 进入脚本 URL，确保 immutable browser cache 只命中对应制品。