行为注释：为什么 readonly 和 destructive 指导 LLM 规划
Source: Dev.to
介绍
在我们之前的文章中，我们讨论了 Schema 如何充当 apcore 生态系统的“邮递员”——确保数据以正确的格式交付。但仅仅知道如何投递信息对于自主代理来说还不够。代理还需要理解投递的影响。
想象一个被指派**“修复数据不一致”**的代理。它发现了两个模块：common.user.sync 和 executor.user.reset。如果没有行为上下文，代理可能会选择看起来更“彻底”的 reset 模块，却没有意识到这会删除整个用户档案。
这就是 行为注解 成为 apcore 协议核心技术支柱的原因。在这篇第十三篇文章中，我们将探讨这些简单的布尔标记如何充当 AI 规划器的“认知止停标志”。
Behavioral Annotations Overview
- Schemas 处理 语法（例如，“Is it a string? Is it required?”）。
- Annotations 处理 语义（例如，“Is it safe? Is it permanent?”）。
通过提供这一语义层，我们从 “Code‑Calling” 转向 “Skill‑Perceiving”。AI 代理不再把你的模块视为黑盒；它能够感知它们的个性。
标准化注解
The apcore protocol defines a set of standardized annotations grouped into Safety（安全）、Execution（执行）and Governance（治理）:
| Annotation | Meaning |
|---|---|
readonly | 无副作用。适用于发现和无限重试。 |
destructive | 数据将被永久修改或删除。 |
idempotent | 相同输入的多次调用产生的效果与一次相同。 |
pure | 输出仅依赖于输入；不依赖外部状态。 |
streaming | 模块返回事件/块的流，而不是单个块。 |
cacheable | 结果可以被存储以供将来使用。 |
cache_ttl | 结果保持有效的时长（秒）。 |
paginated | 结果是系列的一部分；需要光标/令牌继续。 |
requires_approval | 暂停执行，等待人工“是”(HITL)。 |
open_world | 与非确定性外部系统交互（例如 Web、电子邮件）。 |
internal | 对标准发现隐藏；用于系统间调用。 |
extra | 用于特定表面或自定义行为提示的通用映射。 |
大型语言模型如何使用这些标记（规划阶段）
当一个高级代理（例如 Claude 3.5 或 GPT‑4o）收到工具列表时，它会构建一个 Plan of Action（行动计划）。
- 如果某个模块被标记为
destructive: true，模型内部的安全对齐通常会触发 caution（警示）状态。 - 代理可能会先检查 “dry‑run” 标记，或者向用户请求确认：
“我已经找到了解决办法，但它需要一次破坏性的数据库操作。您想让我继续吗？”
如果没有这些注释，代理就会 blind（盲目）——先执行计划，然后才发现后果，往往已经为时已晚。
使用 apexe 自动注释
自动注释的强大功能是 apexe 的亮点——这是一款用于包装现有 CLI 的工具。当你运行：
apexe scan git该工具不仅会提取参数，还会通过模式匹配对命令进行分类：
git status和git log→readonly: truegit push --force和git reset --hard→destructive: true
只需扫描帮助文本，apexe 就会创建一个 安全工作区，让 AI 代理能够在不意外破坏生产分支的情况下浏览你的代码库。
结论与下一步
Engineering for AI means engineering for Cognitive Safety.
通过使用 apcore 行为注解，你可以将原始函数转化为“专业技能”，为 AI 提供负责任规划所需的智慧，减少令牌浪费，防止代理灾难。
Next, we’ll dive into the AI’s Short‑Term Memory: the Context Object and how it manages traces and state across complex module chains.
接下来，我们将深入探讨 AI 的 短期记忆：上下文对象以及它如何在复杂模块链中管理痕迹和状态。
This is Article #13 of the apcore: Building the AI‑Perceivable World series. Safety is a protocol‑level primitive.
这篇文章是 apcore：构建 AI 可感知世界 系列的第 13 篇。安全是协议层面的原语。
GitHub: