docs: explain worker publication and HTTP integration regressions

src/runtime/api/guide.rs

@@ -1,12 +1,16 @@
 //! 从当前命名空间生成 /agent 使用指南。返回的示例、地址和版本描述来自运行时上下文；这里生成文档，不执行用户源码。
 //!
 //! 指南正文是返回给客户端的静态 Markdown 模板，只有命名空间、版本、地址和内置示例按参数填充。
+//! api::handle 的 GET /agent 分支在 NamespaceState 读锁内调用 agent_guide，随后按 text/markdown 返回。
+//! 原始字符串中的 ```endor/JSON/HTTP 等代码块是给 API 使用者看的文档数据，不是 Rust 会执行的逻辑。
 use super::*;
 
 /// 为 /agent 生成可提交代码与查询接口的 Markdown 说明。
 /// format! 使用具名插值注入 namespace.name/revision 与监听地址；示例在编译时嵌入，
 /// 因而请求不会访问示例文件、执行示例或改变会话。正文中的 JSON/Endor 是文档内容。
+/// 函数只读传入状态，不能由“指南显示某版本”推断新候选已成功发布；revision 仍以当前发布状态为准。
 pub(super) fn agent_guide(namespace: &NamespaceState) -> String {
+    // 一次 format 生成完整响应字符串；原始字符串保留文档换行，具名插值在模板结束处统一提供。
     format!(
         r##"# Tessera Agent API
 
@@ -253,9 +257,13 @@ binding. Mouse routing, tab chrome/multiple windows and incremental layout remai
 in progress; process isolation is future work. Console retains objects
 only in its explicitly resettable in-memory VM. It is not an untrusted-code sandbox.
 "##,
+        // 路由指向当前唯一活 namespace，不由请求查询串或任意模板文件决定。
         name = namespace.name,
+        // 只显示最近发布的 revision，不把正在排队的 submission 当作已经成功的新版本。
         revision = namespace.revision,
+        // 与 api::start 的实际监听常量一致；不扫描其他端口或猜测外部网络地址。
         address = API_ADDRESS,
+        // include_str 在应用构建时嵌入例子，处理 GET 时不读磁盘，也不在 VM 运行这个例子。
         example = include_str!("../../../examples/page.endor"),
     )
 }