Skip to content

字浮 CharFloat v2.2.1

Choose a tag to compare

View all tags
@Jolly-J Jolly-J released this 12 Oct 02:54
· 5 commits to main since this release
v2.2.1
e54b4b9

字浮 CharFloat v2.2.1

人机实时协同体系与表格富文本深度治理版本

彻底解决了 WPS/Excel 插件长久以来的「单元格写入变粗、局部加粗变全格粗体」的顽疾：排查证实该现象并非 MCP 传输层故障，而是单元格写入继承原有粗体字族（Microsoft YaHei Bold）、Font.Bold=false 无法消除粗体字族变体，以及修改整格字体会重置字符级局部格式等三重宿主机制叠加导致的。现在 patch_cells 支持在写入数据时顺带规范化字体与字重，get_range_styles 新增 runs 字符级富文本分段读取能力，排查正文格式一目了然。

全面强化「人机实时协同（Live Co-editing）」第一心智：针对字浮主打人机共享同一活工作簿的场景，全面根治 AI 盲目信任历史记忆行号导致的错行覆写问题，规范「写前轻量核验（Refresh-Before-Write）」协议，在追加数据或覆盖已有单元格前动态嗅探最新边界与切片真值，彻底防止错行及覆盖用户手工修改。

同时，近 6000 行的 WPS 表格加载项核心代码完成了 18 模块的高内聚重构拆分；建立了严格的发布制度与全链路版本一致性门禁；完成了「字浮 CharFloat」品牌统合；优化了 Office 多个后台工作簿的连接隔离与长生命周期保持。

官网：https://charfloat.online/ | 源码：GitHub 仓库

核心演进与排查深度剖析

1. 人机实时协同（Live Co-editing）防错行与防覆盖规约

在人机共享同一桌面、同一窗口与活工作簿的场景下，过去 AI 容易陷入“离线独占批处理”的思维定势，曲解了“最小读取”原则：在多轮交互中，AI 盲目信任旧上下文记忆中的绝对行号（如“第 11 行”）。当人类用户在两轮之间手动插入了数据行或修改了单元格后，AI 接管执行往往发生错行（如把追加汇总写到了用户新插入的数据行上）或把用户刚才手动调整的数据粗暴覆盖。

本次协同规约升级落地：

  • 确立人机实时协同第一设定：在主技能规范中确立第一心智，明令严禁跨轮次盲目信任历史行号与旧数据状态。
  • 写前轻量核验（Refresh-Before-Write）协议：
    1. 边界嗅探防错行：涉及追加数据、行末计算或批量操作时，在写入前必须调用超轻量工具 wps_get_sheet_outline（毫秒级获取最新 UsedRange 边界与行数），核验真实末行；对于“小计”、“合计”等业务特定行，优先使用 wps_search_cells 文本锚点动态定位，禁止硬编码绝对行号。
    2. 切片读取防覆盖：准备覆盖已有单元格时，先用 wps_read_range 切片读取目标格当前真值。若发现已被用户手工修改，必须吸收最新值做增量合并，禁止无知觉盲写覆盖。
    3. 纠偏“最小读取”：明确界定“最小读取”是指不滥读全表无用区域，绝不等于跳过写前对关键目标区域的最新状态核验。
  • 工具描述层精准增强：在 outline、patch、search、read 等工具描述中全量注入人机协同防错行防覆盖警示，使所有调用工具的 AI 都能直接获得正确引导。

2. 单元格字重与富文本治理（根治写入显粗、局部加粗变全粗、样式覆盖）

此前在调用写入单元格或对单元格内部分文字加粗时，经常出现整格文字视觉上全部显粗的异常，排查深层机理发现：

  • 写入不规范化字体（接口行为）：Range.Value2 = 文本 仅更新值，完全保留单元格原有的字体。若单元格原本是从外部粘贴带入的粗体字族（如 Microsoft YaHei Bold），写入的常规文本会直接继承该粗体字族。
  • Font.Bold = false 治不了粗体字族（宿主行为）：给单元格设置 Bold = false 仅仅是关闭字重修饰开关；但若字族本身就是粗体变体，宿主仍然以粗体字族渲染。必须显式将 Font.Name 换回常规字族（如 Microsoft YaHei）才能真正变细。
  • 修改字体名会重置字符级格式（顺序陷阱）：宿主底层修改整格 Font.Name 时，会清空单元格内已有的字符级局部格式（Characters）。若先局部加粗再改字体，局部格式会被完全覆盖。

本次治理落地：

  1. patch_cells 新增规范化字体与字重参数：支持传入 fontName（如 'Microsoft YaHei'）与 bold（如 false）。在写入数值或公式后顺带规范化目标区域字体，彻底阻断原粗体字族的继承扩散。
  2. get_range_styles 新增富文本分段读取（runs）：在 include 中传入 "runs"，即可逐段读回单元格内部的字符级切片列表 [{ start, length, text, fontName, bold, fontSize, fontColor }]。单格格式一致时走快速非混合检测，混合格式时逐字符精确探测，文字片段的字体与字重一目了然。
  3. 技能规约与避坑指南全面升级：在工具定义、工作流与避坑清单中规约执行顺序——必须「先统一整格字族，再施加字符级局部格式」；同时明确警告预览图（capture_sheet_preview）存在渲染通道字体替换，不可作为字体验收依据，验收一律以属性探针为准。

3. WPS Excel 核心架构模块化重构

为解决单文件过长、维护难度大和职责不清的问题，将原近 6000 行的 wps-addon/src/excel.js 彻底拆解为 18 个独立的领域模块片段：

  • 模块清晰归位：拆分为纯函数（pure.js）、设计语言（design.js）、样式检测（styles.js）、格式化与局部富文本（format.js）、单元格写入与快照（range.js）、工作表与行高列宽（sheets.js / rows-columns.js）、图表读写（chart-read.js / chart-write.js）、数据验证与高级表格（table-pivot.js / validation-*.js）等。
  • 构建链与测试防御：重构后的构建脚本增加递归清单合法性校验，杜绝漏登记、重复或未跟踪片段；新增纯函数测试与 RPC 契约等价性回归套件，保证打包生成物与重构前逐字节等价。

4. 发布制度与版本质量门禁体系

  • 语义化发布规范：正式确立 MAJOR.MINOR.PATCH 严格语义化版本发布标准与候选包指纹追踪制度。
  • 全链路一致性自动化门禁：新增 check-version.mjs 门禁，将 package.json、锁文件、Bridge 运行时、WPS/Office 插件清单、UI 状态与 CHANGELOG 进行强关联校验，阻断任何一处版本漂移。

新增

  • 人机实时协同（Live Co-editing）写前轻量核验规约：制定 get_sheet_outline 边界嗅探防错行、search_cells 动态锚点与 read_range 切片防覆盖三大执行协议，从心智层根除 AI 盲目信任旧行号引发的错行覆写。
  • patch_cells 支持 fontName 与 bold 可选参数：批量写入数据或公式时，可同步重置区域字族与字重。
  • get_range_styles 支持 include: ["runs"]：单单元格及逐格模式下支持返回字符级富文本 runs 清单。
  • Office 共享运行时长连接：Excel 加载项配置共享运行时，首次激活后为当前工作簿启用后台自动连接；支持的版本收起侧栏后保持长效连接。
  • 版本一致性校验脚本：新增 npm run check:version，作为本地构建、打包 beforePack 及 CI 的强制放行关卡。

修复

  • 富文本单元格局部修改保真（根治编辑富文本单元格时整格误染为红粗样式）：WPS 底层全格纯文本覆盖时会退化套用首段高亮样式；现已将 find_and_replace 升级为基于 Characters 的原位精准增删替换，100% 保持其余未变动段落的原有加粗、颜色；patch_cells 写入纯文本探测到富文本时自动规范化为常规黑色正文，彻底阻断红粗标题泛滥；get_range_styles 的 runs 模式追加字符颜色探测并将单格扫描上限提升至 2000 字符。
  • 后台守护进程跨平台容错与会话隔离稳健性：解决在特定操作系统环境下冷启动守护进程时的动态端口冲突，增加进程异常退出即时侦测与 12 秒启动宽容度，保障双平台全套 160 个自动化回归测试稳定通过。
  • 单元格混合格式在 get_range_styles 中返回 null 容易被误判为读取失败：工具描述与文档澄清 null 代表区域内或单元格内部格式不一致（混合格式），非宿主不支持。
  • 预览图渲染通道失真误导字体验收：capture_sheet_preview 导出时可能发生字体替换与抗锯齿加粗，导致常规字体在预览图中显粗；现已在所有工具说明与技能中明确标注不可作为字体验收依据。
  • Office 多个后台工作簿相互替换连接导致调用串扰：按精确文档定位调用，对歧义目标在执行前坚决拒绝，彻底实现多工作簿连接隔离。
  • Office 工具栏图标与静态缓存响应：修复 Office 插件图标 URL 目录映射错误及禁止缓存响应导致默认图标替代的问题，补充高 DPI 图标。
  • WPS 侧栏与后台通信轻量化：精简 WPS 侧栏为协同面板，收起侧栏不会断开后台连接，功能区改用专用 32px / 64px 图标，消除缩放模糊。
  • Electron 字节码 CLI 动态导入校验：修复字节码 CLI 在特定落盘导出场景下的动态导入依赖判定问题。

升级与使用说明

  1. 配置兼容性：数据结构与已有 MCP 工具契约完全向后兼容，无需重置既有配置。
  2. 加载项更新生效：升级到新版本后，请从字浮桌面客户端停止并重新启动后台服务；若 WPS 或 Office 功能区仍显示旧图标或旧逻辑，请保存文档后完全退出办公软件（macOS 请 Cmd+Q，Windows 请关闭所有进程）再重新打开。

下载与运行

  • macOS（Apple Silicon / arm64）：下载 CharFloat-2.2.1-mac-arm64.zip，解压得到 字浮 CharFloat.app 拖入「应用程序」文件夹运行（无开发者证书签名，首次打开如遇安全提示请在「系统设置 → 隐私与安全性」中允许）。
  • Windows（64 位 / x64）：下载 CharFloat-2.2.1-win-x64.zip，解压后双击 字浮 CharFloat.exe 即可免安装运行。

校验信息 (SHA-256)

  • CharFloat-2.2.1-mac-arm64.zip: cdb7abde4184cedc9db68951c462591f472da8d1a8ad1cec40ed5c24145cbdbf
  • CharFloat-2.2.1-win-x64.zip: 4ca304f7a317a894e44aa4266f1682d43f937099155c536a1b6bf2c67d4210ac
Assets 4
Loading