# ZhiBi

**Repository Path**: aneiangsoft/ZhiBi

## Basic Information

- **Project Name**: ZhiBi
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-30
- **Last Updated**: 2026-11-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 指笔 ZhiBi

> 指头当笔，提笔就写。

用笔记本触摸板写字的**中文输入辅助工具**。面向不会打字、提笔忘字、又不想学拼音的人——
不用买数位板，不用装手写屏，指头在触摸板上划几下，字就出来了。

## 它解决什么问题

很多老人不是不愿意用电脑，是卡在「把想法变成字」这一步：

- 拼音不会，五笔更难，语音输入在人多的地方张不开嘴
- 手写板要额外买、额外装、额外带，还常常认不出字
- 手机上能写，换到电脑上就不会了

指笔把已经在你手边的触摸板变成一块小纸。呼出面板，写几笔，字直接落到
当前光标所在的输入框里——微信、Word、浏览器搜索框都行。

## 功能

| 能力 | 说明 |
| --- | --- |
| 触摸板直接写字 | 直读触摸板 PTP 报文，落指、抬指、绝对坐标全部拿到，不依赖光标移动 |
| 连写成句 | 一句话写完再一次识别，两字约 38ms、三字约 41ms，比逐字快一个量级 |
| 候选选字 | 轻点板面换下一个候选；数字键 1–9 / 0 直接选；`←` `→` 移动高亮 |
| 多指手势 | 写着时第二根指头落下（双指滚动、三指点按）作废当前笔，不落字 |
| 鼠标兜底 | 没触摸板的机器可以按住左键在纸面上写，可在设置里关掉 |
| 鼠标拦截 | 写字期间不让光标跟着指头跑，避免误点到别的窗口 |
| 贴着光标 | 浮层落在输入光标旁；下方放不下就翻到上方，候选行同时跟着镜像到靠光标那一侧 |
| 空闲透明 | 纸上没笔迹时纸面半透明，能看穿到背后；落笔立刻变实 |
| 托盘常驻 | 全局热键呼出/收起，默认 `Ctrl+Alt+H`；撤销 `Ctrl+Alt+Z` |
| 可调手感 | 面板尺寸、笔迹粗细、识别延时（快/标准/慢）、各类辅助动作都能开关 |
| 开机自启 | 可选，走 HKCU 的 Run 键，不需要管理员权限 |

## 系统要求

- Windows 10 版本 2004（19041）及以上，或 Windows 11
- .NET 9 桌面运行时（自行编译则只需 .NET 9 SDK）
- 一块 Precision Touchpad（PTP）触摸板。绝大多数 2017 年后的笔记本都有

## 快速开始

1. 从 [Releases](https://gitee.com/aneiangsoft/ZhiBi/releases) 下载 `ZhiBi.exe`
2. 双击运行，托盘出现一支笔的图标
3. 在任意输入框里按 `Ctrl+Alt+H`，面板出现
4. 用指头在触摸板上写字，停顿一下自动上屏

> 首次启动只弹一句「已启动」提示，不会自作主张弹面板——很多人装了输入法
> 并不想让它立刻挡在屏幕中间。

## 构建

```bash
git clone https://gitee.com/aneiangsoft/ZhiBi.git
cd ZhiBi
dotnet build -c Release
```

产物在 `src/ZhiBi/bin/Release/net9.0-windows10.0.19041.0/ZhiBi.exe`。

打成单文件（约 77MB，无需安装 .NET 运行时）：

```bash
dotnet publish src/ZhiBi/ZhiBi.csproj -c Release -r win-x64 --self-contained true \
  -p:PublishSingleFile=true -p:IncludeNativeLibrariesForSelfExtract=true \
  -p:EnableCompressionInSingleFile=true -p:DebugType=none -o dist
```

## 命令行自检

这个程序的行为大多发生在屏幕之外（钩子、报文、识别），肉眼只能看到「行」或「不行」。
所以留了一组自检入口，改完代码跑一遍比手动点快得多：

| 命令 | 检查什么 |
| --- | --- |
| `ZhiBi.exe --check` | 热键解析、设置往返、默认值等 21 项 |
| `ZhiBi.exe --gesture` | 多指手势仲裁：第二根指头落下要不要作废当前笔 |
| `ZhiBi.exe --sentence` | 连写整句的识别能力与耗时 |
| `ZhiBi.exe --imepanel` | 面板键位、显隐、失焦收起、版式镜像、纸面透明度 |
| `ZhiBi.exe --caret 12` | 光标位置诊断：Win32 插入符 / UIA / 子树查找三层各自拿到了什么 |
| `ZhiBi.exe --boot` | 启动流程（加 `--tip` 看首次提示气泡） |
| `ZhiBi.exe --switch` | 布局对不上时能否自动切换解码器 |
| `ZhiBi.exe --padscan 10` | 扫描触摸板报文与布局，**换机器写不出字时跑这条** |
| `ZhiBi.exe --hidtest 04-12-2E-0C-4B-05` | 用一条已知报文离线验证解码（不用真去摸触摸板） |

## 项目结构

```
src/ZhiBi/
├── Program.cs          入口：单实例、命令行分发、日志
├── App/                应用级服务
│   ├── Settings.cs     用户偏好（%LOCALAPPDATA%\ZhiBi\settings.json）
│   └── AutoStart.cs    开机自启
├── Input/              输入捕获
│   ├── PadHid.cs       触摸板 PTP 报文直读 + 布局对不上时的自动切换
│   ├── PadLayout.cs    内置常量布局（本机 ELAN06FA 的报文格式）
│   ├── PadUsage.cs     设备自己的解码器（系统 HID 解析器，不碰位偏移）
│   ├── PadProbe.cs     枚举触摸板、读能力表、建解码器
│   ├── PadPointer.cs   触摸板指针
│   ├── RawInput.cs     原始输入设备
│   ├── MouseGuard.cs   写字期间拦截鼠标消息
│   ├── Hotkey.cs       全局热键
│   ├── KeyWatcher.cs   键盘钩子
│   └── LiftDetector.cs 抬笔判定
├── Recognition/        笔迹识别
│   └── InkEngine.cs    包一层 Windows 手写识别器
├── Output/             上屏
│   └── TextSink.cs     把字送进当前焦点窗口
├── UI/                 界面
│   ├── ImeWindow.cs    输入法浮层主窗口
│   ├── ImeSurface.cs   纸面绘制与候选排版
│   ├── InkWindow.cs    全屏练字板（`--draw`）
│   ├── InkSurface.cs   练字板绘制
│   ├── SettingsWindow.cs / SettingsControls.cs  设置界面
│   └── Tray.cs         托盘图标与气泡
└── Diagnostics/        自检与诊断
    ├── ImePanelCheck.cs / PadGestureCheck.cs / SentenceCheck.cs
    ├── PadSwitchCheck.cs   布局自动切换的端到端验证
    ├── PadScan.cs          触摸板报文扫描（`--padscan`）
    ├── CaretScan.cs        光标位置三层诊断（`--caret`）
    ├── StrokeSelfTest.cs
    └── PointerProbe.cs
```

## 触摸板兼容性

报文怎么解，默认走内置常量：Report ID 4、X 在 `[2..3]`、Y 在 `[4..5]`、量程 3679×2261，
也就是开发机的格式。

换一台笔记本，这些只要有一项对不上，症状都是「触摸板没反应」，屏幕上还不报错。
所以加了一层兜底探测，**只在明显不对劲时才启动**：

| 触发条件 | 说明 | 用户看到的 |
| --- | --- | --- |
| 收到 6 条报文、一条都解不出 | Report ID 或字段位置不同 | 完全没反应 |
| 有 8 条报文因坐标越界被丢 | 量程比常量小 | 只有板子一角能写 |

触发后程序会去问系统要这台设备的真实布局，然后切过去继续写。用的是
`HidD_GetPreparsedData` + `HidP_GetUsageValue` / `HidP_GetUsages`——**只要查询权限**，
不需要读报文，所以不会被 PTP 驱动拒掉。

两个踩过的坑，写在代码注释里了：

- 能力表的 `DataIndex` 是「第几个数据项」的序号，**不是位偏移**，当位偏移用会互相重叠；
- Tip Switch / Confidence 是**按键型**控件，根本不在值能力表里。照抄值能力表去解，
  会得到「永远是按下状态」，表现为一笔画到底、字糊成一条。

已知能用的机器上，这套探测代码一行都不会执行——先探测再决定怎么解，容易把本来能用的机器搞坏。

排查工具：`ZhiBi.exe --padscan 10`，会打印设备能力表、两种解法在同一批报文上的命中数，
以及结论。把输出发回来就能定位问题。

### 实测机型

| 触摸板 | Report ID | 量程 | 触点数/报文 | 走哪条路 |
| --- | --- | --- | --- | --- |
| ELAN06FA（开发机） | 4 | 3679×2261 | 1 | 内置常量，无需探测 |
| DELL097B（Dell 笔记本） | 3 | 1229×749 | 1 | 设备解码器（常量命中 0/257 条，探测后切换） |

两台机器的报文格式差别很大——Report ID、量程、字段位置全都不同，是同一套兜底逻辑
覆盖掉的。如果你在第三种机型上遇到写不出字，跑一次 `--padscan` 就能判断是
「布局对不上」还是「压根不是 PTP 触摸板」。

## 已知限制

- **老式非 PTP 触摸板用不了**。程序要的是板面绝对坐标，只有精密触摸板（PTP）才提供；
  那种只报相对位移的老触摸板，手写这件事在物理上就不成立。`--padscan` 会明确告诉你是这种情况。
- 报文布局默认用本机（ELAN06FA）的常量，**换机器时会在约 0.2 秒内自动探测并切换**
  （见「触摸板兼容性」）。已在 Report ID、量程、字段位置全都不同的 DELL097B 上实测通过；
  已知能用的机器上这套探测代码不会执行，行为与旧版逐位相同。
- **没有代码签名**。程序同时做了全局键鼠钩子、自启、模拟输入，这几样组合起来
  在杀毒软件眼里和键盘记录器很像，可能被拦或被提示。
- **不是真正的输入法**（没接 TSF）。它靠剪贴板/模拟按键把字送出去，
  在少数做了输入保护的窗口里可能不生效。
- 面板定位按主屏工作区算，多屏（尤其副屏不同缩放）可能偏。

## 许可

[MIT](LICENSE)