feima-lab 内容管家 (feima-lab-content-manager)
能力边界
✅ 本地构建：
- 纯文本/已 md 输入 → 生成符合 feima-lab 样式的 article.mdx
- 本地像素级 + 交互可用的 preview.html（零依赖，file:// 协议直接打开）
- 图片本地化（下载 URL 图 / 拷贝本地图到
posts/<slug>/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=<your-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 不存在或缺字段，引导作者提供后写入：
| 字段 | 示例 |
|---|
default_author | 黎东 |
default_category | AI 实战 |
default_tags | ["Claude Code"] |
slug_style | kebab-case（纯 kebab，不加日期前缀） |
更新：作者明确要求修改默认作者/分类时，更新 MEMORY.md。
工作流路由
Step 1: 识别输入
- 纯文本（会话内粘贴的文字块）
- md 文件路径
- 混合（一段文字 + 图片路径/URL）
Step 2: 分级判定（告知作者）
| 条件 | 归类 | 动作 |
|---|
| < 800 字 且 无结构信号 | 简单 | Read references/workflow-simple.md |
| ≥ 800 字 或 有结构信号 | 复杂 | Read references/workflow-complex.md |
结构信号：标题数 ≥ 3 / "步骤 1/2/3" / "对比 A vs B" / "优缺点" / "时间轴" / 图片数 ≥ 4。任一命中即归为复杂。
必须告知："识别为[简单/复杂]文档，将走 [一把生成 / 先出结构提案] 流程"，然后继续执行（不提问）。
Step 3: 骨架创建
node <skill-dir>/scripts/new-post.mjs --slug <kebab-slug> --cwd <作者工作目录>
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 走原生 <video>。）
用某个组件前 Read references/components/<组件名小写>.md 速查语法。
组件选择决策 Read references/component-selection.md。
脚本调用约定
本地构建（无需 API Key）
# 创建文章骨架
node scripts/new-post.mjs --slug <slug> [--cwd <dir>]
# 图片本地化 + 原位改写 mdx 路径
node scripts/image-localize.mjs <posts/<slug>>
# MDX → preview.html（打印路径到 stdout）
node scripts/render.mjs <posts/<slug>>/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 <slug>
node scripts/api/get-article.mjs --post-dir <posts/slug>
# === 写入类 ===
node scripts/api/upload-file.mjs --file <path>
node scripts/api/save-article.mjs --post-dir <posts/slug> [--dry-run]
node scripts/api/save-tag.mjs --name <tagName>
node scripts/api/publish-article.mjs --post-dir <posts/slug> | --id <n> | --slug <slug>
node scripts/api/unpublish-article.mjs --post-dir <posts/slug> | --id <n> | --slug <slug>
所有脚本均为 Node.js .mjs，跨平台（macOS/Linux/Windows 均可）。
API 路由表
| 用户意图 | 脚本 | 前置 Read |
|---|
| "发布这篇文章" / "推到 feima-lab" / "上线" | save-article → publish-article 串行 | references/api-publish-workflow.md |
| "写一篇博客" | meta.route="BLOG"，save-article | 同上 |
| "写一条动态/新闻" | meta.route="NEWS"，save-article | 同上 |
| "更新已发布的文章" / "重新推" | save-article（mode 自动识别为 update） | 同上 |
| "下线这篇" / "撤回" / "取消发布" | unpublish-article | 同上 |
| "这篇在远程是什么状态" | get-article | 同上 |
| "这个 slug 能用吗" / "查重" | list-articles --slug <slug> | 同上 |
| "列我发过的所有博客" | list-articles --route BLOG --publish-status 1 --format table | 同上 |
| "列某标签下的文章" | list-articles --tag <name> --format table | 同上 |
| "看看所有分类" | list-categories [--route BLOG] --format table | 同上 |
| "看看所有标签" | list-tags --format table | 同上 |
| "新建一个标签" | save-tag --name <name>（一般不用手工调） | 同上 |
| "上传一张图" | upload-file --file <path>（save 内部会自动调） | 同上 |
| "API 报错了怎么处理" | （查 stderr 的 error_type） | references/api-error-handling.md |
| "删掉这篇文章" | v1.2 不支持，告诉用户 v2 再做 | — |
强制规则：
- 调用 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 < 18 → 提示作者升级 Node（render.mjs 使用 ESM + 顶层 await）
运行时错误 — render.mjs
| 退出码 | 含义 | 处理 |
|---|
| 1 | MDX 解析失败 | 读 stderr 定位行号，修语法后重跑 |
| 2 | 组件 props 校验失败 | Read references/components/<组件名>.md，按语义修 props |
| 3 | 未知组件 <Foo> | 立即回到 article.mdx，替换为白名单组件或退回原生 md，重跑 |
运行时错误 — image-localize.mjs
- 退出码 1（部分图片失败）→ 按失败清单逐张处理：
- URL 可访问性验证
- 网络问题 → 建议作者手工下载到
images/ + 手工改 mdx
- 404 → 和作者确认是否删除这张图
- 退出码 2 → post 目录或 article.mdx 不存在
运行时错误 — new-post.mjs
- 退出码 1（目录已存在 / slug 格式错）→ 询问作者：追加/覆盖/换 slug
运行时错误 — API 脚本（scripts/api/*）
所有 API 脚本的错误都是一行 JSON 到 stderr，格式：
{"status":"error","error_type":"<type>","message":"...","suggestion":"..."}
关键 error_type：
| 类型 | 快速处理 |
|---|
missing_api_key | 停下，让用户 export FX_AI_API_KEY=... |
invalid_meta | 按 message 补全 meta.json 重试 |
file_not_found | 按 suggestion 跑前置脚本（new-post / image-localize） |
api_unavailable | 最多重试 1 次，仍失败则停下 |
api_error | 读 message 按后端提示改输入 |
not_found（仅 get-article，exit 2） | 不是错，说明后端没这篇，换 save 路径 |
详细处理 Read references/api-error-handling.md。
渐进式输出
每完成一步立即告知作者，不等全部完成再统一汇报：
- "骨架建好了：posts/<slug>/"
- "图片处理完成：5 张本地化，0 张失败"
- "预览已生成：posts/<slug>/preview.html"
- 最终汇报
最终汇报格式
✅ 文章已生成：posts/<slug>/
📄 预览：posts/<slug>/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
