Knowledge Workspace Resource Snapshots And Project Instructions

Module Structure

该组件把进程内可刷新 workspace registry 转换为 Session 私有快照，并以 source project 为资源身份、以 execution workspace 为文件操作位置。

Directory Layout

• packages/cli/src/agent/resources/WorkspaceAgentResources.ts — workspace registry 聚合、容量、刷新和 Session 快照
• packages/cli/src/agent/resources/WorkspaceModelResources.ts — 模型配置与 PiModelCatalog 的 Session 隔离
• packages/cli/src/agent/resources/WorkspaceCommunicationStyles.ts — 用户、项目和插件输出风格目录
• packages/cli/src/agent/resources/WorkspaceProjectRules.ts — 项目规则发现、优先级、路径匹配和 provenance
• packages/cli/src/prompts/projectInstructions.ts — 无 ProjectRuleCatalog 时的兼容指令加载器
• packages/cli/src/agent/runtime/SessionRuntime.ts — 快照创建、规则水合和 source/execution 路径映射
• packages/cli/src/agent/loop/executeLoopGenerator.ts — 条件规则注入与首次写入屏障

Key Entry Points

• resolveWorkspaceAgentResources() — 获取或初始化指定 workspace 的可刷新资源集合
• withWorkspaceAgentResources() — 在 active-user pin 内执行异步管理操作
• snapshotWorkspaceAgentResources() — 深复制 registry、Hook、风格和规则到 Session
• resolveWorkspaceModelResources() — 重建目标项目的模型配置和私有 catalog
• ProjectRuleCatalog.staticRules() / contextualRules() / hydrate() — 静态注入、路径触发和恢复校验

API Surface

WorkspaceAgentResources

• resolveWorkspaceAgentResources(workspaceRoot, options) — 适合短时读取；返回后通过 deferred release 解除 active pin
• withWorkspaceAgentResources(workspaceRoot, operation, options) — 在整个异步 operation 期间保持资源不可驱逐
• snapshotWorkspaceAgentResources(resources) — 生成 Session-owned registry、Hook、风格和规则快照
• resetWorkspaceAgentResources() — 递增 generation、清空缓存并释放所有 registry 单例
• getWorkspaceAgentResourceCacheStats() — 暴露 resident、in-flight 和 active-user 计数

WorkspaceModelResources

• resolveWorkspaceModelResources(projectRoot, startupConfig) — 返回深复制配置与 Session 私有 catalog
• snapshotWorkspaceModelResources(resources) — 再复制配置并以原 CredentialStore 创建新 catalog
• cloneWorkspaceModelConfig(config) — 深复制普通对象和数组，保留函数类运行时值

ProjectRuleCatalog

• list() — 仅返回规则元数据和 digest
• staticRules(sourceWorkspaceRoot, maxBytes?) — 解析 Session 初始作用域内的无条件规则
• contextualRules(sourceWorkspaceRoot, targetPaths, loadedIds, maxBytes?) — 按工具目标路径选择尚未加载的规则
• hydrate(references) — 用持久化引用重建正文并验证 ID、路径、来源和 digest
• snapshot() — 固化定义与 pattern 数组，隔离后续磁盘和 registry 变化

Usage Examples

Session 创建时冻结 Agent 资源

const resources = this.options.agentResources
  ? this.options.agentResources
  : await resolveWorkspaceAgentResources(this.projectRoot, {
      reconcilePlugins: true,
    });
this.agentResources = snapshotWorkspaceAgentResources(resources);

写入前加载路径条件规则

const projectRules = resolveInvocationRules(toolName, params);
if (projectRules?.files.length && registry.get(toolName)?.kind === 'write') {
  return {
    success: false,
    metadata: { contextualProjectRulesRequired: true },
  };
}

Gotchas

• resolveWorkspaceAgentResources() 只为当前调用短暂增加 users，并通过 setImmediate 延迟释放；管理操作跨越多个 await 且要求资源不被 LRU 驱逐时必须使用 withWorkspaceAgentResources() (packages/cli/src/agent/resources/WorkspaceAgentResources.ts)
• workspace registry 是可刷新对象，不能直接暴露给活动模型；只有 snapshotWorkspaceAgentResources() 深复制后的 registry、Hook 和目录才保证一个 Session 内工具描述与执行查找一致 (packages/cli/src/agent/resources/WorkspaceAgentResources.ts, packages/cli/tests/unit/services/workspace-agent-resources.test.ts)
• idle registry 上限为 32，初始化中或 active-user entry 的硬上限为 64；全部 entry 被 pin 时新 workspace 会在初始化前抛 WorkspaceAgentResourceCapacityError (packages/cli/src/agent/resources/WorkspaceAgentResources.ts, git:2db1b230)
• 初始化任一 registry 或插件集成失败时，已创建的 Subagent/Skill/Command/Plugin 单例必须全部 release；保留半初始化 generation 会污染下一次解析 (packages/cli/src/agent/resources/WorkspaceAgentResources.ts)
• resetWorkspaceAgentResources() 通过 generation 让迟到的初始化结果自毁；仅清空 Map 而不检查 generation 会让并发旧 Promise 重新写回已撤销资源 (packages/cli/src/agent/resources/WorkspaceAgentResources.ts)
• Task worktree 的 workspaceRoot 不是资源根；模型、插件、Hook、项目规则和默认配置继续来自 original source projectRoot，条件规则路径再从 worktree 映射回 source project (packages/cli/src/agent/runtime/SessionRuntime.ts, docs/reference/workspace-agent-resources.md)
• 项目规则只有 Folder Trust 为 trusted 才发现；不可信项目返回空 catalog，而不是降级读取根 AGENTS.md (packages/cli/src/agent/resources/WorkspaceProjectRules.ts)
• 同一目录存在 AGENTS.override.md 时会完全跳过 AGENTS.md；它不是追加层，误把二者都注入会产生相互冲突的指令 (packages/cli/src/agent/resources/WorkspaceProjectRules.ts)
• 路径条件规则首次命中 Write/Edit/ApplyPatch 时会在任何副作用前返回 validation error，注入规则后要求模型下一轮重提写入；不能在当前调用中继续执行原参数 (packages/cli/src/agent/loop/executeLoopGenerator.ts)
• contextual rule 正文不写入 transcript，只持久化 reference 和 digest；恢复时 hydrate() 发现内容、路径或来源漂移会 fail closed，避免静默改变历史 Session 的指令 (packages/cli/src/agent/resources/WorkspaceProjectRules.ts, packages/cli/src/agent/runtime/SessionRuntime.ts)
• 规则预算按从最具体、最高优先级一端反向保留完整文件，超预算文件会整体跳过而不是截断；依赖文件前半段被保留的逻辑会得到错误结果 (packages/cli/src/agent/resources/WorkspaceProjectRules.ts)
• Session 模型 catalog 与配置是私有副本，但 CredentialStore 有意共享；修改全局 catalog 或磁盘 endpoint 不影响活动 Session，修改同一渠道凭据仍可能影响后续请求 (packages/cli/src/agent/resources/WorkspaceModelResources.ts)
• 自定义通信风格对单文件、prompt、总字节、目录深度和隐藏控制字符都有独立限制；单个坏文件只记 warning 并跳过，但总目录超限会使整个解析失败 (packages/cli/src/agent/resources/WorkspaceCommunicationStyles.ts)