星月
85e58ae239
- Move all Hermes skills from skills/ to hermes/ - Add cursor/ for Cursor rules (.mdc) - Add code-review.mdc (Gitea PR review with tea CLI) - Update sync.sh to use new hermes/ path - Update README with new structure
160 lines
4.9 KiB
Markdown
160 lines
4.9 KiB
Markdown
---
|
|
name: cursor-agent-cn
|
|
version: 1.1.0
|
|
description: >
|
|
Run Cursor Agent CLI for coding tasks in China region — writing, editing,
|
|
refactoring, reviewing, or planning code. Uses --model auto to work around
|
|
China-region model restrictions. Use when your machine is in mainland China
|
|
and you need Cursor Agent for coding tasks.
|
|
metadata:
|
|
requiredBinaries: ["cursor-agent"]
|
|
---
|
|
|
|
# Cursor Agent (China Region)
|
|
|
|
Cursor Agent CLI runs on the user's Cursor subscription — zero API cost.
|
|
**This is the China-region variant** that uses `--model auto` to work around
|
|
server-side model availability restrictions.
|
|
|
|
For non-China regions (where you can specify models directly), use the
|
|
`cursor-agent` skill instead.
|
|
|
|
## Prerequisites
|
|
|
|
**Required binary: `cursor-agent`** (or the alias `agent`)
|
|
|
|
Install: <https://cursor.com/docs/cli/overview> — verify with `cursor-agent --version`.
|
|
|
|
The helper script (`scripts/run.sh`) will exit with an error if neither `cursor-agent`
|
|
nor `agent` is found in PATH.
|
|
|
|
## Authentication
|
|
|
|
```bash
|
|
# Option 1: Environment variable
|
|
export CURSOR_API_KEY=crsr_xxxxxxxxxxxxxxxx
|
|
|
|
# Option 2: Browser login (interactive)
|
|
cursor-agent login
|
|
|
|
# Check status
|
|
cursor-agent status
|
|
```
|
|
|
|
## ⚠️ China Region: Model Availability
|
|
|
|
> **Tested & confirmed in WSL (China mainland, April 2026)**
|
|
|
|
Specifying a model like `--model claude-sonnet-4.6` or `--model gpt-5.4` will fail:
|
|
|
|
```
|
|
Model not available — This model provider doesn't serve your region
|
|
```
|
|
|
|
**Setting HTTP_PROXY / SOCKS5 does NOT help.** Cursor routes model selection on the
|
|
server side based on account region, not client IP.
|
|
|
|
### Solution: `--model auto`
|
|
|
|
Let Cursor pick whichever model is available in your region:
|
|
|
|
```bash
|
|
cursor-agent -p "your task" --model auto --trust
|
|
```
|
|
|
|
Or simply omit `--model` — the default is `auto`.
|
|
|
|
> **Trade-off:** `auto` may route to different models across runs, so output quality
|
|
> can vary. Use the two-step workflow below to review before applying changes.
|
|
|
|
## Recommended Workflow: Ask First, Write Second
|
|
|
|
Because `auto` mode picks an unpredictable model, always review before applying:
|
|
|
|
### Step 1 — Read-only review (`ask` mode)
|
|
|
|
```bash
|
|
cursor-agent -p "Review this code for bugs and suggest fixes" \
|
|
--model auto --mode=ask --output-format text --trust
|
|
```
|
|
|
|
Inspect the output. If the suggestions look good, proceed to step 2.
|
|
|
|
### Step 2 — Apply changes (`write` mode)
|
|
|
|
```bash
|
|
cursor-agent -p "Fix the bugs identified above" \
|
|
--model auto --force --output-format text --trust
|
|
```
|
|
|
|
## Headless Mode (Recommended for Automation)
|
|
|
|
Pipe mode (`-p`) is more stable than ACP/interactive mode:
|
|
|
|
```bash
|
|
cursor-agent -p "<task>" --model auto --mode=ask --output-format text --trust
|
|
```
|
|
|
|
- Runs non-interactively, returns text output
|
|
- Best for subagent integration and scripted pipelines
|
|
- Avoids the "Connection stalled" issues seen in ACP/interactive mode
|
|
|
|
## Command Quick Reference
|
|
|
|
| Scenario | Command |
|
|
|----------|---------|
|
|
| Code review | `cursor-agent -p "Review..." --model auto --mode=ask --trust` |
|
|
| Write code / fix bug | `cursor-agent -p "Fix..." --model auto --force --trust` |
|
|
| Planning / design | `cursor-agent -p "Plan..." --model auto --mode=plan --trust` |
|
|
| Check version | `cursor-agent --version` |
|
|
| Check auth status | `cursor-agent status` |
|
|
|
|
## Helper Script
|
|
|
|
Use `scripts/run.sh` for standardized invocation:
|
|
|
|
```bash
|
|
bash scripts/run.sh /path/to/repo "Review the auth module" auto ask
|
|
bash scripts/run.sh /path/to/repo "Fix the auth bug" auto write
|
|
TIMEOUT=300 bash scripts/run.sh /path/to/repo "Refactor utils" auto write
|
|
```
|
|
|
|
Arguments: `<repo_path> <task> [model] [mode]`
|
|
- `model`: `auto` (default) — always use `auto` in China region
|
|
- `mode`: `ask` (default, read-only) | `plan` | `write` (applies changes)
|
|
|
|
## Git Rule
|
|
|
|
Cursor's sandbox blocks `git commit`. After Cursor edits files, commit manually:
|
|
|
|
```bash
|
|
git add -A && git commit -m "feat: description of changes"
|
|
```
|
|
|
|
Always review the diff before committing.
|
|
|
|
## Known Issues
|
|
|
|
| Issue | Details |
|
|
|-------|---------|
|
|
| Region-locked models | Server-side restriction; proxies don't help. Use `--model auto`. |
|
|
| Connection stalled | ACP/interactive mode may hang. Use headless `-p` mode instead. |
|
|
| Inconsistent output | `auto` may route to different models each run. Review before applying. |
|
|
| Sandbox git block | Cursor sandbox prevents `git commit`. Commit manually after edits. |
|
|
|
|
## Gitea Integration
|
|
|
|
Cursor Agent can access git.shazhou.work via the `tea` CLI (pre-configured login: xingyue).
|
|
Global rules at `~/.cursor/rules/gitea-access.mdc` teach it how to use `tea`.
|
|
|
|
When assigning issue-related tasks, tell cursor to read the issue first:
|
|
```
|
|
"Read issue #3 with `tea issues 3`, then implement the changes described."
|
|
```
|
|
|
|
## Context Tips
|
|
|
|
- Add `@<file>` in your prompt to include specific files in context
|
|
- Use `--continue` or `--resume` to continue a previous session
|
|
- `~/.cursor/rules/` contains global rules loaded for all projects (e.g. gitea-access)
|