blog-kit-dev

安全硬约束（必须遵守）

通用约束（所有 skill 必含）：

1. 严禁读取 data/、configs/、sessions.db、user_accounts 等 Grape 内部数据。
2. API 返回 403/无权限时：立即停止该操作并回复用户，严禁尝试其他 token 或绕行手段。
3. 所有 curl / API 调用设 30s 超时——超时判定失败，不 hang。
4. 严禁 mock 模式/假数据：所有 API 调用必须真实访问目标系统。
5. 调用目标 API 一律以 references/api-reference.md 为准：严禁根据经验/记忆/猜测自行拼写 API 路径。

评论规范

• 所有 Issue/PR 评论 body 必须以 [$AGENT_NAME] 开头（如果环境变量未注入，使用 skill name 作为前缀，如 [blog-kit-dev]）
• 引用用户原文：> {用户评论}\n\n[$AGENT_NAME] {回复}

Configuration

目标系统 API 地址必须在使用前确定。所有命令中的 {base_url} 替换为实际地址（格式 http://<host>:<port>）。

{base_url} 解析优先级：

1. 项目知识 — 检查 .project-info/ 目录下 JSON 配置文件（config.BLOG_KIT_DEV_BASE_URL）
2. 环境变量 — BLOG_KIT_DEV_BASE_URL
3. 当前上下文 — 用户直接提供或 A2A context 中已包含
4. 交互输入 — 以上都无时提示用户输入

配置指导

方式一：环境变量（临时，推荐快速测试）

export BLOG_KIT_DEV_BASE_URL="http://<host:port>"

方式二：项目知识 JSON 文件（持久化，推荐生产使用）

在项目根目录下创建 .project-info/ 目录，放入任意名称的 .json 文件：

{
  "config": {
    "BLOG_KIT_DEV_BASE_URL": "http://<host:port>"
  }
}

⚠️ .project-info/ 含配置信息，建议加入 .gitignore 不提交到 git 仓库。

场景 / When to Use

• 查询博客文章列表、详情、热门文章
• 创建/更新/删除/恢复文章
• 管理评论（查看/发表/删除）
• 管理标签（查看/创建）
• 管理留言（查看/发表/回复/删除）
• 管理说说（查看/发表/删除）
• 上传/删除文件
• 查看用户列表、创建用户
• API 健康检查
• 管理员登录/退出/批量删除
• 博客首页/文章详情页（HTML 页面端点）

Don't use for: 非 Blog System API 的操作；Blog System 本身的部署/配置修改。

知识 / Knowledge

API Base URL

{base_url}

All endpoints below are relative to this base. 无认证（公开 API），不需要 header。

Endpoints

按资源分组列出端点表（从 OpenAPI 3.1.0 文档解析，共 25 路径 / 32 操作）：

文章（7 个）

评论（3 个）

标签（2 个）

API 路径为 /api/lables（拼写如此），子命令用正确拼写 labels。

留言（4 个）

说说（3 个）

文件上传（4 个）

用户（2 个）

健康（1 个）

管理（4 个）

admin 端点需要 session cookie。admin-login 返回 HTML，admin-logout 返回 302，admin-delete-articles 未登录返回 401。

页面（2 个）

Web 页面端点返回 HTML 而非 JSON，脚本自动检测 content-type 并返回结构化信息。

认证方式

• 无认证：公开 API，不需要凭据
• API 地址：BLOG_KIT_DEV_BASE_URL

凭据前缀：由 skill name 推导（blog-kit-dev → BLOG_KIT_DEV），skill name 转大写下划线。

Common Pitfalls

1. API 不可达。 先检查 base_url 是否正确，python3 scripts/blog-kit-dev.py health-check 确认可达。
2. 标签路径拼写。 API 实际路径为 /api/lables（非 labels），子命令用正确拼写 labels 但脚本内部请求 lables 路径。
3. 文章删除是软删除。 delete-article 默认 soft=true，文章标记为已删除但可通过 restore-article 恢复。设 --soft false 可硬删除。
4. admin 端点需登录态。 admin-login 返回 HTML 表单页面（非 JSON API），需通过浏览器提交获取 session cookie。admin-delete-articles 未登录返回 {"code":401}。
5. 文件上传用 multipart。 upload-file / upload-files 使用 files= 参数（非 json=），指定本地文件路径。
6. 分页参数。 list-articles 的 size 最大 100，page 从 1 开始。top-articles 的 limit 最大 20。
7. Web 页面端点返回 HTML。 blog-home / blog-article-detail / admin-page 返回 HTML 而非 JSON，脚本自动检测并返回 {"status_code":..., "content_type":..., "raw":"..."} 结构。

字段说明

步骤 / Steps

1. 检查 API 可达性

python3 scripts/blog-kit-dev.py health-check

Expected: {"status":"ok","service":"blog-api","version":"1.0.0"}

2. 查询可用资源

python3 scripts/blog-kit-dev.py list-articles --page 1 --size 10

Expected: {"code":200,"data":[...],"total":N,"page":1,"size":10}

3. 执行操作（按用户需求选择）

查询文章列表

python3 scripts/blog-kit-dev.py list-articles --page 1 --size 5 --keyword AI

Expected: {"code":200,"data":[...],"total":N}

参数说明：

• --page：页码，默认 1
• --size：每页条数（1-100），默认 10
• --lid：标签 ID 过滤
• --keyword：关键词搜索
• --format：输出格式 json/md，默认 json

创建文章

python3 scripts/blog-kit-dev.py create-article --title "测试文章" --content "内容"

Expected: {"code":200,"data":{"id":N,...}}

删除文章（软删除）

python3 scripts/blog-kit-dev.py delete-article --article-id 42

Expected: {"code":200,"message":"删除成功"}

上传文件

python3 scripts/blog-kit-dev.py upload-file --filepath /path/to/file.png

Expected: {"code":200,"data":{"filename":"...","url":"..."}}

capability-list

python3 scripts/blog-kit-dev.py capability-list

Expected: {"capability":"capability-list","skill":"blog-kit-dev","version":"0.1.0","api_coverage":{"total_paths":25,"total_operations":32,"cli_subcommands":31},"capabilities":[...]}

判断标准 / Verification

• API 可达（GET /health 返回 200）
• 只读操作返回有效数据（非空/字段完整）
• 脚本 --help 无语法错误
• 退出码正确（0=成功/2=参数错误/3=缺少配置/4=API失败）
• 25 路径 / 32 操作全覆盖

输出规范 / Output Format

脚本输出

• 默认输出：JSON
• 可选输出：Markdown 表格（--format md）
• 使用示例：cd skills/blog-kit-dev/ && python3 scripts/blog-kit-dev.py list-articles --format md

Issue 评论格式

执行完操作后，Issue 评论 body 格式：

[$AGENT_NAME] ✅ {操作名称}完成

## 操作结果

| 操作 | 状态 | 资源 ID | 详情 |
|------|------|---------|------|
| {操作名} | ✅ 成功 / 🔴 失败 | {id} | {简要说明} |

**API 地址**：{base_url}
**执行时间**：{UTC ISO}

失败时：

[$AGENT_NAME] 🔴 {操作名称}失败

## 错误分析

- **操作**：{操作名}
- **错误**：{API 返回的错误信息}
- **HTTP 状态码**：{code}
- **原因**：{分析原因}

### 修复建议
{修复步骤}

参考文档 / References

• API 端点文档
• 测试用例

分析结论示例

成功时：

分析结论：
- 场景：Blog System API 操作（A2A 触发，Coding Agent 交棒）
- Skill：blog-kit-dev v0.1.0
- 操作：list-articles --page 1 --size 5
- 结果：✅ 成功（返回 N 篇文章）
- 必须执行：Issue 评论汇总 → 任务结束

失败时：

分析结论：
- 场景：Blog System API 操作
- Skill：blog-kit-dev v0.1.0
- 操作：get-article --article-id 999
- 结果：🔴 失败（文章不存在）
- 必须执行：Issue 评论报告错误 → 任务结束

任务结束

完成所有业务动作后，在最终答复末尾输出以下 JSON 块并结束任务：

{
  "actions": ["做了什么"],
  "conclusion": "处理结论",
  "artifacts": ["产生的产物"],
  "next_step": "下一步建议",
  "issue_summary": "Issue 最新聚合结论（紧凑文本，用 | 分隔）"
}

注意：只输出一个 JSON 块，放在答复末尾。