Pallas-Bot

外观

贡献与提交流程 ​

字数
1185 字
阅读时间
5 分钟

本页说明如何提 Issue / PR，以及提交前要过哪些检查。完整约定亦见仓库 CONTRIBUTING.md 与 AGENTS.md。

环境已就绪时，从这里开始贡献即可。架构专题、插件骨架、WebUI 窄屏细则等按改动范围再读。

推荐顺序 ​

  1. 搜索是否已有同类 Issue。
  2. 阅读下方「编码前必读」中与本次改动相关的条目。
  3. 本地跑通 ruff / 相关 pytest，再开 PR。
  4. 一个 PR 只解决一类问题。

Issue ​

提交前搜索是否已有同类问题：Issue 列表。

  • Bug：现象、复现步骤、环境、脱敏日志
  • 功能：要解决的实际问题与期望行为
  • 文档：过时或缺失处可直接 PR

分支与 PR ​

  • 日常开发：从 main 或 dev 拉分支，向目标分支提 PR
  • 一个 PR 只解决一类问题（功能 / 修复 / 文档 / 重构勿混杂）
  • 最小必要改动：避免无关格式化、大范围重排；历史问题在说明里标注「历史遗留」与「本次引入」

编码前必读 ​

主题文档
目录与分层仓库布局
架构总览架构总览、LLM 与 AI
插件组织Golden Plugin
命令权限cmd_perm
配置落盘配置存储

提交前自检 ​

bash
uv run ruff check pallas/ packages/
uv run ruff format --check pallas/ packages/
uv run pytest   # 若改动涉及已有测试覆盖的行为

插件命令权限（cmd_perm）PR 清单 ​

若新增或修改可走 cmd_perm 的命令：

  • Matcher / 手动鉴权与 extra["command_permissions"]（或 registry.DEFAULT_COMMAND_PERMISSIONS）使用同一命令 ID
  • usage、menu_data.trigger_condition 未写死「群管/群主/仅管理员」等静态权限文案
  • 已配置 command_permission / command_permissions，帮助图「何人可用」能反映当前等级
  • 与权限无关的额外条件写在 detail_des 或 docs/plugins/<name>/README.md

WebUI / 控制台页面 ​

改动 Pallas-Bot-WebUI 或主仓内嵌控制台静态资源时，须在 ≤560px 窄屏下自检布局。见 WebUI 前端开发。

文档写作 ​

代码示例 ​

  • 教程、开发指南或 API 说明中的代码块，前面说明它解决的场景；多个场景用 ### 分开。
  • 代码块后说明预期结果或关键行为；命令示例给出最小验证方式。
  • 示例应可复制运行；占位符、前置配置和破坏性影响要明确标注。
  • 只展示 import 或字段清单时，注明这是速查，并链接到完整示例。

链接与收尾 ​

  • 链接文字直接说明目标，不使用「点击这里」或裸 URL；外链优先指向稳定、具体的官方页面。
  • 纯链接型收尾按页面目的命名：教程用 接下来做什么，开发 / 架构用 后续阅读，参考页 / 用户向插件页用 相关链接，维护用 相关阅读。
  • 主题型小节（如 相关配置、相关 API）保留具体主题；同一页面不要同时使用多个含义相同的收尾标题。

搜索与可访问性 ​

  • 标题和开头正文写出用户会搜索的功能名、命令或错误现象；不要为了字数重复关键词。
  • 图片和图表的 alt 描述其传达的信息；纯装饰图不承载信息。
  • 参考页优先准确简洁，教程优先覆盖完成任务所需的前置条件、结果和失败处理，不人为扩写。

Commit 信息 ​

推荐格式（与仓库日常习惯一致）：

text
feat(scope): 简要中文说明
fix(scope): …
docs(scope): …
refactor(scope): …
chore(scope): …
  • 一个 commit 聚焦一件事
  • 勿提交 config/pallas.toml、data/、webui.json、token 等私密内容

文档改动 ​

  • 用户向插件说明：docs/plugins/<name>/README.md（可复制 TEMPLATE.md）
  • 架构与开发约定：docs/developer/
  • 在线站由 CI 将主仓 docs/ 同步至 Pallas-Bot-Docs（见 docs/README.md）

本地预览同步结果：

bash
uv run python tools/scripts/sync_docs_to_web.py
# 在 Pallas-Bot-Docs 目录执行 npm run dev

沟通 ​

可在 Issue 留言或加入 README 中的 QQ 开发者群。

后续阅读 ​