> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flashduty.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 了解知识
> 知识由人维护，写这个环境怎么运转。一份 DUTY.md 加上运行手册、服务清单等文件，会话开始时先读使用说明，其余按需打开。
> AI SRE 需在控制台开通，面向 On-call 专业版及以上订阅，按实际用量计费，详见[开通与计费](/zh/ai-sre/overview#开通与计费)。
## 概述
知识是您交给 AI SRE 的运维资料：一份 `DUTY.md` 加上一组运行手册（runbook）、FAQ、服务清单、集群配置等文件。会话开始时，Agent 先读取 `DUTY.md`，再按需打开其它文件，从而把您团队的处置经验、命名约定与系统拓扑带进每一次诊断。
控制台入口：**AI SRE → 自定义 → 上下文 → 知识**。同一分组下的 [记忆](/zh/ai-sre/memory) 是另一页，两者分开管理。
整个账户只能有 1 份共享知识，每个团队最多有 1 份团队知识：
* 共享（即账户级）知识对账户内所有 Agent 可见。
* **团队级**知识仅在该团队的会话中加载。
知识是 AI SRE 资源的一种，遵循统一的两级作用域模型。其他资源（Skill、MCP、Agent、运行环境）的作用域规则与本页一致。
知识内容用于**精炼**Agent 的领域上下文（人设、方法论、系统知识），但不会覆盖系统的安全与行为底线。如果某份知识要求 Agent 跳过安全规则，会被当作越权内容忽略，而非更高优先级的指令。
## DUTY.md 结构
`DUTY.md` 是整份知识的**目录入口**，每次会话自动加载。Agent 会全文读取 `DUTY.md`，再通过 `@文件名` 引用按需拉取其它文件。系统不会在 `DUTY.md` 之外另附文件列表：知识文件放在会话工作区的 `knowledge/` 目录下，Agent 像浏览代码仓库一样用 ls / glob / grep 查找，`DUTY.md` 没有引用到的文件也能被找到。
如果某个作用域还没有 `DUTY.md`，该作用域不会被静默跳过：系统会告诉 Agent 这个范围没有使用说明、文件在哪个目录下，并要求它在开展实质工作前先列出目录、阅读相关文件。
引用采用 `@<路径>` 风格，路径指向同一份知识内的另一份文件，支持子目录（如 `@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 | 超出无法保存 |
| 单份知识上限 | 5 MiB | 控制台用量条按此额度显示 |
| 文件数量上限 | 100 | 达到上限后无法新增文件 |
| 子目录 | 允许 | 路径可含 `/`，如 `runbooks/api-5xx.md`；不允许以 `.` 开头的路径段 |
| 点文件 | 不允许 | 文件名不能以 `.` 开头 |
## 在控制台维护
进入 **AI SRE → 自定义 → 上下文 → 知识**。列表每行是一份知识，按范围（“共享”或团队名）标识，列出文件数、`DUTY.md` 状态和最近修改时间。`DUTY.md` 状态有三种：**未创建**、**已同步**，以及 **需梳理 · 之后改了 N 次**（`DUTY.md` 写好之后，这份知识里其它文件又改过）。点击 **创建** 可以为共享范围或您所属的团队新建知识；账户和所有可用团队都已有知识时，按钮置灰。
还没有任何知识时，页面改为引导：**初始化 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 个文件。`@引用` 指向这份知识里没有的文件时，仍然可以保存。
### 让 AI 修改
在正文下方的输入框中写下要改什么（例如“补一份 OOM 排查手册”）并发送，控制台会打开一个带有这份知识引用和您要求的新对话（团队知识会切换到对应团队）。AI 会先说明要改哪些文件、怎么改，经您同意后才保存。
**让 AI 生成** 与下面的 **让 AI 梳理** 也是同样的流程：转到新对话，请求已经写好。
### DUTY.md 需要梳理时
`DUTY.md` 写好之后，如果知识中的其他文件又被修改，文件树上方会提示可能需要重新梳理。有编辑权限时，可以：
* **让 AI 梳理**：转到新对话，让 AI 对照现有文件更新 `DUTY.md` 的索引，改动先经您确认。
* **已核对，不用改**：确认 `DUTY.md` 仍然准确。提示随即消失，直到下一次文件改动。
助手也能在对话里维护当前会话所属范围的知识，例如“补一篇 runbook”“更新 services.md”。它读取、修改，再经您确认后保存。
## Agent 如何使用知识
知识不是一次性全量加载，而是**目录先行、按需展开**：
会话启动时，系统会把当前作用域的 `DUTY.md` 加载进会话，不附文件列表。绑定了团队的会话会同时加载共享范围与该团队的 `DUTY.md`；未绑定团队的会话只加载共享范围的。若某个作用域尚未创建 `DUTY.md`，系统会要求 Agent 在实质工作前先列出该范围的目录并阅读相关文件。
Agent 阅读 `DUTY.md` 后，根据当前故障决定展开哪些 `@引用`，再读取对应的知识文件取得具体内容。
未绑定团队的个人会话里，Agent 可以读取**会话创建者所属团队**的知识。读取时，系统把该团队的整套知识（`DUTY.md`、运行手册）连同其 Skill、MCP 一并挂载进当前会话，且在本次会话中持久保留。同一个团队在一次会话里至多挂载一次。绑定了团队的会话不能读取其它团队的知识。
跨团队加载只在 Agent**显式读取**某个团队的知识时触发，不会被模糊的文件遍历误触发。挂载一次后，该团队的知识、Skill 与 MCP 在本次会话内一直可用。
如果知识没能加载到当前会话，消息列表上方会出现警告，此时 Agent 可能无法读取 DUTY.md 与运行手册。点击 **重试** 重新加载。
## 作用域与可见性
每份知识都有一个作用域：共享范围（即账户级，账户内全局可见）或团队范围。
| 维度 | 共享 | 团队 |
| - | - | - |
| 可见范围 | 账户内所有 Agent / 会话 | 仅该团队的会话与成员 |
| 编辑权限 | 账户 Owner 或账户管理员 | 仅该团队的成员可以操作，组织管理员也需要先加入该团队 |
| 会话中加载 | 所有会话 | 仅绑定该团队的会话 |
| 运行时可读 | 所有会话 | 绑定该团队的会话；以及创建者属于该团队的个人会话（读取即挂载） |
**编辑权限**：团队知识只有该团队成员可以编辑（组织管理员也需先加入该团队）；共享知识只有账户 Owner 或管理员可以编辑。创建者没有额外权限。
**创建与改归属**：创建新的团队知识时，您必须是目标团队成员；共享范围创建仅限账户 Owner 或管理员。编辑已有知识时，账户 Owner 或管理员可以把它移动到任意团队，用于恢复空团队或离职成员留下的资源；普通成员只能移动到自己所属的团队。把已有知识提升为共享范围（**设为共享**）与共享范围创建同门槛：仅限账户 Owner 或管理员操作，普通成员即使属于这份知识所在团队也不能自助提升。
**运行时可见性**：会话开始时，只加载**共享范围**资源加上**当前会话绑定团队**的资源。绑定来源是显式指定的团队，或作战室（war room）故障对应的团队。会话进行中能否再挂载其它团队的知识，看会话类型：
绑定了团队的会话只能用共享范围和这个团队的知识，读取其它团队的知识会被拒绝，账户 Owner 和管理员也一样。未绑定团队的个人会话可以按需挂载**会话创建者所属团队**的知识；读取创建者不属于的团队时，报错与“文件不存在”相同。需要跨团队联合排障时，请对方团队把相关知识设为共享，或在个人会话里综合分析。
这套两级作用域模型对账户内所有资源（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` 与相关文件里的 `@引用`。保存时的“引用未解析”警告与删除时的“仍被引用”提示，能帮您及时发现断链。
共享知识放跨团队通用的约定（命名规范、通用排障方法、平台访问方式）；团队知识放该团队专属的服务清单、值班手册与上下游。绑定团队的会话会同时拿到两者。
排障过程中沉淀出的新处置经验，可以直接让 Agent“补一篇 runbook”或“记录这个故障模式”，它会对当前作用域读取→编辑→保存，把经验回写进知识，形成持续积累的闭环。
## 相关页面
把可复用的诊断流程封装为 Skill，与知识共享同一套作用域。
通过 MCP 接入外部系统，让 Agent 调用您的工具与数据。
AI 在对话里记下的偏好、做法、事实和教训，与知识分开管理。
了解会话如何绑定团队，以及知识在会话中如何被读取与挂载。
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.