> 我有个命令行工具，平时只能在电脑上敲命令。想让它变成手机也能点的网页，用 WorkBuddy 干了一个下午就搞定了——一个输入框、一个按钮，就这么简单。

> 本文属于 **WorkBuddy 实战笔记**系列。

## 起因

我在本地维护一个自建的媒体库服务，配套有一个命令行工具，能检索、能下载。用起来有个问题：**每次都要开命令行敲参数。**

```
tool.bat --id 26610712:def1ec
```

对我来说还行，但对家里其他人就不友好了——没人愿意记参数。而且更麻烦的是：**手机上用不了。**

于是想把命令行工具包成一个网页：**输关键词 → 点搜索 → 点下载**，电脑手机都能用。

## 技术选型：越轻越好

考虑过几个方案：

| 方案 | 优点 | 缺点 |
|---|---|---|
| Electron 桌面应用 | 体验好 | 体积大，手机没法用 |
| 单独写 iOS/安卓 App | 原生体验 | 要两台设备分别开发，成本高 |
| **本地网页 + PWA** | **一套代码三端通用** | 需要本机常开 |

**选了第三个。** 理由很实在：

- **一套代码，三个平台**：Windows 浏览器直接开、iOS Safari 和安卓 Chrome 都能「添加到主屏幕」
- **零安装成本**：不用上架、不用签名、不用审核
- **后端复用现成工具**：不用重写逻辑，包一层就行

## 后端：包一层 HTTP 服务

核心思路是**把命令行的能力映射成 HTTP 接口**。

用 Python 标准库写（不装任何第三方依赖）：

```python
import http.server, subprocess, json

TOOL = r"C:\path\to\tool.exe"

def run_tool(args, timeout=180):
    """执行命令行工具，返回 (成功?, 标准输出, 标准错误)"""
    r = subprocess.run([TOOL] + args, capture_output=True, timeout=timeout)
    out = r.stdout.decode("utf-8", errors="replace").strip()
    err = r.stderr.decode("utf-8", errors="replace").strip()
    return r.returncode == 0, out, err
```

**接口设计**：

| 接口 | 方法 | 作用 |
|---|---|---|
| `/api/search?q=关键词` | GET | 搜索 |
| `/api/download` | POST | 发起下载 |
| `/api/task/<id>` | GET | 查下载进度 |
| `/api/quota` | GET | 查配额 |

## 关键点一：优先用工具的 JSON 输出

**这是省事最多的一步。**

我一开始打算解析命令行工具输出的**表格文本**，写了一半发现很痛苦——要处理对齐、截断、中文宽度。

后来翻文档发现它支持 `--json`：

```bash
tool.exe search "关键词" --json -n 30
```

输出直接就是结构化数据：

```json
{
  "items": [
    {
      "id": "26610712:def1ec",
      "name": "示例条目",
      "authors": ["某某"],
      "extension": "epub",
      "size": "2.48 MB",
      "cover": "https://.../cover.jpg"
    }
  ],
  "page": 1,
  "total_pages": 250
}
```

**代码量直接砍掉一大半。** 以前要写文本解析，现在只要 `json.loads()` 然后挑字段。

**顺带一个好处**：JSON 里带了**封面图片 URL**，前端可以直接显示。如果是解析表格文本，封面信息根本拿不到。

### 但 JSON 不一定干净

实际跑起来发现，有些命令的输出里**会混入进度提示或日志**，直接 `json.loads()` 会报错。

写个容错函数：

```python
def extract_json(text):
    """从可能混入日志的输出里抠出 JSON"""
    text = text.strip()
    try:
        return json.loads(text)          # 直接就是 JSON
    except Exception:
        pass
    i, j = text.find("{"), text.rfind("}")   # 找第一个 { 到最后一个 }
    if i >= 0 and j > i:
        try:
            return json.loads(text[i:j + 1])
        except Exception:
            pass
    return None
```

思路很简单：**先试直接解析，不行就把首尾大括号之间的内容截出来再试。**

## 关键点二：下载必须走后台，不能阻塞

**这是体验上最关键的一步。**

下载一个文件可能要几十秒。如果同步处理，会遇到两个问题：

1. 用户点了下载，页面转圈，**没法继续搜别的内容**
2. HTTP 请求超时（一般服务端 30-60 秒就掐了）

**改成异步任务模式**：

```python
TASKS = {}          # 任务表
TASKS_LOCK = threading.Lock()

def download_worker(tid, item_id, title):
    """后台下载线程"""
    def set_state(**kw):
        with TASKS_LOCK:
            TASKS[tid].update(kw)

    set_state(status="running", msg="正在连接…")
    ok, out, err = run_tool(["download", item_id, "-d", SAVE_DIR], timeout=900)

    if not ok:
        set_state(status="error", msg="下载失败")
        return
    set_state(status="done", msg="已入库")

    # 接口里只负责起线程
    tid = uuid.uuid4().hex[:12]
    TASKS[tid] = {"tid": tid, "status": "queued", "started": time.time()}
    threading.Thread(target=download_worker, args=(tid, item_id, title), daemon=True).start()
    return {"tid": tid}
```

前端拿到 `tid` 之后**每 2 秒轮询一次**：

```javascript
function poll(tid, btn) {
  const t = setInterval(async () => {
    const d = await fetch("/api/task/" + tid).then(r => r.json());
    if (d.status === "running") { btn.textContent = "下载中…"; }
    else if (d.status === "done") {
      clearInterval(t);
      btn.textContent = "✓ 已完成";
    } else if (d.status === "error") {
      clearInterval(t);
      btn.textContent = "重试";
    }
  }, 2000);
}
```

**效果**：点完下载立刻能继续搜别的，下载状态在按钮上实时更新。

### 一个容易漏的细节：加锁

`TASKS` 是被多个线程同时读写的字典（主线程写、下载线程写、查询接口读）。Python 的 GIL 虽然保证单条操作原子，但**「读-改-写」这种复合操作不是原子的**。

所以所有对 `TASKS` 的操作都套上锁：

```python
with TASKS_LOCK:
    TASKS[tid].update(kw)
```

不加锁的话，并发下载多个任务时状态可能串。

## 关键点三：PWA 让网页变成 App

**这是「三端通用」的关键。**

PWA（渐进式 Web 应用）的核心就一个 `manifest.json`：

```json
{
  "name": "我的工具",
  "short_name": "工具",
  "start_url": "/",
  "display": "standalone",
  "theme_color": "#c8553d",
  "icons": [
    { "src": "/icon.svg", "sizes": "any", "type": "image/svg+xml" }
  ]
}
```

关键字段是 `"display": "standalone"` —— **它让网页去掉浏览器地址栏，看起来就是一个独立 App。**

在 HTML 里引一下：

```html
<link rel="manifest" href="/manifest.json">
<link rel="apple-touch-icon" href="/icon.svg">
<meta name="apple-mobile-web-app-capable" content="yes">
```

然后各端的「安装」方式：

| 平台 | 操作 |
|---|---|
| iOS Safari | 分享 → 添加到主屏幕 |
| 安卓 Chrome | 菜单 → 添加到主屏幕 |
| Windows Edge | 菜单 → 应用 → 安装此站点为应用 |

**装完之后就是个图标，点开直接进，没有地址栏。**

### 图标用 SVG 内置

不用准备多种尺寸的 PNG，直接写一个 SVG：

```html
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 192 192">
  <defs>
    <linearGradient id="g" x1="0" y1="0" x2="1" y2="1">
      <stop offset="0%" stop-color="#d9694f"/>
      <stop offset="100%" stop-color="#b8452f"/>
    </linearGradient>
  </defs>
  <rect width="192" height="192" rx="42" fill="url(#g)"/>
  
</svg>
```

一个文件搞定所有尺寸，浏览器会自己缩放。

## 三端地址的组织

程序跑起来后，打印三个访问地址：

| 场景 | 地址 | 前提 |
|---|---|---|
| 本机 | `http://127.0.0.1:8099/` | 就在这台机器上用 |
| 局域网 | `http://192.168.x.x:8099/` | 手机连同一个 Wi-Fi |
| 虚拟局域网 | `http://172.16.x.x:8099/` | 需组网工具在线 |

获取局域网 IP 有个小技巧——**不用解析 `ipconfig` 输出**：

```python
import socket

def get_lan_ip():
    s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
    try:
        s.connect(("8.8.8.8", 80))     # 不会真的发数据
        return s.getsockname()[0]       # 但会告诉你走的是哪个网卡
    finally:
        s.close()
```

UDP 的 `connect` 只是**让系统选一条路由**，不会真的发包。比解析 `ipconfig` 输出（还要处理中文编码）可靠得多。

## 实测结果

| 项目 | 结果 |
|---|---|
| 搜索 | 30 条结果，封面全部加载 |
| 下载一个 2.2 MB 文件 | **6 秒**完成 |
| 配额扣减 | ✅ 正确 |
| 与主服务联动 | ✅ 自动识别新文件 |
| 桌面版渲染 | ✅ 880px 无溢出 |
| 手机版渲染 | ✅ 414px 无溢出 |

**闭环成立**：网页搜索 → 后台下载 → 落到目标目录 → 主服务直接认。

## 三条经验

**第一，先找 JSON 输出，再考虑解析文本。**

命令行工具如果支持结构化输出，一定要用。省下的不只是代码量——**JSON 里往往有表格里被截断的字段**（比如封面 URL），这些用文本解析根本拿不到。

**第二，耗时操作一律异步化。**

「发起任务 → 返回任务号 → 轮询状态」这个模式，比同步等待的体验好太多。而且实现成本很低，一个线程 + 一个字典就够了。**别忘了加锁。**

**第三，PWA 是覆盖三端成本最低的方案。**

一套 HTML 同时解决桌面、iOS、安卓。虽然有些能力不如原生（比如推送、后台任务），但对于「用手机查个数据、下个文件」这类场景，**完全够用，而且零维护成本。**

---

*本文记录的是实际开发过程，所有数据来自真实测试。*

我有个命令行工具，平时只能在电脑上敲命令。想让它变成手机也能点的网页，用 WorkBuddy 干了一个下午就搞定了——一个输入框、一个按钮，就这么简单。

WorkBuddy 实战 · 把命令行工具包成三端网页：一个输入框、一个按钮

云计算

用WorkBuddy将命令行工具封装成三端通用网页，核心是Python标准库实现HTTP服务，复用工具JSON输出省去文本解析，下载任务异步处理避免阻塞，配合PWA实现手机桌面零安装体验，实测搜索下载全流程顺畅。

WorkBuddy企业版限时双倍 Credits 活动

workbuddy

2026上云采购 | AI焕新·智启新局

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

WorkBuddy 实战 · 把命令行工具包成三端网页：一个输入框、一个按钮-腾讯云开发者社区-腾讯云

WorkBuddy 实战 · 把命令行工具包成三端网页：一个输入框、一个按钮

WorkBuddy 实战 · 把命令行工具包成三端网页：一个输入框、一个按钮

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐