# Agent Forge

**Repository Path**: han-liming/agent-forge

## Basic Information

- **Project Name**: Agent Forge
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-30
- **Last Updated**: 2026-07-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Agent Forge ⚒️

> **AI 无关、多层架构的 CLI 编排器** — 让大语言模型（Cursor、Claude Code、GitHub Copilot）在软件开发生命周期（SDLC）中更规范、更高效、更可控。

Agent Forge 充当项目的 **单一事实来源（SSoT）** 和 **上下文编译器**。它在本地生成高度定制的 Markdown 指令，引导您偏好的 AI IDE 助手按照标准化的工程工作流进行开发，无需直接消耗 API Token。

---

## 🌟 核心特性

### 四层架构

| 层级 | 名称 | 状态 | 核心能力 |
|:--:|:--|:--:|:--|
| Layer 1 | **基础层** (Skills & Configs) | ✅ | 统一配置管理、多端同步生成、技能系统、SQLite 持久记忆 |
| Layer 2 | **规格层** (Spec Engine) | ✅ | OpenSpec 工作流：Propose → Apply → Archive |
| Layer 3 | **治理层** (Agent Engine) | ✅ | 角色引擎（Analyst/Architect/Developer/QA）、工作流向导 |
| Layer 4 | **质量层** (Quality Engine) | ✅ | 本地安全扫描、代码审查上下文、TDD 测试门控 |

### 功能清单

#### ✅ 已实现

- ✅ **统一 CLI 入口** — `forge` 命令集成了所有功能
- ✅ **渐进式模式** — `quick` / `standard` / `full` 三档按需启用
- ✅ **SSoT 配置** — 一套 `.forge/config.yaml`，自动生成 `CLAUDE.md` / `.cursor/rules/` / `.github/copilot-instructions.md`
- ✅ **技能系统** — 内置 TDD、Git Workflow、Web-App 技能，支持自定义
- ✅ **持久记忆** — 基于 `node:sqlite` 的跨会话记忆（decisions / patterns / lessons）
- ✅ **规格驱动开发** — `forge propose` 生成 Proposal + Tech Design + Tasks，`forge apply` 追踪进度，`forge archive` 归档
- ✅ **角色引擎** — 4 个内置角色 Persona，`forge agent <role> <task>` 编译上下文
- ✅ **工作流向导** — `forge workflow start` 交互式引导 SDLC 全流程
- ✅ **安全扫描** — `forge security-scan` 本地毫秒级扫描 AWS 密钥、JWT、硬编码密码
- ✅ **代码审查** — `forge review` 生成 AI 审查上下文
- ✅ **TDD 门控** — `forge test` 跨包管理器统一测试入口
- ✅ **国际化** — 中英文双语（`--lang zh-CN` / `--lang en`），自动检测系统语言

#### 🚧 规划中

- 🚧 **Spec Verify** — 验证实现是否符合 spec 约定
- 🚧 **Delta Tracking** — ADDED/MODIFIED/REMOVED 变更追踪
- 🚧 **Skill Marketplace** — 远程技能注册表，`forge skill search/install`
- 🚧 **项目模板系统** — Next.js / NestJS / FastAPI 等预置模板
- 🚧 **效率指标看板** — Spec 完成率、Bug 密度等数据化运营
- 🚧 **团队云同步** — `forge team init` 团队级配置同步
- 🚧 **AI 辅助规格生成** — Smart Spec（可选 LLM 接入）
- 🚧 **VitePress 文档站** — 完整在线文档

---

## 🛠️ 技术栈

| 模块 | 技术 | 说明 |
|:--|:--|:--|
| 语言 | TypeScript 6.x (ES2022) | 严格模式，类型安全 |
| 包管理 | pnpm 10.x workspaces | Monorepo 标准方案 |
| 构建编排 | Turborepo 2.x | 增量构建 + 远程缓存 |
| CLI 框架 | Commander.js 14.x | 成熟稳定的命令行框架 |
| 交互提示 | Inquirer.js 13.x | 交互式向导 |
| 输出美化 | chalk 5.x + ora 9.x | 彩色输出 + 加载动画 |
| 国际化 | i18next | 中英文双语支持 |
| 配置格式 | YAML (js-yaml) | 人类可读、Git 友好 |
| 模板引擎 | Handlebars | 生成 AI 工具配置文件 |
| 存储 | node:sqlite | 内置 SQLite，零依赖记忆存储 |
| 版本管理 | Changesets | Monorepo 版本发布 |
| 测试 | Vitest 4.x | 快速、TS 原生支持 |

---

## 📁 项目结构

```
agent-forge/
├── packages/
│   ├── cli/                 # CLI 入口 (@rx-agent-forge/cli)
│   │   └── src/commands/    # init, skill, update, config, memory, spec, agent, workflow, quality
│   ├── core/                # 核心引擎 (@rx-agent-forge/core)
│   │   └── src/             # ConfigManager, FileManager, Logger, MemoryManager, TemplateEngine
│   ├── skills/              # 技能系统 (@rx-agent-forge/skills)
│   │   └── skills/          # tdd, git-workflow, web-app
│   ├── spec-engine/         # 规格引擎 (@rx-agent-forge/spec-engine)
│   │   └── src/             # ProposeEngine, ApplyEngine, ArchiveEngine
│   ├── agent-engine/        # 角色引擎 (@rx-agent-forge/agent-engine)
│   │   ├── agents/          # analyst, architect, developer, qa
│   │   └── src/             # RoleManager, ContextBuilder
│   ├── quality/             # 质量引擎 (@rx-agent-forge/quality)
│   │   └── src/             # TDDEnforcer, ReviewEngine, SecurityScanner
│   ├── i18n/                # 国际化 (@rx-agent-forge/i18n)
│   │   └── src/locales/     # en.json, zh-CN.json
│   └── adapters/            # AI 工具适配器 (@rx-agent-forge/adapters)
│       └── src/             # ClaudeAdapter, CursorAdapter, CopilotAdapter
├── .forge/                  # Agent Forge 工作区（项目级配置）
│   ├── config.yaml          # 全局配置
│   ├── project-context.md   # 项目宪法
│   ├── memory/              # 持久记忆
│   ├── skills/              # 已安装技能
│   ├── specs/               # 规格管理（active/archive）
│   └── agents/              # 角色定义（可选）
├── .changeset/              # 版本管理配置
├── turbo.json               # Turborepo 任务编排
├── pnpm-workspace.yaml      # Monorepo 工作区
├── tsconfig.base.json       # TypeScript 基础配置
└── package.json             # 根 package.json
```

---

## 🚀 快速开始

### 1. 环境要求

- **Node.js** >= 20.19.0（需支持 `node:sqlite` 内置模块）
- **pnpm** >= 10.x

### 2. 安装

#### 方式一：本地开发（当前推荐）

```bash
git clone <repo-url>
cd agent-forge
pnpm install
pnpm build
# 全局链接
cd packages/cli && pnpm link --global
```

#### 方式二：全局安装（发布后可用）

```bash
npm install -g @rx-agent-forge/cli
```

### 3. 初始化项目

在您的项目根目录运行：

```bash
# 交互式初始化（推荐）
forge init

# 指定模式和语言
forge init --mode standard --lang zh-CN

# 指定 AI 工具
forge init --tools claude,cursor
```

**三种模式对比：**

| 模式 | 技能 | 规格引擎 | 角色引擎 | 质量门控 | 适用场景 |
|:--|:--:|:--:|:--:|:--:|:--|
| `quick` | ✅ | ❌ | ❌ | ❌ | 小型项目 / 脚本 |
| `standard` | ✅ | ✅ | ❌ | TDD | 中型项目 / MVP |
| `full` | ✅ | ✅ | ✅ | TDD + Review + Security | 大型项目 / 企业级 |

### 4. 标准开发工作流

```bash
# 启动结构化开发向导
forge workflow start

# 1. 提议新功能
forge propose "add user authentication"

# 2. AI 助手完善 spec（编辑 .forge/specs/active/<id>/ 下的文件）

# 3. 追踪实施进度
forge apply

# 4. 归档完成的规格
forge archive
```

### 5. 记忆与知识沉淀

```bash
# 保存技术决策
forge memory save decision "使用 PostgreSQL，因为需要 JSONB 聚合查询"

# 搜索记忆
forge memory search "数据库"

# 列出所有记忆
forge memory list
```

### 6. 质量门控

```bash
# 本地安全扫描（AWS 密钥、JWT、硬编码密码）
forge security-scan

# 生成 AI 代码审查上下文
forge review

# 运行测试
forge test
```

### 7. 角色协作

```bash
# 分析师角色
forge agent analyst "分析竞品支付方案"

# 架构师角色
forge agent architect "设计支付模块架构"

# 开发者角色
forge agent developer "实现 Story-001"

# QA 角色
forge agent qa "审查支付模块代码"
```

---

## 📋 CLI 命令参考

| 命令 | 说明 |
|:--|:--|
| `forge init` | 初始化 Agent Forge 工作区 |
| `forge skill list` | 列出可用技能 |
| `forge skill add <name>` | 安装技能 |
| `forge skill remove <name>` | 移除技能 |
| `forge update` | 重新生成 AI 工具配置文件 |
| `forge config` | 查看/修改配置 |
| `forge memory save <type> <content>` | 保存记忆（decision/pattern/lesson） |
| `forge memory list [type]` | 列出记忆 |
| `forge memory search <keyword>` | 搜索记忆 |
| `forge memory delete <id>` | 删除记忆 |
| `forge propose <title>` | 创建规格提议 |
| `forge apply [spec-id]` | 检查规格进度 |
| `forge archive [spec-id]` | 归档规格 |
| `forge specs list` | 列出活跃规格 |
| `forge agent <role> [task]` | 角色任务分配 |
| `forge workflow start` | 启动工作流向导 |
| `forge test` | 运行 TDD 测试 |
| `forge review` | 生成审查上下文 |
| `forge security-scan` | 本地安全扫描 |
| `forge --lang zh-CN` | 切换语言 |

---

## 🗺️ 开发路线图

### Phase 1: 基础层 ✅ 已完成

- [x] pnpm monorepo + Turborepo 骨架
- [x] TypeScript 严格模式配置
- [x] Changesets 版本管理
- [x] `packages/i18n` 国际化模块
- [x] `packages/core` 核心引擎（Config/File/Logger/Memory/Template）
- [x] `packages/skills` 技能系统
- [x] `packages/adapters` AI 工具适配器（Claude/Cursor/Copilot）
- [x] `packages/cli` CLI 入口

### Phase 2: 规格层 ✅ 已完成

- [x] `packages/spec-engine` ProposeEngine / ApplyEngine / ArchiveEngine
- [x] `packages/core` MemoryManager（SQLite 持久记忆）
- [x] `forge propose` / `forge apply` / `forge archive` / `forge specs list`

### Phase 3: 治理层 ✅ 已完成

- [x] `packages/agent-engine` RoleManager + ContextBuilder
- [x] 4 个内置角色 Persona（analyst/architect/developer/qa）
- [x] `forge agent` / `forge workflow start`

### Phase 4: 质量层 ✅ 已完成

- [x] `packages/quality` TDDEnforcer / ReviewEngine / SecurityScanner
- [x] `forge test` / `forge review` / `forge security-scan`

### Phase 5: 工程化与生态 🚧 进行中

- [ ] ESLint 配置 + 测试覆盖（P0）
- [ ] CI/CD 流水线（P1）
- [ ] `forge verify` 命令（P1）
- [ ] Delta Tracking（P1）
- [ ] Skill Marketplace（P2）
- [ ] 项目模板系统（P2）
- [ ] VitePress 文档站（P2）
- [ ] 团队云同步（P3）

---

## 💼 业务场景

### 场景一：中型 Web 应用开发（3-4 人团队）

```bash
# 初始化
forge init --mode standard --lang zh-CN --tools claude,cursor

# 需求分析
forge agent analyst "分析用户认证和权限管理需求"

# 规格驱动
forge propose "user-auth-and-rbac"
# AI 完善 spec 后...
forge apply  # 追踪进度

# 开发与质量
forge agent developer "实现认证模块（TDD）"
forge security-scan
forge review

# 交付
forge archive
```

### 场景二：快速原型开发（独立开发者）

```bash
forge init --mode quick
forge skill add tdd
# 直接使用 AI 助手开发
```

### 场景三：企业级微服务（大团队）

```bash
forge init --mode full --lang zh-CN --tools claude,cursor,copilot

# 完整角色协作
forge workflow start
# Analyst → Architect → Developer → QA 全流程
```

---

## 🌍 国际化

Agent Forge 支持中英文双语，自动检测系统语言：

```bash
# 强制中文
forge init --lang zh-CN

# 强制英文
forge init --lang en
```

所有面向用户的字符串均通过 i18next 管理，可在 `packages/i18n/src/locales/` 扩展更多语言。

---

## 📝 License

[MIT](LICENSE)