faf-cli 是围绕 .faf（Foundational AI Format）上下文格式构建的命令行工具，目标是让 AI 编程智能体从仓库的真实技术栈中获取准确、版本化的项目上下文。官方描述强调：每个 AI 编程智能体读取的上下文，由你的仓库生成，而非猜测。
用途
- 为 AI 编程智能体（如 Claude Code、Grok、Cursor、GitHub Copilot 等）提供项目级上下文。
- 用单个 project.faf 文件自动生成 AGENTS.md、CLAUDE.md、GEMINI.md 和 .cursorrules 等智能体指令文件，避免内容漂移和重复说明。
- 让上下文跟随 Git 版本管理，每次克隆、复刻或检出都能获得完整 AI 上下文。
主要能力
- 自动检测：运行 faf auto 可检测并填充项目信息；不带参数运行 faf 可显示项目评分。
- 多格式生成：通过 faf export 可生成 AGENTS.md（--agents）、Copilot 可读文件（--copilot）等。
- 评分机制：从 v8.0 起采用 always-33 评分内核（Rust WASM），在全部 33 个 Mk4 槽位上评分，应用类型决定哪些槽位激活，其余槽位标记为 slotignored 但仍可见。建议目标为 Trophy 100%。
- 自定义规则：可在 project.faf 的 ai_instructions.warnings 中写入自定义指令，会原样出现在 faf 编写的每个 AGENTS.md 顶部。
- Git 原生：v7.0 起支持 faf diff、faf log、faf hooks，上下文随代码版本化。
- Cards 与身份：v8.1 起可通过 faf card init 以七个问题生成 agent.fafa、AI Catalog 条目和 ARD 条目；.fafa 是 Agent Layer 的便携身份格式。
- 记忆格式：.fafm 是 v7.2.0 引入的可移植智能体记忆格式，与 claude-fafm-sdk 1.0 互操作。
- 渲染与展示：faf show 可将 .faf 渲染为可浏览页面；faf loop 可驱动仓库达到 100% 或遇到人为瓶颈。
- 编译产物：v6.0 起使用 Bun 单文件编译，可生成独立二进制，适用于 CI/CD、Docker 或隔离环境。
使用方式（基于官方文本）
- 安装后运行 faf 无参数查看项目评分，faf auto 自动检测并填充。
- 运行 faf --help 查看完整命令集和选项。
- 通过 npm、PyPI、crates.io 分发。
- 自定义规则写入 project.faf 的 ai_instructions.warnings。
- 生成 AGENTS.md 使用 faf export --agents；生成 Copilot 文件使用 faf export --copilot。
适用场景
- 多 AI 编程工具并存的项目，需要统一上下文来源。
- 希望上下文随代码版本化、避免每次向 AI 重复解释项目背景的团队。
- 需要为 CI/CD、Docker 或隔离环境提供单文件二进制的场景。
- 为智能体提供便携身份（.fafa）与记忆（.fafm）的场景。
限制与说明
- 官方文本未提供具体收费、价格或商业授权信息；项目采用 MIT 许可，免费开源。
- 官方文本未说明支持的操作系统细节，仅提及编译产物覆盖四个平台、测试在 Windows、Ubuntu、macOS 上运行。
- 评分目标为 100%，低于 100% 的层级仍存在于评分阶梯中，但官方不再以 85% 为目标。
- 官方文本提及从 7.x 升级到 8.x 时，缺少 12 个 enterprise 标记的 .faf 评分可能下降（21 个填充 = 64%），可运行 faf auto 写入标记恢复评分。
- 官方文本未提供具体的安装命令，仅说明通过 npm、PyPI 和 crates.io 分发；如需安装命令请参考各平台包管理器。
