我们在此总结 Whiteverse 项目团队使用的技术栈需求以及标准化工作流建议。 除此之外，我们还会在此记录一些项目中的设计经验和技巧，以便于团队成员更好地理解项目的设计规范。 请按需阅读本文档，以便更好地理解我们的工作流程。
接下来的所有内容都以高效合作为核心指导，解放创造力为理想目标。因此如有任何建议和意见，欢迎提交 Issue 或 PR。
- 工作留痕：对自己的工作内容留有记录，无论是汇报总结还是提交记录；
- 版本控制：保证项目历史的透明、可追溯；
- 单一数据源(SSOT)：所有数据从一个权威位置获取，避免重复工作或文件管理系统混乱；
- 团队协作：保证团队成员之间的工作协调，互不冲突；
- 安全性：提升项目资料的容灾能力，避免数据丢失；
- 多平台：支持多种操作系统，方便团队成员的使用；
在开始工作之前，请确保你的工作环境已经准备好。 如果你已是电脑高手，请跳过本节。 以下是部署工作环境的分步下载链接（以Windows为例）：
除了步骤 1，其他软件请创建并登录自己的账号。
本章节讨论了在团队开展工作之前所有角色都应当掌握的技术与工具。这是加入团队前的准备工作。
graph TD
Start[开始工作准备] --> IF{我是电脑高手？}
IF --> |是| F
IF --> |否| A[安装基础软件]
A --> D[学习基础知识]
D --> E1[Git 基本操作]
D --> E2[Markdown 语法]
D --> E3[VS Code 使用]
E1 --> F[掌握工作规范]
E2 --> F
E3 --> F
F --> G1[Git 提交规范]
F --> G2[文档编写规范]
F --> G3[工具使用规范]
G1 --> H[学习专业技术栈]
G2 --> H
G3 --> H
H --> I[完成准备工作]
%% 样式定义
classDef setup fill:#f9f,stroke:#333,stroke-width:2px;
classDef learning fill:#bbf,stroke:#333,stroke-width:2px;
classDef standard fill:#ffd,stroke:#333,stroke-width:2px;
classDef professional fill:#dfd,stroke:#333,stroke-width:2px;
%% 应用样式
class A,B1,B2,C1,C2 setup;
class D,E1,E2,E3 learning;
class F,G1,G2,G3 standard;
class H,I professional;
使用 Git 代表团队工作流的技术原则，是我们工作的基础。
在工作中，我们使用 Github 托管代码、文档和美术资源。因此，必须掌握 Github Desktop 的基本使用方法，包括克隆、提交、拉取、分支等操作。同时，还应当掌握 Git 使用的基本规范，以下是我们提倡的使用规范：
- 先学习，再工作：在开始工作之前，先学习
Github的基本操作——先使用自己的仓库练习。 - 先获取，再提交：
- 在每天开展工作之前，先拉取最新的代码，确保本地代码是最新的。
- 在每次提交代码前，先拉取最新的代码并查看变更记录，确保本地代码是最新的。
- 提交信息 Commit Message： 应当简洁明了，能够清晰地表达本次提交的内容，不应当出现无意义的
Commit Message。 - 变动记录 Diff： 应当仔细查看每次拉取内容的更改，确保对项目的更改有清晰的认识。
- 提交原子化：每次提交应当专注于一个小的功能或修复，避免将多个不相关的更改混合在一起，每个提交应具备独立意义。但是话又说回来了——提交原子化不等于频繁提交。笔者的建议是在自己的分支随便折腾，在合并到main上时，还是要做好总结、Rebase和Squash Merge。
- 分支管理：
- 分支生命周期不要超过 7 天，除非只有你自己在工作。
- 不复刻(
fork)分支，而是作为Collaborator克隆(clone)原仓库，否则管理人员无法维护和监督分支内容。 - 不在主干（如
main或master）上开发，应当在功能分支上开发。 - 一个分支应当只负责一个主要功能(
feature)，一个功能应当包含多个原子化提交。 - 主要功能完成后及时通过
PR (Pull Request)交由审核人审核。 - 审核通过后审核人将决定是否合并(
merge)该分支，并给出修改意见 - 合并后及时删除分支，保持仓库整洁。
P.S. 使用 Github 需要翻墙。
P.S.2. 本技术原则仅限Private仓库。
-
Git：工具，用来管理文件变化。
-
GitHub：托管
Git项目的网站。 -
GitHub Desktop：简化
Git操作的桌面应用。 -
GitLab：类似
GitHub的软件服务，可以自己部署。 -
SVN：另一种版本控制工具。
由于学习成本限制，不要求掌握
Git的高级用法或者命令行操作，但是应当掌握Github Desktop的基本操作。 如果使用其他git工具（如SVNGitKrakenSourceTree等），应当保证提交规范与上述一致，否则可能会导致团队协作的混乱。
- 禁止使用特殊字符：如
\/:*?"<>|等，避免文件系统无法识别。但是如果存在强制置顶的情况，可以在文件名前加#或.。 - 重复确认文件大小写规范：如果使用Windows操作系统，需要注意 Windows 文件系统不区分大小写，但是Git是大小写敏感的，如果这样做会导致版本控制的问题。一概使用大驼峰命名，并混合使用下划线
_作为分隔符。比如Localization_Names.xlsx。 - 全角/半角区分：在文件名和内容中应当区分全角和半角字符，避免混淆。中文（含繁体中文、日语）一概使用全角字符和标点符号，英文则全部使用半角。
- 分隔符：在文件名中使用统一的分隔符，如下划线
_，避免使用空格/连字符 -/破折号 ——/句号 .或其他特殊字符。 - 不同的版本：不要在文件名中使用版本号，或同时保留多个不同版本的文件，而是使用版本控制工具（如 Git）来管理文件的版本。如果你对这一条问题存在疑惑，说明需要重新学习版本控制的基本概念。
- Ignore：在使用 Git 控制版本时，不要将不必要的文件添加到版本库中，如编译生成的文件、临时文件、苹果系统的
.DS_Store等。可以通过.gitignore文件来忽略这些文件。 - 二进制提交注意事项：当活动区存在已经修改过的二进制文件时，不要携带该文件切换分支，否则会导致该文件的修改丢失。应当先提交该文件的修改，或者将其暂存（
git stash）后再切换分支。- 美术源文件（PSD、AI、FBX 等）属于正常资产，不受此限制。
- xlsx文件提交应谨慎，且为了防止出现自动合并导致的数据丢失，请保持分支持续时间的简短——feature完成后立刻考虑合并。
相较于二进制文件，我们使用文本文件以控制版本和推进协作。
- 所有的文字性工作文档应当以
Markdown形式呈现，不允许使用Word文档。 - 应当熟练掌握
Markdown的基本语法，并且能够通过MarkdownLint的检查。 - 请用
Markdown结合插件和mermaid满足诸如表格、代码块、公式、思维导图等任何需求。 - 善用插件，提高工作效率。
P.S. 什么是二进制文件？比如 Word、Excel、PSD、AI 等等，这些文件无法通过文本方式查看和编辑（打开时是乱码），必须使用专用软件打开。而 .md、.csv、.json 等都是文本文件，可以直接通过文本编辑器查看和编辑。
必须使用 VSCode 作为主要的文本/代码编辑器，并且根据库的需求和建议安装相应的插件。
笔者已经在 .vscode\extensions.json 中列出了推荐的插件，建议遵循 vscode 的插件推荐机制（扩展-推荐）安装推荐的插件。
P.S. 禁止使用 NotePad++、Obsidian、Notion、Typora 等不同规范的编辑工具。
在项目中，我们使用 CSV、YAML、JSON 等格式来存储数据，因此应当掌握这些格式的基本语法和使用方法。
- Excel 使用规范：
- 我们不使用
Excel传输数据，只使用Excel设计与编辑数据。 - 在每次编辑完成后，应当使用脚本将其转换为相应的数据格式（如 CSV、JSON），再提交。
- 在没有自动化工作流的情况下禁止直接提交二进制
Excel文件，除非编辑不涉及数据变动。(如筛选、排序、填色等)
- 我们不使用
P.S. 什么是自动化工作流？以Github Action为例，一个设定好的Github Action可以在每次提交后自动将Excel转换为CSV并提交到指定位置，就解放了手动转换的工作。不过你仍然需要等待Action运行完成、Action自动提交完成后再拉取最新代码，以确保数据是最新的。（一般需要3分钟左右）
P.S.2. 为什么有时候我的.csv文件都是乱码？因为有些软件（如 Excel）会将 CSV 文件保存为带有特殊编码的格式（如 UTF-8 with BOM），导致无法通过文本编辑器正确显示。反之亦然。
我们应掌握 AI 工具的基本使用方法以提高工作效率。
AI 工具的使用应当是辅助性的，不应当取代人工的创造性工作。
应当明确以下几个原则：
- 禁止使用 AI 作为最终创作成果：任何涉及核心创意的工作（如文本创作、设计创作、艺术创作等）禁止直接使用 AI 工具生成最终成果。创作过程应当以人类的独特思维和创造力为主导，AI 仅可作为灵感辅助工具。
- 谨慎使用 AI 生成数据：AI 工具在数据生成和推理任务中可能存在偏差或错误，尤其是在涉及复杂逻辑或专业知识时。因此，AI 生成的数据或推理结果必须经过人工验证和校准，以确保其准确性和可靠性。
- 代码生成：AI 工具可以用于生成代码片段或自动化重复性编码任务，但生成的代码必须经过人工审查，确保其质量、可读性和安全性。同时，生成的代码应符合项目规范和最佳实践。
- IDE友好：你可能会产生一种疑问：“为什么我一个非代码人员，也需要关注和使用VSCode和Markdown这种明显是编程工作者的工具？”事实上，如果你使用Markdown和IDE的方法得当，那么AI工具的使用效率会大大提升。目前主流的AI工具都支持Markdown格式的输入输出和自动代码或文本段落补全。
- 了解 AI 的能力边界：AI 能够做到什么？AI会伪装能够做到但实际存在问题的是什么？AI 完全不能做到什么？与时俱进地了解 AI 技术的发展和局限性，避免过度依赖或误用 AI 工具。
- AI 不拥有决策权：AI 可以提供选项，但最终决定必须由人类作出。
AI 审查：任何审核人员有权质疑生成的内容，即便它未被标注为 AI 生成。审核人员有权要求提供生成内容的来源和依据，并对确认为 AI 生成的内容有修改和否决权。
隐私责任：如果你认为某些资料是不可以展示给人类的，那么它同样不应该被 AI 使用和学习。
我们要求每个团队成员都具有良好的阅读文档能力，能够快速理解和应用文档中的内容，并且通过参考文档辅助工作。
- 在遇到问题时，应当首先查阅文档，尝试自行解决问题。
- 与项目成员以及主管及时沟通，保持知会。
- 每次使用文档前，查看最新版本，尤其是变动的部分（这一环节需要查看
Commit log & diff）。
英语能力并非仅指对于语言本身的掌握程度，而是指对正确语义的理解和表达：比如统一化的命名、关键名词的使用和近义词的区分等，避免产生任何歧义。 如果项目已经存在了相关术语表，应当遵循术语表中的规范来命名，在设计术语时，更应该与项目成员和主管沟通和论证。切勿随意更改术语。 同时，项目成员应当具备一定的英文阅读能力或使用翻译工具的能力；后者应当注意翻译工具的准确性，懂得分辨正误。
各专业技术人员应当掌握的专业技能和工具，请导航到对应的章节。
-
Q：我能不能直接在 main 上改？
A：不能，见「分支管理」。除非是已批准的。 -
Q：我有 50 个 commit，能不能直接 PR？
A：不行，请先 rebase / squash。 -
Q：Excel 我只改了颜色 / 筛选 / 排序，算不算改动？
A：算。但是可能出现工具识别不出的情况。 -
Q：我每天都在 pull，为什么还会有冲突？ A：因为你和别人改了同一份文件。 解决方式： 先看 diff，理解别人的改动 再决定是保留、修改还是重构 永远不要盲目点 “Accept All”。
-
Q：我在自己的分支随便提交，算不算违反规范？ A：不算。但 一旦准备合并到 main，就必须遵守提交规范。分支是临时的，历史是永久的。
-
Q：PR 被拒绝了，是不是很丢脸？ A：不是。PR 被拒绝 = 在合并前发现问题 = 成功拦截风险。
-
Q：为什么要这么麻烦？群聊也很方便。 A：群聊是“即时”的，但也是“瞬时”的。我们的规范是为了把“沟通结果”沉淀为“项目资产”。群聊适合打招呼，规范适合做项目。
