红豆写作助手安装与使用指南
当前版本：1.0.0.3
适用对象：红豆写作助手终端用户、Microsoft 365 管理员及内部测试人员
更新日期：2026-08-09
1. 插件简介
红豆写作助手是一款运行在 Microsoft Word 或 WPS 文字任务窗格中的云端科研写作插件，主要提供以下能力：
- 检索红豆个人文库、群组文库及其文件夹中的文献；
- 插入、编辑、刷新和移除动态引文；
- 根据文档中的动态引文生成并更新参考文献表；
- 检索红豆云端笔记并插入文档；
- 对选中的普通正文执行学术润色、改写和翻译；
- 在支持的宿主中把 AI 结果安全地替换回原选区。
插件是独立的云端客户端，不需要安装或启动红豆桌面客户端。安装包只负责向 Word 注册插件清单，界面、功能和引文样式由红豆云端提供，因此使用时必须保持网络连接。
生产环境任务窗格地址为：
https://openneweb.inoteexpress.com/word-addin/taskpane.html
2. 使用前准备
2.1 必备条件
- 一个可正常登录的红豆账号；
- 可访问红豆云端服务的网络；
- Microsoft Word 2016 或更高版本，推荐使用最新 Microsoft 365 桌面版；
- 或项目当前支持的 WPS 文字桌面版（WPS 安装目前主要用于开发和内部测试）；
- 安装和卸载前保存文档并完全退出 Word/WPS。
2.2 Word 功能兼容性
| Word 能力 | 可用功能 |
|---|---|
| WordApi 1.4 及以上 | 文献和笔记检索、AI 生成、AI 安全替换、动态引文、参考文献表 |
| WordApi 1.1–1.3 | 文献和笔记检索、AI 生成与复制；不支持动态引文和自动替换 |
| 低于 WordApi 1.1 | 不支持当前插件，请升级 Word |
Word 2016/2019 的具体 API 能力会因安装渠道和更新版本而异。插件会在启动时自动检测，并在任务窗格中显示兼容提示。
2.3 网络要求
如果单位使用防火墙、代理或域名白名单，请确保至少可以通过 HTTPS 访问：
openneweb.inoteexpress.com：插件页面、清单、图标和内置引文样式；zapi.inoteexpress.com：登录、文库、笔记及 AI 服务数据。
3. 安装 Microsoft Word 插件
请选择一种安装渠道。不要在同一台电脑上同时安装 Microsoft 365 统一部署版和本地安装包版；切换渠道前应先完全退出 Word 并卸载原有注册。
3.1 Microsoft 365 管理员统一部署（推荐）
此方式适合单位批量部署，也适合 Windows 与 macOS 混合环境。
- 获取正式安装包中的
manifest.xml。 - 使用管理员账号进入 Microsoft 365 管理中心。
- 进入“设置”→“集成应用”。
- 选择“上传自定义应用”或“部署加载项”，上传
manifest.xml。 - 将插件分配给指定用户或用户组。
- 等待 Microsoft 365 完成分发。
- 用户完全退出并重新启动 Word。
- 在 Word 的“引用”选项卡中，选择“红豆写作”→“打开写作助手”。
组织策略可能导致分发延迟。如果入口没有立即出现，请等待管理员部署状态生效后再重启 Word。
3.2 Windows 单机安装
- 将收到的 ZIP 安装包完整解压到普通文件夹，不要直接在压缩包预览窗口中运行文件。
- 保存文档并完全退出 Word；如有必要，在任务管理器中确认不存在
WINWORD.EXE。 - 双击
install-windows.cmd。 - 如果系统检测到 Word 2016/2019、MSI 或旧批量许可环境，请允许管理员授权，以配置兼容的共享文件夹目录。
- 安装完成后按窗口提示重新启动 Word。
- 对于 Microsoft 365、Office 2021/2024 等现代版本，在“引用”→“红豆写作”中打开插件。
- 对于提示使用兼容目录的版本，首次安装后进入“插入”→“我的加载项”→“共享文件夹”，添加红豆写作助手；以后可从“引用”选项卡打开。
安装器会生成诊断文件：
%LOCALAPPDATA%\Hongdou\WordAddin\install-diagnostics.txt遇到安装问题时，请保留该文件。企业安全策略或 SmartScreen 阻止脚本时，不要关闭安全软件，优先请 Microsoft 365 管理员统一部署。
如果发布方同时提供了 .zip.sha256 文件，可在 PowerShell 中校验安装包完整性：
Get-FileHash .\Hongdou-Word-Addin-v1.0.0.3-YYYYMMDD.zip -Algorithm SHA256将输出值与 .sha256 文件中的哈希值比较，两者应完全一致。
3.3 macOS 单机安装
- 完整解压安装包。
- 保存文档并完全退出 Microsoft Word。
- 双击
install-macos.command。 - 如果 macOS 阻止运行，请右键该文件，选择“打开”，再确认运行。
- 安装完成后启动 Word。
- 在“引用”→“红豆写作”→“打开写作助手”中打开任务窗格。
也可以在终端进入安装包目录后运行：
./install-macos.command清单默认安装到：
~/Library/Containers/com.microsoft.Word/Data/Documents/wef/HongdouWritingAssistant.xml3.4 直接上传清单
如果 Word 或 Office 网页端显示“我的加载项”→“上传我的加载项”，可以选择安装包中的 manifest.xml。仅双击 XML 文件本身不能安装插件。
4. 首次启动与登录
打开任意 Word 文档。
在“引用”选项卡中点击“红豆写作”→“打开写作助手”。
等待插件恢复已有云端会话；没有有效会话时会显示登录页。
选择一种登录方式：
- 密码登录：输入手机号、邮箱或账号以及密码；
- 验证码登录：输入手机号，获取并填写验证码。
阅读并勾选《红豆写作助手隐私政策》，然后点击登录。
没有账号时，点击登录页的“注册红豆账号”；遇到问题可点击“帮助与支持”。
隐私政策：https://openneweb.inoteexpress.com/word-addin/privacy.html
帮助与支持：https://www.inoteexpress.com/support/
- 登录成功后，任务窗格会显示“文献”“笔记”“AI 写作”三个页签。
任务窗格右上角会显示当前红豆用户名。点击“退出登录”会清除当前插件会话及当前界面中的检索/生成结果，但不会删除已经写入文档的内容。
5. 检索文献并插入动态引文
5.1 查找文献
- 打开“文献”页签。
- 从顶部下拉框选择“我的文库”、群组文库或具体文件夹。
- 在检索框输入标题、作者、年份或 DOI，点击“检索”。输入为空时点击按钮会刷新当前范围。
- 也可以把光标放在目标段落中，点击“段落检索”。插件会读取当前段落，并使用最多前 500 个字符查找相关文献。
- 使用结果列表底部的上一页/下一页浏览，每页显示 20 条。
5.2 插入一条或组合动态引文
把 Word 光标放在需要插入引文的位置。
在文献列表中勾选一篇或多篇文献。多选会组成一条组合引文。
点击底部的“设置并插入”。
选择引文样式。当前插件内置 4 个基础样式，并打包了 388 个可搜索的期刊、高校及其他 CSL 样式：
- GB/T 7714-2015（顺序编码）；
- GB/T 7714-2015（著者-出版年）；
- APA 7th（著者-年份）；
- Vancouver（顺序编码）。
按需为每篇文献单独设置：
- 定位类型，如页码、章节、图、表、段落等；
- 页码或位置，例如
12–15； - 前缀和后缀；
- “隐藏作者”，适用于作者已经写在正文中的情形。
可用上移、下移按钮调整组合引文中的文献顺序。
点击“插入动态引文”。
文档已经存在动态引文时，新引文会沿用文档当前样式。若要更换整个文档的样式，请在“文档引文”管理界面中选择样式并刷新全部引文。
5.3 管理已有引文
点击文献页顶部的“文档引文”可执行以下操作：
- 编辑光标处引文：把光标放入红豆动态引文，再修改文献组合、顺序、定位信息、前后缀等；
- 移除光标处引文：删除该动态引文，并重新计算后续编号；
- 刷新全部引文：按文档中的实际顺序重新渲染全部动态引文；
- 切换样式：从下拉框或“更多样式”中选择，再刷新全部引文；
- 插入/更新参考文献表：首次插入时默认放在文档末尾，此后可随引文一起更新；
- 取消链接全部引文：保留当前显示文字，但移除全部动态能力。
“取消链接全部引文”不可恢复。操作前建议另存一份文档副本。取消链接后，引文和参考文献表不能再编辑、刷新或切换样式。
5.4 脚注和尾注样式
当所选 CSL 样式属于注释体时，编辑器会显示“脚注/尾注”选项。是否可选由当前 Word 版本在启动时的能力检测结果决定；不支持时请改用正文引文样式。
6. 检索并插入笔记
- 打开“笔记”页签。
- 选择个人文库、群组文库或具体文件夹。
- 输入标题或正文关键词并点击“检索”；关键词为空时可刷新当前范围。
- 在结果中确认笔记标题、内容预览、更新时间和所属群组。
- 将光标或选区放在目标位置，点击“插入到当前位置”。
笔记正文会插入到当前选区之后。笔记列表每页显示 20 条。
7. 使用 AI 写作
7.1 支持的操作
- 学术润色：在不改变原意和原文语言的前提下改善语法、措辞、逻辑衔接和可读性；
- 改写：保持论点、事实和专业含义，用更规范、严谨的方式重新表达；
- 翻译：可选择中文、英语或日语作为目标语言。
单次所选正文不能超过 20,000 个字符。AI 写作会显示当前可用 Token 和本次消耗 Token。
7.2 操作步骤
在 Word 中选择一段普通正文。
打开“AI 写作”页签并选择“学术润色”“改写”或“翻译”。
如选择翻译，再选择目标语言。
点击“读取所选正文并生成”。
生成过程中可以点击“停止生成”。
生成结束后先审核结果；结果文本可以在任务窗格中继续编辑。
根据需要执行：
- “重新生成”；
- “复制”，再手动粘贴到文档；
- “替换 Word 选区”，用结果替换原文。
7.3 安全限制
在具备完整安全检查能力的 Word/WPS 环境中，为避免损坏文档结构，插件会拒绝自动处理或替换以下选区：
- 红豆动态引文或参考文献表；
- Word 动态字段；
- 其他 Content Control（内容控件）；
- AI 生成期间已经发生变化的选区。
在基础兼容模式下，插件只提供生成、编辑和复制，不显示自动替换能力。请复制结果后手动粘贴。
AI 输出可能存在错误。涉及数据、公式、专有名词、事实和参考文献时，应在写入或提交文档前人工核对。
8. 文档保存、共享与数据说明
- 动态引文、参考文献表状态和安全的 CSL 缓存会随文档保存；关闭再打开文档后可继续刷新和编辑。
- 文档只保存稳定的文献引用信息、渲染结果和引文状态，不保存红豆账号密码或 API 凭据。
- 登录后的插件拥有个人文库和笔记的只读访问权，以及用户有权访问的群组文库只读权限；不会通过插件修改云端文献。
- 将含动态引文的文档交给未安装插件的用户时，对方仍可阅读当前显示文字，但不能刷新或编辑红豆动态引文。
- 交付最终稿前如需彻底固定版面，可先保存副本，再使用“取消链接全部引文”。
插件业务页面采用云端部署，通常会随服务端发布自动更新，无需为每次界面或功能更新重新运行本地安装器。只有清单、加载项 ID、权限、入口等安装级配置发生变化，或管理员要求切换分发渠道时，才需要重新部署或安装。
9. 常见问题
9.1 Word 中没有“红豆写作”入口
- 确认安装前后都完全退出过 Word，而不只是关闭文档窗口。
- Windows 用户查看
%LOCALAPPDATA%\Hongdou\WordAddin\install-diagnostics.txt。 - Word 2016/2019 用户按安装提示进入“插入”→“我的加载项”→“共享文件夹”完成首次添加。
- 统一部署用户请让管理员确认应用已分配给当前账号，并等待部署生效。
- 企业设备若禁止本地加载项注册，请改用 Microsoft 365 管理员统一部署。
9.2 任务窗格空白或无法连接
- 在浏览器打开生产环境任务窗格地址，确认网络和 HTTPS 证书正常。
- 确认防火墙/代理没有阻止本指南“网络要求”中的域名。
- 完全退出并重启 Word。
- 仍无法使用时，记录发生时间、操作系统、Word 完整版本和页面提示。
9.3 登录失败或频繁要求重新登录
- 确认账号、密码或短信验证码正确；
- 验证码发送后需等待 60 秒才能再次获取；
- 会话失效时退出登录并重新登录；
- 若网页登录也失败，请先处理红豆账号或网络问题。
9.4 能检索文献，但不能插入动态引文
当前 Word 很可能只支持 WordApi 1.1–1.3。查看任务窗格中的兼容提示并升级 Word。动态引文要求 WordApi 1.4。
9.5 动态引文编号或参考文献表不正确
- 打开“文档引文”。
- 点击“刷新全部引文”。
- 再点击“更新参考文献表”。
不要直接改写动态引文内容。应把光标放入引文后使用“编辑光标处引文”。
9.6 AI 结果不能替换选区
- 确认生成期间没有移动光标或修改选区；
- 只选择普通正文，不要包含动态引文、字段或内容控件；
- 基础兼容模式不支持自动替换，请使用“复制”。
9.7 图标或名称仍是旧版本
完全退出 Word，等待数分钟后重新启动。统一部署环境还需等待 Microsoft 365 更新同步。不要手工修改 manifest.xml，否则可能导致清单校验或安装失败。
9.8 反馈问题时应提供什么
- 操作系统及版本；
- Word/WPS 的完整版本号和安装类型；
- 插件版本（本指南对应 1.0.0.3）；
- 问题发生时间、操作步骤及是否稳定复现；
- 页面错误提示、截图或录屏；
- Windows 本地安装用户的
install-diagnostics.txt。
10. 卸载
10.1 Microsoft 365 统一部署
由管理员在 Microsoft 365 管理中心的“集成应用”中取消用户分配或删除应用。用户完全退出并重启 Word 后生效。
10.2 Windows 单机安装
- 保存文档并完全退出 Word。
- 双击安装包中的
uninstall-windows.cmd。 - Word 2016/2019 兼容安装可能再次请求管理员授权，以移除受信任目录和插件专用共享。
- 重新启动 Word。
卸载器只移除红豆写作助手自身注册和由它创建的兼容资产，不会删除 Word 文档或云端数据。
10.3 macOS 单机安装
完全退出 Word 后双击 uninstall-macos.command。若被 macOS 阻止，可右键选择“打开”，或在终端运行：
./uninstall-macos.command也可手动删除：
~/Library/Containers/com.microsoft.Word/Data/Documents/wef/HongdouWritingAssistant.xml11. WPS 文字安装说明（开发/内测）
当前项目已经实现 WPS 文字宿主，支持文献、笔记、AI 安全替换、动态引文、脚注/尾注及参考文献表。但正式的可分发 ZIP 和终端用户安装脚本目前以 Microsoft Word 为主；WPS 注册方式适合从项目源码进行开发或内部测试。
在项目根目录安装依赖后执行：
npm install
npm run install:wps-addin:prod完全重启 WPS 后，从红豆写作助手功能区按钮打开任务窗格。卸载生产注册：
npm run uninstall:wps-addin:prod安装脚本会更新 WPS 的 jsaddons/publish.xml，保留其他插件记录，并在修改前备份原文件。默认注册位置为：
| 系统 | 默认目录 |
|---|---|
| Windows | %APPDATA%\kingsoft\wps\jsaddons |
| macOS | ~/Library/Containers/com.kingsoft.wpsoffice.mac/Data/.kingsoft/wps/jsaddons |
| Linux | ~/.local/share/Kingsoft/wps/jsaddons |
12. 开发和发布附录
以下内容仅供本项目开发及发布人员使用。
12.1 本地 Word 开发（macOS）
npm install
npm run install:word-addin:dev
npm run dev:test:https随后重启 Word，在“引用”→“红豆写作（开发）”→“打开本地写作助手”中打开。Word 拒绝 HTTP 任务窗格，因此 Office.js 调试必须使用 dev:test:https 或 dev:prod:https。
12.2 验证与打包
# 清单、版本、CSL、Word 逻辑、组件和类型检查
npm run verify:word-addin
# 完整生产发布检查
npm run verify:word-addin:release
# 部署生产站点后生成可分发 ZIP 和 SHA-256 文件
npm run package:word-addin生产清单的源码是 word-addin/manifest.production.xml。打包命令会验证线上清单与仓库一致，并检查线上任务窗格可访问。版本发布时还需同步更新 src/apps/word-addin/version.js，确保 Word/WPS 清单、界面和客户端元数据使用同一个四段式版本号。
Microsoft Marketplace/AppSource 发布字段、认证备注和逐项检查表位于 word-addin/marketplace/。商店只上传生产 manifest.xml，本地安装 ZIP 不作为商店程序包上传。提交前还必须准备无个人信息的真实 Word 截图，并把审核账号密码仅填写到 Partner Center 的私密认证备注中。
完整发布顺序和 Partner Center 操作见 word-addin/RELEASE-GUIDE.md。
