docs: explain Tessera modules and execution flows in Chinese

src/runtime/api/guide.rs

@@ -1,6 +1,9 @@
+//! 从当前命名空间生成 /agent 使用指南。返回的示例、地址和版本描述来自运行时上下文；这里生成文档，不执行用户源码。
+//!
 //! Live agent-facing guide generated from the current namespace.
 use super::*;
 
+/// 用当前命名空间、地址和版本填充在线指南，示例来自项目内置 Endor 源码。
 pub(super) fn agent_guide(namespace: &NamespaceState) -> String {
     format!(
         r##"# Tessera Agent API

src/runtime/api/tests.rs

@@ -1,3 +1,6 @@
+//! API 集成回归。通过实际本地 HTTP 请求检查队列、候选替换、状态码、版本和完整文档发布。
+//! 测试服务使用独立监听地址和串行 worker；应结合断言理解成功输入、失败候选、过期事件和关闭的不同保留语义。
+//!
 use super::*;
 use std::{
     io::Write,

src/runtime/api/worker.rs

@@ -1,3 +1,7 @@
+//! 唯一串行执行 VM 的 API worker。保留活跃运行时，另建 PUT 候选，并在候选完整成功后切换发布。
+//! 输入、视口刷新与候选布局可以跨 worker 轮次挂起；中途只公布完整文档，不能让新输入进入未结束的只读调用。
+//! 事件身份同时校验窗口、session、layout_version 和 Mount 能力。失败、替换与关闭分别处理，避免旧回调或旧命令泄漏到新 VM。
+//!
 //! Serial VM ownership, incremental requests, publication and shutdown.
 use super::*;
 
@@ -13,6 +17,7 @@ type CandidateOutcome = std::thread::Result<
     )>,
 >;
 
+/// 已执行业务部分但仍在等待展示刷新的输入元数据，避免恢复时重放回调。
 pub(super) struct PendingInput {
     epoch: u64,
     id: u64,
@@ -20,17 +25,20 @@ pub(super) struct PendingInput {
     result: endor_host::ReplResult,
 }
 
+/// 挂起 HTTP 请求的阶段：等旧刷新、继续输入或继续隔离候选。
 pub(super) enum PendingRequest {
     BeforeInput,
     Input(Box<PendingInput>),
     Candidate(Box<endor_host::ReplSession>),
 }
 
+/// 一次 worker 推进的结果：继续保留请求或交付最终响应。
 pub(super) enum RequestProgress {
     Pending(PendingRequest),
     Complete(HttpResponse),
 }
 
+/// 只提取仍属于当前 session 的窗口尺寸，避免旧原生窗口给新候选提供错误约束。
 fn current_viewports(
     current: &NamespaceState,
 ) -> std::collections::BTreeMap<u64, crate::layout::Size> {
@@ -55,11 +63,13 @@ fn current_viewports(
 }
 
 #[derive(Default)]
+/// 唯一活跃 VM 的串行拥有者，另行管理候选和下一 session 身份。
 pub(super) struct Worker {
     pub(super) repl: Option<(u64, endor_host::ReplSession)>,
     pub(super) next_session: u64,
 }
 impl Worker {
+    /// 撤销活跃运行时并有界清理窗口、Mount 和任务；故障域不再执行新的业务回调。
     pub(super) fn shutdown_runtime(&mut self) -> ShutdownOutcome {
         let Some((_, mut runtime)) = self.repl.take() else {
             return ShutdownOutcome {
@@ -90,6 +100,7 @@ impl Worker {
         }
     }
 
+    /// 处理当前无法继续正常交互的窗口关闭，撤销原生资源与相应运行时记录。
     pub(super) fn close_inactive_window(
         &mut self,
         input: &crate::events::Input,
@@ -162,6 +173,7 @@ impl Worker {
         )
     }
 
+    /// 在没有前台输入的 worker 轮次推进尺寸和任务引起的展示刷新。
     pub(super) fn refresh_viewport(
         &mut self,
         namespace: &Arc<RwLock<NamespaceState>>,
@@ -170,12 +182,14 @@ impl Worker {
         self.refresh_viewport_mode(namespace, notify, false);
     }
 
+    /// 在输入之间推进视口/任务刷新；提交序号或 session 已变时拒绝旧结果发布。
     pub(super) fn refresh_viewport_mode(
         &mut self,
         namespace: &Arc<RwLock<NamespaceState>>,
         notify: &Notify,
         before_input: bool,
     ) {
+        // 在读锁内取得一个一致的提交身份和尺寸快照；耗时 VM 工作不占用共享状态写锁。
         let (epoch, viewports) = match namespace.read() {
             Ok(current) => {
                 let viewports = current_viewports(&current);
@@ -216,6 +230,7 @@ impl Worker {
             }
             Ok((completed.or(resized), runtime.take_window_commands()?))
         }));
+        // 计算结束后重新核对归属：期间若发生 PUT/DELETE，不能把旧域草稿发布出去。
         let mut current = match namespace.write() {
             Ok(current) => current,
             Err(_) => return,
@@ -267,6 +282,7 @@ impl Worker {
         }
     }
 
+    /// 检查请求种类和归属，必要时先等已有刷新结束，再建立输入或候选任务。
     pub(super) fn begin_request(
         &mut self,
         job: &BuildRequest,
@@ -591,6 +607,7 @@ impl Worker {
         ))
     }
 
+    /// 恢复已挂起的请求，保持原 HTTP 响应和运行时身份直到最终完成。
     pub(super) fn resume_request(
         &mut self,
         job: &BuildRequest,
@@ -607,6 +624,7 @@ impl Worker {
         }
     }
 
+    /// 继续同一 Console/事件输入的展示刷新，不再次执行其业务回调。
     fn resume_input(
         &mut self,
         job: &BuildRequest,
@@ -671,6 +689,7 @@ impl Worker {
     }
 
     #[allow(clippy::too_many_arguments)]
+    /// 校验输入仍属于当前域，再一次性发布结果、元数据和原生窗口命令。
     fn finish_input(
         &mut self,
         job: &BuildRequest,
@@ -768,6 +787,7 @@ impl Worker {
 
     /// An accepted PUT changes the submission, but does not revoke the old
     /// runtime. DELETE clears runtime_session and does revoke it.
+    /// 接受较新提交不等于立即销毁旧 VM；候选失败时仍需保留当前可用运行时。
     pub(super) fn preserve_live_owner(&mut self, current: &NamespaceState) {
         if let Some((epoch, runtime)) = &mut self.repl {
             if current.runtime_session == runtime.id {
@@ -778,6 +798,7 @@ impl Worker {
         }
     }
 
+    /// 为完整 PUT 建立隔离候选，保留旧运行时直到新候选完整成功。
     fn begin_program_request(
         &mut self,
         job: &BuildRequest,
@@ -830,6 +851,7 @@ impl Worker {
         RequestProgress::Complete(self.finish_candidate(job, namespace, notify, id, result))
     }
 
+    /// 推进候选的布局与视口收敛，检查其是否已被新提交撤销。
     fn resume_candidate(
         &mut self,
         job: &BuildRequest,
@@ -877,6 +899,7 @@ impl Worker {
         RequestProgress::Complete(self.finish_candidate(job, namespace, notify, id, result))
     }
 
+    /// 候选成功才切换活跃 VM 和文档；失败保留先前已发布程序。
     fn finish_candidate(
         &mut self,
         job: &BuildRequest,
@@ -925,6 +948,7 @@ impl Worker {
     }
 }
 
+/// 处理隔离表达式或一次性文档编译；编译前后核对 submission，只发布仍有效的完整快照。
 fn build(
     job: &BuildRequest,
     namespace: &Arc<RwLock<NamespaceState>>,