中文文档目录 · 项目本地 Skill · 分阶段治理 · 可核验的交付证据
SKILL.md 技能入口，面向 Codex、Claude Code 等 AI 编程工具；按各工具的加载方式使用
结构即文档，接手即开发
⭐ 如果这个 Skill 对你有用，欢迎点个 Star
你在用 AI Agent 开发，但每次启动新项目、接手老代码，总绕不开这些摩擦：
- 🗂️ "帮我初始化一个平台项目" → 靠感觉搭，目录不统一、漏掉 Docker、缺 README、没有 AGENTS.md
- 🤖 "帮我接手这个老项目" → AI Agent 读不懂，没有 CLAUDE.md、没有接手层、从零开始摸索
- 📐 "帮我画个架构图" → 每次各搞一套，有的放
docs/、有的放根目录、格式完全不统一 - 📝 "帮我写 README" → 占位符全没填完，没通过 gate 就算交付了
- 🔄 "把这个项目给 AI 接手" → 不知道补什么，AGENTS.md 写什么、graphify 要不要跑、哪些文件必须有
这些不难解决，但需要一套固定规范和可复用的工程流程。
Platform Project Skill 把这些动作变成可复用、可验证的流程，而不是一次性的提示词：
告诉你的 AI Agent：
请使用 /path/to/platform-project-skill/SKILL.md，
在 /path/to/parent 下初始化 my-platform，中文名“我的平台”。
按中文目录标准输出文档；未通过总验证时只报告已完成阶段和缺口。
或直接用脚本：
# 以下命令在本 Skill 仓库根目录执行
# 新项目：只生成骨架，后续仍需资产与验证流程
scripts/create-platform-project.sh my-platform /path/to/parent "My Platform" "我的平台"
# 老项目：先预览保守升级计划
scripts/upgrade-existing-project.sh /path/to/existing-project --dry-run| 🔄 双路径工作流 | 同一个 skill 覆盖新项目初始化和老项目 AI 接手升级，不用切换工具 |
| 🛡️ 非侵入原则 | 老项目只补 AI 接手层，不移动源码、不重构目录、不替换技术栈 |
| ✅ 可校验交付 | 内置 README gate、资产校验、基线检查，完成前必须过验证，不允许虚报 |
| 📦 母版内置 | 骨架复制无需在线拉取母版；依赖安装、Spec Kit 和图片生成另有环境要求 |
| 🤖 项目本地能力 | 8 个基础 Skill、8 类动态 UI Profile；自动选择不回退到全局 ECC Skill |
| 🗂️ 中文文档标准 | 当前需求、架构设计、部署运维、测试验收、方案交接与历史归档分开管理 |
platform-project-skill 是面向 AI 编程的项目脚手架与治理技能包。新项目从内置母版派生多端工程、Docker 配置、中文文档目录、项目本地 Skill 和验证脚本；老项目按需补接手文档与治理入口，不默认搬移源码或更换技术栈。Graphify 仅提供待生成入口，codebase-memory-mcp 仅提供可选项目级包装脚本，不自动安装、索引或启动 watcher。
默认基础设施策略：优先配置复用已有 PostgreSQL / Redis；只有共享服务不可用或用户明确要求隔离时，才选择 standalone-infra profile。创建骨架不会自动启动容器或修改数据库；实际建库、角色与命名空间操作仍需在授权范围内执行。
当前文档口径：0.9.0 本地工作版本，更新于 2026-09-28。 本轮重点为可恢复升级、计划与执行一致、显式 Skills 迁移、防漂移范围校验和迁移工具去重；不代表此版本已发布。既有繁体文档与英文文档保留作参考，当前行为以本页、
SKILL.md和脚本为准。
- 母版驱动：新项目只通过内置
omni-platform派生；先扫描目标，再依据现状与用户意图选择工作流。 - 中文目录优先：七类文档分区，当前正式需求与历史归档分离；保留工具要求的英文文件名。
- 保守升级：不默认修改业务代码、目录和技术栈；既有接手文档可能追加治理说明，执行后必须审查 diff。
- 开发范围约束：基础 Skill 约束假设、修改范围和验证，可选 Spec Kit 固化项目原则、规格、计划与任务。
- 证据分层：区分骨架生成、Skill 就绪、图片验收、总验证和真实页面交付，不以单项检查替代全部验收。
这不是把一批热门 Skill 原样堆进项目。Platform Project Skill 把开发、设计系统、数据体验、动效、审查、交接和验证拆成不同阶段，再通过确定性 Profile 路由到当前任务真正需要的能力。
结果是：Agent 在开发普通表单时不会加载复杂动效规则；开发数据工作台时会自动补齐表格、筛选、权限和异常状态；开发品牌页面时才提高视觉表现和动效强度；页面可运行后再进入精修与验收。
| Skill | 负责什么 | 什么时候使用 |
|---|---|---|
| karpathy-guidelines | 控制范围、显式假设、保护脏工作树 | 所有代码和配置修改 |
| frontend-development | 沿用现有前端栈，实现交互、响应式和无障碍 | 前端与移动端实现 |
| frontend-code-review | 正确性、交互、性能和回归审查 | 前端实现完成后 |
| backend-development | 沿用现有后端栈，管理 API、数据边界和迁移协作 | 服务端开发 |
| backend-code-review | 安全、契约、数据完整性和并发风险 | 服务端审查 |
| project-verification | 构建、Docker、HTTP、浏览器和交付证据 | 验证与发布准备 |
| handoff-project-safe | 把当前任务压缩成项目内可接手交接 | 阶段收口或切换会话 |
| ui-experience-orchestrator | 选择正确的 UI、数据、动效和精修 Profile | 每次页面设计或实现前 |
有防偏离约束，但不是一个能够保证“永不偏离”的独立 Skill。 当前由以下机制配合：
| 层级 | 机制 | 约束边界 |
|---|---|---|
| 修改前 | karpathy-guidelines |
显式说明假设、限定范围、优先既有模式、保护未提交改动 |
| 复杂需求 | 可选 Spec Kit | 以 constitution → specify → plan → tasks 固化原则与验收；明确授权后才进入 implement → converge |
| 实施后 | project-verification 与前后端审查 Skill |
检查实际 diff 和验证证据，不把“代码已改”视为“验收已过” |
| 跨会话 | handoff-project-safe |
将已完成项、未决问题和下一步写入项目内交接记录 |
| 能力选择 | 项目本地 manifest | 自动路由只选项目内声明的 Skill/Profile；显式指定的全局 Skill 是例外 |
新项目默认携带上述基础 Skill；普通老项目升级不等于安装整套基础 Skill。Spec Kit 也需单独完成项目集成，manifest 中的声明不能作为已安装或已执行的证据。详细阶段边界见 Spec Kit 规则。
0.9.0 增加可执行的任务范围门禁：util-verify-task-scope.py init/check 绑定目标、非目标、允许/禁止路径和验收条目，比较任务开始后的文件变化。契约变化或越界会失败；它不能判断业务语义，也不能代替真实测试。示例见任务范围契约。
本 Skill 不安装 Alembic、不新增数据库 Skill、不自动连接或同步数据库。 多人协作依靠项目自己的版本化迁移文件，而非特定工具：已有 Prisma、Drizzle、Flyway、Liquibase、Alembic 或 SQL 迁移时沿用唯一体系；新项目按实际技术栈另行选型。
迁移协作规范已合入 backend-development，验收要求合入 project-verification：关注迁移历史不可改写、分支冲突、空库初始化、带数据升级、幂等执行及环境授权。详见数据库迁移协作规范。目录存在、Skill 安装成功和生成 SQL，都不等于表结构已同步。
本轮审查保留 16 个实体 Skill / 8 个 baseline / 8 个 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 | 项目内适配：依据事实推导简报，区分 Greenfield / Preserve / Overhaul，尊重既有技术栈和 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/方案与交接/交接记录，不使用系统临时目录 |
| Baoyu Design | 高保真 HTML 原型、线框、交互探索和设计系统预览 | github.com/JimLiu/baoyu-design | 固定 commit 的项目内安全适配；只写 docs/架构与设计/原型，不替代生产代码或位图 |
内置的第三方 Skill 适配在生成项目的 .agents/vendor-skills.lock.json 中记录 commit、许可证、本地 SHA256 和安全适配，并由 .agents/VENDOR-NOTICES.md 保留声明。骨架初始化不会运行这些上游 Skill 的安装器、自动更新、全局 MCP、代理服务或 provider Hook；Headroom 已明确排除。Ant Design、GSAP 等运行依赖仍按真实项目需要选装。
项目自带 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
示例（在生成项目根目录执行，而不是本 Skill 仓库根目录）：
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。
以下比较默认交付方式，不代表其他工具无法通过定制实现相同能力。
| 方案 | 目录规范 | 老项目处理 | Skill 路由 | 验证依据 | 跨会话约束 |
|---|---|---|---|---|---|
| Platform Project Skill | 内置中文母版 | 保守升级脚本 | 8 类 UI Profile 与项目 manifest | 分层脚本与证据契约 | 接手文档、可选 Spec Kit |
| 手动搭建 | 人工约定 | 人工判断 | 自行配置 | 自行补充 | 自行维护 |
| 直接复制模板 | 继承模板内容 | 需额外设计迁移边界 | 取决于模板 | 取决于模板 | 取决于模板 |
| 仅靠会话提示词 | 每次重新描述 | 容易遗漏已有边界 | 随会话决定 | 需另行留证 | 依赖交接完整性 |
| 场景 | 路由 | 说明 |
|---|---|---|
| 🆕 新平台项目 | new |
从 omni-platform 母版复制骨架，替换命名，补齐所有标准文件 |
| 🔧 老项目 AI 升级 | existing |
扫描现有结构，补接手层及治理入口，不默认修改业务代码 |
| 📝 局部补全 | partial |
只补 README、assets、graphify 中的一项，适合轻量任务 |
| 🔀 基座派生 | hybrid |
用户明确要求采用母版重组时使用；不能由普通升级隐式触发 |
| 📦 公开仓库派生 | open-source-fork |
保留来源与许可证，补齐中文 README 和产品化接手资料 |
| 📐 项目治理 | Spec Kit | 原则、规划、实现分开授权；规划完成不自动开始写业务代码 |
不确定走哪条路？ 先跑
scripts/inspect-project.sh <path>获取结构、语言和文件存在性信息，再结合用户意图选择路由；扫描输出不替代升级范围确认。
| 使用场景 | 主要依赖 |
|---|---|
| 读取规范或仅修改 README | 可读取 SKILL.md 的 Agent；README gate 需要 Python 3 |
| 创建骨架与执行升级脚本 | Bash 3.2+、Git、rsync、Perl、Python 3、Node.js 及常用命令行工具 |
| 项目安装与构建 | 按生成项目 package.json 的 packageManager 使用 pnpm；当前母版为 pnpm@10.33.2，仓库 CI 使用 Node.js 20 |
| 新项目总验证 | 另需 Docker Compose；验证器执行 config -q，不负责启动服务 |
| 正式视觉资产与完整初始化 | Codex 原生 imagegen、用户风格确认和逐图人工验收 |
| Spec Kit 项目集成 | 已安装且支持项目集成命令的 specify CLI；默认不替用户安装全局工具 |
| 维护脚本回归 | 另需 rg；--full 会安装依赖并构建，需要相应网络与环境 |
# 使用已取得的 Skill 仓库；后续 scripts/ 命令默认在此执行
cd /path/to/platform-project-skill向 Agent 提供这个目录下 SKILL.md 的实际路径，或按所用工具的 Skill 发现规则安装。仅复制目录或重启工具不保证被自动加载；先确认读取了正确入口，再执行目标项目任务。
# 推荐显式提供显示名与中文名，slug 必须为小写 kebab-case 并以 -platform 结尾
scripts/create-platform-project.sh my-platform /path/to/parent "My Platform" "我的平台"脚本输出 STATE=scaffold_done，不代表完成初始化。my-platform 对应的子工程是 my-front、my-mobile、my-server；省略中文名时脚本只会回退到 slug 并警告。
查看生成项目的主要结构
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/
│ ├── prompts/ ← 图片提示词
│ ├── style-previews/ ← 风格候选登记与简报模板
│ ├── style-direction.template.md
│ └── asset-manifest.json ← 正式图片契约，图片需后续生成
├── docs/
│ ├── README.md ← 中文文档导航
│ ├── INDEX.md ← 兼容索引入口
│ ├── 正式需求文档/ ← 当前需求、范围和变更记录
│ ├── 架构与设计/ ← 架构、接口、配置、UI 和原型
│ ├── 部署与运维/ ← 部署、环境、发布和运维资料
│ ├── 测试与验收/ ← 测试、审查、冒烟和验收证据
│ ├── 方案与交接/ ← 专项方案、AI 治理和交接记录
│ ├── 历史归档/ ← 旧需求、旧报告和只读参考
│ └── 维护脚本/ ← 文档生成、校验和索引工具
├── my-front/ ← 前端工程（React + Vite）
├── my-server/ ← 服务端工程（含 Docker）
├── my-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 ← 待生成入口，不是已分析完成的图谱
完整初始化按以下顺序推进，不能把复制母版等同于验收完成：
scaffold_done → agent_ready_done → style_preview_done → style_direction_done
→ asset_done → visual_acceptance_done → validation_done → initialization_done
下列既有配图保留作流程概览；当前目录名、阶段和门禁以正文及规则文件为准。
# 先查看默认升级计划；dry-run 不替代执行后的 diff 审查
scripts/upgrade-existing-project.sh /path/to/existing-project --dry-run
# 确认范围后执行；使用上一步输出的计划 ID，防止审批后内容变化
scripts/upgrade-existing-project.sh /path/to/existing-project --apply --expect-plan <PLAN_ID>
# 可选：同样先计划，审核后用相同参数加 --apply --expect-plan
scripts/upgrade-existing-project.sh /path/to/existing-project --with-assets
# 需要中文 docs 分类时，先以相同参数预览，再执行
scripts/upgrade-existing-project.sh /path/to/existing-project --with-platform-docs --dry-run
scripts/upgrade-existing-project.sh /path/to/existing-project --with-platform-docs --apply --expect-plan <PLAN_ID>
# 显式安装/迁移项目本地 Skills；不会安装运行依赖或连接数据库
scripts/upgrade-existing-project.sh /path/to/existing-project --with-agent-skills
scripts/upgrade-existing-project.sh /path/to/existing-project --with-agent-skills --apply --expect-plan <PLAN_ID>
# 仅在用户请求 Spec Kit / 项目原则时启用；需要已有 specify CLI
scripts/upgrade-existing-project.sh /path/to/existing-project --with-spec-kit--with-platform-docs 只补缺失的中文分类与导航，不搬移或删除既有英文目录。默认升级报告为 docs/方案与交接/AI治理记录/report-老项目AI能力升级.md；若旧版 docs/ai-upgrade/ 下已有同名报告且中文报告尚不存在，则沿用旧位置，避免重复报告。已有报告默认保留，显式 --refresh-report 才刷新。
非侵入不等于完全不写已有文件：AGENTS / CLAUDE 的追加内容作为 UPDATE 进入计划。只有显式 --with-agent-skills 才迁移整套 Skills 和 manifest；只补文档不再虚增 generator.version。未知定制会阻断，不强制覆盖。执行采用逐文件 no-follow 检查、内容指纹、项目锁、备份回执和失败恢复；存在跳过项只报告 upgrade_partial。完整约定与回滚方式见升级安全契约。
Spec Kit 是可选治理链路，不是创建骨架时自动完成的安装步骤。先完成项目集成，再用自然语言表达阶段与边界：
帮我按项目规范梳理这个老项目：先检查现状，补齐 AI 接手层并初始化 Spec Kit，只建立项目原则，不改业务代码。
| 自然语言入口 | 执行阶段 | 停止边界 |
|---|---|---|
| “项目治理 / 梳理项目原则 / 建立项目宪章” | constitution | 只建立原则，不开始业务实现 |
| “需求规划 / 按项目规范规划” | specify → plan → tasks | 缺少宪章时先补；完成任务清单后停止 |
| “规范实现 / 按项目规范实现” | implement → converge | 先读取规格、方案、任务和 checklist，再实施与收敛 |
首次启用也可以直接执行：
scripts/ensure-spec-kit.sh /path/to/project
scripts/ensure-spec-kit.sh /path/to/project --apply --expect-plan <PLAN_ID>第一条只计划，第二条应用。CLI 先在项目内临时目录隔离执行；已有规格/宪章被改写、状态异常或路径冲突时失败。详见 references/spec-kit-rules.md。
# 新项目（统一严格验证）
scripts/validate-platform-project.sh /path/to/project
# 老项目结构检查（manifest 可缺失并提示 WARN，不表示 Skill 全部就绪）
scripts/check-project-baseline.sh --existing /path/to/project
# 公开仓库派生 / 产品化 fork（强制检查中文根 README、顶部图、中文图片）
scripts/check-project-baseline.sh --existing --open-source /path/to/project总验证覆盖初始化契约、资产、README 和 Compose 配置，但不执行应用构建、服务启动或真实浏览器验收。页面交付需另跑生成项目的前端体验验证器，提供真实证据；见开发与验证。
- 从内置
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提供结构、语言和已有文件信息，作为范围判断依据。- 补缺失接手文件，按需追加治理路由；不默认改业务代码、构建工具或源码目录。
- 对报告目录、assets、docs 等目标检查
.gitignore；不能把这当作所有单文件路径都已获得写入保护。 - 按检测到的语言生成差异化
AGENTS.md，保留已有.claude/CLAUDE.md入口。 - 输出升级报告，支持先预览、按需刷新，以及显式启用中文 docs 或 Spec Kit。
新项目直接使用下列分类，不先生成英文目录再搬移；老项目仅在显式传入 --with-platform-docs 时补分类。规范入口见 docs 结构规则。
| 目录 | 内容与推荐子目录 |
|---|---|
docs/正式需求文档/ |
当前有效需求、范围边界、数据契约、需求清单与变更记录 |
docs/架构与设计/ |
技术方案、UI 设计；架构/、接口/、配置/、原型/ |
docs/部署与运维/ |
部署说明、环境映射、运维资料；发布记录/ |
docs/测试与验收/ |
用例、代码审查、冒烟、QA、UI 与产品验收；控制/ |
docs/方案与交接/ |
方案文档/、交接记录/、AI治理记录/ |
docs/历史归档/ |
已失效需求、旧报告、旧系统证据、上游只读快照；不作为当前需求真值 |
docs/维护脚本/ |
文档生成、校验、索引维护；产品构建脚本仍放根级 scripts/ |
- 新项目同时提供
docs/README.md中文导航和docs/INDEX.md兼容入口；老项目保留已有导航，仅在缺失时补docs/README.md和分类说明，不强制新增INDEX.md。 - 文档文件名优先中文，可保留
spec-、report-、checklist-、draft-前缀；README.md、manifest.json、request.yaml等标准入口与协议文件名保留。 - 既有英文路径不自动重命名；如确需迁移，单独核对引用、构建与部署影响，再在授权范围内执行，避免产生两套当前需求。
- 正式生图前先生成同一项目概览的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，共5张；不再生成英文 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 |
schema v3、生成器版本、项目本地路由、冲突和组合规则 |
| 外部来源治理 | 生成项目的 .agents/vendor-skills.lock.json |
内置第三方 Skill 的 commit、许可证、本地 SHA256 与安全适配 |
| 前端体验门禁 | util-verify-frontend-experience.sh |
构建、浏览器、数据状态、无障碍、响应式和动效证据 |
| 规则文档 | references/*.md |
新项目、老项目、README、assets、graphify 详细规则，按需加载 |
| 自动化脚本 | Bash、Python 3、Node.js、Perl、rsync | 扫描、创建、升级、校验与同步 |
| 母版资产 | assets/templates/omni-platform/ |
官方平台母版快照，新项目的唯一来源 |
| 架构图 | assets/architecture/{zh-CN,en}/*.png |
Skill 自身保留的历史配图；新派生项目默认只生成中文图 |
| 图片编排 | references/image-orchestration.md |
Baoyu 场景策划路由、5图预览、一次确认与风格方向门禁 |
| 视觉生成 | Codex imagegen |
从已保存提示词生成最终位图 |
| 项目治理 | Spec Kit、scripts/ensure-spec-kit.sh |
显式启用项目集成，规划与实现分开授权 |
| README 校验 | scripts/readme-gate.py |
README 内容完整性与结构合规检查 |
用户请求 + 目标路径
→ SKILL.md + inspect-project.sh
→ 根据现状、授权范围选择工作流
├─ new：创建骨架 + 中文 docs + 项目本地 Skill
│ → Skill 就绪 → 风格候选与确认 → 正式生图 → 人工验收
│ → validate-platform-project.sh → 初始化完成报告
├─ existing：预览升级 → 补接手层 / 按需中文 docs
│ → 审查 diff → check-project-baseline.sh --existing
└─ partial / hybrid / open-source-fork：按各自规则限定范围
可选治理：Spec Kit 集成 → constitution → specify → plan → tasks
→ 明确授权实现 → implement → converge
真实 UI 交付：构建 / 浏览器 / 状态 / 无障碍 / 动效证据 → 体验门禁
图谱与索引：仅在任务需要并获授权时启用，不随初始化自动运行
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 # 老项目工作流
│ ├── docs-structure-rules.md # 中文 docs 分类与兼容边界
│ ├── spec-kit-rules.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] |
默认计划；--apply --expect-plan 应用，--with-agent-skills 显式迁移能力，--rollback 恢复 |
scripts/ensure-spec-kit.sh <path> [flags] |
默认计划；依赖可信 specify CLI，隔离准备后显式应用 Claude/Codex 集成 |
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 [--open-source] <path> |
初始化总验证：Skill/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-task-scope.py |
init/check 绑定任务契约、记录脏工作树基线、检查新增越界变更；不替代业务验收 |
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 <source-omni-platform-path> |
先验证来源并计划；必须 --apply --expect-plan 才替换/删除，保留恢复回执，不自动查最新版 |
改触发条件和路由 → 优先改 SKILL.md；相关契约变化时同步对应 references/，避免入口与详细规则冲突。
改流程规则 → 优先改 references/ 中对应的规则文件，单个任务通常只需修改 1–3 个文件
改重复性动作 → 优先改 scripts/，改完必须跑 bash -n <script> 通过语法校验再提交
有意维护内置母版时，按范围更新模板、规则与回归；涉及第三方 Skill 内容时同步 vendor lock 的适配说明与 checksum。不要从记忆重建母版，也不要把同步脚本当成无副作用的“检查更新”。
# 默认不改母版；先审查来源和包含删除项的计划
scripts/sync-omni-template.sh /path/to/source-omni-platform
scripts/sync-omni-template.sh /path/to/source-omni-platform --apply --expect-plan <PLAN_ID>应用仍可能覆盖或删除本地定制，必须审查计划中的 UPDATE / DELETE。 来源验证已前置，执行前后有逐文件检查和恢复回执，不再先删除再验证。同步后仍须检查 diff、来源锁并运行派生回归。
# 1. 对同一项目概览生成5张 normal/1K 预览与提示词，展示并等待选择
# 2. 一次性确认并写 assets/style-direction.md
# 3. 用 Codex 原生 imagegen 从已保存、继承 style-direction 的提示词生成正式图
# 4. 注册到 manifest
scripts/register-asset.sh /path/to/project assets/platform/cognition/zh-CN/my-platform-project-hero.png assets/prompts/project-cognition-image-prompt-zh-CN.md
# 5. 校验无孤儿图
scripts/verify-assets.sh /path/to/project在本 Skill 仓库根目录执行：
python3 scripts/readme-gate.py --readme README.md
git diff --check -- README.md
git diff -- README.md另外核对本地图片、文档链接、页内锚点和命令参数。README gate 通过只代表文档结构检查通过，不代表初始化、构建或产品验收完成。
# 1. 脚本语法检查
for f in scripts/*.sh; do bash -n "$f" || exit 1; 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 追加 pnpm 安装与构建
scripts/run-derived-regression.sh --full
# 5. 若是公开仓库派生 / 产品化 fork，追加 open-source README 校验
scripts/check-project-baseline.sh --existing --open-source /path/to/forked-project这些命令适用于脚本或母版维护，不要求一次纯 README 修改重新安装整套工程。任一命令非零退出、出现 *_failed 或遗留必需项，均不能报告相应阶段通过。
派生回归会在本 Skill 的 tmp/ 内使用测试夹具检查正负向门禁；夹具图片和模拟验收记录只证明验证逻辑可用，不是实际项目的生图、人工审核或浏览器验收。未加 --full 的回归不包含依赖安装与构建。
在生成项目根目录按项目实际命令完成构建和浏览器检查，填入 docs/测试与验收/frontend-experience.json 的真实证据，再执行：
pnpm verify:frontend-experience该命令检查证据，不代替运行浏览器；初始化时的 --contract 仅验证契约结构。
- README 必须通过 gate（无缺失节、无占位符、以
#开头） - 脚本必须通过
bash -n语法检查 - 提交与发布范围不得包含
.DS_Store、node_modules、dist、真实.env或密钥；不要为整理文档删除他人的本地依赖或产物 - README 展示图不得放进 fenced code block，必须用 Markdown 图片语法直接引用
- 当前状态：
0.9.0 本地工作版本；本页不声明该版本已打 tag、推送或发布 - 文档更新：
2026-09-28；Skill 版本以 SKILL.md 为准，未发布变更见 CHANGELOG.md - 维护方式：内置母版定向维护，指定来源同步后重新验证
- 环境范围：macOS/Linux、Bash 3.2+、Python 3.10+、Git 与所需命令行依赖；Windows 原生未验证；仓库 CI 配置使用 Node.js 20 / pnpm 10.33.2，实际结果以相应运行记录为准
- Agent 适配：按所用工具加载
SKILL.md；自动发现、图片能力和 Spec Kit 集成分别确认，不作跨工具无条件兼容承诺 - 已知风险与回归证据：见 governance/RISKS.md
- 本轮受控升级就绪复评：92/100（原 68/100）；44 项安全测试、完整派生/安装/三端构建及本机真实 Spec Kit 验证通过。不是生产部署认证，也未实际升级用户生产项目；见评分依据与证据。
如何初始化一个新平台项目？
scripts/create-platform-project.sh my-platform /path/to/parent "My Platform" "我的平台"这个脚本只输出 STATE=scaffold_done。继续完成 Skill、风格、正式图片与人工验收后，运行 scripts/validate-platform-project.sh /path/to/parent/my-platform。只有总验证通过并核对全部必需项，才可在工作流报告中标记 initialization_done；不要等待创建脚本自动完成后续阶段。
老项目升级会改动我的业务代码吗？
默认命令只计划；显式应用不修改业务源码、目录结构或技术栈，但会写接手与治理文件：
- 缺失时补
AGENTS.md、CLAUDE.md、START-HERE.md，保留已有.claude/CLAUDE.md入口。 - 可能向既有 AGENTS / CLAUDE 追加已列明的治理规则；只有显式迁移完整 Skills 并验证通过，才更新能力 manifest。
- 缺失时补
scripts/ensure-spec-kit.sh、治理规则和docs/方案与交接/AI治理记录/report-老项目AI能力升级.md；已有旧版报告时按兼容规则沿用。
需要资产目录加 --with-assets；需要中文文档分类加 --with-platform-docs。先用相同参数加 --dry-run 预览，执行后仍要审查实际 diff，不能把预览当作完整的变更审计。
老项目的英文 docs 会被自动改成中文吗？
不会。升级只补中文分类，不自动重命名、搬移或删除既有路径，也不覆盖现有文档导航。当前正式需求与历史材料应明确区分；如需搬迁已有文档，必须单独评估引用和工具兼容性。完整分工见中文文档目录标准。
装好这个 Skill 后，Codex 就绝对不会偏离需求吗？
不能保证。karpathy-guidelines 提供范围约束，Spec Kit 可将复杂需求落成规格、计划和任务，验证与交接 Skill 要求留下证据；实际效果仍取决于需求是否明确、Agent 是否执行规则，以及审查是否发现偏差。需要先定方向时说“项目治理”，只规划时说“需求规划”，明确授权开发时再说“规范实现”。
架构图可以用 Mermaid / SVG 代替 image_gen 吗？
默认不可以。新生成的正式展示图先完成风格预览和用户确认，再通过 Codex 原生 imagegen 生成最终 .png，并通过 register-asset.sh 注册到 asset-manifest.json。
Mermaid / SVG / HTML 默认只用于讨论、草稿或明确请求的可编辑产物，不能冒充已通过正式位图门禁。维护既有 README 时可保留已有图片，但不能因此声称当前项目的生图与人工验收已完成。
README 怎么算生成完成？
必须通过 gate：
python3 scripts/readme-gate.py --readme README.md通过 gate 后还需核对内容事实、路径和命令。这只完成 README 交付，不等于项目初始化、真实运行或发布验证完成。
skill 兼容哪些 AI Agent？
规则与脚本可供能读取 SKILL.md 的 Agent 使用，但各工具的自动发现、命令执行、图片生成和权限机制不同。优先显式提供本 Skill 的入口路径，再确认所需工具可用；不要把“目录已复制”当作安装成功。新派生项目中的基础 Skill 是项目本地化的，Spec Kit 集成仍需另外启用。
欢迎 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 →
文档默认维护简体中文；既有翻译保留，但不把历史翻译或图片当作当前脚本行为的依据。提交、推送、创建 PR 和发布应由仓库维护者明确授权。
| 版本 | 状态 | 变更摘要 |
|---|---|---|
0.9.0 |
当前本地工作版本 / 未发布 | 升级计划、写入防护、恢复回执、显式 Skills 迁移、任务范围检查；不内置 Alembic |
0.8.0 |
本地历史版本 / 未发布 | 七类中文 docs、旧目录与报告兼容、项目本地 Skill 路由；补齐防偏离、升级边界与验证说明 |
0.7.0 |
前序工作版本 | Spec Kit 项目治理、自然语言路由、老项目 constitution bootstrap |
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，本地新增能力仍记在
Unreleased。上表记录能力演进，不作为公开 tag 或发行状态的证明。
本项目建立在以下优秀项目之上：
Claude Code · Codex CLI · graphify · omni-platform · Agent-Reach · codebase-memory-mcp
如果这个 Skill 对你有帮助，欢迎点亮一颗 Star ⭐。
MIT License © 2026 qierkang
- Email：xyqierkang@gmail.com
- GitHub：github.com/qierkang