Neo-ZQYY/.kiro/steering/cli-env.md

inclusion

inclusion
always

CLI 环境规范（Windows PowerShell）

本项目运行在 Windows + PowerShell 环境。以下是构造命令时必须掌握的前置知识。

PowerShell 语法要点

• 环境变量：$env:VAR_NAME（不是 $VAR_NAME）
• 命令连接符：;（不是 &&）
• where 是 Where-Object 别名，查可执行文件用 Get-Command <name>
• 删除文件/目录：Remove-Item（不是 rm -rf）
• 路径分隔符 \，但 Python/Node 工具也接受 /

Python 调用

• 项目虚拟环境：uv run python 或 .venv\Scripts\python.exe
• 安装依赖：uv sync（不是 pip install）
• 运行模块：uv run python -m <module>
• 系统 Python：python（来自 miniconda3）

Shell 隔离与 REPL 防护（强制）

背景：Kiro 的 executePwsh 复用同一个 shell session。若意外进入 Python REPL，后续所有命令被吞掉，表现为"无输出 + exit code 0"。

核心原则

• 禁止裸调 python/node/ipython——必须带 -c、-m 或脚本路径
• 优先写脚本文件再执行，避免 -c 内联引号地狱
• 禁止管道喂给 python（如 echo "code" | python）

长时间命令

• 预估 > 30s 的命令，提前告知用户
• pytest hypothesis 建议设 timeout 为预估时间 3 倍
• 超时后不要立即重试，先确认前一个进程状态

REPL 劫持

症状：exit code 0 但无输出、连续命令无输出、出现 >>> 提示符。检测与自动恢复由 repl-hijack-guard hook 在命令执行后自动处理。

cwd 校验和命令语法检查由 cwd-guard-shell hook 在执行前自动拦截，此处不再重复。