# AI 开发说明

从用户的需求开始，交付可检查、可安装的 Neomega 原生 Python 插件。用户使用自己的 AI 编程工具；框架本体源码不是开发前置条件。

[本页纯 Markdown](https://wiki.wuxie233.com/raw/develop/ai-entry.md) · [按需阅读索引](https://wiki.wuxie233.com/llms.txt) · [官方工具包](https://wiki.wuxie233.com/toolkit/)

<span id="_1-确定行为与版本"></span>

## 1. 确定行为与环境

将需求整理成“触发条件 → 处理规则 → 可见结果”。从现有对话复用已确定的配置、权限和验收要求；只询问影响行为的未决业务问题，不要求用户先学习 Python。

使用[配套工具包](https://wiki.wuxie233.com/toolkit/)与[运行包](https://wiki.wuxie233.com/releases/)，记录操作系统和 Python 版本。已有实例先读取状态并确认连接目标；插件需要的权限由实例管理员审阅。

有奖励、扣减、发命令或世界写入时，明确同一业务如何防止重复、谁有权限触发、失败或结果未确认时如何处理。正常玩家输入应作为数据校验，不能直接拼成任意游戏命令。

**完成条件：** 能用一个正常案例和一个失败/重复案例说明期望行为，已明确开发环境和安装目标。

1.1.0 的资源会话、`RemoteBus` 与自动投影恢复见[资源会话](https://wiki.wuxie233.com/reference/resource-scopes)和[远程 EP](https://wiki.wuxie233.com/reference/remote-ep)。目标仍为 1.0.0 时，不要生成 `ctx.scopes` 或 `RemoteBus` 调用；先核对目标 Host 与 SDK 是否配套。

## 2. 按能力读取参考

可先按[任务入口](https://wiki.wuxie233.com/develop/tasks)选择示例。先读[能力总览](https://wiki.wuxie233.com/reference/)、[运行上下文](https://wiki.wuxie233.com/reference/runtime)与[生命周期](https://wiki.wuxie233.com/reference/lifecycle)，再按本次需求选读专题。使用[完整 API 目录](https://wiki.wuxie233.com/reference/api-index)核对类、方法与类型字段；目录中的内部或兼容模块按其标注使用。按当前接口签名实现；确有缺失的业务能力写明限制，不用同名的旧框架接口代替。

| 本次需求 | 读取内容 | 实现时必须确认 |
| --- | --- | --- |
| 聊天、玩家或其他事件触发 | [事件](https://wiki.wuxie233.com/reference/events) | 实际事件源、订阅、字段和 ACK；收到的事件不等于全服完整观察 |
| 发命令、读玩家或调用其他插件服务 | [权限](https://wiki.wuxie233.com/reference/permissions)、[SDK](https://wiki.wuxie233.com/reference/sdk) | manifest 声明、Host 支持和管理员授权分别满足 |
| 可配置文案、开关和秘密引用 | [配置](https://wiki.wuxie233.com/reference/configuration) | 配置类型、schema、默认值和真实配置保存位置 |
| 持久数据、周期任务或重载 | [生命周期](https://wiki.wuxie233.com/reference/lifecycle)、[SDK](https://wiki.wuxie233.com/reference/sdk) | 数据属于安装身份；任务能被停止；候选校验只读 |
| 报错、超时或不确定结果 | [错误处理](https://wiki.wuxie233.com/reference/errors)、[调试与交付](https://wiki.wuxie233.com/develop/debugging) | 原回执、原意图和证据；`unknown` 不自动重放 |

世界、BDX、库存、容器、挖掘合成、导航、战斗和协议需求均有独立专题，入口见[接口总览](https://wiki.wuxie233.com/reference/)。不要因 SDK 入门页没有举例就断言框架不支持，也不能把外部 HTTP 方法写成 `ctx` 方法。

常用任务优先阅读[作者便利接口](https://wiki.wuxie233.com/reference/author-helpers)：中文聊天命令、玩家句柄、常用动作、一次提交与命令结果解析。需要玩家能力、环境或配方时查[协议扩展](https://wiki.wuxie233.com/reference/protocol-support)，直接处理包时查[Python 协议模型](https://wiki.wuxie233.com/reference/packets#python-%E5%8D%8F%E8%AE%AE%E6%A8%A1%E5%9E%8B)。

**完成条件：** 每项业务能力都有已阅读的接口依据，核实签名、返回值和限制，列出了所需事件、配置和最小权限。

## 3. 从工具包模板实现

使用[工具包](https://wiki.wuxie233.com/toolkit/)提供的 `runtime-plugins.py new` 创建独立插件目录。[第一个插件](https://wiki.wuxie233.com/develop/first-plugin)给出完整命令和最小源码。初次接入选 `basic`；需要聊天计数可查 `event-counter`，需要导出在线服务可查 `online-service`。

实现时维护下列文件的一致性：

| 文件 | 职责 |
| --- | --- |
| `main.py` | 公开 SDK 实现的插件行为与类型化配置 |
| `manifest.json` | 插件身份、版本、入口、订阅、权限及接口最低版本 |
| `config.schema.json`、`config.example.json` | 用户可以填写的配置及无秘密的默认示例 |
| `package.files.json` | 逐个列出允许发布的文件；新增模块同步加入清单 |
| `README.md` | 安装配置、权限解释、验收步骤和当前限制 |

修改 `Settings` 后，按[配置参考](https://wiki.wuxie233.com/reference/configuration)显式重新导出 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. 按授权调试并交付

根据用户已授权的范围继续执行，不重复询问已明确允许的操作。在线调试前确认目标实例、版本、当前状态及允许的动作；管理令牌通过私有文件读取，交付材料只记录脱敏信息。托管用户未获得本机管理终端时，由实例管理员按同一验收步骤操作。

按[调试与交付](https://wiki.wuxie233.com/develop/debugging)完成安装、配置、权限审阅、诊断和启动。检查 Host 状态及日志；有游戏效果时，在授权目标中触发并记录读回或实际玩家观察。证据不足保留待验收，不能用模拟结果填充实服结论。

结果为 `unknown` 或等待超时时，保留原 `operation_id` / `commit_id`、幂等键、请求和期限，先核对原回执。停止等待不会撤销已提交动作；不更换 ID 或键自动重放。框架异常按[提交可复现的问题](https://wiki.wuxie233.com/guide/troubleshooting#%E6%8F%90%E4%BA%A4%E5%8F%AF%E5%A4%8D%E7%8E%B0%E7%9A%84%E9%97%AE%E9%A2%98)整理最小复现和脱敏证据，通过实例管理员或维护者提供的渠道反馈，无需访问或修改框架私有源码。

最终交付包含以下四项：

1. 源码目录、可安装 ZIP 及其 SHA-256。
2. 插件版本、目标框架/工具包版本、配置与权限说明。
3. 实际执行的检查、输出摘要、跳过项及未完成的验收。
4. 安装/停止步骤，以及测试中留下的运行实例或需清理的资源。

**完成条件：** 用户能取得产物、按说明安装，并清楚区分离线通过、Host 运行通过与游戏内验收；已清理任务创建且不需保留的测试资源。