diff --git a/src/os-skills/README.md b/src/os-skills/README.md index ee6fa8d..35f6ee5 100644 --- a/src/os-skills/README.md +++ b/src/os-skills/README.md @@ -45,6 +45,9 @@ A curated collection of operational skills for AI Agents, covering system admini ### Security - **alinux-cve-query** — Query Alibaba Cloud Linux CVE vulnerability info +### Other +- **cosh-guide** - Copilot Shell user guide + ## Skill Format Each skill lives in its own directory with at least a `SKILL.md` file: diff --git a/src/os-skills/others/cosh-guide/SKILL.md b/src/os-skills/others/cosh-guide/SKILL.md new file mode 100644 index 0000000..82ebbe8 --- /dev/null +++ b/src/os-skills/others/cosh-guide/SKILL.md @@ -0,0 +1,45 @@ +--- +name: cosh-guide +description: Copilot Shell (cosh) CLI 用户指南和帮助文档。用于回答关于 Copilot Shell 的使用、命令、配置、功能特性等问题。 + 当用户询问 Copilot Shell 的使用方法、命令参考、配置方式、功能说明时使用此 skill。 +--- + +# Copilot Shell (COSH) 用户指南 + +你是 Copilot Shell (COSH) CLI 工具的用户帮助助手。当用户询问 Copilot Shell 的使用问题时,根据问题类型参考对应的文档来回答。 + +## 文档索引 + +根据用户问题的类别,参考以下对应的参考文档: + +### 命令参考 +- 斜杠命令 (`/`)、@文件引用、`!`shell 命令、自定义命令、快捷键 +- 参考: [commands.md](reference/commands.md) + +### 功能特性 +- 审批模式 (Plan/Default/Auto-Edit/YOLO) +- Headless 模式 (非交互式/脚本化) +- MCP (Model Context Protocol) 外部工具集成 +- Agent Skills (实验性扩展能力) +- Subagents (子代理/专业化AI助手) +- Checkpointing (检查点/状态恢复) +- LSP (语言服务器协议,代码智能) +- Token 缓存与成本优化 +- 国际化与语言设置 +- 参考: [features.md](reference/features.md) + +### 配置 +- settings.json 配置层级与选项 +- 认证 (OAuth / API Key) +- 主题设置与自定义 +- 可信文件夹 +- 命令行参数 +- 环境变量 +- 参考: [configuration.md](reference/configuration.md) + +## 回答规范 + +1. 根据用户问题判断属于哪个类别,读取对应的参考文档 +2. 用简洁清晰的语言回答,提供具体的命令或配置示例 +3. 如果问题涉及多个类别,综合多个参考文档的信息 +4. 对于不确定的信息,建议用户使用 `/help` 命令或查看官方文档 diff --git a/src/os-skills/others/cosh-guide/reference/commands.md b/src/os-skills/others/cosh-guide/reference/commands.md new file mode 100644 index 0000000..80deb70 --- /dev/null +++ b/src/os-skills/others/cosh-guide/reference/commands.md @@ -0,0 +1,191 @@ +# Commands Reference + +Qwen Code commands use three prefixes: + +| Prefix | Function | Example | +|---|---|---| +| `/` (Slash) | Meta-level control of Qwen Code | `/help`, `/settings` | +| `@` (At) | Inject local file content into conversation | `@src/main.py explain this` | +| `!` (Exclamation) | Direct system shell interaction | `!git status`, `!ls` | + +--- + +## 1. Slash Commands (`/`) + +### 1.1 Session and Project Management + +| Command | Description | Usage | +|---|---|---| +| `/init` | Analyze directory and create initial context file | `/init` | +| `/summary` | Generate project summary from conversation | `/summary` | +| `/compress` | Replace chat history with summary to save tokens | `/compress` | +| `/resume` | Resume a previous conversation session | `/resume` | +| `/restore` | Restore files to state before tool execution | `/restore` or `/restore ` | + +### 1.2 Interface and Workspace Control + +| Command | Description | Usage | +|---|---|---| +| `/clear` | Clear terminal screen | `/clear` (Ctrl+L) | +| `/theme` | Change visual theme | `/theme` | +| `/vim` | Toggle Vim editing mode | `/vim` | +| `/directory` | Manage multi-directory workspace | `/dir add ./src,./tests` | +| `/editor` | Select supported editor | `/editor` | + +### 1.3 Language Settings + +| Command | Description | Usage | +|---|---|---| +| `/language` | View/change language settings | `/language` | +| `/language ui [lang]` | Set UI language | `/language ui zh-CN` | +| `/language output [lang]` | Set LLM output language | `/language output Chinese` | + +Built-in UI languages: `zh-CN`, `en-US`, `ru-RU`, `de-DE`, `ja-JP` +Aliases: `zh`, `en`, `ru`, `de`, `ja` + +### 1.4 Tool and Model Management + +| Command | Description | Usage | +|---|---|---| +| `/mcp` | List configured MCP servers/tools | `/mcp`, `/mcp desc` | +| `/tools` | Display available tool list | `/tools`, `/tools desc` | +| `/skills` | List/run available skills (experimental) | `/skills`, `/skills ` | +| `/approval-mode` | Change approval mode | `/approval-mode --project` | +| `/model` | Switch model in current session | `/model` | +| `/extensions` | List active extensions | `/extensions` | +| `/memory` | Manage AI instruction context | `/memory add Important Info` | + +Approval modes: `plan` (read-only), `default` (manual approval), `auto-edit` (auto-approve edits), `yolo` (auto-approve all) + +### 1.5 Information, Settings, and Help + +| Command | Description | Usage | +|---|---|---| +| `/help` | Display help | `/help` or `/?` | +| `/about` | Display version info | `/about` | +| `/stats` | Session statistics | `/stats` | +| `/settings` | Open settings editor | `/settings` | +| `/auth` | Change authentication | `/auth` | +| `/bug` | Submit issue | `/bug Button unresponsive` | +| `/copy` | Copy last output to clipboard | `/copy` | +| `/quit` | Exit Qwen Code | `/quit` or `/exit` | + +--- + +## 2. @ Commands (File References) + +| Format | Description | Example | +|---|---|---| +| `@` | Inject file content | `@src/main.py Please explain this` | +| `@` | Read all text files recursively | `@docs/ Summarize this` | +| `@server: resource` | Reference MCP resources | `@github: repos/owner/repo/issues` | + +Notes: +- Spaces in paths need backslash escaping: `@My\ Documents/file.txt` +- File paths can be relative or absolute +- `@` file references auto-load `QWEN.md` from the file's directory and parents +- Multiple files: `@file1.js and @file2.js` + +--- + +## 3. Exclamation Commands (`!`) - Shell + +| Format | Description | Example | +|---|---|---| +| `!` | Execute in sub-shell | `!ls -la`, `!git status` | +| Standalone `!` | Toggle shell mode (all input as commands) | `!` (enter) -> commands -> `!` (exit) | + +Environment: Commands via `!` set `QWEN_CODE=1`. + +--- + +## 4. Custom Commands + +Save frequently used prompts as shortcut commands. + +### Storage Locations + +| Type | Location | Priority | +|---|---|---| +| Global | `~/.qwen/commands/` | Low | +| Project | `/.qwen/commands/` | High (overrides global) | + +### Naming + +File path maps to command name: +- `~/.qwen/commands/test.md` -> `/test` +- `/.qwen/commands/git/commit.md` -> `/git:commit` + +### Markdown Format (Recommended) + +```markdown +--- +description: Optional description (shown in /help) +--- + +Your prompt content here. +Use {{args}} for parameter injection. +``` + +### Dynamic Content Injection + +| Type | Syntax | Purpose | +|---|---|---| +| File Content | `@{file path}` | Inject static reference files | +| Shell Commands | `!{command}` | Inject execution results (requires confirmation) | +| Parameters | `{{args}}` | Inject user parameters | + +### Example: Git Commit Command + +````markdown +--- +description: Generate Commit message based on staged changes +--- + +Please generate a Commit message based on the following diff: + +```diff +!{git diff --staged} +``` +```` + +--- + +## 5. Keyboard Shortcuts + +### General + +| Shortcut | Description | +|---|---| +| `Esc` | Close dialogs/suggestions | +| `Ctrl+C` | Cancel request / clear input (press twice to exit) | +| `Ctrl+D` | Exit if input empty (press twice to confirm) | +| `Ctrl+L` | Clear screen | +| `Ctrl+O` | Toggle debug console | +| `Ctrl+S` | Allow long responses to print fully | +| `Ctrl+T` | Toggle tool descriptions | +| `Shift+Tab` | Cycle approval modes | + +### Input Prompt + +| Shortcut | Description | +|---|---| +| `!` | Toggle shell mode (empty input) | +| `?` | Toggle shortcuts display (empty input) | +| `\` + Enter | Insert newline | +| `Tab` | Autocomplete suggestion | +| Up/Down Arrow | Navigate input history | +| `Ctrl+R` | Reverse search history | +| `Ctrl+V` | Paste clipboard (supports images) | +| `Ctrl+X` / `Meta+Enter` | Open in external editor | +| `Ctrl+A` / `Home` | Beginning of line | +| `Ctrl+E` / `End` | End of line | +| `Ctrl+K` | Delete to end of line | +| `Ctrl+U` | Delete to beginning of line | +| `Ctrl+W` | Delete word left | + +### IDE Integration + +| Shortcut | Description | +|---|---| +| `Ctrl+G` | See context from IDE | diff --git a/src/os-skills/others/cosh-guide/reference/configuration.md b/src/os-skills/others/cosh-guide/reference/configuration.md new file mode 100644 index 0000000..e72e06b --- /dev/null +++ b/src/os-skills/others/cosh-guide/reference/configuration.md @@ -0,0 +1,249 @@ +# Configuration Reference + +## Configuration Layers (Precedence) + +| Level | Source | Description | +|---|---|---| +| 1 | Default values | Hardcoded defaults | +| 2 | User settings | `~/.copilot/settings.json` | +| 3 | Project settings | `.copilot/settings.json` | + +--- + +## Authentication +### Switch Method + +``` +/auth +``` + +--- + +## Settings (settings.json) + +### Key Settings + +#### general + +| Setting | Type | Default | Description | +|---|---|---|---| +| `general.preferredEditor` | string | undefined | Preferred editor | +| `general.vimMode` | boolean | false | Enable Vim keybindings | +| `general.disableAutoUpdate` | boolean | false | Disable auto-updates | +| `general.gitCoAuthor` | boolean | true | Add Co-authored-by to commits | +| `general.checkpointing.enabled` | boolean | false | Enable checkpointing | + +#### model + +| Setting | Type | Default | Description | +|---|---|---|---| +| `model.name` | string | undefined | Model to use | +| `model.maxSessionTurns` | number | -1 | Max turns (-1 = unlimited) | +| `model.chatCompression.contextPercentageThreshold` | number | 0.7 | Compression threshold (0-1) | +| `model.generationConfig` | object | undefined | Advanced overrides (timeout, maxRetries, samplingParams, etc.) | + +#### ui + +| Setting | Type | Default | Description | +|---|---|---|---| +| `ui.theme` | string | undefined | Color theme | +| `ui.hideTips` | boolean | false | Hide tips | +| `ui.showLineNumbers` | boolean | true | Line numbers in code blocks | + +#### tools + +| Setting | Type | Default | Description | +|---|---|---|---| +| `tools.approvalMode` | string | "default" | Default approval mode | +| `tools.sandbox` | bool/string | undefined | Sandbox execution | +| `tools.core` | array | undefined | Allowlist of built-in tools | +| `tools.exclude` | array | undefined | Tools to exclude | +| `tools.allowed` | array | undefined | Tools bypassing confirmation | + +#### context + +| Setting | Type | Default | Description | +|---|---|---|---| +| `context.fileName` | string/array | undefined | Context file name(s) | +| `context.includeDirectories` | array | [] | Extra directories | +| `context.fileFiltering.respectGitIgnore` | boolean | true | Respect .gitignore | +| `context.fileFiltering.respectQwenIgnore` | boolean | true | Respect .qwenignore | + +#### privacy + +| Setting | Type | Default | Description | +|---|---|---|---| +| `privacy.usageStatisticsEnabled` | boolean | true | Usage statistics | + +### Example settings.json + +```json +{ + "general": { "vimMode": true, "preferredEditor": "code" }, + "ui": { "theme": "GitHub" }, + "tools": { "approvalMode": "auto-edit" }, + "model": { "name": "qwen3-coder-plus" }, + "context": { + "fileName": ["QWEN.md"], + "includeDirectories": ["path/to/dir1"] + } +} +``` + +--- + +## Themes + +### Built-in Themes + +- **Dark**: ANSI, Atom One, Ayu, Default, Dracula, GitHub +- **Light**: ANSI Light, Ayu Light, Default Light, GitHub Light, Google Code, Xcode + +### Change Theme + +``` +/theme +``` + +### Custom Themes + +In `settings.json`: + +```json +{ + "ui": { + "customThemes": { + "MyTheme": { + "name": "MyTheme", + "type": "custom", + "Background": "#181818", + "Foreground": "#F8F8F2", + "LightBlue": "#82AAFF", + "AccentBlue": "#61AFEF", + "AccentPurple": "#BD93F9", + "AccentCyan": "#8BE9FD", + "AccentGreen": "#50FA7B", + "AccentYellow": "#F1FA8C", + "AccentRed": "#FF5555", + "Comment": "#6272A4", + "Gray": "#ABB2BF" + } + } + } +} +``` + +Load from file: `"ui": { "theme": "/path/to/theme.json" }` + +--- + +## .qwenignore + +Exclude files from Qwen Code tools (similar to `.gitignore`). + +Create `.qwenignore` in project root: + +``` +# Exclude directories +/packages/ + +# Exclude specific files +apikeys.txt + +# Wildcards +*.md + +# Negate (include back) +!README.md +``` + +Restart session after changes. + +--- + +## Trusted Folders + +Security feature controlling which projects can use full Qwen Code capabilities. + +### Enable + +```json +{ "security": { "folderTrust": { "enabled": true } } } +``` + +### Trust Dialog Options + +- **Trust folder**: Full trust for current folder +- **Trust parent**: Trust parent directory and all subdirectories +- **Don't trust**: Restricted "safe mode" + +### Untrusted Restrictions + +1. Project `.qwen/settings.json` ignored +2. Project `.env` files ignored +3. Extension management restricted +4. Tool auto-acceptance disabled +5. Automatic memory loading disabled + +### Manage + +- `/permissions` command to change current folder trust +- View all rules: `~/.qwen/trustedFolders.json` + +--- + +## Context Files (QWEN.md) + +Hierarchical instructional context for the AI. + +### Loading Order + +1. `~/.qwen/QWEN.md` (global) +2. Project root and parent directories (project-specific) + +### Commands + +- `/memory refresh` - Reload all context files +- `/memory show` - Display current loaded context +- `/memory add ` - Add to memory + +### Import Syntax + +Use `@path/to/file.md` in context files to import other Markdown files. + +--- + +## Command-Line Arguments + +| Argument | Alias | Description | +|---|---|---| +| `--model` | `-m` | Specify model | +| `--prompt` | `-p` | Headless mode | +| `--output-format` | `-o` | Output format | +| `--sandbox` | `-s` | Enable sandbox | +| `--debug` | `-d` | Debug mode | +| `--all-files` | `-a` | Include all files | +| `--yolo` | | Auto-approve all | +| `--approval-mode` | | Set approval mode | +| `--continue` | | Resume recent session | +| `--resume` | | Resume specific session | +| `--include-directories` | | Add extra directories | +| `--experimental-skills` | | Enable skills | +| `--experimental-lsp` | | Enable LSP | +| `--extensions` | `-e` | Specify extensions | +| `--proxy` | | Set proxy | +| `--checkpointing` | | Enable checkpointing | + +--- + +## Environment Variables + +| Variable | Description | +|---|---| +| `OPENAI_API_KEY` | API key for OpenAI-compatible provider | +| `OPENAI_BASE_URL` | Custom API base URL | +| `OPENAI_MODEL` | Model to use | +| `QWEN_CODE_LANG` | Override UI language detection | +| `TAVILY_API_KEY` | Tavily web search API key | +| `NO_COLOR` | Disable color output | +| `DEBUG` / `DEBUG_MODE` | Enable debug logging | diff --git a/src/os-skills/others/cosh-guide/reference/features.md b/src/os-skills/others/cosh-guide/reference/features.md new file mode 100644 index 0000000..bee9dda --- /dev/null +++ b/src/os-skills/others/cosh-guide/reference/features.md @@ -0,0 +1,345 @@ +# Features Reference + +## Approval Mode + +Four permission modes controlling how AI interacts with your code: + +| Mode | File Editing | Shell Commands | Best For | Risk | +|---|---|---|---|---| +| **Plan** | Read-only | Not executed | Code exploration, planning | Lowest | +| **Default** | Manual approval | Manual approval | New codebases, critical systems | Low | +| **Auto-Edit** | Auto-approved | Manual approval | Daily development, refactoring | Medium | +| **YOLO** | Auto-approved | Auto-approved | Trusted projects, CI/CD | Highest | + +### Switching Modes + +- **During session**: `Shift+Tab` to cycle +- **Command**: `/approval-mode ` +- **With scope**: `/approval-mode yolo --project` or `--user` +- **Config**: `"permissions": { "defaultMode": "auto-edit" }` in `settings.json` + +### Plan Mode for Complex Refactors + +```bash +/approval-mode plan +``` +``` +I need to refactor our auth system to use OAuth2. Create a detailed migration plan. +``` + +--- + +## Headless Mode + +Run Qwen Code programmatically without interactive UI. + +### Basic Usage + +```bash +# Direct prompt +qwen --prompt "What is machine learning?" +qwen -p "query" + +# Stdin input +echo "Explain this code" | qwen + +# File input +cat README.md | qwen -p "Summarize this documentation" +``` + +### Output Formats + +| Format | Flag | Description | +|---|---|---| +| Text (default) | `--output-format text` | Human-readable | +| JSON | `--output-format json` | Structured, buffered | +| Stream-JSON | `--output-format stream-json` | Real-time streaming | + +### Resume Sessions + +```bash +qwen --continue -p "Run the tests again" +qwen --resume -p "Apply the refactor" +``` + +### Key Options + +| Option | Description | +|---|---| +| `--prompt`, `-p` | Run headless | +| `--output-format`, `-o` | Output format (text/json/stream-json) | +| `--yolo`, `-y` | Auto-approve all | +| `--approval-mode` | Set approval mode | +| `--all-files`, `-a` | Include all files in context | +| `--include-directories` | Include extra directories | +| `--continue` | Resume most recent session | +| `--resume [id]` | Resume specific session | + +--- + +## MCP (Model Context Protocol) + +Connect Qwen Code to external tools and data sources. + +### Quick Start + +```bash +# Add HTTP server +qwen mcp add --transport http my-server http://localhost:3000/mcp + +# Add stdio server +qwen mcp add pythonTools python -m my_mcp_server + +# List servers +qwen mcp list + +# Remove server +qwen mcp remove my-server +``` + +### Transport Types + +| Transport | When to Use | Config Field | +|---|---|---| +| `http` | Remote services (recommended) | `httpUrl` | +| `sse` | Legacy SSE servers | `url` | +| `stdio` | Local processes | `command`, `args` | + +### Configuration via settings.json + +```json +{ + "mcpServers": { + "myServer": { + "command": "python", + "args": ["-m", "my_mcp_server"], + "env": { "API_KEY": "$MY_API_KEY" }, + "timeout": 15000 + } + } +} +``` + +### Scopes + +- **Project** (default): `.copilot/settings.json` +- **User**: `~/.copilot/settings.json` (use `--scope user`) + +### Safety + +- `trust: true` bypasses confirmations (use sparingly) +- `includeTools` / `excludeTools` to filter tools per server +- Global allow/deny: `mcp.allowed` / `mcp.excluded` in settings + +--- + +## Agent Skills +Modular capabilities extending Cosh. + +### Create a Skill + +Skills are directories containing `SKILL.md`: + +- **Personal**: `~/.copilot/skills//SKILL.md` +- **Project**: `.copilot/skills//SKILL.md` + +```yaml +--- +name: your-skill-name +description: Brief description of what this Skill does and when to use it +--- + +# Your Skill Name + +## Instructions +Step-by-step guidance. + +## Examples +Concrete examples. +``` + +### Invoke + +Skills are auto-invoked by the model based on your request. Explicit invocation: + +```bash +/skills +``` + +### Supporting Files + +``` +my-skill/ + SKILL.md (required) + reference.md (optional) + scripts/helper.py (optional) + templates/template.txt (optional) +``` + +--- + +## Subagents + +Specialized AI assistants for specific task types. + +### Management + +``` +/agents create # Create new subagent +/agents manage # View/manage existing +``` + +### Storage + +- **Project**: `.copilot/agents/` (highest precedence) +- **User**: `~/.copilot/agents/` +- **Extension**: Provided by installed extensions + +### Configuration Format + +```markdown +--- +name: agent-name +description: Brief description +tools: + - read_file + - write_file + - run_shell_command +--- + +System prompt content goes here. +Use ${variable} templating for dynamic content. +``` + +### Invocation + +- **Automatic**: AI delegates based on task matching +- **Explicit**: "Let the testing-expert subagent create unit tests for the payment module" + +### Best Practices + +- Single responsibility per agent +- Specific expertise areas +- Clear, actionable descriptions +- Limit tool access to what's needed + +--- + +## Checkpointing + +Auto-saves project state before AI file modifications. + +### Enable + +```bash +qwen --checkpointing +``` + +Or in `settings.json`: +```json +{ "general": { "checkpointing": { "enabled": true } } } +``` + +### How It Works + +Before file modifications, creates: +1. Git snapshot in shadow repository (`~/.qwen/history/`) +2. Conversation history backup +3. Tool call record + +### Restore + +``` +/restore # List available checkpoints +/restore # Restore specific checkpoint +``` + +--- + +## LSP (Language Server Protocol) - Experimental + +Code intelligence features via language servers. + +### Enable + +```bash +qwen --experimental-lsp +``` + +### Supported Languages + +| Language | Server | Install | +|---|---|---| +| TypeScript/JS | typescript-language-server | `npm install -g typescript-language-server typescript` | +| Python | pylsp | `pip install python-lsp-server` | +| Go | gopls | `go install golang.org/x/tools/gopls@latest` | +| Rust | rust-analyzer | See official docs | + +### Configuration (.lsp.json) + +```json +{ + "typescript": { + "command": "typescript-language-server", + "args": ["--stdio"], + "extensionToLanguage": { + ".ts": "typescript", ".tsx": "typescriptreact", + ".js": "javascript", ".jsx": "javascriptreact" + } + } +} +``` + +### Available Operations + +- `goToDefinition`, `findReferences`, `goToImplementation` +- `hover`, `documentSymbol`, `workspaceSymbol` +- `prepareCallHierarchy`, `incomingCalls`, `outgoingCalls` +- `diagnostics`, `workspaceDiagnostics` +- `codeActions` (quickfix, refactor, source.organizeImports, etc.) + +--- + +## Token Caching + +Automatic API cost optimization for API key users. + +- Caches system instructions and conversation history +- Reduces tokens processed in subsequent requests +- Available for API key users (not OAuth) +- Check savings with `/stats` command + +--- + +## Language / i18n + +### UI Language + +```bash +/language ui zh-CN # Chinese +/language ui en-US # English +/language ui ja-JP # Japanese +``` + +Auto-detection priority: `QWEN_CODE_LANG` env -> `LANG` env -> System locale -> English + +### LLM Output Language + +```bash +/language output Chinese +/language output English +``` + +Stored at `~/.qwen/output-language.md`. Restart required after change. + +### Custom Language Packs + +Create files in `~/.qwen/locales/`: + +```javascript +// ~/.qwen/locales/es.js +export default { + Hello: 'Hola', + Settings: 'Configuracion', +}; +```