skill入口文件-skill.md

在fecify skill的根目录，即可看到skill.md文件

定位

SKILL.md 是 Fecify Skill 的唯一入口。它不包含任何 API 细节，只做一件事：根据用户意图，把 Agent 路由到正确的模块文档。

在整个三层递进式结构中，它位于第 1 层（调度摘要）。

文件结构（5 个部分）

SKILL.md
├── Part 0: Frontmatter（元信息）
├── Part 1: 铁律（全局通用 5 条）
├── Part 2: 会话（启动 + 隔离）
├── Part 3: 通用 API 调用（4 种调用模式 + 响应码）
└── Part 4: 模块路由表（8 个业务域，18 个模块）

Part 0：Frontmatter

---
name: fecify-site-manager-v2
version: "2"
description: >
  Fecify 独立站管理。会话绑定站点（URL + Token），配置持久化。
  商品/专辑/博客/图片/AI图片生成/系统配置/权限/物流/税费/订单。相关处理全链路覆盖。
---

YAML 格式，包含三字段：

字段	说明	示例
`name`	技能标识，系统注册用	`fecify-site-manager-v2`
`version`	版本号，字符串格式	`"2"`
`description`	一句话能力概述，帮助系统/用户快速理解	"Fecify 独立站管理..."

这是系统级元数据，不参与 Agent 的调度逻辑。

Part 1：铁律（全局通用）

1. 严禁自行构造 API 路径或猜测端点
2. 必须用 api-doc.js 或直接读文档查询参数
3. 标注「待编写」的模块不可调用
4. 临时文件只进 temp/，图片进 temp/images/
5. 打包 zip 排除 memory/、temp/、MEMORY.md

5 条铁律，覆盖三个维度：

维度	对应的律	防止的问题
API 调用安全	1、2	Agent 凭记忆猜 API 路径/参数，导致错误
模块可用性	3	调用未实现的功能，无文档参考
文件安全	4、5	临时文件污染 skill 根目录、用户数据泄露

铁律高于一切——Agent 必须在任何操作前确保不违反。

模版装修模块有独立铁律体系（docs/theme.md），不在此处列出。

Part 2：会话管理

启动:
  node scripts/base/check-config.js
  → 未配置：引导用户提供 URL + Token
  → 已配置：显示当前站点 URL

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

两个职责：

启动检查 — 每次新会话进来看是否绑定了店铺。未绑定就引导配置。
多店铺隔离 — 通过环境变量区分不同店铺的会话，避免数据串扰。

相关底层脚本：scripts/base/check-config.js、scripts/base/save-config.js、scripts/base/site-config.js。

Part 3：通用 API 调用

定义 Agent 调用 API 的唯一方式，4 种模式：

GET 模式:
  api-call.js GET /api/skill/<path>

POST - stdin 模式（短 JSON）:
  echo "{...}" | api-call.js POST /api/skill/<path>

POST - --data 模式（长 JSON，推荐）:
  api-call.js POST /api/skill/<path> --data body.json

参数查询:
  api-doc.js --module=<模块>     # 列出模块下所有 API
  api-doc.js --api=<模块>/<api>  # 查看指定 API 参数
  api-doc.js --search=关键词      # 搜索 API

响应码速查：

code	含义	Agent 行为
`200`	成功	继续
`-1`	网络错误	可重试
`10000011` / `10000014` / `10000025`	架构拦截	停止，不重试

这是整个 skill 最重要的部分之一——Agent 所有 API 调用必须经过 api-call.js，不允许直接 curl。

Part 4：模块路由表

按业务域分为 8 组，共 18 个模块：

业务域	模块数	模块
商品	3	商品 CRUD / 商品专辑 / 商品评论
内容	3	博客文章 / 博客专辑 / 自定义页面
客户与订单	3	客户管理 / 订单管理 / 优惠券管理
店铺配置	4	店铺信息 / 菜单管理 / 系统配置 / 刷新缓存
运营	6	权限管理 / 系统物流 / 系统税费 / URL 重定向 / 系统任务 / 数据统计
模版装修	1	模版装修
图片	2	图片管理 / AI 图片生成
插件	1	多语言

每个模块的路由信息拆为 4 列：

列	内容	作用
模块	中文功能名	快速识别
能力摘要	该模块能做什么 + workflow 名称 + 脚本引用	判断是否匹配用户需求
⚠️ 易错点	常见踩坑（一行概括）	避免常见错误
入口	链接到第 2 层 + 关联 workflow	精确路由

设计原则

"最少信息决策" — 每个模块行只给足够 Agent 判断"该不该去"的信息，不多不少。

太多信息 → 浪费 Token，SKILL.md 膨胀
太少 → Agent 判断不了要去哪个模块
易错点一行 → 足够提醒，细节在第 2 层展开

SKILL.md 在整个 skill 中的角色

用户请求
    ↓
SKILL.md（本文件）
    ├── 铁律检查：操作合法吗？
    ├── 模块匹配：去哪个模块文档？
    └── 路由输出：docs/<模块>.md
              ↓
         docs/<模块>.md（第 2 层）
              ├── API 速查表：用哪个 API？
              └── 路由输出：docs/<模块>/<API>.md
                        ↓
                   docs/<模块>/<API>.md（第 3 层）
                        ├── 参数字段名和类型
                        └── 构造 api-call.js 命令执行

维护约定

不写 API 细节 — 参数、示例代码都不放在 SKILL.md，放在第 2/3 层
易错点一行 — 不超过一句话，详细说明留给第 2 层
新增模块 — 在对应业务域下新增一行，同时在 docs/ 下创建对应文件
模块改名 — 同步更新 SKILL.md 的路由表和第 2 层入口链接
铁律变更 — 仅当影响所有模块时才更新全局铁律；模块特有约束写在对应 .md 中

入口文件-skill.md