# 万能导共创流程 这份文档用于规范万能导社区共创流程，重点解决三个问题： - 避免多人重复开发同一个平台或 Bug。 - 让新贡献者知道从哪里开始。 - 让维护者 Review 和合并 PR 时有统一标准。 如果你想新增平台、大功能或任务中心相关改动，请先开 Issue 说明目标和实现范围，避免多人重复做同一件事。 ## 总原则 ```text 先搜索 -> 提 Issue -> 认领 -> Draft PR -> 测试 -> Review -> 合并 ``` 文档错字、小范围文案、轻量 README 补充可以直接 PR。新增平台、大功能、复杂 Bug 修复请先提 Issue。 只想建议新增平台时不需要认领，也不要求会开发。平台用户提供真实使用场景、公开资料、脱敏样例或测试意愿，同样可以帮助新平台进入评估和共创队列。 ## 什么时候必须先提 Issue 以下情况请先提 Issue，不建议直接 PR： - 新增平台导出。 - 新增平台导入。 - 新增教程型平台。 - 修复登录、权限、接口、目录结构、图片、附件等复杂问题。 - 改 Plugin/Provider 机制、任务中心、设置页、打包发布、自动更新等核心能力。 - 对已有平台做行为变化，例如改导出格式、改目录结构、改默认参数。 以下情况可以直接 PR： - 文档错字。 - README 链接修复。 - 小范围 UI 文案优化。 - 不影响功能行为的注释或格式修正。 ## Issue 提交流程 ### 1. 搜索是否重复 开发前先搜索： - 平台名称：`语雀`、`飞书`、`知识星球`、`OneNote`、`为知笔记`。 - 功能关键词：`导入`、`导出`、`图片`、`附件`、`目录结构`、`登录`。 - 报错关键词：`Access denied`、`remote debugging port`、`HTTP 429`、`scope`。 如果已有相同 Issue，请在原 Issue 下补充信息。不要重复开同类 Issue。 ### 2. 选择正确模板 GitHub Issue 模板建议这样选： - Bug 反馈：功能报错、效果不对、图片丢失、导入失败、安装失败。 - 新平台接入建议 / 共创认领：任何人都可以建议新增平台；愿意开发时也可以在同一模板中认领。 - 功能建议：已有平台增强、UI 优化、任务中心、设置项等。 - 教程/文档：补平台教程、迁移经验、排障文档。 ### 3. 写清楚关键信息 Issue 最好包含： - 平台名称和平台链接类型。 - 要做导出、导入、教程，还是 Bug 修复。 - 当前实际结果。 - 期望结果。 - 是否包含多层目录、图片、附件。 - 是否有公开样例或脱敏样例。 - 参与方式：仅提出建议、协助测试、提供资料，或认领开发。 请不要上传 Cookie、Token、账号密码、App Secret、API Key 或私人知识库内容。 ## 认领机制 如果你想做某个 Issue，请评论： ```text 我来认领这个问题，预计 X 天内提交 Draft PR。 ``` 维护者确认后会在 Issue 上标记或评论确认。 认领后的规则： - 认领者优先开发，其他人不要重复实现同一个方向。 - 其他人可以在 Issue 下补充资料、测试样例或实现建议。 - 认领确认后 2 天内提交 Draft PR，或在 Issue 中给出可验证进展。 - 如果任务难度较大、无法在 2 天内形成 Draft PR，请在期限内说明当前情况、阻塞点和下一步计划。 - 复杂任务继续认领期间，至少每 2 天在 Issue 或 Draft PR 中同步一次进度。 - 超过 2 天既没有成果也没有进度说明，或后续连续 2 天未按约定同步，维护者可以释放认领。 - 认领者可以主动评论“释放认领”，方便别人接手。 ## PR 提交流程 ### 1. 尽早开 Draft PR 大功能建议先开 Draft PR，哪怕还没完成。这样可以让其他贡献者看到你已经在做，避免重复劳动。 ### 2. 一个 PR 只做一件事 推荐： - 一个 PR 新增一个平台导出。 - 一个 PR 修复一个平台的图片问题。 - 一个 PR 补一份教程。 不推荐： - 一个 PR 同时新增多个平台。 - 一个 PR 同时大改 UI、脚本和文档。 - 一个 PR 混入大量格式化和无关重构。 ### 3. PR 必须关联 Issue PR 描述里请写： ```text Closes #123 ``` 如果只是部分解决，可以写： ```text Related to #123 ``` ### 4. PR 描述必须包含测试 请写清楚： - 运行了哪些命令。 - 是否在桌面端手动测试。 - 测试的平台、入口类型和样例规模。 - 图片、附件、目录结构是否正常。 - 已知限制是什么。 ## 新平台共创流程 新增平台建议分阶段做，不要一开始就追求全量能力。 ### 阶段 1：教程或最小版本 适合先提交： - 平台介绍。 - 登录方式。 - 平台自带导入导出能力。 - 人工导出到 Markdown 的流程。 - 最小可用导出或导入脚本。 ### 阶段 2：目录结构 补齐： - 读取目录。 - 勾选部分目录或文档。 - 保留原平台目录层级。 - 输出本地目录结构。 ### 阶段 3：资源处理 补齐： - 图片下载或上传。 - 附件下载或上传。 - 远程图片、本地图片、缺失图片的处理策略。 - 资源失败报告。 ### 阶段 4：稳定性 补齐： - 失败项重试。 - 断点续跑。 - 增量导出。 - 请求延迟和限流处理。 - 用户可读的错误提示。 ## Plugin 接入建议 新增平台优先放到： ```text plugins// ``` 推荐结构： ```text plugins// plugin.json backend/ providers/ /provider.json /README.md ``` 如果标准 UI 足够，尽量不要改 Tauri 2 宿主。只需要写： ```text plugin.json providers//provider.json providers//README.md backend/actions.py ``` 如果平台非常复杂，可以在同一个插件里拆分多个 Provider；标准 UI 仍然不够时，再声明沙箱自定义 UI，并在 PR 中说明原因。 ### Plugin v1 与 Provider v1 稳定规则 Plugin v1 是新增平台的默认安装、更新、签名和回滚单元。Provider v1 是插件内部描述字段、按钮、目录树和能力的稳定契约。旧 `providers/` 文件型 Provider 仍然兼容，但只建议用于历史功能维护或迁移参考。 Review 时需要额外确认： - PR 默认只修改一个 `plugins/`；批量迁移需要维护者添加 `plugin-batch` 标签。 - `plugin.json.version` 已按改动类型提升。 - `permissions` 最小化，且与实际能力一致。 - PR 没有破坏 `providers/provider.schema.json` 中已有字段含义。 - PR 没有要求其他插件或 Provider 必须跟着改字段。 - PR 如果新增 Provider 能力，优先使用可选字段，并同步更新模板、文档和校验器。 - PR 如果必须改变协议，需要先开 Issue 讨论 `schemaVersion: 2`，不能在 v1 内静默破坏兼容。 - 新平台默认只改 `plugins//`；需要改 Tauri 2 宿主时，必须说明标准 UI 和沙箱自定义 UI 为什么不够。 ## 标签建议 维护者可以按下面方式标记 Issue： - `bug`：Bug 反馈。 - `enhancement`：功能建议。 - `plugin`：在线插件或新平台共创。 - `documentation`：文档教程。 - `good first issue`：适合新人。 - `help wanted`：欢迎共创。 - `duplicate`：重复 Issue。 - `status:needs-triage`：等待维护者确认。 - `status:claimed`：已被认领。 - `status:blocked`：被外部条件阻塞。 - `platform:yuque`、`platform:feishu`、`platform:zsxq`：平台标签。 如果 GitHub 仓库暂时没有这些标签，维护者可以逐步补齐；模板中的描述仍然按这个规范执行。 ## Review 标准 维护者 Review 时重点看： - 是否解决关联 Issue。 - 是否混入无关改动。 - 是否保留目录结构、图片、附件。 - 是否有清晰错误提示。 - 是否会影响已有平台。 - 是否包含敏感信息。 - 是否声明真实能力和已知限制。 - 是否符合 AGPL-3.0-only 协议和第三方许可证要求。 ## 合并后 PR 合并后： - 关联 Issue 自动关闭，或由维护者手动关闭。 - 如果是新平台，确认平台中心能展示对应能力。 - 如果是用户可见能力，必要时补充公告或教程。 - 如果是重要修复，建议写入下一版 Release Notes。 ## 给 AI 辅助开发者的建议 如果你使用 AI 辅助开发，请把下面几份文件一起给 AI： - `CONTRIBUTING.md` - `docs/共创流程.md` - `docs/在线插件开发与发布.md` - `docs/Provider接入说明.md` - `docs/tutorials/provider-ai-prompt.md` - `plugins/wiz/plugin.json` - `plugins/feishu/plugin.json` 提醒 AI： - 不要提交敏感凭证。 - 不要把没实现的能力写成已支持。 - 新平台优先使用 Plugin v1，放到 `plugins//`，不要随意改主程序。 - 每个 PR 只解决一个 Issue；普通插件 PR 只改一个插件目录。 - 修改后必须说明测试方式和已知限制。