Fecify Skill 结构组成（完整版）

从 skill 架构层面，系统分析 fecify_skills 的每个组成部分及其关系，下面写的是V2版本，实时获取可以自己在龙虾智能体中进行提问： fecify-skill-结构组成，从skill架构层面做详细介绍

目录

1. Frontmatter（元信息）
2. 铁律（Iron Laws）
3. 三层递进式路由
4. 会话管理
5. 通用 API 调用层
6. 模块路由表
7. 模块指引文档（第 2 层）
8. API 参数文档（第 3 层）
9. JSON Schema（API 数据源）
10. 工作流文档
11. 脚本层
12. 示例数据
13. 外部配置文件
14. 扩展机制
15. 架构全景图

1. Frontmatter（元信息）

位置：SKILL.md 顶部 YAML 区块。

---
name: fecify-site-manager-v2    # 技能唯一标识，系统注册用
version: "2"                     # 版本号，字符串格式
description: >                   # 一句话能力概述
  Fecify 独立站管理。会话绑定站点（URL + Token），配置持久化。
  商品/专辑/博客/图片/AI图片生成/系统配置/权限/物流/税费/订单。相关处理全链路覆盖。
---

Frontmatter 不参与 Agent 调度逻辑，是纯元数据。

2. 铁律（Iron Laws）

铁律是 skill 的最高优先级规则，Agent 必须在任何操作前先通过铁律检查。

2.1 全局铁律

定义在 SKILL.md，5 条，对全模块生效：

2.2 模块级铁律

某些模块在全局铁律基础上追加自身特有的铁律。例如：

• 商品专辑批量工作流（docs/collections/workflow-collection-batch.md）：
  • 二段式提交（Phase 1 检查→确认 → Phase 2 执行→汇总 → Phase 3 缓存）
  • 语言一致性：用户指定语言则所有 title/bodyhtml/meta* 必须是该语言
  • 缺失字段补全：缺失 bodyhtml/meta* Agent 必须 AI 生成
  • 统一确认执行、统一询问缓存
• 模版装修（docs/theme.md）：独立铁律体系，不在此展开
• 多语言翻译：AI agent 真翻不抄原文；body_html 保留 HTML 标签只译文本

2.3 铁律设计原则

• 全局铁律不超 5 条，只放对所有模块都适用的硬约束
• 模块特有约束写在对应的 .md 中，就近原则
• 每条铁律必须明确指出"防止什么问题"，不只说"不要做什么"

3. 三层递进式路由

Fecify Skill 的核心导航机制。Agent 从粗到细逐层深入：

SKILL.md                        第 1 层 — 调度摘要
    ↓ 模块匹配
docs/<模块>.md                   第 2 层 — 模块指引（API 速查表 + 工作流 + 易错点）
    ↓ API 匹配
docs/<模块>/<API>.md             第 3 层 — 单个 API 的请求参数（字段名/类型/必填/示例）
    ↓ 参数确认
api-call.js                     执行（POST/GET/...）

设计要点

• 第 1 层不做 API 细节：只告诉 Agent "去哪个模块"，不写参数
• 第 2 层不做参数定义：给速查表 + 易错点，Agent 快速锁 API
• 第 3 层只做一件事：把 API 的请求参数说清楚，Agent 照抄即可
• api-call.js 是唯一执行入口：所有 API 调用必须经过它，不直接 curl

4. 会话管理

SKILL.md 第 1 节，定义多店铺会话的生命周期。

4.1 启动流程

node scripts/base/check-config.js
  ├── 未配置 → 引导用户提供 URL + Token
  │           → node scripts/base/save-config.js "<URL>" "<Token>"
  │           （自动调用 /api/skill/base/init 拉取 init 数据）
  └── 已配置 → 显示当前站点 URL

4.2 会话隔离

exec 带 env: { FECIFY_SESSION: "<标识>" }
未指定 → 自动使用 session key 后 8 位

多店铺场景下，每个店铺对应一个独立会话。配置保存到 site-config.js 管理的持久化存储中。

4.3 相关脚本

5. 通用 API 调用层

SKILL.md 第 2 节。Agent 调用任何 API 的统一方式。

5.1 四种调用模式

# 模式 1: GET（无 body）
node scripts/proxy/api-call.js GET /api/skill/<path>

# 模式 2: POST stdin（短 JSON，一行）
echo '{"page":1}' | node scripts/proxy/api-call.js POST /api/skill/<path>

# 模式 3: POST --data（长 JSON，先写到文件再引）
node scripts/proxy/api-call.js POST /api/skill/<path> --data body.json

# 模式 4: POST 命令行参数（非常短的 JSON）
node scripts/proxy/api-call.js POST /api/skill/<path> '{"id":363}'

5.2 参数查询

node scripts/proxy/api-doc.js                          # 列出所有模块
node scripts/proxy/api-doc.js --module=product          # 某模块所有 API
node scripts/proxy/api-doc.js --api=product/list        # 单个 API 详细参数
node scripts/proxy/api-doc.js --search=专辑              # 搜索 API

5.3 响应码速查

5.4 底层支撑

• scripts/proxy/api-call.js：CLI 入口，解析参数→读配置→调 api-client→打印结果
• scripts/proxy/api-doc.js：读 docs/schemas/*.json→格式化输出参数表
• scripts/base/api-client.js：HTTP 封装（GET/POST/PUT/DEL + 自动鉴权 + 30s 超时 + 插件校验）

6. 模块路由表

SKILL.md 第 3 节。按业务域分组，共 8 组 18 个模块：

每个模块在路由表中占一行，4 列：

设计原则："最少信息决策" — 只给足够判断"该去哪个模块"的信息，细节留给下一层。

7. 模块指引文档（第 2 层）

每个 docs/<模块>.md 都是该模块的操作手册。统一的文档结构：

7.1 脚本速查表

列出该模块可用的预写脚本：

| 脚本 | 说明 |
|------|------|
| `scripts/collection/create.js`      | 创建专辑（AI 图片 + SEO 一步完成） |
| `scripts/collection/batch-collection.js` | 批量工具：创建/更新/添加商品 |

7.2 工作流说明

如果模块涉及复杂流程，在这里描述整体步骤。例如商品专辑批量工作流：

Phase 1: Agent 提取语言 → 解析 #N → 翻译 → 补全 → 检查 → 确认清单 → 等用户说"执行"
Phase 2: tasks.json → node batch-collection.js --file ... → 汇总
Phase 3: 统一询问缓存刷新

7.3 API 速查表

该模块所有可调 API 的快速索引：

| 操作 | 路径 | 方法 | 传参 | 详细文档 |
|------|------|------|------|----------|
| 专辑列表 | /api/skill/product-collection/list | POST | query 参数 | [link] |
| 专辑详情 | /api/skill/product-collection/info | POST | query 参数 | [link] |
| 创建专辑 | N/A (独立脚本) | — | — | [link] |

7.4 通用调用示例

该模块 GET/POST 的 bash 示例，Agent 可以直接复制。

7.5 易错点列表

该模块特有的踩坑记录，比 SKILL.md 路由表中更详细。

7.6 相关链接

关联的翻译工作流、批量工作流等。

8. API 参数文档（第 3 层）

每份 docs/<模块>/<API>.md，单个 API 的详细参数手册。

结构

# API 名称

## 请求

- **方法**: GET
- **路径**: /api/skill/<path>

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id   | int  | 是   | 专辑ID |

## 请求示例

{ "id": 363 }

## 响应示例

{ "code": 200, "data": { ... } }

注意事项

• 所有参数字段名必须与真实 API 完全一致
• 类型标注要精确（如 int[]、decimal、Array[Object]）
• 响应示例要反映真实结构
• 如果 API 有 param_style: "query"→GET 方式传参，如果 param_style: "json"→POST body

9. JSON Schema（API 数据源）

docs/schemas/*.json，共 21 个文件，是 api-doc.js 的数据源。

结构格式

{
  "module": "products",
  "label": "商品管理",
  "apis": [
    {
      "id": "list",
      "label": "商品列表",
      "method": "GET",
      "path": "/api/skill/product/list",
      "params_query": {
        "pageNum": { "type": "int", "required": false, "default": 1 },
        "pageSize": { "type": "int", "required": false }
      }
    }
  ]
}

特点

• 结构化：JSON 格式，程序可读，api-doc.js 直接解析
• 单向关系：Schema 是数据源，api-doc.js 是查询器，第 3 层 .md 是给人读的展示
• 独立维护：改 API 参数改 Schema，不影响 markdown 文档结构
• 容量：21 个模块，约 250+ 个 API 端点，覆盖全部业务

与 Markdown 文档的关系

• Schema 是权威数据源
• Markdown 文档是人类可读的展示，内容应与 Schema 一致
• Agent 查参数优先用 api-doc.js（读 Schema），因为保证最新；文档用于详细说明和示例

10. 工作流文档

docs/<模块>/workflow-*.md，为复杂业务流程提供完整操作指引。

结构

# 工作流名称

## 概述
## ⚠️ 铁律
## 工作流程
    Phase 1: ...
    Phase 2: ...
    Phase 3: ...

## Task 数据结构（JSON Schema）
## Agent 执行清单
## 已知坑列表
## 调用示例

已实现的工作流

设计原则

• 工作流文档按二段式提交设计：Phase 1 检查→Phase 2 执行→Phase 3 收尾
• 自带独立铁律，补充模块级约束
• Agent 执行清单：按编号逐一完成，确保不跳步

11. 脚本层

按功能分为 4 类：

11.1 基础设施（scripts/base/ + scripts/proxy/）

Agent 不直接调用，但所有业务脚本依赖它们。

11.2 公共工具（scripts/image/ + scripts/image-gen/ + scripts/language/）

被多个业务模块复用的工具函数。

11.3 业务脚本（各业务目录）

由 Agent 或工作流直接调用。

11.4 脚本间依赖

api-client.js ←── 所有业务脚本
    ↑
site-config.js ←── 读写配置
    ↑
save-config.js / check-config.js / reload-init.js

api-call.js ←── Agent CLI 统一入口
    ↑ uses
api-client.js

api-doc.js
    ↑ reads
docs/schemas/*.json

12. 示例数据

docs/theme/samples/new_default_theme/ — 24 套主题的完整示例数据。

new_default_theme/
├── _index.json                    # 主题索引
├── sample_data.json               # 全局示例数据
├── baby/                          # 婴儿用品主题
│   ├── home.json                  #   首页配置
│   ├── settings_data.json         #   配色/字体/间距等
│   └── sections/                  #   header-group / footer-group 配置
├── bags/    bike/    book/        # 包袋 / 单车 / 图书 ……（共 24 套）
├── boutique/  ceramic/  christmas/
├── coffee/    electronic/ grove/
├── gym/       halloween/ jewelry/
├── keyboard/  main/      parade/
├── pet/       pod/       sapphire/
├── smartlight/ sneaker/  speaker/
├── surfboard/ watch/

每套包含 home.json（页面布局 JSON）+ settings_data.json（样式配置）+ sections/（header/footer 分组）。用于模版装修工作流中参考或复制。

13. 外部配置文件

不在 skill 目录内，但被脚本引用。

%APPDATA%/LobsterAI/data/fecify-shared/
├── image-ai-config.json           # AI 生图 Provider 配置
│                                  # scripts/image-gen/config.js 管理
│
%APPDATA%/LobsterAI/data/
└── fecify-sessions.json           # 多店铺会话配置
                                   # scripts/base/site-config.js 管理

与 skill 本体分离的好处：skill 更新不覆盖配置，数据持久化跨版本。

14. 扩展机制

docs/extending.md 定义了两种扩展方式：

14.1 新增业务模块（3 步）

步骤 1：docs/schemas/<module>.json   ← 创建 Schema
步骤 2：SKILL.md 模块路由表新增一行   ← 注册入口
步骤 3：docs/<module>.md（可选）      ← 模块注意事项
步骤 4：验证 → api-doc.js --module=<module>

14.2 新增 CSV 格式支持（5 个文件）

步骤 1：scripts/product-csv-import/detect-<平台>-csv.js   ← 格式检测器
步骤 2：scripts/product-csv-import/import-<平台>-csv.js   ← 导入器
步骤 3：docs/product-csv-import/<平台>-csv-product-import.md ← 文档
步骤 4：更新 product-csv-import.md 表格
步骤 5：更新 SKILL.md 命令参考

详细的检查清单见 docs/extending.md（含 detect 输出格式/import CLI 参数/buildFecifyJSON 结构）。

15. 架构全景图

┌─────────────────────────────────────────────────────────────┐
│                      FECIFY SKILL                           │
├─────────────────────────────────────────────────────────────┤
│  SKILL.md                                                   │
│  ├── Frontmatter（name/version/description）                 │
│  ├── 铁律（5 条全局 + 模块级铁律）                            │
│  ├── 会话管理（check-config → save-config）                  │
│  ├── 通用 API 调用（api-call.js 4 种模式 + 响应码）           │
│  └── 模块路由表（8 域 18 模块，最少信息决策）                 │
│       ↓ 路由                                                 │
├─────────────────────────────────────────────────────────────┤
│  docs/                                                      │
│  ├── <模块>.md                   第 2 层 模块指引              │
│  │   ├── 脚本速查表                                         │
│  │   ├── API 速查表                                         │
│  │   ├── 工作流说明                                         │
│  │   ├── 易错点                                             │
│  │   └── 相关链接                                           │
│  │       ↓ 路由                                             │
│  ├── <模块>/<API>.md             第 3 层 API 参数             │
│  │   └── 方法/路径/参数表/示例                                │
│  ├── <模块>/workflow-*.md        工作流文档                   │
│  │   └── 铁律+Phase 分步+Task Schema+坑                      │
│  ├── schemas/*.json              API 数据源（21 个模块）       │
│  ├── theme/                      模版装修全套文档              │
│  ├── extending.md                扩展指南                     │
│  └── architecture.md             架构说明                     │
├─────────────────────────────────────────────────────────────┤
│  scripts/                                                   │
│  ├── base/                       基础设施                   │
│  │   ├── api-client.js           HTTP 客户端                │
│  │   ├── site-config.js          配置读写                   │
│  │   ├── check-config.js         配置检查 CLI               │
│  │   ├── save-config.js          配置保存 CLI               │
│  │   └── reload-init.js          init 重载 CLI              │
│  ├── proxy/                      CLI 入口                   │
│  │   ├── api-call.js             API 调用代理 ★             │
│  │   └── api-doc.js              Schema 查询                │
│  ├── image/                      图片上传                   │
│  ├── image-gen/                  AI 生图引擎                │
│  ├── language/                   翻译引擎                   │
│  ├── collection/                 专辑业务                   │
│  ├── product/                    商品业务                   │
│  ├── product-csv-import/         CSV 导入                   │
│  ├── review-csv-import/          评论导入                   │
│  └── theme/                      模版工具                   │
├─────────────────────────────────────────────────────────────┤
│  外部                                                       │
│  ├── fecify-shared/image-ai-config.json   AI配置            │
│  └── fecify-sessions.json                会话配置           │
└─────────────────────────────────────────────────────────────┘