上下文服务（Context0）快速入门

1. 安装

npm install -g @polardbx/ctxdb0

2. 配置

先建立连接，再安装到目标 AI 工具：

printf '%s' "$CTXDB0_API_KEY" | ctxdb0 connect \
  --profile default \
  --endpoint http://<your-endpoint> \
  --user-id <终端用户标识> \
  --api-key-stdin \
  --json

ctxdb0 attach --host claude --json
ctxdb0 doctor --host claude --json

--host 取值：

3. 验证

ctxdb0 doctor --host claude --json

doctor 同时检查连接 profile 与 API 可达性、Host 安装状态、受管资产完整性，全部通过即接入成功。

4. 工作原理

插件由三部分组成：

• 生命周期 Hooks（自动）：会话开始时注入历史上下文；每个有效完成回合自动提交至后端，异步提炼长期记忆。

• 显式 CLI（主动）：Agent 按需调用 ctxdb0 memory / knowledge / sessions / skills 等命令读写记忆、检索知识库。

• 静态 Skill（指导）：随插件安装 ctxdb0-context Skill，Agent 根据用户自然语言自动选择合适的 CLI 命令。

5. 命令速查

所有命令均支持 --json，Agent 调用时应始终携带。

# 连接与诊断
ctxdb0 connect --profile <name> --endpoint <url> --user-id <id> --api-key-stdin --json
ctxdb0 setup --host <host> --endpoint <url> --user-id <id> --api-key-stdin --json
ctxdb0 attach  --host <host> --json
ctxdb0 doctor  --host <host> --json
ctxdb0 config show --json
ctxdb0 refresh --host <host> --json

# 记忆
printf '%s' '项目选用 TypeScript + Prisma' | ctxdb0 memory remember --stdin --json
ctxdb0 memory recall '技术栈选型' --limit 5 --json
ctxdb0 memory browse --offset 0 --limit 20 --json
ctxdb0 memory show <memory-id> --json
printf '%s' '替换后的内容' | ctxdb0 memory revise <memory-id> --stdin --json
ctxdb0 memory forget <memory-id> --confirm-id <memory-id> --json

# 知识库
ctxdb0 knowledge sources --json
ctxdb0 knowledge sources create --name <name> --description '<描述>' --json
ctxdb0 knowledge query '灰度发布要求' --source <source> --json
ctxdb0 knowledge documents --source <source> --json
ctxdb0 knowledge documents show <document-id> --source <source> --json
ctxdb0 knowledge import --source <source> --file ./docs/adr.md --json

# 会话与托管 Skill
ctxdb0 sessions browse --page 0 --limit 20 --json
ctxdb0 sessions restore <session-id> --json
ctxdb0 skills search 'incident response' --json
ctxdb0 skills fetch <skill-id> --json

# 迁移与清理
ctxdb0 migrate --plan --json
ctxdb0 migrate --apply --confirm <confirmation-token> --json
ctxdb0 purge --plan --json
ctxdb0 purge --confirm <confirmation-token> --json

# 卸载
ctxdb0 detach --host <host> --json

6. 配置项

connect 将非敏感配置写入 ~/.ctxdb0/plugin/config.json，API Key 单独写入权限为 0600 的 credentials.json。行为配置默认值：

行为配置通过 CLI 修改：

ctxdb0 config set recall-mode intent --json
ctxdb0 config set session-batch off --json
ctxdb0 config set prompt-knowledge-recall off --json

# 开启 Prompt-KB 召回（指定知识源名称）
ctxdb0 config set prompt-knowledge-recall on --source <name> --json

# 使用当前所有可访问知识源（快照固化到配置）
ctxdb0 config set prompt-knowledge-recall on --all-accessible --json

项目级收紧：在项目根目录放 .ctxdb0.json，只能收紧全局配置（降低召回模式、关闭 session batch、关闭 Prompt-KB 召回），不能选择 profile、endpoint 或放宽行为，也不允许包含任何密钥字段。

准备工作

所有请求携带 X-API-Key 头。先设置环境变量：

export API_KEY="<YOUR_API_KEY>"
export HOST="http://<your-endpoint>"

鉴权支持三种等价头格式：

-H "X-API-Key: $API_KEY"              # 推荐
-H "Authorization: Token $API_KEY"
-H "Authorization: Bearer $API_KEY"

1. 验证连通（whoami）

curl "$HOST/v1/auth/whoami" \
  -H "X-API-Key: $API_KEY"

响应：

{
  "code": 0,
  "msg": "ok",
  "data": {
    "authenticated": true,
    "workspace_id": 1,
    "member_id": 1,
    "key_type": "USER",
    "bound_user_id": "user_001"
  }
}

data.authenticated 为 true 即连通。

2. 写入对话（ingest）

把对话写入会话，服务端异步蒸馏出记忆：

curl -X POST "$HOST/v1/context/ingest" \
  -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{
    "session_id": "sess_789",
    "user_id": "user_001",
    "agent_id": "my-agent",
    "messages": [
      {"role": "user", "content": "我想用 Docker 部署应用"},
      {"role": "assistant", "content": "可以用 Docker Compose 一键起栈"}
    ]
  }'

响应：

{
  "code": 0,
  "data": {
    "session_id": "sess_789",
    "session_internal_id": 1234,
    "message_ids": [{"id": 1001, "seq": 1}, {"id": 1002, "seq": 2}],
    "event_id": 99001
  }
}

3. 装配上下文（assemble）

按 query 召回相关记忆和知识，在 token_budget 预算内精选，输出可直接拼进 system prompt 的 prompt_blocks：

curl -X POST "$HOST/v1/context/assemble" \
  -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{
    "session_id": "sess_789",
    "user_id": "user_001",
    "query": "如何部署应用？",
    "token_budget": 4000,
    "recall": {"top_k": 8}
  }'

响应（节选）：

{
  "code": 0,
  "data": {
    "prompt_blocks": [
      {"role": "system", "tag": "user_profile", "content": "用户偏好 Docker 部署", "tokens": 20, "sources": []}
    ],
    "token_used": 255,
    "token_budget": 4000,
    "trace_id": "550e8400-..."
  }
}

4. 搜索记忆（search）

按语义检索长期记忆（向量 + BM25 融合）：

curl -X POST "$HOST/v2/memories/search" \
  -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{
    "query": "技术栈选型",
    "user_id": "user_001",
    "limit": 10
  }'

响应（裸 JSON 数组）：

[
  {"id": "mem_123", "memory": "项目选用 TypeScript + Prisma", "score": 0.92, "user_id": "user_001"},
  {"id": "mem_124", "memory": "鉴权方案选 NextAuth", "score": 0.85, "user_id": "user_001"}
]