模块 100：自定义斜杠命令与宏系统（cc command / slash macros）

状态：✅ 已落地（CLI 0.162.x）| 对标 Claude-Code custom slash commands | 用户文档：docs-site/docs/chainlesschain/slash-commands.md

1. 背景与目标

Claude-Code 支持把可复用的 prompt 写成 .claude/commands/*.md，在 REPL 里用 /<name> 一键展开。cc 此前只有内置 REPL 斜杠命令（/auto、/plan、/compact 等，见模块 67）和 AI 触发的 Skills，缺一个"用户自定义、确定性展开、零 AI 参与"的 prompt 宏层。本模块补齐这一层，并保持与 Claude-Code 的文件格式互通（同一个 .claude/commands/ 目录两边都能用）。

与 Skills 的边界：Skill 由 AI 根据任务自主选择触发，正文是给 AI 的能力说明；slash 宏由用户显式调用，正文是会被确定性展开后注入对话的 prompt 模板。两者互补，不互相替代。

2. 架构

.claude/commands/*.md（项目级）          ~/.claude/commands/*.md（个人级）
        └────────────┬───────────────────────────┘
                     ▼
      packages/cli/src/lib/slash-commands.js
      （discoverCommands 扫描 + frontmatter 零依赖解析，不引 js-yaml）
                     │
        ┌────────────┴─────────────┐
        ▼                          ▼
  REPL: repl/slash-macro.js   CLI: commands/command.js（alias: cmd）
  resolveSlashMacro 把         list|ls / show <name> /
  `/<name> [args]` 展开为      run <name> [args...] / new <name>
  prompt 注入当前会话           headless 跑宏或脚手架新宏

3. 展开语义（确定性，无 AI 参与）

语法	语义
$ARGUMENTS	调用时整段参数原样替换
$1 … $9	位置参数
!`cmd`（感叹号 + 反引号包裹的 shell 命令）	展开时执行该命令，stdout 内联进 prompt
@<path>	文件内容内联（复用 @file 引用展开器）

frontmatter 支持 description（列表展示）等字段；解析器为手写零依赖实现（不引 js-yaml / skill-loader，避免 CLI 包体与 hoisting 风险，见 memory cli_undeclared_dep_hoisting_global_crash）。

4. 命名空间与相邻系统

• 内置 REPL 斜杠命令（/auto、/plan、/compact、/output-style、/terminal…）：硬编码在 agent-repl，优先级高于同名宏。
• MCP prompts（0.162.38+）：已连接 MCP server 的 prompts 自动注册为 /mcp__<server>__<prompt> [args]，/mcp 总览；与用户宏经命名空间前缀天然隔离（模块 98 相邻面）。
• 发现优先级：项目级 .claude/commands/ 覆盖个人级 ~/.claude/commands/ 同名宏。

5. 安全考虑

• !`bash` 在展开时于用户本机执行——与用户自己敲 shell 等价，不经过 agent 工具权限层；文档中明确提示宏文件应当与代码一起 review。
• 宏正文最终只是 prompt 文本，注入后仍受 agent 既有权限规则（settings.json allow/ask/deny、shell 硬黑名单）约束。
• frontmatter 解析为白名单字段提取，畸形文件跳过不崩。

6. 测试与现状

• 单测覆盖 discover/解析/展开/REPL 集成（packages/cli/__tests__/ slash-commands 相关套件）。
• 用户文档 11 模块齐全：docs-site/docs/chainlesschain/slash-commands.md；官网 /cli/ 展示条目 cc command list / run。
• 演进方向：宏内调用 skill 的语法糖、cc command 对 --claude 双格式导出（与 cc agents new --claude 对齐）。

7. 相关模块

• 模块 67（CLI 高级功能 — 内置斜杠命令）/ 模块 88（OpenAgents 对标 — @file 引用展开）/ 模块 98（IDE 桥接 — MCP prompts slash 命名空间）/ 模块 99（项目记忆 cc.md — 同属"项目级 .claude 资产"家族）

附录：规范章节补全（v5.0.3.108）

本文为系统设计子文档。为对齐项目文档标准结构，下列章节以 见正文 指引或简述方式补齐若干视角，不重复正文细节。

1. 概述

见正文「模块概述 / 功能描述」。自定义斜杠命令与宏系统（cc command / slash macros）：用户自定义 slash 命令宏。

2. 核心特性

slash 命令宏 / .claude/commands / 参数 / 展开。

3. 系统架构

见正文「架构设计」。

4. 系统定位

ChainlessChain 的「自定义斜杠命令与宏系统」。

5. 核心功能

见正文模块概述与各节。

6. 技术架构

见正文实现章节。

7. 系统特点

见正文（状态 / 版本 / 特性）。

8. 应用场景

见正文应用场景 / 背景。

9. 竞品对比

见正文对比（如有）。

10. 配置参考

见正文配置 / 参数章节。

11. 性能指标

见正文性能 / 指标章节。

12. 测试覆盖

见正文测试章节。

13. 安全考虑

见正文安全 / 权限章节。

14. 故障排除

见正文故障 / 已知限制章节。

15. 关键文件

见正文实现位置 / 关键文件章节。

16. 使用示例

见正文使用 / API 示例。

17. 相关文档

系统设计主文档、docs-site 对应功能页。