Agentic Program：工具、技能、agentic function是同一个概念

1. 连续谱的轴是什么？谱上只有三个刻度吗？

轴是这段工作的步骤表落在哪里，以及它有没有约束力：工具那一端步骤表根本不存在（只覆盖一步，步与步之间的事全在对话里现决定）；技能是步骤表写成散文（写下来了，模型读了可以不照做）；agentic function是步骤表写成Python（解释器执行，不照做不可能）。

两个候选说法里，「多少写进代码」比「控制流握在谁手里」准。控制流那个说法在工具那一端会失真：mixture_of_agents是一个@function工具，体内是「并行扇出N个模型 → 最少成功数闸门 → 一次聚合调用」，控制流完全在代码里。所以控制流不是区分点。

可测量的定义：同一件事跑两遍，有多少东西一定相同。工具几乎没有，技能大致相同、细节会漂，agentic function骨架逐字相同、只有内容不同。这把轴从一个说法变成一个能测的量。

不是只有三个刻度。三个是常见落点。骨架里放一个decision.make是硬里嵌软；技能第三步写「调survey_references」是软里嵌硬。所以谱是连续的，一段工作可以一部分硬一部分软。

还有一条要写进设计：装饰器不决定你在谱上的位置。见第3问。

2. 我要加一个能力，该写哪一种？

三问，第一个命中就停（图见第3节）：

Q1 需要模型在中间参与吗？不是问「调不调模型」，是问「要不要停下来看模型答了什么，再决定后面怎么走」。答否就是工具，哪怕体内调了模型。mixture_of_agents体内调N+1次模型，外面看是一进一出，所以它是工具，写法没错。

Q2 参与点提前点得出来吗？写代码的时候能不能说出模型要在第几步、一共几次进来。答否就是技能：每次几个、在哪儿，得跑起来看到东西才知道。

Q3 漏一步会被当场发现吗？这是「值不值」，不是「是什么」。会发现（结果明显不对）就技能够用，别付一份代码的维护成本。不会发现（验证过再交付、引用要核实、八个仓库都要查）才写agentic function。把清单从记性搬进代码的唯一理由，就是漏了不会被发现。

三种各有一条可证伪的验收：工具选对了，参数schema能完整描述输入，description里不需要写「用之前先……」；技能选对了，内容是判断依据不是步骤编号，整份文档里没有「第1步/第2步」；agentic function选对了，你能说出这一次的模型调用次数上界，说不出来说明流程没真的固化。

这个判据能解释现有分布（46 / 7 / 4），不是事后编的：绝大多数能力真的是一进一出，「参与点提前点得出来而且漏了看不出来」本来就是少数。第四种情况是「这件事只做一次」，那就直接干，什么都别写。

3. 两个装饰器要不要合并成一个、用参数区分？

不合并装饰器，合并schema生成器。下面是核实的结果。

已经统一的部分比想象的多。@agentic_function._register_as_tool（function.py:963）调的就是@function用的那个_build_and_register_tool（_runtime.py:1037）。同一个_registry，同一个tools数组，同样六层门禁，20个关键字参数同名同义（name、description、parameters、label、toolset、unsafe_in、check_fn、requires_env、can_use、defer、cache等）。所以注册路径、工具面暴露、调用约定这三样差得很小。

真正差的第一样：参数schema生成器是两份，而且已经漂了。_build_parameters_schema（_runtime.py:426）会读docstring的Args:段、把可选参数放宽成允许null、递归写additionalProperties:false、用get_type_hints解字符串注解、认PEP-604的X | None、认Literal。_build_agentic_tool_spec（function.py:1302）一样都没有：它读input={}的UI元数据，只判typing.Union而PEP-604的origin是types.UnionType，认不出的一律落到{"type":"string"}。 _runtime.py:312-321有一整段注释说明这个union问题曾经打断过生产里的工具调用，那个修复没有搬到agentic这边，现在还是活的。这一处该合，合完删约60行近似重复，顺手修掉一个活问题。

真正差的第二样：_is_agentic不是装饰，是开关。它扛着九处行为：loop_runner.py:108决定渲染成带执行图的运行块还是折叠的工具卡；runtime_attach.py:128决定要不要fork出子进程跑（为了停止键能SIGKILL整个进程组）；forced_tool.py:74和webui/routes/chat.py:184是两道硬门，非agentic直接报错或400；tree.py:93决定进不进Functions面板的内建列表。合成一个装饰器就要把这九处压进一个参数，那个参数一翻就同时翻九件事，和两个装饰器是同一回事，只是更难发现。

还有一个名字撞车得先解决。_build_and_register_tool(expose: bool)的expose是「给不给模型看」，@agentic_function(expose="io"|"llm"|"full"|"hidden")的expose是「DAG里露多少」。两个不相干的意思共用一个词，而且agentic那边压根没给注册函数传expose（function.py:963-977），永远取True。

为什么概念统一而实现不统一是可接受的：因为两个装饰器区分的从来不是概念位置。mixture_of_agents用@function写了一个完全固化的多步流程，站在谱的最右端；interaction_demo用@agentic_function写了一个很小的东西。装饰器选的是内部要不要记账：@agentic_function的模型调用走runtime.exec，每次落一个ModelCall节点进DAG，受expose／render_range约束；@function的模型调用（mixture_of_agents用complete_simple直连）不进DAG，只在usage里记一笔call_kind="tool"。这是一个和「多少写进代码」正交的维度，不该合并。

代价对比：合schema生成器约删60行、修一个活问题、改两个调用点，该做；合装饰器要把九处行为压进一个开关、先给expose解歧义、还要在「description取第一段还是取整份docstring」里二选一（4个agentic function的docstring就是提示词，截成第一段会直接改掉它们的行为），不该做。

4. skills_bundled/那个目录怎么办？技能要不要也有个「注册」动作？

技能曾经注册了两套，而且两套互不认识：agentic_programming/skills.py只读front matter的两个字段、扫两个目录、同名先见先赢；skills/loader.py读正文、还读category／allowed_tools／triggers／aliases、扫五个来源、同名后见先赢。三条后果都是实打实的：skills_bundled/不在喂系统提示那条路上，所以distill和self-update模型根本看不见；两个渲染器输出不一样，chat那条路截到20条且不给路径；SkillTool写好了从来没注册。

现在三条都合了。一个加载器：agentic_programming/skills.py已删除，Runtime(skills=...)和skills_index组件都走skills/loader.py。一份清单：format_skills_for_prompt是唯一渲染器，两条路输出同一段<available_skills>，带name、截到250字符的描述首行、绝对路径。一个加载动词：skill工具（functions/tools/skill/）进了注册表，收层级名或不歧义短名，返回正文加基准目录加同目录文件清单，调用记入skills/tool.py的invoke_log.jsonl，Skills页读的就是这份记录。

冲突顺序也定死了：bundled → remote-cache → plugin → user → project，后见先赢。用户自己写的盖过给他装的，装的盖过随程序发的；同是用户写的，项目里那份盖过家目录那份。之前remote-cache排在最后，从ClawHub拉一个同名技能会盖掉用户自己写的，方向反了。

skill工具在DEFERRED_DEFAULT_TOOLS里：清单每轮已经列了每份技能的名字和描述，schema只在模型真要加载时才由tool_search拉进当轮，平时只占catalog一行。read打开清单里的location同样有效，两条路都留着。skills.py:19当初写的取舍（「We intentionally reuse read」）没有作废，只是不再是唯一入口。

技能现在和工具在同一张表里、同一套门禁、同一份清单。让概念成立的不是共用装饰器，是共用注册表和共用清单。

5. 统一之后模型眼里该是一种还是几种？

曾经是三种半，那半种是同一批技能在chat那条路上的第二种写法，无路径、截到20条。它已经删了，现在是三种：①tools数组里的schema（@function加@agentic_function，split_tools_for_dispatch拆的）；②deferred目录（defer=True的，系统提示里一行name加description，靠tool_search把schema拉进当轮）；③<available_skills>（name加description加绝对路径，靠skill工具或read打开）。

②和③形状完全一样：系统提示里一行name加description，外加一个把正文拉进来的动作。区别只有动作的名字和目录的标签。skill工具本身就在②里，所以两份目录现在至少指向同一套加载语义；把它们并成一份清单是下一步，那是渲染层的事，注册层已经并完了。

终点是两种：能直接调的（tools数组，带schema），和知道名字得先加载的（一份目录，一个加载动词，按类型分派：deferred拉schema，技能拉正文）。

两家参考实现已经这么做了，而且都是把「加载」做成工具。opencode的skill是内建工具之一（packages/opencode/src/tool/registry.ts:210，和read／grep／task并列），入参name，返回<skill_content>加基准目录加<skill_files>，带permission: "skill"走同一套审批；系统提示那段（core/src/skill/guidance.ts:18）直接写「Use the skill tool to load a skill when a task matches its description」。claude-code的SkillTool和ToolSearchTool并排在同一个工具列表里（src/tools.ts:212），而且更进一步：getSkillToolCommands的注释写着「SkillTool shows ALL prompt-based commands that the model can invoke」，技能和斜杠命令进的是同一份清单。

清单要有预算，数可以直接抄claude-code的：SKILL_BUDGET_CONTEXT_PERCENT = 0.01（上下文窗口的1%），MAX_LISTING_DESC_CHARS = 250，注释说明理由「The listing is for discovery only，the Skill tool loads full content on invoke」。我们已经有全部零件，差的只是接成一条。

6. 这次不改代码。真要改名，影响面多大？

分四层，代价差一个数量级。见下表。建议：0和1现在就做，2等新名字用顺了再机械替，3单独当一次提示词改动来评，4不做。

decision.make现在的形态够不够表达「让模型判断哪条值得抄」？

不够，而且方向不对。「哪条值得抄」不是从一组固定选项里挑一项，是产出一个开放列表，而decision.make是闭集选择器。 要分清两种入口：闭集分支（下一步走哪条路）用它，在agentic program里应该少见；开放产出（这一步交出什么内容）用runtime.exec加输出契约加代码侧结构检查，那才是常态。 第二种现在没有便利入口，exec(response_format=)零使用，三个地方各手写一遍JSON解析。补一个exec_json(prompt, schema)就够，约25行，不是新层。

跑了半小时的 program 中间失败了怎么办？session.py管不管？

不管。Session是ask_user在CLI下的文件传递目录：uuid键目录，meta.json加一个answer触发文件，原进程wait_for_answer轮询，run_with_session在finally里cleanup()删目录。跑了半小时崩掉，它什么都不留。 真正落盘的是DAG：create_pending_call_node进入时写status=running、output=None的节点，_update_function_call_exit退出时补上输出和耗时，进git支撑的会话库。 每个已完成步骤的输入和输出已经在磁盘上了，只是没人读回来。最省的补法是once(key, fn)，约30行，不新增写入方、不新增文件格式。上界必须说清：只对「输入决定输出」的步骤正确，写文件的步骤是被跳过不是被回放，所以要显式选择加入。

成本可预测是不是主要收益之一？

是，但要说准：固化之后不是每次调用次数固定，是次数有上界且上界写在代码里、看得见。 排在成本前面的收益其实是另外两个：漏步骤变得不可能（清单是代码，不是记性），结论可核实（出处检查是闸门，不是礼貌）。 三次真实事故里，两次是漏步骤和没核实，一次是两个agent撞同一个文件，都不是成本问题。