From 5588ff82b2b1f8173e865056bf189891d29a9e7e Mon Sep 17 00:00:00 2001 From: ysyneu Date: Mon, 5 Oct 2026 18:11:11 -0700 Subject: [PATCH 1/2] =?UTF-8?q?docs(ai-sre):=20use=20=E7=9F=A5=E8=AF=86=20?= =?UTF-8?q?as=20the=20Chinese=20name=20of=20Knowledge?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Rename the zh-facing name of the AI SRE Knowledge feature from 知识库 to 知识 across page bodies, frontmatter and the translation glossary, so it matches the console menu and the English name. Generic uses of 知识库 (third-party wikis, the docs-search changelog entry) are unchanged. --- .claude/skills/translate-zh-to-en/glossary.md | 2 +- zh/ai-sre.mdx | 2 +- zh/ai-sre/agents.mdx | 4 +- zh/ai-sre/automations.mdx | 2 +- zh/ai-sre/context.mdx | 12 ++--- zh/ai-sre/im.mdx | 6 +-- zh/ai-sre/init.mdx | 34 ++++++------ zh/ai-sre/insight.mdx | 14 ++--- zh/ai-sre/knowledge.mdx | 54 +++++++++---------- zh/ai-sre/mcp.mdx | 2 +- zh/ai-sre/memory.mdx | 6 +-- zh/ai-sre/overview.mdx | 6 +-- zh/ai-sre/quickstart.mdx | 8 +-- zh/ai-sre/sessions.mdx | 10 ++-- zh/ai-sre/skills.mdx | 4 +- zh/developer/cli.mdx | 22 ++++---- zh/developer/go-sdk.mdx | 4 +- zh/home.mdx | 2 +- zh/on-call/comparison/vs-pagerduty.mdx | 2 +- 19 files changed, 98 insertions(+), 98 deletions(-) diff --git a/.claude/skills/translate-zh-to-en/glossary.md b/.claude/skills/translate-zh-to-en/glossary.md index f7cae3ec6..7a5202114 100644 --- a/.claude/skills/translate-zh-to-en/glossary.md +++ b/.claude/skills/translate-zh-to-en/glossary.md @@ -199,7 +199,7 @@ Translatable companions (do NOT belong in DNT — translate to Chinese): | English | Chinese | |---------|---------| | Artifact / Artifacts | 产物 | -| Knowledge | 知识库 — the DUTY.md-rooted file tree an account or team maintains for AI SRE. Formerly "Knowledge Pack"; do not use that name in copy. Running text uses lowercase "knowledge" (e.g., "team knowledge"); API identifiers such as `pack_id` and `knowledge-pack-*` CLI commands stay unchanged | +| Knowledge | 知识 — the DUTY.md-rooted file tree an account or team maintains for AI SRE. Formerly "Knowledge Pack"; do not use that name in copy. Running text uses lowercase "knowledge" (e.g., "team knowledge"); API identifiers such as `pack_id` and `knowledge-pack-*` CLI commands stay unchanged | | Memory | 记忆 | | Context | 上下文 — the Customize group holding Knowledge and Memory | | Customize | 自定义 — the AI SRE sidebar entry that opens Context, Plugins, and Environments | diff --git a/zh/ai-sre.mdx b/zh/ai-sre.mdx index 0cef25ee0..43e90cf72 100644 --- a/zh/ai-sre.mdx +++ b/zh/ai-sre.mdx @@ -25,7 +25,7 @@ Flashduty AI SRE 是一个对话式的自治 SRE Agent 平台。你用自然语 从故障或作战室一键拉起会话，Agent 携带上下文进入排查，沉淀的知识反哺下一次响应 - 以 DUTY.md 为入口的知识库承载服务清单、runbook、值班路径等长期上下文 + 以 DUTY.md 为入口的知识承载服务清单、runbook、值班路径等长期上下文 通过 Skill、MCP、A2A Agent 扩展能力；自托管 Runner 让排障进入你的内网 diff --git a/zh/ai-sre/agents.mdx b/zh/ai-sre/agents.mdx index 7b833fb56..f1272b4c2 100644 --- a/zh/ai-sre/agents.mdx +++ b/zh/ai-sre/agents.mdx @@ -303,7 +303,7 @@ A2A Agent 的完整生命周期可在 **自定义 → 插件 → Agents** 页面 --- -A2A Agent 与其他资源（Skill、知识库、MCP、运行环境）共用同一套**两级作用域**模型，分为账户级与团队级。控制台界面中，账户级这一档显示为「**共享**」/「**共享范围**」，与账户级同义（整个账户内可见）： +A2A Agent 与其他资源（Skill、知识、MCP、运行环境）共用同一套**两级作用域**模型，分为账户级与团队级。控制台界面中，账户级这一档显示为「**共享**」/「**共享范围**」，与账户级同义（整个账户内可见）： | 作用域 | 可见性 | | --- | --- | @@ -328,7 +328,7 @@ A2A Agent 与其他资源（Skill、知识库、MCP、运行环境）共用同 为 Agent 接入外部工具，扩展其在任务中的能力边界。 - 用 DUTY.md 与知识库为 Agent 提供团队上下文与排障经验。 + 用 DUTY.md 与知识为 Agent 提供团队上下文与排障经验。 在 IM 群里 @ AI SRE，并了解故障作战室的自动诊断。 diff --git a/zh/ai-sre/automations.mdx b/zh/ai-sre/automations.mdx index b2b5937ac..1488d0935 100644 --- a/zh/ai-sre/automations.mdx +++ b/zh/ai-sre/automations.mdx @@ -235,7 +235,7 @@ API 返回的运行记录还包含 `trigger_kind`，可能取值为 `schedule` ### 作用域与权限 -自动化规则与 AI SRE 下的其它资源（Skill、知识库、MCP、Agent、运行环境）共用同一套两级作用域： +自动化规则与 AI SRE 下的其它资源（Skill、知识、MCP、Agent、运行环境）共用同一套两级作用域： | 维度 | 规则 | |---|---| diff --git a/zh/ai-sre/context.mdx b/zh/ai-sre/context.mdx index 7447d16ef..e8d0fffb4 100644 --- a/zh/ai-sre/context.mdx +++ b/zh/ai-sre/context.mdx @@ -1,7 +1,7 @@ --- title: 了解上下文 -description: 上下文是 AI SRE 排障时带着的两类长期资料。知识库由人维护，记忆由系统整理。控制台在 自定义 → 上下文 分组下为它们各设一页。 -keywords: ["AI SRE", "上下文", "知识库", "记忆", "DUTY.md"] +description: 上下文是 AI SRE 排障时带着的两类长期资料。知识由人维护，记忆由系统整理。控制台在 自定义 → 上下文 分组下为它们各设一页。 +keywords: ["AI SRE", "上下文", "知识", "记忆", "DUTY.md"] sidebarTitle: 了解上下文 --- @@ -15,7 +15,7 @@ sidebarTitle: 了解上下文 上下文是 AI SRE 在一次排障里能反复用到的长期资料。它分成两种，在控制台 **AI SRE → 自定义** 侧栏的 **上下文** 分组下各有一页。 -- **[知识库](/zh/ai-sre/knowledge)**是人维护的。它写的是这个环境怎么运转：一份使用说明 `DUTY.md`，加上运行手册、服务清单等文件。会话开始时会读使用说明，其它文件在需要时再打开。入口：**AI SRE → 自定义 → 上下文 → 知识库**。 +- **[知识](/zh/ai-sre/knowledge)**是人维护的。它写的是这个环境怎么运转：一份使用说明 `DUTY.md`，加上运行手册、服务清单等文件。会话开始时会读使用说明，其它文件在需要时再打开。入口：**AI SRE → 自定义 → 上下文 → 知识**。 - **[记忆](/zh/ai-sre/memory)**是系统整理的。会话结束后，系统从对话里留下以后还会用到的偏好、做法、事实和教训。你也可以在对话里直接说记住或忘掉一件事。入口：**AI SRE → 自定义 → 上下文 → 记忆**。 两页底部都有一个输入框：写下要改什么，控制台会打开新对话，由 AI 先说明改动、经你同意后保存。 @@ -26,20 +26,20 @@ sidebarTitle: 了解上下文 两类资料都按范围组织，但支持的范围不同。 -| 范围 | 记忆 | 知识库 | +| 范围 | 记忆 | 知识 | | --- | --- | --- | | 个人 | 你自己的 | 没有 | | 团队 | 这个团队的 | 这个团队的那一份（每个团队最多 1 个） | | 共享 | 没有 | 整个账户的那一份 | -个人范围没有知识库。共享范围没有记忆。 +个人范围没有知识。共享范围没有记忆。 ## 接着看 --- - + 使用说明、运行手册和文件怎么组织，以及助手在会话里怎么读它们。 diff --git a/zh/ai-sre/im.mdx b/zh/ai-sre/im.mdx index 752362533..36d357eb7 100644 --- a/zh/ai-sre/im.mdx +++ b/zh/ai-sre/im.mdx @@ -143,7 +143,7 @@ IM 会话没有控制台那样的选择器 UI，但支持两条斜杠命令在** ### /env — 切换运行环境 -在群聊或私聊里向机器人发送 `/env <目标>`，可将当前 IM 会话重新绑定到另一个运行环境，对话历史与上下文完整保留。切换后，旧环境的工作目录不再可用：本次对话中在旧环境里创建或修改的文件已丢失，技能与知识库文件会在新环境中按需重新挂载。 +在群聊或私聊里向机器人发送 `/env <目标>`，可将当前 IM 会话重新绑定到另一个运行环境，对话历史与上下文完整保留。切换后，旧环境的工作目录不再可用：本次对话中在旧环境里创建或修改的文件已丢失，技能与知识文件会在新环境中按需重新挂载。 `<目标>` 有三种写法： @@ -170,11 +170,11 @@ IM 会话没有控制台那样的选择器 UI，但支持两条斜杠命令在** 切换后，AI SRE 会： 1. 将记忆快照刷新为新团队作用域下的记忆（旧团队的记忆不再适用于本次会话）。 -2. 把新团队的知识库排入挂载队列，在下一条消息处理时自动注入上下文。 +2. 把新团队的知识排入挂载队列，在下一条消息处理时自动注入上下文。 3. 检查本次会话钉定的运行环境是否仍然可用：如果钉定的是**另一个团队独有**的 BYOC Runner 或云端沙箱模板，会把运行环境改回「自动选择」，并回复「「x」不属于当前团队，运行环境已改回自动选择。」共享环境与账户级环境不受影响；无法确认归属时（例如模板列表拉取失败）保持原有钉定不变。 -已挂载到本次会话的知识库不会被移除——挂载是对话级别的，切回之前挂载过的团队不会重复注入提醒。 +已挂载到本次会话的知识不会被移除——挂载是对话级别的，切回之前挂载过的团队不会重复注入提醒。 ## /feedback — 评价 AI SRE 的回复 diff --git a/zh/ai-sre/init.mdx b/zh/ai-sre/init.mdx index bda25aaaa..7e8d8daf1 100644 --- a/zh/ai-sre/init.mdx +++ b/zh/ai-sre/init.mdx @@ -1,7 +1,7 @@ --- title: 初始化（/init） -description: 在 AI SRE 会话中输入 /init，由 Agent 以访谈的方式带你从零搭建运维知识库（DUTY.md + runbook + 服务清单等）并按需接入 MCP——每一项写入都需你逐条确认。 -keywords: ["AI SRE", "init", "运营作战图", "知识库", "onboarding", "DUTY.md", "runbook", "MCP"] +description: 在 AI SRE 会话中输入 /init，由 Agent 以访谈的方式带你从零搭建运维知识（DUTY.md + runbook + 服务清单等）并按需接入 MCP——每一项写入都需你逐条确认。 +keywords: ["AI SRE", "init", "运营作战图", "知识", "onboarding", "DUTY.md", "runbook", "MCP"] sidebarTitle: 初始化 --- @@ -13,9 +13,9 @@ sidebarTitle: 初始化 --- -在任意 AI SRE 会话的输入框中输入 `/init`，Agent 会切换成一名**运维 onboarding 访谈者**，带你从零搭建一份运维知识库——也就是这个团队的「运营作战图」。它会扫描你的 Flashduty 故障与通知渠道、向你提问、把你口述的服务拓扑、排查手册、集群访问方式等沉淀成知识文件，并在需要时帮你接入外部工具（MCP）。 +在任意 AI SRE 会话的输入框中输入 `/init`，Agent 会切换成一名**运维 onboarding 访谈者**，带你从零搭建一份运维知识——也就是这个团队的「运营作战图」。它会扫描你的 Flashduty 故障与通知渠道、向你提问、把你口述的服务拓扑、排查手册、集群访问方式等沉淀成知识文件，并在需要时帮你接入外部工具（MCP）。 -`/init` 是知识库的**起点**。AI SRE 的诊断质量直接取决于它能读到多少关于你系统的真实知识：[知识库](/zh/ai-sre/knowledge)维护得越完整、越准确，Agent 定位根因就越快、越靠谱。`/init` 就是把这份知识从零建立起来的引导流程，建完之后每一次会话都会自动加载它。 +`/init` 是搭建知识的**起点**。AI SRE 的诊断质量直接取决于它能读到多少关于你系统的真实知识：[知识](/zh/ai-sre/knowledge)维护得越完整、越准确，Agent 定位根因就越快、越靠谱。`/init` 就是把这份知识从零建立起来的引导流程，建完之后每一次会话都会自动加载它。 `/init` **不会**在未经你同意的情况下写入或安装任何东西。每个阶段在写入文件前都会列出「将要创建/更新哪些文件」的清单，由你逐条确认后才执行。凭证（token、密码、AK/SK）永远不会在对话里明文回显，只记为 `<已记录（长度=N）>`。详见 [安全与同意](#安全与同意)。 @@ -29,12 +29,12 @@ sidebarTitle: 初始化 | 场景 | 用法 | |---|---| -| 第一次给某个账户 / 团队搭知识库 | **`/init`**——它会成体系地走完服务、可观测性、runbook、常见故障、集群访问等主题 | -| 系统性地补全或重整一个已有知识库 | **`/init`**——可随时重跑，它会基于现有内容继续，而非推倒重来 | +| 第一次给某个账户 / 团队搭建知识 | **`/init`**——它会成体系地走完服务、可观测性、runbook、常见故障、集群访问等主题 | +| 系统性地补全或重整一份已有知识 | **`/init`**——可随时重跑，它会基于现有内容继续，而非推倒重来 | | 「补一篇 runbook」「更新 services.md」「记一下这个故障模式」 | **直接用自然语言说**，无需 `/init`——Agent 会就当前会话作用域读取、编辑、保存 | -`/init` 与零散的自然语言编辑是互补的：用 `/init` 把底子打全，之后在日常排障里随手让 Agent「把这条经验记进知识库」做增量维护。两者写入的是同一个知识库。 +`/init` 与零散的自然语言编辑是互补的：用 `/init` 把底子打全，之后在日常排障里随手让 Agent「把这条经验记进知识」做增量维护。两者写入的是同一份知识。 ## 如何运行 @@ -52,7 +52,7 @@ sidebarTitle: 初始化 Agent 按主题逐阶段提问（服务与拓扑、可观测性、runbook、常见故障、集群访问……），把你的回答整理成知识文件草稿。每个阶段结束都会问你「继续下一项，还是先停在这里」。 - 每个阶段写入文件前，Agent 会给出一份「将创建/更新哪些文件」的清单，每个文件配 3–5 行摘要。你确认后它才写入知识库，并把新文件链接进 `DUTY.md` 目录。 + 每个阶段写入文件前，Agent 会给出一份「将创建/更新哪些文件」的清单，每个文件配 3–5 行摘要。你确认后它才写入知识，并把新文件链接进 `DUTY.md` 目录。 你可以随时说「跳过这项」「回到第 N 步」「先到这里」。`/init` 不是一次性的——之后任何时候重新输入 `/init` 都能基于已有知识继续补全。 @@ -73,7 +73,7 @@ sidebarTitle: 初始化 通过 Flashduty MCP 拉取你的渠道、近 30 天故障、团队与成员，归纳出你在用的集成类型与高频故障标签。若扫描结果为空（全新账户），切换到「冷启动」模式，改为完全靠访谈采集。 - 可选步骤，需你主动同意，绝不自动触发。如果你已经在 Claude Code / Codex / Cursor / Windsurf / Copilot / Gemini CLI 等本地工具里积累了知识与记忆，可一次性导入，避免后续被反复追问。当 Runner 能直接访问到这些文件时（装在你本机的自托管 Runner），Agent 直接读取 `~/.claude/CLAUDE.md`、各仓库的 `CLAUDE.md` / `AGENTS.md`、`.cursor/rules`、记忆库等；否则（云端沙箱或装在另一台机器上）Agent 给你两段通用提示词，你在本地工具里运行后把结果粘贴 / 上传回来。导入内容按其性质分流：运维 / 服务知识写入知识库文件，个人偏好 / 可复用习惯写入 Agent 记忆，重复或无用的则丢弃。所有导入内容在预览或写入前都会先做**密钥脱敏**，密钥永远不会落盘。 + 可选步骤，需你主动同意，绝不自动触发。如果你已经在 Claude Code / Codex / Cursor / Windsurf / Copilot / Gemini CLI 等本地工具里积累了知识与记忆，可一次性导入，避免后续被反复追问。当 Runner 能直接访问到这些文件时（装在你本机的自托管 Runner），Agent 直接读取 `~/.claude/CLAUDE.md`、各仓库的 `CLAUDE.md` / `AGENTS.md`、`.cursor/rules`、记忆库等；否则（云端沙箱或装在另一台机器上）Agent 给你两段通用提示词，你在本地工具里运行后把结果粘贴 / 上传回来。导入内容按其性质分流：运维 / 服务知识写入知识文件，个人偏好 / 可复用习惯写入 Agent 记忆，重复或无用的则丢弃。所有导入内容在预览或写入前都会先做**密钥脱敏**，密钥永远不会落盘。 Agent 用一段话回述它看到的画面：「我看到 N 个渠道、近 30 天 M 个故障、你似乎在用 [列表]、高频标签包括 [列表]。对吗？还缺什么？」等你确认或纠正，**此时还不写入任何文件**。 @@ -94,7 +94,7 @@ sidebarTitle: 初始化 - 当你表示完成时，Agent 给出一段小结：本次创建/更新了哪些文件、登记了哪些 MCP，并提示「任何时候重跑 `/init` 都能继续」。知识库本身就是这次会话的持久成果。 + 当你表示完成时，Agent 给出一段小结：本次创建/更新了哪些文件、登记了哪些 MCP，并提示「任何时候重跑 `/init` 都能继续」。知识本身就是这次会话的持久成果。 @@ -115,7 +115,7 @@ sidebarTitle: 初始化 每当需要你提供或生成凭证（kubeconfig、云 AK/SK、数据库账号、API token），Agent 都会要求你按**只读 / 最小权限**来配置；在边界可机器校验时，它会先做一次只读边界检查再记录。 - 不是所有信息都值得写进知识库。Agent 只写「缺了它，AI 在故障里会做出更糟决定」的内容——可有可无的细节不会被塞进去，避免知识库变臃肿。 + 不是所有信息都值得写进知识。Agent 只写「缺了它，AI 在故障里会做出更糟决定」的内容——可有可无的细节不会被塞进去，避免知识变臃肿。 @@ -123,9 +123,9 @@ sidebarTitle: 初始化 --- -`/init` 的成果是一份可被后续每次会话自动加载的[知识库](/zh/ai-sre/knowledge)： +`/init` 的成果是一份可被后续每次会话自动加载的[知识](/zh/ai-sre/knowledge)： -- **`DUTY.md`**——知识库的目录入口，只放一句话导引和一份 `@文件名` 链接清单，指向各主题文件； +- **`DUTY.md`**——知识的目录入口，只放一句话导引和一份 `@文件名` 链接清单，指向各主题文件； - **主题文件**——`services.md`、`topology.md`、`observability.md`、`runbooks/<主题>.md`、`common-failures.md`、`clusters.md` 等，实质内容都在这里； - **MCP 登记**（可选）——若访谈中接入了外部工具，会在 `tools.md` 记录并完成 MCP 服务器注册。 @@ -141,15 +141,15 @@ sidebarTitle: 初始化 - 从零把知识库搭起来：服务、拓扑、runbook、集群访问一次成体系地沉淀，让 Agent 一上来就懂你的系统。 + 从零把知识搭起来：服务、拓扑、runbook、集群访问一次成体系地沉淀，让 Agent 一上来就懂你的系统。 - 回看近 30 天会话，找出反复粘贴的上下文、缺失的 runbook、用错的数据源，告诉你**下一步该往知识库里补什么**。 + 回看近 30 天会话，找出反复粘贴的上下文、缺失的 runbook、用错的数据源，告诉你**下一步该往知识里补什么**。 -推荐的节奏：先用 `/init` 打好底子，跑几次真实排障后再用 `/insight` 复盘，把它指出的摩擦补回知识库——必要时重跑 `/init` 做系统性整理。知识库越完善，AI SRE 越精准好用。 +推荐的节奏：先用 `/init` 打好底子，跑几次真实排障后再用 `/insight` 复盘，把它指出的摩擦补回知识——必要时重跑 `/init` 做系统性整理。知识越完善，AI SRE 越精准好用。 ## 相关页面 @@ -161,7 +161,7 @@ sidebarTitle: 初始化 `/init` 的产出落在这里——了解 DUTY.md 结构、文件约束，以及如何手动编辑与维护。 - 用 `/insight` 复盘会话、发现运维摩擦，指导你持续补全知识库。 + 用 `/insight` 复盘会话、发现运维摩擦，指导你持续补全知识。 `/init` 可在访谈中帮你接入的外部工具，了解 MCP 的连接与管理。 diff --git a/zh/ai-sre/insight.mdx b/zh/ai-sre/insight.mdx index 9b31b3c30..533820b00 100644 --- a/zh/ai-sre/insight.mdx +++ b/zh/ai-sre/insight.mdx @@ -1,7 +1,7 @@ --- title: 使用洞察（/insight） description: 在 AI SRE 会话中输入 /insight，自动分析您近 30 天的会话，产出一份只读的教练式月度复盘——先讲做得好的地方，再讲值得消除的摩擦，最后给出更高杠杆的下一步建议。 -keywords: ["AI SRE", "insight", "运营洞察", "摩擦报告", "知识库", "复盘"] +keywords: ["AI SRE", "insight", "运营洞察", "摩擦报告", "知识", "复盘"] sidebarTitle: 使用洞察 --- @@ -18,7 +18,7 @@ sidebarTitle: 使用洞察 这是一份**教练视角的月度复盘**，而不是一张问题清单：它先讲**做得好的地方**——这一个月 AI SRE 在哪些地方真正帮上了忙；再讲**值得现在就消除的摩擦**——那些一再消耗您时间的模式，比如同一个数据库连接串您在多个会话里反复粘贴、Agent 缺少某个本该已知的排查手册、或它反复查错了数据源；最后给出 **2–3 条更高杠杆的下一步建议**——在「怎么用 AI SRE」这件事上可以尝试的方向。 -`/insight` 是**只读**的。它只做分析和呈现，**不会**自动改动任何知识库、Skill 或 MCP 配置。每一条建议都是可复制的文本，是否采纳由您决定。详见 [如何处理建议](#如何处理建议)。 +`/insight` 是**只读**的。它只做分析和呈现，**不会**自动改动任何知识、Skill 或 MCP 配置。每一条建议都是可复制的文本，是否采纳由您决定。详见 [如何处理建议](#如何处理建议)。 `/insight` 是 AI SRE 内置的一项 Skill：它会自动导出你的历史会话、统计量化指标、逐段分析会话内容，最后汇总渲染成一份报告。整个过程对您透明，您只需要输入 `/insight`。 @@ -134,10 +134,10 @@ sidebarTitle: 使用洞察 | `missing_runbook`（缺少运行手册） | Agent 不得不临时拼凑一套多步排查，而您显然期望它本就该会 | 新增运行手册：`knowledge/<范围>/runbooks/<主题>.md` | | `wrong_data_source`（数据源用错） | Agent 查了错误的数据源 / 集群 / 命名空间，被您纠正 | 在 `observability.md` / `clusters.md` 里固定正确的数据源 | | `hallucinated_entity`（臆测实体） | Agent 引用了一个并不存在的服务 / 主机 / 指标 / 变更，被您否定 | 把真实的实体清单补进 `services.md` | -| `stale_knowledge`（知识过期） | 来自知识库 / DUTY.md 的某个事实已经过时或错误，被您当场纠正 | 更新那个过期的文件 | +| `stale_knowledge`（知识过期） | 来自知识 / DUTY.md 的某个事实已经过时或错误，被您当场纠正 | 更新那个过期的文件 | -`repeated_context` 之所以排在首位，是因为它**最持久**——同一个事实跨多个会话被反复提供，意味着把它沉淀进知识库一次，未来每个会话都能直接受益。当它的证据数与其他摩擦持平时，也优先排在前面。 +`repeated_context` 之所以排在首位，是因为它**最持久**——同一个事实跨多个会话被反复提供，意味着把它沉淀进知识一次，未来每个会话都能直接受益。当它的证据数与其他摩擦持平时，也优先排在前面。 ## 如何处理建议 @@ -154,12 +154,12 @@ sidebarTitle: 使用洞察 每张卡片的「可复制的建议」里是一段可直接粘贴的文本，其第一行（`Add this to knowledge/<范围>/…`）就是落点，告诉您它该写到哪个文件——复制时会把目标路径一并带上。 - 根据摩擦类型，到相应的资源里粘贴并保存：重复上下文与臆测实体写进知识库的 `services.md` 或 DUTY.md；缺少运行手册则在知识库里新增一份 runbook；数据源用错就固定到 `observability.md` / `clusters.md`；知识过期则直接更新那个文件。这些都属于 [知识库](/zh/ai-sre/knowledge) 的常规编辑。 + 根据摩擦类型，到相应的资源里粘贴并保存：重复上下文与臆测实体写进知识的 `services.md` 或 DUTY.md；缺少运行手册则在知识里新增一份 runbook；数据源用错就固定到 `observability.md` / `clusters.md`；知识过期则直接更新那个文件。这些都属于 [知识](/zh/ai-sre/knowledge) 的常规编辑。 -`/insight` 永远不会替您执行写入——它不调用任何同步/安装动作，也不改动知识库、Skill 或 MCP。如果您后续想让 AI SRE「把这条 runbook 加进去」，那是一次**独立**的自然语言指令，不属于 `/insight` 的范围。 +`/insight` 永远不会替您执行写入——它不调用任何同步/安装动作，也不改动知识、Skill 或 MCP。如果您后续想让 AI SRE「把这条 runbook 加进去」，那是一次**独立**的自然语言指令，不属于 `/insight` 的范围。 @@ -175,7 +175,7 @@ sidebarTitle: 使用洞察 了解会话的创建、团队绑定与作战室——这些决定了 `/insight` 的分析范围。 - 报告里的建议大多落在知识库的 DUTY.md / `services.md` / runbooks，这里讲如何编辑。 + 报告里的建议大多落在知识的 DUTY.md / `services.md` / runbooks，这里讲如何编辑。 从整体了解 AI SRE 的能力与运行机制。 diff --git a/zh/ai-sre/knowledge.mdx b/zh/ai-sre/knowledge.mdx index 44fa3de9e..cce853cea 100644 --- a/zh/ai-sre/knowledge.mdx +++ b/zh/ai-sre/knowledge.mdx @@ -1,8 +1,8 @@ --- -title: 了解知识库 -description: 知识库由人维护，写这个环境怎么运转。一份 DUTY.md 加上运行手册、服务清单等文件，会话开始时先读使用说明，其余按需打开。 -keywords: ["AI SRE", "知识库", "DUTY.md", "运行手册", "上下文"] -sidebarTitle: 了解知识库 +title: 了解知识 +description: 知识由人维护，写这个环境怎么运转。一份 DUTY.md 加上运行手册、服务清单等文件，会话开始时先读使用说明，其余按需打开。 +keywords: ["AI SRE", "知识", "DUTY.md", "运行手册", "上下文"] +sidebarTitle: 了解知识 --- @@ -13,30 +13,30 @@ sidebarTitle: 了解知识库 --- -知识库是您交给 AI SRE 的运维知识：一份 `DUTY.md` 加上一组运行手册（runbook）、FAQ、服务清单、集群配置等文件。会话开始时，Agent 先读取 `DUTY.md`，再按需打开其它文件，从而把您团队的处置经验、命名约定与系统拓扑带进每一次诊断。 +知识是您交给 AI SRE 的运维资料：一份 `DUTY.md` 加上一组运行手册（runbook）、FAQ、服务清单、集群配置等文件。会话开始时，Agent 先读取 `DUTY.md`，再按需打开其它文件，从而把您团队的处置经验、命名约定与系统拓扑带进每一次诊断。 -控制台入口：**AI SRE → 自定义 → 上下文 → 知识库**。同一分组下的 [记忆](/zh/ai-sre/memory) 是另一页，两者分开管理。 +控制台入口：**AI SRE → 自定义 → 上下文 → 知识**。同一分组下的 [记忆](/zh/ai-sre/memory) 是另一页，两者分开管理。 -整个账户只能有 1 个共享知识库，每个团队最多有 1 个团队知识库： +整个账户只能有 1 份共享知识，每个团队最多有 1 份团队知识： - **共享（即账户级）**知识对账户内所有 Agent 可见。 - **团队级**知识仅在该团队的会话中加载。 -知识库是 AI SRE 资源的一种，遵循统一的两级作用域模型。其他资源（Skill、MCP、Agent、运行环境）的作用域规则与本页一致。 +知识是 AI SRE 资源的一种，遵循统一的两级作用域模型。其他资源（Skill、MCP、Agent、运行环境）的作用域规则与本页一致。 - 知识库内容用于**精炼**Agent 的领域上下文（人设、方法论、系统知识），但不会覆盖系统的安全与行为底线。如果某份知识要求 Agent 跳过安全规则，会被当作越权内容忽略，而非更高优先级的指令。 + 知识内容用于**精炼**Agent 的领域上下文（人设、方法论、系统知识），但不会覆盖系统的安全与行为底线。如果某份知识要求 Agent 跳过安全规则，会被当作越权内容忽略，而非更高优先级的指令。 ## DUTY.md 结构 --- -`DUTY.md` 是整个知识库的**目录入口**，每次会话自动加载。Agent 会全文读取 `DUTY.md`，再通过 `@文件名` 引用按需拉取其它文件。系统不会在 `DUTY.md` 之外另附文件列表：知识文件放在会话工作区的 `knowledge/` 目录下，Agent 像浏览代码仓库一样用 ls / glob / grep 查找，`DUTY.md` 没有引用到的文件也能被找到。 +`DUTY.md` 是整份知识的**目录入口**，每次会话自动加载。Agent 会全文读取 `DUTY.md`，再通过 `@文件名` 引用按需拉取其它文件。系统不会在 `DUTY.md` 之外另附文件列表：知识文件放在会话工作区的 `knowledge/` 目录下，Agent 像浏览代码仓库一样用 ls / glob / grep 查找，`DUTY.md` 没有引用到的文件也能被找到。 如果某个作用域还没有 `DUTY.md`，该作用域不会被静默跳过：系统会告诉 Agent 这个范围没有使用说明、文件在哪个目录下，并要求它在开展实质工作前先列出目录、阅读相关文件。 -引用采用 `@<路径>` 风格，路径指向同一个知识库内的另一份文件，支持子目录（如 `@runbooks/api-5xx.md`）： +引用采用 `@<路径>` 风格，路径指向同一份知识内的另一份文件，支持子目录（如 `@runbooks/api-5xx.md`）： ```markdown # 值班知识总览 (DUTY.md) @@ -64,7 +64,7 @@ Agent 读取 `DUTY.md` 后，会根据当前故障判断需要展开哪些 `@引 | --- | --- | --- | | 文件内容 | 纯文本（UTF-8） | 按**内容**校验而非扩展名：文件不含 NUL 字节且能按 UTF-8 解码即可保存。因此 `.md` `.yaml` `.json` `.txt` `.sh` 之外的 `.py` `.sql`，乃至没有扩展名的 `Dockerfile` 都可以上传；反之，扩展名是 `.txt` 但内容为二进制的文件会被拒绝 | | 单文件上限 | 1 MiB | 超出无法保存 | -| 单个知识库上限 | 5 MiB | 控制台用量条按此额度显示 | +| 单份知识上限 | 5 MiB | 控制台用量条按此额度显示 | | 文件数量上限 | 100 | 达到上限后无法新增文件 | | 子目录 | 允许 | 路径可含 `/`，如 `runbooks/api-5xx.md`；不允许以 `.` 开头的路径段 | | 点文件 | 不允许 | 文件名不能以 `.` 开头 | @@ -73,33 +73,33 @@ Agent 读取 `DUTY.md` 后，会根据当前故障判断需要展开哪些 `@引 --- -进入 **AI SRE → 自定义 → 上下文 → 知识库**。列表每行是一个知识库，按范围（「共享」或团队名）标识，列出文件数、`DUTY.md` 状态和最近修改时间。`DUTY.md` 状态有三种：**未创建**、**已同步**，以及 **需梳理 · 之后改了 N 次**（`DUTY.md` 写好之后，库里其它文件又改过）。点击 **创建** 可以为共享范围或您所属的团队新建知识库；账户和所有可用团队都已有知识库时，按钮置灰。 +进入 **AI SRE → 自定义 → 上下文 → 知识**。列表每行是一份知识，按范围（「共享」或团队名）标识，列出文件数、`DUTY.md` 状态和最近修改时间。`DUTY.md` 状态有三种：**未创建**、**已同步**，以及 **需梳理 · 之后改了 N 次**（`DUTY.md` 写好之后，这份知识里其它文件又改过）。点击 **创建** 可以为共享范围或您所属的团队新建知识；账户和所有可用团队都已有知识时，按钮置灰。 -还没有任何知识库时，页面改为引导：**初始化 AI-SRE** 会打开新对话并运行 [`/init`](/zh/ai-sre/init)，**上传已有文档** 会打开新对话并弹出附件选择。 +还没有任何知识时，页面改为引导：**初始化 AI-SRE** 会打开新对话并运行 [`/init`](/zh/ai-sre/init)，**上传已有文档** 会打开新对话并弹出附件选择。 -点击某一行进入这个知识库： +点击某一行进入这份知识： - **左侧是文件树。** `DUTY.md` 固定在最上方，带 **自动加载** 标记；其余文件列在「其他文件 · 按需读取」下。还没有 `DUTY.md` 时，这里显示「未创建」和 **让 AI 生成** 按钮。文件树上方显示用量（已用 / 5 MB 和文件数），以及 **新建文件**、**上传** 两个入口。 - **右侧是文件正文。** 点 **编辑** 可以直接改当前文件，在 **预览** 与 **源码** 之间切换，点 **保存** 写入。 - **上传**：任意 UTF-8 文本文件直接入库，支持选择整个文件夹上传，同名文件会先询问是否覆盖。PDF、Word、HTML 等文档不能直接入库，可以点 **转到对话分析**，由 AI 读取后提炼成 Markdown 文件，经您确认再保存。 -文件仍要满足上面的限制：纯文本、单文件不超过 1 MiB、一个知识库不超过 5 MiB 和 100 个文件。`@引用` 指向库里没有的文件时，仍然可以保存。 +文件仍要满足上面的限制：纯文本、单文件不超过 1 MiB、一份知识不超过 5 MiB 和 100 个文件。`@引用` 指向这份知识里没有的文件时，仍然可以保存。 ### 让 AI 修改 -正文下方有一个输入框（提示语为「想让 AI 怎么改这个知识库？例如：补一份 OOM 排查手册」）。写下要改什么并发送，控制台会打开一个新对话，输入框里已带上这个知识库的引用和您的要求；团队知识库会把对话切到对应团队。发出后，AI 先用文字说明要改哪些文件、怎么改，您同意后才保存。页面本身不提供改动预览或逐条审阅。 +正文下方有一个输入框（提示语为「想让 AI 怎么改这份知识？例如：补一份 OOM 排查手册」）。写下要改什么并发送，控制台会打开一个新对话，输入框里已带上这份知识的引用和您的要求；团队知识会把对话切到对应团队。发出后，AI 先用文字说明要改哪些文件、怎么改，您同意后才保存。页面本身不提供改动预览或逐条审阅。 **让 AI 生成** 与下面的 **让 AI 梳理** 也是同样的流程：转到新对话，请求已经写好。 ### DUTY.md 需要梳理时 -`DUTY.md` 写好之后，如果库里其它文件又被改过，文件树上方会出现提示：「DUTY.md 写好之后，知识库又改了 N 次，可能需要重新梳理」。有编辑权限时，提示下方有两个操作： +`DUTY.md` 写好之后，如果这份知识里其它文件又被改过，文件树上方会出现提示：「DUTY.md 写好之后，知识又改了 N 次，可能需要重新梳理」。有编辑权限时，提示下方有两个操作： - **让 AI 梳理**：转到新对话，让 AI 对照现有文件更新 `DUTY.md` 的索引，改动先经您确认。 - **已核对，不用改**：确认 `DUTY.md` 仍然准确。提示随即消失，直到下一次文件改动。 - 助手也能在对话里维护当前会话所属范围的知识库，例如「补一篇 runbook」「更新 services.md」。它读取、修改，再经您确认后保存。 + 助手也能在对话里维护当前会话所属范围的知识，例如「补一篇 runbook」「更新 services.md」。它读取、修改，再经您确认后保存。 ## Agent 如何使用知识 @@ -125,14 +125,14 @@ Agent 读取 `DUTY.md` 后，会根据当前故障判断需要展开哪些 `@引 - 若知识库未能成功加载进当前会话，消息列表上方会出现一条警告横幅：「知识库加载失败 — 本次会话中 AI-SRE 可能无法访问 DUTY.md 与 runbook。」，并附带 **重试** 按钮，点击后会重新尝试加载。重试成功前，Agent 在该会话中可能无法读取 DUTY.md 与运行手册。 + 若知识未能成功加载进当前会话，消息列表上方会出现一条警告横幅：「知识加载失败 — 本次会话中 AI-SRE 可能无法访问 DUTY.md 与 runbook。」，并附带 **重试** 按钮，点击后会重新尝试加载。重试成功前，Agent 在该会话中可能无法读取 DUTY.md 与运行手册。 ## 作用域与可见性 --- -每个知识库都有一个作用域：共享范围（即账户级，账户内全局可见）或团队范围。 +每份知识都有一个作用域：共享范围（即账户级，账户内全局可见）或团队范围。 | 维度 | 共享 | 团队 | | --- | --- | --- | @@ -141,9 +141,9 @@ Agent 读取 `DUTY.md` 后，会根据当前故障判断需要展开哪些 `@引 | 会话中加载 | 所有会话 | 仅绑定该团队的会话 | | 运行时可读 | 所有会话 | 绑定该团队的会话；以及创建者属于该团队的个人会话（读取即挂载） | -**编辑权限**：团队知识库仅该团队的成员可以操作，组织管理员也需要先加入该团队；共享知识库仅账户 Owner 或管理员可以操作；不存在「创建者额外保留权限」的规则。控制台会把你无权编辑的行置灰，并禁用其开关与操作按钮。 +**编辑权限**：团队知识仅该团队的成员可以操作，组织管理员也需要先加入该团队；共享知识仅账户 Owner 或管理员可以操作；不存在「创建者额外保留权限」的规则。控制台会把你无权编辑的行置灰，并禁用其开关与操作按钮。 -**创建与改归属**：创建新的团队知识库时，您必须是目标团队成员；共享范围创建仅限账户 Owner 或管理员。编辑已有知识库时，账户 Owner 或管理员可以把它移动到任意团队，用于恢复空团队或离职成员留下的资源；普通成员只能移动到自己所属的团队。把已有知识库提升为共享范围（**设为共享**）与共享范围创建同门槛：仅限账户 Owner 或管理员操作，普通成员即使属于该知识库所在团队也不能自助提升。 +**创建与改归属**：创建新的团队知识时，您必须是目标团队成员；共享范围创建仅限账户 Owner 或管理员。编辑已有知识时，账户 Owner 或管理员可以把它移动到任意团队，用于恢复空团队或离职成员留下的资源；普通成员只能移动到自己所属的团队。把已有知识提升为共享范围（**设为共享**）与共享范围创建同门槛：仅限账户 Owner 或管理员操作，普通成员即使属于这份知识所在团队也不能自助提升。 **运行时可见性**：会话开始时，只加载**共享范围**资源加上**当前会话绑定团队**的资源。绑定来源是显式指定的团队，或作战室（war room）故障对应的团队。会话进行中能否再挂载其它团队的知识，看会话类型： @@ -171,10 +171,10 @@ Agent 读取 `DUTY.md` 后，会根据当前故障判断需要展开哪些 `@引 新增或重命名文件后，同步更新 `DUTY.md` 与相关文件里的 `@引用`。保存时的「引用未解析」警告与删除时的「仍被引用」提示，能帮您及时发现断链。 - 共享知识库放跨团队通用的约定（命名规范、通用排障方法、平台访问方式）；团队知识库放该团队专属的服务清单、值班手册与上下游。绑定团队的会话会同时拿到两者。 + 共享知识放跨团队通用的约定（命名规范、通用排障方法、平台访问方式）；团队知识放该团队专属的服务清单、值班手册与上下游。绑定团队的会话会同时拿到两者。 - 排障过程中沉淀出的新处置经验，可以直接让 Agent「补一篇 runbook」或「记录这个故障模式」，它会对当前作用域读取→编辑→保存，把经验回写进知识库，形成持续积累的闭环。 + 排障过程中沉淀出的新处置经验，可以直接让 Agent「补一篇 runbook」或「记录这个故障模式」，它会对当前作用域读取→编辑→保存，把经验回写进知识，形成持续积累的闭环。 @@ -184,13 +184,13 @@ Agent 读取 `DUTY.md` 后，会根据当前故障判断需要展开哪些 `@引 - 把可复用的诊断流程封装为 Skill，与知识库共享同一套作用域。 + 把可复用的诊断流程封装为 Skill，与知识共享同一套作用域。 通过 MCP 接入外部系统，让 Agent 调用您的工具与数据。 - AI 在对话里记下的偏好、做法、事实和教训，与知识库分开管理。 + AI 在对话里记下的偏好、做法、事实和教训，与知识分开管理。 了解会话如何绑定团队，以及知识在会话中如何被读取与挂载。 diff --git a/zh/ai-sre/mcp.mdx b/zh/ai-sre/mcp.mdx index 92c0a4b28..0979b00bd 100644 --- a/zh/ai-sre/mcp.mdx +++ b/zh/ai-sre/mcp.mdx @@ -208,7 +208,7 @@ Agent 读取 Flashduty 故障、告警等数据的能力是**内置**的：**Fla --- -MCP 与其他资源（Skill、知识库、Agent、运行环境）共用同一套**两级作用域**模型，分为共享范围与团队范围： +MCP 与其他资源（Skill、知识、Agent、运行环境）共用同一套**两级作用域**模型，分为共享范围与团队范围： | 作用域 | 可见性 | | --- | --- | diff --git a/zh/ai-sre/memory.mdx b/zh/ai-sre/memory.mdx index d65430e6b..ca65324a1 100644 --- a/zh/ai-sre/memory.mdx +++ b/zh/ai-sre/memory.mdx @@ -15,7 +15,7 @@ sidebarTitle: 了解记忆 AI SRE 每次新会话都从当前范围里已有的记忆文件读起。如果每次都要重新说明您的习惯、某类故障先看哪里、上次为什么放弃了某个做法，排障就得从头介绍背景。记忆把这些从对话里留下来，写成一份份 Markdown 文件，后面的会话继续用。 -记忆和[知识库](/zh/ai-sre/knowledge)是两回事。知识库由人维护，写的是环境怎么运转。记忆由系统整理，写的是从对话里留下来的偏好、做法、事实和教训。两者同属控制台的 [上下文](/zh/ai-sre/context) 分组，但各有一页：**AI SRE → 自定义 → 上下文 → 记忆**。 +记忆和[知识](/zh/ai-sre/knowledge)是两回事。知识由人维护，写的是环境怎么运转。记忆由系统整理，写的是从对话里留下来的偏好、做法、事实和教训。两者同属控制台的 [上下文](/zh/ai-sre/context) 分组，但各有一页：**AI SRE → 自定义 → 上下文 → 记忆**。 ## 记忆类型 @@ -89,9 +89,9 @@ AI SRE 每次新会话都从当前范围里已有的记忆文件读起。如果 - 记忆和知识库怎么分，以及个人、团队、共享范围各自有什么。 + 记忆和知识怎么分，以及个人、团队、共享范围各自有什么。 - + 使用说明和运行手册由人维护，和系统整理的记忆不是同一类资料。 diff --git a/zh/ai-sre/overview.mdx b/zh/ai-sre/overview.mdx index aae8dce69..960c56ada 100644 --- a/zh/ai-sre/overview.mdx +++ b/zh/ai-sre/overview.mdx @@ -1,7 +1,7 @@ --- title: AI SRE 产品概述 description: Flashduty 推出的自治 SRE Agent 平台，通过对话让 AI 自主排障、调查故障、沉淀与复用运维知识，并与 Flashduty 故障响应体系及 IM 协作深度联动 -keywords: ["AI SRE", "Agent", "故障排查", "对话式排障", "IM 协作", "作战室", "MCP", "知识库"] +keywords: ["AI SRE", "Agent", "故障排查", "对话式排障", "IM 协作", "作战室", "MCP", "知识"] sidebarTitle: 概述 --- @@ -124,7 +124,7 @@ AI SRE 围绕"对话排障 + 知识沉淀 + 自主执行"构建了一套完整 可被 Agent 调用的 Skill 包，封装可复用的排障流程。范围可设为共享（即账户级）或团队，启用后在会话中按需加载。 - 以 DUTY.md 为入口、按 @-引用索引的知识库，承载服务清单、runbook、值班路径等长期上下文，按账户/团队分层加载。 + 以 DUTY.md 为入口、按 @-引用索引的知识，承载服务清单、runbook、值班路径等长期上下文，按账户/团队分层加载。 通过 Model Context Protocol 接入外部工具与数据源。MCP 服务器不预连接，Agent 在调用时按需建连、执行、断连。 @@ -163,7 +163,7 @@ AI SRE 围绕"对话排障 + 知识沉淀 + 自主执行"构建了一套完整 | 分组 | 页面 | 作用 | |------|------|------| -| 上下文 | 知识库、记忆 | [知识库](/zh/ai-sre/knowledge)：整个账户 1 个共享知识库，每个团队最多 1 个团队知识库。[记忆](/zh/ai-sre/memory)：AI 在对话里记下的偏好、做法、事实和教训，分个人和团队。 | +| 上下文 | 知识、记忆 | [知识](/zh/ai-sre/knowledge)：整个账户 1 份共享知识，每个团队最多 1 份团队知识。[记忆](/zh/ai-sre/memory)：AI 在对话里记下的偏好、做法、事实和教训，分个人和团队。 | | 插件 | 概览、Apps、Skill、MCP、Agents | **概览** 是插件目录（MCP 模板、Skill 模板、内置 App）；[Apps](/zh/ai-sre/apps)（已授权的外部应用，如 GitHub）、[Skill](/zh/ai-sre/skills)、[MCP](/zh/ai-sre/mcp)（外部工具）、[Agents](/zh/ai-sre/agents)（A2A 远端 Agent）。 | | 环境 | 自托管、云端 | [自托管](/zh/ai-sre/environments)：部署在您机器上的常驻 Runner；**云端**：Flashduty 托管的云端沙箱模板。无可用自托管环境时，会话回退到云端沙箱。 | diff --git a/zh/ai-sre/quickstart.mdx b/zh/ai-sre/quickstart.mdx index 93a0fa2e4..aafa25fb5 100644 --- a/zh/ai-sre/quickstart.mdx +++ b/zh/ai-sre/quickstart.mdx @@ -1,7 +1,7 @@ --- title: 15 分钟完成第一次 AI SRE 排障 description: 从一个真实故障开始，完成第一次有上下文、有证据、可继续追问的 AI SRE 调查；随后按需让新故障自动获得第一轮分析、建立团队知识、部署 BYOC Runner 接入真实数据源。 -keywords: ["AI SRE", "快速开始", "Quickstart", "故障调查", "故障自动分析", "/init", "知识库", "MCP", "BYOC Runner"] +keywords: ["AI SRE", "快速开始", "Quickstart", "故障调查", "故障自动分析", "/init", "知识", "MCP", "BYOC Runner"] sidebarTitle: 快速开始 --- @@ -19,7 +19,7 @@ sidebarTitle: 快速开始 |---|---| | 会话 | 你和 Agent 的一次协作，控制台或 IM 里都能开 → [控制台](/zh/ai-sre/sessions) | | @ 引用 | 把故障现场带进对话的方式，输入 `@` 搜索并插入故障 → [控制台](/zh/ai-sre/sessions) | -| 知识库 | 你维护的、关于你系统的长期资料（DUTY.md、运行手册、服务清单），越完整定位越准 → [了解知识库](/zh/ai-sre/knowledge) | +| 知识 | 你维护的、关于你系统的长期资料（DUTY.md、运行手册、服务清单），越完整定位越准 → [了解知识](/zh/ai-sre/knowledge) | | 运行环境 | Agent 动手的地方——云端 Sandbox 或你内网的 BYOC Runner → [运行环境](/zh/ai-sre/environments) | ## 三个入口（从哪儿开始） @@ -90,9 +90,9 @@ AI SRE 没有唯一入口，从你现在所在的场景开始就好： 它与作战室自动诊断是两条独立链路：这条对每一条匹配的新故障生效，结果写回故障评论；作战室自动诊断在你为故障开启 IM 作战室时运行，结果回贴到作战室群里（见 [IM 平台](/zh/ai-sre/im)）。 -### 建一份团队知识库 +### 建一份团队知识 -Agent 每次排障都从零猜「这是什么服务」「谁负责」「以前是怎么处理的」，效率就上不去。在会话里输入 `/init`，Agent 会用访谈的方式带你梳理服务清单、runbook、值班路径等知识，逐条确认后写入知识库，后续会话自动加载。完整访谈流程见[初始化（/init）](/zh/ai-sre/init)，知识库结构与最佳实践见[管理知识](/zh/ai-sre/knowledge)。 +Agent 每次排障都从零猜「这是什么服务」「谁负责」「以前是怎么处理的」，效率就上不去。在会话里输入 `/init`，Agent 会用访谈的方式带你梳理服务清单、runbook、值班路径等知识，逐条确认后写入知识，后续会话自动加载。完整访谈流程见[初始化（/init）](/zh/ai-sre/init)，知识结构与最佳实践见[管理知识](/zh/ai-sre/knowledge)。 ### 接入真实数据源 diff --git a/zh/ai-sre/sessions.mdx b/zh/ai-sre/sessions.mdx index e651e57de..16866c116 100644 --- a/zh/ai-sre/sessions.mdx +++ b/zh/ai-sre/sessions.mdx @@ -143,8 +143,8 @@ Subagent / A2A 子会话本身也不能单独开启分享——分享只能在** **交接只带一个引用时会预填提问**：当本次交接合并后恰好只剩一个引用、且该引用里带了入口维护的默认提问时，输入框会预填这句提问，`[[ref]]` 占位处则落成引用胶囊。例如在故障列表里对多条故障批量点击 **AI 分析**，输入框预填的就是「请批量分析这些故障 〈引用胶囊〉：先判断它们之间的关联性（同一根因、连锁反应或彼此独立）并分组；再按组给出可能根因与影响面；最后给出整体处置建议与优先级。需要单个故障的细节时用工具按需拉取，不必逐个展开全部故障。请区分已确认事实、合理推断和待确认项；证据不足时明确说明，不要声称执行了未执行的操作。」，胶囊标题为「故障清单（N）」；带多个引用的交接则不预填提问，输入框保持原样。一条消息可携带多个引用。除了从相关页面自动携带引用外，也可以在任意会话的输入框里直接输入 `@` 触发故障搜索下拉（支持关键词模糊匹配与近期故障列表），选中后插入与自动携带相同的引用胶囊——这是一个随时可用的独立引用入口。输入邮箱地址不会误触发该下拉：当 `@` 紧跟在邮箱地址字符（字母、数字或 `._%+-`）之后时，选择器不会弹出；而空格之后、或与中文相邻的 `@` 仍正常触发。 - - 会话启动时会按绑定团队自动加载对应的知识库与 Skill；详见下文 知识库 与 Skill。 + + 会话启动时会按绑定团队自动加载对应的知识与 Skill；详见下文 知识 与 Skill。 @@ -187,7 +187,7 @@ Subagent / A2A 子会话本身也不能单独开启分享——分享只能在** -当上一个沙箱因空闲被回收时，卡片会给出警示：**原沙箱因闲置 N 分钟被回收 — 已保存的文件被重置**。这意味着此前写入沙箱文件系统的内容已不复存在。请将需要长期留存的产出**保存为 Artifact 或沉淀到知识库**，而不要依赖沙箱内的临时文件。 +当上一个沙箱因空闲被回收时，卡片会给出警示：**原沙箱因闲置 N 分钟被回收 — 已保存的文件被重置**。这意味着此前写入沙箱文件系统的内容已不复存在。请将需要长期留存的产出**保存为 Artifact 或沉淀到知识**，而不要依赖沙箱内的临时文件。 @@ -469,14 +469,14 @@ Fork 会话会清理只属于运行中的临时状态，例如当前回合缓存 --- -新建会话时可以为会话 **绑定团队**。绑定后，会话在启动时会自动加载该团队的知识库、Skill 与 MCP，让 Agent 一开始就具备这个团队的领域上下文与能力。未绑定团队时，会话以账户范围运行。 +新建会话时可以为会话 **绑定团队**。绑定后，会话在启动时会自动加载该团队的知识、Skill 与 MCP，让 Agent 一开始就具备这个团队的领域上下文与能力。未绑定团队时，会话以账户范围运行。 在新建会话的输入区通过团队选择器挑选要绑定的团队；您上次的选择会被记住，省去每次重复选择。 - 会话启动即加载「账户范围 + 绑定团队」的知识库 / Skill / MCP 元数据，Agent 随即可用。 + 会话启动即加载「账户范围 + 绑定团队」的知识 / Skill / MCP 元数据，Agent 随即可用。 未绑定团队的个人会话里，Agent 可以按需读取会话创建者所属团队的知识，将该团队的知识与能力作为持久上下文挂载进当前会话——一次挂载在本会话内持续有效。绑定了团队的会话只用共享范围和这个团队的知识，不能挂载其它团队的。 diff --git a/zh/ai-sre/skills.mdx b/zh/ai-sre/skills.mdx index 09995d01b..db5943e25 100644 --- a/zh/ai-sre/skills.mdx +++ b/zh/ai-sre/skills.mdx @@ -215,7 +215,7 @@ Skill 包**过大无法预览**时，检视面板会提示体积并建议改用 --- -Skill 与其他资源（知识库、MCP、Agent、运行环境）共用同一套**两级作用域**模型，分为账户级与团队级： +Skill 与其他资源（知识、MCP、Agent、运行环境）共用同一套**两级作用域**模型，分为账户级与团队级： | 作用域 | 可见性 | | --- | --- | @@ -238,7 +238,7 @@ Skill 与其他资源（知识库、MCP、Agent、运行环境）共用同一套 - 用 DUTY.md 与知识库为 Agent 提供团队上下文与排障经验。 + 用 DUTY.md 与知识为 Agent 提供团队上下文与排障经验。 接入外部工具，让 Skill 在 SKILL.md 中以 `mcp:服务名/工具名` 调用它们。 diff --git a/zh/developer/cli.mdx b/zh/developer/cli.mdx index a6c2c1059..f73b84a44 100644 --- a/zh/developer/cli.mdx +++ b/zh/developer/cli.mdx @@ -702,17 +702,17 @@ flashduty alert --help # 查看告警相关的生成命令 生成命令的时间窗口参数（`--start-time` / `--end-time`）与精选命令一样支持人性化的时间格式：相对时长（`7d`、`24h`，表示从当前往前推）、`+7d`（从当前往后推，即未来时间）、`now`、日期或日期时间（如 `2026-05-01`、`2026-05-01 10:00:00`）、Unix 秒级时间戳。此外，`--since` 和 `--until` 分别是 `--start-time` 和 `--end-time` 的别名，可互换使用；若两种写法同时传入且取值不同，CLI 会报冲突错误。 -#### knowledge — AI SRE 知识库 +#### knowledge — AI SRE 知识 -`safari knowledge-*` 命令族管理 AI SRE 的**知识库**——账户或团队作用域下的版本化文件树（`DUTY.md` 加运行手册、FAQ、服务清单等），会话开始时会被加载进每个 AI SRE 沙箱。知识库的完整功能模型（`DUTY.md` 结构、`@引用`、账户/团队作用域、文件约束）参见 [管理知识](/zh/ai-sre/knowledge)。 +`safari knowledge-*` 命令族管理 AI SRE 的**知识**——账户或团队作用域下的版本化文件树（`DUTY.md` 加运行手册、FAQ、服务清单等），会话开始时会被加载进每个 AI SRE 沙箱。知识的完整功能模型（`DUTY.md` 结构、`@引用`、账户/团队作用域、文件约束）参见 [管理知识](/zh/ai-sre/knowledge)。 ```bash -flashduty safari knowledge-get # 获取当前账户知识库（含文件列表） -flashduty safari knowledge-pack-list [flags] # 列出知识库 -flashduty safari knowledge-pack-ensure --scope [--scope-id ] # 确保知识库存在（不存在则创建） -flashduty safari knowledge-pack-update [--scope ...] # 变更知识库作用域 -flashduty safari knowledge-pack-delete # 删除知识库（不可逆） -flashduty safari knowledge-file-list [--pack-id ] # 列出知识库内的文件 +flashduty safari knowledge-get # 获取当前账户知识（含文件列表） +flashduty safari knowledge-pack-list [flags] # 列出知识 +flashduty safari knowledge-pack-ensure --scope [--scope-id ] # 确保知识存在（不存在则创建） +flashduty safari knowledge-pack-update [--scope ...] # 变更知识作用域 +flashduty safari knowledge-pack-delete # 删除知识（不可逆） +flashduty safari knowledge-file-list [--pack-id ] # 列出知识内的文件 flashduty safari knowledge-file-get --rel-path # 读取单个知识文件（内容为 Base64 编码） flashduty safari knowledge-file-put --rel-path --content-b64 # 上传或覆盖知识文件 flashduty safari knowledge-file-delete --rel-path [--force] # 删除知识文件 @@ -722,9 +722,9 @@ flashduty safari knowledge-file-delete --rel-path [--force] # 删除知 | 参数 | 说明 | |------|------| -| `--pack-id` | 知识库 ID；省略时默认使用调用者账户作用域的知识库 | -| `--rel-path` | 文件相对知识库根目录的路径（必填，支持子目录，如 `runbooks/api-5xx.md`） | -| `--scope` | 知识库作用域：`account` 或 `team`（`knowledge-pack-ensure` 必填） | +| `--pack-id` | 知识 ID；省略时默认使用调用者账户作用域的知识 | +| `--rel-path` | 文件相对知识根目录的路径（必填，支持子目录，如 `runbooks/api-5xx.md`） | +| `--scope` | 知识作用域：`account` 或 `team`（`knowledge-pack-ensure` 必填） | | `--scope-id` | 团队 ID；`team` 作用域必填，`account` 作用域忽略 | | `--force` | 删除文件时跳过「仍被其他文件引用」检查，引用方改为以警告形式返回 | diff --git a/zh/developer/go-sdk.mdx b/zh/developer/go-sdk.mdx index 6b8d4def1..2b45a0400 100644 --- a/zh/developer/go-sdk.mdx +++ b/zh/developer/go-sdk.mdx @@ -164,7 +164,7 @@ client, err := flashduty.NewClient("YOUR_APP_KEY", | `client.A2aAgents` | A2A Agents | | `client.Artifacts` | AI SRE 产物 | | `client.Automations` | AI SRE 自动化 | -| `client.Knowledge` | AI SRE 知识库（知识库本身与其中的知识文件） | +| `client.Knowledge` | AI SRE 知识（每份知识本身与其中的知识文件） | | `client.McpServers` | MCP Servers | | `client.Sessions` | AI SRE 会话 | | `client.Skills` | Skills | @@ -180,7 +180,7 @@ client, err := flashduty.NewClient("YOUR_APP_KEY", `client.StatusPages.DraftCreate`（`POST /status-page/draft/create`）把一次状态页事件草稿存下来，供人工在控制台审阅后发布，不会直接对外可见：`draft` 为任意 JSON，按原文存储、序列化后不超过 64 KB，其中 `page_id`、`type`（`incident` 或 `maintenance`）、`name`、`message` 会被校验；`change_id`（> 0 时表示追加到已有事件的一次更新）、`status`、`affected_components` 可选，新建 maintenance 时可用 `start_time` / `end_time`（Unix 秒）指定窗口。请求上的 `source` 是草稿来源标记（≤ 64 字符，如 `ai_sre:sess_xxx`）；响应返回 `draft_id`（匹配 `draft_[A-Za-z0-9]{22}`），控制台的审阅链接即携带它。 -`client.Knowledge` 对应 `/safari/knowledge/*` 的 9 个 API 操作：知识库侧为 `PackReadGet`（获取账户知识库）、`PackReadList`（列出知识库）、`PackWriteEnsure`（确保知识库存在）、`PackWriteUpdate`（变更知识库作用域）、`PackWriteDelete`（删除知识库）；知识文件侧为 `FileReadGet`、`FileReadList`、`FileWritePut`（上传/覆盖）、`FileWriteDelete`。相关导出类型包括 `KnowledgePackItem`、`KnowledgeFileItem`、`KnowledgeWarning` 以及各 `Knowledge*Request` / `Knowledge*Response`。 +`client.Knowledge` 对应 `/safari/knowledge/*` 的 9 个 API 操作：知识侧为 `PackReadGet`（获取账户知识）、`PackReadList`（列出知识）、`PackWriteEnsure`（确保知识存在）、`PackWriteUpdate`（变更知识作用域）、`PackWriteDelete`（删除知识）；知识文件侧为 `FileReadGet`、`FileReadList`、`FileWritePut`（上传/覆盖）、`FileWriteDelete`。相关导出类型包括 `KnowledgePackItem`、`KnowledgeFileItem`、`KnowledgeWarning` 以及各 `Knowledge*Request` / `Knowledge*Response`。 `client.Artifacts`（AI SRE 产物）对应 `/safari/artifact/*` 的 11 个 API 操作：画廊读取侧 `ReadGet`（按 ID 获取单个已发布产物）、`ReadList`（分页列出调用方可见的产物，支持标题子串搜索、`scope`（`all` / `personal` / `team`）与 `team_ids` 过滤）、`ReadGetFileState`（批量探测会话展示文件（`pf_` 前缀）是否已有上线产物，单次至多 50 个 ID）；文件侧 `ReadSign`（为展示文件签发短期有效的下载/预览 URL，有效期 5 分钟，`expires_in` 固定 300 秒）与 `ReadStream`（凭签名 token 下载或预览文件，成功响应体是文件而非 JSON 信封，原始字节放在 `Response.Raw`）；写入侧 `WritePublish`（把会话产生的文件发布为画廊产物）、`WriteUpdate`（重命名或转移个人/团队作用域）、`WriteDelete`（从画廊移除，源文件仍保留在会话中）；公开分享 `WriteShareEnable`（开启匿名公开分享并返回公开链接，任何人凭链接即可查看、无需登录）、`WriteShareRevoke`（关闭分享，链接立即失效）、`WriteShareSync`（把公开快照刷新为最新内容——当 `share_enabled` 为 true 且 `share_file_id` 与 `file_id` 不一致时表示快照已过期，调用它刷新）。相关导出类型包括 `PublishedArtifactItem`、`ArtifactShareState`、`SignedUrLs` 以及各 `Artifact*Request` / `Artifact*Response`。 diff --git a/zh/home.mdx b/zh/home.mdx index bef254aa6..a01c20084 100644 --- a/zh/home.mdx +++ b/zh/home.mdx @@ -45,7 +45,7 @@ Flashduty 是面向 DevOps、SRE 和运维团队的一站式可观测性平台 - **对话即排障**：Agent 自主规划、调用工具、流式输出调查过程与结论 - **与故障响应联动**：从故障或作战室一键拉起会话，携带上下文进入排查 - - **知识沉淀与复用**：以 DUTY.md 为入口的知识库承载长期运维上下文 + - **知识沉淀与复用**：以 DUTY.md 为入口的知识承载长期运维上下文 - **可扩展工具生态**：Skill、MCP、A2A Agent 与自托管 Runner diff --git a/zh/on-call/comparison/vs-pagerduty.mdx b/zh/on-call/comparison/vs-pagerduty.mdx index b70c35712..d67e15507 100644 --- a/zh/on-call/comparison/vs-pagerduty.mdx +++ b/zh/on-call/comparison/vs-pagerduty.mdx @@ -160,7 +160,7 @@ Response 解决「找到人之后怎么快速闭环」：一条时间线、一 | **代码仓库与 K8s** | [GitHub/GitLab App](/zh/ai-sre/apps) 沙箱内访问代码仓库、提交 PR/MR/Issue；Kubernetes App 按 namespace 接入集群 | 公开资料未见 | | **AI 自动化任务** | [自动化](/zh/ai-sre/automations)按 cron、HTTP API 或故障事件触发，内置告警噪音分析、事故复盘、值班洞察等模板 | 依赖 Event Orchestration 与 Runbook Automation 独立产品线 | | **可扩展性** | [Skills 市场](/zh/ai-sre/skills)、[MCP 外部工具](/zh/ai-sre/mcp)、[Subagent 与 A2A 委派](/zh/ai-sre/agents)，**扩展面不设上限** | SRE Agent 限于启停官方预置连接器（Datadog、Splunk、CloudWatch 等约 23 个）与追加提示词式 Skill；不支持为自家 Agent 挂载任意 MCP 工具，无子 Agent 派生，跨厂商 Agent 协作尚在 early access | -| **知识与记忆** | [知识库](/zh/ai-sre/knowledge)（DUTY.md + 文件引用）、[自动记忆提炼](/zh/ai-sre/memory)，`/init` 可导入 Claude Code、Cursor 等工具的已有知识 | 公开资料未见 | +| **知识与记忆** | [知识](/zh/ai-sre/knowledge)（DUTY.md + 文件引用）、[自动记忆提炼](/zh/ai-sre/memory)，`/init` 可导入 Claude Code、Cursor 等工具的已有知识 | 公开资料未见 | | **AI 复盘** | 故障复盘一键生成 + 自动化定时复盘 | 复盘（原 Jeli，正并入主产品）随 Professional 及以上提供，Professional/Business 档限每年 300 次 | | **使用洞察** | [/insight](/zh/ai-sre/insight) 复盘近 30 天 AI 使用情况，量化摩擦并给出改进建议 | 公开资料未见 | | **计费方式** | 按 credits 用量计费（1 credit = ¥1），开通免费，详见[官网价格页](https://www.flashduty.com/zh/pricing) | AIOps 单独加购（\$699+/月起，按事件量计费）；各套餐含一次性 AI Actions 额度（Professional 1,000 / Business 5,000 / Enterprise 20,000 次），SRE Agent 查询、Scribe 会议按次扣点，超额需加购 | From f62af9d27cce49b2209526347c1cd3d8c17a2949 Mon Sep 17 00:00:00 2001 From: ysyneu Date: Mon, 5 Oct 2026 18:12:34 -0700 Subject: [PATCH 2/2] =?UTF-8?q?docs(api):=20name=20AI=20SRE=20knowledge=20?= =?UTF-8?q?endpoints=20Knowledge=20/=20=E7=9F=A5=E8=AF=86?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Replace the "knowledge pack" / 知识包 wording in the /safari/knowledge/* operation summaries, descriptions and schema field descriptions with Knowledge (en) and 知识 (zh), and update the matching api-catalog rows. Operation IDs, paths, slugs and schema keys are unchanged. --- api-reference/openapi.en.json | 166 +++++++++++++-------------- api-reference/openapi.zh.json | 162 +++++++++++++------------- api-reference/safari.openapi.en.json | 166 +++++++++++++-------------- api-reference/safari.openapi.zh.json | 162 +++++++++++++------------- en/openapi/api-catalog.mdx | 10 +- zh/openapi/api-catalog.mdx | 10 +- 6 files changed, 338 insertions(+), 338 deletions(-) diff --git a/api-reference/openapi.en.json b/api-reference/openapi.en.json index 5c2bdd216..7513b534f 100644 --- a/api-reference/openapi.en.json +++ b/api-reference/openapi.en.json @@ -5017,10 +5017,10 @@ "type": "object" }, "ContextResolvedItem": { - "description": "Snapshot of the three-tier knowledge-pack resolution for this session.", + "description": "Snapshot of the three-tier knowledge resolution for this session.", "properties": { "account_pack_id": { - "description": "Resolved account-scoped pack id.", + "description": "Resolved account-scope knowledge ID.", "type": "string" }, "incident_id": { @@ -5028,19 +5028,19 @@ "type": "string" }, "resolved_at_ms": { - "description": "Unix timestamp in milliseconds when the packs were resolved.", + "description": "Unix timestamp in milliseconds when the knowledge was resolved.", "format": "int64", "type": "integer" }, "team_pack_id": { - "description": "Resolved team-scoped pack id.", + "description": "Resolved team-scope knowledge ID.", "type": "string" }, "versions": { "additionalProperties": { "type": "integer" }, - "description": "Per-pack resolved version map.", + "description": "Resolved version map, one entry per knowledge.", "type": "object" } }, @@ -12829,18 +12829,18 @@ "type": "object" }, "KnowledgeFileDeleteRequest": { - "description": "File to remove from a knowledge pack.", + "description": "Knowledge file to remove.", "properties": { "force": { - "description": "Delete even when other pack files reference this file; the referrers are then returned as warnings instead of blocking the delete.", + "description": "Delete even when other knowledge files reference this file; the referrers are then returned as warnings instead of blocking the delete.", "type": "boolean" }, "pack_id": { - "description": "Knowledge pack ID; defaults to the caller's account-scope pack.", + "description": "Knowledge ID; defaults to the caller's account-scope knowledge.", "type": "string" }, "rel_path": { - "description": "Path of the file relative to the pack root.", + "description": "Path of the file relative to the knowledge root.", "type": "string" } }, @@ -12853,7 +12853,7 @@ "description": "Deletion result; empty unless warnings were raised.", "properties": { "warnings": { - "description": "Non-blocking warnings after deletion; `code=still_referenced_by` means the (force-)deleted file is still @ref-referenced by other files in the pack (`refs` lists the referrers). Absent when there are no warnings (omitempty).", + "description": "Non-blocking warnings after deletion; `code=still_referenced_by` means the (force-)deleted file is still @ref-referenced by other files in the knowledge (`refs` lists the referrers). Absent when there are no warnings (omitempty).", "items": { "$ref": "#/components/schemas/KnowledgeWarning" }, @@ -12866,11 +12866,11 @@ "description": "Which file to fetch.", "properties": { "pack_id": { - "description": "Knowledge pack ID; defaults to the caller's account-scope pack.", + "description": "Knowledge ID; defaults to the caller's account-scope knowledge.", "type": "string" }, "rel_path": { - "description": "Path of the file relative to the pack root.", + "description": "Path of the file relative to the knowledge root.", "type": "string" } }, @@ -12897,7 +12897,7 @@ "type": "object" }, "KnowledgeFileItem": { - "description": "Metadata of one file inside a knowledge pack. Content is fetched separately via file/get.", + "description": "Metadata of one knowledge file. Content is fetched separately via file/get.", "properties": { "checksum": { "description": "SHA-256 hex digest of the file content.", @@ -12912,11 +12912,11 @@ "type": "string" }, "pack_id": { - "description": "ID of the knowledge pack that contains the file.", + "description": "ID of the knowledge that contains the file.", "type": "string" }, "rel_path": { - "description": "Path relative to the pack root, e.g. `runbooks/restart.md`.", + "description": "Path relative to the knowledge root, e.g. `runbooks/restart.md`.", "type": "string" }, "size_bytes": { @@ -12948,7 +12948,7 @@ "type": "object" }, "KnowledgeFileListRequest": { - "description": "Which pack's files to list.", + "description": "Which knowledge's files to list.", "properties": { "limit": { "description": "Page size. Accepted but currently ignored — the response always contains the full file list.", @@ -12959,24 +12959,24 @@ "type": "integer" }, "pack_id": { - "description": "Knowledge pack ID; defaults to the caller's account-scope pack.", + "description": "Knowledge ID; defaults to the caller's account-scope knowledge.", "type": "string" } }, "type": "object" }, "KnowledgeFileListResponse": { - "description": "Files in the pack.", + "description": "Files in the knowledge.", "properties": { "files": { - "description": "Array of files in the specified knowledge pack; empty array when the pack has no files.", + "description": "Array of files in the specified knowledge; empty array when it has no files.", "items": { "$ref": "#/components/schemas/KnowledgeFileItem" }, "type": "array" }, "total": { - "description": "Total number of files in the pack.", + "description": "Total number of files in the knowledge.", "format": "int64", "type": "integer" } @@ -12999,11 +12999,11 @@ "type": "string" }, "pack_id": { - "description": "Knowledge pack ID; defaults to the caller's account-scope pack.", + "description": "Knowledge ID; defaults to the caller's account-scope knowledge.", "type": "string" }, "rel_path": { - "description": "Destination path relative to the pack root; existing files are overwritten.", + "description": "Destination path relative to the knowledge root; existing files are overwritten.", "type": "string" } }, @@ -13019,7 +13019,7 @@ "$ref": "#/components/schemas/KnowledgeFileItem" }, "warnings": { - "description": "Non-blocking warnings after a successful write; `code=unresolved_reference` means an @ref in the file content points to a file that does not exist in the pack. Absent when there are no warnings (omitempty).", + "description": "Non-blocking warnings after a successful write; `code=unresolved_reference` means an @ref in the file content points to a file that does not exist in the knowledge. Absent when there are no warnings (omitempty).", "items": { "$ref": "#/components/schemas/KnowledgeWarning" }, @@ -13032,15 +13032,15 @@ "type": "object" }, "KnowledgeGetRequest": { - "description": "No request fields — the account-scope pack is always targeted.", + "description": "No request fields — the account-scope knowledge is always targeted.", "properties": {}, "type": "object" }, "KnowledgeGetResponse": { - "description": "Account-scope pack metadata plus its file list.", + "description": "Account-scope knowledge metadata plus its file list.", "properties": { "files": { - "description": "Array of files in this knowledge pack; empty array when the pack has no files.", + "description": "Array of files in this knowledge; empty array when it has no files.", "items": { "$ref": "#/components/schemas/KnowledgeFileItem" }, @@ -13057,10 +13057,10 @@ "type": "object" }, "KnowledgePackDeleteRequest": { - "description": "Pack to delete.", + "description": "Knowledge to delete.", "properties": { "pack_id": { - "description": "Knowledge pack ID to delete.", + "description": "Knowledge ID to delete.", "type": "string" } }, @@ -13073,7 +13073,7 @@ "description": "Deletion result.", "properties": { "ok": { - "description": "True when the pack was deleted.", + "description": "True when the knowledge was deleted.", "type": "boolean" } }, @@ -13083,10 +13083,10 @@ "type": "object" }, "KnowledgePackEnsureRequest": { - "description": "Scope at which to ensure a knowledge pack exists.", + "description": "Scope at which to ensure knowledge exists.", "properties": { "scope": { - "description": "Scope of the pack to ensure. One of: `account` (account-level pack; scope_id is forced to the caller's account ID and only account admins may create it; first creation seeds a default DUTY.md), `team` (team-level pack; the `scope_id` team ID is required and the caller must belong to that team).", + "description": "Scope of the knowledge to ensure. One of: `account` (account-level knowledge; scope_id is forced to the caller's account ID and only account admins may create it; first creation seeds a default DUTY.md), `team` (team-level knowledge; the `scope_id` team ID is required and the caller must belong to that team).", "enum": [ "account", "team" @@ -13105,41 +13105,41 @@ "type": "object" }, "KnowledgePackItem": { - "description": "A knowledge pack — a versioned file tree staged into every AI SRE sandbox at session start. One pack exists per (account, scope, scope_id).", + "description": "Knowledge — a versioned file tree staged into every AI SRE sandbox at session start. One knowledge exists per (account, scope, scope_id).", "properties": { "account_id": { - "description": "Account that owns the pack.", + "description": "Account that owns the knowledge.", "format": "int64", "type": "integer" }, "can_edit": { - "description": "Whether the caller can edit this pack.", + "description": "Whether the caller can edit this knowledge.", "type": "boolean" }, "created_at_ms": { - "description": "Unix timestamp in milliseconds when the pack was created.", + "description": "Unix timestamp in milliseconds when the knowledge was created.", "format": "int64", "type": "integer" }, "created_by": { - "description": "Person ID of the member who created the pack.", + "description": "Person ID of the member who created the knowledge.", "format": "int64", "type": "integer" }, "duty_version": { - "description": "Pack version at which DUTY.md was last authored or re-affirmed. When `version` is greater, DUTY.md no longer reflects every file in the pack.", + "description": "Knowledge version at which DUTY.md was last authored or re-affirmed. When `version` is greater, DUTY.md no longer reflects every file in the knowledge.", "type": "integer" }, "file_count": { - "description": "Number of files in the pack.", + "description": "Number of files in the knowledge.", "type": "integer" }, "pack_id": { - "description": "Knowledge pack ID (`kpk_` prefix).", + "description": "Knowledge ID (`kpk_` prefix).", "type": "string" }, "scope": { - "description": "Pack scope. `channel` is a legacy scope; new packs are `account` or `team`.", + "description": "Knowledge scope. `channel` is a legacy scope; new knowledge is `account` or `team` scope.", "enum": [ "account", "team", @@ -13162,12 +13162,12 @@ "type": "integer" }, "updated_at_ms": { - "description": "Unix timestamp in milliseconds when the pack was last modified.", + "description": "Unix timestamp in milliseconds when the knowledge was last modified.", "format": "int64", "type": "integer" }, "version": { - "description": "Pack version, incremented on every file change.", + "description": "Knowledge version, incremented on every file change.", "type": "integer" } }, @@ -13188,10 +13188,10 @@ "type": "object" }, "KnowledgePackListRequest": { - "description": "Filter and pagination for the pack list.", + "description": "Filter and pagination for the knowledge list.", "properties": { "include_account": { - "description": "Include the account-scope pack; defaults to true.", + "description": "Include the account-scope knowledge; defaults to true.", "type": [ "boolean", "null" @@ -13206,12 +13206,12 @@ "type": "integer" }, "query": { - "description": "Case-insensitive substring filter over pack ID, scope, scope ID/account ID, and team name.", + "description": "Case-insensitive substring filter over knowledge ID, scope, scope ID/account ID, and team name.", "maxLength": 128, "type": "string" }, "scope": { - "description": "Restrict to one scope; `all` (default) overrides `include_account`. One of: `all` (account scope plus visible team scopes), `account` (account-level packs only), `team` (team-level packs only, can be combined with `team_ids`).", + "description": "Restrict to one scope; `all` (default) overrides `include_account`. One of: `all` (account scope plus visible team scopes), `account` (account-level knowledge only), `team` (team-level knowledge only, can be combined with `team_ids`).", "enum": [ "all", "account", @@ -13231,17 +13231,17 @@ "type": "object" }, "KnowledgePackListResponse": { - "description": "Visible packs and the total after filtering.", + "description": "Visible knowledge and the total after filtering.", "properties": { "packs": { - "description": "Array of visible knowledge packs after filtering (current page), used with `total` for pagination.", + "description": "Array of visible knowledge after filtering (current page), used with `total` for pagination.", "items": { "$ref": "#/components/schemas/KnowledgePackItem" }, "type": "array" }, "total": { - "description": "Total number of packs after filtering, before pagination.", + "description": "Total number of knowledge entries after filtering, before pagination.", "format": "int64", "type": "integer" } @@ -13253,14 +13253,14 @@ "type": "object" }, "KnowledgePackUpdateRequest": { - "description": "Move a knowledge pack to a different scope.", + "description": "Move knowledge to a different scope.", "properties": { "pack_id": { - "description": "Knowledge pack ID to update.", + "description": "Knowledge ID to update.", "type": "string" }, "scope": { - "description": "Destination scope; omit for a no-op that returns the current pack.", + "description": "Destination scope; omit for a no-op that returns the current knowledge.", "enum": [ "account", "team" @@ -13288,7 +13288,7 @@ "description": "Non-blocking annotation returned by file uploads and deletions, e.g. references that point at a removed file.", "properties": { "code": { - "description": "Warning code. One of: `unresolved_reference` (an @ref in the written file's content points to a file that does not exist in the pack; `ref` carries it), `still_referenced_by` (the deleted file is still @ref-referenced by other files in the pack; `refs` lists the referrers).", + "description": "Warning code. One of: `unresolved_reference` (an @ref in the written file's content points to a file that does not exist in the knowledge; `ref` carries it), `still_referenced_by` (the deleted file is still @ref-referenced by other files in the knowledge; `refs` lists the referrers).", "enum": [ "unresolved_reference", "still_referenced_by" @@ -23757,7 +23757,7 @@ "$ref": "#/components/schemas/SessionItem" }, "suggest_init": { - "description": "Account-wide onboarding flag: true when the account has zero knowledge packs in any scope; not specific to this session.", + "description": "Account-wide onboarding flag: true when the account has no knowledge in any scope; not specific to this session.", "type": "boolean" }, "pending_messages": { @@ -24111,7 +24111,7 @@ "type": "array" }, "suggest_init": { - "description": "Account-wide onboarding flag: true when the account has zero knowledge packs in any scope; not dependent on this call's filters.", + "description": "Account-wide onboarding flag: true when the account has no knowledge in any scope; not dependent on this call's filters.", "type": "boolean" }, "total": { @@ -52619,7 +52619,7 @@ }, "/safari/knowledge/file/delete": { "post": { - "description": "Delete a file from a knowledge pack by its relative path.", + "description": "Delete a knowledge file by its relative path.", "operationId": "knowledge-file-write-delete", "requestBody": { "content": { @@ -52687,7 +52687,7 @@ "AI SRE/Knowledge" ], "x-mint": { - "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Knowledge Manage** (`ai-sre`) |\n\n## Usage\n\n- Deleting is idempotent — removing a file that does not exist succeeds.\n- When other pack files still reference the target, the delete fails with `ReferenceExist` listing the referrers; set `force` to proceed (the referrers are returned as warnings).\n- Omitting `pack_id` targets the account-scope pack; editing the account pack requires account owner/admin, editing a team pack requires team membership.\n- Every call is recorded in the account audit log.\n", + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Knowledge Manage** (`ai-sre`) |\n\n## Usage\n\n- Deleting is idempotent — removing a file that does not exist succeeds.\n- When other knowledge files still reference the target, the delete fails with `ReferenceExist` listing the referrers; set `force` to proceed (the referrers are returned as warnings).\n- Omitting `pack_id` targets the account-scope knowledge; editing the account knowledge requires account owner/admin, editing team knowledge requires team membership.\n- Every call is recorded in the account audit log.\n", "href": "/en/api-reference/ai-sre/knowledge/knowledge-file-write-delete", "metadata": { "sidebarTitle": "Delete knowledge file" @@ -52774,7 +52774,7 @@ "AI SRE/Knowledge" ], "x-mint": { - "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Content is returned in `content_b64` (base64); pack files are guaranteed UTF-8 text.\n- Omitting `pack_id` targets the account-scope pack; reading a team-scope pack requires team membership.\n- A missing file returns `ResourceNotFound` (HTTP 400).\n", + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Content is returned in `content_b64` (base64); knowledge files are guaranteed UTF-8 text.\n- Omitting `pack_id` targets the account-scope knowledge; reading team-scope knowledge requires team membership.\n- A missing file returns `ResourceNotFound` (HTTP 400).\n", "href": "/en/api-reference/ai-sre/knowledge/knowledge-file-read-get", "metadata": { "sidebarTitle": "Get knowledge file" @@ -52784,7 +52784,7 @@ }, "/safari/knowledge/file/list": { "post": { - "description": "List the files in a knowledge pack with metadata such as size and checksum.", + "description": "List knowledge files with metadata such as size and checksum.", "operationId": "knowledge-file-read-list", "requestBody": { "content": { @@ -52873,7 +52873,7 @@ "AI SRE/Knowledge" ], "x-mint": { - "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Omitting `pack_id` targets the caller's account-scope pack (created lazily if absent).\n- Reading a team-scope pack requires membership of that team.\n- `p`/`limit` are accepted but the current implementation always returns the full file list.\n", + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Omitting `pack_id` targets the caller's account-scope knowledge (created lazily if absent).\n- Reading team-scope knowledge requires membership of that team.\n- `p`/`limit` are accepted but the current implementation always returns the full file list.\n", "href": "/en/api-reference/ai-sre/knowledge/knowledge-file-read-list", "metadata": { "sidebarTitle": "List knowledge files" @@ -52883,7 +52883,7 @@ }, "/safari/knowledge/file/put": { "post": { - "description": "Create or overwrite a file in a knowledge pack with base64-encoded content.", + "description": "Create or overwrite a knowledge file with base64-encoded content.", "operationId": "knowledge-file-write-put", "requestBody": { "content": { @@ -52964,7 +52964,7 @@ "AI SRE/Knowledge" ], "x-mint": { - "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Knowledge Manage** (`ai-sre`) |\n\n## Usage\n\n- The file body is sent as base64 text in the JSON field `content_b64` — this is not a multipart upload.\n- Writing an existing `rel_path` overwrites it; `content_type` is inferred from the extension when omitted (`.md` → `text/markdown`).\n- Content must decode to valid UTF-8 text; binary payloads are rejected with `InvalidParameter`.\n- Editing the account-scope pack requires account owner/admin; editing a team pack requires team membership.\n- Every call is recorded in the account audit log.\n", + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Knowledge Manage** (`ai-sre`) |\n\n## Usage\n\n- The file body is sent as base64 text in the JSON field `content_b64` — this is not a multipart upload.\n- Writing an existing `rel_path` overwrites it; `content_type` is inferred from the extension when omitted (`.md` → `text/markdown`).\n- Content must decode to valid UTF-8 text; binary payloads are rejected with `InvalidParameter`.\n- Editing the account-scope knowledge requires account owner/admin; editing team knowledge requires team membership.\n- Every call is recorded in the account audit log.\n", "href": "/en/api-reference/ai-sre/knowledge/knowledge-file-write-put", "metadata": { "sidebarTitle": "Upload knowledge file" @@ -52974,7 +52974,7 @@ }, "/safari/knowledge/get": { "post": { - "description": "Return the account-scope knowledge pack metadata and its file list.", + "description": "Return the metadata and file list of the account-scope knowledge.", "operationId": "knowledge-pack-read-get", "requestBody": { "content": { @@ -53069,22 +53069,22 @@ "AppKeyAuth": [] } ], - "summary": "Get account knowledge pack", + "summary": "Get account knowledge", "tags": [ "AI SRE/Knowledge" ], "x-mint": { - "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Always targets the caller's account-scope pack — there is no `pack_id` parameter; use `POST /safari/knowledge/pack/list` to discover team packs.\n- The account pack is created lazily on first access, so a valid account never gets not-found here.\n", + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Always targets the caller's account-scope knowledge — there is no `pack_id` parameter; use `POST /safari/knowledge/pack/list` to discover team knowledge.\n- The account knowledge is created lazily on first access, so a valid account never gets not-found here.\n", "href": "/en/api-reference/ai-sre/knowledge/knowledge-pack-read-get", "metadata": { - "sidebarTitle": "Get account knowledge pack" + "sidebarTitle": "Get account knowledge" } } } }, "/safari/knowledge/pack/delete": { "post": { - "description": "Delete a knowledge pack and all of its files.", + "description": "Delete knowledge and all of its files.", "operationId": "knowledge-pack-write-delete", "requestBody": { "content": { @@ -53149,22 +53149,22 @@ "AppKeyAuth": [] } ], - "summary": "Delete knowledge pack", + "summary": "Delete knowledge", "tags": [ "AI SRE/Knowledge" ], "x-mint": { - "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Knowledge Manage** (`ai-sre`) |\n\n## Usage\n\n- Deleting a pack removes every file it contains; the operation cannot be undone.\n- Deleting the account-scope pack is allowed; it is re-created empty on next access.\n- Every call is recorded in the account audit log.\n", + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Knowledge Manage** (`ai-sre`) |\n\n## Usage\n\n- Deleting knowledge removes every file it contains; the operation cannot be undone.\n- Deleting the account-scope knowledge is allowed; it is re-created empty on next access.\n- Every call is recorded in the account audit log.\n", "href": "/en/api-reference/ai-sre/knowledge/knowledge-pack-write-delete", "metadata": { - "sidebarTitle": "Delete knowledge pack" + "sidebarTitle": "Delete knowledge" } } } }, "/safari/knowledge/pack/ensure": { "post": { - "description": "Idempotently create the knowledge pack at the given scope, or return the existing one.", + "description": "Idempotently create the knowledge at the given scope, or return the existing one.", "operationId": "knowledge-pack-write-ensure", "requestBody": { "content": { @@ -53241,22 +53241,22 @@ "AppKeyAuth": [] } ], - "summary": "Ensure knowledge pack", + "summary": "Ensure knowledge", "tags": [ "AI SRE/Knowledge" ], "x-mint": { - "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Knowledge Manage** (`ai-sre`) |\n\n## Usage\n\n- Idempotent: if a pack already exists at (`scope`, `scope_id`), it is returned unchanged.\n- For `account` scope, `scope_id` is ignored (the account ID is used) and a default `DUTY.md` is seeded on first creation.\n- Creating the account-scope pack requires account owner/admin; creating into a team requires membership of that team.\n- Every call is recorded in the account audit log.\n", + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Knowledge Manage** (`ai-sre`) |\n\n## Usage\n\n- Idempotent: if knowledge already exists at (`scope`, `scope_id`), it is returned unchanged.\n- For `account` scope, `scope_id` is ignored (the account ID is used) and a default `DUTY.md` is seeded on first creation.\n- Creating the account-scope knowledge requires account owner/admin; creating into a team requires membership of that team.\n- Every call is recorded in the account audit log.\n", "href": "/en/api-reference/ai-sre/knowledge/knowledge-pack-write-ensure", "metadata": { - "sidebarTitle": "Ensure knowledge pack" + "sidebarTitle": "Ensure knowledge" } } } }, "/safari/knowledge/pack/list": { "post": { - "description": "List knowledge packs visible to the caller across account and team scopes.", + "description": "List the knowledge visible to the caller across account and team scopes.", "operationId": "knowledge-pack-read-list", "requestBody": { "content": { @@ -53352,22 +53352,22 @@ "AppKeyAuth": [] } ], - "summary": "List knowledge packs", + "summary": "List knowledge", "tags": [ "AI SRE/Knowledge" ], "x-mint": { - "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Visibility matches the console: admins see the account pack plus every team pack; non-admins see the account pack plus their own teams, and requested `team_ids` are silently intersected with their teams.\n- `scope` selects `all` (default), `account`-only, or `team`-only, overriding `include_account`.\n- `query` applies a case-insensitive substring filter over pack ID, scope, and team name; `p`/`limit` paginate the filtered result.\n", + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Visibility matches the console: admins see the account knowledge plus every team's knowledge; non-admins see the account knowledge plus their own teams' knowledge, and requested `team_ids` are silently intersected with their teams.\n- `scope` selects `all` (default), `account`-only, or `team`-only, overriding `include_account`.\n- `query` applies a case-insensitive substring filter over knowledge ID, scope, and team name; `p`/`limit` paginate the filtered result.\n", "href": "/en/api-reference/ai-sre/knowledge/knowledge-pack-read-list", "metadata": { - "sidebarTitle": "List knowledge packs" + "sidebarTitle": "List knowledge" } } } }, "/safari/knowledge/pack/update": { "post": { - "description": "Move a knowledge pack to a different account or team scope.", + "description": "Move knowledge to a different account or team scope.", "operationId": "knowledge-pack-write-update", "requestBody": { "content": { @@ -53446,15 +53446,15 @@ "AppKeyAuth": [] } ], - "summary": "Update knowledge pack", + "summary": "Update knowledge", "tags": [ "AI SRE/Knowledge" ], "x-mint": { - "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Knowledge Manage** (`ai-sre`) |\n\n## Usage\n\n- `scope` is the only mutable field; omitting it is a no-op that returns the current pack.\n- For `team` scope, `scope_id` is required; for `account` scope it is set to the account ID automatically.\n- The move fails with `ReferenceExist` when the destination scope already has a pack — packs are never merged.\n- Every call is recorded in the account audit log.\n", + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Knowledge Manage** (`ai-sre`) |\n\n## Usage\n\n- `scope` is the only mutable field; omitting it is a no-op that returns the current knowledge.\n- For `team` scope, `scope_id` is required; for `account` scope it is set to the account ID automatically.\n- The move fails with `ReferenceExist` when the destination scope already has knowledge — knowledge is never merged.\n- Every call is recorded in the account audit log.\n", "href": "/en/api-reference/ai-sre/knowledge/knowledge-pack-write-update", "metadata": { - "sidebarTitle": "Update knowledge pack" + "sidebarTitle": "Update knowledge" } } } @@ -54491,7 +54491,7 @@ "AI SRE/Sessions" ], "x-mint": { - "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Pagination uses `p`/`limit` (max 100); `scope` defaults to `all`.\n- `all` returns your personal sessions plus team sessions you can access; account admins see all team sessions, but not other users' personal sessions.\n- `team_ids` narrows the visible set and never expands access.\n- `is_running` reflects the live run-set; `has_unread` is computed per calling user; the `current_turn_*` fields are always zero here — only `session/get` computes them while a session is running.\n- `suggest_init` is an account-wide onboarding flag (true only when the account has zero knowledge packs anywhere) — it doesn't depend on the list filters.\n", + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Pagination uses `p`/`limit` (max 100); `scope` defaults to `all`.\n- `all` returns your personal sessions plus team sessions you can access; account admins see all team sessions, but not other users' personal sessions.\n- `team_ids` narrows the visible set and never expands access.\n- `is_running` reflects the live run-set; `has_unread` is computed per calling user; the `current_turn_*` fields are always zero here — only `session/get` computes them while a session is running.\n- `suggest_init` is an account-wide onboarding flag (true only when the account has no knowledge in any scope) — it doesn't depend on the list filters.\n", "href": "/en/api-reference/ai-sre/sessions/session-read-list", "metadata": { "sidebarTitle": "List sessions" diff --git a/api-reference/openapi.zh.json b/api-reference/openapi.zh.json index afedef7f7..fff8dc46f 100644 --- a/api-reference/openapi.zh.json +++ b/api-reference/openapi.zh.json @@ -5017,10 +5017,10 @@ "type": "object" }, "ContextResolvedItem": { - "description": "该会话三层知识包解析结果的快照。", + "description": "该会话三层知识解析结果的快照。", "properties": { "account_pack_id": { - "description": "解析出的账户级知识包 ID。", + "description": "解析出的账户级知识 ID。", "type": "string" }, "incident_id": { @@ -5028,19 +5028,19 @@ "type": "string" }, "resolved_at_ms": { - "description": "知识包解析时间，Unix 毫秒时间戳。", + "description": "知识解析时间，Unix 毫秒时间戳。", "format": "int64", "type": "integer" }, "team_pack_id": { - "description": "解析出的团队级知识包 ID。", + "description": "解析出的团队级知识 ID。", "type": "string" }, "versions": { "additionalProperties": { "type": "integer" }, - "description": "各知识包解析版本映射。", + "description": "各份知识的解析版本映射。", "type": "object" } }, @@ -12829,18 +12829,18 @@ "type": "object" }, "KnowledgeFileDeleteRequest": { - "description": "要从知识包中删除的文件。", + "description": "要删除的知识文件。", "properties": { "force": { - "description": "即使其他包内文件仍引用该文件也强制删除；此时引用方会以警告形式返回，而不再阻止删除。", + "description": "即使其他知识文件仍引用该文件也强制删除；此时引用方会以警告形式返回，而不再阻止删除。", "type": "boolean" }, "pack_id": { - "description": "知识包 ID；默认为调用者的账户范围知识包。", + "description": "知识 ID；默认为调用者的账户范围知识。", "type": "string" }, "rel_path": { - "description": "文件相对于知识包根目录的路径。", + "description": "文件相对于知识根目录的路径。", "type": "string" } }, @@ -12853,7 +12853,7 @@ "description": "删除结果；无警告时为空对象。", "properties": { "warnings": { - "description": "删除后的非阻塞警告数组；`code=still_referenced_by` 表示被（强制）删除的文件仍被包内其他文件 @ref 引用（`refs` 列出引用方）。无警告时该字段缺省（omitempty）。", + "description": "删除后的非阻塞警告数组；`code=still_referenced_by` 表示被（强制）删除的文件仍被知识内其他文件 @ref 引用（`refs` 列出引用方）。无警告时该字段缺省（omitempty）。", "items": { "$ref": "#/components/schemas/KnowledgeWarning" }, @@ -12866,11 +12866,11 @@ "description": "要获取的文件。", "properties": { "pack_id": { - "description": "知识包 ID；默认为调用者的账户范围知识包。", + "description": "知识 ID；默认为调用者的账户范围知识。", "type": "string" }, "rel_path": { - "description": "文件相对于知识包根目录的路径。", + "description": "文件相对于知识根目录的路径。", "type": "string" } }, @@ -12897,7 +12897,7 @@ "type": "object" }, "KnowledgeFileItem": { - "description": "知识包内单个文件的元数据；文件内容需通过 file/get 单独获取。", + "description": "单个知识文件的元数据；文件内容需通过 file/get 单独获取。", "properties": { "checksum": { "description": "文件内容的 SHA-256 十六进制摘要。", @@ -12912,11 +12912,11 @@ "type": "string" }, "pack_id": { - "description": "文件所属的知识包 ID。", + "description": "文件所属的知识 ID。", "type": "string" }, "rel_path": { - "description": "相对于知识包根目录的路径，如 `runbooks/restart.md`。", + "description": "相对于知识根目录的路径，如 `runbooks/restart.md`。", "type": "string" }, "size_bytes": { @@ -12948,7 +12948,7 @@ "type": "object" }, "KnowledgeFileListRequest": { - "description": "要列出文件的知识包。", + "description": "要列出文件的知识。", "properties": { "limit": { "description": "每页条数。目前接受但忽略——响应始终返回完整文件列表。", @@ -12959,24 +12959,24 @@ "type": "integer" }, "pack_id": { - "description": "知识包 ID；默认为调用者的账户范围知识包。", + "description": "知识 ID；默认为调用者的账户范围知识。", "type": "string" } }, "type": "object" }, "KnowledgeFileListResponse": { - "description": "知识包内的文件。", + "description": "知识内的文件。", "properties": { "files": { - "description": "指定知识包内的文件数组；无文件时为空数组。", + "description": "指定知识内的文件数组；无文件时为空数组。", "items": { "$ref": "#/components/schemas/KnowledgeFileItem" }, "type": "array" }, "total": { - "description": "知识包内文件总数。", + "description": "知识内文件总数。", "format": "int64", "type": "integer" } @@ -12999,11 +12999,11 @@ "type": "string" }, "pack_id": { - "description": "知识包 ID；默认为调用者的账户范围知识包。", + "description": "知识 ID；默认为调用者的账户范围知识。", "type": "string" }, "rel_path": { - "description": "相对于知识包根目录的目标路径；已存在的文件会被覆盖。", + "description": "相对于知识根目录的目标路径；已存在的文件会被覆盖。", "type": "string" } }, @@ -13019,7 +13019,7 @@ "$ref": "#/components/schemas/KnowledgeFileItem" }, "warnings": { - "description": "写入成功后的非阻塞警告数组；`code=unresolved_reference` 表示文件内容中的 @ref 引用了包内不存在的文件。无警告时该字段缺省（omitempty）。", + "description": "写入成功后的非阻塞警告数组；`code=unresolved_reference` 表示文件内容中的 @ref 引用了知识内不存在的文件。无警告时该字段缺省（omitempty）。", "items": { "$ref": "#/components/schemas/KnowledgeWarning" }, @@ -13032,15 +13032,15 @@ "type": "object" }, "KnowledgeGetRequest": { - "description": "无请求字段——固定查询账户范围知识包。", + "description": "无请求字段——固定查询账户范围知识。", "properties": {}, "type": "object" }, "KnowledgeGetResponse": { - "description": "账户范围知识包元数据及其文件列表。", + "description": "账户范围知识元数据及其文件列表。", "properties": { "files": { - "description": "该知识包内的文件数组；无文件时为空数组。", + "description": "该知识内的文件数组；无文件时为空数组。", "items": { "$ref": "#/components/schemas/KnowledgeFileItem" }, @@ -13057,10 +13057,10 @@ "type": "object" }, "KnowledgePackDeleteRequest": { - "description": "要删除的知识包。", + "description": "要删除的知识。", "properties": { "pack_id": { - "description": "要删除的知识包 ID。", + "description": "要删除的知识 ID。", "type": "string" } }, @@ -13073,7 +13073,7 @@ "description": "删除结果。", "properties": { "ok": { - "description": "知识包删除成功时为 true。", + "description": "知识删除成功时为 true。", "type": "boolean" } }, @@ -13083,10 +13083,10 @@ "type": "object" }, "KnowledgePackEnsureRequest": { - "description": "要确保存在知识包的范围。", + "description": "要确保存在知识的范围。", "properties": { "scope": { - "description": "知识包范围。可选值：`account`（账户级知识包，scope_id 固定为调用方账户 ID，仅账户管理员可创建；首次创建会播种默认 DUTY.md）、`team`（团队级知识包，必须提供 `scope_id` 团队 ID，调用者需属于该团队）。", + "description": "知识范围。可选值：`account`（账户级知识，scope_id 固定为调用方账户 ID，仅账户管理员可创建；首次创建会播种默认 DUTY.md）、`team`（团队级知识，必须提供 `scope_id` 团队 ID，调用者需属于该团队）。", "enum": [ "account", "team" @@ -13105,15 +13105,15 @@ "type": "object" }, "KnowledgePackItem": { - "description": "知识包——一棵带版本号的文件树，AI SRE 会话启动时会注入到每个沙箱中。每个（账户, scope, scope_id）仅有一个知识包。", + "description": "知识——一棵带版本号的文件树，AI SRE 会话启动时会注入到每个沙箱中。每个（账户, scope, scope_id）仅有一份知识。", "properties": { "account_id": { - "description": "知识包所属账户 ID。", + "description": "知识所属账户 ID。", "format": "int64", "type": "integer" }, "can_edit": { - "description": "调用者是否有权限编辑该知识包。", + "description": "调用者是否有权限编辑该知识。", "type": "boolean" }, "created_at_ms": { @@ -13127,19 +13127,19 @@ "type": "integer" }, "duty_version": { - "description": "最后一次撰写或确认 DUTY.md 时的知识库版本。当 `version` 大于该值时，说明 DUTY.md 已不能反映知识库的全部文件。", + "description": "最后一次撰写或确认 DUTY.md 时的知识版本。当 `version` 大于该值时，说明 DUTY.md 已不能反映知识的全部文件。", "type": "integer" }, "file_count": { - "description": "包内文件数量。", + "description": "知识内文件数量。", "type": "integer" }, "pack_id": { - "description": "知识包 ID（`kpk_` 前缀）。", + "description": "知识 ID（`kpk_` 前缀）。", "type": "string" }, "scope": { - "description": "知识包范围；`channel` 为历史遗留范围，新建知识包为 `account` 或 `team`。", + "description": "知识范围；`channel` 为历史遗留范围，新建知识为 `account` 或 `team`。", "enum": [ "account", "team", @@ -13157,7 +13157,7 @@ "type": "string" }, "total_bytes": { - "description": "包内所有文件的总字节数。", + "description": "知识内所有文件的总字节数。", "format": "int64", "type": "integer" }, @@ -13167,7 +13167,7 @@ "type": "integer" }, "version": { - "description": "知识包版本号，文件每次变更时递增。", + "description": "知识版本号，文件每次变更时递增。", "type": "integer" } }, @@ -13188,10 +13188,10 @@ "type": "object" }, "KnowledgePackListRequest": { - "description": "知识包列表的过滤与分页参数。", + "description": "知识列表的过滤与分页参数。", "properties": { "include_account": { - "description": "是否包含账户范围的知识包；默认为 true。", + "description": "是否包含账户范围的知识；默认为 true。", "type": [ "boolean", "null" @@ -13206,12 +13206,12 @@ "type": "integer" }, "query": { - "description": "对知识包 ID、范围、范围 ID/账户 ID 和团队名称做大小写不敏感的子串过滤。", + "description": "对知识 ID、范围、范围 ID/账户 ID 和团队名称做大小写不敏感的子串过滤。", "maxLength": 128, "type": "string" }, "scope": { - "description": "限定范围；`all`（默认）会覆盖 `include_account`。可选值：`all`（账户范围 + 可见团队范围）、`account`（仅账户级知识包）、`team`（仅团队级知识包，可配合 `team_ids` 过滤）。", + "description": "限定范围；`all`（默认）会覆盖 `include_account`。可选值：`all`（账户范围 + 可见团队范围）、`account`（仅账户级知识）、`team`（仅团队级知识，可配合 `team_ids` 过滤）。", "enum": [ "all", "account", @@ -13231,17 +13231,17 @@ "type": "object" }, "KnowledgePackListResponse": { - "description": "可见的知识包及过滤后的总数。", + "description": "可见的知识及过滤后的总数。", "properties": { "packs": { - "description": "过滤后当前可见的知识包数组（当前页），与 `total` 配合分页。", + "description": "过滤后当前可见的知识数组（当前页），与 `total` 配合分页。", "items": { "$ref": "#/components/schemas/KnowledgePackItem" }, "type": "array" }, "total": { - "description": "过滤后、分页前的知识包总数。", + "description": "过滤后、分页前的知识总数。", "format": "int64", "type": "integer" } @@ -13253,14 +13253,14 @@ "type": "object" }, "KnowledgePackUpdateRequest": { - "description": "将知识包移动到其他范围。", + "description": "将知识移动到其他范围。", "properties": { "pack_id": { - "description": "要更新的知识包 ID。", + "description": "要更新的知识 ID。", "type": "string" }, "scope": { - "description": "目标范围；不传则为空操作，返回当前知识包。", + "description": "目标范围；不传则为空操作，返回当前知识。", "enum": [ "account", "team" @@ -13288,7 +13288,7 @@ "description": "文件上传/删除返回的非阻塞提示，例如指向已删除文件的引用。", "properties": { "code": { - "description": "提示码。可选值：`unresolved_reference`（写入的文件内容中 @ref 引用了包内不存在的文件，`ref` 给出该引用）、`still_referenced_by`（被删除的文件仍被包内其他文件 @ref 引用，`refs` 列出引用方）。", + "description": "提示码。可选值：`unresolved_reference`（写入的文件内容中 @ref 引用了知识内不存在的文件，`ref` 给出该引用）、`still_referenced_by`（被删除的文件仍被知识内其他文件 @ref 引用，`refs` 列出引用方）。", "enum": [ "unresolved_reference", "still_referenced_by" @@ -23757,7 +23757,7 @@ "$ref": "#/components/schemas/SessionItem" }, "suggest_init": { - "description": "账户级引导标志：当账户在任何范围内都没有知识包时为 true；并非该会话独有的属性。", + "description": "账户级引导标志：当账户在任何范围内都没有知识时为 true；并非该会话独有的属性。", "type": "boolean" }, "pending_messages": { @@ -24111,7 +24111,7 @@ "type": "array" }, "suggest_init": { - "description": "账户级引导标志：当账户在任何范围内都没有知识包时为 true；与本次调用的过滤条件无关。", + "description": "账户级引导标志：当账户在任何范围内都没有知识时为 true；与本次调用的过滤条件无关。", "type": "boolean" }, "total": { @@ -52619,7 +52619,7 @@ }, "/safari/knowledge/file/delete": { "post": { - "description": "按相对路径删除知识包中的文件。", + "description": "按相对路径删除知识文件。", "operationId": "knowledge-file-write-delete", "requestBody": { "content": { @@ -52687,7 +52687,7 @@ "AI SRE/知识" ], "x-mint": { - "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **知识库管理**（`ai-sre`） |\n\n## 使用说明\n\n- 删除是幂等的——删除不存在的文件也会成功。\n- 当其他包内文件仍引用目标文件时，删除失败并返回 `ReferenceExist`（附带引用方列表）；设置 `force` 可强制删除（引用方以警告形式返回）。\n- 不传 `pack_id` 时默认账户范围知识包；编辑账户包需要账户 Owner/Admin 权限，编辑团队包需要是该团队成员。\n- 每次调用都会记录到账户审计日志。\n", + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **知识管理**（`ai-sre`） |\n\n## 使用说明\n\n- 删除是幂等的——删除不存在的文件也会成功。\n- 当其他知识文件仍引用目标文件时，删除失败并返回 `ReferenceExist`（附带引用方列表）；设置 `force` 可强制删除（引用方以警告形式返回）。\n- 不传 `pack_id` 时默认账户范围知识；编辑账户知识需要账户 Owner/Admin 权限，编辑团队知识需要是该团队成员。\n- 每次调用都会记录到账户审计日志。\n", "href": "/zh/api-reference/ai-sre/knowledge/knowledge-file-write-delete", "metadata": { "sidebarTitle": "删除知识文件" @@ -52774,7 +52774,7 @@ "AI SRE/知识" ], "x-mint": { - "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 文件内容通过 `content_b64`（Base64）返回；知识包文件保证为 UTF-8 文本。\n- 不传 `pack_id` 时默认账户范围知识包；读取团队范围知识包需要是该团队成员。\n- 文件不存在时返回 `ResourceNotFound`（HTTP 400）。\n", + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 文件内容通过 `content_b64`（Base64）返回；知识文件保证为 UTF-8 文本。\n- 不传 `pack_id` 时默认账户范围知识；读取团队范围知识需要是该团队成员。\n- 文件不存在时返回 `ResourceNotFound`（HTTP 400）。\n", "href": "/zh/api-reference/ai-sre/knowledge/knowledge-file-read-get", "metadata": { "sidebarTitle": "获取知识文件" @@ -52784,7 +52784,7 @@ }, "/safari/knowledge/file/list": { "post": { - "description": "查询知识包内的文件列表，包含大小、校验和等元数据。", + "description": "查询知识文件列表，包含大小、校验和等元数据。", "operationId": "knowledge-file-read-list", "requestBody": { "content": { @@ -52873,7 +52873,7 @@ "AI SRE/知识" ], "x-mint": { - "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 不传 `pack_id` 时默认查询调用者的账户范围知识包（不存在时惰性创建）。\n- 读取团队范围知识包需要是该团队成员。\n- `p`/`limit` 参数会被接受，但当前实现始终返回完整文件列表。\n", + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 不传 `pack_id` 时默认查询调用者的账户范围知识（不存在时惰性创建）。\n- 读取团队范围知识需要是该团队成员。\n- `p`/`limit` 参数会被接受，但当前实现始终返回完整文件列表。\n", "href": "/zh/api-reference/ai-sre/knowledge/knowledge-file-read-list", "metadata": { "sidebarTitle": "查询知识文件列表" @@ -52883,7 +52883,7 @@ }, "/safari/knowledge/file/put": { "post": { - "description": "以 Base64 编码的内容在知识包中创建或覆盖文件。", + "description": "以 Base64 编码的内容创建或覆盖知识文件。", "operationId": "knowledge-file-write-put", "requestBody": { "content": { @@ -52964,7 +52964,7 @@ "AI SRE/知识" ], "x-mint": { - "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **知识库管理**（`ai-sre`） |\n\n## 使用说明\n\n- 文件内容以 JSON 字段 `content_b64` 中的 Base64 文本上传——不是 multipart 上传。\n- 写入已存在的 `rel_path` 会覆盖原文件；`content_type` 留空时按扩展名推断（`.md` → `text/markdown`）。\n- 内容解码后必须是合法的 UTF-8 文本，二进制内容会被拒绝并返回 `InvalidParameter`。\n- 编辑账户范围知识包需要账户 Owner/Admin 权限；编辑团队知识包需要是该团队成员。\n- 每次调用都会记录到账户审计日志。\n", + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **知识管理**（`ai-sre`） |\n\n## 使用说明\n\n- 文件内容以 JSON 字段 `content_b64` 中的 Base64 文本上传——不是 multipart 上传。\n- 写入已存在的 `rel_path` 会覆盖原文件；`content_type` 留空时按扩展名推断（`.md` → `text/markdown`）。\n- 内容解码后必须是合法的 UTF-8 文本，二进制内容会被拒绝并返回 `InvalidParameter`。\n- 编辑账户范围知识需要账户 Owner/Admin 权限；编辑团队知识需要是该团队成员。\n- 每次调用都会记录到账户审计日志。\n", "href": "/zh/api-reference/ai-sre/knowledge/knowledge-file-write-put", "metadata": { "sidebarTitle": "上传知识文件" @@ -52974,7 +52974,7 @@ }, "/safari/knowledge/get": { "post": { - "description": "返回账户范围知识包的元数据及其文件列表。", + "description": "返回账户范围知识的元数据及其文件列表。", "operationId": "knowledge-pack-read-get", "requestBody": { "content": { @@ -53069,22 +53069,22 @@ "AppKeyAuth": [] } ], - "summary": "查看账户知识包", + "summary": "查看账户知识", "tags": [ "AI SRE/知识" ], "x-mint": { - "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 固定返回调用者的账户范围知识包——没有 `pack_id` 参数；如需团队知识包请使用 `POST /safari/knowledge/pack/list`。\n- 账户知识包在首次访问时惰性创建，因此有效账户调用不会返回 not-found。\n", + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 固定返回调用者的账户范围知识——没有 `pack_id` 参数；如需团队知识请使用 `POST /safari/knowledge/pack/list`。\n- 账户知识在首次访问时惰性创建，因此有效账户调用不会返回 not-found。\n", "href": "/zh/api-reference/ai-sre/knowledge/knowledge-pack-read-get", "metadata": { - "sidebarTitle": "查看账户知识包" + "sidebarTitle": "查看账户知识" } } } }, "/safari/knowledge/pack/delete": { "post": { - "description": "删除知识包及其全部文件。", + "description": "删除知识及其全部文件。", "operationId": "knowledge-pack-write-delete", "requestBody": { "content": { @@ -53149,22 +53149,22 @@ "AppKeyAuth": [] } ], - "summary": "删除知识包", + "summary": "删除知识", "tags": [ "AI SRE/知识" ], "x-mint": { - "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **知识库管理**（`ai-sre`） |\n\n## 使用说明\n\n- 删除知识包会同时删除其中所有文件，且不可恢复。\n- 允许删除账户范围知识包；下次访问时会重新创建为空包。\n- 每次调用都会记录到账户审计日志。\n", + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **知识管理**（`ai-sre`） |\n\n## 使用说明\n\n- 删除知识会同时删除其中所有文件，且不可恢复。\n- 允许删除账户范围知识；下次访问时会重新创建一份空知识。\n- 每次调用都会记录到账户审计日志。\n", "href": "/zh/api-reference/ai-sre/knowledge/knowledge-pack-write-delete", "metadata": { - "sidebarTitle": "删除知识包" + "sidebarTitle": "删除知识" } } } }, "/safari/knowledge/pack/ensure": { "post": { - "description": "在指定范围幂等创建知识包，已存在时直接返回现有知识包。", + "description": "在指定范围幂等创建知识，已存在时直接返回现有知识。", "operationId": "knowledge-pack-write-ensure", "requestBody": { "content": { @@ -53241,22 +53241,22 @@ "AppKeyAuth": [] } ], - "summary": "确保知识包存在", + "summary": "确保知识存在", "tags": [ "AI SRE/知识" ], "x-mint": { - "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **知识库管理**（`ai-sre`） |\n\n## 使用说明\n\n- 幂等：若（`scope`, `scope_id`）已存在知识包，则原样返回。\n- 账户范围忽略 `scope_id`（使用账户 ID），首次创建时会自动写入默认 `DUTY.md`。\n- 创建账户范围知识包需要账户 Owner/Admin 权限；在团队下创建需要是该团队成员。\n- 每次调用都会记录到账户审计日志。\n", + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **知识管理**（`ai-sre`） |\n\n## 使用说明\n\n- 幂等：若（`scope`, `scope_id`）已存在知识，则原样返回。\n- 账户范围忽略 `scope_id`（使用账户 ID），首次创建时会自动写入默认 `DUTY.md`。\n- 创建账户范围知识需要账户 Owner/Admin 权限；在团队下创建需要是该团队成员。\n- 每次调用都会记录到账户审计日志。\n", "href": "/zh/api-reference/ai-sre/knowledge/knowledge-pack-write-ensure", "metadata": { - "sidebarTitle": "确保知识包存在" + "sidebarTitle": "确保知识存在" } } } }, "/safari/knowledge/pack/list": { "post": { - "description": "查询调用者可见的账户与团队范围知识包列表。", + "description": "查询调用者可见的账户与团队范围知识列表。", "operationId": "knowledge-pack-read-list", "requestBody": { "content": { @@ -53352,22 +53352,22 @@ "AppKeyAuth": [] } ], - "summary": "查询知识包列表", + "summary": "查询知识列表", "tags": [ "AI SRE/知识" ], "x-mint": { - "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 可见性与控制台一致：管理员可见账户包及全部团队包；非管理员可见账户包及所属团队包，传入的 `team_ids` 会被静默过滤为其所属团队。\n- `scope` 用于选择 `all`（默认）、仅 `account` 或仅 `team`，会覆盖 `include_account`。\n- `query` 对知识包 ID、范围和团队名称做大小写不敏感的子串过滤；`p`/`limit` 对过滤结果分页。\n", + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 可见性与控制台一致：管理员可见账户知识及全部团队知识；非管理员可见账户知识及所属团队的知识，传入的 `team_ids` 会被静默过滤为其所属团队。\n- `scope` 用于选择 `all`（默认）、仅 `account` 或仅 `team`，会覆盖 `include_account`。\n- `query` 对知识 ID、范围和团队名称做大小写不敏感的子串过滤；`p`/`limit` 对过滤结果分页。\n", "href": "/zh/api-reference/ai-sre/knowledge/knowledge-pack-read-list", "metadata": { - "sidebarTitle": "查询知识包列表" + "sidebarTitle": "查询知识列表" } } } }, "/safari/knowledge/pack/update": { "post": { - "description": "将知识包移动到其他账户或团队范围。", + "description": "将知识移动到其他账户或团队范围。", "operationId": "knowledge-pack-write-update", "requestBody": { "content": { @@ -53446,15 +53446,15 @@ "AppKeyAuth": [] } ], - "summary": "更新知识包", + "summary": "更新知识", "tags": [ "AI SRE/知识" ], "x-mint": { - "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **知识库管理**（`ai-sre`） |\n\n## 使用说明\n\n- `scope` 是唯一可修改的字段；不传则为空操作，返回当前知识包。\n- 团队范围必须传 `scope_id`；账户范围自动使用账户 ID。\n- 目标范围已存在知识包时返回 `ReferenceExist`——知识包不会被合并。\n- 每次调用都会记录到账户审计日志。\n", + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **知识管理**（`ai-sre`） |\n\n## 使用说明\n\n- `scope` 是唯一可修改的字段；不传则为空操作，返回当前知识。\n- 团队范围必须传 `scope_id`；账户范围自动使用账户 ID。\n- 目标范围已存在知识时返回 `ReferenceExist`——两份知识不会被合并。\n- 每次调用都会记录到账户审计日志。\n", "href": "/zh/api-reference/ai-sre/knowledge/knowledge-pack-write-update", "metadata": { - "sidebarTitle": "更新知识包" + "sidebarTitle": "更新知识" } } } @@ -54491,7 +54491,7 @@ "AI SRE/会话" ], "x-mint": { - "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 分页使用 `p`/`limit`（最大 100）；`scope` 默认 `all`。\n- `all` 返回调用者自己的个人会话，以及调用者可访问团队的团队会话；账户管理员可见所有团队会话，但不可见他人的个人会话。\n- `team_ids` 只会收窄可见集合，不会扩大访问范围。\n- `is_running` 反映实时运行集合；`has_unread` 按调用者各自计算；`current_turn_*` 字段在此接口恒为 0 —— 仅 `session/get` 会在会话运行时计算它们。\n- `suggest_init` 是账户级的引导提示（仅当账户在任何范围内都没有知识包时为 true），与列表过滤条件无关。\n", + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 分页使用 `p`/`limit`（最大 100）；`scope` 默认 `all`。\n- `all` 返回调用者自己的个人会话，以及调用者可访问团队的团队会话；账户管理员可见所有团队会话，但不可见他人的个人会话。\n- `team_ids` 只会收窄可见集合，不会扩大访问范围。\n- `is_running` 反映实时运行集合；`has_unread` 按调用者各自计算；`current_turn_*` 字段在此接口恒为 0 —— 仅 `session/get` 会在会话运行时计算它们。\n- `suggest_init` 是账户级的引导提示（仅当账户在任何范围内都没有知识时为 true），与列表过滤条件无关。\n", "href": "/zh/api-reference/ai-sre/sessions/session-read-list", "metadata": { "sidebarTitle": "查询会话列表" diff --git a/api-reference/safari.openapi.en.json b/api-reference/safari.openapi.en.json index 3ede44fa1..396530ce8 100644 --- a/api-reference/safari.openapi.en.json +++ b/api-reference/safari.openapi.en.json @@ -2429,7 +2429,7 @@ } ], "x-mint": { - "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Pagination uses `p`/`limit` (max 100); `scope` defaults to `all`.\n- `all` returns your personal sessions plus team sessions you can access; account admins see all team sessions, but not other users' personal sessions.\n- `team_ids` narrows the visible set and never expands access.\n- `is_running` reflects the live run-set; `has_unread` is computed per calling user; the `current_turn_*` fields are always zero here — only `session/get` computes them while a session is running.\n- `suggest_init` is an account-wide onboarding flag (true only when the account has zero knowledge packs anywhere) — it doesn't depend on the list filters.\n", + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Pagination uses `p`/`limit` (max 100); `scope` defaults to `all`.\n- `all` returns your personal sessions plus team sessions you can access; account admins see all team sessions, but not other users' personal sessions.\n- `team_ids` narrows the visible set and never expands access.\n- `is_running` reflects the live run-set; `has_unread` is computed per calling user; the `current_turn_*` fields are always zero here — only `session/get` computes them while a session is running.\n- `suggest_init` is an account-wide onboarding flag (true only when the account has no knowledge in any scope) — it doesn't depend on the list filters.\n", "href": "/en/api-reference/ai-sre/sessions/session-read-list", "metadata": { "sidebarTitle": "List sessions" @@ -3189,8 +3189,8 @@ "/safari/knowledge/get": { "post": { "operationId": "knowledge-pack-read-get", - "summary": "Get account knowledge pack", - "description": "Return the account-scope knowledge pack metadata and its file list.", + "summary": "Get account knowledge", + "description": "Return the metadata and file list of the account-scope knowledge.", "tags": [ "AI SRE/Knowledge" ], @@ -3200,10 +3200,10 @@ } ], "x-mint": { - "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Always targets the caller's account-scope pack — there is no `pack_id` parameter; use `POST /safari/knowledge/pack/list` to discover team packs.\n- The account pack is created lazily on first access, so a valid account never gets not-found here.\n", + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Always targets the caller's account-scope knowledge — there is no `pack_id` parameter; use `POST /safari/knowledge/pack/list` to discover team knowledge.\n- The account knowledge is created lazily on first access, so a valid account never gets not-found here.\n", "href": "/en/api-reference/ai-sre/knowledge/knowledge-pack-read-get", "metadata": { - "sidebarTitle": "Get account knowledge pack" + "sidebarTitle": "Get account knowledge" } }, "responses": { @@ -3299,8 +3299,8 @@ "/safari/knowledge/pack/list": { "post": { "operationId": "knowledge-pack-read-list", - "summary": "List knowledge packs", - "description": "List knowledge packs visible to the caller across account and team scopes.", + "summary": "List knowledge", + "description": "List the knowledge visible to the caller across account and team scopes.", "tags": [ "AI SRE/Knowledge" ], @@ -3310,10 +3310,10 @@ } ], "x-mint": { - "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Visibility matches the console: admins see the account pack plus every team pack; non-admins see the account pack plus their own teams, and requested `team_ids` are silently intersected with their teams.\n- `scope` selects `all` (default), `account`-only, or `team`-only, overriding `include_account`.\n- `query` applies a case-insensitive substring filter over pack ID, scope, and team name; `p`/`limit` paginate the filtered result.\n", + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Visibility matches the console: admins see the account knowledge plus every team's knowledge; non-admins see the account knowledge plus their own teams' knowledge, and requested `team_ids` are silently intersected with their teams.\n- `scope` selects `all` (default), `account`-only, or `team`-only, overriding `include_account`.\n- `query` applies a case-insensitive substring filter over knowledge ID, scope, and team name; `p`/`limit` paginate the filtered result.\n", "href": "/en/api-reference/ai-sre/knowledge/knowledge-pack-read-list", "metadata": { - "sidebarTitle": "List knowledge packs" + "sidebarTitle": "List knowledge" } }, "responses": { @@ -3410,8 +3410,8 @@ "/safari/knowledge/pack/ensure": { "post": { "operationId": "knowledge-pack-write-ensure", - "summary": "Ensure knowledge pack", - "description": "Idempotently create the knowledge pack at the given scope, or return the existing one.", + "summary": "Ensure knowledge", + "description": "Idempotently create the knowledge at the given scope, or return the existing one.", "tags": [ "AI SRE/Knowledge" ], @@ -3421,10 +3421,10 @@ } ], "x-mint": { - "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Knowledge Manage** (`ai-sre`) |\n\n## Usage\n\n- Idempotent: if a pack already exists at (`scope`, `scope_id`), it is returned unchanged.\n- For `account` scope, `scope_id` is ignored (the account ID is used) and a default `DUTY.md` is seeded on first creation.\n- Creating the account-scope pack requires account owner/admin; creating into a team requires membership of that team.\n- Every call is recorded in the account audit log.\n", + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Knowledge Manage** (`ai-sre`) |\n\n## Usage\n\n- Idempotent: if knowledge already exists at (`scope`, `scope_id`), it is returned unchanged.\n- For `account` scope, `scope_id` is ignored (the account ID is used) and a default `DUTY.md` is seeded on first creation.\n- Creating the account-scope knowledge requires account owner/admin; creating into a team requires membership of that team.\n- Every call is recorded in the account audit log.\n", "href": "/en/api-reference/ai-sre/knowledge/knowledge-pack-write-ensure", "metadata": { - "sidebarTitle": "Ensure knowledge pack" + "sidebarTitle": "Ensure knowledge" } }, "responses": { @@ -3502,8 +3502,8 @@ "/safari/knowledge/pack/update": { "post": { "operationId": "knowledge-pack-write-update", - "summary": "Update knowledge pack", - "description": "Move a knowledge pack to a different account or team scope.", + "summary": "Update knowledge", + "description": "Move knowledge to a different account or team scope.", "tags": [ "AI SRE/Knowledge" ], @@ -3513,10 +3513,10 @@ } ], "x-mint": { - "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Knowledge Manage** (`ai-sre`) |\n\n## Usage\n\n- `scope` is the only mutable field; omitting it is a no-op that returns the current pack.\n- For `team` scope, `scope_id` is required; for `account` scope it is set to the account ID automatically.\n- The move fails with `ReferenceExist` when the destination scope already has a pack — packs are never merged.\n- Every call is recorded in the account audit log.\n", + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Knowledge Manage** (`ai-sre`) |\n\n## Usage\n\n- `scope` is the only mutable field; omitting it is a no-op that returns the current knowledge.\n- For `team` scope, `scope_id` is required; for `account` scope it is set to the account ID automatically.\n- The move fails with `ReferenceExist` when the destination scope already has knowledge — knowledge is never merged.\n- Every call is recorded in the account audit log.\n", "href": "/en/api-reference/ai-sre/knowledge/knowledge-pack-write-update", "metadata": { - "sidebarTitle": "Update knowledge pack" + "sidebarTitle": "Update knowledge" } }, "responses": { @@ -3596,8 +3596,8 @@ "/safari/knowledge/pack/delete": { "post": { "operationId": "knowledge-pack-write-delete", - "summary": "Delete knowledge pack", - "description": "Delete a knowledge pack and all of its files.", + "summary": "Delete knowledge", + "description": "Delete knowledge and all of its files.", "tags": [ "AI SRE/Knowledge" ], @@ -3607,10 +3607,10 @@ } ], "x-mint": { - "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Knowledge Manage** (`ai-sre`) |\n\n## Usage\n\n- Deleting a pack removes every file it contains; the operation cannot be undone.\n- Deleting the account-scope pack is allowed; it is re-created empty on next access.\n- Every call is recorded in the account audit log.\n", + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Knowledge Manage** (`ai-sre`) |\n\n## Usage\n\n- Deleting knowledge removes every file it contains; the operation cannot be undone.\n- Deleting the account-scope knowledge is allowed; it is re-created empty on next access.\n- Every call is recorded in the account audit log.\n", "href": "/en/api-reference/ai-sre/knowledge/knowledge-pack-write-delete", "metadata": { - "sidebarTitle": "Delete knowledge pack" + "sidebarTitle": "Delete knowledge" } }, "responses": { @@ -3677,7 +3677,7 @@ "post": { "operationId": "knowledge-file-read-list", "summary": "List knowledge files", - "description": "List the files in a knowledge pack with metadata such as size and checksum.", + "description": "List knowledge files with metadata such as size and checksum.", "tags": [ "AI SRE/Knowledge" ], @@ -3687,7 +3687,7 @@ } ], "x-mint": { - "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Omitting `pack_id` targets the caller's account-scope pack (created lazily if absent).\n- Reading a team-scope pack requires membership of that team.\n- `p`/`limit` are accepted but the current implementation always returns the full file list.\n", + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Omitting `pack_id` targets the caller's account-scope knowledge (created lazily if absent).\n- Reading team-scope knowledge requires membership of that team.\n- `p`/`limit` are accepted but the current implementation always returns the full file list.\n", "href": "/en/api-reference/ai-sre/knowledge/knowledge-file-read-list", "metadata": { "sidebarTitle": "List knowledge files" @@ -3786,7 +3786,7 @@ } ], "x-mint": { - "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Content is returned in `content_b64` (base64); pack files are guaranteed UTF-8 text.\n- Omitting `pack_id` targets the account-scope pack; reading a team-scope pack requires team membership.\n- A missing file returns `ResourceNotFound` (HTTP 400).\n", + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Content is returned in `content_b64` (base64); knowledge files are guaranteed UTF-8 text.\n- Omitting `pack_id` targets the account-scope knowledge; reading team-scope knowledge requires team membership.\n- A missing file returns `ResourceNotFound` (HTTP 400).\n", "href": "/en/api-reference/ai-sre/knowledge/knowledge-file-read-get", "metadata": { "sidebarTitle": "Get knowledge file" @@ -3863,7 +3863,7 @@ "post": { "operationId": "knowledge-file-write-put", "summary": "Upload knowledge file", - "description": "Create or overwrite a file in a knowledge pack with base64-encoded content.", + "description": "Create or overwrite a knowledge file with base64-encoded content.", "tags": [ "AI SRE/Knowledge" ], @@ -3873,7 +3873,7 @@ } ], "x-mint": { - "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Knowledge Manage** (`ai-sre`) |\n\n## Usage\n\n- The file body is sent as base64 text in the JSON field `content_b64` — this is not a multipart upload.\n- Writing an existing `rel_path` overwrites it; `content_type` is inferred from the extension when omitted (`.md` → `text/markdown`).\n- Content must decode to valid UTF-8 text; binary payloads are rejected with `InvalidParameter`.\n- Editing the account-scope pack requires account owner/admin; editing a team pack requires team membership.\n- Every call is recorded in the account audit log.\n", + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Knowledge Manage** (`ai-sre`) |\n\n## Usage\n\n- The file body is sent as base64 text in the JSON field `content_b64` — this is not a multipart upload.\n- Writing an existing `rel_path` overwrites it; `content_type` is inferred from the extension when omitted (`.md` → `text/markdown`).\n- Content must decode to valid UTF-8 text; binary payloads are rejected with `InvalidParameter`.\n- Editing the account-scope knowledge requires account owner/admin; editing team knowledge requires team membership.\n- Every call is recorded in the account audit log.\n", "href": "/en/api-reference/ai-sre/knowledge/knowledge-file-write-put", "metadata": { "sidebarTitle": "Upload knowledge file" @@ -3954,7 +3954,7 @@ "post": { "operationId": "knowledge-file-write-delete", "summary": "Delete knowledge file", - "description": "Delete a file from a knowledge pack by its relative path.", + "description": "Delete a knowledge file by its relative path.", "tags": [ "AI SRE/Knowledge" ], @@ -3964,7 +3964,7 @@ } ], "x-mint": { - "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Knowledge Manage** (`ai-sre`) |\n\n## Usage\n\n- Deleting is idempotent — removing a file that does not exist succeeds.\n- When other pack files still reference the target, the delete fails with `ReferenceExist` listing the referrers; set `force` to proceed (the referrers are returned as warnings).\n- Omitting `pack_id` targets the account-scope pack; editing the account pack requires account owner/admin, editing a team pack requires team membership.\n- Every call is recorded in the account audit log.\n", + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Knowledge Manage** (`ai-sre`) |\n\n## Usage\n\n- Deleting is idempotent — removing a file that does not exist succeeds.\n- When other knowledge files still reference the target, the delete fails with `ReferenceExist` listing the referrers; set `force` to proceed (the referrers are returned as warnings).\n- Omitting `pack_id` targets the account-scope knowledge; editing the account knowledge requires account owner/admin, editing team knowledge requires team membership.\n- Every call is recorded in the account audit log.\n", "href": "/en/api-reference/ai-sre/knowledge/knowledge-file-write-delete", "metadata": { "sidebarTitle": "Delete knowledge file" @@ -6294,15 +6294,15 @@ }, "ContextResolvedItem": { "type": "object", - "description": "Snapshot of the three-tier knowledge-pack resolution for this session.", + "description": "Snapshot of the three-tier knowledge resolution for this session.", "properties": { "account_pack_id": { "type": "string", - "description": "Resolved account-scoped pack id." + "description": "Resolved account-scope knowledge ID." }, "team_pack_id": { "type": "string", - "description": "Resolved team-scoped pack id." + "description": "Resolved team-scope knowledge ID." }, "incident_id": { "type": "string", @@ -6311,14 +6311,14 @@ "resolved_at_ms": { "type": "integer", "format": "int64", - "description": "Unix timestamp in milliseconds when the packs were resolved." + "description": "Unix timestamp in milliseconds when the knowledge was resolved." }, "versions": { "type": "object", "additionalProperties": { "type": "integer" }, - "description": "Per-pack resolved version map." + "description": "Resolved version map, one entry per knowledge." } }, "required": [ @@ -7255,7 +7255,7 @@ }, "suggest_init": { "type": "boolean", - "description": "Account-wide onboarding flag: true when the account has zero knowledge packs in any scope; not specific to this session." + "description": "Account-wide onboarding flag: true when the account has no knowledge in any scope; not specific to this session." }, "pending_messages": { "type": "array", @@ -7614,7 +7614,7 @@ }, "suggest_init": { "type": "boolean", - "description": "Account-wide onboarding flag: true when the account has zero knowledge packs in any scope; not dependent on this call's filters." + "description": "Account-wide onboarding flag: true when the account has no knowledge in any scope; not dependent on this call's filters." } }, "required": [ @@ -7962,20 +7962,20 @@ }, "KnowledgePackItem": { "type": "object", - "description": "A knowledge pack — a versioned file tree staged into every AI SRE sandbox at session start. One pack exists per (account, scope, scope_id).", + "description": "Knowledge — a versioned file tree staged into every AI SRE sandbox at session start. One knowledge exists per (account, scope, scope_id).", "properties": { "pack_id": { "type": "string", - "description": "Knowledge pack ID (`kpk_` prefix)." + "description": "Knowledge ID (`kpk_` prefix)." }, "account_id": { "type": "integer", - "description": "Account that owns the pack.", + "description": "Account that owns the knowledge.", "format": "int64" }, "scope": { "type": "string", - "description": "Pack scope. `channel` is a legacy scope; new packs are `account` or `team`.", + "description": "Knowledge scope. `channel` is a legacy scope; new knowledge is `account` or `team` scope.", "enum": [ "account", "team", @@ -7993,7 +7993,7 @@ }, "file_count": { "type": "integer", - "description": "Number of files in the pack." + "description": "Number of files in the knowledge." }, "total_bytes": { "type": "integer", @@ -8002,30 +8002,30 @@ }, "version": { "type": "integer", - "description": "Pack version, incremented on every file change." + "description": "Knowledge version, incremented on every file change." }, "duty_version": { "type": "integer", - "description": "Pack version at which DUTY.md was last authored or re-affirmed. When `version` is greater, DUTY.md no longer reflects every file in the pack." + "description": "Knowledge version at which DUTY.md was last authored or re-affirmed. When `version` is greater, DUTY.md no longer reflects every file in the knowledge." }, "created_by": { "type": "integer", - "description": "Person ID of the member who created the pack.", + "description": "Person ID of the member who created the knowledge.", "format": "int64" }, "created_at_ms": { "type": "integer", - "description": "Unix timestamp in milliseconds when the pack was created.", + "description": "Unix timestamp in milliseconds when the knowledge was created.", "format": "int64" }, "updated_at_ms": { "type": "integer", - "description": "Unix timestamp in milliseconds when the pack was last modified.", + "description": "Unix timestamp in milliseconds when the knowledge was last modified.", "format": "int64" }, "can_edit": { "type": "boolean", - "description": "Whether the caller can edit this pack." + "description": "Whether the caller can edit this knowledge." } }, "required": [ @@ -8045,7 +8045,7 @@ }, "KnowledgeFileItem": { "type": "object", - "description": "Metadata of one file inside a knowledge pack. Content is fetched separately via file/get.", + "description": "Metadata of one knowledge file. Content is fetched separately via file/get.", "properties": { "file_id": { "type": "string", @@ -8053,11 +8053,11 @@ }, "pack_id": { "type": "string", - "description": "ID of the knowledge pack that contains the file." + "description": "ID of the knowledge that contains the file." }, "rel_path": { "type": "string", - "description": "Path relative to the pack root, e.g. `runbooks/restart.md`." + "description": "Path relative to the knowledge root, e.g. `runbooks/restart.md`." }, "content_type": { "type": "string", @@ -8100,7 +8100,7 @@ "properties": { "code": { "type": "string", - "description": "Warning code. One of: `unresolved_reference` (an @ref in the written file's content points to a file that does not exist in the pack; `ref` carries it), `still_referenced_by` (the deleted file is still @ref-referenced by other files in the pack; `refs` lists the referrers).", + "description": "Warning code. One of: `unresolved_reference` (an @ref in the written file's content points to a file that does not exist in the knowledge; `ref` carries it), `still_referenced_by` (the deleted file is still @ref-referenced by other files in the knowledge; `refs` lists the referrers).", "enum": [ "unresolved_reference", "still_referenced_by" @@ -8124,12 +8124,12 @@ }, "KnowledgeGetRequest": { "type": "object", - "description": "No request fields — the account-scope pack is always targeted.", + "description": "No request fields — the account-scope knowledge is always targeted.", "properties": {} }, "KnowledgePackListRequest": { "type": "object", - "description": "Filter and pagination for the pack list.", + "description": "Filter and pagination for the knowledge list.", "properties": { "p": { "type": "integer", @@ -8141,7 +8141,7 @@ }, "scope": { "type": "string", - "description": "Restrict to one scope; `all` (default) overrides `include_account`. One of: `all` (account scope plus visible team scopes), `account` (account-level packs only), `team` (team-level packs only, can be combined with `team_ids`).", + "description": "Restrict to one scope; `all` (default) overrides `include_account`. One of: `all` (account scope plus visible team scopes), `account` (account-level knowledge only), `team` (team-level knowledge only, can be combined with `team_ids`).", "enum": [ "all", "account", @@ -8150,7 +8150,7 @@ }, "query": { "type": "string", - "description": "Case-insensitive substring filter over pack ID, scope, scope ID/account ID, and team name.", + "description": "Case-insensitive substring filter over knowledge ID, scope, scope ID/account ID, and team name.", "maxLength": 128 }, "team_ids": { @@ -8166,17 +8166,17 @@ "boolean", "null" ], - "description": "Include the account-scope pack; defaults to true." + "description": "Include the account-scope knowledge; defaults to true." } } }, "KnowledgePackEnsureRequest": { "type": "object", - "description": "Scope at which to ensure a knowledge pack exists.", + "description": "Scope at which to ensure knowledge exists.", "properties": { "scope": { "type": "string", - "description": "Scope of the pack to ensure. One of: `account` (account-level pack; scope_id is forced to the caller's account ID and only account admins may create it; first creation seeds a default DUTY.md), `team` (team-level pack; the `scope_id` team ID is required and the caller must belong to that team).", + "description": "Scope of the knowledge to ensure. One of: `account` (account-level knowledge; scope_id is forced to the caller's account ID and only account admins may create it; first creation seeds a default DUTY.md), `team` (team-level knowledge; the `scope_id` team ID is required and the caller must belong to that team).", "enum": [ "account", "team" @@ -8194,18 +8194,18 @@ }, "KnowledgePackUpdateRequest": { "type": "object", - "description": "Move a knowledge pack to a different scope.", + "description": "Move knowledge to a different scope.", "properties": { "pack_id": { "type": "string", - "description": "Knowledge pack ID to update." + "description": "Knowledge ID to update." }, "scope": { "type": [ "string", "null" ], - "description": "Destination scope; omit for a no-op that returns the current pack.", + "description": "Destination scope; omit for a no-op that returns the current knowledge.", "enum": [ "account", "team" @@ -8226,11 +8226,11 @@ }, "KnowledgePackDeleteRequest": { "type": "object", - "description": "Pack to delete.", + "description": "Knowledge to delete.", "properties": { "pack_id": { "type": "string", - "description": "Knowledge pack ID to delete." + "description": "Knowledge ID to delete." } }, "required": [ @@ -8243,7 +8243,7 @@ "properties": { "ok": { "type": "boolean", - "description": "True when the pack was deleted." + "description": "True when the knowledge was deleted." } }, "required": [ @@ -8252,11 +8252,11 @@ }, "KnowledgeFileListRequest": { "type": "object", - "description": "Which pack's files to list.", + "description": "Which knowledge's files to list.", "properties": { "pack_id": { "type": "string", - "description": "Knowledge pack ID; defaults to the caller's account-scope pack." + "description": "Knowledge ID; defaults to the caller's account-scope knowledge." }, "p": { "type": "integer", @@ -8274,11 +8274,11 @@ "properties": { "pack_id": { "type": "string", - "description": "Knowledge pack ID; defaults to the caller's account-scope pack." + "description": "Knowledge ID; defaults to the caller's account-scope knowledge." }, "rel_path": { "type": "string", - "description": "Path of the file relative to the pack root." + "description": "Path of the file relative to the knowledge root." } }, "required": [ @@ -8291,11 +8291,11 @@ "properties": { "pack_id": { "type": "string", - "description": "Knowledge pack ID; defaults to the caller's account-scope pack." + "description": "Knowledge ID; defaults to the caller's account-scope knowledge." }, "rel_path": { "type": "string", - "description": "Destination path relative to the pack root; existing files are overwritten." + "description": "Destination path relative to the knowledge root; existing files are overwritten." }, "content_b64": { "type": "string", @@ -8312,7 +8312,7 @@ }, "KnowledgeGetResponse": { "type": "object", - "description": "Account-scope pack metadata plus its file list.", + "description": "Account-scope knowledge metadata plus its file list.", "properties": { "pack": { "$ref": "#/components/schemas/KnowledgePackItem" @@ -8322,7 +8322,7 @@ "items": { "$ref": "#/components/schemas/KnowledgeFileItem" }, - "description": "Array of files in this knowledge pack; empty array when the pack has no files." + "description": "Array of files in this knowledge; empty array when it has no files." } }, "required": [ @@ -8332,18 +8332,18 @@ }, "KnowledgePackListResponse": { "type": "object", - "description": "Visible packs and the total after filtering.", + "description": "Visible knowledge and the total after filtering.", "properties": { "packs": { "type": "array", "items": { "$ref": "#/components/schemas/KnowledgePackItem" }, - "description": "Array of visible knowledge packs after filtering (current page), used with `total` for pagination." + "description": "Array of visible knowledge after filtering (current page), used with `total` for pagination." }, "total": { "type": "integer", - "description": "Total number of packs after filtering, before pagination.", + "description": "Total number of knowledge entries after filtering, before pagination.", "format": "int64" } }, @@ -8354,18 +8354,18 @@ }, "KnowledgeFileListResponse": { "type": "object", - "description": "Files in the pack.", + "description": "Files in the knowledge.", "properties": { "files": { "type": "array", "items": { "$ref": "#/components/schemas/KnowledgeFileItem" }, - "description": "Array of files in the specified knowledge pack; empty array when the pack has no files." + "description": "Array of files in the specified knowledge; empty array when it has no files." }, "total": { "type": "integer", - "description": "Total number of files in the pack.", + "description": "Total number of files in the knowledge.", "format": "int64" } }, @@ -8403,7 +8403,7 @@ "items": { "$ref": "#/components/schemas/KnowledgeWarning" }, - "description": "Non-blocking warnings after a successful write; `code=unresolved_reference` means an @ref in the file content points to a file that does not exist in the pack. Absent when there are no warnings (omitempty)." + "description": "Non-blocking warnings after a successful write; `code=unresolved_reference` means an @ref in the file content points to a file that does not exist in the knowledge. Absent when there are no warnings (omitempty)." } }, "required": [ @@ -8412,19 +8412,19 @@ }, "KnowledgeFileDeleteRequest": { "type": "object", - "description": "File to remove from a knowledge pack.", + "description": "Knowledge file to remove.", "properties": { "pack_id": { "type": "string", - "description": "Knowledge pack ID; defaults to the caller's account-scope pack." + "description": "Knowledge ID; defaults to the caller's account-scope knowledge." }, "rel_path": { "type": "string", - "description": "Path of the file relative to the pack root." + "description": "Path of the file relative to the knowledge root." }, "force": { "type": "boolean", - "description": "Delete even when other pack files reference this file; the referrers are then returned as warnings instead of blocking the delete." + "description": "Delete even when other knowledge files reference this file; the referrers are then returned as warnings instead of blocking the delete." } }, "required": [ @@ -8440,7 +8440,7 @@ "items": { "$ref": "#/components/schemas/KnowledgeWarning" }, - "description": "Non-blocking warnings after deletion; `code=still_referenced_by` means the (force-)deleted file is still @ref-referenced by other files in the pack (`refs` lists the referrers). Absent when there are no warnings (omitempty)." + "description": "Non-blocking warnings after deletion; `code=still_referenced_by` means the (force-)deleted file is still @ref-referenced by other files in the knowledge (`refs` lists the referrers). Absent when there are no warnings (omitempty)." } } }, diff --git a/api-reference/safari.openapi.zh.json b/api-reference/safari.openapi.zh.json index 3b78f4295..56a04ca72 100644 --- a/api-reference/safari.openapi.zh.json +++ b/api-reference/safari.openapi.zh.json @@ -2429,7 +2429,7 @@ } ], "x-mint": { - "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 分页使用 `p`/`limit`（最大 100）；`scope` 默认 `all`。\n- `all` 返回调用者自己的个人会话，以及调用者可访问团队的团队会话；账户管理员可见所有团队会话，但不可见他人的个人会话。\n- `team_ids` 只会收窄可见集合，不会扩大访问范围。\n- `is_running` 反映实时运行集合；`has_unread` 按调用者各自计算；`current_turn_*` 字段在此接口恒为 0 —— 仅 `session/get` 会在会话运行时计算它们。\n- `suggest_init` 是账户级的引导提示（仅当账户在任何范围内都没有知识包时为 true），与列表过滤条件无关。\n", + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 分页使用 `p`/`limit`（最大 100）；`scope` 默认 `all`。\n- `all` 返回调用者自己的个人会话，以及调用者可访问团队的团队会话；账户管理员可见所有团队会话，但不可见他人的个人会话。\n- `team_ids` 只会收窄可见集合，不会扩大访问范围。\n- `is_running` 反映实时运行集合；`has_unread` 按调用者各自计算；`current_turn_*` 字段在此接口恒为 0 —— 仅 `session/get` 会在会话运行时计算它们。\n- `suggest_init` 是账户级的引导提示（仅当账户在任何范围内都没有知识时为 true），与列表过滤条件无关。\n", "href": "/zh/api-reference/ai-sre/sessions/session-read-list", "metadata": { "sidebarTitle": "查询会话列表" @@ -3189,8 +3189,8 @@ "/safari/knowledge/get": { "post": { "operationId": "knowledge-pack-read-get", - "summary": "查看账户知识包", - "description": "返回账户范围知识包的元数据及其文件列表。", + "summary": "查看账户知识", + "description": "返回账户范围知识的元数据及其文件列表。", "tags": [ "AI SRE/知识" ], @@ -3200,10 +3200,10 @@ } ], "x-mint": { - "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 固定返回调用者的账户范围知识包——没有 `pack_id` 参数；如需团队知识包请使用 `POST /safari/knowledge/pack/list`。\n- 账户知识包在首次访问时惰性创建，因此有效账户调用不会返回 not-found。\n", + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 固定返回调用者的账户范围知识——没有 `pack_id` 参数；如需团队知识请使用 `POST /safari/knowledge/pack/list`。\n- 账户知识在首次访问时惰性创建，因此有效账户调用不会返回 not-found。\n", "href": "/zh/api-reference/ai-sre/knowledge/knowledge-pack-read-get", "metadata": { - "sidebarTitle": "查看账户知识包" + "sidebarTitle": "查看账户知识" } }, "responses": { @@ -3299,8 +3299,8 @@ "/safari/knowledge/pack/list": { "post": { "operationId": "knowledge-pack-read-list", - "summary": "查询知识包列表", - "description": "查询调用者可见的账户与团队范围知识包列表。", + "summary": "查询知识列表", + "description": "查询调用者可见的账户与团队范围知识列表。", "tags": [ "AI SRE/知识" ], @@ -3310,10 +3310,10 @@ } ], "x-mint": { - "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 可见性与控制台一致：管理员可见账户包及全部团队包；非管理员可见账户包及所属团队包，传入的 `team_ids` 会被静默过滤为其所属团队。\n- `scope` 用于选择 `all`（默认）、仅 `account` 或仅 `team`，会覆盖 `include_account`。\n- `query` 对知识包 ID、范围和团队名称做大小写不敏感的子串过滤；`p`/`limit` 对过滤结果分页。\n", + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 可见性与控制台一致：管理员可见账户知识及全部团队知识；非管理员可见账户知识及所属团队的知识，传入的 `team_ids` 会被静默过滤为其所属团队。\n- `scope` 用于选择 `all`（默认）、仅 `account` 或仅 `team`，会覆盖 `include_account`。\n- `query` 对知识 ID、范围和团队名称做大小写不敏感的子串过滤；`p`/`limit` 对过滤结果分页。\n", "href": "/zh/api-reference/ai-sre/knowledge/knowledge-pack-read-list", "metadata": { - "sidebarTitle": "查询知识包列表" + "sidebarTitle": "查询知识列表" } }, "responses": { @@ -3410,8 +3410,8 @@ "/safari/knowledge/pack/ensure": { "post": { "operationId": "knowledge-pack-write-ensure", - "summary": "确保知识包存在", - "description": "在指定范围幂等创建知识包，已存在时直接返回现有知识包。", + "summary": "确保知识存在", + "description": "在指定范围幂等创建知识，已存在时直接返回现有知识。", "tags": [ "AI SRE/知识" ], @@ -3421,10 +3421,10 @@ } ], "x-mint": { - "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **知识库管理**（`ai-sre`） |\n\n## 使用说明\n\n- 幂等：若（`scope`, `scope_id`）已存在知识包，则原样返回。\n- 账户范围忽略 `scope_id`（使用账户 ID），首次创建时会自动写入默认 `DUTY.md`。\n- 创建账户范围知识包需要账户 Owner/Admin 权限；在团队下创建需要是该团队成员。\n- 每次调用都会记录到账户审计日志。\n", + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **知识管理**（`ai-sre`） |\n\n## 使用说明\n\n- 幂等：若（`scope`, `scope_id`）已存在知识，则原样返回。\n- 账户范围忽略 `scope_id`（使用账户 ID），首次创建时会自动写入默认 `DUTY.md`。\n- 创建账户范围知识需要账户 Owner/Admin 权限；在团队下创建需要是该团队成员。\n- 每次调用都会记录到账户审计日志。\n", "href": "/zh/api-reference/ai-sre/knowledge/knowledge-pack-write-ensure", "metadata": { - "sidebarTitle": "确保知识包存在" + "sidebarTitle": "确保知识存在" } }, "responses": { @@ -3502,8 +3502,8 @@ "/safari/knowledge/pack/update": { "post": { "operationId": "knowledge-pack-write-update", - "summary": "更新知识包", - "description": "将知识包移动到其他账户或团队范围。", + "summary": "更新知识", + "description": "将知识移动到其他账户或团队范围。", "tags": [ "AI SRE/知识" ], @@ -3513,10 +3513,10 @@ } ], "x-mint": { - "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **知识库管理**（`ai-sre`） |\n\n## 使用说明\n\n- `scope` 是唯一可修改的字段；不传则为空操作，返回当前知识包。\n- 团队范围必须传 `scope_id`；账户范围自动使用账户 ID。\n- 目标范围已存在知识包时返回 `ReferenceExist`——知识包不会被合并。\n- 每次调用都会记录到账户审计日志。\n", + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **知识管理**（`ai-sre`） |\n\n## 使用说明\n\n- `scope` 是唯一可修改的字段；不传则为空操作，返回当前知识。\n- 团队范围必须传 `scope_id`；账户范围自动使用账户 ID。\n- 目标范围已存在知识时返回 `ReferenceExist`——两份知识不会被合并。\n- 每次调用都会记录到账户审计日志。\n", "href": "/zh/api-reference/ai-sre/knowledge/knowledge-pack-write-update", "metadata": { - "sidebarTitle": "更新知识包" + "sidebarTitle": "更新知识" } }, "responses": { @@ -3596,8 +3596,8 @@ "/safari/knowledge/pack/delete": { "post": { "operationId": "knowledge-pack-write-delete", - "summary": "删除知识包", - "description": "删除知识包及其全部文件。", + "summary": "删除知识", + "description": "删除知识及其全部文件。", "tags": [ "AI SRE/知识" ], @@ -3607,10 +3607,10 @@ } ], "x-mint": { - "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **知识库管理**（`ai-sre`） |\n\n## 使用说明\n\n- 删除知识包会同时删除其中所有文件，且不可恢复。\n- 允许删除账户范围知识包；下次访问时会重新创建为空包。\n- 每次调用都会记录到账户审计日志。\n", + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **知识管理**（`ai-sre`） |\n\n## 使用说明\n\n- 删除知识会同时删除其中所有文件，且不可恢复。\n- 允许删除账户范围知识；下次访问时会重新创建一份空知识。\n- 每次调用都会记录到账户审计日志。\n", "href": "/zh/api-reference/ai-sre/knowledge/knowledge-pack-write-delete", "metadata": { - "sidebarTitle": "删除知识包" + "sidebarTitle": "删除知识" } }, "responses": { @@ -3677,7 +3677,7 @@ "post": { "operationId": "knowledge-file-read-list", "summary": "查询知识文件列表", - "description": "查询知识包内的文件列表，包含大小、校验和等元数据。", + "description": "查询知识文件列表，包含大小、校验和等元数据。", "tags": [ "AI SRE/知识" ], @@ -3687,7 +3687,7 @@ } ], "x-mint": { - "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 不传 `pack_id` 时默认查询调用者的账户范围知识包（不存在时惰性创建）。\n- 读取团队范围知识包需要是该团队成员。\n- `p`/`limit` 参数会被接受，但当前实现始终返回完整文件列表。\n", + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 不传 `pack_id` 时默认查询调用者的账户范围知识（不存在时惰性创建）。\n- 读取团队范围知识需要是该团队成员。\n- `p`/`limit` 参数会被接受，但当前实现始终返回完整文件列表。\n", "href": "/zh/api-reference/ai-sre/knowledge/knowledge-file-read-list", "metadata": { "sidebarTitle": "查询知识文件列表" @@ -3786,7 +3786,7 @@ } ], "x-mint": { - "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 文件内容通过 `content_b64`（Base64）返回；知识包文件保证为 UTF-8 文本。\n- 不传 `pack_id` 时默认账户范围知识包；读取团队范围知识包需要是该团队成员。\n- 文件不存在时返回 `ResourceNotFound`（HTTP 400）。\n", + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 文件内容通过 `content_b64`（Base64）返回；知识文件保证为 UTF-8 文本。\n- 不传 `pack_id` 时默认账户范围知识；读取团队范围知识需要是该团队成员。\n- 文件不存在时返回 `ResourceNotFound`（HTTP 400）。\n", "href": "/zh/api-reference/ai-sre/knowledge/knowledge-file-read-get", "metadata": { "sidebarTitle": "获取知识文件" @@ -3863,7 +3863,7 @@ "post": { "operationId": "knowledge-file-write-put", "summary": "上传知识文件", - "description": "以 Base64 编码的内容在知识包中创建或覆盖文件。", + "description": "以 Base64 编码的内容创建或覆盖知识文件。", "tags": [ "AI SRE/知识" ], @@ -3873,7 +3873,7 @@ } ], "x-mint": { - "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **知识库管理**（`ai-sre`） |\n\n## 使用说明\n\n- 文件内容以 JSON 字段 `content_b64` 中的 Base64 文本上传——不是 multipart 上传。\n- 写入已存在的 `rel_path` 会覆盖原文件；`content_type` 留空时按扩展名推断（`.md` → `text/markdown`）。\n- 内容解码后必须是合法的 UTF-8 文本，二进制内容会被拒绝并返回 `InvalidParameter`。\n- 编辑账户范围知识包需要账户 Owner/Admin 权限；编辑团队知识包需要是该团队成员。\n- 每次调用都会记录到账户审计日志。\n", + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **知识管理**（`ai-sre`） |\n\n## 使用说明\n\n- 文件内容以 JSON 字段 `content_b64` 中的 Base64 文本上传——不是 multipart 上传。\n- 写入已存在的 `rel_path` 会覆盖原文件；`content_type` 留空时按扩展名推断（`.md` → `text/markdown`）。\n- 内容解码后必须是合法的 UTF-8 文本，二进制内容会被拒绝并返回 `InvalidParameter`。\n- 编辑账户范围知识需要账户 Owner/Admin 权限；编辑团队知识需要是该团队成员。\n- 每次调用都会记录到账户审计日志。\n", "href": "/zh/api-reference/ai-sre/knowledge/knowledge-file-write-put", "metadata": { "sidebarTitle": "上传知识文件" @@ -3954,7 +3954,7 @@ "post": { "operationId": "knowledge-file-write-delete", "summary": "删除知识文件", - "description": "按相对路径删除知识包中的文件。", + "description": "按相对路径删除知识文件。", "tags": [ "AI SRE/知识" ], @@ -3964,7 +3964,7 @@ } ], "x-mint": { - "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **知识库管理**（`ai-sre`） |\n\n## 使用说明\n\n- 删除是幂等的——删除不存在的文件也会成功。\n- 当其他包内文件仍引用目标文件时，删除失败并返回 `ReferenceExist`（附带引用方列表）；设置 `force` 可强制删除（引用方以警告形式返回）。\n- 不传 `pack_id` 时默认账户范围知识包；编辑账户包需要账户 Owner/Admin 权限，编辑团队包需要是该团队成员。\n- 每次调用都会记录到账户审计日志。\n", + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **知识管理**（`ai-sre`） |\n\n## 使用说明\n\n- 删除是幂等的——删除不存在的文件也会成功。\n- 当其他知识文件仍引用目标文件时，删除失败并返回 `ReferenceExist`（附带引用方列表）；设置 `force` 可强制删除（引用方以警告形式返回）。\n- 不传 `pack_id` 时默认账户范围知识；编辑账户知识需要账户 Owner/Admin 权限，编辑团队知识需要是该团队成员。\n- 每次调用都会记录到账户审计日志。\n", "href": "/zh/api-reference/ai-sre/knowledge/knowledge-file-write-delete", "metadata": { "sidebarTitle": "删除知识文件" @@ -6294,15 +6294,15 @@ }, "ContextResolvedItem": { "type": "object", - "description": "该会话三层知识包解析结果的快照。", + "description": "该会话三层知识解析结果的快照。", "properties": { "account_pack_id": { "type": "string", - "description": "解析出的账户级知识包 ID。" + "description": "解析出的账户级知识 ID。" }, "team_pack_id": { "type": "string", - "description": "解析出的团队级知识包 ID。" + "description": "解析出的团队级知识 ID。" }, "incident_id": { "type": "string", @@ -6311,14 +6311,14 @@ "resolved_at_ms": { "type": "integer", "format": "int64", - "description": "知识包解析时间，Unix 毫秒时间戳。" + "description": "知识解析时间，Unix 毫秒时间戳。" }, "versions": { "type": "object", "additionalProperties": { "type": "integer" }, - "description": "各知识包解析版本映射。" + "description": "各份知识的解析版本映射。" } }, "required": [ @@ -7255,7 +7255,7 @@ }, "suggest_init": { "type": "boolean", - "description": "账户级引导标志：当账户在任何范围内都没有知识包时为 true；并非该会话独有的属性。" + "description": "账户级引导标志：当账户在任何范围内都没有知识时为 true；并非该会话独有的属性。" }, "pending_messages": { "type": "array", @@ -7614,7 +7614,7 @@ }, "suggest_init": { "type": "boolean", - "description": "账户级引导标志：当账户在任何范围内都没有知识包时为 true；与本次调用的过滤条件无关。" + "description": "账户级引导标志：当账户在任何范围内都没有知识时为 true；与本次调用的过滤条件无关。" } }, "required": [ @@ -7962,20 +7962,20 @@ }, "KnowledgePackItem": { "type": "object", - "description": "知识包——一棵带版本号的文件树，AI SRE 会话启动时会注入到每个沙箱中。每个（账户, scope, scope_id）仅有一个知识包。", + "description": "知识——一棵带版本号的文件树，AI SRE 会话启动时会注入到每个沙箱中。每个（账户, scope, scope_id）仅有一份知识。", "properties": { "pack_id": { "type": "string", - "description": "知识包 ID（`kpk_` 前缀）。" + "description": "知识 ID（`kpk_` 前缀）。" }, "account_id": { "type": "integer", - "description": "知识包所属账户 ID。", + "description": "知识所属账户 ID。", "format": "int64" }, "scope": { "type": "string", - "description": "知识包范围；`channel` 为历史遗留范围，新建知识包为 `account` 或 `team`。", + "description": "知识范围；`channel` 为历史遗留范围，新建知识为 `account` 或 `team`。", "enum": [ "account", "team", @@ -7993,20 +7993,20 @@ }, "file_count": { "type": "integer", - "description": "包内文件数量。" + "description": "知识内文件数量。" }, "total_bytes": { "type": "integer", - "description": "包内所有文件的总字节数。", + "description": "知识内所有文件的总字节数。", "format": "int64" }, "version": { "type": "integer", - "description": "知识包版本号，文件每次变更时递增。" + "description": "知识版本号，文件每次变更时递增。" }, "duty_version": { "type": "integer", - "description": "最后一次撰写或确认 DUTY.md 时的知识库版本。当 `version` 大于该值时，说明 DUTY.md 已不能反映知识库的全部文件。" + "description": "最后一次撰写或确认 DUTY.md 时的知识版本。当 `version` 大于该值时，说明 DUTY.md 已不能反映知识的全部文件。" }, "created_by": { "type": "integer", @@ -8025,7 +8025,7 @@ }, "can_edit": { "type": "boolean", - "description": "调用者是否有权限编辑该知识包。" + "description": "调用者是否有权限编辑该知识。" } }, "required": [ @@ -8045,7 +8045,7 @@ }, "KnowledgeFileItem": { "type": "object", - "description": "知识包内单个文件的元数据；文件内容需通过 file/get 单独获取。", + "description": "单个知识文件的元数据；文件内容需通过 file/get 单独获取。", "properties": { "file_id": { "type": "string", @@ -8053,11 +8053,11 @@ }, "pack_id": { "type": "string", - "description": "文件所属的知识包 ID。" + "description": "文件所属的知识 ID。" }, "rel_path": { "type": "string", - "description": "相对于知识包根目录的路径，如 `runbooks/restart.md`。" + "description": "相对于知识根目录的路径，如 `runbooks/restart.md`。" }, "content_type": { "type": "string", @@ -8100,7 +8100,7 @@ "properties": { "code": { "type": "string", - "description": "提示码。可选值：`unresolved_reference`（写入的文件内容中 @ref 引用了包内不存在的文件，`ref` 给出该引用）、`still_referenced_by`（被删除的文件仍被包内其他文件 @ref 引用，`refs` 列出引用方）。", + "description": "提示码。可选值：`unresolved_reference`（写入的文件内容中 @ref 引用了知识内不存在的文件，`ref` 给出该引用）、`still_referenced_by`（被删除的文件仍被知识内其他文件 @ref 引用，`refs` 列出引用方）。", "enum": [ "unresolved_reference", "still_referenced_by" @@ -8124,12 +8124,12 @@ }, "KnowledgeGetRequest": { "type": "object", - "description": "无请求字段——固定查询账户范围知识包。", + "description": "无请求字段——固定查询账户范围知识。", "properties": {} }, "KnowledgePackListRequest": { "type": "object", - "description": "知识包列表的过滤与分页参数。", + "description": "知识列表的过滤与分页参数。", "properties": { "p": { "type": "integer", @@ -8141,7 +8141,7 @@ }, "scope": { "type": "string", - "description": "限定范围；`all`（默认）会覆盖 `include_account`。可选值：`all`（账户范围 + 可见团队范围）、`account`（仅账户级知识包）、`team`（仅团队级知识包，可配合 `team_ids` 过滤）。", + "description": "限定范围；`all`（默认）会覆盖 `include_account`。可选值：`all`（账户范围 + 可见团队范围）、`account`（仅账户级知识）、`team`（仅团队级知识，可配合 `team_ids` 过滤）。", "enum": [ "all", "account", @@ -8150,7 +8150,7 @@ }, "query": { "type": "string", - "description": "对知识包 ID、范围、范围 ID/账户 ID 和团队名称做大小写不敏感的子串过滤。", + "description": "对知识 ID、范围、范围 ID/账户 ID 和团队名称做大小写不敏感的子串过滤。", "maxLength": 128 }, "team_ids": { @@ -8166,17 +8166,17 @@ "boolean", "null" ], - "description": "是否包含账户范围的知识包；默认为 true。" + "description": "是否包含账户范围的知识；默认为 true。" } } }, "KnowledgePackEnsureRequest": { "type": "object", - "description": "要确保存在知识包的范围。", + "description": "要确保存在知识的范围。", "properties": { "scope": { "type": "string", - "description": "知识包范围。可选值：`account`（账户级知识包，scope_id 固定为调用方账户 ID，仅账户管理员可创建；首次创建会播种默认 DUTY.md）、`team`（团队级知识包，必须提供 `scope_id` 团队 ID，调用者需属于该团队）。", + "description": "知识范围。可选值：`account`（账户级知识，scope_id 固定为调用方账户 ID，仅账户管理员可创建；首次创建会播种默认 DUTY.md）、`team`（团队级知识，必须提供 `scope_id` 团队 ID，调用者需属于该团队）。", "enum": [ "account", "team" @@ -8194,18 +8194,18 @@ }, "KnowledgePackUpdateRequest": { "type": "object", - "description": "将知识包移动到其他范围。", + "description": "将知识移动到其他范围。", "properties": { "pack_id": { "type": "string", - "description": "要更新的知识包 ID。" + "description": "要更新的知识 ID。" }, "scope": { "type": [ "string", "null" ], - "description": "目标范围；不传则为空操作，返回当前知识包。", + "description": "目标范围；不传则为空操作，返回当前知识。", "enum": [ "account", "team" @@ -8226,11 +8226,11 @@ }, "KnowledgePackDeleteRequest": { "type": "object", - "description": "要删除的知识包。", + "description": "要删除的知识。", "properties": { "pack_id": { "type": "string", - "description": "要删除的知识包 ID。" + "description": "要删除的知识 ID。" } }, "required": [ @@ -8243,7 +8243,7 @@ "properties": { "ok": { "type": "boolean", - "description": "知识包删除成功时为 true。" + "description": "知识删除成功时为 true。" } }, "required": [ @@ -8252,11 +8252,11 @@ }, "KnowledgeFileListRequest": { "type": "object", - "description": "要列出文件的知识包。", + "description": "要列出文件的知识。", "properties": { "pack_id": { "type": "string", - "description": "知识包 ID；默认为调用者的账户范围知识包。" + "description": "知识 ID；默认为调用者的账户范围知识。" }, "p": { "type": "integer", @@ -8274,11 +8274,11 @@ "properties": { "pack_id": { "type": "string", - "description": "知识包 ID；默认为调用者的账户范围知识包。" + "description": "知识 ID；默认为调用者的账户范围知识。" }, "rel_path": { "type": "string", - "description": "文件相对于知识包根目录的路径。" + "description": "文件相对于知识根目录的路径。" } }, "required": [ @@ -8291,11 +8291,11 @@ "properties": { "pack_id": { "type": "string", - "description": "知识包 ID；默认为调用者的账户范围知识包。" + "description": "知识 ID；默认为调用者的账户范围知识。" }, "rel_path": { "type": "string", - "description": "相对于知识包根目录的目标路径；已存在的文件会被覆盖。" + "description": "相对于知识根目录的目标路径；已存在的文件会被覆盖。" }, "content_b64": { "type": "string", @@ -8312,7 +8312,7 @@ }, "KnowledgeGetResponse": { "type": "object", - "description": "账户范围知识包元数据及其文件列表。", + "description": "账户范围知识元数据及其文件列表。", "properties": { "pack": { "$ref": "#/components/schemas/KnowledgePackItem" @@ -8322,7 +8322,7 @@ "items": { "$ref": "#/components/schemas/KnowledgeFileItem" }, - "description": "该知识包内的文件数组；无文件时为空数组。" + "description": "该知识内的文件数组；无文件时为空数组。" } }, "required": [ @@ -8332,18 +8332,18 @@ }, "KnowledgePackListResponse": { "type": "object", - "description": "可见的知识包及过滤后的总数。", + "description": "可见的知识及过滤后的总数。", "properties": { "packs": { "type": "array", "items": { "$ref": "#/components/schemas/KnowledgePackItem" }, - "description": "过滤后当前可见的知识包数组（当前页），与 `total` 配合分页。" + "description": "过滤后当前可见的知识数组（当前页），与 `total` 配合分页。" }, "total": { "type": "integer", - "description": "过滤后、分页前的知识包总数。", + "description": "过滤后、分页前的知识总数。", "format": "int64" } }, @@ -8354,18 +8354,18 @@ }, "KnowledgeFileListResponse": { "type": "object", - "description": "知识包内的文件。", + "description": "知识内的文件。", "properties": { "files": { "type": "array", "items": { "$ref": "#/components/schemas/KnowledgeFileItem" }, - "description": "指定知识包内的文件数组；无文件时为空数组。" + "description": "指定知识内的文件数组；无文件时为空数组。" }, "total": { "type": "integer", - "description": "知识包内文件总数。", + "description": "知识内文件总数。", "format": "int64" } }, @@ -8403,7 +8403,7 @@ "items": { "$ref": "#/components/schemas/KnowledgeWarning" }, - "description": "写入成功后的非阻塞警告数组；`code=unresolved_reference` 表示文件内容中的 @ref 引用了包内不存在的文件。无警告时该字段缺省（omitempty）。" + "description": "写入成功后的非阻塞警告数组；`code=unresolved_reference` 表示文件内容中的 @ref 引用了知识内不存在的文件。无警告时该字段缺省（omitempty）。" } }, "required": [ @@ -8412,19 +8412,19 @@ }, "KnowledgeFileDeleteRequest": { "type": "object", - "description": "要从知识包中删除的文件。", + "description": "要删除的知识文件。", "properties": { "pack_id": { "type": "string", - "description": "知识包 ID；默认为调用者的账户范围知识包。" + "description": "知识 ID；默认为调用者的账户范围知识。" }, "rel_path": { "type": "string", - "description": "文件相对于知识包根目录的路径。" + "description": "文件相对于知识根目录的路径。" }, "force": { "type": "boolean", - "description": "即使其他包内文件仍引用该文件也强制删除；此时引用方会以警告形式返回，而不再阻止删除。" + "description": "即使其他知识文件仍引用该文件也强制删除；此时引用方会以警告形式返回，而不再阻止删除。" } }, "required": [ @@ -8440,7 +8440,7 @@ "items": { "$ref": "#/components/schemas/KnowledgeWarning" }, - "description": "删除后的非阻塞警告数组；`code=still_referenced_by` 表示被（强制）删除的文件仍被包内其他文件 @ref 引用（`refs` 列出引用方）。无警告时该字段缺省（omitempty）。" + "description": "删除后的非阻塞警告数组；`code=still_referenced_by` 表示被（强制）删除的文件仍被知识内其他文件 @ref 引用（`refs` 列出引用方）。无警告时该字段缺省（omitempty）。" } } }, diff --git a/en/openapi/api-catalog.mdx b/en/openapi/api-catalog.mdx index 54265f2f6..971ce3139 100644 --- a/en/openapi/api-catalog.mdx +++ b/en/openapi/api-catalog.mdx @@ -491,11 +491,11 @@ Only plain human messages are projected: rows produced by internal producers (au | Method | Endpoint | Description | | :--- | :--- | :--- | -| POST | [`/safari/knowledge/pack/list`](/en/api-reference/ai-sre/knowledge/knowledge-pack-read-list) | List knowledge packs | -| POST | [`/safari/knowledge/get`](/en/api-reference/ai-sre/knowledge/knowledge-pack-read-get) | Get account knowledge pack | -| POST | [`/safari/knowledge/pack/ensure`](/en/api-reference/ai-sre/knowledge/knowledge-pack-write-ensure) | Ensure knowledge pack | -| POST | [`/safari/knowledge/pack/update`](/en/api-reference/ai-sre/knowledge/knowledge-pack-write-update) | Update knowledge pack | -| POST | [`/safari/knowledge/pack/delete`](/en/api-reference/ai-sre/knowledge/knowledge-pack-write-delete) | Delete knowledge pack | +| POST | [`/safari/knowledge/pack/list`](/en/api-reference/ai-sre/knowledge/knowledge-pack-read-list) | List knowledge | +| POST | [`/safari/knowledge/get`](/en/api-reference/ai-sre/knowledge/knowledge-pack-read-get) | Get account knowledge | +| POST | [`/safari/knowledge/pack/ensure`](/en/api-reference/ai-sre/knowledge/knowledge-pack-write-ensure) | Ensure knowledge | +| POST | [`/safari/knowledge/pack/update`](/en/api-reference/ai-sre/knowledge/knowledge-pack-write-update) | Update knowledge | +| POST | [`/safari/knowledge/pack/delete`](/en/api-reference/ai-sre/knowledge/knowledge-pack-write-delete) | Delete knowledge | | POST | [`/safari/knowledge/file/list`](/en/api-reference/ai-sre/knowledge/knowledge-file-read-list) | List knowledge files | | POST | [`/safari/knowledge/file/get`](/en/api-reference/ai-sre/knowledge/knowledge-file-read-get) | Get knowledge file | | POST | [`/safari/knowledge/file/put`](/en/api-reference/ai-sre/knowledge/knowledge-file-write-put) | Upload knowledge file | diff --git a/zh/openapi/api-catalog.mdx b/zh/openapi/api-catalog.mdx index 2b8550a7c..1042b8f57 100644 --- a/zh/openapi/api-catalog.mdx +++ b/zh/openapi/api-catalog.mdx @@ -491,11 +491,11 @@ Flashduty Open API 提供 **338** 个接口，覆盖 On-call、Monitors、RUM、 | 方法 | 接口 | 描述 | | :--- | :--- | :--- | -| POST | [`/safari/knowledge/pack/list`](/zh/api-reference/ai-sre/knowledge/knowledge-pack-read-list) | 查询知识包列表 | -| POST | [`/safari/knowledge/get`](/zh/api-reference/ai-sre/knowledge/knowledge-pack-read-get) | 查看账户知识包 | -| POST | [`/safari/knowledge/pack/ensure`](/zh/api-reference/ai-sre/knowledge/knowledge-pack-write-ensure) | 确保知识包存在 | -| POST | [`/safari/knowledge/pack/update`](/zh/api-reference/ai-sre/knowledge/knowledge-pack-write-update) | 更新知识包 | -| POST | [`/safari/knowledge/pack/delete`](/zh/api-reference/ai-sre/knowledge/knowledge-pack-write-delete) | 删除知识包 | +| POST | [`/safari/knowledge/pack/list`](/zh/api-reference/ai-sre/knowledge/knowledge-pack-read-list) | 查询知识列表 | +| POST | [`/safari/knowledge/get`](/zh/api-reference/ai-sre/knowledge/knowledge-pack-read-get) | 查看账户知识 | +| POST | [`/safari/knowledge/pack/ensure`](/zh/api-reference/ai-sre/knowledge/knowledge-pack-write-ensure) | 确保知识存在 | +| POST | [`/safari/knowledge/pack/update`](/zh/api-reference/ai-sre/knowledge/knowledge-pack-write-update) | 更新知识 | +| POST | [`/safari/knowledge/pack/delete`](/zh/api-reference/ai-sre/knowledge/knowledge-pack-write-delete) | 删除知识 | | POST | [`/safari/knowledge/file/list`](/zh/api-reference/ai-sre/knowledge/knowledge-file-read-list) | 查询知识文件列表 | | POST | [`/safari/knowledge/file/get`](/zh/api-reference/ai-sre/knowledge/knowledge-file-read-get) | 获取知识文件 | | POST | [`/safari/knowledge/file/put`](/zh/api-reference/ai-sre/knowledge/knowledge-file-write-put) | 上传知识文件 |