Add coding-agent skill v0.1.0

README.md

@@ -1,136 +1,237 @@
-# Qoder Community
+# Coding Agent Skill
 
-Global community platform for Qoder developers - share agents, learn together, build faster.
+将编码任务委托给 Claude Code、OpenCode、iFlow 或 qodercli，通过后台进程运行。
 
-## Tech Stack
+## 前提条件
 
-- **Framework**: [Astro](https://astro.build/) 5.6+
-- **Theme**: [Starlight](https://starlight.astro.build/) 0.37+
-- **Deployment**: [Cloudflare Pages](https://pages.cloudflare.com/)
-- **Language**: TypeScript + Markdown/MDX
+### 必须安装 tmux
 
-## Features
+由于 Bash 工具没有 PTY（伪终端）参数，运行交互式 CLI/TUI 工具（如 OpenCode、iFlow、qodercli 的交互模式）时，需要使用 **tmux** 来提供 PTY 环境。
 
-- Lightning-fast performance (Lighthouse 98-100)
-- Quick builds (~4 seconds)
-- Minimal JavaScript (~2.5KB)
-- Built-in full-text search
-- Dark mode support
-- Fully responsive
-- Global CDN via Cloudflare
-- Free web analytics
+**安装 tmux：**
 
-## Project Structure
+```bash
+# macOS
+brew install tmux
+
+# Ubuntu/Debian
+sudo apt install tmux
 
+# CentOS/RHEL
+sudo yum install tmux
 ```
-qoder-community/
-├── src/
-│   ├── content/
-│   │   ├── skills/        # Agent skills (English)
-│   │   ├── skills-zh/     # Agent skills (Chinese)
-│   │   ├── agents/        # Community agent configurations
-│   │   ├── videos/        # Tutorial videos
-│   │   ├── meetups/       # Global meetup events
-│   │   ├── showcase/      # Community projects
-│   │   └── docs/          # Site pages
-│   ├── components/
-│   │   ├── AgentCard.astro
-│   │   ├── VideoCard.astro
-│   │   └── MeetupCard.astro
-│   ├── pages/
-│   │   ├── agents.astro
-│   │   ├── learn.astro
-│   │   ├── meetups.astro
-│   │   └── showcase.astro
-│   └── styles/
-│       └── custom.css
-├── public/
-├── astro.config.mjs
-└── package.json
+
+### 编码代理 CLI 工具
+
+根据需要安装以下一个或多个编码代理：
+
+- **Claude Code**: `claude` CLI
+- **OpenCode**: `opencode` CLI
+- **iFlow**: `iflow` CLI
+- **qodercli**: `qodercli` CLI
+
+## 快速开始
+
+### 一次性任务
+
+对于简单的提示/对话，创建临时 git 仓库并运行：
+
+```bash
+# 创建临时工作目录
+SCRATCH=$(mktemp -d) && cd $SCRATCH && git init
+
+# OpenCode 一次性任务
+cd "$SCRATCH" && opencode run '你的提示词'
+
+# iFlow 一次性任务（非交互）
+cd "$SCRATCH" && iflow -p '你的提示词'
+
+# qodercli 一次性任务（非交互）
+cd "$SCRATCH" && qodercli -p '你的提示词'
 ```
 
-## Local Development
+> **为什么要 git init？** 许多代理 CLI 在 git 仓库中工作效果最佳（支持 diff、patch、历史记录）。临时仓库可以保持工作干净且可复现。
+
+## 使用模式
+
+### 核心模式：cd + tmux + capture-pane/send-keys
 
-### Install Dependencies
+对于较长的任务，在 tmux 中启动代理，然后使用 bash 运行 tmux 命令进行监控和交互：
 
 ```bash
-npm install
+# 1) 在目标目录启动代理（tmux 提供 PTY）
+tmux new-session -d -s opencode-1 "cd ~/project && opencode run '构建贪吃蛇游戏'"
+
+# 2) 监控输出（最后 50 行）
+tmux capture-pane -t opencode-1 -p | tail -50
+
+# 3) 安全发送输入（文本然后回车）
+tmux send-keys -t opencode-1 -l -- "yes"
+sleep 0.1
+tmux send-keys -t opencode-1 Enter
+
+# 4) 如需停止
+tmux send-keys -t opencode-1 C-c
+# 或终止 tmux 会话
+tmux kill-session -t opencode-1
 ```
 
-### Start Dev Server
+## 各代理详细用法
+
+### OpenCode (opencode)
+
+OpenCode 通常是交互式的（TUI），因此**在 tmux 中运行**：
 
 ```bash
-npm run dev
+# 启动 TUI（默认）
+tmux new-session -d -s opencode-1 "cd ~/project && opencode"
+
+# 运行一次性消息
+tmux new-session -d -s opencode-run-1 "cd ~/project && opencode run '添加深色模式切换'"
+
+# 指定模型 / 继续会话
+tmux new-session -d -s opencode-model-1 "cd ~/project && opencode -m zai-coding-plan/glm-4.7 run '重构认证模块'"
+tmux new-session -d -s opencode-continue-1 "cd ~/project && opencode -c"
+tmux new-session -d -s opencode-session-1 "cd ~/project && opencode -s <sessionId>"
+
+# PR 工作流
+tmux new-session -d -s opencode-pr-130 "cd ~/project && opencode pr 130"
 ```
 
-Visit: http://localhost:4321
+### Claude Code
 
-### Build for Production
+Claude Code 使用 `--print --permission-mode bypassPermissions` 模式：
 
 ```bash
-npm run build
+# 前台运行
+cd ~/project && claude --permission-mode bypassPermissions --print '你的任务'
+
+# 后台运行
+# 使用 Bash 工具的 run_in_background: true 参数
 ```
 
-### Preview Build
+### iFlow (iflow)
+
+iFlow 支持交互式和非交互式两种模式：
 
 ```bash
-npm run preview
+# 一次性任务（非交互）
+cd ~/project && iflow -p '解释这个仓库的架构并提出 3 个重构建议'
+
+# 提示后保持交互
+tmux new-session -d -s iflow-1 "cd ~/project && iflow -i '扫描仓库并识别风险模式；然后等待后续指令'"
+
+# 会话控制 / 限制
+cd ~/project && iflow -c -p '总结上次发布以来的变更'
+cd ~/project && iflow --max-turns 25 -p '修复失败的测试'
 ```
 
-## How to Contribute
+### qodercli
+
+qodercli 可以作为交互式助手或非交互式"打印后退出"模式运行：
+
+```bash
+# 交互模式
+tmux new-session -d -s qoder-1 "cd ~/project && qodercli -w ~/project"
+
+# 一次性任务（非交互）— 委托任务的首选方式
+# 注意：qodercli 的 -p 模式不需要 PTY，建议使用后台 bash 而非 tmux
+# 因为 tmux capture-pane 对 qodercli 可能返回空内容
+cd ~/project && qodercli -w ~/project -p '你的任务' --max-turns 25 2>&1 | tee /tmp/qoder-task.log
 
-We currently welcome contributions for **Agent Skills**. Help the community by sharing your specialized skills!
+# 监控进度
+tail -50 /tmp/qoder-task.log
 
-For detailed instructions on how to add and format your skills, please refer to our **[Contributing Guide](CONTRIBUTING.md)**.
+# 机器可读输出
+cd ~/project && qodercli -p '总结 src/ 职责' -f json
+```
 
-## Deployment
+**处理长提示词或非 ASCII 字符：**
 
-### Deploy to Cloudflare Pages
+```bash
+# 1) 将提示词写入临时文件
+# 2) 通过 $(cat ...) 传递
+cd ~/project && qodercli -w ~/project -p "$(cat /tmp/my-prompt.txt)" --max-turns 30
+```
 
-See `DEPLOYMENT.md` for detailed instructions.
+## 高级用法
 
-Quick steps:
+### 使用 git worktree 并行修复多个问题
 
 ```bash
-# 1. Push to GitHub
-git add .
-git commit -m "Update content"
-git push
+# 1. 为每个问题创建 worktree
+git worktree add -b fix/issue-78 /tmp/issue-78 main
+git worktree add -b fix/issue-99 /tmp/issue-99 main
+
+# 2. 在每个 worktree 中启动代理
+tmux new-session -d -s issue-78 "cd /tmp/issue-78 && pnpm install && opencode run '修复 issue #78'"
+tmux new-session -d -s issue-99 "cd /tmp/issue-99 && pnpm install && iflow -i '修复 issue #99'"
+
+# 3. 监控进度
+tmux list-sessions
+tmux capture-pane -t issue-78 -p | tail -50
 
-# 2. Cloudflare Pages auto-deploys (1-2 minutes)
+# 4. 修复完成后创建 PR
+cd /tmp/issue-78 && git push -u origin fix/issue-78
+gh pr create --repo user/repo --head fix/issue-78 --title "fix: ..." --body "..."
+
+# 5. 清理
+git worktree remove /tmp/issue-78
+git worktree remove /tmp/issue-99
 ```
 
-## Contributing
+## 重要规则
+
+1. **为每个代理选择正确的执行模式**：
+   - OpenCode/iFlow：在 **tmux** 中运行以获得交互性（PTY）
+   - qodercli 一次性任务（`-p`）：优先使用**直接后台 bash** 配合 `tee` 记录日志
+   - Claude Code：优先使用 `--print --permission-mode bypassPermissions`（非交互）
+
+2. **尊重工具选择** - 如果用户要求使用特定代理 CLI，请使用该 CLI
+
+3. **保持耐心** - 不要因为会话"慢"就终止它
+
+4. **智能监控** - 首先使用 `tmux capture-pane`，如果 10 秒后返回空内容，切换到日志文件（`tee` 输出）
+
+5. **并行是允许的** - 可以为批处理工作运行多个后台会话
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on contributing agent configurations.
+6. **永远不要在 ~/ 目录启动代理** - 避免将内部文档纳入上下文
 
-## Links
+## 常见问题
 
-- **Live Site**: https://qoder-community.pages.dev
-- **GitHub**: https://github.com/Qoder-AI/qoder-community
-- **Astro Docs**: https://docs.astro.build/
-- **Starlight Guide**: https://starlight.astro.build/
+### capture-pane 返回空内容
 
-## Troubleshooting
+某些代理 CLI（特别是 qodercli）使用备用屏幕缓冲区或延迟 stdout，导致 `tmux capture-pane` 返回空白输出。
 
-### Build Errors
+**解决方案**：使用 `tee` + 日志文件作为主要监控方法：
 
 ```bash
-# Clean and reinstall
-rm -rf node_modules package-lock.json
-npm install
-npm run build
+tmux new-session -d -s agent-1 "cd ~/project && agent-cli ... 2>&1 | tee /tmp/agent-task.log"
+tail -50 /tmp/agent-task.log
 ```
 
-### Content Not Showing
+### 脚手架 CLI 意外阻塞
+
+脚手架工具（create-next-app、create-vite 等）经常在新版本中添加交互提示。
+
+**解决方案**：管道默认答案处理意外提示：
+
+```bash
+echo "no" | npx create-next-app@latest my-app --typescript --tailwind --eslint --app --use-npm
+```
 
-Check frontmatter format is correct.
+### 区域设置 / 编码问题
 
-### Search Not Working
+Bash 工具环境可能不会继承 UTF-8 区域设置。如果看到乱码，请将提示词写入临时文件并通过 `$(cat /tmp/prompt.txt)` 传递。
 
-Check Pagefind output in build logs.
+## 进度更新
 
----
+当在后台启动编码代理时，请保持用户知情：
 
-Powered by Astro and Starlight  
-Hosted on Cloudflare Pages
+- 启动时发送简短消息（正在运行什么 + 在哪里）
+- 仅在以下情况更新：
+  - 里程碑完成（构建完成、测试通过）
+  - 代理提问 / 需要输入
+  - 遇到错误或需要用户操作
+  - 代理完成（包括变更内容 + 位置）
+- 如果终止会话，立即说明原因