本文件约束 content/ 下内容源文件与软件发布流程。站点级全局约束见根 AGENTS.md。

---

1. 内容更新机制

• 编译期更新：修改 content/ 下 Markdown 源文件，重新编译后部署。
• 运行期更新：通过后台管理界面增删改，即时写入磁盘，无需重新编译。
• 合并规则：运行时动态内容优先级高于编译期内容，可覆盖同名/同路径内容。
• 页面同步：内容新增、修改或删除后，必须由同一合并内容快照重建公开页面、首页/栏目列表和 sitemap，完成后整体替换旧 PageStore。

---

2. 内容源文件规范

• 格式：Markdown + YAML Frontmatter。
• 目录结构：

  content/
  ├── software/
  ├── tutorials/
  ├── reviews/
  ├── code/
  ├── about.md
  └── _meta.yaml
  

• 图片等资源与各栏目同级或子目录中，通过相对路径引用。

---

3. YAML Frontmatter 字段

---
title: "文章标题"              # 必填
slug: "article-slug"           # 选填，默认从文件名生成
date: "2024-01-15"             # 必填
updated: "2024-01-20"          # 选填
tags: ["rust", "web"]          # 选填
category: "software"           # 选填
description: "摘要..."         # 选填
cover: "images/cover.png"      # 选填
author: "作者名"               # 选填
status: "published"            # 选填：published / draft / archived
priority: 0                    # 选填，越大越靠前

# 软件发布专用字段（category 为 software 时有效）
version: "1.0.0"               # 选填，版本号
source_url: "https://github..." # 选填，源码仓库链接
platform: "Windows"            # 选填，支持平台
file_size: "12.5 MB"           # 选填，文件大小（人类可读）
download_url: "https://..."    # 选填，单一下载链接（外部 URL 或 /download/文件名）
downloads:                     # 选填，多平台下载列表（优先级高于 download_url）
  - label: "Windows 版下载"
    url: "https://github.com/.../xxx-windows.zip"
  - label: "Linux 版下载"
    url: "https://github.com/.../xxx-linux.tar.gz"
---

_meta.yaml 全局元数据：

site_name: "逻辑拾光"
author: "作者名"
site_description: "..."
icp_beian: "粤ICP备2026066577号-1"
police_beian: "粤公网安备44011802001419号"
contact_email: "..."

---

4. Markdown 渲染支持范围

• 六级标题、段落、加粗/斜体/删除线、行内代码
• 无序/有序列表、任务列表、表格
• 代码块（带语言标注）、LaTeX（$...$ / $$...$$）、Mermaid 流程图
• 引用块、水平分割线、链接与图片
• 不支持脚注

LaTeX 与流程图由前端浏览器渲染，按需加载 KaTeX/Mermaid CDN，CDN 失败时 fallback 到本站 /assets/vendor/。

---

5. 代码高亮

• 覆盖语言：Markdown、JavaScript/TypeScript、Python、Shell/Bash、PowerShell、Batch、Java、Kotlin、C/C++/C#、Objective-C/Swift、Rust、Go、XML/HTML/CSS、YAML、JSON。
• 执行方：前端 JS 原生词法分析状态机，单文件 < 15 KiB，DOMContentLoaded 后渲染。

---

6. 软件发布系统

6.1 发布流程

1. 收集信息（由用户提供）：

   【软件发布】名称、版本、简介、平台、文件大小
   【发布方式】外部链接 / 本地上传 / 纯源码
   【下载链接】【源码链接】【截图】
   

2. 选择发布方式：

   • 外部链接（推荐）：下载文件托管于 GitHub Releases / Gitee / 网盘等。若只有一个下载文件，填写 download_url；若有多个平台（Windows / Linux / macOS 等），使用 downloads 列表为每个平台提供直链，按钮会自动显示为「Windows 版下载」等平台名称。适合大文件，不占用服务器带宽。
   • 本地上传：将文件放入 download/ 目录（生产环境为 /home/muka/mukacool/download/），download_url 填写为 /download/文件名。适合小文件（< 50 MB），受 3Mbps 带宽限制。
   • 纯源码：无下载文件，仅填写 source_url 指向源码仓库。

3. 创建内容：

   • 编译期：在 content/software/ 创建 Markdown 文件，填写 Frontmatter（含软件发布字段）与正文。
   • 运行期：通过后台管理界面填写表单字段，即时发布。

4. 验证：访问文章详情页，确认下载区域正确显示版本号、平台、文件大小、各平台下载按钮（或单个下载按钮）与源码按钮。

6.2 下载路由

• /download/ 下的文件以 Content-Disposition: attachment 方式提供下载。
• 支持 MIME 类型：.zip、.exe、.dmg、.apk、.tar.gz、.7z、.rar、.deb、.rpm、.msi、.appimage、.pdf 等。
• 路径遍历防护：通过 canonicalize 校验，禁止访问 download/ 目录之外的文件。

6.3 带宽建议

• 服务器带宽 3 Mbps（约 375 KB/s）。
• 优先使用外部下载链接（GitHub Releases 等）。
• 本地上传仅适合小体积文件（< 50 MB），避免同时多用户下载造成拥塞。