agents: experience-based buffering; pause work for critical needs

Author: 129s

docs/architecture/agents/agent-implementation-status.md

@@ -13,8 +13,9 @@
 | Need 数值模型（decay/threshold） | `docs/architecture/proposals/agents/agent-personality-big5.md`（部分） | `include/genesis/agents/Needs.hpp` | Spec | 当前以 Need 本身作为“属性”，无独立 Attributes 层。 |
 | NeedSystem 推进 | 同上 | `src/agents/NeedSystem.cpp` | Spec | 仅做线性 decay；无 baseCurve/jitter。 |
 | 选点/决策（Planner/Selector） | 同上（理念） | `src/agents/NeedSatisfier.cpp` | Spec | 规则打分 + Big5 权重缩放 + 确定性 jitter（用于打破稳态收敛）。 |
+| 经验/学习（最小闭环） | `docs/architecture/proposals/agents/agent-personality-big5.md`（理念） | `include/genesis/agents/Experience.hpp`、`src/agents/ActionSystem.cpp`、`src/agents/NeedSatisfier.cpp` | Spec | 从“抢占打断/关键补给失败”学习，提高生存 Need 的缓冲倾向并随时间遗忘；同时允许“先补给再继续作业”。 |
 | 决策可观测性（PlannerDecision） | 同上（链路） | `include/genesis/agents/Planner.hpp` | Spec | 仅用于 Telemetry/拥挤惩罚计数。 |
-| 行动队列（Move/Consume/Take/Produce） | 同上（链路） | `include/genesis/agents/ActionSystem.hpp`、`src/agents/ActionSystem.cpp` | Spec | 具备“生产作业时间+临界需求抢占中断”。 |
+| 行动队列（Move/Consume/Take/Produce） | 同上（链路） | `include/genesis/agents/ActionSystem.hpp`、`src/agents/ActionSystem.cpp` | Spec | 具备“生产作业时间+临界需求抢占（优先补给，必要时才中断）”。 |
 | 自动补链（缺货→上游生产） | 文档未明确 | `src/agents/ProductionPlanner.cpp` | Spec | 当前是工程式 recovery 规划器，不代表“角色策略”。 |
 | Movement（直线/跨图 Portal） | 文档提到 | `include/genesis/agents/Movement2D.hpp`、`src/simulation/Movement2DSystem.cpp` | Spec | Tile 级路径未实现。 |
 | 工坊配方（meta.workshop） | 文档提到 | worldgen→Runtime 写 meta；执行见 `src/agents/ActionSystem.cpp` | Spec | recipe 选择目前发生在 recovery/执行层。 |

docs/architecture/agents/agent-model-v0.md

@@ -11,6 +11,9 @@
 - **人格（Big5）**
   - `genesis::agents::AgentPersonalityBig5`：OCEAN（0~1）人格向量（`include/genesis/agents/Personality.hpp`）。
   - 生成方式：Agent 创建时若未显式指定，则按 `entityId + mapId` 的确定性 RNG 生成（可复现、无外部脚本介入）。
+- **经验（最小学习）**
+  - `genesis::agents::components::AgentExperience`：按 Need 维度记录“缓冲偏好”（`bufferMultiplier`），并随时间遗忘（`include/genesis/agents/Experience.hpp`）。
+  - 目前只学习一件事：当工坊作业被“临界需求抢占打断”或关键补给出现反复失败时，会提高对应 Need 的提前准备与一次性补给量（通过 NeedSatisfier 的 prepareMargin / unitsPerRequest 缩放体现）。
 - **位置/移动**
   - `genesis::agents::components::AgentLocation2D`：Agent 当前所在 `mapId` 与 2D 坐标（`include/genesis/agents/Movement2D.hpp`）。
   - `genesis::agents::components::MovementIntent2D`：当前运动目标与速度（`include/genesis/agents/Movement2D.hpp`）。

include/genesis/agents/Experience.hpp

@@ -0,0 +1,23 @@
+#pragma once
+
+#include <array>
+#include <cstddef>
+
+#include "genesis/agents/Needs.hpp"
+
+namespace genesis::agents::components {
+
+struct AgentExperience {
+    // Multiplicative safety buffer per need. 1.0 means neutral.
+    std::array<float, static_cast<std::size_t>(genesis::agents::NeedType::Count)> bufferMultiplier{};
+
+    // Linear decay rate toward 1.0 per simulated second.
+    float forgetPerSecond{0.15f};
+
+    AgentExperience() {
+        bufferMultiplier.fill(1.0f);
+    }
+};
+
+} // namespace genesis::agents::components
+

src/agents/ActionSystem.cpp

@@ -13,6 +13,7 @@
 #include <nlohmann/json.hpp>
 
 #include "genesis/agents/CarriedResources.hpp"
+#include "genesis/agents/Experience.hpp"
 #include "genesis/agents/Needs.hpp"
 #include "genesis/agents/ProductionPlanner.hpp"
 #include "genesis/world/MapPathfinding.hpp"
@@ -37,13 +38,61 @@ constexpr const char* kReasonPlanningFailed = "PlanningFailed";
 constexpr const char* kReasonUnreachable = "Unreachable";
 constexpr const char* kReasonPreemptedCriticalNeed = "PreemptedCriticalNeed";
 
+constexpr float kExperienceMinMultiplier = 1.0f;
+constexpr float kExperienceMaxMultiplier = 3.0f;
+constexpr float kExperienceBumpPreempt = 0.18f;
+constexpr float kExperienceBumpStockoutVital = 0.06f;
+
 [[nodiscard]] std::string preemptedWithNeed(const char* needName) {
     std::string out(kReasonPreemptedCriticalNeed);
     out.push_back(':');
     out.append(needName);
     return out;
 }
 
+[[nodiscard]] bool isVitalNeed(NeedType need) noexcept {
+    switch (need) {
+    case NeedType::Hunger:
+    case NeedType::Thirst:
+        return true;
+    default:
+        return false;
+    }
+}
+
+void decayExperience(entt::registry& registry, float deltaSeconds) {
+    if (!(deltaSeconds > 0.0f)) {
+        return;
+    }
+    auto view = registry.view<components::AgentExperience>();
+    for (auto entity : view) {
+        auto& exp = view.get<components::AgentExperience>(entity);
+        const float k = std::clamp(exp.forgetPerSecond * deltaSeconds, 0.0f, 1.0f);
+        if (k <= 0.0f) {
+            continue;
+        }
+        for (auto& m : exp.bufferMultiplier) {
+            const float delta = m - 1.0f;
+            m = 1.0f + delta * (1.0f - k);
+            m = std::clamp(m, kExperienceMinMultiplier, kExperienceMaxMultiplier);
+        }
+    }
+}
+
+void bumpNeedBuffer(entt::entity entity, NeedType need, float bump, entt::registry& registry) {
+    if (!(bump > 0.0f)) {
+        return;
+    }
+    auto& exp = registry.get_or_emplace<components::AgentExperience>(entity);
+    const auto idx = needIndex(need);
+    if (idx >= exp.bufferMultiplier.size()) {
+        return;
+    }
+    float m = std::clamp(exp.bufferMultiplier[idx], kExperienceMinMultiplier, kExperienceMaxMultiplier);
+    m *= (1.0f + bump);
+    exp.bufferMultiplier[idx] = std::clamp(m, kExperienceMinMultiplier, kExperienceMaxMultiplier);
+}
+
 [[nodiscard]] const char* needTypeName(NeedType need) {
     switch (need) {
     case NeedType::Hunger:
@@ -283,16 +332,115 @@ void ActionExecutor::requestConsume(entt::entity entity,
     queue.tasks.push_back(consume);
 }
 
-void ActionExecutor::update(entt::registry& registry, float /*deltaSeconds*/) {
+void ActionExecutor::update(entt::registry& registry, float deltaSeconds) {
     m_workshopAttempts.clear();
     m_resourceAttempts.clear();
 
+    decayExperience(registry, deltaSeconds);
+
     auto view = registry.view<ActionQueue, components::AgentLocation2D>();
 
     for (auto entity : view) {
         auto& queue = view.get<ActionQueue>(entity);
         auto& location = view.get<components::AgentLocation2D>(entity);
 
+        const auto findBestInteractionFor = [&](genesis::world::ResourceType type) -> genesis::world::InteractionId {
+            genesis::world::InteractionId best = 0;
+            float bestCost = std::numeric_limits<float>::infinity();
+
+            m_resources.forEachSpawn(registry, [&](const auto& spawn, const auto& inventory) {
+                if (spawn.type != type) {
+                    return;
+                }
+
+                const auto inter = m_db.findInteraction(spawn.interaction);
+                if (!inter) {
+                    return;
+                }
+
+                float cost = 0.0f;
+                if (inter->mapId == location.mapId) {
+                    const auto coord = inter->worldCoord();
+                    const float dx = static_cast<float>(coord.first) - location.x;
+                    const float dy = static_cast<float>(coord.second) - location.y;
+                    cost = dx * dx + dy * dy;
+                } else {
+                    const auto path = genesis::world::shortestMapPath(m_db, location.mapId, inter->mapId);
+                    if (!path) {
+                        return;
+                    }
+                    cost = 500.0f + static_cast<float>(path->totalCost);
+                }
+
+                // Prefer non-empty targets when possible, but still allow empty workshops.
+                if (inventory.current == 0U) {
+                    cost += 250.0f;
+                }
+
+                if (cost < bestCost) {
+                    bestCost = cost;
+                    best = spawn.interaction;
+                }
+            });
+
+            return best;
+        };
+
+        const auto ensureCriticalConsume = [&](NeedType criticalNeed, genesis::world::ResourceType criticalResource) -> bool {
+            for (const auto& t : queue.tasks) {
+                if (t.type == ActionType::ConsumeResource && t.need == criticalNeed) {
+                    return true;
+                }
+            }
+
+            const auto target = findBestInteractionFor(criticalResource);
+            if (target == 0) {
+                return false;
+            }
+
+            float buffer = 1.0f;
+            if (const auto* exp = registry.try_get<components::AgentExperience>(entity)) {
+                const auto idx = needIndex(criticalNeed);
+                if (idx < exp->bufferMultiplier.size()) {
+                    buffer = std::clamp(exp->bufferMultiplier[idx], kExperienceMinMultiplier, kExperienceMaxMultiplier);
+                }
+            }
+
+            std::uint32_t baseUnits = 1U;
+            float reliefPerUnit = 12.0f;
+            switch (criticalNeed) {
+            case NeedType::Hunger:
+                baseUnits = 2U;
+                reliefPerUnit = 12.0f;
+                break;
+            case NeedType::Thirst:
+                baseUnits = 2U;
+                reliefPerUnit = 12.0f;
+                break;
+            case NeedType::Social:
+                baseUnits = 1U;
+                reliefPerUnit = 20.0f;
+                break;
+            default:
+                baseUnits = 1U;
+                reliefPerUnit = 12.0f;
+                break;
+            }
+
+            const auto scaled = static_cast<std::uint32_t>(std::lround(static_cast<double>(baseUnits) * static_cast<double>(buffer)));
+
+            ActionTask consume{};
+            consume.type = ActionType::ConsumeResource;
+            consume.interaction = target;
+            consume.need = criticalNeed;
+            consume.resource = criticalResource;
+            consume.amount = std::max<std::uint32_t>(1U, scaled);
+            consume.retries = 0;
+            consume.reliefPerUnit = reliefPerUnit;
+            queue.tasks.emplace(queue.tasks.begin(), consume);
+            return true;
+        };
+
         const auto abandonAllActions = [&]() {
             queue.tasks.clear();
             if (registry.any_of<components::MovementIntent2D>(entity)) {
@@ -327,6 +475,8 @@ void ActionExecutor::update(entt::registry& registry, float /*deltaSeconds*/) {
             releaseWorkshopSlot(job.interaction, entity);
             registry.remove<components::WorkshopJob>(entity);
             abandonAllActions();
+
+            bumpNeedBuffer(entity, criticalNeed, kExperienceBumpPreempt, registry);
         };
 
         if (auto* needs = registry.try_get<NeedComponent>(entity)) {
@@ -335,12 +485,20 @@ void ActionExecutor::update(entt::registry& registry, float /*deltaSeconds*/) {
 
                 if (auto* job = registry.try_get<components::WorkshopJob>(entity)) {
                     if (job->outputType != criticalResource) {
-                        abortWorkshopJob(*job, criticalNeed);
-                        continue;
+                        // Take a break instead of throwing away progress: eat/drink first, then resume work.
+                        bumpNeedBuffer(entity, criticalNeed, kExperienceBumpPreempt, registry);
+                        releaseWorkshopSlot(job->interaction, entity);
+                        if (!ensureCriticalConsume(criticalNeed, criticalResource)) {
+                            abortWorkshopJob(*job, criticalNeed);
+                            continue;
+                        }
                     }
                 } else if (!queue.tasks.empty() && queue.tasks.front().type == ActionType::ProduceResource) {
                     if (queue.tasks.front().resource != criticalResource) {
-                        abandonAllActions();
+                        bumpNeedBuffer(entity, criticalNeed, kExperienceBumpPreempt, registry);
+                        if (!ensureCriticalConsume(criticalNeed, criticalResource)) {
+                            abandonAllActions();
+                        }
                     }
                 }
             }
@@ -633,11 +791,19 @@ void ActionExecutor::processConsume(entt::entity entity,
             m_resourceAttempts.push_back(std::move(attempt));
             queue.tasks.pop_front();
             queue.tasks.insert(queue.tasks.begin(), plan->begin(), plan->end());
+
+            if (isVitalNeed(task.need)) {
+                bumpNeedBuffer(entity, task.need, kExperienceBumpStockoutVital, registry);
+            }
             return;
         }
 
         attempt.failureReason = kReasonPlanningFailed;
         m_resourceAttempts.push_back(std::move(attempt));
+
+        if (isVitalNeed(task.need)) {
+            bumpNeedBuffer(entity, task.need, kExperienceBumpStockoutVital * 0.5f, registry);
+        }
         queue.tasks.pop_front();
         return;
     }
@@ -799,6 +965,10 @@ bool ActionExecutor::processProduce(entt::entity entity,
             return true;
         }
 
+        if (!acquireWorkshopSlot(job->interaction, entity, slots)) {
+            return false;
+        }
+
         if (job->workRemainingTicks > 0U) {
             job->workRemainingTicks--;
         }