项目协作导航

docs/ 为维护者本地资料，不随 GitHub 仓库提供；下文本地资料路径仅供已有资料时参考，不是构建或使用前提。

从任务找入口

先读本文件，再读目标目录 AGENTS.md，随后只搜索该目录和下表关联文件。局部证据不足、入口不存在或问题跨模块时再扩大搜索，并说明新的调查范围。不要以全项目扫描、读取全部规范作为默认起点。局部规范补充本文件，不重复共性规则。

其他目录：docs/ 仅在本地保存架构和验证说明；prompts 放运行时提示词；build 和 resources 的图片为打包素材。它们沿用根规范。发布包的代码保护（sourcemap 排除、V8 字节码、验证脚本）见 code-protection.md（本地 docs/code-protection.md）；发布专用副本由 build-release-assets.mjs 生成到 dist/release-app/，只在该副本做混淆，业务源码和技能原稿保留。品牌声明与检查范围见 branding.md（本地 docs/branding.md），插件侧栏与后台运行范围见 addon-background.md（本地 docs/addon-background.md）。当前架构参考 architecture.md（本地 docs/architecture.md），主入口配置为 package.json 和 tsup.config.ts。

阶段验收证据按候选标识存放在 docs/acceptance/<候选标识>/，至少包含基线指纹、工具契约快照、环境清单与兼容性差异；只写"已完成"而没有对应证据的条目视为未完成。

证据材料要能被下一个会话直接使用：恢复类材料把锚点（提交 SHA、版本号）写进元数据文件，不要绑定会变化的 HEAD；脚本路径从仓库根目录解析，不写个人目录；修复前复现用临时副本，不要覆盖当前工作区。

加载项部署入口为生成物（改造计划 P3.4/P3.5）：wps-addon/addon-core.js 由 npm run build:wps-addon 从 wps-addon/src/** 生成，office-addon/public/taskpane.js 由 npm run build:office-addon 从 office-addon/src/** 生成；两者顶部都有"请勿手改"注释。改源码后重新构建，禁止手改生成物掩盖源码问题；从干净目录（删除生成物后）执行 npm run build:addons 必须能重建并通过测试。

生成物 dist/、release/、website/dist/、上述两个加载项入口和依赖 node_modules/ 不作为修改入口，也不维护 AGENTS.md——唯一例外是 release/AGENTS.md：它约束产物仓库"每个版本只保留一套构建物"（mac 留 .app、首次安装 DMG 及在线更新 ZIP，win 留首次安装 EXE 及在线更新 ZIP），check:agents 跳过 release/ 目录，该文件只在清理与发布时适用。开发编译在 dist/，发布包按 release/<版本>/<平台>/ 存放；改源文件后通过构建更新，禁止手修产物掩盖源码问题。

本地开发与版本交付

默认以维护者的本地工作区完成开发和发布。接手版本任务时，先读本地 docs/release-workflow.local.md，再按其中入口核对 docs/release-policy.md、docs/update-operations.local.md 和 UPDATES.md。已有本地资料直接沿用，不为一次交付另建一套发布体系。

• 版本以 package.json 为准；已确认的新版本用 npm run version:set -- <版本> 同步声明，随后检查版本一致性。安装包、程序 ZIP、签名清单的版本必须对应。
• Windows 可在 Mac 交叉构建，不要求验收机先搭编译环境。Windows 实机负责运行验收；Mac/Windows 的构建通过不能互相冒充实机通过。
• Windows 每版保留首次安装 EXE 与完整程序 ZIP；在线更新只使用 ZIP。Mac 保留应用及在线 ZIP。独立助手切换版本并保留旧目录，不把安装向导接回在线更新。
• 构建和签名沿用 scripts 的现有入口。实际服务器目录、既有签名材料位置、机器相关操作、当前验收/发布状态与清理记录只写本地 docs；通用职责、参数和命令放本文件、UPDATES.md 或就近目录规范。
• 已有通过证据且实现未改变时，复用该证据，完成本次构建/包校验即可，不自动重开完整实机验收。影响正常使用或数据安全的问题处理；其他小瑕疵记录，不自动扩大范围。
• 清理只针对已识别的重复/作废生成物，先保存大小、哈希、来源与引用关系；不把正式当前包、回退版本、验收记录、源码或用户数据当作临时产物。

改造任务入口

涉及模块化、契约统一及双平台验收的改造，已有本地资料时先读改造计划与执行台账（本地 docs/refactoring-plan.md），按当前阶段与任务 ID 继续；WPS 领域分片的进一步拆分见模块化方案与执行清单（本地 docs/modularization-plan.md）。计划内保留完成清单、验收标准和交接备忘。

协作与变更边界

使用简体中文。明确的小需求直接实施；架构、产品行为或明显扩大的范围先讨论。既定方向内的工程细节自主完成。先看 git status/diff，保留用户及其他任务的修改；不自动提交、推送、部署或清理数据。

界面、CLI、MCP 与宿主加载项职责分离。专用工具缺失不代表宿主不能做，先检查原生脚本路径。操作真实文件须在任务授权范围内，不能把测试脚本当成无副作用检查。

验证与交付

按修改范围选择检查：package.json 中的 npm run typecheck、npm test、npm run build；官网使用 npm run build:website；导航使用 npm run check:agents，品牌使用 npm run check:brand，版本一致性使用 npm run check:version（构建、打包与 CI 门禁）。发布统一遵循 版本与发布制度（本地 docs/release-policy.md），已正式发布版本不得覆盖包或移动标签。局部测试见模块规范，不为纯文档改动启动办公软件。

模拟测试、构建、真实宿主验证分别报告，不能互相替代。失败时区分本次回归、既有缺陷与环境限制，保留原始证据；不为通过检查顺手改无关模块。最终说明完成内容、主要文件、验证及遗留问题。

文档随代码维护

新增/移动/删除关键文件，改变职责、调用链、接口、命令或验证路径时，在同一次修改中更新根导航或最近的 AGENTS.md。普通函数内部变化无需制造文档更新。收尾检查：导航是否仍能定位、联动是否完整、避坑条目是否仍成立，再运行导航检查。

避坑条目格式为“触发条件 → 错误做法 → 已证实原因 → 正确做法 → 验证/证据”。高频关键条目就近写在模块规范，长案例才放本地 docs/ 并注明本地资料路径，不生成公开失效链接。只记录已证实且可复用的经验；猜测留在调查结果里。能回归的问题优先补测试，文档解释原因。修复使旧限制失效时更新或删除条目，不保留永久禁令。

不要记录凭据、用户文档内容、临时版本状态、个人路径或易失效行号。检查脚本只能确认导航结构与路径，职责和经验是否正确仍需修改者核对。跨模块并行工作只有获准后开展，先分配文件归属与接口边界。