> 作者 @zzzzzzzp（立意 · 判据 · 取舍） · 协作 多多 · AI 助手（检索 · 编码 · 核查）
> 版权 著作权归 @zzzzzzzp 所有（All Rights Reserved） · 版本 v1.4.1
万象-办公文档处理助手
读写与美化 Word、Excel、PPT 与 WPS 文件，并做在线文档协作与脱敏。
- 做什么：按四通道路由判该走本地件还是在线件，再打开-编辑-保存与脱敏。
- 何时用：要编辑本地办公文档、要新建一份文档，或要在在线文档上协作时。
- 不做什么：不做超出编辑器能力的排版；文档内容不出本机。
何时用
- 用户手里有本机 Office/WPS 文件（doc/docx/xls/xlsx/ppt/pptx/wps/wpt…）要读、要改、要另存。
- 用户要把内容做成在线可协作的形态：在线文档、结构化数据表、看板/汇报页。
- 用户要生成或美化演示文稿。
- 用户要把一份文档交付出去 / 发出去 / 参赛投出去 —— 先过本技能的交付双检。
不适用：网页开发与前端交付 → 走 万象-网页开发与验收；PDF 精排、印刷稿、出血与色彩管理 → 走交付线；纯文字创作 → 直接写。
§0 三条铁律
- 不重造编辑器。 本技能是判据与流程层，实际的打开/写入动作由平台编辑器执行。出现"编辑器做不到"时，先怀疑是调用姿势不对（见 §2），不要退化成"手搓文件格式"。
- 调用前先查 schema，不凭摘要猜参数。 编辑类工具的单个工具参数必须先查后调；凭记忆拼参数是最常见的一次性失败源。
- 交付前必过双检，且留证据。 脱敏扫描 + 格式一致性核对，两份报告落盘。没跑双检的交付物视为未完成，不以"我看过了"替代。
§1 四通道路由（先判走哪条，再动手）
| 输入形态 | 通道 | 关键动作 |
|---|---|---|
| 本机已有 doc/xls/ppt/wps 文件 | 本地件（§2） | 查 schema → 打开 → 编辑 → 保存（不主动关） |
| 已有内容、要求可协作/可分享/在线看 | 在线件（§3） | 建对应对象（doc / database / page / drive / link） |
| 数据（CSV / 粘贴 / 查询结果）要成表 | 表格优先（§4） | 先定表结构，再导入；不要先做静态表再返工 |
| 只是要交出去 / 发出去 | 交付双检（§6） | 脱敏 + 格式，双报告落盘 |
| 要做成可访问的网页链接 | 出界 | 转 万象-网页开发与验收 的发布线 |
判定口诀：用户说「我本地这个文件」→ 本地件；说「分享/协作/别人也能看」→ 在线件；说「交出去/发出去」→ 先双检。
§2 本地件：打开-编辑-保存
2.1 格式边界（先看这张表，别拿不支持的格式开工）
| 类别 | 可编辑 | 可打开但要注意 |
|---|---|---|
| 文档 | doc / docx / dot / wps / wpt | 含宏格式可打开，但宏不执行 —— 不要按"宏会跑"来设计流程 |
| 表格 | xls / xlsx / xlt / csv / tsv | — |
| 演示 | ppt / pptx / pps / pot | — |
| 不支持 | et / ett / dps / dpt | 遇到这些先转格式，别硬试 |
2.2 调用纪律
- 按类型分流调用：文档 / 表格 / 演示是三类不同的工具，不要互相混用。
- 先查 schema：调任一编辑工具前，先查它单个工具的参数定义。
- 保存即
save_file：保存用保存动作即可。 - 不要主动关闭文件：文件在编辑器中打开时用户实时可见（所见即所得）；主动关闭会打断用户查看。任务结束也不关，交给用户。
- 改动前先另存：涉及批量或结构性改动时，先复制一份再改（§7）。
2.3 读取优先于生成
用户给一份已有文件时，先把现有内容读全（含表格多 sheet、含批注与页眉页脚），再动手。最常见的翻车是"只读了第一页就开始重写"，把后面几页的内容丢掉。
§3 在线件：五类对象
| 对象 | 用来装什么 | 触发说法 |
|---|---|---|
| doc 在线文档 | 要协作编辑的长文 | 「一起改」「多人看」 |
| database 结构化数据表 | 行记录、要增删改查、要筛选 | 「建个表」「登记一下」「台账」 |
| page 数据/汇报页面 | 看板、dashboard、汇报页 | 「做个看板」「给领导看的」 |
| drive 网盘文件 | 附件、素材、要传要下 | 「传上来」「下载」 |
| link 网页链接 | 收藏外部页面 | 「存个链接」 |
| manage 空间管理 | 目录、权限、成员 | 「建个目录」「谁能看」 |
纪律：
- 要点名对象类型，不要让用户猜。 说清楚"我给你建的是数据表，不是文档"，因为两者后续能做的事完全不同。
- 数据一旦要"反复改、要筛、要统计"就选 database，不要用文档里的静态表格硬撑 —— 静态表第二次修改就要返工。
- 在线件与本地件不是二选一：常见正确解是「本地件定稿 → 同步一份在线件供协作」，此时两份的版本责任要讲明，避免双头维护。
§4 表格与数据
- 先结构后数据：列名、类型、必填、枚举值先定，再导数据。先灌数据再改结构 = 重来。
- 导入前先看编码与分隔符：CSV 的中文编码、TSV 的制表符、Excel 的合并单元格与多 sheet，是导入失败的前三名。
- 复杂筛选分步做：一句话里超过 3 个条件的筛选，拆成"先粗筛、再精筛"，并把每步结果落盘 —— 一次到位的黑箱筛选无法复核。
- 数值列不要混文本（"约 300"与"300"不能同列），否则排序与统计全错。
§5 演示文稿
- 先大纲后版式：每页一句论点，先定页序与每页论点，再进版式。直接排版会导致"页数很多但没有论证线"。
- 一页一论点，超过 3 行的正文考虑拆页或改成图示。
- 字体回退：目标机器可能没有你用的字体，交付前确认或改用通用字体族。
- 演讲者备注与页面内容分开，不要把讲稿塞进正文。
§6 交付前双检（本技能的核心增量）
平台件教你"怎么编辑"，没人告诉你"交出去之前要查什么"。这一节是本技能存在的理由。
检① 脱敏扫描
python scripts/doc_sanitize.py --path <文件或目录> [--words <词表.txt>] [--json <报告.json>]
内置判据：手机号、身份证号、邮箱、座机、本机用户名路径（C:\Users\<名> / /Users/<名>）。
自定义词表：一行一词，用来扫真实项目名、甲方名、设计公司名、人名 —— 这些无法靠正则识别，只能靠词表。
词表纪律：词表本身含敏感词 ⇒ 词表放在技能目录之外（如 ~/.workbuddy/omni-project-rules.json 同级的私有位），不得随技能一起分发。
检② 格式一致性
| 项 | 查什么 |
|---|---|
| 字体 | 全文是否只用 1–2 个字体族；有无回退风险字体 |
| 编号 | 标题层级编号是否连续、有无跳级 |
| 页眉页脚 | 是否残留上一版的项目名/日期/版本号 |
| 页码 | 是否有、是否从封面开始计数 |
| 空白与分页 | 有无孤立标题、有无跨页断表 |
| 元数据 | 文档属性里的作者/公司/修订记录（外发必查，这是最常见的泄露点） |
证据
两份报告与交付物一起落盘，路径写进交付说明。双检不过不交付；确需带风险交付时，把风险点与决策人、时间明确写进交付说明，不留"以为没问题"。
§7 批量与版本纪律
- 命名模板：
<类型>_<对象>_<版本>_<日期>，版本用v1/v2而非最终版/最终版2。 - 原件不动：批量处理一律「复制 → 改副本 → 校验 → 替换」，源文件保留到用户确认。
- 幂等：批量脚本重复跑结果一致；写前先查唯一标记，已处理则跳过。
- 改完即回读：写盘后立刻读回校验（不是"应该写好了"）。
§8 本机实测坑
- 含宏的文档别当"能跑" —— 可打开，但宏不执行，流程里不要依赖宏。
et / ett / dps / dpt一律先转格式，硬试只会浪费时间。- 编辑中的文件不要主动关闭，用户可能正在编辑器里看着。
- 列表/表格类对象在排序时可能不出现"生成"选项 —— 先排序、再生成，顺序反了就得重来。
- 文件属性是隐私盲区：正文脱敏了，
作者字段还写着真名。外发前必查（§6 检②）。
§9 能力边界与反例
能做：路由判据、编辑调用纪律、在线件对象选型、表格结构设计、演示结构、交付双检、批量与版本纪律。
不做：
| 反例 | 正确去处 |
|---|---|
| 前端页面开发与效果验收 | 万象-网页开发与验收 |
| PDF 精排、印刷出血、色彩管理 | 交付线 / 印前 |
| 真实项目资料直接外发 | 先双检；外发件一律虚拟名 |
| 靠正则识别"真实项目名" | 正则做不到 —— 用词表（§6 检①） |
§10 工具实操纪律（2026-09-21 吸收自平台件的判定条目）
> 来源：平台内置的本地 Office 编辑件与资料库件。只取操作性判据，文字为自有表述，不引其正文。
本地件三条（对 §2 的补充）
- 要让用户在预览面板看到文件，必须走「呈现给用户」那一步。 后台打开动作只把文件读进编辑器内存，不会在面板里显示 —— 只在回复里说「已打开」不算数。
- 呈现之后不要再做一次默认打开。 呈现动作本身已注册编辑器实例；此时应按路径查实例表取
file_id（或从用户当前选区取），再直接编辑。重复默认打开会造出第二个实例，后续编辑落到哪个实例上就不确定了。 - 实例的 key 不一定是路径。
file_id是编辑器实例表里的键，不要拿路径去猜它；拿不到就先走「按路径查实例表」这条路。
资料库两条（对 §3 的补充）
- 失败先分流错误码，再决定动作。 「权限不足」「找不到对象」「频率受限」三者的下一步完全不同（申请授权 / 换目标 / 稍后重试），不要把三种混成一句「调用失败了」。
- 远端可能已被改动。 基于上一次读取做写入之前，先确认远端版本有没有变；变了先重读再改，否则会覆盖别人的修改。
证据：判据取自平台件的硬约束条目（呈现而非后台打开 / 不重复默认打开 / 保存后不主动关闭 / 按需查 schema / 错误码分流 / 远端变更防护），文字为自有表述。
常见误用与常见问题（FAQ）
常见误用（反模式）
| 误用 | 后果 | 正解 |
|---|---|---|
| 文档／表格／演示工具混用 | 操作错通道 | 按类型分流调用 —— 三者是三类不同的工具，不要互相混用 |
| 出现「编辑器做不到」就退化成「手搓文件格式」 | 重造编辑器 | 本技能是判据与流程层，实际动作由平台编辑器执行；先怀疑调用姿势不对（见 §2），不重造编辑器 |
| 数据要反复改／要筛／要统计，却用文档里的静态表格硬撑 | 静态表第二次修改就要返工 | 选 database |
| 把讲稿塞进正文 | 内容混乱 | 演讲者备注与页面内容分开 |
| 编辑中的文件主动关闭 | 打断用户查看（所见即所得） | 不要主动关闭；任务结束也不关，交给用户 |
| 含宏的文档当「能跑」 | 宏不执行 | 可打开，但流程里不要依赖宏 |
| 数值列混文本（「约 300」与「300」同列） | 排序与统计全错 | 数值列不要混文本 |
| 把三种错误混成一句「调用失败了」 | 下一步动作完全不同 | 先分流错误码：「权限不足」「找不到对象」「频率受限」三者下一步不同（申请授权／换目标／稍后重试） |
| 呈现之后再做一次默认打开 | 造出第二个实例，后续编辑落到哪个实例上就不确定 | 按路径查实例表取 file_id（或从用户当前选区取），再直接编辑 |
| 拿路径去猜实例的 key | 猜不到 | 实例的 key 不一定是路径 —— file_id 是编辑器实例表里的键；拿不到就先走「按路径查实例表」 |
| 不讲对象类型 | 用户误解后续能做什么 | 要点名对象类型，不要让用户猜 —— 说清「我给你建的是数据表，不是文档」 |
| 词表随技能一起分发 | 泄漏敏感词 | 词表本身含敏感词 ⇒ 词表放在技能目录之外（如与 ~/.workbuddy/omni-project-rules.json 同级的私有位） |
常见问题
- Q：走哪条通道？ A：先走「§1 四通道路由（先判走哪条，再动手）」。
- Q：格式支持边界在哪？ A：见「§2.1 格式边界」—— 别拿不支持的格式开工。
- Q：该读还是该生成？ A：见「§2.3 读取优先于生成」。
- Q：交付前要检什么？ A：见「§6 交付前双检（本技能的核心增量）」—— 检① 脱敏扫描 ＋ 检② 格式一致性 ＋ 证据。
- Q：有哪些本机实测坑？ A：见「§8 本机实测坑」与「§10 工具实操纪律」。
- Q：本技能不覆盖什么？ A：见「§9 能力边界与反例」。
附 · 来源交代
| 项 | 说明 |
|---|---|
| 版本 | 1.0.0 |
| 建立日期 | 2026-09-19 |
| 来源 | 自研（origin: own）。建立动机：平台内置的 library（资料库）、tencent-docs-routing、tencent-local-office-edit 三部系统技能覆盖了本域的操作面，但①同为版本目录结构、随平台升级整体替换，本机经验无处沉淀；②都不含"交付前"这一环。故按功能域合并自研一部，只吸收能力类别与格式边界事实，不复制其文本；§6 交付双检、§7 批量与版本纪律、§8 本机实测坑为本技能自有的增量。 |
| 与系统件的关系 | 并存，不替换。系统件仍负责实际的编辑器调用；本技能负责路由判据、调用纪律与交付验收。 |
| 著作权 | 署名 zzzzzzzp，All Rights Reserved |
附 · 付费与授权
§〇 · 本技能定位为付费技能（Pay Skill）
| 项 | 内容 |
|---|---|
| 定位 | 付费版（Pay Skill 通道） |
| 计费形态 | 按次 |
| 已接入的服务 | serviceId API_13DCD6D650224B51 ｜ 服务地址 https://wb-workbase.app.workbuddy.host/demo/a2m/resource（无凭证时返回 402 ＋ Payment-Needed 账单）｜ 单价 0.25 元/次 |
| 🔴 单价须与注册价一致 | 平台明确警告：实际支付价与注册标价不一致会导致用户无法支付 ⇒ 向导里单价填 0.25，不要凭手感改 |
| 这条服务是复用的 | 服务名称是通用的「万象skill」，属同一作者、同一 appId ⇒ 与「万象-支付宝AI付接入」「万象-SkillHub自动上架」共用同一条已注册服务，不另注册 |
| 标识 | 付费技能加一道金色光圈（GOLD = #C8A02C）—— 判据＝该技能被调用时按次收费 |
> 🔴 付费技能一律走完整付费路径 —— 是付费定位，就照着付费通道做完：
> 随包实现 402 链路（见 §〇·2）、接入相应服务、按注册价填单价、走 Pay Skill 向导。
> 不回头讨论「要不要改成免费」。若确实要转免费，改的是 万象标识体系/tools/gen_icons.py 的
> PAY_SKILLS 名单与本段声明（显式改动），不是偷偷少做一步。
§〇·1 · 数据边界与外部连接（如实声明）
| 项 | 事实 |
|---|---|
| 文档正文的处理位置 | 全部在本机完成。读写 .docx / .xlsx / .pptx / .wps 与脱敏都在用户自己的机器上跑，文档内容不出本机 |
| 唯一的外部连接 | 仅支付链路的校验与履约两个动作会访问上面的服务地址（…/demo/a2m/resource），请求体只含订单标识与验付要素，不含文档内容 |
| 本机读写范围 | 仅限用户显式指定的文件及其所在目录；不遍历用户目录、不读取与任务无关的文件 |
| 凭据来源 | 支付宝相关密钥由用户自行放入环境变量（config.js 只读白名单内的键），不写入包内、不落盘、不打日志 |
| 订单存储 | 订单幂等记录写在本机 a2m/ 目录下的本地库中，不上传任何订单数据 |
| 不做什么 | 不上传用户文档、不外发内容、不采集行为数据 |
§〇·2 · 随包提供的 402 付费链路实现（平台「付费改造」检测就看这个）
🔴 实测判据（平台原话）：SkillHub 在提交时会做一次「支付宝付费改造」检测，
判据是技能包内是否存在 402 支付链路的实现，缺失项会被逐条列出：
> 「缺失项：402账单下发 / 携带凭证重试 / 验付调用 / 履约确认 / 订单持久化与幂等」
> 「该检查不阻断提交。提交后平台审核仍会重新做一次完整检测，若不合规将被拒绝。」
⇒ 本包自带该实现（目录 a2m/，零密钥、可直接 npm install && npm start）：
| 平台检测项 | 本包对应实现 | 位置 |
|---|---|---|
| 402 账单下发 | 无凭证 ⇒ HTTP 402 ＋ Payment-Needed（Base64URL 账单，商户本地 RSA2 签名） |
a2m/a2m.js buildPaymentRequired()；路由在 a2m/server.js |
| 携带凭证重试 | 解析 Payment-Proof 头并重放同一资源请求 |
a2m/a2m.js decodePaymentProof() |
| 验付调用 | 查询交易并逐项严格比对（trade_no / 金额 / 资源 ID / 订单状态与时效） | a2m/a2m.js verifyPayment() |
| 履约确认 | 交付后调履约确认；失败可重试且不重复生成资源 | a2m/a2m.js confirmFulfillment() |
| 订单持久化与幂等 | SQLite 事务 ＋ 唯一约束（非内存订单）；重复交付不重复扣费 | a2m/orderRepository.js prepareFulfillment() |
配置边界（有意为之，勿改成「能跑就行」）：配置缺失即明确失败（资源路由返回 503），
不构造 SDK、不使用占位密钥、不提供任何跳过验付的路径。密钥只走运行环境变量或本地配置文件，永不入包。
cd a2m && npm install && npm run smoke # 冒烟：账单结构 / RSA2 签名 / 幂等边界
npm start # 默认 http://localhost:3000/demo/a2m/resource
