Skip to content

AGENTS.md

Latest commit

 

History

History
107 lines (85 loc) · 6.35 KB

AGENTS.md

File metadata and controls

107 lines (85 loc) · 6.35 KB
Raw

AGENTS.md — RimMind-Actions

组合工具（Composite ToolCall）编排层。将 Core 提供的原子 ToolCall 组合为高级动作并注册到 Core 的 ToolRegistry。

项目定位

H2 阶段后，24 个内置动作已全部迁移至 Core Mechanism 系统。本模组现在的唯一职责是：

  • 提供 CompositeToolCallBase 抽象基类（共享 JSON 辅助方法 + 原子调用编排）
  • 实现具体组合工具（当前：StabilizeRestCompositeTool）
  • 通过 CompositeToolRegistrar 反射自动发现并注册所有组合工具

依赖 Core，被 Advisor/其他模组通过 RimMindAPI.Tools 调用。

构建

项 值
Target net48, C#9.0, Nullable enable
Output ../1.6/Assemblies/
Assembly RimMindActions, RootNS: RimMind.Actions
依赖 Krafs.Rimworld.Ref, Lib.Harmony.Ref, Newtonsoft.Json, RimMindCore (Domain/Application)

源码结构

Source/
├── RimMindActionsMod.cs                       Mod 入口，反射注册组合工具
├── Actions/
│   ├── CompositeToolCallBase.cs               抽象基类：ExecuteAtomicAsync + 共享 JSON 辅助
│   ├── CompositeToolRegistrar.cs              反射发现并注册所有 CompositeToolCallBase 子类
│   ├── ContinuousJobPoller.cs                 多阶段作业持续轮询器（支持 Blueprint_Build -> Frame 过渡跟踪）
│   ├── StabilizeRestCompositeTool.cs          组合工具：undraft → force_rest
│   ├── EmergencyFleeCompositeTool.cs          组合工具：紧急撤离危险区
│   ├── EatAndRecreationCompositeTool.cs       组合工具：进食与娱乐调理
│   ├── TriagePatientCompositeTool.cs          组合工具：战地救护包扎
│   ├── PlaceBlueprintCompositeTool.cs         组合工具：放置蓝图并持续运料施工至建筑完成
│   ├── PlanRoomProjectCompositeTool.cs        组合工具：批量规划房间蓝图并持续施工至全部完成
│   ├── ClearAreaForBuildCompositeTool.cs      组合工具：清理建筑区域障碍物
│   ├── DesignatedHarvestCompositeTool.cs      组合工具：指定收获与采集
│   ├── SetWorkBillCompositeTool.cs            组合工具：工作台配方清单设置
│   └── ScheduleFarmingCycleCompositeTool.cs   组合工具：种植区农耕周期调度
└── Policies/
    ├── ActionPermissionGuard.cs               Pawn 存活/在图/未倒地(!Downed)与 WorkType 权限校验
    └── ResourceSafetyGuard.cs                 4 级安全门禁与殖民地资源保底红线守卫

关键 API

// 组合工具调用方（通过 Core ToolRegistry）
RimMindAPI.Tools.FindById("actions.stabilize_rest")

// 新增组合工具：继承 CompositeToolCallBase，自动被 CompositeToolRegistrar 发现
public sealed class MyCompositeTool : CompositeToolCallBase { ... }

CompositeToolCallBase 共享辅助方法

方法 用途
ExecuteAtomicAsync(toolId, argsJson, parentArgs, ct) 调用子原子工具，规整 child ToolCallId/ToolName
TryGetArgument<T>(json, key, out T) 从参数 JSON 安全读取强类型字段
TryGetArgumentOrError<T>(json, key, traceId) 安全读取强类型字段，失败直接返回 Result<T, RimMindError>.Err
AreRequiredToolsRegistered() 检查所有 RequiredToolIds 是否已注册，供前置验证
BuildArgumentsJson(params (key,value)[]) 构造子调用紧凑 JSON 参数
BuildStepSummary(params (name,result)[]) 构造标准 {"ok":bool,"content":str} 汇总

组合工具清单

Id 原子依赖 / 机制 说明
actions.stabilize_rest pawn.draft.toggle, pawn.job.set 解除征召（best-effort）→ 强制休息
actions.emergency_flee pawn.draft.toggle, pawn.goto 紧急避险：征召 pawn 并强行移动到安全逃生位置撤出战火
actions.eat_and_recreation pawn.draft.toggle, pawn.job.set 休整调理：解除征召 → 补充食物充饥 → 安排娱乐活动
actions.triage_patient pawn.draft.toggle, pawn.job.set 战地救护：引导医护人员就近照料并包扎治疗重伤病患
actions.place_blueprint Designator_Build, ContinuousJobPoller 放置单格蓝图并轮询驱动 Blueprint_Build → Frame 运料与施工直至完成
actions.plan_room_project Designator_Build, ContinuousJobPoller 批量规划房间墙体/门/家具蓝图并轮询驱动所有 Blueprint_Build → Frame 直至完工
actions.clear_area_for_build ContinuousJobPoller 清理目标建设区域内的树木、碎石与障碍物
actions.designated_harvest DesignationDefOf, ContinuousJobPoller 标记并驱动小人收获成熟作物或砍伐木材
actions.set_work_bill Bill_Production, ContinuousJobPoller 在工作台创建生产清单并驱动小人执行制作
actions.schedule_farming_cycle Zone_Growing, ContinuousJobPoller 配置种植区作物并轮询驱动播种与收获周期

代码约定

  • 新组合工具继承 CompositeToolCallBase，实现 Id/Definition/RequiredToolIds/ExecuteAsync
  • 参数解析用 TryGetArgument<T>，失败返回 Result.Err(RimMindError)
  • 子调用参数构造用 BuildArgumentsJson，汇总用 BuildStepSummary
  • 多步原子调用之间插入 ct.ThrowIfCancellationRequested()
  • 明确部分失败语义（best-effort 步骤加注释说明）
  • 翻译键前缀: RimMind.Actions.*
  • Harmony ID: mcocdaa.RimMindActions

操作边界

必须做

  • 新组合工具声明正确的 RequiredToolIds
  • 验证失败用 Result<ToolResult, RimMindError>.Err(...)，禁止 Result.Ok(ToolResult.Fail(...))
  • 每个新类编写单元测试

绝对禁止

  • 硬编码注册组合工具（用反射 registrar）
  • 在 ExecuteAsync 中吞掉 OperationCanceledException
  • 重新引入已废弃的 RimMindActionsAPI/ActionsBridge/RimMindActionsSettings

历史说明

H2 阶段（2026-05）将 24 个内置动作迁移至 Core Mechanism 系统。原 ActionsBridge、RimMindActionsAPI、BatchActionIntent、ActionResult、WorkTargetInfo、RimMindActionsSettings、DelayedActionQueue 已于本次清理移除（备份至 Refs/backup/RimMind-Actions/）。运行时 Core 使用 NullAgentActionBridge 作为 IAgentActionBridge 默认实现。