Horosa Skill

---

✨	✨	✨
🌌 技法110種類をまとめて導入	⚡ アルゴリズムはローカルで実行・オフラインでも利用可能	🛡️ AIによるパラメーターの勝手な補完を防止
🧾 結論の出典を追跡可能・技法の根拠カード付き	📚 31領域のナレッジベース・引用には出典を必須化	🧪 忠実性を評価・ハルシネーションを警告
🔀 複数技法を組み合わせて参照・相違点を必ず開示	🗄️ 呼び出しを自動保存・ワンクリックでレポート作成	🔓 無料・オープンソース・AGPL

リポジトリをクローンし、オフラインのランタイムを一度インストールすれば、Claude Code / Claude Desktop / Codex / Open WebUI / OpenClaw などのクライアントから、MCPまたはJSONファーストのCLIを通じて星阙の実際のメソッドを直接呼び出せます。西洋占星術の出生図／推運／ホラリー／選日、八字／紫微斗数／大六壬／奇門遁甲／太乙／金口訣／三式合一、六爻／タロット／天文地占／霊棋経／小六壬／飛宮小奇門／小成図／皇極軌策／神数正伝、さらに神数14系統すべてに対応しています。

アルゴリズムはローカルで実行され、オフラインでも利用できます。各技法は統一されたエンベロープと星阙形式のエクスポート構造を返し、決定的な技法の根拠カードも付属します。呼び出しのたびに、検索可能なローカル記録が自動作成されます。星阙デスクトップ版と同じバックエンドを共有し、値ごとに同一のソースを使用します（エクスポート契約 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 归档

メモ

これは簡易版の占いツールを新たに作るものではありません。星阙がすでに備えるローカルアルゴリズム、天文暦、エクスポートプロトコルを、GitHubで配布しやすく、AIから呼び出しやすく、長期的なローカル管理に適したインターフェースとして整理したものです。デスクトップ版で算出される結果が、そのままここでも得られます。しかも、すべての結論について「この盤はどのように作成されたのか」を確認できます。

📑 目次

• ✨ 主な特長
• 🚀 クイックスタート
• 🔌 AIクライアントとの接続
• 🎯 1回の呼び出しの全手順
• 🧭 技法一覧
• 📐 出力契約
• 🚦 呼び出し前の確認ゲート
• 🧾 信頼性の体系
• 📂 ローカルメモリーとレポート
• 📦 インストールとランタイム戦略
• ✅ 品質と検証
• 📚 ドキュメント
• 🙏 謝辞とライセンス

✨ 核心特性

• 🌌 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 表格，含导航大纲、目录、页码与中文字体；style=chart 不经 AI 直接出完整排盘报告。
• 📚 自备知识库。 自己的笔记放进知识库文件夹，计算时按名 / 标签 / auto 点选，随结果附进 AI 上下文。
• 🔁 成熟的安装与升级链。 断点续传、多镜像回退、实时进度；版本短路（已最新则跳过下载）；upgrade / uninstall / selfcheck / doctor 环境体检齐备。
• 🔗 同源后端。 奇门 / 太乙 / 金口诀走星阙 ken 后端；14 路神数走 chart 服务上挂载的 kentang 引擎；结果由 headless JS 层重排为 aiExport.js 段结构。

🚀 快速开始

ヒント

前置只需 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.43.0/horosa_skill-0.43.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 配置），开通后命令更短、行为不变。

メモ

🐳 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.43.0/horosa_skill-0.43.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 ディレクトリのパスに中国語などの非 ASCII 文字が含まれています（中国語のユーザー名ではデフォルトのパスにも含まれます）。同梱の 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。ミラーごとに 1 回と数えます）。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 クライアントはシェルの 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 <客户端> の 1 コマンドで接続を完了します（v0.38.0）：ネットワーク確認（5 s）→ オフライン runtime のインストール／検証 → 設定の書き込み（自動検出、 horosa 項目のみを変更、書き込み前に .horosa-bak にバックアップ、アトミック置換）→ horosa-agent skill を、そのクライアントが読み込む skills ディレクトリにインストール（v0.43.0； 多くのクライアントは共有の ~/.agents/skills を読み込みます。--no-skill でスキップ、--skill-dir で指定）→ doctor → ディスクから読み戻して検査 → クライアントが実行するコマンドを使って stdio server を実際に 1 回起動し、ツール数を確認 → 次の手順を表示します。失敗時は 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 はエージェントが読むルール（先に質問してから呼び出す／返されたスナップショットのみを読み取る／手計算を禁止する）です。これまでは、このリポジトリを開いたエージェントだけが読めましたが、現在は 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）——これらのエージェントがリポジトリを開くだけで、ガード、ディスク読み取りルール、簡素化された horosa_tool_run の直接呼び出しを把握できるようにするためです。ポリシーの唯一のソースは引き続き SKILL.md です。 その「Shell-only agents」セクションでは、MCP を使えないエージェント向けに、純粋な CLI の契約（tool run --input/--output、終了コード、ガードの手順）を定めています。

対応クライアント

クライアント	トランスポート	1 行でセットアップ	デフォルトのツール構成	注意事項
🟣 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	スキルと MCP を一度にセットアップ；プラグインは ~/.claude/plugins/cache/horosa-skill/horosa/<version>/horosa-skill にインストールされ、初回実行時に uv run --directory "<那个目录>" horosa-skill install でオフラインランタイムをインストール（ツールが runtime.not_installed を報告した場合は、実際のパスを含むこのコマンドが表示されます）
🧷 Agent Plugins v1（VS Code · Copilot CLI · Codex · Kiro · OpenHands · Qwen Code）	stdio	copilot plugin install Horace-Maxwell/horosa-skill；VS Code の「Chat: Install Plugin From Source」にリポジトリアドレスを入力；qwen extensions install Horace-Maxwell/horosa-skill；Kiro の「Import power from GitHub」	厳選 11	リポジトリルートの plugin.json + mcp.json（仕様 1.0.0）：コマンドは uvx + 現行バージョンに固定した wheel です。事前に uv のインストールが必要です；初回呼び出し前に uvx --from <wheel> horosa-skill install でオフラインランタイムをインストールします。Codex は codex plugin marketplace add Horace-Maxwell/horosa-skill を介して同じマニフェストを読み込みます（未テスト）；OpenClaw / Claude Code は引き続き .claude-plugin/ を使用します
📇 MCP 公式レジストリ	stdio（.mcpb）	レジストリ対応クライアントで horosa を検索（Goose、Junie、Copilot /mcp search、PulseMCP、Glama はすべてここから取得）	全 120	エントリー io.github.Horace-Maxwell/horosa-skill。各リリースの .mcpb のみを登録します（sha256 を含み、クライアントがインストール前に検証）；v0.41.0 以降、リリースの公開後に毎回自動登録されます
🟠 Claude Desktop	stdio	setup --client claude-desktop、または .mcpb のワンクリックパッケージをインストール	全 120	.mcpb は各リリースのアセットに含まれます
🟡 Cursor	stdio	setup --client cursor（または client config --format cursor で公式 deep link を取得し、クリックしてインストール）	厳選 11	Cursor の全体上限は約 40 ツールで、超過分は通知なく破棄されます
🔷 VS Code (Copilot)	stdio	setup --client vscode（ユーザーレベルの mcp.json に書き込み；または client config --format vscode で vscode:mcp/install リンクを取得）	厳選 11	全 server 合計で 128 ツールが上限です；リポジトリ内には .vscode/mcp.json が含まれています
🔵 Codex	stdio	setup --client codex（~/.codex/config.toml をその場でマージし、タイムアウトも設定）	厳選 11	startup_timeout_sec（デフォルト 10 s）と tool_timeout_sec（デフォルト 60 s）を引き上げる必要があります；各ツールの inputSchema は ≤ 5000 B（0.158 のデフォルト予算。本リポジトリのガードで制限）
🟤 Gemini CLI	stdio	setup --client gemini	厳選 11	ツール名は ≤63 文字、かつ厳密な JSON Schema 2020-12 が必要です（広告レイヤーはこれに合わせて調整済み）
🌊 Windsurf → Devin Desktop	stdio	setup --client windsurf（CLI キーは変更なし；Devin の MCP ファイルに書き込み：macOS/Linux は ~/.config/devin/mcp_config.json、Windows は %APPDATA%\devin\mcp_config.json、プロジェクトレベルは .devin/mcp_config.json；既存の旧 ~/.codeium/windsurf Cascade 設定があれば、その場でマージ）	厳選 11	2026-09 以降、Cascade は削除済みです。Devin Local は Devin CLI の MCP ファイルを読み込みます；旧 Cascade の上限は 100 ツールです
🧱 Cline	stdio	setup --client cline	厳選 11	ツール検索機能がなく、全ツール構成では重すぎます
⚡ Zed	stdio	setup --client zed	厳選 11	設定のルートキーは context_servers です
OpenCode	stdio	setup --client opencode（~/.config/opencode/opencode.json の mcp キーに書き込み。コマンドは 1 つの配列として記述）	厳選 11	デフォルトの接続／呼び出しタイムアウトではコールドスタートと择日スキャンを完了できないため、timeout: 600000 を設定済みです
Goose	stdio	setup --client goose（~/.config/goose/config.yaml の extensions に書き込み（Windows は %APPDATA%\Block\goose\config\；horosa のセクションのみ変更））	厳選 11	タイムアウトの単位は秒です。600 を設定済みです
Kiro	stdio	setup --client kiro（~/.kiro/settings/mcp.json に書き込み；スキルは ~/.kiro/skills にインストール）	厳選 11	Kiro CLI の起動時の待機時間はデフォルト 5 s のみです。事前に kiro-cli settings mcp.initTimeout 120000 を実行してください
GitHub Copilot CLI	stdio	setup --client copilot-cli（~/.copilot/mcp-config.json に書き込み（tools: ["*"]、timeout を含む））	厳選 11	PATH のみを転送します：env テーブルには HOME と 2 つの runtime ルートを書き込み、プローブも同じ形式で検証します
JetBrains Junie	stdio	setup --client junie（~/.junie/mcp/mcp.json に書き込み）	厳選 11	タイムアウトフィールドがありません。初回使用前に horosa-skill runtime start でウォームアップしてください
Qwen Code	stdio	setup --client qwen（~/.qwen/settings.json に書き込み（コメントを保持））	厳選 11	discoveryTimeoutMs のデフォルトは 30 s です。120000 を設定済みです
Kimi Code CLI	stdio	setup --client kimi（~/.kimi-code/mcp.json に書き込み）	厳選 11	厳密な JSON が必要で、1 つでも不正な項目があるとファイル全体が拒否されます；startupTimeoutMs / toolTimeoutMs を設定済みです
Qoder	stdio	setup --client qoder（~/.qoder/settings.json に書き込み；スキルは ~/.qoder/skills にインストール）	厳選 11	旧バージョンの Qoder IDE では、MCP を UI からしか設定できません
CodeBuddy	stdio	setup --client codebuddy（実際に読み込まれるファイルに書き込み（~/.codebuddy/.mcp.json → mcp.json → ~/.codebuddy.json のうち、最初に存在するもの）；スキルは ~/.codebuddy/skills にインストール）	厳選 11	タイムアウトの設定には環境変数 MCP_TIMEOUT / MCP_TOOL_TIMEOUT のみ使用できます
TRAE	stdio	setup --client trae（ファイルには書き込まず、ワンクリックインポートリンク trae://…（中国国内版は trae-cn://）と貼り付け可能な JSON を表示；スキルは ~/.trae/skills にインストール）	厳選 11	すべての MCP 合計で 40 ツールが上限です；command にスペースを含めることはできません
Amp	stdio	setup --client amp（~/.config/amp/settings.json のリテラルキー amp.mcpServers に書き込み）	厳選 11	エントリーに余分なフィールドを含めることはできません（タイムアウトなし）；初回使用前にウォームアップしてください
Warp	stdio	setup --client warp（~/.warp/.mcp.json に書き込み（保存すると適用））	厳選 11	Warp で Claude Code / Codex の server も自動起動するように設定している場合、二重に起動する可能性があります
Factory Droid	stdio	setup --client droid（~/.factory/mcp.json に書き込み（connectTimeout / timeout を含む））	厳選 11	変更後に自動で再読み込みします
Augment Auggie CLI	stdio	setup --client augment（~/.augment/settings.json に書き込み（コメントを保持））	厳選 11	IDE 拡張機能は独自の設定パネルを使用し、このファイルは読み込みません
Deep Code	stdio	setup --client deepcode（~/.deepcode/settings.json に書き込み（厳密な JSON が必要；ファイルにコメントがある場合は書き込みを拒否します。API key を含むファイル全体が破棄されるためです））	厳選 11	1 回のツール呼び出しの上限は固定で 60 s のため、長時間のタスクはタイムアウトします；起動タイムアウトには DEEPCODE_MCP_TIMEOUT を使用します
DeepSeek Harness（dsh）	stdio	setup --client dsh（独立したパッチ ~/.horosa/clients/dsh/horosa.cordis.yml を生成し、dsh web --patch <它> で有効化；既存の cordis.patch.yml は変更しません）	厳選 11	開発者プレビュー版のため、形式が変更される可能性があります
⚪ OpenClaw / mcporter	stdio	client openclaw-setup --workspace ~/.openclaw/workspace	全 120	—
🟢 Open WebUI · n8n · Dify	streamable-http	horosa-skill serve --host 0.0.0.0 --token <随机串>	全 120	接続方法；別のマシンから接続する場合は必ずトークンを指定してください。また、TLS はありません。リバースプロキシの背後に配置してください
🔶 ChatGPT / claude.ai リモートコネクター	streamable-http	同上に加え、OAuth を終端する HTTPS ゲートウェイ（Cloudflare Access / oauth2-proxy）を重ねてください。両方のコネクターは OAuth のみを受け付けますが、この server が提供するのは静的 Bearer のみです。ゲートウェイが OAuth を Authorization: Bearer <HOROSA_MCP_TOKEN> に変換して注入します	全 120	ホスト型エンドポイントはありません；設定例は説明を参照してください
--surface full / --surface compact 可覆盖默认；--launcher uvx-git 生成免 checkout 的
零安装命令（uvx --from "git+…#subdirectory=horosa-skill"，PyPI 通道尚未开通）。

平台

平台	离线 runtime	说明
macOS arm64	✅ 官方载荷	主力平台
Windows x64	✅ 官方载荷	见 Windows 说明
Windows ARM（骁龙本 / Surface 等）	✅ 自动装 x64 载荷走仿真（自 0.38.0）	Windows 11 的 x64 仿真下 Java / Python / Node 都能起（GitHub windows-11-arm 真机 lane 验证）；install 报 runtime.platform_emulated、doctor 报 emulated: true（payload_platform: win32-x64）
Linux	⚠️ 无载荷（实验）	走网关模式：把 HOROSA_SERVER_ROOT / HOROSA_CHART_SERVER_ROOT 指向一台受支持的机器
Intel Mac	❌ 不支持	arm64 载荷不能在 Rosetta 下跑（内含 JDK/Python 是原生 arm64）；本轮明确不做 x86_64 载荷，走网关模式

ヒント

上下文预算受限的客户端可设 HOROSA_MCP_COMPACT=1，只暴露 11 个门面工具（含按名直调的 horosa_tool_run，110 个技法仍可按名到达），澄清闸照常生效。或用 HOROSA_TOOLSETS=astro,cn 按域裁剪平铺面（合法域 astro/predict/chart/cn/shenshu/other/export/knowledge，别名 western/chinese/reference/all/none；拼错的 token 会告警并忽略、全空回落全量；只要裁剪生效就注册 horosa_tool_run 直呼通道；门面工具恒在）。根目录 server.json 为 MCP Registry 元数据，普通用户无需手改。

ヒント

繁体输出：在 Claude Desktop 扩展设置 / Claude Code 插件设置里勾「繁體中文輸出」，或设 HOROSA_OUTPUT_SCRIPT=zh-Hant（香港字形用 zh-Hant-HK；setup --client <名> --output-script zh-Hant 直接写进客户端配置）。排盘正文、段名、提示与报告转成繁体；回显的入参、设置值、选项、错误码保持原样（AI 原样送回也对得上），不设就是简体、与原来逐字相同。术数用字按 沖 / 剋 / 曆 而非 衝 / 克 / 歷。

ヒント

配好了却在客户端里看不到 horosa？跑 uv run horosa-skill client check —— 它读的是各客户端实际写着什么，能指出未展开的占位符、缺失的 --transport stdio、搬走的目录、以及 Codex 的默认超时。

🎯 一次调用的完整流程

以「查今年事业，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️⃣  溯源尾注   —— 把 data.technique_card 转述成尾注：用了什么技法 /
    什么口径 / 谁算的 / 段落全不全 / 版本链
5️⃣  出报告     —— report_render 生成解读终稿 DOCX（自动写回记忆）；
    horosa_technique_report 另出「技法依据报告」
6️⃣  跨会话找回 —— memory_query 按人名 / 技法 / 日期检索，memory_show 取完整记录

メモ

最短路径为 2 次工具调用 + 1 次本地分析：起盘拿到 run_id，本地撰写 ai_report，再 report_render 出 Word 并自动归档。一问需要多技法互证时，改用一次 horosa_hecan 并行起盘（见可信度体系）。全程算法在本机、AI 只负责解读、结构永不丢。

🧭 技法总览

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

🌟 西洋占星 · 本命与派生盘（11）

工具 ID	名称	说明
chart ⓟ	标准星盘	基础西洋星盘 + 完整导出正文（12 分度 / 主宰星链 / 寿命格局 / 古典 + 古典衍化 / 古典格局）
chart13 ⓟ	13 宫扩展盘	chart13 形态输出
chart12 ⓟ	十二分盘 / Dwadasamsa	黄经×12 mod 360，与十三分盘同结构
babylon	巴比伦占星	恒星黄道·毕宿锚 + 算术历日 + 「位」三法 + 行星神性 + 微黄道
draconic	龙盘 / Draconic	各点黄经减北交点（交点归零的盘）+ 龙首基准专属段
relocation	重置盘 / Relocation	出生时刻不变，按新居住地重算宫位与角点 + 四角对比段
hellen_chart ⓟ	希腊星盘	希腊占星取向盘面
india_chart ⓟ	印度盘	分宫 4→24 制、岁差 6→47 制
guolao_chart ⓟ	七政四余盘	七政四余 / 果老法盘面
relative ⓟ	合盘 / 关系盘	双人关系、合盘、关系量化评分
germany ⓟ	量化盘 / 汉堡学派	90° 拨盘 + 8 颗 TNP + 中点树 / 相位 / 列表

⏳ 西洋占星 · 推运 / 返照 / 时运 · 占星地图 / 名人库（33）

工具 ID	名称	说明
solarreturn ⓟ / lunarreturn ⓟ	太阳 / 太阴返照	本命 + 返照盘 + 相位
solararc ⓟ	太阳弧推运	本命 + 推运盘 + 相位
givenyear ⓟ	指定年推运	本命 + 流年盘 + 相位
profection ⓟ	小限 / 年运推限	profection 时间层
pd ⓟ	本初方向 / 主限	逐位核验核5方位法 + 22 项时间钥匙，可推运至 3000 年
pdchart ⓟ	主限盘	可读主限盘面 + 相位
zr ⓟ	黄道释放	zodiacal release 时间轴
firdaria ⓟ	法达星限	法达星限结构与时间轴
decennials ⓟ	十年大运	与星阙 decennials.test.js 金标对齐
agepoint ⓟ	年龄推进点 / Huber	Koch 宫 6 年一宫周期
distributions ⓟ	界推运 / 分配法	上升点行经埃及界的分配主时间轴
mundane ⓟ	世俗盘	年度入宫盘 + 子盘群（新月 / 满月 / 日月食 / 地区盘 / 行星周期 / 定局 / 分野）
jaynesprog ⓟ	赤纬推运	二次推运 + 赤纬平行 / 反平行
vedicprog ⓟ	恒星推运	sidereal 下的二次推运
prog ⓟ	二次推运（回归黄道）	次限 / 三限 / 小限推运（minorVariant：synodic 缺省 / sidereal / engine），上游 v3.11 新导出键
ephemeris ⓟ	星历	日期窗内入座·留逆·朔望弦·食相 + 行运触发本命（缺省今日起 90 天）
returntimeline ⓟ	回归轴	逐年太阳 / 月亮返照时间轴（起始年 + 年数 1–40）
prenatalsyzygy ⓟ	产前朔望	出生前最近朔 / 望、所落度数与该时刻的星盘
planetaryarc ⓟ	行星弧	整盘按 arcSource 二次弧方向
planetaryages ⓟ	行星年龄	托勒密人生七阶 + 当前主运
yearsystem129 ⓟ	129 年系统	七政各管小年的 129 年一轮
persiandirected ⓟ	波斯向运	黄经象征向运（1°/年）应期表 + 指定日期整铸向运盘
balbillus ⓟ	Balbillus 129 年	旺距削减主限 + 递归子限
triplicityrulers ⓟ	三分主星推运	昼夜换序划分人生阶段
keypoints ⓟ	数字相位推运	七星小年数 + 座距按年龄因数激活
lunationphase ⓟ	月相推运	次限日月黄经差八相时间轴
extrareturns ⓟ	多重回归	土 / 木 / 月交三体返照应期 + 日月返照年表
acg ⓟ	占星地图	行星地理投影线（MC/IC / 天顶点 / 偕升带 / 线交点）+ 落点分析 / 世运事件时刻
india_rectify ⓟ	印度生时校正	KP 法锚点±半窗扫描：RP / Pranapada / gandanta 边界判据打分候选榜
planet_cycles	行星周期	任意两星合冲精确时间轴（木土 / 土冥…；地心 / 日心 / 站心）
astrodata ⓟ	名人星盘库	数万条 A/AA 级出生数据离线检索（FTS / 分类 / Rodden 评级）
xuanshi	玄史知识库	7900+ 玄学事件（原文/白话/解读/引证）· 27000+ 史书天象 · 人物图谱 · 朝代/术数/时间线（只读检索）

🔯 西洋占卜 · 卜卦 / 择日（13）

工具 ID	名称	说明
horary ⓟ	卜卦（horary）	根本性 / 14 类征象星 / 完成分析 / 月亮的故事 / 裁决 / 应期方位
election ⓟ	择日（electional）	红线 / 28 类用事规则包 / 评分定级 / 起盘时刻 / 建议
tianxing ⓟ	天星择日·征象搜索	时间窗内扫西占征象条件树 / 命中区间 + 单时判读 + 选中时刻星盘
qizhengelection ⓟ	七政择日动盘	十一曜二十四山方位 / 地平高度顺逆 / 日月食搜索 / 方位到达搜索
qimenzeri ⓟ	奇门择日「找局」	时间窗内扫奇门条件树 / 命中时辰 + 完整奇门盘 17 段
huanglizeri ⓟ	黄历择吉	日期范围内扫通书条件树（26 类）/ 命中日段 + 完整黄历日课 10 段
bazizeri ⓟ	八字择时	时间窗内扫八字条件树（26 类：十神在柱 / 刑冲穿破 / 纳音星运…）/ 命中时段 + 完整八字盘
taiyizeri ⓟ	太乙择时	时间窗内扫太乙条件树（24 类：十精诸算 / 九州分野…）/ 命中时段 + 完整太乙盘
ziweizeri ⓟ	紫微择时	时间窗内扫紫微条件树（28 类：格局含破格 / 宫干四化 / 来因宫…）/ 命中时段 + 完整紫微盘
liurengzeri ⓟ	六壬择时	时间窗内扫六壬条件树（27 类：小局大格 / 遁干 / 旺衰…）/ 命中时段 + 完整六壬盘
sanshizeri ⓟ	三式合一择时	条件跨六壬 / 奇门 / 太乙三盘自由组合（70 类，最多的一支）+ 三式合一盘
qizhengzeri	七政择时	分钟级区间搜索（七态庙旺等 11 类，判定跑后端 swisseph）+ 果老盘
indiazeri	印度择时 Muhurta	分钟级区间搜索（Panchanga 五肢 / Lagna / 三十须臾 / Choghadia / 五祸等 18 类，判定跑后端）

☯️ 中文术数主干 · 三式合一（11）

工具 ID	名称	说明
bazi_birth ⓟ / bazi_direct ⓟ / bazi_inverse	八字命盘 / 直断 / 八字反查	四柱 + 大运 + 神煞 + 干支合冲 + 五行力量 / 格局 / 盲派结构；反查 = 四柱干支 → 候选出生时刻（Java 逐年回推，免确认门）
ziwei_birth ⓟ	紫微斗数	自定义四化 / 流派 / 身宫 / 八字大运 / 命中格局；22 个传本开关（非缺省即按星阙本地 ZiweiCalc 重排）
ziwei_rules	紫微规则库	返回紫微命中格局规则全库（免确认直读）
liureng_gods ⓟ / liureng_runyear ⓟ	大六壬起课 / 行年	26 起课法 / 四课三传（递生递克）神煞 / 毕法 100 法 / 占断向导 / 七政
qimen ⓟ	奇门遁甲	ken（kinqimen）起盘（缺省置闰；非时家 / 飞盘等按星阙同判据走本地 calcDunJia）+ 法奇门叠加层 + 演卦
taiyi ⓟ	太乙神数	ken（kintaiyi）起盘，十六宫标记，流派六轴 + 时间基准
jinkou ⓟ	金口诀	ken（kinjinkou）起盘（流派非缺省走星阙本地引擎），地分自动取占时支，20 段解读层
sanshiunited ⓟ	三式合一	一页聚合奇门 + 太乙 + 大六壬，统一导出

🀄 本地术数 · 数算 · 占卜（16）

工具 ID	名称	说明
tongshefa ⓟ	统摄法	卦象 / 六爻 / 潜藏 / 亲和
canping ⓟ	邵子参评数 / 金锁银匙	四柱起数 + 本命 / 大运歲運条文
heluo ⓟ	河洛理数	先后天卦 + 元堂爻辞 + 大限岁运断验
yizhangjing ⓟ	一掌经	十二支六道 + 十二宫 + 大限流年十二神 + 神煞合参
zhengchuan ⓟ	神数正传	铁板 / 邵子 / 大定 / 六亲 / 铁算心易 五流派·四柱起数 + 条文 + 大运死月
xiaoliuren ⓟ	小六壬	三数起三传·主流六宫 / 道门九宫 + 生克 + 九神 + 拜解
feigong ⓟ	飞宫小奇门	时上起青龙飞九宫 + 主客命宫 + 八门九星 + 流年流月 + 应期
xiaochengtu ⓟ	小成图	洛书九宫佈局 + 正旁推 + 四象 + 应期 + 股市研判（五式起卦）
guice ⓟ	皇极轨策	十二法起卦 + 演数四位 + 卦变断法 + 三要十应 + 元会运世 + 大定
harmonic ⓟ	调波盘	黄经 × 调波数取位、同频合相 + H 数表专属段
suzhan ⓟ	宿占 / 宿盘	宿占结构与宿曜信息（缺省八字公式起盘，宿度制 0–8）
sixyao ⓟ	六爻 / 易卦	本 / 互 / 之 / 错 / 综卦 + 断卦结构 + 断诀命中 / 占类断语（星阙以时起卦与断语库）
geomancy ⓟ	天文地占	4 母卦 → 16 图形 + 十二宫入宫 + 判官 / 见证
tarot ⓟ	塔罗	78 牌确定性洗牌 + 牌阵直断 / 细论 / 综合建议
lingqi ⓟ	灵棋经	十二棋一时掷之（上四中四下四）→ 六十四卦 + 棋势三才 / 繇辞 / 诸家注 / 课断 / 断诗
otherbu ⓟ	占星骰子	星骰与对应解读结构

🔢 神数（全 14 路）

工具 ID	名称	引擎	工具 ID	名称	引擎
wangji ⓟ	皇极经世	标准	tieban ⓟ	铁板神数	kinastro
wuzhao ⓟ	五兆	标准	fendjing ⓟ	鬼谷分定经	kinastro
taixuan ⓟ	太玄筮法	标准	beiji ⓟ	北极神数	kinastro
jingjue ⓟ	荆诀	标准	nanji ⓟ	南极神数	kinastro
shenyishu ⓟ	神易数	标准	chunzi ⓟ	蠢子数	kinastro
shaozi ⓟ	邵子神数	kinastro	xianqin ⓟ	万化仙禽（演禽）	kinastro
cetian ⓟ	策天飞星	kinastro	qizhengkin ⓟ	七政四余（七政·张果）	kinastro

📅 节气 / 农历 / 黄历（6）

工具 ID	名称	说明
jieqi_year ⓟ / nongli_time ⓟ	全年节气盘 / 农历换算	节气节点 / 农历干支
jieqi_birth ⓟ	出生节气窗	出生前后节气精确时刻 + 所落区间（八字起运窗同源）
calendar_month ⓟ	黄历 / 万年历	整月农历 / 干支 / 节气 / 朔望 + 选中日详情（农历 / 老黄历 / 日子馆三源合一）
huangli	老黄历日课	今日宜忌 / 值神值宿 / 彭祖百忌 / 吉神凶煞 / 冲煞·胎神·方位 / 时辰吉凶 / 物候 / 流年年神方位
tongshu	通书择日	董公 / 奇门叠数 / 三垣列宿 / 天元乌兔 / 三元玄空大卦 五流派

🧠 协议 / 知识（6）+ MCP 门面（11）

工具 ID	名称	说明
gua_desc / gua_meiyi	卦义 / 梅易卦义	卦名卦辞 / 梅花易数卦义
export_registry / export_parse	导出协议注册表 / 正文解析器	机器可读导出总表 / 把导出文本解析回 JSON
knowledge_registry / knowledge_read	知识目录 / 读取器	31 域（hover 知识 + 技法操作手册 + 八字断语库）列出 / 读取 / query 跨域全文检索，逐条带出处

计算工具之外，MCP 面还有 11 个门面工具（HOROSA_MCP_COMPACT=1 时只暴露这一层）：

门面	作用
horosa_dispatch	总调度：自然语言意图自动分派到对应技法，汇总层带每个子结果的导出契约
horosa_hecan	合参：一问并行起多路技法（默认 5 路、上限 8 路），返回带证据指针与结论槽的合参模板
horosa_tool_run	按名直调：用工具名 + payload 调 110 技法目录索引中的任意工具
horosa_agent_guidance	参数指引：该技法必须先问哪些字段、哪些星阙默认值可在用户点头后使用
horosa_technique_report	技法依据报告：单次 / 整场问答「用了什么技法、什么口径、谁算的」的确定性报告
horosa_report_template / horosa_report_render / horosa_report_from_tool	咨询报告：AI 终稿 → JSON / DOCX / PDF，自动写回记忆
horosa_memory_query / horosa_memory_show / horosa_memory_record_answer	本地记忆：检索 / 回看完整记录 / 写回最终答案

メモ

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

📐 输出契约

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

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

接入导出协议的技法额外带 data.export_snapshot，含 export_text（段结构化正文）、sections（逐段标题 + 正文 + 结构化数据）、selected_sections、provenance 等；另附 data.technique_card（技法依据卡，见可信度体系）。因此 ——

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

メモ

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

🚦 调用前的澄清闸

重要

只要技法受时间 / 地点 / 时区 / 性别 / 事项 / 宫制 / 历法 / 起局方式影响，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 名（按起盘日期归一化）。

🧾 可信度体系

重要

玄学输出最大的风险不是算错，而是 AI 在盘面之外自由发挥。这里把「结论怎么来的」做成机器契约：每个答案可溯源、每条教义有出处、每句断言可对盘校验、多技法互证有纪律——四件都由确定性代码守着，不靠模型自觉。

1. 每个结论带技法依据卡

每个技法响应附 data.technique_card：技法名与流派口径（含 排盘规则 晚子时开关）、算源声明 vs 运行实测（compute.matches_declaration=false 时必须提示「结果请谨慎采信」）、段落完整性、版本链。horosa_technique_report 把单次调用（run_id）或整场问答（group_id）渲染成 markdown / json / docx / pdf 方法报告，会话级还会检出跨技法口径冲突（两个技法晚子时开关不同 = 结论不可互证）。不需要时 HOROSA_TECHNIQUE_CARD=0 关闭。

uv run horosa-skill report technique --group-id <group_id> --format markdown

2. 31 域方法论知识库 · 引必带出处

knowledge_registry / knowledge_read 覆盖 31 域 = 星阙 app 内 hover 知识三域 + 27 份技法操作手册 + 八字断语库 21 类（共 409 条：各设置项取值与差别、流派分歧、算法与口径、八字口诀），逐条带「星阙操作手册 · 域 · 条目（源文件 @ 上游版本）」出处。配套策略写进 SKILL.md：引教义必带出处；没有出处的解读必须明说是通则推理——反 Barnum 效应的第一机制。

3. 盘面事实忠实性评测

horosa-skill benchmark faithfulness 用确定性校验器（非 LLM 打分）把 AI 解读中的事实断言逐条对盘面机读真值：四柱干支 / 行星落座 / 紫微主星落宫与身宫 / 大六壬三传 / 六爻卦名与动爻 / 塔罗牌名正逆……三通道判 supported / invented / contradicted。喂错盘的答案、诱导复述（「我月亮在天蝎对吧」「我抽到的月亮是逆位吧」而实际不是）都会判红。HorosaBench 105 条基准用例由工具注册表生成、与工具集锁步——新增技法没有用例直接红。

4. 一问多技法合参

horosa_hecan（CLI：horosa-skill hecan）：一问并行起多路技法（同 group_id 落库；默认 5 路、上限 8 路，可显式指定 tools），返回合参模板而非终稿——逐技法结论槽必须绑定该技法真实段落（响应里只有证据指针，全文用 memory_show(run_id) 取）；convergence 只在多技法独立同判时填；divergence 逐条披露，不许平均、不许只挑一边；口径冲突（consistency.setting_conflicts）必须先声明。

5. 可选云端决策层（TypeSafe Jev · 默认关闭）

上面所有承诺（不联网、不上传）在默认状态下原样成立。v0.39.0 起可以显式开启一个云端「决策层」—— TypeSafe 的 Jev（System One 决策模型，只回类型化的选择/概率，不生成文本）——只做三件窄事：确定性关键词 路由无匹配时兜底选技法；把用户原话里明说的设置（如「我老婆的八字」→ 性别女）变成「已提供」 （词表证据 + 模型判定 + 置信阈值三钥齐才填，永不替用户选默认）；六壬问题的占断门类分类。它不算盘、不解盘。

项	说明
开关	HOROSA_JEV=off（默认）/ shadow（只记录它会怎么判，行为不变）/ enforce；密钥 HOROSA_JEV_API_KEY（Claude Desktop / 插件在设置里填，永不写进 Horosa 文件）
离机的数据	一档 HOROSA_JEV_SCOPE=meta（默认）：本地脱敏后的问题文本（日期 / 时刻 / 坐标 / 地名 / 号码 → 占位符）+ 技法名 + 设置键名；二档 snapshot：额外允许导出快照文本，仅供未来的忠实性/合参判定面
不离机的数据	出生日期、时刻、坐标、地名原值；盘面与导出全文（一档）；密钥；本地记忆
服务商事实	托管闭源模型，美国机房；「不用于训练」是合同承诺（非架构保证）；数据留存无公开数字，零留存仅企业版
每次自陈	data.technique_card.decisions[] / horosa_dispatch 的 decision_layer（模型 id、选项、置信、是否采纳）；horosa-skill jev status / jev events（本地账本）
权限边界	代码持有权限：确定性路径永远是权威；enforce 需在自家中文标注集上晋升过的阈值锁；任何失败关闭式回落并写进 warnings

📂 本地记忆与报告

本地数据默认写入 ~/.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 表格（跨页重复表头）、导航大纲、目录、页码、中文字体，异常自动降级保全文。
• 🧾 report technique 生成技法依据报告（机器元数据），与咨询报告（AI 终稿）分轨，互不混入。
• 🗂️ 完整排盘报告：report render --style chart（或 report_render {style:"chart"}）不经 AI 解读，直接把该技法的全部盘面段落排成 PDF / DOCX——封面、基本信息、可点击目录与书签、「第 N 页 / 共 M 页」、技法依据附录。
• 📚 自备知识库：把自己的笔记（.md / .txt）放进 horosa-skill knowledge mine 列出的文件夹（或 knowledge add <名> --file …），计算时传 knowledge:["条目名", "#标签", "auto"]，选中的正文随结果挂在 data.knowledge_context 供 AI 参考（不进引擎、不改盘面；总字数受 HOROSA_USER_KNOWLEDGE_MAX_CHARS 限）。

uv run horosa-skill knowledge add 八字/滴天髓笔记 --file ./notes.md --techniques bazi_birth --tags 古籍
uv run horosa-skill knowledge mine

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

📦 安装与 runtime 策略

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

层	位置	作用
📂 公开仓库层	GitHub repo	代码、文档、CLI、MCP、测试、示例、打包脚本
📦 打包输入层	vendor/runtime-source/	构建离线 runtime 的大体积输入（不进 Git 历史）
💻 用户运行层	~/.horosa/runtime/current	用户安装后本地执行算法的 runtime

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

✅ 质量与验证

检查项	结果
🧰 可调用工具	110 / 110 ok=true
🧪 工程测试	2071 / 2071 pass（离线 CI 形状：契约 + 导出 fixture + node JS golden；另 116 项 live 集成测试需本地 runtime，服务未起时自动 skip）
🛡️ 未确认参数时强制追问	100 个技法工具触发 must_ask_user=true
🔓 免闸直读	10 个注册表 / 知识 / 解析类工具不经澄清闸
📐 星阙式导出结构	每个业务技法均带 export_snapshot（已建模 107 个导出 technique；契约 v15 镜像桌面端 aiExport v58）
🧾 技法依据卡	每个技法响应附 data.technique_card；算源声明与运行实测不符时显式亮警
📚 知识库	31 域；技法操作手册 236 条逐条带出处（生成器幂等，随上游版本重收割）
🎯 HorosaBench	106 条基准用例与工具注册表锁步 + 盘面事实忠实性评测（喂错盘 / 诱导复述判红的对抗用例全过）
🗄️ 本地 memory / report	每次技法调用写 1 条本地 run 记录 + 1 份 JSON artifact
🔄 GitHub CI	Linux 单测 + JS golden 自检 + Windows OpenClaw smoke（不覆盖跨树上游校验——那两闸需要上游 checkout，只能在维护机跑 preflight_release.py）
📦 Release runtime	macOS (arm64) + Windows (x64) 随每个 release 打包并校验（本仓版本 v0.43.0；公开 latest 以 Releases 页为准）——Windows 半从 darwin 种子在托管流水线派生、清单只在两半齐了才上线、三台真机（macOS / Windows x64 / Windows ARM）装起跑过；Windows ARM 自动走 x64 仿真；Intel Mac / Linux 安装时明确报不支持并指向网关模式

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

cd horosa-skill && uv sync && uv run horosa-skill install
uv run horosa-skill doctor                              # 期望 issues: []
uv run pytest -q                                        # 2071 passed（live 集成测试在服务未起时 skip）
uv run python scripts/run_full_self_check.py --rounds 1 # 全工具调用 / 导出 / 落库 / 检索 / dispatch 汇总

警告

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

📚 文档

文档	内容
docs/ARCHITECTURE.md	架构设计
docs/INPUT_CONTRACTS.md	每个工具的输入契约（必填字段）
docs/DATA_CONTRACTS.md	输出 / envelope / export 数据契约
docs/EXPORT_AUDIT_GUIDE.md	推运类导出的逐段审计方法
docs/OPERATIONS.md · docs/EVALUATION.md	运维 · 评测体系（HorosaBench / 忠实性）
docs/OFFLINE_RUNTIME_RELEASES.md	离线 runtime 打包与发布
docs/LESSONS.md · docs/GLOSSARY.md	逐版本经验台账 · 领域名词表
skills/horosa-agent/SKILL.md · AGENTS.md	AI 客户端行为策略源 · Agent 总规则与路由

🙏 致谢与许可证

奇门遁甲 / 太乙神数 / 金口诀（及三式合一中的奇门 + 太乙）的盘面，由 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 授权。传统术数体系本身（京房八宫、希腊十年星限等）属公共知识，不构成第三方版权。