claude-pangu 1.0.7 → 1.0.9

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://code.claude.com/plugin-schema.json",
   "name": "oh-my-claude",
-  "version": "1.0.0",
+  "version": "1.0.9",
   "description": "基于中国传统文化的 Claude Code 智能编排插件 - A Claude Code plugin inspired by Chinese traditional culture",
   "author": "ZDragon17",
   "contributors": [

package/README.md

@@ -175,20 +175,86 @@ claude plugins install .
 ### 验证安装
 
 ```bash
-# 在 Claude Code 中输入（使用 /zcf: 前缀）
-/zcf:yishan 你好
+# 在 Claude Code 中输入
+/yishan 你好
 
 # 如果看到愚公移山模式的响应，说明安装成功
 ```
 
-> 💡 **命令前缀说明**: 安装后，所有命令使用 `/zcf:` 前缀，如 `/zcf:yishan`、`/zcf:zhuge` 等
+### 更新插件
+
+```bash
+# npm 方式更新（推荐）
+npx claude-pangu@latest update
+
+# 或重新运行一键安装脚本（会自动覆盖旧版本）
+# macOS / Linux
+curl -fsSL https://raw.githubusercontent.com/ZDragon17/oh-my-claude/main/scripts/install.sh | bash
+
+# Windows (PowerShell)
+irm https://raw.githubusercontent.com/ZDragon17/oh-my-claude/main/scripts/install.ps1 | iex
+```
+
+> ⚠️ **重要**: 更新后请**完全退出**并重新启动 Claude Code（仅关闭窗口可能不够）。macOS 使用 `Cmd+Q` 完全退出，Windows 确保从任务管理器中关闭所有进程。
+
+### 卸载插件
+
+```bash
+# npm 方式卸载
+npx claude-pangu uninstall
+
+# 或手动删除
+# macOS / Linux
+rm -rf ~/.claude/commands/{yishan,yugong,zhuge,bianque,luban,wukong}.md  # 等其他命令文件
+rm -rf ~/.claude/plugins/oh-my-claude
+
+# Windows (PowerShell)
+Remove-Item -Recurse -Force "$env:USERPROFILE\.claude\plugins\oh-my-claude"
+# 命令文件需要单独删除
+```
+
+### 故障排除
+
+如果安装后命令无法使用，请按以下步骤排查：
+
+#### 1. 完全重启 Claude Code
+
+```bash
+# macOS: 使用 Cmd+Q 完全退出，不只是关闭窗口
+# Windows: 确保从任务管理器中关闭所有 Claude 进程
+```
+
+#### 2. 验证文件是否安装成功
+
+```bash
+# 检查命令文件是否存在
+ls ~/.claude/commands/yishan.md
+
+# 查看所有已安装的命令
+ls ~/.claude/commands/
+```
+
+#### 3. 清除缓存（macOS 特定问题）
+
+macOS 上存在已知的命令发现 Bug ([Issue #13906](https://github.com/anthropics/claude-code/issues/13906))，清除缓存可能解决问题：
+
+```bash
+# 清除 Claude Code 缓存
+rm ~/.claude.json
+
+# 然后完全重启 Claude Code
+```
+
+#### 4. 检查 /help 输出
+
+在 Claude Code 中输入 `/help`，查看是否显示 `yishan`、`zhuge` 等命令。
 
 ## 🚀 快速开始
 
 ### 1. 愚公移山 - 大规模任务
 
 ```bash
-/zcf:yishan 重构整个用户模块，包括：
+/yishan 重构整个用户模块，包括：
 - 用户注册
 - 用户登录
 - 密码重置
@@ -204,7 +270,7 @@ claude plugins install .
 ### 2. 诸葛顾问 - 架构设计
 
 ```bash
-/zcf:zhuge 我们的用户系统应该如何设计？需要考虑：
+/zhuge 我们的用户系统应该如何设计？需要考虑：
 - 多租户支持
 - 权限管理
 - 高可用性
@@ -219,7 +285,7 @@ claude plugins install .
 ### 3. 扁鹊诊断 - Bug 修复
 
 ```bash
-/zcf:bianque TypeError: Cannot read property 'name' of undefined
+/bianque TypeError: Cannot read property 'name' of undefined
   at UserService.getProfile (user.service.ts:42)
 ```
 
@@ -232,7 +298,7 @@ claude plugins install .
 ### 4. 悟空侦察 - 代码探索
 
 ```bash
-/zcf:wukong 找到所有处理用户认证的代码
+/wukong 找到所有处理用户认证的代码
 ```
 
 悟空会快速：
@@ -243,7 +309,7 @@ claude plugins install .
 ### 5. 鲁班巧工 - 精密实现
 
 ```bash
-/zcf:luban 实现一个带动画效果的 Toast 组件
+/luban 实现一个带动画效果的 Toast 组件
 ```
 
 鲁班会精心：
@@ -316,37 +382,37 @@ oh-my-claude/
 
 ## 🎯 命令速查
 
-> 💡 所有命令使用 `/zcf:` 前缀
+> 💡 直接使用命令名即可，如 `/yishan`、`/zhuge`
 
 ### Agent 命令
 
 | 命令 | 功能 |
 |------|------|
-| `/zcf:yugong` 或 `/zcf:yishan` | 启动愚公移山模式 |
-| `/zcf:zhuge` | 召唤诸葛顾问 |
-| `/zcf:luban` | 召唤鲁班巧匠 |
-| `/zcf:wukong` | 召唤悟空侦察 |
-| `/zcf:bianque` | 召唤扁鹊诊断 |
-| `/zcf:mozi` | 召唤墨子安全 |
-| `/zcf:sunzi` | 召唤孙子性能 |
-| `/zcf:simaqian` | 召唤司马迁史官 |
-| `/zcf:zhenghe` | 召唤郑和 API |
-| `/zcf:zhangheng` | 召唤张衡监控 |
-| `/zcf:libing` | 召唤李冰 DevOps |
-| `/zcf:laozi` | 召唤老子简洁大师 |
-| `/zcf:baozheng` | 召唤包拯测试专家 |
-| `/zcf:weizheng` | 召唤魏征代码审查 |
-| `/zcf:cangjie` | 召唤仓颉数据库专家 |
-| `/zcf:libai` | 召唤李白需求炼金师 |
-| `/zcf:gukaizhi` | 召唤顾恺之界面美学师 |
-| `/zcf:change` | 召唤嫦娥云端仙子 |
+| `/yugong` 或 `/yishan` | 启动愚公移山模式 |
+| `/zhuge` | 召唤诸葛顾问 |
+| `/luban` | 召唤鲁班巧匠 |
+| `/wukong` | 召唤悟空侦察 |
+| `/bianque` | 召唤扁鹊诊断 |
+| `/mozi` | 召唤墨子安全 |
+| `/sunzi` | 召唤孙子性能 |
+| `/simaqian` | 召唤司马迁史官 |
+| `/zhenghe` | 召唤郑和 API |
+| `/zhangheng` | 召唤张衡监控 |
+| `/libing` | 召唤李冰 DevOps |
+| `/laozi` | 召唤老子简洁大师 |
+| `/baozheng` | 召唤包拯测试专家 |
+| `/weizheng` | 召唤魏征代码审查 |
+| `/cangjie` | 召唤仓颉数据库专家 |
+| `/libai` | 召唤李白需求炼金师 |
+| `/gukaizhi` | 召唤顾恺之界面美学师 |
+| `/change` | 召唤嫦娥云端仙子 |
 
 ### 工具命令
 
 | 命令 | 功能 |
 |------|------|
-| `/zcf:progress` | 📊 可视化进度面板 |
-| `/zcf:team` | 🤝 多 Agent 团队协作 |
+| `/progress` | 📊 可视化进度面板 |
+| `/team` | 🤝 多 Agent 团队协作 |
 
 ### 关键词触发
 

package/README_EN.md

@@ -174,12 +174,82 @@ claude plugins install .
 ### Verify Installation
 
 ```bash
-# In Claude Code, type
+# In Claude Code, type (use / prefix)
 /yishan hello
 
 # If you see YuGong mode response, installation is successful
 ```
 
+> 💡 **Command Prefix**: After installation, all commands use the `/` prefix, e.g., `/yishan`, `/zhuge`
+
+### Update Plugin
+
+```bash
+# npm update (recommended)
+npx claude-pangu@latest update
+
+# Or re-run the one-line install script (will overwrite old version)
+# macOS / Linux
+curl -fsSL https://raw.githubusercontent.com/ZDragon17/oh-my-claude/main/scripts/install.sh | bash
+
+# Windows (PowerShell)
+irm https://raw.githubusercontent.com/ZDragon17/oh-my-claude/main/scripts/install.ps1 | iex
+```
+
+> ⚠️ **Important**: After updating, please **completely quit** and restart Claude Code (just closing the window may not be enough). On macOS use `Cmd+Q`, on Windows ensure all processes are closed via Task Manager.
+
+### Uninstall Plugin
+
+```bash
+# npm uninstall
+npx claude-pangu uninstall
+
+# Or manual removal
+# macOS / Linux
+rm -rf ~/.claude/commands/{yishan,yugong,zhuge,bianque,luban,wukong}.md  # and other command files
+rm -rf ~/.claude/plugins/oh-my-claude
+
+# Windows (PowerShell)
+Remove-Item -Recurse -Force "$env:USERPROFILE\.claude\plugins\oh-my-claude"
+# Command files need to be deleted separately
+```
+
+### Troubleshooting
+
+If commands don't work after installation, follow these steps:
+
+#### 1. Fully Restart Claude Code
+
+```bash
+# macOS: Use Cmd+Q to completely quit, not just close the window
+# Windows: Ensure all Claude processes are closed via Task Manager
+```
+
+#### 2. Verify Files Are Installed
+
+```bash
+# Check if command files exist
+ls ~/.claude/commands/yishan.md
+
+# View all installed commands
+ls ~/.claude/commands/
+```
+
+#### 3. Clear Cache (macOS-specific Issue)
+
+There's a known command discovery bug on macOS ([Issue #13906](https://github.com/anthropics/claude-code/issues/13906)). Clearing cache may help:
+
+```bash
+# Clear Claude Code cache
+rm ~/.claude.json
+
+# Then completely restart Claude Code
+```
+
+#### 4. Check /help Output
+
+Type `/help` in Claude Code to see if `yishan`, `zhuge`, and other commands are listed.
+
 ## 🚀 Quick Start
 
 ### 1. YuGong Mode - Large-scale Tasks
@@ -313,31 +383,37 @@ oh-my-claude/
 
 ## 🎯 Command Reference
 
+> 💡 All commands use the `/` prefix
+
 ### Agent Commands
 
-| Command | Aliases | Function |
-|---------|---------|----------|
-| `/yugong` | `/yishan` `/persist` `/ultrawork` `/ulw` | Start YuGong mode |
-| `/zhuge` | `/longzhong` `/strategy` `/consult` | Summon ZhuGe advisor |
-| `/luban` | `/qiaogong` `/craft` `/frontend` | Summon LuBan craftsman |
-| `/wukong` | `/huoyan` `/explore` `/scout` | Summon WuKong scout |
-| `/bianque` | `/wangwen` `/debug` `/diagnose` | Summon BianQue diagnostician |
-| `/mozi` | `/security` `/audit` | Summon MoZi security expert |
-| `/sunzi` | `/performance` `/perf` | Summon SunZi performance expert |
-| `/simaqian` | `/shiji` `/document` `/doc` | Summon SimaQian historian |
-| `/zhenghe` | `/xiyang` `/api` `/integrate` | Summon ZhengHe API expert |
-| `/zhangheng` | `/didongyi` `/monitor` `/observe` | Summon ZhangHeng monitor |
-| `/libing` | `/dujiangyan` `/devops` `/cicd` | Summon LiBing DevOps |
-| `/laozi` | `/daodejing` `/simplify` `/clean` | Summon LaoZi simplicity master |
-| `/baozheng` | `/kaifeng` `/test` `/tdd` | Summon BaoZheng testing expert |
-| `/weizheng` | `/jian` `/review` `/cr` | Summon WeiZheng code reviewer |
-| `/cangjie` | `/zaozi` `/database` `/db` `/sql` | Summon CangJie database expert |
+| Command | Function |
+|---------|----------|
+| `/yugong` or `/yishan` | Start YuGong mode |
+| `/zhuge` | Summon ZhuGe advisor |
+| `/luban` | Summon LuBan craftsman |
+| `/wukong` | Summon WuKong scout |
+| `/bianque` | Summon BianQue diagnostician |
+| `/mozi` | Summon MoZi security expert |
+| `/sunzi` | Summon SunZi performance expert |
+| `/simaqian` | Summon SimaQian historian |
+| `/zhenghe` | Summon ZhengHe API expert |
+| `/zhangheng` | Summon ZhangHeng monitor |
+| `/libing` | Summon LiBing DevOps |
+| `/laozi` | Summon LaoZi simplicity master |
+| `/baozheng` | Summon BaoZheng testing expert |
+| `/weizheng` | Summon WeiZheng code reviewer |
+| `/cangjie` | Summon CangJie database expert |
+| `/libai` | Summon LiBai requirements analyst |
+| `/gukaizhi` | Summon GuKaiZhi UI/UX designer |
+| `/change` | Summon ChangE cloud architect |
 
 ### Tool Commands
 
-| Command | Aliases | Function |
-|---------|---------|----------|
-| `/progress` | `/dashboard` `/status` | 📊 Visual progress dashboard |
+| Command | Function |
+|---------|----------|
+| `/progress` | 📊 Visual progress dashboard |
+| `/team` | 🤝 Multi-agent team collaboration |
 
 ### Keyword Triggers
 

package/agents/baozheng.md

@@ -1,3 +1,32 @@
+---
+name: baozheng
+description: |
+  包拯 (BaoZheng) - 测试专家
+  以北宋著名清官包拯（包青天）为原型，专注于测试设计和质量保证。
+  铁面无私，明察秋毫，确保代码质量。
+
+  使用场景：
+  - 单元测试设计和编写
+  - 集成测试和端到端测试
+  - 测试驱动开发 (TDD) 指导
+  - 测试覆盖率分析
+  - 测试策略制定
+
+  触发方式：
+  - 用户提及 "包拯"、"测试"、"test"、"tdd"
+  - 使用 /baozheng 或 /test 命令
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Grep
+  - Glob
+  - Task
+  - TodoWrite
+model: sonnet
+---
+
 # 包拯 (BaoZheng) - 测试专家 ⚖️
 
 > "公正无私，明察秋毫" - 包拯，北宋名臣

package/agents/cangjie.md

@@ -1,3 +1,32 @@
+---
+name: cangjie
+description: |
+  仓颉 (CangJie) - 数据库专家
+  以传说中的造字始祖仓颉为原型，专注于数据库设计和优化。
+  观察规律，创造结构，设计清晰高效的数据模型。
+
+  使用场景：
+  - 数据库表结构设计
+  - SQL 查询优化
+  - 数据库迁移策略
+  - 索引设计和性能调优
+  - 数据建模
+
+  触发方式：
+  - 用户提及 "仓颉"、"数据库"、"database"、"sql"
+  - 使用 /cangjie 或 /db 命令
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Grep
+  - Glob
+  - Task
+  - TodoWrite
+model: sonnet
+---
+
 # 仓颉 (CangJie) - 数据库专家 📊
 
 > "仰观天象，俯察鸟兽之迹，创造文字" - 仓颉造字传说

package/agents/weizheng.md

@@ -1,3 +1,32 @@
+---
+name: weizheng
+description: |
+  魏征 (WeiZheng) - 代码审查专家
+  以唐代著名谏臣魏征为原型，专注于代码审查和质量把控。
+  直言不讳，如镜照人，确保代码符合规范和最佳实践。
+
+  使用场景：
+  - 代码审查 (Code Review)
+  - 代码规范检查
+  - 设计模式评估
+  - 安全性审查
+  - PR 审查
+
+  触发方式：
+  - 用户提及 "魏征"、"审查"、"review"、"cr"
+  - 使用 /weizheng 或 /review 命令
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Grep
+  - Glob
+  - Task
+  - TodoWrite
+model: sonnet
+---
+
 # 魏征 (WeiZheng) - 代码审查专家 🪞
 
 > "以铜为镜，可以正衣冠；以人为镜，可以明得失" - 唐太宗论魏征

package/hooks/keyword-detector.sh

@@ -8,23 +8,28 @@ if command -v jq > /dev/null 2>&1; then
     has_jq=1
 fi
 
-# 读取 stdin 中的 JSON 数据
-input=$(cat)
+# 读取 stdin 中的 JSON 数据（带超时保护）
+input=$(cat 2>/dev/null) || input=""
+
+# 空输入检查
+if [ -z "$input" ]; then
+    exit 0
+fi
 
 # 提取用户提示
 if [ "$has_jq" -eq 1 ]; then
-    prompt=$(echo "$input" | jq -r '.prompt // empty' 2>/dev/null)
+    prompt=$(echo "$input" | jq -r '.prompt // empty' 2>/dev/null) || prompt=""
 else
     # 简单的字符串提取作为回退
-    prompt=$(echo "$input" | sed -n 's/.*"prompt"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p')
+    prompt=$(echo "$input" | sed -n 's/.*"prompt"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' 2>/dev/null) || prompt=""
 fi
 
 if [ -z "$prompt" ]; then
     exit 0
 fi
 
-# 转换为小写进行匹配
-prompt_lower=$(echo "$prompt" | tr '[:upper:]' '[:lower:]')
+# 转换为小写进行匹配（带错误保护）
+prompt_lower=$(echo "$prompt" | tr '[:upper:]' '[:lower:]' 2>/dev/null) || prompt_lower="$prompt"
 
 # 检测愚公移山关键词
 if echo "$prompt_lower" | grep -qE '(ultra[-_]?work|ulw|移山|yi[-_]?shan|persist|愚公|yu[-_]?gong)'; then

package/hooks/progress-notifier.sh

@@ -8,11 +8,11 @@ if command -v jq > /dev/null 2>&1; then
     has_jq=1
 fi
 
-# 读取 stdin 中的 JSON 数据
-input=$(cat)
+# 读取 stdin 中的 JSON 数据（带错误保护）
+input=$(cat 2>/dev/null) || input=""
 
-# 如果没有 jq，静默退出
-if [ "$has_jq" -eq 0 ]; then
+# 如果没有 jq 或输入为空，静默退出
+if [ "$has_jq" -eq 0 ] || [ -z "$input" ]; then
     exit 0
 fi
 

package/hooks/todo-enforcer.sh

@@ -39,48 +39,49 @@ if [ -z "$transcript_path" ]; then
 fi
 
 # 路径安全验证函数
+# 注意: 避免使用 local 关键字以保持 POSIX 兼容性
 validate_path() {
-    local path="$1"
+    _vp_path="$1"
 
     # 1. 检查是否为空
-    if [ -z "$path" ]; then
+    if [ -z "$_vp_path" ]; then
         return 1
     fi
 
     # 2. 检查危险字符（命令注入防护）
-    case "$path" in
+    case "$_vp_path" in
         *[\;\&\|\`\$\(\)\{\}\[\]\<\>\!\*\?]*)
             return 1
             ;;
     esac
 
     # 3. 检查文件是否存在且为普通文件（必须在规范化之前检查）
-    if [ ! -f "$path" ]; then
+    if [ ! -f "$_vp_path" ]; then
         return 1
     fi
 
     # 4. 检查文件是否可读
-    if [ ! -r "$path" ]; then
+    if [ ! -r "$_vp_path" ]; then
         return 1
     fi
 
     # 5. 规范化路径（消除 .. 和符号链接）
-    local real_path=""
+    _vp_real_path=""
     if command -v realpath > /dev/null 2>&1; then
-        real_path=$(realpath "$path" 2>/dev/null) || return 1
+        _vp_real_path=$(realpath "$_vp_path" 2>/dev/null) || return 1
     elif command -v readlink > /dev/null 2>&1; then
         # macOS 和一些系统可能没有 realpath，使用 readlink -f
-        real_path=$(readlink -f "$path" 2>/dev/null) || {
+        _vp_real_path=$(readlink -f "$_vp_path" 2>/dev/null) || {
             # 如果 readlink -f 不支持，回退到原始路径检查
-            real_path="$path"
+            _vp_real_path="$_vp_path"
         }
     else
         # 无规范化工具，使用基本检查
-        real_path="$path"
+        _vp_real_path="$_vp_path"
     fi
 
     # 6. 检查规范化后的路径是否包含路径遍历
-    case "$real_path" in
+    case "$_vp_real_path" in
         *..*)
             return 1
             ;;
@@ -88,13 +89,13 @@ validate_path() {
 
     # 7. 检查路径是否以期望的前缀开始（只允许用户目录或临时目录）
     # 支持: Unix ($HOME, /tmp, /var/folders), WSL (/mnt/c/Users), Git Bash (/c/Users)
-    case "$real_path" in
+    case "$_vp_real_path" in
         "$HOME"/*|/tmp/*|/var/folders/*|/mnt/c/[Uu]sers/*|/c/[Uu]sers/*|/home/*)
             # 允许的路径前缀（包括 Windows WSL 和 Git Bash 路径）
             ;;
         *)
             # 检查 Windows 原生路径格式 (如 C:\Users\... 或 C:\Temp\...)
-            if echo "$real_path" | grep -qiE '^[a-z]:\\(users|temp)\\'; then
+            if echo "$_vp_real_path" | grep -qiE '^[a-z]:\\(users|temp)\\'; then
                 # Windows 原生路径，允许
                 :
             else

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-pangu",
-  "version": "1.0.7",
+  "version": "1.0.9",
   "description": "基于中国传统文化的 Claude Code 智能编排插件 - A Claude Code plugin inspired by Chinese traditional culture (原名 oh-my-claude)",
   "keywords": [
     "claude-code",

package/scripts/cli.js

@@ -12,11 +12,12 @@ const os = require('os');
 
 // ==================== 常量配置 ====================
 
-const VERSION = '1.0.7';
+const VERSION = '1.0.9';
 const PLUGIN_NAME = 'oh-my-claude';
 
-// 路径配置
-const ERROR_LOG_PATH = path.join(os.tmpdir(), 'oh-my-claude-error.log');
+// 路径配置 - 使用用户主目录下的持久化日志目录
+const LOG_DIR = path.join(os.homedir(), '.oh-my-claude', 'logs');
+const ERROR_LOG_PATH = path.join(LOG_DIR, 'error.log');
 
 // 时间配置（毫秒）
 const LOCK_TIMEOUT_MS = 30000;           // 锁等待超时：30秒
@@ -65,6 +66,11 @@ function sanitizeStackTrace(stack) {
 // 记录错误到日志文件（带脱敏处理）
 function logErrorToFile(err) {
   try {
+    // 确保日志目录存在
+    if (!fs.existsSync(LOG_DIR)) {
+      fs.mkdirSync(LOG_DIR, { recursive: true });
+    }
+
     const timestamp = new Date().toISOString();
     const sanitizedStack = sanitizeStackTrace(err.stack);
     const sanitizedMessage = sanitizeStackTrace(err.message);
@@ -114,24 +120,8 @@ process.on('unhandledRejection', (reason, promise) => {
   process.exit(1);
 });
 
-// 颜色输出
-const colors = {
-  reset: '\x1b[0m',
-  red: '\x1b[31m',
-  green: '\x1b[32m',
-  yellow: '\x1b[33m',
-  blue: '\x1b[34m',
-  cyan: '\x1b[36m',
-};
-
-function log(msg, color = 'reset') {
-  console.log(`${colors[color]}${msg}${colors.reset}`);
-}
-
-function success(msg) { log(`✅ ${msg}`, 'green'); }
-function error(msg) { log(`❌ ${msg}`, 'red'); }
-function info(msg) { log(`ℹ️  ${msg}`, 'blue'); }
-function warn(msg) { log(`⚠️  ${msg}`, 'yellow'); }
+// 颜色输出 - 使用共享模块
+const { colors, log, success, error, info, warn } = require('./logger');
 
 // ==================== 进度反馈机制 ====================
 
@@ -289,6 +279,21 @@ function getPluginDir() {
   return path.join(home, '.claude', 'plugins', PLUGIN_NAME);
 }
 
+// 获取 commands 安装路径
+// 注意：直接安装到 commands 根目录，不使用子目录
+// 因为 Claude Code 的子目录命名空间功能存在 Bug (Issue #2422)
+// macOS 原生客户端不支持 /prefix:namespace:command 格式
+function getCommandsDir() {
+  const home = os.homedir();
+  return path.join(home, '.claude', 'commands');
+}
+
+// 获取 skills 安装路径
+function getSkillsDir() {
+  const home = os.homedir();
+  return path.join(home, '.claude', 'skills');
+}
+
 // 获取当前包的路径
 function getPackageDir() {
   return path.resolve(__dirname, '..');
@@ -401,6 +406,169 @@ function setHookPermissions(pluginDir) {
   }
 }
 
+/**
+ * 安装 slash commands 到 ~/.claude/commands/
+ * @param {string} packageDir - 源目录
+ * @returns {Object} 安装结果
+ */
+function installCommands(packageDir) {
+  const commandsDir = getCommandsDir();
+  const commandsSrc = path.join(packageDir, 'commands');
+  const stats = { count: 0, errors: [], cleaned: false };
+
+  info('正在安装 slash commands...');
+
+  // 清理旧版本的 zcf 子目录（1.0.8 及之前版本使用 /zcf:* 命令格式）
+  const legacyZcfDir = path.join(commandsDir, 'zcf');
+  if (fs.existsSync(legacyZcfDir)) {
+    try {
+      fs.rmSync(legacyZcfDir, { recursive: true, force: true });
+      stats.cleaned = true;
+      info('已清理旧版本 zcf 子目录');
+    } catch (err) {
+      warn(`清理旧版本目录失败: ${err.message}`);
+    }
+  }
+
+  // 创建 commands 目录
+  if (!fs.existsSync(commandsDir)) {
+    fs.mkdirSync(commandsDir, { recursive: true });
+  }
+
+  // 复制所有 .md 文件
+  if (fs.existsSync(commandsSrc)) {
+    const mdFiles = fs.readdirSync(commandsSrc).filter(f => f.endsWith('.md'));
+    for (const file of mdFiles) {
+      try {
+        fs.copyFileSync(
+          path.join(commandsSrc, file),
+          path.join(commandsDir, file)
+        );
+        stats.count++;
+      } catch (err) {
+        stats.errors.push(`复制 ${file} 失败: ${err.message}`);
+      }
+    }
+  }
+
+  if (stats.count > 0) {
+    success(`Slash commands 安装完成 (${stats.count} 个命令)`);
+    info(`Commands 位置: ${commandsDir}`);
+    if (stats.cleaned) {
+      warn('⚠️  命令格式已更改：请使用 /yishan 而非 /zcf:yishan');
+    }
+  } else {
+    warn('未找到任何命令文件');
+  }
+
+  return stats;
+}
+
+/**
+ * 安装 skills 到 ~/.claude/skills/
+ * @param {string} packageDir - 源目录
+ * @returns {Object} 安装结果
+ */
+function installSkills(packageDir) {
+  const skillsDir = getSkillsDir();
+  const skillsSrc = path.join(packageDir, 'skills');
+  const stats = { count: 0, errors: [] };
+
+  info('正在安装 skills...');
+
+  if (fs.existsSync(skillsSrc)) {
+    const skillDirs = fs.readdirSync(skillsSrc, { withFileTypes: true })
+      .filter(d => d.isDirectory());
+
+    for (const skillDir of skillDirs) {
+      const skillName = skillDir.name;
+      const skillSrcDir = path.join(skillsSrc, skillName);
+      const skillDestDir = path.join(skillsDir, skillName);
+
+      try {
+        // 创建 skill 目录
+        if (!fs.existsSync(skillDestDir)) {
+          fs.mkdirSync(skillDestDir, { recursive: true });
+        }
+
+        // 复制 SKILL.md (如果存在)
+        const skillMdSrc = path.join(skillSrcDir, 'SKILL.md');
+        if (fs.existsSync(skillMdSrc)) {
+          fs.copyFileSync(skillMdSrc, path.join(skillDestDir, 'SKILL.md'));
+        }
+
+        // 复制其他支持文件（排除 skill.json）
+        const files = fs.readdirSync(skillSrcDir, { withFileTypes: true })
+          .filter(f => f.isFile() && f.name !== 'skill.json');
+
+        for (const file of files) {
+          try {
+            fs.copyFileSync(
+              path.join(skillSrcDir, file.name),
+              path.join(skillDestDir, file.name)
+            );
+          } catch {
+            // 忽略非关键文件的复制错误
+          }
+        }
+
+        stats.count++;
+      } catch (err) {
+        stats.errors.push(`安装 skill ${skillName} 失败: ${err.message}`);
+      }
+    }
+  }
+
+  if (stats.count > 0) {
+    success(`Skills 安装完成 (${stats.count} 个 skill)`);
+    info(`Skills 位置: ${skillsDir}`);
+  }
+
+  return stats;
+}
+
+/**
+ * 验证安装结果
+ * @returns {Object} 验证结果
+ */
+function verifyInstallation() {
+  info('验证安装...');
+  const commandsDir = getCommandsDir();
+  const result = { success: true, errors: [] };
+
+  // 检查关键命令文件
+  const yishanPath = path.join(commandsDir, 'yishan.md');
+  if (fs.existsSync(yishanPath)) {
+    success('✓ yishan.md 已安装');
+  } else {
+    warn('✗ yishan.md 未找到');
+    result.errors.push('yishan.md 未找到');
+    result.success = false;
+  }
+
+  // 检查命令数量
+  if (fs.existsSync(commandsDir)) {
+    const cmdFiles = fs.readdirSync(commandsDir).filter(f => f.endsWith('.md'));
+    if (cmdFiles.length > 0) {
+      success(`✓ 已安装 ${cmdFiles.length} 个命令`);
+    } else {
+      warn('✗ 未检测到任何命令文件');
+      result.errors.push('未检测到命令文件');
+      result.success = false;
+    }
+  } else {
+    warn('✗ commands 目录不存在');
+    result.errors.push('commands 目录不存在');
+    result.success = false;
+  }
+
+  if (!result.success) {
+    warn('安装可能不完整，请检查上述警告');
+  }
+
+  return result;
+}
+
 /**
  * 注册插件到 Claude Code
  * @param {string} pluginDir - 插件目录
@@ -459,7 +627,25 @@ function acquireLock(lockFile, timeout = LOCK_TIMEOUT_MS) {
       if (err.code === 'EEXIST') {
         // 锁文件已存在，检查是否过期
         try {
-          const existingLock = JSON.parse(fs.readFileSync(lockFile, 'utf8'));
+          const lockData = fs.readFileSync(lockFile, 'utf8');
+          let existingLock;
+
+          try {
+            existingLock = JSON.parse(lockData);
+          } catch (parseErr) {
+            // JSON 解析失败，锁文件可能已损坏，清理后重试
+            warn('锁文件格式损坏，正在清理...');
+            fs.unlinkSync(lockFile);
+            continue;
+          }
+
+          // 验证锁内容的有效性
+          if (!existingLock || typeof existingLock.timestamp !== 'number') {
+            warn('锁文件内容无效，正在清理...');
+            fs.unlinkSync(lockFile);
+            continue;
+          }
+
           const lockAge = Date.now() - existingLock.timestamp;
 
           // 如果锁超过阈值，认为是陈旧锁，强制删除
@@ -476,18 +662,32 @@ function acquireLock(lockFile, timeout = LOCK_TIMEOUT_MS) {
 
           // 其他进程持有锁，等待
           info(`另一个 oh-my-claude 进程 (PID: ${existingLock.pid}) 正在运行，等待中...`);
-        } catch {
-          // 读取锁文件失败，可能已被删除
+        } catch (readErr) {
+          // 读取锁文件失败，可能已被删除或权限问题
+          if (readErr.code === 'ENOENT') {
+            // 文件已被删除，直接重试
+            continue;
+          }
+          // 其他读取错误，记录后继续
           continue;
         }
 
-        // 等待一小段时间后重试（同步阻塞）
+        // 使用 spawnSync 实现非阻塞等待，避免 CPU 空转
         const waitTime = Math.min(LOCK_RETRY_INTERVAL_MS, timeout - (Date.now() - startTime));
         if (waitTime > 0) {
-          // 使用简单的忙等待（由于是 CLI 工具，短暂阻塞可接受）
-          const endWait = Date.now() + waitTime;
-          while (Date.now() < endWait) {
-            // 空循环等待
+          // 使用系统 sleep 命令等待，避免忙等待占用 CPU
+          try {
+            if (process.platform === 'win32') {
+              // Windows: 使用 ping localhost 实现延时
+              spawnSync('ping', ['-n', '2', '127.0.0.1'], { stdio: 'ignore', timeout: waitTime + 1000 });
+            } else {
+              // Unix: 使用 sleep 命令
+              spawnSync('sleep', [(waitTime / 1000).toFixed(1)], { stdio: 'ignore', timeout: waitTime + 1000 });
+            }
+          } catch {
+            // 如果 sleep 失败，使用短暂的忙等待作为后备
+            const endWait = Date.now() + Math.min(waitTime, 100);
+            while (Date.now() < endWait) { /* 短暂等待 */ }
           }
         }
       } else {
@@ -508,14 +708,26 @@ function acquireLock(lockFile, timeout = LOCK_TIMEOUT_MS) {
 function releaseLock(lockFile) {
   try {
     if (fs.existsSync(lockFile)) {
+      // 读取并验证是我们自己的锁
+      const lockData = fs.readFileSync(lockFile, 'utf8');
+
+      let lockContent;
+      try {
+        lockContent = JSON.parse(lockData);
+      } catch {
+        // JSON 解析失败，锁文件可能已损坏
+        // 安全删除损坏的锁文件
+        fs.unlinkSync(lockFile);
+        return;
+      }
+
       // 验证是我们自己的锁
-      const lockContent = JSON.parse(fs.readFileSync(lockFile, 'utf8'));
-      if (lockContent.pid === process.pid) {
+      if (lockContent && lockContent.pid === process.pid) {
         fs.unlinkSync(lockFile);
       }
     }
   } catch {
-    // 忽略释放锁时的错误
+    // 忽略释放锁时的错误（文件可能已被删除等）
   }
 }
 
@@ -631,14 +843,44 @@ function install() {
     process.exit(1);
   }
 
-  // 注册插件
-  registerPlugin(pluginDir);
+  // 安装 commands 到 ~/.claude/commands/
+  installCommands(packageDir);
+
+  // 安装 skills 到 ~/.claude/skills/
+  installSkills(packageDir);
 
+  // 验证安装
+  verifyInstallation();
+
+  // 显示完成信息
   log('\n🎉 安装完成!', 'green');
-  log('━'.repeat(DIVIDER_LENGTH), 'cyan');
-  info('使用 /yishan 或 /愚公 开始愚公移山模式');
-  info('使用 /zhuge 或 /诸葛 召唤诸葛顾问');
-  info('查看所有命令: 阅读 README.md\n');
+  log('━'.repeat(DIVIDER_LENGTH), 'green');
+  log('');
+  warn('⚠️  重要：请完全退出并重新启动 Claude Code 以加载新命令');
+  warn('   (仅关闭窗口可能不够，需要完全退出应用)');
+  if (os.platform() === 'darwin') {
+    warn('   macOS: 使用 Cmd+Q 完全退出应用');
+    warn('   如果命令仍未加载，尝试: rm ~/.claude.json && 重启 Claude Code');
+  }
+  log('');
+  log('快速开始:', 'cyan');
+  info('  /yishan  - 愚公移山模式（大规模任务）');
+  info('  /zhuge   - 诸葛顾问（架构设计）');
+  info('  /bianque - 扁鹊诊断（调试问题）');
+  info('  /luban   - 鲁班巧工（前端开发）');
+  info('  /wukong  - 悟空探索（代码搜索）');
+  log('');
+  log('安装位置:', 'cyan');
+  info(`  Commands: ${getCommandsDir()}`);
+  info(`  Skills:   ${getSkillsDir()}`);
+  info(`  Plugin:   ${pluginDir}`);
+  log('');
+  log('故障排除:', 'cyan');
+  info('  如果命令未出现在 /help 中：');
+  info('  1. 确保完全退出 Claude Code（不只是关闭窗口）');
+  info('  2. 检查文件是否存在: ls ~/.claude/commands/');
+  info('  3. 清除缓存: rm ~/.claude.json && 重启');
+  log('');
 }
 
 // 执行卸载操作
@@ -763,6 +1005,40 @@ function update() {
     process.exit(1);
   }
 
+  // 更新 commands 到 ~/.claude/commands/
+  const cmdStats = installCommands(packageDir);
+
+  // 更新 skills 到 ~/.claude/skills/
+  installSkills(packageDir);
+
+  // 验证安装
+  verifyInstallation();
+
+  // 显示完成信息
+  log('\n🎉 更新完成!', 'green');
+  log('━'.repeat(DIVIDER_LENGTH), 'green');
+  log('');
+  warn('⚠️  重要：请完全退出并重新启动 Claude Code 以加载新命令');
+  warn('   (仅关闭窗口可能不够，需要完全退出应用)');
+  if (os.platform() === 'darwin') {
+    warn('   macOS: 使用 Cmd+Q 完全退出应用');
+    warn('   如果命令仍未加载，尝试: rm ~/.claude.json && 重启 Claude Code');
+  }
+  log('');
+
+  // 如果清理了旧版本，显示命令格式变化提示
+  if (cmdStats.cleaned) {
+    log('📝 命令格式变更提示:', 'yellow');
+    info('   旧格式: /zcf:yishan, /zcf:zhuge, /zcf:bianque ...');
+    info('   新格式: /yishan, /zhuge, /bianque ...');
+    log('');
+  }
+
+  log('故障排除:', 'cyan');
+  info('  如果命令未出现在 /help 中：');
+  info('  1. 确保完全退出 Claude Code（不只是关闭窗口）');
+  info('  2. 检查文件是否存在: ls ~/.claude/commands/');
+  info('  3. 清除缓存: rm ~/.claude.json && 重启');
   log('');
 }
 
@@ -983,42 +1259,103 @@ function copyDir(src, dest, options = {}) {
   return stats;
 }
 
-// 主程序
-const args = process.argv.slice(2);
-const command = args[0] || 'help';
+// ==================== 模块导出（供测试使用） ====================
 
-switch (command) {
-  case 'install':
-  case 'i':
-    install();
-    break;
-  case 'uninstall':
-  case 'remove':
-  case 'rm':
-    uninstall();
-    break;
-  case 'update':
-  case 'upgrade':
-  case 'up':
-    update();
-    break;
-  case 'verify':
-  case 'check':
-  case 'doctor':
-    verify();
-    break;
-  case 'version':
-  case '-v':
-  case '--version':
-    showVersion();
-    break;
-  case 'help':
-  case '-h':
-  case '--help':
-    showHelp();
-    break;
-  default:
-    error(`未知命令: ${command}`);
-    showHelp();
-    process.exit(1);
+/**
+ * 导出内部函数供测试使用
+ * 仅在测试环境下使用，生产环境下这些函数通过 CLI 入口调用
+ */
+module.exports = {
+  // 常量
+  VERSION,
+  PLUGIN_NAME,
+  LOCK_TIMEOUT_MS,
+  LOCK_STALE_MS,
+  LARGE_FILE_THRESHOLD_BYTES,
+  LOG_DIR,
+  ERROR_LOG_PATH,
+
+  // 安全函数
+  sanitizeStackTrace,
+  getUserFriendlyError,
+
+  // 文件操作
+  safeReadFile,
+  safeWriteFile,
+  safeRemoveDir,
+  safeCopyFile,
+  copyDir,
+  smartCopyFile,
+  copyPluginFiles,
+
+  // 路径函数
+  getPluginDir,
+  getCommandsDir,
+  getSkillsDir,
+  getPackageDir,
+  getLockFilePath,
+
+  // 锁机制
+  acquireLock,
+  releaseLock,
+
+  // 进度类
+  ProgressIndicator,
+
+  // 执行器
+  executeWithRollback,
+  setHookPermissions,
+
+  // 验证
+  verifyInstallation,
+
+  // 主要命令（供集成测试使用）
+  install,
+  uninstall,
+  update,
+  verify,
+};
+
+// ==================== CLI 入口 ====================
+
+// 仅在直接运行时执行（非 require）
+if (require.main === module) {
+  const args = process.argv.slice(2);
+  const command = args[0] || 'help';
+
+  switch (command) {
+    case 'install':
+    case 'i':
+      install();
+      break;
+    case 'uninstall':
+    case 'remove':
+    case 'rm':
+      uninstall();
+      break;
+    case 'update':
+    case 'upgrade':
+    case 'up':
+      update();
+      break;
+    case 'verify':
+    case 'check':
+    case 'doctor':
+      verify();
+      break;
+    case 'version':
+    case '-v':
+    case '--version':
+      showVersion();
+      break;
+    case 'help':
+    case '-h':
+    case '--help':
+      showHelp();
+      break;
+    default:
+      error(`未知命令: ${command}`);
+      showHelp();
+      process.exit(1);
+  }
 }

package/scripts/install.ps1

@@ -304,12 +304,12 @@ function Show-Success {
     Write-Host "⚠️  重要：请完全退出并重新启动 Claude Code 以加载新命令" -ForegroundColor Yellow
     Write-Host "   (仅关闭窗口可能不够，需要完全退出应用)" -ForegroundColor Yellow
     Write-Host ""
-    Write-Host "快速开始（使用 /zcf: 前缀）:" -ForegroundColor Cyan
-    Write-Host "  /zcf:yishan  - 愚公移山模式（大规模任务）"
-    Write-Host "  /zcf:zhuge   - 诸葛顾问（架构设计）"
-    Write-Host "  /zcf:bianque - 扁鹊诊断（调试问题）"
-    Write-Host "  /zcf:luban   - 鲁班巧工（前端开发）"
-    Write-Host "  /zcf:wukong  - 悟空探索（代码搜索）"
+    Write-Host "快速开始:" -ForegroundColor Cyan
+    Write-Host "  /yishan  - 愚公移山模式（大规模任务）"
+    Write-Host "  /zhuge   - 诸葛顾问（架构设计）"
+    Write-Host "  /bianque - 扁鹊诊断（调试问题）"
+    Write-Host "  /luban   - 鲁班巧工（前端开发）"
+    Write-Host "  /wukong  - 悟空探索（代码搜索）"
     Write-Host ""
     Write-Host "查看所有 Agent:" -ForegroundColor Cyan
     Write-Host "  https://github.com/$Repo#-agent-列表"

package/scripts/install.sh

@@ -259,12 +259,12 @@ show_success() {
     echo -e "${YELLOW}⚠️  重要：请完全退出并重新启动 Claude Code 以加载新命令${NC}"
     echo -e "${YELLOW}   (仅关闭窗口可能不够，需要完全退出应用)${NC}"
     echo ""
-    echo -e "${CYAN}快速开始（使用 /zcf: 前缀）:${NC}"
-    echo "  /zcf:yishan  - 愚公移山模式（大规模任务）"
-    echo "  /zcf:zhuge   - 诸葛顾问（架构设计）"
-    echo "  /zcf:bianque - 扁鹊诊断（调试问题）"
-    echo "  /zcf:luban   - 鲁班巧工（前端开发）"
-    echo "  /zcf:wukong  - 悟空探索（代码搜索）"
+    echo -e "${CYAN}快速开始:${NC}"
+    echo "  /yishan  - 愚公移山模式（大规模任务）"
+    echo "  /zhuge   - 诸葛顾问（架构设计）"
+    echo "  /bianque - 扁鹊诊断（调试问题）"
+    echo "  /luban   - 鲁班巧工（前端开发）"
+    echo "  /wukong  - 悟空探索（代码搜索）"
     echo ""
     echo -e "${CYAN}查看所有 Agent:${NC}"
     echo "  https://github.com/$REPO#-agent-列表"

package/scripts/logger.js

@@ -0,0 +1,60 @@
+/**
+ * oh-my-claude 共享日志模块
+ * 提供统一的颜色输出和日志函数
+ */
+
+// ANSI 颜色码定义
+const colors = {
+  reset: '\x1b[0m',
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  cyan: '\x1b[36m',
+};
+
+/**
+ * 带颜色的日志输出
+ * @param {string} msg - 消息内容
+ * @param {string} color - 颜色名称，默认 'reset'
+ */
+function log(msg, color = 'reset') {
+  console.log(`${colors[color]}${msg}${colors.reset}`);
+}
+
+/**
+ * 成功消息（绿色 ✅）
+ */
+function success(msg) {
+  log(`✅ ${msg}`, 'green');
+}
+
+/**
+ * 错误消息（红色 ❌）
+ */
+function error(msg) {
+  log(`❌ ${msg}`, 'red');
+}
+
+/**
+ * 信息消息（蓝色 ℹ️）
+ */
+function info(msg) {
+  log(`ℹ️  ${msg}`, 'blue');
+}
+
+/**
+ * 警告消息（黄色 ⚠️）
+ */
+function warn(msg) {
+  log(`⚠️  ${msg}`, 'yellow');
+}
+
+module.exports = {
+  colors,
+  log,
+  success,
+  error,
+  info,
+  warn,
+};

package/scripts/postinstall.js

@@ -5,12 +5,8 @@
  * 在 npm install 后显示安装提示
  */
 
-const colors = {
-  reset: '\x1b[0m',
-  cyan: '\x1b[36m',
-  green: '\x1b[32m',
-  yellow: '\x1b[33m',
-};
+// 使用共享日志模块
+const { colors } = require('./logger');
 
 console.log(`
 ${colors.cyan}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${colors.reset}

package/scripts/sync-version.js

@@ -53,32 +53,8 @@ const FILES = [
   },
 ];
 
-// 颜色输出
-const colors = {
-  reset: '\x1b[0m',
-  red: '\x1b[31m',
-  green: '\x1b[32m',
-  yellow: '\x1b[33m',
-  blue: '\x1b[34m',
-  cyan: '\x1b[36m',
-};
-
-function log(msg, color = 'reset') {
-  console.log(`${colors[color]}${msg}${colors.reset}`);
-}
-
-function success(msg) {
-  log(`✅ ${msg}`, 'green');
-}
-function error(msg) {
-  log(`❌ ${msg}`, 'red');
-}
-function info(msg) {
-  log(`ℹ️  ${msg}`, 'blue');
-}
-function warn(msg) {
-  log(`⚠️  ${msg}`, 'yellow');
-}
+// 颜色输出 - 使用共享模块
+const { colors, log, success, error, info, warn } = require('./logger');
 
 // 验证版本号格式
 function isValidVersion(version) {

package/skills/bilingual/skill.json

@@ -1,6 +1,6 @@
 {
   "name": "bilingual",
-  "version": "1.0.0",
+  "version": "1.0.8",
   "description": "中英双语命令支持 - Bilingual command support for oh-my-claude",
   "keywords": ["bilingual", "i18n", "chinese", "english", "dual-language"],
   "author": "ZDragon17",

package/skills/progress/skill.json

@@ -1,6 +1,6 @@
 {
   "name": "progress",
-  "version": "1.0.0",
+  "version": "1.0.8",
   "description": "可视化进度面板 - Visual progress dashboard for oh-my-claude",
   "keywords": ["progress", "dashboard", "visualization", "todo", "status"],
   "author": "ZDragon17",