# PR #918 检视报告 — cuda2ascend 插件新增 TraeCode 支持

## 检视对象

- Skill/插件: `plugins-community/cuda2ascend`（社区插件，非新增 skill）
- 来源: `https://gitcode.com/cann/cannbot-skills/pull/918`（merge `feat/cuda2ascend-trae-support` → `master`，head `2e47c488`）
- 变更范围: 20 个文件（`init.sh`、新增 `hooks/trae/permission-guard.js`、6 个 `SKILL.md`、7 个 `references/*.md`、`README.md`/`AGENTS.md`/`agents/qa.md`/`example/init.sh`/`.gitignore`）
- 结论: **CONDITIONAL**
- 评分: **74/100**（插件类 PR 的适配性评估）
- 阻塞问题: **0**

## 变更摘要

本 PR 为 cuda2ascend 插件新增 TraeCode（Trae）作为第 5 个目标工具（opencode/claude/codex/dsh 之后），主要改动：

1. **新增 `hooks/trae/permission-guard.js`**（97 行）：Trae 侧静默问卷拦截 hook，语义与 opencode/claude/dsh 三侧一致（`SILENT_GUARDED_TOOLS = ["question","ask"]` + `readSilentMode` 读 `.cannbot/settings.json`）。
2. **`init.sh`（+159 行）**：`SUPPORTED_TOOLS` 增加 `trae`；新增 trae 的 global/project 配置根、Subagent 生成（内联 Python，`ROLE_TOOLS` 按角色注入 `tools` 静态白名单）、`hooks.json` 幂等注册 PreToolUse hook、健康检查；`CLI_NAME="${TOOL}"` 解耦具体框架。
3. **`example/init.sh`**：`CLI_NAME="$TARGET_ENV"`，help 文本去硬编码。
4. **文档一致性**：6 个 `SKILL.md` + 7 个 `references/*.md` 统一在「会话问卷工具」清单中追加 `trae AskUserQuestion`；`review-checklist.md` 的 L8/M6 同步说明 trae 侧无 `DEFAULT_RULES`、角色权限靠 `.trae/agents/*.md` 静态 `tools`。
5. **`.gitignore`** 追加 `.trae` / `.marscode` / `.traecli`。

## 成文法门禁

对 6 个被改动的 `SKILL.md` 逐一运行 `tests/lib/skill_validator.py validate-skill`，**全部通过，无 `error`/`warn` 输出**：

| 文件 | 结果 |
|------|------|
| `skills/ops-direct-invoke-workflow/SKILL.md` | pass |
| `skills/plugin-experience-summary/SKILL.md` | pass |
| `skills/workflow-agent-permissions/SKILL.md` | pass |
| `skills/workflow-cp0/SKILL.md` | pass |
| `skills/workflow-cp1/SKILL.md` | pass |
| `skills/workflow-cp2-2/SKILL.md` | pass |

`name` 与目录名一致、frontmatter 完整、无 XML 注入、无同名冲突，无成文法阻塞项。

## 九维评分

| 维度 | 权重 | 得分 | 理由 |
|------|-----:|-----:|------|
| Frontmatter 质量 | 8 | 8 | 改动未破坏任何 frontmatter，`name`/`description` 清晰 |
| 工作流清晰度 | 15 | 8 | 文档追加清晰、无流程回归 |
| 边界条件覆盖 | 10 | 8 | 明确 Trae PreToolUse 无 agent 角色字段的降级、目录级写权限靠 prompt 兜底、静默拦截 fallback |
| 检查点设计 | 7 | 6 | 非本次变更关注点，未新增需确认点 |
| 指令具体性 | 15 | 8 | hook 路径、hooks.json 格式、ROLE_TOOLS 映射均具体明确 |
| 资源整合度 | 5 | 4 | `references/` 多文件同步更新，覆盖完整 |
| CANNBot 架构适配性 | 15 | 7 | 分层正确、单一职责；但 trae 变体支持窄于官方参考实现（见重要警告） |
| 领域可信度与安全边界 | 10 | 7 | hook 只读、无凭据/网络风险；但 TraeCode 机制事实属第三方、无法从 CANN 官方源核实 |
| 验证证据 | 15 | 7 | 未新增 trae 专项测试，依赖既有前瞻性测试；人工验证通过 |

## 重要警告

**W1：trae 支持仅覆盖 IDE 变体，且与 `.gitignore` 不一致（非阻塞）**

本 PR 的 `init.sh` 将 trae 硬编码为 `~/.trae-cn`（global，init.sh:466）与 `.trae`（project，init.sh:491），**未实现 `detect_trae_variant()`**，不支持 `.marscode`（Trae 插件变体）与 `.traecli`（Trae CLI 变体）。但 `.gitignore` 却同时加入了 `.marscode` 和 `.traecli`（`.gitignore:5-6`），而 init 永远不会向这两个目录安装任何产物，形成「忽略但不支持」的内部不一致。

对照仓库内官方参考插件（如 `plugins-official/ops-registry-invoke/init.sh` 的 `detect_trae_variant()`），它们按 `~/.trae-cn` / `~/.marscode` / `~/.traecli` 三变体自动探测。建议二选一：
- 补齐 `detect_trae_variant()` 对齐官方参考；或
- 在文档中显式声明「仅支持 Trae IDE 变体」，并将 `.gitignore` 中 `.marscode`/`.traecli` 删除或注明为通用编辑器产物忽略项。

## 必须修复项

无阻塞项。

## 建议（非阻塞）

1. `init.sh` 内联 Python 的 here-doc 位于命令替换 `$(... << 'PY' ...)` 内（init.sh:737、1008），`bash -n` 会报「unterminated here-document」误报（运行时经实测正确执行，属 bash 已知解析器局限）。若 CI 引入 `bash -n`/shellcheck 门禁需留意该告警。
2. TraeCode 相关机制事实（PreToolUse stdin 无角色字段、`.trae/hooks.json` 结构、`frontmatter tools` 静态限权、`~/.trae-cn` 根目录、`CLAUDE_PROJECT_DIR` 兼容）均为第三方产品行为，无法从 CANN 官方文档交叉验证，建议在 PR 描述或文档中注明依据来源，便于后续维护者核实。
3. 未新增针对 trae Subagent 生成 / hooks.json 注册的专项测试，当前依赖仓库既有前瞻性测试（`tests/unit/install/test-init-tool.sh --tool trae`）与行为测试的防御性降级分支。建议补充 trae 路径的最小断言，防止未来回归。

## 验证

- Command: `python3 tests/lib/skill_validator.py validate-skill <6 个 SKILL.md>` → **pass**（无 findings）
- Command: `bash tests/unit/install/test-init-tool.sh --tool trae` → **pass**（119 passed / 0 failed）
- Command: `bash -n init.sh` / `bash -n example/init.sh` → **pass**（init.sh 存在 here-doc 误报警告）
- Command: `node --check hooks/trae/permission-guard.js` → **pass**
- 人工核对：`ROLE_TOOLS` 6 个键与 `agents/*.md` 的 `name` 完全一致；`SILENT_GUARDED_TOOLS` 与 opencode/claude/dsh 三侧 hook 一致；`CLI_NAME="${TOOL}"` 有 `TOOL="opencode"` 默认值兜底。

REVIEW_VERDICT=CONDITIONAL