AI打工加油包 · ai-work-booster

让AI从"能干活"升级到"干好活"。

对任意系统进行深度架构分析，用严格的工程方法论约束AI的分析过程，输出准确度更高、更可落地的改进方案。覆盖四大维度：核心引擎、权限安全、工具/插件系统、性能优化。

---

执行流程

Phase 0：信息收集（优先读现有代码/文档）

并行执行以下探测：

Tool 1: 读取入口文件（main/index/app）—— 了解启动流程
Tool 2: 读取核心模块（engine/core/handler）—— 了解主循环
Tool 3: 列出顶层目录结构（depth=2）—— 了解模块划分
Tool 4: 读取 README / 架构文档 —— 了解设计意图

若用户直接提供文字描述（无代码库），跳过 Tool 1-4，直接进入 Phase 1。

---

Phase 1：诊断——问题识别矩阵

对收集到的信息，按以下七个维度打分（1-5分）并标注严重度：

严重度判定：

• 🔴 极高：影响研发效率或系统稳定性，需优先修复
• 🟠 高：影响扩展性或安全性，中期规划修复
• 🟡 中：影响维护性，可纳入技术债计划

输出格式：

### 问题诊断结果

| 问题 | 具体表现 | 严重度 | 优先级 |
|------|---------|--------|--------|
| [描述] | [具体代码/文件/行为] | 🔴 | P0 |

---

Phase 2：改进方案——四大维度

根据诊断结果，只输出涉及严重度 🔴🟠 的维度，🟡 问题合并到"技术债清单"简要列出。

---

维度 A：核心引擎 / Agent Loop

适用场景：主循环文件行数过大、职责混杂、状态管理混乱

改进模式：微内核 + 管道-过滤器（Microkernel + Pipeline-Filter）

改进前：
  [MonolithicEngine] ← LLM调用 + 工具调度 + 状态管理 + 权限检查 全混一起

改进后：
  [AgentKernel]（消息总线 + 生命周期）
       ↓
  Pipeline: [PreProcess] → [PermCheck] → [LLMDispatch] → [ToolExec] → [PostProcess]
       ↓
  ExtensionPoints: [ContextCompressor] [RetryPolicy] [ToolRegistry]

显式状态机设计（将隐式状态变为可序列化的显式状态）：

IDLE → PREPARING → THINKING → EXECUTING/STREAMING → MERGING → DONE
                      ↓ token超限                    ↓ 工具调用
                  COMPRESSING                    TOOL_EXECUTING

关键改进点：

• 每个 Stage 实现统一接口 process(context) → Result<Context, Error>
• Stage 可独立单元测试，可热插拔
• 新功能 = 新增 Stage，不修改现有代码（开闭原则）

权衡：上下文对象传递有额外拷贝开销 → 使用不可变结构 + 结构共享缓解

---

维度 B：权限与安全系统

适用场景：权限逻辑内嵌业务代码、无审计日志、规则硬编码

改进模式：零信任 + 声明式策略引擎（Zero Trust + Policy Engine）

每次操作的决策路径：
  请求 → 规范化 → 快速路径(O(1) Trie) → 静态规则评估 → 风险评分
                                                         ↓ 不确定时
                                                    AI分类器(异步，超时保守拒绝)
                                                         ↓
                                              最终决策 + 写入审计事件流

策略声明式配置（与代码解耦，独立演进）：

rules:
  - id: "allow-workspace-read"
    effect: ALLOW
    action: ["file.read"]
    resource: { path: { pattern: "^/workspace/.*" } }

  - id: "deny-system-files"
    effect: DENY
    priority: 100
    action: ["*"]
    resource: { path: { pattern: "^/(etc|sys|proc)/.*" } }

  - id: "escalate-destructive"
    effect: ESCALATE          # 新增效果：异步升级确认
    action: ["file.delete", "process.kill"]
    escalation: { type: "user-confirmation", timeout: 30s, fallback: DENY }

最小权限能力矩阵：

每个工具/插件必须声明：
  required_capabilities:  [必须的权限列表]
  optional_capabilities:  [可选权限，用户授权后才有]
  forbidden_capabilities: [明确不需要的权限，系统强制拒绝]

运行时实际权限 = required ∪ (optional ∩ user_granted) - forbidden

关键改进点：

• 规则存配置文件，无需改代码即可调整策略
• 所有权限决策写入不可篡改的事件流，满足审计合规
• AI分类器异步执行，不阻塞主流程；超时则保守拒绝

---

维度 C：工具 / 插件系统架构

适用场景：工具靠硬编码注册、顺序执行、无隔离、无版本管理

改进模式：注册中心 + 命名空间 + 能力合约 + DAG 调度（Registry + Contract-First + DAG Scheduler）

注册中心架构：

ToolRegistry
  ├── NamespaceManager      filesystem.* / process.* / network.*
  ├── SchemaStore           统一类型注册，跨工具复用
  ├── CapabilityMap         工具→能力的映射
  └── VersionManager        语义化版本 + 兼容层

ToolExecutionBus
  ├── DAGScheduler          自动分析依赖，并行执行无依赖工具
  ├── SandboxManager        虚拟文件视图 + 资源限制
  └── ResultMerger          聚合并行结果

工具能力合约（Contract-First，权限系统精确授权的基础）：

ToolContract {
  input_schema:    强类型输入（JSON Schema 2020）
  output_schema:   强类型输出
  side_effects:    [FILESYSTEM, NETWORK, PROCESS]  ← 显式声明副作用
  idempotent:      Boolean   ← 是否幂等（影响重试策略）
  cacheable:       Boolean   ← 结果是否可缓存
  timeout:         Duration
  retry_policy:    RetrySpec
}

DAG 自动并行：

LLM 输出多个 tool_call → ToolCallAnalyzer 构建依赖 DAG

  tool_A ─────────────────────► tool_D
                                  ↑
  tool_B ──► tool_C ─────────────┘
  tool_E（独立）

调度：
  第1批：[tool_A, tool_B, tool_E] 并行
  第2批：[tool_C]（等 tool_B）
  第3批：[tool_D]（等 tool_A + tool_C）

组合工具（无需修改核心，声明式组合现有工具）：

CompositeToolDefinition:
  name: "git.safe_commit"
  steps:
    - tool: "bash.run"
      args: { cmd: "{{test_command}}" }
    - tool: "git.add"
      condition: "prev.exit_code == 0"
    - tool: "git.commit"
      condition: "prev.staged_count > 0"
  on_failure: ABORT_WITH_ERROR

---

维度 D：性能优化策略

适用场景：上下文压缩粗糙、缓存无失效策略、重试一刀切、流式无背压

D1 智能上下文压缩（替代"固定保留最近N轮"）：

重要性评分 = f(
  时间衰减:  e^(-λ × age_in_turns)         ← 越旧越不重要
  引用频率:  log(1 + reference_count)       ← 被引用越多越重要
  语义密度:  unique_concepts / token_count  ← 信息密度
  角色权重:  {system:3, user:2, tool:1.5}
  错误加权:  error_bonus = 2.0              ← 错误信息总是重要
)

分层策略：
  L1 高分 → 原文保留
  L2 中高分 → LLM摘要压缩
  L3 中分 → 语义聚类合并相似对话
  L4 低分 → 只保留标题/关键词

目标：在 token_budget 约束下，最大化保留信息量

D2 三级缓存架构：

L1 进程内 LRU  │ ~100MB  │ TTL: 5min    │ 工具结果、文件内容      │ 命中率目标 >60%
L2 会话级缓存  │ ~500MB  │ TTL: 会话    │ 文件树、权限决策         │ 命中率目标 >85%
L3 持久化 CAS  │ 无限    │ 内容哈希 TTL │ 相同prompt的LLM响应     │ 命中率目标 >95%

失效策略：
  L1/L2: TTL + 文件系统变更事件驱动失效 + 容量LRU
  L3:    内容寻址（Content Addressable Storage），内容不变永不失效

D3 自适应重试策略（按错误类型差异化处理）：

TRANSIENT_NETWORK → 指数退避 + 全抖动
RATE_LIMIT        → 遵循 Retry-After 响应头，不盲目等待
SERVER_OVERLOAD   → 退避 + 降级到备用资源
TOKEN_LIMIT       → 不重试！压缩上下文后重发
AUTH_ERROR        → 不重试！立即上报用户

公式：wait = min(base × 2^attempt + rand(0, jitter), max_wait)

熔断器（Circuit Breaker）：
  CLOSED → (失败率>50%) → OPEN(快速失败) → (超时恢复) → HALF_OPEN → 成功 → CLOSED

D4 背压感知流式输出：

LLM Token流 → Buffer(N) → Transformer → Dispatcher
                  ↑                          ↓
             背压信号 ←── 消费者速度感知  UI流/工具流/审计流

背压协议：消费者通过 request(n) 告知可接受量，生产者不超发
缓冲区满时策略：DROP_LATEST / DROP_OLDEST / BLOCK_PRODUCER（按场景选择）

D5 优先级启动预加载：

T=0ms   [P0] 显示UI骨架 + 核心配置 + 认证初始化  ← 用户立感响应
T=50ms  [P1] 常用工具集 + LLM连接池预热           ← 80%场景就绪
T=150ms [P2] 全量工具 + 完整Schema预计算           ← 100%功能就绪
T=500ms [P3] 后台索引 + 预生成摘要                 ← 不阻塞主流程

---

Phase 3：整体改进架构图

根据分析结果，生成该系统的改进后整体架构图（ASCII），包含：

• 分层结构（表示层 → 应用层 → 领域层 → 基础设施层）
• 各层主要组件
• 横切关注点（可观测性：Tracing / Metrics / Logging）
• 数据流向

---

Phase 4：对比表 + 迁移路线

改进前后对比（只列出有实质改进的维度）：

综合质量属性评分：

Strangler Fig 渐进迁移路线（避免大爆炸重写）：

Phase 1 (0~3月): 基础设施层——不动业务逻辑
  → 多级缓存系统（旁路部署，不影响现有逻辑）
  → 审计事件流（旁路记录）
  → 工具注册中心（兼容现有工具，渐进迁入）
  → 可观测性基础设施（TraceID注入）

Phase 2 (3~6月): 领域层剥离
  → 权限系统从业务核心剥离为独立模块
  → 上下文压缩升级为智能评分版本
  → 工具系统增加沙箱层

Phase 3 (6~12月): 核心引擎重构
  → Agent Loop 重构为管道-过滤器
  → 微内核引入，原核心降为兼容适配层
  → 多代理协调引入 DAG 调度

Phase 4 (12月+): 持续演进
  → 策略可视化调试器
  → 架构守护门禁（防止新的上帝对象出现）

---

输出原则

1. 只输出相关维度：用户系统没有工具系统？跳过维度 C。问题都是 🟡？只给技术债清单。
2. 语言无关：所有方案用架构语言描述，不绑定具体实现语言，代码示例用伪代码。
3. 权衡透明：每个改进方案必须说明潜在代价和缓解措施。
4. 可落地：给出可执行的 Strangler Fig 迁移路线，而非只有理论。
5. 简洁优先：ASCII 图优先于文字描述，表格优先于列举。

---

参考资料

详细方法论见：

• references/patterns.md —— 设计模式详解（微内核、管道-过滤器、零信任等）
• references/anti-patterns.md —— 反模式识别（上帝对象、霰弹手术、过度工程等）
• references/migration.md —— Strangler Fig 等迁移策略详解
• references/tradeoffs.md —— 各改进方案的权衡分析矩阵