specrails-desktop 2.8.0 → 2.9.0

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

@@ -0,0 +1,45 @@
+# Profile 与均衡默认值
+
+**Profile** 是一份为流水线运行而保存的「配方」。它在同一处回答了三个问题：
+
+1. **哪些 Agent** 参与（基础三人组，外加任何专家型或自定义 Agent）。
+2. 每个 Agent 用**哪个模型**运行。
+3. 任务**如何路由**到这些 Agent。
+
+你可以在任意项目的 **Agents** 区找到 Profile（右侧边栏 → **Agents** → **Profile** 标签页）。
+
+## 均衡默认值
+
+开箱即用时，项目会解析到一个合理的 **default** Profile。它包含基础三人组——`sr-architect`、`sr-developer`、`sr-reviewer`——并通过一条兜底规则把每个任务都路由给 developer。模型搭配在日常工作中保持均衡：在关键处用足够强的模型，而不会每一步都去动用最贵的那一个。
+
+如果你的项目此前已经用老办法配置过 Agent 模型（写在 Agent 文件的 frontmatter 里），那么 **迁移** 按钮会读取这些配置，并构建出一个完整复刻当前行为的 `default` Profile——零损失，在你决定调校它之前什么都不会变。
+
+重点是：**你不必先创建 Profile 才能使用 Specrails。** 默认值就能正常工作。Profile 是你想更进一步时的手段。
+
+## 一次运行如何选定 Profile
+
+当你启动一条 rail 时，Specrails 会按以下顺序挑选 Profile：
+
+1. 你在 rail 头部做出的**显式选择**（见下文）。
+2. 你的**个人开发者偏好**——你为此项目标记的、属于自己的默认 Profile（它只对你本地生效，不会被提交）。
+3. 项目的 **`default`** Profile。
+
+Profile 会在*启动时被快照固定*，因此一个批次里的每条 rail 都可以运行不同的 Profile，而日后改动某个 Profile 也绝不会重写已经启动的任务。
+
+## 为每条 rail 选用 Profile
+
+Profile 的选择就发生在你启动的地方——**rail 头部**，通过 Profile 选择器完成。
+
+- 从下拉菜单中挑一个 Profile，**仅用于本次启动**。
+- 使用持久化选项，把某个 Profile 设为这条 rail 此后固定的选择。
+
+整个流程就这么简单：选一个 Profile、启动、搞定。同一批次中并发运行的 rail 各自带着自己的 Profile，所以一个快速修复和一个重量级功能可以并排运行、采用各不相同的配置。
+
+## 当 Agents 区悄无声息时
+
+Profile 是 Claude 的能力。在包含非 Claude 提供商（Codex 或 Gemini）的项目上，Agents 区会被隐藏，rail 会在没有 Profile 的情况下运行——这是预期行为，并非 bug。Profile 还要求项目中的 `specrails-core` 足够新；如果版本偏旧，你会看到一条黄色横幅。你创建的 Profile 仍会**保存**——只是在 core 更新之前不会影响流水线。按横幅中给出的命令更新，即可解锁它们。
+
+## 接下来去哪儿
+
+- [按 Agent 自定义模型](customizing-models-per-agent)——打造 `fast` 和 `max` Profile。
+- [自定义 Agent 与目录](custom-agents-catalog)——查看并扩充你的团队。

package/docs/guide/zh/agents/3-customizing-models-per-agent.md

@@ -0,0 +1,60 @@
+# 按 Agent 自定义模型
+
+Profile 让你能做的最有用的一件事，就是**为每一步挑选合适的模型**。规划这一步也许值得动用你最强的模型；而一个常规的建造步骤，换上更快、更便宜的模型也许就足够称心。Profile 让你能把这种意图精确地表达出来。
+
+这正是「共享 vs. 因项目而异」这一划分见效的地方：
+
+- Agent 的*定义*在你的团队间保持共享。
+- *每个 Agent 用哪个模型运行*则**因项目而异**，配置在 Profile 内，且只影响你自己的项目。
+
+改一个模型，你就改变了这个项目的成本与行为——而不会动到任何其他人的配置，也不会动到 Agent 底层的指令。
+
+## 更改某个 Agent 使用的模型
+
+在 **Agents → Profile** 中选中一个 Profile，打开它的 Agent 链编辑器。链中的每个 Agent 都有一个模型字段。此外还有一个**编排器**模型，负责流水线最顶层的协调。
+
+模型值是一些别名——对 Claude 而言就是 `opus`、`sonnet` 和 `haiku`（从最强 → 最快）。按 Agent 设置你想要的别名：
+
+- 把某个 Agent 的模型**留空**，即回退到该 Agent 文件自带的默认值。
+- 显式设置它，则仅在此 Profile 内覆盖。
+
+保存之后，下一条用该 Profile 启动的 rail 就会使用新模型。已在运行的任务则保留它们的快照。
+
+## 创建像 `fast` 和 `max` 这样的 Profile
+
+很自然的做法，是准备几个命名好的 Profile，视任务不同随手取用：
+
+**一个 `fast` Profile**——用于小型、低风险的改动，你追求的是速度和更小的账单：
+
+- Architect：一个中档或快速的模型——方案本身很简单。
+- Developer：一个快速的模型——改动是机械性的。
+- Reviewer：保持稳妥，但这里你也可以适当精简。
+
+**一个 `max` Profile**——用于棘手、高风险的功能，你希望每一步都尽可能锋利：
+
+- Architect、developer、reviewer：全线都用你最强的模型。
+
+### 两种构建方式
+
+1. **复制再微调** *（推荐）。* 选中你的 `default` Profile，**复制** 一份，给副本起一个 kebab-case 名称，比如 `fast` 或 `max`，再逐个调整每个 Agent 的模型。你继承了一套已知可靠的链和路由，只改动你确实想改的部分。
+2. **从空白开始。** 创建一个 **空白 Profile** 并亲手组装这条链。你仍然必须包含基础三人组（`sr-architect`、`sr-developer`、`sr-reviewer`）——流水线依赖这三个 Agent——以及恰好一条终止性的兜底路由规则，且它必须排在最后。
+
+Profile 名称使用小写 kebab-case（例如 `fast`、`max`、`cheap-and-cheerful`）。
+
+## 把任务路由到特定 Agent
+
+Profile 的**路由规则**决定由哪个 Agent 处理带标签的任务。每条规则列出若干任务标签和一个目标 Agent；标签最先匹配上的规则胜出，末尾的一条 `default: true` 规则则兜住其余所有任务。只有真正在 Profile 链中的 Agent 才能作为路由目标——编辑器会强制这一点。
+
+日常使用中你不会去碰路由：兜底规则把工作交给 developer，这就是对的。当你想让带 `migration` 标签的工作转交给某个专家型 Agent 时，再去动用标签规则。
+
+## 启动时挑选 Profile
+
+所有这些都在启动时汇聚到一处：在 rail 头部，为每条 rail 选择 `fast`、`max` 或 `default`。一个批次可以混搭——一个小修复跑 `fast`、一个大功能跑 `max`，两者同时运行。选择流程参见 [Profile 与均衡默认值](profiles-and-the-balanced-default)。
+
+## 关于安全的一点说明
+
+删除一个 Profile 对进行中的工作是安全的：已用它启动的任务保留各自的快照，而未来的启动只会沿着解析顺序回退。尽管放手去试。
+
+## 接下来去哪儿
+
+- [自定义 Agent 与目录](custom-agents-catalog)——添加可放进你的链里的 Agent。

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

@@ -0,0 +1,43 @@
+# 自定义 Agent 与目录
+
+Profile 决定的是*哪些 Agent 运行、用什么模型*。但 Agent 本身又是从哪儿来的呢？答案就是 **Agent 目录**。
+
+在任意项目中打开 **Agents → 目录**。它是一个只读视图，列出该项目可用的每一个 Agent，分为两组：
+
+- **上游 Agent**——随 `specrails-core` 一起发布的 Agent：基础三人组（`sr-architect`、`sr-developer`、`sr-reviewer`）以及像 `sr-merge-resolver` 这样的任何专家型 Agent。
+- **自定义 Agent**——你自己添加的 Agent，命名为 `custom-*`。
+
+每个目录条目都会展示该 Agent 的用途和它的默认模型，这样在把 Agent 接入某条 Profile 链之前，你就能看清整支阵容。
+
+## 添加一个自定义 Agent
+
+自定义 Agent 就是你仓库里 `.claude/agents/` 目录下的普通 Markdown 文件，命名为 `custom-<某某>.md`。文件内容包含该 Agent 的指令（它的系统提示词），以及一小段 frontmatter 头部，其中含有一个默认的 `model:`。
+
+文件一旦存在于项目中，它就会作为自定义 Agent 出现在目录里，你便可以把它的 id 加入任意 Profile 的 Agent 链（并把任务路由给它）。id 必须与文件名一致——`custom-docs` 这个条目对应的是 `.claude/agents/custom-docs.md`。
+
+由于它们就住在你的仓库里，自定义 Agent 是**可提交的团队资产**：提交这个文件，你的整个团队就都拥有了这个 Agent。这呼应了贯穿整个 Agents 区的核心观念——
+
+> **Agent 定义是共享的（它们住在仓库里，随 `git` 一起流转）。模型配置则因项目而异（它住在 Profile 里）。**
+
+`custom-*` 命名空间是保留且受保护的：`specrails-core` 的 `init` 和 `update` 命令绝不会触碰 `.claude/agents/custom-*.md`，因此你的自定义 Agent 能在 core 升级中毫发无损地保留下来。（同样的保护也覆盖插件贡献的片段，比如 `custom-serena.md`。）
+
+## 让自定义 Agent 上岗
+
+典型流程如下：
+
+1. 编写 `.claude/agents/custom-<name>.md`，写好指令和一个默认模型。
+2. 确认它出现在 **Agents → 目录** 的「自定义」分组下。
+3. 在 **Agents → Profile** 中，把这个 Agent 加入某条 Profile 链（也可在该 Profile 内覆盖它的模型）。
+4. 添加一条路由规则，让带有合适标签的任务到达它——或者依赖链的顺序。
+5. 在 rail 头部用该 Profile 启动一条 rail。
+
+## 观察 Profile 的表现
+
+Agents 区还有一个 **用量** 标签页——按 Profile 拆分，展示在所选时间窗口内每个 Profile 各启动了多少个任务。这是个快速的途径，既能确认你的 `fast`/`max` 划分是否真按你设想的方式在被使用，也能看出你的团队更偏爱哪个 Profile。
+
+## 整个章节回顾
+
+- **Agent** 是专职的团队成员——共享的三人组，外加专家型 Agent 和你的自定义 Agent。（[认识这些 Agent](meet-the-agents)）
+- **Profile** 打包了哪些 Agent 运行、用哪些模型、任务如何路由——在启动时按 rail 选用。default Profile 是日常里那个均衡之选。（[Profile 与均衡默认值](profiles-and-the-balanced-default)）
+- **模型** 在 Profile 内按 Agent、按项目调校——打造 `fast` 和 `max` 以匹配不同任务。（[按 Agent 自定义模型](customizing-models-per-agent)）
+- **目录** 展示每一个 Agent，而 `custom-*` 命名空间让你得以壮大团队——定义共享，配置因项目而异。

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

@@ -0,0 +1,49 @@
+# specrails 是什么
+
+欢迎使用 **specrails**——一款桌面应用，它能把 AI 编程助手变成一个真正的软件团队，在*你的*机器上、为*你的*项目工作。
+
+你不必再来回复制粘贴提示词，而是把想做的事描述成一个 **spec**，specrails 就会让它走完一整条开发流水线——设计、实现、评审、交付——而你可以全程实时围观。
+
+## Spec 驱动的 AI 开发
+
+specrails 的核心是一个朴素的想法：**想让 AI 写出好代码，最好的起点是一份清晰的 spec。**
+
+所谓 *spec*，是对一件具体工作的简短、结构化描述——一个功能、一处修复、一次重构。你可以在几秒内手写一份，也可以通过引导式对话来打磨：它会问出关键的问题，并帮你拟好草稿。每个 spec 都会成为项目看板上的一个**工单**，就像任何任务跟踪工具里的任务一样。
+
+接下来，把 spec 交给流水线，让 AI 来挑大梁。
+
+## 流水线：架构师 → 开发者 → 评审员 → 交付
+
+当你启动一个 spec 时，specrails 会让它依次走过四个阶段，每个阶段都由一个专注的 AI agent 来扮演：
+
+1. **架构师**——阅读你的 spec 和相关代码，然后规划这次改动：要动哪些文件，解决方案应该是什么样子。
+2. **开发者**——按照规划，写出真正的代码。
+3. **评审员**——检查成果的正确性与质量，在问题落到你头上之前先把它揪出来。
+4. **交付**——把改动收尾，让它随时可以提交。
+
+每个阶段运行时你都能看到，实时日志直接从 AI 流式输出。一切都不藏着掖着——万一哪里出了岔子，你能一眼看清问题出在哪儿。
+
+## 项目
+
+specrails 里的一切都围绕**项目**来组织。一个项目其实就是你电脑上存放某个代码库的文件夹。你可以添加任意多个项目，并在它们之间瞬间切换——每个项目都各自保留自己的 spec、任务历史、分析数据和设置。
+
+specrails 绝不会去碰你没让它碰的代码。它在你现有的仓库里工作，提交什么始终由你说了算。
+
+## 选择你的 AI 提供商
+
+specrails 支持主流的 AI 编程 CLI：
+
+- **Claude**（Claude Code）
+- **Codex**（Codex CLI）
+- **Gemini**（Gemini CLI）
+
+挑一个你已经在用的就行——或者多装几个，按任务来选。一个项目可以只跑一个提供商，也可以同时跑多个，所以你永远不会被某一个绑死。
+
+## 你会喜欢它的理由
+
+- **快而不乱**——spec 让 AI 保持专注，于是你得到的是有用的改动，而不是漫无边际的猜测。
+- **全程可见**——实时日志、清晰的流水线视图、按项目划分的分析，让你清楚地知道发生了什么、花了多少钱。
+- **你的机器，你的代码**——一切都在本地运行，针对的是你真实的仓库。
+- **一处搞定一切**——spec、任务、聊天、内置终端、成本跟踪，全都在同一个窗口里。
+
+准备好开始了吗？下一篇：[安装与首次运行](installing-and-first-run)。

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

@@ -0,0 +1,42 @@
+# 安装与首次运行
+
+把 specrails 装到机器上只需要几分钟。下面是完整流程。
+
+## 1. 下载并安装
+
+获取适合你平台的安装包：
+
+- **macOS（Apple Silicon）**——一个 `.dmg` 文件。打开它，把 **specrails** 拖进你的“应用程序”文件夹。
+- **Windows**——一个 `.exe` 安装程序。运行它，按提示操作即可。
+
+> **关于 macOS 和 Windows 安全提示的提醒**
+>
+> - 在 **Windows** 上，安装包暂时还没有代码签名，所以 SmartScreen 可能会弹出警告。点击 **更多信息 → 仍要运行** 即可继续。
+> - 在 **macOS** 上，应用已签名并经过公证，所以应该可以顺利打开。
+
+## 2. 你需要准备什么（前置条件）
+
+specrails 通过驱动真实的命令行工具来运行 AI 开发流水线，所以有几样东西得就位。好消息是：桌面应用**已经替你内置了其中大部分**（Node.js、npm 和 Git 都随应用一起打包），所以在一台全新的机器上，通常什么都不用装。
+
+specrails 唯一无法内置的，是 **AI 提供商 CLI** 本身。你至少需要其中之一：
+
+- **Claude Code**
+- **Codex CLI**
+- **Gemini CLI**
+
+把你打算用的那个装好，在终端里登录一次，就齐活了。specrails 会自动检测出有哪些提供商可用。
+
+> 如果哪天你看到某个工具被标记为缺失，应用会给出一个 **更多信息** 链接，里面有针对你操作系统、可直接复制粘贴的安装命令（macOS 用 Homebrew，Windows 用 winget，Linux 用 apt/dnf）。你随时都能重新检测，无需重启。
+
+## 3. 首次启动——欢迎界面
+
+第一次打开 specrails 时，你会看到一个简洁的**欢迎界面**。此时还没有任何项目，所以应用会邀请你添加第一个。
+
+你会看到：
+
+- 一段关于 specrails 用途的简短介绍。
+- 一个 **添加你的第一个项目** 按钮。
+
+整个上手流程就这么多——不用创建账号，也不用注册。specrails 完全在你的机器上运行。
+
+点击 **添加你的第一个项目**，继续阅读[添加你的第一个项目](adding-your-first-project)。

package/docs/guide/zh/getting-started/3-adding-your-first-project.md

@@ -0,0 +1,58 @@
+# 添加你的第一个项目
+
+一个项目其实就是你电脑上存放某个代码库的文件夹。我们来连接一个吧。
+
+## 打开“添加项目”对话框
+
+在欢迎界面点击 **添加你的第一个项目**（之后也可以点击左侧边栏里的 **添加项目** 按钮）。会弹出一个小对话框。
+
+## 填写详情
+
+**项目文件夹** *(必填)*
+
+把 specrails 指向存放你代码的文件夹。在桌面应用里，你可以点击文件夹图标来可视化浏览选择，也可以直接粘贴完整路径。这应该是你仓库的根目录——也就是那个包含你的代码、并且（通常）有一个 `.git` 目录的文件夹。
+
+**项目名称** *(可选)*
+
+显示在侧边栏里的友好标签。如果留空，specrails 会用文件夹名。
+
+**提供商**
+
+选择这个项目要使用哪个（些）AI 提供商。specrails 会把它在你机器上检测到的那些展示给你：
+
+- 🤖 **Claude**
+- ⚡ **Codex**
+- ✨ **Gemini**
+
+没找到的提供商会变灰，并标注为 *未找到*——安装并登录其中一个，然后重新打开对话框即可。默认情况下，所有可用的提供商都会被预选中，但你可以取消勾选，只留下想要的那个。如果你选了不止一个，**第一个** 会成为项目的默认提供商；之后你可以按任务来选择。
+
+> 后台会做一次快速检查，确认所需的工具都在。如果缺少某个关键工具，**添加** 按钮会保持禁用状态，并通过 **更多信息** 链接给出确切的安装命令。
+
+点击 **添加** 继续。
+
+## 几秒钟就跑完的设置
+
+如果该文件夹已经配置好了 specrails，那你就齐活了——项目会立刻出现在侧边栏里。
+
+如果这是个全新的项目，会运行一个简短的**设置向导**。它分三步：
+
+1. **配置**——为你选择的每个提供商确认基本信息。
+2. **安装**——specrails 自动完成项目设置。这是*快速*安装：开箱即用的模板 agent，几秒内就位。运行过程中你会看到实时日志。
+3. **完成**——一份汇总，确认一切就绪。
+
+对于多提供商项目，安装会按提供商逐个运行，一个接一个，“完成”这一步会为每个提供商显示一张卡片。
+
+## 会安装些什么
+
+设置刻意做得很轻量，而且**不侵入**。specrails 只往你的项目里加入少量配置，好让流水线知道该怎么运行：
+
+- 一个 `.specrails/` 文件夹，存放项目的 agent profile 和本地设置。
+- `.claude/agents/` 下的 agent 定义，为“架构师 → 开发者 → 评审员 → 交付”这条流水线提供支撑。
+
+仅此而已——设置过程中 specrails 不会改写你的源代码，而且这些文件可以放心提交，如果你想和团队共享这份配置的话。
+
+> **想要深度设置？** 应用刻意默认采用快速模板安装。如果你更想要 AI 增强流程（代码库分析与自定义 agent 人设），可以在终端里、从你的项目文件夹运行 `npx specrails-core@latest init`。
+
+## 你进来了
+
+设置一结束，specrails 就会把你带进项目的仪表盘。是时候逛一圈了——参见[仪表盘导览](the-dashboard-tour)。

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

@@ -0,0 +1,53 @@
+# 仪表盘导览
+
+项目添加好了，现在你看到的就是你的**项目仪表盘**——把 spec 变成已交付代码的大本营。下面带你认认路。
+
+## 整体格局
+
+窗口分为三个区域：
+
+- **左侧边栏**——你的项目列表。点击任意项目即可瞬间切换，窗口里其余的一切都会随之更新。**添加项目** 按钮也在这里。
+- **主区域**——当前项目的仪表盘：你的 spec，以及运行它们的流水线。
+- **右侧边栏**——在当前项目的各个区块之间导航。
+
+## 主仪表盘
+
+工作就在这里发生。仪表盘会展示：
+
+- **你的 spec**——你创建的工单，按状态组织（从 Backlog/待办 一直到 完成）。你可以用列表、网格或便利贴卡片的形式查看，随你喜欢。
+- **添加 spec 的入口**——开始一件新工作。你可以直接写一份快速 spec，也可以打开一个引导式的 **Explore** 对话，它会通过聊天帮你打磨想法，并替你拟好工单草稿。
+- **Rails**——这些是 spec 被构建的泳道。把一个 spec 拖到某条 rail 上并启动它，就会让它走过“架构师 → 开发者 → 评审员 → 交付”这条流水线。多条 rail 可以同时运行，所以你能并行处理好几件事。
+
+当一个 spec 正在运行时，你会看到它的流水线进度和实时日志——AI 在设计、编码、评审你的改动时的实时输出。
+
+## 右侧边栏：项目区块
+
+右侧边栏是你切换当前项目各部分的总开关。把鼠标悬停上去即可展开，也可以固定常开。你会看到这些区块：
+
+- **仪表盘**——spec 看板和 rails（你刚才待的地方）。
+- **任务**——这个项目的每一次流水线运行，无论过去还是当下，都带有状态、耗时，并能深入查看任意一次运行的详情和日志。
+- **分析**——你的 AI 用量花了多少钱。按天、按活动、按模型、按工单拆解的开销——不会有任何意外惊吓。
+- **Agent**——你项目的 agent profile：流水线里跑哪些 agent、它们各自用什么 AI 模型。*(仅限由 Claude 驱动的项目。)*
+- **代码**——一个只读的文件浏览器，附带通俗易懂的 AI 摘要，还有标签显示 AI 动过哪些文件。对想跟上进度的非开发者来说非常友好。
+- **集成**——可选的附加组件，比如把你的 spec 连接到 **Jira** 看板，或为 AI 启用额外的工具。
+- **设置**——项目级选项（遥测、预算、提供商配置等等）。
+
+> 有些区块只有在对你所选的提供商有意义时才会出现——例如，**Agent** 是 Claude 专属的。如果你没看到某个区块，那只是说明它不适用于这个项目的配置。
+
+## 状态栏
+
+窗口最底部有一条细长的横条。它虽小，却很顺手：
+
+- **连接指示灯**（左侧）——一个彩色圆点加标签，表明应用处于在线状态：绿色代表*已连接*，琥珀色代表*重新连接中*，蓝色代表刚重连后正在*同步中*。你很少会用到它，但需要时它能让人安心。
+- **总花费**（右侧）——你已花金额的实时累计，让成本始终一眼可见。
+- **终端开关**（最右侧）——打开内置的终端面板。随时按 **Cmd+J**（macOS）或 **Ctrl+J**（Windows/Linux）即可切换。它是一个完整的 shell，直接在你的项目文件夹里打开。
+
+## 几个顺手的快捷键
+
+- **Cmd/Ctrl+B**——固定或收起侧边栏。
+- **Cmd/Ctrl+J**——切换终端面板。
+- **Cmd/Ctrl+K**——打开搜索。
+
+## 下一步去哪儿
+
+地形就摸到这儿。从这里出发，最自然的第一步是**添加一个 spec** 并在某条 rail 上启动它——看着流水线从头跑到尾，然后去 **分析** 里看看花了多少钱。欢迎上路。

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

@@ -0,0 +1,78 @@
+# 分析与成本追踪
+
+每当 Specrails 替你运行一次 AI CLI——无论是一个流水线任务、一个 Quick spec、一段 Explore 会话、一次 AI 编辑，还是一份文件摘要——它都会记录下发生了什么：用了哪个模型、输入和输出了多少 token、耗时多久、花了多少钱。**分析**（Analytics）板块把这一切汇总成一个统一的仪表盘，让你随时清楚自己的 AI 开销都花在了哪里。
+
+从右侧边栏打开它（标签写作 **分析**）。你看到的所有内容都只针对当前所在的项目——切换项目，数字也会随之切换。
+
+## 什么算作支出
+
+Specrails 会追踪五类 AI 活动，我们称之为*来源*（surface）。每一类在所有图表中都使用统一的配色，方便你一眼认出：
+
+- **任务（Job）**——一条跑着 Architect → Developer → Reviewer → Ship 的流水线 rail。
+- **Quick spec**——通过快捷的 Add Spec 路径生成的 spec。
+- **Explore spec**——通过聊天来打磨 spec 的 Explore 会话。
+- **AI 编辑（AI edit）**——对某个 agent 或文件做的 AI 辅助优化。
+- **文件摘要（File summary）**——为 Code 浏览器提供支撑的那些通俗易懂的摘要。
+
+有两样东西是我们*故意*不去追踪的：聊天侧边栏和安装向导虽然也会启动 AI CLI，但它们永远不会出现在你的支出里。这样仪表盘反映的就是真实、可重复的工作，而不是顺手发生的闲聊。
+
+## 读懂仪表盘
+
+整个页面由几个区块自上而下组成：
+
+### 燃烧表（Hero）
+
+顶部那个醒目的大数字，就是你在所选时间段内的总支出，旁边还带一个 **vs prev** 的对比值，让你一眼就能看出相比上一个时间窗口是在涨还是在降。如果你才刚开始使用某个项目，空状态会告诉你追踪是从什么时候开始的（"Tracking started YYYY-MM-DD"）——这里没有历史回填，所以这块表只知道你在当前版本期间发生过的运行。
+
+### 每日时间线
+
+一张按天展示支出的堆叠柱状图，并按来源拆分。没有活动的日子会显示为零，而不是被跳过，这样你一周的形态才不会失真。要看清一批昂贵的运行*是什么时候*跑的，这是最快的方式。
+
+### Quick vs Explore
+
+一张并排卡片，对比你创建 spec 的两种风格。如果你的 Explore 会话还不到五次，它会给出一个温和的提示，而不是显示具有误导性的平均值——样本太小，做出来的对比并不可信。
+
+### 按模型
+
+按支出排序的最常用模型（最多十个）。点击任意模型，就能把整个仪表盘筛选到只看那一个模型——当你想知道某个高端模型究竟花了你多少钱时，这一招很实用。
+
+### 成本 vs 轮次散点图
+
+每一个点代表一次调用，横纵坐标对应成本和轮次数。异常值——那些既昂贵又轮次多的运行——会一下子跳出来。（为了保持流畅，散点图只展示你最近的 500 个点。）
+
+### 热门工单
+
+把*所有*来源合在一起后，最烧钱的十个工单，所以一个在 Explore 里花了一点、在任务里花了很多的工单，会显示出它真正的总开销。已删除的工单和无法归属的运行会各自归入专门的分组，这样就不会有任何开销悄悄从总计里消失。
+
+### 原始调用表
+
+最底层的事实：一行对应一次调用。这个区块有自己的二级筛选器，只作用于表格本身，所以你可以深入钻取而不打扰上方的那些图表。
+
+## 筛选
+
+顶部的吸顶标题栏带着两个主要筛选器——**时间段**和**来源**——而且两者都会被存进页面 URL。这意味着你可以把一个筛选后的视图收藏或分享出去（"最近 30 天，仅任务"），下次打开时它会原样还原。原始表格的筛选器是独立的，只对那一个区块生效。
+
+关于准确性的一点说明：失败和已中止的运行会被排除在*成本平均值*之外（否则它们会拉偏每次运行的数字），但它们仍会计入你的总运行次数和失败率。这样平均值保持干净，而可靠性的全貌也保持完整。
+
+## 单工单成本
+
+你不必非得来到分析页面才能看到一个 spec 花了多少钱。打开任意工单，如果它附带了任何支出，你就会在标题正下方看到一行小结：
+
+> $0.42 · 6 turns · 1m 12s active · breakdown
+
+点一下它，你就会落到已经针对该工单筛选好的分析页面。从"这个功能花了我多少钱？"到完整明细，这是最快的路径。
+
+## 导出你的数据
+
+当你需要把这些数字拿到应用之外——做表格、写财务报告、或自己分析——就用 **Export** 下拉菜单。它提供四种格式：
+
+- **摘要 CSV**——一个多区段文件，包含总计、每日时间线、按来源、按模型，以及热门工单。
+- **摘要 JSON**——同样的摘要，结构化呈现。
+- **原始 CSV**——每一行调用记录（最多 10,000 条；如果不得不截断会有注明）。
+- **原始 JSON**——同样的原始记录，结构化呈现。
+
+导出会遵循你当前应用的时间段和来源筛选，文件命名也方便合理排序：`<project>-analytics-<period>-<date>.csv`。当没有任何东西可导出时按钮会被禁用，而如果下载失败，你会收到一条清晰的错误提示。
+
+## 保持实时
+
+你不用刷新。当项目中任何地方记录了一次新调用，正打开着的仪表盘会在稍后悄悄自我重新拉取一次，这样燃烧表就能跟上正在收尾的工作。

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

@@ -0,0 +1,46 @@
+# 内置终端
+
+Specrails 内置了一个真正的终端——就是那个从窗口底部滑出来的面板，跟 VS Code 或 Cursor 里的那个一模一样。它运行的是你真实的 shell，在你真实的项目目录里，所以你可以直接跑 `git`、`npm`、测试，或者任何其他东西，而不用离开应用。
+
+## 打开和关闭它
+
+最快的方式是键盘：**Cmd+J**（macOS）或 **Ctrl+J**（Windows/Linux）可以切换面板的开关，并且面板一出现就会把焦点落在终端上，你可以立刻开始输入。你也可以用状态栏里的那个箭头按钮。
+
+这个面板有三种状态：
+
+- **隐藏**——收起不见。
+- **还原**——正常的分屏高度面板。
+- **最大化**——当你需要更多空间来阅读输出时，让它占满工作区。
+
+最小化面板（点那个箭头）**不会**停止任何东西——你的 shell 会继续在后台运行。唯一真正结束一个会话的操作是关闭它（垃圾桶图标，或者每个标签上的 ✕）。
+
+## 多个会话
+
+你可以在同一个项目里同时跑多个终端——最多十个。每个都有自己的标签页；你可以给它们重命名，这样"dev server"和"tests"就不会搞混了。它们都会从你的项目文件夹启动，并加载你的 shell 配置（`.zshrc`、`.bashrc` 等等），所以你的别名和 PATH 完全是你预期的样子。
+
+这里有个重点：你的终端**能在切换项目和标签时存活下来**。Specrails 会在幕后让每个会话保持鲜活、完好——回滚内容、运行中的进程，全都在——所以你切到分析页面再切回来，并不会重置你的 shell，也不会打断一条长时间运行的命令。会话只会在你明确关闭它（或者移除整个项目）时才结束。
+
+## 按项目记忆
+
+面板是否打开、你把它拖到了多高、有哪些标签页——这一切都是**按项目**记住的。回到一个项目，它还是你离开时布置好的样子。
+
+## 那些高级特性
+
+这可不是个简陋的控制台。这个终端自带了一个一流终端该有的那些贴心功能：
+
+- **快速、清晰的渲染**，由 WebGL 驱动（带自动降级，所以它永远不会崩坏）、完整的 Unicode 宽度处理，以及字体连字。
+- **搜索你的回滚内容**，用 **Cmd+F**——要找那条埋在 500 行之上的错误时特别好用。
+- **字体缩放**，用 **Cmd+=**、**Cmd+-**，以及 **Cmd+0** 重置。
+- **剪贴板快捷键**——Cmd+C / Cmd+V 复制粘贴，Cmd+K 清屏——外加一个右键上下文菜单。
+- **拖放文件路径**（在桌面应用中）：把一个文件拖到终端上，它的路径就会被插入进去，并按你的 shell 正确加引号。
+- **平滑缩放**——拖动面板高度或折叠侧边栏，都不会让输出抖动。
+- **内联图片**——发出 Sixel 或 iTerm2 风格图片的终端会就地把它们渲染出来。
+- **Shell 集成**——Specrails 知道每条命令在哪里开始、哪里结束，所以它能追踪你的命令历史，并在一条长时间运行的命令完成时通知你（一条桌面通知，并带浏览器降级方案）。如果由于某种原因你的 shell 无法被注入，它会安静地降级，并提醒你一次。
+
+## 设置
+
+终端偏好设置分两层：一个应用级的默认值，和一个可选的按项目覆盖值。存在时按项目的设置会胜出，所以你可以保持一套全局的外观风格，同时又能为某个需要不同配置的项目做个性化调整。
+
+## 关掉它
+
+终端默认是开着的。如果你不想要它，可以通过 `VITE_FEATURE_TERMINAL_PANEL`（客户端）或 `SPECRAILS_TERMINAL_PANEL`（服务端）标志来禁用它——把其中任意一个设为 `false` 即可。不过大多数人都会直接让它开着。

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

@@ -0,0 +1,50 @@
+# Code 浏览器
+
+**Code** 板块给你一扇友好的、只读的窗口去看你的代码仓库——特别为那些想弄明白 AI 一直在搭些什么、又不想成天泡在编辑器里的人设计。左边是文件树，右边是代码查看器，而在代码上方，还有一段用大白话写成的摘要，告诉你每个文件到底在做什么。
+
+在这个版本里它是严格只读的：你在这里做的任何操作都不会改动你的文件。把它当成一间阅览室，而不是一间工作坊。
+
+从右侧边栏打开它（**Code**），和其他一切一样，它只针对你当前的项目。
+
+## 文件树
+
+左侧窗格是你项目文件的一棵虚拟化树——即使在很大的仓库里也很快。它会遵循你的 `.gitignore` 和一份内置的拒绝列表，所以你看到的是真正重要的文件，而不是一片由构建产物和 `node_modules` 组成的汪洋。
+
+在文件旁边你会注意到**来源标记（provenance chips）**——一些小标记，告诉你某个文件曾被 *AI 改动过*。这正是 Code 浏览器的核心：Specrails 会记录每个流水线任务创建或修改了哪些文件，并把它们关联回触发这项工作的那个工单。这样你一眼就能回答："这是 AI 写的，还是我写的？"
+
+在树的顶部有一个筛选器：
+
+- **Tocado por IA / AI 改动过**（默认）——只显示 AI 改动过的文件。
+- **全部文件**——完整的树。
+
+你的选择会按项目记住，所以如果你主要关心 AI 写的改动，每次都会先看到它们。
+
+## 代码查看器
+
+点击一个文件，它就会在一个功能完整的查看器里打开（由 Monaco 驱动，跟 VS Code 用的是同一个引擎），并带有与你所选应用主题相匹配的语法高亮。有几条合理的限制让一切保持流畅：二进制文件会被礼貌地拒绝，而非常大的文件（超过 2 MB）不会被加载。
+
+你当前的文件会被存进页面 URL，所以你可以收藏或分享一个直达某个特定文件的链接。
+
+由于这个版本不包含编辑功能，查看器提供了一个 **在外部编辑器中编辑** 按钮，它会复制文件的绝对路径——把它粘进你顺手的编辑器，从那里接着干就行。
+
+## AI 摘要
+
+在代码上方你会看到一段该文件的**大白话摘要**——它是干什么用的、它在做什么——写得让非开发者也能跟得上。这些摘要是为你生成并缓存的，所以打开一个你之前看过的文件会瞬间呈现。
+
+摘要在保持新鲜这件事上很聪明：它们是和文件内容绑定的，所以当一个文件真正发生变化时摘要会被重新生成，而没变的文件则不会被白白重新摘要一遍。如果是你自己改了一个文件，它的摘要会被标记为已过期，而不是悄悄重新生成——什么时候刷新由你掌控。当你想按需获取一份全新解读时，有一个**重新生成**操作。
+
+有几道护栏让成本保持理智：摘要生成会在一个**月度预算**内运行（默认几美元，可在设置中配置），并且对单个任务能触发多少份摘要也设了上限。如果某份摘要被跳过了，应用会告诉你原因——是预算到顶了、单任务上限到了，还是文件根本没找到。
+
+你还可以在全局设置的 *Code section* 区域里选择**摘要语言**（英语或西班牙语）。
+
+## 把代码连回 spec
+
+来源关联是双向的。在 Code 浏览器里，点击文件上的工单标记会打开那个工单的详情。而反过来，**工单详情**视图里有一个 *此工单改动的文件* 区段——在那里点击一个文件，你就会直接跳进 Code 浏览器并打开它。它把"这是我们写的 spec"和"这是从中产出的代码"这个闭环给接上了。
+
+## 它（暂时）做不到的事
+
+把预期说清楚：这第一个版本有意留下了几样东西：应用内编辑、按符号或按目录级别的摘要、叙事式的 diff 视图，以及对话式的"问 AI 关于这个文件"。来源信息只把文件归属到它的主要工单。这些都是随着时间可能逐步成长起来的东西。
+
+## 关掉它
+
+Code 浏览器默认是开着的。可以通过 `VITE_FEATURE_CODE_EXPLORER`（客户端）或 `SPECRAILS_CODE_EXPLORER`（服务端）标志来禁用它——把其中任意一个设为 `false` 即可。关掉它之后，你所有记录的数据和摘要都会安然无恙地留在磁盘上，纹丝不动，以备你哪天再把它打开。

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

@@ -0,0 +1,64 @@
+# AI 提供方（Claude、Codex、Gemini）
+
+Specrails 并不绑定在某一个 AI 上。应用里所有会调用 AI 的环节——Explore Spec、Quick spec、rail、聊天、AI Edit，以及终端里的「Open AI CLI」按钮——都可以走三家一流提供方中的任意一家。你来决定每个项目用哪些，甚至可以按任务逐个切换。
+
+## 三家提供方
+
+| 提供方 | CLI | 出品方 | 说明 |
+|---|---|---|---|
+| **Claude** | `claude` | Anthropic | 功能最完整。Agents（profile）、Ultracode rail 以及 Contract Refine 都只有它支持。 |
+| **Codex** | `codex` | OpenAI | 需要 codex `0.128.0+`。从你的全局 `~/.codex/config.toml` 读取 MCP 服务器。 |
+| **Gemini** | `gemini` | Google | 需要 gemini `0.11.0+`。使用原生遥测，以及 `GEMINI.md` 指令文件。 |
+
+三家都是**默认启用**的。只要某家提供方的 CLI 已安装并在你的 `PATH` 上，它就会出现在 **Add Project** 里。所以第一步永远是一样的：按那个工具自己的文档把你想用的 CLI 装好并登录。一旦 `claude --version`（或 `codex`、`gemini`）能在你的终端里正常运行，Specrails 就能用它了。
+
+## 为一个项目安装单个提供方
+
+添加项目时，setup 向导会问你想安装哪个（哪些）提供方。选一个，点完安装步骤，就搞定了。从那以后，这个项目就直接*拥有*了这个提供方——你再也不用去操心它。规格、rail、聊天和分析，无论你选了哪一个，用起来都一样。
+
+如果你想要的某个 CLI 没有出现在 Add Project 里，原因几乎总是它没安装、或不在你的 `PATH` 上。装好它，再重新打开 Add Project 即可。
+
+## 为同一个项目安装多个提供方
+
+你可以把**不止一个**提供方装进同一个项目——比如同时用 Claude *和* Gemini。在 **Add Project** 里，提供方列表会变成一组复选框；想要哪些就勾哪些。你勾选的第一个会成为这个项目的**主**（默认）提供方，其余的则作为备选可用。
+
+关于多提供方项目，有几点值得了解：
+
+- **只有一个提供方时，行为和以前完全一样。** 如果一个项目只有单个提供方，你在任何地方都不会看到提供方选择器——应用保持干净、简单。
+- **右侧边栏只显示所有已安装提供方都支持的板块。** 因为 Agents（profile）是 Claude 独有的概念，所以一旦项目里包含任何非 Claude 的提供方，**Agents** 板块就会消失。其余的（Specs、Code、Analytics、Integrations、Terminal、Chat）都会保留。
+- **提供方在创建后就锁定了。** 在这个版本里，你在添加项目时选定提供方，之后无法再从 Settings 更改。如果你需要不同的组合，那就新建一个项目。
+
+## 按调用逐个选择提供方
+
+多提供方项目真正的价值，在于为每个任务挑到合适的 AI——而无需改动任何全局设置。凡是会运行 AI 的地方，都会出现一个小小的提供方选择器（仅当项目拥有不止一个提供方时）：
+
+- **Add Spec**——有一个引擎选择器，让你用喜欢的提供方来 Explore 或 Quick 生成规格。
+- **rail 头部**——在启动某条具体的 rail 之前，为它挑选引擎。
+- **终端**——「Open AI CLI」（Sparkles）按钮会打开一个提供方菜单，让你在该项目目录下进入任意已安装的 CLI。
+
+你的选择会按项目被记住，默认是主提供方，所以你不用每次都重新选。
+
+## 只有 Claude 才能做的事
+
+有少数功能天生就是 Claude 专属的，因此当其他提供方参与时，它们要么被隐藏、要么被跳过：
+
+- **Agents（profile）**——按项目的 agent 目录与模型路由。在任何包含非 Claude 提供方的项目上都会隐藏。
+- **Ultracode rail**——始终在 Claude 上运行。
+- **Contract Refine**——对已提交规格追加的「Contract Layer」环节，只有当对话的提供方是 Claude 时才会运行。
+- **Add Spec 高级模式**（SMASH / Contract Layer）——对非 Claude 引擎隐藏。
+
+其余的一切——Explore、Quick spec、完整的 rail 流水线、AI Edit、聊天、成本分析——三家全都能用。
+
+## 跨提供方的成本追踪
+
+**Analytics** 页面会追踪每一次产生费用的调用，无论用的是哪家提供方。在多提供方项目上，它还会加上引擎筛选标签，方便你按提供方对比开销。Claude 会报告自己的精确成本；而对 Codex 和 Gemini，Specrails 会用内置的费率表来估算成本，所以那些数字是接近的近似值，而非实际账单金额。
+
+## 疑难排查
+
+- **我装了某个提供方，却没出现在选项里。** 确认该 CLI 在你的 `PATH` 上（在一个全新终端里试试 `claude --version` / `codex --version` / `gemini --version`）。应用是通过你系统的 `PATH` 来探测提供方 CLI 的。
+- **聊天里没加载 Codex 的 MCP 服务器。** Codex 从你的全局 `~/.codex/config.toml` 读取 MCP 服务器——用 `codex mcp add` 在那里注册它们。
+- **紧急停用。** 可以通过环境变量在应用范围内关闭某个提供方（`SPECRAILS_CODEX_BETA=0` 或 `SPECRAILS_GEMINI_BETA=0`）。这只会把提供方从*选择列表*中隐藏；很少会用到。
+
+## 另见
+
+各提供方的专属指南会对每个 CLI 讲得更深入：Codex 指南和 Gemini 指南都涵盖了安装设置、能做什么，以及各自特有的小脾气。