问题域/PD-09

Human-in-the-Loop

Human-Agent Interaction

Agent 执行中如何在关键节点暂停、向用户澄清、获取审批。人机协作的关键。

子问题

1.暂停点设计：哪些操作需要人工确认

2.澄清请求：Agent 不确定时如何向用户提问

3.审批流程：危险操作的审批机制

4.反馈整合：用户反馈如何影响后续执行

5.多轮交互：复杂任务中的多轮人机对话

6.升级策略：retries 次数与 escalateAfter 时间的双条件升级判定

7.通知容错：单个 Notifier 插件失败不影响其他通道的隔离机制

8.全局完成检测：所有 session 完成后的 all-complete 聚合通知

9.操作边界声明：用 DO NOT 清单显式定义 Agent 不可越权的操作范围

10.环境感知交互：根据本地/服务器环境自动调整人机交互策略（自动提取 vs 手动导入）

11.Doctor 驱动修复循环：Agent 不记忆修复步骤，每次依赖诊断输出决定下一步

12.输入源抽象化：如何统一处理 CLI、Web UI、桌面应用等不同环境的用户输入

13.非阻塞中断：如何在不阻塞事件循环的前提下实现实时中断与恢复

14.中断后消息历史修复：如何为未完成的工具调用生成假结果，保持上下文完整性

15.结构化输入 UI 自动生成：如何从 Pydantic schema 自动生成表单并验证

16.人类作为 Agent：如何将人类包装为 Agent 角色，使其可参与任何工作流

17.输入源运行时切换：如何在不修改 Agent 代码的前提下切换输入源（如测试时用 Mock）

18.WebSocket 连接管理：如何处理断线重连、超时等网络异常

19.多模态输入简化：如何自动简化单文本块为字符串，同时保留多模态列表结构

20.澄清回环无上限保护：用户反复提供模糊回复时缺少最大轮次熔断

21.Gradio 前端与 interrupt 的集成模式：chat_handler 需区分新查询与暂停恢复两种调用路径

22.命令式 vs 请求式 HITL：用户直接发命令绕过 LLM 与通过 LLM 理解意图的取舍

23.首次交互检测：如何准确判定用户是否为首次使用并触发引导流程

24.引导可跳过性：强制引导 vs 允许跳过的用户体验权衡

25.双通道控制一致性：REST API 和 CLI 对同一资源操作时的状态同步

26.批量并行工具调用的一次性审批：多个工具同时触发 interrupt 时的合并审批策略

27.审批 UI 焦点锁定：防止用户在未做决策前切换焦点导致审批悬挂

28.工具描述格式化器：为不同工具类型定制审批上下文展示（diff、命令、文件路径）

29.HITL 迭代上限：Agent 反复重试被拒绝命令时的安全熔断

30.插件优先级冲突：同一 hook point 多个插件的执行顺序与上下文竞争

31.交互补发机制：WebSocket 连接晚于交互请求时的竞态条件处理

32.多轮修改上限：用户反复修改计划时的收敛策略（max_modification_rounds）

33.中间件注册顺序：ClarificationMiddleware 必须在管道末尾，与其他中间件的执行顺序依赖关系

34.空壳工具与中间件的职责边界：工具定义 schema 供 LLM 调用，中间件实现真实逻辑的分工模式

35.前端消息分组渲染：将 ToolMessage 按工具名分类为独立消息组的 UI 适配策略

36.反作弊 attestation 设计：如何用关键词检查而非 checkbox 强制用户描述具体修改

37.批量操作分数影响预估：大规模 wontfix 前 deepcopy 预演计算 strict score delta

38.盲审 provenance 注入：CLI 层覆盖审查者自报来源，确保来源不可伪造

39.skip 自动 resurface：temporary skip 设置 review_after 扫描次数后自动回到队列

40.外部审查 attestation 差异化：resolve 要求 'not gaming'，external 要求 'without awareness' + 'unbiased'

41.反馈有效性判定：用户反馈是纠正、补充还是无关内容的自动分类

42.LLM 输出 ID 幻觉：LLM 生成的记忆 ID 可能不存在，需要去幻觉修正

43.修改比例失控：LLM 可能生成与原文完全不同的'更新'，需要比例安全阀

44.关键词替换 vs 语义修改路由：同一反馈入口需自动分流到精确替换或语义理解路径

45.批量 UPDATE 审核：多条更新操作时 LLM 幻觉风险累积，需二次审核机制

46.结构化字段级修订：用户逐字段修改 Agent 产出的结构化内容时的类型校验与交互流程

47.复合确认指令：用户在确认当前任务的同时附带修改后续任务的指令解析

48.人机角色互换：将人类包装为 LLM 接口，使任何 Agent 角色可无缝切换为人类驱动

49.安全地板设计：即使审批关闭，危险命令仍强制拦截的不可绕过机制

50.已审批命令缓存：用户批准后相同命令自动放行的记忆策略

51.Hook 熔断器：外部脚本 handler 连续失败后的自动禁用与冷却恢复

52.dry-run 审计：Block/Modify 仅记录日志不实际生效的调试模式

53.六层策略合并：Global→Provider→Agent→Group→Sender→Sandbox 的 deny 累积优先策略

54.审批身份绑定：防止其他客户端重放审批 ID 的安全机制

55.多通道审批路由：同一审批请求转发到多个交互渠道的路由策略

56.审批超时降级：人工不响应时的 askFallback 安全降级策略

57.防重复提问：LLM 在多轮对话中反复提出相同澄清问题的抑制策略

58.澄清与执行的图拓扑选择：END 返回 vs interrupt 暂停两种暂停模式的适用场景

59.空壳工具注入：将澄清能力定义为工具 schema 而非图节点的条件注入策略

60.工具优先级排序：多工具并存时如何引导 LLM 优先使用自主工具而非求助人工

61.跨环境适配：同一 AskHuman 接口在 CLI/沙箱/A2A 不同运行环境下的输入源切换

62.Prompt 驱动 vs 代码驱动 HITL：纯靠系统提示词约束 LLM 行为的可靠性与可审计性权衡

63.递归依赖补全深度控制：缺失依赖链过长时的递归深度限制与性能影响

64.三模式语义一致性：不同节点对 skip 和 default 的语义定义不统一时的用户困惑

65.计划与执行的一致性验证：Agent 展示的计划与实际工具调用序列不一致时的检测机制

66.passthrough 旁路：特定 Agent 跳过 Planner 直接执行时的 HITL 绕过策略

67.asyncio.Task 不可序列化：进程重启后暂停状态丢失的恢复策略

68.双层暂停协调：Agno 框架工具级 is_paused 与 Planner 级 adequate:false 的优先级和互斥关系

69.LLM 判定可靠性：纯依赖 LLM 判定查询清晰度的准确性保证

70.澄清成本控制：多轮澄清累积的 LLM 调用成本优化

71.Gate 物化命名冲突：多个 formula 组合时 gate ID 的全局唯一性保证

72.发现式恢复延迟：轮询间隔与 gate 关闭到工作流恢复的响应时间权衡

73.角色推断误判：SSH URL 启发式对 fork contributor 的误分类及降级警告

74.运行模式运行时切换：用户在任务执行中动态调整信任级别而不中断会话

75.Hook stdin/stdout 协议：外部脚本通过 JSON stdin 接收参数、exit code 返回决策的标准化协议

76.影子仓库隔离：Checkpoint 快照不干扰项目原有 Git 仓库的隔离存储策略

77.SubAgent 权限继承控制：isInheritTools 开关决定子代理是否继承父代理全部工具权限

78.自动确认降级：测试/CI/快速模式下如何优雅跳过人工确认而不改变图拓扑

79.悬挂工具调用修复：interrupt 中断导致消息历史中 tool_call 未配对时的恢复策略

80.后台线程恢复：HTTP 请求线程与图执行线程分离时的上下文传递（Flask app_context/contextvars）

各项目的解法25 solutions

Signals

横向对比

维度	DeerFlow	Agent-Orchestrator	AgentReach	AgentScope	AgenticRAGForDummies	CoPaw	DeepAgents	DeepCode	DeepTutor	Desloppify	GPT-Researcher	MemOS	MetaGPT	Moltis	OpenClaw	Open	OpenManus	OpenStoryline	ValueCell	agentic-rag-for-dummies	Beads	iflow-cli	seedance-2	vibe-blog
暂停机制	Command(goto=END) 中断图执行，LangGraph checkpointer 持久化状态	LifecycleManager 30s 轮询检测 waiting_input/stuck，非阻塞式	三模式分流：--dry-run 纯预览 / --safe 只检查打印 / 默认自动执行	asyncio.CancelledError 异步中断，不阻塞事件循环	LangGraph interrupt_before 在 request_clarification 节点前暂停	APScheduler pause_job/resume_job + asyncio.Lock 保护	LangGraph interrupt() + checkpointer 持久化，Command(resume=) 恢复	Plugin hook point + asyncio.Future 异步等待，工作流在 run_hook 处暂停	—	CLI 命令式暂停：用户主动执行 resolve/skip/done 命令触发确认，非自动 interrupt	—	无显式暂停，反馈通过独立 API 端点异步提交，不中断对话流	Planner.ask_review 在 plan 生成和 task 完成后同步阻塞等待人类输入	oneshot channel + tokio::timeout 120s 异步等待	Promise-based 异步等待，register() 返回 Promise，resolve()/expire() 触发	主版本用 Command(goto=END) 返回提问终止图；Legacy 用 LangGraph interrupt() 原语暂停	无显式暂停，LLM 自主决定调用 ask_human 工具	Prompt 驱动：系统提示词要求 Agent 先输出 Markdown 计划，用户文字确认后才调用工具，无代码级 interrupt	asyncio.Event.wait() 协程级挂起，100ms 轮询检测 + SSE 推送	LangGraph interrupt_before 在空壳节点前暂停	Gate Issue 物化：gate 编译为独立 issue，通过 blocks 依赖阻塞后续 step	四模式分级：yolo/accept-edits/plan/default，Shift+Tab 运行时切换	—	LangGraph 原生 interrupt()，图执行自动暂停，MemorySaver 持久化状态
澄清类型	5 种 Literal 枚举：missing_info/ambiguous_requirement/approach_choice/risk_confirmation/suggestion	无结构化澄清类型，依赖 Agent 自身的 terminal output 检测	input() 阻塞式逐步收集，每步支持回车跳过	通过 UserAgent 获取自由文本或结构化输入	QueryAnalysis Pydantic 结构化输出，is_clear 布尔判断	无澄清机制，用户通过 /command 直接控制	无独立澄清机制，仅工具级 Approve/Reject/Auto-approve 三选项	结构化 InteractionRequest（type/title/data/options），LLM 生成引导问题	—	关键词 attestation：要求自然语言包含 'I have actually' + 'not gaming' 两个短语	—	LLM 判定三类态度（dissatisfied/satisfied/irrelevant），非枚举式澄清	confirm/change/redo/exit 四种关键词 + 自由文本复合指令	无结构化澄清，仅 Approved/Denied/Timeout 三态决策	三级决策模型：allow-once / allow-always / deny	ClarifyWithUser 结构化输出（need_clarification + question + verification 三字段）	自由文本，单一 inquire 字符串参数	自然语言对话式：Agent 用 Markdown 展示计划，用户用自然语言确认或修改	双层：Agno UserControlFlowTools 结构化字段 + PlannerResponse.adequate 自然语言	LLM 结构化输出判定（Pydantic QueryAnalysis）	5 种 Gate 类型枚举：human/mail/timer/gh:run/gh:pr	—	—	结构化大纲确认（confirm_outline），含 title/sections/narrative_mode 完整字段
状态持久化	LangGraph ThreadState + checkpointer，中断后状态自动保存	flat file metadata（key=value），updateMetadata 原子写入	YAML 文件 ~/.agent-reach/config.yaml + chmod 600	中断时生成假 tool_result 保持消息历史完整性	InMemorySaver checkpointer，支持跨请求恢复	文件标记（.bootstrap_completed）+ 内存状态（CronJobState）	依赖 LangGraph checkpointer（InMemorySaver 或 PostgresSaver）	WorkflowTask.pending_interaction 内存存储，WebSocket 补发解决竞态	—	JSON state 文件持久化 attestation_log + assessment_import_audit 审计链	—	GraphStore 持久化，旧记忆 archived + covered_history 版本链	working_memory 暂存未确认反馈，confirm 后清空，无磁盘持久化	内存 HashMap + HashSet，进程重启丢失已审批缓存	纯内存 Map + 15s grace period，不持久化，重启丢失	interrupt 依赖 MemorySaver checkpointer；主版本无需持久化（END 后重新进入）	无持久化，input() 同步阻塞等待	ArtifactStore 按 session_id + node_id 隔离存储 JSON，支持跨轮次复用	内存 ExecutionContext + ConversationStatus 数据库持久化，asyncio.Task 不可序列化	InMemorySaver + thread_id 会话绑定	Dolt 数据库持久化 gate issue，状态通过 issue 生命周期管理	Checkpoint Git 影子仓库快照，保存文件+会话+工具调用三维状态	—	MemorySaver checkpointer 自动保存，snapshot.next 检测暂停，Command(resume=...) 恢复
实现层级	三层：Prompt 强制优先级 → 空壳工具 → 中间件拦截	核心层 LifecycleManager + 4 个 Notifier 插件 + Reaction 引擎	CLI argparse 参数级，无中间件/Hook 层	输入抽象层 + Agent 包装层 + 中断处理层三层设计	图拓扑级：空壳节点 + 条件边 + 回环边	三层：reply() 命令拦截 → pre_reasoning 钩子 → Cron REST/CLI	三层：HumanInTheLoopMiddleware → LangGraph interrupt → CLI ApprovalMenu	四层架构：Plugin → Registry → Integration → WebSocket/API	—	CLI 命令层：attestation 验证在 argparse handler 中，非中间件或图节点	—	独立 MemFeedback 模块，与对话引擎解耦，通过 SingleCubeView 路由	三层：Planner(计划级) + ActionNode(节点级) + HumanProvider(LLM级)	三层：ApprovalManager 命令级 + HookRegistry 事件级 + ToolPolicy 策略级	四层架构：Agent→Gateway→安全校验→多通道 UI	图节点级：clarify_with_user 和 human_feedback 均为独立图节点	工具层，AskHuman 继承 BaseTool	三层：Prompt 层（计划审批）+ 拦截器层（依赖补全）+ 节点层（mode 分发）	四层分离：Planner(信号) → PlanService(注册表) → Orchestrator(上下文) → SSE(推送)	图节点级（rewrite_query 判定 + request_clarification 暂停）	Formula 声明层 → Cook 物化层 → 验证层 → 发现层四层架构	外部脚本 Hook（spawn 子进程）+ 配置驱动，不改 CLI 源码	—	节点内部 3 行代码（interrupt 调用），不改变图拓扑结构
身份绑定	—	无审批身份绑定，ao send 通过 CLI 直接发送，无鉴权	无身份绑定，凭据存本地文件，依赖文件系统权限保护	—	—	BootstrapHook 引导用户创建 PROFILE.md 建立身份	无显式身份绑定，审批通过 asyncio.Future 在同一进程内传递	task_id 绑定，POST /respond/{task_id} 需匹配 waiting_for_input 状态	—	session token 绑定：128-bit 随机 token + session_id 双重验证防重放	—	—	无身份绑定，任何终端用户均可响应审查请求	requestId 为 UUID，resolve 时无身份校验（任何客户端可响应）	deviceId 优先 + connId fallback，防审批 ID 重放攻击	—	无，终端 input() 无身份验证	—	ExecutionContext.validate_user() 校验 user_id 一致性，防跨用户重放	—	gate issue 通过 ID 命名规范绑定到 molecule（{mol}.gate-{step}）	—	—	task_id 绑定 _interrupted_tasks 字典，无显式身份校验
多通道转发	—	notificationRouting 按 4 级 priority 路由到多个 Notifier 插件	—	—	—	—	交互式用 Textual ApprovalMenu，非交互式用 allow-list 自动决策	WebSocket 广播 + REST API 响应，前端 useStreaming 统一处理	—	—	—	—	set_human_input_func 全局替换输入源，支持 CLI/WebSocket/API 切换	GatewayApprovalBroadcaster 广播到所有 WebSocket 客户端	Discord 按钮 + Slack Actions + Web UI + Unix Socket 四通道并行	—	仅终端 stdin，A2A 协议可暴露但未实现路由	—	—	—	mail gate 通过 BD_MAIL_DELEGATE 委托外部邮件服务	Notification Hook 支持 Slack/Email 等多通道路由转发	—	SSE 单通道推送 outline_ready 事件到前端
审查粒度控制	—	Reaction 引擎 auto/retries/escalateAfter 三参数控制自动化程度	Tier 0/1/2 三级渠道分类，按平台复杂度分级	—	—	—	interrupt_on 字典按工具名配置，每个工具独立 InterruptOnConfig	—	—	四级风险分层：temporary(无)→permanent(attest+note)→batch(二次确认)→external(盲审token)	—	LLM 三级审核链：judgement → compare → compare_judge，≥5 条 UPDATE 触发二次审核	ReviewMode/ReviseMode 枚举按 ActionNode 粒度控制 HUMAN/AUTO 策略	ApprovalMode×SecurityLevel 矩阵 + SAFE_BINS + DANGEROUS regex 三层过滤	—	—	—	节点级：每个节点独立的 mode 参数，用户可逐节点控制执行策略	Planner 级（adequate:false 整体暂停）+ 工具级（is_paused 逐字段收集）	—	Step 级粒度，每个 Step 可独立声明 Gate	autoAccept 区分只读/写操作，只读自动放行写操作强制确认	—	大纲级别：用户可编辑标题、章节列表、叙事模式
人机角色互换	—	Terminal 插件（iTerm2/Web）提供人类 attach 能力，ao send 单向消息	—	UserAgent 将人类包装为 Agent，可插入任何工作流	—	—	—	—	—	—	—	—	HumanProvider 实现 BaseLLM 接口，Role.is_human=True 即切换为人类驱动	—	—	—	—	—	—	—	—	—	—	不支持，interrupt 仅用于人工确认/编辑
升级策略	—	retries 次数 + escalateAfter 时间双条件升级，支持 per-project 覆盖	doctor 驱动循环：Agent 自动修能修的，不能修的才问用户	—	—	—	无自动升级，reject 后由 Agent 自主决定下一步	—	—	—	—	—	—	超时直接 bail!，无自动升级或降级	—	—	—	—	TTL 过期（默认 1h）后 _cleanup_expired_contexts 自动取消并重置会话	—	Gate.Timeout 字段支持超时升级，checkGateSatisfaction 返回 escalated 标志	—	—	无超时升级，依赖用户主动操作
通知容错	—	Webhook 指数退避重试，Composio 30s 超时，各插件独立 try-catch	—	—	—	—	—	—	—	—	—	—	—	broadcast 失败仅 warn 日志，不阻塞审批流程	—	—	—	—	—	—	—	—	—	SSE 单通道，无多通道容错
dry-run 模式	—	—	完整支持：--dry-run 打印所有操作预览不执行任何变更	—	—	—	—	—	—	deepcopy 预演：批量 wontfix 前 deepcopy state 计算 strict score delta	—	—	—	HookRegistry.dry_run 标志，Block/Modify 仅日志不生效	—	—	—	—	—	—	bd create --dry-run 预览 issue 创建，不实际写入数据库	Plan Mode 先生成计划供用户审批，审批通过后才执行	—	—
自动跳过机制	无显式自动跳过，依赖 Prompt 引导 LLM 判断是否需要澄清	—	Tier 0 渠道全自动，本地环境自动提取 Cookie 失败静默降级	—	—	Bootstrap 明确支持用户跳过引导直接提问	auto_approve 会话标志 + shell allow-list 白名单门控	—	—	temporary skip 支持 review_after 参数，N 次扫描后自动 resurface	—	validity=false 且 attitude=irrelevant 时自动跳过修改，降级为纯添加	—	SAFE_BINS 60+ 命令 + custom allowlist + 已审批缓存三级自动放行	—	allow_clarification=False 配置开关跳过澄清；ask_for_clarification=False 跳过 Question 工具注入	—	三模式 mode 参数（auto/skip/default），LLM 根据对话上下文自主选择	—	—	isMachineCheckableGate 自动验证 CI/PR/timer gate，human/mail 跳过验证直接允许关闭	YOLO 模式自动批准所有工具调用，CI 环境零交互	—	三条件降级：mini 模式 / OUTLINE_AUTO_CONFIRM 环境变量 / 非交互式标志
操作边界声明	Prompt 中 STRICT ENFORCEMENT ❌/✅ 清单定义禁止行为	—	install.md 5 条 DO NOT 规则 + SKILL.md 不记忆步骤指令	—	—	SYSTEM_COMMANDS frozenset 白名单限定可用命令集	—	—	—	ATTEST_EXAMPLE 模板显式要求用户描述具体修改内容，不允许空泛声明	—	—	—	—	—	—	—	系统提示词声明 Agent 只能使用可用工具列表中的工具，不可用时必须告知用户	—	—	Gate 类型枚举限定可声明的等待条件，非法类型在 Validate() 阶段拒绝	SubAgent isInheritTools=false 显式限制工具集，最小权限原则	—	—
多源输入抽象	—	—	—	UserInputBase 基类支持 Terminal/Studio/自定义输入源	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—
结构化输入验证	—	—	—	Pydantic schema 自动生成 JSON Schema 并验证	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—
中断恢复策略	—	—	—	handle_interrupt 钩子生成友好提示，支持子类自定义	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—
工具调用中断	—	—	—	_async_generator_wrapper 捕获中断并设置 is_interrupted 标记	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—
输入源动态切换	—	—	—	override_instance/class_input_method 支持运行时切换	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—
多模态输入支持	—	—	—	blocks_input 支持文本/图片/音频/视频多种类型	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—
WebSocket 实时通信	—	—	—	StudioUserInput 通过 socketio 与前端双向通信	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—
多轮交互支持	Command(goto=END) 后用户响应触发图恢复，支持多轮澄清	—	—	—	回环边支持无限轮澄清，但无迭代上限保护	Bootstrap 引导为单轮注入，命令为单次执行无多轮	最多 50 次 HITL 迭代循环，reject 后 Agent 可调整策略重试	—	—	plan describe/note 支持多轮注释，skip→unskip→reopen 支持状态反转	—	单轮反馈模式，取 chat_history[-4:] 作为上下文，不支持多轮反馈对话	—	单轮审批，approved_commands 缓存避免重复询问	—	Legacy 通过 feedback_on_report_plan 列表累积多轮反馈，用 operator.add reducer	—	CLI while-True 循环 + messages 列表累积，支持无限轮次对话式迭代修改	_continue_planning 循环检测 has_pending_request，支持 Planner 连续多次请求输入	循环边（request_clarification → rewrite_query）支持无限轮澄清	—	—	—	—
自动确认降级	—	—	—	—	无降级机制，查询不清晰时必须等待用户回复	命令式设计无需确认，直接执行	—	—	—	—	—	—	—	—	—	测试中 ask_for_clarification=False 跳过交互；无超时自动批准机制	—	拦截器自动以 default 模式递归执行缺失依赖，无需用户手动确认前置步骤	—	—	—	—	—	—
反馈分类路由	—	—	—	—	无分类，用户回复统一注入 messages 重新分析	—	—	—	—	—	—	关键词替换 vs 语义修改双路径，LLM 自动分类路由	—	—	—	isinstance(feedback, bool) vs isinstance(feedback, str) 类型化分流	—	—	—	—	—	UserPromptSubmit Hook 正则匹配敏感信息，exit code 区分 block/allow	—	—
悬挂工具调用修复	DanglingToolCallMiddleware 注入合成 error ToolMessage	—	—	—	不涉及，interrupt 发生在工具调用之前的查询分析阶段	—	_build_interrupted_ai_message 重建中断时的 AIMessage + tool_calls	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—
澄清与执行的图拓扑选择	—	—	—	—	interrupt_before 暂停模式，非 END 返回	—	—	—	—	—	—	—	—	—	—	—	—	—	—	interrupt 暂停模式，用户回复后自动恢复	—	—	—	—
空壳节点设计	—	—	—	—	request_clarification 函数体为空，纯锚点	—	—	—	—	—	—	—	—	—	—	—	—	—	—	request_clarification 返回空字典，纯暂停点	—	—	—	—
命令分发模式	—	—	—	—	—	getattr 动态分发，统一 _process_{cmd} 签名	—	—	—	plan action 分发器：cmd_plan 按 plan_action 字符串分发到独立 handler 函数	—	—	—	—	—	—	—	—	—	—	—	—	—	—
双通道控制	—	—	—	—	—	Cron 同时暴露 REST API 和 Click CLI 两个控制通道	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—
首次交互检测	—	—	—	—	—	计数 user/assistant 消息数判定首次交互	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—
工具优先级排序	Prompt 中 PRIORITY CHECK 强制先澄清再行动，❌ DO NOT 规则禁止跳过	—	—	—	—	—	无显式优先级，所有受审批工具平等对待	—	—	—	—	—	—	—	—	Multi-Agent 版本通过 ask_for_clarification 开关控制 Question 工具是否注入	—	—	—	—	—	coreTools/excludeTools 配置显式控制可用工具集	—	—
passthrough 旁路	—	—	—	—	—	—	auto_approve=True 时 interrupt_on={} 空字典，完全跳过审批	—	—	—	—	—	—	沙箱内自动跳过审批（is_sandboxed 条件）	—	—	—	—	planner_passthrough 标记的 Agent 跳过 LLM 规划直接创建单任务 Plan	—	—	—	—	—
SubAgent 权限继承控制	—	—	—	—	—	—	子代理默认继承父代理 interrupt_on，可通过 spec 覆盖	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—
熔断器保护	—	—	—	—	—	—	_MAX_HITL_ITERATIONS=50 防止无限重试循环	—	—	—	—	—	—	HookStats 连续失败计数 + 冷却期自动恢复	—	—	—	—	—	—	—	Hook timeout 超时终止，超时不中断主流程仅记录警告	—	—
反作弊评分保护	—	—	—	—	—	—	—	—	—	wontfix 计入 strict score 债务，批量 >10 条强制预估分数影响	—	—	—	—	—	—	—	—	—	—	—	—	—	—
盲审隔离协议	—	—	—	—	—	—	—	—	—	blind packet + SHA256 哈希 + TTL 过期 + CLI 注入 provenance 四重保护	—	—	—	—	—	—	—	—	—	—	—	—	—	—
审计追溯链	—	—	—	—	—	—	—	—	—	attestation_log + assessment_import_audit + query log 三层审计记录	—	—	—	—	—	—	—	—	—	—	—	—	—	—
ID去幻觉	—	—	—	—	—	—	—	—	—	—	—	三级策略：精确匹配→大小写容错→difflib模糊匹配(cutoff=0.8)	—	—	—	—	—	—	—	—	—	—	—	—
修改比例安全阀	—	—	—	—	—	—	—	—	—	—	—	短文本<70%、长文本<20%的动态阈值，防止LLM生成完全不同的更新	—	—	—	—	—	—	—	—	—	—	—	—
递归依赖补全	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	拦截器检测缺失 kind 后递归执行前置节点（default 模式），按 priority 尝试候选实现	—	—	—	—	—	—
LLM 判定策略	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	LLM 自主判断查询清晰度，无硬编码规则	—	—	—	—
并行查询拆分	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	清晰查询拆分为多个子查询，Send 并行执行	—	—	—	—
防重复提问	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	无（依赖 LLM 自身能力，可能重复提问）	—	—	—	—
澄清回环熔断	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	无最大轮次限制（潜在风险）	—	—	—	—
降级处理	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	空澄清请求时使用默认消息	—	—	—	—
发现式恢复	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	轮询 closed gate + ready work 交集，无需 waiter 注册表	/restore 命令交互式选择 Checkpoint 回滚点	—	—

最佳实践

1.CLARIFY→PLAN→ACT 优先级：Agent 不确定时必须先澄清，严格禁止先做再问

2.结构化澄清类型：用枚举类型（missing_info 等）而非自由文本，便于前端渲染不同 UI

3.中间件拦截优于节点内硬编码：wrap_tool_call 钩子让澄清逻辑与业务逻辑解耦

4.interrupt() 优于 threading.Event：不阻塞线程，支持持久化，可扩展为多个中断点

5.超时自动处理：用户长时间不响应时有默认行为，避免任务永久挂起

6.Push not Pull：人类不轮询，Notifier 主动推送，减少认知负担

7.Reaction 先自动后人工：CI 失败等可自动修复事件先 send-to-agent，失败后才升级通知人类

8.状态转换时清零重试计数：避免跨状态的 reaction tracker 污染

9.per-project reaction 覆盖：全局默认 + 项目级覆盖，灵活控制自动化程度

10.Tier 分级人机边界：按功能模块的配置复杂度分 tier，不同 tier 有不同的自动化程度

11.三模式渐进信任：dry-run→safe→auto 让用户按信任级别选择 Agent 自主程度

12.Doctor 驱动优于步骤记忆：SKILL.md 明确禁止 Agent 记忆配置步骤，每次依赖 doctor 实时输出

13.输入抽象优于硬编码：用 UserInputBase 基类而非直接调用 input()，支持跨环境部署

14.人类即 Agent：UserAgent 继承 AgentBase，使人机交互可无缝融入编排图

15.中断不丢失上下文：为未完成的 tool_use 生成假 tool_result，避免 LLM 混乱

16.结构化验证前置：在输入层用 jsonschema 验证，而非依赖 LLM 推理，降低成本

17.finally 块保证持久化：即使中断也要保存 msg 到 memory，确保状态一致性

18.is_interrupted 标记传递：通过 ToolResponse.is_interrupted 而非重新抛出异常，解耦中断逻辑

19.类级/实例级切换分离：override_class_input_method 全局切换，override_instance_input_method 单例切换

20.WebSocket 自动重连：用 socketio.Client 的 reconnection 参数处理网络抖动

21.空壳节点作 interrupt 锚点：函数体为空，暂停逻辑与业务逻辑零耦合

22.结构化输出低温度调用：temperature=0.1 确保 is_clear 判断稳定性，减少随机翻转

23.frozenset 白名单注册命令：不可变集合防止运行时篡改命令列表

24.文件标记实现跨会话一次性触发：零依赖、重启安全、易于调试

25.getattr 动态分发优于 if-elif 链：新增命令只需添加 _process_xxx 方法

26.命令拦截在 LLM 推理之前：避免 token 浪费和理解歧义

27.interrupt_on 字典声明式配置优于逐工具硬编码：一处定义所有审批策略

28.HumanInTheLoopMiddleware 放在 middleware 栈末尾：确保其他中间件先完成处理

29.子代理默认继承父代理审批配置：防止权限泄漏，同时允许 spec 级覆盖

30.非交互模式用 allow-list + 迭代上限双重保护：防止无人值守时的安全风险和死循环

31.三方法协议（should_trigger→create_interaction→process_response）让插件可独立测试

32.asyncio.Future 桥接模式：后端 await Future + 前端 REST set_result，解耦通道与逻辑

33.全局默认 registry + 懒加载：避免循环导入，支持按需启用插件

34.空壳工具模式：工具函数体留空，用 return_direct=True 标记，真实逻辑委托给中间件处理

35.ToolMessage 配对完整性：中断时必须为 tool_call 生成配对的 ToolMessage，否则 LLM API 报错

36.中间件顺序即架构：ClarificationMiddleware 放最后确保其他中间件先完成处理

37.自然语言 attestation 优于 checkbox：要求包含特定短语的自由文本，强迫用户描述具体行为

38.风险分层确认：按操作影响程度分 4 级确认强度，低风险不打断流程

39.批量操作 deepcopy 预演：执行前在副本上模拟，展示分数影响后再让用户决策

40.CLI 层 provenance 注入：不信任外部审查者的自报来源，由可信 CLI 覆盖写入

41.session TTL + token 双重绑定：防止过期重放和跨会话冒用

42.LLM 多级审核优于单次判定：judgement→compare→compare_judge 三级链降低幻觉风险

43.修改比例动态阈值：短文本允许更大修改幅度，长文本严格限制，防止语义漂移

44.归档而非删除：旧记忆标记 archived 而非物理删除，covered_history 建立版本链支持回溯

45.ID 去幻觉三级策略：精确匹配→大小写容错→模糊匹配，逐级放宽容忍度

46.三层审查粒度：计划级(Planner)→节点级(ActionNode)→LLM级(HumanProvider)，不同场景选择不同粒度

47.HUMAN_REVIEW 混合模式：人类提供审查意见 + LLM 自动修改，兼顾可控性和效率

48.输入源全局可插拔：一处 set_human_input_func 替换，所有交互点自动生效，避免逐组件适配

49.安全地板不可绕过：dangerous pattern 检测在所有 mode/security 判断之前执行

50.白名单默认模式：OnMiss + Allowlist 为默认值，未知命令需审批比黑名单更安全

51.沙箱内跳过审批：已有隔离保护的环境不重复审批，避免效率损失

52.oneshot channel 优于共享状态轮询：零拷贝单次通知，无锁竞争

53.熔断器保护外部 Hook：连续失败自动禁用，冷却后恢复，防止坏 hook 拖垮系统

54.两阶段响应模式：先返回 accepted 确认注册，再异步等待最终决策，避免调用方无法区分注册失败和等待中

55.参数白名单过滤：转发审批参数时只允许已知安全字段，防止控制字段注入

56.grace period 处理竞态：审批 resolve 后保留短暂窗口供迟到的 awaitDecision 调用获取结果

57.无审批客户端时自动过期：检测到无 operator 连接时立即 expire，避免无人审批的请求永久挂起

58.prompt 内置防重复提问约束：在澄清 prompt 中显式要求 LLM 检查历史是否已问过

59.反馈累积优于覆盖：用 Annotated[list, operator.add] 保留所有历史反馈供 LLM 参考

60.类型化路由区分意图：用 isinstance 区分 bool(批准) 和 str(修改) 而非字符串匹配

61.工具即交互：将人机交互实现为标准工具而非特殊节点，复用已有工具管道零成本集成

62.prompt 约束优于硬编码：用 system prompt 中 'only for extreme cases' 引导 LLM 控制调用频率，而非代码层面限制

63.mode 作为工具参数而非图拓扑：将执行模式编码为工具参数让 LLM 自主决策，避免修改图结构

64.双依赖集设计：auto 和 default 模式使用不同的依赖列表，skip 时只需最小依赖集

65.拦截器层自动补全优于用户手动执行：缺失依赖时静默以 default 模式递归执行，不打断用户流程

66.asyncio.Event 优于 threading.Event：协程级挂起不占线程，事件循环可继续服务其他请求

67.信号对象封装：将 prompt/response/event 封装为 UserInputRequest，Planner 只需 await 不关心通信细节

68.注册表解耦：UserInputRegistry 按 conversation_id 索引，Planner 和 Orchestrator 无直接引用

69.事件循环时钟计时：ExecutionContext 用 asyncio.get_event_loop().time() 而非 datetime.now()，避免系统时钟调整影响 TTL

70.结构化澄清输出：使用 Pydantic + with_structured_output 确保输出格式

71.空壳节点模式：澄清节点不执行逻辑，只作为暂停点

72.低温度采样：澄清判定使用 temperature=0.1 减少随机性

73.并行查询拆分：清晰查询拆分为多个子查询并行执行，提高效率

74.Gate 即 Issue：复用 issue 生命周期管理 gate 状态，避免引入新状态机

75.人机分流分类器：machine-checkable gate 自动验证，human/mail gate 直接放行，减少不必要人工干预

76.发现式恢复优于回调注册：轮询 closed gate 交集无需维护 waiter 表，简化系统复杂度

77.四模式连续光谱优于二元开关：yolo/accept-edits/plan/default 覆盖从全自动到全受控的所有场景

78.Hook 外部化优于内置逻辑：用户通过外部脚本自定义安全策略，无需修改 CLI 源码

79.autoAccept 安全地板：即使开启自动批准，写操作仍强制拦截，防止误操作

80.Checkpoint 三维快照：同时保存文件状态+会话历史+工具调用，支持完整状态回滚

81.interrupt 数据应包含完整结构化内容，前端可直接渲染编辑 UI 而无需额外查询

82.编辑操作后清空下游产出（sections=[]），确保后续节点基于新输入重新执行

83.resume 前检查并修复悬挂工具调用，防止 LangGraph 恢复时因消息历史不完整报错