graft-comboagent

本地 agent 的 ragbase 远程客户端：直接查云端知识库（语义检索 / 列文档 / 翻 chunk）、嫁接已有 session 的执行成果，以及向已有 session 派发任务（dispatch）。

Repository: Nox-Lumen-tech/combo-skills
Last source activity: June 9, 2026 at 00:13
Detected SKILL.md language: Chinese
Stars: 4
Forks: 0

Install options

The review-first prompt is selected by default. You can switch to a direct command or download a local copy.

Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.

A direct command skips the review prompt. Inspect the source before running it.

npx skills add https://github.com/Nox-Lumen-tech/combo-skills --skill graft-comboagent

The command stays on one line. Scroll horizontally to inspect it before copying.

Prefer a local copy? Download the files currently available to SkillsMP.

Review the source files

Read SKILL.md and any companion files shown by SkillsMP before deciding whether to install.

File Explorer

10 files

SKILL.md

Source instructions · Read-only preview

Back to search Back to installation

File Explorer

10 files

SKILL.md

Source instructions · Read-only preview

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 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 检索（最常用，先看这里）

操作	命令
我有哪些 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，结果丢掉真正的数据。

上下文节流规则（必读）

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

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 专属 — 必读）

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

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

--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>

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）；也不做批量派发

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

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

操作	命令
列我的 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 目录	`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（实际打包的相对路径列表）。

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 四个写口）

只有四个写动作放行：

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，结果丢掉真正的数据。

上下文节流规则（必读）

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

不确定 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）

graft-comboagent

Source facts

Install options

Review the source files

More from this repository

Graft-Comboagent — ragbase 远程客户端

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

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

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

B. Session 嫁接

C. 派发任务（dispatch_task）

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

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

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

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

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

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

上下文节流规则（必读）

使用流程

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

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

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

通用规则

故障排查

Graft-Comboagent — ragbase 远程客户端

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

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

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

B. Session 嫁接

C. 派发任务（dispatch_task）

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

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

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

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

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

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

上下文节流规则（必读）

使用流程

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

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

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

通用规则

故障排查

More from this repository