# 已知限制记录

本文件记录**当前版本已知、且无法在本项目内解决**的限制：它们由底层依赖的行为决定
（tree-sitter grammar、PowerShell 语义等），只能等上游修复或改变技术路线。

本文件不是任务清单。可修复的待办、跟进事项由代理的任务跟踪机制管理，不写在这里。

## 1. tree-sitter-bash：heredoc 之后同一行接命令列表 / 管道时解析不可信

tree-sitter-bash（ast-guard-core 内置 wasm）对「heredoc 重定向之后同一行还跟着列表
或管道」的写法处理错误——尽管它们都是合法 bash（`bash -n` 全部通过）。实测分两类：

| heredoc 之后接 | parseError | 提取结果 |
| --- | --- | --- |
| （收尾，无后续） | 无 | 之前的 `&&` 链完整；但紧邻 `<<` 的参数被吞（`git commit -q -F -` 的 `-` 丢失） |
| `;` 或 `&` | **有** | 空（fail-closed，安全） |
| `&&` 或 `\|\|` | 无（**假成功**） | **后续命令全部静默丢失** |
| `\|` 或 `\|&` | 无（**假成功**） | **管道右侧命令静默丢失** |
| 重定向（如 `2>&1`） | 无 | 完整（重定向可从 CST 恢复） |
| 重定向再接 `\|` | **有** | 空（fail-closed，安全） |

静默漏评型的根因在 grammar：`&&` / `||` / 管道右侧整体被吞进 `heredoc_redirect`
节点内部（CST 结构错误），提取层按 CST 走，无能为力。

最小复现：

```bash
cat <<'EOF' ; echo hi            # 报错型：heredoc 后接 ;
cat <<'EOF' & echo hi            # 报错型：heredoc 后接 &
cat <<'EOF' 2>&1 | tail          # 报错型：heredoc + 重定向 + 管道
{ cat <<'EOF' ; } 2>&1 | tail    # 报错型：{} 分组同样报错
cat <<'EOF' && rm -rf /tmp/x     # 静默漏评：只提取出 cat，rm -rf 绕过命令规则
cat <<'EOF' | tail -6            # 静默漏评：只提取出 cat，tail 丢失
git commit -q -F - <<'EOF'       # 静默漏评：argv 少了紧邻 << 的 `-`
hello
EOF
```

**影响**：

- 报错型：整条命令串（含 `&&` 连接的其他命令）解析失败、`commands` 为空，命令级规则
  （如 `git-add-all`、`git-commit`）不参与评估，只按 `settings.parseFailure` 处理
  （默认 `ask`；DNA 模式下 `settings.dna.parseFailure` 默认 `block`）。安全侧失败，
  只是可用性受损。
- 静默漏评型：无任何报错，按「能提取到的部分」评估——**heredoc 之后的命令完全不设防**
  （上例 `rm -rf /tmp/x` 不会命中任何命令规则）。这是安全相关缺陷，优先级高于报错型。

**规避写法（实测）**：

```bash
# 可靠：带 heredoc 的命令放整条命令串最后，后续命令拆到下一次工具调用
cd /e/x && git add -A && git status --short && git commit -q -F - <<'EOF'
…内容…
EOF
```

- 报错型没有可靠的一行式改写：`;` 换 `&&` 看似能解析，实际落入静默漏评型（更糟）；
  `{ }` / `( )` 分组照样报错。
- 需要处理管道输出时，把 heredoc 命令单独一次调用，管道另起一次。

**根治方向**（解析层在 ast-guard-core，不在本仓库）：

1. 升级 tree-sitter-bash grammar（核心仓库 `bun run grammars:sync`），确认上游是否已修；
2. 防御性兜底：提取层发现 `heredoc_redirect` 子节点中出现 `&&` / `||` / `|` / `&` /
   `command`，或管道 `commandIds` 与实际段数不符时，按 parseFailure 处理（fail-closed）。

修复工作在 ast-guard-core 仓库跟进（grammar 升级 + 提取层防御性兑底）。

## 2. PowerShell 内联 C# / COM 调用无法静态识别

`Add-Type -TypeDefinition @'...'@`、`[Activator]::CreateInstance(...)` 等内容内联了
C# / COM 代码，可在运行期执行任意文件操作，而解析层只看到命令名与参数文本。

**影响**：这类命令内部的文件访问不会命中路径规则，保守处理为 dynamic，按 `ask` 兜底。

## 3. PowerShell 管道传对象而非字节流

pwsh 管道传递 .NET 对象，bash 的字节流语义（`2>&1 |`、stderr 是否入管道等）在 pwsh 中
并不等价。

**影响**：涉及管道 fd / stderr 的判定在 pwsh 脚本上按保守近似处理，不保证与 bash 一致。