command-execution

命令执行指南

这是一项严格的指南。 请严格遵守以下规则。

AI Agent 执行命令和运行脚本时的指南。

---

核心规则

1. 切勿在主机上运行项目工具

保持主机环境干净。 所有项目工具（pnpm、npm、python、pip、pytest、cargo 等）都位于 devcontainer 中。切勿在主机上安装软件包、运行构建或执行项目命令。

如果需要在项目中运行命令，请使用 devcontainer：

# ✅ Correct: execute inside the container
docker exec -it <container_name> pnpm install
docker exec -it <container_name> pnpm build
docker exec -it <container_name> pytest

# ❌ NEVER: run project tools on the host
pnpm install          # installs to host, pollutes system
pip install requests  # modifies host Python
npm run build         # uses host Node version, may differ from container

例外情况（可在主机上使用的工具）：

• git — 版本控制在主机级别
• docker / docker compose — 管理容器
• gh — 用于仓库操作的 GitHub CLI
• npx skills — 安装技能（不会修改项目依赖）
• 文件操作（cat、ls、grep、find 等）

在容器外跨多个项目工作时，请仅进行文件读取、git 操作和 docker 命令。如果需要构建、测试或安装，请进入容器执行。

2. 使用项目的开发者 API

始终使用根目录 package.json 中的脚本：

# ✅ Correct
pnpm lint
pnpm provision:dev
pnpm build:frontend

# ❌ Wrong
cd infrastructure && npx cdk deploy
cd frontend && npm run build

原因：根目录脚本就是开发者 API。绕过它们可能导致 API 悄然失效。

2. 切勿使用 cd

# ❌ Wrong
cd infrastructure && pnpm synth

# ✅ Correct
pnpm synth:dev

# ✅ Or use working_dir parameter
execute_bash(command="pnpm synth", working_dir="infrastructure")

原因：cd 不会持久生效。请使用根目录脚本或 working_dir 参数。

3. 先查找脚本

# Check available scripts
cat package.json | grep -A 50 '"scripts"'

查找：lint、test、build、provision:*、deploy:*

---

安装

# ✅ Workspace root (shared)
pnpm add -D -w eslint

# ✅ Specific workspace
pnpm add -D eslint --filter frontend

# ❌ Wrong
cd frontend && pnpm add eslint

---

必须直接执行时

1. 先检查是否存在根目录脚本
2. 如果可用，请使用 working_dir 参数
3. 说明为何不使用根目录脚本

---

总结

黄金规则：

1. ✅ 使用根目录 package.json 脚本（开发者 API）
2. ✅ 命令中切勿使用 cd
3. ✅ 先检查可用脚本
4. ✅ 直接执行时使用 working_dir 参数

请记住：根目录脚本是项目的公共 API。绕过它们会破坏约定。

---

持续改进

如果开发者纠正了本技能本应避免的行为，请提出对本技能的具体修订建议，以避免今后再次出现同样的纠正。