docs: clarify developer tool filtering and module contracts

src/runtime/mod.rs

@@ -10,6 +10,7 @@ pub(crate) mod endor_host;
 /// 识别并组织 Endor 源输入，保留原始诊断位置，支持脚本和兼容入口形式。
 pub(crate) mod endor_script;
 /// 在 VM 中执行捕获/目标/冒泡路由，处理监听器断开、传播停止与事件结果。
+/// 监听器错误会中断序列；末尾 Finish 是正常路径步骤，不是确保异常后仍运行的 finally。
 pub(crate) mod event_dispatch;
 /// 定义原生输入信封与有界客户端，将窗口输入送往运行时而不跨线程调用源函数。
 pub(crate) mod events;

src/shell/developer_tools/console.rs

@@ -52,7 +52,8 @@ pub(super) fn build(
     }
     // 先把活动记录投影成显示行，再把当前输入附在末尾；不会在绘制函数中提交或执行程序。
     let mut lines = Vec::new();
-    // console_after 是清屏水位，只展示其后会改变程序状态的请求；原生 /events 输入不刷入 Console。
+    // console_after 是按开始 ID 划定的清屏水位，展示之后的 PUT/POST/DELETE，排除 /events。
+    // 清屏时尚未完成的旧请求，即使随后完成也不会重新出现；过滤按方法而非实际执行成功与否判断。
     for r in records.iter().filter(|r| {
         r.id > state.console_after
             && (r.method == "PUT" || r.method == "POST" || r.method == "DELETE")
@@ -87,7 +88,7 @@ pub(super) fn build(
             title.action = Some(Action::Request(r.id));
             lines.push(title);
         }
-        // 请求正文逐行展示，首行 > 提示符、续行两个空格；保留源码换行而不执行文本。
+        // 请求正文来自有界日志预览，首行 > 提示符、续行两个空格；不保证是完整提交源码，也不执行文本。
         for (i, line) in r.request.split('\n').enumerate() {
             lines.push(Line::new(
                 format!("{}{line}", if i == 0 { "> " } else { "  " }),

src/shell/developer_tools/network.rs

@@ -17,7 +17,7 @@ pub(super) fn build(
     let bottom = viewport.height - 22.0;
 
     p.fill(Rect::new(x, 32.0, w, 30.0), BAR);
-    // 水位后存在记录才允许 Clear，Action::ClearNetwork 更新工具水位并清除选择，不删除 Console 共用日志。
+    // 水位后存在记录才允许 Clear，不受当前筛选是否有匹配影响；动作更新水位并清除选择，不删除共享日志。
     p.enabled_button(
         Rect::new(x + 3.0, 32.0, 62.0, 29.0),
         "Clear",
@@ -116,7 +116,8 @@ pub(super) fn build(
     );
     // 只登记横向分隔条，父绘制入口最后覆盖绘制并注册 Split::Network 命中目标。
     p.split(Rect::new(x + 1.0, divider, w - 2.0, 1.0), Split::Network);
-    // 详情从完整保留记录中查找，因此筛选隐藏某行后可继续查看已选详情；记录淘汰后才回提示。
+    // 详情从完整保留记录中查找，不复用筛选结果或 network_after；筛选隐藏行后仍可查看。
+    // 正常 ClearNetwork 会另行清 selected_request，记录被容量淘汰后此处也找不到，才回到提示。
     let selected = records
         .iter()
         .find(|r| Some(r.id) == state.selected_request);

src/shell/developer_tools/settings.rs

@@ -18,7 +18,8 @@ pub(super) fn build(p: &mut Painter, state: &mut DeveloperToolsState, viewport:
         MUTED,
         false,
     );
-    // 色块动作携带调色板索引，绘制仅比较当前 accent 标记选中；实际修改由统一动作处理器执行。
+    // 色块动作携带调色板索引，绘制按完整 Color 相等标记选中；实际修改由统一动作处理器执行。
+    // Theme 动作同步本槽 custom 文本；切换工具只传播 accent，不保证各槽旧 custom 文本始终等于当前主题。
     for (i, color) in PALETTE.iter().enumerate() {
         // 每个调色板项固定宽度和间距，索引 i 作为 Action::Theme 的参数与 PALETTE 一一对应。
         let r = Rect::new(x + 24.0 + i as f32 * 44.0, 122.0, 32.0, 32.0);

src/shell/system_ui/mod.rs

@@ -4,7 +4,7 @@
 //! sidebar 与 DeveloperTools 的 Painter 构造本帧 Ui，输入处理保留 Interaction，再用新 Target 集合校正跨帧捕获。
 // 跨帧保存 hover/press/focus，管理命中目标、键盘导航与控件视觉状态。
 mod interaction;
-// 提供管理界面统一的颜色、尺寸和排版常量，避免各工具各自定义主题。
+// 提供管理界面颜色常量、状态混色和强调色亮度限制；控件尺寸及排版由 widgets/调用方另行定义。
 pub mod theme;
 // 把控件状态转换为显示列表和交互目标；本模块不承担用户源程序的执行。
 mod widgets;