适用范围:App「Algorithm Load」运行器注入给 Python 脚本的公开接口(api、loop、pailink 辅助模块)。
MCP 自动化接口(pbt_mcp)不属于本文范围。
整理依据(本机 RC18 安装包实测,非凭记忆):
extension/case/User_Development_Docs.md(官方用户开发文档,490 行)extension/examples/** 下全部示例脚本的实际调用extension/examples/projects/*/README.md、docs/*.md.appdata/logs/script.log 与实验包 output/experiments/run-*标注「示例未使用」的接口表示文档已列出、但随附脚本没有实际调用;其行为描述以文档为准。
脚本启动时由运行器注入,无需 import:
| 对象 | 说明 |
|---|---|
api |
主控制对象 |
ctx |
api 的别名(同一对象) |
loop(interval_sec) |
主循环控制器,自动处理停止请求 + 周期节流 + 单调时钟漂移补偿 |
math |
标准库 math |
pd / pandas |
pandas(未安装则为 None) |
print(...) |
已重定向到日志面板,等价 api.log(...) |
导入方式有两种,都有效:
# 推荐(App 内运行 + 外部 IDE 补全)
from pailink import api, loop
# 兼容旧脚本(兼容窗口内继续有效)
from algorithm_load.script_runtime import api, loop
pailink 在 App 外由 pailink-script-sdk Wheel 提供;随附示例用 api.runtime_info() 探测运行时,失败则抛 SDKRuntimeUnavailableError 并回退到 pailink_simulation:
try:
api.runtime_info()
except SDKRuntimeUnavailableError:
from pailink_simulation import create_runtime, load_project_parameters
| 接口 | 说明 |
|---|---|
api.now() |
当前运行时逻辑时间戳(秒,float)。控制逻辑必须用它代替 time.time() |
api.elapsed() |
脚本已运行的逻辑秒数;仿真模式按 speed 推进 |
api.sleep(seconds) |
可中断睡眠,收到停止请求会尽快返回 |
api.should_stop() -> bool |
是否收到停止请求 |
loop(interval_sec) |
推荐主循环;等价 api.loop(interval_sec) |
api.run_mode |
只读:"simulation" 或 "deployment",脚本不能改 |
硬性规则(文档明确要求):
# 正确
t0 = api.now()
for _ in loop(period_s):
elapsed_s = api.now() - t0
# 错误:仿真加速下时间线会错乱
t0 = time.time()
不得在控制逻辑中使用 time.time()、time.sleep()、time.perf_counter()、datetime.now()。
loop() 可正常 break / continue;自行写 while 时必须轮询 api.should_stop() 并用 api.sleep() 节流。
仿真速度不是无限加速:当每 tick 的真实 CPU/IPC 开销超过 period_s / speed 时,脚本以机器最快速度运行,但逻辑时间仍按 loop() 周期推进。
| 接口 | 说明 |
|---|---|
api.log(text) |
输出到界面日志区;进入 logs/algorithm.log 与实验包 |
api.set_script_name(name) -> str |
设置能源看板显示的算法名;空串恢复脚本文件名 |
api.set_script_status(status) -> str |
设置当前运行阶段;空串清除 |
api.script_name / api.script_status |
读取本进程内已设置的值 |
日志是事后核对的主要依据,但注意:日志里的"命令已提交"只表示进入本机控制队列,不代表远端已执行。
| 接口 | 说明 |
|---|---|
api.get_parameter(name, default=None) |
读取本项目 project.json 中声明的参数 |
api.parameters |
当前运行的只读参数映射 |
规则:
api.get_parameter() 读取,界面参数才参与计算。project.json 会造成"界面改了不生效"的假象——随附的网络案例 1/2/3 因此都没有声明参数。interval_s = float(api.get_parameter("interval_s", 1.0))
| 接口 | 说明 |
|---|---|
api.publish_metric(key, value, quality="estimated") |
发布一条算法指标,进入指标面板与实验包 metrics/latest.json |
约定与限制:
device.* 是平台保留命名空间,project.json、api.metric()、api.publish_metric() 都不得使用。V1/I1/P1/V2/I2/P2 不要用 publish_metric 重发;在指标面板右键"节点遥测"即可按需读取 Plot 历史(最多 16 条,1 Hz 快照,切换通讯目标会清空旧快照)。quality 取值:随附全部示例统一使用 "estimated"(182 处);工程文档约定的语义是实测值用 good / stale(按在线状态),模型/虚拟功率/CSV 输入用 estimated。案例 3 的 README 明确写了这条约定。scripts/schema.py 拿强类型句柄(App 维护该文件):from pailink.project import Metric, project
USER_NETWORK_ALLOCATED_TOTAL_W: Metric[float] = project.metric(
key='user.network.allocated_total_w',
value_type=float, unit='W', minimum=None, maximum=None,
max_points=10_000, max_age_s=1_800.0, max_publish_hz=20.0,
persist=False, description='当前按权重分配后提交的总功率。',
)
schema.py 是自动生成区,自定义代码不要写进去(# <pailink:auto-generated ...> 段)。
推荐属性写法:api.node[1].p = 30.0
| 接口 | 说明 |
|---|---|
api.node[node].p = value |
设置功率 |
api.node[node].v = value |
设置电压(恒压) |
api.node[node].i = value |
设置电流 |
api.node[node].shutdown() |
下发单节点关机 |
api.node[node].step(field, current, target, steps, step_seconds) |
分步变化,field 为 p/v/i |
api.node[node].step_p / step_v / step_i |
上者的同步封装 |
api.step_node(node, field, current, target, steps, step_seconds) |
函数式同义接口 |
api.set_broadcast_p(value) / _v / _i |
广播设定 |
约束:
node 传整型,p/v/i 传可转 float 的数值。|I| ≤ 100.000 A,-100.000 V ≤ V ≤ 100.000 V)。先决条件:本机 App 为 network master,目标 App 为 online slave。
| 接口 | 说明 |
|---|---|
api.net[target].node[node].p = value |
远端节点功率 |
api.net[target].node[node].v = value |
远端节点电压 |
api.net[target].node[node].i = value |
远端节点电流 |
api.net[target].node[node].shutdown() |
关闭远端节点 |
api.net[target].broadcast.p / .v / .i = value |
远端广播设定 |
api.net[target].algo.on() |
启动远端 App 当前已配置脚本 |
api.net[target].algo.off() |
停止远端脚本并执行现有停机流程 |
target 推荐用网络设置中的持久化 device_id,也兼容当前 IP。api.net 写入成功不等于远端执行成功。| 接口 | 返回 |
|---|---|
api.node[n].get_data() |
dict \| None |
api.node[n].get_data("v1") |
单字段值 |
api.node[n].get_data(["v1", "i1"]) |
DataSelection(可按序解包、.v1 属性、["i1"] 下标、.as_dict()) |
api.node[n].get_data(timeout=0.3) |
显式等待最新数据 |
api.get_node_data(node, timeout_s=0.0) |
函数式等价接口 |
api.get_latest_node(node, timeout_s=0.3) |
兼容别名 |
读取语义:timeout <= 0 立即返回缓存(无缓存为 None);timeout > 0 最多等待该秒数,超时后可能返回缓存或 None。
timeout 必须写成关键字参数(第一个位置参数留给字段名,不要写 get_data(0.3))。
返回 dict 典型字段:node、online、timestamp、v1、i1、p1、v2、i2、p2、raw、idx7_raw_u32、page、StatusMode、RunMode、Board、CalibrationMode、Fault、Reserve 及对应 *Label。
新脚本建议优先用 v1 / i1 / p1(避免通道歧义)。get_data 可能返回 None,必须判空。
result = api.net[target].node[node].get_data(timeout=0.3, max_age=5.0)
始终返回结构化结果(不是裸数值):
| 字段 | 含义 |
|---|---|
valid |
六个电气通道是否全部有效 |
reason |
整体无效原因 |
values |
按 V1/I1/P1/V2/I2/P2/运行时间/协议值 排列;无效通道为 None |
valid_mask |
每通道有效性;单独使用某通道前必须检查对应位 |
channel_reasons |
每通道无效原因 |
units / channels |
单位与通道名 |
age_ms |
每通道数据年龄 |
received_at_ns |
本机接收时钟 |
source_timestamps_ns |
来源机器时钟 |
evaluated_at_ns |
接收端评估时间(网络案例用它做"启动后新样本"围栏) |
schema_version / source / device_id / target / node |
身份与协议标识 |
默认过期阈值 5 秒,最多等待 2 秒;timeout=0 读取缓存并请求更新。
旧快照缺通道元数据、无数据、离线、过期、缺来源时间、查询超时均明确无效。
设定值/模型值/回退估计必须单独命名,不能写进这份实测结果。
extension/examples/projects/network-case*/scripts/network_bus.py 是一份完整的严格校验实现,值得作为模板:
data = api.net[bus["device_id"]].node[bus["cv_node"]].get_data(timeout=0.0, max_age=1.0)
# 依次校验 schema_version / source / device_id / target / node /
# channels[index] / units[index] / valid_mask[index] / channel_reasons[index] /
# values 有限性 / age_ms / received_at_ns / source_timestamps_ns
# 再判断 |value - voltage_v| <= voltage_tolerance_v
| 接口 | 说明 |
|---|---|
api.soft_start_node_p_sigmoid(targets, duration_s, steps=..., shape=..., start_value=0.0) |
对一组节点按 S 形曲线从 start_value 平滑升到各自目标功率 |
实际调用(pro_case1_8node_2subnet_pv_bat_load_pcc.py:207):
first_targets_p = {1: ..., 3: ..., 2: ..., 5: ..., 7: ..., 6: ...}
api.soft_start_node_p_sigmoid(
first_targets_p,
soft_start_duration_s, # 10.0
steps=soft_start_steps, # 40
shape=soft_start_shape, # 10.0
start_value=0.0,
)
本机运行记录验证:soft-start(sigmoid): nodes=6, duration=10.000s, steps=40, shape=10.000, start_value=0.000,日志随后打印 Soft-start done。
| 接口 | 说明 |
|---|---|
api.datarecord.start() / api.datarecord.stop() |
启动/停止 App 自带 Data Log / DataRecord(示例未使用) |
api.record_row(values, table="algorithm_values") -> bool |
往独立 CSV 写一行算法变量(示例未使用,模板中列出) |
record_row 语义:
datarecord 相互独立,默认不与 CAN/DataRecord CSV 并表。table 一个 CSV;首次成功调用固定字段集合与列序,之后可换键序但不能增减字段。wall_time_ns、runtime_elapsed_s、sequence(每表从 1 开始)。True 仅表示进入 Worker 本地有界队列;队列满、记录器关闭、磁盘错误返回 False。None、bool、int、有限 float、≤4096 字符字符串;每行最多 32 个用户字段;非法输入/结构变化抛 ValueError。PYQTEXP_OUTPUT_DIR 时为 <output>/algorithm_runs/<script>_<timestamp>_<session>/,否则回退到脚本旁 runtime_records/。本机实测:所有随附案例都没有调用
datarecord或record_row,因此实验包里的metrics/与telemetry/来自其他机制,不是脚本 CSV。
pailink 辅助模块| 名称 | 说明 |
|---|---|
PowerClamp(api, node_limits=template_node_limits((1, 2, 3))) |
按节点内置限值裁剪功率指令;示例用 clamp_p(node, value) 下发 |
PowerClamp.node_limits |
该实例覆盖的节点集合 |
PowerClamp.clamp_p(node: int, value: float) |
裁剪并下发 P 指令;裁剪会改变实际下发值 |
template_node_limits(nodes) |
按实验台模板生成节点限值映射 |
normalize_run_duration_s(run_duration_s) |
把 <=0 / "inf" 归一成 None(无限运行),否则返回 float 秒 |
project.context() |
当前工程上下文(schema.py 使用) |
project.metric(...) |
声明强类型指标句柄(schema.py 使用) |
SDKRuntimeUnavailableError |
App 外运行 SDK 时的探测异常 |
api / loop |
供外部 IDE 导入的同名公开接口 |
裁剪日志示例(本机实测):clamp_p: total limits now [-15.000, 40.000] W (normal)。
客户指南提示:任一子网发生裁剪时,该子网的本地理论平衡可能失效,需结合裁剪日志与硬件遥测判断。
| 接口 | 说明 |
|---|---|
api.require_capability(name) |
声明脚本需要的能力;能力不足时拒绝运行 |
api.send_node_raw(node, payload) |
直接下发 8 槽浮点原始载荷(仅设备身份/标定读取类脚本使用) |
api.runtime_info() |
运行时信息/探测;App 外调用抛 SDKRuntimeUnavailableError(返回字段未在文档中给出) |
api.to_seconds_series(df, time_col) |
时间列转秒(数值 / datetime 字符串 / 时长字符串) |
api.to_relative_time(df, time_col, speedup=1.0, out_col=None) |
转相对时间并可加速 |
api.replay_relative_schedule(schedule, send_event, ...) |
按相对时间高精度回放事件序列 |
本版本实际出现的能力名只有两个(field_can_cv_characterization.py:293-294):
api.require_capability("node.command.write")
api.require_capability("node.telemetry.read")
send_node_raw 只在 test_readuid.py 中使用(8 槽 payload,第 5 槽作为标记值)。
| 接口 | 8 节点 pro 案例 | network 案例 1 | network 案例 2 | network 案例 3 | field-can 诊断 |
|---|---|---|---|---|---|
api.log |
✓ | ✓ | ✓ | ✓ | ✓ |
api.now |
✓ | 间接¹ | ✓ | ✓ | — |
api.elapsed |
— | — | — | — | ✓ |
api.sleep |
✓ | 间接¹ | 间接¹ | 间接¹ | ✓ |
api.should_stop |
✓ | 间接¹ | ✓ | ✓ | ✓ |
loop(...) |
✓ | — | ✓ | ✓ | — |
api.run_mode |
— | ✓ | ✓ | ✓ | ✓ |
api.node[n].p/.v |
✓ | — | — | — | ✓ |
api.node[n].shutdown |
✓ | — | — | — | ✓ |
api.net[...].node[n] |
— | ✓ | ✓ | ✓ | — |
node.get_data(...) |
— | ✓²(远端) | ✓²(远端) | ✓²(远端) | ✓(本地) |
api.publish_metric |
✓ | ✓ | ✓ | ✓ | — |
api.set_script_name/status |
— | ✓ | ✓ | ✓ | ✓ |
api.soft_start_node_p_sigmoid |
✓ | — | — | — | — |
PowerClamp / template_node_limits |
✓ | — | — | — | — |
api.require_capability |
— | — | — | — | ✓ |
¹ 通过共享的 network_bus.py 间接调用(wait_interruptibly / NetworkBusGuard)。
² 通过 NetworkBusGuard._voltage() 调用远端结构化 get_data。
api.run_mode == "deployment";随附网络案例都显式检查。ENABLE_REAL_CONTROL 前置开关:三个网络案例默认 False,只在打印提示后返回,不访问 api.net。打开前必须替换占位 device_id。api.sleep / loop / should_stop 响应停止请求;硬安全锁存后命令被丢弃,必须先复位,脚本不能绕过。api.net 写入成功、日志"已提交"只代表进入本机队列,远端是否执行需看从机日志或实测。p/v/i 或启动远端算法;仿真与无网络构建保留各自的能力限制。api.log() 留痕;数值变量带单位后缀(power_w、voltage_v)。from algorithm_load.script_runtime import api, loop 在兼容窗口内仍有效;新脚本推荐 from pailink import api, loop。api.get_parameter() 是工程参数生效的唯一入口;未使用它的常量不会被界面修改影响。get_data 改为结构化契约(valid / valid_mask / channel_reasons / age_ms / 双时间戳),旧脚本若把返回值当裸值用需改造。device.* 指标命名空间为平台保留。