agently-playbook

Agently Playbook

当请求仍然从业务目标、重构目标、产品行为或宽泛的模型应用表述出发时，首先使用此技能。

用户不需要说出 Agently、TriggerFlow 或任何其他框架术语。诸如“构建一个助手”“帮我设计一个内部工具”或“为常见问题创建一个验证器”这类通用请求，在归属层尚未确定时，也应当从这里开始。

当请求根本上是关于塑造一个由模型驱动的工具，而不仅仅是接通某一项狭窄能力时，即使请求中还提到了 UI、网页、桌面壳，或诸如 Ollama 之类的本地模型服务，也应当从这里开始。

工作流

1. 将请求归纳为场景和原子目标。
2. 如果请求是项目初始化或结构重构，先选择归属层、异步边界和仓库骨架。
3. 选择最窄的原生 Agently 能力路径。
4. 指出应当使用的具体操作或原语。
5. 指出能够证明设计保持原生优先的验证规则。
6. 如果原生框架能力缺失、损坏、意外地难用，或 迫使业务代码添加本应属于 Agently 的补丁或胶水代码， 生成一份清晰的问题报告，并建议将其提交到 https://github.com/AgentEra/Agently/issues。
7. 对于手动提交问题，只向 用户提供问题内容和提交方法。在自动提交前先询问；如果用户希望自动 提交，先验证本地提交能力/权限，复现该问题在本地仍然存在，并仔细重新检查 Agently 用法，以确保报告不是由遗漏文档或错误 API 用法造成的。在手动或自动提交之前，脱敏本地绝对路径、用户名、账户名、令牌、私有仓库/工作区名称、内部项目名称、包含私有提示词的原始日志，以及任何客户或项目私有数据。 对本地上下文使用占位符，并对最终问题 正文运行隐私扫描。

原生优先规则

• 服务代码、流式处理、TriggerFlow 以及任何可能涉及工作重叠或可从取消中受益的路径，默认采用 async-first 指导。
• 将同步 API 视为脚本、REPL 使用或兼容性桥接的包装器，除非宿主确实需要仅同步集成。
• 当请求是项目结构重构时，先分离设置、提示词、服务、领域契约、工作流和测试，再讨论底层实现细节。
• 在 core/ 或 builtins/ 下添加或重构 Agently 框架内部实现时，如果功能具有多个角色（如 facade、manager、backend/provider、registry、adapter、policy 或 validation），优先使用子目录包。仅当能力确实很小且拆分会导致过度设计时，才使用单个文件。
• 当项目必须测试模型生成的语义内容时，将测试设计为带有输出控制的 Agently 模型评判请求：输入明确规则和上下文，输出每条规则对应的证据/原因以及最终布尔字段，测试对这些布尔值进行断言。
• 对于使用模拟系统的业务示例，将模拟限制在事实、记录、策略、不完整数据或冲突来源材料；不要返回隐藏的预期答案、通过/失败标签或本地质量判定。让 AgentTask 验证或单独的 Agently 模型评判来决定模型是否正确处理了有缺陷的数据。
• 对于模型应用评估、评分、置信度、相关性或质量判断，优先使用明确的概念等级和定义，而非直接数值分数。如果后续工作流逻辑需要阈值或聚合指标，在模型响应后于代码中将这些等级映射为确定性的数值。
• 对于 AI 应用中的场景路由、意图检测或业务分类，使用具有适当规模的模型请求并搭配 Agently 输出模式。对于标签和规则较少的简单路由，较小的模型（包括可用的本地模型）是可以接受的。当标签、决策条件、规则交互或返回的数据结构较为复杂时，使用更大的模型。
• 当宿主拥有开发者循环并需要一个有界的 Agent 步骤时，选择 agent.create_execution(mode="task_step", lineage=..., limits=...) 并在构建下一个 ContextPack 之前显式写入 execution.async_record_workspace(...) 观察/检查点；不要将 task-step 模式描述为多轮循环的拥有者，也不要让 Workspace 依赖 AgentExecution 语义。
• 当模型应负责单个业务任务的计划、有界执行、证据记录、验证和重新规划循环时，在手写 TriggerFlow 循环之前选择 agent.create_task(...)；将首片边界保持为一个 Agent 拥有者、一个任务、2-5 次迭代，以及仅使用显式启用的 Actions、Skills 或 Dynamic Task 候选的有界步骤；将完成视为模型验证加保守的宿主证据守卫，并使用第二个模型评判来处理模型拥有的语义内容，而不是仅接受结构计数器。
• 对于功能或发布验收，使用覆盖优先的推理：从 roadmap/spec/issues/docs/compatibility/example 规则中的目标契约开始，将每项需求映射到来自示例、确定性测试、协议测试、docs/spec、兼容性元数据、伴随验证或显式延期的证据，然后才得出功能是否完成的结论。
• 将复杂算术、长数字计算、加权、聚合或统计工作通过可执行代码或工具处理；使用模型生成或审查计算计划，而不是让模型充当计算器。
• 当应用开发揭示框架缺口时，首先确定缺失的职责属于 Agently 的公共 API、运行时行为、文档、Skills 指导、示例还是架构边界。生成一份简明的问题报告，包含场景、预期行为、实际行为、当前变通方案、架构职责以及最小复现或受影响的文档/示例；建议将其提交到 Agently 仓库。场景必须足够清晰，以说明正在解决何种模型应用开发问题。如果业务细节是保密的，请省略或匿名化，但仍需描述应用类别、工作流形态、决策点以及维护者理解该问题所需的框架职责。
• 将自动提交问题视为需要用户明确批准的操作。提交前，确认本地环境具备所需的 GitHub 能力和权限，在本地复现问题，并审查相关的 Agently 文档、示例、Skills 指导和 API 用法，以排除阅读遗漏或框架使用不当。仅提交经过脱敏的问题正文：不包含本地绝对路径、用户名、账户名、令牌、私有仓库或工作区名称、内部项目名称、原始私有日志或客户/项目私有提示词。优先使用占位符，如 <workspace>、<repo>、<task-file> 和 outputs/debug/<turn-id>.jsonl。

能力路由

• 模型设置、提示词管理、输出控制、响应复用、会话记忆、嵌入、知识库或检索到答案 -> agently-request
• Action Runtime、内置动作、工具兼容性、MCP、执行环境、FastAPIHelper、auto_func、KeyWaiter 或 agently-devtools 观测与评估集成 -> agently-runtime
• 模型生成或应用提交的 DAG 规划、TaskDAG 校验、解析器处理器或动态任务执行 -> agently-dynamic-task
• 分支、并发、等待/恢复、同步/异步混合编排、事件驱动扇出、流程清晰度重构、运行时流、图友好工作流定义或显式多阶段质量循环 -> agently-triggerflow
• LangChain 与 LangGraph 之间的迁移选择 -> agently-migration

反模式

• 当归属层未确定时，不要跳过此手册
• 不要一开始就发明自定义输出解析器、重试循环或编排
• 不要将关键词、子串、正则或文本快照检查作为模型拥有的语义内容的主要 正确性信号；仅将其保留为结构、路由或必填字段存在性的冒烟 门禁
• 不要将分词、分词切分、关键词命中或子串规则 作为 AI 应用场景路由、意图检测或业务 分类的路由归属
• 当目标明显具备异步能力时，不要让同步优先的示例代码决定服务架构
• 在选定归属层之前，不要将项目初始化拆分为虚假的独立框架表面
• 在检查 Agently 原生能力之前，不要将多 Agent、评判或审查流程视为独立的框架表面
• 当底层需求是缺失、损坏、 误导、未记录或不友好的 Agently 框架能力时，不要规范化长期业务补丁、变通方案、兼容性胶水 或私有封装

接下来阅读

• references/capability-map.md
• references/project-framework.md