flow-trace

name	flow-trace
description	对指定功能或模块做全链路追踪（数据流/控制流/错误流），从入口一路追到数据库或 LLM，产出非技术人员也能看懂的端到端路径图（含决策点、数据变换、降级路径）。触发词："/trace"、"路径追踪"、"追踪 XXX"、"这个功能是怎么跑的"、"数据是怎么流转的"、"flow trace"。

路径追踪

版本：v1.0.0 | 状态：已落地 | 触发：/trace、"路径追踪"、"追踪 XXX"、"这个功能是怎么跑的"、"数据是怎么流转的"、"flow trace"

对指定功能或模块进行全链路追踪，输出一份"非程序员也能看懂"的路径图。让黑盒变透明。

为什么需要这个技能

没有路径追踪时：
  产品经理："多文档支持了多个文档"
  → 但不知道文档是全文灌进去的还是被压缩了
  → 不知道历史消息是全保留还是被截断了
  → 不知道出问题时该查哪个环节
  → 结果：要么盲目信任，要么逐行读代码

有路径追踪后：
  "用户发消息 → 加载 3 个文档 → 按类型优先级分预算 → 产品文档全文、参考资料摘要 → 最近 30 条历史 → 发给 AI"
  → 一句话就知道发生了什么
  → 不同意某个环节可以直接提出
  → 出问题知道该查哪一步

触发词

• "路径追踪"、"追踪一下"、"追踪 XXX"
• "flow trace"、"trace"
• "帮我追踪"
• "这个功能是怎么跑的"
• "数据是怎么流转的"
• "/trace"

核心理念

1. 大白话优先：每一步都要有"所以呢？对用户意味着什么？"的解释
2. 追踪到底：从用户操作一直追到数据库/LLM，不能中途断链
3. 标注决策点：每个分支、降级、截断都要标注"为什么这样做"
4. 可审查：输出的路径图让非技术人员也能提出质疑

适用场景

场景	例子	谁需要
理解黑盒	"多文档对话到底是怎么拼的？"	产品经理、新人
方案评审	"这个新功能的数据流对不对？"	技术负责人
排查问题	"用户说 AI 忘了之前聊的内容"	开发者
破坏性变更	"改了这个模块会影响哪些下游？"	架构师
合规审计	"用户数据经过了哪些环节？"	安全/合规
新人上手	"这个系统的核心链路是什么？"	新成员

执行流程

Phase 1: 确定追踪范围

用户说 "追踪 XXX" 或 "XXX 是怎么跑的"
  │
  ├─ 识别追踪目标：功能名 / 模块名 / 用户操作
  │
  ├─ 确定追踪维度：
  │   ├─ 数据流（data flow）: 数据从哪来、经过什么处理、存到哪
  │   ├─ 控制流（control flow）: 先调什么、后调什么、条件分支
  │   └─ 错误流（error flow）: 出错时会怎样、降级策略是什么
  │
  └─ 确定追踪深度：
      ├─ 概览模式（overview）: 3-5 步，适合产品经理和非技术人员
      └─ 详细模式（detail）: 完整调用链 + 代码行号，适合开发者

Phase 2: 代码扫描

# 1. 从入口开始（Controller / 前端组件 / Command）
# 识别关键入口文件

# 2. 追踪调用链
# 从入口沿着方法调用一路往下追

# 3. 识别关键决策点
# if/switch/策略模式 → 标记为"分支点"

# 4. 识别数据变换点
# 参数传递、DTO 转换、聚合计算 → 标记为"数据变换"

# 5. 识别外部交互点
# 数据库读写、LLM 调用、外部 API → 标记为"外部依赖"

Phase 3: 输出路径图

输出模板

概览模式（给产品/非技术人员看）

# [功能名] 路径追踪

> 一句话：[用最简单的话说清楚这个功能做了什么]

## 数据是怎么流转的

[用户操作] ──→ [处理步骤1] ──→ [处理步骤2] ──→ [最终结果] │ └─ 大白话：[这一步其实就是在做XXX]

## 关键决策点

| 步骤 | 决策 | 大白话解释 |
|------|------|-----------|
| 步骤2 | 如果XXX则YYY | 相当于：[日常类比] |

## 对用户的影响

| 场景 | 用户感知 |
|------|----------|
| 正常情况 | [用户看到什么] |
| 异常情况 | [用户看到什么] |

## 可能的疑问

- Q: [非技术人员可能会问的问题]
- A: [用大白话回答]

详细模式（给开发者看）

# [功能名] 路径追踪（详细）

> 追踪目标：[从哪到哪]
> 涉及文件：[N] 个
> 关键分支：[N] 个

## 完整调用链

1. [入口] [文件:行号] │ 输入: [参数] │ 输出: [返回值] │
2. [步骤] [文件:行号] │ 输入: [参数] │ 处理: [做了什么] │ 输出: [返回值] │ ├─ [分支A]: 条件 XXX [文件:行号] │ └─ [处理]: ... │ └─ [分支B]: 条件 YYY [文件:行号] └─ [处理]: ... │
3. [外部调用] [文件:行号] │ 目标: [数据库/LLM/外部API] │ 请求: [什么数据] │ 响应: [返回什么] │
4. [最终输出] [文件:行号] │ 返回: [最终结果]

## 数据变换追踪

[原始输入] │ 类型: UserRequest { content, sessionId } │ ▼ [步骤2: 加载上下文] [中间态1] │ 类型: List (N 个文档) │ 变换: 从 ID 列表 → 完整文档对象 │ ▼ [步骤3: 预算分配] [中间态2] │ 类型: string (PRD_BUNDLE XML) │ 变换: 多文档 → 带优先级标签的 XML │ 决策点: 超预算文档被摘要化 │ ▼ [步骤4: 组装消息] [最终输出] │ 类型: List │ 结构: [系统提示词, PRD上下文, 历史消息..., 当前消息]

## 分支决策表

| # | 位置 | 条件 | 走左边 | 走右边 | 大白话 |
|---|------|------|--------|--------|--------|
| 1 | [文件:行号] | `documents.Count > 1` | 走预算逻辑 | 走原逻辑 | 单文档不限制，多文档才管预算 |
| 2 | [文件:行号] | `remaining >= item.Tokens` | 全文注入 | 摘要注入 | 预算够就放原版，不够放缩印版 |

## 错误/降级路径

| 触发条件 | 降级行为 | 用户感知 |
|----------|----------|----------|
| 文档超预算 | 生成摘要（目录+前文） | AI 可能说"该文档为摘要模式" |
| 历史超预算 | 丢弃早期消息 | AI 可能忘了很早之前聊的 |
| 文档不存在 | 返回错误 | 看到"文档不存在"提示 |

## 文件索引

| 层级 | 文件 | 职责 | 关键行 |
|------|------|------|--------|
| 入口 | `XxxController.cs` | HTTP 端点 | L50-80 |
| 服务 | `XxxService.cs` | 业务逻辑 | L100-200 |
| 基础设施 | `XxxRepository.cs` | 数据存取 | L30-50 |

## 排查 Checklist

| 现象 | 可能原因 | 排查路径 |
|------|----------|----------|
| [用户报告的问题] | [技术原因] | [去哪看、看什么] |

---

追踪技巧

如何找到入口

线索	查找方式
用户说"点了某个按钮"	找前端组件 → 找 API 调用 → 找 Controller
用户说"调了某个接口"	直接找 Controller → 找 Service
用户说"定时任务"	找 Worker / BackgroundService / Cron
用户说"数据不对"	从数据库集合 → 找写入该集合的 Service

如何识别关键决策点

代码中的决策点标志：
  if / else           → 条件分支
  switch / pattern    → 多路分支
  ?? / ?.             → 空值降级
  try / catch         → 错误处理
  .Where() / .Any()   → 数据过滤
  const / 硬编码数字   → 配置阈值（如 token 预算）

如何用大白话解释技术概念

技术术语	大白话翻译
Token 预算	相当于桌子大小——文件太多放不下，就把不重要的折起来
摘要降级	相当于书太厚看不完，先看目录和前言
动态窗口	相当于只记最近聊的内容，太早的忘掉
优先级排序	相当于先给重要的人分座位，剩下的再安排
回退/Fallback	相当于首选方案不行，用备选方案兜底
幂等性	相当于同样的操作做 10 遍，效果跟做 1 遍一样
乐观锁	相当于先改，提交时发现别人也改了就重来
事件驱动	相当于"有事喊我"，不是"我一直盯着"
中间件	相当于保安——每个请求进门前先过安检
依赖注入	相当于"你需要什么工具，我给你准备好"，不用自己去找

---

与其他技能的协作关系

想了解功能怎么工作
  │
  ▼
"追踪 XXX" → 【路径追踪技能】
  │
  ├─ 追踪结果发现了可疑逻辑
  │   └─ "验证一下" → 【人工验证技能】
  │
  ├─ 追踪结果需要端到端确认
  │   └─ "冒烟测试 XXX" → 【冒烟测试技能】
  │
  ├─ 追踪结果发现风险
  │   └─ "风险评估" → 【风险矩阵技能】（待建）
  │
  └─ 追踪结果用于评审
      └─ 输出的路径图直接作为方案评审材料

输出质量规则

必须遵循

1. 每一步都有大白话：不能只写函数名，必须解释"这一步在干嘛"
2. 追踪不能断链：从入口到出口必须连续，不能跳过中间步骤
3. 标注所有决策点：if/switch/降级/截断，每个分支都要说清楚
4. 标注外部依赖：数据库读写、LLM 调用、第三方 API 必须标出
5. 概览模式必须非技术人员能看懂：不用代码术语，用日常类比

禁止

1. 禁止只贴代码：代码是辅助，路径图才是主体
2. 禁止跳过"为什么"：不能只写"走了 A 分支"，要写"因为 XXX 所以走了 A 分支"
3. 禁止遗漏降级路径：正常路径和异常路径都要追踪
4. 禁止遗漏数据变换：数据在每一步的类型和内容变化必须记录

---

实际示例

示例：追踪"多文档对话的上下文组装"

用户说："追踪一下多文档对话是怎么把文档拼给 AI 的"

概览模式输出

# 多文档对话上下文组装 — 路径追踪

> 一句话：用户发消息后，系统把所有文档+聊天记录打包成一个"资料包"发给 AI，
> 但桌子（上下文窗口）大小有限，所以重要文档放原版，不重要的放缩印版。

## 数据是怎么流转的

用户发消息 "这个需求可行吗？"
    │
    ▼
① 找到这个会话关联的 3 个文档
    │ 大白话：看看用户之前往这个对话里加了哪些文档
    │
    ▼
② 给每个文档打"重要程度"标签
    │ 产品文档 → 最重要（必须全文给 AI 看）
    │ 技术文档 → 比较重要
    │ 参考资料 → 有空看看就行
    │
    ▼
③ 按重要程度分配"桌子空间"（60K token 预算）
    │ 产品文档 40K → 预算够，放原版（通过）
    │ 技术文档 25K → 预算不够，放缩印版（只有目录+开头）（注意：摘要降级）
    │ 参考资料 15K → 预算够，放原版（通过）
    │
    ▼
④ 把最近的聊天记录也打包进去（30K 预算）
    │ 大白话：AI 需要记住之前聊了什么，但太久之前的会被忘掉
    │
    ▼
⑤ 加上用户刚发的消息 → 整个资料包发给 AI

## 对用户的影响

| 场景 | 用户感知 |
|------|----------|
| 所有文档预算够 | AI 能看到所有文档的完整内容，回答质量高 |
| 某些文档被摘要 | AI 可能说"该文档当前为摘要模式，如需详细内容请追问" |
| 聊了很多轮 | AI 可能忘了 20 分钟前聊的内容 |
| 只有 1 个文档 | 完全不受影响，跟以前一样 |

---

注意事项

1. 先问用户要概览还是详细：默认给概览模式，用户追问再给详细模式
2. 如果入口不明确：主动问用户"你想从哪里开始追踪？用户操作？API 调用？还是数据库？"
3. 追踪过程中发现 bug：记录下来但不中断追踪，在报告末尾的"发现的问题"里列出
4. 涉及敏感数据：追踪路径中如果经过密码、密钥等字段，标注"此处涉及敏感数据，已脱敏"
5. 跨端追踪：如果链路跨前端→后端→数据库，在每个"端"的边界处明确标注