# Add Memory Trace Tags

> Use when adding new resource tracking types to memory profiling in developtools_profiler and third_party_musl repositories. Triggered by requests to add trace tags, resource labels, or memory tracking types.

- Skill: `openharmonyinsight/add-memory-trace-tags` (Agent Skill)
- Install (CLI): `npx skillmds@latest add openharmonyinsight/add-memory-trace-tags`
- Raw SKILL.md: https://api.skillmd.com/api/skills/openharmonyinsight/add-memory-trace-tags/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: openharmonyinsight (https://skillmd.com/u/openharmonyinsight)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/openharmonyinsight/add-memory-trace-tags

---


# 内存跟踪标签添加

自动在 developtools_profiler 和 third_party_musl 仓库中添加新的资源跟踪类型标签。

## 概述

此 skill 自动跨两个仓库的多个文件添加内存跟踪标签，确保定义一致、协议更新和测试覆盖。

## 使用场景

适用于以下情况：
- 添加新的资源跟踪类型（COMMON_* 或特定类型）
- 更新内存分析功能
- 扩展跟踪标签系统

## 快速参考

| 组件 | 修改文件数 | 主要变更 |
|------|-----------|---------|
| **third_party_musl** | 2 个文件 | TAG 和 MASK 定义 |
| **developtools_profiler** | 9 个文件 | 协议、逻辑、测试 |

## 使用方法

在对话中直接调用：

```
请添加一个新的资源跟踪标签 <标签名称>
```

或

```
使用 add-res-trace-tag 添加 <标签名>
```

## 参数说明

此 skill 会提示输入：

1. **标签名称**（必填）
   - 格式：大写字母和下划线
   - 风格：`COMMON_<类型名>` 或描述性名称
   - 示例：`COMMON_PIXELMAP`、`CREATE_NATIVE_WINDOW_FROM_SURFACE`

2. **描述**（可选）
   - 用途说明

3. **是否绕过大小过滤**（可选，默认：是）
   - 通用资源类型通常需要绕过大小过滤

## 修改内容

### third_party_musl（2 个文件）
- `src/hook/linux/memory_trace.h` - TAG、MASK、位域布局
- `porting/linux/user/src/hook/memory_trace.h` - 重复定义

### developtools_profiler（9 个文件）

**协议：**
- `protos/types/plugins/native_hook/native_hook_result.proto` - TraceType、MemoryType 枚举

**常量：**
- `device/plugins/native_daemon/include/hook_common.h` - 索引常量

**业务逻辑：**
- `device/plugins/native_hook/src/hook_guard.cpp` - TagId 映射
- `device/plugins/native_daemon/src/hook_manager.cpp` - 掩码转换
- `device/plugins/native_daemon/src/stack_preprocess.cpp` - 统计映射
- `device/plugins/native_daemon/src/hook_record.cpp` - TraceType 设置
- `device/plugins/native_hook/src/hook_client.cpp` - 过滤条件（仅 COMMON_* 类型）

**测试：**
- `device/plugins/native_daemon/test/unittest/common/native/hook_record_test.cpp`
- `device/plugins/native_daemon/test/unittest/common/native/stack_preprocess_test.cpp`

## 常见错误

### MASK 定义规则

**每个资源类型必须定义两个宏：**

```c
// ✅ 正确：同时定义两个宏
#define RES_COMMON_WINDOW          (1ULL << 33)
#define RES_COMMON_WINDOW_MASK     (1ULL << 33)

// ❌ 错误：缺少 _MASK 后缀
#define RES_COMMON_WINDOW          (1ULL << 33)
// 缺少 RES_COMMON_WINDOW_MASK！
```

**为什么需要两个定义：**
1. `RES_<NAME>` - 基础掩码值
2. `RES_<NAME>_MASK` - 统一接口的别名

**常见错误场景：**
```
错误 1：忘记添加 _MASK 后缀
#define RES_COMMON_SURFACE (1ULL << 34)     // ✅ 有这个
// ❌ 缺少：#define RES_COMMON_SURFACE_MASK (1ULL << 34)

错误 2：只复制了第一行
#define RES_COMMON_TEXTURE (1ULL << 35)     // ✅ 有这个
#define RES_COMMON_TEXTURE    // ❌ 这行是错的！应该是 (1ULL << 35)
```

**Skill 自动验证：**
此 skill 会自动检查是否两个定义都存在，如果缺失会自动添加。

## 验证清单

添加新标签后检查：

- [ ] musl 主文件：TAG 已定义
- [ ] musl 主文件：MASK 已定义（**两个都要**）
- [ ] musl porting 文件：TAG 已定义
- [ ] musl porting 文件：MASK 已定义（**两个都要**）
- [ ] proto：TraceType 枚举值已添加
- [ ] proto：MemoryType 枚举值已添加
- [ ] hook_common.h：索引已定义
- [ ] hook_common.h：RESTRACE_TYPE_COUNT 已更新
- [ ] hook_guard.cpp：映射已添加
- [ ] hook_manager.cpp：转换逻辑已添加
- [ ] stack_preprocess.cpp：SaveMemTag 和 AddAllocStatistics 已添加
- [ ] hook_record.cpp：SetTraceType 分支已添加
- [ ] hook_client.cpp：过滤条件已更新（仅 COMMON_* 类型）
- [ ] 测试：测试用例已添加

## 约束条件

- **标签命名**：大写字母和下划线
- **比特位分配**：从 bit 34 开始（当前用到 bit 33）
- **索引分配**：从 23 开始（当前最大索引 22）
- **枚举值**：自动递增，不与现有值冲突
- **仓库路径**：假设为 `d:\Code\tools_develop\`
- **RESTRACE_TYPE_COUNT**：必须等于最大索引 + 1


## 注意事项

1. **编译顺序**：修改 musl 后需要重新编译，profiler 才能使用新宏定义
2. **协议兼容性**：protobuf 修改后需要重新生成 C++ 代码
3. **测试覆盖**：所有修改都会添加相应的测试用例
4. **COMMON_* 类型**：只有 COMMON_* 前缀的类型才需要更新 `hook_client.cpp` 的过滤条件

## 错误处理

| 错误 | 解决方案 |
|------|----------|
| 标签已存在 | 使用不同的标签名称 |
| 文件未找到 | 验证仓库路径 |
| 权限被拒绝 | 检查文件写入权限 |
| 格式无效 | 标签名称必须是大写字母和下划线 |
| 缺少 MASK | Skill 自动添加 RES_*_MASK 定义 |
| 定义不匹配 | RES_* 和 RES_*_MASK 的值必须相同 |