模型

Iztro 通过同一套 Agents SDK 和 Session API 提供两个公开模型：

iztro-ziwei-v3 从一个人的出生盘出发。
iztro-qimen-v3 从一件具体事情及其问事时刻出发。

创建 Agent 或 Session 时选择模型。如果产品同时需要两种视角，应分别调用，并明确告诉用户每项结论来自哪个模型。

30 秒选择规则

问题围绕一个人、两个人的关系或较长人生阶段，用紫微；问题围绕当下正在发生的一项具体决策，用奇门。奇门问题如果还要问“什么时候”，请提供用户当地的问事时刻和 UTC 偏移量。

选择正确的模型

模型	最适合的问题	需要提供的信息	不适合当作
`iztro-ziwei-v3`	先天性格与优势、人生主题、两人适配度以及中长期运势周期	出生日期、出生时间、性别和明确主题	脱离本命背景的一件当下事件起局
`iztro-qimen-v3`	一件当下决策：是否推进、局势如何发展、阻力在哪里，以及可选的行动时间	当前事实、一个明确决策和当地问事时刻	宽泛的性格、合盘或一生运势分析

推理配置与模型类型无关，同一配置同时适用于紫微和奇门。详见模型设置。

`iztro-ziwei-v3`

当答案需要以出生盘为基础时，选择紫微。常见主题包括：

性格、能力、优势和反复出现的人生课题；
事业、财富、感情、健康或家庭趋势；
两人适配度，此时应分别提供双方完整出生信息；
一个明确的多年阶段或运势周期。

写好一个紫微问题

请包含：

分析谁。 明确主体是用户本人还是其他人。
完整出生信息。 提供出生日期、出生时间和性别；分析两人关系时要分别标清两个人。
一个主题和时间范围。 说明要看事业、感情、财富或其他具体领域；涉及时间时写明年份。
希望得到的回答结构。 可以要求先给结论，再给盘面依据、时间、风险和行动建议。

例如：

我出生于 1990 年 6 月 15 日上午 10 点，男性。请分析我 2026 至 2028 年的事业发展。先给结论，再说明盘面依据、较强阶段、风险和行动建议。

同一个人的连续追问可以保留在同一个 ChatSession。切换到另一个人的命盘或另一组关系时，应新建会话。

紫微结果边界

将结果作为结构化参考，不要写成必然发生的事件。
每项时间判断都要和回答中注明的年份或阶段保持关联。
分析两人关系时，要区分哪些判断属于个人，哪些属于两人关系。
盘面信号不一致时，应保留不确定性。

`iztro-qimen-v3`

奇门适合判断一件具体且具有时效性的事情。常见主题包括合作、谈判、面试或 offer、产品上线、出行、争议，以及关系中的某个具体下一步。

奇门不需要生日、出生时辰或性别。

用直白语言理解奇门

术语	含义
一事一局	互不相关的决策应放在不同请求或会话中。
问事时刻	用户提出这件具体问题的当地时间。
用神 / Yongshen	盘面中用于代表所问人物、对象或事情的符号。
应期 / Yingqi	用于时间判断的候选触发时刻，不是结果保证。

写好一个奇门问题

请包含：

只问一件具体事情。 不要合并互不相关的决策。
说明当前事实。 已发生了什么、有哪些选项、真正的限制是什么。
提出明确决策。 例如应该推进、继续谈、等待、停止，或在定义清楚的选项中如何选择。
需要时明确问时间。 直接要求行动窗口或可能的触发时间。

例如：

我们已经就一项渠道合作沟通两次，但分成和上线时间仍未确定。现在应该主动推动签约、继续谈判，还是暂缓？如果事情可以推进，请给出最近的行动窗口、盘面依据和可执行方案。

场景	推荐的问题结构
合作或合同	说明谈判阶段和未决条款；询问应该推进、重谈还是等待。
面试或 offer	说明已完成的环节和已知信号；询问流程可能如何发展，以及下一步该做什么。
上线或活动	说明计划动作和现实限制；询问当前窗口是否合适，以及需要控制什么风险。
关系决策	说明当前互动和一个拟采取的动作；询问现在行动还是等待。

出生信息不会改善奇门问题。如果用户还需要中长期本命视角，请另行调用紫微，并清楚标注两份结果。

正确设置奇门问事时刻

默认情况下，服务使用请求时间。用户不在服务端时区、重放历史请求、编写测试夹具，或需要保证结果可复现时，应显式传入 current_datetime：

2026-07-20T14:30:00+08:00

请使用带明确 UTC 偏移量的 ISO 8601 时间。这个值表示用户提出问题的时刻，不是计划签约、上线、面试或出行的日期；计划日期应写在问题正文中。

同一件事情的追问可以保留在同一个 ChatSession。用户切换到互不相关的新事情时，应新建会话。

奇门结果边界

时间结果是候选触发窗口，不代表合同必然签署、款项必然到账或关系必然成功。
每个日期都要和回答中注明的条件及依据保持关联。
不要把不同条件对应的日期合并成一个“必成窗口”。
保留不确定性，现实决策仍由用户承担。

使用 SDK 调用任一模型

先按 SDK 快速开始安装包，并在服务端设置 ZIWEI_API_KEY。PowerShell 使用 $env:ZIWEI_API_KEY="sk_ziwei_..."。

模型	Python 便捷工厂	TypeScript 便捷工厂
`iztro-ziwei-v3`	`iztro_ziwei_agent(...)`	`iztroZiweiAgent({...})`
`iztro-qimen-v3`	`iztro_qimen_agent(...)`	`iztroQimenAgent({...})`

Python
TypeScript

import asyncio
import os

from agents import ModelSettings, Runner
from openai.types.shared import Reasoning
from iztro_agents import iztro_qimen_agent, iztro_ziwei_agent

async def main():
    ziwei = iztro_ziwei_agent(api_key=os.environ["ZIWEI_API_KEY"])
    ziwei_result = await Runner.run(
        ziwei,
        (
            "我出生于 1990 年 6 月 15 日上午 10 点，男性。"
            "请分析我 2026 至 2028 年的事业发展。"
        ),
    )

    qimen = iztro_qimen_agent(
        api_key=os.environ["ZIWEI_API_KEY"],
        model_settings=ModelSettings(
            reasoning=Reasoning(effort="high"),
            metadata={"current_datetime": "2026-07-20T14:30:00+08:00"},
            extra_body={"language": "zh"},
        ),
    )
    qimen_result = await Runner.run(
        qimen,
        (
            "我们已经谈过两次合作，但关键条款仍未确定。"
            "现在应该推进、继续谈判，还是暂缓？"
            "如果可以推进，请给出最近的行动窗口。"
        ),
    )

    print("紫微：", ziwei_result.final_output)
    print("奇门：", qimen_result.final_output)

asyncio.run(main())

完整示例：

紫微：examples/01_hello_ziwei.py
奇门：examples/12_qimen_decision.py

import {run} from '@openai/agents';
import {
  iztroQimenAgent,
  iztroZiweiAgent,
} from 'openai-iztro-agents';

const ziwei = iztroZiweiAgent({
  apiKey: process.env.ZIWEI_API_KEY,
});
const ziweiResult = await run(
  ziwei,
  '我出生于 1990 年 6 月 15 日上午 10 点，男性。请分析我 2026 至 2028 年的事业发展。',
);

const qimen = iztroQimenAgent({
  apiKey: process.env.ZIWEI_API_KEY,
  modelSettings: {
    reasoning: {effort: 'high'},
    providerData: {
      language: 'zh',
      metadata: {current_datetime: '2026-07-20T14:30:00+08:00'},
    },
  },
});
const qimenResult = await run(
  qimen,
  '我们已经谈过两次合作，但关键条款仍未确定。' +
    '现在应该推进、继续谈判，还是暂缓？如果可以推进，请给出最近的行动窗口。',
);

console.log('紫微：', ziweiResult.finalOutput);
console.log('奇门：', qimenResult.finalOutput);

完整示例：

紫微：examples/01-hello-ziwei.ts
奇门：examples/12-qimen-decision.ts

只有在需要自行构造标准 Agent 时，才使用 iztro_ziwei_model(...)、iztro_qimen_model(...)、iztroZiweiModel(...) 或 iztroQimenModel(...)。

对外返回的计算名称

API 和 SDK 可能在 iztro_tools 或 Iztro 工具事件的 tools 数组中返回以下公开值。这些值构成完整的对外命名契约；不要记录、展示或依赖任何其他工具名称及内部实现。

模型	可能返回的值
`iztro-ziwei-v3`	`iztro-mingpan`；`iztro-daxian`；`iztro-xiaoxian`；`iztro-liunian`；`iztro-liuyue`；`iztro-liuri`
`iztro-qimen-v3`	`qimen-qigua`；`qimen-yingqi`

紫微的周期名称可能在名称后带上本次查询范围，例如 iztro-liunian 2026-2028。开发者详情应原样显示返回字符串。如果产品使用“正在分析命盘”等友好进度文案，应将它与返回值分开处理。

使用 Session HTTP API

创建会话时设置 model：

{
  "external_user_id": "user_42",
  "model": "iztro-ziwei-v3"
}

判断一件当下决策时改用 iztro-qimen-v3。发送奇门消息时，current_datetime 是消息请求的顶层字段：

{
  "message": "这项合作现在应该推进、继续谈判，还是暂缓？",
  "current_datetime": "2026-07-20T14:30:00+08:00",
  "language": "zh",
  "enable_iztro_call": true
}

完整请求格式和会话生命周期见 Session API。两个模型的推理配置均独立设置，详见模型设置。

产品呈现检查清单

在结果旁明确显示所选公开模型名称。
紫微结果应概括正在分析谁的出生信息和哪个时间范围。
奇门结果应展示事情标题，以及带时区的当地问事时刻。
先给直接结论，再给依据、时间、行动建议和不确定性。
计算名称必须按返回值原样显示，绝不暴露或推测内部名称。
时间应呈现为阶段或候选窗口，不能写成结果保证。
保留原始分析主体，让后续追问始终关联到正确的人、关系组合或事情。

选择正确的模型​

iztro-ziwei-v3​

写好一个紫微问题​

紫微结果边界​

iztro-qimen-v3​

用直白语言理解奇门​

写好一个奇门问题​

正确设置奇门问事时刻​

奇门结果边界​

使用 SDK 调用任一模型​

对外返回的计算名称​

使用 Session HTTP API​

产品呈现检查清单​