docs: add project documentation to docs/ folder#3
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Co-authored-by: neokoni <90206655+neokoni@users.noreply.github.com>
There was a problem hiding this comment.
Pull request overview
Adds a structured docs/ documentation set (Chinese-language) to replace the previous “only Vite boilerplate README” situation, covering local development, architecture, OTA data conventions, and deployment.
Changes:
- Added a docs index and getting-started guide for local development and scripts.
- Documented project architecture (routing, data flow, and custom Vite plain-text changelog plugins).
- Documented OTA JSON schema, device addition workflow, OTA JSON generation script usage, and deployment details.
Reviewed changes
Copilot reviewed 7 out of 7 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/README.md | Documentation index + project/stack overview |
| docs/getting-started.md | Local dev prerequisites, commands, and repo layout |
| docs/architecture.md | Architecture, routing, data flow, and Vite plugin behavior |
| docs/adding-devices.md | How to add devices/systems/versions via src/ota/*.json |
| docs/ota-json-format.md | OTA updater-consumed ota.json schema and path conventions |
| docs/generate-ota-json.md | How to use scripts/generate_ota_json.py |
| docs/deployment.md | GitHub Actions + server deployment and history-mode fallback |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| "systems": [ | ||
| { | ||
| "name": "ROM名称", // 例如 "AviumUI" | ||
| "description": "简介", // 可选 |
There was a problem hiding this comment.
这里标注 systems[].description 为“可选”，但当前类型定义 src/config/devices.ts 的 SystemConfig 将 description 声明为必填 string。为避免新增设备 JSON 时产生困惑，建议文档与类型保持一致：要么把文档改为必填，要么先把 SystemConfig.description 改为可选后再在文档中说明可选。
| "description": "简介", // 可选 | |
| "description": "简介", // ROM 简介 |
| ### 配置 GitHub Secrets | ||
|
|
||
| 自动部署需要在 GitHub 仓库的 **Settings → Secrets and variables → Actions** 中配置以下 Secrets： | ||
|
|
||
| | Secret 名称 | 说明 | | ||
| |-------------|------| | ||
| | `SERVER_HOST` | 服务器 IP 地址或域名 | | ||
| | `SERVER_USERNAME` | SSH 登录用户名 | | ||
| | `SERVER_PASSWORD` | SSH 登录密码 | | ||
|
|
There was a problem hiding this comment.
部署文档仅列出了使用 SERVER_PASSWORD 的密码登录方式。为降低凭据泄露风险，建议补充（或优先推荐）基于 SSH Key 的配置方式（例如在 Secrets 中存放私钥并在工作流中改用 key/ssh-key 参数），并提示服务器侧可禁用密码登录。
| ## 输出路径 | ||
|
|
||
| 生成的 `ota.json` 将保存至： | ||
|
|
||
| ``` | ||
| public/{ROM名称}/{版本标识}/{设备代号}/ota.json | ||
| ``` | ||
|
|
||
| 例如，处理 `AviumUI-16.2.0-nabu-20260226-Unofficial-GMS.zip` 时，输出路径为： | ||
|
|
||
| ``` | ||
| public/AviumUI/AviumUI-16.2.0-nabu/nabu/ota.json | ||
| ``` |
There was a problem hiding this comment.
“输出路径”示例与当前 scripts/generate_ota_json.py 的实际写入逻辑不一致：脚本默认会把目录版本段写成 rom_name_normalized-rom_ver（例如 avium-16.2.0），而不是示例中的 AviumUI-16.2.0-nabu；且当传入 --version 时目录版本段会直接使用 --version 的值。建议更新这里的示例/说明以与脚本输出保持一致（或同步调整脚本输出规则）。
| 2. 配置 Node.js 环境（actions/setup-node@v4，使用 latest 版本） | ||
| 3. 安装依赖（npm install） | ||
| 4. 构建项目（npm run build → 输出到 dist/） | ||
| 5. 通过 SCP 将 dist/ 上传到服务器（appleboy/scp-action@v0.1.7） |
There was a problem hiding this comment.
The deployment workflow relies on a third-party GitHub Action appleboy/scp-action@v0.1.7 pinned only to a version tag, which is a mutable reference. If the action author’s repository or release tag is compromised, an attacker could ship a malicious update under the same tag and your CI job would execute it with access to SERVER_HOST, SERVER_USERNAME, and SERVER_PASSWORD. To reduce this supply chain risk, pin appleboy/scp-action to a specific commit SHA in .github/workflows/deployment.yml and periodically review/update it as needed.
Project lacked any documentation beyond a boilerplate Vite README. Added structured Chinese-language docs covering the full project.
New files
docs/README.md— Index with project overview and tech stackdocs/getting-started.md— Local dev setup, available npm scripts, recommended toolingdocs/architecture.md— Directory layout, routing table, data flow (import.meta.glob→devices.ts→ views), and the two custom Vite plugins (bpPlainTextMiddleware/alwaysPlainTextPagePlugin) that serve plain-text changelogs for in-ROM updater appsdocs/adding-devices.md— How to add devices/systems/versions by dropping a JSON file intosrc/ota/; no other registration neededdocs/ota-json-format.md— Schema forpublic/{ROM}/{version}/{codename}/ota.jsonconsumed by OTA updater appsdocs/generate-ota-json.md— Usage guide forscripts/generate_ota_json.py(CLI args, filename parsing rules, output path logic)docs/deployment.md— GitHub Actions workflow, required Secrets, SCP target path, and web server history-mode fallback configOriginal prompt
Created from VS Code.
🔒 GitHub Advanced Security automatically protects Copilot coding agent pull requests. You can protect all pull requests by enabling Advanced Security for your repositories. Learn more about Advanced Security.