IronClaw Decision Capture 技能实战：在 Agent 会话中自动检测、持久化与追踪决策

• 人工智能
• AI 应用
• 交互助手
• AI Agent

IronClaw 的decision-capture技能是一套面向 Agent 对话的决策记录机制：当用户在会话中出现明确的决策语言时，技能自动把"当时为什么选这条路"沉淀为可检索的持久化知识，并联动承诺跟踪与结果回访。读完本文，你将掌握该技能完整的激活规则、决策文件的字段规范、memory_write强制写入顺序，以及它与commitment-triage、commitment-digest两个配套技能如何协作，形成"决策 → 承诺 → 结果追踪"的闭环。

技能本体定义见 skills/decision-capture/SKILL.md，其底层能力依赖技能选择器（selector.rs）与技能类型系统（types.rs）。

一、技能定位：决策是"为什么"，承诺是"做什么"

decision-capture（版本 0.2.0）在 SKILL.md 的 frontmatter 中这样描述自己：

Detect decisions in conversation and record them with rationale, alternatives, and outcome tracking.

它把"决策"视为持久化的知识资产：不仅记录结果，还记录备选方案、取舍理由（rationale）与结果追踪（outcome tracking）。这是它与任务跟踪类技能的本质区别——决策回答的是why a path was chosen，而承诺回答的是what needs to be done next。两者互补：一个决策往往派生出一个承诺（如"我们决定 Q2 前完成迁移"），这时决策文件与承诺文件会同时产生。

该技能位于仓库顶层 skills/decision-capture/，遵循 IronClaw 技能目录规范：每个技能一个子目录、入口文件名为SKILL.md。官方文档 docs/capabilities/skills.mdx 指出，技能的本质是"包含领域指令的 Markdown 文件"，激活后其正文被注入 LLM 上下文，从而在不重训模型的前提下赋予 Agent 专项行为。

二、激活机制：frontmatter 如何决定"何时触发"

技能的触发完全由 YAML frontmatter 的activation段声明，Selection 阶段是确定性的、无 LLM 参与的两阶段预筛（见 selector.rs 顶部注释：先决性评分，再把命中的技能注入上下文）。decision-capture的激活声明如下：

activation: keywords: - decided - decision - chose - going with - settled on - picked - landed on - went with - finalized - agreed on - opted for - concluded - confirmed - final answer - made the call - ruling - verdict - record decision exclude_keywords: - undecided - considering - thinking about - tentative - maybe patterns: - "(?i)(we|I|team) (decided|chose|went with|picked|settled on|landed on|opted for)" - "(?i)let's go with" - "(?i)the (decision|call|verdict) is" - "(?i)record (this|that) decision" - "(?i)(instead of|replaced|switched to|migrated to)" tags: - commitments - decision-making max_context_tokens: 1200

结合 selector.rs 的score_skill实现，这些字段的评分语义如下：

几点值得注意的工程细节：

• 排除词是一票否决。score_skill中，若消息包含任一exclude_keyword，无论其他关键词/正则命中多少，得分直接归零（selector.rs 的score_skill开头）。这保证"maybe we should…"这类尚未定论的话不会触发记录流程。
• 正则会预先编译并缓存。LoadedSkill::compile_patterns在加载期编译正则，且对编译后的正则状态施加 64 KiB 大小上限以防 ReDoS；非法正则被记录告警后跳过（types.rs 的compile_patterns）。所有 pattern 都带(?i)忽略大小写。
• 限额是硬约束。ActivationCriteria::enforce_limits会过滤长度不足 3 字符的宽泛词，并把关键词截断到 20 个、正则截断到 5 条、标签截断到 10 个（types.rs）。decision-capture声明了 18 个关键词、5 条正则，恰好都在上限内。
• 上下文预算：max_context_tokens: 1200表示该技能注入的提示词最多消耗 1200 token；省略时默认 2000（types.rs 的default_max_context_tokens）。选择阶段按分数从高到低依次装载技能，直到总预算耗尽（selector.rs 的prefilter_skills_with_options）。

信任级别方面，仓库顶层 skills/ 属于工作区skills/目录，是 Trusted（受信）来源：技能正文可被完整注入，且 Agent 可通过skill_activate自动选择（docs/capabilities/skills.mdx 的 Trust levels 表）。用户也可随时用ironclaw skills list确认技能已被索引。

三、检测（Detection）：识别"已成定局"的语言

技能正文规定，Agent 在会话中应寻找显式的决策语言：

• "We decided to..." / "I'm going with..." / "Let's do X"
• "The call is..." / "We settled on..."
• "I chose X over Y because..."

明确不要捕获（Do NOT capture）三类情况：

• 头脑风暴或假设性讨论："maybe we should..."、"what if we..."
• 未形成承诺的偏好表达："I think X is better"
• 提问："should we go with X?"

当判断不确定时，技能要求 Agent 主动澄清："Was that a decision, or still thinking it through?"

这与exclude_keywords（undecided / considering / thinking about / tentative / maybe）形成双重防线：前者在激活层把未定稿的语句挡在门外，后者在行为层要求 Agent 对被误判的情况谨慎确认。

从仓库结构可以推断，该技能的检测逻辑依赖的是"提示工程 + 确定性预筛"的组合，而非独立的 NLP 服务：技能正文本身指导 LLM 如何判定，而预筛器负责把最相关的技能（包括本技能）优先载入上下文。配套的commitment-triage技能（skills/commitment-triage/SKILL.md）提供了信号模板中obligation_type: decide这一分类，说明"待决策"在承诺体系里也是一类独立义务。

四、记录（Recording）：持久化优先的强制执行顺序

技能正文特别强调：只有真正把决策写进工作区才算成功，仅做口头总结或确认都不算。因此执行顺序是强制的：

1. 调用memory_write写入projects/commitments/decisions/<date>-<slug>.md
2. 如适用，调用memory_write写入后续承诺到projects/commitments/open/
3. 如适用，调用memory_write写入context/intel/<slug>.md
4. 只有以上写入全部成功后，才向用户确认已记录的内容

技能明确禁止在对应memory_write调用成功之前声称决策已被 "captured"、"recorded" 或 "saved"——这是对"口头承诺 ≠ 持久化"的硬性约束。

memory_write是 IronClaw 内存抽象的核心操作之一。底层由ironclaw_memory域定义统一的MemoryService契约（见 crates/domains/ironclaw_memory/README.md），工具命名遵循ironclaw.memory.*约定；具体持久化由memory-native等提供方实现。决策文件写入的目标路径遵循/memory路径语法，落在工作区的projects/commitments/体系下。

决策文件完整模板

技能给出了可直接套用的决策文档结构（frontmatter + 正文）：

--- type: decision decided_at: <today YYYY-MM-DD> context: <topic-slug> participants: [<who was involved>] confidence: <high if explicit, medium if inferred> reversible: <true|false> outcome: null outcome_positive: null tags: [<relevant tags>] --- # <What was decided> ## Context <Why this decision was needed — 1-2 sentences.> ## Options considered 1. **<Option A>** — <brief pros/cons> 2. **<Option B>** — <brief pros/cons> ## Rationale <Why this option was chosen.> ## Outcome <To be filled in later when outcome is known.>

各字段的语义要点：

文件名规范与commitment-triage的 slug 约定一致：小写、连字符、无特殊字符、最长 50 字符（skills/commitment-triage/SKILL.md 的 Filename conventions 一节）。例如 "We decided to migrate to Postgres" →projects/commitments/decisions/2026-09-25-migrate-to-postgres.md。

显式请求的默认行为

当用户显式说 "record this decision"、"log this decision"、"note the decision" 时，除非内容确实含糊不清，技能要求默认立即执行全部必需写入，而不是先反问确认——把"记录"理解为命令而非征求许可。

五、跟进（Follow-through）：从决策派生承诺与情报

一次决策记录往往不是终点，技能要求联动两处写入：

1. 派生承诺：如果决策产生了义务（例如"我们决定 Q2 前完成迁移"），必须同时在projects/commitments/open/创建一条承诺，遵循承诺 schema（skills/commitment-triage/SKILL.md 的 Commitment template）。承诺模板的核心字段包括urgency（critical/high/medium/low，按到期时间推算）、due、resolution_path（agent_can_handle / needs_reply / needs_decision / note_only）等。
2. 情报写入：向context/intel/<slug>.md写一条简短的智能记忆文档，格式为 "Decided X on . Rationale: ."，使决策作为可检索的持久知识沉淀——即使承诺早已解决，这条"为什么"的记录仍然服务于未来的同类决策。

六、结果追踪（Outcome tracking）：7 天回访闭环

决策的价值在于事后验证，技能为此设计了回访机制：

The triage mission checks for decisions older than 7 days without an outcome.

• 触发时机：triage 任务（mission）检查outcome仍为null且超过 7 天的决策文件。
• 回访话术：向用户提问 "You decided days ago. How did it turn out?"
• 回填动作：用户给出结果后，更新决策文件的outcome与outcome_positive字段。

从 skills/commitment-triage/SKILL.md 的 Mode D（Signal promotion）可以看出，triage 任务同时负责把signals/pending/下的待决信号路由到承诺、停放想法、情报或废弃四类目的地，是承诺体系的后台调度者；decision-capture的结果回访即由这类 mission 驱动。配套的 skills/commitment-digest/SKILL.md 则负责把开放承诺、待处理信号、近期已解决项汇总成日报，供用户一站式查看义务全景。

七、确认（Confirmation）：写入成功后的简报

技能规定，只有在写入全部成功后，才向用户做简短确认，包含三要素：

• 决策被写到了哪里（文件路径）
• 是否创建了后续承诺
• 一行理由摘要（rationale）

例如：

Recorded: "Migrate to Postgres" →projects/commitments/decisions/2026-09-25-migrate-to-postgres.md. Created a follow-on commitment inprojects/commitments/open/(due 2026-12-31). Rationale: better query performance and managed backups.

八、技能家族协作全景

decision-capture并非孤立存在，它与承诺体系的其他技能共同构成一个自洽的工作流：

三者共享projects/commitments/工作区目录结构与 slug 命名约定；memory_tree/memory_read/memory_write是它们共同的持久化工具面（技能正文明确要求承诺类操作走内存工具，不使用 CodeAct 或 shell 命令，以保证路径语法与审计一致）。

九、注意事项与最佳实践

• 不要把"讨论"当"决策"：brainstorming、偏好表达、提问三类场景一律不记录；拿不准时先澄清再行动。
• 先写后说：任何"已记录/已保存"的表述都必须发生在memory_write成功之后，避免假确认。
• 文件命名用 slug：小写、连字符、≤50 字符，保证跨工具（memory_tree 遍历、memory_search 检索）的一致性。
• 决策与承诺要分离：决策文件回答"为什么选它"，承诺文件回答"接下来做什么"；一次迁移决策应同时产生两者，但内容不混写。
• 结果必回填：超过 7 天无outcome的决策会被 triage 回访，主动维护outcome/outcome_positive才能让决策知识持续增值。

整体而言，decision-capture体现了 IronClaw 对"知识沉淀"的一贯设计：确定性预筛负责精准激活，提示词规范负责记录质量，工作区文件系统负责持久化，mission 任务负责结果闭环——四层配合，让会话中每一句"我们决定……"都不再随风而逝，而是成为可检索、可追踪、可复用的组织记忆。

• 人工智能
• AI 应用
• 交互助手
• AI Agent