From 50571e156ec33cfcaa53bb700e0d71448bc3b4d9 Mon Sep 17 00:00:00 2001 From: Codex Bot Date: Thu, 12 Nov 2026 19:10:08 +0800 Subject: [PATCH] docs: explain shell activity and platform support boundaries --- src/shell/activity.rs | 17 +++++++++++++++++ src/shell/clipboard.rs | 9 +++++++++ src/shell/mod.rs | 3 ++- src/shell/native_chrome.rs | 11 +++++++++++ src/shell/sources.rs | 9 +++++++++ src/shell/tabs.rs | 2 ++ 6 files changed, 50 insertions(+), 1 deletion(-) diff --git a/src/shell/activity.rs b/src/shell/activity.rs index cb354f9..f5b180a 100644 --- a/src/shell/activity.rs +++ b/src/shell/activity.rs @@ -18,15 +18,22 @@ const MAX_RECORDS: usize = 80; #[derive(Clone, Debug)] /// 一次 HTTP 请求/响应的有界观察记录,供 Network 工具查看。 pub struct Exchange { + // 由 begin 分配的日志身份,HTTP worker 后续只携带此 ID 更新,不持有队列元素引用。 pub id: u64, + // 请求方法和来源标签由本地 API 观察器传入;origin 只供显示,不授予执行权限。 pub method: String, + // 请求 URL 的受限预览,不在此解析路由或读取所指文件。 pub path: String, pub origin: String, + // 开始时刻的 UTC 时分秒文本,不含日期;耗时另用 started 单调时钟计算。 pub timestamp: String, + // 初始为空,成功读取请求体后 body 覆盖预览;不是用于执行脚本的原始正文存储。 pub request: String, + // finish 记录已构造响应的正文预览,即使后续 socket 发送失败也可能有值。 pub response: String, // None 表示尚未记录响应;完成后保存 HTTP 状态码,不据此判断业务调用是否成功。 pub status: Option, + // 初始为零,finish 时从 begin 起累计毫秒;不在界面每次绘制时持续刷新。 pub elapsed_ms: u128, pub request_headers: String, pub response_headers: String, @@ -37,12 +44,15 @@ pub struct Exchange { #[derive(Debug, Default)] /// 按容量维护近期 HTTP 活动与请求身份,防止无限日志积累。 pub struct ActivityLog { + // 开始顺序队列,Network/Console 工具通过共享锁读取或复制;完成顺序不会重排记录。 pub records: VecDeque, next_id: u64, } impl ActivityLog { /// 为请求分配活动 ID 并登记其方法、来源和受限头部。 + // runtime/api 的 ObservedRequest 构造时调用;先写日志再由调用方通知界面,本模块不主动唤醒窗口。 pub fn begin(&mut self, method: String, path: String, origin: String, headers: String) -> u64 { + // ID 在当前日志实例内递增,不从队列长度推导;淘汰旧项不会重置计数。 self.next_id += 1; let id = self.next_id; // 显示时间取 Unix 秒数的当日余数;系统时间早于纪元时回退到零。这里只显示时间,不保存日期。 @@ -51,6 +61,7 @@ impl ActivityLog { .unwrap_or_default() .as_secs() % 86400; + // 登记开始状态,正文和响应留空,started 与墙上时钟分别服务耗时和时间显示。 self.records.push_back(Exchange { id, method, @@ -78,13 +89,16 @@ impl ActivityLog { } /// 更新请求正文预览,内容长度仍由活动记录策略限制。 // 线性查找在最多 80 项范围内完成;本方法覆盖之前的请求预览,不拼接分块正文。 + // ObservedRequest::record_body 在读取请求体后调用,后续 submit 仍使用原正文,日志只保存截断副本。 pub fn body(&mut self, id: u64, body: &str) { + // 按 ID 更新仍在队列内的记录;请求被容量淘汰时不重建,以免旧请求挤走较新的观察记录。 if let Some(record) = self.records.iter_mut().find(|r| r.id == id) { record.request = preview(body); } } /// 为指定请求登记响应状态、正文/头部预览与单调时钟耗时;记录已淘汰时忽略。 // 仅更新仍保留的请求,响应正文和头部都重新截断;耗时从 begin 起计算。 + // ObservedRequest::respond 在真实响应发送前调用,状态和耗时表示已构造响应,不证明客户端接收成功。 pub fn finish(&mut self, id: u64, status: u16, body: &str, headers: String) { if let Some(record) = self.records.iter_mut().find(|r| r.id == id) { record.status = Some(status); @@ -96,12 +110,15 @@ impl ActivityLog { } /// 截取可显示的受限文本预览,避免日志无限保留完整大正文。 +// begin/body/finish 统一使用 UTF-8 字节预算;输入未超限时仍返回独立 String,不借用请求缓冲。 pub fn preview(value: &str) -> String { + // 恰好等于上限也保留原文,不追加截断标记;长度判断按字节而不是字符数量。 if value.len() <= BODY_PREVIEW { return value.to_owned(); } // UTF-8 多字节字符不能从中间切开;从字节上限回退到合法边界,确保输出始终是有效字符串。 let mut end = BODY_PREVIEW; + // 最多回退到当前 UTF-8 字符起点,只保证字符边界,不承诺完整字素簇边界。 while !value.is_char_boundary(end) { end -= 1; } diff --git a/src/shell/clipboard.rs b/src/shell/clipboard.rs index 642af6b..10dc876 100644 --- a/src/shell/clipboard.rs +++ b/src/shell/clipboard.rs @@ -5,6 +5,7 @@ use anyhow::{Result, bail}; #[cfg(target_os = "macos")] /// 构造固定 UTF-8 环境的系统命令;本函数不启动进程,退出状态由 read/write 检查。 +// 仅 macOS 的 read/write 使用,构造独立 Command 并覆盖编码环境,不修改宿主进程全局环境变量。 fn command(program: &str) -> std::process::Command { let mut cmd = std::process::Command::new(program); // 从 Finder 等无 LANG 的环境启动时也显式指定 UTF-8,防止系统工具按其他编码转换中文。 @@ -14,6 +15,7 @@ fn command(program: &str) -> std::process::Command { cmd } /// 取得系统剪贴板的 UTF-8 文本,失败作为可显示错误返回。 +// shell/app 处理开发工具粘贴快捷键时调用;失败由工具 input_error 展示,不用空字符串冒充成功。 pub fn read() -> Result { #[cfg(target_os = "macos")] { @@ -22,18 +24,22 @@ pub fn read() -> Result { .arg("-Prefer") .arg("txt") .output()?; + // 进程正常退出但状态非成功仍为错误,不能把可能残缺的 stdout 当作源代码粘贴。 if !output.status.success() { bail!("system clipboard read failed"); } // Never silently replace invalid bytes in the user's source. + // 严格验证输出 UTF-8,非法字节报错而不是替换为 U+FFFD 后悄悄改变用户文本。 Ok(String::from_utf8(output.stdout)?) } + // 平台分支在编译时选择,非 macOS 不尝试猜测其他系统剪贴板命令。 #[cfg(not(target_os = "macos"))] { bail!("system clipboard adapter is not available on this platform") } } /// 将提供的文本交给系统剪贴板命令,不执行文本内容。 +// shell/app 的复制与剪切路径调用;只有成功返回后剪切才会删除编辑器中的选中文本。 pub fn write(value: &str) -> Result<()> { #[cfg(target_os = "macos")] { @@ -42,13 +48,16 @@ pub fn write(value: &str) -> Result<()> { let mut child = command("/usr/bin/pbcopy") .stdin(std::process::Stdio::piped()) .spawn()?; + // 取走子进程管道句柄,后面可显式 drop 发送 EOF,不能让 pbcopy 一直等待更多输入。 let mut stdin = child .stdin .take() .ok_or_else(|| anyhow::anyhow!("clipboard stdin is unavailable"))?; + // 按 UTF-8 原字节写完整内容;写管道失败立即传播,此函数该错误路径没有另外执行 wait。 stdin.write_all(value.as_bytes())?; // 写完后先关闭管道发送 EOF,让 pbcopy 知道输入结束;之后等待退出状态,不能仅以写管道成功作为完成。 drop(stdin); + // 等待真实系统工具退出并检查状态;写入成功和剪贴板操作完成是两个独立检查。 if !child.wait()?.success() { bail!("system clipboard write failed"); } diff --git a/src/shell/mod.rs b/src/shell/mod.rs index de9c57b..d4f3ff7 100644 --- a/src/shell/mod.rs +++ b/src/shell/mod.rs @@ -1,6 +1,7 @@ //! 原生宿主模块入口。窗口、管理控件、系统适配和开发工具状态与用户业务界面分开维护。 //! // 目录确定模块归属;main 中的 crate 根别名保持内部调用路径稳定。 +// app 在原生事件循环中协调这些状态,并通过共享数据和输入协议与 runtime 衔接;本文件只声明模块,不启动线程或窗口。 /// 保存运行活动、请求和诊断记录,供宿主开发工具展示。 pub(crate) mod activity; /// 实现 winit 应用生命周期、窗口协调、输入路由和 softbuffer 像素呈现。 @@ -14,7 +15,7 @@ pub(crate) mod developer_tools; pub(crate) mod native_chrome; /// 维护页面/工具入口列表、折叠宽度和命中目标;可用页面宽度需扣除其占用。 pub(crate) mod sidebar; -/// 从源码与诊断生成可浏览的结构信息,供 Sources 工具定位对象和文本。 +/// 定义云文件 provider 和 Sources 工作区状态,供工具列出文件并只读打开内容。 pub(crate) mod sources; /// 提供宿主管理界面专用的主题、控件和交互状态,和 Endor 业务界面共享底层绘图能力。 pub(crate) mod system_ui; diff --git a/src/shell/native_chrome.rs b/src/shell/native_chrome.rs index c6c66c9..0c01df9 100644 --- a/src/shell/native_chrome.rs +++ b/src/shell/native_chrome.rs @@ -12,6 +12,7 @@ use winit::{ /// The custom draggable row does not receive AppKit's titlebar double-click /// action automatically. Use the native click count and native window actions. /// 读取系统偏好的标题栏双击行为,委托原生窗口执行相应动作。 +// shell/app 在自绘标题控制区左键按下时调用;true 表示本次双击已处理,调用方不再开始普通窗口拖动。 pub fn titlebar_double_click(window: &Window) -> bool { // AppKit 必须在主线程调用;不在主线程、无有效句柄或句柄非 AppKit 时返回未处理。 let Some(main_thread) = MainThreadMarker::new() else { @@ -26,6 +27,7 @@ pub fn titlebar_double_click(window: &Window) -> bool { // SAFETY: called on the event-loop thread during a left-button press, with // a live winit-owned NSView. No native object outlives the Window borrow. unsafe { + // 从当前 AppKit 事件读取原生 clickCount;无事件就不猜测双击,也不执行窗口动作。 let Some(event) = NSApplication::sharedApplication(main_thread).currentEvent() else { return false; }; @@ -33,6 +35,7 @@ pub fn titlebar_double_click(window: &Window) -> bool { if event.clickCount() != 2 { return false; } + // 借用 winit 提供的活动 NSView,再取得所属 NSWindow;不创建窗口或把原生指针保存到外部状态。 let view = &*handle.ns_view.as_ptr().cast::(); let Some(native) = view.window() else { return false; @@ -41,6 +44,7 @@ pub fn titlebar_double_click(window: &Window) -> bool { if native.styleMask().contains(NSWindowStyleMask::FullScreen) { return true; } + // 读取系统标题栏双击设置,字符串转成 Rust 自有值后按约定选原生动作。 let action = NSUserDefaults::standardUserDefaults() .stringForKey(&NSString::from_str("AppleActionOnDoubleClick")) .map(|value| value.to_string()); @@ -58,7 +62,9 @@ pub fn titlebar_double_click(window: &Window) -> bool { /// Called only on winit's main thread, after native creation and before drawing. /// AppKit can restore its default button positions when laying out the title bar. /// 调整真实 macOS 窗口三键的位置,与全尺寸内容和侧栏控制区对齐。 +// shell/app 创建窗口后和绘制前调用;主线程调用由外层保证,此函数本身没有创建 MainThreadMarker 检查。 pub fn align_controls(window: &Window) { + // 取得当前 Window 的句柄,失败或非 AppKit 平台表示无法调整,返回不改变现有原生布局。 let Ok(handle) = window.window_handle() else { return; }; @@ -76,6 +82,7 @@ pub fn align_controls(window: &Window) { if native.styleMask().contains(NSWindowStyleMask::FullScreen) { return; } + // 读取内容视图边界,用与侧栏相同的 HEADER 高度确定标题行中心。 let bounds = view.bounds(); let center = f64::from(crate::sidebar::HEADER) / 2.0; // AppKit 视图可能以左下或左上为原点;先在内容视图内算标题行中心,再转到按钮父视图。 @@ -84,19 +91,23 @@ pub fn align_controls(window: &Window) { } else { bounds.origin.y + bounds.size.height - center }; + // 只处理关闭、最小化和缩放三个真实系统按钮,不创建伪按钮代替原生交互。 for kind in [ NSWindowButton::NSWindowCloseButton, NSWindowButton::NSWindowMiniaturizeButton, NSWindowButton::NSWindowZoomButton, ] { + // 系统样式可能不提供某个按钮,缺失时跳过该项,其他按钮仍继续对齐。 let Some(button) = native.standardWindowButton(kind) else { continue; }; + // 需要按钮父视图做坐标转换;没有父视图时不能直接写内容视图坐标。 let Some(parent) = button.superview() else { continue; }; // 按钮可能位于不同 AppKit 容器,必须使用 convertPoint 而不能直接赋内容视图坐标。 let target = parent.convertPoint_fromView(NSPoint::new(0.0, content_y), Some(view)); + // 保留当前大小与横坐标,仅把目标中心减半高换算成按钮纵向原点。 let frame = button.frame(); let y = target.y - frame.size.height / 2.0; // Preserve native button size, horizontal spacing and behavior. diff --git a/src/shell/sources.rs b/src/shell/sources.rs index 07ada17..673809a 100644 --- a/src/shell/sources.rs +++ b/src/shell/sources.rs @@ -16,7 +16,9 @@ pub struct SourceFile { #[derive(Clone, Debug)] /// 已经取得的源文件内容与标识,不代表它已经被执行。 pub struct OpenedSource { + // provider 返回的展示路径,Sources 面板据此显示当前打开文件标题,不把它当作执行入口。 pub path: String, + // 已读取的文本副本,仅绘制源码行;不覆盖当前已发布文档的 source 或触发热重载。 pub code: String, } @@ -33,12 +35,16 @@ pub trait CloudSourceProvider: std::fmt::Debug + Send { pub struct SourceWorkspace { // None 表示未接入外部文件服务;默认工作区不提供虚构文件或隐式认证。 pub provider: Option>, + // 最近一次 list_files 成功返回的完整列表,刷新失败仍保留供界面查看。 pub files: Vec, + // 最近成功打开的内容;选择另一个文件失败时保持旧内容,不显示半读取结果。 pub opened: Option, + // 最近调用错误的可显示文本,成功 refresh/open 会清空;默认未连接时初始为空。 pub error: String, } impl SourceWorkspace { /// 更新云文件列表并保存结果或错误,供 Sources 页面显示。 + // developer_tools 处理 Action::CloudRefresh 时调用,build 仅根据保存状态绘制,不在绘制中请求 provider。 pub fn refresh(&mut self) { // 未连接时明确写错误并返回;已有文件列表/打开内容不会在失败路径中被清除。 let Some(provider) = &mut self.provider else { @@ -47,6 +53,7 @@ impl SourceWorkspace { }; // 调用是同步的,调用方负责安排执行位置;成功才整体替换列表,失败保留旧列表供查看。 match provider.list_files() { + // 只替换列表并清错,不自动重读或关闭已经打开的文件。 Ok(files) => { self.files = files; self.error.clear(); @@ -56,12 +63,14 @@ impl SourceWorkspace { } /// 更新选中文件的内容与打开状态,失败保持可读错误信息。 // 只读取内容而不执行代码;未连接时直接返回,不像 refresh 那样写入新的错误。 + // developer_tools 处理 Action::CloudOpen(id) 时调用,id 来自 SourceFile,不用显示路径代替 provider 身份。 pub fn open(&mut self, id: &str) { let Some(provider) = &mut self.provider else { return; }; // 成功替换 opened 并清错;失败只更新 error,用户仍可查看之前成功打开的内容。 match provider.open_file(id) { + // provider 返回完整内容后一次替换 opened,查看动作不会执行其中的 Endor 程序。 Ok(source) => { self.opened = Some(source); self.error.clear(); diff --git a/src/shell/tabs.rs b/src/shell/tabs.rs index 6eaeecd..54b6ffc 100644 --- a/src/shell/tabs.rs +++ b/src/shell/tabs.rs @@ -6,12 +6,14 @@ use serde::{Deserialize, Serialize}; #[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)] /// 托管页面注册表的不可变投影,原生工具只使用稳定 ID 与显示元数据。 +// ui_bridge::project_tabs 从当前窗口页面注册表生成;sidebar 画标签,scene 用 developer_tool 标记选择宿主管理页。 pub struct Tab { // 会话内稳定 ID,供原生侧发起切页/关闭操作;不能直接当作 VM 对象地址。 pub id: u64, // 本次发布的标题文本副本,原生界面显示时无需读取 VM。 pub title: String, // 该标签是否是此窗口当前活动页;页面注册表顺序与选中状态分别表示。 + // 投影可反映待提交切页请求,不能仅凭这一字段推断新页面布局已经发布成功。 pub active: bool, // 开发工具页的类别标识;普通页省略此字段,反序列化缺失字段时默认为 None。 #[serde(default, skip_serializing_if = "Option::is_none")]