## 你将开发什么

Mrite 的扩展分为 **自动化任务组件** 和 **效率插件**。它们都通过 `manifest.json` 声明身份，通过 `Mrite.plugins.register()` 注册入口，在桌面宿主提供的独立窗口中运行。

这套文档面向希望为 Mrite 开发扩展的开发者。读完后，你应该能完成：选择扩展类型、搭建开发环境、运行完整示例、连接实际存在的宿主能力、执行测试，再将源码交给授权发行方生成正式包并上线。

| 你要解决的问题 | 选择 | 例子 |
| --- | --- | --- |
| 一段有输入、阶段和产出的流程 | 自动化任务组件 `task` | 分批处理材料、组织实验、整理研究成果 |
| 一个可反复打开的独立工具 | 效率插件 `tool` | 文本整理、代码编辑、图形处理、资料检索 |
| 新增操作系统或主进程能力 | 需要配套修改宿主 | 新 IPC、原生依赖、后台进程或新的文件授权流程 |

> [!IMPORTANT]
> 组件开发不等于发行授权。开发源码 ZIP 可以供你阅读和测试，正式版导入的是相应发行流程生成的加密组件包，不能把 ZIP 改个后缀就交给用户安装。

## 一条完整的开发路线

1. 阅读[准备开发环境](environment.html)，打开一个最小组件。
2. 核对[目录与组件清单](manifest.html)，确定 ID、类别和宿主版本要求。
3. 完成[效率插件实作](plugin-development.html)或[任务组件实作](workflows.html)。
4. 按需连接[文件接口](file-api.html)、[模型配置](api-configuration.html)和已支持的业务接口。
5. 运行[自动化测试](testing.html)，再做[桌面集成验收](desktop-testing.html)。
6. 准备交付资料，由授权发行方[生成、加密与登记](publishing.html)。
7. 通过[上线验收](release-guide.html)，再向用户发布；后续按[更新与回退](versioning.html)维护。

## 两条可以直接运行的学习路线

### 效率插件：文本整理工具

示例将用户粘贴的文字整理为单空格分隔的文本。它不需要网络、模型账号或磁盘权限，适合先理解模块顺序、DOM 挂载、事件绑定与停用清理。

[下载效率插件源码](/official-design-v20261028u/example-tool.zip)

### 自动化任务：资料统计任务

示例分批统计文本，显示真实处理进度，支持取消和再次运行。它演示状态、运行身份和过期回调处理，不会凭空启动一个模型 Agent，也不会自动创建磁盘工作区。

[下载自动化任务源码](/official-design-v20261028u/example-task.zip)

## 理解宿主、组件和用户项目

```text
Mrite 桌面宿主
  ├─ 发现并校验 manifest
  ├─ 创建扩展窗口、传入 api 与挂载容器
  ├─ 通过 preload / IPC 执行被支持的系统能力
  └─ 管理正式包的完整性、授权与版本范围

组件源码
  ├─ main：注册生命周期
  ├─ modules：界面和业务逻辑
  └─ styles / assets：组件自己的样式与资源

用户项目
  └─ 用户材料、工作副本、执行记录与成果
```

组件源码与安装目录不是保存用户成果的位置。用户项目应放在用户允许的工作区，原始资料与输出分开；组件升级不能清空旧项目。

## 本文档对应的接口边界

当前示例使用 **扩展 API v1**，最低宿主版本在各示例清单中明确声明。接口以目标宿主源码为准，本文不假定存在 `api.chat()`、`api.runTask()` 或通用文件选择方法。

| 源码入口 | 用来核对什么 |
| --- | --- |
| `src/services/extension.js` | 扫描目录、清单、类别、启用与版本限制 |
| `renderer/plugins/runtime.js` | 加载、注册、激活、停用与错误状态 |
| `renderer/plugins/window.js` | 独立窗口中的容器与真实桥接对象 |
| `preload.js` | 当前版本实际暴露的方法和事件 |
| `src/ipc/extension.js`、`src/ipc/file.js` | 主进程最终处理与返回约定 |

## 怎样判断“完成开发”

能显示界面只代表入口成立。完成开发还需要证明：业务结果正确、失败能解释、取消会生效、保存确实成功、再次打开没有重复事件、正式包能在目标宿主正常导入。

每篇文档都围绕这些可验证的结果展开。先把最小示例跑通，再增加一项能力；一次只接入一个新环节，排错会更清楚。