main：稳定版本，只存放已测试、可部署代码 ⚠ 禁止直接在 main 上开发
✔ 开发分支
每个成员开发功能必须新建功能分支：
feature/<功能名> bugfix/<修复内容> hotfix/<紧急修复> refactor/<重构内容>
示例：
✔ 2. 加入 GitHub Actions
main：稳定版本，只存放已测试、可部署代码main 上开发feature/<功能名>bugfix/<修复内容>hotfix/<紧急修复>refactor/<重构内容>目的：统一团队协作流程，减少合并冲突，提高代码质量与交付效率。优先保证
main分支始终可部署。
总体原则：
main（或 release）为稳定、可部署分支；所有开发活动在临时分支完成并通过 PR 合并。推荐分支类型与用途：
main：生产/部署分支，仅可通过合并 PR 更新（受分支保护策略管控）。develop（可选）：汇总短期开发成果的集成分支；团队较大或需要持续集成时建议使用。若使用此分支，Feature 分支应合并到 develop，release 从 develop 发出并合并回 main 与 develop。feature/<短描述>：新功能分支，仅包含一个明确的功能点或任务（如 feature/login-oauth）。bugfix/<短描述>：用于修复开发中发现但不紧急的问题（合并到 develop 或 main 视流程而定）。hotfix/<短描述>：用于线上紧急问题，直接从 main 创建，修复后需合并回 main 和 develop（若存在）。release/<x.y.z>（可选）：准备发布的分支，用于最后的集成测试与版本号调整，测试通过后合并回 main 并打 tag。refactor/<短描述>：仅用于重构，要求在 PR 中说明不改变外部行为。分支命名规范（示例）：
feature/auth-jwt
bugfix/login-redirect
hotfix/critical-500
refactor/api-client
release/1.2.0
常见操作命令（示例）：
# 从远程更新本地 main
git checkout main
git pull origin main
# 创建 feature 分支
git checkout -b feature/auth-jwt
# 在分支上工作、提交、推送
git add .
git commit -m "feat(auth): add JWT login"
git push -u origin feature/auth-jwt
PR 与合并策略：
合并到main分支必须经过bosprimigenious审核
main（或 develop）必须通过 Pull Request。PR 要求至少一个代码评审者通过（人数可在分支保护中设置）。Merge commit（默认），有利于保留上下文；Squash and merge，把多次提交合并为一次有意义提交；rebase，以避免复杂的历史重写风险。冲突处理（简单流程）：
git fetch origin，切换目标分支并 git pull。git merge origin/main（或 origin/develop），解决冲突并 git add 冲突文件。git commit（必要时），再 git push 到远程分支，PR 会自动更新。示例：从 main 合并到 feature 并解决冲突：
git checkout feature/auth-jwt
git fetch origin
git merge origin/main
# 解决冲突后
git add conflicted_file.py
git commit -m "fix: resolve merge conflicts with main"
git push
分支生命周期建议：
main 与 develop，打上补丁版本号。权限与分支保护（建议在 GitHub 上配置）：
main 启用 Branch protection：
规则：
<type>(<scope>): <short summary>，例如：feat(auth): add JWT loginfeat、fix、docs、style、refactor、test、chorefeat(auth): add JWT login
- 支持 access/refresh token
- 增加 token 刷新路由
Git 提交示例命令：
git add changed_file.py
git commit -m "feat(api): add inference endpoint"
在仓库中添加 .github/PULL_REQUEST_TEMPLATE.md 可强制 PR 填写必要信息。建议内容：
feat/fix/docs/chore 等评审要点清单：
建议在 main/develop 的 PR 检查中加入以下 CI：
black（Python）、Prettier（JS）flake8（Python）、ESLint（JS）mypy（可选）、tsc（如使用 TS）可用动作：.github/workflows/ci.yml 配置自动在每个 PR 运行上述检查并把结果作为合并前必须通过的状态检查。
场景：你完成了登录功能，需要把它合并到主线并发布到测试环境。
流程：
git checkout -b feature/login-oauth
# 开发、提交多次
git push -u origin feature/login-oauth
打开 GitHub 创建 PR（目标分支 develop 或 main），填写 PR 模板。
CI 运行，审查者 review 并提出修改意见 → 按照建议修复并 push。
CI 全部通过并获得审批，合并方式选择 Squash and merge（使历史清晰）。
若合并到 main，在合并后打 tag 发布：
git checkout main
git pull origin main
git tag -a v1.2.0 -m "Release v1.2.0"
git push origin v1.2.0
develop，请确保把变更合并回 main（并发 release 流程）。常见问题：
git merge origin/main），按文件逐一解决，鼓励小步提交与更频繁的合并。# 克隆
git clone <repo>
# 查看远程
git remote -v
# 创建并切换分支
git checkout -b feature/xxx
# 提交
git add .
git commit -m "feat: ..."
# 推送分支
git push -u origin feature/xxx
# 合并远端 main 到当前分支
git fetch origin
git merge origin/main
# 删除远端分支
git push origin --delete feature/old
项目复盘不是流水账。好的复盘应该让别人快速看懂：你做了什么、为什么这样做、遇到了什么问题、最后学到了什么。
可以按这个模板写：
1. 项目背景
2. 技术栈
3. 我的职责
4. 核心功能
5. 难点与解决方案
6. 最终效果
7. 反思与改进
背景不用写太长，重点回答：
例如：为了降低团队开发规范执行成本，做一个自动检查提交和分支规则的工具。
不要只写“参与开发”。可以写得具体一点：
具体职责能体现个人贡献。
难点最好按“问题 -> 分析 -> 方案 -> 结果”写。
示例：
问题：项目卡片图片高度不一致，导致列表布局跳动。
分析：图片原始尺寸不统一，缺少固定比例容器。
方案：使用 aspect-ratio 固定 16:9，并用 object-fit: cover。
结果：卡片高度稳定，页面扫描体验更好。
反思可以写：
项目复盘要少写口号，多写事实。越具体，越能体现工程能力。
]]>调试不是靠感觉乱改。越复杂的问题，越要先缩小范围，再验证假设。
不能稳定复现的问题，很难真正修好。先记录：
复现步骤越短，问题越容易定位。
很多报错会连锁出现。不要只看最后一行，先找第一处异常。
前端常看：
后端常看：
如果不知道哪次改动引入了问题，可以用二分思路：
Git 里也可以用 git bisect，但日常手动二分也很有效。
不要只写：
console.log("here");
更好的写法：
console.log("submit payload", payload);
console.log("api response", response);
日志要能回答“程序现在拿到了什么数据”。
调试时一次改太多东西，很难知道到底是哪一处生效。先提出假设，再做最小修改验证。
建议在 PR 或提交信息里写清楚：
这样下次遇到类似问题时，可以直接查历史。
]]>接口设计最重要的是稳定和清楚。前后端协作时，接口文档写得越模糊，联调时越容易互相猜。
资源用名词，不要用动词堆路径：
GET /api/projects
GET /api/projects/:id
POST /api/projects
PATCH /api/projects/:id
DELETE /api/projects/:id
动作由 HTTP 方法表达，路径表达资源。
列表查询常见参数：
page=1
pageSize=20
keyword=xxx
category=frontend
复杂筛选条件要提前约定字段名和类型，不要等联调时临时加。
建议统一结构：
{
"code": 0,
"message": "ok",
"data": {}
}
分页可以这样：
{
"code": 0,
"message": "ok",
"data": {
"items": [],
"total": 100,
"page": 1,
"pageSize": 20
}
}
错误信息要能帮助定位问题：
{
"code": 40001,
"message": "invalid project title"
}
不要只返回 error 或 failed。
同一个项目里要统一风格：
camelCase：createdAtsnake_case：created_at前端项目常用 camelCase，数据库常用 snake_case。如果需要转换，最好在接口层统一处理。
接口不是后端一个人的东西，而是前后端共同维护的契约。
]]>Markdown 是一种轻量级的标记语言，常用于写作文档、博客、技术文档等。其语法简洁，易于学习，广泛应用于 GitHub、博客、论坛等平台。
Markdown 使用 # 来表示标题。# 的数量决定了标题的级别。
# 一级标题
## 二级标题
### 三级标题
#### 四级标题
##### 五级标题
###### 六级标题
Python 项目最常见的问题之一是依赖混乱。虚拟环境的作用就是把不同项目的依赖隔离开，避免 A 项目升级包以后把 B 项目搞坏。
python -m venv .venv
推荐把虚拟环境放在项目根目录，命名为 .venv。
macOS / Linux：
source .venv/bin/activate
Windows PowerShell：
.\.venv\Scripts\Activate.ps1
激活后，终端前面通常会出现 (.venv)。
pip install requests
pip install -r requirements.txt
保存依赖：
pip freeze > requirements.txt
deactivate
先确认：
which python
which pip
如果路径不在 .venv 里，说明虚拟环境没有激活。
pip freeze 会把所有间接依赖也写进去。小项目可以接受，大项目建议使用 pyproject.toml、uv 或 Poetry 管理依赖。
虚拟环境不会自动解决 Python 解释器版本问题。创建环境前要先确认：
python --version
.venv/ 加到 .gitignore。requirements.txt 或 pyproject.toml。环境问题越早规范，后面协作越省时间。
]]>package.json 文件的文件夹。npm install，安装 package.json 中列出的所有依赖。npm install <包名>，安装一个或多个包，并将它们加入到 node_modules。npm install <包名>@<版本号>，如 npm install react@17.0.0。--save（默认）或 --save-dev 标志。
--save：将包作为生产依赖安装。--save-dev：将包作为开发依赖安装。npm update，根据 package.json 更新所有依赖包。npm uninstall <包名>，卸载指定的依赖包。npm init 或 npm init -y（跳过交互式初始化，使用默认配置）。npm start，通常会启动 package.json 中的 start 脚本。npm run <script-name>，例如运行 npm run build 或 npm run test。npm run，列出所有可执行的脚本。npm install <包名> --save-dev，例如安装 webpack。npm install <包名> --save 或不带任何标志。npm cache clean --force，清除 npm 缓存。npm install <包名>@latest，安装最新版本的包。npm list <包名>，查看已安装的包及其版本。npm list -g。npm install -g <包名>，全局安装工具包（例如 eslint, typescript）。npm uninstall -g <包名>。npm install <包名>@<版本号>，回退到指定版本的包。npm info <包名>，查看包的版本信息和历史。package.json 中，依赖版本可以使用不同的符号：
^：允许自动安装小版本更新（例如 ^1.2.3 可以安装 1.x.x 版本）。~：只允许安装修复版本更新（例如 ~1.2.3 可以安装 1.2.x 版本）。*：允许安装任意版本。>=：指定版本及其以上版本。<=：指定版本及其以下版本。npm login 登录 npm 帐号。npm publish 发布包。npm version <new-version> 更新版本号。npm deprecate <包名>@<版本> 标记不再使用的版本。npm ls，查看项目中所有安装的依赖和子依赖。npm info <包名>，查看包的详细信息（例如版本、作者、文档链接等）。npm config set registry <新地址>，更改默认的 npm registry。npm config list，列出当前的 npm 配置。npm config set cache <路径>，指定缓存目录。package.json 文件的 scripts 部分，指定 start 脚本。{
"scripts": {
"start": "node app.js",
"build": "webpack"
}
}
npm install <包名> --prefix <路径>，将包安装到指定目录。并行安装依赖：使用 npm ci 来更快地安装依赖，尤其是用于 CI/CD 环境。
离线安装：使用 npm install --offline，仅使用缓存中的包进行安装。
使用 npm audit 来检测项目的安全性，确保依赖项没有已知的漏洞。
使用 npm outdated 来检查是否有过时的依赖，确保项目使用最新版本的包。
使用 npm ci 来进行自动化部署，它比 npm install 更加快速且可靠。
npm 官方文档：https://docs.npmjs.com
npm 使用最佳实践：保持 package.json 的清晰与简洁，避免多余的依赖和重复的版本范围。
git add）。git commit）。git add <文件/目录>，如 git add . 或 git add README.md，将文件添加到暂存区。git commit -m "版本描述"，提交暂存区的修改并生成一个新版本。git pushgit pullgit clone <仓库地址>.gitssh-keygen -t rsa -b 4096 -C "xxx@email.com"cat ~/.ssh/id_rsa.pubssh -T git@gitee.com （如成功提示“Welcome to Gitee.com, YourName！”）git remote -vgit remote add origin <远程仓库URL>git remote set-url origin <新URL>git clone 命令从远程仓库获取代码：
git clone <远程仓库URL> <目标目录>git push -u origin mastergit pushgit pullmkdir myfolder（感觉New-Item更加好用一点）mkdir -p a/b/c
-p 参数，需逐级创建。New-Item -Path "filename.txt" -ItemType Fileecho "" > filename.txt（创建空文件）git checkout <branch-name>git checkout -b <branch-name>mkdir 不支持 -p 参数，需要逐级创建目录。echo > filename 时，可能会出现“等待输入状态”，直接按回车即可。工作区 → (git add) → 暂存区 → (git commit) → 版本库 → (git push) → 远程仓库
↑ |
└─── (git pull) ───────┘
add → commit → push 流程操作。mkdir -p，更为简便。git checkout -b dev
git checkout master
git branch 查看本地分支
git branch -r 查看远程分支
git branch -a 查看所有分支（本地 + 远程）
git branch -d dev 删除本地分支（已合并）
git branch -D dev 强制删除本地分支
git push origin --delete dev 删除远程分支
git checkout master
git merge dev
git push -u origin dev
git log 查看提交历史
git log --oneline 简洁显示历史记录
git log --graph 可视化分支结构
git reset --hard HEAD^ 回退一个版本
git reset --hard <commit-id> 回退到指定提交
git reset HEAD <file> 把文件从暂存区移出工作区
git checkout -- <file> 放弃工作区的修改
git tag v1.0 创建标签
git tag -a v1.0 -m “说明” 带注释标签
git push origin v1.0 git push origin –tags # 推送所有标签
git tag -d v1.0 git push origin :refs/tags/v1.0 # 删除远程标签
四、忽略文件配置（.gitignore） .gitignore 文件用于指定 Git 在提交时应忽略的文件和目录。
示例： gitignore 复制 编辑
node_modules/
*.log
dist/
*.tmp 五、Git Stash（临时存储）
Git 会标记冲突位置（«««<、=======、»»»>）
手动编辑文件解决冲突
重新添加到暂存区并提交：
bash 复制 编辑 git add <冲突文件> git commit -m "解决合并冲突" 七、Git 常用配置命令 bash 复制 编辑
git config –global user.name “Your Name” git config –global user.email “you@example.com”
git config –list
git config –global core.editor “code –wait” # VSCode
git config –global init.defaultBranch main 八、Git 状态和差异 bash 复制 编辑 git status # 查看当前文件状态 git diff # 比较工作区与暂存区差异 git diff –cached # 比较暂存区与版本库的差异 git diff HEAD # 比较工作区与最新提交的差异 九、Git 清理操作 bash 复制 编辑
git clean -f
git clean -fd
git clean -fx 十、工作流建议 每个新功能或修复新建分支开发，避免在 master 或 main 上直接开发。
常用分支命名规范：
feature/功能名
bugfix/问题修复
hotfix/紧急修复
release/版本发布
提交信息清晰简洁，如：
makefile 复制 编辑 feat: 新增注册功能 fix: 修复登录页空白问题 refactor: 重构请求逻辑 十一、附录：Git 提交信息规范（Angular 风格） 类型 说明 feat 新功能 fix 修复 bug docs 文档修改 style 格式修改，不影响功能 refactor 重构代码 test 添加测试 chore 构建流程、工具等辅助修改
]]>这个站点基于 Jekyll 和 al-folio。日常维护主要是写 Markdown、调整 front matter、跑本地构建确认没有破坏页面。
文章放在 _posts/：
_posts/2025-07-14-jekyll-al-folio.md
文件名格式是：
YYYY-MM-DD-slug.md
日期会影响文章排序，slug 建议用英文，避免链接里出现编码问题。
每篇文章开头都有一段 YAML：
---
layout: post
title: 文章标题
date: 2025-06-22 12:00:00
tags: [jekyll, blog]
categories: notes
permalink: /blog/example/
---
其中：
layout 决定页面模板。title 是文章标题。date 决定排序。tags 用于标签聚合。permalink 决定最终访问路径。常用命令：
bundle exec jekyll build --baseurl /al-folio
构建通过后，再看 _site/ 生成结果是否符合预期。
博客不是一次写完的文档，更像持续整理的知识库。先写能用的，再慢慢补细节。
]]>CI 的目标是让项目每次提交后自动检查。最基础的 CI 不需要很复杂，只要能跑格式化、lint、测试和构建，就已经能挡住很多低级问题。
GitHub Actions 的配置放在：
.github/workflows/*.yml
例如：
.github/workflows/ci.yml
name: CI
on:
push:
branches: [main]
pull_request:
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 20
cache: npm
- run: npm ci
- run: npm run lint
- run: npm test
- run: npm run build
npm ci 比 npm install 更适合 CI，因为它严格按 lockfile 安装。
push：推送到指定分支时触发。pull_request：提交 PR 时触发。workflow_dispatch：允许手动触发。schedule：定时任务。actions/setup-node 自带 npm 缓存能力：
with:
node-version: 20
cache: npm
这能减少重复下载依赖的时间。
CI 真正有用，需要和分支保护配合：
否则 CI 只是提示，不会真正阻止坏代码进入主分支。
CI 失败时先看第一处报错，不要只看最后一行。常见原因包括依赖版本不一致、环境变量缺失、测试依赖本地文件、脚本在 Linux 下路径大小写错误。
]]>