# ai-agent-cli

**Repository Path**: junluoyu/ai-agent-cli

## Basic Information

- **Project Name**: ai-agent-cli
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-08
- **Last Updated**: 2026-05-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AI Agent CLI 流程编排引擎

> 支持 Claude / Codex / Kimi 等多 CLI 工具的流程编排、状态机管理、断点续接。

## 核心能力

| 能力 | 说明 |
|------|------|
| **流程编排** | 7 阶段标准化流程（init → planning → design → impl → review → test → deploy） |
| **状态机** | 8 状态严格转移矩阵，脚本独占写入，大模型只读不写 |
| **断点续接** | 崩溃/关机/中断后快速恢复，~500 tokens 上下文 |
| **并行执行** | 多模块并行开发，会话隔离，产物自动合并 |
| **门禁校验** | 7 种内置校验器（覆盖率/lint/测试/文件/产物/自定义） |
| **MCP 桥接** | 只读查询接口，7 个工具 + 3 个资源 URI |
| **终端交互** | 彩色 STOP 提示 + zCode IDE 结构化输出 |

## 快速开始

### 方式 1：命令行（用户级安装）

```bash
# 用户级安装（一次，跟 Claude/Kimi 一样）
./install.sh

# 在任何项目目录使用
mkdir my-project && cd my-project
agent-cli --init              # 初始化项目文档（零 Token）
agent-cli --new my-feature    # 创建新会话
agent-cli --resume my-feature # 续接会话
```

### 方式 2：开发模式（项目内）

```bash
# 不安装，直接用项目内的脚本
node agent-cli.js --init
node agent-cli.js --new my-feature
```

### 方式 2：Claude 对话 Skill 指令

安装 skill 后，在 Claude 对话中直接使用：

```
/stack:new my-project          # 创建新会话
/stack:resume my-project       # 续接会话
/stack:status                  # 查看状态
/stack:step                    # 执行当前步骤
/stack:confirm                 # 确认通过，推进下一步
/stack:modify                  # 继续修改当前步骤
/stack:parallel user,order,pay # 启动并行会话
/stack:list                    # 列出所有会话
```

安装 skill：
```bash
# 1. 安装到 OpenClaw skills 目录
cp -r skills/stack-cli ~/.openclaw/workspace/skills/

# 2. 或通过 skill 安装器
node lib/skill-installer.js install-local skills/stack-cli
```

## 安装架构

**一个用户级目录 + 项目级数据**

```
# 用户级（只有一个目录）
~/.gsd-flow/
├── agent-cli          # 命令入口（加入 PATH 即可）
├── agent-cli.js       # 引擎入口
├── lib/
│   ├── core/          # 14 个核心引擎模块
│   ├── bridge/        # 桥接层
│   └── skill-installer.js
├── templates/         # 示例文档模板
│   └── init-docs/
├── skills/            # 系统级 OpenClaw Skill
├── .gsd/              # 默认流程配置
├── config.json        # 用户配置
└── sessions/          # 会话索引（运行时创建）

# 项目级（每个项目独立）
my-project/
├── AGENTS.md          # ← agent-cli --init 创建
├── PROJECT.md
├── KNOWLEDGE.md
├── docs/              # ← 项目文档
├── .gsd/              # ← 项目流程配置与状态
├── .agent-sessions/   # ← 会话私有空间
├── src/modules/       # ← 源码产出
└── tests/
```

## 引擎模块

| 模块 | 文件 | 职责 |
|------|------|------|
| 原子 IO | `lib/core/atomic-io.js` | 原子写入 + 乐观锁 + 备份 |
| 状态管理 | `lib/core/state-manager.js` | 状态读写 + 转移矩阵严格校验 |
| 流程引擎 | `lib/core/workflow-engine.js` | 流程解析 + 节点路由 |
| 编排器 | `lib/core/orchestrator.js` | 主编排器，串联所有模块 |
| 门禁校验 | `lib/core/gate-validator.js` | 7 种内置校验器 |
| 任务分发 | `lib/core/dispatch-controller.js` | 模块拆分 + 依赖拓扑 + 状态同步 |
| 进程守护 | `lib/core/process-guard.js` | 信号捕获 + 崩溃自动保存 |
| 会话管理 | `lib/core/session-manager.js` | 会话 CRUD + 注册表 |
| 续接流程 | `lib/core/resume-flow.js` | 检测 → 恢复 → 验证 → 上下文 |
| 上下文压缩 | `lib/core/context-compressor.js` | 续接上下文 ~500 tokens |
| 产物合并 | `lib/core/merge-controller.js` | 冲突检测 + 并行合并 |
| 快照管理 | `lib/core/snapshot-manager.js` | 快照创建/恢复 |
| 提示词注册 | `lib/core/prompt-registry.js` | 统一提示词 + 门禁词体系 |
| 终端 UI | `lib/core/terminal-ui.js` | 彩色输出 + zCode JSON |
| MCP 桥接 | `lib/bridge/mcp-server.js` | 只读查询（7 工具 + 3 资源） |
| Hook 桥接 | `lib/bridge/hook-bridge.js` | Claude Hooks |

## 状态机

```
created → running → waiting-user-input → interrupted → resuming → running → completed
            ↓              ↓                ↓
         checkpoint    checkpoint       checkpoint
```

- 状态转移由脚本独占执行
- 转移矩阵硬编码校验，防止篡改
- 阶段转移：init → planning → design → impl → review/test → deploy → completed

## 门禁词体系

| 类别 | 关键词 | 动作 | 颜色 |
|------|--------|------|------|
| F（确认通过） | confirm, advance, proceed, 通过, 确认 | 推进下一步 | 🟢 绿色 |
| M（继续修改） | modify, retry, revise, 修改, 重试 | 当前步骤重试 | 🟡 黄色 |
| R（回滚） | rollback, back, 回退, 回滚 | 回滚到指定步骤 | 🔴 红色 |
| X（中止） | abort, stop, exit, 中止, 退出 | 终止流程 | ⚪ 灰色 |

## 文档

- `docs/master-plan.md` — 总体规划
- `docs/architecture.md` — 架构设计
- `docs/implementation-plan.md` — 执行计划
- `docs/technical-decisions.md` — 技术决策

## License

MIT