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-guide

Codex / 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-...）调用发布接口返回 401 invalid 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，凭据自举唯一通道）

README.md 11 KB

Előzmények Nyers

skill-core-guide · Fmode Harness 平台母技能标准指南

这是什么

三分钟上手

核心内容

六项自动质检

平台端点真值表（实测 2026-09-22）

四端可用性

各工具安装

Claude Code

任意 Agent（读 README 自行安装）

Codex / Gemini CLI

npm / skillhub

技能清单

交付状态（2026-09-22 实测）

凭据（零密钥入库）

CLI 命令

仓库结构

开发

Changelog

1.0.0

License

README.md 11 KB Előzmények Nyers

skill-core-guide · Fmode Harness 平台母技能标准指南

这是什么

三分钟上手

核心内容

六项自动质检

平台端点真值表（实测 2026-09-22）

四端可用性

各工具安装

Claude Code

任意 Agent（读 README 自行安装）

Codex / Gemini CLI

npm / skillhub

技能清单

交付状态（2026-09-22 实测）

凭据（零密钥入库）

CLI 命令

仓库结构

开发

Changelog

1.0.0

License

README.md 11 KB

Előzmények Nyers