From ec05424e223d7579c30fc237e9550ef6555894fd Mon Sep 17 00:00:00 2001
From: Codex Bot <codex-bot@gitea.entroia.local>
Date: Thu, 12 Nov 2026 21:30:35 +0800
Subject: [PATCH] docs: clarify agent guide template ownership and maintenance

---
 src/runtime/api/guide.rs | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/src/runtime/api/guide.rs b/src/runtime/api/guide.rs
index b12dc57..7bd8cac 100644
--- a/src/runtime/api/guide.rs
+++ b/src/runtime/api/guide.rs
@@ -3,6 +3,7 @@
 //! 指南正文是返回给客户端的静态 Markdown 模板，只有命名空间、版本、地址和内置示例按参数填充。
 //! api::handle 的 GET /agent 分支在 NamespaceState 读锁内调用 agent_guide，随后按 text/markdown 返回。
 //! 原始字符串中的 ```endor/JSON/HTTP 等代码块是给 API 使用者看的文档数据，不是 Rust 会执行的逻辑。
+//! 这不是 API/预算反射生成器：正文中的能力、额度与演进说明需人工随实现维护，format! 不验证这些描述。
 use super::*;
 
 /// 为 /agent 生成可提交代码与查询接口的 Markdown 说明。
@@ -11,6 +12,8 @@ use super::*;
 /// 函数只读传入状态，不能由“指南显示某版本”推断新候选已成功发布；revision 仍以当前发布状态为准。
 pub(super) fn agent_guide(namespace: &NamespaceState) -> String {
     // 一次 format 生成完整响应字符串；原始字符串保留文档换行，具名插值在模板结束处统一提供。
+    // 原始模板内的双花括号输出单个 JSON 花括号；插入的 namespace/示例内容不会被 format 再次解释为格式串。
+    // 调用方当前在共享状态读锁内生成文本，返回的 String 自有内容，不在其中保留 NamespaceState 借用或 VM 句柄。
     format!(
         r##"# Tessera Agent API