Merge pull request 'Docs/vibe coding standard' (#12) from docs/vibe-coding-standard into main

Reviewed-on: #12

.gitea/scripts/ai-review.mjs

@@ -43,6 +43,20 @@ function extractOutputText(response) {
   return parts.join("\n").trim();
 }
 
+function resolveGiteaApiUrl(event) {
+  if (process.env.GITEA_API_URL) return process.env.GITEA_API_URL;
+
+  const repositoryApiUrl = event.repository?.url;
+  const reposMarker = "/repos/";
+  const markerIndex = repositoryApiUrl?.indexOf(reposMarker) ?? -1;
+  if (markerIndex > 0) return repositoryApiUrl.slice(0, markerIndex);
+
+  const serverUrl = process.env.GITEA_SERVER_URL;
+  if (serverUrl) return `${serverUrl.replace(/\/$/, "")}/api/v1`;
+
+  throw new Error("Cannot determine the Gitea API URL from the environment or event payload");
+}
+
 async function upsertComment({ apiUrl, token, owner, repo, number, body }) {
   const headers = {
     Accept: "application/json",
@@ -98,7 +112,7 @@ async function main() {
   const diff = runGit(["diff", "--no-ext-diff", "--unified=30", `${baseSha}...${headSha}`]);
   const number = pull.number || event.number;
   const commentContext = {
-    apiUrl: required("GITEA_API_URL"),
+    apiUrl: resolveGiteaApiUrl(event),
     token: required("GITEA_TOKEN"),
     owner,
     repo,

.gitea/workflows/ai-review.yml

@@ -12,7 +12,7 @@ jobs:
     if: ${{ gitea.event.pull_request.head.repo.full_name == gitea.repository }}
     steps:
       - name: Check out the trusted reviewer from the target revision
-        uses: actions/checkout@v4
+        uses: https://gitea.com/actions/checkout@v4
         with:
           ref: ${{ gitea.event.pull_request.base.sha }}
           fetch-depth: 0
@@ -21,6 +21,7 @@ jobs:
       - name: Run AI review
         working-directory: trusted
         env:
+          GITEA_API_URL: ${{ gitea.api_url }}
           GITEA_TOKEN: ${{ secrets.AI_REVIEW_GITEA_TOKEN }}
           OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
           OPENAI_MODEL: ${{ secrets.OPENAI_MODEL }}

AGENTS.md

@@ -0,0 +1,128 @@
+# Mech-AI AI 开发规范
+
+本文件是本仓库中 AI 编程工具的仓库级提示词。开始任务前必须完整阅读并遵守；若子目录以后出现更具体的 `AGENTS.md`，还要同时遵守离目标文件最近的规则。
+
+## 1. 工作原则
+
+- 把开发者的自然语言描述转换成可验证的小改动，不猜测未说明的大范围需求。
+- 先读代码和文档，再提出方案和改代码。不要仅凭文件名或通用经验判断项目结构。
+- 优先解决根因，不用硬编码、静默忽略异常或伪造成功结果掩盖问题。
+- 保持改动最小且完整。不要顺手重构无关代码、批量格式化文件或更新无关依赖。
+- 不覆盖开发者已有的未提交修改。发现工作区不干净时，先识别哪些修改属于当前任务；有冲突风险再向开发者说明。
+- 不声称运行过没有实际运行的命令、测试、SolidWorks、AutoCAD 或 ANSYS。
+- 遇到信息不足时，先从仓库寻找答案。只有会显著改变实现方向且无法从代码判断时，才询问开发者。
+
+## 2. 项目事实与边界
+
+这是 Windows 优先的机械设计教学与诊断项目，主要组成如下：
+
+- `web/`：Vue 3、TypeScript、Vite 前端，默认端口 `5175`。
+- `backend-csharp/Agent4.Api/`：当前主后端，ASP.NET Core / .NET 10，默认端口 `7200`，并包含 SolidWorks、工程图和机械诊断能力。
+- `backend/agent4/`：Python FastAPI 旧版后端，作为回退和参考实现。除非任务明确要求，不要把只修改 Python 后端当成主功能已经完成。
+- `tools/modeling-process/`：SolidWorks 特征与装配提取工具。
+- `tools/model-diagnostics/`：三维模型诊断工具及其契约、使用说明。
+- `tools/drawing-diagnostics/`：AutoCAD/SolidWorks 工程图诊断工具及流程说明。
+- `data/standards/`：标准答案、建模计划和 skill flow。原始 JSON 是可执行、可比较特征轨迹的权威数据。
+- `data/standards/manifest.json`：标准答案主索引，应通过 `scripts/import_standard_records.py` 维护，不要手工制造与源文件不一致的条目。
+- `data/knowledge/`：机械知识框架。大体积外部分发资料不属于日常代码改动。
+- `.gitea/`：Gitea Actions 和 PR AI 审查配置。
+
+架构主线是：
+
+```text
+标准答案 skill flow -> 预期特征轨迹
+学生模型/操作       -> 提取特征轨迹
+grader              -> 教学反馈或测试评分
+```
+
+教学场景中，特征建模方法是否正确优先于最终几何外观相似。
+
+## 3. 每个任务的标准流程
+
+### 3.1 开始前
+
+1. 用自己的话复述目标、成功条件和不做的内容。
+2. 阅读 `README.md`、相关目录 README、入口文件、调用方、数据模型和配置示例。
+3. 用搜索定位相同 API、字段、类型和已有实现，确认影响范围。
+4. 执行 `git status --short --branch`，确认当前分支和已有修改。
+5. 禁止在 `main` 或 `master` 上开发、提交或推送。若当前在主分支，基于最新 `origin/main` 创建新分支：
+
+```powershell
+git fetch origin main
+git switch -c <类型>/<简短英文说明> origin/main
+```
+
+推荐分支前缀：`feat/`、`fix/`、`docs/`、`refactor/`、`test/`、`chore/`。
+
+### 3.2 实现时
+
+1. 先给出 2 至 6 步的短计划；简单的单文件改动可以直接说明准备修改什么。
+2. 一次只处理当前需求。优先复用现有类型、服务、API 和样式，不创建重复体系。
+3. 修改公共契约时检查所有调用方：前端请求、C# DTO/API、Python 参考实现、JSON 数据和文档。
+4. API JSON 继续使用 `snake_case`。不要无意改变现有状态码、字段名称、路径或错误语义。
+5. 所有外部路径和软件安装位置必须来自配置，不写死个人电脑路径。
+6. 结构化数据使用 JSON/类型化 API 解析，不用正则或字符串拼接代替正常解析。
+7. 保持 UTF-8 和现有中英文风格。不要因为终端显示乱码就批量重写中文文件。
+8. CAD/COM 代码要考虑 Windows、进程生命周期、超时、资源释放和文件占用；不要为了绕过失败吞掉异常。
+9. 前端必须处理加载、空数据、失败和禁用状态；不只实现理想路径。
+10. 修复缺陷时尽量补充能复现问题的最小测试。若当前模块没有测试框架，不要为小改动引入庞大框架，应提供可重复的验证步骤。
+
+### 3.3 验证时
+
+根据改动范围运行最小但充分的验证：
+
+| 改动范围 | 至少执行 |
+| --- | --- |
+| 仅文档 | `git diff --check`，并人工检查命令、路径和链接 |
+| Vue/TypeScript | 在 `web/` 执行 `npm ci`（依赖未安装时）和 `npm run build` |
+| C# 主 API | `dotnet build backend-csharp/Agent4.Api/Agent4.Api.csproj` |
+| 单个 C# 工具 | `dotnet build <受影响的 .csproj>` |
+| Python | 使用项目虚拟环境安装依赖，再执行 `python -m compileall backend scripts`；对受影响逻辑补充可重复检查 |
+| 标准 JSON/manifest | 用 JSON 解析器校验；通过导入脚本生成后核对变更数量、路径和抽样内容 |
+| 跨前后端/API 契约 | 同时构建前端和 C# 主 API，并检查请求与响应字段 |
+
+验证受本机软件、许可证、外部模型或服务限制时：
+
+- 继续完成不依赖这些条件的构建和静态检查。
+- 明确列出未验证项、原因和开发者可执行的命令或操作。
+- 不把“能编译”描述成“CAD/仿真功能已验证”。
+
+### 3.4 提交前自审
+
+依次检查：
+
+1. `git status --short`：没有提交 `.env`、`project_paths.json`、`runtime/`、构建目录、依赖目录、日志或个人路径。
+2. `git diff --check`：没有冲突标记、尾随空格和明显格式问题。
+3. `git diff --stat` 与 `git diff`：每一处修改都服务于当前需求。
+4. 正确性：空值、边界值、错误路径、重复请求、并发和资源释放是否合理。
+5. 兼容性：现有 API、JSON、标准答案和旧数据是否仍可读取。
+6. 安全性：不把令牌、密码或敏感配置写进代码、日志、提交信息和回复。
+7. 验证结果：记录实际成功和未执行的检查，不模糊表达。
+
+## 4. Git 交付规则
+
+- 面向零基础开发者时，在执行会改变 Git 状态的命令前，先用一句话解释命令会影响工作区、暂存区、本地提交还是远端分支；执行后报告实际状态。
+- 永远不要向 `main` 或 `master` 直接推送。
+- 不使用 `git push --force`，不擅自 rebase、reset、删除分支或覆盖他人修改。
+- 个人分支落后于最新 `origin/main` 时，先 `git fetch origin` 并确认工作区干净，再在个人分支执行 `git merge origin/main`。默认不对已推送分支 rebase；若有冲突，解释冲突后再解决并重新验证。
+- 只暂存本任务文件，使用能说明目的的提交信息，例如 `docs: add vibe coding workflow`。
+- 提交前再次检查当前分支不是主分支。
+- 只有开发者要求交付到远端时才执行：
+
+```powershell
+git push -u origin <当前分支>
+```
+
+- 不通过 CLI、API 或网页自动创建合并请求。推送完成后，报告分支名、提交、验证结果和剩余风险，由开发者自行在 Gitea 网页创建合并请求。
+
+## 5. 输出格式
+
+任务完成时用简洁中文给出：
+
+1. 完成了什么，以及关键文件位置。
+2. 实际运行的验证及结果。
+3. 当前分支和提交哈希；若已推送，说明远端分支。
+4. 尚未验证的内容或已知风险。
+5. 提醒开发者自行在网页创建合并请求，不要代为创建。
+
+如果任务没有完成，要明确说明阻塞点和已确认的事实，不要用猜测包装成结果。

README.md

@@ -2,6 +2,11 @@
 
 Agent4 is a rebuilt learning and assessment platform for SolidWorks modeling and ANSYS simulation education.
 
+AI-assisted development must follow [`AGENTS.md`](AGENTS.md). Developers who
+are new to Git or vibe coding should start with the Chinese
+[`Vibe Coding development workflow`](docs/VIBE_CODING_WORKFLOW.md) and
+[`Git beginner guide`](docs/GIT_BEGINNER_GUIDE.md).
+
 It separates the product into these roles:
 
 - Knowledge standards: standard answers, extracted skillflows, teaching scripts, and assessment rules.

docs/GIT_BEGINNER_GUIDE.md

@@ -0,0 +1,538 @@
+# Mech-AI Git 零基础教程
+
+本文写给第一次接触 Git 的开发者。目标不是背命令，而是先理解“代码现在在哪里、处于什么状态、下一步会发生什么”。只要养成每次操作前后查看状态的习惯，大多数 Git 问题都能避免。
+
+本项目有两条必须遵守的团队规则：
+
+1. 不在 `main` 分支开发、提交或推送。
+2. 每个任务使用自己的新分支，推送后由开发者在 Gitea 网页创建合并请求。
+
+## 1. Git 解决什么问题
+
+Git 是代码版本管理工具。它可以记录每次修改，允许多人在不同分支并行开发，并在需要时比较、合并或撤销改动。
+
+Git 和普通网盘同步不同：
+
+- 保存文件只会改变电脑上的文件，不会自动形成 Git 版本。
+- `commit` 只把版本记录在本地仓库，不会自动上传到 Gitea。
+- `push` 才会把本地提交上传到远端仓库。
+- 别人推送的内容不会自动出现在本地，先执行 `fetch` 或 `pull` 才能看到。
+
+## 2. 必须理解的几个概念
+
+### 仓库 Repository
+
+仓库是由 Git 管理的项目目录。`mech-ai` 文件夹是本地仓库，Gitea 上的 `neu/mech-ai` 是远端仓库。
+
+### 工作区 Working Tree
+
+你在编辑器中看到和修改的文件。文件刚保存时，改动只在工作区。
+
+### 暂存区 Staging Area
+
+准备放进下一次提交的改动清单。`git add` 把指定改动放入暂存区。暂存不是上传，也不是提交。
+
+### 提交 Commit
+
+一次有说明文字的版本快照。`git commit` 只记录已经暂存的内容。一个好的提交应该只完成一件明确的事。
+
+### 分支 Branch
+
+一条独立的开发线。`main` 保存团队已合并的稳定代码；`feat/...`、`fix/...` 等个人分支用于开发具体任务。
+
+### 远端 Remote 与 origin
+
+远端是托管在服务器上的仓库。克隆后，Git 通常把这个远端命名为 `origin`。
+
+- `main`：本地 `main` 分支。
+- `origin/main`：本地最后一次获知的远端 `main` 状态。
+- Gitea 上真正的 `main`：服务器当前状态。
+
+`origin/main` 不会自己刷新。执行 `git fetch origin` 后，它才代表刚刚从服务器取得的状态。
+
+### HEAD
+
+HEAD 表示“你当前所在的位置”，通常指向当前分支的最新提交。日常只需通过 `git branch --show-current` 确认当前分支。
+
+### 合并请求 Pull Request
+
+合并请求是请团队审查并把个人分支合入 `main` 的网页流程。它不是 Git 提交，也不是 `push`；本项目要求开发者自行在 Gitea 网页创建。
+
+## 3. 一张图理解代码如何移动
+
+```text
+你的电脑
+
+工作区 --git add--> 暂存区 --git commit--> 本地个人分支
+  ^                                         |
+  |                                         | git push
+  |                                         v
+编辑器                                  Gitea 远端个人分支
+                                             |
+                                             | 网页合并请求 + 审查
+                                             v
+                                        Gitea main
+
+Gitea --git fetch--> 更新 origin/main 等“远端跟踪分支”
+```
+
+最重要的区别是：
+
+| 动作 | 改变工作区 | 产生本地提交 | 上传 Gitea |
+| --- | --- | --- | --- |
+| 保存文件 | 是 | 否 | 否 |
+| `git add` | 否 | 否 | 否 |
+| `git commit` | 否 | 是 | 否 |
+| `git push` | 否 | 否 | 是 |
+| `git fetch` | 否 | 否 | 下载远端状态，不合并代码 |
+| `git merge` | 可能 | 可能产生合并提交 | 否 |
+
+## 4. 第一次使用 Git
+
+检查 Git 是否安装：
+
+```powershell
+git --version
+```
+
+设置提交中显示的姓名和工作邮箱，只需在电脑上设置一次：
+
+```powershell
+git config --global user.name "你的姓名"
+git config --global user.email "你的工作邮箱"
+```
+
+克隆仓库：
+
+```powershell
+git clone https://git.sweecidal.icu/neu/mech-ai/
+cd mech-ai
+```
+
+确认远端和当前状态：
+
+```powershell
+git remote -v
+git status --short --branch
+```
+
+`git clone` 只在第一次下载仓库时使用。以后继续在同一个 `mech-ai` 目录开发，不要为每次任务重复克隆多个副本。
+
+## 5. 看懂 git status
+
+开发期间最常用的命令是：
+
+```powershell
+git status
+git status --short --branch
+```
+
+短格式中，文件名前的符号表示状态：
+
+| 示例 | 含义 |
+| --- | --- |
+| `?? file` | 新文件，Git 尚未跟踪 |
+| ` M file` | 工作区已修改，尚未暂存 |
+| `M  file` | 修改已暂存，准备提交 |
+| `MM file` | 已暂存后又继续修改，暂存区和工作区都有改动 |
+| `A  file` | 新文件已暂存 |
+| `D  file` | 文件被删除 |
+| `UU file` | 合并冲突尚未解决 |
+
+分支行常见提示：
+
+| 提示 | 含义 | 通常下一步 |
+| --- | --- | --- |
+| `[ahead 2]` | 本地比对应远端多 2 个提交 | 检查后 `git push` |
+| `[behind 2]` | 远端比本地多 2 个提交 | 先 `git fetch`，确认后同步 |
+| `[ahead 1, behind 2]` | 两边各有不同提交，已经分叉 | 不要强制推送，先检查和合并 |
+| `nothing to commit, working tree clean` | 没有未提交修改 | 可以切换分支或合并代码 |
+
+注意：只有在刚执行过 `git fetch` 后，ahead/behind 才能准确反映服务器的最新状态。
+
+## 6. 一次标准开发流程
+
+下面是每个新任务都可以照做的完整流程。
+
+### 第 1 步：确认没有遗留修改
+
+```powershell
+git status --short --branch
+```
+
+如果看到修改但不知道来源，先停止。不要删除、覆盖或把它们混入新任务，应确认这些修改属于谁和哪个任务。
+
+### 第 2 步：更新本地 main
+
+只有工作区干净时才执行：
+
+```powershell
+git switch main
+git fetch origin
+git pull --ff-only origin main
+```
+
+- `switch main` 切换到本地主分支。
+- `fetch` 获取远端最新状态，但不修改当前文件。
+- `pull --ff-only` 仅在本地 `main` 可以安全快进时更新；如果历史异常分叉，它会停止而不是自动制造复杂合并。
+
+更新本地 `main` 不等于向 `main` 推送。开发者仍然禁止执行 `git push origin main`。
+
+### 第 3 步：创建任务分支
+
+```powershell
+git switch -c feat/standard-filter origin/main
+```
+
+把 `feat/standard-filter` 换成当前任务名称：
+
+- 新功能：`feat/简短英文名称`
+- 缺陷修复：`fix/简短英文名称`
+- 文档：`docs/简短英文名称`
+- 测试：`test/简短英文名称`
+- 维护：`chore/简短英文名称`
+
+一个分支只处理一个任务。不同开发者不要共用同一个个人开发分支。
+
+### 第 4 步：开发并随时检查差异
+
+```powershell
+git status --short
+git diff
+```
+
+`git diff` 显示尚未暂存的改动。它不会修改任何文件，可以放心频繁使用。
+
+完成一小段功能后运行项目要求的构建或测试。不要等到所有内容都写完才第一次验证。
+
+### 第 5 步：选择要提交的文件
+
+优先明确写出文件路径：
+
+```powershell
+git add web/src/App.vue backend-csharp/Agent4.Api/Program.cs
+```
+
+然后检查暂存内容：
+
+```powershell
+git diff --cached
+git status --short
+```
+
+零基础阶段不建议直接使用 `git add .`，因为它可能把日志、本机配置、生成文件和其他任务的改动一起加入。
+
+如果误把文件加入暂存区，可以取消暂存但保留文件修改：
+
+```powershell
+git restore --staged <文件路径>
+```
+
+### 第 6 步：创建提交
+
+```powershell
+git commit -m "feat: add standard type filter"
+```
+
+推荐格式是 `<类型>: <做了什么>`：
+
+- `feat:` 新功能
+- `fix:` 缺陷修复
+- `docs:` 文档
+- `test:` 测试
+- `refactor:` 不改变行为的重构
+- `chore:` 构建或日常维护
+
+提交说明应描述目的，例如 `fix: handle empty standard response`，不要只写 `update`、`修改`、`test` 或日期。
+
+一个任务可以有多个提交。提交不需要很大，但每个提交都应处于可理解、尽量可构建的状态。
+
+### 第 7 步：推送个人分支
+
+第一次推送：
+
+```powershell
+git push -u origin feat/standard-filter
+```
+
+`-u` 建立本地分支与远端同名分支的对应关系。以后在这个分支继续提交后，只需：
+
+```powershell
+git push
+```
+
+推送前再次确认：
+
+```powershell
+git branch --show-current
+```
+
+结果绝不能是 `main` 或 `master`。
+
+### 第 8 步：网页创建合并请求
+
+打开 `https://git.sweecidal.icu/neu/mech-ai/`，来源选择个人分支，目标选择 `main`。填写改动原因、验证结果和未验证风险，等待自动审查和人工审查。
+
+## 7. commit、push 和“同步”的关系
+
+“我保存了”“我提交了”“我同步了”是三件不同的事：
+
+```text
+保存：文件已经写到本机磁盘
+提交：改动已经形成一个本地 commit
+推送：commit 已上传到 Gitea 的个人分支
+合并：个人分支经审查后进入 Gitea main
+```
+
+可以用下面的命令确认最近提交：
+
+```powershell
+git log --oneline --decorate -10
+```
+
+确认哪些本地提交还没有推送：
+
+```powershell
+git log --oneline "@{upstream}..HEAD"
+```
+
+如果提示没有 upstream，说明当前分支还没有使用 `git push -u` 建立远端对应关系。
+
+只下载远端状态、不修改当前代码：
+
+```powershell
+git fetch origin
+```
+
+查看整个分支关系：
+
+```powershell
+git log --oneline --graph --decorate --all -20
+```
+
+## 8. main 比个人分支更新时怎么办
+
+这是正常情况：你开发期间，其他人的合并请求进入了 `main`。推荐做法是在个人分支中合并最新 `origin/main`。
+
+### 先判断是否真的有新提交
+
+```powershell
+git fetch origin
+git log --oneline HEAD..origin/main
+```
+
+如果第二条命令有输出，表示 `origin/main` 中存在当前个人分支尚未包含的提交。
+
+### 确保个人改动已经安全保存
+
+```powershell
+git status --short --branch
+```
+
+工作区应当干净。若仍有改动，优先完成验证并提交当前可理解的工作，再进行合并。不要在有大量未提交修改时直接合并。
+
+### 在个人分支合并 main
+
+```powershell
+git branch --show-current
+git merge origin/main
+```
+
+第一条命令必须显示你的个人分支。不要切换到 `main` 后把个人分支合入 `main`。
+
+如果没有冲突，Git 会直接完成合并。随后重新运行受影响的构建和测试，再推送个人分支：
+
+```powershell
+git push
+```
+
+原来的合并请求会自动显示新提交，不需要重新创建分支或合并请求。
+
+### 为什么本教程默认使用 merge，不使用 rebase
+
+`rebase` 会重写提交的基础和提交哈希。对尚未熟悉 Git、已经推送或多人共享的分支，误操作后容易需要强制推送并覆盖远端历史。`merge origin/main` 会保留现有历史，不需要强制推送，更适合作为团队默认流程。
+
+熟悉 Git 后可以在团队另行约定只对未共享的个人提交使用 rebase，但不能自行改变公共分支历史。
+
+## 9. 合并冲突怎么处理
+
+当你和 `main` 修改了同一文件的相同位置，Git 无法替你判断应保留哪一版，会暂停并报告冲突。这不代表代码丢失。
+
+先查看冲突文件：
+
+```powershell
+git status
+```
+
+文件中会出现类似标记：
+
+```text
+  <<<<<<< HEAD
+  你的个人分支内容
+  =======
+  origin/main 中的内容
+  >>>>>>> origin/main
+```
+
+处理步骤：
+
+1. 理解两边修改的目的，不要机械地只选一边。
+2. 编辑成最终正确内容，并删除 `<<<<<<<`、`=======`、`>>>>>>>` 标记。
+3. 对解决好的文件执行 `git add <文件路径>`。
+4. 用 `git status` 确认没有 `UU` 文件和未解决冲突。
+5. 运行相关构建和测试。
+6. 执行 `git commit` 完成合并提交，再 `git push`。
+
+如果发现合并方向错误或暂时不会解决，在尚未完成合并提交前可以回到合并前：
+
+```powershell
+git merge --abort
+```
+
+`git merge --abort` 只用于正在进行的合并。执行后应再次查看 `git status`。不确定时保留现场并请有经验的开发者协助，不要尝试强制推送或删除文件。
+
+## 10. 远端个人分支比本地更新时怎么办
+
+这种情况通常发生在同一开发者换电脑开发，或多人错误地共用了一个分支。
+
+先获取并查看状态：
+
+```powershell
+git fetch origin
+git status --short --branch
+```
+
+- 只有 `behind` 且工作区干净：可以执行 `git pull --ff-only`。
+- 只有 `ahead`：检查提交后执行 `git push`。
+- 同时 `ahead` 和 `behind`：两边已经分叉，不要执行 `git push --force`。用提交图检查差异，并请 AI 工具或有经验的开发者协助合并。
+
+团队应坚持“一人一任务一分支”，从源头减少这种情况。
+
+## 11. 合并请求审查后继续修改
+
+审查者要求修改时，不需要新建分支或新建合并请求：
+
+```powershell
+git switch <原个人分支>
+git status --short --branch
+# 修改、验证
+git add <本次文件>
+git commit -m "fix: address review feedback"
+git push
+```
+
+Gitea 会把新提交自动追加到原合并请求。
+
+## 12. 合并完成后开始下一个任务
+
+确认网页上的合并请求已经合入 `main`，然后：
+
+```powershell
+git switch main
+git fetch origin
+git pull --ff-only origin main
+git switch -c feat/next-task origin/main
+```
+
+不要在旧任务分支上直接开始无关的新功能。是否删除旧分支可以等确认合并和新 `main` 正常后再处理。
+
+## 13. 常见错误与安全处理
+
+### 在 main 上修改了文件，但还没有 commit
+
+不要推送。通常可以直接从当前状态创建个人分支，未提交修改会一起保留：
+
+```powershell
+git switch -c fix/correct-branch
+```
+
+然后检查状态、验证、提交并推送新分支。
+
+### 在 main 上错误 commit，但还没有 push
+
+立即停止，不要推送 `main`。先从当前提交创建正确的个人分支并推送该分支：
+
+```powershell
+git switch -c fix/correct-branch
+git push -u origin fix/correct-branch
+```
+
+本地 `main` 指针仍需恢复到 `origin/main`，这个操作可能丢失错误选择的提交。零基础开发者应请有经验的开发者确认后处理，不要自行运行 `reset --hard`。
+
+### commit 后发现漏了文件
+
+最容易审查的方式是补一个小提交：
+
+```powershell
+git add <漏掉的文件>
+git commit -m "fix: include missing file"
+git push
+```
+
+不要为了让历史看起来完美而对已经推送的提交强行改写。
+
+### 已推送的提交需要撤销
+
+使用 `revert` 创建一个反向提交，不改写公共历史：
+
+```powershell
+git revert <提交哈希>
+git push
+```
+
+`revert` 也可能产生冲突，执行前应确认提交范围并在完成后重新验证。
+
+### push 被拒绝 non-fast-forward
+
+说明远端分支有本地未包含的提交。不要加 `--force`。执行 `git fetch origin`，查看 ahead/behind 和提交图，再按“远端个人分支比本地更新”处理。
+
+### 切换分支时提示会覆盖本地修改
+
+说明工作区有尚未安全保存的改动。不要删除它们。回到 `git status`，判断应提交到当前分支、转移到正确的新分支，还是请原开发者处理。
+
+## 14. 不要随意使用的危险命令
+
+零基础开发者不应让 AI 工具自行执行下面命令：
+
+| 命令 | 风险 |
+| --- | --- |
+| `git push --force` | 可能覆盖远端其他人的提交 |
+| `git reset --hard` | 可能永久丢失未保存修改和提交 |
+| `git clean -fd` | 会删除未跟踪文件和目录 |
+| `git restore <文件>` | 会丢弃该文件尚未提交的修改 |
+| `git branch -D` | 强制删除可能尚未合并的分支 |
+
+如果确实需要使用，先让工具解释将影响哪些具体文件和提交，并由有经验的开发者确认。
+
+## 15. 每日命令速查
+
+| 目的 | 命令 |
+| --- | --- |
+| 查看当前分支 | `git branch --show-current` |
+| 查看文件和分支状态 | `git status --short --branch` |
+| 获取远端最新状态但不合并 | `git fetch origin` |
+| 查看未暂存差异 | `git diff` |
+| 查看已暂存差异 | `git diff --cached` |
+| 暂存指定文件 | `git add <文件路径>` |
+| 取消暂存并保留修改 | `git restore --staged <文件路径>` |
+| 创建提交 | `git commit -m "类型: 说明"` |
+| 首次推送个人分支 | `git push -u origin <分支名>` |
+| 后续推送 | `git push` |
+| 查看最近提交 | `git log --oneline --decorate -10` |
+| 把最新 main 合入个人分支 | `git fetch origin` 后执行 `git merge origin/main` |
+
+## 16. 让 AI 工具帮助检查 Git 状态
+
+不确定时可以把下面提示词发给 AI 工具：
+
+```text
+请先只做只读检查，不修改文件、不切换分支、不提交、不推送。解释当前分支、工作区、暂存区、本地提交、远端跟踪分支分别是什么状态；指出当前分支相对 origin/main 和对应远端个人分支是 ahead、behind 还是 diverged。然后给出最安全的下一步及每条命令的影响，等待我确认后再执行。禁止 force push、reset --hard 和 clean -fd。
+```
+
+当 `main` 已更新时可以使用：
+
+```text
+请先执行 git fetch 并只读检查我的个人分支与 origin/main 的差异。如果工作区不干净，先说明每项改动，不要覆盖。若需要同步，默认在我的个人分支执行 merge origin/main，不使用 rebase 或 force push。遇到冲突时停下来解释冲突文件和两边修改目的，不要机械选择任一版本。合并后运行受影响的验证并只推送个人分支，不要推送 main，不要创建合并请求。
+```
+
+始终记住：先 `status`，再理解状态，最后执行会改变状态的命令。

docs/VIBE_CODING_WORKFLOW.md

@@ -0,0 +1,172 @@
+# Mech-AI 零基础 Vibe Coding 开发流程
+
+这份说明供使用 Codex、Claude Code、Cursor、Copilot 等 AI 编程工具的开发者使用。仓库根目录的 `AGENTS.md` 是完整开发规范；本文件说明怎样把一个想法安全地交给工具，并获得可审查的代码分支。第一次接触 Git 的开发者应先阅读 [`Git 零基础教程`](GIT_BEGINNER_GUIDE.md)。
+
+## 开始之前
+
+首次开发请确认电脑具备与任务有关的环境：
+
+- Git，并已获得 `https://git.sweecidal.icu/neu/mech-ai/` 的访问权限。
+- 前端任务：Node.js 和 npm。
+- 主后端或 C# 工具任务：.NET 10 SDK。
+- Python 回退后端任务：Python 3.13 或兼容版本。
+- CAD/仿真任务：对应版本的 SolidWorks、AutoCAD 或 ANSYS，以及可用许可证。
+
+克隆并进入仓库：
+
+```powershell
+git clone https://git.sweecidal.icu/neu/mech-ai/
+cd mech-ai
+```
+
+不了解工作区、暂存区、commit、分支、push 或同步状态时，不要直接照抄后续 Git 命令。先按 [`Git 零基础教程`](GIT_BEGINNER_GUIDE.md) 完成概念和标准流程学习。
+
+本机路径放在由示例生成的本地配置中，不要写进源码：
+
+```powershell
+Copy-Item project_paths.example.json project_paths.json
+```
+
+## 第一步：写清楚需求
+
+不要只输入“帮我优化一下”或“这个不能用”。至少提供下面四类信息：
+
+| 信息 | 示例 |
+| --- | --- |
+| 目标 | 在知识标准列表增加按零件类型筛选 |
+| 当前现象 | 现在只能输入关键词，结果混在一起 |
+| 完成标准 | 可选择类型；切换后列表更新；接口失败时有错误提示 |
+| 限制 | 不改标准 JSON 格式，不修改 Python 回退后端 |
+
+错误日志、截图、复现步骤、涉及的页面或文件都应一并提供。不要把真实令牌和密码粘贴到聊天中。
+
+## 第二步：粘贴启动提示词
+
+每个新任务都可以从下面的提示词开始。把方括号中的内容替换成真实需求：
+
+```text
+你正在开发 mech-ai 仓库。先完整阅读仓库根目录 AGENTS.md、README.md，以及本任务相关目录的 README 和现有代码，然后再行动。
+
+我的需求：
+[描述要新增或修复的功能]
+
+当前现象与复现步骤：
+[从哪里进入、做了什么、看到了什么；没有可写“新功能”]
+
+完成标准：
+1. [用户可以看到或完成什么]
+2. [错误或空数据时应该怎样]
+3. [哪些兼容行为必须保留]
+
+限制与不做事项：
+- [明确不能改的模块、数据格式或行为]
+
+请严格执行以下流程：
+1. 先检查 git 状态和相关代码，用简洁中文复述需求、影响范围与计划；不要立刻大改。
+2. 绝不在 main/master 上开发或推送。基于最新 origin/main 创建语义清晰的新分支。
+3. 只做完成本需求所需的最小完整修改，保留我已有的未提交改动，不修改无关文件。
+4. 按 AGENTS.md 对受影响的前端、C#、Python、工具或 JSON 执行验证；不能运行的验证要说明原因，不能假装运行成功。
+5. 自审完整 diff，检查错误路径、兼容性、个人路径、生成文件和敏感信息。
+6. 使用清晰的提交信息提交，并推送当前新分支到 origin；禁止推送 main/master，禁止强制推送。
+7. 不要创建合并请求。最后报告改动、验证结果、分支名、提交哈希、未验证风险，并提醒我自行去 Gitea 网页创建合并请求。
+
+如果需求存在会改变产品行为的关键歧义，先从代码和文档寻找答案；仍无法判断时再问我。不要自行扩大需求。
+```
+
+如果工具不会自动读取 `AGENTS.md`，先把该文件全文加入工具的项目规则或上下文，再粘贴上述任务提示词。
+
+## 第三步：开发过程中怎样配合
+
+AI 工具提出计划后，先检查三件事：
+
+1. 它理解的是不是你真正想解决的问题。
+2. 它准备修改的模块是不是合理，是否无故触碰大量文件。
+3. 它给出的完成标准能不能由你亲自观察或测试。
+
+遇到下面情况应暂停并要求工具解释：
+
+- 要直接在 `main`/`master` 修改或推送。
+- 一个小功能却要重写整个前端、后端或数据结构。
+- 要删除现有文件、清空修改、强制推送或跳过报错。
+- 没读调用方就修改 API 字段或 JSON 格式。
+- 把“编译通过”说成“SolidWorks/AutoCAD/ANSYS 实际功能通过”。
+- 未展示验证结果就声称已经完成。
+
+可以使用下面的追问提示词：
+
+```text
+先不要继续修改。请用现有代码证据说明：问题根因是什么、为什么要改这些文件、哪些调用方会受影响、准备如何验证。回答后等待我确认。
+```
+
+## 第四步：检查交付结果
+
+工具完成后至少应报告：
+
+- 新分支名，且不是 `main` 或 `master`。
+- 提交哈希和已推送的远端分支。
+- 修改了哪些文件以及用户可见行为。
+- 实际执行过的构建、测试或检查及结果。
+- 因缺少 CAD 软件、许可证、外部数据或服务而没有验证的内容。
+- 没有自动创建合并请求。
+
+你可以要求工具进行最后检查：
+
+```text
+请只做交付前检查，不再扩大功能：确认当前不是 main/master，查看 git status 和完整 diff，运行 AGENTS.md 要求的相关验证，确认没有个人路径、生成文件或敏感信息，然后给出最终交付摘要。不要创建合并请求。
+```
+
+## 第五步：开发者在网页创建合并请求
+
+1. 打开 `https://git.sweecidal.icu/neu/mech-ai/`。
+2. 选择刚刚推送的新分支，点击创建合并请求。
+3. 目标分支选择 `main`，来源分支选择工具报告的新分支。
+4. 标题写清楚改动目的，不要只写“更新”或“修复”。
+5. 描述中写明背景、主要修改、验证结果、未验证风险和必要截图。
+6. 检查文件列表与差异，等待 Gitea 自动审查和人工审查后再合并。
+
+推荐的合并请求描述模板：
+
+```markdown
+## 背景
+
+[为什么需要这次修改]
+
+## 修改内容
+
+- [主要修改 1]
+- [主要修改 2]
+
+## 验证
+
+- [命令或人工步骤及结果]
+
+## 未验证与风险
+
+- [没有就写“无已知项”]
+
+## 截图
+
+[界面改动时附上修改前后截图]
+```
+
+## 常见任务的补充要求
+
+### 前端页面
+
+说清楚入口、用户操作、加载/空数据/错误状态和移动端需求。交付前至少执行 `npm run build`，界面改动还要在浏览器实际走一遍核心流程。
+
+### C# 主后端与 API
+
+说清楚请求、响应、状态码和兼容要求。主实现位于 `backend-csharp/Agent4.Api/`，至少执行对应 `dotnet build`；API 改动还要核对前端调用字段。
+
+### Python 后端
+
+它目前是回退和参考实现。必须明确任务是否只针对 Python，避免工具修改 Python 后误以为当前主后端已经生效。
+
+### 标准答案和知识数据
+
+说明数据来源、目标分类和预期条目数。`data/standards/manifest.json` 应通过导入脚本维护；要求工具解析并抽样核对 JSON，不要把它当普通文本批量替换。
+
+### SolidWorks、AutoCAD 与 ANSYS
+
+提供软件版本、输入文件类型、可公开的复现文件路径和预期输出。构建成功只能证明代码可编译；最终仍需在安装了相应软件和许可证的 Windows 机器上做集成验证。