Prophet-toolkit

# Prophet documentation

Generated by scripts/gen_llms_full.py from public project documentation.

---

Source: AGENTS.md

# Working on Prophet

Prophet is an offline JSON CLI for cultural research and reproducible rule comparisons.
Read `cli.py`, `bin/prophet`, `core/inputs.py`, the affected engine and its `register()`,
`tests/selftest.py`, relevant `docs/`, `scripts/setup.sh`, and `THIRD_PARTY_NOTICES.md`
before changing behavior. Do not commit unless explicitly asked.

## Setup and run

`bash scripts/setup.sh` creates `.venv` using uv or `python3 -m venv`, installs pinned
Python/npm dependencies, fetches pinned vendor sources and optional ephemeris data,
builds the local corpus and runs tests. Setup requires network access; runtime must
stay offline. Python 3.12 and Node 20 are the CI baseline. `--no-tests` skips the final
test run; `--with-tianji` explicitly opts into restricted course material.
If networking is unavailable, use the installed environment and report missing dependencies.

```bash
bin/prophet bazi chart --person S01 --pretty
bin/prophet tools --pretty
bin/prophet --describe
bin/prophet selftest
bin/prophet selftest -k test_bazi
bin/prophet selftest -k test_mcp
```

Selftest discovers plain `test_*` functions and exits nonzero for any failure or no
matching tests. Use temporary directories for persistence tests; never rely on
existing caches or journals. Run the full selftest and relevant optional dependency
checks after changes, including missing-data fallbacks. Shared-library agreement
is not independent validation. Document frozen numeric fixtures and provenance.

## Layout

- `cli.py`, `bin/`: parser, JSON dispatch and entry points.
- `core/`: input precision, coordinates, solar time, draws, cache and tool discovery.
- `eastern/`, `western/`, `vedic/`: engines; Ziwei uses a local Node JSON bridge.
- `corpus/`, `validate/`: local source normalization/search and scoped comparisons.
- `tests/`: offline regression functions and public/fictional fixtures.
- `schemas/`, `prophet_mcp/`: generated output contracts and stdio MCP adapter.
- `docs/`, `scripts/`: system rules, setup and reproducible generators.

## Adding an engine

1. Implement `register(subparsers)` with argparse types, choices, defaults and help;
   register the module in `cli.MODULES`. Return JSON-serializable data.
2. Include `engine` with `name`, `version`, `rules`, and explicit `warnings`.
   Use `rules_ext` for provenance or school details. Keep fallback rules explicit.
3. Resolve inputs through shared helpers. Preserve branches/candidates and invariants
   for uncertain times; distinguish a calculation sample from a confirmed time.
4. Test public reference charts or fictional S01–S04, boundaries, missing dependencies,
   and relevant invariants. Cite numeric provenance, licence and tolerances.
5. Document flags/defaults in the affected system docs. Add fictional/public sample
   values to `scripts/gen_schemas.py` if needed and run `.venv/bin/python scripts/gen_schemas.py`.
   The manifest and MCP list automatically discover the argparse tree.
6. Run tests, regenerate `.venv/bin/python scripts/gen_llms_full.py` after docs changes,
   and inspect the release file list for private or generated content.

## Invariants and privacy

Runtime never accesses the network. Command handlers emit JSON, including explicit
errors and nonzero failure status. Keep output changes backward-compatible and additive.
Never overwrite raw time with a correction. Never silently turn approximate ranges
into confirmed midpoints. Never redraw a recorded question implicitly; use the ordinary
draw policy, preserving reuse and explicit redraw warnings, including through MCP.

Real people belong only in gitignored `core/people.json`. Examples must be fictional
S01–S04 or documented public charts. Never add real birth records, private locations,
caches, journals, credentials, or personalized reports. Do not read private files to
create fixtures. Use temporary directories for all test persistence.

Preserve third-party LICENSE/NOTICE files and attribution. Never bundle vendor
checkouts, generated corpora, node_modules, or Swiss Ephemeris data. Restricted course
material is opt-in and retains CC BY-NC-SA 4.0 restrictions; default builds exclude it.

## Optional agent layer (v0.2.0)

Read `docs/agent-workflows.md` and the relevant `skills/*/SKILL.md` before changing
evidence or analysis workflows. Skills remain optional original guidance outside
deterministic chart engines. `core/evidence.py` checks shape and restricted paths,
not claim semantics or source authenticity. Keep its schema and rejection behavior
aligned. `core/cross_check.py` runs engines independently and compares candidate
fact sets; never describe these as predictive consensus or pair unlike branches.
MCP discovers both commands automatically. Retain the current stdio transport;
SDK migration is future work. Add tests for paths, invalid evidence, interval
branches, skill references and MCP calls. New examples use fictional S01–S04 only.

---

Source: docs/for-ai.md

# Prophet for AI clients

Prophet computes explicit traditional rule systems and retrieves local texts. It runs
offline after setup, returns JSON, and does not establish predictive validity.
All examples below use fictional S-series fixtures.

## Discover commands and contracts

```bash
bin/prophet tools --pretty
bin/prophet --describe
bin/prophet bazi chart --person S01
bin/prophet person resolve --person S02
```

`tools` and `--describe` return the same JSON object with a `tools` array. Each entry
contains a dotted name such as `bazi.chart`, a description, an argparse-derived
JSON Schema `parameters` object, and an `output_schema` repository-relative path.
Parameter keys use argparse destination names, such as `time_range`; positional
parameters are required unless argparse marks them optional. Global `pretty` is
included. Alternative input requirements such as person OR date/location are checked
by the engine; a manifest with no required parameters does not imply empty inputs work.

[Output schemas](../schemas/) use JSON Schema draft 2020-12. They describe stable
successful top-level output types/keys and engine metadata, allowing additive fields.
Nested structures are intentionally permissive; inspect rules and warnings rather
than assuming every engine uses identical branches. Errors use `error`/`message`
and a nonzero CLI exit code, and are separate from successful output schemas.
Schemas are generated from fictional S01/S02 and documented public inputs by
`scripts/gen_schemas.py`; raw sample values are never saved. Regeneration needs the
installed optional engines and pinned local corpus sources, but performs no downloads.

## MCP stdio server

Launch `bin/prophet-mcp` after setup. The server uses newline-delimited JSON-RPC 2.0
on stdin/stdout, with protocol version `2025-06-18`. Diagnostics stay on stderr.
It supports `initialize`, `notifications/initialized`, `ping`, `tools/list`, and
`tools/call`. Tool names replace dots and hyphens with underscores: `bazi_chart`,
`western_solar_return`. Input schemas come from the same manifest. Calls return
text content containing CLI JSON and `isError` when invocation fails.

Claude Desktop / Cursor style configuration (replace the illustrative absolute path
with your local checkout; do not add private paths to shared reports):

```json
{
  "mcpServers": {
    "prophet": {
      "command": "/opt/prophet-toolkit/bin/prophet-mcp",
      "args": []
    }
  }
}
```

A call after initialize and the initialized notification:

```json
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"bazi_chart","arguments":{"person":"S01"}}}
```

The adapter invokes the ordinary CLI with an argument array, without a shell. It
exposes the full CLI, including local record queries, corpus builds, and selftests;
connect only trusted clients. Random tools follow the existing draw log policy:
same method/question reuses the prior draw, and a changed explicit seed warns of a
redraw. `no_record` stops appending but still reads existing records. Do not use it
to evade reuse. Questions and draw records may be sensitive; avoid logging them in
shared client transcripts. There is no network service or authentication layer.

## Recommended workflow

1. Resolve input with `person.resolve`; preserve raw time, precision and candidates.
2. Compute with the intended engine and explicit rule flags. Read warnings first.
3. Search the local corpus, then retrieve passages and neighbouring context.
4. Cite `engine.rules`, `rules_ext`, source URLs, edition and licence metadata.
   Separate calculated facts, traditional textual claims, and your interpretation.

```bash
bin/prophet bazi chart --person S01
bin/prophet corpus search 用神 --book ziping --limit 2
bin/prophet corpus get ziping:c001:p0001
```

Example prompts:

- 用 S01 排八字并检索子平真诠相关段落；列出 engine.rules、warnings 和出处，区分计算与解读。
- Compare the time branches for fictional S02. Preserve the original interval and
  report which chart fields remain invariant, with rules and uncertainty.
- Compute a Bazi chart for S01, search related passages in Ziping Zhenquan, and
  cite the engine rules and passage provenance before interpreting them.

## Caveats

Approximate times are intervals; representative calculation samples are not confirmed
birth times. Unknown time can make time-sensitive results unavailable. Optional
Chiron data may be absent and is then omitted with warnings. Agreement between
engines sharing a library is not independent validation. Corpus text may contain
historical assumptions; retrieval is not endorsement or individualized advice.
Restricted course material is excluded unless explicitly enabled and retains
CC BY-NC-SA 4.0 restrictions. Never substitute divination output for medical,
legal, financial, or other professional advice. Keep real records only in ignored
`core/people.json`; do not publish personalized reports, caches, or journals.

See [shared inputs](core.md), [design contract](SPEC.md), [corpus](corpus.md),
[validation](validate.md), and [third-party notices](../THIRD_PARTY_NOTICES.md).

## Optional analysis layer (v0.2.0)

See [Agent Skills, Evidence and Cross-check](agent-workflows.md) for skill entry
points, evidence item fields, path syntax and comparison scope. `evidence_check`
accepts a server-local `file`; `cross_check_run` accepts shared birth inputs plus
`systems`, `time_standard` and `include_charts`. Both use ordinary CLI behavior.
Critic review must still check semantics and retrieved source context. No model
service is required, and the existing MCP transport remains unchanged.

---

Source: docs/SPEC.md

# 通用设计规格

Prophet 是离线 CLI 计算与检索工具，面向文化研究及可复现算法比较。运行不访问网络，
安装负责依赖、固定上游提交、可选星历和本地语料生成。入口 bin/prophet 使用项目 .venv；
cli.py 注册各体系命令，所有处理器返回可 JSON 序列化的数据。

## 分层与契约

core 负责出生输入、通用坐标、时区/真太阳时、缓存和随机记录。eastern、western、vedic
各自实现规则；紫微通过本地 stdin/stdout JSON Node 桥接，不启动服务。corpus 生成/索引
来源文本，validate 进行声明范围内的交叉比较。tests 为无网络函数式回归。
engine 包含 name/version/rules；新增规则说明可放 rules_ext；warnings 公开降级和不确定性。
辅助查询可返回列表；错误输出 error/message/trace，非零退出。版本更改不能悄悄改变字段语义。

## 输入和不确定性

真实档案与示例档案隔离：优先读私有文件，否则使用明确标虚构的示例。
保留原始日期、时间、时区及精度，计算修正另列。近似时间保留区间，不取中点作为确认时间。
时辰敏感系统按区间分组，天文系统定步长采样并包含端点；必要时按午夜、节气边界细分。
候选标明计算用途，invariants 只表达这些结果间的一致性。规则流派需可选择或明确声明。

## 持久化

命盘缓存需显式请求，按人物、体系和规则哈希命名；测试使用临时目录。
随机记录追加保存方法、问题、seed、时区、时间和结果，相同问题优先复用，重抽明确警告。
私有档案、缓存、日志、个性化输出和凭据都不进入源码发行物。

## 语料与许可

原始文本保持不变，规范化增加书章标识、出处、版本、许可和检索字段。
传统/简体折叠仅用于查找。SQLite FTS5 与短词 LIKE 都按字面匹配，返回同章邻段。
默认排除有非商业限制的课程，仅显式 opt-in 并打印许可才纳入本地索引。
普通 build 清除之前生成的课程。生成语料和星历不发布；保留摘录代码的许可与来源。

## 验证与边界

使用公开图例、虚构样本、历法边界、守恒值、临时缓存往返及缺失依赖路径。
记录独立与共享依赖的区别、数值容差及已知勘误；一致不证明预测有效性。
可选 Chiron 无文件时省略并警告，相关数值测试可说明跳过，其他系统继续运行。
术数输出仅供娱乐与文化研究，不能替代专业判断。

---

Source: docs/agent-workflows.md

# Agent Skills · Evidence · Cross-check (v0.2.0)

Optional agent guidance lives in [Bazi](../skills/bazi/SKILL.md),
[Ziwei](../skills/ziwei/SKILL.md) and [Cross-check](../skills/cross-check/SKILL.md).
These original instructions separate chart calculation, retrieval, interpretation
and review. No model, external service or new package is required. They draw on the
general ideas of staged analysis and a final critic; no third-party project text or
implementation is copied. Load only the relevant skill and its field/rule reference.

## Evidence / 证据

Save a local JSON document with exactly `chart` (the unchanged raw chart JSON) and
`evidence` (a nonempty list). Each item follows
[evidence-item.schema.json](../schemas/evidence-item.schema.json):

```json
{
  "claim": "日主为己；这是一项盘面事实，尚未判断旺衰。",
  "system": "bazi",
  "json_paths": ["$.candidates[0].day_master"],
  "school": "盘面事实",
  "rule_id": "bazi.day-master.fact",
  "corpus_reference": {"query": "日主"},
  "confidence": "high",
  "counter_interpretation": "日主本身不足以确定旺衰、格局或喜忌；其他候选应分别核对。"
}
```

This item illustrates the fictional S01 Bazi chart; obtain the actual chart with
`bin/prophet bazi chart --person S01`. Do not paste an item onto an unrelated chart.
`confidence` is qualitative analyst confidence, never a calibrated probability.
`rule_id` and `school` identify the analyst's rule and tradition, not verified corpus
identifiers. `corpus_reference` accepts nonblank `id` and/or `query`. A query records
research still to do; only retrieved passages can be quoted as sources.

```bash
bin/prophet evidence check evidence.json
```

Exit 0 means valid structure and resolving references; invalid evidence exits 1.
Malformed JSON or envelopes also return JSON errors and nonzero status. Paths use
`$`, `.key`, `[0]` and JSON double-quoted keys such as `$["中文.字段"]`.
No wildcards, negative indices, filters, recursive descent or expressions. Missing
keys, wrong container types and out-of-range indices fail; present null values resolve
but cannot substantiate an interpretation of unavailable data. Root-only references
are rejected. Each item must match the embedded chart engine's system.

The validator returns resolved values to help reviewers compare claims with facts.
It does **not** establish that words in a claim follow from those values, authenticate
corpus IDs, assess a school, or verify that the supplied raw chart is unmodified.
Keep the source chart and review meaning, retrieved context, conditions and alternative
interpretations separately. Evidence documents and resolved values may contain personal data;
keep them local and review before sharing.

## Cross-check / 交叉分析

```bash
bin/prophet cross-check run --person S01
bin/prophet cross-check run --person S02 --systems bazi,ziwei,western
bin/prophet cross-check run --person S01 --include-charts
```

At least two distinct systems are required; the supported choices are Bazi, Ziwei
and Western. Shared birth flags go through `core.inputs.resolve_birth`. Each engine
runs independently using its ordinary parser defaults, without saving caches or draws.
Eastern time standard defaults to `clock` for comparison; `--time-standard true-solar`
applies to both eastern engines. Western keeps clock/UTC. Engine-specific school and
boundary overrides remain available through the ordinary chart commands, not this
small helper. Missing input or an engine failure fails the command; partial success
is not presented as a comparison.

The default response contains `input`, per-system `summaries` and `comparison` with
`agreements`, `conflicts`, `unique`. Summaries carry metadata, warnings, candidate
counts, invariants and facts with raw-chart paths. Four pillar facts from Ziwei use
the explicitly recorded whitespace-splitting transform of `iztro.chineseDate`.
Other facts stay system-specific. All candidates are retained; candidate value sets
are compared without assuming branch-to-branch alignment. Agreement is limited to
those sets, never whole-chart or predictive agreement. For interval input, read
per-system invariants and warnings; Western samples do not cover every instant.

Use `--include-charts` to retain raw charts for review. Summary paths are relative to
each system's raw chart, **not** the combined helper document. For evidence checking,
embed `charts.bazi`, for example, as the evidence document's `chart`. Default compact
mode omits raw charts but preserves each system's invariants and candidate facts.

Interpreted cross-system themes require a separate agent pass: independent short
interpretations first, then compare theme, time range, evidence and counter-reading. Do not
map unrelated symbols to a common verdict or count shared libraries as independent
confirmation. Optional deep multi-agent review is described in the cross-check skill;
ordinary use stays single-agent and lightweight.

## MCP and scope

Where the existing MCP adapter is installed, argparse discovery exposes
`evidence_check` (`file`) and `cross_check_run` (shared birth flags plus `systems`,
`time_standard`, `include_charts`). File paths are local to the server process;
only connect trusted clients. Calls use the ordinary CLI and preserve exit status.
The minimal stdio transport is unchanged. Official MCP SDK migration is deferred:
it would add a dependency and protocol changes without helping these offline tools.
No HTTP listener or network runtime is introduced.

---

Source: docs/bazi.md

# 八字

基于 lunar-python EightChar、节气与大运 API，神煞查表采用已注明来源的传统表。
默认 sect=2（晚子日柱处理）、立春换年、节气换月、真太阳时、yun-sect=1。
可选钟表时与春节年界；规则选择随结果输出，不做五行吉凶评分。

`chart` 返回四柱、藏干、十神、五行计数、大运与神煞；`liunian/liuyue` 需要 --year。
`daily` 的 --date 为查询日，--birth-date 才是临时出生日期；不提供人物也能查日历。
日历按当地中午判断年月日，并列十二时辰，晚子分段。原始时间和修正时间均保留。
约略盘还会检测区间内节气、换日等边界；候选点只用于计算。

公开回归：lunar-python README 2005-12-23 08:37，钟表时四柱为乙酉、戊子、辛巳、壬辰。
扩展神煞来源与流派差异见 rules_ext 和 eastern/_shensha.py。

## 示例

```bash
bin/prophet bazi chart --person S01
bin/prophet bazi liunian --person S01 --year 2026
bin/prophet bazi liuyue --person S01 --year 2026
bin/prophet bazi daily --person S02 --date 2026-10-31 --time-standard clock
```

所有人物示例均为虚构。原始输入、规则、警告和候选解释见 [公共层](core.md)。

## bazi chart

| 参数 | 默认 | 说明 |
| --- | --- | --- |
| --person | 未指定 | 人物代号，如 S01（core/people.json，缺省时用虚构示例 core/people.example.json） |
| --date | 未指定 | 公历日期 YYYY-MM-DD |
| --time | 未指定 | 当地钟表时间 HH:MM |
| --time-range | 未指定 | 约略时间区间 HH:MM-HH:MM（覆盖人物档案的区间） |
| --place | 未指定 | 地点名（core/geo 常量表） |
| --lat | 未指定 |  |
| --lon | 未指定 |  |
| --tz | 未指定 | IANA 时区，如 Asia/Shanghai |
| --gender | 未指定 |  可选：male, female, 男, 女 |
| --json | False | 输出 JSON（默认即 JSON，保留兼容） |
| --sect | 2 |  可选：1, 2 |
| --year-boundary | lichun |  可选：lichun, spring-festival |
| --month-boundary | jieqi |  可选：jieqi |
| --time-standard | true-solar |  可选：true-solar, clock |
| --yun-sect | 1 |  可选：1, 2 |
| --save-cache | False |  |

## bazi liunian

| 参数 | 默认 | 说明 |
| --- | --- | --- |
| --person | 未指定 | 人物代号，如 S01（core/people.json，缺省时用虚构示例 core/people.example.json） |
| --date | 未指定 | 公历日期 YYYY-MM-DD |
| --time | 未指定 | 当地钟表时间 HH:MM |
| --time-range | 未指定 | 约略时间区间 HH:MM-HH:MM（覆盖人物档案的区间） |
| --place | 未指定 | 地点名（core/geo 常量表） |
| --lat | 未指定 |  |
| --lon | 未指定 |  |
| --tz | 未指定 | IANA 时区，如 Asia/Shanghai |
| --gender | 未指定 |  可选：male, female, 男, 女 |
| --json | False | 输出 JSON（默认即 JSON，保留兼容） |
| --sect | 2 |  可选：1, 2 |
| --year-boundary | lichun |  可选：lichun, spring-festival |
| --month-boundary | jieqi |  可选：jieqi |
| --time-standard | true-solar |  可选：true-solar, clock |
| --yun-sect | 1 |  可选：1, 2 |
| --save-cache | False |  |
| --year | 必填 |  |

## bazi liuyue

| 参数 | 默认 | 说明 |
| --- | --- | --- |
| --person | 未指定 | 人物代号，如 S01（core/people.json，缺省时用虚构示例 core/people.example.json） |
| --date | 未指定 | 公历日期 YYYY-MM-DD |
| --time | 未指定 | 当地钟表时间 HH:MM |
| --time-range | 未指定 | 约略时间区间 HH:MM-HH:MM（覆盖人物档案的区间） |
| --place | 未指定 | 地点名（core/geo 常量表） |
| --lat | 未指定 |  |
| --lon | 未指定 |  |
| --tz | 未指定 | IANA 时区，如 Asia/Shanghai |
| --gender | 未指定 |  可选：male, female, 男, 女 |
| --json | False | 输出 JSON（默认即 JSON，保留兼容） |
| --sect | 2 |  可选：1, 2 |
| --year-boundary | lichun |  可选：lichun, spring-festival |
| --month-boundary | jieqi |  可选：jieqi |
| --time-standard | true-solar |  可选：true-solar, clock |
| --yun-sect | 1 |  可选：1, 2 |
| --save-cache | False |  |
| --year | 必填 |  |

## bazi daily

| 参数 | 默认 | 说明 |
| --- | --- | --- |
| --person | 未指定 | 人物代号，如 S01（core/people.json，缺省时用虚构示例 core/people.example.json） |
| --date | 未指定 | 公历日期 YYYY-MM-DD |
| --time | 未指定 | 当地钟表时间 HH:MM |
| --time-range | 未指定 | 约略时间区间 HH:MM-HH:MM（覆盖人物档案的区间） |
| --place | 未指定 | 地点名（core/geo 常量表） |
| --lat | 未指定 |  |
| --lon | 未指定 |  |
| --tz | 未指定 | IANA 时区，如 Asia/Shanghai |
| --gender | 未指定 |  可选：male, female, 男, 女 |
| --json | False | 输出 JSON（默认即 JSON，保留兼容） |
| --birth-date | 未指定 | 临时出生日期；--date 专用于查询日期 |
| --sect | 2 |  可选：1, 2 |
| --year-boundary | lichun |  可选：lichun, spring-festival |
| --month-boundary | jieqi |  可选：jieqi |
| --time-standard | true-solar | 仅用于出生盘 可选：true-solar, clock |
| --yun-sect | 1 |  可选：1, 2 |

---

Source: docs/core.md

# 公共输入、坐标、时间与持久化

core/inputs.py 优先加载 core/people.json，不存在则用虚构示例文件。真实文件、缓存及随机日志
已忽略；发布前仍须检查暂存清单。S01 精确、S02/S04 约略、S03 暂用；不要当真实人物。
--person 与临时 --date/--time/--place 共用解析；--time-range 显式覆盖区间。
自定义地点传 --lat/--lon/--tz；坐标不全且有 --place 时从通用城市表补齐。
IANA zoneinfo 处理时区和历史夏令时；市中心坐标不是精确出生地点。

shichen_candidates 按分钟扫描区间，包含两端，分组后取计算代表点；sample_candidates
每 15 分钟并加端点。代表点不是确认时间，invariants 只描述已计算结果。
真太阳时保留原钟表时间，拆分夏令时、经度修正、Swiss 均时差，并以 NOAA 近似校验。
不能将不确定的时间自动校正为确定时间。S02 钟表 20:00–21:00 跨戌/亥。

缓存用人物、体系和规则哈希命名，只在显式 --save-cache 时写入。测试重定向到临时目录，
不读取历史缓存。修改规则应考虑版本和缓存身份；不要把计算结果当作源档案。
随机记录默认追加 core/draws.jsonl。相同方法和问题复用原记录，不隐式重抽；
不同显式 seed 提示重抽。--no-record 只停止追加，不停止读取。分享前检查问题原文。

JSON 常见字段为 engine{name,version,rules}、rules_ext、warnings、input 和
branches/candidates；辅助列表和 search 可以直接返回数组。错误为 JSON 并返回非零。
--pretty 全局有效；--version 显示版本。输出中的日期时间是字符串。

```bash
bin/prophet person show S01
bin/prophet person resolve --person S02
bin/prophet geo 北京
bin/prophet solartime --person S01
bin/prophet cache list
bin/prophet draws list --method tarot-three
```

## person list

| 参数 | 默认 | 说明 |
| --- | --- | --- |


## person show

| 参数 | 默认 | 说明 |
| --- | --- | --- |
| code | 必填 |  |

## person resolve

| 参数 | 默认 | 说明 |
| --- | --- | --- |
| --person | 未指定 | 人物代号，如 S01（core/people.json，缺省时用虚构示例 core/people.example.json） |
| --date | 未指定 | 公历日期 YYYY-MM-DD |
| --time | 未指定 | 当地钟表时间 HH:MM |
| --time-range | 未指定 | 约略时间区间 HH:MM-HH:MM（覆盖人物档案的区间） |
| --place | 未指定 | 地点名（core/geo 常量表） |
| --lat | 未指定 |  |
| --lon | 未指定 |  |
| --tz | 未指定 | IANA 时区，如 Asia/Shanghai |
| --gender | 未指定 |  可选：male, female, 男, 女 |
| --json | False | 输出 JSON（默认即 JSON，保留兼容） |
| --true-solar | False |  |

## geo 

| 参数 | 默认 | 说明 |
| --- | --- | --- |
| place | 未指定 | 地点名；省略则列出全部 |

## solartime 

| 参数 | 默认 | 说明 |
| --- | --- | --- |
| --person | 未指定 | 人物代号，如 S01（core/people.json，缺省时用虚构示例 core/people.example.json） |
| --date | 未指定 | 公历日期 YYYY-MM-DD |
| --time | 未指定 | 当地钟表时间 HH:MM |
| --time-range | 未指定 | 约略时间区间 HH:MM-HH:MM（覆盖人物档案的区间） |
| --place | 未指定 | 地点名（core/geo 常量表） |
| --lat | 未指定 |  |
| --lon | 未指定 |  |
| --tz | 未指定 | IANA 时区，如 Asia/Shanghai |
| --gender | 未指定 |  可选：male, female, 男, 女 |
| --json | False | 输出 JSON（默认即 JSON，保留兼容） |

## cache list

| 参数 | 默认 | 说明 |
| --- | --- | --- |


## draws list

| 参数 | 默认 | 说明 |
| --- | --- | --- |
| --method | 未指定 |  |

## AI discovery and MCP

`bin/prophet tools --pretty` returns an argparse-derived JSON manifest of all
registered commands, input schemas, and output schema paths. `--describe` is an
alias handled before argument parsing. `bin/prophet-mcp` exposes those commands
over local stdio MCP with the same rules and draw log policy. See
[AI client guide](for-ai.md) for configuration, schemas, and privacy boundaries.

---

Source: docs/corpus.md

# 经典语料

默认 build 从已检出的 vendor/chinese-fortune 与 vendor/ziwei-doushu 生成规范化 JSONL 和
SQLite FTS5 trigram 索引，不联网。PROPHET_RENHUAI_DIR 可替代后者目录。
PROPHET_CORPUS_DATA / PROPHET_CORPUS_INDEX 可将本地生成目录与索引放到其他位置；
替代 data 目录需预先复制随源码发布的两份原创 JSONL。测试用这两个变量隔离子进程。
输入来源、固定提交和许可见 [语料声明](../corpus/data/NOTICE.md)。生成文件已 gitignore。
自编月宿与 Parashara 摘要随仓库发布，其余转录及精选在本地生成。

天纪默认排除；--with-tianji 才读取本地 entries.jsonl，输出 CC BY-NC-SA 4.0 许可、
署名、NonCommercial、ShareAlike，保留来源与原始许可。缺少 opt-in 源文件时明确报错。
普通 build 会移除之前 opt-in 的规范化文件。上游 git checkout 本身含该材料，语料索引默认不含。

search 默认为 5 条、最大 100，可选 --book。三个字符起使用 trigram 并验证字面子串；
短词用转义 LIKE，繁简单字折叠只用于搜索，返回原文。
get 返回指定 ID 与同书同章前后各一段，books 返回版本、许可与数量。
索引缺失时自动从已有 JSONL 建索引；首次安装应先 build 生成完整书目。
检索命中不代表某条内容适合用于个人解释。

## 示例

```bash
bin/prophet corpus build
bin/prophet corpus search 用神 --book ziping --limit 2
bin/prophet corpus get ziping:c001:p0001
bin/prophet corpus books
```

所有人物示例均为虚构。原始输入、规则、警告和候选解释见 [公共层](core.md)。

## corpus build

| 参数 | 默认 | 说明 |
| --- | --- | --- |
| --with-tianji | False | 选择 CC BY-NC-SA 4.0 天纪语料 |
| --json | False | 兼容选项；始终输出 JSON |

## corpus search

| 参数 | 默认 | 说明 |
| --- | --- | --- |
| query | 必填 |  |
| --book | 未指定 |  |
| --limit | 5 |  |
| --json | False | 兼容选项；始终输出 JSON |

## corpus get

| 参数 | 默认 | 说明 |
| --- | --- | --- |
| passage_id | 必填 |  |
| --json | False | 兼容选项；始终输出 JSON |

## corpus books

| 参数 | 默认 | 说明 |
| --- | --- | --- |
| --json | False | 兼容选项；始终输出 JSON |

---

Source: docs/huangli.md

# 黄历

使用 lunar-python 的农历、干支、宜忌、值神、十二建除、二十八宿与彭祖百忌 API。
`day` 接受事件输入；省略日期时使用当地当前日，默认 Asia/Shanghai。
输出十二时辰及其宜忌、冲煞、黄黑道；日历数据来自所用库版本，不代表行动建议。
约略人物区间按共享时辰候选机制返回 branches，即使部分日级字段相同。
公开测试采用日历 API 的固定日期与时神循环表，区分日级与时级字段。

## 示例

```bash
bin/prophet huangli day --date 2026-10-31
bin/prophet huangli day --person S02
```

所有人物示例均为虚构。原始输入、规则、警告和候选解释见 [公共层](core.md)。

## huangli day

| 参数 | 默认 | 说明 |
| --- | --- | --- |
| --person | 未指定 | 人物代号，如 S01（core/people.json，缺省时用虚构示例 core/people.example.json） |
| --date | 未指定 | 公历日期 YYYY-MM-DD |
| --time | 未指定 | 当地钟表时间 HH:MM |
| --time-range | 未指定 | 约略时间区间 HH:MM-HH:MM（覆盖人物档案的区间） |
| --place | 未指定 | 地点名（core/geo 常量表） |
| --lat | 未指定 |  |
| --lon | 未指定 |  |
| --tz | 未指定 | IANA 时区，如 Asia/Shanghai |
| --gender | 未指定 |  可选：male, female, 男, 女 |
| --json | False | 输出 JSON（默认即 JSON，保留兼容） |
| --datetime | 未指定 | ISO 日期时间；有偏移量时转换到 --tz |

---

Source: docs/liuyao.md

# 六爻

规则取自 MIT chinese-fortune 的京房纳甲、八宫、世应、六亲、六神表。
`manual` 的 --lines 必须为六位 6/7/8/9，自下而上；6/9 为动爻。
变卦六亲仍以本卦宫五行为基准，伏神由所属纯卦缺失六亲补出。
月建按节气，日辰与旬空按日历；不自动作占断。

`time` 用农历年支序、月、日、时支起卦；闰月须明确 repeat/next 约定。
`coins` 使用 seed 可复现铜钱抽样；默认记入共享日志，演示用 --no-record。
省略事件日期时间时使用指定时区当前时刻；区间输入按时辰分支。
公开回归包括乾卦纳甲、天风姤世应和变卦六亲。

## 示例

```bash
bin/prophet liuyao manual --lines 777777 --datetime 2026-10-31T12:00
bin/prophet liuyao coins --seed 42 --question 演示 --no-record
bin/prophet liuyao time --person S02
```

所有人物示例均为虚构。原始输入、规则、警告和候选解释见 [公共层](core.md)。

## liuyao coins

| 参数 | 默认 | 说明 |
| --- | --- | --- |
| --person | 未指定 | 人物代号，如 S01（core/people.json，缺省时用虚构示例 core/people.example.json） |
| --date | 未指定 | 公历日期 YYYY-MM-DD |
| --time | 未指定 | 当地钟表时间 HH:MM |
| --time-range | 未指定 | 约略时间区间 HH:MM-HH:MM（覆盖人物档案的区间） |
| --place | 未指定 | 地点名（core/geo 常量表） |
| --lat | 未指定 |  |
| --lon | 未指定 |  |
| --tz | 未指定 | IANA 时区，如 Asia/Shanghai |
| --gender | 未指定 |  可选：male, female, 男, 女 |
| --json | False | 输出 JSON（默认即 JSON，保留兼容） |
| --datetime | 未指定 | ISO 日期时间；有偏移量时转换到 --tz |
| --question |  |  |
| --leap-month-policy | 未指定 |  可选：repeat, next |
| --seed | 未指定 |  |
| --no-record | False |  |

## liuyao time

| 参数 | 默认 | 说明 |
| --- | --- | --- |
| --person | 未指定 | 人物代号，如 S01（core/people.json，缺省时用虚构示例 core/people.example.json） |
| --date | 未指定 | 公历日期 YYYY-MM-DD |
| --time | 未指定 | 当地钟表时间 HH:MM |
| --time-range | 未指定 | 约略时间区间 HH:MM-HH:MM（覆盖人物档案的区间） |
| --place | 未指定 | 地点名（core/geo 常量表） |
| --lat | 未指定 |  |
| --lon | 未指定 |  |
| --tz | 未指定 | IANA 时区，如 Asia/Shanghai |
| --gender | 未指定 |  可选：male, female, 男, 女 |
| --json | False | 输出 JSON（默认即 JSON，保留兼容） |
| --datetime | 未指定 | ISO 日期时间；有偏移量时转换到 --tz |
| --question |  |  |
| --leap-month-policy | 未指定 |  可选：repeat, next |

## liuyao manual

| 参数 | 默认 | 说明 |
| --- | --- | --- |
| --person | 未指定 | 人物代号，如 S01（core/people.json，缺省时用虚构示例 core/people.example.json） |
| --date | 未指定 | 公历日期 YYYY-MM-DD |
| --time | 未指定 | 当地钟表时间 HH:MM |
| --time-range | 未指定 | 约略时间区间 HH:MM-HH:MM（覆盖人物档案的区间） |
| --place | 未指定 | 地点名（core/geo 常量表） |
| --lat | 未指定 |  |
| --lon | 未指定 |  |
| --tz | 未指定 | IANA 时区，如 Asia/Shanghai |
| --gender | 未指定 |  可选：male, female, 男, 女 |
| --json | False | 输出 JSON（默认即 JSON，保留兼容） |
| --datetime | 未指定 | ISO 日期时间；有偏移量时转换到 --tz |
| --question |  |  |
| --leap-month-policy | 未指定 |  可选：repeat, next |
| --lines | 必填 |  |

---

Source: docs/meihua.md

# 梅花易数

采用传统先天八卦数字与 MIT chinese-fortune 体用表。时间法为农历年支序加月日，
再加时支序，取余定上下卦及动爻；日界为午夜。闰月显式选 repeat/next。
数字法 A 为上卦，B 为下卦，A+B 定动爻；静卦为体、动卦为用。
输出本卦、变卦、互卦、动爻、原始算数与体用生克。

`coins` 与 `random` 均为随机数字起卦，不等于六爻铜钱法；使用同一随机日志方法键。
默认事件时间为当前时刻，默认时区 Asia/Shanghai；区间按时辰分支。
公开规则回归为《梅花易数》观梅占：34/43、初爻动、泽火革变泽山咸。

## 示例

```bash
bin/prophet meihua numbers 34 43
bin/prophet meihua time --person S02
bin/prophet meihua random --seed 42 --question 演示 --no-record
```

所有人物示例均为虚构。原始输入、规则、警告和候选解释见 [公共层](core.md)。

## meihua time

| 参数 | 默认 | 说明 |
| --- | --- | --- |
| --person | 未指定 | 人物代号，如 S01（core/people.json，缺省时用虚构示例 core/people.example.json） |
| --date | 未指定 | 公历日期 YYYY-MM-DD |
| --time | 未指定 | 当地钟表时间 HH:MM |
| --time-range | 未指定 | 约略时间区间 HH:MM-HH:MM（覆盖人物档案的区间） |
| --place | 未指定 | 地点名（core/geo 常量表） |
| --lat | 未指定 |  |
| --lon | 未指定 |  |
| --tz | 未指定 | IANA 时区，如 Asia/Shanghai |
| --gender | 未指定 |  可选：male, female, 男, 女 |
| --json | False | 输出 JSON（默认即 JSON，保留兼容） |
| --datetime | 未指定 | ISO 日期时间；有偏移量时转换到 --tz |
| --question |  |  |
| --leap-month-policy | 未指定 |  可选：repeat, next |

## meihua numbers

| 参数 | 默认 | 说明 |
| --- | --- | --- |
| --person | 未指定 | 人物代号，如 S01（core/people.json，缺省时用虚构示例 core/people.example.json） |
| --date | 未指定 | 公历日期 YYYY-MM-DD |
| --time | 未指定 | 当地钟表时间 HH:MM |
| --time-range | 未指定 | 约略时间区间 HH:MM-HH:MM（覆盖人物档案的区间） |
| --place | 未指定 | 地点名（core/geo 常量表） |
| --lat | 未指定 |  |
| --lon | 未指定 |  |
| --tz | 未指定 | IANA 时区，如 Asia/Shanghai |
| --gender | 未指定 |  可选：male, female, 男, 女 |
| --json | False | 输出 JSON（默认即 JSON，保留兼容） |
| --datetime | 未指定 | ISO 日期时间；有偏移量时转换到 --tz |
| --question |  |  |
| --leap-month-policy | 未指定 |  可选：repeat, next |
| A | 必填 |  |
| B | 必填 |  |

## meihua coins

| 参数 | 默认 | 说明 |
| --- | --- | --- |
| --person | 未指定 | 人物代号，如 S01（core/people.json，缺省时用虚构示例 core/people.example.json） |
| --date | 未指定 | 公历日期 YYYY-MM-DD |
| --time | 未指定 | 当地钟表时间 HH:MM |
| --time-range | 未指定 | 约略时间区间 HH:MM-HH:MM（覆盖人物档案的区间） |
| --place | 未指定 | 地点名（core/geo 常量表） |
| --lat | 未指定 |  |
| --lon | 未指定 |  |
| --tz | 未指定 | IANA 时区，如 Asia/Shanghai |
| --gender | 未指定 |  可选：male, female, 男, 女 |
| --json | False | 输出 JSON（默认即 JSON，保留兼容） |
| --datetime | 未指定 | ISO 日期时间；有偏移量时转换到 --tz |
| --question |  |  |
| --leap-month-policy | 未指定 |  可选：repeat, next |
| --seed | 未指定 |  |
| --no-record | False |  |

## meihua random

| 参数 | 默认 | 说明 |
| --- | --- | --- |
| --person | 未指定 | 人物代号，如 S01（core/people.json，缺省时用虚构示例 core/people.example.json） |
| --date | 未指定 | 公历日期 YYYY-MM-DD |
| --time | 未指定 | 当地钟表时间 HH:MM |
| --time-range | 未指定 | 约略时间区间 HH:MM-HH:MM（覆盖人物档案的区间） |
| --place | 未指定 | 地点名（core/geo 常量表） |
| --lat | 未指定 |  |
| --lon | 未指定 |  |
| --tz | 未指定 | IANA 时区，如 Asia/Shanghai |
| --gender | 未指定 |  可选：male, female, 男, 女 |
| --json | False | 输出 JSON（默认即 JSON，保留兼容） |
| --datetime | 未指定 | ISO 日期时间；有偏移量时转换到 --tz |
| --question |  |  |
| --leap-month-policy | 未指定 |  可选：repeat, next |
| --seed | 未指定 |  |
| --no-record | False |  |

---

Source: docs/qimen.md

# 奇门遁甲

实现时家转盘参考兼容盘，表格与基础函数来自 MIT chinese-fortune。
默认 chaibu（符头拆补）；futou 为兼容选择，zhirun/置闰使用连续超神接气算法。
置闰门槛默认 9，允许 0..14；严格大于门槛才闰，7 可复现部分八日差置闰例。
结果明确输出节气上下文、符头、三元、局数、值符、值使、九宫、空亡与马星。
天禽寄宫等流派差异未经过古籍全盘校核，不能声称唯一正统盘。

提供 --lon 时才应用经度真太阳时修正，--place/--person 解析地点本身不自动开启该修正。
约略输入按候选分支；时间、UTC 偏移与节气处理的假设随结果提供。
测试覆盖节气、拆补表、置闰年度连续性、阈值和兼容默认规则。

## 示例

```bash
bin/prophet qimen chart --datetime 2026-10-31T12:00 --tz Asia/Shanghai
bin/prophet qimen chart --person S02 --ju-method zhirun
```

所有人物示例均为虚构。原始输入、规则、警告和候选解释见 [公共层](core.md)。

## qimen chart

| 参数 | 默认 | 说明 |
| --- | --- | --- |
| --person | 未指定 | 人物代号，如 S01（core/people.json，缺省时用虚构示例 core/people.example.json） |
| --date | 未指定 | 公历日期 YYYY-MM-DD |
| --time | 未指定 | 当地钟表时间 HH:MM |
| --time-range | 未指定 | 约略时间区间 HH:MM-HH:MM（覆盖人物档案的区间） |
| --place | 未指定 | 地点名（core/geo 常量表） |
| --lat | 未指定 |  |
| --lon | 未指定 |  |
| --tz | 未指定 | IANA 时区，如 Asia/Shanghai |
| --gender | 未指定 |  可选：male, female, 男, 女 |
| --json | False | 输出 JSON（默认即 JSON，保留兼容） |
| --datetime | 未指定 | ISO 日期时间；有偏移量时转换到 --tz |
| --ju-method | chaibu | 默认符头拆补；zhirun/置闰为连续超神接气置闰法 可选：chaibu, 拆补, futou, zhirun, 置闰 |
| --zhirun-threshold | 9 | 至日期减不闰时至上元符头日期，严格大于门槛才闰（0..14；默认9；7复现8日差置闰） |

---

Source: docs/tarot.md

# 塔罗

RWS 78 张牌，牌义是对 A. E. Waite 1910 年公有领域文本的原创关键词改写，无牌面图像。
默认 one 一张；three 为过去/现在/未来，celtic 十张。seed 驱动 Python Random 洗牌，
每张逆位概率 0.5。可复现性以 Python 算法及版本为限，不声称随机结果有预测效力。

`draw` 需要 --question，默认写 core/draws.jsonl，包含问题原文及结果。
相同方法/问题复用；显式不同 seed 有重抽警告，指定已有旧 seed 时复用旧记录。
--no-record 不追加日志，但仍可读取已有记录。默认时区 Asia/Shanghai。
`card NAME` 支持牌 ID、英文或中文名；不抽牌、不写日志。

## 示例

```bash
bin/prophet tarot draw --spread three --question 虚构演示 --seed 42 --no-record
bin/prophet tarot card "The Fool"
```

所有人物示例均为虚构。原始输入、规则、警告和候选解释见 [公共层](core.md)。

## tarot draw

| 参数 | 默认 | 说明 |
| --- | --- | --- |
| --spread | one |  可选：one, three, celtic |
| --question | 必填 |  |
| --seed | 未指定 |  |
| --no-record | False |  |
| --tz | Asia/Shanghai |  |
| --json | False |  |

## tarot card

| 参数 | 默认 | 说明 |
| --- | --- | --- |
| name | 必填 |  |
| --json | False |  |

---

Source: docs/validate.md

# 交叉校验

validate 接受共同出生输入，默认钟表时。all 返回各体系汇总，单体系返回具体字段差异。
八字 lunar-python 立春规则与 iztro 农历新年规则差异明确保留，不能为通过测试而隐去。
紫微独立子集计算命身宫、五行局、十四主星及部分辅星/四化；Renhuai 比较另标非独立。
西方以 astronomy-engine 对照主行星经度，日月至土星容差 1 角分、外行星 2 角分。
印度以独立热带经度减 Swiss Lahiri 交叉检查位置及月宿区间；共享岁差来源，交点排除。

approx 输入返回分支及 invariants。一致只证明选定字段与规则的计算一致，不证明术数的预测能力。
`selftest` 发现 tests/test_*.py 的 test_* 函数，-k 按名字筛选；失败退出码非零。
Chiron 文件缺失时仅相关数值测试打印 NOTE 后通过，降级路径仍测试。
语料课程未启用时跳过课程断言；其余语料/许可/检索检查仍执行。

## 示例

```bash
bin/prophet validate all --person S01
bin/prophet validate ziwei --person S02
bin/prophet selftest -k vedic
```

所有人物示例均为虚构。原始输入、规则、警告和候选解释见 [公共层](core.md)。

## validate bazi

| 参数 | 默认 | 说明 |
| --- | --- | --- |
| --person | 未指定 | 人物代号，如 S01（core/people.json，缺省时用虚构示例 core/people.example.json） |
| --date | 未指定 | 公历日期 YYYY-MM-DD |
| --time | 未指定 | 当地钟表时间 HH:MM |
| --time-range | 未指定 | 约略时间区间 HH:MM-HH:MM（覆盖人物档案的区间） |
| --place | 未指定 | 地点名（core/geo 常量表） |
| --lat | 未指定 |  |
| --lon | 未指定 |  |
| --tz | 未指定 | IANA 时区，如 Asia/Shanghai |
| --gender | 未指定 |  可选：male, female, 男, 女 |
| --json | False | 输出 JSON（默认即 JSON，保留兼容） |

## validate ziwei

| 参数 | 默认 | 说明 |
| --- | --- | --- |
| --person | 未指定 | 人物代号，如 S01（core/people.json，缺省时用虚构示例 core/people.example.json） |
| --date | 未指定 | 公历日期 YYYY-MM-DD |
| --time | 未指定 | 当地钟表时间 HH:MM |
| --time-range | 未指定 | 约略时间区间 HH:MM-HH:MM（覆盖人物档案的区间） |
| --place | 未指定 | 地点名（core/geo 常量表） |
| --lat | 未指定 |  |
| --lon | 未指定 |  |
| --tz | 未指定 | IANA 时区，如 Asia/Shanghai |
| --gender | 未指定 |  可选：male, female, 男, 女 |
| --json | False | 输出 JSON（默认即 JSON，保留兼容） |

## validate western

| 参数 | 默认 | 说明 |
| --- | --- | --- |
| --person | 未指定 | 人物代号，如 S01（core/people.json，缺省时用虚构示例 core/people.example.json） |
| --date | 未指定 | 公历日期 YYYY-MM-DD |
| --time | 未指定 | 当地钟表时间 HH:MM |
| --time-range | 未指定 | 约略时间区间 HH:MM-HH:MM（覆盖人物档案的区间） |
| --place | 未指定 | 地点名（core/geo 常量表） |
| --lat | 未指定 |  |
| --lon | 未指定 |  |
| --tz | 未指定 | IANA 时区，如 Asia/Shanghai |
| --gender | 未指定 |  可选：male, female, 男, 女 |
| --json | False | 输出 JSON（默认即 JSON，保留兼容） |

## validate vedic

| 参数 | 默认 | 说明 |
| --- | --- | --- |
| --person | 未指定 | 人物代号，如 S01（core/people.json，缺省时用虚构示例 core/people.example.json） |
| --date | 未指定 | 公历日期 YYYY-MM-DD |
| --time | 未指定 | 当地钟表时间 HH:MM |
| --time-range | 未指定 | 约略时间区间 HH:MM-HH:MM（覆盖人物档案的区间） |
| --place | 未指定 | 地点名（core/geo 常量表） |
| --lat | 未指定 |  |
| --lon | 未指定 |  |
| --tz | 未指定 | IANA 时区，如 Asia/Shanghai |
| --gender | 未指定 |  可选：male, female, 男, 女 |
| --json | False | 输出 JSON（默认即 JSON，保留兼容） |

## validate all

| 参数 | 默认 | 说明 |
| --- | --- | --- |
| --person | 未指定 | 人物代号，如 S01（core/people.json，缺省时用虚构示例 core/people.example.json） |
| --date | 未指定 | 公历日期 YYYY-MM-DD |
| --time | 未指定 | 当地钟表时间 HH:MM |
| --time-range | 未指定 | 约略时间区间 HH:MM-HH:MM（覆盖人物档案的区间） |
| --place | 未指定 | 地点名（core/geo 常量表） |
| --lat | 未指定 |  |
| --lon | 未指定 |  |
| --tz | 未指定 | IANA 时区，如 Asia/Shanghai |
| --gender | 未指定 |  可选：male, female, 男, 女 |
| --json | False | 输出 JSON（默认即 JSON，保留兼容） |

---

Source: docs/vedic.md

# 印度占星

采用 Swiss Ephemeris Moshier、Lahiri 恒星黄道、整宫制、默认平均交点，Ketu 与 Rahu 相对。
分盘 D1/D7/D9/D10/D12；Vimshottari 年长固定 365.25 日，出生前完整大运不重启子运。
--levels 默认为 3，可用 1/2；--at 为出生地时区零点的查询日，省略取当前时刻。
BAV 默认 parashara，另有 dashaflow/varahamihira/pyjhora-pvr；输出逐源贡献与 SAV 总分 337。
pyjhora-pvr 从 P.V.R. Narasimha Rao 书中描述独立实现，不使用 PyJHora。

交点尊贵默认 none，可选 bphs/gemini-sagittarius；不是对不同流派的统一结论。
`shadbala` 或 chart --shadbala 输出 Raman/Sripathi 六力及各分量、来源、阈值和警告。
历史平运动近似、历年/月主规则和参考书勘误见 [规则明细](../vedic/data/RULES.md)。
只在测试引用 Raman Standard Horoscope 数字，不发布书中文字。

约略时间每 15 分钟加端点采样，未知时间拒绝。没有自动校时、D60、瑜伽或 BAV 消减。
公开回归包括 dashaflow Delhi 图、Lahiri J2000、BAV 守恒、分盘边界及 Raman 六力数值。

## 示例

```bash
bin/prophet vedic chart --person S01 --levels 1 --at 2026-10-31
bin/prophet vedic dasha --person S02 --levels 2 --at 2026-10-31
bin/prophet vedic shadbala --person S01 --levels 1
```

所有人物示例均为虚构。原始输入、规则、警告和候选解释见 [公共层](core.md)。

## vedic chart

| 参数 | 默认 | 说明 |
| --- | --- | --- |
| --person | 未指定 | 人物代号，如 S01（core/people.json，缺省时用虚构示例 core/people.example.json） |
| --date | 未指定 | 公历日期 YYYY-MM-DD |
| --time | 未指定 | 当地钟表时间 HH:MM |
| --time-range | 未指定 | 约略时间区间 HH:MM-HH:MM（覆盖人物档案的区间） |
| --place | 未指定 | 地点名（core/geo 常量表） |
| --lat | 未指定 |  |
| --lon | 未指定 |  |
| --tz | 未指定 | IANA 时区，如 Asia/Shanghai |
| --gender | 未指定 |  可选：male, female, 男, 女 |
| --json | False | 输出 JSON（默认即 JSON，保留兼容） |
| --node | mean |  可选：mean, true |
| --bav-table | parashara |  可选：dashaflow, parashara, varahamihira, pyjhora-pvr |
| --node-dignity | none |  可选：none, bphs, gemini-sagittarius |
| --shadbala | False | include Raman sixfold strength |
| --at | 未指定 | 查询日期 YYYY-MM-DD（出生地时区午夜） |
| --levels | 3 |  可选：1, 2, 3 |
| --save-cache | False |  |

## vedic dasha

| 参数 | 默认 | 说明 |
| --- | --- | --- |
| --person | 未指定 | 人物代号，如 S01（core/people.json，缺省时用虚构示例 core/people.example.json） |
| --date | 未指定 | 公历日期 YYYY-MM-DD |
| --time | 未指定 | 当地钟表时间 HH:MM |
| --time-range | 未指定 | 约略时间区间 HH:MM-HH:MM（覆盖人物档案的区间） |
| --place | 未指定 | 地点名（core/geo 常量表） |
| --lat | 未指定 |  |
| --lon | 未指定 |  |
| --tz | 未指定 | IANA 时区，如 Asia/Shanghai |
| --gender | 未指定 |  可选：male, female, 男, 女 |
| --json | False | 输出 JSON（默认即 JSON，保留兼容） |
| --node | mean |  可选：mean, true |
| --bav-table | parashara |  可选：dashaflow, parashara, varahamihira, pyjhora-pvr |
| --node-dignity | none |  可选：none, bphs, gemini-sagittarius |
| --shadbala | False | include Raman sixfold strength |
| --at | 未指定 | 查询日期 YYYY-MM-DD（出生地时区午夜） |
| --levels | 3 |  可选：1, 2, 3 |
| --save-cache | False |  |

## vedic nakshatra

| 参数 | 默认 | 说明 |
| --- | --- | --- |
| --person | 未指定 | 人物代号，如 S01（core/people.json，缺省时用虚构示例 core/people.example.json） |
| --date | 未指定 | 公历日期 YYYY-MM-DD |
| --time | 未指定 | 当地钟表时间 HH:MM |
| --time-range | 未指定 | 约略时间区间 HH:MM-HH:MM（覆盖人物档案的区间） |
| --place | 未指定 | 地点名（core/geo 常量表） |
| --lat | 未指定 |  |
| --lon | 未指定 |  |
| --tz | 未指定 | IANA 时区，如 Asia/Shanghai |
| --gender | 未指定 |  可选：male, female, 男, 女 |
| --json | False | 输出 JSON（默认即 JSON，保留兼容） |
| --node | mean |  可选：mean, true |
| --bav-table | parashara |  可选：dashaflow, parashara, varahamihira, pyjhora-pvr |
| --node-dignity | none |  可选：none, bphs, gemini-sagittarius |
| --shadbala | False | include Raman sixfold strength |
| --at | 未指定 | 查询日期 YYYY-MM-DD（出生地时区午夜） |
| --levels | 3 |  可选：1, 2, 3 |
| --save-cache | False |  |

## vedic shadbala

| 参数 | 默认 | 说明 |
| --- | --- | --- |
| --person | 未指定 | 人物代号，如 S01（core/people.json，缺省时用虚构示例 core/people.example.json） |
| --date | 未指定 | 公历日期 YYYY-MM-DD |
| --time | 未指定 | 当地钟表时间 HH:MM |
| --time-range | 未指定 | 约略时间区间 HH:MM-HH:MM（覆盖人物档案的区间） |
| --place | 未指定 | 地点名（core/geo 常量表） |
| --lat | 未指定 |  |
| --lon | 未指定 |  |
| --tz | 未指定 | IANA 时区，如 Asia/Shanghai |
| --gender | 未指定 |  可选：male, female, 男, 女 |
| --json | False | 输出 JSON（默认即 JSON，保留兼容） |
| --node | mean |  可选：mean, true |
| --bav-table | parashara |  可选：dashaflow, parashara, varahamihira, pyjhora-pvr |
| --node-dignity | none |  可选：none, bphs, gemini-sagittarius |
| --shadbala | False | include Raman sixfold strength |
| --at | 未指定 | 查询日期 YYYY-MM-DD（出生地时区午夜） |
| --levels | 3 |  可选：1, 2, 3 |
| --save-cache | False |  |

---

Source: docs/western.md

# 西方占星

主行星及月交点采用 Swiss Ephemeris Moshier、地心视位置、热带黄道，UT 以 UTC 近似。
默认 Placidus 宫制；可选 whole-sign/koch/equal/porphyry。极地 Placidus/Koch 回退 Porphyry，
计算失败进一步回退整宫并警告。默认主要相位容许度：合冲 8、拱刑 6、六合 4 度。
--minor 增加次要相位，--orbs 接收 JSON 度数映射。宫位按黄经宫头区间分配。

`transits/progressions` 需 --at；次限为每 365.2425 个经过日对应一个星历日。
`solar-return` 需 --year；人物输入时 --place 可指定返照地点，不改本命地点。
`synastry` 可用 --other S03，或完整 --other-date/time/place 等输入。
Chiron 依赖下载的 seas_18.se1，缺失或超范围省略并警告；其他星体仍可算。
近停阈值是每日 0.001 度，属于本工具约定。

约略出生按 15 分钟加端点取样，宫位稳定只指样本。未知时间用中午占位并警告。
公开回归包括 Einstein 1879-03-14 11:30 LMT Ulm（测试直接换算地方平时）、
J2000 与 astronomy-engine 经度对照。现代时区输入不等价于历史 LMT。

## 示例

```bash
bin/prophet western natal --person S01
bin/prophet western transits --person S01 --at 2026-10-31
bin/prophet western solar-return --person S01 --year 2026
bin/prophet western synastry --person S01 --other S03
```

所有人物示例均为虚构。原始输入、规则、警告和候选解释见 [公共层](core.md)。

## western natal

| 参数 | 默认 | 说明 |
| --- | --- | --- |
| --person | 未指定 | 人物代号，如 S01（core/people.json，缺省时用虚构示例 core/people.example.json） |
| --date | 未指定 | 公历日期 YYYY-MM-DD |
| --time | 未指定 | 当地钟表时间 HH:MM |
| --time-range | 未指定 | 约略时间区间 HH:MM-HH:MM（覆盖人物档案的区间） |
| --place | 未指定 | 地点名（core/geo 常量表） |
| --lat | 未指定 |  |
| --lon | 未指定 |  |
| --tz | 未指定 | IANA 时区，如 Asia/Shanghai |
| --gender | 未指定 |  可选：male, female, 男, 女 |
| --json | False | 输出 JSON（默认即 JSON，保留兼容） |
| --house-system | placidus |  可选：placidus, whole-sign, koch, equal, porphyry |
| --minor | False |  |
| --orbs | 未指定 |  |
| --save-cache | False |  |

## western transits

| 参数 | 默认 | 说明 |
| --- | --- | --- |
| --person | 未指定 | 人物代号，如 S01（core/people.json，缺省时用虚构示例 core/people.example.json） |
| --date | 未指定 | 公历日期 YYYY-MM-DD |
| --time | 未指定 | 当地钟表时间 HH:MM |
| --time-range | 未指定 | 约略时间区间 HH:MM-HH:MM（覆盖人物档案的区间） |
| --place | 未指定 | 地点名（core/geo 常量表） |
| --lat | 未指定 |  |
| --lon | 未指定 |  |
| --tz | 未指定 | IANA 时区，如 Asia/Shanghai |
| --gender | 未指定 |  可选：male, female, 男, 女 |
| --json | False | 输出 JSON（默认即 JSON，保留兼容） |
| --house-system | placidus |  可选：placidus, whole-sign, koch, equal, porphyry |
| --minor | False |  |
| --orbs | 未指定 |  |
| --save-cache | False |  |
| --at | 必填 |  |

## western progressions

| 参数 | 默认 | 说明 |
| --- | --- | --- |
| --person | 未指定 | 人物代号，如 S01（core/people.json，缺省时用虚构示例 core/people.example.json） |
| --date | 未指定 | 公历日期 YYYY-MM-DD |
| --time | 未指定 | 当地钟表时间 HH:MM |
| --time-range | 未指定 | 约略时间区间 HH:MM-HH:MM（覆盖人物档案的区间） |
| --place | 未指定 | 地点名（core/geo 常量表） |
| --lat | 未指定 |  |
| --lon | 未指定 |  |
| --tz | 未指定 | IANA 时区，如 Asia/Shanghai |
| --gender | 未指定 |  可选：male, female, 男, 女 |
| --json | False | 输出 JSON（默认即 JSON，保留兼容） |
| --house-system | placidus |  可选：placidus, whole-sign, koch, equal, porphyry |
| --minor | False |  |
| --orbs | 未指定 |  |
| --save-cache | False |  |
| --at | 必填 |  |

## western solar-return

| 参数 | 默认 | 说明 |
| --- | --- | --- |
| --person | 未指定 | 人物代号，如 S01（core/people.json，缺省时用虚构示例 core/people.example.json） |
| --date | 未指定 | 公历日期 YYYY-MM-DD |
| --time | 未指定 | 当地钟表时间 HH:MM |
| --time-range | 未指定 | 约略时间区间 HH:MM-HH:MM（覆盖人物档案的区间） |
| --place | 未指定 | 地点名（core/geo 常量表） |
| --lat | 未指定 |  |
| --lon | 未指定 |  |
| --tz | 未指定 | IANA 时区，如 Asia/Shanghai |
| --gender | 未指定 |  可选：male, female, 男, 女 |
| --json | False | 输出 JSON（默认即 JSON，保留兼容） |
| --house-system | placidus |  可选：placidus, whole-sign, koch, equal, porphyry |
| --minor | False |  |
| --orbs | 未指定 |  |
| --save-cache | False |  |
| --year | 必填 |  |

## western synastry

| 参数 | 默认 | 说明 |
| --- | --- | --- |
| --person | 未指定 | 人物代号，如 S01（core/people.json，缺省时用虚构示例 core/people.example.json） |
| --date | 未指定 | 公历日期 YYYY-MM-DD |
| --time | 未指定 | 当地钟表时间 HH:MM |
| --time-range | 未指定 | 约略时间区间 HH:MM-HH:MM（覆盖人物档案的区间） |
| --place | 未指定 | 地点名（core/geo 常量表） |
| --lat | 未指定 |  |
| --lon | 未指定 |  |
| --tz | 未指定 | IANA 时区，如 Asia/Shanghai |
| --gender | 未指定 |  可选：male, female, 男, 女 |
| --json | False | 输出 JSON（默认即 JSON，保留兼容） |
| --house-system | placidus |  可选：placidus, whole-sign, koch, equal, porphyry |
| --minor | False |  |
| --orbs | 未指定 |  |
| --save-cache | False |  |
| --other | 未指定 |  |
| --other-date | 未指定 |  |
| --other-time | 未指定 |  |
| --other-time-range | 未指定 |  |
| --other-place | 未指定 |  |
| --other-tz | 未指定 |  |
| --other-lat | 未指定 |  |
| --other-lon | 未指定 |  |

## western check

| 参数 | 默认 | 说明 |
| --- | --- | --- |
| --person | 未指定 | 人物代号，如 S01（core/people.json，缺省时用虚构示例 core/people.example.json） |
| --date | 未指定 | 公历日期 YYYY-MM-DD |
| --time | 未指定 | 当地钟表时间 HH:MM |
| --time-range | 未指定 | 约略时间区间 HH:MM-HH:MM（覆盖人物档案的区间） |
| --place | 未指定 | 地点名（core/geo 常量表） |
| --lat | 未指定 |  |
| --lon | 未指定 |  |
| --tz | 未指定 | IANA 时区，如 Asia/Shanghai |
| --gender | 未指定 |  可选：male, female, 男, 女 |
| --json | False | 输出 JSON（默认即 JSON，保留兼容） |
| --house-system | placidus |  可选：placidus, whole-sign, koch, equal, porphyry |
| --minor | False |  |
| --orbs | 未指定 |  |
| --save-cache | False |  |

---

Source: docs/ziwei.md

# 紫微斗数

本地 Node 桥接 iztro 2.6.1 与 MIT Renhuai 算法摘录。默认钟表时、农历新年分年、
闰月 split（十五日前后分配）、亮度 default；可选 QS/XD1/ZZ/XD2 亮度表。
晚子 23 点采用次日，保留 iztro 索引 12 与 Renhuai 次日索引 0 的适配信息。
Renhuai 内部调用 iztro，两者一致只能说明适配一致，不能声称独立验证。

`chart/compare` 的 --year 用该年 7 月 1 日作农历年参考，输出流年四化等信息。
`horoscope` 的 --date 是目标日期，--birth-date 为临时出生日期；可选 --hour 0..23，
省略时不输出流时。含大限、小限与年/月/日/时干支、四化落宫和流宫对照。
未知出生时间会拒绝；约略时间按时辰分支，跨午夜保留不同日期。
公开例使用 iztro README 的 2000-08-16 寅时女命；独立排星子集由 validate 校验。


## 示例

```bash
bin/prophet ziwei compare --person S01 --year 2026
bin/prophet ziwei horoscope --person S02 --date 2026-08-28 --hour 12
```

所有人物示例均为虚构。原始输入、规则、警告和候选解释见 [公共层](core.md)。

## ziwei chart

| 参数 | 默认 | 说明 |
| --- | --- | --- |
| --person | 未指定 | 人物代号，如 S01（core/people.json，缺省时用虚构示例 core/people.example.json） |
| --date | 未指定 | 公历日期 YYYY-MM-DD |
| --time | 未指定 | 当地钟表时间 HH:MM |
| --time-range | 未指定 | 约略时间区间 HH:MM-HH:MM（覆盖人物档案的区间） |
| --place | 未指定 | 地点名（core/geo 常量表） |
| --lat | 未指定 |  |
| --lon | 未指定 |  |
| --tz | 未指定 | IANA 时区，如 Asia/Shanghai |
| --gender | 未指定 |  可选：male, female, 男, 女 |
| --json | False | 输出 JSON（默认即 JSON，保留兼容） |
| --year | 未指定 | 流年（以该年7月1日的农历年为准） |
| --time-standard | clock |  可选：clock, true-solar |
| --school, --brightness-school | default |  可选：default, QS, XD1, ZZ, XD2 |
| --leap-month | split |  可选：split, prev-month, next-month, origin-month |
| --save-cache | False |  |

## ziwei compare

| 参数 | 默认 | 说明 |
| --- | --- | --- |
| --person | 未指定 | 人物代号，如 S01（core/people.json，缺省时用虚构示例 core/people.example.json） |
| --date | 未指定 | 公历日期 YYYY-MM-DD |
| --time | 未指定 | 当地钟表时间 HH:MM |
| --time-range | 未指定 | 约略时间区间 HH:MM-HH:MM（覆盖人物档案的区间） |
| --place | 未指定 | 地点名（core/geo 常量表） |
| --lat | 未指定 |  |
| --lon | 未指定 |  |
| --tz | 未指定 | IANA 时区，如 Asia/Shanghai |
| --gender | 未指定 |  可选：male, female, 男, 女 |
| --json | False | 输出 JSON（默认即 JSON，保留兼容） |
| --year | 未指定 | 流年（以该年7月1日的农历年为准） |
| --time-standard | clock |  可选：clock, true-solar |
| --school, --brightness-school | default |  可选：default, QS, XD1, ZZ, XD2 |
| --leap-month | split |  可选：split, prev-month, next-month, origin-month |
| --save-cache | False |  |

## ziwei horoscope

| 参数 | 默认 | 说明 |
| --- | --- | --- |
| --person | 未指定 | 人物代号，如 S01（core/people.json，缺省时用虚构示例 core/people.example.json） |
| --date | 未指定 | 目标日期 YYYY-MM-DD（非出生日期） |
| --time | 未指定 | 当地钟表时间 HH:MM |
| --time-range | 未指定 | 约略时间区间 HH:MM-HH:MM（覆盖人物档案的区间） |
| --place | 未指定 | 地点名（core/geo 常量表） |
| --lat | 未指定 |  |
| --lon | 未指定 |  |
| --tz | 未指定 | IANA 时区，如 Asia/Shanghai |
| --gender | 未指定 |  可选：male, female, 男, 女 |
| --json | False | 输出 JSON（默认即 JSON，保留兼容） |
| --birth-date | 未指定 | 临时出生日期 YYYY-MM-DD；--person 时默认档案日期 |
| --hour | 未指定 | 目标钟表小时0–23；省略不输出流时 |
| --time-standard | clock |  可选：clock, true-solar |
| --leap-month | split |  可选：split, prev-month, next-month, origin-month |

---

Source: skills/bazi/SKILL.md

---
name: bazi
description: 使用 Prophet 八字 JSON 与本地子平语料分阶段解读，区分旺衰、格局、调候及运限并审核证据；不代替排盘。
---

# 八字分析

先读取 `engine.name/version/rules`、`warnings` 和 `input`。保留原始钟表时间、精度和所有候选；不把计算样本写成确认出生时间。以下路径以原始 CLI JSON 为根；`[0]` 仅示范索引，实际逐分支替换，不支持通配符。未返回的字段应写“未计算”，不能凭记忆补盘。

按问题选择工具 → 制定阶段计划 → 排盘 → 按条件检索本地语料 → 带证据回答 → Critic 复核。复用已有有效命盘，避免反复排盘和整库灌入上下文。技能本身不调用模型或网络，不改变核心规则。

## 工具与字段

`bin/prophet bazi chart ...`；运年另用 `bazi liunian ... --year YYYY`，流月用 `bazi liuyue`。
必读字段及条件字段见 [字段与规则](references/analysis.md)。先核对候选数与 `invariants`；不要只读第一盘。

## 分阶段分析

1. **旺衰**：从月令、日主、通根、透干和生克条件分别论证，区分得令/得地/得势；不从五行个数直接判强弱。
2. **格局**：按所选格局流派，从月令及透藏提出候选；列成格、破格、救应条件，不因某个十神出现就定格。
3. **调候**：以日干、季节及寒暖燥湿检索，核实原文条件。调候用神与扶抑、格局用神分别标记。
4. **病药**：写明结构障碍的证据及解决条件；至少检验一个反例，不把“病”当医学诊断。
5. **十神**：在位置、藏透、组合及前述结构中分析；神煞仅作补充，不据单一标签推定具体经历。
6. **大运流年**：读 `dayun` 顺逆、起运、起止年与年龄口径；流年必须来自指定年的工具。分清本命条件与运年触发，写时间范围和相反条件，不承诺事件必发生。

每阶段先列事实，再搜索 [规则查询](references/analysis.md)，最后形成暂定推论。缺少成立条件则保留候选，不强行给唯一喜忌。

## Critic / evaluator

输出前另作一轮审核，返回 `pass/revise/insufficient` 和问题清单：

- 每条盘面事实是否来自当前人物、当前分支的实际工具输出？检查字段值，禁止编造星曜、干支和坐标。
- 每条解释是否有具体 `json_paths`、具名 `school` / `rule_id`、检索 `query` 或真实段落 `id`？查询只是待核出处，不能冒充已取得原文。
- 检索后是否核对段落、相邻上下文、条件、来源及许可？引用不等于规则适用；不虚构引文或段落 ID。
- 是否区分计算事实、经典规则和分析推论？计数不是旺衰评分，星曜标签不是人生事件。
- 是否列出支持和不支持条件、相反解释，以及约略时间改变的部分？不得把单分支结论写成区间共识。
- 是否混用流派、时间规则或把相同底层库重复计为独立证据？实际经历只能作外部反馈，不能伪装为推算。
- 标注 hallucination（不存在字段、虚构出处、无证据断语）、uncertainty（输入/规则/解释分别列出）和 counter-interpretations。缺证据时删改结论，不能只降低 confidence 后保留断言。

## 输出模板

按下列结构输出分析；`evidence` 中每条均遵循 [证据协议](../../docs/agent-workflows.md)，避免留下占位值：

```text
对象与问题；engine / rules / warnings；时间精度与分支范围
盘面事实：字段路径 → 实际值
逐阶段分析：判断 → 成立条件 → evidence item → 反证/异说
稳定结论 / 分支结论 / 未决问题
Critic：status、hallucination、uncertainty、counter_interpretations、修订项
```

使用 `prophet evidence check FILE` 检查 `{chart: 原始命盘, evidence: [...]}`。
验证通过只保证结构和字段存在，不保证解释正确；人工 Critic 仍需检查语义。

---

Source: skills/cross-check/SKILL.md

---
name: cross-check
description: 以 Prophet 独立运行至少两个体系，保留分支和规则，轻量比较共识、冲突与独有信息；仅综合分析请求适用。
---

# 轻量跨体系工作流

默认一个代理顺序完成，无需模型服务或额外依赖。运行：

```bash
bin/prophet cross-check run --person S01
bin/prophet cross-check run --person S02 --systems bazi,ziwei,western --include-charts
```

1. 明确对象、问题和时间精度。helper 经共享输入解析后独立调用各体系，东方默认统一 clock；可用 `--time-standard true-solar`。西占始终钟表转 UTC。规则差异仍须读取各 engine。
2. 读取 summaries 各自的 facts / json_path、engine、warnings、invariants、branch_count。默认只携带精简事实，需要审计时才 include-charts。所有候选保留，不选中点。
3. 分别使用 bazi / ziwei 技能形成短摘要，未看其他体系解释之前先固定本体系结论、证据、条件、反证。西占只解释实际算出的星位宫位，不将东方符号直接对应星座。
4. helper 的 comparison 只比较可匹配的事实键。四柱集合相同仅为历法一致；unique 表示无同键可比，绝不等于其他体系反对。集合不同可能来自边界、代表小时、换年规则或分支取样，不自动认定计算错误。
5. 对解释另建 `agreements/conflicts/unique` 三组。每项写主题、各体系原判断、独立 evidence、条件与时间范围、尚待解决的问题。不同体系不强行投票；同源计算不能升级置信度。不把传统跨体系共识写成预测已获验证。
6. Critic 检查人物一致、字段引用、规则差异、区间覆盖、虚构引文和相反解释。结构检验用 evidence check；它不检查语义。最终保留未决冲突。

可选深度模式仅在复杂问题确有需要且用户允许代理协作时使用：为各体系分配独立分析者，仅提供本体系原始盘与问题；汇总者对照摘要，评审者回查证据。不要为了普通问答默认启用多代理；不把它引入确定性核心。

完整数据协议、命令及局限见 [工作流说明](../../docs/agent-workflows.md)。

---

Source: skills/ziwei/SKILL.md

---
name: ziwei
description: 使用 Prophet 紫微 JSON 分析命身宫、星曜四化、三方四正与运限，逐分支引用证据并审核异说；不凭空排星。
---

# 紫微分析

先读取 `engine.name/version/rules`、`warnings` 和 `input`。保留原始钟表时间、精度和所有候选；不把计算样本写成确认出生时间。以下路径以原始 CLI JSON 为根；`[0]` 仅示范索引，实际逐分支替换，不支持通配符。未返回的字段应写“未计算”，不能凭记忆补盘。

按问题选择工具 → 制定阶段计划 → 排盘 → 按条件检索本地语料 → 带证据回答 → Critic 复核。复用已有有效命盘，避免反复排盘和整库灌入上下文。技能本身不调用模型或网络，不改变核心规则。

## 工具与字段

`bin/prophet ziwei chart ... --year YYYY`；指定目标日的流限使用 `ziwei horoscope --person CODE --date YYYY-MM-DD`。
临时输入的 horoscope 用 `--birth-date` 指定出生日期；`--date` 永远是目标日。
先读 [字段与规则](references/analysis.md)。精确盘字段位于根下；约略盘逐 `$.branches[i]` 处理，不能将不同候选的星曜合成一盘。

## 分阶段分析

1. **命身宫**：核对命宫地支、身宫地支和十二宫顺序；以宫名找到宫索引再引用。身宫不是凭年龄移动的命宫。
2. **主星**：逐宫读主辅星及亮度学校；空宫、借星只能作为具名流派的条件解释。不得凭记忆添加未返回的星。
3. **四化**：生年四化来自 `sihua`；与流限 `flows.*.mutagen` 分开，不混成同一层。核对化星及落宫后才讨论主题。
4. **三方四正**：按十二宫地支关系列本宫、两三合宫与对宫，再读取这些宫的实际星曜。说明采用规则及推导，不把对宫当本宫。
5. **大限流年**：核对大限范围、年龄口径和目标年；chart 的 annual 是指定年七月一日参考值，完整流限另调用 horoscope。区分本命、限、年；不给无触发条件的确定事件。

同主题先提出本体系判断和相反解释，再参与跨体系对照。Renhuai 内部也使用 iztro，二者一致不能算两份独立证据。

## Critic / evaluator

输出前另作一轮审核，返回 `pass/revise/insufficient` 和问题清单：

- 每条盘面事实是否来自当前人物、当前分支的实际工具输出？检查字段值，禁止编造星曜、干支和坐标。
- 每条解释是否有具体 `json_paths`、具名 `school` / `rule_id`、检索 `query` 或真实段落 `id`？查询只是待核出处，不能冒充已取得原文。
- 检索后是否核对段落、相邻上下文、条件、来源及许可？引用不等于规则适用；不虚构引文或段落 ID。
- 是否区分计算事实、经典规则和分析推论？计数不是旺衰评分，星曜标签不是人生事件。
- 是否列出支持和不支持条件、相反解释，以及约略时间改变的部分？不得把单分支结论写成区间共识。
- 是否混用流派、时间规则或把相同底层库重复计为独立证据？实际经历只能作外部反馈，不能伪装为推算。
- 标注 hallucination（不存在字段、虚构出处、无证据断语）、uncertainty（输入/规则/解释分别列出）和 counter-interpretations。缺证据时删改结论，不能只降低 confidence 后保留断言。

## 输出模板

按下列结构输出分析；`evidence` 中每条均遵循 [证据协议](../../docs/agent-workflows.md)，避免留下占位值：

```text
对象与问题；engine / rules / warnings；时间精度与分支范围
盘面事实：字段路径 → 实际值
逐阶段分析：判断 → 成立条件 → evidence item → 反证/异说
稳定结论 / 分支结论 / 未决问题
Critic：status、hallucination、uncertainty、counter_interpretations、修订项
```

使用 `prophet evidence check FILE` 检查 `{chart: 原始命盘, evidence: [...]}`。
验证通过只保证结构和字段存在，不保证解释正确；人工 Critic 仍需检查语义。

---

Source: skills/bazi/references/analysis.md

# 实际字段与规则索引

所有路径针对 `bazi chart` 原始返回。逐 `$.candidates[i]` 分支替换索引：

| 用途 | 精确示例路径 | 注意 |
| --- | --- | --- |
| 元数据 | `$.engine.rules`、`$.warnings`、`$.input.时间精度` | 原始时间在 `$.input.time` / `$.input.time_range` |
| 月令/日主 | `$.candidates[0].pillars.month.branch`、`$.candidates[0].day_master` | 月令不是单一计数 |
| 四柱 | `$.candidates[0].pillars.year.ganzhi`、`$.candidates[0].pillars.month.ganzhi`、`$.candidates[0].pillars.day.ganzhi`、`$.candidates[0].pillars.hour.ganzhi` | 每柱另有 stem / branch |
| 藏透十神 | `$.candidates[0].pillars.month.hidden_stems`、`$.candidates[0].pillars.month.stem_ten_god`、`$.candidates[0].pillars.month.hidden_ten_gods` | year/day/hour 同结构 |
| 计数 | `$.candidates[0].five_elements`、`$.candidates[0].hidden_stem_elements` | 未加权，非强弱分数 |
| 时间校正 | `$.candidates[0].clock_time`、`$.candidates[0].true_solar`、`$.candidates[0].calculation_time` | 查看 `$.engine.rules.time_standard` |
| 运限 | `$.candidates[0].dayun` | 未提供性别时可能为 null |
| 运限明细 | `$.candidates[0].dayun.direction`、`$.candidates[0].dayun.start_date`、`$.candidates[0].dayun.age_convention`、`$.candidates[0].dayun.steps[0].ganzhi`、`$.candidates[0].dayun.steps[0].start_year`、`$.candidates[0].dayun.steps[0].end_year` | 仅 dayun 非 null 时使用 |
| 稳定性 | `$.invariants` | 每字段分别比较，不能推为整盘稳定 |
| 流年（liunian） | `$.candidates[0].liunian.year`、`$.candidates[0].liunian.ganzhi`、`$.candidates[0].liunian.dayun` | 仅 liunian 返回；额外保存该份原始输出 |

原创建议规则 ID（分析协议标签，不冒充古籍条文编号）：

| school / rule_id | 检验内容 | 本地 corpus 查询 |
| --- | --- | --- |
| 扶抑 / bazi.strength.context | 月令、通根与助泄克并看 | `corpus search 通根 --book ditian --limit 3` |
| 格局 / bazi.pattern.conditions | 月令格局、成败救应 | `corpus search 用神 --book ziping --limit 3` |
| 调候 / bazi.climate.conditions | 日干月份寒暖燥湿条件 | `corpus search 甲木 --book qiongtong --limit 3`（按日干替换） |
| 病药 / bazi.remedy.countercase | 障碍与解除条件分别取证 | `corpus search 病药 --limit 3` |
| 十神 / bazi.relationship.context | 位置、透藏及结构条件 | `corpus search 正官 --book yuanhai --limit 3`（按主题替换） |
| 运限 / bazi.timing.conditional | 运限与本命条件叠加 | `corpus search 行运 --limit 3` |

先 `corpus books` 核对本地书籍 ID，若 ID 不存在则去掉 book 过滤；零命中报告缺证。
拿到结果后用 `corpus get ID` 核对来源、原文与邻文。保留 edition / license 等返回元数据。

---

Source: skills/ziwei/references/analysis.md

# 实际字段与规则索引

精确盘前缀为 `$`；约略盘前缀为 `$.branches[0]`（逐一替换索引）。下表用精确盘路径。
`palaces[0]` 是示例，先按实际 `name` / `earthlyBranch` 查索引，不能假设 index 0 是命宫。

| 用途 | 精确示例路径 | 注意 |
| --- | --- | --- |
| 元数据 | `$.engine.rules`、`$.warnings`、`$.input.时间精度` | 元数据始终在根；约略盘另有 `$.invariants` |
| 命身宫 | `$.renhuai.mingGongBranch`、`$.renhuai.shenGongBranch`、`$.renhuai.wuxingJuName` | 地支字段与数值索引不可混用 |
| 宫位 | `$.iztro.palaces[0].name`、`$.iztro.palaces[0].earthlyBranch`、`$.iztro.palaces[0].isBodyPalace` | 以实际宫名与地支定位 |
| 星曜 | `$.iztro.palaces[0].majorStars`、`$.iztro.palaces[0].minorStars`、`$.iztro.palaces[0].adjectiveStars` | 只引用实际存在的数组元素 |
| 四化 | `$.sihua` | 每条实际字段 star / transformation / branch；不要假定顺序 |
| 大限 | `$.daxian`、`$.iztro.palaces[0].decadal` | 记录范围和干支，不能假定当前大限 |
| 流年 | `$.annual` | 不传 year 时为 null；非 null 再读取 year/referenceDate/mingPalace |
| 格局候选 | `$.renhuai.patterns` | 仅规则命中，不自动成为人格或事件断言 |
| horoscope | `$.flows`、`$.target.date` | 单独的命令输出；约略盘 flows 在分支下 |

三方四正的可复现推导：地支序为 子丑寅卯辰巳午未申酉戌亥，目标支索引 i 对应 i、(i+4)%12、(i+8)%12、(i+6)%12。
在实际 `iztro.palaces` 内按地支定位，将参与判断的每宫字段路径写进 evidence。此推导不依赖数组宫位顺序。

| school / rule_id | 条件审核 | 本地 corpus 查询 |
| --- | --- | --- |
| 三合 / ziwei.soul-body.context | 命身宫及会照条件 | `corpus search 命宫 --limit 3` |
| 星曜 / ziwei.stars.context | 星曜所在宫及组合 | `corpus search 紫微 --limit 3`（换为实际星曜） |
| 四化 / ziwei.mutagen.layers | 生年与运限层级分别引用 | `corpus search 化忌 --limit 3`（换为实际四化） |
| 三合 / ziwei.trine-opposition | 四宫定位和会照，不机械评分 | `corpus search 三方 --limit 3` |
| 运限 / ziwei.timing.conditional | 大限、流年与本命对应 | `corpus search 大限 --limit 3` |

规则 ID 为本项目原创审核标签，非古籍编号。先 `corpus books` 确认可用版本，检索后 `corpus get ID` 核对段落及上下文。
经典检索可零命中；不得捏造引文。受限课程资料保持默认关闭；如本地有可用结果，保留其出处和许可，不默认用于可公开传播的报告。

---

Source: THIRD_PARTY_NOTICES.md

# Third-party notices

Prophet's original code is MIT (see LICENSE). Third-party components retain
their own terms. The MIT grant does not relicense dependencies or fetched texts.
The runtime is offline after setup. Setup uses ordinary git checkouts, pip,
npm and one ephemeris download; it does not download release assets or datasets.

| Source | Included or fetched | Licence and attribution |
| --- | --- | --- |
| [Renhuai123/ziwei-doushu](https://github.com/Renhuai123/ziwei-doushu), 495b79ecb3524b20b2edc026067d7d0b0f407319 | Code excerpts in eastern/ziwei/js/renhuai; checkout fetched into vendor | MIT; original LICENSE and NOTICE.md retained in excerpt directory. Adaptations documented there. |
| [ShousenZHANG/chinese-fortune](https://github.com/ShousenZHANG/chinese-fortune), 81a980a5707505468a10f596f1f19c9088457a9e | Excerpts in eastern/_cf; frozen shensha tables in eastern/_shensha.py; corpus/data/han-variants.json; checkout fetched | MIT for code and character map; eastern/_cf/LICENSE and NOTICE and corpus/data/chinese-fortune-LICENSE retain permission. Classical transcription licences are separate. |
| [adarshj322/dashaflow](https://github.com/adarshj322/dashaflow), f8f8ead76e56b9048f80adbbbff282c007068cf7 | Tables adapted in vedic/_tables.py; checkout fetched | MIT; attribution and original permission in vedic/_dashaflow/LICENSE and NOTICE. |
| [iztro](https://github.com/SylarLong/iztro) 2.6.1 | npm dependency, fetched; node_modules excluded | MIT; package licence retained by npm. Renhuai also uses iztro, so agreement between them is not independent validation. |
| [lunar-python](https://github.com/6tail/lunar-python) 1.4.8 / [lunar-javascript](https://github.com/6tail/lunar-javascript) | Python / npm dependencies, fetched | MIT; upstream 6tail copyright and package licences apply. npm versions are locked in package-lock.json. |
| [astronomy-engine](https://github.com/cosinekitty/astronomy) 2.1.19 | Python dependency, fetched | MIT; Don Cross and contributors; package licence applies. |
| [pyswisseph](https://github.com/astrorigin/pyswisseph) 2.10.3.2 / [Swiss Ephemeris](https://www.astro.com/swisseph/) | Dependency, not bundled | AGPL-3.0 or commercial Swiss Ephemeris licensing as applicable. Distributing a combined work that links pyswisseph is subject to AGPL obligations; Prophet's MIT licence does not remove these. A Swiss commercial licence does not automatically relicense the Python wrapper. Consult upstream terms for the chosen distribution. |
| [seas_18.se1](https://raw.githubusercontent.com/aloistr/swisseph/master/ephe/seas_18.se1) | Downloaded by scripts/setup.sh; excluded from release | Swiss Ephemeris licence (AGPL/commercial dual licensing); Astrodienst AG. See [upstream licence](https://github.com/aloistr/swisseph/blob/master/LICENSE). Optional at runtime; Chiron omitted with warning if absent. |
| A. E. Waite, The Pictorial Key to the Tarot (1910), Part III | Original keyword paraphrases in western/data/tarot_rws.json | Underlying 1910 text is public domain. No card artwork is bundled. Prophet's keyword compilation is covered by the project MIT licence. |
| Classical Chinese works via chinese-fortune and Renhuai classics selections | Fetched into vendor; normalised JSONL generated locally, not bundled | Historical works public domain; Wikisource transcriptions CC BY-SA 4.0 where applicable. Keep passage source URLs, edition, revision, licence, attribution and selection metadata. Modern editorial contributions may have separate rights; upstream selections are not critically collated editions. |
| 倪海厦《天纪》 via Renhuai123/ziwei-doushu | Opt-in normalisation only; never bundled | CC BY-NC-SA 4.0: credit 倪海厦 and rights successors, and Renhuai123/ziwei-doushu for structuring; NonCommercial; ShareAlike. Preserve upstream LICENSE.md, source links, and indicate retrieval-field changes. The checkout contains the source, but the default corpus build excludes it. |
| corpus/data/nakshatra.jsonl and parashara.jsonl | Bundled original concise summaries | CC0-1.0; Prophet contributors. Traditional rules summarised independently; no modern translation reproduced. |
| PyJHora | NOT used, copied or installed | Upstream is AGPL. The pyjhora-pvr profile is implemented independently from P.V.R. Narasimha Rao's book description, Vedic Astrology: An Integrated Approach; no PyJHora verification is claimed. |
| B. V. Raman, Graha and Bhava Balas | Numeric reference values cited in tests | Copyright remains with rights holders. No book text or scans bundled. Formula implementation and numeric comparison do not imply permission to redistribute the book. |

The npm lockfile also fetches these support packages; none are bundled in the
source release. Platform-specific packages are installed only where applicable.

| Package | Locked version | Licence (lockfile) |
| --- | --- | --- |
| @babel/runtime | 7.29.10 | MIT |
| @esbuild/aix-ppc64 | 0.28.2 | MIT |
| @esbuild/android-arm | 0.28.2 | MIT |
| @esbuild/android-arm64 | 0.28.2 | MIT |
| @esbuild/android-x64 | 0.28.2 | MIT |
| @esbuild/darwin-arm64 | 0.28.2 | MIT |
| @esbuild/darwin-x64 | 0.28.2 | MIT |
| @esbuild/freebsd-arm64 | 0.28.2 | MIT |
| @esbuild/freebsd-x64 | 0.28.2 | MIT |
| @esbuild/linux-arm | 0.28.2 | MIT |
| @esbuild/linux-arm64 | 0.28.2 | MIT |
| @esbuild/linux-ia32 | 0.28.2 | MIT |
| @esbuild/linux-loong64 | 0.28.2 | MIT |
| @esbuild/linux-mips64el | 0.28.2 | MIT |
| @esbuild/linux-ppc64 | 0.28.2 | MIT |
| @esbuild/linux-riscv64 | 0.28.2 | MIT |
| @esbuild/linux-s390x | 0.28.2 | MIT |
| @esbuild/linux-x64 | 0.28.2 | MIT |
| @esbuild/netbsd-arm64 | 0.28.2 | MIT |
| @esbuild/netbsd-x64 | 0.28.2 | MIT |
| @esbuild/openbsd-arm64 | 0.28.2 | MIT |
| @esbuild/openbsd-x64 | 0.28.2 | MIT |
| @esbuild/openharmony-arm64 | 0.28.2 | MIT |
| @esbuild/sunos-x64 | 0.28.2 | MIT |
| @esbuild/win32-arm64 | 0.28.2 | MIT |
| @esbuild/win32-ia32 | 0.28.2 | MIT |
| @esbuild/win32-x64 | 0.28.2 | MIT |
| dayjs | 1.11.23 | MIT |
| esbuild | 0.28.2 | MIT |
| fsevents | 2.3.3 | MIT |
| i18next | 23.16.8 | MIT |
| lunar-lite | 0.2.8 | MIT |
| lunar-typescript | 1.8.6 | MIT |
| tsx | 4.23.15 | MIT |

Python/npm build tooling is external to this source release. Keep dependency
licence files when packaging an installed environment or executable.

---

Source: SECURITY.md

# Security policy

## Supported versions

| Version | Security fixes |
| --- | --- |
| 0.2.x | Supported |
| 0.1.x | Upgrade to 0.2.x |
| Earlier releases | Unsupported |

## Reporting a vulnerability

Use [GitHub private vulnerability reporting](https://github.com/AstralumeLan/prophet-toolkit/security/advisories/new).
If the form is unavailable, open a minimal GitHub issue asking to enable private reporting;
do not include exploit details or sensitive data in that issue.

Describe the affected version, minimal fictional reproduction, impact, and suggested fix.
Never attach real birth records, private locations, credentials, caches, draw journals,
or personalized reports. Coordinate disclosure privately until a fix is available.
Maintainers will assess reports and coordinate a patch; there is no guaranteed response SLA.

## Scope

Reports may cover CLI input handling, local file access, subprocess bridges, MCP transport,
dependency setup, unsafe corpus processing, or unintended disclosure of local records.
Prophet runs offline after setup. MCP clients can invoke all exposed CLI commands,
including local record reads and explicit persistence; run clients only with trusted access.
The server provides no network listener or authentication boundary.

Incorrect astrology interpretations or predictions are not security vulnerabilities.
Report reproducible calculation errors using fictional/public charts through the bug form.
Third-party vulnerabilities should also be reported to the relevant upstream project;
keep their licence and disclosure requirements intact.