| name | horosa-agent |
| description | Call Horosa (星阙) local metaphysics tools correctly over MCP or CLI — 78 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.22.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). Detail lives in the reference sheets:
| Reference | Content |
|---|
references/payloads.md | Input payload defaults (event/birth JSON), coordinates, gender/timeAlg fields |
references/late-zi.md | 晚子时/日界 two-switch spec — canonical matrix, how to ask, status |
references/predictive.md | Predictive astrology minimum contracts (returns/progressions/PD), PD engine parity |
references/chinese-methods.md | 大六壬 defaults, current-time casting flow, 奇门法奇门 sections, 中式技法 notes |
references/reports.md | Report/memory workflow, one-command CLI report, interpretation style detail |
references/troubleshooting.md | Debug commands, openclaw setup/check, symptom table, cross-platform notes |
Quickstart — 三步出 Word 报告
horosa_cn_qimen {date, time, zone:"+08:00", lat:"31n13", lon:"121e28", agent_confirmed_settings:true, clarification_notes:"…"}
horosa_report_render {run_id, tool_name:"qimen", format:"docx", ai_report:{executive_summary, answer_text, analysis_sections, recommendations, limitations}}
省 token：技法工具可传 response_view:"titles"（只回段标题）或 "sections"；完整快照始终已存档（horosa_memory_show(run_id) 取回）。注意 horosa_report_from_tool 会重新起盘——已有 run_id 用 report_render。
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 (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
- Understand the user's question.
- Choose the smallest matching Horosa tool (table below).
- If required context or result-changing settings are missing, call
horosa_agent_guidance
(CLI: uv run horosa-skill agent guidance --tool <tool> --intent "...").
- Ask the user one concise clarification question with concrete options when settings are unclear.
- Normalize time, place, timezone, and question text.
- Call the tool.
- Read
export_snapshot.export_text, export_snapshot.sections, and summary.
- Explain the chart/pan directly in chat from those returned sections only.
- If the user wants a file, use the report tools (
references/reports.md).
- 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.
- Predictive targets:
datetime, dirLat / dirLon / dirZone, primary-direction method settings —
see 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; Hellenistic: hellen_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 |
| Harmonic 调波盘 | harmonic |
| 八字 | bazi_birth / bazi_direct |
| 紫微斗数 | 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 |
| 天文地占 geomancy | geomancy |
| 塔罗 tarot | tarot |
| 占星地图 ACG | acg |
| 名人库 celebrity data | astrodata (read-only, no confirmation gate) |
| Astrology dice 西占游戏 | otherbu |
| 14 神数 | wangji / wuzhao / taixuan / jingjue / shenyishu / shaozi / tieban / fendjing / beiji / nanji / chunzi / xianqin / cetian / qizhengkin |
| 节气 / 农历 | jieqi_year / nongli_time |
| 黄历 / 万年历 | calendar_month |
| Hover knowledge | knowledge_registry, knowledge_read |
| Export protocol | export_registry, export_parse |
| Natural-language dispatch | horosa_dispatch (MCP) |
Fengshui is intentionally excluded from this public skill surface (not headless-ready).
Payload shapes and defaults: references/payloads.md. 中式技法 specifics
(大六壬 guirengType, current-time casting, 法奇门 sections):
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.
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 (symptom table,
debug commands, stale-runtime signals like source: null).
Maintainer Pointer
Modifying/building/releasing this repo is governed by 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.
