blog-mini-kit-mys

blog-mini-kit-mys

封装博客系统（FastAPI）全部 32 个 API 端点。无认证；后台管理端点依赖 cookie 会话（自动持久化）。

安全硬约束（必须遵守）

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 路径。
6. 删除/不可逆操作警示：delete-article --soft false（硬删除文章）、delete-mood（硬删除说说）、admin-delete-articles（批量硬删除文章）均为不可逆操作，执行前须确认。默认删除为软删除（soft=true）。

评论规范

• 所有 Issue/PR 评论 body 必须以 [blog-mini-kit-mys] 开头（环境变量未注入 agent 名时用 skill name）。
• 引用用户原文：> {用户评论}\n\n[blog-mini-kit-mys] {回复}

Configuration

目标系统 API 地址默认硬编码为博客服务器（_DEFAULT_BASE_URL），可被覆盖。所有命令中的 {base_url} 替换为实际地址（格式 http://:）。

{base_url} 解析优先级：

1. 项目知识 — 检查 .project-info/ 目录下 JSON 配置文件（config.BLOG_MINI_KIT_MYS_BASE_URL）
2. 环境变量 — BLOG_MINI_KIT_MYS_BASE_URL
3. 当前上下文 — 用户直接提供或 A2A context 中已包含
4. 硬编码默认值 — 脚本内 _DEFAULT_BASE_URL（无需用户配置即可开箱即用）

配置指导

方式一：环境变量（临时覆盖默认地址）

export BLOG_MINI_KIT_MYS_BASE_URL="http://:"

方式二：项目知识 JSON 文件（持久化）

在项目根目录下创建 .project-info/ 目录，放入任意名称的 .json 文件（脚本递归扫描）：

{
  "config": {
    "BLOG_MINI_KIT_MYS_BASE_URL": "http://:"
  }
}

不配置时使用脚本内置默认地址（Spec 指定的博客服务器），开箱即用。 ⚠️ .project-info/ 含敏感配置，不提交到 git 仓库（加入 .gitignore）。

场景 / When to Use

• 用户要求查询/发布/更新/删除博客文章
• 用户要求管理标签、用户、评论、留言、说说
• 用户要求上传/列出/删除文件（图片/视频/文档）
• 用户要求访问博客首页或文章详情页（HTML）
• 用户要求后台管理：登录、批量删除文章、登出
• 用户要求检查博客 API 健康状态

Don't use for: 非本博客系统的操作；需要管理员权限但未先执行 admin-login 的后台操作；修改 blog_api.py 源码（本 skill 只调用 API，不改动服务端）。

知识 / Knowledge

API Base URL

{base_url}  （默认硬编码博客服务器，可由 BLOG_MINI_KIT_MYS_BASE_URL 覆盖）

All endpoints below are relative to this base. 无认证——不需要 header。

Endpoints

完整端点表见 references/api-reference.md。按资源分组概览：

认证方式

• 无认证（公开 API）：不需要凭据，不带 Authorization 头。
• API 地址：BLOG_MINI_KIT_MYS_BASE_URL（环境变量）或项目知识或脚本默认值。
• 后台管理：依赖 cookie 会话 admin_token（默认账号 admin/admin），由 admin-login 获取并自动持久化到 ~/.blog-mini-kit-mys-session.json，后续 admin-* 命令自动复用。

Common Pitfalls

1. API 路径拼写 lables。 源码路径为 /api/lables（非 labels），子命令用正确拼写 labels，脚本内部请求用 /api/lables。详见 references/api-reference.md。
2. 删除默认软删除 vs 硬删除。 delete-article 默认 soft=true（软删除，可 restore）；--soft false 硬删除不可逆。delete-mood 与 admin-delete-articles 始终硬删除。
3. 文件上传必须用 multipart。 单传字段名 file，批量字段名 files（元组列表，不能用 dict value 为列表）。文件名需保留扩展名（服务端据此判断类型）。
4. 后台 token 在 body 非cookie。 /admin/api/delete 的 token 在 JSON body（{token, ids}），不在 cookie；但 /admin 入口检查 cookie。admin-login 成功后脚本同时持久化 token，两种用法都支持。
5. 博客页面端点返回 HTML 非JSON。 blog-home / blog-article-page 返回 text/html，子命令返回页面元信息（status_code/length/preview），不解析为 JSON。
6. get-article 会自增热度。 每次调用 /api/articles/{id} 服务端 heat+1，测试时注意副作用。
7. 分页参数约束。 page>=1、size 1-100、top-articles limit 1-20，超出范围服务端返回 422。

字段说明

步骤 / Steps

所有命令从 skills/blog-mini-kit-mys/ 目录执行：python3 scripts/blog-mini-kit-mys.py 。

1. 检查 API 可达性

python3 scripts/blog-mini-kit-mys.py health-check

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

2. 查询可用资源

list-articles（文章列表）

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

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

参数：--page --size --lid(标签过滤,>0) --keyword(标题模糊)

list-labels（标签列表）

python3 scripts/blog-mini-kit-mys.py list-labels

Expected: {"code":200,"data":[{id,lname}]}

list-users（用户列表）

python3 scripts/blog-mini-kit-mys.py list-users

Expected: {"code":200,"data":[{id,uname,...}]}

list-comments（文章评论）

python3 scripts/blog-mini-kit-mys.py list-comments --aid 1

Expected: {"code":200,"data":[{id,uid,aid,content,...}]}

list-messages（留言列表）

python3 scripts/blog-mini-kit-mys.py list-messages

Expected: {"code":200,"data":[{id,uid,content,replies:[...]}]}

list-moods（说说列表）

python3 scripts/blog-mini-kit-mys.py list-moods

Expected: {"code":200,"data":[{id,title,content,src}]}

list-uploads（已上传文件）

python3 scripts/blog-mini-kit-mys.py list-uploads

Expected: {"code":200,"data":[{filename,url,type,size}]}

top-articles（热门文章）

python3 scripts/blog-mini-kit-mys.py top-articles --limit 5

Expected: {"code":200,"data":[{id,title,heat}]}

3. 执行文章操作

create-article（发布文章）

python3 scripts/blog-mini-kit-mys.py create-article --title "测试" --content "正文"

Expected: {"code":200,"message":"文章发布成功","data":{"id":N}}

参数：--title(必填) --content(必填) --uid --lid --img --heat

get-article（文章详情）

python3 scripts/blog-mini-kit-mys.py get-article --article-id 1

Expected: {"code":200,"data":{"article":{...},"comments":[...]}}

update-article（更新文章）

python3 scripts/blog-mini-kit-mys.py update-article --article-id 1 --title "新标题"

Expected: {"code":200,"message":"文章更新成功"}

delete-article（删除文章）

python3 scripts/blog-mini-kit-mys.py delete-article --article-id 1            # 软删除
python3 scripts/blog-mini-kit-mys.py delete-article --article-id 1 --soft false  # 硬删除（不可逆）

Expected: {"code":200,"message":"文章已删除"}

restore-article（恢复文章）

python3 scripts/blog-mini-kit-mys.py restore-article --article-id 1

Expected: {"code":200,"message":"文章已恢复"}

4. 执行标签/用户/评论/留言/说说操作

create-label / create-user / create-comment / create-message / reply-message / create-mood

python3 scripts/blog-mini-kit-mys.py create-label --lname "新标签"
python3 scripts/blog-mini-kit-mys.py create-user --uname "newuser"
python3 scripts/blog-mini-kit-mys.py create-comment --uid 1 --aid 1 --content "好文"
python3 scripts/blog-mini-kit-mys.py create-message --uid 1 --content "留言内容"
python3 scripts/blog-mini-kit-mys.py reply-message --uid 1 --mid 1 --content "回复"
python3 scripts/blog-mini-kit-mys.py create-mood --content "今天天气不错" --title "随笔"

Expected: {"code":200,"data":{"id":N}}（create-label 含 lname）

delete-comment / delete-message / delete-mood

python3 scripts/blog-mini-kit-mys.py delete-comment --comment-id 1
python3 scripts/blog-mini-kit-mys.py delete-message --message-id 1
python3 scripts/blog-mini-kit-mys.py delete-mood --mood-id 1   # 硬删除

Expected: {"code":200,"message":"...已删除"}

5. 文件上传

upload-file（单文件）

python3 scripts/blog-mini-kit-mys.py upload-file --filepath /path/to/image.jpg

Expected: {"code":200,"data":{"url":"/uploads/xxx.jpg","filename":"image.jpg","type":"image","size":N}}

upload-files（批量）

python3 scripts/blog-mini-kit-mys.py upload-files --filepaths /path/a.jpg /path/b.png

Expected: {"code":200,"data":[{url,filename,type,size},...]}

delete-upload（删除文件）

python3 scripts/blog-mini-kit-mys.py delete-upload --filename xxx.jpg

Expected: {"code":200,"message":"文件已删除"}

6. 博客页面

blog-home / blog-article-page

python3 scripts/blog-mini-kit-mys.py blog-home
python3 scripts/blog-mini-kit-mys.py blog-article-page --article-id 1

Expected: {"status_code":200,"content_type":"text/html","length":N,"url":"...","preview":"..."}

7. 后台管理（cookie 会话）

admin-login（登录，持久化 token）

python3 scripts/blog-mini-kit-mys.py admin-login --username admin --password admin

Expected: {"code":200,"logged_in":true,"token":"...","message":"登录成功..."}

admin-entry（后台入口）

python3 scripts/blog-mini-kit-mys.py admin-entry

Expected: {"status_code":200,"logged_in":true,"length":N,"preview":"..."}（未登录 logged_in=false）

admin-delete-articles（批量硬删除，不可逆）

python3 scripts/blog-mini-kit-mys.py admin-delete-articles --ids 1,2,3

Expected: {"code":200,"deleted":3,"message":"成功删除 3 篇文章"}

admin-logout（登出）

python3 scripts/blog-mini-kit-mys.py admin-logout

Expected: {"status_code":302,"logged_out":true,"message":"已登出..."}

8. capability-list（能力清单）

python3 scripts/blog-mini-kit-mys.py capability-list

Expected: {"capability":"capability-list","skill":"blog-mini-kit-mys","endpoint_count":32,...}

判断标准 / Verification

• API 可达（health-check 返回 {"status":"ok"}）
• 只读操作返回有效数据（list-articles 返回非空 data、字段完整）
• 脚本 --help 无语法错误
• 32 子命令 + capability-list 全部在 --help 中可见
• 文件上传 multipart 正确（upload-file 返回 url/filename/type/size）
• 后台会话正确（admin-login 返回 token，admin-delete-articles 复用 token 成功）
• 删除默认软删除（delete-article 后可 restore-article 恢复）
• 退出码正确（0=成功 / 2=参数错误 / 3=缺少配置 / 4=API失败）

输出规范 / Output Format

脚本输出

• 默认输出：JSON（ensure_ascii=False, indent=2）
• 可选输出：Markdown 表格（--format md，capability-list 渲染为能力表）
• 使用示例：cd skills/blog-mini-kit-mys/ && python3 scripts/blog-mini-kit-mys.py list-articles --format md

Issue 评论格式

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

[blog-mini-kit-mys] ✅ {操作名称}完成

## 操作结果

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

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

失败时：

[blog-mini-kit-mys] 🔴 {操作名称}失败

## 错误分析

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

### 修复建议

{修复步骤}

参考文档 / References

• API 端点文档 — 32 端点完整清单（method/path/params/body/响应）
• 测试用例 — 子命令测试用例与预期

分析结论示例

成功时：

分析结论：
- 场景：博客 API 操作（查询/发布/删除等）
- Skill：blog-mini-kit-mys v0.1.0
- 操作：{subcommand} {params}
- 结果：✅ 成功（{API 返回的关键数据摘要}）
- 必须执行：Issue 评论汇总结果 → 任务结束

失败时：

分析结论：
- 场景：博客 API 操作
- Skill：blog-mini-kit-mys v0.1.0
- 操作：{subcommand} {params}
- 结果：🔴 失败（{错误原因}）
- 必须执行：Issue 评论报告错误 → 任务结束

任务结束

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

{
  "actions": ["{具体执行的操作，如 list-articles: 返回 5 篇文章}"],
  "conclusion": "{处理结论，如 查询成功，返回 5 篇文章}",
  "artifacts": ["{产生的产物：写操作返回资源 ID 或操作结果 / 文件操作返回 URL / 只读查询无产物填空数组}"],
  "next_step": "{下一步建议，如 无 / 等待用户下一步指令}",
  "issue_summary": "{Issue 最新聚合结论，紧凑文本，用 | 分隔}"
}

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