Merge pull request #151 from flashcatcloud/doc-review/2026-07-09-031723

ysyneu · web-flow · commit 48cb3bc2b3b3 · 2026-07-09T01:01:42.000-07:00
docs: sync doc-review updates
diff --git a/en/ai-sre/sessions.mdx b/en/ai-sre/sessions.mdx
@@ -48,6 +48,17 @@ Dimensions available in the filter panel:
 
 The panel footer provides **Reset** (restore default filters) and **Done** (close the panel).
 
+### Session Visibility and Permissions
+
+The account is the hard access boundary for sessions: sessions are never accessible across accounts. Within the same account, personal sessions and team sessions use different rules for reading, continuing, and managing the conversation:
+
+| Session type | Can read / continue the conversation | Can rename, archive, delete, or attach an incident |
+|---|---|---|
+| Personal session (no team bound) | Only the creator | Only the creator |
+| Team session (team bound) | Members in the same account who have the session ID | Session creator, account owner / admin, or members of the bound team |
+
+Pinning is a personal preference and does not modify the session itself; if you can read a session, you can pin or unpin it for yourself. Account owners and admins can manage team sessions, but they cannot read or manage another member's personal session.
+
 ### Per-Session Actions
 
 Hover over a session row to reveal the pin and archive actions. A pinned session displays a persistent pin icon to the left of its name.
@@ -285,7 +296,7 @@ The response `Content-Type` is `application/x-ndjson`. The **first line is alway
 If an error occurs after streaming has already begun, the server cannot switch to a standard JSON error envelope. Instead, a JSON-encoded error object is appended as the final line of the stream. Consumers must inspect this last line to determine whether the stream completed successfully.
 </Warning>
 
-**Permissions**: the export endpoint uses the same access gate as sending messages (`CanChatSession`), meaning the caller must have message-send permission on the session — read-only access is not sufficient.
+**Permissions**: the export endpoint uses the same access gate as sending messages (`CanChatSession`), meaning the caller must have message-send permission on the session — read-only access is not sufficient. Personal sessions can be exported only by their creator; team sessions can be exported by same-account members who can access the session.
 
 ## Related Pages
 
diff --git a/en/developer/mcp-server.mdx b/en/developer/mcp-server.mdx
@@ -8,7 +8,7 @@ keywords: ["MCP", "Model Context Protocol", "AI", "Claude", "Cursor", "Flashduty
 Flashduty MCP Server is a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) server that connects the Flashduty API seamlessly into MCP-capable AI tools (such as Cursor and Claude Desktop). With it, you can let an LLM query, acknowledge, and close incidents, retrieve channels and members, and validate notification templates directly — embedding incident management and automation into your AI workflow.
 
 <Info>
-  Flashduty MCP Server is built on the [go-flashduty SDK](/en/developer/go-sdk); every tool is a thin wrapper over the Flashduty Open API.
+  Flashduty MCP Server provides a curated, task-oriented toolset; it does not mirror the full Flashduty Open API. For 1:1 coverage of every Open API operation, use the [Flashduty CLI](/en/developer/cli); agents with shell access can call the CLI directly.
 </Info>
 
 ## Use cases
@@ -224,6 +224,21 @@ The server provides **8 toolsets and 23 tools** in total, all enabled by default
   Toolset names (`incidents`, `status_page`, etc.) are internal program identifiers; keep them in English when configuring.
 </Note>
 
+### Pagination Parameters
+
+List-style query tools use one shared pagination contract: `limit` is the number of items per page, default `20`, max `100`; `page` is a 1-based page number, default `1`. When more results remain, the response includes `truncated: true` and a `hint` that names the next page to request, such as `page:2`.
+
+The following tools support `limit` / `page`:
+
+| Tool | Pagination behavior |
+|---|---|
+| `query_incidents` | Normal list queries use `limit` / `page`; direct lookup with `incident_ids` ignores other filters and does not page |
+| `query_incident_alerts` | `page` applies to every requested incident's alert list; when one incident still has more alerts, that incident entry carries `truncated` and `hint` |
+| `query_channels` | Name search and `channel_ids` filtering use the same paginated list endpoint, so both support `limit` / `page` |
+| `query_members` | Name or email search supports pagination; direct lookup with `person_ids` returns the requested members and does not page |
+| `query_teams` | Name search supports pagination; direct lookup with `team_ids` returns the requested teams and does not page |
+| `query_changes` | Normal filtered queries support pagination; with `change_ids`, the tool filters the current page client-side, reports the matched count, and does not add a pagination hint |
+
 The tools in each toolset are as follows:
 
 <AccordionGroup>
@@ -251,7 +266,8 @@ The tools in each toolset are as follows:
     | `severity` | string | Filter by severity: `Info`, `Warning`, `Critical`. |
     | `channel_ids` | string | Comma-separated channel IDs. |
     | `query` | string | Free-text search across title, labels, and content. |
-    | `limit` | number | Number of results to return. Default 20, max 100. |
+    | `limit` | number | Number of results per page. Default 20, max 100. |
+    | `page` | number | 1-based page number; when the response includes `truncated: true`, follow the `hint` to request the next page. |
 
     **`since` / `until` time-window behavior**
 
@@ -320,6 +336,9 @@ The tools in each toolset are as follows:
   <Card title="go-flashduty SDK" icon="code" href="/en/developer/go-sdk">
     The Go SDK that MCP Server depends on, covering the entire Flashduty Open API.
   </Card>
+  <Card title="Flashduty CLI" icon="terminal" href="/en/developer/cli">
+    Command-line tool covering the Flashduty Open API, useful when an agent needs complete API coverage.
+  </Card>
   <Card title="GitHub repository" icon="rocket" href="https://github.com/flashcatcloud/flashduty-mcp-server">
     Browse the source, releases, and issue tracker.
   </Card>
diff --git a/zh/ai-sre/sessions.mdx b/zh/ai-sre/sessions.mdx
@@ -48,6 +48,17 @@ sidebarTitle: 控制台
 
 面板底部提供 **重置**（恢复默认筛选）与 **完成**（关闭面板）。
 
+### 会话可见性与操作权限
+
+会话以账户为硬边界，跨账户永远不可访问。在同一账户内，个人会话和团队会话的读取、继续对话与管理权限不同：
+
+| 会话类型 | 可读取 / 继续对话 | 可重命名、归档、删除或关联故障 |
+|---|---|---|
+| 个人会话（未绑定团队） | 仅创建者本人 | 仅创建者本人 |
+| 团队会话（绑定团队） | 同账户内拿到会话 ID 的成员 | 会话创建者、账户 Owner / 管理员、或该团队成员 |
+
+置顶是个人偏好，不会修改会话本身；只要您有权读取这条会话，就可以为自己置顶或取消置顶。账户 Owner / 管理员可以管理团队会话，但不能读取或管理其他成员的个人会话。
+
 ### 单条会话操作
 
 将鼠标悬停在会话行上，会显示置顶与归档操作；置顶的会话在名称左侧常驻一个图钉标记。
@@ -285,7 +296,7 @@ Fork 会话会清理只属于运行中的临时状态，例如当前回合缓存
 若流式传输已开始后发生错误，服务器**无法**切换回标准 JSON 错误包。此时会在流末尾追加一行 JSON 编码的错误对象，消费方需检测该行以判断流是否完整。
 </Warning>
 
-**权限**：导出端点使用与发送消息相同的权限门控（`CanChatSession`），即要求调用方具备该会话的消息收发权限，单纯的只读访问权限不够。
+**权限**：导出端点使用与发送消息相同的权限门控（`CanChatSession`），即要求调用方具备该会话的消息收发权限，单纯的只读访问权限不够。个人会话只能由创建者导出；团队会话可由同账户内具备会话访问能力的成员导出。
 
 ## 相关页面
 
diff --git a/zh/developer/mcp-server.mdx b/zh/developer/mcp-server.mdx
@@ -8,7 +8,7 @@ keywords: ["MCP", "Model Context Protocol", "AI", "Claude", "Cursor", "Flashduty
 Flashduty MCP Server 是一个 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) 服务端，将 Flashduty API 无缝接入支持 MCP 的 AI 工具（如 Cursor、Claude Desktop）。借助它，您可以让大模型直接查询故障、确认与关闭故障、检索协作空间与成员、校验通知模板，把故障管理与自动化能力嵌入 AI 工作流。
 
 <Info>
-  Flashduty MCP Server 底层基于 [go-flashduty SDK](/zh/developer/go-sdk) 实现，所有工具均是对 Flashduty 开放 API 的薄封装。
+  Flashduty MCP Server 提供的是经过整理的任务型工具集，并不完整镜像 Flashduty 开放 API。需要 1:1 覆盖全部开放 API 时，请使用 [Flashduty CLI](/zh/developer/cli)；具备 shell 权限的 Agent 也可以直接调用 CLI。
 </Info>
 
 ## 适用场景
@@ -224,6 +224,21 @@ docker run -i --rm \
   工具集名称（`incidents`、`status_page` 等）为程序内部标识，配置时请保持英文原样。
 </Note>
 
+### 分页参数
+
+列表型查询工具使用统一分页规则：`limit` 表示每页数量，默认 `20`，最大 `100`；`page` 表示从 `1` 开始的页码，默认 `1`。当返回结果还没有取完时，响应会包含 `truncated: true` 和 `hint`，其中会明确提示下一次请求应传入的页码，例如 `page:2`。
+
+支持 `limit` / `page` 的工具包括：
+
+| 工具 | 分页行为 |
+|---|---|
+| `query_incidents` | 普通列表查询按 `limit` / `page` 翻页；使用 `incident_ids` 直接查找时忽略其他过滤条件，不走分页 |
+| `query_incident_alerts` | `page` 会应用到每个指定故障的告警列表；某个故障仍有更多告警时，该故障结果内会带 `truncated` 与 `hint` |
+| `query_channels` | 名称搜索和 `channel_ids` 过滤都走同一个分页列表接口，因此都支持 `limit` / `page` |
+| `query_members` | 按名称或邮箱搜索时支持分页；使用 `person_ids` 直接查找时返回指定成员，不走分页 |
+| `query_teams` | 按名称搜索时支持分页；使用 `team_ids` 直接查找时返回指定团队，不走分页 |
+| `query_changes` | 普通过滤查询支持分页；使用 `change_ids` 时会在当前页内做客户端过滤，并返回匹配数量，不追加分页提示 |
+
 各工具集包含的工具如下：
 
 <AccordionGroup>
@@ -251,7 +266,8 @@ docker run -i --rm \
     | `severity` | string | 按严重程度过滤，可选：`Info`、`Warning`、`Critical`。 |
     | `channel_ids` | string | 逗号分隔的协作空间 ID。 |
     | `query` | string | 自由文本搜索（标题、标签、内容）。 |
-    | `limit` | number | 返回条数，默认 20，最大 100。 |
+    | `limit` | number | 每页返回数量，默认 20，最大 100。 |
+    | `page` | number | 页码，从 1 开始；当响应包含 `truncated: true` 时，按 `hint` 提示请求下一页。 |
 
     **`since` / `until` 时间窗口行为**
 
@@ -320,6 +336,9 @@ docker run -i --rm \
   <Card title="go-flashduty SDK" icon="code" href="/zh/developer/go-sdk">
     MCP Server 底层依赖的 Go SDK，覆盖 Flashduty 全部开放 API。
   </Card>
+  <Card title="Flashduty CLI" icon="terminal" href="/zh/developer/cli">
+    覆盖 Flashduty 开放 API 的命令行工具，适合需要完整 API 能力的 Agent。
+  </Card>
   <Card title="GitHub 仓库" icon="rocket" href="https://github.com/flashcatcloud/flashduty-mcp-server">
     查看源码、Release 与问题反馈。
   </Card>
