Oraclebone

Oraclebone

三千年前，商王将占卜结果刻在骨头上，留下了最早可审计的占卜记录。Oraclebone 将同样的严谨带给 AI Agent：经过审计的脚本生成抽取结果、卦象和柱位；模型只解读得到的内容，绝不捏造结果。

English | 简体中文 | 日本語

演示

🔮 面向 AI Agent 的开源占卜工具包，原名 ai-divination-skills（在 v8.0.0 中更名——旧 PyPI 包已冻结；请改为安装 oraclebone）。

oraclebone 是一个实用技能集合，涵盖塔罗、易经、小六壬以及未来的象征体系。它面向需要可审计随机性、明确方法边界和可复用解读模板的 Agent 工作流。

本项目将占卜视为象征性推理与反思，而非确定性预测。

⚡ 为 AI Agent 一键安装

将以下内容粘贴到你的 AI Agent 中：

Install Oraclebone for this agent: https://raw.githubusercontent.com/sapuyou45-bit/oraclebone/main/docs/install.md

也可以直接安装，以用于 Claude 风格的本地技能：

curl -fsSL https://raw.githubusercontent.com/sapuyou45-bit/oraclebone/main/install.sh | bash

默认目标目录为 ~/.claude/skills。如需使用其他 Agent 技能目录，请设置 AI_SKILLS_DIR。

✨ 概述

大多数 AI 占卜提示词会让模型捏造结果。本仓库将两项工作分开：

1. 本地脚本生成抽牌结果、卦象或小六壬位置。
2. AI Agent 根据生成的结果进行解读，并遵循明确的安全边界。

这样一来，占卜解读更易于测试、复现、审计，也更便于在不同 Agent 之间复用。

🧭 方法严谨性

核心规则很简单：占卜结果由脚本或用户提供的实体起卦生成；AI 负责解读该结果，不生成占卜结果。

这并非占卜有效性的科学证明，而是一种更严谨的象征性推理工作流：

• 真实占卜默认使用系统随机数
• 固定种子模式仅用于测试和可复现演示
• 每项技能均记录传统方法及其局限
• JSON 输出包含足够的元数据，以便审计所用方法
• 近似模式会发出警告，而不会冒充传统方法

🌐 多语言文档

GitHub Pages 网站提供六种语言切换选项：简体中文、English、日本語、Português、한국어、Español。默认情况下，网站会根据浏览器语言显示内容，并记住你手动选择的语言。

打开已发布的网站

本地预览：

python3 -m http.server 8000 -d docs

已发布的网站：

https://sapuyou45-bit.github.io/oraclebone/

🧩 内置技能

技能	功能	脚本
tarot	抽取塔罗牌，用于自我反思、决策、突破创作瓶颈和重新审视项目。	skills/tarot/scripts/draw.py
iching	起六爻卦，得出本卦和变卦。	skills/iching/scripts/cast.py
xiaoliuren	根据农历风格的数字或公历时间作为备选方式起小六壬。	skills/xiaoliuren/scripts/cast.py
bazi	根据公历出生日期和时间排八字（四柱）命盘。需要安装可选的 lunar-python 扩展。	skills/bazi/scripts/cast.py

🚀 快速开始

从 PyPI 安装：

pip install oraclebone

或从检出目录安装：

pip install .

开发时使用可编辑模式：

pip install -e .

所有系统都使用同一条命令：

ai-divination tarot --deck major --spread three-card --reversals
ai-divination iching --method yarrow
ai-divination xiaoliuren --method numbers --month 3 --day 12 --hour 7

获取 Agent 解读模板：

ai-divination template tarot

直接使用 Python API：

from oraclebone.tarot import draw
from oraclebone.iching import cast
from oraclebone.xiaoliuren import cast_numbers

你仍然可以直接运行底层脚本：

python3 skills/tarot/scripts/draw.py --deck major --spread three-card --reversals
python3 skills/iching/scripts/cast.py --method coins
python3 skills/iching/scripts/cast.py --method yarrow
python3 skills/xiaoliuren/scripts/cast.py --method numbers --month 3 --day 12 --hour 7

使用种子以便重复演示：

python3 skills/tarot/scripts/draw.py --spread decision --seed demo
python3 skills/iching/scripts/cast.py --method yarrow --seed demo

所有脚本都输出 JSON。

📦 安装为 Agent 技能

如需由 AI Agent 引导设置，请使用远程安装指南：

Install Oraclebone for this agent: https://raw.githubusercontent.com/sapuyou45-bit/oraclebone/main/docs/install.md

直接通过 shell 安装：

curl -fsSL https://raw.githubusercontent.com/sapuyou45-bit/oraclebone/main/install.sh | bash

默认情况下，安装程序会将 tarot、iching 和 xiaoliuren 复制到 ~/.claude/skills。如需指定其他 Agent，请在运行安装程序前设置 AI_SKILLS_DIR。

手动安装时，只需将所需文件夹复制到 Agent 的技能目录：

mkdir -p ~/.claude/skills
cp -R skills/tarot ~/.claude/skills/tarot
cp -R skills/iching ~/.claude/skills/iching
cp -R skills/xiaoliuren ~/.claude/skills/xiaoliuren

每项技能都可独立运行：

skills/name/
  SKILL.md
  agents/openai.yaml
  scripts/
  references/

只想安装一项技能时，请安装单个文件夹，而不是整个代码库。

每个技能脚本也支持单文件夹模式。如果已安装 Python 包，脚本会调用包的运行时。如果只复制了技能文件夹，则会回退到该技能中捆绑的独立脚本。

各宿主适配器

每项技能都会在 skills/<skill>/agents/ 中附带四个适配器文件：

宿主	文件	调用方式
OpenAI / Codex 技能	openai.yaml	技能元数据 + 品牌图标。
Claude Desktop / claude.ai 项目技能	claude.yaml	运行 ai-divination <skill> 的工具规范。
Gemini CLI / Gemini Extensions	gemini.yaml	运行同一 CLI 的扩展清单。
Cursor	cursor.mdc	包含“绝不编造抽取结果”严格规则的规则文件。

这四个适配器都会调用经过审计的同一 ai-divination <skill> CLI，因此 Agent 宿主绝不会编造结果。

🧠 在 Claude Desktop / Codex / 任意 MCP 宿主中使用

oraclebone 内置了 MCP 服务（ai-divination-mcp）。任何 Model Context Protocol 宿主——Claude Desktop、Codex、 Continue、Cursor——只需添加一行配置即可连接，并使用模型提供的五种工具： tarot_draw、iching_cast、xiaoliuren_cast、bazi_cast 和 interpretation_template。

模型绝不会编造抽取结果；服务会在本地运行经过审计的脚本。

Claude Desktop

安装一次软件包：

pip install oraclebone

然后编辑 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

{
  "mcpServers": {
    "divination": {
      "command": "ai-divination-mcp"
    }
  }
}

重启 Claude Desktop。提问“为我的决策抽取三张塔罗牌”——Claude 会调用 tarot_draw 并解读 JSON 输出。

Codex / Continue / Cursor

任何兼容 MCP 的宿主都遵循相同的配置方式。服务通过 stdio 使用 JSON-RPC 2.0 通信， 且不依赖第三方。

各客户端设置指南

可复制粘贴的 JSON 配置及各宿主的示例提示词：

• Claude Desktop
• Codex CLI
• Cursor
• Continue

🤖 Agent 行为

每项技能都会指示 Agent：

• 生成或接受具体的占卜结果
• 仅在需要时阅读简明参考资料
• 按照共享的响应规范进行解读
• 避免表达确定性、宿命论观点或专业建议

共享指南位于：

• shared/methodology.md
• shared/interpretation-protocol.md
• shared/response-contract.md
• shared/randomness-protocol.md
• shared/safety-policy.md
• shared/interpretation-style.md

🧪 示例

• examples/tarot-decision.md
• examples/iching-strategy.md
• examples/xiaoliuren-daily.md

🛡️ 安全边界

这些技能不用于提供医疗、法律、财务或危机指导。

好的解读应当：

• 将结果表述为象征性的反思
• 将观点与生成的结果联系起来
• 保留用户的自主权
• 提供小而可逆的后续步骤
• 清楚说明不确定性

完整的项目立场请参阅 ETHICS.md。

🛠️ 开发

除 Python 3 外，无需运行时依赖。

运行测试：

python3 -m unittest discover -s tests

当前覆盖的检查：

• 统一 CLI 路由
• 仅通过软件包运行 CLI
• 可导入的 Python API
• 单文件夹技能执行
• 技能元数据和资源规范
• 解读协议模板
• 塔罗牌阵输出
• 易经起卦结构和手动爻
• 小六壬数字和时间回退行为

💬 社区

• 发行版本：https://github.com/sapuyou45-bit/oraclebone/releases
• 路线图：ROADMAP.md
• 讨论：https://github.com/sapuyou45-bit/oraclebone/discussions
• 问题：选择一个适合新手的问题，或提出一个新技能
• 安全：请参阅 SECURITY.md 了解如何私下报告漏洞

🗺️ 路线图

近期计划：

• 添加已发布软件包的工作流。
• 扩展 CI 中的自动化技能验证。
• 为每项 MVP 技能添加更丰富的参考资料。
• 添加更多解读示例。
• 添加更多 Agent 集成示例。

后续计划：

• meihua
• liuyao
• runes
• numerology
• astrology

📄 许可证

MIT