feat.新增了插件开发文档

2026-06-23 18:04:26 +08:00 · 2026-04-13 19:54:37 +08:00
parent ce5acf5bd7
commit 1b22e9df4a
23 changed files with 4770 additions and 1 deletions
--- a/develop/07-发布与运营/01-插件打包规范.md
+++ b/develop/07-发布与运营/01-插件打包规范.md
@@ -0,0 +1,92 @@
+# 01-插件打包规范
+
+了解 .laapp 包的规范和结构，确保插件能正确安装和运行。
+
+---
+
+## 📦 .laapp 文件格式
+
+`.laapp` 是阑山桌面的插件包格式，本质上是一个 **ZIP 压缩包**。
+
+### 文件结构
+
+```
+MyPlugin.laapp
+├── plugin.json              # 插件清单（必需）
+├── MyPlugin.dll             # 主程序集（必需）
+├── Localization/            # 本地化文件夹
+│   ├── zh-CN.json
+│   └── en-US.json
+└── *.dll                    # 依赖项
+```
+
+---
+
+## 📋 plugin.json 规范
+
+### 必需字段
+
+```json
+{
+  "id": "com.example.myplugin",
+  "name": "我的插件",
+  "description": "插件描述",
+  "author": "作者名",
+  "version": "1.0.0",
+  "apiVersion": "4.0.1",
+  "entranceAssembly": "MyPlugin.dll",
+  "sharedContracts": []
+}
+```
+
+### 字段验证规则
+
+| 字段 | 规则 |
+|-----|------|
+| `id` | 小写字母、数字、点号，反向域名格式 |
+| `version` | 语义化版本（x.y.z） |
+| `apiVersion` | 必须与 SDK 版本兼容 |
+| `entranceAssembly` | 必须与 DLL 文件名一致 |
+
+---
+
+## 🔨 构建配置
+
+### .csproj 关键配置
+
+```xml
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <TargetFramework>net10.0</TargetFramework>
+  </PropertyGroup>
+  
+  <ItemGroup>
+    <PackageReference Include="LanMountainDesktop.PluginSdk" Version="4.0.1" />
+  </ItemGroup>
+  
+  <!-- 确保资源文件复制到输出目录 -->
+  <ItemGroup>
+    <None Update="plugin.json">
+      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
+    </None>
+    <None Update="Localization\**\*.json">
+      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
+    </None>
+  </ItemGroup>
+</Project>
+```
+
+---
+
+## ✅ 打包检查清单
+
+- [ ] `plugin.json` 格式正确
+- [ ] `id` 全局唯一
+- [ ] `apiVersion` 与 SDK 版本匹配
+- [ ] DLL 文件名与 `entranceAssembly` 一致
+- [ ] 所有依赖项已包含
+- [ ] 本地化文件完整
+
+---
+
+*最后更新：2026年4月*
--- a/develop/07-发布与运营/02-版本管理策略.md
+++ b/develop/07-发布与运营/02-版本管理策略.md
@@ -0,0 +1,75 @@
+# 02-版本管理策略
+
+合理的版本管理是插件维护的基础。
+
+---
+
+## 🎯 语义化版本（SemVer）
+
+版本格式：`主版本.次版本.修订号`
+
+| 版本变化 | 说明 | 示例 |
+|---------|------|------|
+| 主版本（Major） | 破坏性变更 | 1.0.0 → 2.0.0 |
+| 次版本（Minor） | 新功能，向后兼容 | 1.0.0 → 1.1.0 |
+| 修订号（Patch） | Bug 修复 | 1.0.0 → 1.0.1 |
+
+---
+
+## 📋 版本示例
+
+| 版本 | 含义 |
+|-----|------|
+| `1.0.0` | 首个正式版 |
+| `1.1.0` | 新增功能 |
+| `1.1.1` | 修复 Bug |
+| `2.0.0-beta` | 2.0 测试版 |
+| `2.0.0-rc1` | 2.0 候选版 |
+
+---
+
+## 🔄 版本更新流程
+
+### 1. 更新版本号
+
+```json
+// plugin.json
+{
+  "version": "1.1.0"
+}
+```
+
+### 2. 更新 CHANGELOG.md
+
+```markdown
+## [1.1.0] - 2024-04-13
+
+### 新增
+- 添加天气预警功能
+- 支持多城市管理
+
+### 修复
+- 修复定位失败问题
+```
+
+### 3. 创建 Git 标签
+
+```bash
+git add .
+git commit -m "Release v1.1.0"
+git tag -a v1.1.0 -m "Release version 1.1.0"
+git push origin main --tags
+```
+
+---
+
+## 💡 最佳实践
+
+- 使用 GitHub Releases 管理版本
+- 每个版本都写更新日志
+- 测试版使用 `-beta`、`-alpha` 后缀
+- 保持向后兼容，避免频繁主版本升级
+
+---
+
+*最后更新：2026年4月*
--- a/develop/07-发布与运营/03-发布到插件市场.md
+++ b/develop/07-发布与运营/03-发布到插件市场.md
@@ -0,0 +1,71 @@
+# 03-发布到插件市场
+
+将插件发布到阑山桌面插件市场，让更多用户使用。
+
+---
+
+## 🎯 发布流程
+
+### 1. 准备材料
+
+- 插件包（.laapp）
+- 插件图标（256x256 PNG）
+- 截图（至少 1 张）
+- 详细描述
+- 更新日志
+
+### 2. 提交审核
+
+1. 访问阑山桌面开发者门户
+2. 登录开发者账号
+3. 点击「提交新插件」
+4. 填写插件信息
+5. 上传 .laapp 文件
+6. 提交审核
+
+### 3. 审核标准
+
+| 检查项 | 要求 |
+|-------|------|
+| 功能完整性 | 插件能正常运行 |
+| 安全性 | 无恶意代码 |
+| 用户体验 | 界面美观，操作流畅 |
+| 文档完整 | 有基本使用说明 |
+
+---
+
+## 📋 元数据要求
+
+### 必需信息
+
+```json
+{
+  "id": "com.example.plugin",
+  "name": "插件名称",
+  "description": "简短描述（50字以内）",
+  "author": "作者名",
+  "version": "1.0.0",
+  "tags": ["工具", "天气"],
+  "website": "https://github.com/..."
+}
+```
+
+### 图标规范
+
+- 格式：PNG
+- 尺寸：256x256 像素
+- 背景：透明
+- 风格：与阑山桌面一致
+
+---
+
+## 🚀 发布后
+
+- 关注用户反馈
+- 及时修复 Bug
+- 定期更新功能
+- 维护更新日志
+
+---
+
+*最后更新：2026年4月*
--- a/develop/07-发布与运营/04-更新与维护.md
+++ b/develop/07-发布与运营/04-更新与维护.md
@@ -0,0 +1,82 @@
+# 04-更新与维护
+
+插件发布后的持续维护和更新策略。
+
+---
+
+## 🔄 更新策略
+
+### 热修复（Hotfix）
+
+发现严重 Bug 时立即发布：
+
+```bash
+# 1. 修复 Bug
+git checkout -b hotfix/critical-bug
+# ... 修复代码 ...
+
+# 2. 更新版本号（修订号+1）
+# plugin.json: "version": "1.0.1"
+
+# 3. 提交并发布
+git commit -m "Fix critical bug"
+git tag -a v1.0.1 -m "Hotfix v1.0.1"
+git push origin main --tags
+```
+
+### 功能更新
+
+```bash
+# 1. 开发新功能
+git checkout -b feature/new-feature
+
+# 2. 完成功能后合并到 main
+
+# 3. 更新版本号（次版本+1）
+# plugin.json: "version": "1.1.0"
+
+# 4. 发布
+git tag -a v1.1.0 -m "Release v1.1.0"
+git push origin main --tags
+```
+
+---
+
+## 📊 维护清单
+
+### 日常维护
+
+- [ ] 监控用户反馈
+- [ ] 查看崩溃报告
+- [ ] 回复用户问题
+- [ ] 更新依赖包
+
+### 定期维护
+
+- [ ] 每季度检查 SDK 更新
+- [ ] 每年评估功能需求
+- [ ] 定期更新文档
+
+---
+
+## 🐛 Bug 处理流程
+
+1. **收集信息** - 复现步骤、环境信息
+2. **定位问题** - 本地调试复现
+3. **修复验证** - 修复后充分测试
+4. **发布更新** - 按热修复流程发布
+5. **通知用户** - 在 Release 中说明
+
+---
+
+## 💡 最佳实践
+
+- 保持向后兼容
+- 及时响应用户反馈
+- 定期发布小更新
+- 维护清晰的更新日志
+- 废弃功能提前通知
+
+---
+
+*最后更新：2026年4月*