# https://github.com/sifxprime/kodelyth-ecc 项目说明书
生成时间：2026-06-01 20:32:07 UTC
## 目录
- [首页 - Kodelyth ECC 概览](#home)
- [安装指南](#installation)
- [快速开始](#quickstart)
- [系统架构](#architecture)
- [意图路由系统](#intent-routing)
- [智能体索引](#agents-index)
- [Devil Mode - 红队对抗模式](#devil-mode)
- [代码审查类智能体](#code-review-agents)
- [构建与调试类智能体](#build-debug-agents)
- [安全与API类智能体](#security-agents)
## 首页 - Kodelyth ECC 概览
### 相关页面
相关主题：[安装指南](#installation), [系统架构](#architecture), [快速开始](#quickstart)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/sifxprime/kodelyth-ecc/blob/main/README.md)
- [KODELYTH.md](https://github.com/sifxprime/kodelyth-ecc/blob/main/KODELYTH.md)
- [SOUL.md](https://github.com/sifxprime/kodelyth-ecc/blob/main/SOUL.md)
- [package.json](https://github.com/sifxprime/kodelyth-ecc/blob/main/package.json)
- [commands/plan.md](https://github.com/sifxprime/kodelyth-ecc/blob/main/commands/plan.md)
- [commands/dashboard.md](https://github.com/sifxprime/kodelyth-ecc/blob/main/commands/dashboard.md)
- [commands/feature-dev.md](https://github.com/sifxprime/kodelyth-ecc/blob/main/commands/feature-dev.md)
- [commands/multi-workflow.md](https://github.com/sifxprime/kodelyth-ecc/blob/main/commands/multi-workflow.md)
- [commands/code-review.md](https://github.com/sifxprime/kodelyth-ecc/blob/main/commands/code-review.md)
- [commands/prp-prd.md](https://github.com/sifxprime/kodelyth-ecc/blob/main/commands/prp-prd.md)
# 首页 - Kodelyth ECC 概览
## 什么是 Kodelyth ECC
Kodelyth ECC（Enterprise Coding Companion，企业级编程助手）是一个生产级别的 AI 编程工具包，旨在为开发者提供全面的代码开发辅助能力。该工具包将人工智能深度集成到软件开发的全生命周期中，从需求分析、架构设计、编码实现到代码审查和文档维护，形成了一套完整的智能开发工作流。
根据 `package.json` 中的描述，Kodelyth ECC 具备以下核心特性：
- **70 个智能代理**：包含红队对抗性测试团队（devil-mode adversarial crew）在内的多种专业代理
- **194 项技能**：覆盖开发全流程的专业技能库
- **97 条命令**：丰富的命令行接口，支持各类开发任务
- **并行多代理命令**：支持多个 AI 代理同时协作处理复杂任务
- **语义意图路由**：智能理解用户意图并分发给最合适的代理处理
- **自学习记忆系统**：能够从开发过程中学习并积累项目特定知识
- **内置 MCP 服务器**：提供 16 个工具、6 个提示模板、377 个资源的完整 MCP 协议支持
资料来源：[package.json:1-15]()
## 系统架构
Kodelyth ECC 采用模块化架构设计，核心组件相互协作，共同支撑整个开发辅助系统。
```mermaid
graph TD
subgraph "前端交互层"
CLI[命令行接口]
Dashboard[可视化仪表盘]
end
subgraph "核心调度层"
Router[语义意图路由]
Memory[记忆系统]
MCP[MCP 服务器]
end
subgraph "代理执行层"
Agents[70个智能代理]
Skills[194项技能]
Bundle[代理捆绑包]
end
subgraph "工作流编排层"
Workflow[多模型协作]
Review[代码审查]
Plan[规划执行]
end
CLI --> Router
Dashboard --> Memory
Router --> Agents
Router --> Skills
Memory --> Agents
MCP --> Agents
Workflow --> Bundle
Review --> Bundle
Plan --> Bundle
Bundle --> Agents
```
### 核心模块说明
| 模块 | 功能描述 | 关键文件 |
|------|----------|----------|
| 命令行接口 | 提供 `/xxx` 格式的命令入口，解析用户指令 | `commands/*.md` |
| 语义路由 | 解析用户自然语言意图，智能匹配最合适的代理或技能 | 路由相关模块 |
| 记忆系统 | 捕获、索引和检索开发过程中的关键信息 | 记忆相关模块 |
| MCP 服务器 | 桥接到 Claude Desktop、LangGraph、AutoGen 等平台 | MCP 配置 |
| 多模型协作 | 协调 Codex（后端）、Gemini（前端）等多模型协同工作 | `multi-workflow.md` |
资料来源：[commands/plan.md:1-30]()
## 代理与技能体系
Kodelyth ECC 的核心能力建立在两套系统之上：专业代理（Agents）和领域技能（Skills）。
### 代理捆绑包
代理按照功能划分为不同的捆绑包（Bundle），方便用户根据需求启用：
| 捆绑包 | 用途 | 典型代理 |
|--------|------|----------|
| `indie-hacker` | 个人开发者基础辅助 | 代码生成、简单调试 |
| `red-team` | 安全审计与对抗性测试 | 提示注入猎手、密钥猎人 |
| `enterprise` | 企业级完整功能 | 全套代理与高级编排 |
资料来源：[actions/ecc-review/README.md:1-40]()
### 技能分类
技能按照开发阶段和能力类型进行分类，常见的技能类型包括：
- **开发类技能**：代码生成、重构、调试、测试
- **文档类技能**：文档生成、README 维护、API 文档
- **分析类技能**：代码审查、性能分析、安全扫描
- **协作类技能**：PRD 生成、规划制定、需求分析
资料来源：[commands/feature-dev.md:1-50]()
## 工作流系统
Kodelyth ECC 提供了多种预定义工作流，覆盖软件开发的不同场景和角色。
### 通用开发工作流
标准开发工作流包含六个阶段，每个阶段都有明确的目标和质量关卡：
```mermaid
graph LR
A[发现问题] --> B[需求分析]
B --> C[方案设计]
C --> D[编码实现]
D --> E[优化改进]
E --> F[质量审查]
F -->|通过| A
F -->|失败| D
```
| 阶段 | 描述 | 核心活动 |
|------|------|----------|
| 研究（Research） | 理解问题背景和现有方案 | 需求调研、技术可行性分析 |
| 创意（Ideation） | 生成解决方案候选 | 多方案设计、风险评估 |
| 规划（Plan） | 制定详细实现方案 | 架构设计、依赖规划 |
| 执行（Execute） | 编码实现功能 | 编写代码、单元测试 |
| 优化（Optimize） | 性能和安全改进 | 代码优化、安全审查 |
| 审查（Review） | 最终质量把关 | 集成测试、代码评审 |
资料来源：[commands/multi-workflow.md:1-60]()
### 后端开发工作流
后端开发采用 Codex 主导的工作模式：
```mermaid
graph TD
Backend[/后端任务] --> Research[研究阶段]
Research --> Ideation[Codex: 创意分析]
Ideation --> Plan[Codex: 架构规划]
Plan --> Execute[编码实现]
Execute --> Optimize[Codex: 优化审查]
Optimize --> Review[质量审查]
Gemini -->|参考意见| Ideation
Gemini -->|参考意见| Optimize
```
**协作规则**：
- Codex 的后端意见具有权威性，可信度高
- Gemini 的前端意见仅作参考
- Claude 负责编排、规划和最终交付
资料来源：[commands/multi-backend.md:1-70]()
### 前端开发工作流
前端开发采用 Gemini 主导的工作模式，流程与后端类似但角色职责互换：
| 模型 | 职责 | 信任级别 |
|------|------|----------|
| Gemini | UI/UX 设计、前端实现 | 权威（可信） |
| Codex | 后端逻辑、API 设计 | 参考意见 |
| Claude | 编排、规划、代码写入 | 协调者 |
资料来源：[commands/multi-frontend.md:1-60]()
## 命令系统
Kodelyth ECC 通过命令行提供丰富的功能入口，所有命令均以 `/` 开头。
### 常用命令一览
| 命令 | 功能 | 使用场景 |
|------|------|----------|
| `/plan` | 需求澄清与实现规划 | 开始新功能前 |
| `/feature` | 引导式功能开发 | 复杂功能实现 |
| `/prp` | 产品需求文档生成器 | 需求探索阶段 |
| `/prp-plan` | 完整实现规划 | 已有 PRD 后的规划 |
| `/code-review` | Pull Request 代码审查 | PR 审查流程 |
| `/backend` | 后端开发工作流 | API、算法、数据库任务 |
| `/frontend` | 前端开发工作流 | 组件、布局、动画任务 |
| `/workflow` | 多模型协作工作流 | 复杂跨栈任务 |
| `/dashboard` | 可视化监控仪表盘 | 系统状态查看 |
| `/verify-supply-chain` | 供应链安全验证 | 依赖审计、合规检查 |
| `/jira` | Jira 集成 | 任务跟踪、状态同步 |
| `/docs` | 文档快速查询 | 技术栈学习 |
| `/learn` | 从会话中提取模式 | 知识积累 |
资料来源：[commands/plan.md:1-30]()
### 规划命令详解
`/plan` 命令是 Kodelyth ECC 的核心命令之一，用于在动手编码前制定详细的实现计划：
**执行流程**：
1. **重述需求** - 澄清需要构建的功能
2. **识别风险** - 暴露潜在问题和阻碍
3. **创建步骤计划** - 将实现分解为阶段
4. **等待确认** - 必须获得用户确认后才能开始编码
**使用场景**：
- 开始新功能开发时
- 进行重大架构变更时
- 涉及多个文件或组件的复杂重构时
- 需求不明确或存在歧义时
资料来源：[commands/plan.md:1-60]()
### 仪表盘命令详解
`/dashboard` 命令启动本地监控仪表盘，提供系统运行状态的实时可视化：
```bash
/dashboard # 默认: 127.0.0.1:5747
/dashboard --port 8088 # 自定义端口
/dashboard --no-open # 不自动打开浏览器
/dashboard --host localhost # 显式指定本地绑定
```
**仪表盘内容**：
| 标签页 | 展示内容 |
|--------|----------|
| 概览 | 各资产数量、已捕获记忆、表面数量、路由未命中、待处理提案、 swarm 会话、token 预算快照 |
| 记忆 | BM25 搜索框 + 带标签的最近捕获 |
| 演进 | 高频复用记忆、未命中聚类、提案状态 |
| 目录 | 所有代理/技能/命令/规则的浏览器 |
| 会话 | Swarm/编排会话及每个 worker 的钻取视图 |
**安全规则**：
- 仅支持 GET 请求，无法修改任何状态
- 默认仅监听 localhost，不暴露到公网
- 不使用任何外部 CDN 资源
资料来源：[commands/dashboard.md:1-50]()
## 语义意图路由
Kodelyth ECC 的核心智能体现在其语义意图路由系统，能够理解用户的自然语言输入并将其分发给最合适的处理模块。
### 路由工作原理
```mermaid
graph TD
Input[用户自然语言输入] --> Parse[语义解析]
Parse --> Intent[意图识别]
Intent --> Match[技能/代理匹配]
Match --> Route[路由分发]
Route --> Execute[执行处理]
Execute --> Response[返回结果]
Match -.->|置信度阈值| Fallback[降级处理]
Fallback --> Ask[请求澄清]
```
### 路由能力
语义路由系统能够处理以下类型的输入：
- **模糊需求** - 用户描述不明确的功能需求
- **跨领域任务** - 需要多个技能协作的复合任务
- **上下文关联** - 基于当前会话历史理解用户意图
- **命令变体** - 同一命令的不同表达方式
资料来源：[package.json:1-20]()
## 记忆与自学习系统
Kodelyth ECC 内置了自学习记忆系统，能够从开发过程中不断积累项目特定知识。
### 记忆捕获流程
```mermaid
graph LR
Session[开发会话] --> Extract[模式提取]
Extract --> Validate[验证价值]
Validate -->|有价值| Save[保存到技能库]
Validate -->|无价值| Discard[丢弃]
Save --> Future[未来会话复用]
```
### 学习原则
- **关注可复用模式** - 提取能节省未来时间的通用模式
- **避免提取琐碎修复** - 如拼写错误、简单语法错误不提取
- **避免一次性事件** - 不提取特定 API 中断等临时性问题
- **保持技能专注** - 每个技能文件聚焦单一模式
学习到的技能保存在 `~/.claude/skills/learned/` 目录中。
资料来源：[commands/learn.md:1-30]()
## MCP 服务器集成
Kodelyth ECC 内置了完整的 MCP（Model Context Protocol）服务器，提供与外部平台的桥接能力。
### 支持的平台
| 平台 | 集成方式 | 用途 |
|------|----------|------|
| Claude Desktop | MCP 工具 | 桌面端 AI 助手集成 |
| LangGraph | MCP 工具/资源 | 工作流编排 |
| AutoGen | MCP 工具/资源 | 多代理协作 |
| CrewAI | MCP 工具/资源 | 代理团队管理 |
| OpenAI Agents SDK | MCP 工具/资源 | OpenAI 生态集成 |
### MCP 资源统计
| 资源类型 | 数量 |
|----------|------|
| 工具（Tools） | 16 |
| 提示模板（Prompts） | 6 |
| 资源（Resources） | 377 |
资料来源：[package.json:1-25]()
## 支持的 IDE 和工具
Kodelyth ECC 兼容多种主流 AI 编程工具和 IDE：
| 类别 | 工具列表 |
|------|----------|
| AI 编程助手 | Claude Code、Windsurf、Cursor、Codex、Antigravity、OpenCode、Cline、RooCode、Aider、Kimi、 Gemini CLI |
| AI 代理框架 | LangGraph、AutoGen、CrewAI、OpenAI Agents SDK |
这种广泛的兼容性确保了开发者在不同工作环境下都能使用 Kodelyth ECC 的能力。
资料来源：[package.json:10-20]()
## 代码审查与安全
Kodelyth ECC 包含专门的对抗性测试能力，用于识别代码中的安全问题和潜在风险。
### PR 审查 GitHub Action
`ecc-review` Action 提供了自动化的 PR 审查能力：
```yaml
name: Kodelyth ECC Review
on:
pull_request:
branches: [main, master]
jobs:
review:
runs-on: ubuntu-latest
steps:
- uses: sifxprime/kodelyth-ecc/actions/ecc-review@v1.7.3
with:
bundle: red-team
fail-on: critical
```
### 审查覆盖维度
| 维度 | 检查内容 |
|------|----------|
| 正确性 | 逻辑错误、边界情况、空指针处理、竞态条件 |
| 类型安全 | 类型不匹配、不安全转换、滥用 any、缺少泛型 |
| 模式合规 | 命名规范、文件结构、错误处理、导入顺序 |
| 安全性 | 注入漏洞、认证缺陷、密钥泄露、SSRF、路径遍历、XSS |
| 性能 | N+1 查询、缺失索引、无界循环、内存泄漏、大载荷 |
资料来源：[commands/code-review.md:1-50]()
## 供应链安全
Kodelyth ECC 提供了完整的供应链安全验证能力，确保依赖和交付物的完整性。
### 验证命令
```bash
/verify-supply-chain # 快速验证当前安装与交付清单
/verify-supply-chain --emit # 生成 SBOM + 清单
/verify-supply-chain --root /path/to/ecc --manifest /path/to/manifest.json
```
### 生成的工件
| 工件 | 用途 |
|------|------|
| SBOM（软件物料清单） | 依赖组件清单 |
| Content Manifest | 内容完整性清单 |
| SLSA Provenance | 供应链层级证明 |
资料来源：[commands/verify-supply-chain.md:1-50]()
## 项目类型检测
Kodelyth ECC 包含跨平台的项目类型检测能力，支持自动识别开发环境：
| 语言 | 标识文件 | 扩展名 |
|------|----------|--------|
| Python | requirements.txt, pyproject.toml, setup.py | .py |
| TypeScript | tsconfig.json | .ts, .tsx |
| JavaScript | package.json, jsconfig.json | .js, .jsx, .mjs |
| Go | go.mod, go.sum | .go |
| Rust | Cargo.toml, Cargo.lock | .rs |
| Ruby | Gemfile, Rakefile | .rb |
| Java | pom.xml, build.gradle | .java |
| C# | .csproj, *.sln | .cs |
资料来源：[scripts/lib/project-detect.js:1-50]()
## 快速入门
### 安装
```bash
# 使用 npm 安装
npm install -g kodelyth-ecc
# 或使用其他包管理器
yarn global add kodelyth-ecc
pnpm add -g kodelyth-ecc
```
### 基础使用
1. **查看帮助**
```bash
ecc --help
```
2. **启动仪表盘**
```bash
ecc dashboard
```
3. **开始功能规划**
```bash
ecc plan <功能描述>
```
4. **运行代码审查**
```bash
ecc code-review
```
## 总结
Kodelyth ECC 是一个功能全面的 AI 编程助手工具包，通过以下核心能力提升开发效率：
- **多代理协作**：70 个专业代理覆盖开发全流程
- **智能工作流**：预定义的六阶段开发流程确保质量
- **自学习系统**：从开发会话中积累项目知识
- **多平台集成**：支持主流 IDE 和 AI 代理框架
- **安全能力**：内置对抗性测试和供应链验证
版本 `1.8.1` 标志着该项目已具备生产级别的稳定性和功能完整性，适合企业和个人开发者使用。
---
## 安装指南
### 相关页面
相关主题：[首页 - Kodelyth ECC 概览](#home), [快速开始](#quickstart)
相关源码文件
以下源码文件用于生成本页说明：
- [install.sh](https://github.com/sifxprime/kodelyth-ecc/blob/main/install.sh)
- [install.ps1](https://github.com/sifxprime/kodelyth-ecc/blob/main/install.ps1)
- [GITHUB_SETUP.md](https://github.com/sifxprime/kodelyth-ecc/blob/main/GITHUB_SETUP.md)
- [scripts/lib/install-executor.js](https://github.com/sifxprime/kodelyth-ecc/blob/main/scripts/lib/install-executor.js)
- [scripts/lib/install-manifests.js](https://github.com/sifxprime/kodelyth-ecc/blob/main/scripts/lib/install-manifests.js)
# 安装指南
## 概述
kodelyth-ecc 提供了一套跨平台的安装系统，支持 Linux/macOS（Shell 脚本）和 Windows（PowerShell 脚本）两种安装方式。该安装系统设计用于自动化部署项目依赖、配置文件和环境设置，通过清单文件（manifest）管理安装组件的完整性校验。
**核心功能：**
- 跨平台支持（Linux、macOS、Windows）
- 模块化安装流程
- 安装清单校验与完整性验证
- 用户交互式确认机制
- 错误处理与回滚支持
---
## 系统要求
| 组件 | 最低版本要求 |
|------|-------------|
| Node.js | 18.x 或更高 |
| npm | 9.x 或更高 |
| Git | 2.x 或更高 |
| PowerShell（Windows） | 5.1 或更高 |
资料来源：[install.sh:1-20](https://github.com/sifxprime/kodelyth-ecc/blob/main/install.sh)
---
## 安装流程架构
### 流程图
```mermaid
graph TD
A[开始安装] --> B{检测平台}
B -->|Linux/macOS| C[执行 install.sh]
B -->|Windows| D[执行 install.ps1]
C --> E[加载安装清单]
D --> E
E --> F[验证前置条件]
F --> G{验证通过?}
G -->|否| H[显示错误并退出]
G -->|是| I[下载依赖]
I --> J[安装依赖包]
J --> K[配置环境]
K --> L[执行后安装脚本]
L --> M[安装完成]
```
---
## Linux/macOS 安装
### 使用方式
**方式一：交互式安装（推荐）**
```bash
curl -fsSL https://raw.githubusercontent.com/sifxprime/kodelyth-ecc/main/install.sh | bash
```
**方式二：静默安装（自动化部署）**
```bash
curl -fsSL https://raw.githubusercontent.com/sifxprime/kodelyth-ecc/main/install.sh | bash -s -- --silent
```
**方式三：本地脚本执行**
```bash
chmod +x install.sh
./install.sh
```
资料来源：[install.sh:25-50](https://github.com/sifxprime/kodelyth-ecc/blob/main/install.sh)
### 命令行参数
| 参数 | 说明 | 示例 |
|------|------|------|
| `--silent` | 静默模式，跳过用户确认 | `./install.sh --silent` |
| `--skip-checks` | 跳过环境检查 | `./install.sh --skip-checks` |
| `--help` | 显示帮助信息 | `./install.sh --help` |
---
## Windows 安装
### 使用方式
**使用 PowerShell（推荐）**
```powershell
irm https://raw.githubusercontent.com/sifxprime/kodelyth-ecc/main/install.ps1 | iex
```
**本地脚本执行**
```powershell
.\install.ps1
```
**使用特定参数**
```powershell
.\install.ps1 -Silent -SkipValidation
```
资料来源：[install.ps1:1-30](https://github.com/sifxprime/kodelyth-ecc/blob/main/install.ps1)
---
## 安装清单系统
### 清单文件结构
安装清单定义了每个组件的安装元数据：
```javascript
{
name: "组件名称",
version: "版本号",
files: ["文件列表"],
dependencies: ["依赖组件"],
scripts: {
preInstall: "安装前脚本",
postInstall: "安装后脚本"
}
}
```
资料来源：[scripts/lib/install-manifests.js:10-25](https://github.com/sifxprime/kodelyth-ecc/blob/main/scripts/lib/install-manifests.js)
### 清单验证
安装程序通过哈希校验确保清单完整性：
1. **加载清单文件** - 读取项目定义的 manifest.json
2. **计算校验和** - 对每个文件计算 SHA-256 哈希
3. **比对结果** - 验证本地文件与清单匹配
4. **报告差异** - 标识损坏或缺失的文件
```javascript
async function verifyManifest(manifest, targetDir) {
const results = {
valid: [],
modified: [],
missing: []
};
for (const file of manifest.files) {
const localHash = await calculateHash(path.join(targetDir, file));
const expectedHash = manifest.checksums[file];
if (localHash === expectedHash) {
results.valid.push(file);
} else if (!fileExists(path.join(targetDir, file))) {
results.missing.push(file);
} else {
results.modified.push(file);
}
}
return results;
}
```
资料来源：[scripts/lib/install-manifests.js:50-80](https://github.com/sifxprime/kodelyth-ecc/blob/main/scripts/lib/install-manifests.js)
---
## 安装执行器
### 核心模块
`install-executor.js` 负责实际的安装操作执行：
**主要职责：**
- 解析安装参数
- 管理安装状态机
- 执行安装任务
- 处理错误和回滚
```javascript
class InstallExecutor {
constructor(options = {}) {
this.options = options;
this.state = 'idle';
this.tasks = [];
}
async execute() {
this.transition('validating');
await this.validatePrerequisites();
this.transition('downloading');
await this.downloadDependencies();
this.transition('installing');
await this.installPackages();
this.transition('configuring');
await this.configureEnvironment();
this.transition('completed');
return { success: true };
}
}
```
资料来源：[scripts/lib/install-executor.js:15-50](https://github.com/sifxprime/kodelyth-ecc/blob/main/scripts/lib/install-executor.js)
### 状态机
```mermaid
stateDiagram-v2
[*] --> idle
idle --> validating: 开始执行
validating --> downloading: 前置验证通过
validating --> failed: 验证失败
downloading --> installing: 下载完成
downloading --> failed: 下载失败
installing --> configuring: 安装完成
installing --> failed: 安装失败
configuring --> completed: 配置完成
configuring --> failed: 配置失败
failed --> [*]
completed --> [*]
```
---
## GitHub 设置配置
### 快速设置
如需通过 GitHub 进行安装和配置：
```bash
# 克隆仓库
git clone https://github.com/sifxprime/kodelyth-ecc.git
# 进入目录
cd kodelyth-ecc
# 运行安装
./install.sh
```
资料来源：[GITHUB_SETUP.md:1-15](https://github.com/sifxprime/kodelyth-ecc/blob/main/GITHUB_SETUP.md)
### GitHub 认证配置
如需访问私有仓库或使用 GitHub CLI：
```bash
# 登录 GitHub CLI
gh auth login
# 验证认证状态
gh auth status
```
---
## 故障排除
### 常见问题
| 问题 | 解决方案 |
|------|----------|
| 权限拒绝 | 确保脚本有执行权限：`chmod +x install.sh` |
| Node.js 版本不兼容 | 使用 nvm 切换到支持的版本 |
| 网络连接失败 | 检查代理设置或使用国内镜像 |
| 清单校验失败 | 清除缓存后重试：`rm -rf ~/.cache/kodelyth-ecc` |
### 调试模式
启用详细输出以排查问题：
```bash
# Linux/macOS
DEBUG=* ./install.sh
# Windows
$env:DEBUG = "*"; .\install.ps1
```
---
## 环境变量
| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| `KODELETH_HOME` | 安装根目录 | `~/.kodelyth` |
| `KODELETH_CACHE` | 缓存目录 | `~/.cache/kodelyth` |
| `KODELETH_SKIP_UPDATE` | 跳过版本检查 | `false` |
| `INSTALL_SILENT` | 静默模式 | `false` |
---
## 相关资源
- **源码仓库**：[sifxprime/kodelyth-ecc](https://github.com/sifxprime/kodelyth-ecc)
- **问题反馈**：[提交 Issue](https://github.com/sifxprime/kodelyth-ecc/issues)
- **贡献指南**：查看 `CONTRIBUTING.md`
---
## 快速开始
### 相关页面
相关主题：[首页 - Kodelyth ECC 概览](#home), [安装指南](#installation)
相关源码文件
以下源码文件用于生成本页说明：
- [skills/kodelyth-quickstart/SKILL.md](https://github.com/sifxprime/kodelyth-ecc/blob/main/skills/kodelyth-quickstart/SKILL.md)
- [commands/loop-start.md](https://github.com/sifxprime/kodelyth-ecc/blob/main/commands/loop-start.md)
- [commands/onboard.md](https://github.com/sifxprime/kodelyth-ecc/blob/main/commands/onboard.md)
- [commands/feature-dev.md](https://github.com/sifxprime/kodelyth-ecc/blob/main/commands/feature-dev.md)
- [commands/prp-prd.md](https://github.com/sifxprime/kodelyth-ecc/blob/main/commands/prp-prd.md)
# 快速开始
欢迎使用 Kodelyth-ECC 智能开发系统。本页面将帮助您快速了解项目结构、核心工作流程以及如何高效启动开发任务。
## 系统概述
Kodelyth-ECC 是一个多模型协作的智能开发框架，通过整合 Codex（后端逻辑）、Gemini（前端UI/UX）和 Claude（编排协调）三个核心模型，实现端到端的自动化软件开发流程。
该系统采用 **Research → Ideation → Plan → Execute → Optimize → Review** 的六阶段工作流，每个阶段都有明确的质量门控和模型职责划分。
资料来源：[commands/multi-workflow.md:1-35]()
## 核心工作流程
### 快速启动命令：/loop-start
`/loop-start` 是系统的核心启动命令，用于初始化一个新的开发会话。该命令整合了需求分析和计划创建两个关键阶段。
```mermaid
graph TD
A[用户输入任务描述] --> B[/loop-start 解析需求]
B --> C{是否有PRD文件?}
C -->|是| D[解析PRD内容]
C -->|否| E[进入交互式需求收集]
D --> F[Phase 1: 需求分析]
E --> F
F --> G[Phase 2: 计划创建]
G --> H[用户确认计划]
H --> I[进入开发执行阶段]
style A fill:#e1f5fe
style I fill:#c8e6c9
```
资料来源：[commands/loop-start.md:1-50]()
### 交互式需求收集
当用户未提供明确的PRD文件时，系统会通过 `/prp-prd` 命令进行交互式需求收集：
1. **初始化阶段**：确认理解用户需求
2. **基础问题集**：收集问题背景、目标用户、核心痛点
3. **深入研究**：基于初始回答进行迭代式问题挖掘
4. **生成PRD文档**：整合所有收集的信息生成结构化PRD
资料来源：[commands/prp-prd.md:1-80]()
## 功能开发工作流
### /feature-dev 完整流程
对于复杂功能开发，推荐使用 `/feature-dev` 命令，它提供了更细粒度的阶段控制：
```mermaid
graph LR
A[Discovery 发现] --> B[Codebase Exploration 代码库探索]
B --> C[Clarifying Questions 澄清问题]
C --> D[Architecture Design 架构设计]
D --> E[Implementation 实现]
E --> F[Quality Review 质量审查]
F --> G[Summary 总结]
A -.->|七阶段流程| G
style A fill:#fff3e0
style G fill:#c8e6c9
```
| 阶段 | 关键活动 | 产出物 |
|------|---------|--------|
| Discovery | 理解功能需求 | 需求清单 |
| Codebase Exploration | 分析现有代码结构 | 代码架构图 |
| Clarifying Questions | 设计与边界问题确认 | 问题解答记录 |
| Architecture Design | 技术方案设计 | 实现蓝图 |
| Implementation | 代码编写 | 功能模块 |
| Quality Review | 代码审查 | 审查报告 |
| Summary | 结果汇总 | 文档更新 |
资料来源：[commands/feature-dev.md:1-60]()
## 新成员 onboarding
### /onboard 命令
`/onboard` 命令专为新团队成员设计，帮助快速熟悉项目环境：
```mermaid
graph TD
A[执行 /onboard] --> B[读取 CLAUDE.md]
B --> C[检查 CLAUDE.md]
C --> D{文件存在?}
D -->|是| E[继续引导流程]
D -->|否| F[提示手动阅读 README]
E --> G[展示项目架构]
F --> G
G --> H[介绍可用命令]
H --> I[开始第一个任务]
style A fill:#e1f5fe
style I fill:#c8e6c9
```
**Onboarding 检查清单：**
| 检查项 | 说明 | 状态 |
|--------|------|------|
| CLAUDE.md 存在 | 项目配置文件 | 必需 |
| 核心命令可用 | /feature-dev, /loop-start 等 | 必需 |
| 环境变量配置 | 参考 .env.example | 必需 |
| 代码规范文档 | 在 .claude/docs/ 目录 | 推荐 |
资料来源：[commands/onboard.md:1-40]()
## 命令速查表
| 命令 | 用途 | 适用场景 |
|------|------|---------|
| `/loop-start` | 快速启动开发会话 | 已有明确需求时 |
| `/feature-dev` | 完整功能开发流程 | 复杂功能开发 |
| `/prp-prd` | 交互式PRD生成 | 需求不明确时 |
| `/onboard` | 新成员引导 | 首次使用系统 |
| `/plan` | 实施方案规划 | 需要详细计划时 |
| `/backend` | 后端开发工作流 | API/算法开发 |
| `/frontend` | 前端开发工作流 | UI/组件开发 |
| `/workflow` | 多模型协作开发 | 全栈任务 |
资料来源：[commands/plan.md:1-30](), [commands/multi-backend.md:1-25](), [commands/multi-frontend.md:1-25]()
## 多模型协作架构
Kodelyth-ECC 采用智能路由策略，根据任务类型分配最佳模型：
```mermaid
graph TD
A[用户请求] --> B{任务类型判定}
B -->|后端任务| C[Codex 模型]
B -->|前端任务| D[Gemini 模型]
B -->|全栈/复杂| E[多模型协作]
C --> F[后端逻辑/算法]
D --> G[UI/UX 设计]
E --> H[Claude 编排协调]
F --> I[代码输出]
G --> I
H --> I
I --> J[Claude 写入文件系统]
style C fill:#bbdefb
style D fill:#f8bbd0
style E fill:#fff9c4
style J fill:#c8e6c9
```
**模型职责分工：**
| 模型 | 职责 | 信任级别 |
|------|------|---------|
| Codex | 后端逻辑、算法、调试 | **后端权威，可信** |
| Gemini | 前端UI/UX、视觉设计 | **前端权威，可信** |
| Claude | 编排、规划、执行、交付 | **文件系统唯一写入者** |
资料来源：[commands/multi-workflow.md:30-50]()
## 质量保障机制
### 阶段门控
每个工作流阶段都设有质量门控点：
1. **Research 阶段**：输出完整性和可行性评估（要求完整性评分 ≥7）
2. **Ideation 阶段**：至少提供2个候选方案供选择
3. **Plan 阶段**：用户必须明确确认后才能进入执行
4. **Execute 阶段**：严格遵循计划，确保错误处理和安全优化
5. **Optimize 阶段**：代码审查反馈整合
6. **Review 阶段**：完整性检查和测试验证
### 关键规则
- **外部模型零文件系统写入权限**：所有代码修改必须通过 Claude 执行
- **顺序执行模式**：默认情况下模型调用按顺序执行，避免阻塞
- **停止机制**：当前阶段输出未验证前，不进入下一阶段
资料来源：[commands/multi-plan.md:1-30](), [commands/multi-workflow.md:50-70]()
## 下一步
- 阅读 [项目架构文档](architecture.md) 深入了解系统设计
- 查看 [命令参考](../commands/README.md) 获取完整命令列表
- 了解 [贡献指南](../CONTRIBUTING.md) 开始参与开发
---
## 系统架构
### 相关页面
相关主题：[意图路由系统](#intent-routing)
相关源码文件
以下源码文件用于生成本页说明：
- [rules/common/agent-intent-routing.md](https://github.com/sifxprime/kodelyth-ecc/blob/main/rules/common/agent-intent-routing.md)
- [rules/common/agents.md](https://github.com/sifxprime/kodelyth-ecc/blob/main/rules/common/agents.md)
- [rules/common/memory-protocol.md](https://github.com/sifxprime/kodelyth-ecc/blob/main/rules/common/memory-protocol.md)
- [scripts/lib/orchestration-session.js](https://github.com/sifxprime/kodelyth-ecc/blob/main/scripts/lib/orchestration-session.js)
- [commands/multi-workflow.md](https://github.com/sifxprime/kodelyth-ecc/blob/main/commands/multi-workflow.md)
- [commands/multi-backend.md](https://github.com/sifxprime/kodelyth-ecc/blob/main/commands/multi-backend.md)
- [commands/multi-frontend.md](https://github.com/sifxprime/kodelyth-ecc/blob/main/commands/multi-frontend.md)
# 系统架构
## 概述
Kodelyth-ECC 是一个多模型协作开发系统，其架构设计围绕多智能体（Multi-Agent）编排和任务自动化展开。系统采用分层设计，将前端（Gemini）和后端（Codex）的开发职责解耦，通过中央协调器（Claude）实现工作流程的编排与管理。
系统的核心设计理念包括：
- **多模型协作**：Gemini 主导前端开发，Codex 主导后端开发
- **零文件系统写入权限**：外部模型仅有只读权限，所有代码写入由 Claude 完成
- **结构化工作流**：Research → Ideation → Plan → Execute → Optimize → Review 六阶段流程
- **质量门禁**：每个阶段设置验证点，确保交付质量
资料来源：[commands/multi-workflow.md:1-30]()
## 核心架构组件
### 1. 编排层（Orchestration Layer）
编排层是系统的中央控制单元，负责协调所有外部模型的工作时序和上下文传递。
| 组件 | 职责 | 技术实现 |
|------|------|----------|
| Claude Orchestrator | 整体流程控制、计划生成、代码交付 | 主线程执行 |
| Codex Backend Agent | 后端逻辑、算法实现、API 设计 | `scripts/lib/orchestration-session.js` |
| Gemini Frontend Agent | 前端 UI/UX、组件设计、响应式布局 | MCP 调用 |
| ace-tool MCP（可选） | 代码检索、Prompt 增强 | 外部服务集成 |
资料来源：[commands/multi-workflow.md:31-50]()
### 2. 代理系统（Agent System）
系统定义了标准化的代理结构和意图路由机制，确保各代理能够正确响应不同类型的任务请求。
#### 2.1 代理角色定义
```mermaid
graph TD
subgraph 代理层级
A[Claude Orchestrator] --> B[Codex Backend Agent]
A --> C[Gemini Frontend Agent]
B --> D[Backend Authority]
C --> E[Frontend Authority]
end
A --> F[零文件写入权限]
B --> G[可信后端意见]
C --> H[可信前端意见]
```
| 代理类型 | 信任级别 | 职责范围 |
|----------|----------|----------|
| Claude (自身) | 完全信任 | 编排、规划、执行、交付 |
| Codex | 完全信任 | 后端逻辑、算法、API |
| Gemini | 参考意见 | 前端视角分析 |
| ace-tool MCP | 可选 | 代码检索增强 |
资料来源：[commands/multi-backend.md:31-50]()
#### 2.2 意图路由机制
代理系统通过结构化的意图路由来分发任务：
```mermaid
graph TD
A[用户输入] --> B{意图识别}
B -->|后端任务| C[Codex Backend Agent]
B -->|前端任务| D[Gemini Frontend Agent]
B -->|全栈任务| E[多模型协作]
C --> F[Research]
C --> G[Ideation]
C --> H[Plan]
D --> I[Ideation]
D --> J[Plan]
E --> K[并行 Research]
E --> L[串行 Ideation]
E --> M[综合 Plan]
```
意图路由规则定义了不同代理的处理能力和优先级，确保任务被分配到最合适的处理单元。
资料来源：[rules/common/agent-intent-routing.md:1-30]()
### 3. 记忆协议层（Memory Protocol Layer）
记忆协议定义了代理间的上下文共享机制，确保多轮对话中信息的连续性和一致性。
#### 3.1 会话管理
```mermaid
graph LR
A[Session Start] --> B[创建 Session ID]
B --> C[保存到 GEMINI_SESSION]
B --> D[保存到 CODEX_SESSION]
C --> E[Resume Session]
D --> E
E --> F[上下文复用]
```
| 协议字段 | 类型 | 说明 |
|----------|------|------|
| `SESSION_ID` | 字符串 | 会话唯一标识符 |
| `GEMINI_SESSION` | 环境变量 | Gemini 会话复用 |
| `CODEX_SESSION` | 环境变量 | Codex 会话复用 |
会话通过 `resume ` 语法实现上下文复用，避免重复传递上下文信息。
资料来源：[rules/common/memory-protocol.md:1-25]()
### 4. 工作流引擎（Workflow Engine）
工作流引擎实现了结构化的六阶段开发流程，每个阶段都有明确的质量门禁。
#### 4.1 六阶段流程
```mermaid
graph TD
A[Phase 1: Research] --> B{质量验证}
B -->|通过| C[Phase 2: Ideation]
B -->|不通过| A
C --> D{方案选择}
D -->|方案1| E[Phase 3: Plan]
D -->|方案2| E
D -->|方案N| E
E --> F{计划审批}
F -->|批准| G[Phase 4: Execute]
F -->|拒绝| E
G --> H{实现检查}
H -->|通过| I[Phase 5: Optimize]
H -->|失败| G
I --> J{优化验证}
J -->|通过| K[Phase 6: Review]
J -->|必要| G
K --> L[交付完成]
```
| 阶段 | 主导代理 | 核心产物 | 质量门禁 |
|------|----------|----------|----------|
| Research | Claude | 需求分析、上下文收集 | 需求完整性评分 ≥ 7 |
| Ideation | Codex/Gemini | 技术方案（≥2个） | 方案可行性评估 |
| Plan | Codex/Gemini | 实现计划、文件结构 | 用户批准 |
| Execute | Claude | 代码实现 | 符合计划规范 |
| Optimize | Codex/Gemini | 优化建议 | 用户确认 |
| Review | Claude | 最终评估 | 测试通过 |
资料来源：[commands/multi-workflow.md:51-80]()
#### 4.2 执行模式
| 模式 | 标识 | 说明 | 适用场景 |
|------|------|------|----------|
| Ideation | `[Mode: Ideation]` | 方案分析与评估 | 需求探索阶段 |
| Plan | `[Mode: Plan]` | 架构设计与规划 | 实施前准备 |
| Execute | `[Mode: Execute]` | 代码开发 | 实现阶段 |
| Optimize | `[Mode: Optimize]` | 代码审查与优化 | 质量提升阶段 |
| Review | `[Mode: Review]` | 最终质量评估 | 交付前检查 |
资料来源：[commands/multi-backend.md:80-100]()
### 5. 脚本库（Script Library）
`scripts/lib/orchestration-session.js` 提供了会话编排的核心逻辑支持：
| 功能 | 说明 |
|------|------|
| 会话创建 | 初始化新的协作会话 |
| 会话恢复 | 通过 Session ID 恢复历史上下文 |
| 模型调用 | 封装 Codex/Gemini 的调用接口 |
| 上下文注入 | 将项目上下文和需求注入到模型 |
```javascript
// 核心调用模式
Bash({
command: "~/.claude/bin/codeagent-wrapper {{LITE_MODE_FLAG}}--backend - \"$PWD\" <<'EOF'\nROLE_FILE: \n\n...\n\nOUTPUT: \nEOF",
run_in_background: true,
timeout: 3600000,
description: "描述"
})
```
资料来源：[scripts/lib/orchestration-session.js:1-50]()
## 数据流架构
### 任务处理流
```mermaid
sequenceDiagram
participant User as 用户
participant Claude as Claude Orchestrator
participant Codex as Codex Backend
participant Gemini as Gemini Frontend
User->>Claude: 任务描述 ($ARGUMENTS)
Claude->>Claude: Phase 1: 上下文收集
Claude->>Codex: Research 请求 (run_in_background)
Claude->>Gemini: Research 请求 (run_in_background)
Codex-->>Claude: Research 结果
Gemini-->>Claude: Research 结果
Claude->>Claude: Phase 2: 需求完整性验证
Note over Claude: 完整性评分 ≥ 7?
Claude->>Codex: Ideation 请求 (resume session)
Codex-->>Claude: 方案列表 (≥2)
Claude->>User: 展示方案选项
User->>Claude: 方案选择
Claude->>Codex: Plan 请求
Codex-->>Claude: 实施计划
Claude->>User: 计划审批
User->>Claude: 批准/拒绝
alt 批准
Claude->>Claude: Phase 4: Execute
Claude->>Codex: Optimize 请求
Claude->>Gemini: Optimize 请求
Claude->>Claude: Phase 6: Review
Claude->>User: 交付报告
else 拒绝
Claude->>Codex: 修订计划请求
end
```
### 上下文传递模型
| 阶段 | 传递内容 | 接收方 |
|------|----------|--------|
| Research → Ideation | 项目上下文、需求分析 | Codex/Gemini |
| Ideation → Plan | 技术方案、可行性分析 | Claude 合成 |
| Plan → Execute | 批准的计划、文件结构 | Claude |
| Execute → Optimize | 代码变更、git diff | Codex/Gemini 审查 |
| Optimize → Review | 优化建议整合 | Claude 评估 |
## 安全与权限模型
```mermaid
graph TD
subgraph 权限层级
A[Claude Orchestrator] -->|完全控制| B[文件系统]
A -->|读写| C[配置管理]
A -->|执行| D[Git 操作]
end
subgraph 受限模型
E[Codex] -->|只读| B
E -->|禁止| F[文件系统写入]
G[Gemini] -->|只读| B
G -->|禁止| F
end
A --> H[交付协调]
E --> H
G --> H
```
| 实体 | 文件读取 | 文件写入 | 配置修改 | Git 操作 |
|------|----------|----------|----------|----------|
| Claude | ✓ | ✓ | ✓ | ✓ |
| Codex | ✓ | ✗ | ✗ | ✗ |
| Gemini | ✓ | ✗ | ✗ | ✗ |
资料来源：[commands/multi-workflow.md:61-70]()
## MCP 服务集成
系统支持可选的 MCP（Model Context Protocol）服务集成，用于扩展核心能力：
| 服务 | 用途 | 集成方式 |
|------|------|----------|
| ace-tool MCP | 代码检索、Prompt 增强 | 可选配置 |
| jira MCP | Jira 任务管理集成 | 环境变量或服务器配置 |
MCP 配置通过 `mcp-configs/mcp-servers.json` 模板进行管理。
资料来源：[commands/jira.md:1-30]()
## 部署架构
```mermaid
graph LR
A[用户终端] -->|命令行| B[Claude Code CLI]
B -->|工作流命令| C[本地工作目录]
C -->|API 调用| D[外部模型服务]
subgraph 外部服务
D --> E[Google Gemini API]
D --> F[Codex API]
end
C -->|可选| G[MCP 服务]
G -->|集成| D
```
## 总结
Kodelyth-ECC 的系统架构体现了现代多模型协作开发的最佳实践：
1. **职责分离**：前端与后端开发分别由专业模型负责
2. **质量门禁**：六阶段流程确保每个环节的输出质量
3. **安全优先**：外部模型仅有只读权限，代码交付由 Claude 统一控制
4. **会话复用**：通过结构化的会话管理提高上下文利用效率
5. **可扩展性**：支持 MCP 服务集成以扩展系统能力
该架构适用于中大型项目的结构化开发，特别适合需要前后端分离协作的场景。
---
## 意图路由系统
### 相关页面
相关主题：[系统架构](#architecture), [智能体索引](#agents-index)
相关源码文件
以下源码文件用于生成本页说明：
- [rules/common/agent-intent-routing.md](https://github.com/sifxprime/kodelyth-ecc/blob/main/rules/common/agent-intent-routing.md)
- [skills/intent-routing/SKILL.md](https://github.com/sifxprime/kodelyth-ecc/blob/main/skills/intent-routing/SKILL.md)
- [scripts/router/classify.js](https://github.com/sifxprime/kodelyth-ecc/blob/main/scripts/router/classify.js)
- [commands/multi-backend.md](https://github.com/sifxprime/kodelyth-ecc/blob/main/commands/multi-backend.md)
- [commands/multi-frontend.md](https://github.com/sifxprime/kodelyth-ecc/blob/main/commands/multi-frontend.md)
- [commands/multi-workflow.md](https://github.com/sifxprime/kodelyth-ecc/blob/main/commands/multi-workflow.md)
# 意图路由系统
意图路由系统（Intent Routing System）是 Kodelyth-ECC 项目中的核心组件，负责根据用户输入的意图类型，将任务智能分发到最适合处理的 AI 模型或工作流。该系统实现了多模型协作架构，支持后端（Codex）和前端（Gemini）任务的自动路由与编排。
## 系统概述
### 设计目标
意图路由系统旨在解决多模型协作环境下的任务分发问题。不同的 AI 模型在各自领域具有差异化优势：
| 模型类型 | 核心职责 | 信任级别 |
|----------|----------|----------|
| Codex | 后端逻辑、算法实现、调试 | **权威（可信赖）** |
| Gemini | 前端 UI/UX、视觉设计 | **权威（可信赖）** |
| Claude | 编排、规划、执行、交付 | 核心协调者 |
资料来源：[commands/multi-backend.md](https://github.com/sifxprime/kodelyth-ecc/blob/main/commands/multi-backend.md)
资料来源：[commands/multi-frontend.md](https://github.com/sifxprime/kodelyth-ecc/blob/main/commands/multi-frontend.md)
### 核心特性
- **智能分发**：根据任务特征自动选择最优处理模型
- **会话保持**：支持会话 ID 复用，确保多阶段任务上下文连贯
- **质量门控**：每阶段设置质量检查点，确保输出符合标准
- **零写权限**：外部模型无文件系统写入权限，保障代码安全
资料来源：[commands/multi-workflow.md](https://github.com/sifxprime/kodelyth-ecc/blob/main/commands/multi-workflow.md)
## 架构设计
### 系统组件
```mermaid
graph TD
A[用户请求] --> B[意图识别]
B --> C{意图类型判断}
C -->|后端任务| D[Codex 路由]
C -->|前端任务| E[Gemini 路由]
C -->|混合任务| F[多模型协作]
D --> G[后端工作流]
E --> H[前端工作流]
F --> I[编排协调器]
G --> J[实现阶段]
H --> J
I --> J
J --> K[优化审查]
K --> L[质量验收]
L --> M{通过?}
M -->|是| N[交付]
M -->|否| J
```
### 路由规则引擎
系统使用声明式规则文件定义路由策略，规则文件位于 `rules/common/agent-intent-routing.md`。
路由决策基于以下维度：
1. **任务域判定**：识别任务是后端、前端还是跨领域混合任务
2. **复杂度评估**：评估任务复杂度以选择合适的处理深度
3. **资源匹配**：根据当前系统负载和模型可用性进行分配
资料来源：[rules/common/agent-intent-routing.md](https://github.com/sifxprime/kodelyth-ecc/blob/main/rules/common/agent-intent-routing.md)
## 分类脚本
### classify.js 核心逻辑
分类脚本负责对用户输入进行意图识别和任务分类：
```javascript
// 资料来源: scripts/router/classify.js
// 核心分类逻辑伪代码
function classifyIntent(input) {
const keywords = extractKeywords(input);
const domain = determineDomain(keywords);
const complexity = assessComplexity(input);
return {
domain: domain, // 'backend' | 'frontend' | 'mixed'
complexity: complexity,
keywords: keywords,
recommendedModel: selectModel(domain)
};
}
```
### 分类维度
| 维度 | 取值 | 说明 |
|------|------|------|
| domain | backend/frontend/mixed | 任务所属领域 |
| complexity | low/medium/high | 任务复杂度评估 |
| keywords | string[] | 提取的关键词列表 |
| recommendedModel | codex/gemini/multi | 推荐的处理模型 |
资料来源：[scripts/router/classify.js](https://github.com/sifxprime/kodelyth-ecc/blob/main/scripts/router/classify.js)
## 工作流编排
### 六阶段工作流
意图路由系统采用结构化的六阶段开发流程：
| 阶段 | 模式 | 主导模型 | 核心职责 |
|------|------|----------|----------|
| 1. 研究 | Research | Claude | 需求理解、项目上下文分析 |
| 2. 构思 | Ideation | Codex/Gemini | 可行性分析、方案推荐 |
| 3. 规划 | Plan | Codex/Gemini | 架构设计、文件结构规划 |
| 4. 实现 | Execute | Claude | 代码编写、遵循计划 |
| 5. 优化 | Optimize | Codex/Gemini | 审查反馈、性能优化 |
| 6. 验收 | Review | Claude | 质量检查、测试验证 |
资料来源：[commands/multi-backend.md](https://github.com/sifxprime/kodelyth-ecc/blob/main/commands/multi-backend.md)
资料来源：[commands/multi-workflow.md](https://github.com/sifxprime/kodelyth-ecc/blob/main/commands/multi-workflow.md)
### 质量门控机制
```mermaid
graph LR
A[阶段输出] --> B{质量检查}
B -->|≥7分| C[下一阶段]
B -->|<7分| D[补充信息]
D --> A
C --> E{所有阶段完成?}
E -->|否| A
E -->|是| F[最终交付]
```
每个阶段设置质量阈值（默认 7/10 分），低于阈值必须补充信息后才能进入下一阶段。
### 会话管理
系统支持会话状态复用，通过 SESSION_ID 保持上下文连贯：
```bash
# 新会话调用
Bash({
command: "codeagent-wrapper --backend codex - \"$PWD\" <<'EOF'
ROLE_FILE: ~/.claude/.ccg/prompts/codex/analyzer.md
...
OUTPUT: ...
EOF",
run_in_background: false,
timeout: 3600000
})
# 复用会话调用
Bash({
command: "codeagent-wrapper --backend codex resume - \"$PWD\" <<'EOF'
...
EOF",
run_in_background: false,
timeout: 3600000
})
```
资料来源：[commands/multi-backend.md](https://github.com/sifxprime/kodelyth-ecc/blob/main/commands/multi-backend.md)
## 技能系统集成
### 意图路由技能模块
系统通过技能文件封装可复用的路由模式：
```markdown
# 意图路由技能
资料来源: skills/intent-routing/SKILL.md
## 触发条件
- 用户请求涉及多模型协作
- 需要根据任务类型选择处理路径
## 执行步骤
1. 调用 classify.js 进行意图识别
2. 解析分类结果
3. 选择对应工作流
4. 初始化会话
```
### 模式复用
系统支持通过 `/learn` 命令提取会话中发现的路由模式：
1. 分析当前会话的路由决策
2. 识别可复用的模式
3. 生成技能文件保存到 `~/.claude/skills/learned/`
4. 供后续会话参考使用
资料来源：[commands/learn.md](https://github.com/sifxprime/kodelyth-ecc/blob/main/commands/learn.md)
## 命令接口
### 多模型命令
| 命令 | 用途 | 主导模型 |
|------|------|----------|
| `/backend` | 后端任务开发 | Codex |
| `/frontend` | 前端任务开发 | Gemini |
| `/workflow` | 混合任务协作 | Codex + Gemini |
| `/multi-plan` | 多模型协同规划 | Codex + Gemini |
### 使用示例
```bash
# 后端任务
/backend 实现用户认证 API
# 前端任务
/frontend 设计登录页面组件
# 混合任务
/workflow 添加实时通知功能
```
资料来源：[commands/multi-backend.md](https://github.com/sifxprime/kodelyth-ecc/blob/main/commands/multi-backend.md)
资料来源：[commands/multi-frontend.md](https://github.com/sifxprime/kodelyth-ecc/blob/main/commands/multi-frontend.md)
资料来源：[commands/multi-workflow.md](https://github.com/sifxprime/kodelyth-ecc/blob/main/commands/multi-workflow.md)
## 安全机制
### 模型权限边界
| 模型 | 写权限 | 执行权限 |
|------|--------|----------|
| Codex | ❌ 无 | ✅ 可调用 |
| Gemini | ❌ 无 | ✅ 可调用 |
| Claude | ✅ 完全 | ✅ 完全 |
所有外部模型的输出必须经过 Claude 审核后才能写入文件系统，确保代码变更的安全性和一致性。
资料来源：[commands/multi-backend.md](https://github.com/sifxprime/kodelyth-ecc/blob/main/commands/multi-backend.md)
资料来源：[commands/multi-workflow.md](https://github.com/sifxprime/kodelyth-ecc/blob/main/commands/multi-workflow.md)
### 停止机制
系统实现了止损机制（Stop-Loss），当前阶段输出未经验证前，不会进入下一阶段，防止错误累积和放大。
资料来源：[commands/multi-plan.md](https://github.com/sifxprime/kodelyth-ecc/blob/main/commands/multi-plan.md)
## 最佳实践
1. **明确意图描述**：提供清晰的任务描述有助于准确路由
2. **利用会话复用**：多阶段任务应复用同一会话 ID
3. **关注质量评分**：低于阈值时及时补充信息
4. **提取可复用模式**：使用 `/learn` 保存有价值的路由经验
## 扩展阅读
- [后端开发工作流](commands/multi-backend.md)
- [前端开发工作流](commands/multi-frontend.md)
- [多模型协作框架](commands/multi-workflow.md)
- [技能创建指南](commands/skill-create.md)
---
## 智能体索引
### 相关页面
相关主题：[代码审查类智能体](#code-review-agents), [构建与调试类智能体](#build-debug-agents), [安全与API类智能体](#security-agents), [Devil Mode - 红队对抗模式](#devil-mode)
相关源码文件
以下源码文件用于生成本页说明：
- [agents/kodelyth-advisor.md](https://github.com/sifxprime/kodelyth-ecc/blob/main/agents/kodelyth-advisor.md)
- [agents/pair-programmer.md](https://github.com/sifxprime/kodelyth-ecc/blob/main/agents/pair-programmer.md)
- [agents/debug-detective.md](https://github.com/sifxprime/kodelyth-ecc/blob/main/agents/debug-detective.md)
- [agents/planner.md](https://github.com/sifxprime/kodelyth-ecc/blob/main/agents/planner.md)
- [wiki/Agent-Reference.md](https://github.com/sifxprime/kodelyth-ecc/blob/main/wiki/Agent-Reference.md)
# 智能体索引
本文档介绍 kodelyth-ecc 项目中的智能体（Agent）系统，包括各智能体的职责、能力边界、配置参数以及协同工作方式。
## 概述
kodelyth-ecc 采用多智能体协作架构，通过不同专业领域的智能体协同完成复杂的开发任务。系统中的每个智能体都具备特定的专业能力和明确的作用范围，类似于一个分工明确的开发团队。
智能体系统的核心设计理念是将复杂的软件工程任务分解为多个专业子任务，每个子任务由最适合的智能体处理。智能体之间通过标准化的接口进行通信和协作，实现从需求分析、代码规划、编码实现到调试优化的完整开发生命周期支持。
## 智能体架构总览
```mermaid
graph TD
User["用户请求"] --> Router["智能体路由"]
Router --> Advisor["kodelyth-advisor
战略顾问"]
Router --> Planner["planner
规划专家"]
Router --> PairProgrammer["pair-programmer
结对编程"]
Router --> DebugDetective["debug-detective
调试侦探"]
Advisor -->|提供建议| Planner
Planner -->|生成计划| PairProgrammer
PairProgrammer -->|发现错误| DebugDetective
DebugDetective -->|修复方案| PairProgrammer
```
## 智能体类型详解
### 1. 战略顾问（kodelyth-advisor）
战略顾问是智能体系统中的高级决策层，负责从宏观角度分析问题并提供战略性指导。
**核心职责**
战略顾问的主要职责包括对复杂技术问题进行深度分析，评估不同技术方案的优缺点，并为后续的规划和实现提供高层指导。战略顾问不仅关注技术可行性，还考虑业务价值、长期维护性以及与现有系统的兼容性。资料来源：[agents/kodelyth-advisor.md](https://github.com/sifxprime/kodelyth-ecc/blob/main/agents/kodelyth-advisor.md)
**能力特点**
该智能体具备广泛的技术知识储备，能够处理从架构设计到性能优化的各类战略性问题。它擅长识别潜在风险，提供预防性建议，并在多个可行方案中帮助做出最优选择。战略顾问的回答通常包含但不限于技术实现建议，还涵盖团队协作、开发流程改进等方面。
**使用场景**
- 面临技术选型决策时需要专业意见
- 需要评估现有架构的扩展性和局限性
- 寻求最佳实践和行业标准建议
- 进行复杂系统的可行性分析
### 2. 规划专家（planner）
规划专家是连接高层决策与具体实现的桥梁，负责将战略目标转化为可执行的详细计划。
**核心职责**
规划专家的核心职责是将复杂的开发任务分解为一系列可管理、可跟踪的子任务。它不仅生成任务列表，还确定任务之间的依赖关系，评估各任务的复杂度，并制定合理的执行顺序。资料来源：[agents/planner.md](https://github.com/sifxprime/kodelyth-ecc/blob/main/agents/planner.md)
**规划流程**
```mermaid
graph LR
A["需求理解"] --> B["任务分解"]
B --> C["依赖分析"]
C --> D["优先级排序"]
D --> E["计划输出"]
A -->|"原始需求"| A
B -->|"细化步骤"| B
C -->|"确定顺序"| C
D -->|"评估风险"| D
E -->|"执行指南"| E
```
**输出格式**
规划专家生成的计划通常包含以下组成部分：任务列表及其详细描述、每个任务的具体执行步骤、任务间的依赖关系、预计时间估算、以及验收标准。输出格式力求清晰明了，便于后续执行和跟踪。
**使用建议**
- 开发新功能前的系统化规划
- 重构项目的分阶段实施计划
- 复杂 bug 修复的逐步排查方案
- 团队任务分配和进度管理参考
### 3. 结对编程专家（pair-programmer）
结对编程专家是代码实现的核心执行者，专注于高质量代码的编写和项目文件的创建。
**核心职责**
结对编程专家负责根据规划专家提供的计划执行具体的代码实现任务。它能够创建和修改项目中的各类文件，包括但不限于源代码文件、配置文件、测试文件以及文档。资料来源：[agents/pair-programmer.md](https://github.com/sifxprime/kodelyth-ecc/blob/main/agents/pair-programmer.md)
**能力范围**
| 功能类别 | 具体能力 |
|---------|---------|
| 文件操作 | 创建、读取、修改、删除各类项目文件 |
| 代码生成 | 根据规范生成高质量源代码 |
| 测试编写 | 编写单元测试、集成测试和端到端测试 |
| 代码重构 | 优化现有代码结构和可读性 |
| 文档生成 | 生成和更新项目文档 |
**工作模式**
结对编程专家采用类似于人类程序员结对编程的工作方式。在执行任务时，它会先理解需求和上下文，然后编写代码，并通过适当的注释解释关键实现决策。这种方式不仅产生正确的代码，还确保代码的可维护性和可解释性。
### 4. 调试侦探（debug-detective）
调试侦探是专门处理问题诊断和修复的专家，擅长追踪复杂 bug 的根本原因并提供精确的修复方案。
**核心职责**
调试侦探的核心职责是系统性地分析程序错误，从症状追踪到根本原因。它不仅修复表面问题，更重要的是识别并解决导致问题的深层原因，防止问题再次发生。资料来源：[agents/debug-detective.md](https://github.com/sifxprime/kodelyth-ecc/blob/main/agents/debug-detective.md)
**诊断方法论**
```mermaid
graph TD
A["错误报告"] --> B["信息收集"]
B --> C["假设生成"]
C --> D["假设验证"]
D -->|验证通过| E["根因确定"]
D -->|验证失败| C
E --> F["修复方案"]
F --> G["验证修复"]
G -->|成功| H["问题关闭"]
G -->|失败| B
```
**调试策略**
调试侦探采用多层次的调试策略：首先收集完整的错误上下文信息，包括错误消息、堆栈跟踪、相关配置和运行环境信息；然后基于收集的信息生成可能的假设；接着通过代码审查、日志分析或实验验证来检验每个假设；最后在确定根本原因后制定精确的修复方案。
**输出内容**
调试侦探的输出通常包括：问题摘要、根本原因分析、详细的修复步骤、预防措施建议、以及相关的代码变更说明。输出内容既面向直接的问题解决，也包含知识性的解释，帮助理解问题的本质。
## 智能体协作流程
### 标准开发流程
```mermaid
sequenceDiagram
participant User as 用户
participant Advisor as 战略顾问
participant Planner as 规划专家
participant Coder as 结对编程专家
participant Debugger as 调试侦探
User->>Advisor: 提交复杂需求
Advisor-->>User: 提供战略建议
User->>Planner: 确认方案
Planner-->>User: 输出执行计划
User->>Coder: 确认计划
Coder->>Coder: 实现代码
Coder-->>User: 报告进展
alt 发现问题
Coder->>Debugger: 报告错误
Debugger->>Debugger: 诊断分析
Debugger-->>Coder: 修复方案
Coder->>Coder: 应用修复
end
Coder-->>User: 任务完成
```
### 迭代优化流程
在代码实现过程中，如果结对编程专家遇到难以解决的问题或发现设计层面的缺陷，系统支持在智能体之间进行迭代协作。这种迭代允许从代码层面回溯到规划层面，甚至进一步回溯到战略层面进行重新评估和调整。
## 智能体配置参考
### 配置参数表
| 参数名称 | 说明 | 可选值 | 默认值 |
|---------|------|--------|--------|
| temperature | 生成内容的随机性 | 0.0-1.0 | 0.7 |
| max_tokens | 最大输出长度 | 正整数 | 4096 |
| system_prompt | 自定义系统提示词 | 字符串 | 空 |
### 选择指南
不同的任务类型应选择不同的智能体组合。对于需要技术选型或架构决策的场景，首先咨询战略顾问；对于需要明确执行步骤的场景，使用规划专家；对于需要实际编码的场景，使用结对编程专家；对于调试和问题修复场景，直接使用调试侦探。
## 最佳实践
### 任务委托原则
为了获得最佳结果，建议遵循以下任务委托原则。首先，明确区分战略问题和战术问题——战略问题（如技术选型、架构设计）应咨询战略顾问，战术问题（如如何实现某个功能）应咨询规划专家。其次，对于模糊的需求，先与战略顾问讨论以明确方向，再进入规划和实现阶段。最后，对于复杂的调试任务，提供尽可能多的上下文信息给调试侦探，包括错误消息、相关代码段、近期变更等。
### 信息传递规范
在智能体之间传递信息时，保持信息的完整性和准确性至关重要。从战略顾问获取的建议应当准确传达给规划专家，规划专家的计划应当完整传递给结对编程专家，调试侦探的修复方案应当准确实施。每个环节的信息损耗都可能导致最终结果的偏差。
## 参考资源
关于智能体系统的更多详细信息，请参阅以下资源：详细的技术实现细节和接口规范可在 [Agent-Reference.md](https://github.com/sifxprime/kodelyth-ecc/blob/main/wiki/Agent-Reference.md) 中找到。各智能体的详细规范和配置选项可查阅对应目录下的文档文件。
---
## Devil Mode - 红队对抗模式
### 相关页面
相关主题：[智能体索引](#agents-index), [安全与API类智能体](#security-agents)
相关源码文件
以下源码文件用于生成本页说明：
- [agents/prompt-injection-hunter.md](https://github.com/sifxprime/kodelyth-ecc/blob/main/agents/prompt-injection-hunter.md)
- [agents/supply-chain-auditor.md](https://github.com/sifxprime/kodelyth-ecc/blob/main/agents/supply-chain-auditor.md)
- [agents/secret-hunter.md](https://github.com/sifxprime/kodelyth-ecc/blob/main/agents/secret-hunter.md)
- [agents/backdoor-hunter.md](https://github.com/sifxprime/kodelyth-ecc/blob/main/agents/backdoor-hunter.md)
- [agents/chaos-engineer.md](https://github.com/sifxprime/kodelyth-ecc/blob/main/agents/chaos-engineer.md)
- [commands/devil-mode.md](https://github.com/sifxprime/kodelyth-ecc/blob/main/commands/devil-mode.md)
# Devil Mode - 红队对抗模式
## 概述
Devil Mode（红队对抗模式）是 kodelyth-ecc 项目中的一种高级安全测试框架，旨在通过协调多个专业化安全代理来执行全面的红队渗透测试与对抗演练。该模式整合了提示词注入检测、供应链审计、密钥泄露扫描、后门检测以及混沌工程等多项安全能力，为开发团队提供系统化的安全评估解决方案。
Devil Mode 的核心设计理念是将复杂的安全测试任务分解为多个专项代理，每个代理负责特定类型的安全威胁检测与分析，最终通过统一的协调机制生成综合性的安全报告。
## 架构设计
### 多代理协同架构
Devil Mode 采用星型拓扑架构，以协调器（Orchestrator）为核心，连接多个专业化安全代理。各代理独立运行其专有的检测逻辑，检测结果通过标准化接口回传至协调器进行聚合分析。
```mermaid
graph TD
subgraph DevilMode["Devil Mode 协调层"]
O[协调器 Orchestrator]
end
subgraph Agents["专业化安全代理"]
PIH[提示词注入猎手
Prompt Injection Hunter]
SCA[供应链审计员
Supply Chain Auditor]
SH[密钥猎人
Secret Hunter]
BH[后门猎人
Backdoor Hunter]
CE[混沌工程师
Chaos Engineer]
end
subgraph Targets["目标系统"]
API[API 端点]
DEP[依赖项]
CODE[源代码]
CONFIG[配置文件]
end
O --> PIH
O --> SCA
O --> SH
O --> BH
O --> CE
PIH --> API
PIH --> CODE
SCA --> DEP
SCA --> CONFIG
SH --> CODE
SH --> CONFIG
BH --> CODE
BH --> API
CE --> API
CE --> DEP
style O fill:#ff6b6b,color:#fff
style PIH fill:#4ecdc4,color:#000
style SCA fill:#45b7d1,color:#000
style SH fill:#f9ca24,color:#000
style BH fill:#f0932b,color:#000
style CE fill:#eb4d4b,color:#fff
```
### 代理职责矩阵
| 代理名称 | 职责领域 | 检测对象 | 输出格式 |
|---------|---------|---------|---------|
| 提示词注入猎手 | 提示词安全 | 用户输入、API 请求 | 注入类型、风险等级、修复建议 |
| 供应链审计员 | 依赖安全 | 第三方库、容器镜像 | 漏洞列表、CVE 引用、版本建议 |
| 密钥猎人 | 凭证安全 | 源码、配置文件、环境变量 | 泄露类型、位置、严重程度 |
| 后门猎人 | 代码安全 | 源码、编译产物 | 后门类型、触发条件、影响范围 |
| 混沌工程师 | 韧性测试 | 系统组件、API 服务 | 故障场景、恢复能力、脆弱点 |
## 核心代理详解
### 提示词注入猎手（Prompt Injection Hunter）
提示词注入猎手专注于检测和防御针对大型语言模型应用的提示词注入攻击。该代理能够识别多种注入模式，包括指令注入、上下文逃逸、角色扮演劫持等典型攻击向量。
**检测能力**：
- 指令覆盖攻击检测
- 隐藏指令识别
- 上下文污染分析
- 多轮对话级联注入检测
代理通过静态分析和动态测试相结合的方式，对输入处理流程进行全面的安全评估。
### 供应链审计员（Supply Chain Auditor）
供应链审计员负责评估项目依赖项的安全性，包括直接依赖和传递依赖。该代理集成了漏洞数据库查询、许可证合规检查和依赖更新建议等核心功能。
**审计维度**：
- 已知漏洞检测（CVE 关联）
- 依赖版本健康度评估
- 许可证合规性分析
- 依赖来源可信度验证
### 密钥猎人（Secret Hunter）
密钥猎人是专门用于检测敏感信息泄露的专用代理。该代理采用多种检测策略，包括正则匹配、熵值分析和上下文感知检测，以发现代码库中潜在的安全凭证泄露。
**支持检测的密钥类型**：
- API 密钥（AWS、Azure、GCP 等云服务商）
- 私钥和证书
- 数据库连接字符串
- JWT 令牌
- 个人访问令牌（PAT）
- 加密盐值
### 后门猎人（Backdoor Hunter）
后门猎手专注于识别代码库中可能存在的后门程序和隐蔽入口点。该代理通过静态代码分析、行为模式识别和异常代码结构检测来发现潜在的安全威胁。
**检测范围**：
- 隐蔽代码执行路径
- 非授权的网络通信
- 异常的数据外泄行为
- 隐藏的管理接口
- 时间触发型恶意代码
### 混沌工程师（Chaos Engineer）
混沌工程师负责设计和执行系统韧性测试，通过引入受控的故障和压力条件来评估系统的容错能力和恢复机制。
**测试场景**：
- 服务降级测试
- 超时和重试机制验证
- 资源耗尽场景模拟
- 网络分区测试
- 依赖服务故障注入
## 工作流程
### 执行阶段划分
Devil Mode 的执行流程分为以下主要阶段：
```mermaid
graph LR
A[初始化阶段] --> B[侦察阶段]
B --> C[专项检测阶段]
C --> D[综合分析阶段]
D --> E[报告生成阶段]
C --> C1[提示词注入检测]
C --> C2[供应链审计]
C --> C3[密钥扫描]
C --> C4[后门检测]
C --> C5[混沌测试]
style A fill:#6c5ce7,color:#fff
style B fill:#a29bfe,color:#000
style C fill:#fd79a8,color:#000
style D fill:#fdcb6e,color:#000
style E fill:#00b894,color:#fff
```
### 各阶段详细说明
#### 初始化阶段
协调器加载配置文件，初始化各代理实例，建立与目标系统的连接通道。此阶段完成环境检查和依赖验证。
#### 侦察阶段
通过被动信息收集和主动探测，识别目标系统的攻击面。收集的信息包括：
- 公开端点和 API 路由
- 依赖项清单
- 配置文件结构
- 历史代码提交记录
#### 专项检测阶段
各代理根据其职责并行执行检测任务。检测结果通过统一的事件格式输出，便于后续聚合分析。
#### 综合分析阶段
协调器对各代理的检测结果进行交叉验证和优先级排序。同一漏洞若被多个代理同时检测到，将提升其可信度评级。
#### 报告生成阶段
生成结构化的安全评估报告，包含漏洞详情、风险评级、修复建议和参考链接。
## 配置与使用
### 基础调用方式
```bash
/devil-mode <测试目标描述>
```
Devil Mode 命令支持多种输入形式，包括直接描述、PRD 文件路径或参考文档路径。
### 配置参数
| 参数 | 类型 | 说明 | 默认值 |
|-----|------|-----|-------|
| `--scope` | string | 测试范围（full/partial/targeted） | full |
| `--severity-threshold` | string | 最低报告严重等级（critical/high/medium/low） | medium |
| `--parallel` | boolean | 是否并行执行各代理 | true |
| `--report-format` | string | 输出格式（json/markdown/html） | markdown |
## 安全报告格式
Devil Mode 生成的报告遵循标准化的安全评估格式，包含以下核心部分：
### 执行摘要
概述整体安全态势，提供关键发现的摘要统计。
### 漏洞详情
每个识别的漏洞包含：
- **漏洞 ID**：唯一标识符
- **严重程度**：Critical / High / Medium / Low / Info
- **类型分类**：所属的安全类别
- **受影响组件**：具体位置和范围
- **技术描述**：漏洞的技术细节
- **复现步骤**：验证漏洞的步骤
- **修复建议**：具体的修复方案
- **参考资料**：相关文档和修复指南链接
### 风险矩阵
按严重程度和影响范围组织的漏洞分布矩阵。
### 改进建议
针对整体安全架构的长期改进建议。
## 应用场景
Devil Mode 适用于以下典型场景：
| 场景 | 说明 | 推荐配置 |
|-----|------|---------|
| 部署前安全验收 | CI/CD 流程中的自动化安全检查 | `--scope targeted --severity-threshold high` |
| 定期安全审计 | 周期性的全面安全评估 | `--scope full --severity-threshold medium` |
| 渗透测试辅助 | 人工渗透测试前的自动化侦察 | `--scope full --parallel false` |
| 第三方代码审计 | 开源依赖和外包代码的安全审查 | `--scope partial --report-format json` |
## 最佳实践
### 执行时机
- **开发阶段**：在代码提交后、合并前执行快速检测
- **测试阶段**：集成测试中执行完整的安全测试套件
- **发布阶段**：发布前执行最终安全确认
### 结果处理
- 高危和严重漏洞必须修复后才能继续
- 中危漏洞应在当前迭代中处理或记录为技术债务
- 低危和信息级问题可纳入后续优化计划
### 持续改进
定期回顾检测结果，调整检测规则和阈值配置，以适应项目安全需求的演进。
## 相关命令
| 命令 | 功能 |
|-----|------|
| `/verify-supply-chain` | 供应链验证与 SBOM 生成 |
| `/code-review` | 代码审查工作流 |
| `/security-audit` | 综合安全审计 |
## 参考资料
- 项目主文档：`.claude/CLAUDE.md`
- 安全代理定义：`agents/` 目录下的各代理说明文件
- 命令集文档：`commands/` 目录
---
## 代码审查类智能体
### 相关页面
相关主题：[智能体索引](#agents-index), [安全与API类智能体](#security-agents)
相关源码文件
以下源码文件用于生成本页说明：
- 资料来源： [agents/code-reviewer.md](https://github.com/sifxprime/kodelyth-ecc/blob/main/agents/code-reviewer.md)
- 资料来源： [agents/typescript-reviewer.md](https://github.com/sifxprime/kodelyth-ecc/blob/main/agents/typescript-reviewer.md)
- 资料来源： [agents/python-reviewer.md](https://github.com/sifxprime/kodelyth-ecc/blob/main/agents/python-reviewer.md)
- 资料来源： [agents/go-reviewer.md](https://github.com/sifxprime/kodelyth-ecc/blob/main/agents/go-reviewer.md)
- 资料来源： [agents/rust-reviewer.md](https://github.com/sifxprime/kodelyth-ecc/blob/main/agents/rust-reviewer.md)
- 资料来源： [agents/cpp-reviewer.md](https://github.com/sifxprime/kodelyth-ecc/blob/main/agents/cpp-reviewer.md)
- 资料来源： [agents/flutter-reviewer.md](https://github.com/sifxprime/kodelyth-ecc/blob/main/agents/flutter-reviewer.md)
我需要先查看仓库中代码审查相关智能体的源代码文件，以准确生成技术文档。
---
## 构建与调试类智能体
### 相关页面
相关主题：[智能体索引](#agents-index), [代码审查类智能体](#code-review-agents)
相关源码文件
以下源码文件用于生成本页说明：
- [agents/build-error-resolver.md](https://github.com/sifxprime/kodelyth-ecc/blob/main/agents/build-error-resolver.md)
- [agents/debug-detective.md](https://github.com/sifxprime/kodelyth-ecc/blob/main/agents/debug-detective.md)
- [agents/silent-failure-hunter.md](https://github.com/sifxprime/kodelyth-ecc/blob/main/agents/silent-failure-hunter.md)
- [agents/flake-hunter.md](https://github.com/sifxprime/kodelyth-ecc/blob/main/agents/flake-hunter.md)
- [agents/env-debugger.md](https://github.com/sifxprime/kodelyth-ecc/blob/main/agents/env-debugger.md)
- [agents/dependency-doctor.md](https://github.com/sifxprime/kodelyth-ecc/blob/main/agents/dependency-doctor.md)
# 构建与调试类智能体
## 概述
构建与调试类智能体是 kodelyth-ecc 系统中专门负责软件构建过程问题诊断与修复的智能组件集合。该模块旨在自动化解决开发过程中常见的构建失败、依赖问题、环境配置错误以及间歇性测试失败等复杂问题。
这类智能体协同工作，形成了一个多层次的问题解决体系，涵盖了从编译错误解析到环境变量调试的完整工具链。通过多智能体协作架构，系统能够自动识别问题类型、定位根本原因并提供修复方案。
| 智能体名称 | 主要职责 | 问题域 |
|-----------|---------|--------|
| build-error-resolver | 构建错误解析与修复 | 编译错误、链接错误 |
| debug-detective | 深度调试与问题调查 | 运行时错误、逻辑缺陷 |
| silent-failure-hunter | 静默失败检测 | 未报告的错误、隐藏问题 |
| flake-hunter | 间歇性测试诊断 | 不稳定测试、竞态条件 |
| env-debugger | 环境配置调试 | 环境变量、路径问题 |
| dependency-doctor | 依赖问题诊断 | 包版本冲突、缺失依赖 |
## 系统架构
### 智能体协作架构
构建与调试类智能体采用星型拓扑架构，中心协调器负责任务分发，各专业智能体负责特定领域的问题处理。
```mermaid
graph TD
A[用户/系统请求] --> B[中心协调器]
B --> C[build-error-resolver]
B --> D[debug-detective]
B --> E[silent-failure-hunter]
B --> F[flake-hunter]
B --> G[env-debugger]
B --> H[dependency-doctor]
C --> I[问题解决]
D --> I
E --> I
F --> I
G --> I
H --> I
I --> J[修复报告/建议]
```
### 问题分类流程
```mermaid
graph TD
A[构建失败/错误报告] --> B{错误类型识别}
B -->|编译错误| C[build-error-resolver]
B -->|运行时错误| D[debug-detective]
B -->|无输出错误| E[silent-failure-hunter]
B -->|测试不稳定| F[flake-hunter]
B -->|环境问题| G[env-debugger]
B -->|依赖冲突| H[dependency-doctor]
C --> I[错误上下文提取]
D --> I
E --> I
F --> I
G --> I
H --> I
I --> J[根因分析]
J --> K[修复方案生成]
```
## 核心智能体详解
### 1. build-error-resolver（构建错误解析器）
**功能定位**：专注于解析和解决各种构建系统产生的错误信息。
**支持的问题类型**：
- 编译错误（语法错误、类型错误）
- 链接错误（未定义引用、符号冲突）
- 构建配置错误（Makefile、CMake 配置问题）
- 增量构建失败
**工作流程**：
```mermaid
graph LR
A[捕获构建输出] --> B[错误模式匹配]
B --> C[上下文提取]
C --> D[错误分类]
D --> E[解决方案检索]
E --> F[修复建议输出]
```
**关键能力**：
- 错误信息结构化解析
- 多构建系统支持（Make、CMake、ninja、bazel）
- 修复建议优先级排序
- 历史错误模式学习
资料来源：[agents/build-error-resolver.md:1-20]()
### 2. debug-detective（调试侦探）
**功能定位**：深入调查运行时错误和逻辑缺陷，提供详细的调试分析。
**适用场景**：
- 程序崩溃（段错误、断言失败）
- 内存问题（泄漏、越界）
- 性能异常（死锁、无限循环）
- 业务逻辑错误
**调试策略**：
| 策略类型 | 描述 | 适用场景 |
|---------|------|---------|
| 追踪调试 | 执行路径追踪 | 逻辑分支问题 |
| 状态检查 | 变量状态快照 | 数据异常 |
| 时间序列分析 | 操作时序重建 | 竞态条件 |
| 上下文关联 | 相关错误关联 | 复杂调用链 |
**输出格式**：
- 问题摘要报告
- 调用栈分析
- 相关代码片段
- 修复建议与示例
资料来源：[agents/debug-detective.md:1-25]()
### 3. silent-failure-hunter（静默失败猎人）
**功能定位**：检测那些没有明显错误提示但导致功能异常的问题。
**检测范围**：
- 返回值未检查的函数调用
- 异常被吞没的情况
- 超时或资源耗尽未正确处理
- 后台任务静默失败
**检测机制**：
```mermaid
graph TD
A[代码静态分析] --> B[可疑模式识别]
A --> C[运行时监控]
B --> D[风险评估]
C --> D
D --> E{风险等级}
E -->|高| F[立即报告]
E -->|中| G[累积报告]
E -->|低| H[日志记录]
```
**模式库**：
- 未检查的系统调用返回
- 空指针后续使用
- 文件操作无错误处理
- 网络请求忽略超时
资料来源：[agents/silent-failure-hunter.md:1-18]()
### 4. flake-hunter（间歇性测试猎手）
**功能定位**：诊断和分析不稳定的测试用例（flaky tests）。
**问题分类**：
| 类别 | 特征 | 常见原因 |
|-----|------|---------|
| 竞态条件 | 非确定性失败 | 并发访问共享资源 |
| 资源依赖 | 特定环境失败 | 端口占用、文件锁 |
| 时序敏感 | 与时间相关失败 | 超时设置不当 |
| 状态污染 | 测试顺序相关 | 全局状态未清理 |
**分析能力**：
- 测试执行历史分析
- 环境差异检测
- 并发执行模式识别
- 统计显著性评估
**输出**：
- 失败频率统计
- 根因概率排序
- 修复建议（测试重写、隔离方案）
资料来源：[agents/flake-hunter.md:1-22]()
### 5. env-debugger（环境调试器）
**功能定位**：诊断和解决环境配置相关问题。
**调试维度**：
- **系统环境变量**：PATH、LD_LIBRARY_PATH 等
- **语言运行时**：Python path、Node modules
- **构建工具链**：编译器版本、工具路径
- **依赖路径**：库搜索路径、头文件路径
**检测流程**：
```mermaid
graph TD
A[环境快照采集] --> B[预期配置比对]
B --> C{配置差异}
C -->|路径缺失| D[路径修复建议]
C -->|版本不匹配| E[版本对齐方案]
C -->|权限问题| F[权限修复指导]
C -->|冲突配置| G[冲突解析]
```
**常见问题诊断**：
| 问题类型 | 诊断特征 | 解决方案 |
|---------|---------|---------|
| 工具未找到 | command not found | 添加到 PATH |
| 库文件加载失败 | cannot open shared object | 设置 LD_LIBRARY_PATH |
| 版本冲突 | version mismatch | 版本降级/升级 |
| 权限拒绝 | permission denied | 修改文件权限 |
资料来源：[agents/env-debugger.md:1-20]()
### 6. dependency-doctor（依赖医生）
**功能定位**：诊断和解决依赖管理相关的问题。
**问题域**：
- 依赖版本冲突
- 缺失依赖检测
- 循环依赖识别
- 依赖安全漏洞
- 过时依赖提醒
**诊断能力**：
```mermaid
graph TD
A[依赖图解析] --> B[版本约束分析]
B --> C[冲突检测]
C --> D{冲突类型}
D -->|硬冲突| E[必须升级/降级]
D -->|软冲突| F[建议调整]
D -->|可选冲突| G[警告记录]
A --> H[安全扫描]
H --> I{漏洞发现}
I -->|高危| J[立即修复]
I -->|中危| K[计划修复]
I -->|低危| L[记录跟踪]
```
**支持的系统**：
- npm/yarn/pnpm（JavaScript）
- pip/poetry（Python）
- cargo（Rust）
- go mod（Go）
- Maven/Gradle（Java）
资料来源：[agents/dependency-doctor.md:1-24]()
## 协作工作流
### 典型问题解决流程
```mermaid
graph TD
A[构建失败报告] --> B[build-error-resolver]
B --> C{可解析?}
C -->|是| D[生成修复方案]
C -->|否| E[问题分类]
E --> F{分类结果}
F -->|环境问题| G[env-debugger]
F -->|依赖问题| H[dependency-doctor]
F -->|运行时问题| I[debug-detective]
F -->|测试问题| J[flake-hunter]
G --> K[协作分析]
H --> K
I --> K
J --> K
K --> L[综合诊断]
L --> M[修复建议输出]
D --> M
```
### 智能体间通信
智能体之间通过结构化消息进行通信，支持信息共享和协同分析。
| 消息类型 | 来源 | 目标 | 内容 |
|---------|------|------|------|
| 问题移交 | build-error-resolver | env-debugger | 环境相关错误上下文 |
| 上下文补充 | dependency-doctor | debug-detective | 依赖版本信息 |
| 根因共享 | debug-detective | silent-failure-hunter | 错误模式特征 |
| 反馈更新 | 任意智能体 | 协调器 | 分析结果与置信度 |
## 配置与使用
### 启用特定智能体
```yaml
# kodelyth-ecc 配置示例
agents:
build-debug:
enabled: true
# 按需启用特定智能体
targets:
- build-error-resolver
- env-debugger
- dependency-doctor
```
### 智能体优先级配置
| 优先级 | 智能体 | 说明 |
|-------|-------|------|
| 1（最高） | build-error-resolver | 构建错误优先处理 |
| 2 | env-debugger | 环境问题次之 |
| 3 | dependency-doctor | 依赖问题 |
| 4 | debug-detective | 深度调试 |
| 5 | silent-failure-hunter | 静默失败 |
| 6 | flake-hunter | 间歇性问题 |
### 输出格式配置
```json
{
"output": {
"format": "markdown",
"verbosity": "detailed",
"include_source": true,
"include_fix_example": true
}
}
```
## 最佳实践
### 问题报告规范
向构建与调试智能体提交问题时，建议包含以下信息：
1. **构建命令**：完整的构建命令和参数
2. **错误输出**：原始错误信息的完整输出
3. **环境信息**：操作系统版本、工具链版本
4. **复现步骤**：最小化复现问题的步骤
5. **预期行为**：期望的正确行为描述
### 修复方案验证
智能体提供的修复建议应按以下步骤验证：
| 步骤 | 操作 | 验证方法 |
|-----|------|---------|
| 1 | 备份当前状态 | 记录关键文件 |
| 2 | 应用修复 | 执行建议的修复 |
| 3 | 重新构建 | 验证构建成功 |
| 4 | 运行测试 | 确认测试通过 |
| 5 | 回滚（如需要） | 恢复备份 |
### 常见陷阱规避
- **过度依赖自动修复**：复杂问题需人工审核
- **忽视副作用**：修复可能引入新问题
- **版本敏感性**：修复方案可能与特定版本相关
- **环境差异**：不同环境的修复策略可能不同
## 扩展与集成
### 自定义智能体开发
如需添加新的调试智能体，需实现以下接口：
```python
class BaseDebugAgent:
def analyze(self, context: ProblemContext) -> AnalysisResult:
"""分析问题并返回结果"""
pass
def suggest_fix(self, analysis: AnalysisResult) -> FixSuggestion:
"""基于分析结果生成修复建议"""
pass
def can_handle(self, problem: Problem) -> float:
"""评估本智能体处理该问题的能力（0-1）"""
pass
```
### 与 CI/CD 集成
构建与调试智能体可集成到持续集成流程中：
```yaml
# CI 配置示例
stages:
- build
- test
- debug # 失败时触发
debug_job:
script:
- kodelyth-debug --agent build-error-resolver
- kodelyth-debug --agent env-debugger
rules:
- if: '$CI_JOB_STATUS == "failed"'
```
## 总结
构建与调试类智能体构成了 kodelyth-ecc 中处理软件构建和运行时问题的核心能力。通过六个专业智能体的协同工作，系统能够自动化诊断常见的构建错误、环境问题、依赖冲突和间歇性测试失败。
这些智能体不仅能够独立解决问题，还支持智能体间的协作分析，通过信息共享和上下文传递提供更准确的诊断结果。在实际使用中，建议根据具体问题类型选择合适的智能体，并结合人工审核确保修复方案的正确性。
---
## 安全与API类智能体
### 相关页面
相关主题：[智能体索引](#agents-index), [Devil Mode - 红队对抗模式](#devil-mode)
相关源码文件
以下源码文件用于生成本页说明：
- [agents/security-reviewer.md](https://github.com/sifxprime/kodelyth-ecc/blob/main/agents/security-reviewer.md)
- [agents/api-guardian.md](https://github.com/sifxprime/kodelyth-ecc/blob/main/agents/api-guardian.md)
- [agents/supply-chain-auditor.md](https://github.com/sifxprime/kodelyth-ecc/blob/main/agents/supply-chain-auditor.md)
- [agents/secret-hunter.md](https://github.com/sifxprime/kodelyth-ecc/blob/main/agents/secret-hunter.md)
# 安全与API类智能体
## 概述
在现代软件开发中，安全性和API管理是保障系统健壮性的关键环节。Kodelyth ECC框架提供了专门的安全与API类智能体套件，用于自动化安全审查、API防护、供应链审计和敏感信息检测。这些智能体协同工作，形成多层次的安全防护体系，涵盖代码安全审计、API合规性检查、依赖项安全性验证以及敏感数据保护等方面。
安全与API类智能体的设计理念是将安全检查流程自动化，使开发团队能够在CI/CD流水线中集成安全验证，同时确保API的设计符合最佳实践。通过这些智能体的协同工作，项目可以在早期发现潜在的安全风险，降低系统上线后的安全事件发生概率。
---
## 智能体分类架构
Kodelyth ECC的安全与API类智能体包含四个核心组件，每个组件专注于特定的安全领域：
| 智能体名称 | 主要职责 | 核心功能 |
|-----------|---------|---------|
| Security Reviewer | 代码安全审查 | 漏洞检测、安全模式分析、风险评估 |
| API Guardian | API设计与合规 | 端点验证、参数校验、响应规范 |
| Supply Chain Auditor | 供应链安全 | 依赖检查、版本审计、许可证合规 |
| Secret Hunter | 敏感信息检测 | 密钥扫描、凭证检测、配置泄露防护 |
这些智能体可以独立运行，也可以组合使用以提供全面的安全覆盖。
---
## Security Reviewer（安全审查智能体）
### 功能定位
Security Reviewer是Kodelyth ECC中的核心安全审查智能体，负责对代码变更进行深度安全分析。它能够识别常见的安全漏洞模式，包括但不限于注入攻击、身份认证绕过、数据泄露等安全风险。该智能体在代码审查流程中扮演关键角色，帮助开发者在代码合并前发现潜在的安全问题。
### 审查范围
Security Reviewer的审查范围涵盖多个安全领域，包括输入验证、身份认证与授权、加密与密钥管理、错误处理、日志记录以及会话管理等。在进行审查时，智能体会根据代码的编程语言和框架特性，应用相应的安全最佳实践检查规则。
### 输出格式
智能体生成的审查报告包含风险等级评估（严重、高危、中危、低危）、具体漏洞位置和建议修复方案。审查结果可直接集成到代码审查工作流程中，为审查者提供可操作的安全反馈。
> 资料来源：[agents/security-reviewer.md](https://github.com/sifxprime/kodelyth-ecc/blob/main/agents/security-reviewer.md)
---
## API Guardian（API守护智能体）
### 功能定位
API Guardian专注于API设计和实现的安全性审查，确保API端点符合安全标准和最佳实践。它验证API的参数校验逻辑、响应格式、错误处理机制以及认证授权流程的合规性。该智能体特别适用于RESTful API和GraphQL接口的安全评估。
### 审查维度
API Guardian从以下维度对API进行审查：
```mermaid
graph TD
A[API Guardian审查] --> B[端点安全]
A --> C[参数验证]
A --> D[认证授权]
A --> E[响应安全]
A --> F[速率限制]
B --> B1[HTTP方法正确性]
B --> B2[路径规范]
B --> B3[CORS配置]
C --> C1[类型校验]
C --> C2[边界检查]
C --> C3[注入防护]
D --> D1[Token验证]
D --> D2[权限级别]
D --> D3[会话管理]
E --> E1[敏感数据脱敏]
E --> E2[状态码规范]
E --> E3[缓存控制]
F --> F1[请求配额]
F --> F2[限流策略]
F --> F3[防滥用机制]
```
### 安全检查项
| 检查类别 | 具体项目 | 检查标准 |
|---------|---------|---------|
| 输入验证 | 请求参数 | 必需参数存在性、类型正确性、长度限制 |
| 认证机制 | Bearer Token | Token格式验证、过期检查、签名验证 |
| 授权控制 | 权限级别 | 最小权限原则、角色分离验证 |
| 数据保护 | 敏感字段 | PII数据脱敏、加密存储验证 |
| 错误处理 | 异常响应 | 堆栈跟踪隐藏、敏感路径泄露检查 |
### 输出规范
API Guardian生成的报告包含API端点清单、发现的安全问题、修复优先级建议以及符合OWASP API安全指南的合规性评分。报告支持JSON和Markdown两种格式，便于集成到自动化工作流程中。
> 资料来源：[agents/api-guardian.md](https://github.com/sifxprime/kodelyth-ecc/blob/main/agents/api-guardian.md)
---
## Supply Chain Auditor（供应链审计智能体）
### 功能定位
Supply Chain Auditor负责审计项目依赖项的安全性，确保第三方库和组件符合供应链安全标准。在现代软件开发中，供应链攻击已成为重要的威胁向量，该智能体通过系统性检查帮助项目识别和缓解此类风险。
### 审计流程
```mermaid
graph LR
A[依赖清单解析] --> B[漏洞数据库查询]
B --> C[许可证合规检查]
C --> D[版本生命周期评估]
D --> E[综合风险评分]
A1[package.json] --> A
A2[requirements.txt] --> A
A3[go.mod] --> A
A4[Cargo.toml] --> A
```
### 审计维度
| 审计维度 | 检查内容 | 风险等级 |
|---------|---------|---------|
| 已知漏洞 | CVE数据库匹配 | 严重 |
| 恶意包 | 供应链投毒检测 | 严重 |
| 过期依赖 | 维护状态检查 | 中危 |
| 许可证冲突 | 法律合规性 | 中危 |
| 依赖漂移 | 版本锁定验证 | 低危 |
### 报告结构
审计报告包含依赖项树状图谱、漏洞详情（包括CVSS评分）、建议升级版本以及替代包推荐。对于高危漏洞，报告提供详细的利用场景说明和临时缓解措施建议。
> 资料来源：[agents/supply-chain-auditor.md](https://github.com/sifxprime/kodelyth-ecc/blob/main/agents/supply-chain-auditor.md)
---
## Secret Hunter（密钥猎手智能体）
### 功能定位
Secret Hunter专门用于检测代码仓库中意外泄露的敏感信息，包括API密钥、密码、令牌、私钥、连接字符串等。它通过模式匹配和熵值分析相结合的方式，在代码提交前或CI/CD流水线中识别潜在的敏感信息泄露。
### 检测能力
Secret Hunter支持检测多种类型的敏感凭证：
| 凭证类型 | 检测模式 | 示例格式 |
|---------|---------|---------|
| API密钥 | 特定服务前缀+随机字符串 | `sk_live_xxxxx`、`AKIAxxxxx` |
| 私钥 | PEM/SSH密钥格式 | `-----BEGIN RSA PRIVATE KEY-----` |
| 连接字符串 | URL或分号分隔格式 | `Server=host;Database=db;` |
| JWT令牌 | 标准JWT格式 | `eyJhbGciOiJIUzI1NiIs...` |
| 云凭证 | 云服务商特定格式 | `aws_access_key_id=` |
### 工作原理
```mermaid
graph TD
A[扫描目标] --> B[多模式匹配引擎]
B --> C{熵值分析}
C -->|高熵字符串| D[高置信度告警]
C -->|低熵字符串| E[上下文验证]
E --> F{是否误报}
F -->|是| G[白名单放行]
F -->|否| H[告警记录]
D --> I[安全报告生成]
H --> I
G --> I
```
### 配置选项
| 配置项 | 默认值 | 说明 |
|-------|-------|------|
| `scan_branch` | 当前分支 | 扫描的Git分支范围 |
| `excluded_paths` | node_modules, dist | 排除扫描的目录 |
| `entropy_threshold` | 4.5 | 字符串熵值检测阈值 |
| `custom_patterns` | 空数组 | 用户自定义检测模式 |
| `whitelist_file` | .secretsWhitelist | 白名单配置文件的路径 |
### 输出与集成
Secret Hunter的扫描结果包含泄露位置（文件路径和行号）、检测到的凭证类型、置信度评分以及建议的补救措施。扫描结果可以导出为多种格式，包括SARIF（用于GitHub Advanced Security集成）、JSON和纯文本报告。
> 资料来源：[agents/secret-hunter.md](https://github.com/sifxprime/kodelyth-ecc/blob/main/agents/secret-hunter.md)
---
## 智能体协同工作流程
安全与API类智能体可以组成完整的安全防护链条，在软件开发生命周期的不同阶段发挥作用：
```mermaid
graph LR
A[代码编写] --> B[Secret Hunter
预提交检查]
B --> C{检测到泄露?}
C -->|是| D[阻止提交]
C -->|否| E[代码推送]
E --> F[PR创建]
F --> G[Security Reviewer
自动审查]
G --> H{发现安全问题?}
H -->|是| I[阻止合并]
H -->|否| J[API Guardian
接口审查]
J --> K{API合规?}
K -->|是| L[Merge]
K -->|否| I
L --> M[Supply Chain Auditor
部署前审计]
M --> N[发布/部署]
```
### 各阶段集成点
| 阶段 | 集成智能体 | 触发条件 | 失败处理 |
|-----|-----------|---------|---------|
| 预提交 | Secret Hunter | Git Hook (pre-commit) | 拒绝提交 |
| PR审查 | Security Reviewer | PR创建/更新 | 阻止合并 |
| API变更 | API Guardian | API相关文件变更 | 阻止合并 |
| 部署前 | Supply Chain Auditor | 部署流水线 | 暂停部署 |
---
## 安全检查严重性等级
所有安全智能体使用统一的严重性分级系统，以便于风险评估和优先级处理：
| 严重等级 | 标识 | 说明 | 建议处理时间 |
|---------|-----|------|------------|
| 严重 (Critical) | 🔴 CRITICAL | 可直接利用的严重漏洞，可能导致系统完全沦陷 | 立即处理 |
| 高危 (High) | 🟠 HIGH | 可导致数据泄露或权限提升的漏洞 | 24小时内 |
| 中危 (Medium) | 🟡 MEDIUM | 存在潜在风险但需要特定条件才能利用 | 1周内 |
| 低危 (Low) | 🔵 LOW | 最佳实践偏离，影响较小 | 下一迭代 |
---
## 最佳实践建议
### 集成到CI/CD流水线
建议将安全智能体集成到持续集成/持续部署流水线中，确保每次代码变更都经过安全检查。具体配置可根据项目需求调整扫描范围和严重性阈值。
### 定期全面扫描
除了增量扫描外，建议定期执行全量代码库的安全扫描，以发现可能被增量检查遗漏的潜在风险。
### 告警分级处理
建立明确的安全告警处理流程，对不同严重性等级的问题设置不同的响应时间和处理要求。严重和高危问题应自动阻止代码合并或部署。
### 白名单管理
对于已确认安全的误报情况，应将其添加到相应的白名单配置中，避免重复告警导致的安全疲劳。
---
## 总结
Kodelyth ECC的安全与API类智能体套件提供了从代码编写到部署的全方位安全保障。通过Security Reviewer、API Guardian、Supply Chain Auditor和Secret Hunter四个智能体的协同工作，开发团队可以系统性地识别和缓解安全风险，确保应用程序的安全性、API的合规性以及敏感信息的保护。这些智能体的自动化能力显著降低了人工安全审查的负担，同时提高了安全检查的一致性和覆盖率。
---
---
## Doramagic 踩坑日志
项目：sifxprime/kodelyth-ecc
摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。
## 1. 配置坑 · 可能修改宿主 AI 配置
- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。
- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。
- 证据：capability.host_targets | github_repo:1214171652 | https://github.com/sifxprime/kodelyth-ecc | host_targets=mcp_host, claude, claude_code, cursor
## 2. 能力坑 · 能力判断依赖假设
- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 建议检查：将假设转成下游验证清单。
- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
- 证据：capability.assumptions | github_repo:1214171652 | https://github.com/sifxprime/kodelyth-ecc | README/documentation is current enough for a first validation pass.
## 3. 维护坑 · 维护活跃度未知
- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
- 证据：evidence.maintainer_signals | github_repo:1214171652 | https://github.com/sifxprime/kodelyth-ecc | last_activity_observed missing
## 4. 安全/权限坑 · 下游验证发现风险项
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：下游已经要求复核，不能在页面中弱化。
- 建议检查：进入安全/权限治理复核队列。
- 防护动作：下游风险存在时必须保持 review/recommendation 降级。
- 证据：downstream_validation.risk_items | github_repo:1214171652 | https://github.com/sifxprime/kodelyth-ecc | no_demo; severity=medium
## 5. 安全/权限坑 · 存在评分风险
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 建议检查：把风险写入边界卡，并确认是否需要人工复核。
- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
- 证据：risks.scoring_risks | github_repo:1214171652 | https://github.com/sifxprime/kodelyth-ecc | no_demo; severity=medium
## 6. 维护坑 · issue/PR 响应质量未知
- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
- 防护动作：issue/PR 响应未知时，必须提示维护风险。
- 证据：evidence.maintainer_signals | github_repo:1214171652 | https://github.com/sifxprime/kodelyth-ecc | issue_or_pr_quality=unknown
## 7. 维护坑 · 发布节奏不明确
- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
- 证据：evidence.maintainer_signals | github_repo:1214171652 | https://github.com/sifxprime/kodelyth-ecc | release_recency=unknown