@nick848/dev-cli

v3.0.1

Published

25 days ago

A staged AI-driven engineering workflow CLI.

0High
0Medium
0Low

nick848

dev-cli

dev-cli 是一个面向工程接管场景的 AI 工作流 CLI。

它的目标不是替代现有工程规范，而是把一条完整的研发链路串起来：

需求 -> 澄清 -> 研究 -> 设计选择 -> 规格 -> 测试草案 -> 实现蓝图 -> 代码落地 -> 校验 -> 归档

核心定位

LLM 负责什么

LLM 负责“生成内容”和“理解上下文”：

理解当前工程
理解用户需求
生成需求提案 propose.md
生成行为规格 spec.md
生成接口规格 api.yaml
生成测试草案
生成实现蓝图
生成代码内容
根据失败反馈重新修正内容

CLI 负责什么

CLI 负责“流程把控”和“稳定落地”：

管理工作流阶段
管理状态与确认点
记录产物路径和历史
驱动 OpenSpec / 校验命令
应用代码修改
执行 lint / build / test
处理 retry / undo / resume / close
在失败后把反馈重新回流给 LLM

一句话概括：

LLM 负责写什么
CLI 负责什么时候写、写到哪、写错了怎么修

工作流

默认工作流如下：

propose
research
design-options
new
tdd
blueprint
apply
compile
archive
done

说明：

research 和 design-options 只会在合适场景触发，不是每个需求都会进入。
new 阶段现在会同时生成：
- spec.md：行为规格，采用 GIVEN / WHEN / THEN
- api.yaml：接口规格，优先由 OpenSpec 原生命令生成

安装与运行

环境要求

Node.js >=20
可用的 DeepSeek API Key

安装依赖

npm install

开发模式

npm run dev

构建并运行

npm run build
node dist/index.js

查看版本

node dist/index.js -v
node dist/index.js --version

快速开始

启动 CLI

dev-cli

初始化当前工程

/init

如果还没有配置 DeepSeek Key，CLI 会在交互区直接引导你输入，不需要记额外参数。

也可以显式传入：

dev-cli init --deepseek-api-key <your-key>

或者先设置环境变量：

$env:DEEPSEEK_API_KEY="<your-key>"
dev-cli init

直接输入需求

实现一个新的前端页面，支持查询和结果展示

按工作流逐步推进

/next

需求澄清与设计选择

需求不明确时

CLI 会停在 propose 阶段，不允许直接 /next。

此时 propose.md 会包含待确认问题，问题内容由 LLM 根据当前业务动态生成，CLI 本身不预置业务问题。

如果存在选项：

↑ / ↓：切换选项
空格：选中当前选项
回车：提交

也可以直接输入“其他观点”。

设计风格不明确时

对于前端页面类需求，CLI 可能会进入 design-options 阶段，给出 2-3 个可选方向，由用户确认后再进入实现。

OpenSpec 约定

OpenSpec 是规格基座。

`new` 阶段产物

spec.md
- 行为规格
- 使用 GIVEN / WHEN / THEN
api.yaml
- 接口规格
- 优先使用 OpenSpec 原生命令生成与校验

当前原则

OpenSpec 负责规范定义
CLI 负责串联流程
后续 blueprint / apply 会显式消费 spec.md + api.yaml

主要命令

| 命令 | 作用 | 说明 | | --- | --- | --- | | /init | 初始化当前工程 | 生成 AGENTS.md、.dev-cli/config.yaml、.dev-cli/project-context.yaml 等 | | /status | 查看当前状态 | 支持 --json | | /artifact | 查看当前或历史产物 | 支持 --json、--raw、--list、--node <name> | | /next | 确认当前阶段并推进 | 当前阶段未满足前置条件时会被阻止 | | /apply | 从 blueprint 显式进入代码落地 | 也可在 apply failed 时重新执行 | | /retry | 重试当前失败阶段 | 会根据失败类型决定是局部重试还是回上游重规划 | | /undo | 回滚当前变更的落地结果 | 主要用于 apply 之后 | | /resume | 恢复未完成流程 | CLI 重启后继续当前变更 | | /edit | 标记当前产物进入外部编辑态 | 适合手动修改产物文件 | | /confirm-tweak | 确认外部编辑完成 | 重新回到待确认状态 | | /close | 关闭当前活跃变更 | 清理状态、产物，并尽量回滚该变更带来的代码修改 | | /help | 查看内建帮助 | 显示命令和交互说明 |

常见命令示例

| 场景 | 示例 | | --- | --- | | 初始化工程 | /init | | 查看状态 | /status | | 查看 JSON 状态 | /status --json | | 查看当前产物 | /artifact | | 查看当前产物原文 | /artifact --raw | | 查看某个节点产物 | /artifact --node blueprint --json | | 列出所有已有产物 | /artifact --list | | 推进下一阶段 | /next | | 显式开始落代码 | /apply | | 失败后重试 | /retry | | 回滚实现 | /undo | | 恢复中断流程 | /resume | | 关闭当前变更 | /close |

交互规则

自然语言输入

CLI 会根据当前阶段决定自然语言输入的含义：

没有活跃变更时：作为新需求
propose / research / design-options / new / tdd / blueprint：作为当前变更的 refinement
apply / compile / archive：必要时会先回到更上游阶段再重规划

输入历史

↑ / ↓ 支持浏览历史输入
当当前阶段存在选项问题时，方向键会优先用于选择问题答案

初始化后生成的关键文件

`AGENTS.md`

面向 LLM 和协作者阅读，主要描述：

这个项目是做什么的
技术栈
工程结构
如何运行和验证
工程级注意事项
高风险区域

`.dev-cli/config.yaml`

面向 CLI 执行，主要描述：

路径配置
工作流配置
约束规则
命令配置
代码生成和落地策略

`.dev-cli/project-context.yaml`

面向工程画像，主要描述：

项目类型
技术栈
目录结构
常用命令
UI 组件偏好
import / alias 规则
代表性文件样本

校验与失败修复

`compile` 阶段默认顺序

lint -> typecheck/build -> test

失败后会发生什么

apply 和 compile 的失败信息会被结构化记录
/retry 不再只是机械重放
CLI 会根据失败类型决定：
- 当前 step 局部重试
- 回到 blueprint
- 回到更上游阶段重新规划

测试

类型检查

npm run typecheck

构建

npm run build

E2E 测试

npm run test:e2e

全量测试

npm test

当前边界

这是一个通用工程接管 CLI，不应该内置任何具体业务逻辑。
业务问题、需求澄清问题、设计方向内容，应该由 LLM 基于当前工程和当前需求动态生成。
当前 CLI 仍在持续强化：
- 前端工程结构识别
- OpenSpec 约束消费
- apply 稳定性
- 失败反馈回流