diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index c51faf2a1..f67eba333 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -51,6 +51,7 @@ export default withMermaid(defineConfig({ { text: 'Model Context Protocol', link: '/zh/customization/mcp' }, { text: 'Agent Skills', link: '/zh/customization/skills' }, { text: 'Agent 与子 Agent', link: '/zh/customization/agents' }, + { text: 'AGENTS.md 项目指南', link: '/zh/customization/agents-md' }, { text: 'Print 模式', link: '/zh/customization/print-mode' }, { text: 'Wire 模式', link: '/zh/customization/wire-mode' }, ], @@ -132,6 +133,7 @@ export default withMermaid(defineConfig({ { text: 'Model Context Protocol', link: '/en/customization/mcp' }, { text: 'Agent Skills', link: '/en/customization/skills' }, { text: 'Agents and Subagents', link: '/en/customization/agents' }, + { text: 'AGENTS.md Project Guide', link: '/en/customization/agents-md' }, { text: 'Print Mode', link: '/en/customization/print-mode' }, { text: 'Wire Mode', link: '/en/customization/wire-mode' }, ], diff --git a/docs/en/customization/agents-md.md b/docs/en/customization/agents-md.md new file mode 100644 index 000000000..8fef7b4ab --- /dev/null +++ b/docs/en/customization/agents-md.md @@ -0,0 +1,95 @@ +# AGENTS.md project guide + +`AGENTS.md` is a Markdown file placed in the project root, written specifically for AI coding agents. Kimi Code CLI automatically reads it when starting a session and injects its content into the system prompt, so the agent understands the project's background, conventions, and constraints from the very first turn. + +## How it differs from README.md + +`README.md` is for human readers — it describes the project's purpose, installation steps, and usage examples. `AGENTS.md` is for AI agents — it tells the agent how to work correctly within the project. The two serve different purposes: + +| | `README.md` | `AGENTS.md` | +|---|---|---| +| Audience | Human developers and users | AI coding agents | +| Purpose | Introduce the project, guide onboarding | Provide project context and working constraints | +| Typical content | Feature overview, install steps, screenshots | Build commands, code style, directory layout, test instructions | + +A project can have both files without conflict. + +## Why you need AGENTS.md + +When an AI agent enters an unfamiliar project, it knows nothing about the project structure, tech stack, or team conventions. Without `AGENTS.md`, the agent either spends many turns exploring on its own or makes assumptions that don't match the project's norms. A good `AGENTS.md` can: + +- Reduce exploration overhead so the agent gets productive faster +- Prevent the agent from violating team code style or directory conventions +- Make common commands for building, testing, and linting immediately clear +- Inform the agent about special project restrictions (e.g., "do not modify the `generated/` directory") + +## How Kimi Code CLI loads AGENTS.md + +When creating a session, Kimi Code CLI looks for the following files in the current working directory, in order: + +1. `AGENTS.md` (uppercase) +2. `agents.md` (lowercase) + +It reads the first file found and injects the full content into the agent's system prompt via the `${KIMI_AGENTS_MD}` variable. If neither file exists, the variable is an empty string — the agent starts normally but without project context. + +::: warning Note +Kimi Code CLI only looks for `AGENTS.md` in the working directory. It does not traverse parent directories or load from the user's home directory. If your project has nested subdirectories, make sure the file is in the directory where you launch `kimi`. +::: + +## Generating AGENTS.md with /init + +Run the `/init` slash command in a Kimi Code CLI session, and the agent will automatically explore the current project directory, analyze the project structure, tech stack, build configuration, and code organization, then write the results to an `AGENTS.md` file in the working directory. + +How `/init` works: + +1. Creates a temporary isolated context to avoid polluting the current session +2. Lets the agent explore the project and generate `AGENTS.md` in that temporary context +3. Loads the generated file content back into the current session + +If an `AGENTS.md` already exists in the working directory, `/init` will reference its existing content when overwriting. After generation, you should review the file and make corrections or additions as needed. + +## Recommended content + +A practical `AGENTS.md` typically includes the following (include what's relevant — you don't need to cover everything): + +**Project overview** — One or two paragraphs explaining what the project is, what tech stack it uses, and what scenarios it targets. Assume the reader knows nothing about the project. + +**Build and test commands** — List the most common commands for daily development, for example: + +```sh +# Install dependencies +npm install + +# Run tests +npm test + +# Build the project +npm run build + +# Lint check +npm run lint +``` + +**Code style** — Describe the coding conventions the project follows, such as indentation style, naming conventions, import ordering rules, and whether specific linter configurations are used. + +**Directory layout** — Briefly describe the purpose of main directories, such as `src/` for source code, `tests/` for tests, `docs/` for documentation, etc. For large projects, helping the agent quickly locate where code lives is valuable. + +**Common workflows** — Describe the team's development habits, such as branching strategy, commit message format, and PR process. + +**Constraints and restrictions** — Explicitly tell the agent what it should not do, for example: + +- Do not modify auto-generated files +- Do not commit directly to the `main` branch +- Tests must run in a specific environment + +## When to update AGENTS.md + +`AGENTS.md` is not a write-once-and-forget file. Consider updating it when: + +- The project's tech stack or build system changes +- Important directories or modules are added +- Code conventions are adjusted (e.g., switching linter tools or style configurations) +- Team conventions change (e.g., branching strategy, commit format) +- You notice the agent repeatedly making a specific mistake — document the correct approach + +You can rerun `/init` at any time to let the agent regenerate the content, or edit the file manually. Keeping `AGENTS.md` in sync with the actual project state is key to the agent working effectively over time. diff --git a/docs/en/customization/agents.md b/docs/en/customization/agents.md index 61b891302..ed8c3924c 100644 --- a/docs/en/customization/agents.md +++ b/docs/en/customization/agents.md @@ -2,6 +2,8 @@ An agent defines the AI's behavior, including system prompts, available tools, and subagents. You can use built-in agents or create custom agents. +To learn how to provide project context to the agent via an `AGENTS.md` file, see [AGENTS.md project guide](./agents-md.md). + ## Built-in agents Kimi Code CLI provides two built-in agents. You can select one at startup with the `--agent` flag: diff --git a/docs/en/guides/interaction.md b/docs/en/guides/interaction.md index 3f0e96de2..0451f54ad 100644 --- a/docs/en/guides/interaction.md +++ b/docs/en/guides/interaction.md @@ -162,3 +162,46 @@ When YOLO mode is enabled, a yellow YOLO badge appears in the status bar at the ::: warning Note YOLO mode skips all confirmations. Make sure you understand the potential risks. It's recommended to only use this in controlled environments. ::: + +## Security boundaries + +Kimi Code CLI runs directly in your terminal with no sandbox isolation. Shell commands, file operations, and MCP tool calls executed by the agent take effect in your real operating system environment — no different from running commands manually in your terminal. Understanding these boundaries helps you use Kimi Code CLI safely. + +### Workspace scope + +The agent's file operations are centered around the working directory. Read-only tools like `ReadFile`, `Glob`, and `Grep` can access files within the working directory using relative paths, or read files outside it using absolute paths. `WriteFile` and `StrReplaceFile` work the same way, but all write and edit operations require user approval. + +Using the `--add-dir` startup flag or the `/add-dir` command during a session, you can add extra directories to the workspace. Once added, these directories have equal standing with the main working directory — the agent can freely read and write files in them (writes still require approval). Information about additional directories is passed to the system prompt via the `${KIMI_ADDITIONAL_DIRS_INFO}` variable. + +### What operations require approval + +In the default mode, the following operations request your confirmation before each execution: + +| Operation | Approval granularity | +|-----------|---------------------| +| `Shell` command execution | Each command | +| `WriteFile` file writes | Each write | +| `StrReplaceFile` file edits | Each edit | +| MCP tool calls | Each call | + +Read-only tools (`ReadFile`, `ReadMediaFile`, `Glob`, `Grep`, `SearchWeb`, `FetchURL`) do not require approval. + +You can select "Allow for this session" to automatically approve similar operations for the current session. This decision is persisted with the session state and automatically restored when resuming. + +### Risks of YOLO mode + +When YOLO mode is enabled (`kimi --yolo` or `/yolo`), all approval requests are automatically granted. The agent can execute arbitrary shell commands and file modifications without confirmation. This means: + +- The agent can delete files, overwrite code, and perform destructive git operations +- If the agent misunderstands the task, it may make irreversible changes +- If the project has MCP tools configured, those tools are also automatically approved + +Use YOLO mode only when: the project has solid version control, you are running in a recoverable environment such as a container or VM, or you are performing a well-defined low-risk task. + +### MCP tool risk boundaries + +MCP tools are provided by external MCP servers, and their behavior is not controlled by Kimi Code CLI. Each MCP tool call requires user approval by default, but is automatically approved in YOLO mode. When using MCP tools, keep in mind: + +- MCP servers may access the network, databases, or other external resources +- MCP tool inputs and outputs pass through the agent, which may take further actions based on the results +- Make sure you trust the MCP servers you have configured and understand the scope of their tools diff --git a/docs/en/index.md b/docs/en/index.md index af98035da..3b2a8f558 100644 --- a/docs/en/index.md +++ b/docs/en/index.md @@ -12,3 +12,17 @@ hero: text: GitHub link: https://github.com/MoonshotAI/kimi-cli --- + +
+ +## Where to start + +**First time here?** Start with [Getting Started](./guides/getting-started.md) to learn about installation, configuration, and basic usage. + +**Want to understand how the agent works?** [Interaction and Input](./guides/interaction.md) covers agent mode, plan mode, and security boundaries. [Agents and Subagents](./customization/agents.md) explains built-in agents, custom agents, and the subagent mechanism. [AGENTS.md Project Guide](./customization/agents-md.md) shows how to use `AGENTS.md` to help the agent understand your project. + +**Want to configure models, providers, or MCP?** [Providers and Models](./configuration/providers.md) explains how to switch providers and models. [MCP](./customization/mcp.md) covers Model Context Protocol configuration and usage. [Config Files](./configuration/config-files.md) lists all available configuration options. + +**Want IDE, ACP, Wire, or print mode integration?** [Using in IDEs](./guides/ides.md) explains how to use Kimi Code CLI in VS Code and JetBrains. [Integrations with Tools](./guides/integrations.md) covers ACP and other integration methods. [Wire Mode](./customization/wire-mode.md) and [Print Mode](./customization/print-mode.md) provide detailed configuration for non-interactive integrations. + +
diff --git a/docs/zh/customization/agents-md.md b/docs/zh/customization/agents-md.md new file mode 100644 index 000000000..61ec17fd4 --- /dev/null +++ b/docs/zh/customization/agents-md.md @@ -0,0 +1,95 @@ +# AGENTS.md 项目指南 + +`AGENTS.md` 是放在项目根目录的 Markdown 文件，专门写给 AI 编程 Agent 阅读。Kimi Code CLI 每次启动会话时会自动读取它，并将内容注入系统提示词，让 Agent 从第一轮对话开始就了解项目的背景、规范和约束。 + +## 和 README.md 的区别 + +`README.md` 面向人类读者——介绍项目用途、安装步骤、使用示例等。`AGENTS.md` 面向 AI Agent——告诉它如何在这个项目中正确地工作。两者的侧重点不同： + +| | `README.md` | `AGENTS.md` | +|---|---|---| +| 读者 | 人类开发者、用户 | AI 编程 Agent | +| 目的 | 介绍项目、引导上手 | 提供项目上下文和工作约束 | +| 典型内容 | 功能说明、安装步骤、截图 | 构建命令、代码风格、目录说明、测试指令 | + +一个项目可以同时拥有两个文件，互不冲突。 + +## 为什么需要 AGENTS.md + +AI Agent 在进入一个陌生项目时，对项目结构、技术栈和团队约定一无所知。如果没有 `AGENTS.md`，Agent 要么花大量轮次自行探索，要么做出与项目规范不符的假设。一份好的 `AGENTS.md` 可以： + +- 减少 Agent 的探索成本，让它更快进入工作状态 +- 避免 Agent 违反团队的代码风格或目录约定 +- 让构建、测试、lint 等常用命令一目了然 +- 告知 Agent 项目的特殊限制（例如 "不要修改 `generated/` 目录"） + +## Kimi Code CLI 如何加载 AGENTS.md + +Kimi Code CLI 在创建会话时，会在当前工作目录下依次查找以下文件： + +1. `AGENTS.md`（大写） +2. `agents.md`（小写） + +找到第一个存在的文件后读取其全部内容，通过 `${KIMI_AGENTS_MD}` 变量注入 Agent 的系统提示词。如果两个文件都不存在，该变量为空字符串，Agent 正常启动但不会获得项目上下文。 + +::: warning 注意 +Kimi Code CLI 只在工作目录下查找 `AGENTS.md`，不会向上遍历父目录，也不会从用户主目录加载。如果你的项目有多级子目录，请确保在你启动 `kimi` 的目录下放置文件。 +::: + +## 用 /init 生成 AGENTS.md + +在 Kimi Code CLI 会话中运行 `/init` 斜杠命令，Agent 会自动探索当前项目目录，分析项目结构、技术栈、构建配置和代码组织方式，然后将结果写入工作目录下的 `AGENTS.md` 文件。 + +`/init` 的工作方式： + +1. 创建一个临时的独立上下文，避免污染当前会话 +2. 在临时上下文中让 Agent 探索项目并生成 `AGENTS.md` +3. 将生成的文件内容加载回当前会话 + +如果工作目录下已存在 `AGENTS.md`，`/init` 会参考已有内容进行更新覆写。生成后你应当检查文件内容，根据实际情况进行修正和补充。 + +## 推荐写哪些内容 + +一份实用的 `AGENTS.md` 通常包含以下内容（按需取舍，不必面面俱到）： + +**项目概览**——用一两段话说明项目是什么、使用什么技术栈、面向什么场景。假设读者对项目一无所知。 + +**构建与测试命令**——列出日常开发中最常用的命令，例如： + +```sh +# 安装依赖 +npm install + +# 运行测试 +npm test + +# 构建项目 +npm run build + +# lint 检查 +npm run lint +``` + +**代码风格**——说明项目遵循的代码规范，例如缩进风格、命名约定、导入排序规则、是否使用特定的 linter 配置等。 + +**目录说明**——简要描述主要目录的用途，例如 `src/` 存放源代码、`tests/` 存放测试、`docs/` 存放文档等。对于大型项目，帮助 Agent 快速定位代码所在位置很有价值。 + +**常见工作流**——描述团队的开发习惯，例如分支策略、提交信息格式、PR 流程等。 + +**约束与限制**——明确告知 Agent 不应该做的事情，例如： + +- 不要修改自动生成的文件 +- 不要直接提交到 `main` 分支 +- 测试必须在某个特定环境下运行 + +## 什么时候需要更新 AGENTS.md + +`AGENTS.md` 不是写一次就永远不变的文件。以下情况下建议同步更新： + +- 项目的技术栈或构建系统发生变化 +- 新增了重要目录或模块 +- 代码规范有调整（如切换了 linter 工具或风格配置） +- 团队约定发生变化（如分支策略、提交格式） +- 发现 Agent 反复犯某个错误——把正确做法写进去 + +你可以随时重新运行 `/init` 让 Agent 重新生成内容，也可以手动编辑。保持 `AGENTS.md` 与项目实际状态一致，是让 Agent 持续高效工作的关键。 diff --git a/docs/zh/customization/agents.md b/docs/zh/customization/agents.md index 8a146b670..918311c22 100644 --- a/docs/zh/customization/agents.md +++ b/docs/zh/customization/agents.md @@ -2,6 +2,8 @@ Agent 定义了 AI 的行为方式，包括系统提示词、可用工具和子 Agent。你可以使用内置 Agent，也可以创建自定义 Agent。 +如果你想了解如何通过 `AGENTS.md` 文件为 Agent 提供项目上下文，请参阅 [AGENTS.md 项目指南](./agents-md.md)。 + ## 内置 Agent Kimi Code CLI 提供两个内置 Agent。启动时可以通过 `--agent` 参数选择： diff --git a/docs/zh/guides/interaction.md b/docs/zh/guides/interaction.md index a439766ee..94988d0ed 100644 --- a/docs/zh/guides/interaction.md +++ b/docs/zh/guides/interaction.md @@ -163,3 +163,46 @@ kimi --yolo YOLO 模式会跳过所有确认，请确保你了解可能的风险。建议仅在可控环境中使用。 ::: +## 安全边界 + +Kimi Code CLI 直接运行在你的终端中，没有沙箱隔离。Agent 执行的 Shell 命令、文件读写和 MCP 工具调用都在你的真实操作系统环境中生效，与你在终端手动执行命令没有本质区别。理解这些边界有助于安全地使用 Kimi Code CLI。 + +### 工作区范围 + +Agent 的文件操作默认围绕工作目录进行。`ReadFile`、`Glob`、`Grep` 等只读工具可以使用相对路径访问工作目录内的文件，也可以使用绝对路径读取工作目录外的文件。`WriteFile` 和 `StrReplaceFile` 同样如此，但所有写入和编辑操作都需要用户审批。 + +通过 `--add-dir` 启动参数或会话中的 `/add-dir` 命令，你可以将额外目录加入工作区。添加后，这些目录和主工作目录享有同等地位——Agent 可以在其中自由读写文件（写入仍需审批）。额外目录的信息通过 `${KIMI_ADDITIONAL_DIRS_INFO}` 变量传递给系统提示词。 + +### 哪些操作需要审批 + +在默认模式下，以下操作每次执行前都会请求你的确认： + +| 操作 | 审批粒度 | +|------|---------| +| `Shell` 命令执行 | 每条命令 | +| `WriteFile` 写入文件 | 每次写入 | +| `StrReplaceFile` 编辑文件 | 每次编辑 | +| MCP 工具调用 | 每次调用 | + +只读工具（`ReadFile`、`ReadMediaFile`、`Glob`、`Grep`、`SearchWeb`、`FetchURL`）不需要审批。 + +你可以选择 "本会话允许" 来自动批准当前会话中的同类操作。该决策会随会话状态持久化，恢复会话时自动还原。 + +### YOLO 模式的风险 + +开启 YOLO 模式（`kimi --yolo` 或 `/yolo`）后，所有审批请求会被自动通过，Agent 可以不经确认地执行任意 Shell 命令和文件修改。这意味着： + +- Agent 可以删除文件、覆写代码、执行破坏性的 git 操作 +- 如果 Agent 对任务理解有偏差，可能造成不可逆的改动 +- 如果项目中配置了 MCP 工具，这些工具也会被自动批准执行 + +建议仅在以下场景使用 YOLO 模式：项目有完善的版本控制、在容器或虚拟机等可恢复的环境中运行、或者你正在执行明确且低风险的任务。 + +### MCP 工具的风险边界 + +MCP 工具由外部 MCP 服务器提供，其行为不受 Kimi Code CLI 控制。每次 MCP 工具调用默认需要用户审批，但在 YOLO 模式下会自动通过。使用 MCP 工具时需注意： + +- MCP 服务器可能访问网络、数据库或其他外部资源 +- MCP 工具的输入输出经过 Agent，Agent 可能基于这些结果采取进一步操作 +- 确保你信任所配置的 MCP 服务器，并了解其工具的能力范围 + diff --git a/docs/zh/index.md b/docs/zh/index.md index 5ce3084e6..dc9ec771a 100644 --- a/docs/zh/index.md +++ b/docs/zh/index.md @@ -12,3 +12,17 @@ hero: text: GitHub link: https://github.com/MoonshotAI/kimi-cli --- + +
+ +## 从哪里开始 + +**第一次使用？** 从 [开始使用](./guides/getting-started.md) 了解安装、配置和基本用法。 + +**想理解 Agent 如何工作？** [交互与输入](./guides/interaction.md) 介绍 Agent 模式、Plan 模式和安全边界。[Agent 与子 Agent](./customization/agents.md) 介绍内置 Agent、自定义 Agent 和子 Agent 机制。[AGENTS.md 项目指南](./customization/agents-md.md) 讲解如何用 `AGENTS.md` 让 Agent 理解你的项目。 + +**想配置模型、供应商或 MCP？** [平台与模型](./configuration/providers.md) 说明如何切换供应商和模型。[MCP](./customization/mcp.md) 介绍 Model Context Protocol 的配置和使用。[配置文件](./configuration/config-files.md) 列出所有可用的配置项。 + +**想做 IDE、ACP、Wire 或 Print 模式集成？** [在 IDE 中使用](./guides/ides.md) 说明如何在 VS Code 和 JetBrains 中使用。[集成到工具](./guides/integrations.md) 介绍 ACP 和其他集成方式。[Wire 模式](./customization/wire-mode.md) 和 [Print 模式](./customization/print-mode.md) 提供非交互式集成的详细配置。 + +