KDock

面向嵌入式开发的桌面工作台：串口 / 网络调试 · 固件升级(OTA) · 烧录 · 设备文件 · 会自己动手的 AI 助手

串口与网络收发、命令速查、固件打包/升级/烧录、设备文件读写、实时图表、时序编排，
外加一个能直接调这些能力的 Agent —— 全部在一个窗口里。

中文 ｜ English

目录

• 它能做什么
• 截图
• 快速开始
• 界面速览
• 示波器
• 逻辑分析仪
• Agent 使用说明
• 协议与算法文档
• 从源码构建
• 目录结构
• 常见问题
• 开源协议与致谢
• 版本管理

它能做什么

截图

传输页：串口 / 网络收发 + HEX 视图 + 会话日志

命令表：标准 Linux 命令速查，点一下填进发送框

Agent：对话式调试助手，能直接读写设备、升级、烧录

批量文本：多行去重/排序/转格式，按间隔逐行发到串口

计算器：C 风格表达式 + 传统键盘 + 32 位控制板 + 文件校验

示波器：RIGOL DS1000Z 系（SCPI over TCP）—— 状态 / 自动测量 / 多通道波形 / 截屏

示波器页里的波形图：多通道叠加、悬停读数值（这条是 CH2 上的 1 kHz 方波）

Agent 信息页：技能与 MCP 开关、上下文成分、缓存命中与花费；技能由 agent 自己按需读取

快速开始

1. 打开 传输 页，选串口（或 TCP/UDP），点「连接」；
2. 发送框里写内容，Enter 发送、Shift+Enter 换行；HEX 形如 41 54 0D 0A；
3. 想升级固件：固件升级 页 → 选本地 .fw 或填服务器地址 → 选串口/网口通道 → 开始；
4. 想烧片：烧录 页 → 选工具与型号 → 选文件 → 烧录；
5. 想要个帮手：Agent 页 → 在设置里配一个模型（供应商 + API Key）→ 直接说需求。

界面速览

传输

• 串口参数（波特率/数据位/停止位/校验/流控）与网络参数都在右栏；连接状态在标题栏与状态点；
• 输出区支持 HEX/文本切换、时间戳、发送/接收着色、暂停与回看、导出会话日志；
• 「终端模式」把设备发出的 ANSI 序列渲染出来（退格、重绘、光标移动），像终端一样用；
• 快捷发送可以自己加常用命令。

命令表

标准 Linux 命令速查，按「文件 / 文本 / 系统 / 网络 / 权限」分组，带参数模板；
点命令名填进发送框，点 ▶ 直接发。搜索框支持命令名与说明。

固件升级

• 包：.fw = 64 字节包头（magic / 版本 / payload CRC / 包头 CRC / 板卡名）+ 镜像；
• 通道：串口（设备端 YMODEM 在线升级）或网口（服务端口按偏移写 + 校验 + 打升级标记 + 复位）；
• 来源：本地文件，或 HTTP 服务器的版本清单（自动按版本排序、下载后自检 CRC）；
• 每一步都有明确进度与"卡在哪一步"的人话报错。

烧录

界面只负责拼命令行并把输出实时回显；支持 OpenOCD / J-Link / STM32CubeProgrammer，
工具路径、适配器、型号、速度这些填一次就记住。适合首件、救砖、产线。

文件管理

列设备目录、取回文件、下发文件、核对 CRC；串口走 base64，网口走服务通道。

实时图表 / 屏幕捕获 / 示波器 / 中控编排

• 设备按 1.23,4.56,7.89 每行发一串数字，图表自动分通道画曲线；
• 屏幕捕获用系统桌面复制抓帧，参数可调；
• 示波器支持普源（RIGOL）DS1000Z 系，详见下面单独一节；
• 逻辑分析仪：看波形 + 解协议（19 种：UART · SPI · I2C · CAN · 1-Wire · DS18B20 · DHT · PS/2 · NEC 红外 · I2S · JTAG · SWD · Modbus · LIN · DMX512 · Manchester · 差分 Manchester · Miller · PWM），详见下面单独一节；
• 中控编排把多路连接串成流程，支持条件分支、超时、等待与日志。

批量文本 / 计算器

• 批量文本：多行去重/排序/加前后缀/加行号、转 HEX 数组 / HEX 串 / JSON / CSV / C 数组、
  搜索替换（Ctrl+F，支持全词、模糊、正则）、JSON 格式化、正则批量处理、大小写与缩进整理（选区优先）、
  按间隔逐行发到串口；
• 计算器：C 风格表达式（0x/0b/0o、<< >> & | ~ % **，手写解析不用 eval）、传统键盘、
  32 位控制板（点任意一位即改并反馈到计算区）、IEEE 754 浮点↔位（含符号/阶码/尾数拆解）、
  进制换算、文件校验（CRC32 / CRC16-CCITT / CRC16-MODBUS / MD5 / SHA1 / SHA256，可只算某一段）。

窄窗口 / 高 DPI

平时很少全屏，窗口小、或者系统缩放一大，CSS 像素就那么点。所以界面按"还放不放得下"分四级往下收，
每一级都留了回头路：

参数区随时可以用标题栏那个「▭」折叠 / 展开（宽窗折掉中栏立刻变宽，窄窗折掉下面那一整行），
导航的展开状态和参数区的折叠状态都记在本地。

传输页在这一档还会再省一层（小窗口里那两行工具最占地）：

• 中间：显示 / 行尾 / 历史 / 循环 / 清屏 / 时间戳 / 序号 / 方向 / 更多 那一整行收掉；
  "发送"那一行只留「文本 / HEX」开关贴在输入框左边，发送照旧 Enter；
• 右栏（已经挪到下面那条）：压成一行 —— 方式 / 串口 / 波特率 / 自定义 / 连接·断开；
  统计、快捷发送、高级参数收起来；760px 以下连标签也收掉（控件都有悬停提示）；
• 收起来的东西都在标题栏菜单里找得到：清屏 / 复制 / 暂停 / 自动滚动 / ASCII 交互，以及
  时间戳 / 行号 / 方向标记 / 显示用 HEX / 发送用 HEX。窗口拉宽就全部回来。
• 窄窗下连"自定义波特率"也收掉（要特殊波特率把窗口拉宽，或用标题栏「▭」看宽屏布局）。

升级页 / 烧录页在这一档同样把参数区压平（一到三行）：

• 升级 = 方式 / 端口 / 波特率 / 来源 / 文件 / 版本 / 连接·断开 / 升级；
• 烧录 = 工具 / 适配器 / 接口 / 速度 / 目标芯片 / 器件库 / 文件 / 路径 / 地址 / 擦除·烧录·校验·复位；
• 分组标题、长提示、命令预览、烧录工具路径全部收起；760px 以下连标签一起收。

计算器在窄窗只留"基本计算器 + 进制/标记 + 8 位位板"：

• 位运算那一行（<< >> AND OR XOR NOT）、x² / xʸ / x³ / 1⁄x / n! / √ / MOD / 字节交换、
  位板的移位·循环·全反 收起（53 键 → 35 键）——这些在「算式」输入框里照样能打（<< >> & | ^ ~ ** %）；
• 32 位板缩成 8 位（只留最低字节，位号 7..0），点单个位照样改值。

示波器 / 逻辑分析仪 / 屏幕捕获没有做这套降级 —— 它们不会在小窗口里用。

另外几页在窄窗下还各收了一点：

• 传输 / 固件升级（共用中间那张面板）：发送那一行整个收掉（连「文本 / HEX」都不留），输入框占满整行；
  要切 HEX 发送走标题栏「编辑」菜单（窄窗菜单在 ☰ 里）；
• 文件管理：参数区跟升级/烧录一样压平成一到三行（分组标题、长提示收起，760px 以下连标签一起收）；
• 命令表：「常用命令 + ✎ 编辑指令表」那一行收掉（搜索框留着），命令行行高压到 28px，一屏多看几条；
• 计算器：不看历史记录（那条参数带整条收掉）、32 位板留 16 位、显示区并成一行
  （左算式 / 右「= 进制 结果」，不再上下叠）、多进制那行收掉。

示波器

连的是 RIGOL DS1000Z / DS1000Z-E 系（DS1054Z、DS1202Z-E 这些）标配的网口口子：TCP 5555，SCPI 文本。

• 状态：型号（*IDN?）、各通道开关 / 档位 / 偏移 / 耦合 / 探头、时基、采样率、存储深度、触发源与电平；
• 通道卡片：直接改 V/div 与偏移（点「应用」下发到示波器）；
• 自动测量：频率 / 周期 / 峰峰 / 最大最小 / 平均 / 有效值 / 顶底电平 / 上升下降时间 / 正负占空，
  共 13 项，可以勾「连续」每 2 秒刷一次；没接信号的那一路显示 —（示波器回的是 9.9E37，按"测不到"处理）；
• 波形：多通道一起画（一通道一色，鼠标悬停读数），点数是屏幕的 1200 点，
  也可以选深存储（存储深度是 AUTO 时会提示"示波器只给了 1200 点"）；
• 截屏：直接取示波器屏幕（DISP:DATA? 回的二进制 PNG，原生 800×480）就地显示，可另存为；
• 控制：时基 / 触发源 / 触发电平 / RUN·STOP / 自动设置，外加一个 SCPI 控制台（带回复日志）。

同一套能力也挂在 Agent 上：scope_connect / scope_info / scope_measure /
scope_waveform（回摘要 + 字符画）/ scope_screenshot（默认存进会话工作区）/ scope_control，
再加上一条裸 scope <cmd>。所以"连着示波器看看 CH2 是什么波形"这种话可以直接跟 agent 说。

注意：DS1000Z 的 SCPI 口同时只接受一个客户端；被别的程序占着时本程序会自动重连，
但别同时开两个上位机。

逻辑分析仪

参考 DSView / PulseView 的用法做的查看页：左边通道列（名字 / 颜色 / 眼睛显隐 / 当前电平），右边波形，
下面按解码器各占一行，把解出来的字节 / 字段贴着波形画出来（方块颜色按"起始 / 地址 / 数据 / 应答 / 出错"
分类：橙 = 起始、紫 = 地址、蓝 = 数据、绿 = 应答、红 = 出错）。

19 种协议解码器（都是按各自规范实现的，不是"认个大概就能过"）：

数据来源：三个内置示例场景（按协议规范手工拼出来的真实波形，载入就带好对应解码器）、
导入 VCD（单比特标量，按 $timescale 展开）、导入 CSV、导入原始二进制（一个字节 = 8 个通道）。

• bus —— 常用总线：UART 115200 发 "KDock\n" · 1 kHz 25% PWM · I2C 读写 · SPI 读 JEDEC ID · DS18B20 温度 · NEC 红外；
• more —— 调试与音频：CAN 250k（标准帧 + 扩展帧）· JTAG（IR 4 位 + DR 16 位）· I2S 16 位 · PS/2 键盘两帧；
• enc —— 编码与工业总线：Manchester · 差分 Manchester · Miller · DHT22 · 1-Wire ROM · LIN · Modbus RTU · SWD · DMX512。

操作：滚轮缩放（Shift+滚 = 平移）、拖动平移、双击适应窗口、← → 平移 / +/- 缩放 / Home 回起点；
在波形上点一下放光标 A、Shift+点放 B（底下给 Δt 与 1/Δt）；
右栏按解码器列出它要的参数（通道 / 波特率 / 模式…），加协议就是"下拉里选一个 + 点 ＋"；
存盘导出 CSV（time + 各通道）或 VCD（PulseView / DSView / GTKWave 能打开）。

真机采集（fx2lafw / DSLogic 这类 USB 逻辑分析仪）这一版还没接驱动，能用的来源是上面这些；
接驱动时只要把采到的 samples 换进去，查看 / 解码 / 导出这条链路不用动。

同一套能力也挂在 Agent 上：
la_decoders（看支持哪些协议、每种协议要配哪些参数、有哪些示例场景）/ la_state（读状态）/
la_read（读解出来的字节 + 字段判定 + 每路测量）/ la_config（改配置：采样率、整份替换解码器列表、
通道显隐、选中哪一路、视图窗口、光标）/ la_capture（载入示例场景，或 source=device 明确报"驱动还没接"）/
la_save（存 CSV / VCD）。采到的数据本身 agent 改不了 —— 只能改配置或重新采集；
跟传输页那套一个形状：读类不审批，写配置 / 采集 / 存盘要审批。

Agent 使用说明

右栏三页：Agent 信息 / 文本 / 浏览器。

模型：设置 → 模型与供应商里配「供应商 profile」（OpenAI 兼容的 base_url，或 Anthropic 格式），
每个 profile 一个 Key（Windows 上用 DPAPI 按当前用户加密存储）。对话页下方的下拉可以随时切换，
会显示实时负载（AMD Radeon Cloud 那批免费模型）与测得的出字速度。

权限（对话页底部）：

技能：一份 SKILL.md（frontmatter 的 name/description 进系统提示，正文按需读）。
Agent 信息页只管开关，路径 / 导入 / 编辑都在 设置 → 技能。
常驻：技能行上的「常驻」开关打开后，该技能的正文每轮都注入系统提示（系统提示不参与裁剪、
也不会被压缩掉）—— 身份 / 口吻 / 说话规则这类技能就靠它生效，效果是"丢一个身份技能进来，agent
就变成那个人格"；SKILL.md 本身一个字不用改，内置的角色描述也不用动。常驻合计上限 16 KB
（超了前后端都会拦），占多少 token 在「上下文成分」里单列一栏。

MCP：设置 → MCP 里加 stdio 服务（command + args + env，也兼容其它工具那种
command 数组 + environment 的写法）；Agent 信息页只管启用开关。远程 HTTP 类型暂不支持。

斜杠命令：/goal <目标>（长期目标，每轮注入）、/compact、/new、/perm ask|auto|read、
/stop、/help。

上下文与花费：Agent 信息页显示上下文占用、成分分析（系统提示 / 工具定义 / 摘要 / 用户消息 /
助手回复 / 工具调用）、缓存命中率、估算花费与出字速度（只统计模型正在出字的那段）。

协议与算法文档

升级、OTA 包、烧录这几块"实现细节多、容易踩坑"的功能都单独成文：

从源码构建

需要 Node.js 18+、Rust 1.80+（MSVC 工具链）与 Tauri 2 的系统依赖。

npm install
npm run dev            # 只跑前端（配合下面的 tauri dev）
npm run tauri dev      # 开发模式：前端热更 + Rust 后端
cargo test --workspace # 单元测试（在 src-tauri 目录下，或加 --manifest-path）
npm run tauri build    # 出包：Windows 下产物是 target/release/kdock.exe

⚠️ 出包只能用 npm run tauri build。直接 cargo build --release 编出来的是 dev 模式二进制，
它会去加载 devUrl（http://localhost:1420）；没有前端开发服务器时窗口就是浏览器那个
"无法访问此页"。

🔧 调试口子：debug 构建里设 KDOCK_DEBUG_PORT=<端口> 再启动，会给 WebView2 打开远程调试端口，
可以用 CDP 脚本驱动界面做回归测试（release 包里这段代码不存在）。

目录结构

.
├─ crates/kdock-core/     协议层：HEX 编解码、行尾、波特率、串口参数映射、会话日志（与 UI 解耦，可单独测）
├─ src-tauri/             Tauri 2 应用：串口/网络 I/O、升级与烧录、Agent、文件与窗口命令
│  └─ src/agent/          Agent：LLM 客户端、工具、技能、MCP、会话存储
├─ src/                   前端（Vite + 原生 JS，无框架）
│  ├─ main.js             界面与业务逻辑
│  └─ tools-batch-calc.js 批量文本 / 计算器
├─ docs/                  功能与协议说明、截图
├─ tools/                 辅助脚本（图标生成等）
└─ dist/                  前端构建产物（被 Tauri 内嵌，不入库）

常见问题

Q：双击 exe 没反应 / 闪退？
A：先看是不是已经开着一个 KDock（单实例：第二次启动只会把已有窗口叫到前面）。
若上次是被强杀的，WebView2 的进程可能还占着数据目录，等几秒或结束残留的 msedgewebview2.exe 再试。

Q：窗口边框 / 任务栏图标不对？
A：自绘无边框窗口在 Windows 上要额外处理非客户区，代码里已经处理（含最大化贴工作区与 DWM 描边）。
遇到异常请带上系统版本反馈。

Q：升级中途断电/断线会怎样？
A：设备端会拒收不完整的包；重跑一次升级即可（网口按偏移写，会覆盖）。详见 docs/03。

Q：/goal 设了目标但没生效？
A：目标存在会话里，每轮都会拼进系统提示；用 /goal 可以查当前值，/goal clear 清除。

Q：为什么有些界面文字是英文？
A：设置 → 通用里可以切换中英文，切换是即时生效的。

版本管理

• 应用版本走 语义化版本 MAJOR.MINOR.PATCH，当前
  v0.3.0（关于页也会显示实时值）。版本号在这三处保持一致：
  src-tauri/tauri.conf.json、src-tauri/Cargo.toml、package.json；
• 每次发版在 CHANGELOG.md 追加一段，并打 vX.Y.Z 的 git tag
  （例如 git tag v0.3.0 && git push origin v0.3.0）；
• 固件包版本是另一套：.fw 包头里的三段式 PD_HW.PD_SW.PD_FIX，用于设备端判断能否升级/降级，
  与应用版本无关（见 docs/01）；
• 应用内「设置 → 关于与数据」里也写了同样的约定，并给出当前版本、作者与仓库地址。

开源协议与致谢

本项目以 Apache License 2.0 开源，见 LICENSE；第三方组件与借鉴项目的声明见 NOTICE。

特别感谢（设计/交互参考过的开源项目）：

• MICU-OmniProbe（README 声明 MIT）：
  实时图表的实现思路与配色方案参考了它；
• opencode：Agent 的交互形态参考了它 ——
  上下文成分/花费面板、技能与 MCP 的组织方式、"边跑边补充方向"这些都受益于它；
• CC Switch：供应商 profile 列表与技能管理的组织方式参考了它；
• Tauri、uPlot、
  RustCrypto 等开源项目提供的坚实基础。

欢迎 issue / PR。