// Persistent, incremental LLM Wiki — accumulate structured knowledge across multiple ingest/query sessions. Supports init, ingest (local files, URLs, sessions), query, lint, export, and status operations with [[wiki links]] cross-references.
| name | teamai-wiki |
| description | Persistent, incremental LLM Wiki — accumulate structured knowledge across multiple ingest/query sessions. Supports init, ingest (local files, URLs, sessions), query, lint, export, and status operations with [[wiki links]] cross-references. |
持续积累的多页面 Wiki 知识库。通过增量摄入（ingest）、查询（query）、健康检查（lint）不断积累知识，页面间用 [[wiki links]] 互相引用，可直接在 Obsidian 中浏览。
团队共享知识库：wiki 存储在 team repo 的 wiki/ 目录中，通过 teamai pull/push 与团队同步。不仅支持代码，也支持文档、会议纪要、设计决策、团队信息、流程规范等任何知识源。
替代 /teamai-share-learnings：/teamai-wiki ingest --from-session 是 /teamai-share-learnings 的严格超集 — 结构化、增量、可查询。
/teamai-wiki init [dir] # 初始化 wiki 目录结构（dir 可选，可以是代码库、文档目录或空目录）
/teamai-wiki ingest <source> # 摄入源文件/目录，更新 wiki 页面
/teamai-wiki ingest <source> --batch # 批量摄入，少交互
/teamai-wiki ingest <url> # 从 URL 摄入知识（网页、GitHub 仓库等）
/teamai-wiki ingest --from-session # 从当前 Claude 会话中提取知识写入 wiki
/teamai-wiki query "<question>" # 查询 wiki，综合回答
/teamai-wiki query "<question>" --save # 查询并将回答存入 wiki
/teamai-wiki lint # 健康检查：矛盾、孤立页、缺失引用
/teamai-wiki status # 当前 wiki 统计（页面数、链接数、最近活动）
/teamai-wiki export [--format md|html] # 导出 wiki 为单文件 Markdown 或 HTML
实现 Karpathy LLM Wiki 模式的完整版本：
[[wiki links]] 在页面间建立联系，自动维护 Backlinkswiki/ <- 存储在 team repo 中，通过 teamai pull/push 同步
├── _schema.md <- wiki 约定和配置（每次操作前读取）
├── index.md <- 所有页面目录索引（按分类组织，含一行摘要）
├── log.md <- 追加式操作日志
├── overview.md <- 全局综合概述页
├── _metadata.json <- 机器可读元数据（本地生成，不推送到 team repo）
│
├── entities/ <- 实体页（专有名词：具体的模块、服务、产品、项目）
├── concepts/ <- 概念页（通用名词：设计模式、架构原则、技术概念）
├── comparisons/ <- 对比页（两个或多个事物的对比分析）
├── people/ <- 人员页（团队成员、专长、职责）
├── decisions/ <- 决策页（架构决策记录 ADR、技术选型、变更原因）
├── processes/ <- 流程页（工作流、SOP、部署流程、on-call 流程）
├── sources/ <- 源文件摘要页（每个被摄入的源对应一个）
└── queries/ <- 有价值的查询结果（--save 存入）
| 分类 | 目录 | 适用内容 | 示例 |
|---|---|---|---|
| entity | entities/ | 专有名词：具体的模块、服务、产品、项目、工具 | hai-api-server, sglang-engine, pytorch |
| concept | concepts/ | 通用名词：设计模式、架构原则、技术概念 | rollback-workflow, retry-backoff, pub-sub |
| comparison | comparisons/ | 两个或多个事物的对比分析 | sglang-vs-vllm, redis-vs-memcached |
| person | people/ | 团队成员、专长领域、负责模块 | jeff-xu, alice-chen |
| decision | decisions/ | 架构决策、技术选型、变更记录 | use-redis-for-cache, migrate-to-k8s |
| process | processes/ | 工作流、SOP、部署/on-call/发布流程 | deploy-to-prod, incident-response |
| source | sources/ | 源文件的结构化摘要 | hai-api-server-py, design-doc-auth |
| query | queries/ | 有价值的查询结果 | sync-vs-async-comparison |
分类选择由 LLM 智能判断：ingest 时不需要手动指定分类。Agent 分析内容后自动决定应归入哪个目录。一份会议纪要可能同时产生 decisions/ 和 people/ 页面。
每个 wiki 页面遵循统一格式：
---
title: Message Builder
category: entity
tags: [hai-flow, core, message-queue]
sources: [hai_flow/hai_flow/core/message.py]
created: 2026-04-08
updated: 2026-04-08
---
# Message Builder
[正文内容...]
## Related
- [[hai-flow-engine]] — 所属系统
- [[rollback-workflow]] — 使用 MessageBuilder 实现回滚
## Backlinks
_Pages that link here:_
- [[overview]]
- [[hai-flow-engine]]
comparisons/ 页面模板：
---
title: SGLang vs vLLM
category: comparison
tags: [inference, serving, gpu]
sources: []
created: 2026-04-08
updated: 2026-04-08
---
# SGLang vs vLLM
## 对比维度
| 维度 | SGLang | vLLM |
|------|--------|------|
| 吞吐 | ... | ... |
| 延迟 | ... | ... |
| 易用性 | ... | ... |
## 结论
[什么场景选什么]
## Related
- [[sglang-engine]]
- [[vllm]]
## Backlinks
people/ 页面额外字段：
---
title: Jeff Xu
category: person
tags: [backend, hai, gpu-infra]
sources: []
created: 2026-04-08
updated: 2026-04-08
---
# Jeff Xu
## 专长领域
- GPU 推理服务架构
- Kubernetes 集群管理
## 负责模块
- [[hai-api-server]]
- [[sglang-engine]]
## Related
- [[alice-chen]] — 协作：前端开发
## Backlinks
decisions/ 页面额外字段：
---
title: 选择 Redis 作为缓存层
category: decision
tags: [architecture, cache, redis]
sources: [docs/adr/001-redis-cache.md]
status: accepted
date: 2026-03-15
created: 2026-04-08
updated: 2026-04-08
---
# 选择 Redis 作为缓存层
## 背景
[为什么需要这个决策]
## 决策
[最终选择了什么]
## 原因
[为什么选这个方案]
## 备选方案
- 方案 A: ...
- 方案 B: ...
## 影响
[这个决策带来的影响]
## Related
## Backlinks
processes/ 页面额外字段：
---
title: 生产环境部署流程
category: process
tags: [deploy, production, k8s]
sources: [docs/runbooks/deploy.md]
created: 2026-04-08
updated: 2026-04-08
---
# 生产环境部署流程
## 前置条件
- [ ] 所有 CI 测试通过
- [ ] Code review 已完成
## 步骤
1. ...
2. ...
## 回滚方案
...
## Related
## Backlinks
When invoked, first determine the subcommand (init/ingest/query/lint/status/export), then follow the corresponding steps. Do not skip steps.
init [dir]WIKI_DIR: 根据当前项目的 teamai scope 决定：
<projectRoot>/.teamai/config.yaml 中的 scope 字段<projectRoot>/.teamai/wiki/~/.teamai/wiki/SOURCE_DIR: 可选的 dir 参数如果 WIKI_DIR 已经存在且包含 _metadata.json，提示用户已经初始化过，询问是否要重新初始化。
mkdir -p WIKI_DIR/{entities,concepts,comparisons,people,decisions,processes,sources,queries}
写入 wiki 约定文档：
# Wiki Schema
本 wiki 由 `/teamai-wiki` skill 自动维护。
## 页面分类
| 分类 | 目录 | 说明 | 示例 |
|------|------|------|------|
| entity | entities/ | 专有名词：具体的模块、服务、产品、项目 | hai-api-server, message-builder |
| concept | concepts/ | 通用名词：设计模式、架构原则、技术概念 | rollback-workflow, deny-actions |
| comparison | comparisons/ | 两个或多个事物的对比分析 | sglang-vs-vllm, redis-vs-memcached |
| person | people/ | 团队成员、专长领域、负责模块 | jeff-xu, alice-chen |
| decision | decisions/ | 架构决策记录、技术选型、变更原因 | use-redis-for-cache |
| process | processes/ | 工作流、SOP、部署/发布/on-call 流程 | deploy-to-prod |
| source | sources/ | 源文件/文档的结构化摘要 | hai-api-server-py |
| query | queries/ | 有价值的查询结果 | sync-vs-async |
## 命名规则
- 文件名使用 kebab-case：`message-builder.md`
- 标题使用人类可读的格式：`Message Builder`
- Wiki 链接使用文件名（不含 .md）：`[[message-builder]]`
## 链接格式
- 内部引用：`[[page-name]]` — 仅使用文件名，不含目录前缀
- 带描述：`[[page-name]] — 简要说明`
- 跨分类引用同样有效，链接是全局唯一的
## 页面模板
每个页面必须包含：
1. YAML frontmatter（title, category, tags, sources, created, updated）
2. 正文内容
3. Related 段落（出链）
4. Backlinks 段落（入链，由系统自动维护）
写入空的 index.md：
# Wiki Index
> Auto-maintained by /teamai-wiki. Last updated: YYYY-MM-DD
## Entities
_No pages yet._
## Concepts
_No pages yet._
## Comparisons
_No pages yet._
## People
_No pages yet._
## Decisions
_No pages yet._
## Processes
_No pages yet._
## Sources
_No pages yet._
## Queries
_No pages yet._
写入空的 log.md：
# Wiki Log
| Time | Operation | Details |
|------|-----------|---------|
| YYYY-MM-DD HH:MM | init | Wiki initialized |
写入 overview.md：
---
title: Overview
category: entity
tags: [overview, index]
sources: []
created: YYYY-MM-DD
updated: YYYY-MM-DD
---
# Overview
_This page will be populated after the first ingest._
## Related
## Backlinks
写入 _metadata.json：
{
"version": 1,
"wikiDir": "<absolute-path>",
"sourceDir": null,
"createdAt": "<ISO-timestamp>",
"updatedAt": "<ISO-timestamp>",
"sources": {},
"pages": {
"overview.md": {
"title": "Overview",
"category": "entity",
"tags": ["overview", "index"],
"outLinks": [],
"inLinks": [],
"updatedAt": "<ISO-timestamp>"
}
},
"stats": {
"totalPages": 1,
"totalSources": 0,
"totalLinks": 0,
"lastIngest": null,
"lastLint": null
}
}
如果用户提供了 dir 参数：
检测目录类型：
.py, .ts, .go, .rs, .java 等）→ 代码项目代码项目：自动触发 ingest 流程
文档目录：自动触发 ingest 流程（Agent 会智能提取 decisions、processes 等）
空目录/不存在：只完成 init，提示用户后续使用 ingest 添加内容
如果没有提供 dir 参数：只完成 init，不触发 ingest。
输出：
Wiki initialized at WIKI_DIR
Directories: entities/, concepts/, comparisons/, people/, decisions/, processes/, sources/, queries/
Files: _schema.md, index.md, log.md, overview.md, _metadata.json
如果触发了 ingest：
Auto-ingesting from: SOURCE_DIR (detected: code project / document directory)
ingest <source>这是核心操作。单次 ingest 可能创建或更新 10-15 个 wiki 页面。
<source> 支持三种形式：
/path/to/dir 或 ./file.md）https://...）--from-session：从当前 Claude 会话上下文提取读取以下文件（使用 Read 工具）：
_schema.md — 了解 wiki 约定index.md — 了解已有页面_metadata.json — 已摄入文件的哈希如果 _metadata.json 不存在，提示用户先运行 /teamai-wiki init。
如果 _metadata.json 解析失败（JSON 损坏），输出警告并尝试从 wiki 目录重建元数据。
如果 source 是本地路径：
扫描文件，排除噪音和敏感文件：
find SOURCE_PATH -type f \
-not -path '*/node_modules/*' \
-not -path '*/.git/*' \
-not -path '*/dist/*' \
-not -path '*/build/*' \
-not -path '*/__pycache__/*' \
-not -path '*/.next/*' \
-not -path '*/vendor/*' \
-not -path '*/.venv/*' \
-not -path '*/venv/*' \
-not -path '*/.tox/*' \
-not -path '*/.mypy_cache/*' \
-not -path '*/.pytest_cache/*' \
-not -path '*/target/*' \
-not -path '*/.cache/*' \
-not -name '*.pyc' \
-not -name '*.pyo' \
-not -name '.DS_Store' \
-not -name '*.lock' \
-not -name 'package-lock.json' \
-not -name '.env' \
-not -name '.env.*' \
-not -name '*.pem' \
-not -name '*.key' \
-not -name '*.p12' \
-not -name 'credentials.json' \
-not -name '*.secret' \
-not -name 'id_rsa*' \
-not -name '*.pfx' \
| head -2000 \
| sort
对每个文件计算 SHA256 哈希：
sha256sum FILE_PATH
与 _metadata.json 中已记录的哈希比较：
检测文件类型分布，判断是代码为主、文档为主还是混合：
.py, .ts, .js, .go, .rs, .java, .kt, .c, .cpp, .h, .rb, .php, .swift.md, .txt, .rst, .adoc, .doc, .docx, .pdf.yaml, .yml, .json, .toml, .ini, .cfg如果总文件数为 0，输出 No files found in SOURCE_PATH. 并结束。
如果总文件数 > 500，提示用户指定子目录聚焦。
如果 source 是 URL：
判断 URL 类型：
github.com/org/repo）→ 使用 gh CLI 克隆到临时目录，然后按本地路径处理WebFetch 获取的内容作为单个文档处理，计算内容 SHA256 作为去重依据
如果使用 --from-session：
输出扫描摘要：
Scanning: SOURCE_PATH (type: code/docs/mixed/url/session)
Total files: N
New files: X
Changed files: Y
Unchanged (skipped): Z
如果所有文件都未变更，输出 All N files unchanged, nothing to ingest. 并追加 log 条目后结束。
IMPORTANT: 使用 Agent 工具进行并行分析。在单条消息中启动多个 Agent。
将待处理文件分组（每组 3-8 个文件），为每组启动一个 Agent，prompt 如下：
你是一个 Wiki 知识提取 Agent。分析以下源文件，提取 wiki 页面所需的信息。
当前 wiki 已有页面列表：[从 index.md 获取]
待分析文件：
- file1.py
- file2.md
- ...
对每个文件，用 Read 工具读取内容，然后提取以下 8 类知识：
1. **实体（Entities）**：模块、类、服务、组件、工具 — 值得单独成页的东西
- 名称（kebab-case 文件名）
- 标题（人类可读）
- 描述（2-4 句话）
- 关键函数/方法列表（代码文件）或关键段落（文档文件）
- 与其他实体的关系
2. **概念（Concepts）**：设计模式、架构原则、技术概念 — 通用的、可复用的思想
- 名称
- 描述
- 涉及的实体
3. **对比（Comparisons）**：两个或多个事物的对比分析
- 对比标题（A vs B 格式）
- 对比维度
- 结论/建议
4. **人员（People）**：文件中提到的团队成员、作者、负责人
- 名称
- 专长领域（从上下文推断）
- 负责的模块/系统
4. **决策（Decisions）**：技术选型、架构决策、变更记录
- 决策标题
- 背景、选择、原因
- 替代方案
5. **流程（Processes）**：工作流、SOP、部署/发布流程
- 流程名称
- 步骤描述
- 前置条件
6. **关系（Links）**：各类页面之间的 [[wiki link]] 关系
7. **源摘要（Source Summary）**：每个文件的结构化摘要
- 文件路径
- 职责（一句话）
- 关键内容
- 依赖
注意：并非每种分类都会在每个文件中出现。只提取实际存在的内容，不要凭空创造。
输出格式为 Markdown，使用以下结构：
## New Pages
### [entity|concept|comparison|person|decision|process] page-name
Title: ...
Tags: ...
Content: ...
Related: [[link1]], [[link2]]
## Updated Pages
### page-name
Additions: ...（需要追加到已有页面的内容）
## Source Summaries
### file-path
Summary: ...
--batch 模式：减少 Agent 交互，每个 Agent 处理更多文件（最多 15 个），输出更精简。
--from-session 模式：不需要启动 Agent，主 LLM 直接从会话上下文提取知识，按上述 7 类组织输出。
收集所有 Agent 结果后：
新页面（使用 Write 工具）：
entities/<name>.mdconcepts/<name>.mdcomparisons/<name>.mdpeople/<name>.mddecisions/<name>.mdprocesses/<name>.mdsources/<name>.md每个页面使用标准格式（见"页面格式"小节），包含：
更新已有页面（使用 Edit 工具）：
updated 日期和 sources 列表命名规则：
message-builder.mdhai_api/server.py -> hai-api-server-py.mdjeff-xu.mdsglang-vs-vllm.mduse-redis-for-cache.mddeploy-to-prod.md避免重复页面：创建前检查 index.md 和 _metadata.json，如果已有同名或近似页面，更新而非新建。
扫描所有 wiki 页面，收集 [[link]] 引用关系。
对每个页面，更新其 ## Backlinks 段落：
## Backlinks
_Pages that link here:_
- [[overview]]
- [[hai-flow-engine]]
使用 Grep 工具搜索 [[page-name]] 的引用：
grep -r '\[\[page-name\]\]' WIKI_DIR/ --include='*.md'
只更新新增/变更页面的 backlinks 以及引用了这些页面的已有页面的 backlinks。
重新生成 index.md，按分类组织所有页面：
# Wiki Index
> Auto-maintained by /teamai-wiki. Last updated: YYYY-MM-DD
> Pages: N | Links: M | Sources: K
## Entities
- [[message-builder]] — 消息构造器，hai-flow 核心组件
- [[hai-api-server]] — HAI API 主服务
## Concepts
- [[rollback-workflow]] — 回滚工作流设计模式
## Comparisons
- [[sglang-vs-vllm]] — 推理框架对比：吞吐、延迟、易用性
## People
- [[jeff-xu]] — GPU 推理服务架构、K8s 集群管理
## Decisions
- [[use-redis-for-cache]] — 选择 Redis 作为缓存层（2026-03）
## Processes
- [[deploy-to-prod]] — 生产环境部署流程
## Sources
- [[hai-api-server-py]] — hai_api/server.py
## Queries
_No queries yet._
如果本次 ingest 带来了重大新信息（新页面 > 3 或首次 ingest），更新 overview.md：
[[links]]追加一行操作日志：
| YYYY-MM-DD HH:MM | ingest | Source: <path/url/session>, Type: <code/docs/mixed/url/session>, New pages: X, Updated: Y, Skipped: Z |
更新以下字段：
sources: 添加/更新已摄入文件的哈希和关联页面pages: 添加/更新页面的元数据（title, category, tags, outLinks, inLinks）stats: 更新统计数据updatedAt: 当前时间戳sourceDir: 如果未设置，记录源目录路径输出 ingest 摘要：
Ingest complete
Source: <path> (type: code/docs/mixed/url/session)
New pages: X (entities: A, concepts: B, comparisons: C, people: D, decisions: E, processes: F, sources: G)
Updated pages: Y
Skipped: Z unchanged files
Total wiki links: N
query "<question>"读取 index.md 和 _metadata.json，了解 wiki 中有哪些页面。
如果 wiki 为空（无页面），提示用户先运行 /teamai-wiki ingest。
根据问题关键词，从 index.md 中识别 3-8 个最相关的页面。也可使用 Grep 搜索 wiki 页面内容：
grep -r -l 'keyword' WIKI_DIR/ --include='*.md'
使用 Read 工具读取定位到的 wiki 页面。沿着 [[links]] 扩展阅读范围（最多读取 12 个页面）。
基于 wiki 页面内容，回答用户问题：
（参见 [[page-name]]）如果用户使用了 --save 参数：
queries/<name>.md，使用标准页面格式| YYYY-MM-DD HH:MM | query | Q: "<question>", Pages read: N, Saved: yes/no |
lint读取 _metadata.json 获取页面列表，然后读取所有 wiki 页面内容。
如果页面较多（>30），使用 Agent 工具并行读取和分析。
检查以下问题：
Broken Links：
[[link]] 指向不存在的页面Orphan Pages：
Contradictions：
Missing Pages：
[[link]] 引用但不存在的页面Stale Content：
_metadata.json 中记录的源文件哈希与当前文件不同，标记对应的 wiki 页面为 potentially staleBacklink Mismatches：
Empty Categories：
## Wiki Lint Report
### Broken Links (N)
- [[missing-page]] referenced in entities/message-builder.md:15
### Orphan Pages (N)
- entities/old-module.md — no incoming links
### Missing Pages (N)
- [[rabbitmq-integration]] — referenced by 3 pages, suggest creating it
### Stale Content (N)
- sources/server-py.md — source file changed since last ingest
### Backlink Mismatches (N)
- entities/foo.md — missing backlink from concepts/bar.md
### Empty Categories (N)
- people/ — no pages yet (consider: /teamai-wiki ingest team-roster or meeting notes)
- processes/ — no pages yet (consider: /teamai-wiki ingest runbooks or SOPs)
### Summary
Pages: N | Links: M | Issues: K
| YYYY-MM-DD HH:MM | lint | Issues found: N (broken: A, orphan: B, missing: C, stale: D) |
status读取 wiki 的 _metadata.json。如果不存在，提示先运行 /teamai-wiki init。
Wiki Status
Wiki: WIKI_DIR
Pages: N (entities: A, concepts: B, comparisons: C, people: D, decisions: E, processes: F, sources: G, queries: H)
Links: M (avg N.N per page)
Sources ingested: K files
Last ingest: YYYY-MM-DD HH:MM
Last lint: YYYY-MM-DD HH:MM (or "never")
Recent log entries:
- [time] ingest: ...
- [time] query: ...
Also read the last 5 lines of log.md for recent activity.
export [--format md|html]将 wiki 导出为单个文件，方便分享给不用 Obsidian 的同事。
读取 _metadata.json 和 index.md。如果 wiki 为空，提示先 ingest 内容。
--format md（默认）：合并为单个 Markdown 文件--format html：生成带目录导航的 HTML 页面Markdown 格式：
按 index.md 的顺序，将所有页面合并为一个文件：
# Wiki Export: <wiki-name>
> Exported on YYYY-MM-DD | Pages: N | Links: M
---
## Table of Contents
[自动生成目录]
---
## Entities
### Message Builder
[页面正文，[[links]] 转换为 Markdown 内部锚点 [text](#anchor)]
---
### HAI API Server
[...]
---
## Concepts
[...]
## Comparisons
[...]
## People
[...]
## Decisions
[...]
## Processes
[...]
HTML 格式：
生成一个自包含的 HTML 文件：
[[links]] 转换为页面内锚点跳转wiki/export/wiki-export-YYYY-MM-DD.mdwiki/export/wiki-export-YYYY-MM-DD.htmlmkdir -p WIKI_DIR/export
输出：
Wiki exported to: <path>
Format: md/html
Pages included: N
File size: X KB
| YYYY-MM-DD HH:MM | export | Format: md/html, Pages: N, Output: <path> |
_schema.md — 确保遵循 wiki 约定。<projectRoot>/.teamai/config.yaml 的 scope 字段：project scope 用 <projectRoot>/.teamai/wiki/，user scope 用 ~/.teamai/wiki/。与 teamai push/pull 的 WikiHandler.getSharedWikiDir() 逻辑对齐。[[links]] 使用 Obsidian 格式，方便用户在 Obsidian 中直接浏览。.env、*.pem、*.key、credentials.json 等可能含密钥的文件。_metadata.json 损坏时尝试从 wiki 目录重建；URL 无法访问时给出清晰错误提示。teamai push/pull 与团队共享。_metadata.json 不推送，每次 pull 后由本地重建。修改 wiki 后提醒用户运行 teamai push 同步到团队。