AS AgentScopeAPI 手册 / API Reference

WorkspaceManager

public class WorkspaceManager implements AutoCloseable
源码Source io/agentscope/harness/agent/workspace/WorkspaceManager.java:99–1026

工作区管理器,承载智能体的部署、调度与服务化运行。位于 io.agentscope.harness.agent.workspace 包,实现 AutoCloseable。核心成员包括 close、getNamespaceFactory、getIndex、getFilesystem、validate、getWorkspace。

Stateless accessor for workspace content using a two-layer read architecture.

Read path: For every read (AGENTS.md, MEMORY.md, knowledge, etc.), the AbstractFilesystem is queried first. If it returns non-empty content, that content is used (filesystem overrides). Otherwise, the local workspace disk is read as a fallback. The filesystem layer applies user/session scoping transparently via NamespaceFactory.

Write path: All writes (memory, sessions, etc.) go through the AbstractFilesystem.

Listing: File listings (memory files, knowledge files, session logs) union results from both the filesystem layer and local disk, deduplicating by relative path.

Expected layout:


workspace/
├── AGENTS.md
├── MEMORY.md
├── memory/YYYY-MM-DD.md
├── skills/<skill-name>/SKILL.md
├── knowledge/KNOWLEDGE.md
├── knowledge/*
├── subagents/<id>.md (subagent declarations)
├── agents/<agentId>/workspace/ (isolated subagent runtime root, auto-created)
├── agents/<agentId>/sessions/sessions.json
└── agents/<agentId>/sessions/<sessionId>.log.jsonl

构造器摘要Constructor Summary

构造器Constructor说明Description
public WorkspaceManager(Path workspace)
初始化 `WorkspaceManager` 实例。
Creates a new instance.
public WorkspaceManager(Path workspace, AbstractFilesystem filesystem)
初始化 `WorkspaceManager` 实例。
Creates a new instance.
public WorkspaceManager(Path workspace, AbstractFilesystem filesystem, WorkspaceIndex index)
初始化 `WorkspaceManager` 实例。
Creates a new instance.
public WorkspaceManager(Path workspace, AbstractFilesystem filesystem, WorkspaceIndex index, NamespaceFactory namespaceFactory)
初始化 `WorkspaceManager` 实例。
Creates a new instance.

方法摘要Method Summary

方法Method说明Description
public void close()
关闭连接并释放相关资源。
Releases the SQLite-backed `WorkspaceIndex` when this manager owns it.
public NamespaceFactory getNamespaceFactory()
获取命名空间工厂。
Returns the namespace factory.
public WorkspaceIndex getIndex()
获取索引。
Returns the best-effort workspace index; may be `null` when unavailable.
public AbstractFilesystem getFilesystem()
获取文件系统。
Returns the filesystem.
public void validate()
执行校验相关操作。
Validates the workspace exists and key files are present.
public Path getWorkspace()
获取工作区。
Returns the workspace.
public Path resolveRuntimeDataPath(RuntimeContext rc, String relativePath)
解析运行时数据路径。
Resolves a workspace-relative path for runtime user data, applying namespace prefix.
public String readAgentsMd(RuntimeContext rc)
设置读取智能体 Md。
Reads AGENTS.md content, returns empty string if not found.
public String readKnowledgeMd(RuntimeContext rc)
设置读取知识库 Md。
Reads KNOWLEDGE.md content from the knowledge directory.
public String readMemoryMd(RuntimeContext rc)
设置读取记忆 Md。
Reads MEMORY.md content (two-layer: filesystem override, local fallback).
public String readManagedWorkspaceFileUtf8(RuntimeContext rc, String relativePath)
执行 `readManagedWorkspaceFileUtf8` 方法。
Reads a UTF-8 file under the workspace, using the two-layer pattern: filesystem first, then local disk fallback.
public Path getMemoryDir(RuntimeContext rc)
获取记忆目录。
Returns the memory dir.
public Path getSkillsDir()
获取技能目录。
Returns the skills dir.
public Path getKnowledgeDir()
获取知识库目录。
Returns the knowledge dir.
public List<Path> listKnowledgeFiles(RuntimeContext rc)
列出知识库文件。
Lists all files under the knowledge directory tree (union of filesystem + local disk).
public Path getSessionDir(RuntimeContext rc, String agentId)
获取会话目录。
Returns the session dir.
public Path resolveSessionFile(RuntimeContext rc, String agentId, String sessionId)
deprecated
解析会话文件。
Returns the legacy session file path (.json) without creating directories.
public Path resolveSessionContextFile(RuntimeContext rc, String agentId, String sessionId)
解析会话上下文文件。
Returns the JSONL session context file path (LLM-facing, compacted).
public Path resolveSessionLogFile(RuntimeContext rc, String agentId, String sessionId)
解析会话日志文件。
Returns the JSONL session log file path (full history, append-only).
public void appendUtf8WorkspaceRelative(RuntimeContext rc, String relativePath, String content)
追加 `appendUtf8WorkspaceRelative`。
Appends UTF-8 text to a workspace-relative file, creating parent directories when needed.
public void updateSessionIndex(RuntimeContext rc, String agentId, String sessionId, String summary)
更新会话索引。
Upserts metadata for a session in `agents/&lt;agentId&gt;/sessions/sessions.json` (small mutable JSON, keyed by `sessionId`).
public void writeTaskRecord(RuntimeContext rc, String agentId, String sessionId, TaskRecord record)
执行写入任务记录相关操作。
Upserts a `TaskRecord` in `agents/<agentId>/tasks/<sessionId>.json`.
public Optional<TaskRecord> readTaskRecord(RuntimeContext rc, String agentId, String sessionId, String taskId)
执行读取任务记录相关操作。
Reads a single `TaskRecord` by task ID, or `Optional#empty()` if not found.
public Collection<TaskRecord> listTaskRecords(RuntimeContext rc, String agentId, String sessionId)
列出 `listTaskRecords`。
Returns all `TaskRecord`s for the given agent and session, in insertion order.
public Collection<TaskRecord> listAllTaskRecords(RuntimeContext rc, String agentId, Duration recentWindow)
列出 `listAllTaskRecords`。
Returns all `TaskRecord`s for the given agent across *all* sessions that have been active within `recentWindow`, in no particular order.
public void writeUtf8WorkspaceRelative(RuntimeContext rc, String relativePath, String content)
执行 `writeUtf8WorkspaceRelative` 方法。
Overwrites a workspace-relative UTF-8 file.
public void writeDraftSkillFile(RuntimeContext rc, String relativePath, String content)
执行 `writeDraftSkillFile` 方法。
Write a single file under `skills/_drafts/` (or whatever drafts dir the caller passes).
public boolean moveSkill(RuntimeContext rc, String fromRelative, String toRelative)
执行 `moveSkill` 方法。
Move a directory inside the workspace (used by promotion: `skills/_drafts/<x>` → `skills/<x>`).
public List<String> listMemoryFilePaths(RuntimeContext rc)
列出 `listMemoryFilePaths`。
Returns workspace-relative paths of all memory files (`MEMORY.md` and ` memory/*.md`).
public List<String> listSessionLogFiles(RuntimeContext rc)
列出会话日志文件。
Lists workspace-relative paths of all session log files (`*.log.jsonl`).
public String toWorkspaceRelativeString(Path absoluteUnderWorkspace)
设置该参数。
Workspace-relative path for indexing.

构造器详情Constructor Detail

WorkspaceManager

public WorkspaceManager(Path workspace)

初始化 WorkspaceManager 实例。

Creates a new instance.

参数Parameters
名称Name类型Type说明Description
workspacePath工作区(类型 `Path`)。The workspace.
源码Source io/agentscope/harness/agent/workspace/WorkspaceManager.java:138–140

WorkspaceManager

public WorkspaceManager(Path workspace, AbstractFilesystem filesystem)

初始化 WorkspaceManager 实例。

Creates a new instance.

参数Parameters
名称Name类型Type说明Description
workspacePath工作区(类型 `Path`)。The workspace.
filesystemAbstractFilesystem文件系统(类型 `AbstractFilesystem`)。The filesystem.
源码Source io/agentscope/harness/agent/workspace/WorkspaceManager.java:142–144

WorkspaceManager

public WorkspaceManager(Path workspace, AbstractFilesystem filesystem, WorkspaceIndex index)

初始化 WorkspaceManager 实例。

Creates a new instance.

参数Parameters
名称Name类型Type说明Description
workspacePath工作区(类型 `Path`)。The workspace.
filesystemAbstractFilesystem文件系统(类型 `AbstractFilesystem`)。The filesystem.
indexWorkspaceIndex索引(类型 `WorkspaceIndex`)。The index.
源码Source io/agentscope/harness/agent/workspace/WorkspaceManager.java:146–148

WorkspaceManager

public WorkspaceManager(Path workspace, AbstractFilesystem filesystem, WorkspaceIndex index, NamespaceFactory namespaceFactory)

初始化 WorkspaceManager 实例。

Creates a new instance.

参数Parameters
名称Name类型Type说明Description
workspacePath工作区(类型 `Path`)。The workspace.
filesystemAbstractFilesystem文件系统(类型 `AbstractFilesystem`)。The filesystem.
indexWorkspaceIndex索引(类型 `WorkspaceIndex`)。The index.
namespaceFactoryNamespaceFactory命名空间工厂(类型 `NamespaceFactory`)。The namespace factory.
源码Source io/agentscope/harness/agent/workspace/WorkspaceManager.java:150–156

方法详情Method Detail

close

public void close()

关闭连接并释放相关资源。

Releases the SQLite-backed WorkspaceIndex when this manager owns it.

源码Source io/agentscope/harness/agent/workspace/WorkspaceManager.java:178–183

getNamespaceFactory

public NamespaceFactory getNamespaceFactory()

获取命名空间工厂。

Returns the namespace factory.

返回Returns NamespaceFactory
返回NamespaceFactory。Returns namespace factory.
源码Source io/agentscope/harness/agent/workspace/WorkspaceManager.java:185–187

getIndex

public WorkspaceIndex getIndex()

获取索引。

Returns the best-effort workspace index; may be null when unavailable.

返回Returns WorkspaceIndex
返回WorkspaceIndex。Returns workspace index.
源码Source io/agentscope/harness/agent/workspace/WorkspaceManager.java:190–192

getFilesystem

public AbstractFilesystem getFilesystem()

获取文件系统。

Returns the filesystem.

返回Returns AbstractFilesystem
返回AbstractFilesystem。Returns abstract filesystem.
源码Source io/agentscope/harness/agent/workspace/WorkspaceManager.java:194–196

validate

public void validate()

执行校验相关操作。

Validates the workspace exists and key files are present.

源码Source io/agentscope/harness/agent/workspace/WorkspaceManager.java:202–226

getWorkspace

public Path getWorkspace()

获取工作区。

Returns the workspace.

返回Returns Path
返回路径。Returns path.
源码Source io/agentscope/harness/agent/workspace/WorkspaceManager.java:228–230

resolveRuntimeDataPath

public Path resolveRuntimeDataPath(RuntimeContext rc, String relativePath)

解析运行时数据路径。

Resolves a workspace-relative path for runtime user data, applying namespace prefix.

参数Parameters
名称Name类型Type说明Description
rcRuntimeContextrc(类型 `RuntimeContext`)。The rc.
relativePathStringrelative 路径(类型 `String`)。The relative path.
返回Returns Path
返回路径。Returns path.
源码Source io/agentscope/harness/agent/workspace/WorkspaceManager.java:239–248

readAgentsMd

public String readAgentsMd(RuntimeContext rc)

设置读取智能体 Md。

Reads AGENTS.md content, returns empty string if not found.

参数Parameters
名称Name类型Type说明Description
rcRuntimeContextrc(类型 `RuntimeContext`)。The rc.
返回Returns String
返回字符串结果。Returns a string.
源码Source io/agentscope/harness/agent/workspace/WorkspaceManager.java:251–253

readKnowledgeMd

public String readKnowledgeMd(RuntimeContext rc)

设置读取知识库 Md。

Reads KNOWLEDGE.md content from the knowledge directory.

参数Parameters
名称Name类型Type说明Description
rcRuntimeContextrc(类型 `RuntimeContext`)。The rc.
返回Returns String
返回字符串结果。Returns a string.
源码Source io/agentscope/harness/agent/workspace/WorkspaceManager.java:256–258

readMemoryMd

public String readMemoryMd(RuntimeContext rc)

设置读取记忆 Md。

Reads MEMORY.md content (two-layer: filesystem override, local fallback).

参数Parameters
名称Name类型Type说明Description
rcRuntimeContextrc(类型 `RuntimeContext`)。The rc.
返回Returns String
返回字符串结果。Returns a string.
源码Source io/agentscope/harness/agent/workspace/WorkspaceManager.java:261–263

readManagedWorkspaceFileUtf8

public String readManagedWorkspaceFileUtf8(RuntimeContext rc, String relativePath)

执行 readManagedWorkspaceFileUtf8 方法。

Reads a UTF-8 file under the workspace, using the two-layer pattern: filesystem first, then local disk fallback.

参数Parameters
名称Name类型Type说明Description
rcRuntimeContextrc(类型 `RuntimeContext`)。The rc.
relativePathStringrelative 路径(类型 `String`)。The relative path.
返回Returns String
返回字符串结果。Returns a string.
源码Source io/agentscope/harness/agent/workspace/WorkspaceManager.java:269–282

getMemoryDir

public Path getMemoryDir(RuntimeContext rc)

获取记忆目录。

Returns the memory dir.

参数Parameters
名称Name类型Type说明Description
rcRuntimeContextrc(类型 `RuntimeContext`)。The rc.
返回Returns Path
返回路径。Returns path.
源码Source io/agentscope/harness/agent/workspace/WorkspaceManager.java:284–286

getSkillsDir

public Path getSkillsDir()

获取技能目录。

Returns the skills dir.

返回Returns Path
返回路径。Returns path.
源码Source io/agentscope/harness/agent/workspace/WorkspaceManager.java:288–290

getKnowledgeDir

public Path getKnowledgeDir()

获取知识库目录。

Returns the knowledge dir.

返回Returns Path
返回路径。Returns path.
源码Source io/agentscope/harness/agent/workspace/WorkspaceManager.java:292–294

listKnowledgeFiles

public List<Path> listKnowledgeFiles(RuntimeContext rc)

列出知识库文件。

Lists all files under the knowledge directory tree (union of filesystem + local disk).

参数Parameters
名称Name类型Type说明Description
rcRuntimeContextrc(类型 `RuntimeContext`)。The rc.
返回Returns List<Path>
返回列出。Returns list.
源码Source io/agentscope/harness/agent/workspace/WorkspaceManager.java:297–334

getSessionDir

public Path getSessionDir(RuntimeContext rc, String agentId)

获取会话目录。

Returns the session dir.

参数Parameters
名称Name类型Type说明Description
rcRuntimeContextrc(类型 `RuntimeContext`)。The rc.
agentIdString智能体标识(类型 `String`)。The agent id.
返回Returns Path
返回路径。Returns path.
源码Source io/agentscope/harness/agent/workspace/WorkspaceManager.java:336–338

resolveSessionFile

public Path resolveSessionFile(RuntimeContext rc, String agentId, String sessionId)
deprecated

解析会话文件。

Returns the legacy session file path (.json) without creating directories.

已弃用。Deprecated. 用于JSONL 格式的使用`#resolveSessionContextFile(RuntimeContext, String, String)`。Use `#resolveSessionContextFile(RuntimeContext, String, String)` for the JSONL format.
参数Parameters
名称Name类型Type说明Description
rcRuntimeContextrc(类型 `RuntimeContext`)。The rc.
agentIdString智能体标识(类型 `String`)。The agent id.
sessionIdString会话标识(类型 `String`)。The session id.
返回Returns Path
返回路径。Returns path.
源码Source io/agentscope/harness/agent/workspace/WorkspaceManager.java:346–349

resolveSessionContextFile

public Path resolveSessionContextFile(RuntimeContext rc, String agentId, String sessionId)

解析会话上下文文件。

Returns the JSONL session context file path (LLM-facing, compacted).

参数Parameters
名称Name类型Type说明Description
rcRuntimeContextrc(类型 `RuntimeContext`)。The rc.
agentIdString智能体标识(类型 `String`)。The agent id.
sessionIdString会话标识(类型 `String`)。The session id.
返回Returns Path
返回路径。Returns path.
源码Source io/agentscope/harness/agent/workspace/WorkspaceManager.java:352–355

resolveSessionLogFile

public Path resolveSessionLogFile(RuntimeContext rc, String agentId, String sessionId)

解析会话日志文件。

Returns the JSONL session log file path (full history, append-only).

参数Parameters
名称Name类型Type说明Description
rcRuntimeContextrc(类型 `RuntimeContext`)。The rc.
agentIdString智能体标识(类型 `String`)。The agent id.
sessionIdString会话标识(类型 `String`)。The session id.
返回Returns Path
返回路径。Returns path.
源码Source io/agentscope/harness/agent/workspace/WorkspaceManager.java:358–360

appendUtf8WorkspaceRelative

public void appendUtf8WorkspaceRelative(RuntimeContext rc, String relativePath, String content)

追加 appendUtf8WorkspaceRelative。

Appends UTF-8 text to a workspace-relative file, creating parent directories when needed.

参数Parameters
名称Name类型Type说明Description
rcRuntimeContextrc(类型 `RuntimeContext`)。The rc.
relativePathStringrelative 路径(类型 `String`)。The relative path.
contentString内容(类型 `String`)。The content.
源码Source io/agentscope/harness/agent/workspace/WorkspaceManager.java:370–397

updateSessionIndex

public void updateSessionIndex(RuntimeContext rc, String agentId, String sessionId, String summary)

更新会话索引。

Upserts metadata for a session in agents/ /sessions/sessions.json (small mutable JSON, keyed by sessionId).

参数Parameters
名称Name类型Type说明Description
rcRuntimeContextrc(类型 `RuntimeContext`)。The rc.
agentIdString智能体标识(类型 `String`)。The agent id.
sessionIdString会话标识(类型 `String`)。The session id.
summaryString摘要(类型 `String`)。The summary.
源码Source io/agentscope/harness/agent/workspace/WorkspaceManager.java:406–437

writeTaskRecord

public void writeTaskRecord(RuntimeContext rc, String agentId, String sessionId, TaskRecord record)

执行写入任务记录相关操作。

Upserts a TaskRecord in agents/ /tasks/ .json.

参数Parameters
名称Name类型Type说明Description
rcRuntimeContextrc(类型 `RuntimeContext`)。The rc.
agentIdString智能体标识(类型 `String`)。The agent id.
sessionIdString会话标识(类型 `String`)。The session id.
recordTaskRecord记录(类型 `TaskRecord`)。The record.
源码Source io/agentscope/harness/agent/workspace/WorkspaceManager.java:466–497

readTaskRecord

public Optional<TaskRecord> readTaskRecord(RuntimeContext rc, String agentId, String sessionId, String taskId)

执行读取任务记录相关操作。

Reads a single TaskRecord by task ID, or Optional#empty() if not found.

参数Parameters
名称Name类型Type说明Description
rcRuntimeContextrc(类型 `RuntimeContext`)。The rc.
agentIdString智能体标识(类型 `String`)。The agent id.
sessionIdString会话标识(类型 `String`)。The session id.
taskIdString任务标识(类型 `String`)。The task id.
返回Returns Optional<TaskRecord>
返回可选。Returns optional.
源码Source io/agentscope/harness/agent/workspace/WorkspaceManager.java:502–515

listTaskRecords

public Collection<TaskRecord> listTaskRecords(RuntimeContext rc, String agentId, String sessionId)

列出 listTaskRecords。

Returns all TaskRecords for the given agent and session, in insertion order.

参数Parameters
名称Name类型Type说明Description
rcRuntimeContextrc(类型 `RuntimeContext`)。The rc.
agentIdString智能体标识(类型 `String`)。The agent id.
sessionIdString会话标识(类型 `String`)。The session id.
返回Returns Collection<TaskRecord>
返回集合。Returns collection.
源码Source io/agentscope/harness/agent/workspace/WorkspaceManager.java:520–527

listAllTaskRecords

public Collection<TaskRecord> listAllTaskRecords(RuntimeContext rc, String agentId, Duration recentWindow)

列出 listAllTaskRecords。

Returns all TaskRecords for the given agent across all sessions that have been active within recentWindow, in no particular order.

参数Parameters
名称Name类型Type说明Description
rcRuntimeContextrc(类型 `RuntimeContext`)。The rc.
agentIdString智能体标识(类型 `String`)。the parent agent identifier
recentWindowDurationrecent Window(类型 `Duration`)。only consider files modified within this duration; files known to be older are assumed to contain only terminal tasks and are skipped
返回Returns Collection<TaskRecord>
返回集合。Returns collection.
源码Source io/agentscope/harness/agent/workspace/WorkspaceManager.java:546–598

writeUtf8WorkspaceRelative

public void writeUtf8WorkspaceRelative(RuntimeContext rc, String relativePath, String content)

执行 writeUtf8WorkspaceRelative 方法。

Overwrites a workspace-relative UTF-8 file.

参数Parameters
名称Name类型Type说明Description
rcRuntimeContextrc(类型 `RuntimeContext`)。The rc.
relativePathStringrelative 路径(类型 `String`)。The relative path.
contentString内容(类型 `String`)。The content.
源码Source io/agentscope/harness/agent/workspace/WorkspaceManager.java:711–729

writeDraftSkillFile

public void writeDraftSkillFile(RuntimeContext rc, String relativePath, String content)

执行 writeDraftSkillFile 方法。

Write a single file under skills/_drafts/ (or whatever drafts dir the caller passes).

参数Parameters
名称Name类型Type说明Description
rcRuntimeContextrc(类型 `RuntimeContext`)。the runtime context (passed straight through to the filesystem)
relativePathStringrelative 路径(类型 `String`)。workspace-relative path (must include the drafts prefix)
contentString内容(类型 `String`)。UTF-8 content
源码Source io/agentscope/harness/agent/workspace/WorkspaceManager.java:764–784

moveSkill

public boolean moveSkill(RuntimeContext rc, String fromRelative, String toRelative)

执行 moveSkill 方法。

Move a directory inside the workspace (used by promotion: skills/_drafts/ → skills/).

参数Parameters
名称Name类型Type说明Description
rcRuntimeContextrc(类型 `RuntimeContext`)。The rc.
fromRelativeString来自 Relative(类型 `String`)。The from relative.
toRelativeString到 Relative(类型 `String`)。The to relative.
返回Returns boolean
返回布尔值,表示判断结果。Returns a boolean result.
源码Source io/agentscope/harness/agent/workspace/WorkspaceManager.java:791–810

listMemoryFilePaths

public List<String> listMemoryFilePaths(RuntimeContext rc)

列出 listMemoryFilePaths。

Returns workspace-relative paths of all memory files (MEMORY.md and memory/*.md).

参数Parameters
名称Name类型Type说明Description
rcRuntimeContextrc(类型 `RuntimeContext`)。The rc.
返回Returns List<String>
返回列出。Returns list.
源码Source io/agentscope/harness/agent/workspace/WorkspaceManager.java:939–974

listSessionLogFiles

public List<String> listSessionLogFiles(RuntimeContext rc)

列出会话日志文件。

Lists workspace-relative paths of all session log files (*.log.jsonl).

参数Parameters
名称Name类型Type说明Description
rcRuntimeContextrc(类型 `RuntimeContext`)。The rc.
返回Returns List<String>
返回列出。Returns list.
源码Source io/agentscope/harness/agent/workspace/WorkspaceManager.java:980–1017

toWorkspaceRelativeString

public String toWorkspaceRelativeString(Path absoluteUnderWorkspace)

设置该参数。

Workspace-relative path for indexing.

参数Parameters
名称Name类型Type说明Description
absoluteUnderWorkspacePathabsolute Under 工作区(类型 `Path`)。The absolute under workspace.
返回Returns String
返回字符串结果。Returns a string.
源码Source io/agentscope/harness/agent/workspace/WorkspaceManager.java:1020–1025
基于官方固定版本源码静态生成Generated from pinned official sources · Python 2.0.11 · Java 2.0.4
签名与文档为静态抽取;如有疑问请以源码为准。Signatures and docs are extracted statically; verify against the source when in doubt.