自动化 on idiotfan

DSH Web 跨平台桌面启动器全教程：macOS 原生 .app + Windows 一键窗口

Tue, 01 Sep 2026 17:15:00 +0800

之前写过一版 DSH 的 macOS 启动器：一个 shell 脚本包装成的 .app，双击后自动拉起 dsh web 服务再开浏览器。能用，但打开的还是浏览器标签页，混在一堆网页里不够"应用"。

这次升级成原生应用方案，并且把整套方法整理成跨平台教程：

macOS：Swift + WKWebView 编译成原生 .app，独立窗口、Dock 图标、断线自动重连
Windows：Edge/Chrome --app 模式快捷方式（零依赖），或 WebView2 原生窗口（进阶）
图标：不再手绘，直接从 DSH 源码里提取官方鲸鱼 SVG 渲染，配深蓝渐变圆角背景

最终效果（图标）：

本文自包含：所有源码完整附上，照抄即可复现；也可以直接把本文链接发给任何 AI agent，让它照着做。

一、原理

DSH 的 Web 界面跑在 http://127.0.0.1:3080。所谓"桌面应用"，本质就是一个固定加载这个地址的独立窗口：

平台	方案	窗口技术
macOS	编译原生 `.app`	WKWebView
Windows（推荐）	快捷方式 + `--app=` 参数	Edge/Chrome 应用模式
Windows（进阶）	.NET WinForms	WebView2

三种方案都不需要打包网页资源，服务还是那个服务，只是入口变成了双击图标。

二、通用部分：制作图标

2.1 提取官方鲸鱼 SVG

DSH 前端的产物目录里自带 favicon.svg，就是官方鲸鱼 Logo。在本机 DSH 安装目录下找：

1
2
3
4
5
6


npm root -g
# 拼上相对路径：
#   /@deepseek-ai/dsh/node_modules/@deepseek-ai/dsh-web-frontend/dist/favicon.svg

mkdir -p dsh-app && cd dsh-app
cp "$(npm root -g)/@deepseek-ai/dsh/node_modules/@deepseek-ai/dsh-web-frontend/dist/favicon.svg" .

Windows 上 npm root -g 输出形如 C:\Users\<你>\AppData\Roaming\npm\node_modules，同样拼上后面的相对路径。找不到的话用 find "$(npm root -g)/@deepseek-ai" -name favicon.svg 定位。

2.2 图标生成脚本（双平台通用）

依赖：Python 3 + Pillow（pip install pillow）。保存为 make_icon.py：

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167


#!/usr/bin/env python3
"""DSH Web app icon: official DeepSeek Harness whale (from favicon.svg)
on a deep-blue gradient rounded square. 4x supersampled; self-checks at end."""
from PIL import Image, ImageDraw, ImageFilter
import os, re, subprocess, sys

OUT = os.path.dirname(os.path.abspath(__file__))
S = 4096   # supersample canvas
R = 1024   # final master


def lerp(a, b, t):
    return tuple(int(a[i] + (b[i] - a[i]) * t) for i in range(3))


# ---------- minimal SVG path parser (official favicon uses M/C only) ----------
def parse_svg_path(d):
    tokens = re.findall(r'([MmLlCcQqZzHhVvSsTtAa])|(-?\d*\.?\d+(?:e-?\d+)?)', d)
    tokens = [t[0] or float(t[1]) for t in tokens]
    i = 0

    def num():
        nonlocal i
        v = float(tokens[i]); i += 1
        return v

    def cubic(p0, p1, p2, p3, n=40):
        return [( (1-t)**3*p0[0]+3*(1-t)**2*t*p1[0]+3*(1-t)*t*t*p2[0]+t**3*p3[0],
                  (1-t)**3*p0[1]+3*(1-t)**2*t*p1[1]+3*(1-t)*t*t*p2[1]+t**3*p3[1] )
                for t in (k/n for k in range(1, n+1))]

    def quad(p0, p1, p2, n=30):
        return [( (1-t)**2*p0[0]+2*(1-t)*t*p1[0]+t*t*p2[0],
                  (1-t)**2*p0[1]+2*(1-t)*t*p1[1]+t*t*p2[1] )
                for t in (k/n for k in range(1, n+1))]

    subpaths, cur = [], []
    pos = start = (0, 0); last_c = None; last_letter = 'M'
    while i < len(tokens):
        if isinstance(tokens[i], str):
            c = tokens[i]; i += 1
            if c in 'Zz':
                if cur and cur[-1] != start: cur.append(start)
                if cur: subpaths.append(cur)
                cur = []; pos = start; last_c = None
                continue
        else:
            c = last_letter  # implicit repeat (M -> L)
        rel = c.islower(); C = c.upper()
        last_letter = 'L' if C == 'M' else C
        if C == 'M':
            x, y = num(), num()
            pos = (pos[0]+x, pos[1]+y) if rel else (x, y)
            if cur: subpaths.append(cur)
            cur = [pos]; start = pos; last_c = None
        elif C == 'L':
            x, y = num(), num()
            pos = (pos[0]+x, pos[1]+y) if rel else (x, y)
            cur.append(pos); last_c = None
        elif C == 'H':
            x = num(); pos = ((pos[0]+x) if rel else x, pos[1]); cur.append(pos); last_c = None
        elif C == 'V':
            y = num(); pos = (pos[0], (pos[1]+y) if rel else y); cur.append(pos); last_c = None
        elif C == 'C':
            x1, y1, x2, y2, x, y = num(), num(), num(), num(), num(), num()
            p1 = (pos[0]+x1, pos[1]+y1) if rel else (x1, y1)
            p2 = (pos[0]+x2, pos[1]+y2) if rel else (x2, y2)
            p3 = (pos[0]+x, pos[1]+y) if rel else (x, y)
            cur += cubic(pos, p1, p2, p3); pos = p3; last_c = p2
        elif C == 'S':
            x2, y2, x, y = num(), num(), num(), num()
            p1 = (2*pos[0]-last_c[0], 2*pos[1]-last_c[1]) if last_c else pos
            p2 = (pos[0]+x2, pos[1]+y2) if rel else (x2, y2)
            p3 = (pos[0]+x, pos[1]+y) if rel else (x, y)
            cur += cubic(pos, p1, p2, p3); pos = p3; last_c = p2
        elif C == 'Q':
            x1, y1, x, y = num(), num(), num(), num()
            p1 = (pos[0]+x1, pos[1]+y1) if rel else (x1, y1)
            p2 = (pos[0]+x, pos[1]+y) if rel else (x, y)
            cur += quad(pos, p1, p2); pos = p2; last_c = None
        else:
            raise ValueError("unhandled command " + c)
    if cur: subpaths.append(cur)
    return subpaths


def build_official_whale(canvas, span=0.62):
    """Render the official DSH whale (favicon.svg) white, centered, spanning `span` of canvas."""
    src = open(os.path.join(OUT, "favicon.svg")).read()
    d = re.search(r'\bd="([^"]+)"', src).group(1)
    subpaths = parse_svg_path(d)
    xs = [p[0] for sp in subpaths for p in sp]
    ys = [p[1] for sp in subpaths for p in sp]
    bw, bh = max(xs) - min(xs), max(ys) - min(ys)
    scale = canvas * span / max(bw, bh)
    ox = canvas / 2 - (min(xs) + max(xs)) / 2 * scale
    oy = canvas / 2 - (min(ys) + max(ys)) / 2 * scale - canvas * 0.015

    mask = Image.new("L", (canvas, canvas), 0)
    dr = ImageDraw.Draw(mask)
    for sp in subpaths:
        dr.polygon([(p[0]*scale + ox, p[1]*scale + oy) for p in sp], fill=255)

    # white -> ice-blue vertical gradient inside the whale mask
    g1 = Image.new("RGBA", (1, canvas))
    for y in range(canvas):
        g1.putpixel((0, y), lerp((255, 255, 255), (190, 224, 255), y / canvas) + (255,))
    grad = g1.resize((canvas, canvas))
    return Image.composite(grad, Image.new("RGBA", (canvas, canvas), (0, 0, 0, 0)), mask)


def main():
    # background: diagonal navy -> blue -> teal
    bg = Image.new("RGBA", (R, R))
    px = bg.load()
    c1, c2, c3 = (7, 14, 40), (18, 56, 124), (9, 118, 168)
    for y in range(R):
        for x in range(R):
            t = (x + y) / (2 * R)
            c = lerp(c1, c2, t * 2) if t < 0.5 else lerp(c2, c3, (t - 0.5) * 2)
            px[x, y] = c + (255,)

    # rounded-rect mask
    mask = Image.new("L", (R, R), 0)
    ImageDraw.Draw(mask).rounded_rectangle([0, 0, R - 1, R - 1], radius=int(R * 0.2237), fill=255)
    bg.putalpha(mask)

    # whale: 4x supersample -> glow -> composite
    whale_small = build_official_whale(S).resize((R, R), Image.LANCZOS)

    glow = Image.new("RGBA", (S, S), (0, 0, 0, 0))
    ImageDraw.Draw(glow).ellipse([S*0.15, S*0.20, S*0.85, S*0.85], fill=(70, 190, 255, 150))
    glow = glow.filter(ImageFilter.GaussianBlur(S * 0.09)).resize((R, R), Image.LANCZOS)
    glow = Image.composite(glow, Image.new("RGBA", (R, R), (0, 0, 0, 0)), whale_small.split()[3])
    bg = Image.alpha_composite(bg, glow)
    bg = Image.alpha_composite(bg, whale_small)

    bg.save(os.path.join(OUT, "icon_1024.png"))

    # ---- Windows .ico ----
    bg.save(os.path.join(OUT, "AppIcon.ico"),
            sizes=[(16, 16), (32, 32), (48, 48), (64, 64), (128, 128), (256, 256)])

    # ---- macOS .icns（仅 macOS 有 iconutil）----
    if sys.platform == "darwin":
        iconset = os.path.join(OUT, "AppIcon.iconset")
        os.makedirs(iconset, exist_ok=True)
        for name, size in {"icon_16x16.png": 16, "icon_16x16@2x.png": 32, "icon_32x32.png": 32,
                           "icon_32x32@2x.png": 64, "icon_128x128.png": 128, "icon_128x128@2x.png": 256,
                           "icon_256x256.png": 256, "icon_256x256@2x.png": 512, "icon_512x512.png": 512,
                           "icon_512x512@2x.png": 1024}.items():
            bg.resize((size, size), Image.LANCZOS).save(os.path.join(iconset, name))
        subprocess.run(["iconutil", "-c", "icns", iconset, "-o",
                        os.path.join(OUT, "AppIcon.icns")], check=True)

    # self-check
    px = bg.load()
    bright = [(x, y) for y in range(R) for x in range(R)
              if px[x, y][3] > 200 and px[x, y][0] > 200 and px[x, y][1] > 200]
    assert len(bright) > 30000, f"whale too small: {len(bright)} bright pixels"
    xs = [p[0] for p in bright]; ys = [p[1] for p in bright]
    print(f"bright pixels: {len(bright)}  whale bbox: x[{min(xs)}..{max(xs)}] y[{min(ys)}..{max(ys)}]")
    print("OK icon_1024.png + AppIcon.ico" + (" + AppIcon.icns" if sys.platform == "darwin" else ""))


if __name__ == "__main__":
    main()

运行：

1

python3 make_icon.py        # Windows 用 python make_icon.py

产物：

文件	用途
`icon_1024.png`	1024px 预览图
`AppIcon.icns`	macOS 应用图标（仅 macOS 生成）
`AppIcon.ico`	Windows 快捷方式/程序图标（16~256 共 6 档尺寸）

脚本要点：内置了一个极简 SVG path 解析器（支持 M/L/C/S/Q/H/V/Z，官方 favicon 只用到了 M/C/Z），把鲸鱼路径 4 倍超采样渲染成白色渐变鲸鱼，再叠光晕合成到深蓝渐变圆角底板上；末尾自动做像素自检，鲸鱼没画出来会直接 assert 报错。脚本按平台自动决定生成 .icns 还是只出 .ico。

三、macOS：编译原生 `.app`

3.1 依赖

1
2


xcode-select --install   # 提供 swiftc / iconutil，装过可跳过
python3 -m pip install pillow

3.2 应用源码 `main.swift`

一个完整的原生应用，不到 200 行：

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177


import Cocoa
import WebKit

final class AppDelegate: NSObject, NSApplicationDelegate, WKNavigationDelegate {
    private var window: NSWindow!
    private var webView: WKWebView!
    private var errorView: NSView?
    private var retryTimer: Timer?
    private let homeURL = URL(string: "http://127.0.0.1:3080")!

    func applicationDidFinishLaunching(_ notification: Notification) {
        buildMenu()

        let rect = NSRect(x: 0, y: 0, width: 1280, height: 840)
        window = NSWindow(contentRect: rect,
                          styleMask: [.titled, .closable, .miniaturizable, .resizable],
                          backing: .buffered, defer: false)
        window.title = "DSH Web"
        window.minSize = NSSize(width: 800, height: 560)
        window.setFrameAutosaveName("DSHWebWindow")
        window.center()

        let config = WKWebViewConfiguration()
        webView = WKWebView(frame: rect, configuration: config)
        webView.navigationDelegate = self
        webView.allowsBackForwardNavigationGestures = true
        window.contentView = webView

        window.makeKeyAndOrderFront(nil)
        NSApp.activate(ignoringOtherApps: true)
        loadHome()
    }

    func applicationShouldTerminateAfterLastWindowClosed(_ sender: NSApplication) -> Bool { true }

    // MARK: - Loading

    private func loadHome() {
        hideError()
        var req = URLRequest(url: homeURL)
        req.cachePolicy = .reloadIgnoringLocalCacheData
        req.timeoutInterval = 8
        webView.load(req)
    }

    // MARK: - WKNavigationDelegate

    func webView(_ webView: WKWebView, didFinish navigation: WKNavigation!) {
        stopAutoRetry()
        hideError()
    }

    func webView(_ webView: WKWebView, didFail navigation: WKNavigation!, withError error: Error) {
        showError()
    }

    func webView(_ webView: WKWebView, didFailProvisionalNavigation navigation: WKNavigation!, withError error: Error) {
        showError()
    }

    // MARK: - Error screen (auto-retry while server is not up yet)

    private func showError() {
        if errorView == nil { buildErrorView() }
        errorView?.isHidden = false
        startAutoRetry()
    }

    private func hideError() {
        errorView?.isHidden = true
    }

    private func startAutoRetry() {
        guard retryTimer == nil else { return }
        retryTimer = Timer.scheduledTimer(withTimeInterval: 4, repeats: true) { [weak self] _ in
            self?.loadHome()
        }
    }

    private func stopAutoRetry() {
        retryTimer?.invalidate()
        retryTimer = nil
    }

    private func buildErrorView() {
        guard let content = window.contentView else { return }
        let v = NSView(frame: content.bounds)
        v.autoresizingMask = [.width, .height]
        v.wantsLayer = true
        v.layer?.backgroundColor = NSColor(calibratedRed: 0.05, green: 0.08, blue: 0.17, alpha: 1).cgColor

        let title = NSTextField(labelWithString: "无法连接到 DSH Web")
        title.font = .systemFont(ofSize: 22, weight: .semibold)
        title.textColor = .white

        let sub = NSTextField(labelWithString: "请先启动 dsh 服务（127.0.0.1:3080），正在自动重试，也可以点击下方按钮。")
        sub.font = .systemFont(ofSize: 13)
        sub.textColor = NSColor(white: 0.72, alpha: 1)

        let btn = NSButton(title: "立即重试", target: self, action: #selector(retryTapped))
        btn.bezelStyle = .rounded
        btn.controlSize = .large
        btn.keyEquivalent = "\r"

        let stack = NSStackView(views: [title, sub, btn])
        stack.orientation = .vertical
        stack.alignment = .centerX
        stack.spacing = 14
        stack.translatesAutoresizingMaskIntoConstraints = false
        v.addSubview(stack)
        NSLayoutConstraint.activate([
            stack.centerXAnchor.constraint(equalTo: v.centerXAnchor),
            stack.centerYAnchor.constraint(equalTo: v.centerYAnchor),
        ])
        content.addSubview(v, positioned: .above, relativeTo: webView)
        errorView = v
    }

    @objc private func retryTapped() { loadHome() }

    @objc private func reloadHome(_ sender: Any?) { loadHome() }
    @objc private func goBack(_ sender: Any?) { webView.goBack() }
    @objc private func goForward(_ sender: Any?) { webView.goForward() }

    // MARK: - Menus (Cmd+Q / Cmd+R / Cmd+W / copy-paste)

    private func buildMenu() {
        let mainMenu = NSMenu()

        let appItem = NSMenuItem()
        mainMenu.addItem(appItem)
        let appMenu = NSMenu()
        appMenu.addItem(withTitle: "关于 DSH Web", action: #selector(NSApplication.orderFrontStandardAboutPanel(_:)), keyEquivalent: "")
        appMenu.addItem(.separator())
        appMenu.addItem(withTitle: "隐藏 DSH Web", action: #selector(NSApplication.hide(_:)), keyEquivalent: "h")
        appMenu.addItem(.separator())
        appMenu.addItem(withTitle: "退出 DSH Web", action: #selector(NSApplication.terminate(_:)), keyEquivalent: "q")
        appItem.submenu = appMenu

        let navItem = NSMenuItem()
        mainMenu.addItem(navItem)
        let navMenu = NSMenu(title: "导航")
        navMenu.addItem(withTitle: "重新加载", action: #selector(reloadHome(_:)), keyEquivalent: "r")
        navMenu.addItem(withTitle: "后退", action: #selector(goBack(_:)), keyEquivalent: "[")
        navMenu.addItem(withTitle: "前进", action: #selector(goForward(_:)), keyEquivalent: "]")
        navMenu.addItem(.separator())
        navMenu.addItem(withTitle: "关闭窗口", action: #selector(NSWindow.performClose(_:)), keyEquivalent: "w")
        navItem.submenu = navMenu

        let editItem = NSMenuItem()
        mainMenu.addItem(editItem)
        let editMenu = NSMenu(title: "编辑")
        editMenu.addItem(withTitle: "撤销", action: Selector(("undo:")), keyEquivalent: "z")
        editMenu.addItem(withTitle: "重做", action: Selector(("redo:")), keyEquivalent: "Z")
        editMenu.addItem(.separator())
        editMenu.addItem(withTitle: "剪切", action: #selector(NSText.cut(_:)), keyEquivalent: "x")
        editMenu.addItem(withTitle: "拷贝", action: #selector(NSText.copy(_:)), keyEquivalent: "c")
        editMenu.addItem(withTitle: "粘贴", action: #selector(NSText.paste(_:)), keyEquivalent: "v")
        editMenu.addItem(withTitle: "全选", action: #selector(NSText.selectAll(_:)), keyEquivalent: "a")
        editItem.submenu = editMenu

        let winItem = NSMenuItem()
        mainMenu.addItem(winItem)
        let winMenu = NSMenu(title: "窗口")
        winMenu.addItem(withTitle: "最小化", action: #selector(NSWindow.performMiniaturize(_:)), keyEquivalent: "m")
        winMenu.addItem(withTitle: "缩放", action: #selector(NSWindow.performZoom(_:)), keyEquivalent: "")
        winItem.submenu = winMenu

        NSApp.mainMenu = mainMenu
    }
}

let app = NSApplication.shared
let delegate = AppDelegate()
app.delegate = delegate
app.setActivationPolicy(.regular)
app.run()

功能：独立原生窗口（记住大小位置）、dsh 服务没起时显示提示页并每 4 秒自动重试（先开应用再启服务也行）、完整菜单快捷键（Cmd+R 重载、Cmd+[/] 前进后退、Cmd+W 关窗、Cmd+Q 退出、复制粘贴）。

3.3 `Info.plist`

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37




 version="1.0">

	CFBundleName
	DSH Web
	CFBundleDisplayName
	DSH Web
	CFBundleIdentifier
	com.deepseek.dsh-web
	CFBundleExecutable
	DSHWeb
	CFBundlePackageType
	APPL
	CFBundleIconFile
	AppIcon
	CFBundleIconName
	AppIcon
	CFBundleShortVersionString
	1.0
	CFBundleVersion
	1
	LSMinimumSystemVersion
	12.0
	LSApplicationCategoryType
	public.app-category.developer-tools
	LSMultipleInstancesProhibited
	
	NSHighResolutionCapable
	
	NSAppTransportSecurity
	
		NSAllowsLocalNetworking
		
	

⚠️ NSAllowsLocalNetworking 必须有，否则 ATS 可能拦截 http://127.0.0.1 的明文请求，窗口一直空白。

3.4 一键构建 `build.sh`

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


#!/bin/bash
# Build "DSH Web.app": native WKWebView wrapper for http://127.0.0.1:3080
set -euo pipefail
cd "$(dirname "$0")"

APP="DSH Web.app"
echo "==> 生成图标"
python3 make_icon.py

echo "==> 编译 Swift"
swiftc -O -o DSHWeb main.swift -framework Cocoa -framework WebKit

echo "==> 组装 bundle"
rm -rf "$APP"
mkdir -p "$APP/Contents/MacOS" "$APP/Contents/Resources"
cp DSHWeb "$APP/Contents/MacOS/DSHWeb"
cp Info.plist "$APP/Contents/Info.plist"
cp AppIcon.icns "$APP/Contents/Resources/AppIcon.icns"

echo "==> ad-hoc 签名"
codesign --force --deep -s - "$APP"

echo "==> 完成: $(pwd)/$APP"

3.5 构建、安装、验证

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


chmod +x build.sh
./build.sh

# 安装到用户应用目录（Launchpad / 聚焦搜索可见）
cp -R "DSH Web.app" ~/Applications/

# 验证
curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:3080/   # 期望 200
open ~/Applications/"DSH Web.app"
pgrep -fl DSHWeb                                                  # 有进程即成功

四、Windows：两种方案

方案 A（推荐）：Edge/Chrome `--app` 快捷方式

零编译依赖，效果接近原生应用：独立窗口、无地址栏、独立任务栏图标。

按第二节生成 AppIcon.ico（Windows 上直接 python make_icon.py）。
保存下面脚本为 make_shortcut.ps1，与 AppIcon.ico 放同一目录：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


# make_shortcut.ps1 — 创建 DSH Web 桌面快捷方式（独立应用窗口）
$edge86  = "C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe"
$edge64  = "C:\Program Files\Microsoft\Edge\Application\msedge.exe"
$chrome  = "C:\Program Files\Google\Chrome\Application\chrome.exe"
$browser = if (Test-Path $edge86) { $edge86 }
           elseif (Test-Path $edge64) { $edge64 }
           elseif (Test-Path $chrome) { $chrome }
           else { throw "未找到 Edge 或 Chrome" }

$ws = New-Object -ComObject WScript.Shell

# 桌面快捷方式
$sc = $ws.CreateShortcut("$env:USERPROFILE\Desktop\DSH Web.lnk")
$sc.TargetPath       = $browser
$sc.Arguments        = "--app=http://127.0.0.1:3080"
$sc.IconLocation     = "$PSScriptRoot\AppIcon.ico"
$sc.WorkingDirectory = $PSScriptRoot
$sc.Description      = "DeepSeek Harness Web"
$sc.Save()

# 开始菜单（可选，便于搜索）
$start = "$env:APPDATA\Microsoft\Windows\Start Menu\Programs"
Copy-Item "$env:USERPROFILE\Desktop\DSH Web.lnk" "$start\DSH Web.lnk" -Force

Write-Host "OK: 已创建快捷方式（浏览器: $browser）"

运行（如遇执行策略限制）：

1

powershell -ExecutionPolicy Bypass -File make_shortcut.ps1

双击桌面的 DSH Web 即可，可右键快捷方式 →「固定到任务栏」。

方案 B（进阶）：WebView2 原生窗口

需要 .NET SDK（Win11 自带 WebView2 运行时）：

1
2
3
4


dotnet new winforms -n DshWeb
cd DshWeb
dotnet add package Microsoft.Web.WebView2
copy ..\AppIcon.ico .

把 Program.cs 改成：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


using Microsoft.Web.WebView2.WinForms;
using System.Windows.Forms;

var form = new Form
{
    Text = "DSH Web",
    Width = 1280,
    Height = 840,
    StartPosition = FormStartPosition.CenterScreen,
    Icon = new System.Drawing.Icon("AppIcon.ico")
};
var web = new WebView2 { Dock = DockStyle.Fill };
form.Controls.Add(web);
form.Shown += async (s, e) =>
{
    await web.EnsureCoreWebView2Async();
    web.CoreWebView2.Navigate("http://127.0.0.1:3080");
};
Application.Run(form);

发布为单文件：

1
2


dotnet publish -c Release -r win-x64 --self-contained false -p:PublishSingleFile=true
# 产物：bin\Release\net8.0-windows\win-x64\publish\DshWeb.exe

五、验证清单

检查项	方法	期望
dsh 服务在线	访问 `http://127.0.0.1:3080/`	HTTP 200
图标正常	看 Dock / 桌面快捷方式	深蓝渐变底 + 白色鲸鱼
应用启动	双击图标	独立窗口打开 DSH Web
服务未启动	先开应用再启服务	提示页自动重试并成功加载

六、自定义

换端口/地址：macOS 改 main.swift 里的 homeURL；Windows 改快捷方式 --app= 参数，改完分别重跑 build.sh / make_shortcut.ps1
图标鲸鱼大小：make_icon.py 里 build_official_whale(S, span=0.62) 的 span（0~1）
背景配色：make_icon.py 里 c1, c2, c3 三个 RGB
窗口默认尺寸：main.swift 里 NSRect(... width: 1280, height: 840)

七、常见问题

macOS 提示"无法打开，因为无法验证开发者"：本机编译 + ad-hoc 签名一般不会有；如果是从别的机器拷贝过来的，先 xattr -dr com.apple.quarantine "DSH Web.app"。
窗口空白/打不开：确认 dsh web 已在运行且端口是 3080；macOS 版会自动重试，Windows 快捷方式需手动 Ctrl+R 刷新。
favicon.svg 找不到：DSH 版本目录结构可能有差异，用 find "$(npm root -g)/@deepseek-ai" -name favicon.svg 定位。

相比上一版 shell 脚本启动器，这版是真正的独立应用窗口，快捷键、菜单栏、Dock 图标一应俱全；图标也从手搓 SVG 渲染换成了直接复用官方鲸鱼——教训是：先翻翻项目自带的资源，比自己重画省事得多。

给 DSH 手搓一个 macOS 一键启动器：.app 结构、图标与认证的两次翻车记

Thu, 27 Aug 2026 16:10:00 +0800

日常用 DeepSeek Harness（DSH）的 Web 界面和 AI 结对干活，每次都要先开终端敲 dsh web、再开浏览器输地址，步骤琐碎。于是让 AI 直接给我做了一个 macOS 应用：双击图标就打开 DSH 页面；如果 dsh web 没在跑，它会自动在后台把服务拉起来，就绪后再弹开浏览器。

整个过程一次会话搞定，中间翻了两次挺有意思的车——一次在图标，一次在认证——记录如下。

一、应用本体：手写 .app 结构

macOS 的应用本质上就是一个遵守约定目录结构的文件夹，~/Applications/DSH.app：

DSH.app/
└── Contents/
    ├── Info.plist            # 应用元信息（指定可执行文件、图标、Bundle ID）
    ├── MacOS/
    │   └── dsh-launcher      # 启动脚本（chmod +x）
    └── Resources/
        └── icon.icns         # 图标

不需要 Xcode，不需要 Automator，三个文件就是全部。

二、启动脚本：四个关键设计

核心逻辑：探测 3080 端口，通了就开网址；不通就拉起服务、等就绪、再开。但有四个容易踩的坑：

1. GUI 应用的 PATH 是残的

从 Finder/Dock 启动的应用不会继承 shell 环境，PATH 只有 /usr/bin:/bin:...。我的 node 在 nvm 里（~/.nvm/versions/node/v24.15.0/bin），脚本里必须显式补 PATH，否则双击永远找不到 dsh 命令——终端里测试一切正常，双击就失败，非常经典的迷惑现场。

2. 后台拉起用 nohup，加 `--no-open --port`

1

nohup "$DSH" web --no-open --port "$PORT" >>"$LOG" 2>&1 &

nohup + 重定向让服务进程脱离启动器的生命周期，脚本退出后服务照常运行。dsh web 默认会自己弹浏览器，但就绪时序和要打开的 URL 都由启动器统一控制更可控（原因见第 3 点），所以加 --no-open 收归一处；--port 显式传，别让「检测的端口」和「启动的端口」各说各话——这个不一致我在测试时真踩了一次：环境变量改了检测端口，启动的实例却奔着默认端口去抢，EADDRINUSE 秒退。

3. 认证机制：必须打开它「打印出来」的 URL（本篇最大翻车）

第一版上线后博主实测就翻车了：双击后页面报 “dsh web authentication required; reopen the URL printed by dsh web”。

读源码才搞明白，dsh web 有一套 browser-trust 认证机制：

每次 dsh web 启动会生成一个进程内一次性 launch token（randomBytes，只在内存里）；
它向 stdout 打印 dsh web: http://127.0.0.1:3080/?token=…，访问这个带 token 的 URL 会 303 重定向并种一个 30 天的签名 cookie（签名密钥持久化，跨重启有效），然后跳回干净的 /；
裸地址只有在浏览器已持有有效 cookie 时才能用。我 open 的是裸地址，而默认浏览器里恰恰没有有效 cookie → 401。

用 curl 三连验证了整条链路：

1
2
3


裸地址             → 401
/?token=…         → 303 + Set-Cookie
带 cookie 再访问    → 200

所以启动器的正确姿势是：等日志里出现那行 dsh web: ，打开它。这行还是比 nc 探端口更准的就绪信号——它打印出来就意味着 HTTP 服务已经可用。解析时有两个细节：

只认「本次启动之后」打印的、且端口匹配的行。日志是追加式的，上一任实例留下的旧 token 对新进程无效，直接全量 tail -1 会在冷启动竞速里抢到过期 token；
区分「谁拉起的服务」：pidfile 里的 PID 必须和当前端口的监听者一致，才走「取日志 token」路径；如果是用户在终端手动启动的实例，从外面拿不到它的进程 token，只能开裸地址降级，并弹通知告知「若提示认证失败请重启服务」。

4. 超时兜底

实测冷启动约 1 秒就绪；90 秒超时后弹出系统对话框，可一键打开日志（~/Library/Logs/dsh-web.log）。启动期间用 osascript 发系统通知告知进度，体验比干等着好。

三、图标翻车记

第一版：qlmanage 渲染 SVG，埋了两颗雷

DSH 的 Web 界面有个鲸鱼 favicon.svg，就地取材。macOS 没有自带 SVG 转 PNG 的正经工具，第一反应是用 qlmanage -t（Quick Look 缩略图）渲染。当时看着"出图了"就直接打包成 icns 用了，结果双击后 Dock 里还是默认图标。

排查分两层：

雷一：LaunchServices 图标缓存。 图标文件是在向系统注册（lsregister）之前就位的，系统一直用缓存里的默认图标。标准修法：

1
2
3


touch ~/Applications/DSH.app          # 更新时间戳，触发重读
lsregister -f ~/Applications/DSH.app  # 强制重新注册
killall Dock && killall Finder        # 重启显示层

雷二（更隐蔽）：图标图稿本身就是坏的。 缓存问题解决后，我用一个客观方法验证图标内容——写个 Swift 脚本调 NSWorkspace.icon(forFile:) 把系统实际显示的图标导出成 PNG，再用 PIL 做像素统计。结果傻眼了：按颜色包围盒分析，蓝色背景只占了画面下半截（y=394~1022），上半截全被白色填充——qlmanage 对这个 SVG 的渲染完全是错的，只是 1024 缩略图肉眼没细看就信了。

第二版：无头 Chrome + PIL 重造

qlmanage 靠不住，换真正的浏览器引擎。机器上正好有 Chrome：

1
2
3
4


"Google Chrome" --headless --disable-gpu \
  --screenshot=render.png --window-size=1024,1024 \
  --default-background-color=00000000 \
  file:///tmp/render.html        # HTML 里内联 SVG，CSS 拉满 1024×1024

顺手做了两个设计调整：

鲸鱼缩放居中：favicon 的鲸鱼是满铺设计的，直接当 app 图标太挤。包一层缩到 60% 居中，留出蓝色呼吸边距。
圆角透明蒙版：Chrome 渲染的是方图，用 PIL 画一个 22.5% 半径的 rounded_rectangle 作为 alpha 通道，四角变透明，贴合 macOS 图标风格。最终：鲸鱼白色像素占 12.7%、蓝底 82.9%，比例舒服。

然后走标准流程：sips 缩出 16~1024 全套尺寸 → iconutil -c icns 打包 → 替换进 .app → touch + lsregister + killall 三连。

验证方法论：对照组思维

最后怎么确认"系统里看到的图标真的对了"？光看自己的渲染不算数。用同一个 Swift 提取脚本，把 Safari 的图标也导出来做对照：

指标	DSH	Safari（对照）
不透明像素占比	60.7%	63.3%
内容包围盒	(69,78,955,963)	(25,78,955,1001)

两者结构几乎一致——NSWorkspace 返回的图标自带系统级边距，我们的图标渲染特征和一个正经苹果应用完全对齐。中心取样是鲸鱼白、边缘取样是 DeepSeek 蓝、四角透明，收工。

五、成果与备忘

一键启动：拖进 Dock 或 ⌘空格搜 “DSH”，点一下进页面；服务没在跑时自动拉起，全程约 1 秒。
日志：~/Library/Logs/dsh-web.log，PID 在 dsh-web.pid，想停服务 kill $(cat ...) 即可。
认证的边界：应用自己拉起的实例，token 就在日志里，随时能给出认证 URL；但终端里手动启动的实例，token 只在它的 stdout 上，外部拿不到——这种情况下双击应用走裸地址降级，浏览器有有效 cookie（30 天内登录过）就无事，没有就请重启服务。
一个已知维护点：脚本里写死了 nvm 的 node 版本路径（v24.15.0），以后 node 升级大版本要改 NODE_BIN 一行。这也算是 nvm 类版本管理器和"脱离 shell 运行的 GUI 应用"之间固有的摩擦了。

小结

这篇里真正值得带走的不是某个命令，而是三个调试直觉：

“出图了”≠“图对了”。qlmanage 的缩略图管道对 SVG 的支持是有残缺的，肉眼扫一眼缩略图很难发现布局错位；用包围盒/像素统计做客观验证，一次就现形。
验证拿对照组。怀疑"系统显示的图标不对劲"时，把 Safari 这种原生应用用同一条管道过一遍——如果它也"不对劲"，那不对劲的就是你的测量管道，而不是被测对象。
报错文案里藏着答案。“reopen the URL printed by dsh web” 不是一句客套的报错，它就是解法本身：认证模型是"一次性 launch token 换 30 天签名 cookie"，而 token 只随进程打印在 stdout 上。第一版我把它当成了可有可无的启动横幅，直接被现实教育了——遇到带具体指令的报错，先照做，再深究。

本文由 Kimi K3（模型 ID：kimi-k3，月之暗面出品）在 DeepSeek Harness 会话中全程实操（应用创建、图标调试与重造、认证翻车修复与验证）并整理撰写，我负责提出需求、实测反馈、确认效果与审核。

给精酿连锁店做自动化薪酬引擎：从手写考勤、多维营收聚合到 HTML 工资单

Sat, 22 Aug 2026 15:00:00 +0800

在中小餐饮连锁店，每个月最令人头疼的除了盘点，就是算工资。

在大梦（可能实验室），两家门店涵盖了侍酒师、调酒师、咖啡师、主厨、出品厨师和兼任店长等多种角色。看似人不多，背后的算薪逻辑却极其复杂：

考勤源散落各处：有人在群里发手写考勤表照片，有人交 .xlsx，店长交 .xls 评估表，西湖夜班员工在腾讯文档里打卡。
提成与多维营收挂钩：薪酬不仅看基本工资，还挂钩部门业绩（精酿/调酒/咖啡/厨房）、班次业绩（白班/中班/晚班），甚至需要按部门 × 班次矩阵进行交叉剥离。
新 SKU 归口漂移：每个月两家店都会上新酒水或新菜品，如果菜品库没有及时维护，POS 导出的几百条订单就会分错部门。
输出要求高：算完不仅要在腾讯文档 43 列大表里逐行填平并标注店色，还要给每位员工生成带有公章、大写金额、社保代扣明细的精美工资单。

这篇文章记录我如何通过一套组合拳（Claude Fable 5 驱动的 Python 管道 + 腾讯文档 API + 响应式 HTML 工资单 + Rails 8 HR 系统集成），将原本需要耗费一整天的结薪工作缩减为 10 分钟自动化流程。

一、考勤与数据清洗：手写照片与多格式兼容

结薪的第一步是收集出勤、法定假日、加班与请假数据。

面对不同来源的考勤资料，我们建立了一条标准化的数据摄取流水线：

手写纸质排班表：通过多模态 Vision 模型直接识别出勤天数与请假备注（休、年假、调休）。
员工个人提交的 xlsx/xls：使用 openpyxl 和 xlrd 脚本批量读取出勤字段。
腾讯文档夜班表：调用腾讯文档 API 自动拉取最新的夜班排班记录。

考勤规则的程序化

在计算出勤时，有几条必须严格执行的业务口径：

法定节假日：按国家法定假日天数计算双倍津贴（基本工资 / 计薪基准 × 天数 × 2）。
加班是「存」还是「换钱」：员工备注若为「存」，则计入调休池，不折现发放；若为「换钱」，则按小时工资折算为加班费。
月计薪基准的口径区分：国家劳动法标准的月计薪天数是 21.75 天，而门店按「月休 4 天」的排班体系内部约定了自己的计薪基准。两者绝不可混用——这是薪酬计算里最容易犯的低级错误之一。

二、破解营收交叉难题：伪菜品库与部门×班次矩阵

很多餐饮店算提成算不准，根源在于POS 订单数据无法自动归口到部门和班次。

1. 「伪菜品库」反向生成法（100% 覆盖新 SKU）

早先我们维护了一份静态的「菜品库.xlsx」，但每月一到结薪，发现上月新上的十几款精酿或特调都在库外，脚本只能靠关键词模糊匹配，导致大量调酒被误归入精酿。

为了彻底根治这个问题，我们从 6 月起设计了**「伪菜品库生成器」**（make_menu_lib.py）：

直接读取美团/收钱吧 POS 导出的当月「菜品销售明细」（包含 POS 真实的「菜品大类」和「菜品小类」）。
脚本根据 POS 大类自动映射四部门，反向为两家门店各生成一份当月专用的全覆盖菜品库（数百个在售 SKU 全部自动归口）。
实测除扑克牌、雨伞等 2 笔杂物外，全部 SKU 100% 自动归口，彻底告别了人工维护。

2. 部门 × 班次交叉聚合算法

有了准确的菜品归属后，流水线运行 build_analysis.py 进行多维交叉切片：

部门业绩：从全渠道订单中提取含团购套餐的实际到账金额。
班次业绩：按结账时间（17:00 前为白班，17:00 后为晚班，特定时段为中班）切分。
特殊规则硬编码：例如滨江后厨团队（主厨与出品厨师）只考核整体后厨部门业绩，班次业绩置 0；前厅运营无特定部门归属，部门业绩置 0。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


# build_analysis 核心交叉切片逻辑示意
def compute_cross_matrix(orders_df, menu_lib):
    # 结合伪菜品库匹配部门
    merged = orders_df.merge(menu_lib, on='sku_id', how='left')
    # 结合结账时间戳划分班次
    merged['shift'] = merged['pay_time'].apply(classify_shift)
    
    # 交叉透视表：店 x 部门 x 班次
    cross_pivot = merged.pivot_table(
        index=['store', 'department'],
        columns='shift',
        values='actual_amount',
        aggfunc='sum',
        fill_value=0
    )
    return calibrate_totals(cross_pivot)

最终脚本自动输出包含 13 个分析页签的月度 Excel，并将部门起伏 MoM 根因下钻到具体 SKU（例如：精酿本月下滑主要由于哪几款酒头缺货）。

三、腾讯文档 V2 自动回写与店色渲染

大梦团队日常使用腾讯文档「员工档案 V2」作为薪酬管理中枢。整个表结构多达 43 列。

算薪脚本在核算完成后，会调用腾讯文档开放接口完成自动化回填：

行号探测与防偏移：自动读取表格末行，锁定当月全员的起始写入行（与上月行段空一行隔开），写完后立即回读校验。
写入动态计算字段：出勤天数、法假天数、部门业绩、班次业绩、基本工资、加班费、KPI 倍数、管理倍数、全勤行为规范奖、出品提成、社保个人代扣（在册员工按月代扣）、最终私账剩余应发。
自动化店色美化：
- 西湖店：全行设置浅绿底色（#FFE2EFDA）
- 滨江店：全行设置浅蓝底色（#FFDDEBF7）

四、双轨工资单：从 HTML 模板到 Rails 8 系统集成

算完薪后，如何将工资条体面、私密、优雅地分发给每位员工？

我们采取了「双轨制」交付方案：

1. 独立 HTML/JS 工资单生成器

在本地提供一个自包含的单页应用：

复古票据设计：两店分色边框、水印防伪印章、应发金额自动转换为中文大写（如「肆仟捌佰伍拾元整」）。
智能字段收起：没有提成的员工自动隐藏提成明细行；加班小时选择「存」的员工自动将加班费显示为 0 并附带文字备注。
一键导出 PNG：内置 html2canvas 引擎，右上角提供「EXPORT ALL」批量打包，单卡片下方支持单张保存。

2. 水龙头 HR 系统（Rails 8 + SQLite + Tailwind）

为了让店长和管理层具备更系统的历史查询与入职管理能力，我们将这套工资单生成逻辑无损移植进了内网 HR 系统 shuilongtou：

无损组件复用：将 HTML 模板的 CSS 与 JS 渲染核心原样封装为 Rails View Component。
服务端数据注入：SalarySlipBuilder 服务从 SQLite 读取当月评定记录，构造成标准 JSON 挂载在前端 window.SALARY_DATA 上。
批量与单人导出：在后台 /salary-slips 页面，店长可以按月份一键预览全员并导出高清图片分发微信。

结语

在服务实体餐饮的过程中，我们往往容易走向两个极端：要么沉迷于引入庞大昂贵的全套 SaaS 软件，结果员工根本不会用；要么退回原始的手工复制粘贴，每个月重复踩坑。

这套以 Python 脚本打通数据流、腾讯文档作为协作底座、轻量 HTML/Rails 提供交互展示的架构，恰好找到了那个平衡点：低成本、极度灵活，并且能在业务规则演进时随手调整。

当技术真正落进日常的柴米油盐与账目明细里，解决真实世界的琐碎麻烦，那种踏实感才是最迷人的。

🛠️ 项目环境与模型署名

主导逻辑与代码构建：Anthropic Claude Fable 5（桌面端默认模型）
多模态考勤识别：Claude Fable 5 视觉能力（手写纸质排班表与多源照片读取）
客户端与执行环境：Claude Desktop 桌面端（定制 dameng-salary Skill + tencent-docs MCP）
系统技术栈：Python 3 (pandas, openpyxl, xlrd) + 腾讯文档 OpenAPI + Rails 8 (shuilongtou 员工管理系统) + HTML/CSS 矢量打印模板