@pzy560117/codex-harness 0.1.0 → 0.1.2

package/package-source/docs/codex-harness-engineering/templates/package-assets/scripts/ai-workflow/sync-targets.example.json

@@ -0,0 +1,35 @@
+{
+  "source": {
+    "repo": "your-org/ai-workflow-kit",
+    "ref": "main"
+  },
+  "defaults": {
+    "baseBranch": "main",
+    "branchPrefix": "chore/ai-kit-sync",
+    "pushBranch": true,
+    "createPullRequest": true,
+    "draftPullRequest": false,
+    "commitMessage": "chore(ai-kit): sync shared AI workflow config",
+    "prTitle": "chore(ai-kit): sync shared AI workflow config from {{sourceRef}}",
+    "prBody": "## AI Workflow Kit Sync`n`nSource: {{sourceRepo}}@{{sourceRef}}`nCommit: {{sourceCommit}}`n`nChanged files:`n{{changedFiles}}`n",
+    "labels": [
+      "ai-kit-sync",
+      "automation"
+    ],
+    "verifyCommands": [
+      "powershell -NoProfile -ExecutionPolicy Bypass -File .\\tools\\install\\ai-workflow\\check-ai-sync-drift.ps1"
+    ]
+  },
+  "targets": [
+    {
+      "repo": "your-org/project-a",
+      "baseBranch": "main",
+      "syncConfigPath": ".ai-sync.yml"
+    },
+    {
+      "repo": "your-org/project-b",
+      "baseBranch": "main",
+      "syncConfigPath": ".ai-sync.yml"
+    }
+  ]
+}

package/package-source/docs/codex-harness-engineering/templates/package-assets/scripts/harness/harness-governance-check.ps1

@@ -0,0 +1,366 @@
+param(
+  [string]$ProjectRoot = (Get-Location).Path,
+  [switch]$WriteExperience
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = "Stop"
+
+function Get-ObjectPropertyValue {
+  param(
+    [object]$InputObject,
+    [string]$Name,
+    [object]$Default = $null
+  )
+
+  if ($null -eq $InputObject) {
+    return $Default
+  }
+
+  $property = $InputObject.PSObject.Properties[$Name]
+  if ($null -eq $property) {
+    return $Default
+  }
+
+  return $property.Value
+}
+
+function Add-Finding {
+  param(
+    [System.Collections.Generic.List[object]]$Findings,
+    [string]$Severity,
+    [string]$Category,
+    [string]$Message,
+    [string]$RepairMode,
+    [string]$TargetDoc = "docs/harness/governance-auto-repair.md"
+  )
+
+  $Findings.Add([pscustomobject]@{
+    severity = $Severity
+    category = $Category
+    message = $Message
+    repair_mode = $RepairMode
+    target_doc = $TargetDoc
+  })
+}
+
+function Get-RelativePathCompat {
+  param(
+    [string]$Root,
+    [string]$Path
+  )
+
+  $rootFull = ([System.IO.Path]::GetFullPath($Root)).TrimEnd('\', '/') + '\'
+  $pathFull = [System.IO.Path]::GetFullPath($Path)
+  if ($pathFull.StartsWith($rootFull, [System.StringComparison]::OrdinalIgnoreCase)) {
+    return $pathFull.Substring($rootFull.Length).Replace('\', '/')
+  }
+
+  return $pathFull.Replace('\', '/')
+}
+
+function Test-MergeMarkers {
+  param(
+    [string]$Root,
+    [System.Collections.Generic.List[object]]$Findings
+  )
+
+  $scanRoots = @(
+    "AGENTS.md",
+    ".codex",
+    "docs/harness",
+    "docs/codex-harness-engineering"
+  )
+
+  foreach ($scanRoot in $scanRoots) {
+    $fullPath = Join-Path $Root $scanRoot
+    if (-not (Test-Path -LiteralPath $fullPath)) {
+      continue
+    }
+
+    $files = if (Test-Path -LiteralPath $fullPath -PathType Leaf) {
+      @(Get-Item -LiteralPath $fullPath)
+    }
+    else {
+      @(Get-ChildItem -LiteralPath $fullPath -Recurse -File -Include *.md,*.json,*.toml,*.ps1,*.rules)
+    }
+
+    foreach ($file in $files) {
+      $content = Get-Content -LiteralPath $file.FullName -Raw -ErrorAction SilentlyContinue
+      if ($content -match '(?m)^(<<<<<<<|=======|>>>>>>>)') {
+        Add-Finding `
+          -Findings $Findings `
+          -Severity "block" `
+          -Category "merge_marker" `
+          -Message ("Merge marker found in {0}." -f (Get-RelativePathCompat -Root $Root -Path $file.FullName)) `
+          -RepairMode "agent_repair" `
+          -TargetDoc "docs/harness/rule-governance.md"
+      }
+    }
+  }
+}
+
+function Test-HookSurface {
+  param(
+    [string]$Root,
+    [System.Collections.Generic.List[object]]$Findings
+  )
+
+  $hookConfigPath = Join-Path $Root ".codex\hooks.json"
+  if (-not (Test-Path -LiteralPath $hookConfigPath)) {
+    return
+  }
+
+  $hookText = Get-Content -LiteralPath $hookConfigPath -Raw
+  if ($hookText.Contains("hook-stop-verify.ps1")) {
+    $activeScript = Join-Path $Root "scripts\harness\hook-stop-verify.ps1"
+    $templateScript = Join-Path $Root "docs\codex-harness-engineering\templates\hooks\hook-stop-verify.ps1"
+    $installedTemplateScript = Join-Path $Root ".agents\docs\codex-harness-engineering\templates\hooks\hook-stop-verify.ps1"
+
+    if (-not (Test-Path -LiteralPath $activeScript)) {
+      $repairMode = if ((Test-Path -LiteralPath $templateScript) -or (Test-Path -LiteralPath $installedTemplateScript)) {
+        "deterministic_repair"
+      }
+      else {
+        "agent_repair"
+      }
+
+      Add-Finding `
+        -Findings $Findings `
+        -Severity "block" `
+        -Category "missing_stop_hook_script" `
+        -Message "hooks.json references tools/harness/hook-stop-verify.ps1, but the script is missing." `
+        -RepairMode $repairMode `
+        -TargetDoc "docs/harness/governance-auto-repair.md"
+    }
+  }
+}
+
+function Test-RulesSurface {
+  param(
+    [string]$Root,
+    [System.Collections.Generic.List[object]]$Findings
+  )
+
+  $rulesDir = Join-Path $Root ".codex\rules"
+  if (-not (Test-Path -LiteralPath $rulesDir)) {
+    return
+  }
+
+  $rulesFiles = @(Get-ChildItem -LiteralPath $rulesDir -File -Filter "*.rules" -ErrorAction SilentlyContinue)
+  if ($rulesFiles.Count -eq 0) {
+    Add-Finding `
+      -Findings $Findings `
+      -Severity "warn" `
+      -Category "missing_execpolicy_rules" `
+      -Message ".codex/rules contains semantic Markdown rules but no official *.rules execution policy files." `
+      -RepairMode "deterministic_repair" `
+      -TargetDoc "docs/harness/rule-governance.md"
+  }
+}
+
+function Test-ConfigSurface {
+  param(
+    [string]$Root,
+    [System.Collections.Generic.List[object]]$Findings
+  )
+
+  $configPath = Join-Path $Root ".codex\config.toml"
+  if (-not (Test-Path -LiteralPath $configPath)) {
+    return
+  }
+
+  $configText = Get-Content -LiteralPath $configPath -Raw
+  if ($configText -match "project_doc_fallback_filenames") {
+    $hasAgents = Test-Path -LiteralPath (Join-Path $Root "AGENTS.md")
+    $hasTeamGuide = Test-Path -LiteralPath (Join-Path $Root "TEAM_GUIDE.md")
+    $hasDotAgents = Test-Path -LiteralPath (Join-Path $Root ".agents.md")
+    if ($hasAgents -and (-not $hasTeamGuide) -and (-not $hasDotAgents)) {
+      Add-Finding `
+        -Findings $Findings `
+        -Severity "warn" `
+        -Category "stale_fallback_config" `
+        -Message "project_doc_fallback_filenames is configured, but AGENTS.md exists and fallback files are missing." `
+        -RepairMode "agent_repair" `
+        -TargetDoc "docs/harness/rule-governance.md"
+    }
+  }
+}
+
+function Get-LatestTraceFile {
+  param([string]$Root)
+
+  $traceDir = Join-Path $Root "traces"
+  if (-not (Test-Path -LiteralPath $traceDir)) {
+    return $null
+  }
+
+  return @(Get-ChildItem -LiteralPath $traceDir -Recurse -File -Filter "*.json" -ErrorAction SilentlyContinue |
+    Sort-Object LastWriteTimeUtc -Descending |
+    Select-Object -First 1)[0]
+}
+
+function New-ExperienceFromTrace {
+  param([string]$Root)
+
+  $traceFile = Get-LatestTraceFile -Root $Root
+  if ($null -eq $traceFile) {
+    return $null
+  }
+
+  try {
+    $trace = Get-Content -LiteralPath $traceFile.FullName -Raw | ConvertFrom-Json
+  }
+  catch {
+    return $null
+  }
+
+  $status = [string](Get-ObjectPropertyValue -InputObject $trace -Name "status" -Default "")
+  if ($status -eq "passed") {
+    return $null
+  }
+
+  $taskId = [string](Get-ObjectPropertyValue -InputObject $trace -Name "task_id" -Default "unknown")
+  $failedStage = [string](Get-ObjectPropertyValue -InputObject $trace -Name "failed_stage" -Default "")
+  $blockedReason = [string](Get-ObjectPropertyValue -InputObject $trace -Name "blocked_reason" -Default "")
+  $relativeTrace = Get-RelativePathCompat -Root $Root -Path $traceFile.FullName
+  $summary = "Task $taskId ended with status=$status"
+  if (-not [string]::IsNullOrWhiteSpace($failedStage)) {
+    $summary += ", failed_stage=$failedStage"
+  }
+  if (-not [string]::IsNullOrWhiteSpace($blockedReason)) {
+    $summary += ", blocked_reason=$blockedReason"
+  }
+
+  $targetDoc = "docs/harness/governance-auto-repair.md"
+  if ($failedStage -match "stage1|spec|design") {
+    $targetDoc = "docs/harness/rule-governance.md"
+  }
+  elseif ($failedStage -match "stage2|review|test|verify") {
+    $targetDoc = "docs/testing/failure-triage.md"
+  }
+
+  $hashInput = "$relativeTrace|$summary"
+  $bytes = [System.Text.Encoding]::UTF8.GetBytes($hashInput)
+  $sha = [System.Security.Cryptography.SHA256]::Create()
+  try {
+    $hash = ([System.BitConverter]::ToString($sha.ComputeHash($bytes))).Replace("-", "").Substring(0, 16).ToLowerInvariant()
+  }
+  finally {
+    $sha.Dispose()
+  }
+
+  return [pscustomobject]@{
+    hash = $hash
+    task_id = $taskId
+    status = $status
+    failed_stage = $failedStage
+    blocked_reason = $blockedReason
+    trace = $relativeTrace
+    summary = $summary
+    target_doc = $targetDoc
+  }
+}
+
+function Write-ExperienceEntry {
+  param(
+    [string]$Root,
+    [object]$Experience
+  )
+
+  if ($null -eq $Experience) {
+    return $false
+  }
+
+  $docPath = Join-Path $Root "docs\harness\governance-auto-repair.md"
+  $docDir = Split-Path -Parent $docPath
+  if (-not (Test-Path -LiteralPath $docDir)) {
+    New-Item -ItemType Directory -Force -Path $docDir | Out-Null
+  }
+
+  $marker = "<!-- stop-hook-experience:$($Experience.hash) -->"
+  if (Test-Path -LiteralPath $docPath) {
+    $existing = Get-Content -LiteralPath $docPath -Raw
+    if ($existing.Contains($marker)) {
+      return $false
+    }
+  }
+  else {
+    @"
+# Governance Auto Repair
+
+本文件由 Stop hook 治理检查维护，用于记录自动化闭环中反复出现的失败原因、修复去向和后续规则提升候选。这里不是硬规则入口；只有经过复验和维护者确认后，才可提升到 `AGENTS.md`、`.codex/rules/*.md`、prompt 或 `.rules`。
+
+"@ | Set-Content -LiteralPath $docPath -Encoding UTF8
+  }
+
+  $entry = @"
+
+## Stop Hook Experience - $($Experience.task_id)
+
+$marker
+
+- Time: $(Get-Date -Format o)
+- Summary: $($Experience.summary)
+- Trace: `$($Experience.trace)`
+- Suggested target doc: `$($Experience.target_doc)`
+- Next action: review the trace, repair the root cause, then promote only reusable lessons to the target doc.
+
+"@
+
+  Add-Content -LiteralPath $docPath -Value $entry -Encoding UTF8
+  return $true
+}
+
+try {
+  $resolvedRoot = (Resolve-Path -LiteralPath $ProjectRoot).Path
+  $findings = New-Object System.Collections.Generic.List[object]
+
+  Test-MergeMarkers -Root $resolvedRoot -Findings $findings
+  Test-HookSurface -Root $resolvedRoot -Findings $findings
+  Test-RulesSurface -Root $resolvedRoot -Findings $findings
+  Test-ConfigSurface -Root $resolvedRoot -Findings $findings
+
+  $experience = New-ExperienceFromTrace -Root $resolvedRoot
+  $experienceWritten = $false
+  if ($WriteExperience -and $null -ne $experience) {
+    $experienceWritten = Write-ExperienceEntry -Root $resolvedRoot -Experience $experience
+  }
+
+  if ($null -ne $experience) {
+    Add-Finding `
+      -Findings $findings `
+      -Severity "block" `
+      -Category "failed_trace_experience" `
+      -Message $experience.summary `
+      -RepairMode "agent_repair" `
+      -TargetDoc $experience.target_doc
+  }
+
+  $hasBlockingFinding = @($findings | Where-Object { $_.severity -eq "block" }).Count -gt 0
+  $status = if ($hasBlockingFinding) { "fail" } else { "pass" }
+
+  [pscustomobject]@{
+    status = $status
+    findings = @($findings.ToArray())
+    experience = $experience
+    experience_written = $experienceWritten
+    next_action = "Read AGENTS.md, docs/harness/governance-auto-repair.md, docs/harness/rule-governance.md, and .codex/rules/agents.md; use harness-writer for semantic repairs and rerun tools/harness/verify.ps1."
+  } | ConvertTo-Json -Depth 8 -Compress
+}
+catch {
+  $line = if ($null -ne $_.InvocationInfo) { [string]$_.InvocationInfo.ScriptLineNumber } else { "" }
+  [pscustomobject]@{
+    status = "fail"
+    findings = @([pscustomobject]@{
+      severity = "block"
+      category = "governance_check_error"
+      message = if ([string]::IsNullOrWhiteSpace($line)) { $_.Exception.Message } else { "$($_.Exception.Message) at line $line" }
+      repair_mode = "agent_repair"
+      target_doc = "docs/harness/governance-auto-repair.md"
+    })
+    experience = $null
+    experience_written = $false
+    next_action = "Inspect scripts/harness/harness-governance-check.ps1 and rerun tools/harness/verify.ps1."
+  } | ConvertTo-Json -Depth 8 -Compress
+}

package/package-source/docs/codex-harness-engineering/templates/package-assets/skills/HOW_TO_USE_SKILLS.md

@@ -0,0 +1,91 @@
+# Skills 使用指南
+
+## Skill 已加载
+
+当前项目的 skill package 位于：`.agents/skills/`
+
+当前目录约定：
+
+- `.agents/skills/`：active skill package
+- `.agents/workflows/`：独立 workflow 文档
+- `.agents/archive/workflows/skill-mirrors/`：已归档的 workflow 镜像副本
+
+## 如何使用Skill
+
+### 1. 自动识别
+AI会根据任务需求自动判断并使用相关skill：
+- 任务描述中包含skill相关的关键词
+- AI判断某个skill适用于当前任务
+
+### 2. 明确指定
+您可以直接要求使用某个skill：
+```
+"使用 example-skill 来处理这个任务"
+"按照 example-skill 的步骤执行"
+"使用 harness-surface-sync 检查并同步 harness 流程"
+"用 harness-surface-sync 扫一遍 testing-left-shift 文档和镜像"
+"使用 auto-commit 检查当前改动、补齐同步并提交推送"
+"用 auto-commit，如果没有 GitHub 仓库就用 gh 创建后再推送"
+```
+
+### 3. 浏览可用 Skills
+查看所有可用的skills：
+```
+"显示所有可用的skills"
+"列出项目中的skills"
+```
+
+## 当前可用的Skills
+
+### Harness Surface Sync
+- **位置**: `.agents/skills/harness-surface-sync/`
+- **说明**: 一次性检查并同步 harness runtime、docs/testing、templates、workflows、config、package-assets 和 skills 镜像
+- **适用场景**:
+  - 规则、prompt、task 模板或 testing-left-shift 真相源刚改过
+  - 需要继续扫旧流程表述并补齐镜像同步
+  - 需要把新的 repo-local skill 一并打进 package-assets
+
+### Auto Review and Commit
+- **位置**: `.agents/skills/auto-commit/`
+- **说明**: 一次性检查当前工作区、补齐必要同步、生成提交并推送；如果没有远程仓库，默认用 GitHub CLI 创建私有仓库
+- **适用场景**:
+  - 当前改动已经完成，准备收尾提交
+  - 当前仓库有 `.agents` / `agent` / `templates` / `package-assets` 镜像，需要提交前补齐同步
+  - 当前本地仓库还没有 `origin`，希望直接建 GitHub 仓库再推送
+
+### AI Config Git Sync
+- **位置**: `.agents/skills/ai-config-git-sync/`
+- **说明**: 维护共享 AI workflow/config 到多个 Git 项目的同步链路，支持读状态、写配置、建同步分支、push 和开 PR
+- **适用场景**:
+  - 需要更新 `.ai-sync.yml`、`sync-targets.json` 或多项目同步脚本
+  - 需要把 root AI 配置改动 fan-out 到多个项目仓库
+  - 需要检查 drift、manifest、lock 或同步分支/PR 状态
+
+### Example Skill
+- **位置**: `.agents/skills/example-skill/`
+- **说明**: 一个示例技能，展示如何创建和使用技能文件
+- **包含**: 
+  - SKILL.md: 主文档
+  - scripts/: 辅助脚本
+  - examples/: 使用示例
+  - resources/: 配置模板
+
+## Skill开发
+
+创建新的skill：
+1. 在 `.agents/skills/` 下创建新文件夹
+2. 在文件夹中创建 `SKILL.md` 文件
+3. 添加YAML frontmatter和详细说明
+4. （可选）添加scripts、examples、resources等目录
+
+## 系统级Skills
+
+如果想让skill在所有项目中可用，可以复制到：
+```
+~/.gemini/antigravity/skills/
+```
+
+Windows路径：
+```
+C:\Users\<用户名>\.gemini\antigravity\skills\
+```

package/package-source/docs/codex-harness-engineering/templates/package-assets/skills/academic-mermaid-diagrams/SKILL.md

@@ -0,0 +1,172 @@
+---
+name: academic-mermaid-diagrams
+description: 学术规范的 Mermaid 渲染与图表生成指南。用于生成符合学术论文标准的架构图、时序图、ER 图等，具有清晰层次、标准符号和黑白黑白极简配色的特点。
+---
+
+# 学术化 Mermaid 图形生成指南
+
+> 本工作流/技能指南规定了如何使用 Mermaid 代码生成符合严格学术论文要求的高质量、专业化机制图与架构图，彻底替代复杂的手工图像编辑过程。
+
+## 触发场景
+- 当用户要求在技术文档、开题报告、毕业设计或学术论文中补充插图时。
+- 当系统需要生成清晰严谨的“系统总体架构图”、“业务时序图”、“ER实体关系图”、“状态机生命周期图”时。
+- 当现有的系统图显得过于随意（带有鲜艳主题色、排版混乱、标注不清）而需要转为学术格式时。
+
+---
+
+## 核心设计规范与约束
+
+符合学术标准的 Mermaid 图表**必须**严格遵守以下 5 项特征：
+
+### 1. 黑白配色，简洁专业
+- **禁止**使用 Mermaid 默认的蓝/黄/绿鲜艳配色。
+- **配置注入**：必须在图首行注入 `%%{init: {'theme': 'base'... }}%%` 指令，强制图表为白底、黑边框、黑字、黑线、可选的极简浅灰底色。
+
+### 2. 清晰的层次分隔（虚线分隔各层）
+- 使用 `subgraph` 划分逻辑层次（如：展示层、业务层、数据层）。
+- 辅以 `classDef stroke-dasharray` 将分层包裹框修改为规范的**虚线框**，避免包裹框抢夺主体模块的视觉焦点。
+
+### 3. 标准化图形符号
+- **模块/组件**：使用标准的矩形 `[组件名称]` 或圆角矩形 `(组件名称)`。
+- **数据源/存储媒介**：强制使用学术通用的圆柱体符号 `[(数据库名称)]` 标识持久化层。
+- **网关/网关节点**：菱形或平滑多边形。
+
+### 4. 规范的箭头连接
+- 数据/控制流动：统一采用标准实线的黑侧单向箭头 `-->`。
+- 异步消息/弱依赖/缓存击穿：使用虚线箭头 `-.->`。
+- 避免箭头飞线交叉，必要时通过增加隐式排版节点或控制树的深入方向（`graph TD` 俯视或 `graph LR` 平视）进行梳理。
+
+### 5. 层次标签明确标注
+- 每个层次（子图）的左上/中上部必须有明确功能定位的标注，如 `[表现层 presentation layer]`。
+- 模块名应直指系统功能或组件专名，杜绝无意义的代称。
+
+---
+
+## 学术级图表实战模板库
+
+在响应用户“生成一篇符合论文要求的图（如架构图）”的请求时，应当直接套用或变体下方模板生成代码。
+
+### 模板 A：分层架构拓扑图 (系统总体架构)
+
+典型的四层结构架构视图，实现了规范的虚线图层框与黑白学术风：
+
+```mermaid
+%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#ffffff', 'primaryBorderColor': '#000000', 'primaryTextColor': '#000000', 'lineColor': '#000000', 'clusterBkg': 'none', 'clusterBorder': '#333333'}}}%%
+graph TD
+    classDef layerBox fill:none,stroke:#333,stroke-dasharray: 5 5,stroke-width:1.5px;
+    classDef standardBox fill:#fff,stroke:#000,stroke-width:1px;
+    classDef db fill:#fff,stroke:#000,stroke-width:1px;
+
+    subgraph Layer_Presentation [前端展示层]
+        Web[Web 管理后台]:::standardBox
+        App[移动端客户端]:::standardBox
+    end
+
+    subgraph Layer_Business [后端业务处理层]
+        Gateway[API 路由网关]:::standardBox
+        subgraph Core_Modules [核心服务集群]
+            AuthSvc[安全认证服务]:::standardBox
+            OrderSvc[订单流转服务]:::standardBox
+            RuleSvc[业务规则引擎]:::standardBox
+        end
+    end
+
+    subgraph Layer_Data [数据存储层]
+        DB[(MySQL 业务主库)]:::db
+        Redis[(Redis 缓存/锁)]:::db
+    end
+
+    Web --> Gateway
+    App --> Gateway
+    Gateway --> AuthSvc
+    AuthSvc --> OrderSvc
+    AuthSvc --> RuleSvc
+    
+    OrderSvc --> DB
+    OrderSvc -.-> Redis
+    
+    %% 应用层边界虚线样式
+    class Layer_Presentation,Layer_Business,Layer_Data layerBox;
+    class Core_Modules layerBox;
+```
+
+### 模板 B：E-R 数据实体关系图
+
+学术 E-R 图更侧重关系基数与实体属性。学术版需要强制白底黑字。
+
+```mermaid
+%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#fff', 'primaryBorderColor': '#000', 'lineColor': '#000', 'textColor': '#000'}}}%%
+erDiagram
+    USERS ||--o{ ORDERS : "1:N (发起)"
+    PHOTOGRAPHERS ||--o{ ORDERS : "1:N (承接)"
+    ORDERS ||--|| PAYMENTS : "1:1"
+
+    USERS {
+        BigInt user_id PK "用户主键"
+        String email UK "邮箱"
+    }
+    ORDERS {
+        BigInt order_id PK "订单主键"
+        Int status "生命周期状态"
+    }
+    PAYMENTS {
+        BigInt pay_id PK "流水号"
+        Decimal amount "数额"
+    }
+```
+
+### 模板 C：系统级生命周期状态图 (状态机)
+
+用于表现严格的状态转换，在“流转引擎”、“事务处理状态闭环”类论文章节必备。
+
+```mermaid
+%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#fff', 'primaryBorderColor': '#000', 'lineColor': '#000', 'textColor': '#000'}}}%%
+stateDiagram-v2
+    classDef stateNode fill:#fff,stroke:#000,stroke-width:1px;
+    
+    [*] --> 待审核 : 提交发布
+    待审核 --> 已生效 : 人工审核通过
+    待审核 --> 驳回 : 人工审核拒绝
+    
+    已生效 --> [*] : 服务结束/停用
+    驳回 --> [*] : 废弃
+```
+
+### 模板 D：规范预约时序图 (序列交互图)
+
+用于描述涉及三方组件、微服务内部、或者核心交易机制的同步/异步过程交互。
+
+```mermaid
+%%{init: {'theme': 'base', 'themeVariables': { 'actorBkg': '#fff', 'actorBorder': '#000', 'actorTextColor': '#000', 'signalColor': '#000', 'signalTextColor': '#000', 'noteBkg': '#f9f9f9', 'noteBorder': '#000'}}}%%
+sequenceDiagram
+    autonumber
+    participant Client as 客户端界面
+    participant API as 后端聚合服务
+    participant DB as MySQL持久层
+    participant Remote as 外部支付平台
+
+    Client->>API: 1. 发起订单支付请求
+    activate API
+    API->>DB: 2. 校验订单并发隔离锁
+    DB-->>API: 3. 约束校验通过
+    API->>Remote: 4. 调用三方支付网关接口
+    
+    rect rgb(245, 245, 245)
+        note right of Remote: 【关键网关节点】异步验签
+        Remote-->>API: 5. 返回支付凭证(Token)
+    end
+    
+    API-->>Client: 6. 重定向至安全支付页
+    deactivate API
+```
+
+## AI 执行要求
+在应用此 Skill 时，AI 需要执行以下动作：
+1. **抓取原始述求**：仔细提取用户代码或文字中提炼模块（前、后、数据等）、实体关系或调用路径。
+2. **选择渲染图格式**：根据描述类型，判定属于组件图结构(graph TD) 还是 控制流 (sequence/state)。
+3. **强制混入 CSS 层**：把 `%%{init: ...}%%` 学术模板投喂到代码的最前沿。
+4. **验证符合论文 5 准则**：检查 `[]` (实体), `[()]` (DB圆柱), `虚线`, `单色视觉` 分离呈现状况后再进行输出。
+5. **强制全态 AI 生图策略 (PNG 生成)**：在用户明确要求使用 `generate_image` 工具直接生成带有实际文字内容的图表时，请遵循以下最新策略，绝对不允许退避并生成“无字纯几何图形”：
+   - **提取凝练文本短词**：由于模型在渲染复杂长句容易发生文字错乱，构思提示词时，必须将模块名称进行最精简凝练（支持提供中文字符，必要时加上简短精准的英文辅助），如把“订单状态生命周期”精简为“订单流转(Order State)”。
+   - **强硬注入文本指令**：提示词中必须直接且强硬地规定：“图内的核心方框或节点上，必须要端正地渲染写出下列文字，绝不能省略或留白”。
+   - **放宽容错与多次试错**：系统理解模型写字时可能会有瑕疵或拼写失误，但必须迎难而上。为了获得更好效果，允许且推荐在同一次需求中运用工具并行**多次声成**（提供多样化候选给用户选择），从而选出文本更清晰准确、排版最具论文范儿的一张图。