> 环境：WorkBuddy 客户端 ＋ OpenHarmony / HarmonyOS（`ohos-aarch64`，musl libc）＋ Electron 沙箱
> 适用：需要在信创环境、移动端或受限沙箱里落地 AI Agent 的开发者

## 目录

1. 先看清环境：这不是普通 Linux
2. 坑 1：pip 的「假成功」
3. 坑 2：越过签名校验，问题才真正暴露
4. 换思路：长文档不要用编辑器 API 逐段读
5. 要生成 .docx，交给 WorkBuddy 的本地 editor SDK
6. 把踩坑变成「技能」，别重复交学费
7. 小结：可复制清单

---

## 一、先看清环境：这不是普通 Linux

很多坑的根因，在动手前就已经写好了。先把环境画出来：

| 项目 | 实际情况 |
|---|---|
| 架构 | `ohos-aarch64` |
| libc | **musl**，不是 glibc |
| Shell | 没有 `/bin/sh`、没有 `/bin/bash` |
| 诊断工具 | 没有 `ldd` |
| `/tmp` | 只读 |
| Python | 3.12，自带 |

记住两个推论：

1. **凡是编译时假设 glibc 的二进制，到这里都不认。**
2. **调试手段比常规 Linux 少，报错信息就是你唯一的线索。**

## 二、坑 1：pip 的"假成功"

第一个坑最会骗人。

```bash
$ python3 -m pip install lxml
Successfully installed lxml-5.4.0
```

装机过程一路绿灯，看不出任何异常。然后：

```python
>>> import lxml.etree
Permission denied
```

明明装上了，为什么 import 不了？拆开看两件事：

**第一，平台有 ELF 签名校验。** 非本机签名的动态库直接拒载，报 `Permission denied` 而不是 `ImportError`——这个报错很有误导性，容易让人往权限方向查。

**第二，ABI 根本没对上。** 看解释器的扩展后缀：

```python
>>> import sysconfig; sysconfig.get_config_var('EXT_SUFFIX')
'.cpython-312-aarch64-linux-ohos.so'
```

而 pypi 上的 aarch64 轮子，后缀清一色是 `manylinux2014_aarch64`。**`--platform` 参数只影响 pip 认不认这个文件名，并不会改变二进制里的 ABI。**

> 教训：`pip install` 成功 ≠ 模块可用。在非主流平台上，装完必须立刻跑一次 `import` 验证。

## 三、坑 2：越过签名校验，问题才真正暴露

既然卡在签名上，很自然会想：那把签名这一关解决掉不就行了？

校验确实越得过去，`Permission denied` 也随之消失——**看起来解决了**。可紧接着，真正的拦路虎才露面：

```text
Error relocating .../etree.cpython-312-aarch64-linux-ohos.so:
  PyModule_AddObject: symbol not found
```

根因很朴素：本机**没有 `libpython3.12.so`**，Python 的符号只存在于主程序的符号表里。glibc 环境下的 CPython 扩展习惯从 `libpython` 动态解析符号，这里解析不到。

而 `ldd` 不存在，连"它到底依赖谁"都查不了。

**结论：这是平台级不兼容，不是配置问题。** 在这条路上继续投入是纯止损。果断换方案。

> 这一条花的时间最不值。判断标准其实很清晰：**当错误从"权限"变成"符号重定位"，就不是配置能解决的了。**

## 四、换思路：长文档不要用编辑器 API 逐段读

任务本身是读一份超长 Word（十万字量级）并提炼要点。

**先试的正路**：WorkBuddy 自带的文档编辑器 API，逐段取内容。问题很直接——**一次调用只返回一个块**，十万字要几百上千次调用。时间和 token 双双不可接受。

**换的思路**：`.docx` 本质就是个 zip。直接拆开读 XML：

```python
import zipfile, re

def extract_docx(path: str) -> list[str]:
    """把 .docx 的正文按段落/表格抽出为文本行（保持原始顺序）。"""
    xml = zipfile.ZipFile(path).read('word/document.xml').decode('utf-8')
    body = re.search(r'<w:body>(.*)</w:body>', xml, re.S).group(1)
    blocks = re.finditer(
        r'<w:tbl>.*?</w:tbl>|<w:p[ >].*?</w:p>|<w:p/>',
        body, re.S
    )
    out = []
    for b in blocks:
        seg = b.group(0)
        text = ''.join(re.findall(r'<w:t[^>]*>(.*?)</w:t>', seg, re.S))
        if text.strip():
            out.append(text)
    return out
```

一次读完，落成**带行号的纯文本**，后续按行号定点取用——检索、摘取、核对都变成了普通的文本操作。

**收益**：几百次 API 调用 → 1 次文件读取。

> ⚠️ 一句纪律：直接拆 XML 属于**降级手段**，绕过了产品的标准通道。如果只是自己跑批处理没问题；如果是在有规范约束的场景下，**先跟需求方说明再动手**，别默默绕。

## 五、要生成 .docx，交给 WorkBuddy 的本地 editor SDK

读的问题解决了，写的问题又来了。常规的 `python-docx`、`html-to-docx` 在这台机器上——**同样卡在 lxml**（见坑 1）。

绕开依赖链，用 WorkBuddy 内置的本地 editor SDK，三步：

**① 新建文档，拿到 `file_id`**

```bash
python3 edsdk.py call create_doc
# → file_id=new_doc_xxxxxxxx_xxxx
```

**② 插入内容（关键：长内容走文件，别塞命令行）**

```bash
python3 edsdk.py call doc_insert_markdown --json '{
  "file_id": "new_doc_xxxxxxxx_xxxx",
  "idx": 0,
  "markdown": "file:///abs/path/draft.md"
}'
```

`markdown` 支持 `file://<绝对路径>`，从文件读——**省 token、免转义、免编码事故**。支持标题、列表、表格、加粗等常见语法。

**③ 保存到指定路径**

```bash
python3 edsdk.py call save_file --json '{
  "file_id": "new_doc_xxxxxxxx_xxxx",
  "file_path": "/abs/target.docx"
}'
```

### 这一步又踩了三个小坑

**坑 A：空白模板不带页面属性。**
新建出来的文档，XML 里既没有 `sectPr`（节属性）也没有 `docDefaults`（默认样式）→ 页面尺寸、页边距、字号全部走宿主默认值。

**所以想做"一页纸"这种版式，只能靠控制字数，没法靠调页面参数。** 实测经验值：**550–650 字 + 一张小表**，在常见默认字号下稳在一页内。

**坑 B：保存后不要主动关闭文件。**
用户正在预览面板里看着这个文档。`save_file` 就够了，`close_file` 会把他正在看的视图关掉。

**坑 C：`present_files` 返回的是文件地址，不是 `file_id`。**
需要 `file_id` 时去查编辑器池，**不要**默认调 `open_file`——重复 fresh open 会开出与前端订阅脱节的新实例，结果是**你在改，用户在面板里看不到任何变化**。这种 bug 排查起来极其折磨。

## 六、把踩坑变成"技能"，别重复交学费

上面这些坑，最值钱的不是解决方案，而是**别踩第二次**。

我的做法：每个坑解决后，立刻固化成一个 WorkBuddy 技能（Skill）——里面写清楚**触发场景、验证过的命令、参数、以及为什么别的路走不通**。

判断一条经验值不值得写下来，就一句话：

> **如果换个人来做，他得从零再摸一遍 —— 那就值得写。**

举个反例：这次我花了不少时间在 `lxml` 上反复尝试（换轮子、换安装参数、反复重装）。这些尝试**在第一次失败后就注定无效**，但当时没有把"平台级不兼容"这个结论立刻固化，导致后面又绕了回去。

**固化之后，下一次会话开局就知道这条路封死了，直接绕行。**

## 七、小结：可复制清单

| 环节 | 结论 |
|---|---|
| **环境预检** | 先确认 libc（musl/glibc）、架构、Shell、`/tmp` 可写性——**90% 的坑在这里就有答案** |
| **装依赖** | `pip install` 成功 ≠ 可用；**装完立刻 `import` 验证** |
| **看清 ABI** | 比对 `sysconfig.get_config_var('EXT_SUFFIX')` 与轮子标签；`--platform` 不改 ABI |
| **止损信号** | 报错从"权限"变成"符号重定位"→ **平台级不兼容，立刻换路** |
| **读长文档** | 别用编辑器 API 逐段读；`.docx` = zip，直读 `word/document.xml` |
| **写 .docx** | 绕开重依赖链，用宿主本地 SDK：`create_doc → insert_markdown(file://…) → save_file` |
| **版式控制** | 模板不带页面属性时，"一页纸"靠**控字数**，不靠调参数 |
| **经验固化** | 踩过的坑写成可复用文档；**换个人要重摸一遍的，就值得写** |

---

**一句话总结**：用 WorkBuddy 在受限环境里干活，瓶颈往往不在模型，而在**你以为通用的那层依赖**。先画清环境，再选通道；能直读数据就别走重接口；每次踩坑都固化成技能——这三条比任何单点技巧都值钱。

环境：WorkBuddy 客户端 ＋ OpenHarmony / HarmonyOS（ohos-aarch64，musl libc）＋ Electron 沙箱 适用：需要在信创环境、移动端或受限沙箱里落地 AI Agent 的开发者

# WorkBuddy 跑在国产化 Linux 上：我把 .docx 处理的坑踩了个遍（附可复制代码）#WorkBuddy#

人工智能

在信创环境（ohos-aarch64/musllibc）部署AI Agent时，pip安装成功≠模块可用，需立即import验证ABI兼容性。长文档处理应直读docx内部XML而非调用编辑器API，生成文档则用WorkBuddy本地editorSDK。遇到"符号重定位"错误即平台级不兼容，需果断换方案。踩坑经验应及时固化为可复用技能。

代码解释

解释器

WorkBuddy 

Markdown

Python

Linux

JSON

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

prowork

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

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

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

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

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

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

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

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

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

社区新版编辑器体验调研

在信创环境（ohos-aarch64/musllibc）部署AI Agent时，pip安装成功≠模块可用，需立即import验证ABI兼容性。长文档处理应直读docx内部XML而非调用编辑器API，生成文档则用WorkBuddy本地editorSDK。遇到"符号重定位"错误即平台级不兼容，需果断换方案。踩坑经验应及时固...

# WorkBuddy 跑在国产化 Linux 上：我把 .docx 处理的坑踩了个遍（附可复制代码）#WorkBuddy#-腾讯云开发者社区-腾讯云

# WorkBuddy 跑在国产化 Linux 上：我把 .docx 处理的坑踩了个遍（附可复制代码）#WorkBuddy#

# WorkBuddy 跑在国产化 Linux 上：我把 .docx 处理的坑踩了个遍（附可复制代码）#WorkBuddy#

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐