Skip to content
Back to search

DGUIApp开发脚手架

SkillWorks with Claude CodeGitHub

生成、审查或扩展 DGUIApp(PySide6)桌面应用脚手架。涉及 Copier 模板、横纵分层(platform/features)、SQLite 可切 MySQL、MVVM + UI Runtime、严格代码规范、质量门禁、DX 一键启动与热重载时使用;用户要求新建桌面应用工程、检查脚手架合规性或往脚手架加功能切片时也要使用。

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/sc-catl--dgui-app-scaffold/badge.svg)](/listings/sc-catl--dgui-app-scaffold)

HTML

<a href="/listings/sc-catl--dgui-app-scaffold"><img src="/api/listings/sc-catl--dgui-app-scaffold/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

把仓库放进代理的技能目录即可。OpenCode 全局技能目录:

~/.config/opencode/skills/dgui-app-scaffold/
├── SKILL.md
└── references/

也可以放在项目的 `.opencode/skills/dgui-app-scaffold/` 下,只对当前项目生效。

git clone https://github.com/SC-CATL/dgui-app-scaffold.git \
  ~/.config/opencode/skills/dgui-app-scaffold

安装后技能 ID 为 `dgui-app-scaffold`,显示名为 `DGUIApp开发脚手架`。

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 218 lines
  1. ---
  2. name: DGUIApp开发脚手架
  3. description: 生成、审查或扩展 DGUIApp(PySide6)桌面应用脚手架。涉及 Copier 模板、横纵分层(platform/features)、SQLite 可切 MySQL、MVVM + UI Runtime、严格代码规范、质量门禁、DX 一键启动与热重载时使用;用户要求新建桌面应用工程、检查脚手架合规性或往脚手架加功能切片时也要使用。
  4. ---
  5. # DGUIApp 开发脚手架
  6. 一套已经定稿的工程约定:Copier 模板 + 横纵分层 + 生产级门禁 + 快速开发。
  7. 本技能是执行入口,细节按需读取 `references/`。
  8. ## 适用与不适用
  9. 适用:
  10. - 从零生成一个 PySide6 桌面项目。
  11. - 在已有生成项目里新增业务切片、页面、迁移、适配器。
  12. - 审查一个 PySide6 项目是否符合本套分层与质量门禁。
  13. - 维护 Copier 模板本身(改参数、加 profile、升级迁移)。
  14. 不适用:
  15. - Web / 移动端 / 服务端项目。
  16. - 非 PySide6 的 Python GUI(Tkinter、wxPython)。
  17. ## 生成流程
  18. 前置:Windows 10/11、`uv` 已安装、目标目录为空或仅含 `.git`。**开工前先探测下载源**:判定慢就立即切镜像,不要带着慢源开始渲染或同步。
  19. ```powershell
  20. copier copy --trust <模板仓库> myapp
  21. cd myapp
  22. uv sync
  23. uv run dev # 建库 -> 迁移 -> 出窗口
  24. uv run pytest -q
  25. ```
  26. 也可用模板仓库的生成器一步完成(探测 + 渲染 + git + 冒烟):
  27. ```powershell
  28. python scripts/scaffold.py C:\path\myapp
  29. ```
  30. 生成器(模板仓库的 `scripts/scaffold.py`)做五步,顺序固定:
  31. 1. 探测 Python 版本并锁定。
  32. 2. 校验参数(包名合法、目录为空)。
  33. 3. 调用 `copier.run_copy` 渲染。
  34. 4. `git init` 并做首次提交(可用 `--no-git` 跳过)。
  35. 5. 写生成记录;`.venv` 存在时跑 `--self-test` 冒烟,失败删除半成品。
  36. ## 下载与镜像(工程前 + 开发中)
  37. 任何联网下载(解释器、依赖、模板、工具、wheel)都按同一口径判定;**一旦慢,立即切换镜像,不反复重试原源**。
  38. | 判定 | 阈值 |
  39. |---|---|
  40. | 吞吐不足 | 低于 200 KB/s 且持续 10 秒 |
  41. | 无进度 | 15 秒内字节数不增长 |
  42. | 单任务超时 | 超过 60 秒且预计剩余超过 5 分钟 |
  43. | 连接失败 | 连续 2 次超时、重置或 5xx |
  44. | 基线回归 | 全新 `uv sync` 超过 2 分钟 |
  45. - 工程开始前:5 秒超时探测 PyPI / GitHub / 解释器源;首字节超过 2 秒或不可达即视为慢,先为本次会话设镜像。
  46. - 开发中:发现慢立即暂停当前下载,探测候选源,选最快者重试,并记录原源、镜像与耗时。
  47. - 配置优先级:单次命令 > 会话环境 > 项目配置 > 用户全局;写全局必须先告知并给出回滚。
  48. - 有锁文件时只用 `uv sync --locked`;切镜像不得升级版本、不得关闭哈希校验。
  49. - 只用 HTTPS 可信镜像;私有包与凭证只走官方或私有源,绝不经第三方代理。
  50. - 细节、探测命令与各资源切换方式见 `references/mirrors.md`。
  51. ## 锁定参数
  52. | 项 | 值 |
  53. |---|---|
  54. | 包名 / 显示名 | `myapp` / `MyApp` |
  55. | Python | 自动探测:uv > 当前解释器 > `py -0p`,回退 3.12 |
  56. | 平台 / 许可证 | 仅 Windows / MIT |
  57. | GUI / 数据 | PySide6 / SQLAlchemy 2.0 + Alembic |
  58. | Qt 降级 | 主选 PySide6,构建时自动降级 PySide2(Qt5,仅 32 位或 Win7/8 环境) |
  59. | 工具链 | uv + ruff + mypy(strict) + pytest + pytest-qt(PySide2 固定 `>=4.2,<4.3`) |
  60. | 分发 / 模式 | 默认不打包;仅用户明确要求时才启用 PyInstaller `--onedir` / MVVM |
  61. | 架构 | 横纵分层 + ports/adapters(模块化单体) |
  62. | 数据原则 | 每种持久化数据都有对应表;`QSettings` 只存引导信息 |
  63. `python_version` 一旦锁定,`requires-python`、`.python-version`、ruff `target-version`、mypy `python_version`、CI 矩阵全部由它派生;启用打包时 PyInstaller 解释器也用它。禁止各处手写版本号。
  64. ## 当前实现状态(2026-11-17)
  65. | 项 | 状态 |
  66. |---|---|
  67. | Copier 模板 + 生成器 + 渲染矩阵 | 完成,16 项全绿;`meta-ci.yml` 已加 |
  68. | PySide6 3.12 与 PySide2 3.10 双路径 | 完成,ruff/mypy/pytest/`--self-test` 全绿,覆盖率 94%+ |
  69. | 模板仓库治理资产 | README / CHANGELOG / LICENSE / .gitignore / meta CI 已完成 |
  70. | 六服务 UI Runtime + 设置切片七件套 | 完成 |
  71. | `import-linter` 分层契约 | 完成,配置在生成项目 `pyproject.toml` |
  72. | `uv run dev` / `doctor` / `scripts/dev.py` | 完成,离屏冒烟通过 |
  73. | `include_docs` / `include_docker` / `include_packaging` | 完成,均默认关闭(打包必须显式开启) |
  74. | `profile` / `enable_sync` / `include_auth` / `include_updater` | 参数保留位,暂无分支产物 |
  75. | widgets 库 / F12 面板 / L1-L2 热重载 / seed / db reset | 规划 |
  76. ## 架构红线(违反即返工)
  77. 1. `features/*` 可以依赖 `platform/*`;`platform/*` 禁止依赖 `features/*`。
  78. 2. `features/A` 访问 `features/B` 只能 `from ..B.api import ...` 或走事件总线。
  79. 3. `app/` 是唯一组合根,唯一允许同时引用所有切片的地方。
  80. 4. 页面不写颜色与样式:`features/*/view.py` 禁止 `#RRGGBB` 与 `setStyleSheet`。
  81. 5. `QMessageBox` 只在 `platform/ui/kit/dialogs.py`;`QThread` / `QRunnable` 只在 `platform/ui/kit/tasks.py`;`app.exec()` 只在 `app/bootstrap.py`。
  82. 6. UI 线程不做 IO;跨线程只经 `platform/ui/kit/tasks.py` 的信号回传。
  83. 7. 同一逻辑出现两次即下沉到 `platform/`,切片内禁止复制平台能力。
  84. 8. 根目录 `main.py` 是薄层启动器:只转发到 `myapp.__main__:main`,禁止写业务逻辑、禁止 import `features/*`、`platform/*`、`app/*`。
  85. 9. Qt 绑定只在 `platform/ui/qt.py` 导入;其他任何文件出现 `PySide6` / `PySide2` 即为违规。
  86. 10. 禁止 Qt5 独有或已废弃 API:`QRegExp`、`QDesktopWidget`、`QFontMetrics.width`、`exec_()`。
  87. 11. 每种持久化数据都要有对应的表;`QSettings` / JSON 文件 / 注册表只允许存引导信息(数据库位置、`install_id`、安装根目录)。
  88. 12. 文件本体不入库:大文件放磁盘,另建元数据表登记路径、sha256、大小、时间。
  89. ## 代码硬指标
  90. | 项 | 上限 |
  91. |---|---|
  92. | 函数 | 30 行 |
  93. | 文件 / 类 | 300 行 / 200 行 |
  94. | 参数 / 嵌套 | 5 个 / 3 层 |
  95. | 圈复杂度 | 10 |
  96. | 行宽 / docstring | 100 / Google 风格,interrogate ≥ 90% |
  97. 参数超过 3 个必须 keyword-only;禁止位置布尔参数;可预期失败返回 `Result[T, E]`,异常只用于意外。
  98. ## 质量门禁
  99. | 指标 | 门槛 |
  100. |---|---|
  101. | 核心 / 整体覆盖率 | 85% / 75% |
  102. | 冷启动 / idle 内存 | 2.5s(P95) / 250MB |
  103. | 崩溃率 / 数据丢失 | 0.5% / 0 |
  104. | 重复代码率 | 3% |
  105. | 平台复用率 / 新功能复用率 | 60% / 80% |
  106. | 劣化回归 | 超过基线 5% 失败 |
  107. 不达标不发布;发布走 Go/No-Go 清单 + 回滚方案 + 值班人。打包相关门槛(安装包冒烟、签名、体积)只在启用打包时适用。
  108. ## 参考文件
  109. | 文件 | 何时读 |
  110. |---|---|
  111. | `references/architecture.md` | 建目录、定依赖、写数据层或切片骨架 |
  112. | `references/ui-runtime.md` | 写页面、弹窗、主题、任务提交或生命周期 |
  113. | `references/code-standards.md` | 写代码前对齐函数与写法规范 |
  114. | `references/quality-gates.md` | 配 CI、配门禁、判断能否发布 |
  115. | `references/database.md` | 建表、改表、写迁移、ORM 与事务 |
  116. | `references/lifecycle.md` | 生成记录、审查报告、归档、文档站 |
  117. | `references/dx.md` | 做一键启动、热重载、生成器、开发面板 |
  118. | `references/template-spec.md` | 改 `copier.yml`、加 profile、按阶段实施 |
  119. | `references/qt-binding.md` | 处理 PySide6 / PySide2 兼容、降级、打包差异 |
  120. | `references/mirrors.md` | 下载慢、依赖装不上、模板拉不下来、解释器或工具下载卡住 |
  121. ## 任务路由
  122. | 用户要什么 | 做什么 |
  123. |---|---|
  124. | 新建项目 | 按「生成流程」执行;参数与阶段状态见 `template-spec.md` |
  125. | 找入口 / 改启动链 | 根 `main.py` 仅转发,逻辑落在 `__main__.py`,`app.exec()` 只在 `bootstrap.py` |
  126. | 加业务功能 | `uv run python scripts/new_feature.py <name>`,读 `architecture.md` 的切片模板 |
  127. | 加页面 | 在切片内加 `view.py` + `viewmodel.py`,页面继承 `QWidget`,样式只用令牌;`new page` 生成器尚在规划 |
  128. | 加表 / 改表 | 手写 Alembic 迁移(`new migration` 生成器尚在规划),先读 `database.md`;必须可回滚 |
  129. | 改主题 | 只改 `tokens.toml`,不碰业务代码 |
  130. | 配 CI | 按 `quality-gates.md` 的四段流水线 |
  131. | 发版 | `lifecycle.md` 的审查 + Go/No-Go + 归档 |
  132. | 模板升级 | 读 `template-spec.md` 的参数表与渲染矩阵;`_migrations` 升级脚本规划中 |
  133. | 兼容老环境 | 读 `qt-binding.md`,绑定只在 `platform/ui/qt.py`,构建时自动降级 |
  134. | 要打包分发 | 先确认用户明确要求;才生成 `pyinstaller.spec`、`scripts/build.py` 与打包 CI |
  135. | 下载慢 / 依赖装不上 / 模板拉不下来 | 按 `mirrors.md` 判定慢速并立即切镜像;记录切换前后的实测 |
  136. | 换机器 / 内网部署 | 用 `mirrors.md` 的离线缓存与私有源方案,不依赖个人会话配置 |
  137. ## 生成后验收
  138. - [ ] `uv run dev` 出窗口,无裸栈报错。
  139. - [ ] `uv run app --self-test` 退出码 0,`uv run app --help` 有用法输出。
  140. - [ ] `uv run pytest -q` 全绿,覆盖率达标。
  141. - [ ] `uv run ruff check .` 与 `uv run mypy src` 零错误。
  142. - [ ] `uv run lint-imports` 分层契约通过。
  143. - [ ] `alembic upgrade head` 与 `downgrade base` 均可执行。
  144. - [ ] 每种持久化数据都能对应到一张表,主题/语言/最近打开等均已落库。
  145. - [ ] `uv run doctor` 自检全绿,输出当前 Qt 绑定与版本。
  146. - [ ] PySide6 与 PySide2 两个绑定各出一次可启动产物(仅启用打包时要求)。
  147. - [ ] 明暗主题切换无残留样式。
  148. - [ ] 关闭窗口后进程与单实例锁正常释放。
  149. - [ ] 下载全程无长时间卡住;切过镜像时,生成记录已写明原源、镜像与耗时。
  150. ## 常见错误
  151. | 现象 | 原因 | 处理 |
  152. |---|---|---|
  153. | `platform` 导入 `features` | 依赖方向反了 | 把共用能力上移到 `platform/` |
  154. | 页面样式不生效 | 直接写了 `setStyleSheet` | 改用 `tokens.toml` 令牌 |
  155. | UI 卡死 | 在 UI 线程做 IO | 改走 `ui.tasks.submit(..., pool="io")` |
  156. | SQLite `database is locked` | 并发写 | WAL + `busy_timeout`,写操作走 `serial` 池 |
  157. | 打包后启动失败(启用打包时) | 资源未收集 | 检查 `pyinstaller.spec` 的 datas 与隐式导入 |
  158. | `copier update` 冲突 | 改了模板保护区 | 业务代码放特征区,模板区变更走 `_migrations` |
  159. | `python main.py` 报 `ModuleNotFoundError` | 未 `uv sync` 或 `src/` 兜底失效 | 先在 `main.py` 插入 `src/`,仍失败则检查包名与目录 |
  160. | 启动器里堆业务逻辑 | 职责越界 | 全部移回 `__main__.py` / `app/` |
  161. | 降级后 `ImportError` | 直接写了 `import PySide6` | 改从 `platform/ui/qt.py` 导入 |
  162. | Qt5 下高分屏模糊 | 未设高 DPI 属性 | 调 `qt.enable_high_dpi()`,且在 QApplication 之前 |
  163. | 同时装了 PySide6 与 PySide2 | 依赖没锁死 | 只保留一个绑定依赖,重锁 `uv.lock` |
  164. | 设置项重启后丢失 | 存了 `QSettings` 或内存 | 入 `app_settings` 表 |
  165. | 模型加了字段但库没变 | 没生成迁移 | 手写 Alembic 迁移(`new migration` 生成器规划中),CI 跑 `alembic check` |
  166. | 启动慢 | 首屏同步导入重模块 | 延迟导入,启动耗时进基线 |
  167. | `uv sync` 长时间无进度 | 源慢或被限速 | 按 `mirrors.md` 判定并切镜像,不反复重试 |
  168. | 镜像缺少锁定版本 | 镜像同步滞后 | 该次命令回官方源,保持版本不变 |
  169. | 配了镜像仍然慢 | 镜像本身慢,或代理与镜像叠加 | 重新探测,只保留一层加速 |
  170. | 切换镜像后版本被升级 | 误跑了 `uv lock --upgrade` | 回到 `uv.lock`,用 `--locked` 重装 |
  171. | TLS 证书错误 | 企业证书未被信任 | `UV_SYSTEM_CERTS=1` 或配置企业根证书,不要关闭校验 |
  172. ## 输出要求
  173. - 改代码前先读对应 reference,不要凭记忆套规范。
  174. - 新增文件必须同时补测试与注册(容器、路由)。
  175. - 生成器改动后必须跑一次渲染矩阵,五种组合全部通过。
  176. - 切过下载源必须记录原源、镜像与耗时;不得静默修改用户全局配置。
  177. - 任何绕过门禁的改动都要在回复里显式说明原因与补救计划。
README.md · README · 82 lines
  1. # DGUIApp 开发脚手架技能
  2. 一套给 AI 编码代理使用的 **DGUIApp(PySide6)桌面应用工程规范**,以 OpenCode / Claude 兼容的 Skill 形式分发。
  3. 技能本身不包含可执行代码,而是把已经定稿的工程约定沉淀成可检索的规则:Copier 模板、横纵分层(`platform/` + `features/`)、ports/adapters、SQLite 可切 MySQL、MVVM + UI Runtime、严格代码规范、质量门禁、DX 一键启动与热重载,以及下载慢时的镜像切换策略。
  4. ## 这个技能解决什么
  5. - 从零生成 PySide6 桌面项目时,避免每次重新讨论目录、依赖方向和启动链。
  6. - 在已有项目里新增业务切片、页面、Alembic 迁移或适配器时,给出固定落点。
  7. - 审查项目是否违反分层契约、样式令牌、线程模型或质量门槛。
  8. - 工程开始前与开发中,依赖、解释器、模板或工具下载变慢时,按统一阈值判定并立即切换镜像,留下可复现记录。
  9. - 维护 Copier 模板本身:参数、profile、渲染矩阵与升级迁移。
  10. 不适用于 Web、移动端、服务端项目,也不适用于 Tkinter / wxPython 等非 PySide6 GUI。
  11. ## 安装
  12. 把仓库放进代理的技能目录即可。OpenCode 全局技能目录:
  13. ```text
  14. ~/.config/opencode/skills/dgui-app-scaffold/
  15. ├── SKILL.md
  16. └── references/
  17. ```
  18. 也可以放在项目的 `.opencode/skills/dgui-app-scaffold/` 下,只对当前项目生效。
  19. ```bash
  20. git clone https://github.com/SC-CATL/dgui-app-scaffold.git \
  21. ~/.config/opencode/skills/dgui-app-scaffold
  22. ```
  23. 安装后技能 ID 为 `dgui-app-scaffold`,显示名为 `DGUIApp开发脚手架`。
  24. ## 使用
  25. 直接对代理描述任务即可,代理会按 `description` 自动发现并加载;也可以显式引用:
  26. ```text
  27. @dgui-app-scaffold 帮我新建一个 PySide6 桌面项目
  28. @dgui-app-scaffold 审查这个项目是否符合分层与门禁
  29. ```
  30. 技能入口是 `SKILL.md`,其余细节按需读取 `references/`,不会一次性塞进上下文。
  31. ## 技能结构
  32. ```text
  33. .
  34. ├── SKILL.md # 入口:流程、红线、任务路由、验收清单
  35. └── references/
  36. ├── architecture.md # 目录、依赖方向、切片骨架
  37. ├── ui-runtime.md # 页面、弹窗、主题、任务、生命周期
  38. ├── code-standards.md # 函数与写法规范
  39. ├── quality-gates.md # CI、门禁、发布判断
  40. ├── database.md # 建表、迁移、ORM、事务
  41. ├── lifecycle.md # 生成记录、审查报告、归档
  42. ├── dx.md # 一键启动、热重载、生成器
  43. ├── template-spec.md # Copier 参数、渲染矩阵、实施路线
  44. ├── qt-binding.md # PySide6 / PySide2 兼容与降级
  45. └── mirrors.md # 下载慢速判定、镜像与离线缓存
  46. ```
  47. ## 核心约定(摘录)
  48. - `features/*` 可以依赖 `platform/*`,反向禁止;跨切片只走 `api.py` 或事件总线。
  49. - Qt 绑定只在 `platform/ui/qt.py` 导入,其他文件出现 `PySide6` / `PySide2` 即违规。
  50. - 页面不写颜色与样式,统一走 `resources/tokens.toml`。
  51. - UI 线程不做 IO,跨线程只经 `platform/ui/kit/tasks.py`。
  52. - 每种持久化数据都有对应的表;`QSettings` 只存引导信息。
  53. - 下载源慢时立即切镜像:单文件低于 200 KB/s 持续 10 秒或 15 秒无进度即判定为慢,切换后仍用 `uv sync --locked` 保持版本与哈希。
  54. 完整规则见 `SKILL.md` 与对应 reference。
  55. ## 贡献
  56. 见 [CONTRIBUTING.md](CONTRIBUTING.md)。
  57. ## 许可证
  58. [MIT](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.