@dev-workflow/skill 0.1.0

package/skills/execution/figmaSync/examples/plan-doc-sample.md

@@ -0,0 +1,39 @@
+# PLAN 示例片段
+
+## 2. 组件与资产映射决策
+
+| Figma 节点 | nodeId | 目标实现                                  | 复用类型 | 是否需要 CSS | 备注             |
+| ---------- | ------ | ----------------------------------------- | -------- | ------------ | ---------------- |
+| CTA        | 1:3    | `<Button type="primary" size="medium" />` | Apex UI  | 否           | props 可覆盖视觉 |
+| Header     | 1:4    | 自定义 header                             | 无       | 是           | 页面私有布局     |
+
+## 3. CSS 变量映射表
+
+| 来源（Figma）                          | 类型  | CSS variable             | /theme 路径                       | 原始值      | 命中方式                | nodeId | designContextStatus |
+| -------------------------------------- | ----- | ------------------------ | --------------------------------- | ----------- | ----------------------- | ------ | ------------------- |
+| `var(--fill-neutral-primary, #090A0B)` | color | `--fill-neutral-primary` | `foundation.fill.neutral.primary` | `{grey.14}` | Fast Path 0 (variables) | 1:2    | OK                  |
+
+## 4. CSS 草案审核
+
+CSS 草案文件：`./figma-plan.css`
+
+```css
+.welcome-page {
+  min-height: 100%;
+  background: var(--fill-neutral-primary);
+}
+```
+
+## 5. 样式落地清单
+
+### Level 1（组件局部 CSS）
+
+- `.welcome-page`：页面根容器。
+
+### Level 2（扩展 common component）
+
+- （无）
+
+### Level 3（建议新增 /theme 变量）
+
+- （无）

package/skills/execution/figmaSync/scripts/_shared/session-log.mjs

@@ -0,0 +1,82 @@
+/**
+ * Session Log
+ *
+ * figmaSync 任务期间，每次调用 lookup-var / match-token 都追加一行 JSONL，
+ * 供 figma-sync-report.mjs 汇总。session 边界：AI 在任务开始时跑
+ * `pnpm figma:report --reset` 清空。
+ *
+ * 路径：.agent/skills/figmaSync/.session-log.jsonl（git 忽略）
+ *
+ * 去重契约：
+ *   - 把 (script, canonicalInput) 视为同一查询
+ *   - hit 优先于 miss：先 miss 后 hit 时，老的 miss 标 superseded；之后再来 miss 直接丢弃
+ *   - readSessionLog() 默认过滤掉 superseded 项
+ *
+ * canonicalInput 规则：
+ *   - 大小写折叠、空白剥除
+ *   - `Npx` 与 `N` 视为同义（match-token 现接受两种）
+ *   - `var(--xxx, fallback)` 取变量名
+ */
+import fs from 'node:fs'
+
+const LOG_PATH = '.agent/skills/figmaSync/.session-log.jsonl'
+
+function canonicalize(raw) {
+  if (raw === undefined || raw === null) return ''
+  let s = String(raw).toLowerCase().trim()
+  const varMatch = /var\(\s*(--[a-z0-9_-]+)/.exec(s)
+  if (varMatch) s = varMatch[1]
+  s = s.replace(/(\d+(?:\.\d+)?)px\b/, '$1')
+  return s
+}
+
+function readAllRaw() {
+  if (!fs.existsSync(LOG_PATH)) return []
+  return fs
+    .readFileSync(LOG_PATH, 'utf-8')
+    .split('\n')
+    .filter(Boolean)
+    .map((line) => {
+      try {
+        return JSON.parse(line)
+      } catch {
+        return null
+      }
+    })
+    .filter(Boolean)
+}
+
+export function appendSessionLog(entry) {
+  try {
+    const key = `${entry.script}|${canonicalize(entry.input)}`
+    const existing = readAllRaw()
+    const prev = [...existing]
+      .reverse()
+      .find((e) => `${e.script}|${canonicalize(e.input)}` === key && !e.superseded)
+    // 已有 hit 时，无论新 entry 是 hit 还是 miss 都不再追加
+    if (prev?.hit) return
+    if (entry.hit && prev && !prev.hit) {
+      const rewritten = existing.map((e) => {
+        if (`${e.script}|${canonicalize(e.input)}` !== key) return e
+        if (e.hit) return e
+        return { ...e, superseded: true }
+      })
+      const lines = rewritten.map((e) => JSON.stringify(e)).join('\n') + '\n'
+      fs.writeFileSync(LOG_PATH, lines)
+    }
+    const enriched = { ts: new Date().toISOString(), ...entry }
+    fs.appendFileSync(LOG_PATH, JSON.stringify(enriched) + '\n')
+  } catch {
+    // 日志写入失败不影响调用方
+  }
+}
+
+export function readSessionLog() {
+  return readAllRaw().filter((e) => !e.superseded)
+}
+
+export function resetSessionLog() {
+  if (fs.existsSync(LOG_PATH)) fs.unlinkSync(LOG_PATH)
+}
+
+export const SESSION_LOG_PATH = LOG_PATH

package/skills/execution/figmaSync/scripts/_shared/token-resolver.mjs

@@ -0,0 +1,132 @@
+/**
+ * Token Resolver
+ *
+ * 把 DTCG 别名引用（如 `{grey.1}`、`{fill.neutral.primary}`）解析成最终原始值。
+ * 支持跨 set 引用（component 引用 foundation，foundation 引用 palette）。
+ *
+ * 使用：
+ *   const loaded = loadTokens('./tokens')
+ *   const records = flattenTokens(loaded)
+ *   const resolver = createResolver(records)
+ *   resolver.resolve('foundation', ['fill', 'neutral', 'primary'])  // -> '#090a0b'
+ *   resolver.resolveAliasString('{grey.1}')                          // -> '#090a0b'
+ *
+ * 同名 token 跨 set 解析顺序（按 tokenSetOrder 反序优先）：
+ *   componentUsage > component > baseValue > foundation > palette
+ * 即下游 set 内若定义了同名 token，优先用下游的；用于 component 覆盖 palette 的能力。
+ */
+
+const ALIAS_RE = /^\{([^}]+)\}$/
+
+export function createResolver(records, order = []) {
+  // 索引：'setName.a.b.c' -> record
+  const bySetPath = new Map()
+  // 跨 set 索引：'a.b.c' -> record[]（按 set 顺序排）
+  const byPathAcrossSets = new Map()
+
+  for (const rec of records) {
+    bySetPath.set(`${rec.setName}.${rec.pathStr}`, rec)
+    const list = byPathAcrossSets.get(rec.pathStr) ?? []
+    list.push(rec)
+    byPathAcrossSets.set(rec.pathStr, list)
+  }
+
+  // 跨 set 命中时的优先级：tokenSetOrder 越靠后越优先
+  const setPriority = new Map()
+  order.forEach((setName, i) => setPriority.set(setName, i))
+
+  for (const list of byPathAcrossSets.values()) {
+    list.sort((a, b) => (setPriority.get(b.setName) ?? -1) - (setPriority.get(a.setName) ?? -1))
+  }
+
+  function findRecord(setName, pathArr) {
+    const key = `${setName}.${pathArr.join('.')}`
+    return bySetPath.get(key) ?? null
+  }
+
+  function findRecordByPath(pathStr) {
+    const list = byPathAcrossSets.get(pathStr)
+    return list && list.length > 0 ? list[0] : null
+  }
+
+  function resolveAliasString(value, seen = new Set()) {
+    if (typeof value !== 'string') return value
+    const match = value.match(ALIAS_RE)
+    if (!match) return value
+
+    const innerPath = match[1]
+    if (seen.has(innerPath)) {
+      throw new Error(`circular alias detected at {${innerPath}}`)
+    }
+    seen.add(innerPath)
+
+    const target = findRecordByPath(innerPath)
+    if (!target) {
+      // 引用悬空：返回 null 标记，让上层报告影响
+      return { __unresolved: true, alias: innerPath }
+    }
+    return resolveAliasString(target.$value, seen)
+  }
+
+  function resolve(setName, pathArr) {
+    const rec = findRecord(setName, pathArr)
+    if (!rec) return null
+    return resolveAliasString(rec.$value)
+  }
+
+  return {
+    resolve,
+    resolveAliasString,
+    findRecord,
+    findRecordByPath,
+    allRecords: records,
+    order
+  }
+}
+
+/**
+ * 反向查询：给定一个原始值（如 '#202226'），列出所有最终解析到该值的 token 路径。
+ * 返回数组按层级优先级排序：componentUsage > component > foundation > palette > baseValue。
+ */
+export function findTokensByValue(resolver, targetValue) {
+  const cleanTarget = normalizeValue(targetValue)
+  const matches = []
+
+  for (const rec of resolver.allRecords) {
+    const resolved = resolver.resolveAliasString(rec.$value)
+    if (resolved && typeof resolved === 'object' && resolved.__unresolved) continue
+    if (normalizeValue(resolved) === cleanTarget) {
+      matches.push({
+        setName: rec.setName,
+        path: rec.pathStr,
+        fullPath: `${rec.setName}.${rec.pathStr}`,
+        $type: rec.$type,
+        $value: rec.$value,
+        resolvedValue: resolved
+      })
+    }
+  }
+
+  return matches.sort((a, b) => layerPriority(a.setName) - layerPriority(b.setName))
+}
+
+// 数字越小越优先推荐
+const LAYER_PRIORITY = {
+  componentUsage: 0,
+  component: 1,
+  foundation: 2,
+  baseValue: 3,
+  palette: 4
+}
+
+function layerPriority(setName) {
+  return LAYER_PRIORITY[setName] ?? 99
+}
+
+function normalizeValue(v) {
+  if (v === null || v === undefined) return ''
+  if (typeof v === 'number') return String(v)
+  const str = String(v).toLowerCase().trim()
+  const pxMatch = /^(-?\d+(?:\.\d+)?)px$/.exec(str)
+  return pxMatch ? pxMatch[1] : str
+}

package/skills/execution/figmaSync/scripts/_shared/token-source.mjs

@@ -0,0 +1,145 @@
+/**
+ * Token source helpers.
+ *
+ * 默认 token 源为 theme/dark/*.css。
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+
+const DEFAULT_SOURCE_FILES = ['primitives.css', 'aliases.css']
+const PALETTE_PREFIXES = new Set(['green', 'grey', 'purple', 'red', 'yellow'])
+const FOUNDATION_PREFIXES = new Set(['fill', 'icon', 'stroke', 'text'])
+const BASE_VALUE_PREFIXES = new Set([
+  'border',
+  'fontheight',
+  'fontsize',
+  'fontspacing',
+  'fontweight',
+  'icon',
+  'radius',
+  'size',
+  'spacing'
+])
+
+export function loadCurrentTokenRecords({
+  themeDir = path.resolve(process.cwd(), 'theme/dark')
+} = {}) {
+  const loaded = loadCssTokens(themeDir)
+  return { source: 'css', order: loaded.order, records: flattenCssTokenRecords(loaded) }
+}
+
+export function buildTokenPathSets(records) {
+  return {
+    fullPaths: new Set(records.map((r) => `${r.setName}.${r.pathStr}`)),
+    shortPaths: new Set(records.map((r) => r.pathStr))
+  }
+}
+
+function loadCssTokens(tokensSrcDir, sourceFiles = DEFAULT_SOURCE_FILES) {
+  const dir = tokensSrcDir ?? path.resolve(process.cwd(), 'theme/dark')
+  if (!fs.existsSync(dir)) {
+    throw new Error(`theme directory not found: ${dir}`)
+  }
+
+  const variables = []
+  for (const fileName of sourceFiles) {
+    const filePath = path.join(dir, fileName)
+    if (!fs.existsSync(filePath)) {
+      throw new Error(`token css source missing: ${filePath}`)
+    }
+    variables.push(...parseCssVariables(fs.readFileSync(filePath, 'utf-8'), fileName))
+  }
+
+  return {
+    order: ['palette', 'foundation', 'baseValue'],
+    variables,
+    raw: { dir, sourceFiles }
+  }
+}
+
+function flattenCssTokenRecords(loaded) {
+  const records = []
+  for (const variable of loaded.variables) {
+    const record = variableToRecord(variable)
+    if (record) records.push(record)
+  }
+  return records
+}
+
+function parseCssVariables(cssText, sourceFile) {
+  const variables = []
+  const declRe = /--([a-zA-Z0-9_-]+)\s*:\s*([^;]+);/g
+  let match
+  while ((match = declRe.exec(stripComments(cssText)))) {
+    variables.push({
+      name: `--${match[1]}`,
+      value: match[2].trim(),
+      sourceFile
+    })
+  }
+  return variables
+}
+
+function stripComments(cssText) {
+  return cssText.replace(/\/\*[\s\S]*?\*\//g, '')
+}
+
+function variableToRecord(variable) {
+  const segments = variable.name.slice(2).split('-')
+  const [first] = segments
+
+  let setName = null
+  let type = inferType(variable.value)
+
+  if (PALETTE_PREFIXES.has(first)) {
+    setName = 'palette'
+  } else if (FOUNDATION_PREFIXES.has(first)) {
+    setName = 'foundation'
+    type = 'color'
+  } else if (BASE_VALUE_PREFIXES.has(first)) {
+    setName = 'baseValue'
+    type = 'number'
+  }
+
+  if (!setName) return null
+
+  return {
+    setName,
+    path: segments,
+    pathStr: segments.join('.'),
+    $type: type,
+    $value: normalizeRecordValue(variable.value),
+    cssValue: normalizeCssValue(variable.value),
+    cssVar: variable.name,
+    sourceFile: variable.sourceFile
+  }
+}
+
+function inferType(value) {
+  if (
+    /^#|^rgb\(|^hsl\(|^var\(--(?:green|grey|purple|red|yellow|fill|icon|stroke|text)-/i.test(value)
+  ) {
+    return 'color'
+  }
+  return 'number'
+}
+
+function normalizeCssValue(value) {
+  return value.trim().replace(/\s+/g, ' ')
+}
+
+function normalizeRecordValue(value) {
+  const normalized = normalizeCssValue(value)
+  const varRef = parseVarRef(normalized)
+  if (!varRef) return normalized
+  return `{${cssVarToPath(varRef)}}`
+}
+
+function cssVarToPath(cssVar) {
+  return cssVar.slice(2).split('-').join('.')
+}
+
+function parseVarRef(value) {
+  const match = value.match(/^var\(\s*(--[a-zA-Z0-9_-]+)(?:\s*,[^)]*)?\)$/)
+  return match ? match[1] : null
+}