---
name: global-mode
status: REVIEW
change-type: single
created: 2026-04-15 15:57:05
reference: null
archived: '2026-04-16T15:57:08'
---
# global-mode

## Problem Statement

sprout 仅能在含 `.sprout/` 的项目目录内使用——`discover_project_root()` 向上搜索 `.sprout/`，找不到则直接报错。所有 asset 路径被沙箱限制在 project root 内。这使 sprout 无法作为个人工作流工具使用：用户需要在任意位置创建临时目录、笔记、工作区等项目无关的文件结构，当前架构无法支持。

## Proposed Solution

### Approach

新增 `--global` / `-g` CLI 标志，切换到全局模式。全局模式使用独立的注册表（`~/.config/sprout/`）和独立的配置，与项目级模式完全隔离、互不影响。

核心设计：两套注册表，两种沙箱语义，一个 CLI。`-g` 是编译时决策——运行时只走一条代码路径，不需要优先级合并逻辑。

关键约束：
- 项目级代码路径**零侵入**：所有现有函数签名和行为不变
- 全局模式允许绝对路径 asset，无沙箱边界限制
- 全局 manifest 新增 `root` 字段（可选），声明 asset path 的基座
- 全局模式注入新内置变量（`home`, `cwd`, `platform`），替代 `project.*`

### Key Change

**Feat A: 全局注册表加载** — 新增 `GLOBAL_SPROUT_DIR`、`discover_global_dir()`、`load_global_registry()`，`-g` 触发全局加载路径，项目级逻辑不动。

**Feat B: 全局配置文件** — `~/.config/sprout/config.yaml` 支持完整 `ProjectConfig` 格式（conflict 策略等），全局命令继承全局默认配置。

**Feat C: CommandSpec 扩展** — `CommandSpec` 增加 `root: str | None` 字段；全局 manifest 可声明 `root`（支持模板变量），项目级 manifest 忽略此字段。

**Feat D: 全局变量上下文** — 全局模式用 `home`/`cwd`/`platform` 替代 `project.root`/`project.root_name`；`build_variable_context` 接受模式参数切换变量集。

**Feat E: 绝对路径与沙箱改造** — 全局模式下 asset path 允许渲染为绝对路径；`_ensure_within_root` 在全局模式下使用 resolved `root`（或 cwd fallback）做沙箱检查；`build_generation_plan` 接受 `sandbox_root` 参数替代硬编码 `project_root`。

**Feat F: CLI 全局标志** — `new` 和 `list` 子命令增加 `-g/--global`；`init` 增加 `--global` 初始化全局目录；`doctor` 增加 `--global` 检查全局注册表。

**Feat G: 全局 scaffold** — `init --global` 创建 `~/.config/sprout/` 基础结构。

### Scope Summary

| File | Change |
|------|--------|
| `sprout/models.py` | `CommandSpec` 增加 `root` 字段；新增 `GlobalConfig` 或复用 `ProjectConfig` |
| `sprout/core.py` | 新增 `GLOBAL_SPROUT_DIR`、`discover_global_dir()`、`load_global_registry()`；改造 `build_generation_plan` 接受 `sandbox_root`；`build_variable_context` 接受模式参数；`_ensure_within_root` 参数化 |
| `sprout/cli.py` | `new`/`list`/`init`/`doctor` 增加 `-g/--global` 标志；新增 `_run_new_global()` 或在 `_run_new` 中分派 |
| `sprout/scaffold.py` | 新增 `initialize_global_workspace()` |
| `tests/` | 新增全局模式相关测试 |

### Design Reference

→ 详细技术设计见 [design.md](./design.md)