会意 · 让 Agent 听懂你真正想说的

概述

会意（huiyi）

你可以直接这样说

• 你先确认一下我真正想要什么，再开始做。
• 别按字面理解，我要的是最后能用的结果。
• 信息不够就先问，别自己脑补。

作者：唐可创研｜相光域 Chromatic

版权与许可：Source-Available，不是开源软件。

Copyright © 2026 唐可创研 · 相光域 / CHROMATIC。保留所有权利。允许查看源码、下载未修改副本、在私有环境运行并提交审核意见；未经书面授权，不得复制传播、再发布、转授权、销售、商业使用、公开部署，或制作并分发衍生版本。完整条款见本包 [LICENSE.md](LICENSE.md)。

你随口说的话，字面意思和真实目标常常有差距。会意在你每次发消息时先做判断：闲聊就自然聊，不动；是需求，就先确认它理解到的目标，把你没说到位的范围、限制条件和完成程度补全出来、标注为假设，然后带着这份理解动手。回复开头一小段“我理解的是……”，偏了你随时纠正。它的目标是减少按字面跑偏，也减少把每句话套进八股模板。

实现方式：给项目装一条 Hookify 规则，让 Agent 在每次收到用户输入时先做分类判断，仅对需求类输入做意图补全。补全的目的不是把用户的话改写成固定格式，而是让 Agent 对需求的理解更完整、更接近用户本意。

30秒上手

# 校验内置规则模板是否完好
python scripts/install_rule.py check

# 把规则装进某个项目（写入 <项目>/.codebuddy/ 下）
python scripts/install_rule.py install --project /absolute/path/to/project

# 确认安装状态
python scripts/install_rule.py status --project /absolute/path/to/project

装完后不需要任何额外操作：该项目里下一条用户消息开始，Hookify 会在每次提交输入时把补全指引注入给 Agent。

效果对照（装与没装）

同一句口语需求：“帮我把昨天那个报表整理一下发我”。

没装会意：Agent 按字面意思执行——“那个报表”是哪个、“整理”是美化还是汇总、“发我”发到哪里，全部靠猜。它挑了修改时间最近的文件，自作主张美化格式加了图表输出成 PDF；你说不对，它再问，再问再改，三轮返工。

装了会意：

1. 先判断类型：这是需求，进入意图补全（如果你只说“早”，它直接回你“早”，什么都不做）。
2. 理解摆在明面上：回复开头一小段——“我理解的是：整理 reports 目录里 0823 的销售日报；我的假设是：文件是 sales_0823.xlsx、‘整理’是按原格式汇总、‘发我’是生成到桌面”。你一眼能纠偏。
3. 只在会返工时问一句：覆盖原文件不可逆，它先问“覆盖还是另存？”；没有这种风险时它一句都不问，交代完理解直接干。
4. 你说两句话，Agent 先交代理解再动手，通常能减少返工轮次。

理解过程摊在明面上给你看，但不用你点头才动；只有可能白干活的时候才先问你。

核心方法：先分类，再补全

规则要求 Agent 对每条输入做两步处理。

第一步，分类。两类输入走完全不同的路径：

• 口头对话类：问候、闲聊、情绪表达、一句话能答完的简单问答、对上一轮结果的简短反应（"好"、"继续"、"换一个"）。这类输入直接自然回应，不做任何补全，避免把闲聊强行结构化。
• 需求类：要求产出某物（代码、文档、方案、表格）、要求完成某事（修改、创建、查找、分析）、或者口语化地描述一个问题并期待 Agent 行动。这类输入进入补全流程。

第二步，对需求类输入做意图补全，具体三件事：

1. 确认核心意图：用一两句话说明理解到的真实目标。口语表达的字面意思和真实目标常常有差距，先对齐再动手。
2. 补全没说到位的部分：结合对话上下文、工作区环境和常识，推断用户没明说但会影响结果的信息——涉及的对象和范围、期望的产出形态、隐含的限制条件、做到什么程度算完成。推断内容标注为 Agent 的假设，不冒充用户原话。
3. 带着假设行动：假设错误会导致明显返工时，先用一句简短提问确认；其余情况在回复开头交代理解和假设，然后直接执行。用户看到理解有偏差可以随时纠正。

规则同时明确禁止：对口头对话强行结构化、把每句话套进"目标/约束/验收"的八股格式、以补全为名替用户做需求之外的决定、以补全为由拖延简单任务。

使用方法

触发方式：规则装入项目后自动生效，不需要触发词。每次用户提交输入，Hookify 都会把指引随输入一起交给 Agent。

管理命令（输出均为 JSON，退出码 0 表示成功，2 表示阻断性错误）：

# 校验模板完整性，打印规则摘要
python scripts/install_rule.py check

# 体检某个项目里已安装的规则（手改规则后用它确认没改坏）
python scripts/install_rule.py check --project /absolute/path/to/project

# 安装；目标已有不同内容的同名规则时拒绝覆盖
python scripts/install_rule.py install --project /absolute/path/to/project

# 确认要替换已有规则时显式加 --force
python scripts/install_rule.py install --project /absolute/path/to/project --force

# 查看项目当前是否安装、内容与模板是否一致
python scripts/install_rule.py status --project /absolute/path/to/project

# 从项目移除规则
python scripts/install_rule.py uninstall --project /absolute/path/to/project

想临时停用而不是移除：把项目里 .codebuddy/hookify.huiyi.local.md 的 enabled: true 改成 enabled: false，下一条输入即不再注入。

执行流程

1. check 校验内置模板的 frontmatter 字段（name、enabled、event、pattern）和正文长度，损坏即报错。
2. install 复用同一套校验，把模板复制到目标项目的 .codebuddy/ 目录，写完后回读再校验一次。
3. Hookify 动态读取规则目录，无需重启会话；下一次用户提交输入时规则参与匹配。
4. 规则事件为 prompt，匹配模式覆盖包括多行在内的非空输入。
5. Agent 收到注入的指引后按"先分类，再补全"处理该条输入。

数据来源与免责声明

本 Skill 的需求依据来源：2026-08-24 与单用户的两轮对话观察（第一轮提出"每次对话把用户的话转成适合 Agent 理解的 Prompt"，第二轮纠正为"口头对话不动、只对需求做意图补全"）。这是单一来源的需求假设，不代表更多用户的验证。

免责声明：安装与验收通过只证明声明的本地命令在声明的文件上运行成功，不替代真实用户检验，不证明补全效果、安全性或市场需求。

边界声明

• 这不是确定性的文本改写器。注入的是行为指引，最终由 Agent 判断和执行，同一条输入在不同轮次得到的补全深度可能不同。
• 只对安装了规则、且 Hookify 正常加载的项目生效；未安装的项目不受影响。
• 规则不修改用户的原始输入本身，只是随输入追加理解指引。
• 不替代具体任务的领域 Skill；它解决"听懂需求"的问题，不解决"做好任务"的问题。
• 分类依赖 Agent 的判断，存在把简短需求误判为闲聊、或把闲聊误判为需求的可能。

异常与降级

• 内置模板缺失或损坏：check 与 install 输出错误并以退出码 2 结束，不写入任何文件。
• 项目里已安装的规则被改坏（比如 frontmatter 字段误编辑）：check --project 明确指出哪个字段不合法，退出码 2；规则本身静默失效，不会报错提醒，建议每次手改后跑一次体检。
• 目标项目已存在内容不同的同名规则：install 拒绝覆盖并以退出码 2 结束；确认替换需显式传 --force。
• 对未安装规则的项目执行 uninstall：明确报错，退出码 2。
• Hookify 未加载或规则被禁用：补全指引不注入，对话行为退回安装前的状态，无其他副作用。
• 某次补全理解偏差：用户在下一轮直接纠正即可，规则不会锁定或累积错误理解。

不确定性与限制

• 补全质量取决于 Agent 当时的上下文掌握程度；上下文不足时推断的假设可能偏离用户本意，建议用户留意回复开头的理解摘要。
• 规则以 prompt 注入方式工作，不是强制管线，不能从机制上证明每次都会执行补全。
• 分类标准靠文字描述传达，边界案例（比如很短但确实是需求的输入）的处理可能不稳定。
• 建议先在日常项目里试用几轮，根据实际体感调整模板里的分类示例和禁止事项。

版本历史

• v1.2.1（2026-08-25）：SkillHub 审核清包修正；将授权文件统一为 LICENSE.md，验收清单改名为 huiyi-acceptance.json，并移除包内其他 Skill 残留引用。
• v1.2.0（2026-08-24）：加入使用前后效果对照案例；补齐唐可创研 · 相光域 / CHROMATIC 版权归属声明与 LICENSE.md 文件，采用唐可创研统一 Source-Available 条款。
• v1.1.1（2026-08-24）：新增 check --project，对已安装且可能被用户手工修改过的规则做体检，覆盖“改坏 frontmatter 后规则静默失效”的场景。
• v1.1.0（2026-08-24）：定名「会意」（唤名 Skill 出品，经离线核验器六项检查，仅多音字「会」标注读 huì），采用用户定稿的 SkillHub 描述；规则文件与脚本同步更名。
• v1.0.1（2026-08-24）：按沙盘模拟反馈补齐信任线索（新增数据来源与免责声明板块）并为脚本增加 --version 输出。
• v1.0.0（2026-08-24）：首个版本。初版曾对所有输入做统一标准化改写，经用户反馈改为“口头对话不动、需求类做意图补全”，补全目标从格式标准化调整为理解完整性。