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