traces-and-audit

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skill: TraceMem Traces and Audit

技能：TraceMem 追踪与审计

Purpose

用途

This skill explains the concept of the Decision Trace as an artifact. Understanding this helps you write better "evidence" into the system.

本技能解释了作为工件的Decision Trace（决策追踪）概念。理解这一概念有助于你在系统中写入更优质的“证据”。

When to Use

使用场景

When you need to understand what TraceMem is actually recording.
When generating reports or answering questions about past actions ("Why did you do that?").

当你需要了解TraceMem实际记录的内容时。
当生成报告或回答关于过往操作的问题（如“你为什么这么做？”）时。

When NOT to Use

非使用场景

You generally do not "use" this skill to execute actions, but to inform how you execute them.

通常你不会“使用”本技能来执行操作，而是用它来指导你如何执行操作。

Core Rules

核心规则

The Trace is the Truth: If it's not in the trace, it didn't happen (legally/audit-wise).
Append-Only: You cannot go back and fix history.
Complete Picture: A trace includes your ID, the time, the policy version, the data schema version, and the exact outcomes.

追踪即事实：若内容未在追踪记录中，则从法律/审计角度而言，该操作未发生。
仅可追加：你无法回溯修改历史记录。
完整全貌：一条追踪记录需包含你的ID、时间、策略版本、数据架构版本以及确切的结果。

Correct Usage Pattern

正确使用模式

Design for Readability: When running a decision, imagine a human reading the trace 6 months later.
- "Why did this agent delete this user?"
- Look at the
```
intent
```
  , look at the
```
context
```
  you added, look at the
```
policy
```
  result.
- If the trace answers the question, you succeeded.
Linking: If you chain decisions (one decision triggers another workflow), reference the parent
```
decision_id
```
in the child's
```
metadata
```
or
```
context
```
.

为可读性设计：在执行决策时，设想有人类在6个月后阅读这条追踪记录。

“为什么这个agent删除了该用户？”
查看你添加的
```
intent
```
（意图）、
```
context
```
（上下文）以及
```
policy
```
（策略）结果。
若追踪记录能回答该问题，说明你做得很好。

关联链接：若你串联多个决策（一个决策触发另一个工作流），请在子决策的
```
metadata
```
（元数据）或
```
context
```
中引用父决策的
```
decision_id
```
。

Searching Past Decisions

搜索过往决策

Use

decision_search

to query your agent's previous decisions:

Find precedent: Search by text, category, or tags before making a new decision
Check supersession chains: Results include
```
supersedes
```
and
```
superseded_by
```
indicators -- follow the chain to find the current active decision
Filter by status: Use
```
status: "committed"
```
to find only finalized decisions

Tool: decision_search
Parameters:
  - query: "authentication"  (free-text search)
  - category: "architecture"  (optional)
  - tags: ["jwt", "auth"]  (optional, all must match)
  - status: "committed"  (optional)
  - limit: 10  (optional, default 20, max 100)

This is particularly valuable for:

Answering "Why did we decide X?" questions
Avoiding duplicate or contradictory decisions
Building on prior context when making related decisions

使用

decision_search

查询你的agent的过往决策：

查找先例：在做出新决策前，通过文本、类别或标签进行搜索
检查替代链：搜索结果包含
```
supersedes
```
（替代）和
```
superseded_by
```
（被替代）标识——顺着链条可找到当前生效的决策
按状态筛选：使用
```
status: "committed"
```
仅查找已最终确定的决策

Tool: decision_search
Parameters:
  - query: "authentication"  (free-text search)
  - category: "architecture"  (optional)
  - tags: ["jwt", "auth"]  (optional, all must match)
  - status: "committed"  (optional)
  - limit: 10  (optional, default 20, max 100)

这在以下场景中尤为有用：

回答“我们为什么做出X决策？”这类问题
避免重复或矛盾的决策
在做出相关决策时依托过往上下文

Common Mistakes

常见错误

Phantom Actions: Doing side effects (like calling an external API) without recording it in TraceMem or via a Data Product. This creates "dark matter" — actions that have no record.
Incomplete Evidence: Reading data via a side-channel (not a Data Product) and then acting on it. The trace will show the action but not the data that justified it.
Not searching before deciding: Always check
```
decision_search
```
for existing decisions on the same topic before recording a new one.

幽灵操作：执行副作用操作（如调用外部API）却未在TraceMem或通过Data Product（数据产品）记录。这会产生“暗物质”——即无记录可查的操作。
证据不全：通过侧信道（而非Data Product）读取数据并据此操作。追踪记录会显示操作，但不会显示支撑该操作的数据。
决策前未搜索：在记录新决策前，务必通过
```
decision_search
```
检查同一主题的现有决策。

Safety Notes

安全提示

Exoneration: A good trace protects you (the agent). If a policy was wrong, the trace proves you followed the policy correctly. If data was bad, the trace proves you acted on the bad data you were given.

免责保护：优质的追踪记录能保护你（agent）。若策略有误，追踪记录可证明你正确遵循了策略；若数据有误，追踪记录可证明你是基于给定的错误数据采取的行动。