specrails-desktop 2.30.2 → 2.31.0

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

@@ -94,7 +94,8 @@ Algumas coisas que vale a pena saber:
 - **A linha de totais é real.** O compositor mostra um resumo ao vivo `N turnos · $X`, somado a partir do uso real de cada turno concluído — coerente com a promessa desta página de nunca adivinhar.
 - **Duas formas de uma sessão terminar.** A maioria dos jobs **termina sozinha**: assim que um turno acaba sem mensagens em fila, a sessão assenta e o job conclui — as suas mensagens são orientação opcional, nunca uma obrigação. Uma ação discreta **Concluir agora** termina-a mais cedo com tudo o que foi produzido até então. Os jobs **Freestyle** são a exceção: ficam à espera entre turnos até que clique em **Finalize** — é esse o seu desenho, uma sessão de ida e volta que fecha quando terminar.
 - **Nas execuções de loop, as mensagens vão para o passo ativo.** Num loop embutido ou personalizado, a sua mensagem chega ao **passo de IA que está a correr nesse momento**. Entre passos (enquanto o Loop Decider pensa, ou um comando de shell corre) o compositor mostra um breve estado *«À espera do próximo passo…»* — o texto rascunhado mantém-se, e o envio reativa-se quando o próximo passo de IA arranca. **Assentar este passo** termina o passo atual mais cedo e deixa o loop avançar com o que ele produziu.
-- **Só Claude, por agora.** Os jobs Codex e Gemini correm numa só passagem exatamente como antes — não aparece compositor. (Os operadores do servidor podem desligar a funcionalidade inteira com `SPECRAILS_INTERACTIVE_JOBS=false`.)
+- **Interação persistente é só Claude.** Codex, Gemini e Kimi correm one-shot;
+  Kimi retoma o chat com novo `kimi --session=<id> -p` depois de um resume hint.
 
 ## Exportação de diagnóstico
 

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

@@ -81,4 +81,4 @@ Não há limite global de concorrência para ajustar. Abra os projetos ou rails
 
 - [Rails e jobs](rails-and-jobs) — o modelo da fila em detalhe.
 - [A vista de detalhe do job](the-job-detail-view) — ver um batch a correr ao vivo.
-- [Escolher um motor por rail](picking-an-engine-per-rail) — note que o Batch corre em qualquer fornecedor; o Freestyle é só Claude.
+- [Escolher um motor por rail](picking-an-engine-per-rail) — o Batch corre em qualquer fornecedor; o Freestyle está disponível com Claude e Kimi.

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

@@ -1,6 +1,8 @@
 # Escolher um motor por rail
 
-O Specrails desktop trata o **Claude Code**, o **Codex CLI** e o **Gemini CLI** como motores de primeira classe. Um projeto pode ter um, dois ou os três instalados — e quando há mais do que um, escolhe que motor corre cada rail. Esta página cobre o seletor de motor por rail e quando recorrer a cada um.
+O Specrails desktop trata **Claude Code**, **Codex CLI**, **Gemini CLI** e
+**Kimi Code** como motores de primeira classe. Pode instalar qualquer
+combinação compatível.
 
 ## Quando o seletor aparece
 
@@ -13,30 +15,27 @@ Quando aparece, a sua escolha é **por rail e por lançamento** — rails difere
 ## Como escolher um motor
 
 1. Certifique-se de que o seletor de motor do rail está visível (projeto com 2+ fornecedores).
-2. Clique nele e escolha **Claude**, **Codex** ou **Gemini**.
+2. Escolha **Claude**, **Codex**, **Gemini** ou **Kimi**.
 3. Lance o rail com **▶ Play**.
 
 O motor selecionado corre todas as fases do pipeline desse rail. Se a CLI do motor escolhido não estiver instalada, o lançamento falha de imediato — nada é criado. Instale a CLI em falta e tente de novo.
 
 ## Em que cada motor é bom
 
-Os três correm os pipelines standard **Implement** e **Batch**. Aqui fica um guia prático para escolher:
+Os quatro correm os pipelines standard **Implement** e **Batch**:
 
 | Motor | Recorra a ele quando… | Notas |
 |--------|--------------------|-------|
-| **Claude** | Quer o conjunto completo de funcionalidades: perfis de agentes, Freestyle, reporte de custo nativo, o suporte de ferramentas mais rico. O default para a maioria do trabalho. | O único motor que suporta **perfis de agentes**, **Freestyle** e algumas funcionalidades de spec exclusivas do Claude (Contract Layer, SMASH). |
+| **Claude** | Precisa de custo nativo, interação persistente ou tool policy rigorosa. | Perfis, Freestyle e transformações estruturadas. |
 | **Codex** | Prefere o Codex CLI da OpenAI ou quer comparar implementações entre fornecedores. | `codex` ≥ 0.128.0. Sem reporte de custo nativo — a app preenche o custo a partir da sua tabela de preços. Os perfis não se aplicam. |
 | **Gemini** | Quer o Gemini CLI da Google, telemetria nativa ou uma execução mais barata para specs de rotina. | `gemini` ≥ 0.11.0 (defina `GEMINI_API_KEY`). Telemetria OTLP nativa. Os perfis não se aplicam. |
+| **Kimi** | Quer Kimi agentic para Implement, Batch, Freestyle ou loops sem Decider. | `kimi` ≥ 0.27.0 externo; perfis/roles, effort só K3; tokens/custo indisponíveis. |
 
-### As funcionalidades exclusivas do Claude
+### Diferenças de capability
 
-Algumas coisas só funcionam em rails Claude — escolha o Claude se precisar delas:
-
-- **Perfis de agentes** — encaminhamento de modelo por agente. Em rails Codex ou Gemini a execução usa sempre o modo legado e qualquer perfil selecionado é **ignorado**. O seletor de perfil fica escondido nos motores que não são Claude.
-- **Freestyle** — o modo autónomo que ignora o pipeline. O segmento `Freestyle` e o seu seletor de modelo Haiku/Sonnet/Opus só aparecem quando o motor do rail é o Claude.
-- **Contract Layer e SMASH** — funcionalidades de refinamento de spec exclusivas do Claude (são opções de Add Spec, não opções de rail, mas aplica-se a mesma restrição).
-
-Se um projeto mistura motores, a barra lateral direita só mostra as secções que **todos** os fornecedores instalados suportam — por isso a secção **Agentes** desaparece por completo num projeto que inclua qualquer fornecedor que não seja Claude, porque os perfis são específicos do Claude.
+Claude/Kimi suportam perfis e Freestyle; Codex/Gemini usam legacy. Kimi
+recusa Loop Decider e os transforms pure-output do
+[guia Kimi](../../../kimi.md). Perfis Claude/Kimi ficam separados.
 
 ## Um fluxo de trabalho prático
 
@@ -49,12 +48,14 @@ Os projetos com vários fornecedores brilham quando quer **comparar** ou **afina
 ## Coisas a ter em conta
 
 - **A escolha de fornecedor é imutável depois de criar o projeto** (v1). Escolhe os fornecedores instalados ao adicionar o projeto; não há um toggle nas Definições para acrescentar ou remover um mais tarde.
-- **O custo é sempre acompanhado**, mesmo para motores sem reporte de custo nativo — a app recorre a uma tabela de preços para que as execuções de Codex e Gemini apareçam na mesma nas [analytics](../analytics/tracking-cost).
+- **As métricas disponíveis são registadas.** Kimi não fornece tokens/custo
+  USD autoritativos; os campos ficam vazios.
 - **O botão "Abrir CLI de IA" do terminal** também oferece um seletor de fornecedor em projetos com vários fornecedores, caso prefira conduzir uma CLI à mão.
 
 ## Para onde ir a seguir
 
 - [Usar o Codex](../integrations/using-codex) — instalar e iniciar sessão.
 - [Usar o Gemini](../integrations/using-gemini) — instalar, `GEMINI_API_KEY`, telemetria.
+- [Usar Kimi](../../../kimi.md) — instalação e matriz completa.
 - [Rails e jobs](rails-and-jobs) — a fila e o fluxo de lançamento.
 - [Acompanhar o custo](../analytics/tracking-cost) — repartição de custo por motor.

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

@@ -17,7 +17,7 @@ Um **loop** é a *receita* do trabalho; um **rail** é a *pista* que o roda cont
 
 - Os loops vivem na seção **Loops** (barra lateral esquerda, ao lado dos seus projetos) — eles são **globais**, compartilhados por todos os projetos.
 - Um rail **escolhe um loop** no cabeçalho (o seletor de Loop) e o roda quando você aperta Play.
-- O **rail** decide o provedor, o modelo e o esforço de raciocínio — *não* os passos do loop. O mesmo loop roda em Claude, Codex ou Gemini dependendo do rail.
+- O **rail** escolhe provider, modelo e effort compatível. Um loop compatível corre em Claude, Codex, Gemini ou Kimi.
 
 Ou seja: construa um loop uma vez e depois escolha-o em qualquer rail, em qualquer projeto.
 
@@ -41,6 +41,10 @@ Um loop é um grafo de **nós** conectados por **arestas** (as setas). Cada nó
 
 As arestas conectam os passos em ordem. O **Loop Decider** tem duas saídas rotuladas — **continue** e **stop** — então você liga o "ainda não terminei" de volta ao trabalho e o "terminei" para um End.
 
+> **Kimi corre loops com passos AI/shell, mas não com Loop Decider.** O
+> veredito é pure-output e `kimi -p` não consegue impor o limite no-tools; o
+> run é recusado antes do primeiro passo.
+
 ### Escrevendo o texto dos passos
 
 Dentro de qualquer AI Step ou Decider você pode referenciar:
@@ -57,7 +61,7 @@ Um loop que nunca para queimaria dinheiro para sempre, então toda execução te
 |-------|--------------|
 | **Max iterations** | Teto rígido de quantas vezes o Decider pode voltar atrás, independentemente do seu veredito. |
 | **Timeout (min)** | Limite de tempo de relógio para toda a execução. |
-| **Max cost ($)** | *Opcional.* Para o loop quando o custo acumulado cruza o seu orçamento. Verificado **entre passos** (o custo de um passo só é conhecido quando ele termina), então pode freestylepassar em um passo. No Claude o custo é exato; no Codex e no Gemini é uma estimativa. Deixe vazio para não ter teto. |
+| **Max cost ($)** | *Opcional.* Claude reporta custo; Codex/Gemini usam estimativas. Kimi não reporta custo USD autoritativo. |
 
 ## Construindo com confiança
 

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

@@ -2,6 +2,10 @@
 
 O modo Quick é para quando já sabe o que quer. Escreve a sua ideia, a IA redige a spec completa, e ela aterra no seu quadro como **Por fazer**. Sem idas e vindas — basta descrever e avançar.
 
+> **Kimi não está disponível no Quick Spec.** `kimi -p` não consegue impor
+> o limite pure-output deste formulário. O pedido é recusado antes do spawn;
+> use Explore, Raw ou Quick Launcher (`/opsx:ff`).
+
 ## Criar uma spec no modo Quick
 
 Para criar uma spec rapidamente:
@@ -19,7 +23,8 @@ Enquanto a spec está a ser escrita, uma pequena notificação no canto mostra o
 
 **Modelo** — por predefinição, a IA escolhe um modelo sensato. Pode substituí-lo por spec a partir do seletor de modelo se quiser um mais rápido ou mais capaz.
 
-**Motor** — se o seu projeto tiver mais do que um fornecedor de IA instalado (qualquer combinação de Claude, Codex e Gemini), um seletor de motor fica no topo da janela para que possa escolher qual deles gera esta spec. A sua escolha é memorizada por projeto. Projetos com um único fornecedor não mostram isto — não há nada por onde escolher.
+**Motor** — o seletor mostra apenas providers **compatíveis**; Kimi fica
+excluído de Quick Spec.
 
 **Contexto** — o modo Quick normalmente corre como um único turno, porque não precisa de ler a sua base de código para escrever uma spec a partir da sua descrição. Mas um seletor de contexto permite dar-lhe mais material para trabalhar:
 

package/docs/guide/zh/agents/2-profiles-and-the-balanced-default.md

@@ -37,7 +37,10 @@ Profile 的选择就发生在你启动的地方——**rail 头部**，通过 Pr
 
 ## 当 Agents 区悄无声息时
 
-Profile 是 Claude 的能力。在包含非 Claude 提供商（Codex 或 Gemini）的项目上，Agents 区会被隐藏，rail 会在没有 Profile 的情况下运行——这是预期行为，并非 bug。Profile 还要求项目中的 `specrails-core` 足够新；如果版本偏旧，你会看到一条黄色横幅。你创建的 Profile 仍会**保存**——只是在 core 更新之前不会影响流水线。按横幅中给出的命令更新，即可解锁它们。
+Profile 按 provider 隔离。Claude 和 Kimi 支持 profile/role；Codex 和
+Gemini 使用 legacy mode。混合项目中相同名称也不会在 Claude/Kimi 之间
+串用。Kimi 支持手动 role，但 Agent Studio 的 generation、smoke test
+和 AI Refine 会在 spawn 前拒绝。Kimi 需要 `specrails-core` 4.12.0+。
 
 ## 接下来去哪儿
 

package/docs/guide/zh/agents/4-custom-agents-catalog.md

@@ -11,21 +11,24 @@ Profile 决定的是*哪些 Agent 运行、用什么模型*。但 Agent 本身
 
 ## 添加一个自定义 Agent
 
-自定义 Agent 就是你仓库里 `.claude/agents/` 目录下的普通 Markdown 文件，命名为 `custom-<某某>.md`。文件内容包含该 Agent 的指令（它的系统提示词），以及一小段 frontmatter 头部，其中含有一个默认的 `model:`。
+Role 是 provider-native asset：Claude 使用
+`.claude/agents/custom-<name>.md`；Kimi 使用
+`.kimi-code/skills/custom-<name>/SKILL.md`。
 
-文件一旦存在于项目中，它就会作为自定义 Agent 出现在目录里，你便可以把它的 id 加入任意 Profile 的 Agent 链（并把任务路由给它）。id 必须与文件名一致——`custom-docs` 这个条目对应的是 `.claude/agents/custom-docs.md`。
+Asset 存在后会出现在对应 provider 的目录中，其 id 只能加入同 provider 的 Profile。`custom-docs` 在 Claude 中对应 `.claude/agents/custom-docs.md`，在 Kimi 中对应 `.kimi-code/skills/custom-docs/SKILL.md`；二者互不混用。
 
 由于它们就住在你的仓库里，自定义 Agent 是**可提交的团队资产**：提交这个文件，你的整个团队就都拥有了这个 Agent。这呼应了贯穿整个 Agents 区的核心观念——
 
 > **Agent 定义是共享的（它们住在仓库里，随 `git` 一起流转）。模型配置则因项目而异（它住在 Profile 里）。**
 
-`custom-*` 命名空间是保留且受保护的：`specrails-core` 的 `init` 和 `update` 命令绝不会触碰 `.claude/agents/custom-*.md`，因此你的自定义 Agent 能在 core 升级中毫发无损地保留下来。（同样的保护也覆盖插件贡献的片段，比如 `custom-serena.md`。）
+Core 保护两种格式。Kimi 支持手动 create/edit/run；Generate、Test 和
+AI Refine 会在 spawn 前拒绝。
 
 ## 让自定义 Agent 上岗
 
 典型流程如下：
 
-1. 编写 `.claude/agents/custom-<name>.md`，写好指令和一个默认模型。
+1. 创建 native Claude asset 或 Kimi Skill，并使用有效指令/model。
 2. 确认它出现在 **Agents → 目录** 的「自定义」分组下。
 3. 在 **Agents → Profile** 中，把这个 Agent 加入某条 Profile 链（也可在该 Profile 内覆盖它的模型）。
 4. 添加一条路由规则，让带有合适标签的任务到达它——或者依赖链的顺序。

package/docs/guide/zh/getting-started/1-what-is-specrails.md

@@ -36,6 +36,7 @@ specrails 支持主流的 AI 编程 CLI：
 - **Claude**（Claude Code）
 - **Codex**（Codex CLI）
 - **Gemini**（Gemini CLI）
+- **Kimi**（Kimi Code）
 
 挑一个你已经在用的就行——或者多装几个，按任务来选。一个项目可以只跑一个提供商，也可以同时跑多个，所以你永远不会被某一个绑死。
 

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

@@ -23,6 +23,7 @@ specrails 唯一无法内置的，是 **AI 提供商 CLI** 本身。你至少需
 - **Claude Code**
 - **Codex CLI**
 - **Gemini CLI**
+- **Kimi Code**
 
 把你打算用的那个装好，在终端里登录一次，就齐活了。specrails 会自动检测出有哪些提供商可用。
 

package/docs/guide/zh/getting-started/4-the-dashboard-tour.md

@@ -26,13 +26,13 @@
 
 - **仪表盘**——spec 看板和 rails（你刚才待的地方）。
 - **任务**——这个项目的每一次流水线运行，无论过去还是当下，都带有状态、耗时，并能深入查看任意一次运行的详情和日志。
-- **分析**——你的 AI 用量花了多少钱。按天、按活动、按模型、按工单拆解的开销——不会有任何意外惊吓。
-- **Agent**——你项目的 agent profile：流水线里跑哪些 agent、它们各自用什么 AI 模型。*(仅限由 Claude 驱动的项目。)*
-- **代码**——一个只读的文件浏览器，附带通俗易懂的 AI 摘要，还有标签显示 AI 动过哪些文件。对想跟上进度的非开发者来说非常友好。
+- **分析**——按天、活动、模型和工单拆分的调用。Claude 报告账单成本，Codex/Gemini 使用估算值；Kimi 会把无法获得的 token/USD 字段留空。
+- **Agent**——Claude 与 Kimi 各自独立的 Profile 和 Role 目录。Kimi Role 可手动创建/编辑；Generate、Test 和 AI Refine 不可用。
+- **代码**——只读文件浏览器，以及显示 AI 动过哪些文件的标签。通俗 AI 摘要只对兼容 provider 显示，Kimi 不支持该转换。
 - **集成**——可选的附加组件，比如把你的 spec 连接到 **Jira** 看板，或为 AI 启用额外的工具。
 - **设置**——项目级选项（遥测、预算、提供商配置等等）。
 
-> 有些区块只有在对你所选的提供商有意义时才会出现——例如，**Agent** 是 Claude 专属的。如果你没看到某个区块，那只是说明它不适用于这个项目的配置。
+> 区块和操作会遵循当前 provider 的 capability。例如 Profile 可用于 Claude/Kimi，但 Kimi 的 Agent Studio AI 操作会 fail closed。
 
 ## 状态栏
 

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

@@ -1,16 +1,19 @@
-# AI 提供方（Claude、Codex、Gemini）
+# AI 提供方（Claude、Codex、Gemini、Kimi）
 
-Specrails 并不绑定在某一个 AI 上。应用里所有会调用 AI 的环节——Explore Spec、Quick spec、rail、聊天、AI Edit，以及终端里的「Open AI CLI」按钮——都可以走三家一流提供方中的任意一家。你来决定每个项目用哪些，甚至可以按任务逐个切换。
+Specrails 并不绑定某一个 AI。Claude、Codex、Gemini 和 Kimi 都是一流
+提供方；每个界面只显示满足该功能 capability 合约的引擎。
 
-## 三家提供方
+## 四家提供方
 
 | 提供方 | CLI | 出品方 | 说明 |
 |---|---|---|---|
-| **Claude** | `claude` | Anthropic | 功能最完整。Agents（profile）、Freestyle rail 以及 Contract Refine 都只有它支持。 |
+| **Claude** | `claude` | Anthropic | 原生成本和持久交互 transport。 |
 | **Codex** | `codex` | OpenAI | 需要 codex `0.128.0+`。从你的全局 `~/.codex/config.toml` 读取 MCP 服务器。 |
 | **Gemini** | `gemini` | Google | 需要 gemini `0.11.0+`。使用原生遥测，以及 `GEMINI.md` 指令文件。 |
+| **Kimi Code** | `kimi` | Moonshot AI | 需要 Kimi `0.27.0+`。Desktop 用 `-p` 启动外部 CLI，不安装或启动 server。 |
 
-三家都是**默认启用**的。只要某家提供方的 CLI 已安装并在你的 `PATH` 上，它就会出现在 **Add Project** 里。所以第一步永远是一样的：按那个工具自己的文档把你想用的 CLI 装好并登录。一旦 `claude --version`（或 `codex`、`gemini`）能在你的终端里正常运行，Specrails 就能用它了。
+四家都是**默认启用**的。CLI 在 `PATH` 上就会显示。Kimi 请先确认
+`kimi --version`，再运行 `kimi login`。
 
 ## 为一个项目安装单个提供方
 
@@ -25,40 +28,45 @@ Specrails 并不绑定在某一个 AI 上。应用里所有会调用 AI 的环
 关于多提供方项目，有几点值得了解：
 
 - **只有一个提供方时，行为和以前完全一样。** 如果一个项目只有单个提供方，你在任何地方都不会看到提供方选择器——应用保持干净、简单。
-- **右侧边栏只显示所有已安装提供方都支持的板块。** 因为 Agents（profile）是 Claude 独有的概念，所以一旦项目里包含任何非 Claude 的提供方，**Agents** 板块就会消失。其余的（Specs、Code、Analytics、Integrations、Terminal、Chat）都会保留。
+- **UI 由 capability 驱动。** Claude 和 Kimi 支持按提供方隔离的
+  profile；Codex 和 Gemini 使用 legacy mode。
 - **提供方在创建后就锁定了。** 在这个版本里，你在添加项目时选定提供方，之后无法再从 Settings 更改。如果你需要不同的组合，那就新建一个项目。
 
 ## 按调用逐个选择提供方
 
 多提供方项目真正的价值，在于为每个任务挑到合适的 AI——而无需改动任何全局设置。凡是会运行 AI 的地方，都会出现一个小小的提供方选择器（仅当项目拥有不止一个提供方时）：
 
-- **Add Spec**——有一个引擎选择器，让你用喜欢的提供方来 Explore 或 Quick 生成规格。
+- **Add Spec**——Explore 支持 Kimi；Quick Spec 只显示能够保证安全
+  pure-output 边界的提供方，因此不包含 Kimi。
 - **rail 头部**——在启动某条具体的 rail 之前，为它挑选引擎。
 - **终端**——「Open AI CLI」（Sparkles）按钮会打开一个提供方菜单，让你在该项目目录下进入任意已安装的 CLI。
 
 你的选择会按项目被记住，默认是主提供方，所以你不用每次都重新选。
 
-## 只有 Claude 才能做的事
+## Capability 差异
 
-有少数功能天生就是 Claude 专属的，因此当其他提供方参与时，它们要么被隐藏、要么被跳过：
+Kimi 支持 Project/Agent Chat、Explore/proposal、Quick Launcher
+（`/opsx:ff`）、rail、Freestyle、没有 Decider 的 loop、profile/手动 role、
+MCP、Serena、terminal 和附件。
 
-- **Agents（profile）**——按项目的 agent 目录与模型路由。在任何包含非 Claude 提供方的项目上都会隐藏。
-- **Freestyle rail**——始终在 Claude 上运行。
-- **Contract Refine**——对已提交规格追加的「Contract Layer」环节，只有当对话的提供方是 Claude 时才会运行。
-- **Add Spec 高级模式**（SMASH / Contract Layer）——对非 Claude 引擎隐藏。
-
-其余的一切——Explore、Quick spec、完整的 rail 流水线、AI Edit、聊天、成本分析——三家全都能用。
+`kimi -p` 会自动批准工具，无法强制 no-tools/read-only 边界。因此
+Quick Spec、AI Edit、Contract Refine、SMASH/Re-SMASH、Project Builder
+blueprint/milestone 生成、Loop Decider、文件摘要/construction story 和
+Agent Studio automation 都会在 spawn 前拒绝。AI auto-title 使用确定性
+fallback。详见 [Kimi 指南](../../../kimi.md)。
 
 ## 跨提供方的成本追踪
 
-**Analytics** 页面会追踪每一次产生费用的调用，无论用的是哪家提供方。在多提供方项目上，它还会加上引擎筛选标签，方便你按提供方对比开销。Claude 会报告自己的精确成本；而对 Codex 和 Gemini，Specrails 会用内置的费率表来估算成本，所以那些数字是接近的近似值，而非实际账单金额。
+**Analytics** 记录实际启动的调用。Claude 报告成本，Codex/Gemini
+使用估算。Kimi 不报告 authoritative token 或 USD cost，因此这些字段
+保持为空。
 
 ## 疑难排查
 
-- **我装了某个提供方，却没出现在选项里。** 确认该 CLI 在你的 `PATH` 上（在一个全新终端里试试 `claude --version` / `codex --version` / `gemini --version`）。应用是通过你系统的 `PATH` 来探测提供方 CLI 的。
+- **我装了某个提供方，却没出现在选项里。** 检查 `claude --version` / `codex --version` / `gemini --version` / `kimi --version`。
 - **聊天里没加载 Codex 的 MCP 服务器。** Codex 从你的全局 `~/.codex/config.toml` 读取 MCP 服务器——用 `codex mcp add` 在那里注册它们。
 - **紧急停用。** 可以通过环境变量在应用范围内关闭某个提供方（`SPECRAILS_CODEX_BETA=0` 或 `SPECRAILS_GEMINI_BETA=0`）。这只会把提供方从*选择列表*中隐藏；很少会用到。
 
 ## 另见
 
-各提供方的专属指南会对每个 CLI 讲得更深入：Codex 指南和 Gemini 指南都涵盖了安装设置、能做什么，以及各自特有的小脾气。
+请参阅 [Kimi 指南](../../../kimi.md)、Codex 指南和 Gemini 指南。

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

@@ -21,7 +21,7 @@
 3. 点进插件，**预览安装**——这会在任何改动发生之前，明确告诉你哪些文件会被改动。
 4. 点击 **安装**。安装过程中你会看到实时进度。
 
-在底层，安装是*精准且增量*的：它只会把自己的条目加进你项目的 `.mcp.json`（对某些插件，还会在受保护的 `.claude/agents/` 命名空间下加一个片段文件）。它绝不会整体重写你的配置，而且再装第二个插件也绝不会干扰第一个。如果安装无法自我验证为健康状态，它会干净利落地回滚。
+底层安装是*精准且增量*的：它只向所选 provider 的原生 MCP 配置添加自己的条目（某些 Claude 安装还会写入 `.claude/agents/` 片段）。它不会整体重写配置；健康检查失败时会干净回滚。
 
 ## 管理已安装的插件
 
@@ -37,8 +37,8 @@
 
 ## 提供方相关说明
 
-插件是「提供方感知」的。Serena 及类似的 MCP 插件，会对那些通过项目 `.mcp.json` 注册 MCP 的提供方（Claude 和 Gemini）生效。对于 Codex 项目，MCP 服务器是通过 Codex 自己的全局配置来管理的，因此 **Integrations** 里的插件条目会相应地被过滤掉。Integrations 里的 Jira 卡片与提供方无关，对所有人都会显示——参见 Jira 指南。
+插件是 provider-aware 的。Serena 通过 `.mcp.json` 支持 Claude，通过项目隔离的 `CODEX_HOME` 和 `codex mcp add` 支持 Codex，并通过 `.kimi-code/mcp.json` 支持 Kimi。只有 manifest 声明支持时才显示，因此 Gemini 不提供 Serena。Jira 卡片与 provider 无关。
 
 ## 受保留的文件
 
-插件会管理你项目里一小撮定义明确的文件：你的 `.mcp.json`（精准合并）、`.specrails/plugins/` 下的一些状态，以及位于 `.claude/agents/custom-<plugin>.md` 的各插件 agent 片段。如果你想和队友共享某个集成，这些都是可以提交进仓库的团队资产——应用绝不会盲目覆盖它们。
+插件只管理 provider 的原生 MCP 配置、`.specrails/plugins/` 状态，以及 Claude 确实需要时的 `.claude/agents/custom-<plugin>.md` 片段。Kimi 条目位于 `.kimi-code/mcp.json`；应用不会为 Kimi 写 Claude-only 片段，也不会盲目覆盖配置。

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

@@ -22,7 +22,12 @@ Agent Chat 通过内嵌的 **Specrails MCP 服务器**来驱动应用，因此
 
 ## 提供方与模型
 
-在消息框正上方，你可以选择**提供方**（Claude、Codex 或 Gemini）及其**模型**。每个提供方都有各自的模型清单，切换提供方会以该提供方的默认模型开启一段全新会话——因此你可以，比如说，用 Claude 驱动应用，再切到 Codex 进行另一段对话，两者互不串扰。
+在消息框上方可选择**提供方**（Claude、Codex、Gemini 或 Kimi）及其
+**模型**。切换提供方会开始独立 session。
+
+对于 Kimi，level 会限制 Specrails MCP 工具，但不会把 `kimi -p` 变成
+sandbox：Kimi native 工具会自动批准。不安全的 pure-output action 会在
+spawn 前拒绝；详见 [Kimi matrix](../../../kimi.md)。
 
 ## 权限级别——缰绳在你手里
 

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

@@ -35,8 +35,8 @@ rail 是一条**执行通道**。你从 SpecsBoard 上拖一张 spec 卡片放
 | **状态标签** | `idle`、`running` 或 `failed`。这里没有单独的"completed"——任务干净地跑完后，rail 会回到 `idle`。 |
 | **spec 列表** | 分配给这条 rail 的 ID。可以再拖进来，也可以拖出去解除关联。 |
 | **Loop 选择器** | 这条 rail 运行的 Loop——内置的（`Implement` / `Batch` / `Freestyle`）或某个自定义 loop。见下表。按 rail 单独记忆。 |
-| **Profile 选择器** | 运行哪个 Agent Profile（仅限 Claude rail）。只有当项目至少有一个 Profile 时才会出现。 |
-| **引擎选择器** | 这条 rail 用哪个已安装的提供方来跑——Claude、Codex 或 Gemini。仅当项目装有不止一个提供方时才显示。见 [为每条 rail 选择引擎](picking-an-engine-per-rail)。 |
+| **Profile 选择器** | 使用哪个 provider profile（Claude/Kimi rail）。 |
+| **引擎选择器** | 哪个 provider 运行 rail——Claude、Codex、Gemini 或 Kimi。 |
 | **▶ Play / ■ Stop** | 启动或取消。 |
 
 ### rail 运行的是什么：Loop
@@ -47,9 +47,11 @@ rail 是一条**执行通道**。你从 SpecsBoard 上拖一张 spec 卡片放
 |------|---------|--------------|
 | **Implement** | `/specrails:implement` | 一个任务覆盖这条 rail 上的所有 spec。跑完整的 Architect → Developer → Reviewer → Ship 流水线。日常默认选项。 |
 | **Batch** | `/specrails:batch-implement` | 一个任务，按依赖感知的批次（wave）依次处理 rail 上的各个 spec。最适合一组相关的 spec。 |
-| **Freestyle** | Freestyle | Claude 自主实现每个 spec，**绕过**流水线。每个 spec 一个独立任务。仅限 Claude。 |
+| **Freestyle** | Freestyle | Claude 或 Kimi 自主实现每个 spec，**绕过**流水线。 |
 
-Freestyle 是个特例：它跳过 Agent 链条，把原始 spec 直接交给 Claude，让它用自己的原生工具去做。因为它比较"放飞"，所以按下 Play 会先弹出一个确认框，而且有一个按 rail 单独的模型选择器，让你在 Haiku / Sonnet / Opus 之间挑选。只有当 rail 的引擎是 Claude 时它才会出现。Freestyle 运行还是唯一会**一直开着等你**的任务：在任务详情的输入框里和它聊天，满意了就点击 **Finalize**（其他所有任务都会自己收尾）。
+Freestyle 使用 provider 的 native tool/model。Claude 有 persistent
+interactive transport；Kimi 使用没有 persistent stdin 的 agentic
+`kimi -p` process。
 
 除了这些内置 loop，你还可以**搭建自己的 loop**——重复一个 verify → fix → verify 的循环直到目标达成、在 AI 步骤之间串联 shell 命令，等等。这些自定义 loop 会出现在同一个 Loop 选择器里。这就是下一个大点子：[Loop Builder](the-loop-builder)。
 
@@ -81,7 +83,8 @@ Freestyle 是个特例：它跳过 Agent 链条，把原始 spec 直接交给 Cl
 
 ## 如果一条 rail 启动不起来
 
-如果你选了一个对应 CLI 还没装到机器上的引擎，启动会**快速失败**，而不是开一个坏掉的任务——什么都不会启动。装上缺失的提供方 CLI（[使用 Codex](../integrations/using-codex)、[使用 Gemini](../integrations/using-gemini)）再启动一次即可。缺 Claude 或 Codex 时会给出精确的 "*<provider> CLI not found*" 提示；缺 Gemini 目前会显示一个通用的启动错误，但结果是一样的。
+如果缺少所选 CLI，会在 spawn 前失败。Kimi 需要安装并登录 `kimi`
+0.27+；Desktop 不会启动 server。
 
 ## 全部停下
 
@@ -96,4 +99,4 @@ Freestyle 是个特例：它跳过 Agent 链条，把原始 spec 直接交给 Cl
 - [Loop Builder](the-loop-builder)——rail 运行的是什么，以及如何搭建你自己的 loop。
 - [任务详情视图](the-job-detail-view)——阶段、实时指标、工单卡片。
 - [批量实现与多功能](batch-implement-and-multi-feature)——一次跑多个 spec。
-- [为每条 rail 选择引擎](picking-an-engine-per-rail)——Claude、Codex 还是 Gemini。
+- [为每条 rail 选择引擎](picking-an-engine-per-rail)——Claude、Codex、Gemini 或 Kimi。

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

@@ -94,7 +94,8 @@ Architect ──► Developer ──► Reviewer ──► Ship
 - **总计行是真实的。** 输入框会显示一条实时的 `N 轮 · $X` 摘要，由每个已完成轮次的真实用量累加而来——和本页"绝不猜数字"的承诺一致。
 - **会话有两种结束方式。** 大多数任务**自己收尾**：一旦某轮结束且没有排队的消息，会话就自行落定、任务完成——你的消息是可选的引导，从来不是义务。一个低调的**立即收尾**操作可以提前结束它，保留到目前为止产出的一切。**Freestyle** 任务是例外：它们在轮次之间待命，直到你点击 **Finalize**——这正是它的设计，一场由你来关闭的往返会话。
 - **loop 运行中，消息会送到活跃的步骤。** 在内置或自定义 loop 上，你的消息会到达**此刻正在运行的 AI 步骤**。步骤之间（Loop Decider 思考时，或 shell 命令运行时）输入框会短暂显示*"等待下一步……"*状态——你草拟的文字会保留，下一个 AI 步骤启动时发送会重新可用。**结算此步骤**可以提前结束当前步骤，让 loop 带着它的产出继续前进。
-- **目前仅限 Claude。** Codex 和 Gemini 任务和以前一样一次性运行——不会出现输入框。（服务器运维可以用 `SPECRAILS_INTERACTIVE_JOBS=false` 关掉整个功能。）
+- **persistent interaction 仅限 Claude。** Codex、Gemini、Kimi 都是
+  one-shot；Kimi chat 在收到 resume hint 后用新的 `kimi --session=<id> -p` 恢复。
 
 ## 诊断导出
 

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

@@ -81,4 +81,4 @@ Project B   ▶ Rail running feature Y   ┘
 
 - [Rail 与任务](rails-and-jobs)——深入理解队列模型。
 - [任务详情视图](the-job-detail-view)——实时观看一次批量运行。
-- [为每条 rail 选择引擎](picking-an-engine-per-rail)——注意 Batch 可在任意提供方上运行；Freestyle 仅限 Claude。
+- [为每条 rail 选择引擎](picking-an-engine-per-rail)——Batch 可在任意提供方上运行；Freestyle 可用于 Claude 和 Kimi。

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

@@ -1,6 +1,7 @@
 # 为每条 rail 选择引擎
 
-Specrails desktop 把 **Claude Code**、**Codex CLI** 和 **Gemini CLI** 都当作一等公民的引擎。一个项目可以装其中一个、两个，或三个全装——而当装的不止一个时，你就能为每条 rail 选择用哪个引擎。本页讲解按 rail 的引擎选择器，以及什么时候该选哪一个。
+Specrails desktop 把 **Claude Code**、**Codex CLI**、**Gemini CLI** 和
+**Kimi Code** 都当作一等引擎。可安装任何 compatible 组合。
 
 ## 选择器何时出现
 
@@ -13,7 +14,7 @@ Specrails desktop 把 **Claude Code**、**Codex CLI** 和 **Gemini CLI** 都当
 ## 如何选择一个引擎
 
 1. 确认这条 rail 的引擎选择器正在显示（项目有 2 个及以上提供方）。
-2. 点开它，选 **Claude**、**Codex** 或 **Gemini**。
+2. 选择 **Claude**、**Codex**、**Gemini** 或 **Kimi**。
 3. 用 **▶ Play** 启动这条 rail。
 
 被选中的引擎会跑这条 rail 流水线的每一个阶段。如果所选引擎对应的 CLI 没装，启动会快速失败——什么都不会启动。装上缺失的 CLI 再试一次即可。
@@ -24,19 +25,16 @@ Specrails desktop 把 **Claude Code**、**Codex CLI** 和 **Gemini CLI** 都当
 
 | 引擎 | 在什么情况下选它…… | 说明 |
 |--------|--------------------|-------|
-| **Claude** | 你想要全套功能：Agent Profile、Freestyle、原生成本上报、最丰富的工具支持。大多数工作的默认之选。 | 唯一支持 **Agent Profile**、**Freestyle** 以及几个 Claude 专属 spec 功能（Contract Layer、SMASH）的引擎。 |
+| **Claude** | 需要原生成本、持久交互或严格 tool policy。 | Profile、Freestyle 和 structured transform。 |
 | **Codex** | 你更喜欢 OpenAI Codex CLI，或想跨提供方对比实现。 | `codex` ≥ 0.128.0。无原生成本上报——应用会用自己的价格表来补上成本。Profile 不适用。 |
 | **Gemini** | 你想用 Google 的 Gemini CLI、原生遥测，或为常规 spec 跑得更省钱。 | `gemini` ≥ 0.11.0（需设置 `GEMINI_API_KEY`）。原生 OTLP 遥测。Profile 不适用。 |
+| **Kimi** | 用 agentic Kimi 跑 Implement、Batch、Freestyle 或无 Decider 的 loop。 | 外部 `kimi` ≥ 0.27.0；profile/role，effort 仅 K3；token/cost unavailable。 |
 
-### Claude 专属功能
+### Capability 差异
 
-有几样东西只在 Claude rail 上能用——如果你需要它们，就选 Claude：
-
-- **Agent Profile**——按 Agent 的模型路由。在 Codex 或 Gemini rail 上，运行始终走传统模式，所选的任何 Profile 都会被**忽略**。非 Claude 引擎下 Profile 选择器会被隐藏。
-- **Freestyle**——那个自主的、绕过流水线的模式。`Freestyle` 分段及其 Haiku/Sonnet/Opus 模型选择器，只有当 rail 的引擎是 Claude 时才会出现。
-- **Contract Layer 与 SMASH**——Claude 专属的 spec 优化功能（这些是 Add Spec 的选项，不是 rail 的选项，但同样的限制适用）。
-
-如果一个项目混用了引擎，右侧栏只会显示**每一个**已安装提供方都支持的区块——所以在一个含有任何非 Claude 提供方的项目上，**Agents** 区会彻底消失，因为 Profile 是 Claude 特有的。
+Claude/Kimi 支持 Profile 和 Freestyle；Codex/Gemini 使用 legacy。Kimi
+拒绝 Loop Decider 和 [Kimi 指南](../../../kimi.md) 中的 pure-output
+transform。Claude/Kimi Profile 彼此隔离。
 
 ## 一套实用的工作流
 
@@ -49,12 +47,14 @@ Specrails desktop 把 **Claude Code**、**Codex CLI** 和 **Gemini CLI** 都当
 ## 几点需要记住
 
 - **提供方选择在项目创建后不可更改**（v1）。你在添加项目时选定要安装的提供方；之后没有 Settings 开关可以再增删。
-- **成本始终会被追踪**，即便是不原生上报成本的引擎——应用会回退到价格表，让 Codex 和 Gemini 的运行也照样出现在[分析](../analytics/tracking-cost)里。
+- **available metrics 会记录。** Kimi 不提供 authoritative token/USD
+  cost，字段保持为空。
 - 在多提供方项目上，**终端的"Open AI CLI"按钮**也会提供一个提供方选择器，方便你想手动驱动某个 CLI 时使用。
 
 ## 接下来去哪儿
 
 - [使用 Codex](../integrations/using-codex)——安装与登录。
 - [使用 Gemini](../integrations/using-gemini)——安装、`GEMINI_API_KEY`、遥测。
+- [使用 Kimi](../../../kimi.md)——安装与完整矩阵。
 - [Rail 与任务](rails-and-jobs)——队列与启动流程。
 - [追踪成本](../analytics/tracking-cost)——按引擎的成本明细。

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

@@ -17,7 +17,7 @@
 
 - loop 住在 **Loops** 区里（左侧栏，和你的项目并列）——它们是**全局**的，跨所有项目共享。
 - 一条 rail 在它的头部（Loop 选择器）**挑一个 loop**，按下 Play 时就运行它。
-- 是 **rail** 决定提供方、模型和推理强度——而*不是* loop 的步骤。同一个 loop 跑在 Claude、Codex 还是 Gemini 上，取决于这条 rail。
+- **rail** 决定 provider、model 和 compatible effort。compatible loop 可在 Claude、Codex、Gemini 或 Kimi 上运行。
 
 所以：一个 loop 只需搭一次，之后就能在任意项目的任意 rail 上挑来用。
 
@@ -41,6 +41,10 @@
 
 边按顺序把各个步骤连起来。**Loop Decider** 有两个带标签的输出——**continue** 和 **stop**——所以你把"还没完"接回到活儿里去，把"完成了"接出去到一个 End。
 
+> **Kimi 支持包含 AI/shell step 的 loop，但不支持 Loop Decider。**
+> verdict 是 pure-output，`kimi -p` 无法强制 no-tools 边界；run 会在第一
+> 个 step 前拒绝。
+
 ### 编写步骤文本
 
 在任意 AI Step 或 Decider 里，你都可以引用：
@@ -57,7 +61,7 @@
 |-------|--------------|
 | **Max iterations** | 不管 Decider 怎么裁决，它最多能绕回多少次的硬上限。 |
 | **Timeout (min)** | 整次运行的挂钟时间上限。 |
-| **Max cost ($)** | *可选。* 一旦累计成本越过你的预算就停掉 loop。它在**步骤之间**检查（一个步骤的成本只有等它结束才知道），所以可能会超出一个步骤。在 Claude 上成本是精确的；在 Codex 和 Gemini 上是估算值。留空就表示不设上限。 |
+| **Max cost ($)** | *可选。* Claude 报告 cost；Codex/Gemini 使用估算。Kimi 不报告 authoritative USD cost。 |
 
 ## 有把握地搭建
 

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

@@ -2,6 +2,10 @@
 
 当你已经清楚自己想要什么时，Quick 模式正合适。你输入想法，AI 写出完整的 spec，它就以 **待办** 状态落在你的看板上。不需要来回讨论——只管描述，然后开干。
 
+> **Kimi 不支持 Quick Spec。** `kimi -p` 无法强制此表单的 pure-output
+> 边界，因此请求会在 spawn 前拒绝。请使用 Explore、Raw 或 Quick
+> Launcher（`/opsx:ff`）。
+
 ## 用 Quick 模式创建 spec
 
 要快速创建一份 spec：
@@ -19,7 +23,8 @@
 
 **模型**——默认情况下，AI 会挑选一个合适的模型。如果你想要更快或更强的模型，可以在模型选择器里按 spec 单独覆写。
 
-**引擎**——如果你的项目安装了不止一个 AI provider（Claude、Codex、Gemini 的任意组合），对话框顶部会有一个引擎选择器，让你选择由哪一个来生成这份 spec。你的选择会按项目记住。单 provider 的项目不会显示它——因为没有可选的余地。
+**引擎**——选择器只显示 **compatible** provider；Quick Spec 不包含
+Kimi。
 
 **上下文**——Quick 模式通常作为单轮运行，因为它不需要读取你的代码库就能根据你的描述写出 spec。但一个上下文滑块可以给它更多素材：
 

package/docs/internals/README.md

@@ -21,7 +21,10 @@ If you're a user looking for **how do I do X?** docs, head back to the [user gui
 | [gemini-mcp-registration.md](gemini-mcp-registration.md) | How MCP servers actually reach gemini-cli (`.gemini/settings.json` + trust env, FQN tool prefix) and the deferred `.mcp.json` gap on non-agent-chat surfaces |
 | [browser-capture-performance.md](browser-capture-performance.md) | Embedded-browser fluidity: the CDP screencast → WS → canvas pipeline, the latency levers (non-blocking navigation, input coalescing, latest-frame-wins drawing, frame conflation), tuning knobs, and the OAuth popup design |
 
-**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`.
+**See also:** the app registers Claude Code, Codex CLI, Gemini CLI, and Kimi
+Code as first-class engines. See [`../kimi.md`](../kimi.md),
+[`../codex.md`](../codex.md), and [`../gemini.md`](../gemini.md). First-class
+status is capability-aware: Kimi pure-output transforms fail closed.
 
 ## Contributing