kuailexiaozixin / tkinter-desktop

tkinter-desktop

原生 Tkinter / ttk 桌面应用的全生命周期 Agent Skill——从需求澄清、MVC 架构分层、界面设计、编码、线程与异步、SQLite 数据层、运行验证到 PyInstaller 打包交付，一次跑通，最终交付物是原生桌面 EXE（无浏览器、无本地 HTTP 服务）。

Agent Skill 是什么？ Skill 是「指令 + 脚本 + 资源」的文件夹，AI Agent 会动态发现并加载它，以在特定任务上表现得更好。本仓库遵循 Agent Skills 开放标准——一次编写，处处使用，可被 Claude、灵犀、Codex 等支持该标准的助手直接读取。

---

这是什么

本技能为 AI Agent 提供一套标准化、可复现的 Tkinter 桌面应用开发流程，解决「原生 GUI 项目结构混乱、可测试性差、打包反复踩坑」的痛点：

• 界面以 .ui 为唯一载体（pygubu Builder 加载），业务/数据层保持零第三方依赖
• MVC 分层 + Repository 数据模式，Controller 可无头测试
• 内置完整质量门禁：pytest + 无头 GUI 冒烟 + release gate，交付前自动校验
• Win32 原生能力（ctypes / pywin32）可选增强

适合：库存管理、图像批处理、工具软件、内部系统等不依赖浏览器的桌面程序。

---

技术栈（默认交付栈）

层	选型	说明
GUI 框架	tkinter / ttk	Python 标准库，无需额外安装
界面定义	pygubu	界面以 .ui 为唯一载体，运行期用 pygubu.Builder 加载
数据层	sqlite3	Python 标准库，零第三方依赖
打包	PyInstaller	产出原生 Windows EXE
原生能力	ctypes / pywin32	可选增强（Win32 消息循环、资源管理等）

---

安装 / 使用

Agent Skills 通常已内置在支持该标准的助手中（Claude、Codex、灵犀、DeepSeek Harness 等原生支持，可直接读取本仓库）；也可将本仓库显式添加为 Skill / Plugin：

# 以支持 AgentSkills 的助手为例（如 Claude Code）
/plugin marketplace add kuailexiaozixin/tkinter-desktop

本仓库同时已打包为可分发 dsh 插件（DeepSeek Harness，Cordis Bundle）发布到 npm，在 Harness 中可用一条命令安装：

dsh plugin --profile web add dsh-tkinter-desktop

也可从 GitHub Release 下载源码归档离线安装。详见下方「作为 dsh 插件使用」章节。

安装后，只需对助手说一句，例如：

「用 tkinter-desktop 技能，帮我做一个带 SQLite 的库存管理桌面程序，打包成 EXE。」

助手会读取 SKILL.md，按其中的工作流与铁律自动完成从脚手架到打包的完整链路。

---

作为 dsh 插件使用

本技能已发布为 DeepSeek Harness (dsh) 的 Cordis Bundle 插件 dsh-tkinter-desktop（npm 包，网络上的任何人均可在其 dsh 中直接安装）。插件把技能注册进 dsh 的 ctx.skills，让 dsh Agent 在会话中通过 skill 工具加载使用。形态为 Cordis Bundle（Host 侧），类型为 skill 插件（嵌入式提供方，参照官方 dsh-skill-badge）。

本插件为自包含的可分发 npm 包：npm 包根 = 技能仓库根，resourceBase 指向包根，SKILL.md 及其引用的 references/、examples/ 等资源全部随包安装，不依赖发布者的机器或仓库位置。

安装（命令行，从 npm 分发）

前置：已安装 dsh CLI（与 pnpm）。从 npm 安装插件并装入任意 profile（如 web）：

dsh plugin --profile web add dsh-tkinter-desktop

验证配置层并启动：

dsh --profile web --dump-config   # 应看到 "# == dsh-tkinter-desktop" 层
dsh web

从 GitHub Release 下载安装

不依赖 npm，可直接从 GitHub Releases 页面下载源码归档离线安装：

# 下载源码归档（zip 或 tar.gz）
curl -L -o tkinter-desktop.zip \
  https://github.com/kuailexiaozixin/tkinter-desktop/archive/refs/tags/v1.7.10.zip
unzip tkinter-desktop.zip      # 得到 tkinter-desktop-1.7.10/（内含 SKILL.md）

解压后有两种安装方式：

方式一：放入 dsh 技能发现目录（推荐，最简单）

把目录重命名为技能名（kebab-case，不含版本号）后放进用户技能目录，dsh 启动时即自动发现：

mkdir -p ~/.dsh/skills
mv tkinter-desktop-1.7.10 ~/.dsh/skills/tkinter-desktop
dsh web    # 重启后即可通过 skill 工具加载

用户技能目录默认 <dshHome>/skills，Windows 下为 C:\Users\<用户名>\.dsh\skills\。

方式二：作为 dsh 插件从本地目录安装

dsh plugin --profile web add /绝对路径/tkinter-desktop-1.7.10

dsh plugin add 支持本地目录路径（pnpm 语义），与从 npm 安装等价。

使用

启动 dsh Web UI 后，对 Agent 说一句即可触发，例如：

「用 tkinter-desktop 技能，帮我做一个带 SQLite 的库存管理桌面程序，打包成 EXE。」

Agent 会调用 skill 工具加载本技能，按 SKILL.md 的工作流完成从脚手架到打包的完整链路。

移除

dsh plugin --profile web remove dsh-tkinter-desktop

---

目录结构

tkinter-desktop/
├── SKILL.md              # 技能主入口（工作流 + 铁律）
├── CHANGELOG.md          # 版本变更记录
├── LICENSE               # MIT 许可证
├── README.md             # 本文件
├── references/           # 深度参考（架构、UI、打包、质量门禁、Win32 等）
├── examples/             # 参考实现（优先参考，非必要不自造轮子）
├── templates/            # 项目脚手架模板（含启动.bat 等）
├── scripts/              # 自动化脚本（构建、测试、门禁、UI 设计）
├── docs/                 # 交付清单、术语表、排障
├── package.json          # npm 包声明（dsh-tkinter-desktop，Cordis Bundle）
├── index.js              # 嵌入式 skill 提供方
├── cordis.patch.yml      # dsh bundle patch（注册插件）
├── pygubu/               # pygubu 子技能（界面设计唯一默认方案）
├── ctypes/               # Win32 原生 API 参考
├── pywin32/              # pywin32 模块/对象参考
└── tcl-tk/               # Tcl/Tk 底层参考

---

快速开始（给 Agent）

1. 读取入口：SKILL.md 定义完整工作流与铁律，是执行的最高依据。
2. 写控件代码前：必读 references/official-docs/ 的 ttk 官方转档（HARD-GATE）。
3. 界面设计：只用 pygubu 写 .ui + pygubu.Builder 加载，参考 pygubu/ 子技能。
4. 生成项目：用 templates/ 脚手架（含 bootstrap_project.ps1 / run_dev.py）初始化。
5. 开发迭代：Controller + Repository 分层编码，线程用 after() 调度回 UI。
6. 质量门禁：pytest + scripts/smoke_test_gui.py（无头 GUI 冒烟）+ release_gate.py。
7. 打包：scripts/build_windows_exe.ps1 产出 EXE，按 references/08-packaging.md 补 hidden-import。

参考 examples/ 中与目标最接近的项目，非必要不自造轮子。

---

贡献

欢迎提交 Issue 与 PR 完善工作流。请遵循：

• 改动技能核心逻辑时，同步更新 SKILL.md、references/ 与 CHANGELOG.md
• 新增参考实现请放入 examples/，并登记到 examples/README.md
• 保持「界面 .ui + 业务零依赖 + 质量门禁」三条铁律不被破坏

详见 contributing.md。

---

第三方内容与合规

examples/ 目录下以完整源码形式收载了若干第三方开源项目（Thonny、IDLE、pygubu-designer、Tkinter-Designer、Inventory-Management-System、Bulk Image Processor 等），它们各自保留原始许可证与版权声明，与本仓库 MIT 许可相互独立。完整来源、许可证与使用注意详见 THIRD_PARTY_NOTICES.md。

---

许可证

MIT © kuailexiaozixin

---

相关：同系列的 fasthtml-desktop（Web 桌面壳方案，技术栈互斥，可作对比）。