@tencent-ai/agent-sdk 0.3.99 → 0.3.101

package/cli/dist/web-ui/docs/cn/cli/memory.md

@@ -0,0 +1,436 @@
+# 管理 CodeBuddy 的记忆
+
+> 了解如何通过不同的记忆位置和最佳实践来管理 CodeBuddy Code 跨会话的记忆。
+
+CodeBuddy Code 可以跨会话记住您的偏好，例如代码风格指南和工作流程中的常用命令。
+
+## 确定记忆类型
+
+CodeBuddy Code 提供四种分层结构的记忆位置，每种都有不同的用途：
+
+| 记忆类型 | 位置 | 用途 | 使用场景示例 | 共享范围 |
+|---------|------|------|-------------|---------|
+| **用户记忆** | `~/.codebuddy/CODEBUDDY.md` | 适用于所有项目的个人偏好 | 代码风格偏好、个人工具快捷方式 | 仅限本人（所有项目） |
+| **用户规则** | `~/.codebuddy/rules/*.md` | 模块化的个人规则 | 个人编码习惯、常用工作流 | 仅限本人（所有项目） |
+| **项目记忆** | `./CODEBUDDY.md` 或 `./.codebuddy/CODEBUDDY.md` | 项目的团队共享指令 | 项目架构、编码标准、常用工作流程 | 通过源代码管理与团队成员共享 |
+| **项目规则** | `./.codebuddy/rules/*.md` | 模块化的、按主题划分的项目指令 | 语言特定指南、测试规范、API 标准 | 通过源代码管理与团队成员共享 |
+| **项目记忆（本地）** | `./CODEBUDDY.local.md` | 个人的项目特定偏好 | 您的沙箱 URL、首选测试数据 | 仅限本人（当前项目） |
+
+所有记忆文件在启动 CodeBuddy Code 时自动加载到上下文中。加载顺序如下：
+
+1. **用户级**：加载 `~/.codebuddy/CODEBUDDY.md` 等主文件及 `~/.codebuddy/rules/` 下的所有规则
+2. **项目级主文件**：从当前工作目录向上递归加载所有 `CODEBUDDY.md` 和 `CODEBUDDY.local.md`
+3. **项目级规则**：仅加载当前工作目录的 `.codebuddy/rules/` 下的规则（不加载父目录的规则）
+4. **子目录记忆**：当 CodeBuddy 操作子目录中的文件时，动态加载该子目录的 `CODEBUDDY.md`
+5. **本地记忆**：加载 `./CODEBUDDY.local.md`
+
+> **提示**：CODEBUDDY.local.md 文件会自动添加到 .gitignore，非常适合存储不应提交到版本控制的私有项目特定偏好。
+
+## CODEBUDDY.md 导入
+
+CODEBUDDY.md 文件可以使用 `@path/to/import` 语法导入其他文件。以下示例导入了 3 个文件：
+
+```markdown
+查看 @README 了解项目概述，@package.json 了解可用的 npm 命令。
+
+# 附加说明
+- Git 工作流程 @docs/git-instructions.md
+```
+
+支持相对路径和绝对路径。特别是，导入用户主目录中的文件是一种方便的方式，让团队成员可以提供不会提交到仓库的个人指令。导入是 CODEBUDDY.local.md 的替代方案，在多个 git worktree 之间工作得更好。
+
+```markdown
+# 个人偏好
+- @~/.codebuddy/my-project-instructions.md
+```
+
+为避免潜在冲突，代码块和代码范围内的导入不会被解析。
+
+```markdown
+此代码范围不会被视为导入：`@tencent-ai/codebuddy-code`
+```
+
+导入的文件可以递归导入其他文件，最大深度为 5 层。您可以通过运行 `/memory` 命令查看已加载的记忆文件。
+
+## CodeBuddy 如何查找记忆
+
+CodeBuddy Code 递归读取记忆：从当前工作目录开始，CodeBuddy Code 向上递归到根目录（但不包括根目录 `/`），并读取找到的任何 CODEBUDDY.md 或 CODEBUDDY.local.md 文件。这在大型仓库中特别方便，当您在 `foo/bar/` 目录中运行 CodeBuddy Code，并且在 `foo/CODEBUDDY.md` 和 `foo/bar/CODEBUDDY.md` 两处都有记忆时。
+
+CodeBuddy 还会发现当前工作目录下子树中嵌套的 CODEBUDDY.md。这些文件不会在启动时加载，只有当 CodeBuddy 读取这些子树中的文件时才会包含。
+
+## 使用 `/memory` 管理记忆
+
+在会话中使用 `/memory` 斜杠命令，打开记忆管理面板。在该面板中你可以：
+
+- 打开 Auto Memory 目录
+- 打开 `MEMORY.md` 索引文件
+- 切换 Auto Memory 开关
+
+## 设置项目记忆
+
+假设您想设置一个 CODEBUDDY.md 文件来存储重要的项目信息、约定和常用命令。项目记忆可以存储在 `./CODEBUDDY.md` 或 `./.codebuddy/CODEBUDDY.md` 中。
+
+使用以下命令为您的代码库引导一个 CODEBUDDY.md：
+
+```
+> /init
+```
+
+> **提示**：
+> - 包含常用命令（构建、测试、lint）以避免重复搜索
+> - 记录代码风格偏好和命名约定
+> - 添加项目特定的重要架构模式
+> - CODEBUDDY.md 记忆既可用于与团队共享的指令，也可用于个人偏好
+
+## 使用 `.codebuddy/rules/` 实现模块化规则
+
+对于较大的项目，您可以使用 `.codebuddy/rules/` 目录将指令组织到多个文件中。这允许团队维护专注的、组织良好的规则文件，而不是一个庞大的 CODEBUDDY.md。
+
+### 基本结构
+
+将 markdown 文件放在项目的 `.codebuddy/rules/` 目录中：
+
+```
+your-project/
+├── .codebuddy/
+│   ├── CODEBUDDY.md           # 主要项目指令
+│   └── rules/
+│       ├── code-style.md      # 代码风格指南
+│       ├── testing.md         # 测试规范
+│       └── security.md        # 安全要求
+```
+
+`.codebuddy/rules/` 中的所有 `.md` 文件都会自动作为项目记忆加载，优先级与 `.codebuddy/CODEBUDDY.md` 相同。
+
+> **注意**：项目级规则仅从当前工作目录（workDir）的 `.codebuddy/rules/` 加载，不会加载父目录的规则文件夹。这确保规则的作用域清晰明确。
+
+### 规则控制字段
+
+规则文件支持以下 YAML frontmatter 字段来控制加载和应用行为：
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `enabled` | boolean | `true` | 是否加载此规则。设为 `false` 时规则完全不加载 |
+| `alwaysApply` | boolean | `true` | 是否始终应用此规则 |
+| `paths` | string/string[] | - | 触发规则的文件路径 glob 模式 |
+
+#### 规则类型判定
+
+规则类型由 `alwaysApply` 和 `paths` 共同决定：
+
+| alwaysApply | paths | 规则类型 | 行为 |
+|-------------|-------|----------|------|
+| `true`（默认） | 任意 | ALWAYS | 始终注入到上下文 |
+| `false` | 有值 | MANUAL（条件触发） | 仅在操作匹配文件时触发 |
+| `false` | 无 | 不支持 | 规则不会加载 |
+
+#### 示例
+
+**始终应用的规则**（默认行为）：
+
+```markdown
+
+# 通用代码规范
+
+- 使用 2 空格缩进
+- 文件末尾保留空行
+```
+
+**条件触发规则**：
+
+```markdown
+---
+alwaysApply: false
+paths: src/api/**/*.ts
+---
+
+# API 开发规则
+
+- 所有 API 端点必须包含输入验证
+- 使用标准错误响应格式
+- 包含 OpenAPI 文档注释
+```
+
+**禁用规则**（临时关闭）：
+
+```markdown
+---
+enabled: false
+---
+
+# 暂时不使用的规则
+```
+
+> **注意**：`paths` 字段不仅限于 `.codebuddy/rules/` 目录，在所有记忆文件（包括 CODEBUDDY.md、CODEBUDDY.local.md）中都可以使用。
+
+### Glob 模式
+
+`paths` 字段支持标准 glob 模式，并启用了 `matchBase` 选项：
+
+| 模式 | 匹配 |
+|------|------|
+| `**/*.ts` | 任意目录下的所有 TypeScript 文件 |
+| `*.ts` | 任意目录下的所有 TypeScript 文件（matchBase 模式） |
+| `src/**/*` | `src/` 目录下的所有文件 |
+| `*.md` | 任意目录下的 Markdown 文件 |
+| `src/components/*.tsx` | 特定目录下的 React 组件 |
+
+> **matchBase 说明**：启用 matchBase 后，不包含路径分隔符的模式（如 `*.ts`）会匹配任意目录下的文件。例如 `*.ts` 可以匹配 `src/utils/helper.ts`。
+
+您可以使用大括号高效匹配多个模式：
+
+```markdown
+---
+paths: src/**/*.{ts,tsx}
+---
+
+# TypeScript/React 规则
+```
+
+这会展开匹配 `src/**/*.ts` 和 `src/**/*.tsx`。您也可以用逗号组合多个模式：
+
+```markdown
+---
+paths: {src，lib}/**/*.ts, tests/**/*.test.ts
+---
+```
+
+### 子目录
+
+规则可以组织到子目录中以获得更好的结构：
+
+```
+.codebuddy/rules/
+├── frontend/
+│   ├── react.md
+│   └── styles.md
+├── backend/
+│   ├── api.md
+│   └── database.md
+└── general.md
+```
+
+所有 `.md` 文件都会被递归发现。
+
+### 符号链接
+
+`.codebuddy/rules/` 目录支持符号链接，允许您在多个项目之间共享通用规则：
+
+```bash
+# 符号链接共享规则目录
+ln -s ~/shared-codebuddy-rules .codebuddy/rules/shared
+
+# 符号链接单个规则文件
+ln -s ~/company-standards/security.md .codebuddy/rules/security.md
+```
+
+符号链接会被解析，其内容正常加载。循环符号链接会被检测并优雅处理。
+
+### 用户级规则
+
+您可以在 `~/.codebuddy/rules/` 中创建适用于所有项目的个人规则：
+
+```
+~/.codebuddy/rules/
+├── preferences.md    # 您的个人编码偏好
+└── workflows.md      # 您首选的工作流程
+```
+
+用户级规则在项目规则之前加载，给予项目规则更高的优先级。
+
+> **最佳实践**：
+> - **保持规则专注**：每个文件应涵盖一个主题（如 `testing.md`、`api-design.md`）
+> - **使用描述性文件名**：文件名应表明规则涵盖的内容
+> - **谨慎使用条件规则**：仅当规则真正适用于特定文件类型时才添加 `paths` frontmatter
+> - **用子目录组织**：分组相关规则（如 `frontend/`、`backend/`）
+
+## 记忆最佳实践
+
+- **具体明确**："使用 2 空格缩进"比"正确格式化代码"更好。
+- **使用结构组织**：将每条记忆格式化为要点，并在描述性 markdown 标题下分组相关记忆。
+- **定期审查**：随着项目发展更新记忆，确保 CodeBuddy 始终使用最新的信息和上下文。
+
+## 设置语言偏好
+
+推荐使用 `/config` 命令配置首选响应语言（详见 [设置配置](settings.md#可用设置)），这是最简单直接的方式：
+
+```
+> /config
+# 选择 Language，输入您的首选语言，如"简体中文"
+```
+
+如果需要更细粒度的控制（如代码注释语言、提交信息语言），可以在记忆文件中添加：
+
+```markdown
+## CodeBuddy Added Memories
+
+### 语言偏好
+- 代码注释使用中文
+- 提交信息使用中文
+```
+
+项目级语言设置会覆盖用户级设置。
+
+## 分层记忆策略示例
+
+### 用户级记忆 (`~/.codebuddy/CODEBUDDY.md`)
+
+```markdown
+## CodeBuddy Added Memories
+
+### 工具偏好
+- 使用 pnpm 而非 npm
+
+### 代码偏好
+- 倾向函数式编程风格
+- 优先代码可读性
+```
+
+> **提示**：响应语言推荐通过 `/config` 设置，而非在记忆文件中配置。
+
+### 项目级记忆 (`./CODEBUDDY.md`)
+
+```markdown
+## CodeBuddy Added Memories
+
+### 项目架构
+- 使用微服务架构
+- 前端：React + TypeScript
+- 后端：Node.js + Express
+
+### 团队约定
+- PR 需要 2 人审查
+- 遵循 Conventional Commits
+```
+
+### 本地项目记忆 (`./CODEBUDDY.local.md`)
+
+```markdown
+## CodeBuddy Added Memories
+
+### 本地开发配置
+- 数据库端口：5433
+- 使用 debug 模式
+- 跳过 CI 快速测试
+```
+
+## Auto Memory 系统
+
+Auto Memory 是 CodeBuddy Code 的自动记忆系统，允许 CodeBuddy 在会话之间自动保存和检索持久化记忆。与 CODEBUDDY.md 的静态记忆不同，Auto Memory 由 CodeBuddy 在工作过程中自主决定保存什么内容。
+
+### 存储位置
+
+- **项目记忆**：`~/.codebuddy/memories/{project-id}/`
+- **全局记忆**：`~/.codebuddy/memories/global/`
+
+每个项目都有一个 `MEMORY.md` 索引文件，其前 200 行会自动加载到会话上下文。详细的记忆内容应存储在独立的主题文件中（如 `preferences.md`、`decisions.md`），并从 MEMORY.md 链接引用。
+
+### 启用与禁用
+
+- 通过 `/config` 面板切换 Auto Memory 开关
+- 通过 `/memory` 命令面板切换
+- 通过 `settings.json` 配置：`"memory": { "autoMemoryEnabled": false }`
+- 通过环境变量：`CODEBUDDY_DISABLE_AUTO_MEMORY=1`
+
+### Typed Memory 模式（Experimental）
+
+Typed Memory 是 Auto Memory 的增强版本，提供结构化的记忆类型系统。启用后，记忆文件使用 YAML frontmatter 和 4 种类型进行管理。
+
+**4 种记忆类型：**
+
+| 类型 | 用途 | 示例 |
+|------|------|------|
+| `user` | 用户的角色、目标、偏好和知识背景 | “用户是高级后端工程师，擅长 Go” |
+| `feedback` | 用户对 CodeBuddy 行为的纠正和指导 | “不要在测试中 mock 数据库” |
+| `project` | 项目进行中的工作、目标和决策 | “下周三起冻结非关键合并” |
+| `reference` | 外部系统和资源的指引 | “bug 跟踪在 Linear 项目 INGEST 中” |
+
+**记忆文件格式：**
+
+```markdown
+---
+name: 用户角色
+description: 用户的职业背景和技术专长
+type: user
+---
+
+用户是资深后端工程师，拥有 10 年 Go 语言经验，但首次接触项目的 React 前端部分。
+```
+
+**启用方式：**
+
+- 通过 `/config` 面板启用 `[Experimental] Typed Memory`
+- 通过 `settings.json` 配置：`"memory": { "typedMemory": true }`
+- 通过环境变量：`CODEBUDDY_TYPED_MEMORY_ENABLED=true`
+
+> **提示**：Typed Memory 关闭时，Auto Memory 会使用简化的通用格式，无类型系统和 YAML frontmatter。
+
+## 缓存与重载
+
+| 操作 | 重新加载 | 说明 |
+|------|---------|------|
+| 进程重启 | 是 | 缓存清空 |
+| 通过 /memory 编辑 | 是 | 自动清除缓存 |
+| /clear 命令 | 否 | 仅清除消息历史 |
+| 手动修改文件 | 否 | 需手动重启 |
+| 新增/删除规则文件 | 否 | 需手动重启 |
+
+## 常见问题
+
+**AGENTS.md 和 CODEBUDDY.md 有什么区别？**
+
+CodeBuddy Code 同时支持 AGENTS.md 和 CODEBUDDY.md 作为项目记忆文件：
+
+- **AGENTS.md 支持**：如果项目中存在 `CODEBUDDY.md` 文件，项目级记忆将使用 CODEBUDDY.md，否则使用 AGENTS.md
+- **自动检测**：系统会自动检测项目中是否存在 AGENTS.md 文件
+
+### 推荐使用 CODEBUDDY.md
+
+虽然我们保持对 AGENTS.md 的支持，但建议新项目使用 CODEBUDDY.md 作为记忆文件名，以保持与 CodeBuddy Code 品牌的一致性。
+
+**如何迁移 AGENTS.md 到 CODEBUDDY.md？**
+
+重命名 `AGENTS.md` 为 `CODEBUDDY.md` 即可。系统自动检测，CODEBUDDY.md 优先加载。
+
+**记忆文件如何同步？**
+
+- **项目记忆**：通过 Git 与团队同步
+- **用户记忆**：本地存储，不同步
+- **本地项目记忆**：本地存储，自动添加到 .gitignore
+
+**条件规则什么时候触发？**
+
+在以下情况触发：
+- 使用 `@path/to/file` 引用文件时
+- 使用 Read、Glob、Grep、Edit、Write 等文件操作工具时
+
+触发后，匹配规则会作为系统提醒注入到当前消息上下文。当所有条件规则都已注入后，不会重复注入。
+
+**如何调试规则加载问题？**
+
+1. 运行 `/memory` 查看已加载的规则列表
+2. 检查 frontmatter 格式是否正确（`---` 分隔符）
+3. 确认 glob 模式是否匹配
+4. 重启 CodeBuddy 清除缓存
+
+**规则文件大小有限制吗？**
+
+建议保持简洁。特别大的规范文档使用 `@import` 语法引用而非直接包含。
+
+## 与 CodeBuddy IDE 的兼容性
+
+CodeBuddy Code CLI 和 CodeBuddy IDE 都支持记忆/规则功能，但条件规则的触发方式不同：
+
+- **CLI**：条件规则通过 glob 模式自动匹配文件操作触发（包括 @ 引用和工具调用），不支持模型智能选择规则
+- **IDE**：条件规则支持用户通过 @RuleName 手动引用，也支持模型基于上下文智能决策激活规则
+
+
+## 相关资源
+
+- [设置配置](settings.md) - 配置 CodeBuddy Code 行为
+- [斜杠命令](slash-commands.md) - 所有可用命令
+- [快速入门](quickstart.md) - 快速上手指南
+
+---
+
+*通过有效的记忆管理，让 CodeBuddy Code 更好地理解您的需求和偏好*