@@ -5,7 +5,8 @@ English | [简体中文](README.zh-CN.md)
 A Chinese classical divination Mini App. It casts hexagrams with the Plum Blossom method
 (梅花易数), reads the result through the classical 体用生克 rules, and ships a searchable
 library of all sixty-four hexagrams plus a ganzhi almanac. Everything runs locally; the app
-makes no network requests and reads nothing outside its own package.
+makes no network requests. The only file it reads outside its own directory is its own
+reading log, inside the private `dataDir` the Host creates for it.
 
 The interface is in Chinese. To get going, read the **Usage guide** below; the derivation rules
 and capability disclosures follow it.
@@ -320,7 +321,7 @@ Chinese is the AI's job. See "A note on use" below.
 
 **Where do my questions go?**
 Nowhere. Saved castings only touch `context.dataDir` on your own machine. The app does not go
-online and reads nothing outside its package.
+online, and the one file it reads outside its own directory is that same reading log.
 
 ## What it does
 
@@ -347,9 +348,16 @@ to "打开灵签易占".
   really closes the listener and is idempotent, that no log line carries the `dataDir` path or the
   operating-system user name, and that the `dataDir` afterwards holds nothing but the reading log.
   macOS, Node 22.23.2: all 83 checks pass.
-- The suite is run under four timezones spanning UTC-8 to UTC+14 (`America/New_York`, `UTC`,
-  `Asia/Shanghai`, `Pacific/Kiritimati`) and under `LC_ALL=C LANG=C`. 228 pass, 0 fail in every
-  combination, so nothing here depends on the machine's clock zone or locale.
+- The suite is run under nine timezones spanning UTC-8 to UTC+14 (`America/New_York`, `UTC`,
+  `Asia/Shanghai`, `Pacific/Kiritimati`, `Pacific/Apia`, `America/Los_Angeles`,
+  `Pacific/Honolulu`, `Pacific/Chatham`, `Australia/Eucla` — the last two sit on UTC+12:45 and
+  UTC+8:45) and under `LC_ALL=C LANG=C`. 248 pass, 0 fail in every combination.
+- Two guards keep it that way, because the suite has twice broken on a date: no test may build a
+  moment from an absolute instant (`new Date('…')`), since `castByTime` and `castDaily` take the
+  hour and the day pillar from the machine's own zone, and no test may reach for the bare clock
+  without saying `real-clock:` and why. Every MCP call has to pass a `now` explicitly — the two
+  cast results follow the day's ganzhi, which is exactly how an assertion about 出伏 or 日破 once
+  started passing or failing depending on the day it was run.
 - A path audit over the package reports no problems: every path segment is ASCII and matches the
   portable-path rule, no segment collides with a Windows reserved device name, every text file is
   UTF-8 with no BOM and no CRLF, no two files differ only by case, every relative import resolves to
 
@@ -3,7 +3,7 @@
 [English](README.md) | 简体中文
 
 中国传统文化占卜 Mini App。以梅花易数起卦，按体用生克断吉凶，内置六十四卦全文与干支历法。
-全部计算在本机完成：不联网，不读取包目录以外的任何文件。
+全部计算在本机完成：不联网；包目录以外只读一个文件——Host 为它建的那个私有 `dataDir` 里的卦历。
 
 界面为中文。想直接上手，看下面的**使用指南**；想看推演口径与能力披露，往下翻。
 
@@ -303,9 +303,14 @@ README 的安装说明）。重启 MiniMax Code 后对 Agent 说「打开灵签
   非回环名——这一项走裸 HTTP 请求驱动，因为 `fetch` 会把调用方给的 `Host` 静默丢掉；还断言
   `dispose` 真的关掉监听且可重复调用、日志里没有 `dataDir` 路径也没有操作系统用户名、跑完之后
   `dataDir` 里只剩卦历文件。macOS，Node 22.23.2：83 项全过。
-- 同一套测试在四个时区下各跑一遍（`America/New_York`、`UTC`、`Asia/Shanghai`、`Pacific/Kiritimati`，
-  跨 UTC-8 到 UTC+14），另加 `LC_ALL=C LANG=C` 极窄 locale 一遍。每种组合都是 228 通过、0 失败，
-  即此处不依赖本机时区与 locale。
+- 同一套测试在九个时区下各跑一遍（`America/New_York`、`UTC`、`Asia/Shanghai`、`Pacific/Kiritimati`、
+  `Pacific/Apia`、`America/Los_Angeles`、`Pacific/Honolulu`、`Pacific/Chatham`、`Australia/Eucla`，
+  跨 UTC-8 到 UTC+14；后两个分别在 UTC+12:45 与 UTC+8:45），另加 `LC_ALL=C LANG=C` 极窄 locale 一遍。
+  每种组合都是 248 通过、0 失败。
+- 两条守卫让它一直是这样，因为这套测试已经在日期上栽过两次：测试不许用绝对时刻
+  （`new Date('…')`）构造时刻——`castByTime` 与 `castDaily` 取的是本机时区的时辰与日柱；
+  也不许碰真时钟而不写明 `real-clock:` 与理由。每一次 MCP 调用都必须显式给 `now`——
+  起卦结果跟着日辰走，断出伏或日破的断言就是这么一度跟着跑测试的当天翻面的。
 - 一份路径审计扫全包，0 问题：每个路径段都是 ASCII 且符合可移植路径规则，没有段撞 Windows 保留
   设备名，全部文本文件 UTF-8、无 BOM、无 CRLF，没有两个文件只差大小写，每条相对 import 都能在磁盘
   上找到，最坏形态的 `dataDir` 全路径 112 字符，离 `MAX_PATH` 还远。
 
@@ -860,6 +860,16 @@
         align-items: center;
       }
 
+      /* 存卦那行的可见提示。存不下时这里要说得出来，不能只往 live region 里写。 */
+      .save-status {
+        font-size: 13px;
+        color: var(--text-muted);
+      }
+
+      .save-status.err {
+        color: var(--seal);
+      }
+
       input[type='text'],
       input[type='number'],
       textarea {
@@ -2020,11 +2030,10 @@ <h2>卦历</h2>
       </main>
 
       <footer class="disclaimer">
-        <strong>内容由 AI 生成，仅供娱乐，无实际预测功能。</strong>
         <p>
-          本应用实现的是中国传统占筮方法，依据梅花易数的体用生克、旺衰与取象规则推演，
-          所有文字由 AI 生成。卦象不构成任何建议、预测或决策依据，不应作为医疗、法律、财务
-          等重要决定的参考。娱乐之外，请以自身判断与专业意见为准。
+          本应用实现的是中国传统占筮方法，依据梅花易数的体用生克、旺衰与取象规则推演。
+          <strong>内容由 AI 生成，仅供娱乐，无实际预测功能。卦象不构成任何建议、预测或决策依据，不应作为医疗、法律、财务等重要决定的参考。</strong>
+          娱乐之外，请以自身判断与专业意见为准。
         </p>
       </footer>
     </div>
@@ -2062,7 +2071,12 @@ <h2>卦历</h2>
         });
         if (!response.ok) {
           const detail = await response.json().catch(() => ({}));
-          throw new Error(detail.message || `请求失败（${response.status}）`);
+          const error = new Error(detail.message || `请求失败（${response.status}）`);
+          // 带上状态码与错误码，调用方才分得清「这一卦存不了了」（终态）与
+          // 「这条已经存过了」（还能改批注重试）——两者对按钮的处理完全不同。
+          error.status = response.status;
+          error.code = detail.error || '';
+          throw error;
         }
         return response.json();
       }
@@ -3294,16 +3308,21 @@ <h2>卦历</h2>
         const saveBtn = document.createElement('button');
         saveBtn.className = 'primary';
         saveBtn.textContent = '存入卦历';
-        saveBtn.addEventListener('click', () => saveReading(reading, saveBtn, noteInput));
-        save.append(noteInput, saveBtn);
+        // 可见的存卦状态。原先失败只往 live region 里写，屏幕上什么都不出现。
+        const saveStatus = document.createElement('span');
+        saveStatus.className = 'save-status';
+        saveStatus.setAttribute('aria-live', 'polite');
+        saveBtn.addEventListener('click', () => saveReading(reading, saveBtn, noteInput, saveStatus));
+        save.append(noteInput, saveBtn, saveStatus);
         card.append(save);
 
         slot.append(card);
         mountClashRibbons(card);
       }
 
-      async function saveReading(reading, button, noteInput) {
+      async function saveReading(reading, button, noteInput, status) {
         button.disabled = true;
+        setSaveStatus(status, '存入中…');
         try {
           // 只送 id 与批注，不再把整份 reading 回传给服务端——服务端认的是它自己
           // 刚算出来过的卦。原先整份回传、原样落盘，那是整个包里唯一一处没设防的地方。
@@ -3312,14 +3331,32 @@ <h2>卦历</h2>
             body: JSON.stringify({ id: reading.id, note: noteInput.value }),
           });
           button.textContent = '已存入卦历';
+          setSaveStatus(status, '');
           announce('已存入卦历');
         } catch (error) {
+          // 失败要给看得见的反馈。原先只 announce()，那写进的是 .sr-only 的 live region，
+          // 屏幕上什么也没有，按钮又复原成可点——用户看到的就是「点了没反应」，
+          // 再点还是一样。服务重启后这一卦再也存不了，所以那一支连按钮都不还给用户。
+          if (error.code === 'unknown_cast') {
+            button.textContent = '这一卦存不了了';
+            setSaveStatus(status, error.message, true);
+            announce(error.message);
+            return;
+          }
           button.disabled = false;
           button.textContent = '存入卦历';
+          setSaveStatus(status, error.message, true);
           announce(error.message);
         }
       }
 
+      /** 存卦那行的可见提示。aria-live 让读屏软件也念得到。 */
+      function setSaveStatus(status, text, isError = false) {
+        status.textContent = text;
+        status.classList.toggle('err', Boolean(isError));
+        status.setAttribute('role', isError ? 'alert' : 'status');
+      }
+
       /* ---------- 卦库 ---------- */
 
       async function loadLibrary() {
 
@@ -33,6 +33,9 @@ export const CAST_METHODS = Object.freeze(['time', 'daily', 'numbers', 'coins',
 
 /** 铜钱摇卦的次数，由古法定的，不给改。 */
 const COIN_TOSSES = 6;
+/** 三枚铜钱一次投掷的点数范围：三个背面 9，三个正面 6。 */
+const COIN_SUM_MIN = 6;
+const COIN_SUM_MAX = 9;
 
 /**
  * 包版本。`.minimax-plugin/plugin.json` 不在运行时载荷里（载荷只有 `artifacts` 下的
@@ -96,14 +99,33 @@ export function clampText(value, max) {
  * @param {unknown} sums
  * @returns {number[]}
  */
+/**
+ * 摇卦的六次结果，逐次校验到 6–9。
+ *
+ * 收 1–9 是照抄了 `toBoundedInteger` 的通用上界，提示却写着 6–9：传进 1–5 时它放行，
+ * 随后被 `castByCoins` 的普通 Error 接住——那条路没有 recovery，Agent 拿到的只是
+ * 「必须是 6 到 9 之间的整数」而没有该怎么做。这里就按真实的点数范围收。
+ *
+ * @param {unknown} sums
+ * @returns {number[]}
+ */
 function coinSumsFrom(sums) {
   if (!Array.isArray(sums) || sums.length !== COIN_TOSSES) {
     throw new CastParamError(
       `摇卦要 ${COIN_TOSSES} 次掷钱结果。`,
       `传 ${COIN_TOSSES} 个 6 到 9 之间的整数。`,
     );
   }
-  return sums.map((sum, index) => toBoundedInteger(sum, 9, `第 ${index + 1} 次掷钱结果`));
+  return sums.map((sum, index) => {
+    const parsed = toBoundedInteger(sum, COIN_SUM_MAX, `第 ${index + 1} 次掷钱结果`);
+    if (parsed < COIN_SUM_MIN) {
+      throw new CastParamError(
+        `第 ${index + 1} 次掷钱点数是 ${parsed}。`,
+        `三枚铜钱点数只落在 ${COIN_SUM_MIN} 到 ${COIN_SUM_MAX} 之间：背面三个为 ${COIN_SUM_MAX}，正面三个为 ${COIN_SUM_MIN}。`,
+      );
+    }
+    return parsed;
+  });
 }
 
 /**
 
@@ -1872,5 +1872,11 @@ function buildId(hexagram, positions, now) {
   for (let index = 0; index < seed.length; index += 1) {
     hash = (hash * 31 + seed.charCodeAt(index)) >>> 0;
   }
-  return `${stamp}-${hash.toString(36).slice(0, 6)}`;
+  // padStart 而不是 slice：32 位的 hash 转 36 进制有 6 位也有 7 位（36^6 < 2^32 < 36^7），
+  // `slice(0, 6)` 会把 7 位的那种砍掉最低位——而种子末尾那个递增计数改的正是最低位，
+  // 于是「同一秒、同一个卦」拿回同一个 id，实测 3000 组里撞 1228 组。
+  // 新的存卦约定按 id 取卦，撞了之后后一卦会把前一卦盖掉：在甲那张卡上点存入，
+  // 落盘的却是乙那张的问题。补零而不截断是单射的——36 进制里 7 位数的首位不会是 0，
+  // 所以补出来的 '0xxxxxx' 与真正的 7 位数不可能相同。长度仍落在 [A-Za-z0-9-]{1,80} 内。
+  return `${stamp}-${hash.toString(36).padStart(7, '0')}`;
 }
@@ -26,6 +26,20 @@ import {
   tossCoinSums,
 } from '../cast-params.mjs';
 
+/**
+ * MCP 对外认的起法。`hexagram` 是页面卦库那一路专用的，不进工具 schema。
+ * 取自 CAST_METHODS 而不是另写一份数组，少一处会漂移的地方。
+ */
+export const MCP_CAST_METHODS = Object.freeze(
+  CAST_METHODS.filter((item) => item !== 'hexagram'),
+);
+
+/**
+ * 工具描述里 `method` 的那组枚举，与实际认的起法同一份。schema 与实现各写一份时，
+ * 会出现「提示说可以、实际做不到」或反过来。
+ */
+const MCP_CAST_METHOD_ENUM = Object.freeze([...MCP_CAST_METHODS]);
+
 const SERVER_INFO = Object.freeze({ name: 'chinese-divination', version: PACKAGE_VERSION });
 
 /**
@@ -86,7 +100,7 @@ const TOOLS = Object.freeze([
         ...QUESTION_PROPERTY,
         method: {
           type: 'string',
-          enum: CAST_METHODS.filter((item) => item !== 'hexagram'),
+          enum: MCP_CAST_METHOD_ENUM,
           description:
             '起法。time=以当下时辰成卦（两小时一换）；daily=按今日日期成卦（一天一换）；numbers=由你给两个正整数，默念所问之后自行取数，一上卦一下卦；coins=由本工具掷六次铜钱，每次皆不同。用户说「掷铜钱」或要随机时用 coins，说「今天」用 daily。',
           default: 'time',
@@ -290,6 +304,35 @@ function plainBlock(reading) {
   ].filter(Boolean).join('\n');
 }
 
+/**
+ * `divination_cast` 在 schema 里声明的键。白名单而不是黑名单：Agent 多传了什么，
+ * 这里就不认什么。
+ */
+const CAST_ARG_KEYS = Object.freeze(['question', 'topic', 'method', 'upper', 'lower']);
+
+/**
+ * 按白名单收一遍起卦参数，并钉住 method 必须落在 MCP 对外认的那组起法里。
+ * @param {Record<string, unknown>} args
+ * @returns {{ method?: string, upper?: unknown, lower?: unknown }}
+ */
+function pickCastArgs(args) {
+  /** @type {Record<string, unknown>} */
+  const picked = {};
+  for (const key of CAST_ARG_KEYS) {
+    if (key !== 'question' && key !== 'topic' && args[key] !== undefined) picked[key] = args[key];
+  }
+  const method = typeof args.method === 'string' && args.method !== '' ? args.method : 'time';
+  if (!MCP_CAST_METHODS.includes(method)) {
+    throw new ToolError(
+      'INVALID_ARGUMENTS',
+      `未知的起法：${method}`,
+      `method 只能是 ${MCP_CAST_METHODS.join('、')}。`,
+    );
+  }
+  picked.method = method;
+  return picked;
+}
+
 /**
  * @param {string} name
  * @param {Record<string, unknown>} args
@@ -303,16 +346,15 @@ function callTool(name, args, now) {
     /** @type {ReturnType<typeof buildReading>} */
     let reading;
     try {
-      // 取数与校验只有这一份，页面那条路调的是同一个函数。之前两边各写一份，
-      // 于是上限值与提示语各自漂移，而「MCP 那份忘了收六次掷钱长度」那类漏项
-      // 只要漏一次就是一次线上故障。
-      //
-      // 摇卦由谁掷是调用方各自的决定，不做成共用函数的兜底：MCP 背后没有人替用户
-      // 掷，所以它自己掷六次；页面上用户看得见点数并能自己重来，少一次就该报错。
-      const params = args.method === 'coins' && args.sums === undefined
-        ? { ...args, sums: tossCoinSums() }
-        : args;
-      reading = buildReading(castFromParams(params, now), { question, now, topic });
+      // 先按 schema 收一遍参数，只留下 `divination_cast` 真正声明的那几个。
+      // 直接把 args 整个递进 castFromParams 的话，Agent 传进来的 schema 之外的键
+      // 也会被当真：`sums` 会让本该自己掷的摇卦改用 Agent 指定的点数（页面那条路
+      // 要这个，Agent 背后没有人替用户掷，不要），`method: 'hexagram'` 更是页面
+      // 卦库专用的起法，不该从对话里走。
+      const params = pickCastArgs(args);
+      // 摇卦一律由本工具自己掷：Agent 只说「掷铜钱」，点数是随机的，不该由它指定。
+      const withCoins = params.method === 'coins' ? { ...params, sums: tossCoinSums() } : params;
+      reading = buildReading(castFromParams(withCoins, now), { question, now, topic });
     } catch (error) {
       if (error instanceof CastParamError) {
         throw new ToolError('INVALID_ARGUMENTS', error.message, error.recovery);
 
@@ -317,16 +317,27 @@ async function handle(request, response, clientEntry, store, cache) {
     }
     const reading = cache.get(id);
     if (!reading) {
-      sendJson(response, 409, { error: 'unknown_cast' });
-      return;
-    }
-    // 同一 id 存两次会得到两条同 id 的记录，而 remove() 按 id 过滤，删一条连带删另一条。
-    if (await store.get(id)) {
-      sendJson(response, 409, { error: 'already_saved' });
+      // 带上人话：服务重启后这一卦已经不在缓存里，而页面只把错误写进隐藏的
+      // live region，用户看到的是「点了没反应」。这句话是页面上唯一能显示出来的线索。
+      sendJson(response, 409, {
+        error: 'unknown_cast',
+        message: '服务已重启，这一卦无法再存，请重新起一卦。',
+      });
       return;
     }
+    // 「这一 id 已经存过」由 store.save 在它自己的排队任务里判断并落盘，两步合一。
+    // 拆成先 store.get 再 store.save 的话，并发的几次请求会各自把 get 排完（都得到
+    // null）再各自 save，同一个 id 就落盘好几条——而 remove() 按 id 过滤，
+    // 删一条连带删一串。save 撞车时返回 null，这里据此回 409。
     const note = clampText(body.note, MAX_NOTE);
     const saved = await store.save(reading, note);
+    if (saved === null) {
+      sendJson(response, 409, {
+        error: 'already_saved',
+        message: '这一卦已经在卦历里了。',
+      });
+      return;
+    }
     sendJson(response, 201, { entry: saved });
     return;
   }
 
@@ -60,12 +60,20 @@ export class ReadingStore {
   }
 
   /**
+   * 存一条卦。id 撞上已有的那条时返回 `null`——检查与写入在同一个排队任务里，
+   * 不能拆成先 `get` 再 `save` 两个任务：那样并发的几次请求会各自把 `get` 排完
+   * （都得到 null），再各自 `save`，于是同一个 id 落盘四条，而 `remove()` 按 id
+   * 过滤，删一条连带删三条。实测同一 id 并发 POST 五次会得到
+   * `201,201,201,201,409` 与四条同 id 记录；合进一个任务后是 `201,409,409,409,409`。
+   *
    * @param {import('./divination.mjs').Reading} reading
    * @param {string} note
+   * @returns {Promise<object|null>} null 表示这条 id 已经存过了
    */
   async save(reading, note) {
     return this.enqueue(async () => {
       const entries = await this.readAll();
+      if (entries.some((entry) => entry.id === reading.id)) return null;
       const entry = {
         ...reading,
         note: clampText(note, MAX_NOTE),
Original file line number	Diff line number	Diff line change
`@@ -1872,5 +1872,11 @@ function buildId(hexagram, positions, now) {`
`1872`	`1872`	`for (let index = 0; index < seed.length; index += 1) {`
`1873`	`1873`	`hash = (hash * 31 + seed.charCodeAt(index)) >>> 0;`
`1874`	`1874`	`}`
`1875`		- return `${stamp}-${hash.toString(36).slice(0, 6)}`;
	`1875`	`+ // padStart 而不是 slice：32 位的 hash 转 36 进制有 6 位也有 7 位（36^6 < 2^32 < 36^7），`
	`1876`	+ // `slice(0, 6)` 会把 7 位的那种砍掉最低位——而种子末尾那个递增计数改的正是最低位，
	`1877`	`+ // 于是「同一秒、同一个卦」拿回同一个 id，实测 3000 组里撞 1228 组。`
	`1878`	`+ // 新的存卦约定按 id 取卦，撞了之后后一卦会把前一卦盖掉：在甲那张卡上点存入，`
	`1879`	`+ // 落盘的却是乙那张的问题。补零而不截断是单射的——36 进制里 7 位数的首位不会是 0，`
	`1880`	`+ // 所以补出来的 '0xxxxxx' 与真正的 7 位数不可能相同。长度仍落在 [A-Za-z0-9-]{1,80} 内。`
	`1881`	+ return `${stamp}-${hash.toString(36).padStart(7, '0')}`;
`1876`	`1882`	`}`