colyn-cli 3.1.4

package/docs/zh-CN/manual/README.md

@@ -0,0 +1,108 @@
+# Colyn 用户手册
+
+**版本**: 2.5.5
+**最后更新**: 2026-02-10
+
+---
+
+## 欢迎使用 Colyn
+
+Colyn 是一个强大的 Git Worktree 管理工具，专为需要并行开发多个功能的开发者设计。它简化了 Git worktree 的创建和管理流程，自动处理端口分配，支持 tmux 集成，让你能够轻松实现多分支并行开发。
+
+### 核心特性
+
+- **🚀 简化 Worktree 管理**: 一键创建和管理 git worktree，无需复杂的命令
+- **🎯 自动端口分配**: 智能分配开发服务器端口，避免端口冲突
+- **📁 自动目录切换**: 命令执行后自动切换到目标目录
+- **🔍 智能分支处理**: 自动识别本地分支、远程分支或创建新分支
+- **⚡ 自动补全**: 支持 Bash/Zsh Tab 键补全命令、选项和参数
+- **🖥️ tmux 集成**: 在 tmux 中实现高效的 worktree 管理和切换
+- **🌐 跨平台支持**: macOS、Linux、Windows 全平台支持
+
+### 适用场景
+
+Colyn 特别适合以下使用场景：
+
+- **并行功能开发**: 同时开发多个功能，无需频繁切换分支
+- **多版本测试**: 在不同分支上同时运行开发服务器进行对比测试
+- **Bug 修复**: 保持当前开发状态，快速切换到 bugfix 分支
+- **代码审查**: 在独立环境中审查他人的分支代码
+- **AI 协作开发**: 使用 Claude Code 等 AI 工具实现"并行 Vibe Coding"
+
+---
+
+## 手册结构
+
+本用户手册包含以下章节：
+
+0. **[用户故事：从一个人到一支 AI 团队](00-user-story.md)** - 通过一个完整的真实场景，了解 Colyn 能做什么
+1. **[快速开始](01-quick-start.md)** - 5 分钟快速上手
+2. **[安装指南](02-installation.md)** - 详细的安装说明
+3. **[核心概念](03-core-concepts.md)** - 理解 Colyn 的工作原理
+4. **[命令参考](04-command-reference/README.md)** - 所有命令的详细说明（按分类组织）
+5. **[高级用法](05-advanced-usage.md)** - 高级功能和技巧
+6. **[tmux 集成](06-tmux-integration.md)** - tmux 环境下的高效工作流
+7. **[最佳实践](07-best-practices.md)** - 推荐的工作流程和技巧
+8. **[故障排除](08-troubleshooting.md)** - 常见问题和解决方案
+9. **[术语表](09-glossary.md)** - 术语和概念速查
+10. **[配置系统](10-configuration.md)** - 完整的配置文件指南
+11. **[插件系统](11-plugin-system.md)** - 多语言工具链支持（npm / Maven / Gradle / pip）
+
+---
+
+## 快速导航
+
+### 新用户
+
+如果你是第一次使用 Colyn：
+
+1. 阅读 [用户故事](00-user-story.md) 快速了解 Colyn 能解决什么问题
+2. 阅读 [快速开始](01-quick-start.md) 了解基本用法
+3. 查看 [核心概念](03-core-concepts.md) 理解工作原理
+4. 参考 [命令参考](04-command-reference/README.md) 学习具体命令
+
+### 已有用户
+
+如果你已经在使用 Colyn：
+
+- 需要特定命令说明 → [命令参考](04-command-reference/README.md)
+- 配置文件设置 → [配置系统](10-configuration.md)
+- 遇到问题 → [故障排除](08-troubleshooting.md)
+- 查找术语 → [术语表](09-glossary.md)
+- 学习高级技巧 → [高级用法](05-advanced-usage.md)
+
+### tmux 用户
+
+如果你使用 tmux：
+
+- 完整的 tmux 集成指南 → [tmux 集成](06-tmux-integration.md)
+- 快捷键和工作流 → [最佳实践](07-best-practices.md)
+
+---
+
+## 获取帮助
+
+### 命令行帮助
+
+在命令行中随时查看帮助：
+
+```bash
+# 查看所有命令
+colyn --help
+
+# 查看特定命令的帮助
+colyn init --help
+colyn add --help
+```
+
+### 项目信息
+
+- **GitHub 仓库**: [github.com/colinhan/colyn](https://github.com/colinhan/colyn)
+- **问题反馈**: [GitHub Issues](https://github.com/colinhan/colyn/issues)
+- **版本历史**: [CHANGELOG.md](../CHANGELOG.md)
+
+---
+
+## 开始使用
+
+准备好了吗？从 [快速开始](01-quick-start.md) 开始你的 Colyn 之旅！

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "colyn-cli",
+  "version": "3.1.4",
+  "description": "Git worktree 管理工具",
+  "type": "module",
+  "bin": "./bin/colyn",
+  "files": [
+    "dist/",
+    "bin/",
+    "shell/",
+    "README.md",
+    "README-en.md"
+  ],
+  "scripts": {
+    "dev": "tsc --watch",
+    "build": "tsc",
+    "prepack": "yarn build",
+    "colyn": "node dist/index.js",
+    "install-to": "node scripts/install.js",
+    "test": "vitest",
+    "test:ui": "vitest --ui",
+    "test:coverage": "vitest --coverage",
+    "lint": "eslint src --ext .ts",
+    "format": "prettier --write \"src/**/*.ts\""
+  },
+  "keywords": [
+    "git",
+    "worktree",
+    "cli",
+    "development"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "chokidar": "^5.0.0",
+    "cli-table3": "^0.6.3",
+    "commander": "^12.0.0",
+    "deepmerge": "^4.3.1",
+    "dotenv": "^16.4.0",
+    "enquirer": "^2.4.1",
+    "i18next": "^25.8.0",
+    "js-yaml": "^4.1.1",
+    "json5": "^2.2.3",
+    "ora": "^8.0.1",
+    "simple-git": "^3.22.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/chokidar": "^2.1.7",
+    "@types/deepmerge": "^2.2.3",
+    "@types/js-yaml": "^4",
+    "@types/node": "^20.11.0",
+    "@typescript-eslint/eslint-plugin": "^6.19.0",
+    "@typescript-eslint/parser": "^6.19.0",
+    "@vitest/ui": "^1.2.0",
+    "eslint": "^8.56.0",
+    "prettier": "^3.2.4",
+    "typescript": "^5.3.3",
+    "vitest": "^1.2.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/shell/colyn.sh

@@ -0,0 +1,55 @@
+# Colyn Shell 集成（支持目录切换）
+# 使用方法：将以下内容添加到 ~/.bashrc 或 ~/.zshrc
+#   source /path/to/colyn/shell/colyn.sh
+
+colyn() {
+  # 定位 colyn 安装目录（兼容 bash 和 zsh）
+  local COLYN_SHELL_DIR
+  if [[ -n "${BASH_SOURCE[0]:-}" ]]; then
+    # bash
+    COLYN_SHELL_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+  elif [[ -n "${ZSH_VERSION:-}" ]]; then
+    # zsh
+    COLYN_SHELL_DIR="$(cd "$(dirname "${(%):-%x}")" && pwd)"
+  else
+    # fallback
+    COLYN_SHELL_DIR="$(cd "$(dirname "$0")" && pwd)"
+  fi
+
+  local COLYN_BIN="${COLYN_SHELL_DIR}/../../colyn"
+
+  if [[ ! -f "$COLYN_BIN" ]]; then
+    echo "错误: 找不到 colyn" >&2
+    return 1
+  fi
+
+  # 调用 bin/colyn，捕获 stdout（JSON），stderr 直接显示
+  local result
+  result=$(COLYN_OUTPUT_JSON=1 "$COLYN_BIN" "$@")
+  local exit_code=$?
+
+  # 处理输出
+  if [[ -n "$result" ]]; then
+    # 尝试解析 JSON
+    local target_dir display_path attach_session is_json_result
+    target_dir=$(node -e "try{const r=JSON.parse(process.argv[1]);if(r.success&&r.targetDir)console.log(r.targetDir)}catch(e){process.exit(1)}" "$result" 2>/dev/null)
+    attach_session=$(node -e "try{const r=JSON.parse(process.argv[1]);if(r.success&&r.attachSession)console.log(r.attachSession)}catch(e){}" "$result" 2>/dev/null)
+    node -e "try{JSON.parse(process.argv[1]);process.exit(0)}catch(e){process.exit(1)}" "$result" 2>/dev/null
+    is_json_result=$?
+
+    if [[ $? -eq 0 && -n "$attach_session" ]]; then
+      # 需要连接到 tmux session
+      exec tmux attach-session -t "$attach_session"
+    elif [[ $? -eq 0 && -n "$target_dir" && -d "$target_dir" ]]; then
+      # 是 JSON 且有目标目录
+      display_path=$(node -e "try{const r=JSON.parse(process.argv[1]);console.log(r.displayPath||r.targetDir)}catch(e){}" "$result" 2>/dev/null)
+      cd "$target_dir" || return
+      echo "📂 已切换到: $display_path"
+    elif [[ $is_json_result -ne 0 ]]; then
+      # 不是 JSON，原样输出（如 --help）
+      echo "$result"
+    fi
+  fi
+
+  return $exit_code
+}

package/shell/completion.bash

@@ -0,0 +1,270 @@
+#!/usr/bin/env bash
+# Bash completion script for colyn
+#
+# Installation:
+#   source /path/to/completion.bash
+# Or add to ~/.bashrc:
+#   echo "source /path/to/completion.bash" >> ~/.bashrc
+
+_colyn_completion() {
+    local cur prev words cword
+    _init_completion || return
+
+    # 所有可用命令
+    local commands="init add list list-project lsp merge update remove checkout info status repair config setup tmux release completion todo"
+
+    # 当前命令（第一个参数）
+    local command="${words[1]}"
+
+    # 如果还没有输入命令，补全命令列表
+    if [[ $cword -eq 1 ]]; then
+        COMPREPLY=($(compgen -W "$commands" -- "$cur"))
+        return 0
+    fi
+
+    # 根据不同命令提供补全
+    case "$command" in
+        init)
+            # init 命令没有参数
+            return 0
+            ;;
+
+        add)
+            # add <branch> - 补全 git 分支名
+            if [[ $cword -eq 2 ]]; then
+                # 获取所有本地和远程分支
+                local branches=$(git branch -a 2>/dev/null | sed 's/^[* ]*//' | sed 's/remotes\/origin\///' | sort -u)
+                COMPREPLY=($(compgen -W "$branches" -- "$cur"))
+            fi
+            return 0
+            ;;
+
+        list)
+            # list 命令选项
+            local list_opts="--json --paths --no-main"
+            if [[ $cur == -* ]]; then
+                COMPREPLY=($(compgen -W "$list_opts" -- "$cur"))
+            fi
+            return 0
+            ;;
+
+        merge)
+            # merge [id|branch] [--push|--no-push]
+            if [[ $cur == -* ]]; then
+                local merge_opts="--push --no-push"
+                COMPREPLY=($(compgen -W "$merge_opts" -- "$cur"))
+            elif [[ $cword -eq 2 ]]; then
+                # 补全 worktree ID 和分支名
+                _colyn_complete_worktrees
+            fi
+            return 0
+            ;;
+
+        update)
+            # update [target] [--all] [--no-rebase]
+            if [[ $cur == -* ]]; then
+                local update_opts="--all --no-rebase"
+                COMPREPLY=($(compgen -W "$update_opts" -- "$cur"))
+            elif [[ $cword -eq 2 ]]; then
+                _colyn_complete_worktrees
+            fi
+            return 0
+            ;;
+
+        remove)
+            # remove [id|branch] [-y|--yes] [-f|--force] [-d|--delete-branch]
+            if [[ $cur == -* ]]; then
+                local remove_opts="-y --yes -f --force -d --delete-branch"
+                COMPREPLY=($(compgen -W "$remove_opts" -- "$cur"))
+            elif [[ $cword -eq 2 ]]; then
+                # 补全 worktree ID 和分支名
+                _colyn_complete_worktrees
+            fi
+            return 0
+            ;;
+
+        checkout|co)
+            # checkout [id] <branch>
+            if [[ $cword -eq 2 ]]; then
+                # 第一个参数可以是 worktree ID
+                _colyn_complete_worktree_ids
+            elif [[ $cword -eq 3 ]]; then
+                # 第二个参数是分支名
+                local branches=$(git branch -a 2>/dev/null | sed 's/^[* ]*//' | sed 's/remotes\/origin\///' | sort -u)
+                COMPREPLY=($(compgen -W "$branches" -- "$cur"))
+            fi
+            return 0
+            ;;
+
+        info)
+            # info 命令选项
+            if [[ $cur == -* ]]; then
+                local info_opts="-f --field --format -s --separator"
+                COMPREPLY=($(compgen -W "$info_opts" -- "$cur"))
+            elif [[ $prev == "-f" || $prev == "--field" ]]; then
+                # 补全字段名
+                local fields="project project-path worktree-id worktree-dir branch"
+                COMPREPLY=($(compgen -W "$fields" -- "$cur"))
+            fi
+            return 0
+            ;;
+
+        status|st)
+            # status 命令无参数
+            return 0
+            ;;
+
+        repair)
+            # repair 命令无参数
+            return 0
+            ;;
+
+        config)
+            # config 命令选项
+            if [[ $cur == -* ]]; then
+                COMPREPLY=($(compgen -W "--json" -- "$cur"))
+            fi
+            return 0
+            ;;
+
+        setup)
+            # setup 命令无参数
+            return 0
+            ;;
+
+        tmux)
+            # tmux [start|stop] [-f|--force]
+            if [[ $cur == -* ]]; then
+                local tmux_opts="-f --force"
+                COMPREPLY=($(compgen -W "$tmux_opts" -- "$cur"))
+            elif [[ $cword -eq 2 ]]; then
+                COMPREPLY=($(compgen -W "start stop" -- "$cur"))
+            fi
+            return 0
+            ;;
+
+        release)
+            # release <version-type>
+            if [[ $cword -eq 2 ]]; then
+                COMPREPLY=($(compgen -W "patch minor major" -- "$cur"))
+            fi
+            return 0
+            ;;
+
+        completion)
+            # completion [shell] [--install]
+            if [[ $cur == -* ]]; then
+                COMPREPLY=($(compgen -W "--install" -- "$cur"))
+            elif [[ $cword -eq 2 ]]; then
+                COMPREPLY=($(compgen -W "bash zsh" -- "$cur"))
+            fi
+            return 0
+            ;;
+
+        list-project|lsp)
+            # list-project [--json] [-p|--paths]
+            if [[ $cur == -* ]]; then
+                local lsp_opts="--json -p --paths"
+                COMPREPLY=($(compgen -W "$lsp_opts" -- "$cur"))
+            fi
+            return 0
+            ;;
+
+        todo)
+            local subcommand="${words[2]}"
+            # 第一级：补全子命令
+            if [[ $cword -eq 2 ]]; then
+                COMPREPLY=($(compgen -W "add start list ls remove archive uncomplete edit" -- "$cur"))
+                return 0
+            fi
+            # 第二级：根据子命令补全参数
+            case "$subcommand" in
+                add)
+                    if [[ $cword -eq 3 && $cur != -* ]]; then
+                        # 补全 todoId 类型前缀
+                        COMPREPLY=($(compgen -W "feature/ bugfix/ refactor/ document/" -- "$cur"))
+                    fi
+                    ;;
+                start)
+                    if [[ $cur == -* ]]; then
+                        COMPREPLY=($(compgen -W "--no-clipboard" -- "$cur"))
+                    elif [[ $cword -eq 3 ]]; then
+                        _colyn_todo_ids
+                    fi
+                    ;;
+                list|ls)
+                    if [[ $cur == -* ]]; then
+                        COMPREPLY=($(compgen -W "--completed --archived --id-only" -- "$cur"))
+                    fi
+                    ;;
+                remove)
+                    if [[ $cur == -* ]]; then
+                        COMPREPLY=($(compgen -W "-y --yes" -- "$cur"))
+                    elif [[ $cword -eq 3 ]]; then
+                        _colyn_todo_ids
+                    fi
+                    ;;
+                archive)
+                    if [[ $cur == -* ]]; then
+                        COMPREPLY=($(compgen -W "-y --yes" -- "$cur"))
+                    fi
+                    ;;
+                uncomplete)
+                    if [[ $cword -eq 3 ]]; then
+                        _colyn_todo_completed_ids
+                    fi
+                    ;;
+            esac
+            return 0
+            ;;
+
+        *)
+            # 未知命令，不提供补全
+            return 0
+            ;;
+    esac
+}
+
+# 补全 worktree ID 和分支名
+_colyn_complete_worktrees() {
+    # 尝试获取 worktree 列表（JSON 格式）
+    local worktrees_json=$(colyn list --json --no-main 2>/dev/null)
+    if [[ $? -eq 0 && -n "$worktrees_json" ]]; then
+        # 提取 ID 和分支名
+        local ids=$(echo "$worktrees_json" | grep -o '"id":[0-9]*' | cut -d: -f2)
+        local branches=$(echo "$worktrees_json" | grep -o '"branch":"[^"]*"' | cut -d'"' -f4)
+        COMPREPLY=($(compgen -W "$ids $branches" -- "$cur"))
+    fi
+}
+
+# 补全 worktree ID（仅数字）
+_colyn_complete_worktree_ids() {
+    # 尝试获取 worktree 列表（JSON 格式）
+    local worktrees_json=$(colyn list --json --no-main 2>/dev/null)
+    if [[ $? -eq 0 && -n "$worktrees_json" ]]; then
+        # 提取 ID
+        local ids=$(echo "$worktrees_json" | grep -o '"id":[0-9]*' | cut -d: -f2)
+        COMPREPLY=($(compgen -W "$ids" -- "$cur"))
+    fi
+}
+
+# 补全待办 todo ID
+_colyn_todo_ids() {
+    local output
+    output=$(colyn todo list --id-only 2>/dev/null)
+    if [[ -n "$output" ]]; then
+        COMPREPLY=($(compgen -W "$output" -- "$cur"))
+    fi
+}
+
+# 补全已完成 todo ID
+_colyn_todo_completed_ids() {
+    local output
+    output=$(colyn todo list --completed --id-only 2>/dev/null)
+    if [[ -n "$output" ]]; then
+        COMPREPLY=($(compgen -W "$output" -- "$cur"))
+    fi
+}
+
+# 注册补全函数
+complete -F _colyn_completion colyn

package/shell/completion.zsh

@@ -0,0 +1,167 @@
+#compdef colyn
+# Zsh completion script for colyn
+#
+# Installation:
+#   source /path/to/completion.zsh
+# Or add to ~/.zshrc:
+#   echo "source /path/to/completion.zsh" >> ~/.zshrc
+
+_colyn() {
+    local -a commands
+    commands=(
+        'init:初始化 worktree 管理结构'
+        'add:创建新的 worktree'
+        'list:列出所有 worktree'
+        'merge:合并 worktree 到主分支'
+        'update:将主分支更新到 worktree'
+        'remove:删除 worktree'
+        'checkout:在 worktree 中切换分支'
+        'info:显示当前目录的项目信息'
+        'repair:修复 worktree 状态'
+        'config:查看或更新配置'
+        'system-integration:配置 shell 集成'
+        'tmux:tmux 集成管理'
+        'release:在主分支目录执行发布流程'
+        'completion:生成 shell 自动补全脚本'
+    )
+
+    local curcontext="$curcontext" state line
+    typeset -A opt_args
+
+    _arguments -C \
+        '1: :->command' \
+        '*::arg:->args'
+
+    case $state in
+        command)
+            _describe 'colyn commands' commands
+            ;;
+        args)
+            case $line[1] in
+                init)
+                    # init 命令没有参数
+                    ;;
+                add)
+                    # add <branch>
+                    _colyn_branches
+                    ;;
+                list)
+                    _arguments \
+                        '--json[以 JSON 格式输出]' \
+                        '(-p --paths)'{-p,--paths}'[只输出路径]' \
+                        '--no-main[不显示主分支]'
+                    ;;
+                merge)
+                    _arguments \
+                        '1: :_colyn_worktrees' \
+                        '--push[合并后自动推送]' \
+                        '--no-push[合并后不推送]'
+                    ;;
+                update)
+                    _arguments \
+                        '1: :_colyn_worktrees' \
+                        '--all[更新所有 worktree]' \
+                        '--no-rebase[使用 merge 而不是 rebase]'
+                    ;;
+                remove)
+                    _arguments \
+                        '1: :_colyn_worktrees' \
+                        '(-y --yes)'{-y,--yes}'[跳过确认]' \
+                        '(-f --force)'{-f,--force}'[强制删除（忽略未提交更改）]' \
+                        '(-d --delete-branch)'{-d,--delete-branch}'[同时删除本地分支]'
+                    ;;
+                checkout|co)
+                    _arguments \
+                        '1: :_colyn_worktree_ids' \
+                        '2: :_colyn_branches'
+                    ;;
+                info)
+                    _arguments \
+                        '(-f --field)'{-f,--field}'[输出指定字段]:field:_colyn_info_fields' \
+                        '--format[使用模板字符串格式化输出]:template:' \
+                        '(-s --separator)'{-s,--separator}'[多字段时的分隔符]:separator:'
+                    ;;
+                repair)
+                    # repair 命令无参数
+                    ;;
+                config)
+                    _arguments \
+                        '--json[以 JSON 格式输出]'
+                    ;;
+                system-integration)
+                    # system-integration 命令无参数
+                    ;;
+                tmux)
+                    _arguments \
+                        '1: :(start stop)' \
+                        '(-f --force)'{-f,--force}'[强制停止 session]'
+                    ;;
+                release)
+                    _arguments \
+                        '1: :('patch' 'minor' 'major')'
+                    ;;
+                completion)
+                    _arguments \
+                        '1: :(bash zsh)' \
+                        '--install[显示安装说明]'
+                    ;;
+            esac
+            ;;
+    esac
+}
+
+# 补全 git 分支名
+_colyn_branches() {
+    local -a branches
+    branches=(${(f)"$(git branch -a 2>/dev/null | sed 's/^[* ]*//' | sed 's/remotes\/origin\///' | sort -u)"})
+    _describe 'branches' branches
+}
+
+# 补全 worktree ID 和分支名
+_colyn_worktrees() {
+    local -a worktrees
+    local worktrees_json=$(colyn list --json --no-main 2>/dev/null)
+
+    if [[ $? -eq 0 && -n "$worktrees_json" ]]; then
+        # 提取 ID 和分支名
+        local -a ids branches
+        ids=(${(f)"$(echo "$worktrees_json" | grep -o '"id":[0-9]*' | cut -d: -f2)"})
+        branches=(${(f)"$(echo "$worktrees_json" | grep -o '"branch":"[^"]*"' | cut -d'"' -f4)"})
+
+        # 组合 ID 和分支名
+        local i
+        for i in {1..${#ids[@]}}; do
+            worktrees+=("${ids[$i]}:${branches[$i]}")
+        done
+
+        _describe 'worktrees' worktrees
+    fi
+}
+
+# 补全 worktree ID（仅数字）
+_colyn_worktree_ids() {
+    local -a ids
+    local worktrees_json=$(colyn list --json --no-main 2>/dev/null)
+
+    if [[ $? -eq 0 && -n "$worktrees_json" ]]; then
+        ids=(${(f)"$(echo "$worktrees_json" | grep -o '"id":[0-9]*' | cut -d: -f2)"})
+        _describe 'worktree IDs' ids
+    fi
+}
+
+# 补全 info 命令的字段名
+_colyn_info_fields() {
+    local -a fields
+    fields=(
+        'project:项目名称'
+        'project-path:项目路径'
+        'worktree-id:Worktree ID'
+        'worktree-dir:Worktree 目录名'
+        'branch:分支名'
+    )
+    _describe 'fields' fields
+}
+
+# 注册补全函数
+# #compdef 指令会自动调用 _colyn 函数，不需要手动执行
+compdef _colyn colyn