> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qoder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 知识库

> 为 Qoder CLI 接入团队与项目知识，让 Agent 在完成任务时复用既有经验

知识库是指 Qoder CLI 在完成任务时可以检索和复用的、关于你项目与团队的长期知识。它不是对话里的临时上下文，而是可以跨会话、跨任务持续沉淀的内容：项目约定、架构说明、模块职责、代码规范、常见问题的解决办法等。

有了知识库，Agent 不必每次从零理解项目，就能：

* 遵循团队既定的约定与规范，而不是每次都要你重新说明。
* 快速定位相关模块、理解模块边界与依赖关系。
* 复用过去踩过的坑和验证过的解决方案，减少重复犯错。

Qoder CLI 的知识来源主要有三层：**项目说明与规则**、**长期记忆**、**结构化知识模块**。本页介绍它们的区别、如何接入以及如何在日常使用中让它们发挥作用。

<div id="knowledge-layers">
  # 知识的三个层次
</div>

## 项目说明与规则

项目说明文件（`AGENTS.md`）和规则文件描述“在这个项目里应该怎么做”，例如使用哪种包管理器、目录命名约定、测试命令、代码风格偏好等。它们随项目一起提交到版本库，团队成员共享，Agent 在会话开始时会自动加载。

这是最基础也最常用的知识层，适合放置所有贡献者都应遵守的项目约定。详细的文件位置与加载逻辑见 [记忆](/zh/cli/04-扩展QoderCLI/memory)。

## 长期记忆

长期记忆保存跨会话的偏好、事实和习惯，分为个人级（对所有项目生效）和项目级（仅对当前项目生效）。与项目说明不同，记忆更偏向“沉淀下来的经验和偏好”，可以在使用过程中不断积累和整理。

Qoder CLI 提供了记忆管理能力来维护这些内容：

* 内置的记忆管理子代理负责添加、去重和组织记忆条目，并把它们路由到合适的存储位置。
* `/remember` 会评审自动积累的记忆，提出晋升到项目说明或本地说明文件的建议，并识别过期、冲突和重复的条目。

记忆的层级、路由规则和管理方式见 [记忆](/zh/cli/04-扩展QoderCLI/memory)。

## 结构化知识模块

对于较大的代码库，可以把子系统的知识整理成结构化的知识模块（例如按模块拆分的说明页），描述该模块的架构设计、关键文件、职责边界和使用方式。这类知识以文档形式存放在项目中，Agent 在处理相关任务时可以按需检索，而不必一次性把所有内容塞进上下文。

结构化知识模块适合沉淀那些“需要花较大精力才能弄清、且会被反复用到”的领域知识，让团队新成员和 Agent 都能快速上手。

<div id="how-to-build">
  # 如何接入知识库
</div>

## 用 /init 建立起点

在项目根目录运行 `/init`，Qoder CLI 会分析项目并生成初始的项目说明文件。这是接入知识库最简单的起点：先有一个基础的项目说明，再逐步补充。

## 记录项目约定

把所有贡献者都应遵守的约定写进项目说明文件（`AGENTS.md`），例如：

```markdown theme={null}
# 项目约定

- 使用 bun 而非 npm 管理依赖
- API 路由使用 kebab-case 命名
- 提交前运行 `bun test`
- 优先使用函数式风格
```

## 积累与整理记忆

在日常使用中，可以让 Qoder CLI 记住反复出现的偏好和事实；随后用 `/remember` 定期评审这些自动记忆，把值得长期保留的内容晋升到项目说明或本地说明文件，并清理过期与重复条目。

## 沉淀结构化知识

对于复杂子系统，把梳理清楚的架构和约定整理成结构化知识模块并提交到项目中。这样后续无论是团队成员还是 Agent，都能复用这份知识，而不必重新探索。

<div id="how-agent-uses">
  # Agent 如何使用知识库
</div>

在完成任务时，Qoder CLI 会把知识库作为背景信息的一部分：

* **自动加载**：会话开始时，项目说明与规则、相关的长期记忆会被加载进上下文。
* **按需检索**：面对具体任务时，Agent 会检索与当前任务相关的知识（例如某个模块的说明），而不是一次性加载全部内容，以节省上下文空间。
* **作为约束**：检索到的约定和规范会作为行为约束，影响 Agent 的规划和代码生成，使产出与团队既有实践保持一致。
* **持续更新**：任务完成后，如果发现知识与代码现状不一致，可以据此更新对应的知识内容，保持知识库的准确性。

<div id="best-practices">
  # 最佳实践
</div>

* **只写会被复用的知识**：知识库的价值在于复用。放入那些能帮助后续任务做得更好、更快或更贴合团队约定的内容，而不是一次性的临时信息。
* **保持精简与准确**：项目说明文件会在每次会话加载，过长会占用上下文。把详细内容拆到结构化知识模块，说明文件里只保留纲要与索引。
* **明确层次**：所有贡献者共享的约定放项目说明；个人偏好放本地或个人级记忆；复杂子系统的深度知识放结构化知识模块。
* **定期维护**：代码演进后，及时用 `/remember` 整理记忆、更新说明文件，避免知识过期误导 Agent。
* **避免冲突与重复**：同一条约定不要在多个层次重复。发现冲突时，保留最新、最准确的一份。

<div id="next-steps">
  # 下一步
</div>

* 了解记忆的完整机制：[记忆](/zh/cli/04-扩展QoderCLI/memory)。
* 理解上下文如何协同：[上下文](/zh/cli/02-核心概念/context)。
* 用 Skills 复用团队工作流：[技能](/zh/cli/04-扩展QoderCLI/Skills)。