diff --git a/client/electron/test/commit-hygiene.test.mjs b/client/electron/test/commit-hygiene.test.mjs
index ab88598..4d3ac0b 100644
--- a/client/electron/test/commit-hygiene.test.mjs
+++ b/client/electron/test/commit-hygiene.test.mjs
@@ -180,3 +180,52 @@ test('★ 欠账登记里的 static-criteria 必须等于实测（可见副本
     `欠账登记说 static-criteria=${registered}，实测 ${measured} —— 可见的那个数字是副本，` +
     `漂移了就必须两边一起改（这类"登记类"判据别改数字了事：先看是哪笔欠账还清了）`);
 });
+
+/**
+ * ★ 版本库里不许有 **AGC 客户端配置的真身**（pi 2026-09-15 裁定）。
+ *
+ * 为什么单靠 `.gitignore` 不够 —— 这是这条判据存在的全部理由：
+ * `agconnect-services.json` **必须在本地存在才能构建**（`hvigorw` 打包时要读它），
+ * 所以它天然会被 `git add -A` 顺手加回来；而**任何一次这样的 add 都不会有东西变红**。
+ * **ignore 是方便，判据才是机制。**
+ *
+ * 判据形状：扫**所有 tracked 文件**（不只 rawfile），找"AGC 配置的形状" ——
+ * 同时出现 `client_secret` 与 `code1` 这种键。命中即红，并点名文件。
+ * 另一半：`agconnect-services.example.json` **必须存在** —— 否则新人拿到仓库
+ * 不知道这个文件要长什么样，只能去问人或者猜（然后可能猜错键名，构建报一个看不懂的错）。
+ */
+test('★ 版本库里不许跟踪 AGC 配置真身（gitignore 挡不住 `git add -A`，判据才挡得住）', () => {
+  const ls = git(['ls-files']);
+  assert.equal(ls.status, 0, '要能列出 tracked 文件');
+  const files = ls.stdout.split('\n').map(s => s.trim()).filter(Boolean);
+  assert.ok(files.length > 50, `tracked 文件数异常（${files.length}）—— 列不出来时这条会假绿`);
+
+  const SHAPE = [
+    { what: 'AGC 信封密钥', re: /"client_secret"\s*:\s*"\[!/ },
+    { what: 'AGC 校验码', re: /"code1"\s*:\s*"[0-9A-F]{16,}"/ },
+    { what: 'AGC api_key 信封', re: /"api_key"\s*:\s*"\[!/ }
+  ];
+  const offenders = [];
+  for (const f of files) {
+    // example 是**故意**带这些键名的（结构留、值全打掉）——按内容判，不按文件名豁免
+    const src = prose(join(ROOT, f));
+    const hit = SHAPE.filter(s => s.re.test(src)).map(s => s.what);
+    // 只声明了键名但没有真值（值全是 `<…>`）的不算违规
+    const onlyPlaceholders = !/\[!00/.test(src) && !/"[0-9A-F]{32,}"/.test(src);
+    if (hit.length > 0 && !onlyPlaceholders) offenders.push(`${f}（${hit.join('、')}）`);
+  }
+  assert.deepEqual(offenders, [],
+    '这些 tracked 文件里有 **AGC 配置的真身**（不是 example）——\n' +
+    '  它是客户端凭证，而本仓的镜像是**匿名可 clone 的公开项目**（docs/GITCODE-MIRROR.md）：\n' +
+    '  一旦随 push 上去就撤不回。处理：\n' +
+    '    1) `git rm --cached <文件>`（**加 --cached**，别把本地那份删了 —— 构建要用它）\n' +
+    '    2) 确认 `client/harmony/.gitignore` 里那条规则在\n' +
+    '    3) 检查它有没有**已经**进过某次 push：`git cat-file -e origin/main:<路径>`\n' +
+    '       有 ⇒ 已经泄露，要按"已泄露"处理（轮换）；没有 ⇒ 只是本地，赶在下一次 push 前做完就行\n' +
+    `  命中：\n  ${offenders.join('\n  ')}`);
+
+  const examplePath = 'client/harmony/entry/src/main/resources/rawfile/agconnect-services.example.json';
+  assert.ok(files.includes(examplePath),
+    `缺少 ${examplePath} —— 真身不入库之后，新人只能从它知道这个文件要长什么样` +
+    `（键名错一个，构建会报一个和"配置缺失"毫无关系的错）`);
+});
diff --git a/client/electron/test/run-all.mjs b/client/electron/test/run-all.mjs
index c215322..2f532e0 100644
--- a/client/electron/test/run-all.mjs
+++ b/client/electron/test/run-all.mjs
@@ -83,7 +83,7 @@ const SUITE = [
   ['test/harmony-push.test.mjs', ['--experimental-strip-types', '--no-warnings'], 13],
   ['test/harmony-calendar.test.mjs', ['--experimental-strip-types', '--no-warnings'], 23],
   ['test/debt-visibility.test.mjs', [], 1],
-  ['test/commit-hygiene.test.mjs', ['--experimental-strip-types', '--no-warnings'], 2],
+  ['test/commit-hygiene.test.mjs', ['--experimental-strip-types', '--no-warnings'], 4],
   // 判据目录自身的卫生：读文本必须走 test/lib/read.mjs 的具名入口
   ['test/criteria-hygiene.test.mjs', [], 5],
   // 用户管理页（P4c 同批）：动作↔服务端调用同名 / 门禁只认严格 admin /
diff --git a/client/harmony/.gitignore b/client/harmony/.gitignore
index d2ff201..2ff87b2 100644
--- a/client/harmony/.gitignore
+++ b/client/harmony/.gitignore
@@ -9,4 +9,18 @@
 /.clang-format
 /.clang-tidy
 **/.test
-/.appanalyzer
\ No newline at end of file
+/.appanalyzer
+
+# ── AGC 客户端配置：**不入版本库**（pi 2026-09-15 的裁定）──
+#
+# 这个文件**必须在本地存在才能构建**（`hvigorw` 打包时要读它），所以它天然会被
+# `git add -A` 顺手加回来 —— 光靠这行 ignore 挡不住（**ignore 是方便，判据才是机制**，
+# 见 `client/electron/test/commit-hygiene.test.mjs` 里那条"不许有 tracked 的 AGC 形状文件"）。
+#
+# 它含 `client_secret`/`api_key`（AGC 的 `[!00…]` 信封格式）与**明文**的
+# `client_id`/`app_id`/`code1..4`。本仓的镜像（`docs/GITCODE-MIRROR.md`）是
+# **匿名可 clone 的公开项目** ⇒ 一旦随某次 push 上去，就再也撤不回。
+#
+# 新同事怎么开始：把 `agconnect-services.example.json` 复制成这个名字，
+# 再从 AGC 控制台/密钥库把真值填回去。
+/entry/src/main/resources/rawfile/agconnect-services.json
\ No newline at end of file
diff --git a/client/harmony/entry/src/main/resources/rawfile/agconnect-services.example.json b/client/harmony/entry/src/main/resources/rawfile/agconnect-services.example.json
new file mode 100644
index 0000000..e5966a2
--- /dev/null
+++ b/client/harmony/entry/src/main/resources/rawfile/agconnect-services.example.json
@@ -0,0 +1,63 @@
+{
+  "agcgw_all": {
+    "SG": "<值>",
+    "SG_back": "<值>",
+    "CN": "<值>",
+    "CN_back": "<值>",
+    "RU": "<值>",
+    "RU_back": "<值>",
+    "DE": "<值>",
+    "DE_back": "<值>"
+  },
+  "websocketgw_all": {
+    "SG": "<值>",
+    "SG_back": "<值>",
+    "CN": "<值>",
+    "CN_back": "<值>",
+    "RU": "<值>",
+    "RU_back": "<值>",
+    "DE": "<值>",
+    "DE_back": "<值>"
+  },
+  "client": {
+    "cp_id": "<值>",
+    "product_id": "<值>",
+    "client_id": "<AGC client_id>",
+    "client_secret": "<AGC client_secret 的信封值 —— 从 AGC 控制台下载的 agconnect-services.json 里原样粘贴>",
+    "project_id": "<值>",
+    "app_id": "<AGC app_id>",
+    "api_key": "<AGC api_key 的信封值 —— 同上>",
+    "package_name": "com.jianf.agentmail"
+  },
+  "oauth_client": {
+    "client_id": "<AGC client_id>",
+    "client_type": "<值>"
+  },
+  "app_info": {
+    "app_id": "<AGC app_id>",
+    "package_name": "com.jianf.agentmail"
+  },
+  "code": {
+    "code1": "<值>",
+    "code2": "<值>",
+    "code3": "<值>",
+    "code4": "<值>"
+  },
+  "configuration_version": "<值>",
+  "appInfos": [
+    {
+      "package_name": "com.jianf.agentmail",
+      "client": {
+        "client_secret": "<AGC client_secret 的信封值 —— 从 AGC 控制台下载的 agconnect-services.json 里原样粘贴>",
+        "app_id": "<AGC app_id>",
+        "api_key": "<AGC api_key 的信封值 —— 同上>"
+      },
+      "code": {
+        "code1": "<值>",
+        "code2": "<值>",
+        "code3": "<值>",
+        "code4": "<值>"
+      }
+    }
+  ]
+}