ARD-DA 设计说明文档

[Irissssaa]

1. 核心目标

DA 作为 VS Code 界面与 GDB 后端（Python 脚本）之间的“协调员”。其核心任务是将“破碎的物理执行帧”还原为“连续的逻辑异步生命线”。

2. UI 架构：“异步视察器”面板

面板使用 VS Code Webview 实现。

**A. 面板内容 **

• 多根节点异步树：如果同时追踪了多个入口，面板应展示多棵独立的执行树。
  • 节点类型：通过颜色区分（例如：红色 代表 async 协程，绿色 代表 sync 同步函数）。
  • 元数据展示：每个节点旁标注 CID、Poll Count（轮询次数）和 State（状态码，如 State: 3）。
• 线程上下文：显示当前路径是由哪个 OS 线程执行的。
• 日志预览：面板下方显示 ardb.log 中与当前选中的 CID 相关的最后几行记录，支持点击跳转。

B. 变量展示策略

• 原生集成：普通的局部变量、全局变量、结构体成员直接利用 VS Code 标准变量面板（通过 -stack-list-variables 自动获取）。
• ARD 增强展示：我们的面板只负责展示 GDB 不太好直观体现的异步元数据（如 __state 的含义、协程挂起地址等）。

​ 细节：

• 当用户在面板点击某个协程节点时，DA 告诉 VS Code：“请将当前的 Selected Frame 切换到这个协程对应的物理帧。”

• 一旦物理帧切换成功，VS Code 原生的变量面板会自动刷新，显示出该协程内部的所有变量。

3. 按钮设计与命令映射

按钮名称	对应后端命令	DA 行为与逻辑
重置 (Reset)	ardb-reset	删除所有断点，CID 计数器归零，并物理清空 ardb.log 文件。
白名单 (Whitelist)	ardb-gen-whitelist	触发静态分析，扫描当前工作目录下的所有 poll 函数并生成白名单。
追踪 (Trace)	ardb-trace <sym>	将目标函数加入追踪根节点。支持通过编辑器右键菜单直接触发。
快照 (Snapshot)	ardb-get-snapshot	从 GDB 获取当前的 异步+同步 调用栈 JSON 数据。

---

4. 通讯协议

DA 必须能够解析 ardb-get-snapshot 输出的标准 JSON。

快照数据示例：

{
  "thread_id": 1,
  "path": [
    {
      "type": "async",
      "cid": 1,
      "func": "minimal::nonleaf::{async_fn#0}",
      "addr": "0x7fffffffd0c4",
      "poll": 2,
      "state": 3
    },
    {
      "type": "sync",
      "cid": null,
      "func": "minimal::sync_a",
      "addr": "0x55555556a014",
      "state": "NON-ASYNC"
    }
  ]
}

---

5. 开发关键逻辑

A. 多根节点处理

• 全局唯一 CID：_CO_NEXT_ID 是唯一的全局计数器，确保不同树下的协程 ID 不冲突。
• 如果快照返回的路径起点不在当前 UI 树中，DA 应动态创建新的根节点。

B. 自动刷新机制

• 触发条件：每当 GDB 触发 stopped 事件（命中断点、单步跳过、暂停）时，DA 应自动执行 ardb-get-snapshot。
• 同步函数处理：DA 必须正确处理 type: "sync" 节点，以展示异步任务是如何跳转到同步代码执行的。

C. 规范要求

• 语言规范：虽然文档用中文，但后端 Python 脚本和 DA TypeScript 源代码必须维持全英文注释和文档字符串。
• DA 必须能优雅处理 null 值或 N/A 状态（例如内存无法读取时）。

D. ARD 追踪流程详细设计

• 第一阶段：白名单的生成与人工删减

  • 一键生成并自动打开：
    • 用户点击面板上的 Gen Whitelist 按钮。
    • DA 执行 ardb-gen-whitelist。
    • 交互优化：DA 成功执行命令后，自动在 VS Code 中打开生成的 poll_functions.txt 文件。
  • 文件监听与自动同步：
    • 用户在文本编辑器中手动删除不需要的函数名并保存（Ctrl+S）。
    • 交互优化：DA 注册一个 **FileSystemWatcher **。一旦监测到 poll_functions.txt 被保存，自动触发一次 ardb-load-whitelist。
    • 反馈：在 VS Code 右下角弹出通知：“Whitelist reloaded (X symbols found)”。

• 第二阶段：追踪入口的交互式选择

  • 在侧边栏面板中增加一个 "Candidates (候选函数)" 模块。
    • 逻辑：当白名单加载成功后，DA 读取该文件内容，并实时更新到面板的列表中。
    • 操作：每个函数名右侧有两个按钮：
      • Trace：点击后立即执行 ardb-trace <sym>。
      • Locate：点击后利用 VS Code 的符号跳转，直接定位到该函数的源码位置。