agent-sdk/slash-commands.md +0 −594 deleted
File Deleted View Diff
1> ## Documentation Index
2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
3> Use this file to discover all available pages before exploring further.
4
5# SDK 中的 slash commands
6
7> 学习如何通过 SDK 使用 slash commands 来控制 Claude Code 会话
8
9Slash commands 提供了一种方式来控制 Claude Code 会话，使用以 `/` 开头的特殊命令。这些命令可以通过 SDK 发送，以执行诸如压缩上下文、列出上下文使用情况或调用自定义命令等操作。只有在不需要交互式终端的情况下工作的命令才能通过 SDK 分派；`system/init` 消息列出了在您的会话中可用的命令。
10
11<h2 id="discovering-available-slash-commands">
12 发现可用的 Slash Commands
13</h2>
14
15Claude Agent SDK 在系统初始化消息中提供有关可用 slash commands 的信息。在您的会话开始时访问此信息：
16
17<CodeGroup>
18 ```typescript TypeScript theme={null}
19 import { query } from "@anthropic-ai/claude-agent-sdk";
20
21 for await (const message of query({
22 prompt: "Hello Claude",
23 options: { maxTurns: 1 }
24 })) {
25 if (message.type === "system" && message.subtype === "init") {
26 console.log("Available slash commands:", message.slash_commands);
27 // 包括内置命令加上捆绑的 skills，例如：
28 // ["clear", "compact", "context", "usage", "code-review", "verify", ...]
29 }
30 }
31 ```
32
33 ```python Python theme={null}
34 import asyncio
35 from claude_agent_sdk import query, ClaudeAgentOptions, SystemMessage
36
37
38 async def main():
39 async for message in query(prompt="Hello Claude", options=ClaudeAgentOptions(max_turns=1)):
40 if isinstance(message, SystemMessage) and message.subtype == "init":
41 print("Available slash commands:", message.data["slash_commands"])
42 # 包括内置命令加上捆绑的 skills，例如：
43 # ["clear", "compact", "context", "usage", "code-review", "verify", ...]
44
45
46 asyncio.run(main())
47 ```
48</CodeGroup>
49
50<h2 id="sending-slash-commands">
51 发送 Slash Commands
52</h2>
53
54通过在您的提示字符串中包含 slash commands 来发送它们，就像常规文本一样。作用于对话历史的命令，例如 `/compact`，需要先前的消息来处理，因此下面的示例首先提出一个问题，然后将命令作为后续发送到同一对话：
55
56<CodeGroup>
57 ```typescript TypeScript theme={null}
58 import { query } from "@anthropic-ai/claude-agent-sdk";
59
60 // Build up conversation history first
61 try {
62 for await (const message of query({
63 prompt: "What does the README in this directory cover?",
64 options: { maxTurns: 2 }
65 })) {
66 if (message.type === "result" && message.subtype === "success") {
67 console.log(message.result);
68 }
69 }
70 } catch (error) {
71 // A single-shot query() throws after yielding an error result,
72 // so the follow-up query below still runs.
73 console.error(`Session ended with an error: ${error}`);
74 }
75
76 // Send a slash command as a follow-up to the same conversation
77 for await (const message of query({
78 prompt: "/compact",
79 options: { continue: true, maxTurns: 1 }
80 })) {
81 if (message.type === "result") {
82 console.log("Command executed, result subtype:", message.subtype);
83 // Example output: Command executed, result subtype: success
84 }
85 }
86 ```
87
88 ```python Python theme={null}
89 import asyncio
90 from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage
91
92
93 async def main():
94 # Build up conversation history first
95 try:
96 async for message in query(
97 prompt="What does the README in this directory cover?",
98 options=ClaudeAgentOptions(max_turns=2),
99 ):
100 if isinstance(message, ResultMessage) and message.subtype == "success":
101 print(message.result)
102 except Exception as error:
103 # A single-shot query() raises after yielding an error result,
104 # so the follow-up query below still runs.
105 print(f"Session ended with an error: {error}")
106
107 # Send a slash command as a follow-up to the same conversation
108 async for message in query(
109 prompt="/compact",
110 options=ClaudeAgentOptions(continue_conversation=True, max_turns=1),
111 ):
112 if isinstance(message, ResultMessage):
113 print("Command executed, result subtype:", message.subtype)
114 # Example output: Command executed, result subtype: success
115
116
117 asyncio.run(main())
118 ```
119</CodeGroup>
120
121<Note>
122 查询可能以错误结果结束，例如当 `maxTurns` / `max_turns` 限制在工作完成前被达到时。最终结果消息随后具有 `is_error: true` 和错误子类型（例如 `error_max_turns`）而不是 `success`。
123
124 在产生该最终结果消息后，SDK 会抛出错误，因为 CLI 进程以非零代码退出。
125
126 如果您的命令可能达到限制，请在 TypeScript 中将循环包装在 `try`/`catch` 中或在 Python 中使用 `try`/`except`，如 [Single Message Input](/zh-CN/agent-sdk/streaming-vs-single-mode#single-message-input) 中所示，或设置 `maxTurns` 足够高以完成工作。在 Python 中，捕获 `Exception`：SDK 将错误结果作为普通 `Exception` 呈现。
127</Note>
128
129<h2 id="common-slash-commands">
130 常见的 Slash Commands
131</h2>
132
133<h3 id="/compact-compact-conversation-history">
134 `/compact` - 压缩对话历史
135</h3>
136
137`/compact` 命令通过总结较早的消息同时保留重要上下文来减少您的对话历史的大小。压缩需要至少有两次先前交互的现有对话来进行总结。此示例首先进行对话，然后压缩它并读取报告结果的 `compact_boundary` 系统消息：
138
139<CodeGroup>
140 ```typescript TypeScript theme={null}
141 import { query } from "@anthropic-ai/claude-agent-sdk";
142
143 // Compaction needs existing history, so have a conversation first
144 try {
145 for await (const message of query({
146 prompt: "Explain what this project does",
147 options: { maxTurns: 2 }
148 })) {
149 if (message.type === "result" && message.subtype === "success") {
150 console.log(message.result);
151 }
152 }
153 } catch (error) {
154 // A single-shot query() throws after yielding an error result,
155 // so the follow-up query below still runs.
156 console.error(`Session ended with an error: ${error}`);
157 }
158
159 // Compact the same conversation
160 for await (const message of query({
161 prompt: "/compact",
162 options: { continue: true, maxTurns: 1 }
163 })) {
164 if (message.type === "system" && message.subtype === "compact_boundary") {
165 console.log("Compaction completed");
166 console.log("Pre-compaction tokens:", message.compact_metadata.pre_tokens);
167 console.log("Trigger:", message.compact_metadata.trigger);
168 // Example output:
169 // Compaction completed
170 // Pre-compaction tokens: 1842
171 // Trigger: manual
172 }
173 }
174 ```
175
176 ```python Python theme={null}
177 import asyncio
178 from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage, SystemMessage
179
180
181 async def main():
182 # Compaction needs existing history, so have a conversation first
183 try:
184 async for message in query(
185 prompt="Explain what this project does",
186 options=ClaudeAgentOptions(max_turns=2),
187 ):
188 if isinstance(message, ResultMessage) and message.subtype == "success":
189 print(message.result)
190 except Exception as error:
191 # A single-shot query() raises after yielding an error result,
192 # so the follow-up query below still runs.
193 print(f"Session ended with an error: {error}")
194
195 # Compact the same conversation
196 async for message in query(
197 prompt="/compact",
198 options=ClaudeAgentOptions(continue_conversation=True, max_turns=1),
199 ):
200 if isinstance(message, SystemMessage) and message.subtype == "compact_boundary":
201 print("Compaction completed")
202 print("Pre-compaction tokens:", message.data["compact_metadata"]["pre_tokens"])
203 print("Trigger:", message.data["compact_metadata"]["trigger"])
204 # Example output:
205 # Compaction completed
206 # Pre-compaction tokens: 1842
207 # Trigger: manual
208
209
210 asyncio.run(main())
211 ```
212</CodeGroup>
213
214<Note>
215 `compact_boundary` 消息仅在压缩运行时到达。如果没有要总结的内容，`/compact` 会报告原因而不是抛出异常：运行仍然以 `success` 结果结束，不会发出 `compact_boundary` 消息，结果文本会携带消息，例如在单次简短交互后显示 `Not enough messages to compact.`。全新的一次性 `query()` 调用以空上下文开始，因此请在具有先前轮次的会话中使用此模式，例如在[流式输入模式](/zh-CN/agent-sdk/streaming-vs-single-mode)中或恢复会话时。
216</Note>
217
218<h3 id="/clear-reset-conversation-context">
219 `/clear` - 重置对话上下文
220</h3>
221
222`/clear` 命令将对话重置为空上下文，因此后续提示将从没有先前对话历史的状态开始。之前的对话保留在磁盘上，可以通过将其会话 ID 传递给 [`resume` 选项](/zh-CN/agent-sdk/sessions#resume-by-id) 来返回。
223
224这在[流式输入模式](/zh-CN/agent-sdk/streaming-vs-single-mode)中很有用，在该模式下您通过单个连接发送多个提示。对于一次性 `query()` 调用，每个调用已经以空上下文开始，因此发送 `/clear` 没有实际效果；请改为启动一个新的 `query()`。
225
226<Note>
227 SDK 中的 `/clear` 需要 Claude Code v2.1.117 或更高版本。在早期版本中，它从 `slash_commands` 中被省略。
228</Note>
229
230<h2 id="creating-custom-slash-commands">
231 创建自定义 Slash Commands
232</h2>
233
234除了使用内置 slash commands 外，您还可以创建自己的自定义命令，这些命令可通过 SDK 使用。自定义命令定义为特定目录中的 markdown 文件，类似于 subagents 的配置方式。
235
236<Note>
237 `.claude/commands/` 目录是旧版格式。推荐的格式是 `.claude/skills/<name>/SKILL.md`，它支持相同的 slash command 调用（`/name`）加上 Claude 的自主调用。有关当前格式，请参阅 [Skills](/zh-CN/agent-sdk/skills)。CLI 继续支持两种格式，下面的示例对于 `.claude/commands/` 仍然准确。
238</Note>
239
240<h3 id="file-locations">
241 文件位置
242</h3>
243
244自定义 slash commands 根据其范围存储在指定的目录中：
245
246* **项目命令**：`.claude/commands/` - 仅在当前项目中可用（旧版；优先使用 `.claude/skills/`）
247* **个人命令**：`~/.claude/commands/` - 在您的所有项目中可用（旧版；优先使用 `~/.claude/skills/`）
248
249<h3 id="file-format">
250 文件格式
251</h3>
252
253每个自定义命令都是一个 markdown 文件，其中：
254
255* 文件名（不带 `.md` 扩展名）成为命令名称
256* 文件内容定义命令的功能
257* 可选的 YAML frontmatter 提供配置
258
259<h4 id="basic-example">
260 基本示例
261</h4>
262
263在您的项目中创建 `.claude/commands` 目录（如果不存在），然后创建 `.claude/commands/refactor.md`：
264
265```markdown theme={null}
266Refactor the selected code to improve readability and maintainability.
267Focus on clean code principles and best practices.
268```
269
270这创建了 `/refactor` 命令，您可以通过 SDK 使用它。
271
272<h4 id="with-frontmatter">
273 带有 Frontmatter
274</h4>
275
276创建 `.claude/commands/security-check.md`：
277
278```markdown theme={null}
279allowed-tools: Read, Grep, Glob
280description: Run security vulnerability scan
281model: claude-opus-4-8
282
283Analyze the codebase for security vulnerabilities including:
284- SQL injection risks
285- XSS vulnerabilities
286- Exposed credentials
287- Insecure configurations
288```
289
290<h3 id="using-custom-commands-in-the-sdk">
291 在 SDK 中使用自定义命令
292</h3>
293
294一旦在文件系统中定义，自定义命令就会自动通过 SDK 可用：
295
296<CodeGroup>
297 ```typescript TypeScript theme={null}
298 import { query } from "@anthropic-ai/claude-agent-sdk";
299
300 // Use a custom command
301 try {
302 for await (const message of query({
303 prompt: "/refactor src/auth/login.ts",
304 options: { maxTurns: 3 }
305 })) {
306 if (message.type === "assistant") {
307 console.log("Refactoring suggestions:", message.message);
308 }
309 }
310 } catch (error) {
311 // A single-shot query() throws after yielding an error result,
312 // so the second query below still runs.
313 console.error(`Session ended with an error: ${error}`);
314 }
315
316 // Custom commands appear in the slash_commands list
317 for await (const message of query({
318 prompt: "Hello",
319 options: { maxTurns: 1 }
320 })) {
321 if (message.type === "system" && message.subtype === "init") {
322 console.log("Available commands:", message.slash_commands);
323 // Includes built-in commands plus bundled skills and your custom commands, for example:
324 // ["clear", "compact", "context", "usage", "code-review", "verify", "refactor", "security-check", ...]
325 }
326 }
327 ```
328
329 ```python Python theme={null}
330 import asyncio
331 from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, SystemMessage
332
333
334 async def main():
335 # Use a custom command
336 try:
337 async for message in query(
338 prompt="/refactor src/auth/login.py", options=ClaudeAgentOptions(max_turns=3)
339 ):
340 if isinstance(message, AssistantMessage):
341 for block in message.content:
342 if hasattr(block, "text"):
343 print("Refactoring suggestions:", block.text)
344 except Exception as error:
345 # A single-shot query() raises after yielding an error result,
346 # so the second query below still runs.
347 print(f"Session ended with an error: {error}")
348
349 # Custom commands appear in the slash_commands list
350 async for message in query(prompt="Hello", options=ClaudeAgentOptions(max_turns=1)):
351 if isinstance(message, SystemMessage) and message.subtype == "init":
352 print("Available commands:", message.data["slash_commands"])
353 # Includes built-in commands plus bundled skills and your custom commands, for example:
354 # ["clear", "compact", "context", "usage", "code-review", "verify", "refactor", "security-check", ...]
355
356
357 asyncio.run(main())
358 ```
359</CodeGroup>
360
361<h3 id="advanced-features">
362 高级功能
363</h3>
364
365<h4 id="arguments-and-placeholders">
366 参数和占位符
367</h4>
368
369自定义命令支持使用占位符的动态参数：
370
371创建 `.claude/commands/fix-issue.md`：
372
373```markdown theme={null}
374argument-hint: [issue-number] [priority]
375description: Fix a GitHub issue
376
377Fix issue #$0 with priority $1.
378Check the issue description and implement the necessary changes.
379```
380
381在 SDK 中使用：
382
383<CodeGroup>
384 ```typescript TypeScript theme={null}
385 import { query } from "@anthropic-ai/claude-agent-sdk";
386
387 // Pass arguments to custom command
388 for await (const message of query({
389 prompt: "/fix-issue 123 high",
390 options: { maxTurns: 5 }
391 })) {
392 // Command will process with $0="123" and $1="high"
393 if (message.type === "result" && message.subtype === "success") {
394 console.log("Issue fixed:", message.result);
395 }
396 }
397 ```
398
399 ```python Python theme={null}
400 import asyncio
401 from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage
402
403
404 async def main():
405 # Pass arguments to custom command
406 async for message in query(prompt="/fix-issue 123 high", options=ClaudeAgentOptions(max_turns=5)):
407 # Command will process with $0="123" and $1="high"
408 if isinstance(message, ResultMessage):
409 print("Issue fixed:", message.result)
410
411
412 asyncio.run(main())
413 ```
414</CodeGroup>
415
416<h4 id="bash-command-execution">
417 Bash 命令执行
418</h4>
419
420自定义命令可以执行 bash 命令并包含其输出：
421
422创建 `.claude/commands/git-commit.md`：
423
424```markdown theme={null}
425allowed-tools: Bash(git add *), Bash(git status *), Bash(git commit *)
426description: Create a git commit
427
428## Context
429
430- Current status: !`git status`
431- Current diff: !`git diff HEAD`
432
433## Task
434
435Create a git commit with appropriate message based on the changes.
436```
437
438<h4 id="file-references">
439 文件引用
440</h4>
441
442使用 `@` 前缀包含文件内容：
443
444创建 `.claude/commands/review-config.md`：
445
446```markdown theme={null}
447description: Review configuration files
448
449Review the following configuration files for issues:
450- Package config: @package.json
451- TypeScript config: @tsconfig.json
452- Environment config: @.env
453
454Check for security issues, outdated dependencies, and misconfigurations.
455```
456
457<h3 id="organization-with-namespacing">
458 使用命名空间进行组织
459</h3>
460
461在子目录中组织命令以获得更好的结构：
462
463```bash theme={null}
464.claude/commands/
465├── frontend/
466│ ├── component.md # Creates /component (project:frontend)
467│ └── style-check.md # Creates /style-check (project:frontend)
468├── backend/
469│ ├── api-test.md # Creates /api-test (project:backend)
470│ └── db-migrate.md # Creates /db-migrate (project:backend)
471└── review.md # Creates /review (project)
472```
473
474子目录出现在命令描述中，但不影响命令名称本身。
475
476<h3 id="practical-examples">
477 实际示例
478</h3>
479
480<h4 id="pull-request-review-command">
481 Pull Request 审查命令
482</h4>
483
484创建 `.claude/commands/review-pr.md`：
485
486```markdown theme={null}
487allowed-tools: Read, Grep, Glob, Bash(git diff *)
488description: Comprehensive code review
489
490## Changed Files
491!`git diff --name-only HEAD~1`
492
493## Detailed Changes
494!`git diff HEAD~1`
495
496## Review Checklist
497
498Review the above changes for:
4991. Code quality and readability
5002. Security vulnerabilities
5013. Performance implications
5024. Test coverage
5035. Documentation completeness
504
505Provide specific, actionable feedback organized by priority.
506```
507
508<Note>
509 Claude Code 包含捆绑的 `code-review` 和 `verify` skills。如果您以其中之一的名称命名自定义命令，例如 `.claude/commands/code-review.md`，您的命令会覆盖捆绑的 skill，`slash_commands` 列表中该名称仅出现一次。
510</Note>
511
512<h4 id="test-runner-command">
513 测试运行器命令
514</h4>
515
516创建 `.claude/commands/test.md`：
517
518```markdown theme={null}
519allowed-tools: Bash, Read, Edit
520argument-hint: [test-pattern]
521description: Run tests with optional pattern
522
523Run tests matching pattern: $ARGUMENTS
524
5251. Detect the test framework (Jest, pytest, etc.)
5262. Run tests with the provided pattern
5273. If tests fail, analyze and fix them
5284. Re-run to verify fixes
529```
530
531通过 SDK 使用这些命令：
532
533<CodeGroup>
534 ```typescript TypeScript theme={null}
535 import { query } from "@anthropic-ai/claude-agent-sdk";
536
537 // Run code review
538 try {
539 for await (const message of query({
540 prompt: "/review-pr",
541 options: { maxTurns: 3 }
542 })) {
543 // Process review feedback
544 }
545 } catch (error) {
546 // A single-shot query() throws after yielding an error result,
547 // so the second query below still runs.
548 console.error(`Session ended with an error: ${error}`);
549 }
550
551 // Run specific tests
552 for await (const message of query({
553 prompt: "/test auth",
554 options: { maxTurns: 5 }
555 })) {
556 // Handle test results
557 }
558 ```
559
560 ```python Python theme={null}
561 import asyncio
562 from claude_agent_sdk import query, ClaudeAgentOptions
563
564
565 async def main():
566 # Run code review
567 try:
568 async for message in query(prompt="/review-pr", options=ClaudeAgentOptions(max_turns=3)):
569 # Process review feedback
570 pass
571 except Exception as error:
572 # A single-shot query() raises after yielding an error result,
573 # so the second query below still runs.
574 print(f"Session ended with an error: {error}")
575
576 # Run specific tests
577 async for message in query(prompt="/test auth", options=ClaudeAgentOptions(max_turns=5)):
578 # Handle test results
579 pass
580
581
582 asyncio.run(main())
583 ```
584</CodeGroup>
585
586<h2 id="see-also">
587 另请参阅
588</h2>
589
590* [Slash Commands](/zh-CN/skills) - 完整的 slash command 文档
591* [SDK 中的 Subagents](/zh-CN/agent-sdk/subagents) - 类似的基于文件系统的 subagents 配置
592* [TypeScript SDK 参考](/zh-CN/agent-sdk/typescript) - 完整的 API 文档
593* [SDK 概述](/zh-CN/agent-sdk/overview) - 一般 SDK 概念
594* [CLI 参考](/zh-CN/cli-reference) - 命令行界面