Copilot CLI 深度上手指南

# macOS ARM — 首选路径
brew install copilot-cli
​
# 验证
copilot --version

# 全平台 npm 方式（Node.js 22+ 为前提）
npm install -g @github/copilot
​
# 若 ~/.npmrc 中存在 ignore-scripts=true，必须显式开启 scripts
npm_config_ignore_scripts=false npm install -g @github/copilot

# Windows — WinGet
winget install GitHub.Copilot
# 前提：PowerShell v6+，低于此版本需先升级

% copilot --version
GitHub Copilot CLI/
Run 'copilot update' to check for updates.
​
# 建议执行一次 copilot update 更新到最新版

# 首次运行会提示安装 Copilot CLI
gh copilot
​
# 后续所有 args 和 flags 会自动转发给 copilot 命令
gh copilot -sp "YOUR PROMPT HERE"

copilot          # 启动 CLI
/login           # 在 CLI 内执行，触发 OAuth device flow

/user list      # 列出已认证的账号
/user switch    # 切换账号
/logout         # 移除本地 token（不撤销 GitHub 侧授权）

cd /path/to/your-project
copilot
# CLI 会询问是否信任当前目录，选择 "Yes, and remember" 避免重复确认

# 案例 使用 Plan Mode：将 refinex-ai 服务从 Spring MVC 迁移到 WebFlux，并保留所有现有的测试覆盖率
/plan Migrate refinex-ai service from Spring MVC to WebFlux, keeping all existing test coverage

/session               # 查看当前 session 信息
/session checkpoints   # 列出压缩检查点
/context               # 可视化当前 token 使用分布
/compact               # 手动触发压缩（通常不需要手动执行）
/clear                 # 开始新对话（保留工具配置，清除对话历史）

~/.copilot/session-state/{session-id}/
├── events.jsonl     # 完整 session 历史
├── workspace.yaml   # 元数据
├── plan.md          # 实现计划（如果生成了）
└── checkpoints/     # 压缩历史快照

/model    # 在 CLI 内切换模型

/init              # Copilot 分析当前仓库结构，自动生成 .github/copilot-instructions.md
/init suppress     # 如果不需要，抑制后续的 init 建议提示

# .github/copilot-instructions.md
​
## 构建与测试命令
- 构建：`./mvnw clean package -DskipTests`
- 单元测试：`./mvnw test`
- 集成测试：`./mvnw verify -Pintegration`
- 代码检查：`./mvnw checkstyle:check`
​
## 技术栈约束
- Java 21，Spring Boot 3.5.x，Spring Cloud 2025.0.x
- MVC 模块（CRUD）与 WebFlux 模块（AI 流式）严格分离，禁止在同一 service 模块混用
- ORM 使用 MyBatis-Plus，禁止在 Mapper 层写 SQL 以外的业务逻辑
- 分布式事务使用 Seata AT 模式，跨服务写操作必须标注 @GlobalTransactional
​
## 代码规范
- 所有 public API 方法必须有 Javadoc，说明参数含义和异常情况
- 异常处理：业务异常继承 BizException，禁止直接抛出 RuntimeException
- 每个 PR 必须包含对应的单元测试，覆盖率不低于 80%
​
## 提交规范
- 遵循 Conventional Commits：feat/fix/docs/refactor/test/chore
- 每次提交前执行 `./mvnw checkstyle:check && ./mvnw test`

---
applyTo: "refinex-ai/src/**/*.java"
---
​
## refinex-ai 模块专属约束
- 所有 AI 接口使用 WebFlux（返回 Flux<T> 或 Mono<T>），禁止返回同步类型
- SSE 端点必须在 ResponseEntity<Flux<ServerSentEvent<String>>> 上声明 produces = TEXT_EVENT_STREAM_VALUE
- ChatClient 实例必须通过 Spring 注入，禁止在方法内 new ChatClient.Builder()
- Reactor Context 传递用户身份，禁止通过 ThreadLocal（WebFlux 不保证线程绑定）

# AGENTS.md（例如放在 ~/projects/refinex/ 父目录，或单仓库根目录）
​
## 项目概览
Refinex-Cloud 是基于 Spring Boot 3.5.x + Spring Cloud 2025.0.x 的微服务平台。
主要服务：refinex-gateway / refinex-ai / refinex-auth / refinex-system。
​
## 全局技术约束
- Java 21，禁止使用 Java 8 / 11 语法（var 可用，records 优先于 POJO）
- MVC 与 WebFlux 严格分离：CRUD 服务用 MVC，AI 流式服务用 WebFlux，禁止混用
- 所有跨服务调用通过 OpenFeign，禁止直接使用 RestTemplate 或 WebClient 在业务层
- 分布式事务必须用 Seata AT 模式，@GlobalTransactional 注解不可省略
​
## 构建与验证
- 修改代码后必须运行：`./mvnw checkstyle:check && ./mvnw test`
- 禁止提交 checkstyle 不通过的代码
- 集成测试：`./mvnw verify -Pintegration`（仅在完整功能变更后执行）
​
## 提交规范
- 遵循 Conventional Commits：feat / fix / docs / refactor / test / chore
- commit message 格式：`type(scope): description`，scope 使用服务名（如 `feat(refinex-ai): ...`）
- 每个 PR 必须包含对应测试，覆盖率不低于 80%
​
## AI / MCP 工具使用策略
- 涉及 5 个以上文件的变更必须先使用 Plan Mode（Shift+Tab）
- 需要查询 API 文档时，优先使用 Context7 MCP（而非凭记忆生成）
- 生成代码前，先用只读分析确认现有结构，再执行修改
- 禁止在未经审批的情况下执行 git push（已在 hooks 中拦截）
​
## 异常处理规范
- 业务异常统一继承 BizException（不要直接抛 RuntimeException）
- 所有 public API 方法必须有 Javadoc，说明参数、返回值和异常
- WebFlux 链中的错误使用 .onErrorResume() 处理，禁止 try-catch 包裹响应式调用
​
## 安全规范
- 所有接口默认需鉴权，@SaIgnore 豁免必须有注释说明原因
- 禁止在代码中硬编码密钥、密码、Token（使用 Nacos 配置中心或环境变量）
- MyBatis-Plus Wrapper 中禁止拼接未经校验的外部输入（SQL 注入风险）

# Unified Personal Agent Rules
​
- Reply to my questions in Chinese, unless the code context is in English
- Use Chinese for code comments
- Provide concise, data-driven explanations
- When reviewing code, prioritize: **security > correctness > performance > readability**
- Always show reasoning before the conclusion
- Prefer showing **diffs** over full file rewrites
- Prefer functional programming style
- Follow standard Git conventions for commands and write commit messages in Chinese
- Always use Context7 MCP when I need library/API documentation, code generation, setup or configuration steps without me having to explicitly ask.

# 统一个人代理规则
​
- 除非代码上下文为英文，否则请用中文回复我的问题。
- 使用中文编写代码注释。
- 提供简洁、数据驱动的解释。
- 代码审查时，优先考虑：**安全性 > 正确性 > 性能 > 可读性**。
- 始终在得出结论之前展示推理过程。
- 优先展示**差异**，而不是整个文件重写。
- 优先采用函数式编程风格。
- 遵循标准的 Git 命令规范，并使用中文编写提交信息。
- 当我需要库/API 文档、代码生成、设置或配置步骤时，始终使用 Context7 MCP，而无需我明确提出要求。

使用中文生成 changelog。按 Conventional Commits 类型分组：
- 🚀 新功能（feat）
- 🐛 修复（fix）
- ⚡ 性能优化（perf）
- 🛠 重构（refactor）
- 📝 文档（docs）
- 🧪 测试（test）
每条格式：- 中文描述（scope）
省略 chore/ci/style 等无用户感知的变更。如果有 Breaking Changes，单独列出并用 ⚠️ 标记。

使用中文生成 commit 消息。严格遵循 Conventional Commits 规范：
- 格式：<type>(<scope>): <中文描述>
- type 只能是：feat / fix / docs / refactor / test / chore / perf / ci / style / build
- scope 使用模块名或文件名（如 auth、gateway、pom）
- 描述用中文，动词开头，不加句号
- 单行不超过 72 字符
- 示例：feat(refinex-ai): 新增 DeepSeek 模型接入支持

使用中文生成 commit 内容。将变更拆分为原子化的逻辑单元，每个 commit 只做一件事。
- 每个 commit 消息严格遵循 Conventional Commits：<type>(<scope>): <中文描述>
- 按逻辑顺序排列：底层依赖先于上层调用
- 测试文件与实现代码合并在同一 commit
- 配置文件变更单独一个 commit

使用中文生成 stash 消息。格式：WIP: <当前正在做的事情>。简洁明了，一句话说明保存现场的原因。
示例：WIP: 重构 ToolCallService 的参数校验逻辑，等待 API 确认

Generate a concise title and description in English for the cloud patch.
- Title: imperative mood, max 72 chars, summarize the change
- Description: explain what changed and why in 2-3 sentences, mention affected modules

Generate a clear title and description in English for the code suggestion.
- Title: imperative mood, max 72 chars, describe the improvement
- Description: explain the problem being addressed, the proposed solution, and any trade-offs in 2-3 sentences

使用中文生成 PR 标题和描述。
标题格式：<type>(<scope>): <中文摘要>，与 Conventional Commits 保持一致。
描述包含：
1. ✅ 变更概述（这个 PR 做了什么）
2. 📌 变更动机（为什么要这样做）
3. 📝 关键变更列表（用无序列表列出主要修改点）
4. 🧪 测试说明（如何验证此变更）

# Git Commit Message 生成规范
​
## 语言
使用中文生成 commit 消息。
​
## 格式
严格遵循 Conventional Commits 规范：
<type>(<scope>): <中文描述>
​
### type 枚举
- `feat`：新功能
- `fix`：修复 Bug
- `docs`：文档变更
- `refactor`：重构（无功能变化）
- `test`：测试相关
- `chore`：构建/依赖/配置
- `perf`：性能优化
- `ci`：CI/CD 变更
- `style`：代码格式调整
- `build`：构建系统变更
​
### scope
使用模块名或文件名，如 `auth`、`gateway`、`pom`、`refinex-ai`。
​
### 描述规则
- 中文动词开头，如「新增」「修复」「移除」「重构」
- 不加句号
- 单行不超过 72 字符
- 如果需要 body，空一行后用中文简述变更动机和影响
​
## 示例
​
feat(refinex-ai): 新增 DeepSeek 模型接入支持
fix(gateway): 修复路由配置未生效导致 404 的问题
refactor(auth): 抽取 Token 校验逻辑到独立工具类
chore(pom): 升级 Spring Boot 到 3.5.2

# 项目级（仅当前仓库有效）
.github/skills/
└── spring-security-audit/
    ├── SKILL.md          ← 必须，文件名大小写敏感
    └── scripts/
        └── check-auth-bypass.sh
​
# 项目级（.claude 约定，等价）
.claude/skills/
└── spring-security-audit/
    └── SKILL.md
​
# 项目级（.agents 约定，等价）
.agents/skills/
└── spring-security-audit/
    └── SKILL.md
​
# 个人级（跨所有项目有效）
~/.copilot/skills/
└── spring-security-audit/
    └── SKILL.md
​
# 个人级（.claude 约定，等价）
~/.claude/skills/
└── spring-security-audit/
    └── SKILL.md
​
# 个人级（.agents 约定，等价）
~/.agents/skills/
└── spring-security-audit/
    └── SKILL.md

---
name: spring-security-audit
description: >
  Spring Security 安全审计指南。当被要求进行安全审查、检查认证绕过风险、
  审计 Sa-Token 配置，或用户使用关键词 seccheck 时使用此 Skill。
license: MIT
---
​
## 审计流程
​
1. 检查所有 @RequestMapping 端点是否在 SecurityConfig 的 `permitAll()` 列表之外
2. 验证 Sa-Token 的 `isLogin()` 检查是否存在于所有需要认证的 Controller 路径
3. 扫描是否存在 `@SaIgnore` 注解，逐一确认豁免理由
4. 运行 `./scripts/check-auth-bypass.sh`，输出潜在风险点
​
## 风险等级定义
- HIGH：未认证可直接访问涉及用户数据的接口
- MEDIUM：存在 JWT 伪造风险（未验证 alg 字段）
- LOW：调试端点未在生产环境禁用

/skills list                            # 列出当前所有已加载的 skills 及其来源
/skills                                 # 交互式开关面板（↑↓ 键选择，空格键切换启用/禁用）
/skills info                            # 查看 skill 详情，包括文件路径和来源 plugin
/skills add                             # 添加自定义 skills 目录（持久化到配置）
/skills reload                          # 热加载：session 内新增 skill 后无需重启 CLI
/skills remove spring-security-audit    # 移除直接添加的 skill（SPEC 是子目录名）
                                        # 注意：Plugin 安装的 skill 需通过 plugin 管理

# Copilot 自动识别这是安全审计任务，加载 spring-security-audit skill
Audit the authentication logic in refinex-auth module for potential bypass risks

# 强制使用指定 skill（/ 后接 name 字段值）
Use the /spring-security-audit skill to audit all controllers in refinex-auth module
​
# 在 CLI 内键入 / 可以看到所有可用 skill 的补全列表

.github/skills/
└── actions-failure-debugging/
    └── SKILL.md

---
name: github-actions-failure-debugging
description: >
  Guide for debugging failing GitHub Actions workflows.
  Use this when asked to debug failing GitHub Actions workflows,
  investigate CI failures, or troubleshoot workflow runs.
---
​
To debug failing GitHub Actions workflows in a pull request,
follow this process using tools from the GitHub MCP Server:
​
1. Use `list_workflow_runs` to look up recent workflow runs and their status
2. Use `summarize_job_log_failures` to get an AI summary of failed job logs
   — avoids filling context window with thousands of log lines
3. If more detail is needed, use `get_job_logs` or `get_workflow_run_logs`
4. Try to reproduce the failure in your own environment
5. Fix the failing build. If you reproduced it yourself, verify the fix
   before committing

# 方式一：克隆 Anthropic 官方仓库，将 skills 目录复制到个人级目录
git clone https://github.com/anthropics/skills.git /tmp/anthropic-skills
cp -r /tmp/anthropic-skills/skills/* ~/.agents/skills/
​
# 方式二：克隆 OpenAI 官方仓库
git clone https://github.com/openai/skills.git /tmp/openai-skills
cp -r /tmp/openai-skills/skills/* ~/.agents/skills/
​
# 验证安装（在 CLI 内）
/skills list

# 安装 skill-creator（以 Anthropic 版为例）
cp -r /tmp/anthropic-skills/skills/skill-creator ~/.agents/skills/
​
# 然后在 CLI 中直接描述你的需求，skill-creator 会自动触发
Create a skill for auditing Spring Security + Sa-Token authentication bypass risks in Java projects

# 在 CLI 内
/mcp add
# 按 Tab 切换字段，Ctrl+S 保存

// ~/.copilot/mcp-config.json
{
  "mcpServers": {
    "context7": {
      "type": "http",
      "url": "https://mcp.context7.com/mcp",
      "headers": {
        "CONTEXT7_API_KEY": "YOUR-API-KEY"
      },
      "tools": ["*"]
    },
    "chrome-devtools": {
      "type": "stdio",
      "command": "npx",
      "args": ["chrome-devtools-mcp@latest"],
      "tools": ["*"]
    },
    "shadcn": {
      "type": "stdio",
      "command": "npx",
      "args": ["shadcn@latest", "mcp"],
      "tools": ["*"]
    },
    "playwright": {
      "type": "local",
      "command": "npx",
      "args": ["@playwright/mcp@latest", "--headless"],
      "tools": ["*"]
    }
  }
}

/mcp show                    # 列出所有已配置 MCP server 及状态
/mcp show context7           # 查看 playwright server 的工具列表
/mcp disable context7        # 临时禁用（配置保留）
/mcp enable context7         # 重新启用
/mcp delete context7         # 永久删除配置

# 示例1
Create a Next.js middleware that checks for a valid JWT in cookies
and redirects unauthenticated users to `/login`. use context7
​
# 示例2
Configure a Cloudflare Worker script to cache
JSON API responses for five minutes. use context7

Always use Context7 MCP when I need library/API documentation, code generation, setup or configuration steps without me having to explicitly ask.

{
  "mcpServers": {
    "context7": {
      "type": "http",
      "url": "https://mcp.context7.com/mcp",
      "headers": {
        "CONTEXT7_API_KEY": "YOUR_API_KEY"
      },
      "tools": ["query-docs", "resolve-library-id"]
    }
  }
}

// .github/hooks/hooks.json
{
  "version": 1,
  "hooks": {
    "sessionStart": [
      {
        "type": "command",
        "bash": "./scripts/session-start.sh",
        "powershell": "./scripts/session-start.ps1",
        "cwd": ".",
        "timeoutSec": 30,
        "comment": "记录 session 开始"
      }
    ],
    "preToolUse": [
      {
        "type": "command",
        "bash": "./scripts/security-check.sh",
        "comment": "安全检查 — 最先执行"
      },
      {
        "type": "command",
        "bash": "./scripts/audit-log.sh",
        "comment": "审计日志 — 第二执行"
      }
    ],
    "postToolUse": [
      {
        "type": "command",
        "bash": "./scripts/quality-check.sh",
        "timeoutSec": 30
      }
    ],
    "sessionEnd": [
      {
        "type": "command",
        "bash": "echo \"[$(date)] Session ended\" >> ~/.copilot/session-audit.log",
        "powershell": "Add-Content -Path \"$HOME\\.copilot\\session-audit.log\" -Value \"[$(Get-Date)] Session ended\"",
        "timeoutSec": 5
      }
    ]
  }
}

#!/bin/bash
# 所有字段通过 stdin 的 JSON 传入，jq 是必备依赖
INPUT=$(cat)
TOOL_NAME=$(echo "$INPUT" | jq -r '.toolName')
TOOL_ARGS=$(echo "$INPUT" | jq -r '.toolArgs')

$input = [Console]::In.ReadToEnd() | ConvertFrom-Json
$toolName = $input.toolName
$toolArgs = $input.toolArgs

# 使用 jq -n 构造 JSON，避免手写字符串引号问题
REASON="Production deployment requires manual approval"
jq -n --arg reason "$REASON" '{permissionDecision: "deny", permissionDecisionReason: $reason}'

@{ permissionDecision = "deny"; permissionDecisionReason = "Security policy violation" } | ConvertTo-Json -Compress

#!/bin/bash
# .github/hooks/scripts/security-check.sh
# preToolUse hook：拦截破坏性操作
INPUT=$(cat)
TOOL_NAME=$(echo "$INPUT" | jq -r '.toolName')
​
# 只检查 bash 工具，其他工具放行
[ "$TOOL_NAME" != "bash" ] && exit 0
​
COMMAND=$(echo "$INPUT" | jq -r '.toolArgs' | jq -r '.command // empty')
​
# 拦截已知危险命令模式
if echo "$COMMAND" | grep -qE 'rm -rf /|DROP TABLE|format [A-Z]:|sudo rm'; then
  jq -n '{permissionDecision: "deny", permissionDecisionReason: "Dangerous destructive command detected"}'
  exit 0
fi
​
# 拦截 git push（防止未经审批推送）
if echo "$COMMAND" | grep -qE '^git push'; then
  jq -n '{permissionDecision: "deny", permissionDecisionReason: "git push requires manual execution — run it yourself after reviewing changes"}'
  exit 0
fi

#!/bin/bash
# postToolUse hook：文件变更后运行 checkstyle
INPUT=$(cat)
TOOL_NAME=$(echo "$INPUT" | jq -r '.toolName')
​
# 只在文件编辑或创建后触发
[[ "$TOOL_NAME" != "edit" && "$TOOL_NAME" != "create" ]] && exit 0
​
# 运行检查，仅输出末尾 5 行避免日志污染
./mvnw checkstyle:check -q 2>&1 | tail -5

# postToolUse hook（Windows 版本）
$input = [Console]::In.ReadToEnd() | ConvertFrom-Json
if ($input.toolName -notmatch 'edit|create') { exit 0 }
./mvnw checkstyle:check -q 2>&1 | Select-Object -Last 5

// hooks.json — 全链路审计配置
{
  "version": 1,
  "hooks": {
    "sessionStart":        [{"type": "command", "bash": "./audit/log-session-start.sh"}],
    "userPromptSubmitted": [{"type": "command", "bash": "./audit/log-prompt.sh"}],
    "preToolUse":          [{"type": "command", "bash": "./audit/log-tool-use.sh"}],
    "postToolUse":         [{"type": "command", "bash": "./audit/log-tool-result.sh"}],
    "sessionEnd":          [{"type": "command", "bash": "./audit/log-session-end.sh"}]
  }
}

#!/bin/bash
# audit/log-tool-use.sh — JSON Lines 格式结构化日志
INPUT=$(cat)
jq -n \
  --arg ts   "$(echo "$INPUT" | jq -r '.timestamp')" \
  --arg tool "$(echo "$INPUT" | jq -r '.toolName')" \
  --arg user "${USER:-unknown}" \
  '{timestamp: $ts, user: $user, tool: $tool}' >> logs/audit.jsonl

#!/bin/bash
# userPromptSubmitted hook
INPUT=$(cat)
PROMPT=$(echo "$INPUT" | jq -r '.prompt')
​
# 如果 prompt 包含 production/prod/线上 等关键词，发送告警
if echo "$PROMPT" | grep -iqE 'production|prod|线上|生产'; then
  # 发送 Slack 告警（替换为你的 Webhook URL）
  curl -s -X POST "$SLACK_WEBHOOK_URL" \
    -H 'Content-Type: application/json' \
    -d "{\"text\":\"⚠️ Copilot CLI 正在处理生产相关操作：$PROMPT\"}"
fi

# 1. 手动测试 hook 脚本（模拟 CLI 传入的 JSON）
echo '{"toolName":"bash","toolArgs":"{\"command\":\"rm -rf /tmp\"}","timestamp":1704614600000,"cwd":"."}' \
  | bash .github/hooks/scripts/security-check.sh
​
# 2. 检查 hook 脚本是否有执行权限
ls -la .github/hooks/scripts/
chmod +x .github/hooks/scripts/*.sh
​
# 3. jq 未安装时的报错排查
which jq || (echo 'jq not found'; brew install jq)  # macOS
which jq || (echo 'jq not found'; sudo apt install jq)  # Linux
​
# 4. 验证 JSON 输出格式正确（single line）
echo '{"permissionDecision":"deny","permissionDecisionReason":"test"}' | jq -c .

# 从官方 marketplace 安装
copilot plugin install database-data-management@awesome-copilot
​
# 直接从 GitHub 仓库安装（根目录）
copilot plugin install owner/repo
​
# 安装仓库子目录中的插件（如 monorepo 中的某个插件）
copilot plugin install anthropics/claude-code:plugins/frontend-design
​
# 从本地路径安装（开发调试阶段）
copilot plugin install ./my-team-plugin
​
# 更新插件
copilot plugin update my-team-plugin
​
# 查看已安装插件
copilot plugin list

my-team-plugin/
├── plugin.json                    # 必须
├── agents/                        # 自定义 agents (选)
│   └── code-reviewer.agent.md    
├── skills/                        # Skills (选)
│   └── spring-migration/
│       └── SKILL.md
├── hooks.json                     # Hook 配置 (选)
└── .mcp.json                      # MCP 服务配置 (可选)

// plugin.json
{
  "name": "refinex-dev-tools",
  "description": "Refinex 项目 Copilot 能力包：包含代码审查 Agent、Spring 迁移 Skill 和 MCP 数据库配置",
  "version": "1.0.0",
  "author": {
    "name": "Refinex Team"
  },
  "license": "MIT",
  "agents": "agents/",
  "skills": ["skills/"],
  "hooks": "hooks.json",
  "mcpServers": ".mcp.json"
}

// .github/plugin/marketplace.json
{
  "name": "refinex-plugins",
  "owner": {
    "name": "Refinex Team",
    "email": "dev@refinex.com"
  },
  "metadata": {
    "description": "Refinex 工程团队专属 Copilot CLI 插件集",
    "version": "1.0.0"
  },
  "plugins": [
    {
      "name": "refinex-dev-tools",
      "description": "代码审查 Agent + Spring 迁移 Skill + MCP 数据库配置",
      "version": "1.0.0",
      "source": "./plugins/refinex-dev-tools"
    },
    {
      "name": "security-auditor",
      "description": "Sa-Token + Spring Security 安全审计能力包",
      "version": "1.0.0",
      "source": "./plugins/security-auditor"
    }
  ]
}

# 团队成员执行一次，注册整个 marketplace
copilot plugin marketplace add refinex-org/copilot-plugins
​
# 浏览可用插件
copilot plugin marketplace browse refinex-plugins
​
# 安装指定插件
copilot plugin install refinex-dev-tools@refinex-plugins
​
# 注销（会阻止继续安装，但已安装插件不受影响，除非加 --force）
copilot plugin marketplace remove refinex-plugins

Agent 加载顺序（first-wins）：
1. ~/.copilot/agents/              用户个人（.copilot 约定）
2. <project>/.github/agents/      项目级
3. <parents>/.github/agents/      继承（monorepo）
4. ~/.claude/agents/               用户个人（.claude 约定）
5. <project>/.claude/agents/      项目级（.claude 约定）
6. Plugin: agents/ 目录            按安装顺序
7. 远程组织/企业 agents            via API

Skill 加载顺序（first-wins）：
1. <project>/.github/skills/
2. <project>/.claude/skills/
3. <parents>/.github/skills/ 等   继承
4. ~/.copilot/skills/              用户个人
5. ~/.claude/skills/
6. Plugin: skills/ 目录            按安装顺序
7. COPILOT_SKILLS_DIRS env 指定的目录

MCP Server 加载顺序（last-wins）：
1. ~/.copilot/mcp-config.json      最低优先级
2. .vscode/mcp.json                workspace 级
3. Plugin: MCP 配置                按安装顺序
4. --additional-mcp-config flag    最高优先级

/agent
# 从列表中选择 "Create new agent"
# 选择让 Copilot 生成（Option 1）或手动填写（Option 2）

I am a security expert. I check code files thoroughly for potential security issues.
Use me whenever a security review/check/audit is requested for one or more code files,
or when the word "seccheck" is used in a prompt in reference to code files.

I will identify potential problems, such as code that:
- Exposes secrets or credentials
- Allows cross-site scripting or SQL injection
- Contains vulnerable dependencies
- Allows authentication to be bypassed

If any problems are identified, create a single GitHub issue with full details,
including risk level and recommended fix.

# 创建仓库级 agent
mkdir -p .github/agents
vim .github/agents/security-auditor.agent.md
​
# 或创建个人级 agent
mkdir -p ~/.copilot/agents
vim ~/.copilot/agents/security-auditor.agent.md

---
name: security-auditor
description: >
  Spring 安全审计专家。当被要求进行安全审查、检查 Sa-Token 配置、
  审计接口权限，或用户在 prompt 中使用关键词 seccheck 时使用。
tools: ["bash", "view"]
infer: true
---
​
你是一位专注于 Spring Security + Sa-Token 体系的安全审计专家。
​
## 审计范围
仅审计以下风险类别：
1. 未鉴权接口（@SaIgnore 滥用）
2. JWT/Token 伪造风险（alg 未验证、弱 secret）
3. SQL 注入（MyBatis-Plus 原生 SQL 拼接）
4. SSRF（内部服务调用未做 URL 白名单）
​
## 输出格式
以 JSON 数组输出，每个发现包含：
- file: 文件路径
- line: 行号
- severity: HIGH / MEDIUM / LOW
- description: 风险描述
- recommendation: 修复建议
​
## 约束
- 不修改任何代码文件（工具集限定为只读：bash + view）
- 不输出未经验证的猜测；不确定的发现标记 severity 为 LOW 并说明不确定原因

# --agent 后接文件名（去掉 .agent.md 后缀）
copilot --agent security-auditor --prompt "Audit all controllers in refinex-auth/src"
​
# 非交互模式（-s 只输出结果）
RESULT=$(copilot --agent security-auditor -sp "Check @src/app/validator.go for SQL injection")
echo "$RESULT" | jq .

# Copilot 根据 prompt 语义与 description 匹配，自动选择 agent
Check all TypeScript files in or under the src directory for potential security problems
​
# 触发关键词（在 description 中定义）
seccheck @refinex-auth/src/main/java/com/refinex/auth/controller/

# 直接告诉 Copilot 使用哪个 agent
Use the security-auditor agent on all files in the /src/app directory

# 在 CLI 内
/agent
# ↑↓ 键选择 agent，回车确认
# 然后输入要传给该 agent 的 prompt

.github/agents/
├── security-auditor.agent.md    # Sa-Token + Spring Security 安全审计
├── api-doc-writer.agent.md      # 从 Controller 自动生成 API 文档
└── test-generator.agent.md      # 为 Service 层生成单元测试

---
name: api-doc-writer
description: >
  API 文档生成专家。当被要求生成 API 文档、为 Controller 补充 Swagger 注解、
  或输出接口规范文档时使用。触发关键词：api-doc、generate docs、接口文档。
tools: ["bash", "view", "edit"]
---
​
你是一位专注于 Spring Boot REST API 文档的专家。
​
## 工作流程
​
1. 读取指定 Controller 文件（`view` 工具）
2. 分析所有 `@RequestMapping` / `@GetMapping` / `@PostMapping` 端点
3. 为每个端点补充 Springdoc/Swagger 注解：
   - `@Operation(summary = "...", description = "...")`
   - `@Parameter` 描述所有请求参数
   - `@ApiResponse` 描述成功和错误响应
4. 输出修改后的文件
​
## 约束
- 只修改 Controller 文件，不改动 Service 和 Mapper 层
- 注解描述使用中文，符合团队文档规范
- 不改变任何业务逻辑和方法签名

---
name: test-generator
description: >
  单元测试生成专家。当被要求为 Service 层方法生成单元测试、
  补充测试覆盖率不足的代码时使用。触发关键词：generate tests、写单测。
tools: ["bash", "view", "edit"]
---
​
你是一位专注于 Spring Boot + JUnit 5 + Mockito 单元测试的专家。
​
## 工作流程
​
1. 读取目标 Service 文件，分析所有 public 方法
2. 识别外部依赖（注入的 Mapper、其他 Service）
3. 为每个方法生成测试：
   - 正常路径（happy path）
   - 边界条件（空值、空列表、null 参数）
   - 异常路径（BizException 触发条件）
4. 测试文件放在对应的 `src/test/java` 路径下
​
## 技术约束
- 测试框架：JUnit 5 + Mockito
- 使用 `@ExtendWith(MockitoExtension.class)`，禁止 Spring 容器（太慢）
- WebFlux 方法的测试使用 `StepVerifier` 而非 `.block()`
- 每个测试方法名格式：`methodName_scenario_expectedResult`

refinex-gateway    → 新增路由规则
refinex-ai         → 实现接口
refinex-auth       → 确认鉴权配置
refinex-frontend   → 更新 API 调用

# 方式一：从父目录启动（推荐，一次授信所有子目录）
cd ~/projects/refinex
copilot
# refinex-gateway、refinex-ai、refinex-auth 等所有子目录自动可访问
​
# 方式二：运行时动态添加（跨磁盘路径、独立克隆的仓库）
/add-dir /Users/me/projects/refinex-frontend     # 必须绝对路径
/list-dirs                                       # 查看当前已授信目录列表

# 第一步：分析，不修改任何文件
我需要在 refinex-ai 中添加一个新的 Tool Call 接口（POST /api/ai/v2/tools/execute），
同时更新 refinex-gateway 的路由配置，
并在 @/Users/me/projects/refinex-frontend 中更新对应的 API 调用。
​
首先分析四个仓库中与 Tool Call 相关的现有代码结构，**不要修改任何文件**。
找到以下信息：
1. refinex-ai 中现有 Tool 相关的 Controller 和 Service
2. refinex-gateway 中路由规则的配置方式和文件位置
3. refinex-frontend 中 AI 接口的调用层结构
​
# 第二步：确认分析结果后，再进入 Plan Mode 执行
/plan 按照上述分析，实现 Tool Call 接口的跨仓库变更

~/projects/refinex/
├── refinex-gateway/
│   └── .github/copilot-instructions.md   # 路由规则约定、限流配置规范
├── refinex-ai/
│   └── .github/copilot-instructions.md   # WebFlux 约束、SSE 端点规范
├── refinex-auth/
│   └── .github/copilot-instructions.md   # Sa-Token 配置、鉴权约束
└── refinex-frontend/
    └── .github/copilot-instructions.md   # TypeScript 规范、API 调用层约定

# 在启动时预批准特定工具（避免重复审批）
copilot --allow-tool 'shell(git:*)' --deny-tool 'shell(git push)'
# 允许所有 git 子命令，但禁止 git push（防止 Copilot 未经确认推送代码）
​
# 允许文件写入但禁止 rm
copilot --allow-tool 'write' --deny-tool 'shell(rm)'
​
# 禁用所有工具审批（仅在完全信任场景下使用）
copilot --allow-all
# 等价于 --allow-all-tools --allow-all-paths --allow-all-urls
# 或在交互式会话中：/yolo

# 在不写任何代码的情况下，全面了解项目
Give me an overview of this project's architecture, focusing on:
1. Module dependencies and their responsibilities
2. How requests flow from the gateway to the AI service
3. Any non-obvious design decisions you can infer from the code
4. Areas that look like technical debt worth addressing

Do not modify any files.

/review Use Opus 4.5 and Codex 5.2 to review the changes in the current branch against main.
Focus on:
1. Potential NPE risks in the WebFlux chain
2. Missing error handling in Reactor operators
3. Thread-safety issues (especially ThreadLocal usage in WebFlux context)
Output issues as a structured list with severity and file:line reference.