knowledge-workspace-resource-snapshots-and-project-instructions

name

knowledge-workspace-resource-snapshots-and-project-instructions

description

覆盖按 source project 隔离的 Agent/模型资源、Session 不可变快照、通信风格以及静态与路径条件项目规则。 使用时机：新增 workspace 资源来源、创建或恢复 Session、处理 Task worktree、刷新插件、注入 AGENTS/CLAUDE/BLADE 规则或校验 provenance。 不包含：Folder Trust 决策实现见 permissions-and-workspace-trust，通用配置层级见 layered-configuration-and-runtime-settings。 关键词：WorkspaceAgentResources, SessionAgentResources, WorkspaceModelResources, ProjectRuleCatalog, contextualRules, projectInstructionsDigest。

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，修改同一渠道凭据仍可能影响后续请求 ()

Architecture

• 每个 canonical workspace 聚合 Subagent、Skill、Command、Plugin、CommunicationStyle 和 ProjectRule registry；插件先初始化，再把 namespaced 资源集成进同一 workspace 的各 registry (packages/cli/src/agent/resources/WorkspaceAgentResources.ts)
• Agent 资源与模型资源分开快照：前者冻结模型可见扩展，后者冻结 Provider definitions 和模型路由，两者在 SessionRuntime 创建时共同绑定 (packages/cli/src/agent/resources/WorkspaceAgentResources.ts, packages/cli/src/agent/resources/WorkspaceModelResources.ts)
• 项目规则按目录深度、同层文件优先级和路径 pattern 组成确定性目录；静态规则进入初始 system prompt，条件/深层规则在工具触达路径后增量进入下一次 Provider 请求 (packages/cli/src/agent/resources/WorkspaceProjectRules.ts, packages/cli/src/prompts/builder.ts)

Decisions

• Session 使用不可变快照而不是实时 registry，是为了让插件启停、trust revoke 和磁盘规则变化不能改变已经暴露给模型的工具与系统提示 (docs/reference/workspace-agent-resources.md)
• 项目规则持久化 provenance 而不持久化正文，在保持 transcript 有界的同时强制恢复时验证历史指令语义 (docs/reference/trusted-contextual-project-rules.md)
• 模型 catalog 只共享安全 CredentialStore，不共享 Provider definitions，允许同一进程中相同 provider/model ID 在不同项目指向不同 endpoint (packages/cli/src/agent/resources/WorkspaceModelResources.ts, packages/cli/tests/unit/services/workspace-model-resources.test.ts)

Consumer Analysis

• SessionRuntime 在创建和恢复时消费 Agent/Model 快照，并验证项目规则与通信风格 digest (packages/cli/src/agent/runtime/SessionRuntime.ts)
• 子代理与 Team Runtime 继承父快照后再次复制，保持嵌套任务资源视图稳定 (packages/cli/src/agent/subagents/, packages/cli/src/agent/teams/)
• Task、Team、Skill 和 SlashCommand 工具通过闭包绑定 Session registry，不回查全局单例 (packages/cli/src/tools/builtin/)
• 多项目 Session、模型、插件、Hook、Skill 和 suggestions 路由按请求目录获取精确 workspace 资源 (packages/cli/src/server/routes/)
• Prompt builder 与 Agent loop 分别消费静态规则和按工具路径动态加载的 contextual rules (packages/cli/src/prompts/builder.ts, packages/cli/src/agent/loop/executeLoopGenerator.ts)