Qoder参数问题源于变量作用域规则：全局参数在顶层声明，局部参数在函数或迭代块内声明；需通过传参、with语句或as关键字显式传递；禁止直接修改全局参数，须用setpath、reduce等合规方式输出；同名参数会遮蔽全局变量；调试可用debug、keys和type等命令定位作用域问题。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您在使用Qoder处理数据流时遇到参数不可见、值未更新或意外覆盖等问题，则很可能是由于变量作用域规则未被正确遵循。以下是针对Qoder中全局与局部参数传递逻辑的详细解析：
一、理解Qoder中的变量声明位置与默认作用域
Qoder沿用类jq语法风格，变量作用域由其声明位置严格决定：在顶层上下文（即未嵌套于任何函数或过滤器块）中声明的参数视为全局参数，可在整个管道中读取；而在def定义的函数内部或reduce/foreach等迭代块内声明的参数则为局部参数，仅对该块内后续语句可见。该机制防止跨阶段污染，但也要求显式传递必要值。
1、在顶层使用param $timeout = 3000声明参数，该$timeout在整个脚本生命周期内可被任意过滤器引用。
2、在def retry($max): ...函数体内使用param $attempt = 0，此$attempt仅在retry函数执行期间存在，外部无法访问。
3、若在map(.data | $timeout * 2)中直接引用$timeout，该引用有效；但若在map(.data | $attempt * 2)中引用$attempt，则触发Undefined variable: $attempt错误。
二、全局参数向局部作用域显式传入的三种方式
当局部代码块需依赖全局参数时，必须通过明确机制将其引入当前作用域，避免隐式查找失败。Qoder不支持自动向上层作用域回溯解析未声明变量。
1、将全局参数作为函数调用的实参传入：retry($timeout)，并在函数定义中声明形参def retry($t): ...，此时函数体内使用$t而非$timeout。
2、使用with语句临时注入命名空间：with $timeout as $t | .data | $t * 2，该写法在单次表达式中建立局部绑定，不影响外部$timeout值。
3、在迭代块内通过as关键字捕获外部变量：[1,2,3] | map(. as $i | $timeout + $i)，此处$i是局部迭代变量，而$timeout仍为原始全局参数，二者共存无冲突。
三、局部参数反向影响全局状态的合规路径
Qoder禁止在局部作用域内直接赋值修改全局参数，以保障管道的纯函数特性。若需持久化中间计算结果并供后续阶段使用，必须采用符合数据流范式的显式输出机制。
1、通过setpath将局部计算结果写入输出对象特定字段：def calc: .value as $v | setpath(["meta","computed"]; $v * $timeout)，后续阶段可从.meta.computed安全读取。
代码编辑 CLI 工具集合：Cursor CLI（agent）和 Qoder CLI（qodercli），用于代码修改、重构、Code Review 及自动化代码任务。
2、使用reduce累积全局状态，将局部更新合并进累加器：reduce .[] as $item ({}; .count += 1 | .sum += $item * $timeout)，最终输出对象包含.count和.sum两个聚合字段。
3、调用debug配合日志提取关键局部值，再由外部调度器捕获并重新注入为新全局参数，实现跨执行周期的状态延续。
四、同名参数遮蔽（Shadowing）的识别与规避
当局部参数与全局参数同名时，局部声明会完全遮蔽全局版本，且该遮蔽不可撤销。这种设计虽增强封装性，但也易引发静默逻辑偏差，需主动识别并规避。
1、检查函数定义头部是否存在与已知全局参数同名的形参，例如全局有param $format = "json"，而函数定义为def render($format): ...，则函数内所有$format引用均指向形参而非全局。
2、在函数内部使用$ARGS.positional[0]或$ARGS.named.format显式访问原始命令行参数，绕过形参遮蔽，适用于需动态切换格式的场景。
3、对必须保留全局语义的参数，在局部作用域中重命名使用：def process($f): ... | $f as $local_format | ...，确保全局$format原始值始终可用。
五、调试作用域问题的核心命令组合
当参数行为异常时，应立即启用Qoder内置调试能力定位作用域边界，避免猜测性修改。所有调试操作均不改变原始数据流，仅输出诊断信息。
1、在可疑位置插入debug | .，观察控制台输出的完整上下文对象，确认目标参数是否存在于当前作用域键集中。
2、使用keys过滤器列出当前作用域全部可访问键名：debug | keys，比对预期参数名是否缺失或拼写差异。
3、结合type和isnull验证参数存在性与类型：if $timeout | isnull then "timeout missing" else "timeout: \($timeout|type)" end | debug，精准区分未定义与空值。
