2026-05-19-22-59-07 建立代码编纂工作流

2026-05-19 23:05:14 +08:00
parent 5ed2c02809
commit f730a1c48b
7 changed files with 345 additions and 75 deletions
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -0,0 +1,23 @@
+# 项目协作约束
+
+本项目所有后续项目修改相关需求，都必须先执行 `工程分析/代码编纂工作流.md`。
+
+最低要求：
+
+- 每次执行前记录开始时间，格式为 `{Year}-{Mon}-{Day}-{Hour}-{Min}-{Sec}`。
+- 阅读或创建 `工程分析/`，并阅读 `工程分析/工程整体分析.md`、`工程分析/经验记录.md`。
+- 写入当次 `需求分析-{timestamp}.md`、`实现方案-{timestamp}.md`、`测试方案-{timestamp}.md`。
+- 最终执行方案前再次确认已读 `经验记录.md`。
+- 执行后按 A/B/C/D 四段式追加 `工程分析/经验记录.md`。
+- 使用 Git/Gitea 对本次文档做备份 commit，commit message 必须包含时间戳和简要描述。
+- 重新部署项目并验证服务。
+
+当前项目部署优先使用：
+
+```bash
+cd WebSite
+npm run build
+npm run serve -- --host 0.0.0.0 --port 4000
+```
+
+若需要长期运行服务，优先沿用 `tmux` 会话 `revoxelseg-dicom`。
--- a/工程分析/代码编纂工作流.md
+++ b/工程分析/代码编纂工作流.md
@@ -1,60 +1,68 @@
 # 代码编纂工作流

-本工作流适用于后续所有项目修改相关需求。除非用户明确说明跳过流程，否则每次修改都按以下步骤执行。
+更新时间：2026-05-19-22-59-07
+
+本工作流适用于后续所有项目修改相关需求。只要用户提出的是项目修改、修复、重构、部署、文档治理或功能调整，都必须按本流程走；除非用户明确要求跳过其中某一步。

 ## 0. 记录开始时间

 - 每次执行前先记录问题开始时间，格式为 `{Year}-{Mon}-{Day}-{Hour}-{Min}-{Sec}`。
- 本时间戳用于贯穿需求分析、实现方案、测试方案、经验记录和 Git 提交信息。
+- 时间以当前执行环境为准。
+- 同一个时间戳贯穿当次需求分析、实现方案、测试方案、经验记录、commit message 和最终汇报。

-## 1. 阅读工程分析
+## 1. 阅读或创建工程分析目录

- 每次修改前阅读或创建 `工程分析/` 文件夹。
+- 每次修改前确认 `工程分析/` 存在，不存在则创建。
 - 优先阅读：
+  - `工程分析/代码编纂工作流.md`
  - `工程分析/工程整体分析.md`
  - `工程分析/经验记录.md`
-  - 与当前需求相关的历史 `需求分析-*`、`实现方案-*`、`测试方案-*` 文档
+  - 与当前需求相关的历史 `需求分析-*`、`实现方案-*`、`测试方案-*`
+- 如果发现 `工程分析/` 文档在工作区被删除，应先说明风险，只恢复或重建当次必要的核心文档，不把无关删除混入提交。

 ## 2. 写入需求分析

 - 将用户当次需求整理写入：
  - `工程分析/需求分析-{Year}-{Mon}-{Day}-{Hour}-{Min}-{Sec}.md`
- 内容至少包括：
+- 文档至少包含：
+  - 开始时间
  - 原始需求摘要
  - 业务目标
  - 输入与输出
  - 影响范围
+  - 关键约束
  - 风险点
-  - 待确认问题
+  - 待确认问题或默认假设

-## 3. 写入实现方案并等待人工审核
+## 3. 写入实现方案

 - 将实现方案写入：
  - `工程分析/实现方案-{Year}-{Mon}-{Day}-{Hour}-{Min}-{Sec}.md`
- 文档必须包含：
+- 文档至少包含：
+  - 实现方案文档路径
  - 修改目标
  - 涉及路径
  - 技术路线
-  - 数据流或交互流程
+  - 执行步骤
  - 兼容性与回滚方案
  - 预计文件变更
-  - 人工审核状态
- 实现方案写完后必须等待用户二次人工审核确认。
- 未收到明确确认前，不执行项目业务代码修改。
+  - 提交与部署策略
+- 2026-05-07-16-35-52 起，用户已确认“都确认，后续直接搞”。因此默认不在实现方案阶段暂停等待二次确认；若用户明确要求人工审核，则必须等待确认后再执行。

-## 4. 写入测试方案并等待人工审核
+## 4. 写入测试方案

 - 将测试方案写入：
  - `工程分析/测试方案-{Year}-{Mon}-{Day}-{Hour}-{Min}-{Sec}.md`
- 文档必须包含：
+- 文档至少包含：
+  - 测试方案文档路径
  - 静态检查
-  - 单元或集成测试
+  - 构建检查
  - 关键业务场景验证
  - 医学影像数据相关边界验证
-  - 回归风险
-  - 人工审核状态
- 测试方案写完后必须等待用户二次人工审核确认。
- 未收到明确确认前，不执行最终修改方案。
+  - 部署验证
+  - Git/Gitea 备份验证
+  - 风险与回归关注点
+- 默认不在测试方案阶段暂停等待二次确认；若用户明确要求人工审核，则必须等待确认后再执行。

 ## 5. 执行前后维护经验记录

@@ -73,30 +81,25 @@
 - Commit message 必须同时包含：
  - `{Year}-{Mon}-{Day}-{Hour}-{Min}-{Sec}` 时间戳
  - 本次修改简要描述
- 备份完成后提醒用户：文档备份 commit 已完成。
+- 备份提交时默认只暂存本次相关文档和明确属于本次修改的文件，避免提交无关工作区变化。
+- 备份完成后必须提醒用户：文档备份 commit 已完成。
 - 默认远程仓库：
  - `http://192.168.31.5:5002/admin/REVOXELSEG_DICOM.git`

 ## 7. 重新部署

 - 最终修改完成并通过测试后，重新部署本项目。
- 若项目只有前端开发环境，默认使用 `WebSite/` 下的脚本：
+- 优先使用当前项目约定：
+  - `cd WebSite`
  - `npm run build`
-  - `npm run dev`
- 若已有服务进程或部署脚本，优先沿用现有部署方式。
+  - `tmux` 会话 `revoxelseg-dicom`
+  - `npm run serve -- --host 0.0.0.0 --port 4000`
+- 若端口或会话冲突，先检查并记录实际处理方式。
+- 部署后至少验证：
+  - `http://127.0.0.1:4000/api/health`
+  - `http://127.0.0.1:4000/`

-## 人工确认口令
+## 8. 最终汇报

-后续当我完成实现方案和测试方案文档后，需要用户明确回复类似以下内容才继续：
-
- `确认实现方案`
- `确认测试方案`
- `确认执行`
-
-如果用户对方案提出修改意见，则先更新对应文档，再等待新的确认。
-
-## 默认执行确认更新
-
- 2026-05-07-16-35-52 起，用户已确认“都确认，后续直接搞”。
- 后续项目修改需求仍必须记录时间、创建需求分析、实现方案、测试方案、读取经验记录、执行后更新经验记录、备份 commit、重新部署。
- 除非用户明确要求暂停或人工审核，后续不再在实现方案和测试方案阶段停等二次确认。
+- 汇报本次开始时间、修改文件、测试结果、部署地址和 commit 状态。
+- 如果某一步无法完成，必须说明原因、影响范围和建议下一步。
--- a/工程分析/实现方案-2026-05-19-22-59-07.md
+++ b/工程分析/实现方案-2026-05-19-22-59-07.md
@@ -0,0 +1,55 @@
+# 实现方案-2026-05-19-22-59-07
+
+## 实现方案文档路径
+
+`工程分析/实现方案-2026-05-19-22-59-07.md`
+
+## 修改目标
+
+建立并固化项目级代码编纂工作流，使后续项目修改必须留下需求分析、实现方案、测试方案、经验记录、备份 commit 与部署验证。
+
+## 涉及路径
+
+- `工程分析/工程整体分析.md`
+- `工程分析/代码编纂工作流.md`
+- `工程分析/需求分析-2026-05-19-22-59-07.md`
+- `工程分析/实现方案-2026-05-19-22-59-07.md`
+- `工程分析/测试方案-2026-05-19-22-59-07.md`
+- `工程分析/经验记录.md`
+- `AGENTS.md`
+
+## 技术路线
+
+1. 记录本次开始时间 `2026-05-19-22-59-07`。
+2. 阅读项目 README、`WebSite/README.md`、`package.json`、`server.ts`、API 封装和主要 React 组件。
+3. 从 Git 中读取旧 `工程分析/工程整体分析.md`、`代码编纂工作流.md`、`经验记录.md`，保留旧知识库。
+4. 恢复并更新三个核心文档，只处理本次必要文件。
+5. 新增本次需求分析、实现方案、测试方案。
+6. 新增根目录 `AGENTS.md`，提醒后续进入仓库的助手优先执行该工作流。
+7. 执行静态检查和构建。
+8. 使用 `tmux` 重新部署 `WebSite` 服务到 `0.0.0.0:4000`。
+9. 验证 HTTP 健康检查和页面响应。
+10. 仅暂存本次相关文档和 `AGENTS.md`，创建包含时间戳和简要描述的 commit，并尝试推送到 Gitea。
+
+## 兼容性与回滚方案
+
+- 本次不修改业务代码，不改变 API、前端页面和运行态数据结构。
+- 若文档内容需要回滚，可回退本次 commit。
+- 若部署失败，可保留当前代码构建结果，检查 `tmux` 会话日志和端口占用后重新启动。
+- 若 Gitea 推送失败，本地 commit 仍保留，可稍后网络恢复后执行 `git push origin main`。
+
+## 预计文件变更
+
+- 更新：`工程分析/工程整体分析.md`
+- 更新：`工程分析/代码编纂工作流.md`
+- 更新：`工程分析/经验记录.md`
+- 新增：`工程分析/需求分析-2026-05-19-22-59-07.md`
+- 新增：`工程分析/实现方案-2026-05-19-22-59-07.md`
+- 新增：`工程分析/测试方案-2026-05-19-22-59-07.md`
+- 新增：`AGENTS.md`
+
+## 提交与部署策略
+
+- 暂存时显式列出本次文件，避免把工作区已有历史删除状态混入 commit。
+- commit message 使用：`2026-05-19-22-59-07 建立代码编纂工作流`
+- 部署方式沿用项目约定：`tmux` 会话 `revoxelseg-dicom` + `npm run serve -- --host 0.0.0.0 --port 4000`。
--- a/工程分析/工程整体分析.md
+++ b/工程分析/工程整体分析.md
@@ -1,57 +1,85 @@
 # 工程整体分析

-更新时间：2026-05-04-02-38-48
+更新时间：2026-05-19-22-59-07

 ## 项目定位

-本项目计划建设为“基于模型逆向体素化及 DICOM 分割标注系统”。
+本项目是“基于模型逆向体素化及 DICOM 分割标注系统”的前后端一体化演示工程。核心目标是读取 `Head_CT_DICOM/` 中的 DICOM 序列和 `Head_CT_ReConstruct/` 中的 STL 重建模型，在浏览器中完成 DICOM 切片预览、STL 模型预览、影像与模型三维融合观察、构件样式配置，并提供 NIfTI Mask 演示导出能力。

-目标能力：
-
- 输入头部 DICOM 序列。
- 对 DICOM 进行三维重建或读取已有重建模型。
- 从重建后的 STL 模型反向生成体素级分割 Mask。
- 面向医学影像分割标注流程提供可视化、管理和结果导出能力。
+当前系统仍以演示闭环为主，真实医学级 STL 到 DICOM 空间体素化算法尚未接入。后续接入真实算法时，应保留现有 API 和前端工作流，并替换后端 Mask 生成逻辑或接入独立算法服务。

 ## 当前目录结构

- `WebSite/`：前端应用主体，基于 Vite、React、TypeScript。
- `WebSite/src/`：主要页面和组件代码。
- `Head_CT_DICOM/`：头部 CT DICOM 文件目录。
- `Head_CT_ReConstruct/`：已重建 STL 文件目录，包括头部、头颅、气管、肿瘤等结构。
- `工程分析/`：工程分析、需求分析、实现方案、测试方案和经验记录目录。
+- `README.md`：项目目标、构建运行和部署入口说明。
+- `WebSite/`：前后端一体服务目录，包含 Vite React 前端与 Express 后端。
+- `WebSite/server.ts`：Express API、Vite 中间件、DICOM/STL 解析预览、NIfTI 演示导出、运行态状态存储。
+- `WebSite/src/`：React 页面、组件、类型和 API 封装。
+- `WebSite/src/components/Login.tsx`：登录页，默认账号 `admin`、密码 `123456`。
+- `WebSite/src/components/Sidebar.tsx`：主导航，包含总体概况、项目库、逆向工作区、系统管理工作区。
+- `WebSite/src/components/Overview.tsx`：项目、DICOM、STL、Mask 导出统计概览。
+- `WebSite/src/components/ProjectLibrary.tsx`：项目库、DICOM 切片预览、STL 预览、构件层级样式、Mask 下载入口。
+- `WebSite/src/components/ReverseWorkspace.tsx`：逆向工作区，提供 DICOM/STL 三维融合、模型位姿、切片范围和 STL 切面展示。
+- `WebSite/src/components/UserManagement.tsx`：系统管理与演示环境重置。
+- `Head_CT_DICOM/`：默认 DICOM 序列目录，不作为普通文档备份重点。
+- `Head_CT_ReConstruct/`：默认 STL 重建模型目录，不作为普通文档备份重点。
+- `工程分析/`：工程整体分析、代码编纂工作流、需求分析、实现方案、测试方案和经验记录。

-## 前端技术栈
+## 技术栈

- React 19
- TypeScript
- Vite 6
- Tailwind CSS 4
- Three.js、React Three Fiber、Drei
- Framer Motion / Motion
- Recharts
- Lucide React
+- Node.js 18+ 与 npm。
+- React 19、TypeScript、Vite 6。
+- Express 4 与 Vite 中间件，开发和 API 统一由 `npm run serve` 启动。
+- Tailwind CSS 4。
+- Three.js、React Three Fiber、Drei，用于 STL 和融合视图。
+- Motion/Framer Motion、Recharts、Lucide React。
+- Node 内置 `fs/path/zlib` 负责状态文件、DICOM/STL 文件读取、tar.gz 与 NIfTI gzip 演示导出。
+
+## 后端能力
+
+`WebSite/server.ts` 当前提供：
+
+- `/api/health` 健康检查。
+- `/api/session`、`/api/login`、`/api/logout`：共享登录状态。
+- `/api/users`：用户列表。
+- `/api/projects` 及项目增删改查。
+- `/api/projects/:projectId/module-styles`：构件显示、颜色、透明度、Mask ID 的项目级持久化。
+- `/api/projects/:projectId/dicom-preview`：轴向、矢状面、冠状面 DICOM 预览。
+- `/api/projects/:projectId/dicom-fusion-volume`：三维融合所需的 DICOM 体纹理抽样。
+- `/api/projects/:projectId/dicom-archive`：默认 DICOM 序列 tar.gz 下载。
+- `/api/projects/:projectId/dicom-info`：DICOM 关键元数据、spacing 与物理尺寸。
+- `/api/projects/:projectId/models/:fileName` 与 `/preview`：STL 文件与抽样三角面预览。
+- `/api/overview`：概况统计。
+- `/api/demo/reset`：恢复默认演示环境。
+- `/api/projects/:projectId/export-mask`：生成 `.nii` 或 `.nii.gz` 演示分割 Mask。
+
+## 运行态与数据
+
+- `WebSite/data/state.json`：共享登录、项目、用户和构件样式状态。
+- `WebSite/exports/`：Mask 导出文件。
+- `WebSite/dist/`：生产构建产物。
+- 默认项目 ID 为 `head-ct-demo`，由后端扫描 `Head_CT_DICOM/` 和 `Head_CT_ReConstruct/` 生成。
+- DICOM/STL 数据和运行态输出通常不应混入文档备份提交。

 ## 已知脚本

-`WebSite/package.json` 中已有脚本：
+在 `WebSite/` 下执行：

- `npm run dev`：启动 Vite 开发服务器，端口 3000，监听 `0.0.0.0`。
- `npm run build`：生产构建。
- `npm run preview`：预览构建结果。
- `npm run clean`：删除 `dist`。
+- `npm ci`：安装依赖。
 - `npm run lint`：执行 `tsc --noEmit` 类型检查。
+- `npm run build`：Vite 生产构建。
+- `npm run dev`：仅启动 Vite 开发服务器，默认端口 3000。
+- `npm run serve -- --host 0.0.0.0 --port 4000`：启动 Express + Vite 一体服务，是当前优先部署方式。

-## 数据资产
+## 部署约定

- DICOM 数据位于 `Head_CT_DICOM/`。
- STL 重建模型位于 `Head_CT_ReConstruct/`。
- 医学数据和模型文件体积可能较大，Git 备份时应谨慎，默认不将原始影像与重建模型纳入普通文档备份提交。
+- 当前 README 指向访问地址 `http://192.168.3.11:4000/`。
+- 历史经验记录显示本项目长期使用 `tmux` 会话 `revoxelseg-dicom` 托管服务，避免普通后台进程被回收。
+- 重新部署前先检查端口和已有 `tmux` 会话；部署后用 `/api/health` 和页面 HTTP 响应验证。

-## 后续重点
+## 修改风险重点

- 明确 DICOM 读取、排序、空间信息解析方式。
- 明确 STL 到体素 Mask 的坐标对齐策略。
- 明确 Mask 输出格式，例如 NIfTI、NRRD、DICOM SEG、PNG 序列或项目自定义格式。
- 明确前端是否只做可视化，还是需要增加后端处理服务。
- 对医学影像处理流程建立可复现测试样例和数据校验。
+- DICOM 与 STL 的空间基准不能随显示范围变化而变化，显示范围和物理坐标基准要分开处理。
+- 没有真实体素化或真实语义分割结果时，不应伪造 Mask 图像。
+- 构件样式是跨页面、跨浏览器共享状态，新增字段必须检查初始化、服务端归一化、前端更新和 fallback。
+- UI 截图或页面文字相关需求应先用可见文案全局定位真实源码。
+- 文档备份提交必须避免把无关的运行态产物、大型医学数据或既有未确认删除混入 commit。
--- a/工程分析/测试方案-2026-05-19-22-59-07.md
+++ b/工程分析/测试方案-2026-05-19-22-59-07.md
@@ -0,0 +1,54 @@
+# 测试方案-2026-05-19-22-59-07
+
+## 测试方案文档路径
+
+`工程分析/测试方案-2026-05-19-22-59-07.md`
+
+## 静态检查
+
+- 在 `WebSite/` 下执行 `npm run lint`，确认 TypeScript 类型检查通过。
+
+## 构建检查
+
+- 在 `WebSite/` 下执行 `npm run build`，确认生产构建成功生成 `dist/`。
+
+## 文档验证
+
+- 确认 `工程分析/` 存在。
+- 确认本次需求分析、实现方案、测试方案均按时间戳命名。
+- 确认 `工程分析/代码编纂工作流.md` 覆盖用户要求的 0 到 7 步。
+- 确认 `工程分析/经验记录.md` 保留旧经验并追加本次四段式记录。
+- 确认 `AGENTS.md` 包含后续项目修改必须执行该流程的约束。
+
+## 部署验证
+
+- 检查已有 `tmux` 会话和 `4000` 端口占用。
+- 使用 `tmux` 重新启动 `revoxelseg-dicom` 会话。
+- 验证：
+  - `curl http://127.0.0.1:4000/api/health`
+  - `curl -I http://127.0.0.1:4000/`
+
+## Git/Gitea 备份验证
+
+- 使用 `git status --short` 检查工作区。
+- 仅暂存本次相关文件。
+- 创建 commit：`2026-05-19-22-59-07 建立代码编纂工作流`。
+- 尝试 `git push origin main`。
+- 完成后提醒用户文档备份 commit 已完成；若推送失败，说明本地 commit 和失败原因。
+
+## 回归关注点
+
+- 本次不改业务代码，主要回归风险来自重新部署。
+- 注意不要把历史 `工程分析/需求分析-*`、`实现方案-*`、`测试方案-*` 的既有删除状态一起提交。
+- 注意不要提交 `WebSite/data/`、`WebSite/exports/`、医学影像数据或 STL 模型数据。
+
+## 实际执行结果
+
+- `npm run lint`：通过。
+- `npm run build`：通过；Vite 提示存在大 chunk 警告，但构建成功。
+- `tmux` 部署：已创建会话 `revoxelseg-dicom`。
+- 监听端口：`0.0.0.0:4000`，HMR 端口 `24679`。
+- 健康检查：`curl http://127.0.0.1:4000/api/health` 返回 `ok: true`。
+- 首页验证：`curl -I http://127.0.0.1:4000/` 返回 `HTTP/1.1 200 OK`。
+- Git 本地备份 commit：已创建本次工作流文档备份 commit，提交信息为 `2026-05-19-22-59-07 建立代码编纂工作流`。
+- Gitea 远端推送：执行 `git push origin main` 时失败，原因是 HTTP 远端 `http://192.168.31.5:5002` 无法读取用户名；未在命令行拼接或保存凭据。
--- a/工程分析/经验记录.md
+++ b/工程分析/经验记录.md
@@ -793,3 +793,57 @@ C. 解决问题方案
 D. 后续如何避免问题

 右侧结果展示区域应优先呈现真实数据或真实处理结果，避免使用占位式示意图长期冒充结果；如果尚未生成真实语义分割 Mask，应明确展示当前可验证的 STL 切面实体，而不是伪造 Mask 形状。
+
+## 2026-05-19-22-59-07 工程分析核心文档被删除状态下的恢复
+
+A. 具体问题
+
+本次开始时工作区中大量 `工程分析/` 历史文档处于删除状态，且本地目录不存在；如果直接创建新的短版 `经验记录.md` 或直接暂存整个目录，可能丢失旧知识库或把无关删除混入本次备份。
+
+B. 产生问题原因
+
+这些删除状态在本次操作前已经存在，且 `工程分析/经验记录.md` 在 Git 中已有 795 行历史经验。当前需求又要求读取或创建 `工程分析/`，容易把“恢复核心文档”和“提交所有删除”混为一谈。
+
+C. 解决问题方案
+
+先通过 Git 读取旧 `工程整体分析.md`、`代码编纂工作流.md` 和 `经验记录.md`，确认历史内容；随后只恢复并更新这三个核心文件，新增本次三份时间戳文档和 `AGENTS.md`，暂存时显式列出本次相关路径，避免提交其他历史删除。
+
+D. 后续如何避免问题
+
+每次发现工作区已有删除或修改时，先区分是否属于本次需求；文档备份 commit 要显式暂存文件路径，不能用 `git add .`。对 `经验记录.md` 这类知识库文件，更新前必须确认旧内容仍被保留。
+
+## 2026-05-19-22-59-07 固化后续代码编纂工作流
+
+A. 具体问题
+
+用户要求后续所有项目修改相关需求都执行固定流程，但仅在对话中说明流程不够稳固，未来进入项目的助手或开发者可能看不到这条约束。
+
+B. 产生问题原因
+
+工作流要求跨越多次会话和多次修改，单靠当前对话记忆不可靠；项目内原有 `代码编纂工作流.md` 也处于工作区删除状态，需要恢复并更新为当前版本。
+
+C. 解决问题方案
+
+更新 `工程分析/代码编纂工作流.md`，明确 0 到 7 步、默认不等待二次确认、文档备份提交和重新部署要求；同时新增根目录 `AGENTS.md`，把后续修改必须读取并执行该工作流作为项目入口约束。
+
+D. 后续如何避免问题
+
+后续任何项目修改前，先读取根目录 `AGENTS.md` 和 `工程分析/代码编纂工作流.md`；若用户提出新流程要求，应同步更新这两个入口文档和经验记录，确保流程约束留在仓库中。
+
+## 2026-05-19-22-59-07 Gitea HTTP 远端缺少可用凭据
+
+A. 具体问题
+
+本次本地文档备份 commit 已完成，但执行 `git push origin main` 时失败，Git 提示无法读取 `http://192.168.31.5:5002` 的用户名。
+
+B. 产生问题原因
+
+当前 `origin` 使用 HTTP Gitea 地址，执行环境没有交互式用户名输入，也没有可用的凭据助手或已保存认证信息。
+
+C. 解决问题方案
+
+保留本地 commit，不在命令行临时拼接账号密码，也不把凭据信息写入仓库或远端 URL。将推送失败原因记录到测试方案和经验记录中，等待用户提供安全的凭据方式后再推送。
+
+D. 后续如何避免问题
+
+需要 Gitea 远端备份前，先确认远端认证方式。优先使用安全的凭据助手、SSH remote 或用户已配置好的 token；不要把账号密码写进 commit、文档、remote URL 或 shell 历史。
--- a/工程分析/需求分析-2026-05-19-22-59-07.md
+++ b/工程分析/需求分析-2026-05-19-22-59-07.md
@@ -0,0 +1,53 @@
+# 需求分析-2026-05-19-22-59-07
+
+## 开始时间
+
+2026-05-19-22-59-07
+
+## 原始需求摘要
+
+用户要求在仔细阅读项目后，新建一套完整的代码编纂工作流。后续凡是项目修改相关需求，都需要按该流程执行：记录开始时间、阅读或创建 `工程分析/`、写入需求分析/实现方案/测试方案、执行前阅读经验记录、执行后按四段式更新经验记录、使用 Gitea 备份 commit，并重新部署项目。
+
+## 业务目标
+
+- 将项目修改流程固化为可追踪、可复用、可审计的工程文档制度。
+- 让后续需求从“直接改代码”升级为“先分析、再计划、再测试、再沉淀、再备份、再部署”的闭环。
+- 保留已有经验记录中的关键教训，避免重复犯错。
+- 让未来进入仓库的助手或开发者能通过项目文档理解必须执行的流程。
+
+## 输入与输出
+
+- 输入：用户给出的 0 到 7 条流程要求、当前项目源码、已有 README、Git 中历史 `工程分析/` 文档。
+- 输出：
+  - 更新后的 `工程分析/工程整体分析.md`
+  - 更新后的 `工程分析/代码编纂工作流.md`
+  - 本次 `需求分析`、`实现方案`、`测试方案`
+  - 更新后的 `工程分析/经验记录.md`
+  - 根目录 `AGENTS.md`，用于提示后续工作必须遵守该流程
+  - 文档备份 commit 与重新部署结果
+
+## 影响范围
+
+- 文档治理：`工程分析/` 下核心文档和本次时间戳文档。
+- 协作约束：根目录新增 `AGENTS.md`。
+- 项目业务代码：本次不修改业务代码。
+- 部署：按当前项目部署方式重新启动 `WebSite` 服务。
+
+## 关键约束
+
+- 当前工作区已有大量历史 `工程分析/` 时间戳文档处于删除状态，这些删除不是本次操作产生，不能混入本次提交。
+- 必须先阅读旧 `经验记录.md`，尤其是部署端口、tmux 托管、真实源码定位、DICOM/STL 空间基准、不要伪造 Mask 等历史经验。
+- 文档备份 commit 必须包含时间戳和本次修改简要描述。
+- 重新部署优先使用 `WebSite` 的 `npm run serve -- --host 0.0.0.0 --port 4000`。
+
+## 风险点
+
+- 如果误暂存整个 `工程分析/`，可能把历史文档删除一起提交。
+- 如果只创建新经验记录而不保留旧内容，会丢失已有知识库。
+- 如果部署时直接占用端口，可能影响正在运行的服务。
+- 如果未来助手没有读取项目文档，可能无法自动遵守流程，因此需要 `AGENTS.md` 增强可见性。
+
+## 默认假设
+
+- 用户本次需求本身也按新流程执行，但不需要在实现方案和测试方案阶段停等人工确认，因为历史工作流已有“后续直接搞”的确认。
+- “Gitea 备份 commit”理解为在本地 Git 创建 commit，并尝试推送到已配置的 Gitea `origin`。