Startlux-Decision 该从哪个入口调用，一般不能靠目录名字猜。可以先判断三件事：仓库里有没有可执行的 CLI 脚本、有没有对外暴露的包函数、有没有一条已经写好参数的服务启动入口。三者同时存在时，建议先用 CLI 加最小输入跑一遍，因为它最容易把“入口是否找对”和“参数是否填错”两类问题分开暴露；确认链路通了，再决定要不要换成代码调用。
不确定入口时，先按仓库线索定位候选：启动脚本、包导出、示例代码各查一遍，再选一条验证成本最低的链路跑最小示例。先只填必填字段，用是否返回结构化输出作为通过标准。若报 command not found、import error 或 schema error，按错误类型分别排查路径、依赖与字段，不要在同一轮里同时改多个变量。
翻目录定位可能入口，不靠猜
先从仓库里找线索，而不是先读全部源码。常见线索包括：顶层 README 与配置清单、声明命令行入口的清单文件、examples/ 或 scripts/ 目录、以及包初始化文件里的导出列表。路径按你本地实际情况替换，下面命令只给骨架：
# 1. 看顶层目录，先判断它是 CLI 工程、服务工程还是库
find [your-repo] -maxdepth 2 -type d
# 2. 找命令行入口声明（不同语言命中会不同）
grep -rn `--include`="*.toml" `--include`="*.json" `--include`="*.cfg" \
-E "console_scripts|\"bin\"|entry_points|\[\[bin\]\]" [your-repo]
# 3. 找示例与主函数
find [your-repo] -maxdepth 3 -type f \( -name "example*" -o -name "demo*" -o -name "main.*" \)
grep -rn `--include`="*.py" `--include`="*.js" `--include`="*.ts" \
-E "def main|argparse|click|typer|commander" [your-repo]如果命中结果是包导出而不是命令行入口，说明它更可能是库调用；如果命中的是启动脚本加端口配置，那更接近服务入口。先记下候选名字，不要在这一步安装或改动任何依赖。
用最小示例决定先调 CLI 还是代码
两条链路的验证成本不同。CLI 的优势是路径问题会立刻以错误信息暴露出来，劣势是参数解析层可能先报错，掩盖真正的决策逻辑；代码调用的优势是能直接观察返回值类型，劣势是包未安装或路径不对时报错没那么直观。建议先用 CLI 走到“能打印出结果”，再用代码调用确认返回值结构。
# 链路 A：命令行
[your-cli] `--help`
[your-cli] decision `--input` [path/to/min_input.json]# 链路 B：代码调用
from [your_package] import invoke_decision
result = invoke_decision(input)
print(type(result))
print(result)通过标准不是“没报错”，而是能拿到结构化输出，例如字典、列表或可解析的 JSON 文本。若 CLI 只回显帮助信息，说明子命令名不对；若代码调用打印出 None 或自定义对象但没有字段，说明入口对了但输入不满足要求。两条链路都通之后再考虑接业务数据，能省掉一轮排查。
构造一条最小决策输入
最小输入的目的是减少参数干扰。先只填必填字段，可选字段留空，看返回是否正常，再逐项加回。下面只是通用结构，字段名和层级必须以你实际使用的 schema 为准：
{
"context": {},
"options": [
{ "id": "option_a" },
{ "id": "option_b" }
]
}把 context、options 以及每个 option 的字段理解成占位符，不要直接照抄字段名。验证方式有两种：一是返回结构里包含预期字段，例如选中项标识；二是若字段缺失或类型不符，入口通常会给 schema 相关报错，报错信息本身就能反过来确认必填项有哪些。若返回结构为空但无报错，优先怀疑必填字段名拼写或嵌套层级不对，而不是先怀疑模型能力。
从报错定位入口、参数或依赖问题
把错误分成四类，能更快确定该改哪一层。下面表格里的命令都是通用骨架，命令名按实际替换。
| 现象 | 大概率落在哪一层 | 检查动作 | 下一步 |
|---|---|---|---|
| command not found | 入口层：命令没装或不在 PATH | which [your-cli]、ls [venv]/bin | 改用 python -m [module]，或确认虚拟环境已激活 |
| import error / ModuleNotFoundError | 依赖层：包未安装或工作目录不对 | python -c "import [your_package]"、pip show [your_package] | 安装本地包或临时设置 PYTHONPATH，再重跑 |
| schema error / 字段校验失败 | 参数层：字段名、类型或层级不符 | 用最小 JSON 二分删除字段，看报错是否消失 | 只保留必填字段，逐个加回定位问题字段 |
| timeout / 长时间无返回 | 依赖服务或输入规模 | 查看运行日志尾部，必要时加 timeout 10 [your-cli] ... | 先确认下游服务可达，再缩小输入规模 |
判断顺序建议从上往下：先确认命令存在，再确认依赖可导入，再确认输入合法，最后才看超时。跳过前两层直接调参，通常会在错误的地方浪费时间。
保存可复现的最小调用记录
跑通一次之后，把命令固定成脚本，避免下次重新摸索参数。脚本里只保留最小输入和日志落盘，不掺业务数据：
#!/usr/bin/env bash
set -euo pipefail
INPUT="${1:-./min_input.json}"
LOG="${2:-./run.log}"
[your-cli] decision `--input` "$INPUT" 2>&1 | tee "$LOG"用 bash run_min.sh 执行，结果会同时打印到终端并写入 run.log；若走代码链路，同样把输入路径和输出重定向到文件即可。需要替换的占位符清单：入口命令名、子命令名、输入文件路径、日志路径、虚拟环境激活路径、包名或模块名。日志位置建议和脚本放在同一目录，方便连同输入文件一起提交到问题记录里。这样记录下来的调用链，别人按同样步骤也能复现同一入口和同一输入。