Refactor/log media sampler

[heshaoqiong-tuya]

Summary

Five commits finish the log refactor. End state: the SDK holds no runtime log state at all — the level is a compile-time ceiling (one SDK-wide, optionally lowered per module), the destination is a compile-time macro, and what compiles in is what emits.

• a7c0369 feat(log)!: compile-time-only logging + AGENTIC_KIT_LOG destination remap — one SDK-wide ceiling AGENTIC_KIT_LOG_LEVEL (0–4, default 4) gates every SDK log macro via the new log_tag_* facade in common/log.h; module code no longer calls log_emit() directly and CI rejects new raw call sites. rtc-tcp-client packet logging picks its INFO/DEBUG sink at compile time (sampling builds have exactly one level; flood mode needs AGENTIC_KIT_TAI_LOG_MEDIA_SAMPLE_N=0 plus a DEBUG ceiling) and its JSON formatter compiles out below INFO — a compile-matrix test sweeps the level × sampling combinations. On top of that, #define AGENTIC_KIT_LOG(level, tag, fmt, ...) is the single destination switch, riding the same integrator pickup as every knob (agentic_kit_config.h / -D / AGENTIC_KIT_USER_CONFIG, first-definition-wins). This is the idiom lwIP (LWIP_PLATFORM_DIAG) and mbedTLS offer: bridging into ESP_LOGx/Zephyr LOG_* no longer needs a vsnprintf-into-buffer round trip, format checking stays in the target macro, and the sink receives the module tag as its own token (per-tag filtering and structured sinks become possible). log_set_level() / log_get_level(), the tai_*_log_level() wrappers, log_set_handler(), log_fn_t and the public log_default_handler() are all gone; a sink written as a function reuses the default stderr output via the new log_emit_valist() (the esp_log_writev role). The docs-audit round is folded in here where it owns the prose: the architecture page's common table lists the log facade, the agent-trigger -v row matches the binary (a compile-time notice, not a runtime switch), the rtc-client reference scopes its runtime logging outside the compile-time facade, and the log.h comment names the tags actually emitted.
• 42591a3 refactor(iot): log_error family -> IOT_LOG* — iot-client's unprefixed log_error/log_warn/log_info/log_debug become IOT_LOGE/LOGW/LOGI/LOGD, following the module-prefix convention of the other private vocabularies (TAI_LOG*, TUYA_BLE_HAL_LOG*). Pure rename over 342 call sites; prose in log.h / AGENTS.md / the knobs guide synced, and the iot_atop_call() sample (header + atop-generic-call guide, both locales) now logs through the public log_tag_error("app", ...) facade instead of the src-private log_error() — not IOT_LOGE, which is src-private too, so the copied sample never compiled from an iot_atop.h-only TU (compile-probed in the docs-audit round). The old names read like facade API and had already leaked into integrator-facing samples.
• 41723f1 feat(log): per-module log ceilings AGENTIC_KIT_{IOT,TAI,TUYA_BLE}_LOG_LEVEL — quiet one module without touching the SDK-wide ceiling (iot-client at info while rtc-tcp-client stays debug). Each knob lives in its module's *_config_defaults.h, #ifndef-defaults to the global ceiling, and is lower-only (effective ceiling = min(global, module), clamped to the global once in the module's config file so block-level gates see the effective ceiling); the facade gate still applies, so a remap can never resurrect a compiled-out line. The clamp closes the hole the adversarial-verify review round caught: block-level gates (the packet-log formatter, the flood branch, tuya-ble's HEXDUMP body) keyed on the knob alone, so a module value above the global ceiling compiled dead code back in (a 19KB formatter behind ((void)0) dispatches, -Werror breaks). tuya-ble gains its first knob and its tuya_ble_config_defaults.h. Tests: tai_log_module_zero_tests keeps probing the facade while only the module is lowered; the compile matrix grows a tai_level dimension plus module-above-global clamp probes (19 combos); log-only parameters that turn unused under a lowered module ceiling get (void) suppressions so integrator -Wextra -Werror builds stay clean. Default builds verified byte-identical. The docs-audit round is folded in here for the two pages this commit last touched: the knobs guide's AGENTIC_KIT_LOG example compiles as printed (real level mapping, no undefined lvl_of()), the tag list matches the emitted tags, a function-sink example shows log_emit_valist() takes no tag — fold "[tag] " into the format string — and the rtc-tcp-client reference documents the flood recipe plus the ceiling-3/sampling-0 silence trap.
• d9b2e5b chore(review) — two-axis review findings folded in: tai_log_module_zero_tests joins the CI valgrind loop, a stale "runtime-chosen level" sentence leaves AGENTS.md, and core_mqtt_config.h's cross-reference points at its surviving sibling.
• d52dccb docs(changelog) — BREAKING entries plus the PR-number backfill, at the tip. Carries the docs-audit round's CHANGELOG fix: the flood knob is spelled AGENTIC_KIT_TAI_LOG_MEDIA_SAMPLE_N again (the missing TAI_ segment defined a dead macro and silently kept 1/50 sampling).

BREAKING — migration

Before	After
-DTAI_LOG_LEVEL=N (rtc-tcp-client), dead -DLOG_LEVEL	-DAGENTIC_KIT_LOG_LEVEL=N — silences the whole SDK at compile time
log_set_level() / log_get_level(), tai_set_log_level() / tai_get_log_level()	a lower ceiling at build time, or level filtering inside your AGENTIC_KIT_LOG target
log_set_handler(fn) / log_fn_t / public log_default_handler()	make that function the AGENTIC_KIT_LOG target — it now receives the level and the bare tag directly

After migrating, a single module can be quieted further without touching the rest: -DAGENTIC_KIT_{IOT,TAI,TUYA_BLE}_LOG_LEVEL=N — lower-only, defaults to the global ceiling.

What the ESP-IDF pair-by-ble example now ships (examples/esp-idf/components/agentic_kit/kit_opts/agentic_kit_config.h):

#define AGENTIC_KIT_LOG(level, tag, fmt, ...)                                   \
    ESP_LOG_LEVEL_LOCAL((level) == LOG_ERROR ? ESP_LOG_ERROR :                  \
                        (level) == LOG_WARN  ? ESP_LOG_WARN :                   \
                        (level) == LOG_INFO  ? ESP_LOG_INFO :                   \
                                              ESP_LOG_DEBUG,                    \
                        tag, fmt, ##__VA_ARGS__)

A sink written as a plain variadic function calls log_emit_valist(level, fmt, args) for the default stderr output instead of re-implementing it.

Two ground rules from the guide (docs/guides/compile-time-knobs.md):

• The AGENTIC_KIT_LOG_LEVEL ceiling still gates — log_tag_* collapse to ((void)0) above it (arguments never evaluated), so a remap cannot resurrect compiled-out lines.
• There is no runtime fallback: the remap must reach every target that compiles SDK sources — including the vendored coreHTTP/coreMQTT, whose logs route into the facade via common/core_{http,mqtt}_config.h.

Tests & build wiring

The SDK's own tests migrated to the shape they prescribe to integrators: each test build's log_config/agentic_kit_config.h remaps AGENTIC_KIT_LOG into one test_log_sink whose PASSTHROUGH / CAPTURE / QUIET / COUNT are modes, not handler swaps (capture rebuilds the "[tag] " prefix, with va_copy and truncation discipline carried over). The wiring lesson on the CMake side: compiled outside the remap, the vendored coreHTTP/coreMQTT lines bypass the sink — exactly what the runtime handler used to catch library-agnostically — so the tuya_iot_client_testlog variant compiles them in alongside the iot sources, and the ble sources compile into the test executable the same way. The plain tuya_iot_client / core_http / core_mqtt targets are untouched: the examples' link path and output stay byte-identical. TAI_LOOPBACK_VERBOSE keeps its name and default-silent behavior (now test_log_env_default()).

Docs follow in both locales: the knobs guide, the iot-client / rtc-tcp-client reference pages, the public header notes, and the AGENTS.md maintainer guide.