@nick848/ft 0.1.0 → 0.1.1

package/README.md

@@ -1,8 +1,8 @@
 # FT（Frontend Toolkit）
 
-FT 是一个**前端开发工具编排层**。它以 [Comet](https://www.npmjs.com/package/@rpamis/comet) 为工作流基座，将 [andrej-karpathy-skills](https://github.com/multica-ai/andrej-karpathy-skills) 作为 AI 行为的强制约束，并可选择性接入 [GitNexus](https://www.npmjs.com/package/gitnexus) 代码图谱。
+FT 是一个**前端开发工具编排层**。它以 [Comet](https://www.npmjs.com/package/@rpamis/comet) 为工作流基座，将 [andrej-karpathy-skills](https://github.com/multica-ai/andrej-karpathy-skills) 作为 AI 行为的强制约束。
 
-FT **不内置任何 LLM**。它的职责是通过 CLI 命令和 IDE Slash 命令，引导 Cursor、Codex、OpenCode 中的 LLM 完成开发任务。
+FT **不内置任何 LLM**。它的职责是通过 CLI 命令和 IDE Slash 命令，引导 Cursor、Codex、OpenCode 中的 LLM 完成开发任务。代码图谱能力由 Comet 生态（如 CodeGraph）提供，由 `comet init` 引导安装。
 
 ## 核心特性
 
@@ -12,7 +12,6 @@ FT **不内置任何 LLM**。它的职责是通过 CLI 命令和 IDE Slash 命
 | **Comet 透传** | `/ft-open`、`/ft-build` 等命令透传 Comet 工作流，保持原生能力 |
 | **RTK 压缩** | 子进程长输出自动中间截断，降低 Token 消耗；`--json` 等结构化输出自动放行 |
 | **Karpathy 约束** | 初始化时向三平台注入四条行为准则规则文件 |
-| **GitNexus 可选** | 安装后自动配置 MCP；未安装时能力优雅降级 |
 | **双语支持** | CLI 输出与 AGENTS.md 模板支持 `zh-CN` / `en` |
 
 ## 环境依赖
@@ -27,43 +26,31 @@ FT **不内置任何 LLM**。它的职责是通过 CLI 命令和 IDE Slash 命
 
 ### 可选
 
-| 依赖 | 安装方式 | 说明 |
-|------|----------|------|
-| **GitNexus** | `npm install -g gitnexus` | 代码图谱与 MCP 符号查询 |
-| **Cursor / Codex / OpenCode** | 各工具官网 | Slash 命令与规则注入的目标 IDE |
+| 依赖 | 说明 |
+|------|------|
+| **Cursor / Codex / OpenCode** | Slash 命令与规则注入的目标 IDE |
 
 ### 支持平台
 
-当前版本支持以下 IDE / 开发工具：
-
 - **Cursor**
 - **Codex**
 - **OpenCode**
 
-初始化时可将 Karpathy 规则注入到对应平台，并在已安装 GitNexus 时自动配置 MCP。
+初始化时可将 Karpathy 规则注入到对应平台，并安装 Cursor Slash 命令。
 
 ## 安装
 
-### 全局安装
-
 ```bash
 npm install -g @nick848/ft
-```
-
-验证安装：
-
-```bash
 ft version
 ```
 
 ## 快速开始
 
-### 1. 安装前置依赖
+### 1. 安装 Comet
 
 ```bash
 npm install -g @rpamis/comet
-# 可选
-npm install -g gitnexus
 ```
 
 ### 2. 在目标项目中初始化
@@ -79,25 +66,21 @@ ft init
 2. 检测 Karpathy 规则（内置模板可用则通过）
 3. 交互选择注入目标（Cursor / Codex / OpenCode）
 4. 复制 Karpathy 规则到对应平台目录
-5. 若已安装 GitNexus，自动写入 MCP 配置
+5. 若选择 Cursor，安装 `.cursor/commands/` Slash 命令
 6. 生成 `AGENTS.md`（旧文件备份为 `AGENTS-BAK.md`）
-7. 执行 `comet init`
+7. 执行 `comet init`（含 CodeGraph 等 Comet 生态引导）
 8. 提示下一步执行 `/ft-fill-context`
 
-英文初始化：
-
 ```bash
-ft init --lang en
+ft init --lang en   # 英文初始化
 ```
 
 ### 3. 填充项目上下文
 
-在 IDE 聊天框执行 `/ft-fill-context`，将输出的 Prompt 粘贴给 LLM，由 LLM 编辑 `AGENTS.md` 中的 `[NEEDS LLM INPUT]` 占位符。
+在 IDE 中执行 `/ft-fill-context`，由 Agent 根据终端输出的 Prompt 配方编辑 `AGENTS.md`。
 
 ### 4. 使用 Comet 工作流
 
-上下文填充完成后，在 IDE 中使用 Slash 命令驱动 Comet 流程，例如：
-
 ```
 /ft-design
 /ft-build
@@ -108,22 +91,20 @@ ft init --lang en
 
 | 命令 | 说明 |
 |------|------|
-| `ft init [--lang en\|zh-CN]` | 全流程初始化（依赖检测 → 规则注入 → MCP → AGENTS.md → Comet init） |
-| `ft update` | 更新 FT 自身（`npm update -g @nick848/ft`），不更新 Comet / GitNexus |
-| `ft version` | 打印 FT、Comet、GitNexus 版本号 |
+| `ft init [--lang en\|zh-CN]` | 全流程初始化 |
+| `ft update` | 更新 FT 自身，不更新 Comet |
+| `ft version` | 打印 FT 与 Comet 版本号 |
 | `ft help` | 显示帮助信息 |
 
 ## Slash 命令
 
-所有 `/ft-xxx` 命令在 IDE 中触发，并自动继承 RTK 输出压缩能力。
-
 ### 上下文
 
 | Slash 命令 | 说明 |
 |------------|------|
 | `/ft-fill-context` | 输出结构化 Prompt，引导 LLM 填充 `AGENTS.md` |
 
-> **门禁**：`AGENTS.md` 中仍存在 `[NEEDS LLM INPUT]` 时，Comet 透传类命令会被拦截，须先完成 `/ft-fill-context`。
+> **门禁**：`AGENTS.md` 中仍存在 `[NEEDS LLM INPUT]` 时，Comet 透传类命令会被拦截。
 
 ### Comet 工作流（透传）
 
@@ -136,123 +117,78 @@ ft init --lang en
 | `/ft-archive` | Comet `archive` |
 | `/ft-hotfix` | Comet `hotfix` |
 | `/ft-tweak` | Comet `tweak` |
+| `/ft-sync-cursor-commands` | 重新安装 Cursor Slash 命令到 `.cursor/commands/` |
 
-**TTY 处理**：在系统终端中保持 Comet 原生交互；在 IDE 非 TTY 环境中尝试注入 `--non-interactive`，若 Comet 不支持则提示转至系统终端执行。
+> **门禁**：`AGENTS.md` 中仍存在 `[NEEDS LLM INPUT]` 时，Comet 透传类命令会被拦截。
 
-### GitNexus 图谱
+**TTY 处理**：终端中保持 Comet 原生交互；IDE 非 TTY 环境尝试 `--non-interactive`，失败则提示在系统终端执行 `comet <command>`。
 
-| Slash 命令 | 说明 |
-|------------|------|
-| `/ft-graph-setup` | 安装引导 + MCP 配置重试 |
-| `/ft-graph-init` | 首次构建图谱（`gitnexus analyze`） |
-| `/ft-graph-refresh` | 强制刷新图谱（`gitnexus analyze --force`） |
-| `/ft-graph-handoff` | 图谱摘要 + 引导词 + 更新 AGENTS.md 时间戳 |
-| `/ft-graph-status` | 检查 GitNexus 与图谱索引状态 |
-
-## IDE Slash 配置
-
-FT 不直接修改 IDE，需在各平台中配置自定义命令，统一调用 `ft slash <subcommand>`。
-
-### Cursor
+## Cursor Slash 命令
 
-在项目 `.cursor/commands/` 下创建命令文件，例如 `ft-fill-context.md`：
+`ft init` 选择 Cursor 时会自动安装 `.cursor/commands/`。在 **Agent 聊天框**输入 `/` 即可调用。
 
-```markdown
----
-description: Fill AGENTS.md context via FT prompt recipe
----
-
-Run: ft slash fill-context
-```
-
-或在 Cursor Settings → Commands 中添加，命令内容为：
-
-```
-ft slash fill-context
-```
-
-其他 Slash 同理，将 `fill-context` 替换为对应子命令名（`open`、`design`、`build` 等）。
-
-### Codex / OpenCode
-
-参考各平台自定义 Slash / Command 机制，将触发动作配置为：
+修复命令列表：
 
 ```bash
-ft slash <subcommand>
+ft slash sync-cursor-commands
 ```
 
-确保 `ft` 在 IDE 子进程的 `PATH` 中可用（全局安装后一般即可）。
-
 ## 配置文件
 
-初始化后会在项目根目录生成 `.ft/config.yaml`：
+`.ft/config.yaml` 示例：
 
 ```yaml
-# 语言：zh-CN 或 en
 language: zh-CN
 
-# RTK 压缩层
 rtk:
   enabled: true
-  auto_trigger_lines: 500      # 超过此行数强制压缩（即使全局关闭）
-  exclude_patterns:            # 匹配则跳过压缩，保留原始输出
+  auto_trigger_lines: 500
+  exclude_patterns:
     - "--json"
     - "--format json"
     - "--xml"
 
-# 已注入规则的目标工具
 tools:
   - cursor
   - codex
   - opencode
-
-# GitNexus
-gitnexus:
-  graph_path: ".gitnexus/"
-  auto_prompt_in_agents: true
 ```
 
-**语言优先级**：CLI 参数（`--lang`）> 配置文件 > 默认 `zh-CN`。
-
-也可使用 `ft.config.json` 等同名配置文件。
-
 ## 典型工作流
 
 ```
-ft init
+ft init  →  comet init（CodeGraph 等）
     ↓
 /ft-fill-context  →  LLM 填充 AGENTS.md
     ↓
-/ft-graph-setup   →  （可选）安装并配置 GitNexus MCP
-/ft-graph-init    →  （可选）构建代码图谱
-    ↓
-/ft-design        →  Comet 设计阶段
-/ft-build         →  Comet 构建阶段
-/ft-verify        →  Comet 验证阶段
-    ↓
-/ft-graph-handoff →  （可选）交接图谱上下文给 LLM
+/ft-design → /ft-build → /ft-verify
 ```
 
-## RTK 输出压缩
+或在 Cursor 中执行 `/ft-sync-cursor-commands`。
 
-FT 拦截子进程 `stdout` / `stderr`，对长文本采用**中间截断**策略：
+### Codex / OpenCode
 
-- 保留前 **200** 行 + 后 **100** 行
-- 中间以 `...... (已省略 X 行) ......` 替换
-- 命令参数含 `--json`、`--format json`、`--xml` 时完全旁路
-- Comet 透传且处于 TTY 交互模式时自动禁用，避免破坏 TUI
+参考各平台自定义 Command 机制，在终端执行 `ft slash <subcommand>`。
+
+## RTK 输出压缩
+
+子进程长输出采用中间截断（前 200 行 + 后 100 行），`--json` 等结构化参数自动旁路，TTY 交互时不压缩。
 
 ## 已知限制
 
-- **AGENTS-BAK 合并**依赖 LLM 判断，超模板章节迁移可能存在轻微随机性
-- **IDE 内 Comet 透传**：若 Comet 不支持 `--non-interactive`，须在系统终端执行对应 `comet` 命令
-- **平台范围**：当前仅支持 Cursor、Codex、OpenCode
+- AGENTS-BAK 合并依赖 LLM 判断
+- IDE 内 Comet 透传可能需在系统终端执行
+- 当前仅支持 Cursor、Codex、OpenCode
+
+## 文档
+
+- [DESIGN.md](./DESIGN.md) — 设计说明
+- [DEVELOPMENT_PLAN.md](./DEVELOPMENT_PLAN.md) — 开发计划与实现状态
 
 ## 相关链接
 
 - Comet：`npm install -g @rpamis/comet`
 - Karpathy Skills：https://github.com/multica-ai/andrej-karpathy-skills
-- GitNexus：`npm install -g gitnexus`
 
 ## License
 

package/cursor-commands-templates/ft-archive.md

@@ -0,0 +1,11 @@
+---
+description: Comet archive workflow via FT
+---
+
+Execute in the project terminal:
+
+```bash
+ft slash archive
+```
+
+Wait for the command to finish and report the result. If it fails in the IDE non-interactive environment, tell the user to run `comet archive` in a system terminal.

package/cursor-commands-templates/ft-build.md

@@ -0,0 +1,44 @@
+---
+description: Comet build workflow via FT — strict visual design fidelity
+---
+
+## Mandatory: read visual-fidelity skill first
+
+**Before any UI code**, read and follow `.cursor/skills/visual-fidelity/SKILL.md`.
+
+## Step 1 — Run build prep
+
+Execute in the project terminal:
+
+```bash
+ft slash build
+```
+
+Read the **full terminal output**. It scaffolds/updates:
+
+- `.ft/visual-spec.md` — design tokens and component map
+- `.ft/visual-checklist.json` — acceptance items (auto-filled from Figma API when available)
+
+## Step 2 — Fetch designs (if not auto-filled)
+
+1. **Figma Developer MCP** (`get_figma_data`, `download_figma_images`)
+2. **`AGENTS.md` → Visual Design / 视觉稿** links
+3. User-provided links in chat
+
+Update `.ft/visual-spec.md` with extracted tokens. Mark unknowns as `TBD` — never guess.
+
+## Step 3 — If fetch fails, ask the user (do NOT stop)
+
+Present options in chat:
+
+1. Supplement Figma API Key → `ft init` or configure `.cursor/mcp.json`
+2. Supplement design link → record and suggest AGENTS.md update
+3. Skip for now → continue without blocking
+
+## Step 4 — Implement with acceptance gate
+
+1. Code using tokens from visual-spec (no hardcoded colors/spacing)
+2. After coding, output **Visual Acceptance Report** (see skill template)
+3. Update `.ft/visual-checklist.json` — only mark `passed` when verified
+
+Wait for `ft slash build` (including Comet build) to finish. If Comet fails in IDE, tell the user to run `comet build` in a system terminal.

package/cursor-commands-templates/ft-design.md

@@ -0,0 +1,11 @@
+---
+description: Comet design workflow via FT
+---
+
+Execute in the project terminal:
+
+```bash
+ft slash design
+```
+
+Wait for the command to finish and report the result. If it fails in the IDE non-interactive environment, tell the user to run `comet design` in a system terminal.

package/cursor-commands-templates/ft-fill-context.md

@@ -0,0 +1,13 @@
+---
+description: Fill AGENTS.md project context via FT prompt recipe
+---
+
+Execute in the project terminal:
+
+```bash
+ft slash fill-context
+```
+
+Read the full terminal output. It contains a structured prompt recipe.
+
+**Directly edit `AGENTS.md`** in the workspace: replace every `[NEEDS LLM INPUT]` with accurate project-specific content. Follow the language constraint in the output. If `AGENTS-BAK.md` exists, follow the backup merge rules shown in the terminal output.

package/cursor-commands-templates/ft-hotfix.md

@@ -0,0 +1,33 @@
+---
+description: Comet hotfix workflow via FT — visual regression-safe emergency fixes
+---
+
+## Mandatory: regression-safe hotfix
+
+**Before any hotfix**, read `.cursor/skills/visual-fidelity/SKILL.md` (Tweak / hotfix section).
+
+## Step 1 — Run hotfix prep
+
+Execute in the project terminal:
+
+```bash
+ft slash hotfix
+```
+
+Read the **full terminal output**. Note locked (`passed`) checklist items — they must not regress.
+
+## Step 2 — Minimal, scoped fix
+
+- Fix only the reported production issue
+- One dimension at a time (spacing / color / typography)
+- Do not rewrite unrelated layout or remove verified CSS variables
+
+## Step 3 — Full regression re-check
+
+After the fix:
+
+1. Re-verify **every** checklist item
+2. Output **Visual Acceptance Report** with regression table
+3. If a locked item regressed → revert before shipping
+
+Wait for `ft slash hotfix` (including Comet hotfix) to finish. If Comet fails in IDE, tell the user to run `comet hotfix` in a system terminal.

package/cursor-commands-templates/ft-open.md

@@ -0,0 +1,11 @@
+---
+description: Comet open workflow via FT
+---
+
+Execute in the project terminal:
+
+```bash
+ft slash open
+```
+
+Wait for the command to finish and report the result. If it fails in the IDE non-interactive environment, tell the user to run `comet open` in a system terminal.

package/cursor-commands-templates/ft-sync-cursor-commands.md

@@ -0,0 +1,11 @@
+---
+description: Reinstall FT slash commands into .cursor/commands/
+---
+
+Execute in the project terminal:
+
+```bash
+ft slash sync-cursor-commands
+```
+
+This copies all FT slash command definitions into `.cursor/commands/`. Tell the user they can now type `/` in Cursor Agent chat to see commands like `/ft-fill-context`.

package/cursor-commands-templates/ft-tweak.md

@@ -0,0 +1,36 @@
+---
+description: Comet tweak workflow via FT — visual regression-safe fixes
+---
+
+## Mandatory: regression-safe visual tweaks
+
+**Before fixing any visual issue**, read `.cursor/skills/visual-fidelity/SKILL.md` (Tweak / hotfix section).
+
+## Step 1 — Run tweak prep
+
+Execute in the project terminal:
+
+```bash
+ft slash tweak
+```
+
+Read the **full terminal output**. Note:
+
+- Items with `status: "passed"` in `.ft/visual-checklist.json` are **locked** — must not regress
+- Current locked items are listed in the terminal output
+
+## Step 2 — Fix one dimension at a time
+
+- Fix spacing OR color OR typography — not all at once
+- Do not rewrite layout or remove CSS variables for local fixes
+- Only edit files necessary for the reported issue
+
+## Step 3 — Full regression re-check
+
+After the fix:
+
+1. Re-verify **every** checklist item (not just the one you fixed)
+2. Output **Visual Acceptance Report** with regression table (see skill)
+3. If a previously `passed` item regressed → revert before continuing
+
+Wait for `ft slash tweak` (including Comet tweak) to finish. If Comet fails in IDE, tell the user to run `comet tweak` in a system terminal.

package/cursor-commands-templates/ft-verify.md

@@ -0,0 +1,43 @@
+---
+description: Comet verify workflow via FT — checklist gate and Playwright pixel diff
+---
+
+## Mandatory: visual verification before sign-off
+
+Read `.cursor/skills/visual-fidelity/SKILL.md` acceptance sections before verify.
+
+## Step 1 — Run verify prep
+
+Execute in the project terminal:
+
+```bash
+ft slash verify
+```
+
+Read the **full terminal output**. It reports:
+
+1. **Checklist status** from `.ft/visual-checklist.json`
+2. **Pixel diff** (if enabled in `.ft/visual-verify.json`)
+
+## Step 2 — Enable pixel diff (first time)
+
+1. Edit `.ft/visual-verify.json`: set `enabled: true`, `baseUrl`, and `screens`
+2. Install tools (one command):
+   ```bash
+   ft slash visual-tools-install
+   ```
+   Or in IDE: `/ft-visual-tools-install`
+3. Capture baselines (first run):
+   ```bash
+   node node_modules/@nick848/ft/scripts/visual-diff.mjs --update
+   ```
+   Or use the path printed by `ft slash verify`.
+
+## Step 3 — If diff fails
+
+- Inspect diff images in `.ft/visual-diffs/`
+- Fix UI to match baselines
+- Update checklist items to `passed` only when verified
+- Re-run `/ft-verify`
+
+Wait for `ft slash verify` (including Comet verify) to finish. Exit code is non-zero if pixel diff fails. If Comet fails in IDE, tell the user to run `comet verify` in a system terminal.

package/cursor-commands-templates/ft-visual-tools-install.md

@@ -0,0 +1,26 @@
+---
+description: Install Playwright, pixelmatch, pngjs for FT visual pixel diff
+---
+
+Install all dependencies required for `/ft-verify` pixel diff in one step.
+
+Execute in the project terminal:
+
+```bash
+ft slash visual-tools-install
+```
+
+This will:
+
+1. Detect your package manager (npm / pnpm / yarn / bun)
+2. Install devDependencies: `playwright`, `pixelmatch`, `pngjs`
+3. Run `playwright install chromium` for headless screenshots
+
+Wait for the command to finish and report the result.
+
+**Next steps after success:**
+
+1. Set `enabled: true` in `.ft/visual-verify.json`
+2. Configure `baseUrl` and `screens`
+3. Capture baselines: `node node_modules/@nick848/ft/scripts/visual-diff.mjs --update`
+4. Run `/ft-verify`