项目结构约定
字数
848 字
阅读时间
4 分钟
本文档用于统一仓库目录职责，减少“文件放哪儿”的沟通成本。该约定对新增内容即时生效；历史内容按“改到再搬”渐进调整，不要求一次性重构。
顶层目录职责
src/: 业务源码tests/: 单元测试与集成测试docs/: 面向开发与部署的文档（索引见 docs/README.md）config/: 主配置示例与 Compose 插值（pallas.example.toml、compose.env.example）scripts/: 运维脚本（如run_sharded_bot.sh分片启动）local/plugins/: 站点自有插件（extra_plugin_dirs，见 站点定制）tools/: 维护脚本与辅助配置.github/workflows/: CI/CD 流水线data/: 运行期持久化数据（pallas_config/webui.json、各插件子目录等）resource/: 项目静态资源（如语音、样式）
源码分层约定
src/plugins/: 业务插件，按功能域拆分src/foundation/、src/platform/、src/features/、src/console/、src/domain/、src/shared/: 跨插件复用内核（见 common-layers.md）
约定原则：
- 插件业务代码优先放在
src/plugins/<plugin_name>/ - 可复用能力优先沉淀到
src/各内核层，避免在插件间复制 - 新增目录时优先保持语义单一，避免「脚本+配置+文档」混放
补充说明：
- 插件持久化数据统一落在
data/<plugin_name>/...，原因是方便备份与按插件排障。 - 插件资源统一放在
resource/...，原因是便于复用并避免插件目录携带大体积二进制资产。
项目内实际示例：
data/greeting/：greeting插件的好友欢迎消息持久化目录。data/help/：help插件的帮助图渲染缓存目录。data/request_handler/：request_handler插件的待处理申请缓存目录。resource/voices/：greeting使用的语音资源目录。resource/styles/：help插件的样式资源目录。
测试目录约定
- 测试目录尽量镜像源码目录，例如：
src/plugins/repeater/...->tests/plugins/repeater/...src/foundation/db/...->tests/common/...src/console/web/...->tests/common/web/...
这样可以降低定位测试与补测成本。
文档目录约定
docs/Deployment.md、docs/DockerDeployment.md：部署类文档docs/FAQ.md：常见问题docs/architecture/：架构与约定文档（本文件所在目录）docs/plugins/：插件专项说明（按插件目录组织）
目录约定：
- 每个插件使用独立目录：
docs/plugins/<plugin_name>/README.md - 插件文档总索引：
docs/plugins/README.md
当前已迁移的插件文档见 plugins/README.md（21 个用户向插件 + 通用能力文档）。
tools 目录约定
为避免语义混杂，当前按以下方式拆分：
tools/scripts/: 可执行脚本（如备份、清理、迁移）tools/config/: 仅工具侧配置文件
根目录协作文件
AGENTS.md建议保留在仓库根目录，便于贡献者与 Agent 统一读取协作约定。.pre-commit-config.yaml与.pre-commit-ci.yaml建议保留在仓库根目录，便于工具默认发现与执行。
渐进落地策略
- 新增文件按本约定放置
- 历史文件在“改到再搬”的原则下逐步迁移
- 每次 PR 只做小步调整，避免大规模无关重排
