重构: 后端编排拆解与DRY债收敛及命名纠偏

阶段1拆解: stream 系外移 stream_relay.rs,mod.rs 3048→2607,loop_body 502→83
技能收尾: regenerate/edit 回溯补技能,新增 read_skill 工具,项目级技能扫描
DRY: emit 双写 46 处收敛 event_bus 正典,KV 引号归一收口,LOCK-SLOW 33 处单行化
警示骨架 4→1 与压缩兜底 2→1,噪音目录档位收敛,truncate 同名陷阱消除
工具元数据落 ToolMeta 八维,7 张 match 表改查 registry,parity 测试锁等价
命名: is_noise_entry/teardown_round/probe_missed_terminal_event 等 6 项纠偏

crates/df-ai/src/ai_tools_decl.rs

@@ -54,16 +54,47 @@
 /// - `$name`: 工具名 `&str`。
 /// - `$desc`: 工具描述 `&str`(发给 LLM)。
 /// - `$risk`: `RiskLevel`(如 `RiskLevel::Low`)。
+/// - `meta: $meta`(可选段): `ToolMeta` 字面量(DRY 债 #5)。带此段走 `register_meta` 落
+///   条目 + 全局元数据表;不带则 default 元数据(全空,消费方走保守 default 分支)。
 /// - `$schema`: 参数 JSON Schema(`serde_json::Value`),常用 `object_schema(...)`。
 /// - `$handler`: 一个 **block 表达式**(花括号体),返回 `anyhow::Result<serde_json::Value>`。
 ///   体内在 `$args`(serde_json::Value)与 `$capture`(克隆后的捕获变量)上工作。
 ///   宏负责把它包进 `async move { ... }` 并 `Box::pin`——故调用方只写「同步语义的体」,
 ///   不写 `async move`/`Box::pin`/`Box::new` 三层样板。
 ///
-/// 注意:此宏不替代 `register`,而是包装它——`register` 仍是 `AiToolRegistry` 的唯一注册入口,
-/// 宏仅是语法糖。现有 48 个手写 `register` 调用不动,新工具改用 `declare_tool!`。
+/// 注意:此宏不替代 `register`,而是包装它——`register`/`register_meta` 仍是
+/// `AiToolRegistry` 的唯一注册入口,宏仅是语法糖。
 #[macro_export]
 macro_rules! declare_tool {
+    (
+        $registry:expr,
+        $capture:ident : $cap_ty:ty,
+        $name:expr,
+        $desc:expr,
+        $risk:expr,
+        meta: $meta:expr,
+        schema: $schema:expr,
+        $args:ident => $handler:block
+    ) => {{
+        let __cap: $cap_ty = $capture.clone();
+        $registry.register_meta(
+            $name, $desc, $schema, $risk, $meta,
+            {
+                let $capture = __cap.clone();
+                ::std::boxed::Box::new(move |$args: ::serde_json::Value| {
+                    let $capture = $capture.clone();
+                    ::std::boxed::Box::pin(async move {
+                        let $capture: $cap_ty = $capture;
+                        $handler
+                    })
+                        as ::std::pin::Pin<::std::boxed::Box<
+                            dyn ::std::future::Future<Output = ::anyhow::Result<::serde_json::Value>>
+                                + ::std::marker::Send,
+                        >>
+                })
+            },
+        );
+    }};
     (
         $registry:expr,
         $capture:ident : $cap_ty:ty,
@@ -74,8 +105,8 @@ macro_rules! declare_tool {
         $args:ident => $handler:block
     ) => {{
         let __cap: $cap_ty = $capture.clone();
-        $registry.register(
-            $name, $desc, $schema, $risk,
+        $registry.register_meta(
+            $name, $desc, $schema, $risk, $crate::ai_tools::ToolMeta::default(),
             {
                 let $capture = __cap.clone();
                 ::std::boxed::Box::new(move |$args: ::serde_json::Value| {
@@ -151,4 +182,38 @@ mod tests {
         let out = reg.execute("const_tool", serde_json::json!({})).await.unwrap();
         assert_eq!(out["ok"], true);
     }
+
+    /// 带 meta 段的宏形态:元数据落条目 + 全局表;不带 meta 段落 default。
+    #[tokio::test]
+    async fn declare_tool_with_and_without_meta() {
+        use crate::ai_tools::ToolMeta;
+        let mut reg = AiToolRegistry::new();
+        let dummy: std::sync::Arc<()> = std::sync::Arc::new(());
+        declare_tool!(
+            reg,
+            dummy: std::sync::Arc<()>,
+            "meta_variant_tool",
+            "带元数据声明的工具",
+            RiskLevel::Low,
+            meta: ToolMeta { path_args: &["path"], readonly: true, ..Default::default() },
+            schema: object_schema(vec![]),
+            _args => { Ok(serde_json::json!({ "ok": true })) }
+        );
+        declare_tool!(
+            reg,
+            dummy: std::sync::Arc<()>,
+            "plain_variant_tool",
+            "不带元数据声明的工具",
+            RiskLevel::Low,
+            schema: object_schema(vec![]),
+            _args => { Ok(serde_json::json!({ "ok": true })) }
+        );
+        let with = reg.meta("meta_variant_tool").expect("meta 变体应已注册");
+        assert_eq!(with.path_args, &["path"]);
+        assert!(with.readonly);
+        assert_eq!(crate::ai_tools::path_arg_keys("meta_variant_tool"), &["path"]);
+        let plain = reg.meta("plain_variant_tool").expect("无 meta 变体应已注册");
+        assert_eq!(plain, ToolMeta::default());
+        assert_eq!(crate::ai_tools::path_arg_keys("plain_variant_tool"), &[] as &[&str]);
+    }
 }