AI-CLI 深度笔记

export async function initializeContext(
  config: AgentSessionConfig,
  events: AgentStreamCallbacks,
  userInput: string,
): Promise<InitializedContext> {
  const aiMessages: Message[] = [];

  // 1. System Prompt — 注入工具定义和项目指令
  const toolDefs = mcpManager.getToolDefinitions();
  const systemPrompt = buildSystemPrompt({
    tools: toolDefs,
    projectInstructions,
    cwd
  });
  aiMessages.push({ role: 'system', content: systemPrompt });

  // 2. Project rules file (.ai-cli.md) — 项目级约定
  const { content: rulesContent, hasRules } = loadProjectRules(cwd);
  if (hasRules)
    aiMessages.push({ role: 'system', content: formatRulesForContext(rulesContent) });

  // 3. Workspace context — git分支、最近提交、已修改文件
  const ctx = getCachedContext() || await captureContext(cwd);
  if (ctx.workspaceName)
    aiMessages.push({ role: 'system', content: formatContextForPrompt(ctx) });

  // 4. Long-term memories — 语义搜索匹配（最多3条）
  const memories = await smartSearchMemory(userInput, chatFn, { limit: 3, cwd });
  if (memories.length > 0)
    aiMessages.push({ role: 'system', content: `[相关记忆]\n${memories.map(m => m.content).join('\n')}` });

  // 5. Session memory — 当前会话目标与已完成动作
  const loaded = loadSessionMemory(sessionId, cwd);
  if (loaded && (loaded.goal || loaded.completedActions.length > 0))
    aiMessages.push({ role: 'system', content: formatSessionMemoryForContext(loaded) });

  // 6. User preferences — 用户偏好设置
  const prefs = getUserPreferences(cwd);
  if (prefs.length > 0)
    aiMessages.push({ role: 'system', content: `[用户偏好]\n${prefs.join('\n')}` });

  // 7. User input — 最终的用户输入
  aiMessages.push({ role: 'user', content: userInput });

  return { messages: aiMessages, toolDefs };
}

export interface AgentStreamCallbacks {
  onText: (delta: string, fullContent: string) => void;
  onToolCalls: (calls: ToolCallRequest[]) => void;
  onToolResults: (results: ToolResultEntry[]) => void;
  onStatus: (status: AgentStatus) => void;
  onError: (error: string) => void;
  onComplete: (result: AgentCompleteResult) => void;
  onTokenUsage?: (usage: { input: number; output: number }) => void;
}

export interface AgentStatus {
  type: 'thinking' | 'executing' | 'confirming' | 'compressing' | 'idle';
  detail?: string;
}

export interface LLMStreamResult {
  content: string;
  tool_calls?: ToolCallRequest[];
  finishReason?: 'stop' | 'length' | 'tool_calls' | 'content_filter' | 'aborted' | 'error';
  usage?: { input: number; output: number };
  reasoning_content?: string;
}

const CONSECUTIVE_FAILURES_THRESHOLD = 4;   // 连续4次失败 → 警告
const NO_PROGRESS_TURNS_THRESHOLD = 5;       // 连续5轮无进展 → 警告
const OUTPUT_LENGTH_DROP_RATIO = 0.6;        // 输出长度降至60% → 可疑
const REPEATED_TOOL_PATTERN_THRESHOLD = 5;   // 同一工具模式5次 → 可疑
const SEVERE_FAILURES_THRESHOLD = 8;         // 连续8次失败 → 终止循环
const SEVERE_IDLE_THRESHOLD = 10;            // 连续10轮空闲 → 终止循环

export interface DriftSignals {
  consecutiveFailures: number;      // 连续工具执行失败计数
  noProgressTurns: number;          // 无有效输出轮数
  recentAvgOutputLength: number;    // 近期平均输出长度（基准）
  currentOutputLength: number;      // 当前输出长度
  refusalCount: number;             // LLM 拒绝执行计数
  recentToolFingerprints: string[]; // 最近N轮的工具调用指纹
  pendingToolCount: number;         // 待确认/执行的工具数
  hasToolCalls: boolean;            // 本轮是否调用了工具
  hasTextOutput: boolean;           // 本轮是否有文本输出
  turnNumber: number;               // 当前迭代轮次
}

const DAILY_LIMIT = 10;  // 每日最多提取10次
const EXTRACTION_PROMPT = `分析以下对话，只提取**真正有价值**的信息。输出纯 JSON 数组：
[
  { "type": "preference", "content": "用户偏好...", "confidence": 80 },
  { "type": "decision", "content": "决定使用...", "confidence": 90 },
  { "type": "fact", "content": "项目事实...", "confidence": 60 }
]
类型: preference(偏好), decision(决策), fact(事实), command(命令)
置信度: 0-100。80+：用户明确陈述；60-79：可推断；<60：不确定。
忽略闲聊、问候、中间过程和失败尝试。`;

export async function autoExtractMemories(
  messages: Message[],
  cwd: string,
  chatFn: (msgs: Message[]) => Promise<string>
): Promise<number> {
  resetDailyIfNeeded();               // 每日重置计数器
  if (todayCount >= DAILY_LIMIT) return 0;  // 超过每日限额
  const valuable = messages.filter(m => m.role === 'user' || m.role === 'assistant');
  if (valuable.length < 3) return 0;  // 消息太少，不值得提取

  // LLM 提取 + 置信度过滤(>=70) + 去重
  const extractionMsgs = [
    { role: 'system', content: EXTRACTION_PROMPT },
    { role: 'user', content: JSON.stringify(valuable.slice(-20)) }  // 只取最近20条
  ];
  const raw = await chatFn(extractionMsgs);
  const items = JSON.parse(raw)
    .filter((item: any) => item.confidence >= 70);  // 置信度阈值

  let saved = 0;
  for (const item of items) {
    const isDup = await checkDuplicate(item.content, cwd);  // 去重检查
    if (!isDup) {
      await saveMemory({ type: item.type, content: item.content, cwd });
      saved++;
    }
  }
  todayCount += saved;
  return saved;
}

const TIME_GATE_MS = 24 * 60 * 60 * 1000;  // 24小时
const SESSION_GATE_COUNT = 5;                    // 5次会话
const LOCK_STALE_MS = 30 * 60 * 1000;           // 30分钟锁过期

export function checkAutoDream(cwd: string): boolean {
  // 1. 时间门控：距上次dream已超过24小时
  const lastDream = getLastDreamTime(cwd);
  if (Date.now() - lastDream < TIME_GATE_MS) return false;

  // 2. 会话门控：自上次dream后已有5次会话
  const sessionsSince = getSessionsSinceLastDream(cwd);
  if (sessionsSince < SESSION_GATE_COUNT) return false;

  // 3. 锁门控：没有正在运行的dream
  const lock = getDreamLock(cwd);
  if (lock && Date.now() - lock.timestamp < LOCK_STALE_MS) return false;

  // 4. 预算门控：token预算充足
  const budget = getTokenBudget(cwd);
  if (budget.remaining < DREAM_MIN_BUDGET) return false;

  return true;  // 全部通过，可以触发AutoDream
}

export async function captureContext(cwd: string): Promise<WorkspaceContext> {
  // 并行执行4个git命令，减少等待时间
  const [gitBranch, gitRemote, gitLog, gitStatus] = await Promise.all([
    execSafe(['git', 'branch', '--show-current'], cwd),    // 当前分支
    execSafe(['git', 'remote', 'get-url', 'origin'], cwd), // 远程仓库
    execSafe(['git', 'log', '--oneline', '-5'], cwd),      // 最近5条提交
    execSafe(['git', 'status', '--short'], cwd),           // 文件变更状态
  ]);

  return {
    workspaceName: path.basename(cwd),
    gitBranch: gitBranch.stdout,
    gitRemote: gitRemote.stdout,
    recentCommits: gitLog.stdout.split('\n').filter(Boolean),
    modifiedFiles: gitStatus.stdout.split('\n').filter(Boolean),
  };
}

export async function executeSingleTool(
  tc: ToolCallRequest,
  toolCtx: ToolExecutionContext,
  retryTracker: Map<string, number>,
  cachedDangerResult?: 'safe' | { level: 'caution' | 'danger'; reason: string },
): Promise<ToolResultEntry> {
  // Step 1: 解析参数
  let parsedArgs: Record<string, unknown>;
  try { parsedArgs = JSON.parse(tc.arguments); }
  catch { return { error: 'JSON解析失败' }; }

  // Step 2: 查找工具定义 + 静态分类
  const toolDef = mcpManager.getTool(tc.name);
  const staticCat = classifyTool(toolDef);

  // Step 3: 运行时危险检查（dangerCheck 函数）
  const dangerCheckResult = cachedDangerResult
    ?? toolDef?.dangerCheck?.(parsedArgs, toolCtx.cwd);
  const errorCategory = runtimeClassify(staticCat, tc.name, dangerCheckResult);

  // Step 4: 执行工具
  let toolResult = await mcpManager.executeTool(
    { name: tc.name, arguments: parsedArgs }, toolCtx
  );

  // Step 5: 应用上下文修改器
  if (toolResult.contextModifier) toolResult.contextModifier(toolCtx);

  // Step 6: 重试指纹跟踪
  let retryCount = 0;
  if (!toolResult.success) {
    const fp = toolFingerprint(tc.name, parsedArgs);
    retryCount = (retryTracker.get(fp) ?? -1) + 1;
    retryTracker.set(fp, retryCount);
  }

  return { ...toolResult, retryCount, errorCategory };
}

const RESULT_THRESHOLD = 3000;  // 超过3000字符触发持久化

export function persistLargeResult(toolName: string, content: string) {
  if (content.length <= RESULT_THRESHOLD) return { summary: content };

  // 保存完整结果到临时文件
  const timestamp = Date.now();
  const filePath = `/tmp/ai-cli-results/${timestamp}-${toolName}.txt`;
  fs.writeFileSync(filePath, content, 'utf-8');

  // 生成摘要：前30行 + 最后10行 + 省略提示
  const lines = content.split('\n');
  const head = lines.slice(0, 30).join('\n');
  const tail = lines.slice(-10).join('\n');
  const omitted = lines.length - 40;
  const summary = `${head}\n... (省略 ${omitted} 行) ...\n${tail}`;

  // 异步清理24小时前的文件
  scheduleCleanup(24 * 60 * 60 * 1000);

  return {
    summary,
    filePath,
    totalLines: lines.length,
    totalSize: content.length,
  };
}

const CLASSIFIER_SYSTEM_PROMPT = [
  '你是工具安全分类器。判断一次工具调用是否可以在不询问用户的情况下自动执行。',
  '决策标准：',
  '- "safe" = 可以自动执行，无需用户确认',
  '- "risky" = 需要用户确认后再执行',
  '',
  '常见场景判断：',
  '| 读取文件/搜索代码 | safe | 无害操作 |',
  '| 写入/修改现有文件 | risky | 可能覆盖重要内容 |',
  '| 创建新文件 | safe | 新增内容不破坏已有 |',
  '| 删除文件/目录 | risky | 不可逆操作 |',
  '| shell: ls/cat/grep/pwd/which | safe | 只读命令 |',
  '| shell: rm/mv/cp/dd/format | risky | 破坏性命令 |',
  '| shell: mkdir/touch | safe | 创建行为无害 |',
  '| shell: npm/pip/cargo install | risky | 修改依赖锁文件 |',
  '| shell: git commit/push | risky | 不可逆版本操作 |',
  '| 编译/构建 | safe | 构建输出可预览 |',
  '',
  '输出格式（仅 JSON）：',
  '{"decision":"safe"|"risky","reason":"简短解释（10-30字）"}',
].join('\n');

export async function classifyToolAction(
  options: ClassifyOptions
): Promise<ClassifyResult> {
  // 使用轻量 LLM 调用，延迟 200-500ms
  // 输入：工具名 + 参数 + 工作上下文
  // 输出：{ decision: 'safe' | 'risky', reason: string }
  const result = await lightweightLLMCall({
    system: CLASSIFIER_SYSTEM_PROMPT,
    user: JSON.stringify({
      tool: options.toolName,
      args: options.args,
      context: options.workingContext,
    }),
    maxTokens: 100,  // 极短输出，保证速度
  });
  return JSON.parse(result);
}

// 每个工具可以定义自己的 dangerCheck 函数
// shell 工具的 dangerCheck 示例：
function shellDangerCheck(args: { command: string }, cwd: string) {
  const cmd = args.command.trim().toLowerCase();
  const dangerousPatterns = [
    /rm\s+-rf/, /format/, /dd\s+if=/,          // 破坏性命令
    /git\s+push/, /git\s+reset\s+--hard/,      // 不可逆Git操作
    /npm\s+publish/, /docker\s+rm/,             // 发布/删除操作
    /curl.*\|\s*sh/, /wget.*\|\s*bash/,       // 远程脚本执行
  ];
  const safePatterns = [
    /^ls/, /^cat/, /^grep/, /^find/, /^pwd/,      // 只读命令
    /^echo/, /^mkdir/, /^touch/, /^which/,         // 创建/查询
    /^git\s+status/, /^git\s+log/, /^git\s+diff/, // Git只读
  ];

  for (const p of dangerousPatterns) {
    if (p.test(cmd)) return { level: 'danger', reason: '检测到破坏性命令模式' };
  }
  for (const p of safePatterns) {
    if (p.test(cmd)) return 'safe';
  }
  return { level: 'caution', reason: '需要AI分类器判断' };
}

export interface ForkedAgentOptions {
  prompt: string;                    // 子任务描述
  llmStream: LLMStreamFn;           // LLM 流式调用函数
  cwd: string;                       // 工作目录
  maxTurns?: number;                 // 最大轮次（按类型默认：general=10, explore=8, plan/verify=5）
  parentDepth?: number;              // 递归深度限制（防止无限嵌套）
  agentType?: BuiltinAgentType;      // 'general-purpose' | 'explore' | 'plan' | 'verify'
  description?: string;              // 子任务简述（用于日志和UI展示）
  onProgress?: (summary: string, turn: number, toolCount: number) => void;
  progressIntervalMs?: number;       // 进度回调间隔，默认 30000 (30s)
  rawOutput?: boolean;               // 是否返回原始输出（不做结论格式化）
  canUseTool?: (toolName: string, args: any) => boolean | Promise<boolean>;
}

// 默认工具过滤器 — 防止无限递归
async function defaultCanUseTool(toolName: string): Promise<boolean> {
  if (toolName === 'agent_tool') return false;    // 禁止子Agent再派生子Agent
  if (toolName.startsWith('memory_')) return false; // 禁止修改记忆
  // explore/plan/verify 类型只允许只读工具
  if (['explore', 'plan', 'verify'].includes(agentType)) {
    return isReadOnlyTool(toolName);  // 只有搜索、读取类工具
  }
  return true;  // general-purpose 允许所有工具
}

const SHARED_META = `
## 你是子任务执行者
### 通用规则
1. 只做分配的事，不扩展范围
2. 快速收敛，每轮自查"我离目标还有多远"
3. 完成或遇到阻碍后，用结论格式结束

### 结束格式要求
结论: <一句话总结>
证据: <关键发现列表>
下一步: <建议父 Agent 做什么>
`;

// explore 类型额外约束
const EXPLORE_META = SHARED_META + `
### 额外约束
- 只使用只读工具（搜索、读取、查看）
- 不修改任何文件
- 专注于理解和发现信息
- 最多8轮，第6轮起准备收尾
`;

// plan 类型额外约束
const PLAN_META = SHARED_META + `
### 额外约束
- 只使用只读工具进行分析
- 输出结构化的执行方案
- 明确每一步的输入/输出/风险
- 不执行任何实际修改
`;

const DAEMON_TASK_TURNS = 20;  // 守护任务最多20轮

// 启动守护进程
async function start(config: DaemonConfig) {
  // 1. 写入 PID 文件
  fs.writeFileSync(PID_PATH, process.pid.toString());

  // 2. 初始化 MCP 工具
  await mcpManager.initialize(config.mcpServers);

  // 3. 启动调度器
  const scheduler = new Scheduler(config.triggers);

  // 4. 启动 IPC HTTP 服务
  const server = createIPCServer(scheduler);
  server.listen(3051);
}

// 停止守护进程
async function stop() {
  const pid = readPID();  // 读取 PID
  if (pid && isProcessAlive(pid)) {
    process.kill(pid, 'SIGTERM');  // 优雅停止
    await cleanup(pid);            // 清理资源
  }
}

// 查看状态
function status() {
  const pid = readPID();
  return {
    running: pid && isProcessAlive(pid),
    pid,
    uptime: getUptime(pid),
    pendingTasks: scheduler.getPendingCount(),
  };
}

// Cron 表达式解析
function parseCron(cronExpr: string): CronFields {
  const [minute, hour, dayOfMonth, month, dayOfWeek] = cronExpr.split(' ');
  return {
    minute: parseField(minute, 0, 59),
    hour: parseField(hour, 0, 23),
    dayOfMonth: parseField(dayOfMonth, 1, 31),
    month: parseField(month, 1, 12),
    dayOfWeek: parseField(dayOfWeek, 0, 6),
  };
}

// 匹配当前时间
function matchesCron(cron: CronFields, date: Date): boolean {
  return cron.minute.has(date.getMinutes())
    && cron.hour.has(date.getHours())
    && cron.dayOfMonth.has(date.getDate())
    && cron.month.has(date.getMonth() + 1)
    && cron.dayOfWeek.has(date.getDay());
}

// 计算下一次触发时间
function getNextCronTime(cronExpr: string, from: Date): Date {
  const cron = parseCron(cronExpr);
  let next = new Date(from.getTime() + 60000); // 从下一分钟开始
  next.setSeconds(0, 0);
  while (!matchesCron(cron, next)) {
    next = new Date(next.getTime() + 60000);
  }
  return next;
}

export class PluginManager {
  private active: Map<string, ActivePlugin> = new Map();
  private commands: Map<string, CommandHandler> = new Map();

  async loadFromConfig(config: AIConfig): Promise<PluginLoadResult[]> {
    const results: PluginLoadResult[] = [];
    for (const [name, pluginConfig] of Object.entries(config.plugins ?? {})) {
      try {
        const plugin = await this.loadPlugin(name, pluginConfig);
        this.active.set(name, plugin);
        results.push({ name, status: 'loaded' });
      } catch (err) {
        // 单个插件失败不影响其他插件
        results.push({ name, status: 'failed', error: String(err) });
      }
    }
    return results;
  }

  // 插件 API
  registerTool(name: string, tool: ToolDefinition) { ... }
  registerCommand(name: string, handler: CommandHandler) { ... }
  getConfig(pluginName: string, key: string): unknown { ... }
}

export interface PreToolHookResult {
  updatedInput?: Record<string, unknown>;  // 修改工具参数
  block?: { reason: string };              // 阻止执行
  additionalContexts?: string[];            // 注入额外上下文
}

export interface PostToolHookResult {
  updatedResult?: Partial<ToolResult>;     // 修改执行结果
  additionalContexts?: string[];           // 注入额外上下文
  preventContinuation?: boolean;           // 阻止 Agent 继续循环
}

// 配置示例
export const LIFECYCLE_EVENTS = [
  'session_start', 'user_prompt_submit', 'pre_compact', 'post_compact',
  'session_end', 'subagent_start', 'subagent_stop',
  'post_tool_use_failure', 'stop', 'stop_failure',
] as const;

toolHooks:
  - tools: ["write_file", "file_system*"]    # 通配符匹配
    pre: "npx eslint --fix {{file}}"         # 写入前自动格式化
    post: "npm test -- --changed"            # 写入后自动运行测试
    prePhase: "beforeConfirm"                # 在安全确认前执行
    timeout: 15000                           # 15秒超时

  - tools: ["shell"]
    pre: "echo '即将执行: {{command}}'"      # 执行前记录日志
    post: "echo '执行完成，退出码: {{exitCode}}'"
    timeout: 5000

lifecycleHooks:
  session_start:
    - script: "echo '新会话启动' && npx tsc --noEmit"
      timeout: 30000
  session_end:
    - script: "echo '会话结束，清理临时文件'"
  stop_failure:
    - script: "notify-send 'AI-CLI 任务失败'"
      timeout: 5000

# ============================================
# AI-CLI 完整配置文件
# ============================================

# ---- Provider 配置 ----
# 指定默认 Provider 和各 Provider 的连接信息
provider: kimi
providers:
  kimi:
    baseURL: https://api.moonshot.cn/v1
    apiKey: sk-xxx
    model: kimi-k2
  deepseek:
    baseURL: https://api.deepseek.com/v1
    apiKey: sk-xxx
    model: deepseek-chat
  openai:
    baseURL: https://api.openai.com/v1
    apiKey: sk-xxx
    model: gpt-4o

# ---- 外部 MCP 服务器 ----
# 通过 stdio 或 SSE 接入第三方工具服务
mcpServers:
  filesystem:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/path"]
  github:
    url: https://api.github.com/mcp/sse
    headers:
      Authorization: "Bearer ghp_xxx"
    dangerLevelOverride:
      search_repositories: safe       # 搜索自动放行
      create_issue: danger            # 创建Issue必须确认

# ---- 工具 Hook ----
# 在工具执行前后注入自定义脚本
toolHooks:
  - tools: ["write_file", "file_system*"]
    pre: "npx eslint --fix {{file}}"
    post: "npm test -- --changed"
    prePhase: "beforeConfirm"       # beforeConfirm | beforeExecute
    timeout: 15000

  - tools: ["shell"]
    pre: "echo '执行: {{command}}' >> /tmp/ai-cli.log"
    timeout: 5000

# ---- 生命周期 Hook ----
# 在会话关键节点执行脚本
lifecycleHooks:
  session_start:
    - script: "echo '新会话启动' && npx tsc --noEmit"
      timeout: 30000
  session_end:
    - script: "echo '会话结束，清理临时文件'"
  stop_failure:
    - script: "notify-send 'AI-CLI 任务失败'"
      timeout: 5000

# ---- 插件 ----
# 加载 npm 包形式的插件
plugins:
  my-custom-plugin:
    package: "@my-org/ai-cli-plugin"
    config:
      apiKey: "xxx"
      region: "cn"

# ---- Agent 配置 ----
agent:
  maxTurns: 50                    # 最大循环轮次
  compressionThreshold: 80000     # 上下文压缩阈值（tokens）
  autoExtract: true               # 自动记忆提取
  autoDream: true                 # AutoDream 后台整理

# ---- 守护进程 ----
daemon:
  port: 3051                      # IPC 端口
  tasks:
    - name: "每日代码Review"
      trigger: "cron"
      schedule: "0 9 * * 1-5"     # 工作日每天9点
      prompt: "审查最近24小时的代码变更"
      maxTurns: 20