跳到主要内容
版本：2.6

配置参考

Shine 将全局运行时状态保存在 ~/.shine/。首次需要配置时会创建 ~/.shine/config.toml。 配置与清单文件的替换（包括 Windows）不会在重命名暂存文件前删除旧文件；重命名失败时保留原文件。

在 Unix 上，若 SUDO_USER 指定了发起 sudo 的用户，Shine 会通过系统账户数据库解析其主目录， 包括 macOS 的 Directory Services。依赖主目录的配置和路径展开会使用该用户的主目录，而非 sudo 设置的 root HOME。

交互式生命周期 Plan 的人工确认可仅授权本次列出的外部代码，不保存 trust。自动化与 --yes 必须已有 grant。Shell live 始终要求 Development trust；显式 --run-generators 检查也须已有 grant。

常用全局字段​

presets_dir = "~/dotfiles/shine-presets"
# 外部 Shell 预设默认使用 snapshot；预设开发时才设为 live
external_shell_mode = "live"
presets_overlay_git = "https://example.com/team/shine-overlay.git"
presets_overlay_git_branch = "main"
app_default_dest_root = "~/.config"
sync_terminal_theme = true
gpg_recipients = ["user@example.com", "team-backup@example.com"]

secret_backend = "age"
age_recipients = ["age1tag1qexample...", "age1qteammate..."]
age_identity = "~/.shine/age/identity.txt"
age_identities = ["C:/Users/<user>/AppData/Local/age-plugin-phone/identity-....txt"]

[env]
HTTP_PROXY_PORT = "6152"
SOCKS5_PROXY_PORT = "6153"
PROXY_HOST = "127.0.0.1"
PROXY_NO_PROXY = "localhost,127.0.0.1,::1"
IMAGE_QUALITY = "80"
IMAGE_MAX_WIDTH = "1920"
IMAGE_MAX_HEIGHT = "1080"
MY_API_TOKEN = { value = "<令牌>", description = "内部 API 的访问令牌" }

[[env_proxy]]
command = "gh"
with = ["GH_TOKEN"]
# 省略时为 true；设为 false 时 shim 不解密也不注入值
enabled = false
字段作用
presets_dir使用完整的外部预设目录替代内置预设
external_shell_mode外部 Shell 预设的部署方式；默认 snapshot，可显式设为 live
presets_overlay_git由 Shine 浅克隆并镜像到 ~/.shine/overlay/ 的 Git overlay URL
presets_overlay_git_branchGit overlay 跟踪的分支；省略时使用远端默认分支
app_default_dest_root未声明目标路径的旧式 app 预设默认根目录
sync_terminal_theme控制受管 Unix shell profile 是否自动运行终端主题同步，默认为启用
gpg_recipientsshine env secret encrypt 默认 GPG recipient 列表
secret_backend默认密钥后端，省略时为 gpg
age_recipientsage 后端默认加密接收者列表
age_identity解密 age: 密文时使用的身份文件路径，省略时可使用 ~/.shine/age/identity.txt
age_identities附加 identity 文件路径列表，排在 age_identity 之后并自动去重
[env]模板变量及 shell helper 使用的值
[[env_proxy]]一个透明命令代理规则；command 为裸命令名，with 为允许注入的 KEY 或 KEY=ALIAS 列表，enabled 默认为 true

gpg_key_id 与 workspace 的 [env.encryption].recipient 是旧版单 recipient 字段。Shine 不会在普通读取配置时改写文件；用 shine state migrate --dry-run 预览并用 shine state migrate 迁移为 gpg_recipients。同一迁移也会把旧版 age1se... 转为 age 1.3 原生支持的 age1tag...；这能免除加密端的 Secure Enclave 插件依赖，但已经知道 recipient 的人可以判断密文是否发给它。遇到旧 workspace 时，env run 和 env secret seal 会提示迁移。

phone recipient 不由 state migrate 自动转换。升级并验证插件和手机应用的 tag 支持后，用 age-plugin-phone recipients -i <IDENTITY_STUB> --recipient-type tag 导出，替换对应 age_recipients 值并重新 seal；保留独立恢复 recipient。

命令读取格式损坏的 trust.toml 或 ssh-secret-broker.toml 时，TOML 解析错误会指出 文件，不回显存储内容。解析失败不会自动修复或改写文件。

外部代码信任​

外部 App hook、generator、artifact、Sys 安装脚本、可执行 profile 内容，以及每个外部 Shell command 都使用 target-scoped grant，并保存在仅所有者可读写的 ~/.shine/trust.toml。不要手改该文件，也不能从项目配置授予信任。

shine trust inspect app/example
shine trust grant app/example
shine trust list
shine trust revoke app/example
shine trust inspect shell/tools/my-command
shine trust grant preset
shine trust grant app/example --development

快照 Grant 只适用于已经审阅的 target、capability、来源层与完整有效类别快照。显式使用 --development 建立的开发信任允许所显示本地来源中的代码继续修改，但 target、capability、 来源目录/层必须保持不变。这是对未来来源内容的长期授权，不代表持续代码审阅。权限表是否存在不控制代码分类或 grant 资格。 Grant 不能替代每次操作前显示的 Plan。旧的 allow_app_hooks 和 allow_sys_code 已被忽略，并会在下次保存配置时移除。 preset target 可以批量审阅或授予当前激活快照，但保存时仍是各 target 独立的 grant；新增 target 或 capability 变化后仍须重新授权；开发信任还会在来源变化后失效。旧 schema v1 trust grant 仍可查看和撤销，但必须重新审阅。

Env 条目格式与说明​

全局 config.toml、项目 shine.config.toml 的 [env]，以及各层 shine.env.toml 覆盖 文件，都支持两种等价的值格式：

[env]
PLAIN_VALUE = "example"
DETAILED_VALUE = { value = "example", description = "供构建任务使用的示例变量" }
  • 字符串适合不需要补充说明的变量。
  • 详细格式中的 value 参与 env get、模板替换、env secret encrypt、env secret export 和 env run --with，行为与字符串格式相同。
  • description 只用于 shine env list 的可读说明，不会传入子进程或模板。
  • 当前配置中的内联 description 优先于预设 <presets>/env.toml catalog 的同名说明。
  • shine env set 更新已有详细条目时会保留其 description。
  • 字符串与仅有 value 的详细项只覆盖值并继承低层说明。只有显式 description 才替换说明； 空字符串清空说明并阻止 catalog 兜底。值和说明分别追踪来源。
  • 数字、数组、缺少字符串 value 等无效类型会报告文件路径和变量名，不会被静默忽略。

项目配置​

Shine 从当前目录向上查找最近的 shine.config.toml。项目配置是全局配置之上的稀疏覆盖层；没有声明的字段继续继承全局值，相对路径以声明它的配置文件所在目录为基准。

[[env_proxy]] 也遵循项目覆盖规则：项目内同名 command 的规则会取代全局规则，其它全局代理规则继续生效。优先用 shine env proxy install、enable 和 disable 管理这些条目，避免手改后忘记对应的 ~/.shine/bin/ shim。

Shine 0.40.0 不再识别项目中的旧式 config.toml 和 .env.toml。升级前请分别改名为 shine.config.toml 和 shine.env.toml；普通同名文件会被忽略，不会作为 Shine 配置读取。

Shine 0.40.0 也不再自动迁移旧的全局 ~/.shine/env.toml。升级前可先运行一次 v0.39 完成迁移；已经升级时，请将旧文件移动为 ~/.shine/shine.env.toml，若目标文件已存在则手动合并。检测到旧文件时，普通配置加载会停止并显示恢复提示，避免悄悄忽略仍在使用的值。

目录与来源优先级​

相对的 --config-dir、SHINE_CONFIG_DIR 和 SHINE_PRESETS 路径会在生命周期规划或脚本执行前， 按调用时的工作目录解析。子进程切换工作目录不会改变选定的运行时根目录。

SHINE_CONFIG_DIR 的优先级最高。它会改变全局配置和运行时状态目录；不在 Shine 项目中时， 预设目录也固定为 $SHINE_CONFIG_DIR/presets/，此时 SHINE_PRESETS 和全局 presets_dir 都不能覆盖它。

如果当前目录存在生效的项目 shine.config.toml，SHINE_CONFIG_DIR 仍决定运行时状态目录， 但显式设置的 SHINE_PRESETS 或项目 presets_dir 可以选择预设来源；从全局配置继承的 presets_dir 不能覆盖 $SHINE_CONFIG_DIR/presets/。

未设置 SHINE_CONFIG_DIR 时，基础预设目录按以下顺序选择：

  1. SHINE_PRESETS
  2. 项目 shine.config.toml 中的 presets_dir
  3. 全局 config.toml 中的 presets_dir
  4. 默认 ~/.shine/presets/

外部预设或 overlay 的根目录可以是符号链接。Shine 会先解析该链接，并把解析后的来源 用于 development trust；重新指向另一个目录需要重新审阅。失效的根目录链接会报错， 预设树内部的符号链接仍不参与快照。 FIFO、套接字和设备等特殊条目会使快照捕获报错；Shine 不会将它们作为预设文件读取。

使用外部 presets_dir 时，Shell 类别默认以 snapshot 模式复制到 ~/.shine/installed/shell/ 后再运行。在 Unix 上，快照保留捕获时脚本和辅助文件的可执行标记， 不复制所有者或特权权限位。仅执行权限变化（包括旧安装快照缺少可执行标记）也会出现在 shine update 中，并由 shine upgrade 修复。修改来源文件后，先用 shine update 检查，再用 shine upgrade 应用，便于审阅变化且与 app 配置的更新流程一致。仅在编写和调试预设时，才把 external_shell_mode 设为 live：源文件内容会在下次调用时生效；但 target、runtime、 transforms 和 env 等部署元数据变更仍须运行 shine upgrade 重新生成受管入口。Live 模式要求 显式 development trust；snapshot trust 不能授权读取可变来源的 launcher。已有 live launcher 会 保留，状态会把缺少 development trust 的目标标为需要审阅。

升级 Shine 后，运行 shine update 检查，再用 shine upgrade 更新已有的带 transforms 的 Live Bun 命令。更新后的入口在渲染和读取声明的环境值时都使用安装目录对应的配置，即使调用者 设置了不同的 SHINE_CONFIG_DIR。项目配置和 shine.env.toml 覆盖仍按调用者的工作目录生效。 更新后的 PowerShell 入口会保留空参数和字面量 --，也支持 Windows PowerShell 5.1。 此改动也覆盖未声明 env 的带 transforms 的 Live Bun 命令；无 transforms 的 Live 命令、 Native/source 命令及 snapshot 命令保留现有启动方式。

Overlay 在选定的基础预设来源上按相同相对路径覆盖文件，不替代整棵目录。手动关联的 presets_overlay_dir 与 presets_overlay_git 互斥；使用 shine preset overlay link 可避免同时配置。 presets_overlay_git 和 presets_overlay_git_branch 仅用于全局 config.toml； 请在 Shine 项目之外运行 overlay link --git。项目可使用 presets_overlay_dir 关联本地 overlay。 关联命令克隆成功后，Git overlay 即可生效；手动填写配置时，则需先成功执行 shine preset pull。 本地检出会在后续拉取时强制镜像到远端状态，因此不要直接修改 ~/.shine/overlay/。

Env 值覆盖顺序​

同名环境值按以下顺序合并，后者覆盖前者：

  1. 内置默认值（仅运行时兜底）；
  2. 当前 overlay 的 shine.env.toml（共享基线）；
  3. 全局 config.toml 的 [env]；
  4. 全局 shine.env.toml；
  5. 项目 shine.config.toml 的 [env]；
  6. 项目 shine.env.toml。

所有安装统一使用此顺序。SHINE_CONFIG_DIR 选择全局根目录，以上路径不硬编码为 ~/.shine/。 内置默认值不会因加载或保存其他配置而写入文件。已有项全部按显式配置保留，即使等于旧默认值； 主动删除指定层的项后才恢复继承。单独存在 shine.env.toml 不构成项目。 项目 env 文件只从最近 shine.config.toml 所在目录读取，不合并多个祖先项目。

用 shine env explain KEY 查看值来源、描述来源、覆盖链和默认写入目标；默认不显示值， --reveal 才显示且不会解密。env get 保持单值输出。参见 环境管理指南中的人工升级和回退步骤。

shine.env.toml 是不带 [env] 表头的覆盖文件，例如：

HTTP_PROXY_PORT = "7890"
PROXY_HOST = { value = "127.0.0.1", description = "本地代理主机" }

Workspace 环境​

shine.workspace.toml 定义项目可用 mode、环境源文件和项目共享的加密 recipient：

version = 2

[env]
modes = ["development", "production"]
default_mode = "development"
override_process_env = false
files = [
  ".env.shine.toml",
  ".env.local.shine.toml",
  ".env.{mode}.shine.toml",
  ".env.{mode}.local.shine.toml",
]

[env.encryption]
gpg_recipients = ["user@example.com", "team-backup@example.com"]
# 也可使用 age 后端
# backend = "age"
# age_recipients = ["age1tag1qexample...", "age1qteammate..."]

环境源按 files 顺序合并。默认保留当前进程已经存在的变量；设置 env.override_process_env = true 后，改由 workspace 值覆盖。

执行 shine env secret seal 或 shine env run 时，加密设置的优先级为命令行参数、 [env.encryption]、全局 ~/.shine/config.toml。因此，全局配置适合个人默认值；项目团队的 GPG 或 age recipient 列表应放在此文件中。recipient 是公钥信息，可提交到仓库；不要提交 age_identity/age_identities 指向的私有身份文件或本机路径。

每个环境源文件使用以下结构：

version = 1

[plain]
PUBLIC_VALUE = "example"

[secret]
EXISTING_SECRET = true
PROMPT_ON_SEAL = false
PLAINTEXT_TO_SEAL = "<待封存的值>"

[payload]
data = "<由 Shine 管理的 GPG 密文>"

shine env secret seal 会把 [secret] 中的待处理值合并进加密 payload，并将已封存项改为 true。shine env run 按文件顺序合并 [plain] 和解密后的 secret；策略和源均为单后端且配置了可用 recipient 时，还会维护按 mode 区分的加密缓存。

shine env run --with KEY[=ALIAS] 还可注入当前 Shine 配置 [env] 中的值。它优先读取 KEY_SECRET，不存在时读取 KEY；显式注入值覆盖 workspace 和当前进程中的同名变量。

受管目录​

~/.shine/
├── config.toml
├── shine.env.toml
├── app-manifest.toml
├── shell-manifest.toml
├── proxy-manifest.toml
├── tasks.toml
├── bin/
├── http/
├── installed/
├── overlay/
├── rendered/
└── presets/
    ├── app/
    ├── shell/
    └── sys/

不要手工删除 manifest 后再期望 Shine 识别旧安装；优先使用对应的 uninstall --dry-run 和 uninstall。

工作区混合加密​

env.encryption.backend = "hybrid" 要求工作区同时提供 gpg_recipients 和 age_recipients，每组至少一个非空项。GPG 项必须是本机已有公钥的完整 40 位十六进制 主密钥指纹。两组均不合并全局收件人；仅同时配置两组不会启用 hybrid。

在本机全局 config.toml 中设置 hybrid_decrypt_backend = "gpg" 或 "age"。 本机工作区操作可用工作区旁的 shine.config.local.toml 覆盖此字段；文件或字段缺失则继承 全局设置。共享的 shine.config.toml 不能覆盖或保存此偏好。将个人文件加入 .gitignore； 它只接受该字段，格式错误或未知字段会报错。它不改变单后端路由，也不授予秘密释放权限。 SSH broker 不接受远端个人配置。全局 secret_backend 仍只接受 gpg 或 age。

Hybrid 编译缓存使用最终选定的单后端及工作区对应收件人名单。配置变化会重新判定缓存 有效性，不会自动切换到另一后端。详见环境指南。

Workspace 文件组​

Workspace version 3 增加 file_groups.<名称>.files 数组，每项要求 source（密文）和 target（明文）。组必须非空，组名仅含字母、数字、短横线和下划线。路径支持 {mode}，解析基准为 workspace 所在目录。声明了文件组时可省略 env.files。Version 2 不接受文件组。加密复用 [env.encryption]，没有组级或环境级策略。详见临时机密文件。

最后由 biulight 于 更新