feima-lab 内容管家 (feima-lab-content-manager)

能力边界

✅ 本地构建：

• 纯文本/已 md 输入 → 生成符合 feima-lab 样式的 article.mdx
• 本地像素级 + 交互可用的 preview.html（零依赖，file:// 协议直接打开）
• 图片本地化（下载 URL 图 / 拷贝本地图到 posts/\x3Cslug>/images/）
• 文章元数据管理（meta.json）
• 分级工作流（简单/复杂）

✅ 远程 API（v1.2）—— 完整对接 fenxiang-ai-brain ContentApiController：

• 文章 CRUD：save（create / update）/ publish / unpublish / by-slug / list（多条件筛选+分页）
• 分类：list，支持 --route BLOG|NEWS 按路由筛选
• 标签：list / save（创建），save-article 内部会闭环处理 meta.tags 字符串数组（查已有→缺失的自动建→映射成 tagIds）
• 图片上传：任意文件到 OSS，save-article 内部会自动上传封面图 + 正文中所有 ./images/ 本地引用
• category 映射：meta.category 名字 + meta.route 自动查到 categoryId
• slug 冲突检查：list-articles --slug xxx 专门用于查重

❌ 不做：

• PDF/Word/飞书等结构化文档解析（交给其他 skill 先转成 md 或纯文本）
• 样式定制（样式唯一来源是 references/feima-style-snapshot.json）
• 删除文章（/article/delete 破坏性，防误操作，v2 能力）
• 按 id 查文章（/article/detail/{id} 与 by-slug 冗余，by-slug 更稳定）
• 删除标签（/tag/delete 很少用且语义怪，v2 再看）
• 本地 ↔ 远程自动 diff / sync

前置条件

零 npm 依赖——开箱即用，不需要 npm install。

• scripts/render.mjs 是预打包的自包含文件（包含 unified/remark/mdast/hast 等所有 MDX 解析依赖）
• scripts/new-post.mjs / scripts/image-localize.mjs / scripts/api/* 只用 Node 18+ 内置 API（fetch / FormData / Blob 等）

唯一环境要求：Node ≥ 18。

调用远程 API 的额外要求：必须设置环境变量 FX_AI_API_KEY，且 key 必须是 internal 类型。用户在 shell 中执行：

export FX_AI_API_KEY=\x3Cyour-internal-key>

重要：ContentApiController 标注了 @ExternalApiAuth(level = ApiAuthLevel.INTERNAL)——normal 类型的 key 会被后端直接拒绝。从 https://platform.fenxiang-ai.com/ 登录后申请 internal key。

key 不要写入 MEMORY.md 或任何持久化位置——让用户在 shell 自己管理。

如果只用本地构建能力（render / new-post / image-localize），不需要设置这个 env var。

User Context

本 skill 的产出依赖以下作者信息：

读取：填写 meta.json 前先 Read 本目录下的 MEMORY.md，存在字段直接使用。

写入：若 MEMORY.md 不存在或缺字段，引导作者提供后写入：

更新：作者明确要求修改默认作者/分类时，更新 MEMORY.md。

工作流路由

Step 1: 识别输入

• 纯文本（会话内粘贴的文字块）
• md 文件路径
• 混合（一段文字 + 图片路径/URL）

Step 2: 分级判定（告知作者）

结构信号：标题数 ≥ 3 / "步骤 1/2/3" / "对比 A vs B" / "优缺点" / "时间轴" / 图片数 ≥ 4。任一命中即归为复杂。

必须告知："识别为[简单/复杂]文档，将走 [一把生成 / 先出结构提案] 流程"，然后继续执行（不提问）。

Step 3: 骨架创建

node \x3Cskill-dir>/scripts/new-post.mjs --slug \x3Ckebab-slug> --cwd \x3C作者工作目录>

Step 4-N: 按 workflow-simple / workflow-complex 执行

详细步骤见对应 reference 文件，按需 Read，不预加载。

组件白名单

严禁使用白名单之外的组件：

Callout / CodeTabs / Collapse / CompareCard / Timeline / ImageCarousel / Playground / Video

（v1.3 新增 Video；支持 YouTube / Bilibili 自动转 embed iframe，其他 URL 走原生 \x3Cvideo>。）

用某个组件前 Read references/components/\x3C组件名小写>.md 速查语法。

组件选择决策 Read references/component-selection.md。

脚本调用约定

本地构建（无需 API Key）

# 创建文章骨架
node scripts/new-post.mjs --slug \x3Cslug> [--cwd \x3Cdir>]

# 图片本地化 + 原位改写 mdx 路径
node scripts/image-localize.mjs \x3Cposts/\x3Cslug>>

# MDX → preview.html（打印路径到 stdout）
node scripts/render.mjs \x3Cposts/\x3Cslug>>/article.mdx

远程 API（需要 FX_AI_API_KEY 环境变量，internal 类型）

# === 查询类 ===
node scripts/api/list-categories.mjs [--route BLOG|NEWS] [--format json|table]
node scripts/api/list-articles.mjs   [--route ...] [--category-id ...] [--tag ...] [--slug ...]
                                      [--publish-status 0|1] [--page 1] [--size 10] [--format ...]
node scripts/api/list-tags.mjs       [--format json|table]
node scripts/api/get-article.mjs     --slug \x3Cslug>
node scripts/api/get-article.mjs     --post-dir \x3Cposts/slug>

# === 写入类 ===
node scripts/api/upload-file.mjs     --file \x3Cpath>
node scripts/api/save-article.mjs    --post-dir \x3Cposts/slug> [--dry-run]
node scripts/api/save-tag.mjs        --name \x3CtagName>
node scripts/api/publish-article.mjs   --post-dir \x3Cposts/slug> | --id \x3Cn> | --slug \x3Cslug>
node scripts/api/unpublish-article.mjs --post-dir \x3Cposts/slug> | --id \x3Cn> | --slug \x3Cslug>

所有脚本均为 Node.js .mjs，跨平台（macOS/Linux/Windows 均可）。

API 路由表

强制规则：

• 调用 API 脚本前必须 Read references/api-publish-workflow.md，按需 Read references/api-error-handling.md
• 如果 stderr 返回 {"error_type": "missing_api_key"} → 立刻停下告诉用户设internal 类型 env var，禁止自动把 key 写 MEMORY.md
• save / publish / unpublish 的结果（articleId / tagIds / published_at）会自动回写 meta.json，不要手工修改 publish.remote_id / publish.published_at / publish.last_saved_tag_ids
• Claude 根据用户描述自主决定 meta.route（"博客"→BLOG，"动态/新闻/公告"→NEWS），默认 BLOG

错误处理

环境错误

• Node \x3C 18 → 提示作者升级 Node（render.mjs 使用 ESM + 顶层 await）

运行时错误 — render.mjs

运行时错误 — image-localize.mjs

• 退出码 1（部分图片失败）→ 按失败清单逐张处理：
  1. URL 可访问性验证
  2. 网络问题 → 建议作者手工下载到 images/ + 手工改 mdx
  3. 404 → 和作者确认是否删除这张图
• 退出码 2 → post 目录或 article.mdx 不存在

运行时错误 — new-post.mjs

• 退出码 1（目录已存在 / slug 格式错）→ 询问作者：追加/覆盖/换 slug

运行时错误 — API 脚本（scripts/api/*）

所有 API 脚本的错误都是一行 JSON 到 stderr，格式：

{"status":"error","error_type":"\x3Ctype>","message":"...","suggestion":"..."}

关键 error_type：

详细处理 Read references/api-error-handling.md。

渐进式输出

每完成一步立即告知作者，不等全部完成再统一汇报：

1. "骨架建好了：posts/\x3Cslug>/"
2. "图片处理完成：5 张本地化，0 张失败"
3. "预览已生成：posts/\x3Cslug>/preview.html"
4. 最终汇报

最终汇报格式

✅ 文章已生成：posts/\x3Cslug>/
📄 预览：posts/\x3Cslug>/preview.html （请在浏览器打开）
🧩 用到的组件：Callout×2, Timeline, CodeTabs
📊 预估阅读时间：8 分钟（1920 字，按 350 字/分钟估算）
💡 改进建议（仅在有值得说的决策点时输出）：
   - 第 3 段"注意"包成了 Callout warning，觉得多余可告诉我回退
   - coverImage 未设置，meta.json 该字段为空

改进建议区块按需输出——有值得说的决策点才写，没有就省略整个区块。

设计参考

完整设计文档：主仓库 docs/plans/2026-04-09-feima-lab-content-manager-design.md