mod-workflow

Files (1)

• SKILL.md

SKILL.md (first lines)

# MOD 开发工作流约束

本规范是强制性工作流，适用于网易基岩版 MC MOD 的 Python 业务开发。以下所有"必须"均为硬性门控，未通过则不得进入下一阶段。

---

## 阶段零：项目认知门控

**触发条件**：首次接触一个 MOD 项目，或对项目结构不确定时。

**硬性规则**：在写出任何业务代码之前，必须完成以下步骤，不得跳过。

1. 调用 `scan_py2_mod_architecture` 扫描行为包根目录
   - 参数建议：`ignore_third_party_analysis=true`（聚焦业务，避免框架噪音）
   - 必须从输出中确认：入口模块位置、模块分层、核心子系统、依赖链
2. 阅读架构输出，识别当前任务涉及的子系统和模块边界
3. 如果任务涉及特定子系统，对该子系统目录追加调用 `scan_py2_import_chain` 做定点深挖

**禁止**：
- 禁止在未完成架构扫描的情况下创建新文件或修改已有文件
- 禁止凭猜测判断模块职责或依赖关系

**通过条件**：能明确回答"这个项目有哪些子系统、当前任务应该改哪些模块、这些模块之间的依赖关系是什么"。

---

## 阶段一：改动前引用链分析

**触发条件**：需要修改、重构、拆分、合并任何已有模块时。

**硬性规则**：动刀之前，必须对目标文件/目录调用 `scan_py2_import_chain`。

1. 从输出中提取：
   - 直接引用方（谁 import 了它）
   - 间接依赖方（谁通过其他模块间接依赖它）
   - 它的内部依赖（它 import 了谁）
   - 它在架构中的层级位置
2. 根据引用链列出所有受影响的文件清单
3. 制定改动方案时，方案中必须包含对每个受影响文件的处理说明

**禁止**：
- 禁止在未分析引用链的情况下重命名、移动、删除或拆分模块
- 禁止改动一个模块后不检查其引用方是否需要同步更新

**通过条件**：改动方案中已覆盖所有引用方的处理方式（无需修改 / 需同步改接口 / 需更新 import 路径）。

---

## 阶段二：代码编写约束

通过阶段零和阶段一后，进入编码阶段。以下规则在整个编码过程中持续生效。

### 2.1 客户端/服务端 import 边界约束

MOD 业务分为服务端（Server）和客户端（Client）两侧，Python 的 `import` 具有初始化语义，不只是取符号。

**硬性规则**：

- 不得在客户端模块中 import 服务端业务模块，反之亦然
- 不得在 `__init__.py` 中混合导入客户端和服务端业务模块——`__init__.py` 包内导入必须严格确认目标模块属于哪一侧
- 不得在错误线程上初始化对应侧的对象（PyModSdk 基于多线程 GIL 轮换，客户端与服务端对象不是独立副本）

**例外——跳板封装库**：

以下导入本身是合法的，因为它们只在实际调用内部接口时才进入对应侧初始化逻辑：

- `import mod.server.extraServerApi as serverApi`
- `import mod.client.extraClientApi as clientApi`

但前提是：不得在错误线程或错误侧继续调用其内部能力。仅导入无影响，调用才触发初始化。

**决策规则**：

- 当你准备写 `import` 时，先确认：
  - 当前文件运行在哪一侧（客户端 / 服务端）？
  - 被导入的模块属于哪一侧？
  - 两者是否一致？ → 不一致则禁止导入（跳板封装库除外）
- 当你编辑 `__init__.py` 时，逐行检查每个导入目标的归属侧

**禁止**：
- 禁止客户端文件 import 服务端业务模块（跳板封装库除外）
- 禁止服务端文件 import 客户端业务模块（跳板封装库除外）
- 禁止在 `__init__.py` 中混合导入两侧业务模块
- 禁止为了"方便共用"把客户端和服务端逻辑写在同一个文件中

### 2.2 项目架构与命名风格约束

**硬性规则**：

- 优先以当前用户项目已有的架构风格和命名风格进行开发和维护
- 不得擅自引入与现有结构冲突的新组织模式或命名约定
- 仅在用户明确要求重构时才可切换架构风格

**决策规则**：

- 阶段零扫描完成后，从架构输出和已有代码中识别项目采用的：
  - 目录组织风格（按功能板块 / 按端侧 / 其他）
  - 命名约定（文件名、类名、函数名、变量名的风格）
  - 模块划分方式
- 新增代码必须遵循已识别的全部风格，保持一致性
- 如果项目无明确风格（如新项目），可参考以下两种推荐风格，根据项目规模和需求选择

**命名风格约束**：

- 阶段零完成后，必须从已有代码中识别项目的命名风格并遵循
- 常见风格包括但不限于：大驼峰（`GetPlayerPos`）、小驼峰（`getPlayerPos`）、下划线（`get_player_pos`）
- 不同项目可能混用多种风格（如类名大驼峰、函数名下划线），以项目实际为准
- 示例代码中的命名仅为展示逻辑，实际编码时必须适配项目风格

**推荐风格 A——按功能板块划分，端侧文件平铺**：

```
<Feature>/
  <业务板块>/
    Server.py      # 服务端逻辑
    Client.py      # 客户端逻辑
    Utils.py       # 该板块的工具函数
    Config.py      # 该板块的配置/常量
```

From GitHub-Zero123/mcdk-assistant, BSD-3-Clause.

More from GitHub-Zero123/mcdk-assistant