@fastcar/cli 脚手架工具

Fastcar 脚手架工具，用于快速初始化项目模板。

特性

• 🚀 通过 npm 包管理模板，动态获取最新版本
• 📦 支持多种项目模板（web、rpc、cos、micro、static）
• 🎯 交互式模板选择
• ⚡ 自动合并依赖和配置
• 🗜️ 项目打包（自动排除 devDependencies、日志文件）
• 🔄 数据库表逆向生成
• 🤖 AI Agent Skill 管理（支持 Kimi、Claude、Cursor）
• 🔁 自动迭代编码 skill：支持有边界的实现、验证、修复、优化和 session 恢复

安装

全局安装（推荐）

npm install -g @fastcar/cli

使用 npx（无需安装）

npx @fastcar/cli init

使用命令

查看版本

fastcar-cli -v
# 或
fastcar-cli --version

查看帮助

fastcar-cli --help

初始化项目

# 交互式选择模板
fastcar-cli init

# 直接指定模板
fastcar-cli init web
fastcar-cli init rpc
fastcar-cli init cos
fastcar-cli init micro
fastcar-cli init static

# Agent/CI 非交互初始化，并同步项目级 Agent 配置
fastcar-cli init web my-project --yes --package-manager npm --with-agent

# 指定可选组件和 Agent target
fastcar-cli init rpc rpc-service --yes --components pgsql,redis --agent-target codex

# 常用参数
# --yes / -y                非交互模式，适合 Agent / CI
# --package-manager npm|yarn|pnpm  指定安装依赖时使用的包管理器
# --components pgsql,mysql,redis,mongo  指定可选数据库组件
# --with-agent              初始化项目级 Agent 配置目录
# --agent-target agents|codex|kimi|claude|cursor  指定 Agent 配置位置

项目打包

将项目打包成 zip 文件，自动排除 devDependencies、node_modules、dist、logs 和 *.log 文件。

# 自动检测包管理器（根据 lock 文件）
fastcar-cli pack

# 指定包管理器
fastcar-cli pack npm
fastcar-cli pack yarn
fastcar-cli pack pnpm

打包后的文件位于 dist/{name}-{version}.zip，解压后目录名为当前项目文件夹名。

数据库逆向生成

根据数据库表结构生成 Model 和 Mapper 文件。

# 生成配置文件
fastcar-cli reverse:init

# 执行逆向生成
fastcar-cli reverse

配置文件 reverse.config.json 示例：

{
  "tables": ["test"],
  "modelDir": "/path/to/models",
  "mapperDir": "/path/to/mappers",
  "dbConfig": {
    "host": "localhost",
    "port": 3306,
    "user": "root",
    "password": "password",
    "database": "test_db"
  },
  "style": {
    "tabWidth": 4,
    "printWidth": 200,
    "trailingComma": "es5",
    "useTabs": true,
    "parser": "typescript",
    "endOfLine": "crlf"
  },
  "ignoreCamelcase": false
}

Skill 管理

将 FastCar skill 安装到支持的 AI Agent 中，让 AI 在对话时掌握 FastCar 框架知识。

启动自动迭代开发

auto-iterate 当前采用 main_agent_controlled：主 Agent 持有完整目标，可以直接实现，也可以根据工作包依赖、冲突风险和资源动态委派或并行；主 Agent 负责整体 diff、权威验证和最终交付。CLI 不再持有外部 Worker 主循环；--run、--check、--dispatch 仅作为 legacy 输入被识别并拒绝，不是可用执行路径。

默认使用 Agent-first 入口，由 Agent 自动推断 intent、profile、session、预算、工作包和验证：

fastcar-cli auto-iterate --agent --goal "修复登录失败问题"
fastcar-cli auto-iterate --agent --goal "完整实现 docs/prd.md" --from docs/prd.md
fastcar-cli auto-iterate --agent --goal "修复登录失败问题" --session login-bugfix
fastcar-cli auto-iterate --agent --goal "只规划订单模块重构，不写代码"

在第二个终端开启双层实时进度，默认观察 current session：

fastcar-cli auto-iterate --visual
fastcar-cli auto-iterate --visual login-bugfix --open
fastcar-cli auto-iterate --visual login-bugfix --port 4318

--visual 同时输出去重后的终端摘要，并在 127.0.0.1 启动只读 Web dashboard。--dashboard [session] 仅生成一次性静态快照；--visual 不得与 --agent 在同一进程运行。

显式 mode 和 --session 仍可用于高级覆盖或 legacy 管理兼容，但不是自然语言任务的默认入口。用户明确要求 protocol-only / LLM-only、手动模式或不启动 Subagent 时才追加 --no-run：

fastcar-cli auto-iterate --agent --goal "修复登录失败问题" --no-run

缺少 Subagent 能力不会强制切换 protocol-only；主 Agent 可以直接实现或使用平台等价能力，并记录能力降级。

Codex /goal 与 auto-iterate 配合

Codex /goal 和 fastcar-cli auto-iterate --goal 可以配合使用，但职责不同：

• /goal 是交互式 Codex 的会话级目标入口，用于记录当前整体 objective、status 和可选预算。
• fastcar-cli auto-iterate --goal 是 CLI 的目标文本参数，只写入 auto-iterate session 和启动提示。
• .agent-state/auto-iterate/<session>/state.json 是自动迭代的可恢复状态源，负责 mode、session、预算、需求覆盖矩阵、验证证据、恢复和交付门禁。

推荐流程：

1. 在交互式 Codex 输入 /goal，把当前 Codex goal 设为整体任务目标。
2. 用户只描述目标；主 Agent 调用 `fastcar-cli auto-iterate --agent --goal "<目标>"`，自动判断 intent、profile、session、预算、工作包和验证。
3. `--agent` 自动创建或恢复需要持久化的 session；仅在需要固定名称时传入 `--session <name>`。
4. 执行中保持 /goal objective 与 state.json.task.goal 语义一致；具体预算、RCM 和验证证据以 state.json 为准。
5. 只有 auto-iterate 交付门禁通过后，才把 Codex goal 标记为 complete；真正阻塞时才标记 blocked。

普通聊天里的 Goal: 前缀最多被 CLI 清洗为目标文本，不会创建或更新 Codex goal。本地 Codex 是否支持 goal 模型可用 codex features list 辅助验证；看到 goals stable true 表示该运行时启用了 goal feature。实际创建、查看或更新 goal 的入口是交互式 Codex 的 /goal，不是 codex goal 子命令。

auto-iterate-coding 使用技巧与文档引用

auto-iterate-coding 的完整协议以仓库内 skills/auto-iterate-coding/ 为准，README 只保留发包用户最常用的入口说明。建议先阅读这些文档：

• skills/auto-iterate-coding/SKILL.md：主协议，定义触发词、模式选择、能力降级、状态维护、停止条件和最终交付规则。
• docs/auto-iterate-current-architecture.md：当前有效架构，说明主 Agent 控制、动态工作包、验证门禁和旧 CLI Worker 路径边界。
• docs/auto-iterate-v3-correctness-proof.md：独立 Observer、Oracle、证据包和发布正确性门禁。
• skills/auto-iterate-coding/references/natural-language-routing.md：自然语言到 fastcar-cli auto-iterate ... 的路由规则。
• skills/auto-iterate-coding/references/state-schema.md：.agent-state/auto-iterate/<session>/state.json 的强约束字段、生成视图和一致性规则。
• skills/auto-iterate-coding/examples/state-template.md：state.md 人类阅读视图的渲染模板。
• skills/auto-iterate-coding/examples/end-to-end-scenarios.md：端到端场景示例，展示启动、执行、验证和交付摘要。

核心技巧如下：

• 普通任务直接使用 --agent --goal "<目标>"；Agent 自动判断是否需要持久化 session，并自动命名或恢复匹配任务。用户明确要求固定名称时才传 --session <name>。
• 显式 mode flags 仅用于需要强制覆盖自动推断的高级场景和 legacy 管理兼容，新示例不再要求用户学习这些参数。
• 主 Agent 可直接实现关键路径，也可动态创建、复用或并行委派工作包；不得退回固定“主 Agent + 单 coder”拓扑。
• max_iterations 和 autopilot_max_iterations 是预算，不是必须跑满的轮数。验证已通过、风险高于收益、缺少外部资源或达到预算时，Agent 应停止并说明状态。
• 不要把静态阅读当作验证。Agent 必须优先运行真实命令，例如 npm test、npm run build、npm run typecheck；无法运行时要把相关需求标记为 not_verified 或 blocked。
• 长任务要持续维护 .agent-state/auto-iterate/<session>/state.json，并刷新生成视图 .agent-state/auto-iterate/<session>/state.md。恢复任务时使用 fastcar-cli auto-iterate --resume <session>，由主 Agent 继续当前 main_agent_controlled 编排。
• 最终交付不要只看“测试通过”。长清单按需输出需求覆盖状态；普通任务只需说明实现范围、真实验证、未验证项和剩余风险。

推荐工作流：

# 1. 安装 skill
fastcar-cli skill install auto-iterate-coding

# 已安装版本漂移时一键同步
fastcar-cli skill sync auto-iterate-coding --global --target agents

# 2. 默认 Agent-first 入口；自动推断并按需创建或恢复 session
fastcar-cli auto-iterate --agent --goal "修复登录失败，最多迭代 5 轮"

# 3. 只有用户明确要求 protocol-only / LLM-only 时才追加 --no-run
fastcar-cli auto-iterate --agent --goal "修复登录失败" --no-run

# 4. 中断后恢复
fastcar-cli auto-iterate --resume login-bugfix

列出可用的 skills

fastcar-cli skill list

列出支持的 AI Agents

fastcar-cli skill targets

安装 skill

# 交互式选择安装位置（全局/本地）
fastcar-cli skill install fastcar-framework

# 全局安装（默认写入通用 agents 目录，Codex/Kimi 等可识别）
fastcar-cli skill install fastcar-framework --global
fastcar-cli skill install fastcar-framework -g

# 本地安装（仅当前项目可用）
fastcar-cli skill install fastcar-framework --local
fastcar-cli skill install fastcar-framework -l
# 若项目根目录不存在 AGENTS.md，会自动补到项目根目录

# 单独安装自动迭代编码 skill
fastcar-cli skill install auto-iterate-coding
fastcar-cli skill install auto-iterate-coding --global
fastcar-cli skill install auto-iterate-coding --local

# 非交互同步 bundled 版本；--agent 检测到漂移时会返回此命令
fastcar-cli skill sync auto-iterate-coding --global --target agents
fastcar-cli skill sync auto-iterate-coding --local --target agents

# 安装全部 skills（会同时补充共享的 AGENTS.md）
fastcar-cli skill install all
fastcar-cli skill install --all -g

# 指定目标 agent
fastcar-cli skill install fastcar-framework --target agents
fastcar-cli skill install fastcar-framework --target codex
fastcar-cli skill install fastcar-framework --target kimi
fastcar-cli skill install fastcar-framework -t claude

可用的 FastCar Skills

| Skill 名称 | 适用场景 | 安装命令 | |-----------|---------|---------| | fastcar-framework | IoC 核心、Koa Web、项目模板、基础配置 | fastcar-cli skill install fastcar-framework | | fastcar-database | MySQL/PGSQL/MongoDB/Redis ORM、逆向生成 | fastcar-cli skill install fastcar-database | | fastcar-rpc-microservices | RPC 通信、微服务架构、Socket/gRPC | fastcar-cli skill install fastcar-rpc-microservices | | fastcar-serverless | 阿里云 FC / 腾讯云 SCF / AWS Lambda | fastcar-cli skill install fastcar-serverless | | fastcar-toolkit | 缓存、定时任务、时间轮、工作线程池、COS SDK | fastcar-cli skill install fastcar-toolkit | | auto-iterate-coding | 自动迭代式 AI 编程、多轮实现-验证-修复-优化 | fastcar-cli skill install auto-iterate-coding |

卸载 skill

fastcar-cli skill uninstall fastcar-framework

# 卸载全部 skills（保留共享的 AGENTS.md）
fastcar-cli skill uninstall all
fastcar-cli skill uninstall --all -l

初始化项目级 agent 配置

fastcar-cli skill init

其他命令

# 清除多余依赖库
fastcar-cli clean node_modules

# 压缩依赖库
fastcar-cli compress node_modules

快速开始

创建 Web 项目示例

# 创建项目目录
mkdir my-project
cd my-project

# 初始化项目（交互式选择模板）
fastcar-cli init

# 或者直接指定 web 模板
fastcar-cli init web

# Agent/CI 非交互初始化
fastcar-cli init web my-project --yes --package-manager npm --with-agent

# 安装依赖
npm install

# 启动项目
npm run dev

打包项目示例

# 进入项目目录
cd my-project

# 打包项目（自动检测包管理器）
fastcar-cli pack

# 使用 yarn 打包
fastcar-cli pack yarn

# 输出: dist/my-project-1.0.0.zip

可用模板

| 模板名称 | 包名 | 说明 | |---------|------|------| | web | @fastcar/template-web | Web 应用模板 | | rpc | @fastcar/template-rpc | RPC 服务模板 | | cos | @fastcar/template-cos | COS 存储模板 | | micro | @fastcar/template-microservices | 微服务模板 | | static | @fastcar/template-static | 静态资源模板 |

自定义模板

创建模板包

1. 初始化 npm 项目

mkdir template-mytemplate
cd template-mytemplate
npm init

2. 创建 template/ 目录并放入项目文件

3. 发布到 npm

npm publish --access public

模板结构约定：模板包中应包含 template/ 目录，并在 package.json 中声明模板包名称、版本和生产依赖。

注册模板

在 src/templates.json 中添加模板配置：

{
  "mytemplate": {
    "name": "mytemplate",
    "description": "我的自定义模板",
    "package": "@fastcar/template-mytemplate",
    "tags": ["custom"]
  }
}

模板包规范

模板包必须遵循以下结构：

template-xxx/
├── package.json          # 模板包的 package.json
├── README.md            # 模板说明文档
└── template/            # 模板文件目录（必需）
    ├── package.json     # 项目模板中的 package.json
    └── ...              # 其他项目文件

许可证

MIT