echovic 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()inpackages/cli/src/config/ConfigManager.ts— 启动配置、信任过滤和显式运行时覆盖入口WorkspaceTrustService.getStatus()inpackages/cli/src/security/WorkspaceTrustService.ts— 项目资源是否可见的身份决策入口SessionRuntime.create()inpackages/cli/src/agent/runtime/SessionRuntime.ts— 将 source project 配置与资源冻结到 SessionRuntime()inpackages/cli/src/schema/index.ts— 共享 schema 的运行时解析入口ConcurrencyScheduler.schedule()inpackages/cli/src/tools/execution/ConcurrencyScheduler.ts— 工具进程级公平准入入口BoundedSerialEgress.offer()inpackages/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 通过
@apialias 直接消费同一源码合约 (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 或项目注册