Scaffold any platform project · Upgrade any legacy codebase for AI agents — in one command
给你的 AI Agent 装上平台项目初始化能力：新项目一条命令建好骨架，老项目一条命令补齐 AI 接手层
给你的 AI Agent 装上平台项目初始化能力：新项目一条命令建好骨架，老项目一条命令补齐 AI 接手层
SKILL.md-format skill for Claude Code · Codex · Cursor — structure as documentation, ready for AI handoff on day one
结构即文档，接手即开发
⭐ Star it if useful — 如果这个 skill 对你有用，点个 Star 让更多 Agent 开发者发现它
你在用 AI Agent 开发，但每次启动新项目、接手老代码，总绕不开这些摩擦：
- 🗂️ "帮我初始化一个平台项目" → 靠感觉搭，目录不统一、漏掉 Docker、缺 README、没有 AGENTS.md
- 🤖 "帮我接手这个老项目" → AI Agent 读不懂，没有 CLAUDE.md、没有接手层、从零开始摸索
- 📐 "帮我画个架构图" → 每次各搞一套，有的放
docs/、有的放根目录、格式完全不统一 - 📝 "帮我写 README" → 占位符全没填完，没通过 gate 就算交付了
- 🔄 "把这个项目给 AI 接手" → 不知道补什么，AGENTS.md 写什么、graphify 要不要跑、哪些文件必须有
这些不难解决，但需要一套固定规范和可复用的工程流程。
Platform Project Skill 把这两件事变成一条命令：
告诉你的 AI Agent：
帮我初始化平台项目：~/.codex/codex-workspace/ai-workspace/skills/platform-project-skill/SKILL.md
或直接用脚本：
# 新项目：从 omni-platform 母版一键建好完整骨架
scripts/create-platform-project.sh my-platform /path/to/parent "My Platform" "我的平台"
# 老项目：非侵入式补齐所有 AI 接手层
scripts/upgrade-existing-project.sh /path/to/existing-project| 🔄 双路径工作流 | 同一个 skill 覆盖新项目初始化和老项目 AI 接手升级，不用切换工具 |
| 🛡️ 非侵入原则 | 老项目只补 AI 接手层，不移动源码、不重构目录、不替换技术栈 |
| ✅ 可校验交付 | 内置 README gate、资产校验、基线检查，完成前必须过验证，不允许虚报 |
| 📦 母版内置 | omni-platform 母版快照随 skill 一起发布，无需网络拉取，离线可用 |
| 🤖 Codex 项目级能力 | 新项目内置 .agents/skills 单一真值源、8个 baseline Skill、8类动态 UI Profile 和 OpenAI 展示元数据；换电脑也不依赖全局 ECC Skill |
| 🎨 高级 UI/UX 链路 | Ant Design、Taste、UI UX Pro Max、GSAP、Impeccable 与 Data Product UX 按阶段组合，不互相争抢规则 |
| 🧪 体验证据门禁 | 真实页面必须提供构建、桌面/移动、状态、无障碍、数据语义和动效清理证据 |
| 🔌 兼容主流 Agent | Claude Code、Codex、Cursor、OpenClaw……任何支持 SKILL.md 的 Agent 均可调用 |
platform-project-skill 是一套专为 AI 编程工作流设计的项目脚手架技能包——新项目生成完整骨架（目录 · Docker · README · AGENTS.md · CLAUDE.md · graphify 基线），同时注入8个基础 Skill、8类动态 UI Profile、Baoyu Design 高保真 HTML 原型能力、数据产品体验规则和可验证的前端交付门禁；项目 manifest 强制自动路由只使用仓库内 Skill，换电脑也不依赖全局 ECC。老项目则非侵入式补齐 AI 接手层，业务代码零修改。新项目提供可选的项目级 codebase-memory-mcp 安全包装脚本，但不会下载二进制、注册全局 MCP、启动 watcher 或自动索引。
默认基础设施策略：优先复用当前环境已有 PostgreSQL / Redis。共享服务可达时只创建项目自己的 database / schema / role / namespace；只有共享基础设施不存在或用户明确要求隔离时，才启用 standalone-infra profile 创建独立数据库/Redis 容器。
English summary: platform-project-skill is a SKILL.md-format scaffold and governance system for Claude Code, Codex, and Cursor. It creates an offline multi-package platform baseline with eight core Skills, eight deterministic UI Profiles, isolated Baoyu Design HTML prototyping, pinned third-party provenance, data-product UX guidance, and evidence-gated frontend delivery. Existing-project upgrades remain inspect-first and non-invasive.
If this saves you time, a ⭐ helps others find it.
- 双路径工作流：新项目初始化（
new）和老项目 AI 升级（existing）由同一个 skill 统一覆盖，路由自动识别 - 非侵入式升级：老项目默认只补 AI 接手层，业务代码、目录结构、技术栈一律不动
- 母版驱动：
assets/templates/omni-platform/是新项目的唯一来源，禁止从 AI 记忆重建，保证一致性 - 共享基础设施优先：新项目默认复用已有 PostgreSQL / Redis，只在共享服务不存在或明确要求隔离时启用独立容器 fallback
- 可校验交付：内置 README gate + 资产注册校验 + 基线检查，
STATE=initialization_done才允许报告完成 - 脚本化自动化：扫描、创建、升级、校验、同步全部封装为独立 Bash 脚本，可单独调用，也可组合执行
这不是把一批热门 Skill 原样堆进项目。Platform Project Skill 把开发、设计系统、数据体验、动效、审查、交接和验证拆成不同阶段，再通过确定性 Profile 路由到当前任务真正需要的能力。
结果是：Agent 在开发普通表单时不会加载复杂动效规则；开发数据工作台时会自动补齐表格、筛选、权限和异常状态；开发品牌页面时才提高视觉表现和动效强度；页面可运行后再进入精修与验收。
| Skill | 负责什么 | 什么时候使用 |
|---|---|---|
| karpathy-guidelines | 控制范围、显式假设、保护脏工作树 | 所有代码和配置修改 |
| frontend-development | React、TypeScript、交互、响应式和无障碍 | 前端与移动端实现 |
| frontend-code-review | 正确性、交互、性能和回归审查 | 前端实现完成后 |
| backend-development | API、数据边界、缓存和服务实现 | 服务端开发 |
| backend-code-review | 安全、契约、数据完整性和并发风险 | 服务端审查 |
| project-verification | 构建、Docker、HTTP、浏览器和交付证据 | 验证与发布准备 |
| handoff-project-safe | 把当前任务压缩成项目内可接手交接 | 阶段收口或切换会话 |
| ui-experience-orchestrator | 选择正确的 UI、数据、动效和精修 Profile | 每次页面设计或实现前 |
Profile 由 surface、stack、motion、phase、artifact 五项事实决定，而不是由 Agent 凭感觉选择。prototype / wireframe / design-system 只进入隔离的 Baoyu HTML 工作流；implementation 才进入真实项目技术栈。
| Profile | 适用页面 | 组合能力 |
|---|---|---|
| ui-prototype-html | 高保真 HTML 原型、线框、设计系统预览 | Baoyu Design 方法、交互状态、localhost 浏览器验证；不改生产代码 |
| ui-enterprise-react | React 管理后台、运营平台、数据产品 | Ant Design + 设计系统 + Data Product UX |
| ui-data-framework-neutral | Vue、Svelte 等非 React 数据界面 | 设计系统 + Data Product UX，不强制 Ant Design |
| ui-visual-premium | 官网、品牌页、展示型 Web | Taste 视觉方向 + UI UX Pro Max |
| ui-mobile-premium | H5、移动 Web、触控界面 | 移动优先视觉与交互，不继承桌面后台假设 |
| motion-gsap | 协调过渡、数据变化、丰富交互 | GSAP core、React 生命周期和性能规则 |
| motion-gsap-advanced | 时间线、滚动叙事、复杂联动 | GSAP Timeline、ScrollTrigger 和高级插件规则 |
| ui-polish | 已经运行的页面 | Impeccable 安全精修 + findings-first 审查 |
普通 none/micro 动效优先使用 CSS；只有 rich/advanced 才启用 GSAP。ui-polish 只在页面已经真实运行后使用，因此设计、实现、动效和审查不会争夺同一个决策权。
| 能力 | 本项目中的职责 | GitHub 地址 | 集成方式 |
|---|---|---|---|
| Ant Design | React 企业端组件与主题能力；它是组件库，不是假装成 Skill | github.com/ant-design/ant-design | 仅 ui-enterprise-react 按需安装 |
| GSAP Skills | 动效、Timeline、ScrollTrigger、React 清理和性能规则 | github.com/greensock/gsap-skills | 拆成普通与高级两级动效 Profile |
| Taste Skill | 布局、排版、密度、视觉差异化和反模板化方向 | github.com/Leonxlnx/taste-skill | 采用稳定 v1 思路，项目 DESIGN.md 始终优先 |
| UI UX Pro Max | 设计 Token、组件状态、响应式和设计系统 | github.com/nextlevelbuilder/ui-ux-pro-max-skill | 只承担设计系统阶段，不做第二个视觉总监 |
| Impeccable | 页面实现后的视觉与交互精修 | github.com/pbakaus/impeccable | 移除 provider Hook、安装器和根文档覆盖 |
| Handoff | 把阶段成果压缩成下一位 Agent 可继续执行的交接 | github.com/mattpocock/skills/tree/main/skills/productivity/handoff | 只写 docs/handoffs，不使用系统临时目录 |
| Baoyu Design | 高保真 HTML 原型、线框、交互探索和设计系统预览 | github.com/JimLiu/baoyu-design | 固定 commit 的项目内安全适配；只写 docs/design/prototypes，不替代生产代码或位图 |
所有外部来源都在 .agents/vendor-skills.lock.json 中固定 commit、许可证、本地 SHA256 和安全适配记录，并由 .agents/VENDOR-NOTICES.md 保留第三方声明。初始化不会运行上游安装器、自动更新、全局 MCP、代理服务或 provider Hook；Headroom 已明确排除。
项目自带 data-product-ux，不只是让后台“看起来更漂亮”，还会检查：
- 指标含义、单位、精度、时区、更新时间和数据来源。
- 搜索、筛选、排序、分页、保存视图和 URL 状态。
- 表格列管理、批量操作、危险操作范围和恢复路径。
- Loading、Empty、Error、Success、Disabled、Permission、Stale Data。
- 图表比较、钻取、明细追溯和无障碍摘要。
- 长任务进度、取消、重试、最近更新时间和历史记录。
- 大数据量下的分页、虚拟化、聚合与懒加载策略。
业务目标与真实数据
→ 确认 surface / stack / motion / phase / artifact
→ HTML 设计产物选择 ui-prototype-html；真实实现选择一个生产 UI Profile
→ 必要时按图片编排门禁用 Codex 原生 imagegen 生成设计稿
→ 实现页面、数据状态和交互
→ 按需启用 GSAP
→ 页面运行后执行 ui-polish
→ 构建 + 桌面/移动浏览器检查
→ 无障碍、响应式、数据语义和动效验收
→ STATE=frontend_experience_done
示例：
bash scripts/util-select-agent-profiles.sh --surface data --stack react --motion advanced --phase review --artifact implementation
该组合会选择 ui-enterprise-react、motion-gsap-advanced 和 ui-polish，但不会加载移动端 Profile 或无关后端 Skill。
| 方案 | Agent 直接调用 | 老项目非侵入升级 | 动态 UI Profile | UX 证据门禁 | 离线母版 | Graphify |
|---|---|---|---|---|---|---|
| Platform Project Skill | ✅ | ✅ | ✅ 8类 | ✅ | ✅ | ✅ |
| 手动搭建 | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ |
| Cookiecutter / Yeoman | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ |
| GitHub Template | ❌ | ❌ | ❌ | ❌ | 取决于模板 | ❌ |
| 直接让 AI 从记忆重建 | ❌ | ✅ | ❌ |
| 场景 | 路由 | 说明 |
|---|---|---|
| 🆕 新平台项目 | new |
从 omni-platform 母版复制骨架，替换命名，补齐所有标准文件 |
| 🔧 老项目 AI 升级 | existing |
扫描现有结构，只补缺失的 AI 接手层，业务代码零修改 |
| 📝 局部补全 | partial |
只补 README、assets、graphify 中的一项，适合轻量任务 |
| 🔀 基座派生 | hybrid |
基于 omni-platform 重塑已有项目结构，保留原基座能力 |
不确定走哪条路？ 先跑
scripts/inspect-project.sh <path>，它会扫描项目现状并给出推荐路由。
- Claude Code / Codex / Cursor 等支持 SKILL.md 的 AI Agent
- Bash 3.2+（macOS 自带，Linux 默认满足）
- 可选：
image_gen工具（生成最终架构图时需要）
# 推荐路径（Codex 用户）
cp -r platform-project-skill ~/.codex/codex-workspace/ai-workspace/skills/
# OpenClaw 用户
cp -r platform-project-skill ~/.openclaw/skills/# 基础用法（英文名从 slug 自动转 Title Case）
scripts/create-platform-project.sh my-platform /path/to/parent
# 带自定义中英文显示名
scripts/create-platform-project.sh my-platform /path/to/parent "My Platform" "我的平台"执行后生成：
查看生成的完整项目结构
my-platform/
├── README.md ← 已填入项目名、描述、版本、作者
├── AGENTS.md ← AI Agent 接手说明
├── .agents/
│ ├── skills/ ← 8个 baseline + 按需 UI Skills
│ ├── vendor-skills.lock.json ← 来源、commit、许可证和本地 checksum
│ └── VENDOR-NOTICES.md ← 第三方声明
├── CLAUDE.md ← Claude Code 专属规则
├── START-HERE.md ← 首次接手导航
├── docker-compose.yml ← 多服务编排配置
├── assets/
│ └── platform/architecture/ ← 架构图目录（含 prompt）
├── docs/
│ ├── requirements/ ← 需求文档模板
│ ├── design/ ← 技术方案、UI 规范
│ └── testing/ ← 测试用例、验收报告模板
├── my-platform-front/ ← 前端工程（React + Vite）
├── my-platform-server/ ← 服务端工程（含 Docker）
├── my-platform-mobile/ ← 移动端工程
├── scripts/
│ ├── util-verify-agent-skills.sh ← Skill/Profile/来源完整性门禁
│ ├── util-select-agent-profiles.sh ← 确定性 UI Profile 选择
│ └── util-verify-frontend-experience.sh ← 前端体验证据门禁
└── graphify-out/GRAPH_REPORT.md ← AI 可读的代码知识图谱基线
# 默认保守模式：只补 AGENTS / CLAUDE / START-HERE / 升级报告
scripts/upgrade-existing-project.sh /path/to/existing-project
# 同时创建 assets/ 平台目录
scripts/upgrade-existing-project.sh /path/to/existing-project --with-assets
# 同时创建 docs/ 标准文档结构
scripts/upgrade-existing-project.sh /path/to/existing-project --with-platform-docs
# 预览模式，不实际写文件
scripts/upgrade-existing-project.sh /path/to/existing-project --dry-run# 新项目（统一严格验证）
scripts/validate-platform-project.sh /path/to/project
# 老项目（manifest 可缺失，降级为 WARN）
scripts/check-project-baseline.sh --existing /path/to/project
# 公开仓库派生 / 产品化 fork（强制检查中文根 README、英文对照 README、顶部图、双语图片）
scripts/check-project-baseline.sh --existing --open-source /path/to/project- 从内置
omni-platform母版复制完整骨架（front / mobile / server / assets / docs / Docker） - 批量替换项目名、目录名、服务名和 README 身份信息
- 自动生成 README.md、AGENTS.md、CLAUDE.md、START-HERE.md
- 初始化8个 baseline Skill，并附带按需 UI Profile Skill；安全 Handoff 与 UI 路由器默认可用
- 确定性 UI Profile：Baoyu HTML 原型与企业数据端、框架中立数据端、高级视觉、移动端、GSAP 动效和 Impeccable 精修按 surface/stack/motion/phase/artifact 路由
- 外部能力通过 vendor lock 固定来源、commit、许可证、本地 checksum 和安全适配；不运行上游安装器、Hook 或全局配置
- 数据产品体验门禁覆盖表格、筛选、图表、批量操作、数据状态、响应式、无障碍和动效清理
- 每个 Skill 使用精确
description触发，复杂清单按需下沉到references/，并提供agents/openai.yaml pnpm verify:agents校验全部发现 Skill；pnpm verify:agents:baseline校验8个 baseline；pnpm verify:agents:profiles校验全部 Profile 和 vendor lock- 保留 graphify 按需基线，但不安装自动 Hook、不在 Edit/Write 后全量重建
inspect-project.sh扫描现有结构，输出精确缺口报告，决定升级深度- 只补缺失的 AI 接手层，不动业务代码、不重构目录
.gitignore-aware：不创建与忽略规则冲突的文件- 语言感知：根据项目技术栈自动调整 CLAUDE.md 内容
- 输出结构化升级报告，明确改动边界和后续建议
- 正式生图前先生成同一项目概览的5张低清风格候选，展示后等待用户选择；当前用户明确要求跳过时必须记录授权原文
- 通过轻量编排层路由 Baoyu 的 Cover / Infographic / XHS / Comic 策划能力，最终位图统一交给 Codex 原生
imagegen - 用户一次性确认 palette、rendering、mood、typography、text level、locale、reference 和 required/optional 范围后，写入
assets/style-direction.md - 根 README 强制生成5类项目认知图：项目头图、业务协同流程、系统架构、工单状态流转、部署与集成拓扑
- 每类认知图生成
zh-CN与en两套，共10张；中文根 README 与英文 README 分别引用对应版本 - front、mobile、server 的 UI 图和模块图改为按需项，没有真实展示需求时不阻断初始化
- 每张 required 和已生成 optional 图必须通过7项人工验收并留下 reviewer、时间和当前 hash 证据
- 维护架构图、设计图、流程图的 prompt 模板（
assets/prompts/） - 最终展示图必须继承
style-direction.md，通过 Codex 原生imagegen生成，并通过register-asset.sh注册到 manifest verify-assets.sh检测孤儿图和未注册资产，防止 README 断链- 运行
pnpm graphify:doctor检查图谱环境；仅在明确需要时执行pnpm graphify:build
| 层级 | 技术 / 资产 | 说明 |
|---|---|---|
| Skill 入口 | SKILL.md |
触发描述、路由规则和最小执行约束 |
| UI Profile | .agents/skills/manifest.json |
surface/stack/motion/phase/artifact 的确定性路由、冲突和组合规则 |
| 外部来源治理 | .agents/vendor-skills.lock.json |
固定 commit、许可证、本地 SHA256 与安全适配 |
| 前端体验门禁 | util-verify-frontend-experience.sh |
构建、浏览器、数据状态、无障碍、响应式和动效证据 |
| 规则文档 | references/*.md |
新项目、老项目、README、assets、graphify 详细规则，按需加载 |
| 自动化脚本 | Bash | 扫描、创建、升级、校验、同步，每个脚本均可独立调用 |
| 母版资产 | assets/templates/omni-platform/ |
官方平台母版快照，新项目的唯一来源 |
| 架构图 | assets/architecture/{zh-CN,en}/*.png |
skill 自身的中英文工作流图和资源地图 |
| 图片编排 | image-orchestration.md |
Baoyu 场景策划路由、5图预览、一次确认与风格方向门禁 |
| 视觉生成 | Codex imagegen |
从已保存提示词生成最终位图 |
| README 校验 | scripts/readme-gate.py |
README 内容完整性与结构合规检查 |
User Request
↓
SKILL.md（路由识别：new / existing / partial / hybrid）
↓
scripts/inspect-project.sh ← 扫描项目现状
↓
┌─────────────────────┬──────────────────────────────┐
│ New Project │ Existing Project │
│ │ │
│ create-platform- │ upgrade-existing- │
│ project.sh │ project.sh │
│ ↓ │ ↓ │
│ 5图预览 → 用户选择 │ style-direction → imagegen │
└─────────────────────┴──────────────────────────────┘
↓
scripts/check-project-baseline.sh
↓
README · AGENTS · CLAUDE · assets · docs · graphify
SKILL.md只负责路由识别，保持极轻量，避免上下文膨胀- 详细规则按需加载自
references/，单次任务通常只需 1 个 workflow + 1–3 个规则文件 - 重复性动作封装进
scripts/，每个脚本通过bash -n语法校验后才能合入 assets/templates/omni-platform/是新项目的唯一母版来源，禁止从 AI 记忆重建
platform-project-skill/
├── SKILL.md # 触发入口与路由规则
├── START-HERE.md # 首次接手导航
├── README.md # 本文档
├── AGENTS.md # Agent 接手说明
├── CLAUDE.md # Claude Code 专属配置
├── assets/
│ ├── architecture/{zh-CN,en}/ # skill 自身中英文架构图（.png）
│ ├── prompts/ # 图片生成 prompt 模板
│ └── templates/
│ └── omni-platform/ # 官方平台母版快照
├── references/
│ ├── INDEX.md # 规则索引（按需加载入口）
│ ├── workflow-new-project.md # 新项目工作流
│ ├── workflow-existing-project.md # 老项目工作流
│ ├── readme-rules.md # README 生成规则
│ ├── assets-rules.md # 资产管理规则
│ └── ...
├── scripts/
│ ├── create-platform-project.sh # 新项目创建
│ ├── upgrade-existing-project.sh # 老项目升级
│ ├── inspect-project.sh # 项目扫描
│ ├── check-project-baseline.sh # 基线校验
│ ├── validate-platform-project.sh # 新项目统一总验证器
│ ├── run-derived-regression.sh # 真实派生回归
│ ├── verify-assets.sh # 资产校验
│ ├── register-asset.sh # 资产注册
│ ├── add-star-history.sh # 首次公开发布后补 Star History
│ └── sync-omni-template.sh # 母版同步
├── examples/ # 完整流程示例快照
└── governance/ # 风险记录与决策日志
| 命令 | 说明 |
|---|---|
scripts/inspect-project.sh <path> |
扫描项目现状，输出缺口报告，决定走哪条路由 |
scripts/create-platform-project.sh <slug> <parent> [name] [cn] |
从 omni-platform 母版创建新平台项目 |
scripts/upgrade-existing-project.sh <path> [flags] |
非侵入式升级老项目，补齐 AI 接手层 |
scripts/verify-assets.sh <path> |
校验资产注册表，检测孤儿图和缺失图 |
scripts/record-style-preview.py <project> ... |
登记单张低清风格候选及提示词，不进入正式资产 |
scripts/verify-style-previews.py <project> |
校验5张差异化候选或当前用户的显式跳过授权 |
scripts/verify-style-direction.py <project> |
校验用户一次性确认的项目视觉方向 |
scripts/record-visual-acceptance.py <project> <image> ... |
逐图记录人工验收人、时间、hash 和7项检查结果 |
scripts/verify-visual-acceptance.py <project> |
验证全部 required 与已生成 optional 图片具有当前人工验收证据 |
scripts/check-open-source-readme.sh <path> |
校验公开仓库派生 README：默认中文、完整英文版、顶部介绍图、双语图片 |
scripts/check-project-baseline.sh [--existing] [--open-source] <path> |
结构基线校验，输出 baseline_done/failed；--open-source 追加公开 README 检查 |
scripts/validate-platform-project.sh <path> |
新项目统一总验证，覆盖 Agent baseline/Profile、前端体验契约、资产、结构、README 与双 Compose，独占 validation_done/failed |
assets/templates/omni-platform/scripts/util-verify-agent-skills.sh |
校验8个 baseline、全部 Profile、vendor lock、Skill 元数据和禁止副作用规则 |
assets/templates/omni-platform/scripts/util-select-agent-profiles.sh |
根据 surface/stack/motion/phase/artifact 确定性选择 UI Profile |
assets/templates/omni-platform/scripts/util-verify-frontend-experience.sh |
初始化校验体验契约，真实 UI 交付校验浏览器、状态、可访问性与动效证据 |
scripts/run-derived-regression.sh [--full] |
在 Skill 自身 tmp/ 派生并执行正负向回归；--full 追加安装与构建 |
scripts/register-asset.sh <project> <image-path> <prompt-path> |
在 style_direction_done 后注册正式图片到 asset-manifest.json |
scripts/add-star-history.sh <project> <owner>/<repo> |
首次公开发布后向中英文 README 写入真实 Star History，并用于二次提交 |
scripts/sync-omni-template.sh |
从上游同步 omni-platform 母版到最新版本 |
改触发条件和路由 → 优先改 SKILL.md，不要动 references/
改流程规则 → 优先改 references/ 中对应的规则文件，单个任务通常只需修改 1–3 个文件
改重复性动作 → 优先改 scripts/，改完必须跑 bash -n <script> 通过语法校验再提交
# 正确方式：走同步脚本
scripts/sync-omni-template.sh
# 禁止手动编辑 assets/templates/omni-platform/
# 下次同步会覆盖所有手动修改# 1. 对同一项目概览生成5张 normal/1K 预览与提示词，展示并等待选择
# 2. 一次性确认并写 assets/style-direction.md
# 3. 用 Codex 原生 imagegen 从已保存、继承 style-direction 的提示词生成正式图
# 4. 注册到 manifest
scripts/register-asset.sh <project> assets/platform/cognition/zh-CN/<slug>-project-hero.png assets/prompts/project-cognition-image-prompt-zh-CN.md
# 5. 校验无孤儿图
scripts/verify-assets.sh .# 1. 脚本语法检查
for f in scripts/*.sh; do bash -n "$f" && echo "ok: $f"; done
# 2. Codex 项目 Skill 门禁（对母版执行）
bash assets/templates/omni-platform/scripts/util-verify-agent-skills.sh --baseline
bash assets/templates/omni-platform/scripts/util-verify-agent-skills.sh --profiles
bash assets/templates/omni-platform/scripts/util-verify-frontend-experience.sh --contract
# 3. README gate
python3 scripts/readme-gate.py --readme README.md
# 4. 真实派生回归（发布前使用 --full）
scripts/run-derived-regression.sh --full
# 5. 若是公开仓库派生 / 产品化 fork，追加 open-source README 校验
scripts/check-project-baseline.sh --existing --open-source /path/to/forked-project以上门禁全绿才算验证通过。任何 STATE=failed 或孤儿图警告均不允许使用"完成"措辞。
- README 必须通过 gate（无缺失节、无占位符、以
#开头） - 脚本必须通过
bash -n语法检查 - skill 目录内不得保留
.DS_Store、node_modules、dist - README 展示图不得放进 fenced code block，必须用 Markdown 图片语法直接引用
- 当前状态：
生产可用 - 版本阶段：
0.6.0 · Stable - 维护方式：随
omni-platform母版持续同步 - 兼容范围：
macOS / Linux · Bash 3.2+ · Claude Code / Codex / Cursor / OpenClaw - 已知风险与回归证据：见 governance/RISKS.md
如何初始化一个新平台项目？
scripts/create-platform-project.sh my-platform /path/to/parent "My Platform" "我的平台"执行完成后，必须等 STATE=initialization_done 才向用户报告完成。流程：scaffold_done → agent_ready_done → style_preview_done → style_direction_done → asset_done → visual_acceptance_done → validation_done → initialization_done，禁止跨越任何阶段。
老项目升级会改动我的业务代码吗？
不会。upgrade-existing-project.sh 默认只新建以下文件，不动任何已有文件：
AGENTS.md、CLAUDE.md、START-HERE.md（AI 接手层）docs/ai-upgrade/upgrade-report.md（升级报告）
需要扩展资产目录加 --with-assets；需要文档结构加 --with-platform-docs；先用 --dry-run 预览所有变更。
架构图可以用 Mermaid / SVG 代替 image_gen 吗？
不可以。README 里的展示图必须先完成风格预览和用户确认，再通过 Codex 原生 imagegen 生成最终 .png，并通过 register-asset.sh 注册到 asset-manifest.json。
Mermaid / SVG / HTML 只用于过程讨论和草稿，不是最终交付物。verify-assets.sh 会检测未注册的孤儿图并报错阻断流程。
README 怎么算生成完成？
必须通过 gate：
python3 scripts/readme-gate.py --readme README.mdgate 通过 + 所有占位符已替换 = README done。否则不允许向用户报告交付。
skill 兼容哪些 AI Agent？
任何支持 SKILL.md 的 Agent 均可使用：Claude Code、Codex、Cursor、OpenClaw、Windsurf。安装时将 skill 目录复制到对应 Agent 的 skills 路径，重启 Agent 即生效。
欢迎 Issue 和 PR！无论是 Bug 报告、功能建议还是文档改进，都是对这个项目的贡献。
如何参与：
- 报告 Bug：提 Issue，附上
scripts/inspect-project.sh的输出和最小复现步骤 - 新功能建议：先开 Issue 讨论方向，确认可行后再提 PR，避免无效劳动
- 脚本修改：改完必须通过
bash -n <script>语法校验，提 PR 时附上验证结果 - 文档修改：改完必须通过
python3 scripts/readme-gate.py --readme README.md，gate 通过再提交
完整贡献指南请见 CONTRIBUTING.md —— 含本地验证步骤、提交前检查清单、代码规范。
阅读贡献指南 → · 查看 Issues → · 提交 PR →
English contributors are welcome! Feel free to submit PRs or issues in English. See docs/README_en.md for the English documentation and CONTRIBUTING.md for the contribution guide.
| 版本 | 状态 | 变更摘要 |
|---|---|---|
Unreleased |
开发中 | 后续兼容性与母版演进 |
0.6.0 |
当前 | Baoyu HTML 原型隔离路由、图片场景编排、5图风格预览与视觉方向门禁 |
0.5.0 |
归档 | 确定性 UI Profile、安全外部 Skill 适配、数据产品 UX、前端体验证据门禁 |
0.4.0 |
归档 | 安全 MCP、6-Skill 基线、双语认知图、hash 绑定人工验收、locale gate、显式 graphify、完整派生 CI |
0.3.0 |
归档 | 双路径工作流、资产注册校验、README gate 集成 |
0.2.0 |
归档 | 老项目升级脚本、non-invasive 原则落地 |
0.1.0 |
归档 | 新项目初始化、omni-platform 母版内置 |
完整变更历史见 CHANGELOG.md，遵循 Keep a Changelog 与语义化版本。
本项目建立在以下优秀项目之上：
Claude Code · Codex CLI · graphify · omni-platform · Agent-Reach · codebase-memory-mcp
如果这个 skill 对你有帮助，欢迎点亮一颗 Star ⭐ —— If this skill helps you, please consider giving it a star.
MIT License © 2026 qierkang
- Email：xyqierkang@gmail.com
- GitHub：github.com/qierkang