恭喜 了解如何安装 Amp。本手册帮助你充分利用它。

为什么选择 Amp？

Amp 是面向终端和编辑器的前沿编程代理。

• 多模型： GPT-5.5, Opus 4.7, 快速模型——Amp 会根据每个模型最擅长的任务使用它们。
• 有态度： 你始终在使用 Amp 最好的部分。如果我们自己不使用和喜爱某个功能，我们就会砍掉它。
• 在前沿： Amp 追随模型的发展方向前进。没有向后兼容，没有遗留功能。
• 对话： 你可以保存和分享你与 Amp 的交互。你不会在没有版本控制的情况下写代码吧？

Amp 有 3 种模式：smart（无约束的最先进模型使用）、deep（针对复杂问题进行带扩展思考的深度推理）、rush（更快、更便宜，适合小型、定义明确的任务）。

想要更深入了解？请关注我们的 Raising an Agent 播客 ，我们会在那里分享构建 Amp 过程中的经验。

快速开始

1. 登录 ampcode.com/install.
2. 按照说明安装 Amp CLI。
3. Run amp.

你已准备好 use Amp!

Installation

Staying Current

Run amp update.

IDE 集成

登录 ampcode.com/install 并按照说明操作，或者：

• JetBrains（IntelliJ、WebStorm、GoLand 等）： 安装 Amp CLI，然后运行 amp --jetbrains.
• Neovim： 安装 Amp CLI 和 Amp Neovim 插件，然后运行 amp.
• VS Code 及基于 VS Code 的编辑器（Cursor、Windsurf 等）： 安装 Amp CLI，确保你的编辑器正在运行，然后运行 amp.
• Zed： 安装 Amp CLI，确保 Zed 正在运行，然后运行 amp.

通过打开命令面板（Ctrl+O）并选择 ide connect.

使用 Amp

Agent 模式

Amp 有 3 种模式：smart（无约束的最先进模型使用）、deep（针对复杂问题进行带扩展思考的深度推理）、rush（更快、更便宜，适合小型、定义明确的任务）。

• smart：使用最先进的模型，无约束限制，提供最大能力和自主性。
• deep：使用 GPT-5.5 进行深度推理，适合需要长时间思考的复杂问题。
• rush：更快、更便宜，但能力较弱，适合小型、定义明确的任务。请参阅 Rush 模式.

还有一种不推荐使用的模式： large 模式.

参阅 模型 了解各模式使用的模型。

在 CLI 中通过打开命令面板（Ctrl+O）并输入 mode.

如何编写提示词

Amp 的 large 模式目前使用 Claude Opus 4.7，输入上下文最多 300k token。为获得最佳结果，请遵循以下建议：

• 明确表达你的需求。不要问"你能做 X 吗？"，直接说"做 X。"
• 保持简短和专注。将大型任务分解为小的子任务，每个对话处理一个。不要在同一个对话中让代理既写数据库迁移又修改文档页面的 CSS。
• 不要让模型去猜测。如果你知道如何实现你想要代理做的事情——要查看哪些文件、要运行哪些命令——写在你的提示词中。
• 如果你希望模型只做研究和规划而不写代码，明确说明："只规划如何实现这个功能。不要写任何代码。"
• 使用 AGENTS.md 文件重复此操作 来指导 Amp 如何运行测试、构建步骤以及避免常见错误。
• 当对话积累了太多噪声时果断放弃。有时出错和失败的尝试会用错误信息填满上下文窗口。在这种情况下，最好开始一个新的对话，使用干净的上下文窗口。
• 告诉代理如何最好地审查自己的工作：运行什么命令或测试、打开什么 URL、查看哪些日志。反馈对代理的帮助和对我们一样大。

对话中的第一条提示词非常重要。它决定了后续对话的方向。我们鼓励你认真对待。在 Amp CLI 中， Enter 提交，你可以使用 Shift+Enter （需终端支持）或 Ctrl+J 来插入换行。

以下是我们在 Amp 中使用过的提示词示例：

• “Make observeThreadGuidanceFiles return Omit<ResolvedGuidanceFile, 'content'>[] and remove that field from its return value, and update the tests. Note that it is omitted because this is used in places that do not need the file contents, and this saves on data transferred over the view API.” (查看对话)
• “Run <build command> and fix all the errors”
• “Look at <local development server url> to see this UI component. Then change it so that it looks more minimal. Frequently check your work by screenshotting the URL”
• “Run git blame on the file I have open and figure out who added that new title”
• “Convert these 5 files to use Tailwind, use one subagent per file”
• “Take a look at git diff — someone helped me build a debug tool to edit a Thread directly in JSON. Please analyze the code and see how it works and how it can be improved. […]” (查看对话)
• “Check git diff --staged and remove the debug statements someone added” (查看对话)
• “Find the commit that added this using git log, look at the whole commit, then help me change this feature”
• “Explain the relationship between class AutoScroller and ViewUpdater using a diagram”
• “Run psql 并重新连接所有的 threads in the databaser to my user (email starts with thorsten)” (查看对话)

另请参阅 Thorsten Ball 的 我如何使用 Amp.

如果你在工作区中，使用 Amp 的 对话分享 以互相学习。

AGENTS.md

Amp 会在 AGENTS.md 文件来指导代码库结构、构建/测试命令和约定。

Amp 包含 AGENTS.md 文件：

• AGENTS.md 当前工作目录（或编辑器工作区根目录）中的文件 和 父目录（向上到 $HOME）始终会被包含。
• 子目录 AGENTS.md 文件会在代理读取该子目录中的文件时被包含。
• 系统级指导文件，以及 $HOME/.config/amp/AGENTS.md 和 $HOME/.config/AGENTS.md如果存在，都会始终包含。

如果没有 AGENTS.md 存在于某个目录中，但名为 AGENT.md （没有 S) or CLAUDE.md 的文件确实存在，该文件将被包含。

在具有多个子项目的大型仓库中，我们建议保持顶级 AGENTS.md 通用的，并创建更具体的 AGENTS.md 文件，并在每个子项目的子目录中创建更具体的

要查看 Amp 正在使用的 agent 文件，选择 agents-md list 从命令面板中。

编写 AGENTS.md 文件

Amp 提供生成 AGENTS.md 文件（如果不存在）。你可以创建或更新任何 AGENTS.md 文件，手动或让 Amp 帮你（“Update AGENTS.md based on what I told you in this thread”).

要包含其他文件作为上下文，在 agent 文件中用 @-提及它们。例如：

See @doc/style.md and @specs/**/*.md.

When making commits, see @doc/git-commit-instructions.md.

• 相对路径相对于包含引用的 agent 文件进行解释。
• 绝对路径和 @~/some/path 也受支持。
• 代码块中的 @-提及会被忽略，以避免误判。
• Glob 模式受支持（如 @doc/*.md 或 @.agent/**/*.md).

精细化指导

要提供仅在处理某些文件时适用的指导，你可以指定 globs 在提及文件的 YAML 前言中。

例如，要应用语言特定的编码规则：

1. 将 See @docs/*.md 在你的 AGENTS.md 文件中。

2. 创建文件 docs/typescript-conventions.md 包含：

   ---
   globs:
     - '**/*.ts'
     - '**/*.tsx'
   ---
   
   Follow these TypeScript conventions:
   
   - Never use the `any` type
   - ...

3. 对其他语言重复上述步骤。

带有 globs 的被引用文件，只有当 Amp 读取了与任何 glob 匹配的文件时才会被包含（在上面的示例中，任何 TypeScript 文件）。如果没有 globs 被指定，文件在被 @-提及时始终会被包含。

Glob 模式会隐式添加 **/ 前缀，除非它们以 ../ 或 ./开头，在这种情况下它们引用的是相对于被提及文件的路径。

其他示例：

• 前端特定指导： globs: ["src/components/**", "**/*.tsx"]
• 后端指导： globs: ["server/**", "api/**"]
• 测试指导： globs: ["*.test.ts", "__tests__/*"]

引用其他对话

你可以通过对话 URL（例如 https://ampcode.com/threads/T-7f395a45-7fae-4983-8de0-d02e61d30183）或对话 ID（例如 @T-7f395a45-7fae-4983-8de0-d02e61d30183）在你的提示词中引用其他 Amp 对话。

输入 @@ 来搜索要提及的对话。

对于每个被提及的对话，Amp 会读取并提取与你当前任务相关的信息。这对于从之前的对话中继续工作或复用技术非常有用。

示例：

• Implement the plan from https://ampcode.com/threads/T-7f395a45-7fae-4983-8de0-d02e61d30183
• Apply the same fix from @T-7f395a45-7fae-4983-8de0-d02e61d30183 to the form here

查找对话

Amp 可以搜索你过去的对话和工作区成员的对话，以查找相关对话。你可以按关键词、文件路径、仓库、作者、日期或任务让 Amp 查找对话。

示例：

• Find threads where we discussed the monorepo migration
• Show me threads that modified src/server/index.ts
• Find Thorsten's threads on the indexing logic
• Show me my recent threads from the last week
• Which threads worked on task 142?
• Find threads related to this one

归档对话

当你归档一个对话时，它不再出现在你的活跃对话列表中，但仍然可以在网页上查看并 通过 @-提及来引用.

要归档对话，从命令面板中运行 thread: archive and quit （在 CLI 中）。

附加图片

你可以将图片（如截图和图表）附加到你的消息中。

在 CLI 中，按 Ctrl+V 从剪贴板粘贴图片。注意你必须使用 Ctrl+V，而不是 Cmd+V，即使在 macOS 上也是如此。在 Windows 上，如果 Ctrl+V 不起作用，请按 Ctrl+O 并运行 paste image from clipboard 在 Amp 命令面板中执行。

在 Windows 上，图片粘贴在 WezTerm 或 Alacritty 中比在 Windows Terminal 中更可靠。

你也可以通过文件路径 @-提及图片。

提及文件

输入 @ 搜索要提及的文件。

Edit

要在 CLI 中编辑之前的消息，按 Tab 导航到之前的消息，然后按 e.

消息队列

你可以在代理结束当前轮次后排队发送消息，而不中断其当前工作。在 CLI 中，先起草你的下一条提示词，然后打开命令面板并运行 queue.

工具

Amp 代表你运行工具和 shell 命令来检查代码、运行测试并快速迭代。

默认情况下，Amp 在运行工具前不会请求批准。

Amp 会基于工作区中的内容行动。不受信任的仓库、MCP 服务器和其他外部输入都可能影响 Amp 的行为。如果你经常处理不受信任的来源，请考虑创建自定义策略插件，或使用隔离的开发环境。

内置工具

你可以通过运行以下命令查看 Amp 的内置工具 amp tools list （在 CLI 中）。

工具箱

工具箱允许你用简单的脚本来扩展 Amp，而无需提供 MCP 服务器。

当 Amp 启动时，它会调用由 AMP_TOOLBOX， 并将环境变量 TOOLBOX_ACTION 设置为 describe.

工具应将其描述写入 stdout ，以键值对列表的形式，每行一个。

#!/usr/bin/env bun

const action = process.env.TOOLBOX_ACTION

if (action === 'describe') showDescription()
else if (action === 'execute') runTests()

function showDescription() {
	process.stdout.write(
		[
			'name: run-tests',
			'description: use this tool instead of Bash to run tests in a workspace',
			'dir: string the workspace directory',
		].join('\n'),
	)
}

当 Amp 决定使用你的工具时，它会再次运行该可执行文件， 设置 TOOLBOX_ACTION to execute.

工具以相同的格式在 stdin 上接收参数，然后执行其工作：

function runTests() {
	let dir = require('fs')
		.readFileSync(0, 'utf-8')
		.split('\n')
		.filter((line) => line.startsWith('dir: '))

	dir = dir.length > 0 ? dir[0].replace('dir: ', '') : '.'

	require('child_process').spawnSync('pnpm', ['-C', dir, 'run', 'test', '--no-color', '--run'], {
		stdio: 'inherit',
	})
}

如果你的工具需要对象或数组参数，可执行文件可以将其 工具 schema 以 JSON 格式写入 stdout。在这种情况下，它也会以 JSON 形式接收输入。

我们建议使用工具来表达具体的、确定性的和项目本地的行为，例如：

• 查询开发数据库，
• 在项目中运行测试和构建操作，
• 以受控方式暴露 CLI 工具。

参阅 附录 了解完整的技术参考。

Agent 技能

技能是指令和资源的集合，教导代理如何执行特定任务。Amp 包含内置技能，你可以安装或创建自己的技能——可以是项目特定的（.agents/skills/）或用户级别的（~/.config/agents/skills/).

创建技能

Amp 有一个内置的 building-skills 技能，可以创建适合你的代码库、工作流和系统的技能。要创建一个，只需提问：

Create a skill for deploying to staging

要求"项目特定技能"以保存到当前项目，或"用户级技能"以跨所有项目个人使用。项目技能存放在 .agents/skills/ 中，可以提交到 git，这样你的团队就能自动获取它们。

技能优先级（先匹配的优先）：

• ~/.config/agents/skills/
• ~/.config/amp/skills/
• .agents/skills/
• .claude/skills/
• ~/.claude/skills/
• 插件、工具箱目录和内置技能

查看技能

要查看已安装的技能，请使用命令面板（Ctrl+O 在 CLI 中）：

• skill: list ——查看已安装的技能

技能格式

每个技能是一个包含 SKILL.md 文件的目录，带有 YAML 前言：

---
name: my-skill
description: A description of what this skill does
---

# My Skill Instructions

Detailed instructions for the agent...

该 name 和 description 始终对模型可见，并决定何时调用该技能。名称必须唯一——项目特定技能优先于用户级技能，两者都覆盖内置技能。 SKILL.md 内容仅在技能被调用时按需加载。

技能可以在同一目录中包含捆绑的资源（脚本、模板等），代理可以相对于技能文件来访问这些资源。

技能中的 MCP 服务器

技能可以通过包含一个 mcp.json 文件来捆绑 MCP 服务器。服务器在 Amp 启动时启动，但其工具在技能加载前保持隐藏。这是使用 MCP 服务器的推荐方式——与直接将服务器添加到 Amp 配置相比，它保持工具列表整洁并减少上下文膨胀。

示例 mcp.json （本地命令式服务器）：

{
	"chrome-devtools": {
		"command": "npx",
		"args": ["-y", "chrome-devtools-mcp@latest"],
		"includeTools": ["navigate_*", "take_screenshot", "click", "fill*"]
	}
}

示例 mcp.json （远程 HTTP 服务器）：

{
	"linear": {
		"url": "https://mcp.linear.app/sse",
		"includeTools": ["list_issues", "create_issue", "update_issue"]
	}
}

本地服务器字段：

• command (string）——要运行的命令
• args (string[]，可选）——命令参数
• env (object，可选）——环境变量

远程服务器字段：

• url (string）——服务器端点
• headers (object，可选）——随请求发送的 HTTP 头

通用字段：

• includeTools (string[]，可选但推荐）——工具名称或 glob 模式，用于过滤暴露的工具

子代理

Amp 可以生成子代理（通过 Task 工具）来处理受益于独立执行的复杂任务。每个子代理都有自己的上下文窗口和对文件编辑、终端命令等工具的访问权限。

子代理最适用于可以分解为独立部分的多步骤任务、产生大量输出但完成后不再需要的操作、在不同代码区域的并行工作，以及在协调复杂工作时保持主对话上下文的整洁。

但是，子代理是隔离工作的——它们无法相互通信，你无法在任务中途引导它们，它们从零开始而没有你对话中积累的上下文，主代理只接收它们的最终总结而不是监控它们的逐步工作。

Amp 可能会自动使用子代理来处理合适的任务，或者你可以通过提到子代理或建议并行工作来鼓励使用它们。

Oracle

Amp 可以使用一个强大的“第二意见”模型，该模型更适合复杂的推理或分析任务，但代价是稍慢、稍贵，且不如主代理的模型适合日常代码编辑任务。

这个模型通过一个名为 oracle的工具提供给 Amp 的主代理使用，它目前使用 GPT-5.4，推理级别为 high。

主代理可以自主决定在调试或审查复杂代码时向 oracle 寻求帮助。我们有意不强制主代理 始终 使用 oracle，因为成本更高且推理速度更慢。

我们建议在你认为有帮助的时候明确要求 Amp 的主代理使用 oracle。以下是我们自己使用 Amp 的一些示例：

• “Use the oracle to review the last commit’s changes. I want to make sure that the actual logic for when an idle or requires-user-input notification sound plays has not changed.”
• “Ask the oracle whether there isn’t a better solution.”
• “I have a bug in these files: … It shows up when I run this command: … Help me fix this bug. Use the oracle as much as possible, since it’s smart.”
• “Analyze how the functions foobar 和 barfoo are used. Then I want you to work a lot with the oracle to figure out how we can refactor the duplication between them while keeping changes backwards compatible.”

参阅 GPT-5 oracle 发布公告 了解更多信息。

Librarian

Amp 可以使用 Librarian 子代理搜索远程代码库。 Librarian 可以搜索和读取 GitHub 上的所有公开代码以及你的私有 GitHub 仓库。

当你需要进行跨仓库研究时，或者例如当你想让它读取你正在使用的框架和库的代码时，告诉 Amp 召唤 Librarian。 Librarian 的回答通常更长、更详细，因为我们将其设计为提供深入的解释。 Librarian 只会搜索仓库默认分支上的代码。

你可能需要明确提示主代理使用 Librarian。以下是一些示例：

• “Explain how new versions of our documentation are deployed when we release. Search our docs and infra repositories to see how they get to X.Y.sourcegraph.com.”
• “I have a bug in this validation code using Zod, it’s throwing a weird error. Ask the Librarian to investigate why the error is happening and show me the logic causing it.”
• “Use the Librarian to investigate the foo service - were there any recent changes to the API endpoints I am using in bar? If so, what are they and when were they merged?”

参阅 Librarian 发布公告 了解更多信息。

GitHub

你需要在 你的设置 中配置与 GitHub 的连接才能使用它。 如果你想让 Librarian 能够查看你的私有仓库，你需要在配置 GitHub 连接时选择它们。 参阅 GitHub 的文档了解 安装 和 授权 GitHub 应用了解更多信息。

Bitbucket Enterprise

Librarian 还可以搜索和读取 Bitbucket Enterprise（Bitbucket Data Center / Server）实例上的代码。设置需要两个步骤：

1. 工作区管理员：通过工作区连接页面（工作区设置 → 连接).
2. 每个用户：将你的个人访问令牌添加到你的 配置文件:

"amp.bitbucketToken": "YOUR_PERSONAL_ACCESS_TOKEN"

要创建个人访问令牌，前往你的 Bitbucket Enterprise 实例 → 账户 → HTTP 访问令牌 → 创建令牌 与 仓库读取 权限。

Painter

Amp 可以使用 Painter 工具生成和编辑图片，由 Gemini 3 Pro Image 驱动。

当你需要创建 UI 原型图、应用图标、主页横幅图或编辑现有图片（如遮盖截图中的敏感信息）时，告诉 Amp 使用 Painter。 你还可以在提示词中 @-提及图片文件来提供最多 3 张参考图片，用于风格指导或编辑。

你可能需要明确提示 Amp 使用 Painter。以下是一些示例：

• “Use the painter to create a UI mockup for my settings page.”
• “Use the painter to generate an app icon for my CLI tool. Dark background with a glowing terminal cursor in cyan.”
• “Use the painter to redact any visible API keys or passwords in this terminal screenshot.”

参阅 Painter 发布公告 了解更多信息。

代码审查

Amp 可以审查你的代码中的 bug、安全问题、性能问题和风格违规——运行 amp review （在 CLI 中）或直接让主代理审查你的更改。

检查项

检查项是用户定义的审查标准，适用于代码库的特定部分。它们让你将团队约定、安全不变量和 linter 无法捕获的最佳实践编码化。在代码审查期间，Amp 会为每个检查项生成一个单独的子代理。

在 .agents/checks/ 目录中创建 Markdown 文件，带有 YAML 前言：

示例 (.agents/checks/perf.md):

---
name: performance
description: Flags common performance anti-patterns
severity-default: medium
tools: [Grep, Read]
---

Look for these patterns:

- Nested loops over the same collection (O(n²) → O(n) with a Set/Map)
- Repeated `array.includes()` in a loop
- Sorting inside a loop
- String concatenation in a loop (use array + join)

Report the line, why it matters, and how to fix it.

检查项可以在项目和全局位置定义：

• .agents/checks/ ——适用于整个代码库
• api/.agents/checks/ ——仅适用于 api/
• $HOME/.config/amp/checks/ 或 $HOME/.config/agents/checks/ ——全局检查项，适用于所有审查

更近的项目检查项会覆盖来自父目录和全局的同名检查项。

MCP

你可以使用 MCP（模型上下文协议） 服务器来添加额外的工具，可以是本地的或远程的。

对于大多数用例，我们建议 在技能中捆绑 MCP 服务器 via mcp.json 而不是将它们添加到你的用户设置中。这样可以保持工具列表整洁，只在需要时加载 MCP 工具。

如果通过技能加载 MCP 不合适（如果它必须始终在上下文窗口中可用），通过 CLI 或在你的 配置文件:

$ amp mcp add context7 -- npx -y @upstash/context7-mcp
$ amp mcp add linear https://mcp.linear.app/sse

MCP 服务器使用与 技能中的 MCP 服务器—command/args/env 用于本地服务器， url/headers 用于远程。在配置文件中，设置 amp.mcpServers and use ${VAR_NAME} 语法来引用环境变量：

"amp.mcpServers": {
    "playwright": {
        "command": "npx",
        "args": ["-y", "@playwright/mcp@latest", "--headless"]
    },
    "linear": {
        "url": "https://mcp.linear.app/sse"
    },
    "sourcegraph": {
        "url": "${SRC_ENDPOINT}/.api/mcp/v1",
        "headers": { "Authorization": "token ${SRC_ACCESS_TOKEN}" }
    }
}

许多远程服务器通过 OAuth自动处理身份验证。对于需要手动认证的服务器，直接传递 headers 或使用 手动 OAuth 注册.

MCP 服务器加载顺序

当相同的 MCP 服务器名称出现在多个位置时，Amp 使用以下优先级（从高到低）：

1. CLI 标志（--mcp-config)
2. 用户/工作区配置（amp.mcpServers)
3. 技能（仅在上述未配置时加载）

这意味着你可以在需要时用自己的配置覆盖技能提供的 MCP 服务器。

工作区 MCP 服务器信任

工作区设置中的 MCP 服务器（.amp/settings.json）需要明确批准才能运行。这可以防止在你打开项目时不受信任的代码自动执行。

当工作区 MCP 服务器等待批准时，你会看到 awaiting approval 在 amp mcp doctor 输出。要批准：

$ amp mcp approve my-server

在 CLI 中，当首次检测到工作区服务器时，系统会提示你批准。

全局设置中的 MCP 服务器（~/.config/amp/settings.json）或通过 --mcp-config 传递的不需要批准。

MCP 最佳实践

可用工具过多会降低模型性能，因此为了获得最佳效果，请有选择性地使用：

• 在技能中捆绑 MCP 服务器 而不是全局添加——工具在技能加载前保持隐藏。
• 使用暴露少量高级工具且具有高质量描述的 MCP 服务器。
• 禁用你不使用的 MCP 工具，或考虑改用 CLI 工具。

远程 MCP 服务器的 OAuth

一些 MCP 服务器如 Linear 支持自动 OAuth 客户端注册。当你添加这样的服务器时，Amp 会在启动时自动在浏览器中启动 OAuth 流程。

$ amp mcp add my-server https://example.com/.api/mcp/v1

$ amp mcp oauth login my-server \
  --server-url https://example.com/.api/mcp/v1 \
  --client-id your-client-id \
  --client-secret your-client-secret \
  --scopes "openid,profile,email,user:all"

$ amp mcp oauth logout my-server

权限

Amp 在运行工具前不会请求批准。

该 Plugin API 允许你自定义此行为。

如果 Amp 在你的设置中检测到 amp.permissions, amp.guardedFiles.allowlist, or amp.dangerouslyAllowAll （设置为 false) in your settings, an internal plugin is activated to apply the 旧版权限规则.

插件

Amp 插件是用于扩展和自定义 Amp.

插件可以：

• 处理事件 — amp.on(...) 用于工具调用、工具结果和代理生命周期事件
• 添加工具 — amp.registerTool(...) 供代理调用自定义工具
• 添加命令 — amp.registerCommand(...) 用于命令面板操作
• 显示 UI — ctx.ui.notify(...), ctx.ui.confirm(...), ctx.ui.input(...)和 ctx.ui.select(...)
• 用 AI 分类 — amp.ai.ask(...) 用于带置信度和推理理由的是/否判断

当书面指导不够时使用插件。使用 AGENTS.md 保存持久说明，用技能提供任务特定的代理指导，用 MCP 和工具箱集成外部工具，用插件编写响应 Amp 事件或扩展 Amp 行为的代码。

插件会执行代码，因此只使用来自你信任的人和工作区的插件。

插件位置

Amp 会从三个位置加载插件：

• 项目插件 — .amp/plugins/*.ts 在你于该项目中运行 Amp 时生效。
• 系统插件 ——在这台机器上你自己的所有项目中生效：
  • macOS： ~/.config/amp/plugins/*.ts
  • Linux： ~/.config/amp/plugins/*.ts
  • Windows： %USERPROFILE%\.config\amp\plugins\*.ts
• 全局插件 ——在 工作区设置 中配置，并应用于每个工作区成员。全局插件目前处于有限实验发布阶段； 联系我们 如果你想将其用于安全或策略执行。

编写插件

插件是一个导出默认函数的 TypeScript 文件。Amp 会向该函数传入一个 PluginAPI 对象。

import type { PluginAPI } from '@ampcode/plugin'

export default function (amp: PluginAPI) {
	amp.logger.log('Plugin initialized')
}

Code in the exported function runs when the plugin loads. Use session.start only for work that should run when Amp starts a specific thread session.

更改插件后，用 Ctrl+O 并运行 plugins: reload. Run plugins: list 查看已加载插件及其注册的事件、命令和工具。

插件激活设置同时适用于交互式 amp 会话和 amp --execute 运行。

Amp 还内置了用于编写插件的技能，因此你可以直接让它为你编写插件。

事件示例

插件事件遵循对话会话的代理生命周期。系统会先为对话会话触发 session.start；随后每个用户回合开始、可能运行工具，并最终结束。

╭───────────────╮    ╭─────────────╮    ╭───────────╮    ╭─────────────╮    ╭───────────╮
│ session.start │───▶│ agent.start │───▶│ tool.call │───▶│ tool.result │───▶│ agent.end │
╰───────────────╯    ╰─────────────╯    ╰───────────╯    ╰─────────────╯    ╰───────────╯
                                              ▲                 │
                                              ╰──── per tool ───╯

session.start: Run Setup When a Thread Starts

session.start fires when Amp starts a thread session, such as when the user sends the first message in a new thread or opens/switches to an existing thread. Put plugin-load initialization directly in the exported function body. Multiple threads can be started and continue to run at the same time in the same Amp CLI. There is no session.end event.

import type { PluginAPI } from '@ampcode/plugin'

export default function (amp: PluginAPI) {
	amp.on('session.start', async (event, ctx) => {
		await ctx.ui.notify(`Example session.start for ${event.thread.id}.`)
	})
}

tool.call：批准或拒绝工具调用

tool.call 会在工具运行前触发。返回 allow 以运行工具， reject-and-continue 以阻止它并让代理继续， modify 以更改输入，或 synthesize 以在不运行工具的情况下提供结果。

import type { PluginAPI } from '@ampcode/plugin'

export default function (amp: PluginAPI) {
	amp.on('tool.call', async (event, ctx) => {
		const confirmed = await ctx.ui.confirm({
			title: `Allow ${event.tool}?`,
			message: `Amp wants to call ${event.tool}.`,
			confirmButtonText: 'Allow',
		})

		if (confirmed) {
			return { action: 'allow' }
		}

		return {
			action: 'reject-and-continue',
			message: `The user rejected ${event.tool}.`,
		}
	})
}

tool.result：观察或修改工具结果

tool.result 会在工具完成后、结果发回模型前触发。不返回内容会保留原始结果；也可以返回替换后的状态或输出。

import type { PluginAPI } from '@ampcode/plugin'

export default function (amp: PluginAPI) {
	amp.on('tool.result', async (event, ctx) => {
		if (event.status === 'error') {
			await ctx.ui.notify(`Tool failed: ${event.tool}`)
		}
	})
}

agent.start：回合开始时通知

agent.start 会在用户提交提示词时触发，适合在代理开始工作前对新回合作出响应。

import type { PluginAPI } from '@ampcode/plugin'

export default function (amp: PluginAPI) {
	amp.on('agent.start', async (_event, ctx) => {
		await ctx.ui.notify('Amp is starting a new turn.')
	})
}

agent.end：回合结束后继续

agent.end 会在代理完成一个回合时触发。返回 continue 以追加一条后续用户消息并启动另一个回合。返回时务必包含标记或其他保护条件， continue 避免插件无限循环。

import type { PluginAPI } from '@ampcode/plugin'

const marker = '[plugin:tests-requested]'

export default function (amp: PluginAPI) {
	amp.on('agent.end', (event) => {
		if (!event.message.toLowerCase().includes('verify')) {
			return
		}
		if (event.message.includes(marker)) {
			return
		}

		return {
			action: 'continue',
			userMessage: `${marker} Before finishing, run the most relevant tests for your changes.`,
		}
	})
}

命令、工具和 UI 示例

添加命令

命令会出现在 Amp 的命令面板中。

import type { PluginAPI } from '@ampcode/plugin'

export default function (amp: PluginAPI) {
	amp.registerCommand(
		'open-plugin-docs',
		{
			title: 'Open plugin docs',
			category: 'docs',
			description: 'Open the Amp Plugin API manual page.',
		},
		async (ctx) => {
			await ctx.system.open('https://ampcode.com/manual/plugin-api')
		},
	)
}

更改命令可用性

amp.registerCommand(...) 接受可选的 availability，并返回一个 subscription；它的 setAvailability(...) 方法会更新命令在命令面板中的显示方式：

• { type: 'enabled' } —— 显示且可选择（默认值）。
• { type: 'disabled', reason: '...' } —— 显示但不可选择；原因会随命令一起显示。
• { type: 'hidden' } —— 完全不显示。

这个插件添加了两个命令，用于切换 Amp 内置的 notifications.enabled 设置，并让命令面板只显示当前相关的那个命令。

import type { CommandSubscription, PluginAPI } from '@ampcode/plugin'

export default async function (amp: PluginAPI) {
	const isEnabled = (config: Record<string, unknown>) =>
		config['notifications.enabled'] !== false

	let mute: CommandSubscription | undefined
	let unmute: CommandSubscription | undefined

	const refresh = (enabled: boolean) => {
		mute?.setAvailability(enabled ? { type: 'enabled' } : { type: 'hidden' })
		unmute?.setAvailability(enabled ? { type: 'hidden' } : { type: 'enabled' })
	}

	const enabled = isEnabled(await amp.configuration.get())

	mute = amp.registerCommand(
		'mute-notifications',
		{
			title: 'Mute notifications',
			category: 'notifications',
			availability: enabled ? { type: 'enabled' } : { type: 'hidden' },
		},
		async (ctx) => {
			await amp.configuration.update({ 'notifications.enabled': false }, 'global')
			await ctx.ui.notify('Notifications muted.')
		},
	)

	unmute = amp.registerCommand(
		'unmute-notifications',
		{
			title: 'Unmute notifications',
			category: 'notifications',
			availability: enabled ? { type: 'hidden' } : { type: 'enabled' },
		},
		async (ctx) => {
			await amp.configuration.update({ 'notifications.enabled': true }, 'global')
			await ctx.ui.notify('Notifications unmuted.')
		},
	)

	amp.configuration.subscribe((config) => {
		refresh(isEnabled(config))
	})
}

注册工具

插件注册的工具会与 Amp 内置工具一起提供给模型使用。

import type { PluginAPI } from '@ampcode/plugin'

export default function (amp: PluginAPI) {
	amp.registerTool({
		name: 'project_status',
		description: 'Show the current git status for this repository.',
		inputSchema: {
			type: 'object',
			properties: {},
			required: [],
		},
		async execute() {
			const result = await amp.$`git status --short`
			return result.stdout || 'No changes.'
		},
	})
}

请求用户输入

插件可以显示通知、确认对话框、文本输入框和选择对话框。

import type { PluginAPI } from '@ampcode/plugin'

export default function (amp: PluginAPI) {
	amp.registerCommand(
		'add-note-to-thread',
		{
			title: 'Add note to thread',
			category: 'notes',
			description: 'Prompt for a note and append it to the current thread.',
		},
		async (ctx) => {
			const note = await ctx.ui.input({
				title: 'Thread note',
				helpText: 'What should Amp remember in this thread?',
				submitButtonText: 'Add note',
			})

			if (!note) {
				return
			}

			await ctx.thread?.append([{ type: 'user-message', content: note }])
		},
	)
}

使用 AI 分类

使用 amp.ai.ask(...) 当插件需要一个带推理理由的小型是/否分类判断时使用。

import type { PluginAPI } from '@ampcode/plugin'

export default function (amp: PluginAPI) {
	amp.on('agent.start', async (event, ctx) => {
		const answer = await amp.ai.ask(
			`Is this request asking to change production infrastructure? ${event.message}`,
		)

		if (answer.result === 'yes') {
			await ctx.ui.notify(`This looks production-related: ${answer.reason}`)
		}
	})
}

示例插件：权限

这个插件会在运行可能具有破坏性的 git 命令前询问用户。它使用 amp.ai.ask(...) 对每条 git 命令分类，并且只在命令看起来有风险时提示。

将其保存为 .amp/plugins/no-destructive-git-operations.ts，然后运行 plugins: reload.

import type { PluginAIAskResult, PluginAPI } from '@ampcode/plugin'

/**
 * Plugin that prevents risky git operations by asking the user for confirmation.
 * Uses amp.ai.ask() to classify git commands as risky and prompts the user accordingly.
 */
export default function (amp: PluginAPI) {
	const safePatterns = [
		/^\s*git\s+status\b/,
		/^\s*git\s+log\b/,
		/^\s*git\s+diff\b/,
		/^\s*git\s+show\b/,
		/^\s*git\s+branch\s*$/,
		/^\s*git\s+branch\s+-[av]\b/,
		/^\s*git\s+stash\s+list\b/,
		/^\s*git\s+remote\s+-v\b/,
		/^\s*git\s+fetch\b/,
		/^\s*git\s+pull\b/,
		/^\s*git\s+add\b/,
		/^\s*git\s+commit\b/,
		/^\s*git\s+push\b(?!.*(-f|--force))/,
	]

	amp.on('tool.call', async (event, ctx) => {
		const shellCommand = amp.helpers.shellCommandFromToolCall(event)
		if (!shellCommand?.command) {
			return { action: 'allow' }
		}

		const command = shellCommand.command

		if (!/^\s*git\s+/.test(command)) {
			return { action: 'allow' }
		}

		if (safePatterns.some((pattern) => pattern.test(command))) {
			return { action: 'allow' }
		}

		const aiResponse: PluginAIAskResult = await ctx.ai.ask(
			`Does this git command look like a potentially destructive operation that could lose work? Answer yes if it's a destructive operation like force push, branch deletion, reset, or checkout to detached HEAD. Command: ${command}`,
		)

		if (aiResponse.result === 'no') {
			return { action: 'allow' }
		}

		const confirmed = await ctx.ui.confirm({
			title: 'Potentially destructive git operation',
			message: `${command}\n\nReason: ${aiResponse.reason}\n\nDo you want to proceed?`,
			confirmButtonText: 'Allow',
		})

		if (confirmed) {
			return { action: 'allow' }
		}

		return {
			action: 'reject-and-continue',
			message: `User cancelled potentially destructive git operation: ${command}`,
		}
	})
}

示例插件：Kitchen Sink

如需查看一个演示所有插件能力（事件、命令、工具、UI 和 AI 辅助函数）的单一插件，请参阅 Kitchen Sink 示例 （位于 Plugin API 参考页面）。

致谢

Amp 的插件 API 受到 pi 的扩展 API的启发，该 API 由才华横溢的 Mario Zechner 创建。

参阅 Plugin API 参考 查看完整的 @ampcode/plugin type reference.

对话分享

对话是与代理的交谈，包含你所有的消息、上下文和工具调用。你的对话可在 ampcode.com/threads.

我们发现在代码审查中包含 Amp 对话链接很有用，可以为审查者提供更多上下文。阅读和搜索你团队的对话也能帮助你了解进展以及其他人如何使用 Amp。

要更改你的对话分享对象：

• 在 CLI 中，输入 / 打开命令面板，然后选择 thread: set visibility.
• 在网页端，使用顶部的 顶部的分享菜单。

对话的可见性级别可以设置为：

• 公开：在你的公开个人资料上对任何人可见（ampcode.com/@your-username），可被公开搜索
• 未列出：互联网上任何有链接的人都可以看到，并与你的工作区共享
• 工作区共享：对工作区的所有成员可见
• 群组共享：对你选择的特定群组成员和工作区管理员可见（仅限企业版）
• 私密：仅对你自己可见（如果你在工作区中，工作区管理员也可见）

如果你不在工作区中，你的对话默认仅对你自己可见。

如果你在工作区中，你的对话默认与你的工作区成员共享。 企业版 工作区可以配置额外的分享控制；请参阅 工作区对话可见性控制.

CLI

在 安装 并登录后，运行 amp 来启动 Amp CLI。

不带任何参数时，它以交互模式运行：

$ amp

如果你通过管道向 CLI 输入数据，它会将输入作为交互模式中的第一条用户消息：

$ echo "commit all my changes" | amp

使用 -x 或 --execute 来以执行模式启动 CLI。在此模式下，它将提供的消息发送给 -x 代理，等待代理结束其轮次，打印最终消息，然后退出：

$ amp -x "what files in this folder are markdown files? Print only the filenames."
README.md
AGENTS.md

（注意：执行模式（amp -x) 仅消耗付费额度。Amp Free 仅适用于交互式 Amp 使用。）

使用 -x:

$ echo "what package manager is used here?" | amp -x
cargo

如果你想使用 -x 时代理可能使用需要批准的工具，请确保使用 --dangerously-allow-all 或 配置 Amp 以允许它们:

$ amp --dangerously-allow-all -x "Run `sed` to replace 2024 with 2025 in README."
Done. Replaced 8 occurrences of 2024 in README.md

当你重定向 stdout 时，执行模式会自动开启：

$ echo "what is 2+2?" | amp > response.txt

当你通过管道输入数据并使用 -x提供提示词时，代理可以同时看到两者：

$ cat ~/.vimrc | amp -x "which colorscheme is used?"
The colorscheme used is **gruvbox** with dark background and hard contrast.

```vim
set background=dark
let g:gruvbox_contrast_dark = "hard"
colorscheme gruvbox
```

你可以使用 --mcp-config 标志与 -x 命令来指定 MCP 服务器，而无需修改你的配置文件。

$ amp --mcp-config '{"everything": {"command": "npx", "args": ["-y", "@modelcontextprotocol/server-everything"]}}' -x "What tools are available to you?"

要了解 CLI 的更多功能，运行 amp --help.

键绑定

最重要的键绑定是 Ctrl+O 打开命令面板。其他值得记住的键绑定：

• Ctrl+G 在编辑器中打开当前提示词（需要 `$EDITOR`）
• Ctrl+S 切换代理模式
• Ctrl+R 用于提示词历史记录
• ↑/↓ 移动到之前的消息并编辑
• Alt+T 展开思考/工具块
• Alt+D to toggle reasoning effort for the active model (e.g. smart cycles through high, xhigh, max; deep cycles through low, medium, xhigh)
• @ 提及文件

使用 Ctrl+O 打开命令面板并运行 amp: help 查看更多键绑定。

非交互式环境

对于非交互式环境（如脚本、CI/CD 管道），设置你的 访问令牌 到环境变量中：

export AMP_API_KEY=your-access-token-here

CLI–IDE 集成

Amp CLI 与 VS Code、JetBrains、Neovim 和 Zed 集成（参阅 ampcode.com/install 进行安装），这使 Amp CLI 可以：

• 查看当前打开的文件和选择内容，以便 Amp 更好地理解你的提示词上下文
• 通过你的 IDE 编辑文件，支持完全撤销

按照你的 IDE 的说明操作。如果你使用 JetBrains 并从 以外的 JetBrains 内置终端以外的终端运行 Amp CLI，运行 amp --jetbrains 来检测它。

在 CLI 中编写提示词

在 Amp CLI 中， Enter 提交你的提示词。

使用 Shift+Enter 在终端支持修改后的 Enter 键时插入换行（例如 Ghostty、Wezterm、Kitty、iTerm2 或启用了 extended-keys enabled).

Amp 知道如何为此配置 tmux，所以你可以让 Amp 来设置。

使用 Ctrl+J 在任何终端中插入换行。

你也可以输入 \ 后接 return 来插入换行。

如果你设置了环境变量 $EDITOR ，你可以使用 editor 命令从命令面板中打开编辑器来编写提示词。

流式 JSON

Amp 的 CLI 支持流式 JSON 输出格式，每行一个对象输出到 stdout，用于编程集成和实时对话监控。

使用 --stream-json 标志与 --execute 模式以流式 JSON 格式而非纯文本输出。 如果你想在 JSON 输出中包含助手的思考块，添加 --stream-json-thinking （这扩展了 schema，与 Claude Code 不兼容）。

带参数的基本用法：

$ amp --execute "what is 3 + 5?" --stream-json

结合 --stream-json 与 amp threads continue:

$ amp threads continue --execute "now add 8 to that" --stream-json

使用 stdin 输入：

$ echo "analyze this code" | amp --execute --stream-json

你可以找到 附录中 JSON 输出的 schema.

也可以通过 --stream-json-input 标志在 stdin 上提供输入。每行 stdin 是一个完整的 JSON 对象。例如，你可以使用 jq -c 将文本加图片消息发送为单行：

$ jq -c . <<'EOF' | amp -x --stream-json --stream-json-input
{
  "type": "user",
  "message": {
    "role": "user",
    "content": [
      {
        "type": "text",
        "text": "what do you see?"
      },
      {
        "type": "image",
        "source_path": "file:///Users/alice/images/example.jpg",
        "source": {
          "type": "base64",
          "media_type": "image/jpeg",
          "data": "..."
        }
      }
    ]
  }
}
EOF

该 --stream-json 标志需要 --execute 模式。它不能单独使用。 --stream-json-input 需要 --stream-json和 --stream-json-thinking 隐含 --stream-json.

在使用 --stream-json-input的行为， --execute 的行为会改变，Amp 只会在助手完成 和 stdin 被关闭后才退出。

这允许以编程方式使用 Amp CLI 进行包含多条用户消息的对话。

#!/usr/bin/env bash

send_message() {
  local text="$1"
  echo '{"type":"user","message":{"role":"user","content":[{"type":"text","text":"'$text'"}]}}'
}

{
  send_message "what's 2+2?"
  sleep 10

  send_message "now add 8 to that"
  sleep 10

  send_message "now add 5 to that"
} | amp --execute --stream-json --stream-json-input

--stream-json-input 消息还允许在顶层设置 "steer": true 属性。如果消息在代理忙碌时排队，Amp 会将其标记为 steering，以便在下一个中断点处理。

参阅 附录 了解输出 schema、示例输出和更多使用示例。

配置

Amp 从以下位置读取设置：

• 工作区设置：最近的 .amp/settings.json 或 .amp/settings.jsonc， 从当前工作目录向上搜索到仓库根目录（或 git 仓库外的当前目录）
• 用户设置：
  • macOS： ~/.config/amp/settings.json 或 ~/.config/amp/settings.jsonc
  • Linux： ~/.config/amp/settings.json 或 ~/.config/amp/settings.jsonc
  • Windows： %USERPROFILE%\.config\amp\settings.json 或 %USERPROFILE%\.config\amp\settings.jsonc
• 自定义用户设置：传递 --settings-file <path> 让 Amp 指向不同的用户设置文件

当同一设置出现在多个位置时，工作区设置会覆盖用户设置。

所有设置使用 amp. 前缀。

设置

企业版托管设置

企业版 工作区管理员可以通过将策略部署到运行 Amp 的机器上的以下位置来强制执行覆盖用户和工作区设置的设置：

• macOS: /Library/Application Support/ampcode/managed-settings.json
• Linux: /etc/ampcode/managed-settings.json
• Windows: %ProgramData%\ampcode\managed-settings.json

此托管设置文件使用与 常规设置 文件相同的 schema，并增加了一个字段：

代理和证书

在企业网络中使用带有代理服务器或自定义证书的 Amp CLI 时，根据需要在你的 shell 配置文件或 CI 环境中设置以下标准 Node.js 环境变量：

export HTTP_PROXY=your-proxy-url
export HTTPS_PROXY=your-proxy-url
export NODE_EXTRA_CA_CERTS=/path/to/your/certificates.pem

定价

Amp 根据你实际使用的 LLM 和某些其他工具（如网页搜索）向你收费。我们将这些成本直接传递给你。对于个人和非企业版工作区，在提供商的 API 定价上零加价。Amp 没有订阅或承诺，最低购买额度为 $5。

例如，如果你运行一个 Amp 对话产生了 $2 的 Anthropic API 使用费和 $0.50 的 OpenAI API 使用费，我们将从你的 Amp 额度余额中扣除 $2.50。

在 用户设置 或 工作区设置中购买额度并查看余额，或运行 amp usage.

企业版

企业版使用费用比个人和团队计划贵 50%，并包含以下访问权限：

• SSO（Okta、SAML 等）和目录同步
• LLM 推理中的文本输入零数据保留
• 高级 对话可见性控制
• 权限配额 用于按用户成本控制
• MCP 注册表白名单
• 托管用户设置
• 用于工作区分析和数据管理的 API（OpenAPI schema)
• 用于成本归属和按组对话可见性选项的用户组（按需提供）
• 可配置的对话保留（按需提供）
• 工作区访问 IP 白名单（按需提供，额外收费）

有关 Amp 企业版安全功能的更多信息，请参阅 Amp 安全参考.

要开始使用 Amp 企业版，前往 你的工作区 并点击 Plan （右上角）。这需要一次性 $1,000 美元的特殊购买，为你的工作区提供 $1,000 美元的 Amp 企业版使用额度并将你的工作区升级为企业版。

联系 amp-devs@ampcode.com 获取更多购买选项和 Amp 企业版的更多信息。

说明

要查看对话的详细费用信息，点击 $ 任意对话页面右侧边栏的价格。

所有未使用的额度在账户不活跃一年后过期。工作区额度由所有工作区成员共享。

发票通过 Stripe 开具，支持添加你的 VAT ID 或其他税务信息。

参阅 Amp Free 的最新更新.

支持

要获取 Amp 的一般帮助，在 X 上发帖并提及 @AmpCode，或发送邮件至 amp-devs@ampcode.com。你也可以加入我们的 Amp Insiders 社区来讨论 Amp 并与他人分享技巧。

如需账单和账户帮助，请联系 amp-devs@ampcode.com.

支持的平台

Amp 支持 macOS、Linux 和 Windows（通过 WSL）。在 Windows 上，我们建议使用 WezTerm 或 Alacritty 代替 Windows Terminal，以获得完整的剪贴板支持。

Amp 的 JetBrains 集成支持所有 JetBrains IDE（IntelliJ、WebStorm、GoLand 等），版本 2025.1+（推荐 2025.2.2+）。