ai/opencode
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 更新命令文档和发布脚本

Browse Source 
- 更新 release-android.md: 明确前置条件和通用项目支持
- 更新 auto-commit.md: 添加中英文 commit 信息平台选择规则
- 更新 commit-push.md: 添加中英文 commit 信息平台选择规则
- 更新 sync-oc-push.md: 添加中英文 commit 信息平台选择规则
- 更新 release-android.mjs: 支持从 tags 自动推断项目名，不再硬编码 android 前缀
- 更新 AGENTS.md: 补充中文交流规则的注意事项
This commit is contained in:
voson
2026-01-09 16:54:56 +08:00
parent 0e161b3088
commit dce31f9729
6 changed files with 292 additions and 115 deletions
Download Patch File Download Diff File Expand all files Collapse all files

46
command/auto-commit.md
View File

@@ -130,9 +130,13 @@ Based on changes in staging area, **analyze and generate meaningful commit messa
- Use [Conventional Commits](https://www.conventionalcommits.org/) specification
- Commit message should concisely but accurately describe "why" rather than just "what"
- Common types: `feat` (new feature), `fix` (fix), `docs` (documentation), `refactor` (refactoring), `chore` (miscellaneous), `test` (test), etc.
- **Language selection**:
- **Default (macOS/Linux)**: Use Chinese (中文) for commit messages
- **Windows**: Use English due to encoding issues with Cursor Shell tool
- **If monorepo and this commit only affects single subproject, include subproject name in commit message**:
- Format: `<type>(<scope>): <description>`, where `<scope>` is subproject name
- Example: `feat(ios): support OGG Opus upload` or `fix(electron): fix clipboard injection failure`
- Example (Chinese): `feat(ios): 支持 OGG Opus 上传` or `fix(electron): 修复剪贴板注入失败`
- Example (English): `feat(ios): support OGG Opus upload` or `fix(electron): fix clipboard injection failure`
- If affecting multiple subprojects or entire repository, no need to add scope
### 6. Update Project Version Number
@@ -149,11 +153,27 @@ Based on changes in staging area, **analyze and generate meaningful commit messa
Execute commit with generated commit message (staging area now includes user's changes and version number update).
**Windows encoding issue solution:**
**Commit message language by platform:**
Cursor's Shell tool has encoding issues when passing Chinese parameters on Windows, causing garbled Git commit messages.
**macOS/Linux** (use Chinese commit messages):
**Correct approach**: Use **English** commit message
```bash
# Single line commit
git commit -m "feat(android): 添加新功能"
# Multi-line commit (recommended)
git commit -m "$(cat <<'EOF'
feat(android): 添加新功能
- 详细说明 1
- 详细说明 2
EOF
)"
```
**Windows** (use English commit messages):
Due to Cursor's Shell tool encoding issues on Windows, **must use English** commit messages.
```powershell
# Single line commit
@@ -163,26 +183,12 @@ git commit -m "feat(android): add new feature"
git commit --message="fix(android): fix code review issues" --message="- Fix syntax error" --message="- Use JSONObject instead of manual JSON"
```
**Prohibited methods** (will cause garbled text):
**Windows prohibited methods** (will cause garbled text):
- No Chinese commit messages - Cursor Shell tool encoding error when passing Chinese parameters
- No `Out-File -Encoding utf8` - writes UTF-8 with BOM
- No Write tool to write temp files - encoding uncontrollable
- No PowerShell here-string `@"..."@` - newline parsing issues
**For Chinese commit messages**: Please manually execute `git commit` in terminal, or use Git GUI tools other than Cursor.
**macOS/Linux alternative** (supports Chinese):
```bash
git commit -m "$(cat <<'EOF'
feat(android): new feature description
- Detail 1
- Detail 2
EOF
)"
```
### 8. Create Tag
> **Executed by default**. Only skip this step when user explicitly inputs "skip" or "skip tag".
@@ -228,7 +234,7 @@ Examples (multi-line commit, more recommended):
- **Create tag by default**: Unless user inputs "skip" or "skip tag", create tag by default.
- **Update version before commit**: First determine version number and modify version file, then commit at once, avoid using `--amend`.
- **Version file must be verified**: After updating version number and `git add`, must run `git diff --cached --name-only` to confirm version file is in staging area before executing commit.
- **Windows encoding issues**: Cursor Shell tool garbles Chinese parameters, must use **English** commit messages. For Chinese, please manually execute in terminal.
- **Commit message language**: Default use Chinese (macOS/Linux); Windows must use English due to Cursor Shell tool encoding issues.
- **monorepo scope**: If staging area only affects single subproject, commit message should have scope; if affecting multiple subprojects, no scope needed.
- **monorepo tag format**: Use `<subproject>-<version>` format (e.g., `ios-0.1.0`, `android-1.1.0`).
- **No version file case**: If project type cannot be identified or no version file (like pure Go project), only create git tag, don't update any files.

46
command/commit-push.md
View File

@@ -130,9 +130,13 @@ Based on changes in staging area, **analyze and generate meaningful commit messa
- Use [Conventional Commits](https://www.conventionalcommits.org/) specification
- Commit message should concisely but accurately describe "why" rather than just "what"
- Common types: `feat` (new feature), `fix` (fix), `docs` (documentation), `refactor` (refactoring), `chore` (miscellaneous), `test` (test), etc.
- **Language selection**:
- **Default (macOS/Linux)**: Use Chinese (中文) for commit messages
- **Windows**: Use English due to encoding issues with Cursor Shell tool
- **If monorepo and this commit only affects single subproject, include subproject name in commit message**:
- Format: `<type>(<scope>): <description>`, where `<scope>` is subproject name
- Example: `feat(ios): support OGG Opus upload` or `fix(electron): fix clipboard injection failure`
- Example (Chinese): `feat(ios): 支持 OGG Opus 上传` or `fix(electron): 修复剪贴板注入失败`
- Example (English): `feat(ios): support OGG Opus upload` or `fix(electron): fix clipboard injection failure`
- If affecting multiple subprojects or entire repository, no need to add scope
### 6. Update Project Version Number
@@ -149,11 +153,27 @@ Based on changes in staging area, **analyze and generate meaningful commit messa
Execute commit with generated commit message (staging area now includes user's changes and version number update).
**Windows encoding issue solution:**
**Commit message language by platform:**
Cursor's Shell tool has encoding issues when passing Chinese parameters on Windows, causing garbled Git commit messages.
**macOS/Linux** (use Chinese commit messages):
**Correct approach**: Use **English** commit message
```bash
# Single line commit
git commit -m "feat(android): 添加新功能"
# Multi-line commit (recommended)
git commit -m "$(cat <<'EOF'
feat(android): 添加新功能
- 详细说明 1
- 详细说明 2
EOF
)"
```
**Windows** (use English commit messages):
Due to Cursor's Shell tool encoding issues on Windows, **must use English** commit messages.
```powershell
# Single line commit
@@ -163,26 +183,12 @@ git commit -m "feat(android): add new feature"
git commit --message="fix(android): fix code review issues" --message="- Fix syntax error" --message="- Use JSONObject instead of manual JSON"
```
**Prohibited methods** (will cause garbled text):
**Windows prohibited methods** (will cause garbled text):
- No Chinese commit messages - Cursor Shell tool encoding error when passing Chinese parameters
- No `Out-File -Encoding utf8` - writes UTF-8 with BOM
- No Write tool to write temp files - encoding uncontrollable
- No PowerShell here-string `@"..."@` - newline parsing issues
**For Chinese commit messages**: Please manually execute `git commit` in terminal, or use Git GUI tools other than Cursor.
**macOS/Linux alternative** (supports Chinese):
```bash
git commit -m "$(cat <<'EOF'
feat(android): new feature description
- Detail 1
- Detail 2
EOF
)"
```
### 8. Create Tag
> **Executed by default**. Only skip this step when user explicitly inputs "skip" or "skip tag".
@@ -247,7 +253,7 @@ git push origin <subproject>-<version>
- **Create tag by default**: Unless user inputs "skip" or "skip tag", create and push tag by default.
- **Update version before commit**: First determine version number and modify version file, then commit at once, avoid using `--amend`.
- **Version file must be verified**: After updating version number and `git add`, must run `git diff --cached --name-only` to confirm version file is in staging area before executing commit.
- **Windows encoding issues**: Cursor Shell tool garbles Chinese parameters, must use **English** commit messages. For Chinese, please manually execute in terminal.
- **Commit message language**: Default use Chinese (macOS/Linux); Windows must use English due to Cursor Shell tool encoding issues.
- **monorepo scope**: If staging area only affects single subproject, commit message should have scope; if affecting multiple subprojects, no scope needed.
- **monorepo tag format**: Use `<subproject>-<version>` format (e.g., `ios-0.1.0`, `android-1.1.0`).
- **No version file case**: If project type cannot be identified or no version file (like pure Go project), only create git tag, don't update any files.

41
command/release-android.md
View File

@@ -1,14 +1,20 @@
---
description: Build and release Android APK to Gitea
description: Build and release Android APK to Gitea (generic for any Android project)
---
# Android Release Command
Build Android APK and upload to Gitea Release.
Build Android APK and upload to Gitea Release for the current directory's Android project.
## Prerequisites Check
## Prerequisites
First, verify the environment:
Before running this command:
1. **Create and push the git tag first** (e.g., `myapp-1.0.0`, `android-1.0.0`, or `v1.0.0`)
2. Ensure `GITEA_TOKEN` environment variable is set
3. Ensure Android project exists in current directory
Check the environment:
```bash
# Check GITEA_TOKEN
@@ -17,40 +23,25 @@ echo "GITEA_TOKEN: ${GITEA_TOKEN:+SET}"
# Check current directory for Android project
ls -la app/build.gradle.kts 2>/dev/null || ls -la android/app/build.gradle.kts 2>/dev/null || echo "No Android project found"
# Check current version
grep -h 'versionName' app/build.gradle.kts android/app/build.gradle.kts 2>/dev/null | head -1
# Check existing tags
git tag -l '*android*' -l 'v*' | tail -5
# Check recent tags (script will use the latest tag)
git tag -l | tail -10
```
## Release Process
**If there are uncommitted changes:**
1. Increment version: update `versionCode` (+1) and `versionName` in `app/build.gradle.kts`
2. Commit the changes with a descriptive message
3. Create annotated git tag:
- Monorepo: `git tag -a android-{version} -m "Release notes"`
- Standalone: `git tag -a v{version} -m "Release notes"`
4. Push commit and tag: `git push && git push origin {tag}`
**If no uncommitted changes but tag doesn't exist:**
1. Create tag and push it
## Build and Upload
After tag is created and pushed, run:
After creating and pushing the tag, run:
```bash
node ~/.config/opencode/bin/release-android.mjs
node ~/.opencode/bin/release-android.mjs
```
The script will:
- Auto-detect Android project root (standalone or monorepo)
- Auto-detect project name from recent git tags or directory name
- Auto-detect Gitea config from git remote URL (HTTPS/SSH)
- Auto-detect Java from Android Studio
- Build release APK
- Upload to Gitea Release
- Upload to Gitea Release matching the tag pattern
## Error Handling

15
command/sync-oc-push.md
View File

@@ -48,13 +48,24 @@ git add command/ skill/ opencode.json
Generate concise commit message based on change content:
- Use [Conventional Commits](https://www.conventionalcommits.org/) specification
- **Language selection**:
- **Default (macOS/Linux)**: Use Chinese (中文) for commit messages
- **Windows**: Use English due to encoding issues with Cursor Shell tool
- Common types:
- `feat`: New command or config
- `fix`: Fix command or config issues
- `docs`: Documentation update
- `chore`: Miscellaneous adjustments
**Examples**:
**Examples (macOS/Linux - Chinese)**:
```bash
git commit -m "feat: 添加 Vue.js 开发命令"
git commit -m "fix: 修正 MCP 服务器配置"
git commit -m "docs: 更新 review 命令说明"
```
**Examples (Windows - English)**:
```bash
git commit -m "feat: add new developer command for Vue.js"
@@ -72,4 +83,4 @@ git push origin main
- **Only sync config files**: Only add `command/`, `skill/` and `opencode.json`, don't commit other local data.
- **Sensitive info**: `opencode.json` may contain API keys, ensure remote repository access permissions are set correctly.
- **English commit**: To avoid encoding issues, suggest using English commit messages.
- **Commit message language**: Default use Chinese (macOS/Linux); Windows must use English due to Cursor Shell tool encoding issues.