上下文记忆与技能系统

本文介绍 Whimbox 中面向 AI 智能体的上下文记忆与技能系统边界。根据当前可获得的项目说明，该能力位于 whimbox/agent_workspace/，用于“大模型上下文管理”，并与 whimbox/agent.py、whimbox/task/ 以及工具调用链相关；项目说明还指出 AI 对话“一定程度上支持 SKILL”。

说明：当前资料只包含项目 README 的功能概览和目录结构，没有提供 agent_workspace、agent.py、技能定义、记忆文件格式、上下文拼接逻辑或调用协议的实际源码。因此，本文严格区分已确认信息与尚未能从源码验证的实现细节，不推断未提供的 API、配置键、数据结构、异常行为或并发模型。

Purpose and Scope

本页聚焦以下范围：

AI 智能体的上下文管理模块：whimbox/agent_workspace/；
AI 智能体入口或协调模块：whimbox/agent.py；
AI 通过自然语言调用 Whimbox 功能，以及与技能（SKILL）相关的已知产品能力；
configs/agent_workspace/ 作为 Agent 记忆存放位置的项目级目录约定。

本页不覆盖任务脚本本身、游戏交互实现、RPC 服务协议、OCR/YOLO、地图、移动或具体自动化任务的内部实现。项目说明将这些能力分别归于 task/、interaction/、api/、map/、view_and_move/ 和 rpc_server.py；如需了解这些模块的细节，应查看对应专题页面或实际源码。

由于没有可读取的实现文件，本页不能确认该系统是否已实现长期记忆、短期会话记忆、技能发现、技能参数校验、上下文压缩、工具结果回写、持久化格式或恢复策略。

Overview

Whimbox 的产品说明把 AI 对话描述为一种通过自然语言执行既有功能的入口，能力范围覆盖每日任务、自动采集、自动钓鱼、自动跑图、宏播放和其他自动化功能；同一说明还指出该能力“一定程度上支持 SKILL”，并将 agent_workspace/ 标记为“大模型上下文管理”。

从已确认的目录约定可以得出以下边界关系：

whimbox/agent.py 是 AI agent 相关的顶层模块名称；
whimbox/agent_workspace/ 是上下文管理相关代码目录；
configs/agent_workspace/ 是存放 agent 记忆的配置目录；
whimbox/task/ 提供可被 agent 调用的任务模块；
main.py 是程序入口，rpc_server.py 负责与前端通信；
当前后端不再提供 UI，仅负责 RPC 服务、大模型调用和工具调用。

这些信息说明上下文与技能系统处于“大模型调用—工具调用—任务执行”链路附近，但源码不足以证明各模块之间的具体调用顺序。尤其不能仅凭目录名确认 agent_workspace 是 Python package、配置目录中的文件类型，或记忆是否按会话、用户、任务或时间进行隔离。

Confirmed System Boundaries

项目说明给出的目录结构表明，相关组件在系统中的职责大致如下：

组件	已确认职责	当前资料能够确认的程度
`whimbox/agent_workspace/`	大模型上下文管理模块	仅确认目录职责，未见实现
`whimbox/agent.py`	大模型 agent 模块	仅确认文件角色，未见类、函数或签名
`configs/agent_workspace/`	存放 agent 记忆	仅确认目录用途，未见文件格式与生命周期
`whimbox/task/`	各种功能脚本，供 agent 调用	仅确认目录用途，未见技能注册和调用协议
`whimbox/rpc_server.py`	与前端通信的 RPC 服务器	不属于本页核心，具体协议未提供
`whimbox/main.py`	程序入口	未提供启动与依赖注入代码

End-to-End Capability View

已确认的产品级流程是：用户可以通过自然语言让 Whimbox 执行已有功能；这些功能包括任务、自动化小功能、跑图、宏和自动弹琴等。AI 能力还支持一定程度的 SKILL，并支持微信远程控制这一产品功能。

但是，下列关键步骤均没有源码证据，不能在本页中写成确定行为：

用户消息由哪个 RPC 方法、命令行入口或前端协议接收；
agent.py 如何创建或配置模型客户端；
上下文是否从 configs/agent_workspace/ 读取，以及读取时机；
记忆如何注入 system prompt、user prompt 或工具调用上下文；
SKILL 是文件、类、函数、提示词模板还是其他结构；
技能如何发现、注册、选择、参数化和执行；
whimbox/task/ 的任务结果如何反馈给模型；
失败时是否重试、改写参数、清理上下文或交给人工处理。

因此，任何针对上述行为的扩展都应先以实际源码和测试为准，而不能只依赖 README 的目录注释。

Memory Storage Boundary

当前资料唯一明确的持久化线索是 configs/agent_workspace/，其目录说明为“存放 agent 的记忆”。这足以确认项目预留了独立的 agent 记忆存储位置，但不足以确认：

记忆是 Markdown、JSON、YAML、SQLite 还是其他格式；
是否存在默认文件名或必需子目录；
记忆由程序自动创建还是必须手工准备；
写入发生在每轮对话、任务完成后、程序退出时还是其他时机；
是否有大小限制、截断策略、摘要策略或版本迁移；
多个 agent、会话或用户是否共享同一记忆空间；
并发写入是否安全；
记忆损坏或不可读时系统如何处理。

在没有这些源码证据前，不应将该目录当作稳定的公共数据格式，也不应直接修改其中的文件并假设程序能够兼容。

Skill System Boundary

README 将 SKILL 描述为 AI 对话的“一定程度上支持”的能力。这一措辞表明技能支持存在范围限制，但没有定义限制的具体含义。当前资料无法确认技能系统是否支持：

技能元数据与描述；
自动发现或显式注册；
技能依赖关系；
参数 schema 或类型校验；
权限控制与危险操作确认；
多步技能编排；
技能执行状态持久化；
工具调用失败后的恢复；
技能热加载或运行时更新。

能够确认的是，项目将若干已有自动化功能作为 AI 可调用能力的产品背景，包括每日任务、自动对话、自动采集、自动钓鱼、自动跑图、宏操作和自动弹琴。具体哪些功能已接入技能系统，必须以 agent.py、agent_workspace/ 与 task/ 的实际引用关系为准。

Configuration and Operations

已知配置位置如下：

路径	已知用途	默认值或格式
`configs/agent_workspace/`	存放 agent 记忆	未提供
`configs/config.json`	项目配置文件	未提供具体键和值

当前资料没有给出模型名称、服务地址、API 密钥、上下文长度、温度、超时、重试次数、日志级别、技能开关或记忆路径覆盖项，因此不能提供可靠的配置键表或默认值。部署和运维时应以实际配置加载代码为准。

项目说明明确要求使用 Python 3.12，并说明后端负责 RPC 服务、大模型调用和工具调用；这能作为运行环境背景，但不能替代对 agent 初始化、模型适配器或技能执行器源码的分析。

Failure Modes and Consistency Considerations

没有实现代码或测试时，以下行为均属于未确认项：

模型服务不可用时是否返回错误、重试或降级；
技能不存在或参数不合法时如何反馈；
任务执行超时或中途失败时是否回写上下文；
记忆目录不可写、文件损坏或格式不兼容时如何启动；
多个 RPC 请求同时更新记忆时是否会覆盖；
工具调用产生的副作用是否要求用户确认；
上下文过长时是否截断旧消息或生成摘要；
敏感信息是否从持久化记忆中排除。

这些问题直接影响可靠性和安全性。特别是，AI 可以通过自然语言触发游戏自动化功能，而项目说明也指出工具调用属于后端职责；在实施或扩展技能时，应先查明是否已有参数校验、权限边界、取消机制和操作确认逻辑，不能假设模型输出天然可信。

Extension Guidance

在缺少源码细节的情况下，安全的扩展顺序应是：

先定位 whimbox/agent.py 的 agent 创建入口和调用入口；
再完整阅读 whimbox/agent_workspace/，确认上下文对象、记忆读写 API 和生命周期；
搜索 configs/agent_workspace/ 的实际读取路径，确认磁盘格式和命名规则；
搜索 whimbox/task/ 被 agent 或技能模块引用的位置，确认任务适配方式；
检查启动代码和配置加载逻辑，确认依赖注入、模型配置和工作目录；
最后阅读测试、日志和异常处理代码，验证并发、失败和恢复行为。

在这些步骤完成前，不建议新增未验证的记忆文件格式、技能注册机制或公共 API，也不建议把 README 中的目录说明当作稳定扩展接口。

Verification Status

本页基于当前提供的项目说明中的功能描述和目录结构编写。可验证的结论仅限于：项目包含 agent、agent workspace、agent 记忆目录和任务目录；AI 对话可用于通过自然语言触发部分功能；项目对 SKILL 提供一定程度支持；后端负责大模型和工具调用。

实现细节不足的部分已明确标注为“未提供”或“无法确认”。当前没有实际源码片段可作为代码示例，也没有可用于精确行号引用的运行时文件引用基础 URL，因此本页不包含代码块、伪造的 API 签名或猜测性的 Mermaid 图表。

如需了解整体项目入口和模块边界，请参阅项目 README 中的项目结构说明。
如需了解具体自动化能力，请参阅 whimbox/task/ 相关专题。
如需了解前端通信，请参阅 whimbox/rpc_server.py 相关专题。
如需了解项目启动流程，请参阅 whimbox/main.py 相关专题。
如需补全本页，应优先提供并阅读 whimbox/agent.py、whimbox/agent_workspace/、configs/agent_workspace/ 以及技能和任务注册相关源码。