---
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 在执行前自动拦截，此处不再重复。