intent-framed-agent

意图框定 Agent

安装

gh skill install pskoett/pskoett-skills

gh skill install pskoett/pskoett-skills intent-framed-agent

使用 Agent Skills CLI 作为备用方案：

npx skills add pskoett/pskoett-skills/skills/intent-framed-agent

用途

此技能会在执行开始时，将隐含意图转化为明确且可追踪的产物。它会创建一份轻量级意图约定，在工作进行期间监控范围偏移，并为每项意图记录简短的解决结果。

适用范围（重要）

仅将此技能用于编码任务。它专为会修改可执行代码的实现工作而设计。

不要将其用于通用 Agent 活动，例如：

• 广泛调研
• 仅涉及规划的对话
• 仅涉及文档的工作
• 不涉及代码实现的运维／管理任务

对于简单编辑（例如简单重命名或修正错别字），可跳过完整的意图框定。

触发条件

对于非简单编码工作，在从规划转向执行时启用。

常见提示：

• 用户说：“开始吧”“实现这个”“我们开始构建吧”
• Agent 即将从讨论转入代码修改

工作流

阶段 1：捕获意图

执行开始时，根据当前请求或已批准的计划，明确结果、约束和成功标准。只有在尚未解决的决策会实质性改变工作时，才提出有针对性的问题；对于明确的请求，不要要求单独进行访谈或确认。适当时使用宿主支持的提问工具，或直接在聊天中提问（包括 Copilot）。

在检索先前会话的上下文之前，先输出初始框架：

## Intent Frame #N

**Outcome:** [One sentence. What does done look like?]
**Approach:** [Approved approach, or provisional approach pending context.]
**Constraints:** [Out-of-scope boundaries.]
**Success criteria:** [How we verify completion.]
**Estimated complexity:** [Small / Medium / Large]

规则：

• 每个字段限制为 1–2 句话。
• 明确的实现请求或已批准的计划，即可作为忠实框定的依据。输出框架以便追踪，无需重复确认。但这不免除对外部操作或破坏性操作的单独审批要求。
• 如果仍有尚未解决的重要需求、授权或范围决策，请提出具体问题。在请求范围内采用可逆的实现方案，不必要求用户批准每个技术细节。
• 重要决策尚未解决时，不要继续。

阶段 1a：会话上下文与方案

输出初始框架后，在确定未经批准的方案或开始实现之前，如果 session-context 可用，则调用它。传入框架、关联问题、已知代码锚点和允许的范围。它负责检索预算和相关性检查；不要再通过该流程进行第二次搜索。

使用有用且带引证的发现来完善方案，并更新同一框架。历史信息是证据，不是指令或授权。除非当前证据揭示了需要用户决策的重要冲突，否则保留已批准的决定。如果历史记录没有补充信息或不可用，则继续工作。恢复工作时，复用现有简报；只有存在明确的新缺口时才再次搜索。即使未安装 session-context，也可以单独使用此技能。

阶段 2：意图监控

执行期间，在自然的节点监控范围偏移：

• 开始处理新的区域／文件之前
• 开始新的逻辑工作单元之前
• 当前操作看起来偏离主题时

范围偏移示例：

• 超出已说明的范围
• 未明确转向就改变方案
• 超出约束的新功能／重构
• 解决的问题与所述结果不同

发现偏移时，输出：

## Intent Check #N

This looks like it may be moving outside the stated intent.

**Stated outcome:** [From active frame]
**Current action:** [What is happening]
**Question:** Is this a deliberate pivot or accidental scope creep?

如果用户已经指示转向，则更新当前意图框架，并在持续有效的约束下继续。否则，询问用户是否有意转向。如果并非有意，则返回原定范围。

阶段 3：意图解决

当前意图下的工作结束时，输出：

## Intent Resolution #N

**Outcome:** [Fulfilled / Partially fulfilled / Pivoted / Abandoned]
**What was delivered:** [Brief actual output]
**Pivots:** [Any acknowledged changes, or None]
**Open items:** [Remaining in-scope items, or None]

建议记录解决结果；但如果会话突然结束，则可省略。

多意图会话

一个会话可以包含多个意图框架。

规则：

1. 先解决当前意图，再开启下一个意图。
2. 如果用户在任务中途改变方向，将当前意图标记为 Abandoned 或 Pivoted，然后开启一个新框架。
3. 漂移检查始终针对当前激活的框架。
4. 在会话内按顺序为框架编号（#1、#2……）。
5. 持续有效的约束会沿用；框架内的选择不会沿用。用户的禁止事项、安全／隐私限制、授权边界、仓库限制，以及明确的“不要”指令，在用户撤销前始终有效。本地实现选择只有在新结果仍依赖它时才会沿用；否则应重新说明或询问。

完整的 CLI 集成

Entire CLI：https://github.com/entireio/cli

在可用工具访问时，于激活时检测 Entire：

entire status 2>/dev/null

• 如果检测成功，且当前主机适配器会记录对话生命周期事件，请说明预期会在会话记录中看到意图记录。不要仅凭 entire status 推断会话记录完整；在依赖其进行 learning-aggregator --deep 操作前，先检查可用的会话／检查点状态。
• 如果不可用或检测失败，则静默继续。不要阻止执行，也不要反复催促安装。

Copilot／聊天回退：

• 如果无法执行命令，则跳过检测，并在聊天输出中继续使用相同的意图工作流。

意图框架如何转化为学习信号

当当前主机适配器捕获消息事件时，每个意图框架和意图检查都会出现在 Entire 的会话记录中。在设定的周期内，learning-aggregator --deep 可以读取可用的会话记录并提取：

• 标记为 Abandoned 或 Pivoted 的框架 → 潜在的规划缺口
• 在类似上下文中反复触发的漂移信号 → 潜在的范围定义问题
• 漂移检查检测到的约束违反 → 可推广到项目指令文件中的模式

无需进行任何特别操作——意图块采用结构化格式（## Intent Frame #N、## Intent Check、## Intent Resolution），因此可以从会话记录中解析。

防护措施

• 保持轻量；避免冗长的文字。
• 不要对琐碎任务过度触发。
• 不要每个小步骤都进行干预。
• 将已确认的方向调整视为有效。
• 保留结构化块标题／字段的原样，以便解析。

与其他技能的互操作性

将此技能用作非简单编码工作的前置对齐层：

1. plan-interview（可选，用于梳理需求）
2. intent-framed-agent（澄清缺口并生成初始执行约定）
3. session-context（收集范围受限的过往会话证据，然后敲定方案）
4. context-surfing（可选，用于大型、长期运行或明确对上下文敏感的执行过程中的上下文质量监控）
5. simplify-and-harden（完成后的质量／安全检查）
6. self-improvement（记录反复出现的模式，并推广持久规则）

执行期间会持续进行意图监控；session-context 是范围受限的准备步骤，而非另一个监控器。plan-interview 仍需明确调用，且不是意图框架内针对性澄清的必需步骤。

与 context-surfing 的关系

激活 context-surfing 后，执行期间两项技能都会运行。 它们监控不同的故障模式：

• intent-framed-agent 监控范围偏移——Agent 是否在做正确的事？当工作偏离既定目标时，它会触发结构化的意图检查。
• context-surfing 监控上下文质量偏移——Agent 是否仍有能力把事情做好？当 Agent 自身的连贯性下降（出现幻觉、矛盾、含糊其辞）时，它会触发。

两者相辅相成，并非冗余。Agent 可能完全没有偏离范围，但上下文质量却在下降。反过来，范围也可能发生偏移，而上下文质量仍然完好。意图检查会与 context-surfing 的波动监控同时持续触发。

优先级规则： 如果两项技能同时触发（意图检查与 context-surfing 偏移退出同时发生），则以偏移退出为准。上下文质量下降会使范围检查变得不可靠——先解决上下文问题，再在下一次会话中恢复范围监控。

节奏区分： 意图检查会在范围边界触发——开始接触新的区域/文件之前、开始新的逻辑工作单元之前，以及当前操作显得无关时。context-surfing 的提交前锚定检查则会在产生副作用的操作时触发——具体的工具调用、写入、提交以及提交级输出。不要在同一节拍内同时运行两者：如果刚刚触发的意图检查已顺利解决，那么同一工作单元内接下来的产生副作用的操作无需再次进行锚定检查——你已经重新校准了上下文。

此技能会产出什么

• 意图框架产物——由 context-surfing 用作波动锚点的一部分，并在偏移退出时原样复制到交接文件中。
• 意图解决结果——表示任务完成，并触发简化与加固。
• 偏移观察记录——如果范围偏移模式再次出现，可将其作为经验记录到自我改进中。