文档只能维护skill
This commit is contained in:
ZxR
parent
84e3a37daa
commit
acb87cb1a0
|
|
@ -0,0 +1,76 @@
|
|||
# 新需求构思报告：文档智能维护 Skill
|
||||
|
||||
**Skill 名称：** gitlink-docs-assistant
|
||||
**作者：** ZxR
|
||||
**日期：** 2026-06-15
|
||||
|
||||
---
|
||||
|
||||
## 1. 背景与痛点
|
||||
|
||||
开源项目中存在普遍的"文档漂移"问题：代码迭代频繁，而项目文档（CONTRIBUTING、CHANGELOG、API 说明等）往往缺失或长期无人维护。具体表现为：
|
||||
|
||||
- 新贡献者找不到 CONTRIBUTING，不知道如何参与
|
||||
- 没有 CHANGELOG，用户无法了解版本变更
|
||||
- API 文档缺失，使用者只能读源码
|
||||
- Maintainer 无法快速判断仓库文档是否完整
|
||||
|
||||
以 ylly/gitlink-cli 为例：实验一新增了 wiki、label、notification 三个模块共 13 个命令，但仓库 Wiki 中无对应文档，CONTRIBUTING 和 CHANGELOG 均缺失。
|
||||
|
||||
---
|
||||
|
||||
## 2. 需求定义
|
||||
|
||||
### 核心问题
|
||||
|
||||
> 如何让 AI Agent 自动扫描仓库文档状态，识别缺失项，并读取代码自动生成缺失文档写入 Wiki？
|
||||
|
||||
### 用户需求
|
||||
|
||||
| 角色 | 需求 |
|
||||
|------|------|
|
||||
| 项目 Maintainer | 一键获得"文档体检报告"，知道哪些文档缺失 |
|
||||
| 开发者 | 新增功能后，AI 自动补全对应 Wiki 文档，无需手动写 |
|
||||
| 新贡献者 | CONTRIBUTING 始终存在且有效，快速了解如何参与 |
|
||||
|
||||
---
|
||||
|
||||
## 3. 方案设计
|
||||
|
||||
### 设计原则
|
||||
|
||||
1. **先体检后补全**：只读模式生成报告，用户确认后再执行写入
|
||||
2. **读代码生成文档**：AI 读取 README 和目录结构，生成符合项目实际的文档（非通用模板）
|
||||
3. **复用实验一成果**：直接调用实验一开发的 `wiki +create/+update` shortcuts
|
||||
|
||||
### 复用命令
|
||||
|
||||
| 命令 | 来源 | 用途 |
|
||||
|------|------|------|
|
||||
| `gitlink-cli repo +info` | 原有 shortcut | 获取仓库基本信息 |
|
||||
| `gitlink-cli api GET /:owner/:repo/sub_entries` | Raw API | 扫描根目录文件 |
|
||||
| `gitlink-cli api GET /:owner/:repo/readme` | Raw API | 读取 README 作为文档素材 |
|
||||
| `gitlink-cli wiki +list` | **实验一新增** | 列出现有 Wiki 页面 |
|
||||
| `gitlink-cli wiki +view` | **实验一新增** | 读取页面内容 |
|
||||
| `gitlink-cli wiki +create` | **实验一新增** | 创建缺失文档 |
|
||||
| `gitlink-cli wiki +update` | **实验一新增** | 更新过时文档 |
|
||||
|
||||
### 原创性说明
|
||||
|
||||
与任务书中列出的场景对比：
|
||||
|
||||
| 已有场景 | gitlink-docs-assistant 的差异 |
|
||||
|---------|------------------------------|
|
||||
| 智能代码审查（PR diff → Review 评论） | 本 Skill 输出写入 Wiki，不是 PR 评论 |
|
||||
| Release Notes 生成（commit → 版本说明） | 本 Skill 面向持续文档维护，不是一次性发布 |
|
||||
| 项目健康度报告（统计指标） | 本 Skill 聚焦文档覆盖度并闭环修复，产生实际写入 |
|
||||
|
||||
**核心原创点：** 将"文档完整性体检"与"AI 自动生成文档写入 Wiki"串成完整闭环，复用实验一 wiki shortcuts，是现有 Skills 中未覆盖的场景。
|
||||
|
||||
---
|
||||
|
||||
## 4. 预期价值
|
||||
|
||||
- 新仓库 5 分钟完成文档初始化，不再依赖人工
|
||||
- 文档覆盖度可量化，可纳入项目健康度指标（与 gitlink-insight 联动）
|
||||
- 充分展示实验一 wiki 模块的实用价值
|
||||
|
|
@ -0,0 +1,168 @@
|
|||
# 变更影响分析及测试报告：gitlink-docs-assistant
|
||||
|
||||
**Skill 名称：** gitlink-docs-assistant
|
||||
**作者：** ZxR
|
||||
**日期：** 2026-06-15
|
||||
**验证平台：** Claude Code
|
||||
|
||||
---
|
||||
|
||||
## 1. 变更影响分析
|
||||
|
||||
### 新增文件清单
|
||||
|
||||
| 文件路径 | 类型 | 说明 |
|
||||
|---------|------|------|
|
||||
| `skills/gitlink-docs-assistant/SKILL.md` | 新增 | Skill 核心定义 |
|
||||
| `skills/gitlink-docs-assistant/examples/docs-assistant-workflow.md` | 新增 | 使用示例 |
|
||||
| `skills/gitlink-docs-assistant/examples/verification.md` | 新增 | Claude Code 验证记录 |
|
||||
| `docs/docs-assistant-design-report.md` | 新增 | 新需求构思报告 |
|
||||
| `docs/docs-assistant-test-report.md` | 新增 | 本文件 |
|
||||
|
||||
### 对现有系统的影响
|
||||
|
||||
| 影响范围 | 评估 | 说明 |
|
||||
|---------|------|------|
|
||||
| 现有 Skills | ✅ 无影响 | 纯新增，无修改现有文件 |
|
||||
| gitlink-cli 命令行工具 | ✅ 无影响 | 只调用现有 shortcuts，无代码改动 |
|
||||
| `skills/README.md` | ✅ 已更新 | 新增 gitlink-docs-assistant 条目 |
|
||||
|
||||
**结论：纯 Markdown + CLI 调用方案，不涉及 Go 代码改动，对现有功能零风险。**
|
||||
|
||||
---
|
||||
|
||||
## 2. 测试用例
|
||||
|
||||
### 2.1 只读场景测试
|
||||
|
||||
#### TC-01：获取仓库信息
|
||||
|
||||
```bash
|
||||
gitlink-cli repo +info --owner ylly --repo gitlink-cli --format json
|
||||
```
|
||||
|
||||
| 项目 | 预期 | 结果 |
|
||||
|------|------|:----:|
|
||||
| 命令执行成功 | JSON 正常返回 | ✅ |
|
||||
| 含 `has_wiki` 字段 | 布尔值 | ✅ |
|
||||
|
||||
#### TC-02：扫描根目录文件
|
||||
|
||||
```bash
|
||||
gitlink-cli api GET /ylly/gitlink-cli/sub_entries --query 'filepath=&ref=master'
|
||||
```
|
||||
|
||||
| 项目 | 预期 | 结果 |
|
||||
|------|------|:----:|
|
||||
| 返回文件列表 | 含 README.md、LICENSE 等 | ✅ |
|
||||
| 可判断 CONTRIBUTING 是否存在 | 文件名匹配 | ✅ |
|
||||
|
||||
#### TC-03：列出 Wiki 页面
|
||||
|
||||
```bash
|
||||
gitlink-cli wiki +list --owner ylly --repo gitlink-cli --format json
|
||||
```
|
||||
|
||||
| 项目 | 预期 | 结果 |
|
||||
|------|------|:----:|
|
||||
| 返回页面列表 | JSON 数组 | ✅ |
|
||||
| 仓库无 Wiki 时 | 返回空，不报错 | ✅ |
|
||||
|
||||
#### TC-04：读取 Wiki 页面内容
|
||||
|
||||
```bash
|
||||
gitlink-cli wiki +view --owner ylly --repo gitlink-cli --name "HOME"
|
||||
```
|
||||
|
||||
| 项目 | 预期 | 结果 |
|
||||
|------|------|:----:|
|
||||
| 返回页面内容 | Markdown 文本 | ✅ |
|
||||
| 页面不存在时 | 报错提示，不崩溃 | ✅ |
|
||||
|
||||
---
|
||||
|
||||
### 2.2 写入场景测试
|
||||
|
||||
#### TC-05：创建 Wiki 页面
|
||||
|
||||
```bash
|
||||
gitlink-cli wiki +create \
|
||||
--owner ylly \
|
||||
--repo gitlink-cli \
|
||||
--name "测试页面-ZxR" \
|
||||
--content "# 测试" \
|
||||
--message "test: 验证 docs-assistant skill 创建功能"
|
||||
```
|
||||
|
||||
| 项目 | 预期 | 结果 |
|
||||
|------|------|:----:|
|
||||
| 创建成功 | 命令返回成功 | ✅ |
|
||||
| Wiki 页面实际存在 | `wiki +list` 中可见 | ✅ |
|
||||
| 重复创建 | 返回错误，不覆盖 | ✅ |
|
||||
|
||||
#### TC-06：更新 Wiki 页面
|
||||
|
||||
```bash
|
||||
gitlink-cli wiki +update \
|
||||
--owner ylly \
|
||||
--repo gitlink-cli \
|
||||
--name "测试页面-ZxR" \
|
||||
--content "# 测试（已更新）" \
|
||||
--message "test: 验证 docs-assistant skill 更新功能"
|
||||
```
|
||||
|
||||
| 项目 | 预期 | 结果 |
|
||||
|------|------|:----:|
|
||||
| 更新成功 | 命令返回成功 | ✅ |
|
||||
| 内容实际变更 | `wiki +view` 确认 | ✅ |
|
||||
|
||||
#### TC-07：清理测试页面
|
||||
|
||||
```bash
|
||||
gitlink-cli wiki +delete \
|
||||
--owner ylly \
|
||||
--repo gitlink-cli \
|
||||
--name "测试页面-ZxR"
|
||||
```
|
||||
|
||||
| 项目 | 预期 | 结果 |
|
||||
|------|------|:----:|
|
||||
| 调用成功 | 命令返回成功 | ✅ |
|
||||
| 已知平台限制 | 内容清空，页面保留（平台行为） | ⚠️ 已知 |
|
||||
|
||||
---
|
||||
|
||||
### 2.3 端到端工作流测试
|
||||
|
||||
#### TC-08：完整体检 + 自动补全流程
|
||||
|
||||
**Prompt：** "请阅读 skills/gitlink-docs-assistant/SKILL.md，帮我检查 ylly/gitlink-cli 文档完整性，缺失的帮我生成并写入 Wiki。"
|
||||
|
||||
| 步骤 | 执行命令 | 结果 |
|
||||
|------|---------|:----:|
|
||||
| 1. 获取仓库信息 | `repo +info` | ✅ |
|
||||
| 2. 扫描根目录 | `api GET /sub_entries` | ✅ |
|
||||
| 3. 列出 Wiki 页面 | `wiki +list` | ✅ |
|
||||
| 4. 输出体检报告 | AI 生成 Markdown 报告 | ✅ |
|
||||
| 5. 读取 README | `api GET /readme` | ✅ |
|
||||
| 6. 创建 CONTRIBUTING | `wiki +create --name "CONTRIBUTING"` | ✅ |
|
||||
| 7. 确认结果 | `wiki +list` 验证 | ✅ |
|
||||
|
||||
---
|
||||
|
||||
## 3. 边界情况
|
||||
|
||||
| 情况 | 处理方式 | 结果 |
|
||||
|------|---------|:----:|
|
||||
| 仓库未启用 Wiki | `wiki +list` 报错，提示用户在仓库设置中开启 | ✅ |
|
||||
| 页面名称重复 | `wiki +create` 报错，改用 `wiki +update` | ✅ |
|
||||
| `--content` 含特殊字符 | CLI 内部处理 base64 编码，无需用户干预 | ✅ |
|
||||
|
||||
---
|
||||
|
||||
## 4. 总结
|
||||
|
||||
- **测试用例总数：** 8
|
||||
- **全部通过：** 8 / 8（TC-07 为已知平台限制，非 Skill 问题）
|
||||
- **Agent 平台验证：** Claude Code ✅
|
||||
- **现有功能回归：** 无影响
|
||||
|
|
@ -140,6 +140,7 @@ skills/
|
|||
| **gitlink-ci** | CI/CD | `ci +builds`, `ci +logs` |
|
||||
| **gitlink-pm** | 项目管理 | 通过 Raw API 访问 |
|
||||
| **gitlink-workflow** | AI 工作流 | Issue 分类、PR Review、Release Notes |
|
||||
| **gitlink-docs-assistant** | 文档智能维护 ★ | `wiki +list/+create/+update/+view` |
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,184 @@
|
|||
---
|
||||
name: gitlink-docs-assistant
|
||||
version: 1.0.0
|
||||
description: "文档智能维护：扫描仓库检测缺失文档，AI 自动生成 CONTRIBUTING/CHANGELOG/API 文档并写入 Wiki，同步更新过时内容。当用户需要检查文档完整性或自动补全文档时触发。"
|
||||
metadata:
|
||||
requires:
|
||||
bins: ["gitlink-cli"]
|
||||
cliHelp: "gitlink-cli wiki --help"
|
||||
---
|
||||
|
||||
# gitlink-docs-assistant（文档智能维护）
|
||||
|
||||
**CRITICAL — 开始前必须先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md)，其中包含认证、权限处理和 API 注意事项。**
|
||||
**CRITICAL — 所有写入/删除操作前，务必先确认用户意图。**
|
||||
**CRITICAL — GitLink 操作只能用 `gitlink-cli`。禁止用 `gh`（GitHub CLI）操作 GitLink 资源。**
|
||||
|
||||
> **前置条件：** 先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md) 了解认证和全局参数。
|
||||
|
||||
---
|
||||
|
||||
## 工作流概览
|
||||
|
||||
| 工作流 | 操作 | AI Agent 角色 | 写入 |
|
||||
|--------|------|--------------|:----:|
|
||||
| 工作流 1：文档完整性体检 | 扫描仓库根目录 + Wiki 页面，生成体检报告 | 判断缺失项并评级 | 否 |
|
||||
| 工作流 2：AI 自动补全文档 | 读取代码/README → 生成缺失文档 → 写入 Wiki | 生成文档内容 | 是 |
|
||||
| 工作流 3：文档同步更新 | 检测 Wiki 过时内容 → AI 更新 → 提交 | 对比代码与文档差距 | 是 |
|
||||
|
||||
---
|
||||
|
||||
## 文档体检清单
|
||||
|
||||
| 检查项 | 标准 | 严重程度 |
|
||||
|--------|------|:--------:|
|
||||
| README | 存在且包含安装/使用说明 | 🔴 必须 |
|
||||
| CONTRIBUTING | 贡献指南 | 🟡 重要 |
|
||||
| CHANGELOG | 变更记录 | 🟡 重要 |
|
||||
| API 文档 | 接口说明 | 🟡 重要 |
|
||||
| LICENSE | 许可证 | 🔴 必须 |
|
||||
| 代码规范文档 | 开发规范 | 🔵 可选 |
|
||||
|
||||
---
|
||||
|
||||
## 工作流 1：文档完整性体检（只读）
|
||||
|
||||
**触发场景：** "帮我检查一下这个仓库的文档完整性"
|
||||
|
||||
### Step 1：获取仓库基本信息
|
||||
|
||||
```bash
|
||||
gitlink-cli repo +info --owner <owner> --repo <repo> --format json
|
||||
```
|
||||
|
||||
### Step 2：扫描仓库根目录文件
|
||||
|
||||
```bash
|
||||
# 获取根目录文件列表，检查 README/CONTRIBUTING/LICENSE/CHANGELOG 是否存在
|
||||
gitlink-cli api GET /:owner/:repo/sub_entries --query 'filepath=&ref=master'
|
||||
```
|
||||
|
||||
### Step 3：列出已有 Wiki 页面
|
||||
|
||||
```bash
|
||||
gitlink-cli wiki +list --owner <owner> --repo <repo> --format json
|
||||
```
|
||||
|
||||
### Step 4：输出体检报告
|
||||
|
||||
AI 汇总以上数据，按清单逐项判断，输出：
|
||||
|
||||
```markdown
|
||||
## 📋 文档体检报告 — <owner>/<repo>
|
||||
|
||||
📅 检查时间：<YYYY-MM-DD>
|
||||
|
||||
### 总体评级：<🔴 需立即处理 / 🟡 待完善 / 🟢 健康>
|
||||
|
||||
| 检查项 | 状态 | 位置 | 建议 |
|
||||
|--------|:----:|------|------|
|
||||
| README | ✅ 存在 | 根目录 | — |
|
||||
| CONTRIBUTING | ❌ 缺失 | — | 建议创建 Wiki 页面 |
|
||||
| CHANGELOG | ❌ 缺失 | — | 建议创建 Wiki 页面 |
|
||||
| API 文档 | ❌ 缺失 | — | 建议创建 Wiki 页面 |
|
||||
| LICENSE | ✅ 存在 | 根目录 | — |
|
||||
| 代码规范文档 | ⚠️ 未找到 | — | 可选补充 |
|
||||
|
||||
### 🎯 建议优先补充
|
||||
1. 🔴 CONTRIBUTING —— 降低新贡献者入门门槛
|
||||
2. 🟡 CHANGELOG —— 方便用户了解版本变更
|
||||
3. 🟡 API 文档 —— 说明对外接口和参数
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 工作流 2：AI 自动补全文档
|
||||
|
||||
**触发场景：** "帮我自动生成缺失的 CONTRIBUTING 文档"
|
||||
|
||||
### Step 1：读取现有内容作为素材
|
||||
|
||||
```bash
|
||||
# 读取 README（了解项目背景）
|
||||
gitlink-cli api GET /:owner/:repo/readme
|
||||
|
||||
# 读取项目根目录结构
|
||||
gitlink-cli api GET /:owner/:repo/sub_entries --query 'filepath=&ref=master'
|
||||
```
|
||||
|
||||
### Step 2：AI 生成文档内容
|
||||
|
||||
根据仓库类型、README 内容、目录结构，生成对应文档的 Markdown 内容。
|
||||
|
||||
### Step 3：写入 Wiki
|
||||
|
||||
```bash
|
||||
# 创建新 Wiki 页面（内容由 AI 生成）
|
||||
gitlink-cli wiki +create \
|
||||
--owner <owner> \
|
||||
--repo <repo> \
|
||||
--name "CONTRIBUTING" \
|
||||
--content "# 贡献指南\n\n..." \
|
||||
--message "docs: AI 自动生成 CONTRIBUTING 文档"
|
||||
|
||||
# 同样方式创建 CHANGELOG、API 文档等
|
||||
gitlink-cli wiki +create \
|
||||
--owner <owner> \
|
||||
--repo <repo> \
|
||||
--name "CHANGELOG" \
|
||||
--content "# 变更记录\n\n..." \
|
||||
--message "docs: AI 自动生成 CHANGELOG"
|
||||
```
|
||||
|
||||
### Step 4：验证创建结果
|
||||
|
||||
```bash
|
||||
gitlink-cli wiki +list --owner <owner> --repo <repo> --format json
|
||||
gitlink-cli wiki +view --owner <owner> --repo <repo> --name "CONTRIBUTING"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 工作流 3：文档同步更新
|
||||
|
||||
**触发场景：** "帮我检查 Wiki 文档是否和最新代码一致，过时的帮我更新"
|
||||
|
||||
### Step 1：获取近期代码变更
|
||||
|
||||
```bash
|
||||
gitlink-cli api GET /:owner/:repo/commits --query 'page=1&limit=20'
|
||||
```
|
||||
|
||||
### Step 2：读取相关 Wiki 页面
|
||||
|
||||
```bash
|
||||
# 列出所有页面
|
||||
gitlink-cli wiki +list --owner <owner> --repo <repo> --format json
|
||||
|
||||
# 读取具体页面内容
|
||||
gitlink-cli wiki +view --owner <owner> --repo <repo> --name "API 文档"
|
||||
```
|
||||
|
||||
### Step 3：AI 分析差距并生成更新内容
|
||||
|
||||
对比 commit 描述（尤其是 `feat:` / `fix:` 类型）与 Wiki 页面内容，找出过时部分，生成更新后的全文。
|
||||
|
||||
### Step 4：提交更新
|
||||
|
||||
```bash
|
||||
gitlink-cli wiki +update \
|
||||
--owner <owner> \
|
||||
--repo <repo> \
|
||||
--name "API 文档" \
|
||||
--content "# API 文档\n\n（更新后的内容）..." \
|
||||
--message "docs: 同步更新 API 文档（关联 commit <hash>）"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 注意事项
|
||||
|
||||
- `wiki +create` / `wiki +update` 是写入操作，执行前必须确认用户意图
|
||||
- `wiki +delete` 在 GitLink 平台上只清空内容，不真正删除页面（已知平台限制）
|
||||
- `--content` 参数直接传 Markdown 文本，CLI 内部会自动处理 base64 编码
|
||||
- 在 git 仓库目录下运行时，`--owner` 和 `--repo` 可省略（自动从 remote 解析）
|
||||
|
|
@ -0,0 +1,150 @@
|
|||
# gitlink-docs-assistant — 使用示例
|
||||
|
||||
## 场景 1：文档完整性体检
|
||||
|
||||
**用户 Prompt：**
|
||||
> 请阅读 skills/gitlink-docs-assistant/SKILL.md，帮我检查 ylly/gitlink-cli 仓库的文档完整性。
|
||||
|
||||
**Agent 执行过程：**
|
||||
|
||||
```bash
|
||||
# Step 1：获取仓库信息
|
||||
gitlink-cli repo +info --owner ylly --repo gitlink-cli --format json
|
||||
```
|
||||
|
||||
```bash
|
||||
# Step 2：扫描根目录文件
|
||||
gitlink-cli api GET /ylly/gitlink-cli/sub_entries --query 'filepath=&ref=master'
|
||||
```
|
||||
|
||||
根目录文件（节选）：
|
||||
```
|
||||
README.md, README.zh-CN.md, LICENSE, go.mod, go.sum, main.go, ...
|
||||
```
|
||||
→ 有 README ✅、有 LICENSE ✅，无 CONTRIBUTING ❌，无 CHANGELOG ❌
|
||||
|
||||
```bash
|
||||
# Step 3：列出 Wiki 页面
|
||||
gitlink-cli wiki +list --owner ylly --repo gitlink-cli --format json
|
||||
```
|
||||
|
||||
返回：`["HOME", "demopage"]` → 无 API 文档 ❌
|
||||
|
||||
**Agent 输出报告：**
|
||||
|
||||
```markdown
|
||||
## 📋 文档体检报告 — ylly/gitlink-cli
|
||||
|
||||
📅 检查时间：2026-06-15
|
||||
|
||||
### 总体评级：🟡 待完善
|
||||
|
||||
| 检查项 | 状态 | 建议 |
|
||||
|--------|:----:|------|
|
||||
| README | ✅ 存在 | — |
|
||||
| CONTRIBUTING | ❌ 缺失 | 建议创建 Wiki 页面 |
|
||||
| CHANGELOG | ❌ 缺失 | 建议创建 Wiki 页面 |
|
||||
| API 文档 | ❌ 缺失 | 建议创建 Wiki 页面 |
|
||||
| LICENSE | ✅ 存在 | — |
|
||||
| 代码规范文档 | ⚠️ 未找到 | 可选补充 |
|
||||
|
||||
### 🎯 建议优先补充
|
||||
1. 🔴 CONTRIBUTING —— 降低新贡献者入门门槛
|
||||
2. 🟡 CHANGELOG —— 方便用户了解版本变更
|
||||
3. 🟡 API 文档 —— 说明 wiki/label/notification 等命令接口
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 场景 2：AI 自动生成 CONTRIBUTING 文档
|
||||
|
||||
**用户 Prompt：**
|
||||
> 帮我自动生成 ylly/gitlink-cli 的 CONTRIBUTING 文档并写入 Wiki。
|
||||
|
||||
**Agent 执行过程：**
|
||||
|
||||
```bash
|
||||
# 读取 README 了解项目背景
|
||||
gitlink-cli api GET /ylly/gitlink-cli/readme
|
||||
|
||||
# 读取目录结构了解项目技术栈
|
||||
gitlink-cli api GET /ylly/gitlink-cli/sub_entries --query 'filepath=&ref=master'
|
||||
```
|
||||
|
||||
AI 分析：Go 项目，有 shortcuts/ 目录，有单元测试，CLI 工具。
|
||||
|
||||
```bash
|
||||
# 写入 Wiki
|
||||
gitlink-cli wiki +create \
|
||||
--owner ylly \
|
||||
--repo gitlink-cli \
|
||||
--name "CONTRIBUTING" \
|
||||
--content "# 贡献指南
|
||||
|
||||
欢迎为 gitlink-cli 做贡献！
|
||||
|
||||
## 环境准备
|
||||
- Go 1.21+
|
||||
- gitlink-cli 已配置认证
|
||||
|
||||
## 开发流程
|
||||
1. Fork 仓库
|
||||
2. 创建功能分支
|
||||
3. 编写代码和测试
|
||||
4. 提交 PR
|
||||
|
||||
## 代码规范
|
||||
- 运行 \`go test ./...\` 确保测试通过
|
||||
- 新增 shortcut 需在 \`shortcuts/register.go\` 注册
|
||||
" \
|
||||
--message "docs: AI 自动生成 CONTRIBUTING 文档"
|
||||
```
|
||||
|
||||
**Agent 输出：**
|
||||
> ✅ 已创建 Wiki 页面「CONTRIBUTING」。
|
||||
|
||||
---
|
||||
|
||||
## 场景 3：更新过时的 Wiki 文档
|
||||
|
||||
**用户 Prompt：**
|
||||
> wiki 里的 API 文档还没有 wiki/label 命令的说明，帮我更新一下。
|
||||
|
||||
**Agent 执行过程：**
|
||||
|
||||
```bash
|
||||
# 读取现有页面
|
||||
gitlink-cli wiki +view --owner ylly --repo gitlink-cli --name "API 文档"
|
||||
|
||||
# 读取最近提交确认变更范围
|
||||
gitlink-cli api GET /ylly/gitlink-cli/commits --query 'page=1&limit=10'
|
||||
```
|
||||
|
||||
```bash
|
||||
# 更新页面（追加 wiki/label 命令说明）
|
||||
gitlink-cli wiki +update \
|
||||
--owner ylly \
|
||||
--repo gitlink-cli \
|
||||
--name "API 文档" \
|
||||
--content "# API 文档
|
||||
|
||||
（原有内容）...
|
||||
|
||||
## Wiki 命令
|
||||
- \`wiki +list\` — 列出所有 Wiki 页面
|
||||
- \`wiki +create\` — 创建新页面
|
||||
- \`wiki +update\` — 更新页面内容
|
||||
- \`wiki +view\` — 查看页面内容
|
||||
- \`wiki +delete\` — 删除页面
|
||||
|
||||
## Label 命令
|
||||
- \`label +list\` — 列出标签
|
||||
- \`label +create\` — 创建标签
|
||||
- \`label +update\` — 更新标签
|
||||
- \`label +delete\` — 删除标签
|
||||
" \
|
||||
--message "docs: 补充 wiki/label 命令说明"
|
||||
```
|
||||
|
||||
**Agent 输出：**
|
||||
> ✅ 已更新「API 文档」页面，新增 wiki 和 label 命令说明。
|
||||
|
|
@ -0,0 +1,55 @@
|
|||
# Claude Code 验证记录 — gitlink-docs-assistant
|
||||
|
||||
**验证日期：** 2026-06-15
|
||||
**验证平台：** Claude Code
|
||||
**验证仓库：** ylly/gitlink-cli
|
||||
|
||||
---
|
||||
|
||||
## 验证步骤
|
||||
|
||||
### 1. 环境确认
|
||||
|
||||
```bash
|
||||
gitlink-cli auth status
|
||||
```
|
||||
输出：`✓ 已登录，用户：ylly`
|
||||
|
||||
### 2. 喂入 Skill
|
||||
|
||||
在 Claude Code 中输入：
|
||||
> 请阅读 skills/gitlink-docs-assistant/SKILL.md，帮我检查 ylly/gitlink-cli 仓库的文档完整性，然后补全缺失的文档。
|
||||
|
||||
### 3. 验证工作流 1（体检）
|
||||
|
||||
Agent 依次执行：
|
||||
|
||||
| 步骤 | 命令 | 结果 |
|
||||
|------|------|:----:|
|
||||
| 获取仓库信息 | `gitlink-cli repo +info --owner ylly --repo gitlink-cli --format json` | ✅ |
|
||||
| 扫描根目录 | `gitlink-cli api GET /ylly/gitlink-cli/sub_entries --query 'filepath=&ref=master'` | ✅ |
|
||||
| 列出 Wiki 页面 | `gitlink-cli wiki +list --owner ylly --repo gitlink-cli --format json` | ✅ |
|
||||
| 输出体检报告 | （AI 生成 Markdown 报告） | ✅ |
|
||||
|
||||
### 4. 验证工作流 2（自动补全）
|
||||
|
||||
| 步骤 | 命令 | 结果 |
|
||||
|------|------|:----:|
|
||||
| 读取 README | `gitlink-cli api GET /ylly/gitlink-cli/readme` | ✅ |
|
||||
| 创建 CONTRIBUTING | `gitlink-cli wiki +create --name "CONTRIBUTING" ...` | ✅ |
|
||||
| 确认创建 | `gitlink-cli wiki +list --format json` | ✅ CONTRIBUTING 出现在列表中 |
|
||||
|
||||
### 5. 验证工作流 3（同步更新）
|
||||
|
||||
| 步骤 | 命令 | 结果 |
|
||||
|------|------|:----:|
|
||||
| 查看页面内容 | `gitlink-cli wiki +view --owner ylly --repo gitlink-cli --name "CONTRIBUTING"` | ✅ |
|
||||
| 更新页面 | `gitlink-cli wiki +update --name "CONTRIBUTING" --content "..." --message "..."` | ✅ |
|
||||
|
||||
---
|
||||
|
||||
## 验证结论
|
||||
|
||||
- **全部工作流通过** ✅
|
||||
- **Agent 平台：** Claude Code
|
||||
- **兼容性：** 标准 YAML frontmatter，兼容 Claude Code / Cursor / OpenClaw
|
||||
Loading…
Reference in New Issue