agently

Agently

当请求以产品行为而非 Agently API 的形式表达时，请从这里开始。在选择文件或机制之前，先选择最精简的原生归属方。请求中无需提及 Agently。

当 Agently 开发者需要了解模型节点的职责、调整执行效果、检查数据流或冗余上下文，或判断模型与 Host 的归属时，请使用协作审查，无需等待有人说出“Prompt review”。高亮流程和交接请通过 agently-design 路由，相关 Prompt 表格请通过 agently-request 路由，并按可读性和依赖关系分组。与审查无关的机械性工作不要纳入此审查方法。

对于多轮设计、Prompt 修订或实验评估，每轮实质性讨论开始时，都要提供一张状态在左、事项在右的表格，以及一张带时间戳和版本号的变更日志表格。请遵循协作记录指南。

工作流

1. 将请求分解为目标、输入、输出、副作用、证据和生命周期需求。
2. 将模型负责的语义决策与 Host 负责的验证、授权、身份关联、算术和效果区分开来。
3. 将每项决策、状态和效果分配给一个现有归属方。
4. 对于非平凡流程，映射节点、值/事件边、不变量，以及每个请求字段和阶段在生产环境中的必要性。
5. 当调用方拥有异步边界时，优先采用异步实现；分别验证确定性契约与模型负责的质量。
6. 如果没有原生归属方能够承载所需不变量，请报告框架缺口。不要用业务专属粘合代码或透传门面掩盖缺口。

按归属方路由

• 单一请求类别——提供商配置、提示词、结构化输出、LongContent、auto_continue、TTS/STT 音频、结果复用、会话记忆、嵌入或检索——使用 agently-request。
• AgentExecution 插件、最终策略、Actions、Shell、MCP、ExecutionResource、TaskWorkspace、RecordStore、服务暴露、RuntimeEvent 或 DevTools 使用 agently-runtime。
• 进程内任务生命周期、同步/异步桥接、不依赖事件循环的句柄、结算、重放通道或本地监听器使用 agently-stage。
• 跨归属方架构、请求/值/事件拓扑、证据和身份边界、生命周期、压力或信息丢失审计使用 agently-design。
• 由开发者负责的推进、分支、并发、审批、等待/恢复、重试或可安全重启的编排使用 agently-triggerflow。
• 从 LangChain、LangGraph、LlamaIndex、CrewAI 或类似系统迁移时，使用 agently-migration。
• 显式的、由模型生成或由应用提交的无环 DAG 数据属于低频高级场景。请留在此处并阅读 references/task-dag.md；普通 Agent 或工作流任务不要引入 TaskDAG。

按需阅读

• 条件式项目形态和全栈参考资源： references/project-framework.md。
• TaskContext、ContextReader、TaskWorkspace、RecordStore、SkillLibrary 和 SkillsExecutor 兼容门面： references/context-and-skills.md。
• 提交的 TaskDAG 数据和 DynamicTask 便捷门面： references/task-dag.md。
• 先模拟再验证真实模型： references/model-quality-validation.md。
• 跨层拓扑审计方法位于 agently-design，尤其是其中的 ../agently-design/references/execution-topology-validation.md。

核心所有权规则

• ModelRequest 拥有一次模型交互及其提示词/输出契约。
• AgentExecution 拥有一次 Agent 运行及其选定的生产者、控制项、 结果和流。在 4.1.4.8 中，request、plan、long_content 和 long_task 是插件；请阅读运行时 Skill 的 执行契约。
• agent.create_task(...) 返回一个长任务 AgentExecution 草稿。其 生产者负责规划、证据和重新规划；已发布的 AgentTask 导入仍保持兼容。
• AudioModelRequest 拥有独立的 TTS/STT 驱动。Agent 音频调用和依赖音频的 Execution 插件需要显式音频绑定。
• ActionRuntime 拥有可由模型调用的操作；ExecutionResource 拥有实时依赖的生命周期。
• TriggerFlow 拥有应用可见的编排和运行时信号。
• TaskContext 拥有任务信息并创建绑定到消费者的读取器； TaskWorkspace 拥有文件；RecordStore 拥有持久化记录和恢复； SkillLibrary 拥有不可变的已安装 Skill 版本。
• Agently.skills_executor 仅用于管理/上下文兼容。不要重新创建已移除的通用 Workspace、ContextBuilder、SkillsManager、 Skills 路由/策略、skill_activation 或 workspace_operation 所有者。

ModelRequest 边界

对于必须满足下游接口的输出：

• 运行时事实放入 .input(...)；
• 权威模式、签名和源事实放入 .info(...)；
• 转换和调用规则放入 .instruct(...)；
• 实际使用的精确结构放入 .output(...)。

为每个使用的字段声明类型、语义、必填性、枚举/格式/范围、可空性和 跨字段约束。让结构化 ModelRequest 负责源自文本的意图、路由、规划、相关性或质量判断；让宿主代码验证有界枚举/键并执行操作。

不要请求隐藏的思维链。只有在有界过程字段具备明确的角色、边界、消费者、保留规则和失败行为时，才有使用它的正当理由。

项目与验证门槛

从组合、设置、提示词契约和测试着手构建单请求应用。只有当前所有者和消费者需要时，才添加工作流、服务、Actions、本地 Skills、实用工具或资源。逻辑节点并不自动对应一个文件或类。

确定性测试用于证明模式、身份、生命周期、核算、文件或记录操作以及安全性。语义质量需要明确的评判标准，并由结构化编码 Agent、模型或人工进行审核。应将关键性（硬性门槛或软性目标）与评估方法（确定性或语义性）分别分类。

对于真实模型的声明，应先定义评判标准，如实标注模拟结果，使用获授权的最小代表性运行，并将原始事实与判断分开记录。真实追踪记录优先于模拟预期。

反模式

• 未检查原生所有者之前就自建解析器、重试管理器、状态存储或调度器。
• 将关键词、子字符串、正则表达式、分词或手写评分表作为语义处理者。
• 未消费的输出字段、请求阶段、包装器或项目目录。
• 未分析依赖关系就让复杂流程全部串行执行。
• 将完整源内容、包含大量身份信息的记录或原始元数据复制到每个提示词中。
• 将预制答案、隐藏的预期答案测试数据或仅用于测试的生产分支，当作框架能力的证据。