tmcarmichael/compass
GitHub: tmcarmichael/compass
一个纯 Python 实现的零依赖智能体控制架构，通过分层决策栈和贝叶斯学习在 3D MMORPG 中实现感知、规划、学习与自主行动。
Stars: 1 | Forks: 0
# Compass
[](https://github.com/tmcarmichael/compass/actions/workflows/ci.yml)
一种用于实时 3D 世界中智能行为的分层决策架构。
## 架构
系统被组织为一个四阶段的控制管道：感知、大脑、例程和运动，辅以环境解析器、导航和可观察性作为支撑层。它在 Python 3.14 标准库之外零运行时依赖的情况下，以单个 10 Hz 循环运行。其核心由跨越四个模块的优先级规则、具有进入/tick/退出生命周期的状态机例程、可互换的战斗策略、在 1 单位高度图上结合 DDA 视线的 JPS/A* 寻路，以及带有学习成本函数的 GOAP 规划器组成。
数据严格按照单向顺序流经四个阶段：
```
---
config:
look: neo
theme: neutral
flowchart:
nodeSpacing: 60
rankSpacing: 40
---
flowchart TB
%% Forward-only data flow. Solid edges = pipeline data products.
%% Dashed edges = support dependencies (lookups, logging), not pipeline stages.
subgraph PIPELINE["Main Pipeline · 10 Hz forward-only data flow"]
direction LR
P["perception/
GameState · SpawnData
immutable snapshot, each tick"] subgraph BRAIN["brain/"] direction TB PR["Priority Rules
safety envelope · 4 modules"] US["Utility Scoring
phase-gated selection"] GP["GOAP Planner
learned cost functions"] PR --> US --> GP end R["routines/
state-machine behaviors
enter · tick · exit"] M["motor/
action interface"] P -->|"frozen snapshots"| BRAIN BRAIN -->|"selected routine + params"| R R -->|"motor commands"| M end EQ["eq/
terrain · spells · zones"] NAV["nav/
JPS/A* · DDA LOS · heightmaps · waypoints"] UTIL["util/
4-tier logging · forensics"] %% Invisible edges to force vertical stacking EQ --- NAV --- UTIL EQ -.-> BRAIN EQ -.-> R NAV -.-> R UTIL -.-> BRAIN UTIL -.-> R classDef pipeline fill:#EAF4FB,stroke:#2E5E7E,stroke-width:2px,color:#1F3A4A classDef brain fill:#C8DFF0,stroke:#2E5E7E,stroke-width:2px,color:#1F3A4A classDef support fill:#FAF8F5,stroke:#C07A45,stroke-width:1px,color:#1F3A4A class P,R,M pipeline class PR,US,GP brain class EQ,NAV,UTIL support %% 0–1: PR→US, US→GP | 2–3: invisible stacking | 4–6: P→BRAIN, BRAIN→R, R→M | 7–11: support edges linkStyle 0,1 stroke:#2E5E7E,stroke-width:1.5px linkStyle 2,3 stroke:none linkStyle 4,5,6 stroke:#2E5E7E,stroke-width:2px linkStyle 7,8,9,10,11 stroke:#B66A2C,stroke-width:1.5px ``` 没有模块会向上导入。依赖关系图是一个 DAG（有向无环图），每一层都可以独立理解。 **大脑线程**以 10 Hz 运行：读取状态，评估决策栈，tick 活跃例程，发出运动指令。单个周期在远低于 100ms 的时间内完成（p99：在无头模拟中为 0.5ms）。一个辅助线程处理可观察性输出和运行时控制信号。它们之间的线程安全通过不可变的感知快照来保证：每次 tick 生成的冻结 `GameState` 数据类，在创建后从不修改。无锁，无竞态。 ### 感知 感知层通过只读模式的 `ReadProcessMemory` 遍历结构体指针链，读取实时的环境状态，且不进行代码注入。每次 tick 都会产生不可变的快照：一个涵盖玩家属性、位置、目标和施法状态的 `GameState`，以及每个可见实体的 `SpawnData`。感知与大脑之间的接口就是这个快照契约；其上方的所有内容都是环境无关的。 ### 决策栈 大脑运行一个三层决策栈。每一层增加能力；下层提供保证。完整的决策流程图请参见 [`docs/architecture.md`](docs/architecture.md#decision-architecture)。 **优先级规则**是安全底线。四个模块（生存、战斗、维护、导航）中的规则在每个 tick 按优先级顺序进行评估。紧急规则（逃跑、假死、闪避）拥有高于一切的硬性优先级：它们可以中断任何锁定的例程，使任何活跃的计划失效。这种保证是结构性的，而非学习得来的。智能体无法通过学习来无视致命威胁。 **效用评分**在安全底线内运作。非紧急规则生成反映“当前此行动有多大价值”的浮点分数。五个选择阶段可在运行时配置：阶段 0 忽略分数（保守基线），阶段 1 记录分歧但不改变行为（观察模式），阶段 2 在优先级层级内使用分数，阶段 3 使用加权的跨层级比较，阶段 4 使用带有加权几何平均数的基于声明式考量的评分。这种升级路径允许在评分系统影响决策之前对其进行验证。 **GOAP 规划**生成面向明确目标的多步行动序列：生存、获取经验值、管理资源。规划器在目标状态空间上使用 A* 算法，结合每个行动的学习成本函数，在 50ms 的预算内生成 3-8 步的计划。候选计划通过蒙特卡洛鲁棒性门：从学习到的后验分布中随机采样行动效果，在噪声结果下失败的计划将被拒绝。其与优先级系统的关系是明确的：GOAP 负责提议，优先级负责裁决。紧急规则在每个 tick 首先进行评估，如果有触发则使活跃计划失效。完整的规划管道请参见 [`docs/architecture.md`](docs/architecture.md#goap-planner) 和 [`docs/samples/goap-planner.md`](docs/samples/goap-planner.md)。 ### 例程 行为以具有 `enter` / `tick` / `exit` 生命周期的状态机实现。例程使用可中断的休眠来实现实时运动计时（施法条、移动延迟）；所有休眠每 100ms 轮询一次具备逃跑感知的中断谓词，因此紧急规则可以在一个轮询间隔内突破。一个 5 秒的硬性终止阈值会强制退出任何超过其 tick 预算的例程。战斗施法管道通常运行 2-3 秒，因此该阈值设定在该范围之上。 锁定语义（`locked = True`）保护多步序列免受过早中断。飞行中的拉怪、死亡恢复序列、多步交战：一旦锁定，只有紧急规则可以覆盖。如果没有这种机制，低优先级规则会在多步行动刚好变得相关的那一刻，打断进行到一半的行动。 ### 导航 区域地形从环境自身的 3D 几何结构解析为 1 单位分辨率的高度图，具有可行走、水、熔岩、悬崖和障碍物等地表类型。JPS（跳点搜索）是主要的寻路算法，通过修剪网格上的对称路径以提高速度，当 JPS 在密集地形中耗尽其节点预算时，A* 作为后备方案。两者均使用八向距离启发式、位域加速的可行性检查、Z 轴梯度惩罚和动态避让区成本膨胀。预构建的缓存文件在不同会话间持久保存。 视线使用 DDA（Amanatides-Woo）网格遍历，恰好访问射线穿过的每个单元格一次，无采样间隙。每个单元格检查障碍物标志和插值射线 Z 轴。移动通过预测性障碍物扫描验证前方路径，并在遇到危险之前计算垂直绕行路线，而不是仅仅依赖于卡死恢复。 对于网格寻路无法解决垂直歧义的区域（桥梁、隧道、螺旋坡道、重叠几何结构），预先录制的航点图提供了已知安全的路线。带有 BFS 的区域图可计算用于长途旅行的跨区域路径。 ## 学习型自适应 智能体从自身经验中学习。所有四个学习系统都在同一个信号上训练：遭遇结果。 **遭遇历史。** 每次战斗退出记录 20 个字段：持续时间、法力消耗、生命值损失、使用的策略、宠物死亡、遇到的额外 NPC。针对每种实体类型维护贝叶斯共轭后验（连续值为正态分布，比率为 Beta 分布），并在每次遭遇时增量更新。目标评分路径通过汤普森采样从这些后验中提取，自然地平衡了对不确定目标的探索与对已知优质目标的利用。随着数据的积累，后验逐渐收紧，选择趋于稳定，而无需硬编码的探索计划。数据在不同会话间持久保存。跟踪每次遭遇的遗憾值（所选目标的适应度与最佳可用目标之比）；亚线性的累积遗憾值增长验证了学习的收敛性。 **空间记忆。** 基于 50 单位网格的热力图通过 4 小时的指数衰减跟踪战败、目击和危险事件。热力图将目标评分偏向最多 50%，将智能体引导至高效区域。GOAP 规划器使用逐单元格的泊松刷新预测（源自战败时间戳）来定位预测的刷新点，而不是随机游荡。 **会话记分卡。** 每 30 分钟，一份 7 维记分卡对战败率、生存、拉怪成功率、运行时间、寻路、法力效率和目标选择进行评级。三个参数立即自动调整：游荡半径、社交引怪限制和法力保守水平。 **评分权重调优。** 15 因子的目标评分函数通过有限差分投影梯度下降调整其权重。每个梯度步骤独立扰动权重，通过中心数值导数测量对遭遇适应度的影响，并将更新投影回有界区域（默认值的 ±20%）。自适应的逐权重学习率检测震荡、收敛和停滞。每个区域的收敛大约需要约 100 次战败。 GOAP 规划器的成本函数直接提取自这些学习到的数据。休息成本来自观察到的休息持续时间。遭遇成本来自每个实体的历史记录。随着成本模型收敛，计划质量也随之提高。 ``` --- config: look: neo theme: neutral flowchart: nodeSpacing: 60 rankSpacing: 40 --- flowchart TD %% One encounter signal drives four learning systems at distinct cadences. %% Orange = external input signals. Blue = internal learners. Darker blue = sink. CO(["Combat Outcomes
duration · mana spent · HP lost
survival · pet death · extra npcs encountered"]) PE(["Perception Events
entity sightings · danger events
spawn tracking"]) SP(["Session Performance Data
defeat rate · uptime · pull success
pathing quality · mana efficiency"]) EH["Encounter History
strategy fitness · danger score
cadence: each combat exit"] %% SM receives from both CO and PE. Sightings are not combat-exit-driven. SM["Spatial Memory
50-unit heat map · 4-hour decay
cadence: continuous"] WL["Weight Tuner
15-factor gradient descent · ±20% bounded
cadence: per defeat · ~100 to converge"] SS["Session Scorecard
7-dimension performance grading
roam radius · add limit · mana conservation level
cadence: every 30 minutes"] %% Collapsed consumer view. Actual consumers: GOAP costs, utility weights, %% target scoring, rule thresholds (via AgentContext), strategy selection. DS["Decision System / AgentContext
GOAP cost model · target scoring
utility weights · rule thresholds · spawn positioning"] CO --> EH CO -->|"defeat location · timestamp"| SM CO --> WL PE -->|"sighting records · danger events"| SM SP --> SS EH -->|"encounter cost estimates
strategy fitness override"| DS SM -->|"target score bias
spawn positioning"| DS WL -->|"tuned scoring weights"| DS SS -->|"auto-tuned thresholds
via AgentContext"| DS classDef input fill:#FDF5EC,stroke:#C07A45,stroke-width:1.5px,color:#1F3A4A classDef learner fill:#EAF4FB,stroke:#2E5E7E,stroke-width:2px,color:#1F3A4A classDef sink fill:#C8DFF0,stroke:#2E5E7E,stroke-width:2.5px,color:#1F3A4A class CO,PE,SP input class EH,SM,WL,SS learner class DS sink %% 0–4: CO→EH, CO→SM, CO→WL, PE→SM, SP→SS | 5–8: learners→DS linkStyle 0,1,2,3,4 stroke:#B66A2C,stroke-width:1.5px linkStyle 5,6,7,8 stroke:#2E5E7E,stroke-width:2px ``` ## 可观察性 每个决策分支都记录其推理过程。无声的 `return False` 被视为一个缺陷；它使得相应的行为在会话后分析中不可见。热路径日志记录（每个 tick 对每个实体运行的评分函数）进行了速率限制，以避免数据量问题。 四个层级提供渐进的详细信息： | 层级 | 级别 | 数据量 | 用途 | | ---- | ------- | ---------------- | ------------------------------------------------------ | | T1 | EVENT | ~50 行/小时 | 状态变化：战败、死亡、区域转换 | | T2 | INFO | ~2,000 行/小时 | 操作流程：例程进入/退出、目标选择 | | T3 | VERBOSE | ~5,000 行/小时 | 决策分支：规则跳过、评分明细 | | T4 | DEBUG | ~50,000 行/小时 | 原始数据：内存读取、运动输出、tick 计时 | 每次会话生成 6 个输出文件：4 个日志文件（每个层级阈值一个）、一个结构化的 JSONL 事件流和一个决策回执日志。一个 300 tick 的取证环形缓冲区持续捕获大脑状态，并在死亡时刷新到磁盘：为每次故障提供 30 秒的事件前遥测数据。 ### 会话样本 [docs/samples/](docs/samples/) 中的所有样本都是来自真实会话的实际输出，而非手工编写的示例： | 样本 | 展示内容 | | --- | --- | | [会话层级](docs/samples/session-tiers.md) | 贯穿所有 4 个日志层级的单个会话 | | [决策追踪](docs/samples/decision-trace.md) | 经历 WANDER → ACQUIRE → PULL → IN_COMBAT 转换的 18 条回执 | | [GOAP 计划](docs/samples/goap-planner.md) | 目标评估、A* 搜索、蒙特卡洛鲁棒性门控、成本自我纠正 | | [取证缓冲区](docs/samples/forensics-ring-buffer.md) | 骷髅仇恨打断记忆过程后的 300 tick 环形缓冲区转储 | | [学习的遭遇数据](docs/samples/learned-encounter-data.md) | 跨会话改进：评级 B → A，战斗持续时间 29.5s → 15.9s | | [战斗事件](docs/samples/structured-fight-event.md) | 包含所有 20 个字段的结构化 `fight_end` 事件 | | [收敛性](docs/samples/convergence.md) | 10 次会话运行：随着后验收紧，战斗持续时间减少 53% | | [消融结果](docs/samples/ablation-results.md) | 学习与默认值对比：成本误差、危险区分度、权重稳定性 | ## 无头模拟器 模拟器针对合成的感知序列运行完整的决策栈（大脑、规则、GOAP、学习）。无需游戏客户端，无需环境资产，无外部依赖。 ``` just simulate # replay: single camp session just simulate converge --sessions 10 # convergence: learning across sessions just simulate replay --scenario survival_stress # stress: safety envelope under pressure just simulate benchmark --scenario camp_session # benchmark: 10 Hz realtime pacing ``` 三个内置场景测试不同的系统路径：`camp_session`（拉怪/战斗/休息循环、目标评分、遭遇学习）、`survival_stress`（伤害递增、逃跑紧迫性、紧急规则）和 `exploration`（稀疏目标GOAP 规划、空间记忆）。结果包括 tick 计时百分位数、决策栈活动、GOAP 规划统计和学习快照。 收敛模式在不同会话之间保持学习状态。随着遭遇后验收紧和成本函数自我纠正，战斗持续时间随之下降： ``` Session Grade Fights Avg Dur 1 A 8 22.2s 3 A 24 19.4s 5 A 30 16.6s 10 A 30 10.4s 53% improvement ``` 完整的输出和解释请参见 [docs/samples/convergence.md](docs/samples/convergence.md)。 各场景下的 tick 计时： | | p50 | p95 | p99 | 最大值 | |---|---|---|---|---| | camp_session (1 280 ticks) | 0.1 ms | 0.1 ms | 0.5 ms | 0.7 ms | | survival_stress (220 ticks) | 0.1 ms | 0.2 ms | 0.3 ms | 0.3 ms | 测试策略和覆盖率理念请参见 [docs/testing.md](docs/testing.md)。 ## 许可证 基于 [MIT 许可证](LICENSE) 发布。
项目结构
``` src/ core/ Cross-cutting primitives (types, constants, exceptions, features) runtime/ Agent wiring and session lifecycle perception/ Environment state reading (snapshot contract, pointer traversal) brain/ Decision stack: priority rules, utility scoring, GOAP planner brain/state/ Typed sub-state dataclasses (combat, pet, camp, inventory, ...) brain/runner/ 10 Hz tick loop, lifecycle management, level-up handling brain/world/ World model, entity tracking, anomaly detection brain/goap/ GOAP planner, world state, actions, goals, spawn predictor brain/learning/ Encounter history, spatial memory, scorecard, weight gradient brain/scoring/ Target scoring, utility curves, weight learner brain/rules/ Priority rules across 4 modules (survival, combat, maintenance, nav) routines/ State machine behaviors (enter/tick/exit) routines/strategies/ Swappable combat strategy implementations nav/ JPS/A* pathfinding, DDA line-of-sight, waypoint graphs, zone graph nav/terrain/ 1-unit heightmaps from zone geometry, obstacle detection motor/ Action interface (movement, targeting, casting, stance) eq/ Environment data parsers (geometry, spells, zone models) simulator/ Offline scenario runner for testing decisions without live environment util/ Structured logging, event schemas, forensics, invariant checking docs/ Architecture, design decisions, evolution history, retrospective ```GameState · SpawnData
immutable snapshot, each tick"] subgraph BRAIN["brain/"] direction TB PR["Priority Rules
safety envelope · 4 modules"] US["Utility Scoring
phase-gated selection"] GP["GOAP Planner
learned cost functions"] PR --> US --> GP end R["routines/
state-machine behaviors
enter · tick · exit"] M["motor/
action interface"] P -->|"frozen snapshots"| BRAIN BRAIN -->|"selected routine + params"| R R -->|"motor commands"| M end EQ["eq/
terrain · spells · zones"] NAV["nav/
JPS/A* · DDA LOS · heightmaps · waypoints"] UTIL["util/
4-tier logging · forensics"] %% Invisible edges to force vertical stacking EQ --- NAV --- UTIL EQ -.-> BRAIN EQ -.-> R NAV -.-> R UTIL -.-> BRAIN UTIL -.-> R classDef pipeline fill:#EAF4FB,stroke:#2E5E7E,stroke-width:2px,color:#1F3A4A classDef brain fill:#C8DFF0,stroke:#2E5E7E,stroke-width:2px,color:#1F3A4A classDef support fill:#FAF8F5,stroke:#C07A45,stroke-width:1px,color:#1F3A4A class P,R,M pipeline class PR,US,GP brain class EQ,NAV,UTIL support %% 0–1: PR→US, US→GP | 2–3: invisible stacking | 4–6: P→BRAIN, BRAIN→R, R→M | 7–11: support edges linkStyle 0,1 stroke:#2E5E7E,stroke-width:1.5px linkStyle 2,3 stroke:none linkStyle 4,5,6 stroke:#2E5E7E,stroke-width:2px linkStyle 7,8,9,10,11 stroke:#B66A2C,stroke-width:1.5px ``` 没有模块会向上导入。依赖关系图是一个 DAG（有向无环图），每一层都可以独立理解。 **大脑线程**以 10 Hz 运行：读取状态，评估决策栈，tick 活跃例程，发出运动指令。单个周期在远低于 100ms 的时间内完成（p99：在无头模拟中为 0.5ms）。一个辅助线程处理可观察性输出和运行时控制信号。它们之间的线程安全通过不可变的感知快照来保证：每次 tick 生成的冻结 `GameState` 数据类，在创建后从不修改。无锁，无竞态。 ### 感知 感知层通过只读模式的 `ReadProcessMemory` 遍历结构体指针链，读取实时的环境状态，且不进行代码注入。每次 tick 都会产生不可变的快照：一个涵盖玩家属性、位置、目标和施法状态的 `GameState`，以及每个可见实体的 `SpawnData`。感知与大脑之间的接口就是这个快照契约；其上方的所有内容都是环境无关的。 ### 决策栈 大脑运行一个三层决策栈。每一层增加能力；下层提供保证。完整的决策流程图请参见 [`docs/architecture.md`](docs/architecture.md#decision-architecture)。 **优先级规则**是安全底线。四个模块（生存、战斗、维护、导航）中的规则在每个 tick 按优先级顺序进行评估。紧急规则（逃跑、假死、闪避）拥有高于一切的硬性优先级：它们可以中断任何锁定的例程，使任何活跃的计划失效。这种保证是结构性的，而非学习得来的。智能体无法通过学习来无视致命威胁。 **效用评分**在安全底线内运作。非紧急规则生成反映“当前此行动有多大价值”的浮点分数。五个选择阶段可在运行时配置：阶段 0 忽略分数（保守基线），阶段 1 记录分歧但不改变行为（观察模式），阶段 2 在优先级层级内使用分数，阶段 3 使用加权的跨层级比较，阶段 4 使用带有加权几何平均数的基于声明式考量的评分。这种升级路径允许在评分系统影响决策之前对其进行验证。 **GOAP 规划**生成面向明确目标的多步行动序列：生存、获取经验值、管理资源。规划器在目标状态空间上使用 A* 算法，结合每个行动的学习成本函数，在 50ms 的预算内生成 3-8 步的计划。候选计划通过蒙特卡洛鲁棒性门：从学习到的后验分布中随机采样行动效果，在噪声结果下失败的计划将被拒绝。其与优先级系统的关系是明确的：GOAP 负责提议，优先级负责裁决。紧急规则在每个 tick 首先进行评估，如果有触发则使活跃计划失效。完整的规划管道请参见 [`docs/architecture.md`](docs/architecture.md#goap-planner) 和 [`docs/samples/goap-planner.md`](docs/samples/goap-planner.md)。 ### 例程 行为以具有 `enter` / `tick` / `exit` 生命周期的状态机实现。例程使用可中断的休眠来实现实时运动计时（施法条、移动延迟）；所有休眠每 100ms 轮询一次具备逃跑感知的中断谓词，因此紧急规则可以在一个轮询间隔内突破。一个 5 秒的硬性终止阈值会强制退出任何超过其 tick 预算的例程。战斗施法管道通常运行 2-3 秒，因此该阈值设定在该范围之上。 锁定语义（`locked = True`）保护多步序列免受过早中断。飞行中的拉怪、死亡恢复序列、多步交战：一旦锁定，只有紧急规则可以覆盖。如果没有这种机制，低优先级规则会在多步行动刚好变得相关的那一刻，打断进行到一半的行动。 ### 导航 区域地形从环境自身的 3D 几何结构解析为 1 单位分辨率的高度图，具有可行走、水、熔岩、悬崖和障碍物等地表类型。JPS（跳点搜索）是主要的寻路算法，通过修剪网格上的对称路径以提高速度，当 JPS 在密集地形中耗尽其节点预算时，A* 作为后备方案。两者均使用八向距离启发式、位域加速的可行性检查、Z 轴梯度惩罚和动态避让区成本膨胀。预构建的缓存文件在不同会话间持久保存。 视线使用 DDA（Amanatides-Woo）网格遍历，恰好访问射线穿过的每个单元格一次，无采样间隙。每个单元格检查障碍物标志和插值射线 Z 轴。移动通过预测性障碍物扫描验证前方路径，并在遇到危险之前计算垂直绕行路线，而不是仅仅依赖于卡死恢复。 对于网格寻路无法解决垂直歧义的区域（桥梁、隧道、螺旋坡道、重叠几何结构），预先录制的航点图提供了已知安全的路线。带有 BFS 的区域图可计算用于长途旅行的跨区域路径。 ## 学习型自适应 智能体从自身经验中学习。所有四个学习系统都在同一个信号上训练：遭遇结果。 **遭遇历史。** 每次战斗退出记录 20 个字段：持续时间、法力消耗、生命值损失、使用的策略、宠物死亡、遇到的额外 NPC。针对每种实体类型维护贝叶斯共轭后验（连续值为正态分布，比率为 Beta 分布），并在每次遭遇时增量更新。目标评分路径通过汤普森采样从这些后验中提取，自然地平衡了对不确定目标的探索与对已知优质目标的利用。随着数据的积累，后验逐渐收紧，选择趋于稳定，而无需硬编码的探索计划。数据在不同会话间持久保存。跟踪每次遭遇的遗憾值（所选目标的适应度与最佳可用目标之比）；亚线性的累积遗憾值增长验证了学习的收敛性。 **空间记忆。** 基于 50 单位网格的热力图通过 4 小时的指数衰减跟踪战败、目击和危险事件。热力图将目标评分偏向最多 50%，将智能体引导至高效区域。GOAP 规划器使用逐单元格的泊松刷新预测（源自战败时间戳）来定位预测的刷新点，而不是随机游荡。 **会话记分卡。** 每 30 分钟，一份 7 维记分卡对战败率、生存、拉怪成功率、运行时间、寻路、法力效率和目标选择进行评级。三个参数立即自动调整：游荡半径、社交引怪限制和法力保守水平。 **评分权重调优。** 15 因子的目标评分函数通过有限差分投影梯度下降调整其权重。每个梯度步骤独立扰动权重，通过中心数值导数测量对遭遇适应度的影响，并将更新投影回有界区域（默认值的 ±20%）。自适应的逐权重学习率检测震荡、收敛和停滞。每个区域的收敛大约需要约 100 次战败。 GOAP 规划器的成本函数直接提取自这些学习到的数据。休息成本来自观察到的休息持续时间。遭遇成本来自每个实体的历史记录。随着成本模型收敛，计划质量也随之提高。 ``` --- config: look: neo theme: neutral flowchart: nodeSpacing: 60 rankSpacing: 40 --- flowchart TD %% One encounter signal drives four learning systems at distinct cadences. %% Orange = external input signals. Blue = internal learners. Darker blue = sink. CO(["Combat Outcomes
duration · mana spent · HP lost
survival · pet death · extra npcs encountered"]) PE(["Perception Events
entity sightings · danger events
spawn tracking"]) SP(["Session Performance Data
defeat rate · uptime · pull success
pathing quality · mana efficiency"]) EH["Encounter History
strategy fitness · danger score
cadence: each combat exit"] %% SM receives from both CO and PE. Sightings are not combat-exit-driven. SM["Spatial Memory
50-unit heat map · 4-hour decay
cadence: continuous"] WL["Weight Tuner
15-factor gradient descent · ±20% bounded
cadence: per defeat · ~100 to converge"] SS["Session Scorecard
7-dimension performance grading
roam radius · add limit · mana conservation level
cadence: every 30 minutes"] %% Collapsed consumer view. Actual consumers: GOAP costs, utility weights, %% target scoring, rule thresholds (via AgentContext), strategy selection. DS["Decision System / AgentContext
GOAP cost model · target scoring
utility weights · rule thresholds · spawn positioning"] CO --> EH CO -->|"defeat location · timestamp"| SM CO --> WL PE -->|"sighting records · danger events"| SM SP --> SS EH -->|"encounter cost estimates
strategy fitness override"| DS SM -->|"target score bias
spawn positioning"| DS WL -->|"tuned scoring weights"| DS SS -->|"auto-tuned thresholds
via AgentContext"| DS classDef input fill:#FDF5EC,stroke:#C07A45,stroke-width:1.5px,color:#1F3A4A classDef learner fill:#EAF4FB,stroke:#2E5E7E,stroke-width:2px,color:#1F3A4A classDef sink fill:#C8DFF0,stroke:#2E5E7E,stroke-width:2.5px,color:#1F3A4A class CO,PE,SP input class EH,SM,WL,SS learner class DS sink %% 0–4: CO→EH, CO→SM, CO→WL, PE→SM, SP→SS | 5–8: learners→DS linkStyle 0,1,2,3,4 stroke:#B66A2C,stroke-width:1.5px linkStyle 5,6,7,8 stroke:#2E5E7E,stroke-width:2px ``` ## 可观察性 每个决策分支都记录其推理过程。无声的 `return False` 被视为一个缺陷；它使得相应的行为在会话后分析中不可见。热路径日志记录（每个 tick 对每个实体运行的评分函数）进行了速率限制，以避免数据量问题。 四个层级提供渐进的详细信息： | 层级 | 级别 | 数据量 | 用途 | | ---- | ------- | ---------------- | ------------------------------------------------------ | | T1 | EVENT | ~50 行/小时 | 状态变化：战败、死亡、区域转换 | | T2 | INFO | ~2,000 行/小时 | 操作流程：例程进入/退出、目标选择 | | T3 | VERBOSE | ~5,000 行/小时 | 决策分支：规则跳过、评分明细 | | T4 | DEBUG | ~50,000 行/小时 | 原始数据：内存读取、运动输出、tick 计时 | 每次会话生成 6 个输出文件：4 个日志文件（每个层级阈值一个）、一个结构化的 JSONL 事件流和一个决策回执日志。一个 300 tick 的取证环形缓冲区持续捕获大脑状态，并在死亡时刷新到磁盘：为每次故障提供 30 秒的事件前遥测数据。 ### 会话样本 [docs/samples/](docs/samples/) 中的所有样本都是来自真实会话的实际输出，而非手工编写的示例： | 样本 | 展示内容 | | --- | --- | | [会话层级](docs/samples/session-tiers.md) | 贯穿所有 4 个日志层级的单个会话 | | [决策追踪](docs/samples/decision-trace.md) | 经历 WANDER → ACQUIRE → PULL → IN_COMBAT 转换的 18 条回执 | | [GOAP 计划](docs/samples/goap-planner.md) | 目标评估、A* 搜索、蒙特卡洛鲁棒性门控、成本自我纠正 | | [取证缓冲区](docs/samples/forensics-ring-buffer.md) | 骷髅仇恨打断记忆过程后的 300 tick 环形缓冲区转储 | | [学习的遭遇数据](docs/samples/learned-encounter-data.md) | 跨会话改进：评级 B → A，战斗持续时间 29.5s → 15.9s | | [战斗事件](docs/samples/structured-fight-event.md) | 包含所有 20 个字段的结构化 `fight_end` 事件 | | [收敛性](docs/samples/convergence.md) | 10 次会话运行：随着后验收紧，战斗持续时间减少 53% | | [消融结果](docs/samples/ablation-results.md) | 学习与默认值对比：成本误差、危险区分度、权重稳定性 | ## 无头模拟器 模拟器针对合成的感知序列运行完整的决策栈（大脑、规则、GOAP、学习）。无需游戏客户端，无需环境资产，无外部依赖。 ``` just simulate # replay: single camp session just simulate converge --sessions 10 # convergence: learning across sessions just simulate replay --scenario survival_stress # stress: safety envelope under pressure just simulate benchmark --scenario camp_session # benchmark: 10 Hz realtime pacing ``` 三个内置场景测试不同的系统路径：`camp_session`（拉怪/战斗/休息循环、目标评分、遭遇学习）、`survival_stress`（伤害递增、逃跑紧迫性、紧急规则）和 `exploration`（稀疏目标GOAP 规划、空间记忆）。结果包括 tick 计时百分位数、决策栈活动、GOAP 规划统计和学习快照。 收敛模式在不同会话之间保持学习状态。随着遭遇后验收紧和成本函数自我纠正，战斗持续时间随之下降： ``` Session Grade Fights Avg Dur 1 A 8 22.2s 3 A 24 19.4s 5 A 30 16.6s 10 A 30 10.4s 53% improvement ``` 完整的输出和解释请参见 [docs/samples/convergence.md](docs/samples/convergence.md)。 各场景下的 tick 计时： | | p50 | p95 | p99 | 最大值 | |---|---|---|---|---| | camp_session (1 280 ticks) | 0.1 ms | 0.1 ms | 0.5 ms | 0.7 ms | | survival_stress (220 ticks) | 0.1 ms | 0.2 ms | 0.3 ms | 0.3 ms | 测试策略和覆盖率理念请参见 [docs/testing.md](docs/testing.md)。 ## 许可证 基于 [MIT 许可证](LICENSE) 发布。
标签：3D游戏, AI架构, A*算法, DDA, GOAP, JPS算法, MMORPG, NPC逻辑, Python 3.14, 人工智能, 代理决策, 决策系统, 反应式规则, 寻路, 感知规划, 控制架构, 效用评分, 无依赖, 智能体架构, 汤普森采样, 游戏AI, 游戏开发, 状态机, 用户模式Hook绕过, 目标导向行动规划, 空间记忆, 纯Python, 自适应学习, 蒙地卡罗方法, 视线计算, 贝叶斯, 部分可观察