specrails-desktop 2.64.2 → 2.65.0

package/docs/guide/pt/settings/8-accessibility.md

@@ -0,0 +1,23 @@
+# Acessibilidade e personalização {#accessibility}
+
+O Specrails adapta-se à sua forma de trabalhar. Tudo isto está em **Definições ▸ Aparência**, aplica-se de imediato e fica guardado neste computador.
+
+## Densidade {#density}
+
+**Confortável** mantém os cartões e as linhas arejados. **Compacta** cabe mais no ecrã: o quadro de specs começa em linhas compactas, a lista de jobs usa linhas mais justas e a história do job aperta a sua linha do tempo. Uma vista guardada do quadro mantém o seu próprio layout, por isso uma vista guardada com cartões tipo post-it continua a abrir como cartões tipo post-it. Se o quadro deste projeto já tem o seu próprio esquema, **Usar também no quadro**, por baixo da escolha, faz com que volte a seguir a densidade.
+
+## Reduzir movimento {#reduce-motion}
+
+**Seguir o sistema** respeita o seu sistema operativo. **Reduzir** desativa animações e transições dentro do Specrails, diga o que disser o sistema: a pílula do rail fica parada na sua posição, os pontos em direto deixam de pulsar e o halo do Builder e os efeitos de tema ficam quietos. **Movimento total** anima mesmo quando o sistema pede menos.
+
+## Mover uma spec com o teclado {#keyboard-moves}
+
+Foque um cartão de spec no quadro (Tab ou setas) e prima **M**. Um pequeno seletor lista os estados e os rails; escolha com as setas e **Enter**. Faz o mesmo que arrastar o cartão até lá, incluindo as specs ligadas ao Jira, que se movem pelo seu fluxo do Jira. Se o cartão fizer parte de uma seleção múltipla (**X** seleciona o cartão em foco), o movimento aplica-se a todas as specs selecionadas. A paleta de comandos oferece o mesmo como **Mover a spec em foco…**. **M** não faz nada enquanto escreve num campo.
+
+## Avisos de execução para leitores de ecrã {#live-status}
+
+O Specrails anuncia as alterações dos runs através de uma região em direto educada, para o projeto que está a ver: um run iniciado, em pausa, que precisa de si, falhado, concluído ou com a revisão pronta. As rajadas são fundidas e as repetições descartadas, por isso um rail muito ativo nunca inunda o leitor. Os avisos de anular já se anunciam sozinhos.
+
+## Foco do teclado {#focus}
+
+Cada botão, ligação, item de menu, cartão e linha de árvore mostra um anel de foco visível quando lá chega com o teclado. A informação que antes só existia num tooltip, como a referência da spec na faixa de um rail, também está disponível para quem usa teclado ou leitor de ecrã.

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

@@ -1,4 +1,4 @@
-# Specs e o backlog
+# Specs e o backlog {#specs-backlog}
 
 Uma **spec** é a unidade de trabalho que o pipeline de IA implementa. Pense nela como um ticket: um título, uma descrição do que quer fazer, uma prioridade e, opcionalmente, etiquetas. Quando lança o pipeline, os agentes de IA leem a spec e agem sobre ela — por isso, uma spec clara é o input mais importante para um bom resultado.
 
@@ -13,7 +13,27 @@ O quadro tem dois modos de visualização, alternados a partir de um botão na b
 - **Vista de post-its** (a predefinida) — mosaicos em forma de cartão com resumos curtos.
 - **Vista de lista** — linhas compactas de uma só linha.
 
-O **seletor de estados** da barra de ferramentas mostra cada estado como um chip próprio com contagem em direto — mais dois grupos inteligentes: **Ativas** (a predefinição — tudo o que ainda está em movimento: rascunhos, por fazer, em curso e em revisão) e **Todos** (tudo, com Concluído fixado no fundo). A sua escolha é lembrada por projeto e espelhada no URL, pelo que um refresh ou um link partilhado restaura a vista exata. Em projetos ligados ao Jira aparece ainda um menu de **estado Jira**, que lista os estados *reais* do fluxo de trabalho do quadro (os nomes tal e qual, p. ex. "Code Review", cada um com contagem em direto) agrupados sob o estado a que mapeiam — combina-se com os chips de estado. Também pode filtrar por **etiqueta**, e ordenar por **Predefinida**, **Ticket #** ou **Prioridade** (cada uma com um seletor ascendente/descendente).
+A barra de ferramentas das Specs tem duas linhas. A primeira reúne um campo de **pesquisa** (prima `/` para lá chegar; procura no título, `#número`, etiqueta ou chave do Jira), um único botão **Filtros**, os controlos de ordenação e vista, e **Nova spec**. A segunda linha é o **seletor de estados**: cada estado como um segmento próprio com contagem em direto, mais dois grupos inteligentes, **Ativas** (a predefinição: tudo o que ainda está em movimento, ou seja rascunhos, por fazer, em curso e em revisão) e **Todos** (tudo, com Concluído fixado no fundo). Quando a coluna é estreita, os estados menos usados recolhem-se num menu **Mais**, e o estado escolhido fica sempre visível. A sua escolha é lembrada por projeto e espelhada no URL, pelo que um refresh ou um link partilhado restaura a vista exata. **Filtros** abre um único painel com uma secção por dimensão: **etiquetas** (seleção múltipla) e, em projetos ligados ao Jira, **épico**, **sprint** e **estado Jira** (os estados *reais* do fluxo do quadro, p. ex. "Code Review", agrupados sob o estado a que mapeiam e combinados com o seletor de estados). Enquanto uma pesquisa ou um filtro restringe o quadro, uma terceira linha mostra cada um como um chip removível, indica "x de y" specs e oferece **Limpar tudo** (que mantém o estado escolhido). Ordene por **Predefinida**, **Ticket #** ou **Prioridade**, cada uma com um seletor ascendente/descendente.
+
+### Selecionar várias specs
+
+Faça a triagem em lote em vez de uma spec de cada vez. Pressione `x` em um cartão em foco, clique em um cartão com `Ctrl`/`⌘` ou clique com `Shift` para selecionar um intervalo (um intervalo fica dentro de uma coluna: as specs ativas ou o grupo Concluído). `Ctrl`/`⌘`+`A` seleciona toda a coluna em que você está e `Esc` limpa a seleção. Cada cartão mostra uma caixa de seleção ao passar o mouse ou receber foco, e os cartões selecionados têm a borda destacada. Nenhuma dessas teclas age enquanto você digita no campo de busca.
+
+Assim que uma spec é selecionada, uma barra flutuante aparece na parte inferior do quadro com a contagem e as ações:
+
+- **Mover para** muda o estado. As specs locais recebem os estados locais; as que vêm do Jira recebem os estados reais do fluxo do quadro do Jira e passam pela mesma fila do Jira que um movimento individual.
+- **Etiqueta** adiciona uma etiqueta à seleção, ou remove uma que as specs já tenham.
+- **Prioridade** define uma mesma prioridade para todas.
+- **Adicionar a um rail** coloca a seleção em um rail.
+- **Lançar tudo** dá a cada spec selecionada seu próprio rail livre e as inicia em paralelo, após a mesma confirmação e verificação do orçamento diário do *Lançar tudo* dos rails. Specs que ainda não podem ser lançadas (por exemplo, em revisão sem PR aberta) ou que não encontram um rail livre são ignoradas e contadas no resumo.
+- **Excluir** envia as specs para *Excluídas recentemente*.
+- **Limpar** (ou `Esc`) descarta a seleção.
+
+Excluir e alterar estado, etiquetas ou prioridade podem ser desfeitos em uma única etapa: um só aviso *Desfazer* (ou `⌘Z`) restaura todas as specs alteradas. Se algumas falharem, um único aviso diz quantas deram certo e quantas não. A seleção só contém specs que você vê: um filtro que oculta uma spec selecionada a tira da seleção.
+
+### Visões salvas
+
+O botão **Visões**, ao lado de **Filtros**, salva o quadro como está agora: o seletor de estado, os filtros, a ordenação e a densidade (não o texto da busca). Escolha **Salvar a visão atual…**, dê um nome («Prontas para lançar», «Sprint 42», «Falhas desta semana») e escolha-a depois no mesmo menu. **Gerenciar visões…** renomeia uma visão, atualiza-a com o quadro como está, copia o link ou exclui. As visões pertencem ao projeto. Um link copiado (`?view=…`) aplica a visão quando aberto neste aplicativo, e a paleta de comandos (`⌘K`) pode salvar a visão atual ou trocar para outra.
 
 ## Estados
 
@@ -38,7 +58,7 @@ Os rascunhos são a única exceção: um rascunho pode *não* ter prioridade nen
 
 ## Criar uma spec
 
-Para criar uma spec, clique em **Adicionar** (o botão Mais na barra de ferramentas da SpecsBoard). Abre-se a janela **Adicionar Spec** com algumas formas de trabalhar:
+Para criar uma spec, clique em **Nova spec** (o botão Mais na barra de ferramentas da SpecsBoard). Abre-se a janela **Adicionar Spec** com algumas formas de trabalhar:
 
 - **Quick** — descreve o que quer e a IA escreve a spec completa de uma só vez. Veja [Adicionar Spec — modo Quick](add-spec-quick-mode.md).
 - **Explore** — conversa com a IA, e ela ajuda-o a dar forma à spec turno a turno. Veja [Adicionar Spec — modo Explore](add-spec-explore-mode.md).
@@ -50,6 +70,24 @@ Qual escolher depende do quão clara já está a ideia. Sabe exatamente o que qu
 
 Quando uma spec já tem trabalho por trás — uma PR em revisão, uma funcionalidade integrada — e quer *mais*, não reescreva a descrição: isso desvirtua a spec (e sincroniza o desvio com o Jira) e obriga a próxima execução a replanear tudo. Abra a spec e adicione um **adendo**: uma nota curta com um tipo (pedido de alteração, feedback de revisão, esclarecimento, restrição) e as suas palavras. Os adendos abertos seguem automaticamente com o próximo lançamento dessa spec em qualquer loop — Implement, SDD Quick, Freestyle — para que a execução altere apenas o que pediu, e o pacote de revisão reporta cada um como aplicado, parcialmente aplicado ou bloqueado. Se a execução falhar ou descartar a entrega, voltam sozinhos a **Aberto**. O agente de missão pode adicioná-los por si quando lhe pede para alterar algo numa spec existente.
 
+## Revisar uma entrega: o que olhar primeiro
+
+Quando uma execução termina, o pacote de revisão abre com **O que olhar**: o resumo curto do revisor de IA com os pontos mais arriscados primeiro (alto, depois médio, depois baixo, cada um com arquivo e linha), o comportamento que muda, as regras em que a mudança se apoia, os caminhos de código que nenhum teste exercita e as verificações que só uma pessoa pode fazer. Os mesmos riscos, caminhos sem teste e verificações aparecem num bloco curto no topo da pull request, e o card da missão mostra o principal risco em uma linha. O resumo orienta a revisão, não é um resultado de verificação: nunca bloqueia Aceitar. Execuções feitas com um Specrails Core anterior não têm resumo e o pacote continua igual.
+
+## Desfazer e Excluídos recentemente {#recently-deleted}
+
+Excluir uma spec, movê-la para outro estado, mudar suas etiquetas ou tirá-la de um rail acontece na hora — sem um "Tem certeza?" antes. Em vez disso, um aviso oferece **Desfazer** por cerca de oito segundos, e **⌘Z** (**Ctrl+Z** no Windows e no Linux) faz o mesmo enquanto você não estiver digitando em um campo. Desfazer é por projeto: trocar de projeto encerra a janela.
+
+Uma spec excluída (e uma missão excluída) não desaparece. Ela vai para **Configurações → Excluídos recentemente**, nas configurações do projeto, onde você pode **Restaurá-la** por 30 dias ou **Excluí-la definitivamente**, o que pergunta antes. Depois de 30 dias ela é removida de vez. Descartar trabalho não enviado, fechar à força uma pull request e remover um projeto continuam perguntando antes, porque não podem ser revertidos. Uma spec ligada ao Jira continua sendo movida com **Mover para**, em vez de excluída.
+
+## A cronologia da spec e a passagem {#spec-timeline}
+
+Abra uma spec e passe para o separador **Cronologia** para ler toda a sua história num só sítio: as edições e adendas, as missões que lhe tocaram, cada execução com as suas fases e ações do agente, os eventos do pull request e o veredito do revisor com os seus achados. As entradas são agrupadas por dia, os chips filtram por tipo e cada entrada liga à missão, execução ou revisão de onde vem. Os grupos longos (fases, ações do agente, turnos de missão) ficam recolhidos com uma contagem e expandem no próprio sítio.
+
+O custo aparece junto da entrada que o gerou, com os dois tipos separados: um valor reportado pelo fornecedor e outro estimado pela tabela de preços local (marcado «est.»). Se um fornecedor é faturado por um plano, a cronologia e as exportações mostram turnos, nunca dólares; uma execução que não reportou custo simplesmente não o mostra.
+
+**Exportar passagem** (o menu junto aos separadores, ou ⌘K → *Exportar passagem de #N*) gera um ficheiro Markdown ou uma página HTML autónoma com o resumo, as decisões (adendas, esclarecimentos, vereditos do revisor), as estatísticas do diff, o custo e o que continua em aberto (adendas abertas e achados de revisão por resolver). **Copiar como descrição de PR** (também no ⌘K) coloca uma versão mais curta em Markdown na área de transferência. Os títulos seguem o idioma da aplicação. Tudo passa pela mesma ocultação de segredos usada pela auditoria de ações do agente, e o aviso diz-lhe quando algo foi ocultado.
+
 ## Para onde ir a seguir
 
 - [Adicionar Spec — modo Quick](add-spec-quick-mode.md) — a forma mais rápida de transformar uma ideia numa spec.

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

@@ -6,7 +6,7 @@ O modo Quick é para quando já sabe o que quer. Escreve a sua ideia, a IA redig
 
 Para criar uma spec rapidamente:
 
-1. No Dashboard, clique em **Adicionar** (o botão Mais na barra de ferramentas da SpecsBoard).
+1. No Dashboard, clique em **Nova spec** (o botão Mais na barra de ferramentas da SpecsBoard).
 2. Escolha o modo **Quick**.
 3. Escreva a sua ideia no campo de texto — uma frase ou um parágrafo, o que melhor a capturar.
 4. Clique para gerar.

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

@@ -22,7 +22,7 @@ A conversa fica no seu histórico, por isso pode sempre voltar para ver como a s
 
 É este o coração do modo Explore: nunca está a olhar para um formulário em branco. Está sempre a olhar para uma spec real e em evolução.
 
-## Quanto é que a IA vê: o seletor de contexto
+## Quanto é que a IA vê: o seletor de contexto {#context-scope}
 
 Antes de a IA responder, decide quanto do seu projeto ela pode ver. Um seletor de presets de contexto permite-lhe trocar velocidade por profundidade:
 

package/docs/guide/zh/agents/1-meet-the-agents.md

@@ -1,4 +1,4 @@
-# 认识这些 Agent
+# 认识这些 Agent {#agents}
 
 当你启动一条 **Implement** rail 时，Specrails 并不会把你的 spec 丢给某一个 AI、然后听天由命。它会让一支精干的专职 *Agent* 团队上阵——每个 Agent 只负责一件事，并按精心设计的顺序协作。这一页就来介绍这支团队里都有谁、各自又在做什么。
 

package/docs/guide/zh/getting-started/2-installing-and-first-run.md

@@ -39,3 +39,5 @@ specrails 唯一无法内置的，是 **AI 提供商 CLI** 本身。你至少需
 整个上手流程就这么多——不用创建账号，也不用注册。specrails 完全在你的机器上运行。
 
 点击 **添加你的第一个项目**，继续阅读[添加你的第一个项目](adding-your-first-project)。
+
+或者先从[示例项目](try-the-sample-project)开始：一个小游戏和三份现成的规格，费用事先说明。

package/docs/guide/zh/getting-started/3-try-the-sample-project.md

@@ -0,0 +1,35 @@
+# 试用示例项目
+
+想在把 specrails 指向你自己的代码之前，先看看一份规格如何变成经过审阅的变更吗？**示例项目**是一个小型井字棋网页游戏，附带三份现成的规格。只需几分钟，最终得到一个真实的**审阅包**。
+
+## 开始
+
+在欢迎页点击**在示例项目上试一试**（位于**添加你的第一个项目**旁边）。在任何事情发生之前，对话框会告诉你：
+
+- **会创建什么**：一个带独立 git 仓库的小型网页游戏，看板上已有三份规格。
+- **创建在哪里**：默认为主目录内的 `~/Specrails Samples/tic-tac-toe`。你可以更改文件夹；已存在的文件夹绝不会被覆盖。
+- **一次运行的费用**：类似“≈ $0.30–$1 · 约 3–5 分钟”的估算。只有当你的提供商按用量计费时才以美元显示；订阅套餐会注明没有额外费用，本地引擎则没有 API 费用。
+
+创建示例不花钱，也不运行任何内容。点击**创建示例项目**，即可进入看板。
+
+## 三个步骤
+
+一张小小的向导卡片会逐步指向真实的看板。你可以随时关闭它；它会收起为**示例项目**小标签，点击**显示向导**即可恢复。
+
+1. **规格。** 这三份规格已为你写好。每份都说明了要构建什么，以及如何判断完成。
+2. **轨道。** 点击**运行第一份规格**。示例已设置为低成本且有上限：快速模式、可用的最便宜模型，以及每次运行的软上限（运行会在超过 $1 之前暂停并询问）。如果你配置了本地引擎，也可以选择它，无需 API 费用。
+3. **审阅。** 没有任何内容会自动合并。运行结束后，**审阅包**会展示改动内容，并让你接受或丢弃。
+
+## 没有可用的 AI 提供商？
+
+在提供运行之前，specrails 会检查是否已安装并登录了提供商。如果没有，你会看到**观看录制的运行**：回放一次已完成的运行，终点是一个审阅包。它被明确标注为录制内容；不会运行任何东西，也不会收费。安装提供商或登录后，选择**重新检查**即可切换到真实运行。
+
+## 然后，你自己的项目
+
+向导以**现在添加你自己的项目**收尾。用完示例后，点击**移除示例**即可一键注销。除非你勾选**同时删除示例文件夹**（此操作无法撤销），否则文件夹仍保留在磁盘上。
+
+## 重新播放平台导览
+
+导览已不在欢迎页。打开**文档**并选择**重新播放导览**，或打开命令面板并输入“重新播放导览”。它也在**设置 ▸ 外观**中。
+
+下一篇：[添加你的第一个项目](adding-your-first-project)。

package/docs/guide/zh/getting-started/{4-the-dashboard-tour.md → 5-the-dashboard-tour.md}

@@ -37,11 +37,15 @@
 - **总花费**（右侧）——你已花金额的实时累计，让成本始终一眼可见。
 - **终端开关**（最右侧）——打开内置的终端面板。随时按 **Cmd+J**（macOS）或 **Ctrl+J**（Windows/Linux）即可切换。它是一个完整的 shell，直接在你的项目文件夹里打开。
 
-## 几个顺手的快捷键
+## 几个顺手的快捷键 {#shortcuts}
 
-- **Cmd/Ctrl+B**——固定或收起侧边栏。
+- **Cmd/Ctrl+B**——固定或收起左侧边栏；**Option+Cmd+B**（**Ctrl+Alt+B**）对右侧边栏执行相同操作。
 - **Cmd/Ctrl+J**——切换终端面板。
-- **Cmd/Ctrl+K**——打开搜索。
+- **Cmd/Ctrl+K**——命令面板：搜索任务、项目和 job，并**执行操作**。输入动词（如“新建”“启动”“移动”“切换”）或以 **>** 开头即可列出操作：新建 Spec（也可用探索模式）、启动或移动 Spec、打开其评审、交接或暂停 Flow、新建任务、切换主题、在任务模式与看板模式之间切换、在指定分区打开应用或项目设置、运行 Loop、切换侧边栏、后退或前进、撤销上一次更改，以及最近删除。需要选择的操作（Rail、状态、主题、分区）会打开第二页；搜索框为空时按 **Backspace** 返回。每个操作都会显示它的快捷键，面板因此也在教你按键。它只提供当前位置可用的操作，并遵守与按钮相同的规则（无法启动的 Spec 不会出现）。搜索为空时会列出你的**最近操作**和**最近位置**。
+- **Cmd+[ / Cmd+]**（Windows/Linux 为 **Alt+← / Alt+→**）、标题栏中的 **←  →** 按钮，或鼠标的后退/前进键——在你去过的位置之间后退或前进：规格、任务、作业、项目和全屏面板。右键（或长按）按钮可查看最近的位置。
+- **Cmd+Shift+I**（Windows 和 Linux 上为 **Ctrl+Alt+I**）或标题栏中的**待处理**按钮 —— **待处理**列表：把所有项目中等你处理的事项集中在一个按项目分组的列表里。它汇集了可以决定的评审、代理正在等待的提问、失败或被阻塞的运行、因每日预算而暂停的运行，以及未能同步的 Jira 更新。每一行都带有主要操作（**打开评审**、**回答**、**继续**、**重试**），以及**稍后提醒**（1 小时或明天）和**完成**。被推迟或已完成的事项一旦状态变化会自动回来。按钮会显示有多少项在等待，服务商额度提示通知也会打开该列表。该列表还是一个链接（`?inbox=1`），并且是命令面板中的一个操作。
+- **M** — 在看板上聚焦某张规格卡片时,打开选择器把它移到某个状态或某条 Rail,相当于拖放的键盘版本。多选同样适用,命令面板中对应的是**移动聚焦的规格…**。
+- **?** — 快捷键速查表。在它的搜索框里输入内容，可以筛选快捷键，并找到本指南中匹配的页面和章节，它们会直接在指南中打开，无需离开当前界面。设置、轨道、Flow、上下文滑块和预算旁边的小 **ⓘ** 图标和**了解更多**链接，也会以同样方式打开指南的对应章节。
 
 ## 下一步去哪儿
 

package/docs/guide/zh/getting-started/6-universal-search.md

@@ -0,0 +1,34 @@
+# 通用搜索（⌘K）
+
+按 **⌘K**（Windows 和 Linux 上为 **Ctrl+K**），即可在同一处搜索 Specrails 中几乎所有内容：任务、Spec、作业日志、文件、设置和本指南。输入普通查询会像以前一样搜索任务、项目、Spec 和最近的作业；以**前缀**开头则只搜索某一类来源。
+
+## 前缀
+
+| 输入 | 搜索范围 | 按回车打开 |
+| --- | --- | --- |
+| `#` | Spec：标题、摘要、描述、标签、范围外说明、补充说明和评论。`#12` 可找到 12 号 Spec。 | 该 Spec |
+| `@` | 任务：标题和对话内容。 | 该任务 |
+| `/` | 设置（Desktop 和项目），可按名称或常用说法查找。 | 打开设置窗口并滚动、聚焦到对应区块 |
+| `f:` | 项目文件，按名称或路径。 | 在代码浏览器中打开该文件 |
+| `log:` | 作业日志：命令、循环名称、阶段标题和失败诊断。 | 该作业 |
+| `?` | 本指南：页面标题和小节标题。 | 指南中对应的小节 |
+
+输入前缀后，它会变成搜索框中的一个**标签**，输入框只保留你的查询。在输入框为空时按**退格键**（或点击标签上的 ×）即可取消范围。输入框为空时，面板会在其下方列出各个前缀，点击即可开始。`>` 仍然用于列出操作。
+
+## 高亮
+
+结果会显示首个匹配处周围的一小段文字，并高亮匹配内容。搜索忽略大小写和重音符号，因此 `revision` 可以找到 “Révision”。
+
+## 设置
+
+`/` 了解主要的设置区块，并使用你的语言：主题、语言、编辑器、预算、通知、Webhook、更新、分支、环境、遥测、规则等。打开项目后才会提供项目设置。选中一项，即可在对应区块打开正确的窗口。不带前缀时，强匹配（三个或更多字符）最多会向常规结果中添加三项设置。`/budget` 还能找到预算面板（上限、预测、假设分析），每周和每月的上限就在那里。像 `/implement` 这样的斜杠命令会单独成组列在设置下方，因此 `/` 前缀不会把它藏起来。
+
+## 作业日志
+
+`log:` 搜索的是一个精简索引，而不是运行的原始输出：命令、循环名称、阶段标题，以及失败、被阻塞或停滞的运行的简短诊断。它从不保存令牌流或工具输出，因此体积小、速度快。索引按项目保存，包含最近的运行。
+
+## 须知
+
+- `#`、`f:` 和 `log:` 搜索当前项目；请先打开一个项目。
+- 文件范围遵循代码浏览器的排除规则。
+- 每个分组只显示最佳的几条结果；可细化查询来缩小范围。

package/docs/guide/zh/insights/1-analytics-and-cost-tracking.md

@@ -6,15 +6,17 @@
 
 ## 什么算作支出
 
-Specrails 会追踪五类 AI 活动，我们称之为*来源*（surface）。每一类在所有图表中都使用统一的配色，方便你一眼认出：
+Specrails 会给每一次 AI 运行打上*来源*（surface）标签，也就是产生这笔支出的应用部分。主要来源各有固定的颜色和专属的筛选标签，让你一眼就能认出：
 
-- **任务（Job）**——一条跑着 Architect → Developer → Reviewer → Ship 的流水线 rail。
+- **任务（Job）**——排入队列的流水线任务（Architect → Developer → Reviewer → Ship），包括 Freestyle 运行。
+- **循环（Loop）**——循环运行中的每一个 AI 步骤。rail 默认以循环方式运行，所以 rail 的大部分支出都记在这里。
 - **Quick spec**——通过快捷的 Add Spec 路径生成的 spec。
 - **Explore spec**——通过聊天来打磨 spec 的 Explore 会话。
 - **AI 编辑（AI edit）**——对某个 agent 或文件做的 AI 辅助优化。
-- **文件摘要（File summary）**——为 Code 浏览器提供支撑的那些通俗易懂的摘要。
+- **SMASH**——把一个史诗级 spec 拆分成更小的 spec。
+- **文件摘要（File summary）**——为 Code 浏览器提供支撑的通俗摘要和文件故事。
 
-有两样东西是我们*故意*不去追踪的：聊天侧边栏和安装向导虽然也会启动 AI CLI，但它们永远不会出现在你的支出里。这样仪表盘反映的就是真实、可重复的工作，而不是顺手发生的闲聊。
+一些较小的来源也会被记录，只是没有专属的筛选标签：聊天侧边栏、OpenSpec spec 启动器、spec 提案、Agent Studio 以及旧版的安装聊天。固定到该项目的任务会话（mission）也计入它的支出。凡是运行 AI CLI 的活动都不会被遗漏，因此总额反映了项目的全部 AI 活动。
 
 ## 读懂仪表盘
 
@@ -76,3 +78,15 @@ Specrails 会追踪五类 AI 活动，我们称之为*来源*（surface）。每
 ## 保持实时
 
 你不用刷新。当项目中任何地方记录了一次新调用，正打开着的仪表盘会在稍后悄悄自我重新拉取一次，这样燃烧表就能跟上正在收尾的工作。
+
+## 每日预算 {#daily-budget}
+
+设置每日预算，限制一天最多能花多少。所有上限（每日、每周、每月和每次运行）都在同一处编辑：**分析 → 预算**。**设置 → 高级**和**项目设置 → 预算**只显示当前的每日上限，并提供**打开预算**按钮跳转到那里。
+
+当当天记录的花费达到预算时，队列会自行暂停，轨道和循环运行会拒绝启动并提示*已达到每日预算*，正在进行的循环运行会在步骤之间停下，因预算而暂停。提高或清除预算，或等待每日重置，然后继续。
+
+项目预算按你的本地日期计算，全应用预算按 UTC 日期计算。单个任务的费用提醒是另一项独立设置。
+
+**每周、每月和单次运行上限.** 更长周期的上限工作方式相同。打开**分析 → 预算**，可按项目或针对整个应用设置**每周**和**每月**上限，以及**单次运行软上限**（*达到 $X 时暂停并询问*）。每周从周一开始，每月从 1 日开始，按你的本地时间计算。每周或每月上限与每日预算完全一样：暂停队列、拒绝启动，并让正在运行的循环暂停；可在此调高或清除，也可等待重置。当某次运行自身上报的成本达到单次运行上限时，它会暂停，**恢复**时会询问是取消上限继续，还是调高上限。达到任何上限还会在收件箱中添加一条**调高上限**。
+
+预算面板会把今天、本周和本月与各项上限对照显示。月末**预测**只是估算（最近 14 个完整日的平均值乘以剩余天数，再加上已花费金额），不会与已结算的花费相加。**假设**会按应用的价格表，用另一个模型重新计算最近 30 天记录的 token 用量；对没有价格的模型会显示*没有价格*。订阅套餐下每次使用没有美元成本，因此面板显示回合数和套餐额度，而不是美元。

package/docs/guide/zh/insights/2-the-integrated-terminal.md

@@ -1,4 +1,4 @@
-# 内置终端
+# 内置终端 {#integrated-terminal}
 
 Specrails 内置了一个真正的终端——就是那个从窗口底部滑出来的面板，跟 VS Code 或 Cursor 里的那个一模一样。它运行的是你真实的 shell，在你真实的项目目录里，所以你可以直接跑 `git`、`npm`、测试，或者任何其他东西，而不用离开应用。
 

package/docs/guide/zh/insights/3-code-explorer.md

@@ -1,4 +1,4 @@
-# Code 浏览器
+# Code 浏览器 {#code-explorer}
 
 **Code** 板块给你一扇友好的、只读的窗口去看你的代码仓库——特别为那些想弄明白 AI 一直在搭些什么、又不想成天泡在编辑器里的人设计。左边是文件树，右边是代码查看器，而在代码上方，还有一段用大白话写成的摘要，告诉你每个文件到底在做什么。
 

package/docs/guide/zh/integrations/1-ai-providers.md

@@ -1 +1 @@
-# AI 提供方（Claude、Codex、、）
+# AI 提供方（Claude、Codex、、） {#ai-providers}

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

@@ -1,4 +1,4 @@
-# 插件（Integrations）
+# 插件（Integrations） {#plugins}
 
 **Integrations** 板块是按项目划分的可选插件市场，用来扩展 AI 能做的事。每个项目都独立决定自己想要哪些插件——在一个项目里安装插件，绝不会动到另一个项目。
 

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

@@ -15,7 +15,7 @@ Specrails 充当 Jira 和你项目之间的**同步层**。核心思路是：你
 
 ## 连接一个看板
 
-你从项目的 **Settings** 页面进行连接（在 Add-Project 向导的末尾，也有一个可选的「Configure Jira」步骤）。连接向导会带你走完：
+你从左侧边栏的 **插件** 页面进行连接：在 Jira 卡片上点击 **安装**，然后选择项目。连接向导会带你走完：
 
 1. **测试**——输入你的 Jira 网址和凭据，Specrails 会验证连接。
 2. **选择一个项目**——选定要与之同步的 Jira 项目。
@@ -52,7 +52,7 @@ Jira 的关联是**按规格**的，在你启动一条 rail 的那一刻被捕
 
 ## 日常使用
 
-连接之后，项目的 Settings 页面会显示一张**已连接卡片**，在那里你可以：
+连接之后，**插件** 页面上的 Jira 卡片会变为 **管理**。在那里选择项目即可打开它的**已连接卡片**，在那里你可以：
 
 - **立即同步**——强制马上轮询一次，而不必等计时器。
 - **重试死信**——重新执行任何卡住的回写。
@@ -69,4 +69,4 @@ Jira 的关联是**按规格**的，在你启动一条 rail 的那一刻被捕
 
 ## 关闭它
 
-如果你哪天想彻底退出，只需从 Settings 里**断开连接**。你的规格会回到纯本地行为，而那些 Jira 元数据就只是闲置不用——什么都不会被销毁。
+如果你哪天想彻底退出，只需在已连接卡片上**断开连接**。你的规格会回到纯本地行为，而那些 Jira 元数据就只是闲置不用——什么都不会被销毁。

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

@@ -1,4 +1,4 @@
-# 移动端伴侣应用
+# 移动端伴侣应用 {#mobile-companion}
 
 Specrails 有一个手机伴侣应用，让你离开座位时也能盯着自己的 rail——看任务在跑、看它们完成，不用守在仪表盘前也能随时掌握进展。
 

package/docs/guide/zh/integrations/5-mcp-server.md

@@ -1,4 +1,4 @@
-# 从任意 AI 操控 Specrails（MCP 服务器）
+# 从任意 AI 操控 Specrails（MCP 服务器） {#mcp-server}
 
 > **For agents (English):** use the [current connection runbook](../../../agents/mcp.md) for Claude and Codex. It includes verified bridge discovery, registration and read-only checks.
 

package/docs/guide/zh/integrations/6-agent-chat.md

@@ -33,6 +33,8 @@ Agent Chat 通过内嵌的 **Specrails MCP 服务器**来驱动应用，因此
 
 从**观察**开始，只有当你想让智能体动手时才提升级别。如果它尝试超出当前级别的操作，它会停下来，并准确告诉你需要切换到哪个级别——它绝不会绕过限制。这与 设置 ▸ MCP 的分级是相互独立的，后者管辖的是*外部*助手；这里的级别只针对这个应用内的智能体。
 
+提升到**自主**级别绝不会只凭一次按键完成：在“操作”级别按 Shift+Tab 会显示带有**切换到自主**的提示，再按一次 Shift+Tab 则会跳回“观察”。降低级别始终立即生效。
+
 ## 一些可以让它做的事
 
 进入**操作**后，试试：
@@ -47,16 +49,21 @@ Agent Chat 通过内嵌的 **Specrails MCP 服务器**来驱动应用，因此
 
 回复会顺滑地流式呈现，并已排版落地（标题、表格、列表），每一段都带一个小小的**复制**按钮。底部的状态标签会显示智能体此刻正在做什么——*思考中……*、*MCP · jobs*、*Terminal*——让你随时了解它的状态。
 
+代码块会显示其语言，并带有单独的**复制**按钮。如果在智能体仍在输出时向上滚动，输入框上方会出现**新消息**提示，点击即可回到最新回复。
+
 ## 贴心细节
 
 - **在对话中打造超级规格。** 让智能体和你一起*打磨*规格，而不是一次性生成：它会先阅读真实代码，简短地向你提问，并在对话中以实时卡片展示不断演进的草稿。你确认后它会创建规格，并默认在后台用 **Contract Layer**（精确的文件路径、数据形状、不变量）加以充实，让负责实现的智能体不必即兴发挥。说"不要 contract layer"即可跳过充实步骤。
 - **点击它提到的内容。** 在固定到某个项目的任务中，智能体回复里的规格编号（`#12`）和 job/run 的 id 都是可点击的标签——点规格会打开看板的详情弹窗，点 job id 会打开实时的任务视图。如果引用已不存在，会看到一条低调的"未找到"提示。
-- **实现卡片始终可见。** 当智能体为你实现规格时，一张实时卡片会跟踪这项工作——只要它还需要你做决定（创建 PR、发布、重试、丢弃），它就会**固定在消息框正上方**，无论对话滚动到哪里；它在历史记录中原来的位置会改为显示一条「已固定在上方」的细提示。多张活动卡片会以小标签的形式堆叠（点击即可把它换到前面），点击箭头可把卡片最小化成一条细栏。一旦 PR 发布——或工作被合并或丢弃——卡片就会回到对话历史中原来的位置。
+- **所有运行汇成一条。** 智能体启动工作后，消息框正上方的一条运行条会跟踪它：用平实的话说明运行正在做什么（“正在根据你的更改编写 spec”）、已完成的运行数、耗时，以及到目前为止的实际费用（提供商计费前显示 `—`）。当某个运行需要你时——创建 PR、重试、回到 Flow——运行条会用图标和文字说明，并只给出那一个操作；点击运行条即可在其正上方打开该运行的完整卡片（按 Esc 关闭）。有多个运行时，运行条会先显示需要你的那个，并附带一个小切换器（“Rail 1 · Rail 2 · +1”）。对话中只保留发生过的事（“已在 Rail 1 上启动”“Rail 1 失败：…”“已交付：PR #812”），每一行都能打开对应的运行。等待你决定的任务会在任务列表中显示一个圆点。会启动新的付费运行的操作（**重新启动**、**恢复并重试**）或他人可见的操作（创建 PR、发布）从不在运行条中直接执行：它会打开卡片并把焦点放在该按钮上，由你在那里确认。
+- **用键盘操作运行条。** **⌥R**（Windows/Linux 上为 **Alt+R**）从消息框跳到当前任务的运行条；再按一次可显示或隐藏运行详情，按 **Esc** 回到原来的位置。在文本框之外，**⌥[** 和 **⌥]** 可在运行之间切换。运行条获得焦点时，**P** 暂停或继续 Flow，**H** 将其交给 Rail；这些字母键在其他地方不起作用。按 **?** 查看完整列表。
 - **提示词历史。** 在输入框为空时，按 **↑**/**↓** 浏览你之前问过的内容（滚动时以淡化样式显示）；开始输入即可编辑，或按回车发送。
 - **编辑队列。** 智能体忙碌时又发了消息？只要有消息在排队，**↑**/**↓** 就会改为在*这些消息*之间移动：输入框显示选中的那条，你可就地编辑，按**回车即保存回队列**（Esc 取消；未发送的草稿会原样回来）。
+- **用按键作答。** 智能体给出选项时，每个选项都带有编号：在输入框为空时按 **⌥1**…**⌥9**（Windows/Linux 上为 **Alt+1**…**Alt+9**）即可选择。
+- **撤销删除的排队消息。** 删除排队消息后会显示几秒钟的**撤销**，可将消息放回队列。
 - **最小化，而不丢失。** 点击 ✕ 把面板收回气泡——对话仍在继续运行。重新打开时你会落在最新一条消息上；无需重新输入任何内容。
 - **新建对话。** **+** 按钮开启一段全新的线程；历史记录存在于整个应用层面，凌驾于任何单个项目之上。
-- **切换任务。** 项目选择器旁的任务选择器按从新到旧列出你的对话——跳动的圆点标记代理仍在工作的对话，小徽章显示排队消息的数量。列表超过八条时会出现搜索框；每行的垃圾桶图标在快速的行内确认后删除任务——即使是正在运行的任务（会先警告，然后停止代理）。
+- **切换任务。** 项目选择器旁的任务选择器按从新到旧列出你的对话——跳动的圆点标记代理仍在工作的对话，小徽章显示排队消息的数量。列表超过八条时会出现搜索框；每行的垃圾桶图标会立即删除任务，并在几秒内显示**撤销**（或按 **⌘Z**）；之后该任务会在项目设置的**最近删除**中保留 30 天。代理仍在工作的任务会先询问，因为停止代理无法撤销。
 - **随时随地找到任务。** 按 **⌘K**（或代理模式下侧边栏的 **搜索** 按钮），输入你记得的任何片段——标题中的一个词，*或者* 对话里说过的内容。任务会立刻按标题从内存中匹配，紧接着按内容匹配的结果也会到达，并高亮匹配段落，同时显示固定的项目和最近活动时间。在代理模式下任务是第一组；在看板中紧跟在项目之后。按 Enter 打开任务。
 
 ## 启动卡片与运行卡片
@@ -69,9 +76,9 @@ Agent Chat 通过内嵌的 **Specrails MCP 服务器**来驱动应用，因此
 
 ## 子代理
 
-部分提供商可以把任务的一部分交给**子代理**——它们并行工作，并在代理回复后继续运行。由于子代理会让单次请求的成本成倍增加，它们**默认关闭**。
+部分提供商可以把任务的一部分交给**子代理**——它们并行工作，并在代理回复后继续运行。子代理**默认开启**；由于它们会让单次请求的成本成倍增加，如需控制成本，可按项目关闭。
 
-- **按项目开启。** 打开项目的**设置 → 子代理**，开启**在此项目中允许子代理**。它适用于该项目的任务、探索和细化；Implement 流水线永远不受影响。无项目的任务遵循**应用设置 → AI 提供商 → 在无项目的任务中允许子代理**。
+- **按项目关闭。** 打开项目的**设置 → 子代理**，关闭**在此项目中允许子代理**。它适用于该项目的任务、探索和细化；Implement 流水线永远不受影响。无项目的任务遵循**应用设置 → AI 提供商 → 在无项目的任务中允许子代理**。
 - **选择由谁运行。** 在 **子代理运行方式** 中，默认的 **与任务代理相同** 会让任务自身的 CLI 原生启动它们：速度最快，并共享其提示缓存。也可以改选提供方、模型和推理强度来混用提供方——例如 Codex 任务搭配 Claude 子代理。已使用该提供方的任务保持原生并使用该模型；使用其他提供方时，Specrails 会自行启动每个子代理，冷启动可能更慢、更贵，但你能获得更多控制，并看到每个子代理的真实成本。切换前 Specrails 会请你确认，这些子代理在任务中会显示提供方标记。
 - **查看它们的工作。** 某条回复启动的代理会以一行紧凑的形式显示在该回复下方。它们工作时保持展开，全部完成后会折叠成一行摘要，显示总时长和 token。展开某一行可查看其结果和花费，或实时跟踪其活动。每次启动都会停留在对话中对应的位置，之后的启动不会与之前的混在一起。可在行内停止正在运行的代理，或在摘要行中全部停止。
 - **代理会自行跟进。** 后台代理完成后，代理会继续工作并发布它们的发现，标注为*在后台代理完成后继续*。

package/docs/guide/zh/integrations/8-flow-mode.md

@@ -0,0 +1,69 @@
+# Flow：先构建，后写 spec {#flow-mode}
+
+Flow 是在你还不确定自己想要什么时与智能体一起构建的方式。你在任务中与智能体对话，它会在专属的 Flow 分支（项目的独立副本）上编写并运行真实代码；当结果满意时，按 **交给 Rail**：Rail 接手你的更改，推导出 spec，并照常执行验证、评审和交付。
+
+Implement 用于委派你已经能描述清楚的工作，Flow 用于发现它。
+
+## Flow 如何开始
+
+你无需点名要求 Flow。当你描述探索性或视觉性的需求（"我想试试……"、"我不知道它该长什么样"）时，任务会显示一张有两条路径的卡片：
+
+- **Flow**：现在一起构建；spec 最后再写。
+- **Spec + Implement**：先商定 spec，再委派给 Rail。
+
+两条路径分量相同，且始终按同样的顺序出现：不推荐任何一条，由你选择。在 **智能体为何询问** 中，智能体用一句话说明它为何询问；无论你选择哪条路径或按 **暂不**，它都不会坚持。
+
+选择 Flow 会打开确认：Specrails 会在专属的 Flow 分支上创建项目的独立副本，智能体可以在其中编写代码，你的主分支不会被改动。按 **开始 Flow**。看板上会出现一个带 **Flow 中** 标签的占位 spec（点击可回到任务）。
+
+如果你的 Specrails Core 还不能运行 Flow，开始按钮会被禁用，卡片会列出缺少的内容。通常更新 Specrails Core 即可解决。
+
+## 从已有规格开始 Flow
+
+不只是新想法，任何规格都可以在 Flow 中构建。Flow 和 Implement 仍是处理规格的两种同等方式：
+
+- 在看板上右键点击规格并选择 **在 Flow 中开始**（与拖到轨道并列）；在规格详情中，**在 Flow 中开始** 位于 **移到轨道** 旁边；
+- 在任务中，如果你要求实现某个规格但没有指定轨道，代理会为该规格显示同样的双路径卡片：**Flow** 与你一起处理它，**Spec + Implement** 在轨道上启动它；
+- 只包含一个规格的轨道启动卡片，也会在启动按钮旁提供 **在 Flow 中开始**。
+
+规格本身会进入 **Flow 中**：不会创建占位规格，代理的第一轮会收到该规格（验收标准、Contract Layer、范围外事项和未处理的补充说明）。从看板开始时，Flow 会在该规格自己的任务中打开，或在以规格命名的新任务中打开。在有多个 Git 仓库的项目中，如果规格没有恰好指定其中一个，会先弹出一个小对话框询问 Flow 在哪里运行：只列出 Git 仓库，预选规格自己的仓库（否则为主仓库），可用方向键切换选择。当规格已在 Flow 中、已完成或已取消、位于轨道上，或 Flow 不可用时，**在 Flow 中开始** 会被禁用，悬停可看到原因。
+
+**丢弃** 会把规格原样还给你，并恢复之前的状态：你的规格绝不会被删除。Flow 交付时，规格会根据所构建的内容重写；在此之前，原文会先保存为评论 **Original spec before Flow**，不会丢失任何内容。已关联 Jira 的规格会更新同一个问题，并将其移到映射为评审的状态；不会创建第二个问题。
+
+## 在 Flow 中
+
+Flow 模式会在你看的地方以专属的 Flow 颜色标示：输入框在自主度标签旁显示 **Flow** 标签，提示语为 *告诉智能体要在这个 Flow 中修改什么…*；任务标题和任务列表中的对应行都显示 **Flow 中**。对话会标出你进入和离开 Flow 的位置，智能体在 Flow 中写的回复在时间旁带有一个小小的 **Flow** 标记。
+
+输入框正上方的条带用简短的一行显示 Flow：状态、**Flow · 7 个文件**、**暂停 Flow** 和主要操作 **交给 Rail**。当某个操作不可用（Flow 仍在保存、另一操作正在进行）时，悬停即可看到原因。像其他运行一样，用箭头展开这一行即可查看其余内容：
+
+- **分支**（点击复制名称）、带增删行数的 **更改**（点击列出每个更改文件及其状态和 +/−），以及提供商计费的 **目前成本**。在某一轮有上报成本之前显示 `—`，从不显示估算；`*` 表示总额不含未计价的轮次，并附注说明数量；
+- Flow 的应用运行时显示 **预览**（见下文）；
+- 单独放置的 **丢弃** 会删除 Flow 的更改、其分支和占位 spec。确认框会列出你将失去的内容：带 +/− 的更改文件、分支和 spec。
+
+**暂停 Flow** 会让智能体停下，并保留你的更改和 spec。该行随后显示 **恢复 Flow**。
+
+智能体工作时你也可以输入：在 Flow 中，你的消息会 **打断** 当前步骤（发送按钮变成闪电），智能体会立即带着新信息继续。Flow 打开期间，输入框下方的 git 条会让开：Flow 的面板已经显示了它的分支。
+
+## 试用应用
+
+Flow 智能体会自行运行类型检查和测试来检验工作。有可试用的内容时，它会给出三个选项：**Start the app**、**Start and expose on the local network** 或 **Not now**。对外公开后，你可以在同一 Wi-Fi 或 VPN 的手机上打开应用，该网络中的任何人都能访问。
+
+应用开始监听后，智能体会以链接形式给出地址，Flow 的面板会显示带绿点的 **预览**：在浏览器中打开应用。其菜单包含网络地址和 **停止应用**。应用从 Flow 的副本运行，而不是你的主检出；当你暂停、丢弃或交付 Flow 时，Specrails 会停止它。
+
+## 交给 Rail {#flow-hand-off}
+
+对结果满意时，按 **交给 Rail**。该行变为 **可以变成 PR 了**，并在上方只显示一行：*Rail 2 会把你更改的 7 个文件变成经过评审的 PR。即使失败，你的工作也不会丢失。* 按 **启动**，或按 **暂不** 回到 Flow；**Esc** 等同于 **暂不**；点击别处只会收起这一行，条带仍显示 **可以变成 PR 了** 和 **启动**。如果你对话所用的引擎无法在此设备上运行移交，该行正下方的提示会说明，并改用该 Rail 的默认引擎。
+
+Rail、引擎、模型和推理强度已为你选好（一个空闲的 Rail 和你对话所用的引擎）。如需更改，打开 **更改方式**；那里还会显示更改内容。目前成本显示在主行上。如果你按 **暂不** 之后再次移交，之前的选择会保留。移交启动时，条带会无缝显示启动过程，随后逐步跟踪运行。如果达到评审上限或预算，该行会说明，且不会启动任何内容。如果 45 秒后运行仍未出现，条带会停止转动并显示 **仍在交给 Rail 2…** 和 **刷新**；**刷新** 只会重新检查，并继续等待运行出现。
+
+Rail 会根据你构建的内容推导出 spec 及其 spec 变更，进行验证和评审，交付卡片会像其他运行一样出现在任务中。
+
+如果运行因技术原因失败，工作会自动、完好地回到这个 Flow：卡片会用平实的语言说明失败原因（代码保留在 **技术细节** 中），智能体会收到错误并加以解释。如果评审要求修改，卡片会提供 **回到 Flow** 或 **重新运行**。交付完成后，任务会用一份摘要结束 Flow：PR、根据你构建的内容重写的 spec、已归档的 spec 变更，以及 Jira 工单（如有）。
+
+## 须知
+
+- Flow 只在自己的分支上写入。Flow 之外，任务保持只读。
+- 每个任务同一时间只能有一个 Flow。暂停状态在应用重启后仍会保留。
+- 如果 Flow 的项目副本消失，Flow 会被标记为 **需要检查**（仅供参考，无需决定），且不会删除任何内容。
+- 条带从不切换你正在查看的运行。如果期间有其他运行需要你，它在条带切换器中的名称会显示 **需要你处理**。
+- 在 Flow 中或丢弃 Flow 时，Jira 不会收到任何内容。
+- Flow 成本会在分析中作为独立的 **Flow** 类别显示，并出现在智能体任务区块中。

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

@@ -37,13 +37,14 @@ rail 是一条**执行通道**。你从 SpecsBoard 上拖一张 spec 卡片放
 | **Loop 选择器** | 这条 rail 运行的 Loop——内置的（`Implement` / `Freestyle` / `SDD Quick (OpenSpec)`）或某个自定义 loop。见下表。按 rail 单独记忆。 |
 | **▶ Play / ■ Stop** | 启动或取消。 |
 
-### rail 运行的是什么：Loop
+### rail 运行的是什么：Loop {#rail-loops}
 
 一条 rail 运行的是一个 **Loop**——干活的配方。有两个 loop 是**内置**的，覆盖了常见情况：
 
 | 内置 loop | 命令 | 作用 |
 |------|---------|--------------|
 | **Implement** | `/specrails:implement` | 一个任务覆盖这条 rail 上的所有 spec。跑完整的 Architect → Developer → Reviewer → Ship 流水线。日常默认选项。 |
+| **Freestyle** | Freestyle | 由 rail 的提供方**绕过**流水线自主实现每个 spec，随后由验证和 Loop Decider 打磨，直到全部通过。每个 spec 一次独立运行。支持 Claude、Codex、Gemini、Kimi 和本地引擎；任务内的交互式聊天仅限 Claude。 |
 
 要运行多个 spec，可以把相关的（最多 3 个）放到同一条 rail 上——`Implement` 会把它们作为一个整体任务运行——或者把彼此独立的 spec 分到多条 rail：每条基于 git 的 rail 都在自己隔离的 worktree 中并行运行。
 
@@ -85,6 +86,25 @@ rail 是一条**执行通道**。你从 SpecsBoard 上拖一张 spec 卡片放
 - **预算自动暂停**——设一个每日预算，当当天花费触到上限时队列会自我暂停。
 - **全部**——退出桌面应用，或运行 `specrails-desktop stop`。
 
+## 在有未提交更改时本地集成
+
+**本地集成** 会在这台电脑上把已批准的交付合并到你的集成分支（例如 `main`），无需 PR。你不需要先清理工作区：
+
+- 不涉及交付文件的未提交更改会原样保留。
+- 如果你的更改涉及相同的文件，Specrails 会把它们保存为名为 `specrails: before integrating #N (…)` 的 git stash，完成集成后再恢复。提示为“已保存你的本地更改，集成了 #N，并已恢复这些更改。”
+- 如果恢复时与集成后的代码冲突，Specrails 会让分支保持集成后的状态并**保留该 stash**——不会丢失任何内容。卡片会显示“你的本地更改已保存为 stash”、冲突文件、**恢复我的更改**（例如修改代码后再次尝试）以及可复制的 stash 名称。随后 Specrails 会亲自在单独 worktree 中的新分支 `specrails/restore-local-<id>` 上恢复它们：如果在那里能无冲突地应用，就直接提交；否则由 AI 冲突解决器仅在该 worktree 内工作，同时保留你的意图和集成后的代码，再由 Specrails 提交结果。卡片会列出恢复的文件；**带回 <分支>** 会把它们移到你的分支（只有此时才会删除 stash），**丢弃恢复的分支** 会删除该分支并保留 stash。任务只会收到情况说明，从不需要执行任何操作。Specrails 生成的 OpenSpec 技能和命令（例如 `.claude/skills/openspec-*/SKILL.md`）不算作你的更改：发生冲突时保留集成版本。
+- 被忽略的文件永远不会放入 stash：如果其中某个文件与交付冲突，Specrails 会请你先把它移走。
+- 如果应用在保存和恢复之间停止，下次打开项目时会恢复你的更改（仅当仍检出同一分支时）。
+
+## 时间与费用预估 {#launch-forecast}
+
+在你点击启动之前，轨道可以显示这类运行通常需要多长时间，并在有意义时显示通常的花费，例如*同类运行通常 6–9 分钟 · $2–4*。
+
+这个范围取自你自己的历史记录的中间一半：本项目中使用相同循环或命令、相同引擎且已完成的运行的第 25 到第 75 百分位。至少需要 5 次可比较的运行。在此之前，这一行会显示*历史记录尚不足*，而不是猜测。只使用提供方报告的费用，估算的费用不计入。这是估计值，不是账单。
+
+只有在确认引擎按用量计费（例如使用 API 密钥）时才会显示美元金额；订阅套餐下，或计费方式尚未确认时，只显示时间。当轨道里有多个规格时，该范围针对单个规格，并标注*（每个规格）*。如果今天的花费加上范围上限可能达到每日预算，这一行会加上*可能因预算而暂停*，并附带指向预算设置的链接。如果今天的预算已经用完，启动前会先请你确认，因为运行会暂停到预算重置为止。
+
+
 ## 接下来去哪儿
 
 - [Loop Builder](the-loop-builder)——rail 运行的是什么，以及如何搭建你自己的 loop。

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

@@ -107,6 +107,18 @@ Architect ──► Developer ──► Reviewer ──► Ship
 
 无论是和队友分享一次运行，还是提交一份精确的 bug 报告，都很顺手。
 
+## 运行失败时
+
+当任务失败、停滞或被阻塞时，终态会以一张**诊断卡片**开头，用平实的话说明发生了什么，例如*测试在 Reviewer 阶段失败，已修复 4 轮*，并在应用知道原因时说明原因：
+
+- **测试失败**：经过修正轮次后，检查仍然失败。
+- **提供商上限**：已达到 AI 提供商的使用上限。卡片会用提供商自己的措辞写出重置时间。
+- **环境**：机器无法运行检查（凭据、缺少的工具、失败的准备命令）。*修复环境*会准确显示要运行或修改的内容。
+- **被阻塞**、**超时**、**停止动作**和**意外停止**会指出让运行停下的上限或进程。
+- **原因未知**：应用不会猜测，而是显示日志末尾，让你自己查看。
+
+诊断下方最多有三个按优先级排列的补救办法，而且只列出在此处真正可行的：从停下的阶段**继续**、**再次运行**、**编辑规格并重新启动**（规格的补充说明会把你的修改带入下一次运行）、**修复环境**和**在失败处打开日志**。同一原因在[待处理列表](../getting-started/the-dashboard-tour)里显示为一行标签，任务的运行卡片展示同一张卡片。
+
 ## 接下来去哪儿
 
 - [Rail 与任务](rails-and-jobs)——启动与排队。

package/docs/guide/zh/pipeline/3-reviewing-a-delivery.md

@@ -0,0 +1,43 @@
+<!-- guide-revision: mission-first-v1 -->
+
+# 在应用中评审一次交付 {#review-a-delivery}
+
+待评审的交付有两个视图：**概览**（结论、证据和决策按钮）和**变更**（交付实际改了什么）。从交付的**评审**按钮打开评审，然后选择**变更**。
+
+## 阅读变更
+
+左侧的文件列表显示每个变更文件的状态（新增、修改、删除、重命名）、`+` 和 `−` 的行数，以及你标记为已查看后出现的对勾。右侧的差异一次只加载一个文件，因此大型变更也保持流畅。可在**统一**和**分栏**布局之间切换，Specrails 会记住你的选择。特别大的文件会先显示开头的若干行，并提供**加载完整的文件差异**；二进制文件会标明为二进制。
+
+变更从交付与基础分支分叉的位置开始计算，因此之后合入基础分支的内容不会出现。如果交付还没有合并后的分支，你可以选择读取哪个规格的分支。
+
+## 评审员对代码的批注
+
+评审员的发现、它标出的风险，以及本次运行要解决的评审评论，会显示在它们所指的那一行下面。没有指明文件或行的批注会列在文件列表上方，因此不会被隐藏。较早的交付，以及没有指明位置的评审员，会在该列表中显示其发现。
+
+## 让智能体修改某处
+
+点击行号选择行（按住 Shift 点击可扩大范围），选择**请智能体做出修改**并描述修改。Specrails 会把它作为评审反馈保存到规格中，附上文件、行范围和所选代码，并显示一条带有规格链接的消息。之后针对该规格的运行会收到它。若要立即开始运行，请使用概览中的**请求修改**。这里没有人与人之间的评论线程；请在 GitHub 上与团队讨论。
+
+## 在你的编辑器中打开
+
+**在编辑器中打开**会在 VS Code、Cursor 或 JetBrains IDE 中打开该文件并定位到所选行。请在**设置 → 代码 → 编辑器**中选择编辑器。文件从你本地的项目副本打开，评审分支可能没有在那里检出。
+
+## 选择交付结果的去向 {#pr-decision}
+
+完成的运行只会问你一件事：如何处理它的结果。卡片上有一个用于下一步的主按钮（创建 PR、发布或验证），旁边是 **审阅**，用于打开通俗易懂的审阅包。其余操作都收在 **更多操作** 中：
+
+- **检出分支** 会把分支放进你的项目文件夹，方便你试用。
+- **本地集成** 会在这台电脑上把结果合并到基础分支。无需 GitHub，且会先请你确认。
+- **丢弃** 会删除结果及其分支，同样会先请你确认。
+
+如果某个操作失败，通知会说明哪件事没能完成，并提供 **重试**。
+
+## 键盘
+
+| 按键 | 操作 |
+| --- | --- |
+| `j` / `k` | 下一个 / 上一个变更文件 |
+| `n` / `p` | 下一条 / 上一条评审员批注 |
+| `v` | 将文件标记为已查看 |
+
+在输入框中输入时，这些按键会被忽略。“已查看”仅对你自己可见；如果文件在之后的修订中发生变化，它会显示**自你查看后已更改**，并重新算作未查看。

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

@@ -1,4 +1,4 @@
-# 为每条 rail 选择引擎
+# 为每条 rail 选择引擎 {#provider-capabilities}
 
 ## 选择器何时出现
 
@@ -19,7 +19,7 @@
 | 引擎 | 在什么情况下选它…… | 说明 |
 |--------|--------------------|-------|
 | **Claude** | 需要原生成本、持久交互或严格 tool policy。 | Profile、Freestyle 和 structured transform。 |
-| **Codex** | 你更喜欢 OpenAI Codex CLI，或想跨提供方对比实现。 | `codex` ≥ 0.128.0。无原生成本上报——应用会用自己的价格表来补上成本。Profile 不适用。 |
+| **Codex** | 你更喜欢 OpenAI Codex CLI，或想跨提供方对比实现。 | `codex` ≥ 0.128.0。无原生成本上报——应用会用自己的价格表来补上成本。Profile 不适用。Freestyle 可用，但没有交互式聊天。 |
 
 ## 一套实用的工作流
 

package/docs/guide/zh/pipeline/5-the-loop-builder.md

@@ -1,4 +1,4 @@
-# Loop Builder
+# Loop Builder {#loop-builder}
 
 ## Core 工作流