skillnerds/xskill/xskill-dev

Developing xskill

工具描述从哪来

Agno 框架直接把 @tool 装饰的 Python 函数 docstring 当作发给模型的工具描述， 参数说明也从 docstring 里解析。也就是说 docstring 就是模型上下文的一部分：

• 写给模型看，不写内部实现细节（内部细节放代码注释）。
• 系统提示词里不要再抄一遍工具清单，框架会自动注入 schema，抄了会漂移。
• generate 代理的轨迹工具在 src/xskill/agents/traj_tools.py，

通用工具在 src/xskill/agents/agent_tools.py， wiki 工具在 src/xskill/agents/llm_wiki.py。

改完 docstring 必跑：dump_schema

改任何工具的 docstring 或签名之后，跑一次导出脚本，看 Agno 实际生成的 schema 是什么样，确认模型看到的和你想的一致：

/home/admin/xskill/.venv/bin/python \
  scratch/standalone-generate/tool_surface/dump_schema.py

输出写在同目录 SCHEMA.txt。对照检查：

• 每个工具的 description 是否完整、有没有被截断或混进实现细节；
• 参数名、类型、必填项是否与函数签名一致；
• 新增或删除工具后，工具总数是否符合预期（generate 面当前是 16 个）。

SCHEMA.txt 可以进 code review diff，reviewer 能直接看到模型侧的变化。

上下文预算的流式陷阱

_wrap_with_context_mgmt 只包 model.invoke。任何用 stream=True 跑 agent 的路径都会走 invoke_stream，完全绕过 compact、spill 和超长兜底，模型跑在 后端原生窗口里（DeepSeek 是 1M），而且日志里一条 CONTEXT 事件都不会有。 产品 GenerateAgent 用非流式 agent.run() 所以没事；写实验脚本、demo、 新 agent 入口时必须非流式，或先给 invoke_stream 补包装。判断预算机制 是否真在跑，看 agent.log 里有没有 CONTEXT 事件（Compacted context、 Spilled、Compact was not needed 任意一种）。

llm_cfg 里开剪裁的键名是 enable_spill，不是 spill。

相关材料

• 工具面设计与取舍：docs/plans/2026-08-27-generate-tool-surface.md
• 独立实验台（Phoenix 观测、变体对比）：scratch/standalone-generate/，

入口 run_experiment.py，product 变体加载产品 traj_tools 与产品 SYSTEM_PROMPT，是验证产品行为的首选变体。