跑 Startlux-Decision 的本地决策任务，卡点通常不在模型本身，而在于运行时实际连的是哪个推理后端、以及输入有没有越过模型能接受的边界。建议先把这两件事分开确认：后端指向和连通性一次，最小输入链路一次。这两步没走通之前就去调输入细节或更换模型，很容易把环境问题和数据问题混在一起。

先分清「环境没就绪」和「输入不合法」两类失败，再谈输出是否合理。适用场景是刚拿到仓库、还没有已知可用配置。操作动作是执行仓库给定的启动入口并记录首条错误，再跑一条最小输入看返回码和 stdout。验证以后端连接日志、进程监听状态和退出码为准。风险边界是：不要用空输入或超长输入去判断环境是否正常，那会让两类问题互相遮掩。

在目标机器上确认运行入口和依赖是否就绪

先把失败分成三类：环境缺失（解释器、依赖包、系统库没装齐）、模型文件缺失（权重路径写错或文件不完整）、服务未启动（推理进程没有进入监听）。这三类在日志里的首条错误不同，先归类再处理，比逐个试命令有效。

从仓库说明里找到安装与启动入口，把它们当作占位命令执行，重点记录返回码和第一条错误，而不是整段日志。

# 占位：替换为仓库说明中的安装入口
<install-command>
echo "exit=$?"

# 占位：替换为仓库说明中的启动入口
<start-command> 2>&1 | tee start.log
echo "exit=$?"
head -n 20 start.log

判断方式：安装命令返回非 0，且首条错误是可识别的导入或依赖报错，优先补环境；安装返回 0 但启动时报找不到模型文件，先去核对模型目录的绝对路径和读取权限；启动没报错但后续调用连接被拒，多半是推理服务没有真正进入监听状态。

把推理后端指向可用服务并核对配置字段

Startlux-Decision 运行时读的可能是本地后端，也可能是远端后端，配置字段名各仓库不同，先以仓库示例为准。下面只是通用骨架，值都需要替换。

backend:
  type: <local | remote>        # 按实际字段名替换
  endpoint: <http://host:port>  # 后端地址，本地也要写清
  model_path: </abs/path/to/model>
  timeout_ms: <整数>

input:
  max_length: <整数>           # 输入长度上限，按仓库字段名替换
  truncate: <true | false>      # 超长时截断还是拒绝

验证方式是看启动日志：出现指向 endpoint 的连接成功记录，说明后端地址被正确读取；出现 connection refused、timeout 这类明确报错，说明地址、端口或服务状态有问题。如果连接成功但随后报模型加载失败，说明后端是通的，问题在 model_path。把这次启动日志单独存下来，后续对照用。

<start-command> 2>&1 | tee -a start.log
grep -iE "connect|refused|timeout|load|ready|listen" start.log

需要留意的是，改了配置但没重启进程，是常见的假象；确认进程启动时间晚于配置文件修改时间，再判断配置是否生效。

用一条最小决策输入跑通完整链路

后端确认之后，用一条最小输入把解析、调用、输出三段串起来。下面的字段名都是占位，需要按仓库实际的输入 schema 替换；不确定时先找仓库里的示例输入文件，改值而不是改结构。

{
  "input": "<一个最小可判定的问题>",
  "candidates": ["<候选A>", "<候选B>"],
  "max_tokens": 64
}

运行时把标准输出和标准错误分开留档，退出码单独记录：

<run-command> `--input` minimal.json > out.json 2> err.log
echo "exit=$?"
cat out.json
tail -n 20 err.log

贯通的标准是：退出码为 0，out.json 里有可解析的结构化结果。退出码非 0 时，先看 err.log 第一行是输入解析错误还是连接错误——前者说明链路已经走到解析层，问题在输入；后者说明调用还没发出去，问题仍在后端或网络。

测试输入边界和截断行为

最小输入跑通只说明链路通，不代表边界行为符合预期。建议按下面四类各测一次，逐条记录返回码和返回内容，而不是只看成功与否。

• 空输入：input 给空字符串，或候选列表为空。观察是参数校验直接拒绝，还是走到模型层再返回空结果。
• 超长输入：长度明显超过配置里的 max_length。观察是截断后照常返回，还是直接报长度超限。
• 多候选输入：候选数量超过示例中的规模。观察是拒绝、截断候选，还是只取前若干个。
• 字段缺失或类型错误：例如把 candidates 给成字符串。观察校验层是否在调用前拦下。

判断发生在哪一层，看日志位置比看返回码更直接：日志里出现 truncat、length 之类字样，通常是在分词或预处理阶段做了截断；出现参数校验失败、schema 不匹配的报错，通常是在输入校验层被拒绝，此时请求还没到后端。把两类行为的日志片段分开保存，可以避免以后把校验失败误判成后端不稳定。

truncate 开关的含义要按仓库实现确认：有的实现是超长即截断，有的实现是超长即拒绝。两种行为对下游决策结果的影响不同，需要结合自己的输入长度分布决定保留哪种。

整理可复现的成功与失败命令记录

排障过程中最有用的产出，是一条能重复执行的命令记录。建议按下面的模板逐项填写，把命令、配置片段、返回码、日志片段和判断放在一起，下次遇到同类现象可以直接对照。

[环境]     命令：<install-command>   返回码：   首条错误：
[启动]     命令：<start-command>     返回码：   日志关键行：
[后端]     配置：backend.endpoint=     日志：connect ok / refused / timeout
[链路]     命令：<run-command>       返回码：   stdout 首行：
[空输入]                            返回码：   表现：拒绝 / 空结果
[超长输入]                          返回码：   表现：截断 / 拒绝，日志层：
[多候选]                            返回码：   表现：
[类型错误]                          返回码：   表现：校验层拒绝 / 后端报错

结论表可以按这个顺序用：启动即失败且首条错误是导入或依赖报错，归到环境；启动时报找不到模型文件，归到模型路径；启动正常但调用被拒或超时，归到后端地址与服务状态；解析或校验错误出现在连接错误之前，归到输入格式。每次只改一个变量并重跑同一条命令，才能把判断对应到具体改动上。