fix(audit): Batch 7-9 dead_code 标注 + TODO 清理 + 文档同步

Batch 7: dead_code 标注统一 (16 处)
- crates/ 9 处: growth, kernel, pipeline, runtime, saas, skills
- src-tauri/ 7 处: classroom, intelligence, browser, mcp
- 统一格式: #[allow(dead_code)] // @reserved: <原因>

Batch 7+: EvolutionEngine L2/L3 10 个未使用 pub 函数
- 全部标注 @reserved: EvolutionEngine L2/L3, post-release integration

Batch 9: TODO → FUTURE 标记 (4 处)
- html.rs: template-based export
- nl_schedule.rs: LLM-assisted parsing
- knowledge/handlers.rs: category_id from upload
- personality_detector.rs: VikingStorage persistence

Batch 5+: Cargo.lock 更新 (serde_yaml_bw 迁移)

全量测试通过: 719 passed, 0 failed

Cargo.lock

@@ -1606,7 +1606,7 @@ dependencies = [
  "secrecy",
  "serde",
  "serde_json",
- "serde_yaml",
+ "serde_yaml_bw",
  "sha2",
  "sqlx 0.7.4",
  "tauri",
@@ -5913,19 +5913,6 @@ dependencies = [
  "syn 2.0.117",
 ]
 
-[[package]]
-name = "serde_yaml"
-version = "0.9.34+deprecated"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "6a8b1a1a2ebf674015cc02edccce75287f1a0130d394307b36743c2f5d504b47"
-dependencies = [
- "indexmap 2.13.0",
- "itoa 1.0.18",
- "ryu",
- "serde",
- "unsafe-libyaml",
-]
-
 [[package]]
 name = "serde_yaml_bw"
 version = "2.5.3"
@@ -7841,12 +7828,6 @@ dependencies = [
  "subtle",
 ]
 
-[[package]]
-name = "unsafe-libyaml"
-version = "0.2.11"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "673aac59facbab8a9007c7f6108d11f63b603f7cabff99fabf650fea5c32b861"
-
 [[package]]
 name = "unsafe-libyaml-norway"
 version = "0.2.15"

crates/zclaw-growth/src/evolution_engine.rs

@@ -57,6 +57,7 @@ impl EvolutionEngine {
         }
     }
 
+    /// @reserved: EvolutionEngine L2/L3 feature, post-release integration
     /// Backward-compatible constructor
     /// 从 ExperienceStore 中提取共享的 VikingAdapter 实例
     pub fn from_experience_store(experience_store: Arc<ExperienceStore>) -> Self {
@@ -70,6 +71,7 @@ impl EvolutionEngine {
         }
     }
 
+    /// @reserved: EvolutionEngine L2/L3 feature, post-release integration
     pub fn with_config(mut self, config: EvolutionConfig) -> Self {
         self.config = config;
         self
@@ -94,12 +96,14 @@ impl EvolutionEngine {
             .await
     }
 
+    /// @reserved: EvolutionEngine L2/L3 feature, post-release integration
     /// L2 执行：为给定模式构建技能生成 prompt
     /// 返回 (prompt_string, pattern) 供上层通过 LLM 调用后 parse
     pub fn build_skill_prompt(&self, pattern: &AggregatedPattern) -> String {
         SkillGenerator::build_prompt(pattern)
     }
 
+    /// @reserved: EvolutionEngine L2/L3 feature, post-release integration
     /// L2 执行：解析 LLM 返回的技能 JSON 并进行质量门控
     pub fn validate_skill_candidate(
         &self,
@@ -113,6 +117,7 @@ impl EvolutionEngine {
         Ok((candidate, report))
     }
 
+    /// @reserved: EvolutionEngine L2/L3 feature, post-release integration
     /// 获取当前配置
     pub fn config(&self) -> &EvolutionConfig {
         &self.config
@@ -122,6 +127,7 @@ impl EvolutionEngine {
     // L3: 工作流进化
     // -----------------------------------------------------------------------
 
+    /// @reserved: EvolutionEngine L2/L3 feature, post-release integration
     /// L3: 从轨迹数据中提取重复的工具链模式
     pub fn analyze_trajectory_patterns(
         &self,
@@ -133,6 +139,7 @@ impl EvolutionEngine {
         WorkflowComposer::extract_patterns(trajectories)
     }
 
+    /// @reserved: EvolutionEngine L2/L3 feature, post-release integration
     /// L3: 为给定工具链模式构建工作流生成 prompt
     pub fn build_workflow_prompt(
         &self,
@@ -158,6 +165,7 @@ impl EvolutionEngine {
         update
     }
 
+    /// @reserved: EvolutionEngine L2/L3 feature, post-release integration
     /// 获取需要优化的进化产物
     pub async fn get_artifacts_needing_optimization(&self) -> Vec<String> {
         self.feedback
@@ -169,6 +177,7 @@ impl EvolutionEngine {
             .collect()
     }
 
+    /// @reserved: EvolutionEngine L2/L3 feature, post-release integration
     /// 获取建议归档的进化产物
     pub async fn get_artifacts_to_archive(&self) -> Vec<String> {
         self.feedback
@@ -180,6 +189,7 @@ impl EvolutionEngine {
             .collect()
     }
 
+    /// @reserved: EvolutionEngine L2/L3 feature, post-release integration
     /// 获取推荐产物
     pub async fn get_recommended_artifacts(&self) -> Vec<String> {
         self.feedback

crates/zclaw-growth/src/retrieval/cache.rs

@@ -19,7 +19,7 @@ struct CacheEntry {
 }
 
 /// Cache key for efficient lookups (reserved for future cache optimization)
-#[allow(dead_code)]
+#[allow(dead_code)] // @reserved: post-release cache optimization lookups
 #[derive(Debug, Clone, Hash, Eq, PartialEq)]
 struct CacheKey {
     agent_id: String,

crates/zclaw-growth/src/storage/sqlite.rs

@@ -22,7 +22,7 @@ pub struct SqliteStorage {
     /// Semantic scorer for similarity computation
     scorer: Arc<RwLock<SemanticScorer>>,
     /// Database path (for reference)
-    #[allow(dead_code)]
+    #[allow(dead_code)] // @reserved: db path for diagnostics and reconnect
     path: PathBuf,
 }
 

crates/zclaw-kernel/src/export/html.rs

@@ -14,7 +14,7 @@ use zclaw_types::Result;
 /// HTML exporter
 pub struct HtmlExporter {
     /// Template name (reserved for future template support)
-    #[allow(dead_code)] // TODO: Implement template-based HTML export
+    #[allow(dead_code)] // @reserved: post-release template-based HTML export
     template: String,
 }
 

crates/zclaw-kernel/src/generation/mod.rs

@@ -557,7 +557,7 @@ Use Chinese if the topic is in Chinese. Include metaphors that relate to everyda
             .join("\n")
     }
 
-    #[allow(dead_code)]
+    #[allow(dead_code)] // @reserved: instance-method convenience wrapper for static helper
     fn extract_text_from_response(&self, response: &CompletionResponse) -> String {
         Self::extract_text_from_response_static(response)
     }

crates/zclaw-pipeline/src/engine/stage.rs

@@ -589,7 +589,7 @@ impl StageEngine {
     }
 
     /// Clone with drivers (reserved for future use)
-    #[allow(dead_code)]
+    #[allow(dead_code)] // @reserved: post-release stage cloning with drivers
     fn clone_with_drivers(&self) -> Self {
         Self {
             llm_driver: self.llm_driver.clone(),

crates/zclaw-runtime/src/driver/gemini.rs

@@ -616,7 +616,7 @@ struct GeminiResponseContent {
     #[serde(default)]
     parts: Vec<GeminiResponsePart>,
     #[serde(default)]
-    #[allow(dead_code)]
+    #[allow(dead_code)] // @reserved: deserialized from Gemini API, not accessed in code
     role: Option<String>,
 }
 
@@ -643,7 +643,7 @@ struct GeminiUsageMetadata {
     #[serde(default)]
     candidates_token_count: Option<u32>,
     #[serde(default)]
-    #[allow(dead_code)]
+    #[allow(dead_code)] // @reserved: deserialized from Gemini API, not accessed in code
     total_token_count: Option<u32>,
 }
 

crates/zclaw-runtime/src/nl_schedule.rs

@@ -2,7 +2,7 @@
 //!
 //! Three-layer fallback strategy:
 //! 1. Regex pattern matching (covers ~80% of common expressions)
-//! 2. LLM-assisted parsing (for ambiguous/complex expressions) — TODO: wire when Haiku driver available
+//! 2. LLM-assisted parsing (for ambiguous/complex expressions) — FUTURE: post-release LLM-assisted natural language parsing
 //! 3. Interactive clarification (return `Unclear`)
 //!
 //! Lives in `zclaw-runtime` because it's a pure text→cron utility with no kernel dependency.

crates/zclaw-saas/src/auth/handlers.rs

@@ -565,7 +565,7 @@ async fn store_refresh_token(
 
 /// 清理过期和已使用的 refresh tokens
 /// 注意: 现已迁移到 Worker/Scheduler 定期执行，此函数保留作为备用
-#[allow(dead_code)]
+#[allow(dead_code)] // @reserved: backup for Worker/Scheduler cleanup; kept as fallback
 async fn cleanup_expired_refresh_tokens(db: &sqlx::PgPool) -> SaasResult<()> {
     let now = chrono::Utc::now();
     // 删除过期超过 30 天的已使用 token (减少 DB 膨胀)

crates/zclaw-saas/src/knowledge/handlers.rs

@@ -804,7 +804,7 @@ async fn handle_document_upload(
 
     // 创建知识条目
     let item_req = CreateItemRequest {
-        category_id: "uploaded".to_string(), // TODO: 从上传参数获取
+        category_id: "uploaded".to_string(), // FUTURE: post-release category_id from upload params
         title: doc.title.clone(),
         content,
         keywords: None,

crates/zclaw-saas/src/scheduled_task/service.rs

@@ -6,7 +6,7 @@ use super::types::*;
 
 /// 数据库行结构
 #[derive(Debug, FromRow)]
-#[allow(dead_code)]
+#[allow(dead_code)] // @reserved: FromRow deserialization struct; fields accessed via destructuring
 struct ScheduledTaskRow {
     id: String,
     account_id: String,

crates/zclaw-skills/src/orchestration/executor.rs

@@ -83,7 +83,7 @@ impl DefaultExecutor {
     }
 
     /// Execute a single node (used by pipeline orchestration action driver)
-    #[allow(dead_code)]
+    #[allow(dead_code)] // @reserved: post-release pipeline orchestration action driver
     async fn execute_node(
         &self,
         node: &super::SkillNode,

desktop/src-tauri/src/browser/session.rs

@@ -168,7 +168,7 @@ impl SessionManager {
 
     /// Get the number of active sessions
     /// Reserved for future status dashboard
-    #[allow(dead_code)]
+    #[allow(dead_code)] // @reserved: post-release status dashboard session count
     pub async fn session_count(&self) -> usize {
         let sessions = self.sessions.read().await;
         sessions.len()

desktop/src-tauri/src/classroom_commands/persist.rs

@@ -101,7 +101,7 @@ impl ClassroomPersistence {
     }
 
     /// Delete a classroom and its chat history.
-    #[allow(dead_code)]
+    #[allow(dead_code)] // @reserved: post-release classroom deletion Tauri command
     pub async fn delete_classroom(&self, classroom_id: &str) -> Result<(), String> {
         let mut conn = self.conn.lock().await;
         sqlx::query("DELETE FROM classrooms WHERE id = ?")

desktop/src-tauri/src/intelligence/compactor.rs

@@ -99,7 +99,7 @@ pub struct CompactionCheck {
 
 /// Configuration for LLM-based summary generation
 /// NOTE: Reserved for future LLM compaction Tauri command
-#[allow(dead_code)]
+#[allow(dead_code)] // @reserved: post-release LLM compaction Tauri command
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct LlmSummaryConfig {
     pub provider: String,

desktop/src-tauri/src/intelligence/extraction_adapter.rs

@@ -313,7 +313,7 @@ pub fn configure_extraction_driver(driver: Arc<dyn LlmDriver>, model: String) {
 }
 
 /// Check if the extraction driver is available (legacy OnceCell path).
-#[allow(dead_code)]
+#[allow(dead_code)] // @reserved: diagnostic check for legacy OnceCell extraction driver
 pub fn is_extraction_driver_configured() -> bool {
     EXTRACTION_DRIVER.get().is_some()
 }
@@ -321,7 +321,7 @@ pub fn is_extraction_driver_configured() -> bool {
 /// Get the global extraction driver (legacy OnceCell path).
 ///
 /// Prefer accessing via `kernel.extraction_driver()` when the Kernel is available.
-#[allow(dead_code)]
+#[allow(dead_code)] // @reserved: legacy accessor, prefer kernel.extraction_driver()
 pub fn get_extraction_driver() -> Option<Arc<TauriExtractionDriver>> {
     EXTRACTION_DRIVER.get().cloned()
 }

desktop/src-tauri/src/intelligence/personality_detector.rs

@@ -324,7 +324,7 @@ mod tests {
 }
 
 // ---------------------------------------------------------------------------
-// Persistence helpers (stub — TODO: integrate with VikingStorage)
+// Persistence helpers (stub — FUTURE: post-release personality persistence via VikingStorage)
 // ---------------------------------------------------------------------------
 
 use std::sync::OnceLock;

desktop/src-tauri/src/intelligence_hooks.rs

@@ -206,7 +206,7 @@ pub async fn post_conversation_hook(
 ///
 /// NOTE: Memory injection is now handled by MemoryMiddleware in the Kernel
 /// middleware chain. This function is kept as a utility for ad-hoc queries.
-#[allow(dead_code)]
+#[allow(dead_code)] // @reserved: ad-hoc memory context queries outside middleware chain
 async fn build_memory_context(
     agent_id: &str,
     user_message: &str,

desktop/src-tauri/src/kernel_commands/mcp.rs

@@ -33,7 +33,7 @@ impl Default for McpManagerState {
 
 impl McpManagerState {
     /// Create with a pre-allocated kernel_adapters Arc for sharing with Kernel.
-    #[allow(dead_code)]
+    #[allow(dead_code)] // @reserved: alternate constructor for shared MCP adapter injection
     pub fn with_shared_adapters(kernel_adapters: Arc<std::sync::RwLock<Vec<McpToolAdapter>>>) -> Self {
         Self {
             manager: Arc::new(Mutex::new(McpServiceManager::new())),