specrails-desktop 2.7.0 → 2.9.0

package/docs/guide/zh/integrations/2-plugins.md

@@ -0,0 +1,44 @@
+# 插件（Integrations）
+
+**Integrations** 板块是按项目划分的可选插件市场，用来扩展 AI 能做的事。每个项目都独立决定自己想要哪些插件——在一个项目里安装插件，绝不会动到另一个项目。
+
+插件的工作方式，是悄悄地往你的项目里注册一个 **MCP 服务器**（Model Context Protocol），从而在 rail 和聊天过程中给 AI 提供新的可调用工具。你不需要懂 MCP 也能用它们——装好之后，下一次 rail 运行时它们就可用了。
+
+## 目前提供哪些
+
+这个版本采用**纯内置**方式：你能安装的插件，都是构建进应用里的那些。没有远程注册表、没有用户上传的插件、也不加载第三方代码——所以目录里的一切都经过审核，随 Specrails 一起发布。
+
+当家插件是：
+
+- **Serena**——语义化代码导航。它借助语言服务器，让 AI 真正理解你的代码库（跳转到定义、查找引用、基于符号的搜索），而不是简单的纯文本匹配。对于较大或不熟悉的仓库尤其好用——你会希望 agent 是在对真实符号做推理。
+
+  Serena 需要你的 `PATH` 上有 `uv` 工具（它通过 `uvx` 运行）。应用会自动检测 `uv` 是否存在，并在缺失时提示你。
+
+## 安装一个插件
+
+1. 从右侧边栏打开 **Integrations**。
+2. 在目录里找到该插件。每张卡片都会显示一个状态：**未安装**、**已安装**、**已降级** 或 **孤立**。
+3. 点进插件，**预览安装**——这会在任何改动发生之前，明确告诉你哪些文件会被改动。
+4. 点击 **安装**。安装过程中你会看到实时进度。
+
+在底层，安装是*精准且增量*的：它只会把自己的条目加进你项目的 `.mcp.json`（对某些插件，还会在受保护的 `.claude/agents/` 命名空间下加一个片段文件）。它绝不会整体重写你的配置，而且再装第二个插件也绝不会干扰第一个。如果安装无法自我验证为健康状态，它会干净利落地回滚。
+
+## 管理已安装的插件
+
+- **健康状况。** 每个插件都有一个按需运行的健康检查。一个安装顺利、但之后却起不来的插件会被标记为**已降级**——它不会阻塞你的 rail，你只会看到这个徽标和原因。
+- **卸载。** 移除插件时，只会精准删除它所拥有的条目，你配置的其余部分原封不动。
+- **孤立项。** 如果某个插件的文件被遗留下来、却没有对应的正常状态（比如某次改动被中断之后），它就会显示为**孤立**项，你可以一键清理掉。
+
+## 插件如何融入你的工作
+
+- **rail。** 在 rail 运行之前，Specrails 会检查哪些插件已安装且健康，并把那些工具提供给本次任务的 agent。一个已降级的插件会在这次运行中被直接跳过——rail 照常启动。每个任务都会记录一份当时哪些插件处于活动状态的快照，你可以在该任务的诊断导出里看到。
+- **聊天。** 聊天会自动采用你项目的 MCP 配置，所以已安装的插件在那里也同样可用。
+- **Setup。** 在项目仍处于安装设置阶段时，插件会被忽略——等项目准备就绪后它们才会发挥作用。
+
+## 提供方相关说明
+
+插件是「提供方感知」的。Serena 及类似的 MCP 插件，会对那些通过项目 `.mcp.json` 注册 MCP 的提供方（Claude 和 Gemini）生效。对于 Codex 项目，MCP 服务器是通过 Codex 自己的全局配置来管理的，因此 **Integrations** 里的插件条目会相应地被过滤掉。Integrations 里的 Jira 卡片与提供方无关，对所有人都会显示——参见 Jira 指南。
+
+## 受保留的文件
+
+插件会管理你项目里一小撮定义明确的文件：你的 `.mcp.json`（精准合并）、`.specrails/plugins/` 下的一些状态，以及位于 `.claude/agents/custom-<plugin>.md` 的各插件 agent 片段。如果你想和队友共享某个集成，这些都是可以提交进仓库的团队资产——应用绝不会盲目覆盖它们。

package/docs/guide/zh/integrations/3-jira-integration.md

@@ -0,0 +1,71 @@
+# Jira 集成
+
+想让你的规格活在真正的 **Jira 看板**上，而不是待在 Specrails 里？Jira 集成会用 Jira 事务来支撑一个项目的规格，在 rail 运行时保持状态同步，其余时间则安静地待在一旁不打扰你。每个项目都与**它自己的** Jira 看板同步。
+
+## 工作原理（简短版）
+
+Specrails 充当 Jira 和你项目之间的**同步层**。核心思路是：你本地的规格存储仍然是流水线读取的那个权威来源，而 Specrails 负责让它和 Jira 保持一致。
+
+- 当你启动一条 rail 时，Specrails 会把关联的 Jira 事务移动到 **In Progress**。
+- 当一个任务结束时，Specrails 会转移该事务的状态（移到 **Done**，如果失败则退回 **To Do**），并发布一条包含任务 id、成本和时长的完成评论。
+- Specrails 会定期**轮询** Jira，把任何人在看板上做的改动取回来，反映到你的规格里。
+
+所有的回写都会经过一个持久化、防崩溃的发件箱（outbox），所以 Jira 一时的小故障绝不会让任务出错——那次更新只是会重试而已。
+
+## 连接一个看板
+
+你从项目的 **Settings** 页面进行连接（在 Add-Project 向导的末尾，也有一个可选的「Configure Jira」步骤）。连接向导会带你走完：
+
+1. **测试**——输入你的 Jira 网址和凭据，Specrails 会验证连接。
+2. **选择一个项目**——选定要与之同步的 Jira 项目。
+3. **状态映射（可选）**——如果自动检测需要帮一把，就把你的 Jira 工作流状态映射到 Specrails 的状态上（下文详述）。
+4. **连接**——完成。你的规格现在会镜像那个看板。
+
+### 身份验证
+
+这个版本使用**令牌粘贴**式验证——快捷、在本机完成、不涉及任何后端：
+
+- **Jira Cloud：** 你的账户邮箱加上一个 API 令牌。
+- **Jira Data Center / Server：** 一个个人访问令牌（PAT）。
+
+你的令牌会**在你自己的机器上加密存储**，永不外泄。应用只会显示是否存在令牌，绝不会显示令牌本身。
+
+## 状态映射
+
+任何 Jira 同步里最棘手的部分，就是把*你的*工作流对应到 Specrails 那套简单的状态上（To Do / In Progress / Done，外加取消 / 上线的变体）。Specrails 分两层来解决：
+
+1. **你显式设置的状态映射**——如果你在向导里设了一个，它永远优先。
+2. **自动检测**——依据每个状态的类别（new / in-progress / done），再加上针对取消和上线类状态的智能匹配。
+
+当它需要把一个事务跨越带有门槛转换的工作流来移动时，它会一步步找到一条有效路径，并沿途填好任何必填字段（比如 resolution）。如果某个状态确实无法到达，那个操作会被搁置为「死信」（dead-letter）并呈现给你，而不是无声地失败——你会看到一个**已降级**的提示，并可以重试。
+
+## 热切换：安全地开和关
+
+Jira 的关联是**按规格**的，在你启动一条 rail 的那一刻被捕获——而不是对整个看板的全局、要么全开要么全关的开关。这让它切换起来很安全：
+
+- **启用或禁用**集成，绝不会重新归属你已有的规格。
+- **断开连接**会让你的项目恢复正常的本地规格行为。
+- 已经有 Jira 关联的规格会保留它们的回写；没有关联的规格则保持原样、不受影响。
+
+所以你可以放心地试验——打开它、跑几条 rail、再关掉——而不会搞乱你的看板或本地规格。
+
+## 日常使用
+
+连接之后，项目的 Settings 页面会显示一张**已连接卡片**，在那里你可以：
+
+- **立即同步**——强制马上轮询一次，而不必等计时器。
+- **重试死信**——重新执行任何卡住的回写。
+- **热切换开关**——临时暂停 / 恢复集成。
+- **断开连接**——干净地解除与看板的关联。
+
+由 Jira 支撑的规格，会在卡片上显示一个 **Jira key 徽标**（比如 `PROJ-123`），点进去能链接回那个事务。当一次同步完成、当一个验证令牌过期（这样你好去刷新它），或当集成进入降级状态时，你还会收到一些小提示。
+
+## 需要记住的几点
+
+- **是轮询，不是 webhook。** 因为 Specrails 在本地运行，它是通过轮询 Jira 来获取入站变更的，而不是接收推送通知。变更会在一个轮询周期内出现，而不是瞬间。
+- **一个项目一个看板。** 不同项目可以和不同看板同步；但单个项目只与恰好一个看板同步。
+- **冲突时以最后写入为准**——用于两个标签页同时编辑同一份草稿这种罕见情况。
+
+## 关闭它
+
+如果你哪天想彻底退出，只需从 Settings 里**断开连接**。你的规格会回到纯本地行为，而那些 Jira 元数据就只是闲置不用——什么都不会被销毁。

package/docs/guide/zh/integrations/4-mobile-companion.md

@@ -0,0 +1,38 @@
+# 移动端伴侣应用
+
+Specrails 有一个手机伴侣应用，让你离开座位时也能盯着自己的 rail——看任务在跑、看它们完成，不用守在仪表盘前也能随时掌握进展。
+
+## 它是做什么的
+
+伴侣应用是一个**监控**界面。它通过你的本地网络连接到正在运行的 Specrails 桌面应用，把实时的项目和任务动态镜像到你的手机上。可以把它想成一扇能随手一瞥的小窗，看到的正是你本来要在仪表盘上盯的那些 rail。
+
+## 配对你的手机
+
+配对是围绕一个**二维码**设计的，免去你手动输入那些繁琐内容：
+
+1. 确保你的桌面 Specrails 应用正在运行，并且你的手机和它处在**同一个本地网络**（同一个 Wi-Fi）。
+2. 在桌面应用里，打开配对界面以显示一个二维码。
+3. 在你手机上的伴侣应用里，扫描那个二维码。
+4. 手机会在网络上发现桌面应用并连接上去。
+
+从那以后，伴侣应用会保持一个实时连接，随着项目列表和任务更新的发生，把它们流式推送过来。
+
+## 连接是如何工作的
+
+桌面应用会在你的本地网络上「广播」自己，好让手机能找到它；而二维码则携带了手机安全连接所需的信息。一切都留在你的本地网络内——伴侣应用是直接和你的机器通信的，不经过任何云服务。
+
+正因为它基于本地网络，两台设备之间必须能互相访问。如果配对没成功：
+
+- 确认两台设备都在**同一个 Wi-Fi** 上（并且该网络没有把客户端彼此隔离）。
+- 确保扫码时桌面应用正在**运行**。
+- 重新打开配对界面以刷新二维码，再试着扫一次。
+
+## 你会看到什么
+
+配对之后，伴侣应用会呈现你的项目及其实时任务动态，于是你会得到和流入桌面仪表盘相同的实时 rail 更新——在事件发生时推送到你的手机上。想知道一条长时间运行的 rail 何时收尾，这是最省事的方式。
+
+## 须知
+
+- **以监控为主。** 伴侣应用的定位是帮你随时掌握 rail 的状况，而不是在手机上驱动完整的桌面工作流。
+- **仅限本地。** 没有账户、没有云端中继——只有你的机器和你的手机，在你的网络里。
+- **让桌面保持唤醒。** 伴侣应用镜像的是一个正在运行的桌面应用；如果你的机器休眠或应用关闭，实时更新会暂停，直到它重新运行。

package/docs/guide/zh/pipeline/1-rails-and-jobs.md

@@ -0,0 +1,94 @@
+# Rail 与任务
+
+你已经在看板上准备好了一堆 spec，现在就到了把它们变成真实代码的环节。一条 **rail** 就是一条"通道"，负责把一个 spec 推过完整的流水线——Architect → Developer → Reviewer → Ship——并在你的项目目录里运行真实的 AI Agent。本页会讲清楚如何启动一条 rail、任务队列是怎么回事，以及如何实时观看整个过程。
+
+## 什么是 rail
+
+可以把你的屏幕想象成左右两半：
+
+```
+SpecsBoard (left)            Rails (right)
+─────────────────            ─────────────────
+#1 Login flow      ─┐
+#2 Webhook retry    │  drag onto
+#3 Cost limits      │ ────────────►   Rail 1   ▶ Play
+#4 Audit log        │
+                    └────────────►   Rail 2   ▶ Play
+```
+
+rail 是一条**执行通道**。你从 SpecsBoard 上拖一张 spec 卡片放到某条 rail 上，然后按下 **▶ Play**。这条 rail 就会启动流水线，从头到尾把这个 spec 做完——就在你项目的工作目录里，改文件、跑测试，样样都来。
+
+你可以同时拥有好几条 rail，把工作组织成一条条命名的通道（一条放你眼下专注的功能，另一条排在它后面候着）。关于多 rail 和批量运行的更多内容，请看 [批量实现与多功能](batch-implement-and-multi-feature)。
+
+## 在某个 spec 上启动一条 rail
+
+1. **把一张 spec 卡片拖**到某条 rail 上。该 spec 的 ID 会出现在这条 rail 的 spec 列表里。（不想拖？用 spec 卡片上的 **放入 Rail** 弹窗——它会为每条 rail 显示一个状态圆点，避免你把活儿丢进一条正忙的通道。）
+2. 如果你不想用默认模式，就**挑一个模式**——rail 头部的分段控件提供了 `Implement`、`Batch`，以及（仅限 Claude rail 的）`Ultra`。
+3. **按下 ▶ Play。**
+
+就这么简单。rail 会在你的项目里启动一个 AI CLI 进程，开始跑流水线。
+
+### rail 头部里有什么
+
+| 控件 | 作用 |
+|---------|--------------|
+| **状态标签** | `idle`、`running` 或 `failed`。这里没有单独的"completed"——任务干净地跑完后，rail 会回到 `idle`。 |
+| **spec 列表** | 分配给这条 rail 的 ID。可以再拖进来，也可以拖出去解除关联。 |
+| **模式控件** | `Implement` / `Batch` / `Ultra`——见下表。按 rail 单独记忆。 |
+| **Profile 选择器** | 运行哪个 Agent Profile（仅限 Claude rail）。只有当项目至少有一个 Profile 时才会出现。 |
+| **引擎选择器** | 这条 rail 用哪个已安装的提供方来跑——Claude、Codex 或 Gemini。仅当项目装有不止一个提供方时才显示。见 [为每条 rail 选择引擎](picking-an-engine-per-rail)。 |
+| **▶ Play / ■ Stop** | 启动或取消。 |
+
+### 三种 rail 模式
+
+| 模式 | 命令 | 作用 |
+|------|---------|--------------|
+| **Implement** | `/specrails:implement` | 一个任务覆盖这条 rail 上的所有 spec。跑完整的 Architect → Developer → Reviewer → Ship 流水线。日常默认选项。 |
+| **Batch** | `/specrails:batch-implement` | 一个任务，按依赖感知的批次（wave）依次处理 rail 上的各个 spec。最适合一组相关的 spec。 |
+| **Ultra** | Ultracode | Claude 自主实现每个 spec，**绕过**流水线。每个 spec 一个独立任务。仅限 Claude。 |
+
+Ultra 是个特例：它跳过 Agent 链条，把原始 spec 直接交给 Claude，让它用自己的原生工具去做。因为它比较"放飞"，所以按下 Play 会先弹出一个确认框，而且有一个按 rail 单独的模型选择器，让你在 Haiku / Sonnet / Opus 之间挑选。只有当 rail 的引擎是 Claude 时它才会出现。
+
+## 任务队列
+
+每次你按下 Play，这次 rail 的运行就成了一个**任务**。最该记牢的一条规则是：
+
+> **每个项目同一时间只跑一个任务。** 每个项目只有一条队列。在同一个项目内，同一时间只有一个 rail 任务在运行——其余的排在它后面，随着空位腾出而自动开始。
+
+这一点常常让那些"加了三条 rail，以为它们会并行跑"的人感到意外。它们不会——至少在同一个项目里不会。加 rail 只是把你的工作*组织*成通道，并不会让这些通道并发运行。
+
+**真正的并行是跨项目的。** 每个项目都有自己独立的队列，所以项目 A 里的一条 rail 和项目 B 里的一条 rail 可以同时运行、互不争抢。想要更高的吞吐量？多开几个项目。
+
+没有什么全局并发旋钮可调。唯一的自动节流是基于预算的：如果你设了每日预算（项目级或应用级），当当天的花费触到上限时，队列会自动暂停。
+
+## 实时观看运行
+
+在项目右侧栏的 **Jobs** 里能找到每一个任务——一个卡片列表，最新的在最前面。每张卡片显示一个状态徽章、Profile 徽章、优先级徽章、时长、成本，以及启动时用的命令。列表上方有：
+
+- **状态筛选标签**——只显示某个状态的任务。
+- **日期范围筛选**——收窄到某个时间窗口。
+- **对比**——选两个任务并排查看。
+
+点击任意一张卡片，就能打开**任务详情视图**，实时流式日志和实时指标都在那里。这就是下一页的内容：[任务详情视图](the-job-detail-view)。
+
+## 取消一个任务
+
+点击 rail 头部的 **■ Stop**。应用会向子进程发送 `SIGTERM`，等 **5 秒**让它干净退出，然后再 `SIGKILL` 掉它。不会留下半生不熟、还没启动完的进程。
+
+## 如果一条 rail 启动不起来
+
+如果你选了一个对应 CLI 还没装到机器上的引擎，启动会**快速失败**，而不是开一个坏掉的任务——什么都不会启动。装上缺失的提供方 CLI（[使用 Codex](../integrations/using-codex)、[使用 Gemini](../integrations/using-gemini)）再启动一次即可。缺 Claude 或 Codex 时会给出精确的 "*<provider> CLI not found*" 提示；缺 Gemini 目前会显示一个通用的启动错误，但结果是一样的。
+
+## 全部停下
+
+如果哪里看起来不对劲：
+
+- **某一条 rail**——点击它头部的 **■ Stop**。
+- **预算自动暂停**——设一个每日预算，当当天花费触到上限时队列会自我暂停。
+- **全部**——退出桌面应用，或运行 `specrails-desktop stop`。
+
+## 接下来去哪儿
+
+- [任务详情视图](the-job-detail-view)——阶段、实时指标、工单卡片。
+- [批量实现与多功能](batch-implement-and-multi-feature)——一次跑多个 spec。
+- [为每条 rail 选择引擎](picking-an-engine-per-rail)——Claude、Codex 还是 Gemini。

package/docs/guide/zh/pipeline/2-the-job-detail-view.md

@@ -0,0 +1,90 @@
+# 任务详情视图
+
+在 **Jobs** 页面点击任意一张任务卡片，你就来到了这里：观察单次 rail 运行的"驾驶舱"。它围绕一个承诺打造——**你看到的实时数字都是真实的，绝不是猜出来的。** 本页会带你逐一了解各个阶段、实时指标和工单卡片。
+
+## 布局
+
+完整的流式日志上方坐着两个面板：
+
+```
+┌─────────────────────────────────────────────┐
+│  Status header  (icon · live duration · …)  │
+├─────────────────────────────────────────────┤
+│  Ticket header  ( #12  #14  #15 )           │
+├─────────────────────────────────────────────┤
+│                                             │
+│  Streaming log  (auto-scroll · search · …)  │
+│                                             │
+└─────────────────────────────────────────────┘
+```
+
+## 流水线阶段
+
+对于 `Implement` 和 `Batch` 任务，整个运行会走过 slash 命令所定义的各个阶段——默认是：
+
+```
+Architect ──► Developer ──► Reviewer ──► Ship
+```
+
+每个阶段都是一个专门的 Agent，由 rail 的引擎在你的项目目录里调起：
+
+| 阶段 | Agent | 作用 |
+|-------|-------|--------------|
+| **Architect** | `sr-architect` | 规划实现方案。 |
+| **Developer** | `sr-developer` | 编写代码。 |
+| **Reviewer** | `sr-reviewer` | 审查产出。 |
+| **Ship** | （视情况而定） | 收尾：测试、提交、起草 PR。 |
+
+每个阶段由哪个 Agent 来处理，是由项目的 **Agent Profile** 决定的。基线三人组（`sr-architect`、`sr-developer`、`sr-reviewer`）始终在场；Profile 里的路由规则可以添加 Agent，或替换某个阶段由谁来跑。只有当命令确实定义了阶段时，阶段进度条才会出现——Ultracode 任务（绕过了流水线）不会显示进度条。
+
+## 实时指标——为诚实而设计
+
+状态头部是重头戏。它显示一个状态图标、一行描述任务*此刻*在做什么的活动说明、已执行步骤的计数，以及一排指标：
+
+| 指标 | 何时能看到真实值 |
+|--------|------------------------------|
+| **时长** | **实时。** 任务运行时有一个 1 秒一跳的计时器在往上加——这是唯一一个货真价实的实时数字。 |
+| **轮次** | 随着流式 assistant 事件陆续到达，逐步累加得出。 |
+| **Token** | 从同一条流里逐步聚合（对缺少 usage 字段的事件也能容忍）。 |
+| **成本** | 在任务结束前显示为 `—`，结束后揭晓为权威的 `total_cost_usd`。 |
+
+设计原则是：**运行途中绝不给近似值或估算值。** 时长之所以真实，是因为它不过就是一个时钟。轮次和 token 是从真实的流式活动里累加出来的。成本则是故意*不*在运行时估算的——它显示为待定，只有当提供方在任务结束时上报后，才会落定为最终的、权威的数字。如果某个数字看起来像在等待，那是有意为之——给你看的是真相，而不是预测。
+
+头部的标签和图标会映射到任务的状态，并且这个面板对 `running`、`completed` 和 `failed` 的任务一视同仁地渲染——所以一个已完成任务的详情视图，会把这些指标定格在它们的最终值上。
+
+## 工单卡片
+
+**工单头部**坐落在状态头部和日志之间。这是一张高级感的身份卡片，为这个任务触及的每个 spec 显示一枚 chip——它们是从启动命令里匹配出来的，因此精确反映了本次运行究竟是关于哪些工单的。
+
+- **2–3 个工单**——以一列 chip 的形式显示。
+- **4 个及以上**——折叠成一个紧凑的 `+ N more` 模式，带一个展开的箭头，让头部保持整洁。
+
+点击某枚 chip，会在**任务页面之上**打开该 spec 的详情——你不会丢失当前位置，也不会跳转路由。这是在你观看任务运行的同时，快速重读一遍"这个任务应该交付什么"的便捷方式。（在平板宽度的屏幕上，你甚至可以把一个工单弹窗拖到一旁，把两个 spec 并排对比。）
+
+## 流式日志
+
+面板下方是本次运行的完整日志，通过 WebSocket 实时流式传输：
+
+- **自动滚动**让最新的输出始终在视野内（往上滚就会暂停，方便你阅读）。
+- **搜索**可以跳到某个短语。
+- **复制**可以一把抓走整个日志。
+
+这就是 AI 正在做什么的原始真相——每一次工具调用、每一次文件编辑、每一次测试运行。
+
+## 诊断导出
+
+如果该任务启用了[遥测](../settings/customizing)，头部会出现一个**导出诊断**按钮。它会下载一个 ZIP，里面包含：
+
+- `job-metadata.json`——命令、状态、Profile、插件。
+- `telemetry.ndjson`——未压缩的 OTLP/JSON 信号。
+- `logs.txt`——完整的流式日志。
+- `summary.md`——人类可读的要点摘要。
+- `profile.json`、`plugins.json`——本次运行内容的精确快照（存在时）。
+
+无论是和队友分享一次运行，还是提交一份精确的 bug 报告，都很顺手。
+
+## 接下来去哪儿
+
+- [Rail 与任务](rails-and-jobs)——启动与排队。
+- [批量实现与多功能](batch-implement-and-multi-feature)——多个 spec、依赖批次。
+- [追踪成本](../analytics/tracking-cost)——把单任务成本汇成项目级分析。

package/docs/guide/zh/pipeline/3-batch-implement-and-multi-feature.md

@@ -0,0 +1,78 @@
+# 批量实现与多功能
+
+一次做一个 spec 当然没问题，但现实里的活儿常常是成串来的——一个功能加上它的测试、再加上它的迁移，或者一个你想一口气清空的待办列表。本页讲的是把多个 spec 放在一起跑：Batch 模式、依赖批次，以及流水线是如何防止并发工作互相打架的。
+
+## 一次跑多个 spec
+
+从一条 rail 跑一堆 spec，最简单的方式就是 **Batch** 模式：
+
+1. **把所有你想跑的 spec 都拖**到同一条 rail 上。它们会在这条 rail 的 spec 列表里堆起来。
+2. **把这条 rail 的模式切到 Batch**（rail 头部的分段控件）。
+3. **按下 ▶ Play。**
+
+这条 rail 会启动**一个** `/specrails:batch-implement` 任务，逐一处理每个分配进来的 spec。像监控其他任务一样在 Jobs 页面上盯着它就行——它是覆盖整组 spec 的单个任务，而不是每个 spec 一个任务。
+
+这一点之所以重要，是因为有那条**每个项目一个任务的队列**规则。既然一个项目同一时间只跑一个 rail 任务，Batch 模式也就成了把一串 spec*串起来*的最干净方式，免得你去摆弄多条 rail、还要等每条逐个排空。
+
+### Implement 还是 Batch——选哪个？
+
+| | **Implement** | **Batch** |
+|---|---|---|
+| 命令 | `/specrails:implement` | `/specrails:batch-implement` |
+| 每个任务的 spec | rail 上的全部，当作一个工作单元 | rail 上的全部，**依次**处理 |
+| 最适合 | 一个紧密耦合的变更 | 几个想按顺序清掉的、彼此独立的功能 |
+| 顺序 | 不适用 | 依赖感知的批次（见下文） |
+
+如果这些 spec 真的属于同一个变更，用 **Implement**。如果它们是一串各自独立的功能，用 **Batch**，让它来排定顺序。
+
+## 依赖批次
+
+Batch 模式并不是简单地从上到下挨个跑 spec——它会计算出一个**依赖感知的执行顺序**，把 spec 分成一个个*批次（wave）*。编排器（`/specrails:batch-implement`）会算清楚哪些 spec 依赖哪些，然后排好日程，确保没有任何东西会跑在它所依赖的工作之前。
+
+概念上是这样的：
+
+```
+Wave 1:  #2 (data model)        ← no dependencies, runs first
+Wave 2:  #4 (API on the model)  ← waits for #2
+         #5 (CLI on the model)  ← waits for #2
+Wave 3:  #7 (docs across all)   ← waits for #4 and #5
+```
+
+在这个任务内部，每个批次的 spec 都会在下一个批次开始之前实现完。你不需要手动配置这些——编排器会从 spec 本身推导出批次。在[任务详情视图](the-job-detail-view)里看着它一步步展开：流式日志会讲述这一批正进行到哪个 spec，而工单头部会显示这个任务触及的每一个 spec。
+
+## Worktree 隔离
+
+当多个 spec 在一次运行中被实现时，流水线会让每个工作单元保持隔离，这样并发或顺序的改动就不会把彼此的文件搞乱。批量编排器会在各自干净的工作上下文里实现每个 spec，然后再把结果整合起来——所以一个做了一半的 spec，绝不会把你的工作树留在一个对下一个 spec 可见的、破碎的中间状态里。
+
+落到实处就是：
+
+- 每个 spec 都得到一块干净的画布去实现，而不是接手上一个 spec 半路上的编辑。
+- 审查和 ship 步骤面对的是一个连贯一致的快照，而不是一个动来动去的靶子。
+- 某个批次里的失败会被隔离开——它不会悄悄毁掉那些已经 ship 出去的 spec。
+
+应用会针对每个任务，精确记录下哪些文件被改动过、以及是哪个工单改动了它们（你会在 **Code** 区看到它以来源标记 chip 的形式出现，也会在每个 spec 的详情弹窗里看到一份"本工单触及的文件"列表）。正是这份归因，让你能放心地相信一次多 spec 的运行：你随时可以把一个文件改动追溯回造成它的那个 spec。
+
+## 跨项目的多功能
+
+如果你想要真正的并行——两个大功能同时在做——那就把它们**跨项目**拆开，而不是塞进同一个项目里的多条 rail。每个项目都有自己独立的队列，所以：
+
+```
+Project A   ▶ Rail running feature X   ┐
+                                       ├─ run simultaneously
+Project B   ▶ Rail running feature Y   ┘
+```
+
+没有全局并发上限，项目之间也没有争抢。两个都开着，各启动一条 rail，它们就会一起推进。唯一共享的节流是你的预算上限，它会在当天花费触到上限时，按项目或按应用级暂停队列。
+
+## 大批量的小贴士
+
+- **先把相关的 spec 凑到同一条 rail 上**，再切到 Batch——依赖批次只看得见这条 rail 上的内容。
+- 在跑一个大批量之前**设一个每日预算**，这样一次意外昂贵的运行会自动暂停，而不是失控狂奔。在 [预算](../settings/customizing) 下配置它。
+- 事后在 Jobs 页面**用对比按钮**把两次批量运行并排做 diff。
+- **导出一份诊断**（如果当时开了遥测），就能拿到整批运行的精确 Profile + 插件快照。
+
+## 接下来去哪儿
+
+- [Rail 与任务](rails-and-jobs)——深入理解队列模型。
+- [任务详情视图](the-job-detail-view)——实时观看一次批量运行。
+- [为每条 rail 选择引擎](picking-an-engine-per-rail)——注意 Batch 可在任意提供方上运行；Ultra 仅限 Claude。

package/docs/guide/zh/pipeline/4-picking-an-engine-per-rail.md

@@ -0,0 +1,60 @@
+# 为每条 rail 选择引擎
+
+Specrails desktop 把 **Claude Code**、**Codex CLI** 和 **Gemini CLI** 都当作一等公民的引擎。一个项目可以装其中一个、两个，或三个全装——而当装的不止一个时，你就能为每条 rail 选择用哪个引擎。本页讲解按 rail 的引擎选择器，以及什么时候该选哪一个。
+
+## 选择器何时出现
+
+**引擎选择器**就在 rail 头部，紧挨着模式控件。只有当项目装了**不止一个**提供方时它才会出现。
+
+> **单提供方项目的行为逐字节一致。** 如果一个项目只装了一个引擎，就不会显示选择器，提供方选择相关的一切也都不会变——它就直接在那个引擎上跑。这个选择器纯粹是给多提供方项目用的。
+
+当它确实出现时，你的选择是**按 rail、按每次启动**生效的——不同的 rail 可以跑不同的引擎，而你的选择会按项目记住（默认为项目的主引擎）。
+
+## 如何选择一个引擎
+
+1. 确认这条 rail 的引擎选择器正在显示（项目有 2 个及以上提供方）。
+2. 点开它，选 **Claude**、**Codex** 或 **Gemini**。
+3. 用 **▶ Play** 启动这条 rail。
+
+被选中的引擎会跑这条 rail 流水线的每一个阶段。如果所选引擎对应的 CLI 没装，启动会快速失败——什么都不会启动。装上缺失的 CLI 再试一次即可。
+
+## 每个引擎擅长什么
+
+三者都能跑标准的 **Implement** 和 **Batch** 流水线。下面是一份实用的选择指南：
+
+| 引擎 | 在什么情况下选它…… | 说明 |
+|--------|--------------------|-------|
+| **Claude** | 你想要全套功能：Agent Profile、Ultracode、原生成本上报、最丰富的工具支持。大多数工作的默认之选。 | 唯一支持 **Agent Profile**、**Ultracode** 以及几个 Claude 专属 spec 功能（Contract Layer、SMASH）的引擎。 |
+| **Codex** | 你更喜欢 OpenAI Codex CLI，或想跨提供方对比实现。 | `codex` ≥ 0.128.0。无原生成本上报——应用会用自己的价格表来补上成本。Profile 不适用。 |
+| **Gemini** | 你想用 Google 的 Gemini CLI、原生遥测，或为常规 spec 跑得更省钱。 | `gemini` ≥ 0.11.0（需设置 `GEMINI_API_KEY`）。原生 OTLP 遥测。Profile 不适用。 |
+
+### Claude 专属功能
+
+有几样东西只在 Claude rail 上能用——如果你需要它们，就选 Claude：
+
+- **Agent Profile**——按 Agent 的模型路由。在 Codex 或 Gemini rail 上，运行始终走传统模式，所选的任何 Profile 都会被**忽略**。非 Claude 引擎下 Profile 选择器会被隐藏。
+- **Ultracode（`Ultra` 模式）**——那个自主的、绕过流水线的模式。`Ultra` 分段及其 Haiku/Sonnet/Opus 模型选择器，只有当 rail 的引擎是 Claude 时才会出现。
+- **Contract Layer 与 SMASH**——Claude 专属的 spec 优化功能（这些是 Add Spec 的选项，不是 rail 的选项，但同样的限制适用）。
+
+如果一个项目混用了引擎，右侧栏只会显示**每一个**已安装提供方都支持的区块——所以在一个含有任何非 Claude 提供方的项目上，**Agents** 区会彻底消失，因为 Profile 是 Claude 特有的。
+
+## 一套实用的工作流
+
+多提供方项目在你想要**对比**或**调成本**时格外出彩：
+
+- **对比实现。** 把同一个 spec 放到两条 rail 上，一条设为 Claude、一条设为 Codex，两条都启动（跨项目，或在同一个项目的队列里一前一后），然后用 Jobs 页面上的**对比**按钮来 diff 结果。
+- **按 spec 调成本。** 高风险的 spec 用 Claude 配 `max` Profile 来跑；常规清理类的 spec 用 Gemini 跑以省钱。在 `/analytics` 里按引擎筛选，看清各自的明细。
+- **设好合理的默认。** 把你最常用的引擎设为项目的主引擎，让 rail 默认用它，只在某个特定 spec 想换引擎时才按 rail 临时切换。
+
+## 几点需要记住
+
+- **提供方选择在项目创建后不可更改**（v1）。你在添加项目时选定要安装的提供方；之后没有 Settings 开关可以再增删。
+- **成本始终会被追踪**，即便是不原生上报成本的引擎——应用会回退到价格表，让 Codex 和 Gemini 的运行也照样出现在[分析](../analytics/tracking-cost)里。
+- 在多提供方项目上，**终端的"Open AI CLI"按钮**也会提供一个提供方选择器，方便你想手动驱动某个 CLI 时使用。
+
+## 接下来去哪儿
+
+- [使用 Codex](../integrations/using-codex)——安装与登录。
+- [使用 Gemini](../integrations/using-gemini)——安装、`GEMINI_API_KEY`、遥测。
+- [Rail 与任务](rails-and-jobs)——队列与启动流程。
+- [追踪成本](../analytics/tracking-cost)——按引擎的成本明细。

package/docs/guide/zh/settings/1-themes.md

@@ -0,0 +1,37 @@
+# 主题
+
+让 Specrails 看起来更合你的心意。应用内置了五套精心调校的主题，可以随时一键切换——无需重启、无需重新构建，也不用做任何配置。
+
+## 五套内置主题
+
+| 主题 | 风格 |
+| --- | --- |
+| **Specrails** | 默认主题。平衡、沉稳，贴合品牌调性。 |
+| **Dracula** | 经典暗紫色。夜间使用更护眼。 |
+| **Aurora Light** | 明亮通透的浅色主题，适合白天工作。 |
+| **Obsidian Dark** | 深邃、高对比度的暗色模式。 |
+| **Matrix** | 黑底绿字，让你瞬间有种「身处主机内部」的感觉。 |
+
+## 如何切换
+
+1. 打开 **Settings**（应用级设置弹窗）。
+2. 进入 **Appearance** 板块。
+3. 选一套主题。它会立即应用到整个应用。
+
+就这么简单。你一点击，改动便即时生效——界面会实时换肤。
+
+## 应用范围
+
+你选择的主题是**应用级**的，而非按项目区分。所有项目、所有页面、所有面板都会遵循同一套主题。它甚至还覆盖了一些你可能想不到的地方：
+
+- **终端面板**会实时重新着色，同时保留你的回滚记录和任何正在运行的 shell 会话。
+- Analytics 页面上的**图表**会重新调色以保持一致。
+- Code 查看器中的**代码语法高亮**也会跟随主题变化。
+
+## 它会记住你的选择
+
+你的选择会随应用一起保存，因此重启之后依然有效。为了避免应用首次打开时短暂闪现错误的配色，Specrails 会在界面尚未加载完成之前就应用你保存的主题——所以从第一帧起，你看到的就是正确的样子。
+
+## 给好奇者的小贴士
+
+主题构建在一小套语义化的颜色角色之上（比如一个「强调」色、一个「表面」色等等），而不是写死的固定色值。正因如此，新增下一套主题才会如此轻松，每套主题内部也始终保持一致——每套主题只是重新映射这些角色而已。使用时你完全不必关心这些细节；这只是它为何能如此无缝切换的原因。

package/docs/guide/zh/settings/2-language.md

@@ -0,0 +1,39 @@
+# 语言
+
+Specrails 会说你的语言。整个界面已完整翻译成八种语言，并且默认会跟随你电脑设置的语言——所以对大多数人来说，首次启动时它就直接以正确的语言呈现。
+
+## 支持的语言
+
+- English（英语）
+- Español（西班牙语）
+- Français（法语）
+- Deutsch（德语）
+- Português（葡萄牙语）
+- Italiano（意大利语）
+- 中文
+- 日本語（日语）
+
+## 默认跟随操作系统语言
+
+你第一次打开 Specrails 时，它会查看操作系统的语言偏好，并匹配到最接近的受支持语言。如果你的 Mac 或 PC 设为西班牙语，你看到的就是西班牙语。如果设的是某个地区变体（比如 `es-ES` 或 `zh-Hans-CN`），Specrails 会自动将其映射到对应的基础语言。
+
+你什么都不用做——只要你从不去碰语言设置，Specrails 就会一直跟随你的操作系统。日后更改电脑的语言，Specrails 也会随之跟进。
+
+## 自己选择语言
+
+想用一个不同于操作系统默认的语言？直接手动指定即可：
+
+1. 打开 **Settings**。
+2. 进入 **Language** 板块。
+3. 选择你的语言。
+
+切换是**即时**的——整个界面会以新语言重新渲染，无需重启。一旦你做出明确选择，Specrails 就会记住它并停止跟随操作系统，从此每次打开应用都尊重你的选择。
+
+## 哪些内容会被翻译
+
+界面上你读到的一切——按钮、标签、状态消息、页面标题、对话框。日期也会适配你选择的语言，按该语言惯用的格式来呈现。
+
+## 值得了解的几点
+
+- **英语是源语言。**如果某个全新功能在翻译完成之前就发布了，你可能会在个别地方短暂看到英文标签——它会在后续更新中被翻译。
+- 你选择的语言是**应用级**的，所有项目中保持一致。

package/docs/guide/zh/settings/3-pipeline-telemetry-and-diagnostics.md

@@ -0,0 +1,46 @@
+# 流水线遥测与诊断
+
+当一个流水线任务的运行结果不如你所料时，遥测能为你提供一份详尽的幕后记录，告诉你 AI CLI 实际做了什么。它**默认关闭**、完全按需开启、按项目独立配置——只有在你需要时才开启它。
+
+## 它是什么
+
+遥测会采集 AI CLI 在运行流水线任务过程中发出的结构化诊断信号（追踪、指标和日志）。可以把它想象成流水线运行的「黑匣子」：耗时、token 用量、逐步活动，全都在本地采集下来，方便你事后回溯检查某个任务。
+
+它构建于 **OpenTelemetry** 之上——这是一种开放的标准格式，所以这些数据不会被锁死在某个专有体系里。
+
+## 开启遥测
+
+遥测**按项目**配置：
+
+1. 打开该项目的 **Settings** 页面（项目级设置路由）。
+2. 找到 **Pipeline telemetry**（流水线遥测）开关。
+3. 把它打开。
+
+从此刻起，该项目中的流水线任务都会记录遥测。其他项目不受影响——每个项目自行决定。
+
+### 覆盖范围
+
+遥测适用于**流水线任务**（即排入队列的 Architect → Developer → Reviewer → Ship rail 运行）。像聊天、安装向导这样的交互式会话被有意排除在外——遥测面向的是可重复、可检查的流水线运行，而非一次性的对话。
+
+## 数据存放在哪里
+
+一切都留在你自己的机器上，位于你的主目录下（`~/.specrails/`）——绝不会进入你的仓库。原始记录会以压缩形式与对应任务一同存放，较旧的记录会在一周后自动浓缩成紧凑的摘要以保持整洁。这些你都无需手动管理。
+
+## 导出诊断包
+
+遥测带来的最实用能力，就是**导出诊断**——一个把某个任务的全部信息打包在一起的 ZIP，用于排查问题或对外分享。
+
+当某个任务记录了遥测后，它的任务卡片上会出现一个**导出按钮**。点击它即可下载一个 ZIP，内含：
+
+- **`job-metadata.json`** —— 任务的标识与参数
+- **`telemetry.ndjson`** —— 采集到的原始信号
+- **`logs.txt`** —— 捕获的日志输出
+- **`summary.md`** —— 一份人类可读的运行摘要
+
+如果该项目使用了插件，诊断包还会包含一份快照，记录该任务运行时哪些插件处于激活状态。
+
+当你想弄清楚一次棘手的运行、留存一份记录，或把细节交给帮你排查的人时，这就是该抓取的那个包。
+
+## 关闭遥测
+
+随时把开关重新关掉即可。新任务会立即停止记录。已经采集到的内容会保留在磁盘上，直到它被浓缩，或你移除该项目——不会有任何东西在你不知情的情况下被发送到别处或丢失。