docs(action): add document for action

2026-05-12 08:43:02 +08:00 · 2026-04-29 22:27:27 +08:00
parent 690f258dc9
commit 4a00e5f320
11 changed files with 1287 additions and 1 deletions
--- a/doc/action/action-extraction-and-evaluation.md
+++ b/doc/action/action-extraction-and-evaluation.md
@@ -0,0 +1,146 @@
+# 行动提取与评估
+
+本文介绍 Partner 行动系统的入口决策层：如何从输入中识别行动意图，并在进入执行或调度前完成可行性评估。
+
+行动提取与评估位于 `ActionPlanner` 的前半段。它的输出不是执行结果，而是一个明确的运行时决策：本轮输入是否应进入行动系统；如果进入，应当成为即时行动、计划行动，还是等待用户确认。
+
+## 入口决策层
+
+行动系统面对的输入通常并不直接等同于行动。用户可能是在提问、讨论、确认、补充条件，也可能是在要求系统实际完成某件事。入口决策层负责把这些情况分开。
+
+它需要在三个对象之间建立关系：
+
+- **输入意图**：来自用户或认知模块的当前表达。
+- **上下文状态**：当前会话、感知、记忆、认知和已有行动状态。
+- **行动能力**：系统当前真实可用的 `MetaAction` 集合。
+
+只有当一个意图能在当前上下文中被解释为可推进目标，并且存在可承接的行动能力时，它才会进入行动建模与执行链路。
+
+## 分层职责
+
+行动入口被拆成三个层次：
+
+```text
+ActionExtractor
+  负责发现候选行动倾向
+
+ActionEvaluator
+  负责判断候选倾向是否可推进
+
+ActionPlanner
+  负责把评估结果装配为运行时行动
+```
+
+三者的边界如下：
+
+| 层次                | 输入                       | 输出                                                           | 不负责            |
+|-------------------|--------------------------|--------------------------------------------------------------|----------------|
+| `ActionExtractor` | 当前输入 + 上下文               | `tendencies`                                                 | 生成行动链、判断能力是否足够 |
+| `ActionEvaluator` | 单条 tendency + 上下文 + 可用能力 | `EvaluatorResult`                                            | 执行行动、持久化行动对象   |
+| `ActionPlanner`   | `EvaluatorResult`        | `ExecutableAction` / pending confirmation / refused tendency | 重新解释用户意图       |
+
+这种分层使“发现可能要做的事”和“决定能不能做”相互独立。提取阶段保持轻量，评估阶段负责执行前的结构化判断，Planner 负责与行动运行时交接。
+
+## 主流程
+
+```mermaid
+flowchart TD
+    Input["当前输入"] --> Extractor["ActionExtractor"]
+    ContextA["ContextWorkspace\n对话 / 感知 / 行动状态"] -.-> Extractor
+    Extractor --> T{"tendencies"}
+    T -- " empty " --> NoAction["不进入行动系统"]
+    T -- " non-empty " --> IntentBlock["发布 pending_action_intentions"]
+    IntentBlock --> Evaluator["ActionEvaluator"]
+    ContextB["ContextWorkspace\n行动 / 对话 / 感知 / 记忆 / 认知"] -.-> Evaluator
+    Capabilities["available_meta_actions"] -.-> Evaluator
+    Evaluator --> Decision{"EvaluatorResult"}
+    Decision -- " rejected " --> Refused["拒绝进入行动链"]
+    Decision -- " need confirmation " --> Pending["actions_need_confirmation"]
+    Decision -- " immediate " --> Immediate["ImmediateExecutableAction"]
+    Decision -- " planned " --> Scheduled["SchedulableExecutableAction"]
+    Pending --> ConfirmTurn["请求用户确认"]
+    Immediate --> Executor["ActionExecutor"]
+    Scheduled --> Scheduler["ActionScheduler"]
+```
+
+## ActionExtractor：候选行动发现
+
+`ActionExtractor` 的职责是从当前输入中提取行动倾向。倾向不是行动计划，而是一个待评估目标。
+
+行动倾向应保持“目标语义”，而不是“执行语义”。例如用户说“先检查配置，再修复问题，最后告诉我结果”，提取结果应表达为一个整体目标，而不是拆成多个工具步骤。
+
+提取阶段只决定是否存在候选目标，不承诺该目标一定能执行。它不会绑定 `MetaAction`，也不会判断是否需要确认。
+
+### 提取边界
+
+行动倾向通常对应以下语义：
+
+- 用户要求系统代为完成某件事。
+- 当前目标需要访问能力、操作对象、修改状态或安排未来动作。
+- 该目标如果不进入行动链，就无法被实际推进。
+
+普通交流不应进入行动系统。解释、分析、翻译、总结、评价、闲聊，以及可直接基于当前上下文回答的问题，都应留给沟通模块处理。
+
+这条边界能避免行动系统过度激活。
+
+## ActionEvaluator：执行前判断
+
+`ActionEvaluator` 对单条 tendency 做执行前判断。它不重新提取意图，而是在当前上下文和能力集合下判断该倾向是否可推进。
+
+评估阶段主要形成四类结论：
+
+| 结论   | 含义                                   |
+|------|--------------------------------------|
+| 拒绝   | 倾向不应进入行动链，原因可能是无需行动、能力不足、目标不清或已有行动覆盖 |
+| 待确认  | 行动可以建模，但执行前需要用户确认                    |
+| 即时行动 | 行动可以立即装配并交给执行器                       |
+| 计划行动 | 行动应按未来时间、周期或条件进入调度器                  |
+
+评估结果通过 `EvaluatorResult` 表达。它是 planner 的输入契约，而不是给用户展示的回复文案。
+
+## 确认与 pending action
+
+某些行动虽然可以建模，但不能直接执行。典型原因包括副作用、权限风险、外部可见影响、长期运行影响或用户意图仍需最终确认。
+
+这类行动会进入 pending confirmation：
+
+```text
+EvaluatorResult(ok=true, needConfirm=true)
+  ↓
+ActionPlanner
+  ↓
+ContextWorkspace.register(actions_need_confirmation)
+  ↓
+后续输入承接确认 / 取消 / 修改
+```
+
+> pending confirmation 将借助 CommunicationBlockContent 作为输入时的补充块，用来及时提醒交流模块生产合适响应。
+
+## Planner 装配
+
+`ActionPlanner` 异步接收评估结果后，把结构化决策转换为运行时对象。
+
+主要装配动作包括：
+
+- 将 `primaryActionChain` 转换为 `Map<Int, List<MetaAction>>`。
+- 加载每个 action key 对应的 `MetaAction`。
+- 根据 `MetaActionInfo` 修正顺序并补齐严格依赖。
+- 根据评估类型构造 `ImmediateExecutableAction` 或 `SchedulableExecutableAction`。
+- 对待确认行动注册 `actions_need_confirmation`。
+- 对已承接的 pending block 执行过期。
+- 将即时行动交给 `ActionExecutor`，将计划行动交给 `ActionScheduler`。
+
+Planner 是入口决策层与运行时执行层之间的边界。评估器给出“应该怎样推进”，Planner 负责把这个结论变成可运行对象。
+
+## 输出流向
+
+评估和装配后的输出分为四种：
+
+| 流向      | 说明                                      |
+|---------|-----------------------------------------|
+| 不进入行动系统 | 没有提取到 tendency，或评估认为无需行动                |
+| 等待确认    | 行动可建模，但先写入 pending confirmation         |
+| 即时执行    | 构造 `ImmediateExecutableAction` 并交给执行器   |
+| 计划调度    | 构造 `SchedulableExecutableAction` 并交给调度器 |
+
+这四种流向共同构成行动系统的入口安全阀。任何行动在进入执行器前，都必须先经过提取、评估和 planner 装配。