PDM 会话管理（三合一工具）。

三个 action：

• "start" — 启动一个新的 PDM 会话。

• "stop" — 关闭指定的 PDM 会话。

• "list" — 列出所有活跃的 PDM 会话及其状态。

启动模式：

• "py" (默认) — 启动 pdm -mode py -script mainloop.py 无头子进程， 通过 Python API 执行所有操作。适合脚本化和 CI 场景。

• "gui" — 启动 PDM GUI（暂未实现）。

每个 session_id 对应一个独立的 PDM 实例，支持多会话并行。

Args: action: 操作类型，"start" / "stop" / "list"。 session_id: 会话标识符，默认 "default"。start/stop 使用。 mode: 启动模式，"py" / "gui"，默认 "py"。仅 action="start" 使用。 pdm_path: 可选，自定义 PDM 可执行文件路径。留空则自动检测。仅 action="start" 使用。 timeout: 启动超时秒数，默认 120。仅 action="start" 使用。

快速功耗估算 / Part 推荐 / 系列列表——无需 PDM 会话。

action 决定操作：

• "quick": 快速功耗估算，基于 XPE 公开系数 + 线性模型，秒级返回。精度约 ±40%。

• "recommend": 根据功耗预算和资源需求推荐合适的 Part 型号。

• "families": 列出支持快速估算的 FPGA 系列及典型参数。

quick 参数: part: FPGA 器件型号，如 "xc7a100tcsg324-1"。 clock_mhz: 主时钟频率 (MHz)。 lut_pct: LUT 利用率百分比 (0-100)。 ff_pct: FF 利用率百分比 (0-100)。 bram_pct: BRAM 利用率百分比 (0-100)。 dsp_pct: DSP 利用率百分比 (0-100)。 io_count: IO 引脚数量。 io_standard: IO 标准，如 "LVCMOS33"、"LVDS"、"SSTL15"。 io_toggle: IO 翻转率百分比 (0-100)，默认 12.5。 gt_count: GT 高速收发器数量。 gt_rate: GT 线速率 (Gbps)。 temp: 环境温度 (°C)，默认 25。 airflow: 风流量 (LFM)，默认 250。 heatsink: 散热器类型 (none/small/medium/large)，默认 medium。

recommend 参数: budget: 总功耗预算 (W)。 logic_cells: 需要的逻辑单元数。 bram_kb: 需要的 BRAM (Kb)。 dsp_slices: 需要的 DSP Slice 数。 io_count: 需要的 IO 引脚数。 gt_count: 需要的 GT 收发器数。 family: 限定系列，如 "7series"、"ultrascale"。 max_count: 最多返回结果数，默认 5。

统一的 PDM 项目操作入口。

Actions: open(path) — 打开 .pdm 项目文件 create(name, part, output_dir) — 创建新的 PDM 项目 close — 关闭当前项目 save(save_path) — 保存项目（可选另存为路径） info — 获取项目基本信息 list_blocks — 列出所有 Block list_architectures — 列出可用 FPGA 器件架构 list_parts(arch, package) — 按架构/封装筛选 Part 型号 list_processes — 列出可用的工艺角类型 select_part(part, process) — 更换 FPGA 器件型号 import_xpe(file, append) — 导入 XPE 文件 export_xdc(file, thermal, rails, overwrite) — 导出功耗约束为 XDC export_power_design(file, overwrite) — 导出 Power Design 为 XML reset — 重置项目（清除所有数据）

Args: action: 操作名称（见上方列表）。 session_id: 目标会话 ID。

统一的功耗查询/导出工具。

通过 action 参数选择子功能：

• summary: 项目总功耗摘要（静态/动态/结温）。每次调用自动保存快照。

• block_power: 某个 Block 的详细功耗分解（需 block_name）。

• rails: 各电源轨的电压、电流、功耗。

• thermal: 热分析结果（结温、环境温度、θ-JA 等）。

• clock_power: 各时钟域的功耗分布。

• export_report: 导出功耗报告为文本或 CSV 文件（需 output_path）。

Args: action: 操作类型：summary / block_power / rails / thermal / clock_power / export_report。 block_name: block_power 操作的 Block 名称。 output_path: export_report 操作的输出文件路径。 format: export_report 操作的输出格式，"text" 或 "csv"。 session_id: 目标会话 ID。

统一的场景管理入口——通过 action 参数选择操作。

Actions:

• "set_environment" — 设置环境参数（温度、风流量、散热器）。 需要 temp，可选 airflow（默认 250）、heatsink（默认 medium）。

• "set_clock_frequency" — 修改某个时钟的频率。 需要 name、freq_mhz。

• "set_toggle_rate" — 修改某个 Block 的信号翻转率。 需要 block、pct（0–100）。

• "set_resource_util" — 修改某个 Block 的资源用量（绝对数量）。 需要 block，可选 lut / ff / bram / dsp （-1 表示不修改对应项）。填入实际使用的资源数， 如 lut=50000 表示已用 50000 个 LUT。

• "recalculate" — 参数修改后重新计算功耗。

• "compare" — 对比最近两次功耗快照（依赖 power(action="summary") 保存的快照），

  10% 差异标记 WARN。

Args: action: 操作类型（见上）。 session_id: 目标会话 ID。 temp: 环境温度 (°C)（set_environment）。 airflow: 风流量 LFM（set_environment，默认 250）。 heatsink: 散热器类型 none/small/medium/large（set_environment，默认 medium）。 name: 时钟名称（set_clock_frequency）。 freq_mhz: 新频率 MHz（set_clock_frequency）。 block: Block 名称（set_toggle_rate / set_resource_util）。 pct: 翻转率百分比 0–100（set_toggle_rate）。 lut: 已用 LUT 数量（set_resource_util, -1 跳过）。 ff: 已用 FF 数量（set_resource_util, -1 跳过）。 bram: 已用 BRAM Tile 数量（set_resource_util, -1 跳过）。 dsp: 已用 DSP Slice 数量（set_resource_util, -1 跳过）。

Vivado 导入与对比工具 (单一入口)。

action: "import_report" — 导入 Vivado report_power 输出文件进行对比分析。 参数: report_path (必需), label (可选, 默认 "vivado_import")。 解析文件后缓存，供 compare 使用。 "compare" — 将导入的 Vivado 功耗数据与当前 PDM 结果逐项对比。 差异 >10% 标记 [WARN]。 参数: label (可选, 默认 "vivado_import")。 "import_utilization" — 从 Vivado 利用率报告自动填充 PDM Block 的资源参数。 参数: util_report_path (必需), block_name (可选)。

Args: action: 操作类型: "import_report" / "compare" / "import_utilization"。 report_path: Vivado .rpt 或 .txt 文件路径 (import_report 必需)。 label: 导入标签，用于多次导入区分，默认 "vivado_import"。 util_report_path: Vivado utilization report 文件路径 (import_utilization 必需)。 block_name: Block 名称，留空则填充顶层 Block。 session_id: 目标会话 ID。

统一时钟管理工具 — 通过 action 参数选择操作。

Clock 操作： list — 列出所有时钟 create — 创建时钟 (name, freq, io_type, io_standard, is_gated, min_freq) delete — 删除时钟 (name) edit — 编辑时钟 (name, freq, io_type, io_standard, is_gated, min_freq) settings — 获取时钟设置 (name) sample_settings — 获取时钟示例设置模板 replace — 替换时钟 (name, other, blocks)

Clock Manager 操作： mgr_types — 列出可用时钟管理器类型 mgr_list — 列出所有时钟管理器 mgr_create — 创建时钟管理器 (name, type, input_clock, vco_range) mgr_delete — 删除时钟管理器 (name) mgr_settings — 获取时钟管理器设置 (name)

Args: action: 操作类型，见上。 name: 时钟/管理器名称。 freq: 时钟频率 (MHz)。 io_type: IO 类型，如 "HD"、"HP"。 io_standard: IO 标准，如 "LVCMOS 1.8V"、"LVDS"。 is_gated: 是否为门控时钟 (create: bool; edit: "true"/"false"/"")。 min_freq: 最低缩放频率 (MHz)，0 表示无。 other: replace 时的目标时钟名称。 blocks: replace 时限定作用的 Block 列表，逗号分隔。 type: 管理器类型，如 "MMCM"、"DPLL"、"XPLL"。 input_clock: 管理器输入时钟名称。 vco_range: VCO 范围，"Low" 或 "High"。 session_id: 目标会话 ID。

综合 IP 管理工具。

Args: action: 操作类型。 - "types": 列出可用的 IP 类型。 - "list": 列出指定类型的 IP 实例（需 ip_type）。 - "create": 创建 IP 实例（需 ip_type + ip_name）。 - "delete": 删除 IP 实例（需 ip_type + ip_name）。 - "settings": 获取 IP 实例的当前设置（需 ip_type + ip_name）。 - "sample_settings": 获取 IP 类型的示例设置模板（需 ip_type）。 ip_type: IP 类型，如 "MIG"、"PCIE"、"GTH"。 ip_name: IP 实例名称。 session_id: 目标会话 ID。

Power Design 综合工具：信息查询、电源轨特性、电源传输设计、合并模式设置。

Args: action: 操作类型。 - "info": 获取 Power Design 概览（域、电源、汇总类型、合并模式）。 - "rail_characteristics": 获取 power_rail_characteristics 汇总表。 - "delivery_design": 获取 power_delivery_design 汇总表。 - "set_consolidation": 设置电源轨合并模式（需配合 mode 参数）。 mode: 合并模式，仅在 action="set_consolidation" 时使用。 session_id: 目标会话 ID。

统一探索入口，通过 action 参数选择子功能。

Actions: block_resources(block) 列出指定 Block 的资源名称。 block_summaries(block) 列出指定 Block 的汇总表名称。 resource_info(block, resource) 获取 Block 资源的字段名和记录名。 resource_defaults(block, resource) 获取 Block 资源的默认值。 resource_valid_values(block, resource, fields) 获取 Block 资源字段的有效值范围。fields 逗号分隔，留空获取所有。 summary_info(target, summary) 获取汇总表的字段名、记录名和当前值。target 为 "project" 或 block 名。 list_property(target) 列出 PDM 对象的属性名。target 为 "project" / block名 / "block.resource"。 report_property(target, pattern, all_props, detail) 报告 PDM 对象的属性。pattern 支持通配符和正则。 reset_property(target, prop) 重置 PDM 对象的属性为默认值。

Args: action: 操作名（见上方列表）。 block: Block 名称（block_* / resource_* 操作使用）。 resource: 资源名称（resource_* 操作使用）。 fields: 字段名，逗号分隔（resource_valid_values 使用）。 summary: 汇总表名称（summary_info 使用）。 target: 目标对象，"project" / block名 / "block.resource"。 pattern: 属性名匹配模式（report_property 使用）。 all_props: 是否报告所有属性（report_property 使用）。 detail: 是否报告详细帮助信息（report_property 使用）。 prop: 要重置的属性名（reset_property 使用）。 session_id: 目标会话 ID。

引导式功耗评估向导——逐步收集参数，给出选项，无需记忆工具名和参数。

每次调用返回下一步应该问用户什么问题，以及可选的选项列表。 AI Agent 负责向用户展示问题并收集回答，然后将回答作为 value 传入下一步。

典型流程::

guide(step="start")                                    → 询问器件型号
guide(step="device", device="xc7a100tcsg324-1")       → 询问评估模式
guide(step="mode", value="quick")                     → 询问时钟频率
guide(step="quick_clock", value="200")                → 询问 LUT 利用率
...                                                   → 逐步收集参数
guide(step="quick_heatsink", value="medium")          → 返回估算结果

Args: step: 当前步骤名。首次调用用 "start"。 value: 用户对当前步骤的回答。数字/字符串均可。 device: 器件型号（仅 step="device" 时需要）。