docs: clarify shell observation and window-local tab contracts

src/shell/activity.rs

@@ -1,5 +1,5 @@
 //! 有界 HTTP 活动记录。保存请求/响应的可显示预览供 Network 工具读取，不负责执行请求。
-//! 正文预览和允许显示的头部受限制，避免活动面板成为无限日志或暴露不必要数据的通道。
+//! 本模块限制预览字节数与记录条数；请求头白名单由 runtime/api::ObservedRequest 提前筛选。
 //!
 //! Bounded observation of this process's local HTTP API, never external traffic.
 use std::{
@@ -20,10 +20,11 @@ const MAX_RECORDS: usize = 80;
 pub struct Exchange {
     // 由 begin 分配的日志身份，HTTP worker 后续只携带此 ID 更新，不持有队列元素引用。
     pub id: u64,
-    // 请求方法和来源标签由本地 API 观察器传入；origin 只供显示，不授予执行权限。
+    // 请求方法由本地 API 观察器传入，按原文本保存；这里不校验或执行 HTTP 方法。
     pub method: String,
     // 请求 URL 的受限预览，不在此解析路由或读取所指文件。
     pub path: String,
+    // ObservedRequest 传入 HTTP/Console 显示标签；本字段不参与认证或路由，也不在此截断。
     pub origin: String,
     // 开始时刻的 UTC 时分秒文本，不含日期；耗时另用 started 单调时钟计算。
     pub timestamp: String,
@@ -35,7 +36,9 @@ pub struct Exchange {
     pub status: Option<u16>,
     // 初始为零，finish 时从 begin 起累计毫秒；不在界面每次绘制时持续刷新。
     pub elapsed_ms: u128,
+    // 请求头已经过观察器白名单筛选，这里再截断文本；ActivityLog 自身不检查头名称。
     pub request_headers: String,
+    // respond 提供已构造响应的全部头部文本，本模块仅限长，不沿用请求头的白名单。
     pub response_headers: String,
     // 使用单调时钟计算耗时，不受系统时间调整影响；timestamp 则用于显示 UTC 时刻。
     started: Instant,
@@ -46,6 +49,7 @@ pub struct Exchange {
 pub struct ActivityLog {
     // 开始顺序队列，Network/Console 工具通过共享锁读取或复制；完成顺序不会重排记录。
     pub records: VecDeque<Exchange>,
+    // 默认从零开始，begin 先递增再使用；计数仅属此日志实例，不是跨进程请求身份。
     next_id: u64,
 }
 impl ActivityLog {
@@ -100,6 +104,7 @@ impl ActivityLog {
     // 仅更新仍保留的请求，响应正文和头部都重新截断；耗时从 begin 起计算。
     // ObservedRequest::respond 在真实响应发送前调用，状态和耗时表示已构造响应，不证明客户端接收成功。
     pub fn finish(&mut self, id: u64, status: u16, body: &str, headers: String) {
+        // finish 可能晚于容量淘汰，找不到 ID 时整个更新跳过；不为旧响应另建记录。
         if let Some(record) = self.records.iter_mut().find(|r| r.id == id) {
             record.status = Some(status);
             record.response = preview(body);