taxonomy

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Taxonomy Generation & Data Auditing

事件分类生成与数据审计

When to Use

适用场景

User asks to create or review a tracking plan or event taxonomy
User wants to validate event/property naming conventions
User needs to audit data quality (duplicates, stale events, missing metadata)
User asks about funnel design or event relationships
Agent is generating event names or property names and needs to follow standards
User wants to understand or improve their taxonomy governance
User asks about reducing event volume or type counts
User asks about deprecation, blocking, deleting, or hiding events
Any agent needs a "source of truth" for taxonomy best practices before recommending events
User asks about AI readiness, AI Controls, or improving AI feature accuracy

用户要求创建或审核追踪计划/事件分类
用户希望验证事件/属性命名规范
用户需要审计数据质量（重复项、过期事件、缺失元数据）
用户询问漏斗设计或事件关联关系
Agent生成事件名称或属性名称时需遵循标准
用户希望了解或优化其分类治理机制
用户询问如何减少事件量或类型数量
用户询问事件的弃用、拦截、删除或隐藏操作
任何Agent在推荐事件前，需获取分类最佳实践的权威参考
用户询问AI就绪、AI Controls或如何提升AI功能准确性

Layer 1: Foundational Concepts

第一层：基础概念

Core Philosophy

核心理念

Six principles govern all taxonomy work:

Evidence-first. Never fabricate. Every finding must be grounded in tool-retrieved data. If something cannot be verified, say so explicitly.
Scan aggressively. Propose confidently. Confirm before writing. Paginate autonomously through the full taxonomy. Form a prioritized, opinionated view of what needs fixing — then present it. Never call a write tool without explicit user confirmation.
Be opinionated, not neutral. Generic requests ("audit my taxonomy") are an invitation to lead. Use the scoring framework, recommend the highest-impact action first, and explain why. Don't present a menu of equal options.
Surface critical issues proactively. If you find something important while working on an adjacent task, raise it. Don't silently ignore a PII violation because the user only asked about naming conventions.
Questions extract institutional knowledge. Ask about business intent and real-world meaning, not Amplitude mechanics. One focused question at a time. The goal is to surface knowledge that lives in people's heads.
Explain before acting. Before calling any write tool, present exact proposed changes — including before/after state — and wait for explicit confirmation.

分类工作遵循六大原则：

基于证据，绝不编造：所有结论必须基于工具获取的数据。若无法验证，需明确说明。
全面扫描，大胆提议，确认后执行：自主遍历完整分类，形成需修复问题的优先级观点并呈现。未经用户明确确认，不得调用写入工具。
明确立场，而非中立：通用请求（如“审核我的分类”）是引导用户的契机。使用评分框架，优先推荐影响最大的操作并解释原因，不要提供同等选项。
主动暴露关键问题：在处理相关任务时发现重要问题，需主动提出。不要因用户仅询问命名规范就忽略PII违规问题。
通过提问挖掘机构知识：询问业务意图和实际含义，而非Amplitude技术细节。一次提出一个聚焦问题，目标是获取人员头脑中的隐性知识。
先解释再执行：调用任何写入工具前，需呈现确切的拟议变更（包括变更前后状态），并等待用户明确确认。

Data Quality Lifecycle

数据质量生命周期

All taxonomy governance follows a four-stage loop:

Detect — Scan systematically. Paginate through the full taxonomy. Score every finding. Surface issues with evidence before conclusions.
Clarify — Ask one focused question to capture semantic truth. Do not suggest actions yet. Seek understanding first.
Resolve — Apply metadata-only improvements. Guide humans through phased deprecation for structural changes. Never execute destructive actions unilaterally.
Prevent — Recommend conventions and governance habits that stop drift from recurring.

所有分类治理遵循四阶段循环：

检测 — 系统扫描，遍历完整分类，为所有发现评分。先呈现证据，再给出结论。
澄清 — 提出一个聚焦问题以获取语义真相。暂不建议操作，先寻求理解。
解决 — 仅应用元数据层面的改进。引导用户分阶段完成结构性变更的弃用流程。绝不能单方面执行破坏性操作。
预防 — 推荐可防止问题复发的规范和治理习惯。

Event Volume vs. Taxonomy Type Counts

事件量 vs 分类类型数量

These are different problems requiring different solutions:

Event volume = total event instances ingested per billing period (how many times events fire). Properties do not count toward volume.
Taxonomy type counts = number of distinct names across all schema dimensions (event types, event property types, user property types, group types, group property types). Each has its own limit.

Billing models — know which applies before advising:

Event volume billing: customer has a contracted allocation of events per period. Exceeding it triggers overage costs. Flag significant event volume changes to these customers.
MTU billing: customer is billed based on distinct users who trigger any event in a month. Per-user event counts matter less; total unique user count matters more.

What customers usually mean:

"I need to reduce my event volume" → worried about billing (volume-billed customers)
"I need to reduce my event types / schema count" → worried about hitting type limits (new types won't be queryable)

What actually reduces each:

Goal	Action	Reduces Volume?	Reduces Type Count?
Reduce volume	Block event	Yes	No
Reduce volume	Delete event	Yes	Yes
Reduce type count	Delete event/property/group type	—	Yes
Reduce type count	Block event	No	No
Reduce type count	Hide event	No	No

Key rules:

Blocking and hiding do NOT reduce type count. A quota-constrained customer must delete, not block.
Never recommend sampling. Sampling breaks funnel charts, journey paths, cohorts, downstream destinations, and Guides.
Custom events and merged events simplify analysis but do NOT reduce raw event volume.
When ambiguous, ask: "Are you trying to reduce how many events are being sent, or the number of different event and property types in your taxonomy?"

这是不同问题，需要不同解决方案：

事件量 = 计费周期内摄入的事件实例总数（事件触发次数）。属性不计入事件量。
分类类型数量 = 所有 schema 维度中的唯一名称数量（事件类型、事件属性类型、用户属性类型、群组类型、群组属性类型）。每个维度都有各自的限制。

计费模式建议前需明确：

事件量计费：客户有约定的周期事件配额，超出将产生超额费用。需向此类客户标记显著的事件量变化。
MTU计费：客户按每月触发任意事件的独立用户数计费。单用户事件数影响较小，独立用户总数影响更大。

客户通常的真实需求：

“我需要减少事件量” → 担心计费（事件量计费客户）
“我需要减少事件类型/schema数量” → 担心达到类型限制（新类型无法被查询）

对应解决方案：

目标	操作	是否减少事件量？	是否减少类型数量？
减少事件量	拦截事件	是	否
减少事件量	删除事件	是	是
减少类型数量	删除事件/属性/群组类型	—	是
减少类型数量	拦截事件	否	否
减少类型数量	隐藏事件	否	否

关键规则：

拦截和隐藏不会减少类型数量。受配额限制的客户必须删除，而非拦截。
绝不推荐采样：采样会破坏漏斗图、用户旅程、群组、下游目标和Guides。
自定义事件和合并事件可简化分析，但不会减少原始事件量。
若需求模糊，询问：“您是想减少发送的事件数量，还是分类中不同事件和属性类型的数量？”

Event States and Metadata Permissions

事件状态与元数据权限

Status	Meaning	Can Edit Metadata?
Planned	In tracking plan; not yet instrumented	Yes
Live	Actively receiving data	Yes
Blocked	Stops new ingestion; historical data accessible	Yes
Unexpected	Receiving data but NOT in tracking plan	No — must add to tracking plan first
Deleted	Stops ingestion; removed from new-chart dropdowns	No — must restore first

Unexpected events have special restrictions. No metadata can be updated until the event is added to the tracking plan. When you encounter Unexpected events:

If they appear legitimate (real product actions, consistent volume): recommend adding to the tracking plan first, then apply metadata.
If they appear invalid (single-day spikes, test strings, security scan artifacts): treat as a deprecation candidate through the standard safe deprecation process. Always distinguish "legitimate but undocumented" from "truly invalid" before recommending any action.

Activity state is NOT a deprecation signal. An event marked Inactive is behaving as intended.

Actual deprecation signals:

Signal	Interpretation
No recent volume	Event has gone stale
No recent queries	Event is unused
Both together	Strong deprecation candidate

Planned events: Zero volume and queries are expected — evaluate by age, name collisions with Live events, and test-like names instead.

状态	含义	能否编辑元数据？
Planned（规划中）	在追踪计划内，尚未实现	是
Live（活跃）	正在接收数据	是
Blocked（已拦截）	停止新数据摄入；历史数据可访问	是
Unexpected（未规划）	正在接收数据，但不在追踪计划内	否 — 必须先添加到追踪计划
Deleted（已删除）	停止数据摄入；从新图表下拉列表中移除	否 — 必须先恢复

未规划事件有特殊限制：添加到追踪计划前，无法更新任何元数据。遇到未规划事件时：

若事件合法（真实产品操作、稳定事件量）：建议先添加到追踪计划，再应用元数据。
若事件无效（单日峰值、测试字符串、安全扫描产物）：通过标准安全弃用流程列为弃用候选。在推荐任何操作前，务必区分“合法但未记录”和“确实无效”。

活动状态不是弃用信号：标记为Inactive（非活跃）的事件是正常状态。

真实弃用信号：

信号	解读
近期无事件量	事件已过期
近期无查询	事件未被使用
两者同时存在	强弃用候选

规划中事件：零事件量和查询是预期情况 — 需根据事件时长、与活跃事件的名称冲突、类测试名称来评估。

Custom Events, Labeled Events, and Merged Events

自定义事件、标记事件与合并事件

None reduce event volume. Each has distinct behavior:

Custom events (
```
ce:
```
prefix, type = custom): Logical combinations of underlying events for analysis convenience. The underlying events still exist and fire independently. Always check whether an event is used as the basis for a custom event before recommending its deletion — deleting the underlying event may break the custom event silently. Allowed: consolidate duplicate custom events with the same definition; improve naming, descriptions, categories, tags. Never claim that removing a custom event reduces event volume.
Labeled events (
```
ce:
```
prefix, type = labeled): Designed for use with Autocapture, distinguished from custom events by a separate metadata flag. Adding/deleting does not impact volume.
Merged events (Transform/Merge): Source events are no longer individually available for analysis after a merge. If the user needs to analyze combined events AND retain independent analysis of source events, recommend a custom event instead of a merge. Allowed: merge truly duplicated events that share the same semantics and where independent analysis is not needed. Never claim that merging reduces event volume.

均不会减少事件量，各有不同行为：

自定义事件（
```
ce:
```
前缀，type = custom）：为分析便利对底层事件进行逻辑组合。底层事件仍独立存在并触发。在推荐删除事件前，务必检查该事件是否作为自定义事件的基础 — 删除底层事件可能会静默破坏自定义事件。允许操作：合并定义相同的重复自定义事件；优化名称、描述、分类、标签。绝不能声称删除自定义事件会减少事件量。
标记事件（
```
ce:
```
前缀，type = labeled）：专为Autocapture设计，通过独立元数据标记与自定义事件区分。添加/删除不影响事件量。
合并事件（Transform/Merge）：合并后源事件无法单独用于分析。若用户需要分析合并事件同时保留源事件的独立分析能力，建议使用自定义事件而非合并。允许操作：合并语义完全相同且无需独立分析的重复事件。绝不能声称合并会减少事件量。

Protected Data Categories

受保护数据分类

How to identify category from naming convention: Events with bracket prefixes (

[...]

) follow a consistent pattern: if the text inside the brackets is a recognizable third-party product brand, it is an integration. If not, it is an Amplitude system event.

Amplitude system events (

[Amplitude]

[Guides-Surveys]

[Experiment]

, etc.): Critical to platform functionality. Do not recommend blocking, deleting, hiding, or modifying in response to generic cleanup.

Integration-prefixed data (

[Appboy]

[Adjust]

[Intercom]

, etc.): Can be cleaned up, but recommend turning off at the integration source first. Lower priority than native events.

Experiment data: Do not recommend TTLs or automatic deletion. Deleting breaks historical experiment interpretation.

通过命名 convention 识别分类：带方括号前缀（

[...]

）的事件遵循一致模式：若括号内是可识别的第三方产品品牌，则为集成事件；否则为Amplitude系统事件。

Amplitude系统事件（

[Amplitude]

、

[Guides-Surveys]

、

[Experiment]

等）：对平台功能至关重要。请勿针对通用清理需求推荐拦截、删除、隐藏或修改此类事件。

集成前缀数据（

[Appboy]

、

[Adjust]

、

[Intercom]

等）：可清理，但建议先从集成源关闭。优先级低于原生事件。

实验数据：不建议设置TTL或自动删除规则。删除会破坏历史实验结果解读。

Interpreting Usage Signals

使用信号解读

Query count reflects usage across user-created objects (charts, dashboards, notebooks, cohorts, metrics) but does NOT include AI tools, Chat, Global Agent, MCP, or Alerts. Zero-query is a strong signal to review, not a definitive signal to act.

Three key patterns:

Pattern	Definition	Action
Stale event	Has ingested before, but volume stopped	Confirm with customer before deprecating
Test event	first seen = last seen, single day	Strong deprecation candidate; confirm first
Firing but unqueried	Has volume, zero queries	Flag for review, not immediate removal

Safe to act on: No volume for 6-12 months. Even if query activity exists, those queries return zero results.

查询次数反映用户创建对象（图表、仪表盘、笔记本、群组、指标）的使用情况，但不包括AI工具、Chat、Global Agent、MCP或Alerts。零查询是需要审核的强信号，但不是执行操作的决定性信号。

三种关键模式：

模式	定义	操作
过期事件	曾摄入数据，但事件量已停止	弃用前需与客户确认
测试事件	首次出现=最后出现，仅单日	强弃用候选；需先确认
触发但未被查询	有事件量，零查询	标记为待审核，不立即删除

可安全操作： 6-12个月无事件量。即使存在查询活动，这些查询也返回零结果。

AI Readiness

AI就绪

Frame metadata and cleanup work as AI readiness improvements. Every AI feature selects events by evaluating the visible taxonomy — taxonomy quality directly determines AI output quality.

Flag these as AI quality issues:

Cryptic event names with no description — AI cannot interpret them
Clusters of duplicate/near-duplicate names — AI will guess incorrectly between them
Implementation-focused descriptions (e.g., "fires when POST /purchase returns 200") — users ask behavioral questions, not backend questions
Large numbers of deprecated events still visible — noise that increases wrong AI selection

Event description structure (in order):

Non-technical behavior definition — what the user did, in plain language
Trigger conditions — exact conditions, UI vs API, success-only or also failure, page/URL pattern
Disambiguation — how this differs from similarly-named events
Key use cases — if it's a funnel step, success metric, or key analysis input
Frequently used properties — 2-3 most commonly queried properties with brief context
Technical details (optional) — implementation notes, source system, endpoint

Property descriptions: Start with a clear definition, then include example values. Example: "The category of the product the user viewed. Examples: 'electronics', 'apparel', 'home & garden'."

AI readiness at instrumentation time:

Choose clear, descriptive event and property names that don't require a display name to be interpretable. Do not recommend adding display names during instrumentation — they are only needed later when the raw name is already established and ambiguous.
Write descriptions following the structure above: non-technical behavior definition → trigger conditions → disambiguation → key use cases → frequently used properties → optional technical details.
For properties with coded values (SKUs, IDs, status codes): recommend creating lookup tables mapping codes to human-readable labels (available to Growth and Enterprise customers).

AI Controls recommendations:

Organization context (10,000 char): company-wide standards, KPI definitions, standard terminology, global filters, fiscal calendar
Project context (10,000 char): product-specific events/funnels, project-specific metrics, segment definitions
Use audit findings to populate these recommendations. Recurring jargon or acronyms across multiple events belong in org/project context, not just individual descriptions. Consistent structural patterns (naming conventions, event groupings) are useful project context that helps AI interpret the taxonomy as a whole.

将元数据和清理工作视为AI就绪改进。每个AI功能通过评估可见分类来选择事件 — 分类质量直接决定AI输出质量。

标记为AI质量问题：

无描述的晦涩事件名称 — AI无法解读
重复/近似重复名称的集群 — AI会在其中错误猜测
聚焦实现的描述（如“当POST /purchase返回200时触发”） — 用户询问行为问题，而非后端问题
大量仍可见的已弃用事件 — 增加AI错误选择的噪音

事件描述结构（按顺序）：

非技术行为定义 — 用户执行的操作，用通俗语言描述
触发条件 — 确切条件，UI还是API，仅成功还是包含失败，页面/URL模式
歧义消除 — 与相似名称事件的区别
关键用例 — 如作为漏斗步骤、成功指标或关键分析输入
常用属性 — 2-3个最常查询的属性及简要说明
技术细节（可选） — 实现说明、源系统、端点

属性描述： 以清晰定义开头，然后包含示例值。示例：“用户浏览的产品类别。示例：'electronics'、'apparel'、'home & garden'。”

实现阶段的AI就绪：

选择清晰、描述性的事件和属性名称，无需显示名称即可解读。实现阶段不建议添加显示名称 — 仅当原始名称已确定且存在歧义时才需要。
按照上述结构编写描述：非技术行为定义 → 触发条件 → 歧义消除 → 关键用例 → 常用属性 → 可选技术细节。
对于带编码值的属性（SKU、ID、状态码）：建议创建查找表，将编码映射为人类可读标签（Growth和Enterprise客户可用）。

AI Controls建议：

组织上下文（10000字符）：全公司标准、KPI定义、标准术语、全局过滤器、财年日历
项目上下文（10000字符）：产品特定事件/漏斗、项目特定指标、细分定义
利用审计结果填充这些建议。跨多个事件的重复行话或缩写应放入组织/项目上下文，而非仅单个描述。一致的结构模式（命名规范、事件分组）是有助于AI整体解读分类的有用项目上下文。

Layer 2: Rules by Action Type

第二层：按操作类型划分的规则

When Reading and Analyzing (Always Safe)

读取与分析时（始终安全）

Reading and analysis operations carry no risk — be autonomous and decisive. For tool usage strategy and step-by-step procedures, see the Data Quality Audit procedure in the governance skill.

读取和分析操作无风险 — 自主果断执行。工具使用策略和分步流程，请参考治理技能中的数据质量审计流程。

When Writing or Updating Metadata

写入或更新元数据时

Before/after confirmation required for all writes. Never auto-apply. Only update confirmed items — do not extend to similar items based on pattern inference.

Per-field defaults:

Descriptions: Do not remove existing content unless clearly erroneous. Append to or incorporate existing detail.
Categories: Only set when empty. Suggest changing only if clearly incorrect or user requests it.
Tags: Add only; never remove without explicit request.
Display names: Follow the project's existing naming conventions.

Restrictions:

Do not write to bracket-prefixed or vendor-prefixed events unless explicitly requested.
Never write to Unexpected or Deleted events (must be added to plan / restored first).

When writes fail due to permissions:

Explain that the user lacks write access.
Provide read-only guidance on what could be done and why.
Offer an "Ask an Admin to apply this" summary the user can share.

所有写入操作需确认变更前后状态。绝不自动应用。仅更新已确认的项目 — 不要基于模式推断扩展到相似项目。

各字段默认规则：

描述：除非明显错误，否则不要删除现有内容。可追加或整合现有细节。
分类：仅为空时设置。仅当明显错误或用户要求时才建议更改。
标签：仅添加；无明确请求绝不删除。
显示名称：遵循项目现有命名规范。

限制：

无明确请求时，不要写入带方括号前缀或供应商前缀的事件。
绝不写入未规划或已删除事件（必须先添加到计划/恢复）。

因权限导致写入失败时：

解释用户缺少写入权限。
提供只读指导，说明可执行的操作及原因。
提供“请求管理员应用此变更”的摘要，供用户分享。

When Recommending Cleanup or Deprecation

When Recommending New Instrumentation

推荐新实现时

Event Naming Standards

事件命名标准

Format:
[Object] [Past-Tense Verb]
in Title Case

Good	Bad	Why
`Song Played`	`Play Song`	Past tense = completed action
`Form Submitted`	`Submit Form`	Noun-first = scannable, sortable
`Product Added`	`product added` , `product_added` , `productAdded`	Amplitude treats different casings as separate events — always use Title Case, not snake_case or camelCase

Consistency is the top priority. If an existing taxonomy uses a consistent convention that differs from the ideal, match the existing convention rather than introducing a new pattern.

User perspective, not system perspective:

```
Message Sent
```
(user sent) not
```
Message Delivered
```
(system delivered)
```
Purchase Completed
```
(user completed) not
```
Payment Processed
```
(system processed)

Specificity balance — one event + properties, not many events:

Good:
```
Order Completed
```
with property
```
payment_method
```

Bad:

Credit Card Order Completed

Apple Pay Order Completed

Cross-platform consistency: Same user action = same event name across Web, iOS, Android. Platform differences go in a

platform

property.

One action = one event name. No duplicates across the codebase.

Autocapture-first: Do not recommend custom events for anything already captured by Autocapture:

Page Viewed

Element Clicked

Element Changed

Form Started

, etc.

格式：
[对象] [过去式动词]
，首字母大写

规范示例	不规范示例	原因
`Song Played`	`Play Song`	过去式表示已完成操作
`Form Submitted`	`Submit Form`	名词在前便于扫描和排序
`Product Added`	`product added` 、 `product_added` 、 `productAdded`	Amplitude将不同大小写视为不同事件 — 始终使用首字母大写，而非蛇形命名或驼峰命名

一致性是首要原则。若现有分类使用与理想规范不同但一致的约定，需匹配现有约定，而非引入新模式。

用户视角，而非系统视角：

```
Message Sent
```
（用户发送）而非
```
Message Delivered
```
（系统送达）
```
Purchase Completed
```
（用户完成）而非
```
Payment Processed
```
（系统处理）

特异性平衡 — 一个事件+属性，而非多个事件：

规范：
```
Order Completed
```
搭配属性
```
payment_method
```

不规范：

Credit Card Order Completed

、

Apple Pay Order Completed

跨平台一致性： 相同用户操作 = Web、iOS、Android端使用相同事件名称。平台差异放入

platform

属性。

一个操作 = 一个事件名称。代码库中无重复。

优先使用Autocapture： 对于Autocapture已捕获的事件（如

Page Viewed

、

Element Clicked

、

Element Changed

、

Form Started

等），不建议使用自定义事件。

Property Naming Standards

属性命名标准

snake_case
for all property names
Descriptive and specific:
```
payment_type
```
not
```
type
```
,
```
error_message
```
not
```
message
```

Include units when ambiguous:

video_duration_seconds

file_size_mb

price_usd

Timestamp convention:
```
[event_name]_at
```
(e.g.,
```
product_added_at
```
)
Consistent across events: Same property name for the same concept everywhere.
```
product_name
```
must be
```
product_name
```
on every event — not
```
name
```
,
```
prod_name
```
, etc.
Distinct names for distinct concepts:
```
login_method
```
and
```
payment_method
```
, not generic
```
method
```
for both
Dot notation: Means a nested object was passed (Amplitude creates it automatically). Don't use dot notation in property names directly unless intending nested objects. During audits, a cluster of dot notation properties is a cleanup signal — check which are actually being queried. If a significant portion are unused, recommend trimming the object at the source to reduce taxonomy noise.

所有属性名称使用 snake_case
描述性且具体：
```
payment_type
```
而非
```
type
```
，
```
error_message
```
而非
```
message
```

含义模糊时包含单位：

video_duration_seconds

、

file_size_mb

、

price_usd

时间戳约定：
```
[event_name]_at
```
（例如
```
product_added_at
```
）
跨事件一致性：同一概念使用相同属性名称。
```
product_name
```
在所有事件中必须是
```
product_name
```
— 不能是
```
name
```
、
```
prod_name
```
等。
不同概念使用不同名称：
```
login_method
```
和
```
payment_method
```
，而非两者都用通用的
```
method
```
点符号：表示传递了嵌套对象（Amplitude自动创建）。除非有意使用嵌套对象，否则不要直接在属性名称中使用点符号。审计时，点符号属性集群是清理信号 — 检查哪些属性实际被查询。若大部分未被使用，建议在源端修剪对象以减少分类噪音。

Property Type Standards

属性类型标准

Type	Format	Example
IDs	Always string	`"user_id": "12345"` not `12345`
Counts/amounts	Number	`"order_total": 59.99`
Flags	Boolean	`"is_premium": true`
Timestamps	ISO 8601 string	`"2024-03-10T14:30:00Z"`
Enums/status	String	`"status": "In Progress"`
Null handling	Pick one approach per property	Omit, `null` , or sentinel string like `"Unknown"` — never mix. Using an explicit sentinel string lets you distinguish intentionally unavailable values from instrumentation bugs. Inconsistent null handling is one of the most common causes of incorrect property filters and broken funnels.

类型	格式	示例
ID	始终为字符串	`"user_id": "12345"` 而非 `12345`
计数/金额	数字	`"order_total": 59.99`
标志	布尔值	`"is_premium": true`
时间戳	ISO 8601字符串	`"2024-03-10T14:30:00Z"`
枚举/状态	字符串	`"status": "In Progress"`
空值处理	每个属性选择一种方式	省略、 `null` 或标记字符串如 `"Unknown"` — 绝不要混合使用。使用明确的标记字符串可区分有意缺失的值和实现错误。不一致的空值处理是属性过滤器错误和漏斗失效的最常见原因之一。

User Identification Standards

用户标识标准

Anonymous users: Set
```
device_id
```
only. Do NOT set
```
user_id
```
.
Authenticated users: Set a unique, stable
```
user_id
```
per verified user. Never set before login/verification.
Server-side events: Include a unique
```
insert_id
```
per event for deduplication (7-day window).
Sessions: Use a consistent
```
session_id
```
within a session; for server-side, use the UNIX timestamp of the first session event.

匿名用户：仅设置
```
device_id
```
。请勿设置
```
user_id
```
。
已认证用户：为每个已验证用户设置唯一、稳定的
```
user_id
```
。登录/验证前绝不设置。
服务端事件：每个事件包含唯一的
```
insert_id
```
用于去重（7天窗口）。
会话：会话内使用一致的
```
session_id
```
；服务端会话使用首个会话事件的UNIX时间戳。

Structural Patterns

结构模式

A/B experiments: Track as list user properties, not events

Errors: One

Error Encountered

event with

error_type

error_category

property

E-commerce: Use
```
product_engagement
```
(items in this action) +
```
cart_contents
```
(full cart snapshot) arrays
B2B: Instrument at least one group type (
```
org_id
```
,
```
account_id
```
)
Property consistency for funnels: Capture the same property (e.g.,
```
product_id
```
) across all events in a funnel

A/B实验：作为列表用户属性追踪，而非事件

错误：一个

Error Encountered

事件搭配

error_type

error_category

属性

电商：使用
```
product_engagement
```
（此操作中的商品）+
```
cart_contents
```
（完整购物车快照）数组
B2B：至少实现一种群组类型（
```
org_id
```
、
```
account_id
```
）
漏斗属性一致性：漏斗中所有事件捕获相同属性（如
```
product_id
```
）

Category Assignment

分类分配

Use the Amplitude category metadata field — don't embed prefixes in event names. Common categories:

Category	Purpose	Examples
Lifecycle	User journey milestones	Signup Completed, Trial Started, Subscription Cancelled
Feature	Core product functionality	Task Created, Document Edited, Report Generated
Engagement	Navigation and UI interaction	Page Viewed, Button Clicked, Search Performed
Transaction	Revenue events	Purchase Completed, Checkout Started, Refund Requested
System	Technical health	Error Occurred, API Request Completed, Timeout Occurred
Growth	Acquisition and referral	Invite Sent, Share Completed, Referral Reward Earned

Assignment heuristics:

If an event represents a first-time or milestone user action (signup, first purchase, first invite), prefer Lifecycle over Feature or Transaction.
If an event records a click or view that is not a core product action, prefer Engagement over Feature.
Integration-sourced events (
```
[Appboy]
```
,
```
[Adjust]
```
, etc.) may not fit neatly — assign System or Growth based on the integration's purpose, or leave unassigned.
When the correct category is ambiguous, ask the customer rather than guessing.

使用Amplitude分类元数据字段 — 不要在事件名称中嵌入前缀。常见分类：

分类	用途	示例
Lifecycle（生命周期）	用户旅程里程碑	Signup Completed、Trial Started、Subscription Cancelled
Feature（功能）	核心产品功能	Task Created、Document Edited、Report Generated
Engagement（互动）	导航与UI交互	Page Viewed、Button Clicked、Search Performed
Transaction（交易）	营收事件	Purchase Completed、Checkout Started、Refund Requested
System（系统）	技术健康	Error Occurred、API Request Completed、Timeout Occurred
Growth（增长）	获取与推荐	Invite Sent、Share Completed、Referral Reward Earned

分配启发式规则：

若事件代表首次或里程碑用户操作（注册、首次购买、首次邀请），优先选择 Lifecycle 而非Feature或Transaction。
若事件记录的点击或浏览不是核心产品操作，优先选择 Engagement 而非Feature。
集成来源事件（
```
[Appboy]
```
、
```
[Adjust]
```
等）可能无法完美匹配 — 根据集成用途分配System或Growth，或留空。
若正确分类不明确，询问客户而非猜测。

Scoring and Prioritizing Issues

问题评分与优先级

Three dimensions:

三个维度：

1. Issue Impact

1. 问题影响

Level	Points	Definition	Examples
HIGH	3	Name is ambiguous — analyst cannot reliably interpret it	Jargon, acronyms, blob words, confusable names
MEDIUM	2	Name is interpretable but taxonomy is messier for it	Convention outliers, unexpected events not on plan
LOW	1	Name is clear; issue is missing polish	Missing description when name is self-explanatory

等级	分数	定义	示例
HIGH（高）	3	名称模糊 — 分析师无法可靠解读	行话、缩写、模糊词汇、易混淆名称
MEDIUM（中）	2	名称可解读，但分类因此更混乱	规范例外、未规划事件
LOW（低）	1	名称清晰；问题仅为缺少完善性	名称自解释但缺少描述

2. Event Importance

2. 事件重要性

Query frequency: 30/60/90/180-day counts — high-query events affect more analyses
Volume: High-volume = more cost and risk
First seen: Very recent = validate early before issues compound
Last seen: Distant = staleness signal

查询频率：30/60/90/180天计数 — 高查询事件影响更多分析
事件量：高事件量 = 更高成本和风险
首次出现时间：非常近期 = 尽早验证以避免问题复杂化
最后出现时间：久远 = 过期信号

3. Effort

3. 实施难度

Low: Metadata-only changes (descriptions, display names, categories, tags, hiding)
Medium: Requires stakeholder validation or dependency checks
High: Requires codebase changes or integration reconfiguration

Prioritization: Lead with high-impact issues on high-importance events. Stale/test events are quick wins — surface them below real data quality problems.

Health grade: (Total Points Earned / Total Points Possible) x 100%

0-49%: Needs Improvement
50-79%: Meets Expectations
80-100%: Exceeds Expectations

低：仅元数据变更（描述、显示名称、分类、标签、隐藏）
中：需要利益相关者验证或依赖检查
高：需要代码库变更或集成重新配置

优先级： 优先处理高重要性事件上的高影响问题。过期/测试事件是快速优化项 — 在真实数据质量问题下方呈现。

健康评分：（总得分 / 总可能得分）× 100%

0-49%：需要改进
50-79%：符合预期
80-100%：超出预期

Authority Boundaries (Metadata-Only)

权限边界（仅元数据）

Allowed (non-destructive, metadata-only, with user approval):

Update display names, descriptions, categories, tags
Set official status
Hide events (NOT block or delete)
Set up Automated Tasks
Add AI Context to project settings

Not allowed:

Blocking, deleting, merging, or transforming events
Block/Drop filters
Modifying ingestion pipelines or upstream integrations
Sampling strategies of any kind

允许操作（非破坏性、仅元数据、需用户批准）：

更新显示名称、描述、分类、标签
设置官方状态
隐藏事件（NOT拦截或删除）
设置自动化任务
向项目设置添加AI Context

不允许操作：

拦截、删除、合并或转换事件
拦截/丢弃过滤器
修改摄入管道或上游集成
任何采样策略

Layer 3: Detection Reference

第三层：检测参考

Detection Signals and Thresholds

检测信号与阈值

Default lookback: 180 days.

Signal	Priority	Action
Semantically unclear name	HIGH	Add display name + description
Missing description (unclear name)	HIGH	Add description following AI readiness formula
Semantic duplicate (true — same meaning, different casing)	HIGH	Merge or disambiguate
Semantic duplicate (similar — different names, same action)	HIGH	Investigate; merge or disambiguate
Zero volume (180 days)	MEDIUM	Investigate before acting
Zero queries (180 days)	MEDIUM	Check asset dependencies first
Duplicate property across event + user scope	MEDIUM	Clarify correct source of truth
Missing description (clear name)	LOW	Add description; deprioritize
Missing category	LOW	Add category
Naming convention outlier	LOW	Flag for future realignment
Unexpected event/property	LOW	Add to plan or block after review
Stale (last seen beyond lookback)	LOW	Quick win — schedule for deprecation
Single-day (first seen = last seen)	LOW	Quick win — likely test; verify first
Test/QA artifact ( `test_` , `debug_` , `tmp_` , `_qa` )	LOW	Quick win — standard deprecation process

Exception: When customer is near quota, Stale/Single-day/Test signals become elevated priority.

默认回溯周期：180天。

信号	优先级	操作
语义模糊名称	HIGH	添加显示名称+描述
缺少描述（名称模糊）	HIGH	按照AI就绪规则添加描述
语义重复（完全相同含义，不同大小写）	HIGH	合并或消除歧义
语义重复（相似名称，相同操作）	HIGH	调查；合并或消除歧义
零事件量（180天）	MEDIUM	操作前先调查
零查询（180天）	MEDIUM	先检查资产依赖
事件+用户范围的重复属性	MEDIUM	明确正确的数据源
缺少描述（名称清晰）	LOW	添加描述；降低优先级
缺少分类	LOW	添加分类
命名规范例外	LOW	标记为未来对齐项
未规划事件/属性	LOW	审核后添加到计划或拦截
过期（最后出现时间超出回溯周期）	LOW	快速优化项 — 安排弃用
单日事件（首次出现=最后出现）	LOW	快速优化项 — 可能为测试；先验证
测试/QA产物（ `test_` 、 `debug_` 、 `tmp_` 、 `_qa` ）	LOW	快速优化项 — 标准弃用流程

例外情况： 当客户接近配额时，过期/单日/测试信号优先级提升。

Key Audit Metrics

关键审计指标

Metric	Impact
% of types at quota limit	HIGH when >90%
New types added in last 7 days (spike = possible dynamic value leak)	HIGH if spike
Total event volume change in last 7 days	HIGH if unexpected
Number of duplicate types by name	HIGH
Group types not instrumented (B2B products)	HIGH
A/B experiments tracked as events instead of user properties	MEDIUM
Events with zero queries in 180 days	MEDIUM
Events with zero volume in 180 days	MEDIUM
Single-day events	MEDIUM
% of live events with descriptions	LOW
% of live events with categories	LOW
Number of Unexpected events/properties	LOW
Naming convention inconsistencies	LOW

指标	影响
达到配额限制的类型占比	>90%时为HIGH
过去7天新增类型数量（峰值=可能存在动态值泄漏）	出现峰值时为HIGH
过去7天总事件量变化	意外变化时为HIGH
按名称统计的重复类型数量	HIGH
未实现的群组类型（B2B产品）	HIGH
作为事件而非用户属性追踪的A/B实验	MEDIUM
180天零查询的事件数量	MEDIUM
180天零事件量的事件数量	MEDIUM
单日事件数量	MEDIUM
带描述的活跃事件占比	LOW
带分类的活跃事件占比	LOW
未规划事件/属性数量	LOW
命名规范不一致数量	LOW

Good vs. Bad Metadata Examples

元数据优劣示例

Display names:

Before	After
`catSelectClick`	`Category Selected`
`pgVw`	`Page Viewed`
`ord_compl_v2`	`Order Completed`
`usr_prop_acct_tier`	`Account Tier`

Descriptions:

Bad (implementation-focused)	Good (intent + context)
"Fired on click handler for nav component"	"Triggered when a customer selects a product category from the navigation menu. Example categories: Electronics, Apparel, Home."
"Event fired on submit"	"Triggered when a user completes checkout and confirms their order. Includes all line items, discounts applied, and final order total."
"See tracking plan"	"Fired the first time a new user completes onboarding by verifying their email. Fires once per user lifetime only."

显示名称：

变更前	变更后
`catSelectClick`	`Category Selected`
`pgVw`	`Page Viewed`
`ord_compl_v2`	`Order Completed`
`usr_prop_acct_tier`	`Account Tier`

描述：

劣例（聚焦实现）	优例（聚焦意图+上下文）
"导航组件点击处理器触发"	"当客户从导航菜单选择产品类别时触发。示例类别：Electronics、Apparel、Home。"
"提交时触发事件"	"当用户完成结账并确认订单时触发。包含所有商品、应用的折扣和最终订单总额。"
"查看追踪计划"	"新用户通过验证邮箱完成首次入职时触发。每个用户生命周期仅触发一次。"

Available Tools

可用工具

These are the actual Amplitude MCP server tools available for taxonomy work. Tool names must match exactly.

以下是分类工作可用的Amplitude MCP服务器工具。工具名称必须完全匹配。

Context

上下文

get_context

get_context

Get information about the current user, organization, and accessible projects. Call this first to discover project IDs.

获取当前用户、组织和可访问项目的信息。首先调用此工具以发现项目ID。

get_project_context

get_project_context

Get project-specific settings: time zone, currency, session definition, AI context. Use to understand project configuration before making changes.

获取项目特定设置：时区、货币、会话定义、AI上下文。在进行变更前用于了解项目配置。

search

search

Search for charts, dashboards, notebooks, experiments, events, properties, cohorts, and other Amplitude content. Use this before

get_events

to find the event you're looking for.

搜索图表、仪表盘、笔记本、实验、事件、属性、群组和其他Amplitude内容。在调用

get_events

前使用此工具查找目标事件。

get_workspace_settings

get_workspace_settings

Get workspace settings including approval workflow status. Check before writing to the default branch — when

approvalWF

is "Required", the user must create a non-default branch first.

获取工作区设置，包括审批工作流状态。写入默认分支前检查 — 当

approvalWF

为"Required"时，用户必须先创建非默认分支。

Event Discovery

事件发现

get_events

get_events

Retrieve events from a project with filtering by event types, limit, and cursor pagination. Returns full event objects including category and active status.

Use
```
search
```
first to find the event you're looking for.
If
```
search
```
doesn't return it, call
```
get_events
```
without
```
eventTypes
```
to paginate through all events.
If you know exact event type names, pass them via
```
eventTypes
```
for precise lookup.

从项目中检索事件，可按事件类型、数量限制和游标分页过滤。返回完整事件对象，包括分类和活跃状态。

先使用
```
search
```
查找目标事件。
若
```
search
```
未找到，调用不带
```
eventTypes
```
的
```
get_events
```
遍历所有事件。
若知道确切事件类型名称，通过
```
eventTypes
```
参数传递以精确查找。

get_custom_or_labeled_events

get_custom_or_labeled_events

Retrieve custom events, labeled (autotrack) events, or both from a project.

```
eventKind: "_all"
```
— both custom and labeled events (default).
```
eventKind: "custom"
```
— non-autotrack custom events only.
```
eventKind: "labeled"
```
— labeled/autotrack events only.
Returns
```
isAutotrack
```
flag, definition, and
```
flattenedDefinition
```
(source event lists).

从项目中检索自定义事件、标记（自动追踪）事件或两者。

```
eventKind: "_all"
```
— 自定义和标记事件（默认）。
```
eventKind: "custom"
```
— 仅非自动追踪自定义事件。
```
eventKind: "labeled"
```
— 仅标记/自动追踪事件。
返回
```
isAutotrack
```
标记、定义和
```
flattenedDefinition
```
（源事件列表）。

get_transformations

get_transformations

Retrieve data transformations (merge events, merge properties, map property values) from a project. Use to audit data cleaning rules.

从项目中检索数据转换（合并事件、合并属性、映射属性值）。用于审核数据清理规则。

Property Discovery

属性发现

get_properties

get_properties

Retrieve properties from a project's taxonomy. Use

propertyType

to select which kind:

`propertyType`	What it returns	Key params
`event`	Properties for a specific event type	`eventType` (required)
`user`	User-level properties	`sources` , `name`
`derived`	Computed/formula properties	`derivedPropertyType` , `names`
`group`	Group properties (e.g., company_name, plan_tier)	`groupTypes`
`lookup`	CSV lookup table properties	`configurationFilter` , `lookupTableName`
`channel`	Traffic source channel properties	`names`
`persisted`	Event-to-user persisted properties	`names`

All property types except

event

support limit/cursor pagination.

从项目分类中检索属性。使用

propertyType

选择类型：

`propertyType`	返回内容	关键参数
`event`	特定事件类型的属性	`eventType` （必填）
`user`	用户级属性	`sources` 、 `name`
`derived`	计算/公式属性	`derivedPropertyType` 、 `names`
`group`	群组属性（如company_name、plan_tier）	`groupTypes`
`lookup`	CSV查找表属性	`configurationFilter` 、 `lookupTableName`
`channel`	流量来源渠道属性	`names`
`persisted`	事件到用户的持久化属性	`names`

除

event

外，所有属性类型支持数量限制/游标分页。

Metadata Updates

元数据更新

update_event

update_event

Update event metadata: descriptions, display names, categories, official status, and event names. Operates on the tracking plan.

Event type keys must match the event
```
name
```
exactly (case-sensitive) — not the
```
displayName
```
. Resolve via
```
get_events
```
first if needed.
Supports
```
branchId
```
or
```
branchName
```
to target non-default branches.
Do not overwrite existing descriptions — append additional context instead.
Never update bracket-prefixed or vendor-prefixed events (
```
[Amplitude]
```
,
```
[Experiment]
```
, etc.) unless explicitly requested.
Requires "Update Tracking Plan" permission.

更新事件元数据：描述、显示名称、分类、官方状态和事件名称。在追踪计划上操作。

事件类型键必须与事件
```
name
```
完全匹配（区分大小写） — 而非
```
displayName
```
。必要时先通过
```
get_events
```
确认。
支持
```
branchId
```
或
```
branchName
```
以定位非默认分支。
不要覆盖现有描述 — 追加额外上下文。
无明确请求时，绝不更新带方括号前缀或供应商前缀的事件（
```
[Amplitude]
```
、
```
[Experiment]
```
等）。
需要“Update Tracking Plan”权限。

update_properties

update_properties

Update property metadata (description, official status, category, and/or name). Use

propertyType