---
name: horosa-agent
description: >-
  Call Horosa (星阙) local metaphysics tools correctly over MCP or CLI — 106 real techniques: Western
  natal/predictive astrology (returns, progressions, primary directions, horary 卜卦, election 择日),
  八字, 紫微, 大六壬, 奇门遁甲, 太乙, 金口诀, 三式合一, 河洛理数, 邵子参评数, 六爻, 天文地占, 塔罗, and
  the full 14 神数. Use whenever a user asks to 起盘 / 排盘 / 起课 / 起卦 / 算命 / 推运 / 看盘 / 合盘 /
  卜卦 / 择日 or requests any Horosa/星阙 chart, reading, report, or stored run — and when debugging a
  user-facing Horosa result. Enforces the clarify-before-call gate and the export-snapshot reading
  contract; never hand-calculate these methods.
license: AGPL-3.0-only
compatibility: Requires the local Horosa Skill MCP server/CLI (Python 3.12 + uv + installed offline runtime)
metadata:
  version: "0.38.0"
---

# Horosa Skill Agent Guide

Use this guide when an AI agent is connected to Horosa Skill through MCP, CLI, Cursor, Claude, Codex,
OpenClaw, Open WebUI, or another local-first client and needs to call Horosa metaphysics tools,
generate reports, store memory, or debug user-facing results.

This file is the **single policy source for AI-client behaviour** (repo rules & maintainer law live in
[`AGENTS.md`](../../AGENTS.md)). Detail lives in the reference sheets:

| Reference | Content |
| --- | --- |
| [`references/payloads.md`](./references/payloads.md) | Input payload defaults (event/birth JSON), coordinates, gender/timeAlg fields |
| [`references/late-zi.md`](./references/late-zi.md) | 晚子时/日界 two-switch spec — canonical matrix, how to ask, status |
| [`references/predictive.md`](./references/predictive.md) | Predictive astrology minimum contracts (returns/progressions/PD), PD engine parity |
| [`references/chinese-methods.md`](./references/chinese-methods.md) | 大六壬 defaults, current-time casting flow, 奇门法奇门 sections, 中式技法 notes |
| [`references/reports.md`](./references/reports.md) | Report/memory workflow, one-command CLI report, interpretation style detail |
| [`references/troubleshooting.md`](./references/troubleshooting.md) | Debug commands, openclaw setup/check, symptom table, cross-platform notes |

## Quickstart — 三步出 Word 报告

```jsonc
// 1) 起盘（确认设置后）——返回 memory_ref.run_id
horosa_cn_qimen {date, time, zone:"+08:00", lat:"31n13", lon:"121e28", agent_confirmed_settings:true, clarification_notes:"…"}
// 2) 读 data.export_snapshot.export_text / sections 写出你的解读（ai_report 各字段）
// 3) 渲染 —— ai_report 自动写回记忆，无需再调 memory_record_answer
horosa_report_render {run_id, tool_name:"qimen", format:"docx", ai_report:{executive_summary, answer_text, analysis_sections, recommendations, limitations}}
```

七政四余 `guolao_chart` 可传 `guolaoLifeMode`（asc/yumao/cotrans）、`guolaoBodyMode`、`moiraTransitDate`（[流年流曜]
的流年时刻，缺省今天）；[虚实]/[本命化曜]/[流年流曜] 三段来自 Java 规则层，Java 不可用时缺席并进 `warnings`。
河洛 `heluo` 可传 `liunianStep2`（ying/sequential）、`ziShuMode`、`jiGongMode` 等取法旋钮（全表见 guidance）。
只知道四柱不知道生日：`bazi_inverse {pillars:["甲子","丙寅","戊辰","庚申"], fromYear, count}` 反查候选出生时刻
（免确认门，候选每 60 年重现，请让用户确认年代）。八字口诀层：`knowledge_read {domain:"bazi_pithy", category:"三字诀", key:"甲"}`
或 `query` 全文检索（21 类 173 条，引必带出处）。

闸门问题带 `options` 的，直接把用户选的那一项原话记进 `clarification_notes`（同名 `values` 是该选项对应的
schema 值，可直接放进载荷）；`planetaryarc` 的弧源、神数的性别/地点这类工具自有敏感项闸门会点名问，别替用户默认。

找工具：每个工具描述带 `aka:` 别名（中文口语/拼音/英文）；不确定就 `horosa_dispatch`（路由覆盖全部技法，
含 8 个择日搜索）或 `horosa_agent_guidance`（响应里的 `server_profile` 告诉你本进程实际平铺了哪些域、
`HOROSA_TOOLSETS` 有没有拼错、`horosa_tool_run` 在不在）。

tools/list 只广告每个工具的域核心字段 + 自有字段；BirthInput 长尾旋钮（`orbSystem`/`extraBodies`/`termsVariant`…）
**顶层按名直接传即可、不会被丢**，全表用 `horosa_agent_guidance(tool_name=…)` 查（v0.36.0 两层 schema）。

省 token：技法工具可传 `response_view:"titles"`（只回段标题）或 `"sections"`；完整快照始终已存档（`horosa_memory_show(run_id)` 取回）。`export_snapshot.sections[*]` 只含 `body`；机读数据在 `data.<key>`（`data.pan` / `data.chart` / `data.liureng` …）只出现一次，别去段里找。注意 `horosa_report_from_tool` 会重新起盘——已有 run_id 用 `report_render`。

出错时看 `details.agent_recovery`：`kind` 说谁能修（input=问用户/修入参、retry_or_doctor=重试一次再让用户跑
`uv run horosa-skill doctor`、runtime/js_engine=装 runtime 或设 HOROSA_NODE_BIN），`next_action` 是机器可读的下一步，
`prompt_to_user` 双语可直接转述；不要把 `ok:false` 当成「该技法没有此项」。

**`warnings` 非空 = 结果不完整**（`ok` 仍为 true）：「降级：…」是某个子引擎/可选后端本次失败、对应段缺席；
「结果不完整：预设 N 段中 M 段未产出」列出缺了哪些段。报告里必须如实转述，不得把缺席的段当成「该技法没有此项」，
也不得自行补算；dispatch 的 `warnings` 只汇总哪些工具带说明，细节在 `results.<tool>.warnings`。

**每次给出结论后，把 `data.technique_card` 原样转述成一段技法尾注**（技法 / 口径 / 算源 / 段落 / 版本）——
它是确定性元数据，`response_view` 精简时也在。要文件就调 `horosa_technique_report`（`run_id` 单次、
`group_id` 整场，后者还会检出跨技法口径冲突）。细则与两种报告的分界：[`references/reports.md`](./references/reports.md)。

## Core Rule

Horosa Skill is **local-first**. After `horosa-skill install`, algorithms run through the local
runtime, local headless JS engines, and local storage. Do not tell users that a missing field requires
MongoDB, port 7897, Xingque Desktop, a remote database, or an external service unless a current
`doctor` / `openclaw-check` result explicitly says so. If output is missing, describe it as a local
tool/result/input issue and suggest a concrete recheck.

If the client exposes native Horosa MCP tools (`horosa_cn_qimen`, `horosa_cn_liureng_gods`,
`horosa_astro_chart`, `horosa_agent_guidance`, `horosa_memory_show`, `horosa_report_render`, …), call
them directly. If the trace shows `clientToolCount: 0` or no `horosa_*` tools, the MCP server was not
attached — stop and follow [`references/troubleshooting.md`](./references/troubleshooting.md) (openclaw
setup/check). CLI fallback is a diagnostic only, and must use the exact `HOME`, `HOROSA_RUNTIME_ROOT`,
`HOROSA_SKILL_DATA_DIR` env block from the generated mcporter config.

**Never hand-calculate Horosa techniques** with `Exec`, shell, Python, JavaScript snippets, web search,
or memory-only formulas. If the user asks for a pan/result, call the Horosa MCP or CLI tool and treat
the returned `export_snapshot` as the source of truth. Manual scripts bypass input normalization,
true-solar-time and timezone handling, Xingque-compatible defaults, runtime parity fixes, memory, and
reports — they will disagree with 星阙 and there will be no way to tell why.

## Preferred Agent Workflow

1. Understand the user's question.
2. Choose the smallest matching Horosa tool (table below).
3. If required context or result-changing settings are missing, call `horosa_agent_guidance`
   (CLI: `uv run horosa-skill agent guidance --tool <tool> --intent "..."`).
4. Ask the user one concise clarification question with concrete options when settings are unclear.
5. Normalize time, place, timezone, and question text.
6. Call the tool.
7. Read `export_snapshot.export_text`, `export_snapshot.sections`, and `summary`.
8. Explain the chart/pan directly in chat from those returned sections only.
9. If the user wants a file, use the report tools ([`references/reports.md`](./references/reports.md)).
10. For follow-ups, retrieve prior runs and AI answers with the memory tools.

## Clarification Rule (hard gate)

**If the user omitted a setting that changes the result, ask before calling.** Do not silently pick a
value just because the schema has a default. Ask when these are missing:

- Time/date/timezone/place for birth/event methods.
- Gender for Ziwei, Bazi direct/luck flow, LiuReng runyear, or any gender-sensitive report.
- House system / zodiacal (tropical vs sidereal ayanāṃśa) / traditional settings for astrology charts
  when the user cares about chart style.
- Qimen 起局方式、命式性别、拆补/置闰/茅山 method settings when the user expects a non-default pan.
- LiuReng 贵人体系 and 昼夜贵人 if the user does not accept Xingque defaults; Jinkou 地分 and 贵人体系.
- SixYao lines, gua code, or 起卦方式.
- 晚子时/日界 switches when the time is in `[23:00, 24:00)` — see
  [`references/late-zi.md`](./references/late-zi.md).
- Predictive targets: `datetime`, `dirLat` / `dirLon` / `dirZone`, primary-direction method settings —
  see [`references/predictive.md`](./references/predictive.md).
- Report format and whether AI analysis text is ready.

Allowed shortcuts:

- User says “当前时间” → use current local date/time/timezone.
- User says “按星阙默认 / 默认 / 快速起盘 / 你来决定” → use documented safe defaults and say so.
- A stored memory run already contains the setting → reuse it and cite the run.

Runtime enforcement (the gate is in code, not just policy):

- Calculation tools and `horosa_dispatch` reject unconfirmed calls with `agent_guidance.required`.
- After the user answers, include `agent_confirmed_settings: true`. If the user explicitly accepts
  defaults, include `defaults_accepted: true`. Add `clarification_notes` summarizing what was confirmed
  (e.g. `"user accepted Xingque defaults for guirengType and automatic day/night noble-person"`).
- If a response carries `details.agent_recovery`, stop and ask the user with
  `details.agent_recovery.prompt_to_user`. Do not retry the same tool, and do not call another
  calculation tool as a workaround, until the user answers or accepts defaults.
- **Never set `agent_confirmed_settings: true` yourself without a real user answer.**

## Do Not Hallucinate Dependencies

Never say: “大六壬 needs MongoDB” / “四课三传 require port 7897” / “you must install Xingque Desktop” /
“this tool needs a remote database or external service”.

Instead say: “This local run did not return that section — I'll rely on the returned sections, or we
can rerun `doctor` / `openclaw-check`.” / “The export contract shows the available sections; I won't
invent missing data.” / “Please provide the missing birth/event time, location, timezone, gender, or
question context.”

## Tool Selection

| User intent | Tool |
| --- | --- |
| Natal chart 标准星盘 | `chart` (13-house: `chart13`; 12th-harmonic/Dwadasamsa: `chart12`; Hellenistic: `hellen_chart`) |
| 老黄历 / 通书择日 | `huangli` (day almanac) · `tongshu` (needs `school` — the five schools can disagree outright on the same day) |
| 巴比伦占星 Babylonian | `babylon` (no houses/aspects/Asc by design — the reading device is the bīt niṣirti triplicity + planetary numina) |
| Draconic / Relocation 衍生盘 | `draconic` (node-zeroed) · `relocation` (needs `relocLat`/`relocLon` — without them it degenerates to the natal chart) |
| 古典占星 dignities reading (v2.6.7) | no separate tool — `chart`/`chart13`/`hellen_chart` exports carry `[古典]` + `[古典格局]` automatically; `india_chart`/`mundane` carry `[古典]` only |
| Qizheng Siyi / 七政四余 | `guolao_chart` |
| Indian chart 印度盘 | `india_chart` |
| Relationship 合盘 | `relative` |
| Midpoint/Uranian 中点盘 | `germany` |
| Solar/lunar return 返照 | `solarreturn` / `lunarreturn` |
| Solar arc / given year / profection | `solararc` / `givenyear` / `profection` |
| Primary directions 主限法 | `pd`, `pdchart` (see `references/predictive.md` for the v12 engine surface) |
| Zodiacal releasing / Firdaria / Decennials | `zr` / `firdaria` / `decennials` |
| Age point / distributions / mundane ingress | `agepoint` / `distributions` / `mundane` (year + 入宫节气 + place) |
| Triplicity rulers / keypoints / lunation phase / extra returns | `triplicityrulers` / `keypoints` / `lunationphase` / `extrareturns` |
| More progressions (v2.5.0) | `jaynesprog` / `vedicprog` / `planetaryarc` / `planetaryages` / `balbillus` / `yearsystem129` / `persiandirected` |
| Horary 卜卦 / Election 择日 | `horary` / `election` |
| 择日「找日子」——要在一段时间里搜时刻，而不是评一个候选时刻 | 西占征象 → `tianxing`（`explainAt` 可对单时刻逐叶判读）；奇门 → `qimenzeri`；另有择日十技法的其余八支：黄历 `huanglizeri`（日粒度）/ 八字 `bazizeri` / 太乙 `taiyizeri` / 紫微 `ziweizeri` / 六壬 `liurengzeri` / 三式合一 `sanshizeri`（条件可跨三式）/ 七政 `qizhengzeri` / 印度 Muhurta `indiazeri`。全部要 startDate/endDate + conditions 条件树；条件类键见各工具 agent_guidance（引擎自带词表，别自己编）；单点评估仍用 `election` |
| 七政择日动盘（十一曜山位 / 日月食 / 方位到达） | `qizhengelection`（action: pan / eclipses / azimuthsearch；date/time 是候选时刻非出生盘） |
| 生时校正（出生时间不确定） | `india_rectify`（KP 法锚点±半窗扫描；输出证据与排序，采用与否由用户决定） |
| Harmonic 调波盘 | `harmonic` |
| 八字 | `bazi_birth` / `bazi_direct` / `bazi_inverse`（四柱干支反查候选出生时刻，free of the confirmation gate） |
| 紫微斗数 | `ziwei_birth` (`ziwei_rules` returns the rules library) |
| 大六壬 / 行年 | `liureng_gods` / `liureng_runyear` |
| 奇门遁甲 / 太乙 / 金口诀 / 三式合一 | `qimen` / `taiyi` / `jinkou` / `sanshiunited` |
| 统摄法 | `tongshefa` |
| 邵子参评数 / 河洛理数 | `canping` / `heluo` |
| 六爻 | `sixyao` |
| 卦义 | `gua_desc`, `gua_meiyi` |
| 宿占 | `suzhan` |
| 一掌经 | `yizhangjing` |
| 神数正传（铁板 / 邵子 / 大定 / 六亲 / 铁算心易） | `zhengchuan`（school 选流派；除铁算心易外需生辰） |
| 小六壬 | `xiaoliuren`（三数或占时起课，冻结值；改流派只重排） |
| 飞宫小奇门 | `feigong`（起支+日干支定局，冻结值；占时可起） |
| 小成图 | `xiaochengtu`（手动/两数/股价/大衍/占时，大衍须显式 seed，卦为冻结值） |
| 皇极轨策 | `guice`（十二法起卦，冻结值；十开关流派只重排断法） |
| 天文地占 geomancy | `geomancy` |
| 塔罗 tarot | `tarot` |
| 灵棋经 lingqi | `lingqi`（以起卦时刻确定性掷十二棋；给了 counts 就复排，绝不重掷） |
| 占星地图 ACG | `acg`（clickLat/clickLon 加落点分析段；eventKind 加世运事件时刻段） |
| 行星周期（木土合 / 土冥…任意两星合冲时间轴） | `planet_cycles`（无出生盘概念；星对与年区间仍需确认） |
| 名人库 celebrity data | `astrodata` (read-only, no confirmation gate) |
| 玄史知识库 Esoteric-history KB | `xuanshi` (action: search / events / event / celestial / figures / dynasty / timeline / graph …; read-only, no result-sensitive settings) |
| Astrology dice 西占游戏 | `otherbu` |
| 14 神数 | `wangji` / `wuzhao` / `taixuan` / `jingjue` / `shenyishu` / `shaozi` / `tieban` / `fendjing` / `beiji` / `nanji` / `chunzi` / `xianqin` / `cetian` / `qizhengkin` |
| 节气 / 农历 | `jieqi_year` / `nongli_time` |
| 出生节气窗（八字起运窗同源） | `jieqi_birth` |
| 黄历 / 万年历 | `calendar_month` |
| Hover knowledge + 方法论手册 | `knowledge_registry`, `knowledge_read`（24 域 = hover 三域 + 各技法操作手册域，逐条带出处；传 `query` 即跨域全文检索） |
| Export protocol | `export_registry`, `export_parse` |
| Natural-language dispatch | `horosa_dispatch` (MCP) |
| 合参（多技法交叉印证） | `horosa_hecan`（模板制：结论槽留白，分歧必须披露；细则见 [`references/reports.md`](./references/reports.md)） |

Fengshui is intentionally excluded from this public skill surface (not headless-ready).

**引知识必带出处（v0.28.0 反 Barnum 第一机制）**：解读中引用口径/流派/教义时，先用
`knowledge_read` 取条目并转述其 `citation`（形如「星阙操作手册 · 八字四柱 · 算法与口径」）；
不知道条目在哪个域时，先 `knowledge_read {"query": "晚子时"}` 跨 24 域全文检索（v0.32.0）——
命中自带 citation 与可直接回读的 (domain, category, key) 坐标，再精读引用；
`knowledge_read` 没有的内容按通则推理并**明说无出处**。不许把通则包装成「古籍说」「星阙口径」。

Payload shapes and defaults: [`references/payloads.md`](./references/payloads.md). 中式技法 specifics
(大六壬 guirengType, current-time casting, 法奇门 sections):
[`references/chinese-methods.md`](./references/chinese-methods.md).

## Interpretation Style

Answer like a careful consultant: start with the direct conclusion; cite the actual chart/pan sections
that support it; explain the reasoning path in human language; separate opportunity, risk, timing, and
suggested action; with no specific question give a comprehensive overall reading, with a specific
question prioritize it over textbook generalities; mention limitations without hiding behind them.
Quote the `排盘规则: …` line back to the user when present (see `references/late-zi.md`). Report-body
style rules: [`references/reports.md`](./references/reports.md).

## Validation Checklist

Before telling the user a result is ready:

- `ok` is `true`; a failed tool returns `ok=False` with an `error.code` (e.g. `tool.internal_error`,
  `tool.ken_compute_failed`) — it does not throw. Read and relay the error; a failure is not
  “the tool is unavailable”.
- `export_snapshot.export_text` present (calculation tools); `export_snapshot.sections` non-empty;
  no section body is a bare `"无"`.
- The answer contains no dependency hallucinations (MongoDB, 7897, Xingque Desktop, remote DB).
- If a report was generated: the artifact path exists with non-zero size.
- If memory was used: `memory_show` / `memory_query` can retrieve the run.

Anything off → [`references/troubleshooting.md`](./references/troubleshooting.md) (symptom table,
debug commands, stale-runtime signals like `source: null`).

## Shell-only agents (no MCP)

An agent that can run commands but cannot mount an MCP server (CI bots, `codex exec` without MCP, plain
shell tools) gets the same contract through the CLI. **stdout is always exactly one JSON document**;
progress lines and error envelopes go to stderr, so parse stdout only.

| Need | Command |
| --- | --- |
| Tool names, `aka:` aliases, input fields | `horosa-skill tool list` |
| What must be confirmed before a call | `horosa-skill agent guidance --tool qimen --intent "签约择时"` |
| Run one technique | `horosa-skill tool run qimen --input payload.json --output result.json` |
| Natural-language routing (several techniques) | `horosa-skill dispatch --input query.json --output result.json` |
| Re-read a stored run | `horosa-skill memory show <run_id>` |
| Health / live check | `horosa-skill doctor` · `horosa-skill selfcheck` |

- Payload files are UTF-8 JSON objects (`{"date": "2028-04-06", "time": "09:33:00", "zone": "+08:00", "lat": "31n13",
  "lon": "121e28", …}`). `--stdin` also works on macOS/Linux; on **Windows PowerShell 5.1 use `--input` / `--output`
  files** — the pipe re-encodes bytes through the console code page and mangles Chinese in both directions.
- Exit code 0 = an envelope was written: check `ok`; a failed technique is `ok: false` + `error.code`, not an
  exception and not "the technique has no such item". Exit code 2 = rejected before running (the clarification
  gate, a malformed payload, a runtime error) — the stderr JSON carries `code` / `message` / `details`.
- Gate flow: stderr `code: "agent_guidance.required"` → show `details.agent_recovery.prompt_to_user` to the user,
  then rerun with `agent_confirmed_settings: true` + `clarification_notes` (or `defaults_accepted: true` only when
  the user explicitly accepts defaults) added to the payload. Never set the flag without a real answer.
- Envelope keys: `ok`, `tool`, `version`, `input_normalized`, `data` (`export_snapshot`, `technique_card`, the engine
  object once under `data.<key>`), `summary`, `warnings` (non-empty = incomplete result), `memory_ref` (`run_id`),
  `error`. `dispatch` wraps per-tool envelopes under `results.<tool>`.
- Everything above still holds: never hand-calculate, explain only from `export_snapshot.export_text`, quote
  `data.technique_card` after the answer.

## First 3 commands on a fresh machine

Each block: get `uv` → one-command onboarding (installs the offline runtime, writes the client config, then starts
the server once over stdio with the exact command the client will run) → live check. Replace `cursor` with the
client at hand (`claude-code` / `claude-desktop` / `vscode` / `codex` / `gemini` / `windsurf` / `cline` / `zed`).

**macOS (zsh), no checkout**

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
uvx --from "https://github.com/Horace-Maxwell/horosa-skill/releases/download/v0.38.0/horosa_skill-0.38.0-py3-none-any.whl" horosa-skill setup --client cursor
uvx --from "https://github.com/Horace-Maxwell/horosa-skill/releases/download/v0.38.0/horosa_skill-0.38.0-py3-none-any.whl" horosa-skill selfcheck
```

**Windows (PowerShell)**

```powershell
irm https://astral.sh/uv/install.ps1 | iex
uvx --from "https://github.com/Horace-Maxwell/horosa-skill/releases/download/v0.38.0/horosa_skill-0.38.0-py3-none-any.whl" horosa-skill setup --client cursor
uvx --from "https://github.com/Horace-Maxwell/horosa-skill/releases/download/v0.38.0/horosa_skill-0.38.0-py3-none-any.whl" horosa-skill selfcheck
```

**Source checkout (any OS)**

```bash
git clone https://github.com/Horace-Maxwell/horosa-skill && cd horosa-skill/horosa-skill && uv sync
uv run horosa-skill setup --client cursor
uv run horosa-skill selfcheck
```

`setup` is idempotent (re-run after an upgrade), `--dry-run` prints the plan with zero side effects, and a failure
is a stderr JSON with `step` / `code` / `config_untouched` / `retry_command` (exit 2). No github.com access:
`HOROSA_RUNTIME_MIRROR=<mirror prefix>` in front of the same commands, or `setup --archive <local runtime archive>`
— see `docs/INSTALL_RESTRICTED_NETWORK.md`. Windows on ARM installs the x64 payload under emulation automatically;
Intel Macs and Linux have no payload (gateway mode via `HOROSA_SERVER_ROOT` / `HOROSA_CHART_SERVER_ROOT`).

## Maintainer Pointer

Modifying/building/releasing this repo is governed by [`AGENTS.md`](../../AGENTS.md) — routing (§0),
iron laws (§1), and the **🔴 problem-logging protocol v2 (§2)**: every gotcha lands in
`docs/LESSONS.md` + a distilled rule + `CHANGELOG.md` + a machine guard, in the same change; sync this
skill doc whenever a lesson is client-facing, and never leave the two contradicting. Engine credit:
the ken engines (`kinqimen` / `kintaiyi` / `kinjinkou`, MIT, by **kentang2017**) ship their LICENSE
files inside the runtime and are acknowledged in `README.md` / `README_EN.md` — see AGENTS.md §11.