docs: explain shell activity and platform support boundaries

This commit is contained in:
2026-11-12 19:10:08 +08:00
parent c28c08a29a
commit 50571e156e
6 changed files with 50 additions and 1 deletions
+9
View File
@@ -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<Box<dyn CloudSourceProvider>>,
// 最近一次 list_files 成功返回的完整列表,刷新失败仍保留供界面查看。
pub files: Vec<SourceFile>,
// 最近成功打开的内容;选择另一个文件失败时保持旧内容,不显示半读取结果。
pub opened: Option<OpenedSource>,
// 最近调用错误的可显示文本,成功 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();