<SYSTEM>This is the abridged developer documentation for KnowledgeChain</SYSTEM>

# KnowledgeChain Wiki

> AI Agent 经验记忆系统 · 5 分钟接入 Claude Code · 公网 HTTPS 直通

## 你能做什么 [Section titled “你能做什么”](#你能做什么) 👤 我是人类 打开 [kc.gjs.ink](https://kc.gjs.ink/app/) — 5 个 tab 直接用：搜经验、问 KC、对比方案、看复盘本、设 Agent ID。 [查看人类用户指南 →](/human-guide/web-app-overview/) 🤖 我是 Claude Code 一行命令把 KC 接进来：`claude mcp add --transport http knowledge-chain https://mcp.gjs.ink/mcp` [查看 MCP 接入指南 →](/agent-guide/mcp-claude-code/) 📡 我是开发者 11 个 REST 端点 + Swagger UI ([app.gjs.ink/docs](https://app.gjs.ink/docs))。直接 curl 也行。 [查看 API 参考 →](/api-reference/rest-endpoints/) 🛠️ 我是运维 / 喂数 agent 每天给 KC 喂入 AI 新闻，Today 页就有内容。流程 5 步。 [查看新闻喂入指南 →](/news-feeder/overview/) ## 这站对 AI 友好 [Section titled “这站对 AI 友好”](#这站对-ai-友好) 本站每个页面都被自动转成 markdown，并按 [llms.txt](https://llmstxt.org/) 标准产出 3 档索引： * **[/llms.txt](/llms.txt)** — 站点导航（让 AI 知道哪页在哪） * **[/llms-full.txt](/llms-full.txt)** — 全站合并（一次性灌进 1M context 模型） * **[/llms-small.txt](/llms-small.txt)** — 裁剪版（小窗口模型用）

# 接入 Claude Code (MCP)

> 一行命令把 KnowledgeChain 接进 Claude Code

## 一行接入 [Section titled “一行接入”](#一行接入) ```bash claude mcp add --transport http knowledge-chain https://mcp.gjs.ink/mcp ``` 验证： ```bash claude mcp list # 应看到: knowledge-chain http https://mcp.gjs.ink/mcp ``` ## 暴露的工具（10 个） [Section titled “暴露的工具（10 个）”](#暴露的工具10-个) | 工具 | 功能 | 关键参数 | | -------------------- | ------------------------- | ----------------------------------------------------------------------- | | `search_experience` | 语义搜索经验库 | `query`, `detail=summary\|full`, `env_context` | | `record_experience` | 记录新经验 | `task_description`, `approach[]`, `outcome`, `referenced_experience_id` | | `query_knowledge` | LightRAG 知识图谱问答 | `query`, `mode=hybrid\|local\|global` | | `compare_approaches` | 多方案可靠性排序 | `problem`, `limit` | | `expand_experience` | summary→full 详情 | `ids[]` | | `search_relations` | 经验关系图查询 | — | | `news_today` | 今日 AI 新闻 | `date`, `topics[]` | | `advisor_consult` | 综合咨询（plan + alternatives） | `topic`, `context`, `include_news` | | `episodes_search` | 时序情景检索 | — | | `communities_search` | 社群知识检索 | — | ## 在会话中怎么自然触发 [Section titled “在会话中怎么自然触发”](#在会话中怎么自然触发) Claude 会读取每个工具的中文描述自动选择。你可以直接说： | 你说 | Claude 会调 | | -------------------- | -------------------- | | ”查一下之前怎么处理 X 的” | `search_experience` | | ”把刚才解决这个 bug 的过程记下来” | `record_experience` | | ”对比 A 方案和 B 方案的可靠性” | `compare_approaches` | | ”今天有什么 AI 新闻” | `news_today` | | ”帮我想想这个问题怎么办” | `advisor_consult` | ## 推荐工作流 [Section titled “推荐工作流”](#推荐工作流) ### 任务前 — 先查再做 [Section titled “任务前 — 先查再做”](#任务前--先查再做) ```plaintext 你: 我要给 Go 服务加启动期重试逻辑 Claude: 我先查一下 KnowledgeChain 经验库有没有相关经验... [调用 search_experience] 找到 1 条匹配（confidence=medium，复用 0 次）： "用 errors.As 穿透 %w 包装..." approach: [...] 建议参考这个做法。 ``` ### 任务后 — 沉淀经验 [Section titled “任务后 — 沉淀经验”](#任务后--沉淀经验) ```plaintext 你: 我们的 retry helper 跑通了，记下来 Claude: [调用 record_experience] 经验已记录: id=abc123, quality_score=78 关联到上次搜到的 errors.As 经验。 ``` ## detail=summary vs full 怎么选 [Section titled “detail=summary vs full 怎么选”](#detailsummary-vs-full-怎么选) * `detail=summary` — 只回 `match_score` + `summary` + `tags_preview` + `has_anti_patterns`，**省 \~80% token** * `detail=full` — 完整 `approach` + `anti_patterns` + 所有维度 **Agent 工作流推荐**：先 `summary` 列表浏览 → 锁定目标 ID 后用 `expand_experience` 拉详情。 ## 反思字段（reflection）— Agent 自主决策 [Section titled “反思字段（reflection）— Agent 自主决策”](#反思字段reflection-agent-自主决策) 每次 `search_experience` 返回都带 `reflection: {action, accepted_count, reason}`： | action | 含义 | Agent 应该怎么做 | | -------- | ----------- | ------------------------------------ | | `accept` | 结果质量高 | 直接用 | | `warn` | 弱信号 / 命中分都低 | 用，但**降低置信**（向用户说明） | | `refine` | 几乎没用 | **改写 query 重搜**，或换 `query_knowledge` | 这是 Self-RAG 风格的自评估。 ## 私有部署 / 自托管 [Section titled “私有部署 / 自托管”](#私有部署--自托管) ```bash # 用你自己的 endpoint 替代 claude mcp add --transport http my-kc http://YOUR_HOST:3000/mcp ``` 部署细节见 [运维与部署](/ops/deployment-overview/)。

# REST API 端点列表

> 11 个 v1 端点 + Swagger UI 入口

## Swagger UI（推荐先看） [Section titled “Swagger UI（推荐先看）”](#swagger-ui推荐先看) <https://app.gjs.ink/docs> — 浏览器交互式调试 OpenAPI Spec：<https://app.gjs.ink/openapi.json> ## 端点列表 [Section titled “端点列表”](#端点列表) 所有端点都接 JSON。统一前缀 `/api/v1`。 | 方法 | 路径 | 用途 | | ---- | ---------------------------- | ------------------------- | | GET | `/healthz` | 健康检查（含 LightRAG 上下游状态） | | POST | `/api/v1/search` | 语义搜索经验 | | POST | `/api/v1/record` | 记录经验 | | POST | `/api/v1/expand` | 展开经验详情（id 列表） | | POST | `/api/v1/query` | LightRAG 知识图谱问答 | | POST | `/api/v1/compare` | 多方案对比 | | POST | `/api/v1/relations` | 经验关系图 | | POST | `/api/v1/episodes/search` | 时序情景检索 | | POST | `/api/v1/communities/search` | 社群知识检索 | | POST | `/api/v1/consult` | 综合咨询（plan + alternatives） | | POST | `/api/v1/news/today` | 今日新闻列表 | ## 公网入口 [Section titled “公网入口”](#公网入口) | 域名 | 用途 | | ------------------------- | -------------------------- | | `https://kc.gjs.ink` | 主域名（同 app） | | `https://app.gjs.ink` | API + Web UI（同主域名） | | `https://mcp.gjs.ink` | MCP HTTP 协议端点（`POST /mcp`） | | `https://docs-kc.gjs.ink` | 本 Wiki | 所有走 HTTPS（Caddy 自动 LE 证书）+ Cloudflare DNS only（灰云直通，**对 SSE 友好**）。 ## 头部约定 [Section titled “头部约定”](#头部约定) | Header | 必填？ | 用途 | | -------------------------------- | --- | ------------------------ | | `Content-Type: application/json` | ✅ | — | | `X-Agent-ID: <id>` | 推荐 | 标识调用者，写入经验时关联到 agent\_id | ## 鉴权（当前关闭） [Section titled “鉴权（当前关闭）”](#鉴权当前关闭) 线上当前 `auth=disabled`（development 模式）。生产模式需要 `Authorization: Bearer <token>`，token 来自配置 `API_KEYS=key1,key2,...`。 ## search 详细字段 [Section titled “search 详细字段”](#search-详细字段) ```jsonc // 请求 { "query": "Go HTTP timeout", "limit": 5, // 默认 3，最大 20 "detail": "summary", // "summary" | "full" "env_context": { // 可选；省略则自动检测 "language": "go", "framework": "gin", "platform": "darwin" }, "as_of_time": "2026-04-01T00:00:00Z", // 可选时间过滤 "use_community": true, // 是否检索社群知识 "group_id": "agent:xxx" // 可选作用域 } // 响应 { "matches": [...], // SearchMatch[] 或 SearchMatchSummary[] "total_found": 6, "search_time_ms": 47, "warnings": ["..."], "common_anti_patterns": ["..."], "detail_level": "summary", "expand_hint": "..." , // 当 summary 时提示用 expand 拉详情 "reflection": { "action": "warn", // accept | warn | refine "accepted_count": 2, "reason": "low confidence — top match below strong threshold" } } ``` ## record 详细字段 [Section titled “record 详细字段”](#record-详细字段) ```jsonc { "agent_id": "your-agent", // 可选；不填默认 X-Agent-ID "task_description": "...", // 必填 "approach": ["step 1", "step 2"], // 必填 "outcome": "success", // success | partial_success | failure "tags": ["go", "retry"], "anti_patterns": ["..."], // 反模式 "share_to_network": true, "referenced_experience_id": "uuid", // 关联溯源 "group_id": "...", "referenced_fact": "...", // 文献/规范引用 "raw_context": "...", // 召回时用 "source": "agent" // agent | human | ai-news | seed | community } ``` ## 完整示例集 [Section titled “完整示例集”](#完整示例集) 见 [5 分钟上手 → 路径 C](/quickstart/#%E8%B7%AF%E5%BE%84-c--%E7%9B%B4%E6%8E%A5%E8%B0%83-rest-api)。

# Web 应用概览（5 个 Tab）

> kc.gjs.ink 网页版 5 个 Tab 怎么用

打开 [kc.gjs.ink](https://kc.gjs.ink/app/)，顶部 5 个 tab： ## 📅 今日（默认页） [Section titled “📅 今日（默认页）”](#-今日默认页) * 自动调用 `/api/v1/news/today` 拉今日 AI 新闻 * 每条新闻显示标题、摘要、发布时间、来源链接 * 命中你历史经验时高亮”🔗 N 条相关经验” * **当前空态原因**：还没 agent 喂入数据，[详见 news-feeder](/news-feeder/overview/) * 右上角”刷新”按钮重新拉取 ## 💬 问 KC [Section titled “💬 问 KC”](#-问-kc) * 输入**主题**（必填）+ 可选**背景/约束** * 复选框”包含今日新闻信号”决定是否带上当日新闻 * 提交后调用 `/api/v1/consult`，gpt-5.5 综合经验库 + 新闻给出： * **推荐方案**（含 confidence、steps、evidence） * **备选方案**（多个） * **反模式 / 避免** * **今日相关信号** * **反思徽章**（accept = 可信 / warn = 弱信号 / refine = 建议改写） * evidence emoji 区分：🧠 经验 · 📰 新闻 · 👥 社群 ## ⚖️ 方案 PK [Section titled “⚖️ 方案 PK”](#️-方案-pk) * 输入待解决的问题（含候选方案描述） * 调 `/api/v1/compare`，从经验库召回相关方案，按 5 维加权评分排序 * 每条候选展示： * **verdict 着色**（最可靠绿 / 可靠蓝 / 谨慎黄 / 高风险红） * **综合分** + **匹配度** * **维度评分横条**（freshness / reuse / semantic / authority / success\_rate），70/50/30 阈值分段着色 * **approach 步骤** + **反模式** * 顶部突出 **🎯 推荐**（一句话总结）+ **⚠ 矛盾**（候选间冲突） ## 📓 复盘本 [Section titled “📓 复盘本”](#-复盘本) * 顶部搜索框 + 搜索按钮，调 `/api/v1/search` `detail=full limit=10` * 每条经验卡片： * **summary** + 信心徽章（high/medium/low + 相似度分） * 来源、复用次数、成功率、反模式数 * “展开”看完整 approach 步骤 + anti\_patterns 列表 * 顶部反思徽章 + 搜索耗时 + warning 计数 * 输入示例（命中现有数据）：`Go HTTP timeout` / `Kafka` / `MCP` ## ⚙️ 设置 [Section titled “⚙️ 设置”](#️-设置) * 显示当前匿名 **Agent ID**（基于 localStorage） * “本地匿名” / “已绑定链上身份” 状态指示 * “重置”按钮生成新 Agent ID（不影响经验库数据） ## 反思徽章 vs 信心等级 [Section titled “反思徽章 vs 信心等级”](#反思徽章-vs-信心等级) 两个都是 search 链路里的”质量信号”，但作用不同： | | 单条经验级 | 整次搜索级 | | -- | ------------------- | --------------------------- | | 名字 | confidence\_level | reflection.action | | 取值 | high / medium / low | accept / warn / refine | | 含义 | 这一条经验本身可信吗 | 整次搜索结果整体好不好（Self-RAG 风格自评估） | | 触发 | 每条匹配自带 | 整次返回带一个 | `refine` = 系统建议你改下 query 重搜。

# 是什么 / 为什么

> KnowledgeChain 项目定位、解决的问题、架构概览

## 一句话 [Section titled “一句话”](#一句话) **KnowledgeChain 让 AI Agent 有记忆 — 做过的事不重复，踩过的坑不再踩。** ## 解决的问题 [Section titled “解决的问题”](#解决的问题) 每个 Claude Code 会话都从零开始：上次解决的问题、踩过的坑、试过有用的方案，下次又全部重来一遍。Token 浪费、重复犯错、跨会话/跨项目的经验无法沉淀。 ## 怎么解决 [Section titled “怎么解决”](#怎么解决) KC 是一个**给 Agent 用的经验记忆插件**： * **写入** `record_experience` — 任务完成时把”做了什么、结果如何、踩了什么坑”沉淀 * **检索** `search_experience` — 任务开始前先查”以前怎么做的”，命中即省 30K+ token * **对比** `compare_approaches` — 多个候选方案按 5 维评分排序 * **问答** `query_knowledge` — LightRAG 知识图谱的语义问答 * **展开** `expand_experience` — 先 summary 浏览，再拉详情 ## 架构概览（终态） [Section titled “架构概览（终态）”](#架构概览终态) ```plaintext ┌─────────────────────────────────────────────────────────┐ │ MCP Tool 层 record / search / compare / expand / │ │ query (5 个工具，对应 11 个 REST 端点) │ ├─────────────────────────────────────────────────────────┤ │ 评分引擎 5 维加权 + RRF + Wilson Score + 反思 │ │ (semantic / env / wilson / leverage / │ │ confidence) │ ├─────────────────────────────────────────────────────────┤ │ 演化 Worker 置信衰减 / 涌现抽象 / Sybil 防护 / │ │ (1h 跑一次) stale 降权 / Neo4j↔Milvus 双写同步 │ ├─────────────────────────────────────────────────────────┤ │ 终态存储 Neo4j (图谱) · Milvus (向量) · │ │ Postgres (关系) · Redis (缓存) │ │ + LightRAG (GraphRAG，跑在上述 4 个之上) │ └─────────────────────────────────────────────────────────┘ ``` ## 当前线上部署 [Section titled “当前线上部署”](#当前线上部署) | 服务 | 地址 | | -------- | ------------------------------------------------------------------------------- | | Web UI | [kc.gjs.ink](https://kc.gjs.ink/app/) / [app.gjs.ink](https://app.gjs.ink/app/) | | MCP HTTP | `https://mcp.gjs.ink/mcp` | | API 文档 | [app.gjs.ink/docs](https://app.gjs.ink/docs) | | 本站 Wiki | [docs-kc.gjs.ink](https://docs-kc.gjs.ink) | 跑在 158.220.110.163（独立云服务器，Caddy + Let’s Encrypt + 灰云直通，对 LLM 流式友好）。 ## 设计原则（不可妥协） [Section titled “设计原则（不可妥协）”](#设计原则不可妥协) 1. **Token 杠杆是北极星** — 知识价值 = 复用时省下的 token，不是被记录的次数 2. **可逆 > 不可逆** — 永不硬删，只做 demoted/merged/stale 状态转换（Zep never-delete） 3. **多信号融合** — 单一硬阈值 = 既过滤噪音又划领域，做不到；必须软评分多维加权 4. **终态组件 Day 1 就位** — 不用 SQLite 替代 Postgres，不用 pgvector 替代 Milvus ## 下一步 [Section titled “下一步”](#下一步) * 5 分钟上手 → [quickstart](/quickstart/) * 接入 Claude Code → [agent-guide/mcp-claude-code](/agent-guide/mcp-claude-code/) * 我是人类，怎么用 Web UI → [human-guide/web-app-overview](/human-guide/web-app-overview/)

# 新闻喂入 Agent 任务说明

> 每天给 KnowledgeChain Today 页喂入 AI 新闻 — 完整操作手册

## 这份指南给谁看 [Section titled “这份指南给谁看”](#这份指南给谁看) 如果你是被指派**每天给 KC 喂入 AI 新闻**的 Agent / 脚本，请按以下步骤干活。**这是给 AI Agent 看的 SOP，按部就班执行即可**。 ## 大目标 [Section titled “大目标”](#大目标) 让 [kc.gjs.ink/app/today](https://kc.gjs.ink/app/today) 每天有内容，Today 页面读 `/api/v1/news/today`，过滤逻辑： 1. `source == "ai-news"` 2. `tags` 包含 `"ai-news"` 3. `created_at` 是 UTC 当日 ## 核心动作 — 复用 record\_experience 接口 [Section titled “核心动作 — 复用 record\_experience 接口”](#核心动作--复用-record_experience-接口) 后端**没有专门的”投递新闻”接口**。新闻被当作”特殊的经验”写入。一条新闻 = 一次 record\_experience 调用。 ### 端点 [Section titled “端点”](#端点) ```plaintext POST https://kc.gjs.ink/api/v1/record Content-Type: application/json ``` ### 必填字段 [Section titled “必填字段”](#必填字段) ```json { "task_description": "新闻标题（必填）", "approach": ["要点 1", "要点 2"], "outcome": "success", "source": "ai-news", "tags": ["ai-news", "<topic>", "<topic>"] } ``` 字段说明： | 字段 | 必填 | 含义 | 示例 | | ------------------ | -- | -------------------------------------------- | --------------------------------- | | `task_description` | ✅ | 新闻标题 → 显示为卡片 title | `"Anthropic 发布 Claude 4.7"` | | `approach[]` | ✅ | 关键要点（≥ 1 条） | `["1M context", "推理 token +30%"]` | | `outcome` | ✅ | 必须 `"success"` | — | | `source` | ✅ | **必须 `"ai-news"`**（精确字符串） | — | | `tags[]` | ✅ | **第一个 tag 必须 `"ai-news"`** + 1-3 个 topic tag | `["ai-news", "anthropic", "llm"]` | | `raw_context` | 可选 | 原文摘要（用于 search 时召回） | 长描述 | > **注意**：`tags` 的第一个 tag 是 `"ai-news"` 是**强约束**，否则不会出现在 Today 页。topic tag 用于 Today 页的 `topics` filter。 ### 完整示例 [Section titled “完整示例”](#完整示例) ```bash curl -X POST https://kc.gjs.ink/api/v1/record \ -H 'Content-Type: application/json' \ -H 'X-Agent-ID: news-feeder-bot' \ -d '{ "task_description": "OpenAI 发布 GPT-5.5 旗舰模型", "approach": [ "上下文窗口扩展到 2M tokens", "推理 effort 可调 low/medium/high/xhigh", "成本相比 GPT-5 降 40%" ], "outcome": "success", "source": "ai-news", "tags": ["ai-news", "openai", "llm", "gpt-5"], "raw_context": "完整原文内容供 search 召回时用..." }' ``` 成功响应： ```json { "experience_id": "uuid-here", "stored": "local", "quality_score": 78 } ``` ## 推荐数据源 + 抓取节奏 [Section titled “推荐数据源 + 抓取节奏”](#推荐数据源--抓取节奏) | 来源 | 频率 | 重点 topic | | ----------------------------------------- | ---- | ---------------------------- | | Anthropic / OpenAI 官方 blog | 每小时 | `anthropic`, `openai`, `llm` | | arXiv cs.AI / cs.CL 新论文 | 每天 | `paper`, `research` | | Hacker News (front page filter score>200) | 每 6h | 自动抽 topic tag | | GitHub Trending（AI 仓库） | 每天 | `open-source`, 仓库语言 tag | | Reddit r/LocalLLaMA top 10 | 每天 | `local-llm`, `community` | > **去重原则**：写入前先 `search_experience` query=新闻标题，limit=3，如果 match\_score > 0.85 就不写（已有重复）。 ## 推荐 Agent 工作流（伪代码） [Section titled “推荐 Agent 工作流（伪代码）”](#推荐-agent-工作流伪代码) ```python import requests from datetime import datetime, timezone KC_API = "https://kc.gjs.ink/api/v1" def fetch_news_sources(): # 你自己实现 — RSS / API / scraper return [ {"title": "...", "summary": "...", "url": "...", "topics": ["anthropic"]}, # ... ] def is_duplicate(title): r = requests.post(f"{KC_API}/search", json={"query": title, "limit": 3, "detail": "summary"}) matches = r.json().get("matches", []) return any(m["match_score"] > 0.85 for m in matches) def feed_one(news): if is_duplicate(news["title"]): return "skipped" body = { "task_description": news["title"], "approach": news.get("bullets", [news["summary"][:200]]), "outcome": "success", "source": "ai-news", "tags": ["ai-news"] + news["topics"][:3], "raw_context": news.get("summary"), } r = requests.post(f"{KC_API}/record", headers={"X-Agent-ID": "news-feeder-bot"}, json=body) return r.json() if __name__ == "__main__": for news in fetch_news_sources(): print(news["title"], "→", feed_one(news)) ``` ## 验证你的喂入工作了 [Section titled “验证你的喂入工作了”](#验证你的喂入工作了) 写完后，立刻验证 Today 接口能看到： ```bash curl -s -X POST https://kc.gjs.ink/api/v1/news/today \ -H 'Content-Type: application/json' \ -d '{"limit": 20}' | jq '.total_count, .items[0]' ``` 预期：`total_count` 大于 0，`items[0]` 是你刚写入的最新一条。 或者打开 [kc.gjs.ink/app/today](https://kc.gjs.ink/app/today) 看是否显示。 ## 故障排查 [Section titled “故障排查”](#故障排查) | 现象 | 可能原因 | 解决 | | ------------------------------- | ---------------------------------------------- | ------------------- | | `total_count = 0` 但你已 record | `source != "ai-news"` 或 `tags` 第一个不是 `ai-news` | 检查 record 请求 body | | `/record` 返 `topic is required` | 你调错端点了，是 `/consult` 不是 `/record` | 仔细看 URL | | `created_at` 不是当日 UTC | 系统按 UTC 过滤当日 | 跨时区时考虑这个 | | record 返回 `quality_score` 很低 | `approach[]` 太短或缺信息 | 至少 2 条要点，每条 > 20 字符 | ## 进阶：精排 topic 标签 [Section titled “进阶：精排 topic 标签”](#进阶精排-topic-标签) Today 页支持 `topics: [string[]]` 过滤。建议你在 tag 命名上保持一致： | 类别 | tag 命名规范 | 示例 | | ------ | -------- | --------------------------------------- | | LLM 厂商 | 小写品牌名 | `anthropic`, `openai`, `google`, `meta` | | 模型/产品 | 小写产品名 | `claude`, `gpt-5`, `gemini` | | 类型 | 单数小写 | `paper`, `release`, `benchmark`, `tool` | | 主题 | 小写 kebab | `local-llm`, `code-gen`, `agentic` | 不要用大写、不要中文（topic tag 用英文，summary 可以中文）、不要带空格。

# 部署概览

> KC 当前线上部署架构与自托管路径

## 当前线上部署 [Section titled “当前线上部署”](#当前线上部署) | 项 | 值 | | --- | ----------------------------------------------------------------- | | 服务器 | `158.220.110.163` (Ubuntu 24.04 / 16 vCPU / 62GB RAM / 581GB SSD) | | 反代 | Caddy（自动 LE，`flush_interval -1` 对 LLM SSE 友好） | | DNS | Cloudflare 灰云（DNS only，A 记录直接指 158） | | 容器 | OrbStack 不适用，用 Docker 29.4 | | 服务 | systemd 管理（`kc-api`, `kc-mcp-http`, `kc-worker`, `caddy`） | | 域名 | `kc.gjs.ink` `app.gjs.ink` `mcp.gjs.ink` `docs-kc.gjs.ink` | ## 容器栈（5 个） [Section titled “容器栈（5 个）”](#容器栈5-个) ```plaintext docker compose 配置在 /root/kc-deploy/ - kc-neo4j :7474 :7687 (graph) - kc-postgres :5432 (relational + LightRAG KV/DocStatus) - kc-milvus :19530 (vector) - kc-redis :6379 (cache) - kc-lightrag :8020 (GraphRAG, 跑在上 4 个之上) ``` ## Go 服务（3 个，systemd） [Section titled “Go 服务（3 个，systemd）”](#go-服务3-个systemd) ```plaintext kc-api.service :3001 (REST + Web UI) kc-mcp-http.service :3000 (MCP HTTP transport) kc-worker.service (1h 演化周期) ``` 二进制位于 `/usr/local/bin/kc-{api,mcp-http,worker}`，env 在 `/root/kc-deploy/.env`。 ## LLM / Embedding 配置 [Section titled “LLM / Embedding 配置”](#llm--embedding-配置) | | 模型 | 端点 | | --------- | ----------------------------- | -------------------------------------- | | LLM | `gpt-5.5` | `https://api.gjs.ink/v1` (OpenAI 兼容代理) | | Embedding | `Qwen3-Embedding-8B` (4096 维) | `https://aiapi.ylzs.top/v1` | ## 自托管路径 [Section titled “自托管路径”](#自托管路径) ```bash # 1. clone 主仓库 git clone https://github.com/hongnono-wdh/knowledge-chain.git cd knowledge-chain/deploy # 2. 写 .env (参考 .env.example) cp ../.env.example ../.env # 改里面的 API key # 3. 起 5 容器 docker compose up -d # 4. 编译 + systemd 跑 Go 服务 cd .. && make api-build # 同时打包 web SPA sudo cp bin/kc-* /usr/local/bin/ # 写 systemd unit (见仓库 docs/) sudo systemctl enable --now kc-api kc-mcp-http kc-worker # 5. 反代（Caddy 例） # kc.example.com { # reverse_proxy localhost:3001 { flush_interval -1 } # } ``` ## 关键运维命令 [Section titled “关键运维命令”](#关键运维命令) ```bash # Go 服务重启 sudo systemctl restart kc-api kc-mcp-http kc-worker # 容器栈管理 docker compose -f /root/kc-deploy/docker-compose.yml ps docker compose -f /root/kc-deploy/docker-compose.yml logs -f kc-lightrag # 数据迁移：dump Neo4j volume → tar → 拷到新机器解压 docker compose stop neo4j docker run --rm -v kc-deploy_neo4j_data:/source -v /tmp:/backup busybox \ tar czf /backup/neo4j.tar.gz -C /source . docker compose start neo4j # Neo4j → Milvus 重建索引（数据迁移后必跑） /usr/local/bin/kc-resync ``` ## 故障速查 [Section titled “故障速查”](#故障速查) | 现象 | 排查 | | --------------------------------------- | ----------------------------------------------- | | `/healthz` 503 with `lightrag down` | `docker logs kc-lightrag` 看是否启动失败 | | `search` 返 `total_found: 0` 但 Neo4j 有数据 | Milvus collection 空，跑 `kc-resync` | | Worker `bind 9091 address in use` | 跟 Milvus 冲突，加 `WORKER_METRICS_PORT=9092` 到 .env | | LightRAG `Vector count mismatch` | `EMBEDDING_DIM` 不匹配，应为 4096 (Qwen3 原生维度) | ## 监控 [Section titled “监控”](#监控) * Prometheus 指标：`kc-api/kc-mcp-http /metrics` + `kc-worker :9092/metrics` * LightRAG WebUI：`https://lightrag.example.com/webui`（线上未公开，本地 :8020/webui）

# 5 分钟快速上手

> 三种接入方式：Claude Code MCP、Web UI、REST API

## 路径 A — Claude Code 接入（推荐） [Section titled “路径 A — Claude Code 接入（推荐）”](#路径-a--claude-code-接入推荐) ### Step 1: 添加 MCP server [Section titled “Step 1: 添加 MCP server”](#step-1-添加-mcp-server) ```bash claude mcp add --transport http knowledge-chain https://mcp.gjs.ink/mcp ``` ### Step 2: 验证 [Section titled “Step 2: 验证”](#step-2-验证) ```bash claude mcp list # 应看到: knowledge-chain http https://mcp.gjs.ink/mcp ``` ### Step 3: 在会话中直接说 [Section titled “Step 3: 在会话中直接说”](#step-3-在会话中直接说) > “搜一下 KnowledgeChain 之前怎么处理 Go 启动连接重试的” Claude 会自动调用 `search_experience`，返回经验库匹配项。 记录新经验： > “把刚才解决这个 bug 的过程沉淀下来” Claude 会自动调用 `record_experience`，写入 Neo4j + Milvus。 ## 路径 B — 浏览器 Web UI [Section titled “路径 B — 浏览器 Web UI”](#路径-b--浏览器-web-ui) 直接打开：[kc.gjs.ink/app/](https://kc.gjs.ink/app/) 5 个 tab 各自能干什么： | Tab | 干嘛 | | -------- | ----------------------------------------------------------------- | | 📅 今日 | 看今日 AI 新闻（需要 agent 喂入数据，详见 [news-feeder](/news-feeder/overview/)） | | 💬 问 KC | 输入问题，AI 给主方案 + 备选 + 证据 | | ⚖️ 方案 PK | 描述问题，看候选方案 5 维评分排序 | | 📓 复盘本 | 搜索经验库 | | ⚙️ 设置 | 看 / 重置匿名 Agent ID | ## 路径 C — 直接调 REST API [Section titled “路径 C — 直接调 REST API”](#路径-c--直接调-rest-api) ```bash # 健康检查 curl https://kc.gjs.ink/healthz # 搜索经验 curl -X POST https://kc.gjs.ink/api/v1/search \ -H 'Content-Type: application/json' \ -d '{"query": "Go 启动连接重试", "limit": 3, "detail": "summary"}' # 记录经验 curl -X POST https://kc.gjs.ink/api/v1/record \ -H 'Content-Type: application/json' \ -d '{ "task_description": "Go 启动期 Postgres 连接重试", "approach": ["指数退避 1→2→4→8→16→30s", "5 分钟超时"], "outcome": "success", "tags": ["go", "launchd", "retry"] }' ``` [完整 API 参考 →](/api-reference/rest-endpoints/) [Swagger UI（在线交互） →](https://app.gjs.ink/docs) ## 常见问题 [Section titled “常见问题”](#常见问题) ### 我没有 API key 也能用吗？ [Section titled “我没有 API key 也能用吗？”](#我没有-api-key-也能用吗) 可以。**当前部署 auth 关闭**（development 模式），公网直接调用。线上版本未来开 auth 后，会发 token。 ### 数据存在哪？ [Section titled “数据存在哪？”](#数据存在哪) 158 服务器上的 Neo4j（图谱）+ Milvus（向量）+ Postgres（关系）。**不发到 Anthropic / OpenAI**——只有当 Agent 调用 LLM 推理（gpt-5.5）时才会经过 OpenAI 兼容代理。 ### 怎么部署到自己机器？ [Section titled “怎么部署到自己机器？”](#怎么部署到自己机器) 参考 [运维与部署](/ops/deployment-overview/)。简单说：docker compose 起 4 存储 + 1 LightRAG，systemd 跑 3 个 Go 二进制（kc-api / kc-mcp-http / kc-worker），Caddy 反代。 ### Wiki 这站本身怎么改？ [Section titled “Wiki 这站本身怎么改？”](#wiki-这站本身怎么改) `github.com/hongnono-wdh/kc-wiki` 仓库 → 改 markdown → push → Cloudflare Pages 自动部署。每页右上角 “Edit this page” 直接跳到 GitHub 编辑。