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

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,