🔮 Horosa Skill

把星阙（Horosa）的 89 个真实术数 / 占星技法，做成任何 AI 都能本地调用的 MCP server 与 CLI。
A local-first MCP server & CLI that exposes 89 real astrology / metaphysics techniques from Horosa (星阙) to any AI client.

简体中文 · English

克隆仓库、安装一次离线 runtime，Claude Code / Claude Desktop / Codex / Open WebUI / OpenClaw 等客户端即可通过 MCP 或 JSON-first CLI 直接调用真实的星阙方法：西洋本命 / 推运 / 卜卦 / 择日，八字 / 紫微 / 大六壬 / 奇门 / 太乙 / 金口诀 / 三式合一，六爻 / 塔罗 / 天文地占 / 小六壬 / 飞宫小奇门 / 小成图 / 皇极轨策 / 神数正传，以及全 14 路神数。

算法在本机运行，断网可用；每个技法返回统一 envelope 与星阙式导出结构；每次调用自动落成可检索的本地记录。与星阙桌面端共用同一套后端、逐值同源。

   🖥️  AI 客户端   Claude Code · Claude Desktop · Codex · Open WebUI · OpenClaw
        │
        │  MCP  /  JSON-first CLI
        ▼
   ┌──────────────────────────────────────────────────────────────┐
   │  🔮 Horosa Skill   本地进程 · 83 工具 · 澄清闸 · 统一 envelope │
   │  自然语言调度 · 逐技法直调 · 报告渲染 · 本地记忆检索           │
   └──────────────────────────────────────────────────────────────┘
        │  全部在本机 · 断网可用
        ▼
   ⚙️ 离线 runtime         🧩 headless JS 引擎     💾 本地存储
   Java+Python 星历        horosa-core-js          SQLite 全文索引
   ken / kentang 引擎      aiExport 结构化          + JSON artifact 归档

[!NOTE] 它不是又造一个简化占算器，而是把星阙已有的本地算法、星历与导出协议，整理成一层适合 GitHub 分发、适合 AI 调用、适合长期本地管理的接口。桌面端算出来是什么，这里就是什么。

📑 目录

• ✨ 核心特性
• 🚀 快速开始
• 🔌 接入 AI 客户端
• 🎯 一次调用的完整流程
• 🧭 技法总览
• 📐 输出契约
• 🚦 调用前的澄清闸
• 📂 本地记忆与报告
• 📦 安装与 runtime 策略
• ✅ 质量与验证
• 📚 文档
• 🙏 致谢与许可证

✨ 核心特性

• 🌌 89 个真实技法，一次安装，全程离线。 覆盖西洋占星全链路、中文术数主干、数算与卜法、全 14 路神数；算法在本机运行，不联网、不上传。
• 🧠 为 AI 消费而设计的稳定契约。 每次调用返回统一 envelope，接入导出协议的技法附带 export_snapshot（段结构化正文）。同一技法连续调用得到同一套字段，落库后结构不丢。
• 🛡️ 调用前的硬性澄清闸。 只要技法受时间 / 地点 / 时区 / 性别 / 事项 / 宫制 / 历法 / 起局方式影响，agent 在用户确认前会被结构化拦截，并收到可直接转发给用户的追问文本。
• 🪙 精简的响应体量。 导出契约单份化，同一份快照不再重复；大盘单次响应体量较早期显著下降。可用 response_view=titles|sections 仅取段标题或指定段，完整快照始终已归档。
• ⏳ 主限法可推至 3000 年。 逐位核验的核5方位法 + 22 项时间钥匙 + In Zodiaco / In Mundo + 宿命点(Vertex)应星 + 映点 / 界作迫星，多圈复发行。
• 🗄️ 完整的本地记录系统。 SQLite 全文检索（trigram，中文子串可命中）+ JSON artifact 归档；按人名 / 技法 / 日期区间 / 全文组合检索，跨会话找回历史。
• 📄 结构化报告导出。 一条命令生成 DOCX / PDF / JSON；Markdown 表格渲染为真 Word 表格，含导航大纲、目录、页码与中文字体。
• 🔁 成熟的安装与升级链。 断点续传、多镜像回退、实时进度；版本短路（已最新则跳过下载）；upgrade / uninstall / selfcheck / doctor 环境体检齐备。
• 🔗 同源后端。 奇门 / 太乙 / 金口诀走星阙 ken 后端；14 路神数走 chart 服务上挂载的 kentang 引擎；结果由 headless JS 层重排为 aiExport.js 段结构。

🚀 快速开始

[!TIP] 前置只需 uv（curl -LsSf https://astral.sh/uv/install.sh | sh）；Python ≥ 3.12 由 uv 自动准备；磁盘预留约 5 GB（runtime 下载约 730 MB、解压后约 2 GB）。

git clone https://github.com/Horace-Maxwell/horosa-skill.git
cd horosa-skill/horosa-skill
uv sync
uv run horosa-skill install      # 📦 安装离线 runtime（带进度 / 断点续传；已最新则跳过下载）
uv run horosa-skill doctor       # 🩺 环境体检（磁盘 / 端口 / node 实跑探针，期望 issues: []）
uv run horosa-skill selfcheck    # ✅ 活体验证：起一张盘 → 存 → 读回
uv run horosa-skill serve        # 🚀 启动本地 MCP（默认 http://127.0.0.1:8765/mcp）

🔌 接入 AI 客户端

一条命令生成带真实绝对路径的即用配置，无需手填占位符：

uv run horosa-skill client config --format claude-code      # 输出 claude mcp add … 命令
uv run horosa-skill client config --format claude-desktop   # Claude Desktop mcpServers 片段
uv run horosa-skill client config --format codex            # Codex config.toml 片段

[!TIP] 上下文预算受限的客户端可设 HOROSA_MCP_COMPACT=1，只暴露约 9 个门面工具（含按名直调的 horosa_tool_run 与 83 技法目录索引），澄清闸照常生效。根目录 server.json 为 MCP Registry 元数据，普通用户无需手改。

🎯 一次调用的完整流程

以「查今年事业，1995-06-03 05:30 上海出生」为例，agent 端的实际序列：

1️⃣  澄清闸兜底 —— 缺时区 / 宫制等结果敏感设置时，工具返回追问文本，
    agent 先向用户确认，而非自行补参
2️⃣  起盘       —— 确认后传 agent_confirmed_settings: true 调用技法工具，
    返回统一 envelope，含 memory_ref.run_id 与 data.export_snapshot
3️⃣  读盘       —— 读 export_snapshot.export_text / sections 撰写解读
    （想省 token 可传 response_view: "titles" 只取段标题，完整快照已归档）
4️⃣  出报告     —— report_render 生成 DOCX，传入的 ai_report 自动写回记忆
5️⃣  跨会话找回 —— memory_query 按人名 / 技法 / 日期检索，memory_show 取完整记录

[!NOTE] 最短路径为 2 次工具调用 + 1 次本地分析：起盘拿到 run_id，本地撰写 ai_report，再 report_render 出 Word 并自动归档。全程算法在本机、AI 只负责解读、结构永不丢。

🧭 技法总览

所有业务技法都返回统一 envelope 并附星阙式 export_snapshot。带 ⓟ 的工具受设置影响，调用前必须先确认参数。

[!NOTE] 明确排除项：fengshui（风水尚未完成 headless 化，不作为可发布能力）。

📐 输出契约

每个工具调用返回统一 envelope：

{
  "ok": true, "tool": "qimen", "version": "0.25.0",
  "input_normalized": {}, "data": {}, "summary": [],
  "warnings": [], "memory_ref": {}, "error": null
}

接入导出协议的技法额外带 data.export_snapshot，含 export_text（段结构化正文）、sections（逐段标题 + 正文 + 结构化数据）、selected_sections、provenance 等。因此 ——

• 🧷 AI 无需从自由文本猜结构；
• 🔁 同一技法连续调用得到同一套契约；
• 🧮 horosa_dispatch 汇总层显式带每个子结果的导出契约；
• 💾 落库到 JSON artifact 后结构不丢。

[!NOTE] 自 v0.21.0 起契约单份化，同一份快照不再重复存放；可传 response_view=titles|sections 仅返回段标题或段标题 + 正文，完整快照始终已归档，可用 memory_show(run_id) 取回。字段全表见 docs/DATA_CONTRACTS.md 与 docs/INPUT_CONTRACTS.md。

🚦 调用前的澄清闸

[!IMPORTANT] 只要技法受时间 / 地点 / 时区 / 性别 / 事项 / 宫制 / 历法 / 起局方式影响，agent 在用户确认前会被拦截，返回 agent_guidance.required 与可直接转发给用户的追问文本。杜绝「AI 自己脑补一个生辰就开算」。

// ❌ 被拦截：缺确认、地点、时区、事项
{ "date": "2026-05-18", "time": "13:14:00" }

// ✅ 通过：含用户确认 + 完整上下文
{
  "agent_confirmed_settings": true,
  "clarification_notes": "用户确认：2026-05-18 13:14:00，America/Los_Angeles，旧金山，事项为工作决策。",
  "date": "2026-05-18", "time": "13:14:00", "zone": "-07:00",
  "lat": "37n46", "lon": "122w25"
}

标准流程：用户说出需求 → 参数不足则查 horosa_agent_guidance 或直接询问 → 用户明确回答 → agent 传 agent_confirmed_settings: true + clarification_notes 调真实工具 → 用 export_snapshot 解释，不自行手算。时区可用 +08:00 固定偏移，也可用 Asia/Shanghai IANA 名（按起盘日期归一化）。

📂 本地记忆与报告

本地数据默认写入 ~/.horosa-skill/（Windows：%APPDATA%/HorosaSkill/）。每次 run 沉淀：run 元信息、tool call 记录、entity 索引、JSON artifact、run manifest、原始 query_text、用户问题、AI 最终回答与可选结构化回答。

• 🔎 SQLite 全文检索（trigram，中文子串可命中）+ 热路径索引 + WAL 并发；按人名 / 技法 / 日期区间 / 全文组合检索，支持分页。
• 📄 report_render 生成 DOCX / PDF / JSON：Markdown 表格渲染为真 Word 表格（跨页重复表头）、导航大纲、目录、页码、中文字体，异常自动降级保全文。

uv run horosa-skill memory query                 # 按 tool / entity / run_id / 全文 检索
uv run horosa-skill memory show <run_id>         # 精确回看某次完整调用

📦 安装与 runtime 策略

仓库分为三层，兼顾「代码仓库轻量、Release 资产完整、本地运行离线」：

奇门 / 太乙 / 金口诀（及三式合一中的奇门 + 太乙）走星阙 ken 后端；14 路神数走 chart 服务上挂载的 kentang 引擎；结果由 headless JS 层重排为 aiExport.js 段结构，与星阙桌面端逐值同源。配套阅读：Offline Runtime Releases · Runtime Manifest Spec · Repo Layout。

✅ 质量与验证

第一次 clone 后确认非空壳的最小验证：

cd horosa-skill && uv sync && uv run horosa-skill install
uv run horosa-skill doctor                              # 期望 issues: []
uv run pytest -q                                        # 326 passed
uv run python scripts/run_full_self_check.py --rounds 1 # 全工具调用 / 导出 / 落库 / 检索 / dispatch 汇总

[!WARNING] 审计推运 / 神数类工具时不要只看短预览——其正文通常先写本命盘再写返照 / 推运 / 流年 / 主限表格，只截前若干字符可能只看到本命盘。应打开完整 artifact，按 export_snapshot.sections 逐段检查。详见 docs/EXPORT_AUDIT_GUIDE.md。

📚 文档

🙏 致谢与许可证

奇门遁甲 / 太乙神数 / 金口诀（及三式合一中的奇门 + 太乙）的盘面，由 kentang2017 开源的三个 Python 引擎计算，随离线 runtime 一起分发：

• ✳️ kinqimen（奇门遁甲）— MIT — https://github.com/kentang2017/kinqimen
• ✳️ kintaiyi（太乙神数）— MIT — https://github.com/kentang2017/kintaiyi
• ✳️ kinjinkou（金口诀）— MIT — https://github.com/kentang2017/kinjinkou

上述三个 ken 引擎为第三方 MIT 组件。本仓库其余术数实现——统摄法、十年大运，以及奇门 / 太乙 / 金口 / 大六壬 / 星盘 / 推运 / 卜卦 / 择日 / 神数等的 aiExport.js 格式化与 headless 适配——均为星阙自有算法，按根目录 GNU AGPL-3.0-only 授权。传统术数体系本身（京房八宫、希腊十年星限等）属公共知识，不构成第三方版权。