Cordis 运行时调试 wang-kaopu/dsh-cordis-devtools

DSH DevTools for Agents

让你的编码 Agent 看到它正在修改的 Cordis 运行时。

English · 简体中文

编码 Agent 可以阅读你的插件源码，但通常无法看到该源码在 DSH 内部实际产生的 Cordis 运行时状态。

这就留下了一个明显的证据缺口：DSH 真的加载了这次改动吗？某个 Event 是否被注册了不止一次？是否还有旧的 Fiber 仍然存活？修复之后运行时究竟发生了什么变化？

DSH DevTools 将这些运行时信息暴露给 Agent。Agent 可以在做出改动之前检查当前状态，在复现过程中等待目标行为出现，并对比重载前后的运行时。

| 调试问题 | 来自 DevTools 的证据 |
| 重载后运行时发生了什么变化？ | checkpoint + 语义拓扑对比 |
| 为什么某个 Event 看起来运行了两次？ | 实时监听器注册、多重性以及所属 Fiber |
| 旧的插件实例是否仍然存活？ | 当前存活的 Fiber 拓扑 |
| 复现过程中目标行为是否出现？ | 最近的派发记录与过滤后的运行时等待 |
| waterfall 链内部发生了什么？ | 带有监听器 span、时序以及 next() 记录的 profiler 追踪 |

一个典型的 Agent 调试循环：

inspect runtime
↓
capture checkpoint
↓
edit plugin
↓
normal reload + reproduce
↓
wait / inspect current runtime
↓
compare checkpoint

代码改动与重载仍通过正常的开发工作流进行。DSH DevTools 缩小了源码与实时运行时之间的证据缺口，为 Agent 提供了可供参考的具体进程状态。

快速开始

1. 将 DevTools 添加到 DSH Web profile

直接从 GitHub 安装 v0.8.0 版本：

dsh plugin --profile web add github:wang-kaopu/dsh-cordis-devtools#v0.8.0

随后你可以从 DSH Web 侧边栏底部打开 Cordis DevTools，直接检查当前运行时。

若要进行仓库开发，请克隆源码并使用本地包：

pnpm install --frozen-lockfile
pnpm build
dsh plugin --profile web add ./

2. 连接 Codex 或其他 MCP 宿主

配置目标 DSH profile，并注册 profile 本地的 stdio 桥接：

dsh plugin --profile web exec dsh-cordis-debug setup --profile web --agent codex

通过你正常的开发工作流重载 DSH，然后检查连接：

dsh plugin --profile web exec dsh-cordis-debug doctor --profile web

setup 会为所选 profile 创建一个仅限所有者访问的 token 文件，启用本地回环 MCP 端点，并将 DevTools 桥接注册到 Codex。

stdio 桥接在本地读取凭据，并将 MCP 请求转发到正在运行的 DSH 进程。该 token 无需进入提示词、工具参数、日志或诊断结果。
对于其他支持 MCP 的宿主，请使用 setup 打印的 bridge 命令，或参阅 MCP 连接指南。

3. 让 Agent 检查、更改并验证

你可以给 Agent 一个带有明确运行时验证步骤的任务：

检查当前的 Cordis 运行时，并在更改此插件之前捕获一个检查点。在我重新加载 DSH 并复现问题后，比较当前运行时，并仅基于保留的运行时证据得出结论。

一个典型的会话如下所示：

list targets
↓
attach session
↓
snapshot / focused inspection
↓
capture checkpoint
↓
edit code + normal reload + reproduce
↓
wait / inspect current runtime
↓
compare checkpoint
↓
detach session

可选的 runtime-debugging Skill 提供了完整的 Agent 工作流，包括游标处理、过期会话、间隙恢复和租约清理。

接口

Agent 工具

| 用途 | 工具 |
| 会话生命周期 | cordis_list_debug_targets、cordis_attach_debug_session、cordis_debug_snapshot、cordis_wait_for_runtime_change、cordis_detach_debug_session |
| 可发现的协议 | cordis_devtools_get_protocol、cordis_devtools_list_targets、cordis_devtools_attach、cordis_devtools_send、cordis_devtools_read_events、cordis_devtools_wait_for_event、cordis_devtools_detach |
| 聚焦的运行时检查 | cordis_runtime_summary、cordis_inspect_event、cordis_inspect_fiber、cordis_search_dispatches、cordis_profiler_traces |
| 运行时验证 | cordis_capture_checkpoint、cordis_compare_current |
| Waterfall 实验 | cordis_waterfall_experiment_status、cordis_start_waterfall_experiment、cordis_stop_waterfall_experiment |

会话、快照、等待、聚焦诊断和验证均为只读路径。通用协议发送器仅在 bearer 认证和显式实验能力均启用时，才能路由 profiler 变更。

当所需的认证和能力设置启用时，Waterfall 实验工具才会暴露。

人类 DevTools

DSH Web 侧边栏提供四个视图：

- Events — 实时 Event 注册、监听器顺序、所有权以及 Event → Fiber 导航；
- Timeline — 最近的 observer 调度元数据；
- Fibers — 实时 Fiber 拓扑、所有权、Effects 以及最近的调度上下文；
- Profiler — waterfall 追踪和显式 profiling 插桩控制。

人类 UI 和 Agent 接口使用相同的 Host 运行时状态。

JSON CLI

相同的调试界面也可通过 dsh-cordis-debug CLI 使用：

dsh plugin --profile web exec dsh-cordis-debug targets
dsh plugin --profile web exec dsh-cordis-debug snapshot
dsh plugin --profile web exec dsh-cordis-debug checkpoint --output checkpoint.jsonbash
dsh plugin --profile web exec dsh-cordis-debug compare --baseline checkpoint.json

完整的命令集请参阅 CLI 参考。

手动回环 MCP

无法直接启动 stdio MCP 服务器的主机可以连接到 DSH 进程内嵌的回环 MCP 端点： yaml
- id: dsh-cordis-devtools
name: dsh-cordis-devtools
config:
mcp:
enabled: true
port: 43127

端点： text http://127.0.0.1:43127/mcp

只读的本地调试无需令牌即可运行。

外部瀑布实验额外需要身份验证和显式的实验能力。

请参阅 MCP 身份验证。

工作原理

DSH DevTools 在 DSH 进程内收集 Cordis 运行时信息，将这些状态保存在 Host 中，并通过 MCP、CLI、DSH 集成和 Web UI 对外暴露。
text
实时 Cordis 运行时 │ ┌────────────────┴────────────────┐ ▼ ▼ ObserverCollector 瀑布插桩拓扑 + 调度 选择性启用 │ │ ▼ ▼ 快照 WaterfallTraceStore │ │ └──────────────┬──────────────────┘ ▼ DevtoolsService Host 持有的状态 │ ┌─────────────┴─────────────┐ ▼ ▼ AgentDebugService RuntimeDiagnosticsQuery 会话 / 快照 / 聚焦查询 / 等待 / 实验租约 检查点 / 比较 │ │ └─────────────┬─────────────┘ ▼ MCP / CLI / Skill / DSH / Web UI │ ┌───────────┴───────────┐ ▼ ▼ Agent 人类

DevtoolsService 是 Host 侧用于运行时收集、近期历史、运行时通知、验证和性能分析协调的组合点。

AgentDebugService 提供面向 Agent 的调试生命周期，包括目标、会话、快照、游标、等待和实验租约。

RuntimeDiagnosticsQuery 提供聚焦的 Event、Fiber、调度和性能分析器跟踪查询，以及检查点捕获和语义比较。

MCP、CLI、DSH 集成和 Web DevTools 都从这一共享的 Host 运行时状态中读取数据，因此每个接口看到的都是同一个 Cordis 运行时。

Observer 路径默认观察器路径读取当前 Cordis 状态并保留近期运行时历史。

它提供：

- 实时 Event 与监听器注册；
- 监听器顺序、注册元数据以及所属 Fiber；
- 当前实时 Fiber 拓扑；
- 近期派发元数据；
- 运行时快照；
- 聚焦的 Event / Fiber / 派发 / 追踪查询；
- 检查点捕获与前后对比；
- 可供 Agent 等待的运行时变更日志。

观察器收集仅限于调试元数据。它不包含 Event 参数、返回值、提示词、工具结果、文件内容、插件配置、令牌或凭据。

运行时证据

派发、分析器追踪和运行时变更观察都有明确的保留窗口。随着新数据到达，较旧的记录会逐渐被淘汰。

查询结果包含相应的窗口状态：

- timeout：在当前窗口内未观察到匹配的变更；
- gap：当前游标已落后于保留窗口，需要重新获取快照；
- 检查点对比：报告两个运行时状态之间的语义变更。

例如： text listener multiplicity: 2 → 1 Fiber "foo": removed Event "bar": listener group added

这些结果可直接作为进一步 Agent 分析的证据。根本原因、置信度以及修复是否真正正确，由 Agent 结合源码与运行时状态自行判定。

受控瀑布式分析

观察器路径覆盖拓扑、注册和派发层面的问题。逐监听器计时和瀑布式 next() 行为需要在执行链内部进行临时插桩。

对于这些情况，DevTools 可以运行一次有限期的瀑布式实验： text Agent / Human │ ▼ WaterfallExperimentCoordinator │ exact owner + finite lease ▼ WaterfallInstrumentationController │ ▼ WaterfallTraceStore

WaterfallExperimentCoordinator 负责分析协调。

Agent 实验会获得一个具有有限 TTL 的 leaseId。租约会自动过期，显式停止必须与当前活动的 leaseId 匹配。人类 DevTools 可以随时触发紧急停止。

分析器记录分析元数据，例如 Event 标识、监听器归属、计时、结果以及 next() 行为。业务负载不会被保留。

文档

- 架构与不变量
- Agent 运行时诊断指南
- 受控运行时实验
- 运行时验证设计
- 开发工作流

开发 bash
pnpm install --frozen-lockfile
pnpm verify:policy
pnpm typecheck
pnpm test
pnpm build
pnpm verify:client-bundle
pnpm test:e2e:web

优先选择能覆盖当前变更的最小检查集。
仓库约定和持久性设计决策记录在 AGENTS.md 和 .agents/notes 中。

许可证

Apache-2.0