@nick848/ft

v0.2.3

Published

2 months ago

Frontend Toolkit — CLI orchestration layer for Comet and Karpathy rules

0High
0Medium
0Low

nick848

frontend cli comet cursor codex opencode agents

FT（Frontend Toolkit）

FT 是一个前端开发工具编排层。它以 Comet 为工作流基座，将 andrej-karpathy-skills 作为 AI 行为的强制约束。

FT 不内置任何 LLM。它的职责是通过 CLI 命令和 IDE Slash 命令，引导 Cursor、Codex、OpenCode 中的 LLM 完成开发任务。代码图谱能力由 Comet 生态（如 CodeGraph）提供，由 comet init 引导安装。

核心特性

| 特性 | 说明 | |------|------| | 零 LLM | FT 不做推理、不生成代码，所有智能行为由 IDE 内 LLM 完成 | | Comet 工作流分发 | /ft-open、/ft-design、/ft-visual、/ft-build 等命令输出状态快照并分发 Comet Agent Skill | | 视觉还原两阶段 | /ft-visual Pass 1（解析 + CDN 澄清）→ Pass 2（静态壳 + 验收）；/ft-build 仅接入业务逻辑 | | RTK 压缩 | 子进程长输出自动中间截断，降低 Token 消耗；--json 等结构化输出自动放行 | | Karpathy 约束 | 初始化时向三平台注入四条行为准则规则文件 | | 双语支持 | CLI 输出与 AGENTS.md 模板支持 zh-CN / en |

环境依赖

必需

| 依赖 | 版本 | 说明 | |------|------|------| | Node.js | >= 18 | FT 运行时 | | npm | 任意较新版本 | 安装与更新 FT、Comet | | Comet | 全局安装 | npm install -g @rpamis/comet — ft init 的强制依赖 |

可选

| 依赖 | 说明 | |------|------| | Cursor / Codex / OpenCode | Slash 命令与规则注入的目标 IDE |

支持平台

Cursor
Codex
OpenCode

初始化时可将 Karpathy 规则注入到对应平台，并安装 Cursor Slash 命令。

安装

npm install -g @nick848/ft
ft version

快速开始

1. 安装 Comet

npm install -g @rpamis/comet

2. 在目标项目中初始化

cd your-frontend-project
ft init

ft init 将依次执行：

检测 Comet（缺失则阻塞退出）
检测 Karpathy 规则（内置模板可用则通过）
交互选择注入目标（Cursor / Codex / OpenCode）
复制 Karpathy 规则到对应平台目录
若选择 Cursor，安装 .cursor/commands/ Slash 命令
生成 AGENTS.md（旧文件备份为 AGENTS-BAK.md）
执行 comet init（含 CodeGraph 等 Comet 生态引导）
提示下一步执行 /ft-fill-context

ft init --lang en   # 英文初始化

3. 填充项目上下文

在 IDE 中执行 /ft-fill-context，由 Agent 根据终端输出的 Prompt 配方编辑 AGENTS.md。

4. 使用 Comet 工作流

/ft-open      # 需求与 OpenSpec 变更
/ft-design    # 规格与 API 契约（不含视觉实现）
/ft-visual    # 视觉还原（至少 2 次，见下文）
/ft-build     # 业务逻辑（须静态壳已通过）
/ft-verify    # 完整签收与像素对比

可选：/ft-tweak（人工微调后的回归安全修复）、/ft-archive、/ft-hotfix。

CLI 命令

| 命令 | 说明 | |------|------| | ft init [--lang en\|zh-CN] | 全流程初始化 | | ft update | 更新 FT 自身，不更新 Comet | | ft version | 打印 FT 与 Comet 版本号 | | ft help | 显示帮助信息 |

Slash 命令

上下文

| Slash 命令 | 说明 | |------------|------| | /ft-fill-context | 输出结构化 Prompt，引导 LLM 填充 AGENTS.md |

门禁：AGENTS.md 中仍存在 [NEEDS LLM INPUT] 时，Comet 工作流类命令会被拦截。

Comet 工作流（Skill 分发）

| Slash 命令 | 说明 | |------------|------| | /ft-open | 分发 comet-open Skill；录入设计链接 | | /ft-design | 分发 comet-design Skill；OpenSpec 规格与 API 契约 | | /ft-visual | 视觉还原两阶段：Pass 1 解析/mock/CDN → Pass 2 静态壳 + 验收 | | /ft-build | 分发 comet-build Skill；仅 API / 状态 / 交互（须 shell gate 已通过） | | /ft-verify | FT 验收准备 + 分发 comet-verify Skill | | /ft-archive | 分发 comet-archive Skill | | /ft-hotfix | FT 回归防护 + 分发 comet-hotfix Skill | | /ft-tweak | FT 回归防护 + 分发 comet-tweak Skill | | /ft-sync-cursor-commands | 重新安装 Cursor Slash 命令到 .cursor/commands/ |

视觉还原（Visual）

| Slash 命令 | 说明 | |------------|------| | /ft-visual | 主入口：ft slash visual 自动路由 Pass 1 / Pass 2 | | /ft-visual-prep | 仅视觉准备（图层盘点、资产清单、mock） | | /ft-visual-static-verify | Pass 2 静态壳验收循环（最多 3 轮） | | /ft-visual-tools-install | 安装 Playwright / pixelmatch 等像素对比工具 | | /ft-detect-viewport | 检测 H5 视口与缩放基线 |

两阶段模型（最少 2× /ft-visual）

CDN 切图须由用户澄清，因此高还原静态页至少执行两次 /ft-visual：

第 1 次 /ft-visual  →  Pass 1：Figma 解析、组件计划、mock、切图清单  →  暂停等 CDN
        ↓ 用户补充 URL，写入 visual-assets.json
第 2 次 /ft-visual  →  Pass 2：静态页面 + visual-static-verify  →  dev server 人工比对
        ↓ 确认 OK
/ft-build            →  接入 API / 状态 / 交互
/ft-verify           →  完整签收

产物目录：openspec/changes/<active-change>/visual/

| 文件 | Pass 1 脚手架 | 说明 | |------|--------------|------| | visual-spec.md | ✅ | 叙事 + Component Map + Viewport | | visual-checklist.json | ✅ | 验收项 | | visual-assets.json | ✅ | CDN 切图清单 | | visual-mock-data.json | ✅ | mock + fixture | | visual-frames.json | ✅ | 页面状态 Frame | | visual-session.json | 首次 /ft-visual 后 | Pass 进度 + shell gate | | visual-components.json | 懒创建 | Figma 有组件块时 | | visual-fonts.json | 懒创建 | 检测到自定义字体时 | | visual-blocks.json | 懒创建 | 仅自定义分块顺序时 | | visual-verify.json | /ft-verify 时 | 像素对比配置 |

终端常用：

ft slash visual                  # 自动 Pass 1 或 Pass 2
ft slash visual --pass shell     # 显式 Pass 2（须 CDN 已澄清）
ft slash visual-static-verify    # Pass 2 验收循环
ft slash build --phase2-check    # 确认可进入 build

视觉规范见 .cursor/skills/visual-fidelity/SKILL.md。

门禁：AGENTS.md 中仍存在 [NEEDS LLM INPUT] 时，Comet 工作流类命令会被拦截。

Skill 分发：Comet 0.3.x 工作流由 Agent Skill 驱动（/comet-open 等），不是 comet open CLI。ft slash <phase> 在非 TTY（IDE）环境输出项目状态快照与 Agent 执行指令（exit 0），Agent 在当前对话中继续执行 Skill。若 Comet Skills 未安装则阻塞并提示 comet init。

Cursor Slash 命令

ft init 选择 Cursor 时会自动安装 .cursor/commands/。在 Agent 聊天框输入 / 即可调用。

修复命令列表：

ft slash sync-cursor-commands

配置文件

.ft/config.yaml 示例：

language: zh-CN

rtk:
  enabled: true
  auto_trigger_lines: 500
  exclude_patterns:
    - "--json"
    - "--format json"
    - "--xml"

visual:
  designGate: true          # design 阶段可选门禁（Phase 0 在 /ft-visual 完成）
  shellGate: true           # Pass 2 静态壳验收循环
  shellGateMaxAttempts: 3   # 每轮 Pass 2 最多 verify 次数

tools:
  - cursor
  - codex
  - opencode

典型工作流

ft init  →  comet init（CodeGraph 等）
    ↓
/ft-fill-context  →  LLM 填充 AGENTS.md
    ↓
/ft-open  →  需求澄清、创建 OpenSpec 变更、录入设计链接
    ↓
/ft-design  →  delta specs、API 契约、页面流程
    ↓
/ft-visual（第 1 次）  →  Pass 1：解析 + mock + CDN 清单  →  等待用户 CDN
    ↓
/ft-visual（第 2 次）  →  Pass 2：静态壳 + verify  →  人工比对 Figma
    ↓
/ft-tweak（可选）  →  像素级微调
    ↓
/ft-build  →  API / 状态 / 交互
    ↓
/ft-verify  →  签收审计 + 像素对比

职责速查：

| 阶段 | 负责什么 | 不负责什么 | |------|----------|------------| | design | 规格、API 契约 | Figma 图层盘点、静态壳 | | visual Pass 1 | 解析、mock、CDN 清单 | 静态壳编码 | | visual Pass 2 | 静态壳、shell 验收 | API / 状态 | | build | API、状态、交互 | 重写 layout / 切图 | | verify | 全量签收、像素 diff | — |

或在 Cursor 中执行 /ft-sync-cursor-commands 同步最新 Slash 命令。

Codex / OpenCode

参考各平台自定义 Command 机制，在终端执行 ft slash <subcommand>。

RTK 输出压缩

子进程长输出采用中间截断（前 200 行 + 后 100 行），--json 等结构化参数自动旁路，TTY 交互时不压缩。

已知限制

AGENTS-BAK 合并依赖 LLM 判断
Comet Skills 未安装时工作流命令会阻塞，需先 comet init
视觉还原至少需 2× /ft-visual（CDN 澄清须用户参与）
ft slash build 在静态壳未通过（visual-session.json → shellGate）时会阻塞
当前仅支持 Cursor、Codex、OpenCode

文档

DESIGN.md — 设计说明
DEVELOPMENT_PLAN.md — 开发计划与实现状态

License

MIT