JiuwenSwarm 装好之后跑不起来，通常不是编排层的问题，而是模型端点和工具实现还没接。平台负责的是编排：任务怎么声明、角色之间怎么流转、一次运行的状态怎么落日志；模型走哪个端点、密钥放哪、工具函数怎么注册、入参怎么校验，这些要按仓库文档自己配。先分清这两类职责，再决定改哪一层文件，能省掉大量“改了编排结果模型报错”的来回。判断依据不用凭印象，直接去仓库文档找对应的配置节：找得到配置说明的，就是要你自备；只在快速开始里出现一条 run 命令的，多半是平台自带。

把 JiuwenSwarm 分两层维护：编排配置归平台，模型接入与工具注册归你自己。适用场景是首次接入、换模型、加工具。动作上先列一张自带项与自备项的对照表，把模型配置单独拆成一个文件；验证方式是改完只重跑任务，看日志里模型端点和工具名有没有按预期出现。边界要守住：文档没写清的字段不要猜，留空回仓库的示例目录或 issue 里找，宁可慢一步也不要写一个看起来对、实际被忽略的配置项。

对照仓库文档列出自带项与自备项

这一步的目的不是把文档抄一遍，而是把“谁负责”写死，避免同一个参数在编排文件和模型文件里各配一次。下表的第二列同时写归属和出处，出处只填文档里确实成节的内容；文档里找不到对应说明的，留空标记为待确认，不要凭经验补。

表里出现“待确认”的行，就是接下来排查会卡住的地方，建议在动手前先去仓库的示例目录翻一遍，比对着别人的配置文件改更省时间。

把模型接入写成可替换的配置片段

换模型时最怕的是一改就要动好几处，所以模型相关的字段全部收进一个文件，编排文件只按名字引用。下面的骨架是占位写法，字段名、文件路径、是否支持环境变量插值，都以仓库文档的「模型接入」一节为准，照着替换。

# config/model.yaml（路径与字段名以仓库文档为准）
model:
  profile: default            # 编排文件引用这个名字
  name: <model-id>           # 换成实际要用的模型标识
  base_url: <endpoint>       # 服务地址
  api_key: ${MODEL_API_KEY}   # 从环境变量读，不要写进仓库
  params:
    temperature: 0.2
    max_tokens: 2048

换模型只改 name、base_url、api_key 三处，profile 名保持不变，编排侧就完全不用动。改完的验证方式：先确认环境变量在当前 shell 已经生效（echo $MODEL_API_KEY 能看到值，注意 .env 的加载位置和启动命令的工作目录是否一致），再跑一条步骤最少的任务，看日志里请求实际打到的地址是不是新端点、返回内容有没有被正常解析成模型回复。如果报鉴权错误，先查密钥读取路径，再去怀疑字段名拼写。

工具注册走一遍最小闭环

工具的问题几乎都不是“没写函数”，而是注册名和调用名对不上。先确认注册项齐全，再跑一次调用看日志，比反复读代码有效。

• 工具名：唯一，编排文件里引用的就是这个名字，大小写要一致
• 描述：给模型判断“什么时候该用”看的，写得太泛会导致工具被误选或不被选
• 入参 schema：字段名、类型、是否必填，缺一个都可能在调用时被拒
• 返回值结构：模型要能读懂，字段尽量平铺，不要嵌套太深
• 实现入口：函数路径或 HTTP 地址，确认注册时能被加载到
• 超时与失败处理：文档若支持就配上，不支持则记下来作为已知限制

[registry] loaded tool name=search_docs params=[query:string]
[run] step=2 action=tool_call name=search_docs args={"query":"接入说明"}
[registry] invoke search_docs status=ok
[run] step=3 action=model_call profile=default

调用失败时按顺序看三个字段：name 是否和注册名逐字相同；args 是否通过了 schema 校验（类型错、必填缺都会在这一步掉）；registry 的 loaded 行里有没有出现这个工具——没有出现说明注册文件根本没被读进去，问题在加载路径而不是工具逻辑。

编排侧只改任务声明，不动接入配置

两类配置要能分开维护，前提是目录上先分开，编排文件里只出现 profile 名和工具名，不出现端点、密钥和实现路径。

project/
├── config/
│   ├── model.yaml      # 接入层：模型端点与密钥
│   └── tools.yaml      # 接入层：工具注册
└── tasks/
    ├── daily_digest.yaml
    └── review.yaml

# tasks/daily_digest.yaml —— 只声明编排，不写端点
task: daily_digest
model: default
steps:
  - role: planner
    tools: [search_docs]
  - role: writer

验证独立性的办法很直接：只改 tasks/ 下的步骤顺序或增删一个 role，重跑任务，日志里 model_call 打到的 base_url 应该和改之前完全一样；反过来只改 config/model.yaml 的 profile 内容，任务声明文件不应该产生任何 diff。用 git status 就能看出来，哪个文件被动了说明分层没做到位，需要回去把共用字段抽出去。重跑任务时不需要重新配置模型，只要配置文件路径没变，加载的就是同一份接入配置。

仓库更新后先跑哪几项自检

更新仓库之后最常见的破坏不是报错，而是某个配置节静默失效。下面几项按顺序跑一遍，每项都能在一个命令或一屏日志里判断。

任何一项不过，先回退配置再排查代码：把 config/ 和 tasks/ 纳入版本管理，更新仓库前打一个 commit 或 tag，出问题用 git checkout -- config/ tasks/ 恢复到上一份可用配置，再逐个文件替换定位；没有用 git 的，至少保留 model.yaml.bak、tools.yaml.bak 两份备份，回退时直接覆盖回去并重启一次确认日志恢复。回退只解决“先跑起来”，配置被新版本文档改了字段名这件事，仍要回到仓库文档对应小节逐条核对。