当前版本：0.3.2 · 维护者：GEsoFo · 源码仓库 · 问题反馈
本地运行的六壬、奇门与真实北斗方位联合择时插件，适用于支持 stdio MCP 与 Skill 的 AI 客户端。
一个组合插件，包含通用、可离线计算的 stdio MCP 服务器和 time-direction-election Skill。提供六壬、奇门和北斗方位的
固定事实与候选材料，由调用它的模型按事项和全部本命作取舍。
不使用吉神加分、凶神扣分，不自动给出“最佳方位”。没有模型 API 密钥依赖。
- 六壬完整式盘：天地盘、四课、九宗门三传、十二天将、旬遁、六亲长生。
- 奇门：时家转盘拆补/置闰可选，星、门、神、天地干、值符值使、时旬空。
- 具名九遁组合，含龙遁、虎遁主式与另说；门迫、击刑、三奇入墓及 乙加辛等条件一起提供，格名不自动等于通用吉方。
- 六壬贵人所临地盘方、式盘辰天罡斗柄方，保留原文事类边界。
- 真实北斗七星：每次传入任意经纬度，计算具体时刻的几何方位、高度、 是否在地平线上及近似太阳高度。没有默认城市，也不要求在线星历下载。
- 多个具名本命分别比较；婚姻需双方资料，缺一方不能回填可用结论。
- 判断材料按小批次读取，模型回填后生成离线 HTML；用方留空时可用段 必须附模型选择的方位和理由。
Python 3.11+、Node.js 18+。
git clone https://github.com/GEsoFo/time-direction-plugin.git
cd time-direction-plugin
python -m pip install .
time-direction-mcp也可通过仓库的 Code → Download ZIP 下载源码后解压，在解压目录执行安装命令。启动命令供客户端接入或协议调试使用，交互时请在 AI 客户端加载 MCP 配置与配套 Skill。
源代码方式可运行 python /path/to/time-direction-mcp/server.py，先安装
lunar-python==1.4.8 skyfield==1.54 tzdata。所有资源跟随包安装，
不依赖开发者的盘符、用户目录、另一个项目 checkout 或私人配置。
服务器采用 MCP 标准 UTF-8 JSON-RPC stdio，支持初始化、工具列举、 工具调用与 ping。它是专用 stdio 实现；不声称提供 HTTP、SSE、OAuth 或通用 MCP 框架的所有可选能力。日志不混入 stdout。
安装后可使用仓库的 .mcp.json：
{"mcpServers":{"time-direction":{"command":"time-direction-mcp","args":[]}}}若使用源码，把 command 设为实际 Python 命令，args 设为
服务器入口的绝对路径；不同客户端的配置存放位置由其产品决定。
可通过 TIME_DIRECTION_OUTPUT_ROOT 指定生成文件的根目录；默认使用
系统临时目录下的独立目录。观测地点只由工具参数提供，没有环境里的
隐藏默认城市。
| 工具 | 用途 |
|---|---|
get_qimen_chart |
指定时刻起奇门局 |
get_beidou_sky |
指定时刻和经纬度计算真实七星 |
get_direction_facts |
联合六壬、奇门、式盘斗柄、真实七星及各本命 |
build_election_request |
创建1–7日材料和未判断 HTML，跨月不丢窗口 |
build_year_election |
完整公历年365/366日；按月加载HTML，模型逐批判断 |
preview_election_calendar |
恢复日历HTTP预览与已登记书签 |
read_election_windows |
每次读取最多14个窗口供模型审阅 |
render_election_calendar |
校验并累积合并各批判断后回填 HTML |
示例工具参数（地点是本次请求的示例，不是服务器默认值）：
{
"datetime":"2026-10-06T20:00:00+08:00",
"purpose":"祈福",
"participants":[{"name":"本人","branch":"午"}],
"observer":{"latitude":30.0,"longitude":120.0,"elevation_m":0,"label":"本次观测点"}
}不传 observer 时，六壬、奇门和式盘斗柄仍正常计算，真实七星返回
needs_observer，不会假定城市或编造地平坐标。
本版术数时钟明确使用北京时间、默认23:00换日；input_timezone 仅用于
解析无偏移的输入时间，有时区偏移的 ISO 时间会先转换到北京时间起课。
观测地点影响真实星空，不暗改术数时钟为当地真太阳时。海外地点也可
调用真实天文工具，但不能把此默认术盘误称当地太阳时盘。
奇门采用具名现代拆补转盘口径：天禽寄芮、中五寄坤二，值符随时干， 值使按阴阳顺逆计时落宫，八门转八宫，八神阳顺阴逆。 局表、符首三元、八门九星及格局参考：
qimen_method 可传 chaibu（拆补，默认）或 zhirun（置闰）。
置闰按《遁甲演义》超接引例，采用含符首九日阈值、芒种/大雪重复三元、接气借新节下元；以1899-12-07甲午大雪正授连续推算，支持1900–2099。
两法均用时家转盘；不是九星飞宫。每次判断绑定所选起局法。龙遁“休乙加癸”引文含伏吟文字歧义，作为条件候选，
不宣称该另说完整成立。虎遁休门主式、生门另说分别保留。
天文使用 SIMBAD/CDS ICRS J2000 坐标与自行、Skyfield 公共接口的岁差章动
及地球转动转换。返回巡天级几何方位，不含周年光行差、视差、大气折射、
天气或地形；地平线上不等于肉眼可见。太阳高度是日光提醒的近似计算。
日历中的七星是窗口中点快照，并非两小时内方位恒定；要具体分钟请
再次调用 get_beidou_sky。
- 明确事项、每个参与者本命、范围和是否有观测坐标。
- 创建材料，按小批次读取所有需要的窗口，不能只挑漂亮案例。
- 模型比较每个方位的多体系证据、事类用途和矛盾；填写
verdict/reason/evidence。未指定用方的可用段还需suggested_direction（单一地支、理由、证据）。 - 不能把吉格、贵人方或真实星空坐标机械累加成吉凶分数。
- 回填工具绑定参与者、观测点、事实摘要；不完整或旧参数不能冒充已审。
资料不足的窗口可以明确标待定。盘面事实和文化择时不构成中奖、疾病 结果、婚姻结局或其他现实事件的保证。
python -m unittest discover -s tests -v测试覆盖原文天遁示例、局盘排列不变量、主式/另说分离、太阳节气边界、 跨地点星空、MCP 初始化和真实工具调用、跨月材料及回填约束。
MIT 许可适用于本插件原创代码，派生六壬引擎保留 BSD-3-Clause；见
THIRD_PARTY_NOTICES.md。发布目录不包含开发环境、私人判断或个人坐标。
由 GEsoFo 维护；问题与改进建议可提交到 GitHub Issues。反馈请使用虚构示例，不要提交个人生成日历、真实坐标或凭据。
调用 build_year_election，传入 year（1900–2099），以及事项、具名多本命、所选奇门方法和可选观测坐标。生成12个月全部365/366日事实。年度材料只保留窗口索引，每批 read_election_windows 最多14窗才展开完整盘面。
模型回填每批 render_election_calendar 后，会保留并合并之前已判断窗口；同ID再次提交可纠正结论。每批返回累计覆盖数及 complete，部分判断不会冒充全年完成。HTML只载入当前月份，保留同目录全部 .data.js 文件才能离线切月。
CLI：python <resources/calendar/scripts/calendar.py> --year 2027 --output <输出目录>。默认显示当前日期所在月；没有该月时从生成范围第一月开始。离线页面只浏览已有年份，要新年份由 MCP 或 CLI 重新生成。
发布 ZIP 解压后根目录包含 plugin.json、mcp.json、skills/time-direction-election/，以及兼容旧客户端的 .codex-plugin/plugin.json、.mcp.json。Skill 的 MCP 依赖标识与服务名称统一为 time-direction。
- 准备 Python 3.11+、Node.js 18+；在解压目录执行
python -m pip install .安装计算运行时。也可安装同版 wheel，依赖仍需通过合法包源安装。插件管理器不会自动安装 Python/Node，这一步是运行前提。 - 在支持本地插件的客户端中添加解压目录/本地插件源并启用插件。新客户端读取根
plugin.json/mcp.json，兼容客户端读取.codex-plugin/plugin.json/.mcp.json。仅支持 MCP 的客户端可单独导入.mcp.json，并手动加载配套 Skill。 - 新会话确认
time-direction的8个工具与time-direction-electionSkill 可见，输入“用择时与方位插件，为2027年开业择日，本命午，用方未指定”。多本命用名称与地支逐人提供。
如果客户端找不到 time-direction-mcp，将本机客户端配置的 command 改为实际 Python 环境的该入口绝对路径；发布包不包含开发者机器路径。该包是本地 stdio 插件，未部署远程服务、未提交官方公共插件目录，也没有自动修改用户的客户端配置。官方公共目录提交需满足其当前远程 HTTPS 接入要求。
MCP固定事实，Skill组织事项判断、全年的逐批审阅、上下文绑定和日历回填。安装两者不代表模型已经审阅任何日期。
开发者重建发布包：python scripts/package_release.py <包外输出目录>。不要把个人事实/判断输出、虚拟环境或密钥加入发布包。
官方包装规范：https://developers.openai.com/plugins/build/plugins ，Skill连接规范：https://developers.openai.com/plugins/build/skills 。
生成、回填工具现在自动返回标准 HTTP preview_url。预览在 MCP 进程中运行，仅绑定127.0.0.1，只提供明确注册的日历 HTML 与 .data.js，不暴露事实JSON、配置、目录列表或任意磁盘路径。地址使用ASCII路径；支持UTF-8脚本名。页面显示实际已回填/总窗口数，未回填不冒充全审阅。
服务随 MCP 进程存活，应用重启后请调用 preview_election_calendar(artifact_id) 恢复地址。默认自动分配空闲端口；TIME_DIRECTION_PREVIEW_PORT 可设首选端口，占用时回退空闲端口，返回实际地址。启动失败仍保留离线HTML与数据文件，返回 preview_error。没有自动关闭或绕过浏览器策略。
独立预览命令：time-direction-preview --artifact <artifact_id> --output-root <生成根目录> --port 8767。该命令保持运行才能提供预览；可用 --alias <短名> 兼容现有书签。本地 /health 返回服务名和版本。它只预览文件，不是远程HTTP MCP服务。
0.3.1 在每个已预览 artifact 内保存 preview.json（仅本机使用，不通过预览提供），MCP启动时恢复已登记的日历与别名。设置固定首选端口且该端口空闲时，重启后原书签可继续用；端口回退时以工具返回的新地址为准。
- 从明确的
release-files.json清单在干净目录构建，扫描最终 ZIP 和 wheel；排除 Python 缓存，并在 wheel 内携带第三方许可说明。 - 修复重启后第一次读取年度材料的导入错误、无效起盘口径未提前拒绝、北京时间转换和跨年范围越界。
- 修复异常预览记录导致启动失败及别名/令牌冲突，增加跨站读取限制。
- 未判断的日历保留请求事项、参与者和口径；页面导入时拒绝无效建议方位。
- 隐私边界和发布步骤见
SECURITY.md。公开仓库只使用新发布 ZIP 解压内容。
在已连接的 AI 客户端输入：
用择时与方位插件，为 2027 年开业择日。参与者本命为午，用方未指定。先生成全年事实，再逐批判断并回填日历；报告已经判断的窗口数量与未完成部分。
只看盘面可输入：
查看北京时间 2027-01-01 12:00 的六壬和奇门盘，只列固定事实。
真实北斗方位须另行提供本次观测坐标；没有观测点时仍可查看术盘。参与者姓名可以使用“甲方”“乙方”等代号。
src/time_direction_mcp/：服务器、文件材料管理与本机预览。src/time_direction_mcp/resources/calendar/：历法、六壬桥接、奇门、神煞、天文与离线页面。skills/time-direction-election/：事项澄清、逐批判断与回填工作流。tests/：排盘不变量、日历、协议、发布和隐私边界的回归测试。
欢迎通过 Issue 或 Pull Request 提交可复现问题与修复。修改计算规则时，请附具名口径、原始出处与虚构案例，并保持“固定事实、真实天文、模型判断”之间的界限。
0.3.2 在 Windows / Python 3.14 环境通过 23 项测试及隔离安装验证；其他系统与 Python 版本尚未逐一验证。常规算例测试不等于所有规则和日期逐例校勘。