3096 lines
119 KiB
Markdown
3096 lines
119 KiB
Markdown
# IT0 后端开发指导文档
|
||
|
||
> IT Operations Intelligent Agent — 基于 Claude Code 本体的服务器集群运维智能体
|
||
|
||
## 1. 项目概述
|
||
|
||
### 1.1 定位
|
||
|
||
IT0 是一个**服务器集群运维智能体平台**，核心理念是将 Claude Code 作为运维大脑，通过自建的调度层和安全层，实现 AI 驱动的自动化运维。
|
||
|
||
### 1.2 核心设计原则
|
||
|
||
- **引擎可替换**：Claude Code CLI / Claude API / 自研 Agent 可无缝切换
|
||
- **安全第一**：三层防御模型（分级权限 + Hook 拦截 + 架构隔离）
|
||
- **人在回路**：高风险操作必须人工审批，AI 只负责"看"和"想"
|
||
- **通信多元**：支持语音、文字、短信、自动电话、社交通信、邮件等多渠道通知与交互
|
||
- **多租户 SaaS**：从第一天起支持多租户隔离，未来可对外提供服务
|
||
|
||
### 1.3 技术栈
|
||
|
||
| 层面 | 技术选型 |
|
||
|------|---------|
|
||
| 主体语言 | TypeScript (NestJS) |
|
||
| 架构模式 | DDD + Clean Architecture + 微服务 |
|
||
| 数据库 | PostgreSQL (每个服务独立 schema) |
|
||
| 消息队列 | Redis Streams / Bull Queue |
|
||
| 服务通信 | gRPC (服务间) + REST (对外 API) + WebSocket (实时推送) |
|
||
| 容器化 | Docker + Docker Compose (开发) / Kubernetes (生产) |
|
||
| API 网关 | Kong (DB-less 模式，声明式配置) |
|
||
| 监控 | Prometheus + Grafana |
|
||
| 日志 | ELK Stack / Loki |
|
||
| AI Skills | Anthropic Claude Skills（`.claude/skills/` 目录规范） |
|
||
| 语音对话引擎 | Pipecat (Python) + faster-whisper (STT) + Kokoro-82M (TTS) + Silero VAD |
|
||
| 电话线路 | Twilio Voice（仅作为 Pipecat 的电话线路载体，拨号/接听） |
|
||
|
||
---
|
||
|
||
## 2. 整体架构
|
||
|
||
### 2.1 系统架构图
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ Flutter Android App │
|
||
│ (语音/文字交互 + 仪表盘 + 任务审批 + 日志流) │
|
||
└──────────────────────────┬──────────────────────────────────┘
|
||
│ HTTPS / WebSocket
|
||
▼
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ API Gateway (Kong) │
|
||
│ 路由 / 认证 / 限流 / 日志 │
|
||
└──────┬────────┬────────┬────────┬────────┬────────┬─────────┘
|
||
│ │ │ │ │ │
|
||
▼ ▼ ▼ ▼ ▼ ▼
|
||
┌─────────┐┌────────┐┌────────┐┌────────┐┌────────┐┌────────┐
|
||
│ auth ││ agent ││ ops ││ inv ││monitor ││ comm │
|
||
│ service ││service ││service ││service ││service ││service │
|
||
└─────────┘└───┬────┘└────────┘└────────┘└────────┘└────────┘
|
||
│ │
|
||
▼ ▼
|
||
┌──────────────────────────┐ ┌──────────────────────┐
|
||
│ Agent Engine Layer │ │ 通信渠道适配器 │
|
||
│ ┌──────────────────────┐ │ │ ┌──────┐ ┌────────┐ │
|
||
│ │ Claude Code CLI │ │ │ │ SMS │ │ IM │ │
|
||
│ │ Claude API │ │ │ │Email │ │ Push │ │
|
||
│ │ Custom Agent │ │ │ └──────┘ └────────┘ │
|
||
│ └──────────────────────┘ │ └──────────┬───────────┘
|
||
└──────────┬───────────────┘ │
|
||
│ ┌─────────▼────────────┐
|
||
│ │ voice-service │
|
||
│ │ (Pipecat + Whisper) │
|
||
│ │ 实时语音对话引擎 │
|
||
│ └──────────────────────┘
|
||
│ SSH / kubectl / docker
|
||
▼
|
||
┌──────────────────────────┐
|
||
│ 目标服务器集群 │
|
||
│ prod-1 / prod-2 / k8s │
|
||
└──────────────────────────┘
|
||
```
|
||
|
||
### 2.2 微服务拆分
|
||
|
||
| 服务 | 端口 | 职责 | 数据库 Schema |
|
||
|------|------|------|--------------|
|
||
| `api-gateway` | 8000 | 路由、认证、限流 | — |
|
||
| `auth-service` | 3001 | 用户认证、RBAC、API Key | `it0_auth` |
|
||
| `agent-service` | 3002 | 智能体引擎、会话管理、命令执行 | `it0_agent` |
|
||
| `ops-service` | 3003 | 运维任务、审批工作流、Runbook | `it0_ops` |
|
||
| `inventory-service` | 3004 | 资产管理、凭证管理、SSH 配置 | `it0_inventory` |
|
||
| `monitor-service` | 3005 | 健康检查、指标、告警 | `it0_monitor` |
|
||
| `comm-service` | 3006 | 多渠道通信（推送/短信/邮件/IM） | `it0_comm` |
|
||
| `audit-service` | 3007 | 操作审计、合规日志 | `it0_audit` |
|
||
| `voice-service` | 3008 | 实时语音对话引擎（Pipecat + Whisper + Kokoro） | — (无状态) |
|
||
|
||
---
|
||
|
||
## 3. DDD 限界上下文详细设计
|
||
|
||
### 3.1 Agent Core（智能体核心）— `agent-service`
|
||
|
||
这是整个系统的**大脑**，也是架构灵活性的关键所在。
|
||
|
||
#### 3.1.1 Clean Architecture 分层
|
||
|
||
```
|
||
agent-service/
|
||
├── src/
|
||
│ ├── domain/ # 领域层（零依赖）
|
||
│ │ ├── entities/
|
||
│ │ │ ├── agent-session.entity.ts # 会话聚合根
|
||
│ │ │ ├── agent-task.entity.ts # 任务实体
|
||
│ │ │ ├── command-record.entity.ts # 命令记录
|
||
│ │ │ └── standing-order.entity.ts # ★ 驻留指令（自治任务定义）
|
||
│ │ ├── value-objects/
|
||
│ │ │ ├── agent-engine-type.vo.ts # 引擎类型（ClaudeCode/API/Custom）
|
||
│ │ │ ├── command-risk-level.vo.ts # 风险等级（L0-L3）
|
||
│ │ │ ├── task-status.vo.ts # 任务状态
|
||
│ │ │ └── session-id.vo.ts
|
||
│ │ ├── ports/ # 端口（接口定义）
|
||
│ │ │ ├── inbound/
|
||
│ │ │ │ ├── execute-task.port.ts # 执行任务用例
|
||
│ │ │ │ ├── approve-command.port.ts # 审批命令用例
|
||
│ │ │ │ ├── switch-engine.port.ts # 切换引擎用例
|
||
│ │ │ │ └── manage-standing-order.port.ts # ★ 驻留指令管理
|
||
│ │ │ └── outbound/
|
||
│ │ │ ├── agent-engine.port.ts # ★ 核心抽象 — 智能体引擎接口
|
||
│ │ │ ├── session-repository.port.ts
|
||
│ │ │ ├── command-guard.port.ts # 命令安全守卫
|
||
│ │ │ ├── event-publisher.port.ts
|
||
│ │ │ └── stream-emitter.port.ts # 流式输出发射器
|
||
│ │ ├── events/
|
||
│ │ │ ├── command-blocked.event.ts
|
||
│ │ │ ├── task-completed.event.ts
|
||
│ │ │ └── approval-required.event.ts
|
||
│ │ └── services/
|
||
│ │ ├── command-risk-classifier.ts # 命令风险分级（领域服务）
|
||
│ │ ├── session-manager.ts
|
||
│ │ └── standing-order-extractor.ts # ★ 对话 → 驻留指令提取
|
||
│ │
|
||
│ ├── application/ # 应用层（用例编排）
|
||
│ │ ├── use-cases/
|
||
│ │ │ ├── execute-task.use-case.ts
|
||
│ │ │ ├── approve-command.use-case.ts
|
||
│ │ │ ├── cancel-task.use-case.ts
|
||
│ │ │ ├── get-session-history.use-case.ts
|
||
│ │ │ └── switch-engine.use-case.ts
|
||
│ │ └── dto/
|
||
│ │ ├── execute-task.dto.ts
|
||
│ │ ├── task-result.dto.ts
|
||
│ │ └── stream-event.dto.ts
|
||
│ │
|
||
│ ├── infrastructure/ # 基础设施层（适配器实现）
|
||
│ │ ├── engines/ # ★ 引擎适配器（Strategy 模式）
|
||
│ │ │ ├── agent-engine.interface.ts # 统一接口
|
||
│ │ │ ├── claude-code-cli/
|
||
│ │ │ │ ├── claude-code-engine.ts # Claude Code CLI 适配器
|
||
│ │ │ │ ├── cli-process-manager.ts # 进程管理（spawn/kill/timeout）
|
||
│ │ │ │ ├── stream-json-parser.ts # stream-json 输出解析
|
||
│ │ │ │ ├── system-prompt-builder.ts # 运维专用 prompt 构建
|
||
│ │ │ │ └── hook-config-manager.ts # .claude/settings.json 管理
|
||
│ │ │ ├── claude-api/
|
||
│ │ │ │ ├── claude-api-engine.ts # Claude API 直连适配器
|
||
│ │ │ │ ├── tool-executor.ts # 工具执行器（Bash/Read/Write）
|
||
│ │ │ │ └── agent-loop.ts # 自建 Agent Loop
|
||
│ │ │ └── custom/
|
||
│ │ │ └── custom-engine.ts # 未来自研引擎预留
|
||
│ │ ├── guards/ # 命令安全守卫
|
||
│ │ │ ├── command-guard.service.ts # 命令拦截实现
|
||
│ │ │ ├── risk-patterns.ts # 风险命令正则库
|
||
│ │ │ └── pre-tool-use-hook.py # Claude Code Hook 脚本
|
||
│ │ ├── persistence/
|
||
│ │ │ ├── typeorm/
|
||
│ │ │ │ ├── session.orm-entity.ts
|
||
│ │ │ │ ├── task.orm-entity.ts
|
||
│ │ │ │ └── command-record.orm-entity.ts
|
||
│ │ │ └── repositories/
|
||
│ │ │ └── session.repository.ts
|
||
│ │ └── messaging/
|
||
│ │ ├── event-publisher.service.ts
|
||
│ │ └── stream-emitter.service.ts # WebSocket 流推送
|
||
│ │
|
||
│ └── interfaces/ # 接口层（控制器）
|
||
│ ├── rest/
|
||
│ │ ├── agent.controller.ts
|
||
│ │ └── session.controller.ts
|
||
│ └── ws/
|
||
│ └── agent-stream.gateway.ts # WebSocket 网关
|
||
```
|
||
|
||
#### 3.1.2 ★ 核心接口：AgentEngine（引擎抽象）
|
||
|
||
这是整个架构灵活性的**核心**，使用 **Strategy + Adapter 模式**：
|
||
|
||
```typescript
|
||
// domain/ports/outbound/agent-engine.port.ts
|
||
|
||
/**
|
||
* 智能体引擎端口 — 所有引擎实现必须遵循此接口
|
||
* Claude Code CLI / Claude API / 自研 Agent 均通过此接口接入
|
||
*/
|
||
export interface AgentEnginePort {
|
||
/** 引擎类型标识 */
|
||
readonly engineType: AgentEngineType;
|
||
|
||
/**
|
||
* 执行任务（流式输出）
|
||
* @returns AsyncGenerator，逐步 yield 流式事件
|
||
*/
|
||
executeTask(params: EngineTaskParams): AsyncGenerator<EngineStreamEvent>;
|
||
|
||
/** 取消正在执行的任务 */
|
||
cancelTask(sessionId: string): Promise<void>;
|
||
|
||
/** 继续会话（追加指令） */
|
||
continueSession(sessionId: string, message: string): AsyncGenerator<EngineStreamEvent>;
|
||
|
||
/** 健康检查 */
|
||
healthCheck(): Promise<boolean>;
|
||
}
|
||
|
||
/** 引擎任务参数 */
|
||
export interface EngineTaskParams {
|
||
sessionId: string;
|
||
prompt: string;
|
||
systemPrompt: string;
|
||
allowedTools: string[];
|
||
maxTurns: number;
|
||
maxBudgetUsd?: number;
|
||
/** 上下文附加信息（服务器清单、历史操作等） */
|
||
context?: Record<string, unknown>;
|
||
/** Skill 调用：如果指定，prompt 格式为 /{skillName} {args} */
|
||
skill?: {
|
||
name: string;
|
||
arguments: string;
|
||
};
|
||
}
|
||
|
||
/** 引擎流式事件（统一格式，各适配器负责转换） */
|
||
export type EngineStreamEvent =
|
||
| { type: 'thinking'; content: string }
|
||
| { type: 'text'; content: string }
|
||
| { type: 'tool_use'; toolName: string; input: Record<string, unknown> }
|
||
| { type: 'tool_result'; toolName: string; output: string; isError: boolean }
|
||
| { type: 'approval_required'; command: string; riskLevel: RiskLevel; taskId: string }
|
||
| { type: 'completed'; summary: string; tokensUsed?: number }
|
||
| { type: 'error'; message: string; code: string };
|
||
```
|
||
|
||
#### 3.1.3 Claude Code CLI 引擎实现
|
||
|
||
```typescript
|
||
// infrastructure/engines/claude-code-cli/claude-code-engine.ts
|
||
|
||
@Injectable()
|
||
export class ClaudeCodeCliEngine implements AgentEnginePort {
|
||
readonly engineType = AgentEngineType.CLAUDE_CODE_CLI;
|
||
|
||
constructor(
|
||
private readonly processManager: CliProcessManager,
|
||
private readonly streamParser: StreamJsonParser,
|
||
private readonly promptBuilder: SystemPromptBuilder,
|
||
private readonly configService: ConfigService,
|
||
) {}
|
||
|
||
async *executeTask(params: EngineTaskParams): AsyncGenerator<EngineStreamEvent> {
|
||
const systemPromptPath = await this.promptBuilder.buildAndSave(params);
|
||
|
||
const args = [
|
||
'-p', params.prompt,
|
||
'--system-prompt-file', systemPromptPath,
|
||
'--output-format', 'stream-json',
|
||
'--allowedTools', params.allowedTools.join(','),
|
||
'--max-turns', String(params.maxTurns),
|
||
'--session-id', params.sessionId,
|
||
'--verbose',
|
||
'--include-partial-messages',
|
||
];
|
||
|
||
if (params.maxBudgetUsd) {
|
||
args.push('--max-budget-usd', String(params.maxBudgetUsd));
|
||
}
|
||
|
||
const process = this.processManager.spawn('claude', args);
|
||
|
||
for await (const rawEvent of this.streamParser.parse(process.stdout)) {
|
||
// 将 Claude Code 原始 stream-json 事件转换为统一 EngineStreamEvent
|
||
const event = this.mapToEngineEvent(rawEvent);
|
||
if (event) yield event;
|
||
}
|
||
|
||
const exitCode = await this.processManager.waitForExit(process);
|
||
if (exitCode !== 0) {
|
||
yield { type: 'error', message: `Claude Code exited with code ${exitCode}`, code: 'CLI_EXIT_ERROR' };
|
||
}
|
||
}
|
||
|
||
// ... 其他方法
|
||
}
|
||
```
|
||
|
||
#### 3.1.4 Claude API 引擎实现（备选）
|
||
|
||
```typescript
|
||
// infrastructure/engines/claude-api/claude-api-engine.ts
|
||
|
||
@Injectable()
|
||
export class ClaudeApiEngine implements AgentEnginePort {
|
||
readonly engineType = AgentEngineType.CLAUDE_API;
|
||
|
||
constructor(
|
||
private readonly toolExecutor: ToolExecutor, // 自建的 Bash/Read/Write 执行器
|
||
private readonly configService: ConfigService,
|
||
) {}
|
||
|
||
async *executeTask(params: EngineTaskParams): AsyncGenerator<EngineStreamEvent> {
|
||
const client = new Anthropic({ apiKey: this.configService.get('ANTHROPIC_API_KEY') });
|
||
|
||
const tools = this.buildToolDefinitions(params.allowedTools);
|
||
let messages: MessageParam[] = [{ role: 'user', content: params.prompt }];
|
||
|
||
// 自建 Agent Loop
|
||
for (let turn = 0; turn < params.maxTurns; turn++) {
|
||
const stream = client.messages.stream({
|
||
model: this.configService.get('CLAUDE_MODEL', 'claude-sonnet-4-5-20250929'),
|
||
max_tokens: 8192,
|
||
system: params.systemPrompt,
|
||
messages,
|
||
tools,
|
||
});
|
||
|
||
for await (const event of stream) {
|
||
const mapped = this.mapStreamEvent(event);
|
||
if (mapped) yield mapped;
|
||
}
|
||
|
||
const response = await stream.finalMessage();
|
||
|
||
// 检查是否需要执行工具
|
||
const toolUseBlocks = response.content.filter(b => b.type === 'tool_use');
|
||
if (toolUseBlocks.length === 0) break; // 无工具调用，结束
|
||
|
||
// 执行工具并收集结果
|
||
const toolResults = [];
|
||
for (const block of toolUseBlocks) {
|
||
const result = await this.toolExecutor.execute(block.name, block.input);
|
||
yield { type: 'tool_result', toolName: block.name, output: result.output, isError: result.isError };
|
||
toolResults.push({ type: 'tool_result' as const, tool_use_id: block.id, content: result.output });
|
||
}
|
||
|
||
messages = [...messages,
|
||
{ role: 'assistant', content: response.content },
|
||
{ role: 'user', content: toolResults },
|
||
];
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 3.1.5 引擎切换机制
|
||
|
||
```typescript
|
||
// infrastructure/engines/engine-registry.ts
|
||
|
||
@Injectable()
|
||
export class EngineRegistry {
|
||
private engines = new Map<AgentEngineType, AgentEnginePort>();
|
||
|
||
constructor(
|
||
@Optional() private readonly cliEngine: ClaudeCodeCliEngine,
|
||
@Optional() private readonly apiEngine: ClaudeApiEngine,
|
||
@Optional() private readonly customEngine: CustomEngine,
|
||
private readonly configService: ConfigService,
|
||
) {
|
||
if (cliEngine) this.engines.set(AgentEngineType.CLAUDE_CODE_CLI, cliEngine);
|
||
if (apiEngine) this.engines.set(AgentEngineType.CLAUDE_API, apiEngine);
|
||
if (customEngine) this.engines.set(AgentEngineType.CUSTOM, customEngine);
|
||
}
|
||
|
||
/** 获取当前活跃引擎 */
|
||
getActiveEngine(): AgentEnginePort {
|
||
const type = this.configService.get<AgentEngineType>(
|
||
'AGENT_ENGINE_TYPE',
|
||
AgentEngineType.CLAUDE_CODE_CLI,
|
||
);
|
||
const engine = this.engines.get(type);
|
||
if (!engine) throw new Error(`Engine ${type} not registered`);
|
||
return engine;
|
||
}
|
||
|
||
/** 运行时切换引擎 */
|
||
switchEngine(type: AgentEngineType): AgentEnginePort {
|
||
const engine = this.engines.get(type);
|
||
if (!engine) throw new Error(`Engine ${type} not available`);
|
||
// 更新配置
|
||
this.configService.set('AGENT_ENGINE_TYPE', type);
|
||
return engine;
|
||
}
|
||
|
||
/** 列出可用引擎 */
|
||
listAvailable(): AgentEngineType[] {
|
||
return [...this.engines.keys()];
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 3.2 Operations（运维操作）— `ops-service`
|
||
|
||
#### 3.2.1 目录结构
|
||
|
||
```
|
||
ops-service/
|
||
├── src/
|
||
│ ├── domain/
|
||
│ │ ├── entities/
|
||
│ │ │ ├── ops-task.entity.ts # 运维任务聚合根
|
||
│ │ │ ├── approval-request.entity.ts # 审批请求
|
||
│ │ │ ├── runbook.entity.ts # 运维手册
|
||
│ │ │ ├── standing-order.entity.ts # ★ 驻留指令聚合根
|
||
│ │ │ └── standing-order-execution.entity.ts # ★ 执行记录
|
||
│ │ ├── value-objects/
|
||
│ │ │ ├── task-type.vo.ts # 巡检/部署/回滚/扩缩容/故障恢复
|
||
│ │ │ ├── approval-status.vo.ts # pending/approved/rejected
|
||
│ │ │ └── execution-result.vo.ts
|
||
│ │ ├── ports/
|
||
│ │ │ ├── inbound/
|
||
│ │ │ │ ├── create-task.port.ts
|
||
│ │ │ │ ├── approve-task.port.ts
|
||
│ │ │ │ └── execute-runbook.port.ts
|
||
│ │ │ └── outbound/
|
||
│ │ │ ├── task-repository.port.ts
|
||
│ │ │ ├── agent-client.port.ts # 调用 agent-service
|
||
│ │ │ ├── notification.port.ts # 调用 comm-service
|
||
│ │ │ └── audit-logger.port.ts # 调用 audit-service
|
||
│ │ └── services/
|
||
│ │ └── approval-workflow.service.ts # 审批流程领域服务
|
||
│ │
|
||
│ ├── application/
|
||
│ │ └── use-cases/
|
||
│ │ ├── create-inspection-task.use-case.ts # 创建巡检任务
|
||
│ │ ├── create-deployment-task.use-case.ts # 创建部署任务
|
||
│ │ ├── approve-task.use-case.ts
|
||
│ │ ├── schedule-recurring-task.use-case.ts # 定时任务
|
||
│ │ ├── execute-runbook.use-case.ts
|
||
│ │ ├── create-standing-order.use-case.ts # ★ 创建驻留指令
|
||
│ │ ├── update-standing-order.use-case.ts # ★ 修改驻留指令
|
||
│ │ └── execute-standing-order.use-case.ts # ★ 执行驻留指令
|
||
│ │
|
||
│ ├── infrastructure/
|
||
│ │ ├── persistence/typeorm/
|
||
│ │ ├── clients/
|
||
│ │ │ ├── agent-client.service.ts # gRPC 调用 agent-service
|
||
│ │ │ └── comm-client.service.ts # gRPC 调用 comm-service
|
||
│ │ └── schedulers/
|
||
│ │ ├── cron-scheduler.service.ts # 定时巡检调度
|
||
│ │ └── standing-order-executor.ts # ★ 驻留指令执行引擎
|
||
│ │
|
||
│ └── interfaces/
|
||
│ └── rest/
|
||
│ ├── task.controller.ts
|
||
│ ├── approval.controller.ts
|
||
│ └── runbook.controller.ts
|
||
```
|
||
|
||
#### 3.2.2 审批工作流
|
||
|
||
```typescript
|
||
// domain/services/approval-workflow.service.ts
|
||
|
||
export class ApprovalWorkflowService {
|
||
/**
|
||
* 审批流程：
|
||
* 1. agent-service 执行任务时遇到 Level 2 命令
|
||
* 2. 发布 approval_required 事件
|
||
* 3. ops-service 创建审批请求
|
||
* 4. comm-service 通知人类（推送/短信/电话）
|
||
* 5. 人类通过 Flutter App 或回复短信/邮件 审批
|
||
* 6. ops-service 发布 approval_granted 事件
|
||
* 7. agent-service 继续执行
|
||
*
|
||
* 超时策略：
|
||
* - Level 1: 5 分钟超时，自动通过
|
||
* - Level 2: 30 分钟超时，自动拒绝
|
||
* - 紧急模式: 管理员可设置特定 Runbook 自动审批
|
||
*/
|
||
async processApproval(request: ApprovalRequest): Promise<ApprovalResult> {
|
||
// ...
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 3.3 Inventory（资产管理）— `inventory-service`
|
||
|
||
```
|
||
inventory-service/
|
||
├── src/
|
||
│ ├── domain/
|
||
│ │ ├── entities/
|
||
│ │ │ ├── server.entity.ts # 服务器实体
|
||
│ │ │ ├── cluster.entity.ts # 集群聚合根
|
||
│ │ │ ├── credential.entity.ts # 凭证（加密存储）
|
||
│ │ │ └── ssh-config.entity.ts # SSH 配置
|
||
│ │ ├── value-objects/
|
||
│ │ │ ├── server-role.vo.ts # web/db/cache/worker/gateway
|
||
│ │ │ ├── environment.vo.ts # dev/staging/prod
|
||
│ │ │ └── connection-info.vo.ts # IP/端口/用户
|
||
│ │ └── ports/
|
||
│ │ └── outbound/
|
||
│ │ ├── server-repository.port.ts
|
||
│ │ └── credential-vault.port.ts # 凭证保险库
|
||
│ │
|
||
│ ├── infrastructure/
|
||
│ │ ├── vault/
|
||
│ │ │ └── credential-vault.service.ts # AES-256 加密存储
|
||
│ │ └── persistence/typeorm/
|
||
│ │
|
||
│ └── interfaces/
|
||
│ └── rest/
|
||
│ ├── server.controller.ts
|
||
│ └── cluster.controller.ts
|
||
```
|
||
|
||
**关键：凭证安全**
|
||
|
||
```typescript
|
||
// infrastructure/vault/credential-vault.service.ts
|
||
|
||
@Injectable()
|
||
export class CredentialVaultService implements CredentialVaultPort {
|
||
/**
|
||
* 凭证存储规范：
|
||
* - SSH 私钥、密码等敏感信息 AES-256-GCM 加密后存入 PostgreSQL
|
||
* - 加密密钥从环境变量 VAULT_MASTER_KEY 读取
|
||
* - 读取时解密到内存，绝不写入日志或磁盘临时文件
|
||
* - Agent 需要 SSH 时，通过 inventory-service API 获取临时凭证
|
||
* （凭证有 TTL，用后即弃）
|
||
*/
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 3.4 Monitoring（监控告警）— `monitor-service`
|
||
|
||
```
|
||
monitor-service/
|
||
├── src/
|
||
│ ├── domain/
|
||
│ │ ├── entities/
|
||
│ │ │ ├── health-check.entity.ts
|
||
│ │ │ ├── alert-rule.entity.ts # 告警规则
|
||
│ │ │ ├── alert-event.entity.ts # 告警事件
|
||
│ │ │ └── metric-snapshot.entity.ts
|
||
│ │ ├── value-objects/
|
||
│ │ │ ├── alert-severity.vo.ts # info/warning/critical/fatal
|
||
│ │ │ ├── check-type.vo.ts # ping/http/tcp/ssh/custom
|
||
│ │ │ └── metric-type.vo.ts # cpu/mem/disk/network/custom
|
||
│ │ └── ports/outbound/
|
||
│ │ ├── metric-collector.port.ts # 指标采集
|
||
│ │ └── alert-dispatcher.port.ts # 告警分发 → comm-service
|
||
│ │
|
||
│ ├── infrastructure/
|
||
│ │ ├── collectors/
|
||
│ │ │ ├── ssh-collector.service.ts # SSH 远程采集
|
||
│ │ │ ├── prometheus-collector.ts # Prometheus 拉取
|
||
│ │ │ └── agent-collector.ts # 通过 agent-service 执行采集命令
|
||
│ │ └── schedulers/
|
||
│ │ └── health-check-scheduler.ts # 定时健康检查
|
||
│ │
|
||
│ └── interfaces/
|
||
│ └── rest/
|
||
│ ├── health-check.controller.ts
|
||
│ └── alert.controller.ts
|
||
```
|
||
|
||
**告警 → 自动修复流程：**
|
||
|
||
```
|
||
monitor-service 检测到异常
|
||
↓ 发布 AlertEvent
|
||
ops-service 接收告警
|
||
↓ 匹配 Runbook（自动修复手册）
|
||
↓ 如果有匹配的 Runbook 且风险等级允许
|
||
agent-service 执行修复
|
||
↓ 如果需要审批
|
||
comm-service 通知人类（推送+短信+电话升级）
|
||
↓ 人类审批
|
||
agent-service 继续执行
|
||
↓
|
||
monitor-service 验证恢复
|
||
```
|
||
|
||
---
|
||
|
||
### 3.5 Communication（多渠道通信）— `comm-service`
|
||
|
||
这是联系人类的统一出口。
|
||
|
||
```
|
||
comm-service/
|
||
├── src/
|
||
│ ├── domain/
|
||
│ │ ├── entities/
|
||
│ │ │ ├── message.entity.ts # 消息聚合根
|
||
│ │ │ ├── contact.entity.ts # 联系人
|
||
│ │ │ ├── channel-config.entity.ts # 渠道配置
|
||
│ │ │ └── escalation-policy.entity.ts # 升级策略
|
||
│ │ ├── value-objects/
|
||
│ │ │ ├── channel-type.vo.ts # push/sms/voice_call/email/telegram/wechat/voice_dialog
|
||
│ │ │ ├── message-priority.vo.ts # low/normal/high/urgent
|
||
│ │ │ └── delivery-status.vo.ts # pending/sent/delivered/failed
|
||
│ │ └── ports/outbound/
|
||
│ │ └── channel-adapter.port.ts # ★ 通信渠道抽象接口
|
||
│ │
|
||
│ ├── infrastructure/
|
||
│ │ ├── channels/ # ★ 渠道适配器（Strategy 模式）
|
||
│ │ │ ├── channel-adapter.interface.ts
|
||
│ │ │ ├── websocket/
|
||
│ │ │ │ └── ws-channel.adapter.ts # WebSocket 实时推送
|
||
│ │ │ ├── sms/
|
||
│ │ │ │ └── twilio-sms.adapter.ts # Twilio SMS
|
||
│ │ │ ├── voice/
|
||
│ │ │ │ ├── pipecat-voice.adapter.ts # ★ 主要：Pipecat 实时语音对话
|
||
│ │ │ │ └── twilio-voice.adapter.ts # Twilio 电话线路（Pipecat 拨号载体）
|
||
│ │ │ ├── email/
|
||
│ │ │ │ └── smtp-email.adapter.ts # SMTP 邮件
|
||
│ │ │ ├── telegram/
|
||
│ │ │ │ └── telegram-bot.adapter.ts # Telegram Bot
|
||
│ │ │ ├── wechat/
|
||
│ │ │ │ └── wechat-work.adapter.ts # 企业微信
|
||
│ │ │ └── voice-client/
|
||
│ │ │ └── voice-service-client.ts # HTTP/gRPC 调用 voice-service
|
||
│ │ ├── escalation/
|
||
│ │ │ └── escalation-engine.service.ts # 升级引擎
|
||
│ │ └── persistence/typeorm/
|
||
│ │
|
||
│ └── interfaces/
|
||
│ ├── rest/
|
||
│ │ ├── message.controller.ts
|
||
│ │ └── contact.controller.ts
|
||
│ └── ws/
|
||
│ └── realtime.gateway.ts
|
||
```
|
||
|
||
#### 3.5.1 通信渠道抽象
|
||
|
||
```typescript
|
||
// domain/ports/outbound/channel-adapter.port.ts
|
||
|
||
export interface ChannelAdapterPort {
|
||
readonly channelType: ChannelType;
|
||
|
||
/** 发送消息（文字/语音/富文本） */
|
||
send(params: SendMessageParams): Promise<DeliveryResult>;
|
||
|
||
/** 接收消息（双向渠道如 Telegram/微信） */
|
||
onMessage?(callback: (msg: IncomingMessage) => void): void;
|
||
|
||
/** 渠道是否可用 */
|
||
isAvailable(): Promise<boolean>;
|
||
}
|
||
|
||
export interface SendMessageParams {
|
||
to: Contact;
|
||
content: string;
|
||
priority: MessagePriority;
|
||
/** 语音电话场景：TTS 文本 */
|
||
ttsText?: string;
|
||
/** 审批场景：附带审批链接或回复指令 */
|
||
approvalAction?: {
|
||
taskId: string;
|
||
approveKeyword: string; // 如 "Y" 或 "approve"
|
||
rejectKeyword: string; // 如 "N" 或 "reject"
|
||
};
|
||
}
|
||
```
|
||
|
||
#### 3.5.2 升级策略（Escalation）
|
||
|
||
```typescript
|
||
// infrastructure/escalation/escalation-engine.service.ts
|
||
|
||
/**
|
||
* 通知升级策略（分层递进）：
|
||
*
|
||
* ┌─── 第一层：推送 + 电话 ─────────────────────────────────────┐
|
||
* │ 1. WebSocket + FCM 推送到 Flutter App（通知卡片） │
|
||
* │ 用户打开 App → Pipecat 语音对话（App 内 WebSocket 音频） │
|
||
* │ 2. 如果 2 分钟内无响应 → Pipecat 通过 Twilio 拨出电话 │
|
||
* │ 管理员接听 → Agent 直接开口说话（同一 Pipecat 引擎） │
|
||
* │ "您好，prod-2 磁盘 97%，我建议清理日志，您同意吗？" │
|
||
* │ 管理员语音回复 → Agent 理解并执行 │
|
||
* └────────────────────────────────────────────────────────────┘
|
||
*
|
||
* ┌─── 第二层：扩大通知 ──────────────────────────────────────┐
|
||
* │ 如果 5 分钟内仍无响应 → 短信 + IM (Telegram/企业微信) │
|
||
* │ 如果 10 分钟内无响应 → 通知备用联系人（重复第一层） │
|
||
* │ 如果 20 分钟内无响应 → 邮件通知管理组（完整报告） │
|
||
* └────────────────────────────────────────────────────────────┘
|
||
*
|
||
* 升级策略可按告警级别自定义：
|
||
* - info: 只推送 App
|
||
* - warning: App + 短信/IM
|
||
* - critical: App + Pipecat 电话语音对话
|
||
* - fatal: 全渠道 + 备用联系人 + 管理组
|
||
*/
|
||
```
|
||
|
||
#### 3.5.3 语音交互流程（Pipecat 引擎）
|
||
|
||
IT0 使用 **Pipecat**（GitHub 10.1k stars）作为实时语音对话引擎，自部署 STT/TTS 模型，不依赖外部语音 API。
|
||
|
||
**主要场景：App 内语音对话**
|
||
```
|
||
Flutter App（麦克风录音）
|
||
↓ WebSocket 音频流 (PCM 16kHz)
|
||
voice-service (Pipecat Pipeline)
|
||
├── Silero VAD → 检测语音活动 + 打断
|
||
├── faster-whisper → STT（语音转文字）
|
||
├── Claude API → LLM 理解 + 决策
|
||
└── Kokoro-82M → TTS（文字转语音）
|
||
↓ WebSocket 音频流
|
||
Flutter App 实时播放语音回复
|
||
↓ 同步显示实时转写文字（辅助理解 + 留痕）
|
||
```
|
||
|
||
**电话场景：Pipecat 主动拨号（2分钟 App 无响应后）**
|
||
```
|
||
voice-service (Pipecat) 发起拨号请求
|
||
↓ Twilio REST API: 拨出电话到管理员手机
|
||
管理员手机响铃 → 接听
|
||
↓ Twilio Media Streams (WebSocket 双向音频)
|
||
voice-service (Pipecat Pipeline) ← 同一个引擎
|
||
├── 与 App 内语音对话使用完全相同的 Pipeline
|
||
├── Agent 接通后立即开口："您好，我是 IT0 Agent..."
|
||
└── 唯一区别：音频通过 Twilio 电话线而非 Flutter WebSocket
|
||
↓ Twilio Media Streams
|
||
管理员通过电话与 Agent 语音对话
|
||
```
|
||
|
||
**关键设计决策**：
|
||
- **Pipecat 是唯一的语音对话引擎**，无论音频来自 App 还是电话线
|
||
- **Twilio 只是电话线路载体**（拨号/接听），不负责任何 STT/TTS/IVR 逻辑
|
||
- **无 IVR 菜单**：不需要"按 1 按 2"，Agent 接通就说话，管理员直接语音回复
|
||
- **所有 STT/TTS 在本地 GPU 运行**（faster-whisper + Kokoro），延迟 < 500ms
|
||
- **支持打断（barge-in）**：用户开始说话时 Pipecat 自动暂停 TTS 播放
|
||
|
||
#### 3.5.4 Voice Dialogue Service（voice-service）
|
||
|
||
voice-service 是一个 **Python 微服务**，基于 Pipecat 框架运行实时语音对话 Pipeline。
|
||
|
||
```
|
||
voice-service/ # Python (FastAPI + Pipecat)
|
||
├── app/
|
||
│ ├── main.py # FastAPI 入口
|
||
│ ├── config.py # 配置（模型路径、端口、Claude API Key）
|
||
│ ├── pipelines/
|
||
│ │ ├── base_pipeline.py # ★ Pipecat Pipeline 定义
|
||
│ │ │ # VAD → STT → LLM → TTS → Audio Output
|
||
│ │ ├── app_transport.py # Flutter WebSocket 音频传输
|
||
│ │ └── twilio_transport.py # Twilio Media Streams 音频传输
|
||
│ ├── services/
|
||
│ │ ├── stt_service.py # faster-whisper 配置（模型: large-v3, GPU）
|
||
│ │ ├── tts_service.py # Kokoro-82M 配置（中/英双语）
|
||
│ │ ├── vad_service.py # Silero VAD 配置
|
||
│ │ └── llm_service.py # Pipecat AnthropicLLMService (Claude API)
|
||
│ ├── context/
|
||
│ │ ├── session_context.py # 对话上下文管理（从 agent-service 获取）
|
||
│ │ └── tool_handler.py # Agent tool 调用转发给 agent-service
|
||
│ └── api/
|
||
│ ├── health.py # 健康检查
|
||
│ ├── session_router.py # 创建/结束语音对话会话
|
||
│ └── twilio_webhook.py # Twilio Media Streams WebSocket 端点
|
||
├── models/ # 本地模型文件
|
||
│ ├── whisper-large-v3/ # faster-whisper 模型
|
||
│ ├── kokoro-82m/ # Kokoro TTS 模型
|
||
│ └── silero-vad/ # Silero VAD 模型
|
||
├── Dockerfile
|
||
├── requirements.txt
|
||
└── docker-compose.voice.yml
|
||
```
|
||
|
||
```python
|
||
# app/pipelines/base_pipeline.py — Pipecat Pipeline 核心
|
||
|
||
from pipecat.pipeline.pipeline import Pipeline
|
||
from pipecat.pipeline.task import PipelineTask
|
||
from pipecat.services.anthropic import AnthropicLLMService
|
||
from pipecat.services.faster_whisper import FasterWhisperSTTService
|
||
from pipecat.services.kokoro import KokoroTTSService
|
||
from pipecat.vad.silero import SileroVADAnalyzer
|
||
|
||
async def create_voice_pipeline(
|
||
transport, # AppTransport 或 TwilioTransport
|
||
session_context, # 对话上下文（驻留指令、服务器信息等）
|
||
):
|
||
"""
|
||
创建 Pipecat 语音对话 Pipeline
|
||
- 音频输入 → VAD → STT → LLM → TTS → 音频输出
|
||
- 支持打断：用户说话时自动停止 TTS
|
||
- 支持 tool_use：Agent 可调用 agent-service 的工具
|
||
"""
|
||
stt = FasterWhisperSTTService(
|
||
model="large-v3",
|
||
language="zh", # 中文为主，自动检测英文
|
||
device="cuda",
|
||
)
|
||
|
||
llm = AnthropicLLMService(
|
||
model="claude-sonnet-4-5-20250929",
|
||
system_prompt=session_context.system_prompt,
|
||
tools=session_context.available_tools,
|
||
)
|
||
|
||
tts = KokoroTTSService(
|
||
model="kokoro-82m",
|
||
voice="zh_female_1", # 中文女声
|
||
)
|
||
|
||
pipeline = Pipeline([
|
||
transport.input(), # 音频输入
|
||
SileroVADAnalyzer(), # 语音活动检测
|
||
stt, # 语音 → 文字
|
||
llm, # 文字 → Agent 回复
|
||
tts, # 回复 → 语音
|
||
transport.output(), # 音频输出
|
||
])
|
||
|
||
return PipelineTask(pipeline, allow_interruptions=True)
|
||
```
|
||
|
||
```python
|
||
# app/pipelines/app_transport.py — Flutter App WebSocket 传输
|
||
|
||
from pipecat.transports.network.websocket import WebSocketServerTransport
|
||
|
||
class AppTransport(WebSocketServerTransport):
|
||
"""
|
||
Flutter App 通过 WebSocket 发送/接收音频流
|
||
- 输入：PCM 16kHz 16bit 单声道（Flutter 录音格式）
|
||
- 输出：PCM 16kHz 16bit 单声道（Flutter 播放格式）
|
||
"""
|
||
def __init__(self, websocket):
|
||
super().__init__(
|
||
websocket=websocket,
|
||
params=WebSocketServerParams(
|
||
audio_in_sample_rate=16000,
|
||
audio_out_sample_rate=16000,
|
||
vad_enabled=True,
|
||
vad_analyzer=SileroVADAnalyzer(),
|
||
),
|
||
)
|
||
```
|
||
|
||
```python
|
||
# app/pipelines/twilio_transport.py — Twilio 电话线兜底传输
|
||
|
||
from pipecat.transports.services.twilio import TwilioTransport
|
||
|
||
class TwilioPhoneTransport(TwilioTransport):
|
||
"""
|
||
Twilio 电话线传输：Pipecat 主动拨号 → 管理员接听 → Agent 直接开口说话
|
||
- Pipecat 调用 Twilio REST API 拨出电话
|
||
- 接通后通过 Media Streams WebSocket 双向传输音频
|
||
- Agent 接通即开始语音汇报，无 IVR 菜单
|
||
- 音频编解码：mu-law 8kHz（电话标准）↔ PCM 16kHz（Whisper 输入）
|
||
"""
|
||
async def initiate_call(self, phone_number: str, voice_session_id: str):
|
||
"""主动拨出电话（由 SmartEscalationService 触发）"""
|
||
# Twilio REST API 创建呼叫，连接到 Media Streams
|
||
pass
|
||
```
|
||
|
||
**Docker 配置**：
|
||
```yaml
|
||
# docker-compose.voice.yml
|
||
voice-service:
|
||
build: ./packages/services/voice-service
|
||
ports:
|
||
- "3008:3008"
|
||
environment:
|
||
- ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
|
||
- AGENT_SERVICE_URL=http://agent-service:3002
|
||
- WHISPER_MODEL=large-v3
|
||
- KOKORO_MODEL=kokoro-82m
|
||
- DEVICE=cuda # GPU 加速（生产环境）
|
||
volumes:
|
||
- ./models:/app/models # 模型文件挂载
|
||
deploy:
|
||
resources:
|
||
reservations:
|
||
devices:
|
||
- driver: nvidia
|
||
count: 1
|
||
capabilities: [gpu]
|
||
healthcheck:
|
||
test: ["CMD", "curl", "-f", "http://localhost:3008/health"]
|
||
interval: 30s
|
||
start_period: 60s # 模型加载时间
|
||
```
|
||
|
||
---
|
||
|
||
### 3.6 Audit（审计日志）— `audit-service`
|
||
|
||
```
|
||
audit-service/
|
||
├── src/
|
||
│ ├── domain/
|
||
│ │ ├── entities/
|
||
│ │ │ └── audit-log.entity.ts
|
||
│ │ └── value-objects/
|
||
│ │ ├── action-type.vo.ts # command_executed/approval/login/config_change
|
||
│ │ └── audit-level.vo.ts
|
||
│ ├── application/
|
||
│ │ └── use-cases/
|
||
│ │ ├── record-audit.use-case.ts
|
||
│ │ └── query-audit-trail.use-case.ts
|
||
│ └── infrastructure/
|
||
│ └── persistence/
|
||
│ └── append-only-repository.ts # 只追加，不可修改/删除
|
||
```
|
||
|
||
**审计日志规范：**
|
||
- 所有 agent 执行的命令、结果、时间戳
|
||
- 所有审批操作的决策人、时间、理由
|
||
- 所有引擎切换操作
|
||
- **只追加（Append-Only）**，不可篡改
|
||
|
||
---
|
||
|
||
### 3.7 Auth（认证授权）— `auth-service`
|
||
|
||
```
|
||
auth-service/
|
||
├── src/
|
||
│ ├── domain/
|
||
│ │ ├── entities/
|
||
│ │ │ ├── user.entity.ts
|
||
│ │ │ ├── role.entity.ts
|
||
│ │ │ └── api-key.entity.ts
|
||
│ │ └── value-objects/
|
||
│ │ ├── permission.vo.ts # 细粒度权限
|
||
│ │ └── role-type.vo.ts # admin/operator/viewer
|
||
│ └── infrastructure/
|
||
│ ├── jwt/
|
||
│ │ └── jwt.strategy.ts
|
||
│ └── guards/
|
||
│ └── rbac.guard.ts
|
||
```
|
||
|
||
**RBAC 权限模型：**
|
||
|
||
| 角色 | 查看仪表盘 | 发起巡检 | 审批操作 | 管理服务器 | 切换引擎 |
|
||
|------|-----------|---------|---------|-----------|---------|
|
||
| viewer | ✅ | ❌ | ❌ | ❌ | ❌ |
|
||
| operator | ✅ | ✅ | ❌ | ❌ | ❌ |
|
||
| admin | ✅ | ✅ | ✅ | ✅ | ✅ |
|
||
|
||
---
|
||
|
||
### 3.8 ★ 自治运维工作流 — 驻留指令（Standing Orders）
|
||
|
||
这是 IT0 的**核心运维范式**：管理员通过对话定义任务 → Agent 自主执行 → 遇到无法决策的事件智能升级给人类。
|
||
|
||
#### 3.8.1 核心概念：驻留指令
|
||
|
||
**驻留指令（Standing Order）** 是管理员通过对话与 Agent 协商后生成的**持久化自治任务定义**。一旦创建，Agent 将按照定义自主执行，无需管理员持续在线。
|
||
|
||
```
|
||
┌────────────────────────────────────────────────────────────────────────┐
|
||
│ IT0 自治运维工作流 │
|
||
│ │
|
||
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐ │
|
||
│ │ Phase 1 │ │ Phase 2 │ │ Phase 3 │ │
|
||
│ │ 对话定义 │───→│ 自治执行 │───→│ 智能升级 │ │
|
||
│ │ │ │ │ │ │ │
|
||
│ │ 管理员通过 │ │ Agent 按计划 │ │ 遇到无法决策的情况： │ │
|
||
│ │ 文字/语音对话 │ │ 或事件触发 │ │ │ │
|
||
│ │ 与 Agent 沟通 │ │ 自动执行任务 │ │ 致命 → 语音电话 │ │
|
||
│ │ 任务需求 │ │ │ │ 严重 → IM 实时消息 │ │
|
||
│ │ │ │ 在决策边界内 │ │ 警告 → 短信/推送 │ │
|
||
│ │ Agent 提取为 │ │ 自主处理问题 │ │ 信息 → 邮件/日报 │ │
|
||
│ │ 结构化指令 │ │ │ │ │ │
|
||
│ │ │ │ 记录所有操作 │ │ 人类响应后继续执行 │ │
|
||
│ │ 管理员确认 │ │ 到审计日志 │ │ 或按人类指示调整 │ │
|
||
│ └──────────────┘ └──────────────┘ └──────────────────────┘ │
|
||
│ │
|
||
│ ── 管理员随时可以修改、暂停、删除驻留指令 ── │
|
||
└────────────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
#### 3.8.2 对话 → 指令提取（Task Definition Session）
|
||
|
||
管理员与 Agent 的对话中，Agent 使用专门的**指令提取模式**，从自然语言中结构化提取任务定义：
|
||
|
||
```
|
||
管理员: "以后每天早上8点帮我巡检所有生产服务器，检查CPU、内存、磁盘用量。
|
||
如果磁盘超过85%，自动清理超过7天的日志。
|
||
如果超过95%，马上电话通知我。
|
||
其他异常发短信就行。"
|
||
|
||
Agent: "收到。让我确认一下您的要求：
|
||
|
||
📋 驻留指令：每日生产环境巡检
|
||
⏰ 触发方式：每天 08:00（cron: 0 8 * * *）
|
||
🎯 目标范围：所有 environment=prod 的服务器
|
||
|
||
📌 自治操作（Agent 可自主执行）：
|
||
├─ 检查 CPU / 内存 / 磁盘使用率
|
||
└─ 磁盘 > 85%：自动清理 7 天前的日志
|
||
|
||
🚨 升级策略：
|
||
├─ 磁盘 > 95%：立即语音电话通知
|
||
└─ 其他异常：短信通知
|
||
|
||
⚠️ 决策边界（Agent 不会自主执行的操作）：
|
||
├─ ❌ 不会重启任何服务
|
||
├─ ❌ 不会修改任何配置文件
|
||
└─ ❌ 不会删除非日志文件
|
||
|
||
是否确认创建？"
|
||
|
||
管理员: "确认。另外如果CPU持续超过90%超过10分钟，也给我打电话。"
|
||
|
||
Agent: "已更新。追加条件：
|
||
├─ CPU > 90% 持续 10 分钟：语音电话通知
|
||
|
||
✅ 驻留指令已创建，将从明天 08:00 开始执行。
|
||
指令ID: SO-20260208-001"
|
||
```
|
||
|
||
**指令提取流程（agent-service 内部）**：
|
||
|
||
```typescript
|
||
// domain/services/standing-order-extractor.ts
|
||
|
||
/**
|
||
* 从对话中提取驻留指令的领域服务
|
||
*
|
||
* 流程：
|
||
* 1. 对话进行中，Agent 检测到用户意图是「定义持续性任务」
|
||
* 2. Agent 切换到指令提取模式（System Prompt 追加指令提取 schema）
|
||
* 3. Agent 生成结构化的指令草案（JSON）
|
||
* 4. 草案经人类确认后持久化为 StandingOrder
|
||
* 5. 后续对话修改可增量更新现有指令
|
||
*
|
||
* 关键：Agent 的 System Prompt 中包含 StandingOrder JSON Schema，
|
||
* 使 Agent 输出符合格式的指令定义，而非自由文本。
|
||
*/
|
||
export class StandingOrderExtractorService {
|
||
/**
|
||
* 检测对话意图是否为「定义任务」
|
||
* 关键词：以后、每天、定时、自动、帮我...检查/清理/巡检...
|
||
*/
|
||
detectTaskDefinitionIntent(message: string): boolean;
|
||
|
||
/**
|
||
* 将 Agent 的结构化输出解析为 StandingOrder 草案
|
||
*/
|
||
parseOrderDraft(agentOutput: string): StandingOrderDraft;
|
||
|
||
/**
|
||
* 人类确认后，将草案转为正式驻留指令
|
||
*/
|
||
confirmOrder(draft: StandingOrderDraft, userId: string): StandingOrder;
|
||
}
|
||
```
|
||
|
||
#### 3.8.3 驻留指令实体（跨 agent-service + ops-service）
|
||
|
||
```typescript
|
||
// ops-service/domain/entities/standing-order.entity.ts
|
||
|
||
export class StandingOrder {
|
||
id: string; // SO-{date}-{seq}
|
||
tenantId: string;
|
||
name: string; // "每日生产巡检"
|
||
description: string; // 自然语言描述
|
||
|
||
/** 定义此指令的对话会话ID（溯源） */
|
||
definedInSessionId: string;
|
||
|
||
/** ── 触发方式 ── */
|
||
trigger: {
|
||
type: 'cron' | 'event' | 'threshold' | 'manual';
|
||
cronExpression?: string; // "0 8 * * *"
|
||
eventType?: string; // 'alert_fired' | 'deployment_completed'
|
||
thresholdCondition?: { // 指标阈值触发
|
||
metricType: string;
|
||
operator: '>' | '<' | '==' | '>=';
|
||
value: number;
|
||
durationSeconds: number; // 持续时间
|
||
};
|
||
};
|
||
|
||
/** ── 目标范围 ── */
|
||
targets: {
|
||
serverIds?: string[]; // 指定服务器
|
||
clusterIds?: string[]; // 指定集群
|
||
allServers?: boolean; // 所有服务器
|
||
environmentFilter?: string[]; // ['prod'] 只在生产环境
|
||
tagFilter?: Record<string, string>; // 按标签筛选
|
||
};
|
||
|
||
/** ── Agent 执行指令 ── */
|
||
agentInstructions: {
|
||
prompt: string; // 结构化的执行指令（从对话提取）
|
||
skills?: string[]; // 使用的 Skills
|
||
runbookId?: string; // 关联的 Runbook（可选）
|
||
maxRiskLevel: 0 | 1; // 自治执行允许的最高风险等级（0=只读，1=低风险写入）
|
||
maxTurns: number; // Agent 最大对话轮次
|
||
maxBudgetUsd?: number; // 单次执行预算上限
|
||
};
|
||
|
||
/** ── 决策边界（Agent 自治范围）── */
|
||
decisionBoundary: {
|
||
/** 可自动执行的操作白名单 */
|
||
allowedActions: string[]; // ['cleanup_logs', 'report_metrics']
|
||
/** 必须升级给人类的情况 */
|
||
escalateConditions: string[]; // ['disk_full', 'service_down', 'data_loss_risk']
|
||
/** 各阈值的通知方式 */
|
||
escalationRules: Array<{
|
||
condition: string; // "disk_usage > 95%" 或 "cpu > 90% for 10min"
|
||
channel: 'voice_call' | 'im' | 'sms' | 'push' | 'email';
|
||
priority: 'urgent' | 'high' | 'normal' | 'low';
|
||
}>;
|
||
};
|
||
|
||
/** ── 升级策略 ── */
|
||
escalationPolicyId: string; // 关联的 comm-service 升级策略
|
||
|
||
/** ── 生命周期 ── */
|
||
status: 'active' | 'paused' | 'archived';
|
||
validFrom: Date;
|
||
validUntil?: Date; // 可选过期时间
|
||
createdBy: string;
|
||
lastModifiedInSessionId?: string; // 最后修改此指令的对话ID
|
||
createdAt: Date;
|
||
updatedAt: Date;
|
||
}
|
||
```
|
||
|
||
#### 3.8.4 自治执行引擎（ops-service + agent-service 协作）
|
||
|
||
```typescript
|
||
// ops-service/infrastructure/schedulers/standing-order-executor.service.ts
|
||
|
||
/**
|
||
* 驻留指令执行引擎
|
||
*
|
||
* 职责：
|
||
* 1. 根据触发条件（cron/event/threshold）启动执行
|
||
* 2. 创建「无人值守会话」（headless session）
|
||
* 3. 在 Agent 的决策边界内自主运行
|
||
* 4. 记录所有操作到审计日志
|
||
* 5. 遇到边界外情况 → 触发智能升级
|
||
*/
|
||
@Injectable()
|
||
export class StandingOrderExecutorService {
|
||
constructor(
|
||
private readonly orderRepo: StandingOrderRepository,
|
||
private readonly agentClient: AgentClientPort,
|
||
private readonly commClient: CommClientPort,
|
||
private readonly auditLogger: AuditLoggerPort,
|
||
) {}
|
||
|
||
/**
|
||
* Cron 触发：Bull Queue 定时任务调度
|
||
* 每分钟扫描所有 active 的 cron 型驻留指令，匹配到期的加入执行队列
|
||
*/
|
||
@Cron('* * * * *')
|
||
async scanCronOrders(): Promise<void> {
|
||
const dueOrders = await this.orderRepo.findDueCronOrders();
|
||
for (const order of dueOrders) {
|
||
await this.executionQueue.add('execute-standing-order', {
|
||
orderId: order.id,
|
||
triggerType: 'cron',
|
||
triggeredAt: new Date(),
|
||
});
|
||
}
|
||
}
|
||
|
||
/**
|
||
* 事件触发：监听 Redis Streams 事件
|
||
* alert_fired / deployment_completed 等事件匹配 event 型驻留指令
|
||
*/
|
||
@OnEvent('alert.fired')
|
||
async onAlertFired(event: AlertEvent): Promise<void> {
|
||
const matchingOrders = await this.orderRepo.findByEventTrigger('alert_fired');
|
||
for (const order of matchingOrders) {
|
||
if (this.matchesTargets(order, event.serverId)) {
|
||
await this.executeOrder(order, { triggerEvent: event });
|
||
}
|
||
}
|
||
}
|
||
|
||
/**
|
||
* 核心执行逻辑
|
||
*/
|
||
async executeOrder(order: StandingOrder, context: ExecutionContext): Promise<void> {
|
||
// 1. 创建无人值守执行记录
|
||
const execution = await this.createExecution(order);
|
||
|
||
// 2. 构建 Agent 任务参数（注入决策边界到 System Prompt）
|
||
const taskParams = this.buildTaskParams(order, context);
|
||
|
||
// 3. 调用 agent-service 执行（gRPC 流式调用）
|
||
try {
|
||
for await (const event of this.agentClient.executeTask(taskParams)) {
|
||
// 记录每一步操作
|
||
await this.auditLogger.log({
|
||
actionType: 'standing_order_step',
|
||
orderId: order.id,
|
||
executionId: execution.id,
|
||
detail: event,
|
||
});
|
||
|
||
// 4. 检查是否触发升级条件
|
||
if (event.type === 'approval_required') {
|
||
await this.handleEscalation(order, execution, event);
|
||
}
|
||
|
||
// 5. 检查自定义升级规则
|
||
if (this.matchesEscalationRule(order, event)) {
|
||
await this.triggerCustomEscalation(order, execution, event);
|
||
}
|
||
}
|
||
|
||
execution.status = 'completed';
|
||
} catch (error) {
|
||
execution.status = 'failed';
|
||
execution.error = error.message;
|
||
// 执行失败也要通知
|
||
await this.notifyExecutionFailure(order, execution, error);
|
||
}
|
||
|
||
await this.orderRepo.saveExecution(execution);
|
||
}
|
||
|
||
/**
|
||
* 构建 Agent 任务参数
|
||
* 关键：将决策边界注入到 System Prompt 中，约束 Agent 行为
|
||
*/
|
||
private buildTaskParams(order: StandingOrder, ctx: ExecutionContext): EngineTaskParams {
|
||
const boundaryPrompt = `
|
||
## 驻留指令执行模式
|
||
|
||
你正在执行驻留指令「${order.name}」（ID: ${order.id}）。
|
||
这是一次**无人值守的自治执行**，请严格遵守以下边界：
|
||
|
||
### 允许的操作（可自主执行）
|
||
${order.decisionBoundary.allowedActions.map(a => `- ${a}`).join('\n')}
|
||
|
||
### 禁止的操作（必须停止并请求人工干预）
|
||
${order.decisionBoundary.escalateConditions.map(c => `- 遇到「${c}」→ 立即停止，输出 ESCALATION_REQUIRED`).join('\n')}
|
||
|
||
### 最高风险等级限制
|
||
仅允许执行风险等级 ≤ ${order.agentInstructions.maxRiskLevel} 的命令。
|
||
遇到更高风险的命令，输出 ESCALATION_REQUIRED 并说明原因。
|
||
|
||
### 执行目标
|
||
${JSON.stringify(order.targets, null, 2)}
|
||
`;
|
||
|
||
return {
|
||
sessionId: `so-${order.id}-${Date.now()}`,
|
||
prompt: order.agentInstructions.prompt,
|
||
systemPrompt: boundaryPrompt,
|
||
allowedTools: this.resolveAllowedTools(order),
|
||
maxTurns: order.agentInstructions.maxTurns,
|
||
maxBudgetUsd: order.agentInstructions.maxBudgetUsd,
|
||
context: {
|
||
standingOrderId: order.id,
|
||
triggerContext: ctx,
|
||
isHeadless: true, // 标记为无人值守模式
|
||
},
|
||
};
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 3.8.5 智能升级（Smart Escalation）
|
||
|
||
当 Agent 在自治执行中遇到超出决策边界的情况时，按以下**三层递进**流程升级：
|
||
|
||
```
|
||
Agent 执行中检测到异常
|
||
│
|
||
├── 匹配驻留指令中的 escalationRules
|
||
│ ├── condition: "disk_usage > 95%" → priority: urgent
|
||
│ ├── condition: "cpu > 90% for 10min" → priority: urgent
|
||
│ └── condition: "other_anomaly" → priority: normal
|
||
│
|
||
├── 如果无具体规则匹配 → 使用驻留指令关联的 escalationPolicy
|
||
│
|
||
└── 三层递进升级
|
||
│
|
||
├── ⏱ 第一层：唤醒管理员
|
||
│ ├── ① App 推送（WebSocket + FCM）→ 全屏通知卡片
|
||
│ │ └── 管理员打开 App →「语音对话」→ Pipecat WebSocket 语音对话
|
||
│ │ Agent 语音汇报 + 听取指示（支持打断）
|
||
│ │
|
||
│ ├── ② 2分钟无响应 → Pipecat 通过 Twilio 拨出电话
|
||
│ │ 管理员接听 → Agent 直接开口说话（无 IVR 菜单）：
|
||
│ │ "您好，我是 IT0 Agent。prod-2 磁盘使用率 97%，
|
||
│ │ 我建议清理 /var/log 下超过7天的日志。您同意吗？"
|
||
│ │ 管理员语音回复 → Agent 理解并执行
|
||
│ │ （与 App 内语音对话使用同一 Pipecat 引擎）
|
||
│ │
|
||
│ └── 管理员通过任意渠道回复后 → SmartEscalationService.onHumanResponse()
|
||
│
|
||
├── ⏱ 第二层：扩大通知范围（5 分钟内仍无响应）
|
||
│ ├── IM 消息（Telegram/企业微信）：
|
||
│ │ 结构化消息 + 操作按钮（批准/拒绝/查看详情）
|
||
│ ├── 短信（简要描述 + 回复 Y/N 审批）
|
||
│ └── 通知备用联系人（重复第一层流程）
|
||
│
|
||
└── ⏱ 第三层：全渠道通知（10+ 分钟无响应）
|
||
├── 邮件：完整报告（日志摘录、指标图表、操作链接）
|
||
└── 通知管理组所有成员
|
||
```
|
||
|
||
```typescript
|
||
// ops-service/domain/services/smart-escalation.service.ts
|
||
|
||
export class SmartEscalationService {
|
||
constructor(
|
||
private readonly commClient: CommClientPort,
|
||
private readonly voiceClient: VoiceServiceClientPort, // ★ voice-service 客户端
|
||
private readonly agentClient: AgentClientPort,
|
||
private readonly orderRepo: StandingOrderRepository,
|
||
private readonly execRepo: StandingOrderExecutionRepository,
|
||
) {}
|
||
|
||
/**
|
||
* 根据驻留指令的升级规则 + 当前事件，决定通知渠道和内容
|
||
*/
|
||
async escalate(
|
||
order: StandingOrder,
|
||
execution: StandingOrderExecution,
|
||
event: EngineStreamEvent,
|
||
): Promise<void> {
|
||
const rule = this.matchRule(order.decisionBoundary.escalationRules, event);
|
||
const notification = this.buildNotification(order, execution, event, rule);
|
||
|
||
// 1. 第一层：App 推送 + 语音对话预备
|
||
await this.commClient.send({
|
||
tenantId: order.tenantId,
|
||
channel: 'push', // 推送到 App
|
||
priority: rule?.priority ?? 'normal',
|
||
content: notification,
|
||
callbackContext: {
|
||
executionId: execution.id,
|
||
orderId: order.id,
|
||
awaitingAction: 'approve_or_reject',
|
||
},
|
||
});
|
||
|
||
// 2. 预创建语音对话会话（用户打开 App 时可立即接入）
|
||
const voiceSession = await this.voiceClient.prepareSession({
|
||
executionId: execution.id,
|
||
agentContext: {
|
||
orderId: order.id,
|
||
orderName: order.name,
|
||
eventSummary: event.summary,
|
||
sessionId: execution.sessionId,
|
||
},
|
||
});
|
||
|
||
// 3. 启动超时升级调度
|
||
await this.scheduleEscalationChain(execution, rule, voiceSession);
|
||
|
||
// 4. 暂停执行，等待人类响应
|
||
execution.status = 'awaiting_human';
|
||
execution.escalatedAt = new Date();
|
||
execution.escalationChannel = 'push'; // 初始渠道
|
||
}
|
||
|
||
/**
|
||
* 超时升级链：App推送 → 电话唤醒 → IM/短信 → 备用联系人 → 邮件/管理组
|
||
*/
|
||
private async scheduleEscalationChain(
|
||
execution: StandingOrderExecution,
|
||
rule: EscalationRule | null,
|
||
voiceSession: VoiceSessionInfo,
|
||
) {
|
||
const chain = [
|
||
{ delay: 2 * 60_000, action: 'pipecat_phone_call', params: { voiceSessionId: voiceSession.id } },
|
||
{ delay: 5 * 60_000, action: 'im_and_sms' },
|
||
{ delay: 10 * 60_000, action: 'backup_contacts' },
|
||
{ delay: 20 * 60_000, action: 'email_management_group' },
|
||
];
|
||
|
||
// 使用 Bull Queue 延迟任务实现，每一步检查是否已有响应
|
||
for (const step of chain) {
|
||
await this.escalationQueue.add('escalation-step', {
|
||
executionId: execution.id,
|
||
...step,
|
||
}, { delay: step.delay });
|
||
}
|
||
}
|
||
|
||
/**
|
||
* 人类响应回调（通过任何渠道回复后触发）
|
||
* - App 内语音对话 → voice-service 回调
|
||
* - Pipecat 电话语音对话 → voice-service 回调（同一引擎）
|
||
* - IM 按钮/文字 → comm-service 回调
|
||
* - 短信回复 → comm-service 回调
|
||
*/
|
||
async onHumanResponse(
|
||
executionId: string,
|
||
response: HumanResponse,
|
||
): Promise<void> {
|
||
const execution = await this.execRepo.findById(executionId);
|
||
|
||
// 取消后续升级链（人已响应）
|
||
await this.escalationQueue.removeByExecutionId(executionId);
|
||
|
||
if (response.action === 'approve') {
|
||
await this.agentClient.continueSession(execution.sessionId,
|
||
`人工审批已通过。操作者: ${response.respondedBy}，渠道: ${response.channel}。继续执行。`
|
||
);
|
||
execution.status = 'running';
|
||
} else if (response.action === 'reject') {
|
||
await this.agentClient.cancelTask(execution.sessionId);
|
||
execution.status = 'aborted_by_human';
|
||
} else if (response.action === 'instruct') {
|
||
// 人类通过语音或文字给出详细指示
|
||
await this.agentClient.continueSession(execution.sessionId,
|
||
`管理员指示（${response.channel}）：${response.instruction}`
|
||
);
|
||
execution.status = 'running';
|
||
}
|
||
|
||
execution.humanResponse = response;
|
||
execution.respondedBy = response.respondedBy;
|
||
execution.respondedAt = new Date();
|
||
}
|
||
}
|
||
```
|
||
|
||
**Pipecat 主动拨号**（voice-service 通过 Twilio REST API 发起电话）：
|
||
```python
|
||
# voice-service — 主动拨出电话
|
||
# app/services/outbound_call_service.py
|
||
|
||
from twilio.rest import Client as TwilioClient
|
||
|
||
class OutboundCallService:
|
||
"""
|
||
当 App 推送 2 分钟无响应时，SmartEscalationService 调用此服务
|
||
→ Pipecat 通过 Twilio 拨出电话
|
||
→ 管理员接听后 Pipecat 直接开始语音对话（无 IVR 菜单）
|
||
"""
|
||
|
||
async def initiate_call(
|
||
self,
|
||
phone_number: str,
|
||
voice_session_id: str, # 预创建的语音会话 ID
|
||
agent_context: dict, # 驻留指令上下文
|
||
):
|
||
# 1. Twilio 拨出电话，接通后连接到 Pipecat Media Streams
|
||
call = self.twilio_client.calls.create(
|
||
to=phone_number,
|
||
from_=self.twilio_phone_number,
|
||
twiml=f'''
|
||
<Response>
|
||
<Connect>
|
||
<Stream url="wss://{self.host}/twilio-stream/{voice_session_id}" />
|
||
</Connect>
|
||
</Response>
|
||
''',
|
||
)
|
||
|
||
# 2. Pipecat Pipeline 在 Media Streams 连接时自动启动
|
||
# Agent 接通即开口说话："您好，我是 IT0 Agent..."
|
||
# 无需任何 IVR 菜单或按键操作
|
||
return call.sid
|
||
```
|
||
|
||
```typescript
|
||
// comm-service — 触发 Pipecat 拨号
|
||
// SmartEscalationService 在 2 分钟超时后调用
|
||
|
||
async function triggerPipecatCall(
|
||
voiceSessionId: string,
|
||
contact: Contact,
|
||
) {
|
||
// 调用 voice-service API，让 Pipecat 拨出电话
|
||
await this.voiceClient.initiateCall({
|
||
phoneNumber: contact.phone,
|
||
voiceSessionId,
|
||
// Pipecat 接通后 Agent 直接开口说话
|
||
// 使用与 App 内完全相同的 Pipeline
|
||
});
|
||
}
|
||
```
|
||
|
||
#### 3.8.6 对话修改驻留指令
|
||
|
||
管理员可以随时通过对话修改已有的驻留指令：
|
||
|
||
```
|
||
管理员: "把每日巡检的时间改成早上7点，另外磁盘清理阈值从85%降到80%。"
|
||
|
||
Agent: "已更新驻留指令 SO-20260208-001：
|
||
├─ ⏰ 触发时间：08:00 → 07:00（cron: 0 7 * * *）
|
||
└─ 📌 磁盘清理阈值：85% → 80%
|
||
|
||
其他配置保持不变。变更已生效。"
|
||
|
||
管理员: "暂停这个指令，我这周在做服务器迁移。"
|
||
|
||
Agent: "已暂停驻留指令 SO-20260208-001「每日生产巡检」。
|
||
⏸ 状态：active → paused
|
||
需要恢复时告诉我即可。"
|
||
```
|
||
|
||
**实现要点**：
|
||
- Agent System Prompt 中包含当前租户所有活跃的驻留指令列表
|
||
- Agent 检测到修改意图时，调用 `update_standing_order` tool
|
||
- 所有修改记录关联对话 session ID（完整溯源）
|
||
- 修改操作写入审计日志
|
||
|
||
#### 3.8.7 执行结果汇报
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ 驻留指令执行汇报方式 │
|
||
│ │
|
||
│ ┌───────────────────┐ │
|
||
│ │ 正常完成 │ → 静默记录审计日志 │
|
||
│ │（一切正常） │ 可在 Web Admin / Flutter 查看 │
|
||
│ └───────────────────┘ │
|
||
│ │
|
||
│ ┌───────────────────┐ │
|
||
│ │ 有发现但已自治处理 │ → 推送通知 + 执行摘要 │
|
||
│ │（如自动清理了日志） │ "已清理 prod-2 的 3.2GB 旧日志" │
|
||
│ └───────────────────┘ │
|
||
│ │
|
||
│ ┌───────────────────┐ │
|
||
│ │ 需人工决策 │ → 按 escalationRules 升级 │
|
||
│ │（超出决策边界） │ 电话/IM/短信/邮件 │
|
||
│ └───────────────────┘ │
|
||
│ │
|
||
│ ┌───────────────────┐ │
|
||
│ │ 执行失败 │ → 立即推送 + 短信 │
|
||
│ │（Agent 异常/超时） │ 含错误详情和建议 │
|
||
│ └───────────────────┘ │
|
||
│ │
|
||
│ ── 日报/周报 ── │
|
||
│ 每日 20:00 汇总当天所有驻留指令执行情况 │
|
||
│ 推送到 Flutter App / 邮件 │
|
||
└─────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
#### 3.8.8 相关 Tools（agent-service 注册的工具）
|
||
|
||
```typescript
|
||
// agent-service 的 tool 定义（供 Agent 调用）
|
||
|
||
const standingOrderTools = [
|
||
{
|
||
name: 'create_standing_order',
|
||
description: '创建新的驻留指令（当用户要求定义持续性/定时任务时使用）',
|
||
input_schema: { /* StandingOrderDraft JSON Schema */ },
|
||
},
|
||
{
|
||
name: 'update_standing_order',
|
||
description: '修改已有的驻留指令（当用户要求调整任务参数时使用）',
|
||
input_schema: {
|
||
orderId: { type: 'string' },
|
||
changes: { /* 部分更新的字段 */ },
|
||
},
|
||
},
|
||
{
|
||
name: 'pause_standing_order',
|
||
description: '暂停驻留指令（用户要求暂停某个定时任务时使用）',
|
||
input_schema: { orderId: { type: 'string' } },
|
||
},
|
||
{
|
||
name: 'resume_standing_order',
|
||
description: '恢复已暂停的驻留指令',
|
||
input_schema: { orderId: { type: 'string' } },
|
||
},
|
||
{
|
||
name: 'list_standing_orders',
|
||
description: '列出当前所有驻留指令及其状态',
|
||
input_schema: { statusFilter: { type: 'string', enum: ['active', 'paused', 'all'] } },
|
||
},
|
||
{
|
||
name: 'report_escalation',
|
||
description: '无人值守执行中遇到超出决策边界的情况，请求人工干预',
|
||
input_schema: {
|
||
severity: { type: 'string', enum: ['fatal', 'critical', 'warning', 'info'] },
|
||
situation: { type: 'string', description: '当前状况描述' },
|
||
suggestedAction: { type: 'string', description: 'Agent 建议的操作' },
|
||
requiresImmediate: { type: 'boolean' },
|
||
},
|
||
},
|
||
];
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 数据库设计（PostgreSQL）
|
||
|
||
> **多租户说明**：根据 §7 的 Schema-per-Tenant 策略，以下业务表存在于每个租户的独立 Schema（`it0_t_{tenantId}`）中。
|
||
> 所有表额外包含 `tenant_id` 列作为**防御性纵深**——即使 Schema 隔离失败，行级 `tenant_id` 仍可防止数据泄露。
|
||
> 公共管理表（`tenants`, `plans` 等）位于 `it0_shared` Schema，参见 §7.5。
|
||
|
||
### 4.1 agent-service — `it0_agent` schema
|
||
|
||
```sql
|
||
-- 智能体会话
|
||
CREATE TABLE agent_sessions (
|
||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||
tenant_id VARCHAR(20) NOT NULL, -- ★ 防御性纵深：冗余租户标识
|
||
engine_type VARCHAR(20) NOT NULL, -- 'claude_code_cli' | 'claude_api' | 'custom'
|
||
status VARCHAR(20) NOT NULL DEFAULT 'active',
|
||
system_prompt TEXT,
|
||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||
metadata JSONB DEFAULT '{}'
|
||
);
|
||
|
||
-- 命令执行记录
|
||
CREATE TABLE command_records (
|
||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||
tenant_id VARCHAR(20) NOT NULL,
|
||
session_id UUID NOT NULL REFERENCES agent_sessions(id),
|
||
command TEXT NOT NULL,
|
||
risk_level SMALLINT NOT NULL DEFAULT 0, -- 0-3
|
||
status VARCHAR(20) NOT NULL, -- 'executed' | 'blocked' | 'approved' | 'rejected'
|
||
output TEXT,
|
||
error TEXT,
|
||
approved_by UUID, -- 审批人
|
||
executed_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||
duration_ms INTEGER
|
||
);
|
||
|
||
CREATE INDEX idx_command_records_session ON command_records(session_id);
|
||
CREATE INDEX idx_command_records_risk ON command_records(risk_level) WHERE risk_level >= 2;
|
||
```
|
||
|
||
### 4.2 ops-service — `it0_ops` schema
|
||
|
||
```sql
|
||
-- 运维任务
|
||
CREATE TABLE ops_tasks (
|
||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||
tenant_id VARCHAR(20) NOT NULL,
|
||
type VARCHAR(30) NOT NULL, -- 'inspection' | 'deployment' | 'rollback' | 'scaling' | 'recovery'
|
||
title VARCHAR(200) NOT NULL,
|
||
description TEXT,
|
||
status VARCHAR(20) NOT NULL DEFAULT 'pending',
|
||
priority SMALLINT NOT NULL DEFAULT 1,
|
||
target_servers UUID[] NOT NULL, -- 目标服务器 ID 列表
|
||
runbook_id UUID,
|
||
agent_session_id UUID,
|
||
created_by UUID NOT NULL,
|
||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||
completed_at TIMESTAMPTZ,
|
||
result_summary TEXT
|
||
);
|
||
|
||
-- 审批请求
|
||
CREATE TABLE approval_requests (
|
||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||
tenant_id VARCHAR(20) NOT NULL,
|
||
task_id UUID NOT NULL REFERENCES ops_tasks(id),
|
||
command TEXT NOT NULL,
|
||
risk_level SMALLINT NOT NULL,
|
||
status VARCHAR(20) NOT NULL DEFAULT 'pending',
|
||
decided_by UUID,
|
||
decided_at TIMESTAMPTZ,
|
||
reason TEXT,
|
||
expires_at TIMESTAMPTZ NOT NULL,
|
||
notification_channels VARCHAR(20)[] -- 已通知的渠道
|
||
);
|
||
|
||
-- 运维手册（Runbook）
|
||
CREATE TABLE runbooks (
|
||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||
tenant_id VARCHAR(20) NOT NULL,
|
||
name VARCHAR(200) NOT NULL,
|
||
description TEXT,
|
||
trigger_type VARCHAR(30), -- 'manual' | 'alert' | 'schedule'
|
||
prompt_template TEXT NOT NULL, -- Agent 执行的 prompt 模板
|
||
allowed_tools VARCHAR(50)[] NOT NULL,
|
||
max_risk_level SMALLINT NOT NULL DEFAULT 1, -- 此 Runbook 允许的最高风险等级
|
||
auto_approve BOOLEAN NOT NULL DEFAULT FALSE,
|
||
is_active BOOLEAN NOT NULL DEFAULT TRUE,
|
||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
|
||
);
|
||
|
||
-- ★ 驻留指令（Standing Orders）— 自治运维任务定义
|
||
CREATE TABLE standing_orders (
|
||
id VARCHAR(30) PRIMARY KEY, -- SO-{date}-{seq}
|
||
tenant_id VARCHAR(20) NOT NULL,
|
||
name VARCHAR(200) NOT NULL,
|
||
description TEXT,
|
||
-- 对话溯源
|
||
defined_in_session_id UUID NOT NULL, -- 定义此指令的对话ID
|
||
last_modified_in_session_id UUID, -- 最后修改的对话ID
|
||
-- 触发方式
|
||
trigger_type VARCHAR(20) NOT NULL, -- 'cron' | 'event' | 'threshold' | 'manual'
|
||
trigger_config JSONB NOT NULL, -- { cronExpression, eventType, thresholdCondition }
|
||
-- 目标范围
|
||
targets JSONB NOT NULL, -- { serverIds, clusterIds, allServers, environmentFilter, tagFilter }
|
||
-- Agent 执行参数
|
||
agent_prompt TEXT NOT NULL, -- 从对话提取的结构化执行指令
|
||
agent_skills VARCHAR(100)[], -- 使用的 Skills 名称列表
|
||
runbook_id UUID REFERENCES runbooks(id), -- 关联的 Runbook（可选）
|
||
max_risk_level SMALLINT NOT NULL DEFAULT 0, -- 自治执行最高风险等级（0=只读，1=低风险写入）
|
||
max_turns INTEGER NOT NULL DEFAULT 20,
|
||
max_budget_usd NUMERIC(6,2),
|
||
-- 决策边界
|
||
decision_boundary JSONB NOT NULL, -- { allowedActions, escalateConditions, escalationRules }
|
||
-- 升级策略
|
||
escalation_policy_id UUID,
|
||
-- 生命周期
|
||
status VARCHAR(20) NOT NULL DEFAULT 'active', -- 'active' | 'paused' | 'archived'
|
||
valid_from TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||
valid_until TIMESTAMPTZ,
|
||
-- 元信息
|
||
created_by UUID NOT NULL,
|
||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
|
||
);
|
||
|
||
CREATE INDEX idx_standing_orders_status ON standing_orders(status) WHERE status = 'active';
|
||
CREATE INDEX idx_standing_orders_trigger ON standing_orders(trigger_type);
|
||
|
||
-- 驻留指令执行记录
|
||
CREATE TABLE standing_order_executions (
|
||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||
tenant_id VARCHAR(20) NOT NULL,
|
||
order_id VARCHAR(30) NOT NULL REFERENCES standing_orders(id),
|
||
-- 触发信息
|
||
trigger_type VARCHAR(20) NOT NULL,
|
||
trigger_context JSONB, -- 触发上下文（告警事件、cron 时间等）
|
||
-- 执行状态
|
||
session_id VARCHAR(100), -- Agent 会话ID
|
||
status VARCHAR(20) NOT NULL DEFAULT 'running',
|
||
-- 'running' | 'completed' | 'failed' | 'awaiting_human' | 'aborted_by_human'
|
||
-- 结果
|
||
result_summary TEXT, -- Agent 执行摘要
|
||
actions_taken JSONB DEFAULT '[]', -- 执行的操作列表
|
||
error TEXT,
|
||
-- 升级信息
|
||
escalated_at TIMESTAMPTZ,
|
||
escalation_channel VARCHAR(20), -- 升级使用的渠道
|
||
human_response JSONB, -- 人类响应内容
|
||
responded_by UUID,
|
||
responded_at TIMESTAMPTZ,
|
||
-- 时间
|
||
started_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||
completed_at TIMESTAMPTZ,
|
||
duration_ms INTEGER
|
||
);
|
||
|
||
CREATE INDEX idx_so_executions_order ON standing_order_executions(order_id, started_at DESC);
|
||
CREATE INDEX idx_so_executions_status ON standing_order_executions(status) WHERE status IN ('running', 'awaiting_human');
|
||
```
|
||
|
||
### 4.3 inventory-service — `it0_inventory` schema
|
||
|
||
```sql
|
||
-- 服务器
|
||
CREATE TABLE servers (
|
||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||
tenant_id VARCHAR(20) NOT NULL,
|
||
name VARCHAR(100) NOT NULL UNIQUE,
|
||
host VARCHAR(255) NOT NULL, -- IP 或主机名（内网 IP 也可以）
|
||
port INTEGER NOT NULL DEFAULT 22,
|
||
environment VARCHAR(20) NOT NULL, -- 'dev' | 'staging' | 'prod'
|
||
role VARCHAR(30) NOT NULL, -- 'web' | 'db' | 'cache' | 'worker' | 'gateway'
|
||
cluster_id UUID REFERENCES clusters(id),
|
||
ssh_user VARCHAR(50) NOT NULL, -- SSH 登录用户名
|
||
credential_id UUID NOT NULL REFERENCES credentials(id), -- SSH 密钥或密码
|
||
-- ★ SSH ProxyJump 跳板机配置
|
||
network_type VARCHAR(20) NOT NULL DEFAULT 'public', -- 'public' | 'private'（内网需跳板机）
|
||
jump_server_id UUID REFERENCES servers(id), -- 跳板机（自引用，NULL=直连）
|
||
-- 额外 SSH 选项
|
||
ssh_options JSONB DEFAULT '{}', -- 自定义 SSH 参数，如 StrictHostKeyChecking 等
|
||
tags JSONB DEFAULT '{}',
|
||
status VARCHAR(20) NOT NULL DEFAULT 'active',
|
||
description TEXT,
|
||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
|
||
);
|
||
|
||
CREATE INDEX idx_servers_environment ON servers(environment);
|
||
CREATE INDEX idx_servers_cluster ON servers(cluster_id);
|
||
|
||
-- 集群
|
||
CREATE TABLE clusters (
|
||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||
tenant_id VARCHAR(20) NOT NULL,
|
||
name VARCHAR(100) NOT NULL UNIQUE,
|
||
type VARCHAR(20) NOT NULL, -- 'bare_metal' | 'k8s' | 'docker_swarm'
|
||
environment VARCHAR(20) NOT NULL,
|
||
description TEXT,
|
||
kubeconfig TEXT, -- 加密存储
|
||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
|
||
);
|
||
|
||
-- 凭证（加密存储）
|
||
CREATE TABLE credentials (
|
||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||
tenant_id VARCHAR(20) NOT NULL,
|
||
name VARCHAR(100) NOT NULL,
|
||
type VARCHAR(20) NOT NULL, -- 'ssh_key' | 'ssh_password' | 'token' | 'kubeconfig'
|
||
encrypted_value BYTEA NOT NULL, -- AES-256-GCM 加密
|
||
iv BYTEA NOT NULL,
|
||
-- 元信息（非敏感）
|
||
fingerprint VARCHAR(100), -- SSH key 指纹（用于展示，不含私钥）
|
||
key_type VARCHAR(20), -- 'rsa' | 'ed25519' | 'ecdsa'（仅 ssh_key 类型）
|
||
created_by UUID,
|
||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||
expires_at TIMESTAMPTZ,
|
||
last_used_at TIMESTAMPTZ
|
||
);
|
||
|
||
/**
|
||
* SSH 连接构建逻辑（agent-service 中实现）：
|
||
*
|
||
* 1. 查询目标服务器：server = getServer(serverId)
|
||
* 2. 查询凭证：credential = getCredential(server.credential_id)
|
||
* 3. 判断连接方式：
|
||
*
|
||
* A) 直连（network_type = 'public' 或 jump_server_id = NULL）：
|
||
* ssh -i /tmp/key_{uuid} -p {port} {ssh_user}@{host}
|
||
*
|
||
* B) 跳板机（network_type = 'private' 且 jump_server_id != NULL）：
|
||
* jumpServer = getServer(server.jump_server_id)
|
||
* jumpCred = getCredential(jumpServer.credential_id)
|
||
* ssh -J {jump_user}@{jump_host}:{jump_port} -i /tmp/key_{uuid} -p {port} {ssh_user}@{host}
|
||
*
|
||
* C) 多级跳板（jump_server 自身也有 jump_server_id）：
|
||
* 递归构建 ProxyJump 链：ssh -J jump1,jump2 target
|
||
*
|
||
* 4. 凭证通过临时文件注入（TTL=5min，用后删除）
|
||
* 5. 额外 SSH 选项从 server.ssh_options 读取
|
||
*/
|
||
```
|
||
|
||
### 4.4 monitor-service — `it0_monitor` schema
|
||
|
||
```sql
|
||
-- 告警规则
|
||
CREATE TABLE alert_rules (
|
||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||
tenant_id VARCHAR(20) NOT NULL,
|
||
name VARCHAR(200) NOT NULL,
|
||
metric_type VARCHAR(30) NOT NULL, -- 'cpu' | 'memory' | 'disk' | 'network' | 'custom'
|
||
condition JSONB NOT NULL, -- { "operator": ">", "threshold": 90, "duration_seconds": 300 }
|
||
severity VARCHAR(20) NOT NULL, -- 'info' | 'warning' | 'critical' | 'fatal'
|
||
target_servers UUID[], -- NULL = 所有服务器
|
||
runbook_id UUID, -- 自动修复关联的 Runbook
|
||
is_active BOOLEAN NOT NULL DEFAULT TRUE,
|
||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
|
||
);
|
||
|
||
-- 告警事件
|
||
CREATE TABLE alert_events (
|
||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||
tenant_id VARCHAR(20) NOT NULL,
|
||
rule_id UUID NOT NULL REFERENCES alert_rules(id),
|
||
server_id UUID NOT NULL,
|
||
severity VARCHAR(20) NOT NULL,
|
||
message TEXT NOT NULL,
|
||
metric_value DOUBLE PRECISION,
|
||
status VARCHAR(20) NOT NULL DEFAULT 'firing', -- 'firing' | 'resolved' | 'acknowledged'
|
||
fired_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||
resolved_at TIMESTAMPTZ,
|
||
acknowledged_by UUID
|
||
);
|
||
|
||
-- 指标快照（时序数据，定期归档）
|
||
CREATE TABLE metric_snapshots (
|
||
id BIGSERIAL PRIMARY KEY,
|
||
tenant_id VARCHAR(20) NOT NULL,
|
||
server_id UUID NOT NULL,
|
||
metric_type VARCHAR(30) NOT NULL,
|
||
value DOUBLE PRECISION NOT NULL,
|
||
recorded_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
|
||
);
|
||
|
||
-- 分区表优化（按月）
|
||
-- CREATE TABLE metric_snapshots_2026_02 PARTITION OF metric_snapshots
|
||
-- FOR VALUES FROM ('2026-02-01') TO ('2026-03-01');
|
||
```
|
||
|
||
### 4.5 comm-service — `it0_comm` schema
|
||
|
||
```sql
|
||
-- 联系人
|
||
CREATE TABLE contacts (
|
||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||
tenant_id VARCHAR(20) NOT NULL,
|
||
user_id UUID NOT NULL,
|
||
name VARCHAR(100) NOT NULL,
|
||
phone VARCHAR(20), -- 短信/电话
|
||
email VARCHAR(200),
|
||
telegram_id VARCHAR(100),
|
||
wechat_id VARCHAR(100),
|
||
preferred_channel VARCHAR(20) NOT NULL DEFAULT 'websocket',
|
||
is_active BOOLEAN NOT NULL DEFAULT TRUE
|
||
);
|
||
|
||
-- 消息记录
|
||
CREATE TABLE messages (
|
||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||
tenant_id VARCHAR(20) NOT NULL,
|
||
contact_id UUID NOT NULL REFERENCES contacts(id),
|
||
channel_type VARCHAR(20) NOT NULL,
|
||
direction VARCHAR(10) NOT NULL, -- 'outbound' | 'inbound'
|
||
content TEXT NOT NULL,
|
||
priority VARCHAR(10) NOT NULL DEFAULT 'normal',
|
||
delivery_status VARCHAR(20) NOT NULL DEFAULT 'pending',
|
||
related_task_id UUID, -- 关联的运维任务
|
||
sent_at TIMESTAMPTZ,
|
||
delivered_at TIMESTAMPTZ,
|
||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
|
||
);
|
||
|
||
-- 升级策略
|
||
CREATE TABLE escalation_policies (
|
||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||
tenant_id VARCHAR(20) NOT NULL,
|
||
name VARCHAR(100) NOT NULL,
|
||
severity VARCHAR(20) NOT NULL, -- 匹配告警级别
|
||
steps JSONB NOT NULL, -- [{"delay_seconds": 0, "channel": "websocket"}, {"delay_seconds": 120, "channel": "sms"}, ...]
|
||
is_default BOOLEAN NOT NULL DEFAULT FALSE
|
||
);
|
||
```
|
||
|
||
### 4.6 audit-service — `it0_audit` schema
|
||
|
||
```sql
|
||
-- 审计日志（只追加，不可修改/删除）
|
||
CREATE TABLE audit_logs (
|
||
id BIGSERIAL PRIMARY KEY,
|
||
tenant_id VARCHAR(20) NOT NULL,
|
||
action_type VARCHAR(50) NOT NULL, -- 'command_executed' | 'approval_decided' | 'engine_switched' | etc.
|
||
actor_type VARCHAR(20) NOT NULL, -- 'agent' | 'user' | 'system'
|
||
actor_id VARCHAR(100),
|
||
resource_type VARCHAR(50), -- 'server' | 'task' | 'session'
|
||
resource_id VARCHAR(100),
|
||
detail JSONB NOT NULL,
|
||
ip_address INET,
|
||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
|
||
);
|
||
|
||
-- 性能索引
|
||
CREATE INDEX idx_audit_logs_action ON audit_logs(action_type, created_at);
|
||
CREATE INDEX idx_audit_logs_actor ON audit_logs(actor_id, created_at);
|
||
CREATE INDEX idx_audit_logs_resource ON audit_logs(resource_type, resource_id);
|
||
|
||
-- 防篡改：REVOKE DELETE, UPDATE ON audit_logs FROM app_user;
|
||
```
|
||
|
||
---
|
||
|
||
## 5. 服务间通信
|
||
|
||
### 5.1 通信矩阵
|
||
|
||
```
|
||
┌─────────────────────────────────────────────┐
|
||
│ 事件总线 (Redis Streams) │
|
||
└──┬────┬────┬────┬────┬────┬────┬────────────┘
|
||
│ │ │ │ │ │ │
|
||
┌────┴─┐ ┌┴────┐ ┌─┴──┐ ┌┴───┐ ┌─┴──┐ ┌──┴──┐
|
||
│auth │ │agent│ │ops │ │inv │ │mon │ │comm │
|
||
└──────┘ └──┬──┘ └─┬──┘ └────┘ └──┬─┘ └─────┘
|
||
│ │ │
|
||
gRPC 同步调用: │
|
||
ops → agent (执行任务) │
|
||
agent → inv (获取凭证) │
|
||
mon → ops (触发自动修复) ───────────┘
|
||
ops → comm (通知人类)
|
||
```
|
||
|
||
### 5.2 关键事件流
|
||
|
||
```typescript
|
||
// 事件定义（所有服务共享的 proto/event 包）
|
||
|
||
// agent-service 发布
|
||
interface CommandExecutedEvent {
|
||
sessionId: string;
|
||
command: string;
|
||
riskLevel: number;
|
||
output: string;
|
||
timestamp: Date;
|
||
}
|
||
|
||
interface ApprovalRequiredEvent {
|
||
taskId: string;
|
||
command: string;
|
||
riskLevel: number;
|
||
targetServer: string;
|
||
expiresAt: Date;
|
||
}
|
||
|
||
// monitor-service 发布
|
||
interface AlertFiredEvent {
|
||
ruleId: string;
|
||
serverId: string;
|
||
severity: 'info' | 'warning' | 'critical' | 'fatal';
|
||
message: string;
|
||
metricValue: number;
|
||
}
|
||
|
||
// ops-service 发布
|
||
interface TaskCompletedEvent {
|
||
taskId: string;
|
||
result: 'success' | 'failure' | 'partial';
|
||
summary: string;
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 安全架构
|
||
|
||
### 6.1 三层防御模型
|
||
|
||
```
|
||
Layer 1: 命令分级（agent-service 领域层）
|
||
├── Level 0: 只读命令 → 自动执行
|
||
├── Level 1: 低风险写入 → 前端确认
|
||
├── Level 2: 高风险操作 → 多渠道审批
|
||
└── Level 3: 禁止命令 → 直接拦截
|
||
|
||
Layer 2: Hook 拦截（Claude Code PreToolUse）
|
||
└── pre-tool-use-hook.py
|
||
├── 正则匹配危险模式
|
||
├── 写入审批队列
|
||
└── 返回 block/allow
|
||
|
||
Layer 3: 架构隔离（目标服务器侧）
|
||
├── 受限 SSH 用户 (rbash)
|
||
├── K8s RBAC (ops-agent ClusterRole)
|
||
├── 数据库只读账号
|
||
└── 网络隔离 (Security Group)
|
||
```
|
||
|
||
### 6.2 凭证安全流程
|
||
|
||
```
|
||
agent-service 需要 SSH 到 prod-1
|
||
↓ gRPC 请求
|
||
inventory-service 接收请求
|
||
↓ 验证调用者权限
|
||
↓ 从 PostgreSQL 读取加密凭证
|
||
↓ 内存中解密
|
||
↓ 生成临时凭证（TTL=5min）
|
||
↓ 返回
|
||
agent-service 使用临时凭证执行 SSH
|
||
↓ 完成后
|
||
临时凭证自动过期
|
||
```
|
||
|
||
---
|
||
|
||
## 7. 多租户 SaaS 架构
|
||
|
||
### 7.1 隔离策略
|
||
|
||
采用 **Schema-per-Tenant**（同一 PostgreSQL 实例，每个租户独立 Schema）+ **行级隔离**混合模式：
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ PostgreSQL 实例 │
|
||
│ │
|
||
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
|
||
│ │ it0_shared │ │ it0_t_001 │ │ it0_t_002 │ ... │
|
||
│ │ (公共表) │ │ (租户A数据) │ │ (租户B数据) │ │
|
||
│ │ │ │ │ │ │ │
|
||
│ │ tenants │ │ servers │ │ servers │ │
|
||
│ │ plans │ │ credentials │ │ credentials │ │
|
||
│ │ billing │ │ tasks │ │ tasks │ │
|
||
│ │ global_cfg │ │ sessions │ │ sessions │ │
|
||
│ └─────────────┘ └─────────────┘ └─────────────┘ │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
| 表类别 | 隔离方式 | 说明 |
|
||
|--------|---------|------|
|
||
| tenants, plans, billing | 公共 Schema (`it0_shared`) | 跨租户的 SaaS 管理数据 |
|
||
| servers, credentials, tasks, sessions, skills, runbooks, alerts, contacts, audit_logs | 租户独立 Schema (`it0_t_{tenantId}`) | 完全隔离，互不可见 |
|
||
|
||
### 7.2 租户上下文传播（AsyncLocalStorage）
|
||
|
||
所有微服务共享同一个 **TenantContext** 模式，基于 Node.js `AsyncLocalStorage`：
|
||
|
||
```typescript
|
||
// packages/shared/tenant/tenant-context.service.ts
|
||
|
||
import { AsyncLocalStorage } from 'async_hooks';
|
||
|
||
export interface TenantInfo {
|
||
tenantId: string;
|
||
tenantName: string;
|
||
plan: 'free' | 'pro' | 'enterprise';
|
||
schemaName: string; // 'it0_t_{tenantId}'
|
||
}
|
||
|
||
export class TenantContextService {
|
||
private static storage = new AsyncLocalStorage<TenantInfo>();
|
||
|
||
/** 设置当前请求的租户上下文 */
|
||
static run<T>(tenant: TenantInfo, fn: () => T): T {
|
||
return this.storage.run(tenant, fn);
|
||
}
|
||
|
||
/** 获取当前租户 */
|
||
static getTenant(): TenantInfo {
|
||
const tenant = this.storage.getStore();
|
||
if (!tenant) throw new Error('Tenant context not initialized');
|
||
return tenant;
|
||
}
|
||
|
||
static getTenantId(): string {
|
||
return this.getTenant().tenantId;
|
||
}
|
||
|
||
static getSchemaName(): string {
|
||
return this.getTenant().schemaName;
|
||
}
|
||
}
|
||
```
|
||
|
||
### 7.3 请求级租户注入
|
||
|
||
```typescript
|
||
// packages/shared/tenant/tenant.middleware.ts
|
||
|
||
/**
|
||
* NestJS 中间件：从 JWT / API Key / 请求头提取 tenantId
|
||
* 注入到 AsyncLocalStorage，后续所有数据库操作自动切换 Schema
|
||
*/
|
||
@Injectable()
|
||
export class TenantMiddleware implements NestMiddleware {
|
||
constructor(private readonly tenantRepo: TenantRepository) {}
|
||
|
||
async use(req: Request, res: Response, next: NextFunction) {
|
||
// 优先级：JWT claim > X-Tenant-Id header > API Key 关联
|
||
const tenantId = this.extractTenantId(req);
|
||
if (!tenantId) throw new UnauthorizedException('Tenant not identified');
|
||
|
||
const tenant = await this.tenantRepo.findById(tenantId);
|
||
if (!tenant) throw new NotFoundException('Tenant not found');
|
||
|
||
TenantContextService.run({
|
||
tenantId: tenant.id,
|
||
tenantName: tenant.name,
|
||
plan: tenant.plan,
|
||
schemaName: `it0_t_${tenant.id}`,
|
||
}, () => next());
|
||
}
|
||
}
|
||
```
|
||
|
||
### 7.4 TypeORM 动态 Schema 切换
|
||
|
||
```typescript
|
||
// packages/shared/tenant/tenant-aware.repository.ts
|
||
|
||
/**
|
||
* 所有租户隔离的 Repository 基类
|
||
* 自动在查询前切换 PostgreSQL search_path 到租户 Schema
|
||
*/
|
||
export abstract class TenantAwareRepository<T> {
|
||
constructor(
|
||
protected readonly dataSource: DataSource,
|
||
protected readonly entity: EntityTarget<T>,
|
||
) {}
|
||
|
||
protected async getRepository(): Promise<Repository<T>> {
|
||
const schema = TenantContextService.getSchemaName();
|
||
const queryRunner = this.dataSource.createQueryRunner();
|
||
await queryRunner.query(`SET search_path TO "${schema}", public`);
|
||
return queryRunner.manager.getRepository(this.entity);
|
||
}
|
||
|
||
// CRUD 方法都通过 getRepository() 获取租户隔离的仓储
|
||
async findById(id: string): Promise<T | null> {
|
||
const repo = await this.getRepository();
|
||
return repo.findOneBy({ id } as any);
|
||
}
|
||
|
||
async save(entity: T): Promise<T> {
|
||
const repo = await this.getRepository();
|
||
return repo.save(entity);
|
||
}
|
||
}
|
||
```
|
||
|
||
### 7.5 租户生命周期管理
|
||
|
||
```sql
|
||
-- it0_shared schema
|
||
|
||
CREATE TABLE tenants (
|
||
id VARCHAR(20) PRIMARY KEY, -- 短ID如 't001'
|
||
name VARCHAR(200) NOT NULL,
|
||
slug VARCHAR(50) NOT NULL UNIQUE, -- URL 友好标识
|
||
plan VARCHAR(20) NOT NULL DEFAULT 'free', -- 'free' | 'pro' | 'enterprise'
|
||
owner_user_id UUID NOT NULL,
|
||
status VARCHAR(20) NOT NULL DEFAULT 'active', -- 'active' | 'suspended' | 'deleted'
|
||
-- 资源配额
|
||
max_servers INTEGER NOT NULL DEFAULT 5,
|
||
max_skills INTEGER NOT NULL DEFAULT 10,
|
||
max_users INTEGER NOT NULL DEFAULT 3,
|
||
max_sessions_per_day INTEGER NOT NULL DEFAULT 50,
|
||
-- 引擎配置
|
||
allowed_engines VARCHAR(20)[] NOT NULL DEFAULT '{claude_code_cli}',
|
||
-- 审计
|
||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
|
||
);
|
||
|
||
-- 租户创建时自动初始化 Schema
|
||
-- 通过 NestJS migration 或 tenant-provisioning.service.ts 执行：
|
||
-- CREATE SCHEMA it0_t_{tenantId};
|
||
-- 运行租户 Schema 的迁移脚本（创建 servers, credentials, tasks 等表）
|
||
```
|
||
|
||
### 7.6 Kong 多租户路由
|
||
|
||
在 Kong 层面，通过 JWT claim 中的 `tenant_id` 传递租户标识：
|
||
|
||
```yaml
|
||
# kong.yml 追加：租户限流（按 tenant 维度）
|
||
plugins:
|
||
- name: rate-limiting
|
||
config:
|
||
minute: 120
|
||
policy: redis
|
||
redis_host: redis
|
||
# 按 JWT 中的 tenant_id 限流
|
||
limit_by: credential
|
||
```
|
||
|
||
### 7.7 Agent 引擎的多租户隔离
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────┐
|
||
│ agent-service │
|
||
│ │
|
||
│ 租户 A 的任务 ──→ spawn claude -p "..." │
|
||
│ --system-prompt-file /tmp/a/ │
|
||
│ 使用租户 A 的 .claude/skills/ │
|
||
│ SSH 到租户 A 的服务器 │
|
||
│ │
|
||
│ 租户 B 的任务 ──→ spawn claude -p "..." │
|
||
│ --system-prompt-file /tmp/b/ │
|
||
│ 使用租户 B 的 .claude/skills/ │
|
||
│ SSH 到租户 B 的服务器 │
|
||
│ │
|
||
│ 关键隔离点： │
|
||
│ 1. System Prompt 包含租户专属的服务器清单 │
|
||
│ 2. Skills 目录按租户隔离 │
|
||
│ 3. SSH 凭证从租户 Schema 读取 │
|
||
│ 4. Hook 脚本验证命令目标在租户范围内 │
|
||
│ 5. 并发控制：按租户 plan 限制同时执行的任务数 │
|
||
└─────────────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 8. API Gateway — Kong 声明式配置
|
||
|
||
### 8.1 架构选择
|
||
|
||
使用 **Kong DB-less 模式**（声明式 YAML 配置），不依赖额外数据库，配置文件即基础设施：
|
||
|
||
```yaml
|
||
# packages/services/api-gateway/kong.yml
|
||
|
||
_format_version: "3.0"
|
||
|
||
services:
|
||
# ===== auth-service =====
|
||
- name: auth-service
|
||
url: http://auth-service:3001
|
||
routes:
|
||
- name: auth-routes
|
||
paths:
|
||
- /api/v1/auth
|
||
strip_path: false
|
||
|
||
# ===== agent-service =====
|
||
- name: agent-service
|
||
url: http://agent-service:3002
|
||
routes:
|
||
- name: agent-routes
|
||
paths:
|
||
- /api/v1/agent
|
||
strip_path: false
|
||
- name: agent-ws
|
||
paths:
|
||
- /ws/agent
|
||
strip_path: false
|
||
protocols:
|
||
- http
|
||
- https
|
||
- ws
|
||
- wss
|
||
|
||
# ===== ops-service =====
|
||
- name: ops-service
|
||
url: http://ops-service:3003
|
||
routes:
|
||
- name: ops-routes
|
||
paths:
|
||
- /api/v1/ops
|
||
strip_path: false
|
||
|
||
# ===== inventory-service =====
|
||
- name: inventory-service
|
||
url: http://inventory-service:3004
|
||
routes:
|
||
- name: inventory-routes
|
||
paths:
|
||
- /api/v1/inventory
|
||
strip_path: false
|
||
|
||
# ===== monitor-service =====
|
||
- name: monitor-service
|
||
url: http://monitor-service:3005
|
||
routes:
|
||
- name: monitor-routes
|
||
paths:
|
||
- /api/v1/monitor
|
||
strip_path: false
|
||
|
||
# ===== comm-service =====
|
||
- name: comm-service
|
||
url: http://comm-service:3006
|
||
routes:
|
||
- name: comm-routes
|
||
paths:
|
||
- /api/v1/comm
|
||
strip_path: false
|
||
- name: comm-ws
|
||
paths:
|
||
- /ws/comm
|
||
strip_path: false
|
||
protocols:
|
||
- http
|
||
- https
|
||
- ws
|
||
- wss
|
||
|
||
# ===== voice-service =====
|
||
- name: voice-service
|
||
url: http://voice-service:3008
|
||
routes:
|
||
- name: voice-ws
|
||
paths:
|
||
- /ws/voice
|
||
strip_path: false
|
||
protocols:
|
||
- ws
|
||
- wss
|
||
- name: voice-api
|
||
paths:
|
||
- /api/v1/voice
|
||
strip_path: false
|
||
- name: twilio-webhook
|
||
paths:
|
||
- /api/v1/twilio
|
||
strip_path: false
|
||
|
||
# ===== audit-service =====
|
||
- name: audit-service
|
||
url: http://audit-service:3007
|
||
routes:
|
||
- name: audit-routes
|
||
paths:
|
||
- /api/v1/audit
|
||
strip_path: false
|
||
|
||
# ===== 全局插件 =====
|
||
plugins:
|
||
# JWT 认证（全局）
|
||
- name: jwt
|
||
config:
|
||
key_claim_name: kid
|
||
claims_to_verify:
|
||
- exp
|
||
# 排除登录和健康检查路由
|
||
route: null
|
||
service: null
|
||
|
||
# CORS
|
||
- name: cors
|
||
config:
|
||
origins:
|
||
- http://localhost:3000 # Web Admin (Next.js dev)
|
||
- https://admin.it0.your-domain.com
|
||
methods:
|
||
- GET
|
||
- POST
|
||
- PUT
|
||
- DELETE
|
||
- PATCH
|
||
- OPTIONS
|
||
headers:
|
||
- Authorization
|
||
- Content-Type
|
||
credentials: true
|
||
|
||
# 限流（全局默认）
|
||
- name: rate-limiting
|
||
config:
|
||
minute: 120
|
||
policy: redis
|
||
redis_host: redis
|
||
redis_port: 6379
|
||
|
||
# 请求日志
|
||
- name: file-log
|
||
config:
|
||
path: /dev/stdout
|
||
reopen: true
|
||
|
||
# ===== 路由级插件覆盖 =====
|
||
|
||
# auth 路由不需要 JWT（登录端点）
|
||
- name: jwt
|
||
route: auth-routes
|
||
enabled: false
|
||
|
||
# agent WebSocket 更高限流
|
||
- name: rate-limiting
|
||
route: agent-ws
|
||
config:
|
||
minute: 30
|
||
policy: redis
|
||
redis_host: redis
|
||
|
||
# audit 路由只允许 admin 角色
|
||
- name: acl
|
||
route: audit-routes
|
||
config:
|
||
allow:
|
||
- admin
|
||
```
|
||
|
||
### 8.2 Kong Docker 配置
|
||
|
||
```dockerfile
|
||
# packages/services/api-gateway/Dockerfile
|
||
|
||
FROM kong:3.7-alpine
|
||
|
||
# 复制声明式配置
|
||
COPY kong.yml /etc/kong/kong.yml
|
||
|
||
# 环境变量设为 DB-less 模式
|
||
ENV KONG_DATABASE=off
|
||
ENV KONG_DECLARATIVE_CONFIG=/etc/kong/kong.yml
|
||
ENV KONG_PROXY_LISTEN=0.0.0.0:8000
|
||
ENV KONG_ADMIN_LISTEN=0.0.0.0:8001
|
||
ENV KONG_LOG_LEVEL=info
|
||
```
|
||
|
||
```yaml
|
||
# deploy/docker-compose.yml 中的 Kong 服务
|
||
services:
|
||
api-gateway:
|
||
build: ../packages/services/api-gateway
|
||
ports:
|
||
- "8000:8000" # Proxy（客户端访问）
|
||
- "8001:8001" # Admin API（仅内部使用）
|
||
depends_on:
|
||
- auth-service
|
||
- agent-service
|
||
- ops-service
|
||
- inventory-service
|
||
- monitor-service
|
||
- comm-service
|
||
- audit-service
|
||
- redis
|
||
healthcheck:
|
||
test: ["CMD", "kong", "health"]
|
||
interval: 10s
|
||
timeout: 5s
|
||
retries: 3
|
||
networks:
|
||
- it0-network
|
||
```
|
||
|
||
### 8.3 WebSocket 代理注意事项
|
||
|
||
Kong 原生支持 WebSocket 代理，关键配置：
|
||
- `protocols` 包含 `ws` 和 `wss`
|
||
- 建议为 WebSocket 路由单独设置更宽松的超时：连接超时 60s、读写超时 3600s
|
||
- Agent 流式输出和实时通信都走 WebSocket，需要确保 Kong 不会过早断开长连接
|
||
|
||
---
|
||
|
||
## 9. Claude Skills 支持（Anthropic Claude Skills）
|
||
|
||
### 9.1 Skills 与 Runbook 的关系
|
||
|
||
```
|
||
Claude Skills Runbook
|
||
(底层能力单元) (高层业务流程)
|
||
┌─────────────┐ ┌──────────────────┐
|
||
│ /inspect │─── 被组合使用 ──→ │ 每日巡检 Runbook │
|
||
│ /cleanup │─── 被组合使用 ──→ │ (调用多个 Skills) │
|
||
│ /diagnose │ │ │
|
||
└─────────────┘ └──────────────────┘
|
||
|
||
Skills = 原子操作（单个技能，Claude Code 原生识别）
|
||
Runbook = 编排流程（多步骤，包含审批、通知、条件分支）
|
||
```
|
||
|
||
### 9.2 Skill 定义规范
|
||
|
||
每个 Skill 是一个目录，包含 `SKILL.md`（YAML frontmatter + Markdown 指令）：
|
||
|
||
```yaml
|
||
# .claude/skills/inspect/SKILL.md
|
||
|
||
---
|
||
name: inspect
|
||
description: 对指定服务器执行全面健康检查（CPU/MEM/DISK/网络/服务状态），返回结构化报告
|
||
argument-hint: "[server-name|all]"
|
||
allowed-tools: Bash, Read, Grep
|
||
disable-model-invocation: false
|
||
---
|
||
|
||
# 服务器健康检查
|
||
|
||
## 参数
|
||
- `$0`: 目标服务器名称，或 `all` 检查所有服务器
|
||
|
||
## 执行步骤
|
||
|
||
1. **确认目标**：如果 `$0` 是 `all`，从服务器清单获取所有在线服务器
|
||
2. **基础指标采集**（对每台服务器）：
|
||
- `ssh {server} 'top -bn1 | head -5'` — CPU 负载
|
||
- `ssh {server} 'free -h'` — 内存使用
|
||
- `ssh {server} 'df -h'` — 磁盘使用
|
||
- `ssh {server} 'ss -tuln'` — 网络端口
|
||
- `ssh {server} 'uptime'` — 运行时间
|
||
3. **服务状态**：
|
||
- `ssh {server} 'systemctl list-units --failed'` — 失败的服务
|
||
- `ssh {server} 'docker ps --format "table {{.Names}}\t{{.Status}}"'` — 容器状态（如适用）
|
||
4. **异常检测**：标记 CPU>80%、MEM>85%、DISK>90% 的指标
|
||
5. **输出结构化报告**：按服务器分组，标记异常项
|
||
|
||
## 输出格式
|
||
```markdown
|
||
## 巡检报告 — {timestamp}
|
||
|
||
### {server-name} ● 正常 / ⚠ 告警 / 🔴 异常
|
||
| 指标 | 值 | 状态 |
|
||
|------|-----|------|
|
||
| CPU | 45% | ✓ |
|
||
| MEM | 62% | ✓ |
|
||
| DISK | 92% | ⚠ |
|
||
...
|
||
```
|
||
```
|
||
|
||
```yaml
|
||
# .claude/skills/deploy/SKILL.md
|
||
|
||
---
|
||
name: deploy
|
||
description: 将指定应用部署到目标环境（支持 Docker 和 K8s）
|
||
argument-hint: "[app-name] [environment]"
|
||
allowed-tools: Bash, Read, Grep, Glob
|
||
disable-model-invocation: true
|
||
---
|
||
|
||
# 应用部署
|
||
|
||
## 参数
|
||
- `$0`: 应用名称
|
||
- `$1`: 目标环境 (dev/staging/prod)
|
||
|
||
## 前置检查
|
||
1. 确认应用 `$0` 存在于部署配置中
|
||
2. 确认目标环境 `$1` 的服务器可达
|
||
3. 如果是 prod 环境，明确提示需要审批
|
||
|
||
## 部署流程
|
||
1. 拉取最新镜像 / 构建产物
|
||
2. 备份当前版本信息（用于回滚）
|
||
3. 执行滚动更新
|
||
4. 等待健康检查通过
|
||
5. 验证服务正常响应
|
||
6. 输出部署摘要（版本号、耗时、服务状态）
|
||
|
||
## 回滚预案
|
||
如果部署后健康检查失败，自动执行 /rollback $0 $1
|
||
```
|
||
|
||
```yaml
|
||
# .claude/skills/diagnose/SKILL.md
|
||
|
||
---
|
||
name: diagnose
|
||
description: 诊断服务器或服务的异常问题，自动收集日志和上下文
|
||
argument-hint: "[server-name] [symptom-description]"
|
||
allowed-tools: Bash, Read, Grep, Glob
|
||
disable-model-invocation: false
|
||
---
|
||
|
||
# 故障诊断
|
||
|
||
## 参数
|
||
- `$0`: 目标服务器
|
||
- `$ARGUMENTS`: 症状描述（如 "nginx 502 错误"、"磁盘 IO 高"）
|
||
|
||
## 诊断框架
|
||
|
||
### 1. 收集上下文
|
||
- 系统负载: `uptime`, `top -bn1`, `vmstat 1 5`
|
||
- 磁盘 IO: `iostat -x 1 5`
|
||
- 网络: `netstat -s`, `ss -s`
|
||
- 最近错误日志: `journalctl -p err --since "1 hour ago"`
|
||
|
||
### 2. 针对症状深入
|
||
根据 `$ARGUMENTS` 描述的症状，针对性收集：
|
||
- HTTP 错误 → Nginx/Apache 错误日志 + upstream 状态
|
||
- 高负载 → 进程列表 + 资源占用排行
|
||
- 磁盘满 → 大文件查找 + 日志增长速率
|
||
- 内存泄漏 → 进程内存排行 + OOM killer 日志
|
||
|
||
### 3. 分析与建议
|
||
- 总结根因分析
|
||
- 提供修复建议（标明风险等级）
|
||
- 如果有明确的修复命令，提示是否执行
|
||
```
|
||
|
||
### 9.3 Skills 管理在 agent-service 中的实现
|
||
|
||
```
|
||
agent-service/
|
||
├── src/
|
||
│ ├── infrastructure/
|
||
│ │ ├── engines/
|
||
│ │ │ └── claude-code-cli/
|
||
│ │ │ ├── claude-code-engine.ts
|
||
│ │ │ └── ...
|
||
│ │ └── skills/ # ★ Skills 管理层
|
||
│ │ ├── skill-manager.service.ts # Skill CRUD（读写 .claude/skills/）
|
||
│ │ ├── skill-sync.service.ts # DB ↔ 文件系统双向同步
|
||
│ │ ├── skill-template-renderer.ts # 模板变量渲染（$0, $ARGUMENTS 等）
|
||
│ │ └── skill-validator.service.ts # Skill 格式校验（frontmatter + 内容）
|
||
```
|
||
|
||
```typescript
|
||
// infrastructure/skills/skill-manager.service.ts
|
||
|
||
@Injectable()
|
||
export class SkillManagerService {
|
||
private readonly skillsDir: string;
|
||
|
||
constructor(private readonly configService: ConfigService) {
|
||
// Skills 目录：项目根目录下的 .claude/skills/
|
||
this.skillsDir = path.join(
|
||
this.configService.get('PROJECT_ROOT', process.cwd()),
|
||
'.claude', 'skills',
|
||
);
|
||
}
|
||
|
||
/** 列出所有已注册的 Skills */
|
||
async listSkills(): Promise<SkillDefinition[]> {
|
||
const dirs = await fs.readdir(this.skillsDir, { withFileTypes: true });
|
||
const skills: SkillDefinition[] = [];
|
||
|
||
for (const dir of dirs.filter(d => d.isDirectory())) {
|
||
const skillPath = path.join(this.skillsDir, dir.name, 'SKILL.md');
|
||
if (await this.fileExists(skillPath)) {
|
||
const content = await fs.readFile(skillPath, 'utf-8');
|
||
skills.push(this.parseSkillMd(dir.name, content));
|
||
}
|
||
}
|
||
return skills;
|
||
}
|
||
|
||
/** 创建/更新 Skill（从 Web Admin 配置写入文件系统） */
|
||
async upsertSkill(skill: CreateSkillDto): Promise<void> {
|
||
const skillDir = path.join(this.skillsDir, skill.name);
|
||
await fs.mkdir(skillDir, { recursive: true });
|
||
|
||
const content = this.buildSkillMd(skill);
|
||
await fs.writeFile(path.join(skillDir, 'SKILL.md'), content, 'utf-8');
|
||
|
||
// 如果有附带脚本
|
||
if (skill.scripts?.length) {
|
||
const scriptsDir = path.join(skillDir, 'scripts');
|
||
await fs.mkdir(scriptsDir, { recursive: true });
|
||
for (const script of skill.scripts) {
|
||
await fs.writeFile(path.join(scriptsDir, script.name), script.content, 'utf-8');
|
||
}
|
||
}
|
||
}
|
||
|
||
/** 删除 Skill */
|
||
async deleteSkill(name: string): Promise<void> {
|
||
const skillDir = path.join(this.skillsDir, name);
|
||
await fs.rm(skillDir, { recursive: true, force: true });
|
||
}
|
||
|
||
/** 通过 Claude Code CLI 调用 Skill */
|
||
invokeSkillPrompt(skillName: string, args: string): string {
|
||
// 返回格式化的 prompt，让 Claude Code 识别为 Skill 调用
|
||
return `/${skillName} ${args}`;
|
||
}
|
||
|
||
/** 解析 SKILL.md (YAML frontmatter + Markdown body) */
|
||
private parseSkillMd(dirName: string, content: string): SkillDefinition {
|
||
const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
|
||
if (!frontmatterMatch) {
|
||
return { name: dirName, description: '', content, frontmatter: {} };
|
||
}
|
||
const frontmatter = yaml.parse(frontmatterMatch[1]);
|
||
const body = frontmatterMatch[2];
|
||
return {
|
||
name: frontmatter.name || dirName,
|
||
description: frontmatter.description || '',
|
||
argumentHint: frontmatter['argument-hint'],
|
||
allowedTools: frontmatter['allowed-tools'],
|
||
disableModelInvocation: frontmatter['disable-model-invocation'] ?? false,
|
||
content: body,
|
||
frontmatter,
|
||
};
|
||
}
|
||
|
||
/** 构建 SKILL.md 内容 */
|
||
private buildSkillMd(skill: CreateSkillDto): string {
|
||
const frontmatter = yaml.stringify({
|
||
name: skill.name,
|
||
description: skill.description,
|
||
'argument-hint': skill.argumentHint,
|
||
'allowed-tools': skill.allowedTools,
|
||
'disable-model-invocation': skill.disableModelInvocation ?? false,
|
||
});
|
||
return `---\n${frontmatter}---\n\n${skill.content}`;
|
||
}
|
||
}
|
||
```
|
||
|
||
### 9.4 Skill 与引擎的集成
|
||
|
||
```typescript
|
||
// Claude Code CLI 引擎中调用 Skill 的两种方式：
|
||
|
||
// 方式 1: 直接在 prompt 中使用 /skill-name（Claude Code 自动识别）
|
||
const args = ['-p', `/inspect all`, '--output-format', 'stream-json', ...];
|
||
|
||
// 方式 2: Skill 内容已通过 .claude/skills/ 目录自动加载到 Claude Code 上下文中
|
||
// Claude Code 启动时读取所有 Skills 的 description，自主决定何时使用
|
||
// 当用户说"检查一下服务器"时，Claude Code 会自动匹配 /inspect skill
|
||
|
||
// 方式 3: Claude API 引擎 — 手动注入 Skill 内容到 system prompt
|
||
// 当切换到 Claude API 引擎时，SkillManager 读取 Skill 内容，拼接到 system prompt 中
|
||
```
|
||
|
||
### 9.5 Skill 数据库表（agent-service）
|
||
|
||
```sql
|
||
-- 追加到 it0_agent schema
|
||
|
||
-- Skills 注册表（与文件系统双向同步）
|
||
CREATE TABLE skills (
|
||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||
name VARCHAR(64) NOT NULL UNIQUE, -- kebab-case 名称
|
||
description TEXT NOT NULL,
|
||
argument_hint VARCHAR(200),
|
||
allowed_tools VARCHAR(50)[],
|
||
disable_model_invocation BOOLEAN NOT NULL DEFAULT FALSE,
|
||
content TEXT NOT NULL, -- Markdown 指令体
|
||
frontmatter JSONB NOT NULL DEFAULT '{}', -- 完整 frontmatter
|
||
version INTEGER NOT NULL DEFAULT 1,
|
||
is_active BOOLEAN NOT NULL DEFAULT TRUE,
|
||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
|
||
);
|
||
|
||
-- Skill 执行记录
|
||
CREATE TABLE skill_executions (
|
||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||
skill_name VARCHAR(64) NOT NULL,
|
||
session_id UUID REFERENCES agent_sessions(id),
|
||
arguments TEXT,
|
||
engine_type VARCHAR(20) NOT NULL,
|
||
status VARCHAR(20) NOT NULL, -- 'success' | 'failure' | 'cancelled'
|
||
duration_ms INTEGER,
|
||
executed_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
|
||
);
|
||
|
||
CREATE INDEX idx_skill_executions_name ON skill_executions(skill_name, executed_at);
|
||
```
|
||
|
||
### 9.6 引擎兼容性：Skills 在三种引擎下的行为
|
||
|
||
| 引擎 | Skill 加载方式 | Skill 调用方式 |
|
||
|------|---------------|---------------|
|
||
| **Claude Code CLI** | `.claude/skills/` 目录自动发现 | `/skill-name args`（原生支持） |
|
||
| **Claude API** | `SkillManager` 读取 → 拼接到 system prompt | prompt 中包含 Skill 指令文本 |
|
||
| **Custom Agent** | `SkillManager` 读取 → 注入到自研引擎上下文 | 自定义调用机制 |
|
||
|
||
当切换引擎时，`SkillManager` 确保 Skills 的跨引擎可移植性：
|
||
- Claude Code CLI 原生读 `.claude/skills/` 目录
|
||
- 其他引擎通过 `SkillManager.getSkillContent(name)` 获取 Skill 内容，手动注入
|
||
|
||
---
|
||
|
||
## 10. 运维专用 System Prompt 模板
|
||
|
||
```typescript
|
||
// infrastructure/engines/claude-code-cli/system-prompt-builder.ts
|
||
|
||
export class SystemPromptBuilder {
|
||
build(context: OpsContext): string {
|
||
return `
|
||
你是 IT0 运维智能体，负责管理以下服务器集群。
|
||
|
||
## 你管理的环境
|
||
${context.servers.map(s => `- ${s.name} (${s.host}) [${s.environment}/${s.role}]`).join('\n')}
|
||
|
||
## 集群信息
|
||
${context.clusters.map(c => `- ${c.name} (${c.type}) — ${c.description}`).join('\n')}
|
||
|
||
## 操作规范
|
||
|
||
### 权限分级
|
||
- Level 0（自动执行）：查看类命令（df, free, top, kubectl get, docker ps, cat/grep 日志）
|
||
- Level 1（需确认）：服务重启、日志清理、配置查看
|
||
- Level 2（需审批）：部署、扩缩容、数据库操作、配置修改
|
||
- Level 3（禁止）：rm -rf /, DROP DATABASE, shutdown, reboot, 格式化磁盘
|
||
|
||
### 执行原则
|
||
1. 每次操作前先说明你要做什么、为什么
|
||
2. 执行破坏性操作前，先展示完整命令
|
||
3. 每次操作后验证结果（检查返回码、确认服务状态）
|
||
4. 发现异常时自动收集诊断信息（日志末尾、资源使用、进程列表、网络状态）
|
||
5. 如果不确定，宁可多查一步也不要盲目执行
|
||
6. 操作完成后给出简洁总结
|
||
|
||
### 禁止行为
|
||
- 绝不猜测密码或凭证
|
||
- 绝不修改 SSH 配置或防火墙规则（除非明确指示）
|
||
- 绝不安装未经授权的软件包
|
||
- 绝不在生产环境执行未经验证的脚本
|
||
|
||
### SSH 访问
|
||
使用预配置的 SSH 别名：ssh ${context.sshUser}@{server_host}
|
||
`.trim();
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 11. 项目初始化与目录结构
|
||
|
||
### 11.1 Monorepo 结构
|
||
|
||
```
|
||
IT0/
|
||
├── docs/ # 文档
|
||
│ ├── backend-guide.md # 本文档
|
||
│ ├── flutter-guide.md # Flutter 前端指导
|
||
│ └── web-admin-guide.md # PC Web 管理前端指导
|
||
│
|
||
├── packages/
|
||
│ ├── shared/ # 共享包
|
||
│ │ ├── proto/ # gRPC Protobuf 定义
|
||
│ │ ├── events/ # 事件类型定义
|
||
│ │ └── utils/ # 公共工具
|
||
│ │
|
||
│ └── services/ # 微服务
|
||
│ ├── api-gateway/ # Kong 声明式配置
|
||
│ │ ├── kong.yml # 路由/服务/插件声明
|
||
│ │ ├── Dockerfile # Kong 自定义镜像
|
||
│ │ └── plugins/ # 自定义插件（如需）
|
||
│ ├── auth-service/
|
||
│ ├── agent-service/ # ★ 核心智能体服务
|
||
│ ├── ops-service/
|
||
│ ├── inventory-service/
|
||
│ ├── monitor-service/
|
||
│ ├── comm-service/
|
||
│ ├── voice-service/ # ★ Pipecat 语音对话引擎 (Python)
|
||
│ └── audit-service/
|
||
│
|
||
├── .claude/ # ★ Claude Code Skills 目录
|
||
│ ├── skills/ # 运维技能定义
|
||
│ │ ├── inspect/SKILL.md # 全面巡检 Skill
|
||
│ │ ├── deploy/SKILL.md # 部署 Skill
|
||
│ │ ├── rollback/SKILL.md # 回滚 Skill
|
||
│ │ ├── cleanup/SKILL.md # 清理 Skill
|
||
│ │ ├── diagnose/SKILL.md # 故障诊断 Skill
|
||
│ │ ├── scale/SKILL.md # 扩缩容 Skill
|
||
│ │ ├── backup-check/SKILL.md # 备份验证 Skill
|
||
│ │ └── security-audit/SKILL.md # 安全审计 Skill
|
||
│ ├── commands/ # 兼容旧版 slash commands
|
||
│ └── settings.json # Hook + 权限配置
|
||
│
|
||
├── ops-config/ # 运维配置
|
||
│ ├── system-prompts/ # System Prompt 模板
|
||
│ ├── hooks/ # Claude Code Hook 脚本
|
||
│ │ └── pre-tool-use-hook.py
|
||
│ ├── runbooks/ # Runbook 模板（高级，多步骤）
|
||
│ └── risk-patterns.json # 危险命令模式库
|
||
│
|
||
├── deploy/
|
||
│ ├── docker-compose.yml # 开发环境
|
||
│ ├── docker-compose.prod.yml # 生产环境
|
||
│ └── k8s/ # Kubernetes 部署清单
|
||
│
|
||
├── package.json # Monorepo root (pnpm workspace)
|
||
├── pnpm-workspace.yaml
|
||
├── tsconfig.base.json
|
||
└── .env.example
|
||
```
|
||
|
||
### 11.2 单个微服务标准结构（Clean Architecture）
|
||
|
||
```
|
||
{service-name}/
|
||
├── src/
|
||
│ ├── domain/ # 领域层 — 零外部依赖
|
||
│ │ ├── entities/ # 聚合根 & 实体
|
||
│ │ ├── value-objects/ # 值对象
|
||
│ │ ├── ports/ # 端口（接口定义）
|
||
│ │ │ ├── inbound/ # 入站端口（用例接口）
|
||
│ │ │ └── outbound/ # 出站端口（依赖接口）
|
||
│ │ ├── events/ # 领域事件
|
||
│ │ └── services/ # 领域服务
|
||
│ │
|
||
│ ├── application/ # 应用层 — 用例编排
|
||
│ │ ├── use-cases/ # 用例实现
|
||
│ │ └── dto/ # 数据传输对象
|
||
│ │
|
||
│ ├── infrastructure/ # 基础设施层 — 适配器实现
|
||
│ │ ├── persistence/ # TypeORM 实体 & 仓储
|
||
│ │ ├── messaging/ # 消息队列
|
||
│ │ ├── clients/ # 外部服务客户端
|
||
│ │ └── config/ # 配置
|
||
│ │
|
||
│ ├── interfaces/ # 接口层 — 控制器
|
||
│ │ ├── rest/ # REST API
|
||
│ │ ├── grpc/ # gRPC 服务
|
||
│ │ └── ws/ # WebSocket 网关
|
||
│ │
|
||
│ ├── app.module.ts
|
||
│ └── main.ts
|
||
│
|
||
├── test/
|
||
│ ├── unit/
|
||
│ ├── integration/
|
||
│ └── e2e/
|
||
│
|
||
├── Dockerfile
|
||
├── package.json
|
||
└── tsconfig.json
|
||
```
|
||
|
||
---
|
||
|
||
## 12. 开发路线图
|
||
|
||
### Phase 1: 基础骨架（Week 1-2）
|
||
- [ ] Monorepo 初始化（pnpm workspace + NestJS CLI）
|
||
- [ ] auth-service: JWT 认证 + RBAC
|
||
- [ ] agent-service: Claude Code CLI 引擎 + 流式输出
|
||
- [ ] 命令风险分级 + Hook 拦截脚本
|
||
- [ ] WebSocket 实时推送
|
||
|
||
### Phase 2: 运维核心（Week 3-4）
|
||
- [ ] inventory-service: 服务器/凭证管理
|
||
- [ ] ops-service: 任务创建 + 审批工作流
|
||
- [ ] 端到端流程：前端发起任务 → Agent 执行 → 审批 → 完成
|
||
- [ ] Runbook 模板系统
|
||
|
||
### Phase 3: 监控告警（Week 5-6）
|
||
- [ ] monitor-service: 健康检查 + 指标采集
|
||
- [ ] 告警规则 + 自动触发 Runbook
|
||
- [ ] 告警 → 通知升级链路
|
||
|
||
### Phase 4: 多渠道通信 + 语音对话（Week 7-9）
|
||
- [ ] comm-service: 推送 + 短信 + 邮件 + IM（Telegram/企业微信）
|
||
- [ ] voice-service: Pipecat + faster-whisper + Kokoro-82M 部署
|
||
- [ ] Flutter App WebSocket 音频流 ←→ voice-service 对接
|
||
- [ ] Pipecat 主动拨号（Twilio 电话线路）+ Media Streams 语音对话
|
||
- [ ] 三层递进升级链路端到端测试
|
||
|
||
### Phase 5: 引擎扩展（Week 9-10）
|
||
- [ ] Claude API 引擎实现（备选方案）
|
||
- [ ] 引擎运行时切换 + 性能对比
|
||
- [ ] audit-service: 完整审计链
|
||
|
||
---
|
||
|
||
## 13. 环境变量配置
|
||
|
||
```env
|
||
# .env.example
|
||
|
||
# ===== 全局 =====
|
||
NODE_ENV=development
|
||
LOG_LEVEL=debug
|
||
|
||
# ===== PostgreSQL =====
|
||
POSTGRES_HOST=localhost
|
||
POSTGRES_PORT=5432
|
||
POSTGRES_USER=it0
|
||
POSTGRES_PASSWORD=changeme
|
||
POSTGRES_DB=it0
|
||
|
||
# ===== Redis =====
|
||
REDIS_HOST=localhost
|
||
REDIS_PORT=6379
|
||
|
||
# ===== Agent Engine =====
|
||
AGENT_ENGINE_TYPE=claude_code_cli # claude_code_cli | claude_api | custom
|
||
CLAUDE_CODE_PATH=/usr/local/bin/claude # Claude Code CLI 路径
|
||
ANTHROPIC_API_KEY=sk-ant-xxx # Claude API 备选方案
|
||
|
||
# ===== 安全 =====
|
||
VAULT_MASTER_KEY=your-256-bit-key # 凭证加密密钥
|
||
JWT_SECRET=your-jwt-secret
|
||
JWT_EXPIRES_IN=24h
|
||
|
||
# ===== 通信渠道（comm-service）=====
|
||
SMTP_HOST=smtp.gmail.com
|
||
SMTP_PORT=587
|
||
SMTP_USER=xxx
|
||
SMTP_PASSWORD=xxx
|
||
TELEGRAM_BOT_TOKEN=xxx
|
||
WECHAT_CORP_ID=xxx
|
||
WECHAT_CORP_SECRET=xxx
|
||
|
||
# ===== voice-service（Pipecat 语音对话引擎）=====
|
||
VOICE_SERVICE_URL=http://voice-service:3008 # voice-service 内部地址
|
||
WHISPER_MODEL=large-v3 # faster-whisper 模型 (base/small/medium/large-v3)
|
||
KOKORO_MODEL=kokoro-82m # Kokoro TTS 模型
|
||
VOICE_DEVICE=cuda # STT/TTS 推理设备 (cuda/cpu)
|
||
|
||
# ===== Twilio（电话线路载体：Pipecat 通过它拨号）=====
|
||
TWILIO_ACCOUNT_SID=ACxxx
|
||
TWILIO_AUTH_TOKEN=xxx
|
||
TWILIO_PHONE_NUMBER=+1234567890
|
||
TWILIO_MEDIA_STREAMS_URL=wss://voice-service:3008/twilio-stream # Media Streams 转接地址
|
||
```
|
||
|
||
---
|
||
|
||
## 14. 关键设计决策备忘
|
||
|
||
| 决策 | 选择 | 理由 |
|
||
|------|------|------|
|
||
| 引擎抽象层 | Strategy + Adapter | 运行时切换，不需要重启服务 |
|
||
| 服务间同步通信 | gRPC | 类型安全、高性能、双向流 |
|
||
| 服务间异步通信 | Redis Streams | 轻量、可靠、不需要额外中间件 |
|
||
| 数据库 | PostgreSQL（每服务独立 schema） | 同一个 PG 实例多 schema，开发简单；生产可拆分 |
|
||
| 凭证存储 | AES-256-GCM + PostgreSQL | 不引入 HashiCorp Vault 的复杂度，够用 |
|
||
| 审计日志 | Append-Only + 数据库级权限控制 | 防篡改，满足合规需求 |
|
||
| 定时任务 | Bull Queue (Redis-backed) | NestJS 原生支持，可靠的延迟/重试机制 |
|
||
| 监控指标存储 | PostgreSQL 分区表 | 初期够用；后期可迁移 TimescaleDB |
|
||
| 前后端通信 | REST + WebSocket | REST 用于 CRUD，WebSocket 用于实时流 |
|
||
| API 网关 | Kong DB-less 声明式 | 无需额外 DB，YAML 配置即基础设施，原生支持 WebSocket/JWT/限流 |
|
||
| AI Skills | Anthropic Claude Skills (`.claude/skills/`) | 原生 Claude Code 支持 + DB 同步实现跨引擎可移植 |
|
||
| Skills vs Runbook | Skills=原子技能，Runbook=编排流程 | Skills 是底层能力单元，Runbook 组合 Skills 实现多步骤业务流程 |
|
||
| 多租户隔离 | Schema-per-Tenant + 行级 tenant_id | Schema 级隔离安全性高，tenant_id 列防御纵深；避免 Database-per-Tenant 的运维复杂度 |
|
||
| 租户上下文 | AsyncLocalStorage | 无侵入式传播，不需要每个方法显式传参；NestJS 中间件统一注入 |
|
||
| 租户 Schema 管理 | TypeORM `SET search_path` | 动态切换，无需维护多 DataSource；QueryRunner 级别隔离 |
|
||
| 自治运维范式 | 驻留指令（Standing Orders） | 对话定义 → 结构化提取 → 自主执行 → 智能升级；避免 24/7 人工在线 |
|
||
| 驻留指令执行 | Bull Queue + cron 调度 | 可靠的定时触发、重试、并发控制；执行记录完整审计 |
|
||
| 智能升级通道 | 三层递进（推送→电话唤醒→扩大通知） | App 推送优先；2分钟无响应→电话唤醒；5分钟→IM/短信；10分钟→备用联系人/邮件 |
|
||
| 语音对话引擎 | Pipecat (Python, 10.1k stars) | 原生 Claude 集成 + 自部署 STT/TTS + 打断支持 + < 500ms 延迟；不依赖外部语音 API |
|
||
| STT 选型 | faster-whisper (large-v3) | 20.6k stars，4x 快于原版 Whisper，支持 GPU + 8bit 量化，中英文准确率高 |
|
||
| TTS 选型 | Kokoro-82M | Apache 开源，82M 参数质量媲美大模型，中英双语，CPU/GPU 均可运行 |
|
||
| Twilio 定位 | 纯电话线路载体 | Pipecat 通过 Twilio REST API 拨号 + Media Streams 传输音频；无 IVR，Agent 接通即说话 |
|