AgentsView S3 Provider 规则:面向对象存储会话摄入的实现者契约【免费下载链接】agentsviewLocal-first session search, analytics, insights, and token use statistics for coding agents, supporting Claude Code, Codex, and more than 20 other agents.项目地址: https://gitcode.com/GitHub_Trending/ag/agentsview本篇围绕 S3 Provider Rules 展开,讲解 AgentsView 如何在s3://对象存储根上发现、去重与解析单文件会话对象,以及为 Claude、Codex、Cursor 等 agent 接入 S3 摄入时必须遵守的实现契约。读完后,你将掌握 S3Provider 接口的完整方法面、DefaultS3Provider 的适用边界、会话身份命名规则,以及从发现(discovery)到同步分发(sync dispatch)的整条调用链,并知道如何为自定义 agent 正确地打开S3 能力。适用场景:S3 摄入不是万能的AgentsView 的 S3 摄入只面向单文件会话对象,且对象必须位于如下布局之下:s3://bucket/.../machine/raw/agent/...其中agent路径段必须是该 provider 的AgentType字符串——引擎正是靠这个路径段加上Source.S3Discovery能力位,决定哪个对象属于哪个 agent。这一点在 docs/configuration.md 的 S3-Compatible Session Sources 一节有面向操作者的配置说明,而 docs/agents/s3-providers.md 则是面向实现者的契约。明确不适合 S3 摄入的情形包括:多文件容器、SQLite 存储,以及无法从单个对象路径推导出会话名的 agent。这些情况不应通过扩展 S3 路径来处理,而应走 SSH 远程同步或 PostgreSQL 等其他机制。从源码结构看,这个单文件、可命名的约束贯穿全链路:s3Client 构建传输客户端,s3PrefixScan列出对象,同步引擎把对象拉取到临时文件、交给既有 per-agent 解析器,再删除临时文件——全程不建立持久的本地镜像。必备实现面:四条硬性要求文档把新 agent 接入 S3 的工作面收敛为四条,全部可在仓库中找到对应实现:实现parser.S3Provider接口。接口定义在 internal/parser/s3_provider.go,包含五个方法:type S3Provider interface { S3Scanner() S3SessionScanner S3SessionID(uri string) string S3TempRelPath(objectPath string) (string, error) S3StatSession(uri string) (S3Object, error) S3PostFetchHydrate(tempDir, tempPath, configuredRoot, objectURI string) error }S3Scanner返回共享扫描配置,提供 Keep/Project 谓词;S3SessionID从对象 URI 推导持久会话 ID;S3TempRelPath把对象路径映射为临时物化目录内的相对路径;S3StatSession返回对象元数据(供增量跳过检查);S3PostFetchHydrate在拉取完成后对临时文件做 provider 专属的水合(hydrate)。在工厂和构造出的 provider 上都将Source.S3Discovery设为CapabilitySupported。启动迁移会拒绝声明了能力却未实现接口的 provider——查找逻辑 S3ProviderFor 正是这样双重校验的:先查能力位,再对factory.NewProvider(ProviderConfig{})做.(S3Provider)断言,断言失败会写入s3ProviderNone{}哨兵缓存,避免反复重试。把Discover/DiscoverEach中的s3://根路由到s3PrefixScan(root, scanner),确保 provider 侧发现与引擎侧分发使用同一套 keep/project 规则。共享扫描体 s3PrefixScan 列出根下全部对象,用s3MachineFromRoot从.../machine/raw/provider布局中推导来源机器,再对每个对象依次执行 Keep 过滤、Sidecar 元数据折叠、Project 推导,产出DiscoveredFile。在WatchPlan中跳过s3://根。对象存储不是本地可监视目录树,s3://源由初始同步、手动同步和周期性目录扫描拾取,不参与 fsnotify。默认实现与自定义实现的边界当 agent 符合常见布局时,应内嵌DefaultS3Provider,而不是自写逻辑。DefaultS3Provider 只有三个字段:type DefaultS3Provider struct { Agent AgentType IDPrefix string Extensions []string }它封装的规则(见 S3Scanner 与 S3SessionID):只保留文件名以声明扩展名结尾的对象(匹配时大小写不敏感,且要求至少两个路径段);项目取配置根下的第一个路径段;会话 ID 为IDPrefix加文件名去扩展名后的 stem;临时物化路径剥离raw/agent段(见 s3TempRelPathAfterRawAgent,并经sanitizeS3TempRelParts拒绝空段、.、..、含/或\的不安全对象名,防止路径逃逸);不做 sidecar 折叠,也不做 post-fetch hydrate。一旦上述任何一条规则不成立,就应为该 agent 编写专门的agent_s3.go。当前的三个自定义实现及其原因(与文档中的表格一致):Agent无法仅用默认实现的原因ClaudeSidecar 折叠(工具结果旁路对象)、subagent 路径、transcript 保留规则Codexrollout-*.jsonl保留规则、codex:UUID 会话 ID、sessions/archived 路径改写、父会话与session_index定位;此外 TraeX 共享同一 provider 类型,绝不能为其启用 S3Cursor同时采集project/id.{jsonl,txt}与本地agent-transcripts布局(含父会话的subagents目录);仅对本地布局解码编码后的项目目录;跨多个配置根按来源机器对同 stem 会话去重,优先顺序为本会话自己的嵌套/平铺对象 其他会话subagents目录中的副本 .jsonl 嵌套 平铺 字典序路径各实现的源码位置:internal/parser/claude_s3.go、internal/parser/codex_s3.go、internal/parser/cursor_s3.go。其中几个细节值得注意:Claude 的 sidecar 折叠:claudeS3SidecarRoots 为每个 transcript 定位tool-results前缀(subagent 还要加上父会话的前缀),这些对象的大小、修改时间与指纹会折叠进会话的新鲜度身份——因为工具结果可能在不改 JSONL 的前提下改变解析内容。Codex 的根隔离:CodexS3SessionUUIDFromFilename 从文件名提取 UUID 并加codex:前缀;而 FindCodexS3ParentSessionURI 在定位父 rollout 时只在同一配置根内列举元数据,优先非archived_sessions路径的匹配——这解释了文档配置中Codex 发现只导入配置根加尾部斜杠下的 rollout 文件,raw/codex-backup这类兄弟前缀会被忽略的行为。Cursor 的去重排序:preferCursorS3Transcripts 以{machine, stem}为键保留每个会话的一个对象,而 cursorS3LayoutRank 把对象分类为 subagent/flat/nested 三档后再按.jsonl、嵌套优先、字典序决胜。文档同时划定了通用传输层的边界:internal/parser/s3source.go 保持纯通用传输——client、list、fetch、stat 与s3PrefixScan,agent 策略不放在这里。身份规则:两个对象共用一个 ID 会互相覆盖S3SessionID是引擎在加上来源机器前缀之前的持久会话键。internal/sync/s3.go中的 s3SessionIDPrefix 以machine~形式生成前缀,因此完整存储键形如machine~S3SessionID。由此导出四条身份纪律:只保留该 agent 的真实 transcript 路径。Claude 的 keepClaudeS3Session 是范例:顶层project/uuid.jsonl(排除agent-开头名称与任何subagents路径),或.../subagents/.../agent-*.jsonl两种形态之一。同 stem 的文件对只保留一个。若.jsonl与.txt(或其他成对格式)共享 stem,保留本地解析器偏好的那个格式。Cursor 的.jsonl优先正是这一条的落地。ID 校验沿用本地 provider 已有的规则。例如 cursorS3TranscriptName 用IsValidSessionID校验 stem,与本地发现路径共用同一校验器。不要发明绕过 scanner 的第二套 discover 包装器。额外的后处理(优先.jsonl、折叠 sidecar)应放在 scanner 旁边,而不是另起一条发现管线。测试:用具体对象 URI 保护 keep 与身份契约文档要求测试以具体对象 URI为素材,覆盖四类断言:一个已记录的 harvest 对象能被发现;一个同扩展名的垃圾对象不能被发现;同 stem 的文件对只产出一个会话 ID 和一个发现的 source;共享 provider 类型的 fork 在未拥有命名空间时保持 S3 关闭。仓库中 internal/parser/s3_discovery_test.go、claude_s3_test.go、codex_s3_test.go、cursor_s3_test.go 即这些契约的测试载体。TraeX 的共享类型不启用 S3约束在源码中同样有硬证据:codexProvider.S3Scanner 与 S3SessionID 开头都先检查p.spec.agent ! AgentCodex,不匹配时返回空扫描器/空 ID。同步分发:能力位之后只有一条路能力位设置好之后,internal/sync/s3.go与internal/sync/s3_source.go通过 S3ProviderFor 分发——不要为新的 agent 再加一处switch file.Agent。核心处理函数 Engine.processS3Session 展示了这条路的实际形状:按 agent 计算持久会话 ID 并做源未变化跳过检查(基于Size、LastModified与对象指纹——s3ObjectFingerprint会收集 ETag、version ID 与各类校验和,见 internal/parser/s3source.go);通过safeS3TempRelPath得到安全的临时相对路径,再获取保留租约;fetchS3Object流式拉取对象到avs3-*临时目录(对象字节直写磁盘,大会话不必整块驻留内存);按 agent 执行水合:claude 格式折叠 tool-results,Codex 定位父 rollout 与session_index.jsonl(见 hydrateS3CodexSessionIndex),其余 agent 回调S3PostFetchHydrate;用os.Chtimes把临时文件 mtime 还原为源对象的修改时间,再以 tempDir 为根调用普通 provider 的Parse(parseMaterializedS3Source);解析结果中把File.Path改写回真实的s3://URI,并应用machine~前缀后落库,临时文件随即删除。操作者侧配置速览实现契约的另一面是操作者配置,完整说明见 docs/configuration.md 的 S3-Compatible Session Sources 一节,典型配置如下:[agents.claude] dirs [ ~/.claude/projects, s3://agent-archive/laptop/raw/claude, ] [agents.codex] dirs [ ~/.codex/sessions, s3://agent-archive/laptop/raw/codex, ]凭据与端点使用标准 AWS 风格环境变量:AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY、AWS_REGION、AWS_S3_ENDPOINT(对 MinIO、阿里云 OSS、Cloudflare R2 等 S3 兼容服务必设)。端点安全策略在 s3EndpointConfig 中实现:http://端点仅对回环主机放行,非回环 HTTP 端点需显式设置AGENTSVIEW_ALLOW_INSECURE_S3_ENDPOINTtrue,且仅限可信内网——因为会话 transcript 将无 TLS 传输。预期对象布局(与实现契约中的machine/raw/agent一一对应):s3://bucket/.../machine/raw/claude/project/uuid.jsonl s3://bucket/.../machine/raw/claude/project/subagents/.../agent-*.jsonl s3://bucket/.../machine/raw/codex/2026/06/24/rollout-*.jsonl s3://bucket/.../machine/raw/cursor/project/uuid.jsonl s3://bucket/.../machine/raw/icodemate/project/session.jsonl机器名取自raw之前的路径段(s3MachineFromRoot 的实现);若不存在这样的段,会话回退到本机 AgentsView 的机器标签。小结S3 摄入契约的核心可以浓缩为三句话:布局决定归属(agent段 能力位)、身份决定去重(S3SessionID 机器前缀,同 ID 互相覆盖)、分发只走一处(s3PrefixScan发现、S3ProviderFor调度,禁止新增 agent 级 switch)。满足这三点后,新 agent 的对象存储摄入即可复用引擎的增量跳过、指纹比较与临时物化解析,而不需要改动同步主链路。【免费下载链接】agentsviewLocal-first session search, analytics, insights, and token use statistics for coding agents, supporting Claude Code, Codex, and more than 20 other agents.项目地址: https://gitcode.com/GitHub_Trending/ag/agentsview创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
AgentsView S3 Provider 规则:面向对象存储会话摄入的实现者契约【免费下载链接】agentsviewLocal-first session search, analytics, insights, and token use statistics for coding agents, supporting Claude Code, Codex, and more than 20 other agents.项目地址: https://gitcode.com/GitHub_Trending/ag/agentsview本篇围绕 S3 Provider Rules 展开,讲解 AgentsView 如何在s3://对象存储根上发现、去重与解析单文件会话对象,以及为 Claude、Codex、Cursor 等 agent 接入 S3 摄入时必须遵守的实现契约。读完后,你将掌握 S3Provider 接口的完整方法面、DefaultS3Provider 的适用边界、会话身份命名规则,以及从发现(discovery)到同步分发(sync dispatch)的整条调用链,并知道如何为自定义 agent 正确地打开S3 能力。适用场景:S3 摄入不是万能的AgentsView 的 S3 摄入只面向单文件会话对象,且对象必须位于如下布局之下:s3://bucket/.../machine/raw/agent/...其中agent路径段必须是该 provider 的AgentType字符串——引擎正是靠这个路径段加上Source.S3Discovery能力位,决定哪个对象属于哪个 agent。这一点在 docs/configuration.md 的 S3-Compatible Session Sources 一节有面向操作者的配置说明,而 docs/agents/s3-providers.md 则是面向实现者的契约。明确不适合 S3 摄入的情形包括:多文件容器、SQLite 存储,以及无法从单个对象路径推导出会话名的 agent。这些情况不应通过扩展 S3 路径来处理,而应走 SSH 远程同步或 PostgreSQL 等其他机制。从源码结构看,这个单文件、可命名的约束贯穿全链路:s3Client 构建传输客户端,s3PrefixScan列出对象,同步引擎把对象拉取到临时文件、交给既有 per-agent 解析器,再删除临时文件——全程不建立持久的本地镜像。必备实现面:四条硬性要求文档把新 agent 接入 S3 的工作面收敛为四条,全部可在仓库中找到对应实现:实现parser.S3Provider接口。接口定义在 internal/parser/s3_provider.go,包含五个方法:type S3Provider interface { S3Scanner() S3SessionScanner S3SessionID(uri string) string S3TempRelPath(objectPath string) (string, error) S3StatSession(uri string) (S3Object, error) S3PostFetchHydrate(tempDir, tempPath, configuredRoot, objectURI string) error }S3Scanner返回共享扫描配置,提供 Keep/Project 谓词;S3SessionID从对象 URI 推导持久会话 ID;S3TempRelPath把对象路径映射为临时物化目录内的相对路径;S3StatSession返回对象元数据(供增量跳过检查);S3PostFetchHydrate在拉取完成后对临时文件做 provider 专属的水合(hydrate)。在工厂和构造出的 provider 上都将Source.S3Discovery设为CapabilitySupported。启动迁移会拒绝声明了能力却未实现接口的 provider——查找逻辑 S3ProviderFor 正是这样双重校验的:先查能力位,再对factory.NewProvider(ProviderConfig{})做.(S3Provider)断言,断言失败会写入s3ProviderNone{}哨兵缓存,避免反复重试。把Discover/DiscoverEach中的s3://根路由到s3PrefixScan(root, scanner),确保 provider 侧发现与引擎侧分发使用同一套 keep/project 规则。共享扫描体 s3PrefixScan 列出根下全部对象,用s3MachineFromRoot从.../machine/raw/provider布局中推导来源机器,再对每个对象依次执行 Keep 过滤、Sidecar 元数据折叠、Project 推导,产出DiscoveredFile。在WatchPlan中跳过s3://根。对象存储不是本地可监视目录树,s3://源由初始同步、手动同步和周期性目录扫描拾取,不参与 fsnotify。默认实现与自定义实现的边界当 agent 符合常见布局时,应内嵌DefaultS3Provider,而不是自写逻辑。DefaultS3Provider 只有三个字段:type DefaultS3Provider struct { Agent AgentType IDPrefix string Extensions []string }它封装的规则(见 S3Scanner 与 S3SessionID):只保留文件名以声明扩展名结尾的对象(匹配时大小写不敏感,且要求至少两个路径段);项目取配置根下的第一个路径段;会话 ID 为IDPrefix加文件名去扩展名后的 stem;临时物化路径剥离raw/agent段(见 s3TempRelPathAfterRawAgent,并经sanitizeS3TempRelParts拒绝空段、.、..、含/或\的不安全对象名,防止路径逃逸);不做 sidecar 折叠,也不做 post-fetch hydrate。一旦上述任何一条规则不成立,就应为该 agent 编写专门的agent_s3.go。当前的三个自定义实现及其原因(与文档中的表格一致):Agent无法仅用默认实现的原因ClaudeSidecar 折叠(工具结果旁路对象)、subagent 路径、transcript 保留规则Codexrollout-*.jsonl保留规则、codex:UUID 会话 ID、sessions/archived 路径改写、父会话与session_index定位;此外 TraeX 共享同一 provider 类型,绝不能为其启用 S3Cursor同时采集project/id.{jsonl,txt}与本地agent-transcripts布局(含父会话的subagents目录);仅对本地布局解码编码后的项目目录;跨多个配置根按来源机器对同 stem 会话去重,优先顺序为本会话自己的嵌套/平铺对象 其他会话subagents目录中的副本 .jsonl 嵌套 平铺 字典序路径各实现的源码位置:internal/parser/claude_s3.go、internal/parser/codex_s3.go、internal/parser/cursor_s3.go。其中几个细节值得注意:Claude 的 sidecar 折叠:claudeS3SidecarRoots 为每个 transcript 定位tool-results前缀(subagent 还要加上父会话的前缀),这些对象的大小、修改时间与指纹会折叠进会话的新鲜度身份——因为工具结果可能在不改 JSONL 的前提下改变解析内容。Codex 的根隔离:CodexS3SessionUUIDFromFilename 从文件名提取 UUID 并加codex:前缀;而 FindCodexS3ParentSessionURI 在定位父 rollout 时只在同一配置根内列举元数据,优先非archived_sessions路径的匹配——这解释了文档配置中Codex 发现只导入配置根加尾部斜杠下的 rollout 文件,raw/codex-backup这类兄弟前缀会被忽略的行为。Cursor 的去重排序:preferCursorS3Transcripts 以{machine, stem}为键保留每个会话的一个对象,而 cursorS3LayoutRank 把对象分类为 subagent/flat/nested 三档后再按.jsonl、嵌套优先、字典序决胜。文档同时划定了通用传输层的边界:internal/parser/s3source.go 保持纯通用传输——client、list、fetch、stat 与s3PrefixScan,agent 策略不放在这里。身份规则:两个对象共用一个 ID 会互相覆盖S3SessionID是引擎在加上来源机器前缀之前的持久会话键。internal/sync/s3.go中的 s3SessionIDPrefix 以machine~形式生成前缀,因此完整存储键形如machine~S3SessionID。由此导出四条身份纪律:只保留该 agent 的真实 transcript 路径。Claude 的 keepClaudeS3Session 是范例:顶层project/uuid.jsonl(排除agent-开头名称与任何subagents路径),或.../subagents/.../agent-*.jsonl两种形态之一。同 stem 的文件对只保留一个。若.jsonl与.txt(或其他成对格式)共享 stem,保留本地解析器偏好的那个格式。Cursor 的.jsonl优先正是这一条的落地。ID 校验沿用本地 provider 已有的规则。例如 cursorS3TranscriptName 用IsValidSessionID校验 stem,与本地发现路径共用同一校验器。不要发明绕过 scanner 的第二套 discover 包装器。额外的后处理(优先.jsonl、折叠 sidecar)应放在 scanner 旁边,而不是另起一条发现管线。测试:用具体对象 URI 保护 keep 与身份契约文档要求测试以具体对象 URI为素材,覆盖四类断言:一个已记录的 harvest 对象能被发现;一个同扩展名的垃圾对象不能被发现;同 stem 的文件对只产出一个会话 ID 和一个发现的 source;共享 provider 类型的 fork 在未拥有命名空间时保持 S3 关闭。仓库中 internal/parser/s3_discovery_test.go、claude_s3_test.go、codex_s3_test.go、cursor_s3_test.go 即这些契约的测试载体。TraeX 的共享类型不启用 S3约束在源码中同样有硬证据:codexProvider.S3Scanner 与 S3SessionID 开头都先检查p.spec.agent ! AgentCodex,不匹配时返回空扫描器/空 ID。同步分发:能力位之后只有一条路能力位设置好之后,internal/sync/s3.go与internal/sync/s3_source.go通过 S3ProviderFor 分发——不要为新的 agent 再加一处switch file.Agent。核心处理函数 Engine.processS3Session 展示了这条路的实际形状:按 agent 计算持久会话 ID 并做源未变化跳过检查(基于Size、LastModified与对象指纹——s3ObjectFingerprint会收集 ETag、version ID 与各类校验和,见 internal/parser/s3source.go);通过safeS3TempRelPath得到安全的临时相对路径,再获取保留租约;fetchS3Object流式拉取对象到avs3-*临时目录(对象字节直写磁盘,大会话不必整块驻留内存);按 agent 执行水合:claude 格式折叠 tool-results,Codex 定位父 rollout 与session_index.jsonl(见 hydrateS3CodexSessionIndex),其余 agent 回调S3PostFetchHydrate;用os.Chtimes把临时文件 mtime 还原为源对象的修改时间,再以 tempDir 为根调用普通 provider 的Parse(parseMaterializedS3Source);解析结果中把File.Path改写回真实的s3://URI,并应用machine~前缀后落库,临时文件随即删除。操作者侧配置速览实现契约的另一面是操作者配置,完整说明见 docs/configuration.md 的 S3-Compatible Session Sources 一节,典型配置如下:[agents.claude] dirs [ ~/.claude/projects, s3://agent-archive/laptop/raw/claude, ] [agents.codex] dirs [ ~/.codex/sessions, s3://agent-archive/laptop/raw/codex, ]凭据与端点使用标准 AWS 风格环境变量:AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY、AWS_REGION、AWS_S3_ENDPOINT(对 MinIO、阿里云 OSS、Cloudflare R2 等 S3 兼容服务必设)。端点安全策略在 s3EndpointConfig 中实现:http://端点仅对回环主机放行,非回环 HTTP 端点需显式设置AGENTSVIEW_ALLOW_INSECURE_S3_ENDPOINTtrue,且仅限可信内网——因为会话 transcript 将无 TLS 传输。预期对象布局(与实现契约中的machine/raw/agent一一对应):s3://bucket/.../machine/raw/claude/project/uuid.jsonl s3://bucket/.../machine/raw/claude/project/subagents/.../agent-*.jsonl s3://bucket/.../machine/raw/codex/2026/06/24/rollout-*.jsonl s3://bucket/.../machine/raw/cursor/project/uuid.jsonl s3://bucket/.../machine/raw/icodemate/project/session.jsonl机器名取自raw之前的路径段(s3MachineFromRoot 的实现);若不存在这样的段,会话回退到本机 AgentsView 的机器标签。小结S3 摄入契约的核心可以浓缩为三句话:布局决定归属(agent段 能力位)、身份决定去重(S3SessionID 机器前缀,同 ID 互相覆盖)、分发只走一处(s3PrefixScan发现、S3ProviderFor调度,禁止新增 agent 级 switch)。满足这三点后,新 agent 的对象存储摄入即可复用引擎的增量跳过、指纹比较与临时物化解析,而不需要改动同步主链路。【免费下载链接】agentsviewLocal-first session search, analytics, insights, and token use statistics for coding agents, supporting Claude Code, Codex, and more than 20 other agents.项目地址: https://gitcode.com/GitHub_Trending/ag/agentsview创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
的完整启动流程全解)
