掌问（ZhangWen）本地 Web 安装教程

掌问（ZhangWen）本地 Web 安装教程

项目地址：https://gitee.com/zmh1979/ask-with-your-palm 掌问是本地部署的创作平台，集成 MicroPython 编程、硬件资料库、AI 对话、Web Serial 上传、结构设计、3D 与激光造物。

一、系统要求

无需预装 Git、Node.js、Python。安装器会自动检测已有环境，缺失时才下载项目内独立运行时（Node 24.14.0、Python 3.13.7），不修改系统 PATH，不需要管理员权限。

二、一键安装（推荐）

Windows 10/11

方式一：PowerShell（推荐）

打开 PowerShell，粘贴执行：

irm https://gitee.com/zmh1979/ask-with-your-palm/raw/master/install.ps1 | iex

方式二：CMD

powershell.exe -NoLogo -NoProfile -ExecutionPolicy Bypass -Command "irm https://gitee.com/zmh1979/ask-with-your-palm/raw/master/install.ps1 | iex"

macOS

打开「终端」，粘贴执行：

curl -fsSL https://gitee.com/zmh1979/ask-with-your-palm/raw/master/install.sh | bash

安装过程说明

1. 安装器自动检测已有环境，缺失才下载运行时（已校验 SHA-256）。
2. 按锁定版本检查、补齐依赖。
3. 自动构建并打开浏览器。
4. 首次安装需要联网，之后日常使用为本地运行。

三、安装完成后的入口

启动后会自动打开浏览器，默认地址：

http://127.0.0.1:3080

• 端口被占用时自动切换到空闲端口，实际地址显示在服务窗口。
• 保留服务窗口，按 Ctrl+C 停止服务。

macOS 找不到入口时：在 Finder 按 ⌘⇧G，分别查看 /Applications 与 ~/Applications。安装输出中的 Application: 一行会显示实际入口路径。

四、已下载源码时的启动方式

如果已经把仓库克隆/下载到本地：

如果你本机已有 Node 22+ 和 Python 3.12+，也可以手动执行：

npm run setupnpm start

Intel Mac 请使用 Python 3.12 / 3.13。

五、使用注意事项

1. 浏览器选择：Web Serial（设备串口上传）和本地项目文件夹操作请使用桌面版 Chrome 或 Edge；Safari 不支持 Web Serial。
2. 服务范围：本地服务只监听 127.0.0.1，不对外暴露。
3. 数据目录（用户数据与程序版本分开）：

• Windows：%LOCALAPPDATA%\ZhangWen\data

• macOS：~/Library/Application Support/ZhangWen/data

4. API Key：在平台「API 设置」中配置 DeepSeek / GLM / Qwen / Kimi 或自定义 OpenAI 兼容接口；Key 只存本机，不随项目导出。纯手工编程不需要 Key。
5. 安装失败时：先查看错误输出；不要删除 data 目录，里面是你的项目和用户数据。

六、更新

• 方式一：再次执行上面的一键安装命令，会自动检查并安装 Gitee 最新版本（同一版本校验通过后跳过源码下载）。
• 方式二：在平台内使用「检查更新」，确认后才安装，下次启动生效；检查失败不影响现有工作台。

从旧版平台内更新可能使用旧安装器，遗漏新增入口；新版本正常启动时会自动补齐。

七、常见问题

下面是第二种CMD安装的过程截图

安装完成后打开http://127.0.0.1:3080/

配置一下

填入自己的API Key，保存设置。

deepseek会赠送6元，可以使用一周时间，尽情的享用吧。