# ai

**Repository Path**: idcu/ai

## Basic Information

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

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-06
- **Last Updated**: 2026-07-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# idcu-ai · 全场景 AI 开发提效框架

> 🚀 **让 AI 辅助开发更规范、更高效、更可控** — 142 个标准化 Skill + 自主 Agent 引擎 + MCP 协议，跨语言、跨框架、跨场景，开箱即用。

> 💡 **LLM 无关设计** — 核心功能不依赖大模型，接入 LLM 后更智能。不配置 API Key 也能用 80% 以上的功能。

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)
[![Skills: 142](https://img.shields.io/badge/Skills-142-green.svg)](#-skill-体系五层架构)
[![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-purple.svg)](./docs/MCP-QUICKSTART.md)
[![Quality: 4.8★](https://img.shields.io/badge/Quality-4.8%E2%98%85-yellow.svg)](./docs/SKILL_STANDARD.md)
[![Tests: 1400+](https://img.shields.io/badge/Tests-1400%2B-brightgreen.svg)](#-质量保障)

---

## ✨ 为什么选择 idcu-ai？

### 🎯 痛点 vs 解决方案

| 开发痛点 | idcu-ai 怎么解决 |
|---------|-----------------|
| AI 写代码没章法，每次都从零开始 prompt | **142 个标准化 Skill** — 每个场景都有最佳实践模板 |
| 不同项目风格不一致，代码质量参差不齐 | **规范前置** — Level 3 规范层统一代码风格、项目配置 |
| 复杂任务 AI 容易跑偏，做着做着就错了 | **分层 Workflow** — Level 4 工作流拆解复杂任务，步步为营 |
| 每次都要告诉 AI 项目用什么技术栈 | **项目配置 + 智能路由** — 自动识别框架，推荐最合适的 Skill |
| AI 工具散落在各处，切换成本高 | **MCP 统一接入** — 51 个 MCP 工具，Trae/Cursor/Claude 都能用 |
| 担心没有 API Key 就用不了 | **LLM 无关设计** — 核心功能不依赖大模型，没配置也能用 |

---

## 📌 前置说明：需要 API Key 吗？

**简单回答：不需要也能用，配置了更好用。**

idcu-ai 采用 **LLM 无关设计**，自身不内置大模型，但支持接入多种外部 LLM。

| 情况 | 能做什么 | 体验 |
|------|---------|------|
| **不配置 API Key** | Skill 管理、搜索、执行、MCP Server、项目配置、规则路由、启发式 plan 等 80%+ 功能 | ⭐⭐⭐ 能用，核心功能完整 |
| **配置 API Key** | 上面所有 + 智能路由 + LLM 增强的 plan + 完整 Agent 流程 + 代码生成 | ⭐⭐⭐⭐⭐ 体验最佳 |

**支持的 LLM Provider（7+ 种）：**
- OpenAI · Anthropic · DeepSeek · 通义千问 · 智谱 AI · Ollama（本地） · OpenAI 兼容

> 💡 **想先体验？直接往下看快速上手，不用配置 API Key 也能跑通大部分功能。**
>
> 想配置 API Key？查看 [快速上手指南 →](./docs/QUICKSTART.md#配置-llm-api-key-5-分钟)

---

## 🚀 3 分钟快速上手

### 第 1 步：安装（30 秒）

```bash
npm i -g idcu-ai
```

> 💡 源码开发？[查看贡献者安装指南](#-参与贡献)

### 第 2 步：在项目中初始化（1 分钟）

```bash
cd your-project
idcu init --force
```

这会生成 `.ai/config.json`，记录你的项目技术栈和偏好。

### 第 3 步：第一个 AI 开发任务（1.5 分钟）

```bash
# 让 AI 帮你给项目加 ESLint
idcu dispatch "给项目加上 eslint 配置"

# 或者启动交互式 Agent，做更复杂的事
idcu run "添加一个用户登录页面，带表单验证"
```

🎉 **完成！** 你已经体验了 idcu-ai 的核心能力。

> 📚 想深入学习？查看 [**30 分钟完全上手指南**](./docs/QUICKSTART.md)

---

## 💡 它能做什么？6 大典型场景

### 1. 🆕 功能开发
> 从需求到代码，一条龙搞定

```bash
idcu run "给 Todo 应用添加分类功能，支持按分类筛选"
```

**AI 会做什么：**
- ✅ 分析需求，识别需要改动的文件
- ✅ 生成详细开发计划（Plan）
- ✅ 逐步执行：类型定义 → 组件 → 样式 → 测试
- ✅ 自动生成测试用例

**适用 Skill**：[`feature-dev-flow`](./skills/level-4/workflow/feature-dev-flow) · [`business-coding`](./skills/level-2/business-coding) · [`create-plan`](./skills/level-1/create-plan)

---

### 2. 🐛 Bug 修复
> 快速定位，精准修复，附带测试

```bash
idcu run "修复登录页面在移动端布局错乱的问题"
```

**AI 会做什么：**
- ✅ 复现问题，定位根因
- ✅ 评估影响范围
- ✅ 修复代码 + 回归测试
- ✅ 记录修复过程，方便后续复盘

**适用 Skill**：[`bug-debug-flow`](./skills/level-4/workflow/bug-debug-flow) · [`code-refactoring`](./skills/level-2/code-refactoring)

---

### 3. 🧪 测试生成
> 一键补充单元测试，覆盖率蹭蹭涨

```bash
idcu dispatch "给 src/utils 目录下的所有函数加单元测试"
```

**AI 会做什么：**
- ✅ 分析函数逻辑和边界情况
- ✅ 生成 Jest/Vitest 测试用例
- ✅ 包含正常路径 + 异常路径 + 边界条件
- ✅ 遵循项目现有测试风格

**适用 Skill**：[`test-generation-flow`](./skills/level-4/workflow/test-generation-flow) · [`jest-testing`](./skills/level-2/test-generation/jest-testing) · [`vitest-testing`](./skills/level-2/test-generation/vitest-testing)

---

### 4. 🔄 代码重构
> 安全重构，不破坏现有功能

```bash
idcu run "把这个组件拆成更小的子组件，提高可维护性"
```

**AI 会做什么：**
- ✅ 分析代码结构和依赖关系
- ✅ 制定重构方案
- ✅ 逐步重构，每步都可验证
- ✅ 保持 API 兼容，附带重构说明

**适用 Skill**：[`code-refactoring-flow`](./skills/level-4/workflow/code-refactoring-flow) · [`code-refactoring`](./skills/level-2/code-refactoring)

---

### 5. 📝 文档写作
> 代码写完了？文档自动跟上

```bash
idcu dispatch "给这个项目写一份 README"
```

**AI 会做什么：**
- ✅ 分析项目结构和技术栈
- ✅ 生成标准 README 模板
- ✅ 包含：安装、使用、架构、开发指南
- ✅ 自动提取 API 接口信息

**适用 Skill**：[`documentation-flow`](./skills/level-4/workflow/documentation-flow) · [`documentation`](./skills/level-2/documentation)

---

### 6. 🚀 部署上线
> 从代码到生产，一键部署

```bash
idcu dispatch "把这个 Next.js 项目部署到 Vercel"
```

**AI 会做什么：**
- ✅ 检查项目配置
- ✅ 生成部署配置文件
- ✅ 环境变量配置指南
- ✅ 域名绑定 + CI/CD 配置

**适用 Skill**：[`vercel-deploy`](./skills/level-4/workflow/vercel-deploy) · [`netlify-deploy`](./skills/level-4/workflow/netlify-deploy) · [`custom-deploy`](./skills/level-4/workflow/custom-deploy)

---

> 💡 **更多场景**：代码审查、性能优化、安全审计、技术债管理、项目演进规划...
>
> 查看 [**使用场景大全**](./docs/USE_CASES.md)

---

## 🏗️ 核心特性

### 🧩 142 个标准化 Skill，5 层架构

```
                    ┌─────────────────────────┐
                    │   Level 5 工具链集成     │  与外部工具深度集成
                    │  git / ai-tools / ...   │
                    └───────────┬─────────────┘
                                │
                    ┌───────────▼─────────────┐
                    │   Level 4 Workflow      │  完整工作流，多步编排
                    │  feature-dev / bug-debug │
                    └───────────┬─────────────┘
                                │
                    ┌───────────▼─────────────┐
                    │  Level 3 规范与提示      │  统一标准，最佳实践
                    │  code-style / create-spec│
                    └───────────┬─────────────┘
                                │
                    ┌───────────▼─────────────┐
                    │   Level 2 场景能力       │  面向具体开发场景
                    │  react-component / ...  │
                    └───────────┬─────────────┘
                                │
                    ┌───────────▼─────────────┐
                    │   Level 1 原子能力       │  单一职责，可组合
                    │  file-read / create-plan │
                    └─────────────────────────┘
```

| 层级 | 数量 | 定位 | 代表 Skill |
|:----:|:----:|------|-----------|
| L1 原子能力 | 21 | 基础操作，单一职责 | `file-read` · `create-plan` · `code-stats` |
| L2 场景能力 | 71 | 具体场景解决方案 | `react-component` · `bug-debug` · `jest-testing` |
| L3 规范与提示 | 14 | 统一标准与最佳实践 | `eslint-config` · `create-spec` · `naming-conventions` |
| L4 Workflow | 21 | 完整工作流编排 | `feature-dev-flow` · `bug-debug-flow` · `code-refactoring-flow` |
| L5 工具链集成 | 15 | 外部工具/平台集成 | `git-workflow` · `ai-tools` · `project-setup` |

> 📖 查看完整 [**Skill 索引**](./docs/SKILLS_INDEX.md)

---

### 🤖 LLM 无关设计

**核心功能不依赖大模型，接入 LLM 后更智能。**

**无需 LLM 即可使用（80%+ 功能）：**
- Skill 管理（info / list / search / show / validate）
- Skill 直接执行（skill-exec / dispatch）
- MCP Server（51 个工具全部可用）
- 项目配置与智能推荐
- 基于规则的路由与启发式 plan
- 运行时统计与健康度监控
- 项目级 Lint 代码扫描与自动修复

**配置 LLM 后增强（体验更佳）：**
- 更智能的需求理解与任务路由
- 更贴合项目的个性化开发计划
- 完整的 Agent 自主执行流程
- LLM 辅助的代码生成与重构

**支持 7+ 种 LLM Provider：**
OpenAI · Anthropic · DeepSeek · 通义千问 · 智谱 AI · Ollama（本地） · OpenAI 兼容

> 💡 **降级策略**：没有配置 LLM 时，系统自动切换到规则/启发式模式，保证核心功能可用。

---

### 🤖 自主 Agent 引擎

**三大核心模块：**

```
用户需求
   │
   ▼
┌──────────┐     Plan     ┌──────────┐     Step     ┌──────────┐
│ Planner  │─────────────▶│  Engine  │─────────────▶│ Executor │
│ 规划器    │              │  执行引擎  │              │  执行者    │
└──────────┘              └─────┬─────┘              └─────┬─────┘
                                │                            │
                                │         失败重试            │
                                └────────────────────────────┘
                                          │
                                          ▼
                                   失败重规划 (replan)
```

- **Planner（规划器）**：分析需求 → 拆解步骤 → 生成可执行 Plan
- **Engine（执行引擎）**：逐步执行 → 状态管理 → 失败重试 → 智能重规划
- **Executor（执行者）**：调用具体 Skill → 执行原子操作

---

### 🔌 MCP 协议兼容

**51 个 MCP 工具，接入任意支持 MCP 的编辑器：**

| 类别 | 工具数量 | 代表工具 |
|------|:--------:|---------|
| Skill 管理 | 16 | `skill.search` · `skill.get` · `skill.routeByInput` · `skill.execute` · `skill.rules-list` · `skill.quality` |
| 运行时统计 | 4 | `runtime.stats` · `runtime.record` · `runtime.skillReport` · `runtime.healthDetail` |
| 文件操作 | 3 | `file.read` · `file.write` · `file.list` |
| 代码理解与编辑 | 9 | `code.summary` · `code.findDefinition` · `code.edit` · `code.diagnostics` · `code.formatCheck` |
| 对话管理 | 7 | `dialogue.start` · `dialogue.send` · `dialogue.history` · `dialogue.memory` · `dialogue.tokenInfo` |
| 项目信息 | 4 | `project.info` · `project.scan` · `project.validate` · `project.lint` |
| Git 操作 | 6 | `git.status` · `git.diff` · `git.log` · `git.commit` · `git.branch` · `git.authors` |
| 测试运行 | 1 | `test.run` |
| 命令执行 | 1 | `exec.run` |

> 📖 [**MCP 接入指南 →**](./docs/MCP-QUICKSTART.md)

---

### 🔄 运行时反馈闭环

```
使用 Skill → 评分反馈 → 推荐算法变准 → 更精准匹配 → 更多使用
     ▲                                                        │
     └────────────────────────────────────────────────────────┘
```

- 每次使用都在让系统更懂你
- 基于 TF-IDF + 上下文匹配 + 运行时健康度的智能推荐
- 越用越聪明，越用越顺手

---

### 🌐 跨语言跨框架

| 语言/框架 | 支持程度 | 相关 Skill |
|----------|:--------:|-----------|
| TypeScript / JavaScript | ⭐⭐⭐⭐⭐ | `typescript-setup` · `javascript-code-style` · `jest-testing` |
| React / Next.js | ⭐⭐⭐⭐⭐ | `react-component` · `nextjs-guide` · `tsx-development` |
| Vue / Nuxt | ⭐⭐⭐⭐ | `vue-component` · `nuxt-guide` |
| Python | ⭐⭐⭐⭐ | `python-fastapi-guide` · `python-django-guide` · `python-add-tests` |
| Node.js / Express | ⭐⭐⭐⭐ | `express-guide` · `nestjs-guide` · `fastify-guide` |
| Go / Rust | ⭐⭐⭐ | `go-code-style` · `rust-guide` |
| 数据库 | ⭐⭐⭐⭐ | `postgresql-guide` · `mongodb-guide` · `redis-guide` · `prisma-guide` |
| DevOps | ⭐⭐⭐⭐ | `vercel-deploy` · `netlify-deploy` · `docker-compose-guide` |

---

## 🛠️ 常用命令速查

| 命令 | 说明 | 示例 |
|------|------|------|
| `init [--force] [--lang ts]` | 项目初始化 | `idcu init --force` |
| `create-project --name <n>` | 一键脚手架 | `idcu create-project --name my-app --template react-ts-tailwind` |
| `info` | 项目信息 | `idcu info` |
| `search <keyword>` | 搜索 Skill | `idcu search react` |
| `show <name>` | Skill 详情 | `idcu show feature-dev-flow` |
| `list [--level N]` | 列出所有 Skill | `idcu list --level 4` |
| `plan <request...>` | 生成开发计划 | `idcu plan "添加用户登录功能"` |
| `run <request...>` | 启动 Agent（交互式） | `idcu run "修复登录页面样式 bug"` |
| `dispatch <request...>` | 自动路由执行 | `idcu dispatch "给项目加 eslint"` |
| `skill-exec <name> [k=v...]` | 直接执行 Skill | `idcu skill-exec create-file path=src/foo.ts` |
| `recommend [--limit N]` | 智能推荐 | `idcu recommend --limit 5` |
| `rate <skill> <rating>` | 为 Skill 评分 | `idcu rate feature-dev-flow 5 --success` |
| `stats` | 运行时统计 | `idcu stats` |
| `validate` | 验证所有 Skill | `idcu validate` |

> 💡 完整命令列表：`idcu --help`

---

## 📚 文档导航

### 🌱 新手入门

| 文档 | 阅读时间 | 适合人群 |
|------|---------|---------|
| [🚀 30 分钟快速上手指南](./docs/QUICKSTART.md) | 30 分钟 | 第一次接触的新手 |
| [📖 教程索引](./docs/TUTORIALS.md) | 按需 | 想系统学习的用户 |
| [❓ 常见问题 FAQ](./docs/FAQ.md) | 10 分钟 | 遇到问题的用户 |
| [💡 使用场景大全](./docs/USE_CASES.md) | 15 分钟 | 想了解能做什么的用户 |

### ⚡ 进阶使用

| 文档 | 阅读时间 | 适合人群 |
|------|---------|---------|
| [🔧 MCP 接入指南](./docs/MCP-QUICKSTART.md) | 25 分钟 | Trae/Cursor 用户 |
| [🏗️ 架构设计](./docs/ARCHITECTURE.md) | 40 分钟 | 高级用户 / 贡献者 |
| [⚔️ 竞品对比](./docs/COMPARISON.md) | 15 分钟 | 技术选型决策者 |

### 🏆 开发者指南

| 文档 | 阅读时间 | 适合人群 |
|------|---------|---------|
| [📏 Skill 开发规范](./docs/SKILL_STANDARD.md) | 35 分钟 | Skill 开发者 |
| [📝 示例编写规范](./docs/EXAMPLES_STANDARD.md) | 20 分钟 | 示例贡献者 |
| [🧪 Skill 质量评级标准](./docs/SKILL_AUDIT.md) | 25 分钟 | 质量把关者 |

---

## 📊 质量保障

我们对质量有着近乎苛刻的追求：

| 指标 | 当前值 | 说明 |
|------|:------:|------|
| **平均质量评分** | **96.6 / 100** | 6 维度综合评分 |
| **平均星级** | **4.8 ★** | 142 个 Skill 平均 |
| **5 星 Skill** | **138 个** | 占比 97% |
| **4 星以上** | **142 个** | 占比 100% |
| **测试用例** | **1541 个** | 全部通过 ✅ |
| **Skill 合规率** | **100%** | 142/142 全部通过 |
| **可执行 Skill** | **142 个** | 带 exec.ts 可直接执行 |
| **自带示例 Skill** | **135 个+** | 占比 95%+ |
| **TypeScript Strict** | **100% 通过** | 0 错误，strict 模式全面达标 |

> 🏆 **Top 5 五星 Skill**：`feature-dev-flow` (100分) · `netlify-deploy` (98.8分) · `ts-instrumentation-flow` (98.2分) · `code-refactoring-flow` (97.9分) · `project-evolution-flow` (97.9分)

---

## 🏗️ 项目结构

```
idcu-ai/
├── skills/                    # 142 个 Skill（Level 1-5）
│   ├── level-1/               # 原子能力（21个）
│   ├── level-2/               # 场景能力（71个）
│   ├── level-3/               # 规范与提示（14个）
│   ├── level-4/               # Workflow（21个）
│   └── level-5/               # 工具链集成（15个）
├── tools/                     # 核心工具链
│   ├── cli/                   # CLI 统一入口（10+ 子模块）
│   ├── agent/                 # Agent 执行引擎（planner + engine + tools）
│   ├── core/                  # Skill 加载 / 搜索 / 推荐 / 权限 / 执行
│   ├── llm/                   # LLM 适配器（7+ provider 支持）
│   ├── mcp/                   # MCP Server（stdio + HTTP 双模式）
│   ├── runtime/               # 运行时统计 / 健康度 / 审计日志
│   ├── analysis/              # 代码理解与分析（AST 解析）
│   ├── skill-mgmt/            # Skill 生命周期管理（9 个子领域）
│   │   ├── rules/             # 规则定义与评估器
│   │   ├── validation/        # 校验与依赖检查
│   │   ├── quality/           # 质量评级
│   │   ├── scaffold/          # 脚手架与版本管理
│   │   ├── registry/          # 注册中心
│   │   ├── market/            # 市场管理
│   │   ├── discovery/         # 搜索与发现
│   │   ├── testing/           # 测试框架
│   │   └── audit/             # 审计追踪
│   ├── lint/                  # 项目级 Lint（30 条规则 + auto-fix）
│   ├── code-ast/              # 代码 AST 解析（多后端）
│   ├── config/                # 项目配置管理
│   ├── templates/             # 模板引擎（多语言脚手架）
│   ├── reports/               # 报告生成
│   ├── ci/                    # CI/CD 集成
│   ├── vcs/                   # 版本控制集成
│   ├── auth/                  # 认证与授权
│   └── web-dashboard/         # Web 可视化面板
├── docs/                      # 文档
├── examples/                  # 示例项目
├── specs/                     # 架构规范
├── __tests__/                 # 测试套件（65+ 测试文件）
└── package.json
```

---

## 🤝 参与贡献

idcu-ai 是社区驱动的开源项目，欢迎各种形式的贡献！

### 🌟 最受欢迎：新增 Skill

有一个好用的工作流想分享？贡献一个 Skill 吧！

**4 步贡献你的第一个 Skill：**

```bash
# 1. 用脚手架创建 Skill 模板
npm run skill-scaffold create my-awesome-skill --level 2

# 2. 编写 meta.json + SKILL.md + examples
#    参考: docs/SKILL_STANDARD.md

# 3. 验证 Skill 是否符合规范
npm run validate:skill my-awesome-skill

# 4. 提交 Pull Request 🎉
```

**Skill 分层建议：**
- 💡 单一原子操作 → Level 1
- 🎯 具体场景方案 → Level 2
- 📏 规范/最佳实践 → Level 3
- ⚙️ 完整工作流 → Level 4
- 🔗 外部工具集成 → Level 5

### 🛠️ 其他贡献方式

| 贡献类型 | 说明 | 从哪里开始 |
|---------|------|-----------|
| 🐛 报告 Bug | 发现问题？提 Issue 告诉我们 | New Issue |
| 📝 改进文档 | 文档有错漏？帮我们完善 | `docs/` 目录 |
| 🔧 代码贡献 | 修复 Bug / 新增功能 | [ARCHITECTURE.md](./docs/ARCHITECTURE.md) |
| 💡 功能建议 | 有好想法？提出来讨论 | Discussion / Issue |
| ⭐ 推广分享 | 觉得好用？Star + 分享 | 每个 Star 都是鼓励 |

### 开发环境搭建

```bash
# 克隆项目
git clone <repo-url> idcu-ai
cd idcu-ai

# 安装依赖
npm install

# 链接到全局（方便本地测试）
npm link

# 运行测试
npm test
```

### 核心模块速查

- CLI 入口：[`tools/cli/index.ts`](./tools/cli/index.ts)
- Agent 引擎：[`tools/agent/engine.ts`](./tools/agent/engine.ts)
- Skill 加载器：[`tools/core/loader.ts`](./tools/core/loader.ts)
- MCP Server：[`tools/mcp/server.ts`](./tools/mcp/server.ts)
- Skill 目录：[`skills/`](./skills)

---

## 📄 License

MIT © idcu 团队

---

<div align="center">

**觉得好用？给个 Star ⭐ 支持一下**

[文档](./docs/QUICKSTART.md) · [示例](./examples) · [报告 Bug](../../issues) · [讨论](../../discussions)

</div>