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}}

报告 output_path 可省（写到报告输出目录的缺省产物路径）；给了则相对路径按输出目录解析，绝对路径必须在输出目录或 HOROSA_REPORT_OUTPUT_ROOTS 白名单目录内，越界返回 report.output_path_not_allowed 且不写文件——别替用户猜别的目录。

七政四余 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（路由覆盖全部技法， 含 10 个择日窗口搜索：tianxing + 9 支 *zeri）或 horosa_agent_guidance（响应里的 server_profile 告诉你本进程实际平铺了哪些域、 HOROSA_TOOLSETS 有没有拼错、horosa_tool_run 在不在）。HOROSA_TOOLSETS 的合法域 = astro / predict / chart / cn / shenshu / other / export / knowledge，别名 western / chinese / reference / all / none；认不出的词会被丢掉并进 warning。

精简面（HOROSA_MCP_COMPACT=1，11 个门面级工具 = 10 门面 + horosa_tool_run）：Cursor / VS Code / Codex / Gemini / Devin Desktop（原 Windsurf）/ Cline / Zed 默认拿到它（setup --surface full|compact 可改；Claude Code / Claude Desktop 默认全量 120）。horosa_tool_run(tool_name=<注册键>, …) 接受与平铺工具完全相同的载荷与闸门字段；tool_name 不认识时返回按域分组的 details.catalog，不要据此说「没有这个技法」。

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）、transport（冷启动 ≤ ~45 s，等几秒重试一次）、runtime / js_engine（装 runtime 或设 HOROSA_NODE_BIN）、 environment（本机环境：PATH / 编码 / 端口）、decision_layer（云端决策层不可用 = 已本地兜底）；next_action 是机器可读的下一步， prompt_to_user 双语可直接转述；不要把 ok:false 当成「该技法没有此项」。几条要记住的码：runtime.starting → 按 retry_after_seconds （5 s）原样重试同一调用，三次后 horosa-skill runtime status；runtime.java_backend_unavailable → 只影响农历/八字/紫微/六壬族，chart 族照常， 冷却后再试；runtime.platform_unsupported → Linux / Intel Mac 没有离线载荷，走网关模式（HOROSA_SERVER_ROOT / HOROSA_CHART_SERVER_ROOT 指向一台受支持的机器）；runtime.path_not_ascii → Windows 的 runtime 根必须纯 ASCII（setx HOROSA_RUNTIME_ROOT C:\horosa 后重装）； runtime.stop_refused_clients_attached / stop_refused_foreign → 另一个客户端或用户的桌面端还挂在服务上，不要自作主张加 --force。

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

Optional Cloud Decision Layer (HOROSA_JEV)

Horosa can optionally consult TypeSafe Jev — a cloud "System One" decision model — for three narrow decisions: routing a request nobody's keyword matched, extracting a setting the user explicitly stated (e.g. 「我老婆的八字」→ gender female), and classifying a 大六壬 question's topic. It is off by default; when off, nothing leaves the machine and no response carries any of the fields below. When the operator turns it on:

• Every affected result self-reports it: data.technique_card.decisions[] (per technique run) and DispatchEnvelope.decision_layer (dispatch). Tell the user, once per answer, that the cloud decision layer was consulted, and quote what it decided and whether it was adopted (adopted / reason).
• mode: shadow means it only recorded what it would have decided — behaviour is unchanged.
• Jev never computes charts and never explains them. Its confidence is distribution concentration, not correctness — do not present it as certainty about the user's life.
• The clarification gate is unchanged: a value the user did not state is still asked for. If the user disputes an extracted value (decision.field / value / evidence), re-run with the corrected input.
• If a warning says the decision layer was unavailable, the deterministic path ran instead; no action needed.
• Which surfaces may actually change behaviour is decided by a measured thresholds lock (contracts/jev_thresholds.json): as of v0.39.0 routing fallback and 六壬 topic classification are promoted; gender extraction is still shadow-only (recorded, never filled).

Disclosure when the cloud decision layer is on: the default scope meta sends only the de-identified question text; under HOROSA_JEV_SCOPE=snapshot export-snapshot text leaves the machine — say so to the user before relying on it. jev.* warnings mean the deterministic local fallback answered; horosa-skill jev status shows the state. Never echo HOROSA_JEV_API_KEY (plugin jevApiKey).