Knowledge Runtime State Bootstrap And Observability

Module Structure

该组件提供各运行表面共享的进程级基础状态与观测入口；它区分启动目录、当前工作区和稳定项目根，并把 UI 状态、日志、环境探测及项目发现收敛到可被 Agent、CLI、Server、工具和扩展复用的 API。

Directory Layout

• packages/cli/src/bootstrap/state.ts — 惰性初始化的 cwd、originalCwd 与 projectRoot 三态
• packages/cli/src/store/ — React 与非 React 共用的 Zustand Store、切片、类型和细粒度选择器
• packages/cli/src/logging/ — 分类 JSONL 日志与独立流式调试日志
• packages/cli/src/utils/cwd.ts — 基于 AsyncLocalStorage 的并发 cwd 覆写
• packages/cli/src/utils/environment.ts — 项目根发现、环境提示和目录概览
• packages/cli/src/utils/packageInfo.ts — 源码与打包布局兼容的运行时包信息
• packages/cli/src/utils/sessionId.ts — 可安全用于存储路径的 Session ID
• packages/cli/src/services/DirectoryPicker.ts — macOS、Windows 与 Linux 原生目录选择
• packages/cli/src/services/ProjectRegistry.ts — 规范化项目路径的持久绑定注册表

Key Entry Points

• getCwd() / runWithCwdOverride() — 获取当前执行上下文的 workspace，或为异步调用链临时覆写
• vanillaStore / useBladeStore() / ensureStoreInitialized() — 共享状态实例、React 订阅与幂等配置初始化
• createLogger() / setLoggerSessionId() / streamDebug() — 分类日志、会话日志路由与流式专项诊断
• getEnvironmentContext() / getVersion() / createSessionId() — 构造环境上下文、读取运行版本和生成存储安全标识
• NativeDirectoryPicker.pick() / ProjectRegistry.list() — 选择本机目录并读取规范化项目集合

API Surface

Workspace Location

• getCwd() — 优先返回当前 AsyncLocalStorage 覆写，否则返回进程级 cwd
• runWithCwdOverride(cwd, fn) — 在同步及后续异步调用链内隔离 workspace
• getOriginalCwd() — 返回 CLI 被调用时的原始目录，用于解析用户传入的相对路径
• getProjectRoot() — 返回启动后保持稳定的项目标识根
• findProjectRoot(startDir) / setCwd(newPath, relativeTo?) — 发现工作区根并更新规范化的全局 cwd

Shared Store

• useBladeStore(selector) — React 对共享 Vanilla Store 的细粒度订阅入口
• getState() — Agent、服务与命令读取当前 Store 快照
• sessionActions() / appActions() / configActions() — 面向不同状态域的动作入口
• ensureStoreInitialized() — 以共享 Promise 合并并发配置初始化
• useCurrentStreamingBuffer() — 以浅比较订阅流式行缓冲、尾部、计数和版本

Observability

• createLogger(category, options?) — 创建分类日志器，文件输出与终端调试过滤相互独立
• Logger.setGlobalDebug(config) — 动态设置全局终端日志开关或分类过滤
• setLoggerSessionId(sessionId) — 切换后续 JSONL 日志的文件名
• streamDebug(source, message, data?) — 向独立流式诊断文件追加记录且不向调用方抛错
• getEnvironmentContext(options?) — 组装系统、Git、脚本和目录信息供系统提示使用

Runtime Identity And Project Discovery

• getPackageInfo() / getVersion() — 从运行时邻近 package.json 读取并缓存实际发布信息
• createSessionId(prefix?, size?) — 校验前缀后生成可用于文件名的 ID
• NativeDirectoryPicker.pick() — 跨平台打开至多一个并发原生目录选择器
• ProjectRegistry.bind() / list() / unbind() — 规范化、持久化并查询项目绑定

Usage Examples

CLI 启动时固定项目根

const invocationCwd = process.cwd();
const detectedRoot = findProjectRoot(invocationCwd);
setCwd(detectedRoot);
setProjectRoot(getCwd());

启动 Server 前确保共享 Store 可用

await ensureStoreInitialized();
const server = await BladeServer.listenAsync(opts);

TUI 初始化完成后绑定会话日志

const state = getState();
const sessionId = state.session.sessionId;
setLoggerSessionId(sessionId);

Gotchas

• originalCwd、cwd 与 projectRoot 不能互换：CLI 相对参数以调用目录解析，运行工具使用可变 cwd，历史、Skill 和 Session 等项目身份使用启动后固定的 projectRoot (packages/cli/src/bootstrap/state.ts, packages/cli/src/blade.tsx, packages/cli/src/cli/settings.ts, packages/cli/src/mcp/loadMcpConfig.ts)
• CLI 必须先执行 findProjectRoot()、setCwd() 和 setProjectRoot() 再启动依赖 workspace 的流程，否则配置、信任与资源发现会以调用子目录为根 (packages/cli/src/blade.tsx, packages/cli/src/utils/environment.ts)
• 并发 Session 或子代理不能用全局 setCwd() 做临时切换；应使用 runWithCwdOverride()，其 AsyncLocalStorage 覆写会沿异步调用链传播且不污染其他执行上下文 (packages/cli/src/utils/cwd.ts, git:4543542b)
• setCwd() 解析相对路径时默认基于真实 process.cwd() 而不是当前 AsyncLocalStorage 覆写；在隔离上下文内传相对路径必须显式提供 relativeTo (packages/cli/src/utils/environment.ts, packages/cli/src/utils/cwd.ts)
• Store 是否初始化仅以 config.config !== null 判断；CLI、Server、ACP 和 Hook 等非 React 入口在读取配置前都必须等待 ensureStoreInitialized()，并发调用会共享同一个初始化 Promise (packages/cli/src/store/vanilla.ts, packages/cli/src/commands/serve.ts, packages/cli/src/acp/BladeAgent.ts)
• resetSession() 只重置 Zustand 内的 Session 字段并保留 sessionId，不会隐式清空模块级 conversationProjection；切换事件流时还要显式调用 resetConversationProjection() (packages/cli/src/store/slices/sessionSlice.ts)
• Logger 的 debug 开关只控制终端输出，所有级别仍同步追加到 JSONL；不要通过关闭 debug 假设磁盘日志已停用 (packages/cli/src/logging/Logger.ts)
• 日志文件路由使用进程级 currentSessionId 而非异步上下文；TUI 绑定 Session 前的记录进入 blade-default.jsonl，该机制也不能区分并发 Server Session (packages/cli/src/logging/Logger.ts, packages/cli/src/ui/App.tsx)
• 日志目录初始化只尝试一次；权限或创建失败后会缓存不可用状态，当前进程内即使外部修复目录也不会自动重试 (packages/cli/src/logging/Logger.ts)
• streamDebug() 不受 Logger.setGlobalDebug() 控制，并会在每个 storage root 的首次调用时重写 stream-debug.log；它是临时专项诊断通道，不是普通分类日志 (packages/cli/src/logging/StreamDebugLogger.ts, packages/cli/src/ui/utils/loopEventHandler.ts)
• ProjectRegistry 遇到缺失、损坏或版本不匹配的注册表会按空集合继续，并始终临时注入当前项目；因此列表只剩当前项目不代表绑定从未存在 (packages/cli/src/services/ProjectRegistry.ts, packages/cli/tests/unit/services/project-registry.test.ts)
• 原生目录选择服务本身不校验请求来源，只有 Server 路由拒绝非本机 Origin；新增调用表面时必须复用同等访问边界 (packages/cli/src/services/DirectoryPicker.ts, packages/cli/src/server/routes/projects.ts)
• Linux 目录选择仅在命令不存在时从 zenity 回退到 kdialog；已安装选择器返回真实错误时会立即失败，而空输出的退出码 1 被视为用户取消 (packages/cli/src/services/DirectoryPicker.ts, packages/cli/tests/unit/platform/services/directory-picker.test.ts)