# `roots-v1` 根气位置事实

`roots-v1` 检测年、月、日、时四个地支的藏干中，是否出现与日主同五行的天干。它只回答有没有根、根在哪里、属于本气/中气/余气哪一级，不判断根的强弱或有效性，也不修改 `ziping-strength-v1` 的旺衰结果。

## 输出结构

```ts
interface RootsContext {
  model: 'roots-v1';
  dayMaster: DayMaster;
  hasRoot: boolean;
  roots: Array<{
    pillar: 'year' | 'month' | 'day' | 'hour';
    branch: EarthlyBranchName;
    hiddenStem: HeavenlyStemName;
    order: 'main' | 'middle' | 'residual';
    source: string;
  }>;
}
```

- `hasRoot` 只表示是否至少检测到一处同五行藏干；
- `pillar` 和 `branch` 保留根的准确位置；
- `hiddenStem` 是实际构成根的藏干；
- `order` 表示该藏干在地支内部属于本气、中气或余气；
- `source` 指向四柱结构中的原始藏干路径。

月支根以 `pillar: 'month'` 输出，日坐根以 `pillar: 'day'` 输出。二者只是位置不同；`roots-v1` 不把月支根自动解释为得令，也不把日坐根解释为身强。

## 独立 API

```ts
import { detectPillarRoots, detectRoots } from 'bazi-core';

const roots = detectPillarRoots({
  year: '甲寅',
  month: '丙亥',
  day: '甲辰',
  hour: '戊未',
});
```

`detectRoots(chart)` 接受已经标准化的 `BaziChart`；`detectPillarRoots(pillars)` 接受四柱字符串。

## 明确不做的事

`roots-v1` 不会：

- 给根分配强弱、权重或百分比；
- 根据月令、旺相休囚或节气距离判断根是否有效；
- 根据刑冲合害判定根受损、被合或被冲掉；
- 判断从格、用神或生成吉凶断语。

`ziping-strength-v2` 已按本中余气和月令/日坐位置消费根气事实，并逐条记录采用条件和推导过程。完整规则见 [algorithm-v2.md](./algorithm-v2.md)。