telemetry: separate social targets from plannerTargets

Author: 129s

docs/architecture/foundation/runtime-api.md

@@ -50,7 +50,7 @@ Headless 工具：仓库提供 `genesis-runtime-cli`（见 `docs/guides/headless
 - 变更集合（按需扩展）：
   - `resourceChanges[]` / `needChanges[]` / `plannerChanges[]` / `actionChanges[]` / `agentChanges[]` / `movementChanges[]`
 
-## TickTelemetry 契约（v5）
+## TickTelemetry 契约（v6）
 最小字段集合，按需扩展；变更需提升 `schema_version` 并记录（GUI 以 schema 做兼容）。
 
 完整字段字典与变更记录见：`docs/architecture/foundation/telemetry-schema.md`。

docs/architecture/foundation/telemetry-schema.md

@@ -1,4 +1,4 @@
-# Telemetry Schema（TickTelemetry v5）
+# Telemetry Schema（TickTelemetry v6）
 
 本文档定义运行时对外暴露的 **TickTelemetry** 数据结构（GUI/工具链消费的只读快照内容之一），并提供最小的版本演进记录，作为“可观测性闭环”的协议基线。
 
@@ -20,13 +20,13 @@
 - 推荐约定（当前仓库采用偏保守策略）：
   - **新增字段也提升版本**（即使是可选字段），用版本号显式驱动消费端适配。
 
-## 2. TickTelemetry（v3）字段字典
+## 2. TickTelemetry（v6）字段字典
 
 代码定义：`include/genesis/telemetry/TelemetryBuffer.hpp`
 
 ### 2.1 顶层字段
 
-- `schema_version:uint32`：Telemetry 协议版本（当前为 5）。
+- `schema_version:uint32`：Telemetry 协议版本（当前为 6）。
 - `step:uint64`：模拟步号（离散时间）。
 - `stepSeconds:float`：单步的时间长度（秒），由 `SimulationClock::stepDuration()` 推导；用于把“每步统计”换算为“每秒速率”。
 - `agents:AgentSnapshot[]`：代理位置与身份摘要。
@@ -67,6 +67,7 @@
 - `currentAction:string`：当前动作类型（例如 `MoveToInteraction/ConsumeResource/TakeResource/ProduceResource/SocializeWithAgent/Idle` 等）。
 - `queueLength:uint32`：行动队列长度。
 - `target:InteractionId(uint32)`：当前动作目标（如移动/消耗/生产的交互点）。
+- `targetEntityId:uint32`：当前动作的实体目标（仅 `SocializeWithAgent` 有意义；否则为 0）。
 - `speed:float`：移动速度（仅在移动相关动作时有意义）。
 - `resource:ResourceType(enum)`：与当前动作相关的资源类型（例如消费/取货/生产的资源）。
 - `amount:uint32`：与当前动作相关的数量（例如本次想消耗/取货的单位数）。

include/genesis/agents/PlannerTargetEncoding.hpp

@@ -0,0 +1,25 @@
+#pragma once
+
+#include <cstdint>
+
+namespace genesis::agents {
+
+// PlannerDecision.target 编码约定：
+// - 真实世界交互点：InteractionId（最高位为 0）
+// - 代理实体目标（例如社交伙伴）：最高位为 1，低 31 位存 entityId
+inline constexpr std::uint32_t kAgentPlannerTargetMask = 0x80000000u;
+
+[[nodiscard]] inline bool isAgentPlannerTarget(std::uint32_t target) noexcept {
+    return (target & kAgentPlannerTargetMask) != 0U;
+}
+
+[[nodiscard]] inline std::uint32_t encodeAgentPlannerTargetEntityId(std::uint32_t entityId) noexcept {
+    return kAgentPlannerTargetMask | (entityId & ~kAgentPlannerTargetMask);
+}
+
+[[nodiscard]] inline std::uint32_t decodeAgentPlannerTargetEntityId(std::uint32_t target) noexcept {
+    return (target & ~kAgentPlannerTargetMask);
+}
+
+} // namespace genesis::agents
+

include/genesis/telemetry/SchemaVersions.hpp

@@ -4,7 +4,6 @@
 
 namespace genesis::telemetry {
 
-inline constexpr std::uint32_t kTickTelemetrySchemaVersion = 5;
+inline constexpr std::uint32_t kTickTelemetrySchemaVersion = 6;
 
 } // namespace genesis::telemetry
-

include/genesis/telemetry/TelemetryBuffer.hpp

@@ -49,6 +49,7 @@ struct ActionSnapshot {
     std::string currentAction;
     std::uint32_t queueLength{0};
     genesis::world::InteractionId target{0};
+    std::uint32_t targetEntityId{0}; // 仅对 SocializeWithAgent 有意义
     float speed{0.0f};
     genesis::world::ResourceType resource{genesis::world::ResourceType::Food};
     std::uint32_t amount{0};

src/agents/NeedSatisfier.cpp

@@ -9,6 +9,7 @@
 #include <utility>
 
 #include "genesis/agents/ActionSystem.hpp"
+#include "genesis/agents/PlannerTargetEncoding.hpp"
 #include "genesis/agents/Beliefs.hpp"
 #include "genesis/agents/Experience.hpp"
 #include "genesis/agents/Needs.hpp"
@@ -21,18 +22,16 @@ namespace genesis::agents {
 
 namespace {
 
-constexpr std::uint32_t kAgentTargetMask = 0x80000000u;
-
 [[nodiscard]] std::uint32_t encodeAgentTarget(entt::entity entity) noexcept {
-    return kAgentTargetMask | static_cast<std::uint32_t>(entt::to_integral(entity));
+    return encodeAgentPlannerTargetEntityId(static_cast<std::uint32_t>(entt::to_integral(entity)));
 }
 
 [[nodiscard]] bool isAgentTarget(std::uint32_t target) noexcept {
-    return (target & kAgentTargetMask) != 0U;
+    return isAgentPlannerTarget(target);
 }
 
 [[nodiscard]] entt::entity decodeAgentTarget(std::uint32_t target) noexcept {
-    return static_cast<entt::entity>(target & ~kAgentTargetMask);
+    return static_cast<entt::entity>(decodeAgentPlannerTargetEntityId(target));
 }
 
 [[nodiscard]] std::uint64_t mix_u64(std::uint64_t x) noexcept {

src/apps/runtime_cli/Main.cpp

@@ -17,6 +17,7 @@
 #include <nlohmann/json.hpp>
 
 #include "genesis/agents/Personality.hpp"
+#include "genesis/agents/PlannerTargetEncoding.hpp"
 #include "genesis/runtime/Runtime.hpp"
 #include "genesis/runtime/SchemaVersions.hpp"
 #include "genesis/telemetry/SchemaVersions.hpp"
@@ -512,14 +513,15 @@ void normalizeScriptPaths(json& script, const std::filesystem::path& root) {
     out << "\n";
 
     out << "## 动作与行为\n\n";
-    if (summary.contains("actions") && summary.at("actions").is_object() && summary.at("actions").contains("counts")) {
-        const auto& actions = summary.at("actions").at("counts");
-        out << "- ConsumeResource: `" << actions.value("ConsumeResource", 0ULL) << "`\n";
-        out << "- TakeResource: `" << actions.value("TakeResource", 0ULL) << "`\n";
-        out << "- ProduceResource: `" << actions.value("ProduceResource", 0ULL) << "`\n";
-        out << "- MoveToInteraction: `" << actions.value("MoveToInteraction", 0ULL) << "`\n";
-    }
-    out << "\n";
+	    if (summary.contains("actions") && summary.at("actions").is_object() && summary.at("actions").contains("counts")) {
+	        const auto& actions = summary.at("actions").at("counts");
+	        out << "- ConsumeResource: `" << actions.value("ConsumeResource", 0ULL) << "`\n";
+	        out << "- TakeResource: `" << actions.value("TakeResource", 0ULL) << "`\n";
+	        out << "- ProduceResource: `" << actions.value("ProduceResource", 0ULL) << "`\n";
+	        out << "- MoveToInteraction: `" << actions.value("MoveToInteraction", 0ULL) << "`\n";
+	        out << "- SocializeWithAgent: `" << actions.value("SocializeWithAgent", 0ULL) << "`\n";
+	    }
+	    out << "\n";
 
     if (summary.contains("switching")) {
         const auto& switching = summary.at("switching");
@@ -762,19 +764,21 @@ struct ResourceEconomy {
     double utilizationSum = 0.0;
     std::uint64_t utilizationSamples = 0;
 
-    struct WorldlineWindowAgg {
-        std::uint64_t steps{0};
-        std::uint64_t needSamples{0};
-        std::uint64_t criticalNeedSamples{0};
-        double plannerTravelCostSum{0.0};
-        std::uint64_t plannerTravelCostSamples{0};
-        std::unordered_map<std::string, std::uint64_t> actionTypeCounts;
-        std::unordered_map<std::uint32_t, std::uint64_t> plannerTargetCounts;
-        std::uint64_t stockoutStepsAny{0};
-        std::uint64_t stockoutStepsSources{0};
-        std::uint64_t stockoutStepsWorkshops{0};
-        std::uint64_t stepsWithAnyConsumption{0};
-        std::uint64_t stepsWithAnyRegen{0};
+	    struct WorldlineWindowAgg {
+	        std::uint64_t steps{0};
+	        std::uint64_t needSamples{0};
+	        std::uint64_t criticalNeedSamples{0};
+	        double plannerTravelCostSum{0.0};
+	        std::uint64_t plannerTravelCostSamples{0};
+	        std::unordered_map<std::string, std::uint64_t> actionTypeCounts;
+	        std::unordered_map<std::uint32_t, std::uint64_t> plannerTargetCounts;
+	        std::uint64_t socializeEvents{0};
+	        std::unordered_map<std::uint32_t, std::uint64_t> socializePartnerCounts;
+	        std::uint64_t stockoutStepsAny{0};
+	        std::uint64_t stockoutStepsSources{0};
+	        std::uint64_t stockoutStepsWorkshops{0};
+	        std::uint64_t stepsWithAnyConsumption{0};
+	        std::uint64_t stepsWithAnyRegen{0};
         std::uint64_t stepsWithAnyDecay{0};
         std::uint64_t productionAttempts{0};
         std::uint64_t productionSucceeded{0};
@@ -785,19 +789,21 @@ struct ResourceEconomy {
         std::uint64_t resourceFailed{0};
         std::unordered_map<std::string, std::uint64_t> resourceFailureReasons;
 
-        void clear() {
-            steps = 0;
-            needSamples = 0;
-            criticalNeedSamples = 0;
-            plannerTravelCostSum = 0.0;
-            plannerTravelCostSamples = 0;
-            actionTypeCounts.clear();
-            plannerTargetCounts.clear();
-            stockoutStepsAny = 0;
-            stockoutStepsSources = 0;
-            stockoutStepsWorkshops = 0;
-            stepsWithAnyConsumption = 0;
-            stepsWithAnyRegen = 0;
+	        void clear() {
+	            steps = 0;
+	            needSamples = 0;
+	            criticalNeedSamples = 0;
+	            plannerTravelCostSum = 0.0;
+	            plannerTravelCostSamples = 0;
+	            actionTypeCounts.clear();
+	            plannerTargetCounts.clear();
+	            socializeEvents = 0;
+	            socializePartnerCounts.clear();
+	            stockoutStepsAny = 0;
+	            stockoutStepsSources = 0;
+	            stockoutStepsWorkshops = 0;
+	            stepsWithAnyConsumption = 0;
+	            stepsWithAnyRegen = 0;
             stepsWithAnyDecay = 0;
             productionAttempts = 0;
             productionSucceeded = 0;
@@ -810,34 +816,40 @@ struct ResourceEconomy {
         }
     };
 
-    auto buildWorldlineCountsJson = [](const WorldlineWindowAgg& agg) {
-        json actionCountsJson = json::object();
-        for (const auto& [k, v] : agg.actionTypeCounts) {
-            actionCountsJson[k] = v;
-        }
+	    auto buildWorldlineCountsJson = [](const WorldlineWindowAgg& agg) {
+	        json actionCountsJson = json::object();
+	        for (const auto& [k, v] : agg.actionTypeCounts) {
+	            actionCountsJson[k] = v;
+	        }
 
-        json plannerCountsJson = json::object();
-        for (const auto& [k, v] : agg.plannerTargetCounts) {
-            plannerCountsJson[std::to_string(k)] = v;
-        }
+	        json plannerCountsJson = json::object();
+	        for (const auto& [k, v] : agg.plannerTargetCounts) {
+	            plannerCountsJson[std::to_string(k)] = v;
+	        }
 
-        json resourceFailureReasonsJson = json::object();
-        for (const auto& [k, v] : agg.resourceFailureReasons) {
-            resourceFailureReasonsJson[k] = v;
-        }
+	        json socialJson = json::object();
+	        socialJson["events"] = agg.socializeEvents;
+	        socialJson["uniquePartners"] = agg.socializePartnerCounts.size();
+	        socialJson["partnerEntropyBits"] = entropyBitsFromCounts(agg.socializePartnerCounts);
+
+	        json resourceFailureReasonsJson = json::object();
+	        for (const auto& [k, v] : agg.resourceFailureReasons) {
+	            resourceFailureReasonsJson[k] = v;
+	        }
 
         json productionFailureReasonsJson = json::object();
         for (const auto& [k, v] : agg.productionFailureReasons) {
             productionFailureReasonsJson[k] = v;
         }
 
-        return json{
-            {"actionTypes", std::move(actionCountsJson)},
-            {"plannerTargets", std::move(plannerCountsJson)},
-            {"resourceFailureReasons", std::move(resourceFailureReasonsJson)},
-            {"productionFailureReasons", std::move(productionFailureReasonsJson)},
-        };
-    };
+	        return json{
+	            {"actionTypes", std::move(actionCountsJson)},
+	            {"plannerTargets", std::move(plannerCountsJson)},
+	            {"social", std::move(socialJson)},
+	            {"resourceFailureReasons", std::move(resourceFailureReasonsJson)},
+	            {"productionFailureReasons", std::move(productionFailureReasonsJson)},
+	        };
+	    };
 
     auto buildWorldlineMetricsJson = [&](const WorldlineWindowAgg& agg) {
         const double stepCount = static_cast<double>(std::max<std::uint64_t>(1, agg.steps));
@@ -907,24 +919,33 @@ struct ResourceEconomy {
     std::uint64_t worldlineWindowStartStep = 0;
     std::uint64_t worldlineStep = 0;
 
-    auto ingestWorldlineWindow = [&](const genesis::telemetry::TickTelemetry& telemetry) {
-        windowAgg.steps++;
-        windowAgg.needSamples += telemetry.needs.size();
-        for (const auto& need : telemetry.needs) {
+	    auto ingestWorldlineWindow = [&](const genesis::telemetry::TickTelemetry& telemetry) {
+	        windowAgg.steps++;
+	        windowAgg.needSamples += telemetry.needs.size();
+	        for (const auto& need : telemetry.needs) {
             if (need.critical) {
                 windowAgg.criticalNeedSamples++;
             }
         }
-        for (const auto& action : telemetry.actions) {
-            windowAgg.actionTypeCounts[action.currentAction]++;
-        }
-        for (const auto& decision : telemetry.plannerDecisions) {
-            windowAgg.plannerTargetCounts[decision.target]++;
-            if (std::isfinite(decision.travelCost)) {
-                windowAgg.plannerTravelCostSum += static_cast<double>(decision.travelCost);
-                windowAgg.plannerTravelCostSamples++;
-            }
-        }
+	        for (const auto& action : telemetry.actions) {
+	            windowAgg.actionTypeCounts[action.currentAction]++;
+	            if (action.currentAction == "SocializeWithAgent") {
+	                windowAgg.socializeEvents++;
+	                if (action.targetEntityId != 0U) {
+	                    windowAgg.socializePartnerCounts[action.targetEntityId]++;
+	                }
+	            }
+	        }
+	        for (const auto& decision : telemetry.plannerDecisions) {
+	            if (decision.target == 0U || genesis::agents::isAgentPlannerTarget(static_cast<std::uint32_t>(decision.target))) {
+	                continue;
+	            }
+	            windowAgg.plannerTargetCounts[decision.target]++;
+	            if (std::isfinite(decision.travelCost)) {
+	                windowAgg.plannerTravelCostSum += static_cast<double>(decision.travelCost);
+	                windowAgg.plannerTravelCostSamples++;
+	            }
+	        }
 
         bool anyStockout = false;
         bool anyStockoutSource = false;
@@ -1027,16 +1048,19 @@ struct ResourceEconomy {
                 takeTicksByAgent[action.entityId]++;
             }
         }
-        for (const auto& decision : telemetry.plannerDecisions) {
-            plannerTargetCounts[decision.target]++;
-            if (decision.target != 0) {
-                const auto prev = lastPlannerTargetByAgent.contains(decision.entityId) ? lastPlannerTargetByAgent[decision.entityId] : 0U;
-                if (prev != 0 && prev != decision.target) {
-                    plannerTargetSwitchesTotal++;
-                }
-                lastPlannerTargetByAgent[decision.entityId] = decision.target;
-            }
-        }
+	        for (const auto& decision : telemetry.plannerDecisions) {
+	            if (decision.target == 0U || genesis::agents::isAgentPlannerTarget(static_cast<std::uint32_t>(decision.target))) {
+	                continue;
+	            }
+	            plannerTargetCounts[decision.target]++;
+	            if (decision.target != 0U) {
+	                const auto prev = lastPlannerTargetByAgent.contains(decision.entityId) ? lastPlannerTargetByAgent[decision.entityId] : 0U;
+	                if (prev != 0 && prev != decision.target) {
+	                    plannerTargetSwitchesTotal++;
+	                }
+	                lastPlannerTargetByAgent[decision.entityId] = decision.target;
+	            }
+	        }
 
         bool anyStockout = false;
         bool anyStockoutSource = false;

src/engine/runtime/SnapshotDiff.cpp

@@ -92,10 +92,11 @@ std::string actionKey(const telemetry::ActionSnapshot& snapshot) {
     return std::to_string(snapshot.entityId);
 }
 
-bool actionEqual(const telemetry::ActionSnapshot& lhs, const telemetry::ActionSnapshot& rhs) {
-    return lhs.entityId == rhs.entityId && lhs.currentAction == rhs.currentAction && lhs.queueLength == rhs.queueLength && lhs.target == rhs.target &&
-           lhs.speed == rhs.speed && lhs.resource == rhs.resource && lhs.amount == rhs.amount && lhs.reliefPerUnit == rhs.reliefPerUnit;
-}
+bool actionEqual(const telemetry::ActionSnapshot& lhs, const telemetry::ActionSnapshot& rhs) {
+    return lhs.entityId == rhs.entityId && lhs.currentAction == rhs.currentAction && lhs.queueLength == rhs.queueLength && lhs.target == rhs.target &&
+           lhs.targetEntityId == rhs.targetEntityId && lhs.speed == rhs.speed && lhs.resource == rhs.resource && lhs.amount == rhs.amount &&
+           lhs.reliefPerUnit == rhs.reliefPerUnit;
+}
 
 std::string agentKey(const telemetry::AgentSnapshot& snapshot) {
     return std::to_string(snapshot.entityId);

src/simulation/SimulationContext.cpp

@@ -347,6 +347,7 @@ void SimulationContext::collectActionSnapshots(std::vector<telemetry::ActionSnap
         if (!queue.tasks.empty()) {
             const auto& task = queue.tasks.front();
             snap.target = task.interaction;
+            snap.targetEntityId = task.targetEntityId;
             snap.speed = task.speed;
             snap.resource = task.resource;
             snap.amount = task.amount;