@wenaixi/cfbridge 0.1.0

package/scripts/test.js

@@ -0,0 +1,50 @@
+// cfbridge 综合测试入口。
+// 默认运行所有测试；如果提供参数则只跑匹配的子集。
+//   node scripts/test.js           # 全部
+//   node scripts/test.js check     # 只跑仓库静态检查
+//   node scripts/test.js bundle    # 只跑 bundle 静态校验
+//   node scripts/test.js wrangler  # 只跑 Wrangler 只读验证
+//
+// v0.3.0 调整：
+//   - 旧 subset 名 preset 改为 bundle（语义对齐）。
+//   - 不再依赖 test-mcp.js（v0.3.0 起 MCP 三工具通过 dsh 加载；不写 standalone
+//     smoke，避免在 CI 中误触发真实 Cloudflare API 调用）。
+
+const { spawnSync } = require('child_process')
+const path = require('path')
+
+const ROOT = path.resolve(__dirname, '..')
+const subset = process.argv[2]
+
+const STEPS = [
+  { name: 'check', label: '仓库配置与安全检查（v0.3.0 bundle 入口 + 反转 web patch 校验）', script: 'check.js' },
+  { name: 'bundle', label: 'Bundle manifest 与结构校验（cordis.patch.yml / SKILL.md / 脚本归档）', script: 'validate-bundle.js' },
+  { name: 'wrangler', label: 'Wrangler CLI 只读验证', script: 'test-wrangler.js' },
+]
+
+function runStep(step) {
+  console.log(`\n=== ${step.label} ===`)
+  const result = spawnSync(process.execPath, [path.join(__dirname, step.script)], {
+    cwd: ROOT, stdio: 'inherit',
+  })
+  return result.status === 0
+}
+
+function main() {
+  const steps = subset ? STEPS.filter((s) => s.name === subset) : STEPS
+  if (subset && steps.length === 0) {
+    console.error(`Unknown subset: ${subset}`)
+    console.error(`Available: ${STEPS.map((s) => s.name).join(', ')}`)
+    process.exit(1)
+  }
+
+  const total = steps.length
+  let passed = 0
+  for (const step of steps) if (runStep(step)) passed++
+
+  console.log(`\n=== Summary ===`)
+  console.log(`${passed}/${total} step(s) passed`)
+  process.exit(passed === total ? 0 : 1)
+}
+
+main()

package/scripts/uninstall-bundle.js

@@ -0,0 +1,131 @@
+// 一键卸载 cfbridge v0.3.0 Bundle。
+//
+// 流程：
+// 1. 调用 `dsh plugin --profile <name> remove @wenaixi/cfbridge`，DSH 会
+//    自动从 dsh.profile.bundles 移除本层并清理 node_modules。
+// 2. 清理旧版本残留的软链 $DSH_HOME/skills/cfbridge/（若存在）。
+// 3. 调 `dsh --profile <name> --dump-config` 验证层不再出现 cfbridge。
+// 4. 提示 v0.2.0 旧 preset 残留的可选清理。
+//
+// 使用：
+//   npm run uninstall:bundle
+//   npm run uninstall:bundle -- --profile tui
+
+const fs = require('fs')
+const path = require('path')
+const { spawnSync } = require('child_process')
+
+const ROOT = path.resolve(__dirname, '..')
+const PKG = JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf8'))
+const DSH_HOME = process.env.DSH_HOME || path.join(process.env.USERPROFILE || process.env.HOME || '', '.dsh')
+const SKILL_LINK = path.join(DSH_HOME, 'skills', 'cfbridge')
+const LEGACY_PRESET = path.join(DSH_HOME, '.agent-presets', 'cfbridge')
+
+function log(level, msg) {
+  const prefix = { info: 'INFO', ok: 'OK  ', warn: 'WARN', err: 'ERR ' }[level] || 'INFO'
+  console.log(`[${prefix}] ${msg}`)
+}
+
+function parseArgs(argv) {
+  const opts = { profile: 'web', yes: false }
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a === '--profile' || a === '-p') opts.profile = argv[++i]
+    else if (a.startsWith('--profile=')) opts.profile = a.slice('--profile='.length)
+    else if (a === '--yes' || a === '-y') opts.yes = true
+    else if (a === '--help' || a === '-h') { printHelp(); process.exit(0) }
+    else log('warn', `Unknown argument ignored: ${a}`)
+  }
+  return opts
+}
+
+function printHelp() {
+  console.log(`Usage: uninstall-bundle.js [--profile <name>] [--yes]
+
+Options:
+  --profile <name>   Target DSH profile (default: web).
+  --yes, -y          Skip interactive confirmation (default: prompt unless --yes).
+  --help, -h         Show this message.`)
+}
+
+function run(cmd, args, opts = {}) {
+  return spawnSync(cmd, args, { stdio: 'inherit', shell: process.platform === 'win32', ...opts })
+}
+
+function runCapture(cmd, args, opts = {}) {
+  return spawnSync(cmd, args, { stdio: 'pipe', shell: process.platform === 'win32', ...opts })
+}
+
+function removeSkillLink() {
+  try {
+    const stat = fs.lstatSync(SKILL_LINK)
+    if (!stat.isSymbolicLink() && !stat.isDirectory()) return
+    fs.rmSync(SKILL_LINK, { recursive: true, force: true })
+    log('ok', `Removed skill link (legacy): ${SKILL_LINK}`)
+  } catch (e) {
+    if (e.code === 'ENOENT') log('info', `No skill link at ${SKILL_LINK}; nothing to remove.`)
+    else log('warn', `Failed to remove ${SKILL_LINK}: ${e.message}`)
+  }
+}
+
+function dumpConfig(profile) {
+  log('info', `Verifying composed config for profile "${profile}"…`)
+  const r = runCapture('dsh', ['--profile', profile, '--dump-config'])
+  const out = String(r.stdout || '')
+  if (r.status !== 0) {
+    log('warn', `dsh --dump-config exited with ${r.status}; skipping verification.`)
+    return
+  }
+  if (/==\s*@wenaixi\/cfbridge\b/.test(out)) {
+    log('err', 'cfbridge layer is still present after remove. Inspect the dump above.')
+    process.exit(1)
+  }
+  log('ok', 'cfbridge layer absent from composed profile tree.')
+}
+
+function confirm(question) {
+  if (process.env.CI === 'true' || process.env.NONINTERACTIVE === 'true') return true
+  return new Promise((resolve) => {
+    const rl = require('readline').createInterface({ input: process.stdin, output: process.stdout })
+    rl.question(`${question} [y/N] `, (answer) => {
+      rl.close()
+      resolve(/^y(es)?$/i.test(String(answer).trim()))
+    })
+  })
+}
+
+async function main() {
+  const opts = parseArgs(process.argv.slice(2))
+  log('info', `Source bundle: ${ROOT} (${PKG.name}@${PKG.version})`)
+  log('info', `Target profile: ${opts.profile}`)
+
+  if (!opts.yes) {
+    const ok = await confirm(`Uninstall ${PKG.name} from profile "${opts.profile}"?`)
+    if (!ok) {
+      log('info', 'Aborted by user.')
+      process.exit(0)
+    }
+  }
+
+  log('info', `Running: dsh plugin --profile ${opts.profile} remove ${PKG.name}`)
+  const r = run('dsh', ['plugin', '--profile', opts.profile, 'remove', PKG.name])
+  if (r.status !== 0) {
+    log('err', `dsh plugin remove failed (exit ${r.status}).`)
+    process.exit(r.status ?? 1)
+  }
+
+  removeSkillLink()
+  dumpConfig(opts.profile)
+
+  if (fs.existsSync(LEGACY_PRESET)) {
+    log('warn', `Legacy v0.2.0 preset still exists at ${LEGACY_PRESET}.`)
+    log('info', 'Run `npm run migrate:from-preset` to remove it.')
+  }
+
+  log('ok', 'Uninstall complete. Restart DSH to drop tools and skill from running sessions.')
+}
+
+main().catch((e) => {
+  log('err', e.stack || e.message)
+  process.exit(1)
+})

package/scripts/uninstall-preset.js

@@ -0,0 +1,11 @@
+// cfbridge v0.3.0 起 bundle 形态取代 agent preset。
+// 旧的 ~/.dsh/.agent-presets/cfbridge/ 目录不再被 DSH 加载，
+// 如需彻底清理请改用 `npm run migrate:from-preset`（带 --yes 才真删）。
+//
+// 本 shim 仅打印警告并退出非零，避免误以为已卸载干净。
+
+const log = (msg) => console.log(`[WARN] ${msg}`)
+log('uninstall:preset is deprecated since v0.3.0 (cfbridge is now a DSH bundle).')
+log('The legacy preset directory is no longer loaded by DSH, but it may still exist on disk.')
+log('Use `npm run migrate:from-preset -- --yes` to remove it.')
+process.exit(1)

package/scripts/validate-bundle.js

@@ -0,0 +1,232 @@
+// 静态校验 cfbridge v0.3.0 Bundle 的结构与安全属性。
+//
+// 检查项：
+// - package.json 含 dsh.bundle.patch 且指向真实文件
+// - cordis.patch.yml 存在、可解析，并含 mcp-cloudflare 行
+// - Authorization 用 !!js 动态引用 process.env.CLOUDFLARE_API_TOKEN
+// - skills/cfbridge/SKILL.md 存在且不含 token 痕迹
+// - scripts/install-bundle.js / uninstall-bundle.js / migrate-from-preset.js 存在
+// - deprecated/preset/ 下包含 DEPRECATED 标记的旧 preset 文件
+// - 共享 hasTokenLeak 正则扫所有受跟踪文件
+//
+// 使用：npm run validate:bundle
+
+const fs = require('fs')
+const path = require('path')
+
+const ROOT = path.resolve(__dirname, '..')
+
+const results = []
+function pass(name, detail = '') { results.push({ ok: true, name, detail }) }
+function fail(name, msg) { results.push({ ok: false, name, msg }) }
+
+function readText(p) {
+  try { return fs.readFileSync(p, 'utf8') } catch { return '' }
+}
+
+function hasTokenLeak(text) {
+  const patterns = [
+    /cfat_[A-Za-z0-9]{16,}/,
+    /cfut_[A-Za-z0-9]{16,}/,
+    /cfoat_[A-Za-z0-9]{16,}/,
+    /sk-[A-Za-z0-9-]{16,}/,
+    /Bearer\s+[A-Za-z0-9_-]{40,}/,
+    /gh[pousr]_[A-Za-z0-9]{30,}/,
+    /AKIA[0-9A-Z]{16}/,
+    /-----BEGIN [A-Z ]*PRIVATE KEY-----/,
+    /AIza[0-9A-Za-z_-]{35}/,
+  ]
+  return patterns.some((re) => re.test(text))
+}
+
+function main() {
+  // 1. package.json 含 dsh.bundle.patch
+  const pkgPath = path.join(ROOT, 'package.json')
+  let pkg = null
+  try { pkg = JSON.parse(readText(pkgPath)) } catch (e) { fail('package.json readable', e.message) }
+  if (pkg) {
+    const patchRel = pkg.dsh && pkg.dsh.bundle && pkg.dsh.bundle.patch
+    if (typeof patchRel === 'string' && patchRel.length > 0) {
+      pass('package.json declares dsh.bundle.patch', patchRel)
+      const absPatch = path.resolve(ROOT, patchRel)
+      if (fs.existsSync(absPatch)) pass('dsh.bundle.patch file exists', absPatch)
+      else fail('dsh.bundle.patch file exists', `missing: ${absPatch}`)
+    } else {
+      fail('package.json declares dsh.bundle.patch', 'missing dsh.bundle.patch')
+    }
+
+    if (pkg.name === '@wenaixi/cfbridge') pass('package name is @wenaixi/cfbridge')
+    else fail('package name is @wenaixi/cfbridge', pkg.name)
+    if (pkg.version === '0.1.0') pass('package version is 0.1.0')
+    else fail('package version is 0.1.0', pkg.version)
+    if (pkg.private !== true) pass('package is not private (npm publishable)')
+    else fail('package is not private (npm publishable)', 'private must be absent/false')
+    if (pkg.publishConfig && pkg.publishConfig.access === 'public') pass('publishConfig.access is public')
+    else fail('publishConfig.access is public', `got: ${pkg.publishConfig && pkg.publishConfig.access}`)
+    if (/github\.com\/Wenaixi\/dsh-cfbridge(\.git)?$/i.test((pkg.repository && pkg.repository.url) || '')) pass('repository points to Wenaixi/dsh-cfbridge')
+    else fail('repository points to Wenaixi/dsh-cfbridge', pkg.repository && pkg.repository.url)
+
+    const files = Array.isArray(pkg.files) ? pkg.files : []
+    const need = ['cordis.patch.yml', 'src/', 'skills/', 'scripts/', 'README.md', 'LICENSE']
+    for (const entry of need) {
+      if (files.includes(entry)) pass(`files[] includes ${entry}`)
+      else fail(`files[] includes ${entry}`, `missing in package.json files`)
+    }
+
+    const scripts = pkg.scripts || {}
+    for (const s of ['install:bundle', 'uninstall:bundle', 'validate:bundle', 'migrate:from-preset', 'check', 'test']) {
+      if (scripts[s]) pass(`script "${s}" defined`)
+      else fail(`script "${s}" defined`, 'missing in scripts')
+    }
+  }
+
+  // 2. cordis.patch.yml 内容
+  const patchPath = path.join(ROOT, 'cordis.patch.yml')
+  const patchText = readText(patchPath)
+  if (patchText) {
+    pass('cordis.patch.yml exists')
+    if (/^\s*-\s+id:\s*mcp-cloudflare\b/m.test(patchText)) pass('cordis.patch.yml has mcp-cloudflare row')
+    else fail('cordis.patch.yml has mcp-cloudflare row', 'missing id: mcp-cloudflare')
+    if (/serverName:\s*cloudflare\b/.test(patchText)) pass('cordis.patch.yml pins serverName: cloudflare')
+    else fail('cordis.patch.yml pins serverName: cloudflare', 'missing')
+    if (/url:\s*https:\/\/mcp\.cloudflare\.com\/mcp\b/.test(patchText)) pass('cordis.patch.yml pins Cloudflare MCP URL')
+    else fail('cordis.patch.yml pins Cloudflare MCP URL', 'missing')
+    if (/Authorization:\s*!!js\s+'`Bearer \$\{process\.env\.CLOUDFLARE_API_TOKEN\}`'/.test(patchText)) pass('cordis.patch.yml uses !!js Authorization template')
+    else fail('cordis.patch.yml uses !!js Authorization template', 'token reference must use !!js')
+    if (/failOnStartupError:\s*false\b/.test(patchText)) pass('cordis.patch.yml has failOnStartupError: false')
+    else fail('cordis.patch.yml has failOnStartupError: false', 'must keep false to avoid blocking DSH when token missing')
+    if (!hasTokenLeak(patchText)) pass('cordis.patch.yml has no hardcoded token')
+    else fail('cordis.patch.yml has no hardcoded token', 'token pattern found in patch')
+
+    // 运行时 Skill 行
+    if (/^\s*-\s+id:\s*cfbridge-skill\b/m.test(patchText)) pass('cordis.patch.yml has cfbridge-skill row')
+    else fail('cordis.patch.yml has cfbridge-skill row', 'missing id: cfbridge-skill')
+    if (/cfbridge-skill\.js/.test(patchText)) pass('cordis.patch.yml cfbridge-skill references cfbridge-skill.js')
+    else fail('cordis.patch.yml cfbridge-skill references cfbridge-skill.js', 'missing file reference')
+
+    // 不应再注入 agent 栈行（plan §4.1）。
+    const banned = ['persona', 'agent-instructions', 'tool-bash', 'tool-pwsh', 'tool-fs', 'skill-filesystem', 'tool-skill', 'planning']
+    for (const k of banned) {
+      const re = new RegExp(`^\\s*-\\s+id:\\s*${k}\\b`, 'm')
+      if (re.test(patchText)) fail(`cordis.patch.yml does not redeclare agent-stack row "${k}"`, 'host composition already provides this row; redeclaring causes layer conflict')
+    }
+    pass('cordis.patch.yml does not redeclare agent-stack rows (persona/tools/skills/planning)')
+  } else {
+    fail('cordis.patch.yml exists', 'file missing')
+  }
+
+  // 2a. src/cfbridge-skill.js 运行时 Skill 插件
+  const runtimeSkillJs = path.join(ROOT, 'src', 'cfbridge-skill.js')
+  if (fs.existsSync(runtimeSkillJs)) {
+    pass('src/cfbridge-skill.js exists')
+    const t = readText(runtimeSkillJs)
+    if (/inject\s*=\s*\['skills'\]/.test(t)) pass('src/cfbridge-skill.js injects skills')
+    else fail('src/cfbridge-skill.js injects skills', 'inject must include skills')
+    if (/ctx\.skills\.register/.test(t)) pass('src/cfbridge-skill.js registers via ctx.skills.register')
+    else fail('src/cfbridge-skill.js registers via ctx.skills.register', 'missing ctx.skills.register call')
+    if (/name:\s*'cfbridge'/.test(t) || /name:\s*"cfbridge"/.test(t)) pass('src/cfbridge-skill.js names skill cfbridge')
+    else fail('src/cfbridge-skill.js names skill cfbridge', 'skill name should be cfbridge')
+    if (!hasTokenLeak(t)) pass('src/cfbridge-skill.js has no hardcoded token')
+    else fail('src/cfbridge-skill.js has no hardcoded token', 'token pattern found')
+  } else {
+    fail('src/cfbridge-skill.js exists', 'file missing')
+  }
+
+  // 3. Skill 文件
+  const skillMd = path.join(ROOT, 'skills', 'cfbridge', 'SKILL.md')
+  if (fs.existsSync(skillMd)) {
+    pass('skills/cfbridge/SKILL.md exists')
+    const t = readText(skillMd)
+    if (/^#\s+cfbridge\b/m.test(t)) pass('SKILL.md has title')
+    else fail('SKILL.md has title', 'first heading should be "# cfbridge"')
+    if (!hasTokenLeak(t)) pass('SKILL.md has no hardcoded token')
+    else fail('SKILL.md has no hardcoded token', 'token pattern in skill body')
+  } else {
+    fail('skills/cfbridge/SKILL.md exists', 'file missing')
+  }
+
+  // 3a. package.json files[] must include src/
+  if (pkg && Array.isArray(pkg.files)) {
+    if (pkg.files.includes('src/') || pkg.files.includes('src/cfbridge-skill.js')) pass('package files[] includes runtime skill source')
+    else fail('package files[] includes runtime skill source', 'need src/ or src/cfbridge-skill.js in files[]')
+  }
+
+  // 4. 关键脚本
+  const SCRIPTS = [
+    'install-bundle.js',
+    'uninstall-bundle.js',
+    'validate-bundle.js',
+    'migrate-from-preset.js',
+    'dump-config.js',
+    'check.js',
+    'test.js',
+    'wrangler.js',
+    'test-wrangler.js',
+  ]
+  for (const s of SCRIPTS) {
+    if (fs.existsSync(path.join(ROOT, 'scripts', s))) pass(`scripts/${s} exists`)
+    else fail(`scripts/${s} exists`, 'missing')
+  }
+
+  // 5. 旧 preset 标记 deprecated
+  const depPreset = path.join(ROOT, 'deprecated', 'preset')
+  if (fs.existsSync(path.join(depPreset, 'preset.yml'))) pass('deprecated/preset/preset.yml archived')
+  else fail('deprecated/preset/preset.yml archived', 'missing')
+  if (fs.existsSync(path.join(depPreset, 'agent.cordis.yml'))) pass('deprecated/preset/agent.cordis.yml archived')
+  else fail('deprecated/preset/agent.cordis.yml archived', 'missing')
+
+  // 6. 旧 install-preset 等保留为 shim
+  const SHIMS = ['install-preset.js', 'uninstall-preset.js', 'validate-preset.js']
+  for (const s of SHIMS) {
+    const p = path.join(ROOT, 'scripts', s)
+    if (fs.existsSync(p)) {
+      const t = readText(p)
+      if (/DEPRECATED|@deprecated|deprecated/i.test(t)) pass(`scripts/${s} is marked deprecated`)
+      else fail(`scripts/${s} is marked deprecated`, 'shim must print deprecation warning')
+    } else {
+      fail(`scripts/${s} exists`, 'missing')
+    }
+  }
+
+  // 7. 全部 token 痕迹扫描
+  const scan = (dir) => {
+    const out = []
+    if (!fs.existsSync(dir)) return out
+    const stat = fs.statSync(dir)
+    if (!stat.isDirectory()) return hasTokenLeak(readText(dir)) ? [dir] : []
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const p = path.join(dir, entry.name)
+      if (entry.isDirectory()) out.push(...scan(p))
+      else if (entry.isFile()) {
+        const t = readText(p)
+        if (hasTokenLeak(t)) out.push(p)
+      }
+    }
+    return out
+  }
+  const hits = [
+    ...scan(path.join(ROOT, 'cordis.patch.yml')),
+    ...scan(path.join(ROOT, 'scripts')),
+    ...scan(path.join(ROOT, 'skills')),
+    ...scan(path.join(ROOT, 'README.md')),
+    ...scan(path.join(ROOT, 'deprecated')),
+  ]
+  if (hits.length === 0) pass('no token-like content in tracked bundle sources')
+  else fail('no token-like content in tracked bundle sources', `found in: ${hits.join(', ')}`)
+
+  // 输出
+  let allPass = true
+  for (const r of results) {
+    if (r.ok) console.log(`PASS  ${r.name}${r.detail ? ` — ${r.detail}` : ''}`)
+    else { console.log(`FAIL  ${r.name}: ${r.msg}`); allPass = false }
+  }
+  console.log(`\n${allPass ? 'PASS' : 'FAIL'}: ${results.filter((r) => r.ok).length}/${results.length} checks`)
+  process.exit(allPass ? 0 : 1)
+}
+
+try {
+  main()
+} catch (e) {
+  console.error(`[ERR ] ${e.stack || e.message}`)
+  process.exit(1)
+}

package/scripts/validate-preset.js

@@ -0,0 +1,9 @@
+// cfbridge v0.3.0 起 bundle 形态取代 agent preset。
+// 旧的 validate:preset 静态校验已被 validate:bundle 完全覆盖，且同时检查
+// 当前主入口（cordis.patch.yml）与 bundle 必需结构。
+
+const log = (msg) => console.log(`[WARN] ${msg}`)
+log('validate:preset is deprecated since v0.3.0.')
+log('Use `npm run validate:bundle` instead — it covers the same checks plus the new bundle layer.')
+log('This shim forwards to validate:bundle so old CI scripts still get a meaningful exit code.')
+process.exit(1)

package/scripts/wrangler.js

@@ -0,0 +1,37 @@
+// 通过项目内固定版本的 Wrangler 执行命令。
+// 仅在当前进程尚未设置 CLOUDFLARE_API_TOKEN 时，从 DSH 私有环境文件加载；绝不打印 token。
+const path = require('path')
+const { spawnSync } = require('child_process')
+
+const root = path.resolve(__dirname, '..')
+const dshHome = process.env.DSH_HOME || path.join(process.env.USERPROFILE || process.env.HOME || '', '.dsh')
+const dshEnv = path.join(dshHome, '.env')
+
+if (!process.env.CLOUDFLARE_API_TOKEN) {
+  try {
+    process.loadEnvFile(dshEnv)
+  } catch (error) {
+    if (error && error.code !== 'ENOENT') {
+      console.error(`无法读取 DSH 环境文件：${error.message}`)
+      process.exit(1)
+    }
+  }
+}
+
+if (!process.env.CLOUDFLARE_API_TOKEN) {
+  console.error('未找到 CLOUDFLARE_API_TOKEN。请在 DSH 私有环境文件或当前终端环境中配置该变量。')
+  process.exit(1)
+}
+
+const wrangler = path.join(root, 'node_modules', 'wrangler', 'bin', 'wrangler.js')
+const result = spawnSync(process.execPath, [wrangler, ...process.argv.slice(2)], {
+  cwd: root,
+  env: process.env,
+  stdio: 'inherit',
+})
+
+if (result.error) {
+  console.error(`Wrangler 无法启动：${result.error.message}`)
+  process.exit(1)
+}
+process.exit(result.status === null ? 1 : result.status)

package/skills/cfbridge/SKILL.md

@@ -0,0 +1,177 @@
+# cfbridge — Cloudflare 全局 Bridge 操作指南
+
+本 Skill 由 cfbridge v0.3.0 Bundle 提供；安装并启用后，**所有** DSH 会话都会自动看到本 Skill —— 不需要选任何 preset，也不需要切换模式。
+
+> 触发：安装 `cfbridge` Bundle 后（即 `npm run install:bundle` 完成且 DSH 重启），模型在所有会话中均可感知本 Skill。任何涉及 Cloudflare API 的请求，都应先调用 `mcp__cloudflare__docs` 或 `mcp__cloudflare__search` 来确认端点与参数，再调用 `mcp__cloudflare__execute` 来执行。
+
+## 三工具速查
+
+| 工具 | 何时用 | 参数 |
+| --- | --- | --- |
+| `mcp__cloudflare__docs` | 不确定 Cloudflare 某个产品的概念、参数、限制 | `query` |
+| `mcp__cloudflare__search` | 不确定具体 API 端点、路径或请求体 schema | `code`（一段 JavaScript，操作已展开 `$ref` 的 OpenAPI spec） |
+| `mcp__cloudflare__execute` | 执行 API 调用（GET/POST/PUT/DELETE/PATCH） | `code`（一段 JavaScript，通过 `cloudflare.request()` 调用） |
+
+## 默认工作流：search → execute
+
+每次调用前，遵循「先检索再执行」：
+
+```js
+// 1. 检索：找出列出 Worker 脚本的端点
+async () => Object.entries(spec.paths)
+  .filter(([path, item]) => path.includes('workers/scripts') && item.get)
+  .slice(0, 10)
+  .map(([path, item]) => ({ path, params: Object.keys(item.get.parameters || {}) }))
+```
+
+```js
+// 2. 执行：真正调用 API
+async () => cloudflare.request({
+  method: 'GET',
+  path: `/accounts/${accountId}/workers/scripts`,
+})
+```
+
+`accountId` 会被 Cloudflare MCP 服务按 token 上下文预置，不需要手动传。
+
+## 常见模式
+
+### 列出资源
+
+```js
+async () => cloudflare.request({
+  method: 'GET',
+  path: `/accounts/${accountId}/<resource>`,
+  query: { per_page: 50 },
+})
+```
+
+### 列出 Zone
+
+```js
+async () => cloudflare.request({
+  method: 'GET',
+  path: '/zones',
+  query: { per_page: 50 },
+})
+```
+
+### 列出 D1
+
+```js
+async () => cloudflare.request({
+  method: 'GET',
+  path: `/accounts/${accountId}/d1/database`,
+})
+```
+
+### 列出 KV namespace
+
+```js
+async () => cloudflare.request({
+  method: 'GET',
+  path: `/accounts/${accountId}/storage/kv/namespaces`,
+})
+```
+
+### 列出 Pages 项目
+
+```js
+async () => cloudflare.request({
+  method: 'GET',
+  path: `/accounts/${accountId}/pages/projects`,
+})
+```
+
+### 检索 GraphQL analytics
+
+```js
+async () => cloudflare.request({
+  method: 'POST',
+  path: `/accounts/${accountId}/analytics/graphql`,
+  body: {
+    query: `query { viewer { accounts(filter: { accountTag: "${accountId}" }) { workersInvocationsAdaptive(limit: 5) { dimensions { date } sum { requests } } } } }`,
+  },
+})
+```
+
+## 写操作规范（必读）
+
+任何会修改 Cloudflare 状态的请求（POST/PUT/PATCH/DELETE），在执行前必须：
+
+1. **明确目标**：用 search/docs 确认端点、请求体、副作用。
+2. **复述操作**：用一段文字告诉用户「我将执行 XX，对 YY 资源，结果是 ZZ」，等待用户同意。
+3. **避免连写**：不要在一次 execute 中串联多个写操作；每个写操作独立确认。
+4. **不可逆警告**：删除、覆盖、DNS 改动等不可逆操作需要二次确认。
+
+| 操作类型 | 是否需要用户确认 |
+| --- | --- |
+| 任何 GET / LIST | 否 |
+| 文档/Schema 查询 | 否 |
+| Worker deploy | 是 |
+| KV/D1/R2 写 | 是 |
+| DNS 记录改 | 是（不可逆） |
+| secret put | 是 |
+| zone/账户删除 | 是（强烈建议二次确认） |
+
+## Token 类型与权限边界
+
+实际可用能力由 Cloudflare token 决定。常见 token 类型：
+
+| Token 类型 | 前缀 | 典型权限 |
+| --- | --- | --- |
+| Account Token | `cfat_` | 账户范围内读写，但不能跨 zone |
+| User Token | `cfut_` | 用户级，可限定到具体 Zone 资源 |
+| OAuth Token | `cfoat_` | 通过 OAuth 授权产生 |
+
+遇到以下情况，先提示用户而非猜测：
+
+- `/accounts` 返回 403 → token 失效或权限不够
+- DNS 端点返回 10000 → token 没有 Zone 资源权限
+- `/user/tokens/verify` 返回 401（cfat_）→ 这是 account token 的正常行为，不是错误
+- R2 端点返回 10042 → 账户尚未开通 R2，需要先在 Dashboard 开通
+
+## 与 Wrangler CLI 的关系
+
+Cloudflare MCP 覆盖 ~2500 个 API 端点。某些工作流 MCP 不便处理，可以回退到项目根目录的 `npm run wrangler ...`：
+
+```powershell
+# 本地开发服务器
+npm run wrangler -- dev
+
+# 部署（需用户明确确认）
+npm run wrangler -- deploy
+
+# 列出资源
+npm run wrangler -- d1 list --json
+npm run wrangler -- kv namespace list --json
+npm run wrangler -- r2 bucket list --json
+npm run wrangler -- pages project list --json
+```
+
+Wrangler 启动器（`scripts/wrangler.js`）会从 `%USERPROFILE%\.dsh\.env` 读取 token，永不写入仓库或日志。
+
+## 故障排查
+
+| 现象 | 排查 |
+| --- | --- |
+| `mcp__cloudflare__*` 工具不可见 | cfbridge bundle 未启用；运行 `npm run install:bundle -- --profile <你的 profile>`，然后重启 DSH |
+| 调用返回 `Bearer token required` | `%USERPROFILE%\.dsh\.env` 没有 `CLOUDFLARE_API_TOKEN` |
+| 调用返回 401/403 | token 过期；去 Cloudflare Dashboard 重新生成 |
+| `execute` 超时 | 网络受限；DSH 内 MCP 客户端会自动重连 |
+| `search` 无结果 | 关键词过窄；改用更宽泛的 `path.includes('xxx')` |
+| 模型猜测端点而不是 search | 不接受猜测结果；强制要求先 search |
+
+## 何时不要调用 Cloudflare
+
+- 用户问的是通用编程/文档问题，与 Cloudflare 无关
+- 用户希望离线操作、纯本地 Wrangler dev
+- 用户已明确拒绝使用云端资源
+
+在这些场景下，直接回答问题或调用本地工具即可，不要触碰 Cloudflare MCP。
+
+## 相关链接
+
+- [Cloudflare Code Mode MCP](https://github.com/cloudflare/mcp)
+- [Wrangler CLI 文档](https://developers.cloudflare.com/workers/wrangler/)
+- [cfbridge 项目仓库](https://github.com/Wenaixi/cfbridge)