miniprogram-architecture-kit

一个用于搭建标准化微信小程序项目的 Codex 技能，内置统一的前端、后端、配置与部署约定。

这个技能是做什么的

miniprogram-architecture-kit 不是一个“帮你随便生成项目”的技能，它更像是一套已经踩过坑之后沉淀下来的默认工程方案。

它的目标是：

• 从零搭建标准化的微信小程序 monorepo
• 固定前后端目录结构、配置方式和分层习惯
• 同时生成本地运行文档与生产部署文档
• 让后续的新项目不需要再重复给 AI 讲一遍相同约束

核心特性

• 默认技术栈固定：uni-app + Vue 3 + TypeScript、Go + Gin + Gorm、MySQL
• 默认项目结构统一：前后端、环境变量、Compose、部署文档一起交付
• 发布链路明确：git -> GitHub Actions -> Aliyun ACR -> Aliyun ECS -> Nginx
• 文档不是附属品：创建项目时默认同时产出 运行教程.md 和 Linux部署文档_AL3.md
• 适合持续复用：把反复出现的架构约束沉淀成技能，而不是每次临时补充说明

标准产出物

使用该技能创建新项目时，默认至少应产出这些文件和目录：

• frontend/
• backend/
• .env.example
• .env.prod.example
• docker-compose.yml
• docker-compose-prod.yml
• 运行教程.md
• Linux部署文档_AL3.md

其中：

• 运行教程.md 用于本地开发、联调和启动说明
• Linux部署文档_AL3.md 用于阿里云 ECS 生产环境部署与发布说明

安装方式

所有安装方式完成后，都建议重启 Codex，让新技能被重新发现。

方式一：手动复制

mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
cp -R ./miniprogram-architecture-kit "${CODEX_HOME:-$HOME/.codex}/skills/"

默认安装目录通常是：

~/.codex/skills/miniprogram-architecture-kit

方式二：通过 GitHub 仓库路径安装

如果本机已包含系统自带的 skill-installer，可以直接按 GitHub 仓库路径安装：

python "${CODEX_HOME:-$HOME/.codex}/skills/.system/skill-installer/scripts/install-skill-from-github.py" \
  --repo thisliu/miniprogram-architecture-kit \
  --path miniprogram-architecture-kit

方式三：通过 git clone

如果你希望后续可以直接 git pull 更新这个技能，推荐 clone 仓库后再把真正的技能目录软链接到 Codex：

git clone https://github.com/thisliu/miniprogram-architecture-kit.git ~/projects/miniprogram-architecture-kit
mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
ln -s ~/projects/miniprogram-architecture-kit/miniprogram-architecture-kit \
  "${CODEX_HOME:-$HOME/.codex}/skills/miniprogram-architecture-kit"

如果目标链接已经存在，可以先删除旧链接再重新执行：

rm -rf "${CODEX_HOME:-$HOME/.codex}/skills/miniprogram-architecture-kit"

后续更新只需要：

cd ~/projects/miniprogram-architecture-kit
git pull

使用方式

你可以直接用类似下面的提示触发这个技能：

用标准架构新建一个微信小程序项目，前端用 uni-app，后端用 Go。

帮我从零搭一个小程序仓库，要包含前后端、docker-compose 和部署文档。

创建一个小程序 monorepo，同时生成运行教程和上线文档。

当它被触发时，默认会帮助你：

1. 规划标准小程序 monorepo 结构
2. 固定前后端分层、配置和环境变量命名
3. 补齐本地开发需要的 Compose 与模板
4. 默认生成运行文档和阿里云部署文档

架构说明

这个技能采用“主规则保持精简，细节按需加载”的结构，避免把所有说明都塞进一个超长 SKILL.md 里。

路径	作用	使用时机
miniprogram-architecture-kit/SKILL.md	核心工作流、默认技术栈、交付约束	技能触发时
miniprogram-architecture-kit/agents/openai.yaml	界面展示元数据	技能列表展示时
miniprogram-architecture-kit/references/default-release-pipeline.md	默认发布链路规则	生成部署方案或发布文档时
miniprogram-architecture-kit/references/project-doc-generation-rules.md	文档生成规则与占位符约束	生成 运行教程.md / Linux部署文档_AL3.md 时
miniprogram-architecture-kit/assets/templates/运行教程.md	本地运行文档模板	创建新项目时
miniprogram-architecture-kit/assets/templates/Linux部署文档_AL3.md	阿里云部署文档模板	创建新项目时
docs/architecture.png	仓库首页架构图	GitHub 展示时

仓库结构

.
├── LICENSE
├── README.md
├── docs/
│   └── architecture.png
└── miniprogram-architecture-kit/
    ├── SKILL.md
    ├── agents/
    │   └── openai.yaml
    ├── references/
    │   ├── default-release-pipeline.md
    │   └── project-doc-generation-rules.md
    └── assets/
        └── templates/
            ├── Linux部署文档_AL3.md
            └── 运行教程.md

这样的结构把“给人看的仓库首页”和“给 Codex 安装的技能目录”分开了：

• 仓库根目录适合直接在 GitHub 首页阅读
• miniprogram-architecture-kit/ 可以被单独复制或按路径安装

默认发布流程

这个技能为“使用它创建出来的项目”规定的默认发布链路是：

1. 开发者在本地通过 git 提交代码并推送到 GitHub
2. 通过 workflow_dispatch 手动触发 GitHub Actions 发布工作流
3. GitHub Actions 运行测试并构建后端镜像
4. 镜像推送到阿里云 ACR
5. 运维或开发者在 ECS 上执行 docker compose pull && docker compose up -d
6. Nginx 负责域名接入、HTTPS 和反向代理
7. 如需回滚，切换到历史 sha-<short_commit> 镜像标签后重新拉起

默认约定包括：

• GitHub Secrets：ACR_USERNAME、ACR_PASSWORD
• GitHub Variables：ACR_REGISTRY、ACR_NAMESPACE、ACR_REPOSITORY
• 镜像标签：latest 与 sha-<short_commit>
• 生产环境默认不把 MySQL 放进生产 Compose，除非用户明确要求单机一体化部署

设计思路

这个技能的出发点很简单：

• AI 可以很快把项目“做出来”
• 但真正影响后续体验的，是架构、配置、部署和文档这些重复性工程约束
• 与其每次都重新补充一遍，不如把已经验证过的做法沉淀成一个可复用的技能

它解决的不是“不会写代码”，而是“以后不想再重复讲同样的话”。

参考资料

默认发布规则和文档规则见：

• default-release-pipeline.md
• project-doc-generation-rules.md

开源协议

采用 MIT 协议，详见 LICENSE。