T Wiki

T Wiki 是用于把代码仓库或 Markdown 资料编译成可提交、可追溯、同时适合人和 Agent 阅读的本地 Wiki。

它会在目标项目中维护 docs/wiki/ 知识层，生成主题文章、跨主题概念、机器索引、来源映射、知识图谱和增量编译状态。

主要能力

• 支持代码仓库和 Markdown 知识库两种模式。
• 根据目录、文档、manifest 和可选源码扫描自动发现主题。
• 增量编译发生变化的内容，也支持全量重建和单主题重建。
• 为重要结论记录 claim 与真实来源，便于追溯和审计。
• 生成适合 Obsidian 阅读的 Markdown 和适合 Agent 检索的 JSON 索引。
• 支持基于已编译 Wiki 的问答、搜索、lint 和质量审计。
• 支持把单个新增文件吸收到现有 Wiki。

安装

将本目录复制或链接到 Codex 的 skills 目录，确保目录结构如下：

npx skills@latest add https://github.com/taroify/t-wiki.git

安装后确认的可用 skill 列表中出现 t-wiki。

快速开始

进入需要创建 Wiki 的项目目录，然后初始化：

$t-wiki init

初始化会自动判断项目更适合 Codebase Mode 还是 Knowledge Mode，并生成：

docs/wiki/.t-wiki.json

随后执行首次编译：

$t-wiki --full

编译完成后，可以直接提问：

$t-wiki query 登录态是如何处理的？

也可以搜索已有主题：

$t-wiki search 权限校验

工作模式

模式	适用场景	默认扫描范围
codebase	代码仓库、服务、应用或 monorepo	项目文档、manifest、构建与部署配置；开启 deep 后扫描指定扩展名的源码
knowledge	文档库、会议记录、研究资料、知识笔记	sources[] 范围内的 Markdown、MDX、RST 和 AsciiDoc 等文档

初始化时可以强制选择模式：

$t-wiki init --codebase
$t-wiki init --knowledge

为 Codebase Mode 开启源码深度扫描：

$t-wiki init --codebase --deep

--deep 是初始化参数，对应配置中的 "deep": true。

命令

指令	作用	是否写文件
$t-wiki init	检测项目类型并初始化配置与目录	是
$t-wiki	增量编译新增或变化的来源	是
$t-wiki compile	与无参数调用相同，执行增量编译	是
$t-wiki refresh	刷新 Wiki，默认按增量方式执行	是
$t-wiki query {问题}	基于已编译 Wiki 回答问题并给出 claim 来源	默认否
$t-wiki search {关键词}	搜索 topic、concept、别名和标签	否
$t-wiki lint	检查结构、链接、覆盖率、状态和图谱健康度	否
$t-wiki audit	审计来源覆盖与结论准确性	否
$t-wiki ingest {path}	把单个源文件吸收到相关 topic	是

编译参数

参数	作用
--full	重新枚举全部候选源并全量编译
--topic {slug}	只重编指定 topic，但仍会重新枚举完整候选源
--dry-run	预览候选源、变化和计划写集，不写文件
--no-audit	编译完成后跳过 audit 修复闭环

示例：

$t-wiki compile --full
$t-wiki refresh --topic api-routes
$t-wiki compile --dry-run
$t-wiki compile --no-audit

单文件吸收参数

默认情况下，ingest 会先总结文件并询问需要强调或弱化的内容：

$t-wiki ingest docs/architecture.md

使用 --quiet 可以跳过强调点确认并自动分类：

$t-wiki ingest docs/architecture.md --quiet

配置

配置文件位置固定为：

{repo}/docs/wiki/.t-wiki.json

完整的 Codebase Mode 示例：

{
  "version": 1,
  "name": "Project Wiki",
  "mode": "codebase",
  "sources": [
    {
      "path": "./",
      "exclude": [
        "docs/wiki/",
        "generated/"
      ]
    }
  ],
  "output": "docs/wiki/",
  "purpose_file": "PURPOSE.md",
  "topic_hints": [],
  "knowledge_files": [
    "README.md",
    "AGENTS.md",
    "ARCHITECTURE.md",
    "docs/**/*.md"
  ],
  "deep": true,
  "code_extensions": [
    ".ts",
    ".tsx",
    ".js",
    ".py",
    ".go",
    ".rs",
    ".java"
  ],
  "article_sections": []
}

配置项说明

配置项	类型	说明
version	number	配置版本，当前为 1
name	string	Wiki 名称
mode	string	工作模式：codebase 或 knowledge
sources[]	array	允许读取的来源目录
sources[].path	string	相对仓库根的来源路径，必须解析到仓库根以内
sources[].exclude[]	array	该来源目录下需要排除的路径或匹配规则
output	string	Wiki 输出目录，默认 docs/wiki/
purpose_file	string	目标问题集文件，相对 output，默认 PURPOSE.md
topic_hints[]	array	主题发现的种子词或候选主题
knowledge_files[]	array	优先作为事实来源的文件和 Glob 规则
deep	boolean	是否按 code_extensions[] 深度扫描源码，默认 false
code_extensions[]	array	深度扫描允许的文件扩展名
article_sections[]	array	自定义文章章节；为空时使用对应模式的默认模板

注意：

• output 和 purpose_file 必须使用相对路径。
• purpose_file 的路径相对 output，文件缺失不会阻断编译或查询。
• 建议始终把 output 加入 sources[].exclude[]，避免编译产物被再次扫描。
• Knowledge Mode 默认不需要 deep 和 code_extensions[]，除非明确需要扫描代码。

编译产物

使用默认输出目录时，结构如下：

docs/wiki/
├── .t-wiki.json          # 项目配置
├── .compile.json         # 增量编译状态和候选源清单
├── PURPOSE.md            # 可选：Wiki 需要服务的主要问题与范围
├── CONTEXT.md            # Codebase Mode 的简明使用入口
├── INDEX.md              # 人类可读目录
├── schema.md             # topic、concept 和命名规范
├── index.json            # Agent 可读的 topic/concept 索引
├── source-map.jsonl      # claim 到真实来源的映射
├── graph.json            # topic/concept/source 关系图谱
├── log.md                # 编译变化记录
├── topics/
│   └── {topic-slug}.md
└── concepts/
    └── {concept-slug}.md

各类产物的用途：

• INDEX.md：阅读 Wiki 的首选入口。
• topics/*.md：围绕业务、模块或知识主题组织的事实文章。
• concepts/*.md：连接三个以上 topic 的跨主题模式。
• schema.md：Wiki 结构和命名的事实源，可由人手工调整。
• index.json：供 Agent 快速定位主题、别名、覆盖率和新鲜度。
• source-map.jsonl：记录重要 claim 对应的源文件、行号、hash 和权威级别。
• graph.json：为 query 和 search 提供可解释的 1-hop 关联扩展。
• .compile.json：保存候选源 hash、Git 提交信息和上次编译状态。

常用流程

第一次为代码仓库建 Wiki

$t-wiki init --codebase --deep
$t-wiki compile --full
$t-wiki lint

日常刷新

$t-wiki

增量编译会重新枚举候选源，并优先使用 Git commit、内容 hash 和 mtime 判断新增、变化或缺失文件。

只预览影响范围

$t-wiki --dry-run

查询实现与依据

$t-wiki query 订单状态是如何流转的，修改时有哪些约束？

query 优先读取 1–3 篇最相关的 topic 或 concept，并通过 source-map.jsonl 返回 claim 来源。覆盖率低或内容可能过期时，会建议回看原始文件。

检查 Wiki 健康度

$t-wiki lint
$t-wiki audit

• lint 关注结构健康：失效链接、孤儿内容、低覆盖、索引漂移、候选源缺口和图谱健康。
• audit 关注内容质量：来源覆盖、关键面缺失、结论证据、冲突、夸大和过期风险。

独立运行的 lint 和 audit 都是只读操作。普通 compile 默认会执行 audit，并且最多在 Wiki 输出范围内修复两轮。

项目内配置

在项目的 AGENTS.md 或者 CLAUDE.md 中加入，即可让模型注入相关信息。

## 知识库

编译后的知识库位于 `docs/wiki/`。

**Session startup:** 先读 `docs/wiki/index.json` 了解可用 topic/concept，再阅读与当前任务相关的 `docs/wiki/topics/**` 或 `docs/wiki/concepts/**` 文章。

**Using coverage indicators:**
- `[coverage: high]`：可优先信任该 section，通常不用回源。
- `[coverage: medium]`：可作为概览；涉及精确字段、接口、边界逻辑或实现位置时回看 Sources。
- `[coverage: low]`：必须阅读该 section 的 Sources 原始文件。

**When you need depth:** 查看文章的 `Sources` section，只读取当前问题相关的 raw files。Wiki 是减少无效源码检索的上下文层，不替代源码、接口契约或任务证据。