SkillNerds 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，是验证产品行为的首选变体。