diff --git a/tools/recalc_completeness.php b/tools/recalc_completeness.php
new file mode 100644
index 0000000..35f03e7
--- /dev/null
+++ b/tools/recalc_completeness.php
@@ -0,0 +1,63 @@
+<?php
+/**
+ * 完整度全量重算脚本（CLI 运行）
+ * 用法：php tools/recalc_completeness.php [--dry-run]
+ * 作用：遍历 persons / companies / social_accounts / media_commercial_attributes
+ *       全部记录，按三层完整度判定规则重新计算并刷新 is_incomplete。
+ * 场景：完整性规则变更后回填存量数据（如 v1.0.29 规则修订后）。
+ */
+require_once __DIR__ . '/../api/common/db.php';
+require_once __DIR__ . '/../api/common/completeness.php';
+
+$dryRun = in_array('--dry-run', $argv, true);
+
+$pdo = DB::getInstance()->getPdo();
+$summary = [];
+
+/** 逐条重算某表 */
+function recalcTable(PDO $pdo, $table, $sql, $dryRun, &$summary, $label, $realTable = null, $idCol = 'id')
+{
+    $realTable = $realTable ?: $table;
+    $rows = $pdo->query($sql)->fetchAll(PDO::FETCH_COLUMN);
+    $total = count($rows);
+    $changed = 0;
+    foreach ($rows as $id) {
+        $id = (int)$id;
+        if ($dryRun) {
+            // 只读计算，不写库
+            $info = completenessInfo($pdo, $table, $id);
+        } else {
+            $info = updateIncomplete($pdo, $table, $id);
+        }
+        if ($info === null) {
+            continue;
+        }
+        if ($dryRun) {
+            $flag = $info['is_complete'] ? 0 : 1;
+            $cur = (int)$pdo->query("SELECT is_incomplete FROM `$realTable` WHERE `$idCol` = $id")->fetchColumn();
+            if ($cur !== $flag) {
+                $changed++;
+            }
+        } else {
+            $changed++;
+        }
+    }
+    $summary[$label] = ['total' => $total, 'changed' => $changed];
+}
+
+echo $dryRun ? "[DRY-RUN] 仅统计，不写库\n" : "开始全量重算完整度标记...\n";
+
+recalcTable($pdo, 'persons', "SELECT id FROM persons", $dryRun, $summary, 'persons');
+recalcTable($pdo, 'companies', "SELECT id FROM companies", $dryRun, $summary, 'companies');
+recalcTable($pdo, 'social_accounts', "SELECT id FROM social_accounts", $dryRun, $summary, 'social_accounts');
+recalcTable($pdo, 'media', "SELECT social_account_id FROM media_commercial_attributes", $dryRun, $summary, 'media', 'media_commercial_attributes', 'social_account_id');
+
+foreach ($summary as $label => $s) {
+    printf("%-16s 共 %d 条，%s %d 条\n", $label, $s['total'], $dryRun ? '将被更新' : '已更新', $s['changed']);
+}
+
+$softTotal = 0;
+foreach (['companies', 'persons', 'social_accounts', 'media_commercial_attributes'] as $t) {
+    $softTotal += (int)$pdo->query("SELECT COUNT(*) FROM `$t` WHERE is_incomplete = 1")->fetchColumn();
+}
+echo "重算后软碎片总数：{$softTotal}\n";