specrails-desktop 2.8.0 → 2.9.0

package/docs/guide/zh/settings/4-where-your-data-lives.md

@@ -0,0 +1,48 @@
+# 你的数据存放在哪里
+
+一句话总结：**Specrails 始终让你的仓库保持纯净。**当你把应用指向你的某个项目时，它不会鸠占鹊巢，不会到处散落配置文件，也不会改写任何你没要求它改的东西。你的代码依然是你的，而且干干净净。
+
+## 你的仓库保持洁净
+
+Specrails 自身的文件——它的数据库、各项目状态、agent 定义、设置、遥测、摘要，以及运行所需的一切——都集中存放在你主目录下一个整洁的家中：
+
+```
+~/.specrails/
+```
+
+那个文件夹是应用的私有工作区。项目注册表、各项目数据库、内置工具链以及所有运行相关的零碎信息都住在这里。你真正的代码仓库绝不会被当作这些东西的「垃圾场」。
+
+这意味着：
+
+- 你仓库的 `.gitignore` **不会**被应用改写。
+- 你的仓库不会被工具配置或隐藏的状态目录弄得乱七八糟。
+- 从 Specrails 中移除一个项目，不会在你的代码里留下一地狼藉。
+
+如果你以前用过那种悄悄在项目里到处添加文件夹和文件的工具，那么这是一次有意为之的不同选择。Specrails 的设计宗旨，就是让「把它指向某个仓库」对该仓库的 git 历史而言是一件**毫无波澜的小事**。
+
+## 唯一**会被**提交的东西——这是有意设计
+
+恰好有一个有意为之的例外，而它正是整个工具的意义所在：**你的 OpenSpec spec。**
+
+spec 存放在你的仓库中，位于：
+
+```
+openspec/
+```
+
+这是刻意为之。你的 spec 是一份**交付物**——一份带版本、可审查的记录，记述了你决定构建什么以及为什么。它们理应与你的代码并肩而立，被 git 追踪，在 pull request 中可见，与团队共享。这正是其价值所在：spec 不是用完即弃的临时状态，而是你项目历史的一部分。
+
+所以规则简单而坦诚：
+
+- **`openspec/`** → 存放在你的仓库中，被提交，这是有意设计。
+- **Specrails 所需的其他一切** → 存放在 `~/.specrails/` 下，不挡你的道。
+
+## 为何如此设计
+
+Specrails 在它自己的私有工作区（`~/.specrails/` 下）运行 AI 工具链，只有在确实需要触碰你真实仓库的事情上才会伸手进去——读取你的代码，以及写入你要求的 spec。工具链、框架定义和各种记账信息全都留在应用的家目录里。
+
+对你而言，好处在于：你可以放心地添加项目、运行流水线、探索 spec、试验各种想法，因为你仓库的工作区和 git 历史只会以你预期的方式发生变化——你提交的 spec，以及你的流水线写出的代码。别的什么都不会偷偷溜进来。
+
+## 移除一个项目
+
+当你从 Specrails 中移除一个项目时，应用会清理它在 `~/.specrails/` 下自己的项目级状态。已经提交到你仓库的 spec 仍留在它们该在的地方——你的仓库里——因为它们是你的。

package/docs/guide/zh/specs/1-specs-and-the-backlog.md

@@ -0,0 +1,52 @@
+# Spec 与 backlog
+
+**spec** 是 AI 流水线要实现的工作单元。你可以把它想象成一张工单：包含标题、一段对需求的描述、优先级，以及可选的标签。当你启动流水线时，AI agent 会读取这份 spec 并据此行动——所以一份清晰的 spec，是决定结果好坏的最重要输入。
+
+在应用里，spec 有时也被称作 **工单**——这两个词指的是同一样东西。
+
+## 看板
+
+每个项目打开后都会停留在 **Dashboard** 上，那里展示的就是 **SpecsBoard**——项目里所有 spec 的列表。这就是你的 backlog。你可以在这里创建新的 spec、设置优先级、把它们拖到某条 rail 上去实现，并随着工作的推进看着它们的状态发生变化。
+
+看板有两种视图模式，通过工具栏上的切换按钮选择，并会按项目分别记住你的选择：
+
+- **便签视图**（默认）——卡片样式的方块，附带简短摘要。
+- **列表视图**——紧凑的单行行式布局。
+
+你还可以按 **状态**（全部 / 待办 / 完成）和 **标签** 筛选，并按 **默认**、**工单 #** 或 **优先级** 排序（每一种都带有升序/降序切换）。
+
+## 状态
+
+一份 spec 会在一小组状态之间流转。看板为每种状态都设计了统一的视觉标识，让你一眼就能读懂整个 backlog 的状态：
+
+| 状态 | 含义 |
+|--------|---------------|
+| **草稿** | 从一次 Explore 对话中保存下来的、仍在打磨中的想法。还没准备好实现——你随时可以回来继续雕琢。会显示一个 `Draft` 标签。 |
+| **待办** | 可以开工了。一份完成的 spec 创建后就落在这个状态。 |
+| **进行中** | 流水线正在处理它（一个跳动的蓝点）。 |
+| **完成** | 流水线已实现（一个绿色对勾）。 |
+| **已取消** | 已放弃（一个红色 X）。 |
+
+草稿和待办的 spec 共处于同一个活跃区域里——并没有单独的列——但它们带有一圈淡淡的着色边框和一个 `Draft` 标签，所以很容易辨认。关于草稿的完整介绍，请参阅 [草稿与 Contract Layer](drafts-and-contract-layer.md)。
+
+## 优先级
+
+每一份非草稿的 spec 都有一个优先级：**紧急**、**高**、**中** 或 **低**。优先级纯粹是一个组织工具——它帮你决定接下来先实现哪一项，也让你可以据此为看板排序。你在创建 spec 时设置它，之后随时可以右键点击 spec 卡片、选择 **设置优先级** 来更改。
+
+草稿是唯一的例外：草稿可以*完全没有*优先级，因为它还只是一个进行中的想法。当你把草稿提交为正式 spec 时，优先级才会被确定下来。
+
+## 创建一份 spec
+
+要创建 spec，点击 **添加**（SpecsBoard 工具栏上的加号按钮）。**添加 Spec** 对话框会打开，提供几种工作方式：
+
+- **Quick 模式**——你描述需求，AI 一次性写出完整的 spec。参见 [添加 Spec — Quick 模式](add-spec-quick-mode.md)。
+- **Explore 模式**——你与 AI 对话，它会一轮一轮地帮你打磨 spec。参见 [添加 Spec — Explore 模式](add-spec-explore-mode.md)。
+- **Raw 模式**——你输入什么，就原样保存成 spec，全程不涉及 AI。当你手头已经写好了 spec 文本时，用它最合适。
+
+具体选哪一种，取决于你的想法已经多清晰了。完全清楚自己要什么？用 Quick。还在琢磨？用 Explore。文本已经写好了？用 Raw。
+
+## 下一步去哪里
+
+- [添加 Spec — Quick 模式](add-spec-quick-mode.md)——把想法变成 spec 的最快方式。
+- [添加 Spec — Explore 模式](add-spec-explore-mode.md)——在对话中打磨一份 spec。
+- [草稿与 Contract Layer](drafts-and-contract-layer.md)——保存进行中的工作，并为流水线增强你的 spec。

package/docs/guide/zh/specs/2-add-spec-quick-mode.md

@@ -0,0 +1,45 @@
+# 添加 Spec — Quick 模式
+
+当你已经清楚自己想要什么时，Quick 模式正合适。你输入想法，AI 写出完整的 spec，它就以 **待办** 状态落在你的看板上。不需要来回讨论——只管描述，然后开干。
+
+## 用 Quick 模式创建 spec
+
+要快速创建一份 spec：
+
+1. 在 Dashboard 上点击 **添加**（SpecsBoard 工具栏上的加号按钮）。
+2. 选择 **Quick** 模式。
+3. 在文本框里输入你的想法——一句话或一段话，能说清楚就行。
+4. 点击生成。
+
+在 spec 生成期间，角落里会出现一个小提示，显示项目名称、你想法的片段，以及 **已用时间**（“正在生成… 0:12”）。完成后，提示会切换成“已在 <时长> 内生成”，并附带一个 **查看** 按钮，点一下就直接跳到你新建的 spec。
+
+整个流程就这么简单。下面的内容都是可选的微调。
+
+## 你可以调整什么
+
+**模型**——默认情况下，AI 会挑选一个合适的模型。如果你想要更快或更强的模型，可以在模型选择器里按 spec 单独覆写。
+
+**引擎**——如果你的项目安装了不止一个 AI provider（Claude、Codex、Gemini 的任意组合），对话框顶部会有一个引擎选择器，让你选择由哪一个来生成这份 spec。你的选择会按项目记住。单 provider 的项目不会显示它——因为没有可选的余地。
+
+**上下文**——Quick 模式通常作为单轮运行，因为它不需要读取你的代码库就能根据你的描述写出 spec。但一个上下文滑块可以给它更多素材：
+
+- 在最低档时，它只读取你的描述。
+- 在更高的档位上，它可以在动笔前读取你现有的 spec、项目的 OpenSpec spec，甚至你的整个代码库。
+
+你给它的上下文越多，生成耗时就越长（它会切换到多轮模式，以便先读取内容），但换来的 spec 是扎根于你真实项目的。当 spec 需要引用真实代码、文件名或现有行为时，就把上下文档位调高。
+
+**附件**——把原型图、简报或数据文件拖进想法输入框。AI 会在撰写 spec 时一并阅读它们。（附件同样会让生成切换到多轮模式。）
+
+**用 Contract Layer 增强**——这是一个开关，它会在生成的 spec 后面追加一个结构化的区块，让下游流水线不必去猜测命名或数据结构。它是可选的，默认关闭；你上次的选择会按项目记住。关于它会增加什么、以及何时值得开启，参见 [草稿与 Contract Layer](drafts-and-contract-layer.md)。
+
+## Quick 模式 vs Explore 该怎么选
+
+当想法在你脑子里已经清晰成型时，用 **Quick**——你本可以自己写出这份 spec，只是更愿意让 AI 来代劳。当你还在反复斟酌、想找个搭档帮你打磨时，用 [**Explore**](add-spec-explore-mode.md)。
+
+在 Quick 模式下创建的 spec 是一份完全正常的 spec：如果之后需要进一步打磨，你可以打开它，在一次 Explore 会话里 **继续编辑**。
+
+## 下一步去哪里
+
+- [添加 Spec — Explore 模式](add-spec-explore-mode.md)——适合需要打磨的 spec。
+- [草稿与 Contract Layer](drafts-and-contract-layer.md)——详解 Contract Layer 增强。
+- [运行流水线](running-pipelines.md)——把你新建的 spec 拖到 rail 上并实现它。

package/docs/guide/zh/specs/3-add-spec-explore-mode.md

@@ -0,0 +1,68 @@
+# 添加 Spec — Explore 模式
+
+Explore 模式是一场对话。你不必自己动手写 spec，而是和 AI 一起把想法聊清楚——它扮演一个思考伙伴的角色，提出问题、给出结构建议，并在过程中构建一份 spec 的 **实时草稿**。当你满意时，再把草稿提交成正式 spec。
+
+当想法还没完全成型、有一些权衡需要讨论，或者你想让 AI 在敲定 spec 之前先看看你的真实代码时，就用 Explore。
+
+## 用 Explore 模式创建 spec
+
+要在 Explore 模式下打磨一份 spec：
+
+1. 在 Dashboard 上点击 **添加**，然后选择 **Explore**。
+2. 输入你的第一条消息——一个想法、一个问题，或者一个还没想透的念头。
+3. 阅读 AI 的回复并继续对话。每一轮，它都会让自己的理解更精准。
+4. 看着 **实时草稿** 随着对话一起更新——这就是逐渐成型的 spec。
+5. 当草稿看起来对劲了，点击 **创建 Spec**。
+
+对话会保留在你的历史记录里，所以你随时可以回来看看这份 spec 当初是怎么被打磨出来的。
+
+## 实时草稿
+
+随着对话进行，草稿面板会展示 spec 当前的样子——标题、描述、优先级、标签、验收标准。它每一轮都会根据你们讨论的内容重写自己。你不必直接编辑它，而是通过对话来引导它（“其实把优先级改成高吧”、“加一条关于错误处理的标准”，诸如此类）。
+
+这正是 Explore 模式的精髓：你永远不会对着一张空白表单发呆，而是始终面对一份真实的、不断演进的 spec。
+
+## AI 能看到多少：上下文滑块
+
+在 AI 作答之前，由你来决定它能看到你项目里的多少内容。一个上下文预设滑块让你在速度和深度之间做权衡：
+
+| 预设 | AI 能看到什么 |
+|--------|------------------|
+| **极简** | 只看你的消息。最快、最省钱。 |
+| **轻量** | + 你现有的 spec。 |
+| **标准** | + 你的 spec 以及项目的 OpenSpec spec。 |
+| **丰富** | + 对你整个代码库的读取权限，让它能把回答扎根于真实代码。 |
+| **最大** | 在“丰富”的基础上，提交时再追加一遍 Contract Layer 增强。 |
+| **Desktop** | 在“最大”的基础上，加上你项目的 MCP server 以及你自己已批准的 MCP server。 |
+
+头脑风暴时从低档起步求快；当你想让 AI 拿你的真实代码核对它的建议时，再往上调。这个选择会保存在当前对话上，所以不会泄漏到其他 Explore 会话里。
+
+如果你想要更精细的控制，点击 **微调**，逐项手动切换底层选项——其中包括 **我已批准的 MCP**，它会加载你本地已经批准过的 MCP server，而不会拖慢会话。
+
+## Explore 界面里的按钮
+
+- **创建 Spec**——把实时草稿提升为一份状态为 **待办** 的正式 spec。（当你在编辑一份已有的 spec 时，这个按钮会变成 **更新 Spec**，原地更新那份 spec。）
+- **审阅 →**——打开一个审阅浮层，在你提交之前把拟定的 spec 与基线做对比，做到心中有数、没有意外。
+- **保存为草稿**——把对话作为一张草稿工单保存下来，方便你以后接着做。只要你至少发过一条消息就可使用。见下文。
+- **最小化**——把对话停靠成左下角“最小化聊天”坞里的一个小标签。随时点击这个标签就能回到对话——什么都不会丢。
+- **丢弃**——把对话扔掉（会先请你确认）。
+
+## 保存为草稿
+
+还没准备好提交，但又不想丢掉这些思考？点击 **保存为草稿**。对话会变成你看板上的一份 **草稿 spec**，并与它背后的对话保持关联。
+
+之后，从看板上打开这份草稿并点击 **继续编辑**——原来的对话会带着完整的聊天历史重新打开，你就能从离开的地方精确地接着往下做。草稿永远不会被自动删除；它们会一直等着你。
+
+这让 Explore 用起来很安心，哪怕想法还半生不熟：开一场对话、有了点眉目、存成草稿，明天再回来。
+
+关于草稿的方方面面——包括 Contract Layer 增强——请参阅 [草稿与 Contract Layer](drafts-and-contract-layer.md)。
+
+## 多 provider 说明
+
+如果你的项目安装了不止一个 AI provider，会有一个引擎选择器让你选择由哪一个来主导这场 Explore 对话。单 provider 的项目不会显示它。
+
+## 下一步去哪里
+
+- [草稿与 Contract Layer](drafts-and-contract-layer.md)——保存进行中的工作，并为流水线增强你的 spec。
+- [添加 Spec — Quick 模式](add-spec-quick-mode.md)——当想法已经清晰时。
+- [运行流水线](running-pipelines.md)——spec 准备好后就去实现它。

package/docs/guide/zh/specs/4-drafts-and-contract-layer.md

@@ -0,0 +1,81 @@
+# 草稿与 Contract Layer
+
+本页介绍两种让你的 spec 发挥更大价值的方式：**草稿**（保存一个进行中的想法，方便日后接着做）和 **Contract Layer**（一种可选的增强，让 spec 对 AI 流水线更精确）。
+
+## 草稿：保存进行中的想法
+
+**草稿** 是一段进行中的 [Explore](add-spec-explore-mode.md) 对话被保存成的 spec。它让你可以在想法只想了一半时停下来而不丢失任何东西，等准备好了再回来。
+
+### 保存草稿
+
+在一场 Explore 对话里，点击 **保存为草稿**（一旦你发过至少一条消息即可使用）。应用会：
+
+- 在你的看板上创建一份状态为 **草稿** 的 spec。
+- 如果你没有设置标题，自动给它起一个（一段对话的简短摘要）。
+- 把它与对话关联起来，从而保留完整的聊天历史。
+
+保存是幂等的——如果你把同一场对话保存两次，它会更新已有的那份草稿，而不是创建一个重复项。
+
+### 草稿在看板上长什么样
+
+草稿和你的待办 spec 共处于同一个活跃区域里——没有单独的列。你可以通过以下两点认出它们：
+
+- 在优先级标签通常所在的位置，会有一个 `Draft` 标签。
+- 卡片带有一圈淡淡的着色边框。
+
+草稿允许*没有优先级*——当你把它提交为正式 spec 时再设置优先级。
+
+### 继续一份草稿
+
+要从离开的地方接着做：
+
+1. 从看板上打开那份草稿。
+2. 在详情弹窗里点击 **继续编辑**。
+3. 原来的 Explore 对话会带着完整的聊天历史重新打开，实时草稿面板里也预先填好了你此前打磨的一切。
+4. 继续对话。完成后，**创建 Spec** 会把草稿提升为一份正式 spec（状态 **待办**，使用你选定的优先级）。
+
+### 丢弃一份草稿
+
+草稿 **永远不会被自动删除**。它们只有在你显式丢弃、或把它们提交到某个正式状态时才会消失。当某份草稿关联的对话没有别处再引用它时，丢弃这份草稿也会一并清理掉那场对话。
+
+> 提示：当你拿不准一份 spec 是否值得做时，把它存成草稿，让它放一放。第二天早上打开它，扫一眼描述，用清醒的眼光来定夺。
+
+## Contract Layer：为流水线带来精确性
+
+**Contract Layer** 是一种可选的增强，它会在 spec 的描述后面追加一个结构化的区块。它的职责是替实现这份 spec 的 AI agent 消除猜测——让它们复用正确的命名、匹配预期的数据结构、改动正确的文件，而不是自己另造一套。
+
+### 它会增加什么
+
+Contract Layer 是追加在 spec 后面的五个简短小节：
+
+- **Naming Contract**——实现时应当复用的确切标识符（函数、字段、路由）。
+- **Data Shapes**——涉及的 JSON 形式的数据负载。
+- **State Machine**——该功能所经历的状态或状态转换。
+- **Invariants**——必须始终成立的性质。
+- **File Touch List**——实现时预期会改动的文件。
+
+可以把它想象成交给流水线一张精确的蓝图，而不是一张草图。对于那些要接入现有代码的 spec 来说，它尤其宝贵——在这些场景里，AI 一旦猜错命名或结构，就会带来返工。
+
+### 如何添加
+
+Contract Layer 有三种应用方式：
+
+- **Quick 模式**——在生成之前打开 **用 Contract Layer 增强** 开关。你上次的选择会按项目记住。（参见 [添加 Spec — Quick 模式](add-spec-quick-mode.md)。）
+- **Explore 模式**——选择 **最大** 或 **Desktop** 上下文预设（它们会在提交时自动运行增强），或者打开 **微调** 手动切换它。（参见 [添加 Spec — Explore 模式](add-spec-explore-mode.md)。）
+- **在已有的 spec 上**——打开该 spec 的详情弹窗，从那里重新运行增强。
+
+### 它显示在哪里
+
+一旦一份 spec 有了 Contract Layer，详情弹窗会把它显示为一个可折叠的展开区域，并带有一个类似 `3/5 populated` 的徽章——告诉你五个小节里实际填写了几个（有些功能本身就没有比如状态机这样的内容，这些小节会被标记为不适用）。展开它就能读到完整的契约；收起它就能让描述保持整洁。
+
+如果增强运行失败了，应用会弹出一条通知，附带一个 **重试** 操作，让你可以再触发一次。
+
+### 它总是值得做吗？
+
+并非总是。对于一份小而自洽的 spec，AI 没有它也能实现得很好。Contract Layer 真正发挥作用的地方，是那些与现有代码紧密集成、确切命名和结构都很关键的 spec——在这种情况下，提前把契约钉死，能为你省下之后一轮的修正。
+
+## 下一步去哪里
+
+- [添加 Spec — Explore 模式](add-spec-explore-mode.md)——草稿的来源。
+- [添加 Spec — Quick 模式](add-spec-quick-mode.md)——Quick 模式里的 Contract Layer 开关。
+- [运行流水线](running-pipelines.md)——spec 准备好后就去实现它。

package/docs/internals/README.md

@@ -16,7 +16,7 @@ If you're a user looking for **how do I do X?** docs, head back to the [user gui
 | [adding-a-provider.md](adding-a-provider.md) | How to add a new AI CLI: one adapter file plus one entry in the registry |
 | [profiles.md](profiles.md) | Agent profiles quick start: open the Agents section, pick a profile per rail at launch, author custom agents in Agent Studio. For the true file-format and snapshotting internals, read `server/profile-manager.ts` and the profile-manager section of `CLAUDE.md` |
 
-**See also:** [`../codex.md`](../codex.md) for the multi-provider model (Claude Code + Codex CLI as first-class engines).
+**See also:** the app supports multiple AI CLIs as first-class, interchangeable engines — Claude Code, Codex CLI, and Gemini CLI. See [`../codex.md`](../codex.md) and [`../gemini.md`](../gemini.md) for the per-provider detail. Gemini is **enabled by default** (selectable whenever the `gemini` CLI is on `PATH`); the emergency rollback is `SPECRAILS_GEMINI_BETA=0` (only the exact string `0` disables it). Codex parallels this with `SPECRAILS_CODEX_BETA=0`.
 
 ## Contributing