> ## Documentation Index
> Fetch the complete documentation index at: https://test-8ad8522e-feat-ai-sre.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# 管理知识
> 为 AI SRE 提供账户与团队的运维知识——一份 DUTY.md 加运行手册、FAQ、服务清单、集群配置等文件，Agent 在会话中按需读取并挂载。
**公测功能**：AI SRE 已全量开放公测，无需申请，登录控制台即可直接使用，公测期间免费。功能与界面可能继续调整。
## 概述
***
知识库（Knowledge Pack）是您交给 AI SRE 的运维知识：一份 `DUTY.md` 加上一组运行手册（runbook）、FAQ、服务清单、集群配置等文件。会话开始时，Agent 先读取 `DUTY.md`，再顺着其中的引用按需取用相关文件，从而把您团队的处置经验、命名约定与系统拓扑带进每一次诊断。
每个**目标**（账户或团队）最多拥有一个 Knowledge Pack：
* \*\*共享（即账户级，整个账户可见）\*\*知识对账户内所有 Agent 可见。
* **团队级**知识仅在该团队的会话中加载，仅对该团队成员可见。
Knowledge Pack 是 AI SRE 资源的一种，遵循统一的两级作用域模型。其他资源（Skill、MCP、Agent、运行环境）的作用域规则与本页一致。
知识库内容用于**精炼**Agent 的领域上下文（人设、方法论、系统知识），但不会覆盖系统的安全与行为底线。如果某份知识要求 Agent 跳过安全规则，会被当作越权内容忽略，而非更高优先级的指令。
## DUTY.md 结构
***
`DUTY.md` 是整个知识库的**目录入口**。它本身就是清单——Agent 会全文读取 `DUTY.md`，再通过 `@文件名` 引用按需拉取其它文件。`DUTY.md` 存在时，系统不会在其之外另附一份文件列表；目录即正文。
如果某个作用域还没有 `DUTY.md`、但已有其它知识文件，该作用域不会被静默跳过：系统会在会话知识清单中附上一份自动生成的权威文件索引，并明确指示 Agent 在开展实质工作前，先阅读索引中与当前任务相关的文件（文件不多时应全部读完），而不是跳过这一步直接下结论。创建 `DUTY.md` 之后，这份生成索引的引导即随之消失，恢复「目录即正文」。
引用采用 `@<路径>` 风格，路径指向同一个 Pack 内的另一份文件，支持子目录（如 `@runbooks/api-5xx.md`）：
```markdown theme={null}
# 值班知识总览 (DUTY.md)
## 服务清单
我们的核心服务与负责人见 @services.md。
## 常见故障处置
- API 5xx 飙升：参见 @runbooks/api-5xx.md
- 数据库连接池打满：参见 @runbooks/db-pool.md
## 集群与环境
生产集群拓扑与访问方式见 @cluster.yaml。
```
Agent 读取 `DUTY.md` 后，会根据当前故障判断需要展开哪些 `@引用`，再去读对应文件——实质内容放在被引用的兄弟文件里，`DUTY.md` 只承载链接列表。
这套分层 `@reference` 架构让 `DUTY.md` 保持精简、可读。`DUTY.md` 像一张地图，运行手册、服务清单、配置则是它指向的详情页。Agent 不必把所有文件一次性塞进上下文，只在需要时才展开相关分支。
**文件约束**（在创建与编辑时强制）：
| 约束 | 取值 | 说明 |
| ---------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 文件内容 | 纯文本（UTF-8） | 按**内容**校验而非扩展名：文件不含 NUL 字节且能按 UTF-8 解码即可保存。因此 `.md` `.yaml` `.json` `.txt` `.sh` 之外的 `.py` `.sql`，乃至没有扩展名的 `Dockerfile` 都可以上传；反之，扩展名是 `.txt` 但内容为二进制的文件会被拒绝 |
| 单文件上限 | 1 MiB | 超出无法保存 |
| 单个 Pack 上限 | 5 MiB | 控制台用量条按此额度显示 |
| 文件数量上限 | 100 | 达到上限后无法新增文件 |
| 子目录 | 允许 | 路径可含 `/`，如 `runbooks/api-5xx.md`；不允许以 `.` 开头的路径段 |
| 点文件 | 不允许 | 文件名不能以 `.` 开头 |
## 创建与编辑
***
进入 **知识库**（Knowledges）管理页，您可以为账户或团队创建、编辑、启用/禁用、删除 Knowledge Pack。列表按 **名称 / 范围 / 文件 / 状态 / 操作** 展示每个 Pack，并通过顶部的范围筛选器在共享、团队之间切换。
点击页面右上角的 **创建**，弹出「创建知识库」对话框。Knowledge Pack 本身没有可编辑的名称——它是按目标（账户或团队）的单例资源，弹窗里只需选择 **范围**：共享或某个团队。创建团队级 Pack 时，您必须是目标团队成员；共享范围创建仅限账户 Owner 或管理员。每个目标只能拥有一个 Pack。已有 Pack 的账户或团队仍会出现在下拉列表中，并标记为「已有知识库」；选择后主按钮变为 **打开知识库**，点击即可直接进入该 Pack，不会重复创建。选择没有 Pack 的范围后，点击 **新建** 完成创建；提交前控制台会再次检查，若该范围刚被其他人创建为 Pack，则改为打开已有 Pack。控制台用范围（共享 / 团队名）作为该 Pack 的显示标识。
点击列表中的某一行打开检视器。左侧是文件树，右侧是行内编辑器。点击 **新建文件** 输入文件名（如 `runbook.md`），或用 **上传** 导入本地文件；Markdown 文件支持 **预览** 与 **源码** 两种视图。编辑后点击 **保存**。
左侧 **用量** 条实时显示当前占用 / 5 MB 额度。临近上限时颜色变红，提示您清理或拆分文件。
用列表中的开关 **启用 / 禁用** 整个 Pack——禁用后文件保留，但不再加载到 AI SRE 会话。**删除** 会移除该 Pack 及其下全部文件。
**文件夹上传**：上传对话框中的 **选择文件夹上传** 按钮可以一次导入整个本地文件夹。目录结构会被保留——文件以「顶层文件夹名 / 子路径」作为知识库内的文件路径入库（例如所选文件夹下的 `runbooks/api-5xx.md` 会以 `<文件夹名>/runbooks/api-5xx.md` 落库）。导入前按与单文件上传相同的规则逐文件过滤：必须是 UTF-8 文本、单文件不超过 1 MiB、且加上知识库现有用量后不超过 5 MB 配额；`node_modules` 目录与以 `.` 开头的文件 / 目录会被静默忽略。上传过程中显示进度（「正在上传 N/M 个文件…」），被跳过的文件会在对话框中列出清单，逐条给出文件名与原因（非 UTF-8 文本 / 超过每文件 1 MiB 限制 / 超出知识库 5MB 配额 / 上传失败）。
**文档提炼入库**：知识文件只接受纯文本内容（见上表）。如果上传 `.pdf`、`.docx`、`.xlsx`、`.pptx`、`.html`、`.htm` 这类无法直接入库的文档，控制台会提示该格式无法被 AI 直接使用，并提供 **转到对话分析** 入口。点击后系统会新开一个 AI SRE 会话，把该文档作为附件带入；Agent 阅读文档后将其提炼为 Markdown 知识文件，经您确认后再保存进当前知识库。旧版 Office 二进制格式（`.doc`、`.xls`、`.ppt`）不在转换范围内，会被当作二进制文件直接拒绝——请先另存为 `.docx` / `.xlsx` / `.pptx` 再上传。
**引用一致性检查**：保存文件时，如果其中的 `@引用` 指向一个 Pack 内不存在的文件，会给出非阻断的「引用未解析」警告（不影响保存）。删除一个仍被其它文件引用的文件时，会先提示「仍被引用」冲突，您可以选择 **强制删除**。
Agent 也能在会话中自然语言地维护知识库——例如「补一篇 runbook」「更新 services.md」「记录这个故障模式」。它会直接对当前会话所属作用域执行读取、编辑、保存，无需您离开对话。结构化的初始化（onboarding）则由专门的引导流程完成，而非行内编辑器。
## Agent 如何使用知识
***
知识不是一次性全量加载，而是**目录先行、按需展开**：
会话启动时，系统会把当前作用域的 `DUTY.md` 加载进会话（`DUTY.md` 存在时不附独立文件列表）。绑定了团队的会话会同时加载共享范围与该团队的 `DUTY.md`；未绑定团队的会话只加载共享范围的。若某个作用域有知识文件但尚未创建 `DUTY.md`，系统会改为附上一份生成的文件索引，并要求 Agent 在实质工作前先阅读其中的相关文件。
Agent 阅读 `DUTY.md` 后，根据当前故障决定展开哪些 `@引用`，再读取对应的知识文件取得具体内容。
需要跨团队排障时，Agent 读取另一个团队的知识，系统会把该团队的整套知识（`DUTY.md`、运行手册）连同其 Skill、MCP 一并挂载进当前会话，且在本次会话中持久保留。同一个团队在一次会话里至多挂载一次。
跨团队加载只在 Agent**显式读取**某个团队的知识时触发，不会被模糊的文件遍历误触发。挂载一次后，该团队的知识、Skill 与 MCP 在本次会话内一直可用。
若知识库未能成功加载进当前会话，消息列表上方会出现一条警告横幅：「知识库加载失败 — 本次会话中 AI-SRE 可能无法访问 DUTY.md 与 runbook」，并附带 **重试** 按钮，点击后会重新尝试加载。重试成功前，Agent 在该会话中可能无法读取 DUTY.md 与运行手册。
## 作用域与可见性
***
每个 Knowledge Pack 都有一个作用域：共享范围（即账户级，账户内全局可见）或团队范围（仅对该团队成员可见）。
| 维度 | 共享 | 团队 |
| ----- | ---------------- | -------------------------- |
| 可见范围 | 账户内所有 Agent / 会话 | 仅该团队的会话与成员 |
| 编辑权限 | 账户 Owner 或账户管理员 | 仅该团队的成员可以操作，组织管理员也需要先加入该团队 |
| 会话中加载 | 所有会话 | 仅绑定该团队的会话 |
| 运行时可读 | 全账户 | 全账户（读取即挂载） |
**编辑权限**：团队级 Pack 仅该团队的成员可以操作，组织管理员也需要先加入该团队；共享范围 Pack 仅账户 Owner 或管理员可以操作；不存在「创建者额外保留权限」的规则。控制台会把你无权编辑的行置灰，并禁用其开关与操作按钮。
**创建与改归属**：创建新的团队级 Pack 时，您必须是目标团队成员；共享范围创建仅限账户 Owner 或管理员。编辑已有 Pack 时，账户 Owner 或管理员可以把它移动到任意团队，用于恢复空团队或离职成员留下的资源；普通成员只能移动到自己所属的团队。把已有 Pack 提升为共享范围（**设为共享**）与共享范围创建同门槛：仅限账户 Owner 或管理员操作，普通成员即使属于该 Pack 所在团队也不能自助提升。
**运行时可见性**：会话开始时，只加载**共享范围**资源加上**当前会话绑定团队**的资源。绑定来源是显式指定的团队，或作战室（war room）故障对应的团队。其它团队的知识在会话进行中、当 Agent 读取该团队 `DUTY.md` 时才按需挂载。
账户是运行时唯一的安全边界；团队是「编辑 / 所有权」标签，**不是**「运行时可读」边界。也就是说，账户内任意会话都能读取并挂载本账户其它团队的知识——这是跨团队联合排障的基础。如果某份知识对账户内其它团队也敏感，请评估是否适合纳入知识库。
这套两级作用域模型对账户内所有资源（Skill、MCP、Agent、运行环境）一致适用。
## 最佳实践
***
`DUTY.md` 只放链接列表与一句话导引，所有实质内容下沉到被 `@引用` 的兄弟文件。这样目录精简、可读，Agent 也能只展开当前故障相关的分支，避免无关内容占用上下文。
每篇运行手册聚焦一类故障或一个服务（如 `runbooks/api-5xx.md`、`runbooks/db-pool.md`），用清晰的路径做语义索引。支持子目录组织文件，可按服务或主题分组（如 `runbooks/`、`configs/`）。
服务清单、集群拓扑、阈值配置等结构化信息适合用 `.yaml` / `.json` 承载（如 `services.md`、`cluster.yaml`），让 Agent 既能阅读也能直接解析。脚本片段可用 `.sh`。
新增或重命名文件后，同步更新 `DUTY.md` 与相关文件里的 `@引用`。保存时的「引用未解析」警告与删除时的「仍被引用」提示，能帮您及时发现断链。
共享范围的 Pack 放跨团队通用的约定（命名规范、通用排障方法、平台访问方式）；团队级 Pack 放该团队专属的服务清单、值班手册与上下游。绑定团队的会话会同时拿到两者。
排障过程中沉淀出的新处置经验，可以直接让 Agent「补一篇 runbook」或「记录这个故障模式」，它会对当前作用域读取→编辑→保存，把经验回写进知识库，形成持续积累的闭环。
## 相关页面
***
把可复用的诊断流程封装为 Skill，与知识库共享同一套作用域。
通过 MCP 接入外部系统，让 Agent 调用您的工具与数据。
了解会话如何绑定团队，以及知识在会话中如何被读取与挂载。