| name | gitnexus-wiki |
| description | 使用 GitNexus 调用大语言模型生成项目架构 Wiki。当用户要求生成文档、创建项目 Wiki 或编写架构文档时调用。注意:脚本在技能目录下,执行在当前项目目录下。 |
GitNexus Wiki 生成器 Skill
技能描述
此技能用于异步调用 GitNexus 为当前代码库生成架构 Wiki。
该脚本会在后台异步生成 Wiki 文档,生成完成后用户可以直接在浏览器中打开 .gitnexus/wiki/index.html 查看结果。
重要提示:所有输出和交互必须使用中文(简体中文)。
触发条件
当用户说出以下关键词时调用此 Skill:
- "生成 Wiki"
- "创建文档"
- "写项目文档"
- "生成架构文档"
- "用 GitNexus 写文档"
- "Wiki 生成进度"
- "查看 Wiki 状态"
执行步骤(必须按顺序执行)
步骤 1:检查现有 Wiki 生成状态
首先执行以下命令检查是否已有 Wiki 在生成或已完成:
ps aux | grep -E "gitnexus wiki" | grep -v grep && echo "RUNNING" || echo "NOT_RUNNING"
同时检查 Wiki 文件是否已存在:
ls -lh .gitnexus/wiki/index.html 2>/dev/null && echo "WIKI_EXISTS" || echo "NO_WIKI_FILE"
情况 A:进程正在运行
如果检测到 gitnexus wiki 进程正在运行,告诉用户:
"检测到 Wiki 生成任务正在进行中。生成完成后,您可以在浏览器中打开 .gitnexus/wiki/index.html 查看结果。"
情况 B:Wiki 文件已存在且进程未运行
如果检测到 Wiki 文件(.gitnexus/wiki/index.html)且没有运行中的进程,询问用户:
"检测到已有 Wiki 文件生成。您想要:1) 查看现有 Wiki;2) 重新生成 Wiki;3) 查看 Wiki 文件位置?"
情况 C:无运行进程且无 Wiki 文件
继续执行步骤 2。
步骤 2:执行 Skill 脚本
⚠️ 重要:脚本位于 技能目录(SKILL.md 所在目录),但需要在 执行目录(当前项目目录)下运行。
首先确定技能目录的绝对路径,然后执行:
SKILL_DIR="你的技能目录绝对路径"
"${SKILL_DIR}/scripts/gitnexus-wiki.sh" --workdir "$(pwd)"
不要询问用户是否执行,直接运行上述命令。
步骤 3:处理权限错误(如需要)
如果步骤 2 返回 "Permission denied" 错误,必须先执行赋权命令:
chmod +x "${SKILL_DIR}/scripts/gitnexus-wiki.sh"
然后重新执行步骤 2。
步骤 4:处理执行结果
根据脚本的返回结果,按以下情况处理:
情况 A:执行成功
如果脚本返回成功(exit code 0),告诉用户:
"✅ Wiki 生成任务已在后台启动!生成完成后,您可以在浏览器中打开 .gitnexus/wiki/index.html 查看结果。"
情况 B:缺少配置(脚本输出包含 [ACTION_REQUIRED])
不要报错结束。主动询问用户:
"我没有在您的本地配置中找到大模型 API Key。请直接发送您的 API Key 给我。如果您使用自定义代理或特定模型,也可以一并告诉我(如:Key + 代理地址 + 模型名),我将为您全局保存并继续生成。"
情况 C:用户提供 API Key 后
当用户提供 API Key、Base URL、模型名等信息后,必须执行以下命令:
API_KEY="用户提供的Key" BASE_URL="用户提供的URL" MODEL="用户提供的模型" "${SKILL_DIR}/scripts/gitnexus-wiki.sh" --workdir "$(pwd)"
状态检查命令参考
检查 Wiki 生成进程
ps aux | grep -E "gitnexus wiki" | grep -v grep
检查 Wiki 文件是否已生成
ls -lh .gitnexus/wiki/index.html 2>/dev/null || echo "Wiki 仍在生成中..."
查看 Wiki 生成日志
cat .gitnexus/wiki.log
查找已生成的 Wiki 文件
find . -maxdepth 2 -type f \( -iname "*wiki*.md" -o -iname "WIKI.md" \) 2>/dev/null
常用命令(中文说明)
gitnexus list
gitnexus status
gitnexus wiki --help
核心能力
- 智能层级读取:按优先级读取多个配置源
- OpenCode Provider 支持:自动从 OpenCode 配置的第一个 provider 中提取 API Key、Base URL 和模型
- Claude Settings 支持:从 Claude Code 的 settings.json 中提取配置
- 全局持久化:新配置保存到
~/.gitnexus/config.json
- 进程防抖:杀掉旧的 wiki 进程,避免冲突
- 异步执行:后台生成文档,不阻塞用户操作
- 多模型支持:支持 OpenAI、Anthropic 等兼容接口
- 状态检测:自动检测现有 Wiki 生成状态和文件
- 浏览器查看:生成完成后可直接在浏览器中打开
.gitnexus/wiki/index.html
- 中文输出:所有提示和说明使用简体中文
配置层级(优先级从高到低)
- 环境变量:
API_KEY, BASE_URL, MODEL
- GitNexus 全局配置:
~/.gitnexus/config.json
- OpenCode 配置:
~/.config/opencode/opencode.json
- Claude Code 配置:
~/.claude/settings.json
预期输出
执行成功后,向用户展示:
- Wiki 生成位置:
.gitnexus/wiki/index.html
- 浏览器查看方式:
file://$(pwd)/.gitnexus/wiki/index.html
- 检查进度命令:
ls -lh .gitnexus/wiki/index.html
- 常用命令提示(中文说明)
质量评估标准
- 配置发现:成功从所有配置源读取
- 全局持久化:新配置正确保存
- 进程防抖:旧进程终止后才启动新进程
- 状态检测:正确识别现有 Wiki 生成状态和文件
- 异步执行:生成任务在后台运行,不阻塞用户
- 优雅降级:配置缺失时给出清晰提示
- 中文输出:所有提示和说明使用简体中文
Skill 文件位置说明
本 Skill 可能位于以下目录之一:
~/.claude/skills/ - Claude Code 技能目录
~/.config/opencode/skills/ - OpenCode 技能目录
~/.cc-switch/skills/ - CC-Switch 技能目录
⚠️ 技能目录 vs 执行目录(重要)
技能目录(A):SKILL.md 和脚本所在的目录,即 $(dirname "$SKILL_FILE")。
执行目录(B):当前用户工作目录(即当前 Git 仓库根目录)。
脚本位于 A 目录,但需要在 B 目录执行。 执行时必须使用 A 目录的脚本路径:
SKILL_DIR="你的技能目录绝对路径"
"${SKILL_DIR}/scripts/gitnexus-wiki.sh" --workdir "$(pwd)"
如果无法通过变量解析脚本路径,请根据 Skill 的实际安装位置使用对应的绝对路径:
~/.claude/skills/gitnexus-wiki/scripts/gitnexus-wiki.sh --workdir "$(pwd)"
~/.config/opencode/skills/gitnexus-wiki/scripts/gitnexus-wiki.sh --workdir "$(pwd)"
~/.cc-switch/skills/gitnexus-wiki/scripts/gitnexus-wiki.sh --workdir "$(pwd)"
参考资料
详见 Reference.md