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/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 通常已内置在支持该标准的助手中（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）
curl -L -o fasthtml-desktop.zip \
  https://github.com/kuailexiaozixin/fasthtml-desktop/archive/refs/tags/v1.6.0.zip
unzip fasthtml-desktop.zip      # 得到 fasthtml-desktop-1.6.0/（内含 SKILL.md）

解压后有两种安装方式：

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

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

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

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

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

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

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

目录结构

fasthtml-desktop/
├── SKILL.md              # 技能主入口（工作流 + 铁律）
├── CHANGELOG.md          # 版本变更记录
├── LICENSE               # MIT 许可证
├── README.md             # 本文件
├── references/           # 深度参考（架构、模块设计、打包、TDD、集成模式等）
│   └── fasthtml-refs/    # FastHTML 官方上下文转档（写码前必读）
├── 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（注册插件）
└── examples/README.md

快速开始（给 Agent）

1. 读取入口：SKILL.md 定义完整工作流与铁律。
2. 写 FastHTML 代码前：必读 references/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 方案，技术栈互斥，可作对比）。