graft-comboagent

name	graft-comboagent
description	本地 agent 的 ragbase 远程客户端：直接查云端知识库（语义检索 / 列文档 / 翻 chunk）、嫁接已有 session 的执行成果，以及向已有 session 派发任务（dispatch）。
execution_mode	balanced
metadata	{"tags":["ragbase","kb-retrieval","rag","cross-session","graft","memory","remote","dispatch"],"emoji":"🌿","reserved":true}

Graft-Comboagent — ragbase 远程客户端

本地 agent（Cursor / Claude Code / Codex）通过本 skill 直连云端 ragbase，做这些事：

用途	说明	写入云端？	是否需要云端先跑过 session
A. KB 检索（核心高频）	列我有哪些 KB → 在 KB 里做语义检索 → 把命中 chunks 拉回本地给当前 agent 当 RAG 上下文	否	不需要
B. Session 嫁接	拉某次 comboagent 跑出来的 digest / round / 产出物，对照本地代码做分析	否	需要
C. 派发任务	把指令派给已存在的某个 session，让云端 agent 排队跑一轮（异步）	触发执行（不创建/删除资源）	需要（目标 session 必须已存在）
D. 上传到 KB（upload）	把本地文件灌进指定 KB，可选触发解析；本地的 findings / 缺陷 / 报告回流云端 KB	是（入库；仅限你有权限的 KB）	不需要
E. 安装 skill（install_skill）	把本地 skill 目录（SKILL.md + scripts/references）打包装进你自己的云端技能库；git 可选	是（写入 skills/users/你/）	不需要
F. 列 agents（list_agents，辅助）	列出你名下的 combo agents（bot），拿 agent_id 去建会话	否	不需要
G. 创建 session（create_session）	为指定 agent 新建会话；可 --first-prompt 一步建好并派发首轮，与 dispatch_task 形成"本地建会话→驱动执行"闭环	是（建会话记录）	不需要

服务端实现在 AgentFlow/src/skills/builtin/graft 与 api/apps/graft_app.py / api/apps/kb_app.py；upload 直接复用平台现成的 /v1/document/upload（+ 可选 /v1/document/run），install_skill 复用 /v1/skills/install_bundle，list_agents / create_session 复用前端现成的 /v1/combo_web/agents(GET) 与 /v1/combo_web/agents/<id>/sessions(POST)，均与云端 agent / 前端同源。 本 skill 是这些 HTTP 端点的本地包装。写边界很窄：只有 dispatch_task、upload、install_skill 和 create_session 四个写动作，其余全部只读（含新增的只读 list_agents）。

🌳 不知道用哪条 action？先查 references/action-decision-tree.md —— 按"用户意图"分类的 9 分支决策树，本地 LLM 1 秒选中。

远程调用方式（本地 skill 专属 — 必读）

所有命令都通过 scripts/call.py 发起；它会自动从 ~/.config/graft-comboagent/token.json（或 GRAFT_COMBOAGENT_TOKEN 指定路径）读取本地登录态，把 Authorization 头带上。

0. 配置 server（多租户 / 自部署 — 一次就够）

默认 https://xipnex.nox-lumen.com（公有云）。自部署 / 内网 / 临时 cloudflare tunnel 用 python scripts/login.py --server <URL> 或 GRAFT_COMBOAGENT_SERVER=<URL> 覆盖一次即可——server 会和 token 一起持久化到 ~/.config/graft-comboagent/token.json，之后所有 call.py 自动指向它。

⚠️ 切 server 一律走 login.py 重登，绝不要手改 token.json 的 server 字段：手改只换了地址、auth_token 还是旧 server 登的那个，仅在两端碰巧共用同一数据库时才凑效，否则直接 401，还会留下不一致状态。换环境 = login.py --server <新URL> 重登一次即可。

官方获取入口：用户在 https://xipnex.nox-lumen.com/combospace/user-setting/skills 可以查看/复制属于自己的 combo-agent 访问地址。如果用户没明确说用哪个 server，agent 应先建议他从这里复制。

用户丢一条完整 signin URL 时，agent 自己拆：例如 https://katrina-simpson-welfare-funeral.trycloudflare.com/zh/signin?email=test-syncore%40nox-lumen.com&password=<password> 应拆成：

• --server https://katrina-simpson-welfare-funeral.trycloudflare.com（去掉 /zh/signin path 和整个 query）
• --email [e-mail]（URL-decode：%40→@、%20→空格 等）
• --password <password>（从 query 原值取，URL-decode 后用）

然后一行直接登录（无需交互）：

python scripts/login.py --server <URL> --email <email> --password <pwd>

链接里没带 email/password 时，HIL 问用户，不要瞎猜：如果用户给的 URL 是 https://xipnex.nox-lumen.com/combospace/user-setting/skills 这种纯页面链接（没有 query string，或 query 里只有 server 信息），agent 只能拆出 server，email 和 password 必须停下来问用户索要——不要拿历史对话、配置文件、环境变量里的别人账号去登。

A. KB 检索（最常用，先看这里）

操作	命令
我有哪些 KB	python scripts/call.py list_kbs
按名字搜 KB	python scripts/call.py list_kbs --keywords ASPICE
KB 详情	python scripts/call.py kb_detail --kb-id <kb_id>
在 KB 里语义检索（核心 RAG 入口）	python scripts/call.py search --source document --query "传感器精度要求" --kb-ids <kb_id> --top-k 3
列 KB 里的文档	python scripts/call.py list_documents --kb-ids <kb_id>
看文档元信息	python scripts/call.py get_doc_profile --doc-ids <doc_id>
翻文档 chunks（顺序）	python scripts/call.py list_chunks --doc-ids <doc_id> --offset 0 --limit 20
取某些 chunks（精确 + 上下文窗口）	python scripts/call.py list_chunks --chunk-ids <id1>,<id2> --window 1 ← 返回目标 chunk + 前后各 1 个同文档 chunk，is_target=true 标命中

search --source document 走的是 ragbase 的混合检索（向量 + 全文 + reranker），等同于前端 KB 测试页的"提问"入口。

B. Session 嫁接

操作	命令
首次登录	python scripts/login.py（命令行输 email + password）
查看身份	python scripts/whoami.py
退出	python scripts/logout.py
发现 session	python scripts/call.py list_sessions --query <关键词>
看 digest	python scripts/call.py get_digest --session-id <id或名称>
取某轮	python scripts/call.py get_round --session-id <x> --round-id 5
跨 session 搜	python scripts/call.py search --query <kw> --session-id "*" --source round
读产出物（文本，整页）	python scripts/call.py read_file --path workspace/sessions/<sid>/<path>
读产出物（指定行范围）	python scripts/call.py read_file --path <p> --line-start 100 --line-end 200
读产出物（围绕某行取 ±N 行）	python scripts/call.py read_file --path <p> --center-line 500 --context-lines 50
文件内搜索定位（精确）	python scripts/call.py read_file --path <p> --find "关键词" --find-context 5 --max-find-matches 3 ← 比 grep_file 准；返回每处命中 + 前后 N 行上下文
下载产出物（原始字节）	python scripts/call.py download --path workspace/sessions/<sid>/<path> [--out <本地路径>]
列文件	python scripts/call.py list_files --query "workspace/sessions/<sid>/output/"
按产出物找	python scripts/call.py search_by_artifact --query <产出物名> --session-id <sid>
文件名模糊搜	python scripts/call.py grep_file --query <文件名关键词>

C. 派发任务（dispatch_task）

向已存在的某个 session 派一条新指令，云端会异步跑一轮，HTTP 立即返回。

操作	命令
派发任务（异步）	python scripts/call.py dispatch_task --session-id <名称或UUID> --prompt "请把附件总结成中文要点"
轮询执行进度（轻量）	python scripts/call.py list_sessions --query <名字片段> 看 updated_at 是否前进
看新一轮内容（重量）	python scripts/call.py get_digest --session-id <sid> 看 digest 是否多出新 round
找新轮号	python scripts/call.py search --source round --query <派发 prompt 关键词> --session-id <sid> 命中里的 round 字段就是 round_id
取某轮完整内容	python scripts/call.py get_round --session-id <sid> --round-id <N> （多 epoch session 加 --epoch <E>）

节奏建议：

• 重 agent（ASPICE / 多步 plan）单轮 1–5 分钟很正常，轮询间隔 30s ~ 1min，不要每秒一次
• updated_at 前进 ≠ 新 round 已写入：agent 在某一轮中间也会前进 updated_at；要等 round finalize 入库才能 get_round 到

dispatch 与"创建 session"不同：

• ✅ 只能派发到已存在的 session（owner 或共享给你的）
• ✅ 不创建任何新 session、文件、记录
• ✅ 服务端复用既有的 _DISPATCH_SEMAPHORE 做并发控制
• ❌ HTTP 派发不支持 wait=True（本地没有 source session 可挂起）；要等结果就用 get_digest / get_round 轮询
• ❌ 本动作自身不创建 session（要新建会话用下面的 create_session）；也不做批量派发

⚠️ 依赖后端部署：/v1/graft/dispatch_task 是新加的端点，需要后端跑了带这个改动的版本。如果返回 [ERR] Not Found，说明目标 server 还没部署。已部署能力（list_kbs / search / get_digest 等）不受影响。

典型用途：本地 agent 决定"这个 KB 检索结果不够，要让云端某个长跑 session 重新跑一轮带上新指令" → 派任务回去 → 用 get_digest 看新一轮产出。

C+. 创建 session 并驱动（create_session / list_agents）

dispatch_task 只能派给已存在的 session。要从本地新建 session 再驱动，用 create_session（第四个写口）；选哪个 bot 先用 list_agents（只读）拿 agent_id。

操作	命令
列我的 agents（bot）	python scripts/call.py list_agents [--keywords <名字片段>] [--limit 30]
为某 agent 建会话	python scripts/call.py create_session --agent-id <名称或UUID> --name "<会话名>"
一步建会话并派发首轮	python scripts/call.py create_session --agent-id <id> --name "<会话名>" --first-prompt "<首条指令>"
强制新建（不复用已有）	... create_session --agent-id <id> --allow-duplicate

关键约定：

• --agent-id 支持 agent 名称或 UUID；传名称时本地用 list_agents 解析（0 命中报错，多命中要求更精确名称或 UUID）。
• 默认复用：服务端 allow_duplicate=False 时，若该 agent 已有 session，会返回已存在的那个（不新建）；要每次都开新会话加 --allow-duplicate。
• --first-prompt = 建好后立即 dispatch_task 派发首轮（异步），返回里带 dispatched=true + queued_at_ms；之后用 get_digest --session-id <sid> 看新一轮概览（服务端 get_round 需具体 round 号，不支持 -1）。
• 复用前端「新建会话」同一入口（/v1/combo_web/agents/<id>/sessions），是老端点、无需后端新部署；建的 session 在前端会话列表、list_sessions 里都能看到。

闭环：list_agents → create_session --first-prompt → get_round 轮询——本地全程不碰前端即可开一个新会话并驱动它跑。

D. 上传本地文件到 KB（upload — 第二个、也是唯一的"入库"写口）

把本地文件灌进指定 KB。典型场景：本地 agent 跑出 findings / 缺陷分析 / 报告，要回流到云端某个 KB，供后续 comboagent / 团队检索。

操作	命令
先找目标 KB 的 kb_id	python scripts/call.py list_kbs [--keywords <名字>]
上传单个文件（默认只上传不解析）	python scripts/call.py upload --kb-id <kb_id> --file ./缺陷分析.md
上传并立即解析入库	python scripts/call.py upload --kb-id <kb_id> --file ./report.docx --parse
上传多个文件	python scripts/call.py upload --kb-id <kb_id> --file a.md --file b.xlsx --parse
上传整个目录（按模式）	python scripts/call.py upload --kb-id <kb_id> --dir ./findings --glob "*.md" --parse
指定 parser / KB 子目录 / 改名	... --parser-id naive --kb-path findings/2026 --name 缺陷汇总.md
看解析进度	python scripts/call.py list_documents --kb-ids <kb_id> 看每条 run / progress

关键约定：

• 默认只上传不解析。要让文件真正进检索（chunk + embedding），必须加 --parse（或事后在前端 KB 页点解析）。这是刻意的：避免误触发大批量解析占用云端队列。
• 并发上传（默认 8 路，--workers N 调整，--workers 1 退回顺序）。每个请求仍是单文件，doc_id 与本地文件保持 1:1 对齐。整目录/几十个文件直接 --dir 即可；上千文件的大批量仍建议走前端 KB 或云端 Source SKILL。
• 单文件 ≤ 200 MB；超限请走前端 KB。
• 上传后本地会把 content_hash(sha256) → local_path 追加到 .graft/uploads/manifest.jsonl（可用 --no-manifest 关）。这是 M4 架构边界：云端只拿文件字节，不持有任何指向你本地的路径；本地自己存映射，便于召回云端 chunk 时跳回本地原文。
• 只能上传到你有权限的 KB（服务端 upload() 用 current_user 校验 KB 归属；kb_id 不存在/无权限会被拒，本地不创建任何东西）。

返回 JSON 关键字段：uploaded[].doc_id / uploaded[].sha256 / parse_triggered / manifest（本地清单路径）/ failed[]（逐文件失败原因）。

⚠️ 依赖后端可达：upload 命中的是 ragbase 主服务的 /v1/document/upload，和 list_kbs 同一个 server；如果 list_kbs 能通，upload 就能通。

E. 安装本地 skill 到云端个人技能库（install_skill — 第三个写口）

把本地一个 skill 目录（含 SKILL.md，外加 scripts/ references/ assets/ 等）打包上传到你自己的云端技能库。git 可选：未配置技能管理仓库也能装（直接进 MinIO skills/users/<你>/）；配了仓库则照旧，可事后在仓库做版本管理。

操作	命令
安装本地 skill 目录	python scripts/call.py install_skill --skill-path ./my-skill
覆盖同名已装技能	python scripts/call.py install_skill --skill-path ./my-skill --overwrite
允许覆盖 builtin 同名 tool（罕见）	python scripts/call.py install_skill --skill-path ./my-skill --allow-shadow

关键约定：

• --skill-path 必须是目录，目录里直接有 SKILL.md；且目录名 == SKILL.md 的 name（后端 parser 强制 dir-name invariant，不一致会被拒）。
• 子目录（scripts/ references/ assets/…）会一并打包；.git / __pycache__ / node_modules / .venv 等自动跳过。
• 默认同名拒绝，要替换已装技能加 --overwrite。
• 服务端走 Layer-8 SkillSafetyValidator（和前端「技能上传」、离线 install_user_skill.py 同一道闸）：可执行 tool 命名冲突、危险写法会被拦；与 builtin 同名 tool 默认拒绝，确认覆盖才加 --allow-shadow。
• 只写进你本人的 skills/users/<你>/，不碰他人 / builtin。
• 装完即时可用：在 ComboAgent 会话或前端「技能设置」即可见。

返回 JSON 关键字段：skill_name / file_count / packed_files（实际打包的相对路径列表）。

⚠️ 依赖后端部署：install_skill 命中的是 /v1/skills/install_bundle（本次新增端点）。若返回 Not Found，说明目标 server 还没部署带此端点的版本；其余命令不受影响。

F. search 高级过滤（小众但 unified_search 支持）

search action 除了 --query / --kb-ids / --doc-ids / --top-k / --source，还透传：

参数	用途	示例
--time-start / --time-end	时间范围（ISO 8601）	search --source round --query "decision" --time-start 2026-04-01T00:00:00 --time-end 2026-04-15T23:59:59
--speaker	按发言人过滤	search --source round --speaker "Assistant"
--chat-id	渠道群聊 ID（仅 --source channel_history 用）	search --source channel_history --chat-id oc_xxx --query "升级"

这些参数和上面 A/B 节里的命令可以任意组合——本 skill 把所有非 dispatch / 非 KB-only 字段透传给 unified_search，用法对齐云端 agent 工具签名（详见 AgentFlow/src/memory/memory_os.py::create_tool）。

严格只读边界（仅 dispatch_task / upload / install_skill / create_session 四个写口）

call.py 在分发前会拒绝任何 rm / delete / remove / save / update / patch / put 类 action，以及裸 create、服务端禁用的 copy_kb_document / register_artifact。即便你的 token 在技术上能调那些端点，本 skill 也不给入口。删除 / 改写 KB 已有内容请走前端 UI。

只有四个写动作放行：

• dispatch_task：向已有 session 排队一次执行，不修改 / 创建 / 删除任何持久化资源。
• upload：把本地文件灌进你有权限的指定 KB（可选触发解析）。它新建 doc、不删/改 KB 既有内容；服务端用 current_user 校验 KB 归属。
• install_skill：把本地 skill 目录打包装进你本人的技能库（skills/users/<你>/）。服务端 Layer-8 校验后才落库；不碰他人 / builtin。
• create_session：为你名下的 agent 新建一个会话（可选 --first-prompt 派发首轮）。只建会话记录、复用前端「新建会话」同一入口；不删/改任何既有资源。（注意：被拒的是裸 create，create_session 是这里显式放行的具体动作。）

安全说明：upload 没有放宽任何服务端闸 —— graft 的 token 本来就是完整用户会话签名，技术上一直能命中 /v1/document/upload（和浏览器登录态等价）。本次只是在本地 skill 暴露了这个入口，并把它收窄成"只上传到指定 KB"。

read_file vs download：

• read_file：服务端 markitdown 把 docx/xlsx/pdf 转成 markdown 文本 → 适合 AI 直接阅读、截取片段
• download：服务端 原始字节流 → 适合用 Office 打开、用 pandas/openpyxl 读 xlsx、用户拿"原文件"

响应结构（必读 — 别看错了字段）

ragbase 后端把"给 LLM 看的内容"和"给前端调度看的元数据"放在不同字段。本 skill 透传，所以解析时记住：

字段	含义	谁该读
content	真正给 AI 看的正文（chunks/markdown/JSON 字符串）	AI / 你：这是核心数据
metadata.items	结构化元信息列表（session 表、文档表、文件表、search 命中表）	AI / 你：取 ID / score / 路径
metadata.usage_hint	服务端给的"下一步建议"（带样例 unified_search 调用）	AI / 你：可以参考但别盲从
metadata.budget_remaining / budget_used	本次返回消耗的 token 预算	跳过即可
compressible / flush_group	autogen 的 ToolCallSummaryMessage 调度字段	不是数据，跳过
batch_hint	"先写后读"提示，面向云端 agent（要它 write_file 持久化）	本地调用直接忽略
continuation_hint	"续读 offset=N"的 unified_search 写法提示	翻页时参考

最常见错误：把 content 当成 wrapper、跳过它去看 metadata，结果丢掉真正的数据。

上下文节流规则（必读）

1. 默认只调 get_digest，获取目录型概览（5–20K tokens）。
2. 按需 drill down：digest 指明 Round N 有关键结论，才去调 get_round --round-id N。
3. search --source document 控顶：本地 RAG 用法 --top-k 3-5（不要默认 10），单 chunk 几百字 × top-k = 上下文炸。
4. 大文件落地：read_file 返回的 docx/xlsx 转文本若 > 20K tokens，写入 .graft/<slug>/artifacts/<name>，由后续 Read 工具按需读取，不要全文进当前上下文。
5. 原始文件只 download，不读回 AI 上下文：下载后把路径给用户/后续流程用，字节流绝不塞进 prompt。
6. 不做全量拖库：禁止循环拉所有 round / 所有 artifact。
7. 翻页要明确：list_chunks / read_file 默认每次几 KB，必须传 --offset 才能继续；不要无限翻完整本书塞进上下文。

使用流程

流程 A：把云端 KB 当 RAG 用（不需要任何 session）

1. list_kbs                                              → 我能看到哪些 KB
2. (可选) kb_detail --kb-id <id>                         → 看 KB 大小、embedding 模型、parser 配置
3. search --source document --query "..." --kb-ids <id> --top-k 3-5
                                                         → 语义检索，命中 chunks 直接返回
4. (按需) list_chunks --doc-ids <doc_id> --offset 0      → 拿同一份文档的更多上下文（翻页）
5. 本地 agent 拿 chunks 做推理 / 写代码 / 答复用户

不要做的事：拿到一个 doc_id 后无脑 list_chunks 翻完整本书—— read_file 同一份文档可能更省 token，且不要超过 --limit 默认。

流程 B：嫁接已有 session 成果做对照分析

1. list_sessions [--query <关键词>]   → 定位 session（看 metadata.items）
2. get_digest --session-id <id|name>  → 看全貌（13 轮做了什么、产出了哪些文件、最终结论在第几轮）
3. 按需取回：
     get_round --round-id N           → 某一轮完整输出（多 epoch session 加 --epoch E）
     get_round --round-id 1 --end-round 10 --session-id X   → 多轮概要
     search_by_artifact --query <产出物名>   → 找产出物内容
     search --source round --query <kw> --session-id X       → 关键词搜索本 session
     read_file --path workspace/sessions/<sid>/...           → 读产出物文本（markdown 化）
     download --path workspace/sessions/<sid>/...            → 取原始字节文件（docx/xlsx 等）
4. 本地 Read/Grep 扫 src/ → 对照 session 结论做分析 / 比对

Digest 是目录，不是数据：digest 表里 R7 显示 工具: execute_code×12，不要由此推断"R7 跑了 12 个工具实例必须看每一个"。要看实际 reasoning 才 get_round。

不确定 session 名 → 用 * 广搜：

python scripts/call.py search --source round --query "F1 score 结论" --session-id "*"

→ 跨所有可见 session 搜，命中里带 session_name，再切到具体 session 走 digest。

详见 → references/cross-session-retrieval.md

流程 C：派发新任务给已有 session（dispatch）

1. list_sessions --query <session 名>          → 看 session 是否存在
2. (推荐) get_digest --session-id <id|name>    → 看当前状态、原 episode 最大 round
3. dispatch_task --session-id <名称或UUID> --prompt "..."
                                               → 异步排队，HTTP 立即返回
                                               → 注意 INFO 里会打印名称→UUID 的解析结果
4. 等 30s ~ 数分钟（重 agent 单轮可能 3–5 分钟；ping 类轻 prompt 30–90s）
5. 轮询找新 episode（**关键**：用 search，不要用 get_round 直接试 N+1）：
     search --source round --query <prompt 关键词> --session-id <sid> --top-k 5
                                               → 顶部命中带新 episode_id 前缀
                                               → episode_id 看 chunk id：ep_<sid>_<EPISODE>_e<E>_r<R>
6. (可选) get_round --session-id <sid> --round-id <R> --epoch <E>
                                               → 取整轮原文（注意：跨 episode 的 round 编号会重置）

dispatch 不是"创建会话再聊天"——目标 session 必须已存在；不能用 * 广派；prompt ≤ 32 KB。

最关键的一条 — episode 模型（容易踩坑）：

dispatch 在已有 session 里起一个新 episode（独立的执行任务），新 episode 从 R1 开始，不是在原 episode 上续 R14。所以：

• ❌ 错：dispatch 后用 get_round R<原最大+1> 找新内容
• ✅ 对：dispatch 后用 search --source round --query <prompt 关键词>，命中的 id 字段形如 ep_<sid>_<EPISODE>_e<epoch>_r<round>，新 episode 的 hash 跟原 episode 不同

updated_at 前进 ≠ round 已写入：agent 在某一轮中间会前进 updated_at，但 round 必须 finalize 才能 search/get_round 到。

round_id 边界：

• 服务端不识别 --round-id -1 表示"最新轮"（会被当成 None，报"需要 round_id 参数"）
• 拿不到具体 round_id 时，用 search --source round 命中里的 round 字段

通用规则

• 用户说了 KB / session 名称 → 直接传名称（自动解析为 ID）
• 不确定有什么 → 先 list_kbs / list_sessions 发现，再用名称或 ID 操作
• session 不确定是哪个 → --session-id "*" 广搜（仅 search action 支持）
• 先 Digest 后 drill down — 不要盲搜，先看全貌再定点取回
• 名称匹配多个 KB / session 时向用户确认，不要自行选择
• 可见范围包括自己的资源 + 团队共享的资源（list 接口已自动合并）
• 除 dispatch_task / upload / install_skill 外其余命令只读，不会修改云端任何数据；其余写操作在 skill 层 + 服务端双重拦截
• upload 默认只上传不解析，要进检索得显式 --parse；只上传到你有权限的 KB，不删/改 KB 既有内容
• install_skill 只装进你本人技能库（skills/users/<你>/）；目录名须等于 skill 名；走 Layer-8 安全校验，git 可选
• 原始字节文件只走 download，不读进 AI 上下文
• 不要把 dispatch_task 当成 fire-and-forget 的批量分发：每次调用都消耗云端 agent 资源（CPU + LLM token）

故障排查

症状	原因	处理
[ERR] 未登录	token 文件不存在	python scripts/login.py
HTTP 401 / 认证失效	access_token 被重置（别处 login 过 / 长期未用过期）	重新 python scripts/login.py
所有命令一致 401 / Not Found / DNS / 连接错误	server URL 不对（默认指向公有云，但你账号在自部署）；或 cloudflare tunnel 已换地址	python scripts/whoami.py 看当前 server；不对就 logout.py && login.py --server <你的真实 server>
whoami 显示有 token，但任何 call.py 都 401	whoami 只读本地文件不验证服务端，token 实际已失效	重新 login.py，不要信 whoami
Access denied	目标 session 不在你的可见范围	确认 owner / 共享关系；换 session_id
File not found: ...	path 拼错或文件不存在	先 list_files 或 grep_file 确认路径
Action ... not allowed via graft	误用了写 action（copy_kb_document / register_artifact）	graft 只读，换 action
Round N, Epoch 1 未找到	多 epoch session 时 round 编号跨 epoch；或 round 还没 finalize 入库	加 --epoch <E>；或先 get_digest / search --source round 确认 (epoch, round)
get_round 需要 round_id 参数（传了 --round-id -1）	服务端不支持 -1 表示"最新轮"；它把 -1 当 None	用 search --source round 找命中里的 round 字段；或 get_digest 看最大 round 后再传具体值
dispatch_task 返回 ok 但 get_round R<原最大+1> 始终未找到	dispatch 起新 episode，R 从 1 重新开始（不在原 episode 续号）	改用 search --source round --query <prompt 关键词>，看命中的 round 和 episode prefix
dispatch_task 返回 ok 但 get_round R<N> 一段时间内仍未找到	round 还在跑（pre-investigation/reasoning 未 finalize）