software-workspace/docs/create-project.md

新增项目详细指南

本指南说明如何在 SoftwareWorkspace 网站中新增一个完整的项目条目。

---

涉及文件总览

步骤	文件	是否必须
1	src/data/projects/<项目id>.yaml	必须
2	src/utils/iconRegistry.ts	仅当使用新图标时
3	src/data/categories.yaml	仅当新增分类时
4	src/data/statuses.yaml	仅当新增状态时
5	public/logos/	仅当有项目 Logo 时
6	public/screenshots/	仅当有截图时

核心原则： 只需创建一个 YAML 文件，项目就会自动出现在网站上。loader.ts 使用 import.meta.glob('./projects/*.yaml') 自动扫描该目录，无需手动注册。

---

步骤一：创建项目 YAML 文件

在 src/data/projects/ 下新建文件，文件名即项目 ID（小写，用连字符分隔）。

例如：src/data/projects/my-new-app.yaml

完整字段模板

# ========== 基础信息 ==========

# 项目唯一标识（与文件名一致，用于 URL 路由 /projects/:id）
id: 'my-new-app'

# 项目内部名称（英文，小写）
name: 'my-new-app'

# 显示名称（双语，通常首字母大写）
displayName:
  zh: '我的新应用'
  en: 'My New App'

# 一句话简介（显示在卡片和详情页标题下方）
slogan:
  zh: '一句话中文描述'
  en: 'A one-line English description'

# 详细描述（显示在详情页"概览"区域）
description:
  zh: '详细的中文介绍，说明项目功能、技术特点和适用场景。'
  en: 'Detailed English introduction explaining features, technical highlights and use cases.'

# ========== 分类与状态 ==========

# 项目分类，可选多个（对应 categories.yaml 中的 id）
# 可用值：desktop / mobile / devtool / library / backend / selfhosted / ai
type:
  - 'desktop'

# 开发状态（对应 statuses.yaml 中的 key）
# 可用值：active / maintained / beta / experimental / archived
status: 'active'

# ========== 技术信息 ==========

# 支持平台（对应 platforms.yaml 中的 key）
# 可用值：windows / macos / linux / android / ios / web / docker / npm / cli
platforms:
  - 'windows'
  - 'macos'
  - 'linux'

# 技术栈标签（自由填写，会出现在筛选下拉和项目卡片上）
techStack:
  - 'Rust'
  - 'TypeScript'
  - 'React'

# 核心功能列表（双语，显示在详情页"核心功能"区域）
features:
  zh:
    - '功能一'
    - '功能二'
    - '功能三'
  en:
    - 'Feature one'
    - 'Feature two'
    - 'Feature three'

# 搜索标签（用于搜索框模糊匹配，界面上不直接展示）
tags:
  - 'Keyword1'
  - 'Keyword2'
  - 'Keyword3'

# ========== 图标与链接 ==========

# 项目图标（lucide-react 图标名称）
# 已注册的图标：NotebookPen / Terminal / MapPin / SmartPhone / BookOpen /
#               Monitor / Brain / KeyRound / Wrench / Package / Cloud / Server / FlaskConical
# 如果需要新图标，见"步骤二"
icon: 'Terminal'

# 项目 Logo 图片（可选，支持 SVG/PNG/JPG）
# 图片放在 public/logos/ 目录下，路径相对于 public 目录
# 若设置了 logo，卡片和详情页会优先展示 Logo 图片，否则回退到上面的 lucide 图标
# logo: '/logos/my-new-app.png'

# GitHub 仓库地址（必须）
repoUrl: 'https://github.com/shenjianZ/my-new-app'

# 在线文档地址（可选，不填则不显示文档按钮）
docsUrl: 'https://github.com/shenjianZ/my-new-app#readme'

# npm 包地址（可选，仅 NPM 包类项目填写）
# npmUrl: 'https://www.npmjs.com/package/my-new-app'

# ========== 版本信息 ==========

latestVersion: 'v1.0.0'
releaseDate: '2026-05-22'
license: 'MIT'
language: 'TypeScript'
lastUpdated: '2026-05-22'

# ========== 首页展示控制 ==========

# 是否在首页"重点项目"区域展示（true/false）
recommended: false

# 是否在首页"Featured"大卡片展示（true/false，通常只给 1-2 个项目）
featured: false

# 排序权重（数字越小越靠前）
order: 9

# 卡片主题色（十六进制色值）
color: '#3B82F6'

# ========== 下载信息（可选） ==========

# 如果没有下载功能，设为空数组 []
downloads:
  - platform: 'Windows'
    arch: 'x64'
    url: 'https://github.com/shenjianZ/my-new-app/releases/download/v1.0.0/my-new-app-setup.exe'
    size: '15 MB'
    sha256: ''
  - platform: 'macOS'
    arch: 'universal'
    url: 'https://github.com/shenjianZ/my-new-app/releases/download/v1.0.0/my-new-app.dmg'
    size: '18 MB'
    sha256: ''
  - platform: 'Linux'
    arch: 'x64'
    url: 'https://github.com/shenjianZ/my-new-app/releases/download/v1.0.0/my-new-app.AppImage'
    size: '14 MB'
    sha256: ''

# ========== 路线图（可选） ==========

roadmap:
  done:
    - '已完成的功能'
  doing:
    - '正在开发的功能'
  planned:
    - '计划中的功能'

# ========== 更新日志（可选） ==========

changelog:
  - version: 'v1.0.0'
    date: '2026-05-22'
    changes:
      zh:
        - '初始发布'
        - '核心功能上线'
      en:
        - 'Initial release'
        - 'Core features launched'

# ========== 架构说明（可选） ==========

architecture:
  zh: '前端 (React) → API 层 → 后端 (Rust)'
  en: 'Frontend (React) → API Layer → Backend (Rust)'

# ========== 截图（可选） ==========

# 截图文件放在 public/screenshots/<项目id>/ 目录下
# screenshots:
#   - '/screenshots/my-new-app/main.png'
#   - '/screenshots/my-new-app/settings.png'

# ========== 安装指南（可选） ==========
# 每个项目生产的安装包不同，按实际包格式填写即可
# 会以紧凑的单行提示展示在"下载安装"区域内
# 不填写则使用默认的通用安装说明

installGuide:
  zh:
    - platform: 'Windows'
      icon: '🪟'
      format: '.exe'
      tip: 'SmartScreen 拦截？点击"更多信息" → "仍要运行"'
    - platform: 'macOS'
      icon: '🍎'
      format: '.dmg'
      tip: '提示已损坏？终端运行: xattr -dr com.apple.quarantine /Applications/MyApp.app'
    - platform: 'Linux'
      icon: '🐧'
      format: '.AppImage'
      tip: 'chmod +x MyApp-*.AppImage && ./MyApp-*.AppImage'
  en:
    - platform: 'Windows'
      icon: '🪟'
      format: '.exe'
      tip: 'SmartScreen blocked? Click "More info" → "Run anyway"'
    - platform: 'macOS'
      icon: '🍎'
      format: '.dmg'
      tip: '"Damaged" error? Run: xattr -dr com.apple.quarantine /Applications/MyApp.app'
    - platform: 'Linux'
      icon: '🐧'
      format: '.AppImage'
      tip: 'chmod +x MyApp-*.AppImage && ./MyApp-*.AppImage'

---

步骤二（仅在需要新图标时）：注册图标

如果 icon 字段需要使用一个尚未注册的 lucide-react 图标，编辑 src/utils/iconRegistry.ts：

// 1. 在 import 中添加新图标
import {
  // ... 已有图标
  Zap,  // 新增
} from 'lucide-react';

// 2. 在 iconRegistry 对象中注册
const iconRegistry: Record<string, ComponentType<{ size?: number }>> = {
  // ... 已有图标
  Zap,  // 新增
};

然后在 YAML 中 icon: 'Zap' 即可。

---

步骤三（仅在需要新分类时）：添加分类

编辑 src/data/categories.yaml，追加新分类：

- id: 'new-category-id'
  label:
    zh: '新分类中文名'
    en: 'New Category Name'
  icon: 'IconName'  # 需要在 iconRegistry 中已注册

然后在项目的 type 字段中使用该 id。

---

步骤四（仅在需要新状态时）：添加状态

编辑 src/data/statuses.yaml，追加新状态：

new-status:
  label:
    zh: '中文状态名'
    en: 'English Status Name'
  color: '#HEXCOLOR'

---

步骤五（仅在有截图时）：添加截图

1. 在 public/ 下创建目录：public/screenshots/<项目id>/
2. 放入截图文件（推荐 PNG 格式）
3. 在 YAML 中引用：

screenshots:
  - '/screenshots/my-new-app/main.png'
  - '/screenshots/my-new-app/feature.png'

---

步骤六：验证

1. 启动开发服务器：pnpm dev
2. 检查以下页面：
   • 首页：项目出现在"最新发布"区域；若 featured: true 则出现在 Featured 大卡片
   • 项目列表页：项目出现在列表中，技术栈/平台/状态筛选均生效
   • 项目详情页：访问 /projects/<项目id>，所有信息正确展示
   • 搜索：在搜索框输入 tags 中的关键词，能搜索到该项目
3. 运行测试：pnpm test（siteData 测试会验证数据结构完整性）

---

可用值速查

type（分类）

id	中文	英文
desktop	桌面软件	Desktop Apps
mobile	移动应用	Mobile Apps
devtool	开发者工具	Dev Tools
library	NPM / 组件库	NPM / Libraries
backend	后端服务	Backend
selfhosted	自托管	Self-hosted
ai	AI / 实验项目	AI / Experiments

status（状态）

key	中文	英文	颜色
active	活跃开发	Active	#22C55E
maintained	维护中	Maintained	#3B82F6
beta	测试版	Beta	#F59E0B
experimental	实验性	Experimental	#A855F7
archived	已归档	Archived	#6B7280

platforms（平台）

windows / macos / linux / android / ios / web / docker / npm / cli

已注册图标

NotebookPen / Terminal / MapPin / SmartPhone / BookOpen / Monitor / Brain / KeyRound / Wrench / Package / Cloud / Server / FlaskConical

---

数据流示意

src/data/projects/<id>.yaml
  ↓ import.meta.glob 自动扫描
src/data/loader.ts（解析为 Project 对象，按 order 排序）
  ↓ 导出 siteData
src/pages/HomePage.tsx     → 首页卡片、Featured、最新发布
src/pages/ProjectsPage.tsx → 项目列表 + 筛选
src/pages/ProjectDetailPage.tsx → 详情页（/projects/:id）

只需创建 YAML 文件，无需修改任何 TypeScript 代码，项目即自动上线。