skill-core-guide
v1.0.4
Published
Fmode Harness 平台母技能标准指南:平台端点真值表、ESM-first 四端标准、四渠道分发、六项自动质检、一键凭证供给、新技能脚手架。
Maintainers
Readme
skill-core-guide · Fmode Harness 平台母技能标准指南
一份可独立阅读的 Fmode 技能开发规范。读它不需要先读任何别的文档。 它是 Fmode 技能生态的「宪法」——定义平台真值、包结构、分发渠道、质检标准。
这是什么
skill-core-guide 是 Fmode Harness 平台的母技能。它同时是:
- 一份规范文档 ——
SKILL.md是完整的平台开发标准,可独立阅读 - 一套可执行工具 —— CLI + SDK 帮你脚手架、质检、发布新技能
- 一个真值源 —— 平台端点实测状态表,代码可 import,避免硬编码与「文档说能跑」的假象
解决的问题:Fmode 技能生态过去没有统一标准 —— 端点状态靠口口相传、 包结构各写各的、发布流程记在脑子里、质检靠人工、凭据配置踩坑反复。 本技能把这一切固化成可执行、可验证、可复用的规范。
三分钟上手
# 创建一个新技能(脚手架)
npx --yes skill-core-guide@latest init my-thing --name skill-my-thing
# 检查你的技能(六项自动质检)
npx --yes skill-core-guide@latest check .
# 生成四渠道发布计划
npx --yes skill-core-guide@latest publish .
# 查看平台端点真值表(哪些真的能调)
npx --yes skill-core-guide@latest endpoints
# 检查/初始化 Fmode 凭据
npx --yes skill-core-guide@latest bootstrap核心内容
| 章节 | 内容 | 位置 |
|------|------|------|
| 平台基础设施规范 | 基址、.fmode/ 机制、端点真值表(实测状态) | SKILL.md §1 |
| 技能分类体系 | 系统层 / 服务层 / 应用层 + 命名规则 | SKILL.md §2 | inventory.md |
| ESM-first 打包标准 | 包结构、package.json 约束、四端等价性 | SKILL.md §3 |
| 多渠道分发 | Gogs / GitHub / npm / skillhub.cn | SKILL.md §4 |
| 自动质检与看板 | 六项检查、skip≠pass 语义、看板 manifest | SKILL.md §5 |
| 一键凭证供给 | 5 级凭据链、诚实自举 | SKILL.md §6 |
| 新技能开发 SOP | 11 步完整流程 + 开发纪律 | SKILL.md §7 |
| 事故复盘 | 规范里每条 ⚠️ 背后的真实事故 | SKILL.md §8 |
六项自动质检
skill-core check .| # | 检查项 | 验证方式 |
|---|--------|----------|
| 1 | 功能完整性 | 运行 scripts.test / test/*.mjs |
| 2 | Fmode API 联通 | 探测 api.fmode.cn 与 server.fmode.cn |
| 3 | 基础 SOP 跑通 | skillhub publish --dry-run + frontmatter 校验 |
| 4 | 看板后台就绪 | skill-package-manifest.json 存在且合法 |
| 5 | Loop 迭代能力 | npm view(轻量)/ npx --yes(--deep) |
| 6 | 多端可用性 | 实测 ESM import + CLI --help |
结果语义:pass(有证据通过)/ fail(明确失败,exit 1)/ skip(无法验证,不算通过,exit 3)。
🎯
skip ≠ pass是本平台最贵的一课:端点 404 却被当成成功, 「能跑通」只是历史遗留配置的假象。详见 SKILL.md §8.1。
平台端点真值表(实测 2026-09-22)
| 端点 | 状态 | 用途 |
|------|------|------|
| api.fmode.cn/v1/chat/completions | ✅ live | LLM 调用(统一出口) |
| api.fmode.cn/v1/images/generations | ✅ live | 图像生成 |
| server.fmode.cn/api/listen/transcribe | ✅ live | 录音转写 |
| server.fmode.cn/api/fmode/voc-skill/install-prompt | ✅ live | 凭据自举(唯一通道) |
| server.fmode.cn/api/apig/deploy/huaweicloud | ✅ live | 项目隔离 OBS STS |
| server.fmode.cn/api/storage/upload | 🕓 planned | 未上线,走 obsutil 直传 |
| server.fmode.cn/api/storage/credentials | ✗ deprecated | 从未上线(伪自举事故源) |
| server.fmode.cn/api/image/generate | 🕓 planned | 未上线,用 /v1/images/generations |
| server.fmode.cn/api/vision/analyze | 🕓 planned | 未上线,用多模态 chat |
| server.fmode.cn/api/fmode/verifycode | 🕓 planned | 未上线,用 sessionToken 路径 |
⚠️
planned/deprecated端点调用前必须探测并回落,禁止当作已上线。 完整说明:npx --yes skill-core-guide@latest endpoints
四端可用性
| 端 | 入口 | 用法 | 状态 |
|----|------|------|------|
| CLI | bin/skill-core.mjs | npx --yes skill-core-guide@latest <cmd> | ✅ |
| SDK | lib/index.mjs | import { ... } from 'skill-core-guide' | ✅ |
| Browser | browser/index.mjs | <script type="module">(无 Node 依赖) | ✅ |
| Server | — | require('skill-core-guide') | ❌ ESM only |
// SDK
import { PLATFORM, ENDPOINTS, runChecks, bootstrap, INVENTORY } from 'skill-core-guide';
// 浏览器
import { PLATFORM, checkApiConnectivity } from 'skill-core-guide/browser';各工具安装
Claude Code
npx --yes skill-core-guide@latest workspace任意 Agent(读 README 自行安装)
git clone https://github.com/fmodecn/skill-core-guide.git
cp -r skill-core-guide/skills/skill-core-guide <你的工具技能目录>/skill-core-guideCodex / Gemini CLI
把 skills/skill-core-guide/SKILL.md 的内容并入 AGENTS.md(Codex)
或 ~/.gemini/commands/(Gemini CLI)。
npm / skillhub
npm install skill-core-guide
skillhub install fmode-skill-core-guide # ⚠️ 待 key 补发,见下方渠道现状⚠️ skillhub.cn 渠道现状(2026-09-22 实测):企业 key(
sk-ent-...)调用发布接口 返回 401invalid or expired token。本技能的打包与--dry-run预检均已通过 (slug=fmode-skill-core-guide),待重新签发 key 后补发。
技能清单
完整清单(16 个技能,含标签、版本、渠道、状态)见 inventory.md。
npx --yes skill-core-guide@latest inventory| 分层 | 技能 |
|------|------|
| 系统层(7) | skill-heterarchy · skill-multi-branch · skill-bypass-permission · skill-task-progress · plugin-wecom-fix · skill-agent-clone · skill-core-guide |
| 服务层(6) | skill-storage · skill-image · skill-vision · skill-listen · fmode-ffmpeg · fmode-qiwei |
| 应用层(3) | skill-study-report · skill-present · fmode-product-lab |
交付状态(2026-09-22 实测)
| 渠道 | 状态 | 验证方式 |
|------|------|----------|
| Gogs | ✅ 已发布 | git.fmode.cn/api/v1/repos/search?q=skill-core-guide → 200 |
| GitHub | ✅ 已发布 | api.github.com/repos/fmodecn/skill-core-guide → 13 项内容 |
| npm | ✅ 已发布 | npm view skill-core-guide version → 1.0.0 |
| skillhub.cn | ⚠️ 受阻 | 企业 key 服务端 401 invalid or expired token(预检已通过,待补发) |
六项自动质检:6 通过 / 0 失败 / 0 未验证(含 --deep 真实 npx 拉取验证)。
凭据(零密钥入库)
Fmode 标准 5 级凭据链,命中即用,全失败显式报错(绝不伪装成功):
第0级 FMODE_SESSION_TOKEN / ~/.fmode/config.json 的 sessionToken → 自举换 API token
第1级 环境变量 FMODE_API_TOKEN
第2级 ~/.fmode/config.json → fmodeApiToken
第3级 <cwd>/.fmode/config.json → fmodeApiToken
第4级 ~/.claude/settings.json → env.ANTHROPIC_AUTH_TOKEN检查:npx --yes skill-core-guide@latest bootstrap
⚠️ 任务书描述的「手机号+验证码」开户路径依赖
/api/fmode/verifycode, 该端点当前实测 404(未上线)。本技能不伪造短信流程, 真实可用路径是 sessionToken 自举。详见 SKILL.md §6。
CLI 命令
skill-core init [dir] 从脚手架创建新技能
skill-core check [dir] 运行六项自动质检
skill-core verify [dir] 静态校验(不执行代码)
skill-core publish [dir] 生成四渠道发布计划
skill-core inventory 输出技能清单
skill-core bootstrap 一键凭证供给
skill-core spec 输出平台规范摘要
skill-core endpoints 输出端点真值表仓库结构
skill-core-guide/
├── SKILL.md # ★ 完整规范文档(可独立阅读)
├── README.md # 本文件
├── inventory.md # 完整技能清单
├── package.json # ESM, zero-dependency
├── lib/
│ ├── index.mjs # ESM 入口(平台常量 + 校验器 + 分发计划)
│ ├── platform.mjs # ★ 端点真值表(single source of truth)
│ ├── check.mjs # ★ 六项质检引擎
│ ├── bootstrap.mjs # ★ 诚实凭证供给
│ └── inventory.mjs # 技能清单真值
├── bin/
│ └── skill-core.mjs # CLI
├── browser/
│ └── index.mjs # 浏览器 bundle(无 Node 依赖)
├── templates/
│ └── skill-starter/ # ★ 新技能脚手架(可跑通)
├── test/
│ └── smoke.mjs # 冒烟测试
├── LICENSE # MIT
└── skill-package-manifest.json # 看板数据源开发
npm test # 冒烟测试
node bin/skill-core.mjs check . --offline # 自检(离线)
node bin/skill-core.mjs verify . # 静态校验Changelog
1.0.0
- 首版:平台端点真值表(实测 2026-09-22)、技能三层清单(17 个)、 ESM-first 四端标准、四渠道分发、六项自动质检、诚实凭证供给、脚手架模板
- 端点真值修正:任务书描述的
/api/storage/upload、/api/image/generate、/api/vision/analyze、/api/fmode/verifycode实测均为 404(planned), 已在真值表中标注并给出替代路径 - 真实端点补充:
/v1/images/generations(live)、/api/apig/deploy/huaweicloud(live)、/api/fmode/voc-skill/install-prompt(live,凭据自举唯一通道)
License
MIT © 2026 Fmode (未来飞马)
