类class io.agentscope.harness.agent.workspace 2.x

WorkspaceIndex

public class WorkspaceIndex implements AutoCloseable

源码Source io/agentscope/harness/agent/workspace/WorkspaceIndex.java:50–372

工作区索引，承载智能体的部署、调度与服务化运行。位于 io.agentscope.harness.agent.workspace 包，实现 AutoCloseable。核心成员包括 open、upsert、upsertFromLocalFile、remove、rename、exists。

Best-effort SQLite index for the local workspace.

Tracks files that have been materialized locally under two path prefixes: agents/*/sessions/** and memory/**. The index is used to speed up ls / glob / exists / grep in remote-backed workspace mode by avoiding full-store key scans when enumerating paths under a prefix. File content is never stored in the index — grep still fetches each candidate file from the remote store authoritatively.

Consistency model: the index is best-effort and may lag remote changes. Remote writes remain authoritative. Index update failures are silently logged and never propagate to callers.

Thread-safety: SQLite serialises concurrent writers through its own transaction machinery. No external locks are required.

方法摘要Method Summary

方法Method	说明Description
`public static` `WorkspaceIndex open(Path workspaceRoot)` static	设置打开。 Opens (or creates) the workspace index for the given workspace root.
`public void upsert(String path, long sizeBytes, String modifiedAt)`	执行 `upsert` 方法。 Upserts a file entry in the index.
`public void upsertFromLocalFile(String path, Path localFile)`	执行 `upsertFromLocalFile` 方法。 Convenience overload that reads file size from the local file if it exists.
`public void remove(String path)`	设置移除。 Removes a file entry from the index.
`public void rename(String fromPath, String toPath)`	执行 `rename` 方法。 Renames (moves) an index entry from `fromPath` to `toPath`.
`public boolean exists(String path)`	判断数据是否存在。 Returns `true` if the index contains an entry for the given path with `present_local = 1`.
`public List<String> listByPrefix(String prefix)`	列出 `listByPrefix`。 Returns all locally-present paths that start with the given prefix.
`public boolean hasPrefix(String prefix)`	判断是否具有 `hasPrefix`。 Returns true if the index has any entries under the given prefix.
`public void rebuildFromDisk(Path workspaceRoot)`	设置该参数。 Rebuilds the index by walking the local workspace directories (`agents/*/sessions` and `memory`).
`public void close()`	关闭连接并释放相关资源。 Releases resources and connections.

方法详情Method Detail

open

public static WorkspaceIndex open(Path workspaceRoot)

static

设置打开。

Opens (or creates) the workspace index for the given workspace root.

参数Parameters

名称Name	类型Type	说明Description
`workspaceRoot`	Path	工作区根（类型 `Path`）。absolute path to the workspace root directory

返回Returns WorkspaceIndex

返回WorkspaceIndex。a ready-to-use `WorkspaceIndex`, or `null` on failure

源码Source io/agentscope/harness/agent/workspace/WorkspaceIndex.java:82–96

upsert

public void upsert(String path, long sizeBytes, String modifiedAt)

执行 upsert 方法。

Upserts a file entry in the index.

参数Parameters

名称Name	类型Type	说明Description
`path`	String	路径（类型 `String`）。workspace-relative path (forward slashes)
`sizeBytes`	long	大小字节（类型 `long`）。file size in bytes; pass `-1` if unknown
`modifiedAt`	String	modified At（类型 `String`）。ISO-8601 timestamp string; pass `null` to use current time

源码Source io/agentscope/harness/agent/workspace/WorkspaceIndex.java:142–164

upsertFromLocalFile

public void upsertFromLocalFile(String path, Path localFile)

执行 upsertFromLocalFile 方法。

Convenience overload that reads file size from the local file if it exists.

参数Parameters

名称Name	类型Type	说明Description
`path`	String	路径（类型 `String`）。workspace-relative path
`localFile`	Path	本地文件（类型 `Path`）。absolute path on disk (used for size / mtime); may not exist

源码Source io/agentscope/harness/agent/workspace/WorkspaceIndex.java:172–187

remove

public void remove(String path)

设置移除。

Removes a file entry from the index.

参数Parameters

名称Name	类型Type	说明Description
`path`	String	路径（类型 `String`）。workspace-relative path

源码Source io/agentscope/harness/agent/workspace/WorkspaceIndex.java:194–204

rename

public void rename(String fromPath, String toPath)

执行 rename 方法。

Renames (moves) an index entry from fromPath to toPath.

参数Parameters

名称Name	类型Type	说明Description
`fromPath`	String	来自路径（类型 `String`）。The from path.
`toPath`	String	到路径（类型 `String`）。The to path.

源码Source io/agentscope/harness/agent/workspace/WorkspaceIndex.java:210–225

exists

public boolean exists(String path)

判断数据是否存在。

Returns true if the index contains an entry for the given path with present_local = 1.

参数Parameters

名称Name	类型Type	说明Description
`path`	String	路径（类型 `String`）。The path.

返回Returns boolean

返回布尔值，表示判断结果。Returns a boolean result.

源码Source io/agentscope/harness/agent/workspace/WorkspaceIndex.java:235–250

listByPrefix

public List<String> listByPrefix(String prefix)

列出 listByPrefix。

Returns all locally-present paths that start with the given prefix.

参数Parameters

名称Name	类型Type	说明Description
`prefix`	String	prefix（类型 `String`）。workspace-relative directory prefix (e.g. `agents/a1/sessions/`)

返回Returns List<String>

返回列出。list of matching paths, may be empty

源码Source io/agentscope/harness/agent/workspace/WorkspaceIndex.java:258–276

hasPrefix

public boolean hasPrefix(String prefix)

判断是否具有 hasPrefix。

Returns true if the index has any entries under the given prefix.

参数Parameters

名称Name	类型Type	说明Description
`prefix`	String	prefix（类型 `String`）。The prefix.

返回Returns boolean

返回布尔值，表示判断结果。Returns a boolean result.

源码Source io/agentscope/harness/agent/workspace/WorkspaceIndex.java:282–294

rebuildFromDisk

public void rebuildFromDisk(Path workspaceRoot)

设置该参数。

Rebuilds the index by walking the local workspace directories (agents/*/sessions and memory).

参数Parameters

名称Name	类型Type	说明Description
`workspaceRoot`	Path	工作区根（类型 `Path`）。absolute path to workspace root

源码Source io/agentscope/harness/agent/workspace/WorkspaceIndex.java:309–338

close

public void close()

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

Releases resources and connections.

源码Source io/agentscope/harness/agent/workspace/WorkspaceIndex.java:344–351