ECC TypeScript 代码审查 Agent 实战指南从类型安全到 Node 安全的系统化评审流程【免费下载链接】ECCThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.项目地址: https://gitcode.com/GitHub_Trending/ev/ECC导读本文以 ECCThe agent harness performance optimization system仓库中内置的typescript-reviewer专家 Agent 为蓝本系统讲解面向 TypeScript/JavaScript 变更的代码审查方法论。你将掌握如何在 PR 与本地 diff 上建立可靠的评审范围、如何执行类型检查与 ESLint 诊断、如何按 CRITICAL/HIGH/MEDIUM 三级优先级审查安全、类型安全、async 正确性、错误处理、Node.js 特有风险与 React/Next.js 模式以及如何依据批准标准给出通过 / 警告 / 阻塞结论。文中所有流程、命令与判据均来自 typescript-reviewer Agent 定义并结合仓库内 rules/typescript/ 规则体系与 react-review.md 等配套命令作源码级印证。一、typescript-reviewer 的角色定位与适用场景typescript-reviewer是 ECC 68 个内置专家 Agent 之一定位为以类型安全、async 正确性、Node/Web 安全与惯用模式为核心的高标准 TypeScript/JavaScript 代码审查者。其在仓库中的完整定义位于 agents/typescript-reviewer.md日文版见 docs/ja-JP/agents/typescript-reviewer.md。从 Agent 元数据frontmatter可以读出它的运行约束元数据字段值含义nametypescript-reviewerAgent 标识供 ECC 按名调用description类型安全、async 正确性、Node/Web 安全、惯用模式专家决定 ECC 何时自动路由到该 AgenttoolsRead, Grep, Glob, Bash只读探查 命令执行不写代码modelsonnet默认模型选择适用场景非常明确所有 TypeScript/JavaScript 代码变更.ts/.tsx/.js/.jsxTypeScript/JavaScript 项目必用——这是 Agent 描述中的硬性要求MUST BE USED在 ECC 的评审体系内它与react-reviewer是互补双通道关系当 PR 涉及.tsx/.jsx时两个 Agent 应同时运行、各自负责互不重叠的评审域。这一分工在 react-review.md 的 Scope 对比表中写得很清楚工具评审域react-reviewer/react-reviewHooks 规则、JSX、RSC、a11y、React 专属安全、渲染性能typescript-reviewer通用 TS/JS——any滥用、async 正确性、Node 安全security-reviewer项目级安全审计/code-review通用的未提交变更或 PR 评审从源码结构看这条 lane 分工是刻意设计的typescript-reviewer专注语言与运行时层面的通用问题React 专属问题交给react-reviewer两者在 TSX/JSX PR 上by design不产生重叠结论。二、启动即建立评审范围7 步标准流程Agent 定义给出了一套严谨的启动协议。评审的第一要务不是看代码而是在发表任何评论之前先锁定评审范围。完整流程如下确立评审基线review scopePR 评审优先使用真实 PR 基础分支例如通过gh pr view --json baseRefName获取或使用当前分支的 upstream/merge-base。不要硬编码main——基线错了整个 diff 就错了。本地评审优先git diff --staged已暂存与git diff工作区未暂存。浅历史 / 单提交兜底当历史很浅或只有一个 commit 时回退到git show --patch HEAD -- *.ts *.tsx *.js *.jsx确保仍能看到代码级变更。PR 合并就绪检查merge readiness有元数据时通过gh pr view --json mergeStateStatus,statusCheckRollup检查必需检查required checks失败或 pending → 停下来报告应等待 CI 变绿再评审PR 存在合并冲突或不可合并状态 → 停下来报告需先解决冲突无法从上下文验证合并就绪 → 继续前明确声明这一不确定性。运行项目标准类型检查命令优先npm/pnpm/yarn/bun run typecheck--if-present语义。若没有该脚本选择覆盖被改代码的tsconfig文件而不是默认仓库根目录的tsconfig.json在 project references 工程里优先仓库的非产出物 solution check 命令而不是盲目调用 build 模式兜底用tsc --noEmit -p relevant-config纯 JavaScript 项目直接跳过本步不要让评审失败。运行 ESLinteslint . --ext .ts,.tsx,.js,.jsx。若 lint 或类型检查失败 → 停止并报告先修门禁再谈评审。确认 diff 相关如果所有 diff 命令都没有产出相关的 TypeScript/JavaScript 变更 → 停止报告无法可靠建立评审范围。聚焦被修改文件在评论前先读取周围上下文。开始评审。两条贯穿始终的纪律不重构、不重写代码只报告发现You DO NOT refactor or rewrite code — you report findings only以及评估心态——这段代码能否通过顶级 TypeScript 团队或维护良好的开源项目的 code review这套流程与仓库中 code-review.md 的诊断思路一致其命令清单同样以npm run typechecknpx tsc --noEmit起步可视为通用评审流程在 TypeScript 域的细化。三、审查优先级全景CRITICAL / HIGH / MEDIUM 三级判据Agent 将全部评审关注点按严重度分为三级。下表完整继承原文档的核心判据并补充如何修复的实操要点修复建议结合 rules/typescript/ 的编码规范佐证。CRITICAL —— 安全Security任何一条命中都直接阻塞合并判据风险形态修复方向eval/new Function注入用户可控输入进入动态执行绝不执行不可信字符串改用数据驱动方案XSS未净化的用户输入赋给innerHTML、dangerouslySetInnerHTML、document.write渲染为文本或经 DOMPurify 等净化后再插入react-review.md的 CRITICAL 清单同样点名dangerouslySetInnerHTMLSQL/NoSQL 注入查询中的字符串拼接参数化查询或 ORM路径遍历fs.readFile、path.join中出现用户输入且无path.resolve 前缀校验先path.resolve再做前缀白名单校验硬编码密钥源码中的 API key、token、密码改用环境变量缺失时启动即抛错security.md 给出了process.env.API_KEY 空值检查的标准写法原型污染无Object.create(null)或 schema 校验就合并不可信对象使用Object.create(null)或先做 schema 校验用户输入进入child_processexec/spawn接收未经校验的输入传参前校验 白名单HIGH —— 类型安全Type Safety无正当理由的any等于关闭类型检查——改用unknown并收窄或使用精确类型。coding-style.md 给出了标准范式function getErrorMessage(error: unknown): string内部instanceof Error收窄兜底返回默认值非空断言滥用前面没有 guard 的value!——应补运行时检查绕过检查的as断言为了消音而把值断言到无关类型——应修复类型本身放松的编译器配置若tsconfig.json被改动且削弱了 strictness必须明确点名。HIGH —— async 正确性Async Correctness未处理的 Promise rejectionasync函数被调用却无await或.catch()独立任务的串行 await循环内await明明可并行——考虑Promise.all浮空 Promise事件处理器或构造函数里 fire-and-forget 且无错误处理forEach中的asyncarray.forEach(async fn)不会等待——改用for...of或Promise.all。HIGH —— 错误处理Error Handling吞掉错误空catch块或catch (e) {}无任何动作无 try/catch 的JSON.parse非法输入会抛异常——始终包裹抛出非 Error 对象throw message——始终throw new Error(message)缺少错误边界React 树中 async/数据获取子树周边没有ErrorBoundary。coding-style.md 的错误处理小节与之一致推荐async/await try-catch以unknown捕获并用instanceof Error安全收窄再以new Error(getErrorMessage(error))重新抛出。HIGH —— 惯用模式Idiomatic Patterns可变的模块级共享状态优先不可变数据与纯函数coding-style.md 的 immutability 示例用ReadonlyUser spread 返回新对象而非原地改user.name使用var默认const需要重赋值才用let缺少返回类型导致的隐式any公共函数应有显式返回类型回调风格 async回调与async/await混用——统一为 Promise用而非全程使用严格相等。HIGH —— Node.js 特有Node.js Specifics请求处理器中的同步 fsfs.readFileSync阻塞事件循环——用 async 版本边界缺少输入校验外部数据无 schema 校验zod、joi、yup。coding-style.md 的推荐是 Zod定义userSchema z.object({...})用z.infertypeof userSchema反推类型再userSchema.parse(input)未校验的process.env访问无兜底或启动时校验就读取ESM 环境中的require()无明确意图的模块系统混用。MEDIUM —— React / Next.js适用时重要前置React 专属评审请优先交给react-reviewer/react-review。typescript-reviewer中保留的 React 检查仅作兜底——当 diff 含.tsx/.jsx时两个 Agent 应同时被调用完整 CRITICAL/HIGH 规则集hooks 规则、dangerouslySetInnerHTML、RSC 边界、可访问性、渲染性能见 agents/react-reviewer.md。依赖数组缺失useEffect/useCallback/useMemodeps 不完整——启用exhaustive-depslint 规则状态直接变更应返回新对象而非原地修改 state用 index 作 key动态列表key{index}——改用稳定唯一 ID用useEffect计算派生状态应在渲染期间计算派生值服务端/客户端边界泄漏Next.js 中客户端组件导入服务端专用模块。MEDIUM —— 性能Performance渲染中创建对象/数组内联对象作为 props 导致不必要的重渲染——提升hoist或 memoizeN1 查询循环内发起数据库/API 调用——批处理或Promise.all缺少React.memo/useMemo高开销计算或组件每次渲染都重跑大体积包导入import _ from lodash——用命名导入或可 tree-shake 的替代品。MEDIUM —— 最佳实践Best Practices生产代码残留console.log改用结构化日志coding-style.md 明确生产代码零console.loghooks.md 还配置了自动检测 hook 来告警魔法数字/字符串使用命名常量或 enumcoding-style.md 更推荐 string literal union 而非enum除非互操作需要无兜底的深层可选链a?.b?.c?.d没有默认值——加?? fallback命名不一致变量/函数 camelCase类型/类/组件 PascalCase。四、诊断命令集开箱即用的标准检查清单Agent 定义提供了一组可直接执行的诊断命令覆盖类型检查、lint、格式化、供应链安全与测试npm run typecheck --if-present # 项目自定义的标准 TypeScript 检查 tsc --noEmit -p relevant-config # 兜底对拥有被改文件的 tsconfig 做类型检查 eslint . --ext .ts,.tsx,.js,.jsx # 代码规范检查lint prettier --check . # 格式检查 npm audit # 依赖漏洞或 yarn/pnpm/bun 等价命令 vitest run # 测试Vitest jest --ci # 测试Jest仓库配套命令印证了同一套工具链code-review.md 中同样以npm run typecheck与npx tsc --noEmit作为前置门禁react-build.md 也采用npm run typecheck --if-presenttsc --noEmit -p tsconfig.json的独立 typecheck 流程rules/typescript/testing.md 则进一步约定 E2E 测试使用 Playwright。实操建议从 Agent 定义与仓库用法推断--if-present保证了脚本缺失时命令静默跳过不会让评审卡死ESLint 全量扫描开销较大评审阶段可配合第 2 节的聚焦被修改文件原则先对变更文件跑eslint changed-files全量扫描用于最终确认npm audit属于供应链检查在 PR 评审中可与合并就绪检查statusCheckRollup相互印证。五、批准标准如何给出评审结论评审产出必须是清晰、可执行的三态结论这与 react-review.md 的 PASS/WARNING/FAIL 门禁完全对齐结论条件可操作性批准Approve无 CRITICAL 或 HIGH 问题可以合并警告Warning仅有 MEDIUM 问题谨慎合并merge with caution阻塞Block存在 CRITICAL 或 HIGH 问题禁止合并修复后重新评审这条三级门禁意味着评审报告应严格按 CRITICAL / HIGH / MEDIUM 归类输出并附文件路径与行号阻塞项必须给出明确的为什么危险 怎么修而不是笼统的负面评价。六、与仓库配套资源的协同使用typescript-reviewer不是孤立的ECC 为 TypeScript/JavaScript 项目提供了一整套配套资产评审时可以交叉引用rules/typescript/5 个规则文件构成评审的标准答案来源——coding-style.md类型与接口、避免any、不可变性、错误处理、Zod 输入校验、console.log纪律security.md密钥管理环境变量 启动校验、安全审计指引patterns.mdApiResponseT响应格式、useDebounce自定义 Hook、RepositoryT仓储模式testing.mdPlaywright E2E 约定hooks.md编辑后自动 Prettier、tsc检查、console.log告警等 hook 配置。agents/react-reviewer.md.tsx/.jsx变更时的搭档 AgentReact lane。commands/react-review.md/react-review命令TSX/JSX PR 上与typescript-reviewer并行运行。commands/code-review.md通用的未提交变更/PR 评审入口纯.ts/.js且无 React 的场景下可作为入口。Agent 定义中的参考一节还诚实声明本仓库尚未内置独立的typescript-patternsskill因此涉及具体模式时按被审代码的类型选用coding-standardsfrontend-patterns或backend-patternsskill 即可——评审者应基于被审代码的技术栈选择最贴近的规范源。七、使用方式与前提限制调用方式作为 ECC 内置 Agent可通过命令如/react-review的 companion 调用或直接在评审任务中指定typescript-reviewer激活model: sonnet表明其默认运行模型实际可由 harness 配置覆盖。适用前提本文所有命令均假设仓库使用 npm 生态或等价 yarn/pnpm/bun且本地已安装 Node.js 工具链gh相关命令仅在 GitHub PR 元数据可用时生效。限制说明Agent 只报告发现、不代改代码对纯 JavaScript 项目会自动跳过类型检查步骤当 diff 不含 TS/JS 变更时会主动终止并声明范围未建立——这些优雅失败行为是评审可靠性的组成部分。结语typescript-reviewer的价值不在于罗列了多少条检查项而在于把一次 TypeScript 代码评审固化成可重复、可门禁化的工程流程先锁定 diff 基线、再跑类型检查与 lint 门禁、随后按 CRITICAL/HIGH/MEDIUM 三级判据逐项审查、最后输出三态结论。配合 rules/typescript/ 的规则体系与react-reviewer的 lane 分工它足以支撑这段代码能否通过顶级 TypeScript 团队评审这一高标准自问——而这正是原文档最后那句评审心态的用意所在。【免费下载链接】ECCThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.项目地址: https://gitcode.com/GitHub_Trending/ev/ECC创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考