命运工具

运行与部署方式

本项目支持本地开发、Cloudflare Pages 和 Docker 三种常用运行方式。AI 相关变量也放在这里，部署时可以一起配置。

<details> <summary>本地开发</summary>

本项目使用 pnpm workspace 管理应用层与 mingyu-core 算法包，需先安装 pnpm：

npm install -g pnpm

安装依赖：

pnpm install

启动网页开发服务：

pnpm dev

启动 MCP Server：

pnpm mcp

构建生产版本：

pnpm build

运行测试：

pnpm test

单独构建 mingyu-core 算法包：

pnpm --filter mingyu-core build

类型检查 MCP 与共享源码：

npx tsc --project mcp/tsconfig.json --noEmit

</details>

<details> <summary>Cloudflare Pages 部署</summary>

推荐部署到 Cloudflare Pages，静态页面由 Pages 托管，/api/v1/* 由 Pages Functions 处理。

Pages 构建设置：

如果 Cloudflare 没有自动启用 pnpm，可在环境变量中添加：

PNPM_VERSION=10

公开 API 路由来自 functions/api/v1/[[path]].ts，部署后可访问：

https://你的域名/api/v1/manifest
https://你的域名/api/v1/openapi.json

Cloudflare Pages 的环境变量在 Dashboard → Settings → Environment variables 中配置。密钥不要写进代码仓库。

</details>

<details> <summary>Docker 部署</summary>

Docker 镜像会构建前端页面，并在容器内启动一个 Node 服务，同时提供：

• 网页访问
• /api/v1/* 公开 API
• /api/v1/ai/analyze 流式 AI 解读
• /api/v1/ai/models 模型列表获取

构建镜像：

docker build -t mingyu .

启动基础服务：

docker run --rm -p 3000:3000 mingyu

访问：

http://localhost:3000

带服务端 AI 启动：

docker run --rm -p 3000:3000 \
  -e AI_API_KEY=sk-xxx \
  -e AI_BASE_URL=https://api.deepseek.com/v1 \
  -e AI_MODEL=deepseek-chat \
  -e AI_PROVIDER_NAME=DeepSeek \
  -e AI_BUILTIN_ENABLED=true \
  -e AI_DEFAULT_ENABLED=false \
  mingyu

也可以使用 Docker Compose：

docker compose up --build

Compose 会读取本地 .env。可以在本地 .env 中填写下面内容，但不要提交这个文件：

AI_API_KEY=sk-xxx
AI_BASE_URL=https://api.deepseek.com/v1
AI_MODEL=deepseek-chat
AI_PROVIDER_NAME=DeepSeek
AI_BUILTIN_ENABLED=true
AI_DEFAULT_ENABLED=false

默认端口是 3000。如需修改容器内端口，可设置 PORT；如需修改宿主机端口，调整 compose 或 docker run 的 -p 左侧端口。

</details>

<details> <summary>服务端 AI（内置 AI）配置</summary>

命语支持两种 AI 使用方式：

• 用户在首页顶部齿轮中自行填写 OpenAI 兼容接口，API Key 只保存在用户自己的浏览器。
• 站点部署者在服务端配置 AI，前端会显示一个可选服务商。这个能力也可以理解为“内置 AI”。

服务端 AI 环境变量：

只配置 AI_API_KEY 不会自动显示服务端 AI；必须同时设置 AI_BUILTIN_ENABLED=true。如果想提供公益内置 AI，但默认仍让用户复制提示词，可设置 AI_BUILTIN_ENABLED=true、AI_DEFAULT_ENABLED=false。用户仍可通过齿轮自行填写自己的接口。

AI 代理会对上游临时错误自动重试 2 次。只重试网络异常、408、429 和 5xx；鉴权失败、模型名错误等确定性问题不会重试。常见错误码：

.dev.vars.example 提供了本地和 Cloudflare 可参考的变量模板。公开站点启用服务端 AI 会产生调用成本，也可能受上游模型稳定性影响，建议先确认额度、限流和可用性。

</details>

集成方式

命语提供三种集成方式：公开 API、MCP Server、公开 skill。API 和 MCP 都支持一站式返回 result 与 prompt；六爻、梅花易数、奇门遁甲、大六壬、小六壬还支持通过 customDate 指定起卦或排盘时间。README 只保留快速入口和安装方式，接口参数、客户端配置和调用示例请跳转到对应文档。

<details> <summary>公开 API</summary>

无需安装，直接调用线上接口：

https://aov.cc/api/v1

详细文档：docs/api.md

OpenAPI：https://aov.cc/api/v1/openapi.json

</details>

<details> <summary>MCP Server</summary>

命语内置 MCP Server，让支持 MCP 的 AI 客户端直接调用本地排盘引擎，不需要用户手动复制 JSON 或提示词。

快速安装：

git clone https://github.com/Brhiza/mingyu.git
cd mingyu
npm install

启动命令：

npm run mcp

详细文档：mcp/README.md

</details>

<details> <summary>公开 skill</summary>

这个 skill 面向 AI 代理和开发者，说明如何通过 aov.cc 公开 API 完成排盘、占卜和提示词生成。

快速安装：

npx skills add Brhiza/mingyu --skill aov-mingyu-api -g -y

快速读取：

让你的 AI 代理读取这个 skill：
https://aov.cc/skills/aov-mingyu-api/SKILL.md

如果当前环境无法使用 npx skills，也可以手动创建目录后保存：

mkdir -p ~/.codex/skills/aov-mingyu-api
curl -L https://aov.cc/skills/aov-mingyu-api/SKILL.md \
  -o ~/.codex/skills/aov-mingyu-api/SKILL.md

Windows PowerShell：

New-Item -ItemType Directory -Force "$env:USERPROFILE\.codex\skills\aov-mingyu-api"
Invoke-WebRequest "https://aov.cc/skills/aov-mingyu-api/SKILL.md" `
  -OutFile "$env:USERPROFILE\.codex\skills\aov-mingyu-api\SKILL.md"

详细文档：public/skills/aov-mingyu-api/SKILL.md

元数据发现：https://aov.cc/.well-known/aov-mingyu-api.json

</details>

模型评测

比赛资料位于：docs/2025第十六届全球算命师比赛

<details> <summary>展开评测命令和参数</summary>

交互式运行：

npm run contest:evaluate

脚本会依次询问接口 URL、API Key 和模型名称，自动读取 8 份提示词与 正确答案.md。每个命例只要求模型输出 5 个 A/B/C/D 答案字母，减少长理由导致的截断和解析错误；调用完成后输出 100 分制总分、准确率、分命例得分和逐题明细。

也可以直接传参：

npm run contest:evaluate -- --format chat --url https://api.openai.com/v1 --key sk-xxx --model gpt-4.1-mini

批量并发评测：

npm run contest:evaluate -- --format chat --url https://openrouter.ai/api/v1 --key sk-xxx --concurrency 3 --models "GPT-5.4=openai/gpt-5.4,Claude Sonnet 4.6=anthropic/claude-sonnet-4.6"

--concurrency 控制同时评测的模型数量，默认批量为 3；--caseConcurrency 控制同一模型内命例并发数量，默认 1。批量模式会合并更新比赛目录下的 模型评测排名报告.md 和 评测结果/本次排名原始结果.json。

使用 OpenRouter 测 reasoning 模型时，可以加 --reasoningEffort none --excludeReasoning --maxTokens 256，让模型尽量只返回最终答案。若某个命例没有解析满 5 个答案，脚本会把该模型标为失败，不会把 ????? 当作 0 分答案计入排名。

支持的 --format：

不传 --format 时会自动识别；评测报告会保存到比赛资料目录下的 评测结果/。

</details>