@qoder-ai/qodercli 0.2.7 → 0.2.8

package/README.md

@@ -1,6 +1,7 @@
 # Qoder CLI
 
-Qoder CLI 是Qoder品牌下的 CLI AI 编程助手，将强大的 AI 编程能力直接带入你的终端。
+Qoder CLI 是Qoder品牌下的 CLI
+AI 编程助手，将强大的 AI 编程能力直接带入你的终端。
 
 ## 🚀 Why Qoder CLI?
 
@@ -101,11 +102,10 @@ qodercli
 
 ## 🔐 认证配置
 
-Qoder CLI 使用自有认证体系（已移除所有 Gemini 原生认证），支持以下认证方式：
+Qoder CLI 使用自有认证体系，支持以下认证方式：
 
 ### 方式一：浏览器登录（推荐）
 
-
 ```sh
 qodercli
 # 首次运行自动打开浏览器引导登录
@@ -117,9 +117,10 @@ qodercli
 qodercli login
 ```
 
-后台每 30 分钟自动刷新 token（通过 `/api/v1/deviceToken/refresh`），无需手动干预
+后台每 30 分钟自动刷新 token，无需手动干预
 
-> 如果环境不支持自动打开浏览器，设置 `NO_BROWSER=1` 后 CLI 会打印 URL 供手动访问。
+> 如果环境不支持自动打开浏览器，设置 `NO_BROWSER=1`
+> 后 CLI 会打印 URL 供手动访问。
 
 ### 方式二：Personal Access Token (PAT)
 
@@ -132,23 +133,21 @@ qodercli
 
 PAT 可在 Qoder 账号设置页 (`https://qoder.com/account/integrations`) 创建和管理。
 
-
 ### 认证相关环境变量
 
-| 环境变量 | 说明 |
-|---------|------|
+| 环境变量                      | 说明                              |
+| ----------------------------- | --------------------------------- |
 | `QODER_PERSONAL_ACCESS_TOKEN` | PAT 令牌，设置后自动使用 PAT 认证 |
-| `QODER_CONFIG_DIR` | 自定义配置目录（默认 `~/.qoder`） |
-| `NO_BROWSER` | 设置后禁止自动打开浏览器 |
-
+| `QODER_CONFIG_DIR`            | 自定义配置目录（默认 `~/.qoder`） |
+| `NO_BROWSER`                  | 设置后禁止自动打开浏览器          |
 
 ### 会话内命令
 
-| 命令 | 说明 |
-|------|------|
-| `/login` 或 `/signin` | 在会话中执行登录 |
+| 命令                    | 说明               |
+| ----------------------- | ------------------ |
+| `/login` 或 `/signin`   | 在会话中执行登录   |
 | `/logout` 或 `/signout` | 退出登录（需确认） |
 
 ## 🔌 MCP 扩展
 
-在配置文件中添加 MCP 服务器，扩展 CLI 的能力
+在配置文件中添加 MCP 服务器，扩展 CLI 的能力

package/bundle/builtin/agent-creator/SKILL.md

@@ -0,0 +1,327 @@
+---
+name: agent-creator
+description:
+  Guide for creating custom agents. Use when users want to create a new agent
+  that runs in an isolated context with custom system prompts and
+  specific tool access.
+allowed-tools: Edit, Write
+---
+
+# Creating Custom Agents for Qoder CLI
+
+This skill guides you through creating custom agents. Agents are
+specialized AI assistants that run in isolated contexts with custom system
+prompts, specific tool access, and independent permissions.
+
+## When to Use Agents
+
+Use agents when you need:
+
+- **Context isolation** for long research or exploration tasks
+- **Parallel execution** of multiple independent workstreams
+- **Specialized expertise** with custom prompts for specific domains
+- **Reusable configurations** across projects
+
+**When NOT to use agents:**
+
+- Simple, single-purpose tasks (use skills instead)
+- Tasks requiring frequent back-and-forth with the user
+- Quick, targeted changes
+
+## Agent Locations
+
+| Location                         | Scope             | Priority |
+| -------------------------------- | ----------------- | -------- |
+| `<project>/${QODER_CONFIG_DIR}/agents/` | Current project   | Higher   |
+| `~/${QODER_CONFIG_DIR}/agents/`         | All your projects | Lower    |
+
+**Project agents** (`${QODER_CONFIG_DIR}/agents/`): Ideal for codebase-specific
+agents. Check into version control to share with your team.
+
+**User agents** (`~/${QODER_CONFIG_DIR}/agents/`): Personal agents available across
+all your projects.
+
+## Agent File Format
+
+Each agent is a Markdown file with YAML frontmatter:
+
+```markdown
+---
+name: agent-name
+description: When to use this agent. Be specific!
+---
+
+You are a [role]. When invoked:
+
+1. [First step]
+2. [Second step]
+3. [Output format]
+```
+
+### Required Fields
+
+| Field         | Description                                                                |
+| ------------- | -------------------------------------------------------------------------- |
+| `name`        | Unique identifier (lowercase letters and hyphens only)                     |
+| `description` | When to delegate to this agent (be specific). Including trigger scenarios. |
+
+## Writing Effective Descriptions
+
+The description is **critical**. Include "use proactively" to encourage
+automatic delegation - Qoder CLI uses it to decide when to delegate.
+
+```yaml
+# Bad - Too vague
+description: Helps with code
+
+# Good - Specific and actionable
+description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code.
+```
+
+### Optional Fields
+
+| Field            | Description                                                                         |
+| ---------------- | ----------------------------------------------------------------------------------- |
+| `tools`          | Tools the agent can use (string or array)                                           |
+| `disallowedTools`| Tools to explicitly deny (string or array)                                          |
+| `model`          | Model to use: `inherit` (default), `sonnet`, `opus`, `haiku`                        |
+| `color`          | Display color: `red`, `blue`, `green`, `yellow`, `purple`, `orange`, `pink`, `cyan` |
+| `displayName`    | Human-friendly display name                                                         |
+| `maxTurns`       | Maximum conversation turns (positive integer)                                       |
+| `timeoutMins`    | Timeout in minutes (positive integer)                                               |
+| `effort`         | Thinking effort: `low`, `medium`, `high`, `max`                                     |
+| `skills`         | Skills the agent can use (string or array)                                          |
+
+#### Tools
+
+Specify which tools the agent has access to. This limits the agent's
+capabilities for security and focus.
+
+```yaml
+# Read-only access
+tools: Read, Grep, Glob
+
+# Full development access
+tools: Bash, Read, Write, Edit, Glob, Grep
+
+# Web research capabilities
+tools: Read, WebSearch, WebFetch
+```
+
+**Available Tools:**
+
+- `Bash` - Execute shell commands
+- `Read` - Read file contents
+- `Write` - Create new files
+- `Edit` - Modify existing files
+- `Glob` - Find files by pattern
+- `Grep` - Search file contents
+- `WebSearch` - Search the web
+- `WebFetch` - Fetch web page content
+
+If not specified, the agent inherits default tool access.
+
+## Agent Creation Workflow
+
+### Step 1: Decide the Scope
+
+If not sure where to create the agent, ask the user with two options:
+
+- **Project-level** (`.agents/`): For team-shared, codebase-specific agents
+- **User-level** (`~/.agents/`): For personal agents across all projects
+
+### Step 2: Gather Requirements
+
+Understand what the agent should do:
+
+- What specific task or domain?
+- What tools does it need?
+- Should it be read-only or have write access?
+- Any special constraints or workflows?
+
+### Step 3: Create the File
+
+```bash
+# For project-level
+mkdir -p ${QODER_CONFIG_DIR}/agents
+touch ${QODER_CONFIG_DIR}/agents/agent-name.md
+
+# For user-level
+mkdir -p ~/${QODER_CONFIG_DIR}/agents
+touch ~/${QODER_CONFIG_DIR}/agents/agent-name.md
+```
+
+### Step 4: Write Configuration
+
+Create the markdown file with:
+
+1. YAML frontmatter with required fields
+2. System prompt in the body
+
+### Step 5: Verify
+
+- Check file location is correct
+- Verify YAML syntax is valid
+- Confirm the description clearly describes when to use it
+- Tell the user: run `/agents reload` to make the new agent available in the
+  current session. They can then invoke it with:
+
+```
+@agent-name [task description]
+```
+
+## Best Practices
+
+1. **Design focused agents** - Each should excel at one specific task
+2. **Write detailed descriptions** - Be detailed and specific so Qoder CLI knows
+   when to delegate
+3. **Limit tool access** - Grant only necessary permissions for security and
+   focus
+4. **Keep prompts concise** - Long, rambling prompts dilute focus
+
+## Anti-Patterns to Avoid
+
+- **Vague descriptions** - "Use for general tasks" gives no signal
+- **Overly long prompts** - A 2000-word prompt doesn't make it smarter
+
+## Examples
+
+### Verifier
+
+```markdown
+---
+name: verifier
+description:
+  Validates completed work. Use after tasks are marked done to confirm
+  implementations are functional.
+color: yellow
+---
+
+You are a skeptical validator. Your job is to verify that work claimed as
+complete actually works.
+
+When invoked:
+
+1. Identify what was claimed to be completed
+2. Check that the implementation exists and is functional
+3. Run relevant tests or verification steps
+4. Look for edge cases that may have been missed
+
+Be thorough and skeptical. Report:
+
+- What was verified and passed
+- What was claimed but incomplete or broken
+- Specific issues that need to be addressed
+
+Do not accept claims at face value. Test everything.
+```
+
+### Debugger
+
+```markdown
+---
+name: debugger
+description:
+  Debugging specialist for errors and test failures. Use when encountering
+  issues.
+color: red
+---
+
+You are an expert debugger specializing in root cause analysis.
+
+When invoked:
+
+1. Capture error message and stack trace
+2. Identify reproduction steps
+3. Isolate the failure location
+4. Implement minimal fix
+5. Verify solution works
+
+For each issue, provide:
+
+- Root cause explanation
+- Evidence supporting the diagnosis
+- Specific code fix
+- Testing approach
+
+Focus on fixing the underlying issue, not symptoms.
+```
+
+### Data Scientist
+
+```markdown
+---
+name: data-scientist
+description:
+  Data analysis expert for SQL queries, BigQuery operations, and data insights.
+  Use proactively for data analysis tasks and queries.
+tools: Bash, Read, Write
+---
+
+You are a data scientist specializing in SQL and BigQuery analysis.
+
+When invoked:
+
+1. Understand the data analysis requirement
+2. Write efficient SQL queries
+3. Use BigQuery command line tools (bq) when appropriate
+4. Analyze and summarize results
+5. Present findings clearly
+
+Key practices:
+
+- Write optimized SQL queries with proper filters
+- Use appropriate aggregations and joins
+- Include comments explaining complex logic
+- Format results for readability
+- Provide data-driven recommendations
+
+For each analysis:
+
+- Explain the query approach
+- Document any assumptions
+- Highlight key findings
+- Suggest next steps based on data
+
+Always ensure queries are efficient and cost-effective.
+```
+
+### Security Auditor
+
+```markdown
+---
+name: security-auditor
+description:
+  Security specialist. Use when implementing auth, payments, or handling
+  sensitive data. Proactively audit security-sensitive code.
+tools: Read, Grep, Glob
+color: red
+model: sonnet
+---
+
+You are a security expert auditing code for vulnerabilities.
+
+When invoked:
+
+1. Identify security-sensitive code paths
+2. Check for common vulnerabilities (injection, XSS, auth bypass)
+3. Verify secrets are not hardcoded
+4. Review input validation and sanitization
+
+Report findings by severity:
+
+- Critical (must fix before deploy)
+- High (fix soon)
+- Medium (address when possible)
+
+Security checklist:
+
+- SQL injection prevention
+- XSS protection
+- CSRF tokens
+- Authentication bypass risks
+- Authorization checks
+- Secret management
+- Input validation
+- Output encoding
+```