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，做这些事：

服务端实现在 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 test-syncore@nox-lumen.com（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 检索（最常用，先看这里）

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

B. Session 嫁接

C. 派发任务（dispatch_task）

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

节奏建议：

• 重 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。

关键约定：

• --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 / 团队检索。

关键约定：

• 默认只上传不解析。要让文件真正进检索（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-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，还透传：

这些参数和上面 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 当成 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）

故障排查