· 使用手册附录

发送包含诊断信息的报告

我们可能会请你发送一份包含诊断信息的报告，以帮助我们修复你遇到的 bug。

在 Amp CLI 中，打开命令面板（Ctrl-O）并选择 feedback: send report with diagnostics。你也可以运行 amp threads report <thread-id>。

在 ampcode.com 查看对话时，你也可以发送报告：

  1. 打开 对话侧边栏中的菜单。
  2. 选择 发送包含诊断信息的报告.

这会提交一个诊断报告 ID，你在联系 Amp 支持时可以附上它。诊断数据会在 7 天后删除，且只有在你提供报告 ID 时，Amp 团队成员才能访问这些数据。

我们更希望你从 CLI 发送报告，而不是从网页发送，因为 CLI 会包含网页端无法提供的额外客户端诊断信息（例如客户端日志）。

Amp CLI 在 tmux 中的使用

Tmux 默认不会区分 Shift+Enter 和 Enter 。为了让 Shift+Enter 在 Amp CLI 中插入换行，请启用 extended-keys 。

如果你不想更改 tmux 设置，使用 Ctrl+J 来插入换行符。

$ tmux set -s extended-keys on

要永久生效，请将 set -s extended-keys on 添加到 ~/.tmux.conf，然后重新加载： tmux source-file ~/.tmux.conf.

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

服务状态

请查看 ampcodestatus.com 了解服务状态并通过邮件、RSS、Slack 订阅警报。或者关注 @ampcodestatus 。

MCP 注册表白名单

企业版工作区管理员可以强制使用 MCP 注册表，以便只有已批准的 MCP 服务器可供工作区成员使用。如果注册表不可访问，所有 MCP 服务器将被阻止。注册表协议和模式定义在 registry.modelcontextprotocol.io.

设置注册表 URL：

  1. 打开 工作区设置 并找到 MCP 注册表.
  2. 输入注册表 URL（ v0.1/servers 端点）并保存。

可选择限制为特定用户：

  1. 将 应用于 添加到 仅限特定用户.
  2. 输入工作区成员邮箱（每行一个或用逗号分隔）并保存。

注意：

  • 如果你限定为特定用户，只有这些用户受注册表限制；其他人不受影响。
  • 清除 URL 以移除注册表并允许所有 MCP 服务器。

权限参考

本参考说明 Amp 权限插件所理解的规则格式。自定义策略插件也可以直接使用同一个 tool.call 插件钩子。

权限工作原理

启用权限插件后，它会按以下步骤评估工具调用：

  1. 查找匹配规则：第一个匹配该工具 和 参数的规则胜出
  2. 确定操作：匹配的规则告诉 Amp：
    • allow —— 静默运行工具
    • reject —— 阻止调用（可选择返回自定义消息）
    • ask —— 提示操作者批准
    • delegate —— 将决定委托给外部程序
  3. 检查默认规则：如果没有用户规则匹配，插件会回退到内置默认规则（例如允许 ls 和 cat 这类安全命令）。
  4. 返回插件结果：插件向执行器返回 allow、reject 或 ask。如果你想采用默认拒绝或默认询问策略，请在规则末尾添加兜底规则，例如 ask '*' 或 reject '*'。

配置

规则定义在 amp.permissions 设置中。每条规则是一个具有以下属性的 JSON 对象：

键类型必填描述
tool字符串 (glob)是此规则适用的工具名称。支持 glob（Bash, mcp__playwright__*, **/my-tool)
matches对象– 工具参数 → 条件的映射。如果省略，规则匹配该工具的 所有 调用
action"allow" / "reject" / "ask" / "delegate"是规则匹配时 Amp 应执行的操作
context"thread" / "subagent"–将规则限制为主线程或子代理。省略则全局适用
to字符串（程序）仅当 action = "delegate"做决定的程序。必须在 $PATH
message字符串仅当 action = "reject"返回给模型的消息。如果设置，拒绝会继续对话而不是终止对话

匹配条件

每个 matches 键对应一个工具参数。值可以是：

  • 字符串 —— glob 模式（* = 任意字符）或正则表达式模式（/pattern/)
  • 数组 —— 每个条目的 OR（["rm -rf *", "git commit *"])
  • boolean/number/null/undefined —— 字面值匹配
  • 对象 —— 嵌套结构匹配

正则表达式模式

以 / 开头和结尾的字符串被视为正则表达式：

{
  "tool": "Bash",
  "matches": { "cmd": "/^git (status|log|diff)$/" },
  "action": "allow"
}

这将精确匹配 git status, git log、 git diff 但不匹配 git commit.

值类型匹配

  • 字符串模式 仅使用 glob 语法匹配字符串值
  • 字面值 （boolean、number、null、undefined）需要精确匹配
  • 数组条件 提供跨多个模式的 OR 逻辑
  • 嵌套对象 启用对象的点号表示法和数组索引的数字字符串进行深层属性匹配

示例

基本权限规则

允许主线程中的所有 Bash 命令，但限制子代理：

{
  "tool": "Bash",
  "action": "allow",
  "context": "thread"
},
{
  "tool": "Bash",
  "matches": { "cmd": ["rm -rf *", "find *", "git commit *"] },
  "action": "reject",
  "context": "subagent"
}
// In text form:
// allow --context thread Bash
// reject --context subagent Bash --cmd "rm -rf *" --cmd "find *" --cmd "git commit *"

在 home 目录中 grep 时请求批准：

{
  "tool": "Grep",
  "matches": { "path": "$HOME/*" },
  "action": "ask"
}
// In text form:
// ask Grep --path '$HOME/*'

禁止编辑点文件：

{
  "tool": "edit_file",
  "matches": { "path": ".*" },
  "action": "reject"
}
// In text form:
// reject edit_file --path '.*'

拒绝破坏性 git 命令并返回有用消息（允许模型继续）：

{
  "tool": "Bash",
  "matches": { "cmd": ["*git checkout*", "*git reset*"] },
  "action": "reject",
  "message": "Do not use git checkout or git reset. Use edit_file to make manual changes instead."
}

委托

将 GitHub CLI 调用委托给外部验证器：

{
  "tool": "Bash",
  "matches": { "cmd": "gh *" },
  "action": "delegate",
  "to": "my-gh-permission-helper"
}
// In text form:
// delegate --to my-gh-permission-helper Bash --cmd "gh *"

当指示委托时，Amp 将：

  • 执行 to 中指定的程序（必须在 $PATH上，或为绝对路径）
  • 导出 AMP_THREAD_ID, AGENT_TOOL_NAME=nameOfInvokedTool 和 AGENT=amp 环境变量
  • 将工具参数通过管道传递到 stdin （JSON 格式）
  • 解释退出状态：
    • 0 → 允许
    • 1 → 询问操作者
    • ≥ 2 → 拒绝（stderr 会呈现给模型）

Amp 的权限行为正在迁移到插件中，以便更容易自定义。不同团队对于哪些工具调用应允许、拒绝或要求批准有不同标准；基于插件的权限系统让每个团队都能让 Amp 适配自己的工作流。对于新的权限钩子，请优先使用 Plugin API。

文本格式

为了方便编辑大量规则，你可以配合以下 amp permissions shell 命令使用文本格式：

<action> [--<action-arg> ...] <tool> [--<match-key>[:<op>] <value>] ...

文本格式设计为与 UNIX shell 语法兼容，允许你无需进一步编辑即可从命令行复制/粘贴规则。

# Basic allow/reject rules
allow Bash --cmd 'git *'
reject Bash --cmd 'python *'

# Multiple conditions
allow Bash --cmd 'git diff*' --cmd 'git commit*'

# Delegation
delegate --to amp-git-permissions Bash --cmd '*'
  • 支持单引号和双引号字符串
  • 未加引号的 true、false、null 和数字会被解释为 JSON 字面值
  • 任何包含 * 的值必须加引号

列出规则

amp permissions list                    # Show user rules
amp permissions list --builtin          # Show default rules

测试规则

例如，测试 git commit 是否会询问：

$ amp permissions test Bash --cmd "git commit -m 'test'"
tool: Bash
arguments: {"cmd":"git commit -m 'test'"}
action: ask
matched-rule: 12
source: built-in

或测试编辑当前目录中的 .env 是否会询问

$ amp permissions test edit_file --path "$PWD/README.md"
tool: edit_file
arguments: {"path":"/Users/your/project/README.md"}
action: allow
matched-rule: 29
source: built-in

test 子命令允许你测试权限规则，而无需实际运行任何工具或希望代理生成正确的参数。

编辑规则

你可以使用 $EDITOR 在文本格式中交互式编辑规则：

$ amp permissions edit

你也可以从 STDIN 编辑：

$ amp permissions edit <<'EOF'
# Ask for approval on every tool use
ask '*'
EOF

添加规则

例如，拒绝所有网页搜索：

$ amp permissions add reject web_search

或者对关于 node.js 或 npm 包的搜索请求批准：

$ amp permissions add ask web_search --query "*node*" --query "*npm*"

使用单条规则匹配多个工具

工具名称支持 glob 模式用于管理工具组：

  • Bash —— 仅匹配 Bash 工具
  • mcp__playwright__* —— 匹配所有 Playwright MCP 工具

上下文限制

使用 context 字段将规则限制为主代理或子代理

  • "context": "thread" —— 仅在主对话线程中适用
  • "context": "subagent" —— 仅适用于子代理工具调用
  • 省略 context —— 全局适用

工具箱协议参考

工具箱允许你使用任何编程语言创建自定义工具。工具是通过 stdin/stdout 使用简单协议与 Amp 通信的可执行文件。请参阅 工具箱 新闻文章了解介绍。

概述

工具箱是一个包含可执行文件的目录，这些文件会成为 Amp 可用的工具。目录中的每个可执行文件代表一个工具。

来自工具箱的工具会以 tb__ 前缀注册（例如， run_tests 会变为 tb__run_tests），并且必须实现工具箱协议（如下所述）。

只要可执行文件遵循协议，它们可以用任何语言编写。

工具发现

Amp 通过扫描 AMP_TOOLBOX 环境变量中指定的目录来发现工具，其工作方式类似于 PATH 变量：多个目录用冒号分隔。

默认情况下，如果 AMP_TOOLBOX 未设置，Amp 使用 ~/.config/amp/tools 作为默认工具箱目录。

当 AMP_TOOLBOX 设置为空字符串或环境中不存在时，不会扫描任何工具箱目录。

否则 Amp 会扫描 AMP_TOOLBOX 中列出的目录，从左到右，优先使用较早目录中同名工具：

# Example: a run_tests tool in $PWD/.agents/tools will be used even if
# a tol with the same name exists in $HOME/.config/amp/tools
export AMP_TOOLBOX="$PWD/.agents/tools:$HOME/.config/amp/tools"

协议规范

工具通过两个操作与 Amp 通信： describe 和 execute。操作由 TOOLBOX_ACTION 环境变量决定。

describe 操作用于告诉 Amp 何时以及如何使用该工具。

一旦 Amp 决定执行工具，可执行文件会再次被调用，但 TOOLBOX_ACTION 设置为 execute.

通信：

  • 工具通过 stdin接收工具参数，可以是 JSON 或基于行的键值对。
  • 工具将消息写入 stdout.
  • 退出代码 0 表示成功，非零表示错误
  • Stderr 用于错误消息和诊断信息

传递给工具的环境变量：

变量值可用时机
TOOLBOX_ACTION"describe" 或 "execute"两个操作都可用
AGENT"amp"两个操作都可用
AMP_THREAD_ID当前对话 ID仅执行时
AGENT_THREAD_ID当前对话 ID仅执行时
PATH从环境继承两个操作都可用

通信格式

工具可以使用 JSON 格式 或 文本格式 来传达工具模式和输入参数。Amp 在 describe 操作期间自动检测格式：

  1. 首先尝试将输出解析为 JSON
  2. 如果 JSON 解析失败，回退到文本格式
  3. 检测到的格式用于 describe 和 execute 操作

Amp 会记住工具声明的格式，并以相同格式提供工具输入参数。

当 TOOLBOX_ACTION 为 execute Amp 会获取工具的任何输出并直接传递给模型。

JSON 格式

JSON 格式在大多数编程语言中都很容易使用，当工具的大部分逻辑由现有编程语言库实现时，这是编写工具箱工具的推荐方式。

对于主要调用 shell 命令的工具，推荐使用文本格式。

Describe 操作：

输出一个包含 name, description和 args （紧凑）或 inputSchema （完整）的 JSON 对象：

简单工具的紧凑参数格式：

{
  "name": "run_tests",
  "description": "Run the tests in the project using this tool instead of Bash",
  "args": {
    "workspace": ["string", "optional name of the workspace directory"],
    "test": ["string", "optional test name pattern to match"]
  }
}

对于具有深层嵌套对象的更结构化参数，使用完整的 MCP inputSchema:

完整 inputSchema 格式（JSON Schema draft 2020-12）：

{
  "name": "run_tests",
  "description": "Run the tests in the project using this tool instead of Bash",
  "inputSchema": {
    "type": "object",
    "properties": {
      "workspace": {
        "type": "array",
		"items": {
			"type": "string"
		},
        "description": "list of names of the workspace directories"
      },
      "test": {
        "type": "string",
        "description": "optional test name pattern to match"
      }
    },
    "required": ["workspace"]
  }
}

Execute 操作：

  • 输入： 通过 stdin 传入包含工具参数的 JSON 对象
  • 输出： 写入 stdout 的自由格式文本
  • 退出代码： 0 表示成功，非零表示错误

文本格式

文本格式适用于主要需要少量字符串参数的简单工具定义。

它在任何编程语言中都很容易生成和解析。

Describe 操作:

输出基于行的工具描述：

name: run_tests
description: Run the tests in the project using this tool instead of Bash.
workspace: string optional name of the workspace directory
test: string optional test name pattern

多行描述用换行符连接。

没有类型前缀的参数行默认为 string 类型。

空行被忽略。

可选参数：

参数可以通过三种方式标记为可选：

  1. 类型后缀为 ?: param: string? description
  2. (optional) 在描述中: param: string (optional) description
  3. 描述以 optional: param: string optional description 或 param: optional description

三种方法都不区分大小写。未标记为可选的参数默认为必填。

Execute 操作：

  • 输入： 用换行符分隔的键值对（例如， param1=value1\nparam2=value2\n)
  • 输出： 写入 stdout 的任何输出

CLI 命令

amp tools 命令允许你直接从命令行使用工具。

要获取 Amp 已知的所有工具列表，运行 amp tools list:

Bash                              built-in  Executes the given shell command in the user's default shell
# ...
mcp__context7__get-library-docs   local-mcp Fetches up-to-date documentation for a library
mcp__context7__resolve-library-id local-mcp Resolves a package/product name to a Context7-compatible library ID and returns a list of matching libraries
tb__run_tests                     toolbox   Run tests using this tool instead of Bash

MCP 服务器提供的工具有 mcp__ 前缀，来自工具箱的工具有 tb__ 前缀。

要创建新的工具箱工具，使用 amp tools make 命令：

$ amp tools make --bash run_tests
Tool created at: /Users/dhamidi/.config/amp/tools/run_tests

Inspect with: amp tools show tb__run_tests

Execute with: amp tools use tb__run_tests

默认创建使用 bun 的 JavaScript 工具， --bash 和 --zsh 参数使用相应的 shell 生成工具脚手架。当你的工具主要是调用其他进程时非常有用。

使用 amp tools show 你可以查看生成工具的模式：

amp tools show tb__run_tests
# tb__run_tests (toolbox: /Users/dhamidi/.config/amp/tools/run_tests)

Use this tool to get the current time.
Supported actions are:
date to retrieve the current time

# Schema

- action (string): the action to take

要原样调用工具，我们使用 amp tools use:

$ amp tools use tb__run_tests --action date
{
  "output": "Got action: date\nTue Oct 14 15:03:46 EEST 2025\n",
  "exitCode": 0
}

Amp 会收集工具箱可执行文件的输出，并将收集的输出连同退出状态一起报告给模型。

编辑脚手架以实际运行 Go 测试后，现在看起来是这样的：

#!/usr/bin/env bash

main() {
  case "${TOOLBOX_ACTION:-${1:-describe}}" in
  describe) print_tool_definition ;;
  execute) read_args_and_run ;;
  *)
    printf "Unknown action: %s\n" "$action" >&2
    exit 1
    ;;
  esac
}

print_tool_definition() {
  cat <<-'EOF'
		name: run_tests
		description: Run Go tests using this tool instead of Bash
		description: The pattern parameter limits the tests to a given pattern.

		pattern: string optional Only run tests matching this pattern
	EOF
}

read_args_and_run() {
  local pattern
  local input=$(</dev/stdin)
  while IFS=": " read name value; do
    if [ -n "$name" ]; then
      local $name="$value"
    fi
  done <<<"$input"

  go test ./... ${pattern:+-run "$pattern"}
}

main "$@"

我们可以使用 amp toosl use 再次验证它是否正常工作：

$ amp tools use --only output tb__run_tests
ok      github.com/dhamidi/proompt/cmd/proompt  (cached)
ok      github.com/dhamidi/proompt/pkg/config   (cached)
ok      github.com/dhamidi/proompt/pkg/copier   (cached)
ok      github.com/dhamidi/proompt/pkg/editor   (cached)
ok      github.com/dhamidi/proompt/pkg/filesystem       (cached)
ok      github.com/dhamidi/proompt/pkg/picker   (cached)
ok      github.com/dhamidi/proompt/pkg/prompt   (cached)

流式 JSON 输出

Amp 的 CLI 支持与 Claude Code 兼容的流式 JSON 输出格式，用于编程集成和实时对话监控。

用法

使用 --stream-json 标志配合 --execute 模式一起使用，以流式 JSON 格式而不是纯文本输出：要包含助手思维块，请添加 --stream-json-thinking （这会扩展 schema，与 Claude Code 不兼容）。

带参数的基本用法：

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

使用 stdin 输入：

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

流式 JSON 输入模式（更多信息请见下文）：

$ echo '{"type":"user","message":{"role":"user","content":[{"type":"text","text":"what is 2+2?"}]}}' | amp --execute --stream-json --stream-json-input

注意： --stream-json 标志需要 --execute 模式。它不能单独使用。 --stream-json-thinking 暗示 --stream-json.

每个对话以一个初始 init system message 开始，然后是一系列 user 和 assistant messages，最后是一个 result system message，包含统计信息。每条消息都以单独的 JSON 对象发出。

消息 Schema

当 --stream-json-thinking 启用时，assistant 内容可能包含 thinking 和 redacted_thinking blocks。

流式 JSON API 返回的消息根据以下 schema 进行严格类型化：

type StreamJSONMessage =
  // An assistant message
  | {
      type: "assistant";
      message: {
        type: "message";
        role: "assistant";
        content: Array<{
          type: "text";
          text: string;
        } | {
          type: "tool_use";
          id: string;
          name: string;
          input: Record<string, unknown>;
        } | {
          type: "thinking";
          thinking: string;
        } | {
          type: "redacted_thinking";
          data: string;
        }>;
        stop_reason: "end_turn" | "tool_use" | "max_tokens" | null;
        usage?: {
          input_tokens: number;
		  max_tokens: number;
          cache_creation_input_tokens?: number;
          cache_read_input_tokens?: number;
          output_tokens: number;
          service_tier?: string;
        };
      };
      parent_tool_use_id: string | null;
      session_id: string;
    }

  // A user message in stream JSON output (plain text or tool results)
  | {
      type: "user";
      message: {
        role: "user";
        content: Array<{
          type: "text";
          text: string;
        } | {
          type: "tool_result";
          tool_use_id: string;
          content: string;
          is_error: boolean;
        }>;
      };
      parent_tool_use_id: string | null;
      session_id: string;
    }

  // Emitted as the last message on success
  | {
      type: "result";
      subtype: "success";
      duration_ms: number;
      is_error: false;
      num_turns: number;
      result: string;
      session_id: string;
      usage?: {
        input_tokens: number;
		max_tokens: number;
        cache_creation_input_tokens?: number;
        cache_read_input_tokens?: number;
        output_tokens: number;
        service_tier?: string;
      };
      permission_denials?: string[];
    }

  // Emitted as the last message on error
  | {
      type: "result";
      subtype: "error_during_execution" | "error_max_turns";
      duration_ms: number;
      is_error: true;
      num_turns: number;
      error: string;
      session_id: string;
      usage?: {
        input_tokens: number;
		max_tokens: number;
        cache_creation_input_tokens?: number;
        cache_read_input_tokens?: number;
        output_tokens: number;
        service_tier?: string;
      };
      permission_denials?: string[];
    }

  // Emitted as the first message at the start of a conversation
  | {
      type: "system";
      subtype: "init";
      cwd: string;
      session_id: string;
      tools: string[];
      mcp_servers: { name: string; status: "connected" | "connecting" | "connection-failed" | "disabled" }[];
      // Agent mode for this run (e.g. "smart", "main"). Omitted if unknown.
      agent_mode?: string;
      // Reasoning effort for this run (e.g. "minimal", "high", "xhigh"). Omitted if not applicable.
      reasoning_effort?: string;
    };

输出示例

简单数学查询：

$ amp --execute "what is 3 + 5?" --stream-json
{"type":"system","subtype":"init","cwd":"/Users/orb","session_id":"T-f9941a55-3765-421e-972f-05dc1138c3a3","tools":["Bash","finder","create_file","edit_file","glob","Grep","mcp__postgres__query","oracle","Read","read_mcp_resource","read_web_page","Task","todo_read","todo_write","undo_edit","web_search"],"mcp_servers":[{"name":"postgres","status":"connected"}]}
{"type":"user","message":{"role":"user","content":[{"type":"text","text":"what is 3 + 5?"}]},"parent_tool_use_id":null,"session_id":"T-f9941a55-3765-421e-972f-05dc1138c3a3"}
{"type":"assistant","message":{"type":"message","role":"assistant","content":[{"type":"text","text":"8"}],"stop_reason":"end_turn","usage":{"input_tokens":10,"cache_creation_input_tokens":16256,"cache_read_input_tokens":0,"output_tokens":99,"max_tokens":968000,"service_tier":"standard"}},"parent_tool_use_id":null,"session_id":"T-f9941a55-3765-421e-972f-05dc1138c3a3"}
{"type":"result","subtype":"success","duration_ms":5400,"is_error":false,"num_turns":1,"result":"8","session_id":"T-f9941a55-3765-421e-972f-05dc1138c3a3"}

工具使用示例：

$ amp --execute "list files using a tool" --stream-json
{"type":"system","subtype":"init","cwd":"/Users/orb/project","session_id":"T-d2fc4acc-dd1d-497f-9609-ed0da22a7c95","tools":["Bash","finder" ,"create_file","edit_file","glob","Grep","mcp__postgres__query","oracle","Read","read_mcp_resource","read_web_page","Task","todo_rea d","todo_write","undo_edit","web_search"],"mcp_servers":[{"name":"postgres","status":"connected"}]}
{"type":"user","message":{"role":"user","content":[{"type":"text","text":"list files using a tool"}]},"parent_tool_use_id":null,"session_id":"T-d2fc4acc-dd1d-4 97f-9609-ed0da22a7c95"}
{"type":"assistant","message":{"type":"message","role":"assistant","content":[{"type":"tool_use","id":"toolu_019cyniPYrSgaJitUSMyxyNV","name": "read", "input":{"path":"/Users/orb/project"}}],"stop_reason":"tool_use","usage":{"input_tokens":10,"cache_creation_input_tokens":13150,"cache_read_input_tokens": 0,"output_tokens":111,"max_tokens":968000,"service_tier":"standard"}},"parent_tool_use_id":null,"session_id":"T-d2fc4acc-dd1d-497f-9609-ed0da22a7c95"}
{"type":"user","message":{"role":"user","content":[{"type":"tool_result","tool_use_id":"toolu_019cyniPYrSgaJitUSMyxyNV","content":"[\"index.js\",\"README.md\"] ","is_error":false}]},"parent_tool_use_id":null,"session_id":"T-d2fc4acc-dd1d-497f-9609-ed0da22a7c95"}
{"type":"assistant","message":{"type":"message","role":"assistant","content":[{"type":"text","text":"Two files: index.js and README.md"}],"stop_reason":"end_tu rn","usage":{"input_tokens":7,"cache_creation_input_tokens":133,"cache_read_input_tokens":13150,"output_tokens":13,"max_tokens":968000,"service_tier":"standard "}},"parent_tool_use_id":null,"session_id":"T-d2fc4acc-dd1d-497f-9609-ed0da22a7c95"}
{"type":"result","subtype":"success","duration_ms":7363,"is_error":false,"num_turns":2,"result":"Two files: index.js and README.md","session_id":"T-d2fc4acc-dd1d-497f-9609-ed0da22a7c95"}

流式 JSON 输入（--stream-json-input)

--stream-json-input 标志启用 流式输入 ，其中 Amp 从 stdin 读取消息直到关闭。

每条消息应为单行的有效 JSON 对象。输入内容块可以是纯文本或 base64 编码的图片：

type StreamJSONInputMessage = {
  type: "user";
  message: {
    role: "user";
    content: Array<{
      type: "text";
      text: string;
    } | {
      type: "image";
      source_path?: string;
      source: {
        type: "base64";
        media_type: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
        data: string;
      };
    }>;
  };
}

设置 steer 添加到 true ，当消息在代理忙碌时排队时，将其标记为 steering。steering 排队消息会在下一个中断点处理。

type StreamJSONInputMessage = {
  type: "user";
  steer?: boolean;
  message: { ... };
}

示例消息：

{
  "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": "..."
        }
      }
    ]
  }
}

source_path 是可选的。如果省略，Amp 会自动生成。声明的 media_type 必须与解码后的图片字节匹配。对于 Claude 兼容输出，用户图片块在输入时被接受，但会从 stdout 上的流式 user 消息中省略。

使用 --stream-json-input时， --execute 的行为会变化：Amp 只有在 assistant 完成后 和 且 stdin 关闭时才会退出。

这允许程序化使用 Amp CLI 进行多条 user messages 的对话。

示例：

#!/bin/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

此脚本产生以下输出：

$ ./script.sh
{"type":"system","subtype":"init","cwd":"/Users/orb","session_id":"T-addfb7a4-61d9-41e1-890b-7330aa54087a","tools":["Bash","finder","create_file","edit_file","glob","Grep","mcp__postgres__query","oracle","Read","read_mcp_resource","read_web_page","Task","todo_read","todo_write","undo_edit","web_search"],"mcp_servers":[{"name":"postgres","status":"connected"}]}
{"type":"user","message":{"role":"user","content":[{"type":"text","text":"what's 2+2?"}]},"parent_tool_use_id":null,"session_id":"T-addfb7a4-61d9-41e1-890b-7330aa54087a"}
{"type":"assistant","message":{"type":"message","role":"assistant","content":[{"type":"text","text":"4"}],"stop_reason":"end_turn","usage":{"input_tokens":10,"cache_creation_input_tokens":13993,"cache_read_input_tokens":0,"output_tokens":67,"max_tokens":968000,"service_tier":"standard"}},"parent_tool_use_id":null,"session_id":"T-addfb7a4-61d9-41e1-890b-7330aa54087a"}
{"type":"user","message":{"role":"user","content":[{"type":"text","text":"now add 8 to that"}]},"parent_tool_use_id":null,"session_id":"T-addfb7a4-61d9-41e1-890b-7330aa54087a"}
{"type":"assistant","message":{"type":"message","role":"assistant","content":[{"type":"text","text":"12"}],"stop_reason":"end_turn","usage":{"input_tokens":10,"cache_creation_input_tokens":36,"cache_read_input_tokens":13993,"output_tokens":76,"max_tokens":968000,"service_tier":"standard"}},"parent_tool_use_id":null,"session_id":"T-addfb7a4-61d9-41e1-890b-7330aa54087a"}
{"type":"user","message":{"role":"user","content":[{"type":"text","text":"now add 5 to that"}]},"parent_tool_use_id":null,"session_id":"T-addfb7a4-61d9-41e1-890b-7330aa54087a"}
{"type":"assistant","message":{"type":"message","role":"assistant","content":[{"type":"text","text":"17"}],"stop_reason":"end_turn","usage":{"input_tokens":10,"cache_creation_input_tokens":36,"cache_read_input_tokens":14029,"output_tokens":43,"max_tokens":968000,"service_tier":"standard"}},"parent_tool_use_id":null,"session_id":"T-addfb7a4-61d9-41e1-890b-7330aa54087a"}
{"type":"result","subtype":"success","duration_ms":21639,"is_error":false,"num_turns":3,"result":"17","session_id":"T-addfb7a4-61d9-41e1-890b-7330aa54087a"}

子代理支持

流式 JSON 模式完全支持由 Task 工具创建的子代理：

  • 子代理消息 有其 parent_tool_use_id 字段设置为 Task 工具的 ID
  • 主代理消息 有 parent_tool_use_id 设置为 null
  • 完成邏輯 等待所有子代理完成后才发出最终结果

子代理示例：

$ amp --execute "use Task tool to calculate 4+7" --stream-json
{"type":"system","subtype":"init",...}
{"type":"assistant","message":{"content":[{"type":"tool_use","id":"toolu_123","name":"Task",...}]},"parent_tool_use_id":null,...}
{"type":"assistant","message":{"content":[{"type":"text","text":"11"}]},"parent_tool_use_id":"toolu_123",...}
{"type":"user","message":{"content":[{"type":"tool_result","tool_use_id":"toolu_123",...}]},"parent_tool_use_id":null,...}
{"type":"result","subtype":"success",...}

Claude Code 兼容性

Amp 的流式 JSON 输出尽可能与 Claude Code 的格式兼容。当 --stream-json-thinking 启用时，输出包含不属于 Claude Code 公开模式的额外内容块类型。

工作区对话可见性控制

默认情况下，工作空间成员创建的对话 与工作空间共享.

企业版 工作空间可以在 工作区设置 页面中配置额外的对话可见性选项。目前支持的选项包括：

  • 禁用公开（未列出或可发现）对话
  • 禁用私有对话
  • 默认为私有的对话

根据要求，企业版工作空间还可以启用用户组和每组对话可见性。

了解更多关于对话可见性的信息，请参阅 隐私与权限.

工作区权益

Amp 企业版高级版工作空间可以通过权益设置每个用户的使用配额，例如：

  • 普通用户默认 $50/周，高级工程师 $200/周
  • 全团队 $100/天的限额，对所有人生效
  • 承包商和全职员工有不同的限额

要开始使用，前往 工作区设置 页面并导航到“权益”部分。

分配权益

可以通过四种方式为用户分配权益：

  • 默认：可以将一项权益标记为默认，适用于没有更具体分配的所有工作区成员。
  • 个人：直接将权益分配给特定的工作空间成员。
  • 工作区用户组：将权益分配给一个 Amp 工作区用户组。工作区用户组权益仍处于实验阶段。该组当前成员会获得该权益，成员变更也会更新权益覆盖范围。
  • 目录组：将权益链接到通过 SCIM 从身份提供商（如 Okta、Entra ID）同步的一个或多个目录组。这些组的成员会自动获得该权益。

工作区用户组权益

工作区用户组权益仍处于实验阶段，并使用 Amp 工作区用户组。当工作区管理员希望直接在 Amp 中管理支出类别，而不是通过身份提供商管理时，它们会很有用。

创建或编辑权益时，选择“工作区用户组”作为分配类型，选择一个工作区用户组并保存。所选用户组的当前成员会自动获得该权益。

目录组权益

如果你的工作区启用了目录同步（通过 WorkOS SCIM），你可以根据 IdP 组成员身份分配权益。这对于希望权益分配与身份提供商自动保持同步的组织很有用。

创建或编辑权益时，选择“目录组”作为分配类型，选择一个目录和一个或多个组，然后保存。属于所选组的成员且已加入工作区的用户将自动获得该权益。

解析优先级：当用户符合多项权益时，有效权益按以下顺序确定：

  1. 个人权益
  2. 工作区用户组权益
  3. 目录组权益
  4. 默认权益

如果用户在同一优先级满足多个权益，则采用标准化每日配额最高的权益。

用量会按用户和权益窗口跟踪。Amp 会根据用户的有效权益检查支出。如果该权益发生变化，已计入其他权益的支出不会计入当前限制。