@kunlv/atdc 1.0.0

package/prompts/6-article.md

@@ -0,0 +1,571 @@
+# prompts/6-article · 技术分享文章生成
+
+从此文件读取后，直接开始执行，无需用户再次确认。
+
+> **触发方式**：`/atdc:article`、`/atd article`、`生成文章`、`写文章`
+
+---
+
+## Step 0：定位目标 change
+
+检测当前可用的 change：
+
+```bash
+# 优先活跃 change，其次最近归档
+ACTIVE=$(ls -t openspec/changes/ 2>/dev/null | grep -v archive | head -1)
+ARCHIVED=$(ls -t openspec/changes/archive/ 2>/dev/null | head -1)
+
+if [ -n "$ACTIVE" ]; then
+  CHANGE_NAME="$ACTIVE"
+  CHANGE_DIR="openspec/changes/$CHANGE_NAME"
+elif [ -n "$ARCHIVED" ]; then
+  CHANGE_NAME="$ARCHIVED"
+  CHANGE_DIR="openspec/changes/archive/$CHANGE_NAME"
+else
+  echo "ℹ️  未找到 openspec change，将从当前会话上下文提取素材。"
+  CHANGE_NAME="session-$(date +%Y%m%d-%H%M)"
+  CHANGE_DIR=""
+fi
+
+echo "TARGET_CHANGE=$CHANGE_NAME"
+echo "TARGET_DIR=$CHANGE_DIR"
+```
+
+- 多个 change → 列出让用户选择，默认取最近归档
+- 无 change → 不退出，直接从当前会话上下文提取素材继续（见 Step 0.5）
+- 被手动调用且带参数 → 以参数为主题，结合会话上下文生成
+
+---
+
+## Step 0.3：用户提供素材的优先处理（OCR 增强）
+
+> **触发条件**：用户调用 `/atdc:article` 时附带素材路径（如「素材在 /path/to/dir/」或「使用 /path/ 下面的图片」）。
+
+### 检测素材路径
+
+从用户输入中提取素材目录路径（如 `/Users/.../assets/xxx/`），执行：
+
+```bash
+ls -1 <素材目录>/ 2>/dev/null | head -30
+```
+
+若目录存在且包含文件 → 进入 OCR 处理；不存在 → 跳过，提示用户。
+
+### OCR 识别图片内容（强制）
+
+对素材目录中每个图片文件（`.png`、`.jpg`、`.jpeg`、`.gif`），运行 tesseract OCR 提取文字：
+
+```bash
+# 检查 tesseract 可用性
+which tesseract || brew install tesseract tesseract-lang
+
+# 批量 OCR（中文优先，英文回退）
+for f in $(ls <素材目录>/*.png <素材目录>/*.jpg 2>/dev/null | sort -V); do
+  echo "=== $(basename $f) ==="
+  tesseract "$f" stdout -l chi_sim 2>/dev/null | head -15
+  echo ""
+done
+```
+
+> 若 tesseract 中文识别率低，追加 `-l chi_sim+eng` 或仅用 `-l eng` 回退。
+
+### OCR 结果用途
+
+将 OCR 提取的文字内容用于：
+
+1. **识别截图主题**：判断每张截图属于 atdc 的哪个阶段（1-spec / 2-qa / 3-impl / 4-verify / 5-done）
+2. **补充文章上下文**：OCR 文字作为会话历史的补充证据，丰富 Phase A 素材
+3. **确定插图位置**：按阶段归类后，在文章对应章节插入 `![[素材目录/xxx.png]]`
+
+### 素材优先级
+
+| 优先级 | 来源 | 用途 |
+|--------|------|------|
+| 1（最高） | 用户提供的截图 OCR 内容 | 还原实际操作过程，截图直接插入文章 |
+| 2 | proposal.md + design.md + spec.md | 技术方案与决策 |
+| 3 | git diff | 代码示例 |
+| 4（最低） | auto-generated diagrams | 架构图、流程图辅助说明 |
+
+> **规则**：用户提供的素材截图 MUST 插入到文章对应阶段。若有阶段无对应截图，才使用 auto-generated diagram 补位。不得因图片无法直接查看而跳过用户素材。
+
+---
+
+## Step 0.5：无 change 时从会话提取素材
+
+当 Step 0 未找到任何 change 时，从当前会话上下文提取文章素材：
+
+### 提取内容
+
+回顾当前会话的历史消息，提取以下信息：
+
+1. **主题**：本次会话讨论的核心技术主题是什么？（功能实现、架构设计、bug 修复、工具优化）
+2. **背景**：为什么要做这件事？解决了什么问题？
+3. **关键决策**：过程中做了哪些技术选择？排除了什么方案？
+4. **实现要点**：最核心的实现逻辑或架构设计是什么？
+5. **代码/配置**：会话中创建或修改了哪些关键文件？提供了哪些代码片段？
+
+### 替代 Phase A 数据
+
+提取结果替代 Phase A 的 proposal.md / design.md / git diff：
+
+```
+Phase A 数据来源：当前会话上下文（无 openspec change）
+- 主题：<一句话>
+- 背景：<2-3 句>
+- 关键决策：<列表>
+- 实现要点：<文件清单 + 核心逻辑>
+```
+
+> 从会话提取的代码片段也必须遵守「代码来源不得编造」约束：只能使用会话中实际出现过的代码。
+
+---
+
+## Phase A：上下文采集
+
+### A1. 读取需求与技术文档
+
+从 change 目录采集背景和技术方案：
+
+- `$TARGET_DIR/proposal.md`：需求背景、目标、技术方案、排除方案
+- `$TARGET_DIR/design.md`：模块划分、接口定义、数据流、ADR
+
+若 `design.md` 不存在 → 仅用 `proposal.md` + git diff，提示用户。
+若两者均不存在 → 仅用 git diff，提示用户。
+两者均无且 git diff 也为空 → 退出。
+
+### A2. 提取代码变更
+
+```bash
+git diff origin/main..HEAD 2>/dev/null || git diff HEAD~1..HEAD 2>/dev/null || git diff --cached 2>/dev/null
+```
+
+- diff 为空 → 退出
+- diff 超过 3000 行 → 裁剪策略：① proposal.md 声明的涉及文件 ② 行数最多的非测试文件 ③ 排除测试文件和注释变更
+
+### A3. 识别文章元数据
+
+从 proposal.md 提取：
+
+- **标题**：从 `# change:` 或 `## 背景与目标` 提取主题
+- **标签(tags)**：从 change 名、涉及模块、技术栈关键词提取，3-6 个
+- **难度(difficulty)**：默认 `"easy"`。若涉及跨层改动、并发、分布式等 → `"medium"` 或 `"hard"`
+- **模块(module)**：从 proposal.md "实施范围 → 涉及模块" 提取第一个模块名
+
+---
+
+## Phase A.5：标题确认（暂停等用户选择）
+
+> **强制要求**：进入 Phase B 之前，必须先生成 3-5 个标题候选，等用户选定后再继续。
+
+### 生成标题候选
+
+基于 Phase A 采集的 proposal + design + git diff 内容，生成 3-5 个标题候选。
+每个标题从不同角度切入：
+
+| 角度 | 格式示例 | 适用场景 |
+|------|---------|---------|
+| 问题驱动 | 《解决 <问题>：<方案> 实现笔记》 | bug fix、性能优化 |
+| 技术叙事 | 《<技术主题> — 实现笔记》 | 新功能、架构变更 |
+| 结果导向 | 《从 <旧状态> 到 <新状态>：<做了什么>》 | 重构、迁移 |
+| 设计决策 | 《<N> 个关键决策：<主题> 的设计思路》 | 架构设计、技术选型 |
+| 对比分析 | 《<方案A> vs <方案B>：<主题> 落地实录》 | 多方案对比 |
+
+要求：
+- 每个标题 ≤ 30 字
+- 不重复同一角度
+- 不出现"颠覆性"、"革命性"、"极致"等炒作词
+- 必须体现本次 change 的具体内容，不能用泛化标题
+
+### 标题推荐
+
+从候选中标记一个推荐标题（标记 `★`），基于以下优先级：
+1. 最准确概括 change 核心内容
+2. 对目标读者（同行工程师）最有吸引力
+3. 信息密度最高（标题本身透露了 what + why）
+
+### 输出格式
+
+```
+📝 请选择文章标题（输入序号）：
+
+1. [★ 推荐] <标题1>
+   角度：<问题驱动/技术叙事/...>
+
+2. <标题2>
+   角度：<...>
+
+3. <标题3>
+   角度：<...>
+
+4. <标题4>
+   角度：<...>
+
+5. <标题5>
+   角度：<...>
+
+💡 选 1 直接回车，或输入序号/自定义标题。
+```
+
+### 等待用户选择
+
+- 用户输入序号 → 使用对应标题
+- 用户输入自定义文本 → 使用用户提供的标题
+- 用户直接回车（空输入）→ 使用推荐标题（★）
+- **收到选择后才继续 Phase B，不得跳过等待**
+
+---
+
+## Phase B：图表规划与生成
+
+> **强制要求**：每篇文章必须包含至少 1 张技术图表。图表不得有乱码。
+
+### B1. 识别图表需求
+
+> **用户素材优先**：如果 Step 0.3 检测到用户提供了截图素材，用户截图 MUST 优先作为配图使用。auto-generated diagram 仅在以下情况使用：(a) 用户未提供素材；(b) 用户素材无法覆盖的阶段需要补位图表。
+
+从 Phase A 采集的内容中识别适合做图的额外需求（补充用户已有素材的不足）：
+
+| 内容特征 | 图表类型 | 示例 |
+|---------|---------|------|
+| 模块划分 + 依赖关系 | 架构图（architecture） | `fireworks-tech-graph` 模板 `architecture` |
+| 数据流转步骤 | 数据流图（data-flow） | 箭头标注数据类型 |
+| 调用链 / 请求链路 | 时序图（sequence） | 参与者 lifeline + 消息箭头 |
+| 工作流 / 状态变更 | 流程图（flowchart） | 菱形决策 + 矩形处理 |
+| 多方案对比 | 对比表（comparison） | 行=方案、列=维度 |
+| Agent 决策链路 | Agent 架构图 | 输入→推理→工具→输出 |
+
+**最少 1 张，推荐 2-3 张。**
+
+### B2. 生成 SVG 图表
+
+使用 `fireworks-tech-graph` skill 生成 SVG 图表。
+
+**布局规则（必须遵守，否则图表会重叠模糊）：**
+
+| 规则 | 约束 |
+|------|------|
+| 节点数上限 | 单张图 ≤ **15 个节点**（超过则拆分为多张图） |
+| 节点间距 | 水平 ≥ 40px，垂直行间距 ≥ 50px（边缘到边缘） |
+| 标签长度 | 每行 ≤ 12 个中文字（或 20 个英文字符），超出则换行 |
+| 多行文本 | **禁止**在 SVG `<text>` 中嵌入 `\n`。每行必须是独立的 `<text>` 元素，y 坐标递增 `font-size + 4px` |
+| viewBox 高度 | **必须根据节点实际位置计算**，不可硬编码 700。公式：`max(最底节点 bottom) + 40px`，向上取整到 8 的倍数 |
+| 标题位置 | y=40–48，居中，26px 字号。y=0–70 为标题保留区，不得有任何节点 |
+| 箭头数量 | ≤ 节点数 × 1.5（太多箭头必然交叉） |
+| 图层数 | ≤ 4 层（垂直方向），超过则换架构图 |
+| 字体 | 中文必须声明 `'PingFang SC', 'Microsoft YaHei'` |
+| Legend | 放在左下角或右下角，不与任何节点重叠 |
+
+**生成方法**：必须使用 Python list 逐行拼接（`generate-from-template.py` 生成的 `\n` 内嵌文字不换行），然后逐个 `<text>` 写多行标签。
+
+```python
+python3 << 'PYEOF'
+lines = []
+lines.append('<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 960 500" ...>')
+# title at y=40
+lines.append('<text x="480" y="40" text-anchor="middle" class="title">图表标题</text>')
+# node with multiline text — separate <text> per line
+lines.append('<rect x="40" y="120" width="160" height="80" rx="10" .../>')
+lines.append('<text x="120" y="145" text-anchor="middle" class="node-label">主标题</text>')
+lines.append('<text x="120" y="162" text-anchor="middle" class="node-sub">副标题行1</text>')
+lines.append('<text x="120" y="179" text-anchor="middle" class="node-sub">副标题行2</text>')
+lines.append('</svg>')
+with open('output.svg', 'w') as f: f.write('\n'.join(lines))
+PYEOF
+```
+
+每张图生成后验证 XML 语法：
+
+```bash
+python3 -c "import xml.etree.ElementTree as ET; ET.parse('<output-path.svg>')" && echo "✓ valid"
+```
+
+**布局计算——先算高度再写 viewBox**：
+1. 横向：节点均匀排列，间距 40px
+2. 纵向：row0(y=80-140), row1(y=190-270), row2(y=340-420) → height = 420+40 = 460
+3. 填入 viewBox 时用计算值，不是 700
+
+### B3. 导出 PNG（禁止乱码）
+
+> **关键约束**：必须使用 Puppeteer（headless Chrome）导出 PNG，禁止使用 `cairosvg` 和 `rsvg-convert`。
+> 原因：cairosvg 基于 Cairo，不渲染 CJK 字符；rsvg-convert 在 macOS 下 fontconfig 不稳定，中文会变成方框。
+> 唯一可靠方案是 Puppeteer（Chrome 引擎），字体回退机制与浏览器一致。
+
+```bash
+# 一键导出目录下所有 SVG → PNG（2x 分辨率）
+node ~/atdc/scripts/svg2png.js <assets-dir>
+```
+
+> 依赖：`~/atdc/node_modules/puppeteer`（已在 install.sh 中安装）。
+> 若报错 `Cannot find module 'puppeteer'`，执行：`cd ~/atdc && npm install puppeteer`
+
+### B4. 布局验证
+
+导出后运行重叠检测，确保无文字被遮挡：
+
+```bash
+python3 << 'EOF'
+import xml.etree.ElementTree as ET
+
+tree = ET.parse('<output-path.svg>')
+root = tree.getroot()
+vb = root.get('viewBox', '0 0 960 700')
+parts = vb.split()
+vw, vh = float(parts[2]), float(parts[3])
+
+rects = []
+for elem in root.iter():
+    tag = elem.tag.split('}')[-1] if '}' in elem.tag else elem.tag
+    if tag not in ('rect', 'ellipse'):
+        continue
+    try:
+        if tag == 'rect':
+            x = float(elem.get('x', 0))
+            y = float(elem.get('y', 0))
+            w = float(elem.get('width', 0))
+            h = float(elem.get('height', 0))
+        else:
+            cx = float(elem.get('cx', 0))
+            cy = float(elem.get('cy', 0))
+            rx = float(elem.get('rx', 0))
+            ry = float(elem.get('ry', 0))
+            x, y, w, h = cx - rx, cy - ry, rx * 2, ry * 2
+    except (ValueError, TypeError):
+        continue
+    if w <= 0 or h <= 0 or w > vw * 0.8:
+        continue
+    fill = elem.get('fill', 'none')
+    if fill == 'none':
+        continue
+    rects.append({'x': x, 'y': y, 'w': w, 'h': h, 'r': x + w, 'b': y + h})
+
+issues = []
+for i in range(len(rects)):
+    for j in range(i+1, len(rects)):
+        r1, r2 = rects[i], rects[j]
+        ox = max(0, min(r1['r'], r2['r']) - max(r1['x'], r2['x']))
+        oy = max(0, min(r1['b'], r2['b']) - max(r1['y'], r2['y']))
+        if ox > 15 and oy > 15:
+            issues.append(f"重叠 {ox:.0f}x{oy:.0f}px")
+
+for r in rects:
+    if r['x'] < 3:
+        issues.append("节点贴左边缘")
+    if r['r'] > vw - 3:
+        issues.append(f"节点超出右边缘")
+    if r['b'] > vh - 20:
+        issues.append("节点超出底边缘")
+
+if issues:
+    print(f"❌ 布局问题 ({len(issues)}):")
+    for iss in issues[:5]:
+        print(f"  - {iss}")
+    print("请调整节点位置或减少节点数后重新生成")
+else:
+    print("✅ 布局正常")
+EOF
+```
+
+> PNG 内容验证由 Puppeteer Chrome 引擎保证（CJK 字体回退与浏览器一致）。
+
+### B5. 确定图片路径
+
+**用户素材**（Step 0.3 检测到的）：
+- 直接使用用户提供的路径，如 `![[素材目录/1.png]]`
+- Obsidian wikilink 中的路径相对于 `assets/`，即 `/Users/lvkun/Documents/Obsidian/Docs/assets/`
+
+**Auto-generated diagrams**（fireworks-tech-graph 生成的）：
+- 输出到 Obsidian assets 根目录：
+  ```
+  /Users/lvkun/Documents/Obsidian/Docs/assets/<change-name>-<diagram-label>.png
+  ```
+- 文章中引用使用 Obsidian wikilink 格式：`![[<change-name>-<diagram-label>.png]]`
+
+---
+
+## Phase C：初稿生成
+
+> **强制要求**：必须加载以下三个 skill，不得跳过、不得降级。
+> 任一 skill 加载失败 → 停止，提示用户安装后重试。
+
+### C1. 加载写作 skill（强制执行）
+
+按顺序加载三个 skill，每个加载后确认成功：
+
+```
+1. Skill("article-writing")     → 确认已加载
+2. Skill("chinese-content-writing-guideline") → 确认已加载
+3. Skill("humanizer-zh")        → 确认已加载
+```
+
+**任一加载失败 → 输出以下提示并停止：**
+
+```
+❌ 文章生成中止：skill 加载失败
+
+缺失的 skill：<skill-name>
+安装方式：npx skills add <skill-package>
+
+所有 skill 就绪后重新运行 /atdc:article。
+```
+
+### C2. 写作规范（内嵌硬约束，与 skill 并行生效）
+
+```
+你是一位资深技术写作者。基于以下上下文，写一篇图文结合的技术分享文章。
+
+## 硬性约束（违反任何一条 = 不合格）
+
+1. **图文结合**：每个主要章节必须配图。图片来自 Phase B 生成的 PNG，
+   文章中用 Obsidian wikilink 引用：`![[<图片名>.png]]`
+2. **代码先行**：每个技术点先给完整代码示例，再解释原理。代码块必须有语言标注。
+3. **代码来源**：所有代码示例 MUST 来自 Phase A 提供的 git diff，不得编造、不得简化、不得省略。
+   如果 diff 中没有某段代码，就不要展示该段代码，改用文字描述思路。
+4. **去炒作化**：禁止使用"颠覆性"、"革命性"、"重新定义"、"极致"、"完美"等空洞修饰词。
+5. **中文输出**：标题、正文、代码注释说明 MUST 为简体中文。代码变量名/函数名保持原样。
+
+## 文章结构
+
+### 1. 标题
+格式：`<技术主题> — 实现笔记`
+
+### 2. 背景（3-5 句）
+- 要解决什么问题
+- 为什么值得分享
+
+### 3. 核心实现（占全文 60%+）
+- 每个关键模块一个小节
+- 小节格式：配图 → `### <模块名>` → 代码块 → 解释
+- 代码块后紧跟 2-4 句解释：这段代码做什么、为什么这样写
+- 配图放在小节标题之前或紧随其后
+
+### 4. 关键决策（3-5 个要点）
+- 选择了什么方案、为什么
+- 排除了什么方案、为什么不选
+
+### 5. 总结（2-3 句）
+- 一句话回顾做了什么
+- 一句话可改进方向（如有）
+
+## 上下文
+
+### 需求背景
+<proposal.md 内容>
+
+### 技术设计
+<design.md 内容或 [无 design.md]>
+
+### 代码变更
+<git diff 输出>
+
+### 配图清单
+<Phase B 生成的图片路径列表，含 wikilink>
+```
+
+### C3. 生成初稿
+
+将上下文填充到 C2 模板中，生成初稿。约束：
+- **图文结合**：每个主要章节配一张图，图片放在章节开头
+- 不提前透露"这是一个模板"
+- 初稿即最终结构，后续只做格式规范化和润色
+- 若 git diff 中无可展示的代码（如纯配置变更）→ 代码块替换为配置示例或关键参数说明
+
+---
+
+## Phase D：规范与润色
+
+> **强制要求**：Phase C 已加载的 chinese-content-writing-guideline 和 humanizer-zh skill 在此阶段生效。
+
+### D1. 中文排版规范
+
+对初稿执行以下排版检查（chinese-content-writing-guideline skill 规则）：
+
+- 全角标点（，。！？；：""）
+- 中英文之间插入空格（`使用 Node.js 构建`）
+- 数字与中文之间插入空格
+- 统一术语格式
+- 破折号检查：全文最多 2 个 `——`
+
+### D2. 去 AI 味润色
+
+对 D1 输出执行 humanizer-zh skill 规则（模式 `学术`）：
+
+- 删除"首先...其次...最后..."等机械过渡词
+- 删除"综上所述"、"值得注意的是"等模板句式
+- 删除否定式排比（"不仅是...更是..."）
+- 删除三段式列举（强行凑三个点）
+- 确保句式长短交替，避免连续 3 句以上相同结构
+- 质量检查：对照 humanizer-zh 的 24 条检查清单逐项扫描
+
+### D3. 图片引用验证
+
+确认文章中每个 `![[...]]` 引用的图片文件确实存在：
+
+```bash
+# 提取文章中所有图片引用，逐个验证
+# 支持子目录路径，如 ![[预约详情/1.png]]
+ASSETS="/Users/lvkun/Documents/Obsidian/Docs/assets"
+grep -oP '!\[\[.*?\]\]' <article-path> | sed 's/!\[\[//;s/\]\]//' | while read img; do
+  ls "$ASSETS/$img" 2>/dev/null && echo "✓ $img" || echo "❌ MISSING: $img"
+done
+```
+
+> **用户素材优先检查**：若 Step 0.3 检测到用户素材目录，验证该目录下被引用的图片是否存在。缺失的截图需提示用户确认路径。
+
+有缺失 → 回到 Phase B 补生成。用户素材缺失 → 不可跳过，必须等用户确认路径后再继续。
+
+---
+
+## Phase E：发布到 Obsidian
+
+### E1. 组装 frontmatter
+
+```yaml
+---
+title: "<从 Phase A3 提取>"
+date: "<当前日期 YYYY-MM-DD>"
+tags: [<从 Phase A3 提取的标签列表>]
+difficulty: "<从 Phase A3 提取>"
+module: "<从 Phase A3 提取>"
+---
+```
+
+### E2. 写入文件
+
+目标路径：`/Users/lvkun/Documents/Obsidian/Docs/ai-tools/<change-name>-技术分享.md`
+
+- 路径不存在 → 创建目录后写入
+- 同名文件已存在 → 询问：覆盖 / 追加时间戳 / 跳过
+
+### E3. 最终质量检查
+
+逐项确认后输出报告：
+
+```
+✅ 技术分享文章已生成
+
+📄 /Users/lvkun/Documents/Obsidian/Docs/ai-tools/<change-name>-技术分享.md
+
+📋 元数据：
+  - 标题: <title>
+  - 标签: <tags>
+  - 难度: <difficulty>
+  - 字数: ~<N> 汉字
+
+🖼️ 配图（<N> 张）：
+  - 用户素材：<N> 张（OCR 识别 <N> 张有效）
+  - auto-generated：<N> 张
+  - assets/<image1>.png  ✓
+  - assets/<image2>.png  ✓
+
+✅ 强制 skill 检查：
+  - article-writing            ✓ 已加载
+  - chinese-content-writing-guideline  ✓ 已加载
+  - humanizer-zh               ✓ 已加载
+
+✅ 质量检查：
+  - 破折号: <N>/2
+  - 图片引用完整: ✓
+  - 中文排版: ✓
+
+💡 建议在 Obsidian 中打开确认排版和图片渲染后再发布。
+```

package/prompts/X-add-command.md

@@ -0,0 +1,60 @@
+# prompts/X-add-command · 新增 atdc 命令
+
+横向命令，任意时刻可触发：`/atdc:add-command <name> <描述> <触发词>`
+
+---
+
+## 执行步骤
+
+### 1. 确定参数
+
+从用户输入中提取 3 个必填参数：
+- **name**：命令名（kebab-case，如 `my-cmd`）
+- **desc**：命令描述（如 `"我的工具"`）
+- **triggers**：触发词（逗号分隔，如 `"my-cmd、我的工具、/atdc:my-cmd"`）
+
+可选：
+- `--short`：简短描述（默认取 desc 前 30 字）
+
+### 2. 执行生成脚本
+
+```bash
+python3 ~/atdc/bin/add-command.py <name> "<desc>" "<triggers>" --short "<short_desc>"
+```
+
+脚本自动完成：
+- ✅ 4 端命令文件（OpenCode / Claude / Codex / Cursor）
+- ✅ prompts/X-<name>.md 模板
+- ✅ install.sh 注册
+- ✅ ~/.agents/skills/ 符号链接
+
+### 3. 运行 install.sh
+
+```bash
+bash ~/atdc/install.sh
+```
+
+### 4. 验证
+
+```bash
+# 确认 Cursor 版本无 $ARGUMENTS
+grep '$ARGUMENTS' ~/atdc/commands/cursor/atd-<name>/SKILL.md && echo "❌" || echo "✅"
+
+# 确认符号链接
+ls ~/.agents/skills/atd-<name>
+```
+
+### 5. 补充 prompt 内容
+
+根据命令功能，填写 `prompts/X-<name>.md` 的完整执行指令。
+
+---
+
+## 示例
+
+```bash
+# 用户说：新增一个 /atdc:export-csv 命令，用于导出 CSV
+# AI 执行：
+python3 ~/atdc/bin/add-command.py export-csv "导出数据为CSV" "export-csv、导出CSV、/atdc:export-csv" --short "导出CSV"
+bash ~/atdc/install.sh
+```