horosa

🔮 Horosa Skill

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

简体中文 · English

---

✨	✨	✨
🌌 110 技法一次装齐	⚡ 算法本机跑 · 断网可用	🛡️ AI 不许乱补参数
🧾 结论可溯源 · 技法依据卡	📚 31 域知识库 · 引必带出处	🧪 忠实性评测 · 幻觉判红
🔀 多技法合参 · 分歧必披露	🗄️ 调用自动落库 · 一键出报告	🔓 免费 · 开源 · AGPL

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

算法在本机运行，断网可用；每个技法返回统一 envelope 与星阙式导出结构，并附一张确定性的技法依据卡；每次调用自动落成可检索的本地记录。与星阙桌面端共用同一套后端、逐值同源（导出契约 v15 镜像桌面端 aiExport v58，星阙 v3.11.3）。

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

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

📑 目录

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

✨ 核心特性

• 🌌 110 个真实技法，一次安装，全程离线。 覆盖西洋占星全链路、中文术数主干、数算与卜法、全 14 路神数；算法在本机运行，不联网、不上传。
• 🧠 为 AI 消费而设计的稳定契约。 每次调用返回统一 envelope，接入导出协议的技法附带 export_snapshot（段结构化正文）。同一技法连续调用得到同一套字段，落库后结构不丢。
• 🛡️ 调用前的硬性澄清闸。 只要技法受时间 / 地点 / 时区 / 性别 / 事项 / 宫制 / 历法 / 起局方式影响，agent 在用户确认前会被结构化拦截，并收到可直接转发给用户的追问文本。
• 🧾 每个结论可溯源。 响应自带技法依据卡（技法 / 流派口径 / 谁算的 / 段落全不全 / 版本链），horosa_technique_report 一键出方法报告，会话级自动检出跨技法口径冲突。
• 📚 31 域方法论知识库，引必带出处。 星阙 app 内 hover 知识三域 + 27 份技法操作手册 + 八字断语库（21 类口诀）共 409 条，逐条带上游文件与版本出处；没有出处的解读必须明说是通则推理。
• 🧪 盘面事实忠实性评测。 确定性校验器把 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 表格，含导航大纲、目录、页码与中文字体。
• 🔁 成熟的安装与升级链。 断点续传、多镜像回退、实时进度；版本短路（已最新则跳过下载）；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.41.0/horosa_skill-0.41.0-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.41.0/horosa_skill-0.41.0-py3-none-any.whl" 后 horosa-skill serve --transport streamable-http 即为网关（PyPI 尚未开通，装的是发布页的 wheel）。

症状	处理
uv: command not found	先安装 uv：curl -LsSf https://astral.sh/uv/install.sh | sh
下载缓慢或中断	重跑 install 会断点续传；或设 HOROSA_RUNTIME_MIRROR=<镜像前缀> 走镜像
github.com:443 直连不通（但 api.github.com 可达）——完整方案见 docs/INSTALL_RESTRICTED_NETWORK.md	走 API 资产直链下载后本地安装：先 curl -s https://api.github.com/repos/Horace-Maxwell/horosa-skill/releases/latest 找到平台 zip/tar.gz 的 assets[].id，再 curl -L -H "Accept: application/octet-stream" -o runtime.zip https://api.github.com/repos/Horace-Maxwell/horosa-skill/releases/assets/<id>，最后 uv run horosa-skill install --archive runtime.zip
Java 后端(:9999)未就绪 / doctor 报 services:java_backend_not_running	会自动降级 chart-only 而不是全盘卡死：三式(奇门/太乙/金口)、神数、地占、塔罗、西占 chart 族照常可用；nongli/bazi/ziwei/liureng 与「占时」起课暂不可用。doctor 的 java_diagnostics 附捕获的 Java 启动错误，selfcheck 会自动改用 chart 侧探针
Windows 上 Java 进程秒退、无任何日志	已知诱因：代理/VPN/安全软件的 WFP 过滤会拦 java.exe 的 loopback（JDK-17 内部管道优先 AF_UNIX，connect 被拦即崩且无 TCP 回退，见 issue #14）。停掉相关服务通常不够（WFP 过滤驻留内核），需禁用后重启再试；期间 chart-only 降级模式可继续用
磁盘不足 / 端口被占 / 看不懂 doctor 的码	uv run horosa-skill doctor --explain：stdout 仍是 JSON，stderr 多 6–10 行人话；报告里 advice[] 给每个 issue / warning 码一句 user_summary + next_action；--probe-network 逐个镜像探清单 URL（默认零外网请求）
macOS 首次起 runtime 失败且无日志 / doctor 报 quarantine:runtime_binaries	浏览器下载的归档解出来的 python / java / node 带 Gatekeeper 隔离属性：运行报告里 quarantine.fix 给出的 xattr -dr com.apple.quarantine <runtime/current> 后 runtime restart
Windows 路径太长（runtime.install_long_path）	doctor.windows.headroom_chars 为负即会拒：设 HOROSA_RUNTIME_ROOT=C:\horosa，或开注册表 LongPathsEnabled=1 后重启（v0.38.0 起临时目录前缀缩短，多出约 20 字符余量）
Windows 上 install 报 runtime.path_not_ascii，或 doctor 报 windows:runtime_root_not_ascii（八字 / 紫微 / 六壬起不来、chart 族报参数错误）	runtime 目录路径含中文等非英文字符（中文用户名下的默认路径即是）；随包的 Java 17 与 Swiss Ephemeris 用窄字符 API 访问文件。设纯英文路径：setx HOROSA_RUNTIME_ROOT C:\horosa，新开终端并重启 AI 客户端后重跑 install / setup
慢网 / 企业代理下载总超时	HOROSA_RUNTIME_DOWNLOAD_TIMEOUT_SECONDS（默认 120）、HOROSA_RUNTIME_DOWNLOAD_ATTEMPTS（默认 3，每个镜像各算一轮）；doctor 报 arch.emulated: true 只是提示进程在仿真下跑，不影响安装
Windows 首次启动弹防火墙 / doctor 报 listener:not_loopback_only	旧版启动器把 Java 绑在 0.0.0.0；升级后 uv run horosa-skill runtime restart 重套模板即钉回 127.0.0.1（doctor.listener_scope 可核）
Codex 里一堆报错 / 首轮看不到工具	多半是超时没写（Codex 默认 10 s/60 s）：uv run horosa-skill client check --client codex 会指出缺哪项，client config --format codex --write ~/.codex/config.toml 原位合并修好
终端里 uvx 能跑、GUI 客户端里起不来	GUI 客户端不继承 shell PATH；重跑 client config（现在写绝对路径），client check 报 command_not_on_path 即此症
Windows 用户名带空格 / 中文时服务起不来	v0.38.0 起启动器给每个路径参数加了引号；升级后 runtime restart
升级	uv run horosa-skill upgrade（同版本不重复下载）
卸载	uv run horosa-skill uninstall（默认仅打印将删清单，--yes 执行，--purge-data 才动用户数据）

🔌 接入 AI 客户端

setup --client <客户端> 一条命令走完接入（v0.38.0）：探网（5 s）→ 装 / 校验离线 runtime → 写配置（自动定位、 只动 horosa 条目、写前备份 .horosa-bak、原子替换）→ 把 horosa-agent skill 装进该客户端读的 skills 目录（v0.41.0； 多数客户端读共享的 ~/.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	stdio	setup --client claude-code（CWD 有 .mcp.json 写项目级，否则自动 claude mcp add --scope user）	全量 120	项目内直接用仓根 .mcp.json；说明
🧩 Claude Code Plugin	stdio	/plugin marketplace add Horace-Maxwell/horosa-skill → /plugin install horosa@horosa-skill	全量 120	skill + MCP 一步到位；插件装在 ~/.claude/plugins/cache/horosa-skill/horosa/<version>/horosa-skill，首次运行 uv run --directory "<那个目录>" horosa-skill install 装离线 runtime（工具报 runtime.not_installed 时会给出带真实路径的这条命令）