# 妙算子（xingming-jiedu）— 完整 Agent 上下文

> 本文件面向大模型和 AI Agent 编写，给出全部工具的输入字段、输出结构、推荐任务路径与边界说明。如需精简版请看 `/llms.txt`。

## 1. 站点说明

- 中文名：妙算子（姓名笔画解读）
- 域名：https://name.mihaozhuan.com/
- 语言：zh-CN
- 运营阶段：内测期（2026 年起）
- 主营业务：基于康熙字典笔画的姓名学 H5 测算
- 数据归属：所有测算记录落 SQLite 库（按 IP hash + 当日时间限流 5 次/天）

## 2. 入口

| 入口 | 路径 | 说明 |
|---|---|---|
| 首页 | `/` | H5 SPA 入口 |
| 单身女测算 | `/single` | 6格 + 场景化解读 |
| 非单身女测算 | `/in-relationship` | 含未婚 / 已婚 / 离异 / 丧偶 4 状态 |
| 解读结果 | `/result/:id` | 单次报告 |
| API 根 | `/api/` | REST API |
| 健康检查 | `GET /api/health` | 返回 `{ status: "ok" }` |
| 测算接口 | `POST /api/calculate` | 主接口 |
| 查解读 | `GET /api/result/:id` | 拉单次 JSON |

## 3. 工具 Schema

### 3.1 run_name_test（POST /api/calculate）

**用途**：根据用户姓名 + 场景 + 伴侣姓，输出完整 6格 + 81 数理 + 特殊格局 + 场景化解读。

**Request**:
```json
{
  "xing": "王",                   // 必填，姓，1-2 字
  "xing2": "葛",                  // 可选，复姓第二字（暂未启用，统一靠 xing 整串识别）
  "ming1": "芳",                  // 必填，名首字，1-2 字
  "ming2": "婷",                  // 可选，名次字；不传=单名
  "scene": "female_single",      // 必填，场景枚举
  "age": 25,                       // 可填，年龄（18-99）
  "partnerSurname": "李",          // 可选，男友姓（未婚预测用）
  "fuXing": "李",                  // 可选，夫姓（已婚 / 离异 / 丧偶 用）
  "partnerStatus": "married"       // 可选，married/divorced/widowed
}
```

**Scene 枚举**：
- `female_single`：单身女
- `female_in_rel_unmarried`：有男友（未婚）— 会包含【预测】
- `female_in_rel_married`：已婚 / 离异 / 丧偶 — 需 `fuXing` + `partnerStatus`
- `male`：男（暂未上线）
- `student`：学生（暂未上线）

**Response 200**:
```json
{
  "id": "uuid-v4",
  "result": {
    "grids":    { "tian": 5, "ren": 18, "di": 11, "wai": 8, "zong": 16, "xiu": 18 },
    "wuxing": {
      "tian": { "el": "土", "yin": false },
      "ren":  { "el": "金", "yin": true },
      "di":   { "el": "木", "yin": false },
      "wai":  { "el": "金", "yin": false },
      "zong": { "el": "土", "yin": true },
      "xiu":  { "el": "金", "yin": true }
    },
    "patterns": [
      { "key": "天地生", "txt": "天地相生，配置温和..." }
    ],
    "shuli": [
      { "grid": "ren", "num": 18, "jixiong": "吉", "txt": "...", "ext": "..." }
    ],
    "sections": [
      { "title": "基础解读", "content": "...", "isPredictive": false }
    ],
    "warnings": []
  }
}
```

**Response 400**（限流）：
```json
{ "error": "今日解读次数已用完（内测期上限 5 次）" }
```

**Response 500**（康熙缺字）：
```json
{ "error": "姓氏「X」不在康熙字典（姓位）" }
```

### 3.2 get_name_test（GET /api/result/:id）

**用途**：按解读 id 拉取完整 JSON（与 /calculate 返回的 result 结构一致）。

**Request**：URL 参数 `id`（UUID v4）

**Response 200**：
```json
{
  "id": "uuid",
  "input": { "xing": "王", "ming1": "芳", "ming2": "婷", "scene": "female_single" },
  "result": { "...": "同 /calculate 返回结构" },
  "created_at": 1780536659793
}
```

### 3.3 health_check（GET /api/health）

**Response 200**：
```json
{ "status": "ok" }
```

## 4. 算法核心

### 4.1 6格 公式（lookup.ts，4 种姓×名组合 × 是否已婚 = 8 条分支）

| 姓 | 名 | 已婚 | 天 | 人 | 地 | 外 | 总 | 修 |
|---|---|---|---|---|---|---|---|---|
| 单 | 单 | 否 | 姓+1 | 姓+名1 | 名1+1 | 1+1 | 姓+名1 | 姓+名1 |
| 单 | 单 | 是 | 夫+姓 | 姓+名1 | 名1+1 | 夫+1 | 夫+姓+名1 | 姓+名1 |
| 单 | 双 | 否 | 姓+1 | 姓+名1 | 名1+名2 | 1+名2 | 姓+名1+名2 | 姓+名2 |
| 单 | 双 | 是 | 夫+姓 | 姓+名1 | 名1+名2 | 夫+名2 | 夫+姓+名1+名2 | 姓+名2 |
| 复 | 单 | 否 | 姓1+姓2 | 姓2+名1 | 名1+1 | 姓1+1 | 姓1+姓2+名1 | 姓2+名1 |
| 复 | 单 | 是 | 夫+姓1+姓2 | 姓2+名1 | 名1+1 | 夫+姓1+1 | 夫+姓1+姓2+名1 | 姓2+名1 |
| 复 | 双 | 否 | 姓1+姓2 | 姓2+名1 | 名1+名2 | 姓1+名2 | 姓1+姓2+名1+名2 | 姓2+名2 |
| 复 | 双 | 是 | 夫+姓1+姓2 | 姓2+名1 | 名1+名2 | 夫+姓1+名2 | 夫+姓1+姓2+名1+名2 | 姓2+名2 |

**复姓上下文笔画**（compound_parts 字段）：
- 诸葛：诸=15（单姓=16，复姓=15），葛=15

### 4.2 五行（mapping.ts，按末位判定）

| 末位 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 0 |
|---|---|---|---|---|---|---|---|---|---|---|
| 五行 | 木 | 木 | 火 | 火 | 土 | 土 | 金 | 金 | 水 | 水 |
| 阴阳 | 阳 | 阴 | 阳 | 阴 | 阳 | 阴 | 阳 | 阴 | 阳 | 阴 |

### 4.3 16 类特殊格局（patterns/checker.ts）

连地克 / 通天克 / 天地克 / 天地生 / 连地生 / 通天生 / 木扎土 / 福寿土被病木克 / 阴阳水 / 阴阳火 / 阴阳木 / 阴阳金 / 阴阳土 / 水火急变 / 全阴局 / 三阴局 / 全阴木局

### 4.4 81 数理（shuli_81 表）

- 1-81 每条一条解读，含 `jixiong`（吉/半吉/凶/男吉女凶）
- 敏感词过滤（interpreter/sensitive.ts，22 类基词 + 70+ 软词）
- 人格/地格 优先用 v2 draft（温暖正向 + 留白多 + scene 分块）
- 其他格（天/外/总/修）走 DB shuli_81 fallback

## 5. 推荐任务路径

### 5.1 快速测算

```
POST /api/calculate
body: { xing, ming1, ming2?, scene, age }
→ 拿到 id
GET /api/result/:id
→ 拿到完整 result JSON
```

### 5.2 复姓用户

```
POST /api/calculate
body: { xing: "诸葛", ming1: "小", ming2: "明", scene, age }
（系统自动通过 compound_parts 判断复姓）
```

### 5.3 未婚男友姓预测

```
POST /api/calculate
body: { xing, ming1, ming2, scene: "female_in_rel_unmarried", age, partnerSurname: "李" }
→ result.sections 会切两段：实测（自身）+ 预测（按男友姓推算）
→ result.warnings 包含"本解读包含【预测】部分"
```

### 5.4 已婚细分

```
POST /api/calculate
body: { xing, ming1, ming2, scene: "female_in_rel_married", age, fuXing: "李", partnerStatus: "divorced" }
```

## 6. 边界与失败模式

| 错误 | 原因 | 建议处理 |
|---|---|---|
| 400 姓/名必填 | 缺 `xing` 或 `ming1` | 检查输入 |
| 400 scene 必填 | 缺 `scene` | 检查输入 |
| 400 今日解读次数已用完 | 匿名 IP 当日 5 次已满 | 提示用户次日再试 |
| 500 姓氏「X」不在康熙字典 | xing 字符无 kx_surname 笔画 | 用常见汉字 |
| 500 名「X」不在康熙字典 | ming1 字符无 kx_given 笔画 | 用常见汉字 |
| 500 已婚模式必须输入夫姓 | female_in_rel_married 缺 fuXing | 补 fuXing |

## 7. 隐私与限流

- 不收集用户账号（内测期免登录）
- 测算记录落 SQLite，关联 IP hash（sha256）+ 输入 JSON + 结果 JSON
- IP hash 不含明文 IP
- 匿名 IP 限流 5 次/天（北京时间，按 created_at 滚动 24h）
- 用户可见 Disclaimer：服务仅供文化娱乐参考

## 8. 工具版本

- 当前工具集于 2026-06 上线
- v2 解读内容（人格/地格）持续维护，每 2 周更新一次
- v1 DB shuli_81 覆盖 1-81 全量