外观
AI 开发说明
从用户的需求开始，交付可检查、可安装的 Neomega 原生 Python 插件。用户使用自己的 AI 编程工具；框架本体源码不是开发前置条件。
本页纯 Markdown · 按需阅读索引 · 官方工具包
1. 确定行为与环境
将需求整理成“触发条件 → 处理规则 → 可见结果”。从现有对话复用已确定的配置、权限和验收要求；只询问影响行为的未决业务问题，不要求用户先学习 Python。
使用配套工具包与运行包，记录操作系统和 Python 版本。已有实例先读取状态并确认连接目标；插件需要的权限由实例管理员审阅。
有奖励、扣减、发命令或世界写入时，明确同一业务如何防止重复、谁有权限触发、失败或结果未确认时如何处理。正常玩家输入应作为数据校验，不能直接拼成任意游戏命令。
完成条件： 能用一个正常案例和一个失败/重复案例说明期望行为，已明确开发环境和安装目标。
1.1.0 的资源会话、RemoteBus 与自动投影恢复见资源会话和远程 EP。目标仍为 1.0.0 时，不要生成 ctx.scopes 或 RemoteBus 调用；先核对目标 Host 与 SDK 是否配套。
2. 按能力读取参考
可先按任务入口选择示例。先读能力总览、运行上下文与生命周期，再按本次需求选读专题。使用完整 API 目录核对类、方法与类型字段；目录中的内部或兼容模块按其标注使用。按当前接口签名实现；确有缺失的业务能力写明限制，不用同名的旧框架接口代替。
| 本次需求 | 读取内容 | 实现时必须确认 |
|---|---|---|
| 聊天、玩家或其他事件触发 | 事件 | 实际事件源、订阅、字段和 ACK；收到的事件不等于全服完整观察 |
| 发命令、读玩家或调用其他插件服务 | 权限、SDK | manifest 声明、Host 支持和管理员授权分别满足 |
| 可配置文案、开关和秘密引用 | 配置 | 配置类型、schema、默认值和真实配置保存位置 |
| 持久数据、周期任务或重载 | 生命周期、SDK | 数据属于安装身份；任务能被停止；候选校验只读 |
| 报错、超时或不确定结果 | 错误处理、调试与交付 | 原回执、原意图和证据；unknown 不自动重放 |
世界、BDX、库存、容器、挖掘合成、导航、战斗和协议需求均有独立专题，入口见接口总览。不要因 SDK 入门页没有举例就断言框架不支持，也不能把外部 HTTP 方法写成 ctx 方法。
常用任务优先阅读作者便利接口：中文聊天命令、玩家句柄、常用动作、一次提交与命令结果解析。需要玩家能力、环境或配方时查协议扩展，直接处理包时查Python 协议模型。
完成条件： 每项业务能力都有已阅读的接口依据，核实签名、返回值和限制，列出了所需事件、配置和最小权限。
3. 从工具包模板实现
使用工具包提供的 runtime-plugins.py new 创建独立插件目录。第一个插件给出完整命令和最小源码。初次接入选 basic；需要聊天计数可查 event-counter，需要导出在线服务可查 online-service。
实现时维护下列文件的一致性：
| 文件 | 职责 |
|---|---|
main.py | 公开 SDK 实现的插件行为与类型化配置 |
manifest.json | 插件身份、版本、入口、订阅、权限及接口最低版本 |
config.schema.json、config.example.json | 用户可以填写的配置及无秘密的默认示例 |
package.files.json | 逐个列出允许发布的文件；新增模块同步加入清单 |
README.md | 安装配置、权限解释、验收步骤和当前限制 |
修改 Settings 后，按配置参考显式重新导出 schema，并同步示例。lint 不会比较 Python 配置类型与已导出的 schema 是否一致。
事件业务数据与 ACK 需要一起提交时，使用事件事务；普通文件写入不属于该事务。游戏动作即使通过同一事务登记，也要单独查询实际动作结果。保存成功不能替代游戏动作成功。
完成条件： 正常和失败路径已实现，发布清单完整，配置与权限说明能让管理员判断是否启用。
4. 完成离线检查
在工具包目录运行以下命令，将 hello 换成实际插件目录名：
sh
python3 runtime-plugins.py lint plugins/hello --json
python3 runtime-plugins.py pack plugins/hello hello.zip
python3 runtime-plugins.py check hello.zip读取退出码及 JSON，按 checks 中的 path、line、message、hint 修复，再复查受影响的内容。工具缺失或不能执行时，修复工具环境，不能改写检查结果。
lint 会检查发布清单、制品、Python 语法和存在的静态配置。它不导入插件、不安装依赖、不执行业务；skip 必须保留。pack/check 通过也不证明权限已授予、Host 兼容或游戏内功能可用。涉及重要业务规则时，另做有意义的离线行为验证并说明使用的是模拟输入。
完成条件： 三条命令退出码为 0，报告 ok: true，已说明跳过项；源码与 ZIP 来自同一最终版本。
5. 按授权调试并交付
根据用户已授权的范围继续执行，不重复询问已明确允许的操作。在线调试前确认目标实例、版本、当前状态及允许的动作；管理令牌通过私有文件读取，交付材料只记录脱敏信息。托管用户未获得本机管理终端时，由实例管理员按同一验收步骤操作。
按调试与交付完成安装、配置、权限审阅、诊断和启动。检查 Host 状态及日志；有游戏效果时，在授权目标中触发并记录读回或实际玩家观察。证据不足保留待验收，不能用模拟结果填充实服结论。
结果为 unknown 或等待超时时，保留原 operation_id / commit_id、幂等键、请求和期限，先核对原回执。停止等待不会撤销已提交动作；不更换 ID 或键自动重放。框架异常按提交可复现的问题整理最小复现和脱敏证据，通过实例管理员或维护者提供的渠道反馈，无需访问或修改框架私有源码。
最终交付包含以下四项：
- 源码目录、可安装 ZIP 及其 SHA-256。
- 插件版本、目标框架/工具包版本、配置与权限说明。
- 实际执行的检查、输出摘要、跳过项及未完成的验收。
- 安装/停止步骤，以及测试中留下的运行实例或需清理的资源。
完成条件： 用户能取得产物、按说明安装，并清楚区分离线通过、Host 运行通过与游戏内验收；已清理任务创建且不需保留的测试资源。