refactor(mds): unify inode/partition/dirshard version tracking

.agents/skills/automate-test/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: automate-test
+description: 开发环境测试闭环：单元测试 / e2e / 重型回归 / xfstests。
+context: fork
+disable-model-invocation: true
+---
+
+# dingofs 自动化测试技能
+
+自动化测试闭环：跑测试 → 定位失败 → 修代码 → 重编译重部署 → 再跑。仅限开发环境，不用于生产，不自行 git 提交。
+
+## 前置：服务就绪
+
+编译、MDS/client 的部署启动、日志位置全部见 `/skill:dev-deploy`。本技能假设 dist/ 下服务已在跑，**不重复部署步骤**。
+
+## 编译
+
+```bash
+cd build && make -j 12
+```
+
+单元测试二进制要求 build 以 `-DBUILD_UNIT_TESTS=ON` 配置（当前 build/ 已满足）。若 `build/bin/test` 不存在或为空，重新配置：
+
+```bash
+cd build && cmake -DCMAKE_BUILD_TYPE=RelWithDebInfo -DBUILD_UNIT_TESTS=ON .. && make -j 12
+```
+
+## 单元测试
+
+`build/bin/test` 下是 gtest 二进制，逐个直接运行，无需参数。`test_coverage_helper` 是覆盖率辅助程序，跳过。
+
+判据：进程退出码为 0，且输出中无 `[  FAILED  ]`。
+
+## 端到端与重型工具
+
+`run_all_test.sh` 封装了 e2e / pjdfstest / fsx / mdtest / fio / fsstress。**`--mountpoint` 必填**，不传直接退出。
+
+```bash
+cd scripts/dev-mds
+bash run_all_test.sh --mountpoint=$MOUNT_POINT --type=e2e --round=1
+```
+
+| 场景 | `--type` |
+|---|---|
+| 日常回归 | `e2e` |
+| 全量重型（e2e / pjdfstest / fsx / mdtest / fsstress） | `all` |
+| 单个工具 | `pjdtest` \| `fsx` \| `mdtest` \| `fio` \| `fsstress` |
+
+- `--round` 默认 1；只有反复跑找偶发才需要调大。
+- e2e 依赖 `test/e2e` 的 uv 环境；pjdfstest 依赖 `/home/dengzihui/work/dingofs-test/pjdfstest/tests` 存在。
+- `--mds-addr` 在脚本里已定义但未使用，不要传。
+
+判据：退出码 0，且输出中没有 `result: FAIL` —— **脚本只对 e2e / pjdfstest / fsx 判定**；mdtest / fio / fsstress 不判定，需自己查日志确认无 error。
+
+日志：`/tmp/dev-regression-test/<tool>_<时间戳>_<轮次>/`。
+
+## xfstests（脚本未覆盖）
+
+适配层的安装、产物、local/MDS 两种模式见仓库 `xfstests/README_CN.md`，不在此重复。
+
+```bash
+# 一次性：安装挂载 helper 并生成配置；meta-url 按需改
+DINGOFS_META_URL_TEMPLATE="mds://<SERVER_HOST>:7801/{fsname}" \
+  bash xfstests/setup.sh /home/dengzihui/work/dingofs-test/xfstests-dev
+```
+
+```bash
+cd /home/dengzihui/work/dingofs-test/xfstests-dev
+sudo ./check $(cat tests/generic/supported)
+```
+
+`<SERVER_HOST>` 从 `scripts/dev-mds/mds_deploy_parameters.local` 取。
+
+判据：`./check` 退出码 0（末行 `Passed all ... tests`）。
+失败证据：`results/generic/NNN.out.bad`（测试侧）、`/mnt/dingofs-xfstests/runtime/<fsname>/log/`（client 侧）。
+
+## vdbench（脚本未覆盖）
+
+```bash
+cd /home/dengzihui/work/dingofs-test/vdbench
+# 先改 config/test-01.vd：anchor= 指到 $MOUNT_POINT 下，elapsed 改成回归可接受的秒数
+./vdbench -f config/test-01.vd
+```
+
+判据：退出码 0 且输出无 error。结果在 `output/logfile.html`、`output/flatfile.html`。
+
+## 测试对象地址
+
+第 1 个 MDS 实例监听 `<SERVER_HOST>:<SERVER_START_PORT + 1>`（默认 7801），取值见 `scripts/dev-mds/mds_deploy_parameters.local`。
+
+- meta: `mds://<SERVER_HOST>:7801/<fs_name>`
+- fs 不存在时先创建（需要 MDS 已在跑）：`cd scripts/dev-mds && bash create_fs.sh --fs_name=$FS_NAME --mds_addr=<SERVER_HOST>:7801`
+
+## 流程
+
+1. **编译**：`cd build && make -j 12` 成功。
+2. **确认服务在跑**：`pgrep -c -x dingo-mds` 等于 `SERVER_NUM`，且 `mountpoint -q $MOUNT_POINT` 成立；不一致先按 `/skill:dev-deploy` 重部署。（不要用 `ps -ef | grep`：会匹配到自己，且本机可能另有部署的 client。）
+3. **执行测试**：单元测试逐个跑，或 `run_all_test.sh --type=...`；需要时加 xfstests / vdbench。记录到 trace（见下）。
+4. **判定**：按各自判据全绿 → 跳 6；有失败 → 下一步。
+5. **定位并修复**：e2e 失败看对应 `result` 上方的日志目录，单元测试看 stderr，结合 `dist/*/log/` 里的服务日志定位根因，改代码后回到 1。
+   **同一个测试连续 3 轮仍不通过就停手**，把已定位的根因、试过的改法、日志路径汇报给用户，不要继续盲改。
+6. **报告**：给出变更清单与测试结论。**不要自行 git 提交**，提交交给用户或 `/skill:git-commit`。
+
+## 跟踪
+
+每完成上面一步，向 `/tmp/automate-test.trace` 追加一行：
+
+```
+<时间> <步骤号> <命令> <结果> <日志路径>
+```

.agents/skills/dev-deploy/SKILL.md

@@ -1,73 +1,98 @@
 ---
 name: dev-deploy
-description: 在开发环境部署dingofs的技能，当开发完成功能或修复bug后，可以使用这个技能将代码部署到测试环境进行验证
+description: 开发环境部署/重部署 dingofs：部署并启动 MDS 与 client，再做基本可用性冒烟。开发完成功能或修复 bug 后，需要把改动跑起来（重启服务）验证时使用。仅限开发环境，不做性能/压力/稳定性测试。
 context: fork
-disable-model-invocation: true
 ---
 
+# dingofs 部署技能
 
-# dingofs部署技能
-**注意**: 本技能仅适用于开发环境部署测试dingofs，不能用于生产环境部署，并只进行基本功能验证，不用于性能测试或压力测试或者稳定性测试。
-
-## 脚本
-脚本在`scripts/dev-mds`目录下，包含以下文件：
-- ** mds_deploy_parameters **: 部署mds服务器的参数配置文件，包含服务器实例数量、起始端口号、起始实例ID等参数。
-  - CLUSTER_ID: 集群ID，默认为101
-  - SERVER_NUM: 服务器实例数量，默认为1
-  - SERVER_HOST: 服务器主机IP地址
-  - SERVER_LISTEN_HOST: 服务器监听IP地址
-  - SERVER_START_PORT: 服务器起始端口号，默认为7800
-  - MDS_INSTANCE_START_ID: mds服务器实例起始ID，默认为1000
-  - COORDINATOR_ADDR: coordinator地址
-- ** deploy_mds.sh **: 部署mds服务器的脚本，支持部署多个实例，并且可以选择是否替换配置文件。
-- ** start_mds.sh **: 启动mds服务器的脚本，支持启动多个实例，并且可以选择是否替换配置文件。
-- ** stop_mds.sh **: 停止mds服务器的脚本，支持停止多个实例。
-- ** start_client.sh **: 部署和启动client的脚本
-
-## MDS部署、启动、停止
-**注意**: 必须在脚本目录scripts/dev-mds下执行以下命令，否则会报错。
-部署目标目录为项目根目录下的dist目录。
-```bash
-# 进入脚本目录
-cd scripts/dev-mds
+仅适用于开发环境：部署 + 基本功能验证。不用于生产环境，也不用于性能/压力/稳定性测试。
 
-# 部署，部署目录为 dist/mds-1 dist/mds-2 ... dist/mds-N，N为服务器实例数量
-# mds目录下包括：bin、conf、log等目录
-bash deploy_mds.sh --server_num=${SERVER_NUM}
+## 参数
 
-# 启动
-bash start_mds.sh --server_num=${SERVER_NUM}
+`scripts/dev-mds/mds_deploy_parameters.local` —— 本机私有，已被 `.gitignore` 忽略；入库的模板是 `mds_deploy_parameters`，首次从模板复制。
 
-# 停止
-bash stop_mds.sh --server_num=${SERVER_NUM}
+脚本真正消费的键：
 
-# 一键部署、启动
-bash clean_start.sh --server_num=${SERVER_NUM}
+- `SERVER_NUM`：MDS 实例数
+- `SERVER_HOST` / `SERVER_LISTEN_HOST`：对外 / 监听地址
+- `SERVER_START_PORT`：起始端口；第 `i` 个实例为 `SERVER_START_PORT + i`，即首实例 `7801`
+- `CLUSTER_ID`、`MDS_INSTANCE_START_ID`、`COORDINATOR_ADDR`
+- `STORAGE_ENGINE` / `STORAGE_URL`：由 `deploy_mds.sh` 写进 `mds.conf`
+- `S3_ENDPOINT` / `S3_AK` / `S3_SK` / `S3_BUCKETNAME`、`LOCAL_DATASTORE_PATH`：仅 `create_fs.sh` 使用
 
-```
+## 步骤
 
+以下命令**必须**在 `scripts/dev-mds` 目录下执行，否则脚本会报错。部署产物在项目根目录 `dist/`。
 
-## Client部署启动
-**注意**: 必须在脚本目录scripts/dev-mds下执行以下命令，否则会报错。
-```bash
+1. **编译**
+
+   ```bash
+   cd build && make -j 12
+   ```
+
+   判据：退出码 0。
+
+2. **停止 client**
+
+   先停 client 再动 MDS —— MDS 的二进制会被重新软链，挂着旧进程容易踩坑。
+
+   ```bash
+   cd scripts/dev-mds
+   sudo ./start_client.sh --meta=$META_ADDR --mountpoint=$MOUNT_POINT --num=1 --stop
+   ```
+
+3. **部署并启动 MDS**
+
+   ```bash
+   bash clean_start.sh --server_num=$SERVER_NUM
+   ```
+
+   判据：`pgrep -c dingo-mds` 输出等于 `SERVER_NUM`。（不要用 `ps -ef | grep`，它会匹配到自己，也不校验数量。）
 
-# 进入脚本目录
-cd scripts/dev-mds
+   失败看 `dist/mds-<i>/log/out`。
 
-# 部署和启动client （需要先部署启动mds服务器）
-# META_ADDR: mds服务器的地址，格式为mds://ip:port/fs_name 例如mds://10.220.69.5:7801/dengzh_hash_01
+4. **启动 client**
 
+   `META_ADDR` 格式为 `mds://<SERVER_HOST>:<SERVER_START_PORT+1>/<fs_name>`，例如 `mds://10.220.69.5:7801/dengzh_hash_01`。fs 不存在时先创建：
 
-sudo ./start_client.sh --meta=$META_ADDR --mountpoint=$MOUNT_POINT --num=1 --noupgrade --clean_log
+   ```bash
+   bash create_fs.sh --fs_name=$FS_NAME --mds_addr=$SERVER_HOST:$(($SERVER_START_PORT + 1))
+   ```
 
+   ```bash
+   sudo ./start_client.sh --meta=$META_ADDR --mountpoint=$MOUNT_POINT \
+     --num=1 --noupgrade --clean_log
+   ```
 
-# 停止
-sudo ./start_client.sh --meta=$META_ADDR --mountpoint=$MOUNT_POINT --num=1 --stop
+   - `--noupgrade`：不重装 client 二进制，直接用 `dist/client/bin` 下已有的
+   - `--clean_log`：清掉 `dist/client/log/` 的旧日志（排查问题时建议保留，去掉此参数）
 
+   判据：`mountpoint -q $MOUNT_POINT`。
+
+5. **冒烟验证**
+
+   ```bash
+   touch $MOUNT_POINT/.deploy_check && rm $MOUNT_POINT/.deploy_check
+   ```
+
+   判据：退出码 0。失败先看 `dist/client/log/` 与 `dist/mds-*/log/`。
+
+6. **汇报**
+
+   给用户：MDS 实例数、client 挂载点、冒烟结果、日志路径。**不要自行 git 提交**，提交交给用户或 `/skill:git-commit`。
+
+需要跑测试（单元 / e2e / 重型回归 / xfstests）→ `/skill:automate-test`。
+
+## 首次环境
+
+集群和文件系统尚不存在时，MDS 起来之后先建（`create_cluster.sh` 的 `--cluster_id` 必须大于 0）：
+
+```bash
+bash create_cluster.sh --cluster_id=101
+bash create_fs.sh --fs_name=$FS_NAME --mds_addr=$SERVER_HOST:$(($SERVER_START_PORT + 1))
 ```
 
+## 其他脚本
 
-## 步骤
-1. 代码变更后，重新编译代码，编译成功后进入后续步骤。
-2. 一键部署、启动mds服务器，使用clean_start.sh脚本，启动成功后进入后续步骤，可以使用`ps -ef | grep dingo-mds`命令查看mds服务器是否启动成功。
-3. 先停止client，再启动client，使用start_client.sh脚本，启动成功后进入后续步骤，可以使用`ps -ef | grep dingo-client`命令查看client是否启动成功。
+`deploy_mds.sh` / `start_mds.sh` / `stop_mds.sh` 是 `clean_start.sh` 的拆分，只重启 MDS 时单独用。参数以 `bash <脚本> --help` 为准。