blocklet-pr（小块公关）

Blocklet PR

Help developers create standardized Pull Requests for blocklet projects, ensuring code quality and following project PR templates.

Core Philosophy

"Quality gates + standardized workflow."

PRs are not submitted casually. Before submission, code must pass lint and tests, must be on a working branch (never directly on main branch), and PR content must follow project templates. Enforced standardization reduces human oversight errors.

Prerequisites

• Current directory is a blocklet project (contains blocklet.yml)
• Has code changes to commit

Reference Files

Branch conventions and repository info are read from local reference files (in blocklet-url-analyzer skill directory):

• blocklet-url-analyzer/references/org-arcblock-repos.md - ArcBlock repos (core infrastructure, SDKs, mobile apps)
• blocklet-url-analyzer/references/org-blocklet-repos.md - Blocklet repos (blocklet applications, kits, tools)
• blocklet-url-analyzer/references/org-aigne-repos.md - AIGNE repos (AI agent framework, LLM adapters)

Active Loading Policy (ALP)

Load reference files on-demand based on repository organization. Do not preload all files.

Loading Strategy:

1. Determine repository organization from git remote get-url origin
2. Load only the reference file for that organization
3. If organization unknown, read README.md first for high-density summary

Workflow

Execute the following phases in order.

Phase 1: Workspace Check

Refer to blocklet-branch skill for branch operations. Skill location: blocklet-branch/SKILL.md

1.1 Confirm Remote Repository

Refer to blocklet-branch section 1.1:

REMOTE_URL=$(git remote get-url origin)
ORG=$(echo $REMOTE_URL | sed -E 's/.*[:/]([^/]+)\/([^/]+)(\.git)?$/\1/')
REPO=$(echo $REMOTE_URL | sed -E 's/.*[:/]([^/]+)\/([^/]+)(\.git)?$/\2/' | sed 's/\.git$//')

1.2 Detect Main Iteration Branch

Read from local reference files to get branch conventions for the repository (following ALP).

Load reference file based on repository organization (from 1.1):

• ArcBlock org → blocklet-url-analyzer/references/org-arcblock-repos.md
• blocklet org → blocklet-url-analyzer/references/org-blocklet-repos.md
• AIGNE-io org → blocklet-url-analyzer/references/org-aigne-repos.md
• Unknown → First read blocklet-url-analyzer/references/README.md

Default branch conventions (if no specific info found in references):

Output variables: MAIN_BRANCH, MAIN_BRANCH_REASON

1.3 Detect Branch Naming Conventions

Read from local reference files to get branch prefix conventions for the repository.

Default prefix conventions (if no specific info found in references):

Output variables: BRANCH_PREFIX_CONVENTION, BRANCH_SEPARATOR

1.4 Branch Check and Creation (Mandatory)

Refer to blocklet-branch sections 6, 7.

Important: Before submitting a PR, you must ensure you are on a working branch; cannot commit directly on the main iteration branch.

CURRENT_BRANCH=$(git branch --show-current)

if [ "$CURRENT_BRANCH" = "$MAIN_BRANCH" ]; then
    echo "⚠️ Currently on main iteration branch $MAIN_BRANCH, must create new branch!"
fi

If on main iteration branch, use AskUserQuestion:

⚠️ Currently on main iteration branch {MAIN_BRANCH}, cannot submit PR directly.

Please select new branch name (will be created based on {MAIN_BRANCH}):

Options:
A. {suggested branch name, generated based on change type and BRANCH_PREFIX_CONVENTION} (Recommended)
B. Enter custom branch name
C. Cancel operation

Create working branch (refer to blocklet-branch section 6.2):

git fetch origin $MAIN_BRANCH
git checkout $MAIN_BRANCH
git pull origin $MAIN_BRANCH
git checkout -b $NEW_BRANCH_NAME

1.5 Check Uncommitted Changes

git status --porcelain

Phase 2: Code Quality Checks

2.0 Ensure Dependencies Installed

Before running lint or tests, check if node_modules exists. If not, ask user whether to install dependencies.

Important: Detect and use the project's package manager (check lock files like pnpm-lock.yaml, yarn.lock, package-lock.json, etc.) for all dependency operations.

2.1 Lint Check

Run lint script from package.json (e.g., lint, lint:fix, check).

Handle missing dependency errors:

If lint fails with command not found or Cannot find module errors:

1. Extract the missing package name from error message
2. Check if it exists in project's devDependencies or dependencies
3. If NOT in project dependencies, ask user:

- Add the package to devDependencies (using project's package manager) - Skip lint check - Cancel

Never suggest global installation - missing packages should be added to the project.

2.2 Unit Tests

Run test script from package.json (e.g., test, test:unit, test:ci).

Handle missing dependency errors: Same as 2.1 - ask user to add missing package to project, never suggest global installation.

Regular test results:

Phase 3: Version Update

Important: If the project has a CHANGELOG.md file, version bump is required for every PR, not optional.

3.1 Check If Version Update Required

First check if CHANGELOG.md exists in project root:

test -f CHANGELOG.md && echo "CHANGELOG exists - version bump required"

3.2 Ask Version Update Type

Use AskUserQuestion to ask:

If CHANGELOG.md exists:

Project has CHANGELOG.md - version bump is required.

Please select version update type:
Options:
A. Patch version (x.x.X) (Recommended for bug fixes)
B. Minor version (x.X.0)
C. Major version (X.0.0)

If no CHANGELOG.md:

Do you need to update version and create release?

Options:
A. Yes, update patch version (x.x.X) (Recommended for bug fixes)
B. Yes, update minor version (x.X.0)
C. Yes, update major version (X.0.0)
D. No, skip version update

3.3 Execute Version Update

If user chooses to update version (or if required due to CHANGELOG.md), call blocklet-updater skill:

blocklet-updater skill location: blocklet-updater/SKILL.md

Phase 4: Git Commit

4.0 Check for Temporary Files (Pre-staging)

Before staging files, check for temporary database files in the root directory that should be ignored:

# Check for .db files in root directory only (not in subdirectories)
ROOT_DB_FILES=$(git status --porcelain | grep -E '^\?\? .*\.db$' | awk '{print $2}' | grep -v '/')

if [ -n "$ROOT_DB_FILES" ]; then
    echo "⚠️ Found temporary database files in root directory:"
    echo "$ROOT_DB_FILES"
fi

If root .db files found, use AskUserQuestion:

⚠️ Found temporary database files in root directory:

{list of files found}

These .db files are typically generated by tools and should not be committed.

Options:
A. Add *.db to .gitignore and continue (Recommended)
B. Continue anyway (these files will be committed)
C. Cancel, let me handle this manually

If Option A selected:

# Add .db pattern to .gitignore
echo "" >> .gitignore
echo "# Temporary database files" >> .gitignore
echo "*.db" >> .gitignore

git add .gitignore

If Option C selected: EXIT and let user handle manually.

Note: .aigne/ directories and files in subdirectories are NOT temporary files and should not be flagged.

4.1 Stage Changes

git add -A
git status

Display list of files to be committed, use AskUserQuestion to confirm:

The following files will be committed:
{file list}

Continue?
A. Yes, commit all changes (Recommended)
B. No, let me select files to commit
C. Cancel

4.2 Generate Commit Message

Generate standardized commit message based on change type:

Note: Refer to the last 20 commits for the specific prefix, follow historical conventions.

Analyze changes to automatically infer type, then use AskUserQuestion to confirm:

Suggested commit message:

{generated commit message}

Options:
A. Use this message (Recommended)
B. Modify message
C. Cancel

4.3 Execute Commit

git commit -m "$(cat <<'EOF'
{commit_message}

Co-Authored-By: Claude < [email protected] >
EOF
)"

Phase 5: Push Branch

5.1 Check Remote Branch

git ls-remote --heads origin $CURRENT_BRANCH

5.2 Push

git push -u origin $CURRENT_BRANCH

Phase 6: Create Pull Request

6.1 Check PR Template

# Find PR template
PR_TEMPLATE=""
if [ -f ".github/PULL_REQUEST_TEMPLATE.md" ]; then
    PR_TEMPLATE=".github/PULL_REQUEST_TEMPLATE.md"
elif [ -f ".github/pull_request_template.md" ]; then
    PR_TEMPLATE=".github/pull_request_template.md"
elif [ -f "docs/PULL_REQUEST_TEMPLATE.md" ]; then
    PR_TEMPLATE="docs/PULL_REQUEST_TEMPLATE.md"
fi

If template found: Read and parse template structure, fill PR content according to template format.

If template not found: Use default PR format.

6.2 Get Target Branch

Use the MAIN_BRANCH detected in Phase 1.2 (from reference files).

Use AskUserQuestion to confirm target branch:

PR target branch:

Options:
A. {MAIN_BRANCH} (Recommended)
B. Other branch

6.3 Link Issue (If Applicable)

Use AskUserQuestion to ask:

Do you need to link an Issue?

Options:
A. No, don't link Issue
B. Yes, link Issue (please enter Issue number)

If linking Issue, add to PR description:

• Closes #123 - Auto-close Issue when merged
• Fixes #123 - Fix Issue
• Relates to #123 - Related but don't auto-close

6.4 Generate PR Content

PR Title: Generate based on commit message or branch name, keep format concise and clear.

Important: PR title must be all lowercase. When converting camelCase words, use hyphens between words (e.g., devDependencies → dev-dependencies). Example: fix: add lerna to dev-dependencies

PR Description (according to template or default format):

## Summary

{Change overview, 2-3 sentences explaining what this PR does}

## Changes

{Specific change list}
- Change 1
- Change 2
- ...

## Related Issues

{If there are linked Issues}
Closes #{issue_number}

## Test Plan

{Verification methods and test points}
- [ ] Verification point 1
- [ ] Verification point 2
- [ ] Unit tests pass
- [ ] Lint check passes

## Screenshots (if applicable)

{If there are UI changes, add screenshots}

6.5 Choose PR Creation Method

After generating PR content, use AskUserQuestion to ask user:

How would you like to create the PR?

Options:
A. Create PR.md file (for manual submission later)
B. Submit PR directly using gh CLI (Recommended)

6.5.1 Option A: Create PR.md File

Create a PR.md file in the repository root with the PR content:

cat > PR.md << 'EOF'
# {pr_title}

**Target Branch**: {TARGET_BRANCH}
**Source Branch**: {CURRENT_BRANCH}

{pr_body}
EOF

echo "✅ PR.md created. You can manually create PR on GitHub using this content."

Output:

===== PR.md Created =====

File: PR.md
Title: {pr_title}
Target Branch: {target_branch}

Next Steps:
1. Open GitHub repository: https://github.com/{ORG}/{REPO}
2. Click "Pull requests" → "New pull request"
3. Select base: {TARGET_BRANCH}, compare: {CURRENT_BRANCH}
4. Copy content from PR.md

6.5.2 Option B: Submit PR using gh CLI

First check gh CLI availability:

# Check if gh is installed
if ! command -v gh &> /dev/null; then
    echo "❌ gh CLI is not installed."
    echo ""
    echo "Install gh CLI:"
    echo "  macOS: brew install gh"
    echo "  Linux: see https://cli.github.com/linux"
    echo "  Windows: winget install GitHub.cli"
    echo ""
    echo "After installation, run: gh auth login"
    exit 1
fi

# Check if gh is authenticated
if ! gh auth status &> /dev/null; then
    echo "❌ gh CLI is not authenticated."
    echo ""
    echo "Run: gh auth login"
    echo "Then retry creating PR."
    exit 1
fi

Create PR:

gh pr create \
  --title "{pr_title}" \
  --body "$(cat <<'EOF'
{pr_body}
EOF
)" \
  --base $TARGET_BRANCH

6.6 Output Result

If PR created via gh:

===== PR Created Successfully =====

PR URL: {pr_url}
Title: {pr_title}
Target Branch: {target_branch}
Linked Issues: {issue_numbers or "None"}

===== Next Steps =====
Wait for Code Review

If PR.md created:

===== PR.md Created =====

File: PR.md
Please manually create PR on GitHub.

Error Handling

Relationship with Other Skills