跳转到内容
Crystal CodeDocs
简简体中文
自动English简体中文繁體中文

提示与指令

Crystal 是提示中立的。本产品发送的每条绑定模型的字符串都在这里编写。操作者可以把文件放在 ~/.crystal/prompts 和 <workspace>/.crystal/prompts 下，以替换 Work、Plan、Review、Review 用户回合、主题命名、压缩和图像描述。

命名文件（work.md、plan.md、review.md、review.user.md、topic.md、compaction.system.md、compaction.user.md、image.system.md 和 image.user.md；也接受 .txt）：

  • 在直接覆盖内，Home 文件在项目文件之前应用。
  • 项目文件替换该名称的主目录文件。
  • 空文件视为缺失。
  • 宿主从不写入提示文件。

提示集选择与直接提示覆盖分开。可复用集合只位于 ~/.crystal/promptsets/<name>/；从不扫描工作区寻找提示集。每个集合包含 prompt.json 和这些命名文件的任意子集（也接受 .txt）。缺失或空的成员使用该名称的内置提示。

prompt.json 可以包含 name 和 description。name 是至多 80 个字符的显示标题。description 至多 280 个字符。目录名仍是命令使用的 id。enabled 打开该目录。省略 enabled 表示关闭。未知字段被保留。缺失、不可读或无效的文件跳过该目录。启用和禁用不创建目录或缺失的文件，并让损坏的文件保持不变。

最多启用一个提示集。启用一个会关闭其他集合。如果手工编辑使多个集合为 enabled: true，Crystal 使用内置提示并报告冲突。/promptset default 关闭每个集合。

每个命名提示的最终优先级：

  1. 内置默认。
  2. 所选 Home 提示集。
  3. 直接的 ~/.crystal/prompts 覆盖。
  4. 直接的 <workspace>/.crystal/prompts 覆盖。

用 /promptset（别名 /prompts）列出可用集合以及 Work、Plan 和 Review 的有效来源。/promptset <name> 启用该集合。/promptset default 回到虚拟的内置选择。回合运行时拒绝切换，但列出仍然可用。非默认集合在状态栏显示为 Prompt <name>，并作为启动说明。crystal promptsets list|show|enable|disable 在会话外编辑相同文件。

config.json 中较旧的 promptSet 和 promptAttachments 值被忽略。下次保存偏好时省略它们。没有迁移工具。给每个你仍想要的目录添加 prompt.json。

提示附件追加在已解析的 Work、Plan 或 Review 文本之后。附件不替换主题、Review 用户、压缩或图像描述。每个附件是带 prompt.json 以及 work.md、plan.md 和 review.md 中任意文件的目录（也接受 .txt）。没有文件的模式从该附件得不到任何内容。空文件视为缺失。附件文件末尾的尾随换行被保留。目录名是 1–64 个由单个连字符连接的小写字母数字词。允许 default。

附件在两处发现：

  1. ~/.crystal/prompt-attachments/<name>/
  2. <workspace>/.crystal/prompt-attachments/<name>/

工作区扫描只是当前工作区根。不遍历父目录。同名存在于两处时，工作区 prompt.json 替换 Home 文件，包括 enabled 和 order。发现本身不启用目录。

可以启用多个附件。它们按 order 追加，然后按目录名。缺失的 order 排在最后。启用一个名称把它放在最后，并把已启用的顺序改写为 0、1、2 等等。禁用把 enabled 设为 false，且不重新编号。附件内的占位符用与正文相同的值展开。

/promptattach 列出每个已发现的附件。有效行被编号，并显示显示名称、描述和 Home 或 Workspace 来源。/promptattach enable <name> 和 disable <name> 编辑获胜的目录。/promptattach up <name> 和 down <name> 在已启用顺序中移动一个名称。回合运行时拒绝更改。列出仍然可用。状态栏仍只显示所选提示集。crystal prompt-attachments list|show|enable|disable 接受 --home、--workspace、--source home|project 和 --format text。

crystal、crystal space 和 crystal run 遵循已启用的清单。--prompt-set <name> 为该进程强制一个集合，包括文件中 enabled: false 的集合。default 强制内置文本。--prompt-attachments off 不附加任何内容，并拒绝 /promptattach 的 enable、disable、up 和 down。列出仍然可用。省略该标志或传入 on 时遵循文件。重复 --prompt-attachment <name> 把该附件追加到已启用集合之后，即使其 prompt.json 中 enabled: false。已经启用的名称留在其文件顺序中。同一标志与 --prompt-attachments off 一起被拒绝，不在 Home 或启动工作区中的名称会使启动失败。对强制名称，/promptattach enable、disable、up 和 down 被拒绝，且不写入文件。其他名称仍可更改。列出仍然可用。之后的工作区更改不再包含强制名称时，跳过它并打印一条说明。--prompt-set 拒绝该进程的 /promptset 切换，包括 default，且不写入 prompt.json。列出和导出仍然可用。这些标志都不写入 prompt.json 或 config.json。

已启用的附件文本在正文绑定之后、普通插件提示钩子追加自己的文本之前加入。

内置 Work 和 Plan 助手名称是 Crystal Code。Work、Plan、Review、压缩和图像描述模板使用宿主拥有的占位符（{{name}}）。复合会话槽是 {{env}}、{{skills}}、{{directories}}，以及 {{instructions_section}} 或原始 {{instructions}}。原子会话槽包括 {{workspace}}、{{is_git_repo}}、{{git_root}}、{{platform}}、{{os}}、{{architecture}}、{{date}}、{{time}}、{{provider}}、{{model}}、{{model_line}}、{{mode}}、{{product_name}}、{{session_id}} 和 {{approval}}。{{os}} 是操作系统名称和版本。{{architecture}} 是进程架构，例如 x64 或 arm64。{{time}} 是带数字偏移的本地时间，在组合该系统消息时捕获。工作区目录本身包含 .git 目录或文件时，{{is_git_repo}} 为 yes。{{git_root}} 是通过遍历父目录找到的仓库根，该遍历找不到时为空。{{session_id}} 是已保存的会话 id。{{approval}} 是审批模式（plan、default、edit、review、audit 或 full）。对 Work 和 Plan，{{mode}} 是 plan 或 work；对 Review 系统文本是 review；对压缩系统文本是 compaction；对图像描述系统文本是 image。{{env}} 块包括操作系统、架构和本地时间，并在宿主有它们时添加 git 根、会话和审批行。会话没有添加的目录规则时，{{directories}} 为空。否则它是追加到工作区指令的同一段会话目录访问文本。内置模板不声明此槽。活动系统消息被替换时它会刷新，包括 /access 之后。这些值在 /cd、/model、/approval，以及活动系统消息被替换时刷新。Review 用户模板添加 {{conversation}}、{{tool_name}}、{{tool_arguments}}、{{host_risk}}、{{host_authority}} 和 {{classification_summary}}。压缩用户模板添加 {{conversation}}、{{prior_summary_section}}、{{summary_task}}、{{output_template}} 和 {{todos_section}}。图像用户模板添加 {{question}}，即描述请求或模型的问题。占位符名称不区分大小写。未知名称保持不变。插件可以添加更多名称。解析名称时，插件可以读取当前会话模型，以及审查是否在使用自己的模型。宿主拒绝它已经拥有的名称，并把插件的值作为文本插入。模板必须声明它们需要的每个宿主槽。启用 Skills 时，可用技能引导填充 {{skills}}。复合宿主值不可覆盖。

工作区事实只在 Work 和 Plan 上追加在 “Workspace instructions” 下。Review 不接收该指令块。已启用的提示附件仍可以追加到 Review。

指令来源，按顺序：

  1. ~/.crystal/instructions.md（或 .txt）
  2. <workspace>/.crystal/instructions.md（或 .txt）
  3. <workspace>/.crystal.md
  4. OpenCode 兼容的规则文件（见下）

AGENTS.md 和 CLAUDE.md 是额外指令，不是提示替换。它们从不替换 Work、Plan 或 Review。

  • 全局：~/.crystal/AGENTS.md、~/.crystal/CLAUDE.md、~/.config/opencode/AGENTS.md 和 ~/.claude/CLAUDE.md 中第一个存在的文件（OpenCode 路径遵循 XDG_CONFIG_HOME）。
  • 项目：从工作区向上走到 git 根。第一个匹配的名称获胜（AGENTS.md，然后 CLAUDE.md，然后 CONTEXT.md）。遍历中该名称的每个文件都被追加。只在遍历中不存在 AGENTS.md 时使用 CLAUDE.md。

config.json 中的 ruleFiles 打开或关闭这些兼容文件。global 和 project 各自默认打开，关闭前省略。/rules 显示它们并写入同一文件。/rules on 或 off 设置两侧。/rules global off 或 /rules project off 设置一侧，并让另一侧保持原样，包括不在磁盘上的启动覆盖。--rules 为一个进程做同样的事，且不写入。off 跳过该发现。instructions.md 和 .crystal.md 保留。