Horosa Agent

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:

Quickstart — 三步出 Word 报告

// 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。

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

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).
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.
• 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

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. 中式技法 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).

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.

• 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

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)

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)

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 — 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.