Compare commits

...

2 Commits

Author SHA1 Message Date
zfc
6da34c4869 feat: support codex sh download 2026-03-09 22:17:01 +08:00
zfc
cc093d5f90 feat(skills): add doc generator skill 2026-03-09 21:34:00 +08:00
8 changed files with 334 additions and 93 deletions

101
.claude/skills/doc/SKILL.md Normal file
View File

@ -0,0 +1,101 @@
---
name: doc
description: 渐进式文档生成器。首次只写精炼梗概≤300字后续通过迭代不断完善。
---
# Doc - 渐进式文档生成器
> **核心理念**:文档是缝缝补补长出来的,不是一步到位写出来的。首次只写最重要的梗概,后续通过讨论和迭代逐步完善。
当用户调用 `/doc``/doc <指令>` 时,执行以下步骤:
## 1. 理解需求
如果用户提供了参数,使用该描述。否则询问要写什么文档。
快速确认(已知的不重复问):
| 项目 | 默认值 |
|------|--------|
| 文档主题 | 用户指令 |
| 输出路径 | 询问用户 |
| 作者署名 | 询问用户 |
简短讨论文档边界:列出你理解的覆盖范围,标注不确定的点,让用户拍板。
> 你是执笔人,不是决策者。"写什么、不写什么"由用户决定。
## 2. 快速调研
聚焦调研,不求面面俱到:
- 扫描相关代码和现有文档
- 提取核心概念、关键接口、主要数据流
- 了解项目现有文档风格(命名、格式)
调研完成后,用 2-3 句话告诉用户你发现了什么,有什么存疑的点。**不需要正式的大纲确认环节**,直接写梗概,快速拿到反馈比完美大纲更重要。
## 3. 生成梗概
### 3.1 写作原则
**首次写作(默认模式)**
- **言简意赅**,建议控制在 300 字以内
- 只写最重要的骨架:是什么、为什么、怎么用
- 留白是刻意的,后续迭代会填充细节
- 不需要面面俱到,抓住核心价值
**迭代补充**(用户再次调用 `/doc` 指向同一文件时):
- 读取现有内容,在此基础上增量补充
- 递增版本号,更新 `updated` 日期
- 每次迭代聚焦一个方面,不要一次补太多
### 3.2 文档头部
```markdown
---
title: {文档标题}
version: v1.0
created: {YYYY-MM-DD}
updated: {YYYY-MM-DD}
author: {作者署名}
---
```
### 3.3 内容要求
- **准确**:基于实际代码,不编造
- **精炼**:一句话能说清的不用两句
- **实用**:面向读者,提供可操作的信息
- 善用表格、代码块、ASCII 图示(但首次不强求)
## 4. 保存并输出
保存到用户指定路径。如果文件已存在,先询问是覆盖还是增量更新。
输出摘要:
```text
文档: {标题} | 版本: v1.0 | 路径: {path}
字数: ~{N}字(首版梗概)
后续可以通过 /doc 继续补充完善。
主人,用不用我沉淀 or git 提交?
```
## 工作流总览
```text
/doc <指令>
├── 1. 理解需求(简短确认主题、路径、署名)
├── 2. 快速调研(聚焦核心,不求全面)
├── 3. 生成梗概≤300字抓骨架
└── 4. 保存输出(鼓励后续迭代)
```
## 注意事项
- **少即是多**首版宁短勿长300 字是指导建议而非硬限制
- **鼓励迭代**:每次 `/doc` 都是一次对话机会,文档在讨论中成长
- **不做代码改动**:本 skill 只生成文档
- **风格一致**:与项目已有文档风格保持一致

View File

@ -25,6 +25,7 @@
- `mt`: 增量修改 tasks.md根据用户指令在现有内容基础上更新任务列表。 (file: `./.codex/skills/mt/SKILL.md`)
- `go`: 终极执行按钮,激进模式一口气完成开发任务,兼容 0->1 和 1->100 场景。 (file: `./.codex/skills/go/SKILL.md`)
- `iter`: 迭代变更入口,调研问题后更新 PRD.md 和 tasks.md支持 Bug 修复、功能迭代、技术重构。 (file: `./.codex/skills/iter/SKILL.md`)
- `doc`: 渐进式文档生成器。首次只写精炼梗概≤300字后续通过迭代不断完善。 (file: `./.codex/skills/doc/SKILL.md`)
- `update`: 收集用户反馈并更新最近使用的 skill。别名`up`。 (file: `./.codex/skills/up/SKILL.md`)
- `deploy`: Drone CI + 服务器 CD 全流程引导:从基础设施检查到生成配置文件到验证部署,交互式完成。 (file: `./.codex/skills/deploy/SKILL.md`)
- `changelog`: 一键发版:生成更新日志 → commit → 打 tag全流程自动化。 (file: `./.codex/skills/changelog/SKILL.md`)

101
.codex/skills/doc/SKILL.md Normal file
View File

@ -0,0 +1,101 @@
---
name: doc
description: 渐进式文档生成器。首次只写精炼梗概≤300字后续通过迭代不断完善。
---
# Doc - 渐进式文档生成器
> **核心理念**:文档是缝缝补补长出来的,不是一步到位写出来的。首次只写最重要的梗概,后续通过讨论和迭代逐步完善。
当用户调用 `doc` skill、`$doc`,或自然语言要求“用 doc 写文档”时,执行以下步骤:
## 1. 理解需求
如果用户提供了参数,使用该描述。否则询问要写什么文档。
快速确认(已知的不重复问):
| 项目 | 默认值 |
|------|--------|
| 文档主题 | 用户指令 |
| 输出路径 | 询问用户 |
| 作者署名 | 询问用户 |
简短讨论文档边界:列出你理解的覆盖范围,标注不确定的点,让用户拍板。
> 你是执笔人,不是决策者。"写什么、不写什么"由用户决定。
## 2. 快速调研
聚焦调研,不求面面俱到:
- 扫描相关代码和现有文档
- 提取核心概念、关键接口、主要数据流
- 了解项目现有文档风格(命名、格式)
调研完成后,用 2-3 句话告诉用户你发现了什么,有什么存疑的点。**不需要正式的大纲确认环节**,直接写梗概,快速拿到反馈比完美大纲更重要。
## 3. 生成梗概
### 3.1 写作原则
**首次写作(默认模式)**
- **言简意赅**,建议控制在 300 字以内
- 只写最重要的骨架:是什么、为什么、怎么用
- 留白是刻意的,后续迭代会填充细节
- 不需要面面俱到,抓住核心价值
**迭代补充**(用户再次调用 `doc` 指向同一文件时):
- 读取现有内容,在此基础上增量补充
- 递增版本号,更新 `updated` 日期
- 每次迭代聚焦一个方面,不要一次补太多
### 3.2 文档头部
```markdown
---
title: {文档标题}
version: v1.0
created: {YYYY-MM-DD}
updated: {YYYY-MM-DD}
author: {作者署名}
---
```
### 3.3 内容要求
- **准确**:基于实际代码,不编造
- **精炼**:一句话能说清的不用两句
- **实用**:面向读者,提供可操作的信息
- 善用表格、代码块、ASCII 图示(但首次不强求)
## 4. 保存并输出
保存到用户指定路径。如果文件已存在,先询问是覆盖还是增量更新。
输出摘要:
```text
文档: {标题} | 版本: v1.0 | 路径: {path}
字数: ~{N}字(首版梗概)
后续可以通过 $doc 继续补充完善。
主人,用不用我沉淀 or git 提交?
```
## 工作流总览
```text
$doc <指令>
├── 1. 理解需求(简短确认主题、路径、署名)
├── 2. 快速调研(聚焦核心,不求全面)
├── 3. 生成梗概≤300字抓骨架
└── 4. 保存输出(鼓励后续迭代)
```
## 注意事项
- **少即是多**首版宁短勿长300 字是指导建议而非硬限制
- **鼓励迭代**:每次 `doc` 都是一次对话机会,文档在讨论中成长
- **不做代码改动**:本 skill 只生成文档
- **风格一致**:与项目已有文档风格保持一致

2
.gitignore vendored
View File

@ -1,5 +1,5 @@
# 文档目录(各项目自己生成)
doc/
/doc/
# 其他开发文件
write-skills/

View File

@ -21,6 +21,7 @@
- `mt`: 增量修改 tasks.md根据用户指令在现有内容基础上更新任务列表。 (file: `./.codex/skills/mt/SKILL.md`)
- `go`: 终极执行按钮,激进模式一口气完成开发任务,兼容 0->1 和 1->100 场景。 (file: `./.codex/skills/go/SKILL.md`)
- `iter`: 迭代变更入口,调研问题后更新 PRD.md 和 tasks.md支持 Bug 修复、功能迭代、技术重构。 (file: `./.codex/skills/iter/SKILL.md`)
- `doc`: 渐进式文档生成器。首次只写精炼梗概≤300字后续通过迭代不断完善。 (file: `./.codex/skills/doc/SKILL.md`)
- `update`: 收集用户反馈并更新最近使用的 skill。别名`up`。 (file: `./.codex/skills/up/SKILL.md`)
- `deploy`: Drone CI + 服务器 CD 全流程引导:从基础设施检查到生成配置文件到验证部署,交互式完成。 (file: `./.codex/skills/deploy/SKILL.md`)
- `changelog`: 一键发版:生成更新日志 → commit → 打 tag全流程自动化。 (file: `./.codex/skills/changelog/SKILL.md`)

View File

@ -25,6 +25,7 @@
- `mt`: 增量修改 tasks.md根据用户指令在现有内容基础上更新任务列表。 (file: `./.codex/skills/mt/SKILL.md`)
- `go`: 终极执行按钮,激进模式一口气完成开发任务,兼容 0->1 和 1->100 场景。 (file: `./.codex/skills/go/SKILL.md`)
- `iter`: 迭代变更入口,调研问题后更新 PRD.md 和 tasks.md支持 Bug 修复、功能迭代、技术重构。 (file: `./.codex/skills/iter/SKILL.md`)
- `doc`: 渐进式文档生成器。首次只写精炼梗概≤300字后续通过迭代不断完善。 (file: `./.codex/skills/doc/SKILL.md`)
- `update`: 收集用户反馈并更新最近使用的 skill。别名`up`。 (file: `./.codex/skills/up/SKILL.md`)
- `deploy`: Drone CI + 服务器 CD 全流程引导:从基础设施检查到生成配置文件到验证部署,交互式完成。 (file: `./.codex/skills/deploy/SKILL.md`)
- `changelog`: 一键发版:生成更新日志 → commit → 打 tag全流程自动化。 (file: `./.codex/skills/changelog/SKILL.md`)

View File

@ -44,6 +44,7 @@ RequirementsDoc ──▶ PRD ──▶ FeatureSummary ──▶ DevelopmentPlan
| | `mt` | `/mt` | `$mt` | 增量修改 tasks |
| **执行** | `go` | `/go` | `$go` | 🚀 发射按钮,激进模式一口气完成开发 |
| **辅助** | `iter` | `/iter` | `$iter` | 迭代变更入口Bug/功能/重构) |
| | `doc` | `/doc` | `$doc` | 渐进式文档生成器,先写梗概再迭代完善 |
| | `update` | `/up` | `$update``$up` | Skill 升级优化 |
| | `deploy` | `/deploy` | `$deploy` | Drone CI/CD 全流程部署引导 |
| | `changelog` | `/changelog` | `$changelog` | 一键发版(日志 + commit + tag |
@ -53,10 +54,13 @@ RequirementsDoc ──▶ PRD ──▶ FeatureSummary ──▶ DevelopmentPlan
一行命令搞定安装和更新。脚本会智能处理:新 skill 直接装,已有的对比更新,本地魔改自动备份。
```bash
# Codex默认
# Claude Code + Codex推荐
bash <(curl -sL https://git.internal.intelligrow.cn/zhangfucai/spec-coding-skills/raw/branch/main/install.sh) both
# Codex only
bash <(curl -sL https://git.internal.intelligrow.cn/zhangfucai/spec-coding-skills/raw/branch/main/install.sh) codex
# Claude Code
# Claude Code only
bash <(curl -sL https://git.internal.intelligrow.cn/zhangfucai/spec-coding-skills/raw/branch/main/install.sh) claude
```
@ -64,15 +68,22 @@ bash <(curl -sL https://git.internal.intelligrow.cn/zhangfucai/spec-coding-skill
```bash
curl -sL https://git.internal.intelligrow.cn/zhangfucai/spec-coding-skills/raw/branch/main/install.sh -o /tmp/install-skills.sh
bash /tmp/install-skills.sh codex
bash /tmp/install-skills.sh both
```
### 安装脚本行为
- `both` 模式:同时安装 `.codex/skills/``.claude/skills/`,并生成 `AGENTS.md` + `CLAUDE.md`
- `codex` 模式:安装到 `.codex/skills/`,并在项目根目录生成或更新 `AGENTS.md`
- `claude` 模式:安装到 `.claude/skills/`,并在项目根目录生成或更新 `CLAUDE.md`
- 如果传入自定义目标目录,脚本会优先安装 Codex 版 skills目标路径包含 `.claude/skills` 时自动切到 Claude 版
### 推荐用法
- 团队项目、模板仓库:用 `both`,一次安装双端,最省心
- 只有你自己在 Codex 里用:用 `codex`
- 仓库明确只服务 Claude Code`claude`
### 更新策略
| 情况 | 处理方式 |
@ -131,6 +142,7 @@ $go
请用 rr skill 评审 doc/RequirementsDoc.md
请用 wf skill 根据 PRD 生成 FeatureSummary
请用 go skill 按 doc/tasks.md 执行未完成任务
请用 doc skill 为认证模块写一份 300 字以内的使用说明
```
### 工作流总览

View File

@ -1,8 +1,8 @@
#!/usr/bin/env bash
# ============================================================
# spec-coding-skills 安装/更新脚本
# 用法: bash <(curl -sL <raw-url>/install.sh) [codex|claude]
# 或: bash install.sh [codex|claude|目标目录]
# 用法: bash <(curl -sL <raw-url>/install.sh) [codex|claude|both]
# 或: bash install.sh [codex|claude|both|目标目录]
# ============================================================
set -euo pipefail
@ -19,6 +19,11 @@ TARGET=""
SKILLS_SRC=""
GUIDE_SRC=""
GUIDE_DST=""
REQUEST="${1:-$DEFAULT_MODE}"
TOTAL_NEW=0
TOTAL_UPDATED=0
TOTAL_SKIPPED=0
INSTALLED_TARGETS=""
resolve_layout() {
local input="$1"
@ -38,6 +43,10 @@ resolve_layout() {
GUIDE_SRC="CLAUDE.md.template"
GUIDE_DST="CLAUDE.md"
;;
both)
log_warn "both 不是单一布局,请在主流程中单独处理"
exit 1
;;
*)
TARGET="$input"
case "$TARGET" in
@ -58,10 +67,92 @@ resolve_layout() {
esac
}
resolve_layout "${1:-$DEFAULT_MODE}"
TMP_DIR=$(mktemp -d)
trap "rm -rf $TMP_DIR" EXIT
sync_file() {
local src="$1"
local dst="$2"
local create_msg="$3"
local update_msg="$4"
if [ ! -f "$dst" ]; then
mkdir -p "$(dirname "$dst")"
cp "$src" "$dst"
log_info "$create_msg"
TOTAL_NEW=$((TOTAL_NEW + 1))
elif ! diff -q "$src" "$dst" >/dev/null 2>&1; then
cp "$dst" "$dst.local.bak"
cp "$src" "$dst"
log_warn "$update_msg"
TOTAL_UPDATED=$((TOTAL_UPDATED + 1))
else
TOTAL_SKIPPED=$((TOTAL_SKIPPED + 1))
fi
}
install_layout() {
local input="$1"
local skill_dir
local skill_name
local src_file
local dst_dir
local dst_file
local tpl_file
local tpl_name
local dst
local guide_src_path
resolve_layout "$input"
if [ ! -d "$TMP_DIR/$SKILLS_SRC" ]; then
log_warn "上游仓库中不存在技能目录: $SKILLS_SRC"
exit 1
fi
log_info "同步 $MODE: $TARGET"
mkdir -p "$TARGET"
for skill_dir in "$TMP_DIR/$SKILLS_SRC"/*/; do
[ -d "$skill_dir" ] || continue
skill_name=$(basename "$skill_dir")
src_file="$skill_dir/SKILL.md"
dst_dir="$TARGET/$skill_name"
dst_file="$dst_dir/SKILL.md"
[ -f "$src_file" ] || continue
sync_file \
"$src_file" \
"$dst_file" \
"✨ 新增: $skill_name ($MODE)" \
"🔄 更新: $skill_name ($MODE) (本地版本已备份为 SKILL.md.local.bak"
done
for tpl_file in "$TMP_DIR/$SKILLS_SRC"/*.template "$TMP_DIR/$SKILLS_SRC"/*.md; do
[ -f "$tpl_file" ] || continue
tpl_name=$(basename "$tpl_file")
dst="$TARGET/$tpl_name"
sync_file \
"$tpl_file" \
"$dst" \
"✨ 新增模板: $tpl_name ($MODE)" \
"🔄 更新模板: $tpl_name ($MODE) (本地版本已备份为 ${tpl_name}.local.bak"
done
guide_src_path="$TMP_DIR/$GUIDE_SRC"
if [ -f "$guide_src_path" ]; then
sync_file \
"$guide_src_path" \
"$GUIDE_DST" \
"✨ 新增项目引导: $GUIDE_DST" \
"🔄 更新项目引导: $GUIDE_DST (本地版本已备份为 ${GUIDE_DST}.local.bak"
fi
INSTALLED_TARGETS="${INSTALLED_TARGETS}${INSTALLED_TARGETS:+, }$TARGET"
}
# ---------- 拉取最新 ----------
log_title "📦 spec-coding-skills 安装/更新"
echo ""
@ -70,102 +161,35 @@ git clone --depth 1 --quiet "$REPO_URL" "$TMP_DIR"
VERSION=$(git -C "$TMP_DIR" describe --tags --always 2>/dev/null || git -C "$TMP_DIR" rev-parse --short HEAD)
log_info "版本: $VERSION"
log_info "模式: $MODE"
if [ ! -d "$TMP_DIR/$SKILLS_SRC" ]; then
log_warn "上游仓库中不存在技能目录: $SKILLS_SRC"
exit 1
fi
# ---------- 统计变更 ----------
NEW=0
UPDATED=0
SKIPPED=0
KEPT=0
mkdir -p "$TARGET"
# 遍历上游 skill 目录
for skill_dir in "$TMP_DIR/$SKILLS_SRC"/*/; do
[ -d "$skill_dir" ] || continue
skill_name=$(basename "$skill_dir")
src_file="$skill_dir/SKILL.md"
dst_dir="$TARGET/$skill_name"
dst_file="$dst_dir/SKILL.md"
[ -f "$src_file" ] || continue
if [ ! -f "$dst_file" ]; then
# 新 skill直接复制
mkdir -p "$dst_dir"
cp "$src_file" "$dst_file"
log_info "✨ 新增: $skill_name"
NEW=$((NEW + 1))
elif diff -q "$src_file" "$dst_file" >/dev/null 2>&1; then
# 内容一致,跳过
SKIPPED=$((SKIPPED + 1))
else
# 内容不同:上游有更新 或 用户本地修改过
# 策略:备份本地版本,写入上游新版本
cp "$dst_file" "$dst_file.local.bak"
cp "$src_file" "$dst_file"
log_warn "🔄 更新: $skill_name (本地版本已备份为 SKILL.md.local.bak"
UPDATED=$((UPDATED + 1))
fi
done
# 复制模板文件(非 skill 目录的文件)
for tpl_file in "$TMP_DIR/$SKILLS_SRC"/*.template "$TMP_DIR/$SKILLS_SRC"/*.md; do
[ -f "$tpl_file" ] || continue
tpl_name=$(basename "$tpl_file")
dst="$TARGET/$tpl_name"
if [ ! -f "$dst" ]; then
cp "$tpl_file" "$dst"
log_info "✨ 新增模板: $tpl_name"
NEW=$((NEW + 1))
elif ! diff -q "$tpl_file" "$dst" >/dev/null 2>&1; then
cp "$dst" "$dst.local.bak"
cp "$tpl_file" "$dst"
log_warn "🔄 更新模板: $tpl_name (本地版本已备份为 ${tpl_name}.local.bak"
UPDATED=$((UPDATED + 1))
else
SKIPPED=$((SKIPPED + 1))
fi
done
# 安装项目根目录引导文件
guide_src_path="$TMP_DIR/$GUIDE_SRC"
if [ -f "$guide_src_path" ]; then
if [ ! -f "$GUIDE_DST" ]; then
cp "$guide_src_path" "$GUIDE_DST"
log_info "✨ 新增项目引导: $GUIDE_DST"
NEW=$((NEW + 1))
elif ! diff -q "$guide_src_path" "$GUIDE_DST" >/dev/null 2>&1; then
cp "$GUIDE_DST" "$GUIDE_DST.local.bak"
cp "$guide_src_path" "$GUIDE_DST"
log_warn "🔄 更新项目引导: $GUIDE_DST (本地版本已备份为 ${GUIDE_DST}.local.bak"
UPDATED=$((UPDATED + 1))
else
SKIPPED=$((SKIPPED + 1))
fi
fi
case "$REQUEST" in
both)
log_info "模式: both"
install_layout codex
install_layout claude
;;
*)
resolve_layout "$REQUEST"
log_info "模式: $MODE"
install_layout "$REQUEST"
;;
esac
# ---------- 汇总 ----------
echo ""
log_title "✅ 完成!"
echo ""
echo " 🧭 模式: $MODE"
echo " 📁 目标目录: $TARGET"
echo " 🧭 模式: $REQUEST"
echo " 📁 目标目录: $INSTALLED_TARGETS"
echo " 📦 版本: $VERSION"
echo ""
echo " ✨ 新增: $NEW"
echo " 🔄 更新: $UPDATED(本地版本已备份为 .local.bak"
echo " ⏭️ 无变化: $SKIPPED"
echo " ✨ 新增: $TOTAL_NEW"
echo " 🔄 更新: $TOTAL_UPDATED(本地版本已备份为 .local.bak"
echo " ⏭️ 无变化: $TOTAL_SKIPPED"
echo ""
if [ "$UPDATED" -gt 0 ]; then
log_warn "$UPDATED 个文件被更新,本地修改已备份为 .local.bak"
if [ "$TOTAL_UPDATED" -gt 0 ]; then
log_warn "$TOTAL_UPDATED 个文件被更新,本地修改已备份为 .local.bak"
log_warn "如需恢复本地版本: mv SKILL.md.local.bak SKILL.md"
log_warn "如需对比差异: diff SKILL.md SKILL.md.local.bak"
fi