设计地图 · Arkk 的笔记

本文展开设计原理中的工程位置与结果三指标，帮助从“想改善什么”逐层找到“具体可以改什么”。各分支是可选择的方向，不是需要全部实现的功能清单。

先找到真实瓶颈，再选最直接的改法。收益看整个任务：便宜模型若反复返工，可能更贵；上下文缩短若丢失必要信息，可能更慢；增加检测若引入误报，未必改善效果。

工程位置

确定想改善的问题后，再选择改动落在哪里。同一种表现可能有不同原因，不必为每个问题新增一层机制。

模型
- 推理、指令遵循、模态能力
- 延迟与费率
核心机制
- 核心循环与任务推进
- 工作模式切换，例如 EnterXXMode?
- 多 Agent 分工与交接
运行时
- 持续执行与状态保存
- 异常检测与恢复
工具
- 接口与实际执行
- 结果反馈与外部能力接入
上下文管理
- 信息召回与记忆
- 压缩、缓存与工具输出管理
自反馈
- 结果检查与偏差识别
- 完成验证

结果三指标

速度
- 模型推理耗时
  - 单次推理延迟
    - 选择更快的模型
    - 按任务难度调整推理强度和输出长度，避免削弱必要判断后增加返工
  - 推理轮次
    - 固定流程程序化，减少不需要模型判断的往返
      - 例如项目初始化时注入 file_tree 与 task_read 的必要结果，直接提供文件树与任务记录
- 执行时长
  - 单个工具耗时
    - 优化慢工具、缩小查询范围、复用已有结果
  - 串行等待
    - 并行调用互不依赖的工具
    - 将可独立交付的任务分给子 Agent
      - 并行收益需覆盖启动、交接和整合成本；有依赖的工作仍需串行
- 用户等待体验
  - 流式输出
  - 尽早提供可用的阶段结果
    - 改善感知等待，不一定缩短总完成时间
成本
- 模型费率
  - 提供轻量与高能力模型，例如 lite/premium 两档
  - 按任务难度、模态与错误后果分流
    - 简单、易验收的任务交给便宜模型
    - 可比较的任务与模型搭配
      - UI—kimi
      - 简单任务—minimax2.1max
      - 快速开发—MiniMAX / Claude
      - BUG 修复—Codex
    - 模型选择随实测更新，不固定为品牌与任务的一一对应
- 输入 token
  - 上下文长度
    - 历史对话
      - 压缩已完成过程，保留当前目标、关键约束、未决事项和证据入口
      - 选择压缩或重置时机
        
        达到上下文容量阈值时压缩记忆
        
        在检查点（checkpoint）通过 is_new_topic 判断话题是否切换，并建议清空或压缩
        
        按闲置时间清理，例如空闲超过 24 小时清空 session 上下文
        
        长时间闲置不等于信息失效；清空前保存继续任务所需的状态，并说明信息损失
    - 工具执行结果
      - 大结果文件化，返回摘要、状态和检索入口
        
        文件化之后仍需容易找回，不能只隐藏输出
    - 文件阅读
      - 先看结构、函数与类的定义及行号，再精确读取实现
        
        概览不能替代完成任务所需的实现细节
      - 大文件按需检索
        
        只有维护需要时才拆文件，不为节省一次读取破坏结构
    - 探索过程
      - 复用项目知识与历史结果，减少重复探索
      - 子 Agent 隔离独立探索，只向主 Agent 返回必要结果
        
        例如让从空上下文开始的子 Agent 探索仓库
        
        减轻主上下文，但会增加子 Agent 调用与交接成本
      - 检索增强（RAG），按需召回信息
        
        留意召回遗漏，不能把未检索到当成不存在
  - 重复输入的计费
    - Prompt Cache
    - 合理设置缓存保留时间
      - 例如对话结束后将缓存延长到 15 分钟，供后续对话复用
      - 收益取决于供应商计费、命中率与复用间隔；延长缓存也可能有成本
- 输出与推理 token
  - 避免重复解释和无用长输出
  - 按任务调整推理预算，不削减必要推理与验证
- 调用次数
  - 用脚本替代固定操作
  - 改善工具反馈，尽早暴露失败与前置条件，减少返工
    - 不为减少次数把过多职责塞进一次调用，导致失败后难以恢复
- 工具/API 费用
  - 缓存可复用结果，避免重复生成、下载与查询
  - 使用批处理或更合适的服务
    - 同时考虑时效、隐私、质量与维护成本
效果
- 上下文
  - 目标与标准
    - 明确目标、偏好和验收标准，先区分需求未表达与模型做不到
    - 方向未定时，用候选方案、小样和对比共同澄清
      - 设计任务可明确参考风格，以及颜色、字体、间距等 design token
  - 代码召回
    - 精确名称与符号：关键词搜索、符号索引
    - 依赖与调用关系：调用关系图、图检索
    - 语义相似与模糊描述：语义检索
      - 按问题组合方法，图检索不是向量检索的通用替代
  - 环境反馈
    - 测试与构建结果
    - 浏览器自动化
      - 基于模板的快速测试
      - 真实使用路径的交互验证，补足模板覆盖不到的行为
    - 截图与实际交互反馈
  - 记忆
    - 长期知识
      - 在项目文档、规则或 Skill 中维护稳定知识
        
        例如用 xxrules 一类规则文件提供项目约定
        
        明确权威来源和更新责任，不把所有历史变成常驻上下文
      - 保留可检索的历史对话，按需查回
    - 当前任务状态
      - 维护目标、待办、进展、阻塞与完成依据
        
        例如 TODO 模式，用待办与完成状态支持持续推进
        
        记录应帮助决定下一步，不只是增加维护工作
- 智力
  - 理解、推理、规划、设计与问题定位
    - 必要信息与反馈已经提供，仍无法正确判断时，考虑更强或更适合的模型
  - 任务分工
    - 可拆分且能独立验收的任务，交给各自适合的模型
    - 不仅靠增加提示词或检测层弥补根本能力不足
- 能力
  - 工具设计
    - 命令执行：状态、错误与恢复路径是否清楚
    - 文件读取、写入与编辑：能否准确定位、修改并核对结果
    - 交互入口：Interaction 工具
    - 明确区分成功、失败与未知结果
  - 外部能力接入
    - API、MCP、专用工具
      - 确认权限、环境与可靠性；工具多不等于任务能力强
  - 方法与经验
    - Skill 提供成熟方法、经验与配套资源
      - 方法不能替代实际工具、环境与权限
  - 完成验证
    - 测试、构建、浏览器操作、人工验收入口
      - 检查真实交付物，不以文字宣称或工具调用成功代替任务完成

具体场景与问题

这些问题通常跨越多个指标，需要组合前面的手段。

开发阶段
- 首次开发
  - 只做出 Demo、过早结束
    - 提前明确可用范围与完成依据
    - 保留剩余工作，用真实使用路径验收
- 迭代开发
  - 修改新功能时破坏旧功能
    - 维护有效规格与回归测试
    - 明确应保留的行为，变更规格须有依据，不靠一句“不要破坏”保证
  - 持续排障陷入循环
    - 检查缺的是证据、能力，还是新的排查假设
    - 必要时保存状态后换方法、换模型或重置上下文
      - 不自动把重启视为解决方案；也要让用户知道何时可以重置、会失去什么
界面设计
- 模板化、风格不一致
  - 明确视觉方向与设计变量
- 定位用户要修改的页面内容
  - 虚拟编辑：选择页面元素，将元素类型和源码位置提供给模型
  - 动态渲染内容还需提供实际元素与值，区分同一源码生成的不同内容
- 实现偏离预期
  - 用实际渲染与交互反馈迭代
特化需求
- 客服
  - 补充业务知识、行动权限与场景验收
- 部署
  - 模板脚本
  - Kamal 等私有化部署方案
    - 结合项目环境选择，不预设一种工具适合所有项目

选定方向后，按专题索引进入具体的设计、验证或维护方法。