从哪里开始
- 想先了解产品：阅读根目录
README.md，再打开 GitHub Pages 展示站。 - 想实际使用：阅读
docs/user-guide.md，下载 Releases 中的服务器版或客户端。 - 想部署服务器：阅读
docs/server-deployment-guide.md，需要 Docker 时查看根目录Dockerfile和docker-compose.yml。 - 想修改代码：先阅读
docs/architecture.md、CONTRIBUTING.md和PRODUCT.md，再运行npm ci与测试。 - 想重新打包：Windows 使用
build-windows.ps1，独立服务端使用build-server-package.ps1，macOS 需要 macOS 主机或 macOS CI。
文件夹说明
| 路径 | 用途 | 新手是否需要修改 |
| --- | --- | --- |
| .github/ | Issue/PR 模板、代码所有者、贡献检查和 Pages 自动部署工作流 | 通常不需要；修改工作流前先阅读 YAML |
| .impeccable/ | 展示站设计系统的机器可读侧车文件 | 不要直接删；视觉变更后同步设计文档 |
| assets/ | 应用图标和品牌资源 | 只有更换图标时修改 |
| docs/ | GitHub Pages、3D 管理中心 HTML、截图、用户教程、错误处理、技巧与架构说明 | 文档贡献主要在这里 |
| mac/ | macOS 发布说明和平台资源清单 | macOS 构建者使用 |
| mobile/ | Android 客户端、手机服务器、Gradle 工程和 APK 构建脚本 | Android 构建者使用 |
| public/ | 实际浏览器界面、样式、前端逻辑和本地化资源 | 修改界面功能时使用 |
| scripts/ | macOS 构建、Cloudflare 工具准备、清理和发布辅助脚本 | 按平台文档调用 |
| server/ | HTTP API、Socket.IO、认证、房间、媒体、AI 和公网隧道 | 后端功能主要在这里 |
| tests/ | 集成、前端契约、桌面成品、Android、隧道和发布验收 | 每次功能变更都应补充或运行相关测试 |
| dist/ | 唯一正式构建成品目录；已被 Git 忽略 | 完整版本必须直接包含固定 28 个文件 |
根目录规范文件
| 文件 | 作用 |
| --- | --- |
| .dockerignore | Docker 构建时排除源码缓存、测试和无关成品，同时保留服务器需要的客户端文件 |
| .editorconfig | 统一缩进、换行、编码和末尾空格，减少不同编辑器造成的格式差异 |
| .gitattributes | 告诉 Git 哪些文件使用文本处理、LF 换行和二进制方式存储 |
| .gitignore | 排除 node_modules、构建目录、运行数据、临时输出和签名材料 |
| CODE_OF_CONDUCT.md | 社区参与者的行为规范和投诉边界 |
| CONTRIBUTING.md | 分支命名、提交、测试、文档和 Pull Request 要求 |
| DESIGN.md | Pages 展示站的设计方向、色板、排版、布局和无障碍约束 |
| Dockerfile | 构建 Linux/amd64 独立服务器容器 |
| LICENSE | Apache License 2.0 全文，规定使用、修改、专利和再发布条件 |
| NOTICE | 原始项目和版权归属信息，再发布时应保留 |
| PRODUCT.md | 产品定位、用户、能力边界、数据保护和展示站事实依据 |
| README.md | GitHub 首页的新手入口、功能概览、下载选择和文档索引 |
| SECURITY.md | 私密报告安全漏洞的方式和提交前脱敏要求 |
| build-server-package.ps1 | 把独立服务器源码、生产依赖、启动脚本、cloudflared 和客户端文件打成 ZIP |
| build-windows.ps1 | Windows 发布总入口，构建服务器 EXE、客户端 EXE、Android APK 并验证成品 |
| client-launcher.html | 独立 Windows 客户端的登录和服务器地址入口 |
| docker-compose.yml | 用持久化数据目录启动独立服务器容器 |
| electron-builder-client.json | Windows 客户端 Electron 打包配置 |
| electron-builder-mac-client.json | macOS 客户端 x64/arm64 DMG 和 ZIP 配置 |
| electron-builder-mac-server.json | macOS 服务器 x64/arm64 DMG 和 ZIP 配置 |
| electron-builder-mac-full.json | macOS Intel/Apple Silicon 离线完整版 DMG 和 ZIP 配置 |
| electron-builder-windows-full-portable.json | Windows 无需安装的独立 EXE 离线完整版配置 |
| electron-client-preload.js | 客户端渲染进程可用的最小安全 IPC 接口 |
| electron-client.js | Windows/macOS 独立客户端主进程 |
| electron-main-preload.js | 服务器桌面端渲染进程的安全 IPC 接口 |
| electron-pink.js | Windows/macOS 服务器桌面端主进程 |
| electron-settings-preload.js | 服务器设置窗口的受限 IPC 接口 |
| mac-distribution.example.json | macOS 成品下载地址清单示例；没有真实文件时界面显示不可用 |
| package.json | 项目版本、依赖、脚本、Electron 产品名和打包文件白名单 |
| package-lock.json / pnpm-lock.yaml / pnpm-workspace.yaml | 锁定依赖版本和包管理工作区，避免不同机器安装出不同结果 |
| server-standalone.js | 不启动 Electron、直接运行 Node.js 独立服务端 |
| start-server.cmd / start-server.ps1 / start-server.sh | Windows CMD、PowerShell、Linux/macOS 三种启动入口 |
GitHub Actions 与 Pages
.github/workflows/pages.yml 只发布 docs/ 静态目录。它会先运行 node tests/repository-standards.test.js，通过后才上传 Pages artifact 并部署。它不打包服务器，也不会接触用户运行数据。
.github/workflows/ci.yml 在 Pull Request 和 main 更新时安装锁定依赖，运行仓库规范检查与核心集成测试。.github/CODEOWNERS 指定 @xuange6610 为源码审核者；配合 main 分支保护，外部贡献必须经过 Pull Request、自动检查和维护者批准，不能直接强制覆盖正式源码。
修改和提交建议
- 修改
public/或server/后运行npm test和相关专项测试。 - 修改
docs/、README 或许可证后运行npm run test:repo。 - 不提交
dist/、release/、output/、.env、密钥、APK 签名文件和真实用户数据。 - 提交信息使用简短动词，例如
完善管理中心文档、修复移动端灯箱布局。
