FET

中文 | English

npm 包页只展示 README.md，站内 ./README_en.md 等相对链接会 404。请用上方 unpkg 链接打开同 npm 包内的另一份文档；源码仓库见 Gitee。

FET 是一个围绕 OpenSpec 构建的前端开发工作流编排 CLI。它不会直接生成业务代码，而是代理 OpenSpec 命令、维护本地工作流状态、生成可审计的项目上下文，并帮助 Cursor、Codex 等 AI 编程工具读取正确的项目资料。

功能概览

• 统一入口：使用 fet <command> 包装 OpenSpec 工作流，避免用户和 AI 工具绕过 FET 的状态记录。
• 生成上下文：扫描项目并生成 AGENTS.md 与 openspec/config.yaml 中的 fet: 配置。
• 管理状态：记录 active change、任务同步、手动验证声明、工具适配状态和语言偏好。
• 集成 AI 工具：为 Cursor 生成规则和 Skill，为 Codex 生成上下文、命令指南和 native slash prompt。
• 统一语言：默认使用中文输出交互信息和生成产物，可通过 --lang <language> 切换。
• 保护关键阶段：在 sync / archive 前检查 FET verify 状态，降低未验证变更被合入或归档的风险。
• 可选代码图：可接入 GitNexus，在大范围扫描前优先提供结构化代码上下文。
• Figma 守卫：当 change 产物含 Figma 链接时，自动写入 figma-apply-instructions.md（apply 前必读稿）与 figma-stop.md（读稿失败则停下问用户，禁止猜样式）。
• UI 展示契约：当 change 含 Figma 和/或接口文档引用时，生成 ui-display-contract.yaml 草案与 ui-field-apply-instructions.md；规划 spec 须写入「仅展示 displayFields」Requirement，避免按 OpenAPI 全量渲染。
• Spec 分层双语：英文 Requirements/Scenario 为权威，每个 Requirement 配 <!-- 中文：... -->；LLM 更新 spec 时须同次编辑同步中文说明（见 fet.specLanguage 与 .cursor/rules/fet-spec-language.mdc）。

基本原理

FET 是 OpenSpec 的透明代理和本地编排层。运行 fet apply、fet archive 等命令时，FET 会先读取项目状态和 change 状态，执行必要的 pre-hook，再调用真实的 openspec CLI，最后根据 OpenSpec 的结果更新 FET 状态。

FET 代理命令会保留 OpenSpec 原生命令名。例如，fet apply --change <id> 会调用 openspec apply --change <id>，fet sync --change <id> 会在 FET verify gate 通过后调用 openspec sync --change <id>。

环境要求

• Node.js 18 或更高版本
• OpenSpec CLI 在 PATH 中可用

安装 OpenSpec：

npm install -g @fission-ai/openspec

安装

npm install -g @nick848/fet

安装后检查：

fet --version
fet --help
fet update

第一次使用（推荐顺序）

以下流程面向第一次在业务项目中接入 FET 的场景。请在你希望接入 OpenSpec 的项目根目录（含 package.json 或业务源码的目录）执行，而不是在 FET 工具仓库自身目录。

步骤 1：安装依赖工具

1. 安装 OpenSpec CLI（全局）：

   npm install -g @fission-ai/openspec
   openspec --version

2. 安装 FET（全局）：

   npm install -g @nick848/fet
   fet --version

步骤 2：初始化项目

在业务项目根目录执行：

fet init --yes

fet init 会：

• 检测 OpenSpec；若项目尚无 openspec/，则调用 openspec init
• 扫描仓库并生成 AGENTS.md、openspec/config.yaml 的 fet: 配置
• 写入 openspec/fet-state.json 等工作流状态
• 为 Cursor、Codex 生成 Skill / 规则 / 命令指南（见下文「在 IDE 中使用」）
• 可选检测 GitNexus（未安装仅提示一次，不阻断）

需要英文产物时，可在初始化时指定：

fet init --yes --lang en

步骤 3：检查环境

fet doctor

确认 OpenSpec 路径、上下文文件、工具集成无 fail。若有锁文件残留，可执行 fet doctor --fix-lock。

步骤 4：补齐项目上下文（与 IDE 协作）

扫描器无法自动推断的内容会在 AGENTS.md 中标记为 [NEEDS LLM INPUT]。请执行：

fet fill-context

然后在 Cursor 或 Codex 中按生成的 handoff 说明（如 .fet/fill-context.md、.cursor/skills/fet-fill-context/SKILL.md）让 AI 协助补全占位符。补全后再次运行 fet doctor，占位符相关项应为通过。

步骤 5：（可选）配置代码图

若希望 AI 在大范围扫仓库前先读结构化代码图，请先安装 GitNexus CLI（确保 gitnexus 在 PATH 中），再执行：

fet graph setup    # 生成安装引导，FET 不会自动安装 GitNexus
fet graph init     # 首次构建图谱
fet graph handoff  # 生成 IDE 交接说明

步骤 6：在 IDE 中使用

初始化完成后，建议在 AI 工具中确认以下资料可被读取：

| 工具 | 主要入口 | |------|----------| | Cursor | .cursor/rules/fet-context.mdc；.cursor/skills/fet-*/SKILL.md | | Codex | .codex/fet/context.md；$CODEX_HOME/prompts/fet-*.md |

工作流命令请在终端执行 fet <command>（例如 fet apply），不要绕过 FET 直接调用 openspec，否则本地状态与 verify 闸门不会更新。

步骤 7：完成第一个 change

初始化无误后，按 OpenSpec 工作流创建并落地第一个变更。简单路径示例：

fet propose my-first-change
# 或在 Cursor/Codex 中按提示逐步执行 fet continue
fet tdd --change my-first-change
fet apply --change my-first-change
fet test --change my-first-change
fet visual --change my-first-change
fet verify --change my-first-change
fet verify --done --change my-first-change
fet sync --change my-first-change
fet archive --change my-first-change

复杂路径可先 fet new <id>，再多次 fet continue 或 fet ff。各阶段说明见下文「日常变更流程」。

日常变更流程

在已完成「第一次使用」的项目中，典型循环为：

fet new my-change          # 或 fet propose my-change
fet continue               # 按需重复，生成下一规划产物
fet tdd --change my-change # 生成本 change 的 TDD 清单（.fet/tdd-manifest.yaml）
fet apply --change my-change
fet test --change my-change
fet visual --change my-change
fet verify --change my-change
fet verify --done --change my-change
fet sync --change my-change
fet archive --change my-change

说明：

• continue、apply、ff、sync 等命令在未传 --change 时，优先使用 FET 记录的 active change；若仅有一个打开的 change，会自动选中。
• fet apply 默认要求已运行 fet tdd（openspec/config.yaml 中 fet.tdd.mode 可配置）。
• fet verify 要求本 change 已通过 fet test（除非 fet.tdd.enabled: false 或 test 被配置为 skip）。
• 含 Figma 引用的 change 在 fet verify 前须通过 fet visual（默认 layout-only，一条命令完成清单/截图/布局检查）。
• 经 FET 执行的 sync / archive 会先检查是否已 fet verify --done。
• 项目结构变化后运行 fet update-context；仅刷新 IDE 占位符提示时运行 fet fill-context。

语言设置

FET 默认使用中文输出交互信息和生成产物。

fet init --lang zh-CN
fet init --lang en

fet init --lang <language> 会把语言写入 openspec/fet-state.json。后续命令如果没有传 --lang，会复用初始化时保存的语言。支持值：

| 参数值 | 含义 | |------|------| | zh-CN、zh、cn、chinese | 中文 | | en、en-US、english | 英文 |

全局参数

| 参数 | 说明 | 示例 | |------|------|------| | --cwd <path> | 指定项目根目录，默认当前目录。 | fet doctor --cwd ./app | | --change <id> | 指定 OpenSpec change。 | fet apply --change add-login | | --lang <language> | 指定交互信息和生成产物语言。 | fet init --lang en | | --yes | 对低风险确认使用默认同意。 | fet init --yes | | --json | 输出机器可读 JSON。 | fet doctor --json | | --verbose | 输出更多诊断信息。 | fet doctor --verbose | | --no-color | 禁用终端颜色。 | fet --no-color doctor |

版本更新检查

除 fet update 外，FET 在执行其他命令前会检查 npm 上是否有新版本（默认缓存 6 小时）。发现新版本时会提示当前版本与最新版本；在交互式终端中可选择立即升级、跳过并继续当前任务，或取消命令。

| 环境变量 | 说明 | |----------|------| | FET_UPDATE_CHECK | off 关闭检查；warn 仅警告并继续；confirm 在 TTY 中交互询问（默认）。 | | FET_SKIP_UPDATE_CHECK | 设为 1 时等同于 FET_UPDATE_CHECK=off。 | | FET_UPDATE_CHECK_TTL_MS | 版本检查缓存时长（毫秒），默认 21600000（6 小时）。 |

使用 --yes 或 --json 时会跳过交互式升级询问；跳过某版本后，同一最新版本不会重复提示，直到检测到更高的新版本。

命令列表

| 命令 | 用法 | 说明 | |------|------|------| | fet init | fet init [--yes] [--lang <language>] | 初始化 FET 和 OpenSpec；生成上下文、状态、Cursor 集成和 Codex 工作流指南。 | | fet update | fet update | 检查 npm 上的新版本并在需要时自动升级 FET。 | | fet update-context | fet update-context [--yes] | 重新扫描项目并更新 AGENTS.md 与 openspec/config.yaml 的 FET 托管区域。 | | fet fill-context | fet fill-context [--yes] | 刷新 IDE 交接命令；自动识别小程序工程并写入包体积/2MB 约束，引导 AI 补齐其余 AGENTS.md 占位符。 | | fet doctor | fet doctor [--fix-lock] | 诊断 OpenSpec、FET 状态、上下文文件、工具集成和锁文件。 | | fet explore | fet explore [...args] [--change <id>] | 通过 FET 执行 OpenSpec 原生 explore，保留交互式需求澄清。 | | fet propose | fet propose <change-id-or-description> | 创建 OpenSpec change，并生成第一个 ready 规划产物；后续产物用 continue 逐步推进。 | | fet new | fet new <change-id> | 创建新的 OpenSpec change。 | | fet continue | fet continue [...args] [--change <id>] | 通过 FET 执行 OpenSpec 原生 continue。 | | fet ff | fet ff [...args] [--change <id>] | 通过 FET 执行 OpenSpec 原生 ff。 | | fet tdd | fet tdd [--change <id>] | 根据规划产物生成 openspec/changes/<id>/.fet/tdd-manifest.yaml 等 TDD 契约。 | | fet apply | fet apply [...args] [--change <id>] | 准备实施指令；需先有 TDD 清单（默认）。 | | fet test | fet test [--change <id>] [--plan] | 按 TDD 清单运行项目 test 脚本并记录绿灯状态。 | | fet visual | fet visual [--change <id>] [--base-url <url>] [--plan] | layout-only 视觉验收（默认含截图+布局检查；含 Figma 时 verify 前必需）。 | | fet verify | fet verify --change <id> | 生成 .fet/verify-instructions.md；需先 fet test（及含 Figma 时的 fet visual）通过。 | | fet verify --done | fet verify --done --change <id> | 声明手动验证完成，允许后续 sync / archive。 | | fet verify --auto | fet verify --auto [--yes] | 生成自动验证计划；当前版本不执行项目脚本，--yes 会记录计划指纹。 | | fet sync | fet sync [...args] [--change <id>] | FET verify gate 通过后执行 OpenSpec 原生 sync。 | | fet archive | fet archive --change <id> | FET verify gate 通过后归档 change，并追加 CHANGELOG.md。 | | fet bulk-archive | fet bulk-archive [...args] [--change <id>] | 通过 FET 执行 OpenSpec 原生 bulk-archive。 | | fet onboard | fet onboard [...args] [--change <id>] | 通过 FET 执行 OpenSpec 原生 onboard。 | | fet passthrough | fet passthrough <command> [...args] | 透传暂未接管的 OpenSpec 命令，不更新 FET 生命周期状态。 |

GitNexus 代码图支持

GitNexus 是可选能力。FET 会在 fet init 时检测 gitnexus 可执行文件，并把结果记录到 openspec/fet-state.json。如果没有安装 GitNexus，初始化只会给出一次推荐提示，主流程会继续执行；fet doctor 也只会把缺失 GitNexus 作为 warning。

图谱命令统一放在 fet graph 下：

| 命令 | 说明 | |------|------| | fet graph status | 检查 GitNexus、图谱路径和当前状态，并更新 FET 状态。 | | fet graph setup | 生成 .fet/graph-setup.md，用于安装和 IDE 辅助配置引导；FET 不会自动安装 GitNexus。 | | fet graph init | 执行 gitnexus analyze，用于首次构建图谱。 | | fet graph refresh | 再次执行 gitnexus analyze，用于刷新图谱。 | | fet graph doctor | 检查图谱集成健康状态，缺失只提示，不阻断 FET/OpenSpec 命令。 | | fet graph handoff | 生成 .fet/graph-handoff.md，供 Cursor、Codex、OpenCode 等 IDE AI 在大范围扫描前优先参考图谱上下文。 |

默认情况下，FET 从 PATH 查找 gitnexus，并认为图谱目录是 .gitnexus。高级用户可以通过 FET_GITNEXUS_EXECUTABLE、FET_GITNEXUS_COMMAND、FET_GITNEXUS_GRAPH_PATH 覆盖默认行为。

Andrej Karpathy 风格指南

fet init 和 fet update-context 会为当前工程加入一份 FET 管理的 Andrej Karpathy 风格编码指南。FET 不假设 Codex 或 OpenCode 会主动读取 CLAUDE.md，因此会把指南同步到多个上下文文件中：

• CLAUDE.md：追加或刷新 FET:BEGIN ANDREJ-KARPATHY-SKILLS 管理块。
• .fet/karpathy-guidelines.md：通用 IDE handoff。
• .codex/fet/karpathy-guidelines.md：Codex 专用上下文。
• .cursor/rules/karpathy-guidelines.mdc：Cursor 项目规则。

这份指南不是复制第三方仓库全文，而是基于 andrej-karpathy-skills 的使用目标生成项目级精简规则：先思考、保持简单、精准修改、按目标验证。来源项目：https://github.com/forrestchang/andrej-karpathy-skills。

生成文件

FET 可能创建或更新：

• AGENTS.md
• openspec/config.yaml 的 fet: 命名空间
• openspec/fet-state.json
• openspec/changes/<change-id>/fet-state.json
• openspec/changes/<change-id>/.fet/verify-instructions.md
• CHANGELOG.md
• .fet/fill-context.md
• .fet/graph-setup.md
• .fet/graph-handoff.md
• .fet/karpathy-guidelines.md
• CLAUDE.md
• .cursor/skills/fet-*/SKILL.md
• .cursor/rules/fet-context.mdc
• .cursor/rules/fet-figma-stop.mdc
• .cursor/rules/fet-spec-language.mdc
• .cursor/rules/karpathy-guidelines.mdc
• .codex/fet/context.md
• .codex/fet/figma-stop.md
• .codex/fet/spec-language.md
• .codex/fet/karpathy-guidelines.md
• openspec/changes/<change-id>/.fet/figma-apply-instructions.md（apply 时含 Figma 链接则写入，实施 UI 前必读）
• openspec/changes/<change-id>/.fet/figma-stop.md（change 含 Figma 链接时自动写入）
• .codex/fet/commands/*.md
• $CODEX_HOME/prompts/fet-*.md

FET 只拥有明确标记的托管区域。托管区域之外的用户内容应被保留。

团队与 Git：openspec/fet-state.json、锁文件等是否纳入版本库由团队自行决定。fet init 不再自动修改 .gitignore。常见做法：（1）提交共享状态并约定每人只改自己负责的 change，减少 activeChangeId 冲突；（2）仅在本机用 .git/info/exclude 排除锁文件与日志，仓库 .gitignore 保持团队统一；（3）整包状态不入库，由每人本地维护（适合无协作场景）。可参考 src/templates/gitignore.ts 中的规则片段自行合并。

安全边界

FET 是本地工作流辅助工具，不是沙箱、强制 CI gate 或密码学审计系统。直接调用 openspec 可以绕过 FET 的本地 gate。团队如果需要强制执行验证，应在 CI、分支保护或代码审查规则中重复校验。

开发

npm install
npm run typecheck
npm run test
npm run build
npm run release:check

运行真实 OpenSpec 烟测：

$env:FET_REAL_OPENSPEC='1'; npm run test:real-openspec

许可证

MIT