---
name: knowledge-workspace-policy-and-shared-foundations
description: >
  覆盖 Blade 跨 Agent、工具、扩展和交互表面的配置、Workspace Trust、Session 资源快照、共享 TypeBox 合约、容量准入与关闭策略。
  使用时机：修改全局策略、排查多 workspace 串扰、增加共享配置或 API 字段、处理资源耗尽、背压与进程回收。
  不包含：具体工具实现见 tool-and-automation-platform，Provider 重试与熔断见 model-and-provider-runtime，Session 事件持久化见 session-state-and-context。
  关键词：ConfigManager, WorkspaceTrustService, SessionAgentResources, RuntimeSchema, admission, egress, shutdown, workspace isolation。
---

## Module Structure

该域集中描述会跨越 CLI、Web、ACP、Agent Runtime、工具和扩展系统的基础策略；其共同约束是以 source project 建立身份，在进入 Session 前完成信任过滤和配置解析，再把可变进程资源冻结为 Session 私有视图。

### Directory Layout
- `packages/cli/src/config/` — 配置加载、归一化、字段持久化路由和权限规则
- `packages/cli/src/security/` — canonical workspace identity 与 Folder Trust 决策
- `packages/cli/src/agent/resources/` — workspace registry、模型资源和 Session 快照
- `packages/cli/src/api/` — Server/Web 共用的请求、响应和事件合约
- `packages/cli/src/schema/` — TypeBox runtime 解析与错误归一化
- `packages/cli/src/tools/execution/` — 权限、批内 gate 和进程级工具准入
- `packages/cli/src/utils/BoundedSerialEgress.ts` — 多表面共用的有界串行输出
- `packages/cli/src/services/GracefulShutdown.ts` — 进程级关闭编排

### Decision Entry
- `ConfigManager.initialize()` in `packages/cli/src/config/ConfigManager.ts` — 启动配置、信任过滤和显式运行时覆盖入口
- `WorkspaceTrustService.getStatus()` in `packages/cli/src/security/WorkspaceTrustService.ts` — 项目资源是否可见的身份决策入口
- `SessionRuntime.create()` in `packages/cli/src/agent/runtime/SessionRuntime.ts` — 将 source project 配置与资源冻结到 Session
- `Runtime()` in `packages/cli/src/schema/index.ts` — 共享 schema 的运行时解析入口
- `ConcurrencyScheduler.schedule()` in `packages/cli/src/tools/execution/ConcurrencyScheduler.ts` — 工具进程级公平准入入口
- `BoundedSerialEgress.offer()` in `packages/cli/src/utils/BoundedSerialEgress.ts` — Web、ACP 与 Headless 输出背压入口

## Branching Table

| 决策维度 | 主路径 | 受限或替代路径 |
|----------|--------|----------------|
| 配置身份 | 启动 workspace 可复用 Store 投影 | 其他 workspace 必须从用户层和目标项目层重建，不能继承启动项目私有层 |
| 项目来源 | `trusted` 项目可加载配置、插件、规则和可执行资源 | `untrusted` 或 trust store 错误时忽略可放宽执行面的项目来源 |
| 资源时点 | workspace registry 可刷新并参与后续 Session 创建 | 活动 Session 使用深复制快照，不接受 registry 热更新 |
| 边界数据 | schema 解析成功后应用默认值并清理未知字段 | 输入验证失败映射为 4xx，输出投影失败则阻止泄漏内部字段 |
| 容量状态 | 有空位时直接取得 permit 或 lease | 等待时受数量、字节和超时约束；满载时返回 typed capacity failure |
| 输出状态 | 单写者按接纳顺序排空并支持 high-water-mark flush | overflow、写超时或 committed seq 回退会关闭对应输出通道 |
| 生命周期 | owner 活跃时持有 Session、Browser、进程和排队项 | cancel/dispose/shutdown 逐层撤销等待者并等待实际资源回收 |

## Affected Scope
- `packages/cli/src/agent/runtime/` — Session 创建、资源快照、任务准入和驻留生命周期
- `packages/cli/src/tools/` — 工具 schema、权限决策、并发 gate 和外部副作用边界
- `packages/cli/src/server/` — Hono API 校验、SSE 顺序、容量错误映射和关闭清理
- `packages/cli/src/acp/` — 多 cwd Session 隔离、不可驱逐驻留与有界更新输出
- `packages/cli/src/commands/` — CLI 覆盖、Headless 输出背压和进程级启动/关闭
- `packages/cli/src/plugins/` — 可信项目来源、配置收紧和 workspace registry 刷新
- `packages/cli/src/browser/` — HTTP(S) 来源安全、Context 容量和串行页面操作
- `packages/cli/web/src/` — 共享 API schema 消费、workspace 模型投影和容量状态展示

## Gotchas
- 进程 Store 只代表启动 workspace 的 UI 投影；为 Web 多项目、ACP 多 cwd 或 Task source project 创建 Runtime 时直接读取 Store 会泄漏模型、权限、MCP、LSP 或环境配置 (`packages/cli/src/config/ConfigManager.ts`, `packages/cli/src/agent/runtime/SessionRuntime.ts`, `git:3549bb1e`)
- `projectRoot` 是配置和资源身份，`workspaceRoot` 是文件副作用位置；worktree 只替换后者，不能据此重新选择插件、Provider 或项目规则 (`packages/cli/src/agent/runtime/SessionRuntime.ts`, `docs/reference/workspace-agent-resources.md`)
- Workspace Trust 变更不是单纯更新一个布尔值；当前启动配置必须先重载，随后断开 MCP、清空 workspace registry 并重新解析资源 (`packages/cli/src/security/reloadWorkspaceTrust.ts`)
- 新增跨表面字段若只改 TypeScript 接口会留下不一致边界；通常还要同步默认值、配置校验/持久化路由、共享 API schema、公开投影和客户端解析 (`packages/cli/src/config/types.ts`, `packages/cli/src/config/defaults.ts`, `packages/cli/src/api/schemas.ts`)
- 容量拒绝是可恢复协议的一部分，不应被折叠成通用 500；Session、Task、Tool、Provider 和 Browser 各自携带稳定的 resource/reason/limit 语义 (`packages/cli/src/context/taskFailure.ts`, `packages/cli/src/server/error.ts`)
- 输出队列失败采用 fail-closed；继续向已经 overflow 或 timeout 的通道写入会破坏顺序与内存上限，因此调用方必须关闭对应订阅或会话，而不是重试同一 writer (`packages/cli/src/utils/BoundedSerialEgress.ts`)

## Architecture
- 跨域策略按“磁盘来源 → 信任过滤 → workspace 解析 → Session 快照 → 执行时准入 → 有界表面输出”串联，任何中间层都不应绕回进程全局可变状态 (`packages/cli/src/config/ConfigManager.ts`, `packages/cli/src/agent/runtime/SessionRuntime.ts`)
- 配置、资源目录与运行时状态拥有不同所有者：`ConfigManager` 读盘，`ConfigService` 写盘，Zustand Store 做启动表面投影，SessionRuntime 持有执行快照 (`packages/cli/src/config/ConfigManager.ts`, `packages/cli/src/config/ConfigService.ts`, `packages/cli/src/store/vanilla.ts`)
- TypeBox schema 同时承担静态类型、HTTP 边界验证和公开字段投影，Web 通过 `@api` alias 直接消费同一源码合约 (`packages/cli/src/schema/index.ts`, `packages/cli/web/vite.config.ts`)

## Decisions
- 项目采用 source-project 级隔离而非进程 cwd 级隔离，因为同一 Serve/ACP 进程必须并发承载多个目录且不能共享可变 registry 或 endpoint (`docs/reference/workspace-agent-resources.md`, `docs/reference/workspace-model-resources.md`)
- 从 Zod 迁移到 TypeBox 是为同时保留原生 JSON Schema 与运行时解析能力，工具声明和 Server/Web 合约由同一 schema 体系生成 (`packages/cli/src/schema/index.ts`, `git:311ba368`)
- 资源限制同时约束 active 数量、pending 数量和 retained bytes；只限制并发数仍会让等待队列与输出缓冲无界增长 (`packages/cli/src/agent/runtime/TaskRunScheduler.ts`, `packages/cli/src/utils/BoundedSerialEgress.ts`, `git:1af43232`)

## Branching Behavior
- 不可信项目只能让 Hook 更严格，例如设置 `disableAllHooks=true`；模型、环境、权限放宽和项目扩展均不进入 Runtime (`packages/cli/src/config/ConfigManager.ts`)
- Session 快照创建后，配置、插件或规则变更只影响后续 Session；恢复路径通过 digest 和引用校验旧快照语义，不能静默采用新内容 (`packages/cli/src/agent/resources/WorkspaceAgentResources.ts`, `packages/cli/src/agent/runtime/SessionRuntime.ts`)
- 有空闲执行槽时，Task 和 Provider 的 pending-byte 预算不参与拒绝；只有请求必须排队时才对 retained footprint 计费 (`packages/cli/src/agent/runtime/TaskRunScheduler.ts`, `packages/cli/src/services/pi/providerRequestAdmission.ts`)
- Web Session 驻留允许驱逐可回收的 idle Web Runtime，ACP 驻留不做隐式驱逐并要求宿主显式关闭 (`packages/cli/src/agent/runtime/SessionRuntimeResidency.ts`)
- SSE 初始化阶段先缓冲 live 事件；完成 replay 后只补发高于 replay 水位的 committed 事件，并丢弃该窗口内无法可靠排序的 ephemeral delta (`packages/cli/src/server/OrderedSseEgress.ts`)

## Child Knowledge Nodes
- `./layered-configuration-and-runtime-settings/SKILL.md` — 使用时机：调整配置层级、字段写入位置、workspace 运行时设置或 Web 配置同步
- `./permissions-and-workspace-trust/SKILL.md` — 使用时机：修改权限模式、allow/ask/deny、审批作用域、Folder/Hook Trust 或网络安全
- `./workspace-resource-snapshots-and-project-instructions/SKILL.md` — 使用时机：修改 Agent/模型资源隔离、Session 快照、通信风格或路径条件项目规则
- `./shared-api-and-runtime-schemas/SKILL.md` — 使用时机：新增跨 Server/Web 数据字段、TypeBox schema、默认值或公开投影
- `./capacity-lifecycle-and-egress/SKILL.md` — 使用时机：修改 Session/Task/Tool/Provider/Browser 容量、公平队列、输出背压或资源回收
- `./runtime-state-bootstrap-and-observability/SKILL.md` — 使用时机：修改 cwd/project root 启动状态、共享 Store、日志、运行版本、Session ID 或项目注册