@nick848/fet 1.1.7 → 1.1.9

package/README.md

@@ -1,6 +1,8 @@
 # FET
 
-[中文](./README.md) | [English](./README_en.md)
+[中文](https://unpkg.com/@nick848/fet/README.md) | [English](https://unpkg.com/@nick848/fet/README_en.md)
+
+> npm 包页只展示 `README.md`，站内 `./README_en.md` 等相对链接会 404。请用上方 **unpkg** 链接打开同 npm 包内的另一份文档；源码仓库见 [Gitee](https://gitee.com/agent-team/fet)。
 
 FET 是一个围绕 OpenSpec 构建的前端开发工作流编排 CLI。它不会直接生成业务代码，而是代理 OpenSpec 命令、维护本地工作流状态、生成可审计的项目上下文，并帮助 Cursor、Codex 等 AI 编程工具读取正确的项目资料。
 
@@ -13,7 +15,9 @@ FET 是一个围绕 OpenSpec 构建的前端开发工作流编排 CLI。它不
 - 统一语言：默认使用中文输出交互信息和生成产物，可通过 `--lang <language>` 切换。
 - 保护关键阶段：在 `sync` / `archive` 前检查 FET verify 状态，降低未验证变更被合入或归档的风险。
 - 可选代码图：可接入 GitNexus，在大范围扫描前优先提供结构化代码上下文。
-- Figma 守卫：当 change 产物含 Figma 链接时，自动写入停止协议并让 IDE 在理解失败时先问用户，不猜测样式（无需额外命令）。
+- 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`）。
 
 ## 基本原理
 
@@ -43,31 +47,127 @@ npm install -g @nick848/fet
 ```sh
 fet --version
 fet --help
+fet update
 ```
 
-## 快速开始
+## 第一次使用（推荐顺序）
+
+以下流程面向**第一次在业务项目中接入 FET** 的场景。请在你希望接入 OpenSpec 的**项目根目录**（含 `package.json` 或业务源码的目录）执行，而不是在 FET 工具仓库自身目录。
+
+### 步骤 1：安装依赖工具
+
+1. 安装 [OpenSpec CLI](https://github.com/Fission-AI/OpenSpec)（全局）：
+
+   ```sh
+   npm install -g @fission-ai/openspec
+   openspec --version
+   ```
+
+2. 安装 FET（全局）：
 
-在需要接入 OpenSpec 的项目根目录运行：
+   ```sh
+   npm install -g @nick848/fet
+   fet --version
+   ```
+
+### 步骤 2：初始化项目
+
+在业务项目根目录执行：
+
+```sh
+fet init --yes
+```
+
+`fet init` 会：
+
+- 检测 OpenSpec；若项目尚无 `openspec/`，则调用 `openspec init`
+- 扫描仓库并生成 `AGENTS.md`、`openspec/config.yaml` 的 `fet:` 配置
+- 写入 `openspec/fet-state.json` 等工作流状态
+- 为 **Cursor**、**Codex** 生成 Skill / 规则 / 命令指南（见下文「在 IDE 中使用」）
+- 可选检测 GitNexus（未安装仅提示一次，不阻断）
+
+需要英文产物时，可在初始化时指定：
+
+```sh
+fet init --yes --lang en
+```
+
+### 步骤 3：检查环境
 
 ```sh
-fet init
-fet fill-context
 fet doctor
 ```
 
-典型流程：
+确认 OpenSpec 路径、上下文文件、工具集成无 `fail`。若有锁文件残留，可执行 `fet doctor --fix-lock`。
+
+### 步骤 4：补齐项目上下文（与 IDE 协作）
+
+扫描器无法自动推断的内容会在 `AGENTS.md` 中标记为 `[NEEDS LLM INPUT]`。请执行：
 
 ```sh
-fet new my-change
-fet continue
-fet apply
+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 中），再执行：
+
+```sh
+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 工作流创建并落地第一个变更。简单路径示例：
+
+```sh
+fet propose my-first-change
+# 或在 Cursor/Codex 中按提示逐步执行 fet continue
+fet apply --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`。各阶段说明见下文「日常变更流程」。
+
+---
+
+## 日常变更流程
+
+在已完成「第一次使用」的项目中，典型循环为：
+
+```sh
+fet new my-change          # 或 fet propose my-change
+fet continue               # 按需重复，生成下一规划产物
+fet apply --change my-change
 fet verify --change my-change
 fet verify --done --change my-change
-fet sync
+fet sync --change my-change
 fet archive --change my-change
 ```
 
-`continue`、`apply`、`ff`、`sync` 等命令在未显式传入 `--change` 时，会优先使用 FET 记录的 active change；如果只有一个打开的 change，也会自动使用它。
+说明：
+
+- `continue`、`apply`、`ff`、`sync` 等命令在未传 `--change` 时，优先使用 FET 记录的 **active change**；若仅有一个打开的 change，会自动选中。
+- 经 FET 执行的 `sync` / `archive` 会先检查是否已 `fet verify --done`。
+- 项目结构变化后运行 `fet update-context`；仅刷新 IDE 占位符提示时运行 `fet fill-context`。
 
 ## 语言设置
 
@@ -114,6 +214,7 @@ fet init --lang en
 | 命令 | 用法 | 说明 |
 |------|------|------|
 | `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 状态、上下文文件、工具集成和锁文件。 |
@@ -178,10 +279,13 @@ FET 可能创建或更新：
 - `.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`

package/README_en.md

@@ -1,6 +1,8 @@
 # FET
 
-[中文](./README.md) | [English](./README_en.md)
+[中文](https://unpkg.com/@nick848/fet/README.md) | [English](https://unpkg.com/@nick848/fet/README_en.md)
+
+> The npm package page only renders `README.md`; relative links such as `./README_en.md` return 404. Use the **unpkg** links above to open the other file from the same npm package. Source repo: [Gitee](https://gitee.com/agent-team/fet).
 
 FET is a frontend development workflow orchestration CLI built around OpenSpec. It does not generate business code directly. Instead, it proxies OpenSpec commands, maintains local workflow state, generates auditable project context, and helps AI coding tools such as Cursor and Codex load the right project material.
 
@@ -13,7 +15,9 @@ FET is a frontend development workflow orchestration CLI built around OpenSpec.
 - Unifies language: Chinese is the default for interaction messages and generated artifacts; use `--lang <language>` to switch.
 - Guards critical stages: checks FET verification state before `sync` / `archive`.
 - Supports optional code graphs: integrates with GitNexus so AI tools can prefer structured code context before broad repository scans.
-- Figma guard: when a change references Figma, FET writes a stop protocol so the IDE asks the user instead of guessing styles when design input is unclear (no extra commands).
+- Figma guard: when a change references Figma, FET writes `figma-apply-instructions.md` (read design before UI work on apply) and `figma-stop.md` (stop and ask the user when Figma cannot be read—no guessed styles).
+- Layered bilingual specs: English Requirements/Scenario stay canonical; each Requirement gets a `<!-- 中文：... -->` note. LLM edits must refresh Chinese notes in the same edit (`fet.specLanguage`, `.cursor/rules/fet-spec-language.mdc`).
+- UI display contract: when a change references Figma and/or API docs, FET writes `ui-display-contract.yaml` (draft) and `ui-field-apply-instructions.md`; planning specs must include a Requirement that only `displayFields` may render—OpenAPI must not drive full UI field lists.
 
 ## How It Works
 
@@ -46,29 +50,124 @@ fet --help
 fet update
 ```
 
-## Quick Start
+## First-Time Setup (Recommended Order)
+
+This section is for **bringing FET into a business project for the first time**. Run commands in the **project root** you want OpenSpec to manage (where your app source lives), not inside the FET tool repository itself.
+
+### Step 1: Install required tools
+
+1. Install the [OpenSpec CLI](https://github.com/Fission-AI/OpenSpec) globally:
+
+   ```sh
+   npm install -g @fission-ai/openspec
+   openspec --version
+   ```
+
+2. Install FET globally:
 
-Run this in a project root that should use OpenSpec:
+   ```sh
+   npm install -g @nick848/fet
+   fet --version
+   ```
+
+### Step 2: Initialize the project
+
+From your project root:
+
+```sh
+fet init --yes
+```
+
+`fet init` will:
+
+- Detect OpenSpec and run `openspec init` when `openspec/` is missing
+- Scan the repository and generate `AGENTS.md` plus the `fet:` namespace in `openspec/config.yaml`
+- Write workflow state such as `openspec/fet-state.json`
+- Install **Cursor** and **Codex** integration files (see “Use in your IDE” below)
+- Optionally detect GitNexus (a one-time recommendation if missing; non-blocking)
+
+For English interaction messages and generated artifacts:
+
+```sh
+fet init --yes --lang en
+```
+
+### Step 3: Verify the environment
 
 ```sh
-fet init
-fet fill-context
 fet doctor
 ```
 
-Typical workflow:
+Confirm there are no `fail` results for OpenSpec, context files, or tool integration. Use `fet doctor --fix-lock` if a stale `openspec/.fet.lock` is reported.
+
+### Step 4: Fill project context (with your IDE)
+
+The scanner marks unknown facts in `AGENTS.md` as `[NEEDS LLM INPUT]`. Run:
 
 ```sh
-fet new my-change
-fet continue
-fet apply
+fet fill-context
+```
+
+Then, in **Cursor** or **Codex**, follow the generated handoff (for example `.fet/fill-context.md` or `.cursor/skills/fet-fill-context/SKILL.md`) so the AI can help replace placeholders. Run `fet doctor` again afterward; placeholder checks should pass.
+
+### Step 5: (Optional) Set up a code graph
+
+To let AI prefer structured graph context before broad repository scans, install GitNexus, then:
+
+```sh
+fet graph setup    # installation guide only; FET does not install GitNexus for you
+fet graph init     # first graph build
+fet graph handoff  # IDE handoff document
+```
+
+### Step 6: Use in your IDE
+
+After initialization, make sure your AI tool can read:
+
+| Tool | Main entry points |
+|------|-------------------|
+| Cursor | `.cursor/rules/fet-context.mdc`; `.cursor/skills/fet-*/SKILL.md` |
+| Codex | `.codex/fet/context.md`; `$CODEX_HOME/prompts/fet-*.md` |
+
+Run workflow commands in the **terminal** as `fet <command>` (for example `fet apply`). Calling `openspec` directly bypasses FET state and the verify gate.
+
+### Step 7: Complete your first change
+
+When setup looks healthy, drive your first OpenSpec change. Simple path example:
+
+```sh
+fet propose my-first-change
+# or use fet continue step by step from your IDE handoff
+fet apply --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
+```
+
+For the expanded workflow, start with `fet new <id>` and repeat `fet continue` or run `fet ff`. See “Day-to-day change workflow” below.
+
+---
+
+## Day-to-day change workflow
+
+After first-time setup, a typical loop is:
+
+```sh
+fet new my-change          # or fet propose my-change
+fet continue               # repeat as needed for the next planning artifact
+fet apply --change my-change
 fet verify --change my-change
 fet verify --done --change my-change
-fet sync
+fet sync --change my-change
 fet archive --change my-change
 ```
 
-When `continue`, `apply`, `ff`, or `sync` is called without `--change`, FET first uses the recorded active change. If there is exactly one open change, FET uses it automatically.
+Notes:
+
+- When `continue`, `apply`, `ff`, or `sync` is called without `--change`, FET uses the recorded **active change**, or the only open change when there is exactly one.
+- `sync` and `archive` through FET require `fet verify --done` first.
+- Run `fet update-context` after major project structure changes; run `fet fill-context` when you only need to refresh IDE placeholder handoff.
 
 ## Language
 
@@ -180,10 +279,13 @@ FET may create or update:
 - `.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` (written on apply when the change references Figma)
 - `openspec/changes/<change-id>/.fet/figma-stop.md` (written when the change references Figma)
 - `.codex/fet/commands/*.md`
 - `$CODEX_HOME/prompts/fet-*.md`