aistack (Blackms)

Aistack

Claude代码的超现代多代理编排

](https://www.npmjs.com/package/@blackms/aistack)     ](https://nodejs.org)

生产级代理编排，具有对抗性验证、持久内存和实时web仪表板。

快速开始 · 它的作用 · 特性 · 文档

11 agents · 46 MCP tools · 6 LLM providers · SQLite + FTS5 · Web dashboard · Agent Identity · Drift Detection · Consensus Checkpoints · Resource Monitoring

______________________________________________________________________

它的作用

aistack助您一臂之力 协调多个专门的人工智能代理 共同完成复杂的任务。把它想象成一个人工智能专家团队：

你可以：

• 产卵a 编码员 编写代码的代理
• 产卵 对抗的 代理人审查并打破它
• 产卵a 测试员 编写测试的代理
• 产卵a 文档 代理人记录它
• 将学习内容存储在 持久内存 以备后用

它是如何工作的：

1. Spawn专业代理商 -每个代理都有特定的专业知识（编码、测试、审查等）
2. 它们通过信息总线进行通信 -代理可以协调和共享信息
3. 内存在会话中持续存在 -代理记住模式、决策和学习
4. 对抗性验证 -通过迭代反馈自动审查和改进代码
5. 与Claude Code集成 -通过MCP协议直接从IDE使用代理

非常适合：

• 具有自动审查周期的代码生成
• 多步骤开发工作流程（设计→ code → test → 文件）
• 建立跨项目持续存在的机构知识
• 自动化需要不同类型专业知识的复杂任务

示例工作流程

You ask: "Create a login API endpoint with tests"

aistack:
1. Spawns a Coder agent → writes the API code
2. Spawns an Adversarial agent → tries to break it, finds security issues
3. Coder fixes the issues
4. Spawns a Tester agent → writes comprehensive tests
5. Spawns a Documentation agent → generates API docs
6. Stores patterns in memory → "Always use bcrypt for passwords"

Next time: The memory helps agents make better decisions automatically

______________________________________________________________________

技术栈

Node.js 20+

TypeScript

SQLite + FTS5

Vitest

React 18

Material-UI

Vite

Anthropic

OpenAI

Ollama

GitHub Actions

NPM Package

______________________________________________________________________

✨ 特性

🤖 11种专业代理类型

每个代理都有特定的专业知识和能力：

• 编码员 -编写、编辑和重构代码
• 研究员 -搜索和分析代码库，收集信息
• 测试员 -编写和运行测试、覆盖率分析
• 审稿人 -代码审查和最佳实践
• 对抗的 -用于查找漏洞的攻击代码（用于审查循环）
• 建筑师 -系统设计和技术决策
• 协调员 -为复杂任务编排多个代理
• 分析师 -数据分析和性能分析
• 开发运维 -部署、基础设施、监控
• 文档 -生成和维护文档
• 安全审计员 -安全审计、合规性、威胁建模

💾 持久存储系统

跨会话生存的知识：

• 带FTS5的SQLite -在所有内存中快速进行全文搜索
• 矢量嵌入 -可选语义搜索（OpenAI/Ollama）
• 命名空间和标签 -按项目、主题或团队组织记忆
• 版本历史 -跟踪更改并在需要时回滚
• 记忆关系 -将相关概念联系在一起

🔄 对抗性评论循环

通过迭代反馈自动改进代码：

1. Coder代理生成代码
2. 对手代理评论并试图打破它
3. Coder修复问题
4. 重复最多3次，直至获得批准

结果：代码更健壮、更安全，错误更少。

🪪 代理身份v1

具有生命周期管理的持久代理身份：

• 稳定的UUID -代理商具有持久性 agent_id 跨处决
• 生命周期状态 - created → active → dormant → retired
• 能力跟踪 -存储和版本代理功能
• 完整审计跟踪 -每次身份更改都会被记录下来
• 代理作用域内存 -特定代理拥有的内存命名空间

🎯 语义漂移检测

检测任务描述在语义上何时与祖先相似：

• 基于嵌入的相似性 -使用OpenAI或Ollama嵌入
• 可配置阈值 - threshold （阻止/警告）和 warningThreshold （仅警告）
• 两种行为 - warn （记录并允许）或 prevent （块创建）
• 任务关系 -轨道 parent_of, derived_from, depends_on, supersedes
• 指标和事件 -漂移检测分析的全记录

🛡️ 资源消耗监测

检测并防止失控代理消耗过多资源：

• 每个代理跟踪 -跟踪访问的文件、API调用、派生的子任务、消耗的令牌
• 阶段进展 - normal → warning → intervention → termination
• 可配置阈值 -为每种资源类型设置限制
• 暂停/恢复控制 -自动暂停超过阈值的代理
• 可交付检查点 -当代理产生结果时重置基于时间的跟踪
• Slack通知 -警告、干预和终止警报

🤝 共识检查点

在高风险任务生成子任务之前需要验证：

• 基于风险的门控 -配置哪些风险级别（高、中、低）需要达成共识
• 审稿人策略 -从中选择 adversarial, different-model，或 human 审稿人
• 可配置风险评估 -定义高/中风险代理类型和关键字模式
• 任务深度跟踪 -通过以下方式防止无限任务递归 maxDepth 限制
• 检查点生命周期 - pending → approved/rejected/expired 有审计追踪
• 超时和自动过期 -检查点在可配置超时后过期

🎯 46个用于Claude代码的MCP工具

直接从Claude Code IDE控制堆栈：

• 6个代理工具（生成、列表、停止、状态、类型、更新）
• 8个身份识别工具（创建、获取、列出、更新、激活、停用、退役、审计）
• 5个内存工具（存储、搜索、获取、列表、删除）——具有代理范围的内存支持
• 13个任务工具（创建、分配、完成、列表、获取、check_drift、获取关系、漂流记、+5个共识工具）
• 4个会话工具（开始、结束、状态、活动）
• 3个系统工具（状态、运行状况、配置）
• 7个GitHub工具（问题、PR、仓库信息）

🌐 Web仪表板

实时监控：

• 可视化代理管理
• 带搜索功能的内存浏览器
• 任务队列可视化
• 实时WebSocket更新
• React 18+材质用户界面
• 暗模式支持

🔌 6名法学硕士提供者

选择您喜欢的AI：

• Anthropic -克劳德·十四行诗4（推荐）
• 开放人工智能 -GPT-4o+嵌入
• 奥拉玛 -本地模型（骆驼3.2）
• ClaudeCode命令行界面 -直接集成Claude代码
• Gemini CLI -谷歌双子座2.0
• 法典 -GitHub Codex

🔐 安全与认证

生产就绪安全：

• JWT身份验证
• BCrypt密码散列
• 基于角色的访问控制（管理员、开发人员、查看器）
• 代码审查的安全审计员代理

📢 Slack集成

实时通知您的团队：

• 代理事件 -生成、停止、错误
• 工作流更新 -开始、完成、失败
• 审查循环进度 -迭代更新
• 资源警报 -警告、干预、终止
• 可定制的 -选择要通知的事件

______________________________________________________________________

📚 文档

• **** -综合用户指南（54页）

- 入门教程 - 所有11种类型的代理指南 - MCP工具参考 - 实用食谱和示例 - 高级主题（插件、自定义代理、工作流） - 完整的API参考

• 技术文档 -架构和实施细节

- API毫米 -MCP工具和程序化API - 建筑.md -系统架构 - 数据.md -数据库架构 - 安全.md -安全模型 - ONBOARDING.md -开发者指南

______________________________________________________________________

🚀 快速开始

安装

npm install @blackms/aistack

初始化并连接到Claude代码

# Initialize project structure
npx @blackms/aistack init

# Add to Claude Code MCP
claude mcp add aistack -- npx @blackms/aistack mcp start

# Verify installation
npx @blackms/aistack status

启动Web仪表板

# Start backend + web dashboard
npx @blackms/aistack web start

# Open http://localhost:3001

配置

创建 aistack.config.json 在项目根目录中：

{
  "version": "1.5.3",
  "providers": {
    "default": "anthropic",
    "anthropic": {
      "apiKey": "${ANTHROPIC_API_KEY}",
      "model": "claude-sonnet-4-20250514"
    },
    "openai": {
      "apiKey": "${OPENAI_API_KEY}",
      "model": "gpt-4o"
    },
    "ollama": {
      "baseUrl": "http://localhost:11434",
      "model": "llama3.2"
    }
  },
  "memory": {
    "path": "./data/aistack.db",
    "vectorSearch": {
      "enabled": false,
      "provider": "openai"
    }
  },
  "driftDetection": {
    "enabled": false,
    "threshold": 0.95,
    "warningThreshold": 0.8,
    "ancestorDepth": 3,
    "behavior": "warn",
    "asyncEmbedding": true
  },
  "resourceExhaustion": {
    "enabled": false,
    "thresholds": {
      "maxFilesAccessed": 50,
      "maxApiCalls": 100,
      "maxSubtasksSpawned": 20,
      "maxTimeWithoutDeliverableMs": 1800000,
      "maxTokensConsumed": 500000
    },
    "warningThresholdPercent": 0.7,
    "checkIntervalMs": 10000,
    "autoTerminate": false,
    "requireConfirmationOnIntervention": true,
    "pauseOnIntervention": true
  },
  "slack": {
    "enabled": false,
    "webhookUrl": "${SLACK_WEBHOOK_URL}",
    "channel": "#aistack-notifications",
    "notifyOnAgentSpawn": false,
    "notifyOnWorkflowComplete": true,
    "notifyOnErrors": true,
    "notifyOnReviewLoop": true,
    "notifyOnResourceWarning": true,
    "notifyOnResourceIntervention": true
  },
  "consensus": {
    "enabled": false,
    "requireForRiskLevels": ["high", "medium"],
    "reviewerStrategy": "adversarial",
    "timeout": 300000,
    "maxDepth": 5,
    "autoReject": false,
    "highRiskAgentTypes": ["coder", "devops", "security-auditor"],
    "mediumRiskAgentTypes": ["architect", "coordinator", "analyst"],
    "highRiskPatterns": ["delete", "remove", "drop", "deploy", "production", "credentials", "secret", "password", "token", "api key"],
    "mediumRiskPatterns": ["modify", "update", "change", "configure", "install"]
  }
}

______________________________________________________________________

💡 用法示例

示例1：代码生成与审查

通过克劳德代码（MCP）:

In Claude Code, just ask:
"Use aistack to generate a REST API for user authentication with adversarial review"

aistack will:
1. Spawn a coder agent to write the API
2. Spawn an adversarial agent to find vulnerabilities
3. Fix issues iteratively (up to 3 rounds)
4. Return production-ready code

通过CLI:

# Start adversarial review loop
npx @blackms/aistack workflow run adversarial-review \
  --task "Create REST API for user authentication"

# Check the review status
npx @blackms/aistack agent list

通过TypeScript:

import { createReviewLoop, getConfig } from '@blackms/aistack';

const result = await createReviewLoop(
  'Create REST API for user authentication',
  getConfig(),
  { maxIterations: 3 }
);

console.log(result.finalVerdict); // APPROVED
console.log(result.currentCode);   // Production-ready code

示例2：建立机构知识

学习时存储模式:

# Store a coding pattern
npx @blackms/aistack memory store \
  -k "api:error-handling" \
  -c "Always return { success: boolean, data?, error? } structure" \
  -n "best-practices"

# Store an architecture decision
npx @blackms/aistack memory store \
  -k "db:connection" \
  -c "Use connection pooling with max 10 connections" \
  -n "architecture"

需要时搜索:

# Find all patterns about error handling
npx @blackms/aistack memory search -q "error handling" -n "best-practices"

# Find architecture decisions about databases
npx @blackms/aistack memory search -q "database" -n "architecture"

克劳德密码:

You: "What's our pattern for API error handling?"
Claude uses memory_search tool: Returns your stored pattern
Claude: "Based on your team's pattern, use { success, data, error } structure"

示例3：多代理协作

使用测试和文档生成功能:

import { spawnAgent, getMemoryManager, getConfig } from '@blackms/aistack';

// 1. Coder writes the feature
const coder = spawnAgent('coder', { name: 'feature-coder' });
const code = await executeTask(coder, 'Create user profile API');

// 2. Tester writes tests
const tester = spawnAgent('tester', { name: 'test-writer' });
const tests = await executeTask(tester, 'Write tests for user profile API');

// 3. Documentation agent generates docs
const docs = spawnAgent('documentation', { name: 'doc-writer' });
const documentation = await executeTask(docs, 'Document user profile API');

// 4. Store the pattern for future use
const memory = getMemoryManager(getConfig());
await memory.store('pattern:user-api', 'User API pattern with tests and docs', {
  namespace: 'patterns',
  metadata: { code, tests, documentation }
});

示例4：在Claude代码中使用

安装MCP服务器后：

claude mcp add aistack -- npx @blackms/aistack mcp start

在Claude Code中，您可以：

"Spawn a researcher agent to analyze this codebase"
→ Uses agent_spawn tool

"Store this pattern in memory: Always validate user input"
→ Uses memory_store tool

"Search memory for authentication patterns"
→ Uses memory_search tool

"Start an adversarial review of this function"
→ Uses review_loop_start tool

"List all active agents"
→ Uses agent_list tool

示例5:CLI工作流

# 1. Start a session
npx @blackms/aistack session start --metadata '{"project": "myapp"}'

# 2. Spawn specialized agents
npx @blackms/aistack agent spawn -t coder -n backend-coder
npx @blackms/aistack agent spawn -t tester -n test-writer
npx @blackms/aistack agent spawn -t reviewer -n code-reviewer

# 3. Run tasks (agents process automatically)
npx @blackms/aistack agent run -t coder -p "Create login endpoint"
npx @blackms/aistack agent run -t tester -p "Test login endpoint"
npx @blackms/aistack agent run -t reviewer -p "Review login code"

# 4. Check system status
npx @blackms/aistack status

# 5. End session
npx @blackms/aistack session end

示例6：Web仪表板

# Start the dashboard
npx @blackms/aistack web start

然后打开http://localhost:3001致：

• 👀 监视器 所有活性剂实时
• 🧠 浏览 并搜索您的内存数据库
• ✅ 管理 可视化任务和工作流
• 📊 视图 系统健康和统计
• 🔄 手表 对抗性审查循环正在进行中

______________________________________________________________________

📦 MCP工具

代理工具（6）

记忆工具（5）

身份识别工具（8）

任务工具（8）

共识工具（5）

会话工具（4）

系统工具（3）

GitHub工具（7）

总计：46个MCP工具

注： 评审循环功能可通过程序化API获得(createReviewLoop)但不作为MCP工具公开。

______________________________________________________________________

💻 程序化API

TypeScript SDK

import {
  spawnAgent,
  getMemoryManager,
  startMCPServer,
  getConfig,
  createReviewLoop,
} from '@blackms/aistack';

// Spawn an agent
const agent = spawnAgent('coder', {
  name: 'my-coder',
  metadata: { project: 'awesome-app' }
});

// Use memory with FTS5 search
const memory = getMemoryManager(getConfig());
await memory.store('architecture:pattern', 'Use dependency injection', {
  namespace: 'best-practices',
  tags: ['architecture', 'patterns'],
});

const results = await memory.search('dependency injection');
console.log(results); // FTS5 ranked results

// Start adversarial review loop
const reviewState = await createReviewLoop(
  'Write a secure authentication function',
  getConfig(),
  { maxIterations: 3 }
);

console.log(reviewState.finalVerdict); // APPROVED or REJECTED
console.log(reviewState.currentCode);
console.log(reviewState.reviews); // All review rounds

// Start MCP server
const server = await startMCPServer(getConfig());
console.log('MCP server listening on stdio');

子模块导入

import { MemoryManager } from '@blackms/aistack/memory';
import { spawnAgent, listAgentTypes, pauseAgent, resumeAgent } from '@blackms/aistack/agents';
import { startMCPServer } from '@blackms/aistack/mcp';
import { getResourceExhaustionService } from '@blackms/aistack/monitoring';

// Direct imports for smaller bundles
const agentTypes = listAgentTypes();
// => ['coder', 'researcher', 'tester', 'reviewer', 'adversarial', 'architect', 'coordinator', 'analyst', 'devops', 'documentation', 'security-auditor']

______________________________________________________________________

📂 项目结构

aistack/
├── src/
│   ├── agents/          # 11 agent types with system prompts + identity service
│   ├── mcp/             # MCP server + 41 tools
│   ├── memory/          # SQLite + FTS5 + vector search
│   ├── tasks/           # Drift detection service
│   ├── monitoring/      # Resource exhaustion, metrics, health
│   ├── coordination/    # Task queue, message bus, review loop
│   ├── web/             # REST API + WebSocket server + identity routes
│   ├── providers/       # 6 LLM provider integrations
│   ├── workflows/       # Multi-phase workflow engine
│   ├── auth/            # JWT + RBAC authentication
│   ├── github/          # GitHub issues/PRs integration
│   ├── plugins/         # Plugin system
│   ├── hooks/           # Lifecycle hooks
│   └── cli/             # Command-line interface
│
├── web/                 # React 18 dashboard
│   └── src/
│       ├── pages/       # 11 dashboard pages
│       ├── components/  # React components
│       └── stores/      # Zustand state management
│
├── migrations/          # Database migrations
├── tests/               # Unit + integration tests
├── docs/                # Technical documentation
└── .github/workflows/   # CI/CD pipeline

______________________________________________________________________

🧪 开发与测试

构建与测试

npm install               # Install dependencies
npm run build             # Build TypeScript to dist/
npm test                  # Run all tests (unit + integration)
npm run test:unit         # Unit tests only
npm run test:integration  # Integration tests only
npm run test:coverage     # Generate coverage report
npm run typecheck         # Type check without emit
npm run lint              # ESLint

CI/CD管道

GitHub操作工作流 5个并行作业:

1. 棉绒 -ESLint代码质量检查
2. 类型检查 -TypeScript类型验证
3. 单元测试 -快速隔离测试
4. 集成测试 -数据库+代理集成
5. 构建 -生产构建验证

代码覆盖范围： 测试完成后上传到Codecov

代码： .github/workflows/ci.yml

Web仪表板开发

npm run dev:web           # Start Vite dev server (hot reload)
npm run build:web         # Build for production

______________________________________________________________________

⚠️ aistack不包括什么

为了设定准确的期望，以下是功能 明确未实施:

• ❌ Docker容器化 （没有 Dockerfile 在项目根中）
• ❌ Kubernetes/Helm清单 （无编排配置）
• ❌ 云特定部署 （AWS、GCP、Azure模板）
• ❌ GraphQL API （仅限REST+WebSocket）
• ❌ 多租户技术 （每次部署一个SQLite实例）
• ⚠️ 可观察性有限 -内置健康检查和Prometheus风格的指标，但没有Grafana仪表板
• ❌ 消息队列系统 （没有Kafka、RabbitMQ、Redis流）
• ❌ 分布式跟踪 （无OpenTetry集成）

aistack被设计为 本地优先，NPM分布式包 适用于开发人员工作流，而不是云原生微服务。

______________________________________________________________________

🗺️ 路线图

aistack的主要用例是功能完整的：本地Claude代码与多代理编排的集成。

当前重点领域：

• 稳定性和错误修复
• 文档改进
• 社区要求的功能

______________________________________________________________________

🤝 贡献

1. 克隆该仓库
2. 创建要素分支(git checkout -b feature/amazing)
3. 提交更改(git commit -m 'Add amazing feature')
4. 推送到分支(git push origin feature/amazing)
5. 打开拉取请求

PR要求：

• 所有测试均通过(npm test)
• 代码过梁(npm run lint)
• 类型已检查(npm run typecheck)
• 构建成功(npm run build)
• 保持或改进代码覆盖率

______________________________________________________________________

📄 许可证

麻省理工学院 © 2024

______________________________________________________________________

基于TypeScript构建·专为克劳德代码打造·通过NPM分发

______________________________________________________________________

✅ README已根据代码库v1.5.3进行验证 -所有声明均由具有file:行引用的已实现代码支持（包括共识检查点、资源耗尽监控和基于会话的内存隔离）