## 开始前准备什么

- 匹配目标版本的 Mrite 开发源码，以及该版本允许使用的开发环境。
- 能运行项目依赖的 Node.js、npm 与项目锁文件。宿主使用的 Electron 版本由项目依赖决定。
- 一个独立的小型测试项目。不要用包含重要资料的日常项目做首次保存、删除或迁移测试。
- 一个代码编辑器，以及阅读浏览器控制台和终端日志的基本能力。

> [!NOTE]
> 正式安装包不等同于开发 SDK。没有源码或对应开发环境时，先与维护者确认开发接入方式。网页中的示例窗口也不能运行桌面 IPC。

## 启动宿主开发版

在包含 `package.json` 的宿主项目根目录运行：

```powershell
cd "D:/dev/Mrite"
npm ci
npm run check:project
npm run dev
```

`npm ci` 根据锁文件安装依赖；`check:project` 检查结构、语法和清单等项目约束；`dev` 打开桌面开发版。若依赖涉及本机原生构建工具，按项目自身说明配置，不要通过删除锁文件或关闭完整性检查来跳过问题。

浏览器开发模式适合检查纯界面，但文件、终端、组件窗口和正式授权仍应在 Electron 中验证。

## 下载并解压示例

| 示例 | 文件 | 解压后的根目录 |
| --- | --- | --- |
| 效率工具 | [example-tool.zip](/official-design-v20261028u/example-tool.zip) | `my-example-tool/` |
| 自动化任务 | [example-task.zip](/official-design-v20261028u/example-task.zip) | `my-example-task/` |

每个目录直接包含 `manifest.json`，不要再次套一层同名目录。源码包还包含 `.tests/` 下的本地测试；它们用于开发验证，不作为用户执行的业务模块。

## 选择开发期放置位置

### 推荐：开发版用户扩展目录

开发版按类别扫描 `app.getPath('userData')` 下的 `plugins/` 和 `task-components/`。路径随当前宿主数据目录而变化，不要猜测固定的 AppData 路径。

可在自己的开发版 DevTools 中使用实际暴露的接口打开对应目录：

```javascript
await window.electronAPI.extensionOpenUserDir('tool');
// 自动化任务使用 'task'
```

将解压后的组件目录放进打开的目录，再重新扫描。第三方目录的组件默认不启用，需要显式启用。

### 宿主源码目录中的组件

宿主本身在 `plugins/` 和 `task-components/` 中维护内置扩展。开发者拥有对应源码维护权限时可以在这些目录联调，但扫描器会把该来源按内置组件处理。**在内置来源里运行成功，不代表第三方生产导入的约束也已经验收。**

不要占用已有内置 ID，也不要靠更改 `type` 冒充内置权限。

## 扫描、启用并打开

正常开发流程优先使用软件组件管理入口。需要排查时，可在自己开发版的控制台逐项验证：

```javascript
const api = window.electronAPI;
const scan = await api.extensionReload();
if (!scan.success) throw new Error(scan.error || '组件扫描失败');

const enabled = await api.extensionEnable('my-example-tool');
if (enabled && enabled.success === false) throw new Error(enabled.error);

await api.extensionOpenWindow('my-example-tool');
```

任务示例的 ID 是 `my-example-task`。不要在陌生网页控制台粘贴这些命令，也不要通过网站注入桌面桥接对象。

## 验证第一次运行

1. 文本整理工具：输入 `  alpha    beta  `，操作后应得到 `alpha beta`。
2. 资料统计任务：输入“甲乙”，换行输入“丙”，应得到 `lines: 2`、`characters: 3`。
3. 关闭并重新打开，确认只有一份界面和一套按钮。
4. 停用后重新启用，确认没有重复操作和残留计时器。

## 修改源码后如何刷新

重新扫描会更新清单信息，**不会撤销已经执行的 JavaScript**。改了脚本后，先关闭对应窗口，再重新打开；涉及全局定义或宿主入口时重启开发版。

如果扫描不到组件，先检查目录嵌套、JSON 语法、ID、类别和最低版本。完整排查路径见[常见问题排查](troubleshooting.html)。