wauxiliary-plugin-dev

# WAuxiliary 插件开发 以当前 WA 文档和运行时源码为准。同版本插件可以参考写法，但不能代替接口文档。涉及 Hook、广播或任务时，插件卸载后不能留下仍在运行的内容。 ## 任务边界 - 默认用中文回复，保留代码、路径和 API 原名。讨论、原因诊断和审核先给分析与证据；只有用户明确要求实施或确认方案后才修改代码。要求给出文件内容时直接提供内容，要求落地时才编辑目标目录。 - 检查、清理或审核先看 `git status --short`、`git diff` 和 `git diff --cached`，并读取相关未跟踪文件。有未提交改动时，以这些改动及必要的上下游为范围；只有工作区干净或用户明确要求，才扩到整个项目。用户已给出待审 diff 或片段时，以其为准。 - 已授权的范围内直接执行；下面的确认只针对尚未确定、会影响实现的选择或范围扩大，不重复询问已确认事项。不顺手重构、不主动创建 Git 提交。 ## 执行流程 | 阶段 | 操作 | 检查标准 | |---|---|---| | 1. 明确需求 | 按任务边界确定只读分析或实施、目标目录与 WA 版本；按 [workflow.md](references/workflow.md) 整理本次涉及的触发条件、会话、动作、配置、失败反馈和卸载行为。 | 得到与请求范围一致、可直接检查的完成标准。 | | 2. 核对接口 | 按 [repository-map.md](references/repository-map.md) 定位资料，从 [API 索引](references/api/INDEX.md) 读取本次实际涉及的回调、签名和字段。 | 每项 WA 调用都有来源，没有推测的接口。 | | 3. 追踪与设计 | 涉及脚本规则、生命周期、网络或联系人时读取 [runtime.md](references/runtime.md)。调用链检查从入口追踪参数、状态和异步回调，直到最终动作及相关返回、清理；新建或调整模块时读取 [architecture.md](references/architecture.md)。 | 能说明值从哪里来、在哪一步改变、最终影响什么；不能只看单个模块就下结论。 | | 4. 执行 | 诊断时给出原因、证据与修复方向；审核时按 [review-checklist.md](references/review-checklist.md) 检查；已授权的创建、修改或迁移按完成标准实施。 | 结论或改动有文档、源码或日志依据，未超出任务边界。 | | 5. 验证 | 检查完成标准、`info.prop`、`loadJava` 路径、回调、失败处理与卸载清理；能运行 WA 时再验证实际加载和交互。 | 交付改动文件、已验证项和真机待验证内容。 | ## 遇到不确定情况时 - 先查需求、目录、文档和源码。如果仍有多个 WA 版本或插件根目录可选，而且选择会影响实现，再询问用户；得到答复后重新核对接口。 - 公开接口不能满足需求而需要 Hook、反射或内部类型时，先说明版本风险并确认；用户不接受时保留公开接口范围或缩小功能。 - 迁移会删减功能或改变配置、数据格式时，先说明改动前后的差别。用户确认前，保留原有行为和格式。 - 资料冲突时按“当前工作区文档和源码 > 内置接口文档 > 同版本插件 > 用户示例”的顺序判断，并说明采用了哪份资料。仍查不到的签名或字段不要猜，只实现能够确认的部分。 - 没有真机环境时，完成静态检查和源码核对，列出还要在真机上检查什么，不要写成“已经运行通过”。 ## WA 开发规则 - `main.java` 采用 BeanShell 顶层脚本。功能较多、拆分后更容易阅读时，再用 `loadJava("相对路径.java")` 加载模块。路径以 `pluginDir` 为基准，先加载被其他代码使用的模块；`main.java` 只保留加载代码、需要共享的 Hook 或任务引用、WA 回调和模块调用。 - 必需文件只有 `info.prop` 和 `main.java`。`config.prop` 在首次写入配置时由 WA 生成；`readme.md` 仅在用户或仓库要求时添加，不创建空文件占位。 - 使用回调、全局变量、字段、方法或重载前核对文档。入站自动处理通常排除 `msgInfoBean.isSend()`；事件回复用 `msgInfoBean.getTalker()`，当前会话主动操作才用 `getTargetTalker()`。 - `get`、`post`、`download` 均为异步接口；请求前保存事件会话 ID，只在回调中使用可能为 `null` 的结果。 - 混合来源的选择项在收集时保留对象类型或明确类型标记；不能只保存 ID 丢失类型信息后，再根据字符串格式猜测类型。 - 菜单回调只负责添加菜单项，发消息或写配置放在点击 lambda 中。Hook、广播和定时任务等注册内容要在 `onUnload()` 中取消。 ## 结果要求 - 创建、修改或迁移：用户要求落地时直接编辑目标目录，逐项满足完成标准，交付必要文件和确有职责的模块。 - 调试：报告“现象或日志 → 原因与证据 → 最小修复方向 → 验证状态”。证据不足时标明待确认点，提出能区分原因的最小复现或脱敏日志；只有获准修改后才实施修复，检查范围限于受影响调用链。 - 审核：问题优先，逐项给出严重程度、文件与行号、实际影响和依据；无问题时明确说明剩余验证风险。