<SYSTEM>This is the full 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 编辑。