Horosa Skill

🔮 Horosa Skill

把星阙（Horosa）的 114 个真实术数 / 占星技法，做成任何 AI 都能本地调用的 MCP server 与 CLI。

A local-first MCP server & CLI that exposes 114 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 与星阙式导出结构，并附一张确定性的技法依据卡；每次调用自动落成可检索的本地记录。与星阙桌面端共用同一套后端、逐值同源（导出契约 v16 镜像桌面端 aiExport v60，星阙 v3.11.3）。

   🖥️  AI 客户端   Claude Code · Claude Desktop · Codex · Open WebUI · OpenClaw

│ │ MCP / JSON-first CLI ▼ ┌──────────────────────────────────────────────────────────────┐ │ 🔮 Horosa Skill 本地进程 · 114 工具 · 澄清闸 · 统一 envelope │ │ 自然语言调度 · 多技法合参 · 技法依据卡 · 报告渲染 · 记忆检索 │ └──────────────────────────────────────────────────────────────┘ │ 全部在本机 · 断网可用 ▼ ⚙️ 离线 runtime 🧩 headless JS 引擎 💾 本地存储 Java+Python 星历 horosa-core-js SQLite 全文索引 ken / kentang 引擎 aiExport 结构化 + JSON artifact 归档

[!NOTE]

它不是又造一个简化占算器，而是把星阙已有的本地算法、星历与导出协议，整理成一层适合 GitHub 分发、适合 AI 调用、适合长期本地管理的接口。桌面端算出来是什么，这里就是什么——而且每个结论都能回答「这盘怎么来的」。

📑 目录

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

✨ 核心特性

• 🌌 114 个真实技法，一次安装，全程离线。 覆盖西洋占星全链路、中文术数主干、数算与卜法、全 14 路神数；算法在本机运行，不联网、不上传。
• 🧠 为 AI 消费而设计的稳定契约。 每次调用返回统一 envelope，接入导出协议的技法附带 export_snapshot（段结构化正文）。同一技法连续调用得到同一套字段，落库后结构不丢。
• 🛡️ 调用前的硬性澄清闸。 只要技法受时间 / 地点 / 时区 / 性别 / 事项 / 宫制 / 历法 / 起局方式影响，agent 在用户确认前会被结构化拦截，并收到可直接转发给用户的追问文本。
• 🧾 每个结论可溯源。 响应自带技法依据卡（技法 / 流派口径 / 谁算的 / 段落全不全 / 版本链），horosa_technique_report 一键出方法报告，会话级自动检出跨技法口径冲突。
• 📚 31 域方法论知识库，引必带出处。 星阙 app 内 hover 知识三域 + 27 份技法操作手册 + 八字断语库（21 类口诀）共 416 条，逐条带上游文件与版本出处；没有出处的解读必须明说是通则推理。
• 🧪 盘面事实忠实性评测。 确定性校验器把 AI 解读逐句对盘面机读真值，判 supported / invented / contradicted；喂错盘与诱导复述判红；106 条基准用例与工具注册表锁步。
• 🔀 一问多技法合参。 horosa_hecan 并行起盘 + 合参模板：每条结论必须绑定真实段落，收敛与分歧分开填，分歧必须披露、不许平均。
• 🪙 精简的响应体量。 导出契约单份化，同一份快照不再重复；大盘单次响应体量较早期显著下降。可用 response_view=titles|sections 仅取段标题或指定段，完整快照始终已归档。
• ⏳ 主限法可推至 3000 年。 逐位核验的核5方位法 + 22 项时间钥匙 + In Zodiaco / In Mundo + 宿命点(Vertex)应星 + 映点 / 界作迫星，多圈复发行。
• 🗄️ 完整的本地记录系统。 SQLite 全文检索（trigram，中文子串可命中）+ JSON artifact 归档；按人名 / 技法 / 日期区间 / 全文组合检索，跨会话找回历史。
• 📄 结构化报告导出。 一条命令生成 DOCX / PDF / JSON；Markdown 表格渲染为真 Word 表格，含导航大纲、目录、页码与中文字体；style=chart 不经 AI 直接出完整排盘报告。
• 📚 自备知识库。 自己的笔记放进知识库文件夹，计算时按名 / 标签 / auto 点选，随结果附进 AI 上下文。
• 🔁 成熟的安装与升级链。 断点续传、多镜像回退、实时进度；版本短路（已最新则跳过下载）；upgrade / uninstall / selfcheck / doctor 环境体检齐备。
• 🔗 同源后端。 奇门 / 太乙 / 金口诀走星阙 ken 后端；14 路神数走 chart 服务上挂载的 kentang 引擎；结果由 headless JS 层重排为 aiExport.js 段结构。

🚀 快速开始

[!TIP]

前置只需 uv：macOS / Linux curl -LsSf https://astral.sh/uv/install.sh | sh；Windows（PowerShell）powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"。装完 重开终端（或 source $HOME/.local/bin/env）让 uv 进 PATH；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）

不想 clone 源码？零安装（无需 git、无需 PyPI）——每个发布页都附带纯 Python wheel，uvx 直接从 URL 起， HOROSA_RUNTIME_MIRROR 对 wheel 与 runtime 一并生效：

WHL="https://github.com/Horace-Maxwell/horosa-skill/releases/download/v0.47.3/horosa_skill-0.47.3-py3-none-any.whl"

uvx --from "$WHL" horosa-skill install # 📦 装离线 runtime（同上） uvx --from "$WHL" horosa-skill doctor # 🩺 体检 uvx --from "$WHL" horosa-skill setup --client cursor # 🪄 零安装一条命令接入（自动选 --launcher uvx-wheel，配置里写 wheel URL） uvx --from "$WHL" horosa-skill serve --transport stdio # 🚀 给客户端直连；client config --launcher uvx-wheel 生成对应配置

github.com 直连不通（镜像 / API 直链 / U 盘离线搬运 / 代理与企业证书）见 docs/INSTALL_RESTRICTED_NETWORK.md。

PyPI 通道（uvx horosa-skill …）已就绪但暂未开通（等维护者完成一次性 Trusted Publisher 配置），开通后命令更短、行为不变。

[!NOTE]

🐳 Docker / Linux（实验）：离线 runtime 只发布 macOS(arm64) / Windows(x64) 两个 payload，没有 Linux payload；

容器里能跑的是 MCP 网关（Python 包 + 知识库 + 记忆），把 HOROSA_SERVER_ROOT / HOROSA_CHART_SERVER_ROOT

指向宿主机或另一台装了 runtime 的机器即可。仓库附带实验性的 horosa-skill/Dockerfile + docker-compose.yml

（网关镜像：容器内没有离线 runtime，必须设上面两个变量；绑 0.0.0.0 必须给 HOROSA_MCP_TOKEN）；

手工起也行：pip install "https://github.com/Horace-Maxwell/horosa-skill/releases/download/v0.47.3/horosa_skill-0.47.3-py3-none-any.whl" 后 horosa-skill serve --transport streamable-http 即为网关（PyPI 尚未开通，装的是发布页的 wheel）。

🔧 安装排障与升级 / 卸载

🔌 接入 AI 客户端

setup --client <客户端> 一条命令走完接入（v0.38.0）：探网（5 s）→ 装 / 校验离线 runtime →（--vectors 时）准备向量检索 → 写配置（自动定位、 只动 horosa 条目、写前备份 .horosa-bak、原子替换）→ 把 horosa-agent skill 装进该客户端读的 skills 目录（v0.47.3； 多数客户端读共享的 ~/.agents/skills；--no-skill 跳过、--skill-dir 指定）→ doctor → 回读磁盘体检 → 用客户端将要执行的那条命令真起一次 stdio server 并数工具 → 打印下一步。失败时 stderr 给出结构化失败包（step / code / config_untouched / backup_path / retry_command），退出码 2；写配置之前失败保证 config_untouched: true。只想看配置不落盘用 client config：

uv run horosa-skill setup --client cursor                # 🪄 一条命令接入（25 个客户端，见下方 Works with 表）

uv run horosa-skill setup --client cursor --dry-run # 只看计划：零副作用 uv run horosa-skill client config --format claude-code # 只生成不落盘：输出 claude mcp add … 命令 uv run horosa-skill client config --format codex # config.toml 片段（含超时设置） uv run horosa-skill client check # 体检本机各客户端实际写着什么（含 skill 装没装、是不是本版） uv run horosa-skill client skill --client codex # 只装 skill 规则（手动配过 MCP 的用户；不带 --client = 共享目录）

skill 是 agent 读的规则（先问后调 / 只读返回的快照 / 禁手算），此前只有打开本仓的 agent 读得到；wheel 里现在带一份，setup 顺手装好。 已有同名目录时：由 npx skills 等工具以软链接管理的、或不是本工具装的，一律不动；你改过的旧版先备份成 horosa-agent.horosa-bak 再更新。

仓根另带 6 份薄镜像——GEMINI.md（Gemini CLI）、.github/copilot-instructions.md（Copilot）、.windsurf/rules/、 .clinerules/、.cursor/rules/（Cursor）、.agents/skills/horosa-agent/（Codex / agentskills.io）——让这些 agent 打开仓库就知道闸门、读盘规则与精简面下的 horosa_tool_run 直呼；策略唯一源仍是 SKILL.md， 其中「Shell-only agents」一节给没有 MCP 的 agent 一套纯 CLI 契约（tool run --input/--output、退出码、闸门流程）。

Works with

| 🧩 Claude Code Plugin | stdio | /plugin marketplace add Horace-Maxwell/horosa-skill → /plugin install horosa@horosa-skill | 全量 125 | skill + MCP 一步到位；插件装在 ~/.claude/plugins/cache/horosa-skill/horosa/ /horosa-skill，首次运行 uv run --directory "<那个目录>" horosa-skill install 装离线 runtime（工具报 `runt