ln-653-runtime-performance-auditor

**路径：**文件路径（references/、../ln-*）均相对于此技能目录。

运行时性能审计员（L3 Worker）

**类型：**L3 Worker

专门审计异步代码和通用代码中的运行时性能反模式。

目的与范围

• 审计运行时性能（优先级：中）
• 检查异步反模式、不必要的分配和阻塞操作
• 将结构化发现写入文件，包含严重性、位置、工作量和建议
• 计算运行时性能类别的合规评分（X/10）

输入

**必须读取：**加载 references/audit_worker_core_contract.md 和 references/mcp_tool_preferences.md。 工具策略：你可能会作为独立子 Agent 运行，此时宿主的 AGENTS.md 不在适用范围内，因此读取、搜索和编辑文件时默认优先使用 hex-line MCP。仅当 MCP 行为不明确时，才加载 references/mcp_integration_patterns.md。

接收包含以下内容的 contextStore：tech_stack、best_practices、codebase_root、output_dir。

**支持领域感知：**支持 domain_mode + current_domain。

当热点检测能显著改善运行时性能发现时，优先使用 hex-graph。在本地代码读取方面，若可用，优先使用 hex-line。如果 MCP 不可用、不受支持或未建立索引，则继续使用内置的 Read/Grep/Glob/Bash，并在报告中说明回退情况。

工作流

检测策略：采用两层检测（候选项扫描，然后进行上下文验证）；仅当验证方法不明确时，才加载 references/two_layer_detection.md。

1. 从 contextStore 解析上下文

   • 提取 tech_stack、best_practices、output_dir
   • 确定 scan_path
   • 检测异步框架：asyncio（Python）、Node.js async、Tokio（Rust）

2. 扫描代码库中的违规项

   • 使用 Grep 模式，范围限定在 scan_path
   • 对于规则 1、3、5：先检测 async def 代码块，再检查其中的违规项

3. 收集发现，包含严重性、位置、工作量和建议

4. 使用惩罚算法计算评分

5. **编写报告：**根据 references/templates/audit_worker_report_template.md 在内存中构建完整的 Markdown 报告，并通过一次 Write 调用写入 {output_dir}/ln-653--global.md

6. **返回摘要：**向协调器返回最简摘要（参见输出格式）

审计规则（优先级：中）

1. 异步代码中的阻塞 IO

**内容：**在异步函数中执行同步文件/网络操作，阻塞事件循环

检测（Python）：

• 查找 async def 函数
• 在其中搜索阻塞调用：
  • 文件：open(、.read_bytes()、.read_text()、.write_bytes()、.write_text()、Path(...).(read|write)
  • 网络：requests.get、requests.post、urllib.request
  • 子进程：subprocess.run(、subprocess.call(
• 排除：包装在 await asyncio.to_thread(...) 或 await loop.run_in_executor(...) 中的调用

检测（Node.js）：

• 在 async function 或异步箭头函数中，搜索 fs.readFileSync、fs.writeFileSync、child_process.execSync

严重性：

• **高：**API 请求处理程序中的阻塞 IO（会阻塞整个事件循环）
• **中：**后台任务/工作进程中的阻塞 IO
• **降低严重性时：**在 __init__/setup/bootstrap 中的阻塞 IO（不在请求路径上）-> 低。非热点路径中读取小于 1KB 的文件 -> 跳过

**建议：**文件操作使用 aiofiles、asyncio.to_thread() 或 loop.run_in_executor()；使用 httpx.AsyncClient 替代 requests

**工作量：**S（封装在 to_thread 中或改用异步库）

2. 不必要的列表分配

说明： 可以使用生成器表达式的地方使用了列表推导式

检测：

• len([x for x in ...])——仅为计数就分配列表；改用 sum(1 for ...)
• any([x for x in ...])——为短路检查分配列表；改用 any(x for x in ...)
• all([x for x in ...])——同类问题；改用 all(x for x in ...)
• set([x for x in ...])——改用集合推导式 {x for x in ...}
• "".join([x for x in ...])——直接使用生成器："".join(x for x in ...)

严重程度：

• MEDIUM： 在热点路径（API 处理程序、循环）中进行不必要的分配
• LOW： 在不常执行的代码中进行不必要的分配

建议： 将 [...] 替换为生成器 (...) 或集合推导式 {...}

工作量： S（仅更改语法）

3. 异步代码中的同步休眠

说明： 在异步函数中调用 time.sleep() 会阻塞事件循环

检测：

• 在 async def 代码块中搜索 time\.sleep
• 模式：await some_async_call() ... time.sleep(N) ... await another_call()

严重程度：

• HIGH： 在异步 API 处理程序中调用 time.sleep()（会冻结所有并发请求）
• MEDIUM： 在异步后台任务中调用 time.sleep()
• 降低严重程度的情况： 在 CLI/脚本（非异步服务）中调用 time.sleep → 跳过

建议： 替换为 await asyncio.sleep(N)

工作量： S（单行更改）

4. 循环中的字符串拼接

说明： 在循环中通过 += 构建字符串（对于较大的字符串，复杂度为 O(n^2)）

检测：

• 模式：变量 result、output、html、text 在 for/while 循环中使用 +=
• 搜索：循环体内，变量后跟 +=，且包含字符串操作数

严重程度：

• MEDIUM： 在处理大量数据（>100 次迭代）的循环中拼接字符串
• LOW： 在迭代次数较少（<100）的循环中拼接字符串

建议： 使用 list.append() + "".join()、io.StringIO，或使用 f-string 和 "".join(generator)

工作量： S（重构为列表 + join）

5. CPU 密集型代码缺少 to_thread

说明： 异步处理程序中有 CPU 密集型同步代码，但未将其卸载到线程

检测：

• 在 async def 内查找 CPU 密集型操作：
  • 解析大型 JSON 文件：json.loads(large_data)、json.load(file)
  • 图像处理：PIL.Image.open、cv2.imread
  • 加密：hashlib、bcrypt.hashpw
  • XML/HTML 解析：lxml.etree.parse、BeautifulSoup(
  • 没有 await 点的大型数据转换
• 排除：已包装在 asyncio.to_thread() 或 executor 中的操作

严重程度：

• MEDIUM： 异步处理程序中的 CPU 密集型操作（会根据数据大小相应地阻塞事件循环）

建议： 使用 await asyncio.to_thread(func, *args)（Python 3.9+）或 loop.run_in_executor(None, func, *args) 包装

工作量： S（使用 to_thread 包装）

6. 多余的数据副本

说明： 数据仅被读取、未被修改时，不必要地调用 .copy()、list()、dict()

检测：

• data = list(items)，其中 data 仅用于迭代（从未修改）
• config = config_dict.copy()，其中 config 仅用于读取
• result = dict(original)，其中 result 未经修改就被返回

严重程度：

• LOW： 大多数情况下的多余复制（轻微增加内存开销）
• MEDIUM： 热点路径中对大型数据进行多余复制

建议： 删除不必要的复制；如果数据不会被修改，则直接传递原对象

工作量： S（移除复制调用）

评分算法

必须阅读： 加载 references/audit_scoring.md。

输出格式

**必须阅读：**加载 references/templates/audit_worker_report_template.md。

按照 references/audit_summary_contract.md 编写 JSON 摘要。在托管模式下，调用方会传入 runId 和 summaryArtifactPath；在独立模式下，工作器会根据共享契约生成自己的运行级制品路径。

将报告写入 {output_dir}/ln-653--global.md，并设置 category: "Runtime Performance"，检查项为：blocking_io_in_async、unnecessary_list_allocation、sync_sleep_in_async、string_concat_in_loop、missing_to_thread、redundant_data_copies。

按照 references/audit_summary_contract.md 返回摘要。

当 summaryArtifactPath 缺失时，将独立运行时摘要写入 .hex-skills/runtime-artifacts/runs/{run_id}/evaluation-worker/{worker}--{identifier}.json，并可选择在结构化输出中回显同一份摘要。

Report written: .hex-skills/runtime-artifacts/runs/{run_id}/audit-report/ln-653--global.md
Score: X.X/10 | Issues: N (C:N H:N M:N L:N)

关键规则

遵循已加载的 references/audit_worker_core_contract.md。

• **不要自动修复：**仅报告问题
• **必须处于异步上下文中：**规则 1、3、5 仅适用于异步函数内部
• **排除包装调用：**不要报告已经由 to_thread/run_in_executor 包装的调用
• **结合上下文判断：**同步读取的小文件（<1KB）可能可以接受
• **排除测试：**不要报告测试工具或测试夹具

完成标准

遵循已加载的 references/audit_worker_core_contract.md。

• contextStore 已成功解析（包括 output_dir）
• 已确定 scan_path
• 已检测到异步框架（asyncio/Node.js async/Tokio）
• 已完成全部 6 项检查：
  • 阻塞式 IO、不必要的分配、同步休眠、字符串拼接、CPU 密集型操作、多余的副本
• 已收集包含严重程度、位置、工作量和建议的发现
• 已使用惩罚算法计算评分
• 已将报告写入 {output_dir}/ln-653--global.md（通过一次原子 Write 调用完成）
• 已按照契约写入摘要

参考文件

• 审计输出架构：references/audit_output_schema.md

---

**版本：**1.0.0 **最后更新：**2026-02-04