fasthtml-desktop

FastHTML + pywebview 桌面应用的全生命周期 Agent Skill——从需求澄清、FastHTML Web 开发、pywebview 桌面壳包装到 PyInstaller 打包交付，最终交付物是包含 pywebview 原生窗口的 FastHTML 桌面 EXE（WebView2 渲染，本地 HTTP 服务）。

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

---

这是什么

本技能为 AI Agent 提供一套标准化、可复现的 FastHTML 桌面应用开发流程，用 Web 技术栈做出带原生窗口的桌面程序：

• Web 技术栈做桌面：FastHTML + HTMX 构建界面，pywebview 提供原生窗口（WebView2 渲染）
• 权威文档 HARD-GATE：references/05-coding/fasthtml-refs/fasthtml-llms-ctx.txt（约 1 万行官方上下文）为写码前必读
• 20+ 参考实现：examples/ 覆盖 CRM、ERP、HRM、财务、进销存、法律、文档、表单等真实业务场景
• 完整质量门禁：路由联动检查、引用检查、无头 UI 验证、release gate
• 跨平台构建：Windows / macOS / Linux 构建脚本齐全

适合：需要现代 Web 界面、又希望以原生桌面应用交付的业务系统。

---

技术栈

层	选型	说明
Web 框架	FastHTML	基于 Starlette + HTMX 的 Python Web 框架
桌面壳	pywebview	原生窗口内嵌 WebView2 渲染
交互	HTMX	服务端驱动的前端交互
打包	PyInstaller	产出含原生窗口的 Windows EXE
跨平台	辅助脚本	macOS (py2app) / Linux (AppImage)

---

安装 / 使用

本仓库遵循 Agent Skills 开放标准，技能位于 skills/fasthtml-desktop/（符合 gh skill 的 skills/*/SKILL.md 发现约定），可用 GitHub CLI（≥ v2.90.0） 一键安装：

# 安装到当前项目（project 作用域，默认）
gh skill install kuailexiaozixin/fasthtml-desktop

# 或安装到用户全局（user 作用域，所有项目可用）
gh skill install kuailexiaozixin/fasthtml-desktop --scope user

# 查看/搜索/校验
gh skill list
gh skill preview kuailexiaozixin/fasthtml-desktop

安装时技能被发现为 fasthtml-desktop；gh skill install 会按需自动注入来源元数据（metadata.github-*），支持 gh skill update 增量更新与 --pin <tag> 版本锁定。

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

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

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

dsh plugin --profile web add dsh-fasthtml-desktop

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

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

「用 fasthtml-desktop 技能，帮我做一个带 Web 界面的客户管理桌面程序，打包成 EXE。」

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

---

作为 dsh 插件使用

本技能已发布为 DeepSeek Harness (dsh) 的 Cordis Bundle 插件 dsh-fasthtml-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-fasthtml-desktop

验证配置层并启动：

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

从 GitHub Release 下载安装

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

# 下载源码归档（zip 或 tar.gz），以下载最新 Release 为例
curl -L -o fasthtml-desktop.zip \
  https://github.com/kuailexiaozixin/fasthtml-desktop/archive/refs/heads/main.zip
unzip fasthtml-desktop.zip      # 得到 fasthtml-desktop-main/（技能位于 skills/fasthtml-desktop/）

解压后有两种安装方式：

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

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

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

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

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

dsh plugin --profile web add /绝对路径/fasthtml-desktop-main/skills/fasthtml-desktop

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

使用

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

「用 fasthtml-desktop 技能，帮我做一个带 Web 界面的客户管理桌面程序，打包成 EXE。」

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

移除

dsh plugin --profile web remove dsh-fasthtml-desktop

---

目录结构

仓库遵循 gh skill 标准发布树（技能本体自包含于 skills/fasthtml-desktop/）：

fasthtml-desktop/                # 仓库根
├── skills/
│   └── fasthtml-desktop/        # 技能根（gh skill 发现路径 skills/*/SKILL.md）
│       ├── SKILL.md             # 技能主入口（工作流①→⑨ + 铁律内联）
│       ├── CHANGELOG.md         # 版本变更记录
│       ├── LICENSE              # MIT 许可证
│       ├── README.md            # 本文件
│       ├── references/          # 深度参考（按工作流①→⑨编号）
│       │   ├── 02-architecture/ # ② 架构设计（18 章 + 模块设计）
│       │   ├── 05-coding/       # ⑤ 编码（含 fasthtml-refs/ 官方上下文、pywebview-examples/）
│       │   ├── 07-quality-gate/ # ⑦ 质量门禁（Check/Test/Debug 三层）
│       │   ├── 08-packaging/    # ⑧ 打包（深度指南 + 跨平台 + 7 子专题）
│       │   └── ...
│       ├── examples/            # 20+ 参考实现（优先参考）
│       │   ├── 03-FastCRM       # 客户关系管理
│       │   ├── 04-FastERP       # 企业资源计划
│       │   ├── 05-FastHRM       # 人事管理
│       │   ├── 06-FastInsights  # 数据洞察
│       │   ├── 09-FastSheets    # 电子表格
│       │   ├── 12-FastLegal     # 法律服务
│       │   └── ...              # 完整列表见 examples/README.md
│       ├── templates/           # 项目脚手架模板
│       ├── scripts/             # 构建、校验、门禁自动化脚本
│       ├── docs/                # 交付清单、术语表、排障
│       ├── package.json         # npm 包声明（dsh-fasthtml-desktop，Cordis Bundle）
│       ├── index.js             # 嵌入式 skill 提供方
│       └── cordis.patch.yml     # dsh bundle patch（注册插件）
├── .github/workflows/ci.yml     # gh skill publish --dry-run + 目录结构校验
├── .gitattributes               # 强制 .bat 以 CRLF 分发
└── README.md                    # 仓库级说明（本文件为技能内说明）

---

快速开始（给 Agent）

1. 读取入口：SKILL.md 定义完整工作流与铁律。
2. 写 FastHTML 代码前：必读 references/05-coding/fasthtml-refs/fasthtml-llms-ctx.txt（HARD-GATE），注意与 FastAPI 的语法差异。
3. 生成项目：用 templates/ 脚手架（bootstrap_project.sh / ensure_uv_env）初始化。
4. 开发迭代：FastHTML 路由 + HTMX 交互，参考 examples/ 中与业务最接近的项目。
5. 质量门禁：路由联动检查 + 引用检查 + 无头 UI 验证 + release_gate.py。
6. 打包：scripts/build_windows_exe 产出 EXE，跨平台用 build_cross_platform.py。

---

贡献

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

• 改动技能核心逻辑时，同步更新 SKILL.md、references/ 与 CHANGELOG.md
• 新增参考实现请放入 examples/，并登记到 examples/README.md
• 保持「权威文档 HARD-GATE + 质量门禁 + 跨平台构建」的铁律不被破坏

详见 contributing.md。

---

第三方内容与合规

examples/ 目录下的参考实现绝大多数克隆自 Predictive Labs（predictivelabsai 组织）的 Fast* 系列（代码版权归 Predictive Labs Ltd，多为 MIT），仅少数源自其他项目（02-TrafficData Apache、07-genui-weather、08-code-assistant）。完整来源、许可证与使用注意详见 THIRD_PARTY_NOTICES.md。

---

许可证

MIT © kuailexiaozixin

---

相关：同系列的 tkinter-desktop（原生 Tkinter 方案，技术栈互斥，可作对比）。