repo-wiki

Local-first repository wiki generator — 无需 .qoder 目录即可为任意工程生成结构化 Wiki 文档。

核心能力

Qoder-like 输出 — 提供隔离生成、发布清单和可配置的严格质量门禁
Local-first — 无需外部数据库；SQLite+FTS 必有。Chroma 可选（pip install 'repo-wiki[vector]'），未安装时语义索引降级为本地 vectors.json
隔离输出 — --profile qoder-like 输出到 .repo-agent-eval/，不污染目标仓库
增量更新 — 基于 git diff 实现页面级失效和选择性重生成
Strict Verify — 13 项质量门禁（prose density、citations、Mermaid、stale commit 等）

快速开始

1. 安装 `repo-wiki` CLI

git clone https://github.com/bingooyong/repo-wiki-agent.git
cd repo-wiki-agent
uv venv .venv && source .venv/bin/activate
uv pip install -e .

在新项目中确认命令可用：

cd /path/to/your-repo
repo-wiki --help

2. 在目标项目配置 LLM

推荐用 VS Code/Cursor 插件侧栏配置：活动栏 Repo Wiki → Configure LLM Settings / Set LLM API Key / Test LLM Configuration。Key 进入 VS Code SecretStorage，不写入 YAML 或普通 settings。真正调用 LLM 的仍是 Python CLI。

YAML + 环境变量仍可用（CI、纯终端、或旧 VSIX）。从本仓重新 vsce package 后才有上述 UI。

在目标项目根目录创建 repo-wiki.yaml，只写非敏感配置：

project:
  name: auto
  root: .

llm:
  provider: openai
  model: gpt-4o-mini
  base_url: https://api.example.com/v1
  api_key_env: REPO_WIKI_LLM_API_KEY

无 YAML 时默认 provider=openai、model=gpt-4o-mini。要用 Anthropic 请在 YAML 里显式写 provider: anthropic。

然后在当前 VS Code 集成终端或 shell 中设置真实 API Key：

export REPO_WIKI_LLM_API_KEY="<your-api-key>"

不要把真实 API Key 写入 repo-wiki.yaml、VS Code settings、命令字符串、日志、文档或已提交文件。插件里用 Set LLM API Key 写入 SecretStorage；终端场景用临时环境变量。shell profile 或未提交 .env 仅在你接受本机落盘风险时使用。

也可以不写 YAML，直接使用环境变量：

export LLM_PROVIDER="openai"
export LLM_MODEL="gpt-4o-mini"
export LLM_BASE_URL="https://api.example.com/v1"
export LLM_API_KEY_ENV="REPO_WIKI_LLM_API_KEY"
export REPO_WIKI_LLM_API_KEY="<your-api-key>"

3. 诊断、生成、验证、发布

# 检查 LLM 配置。FAIL 时会返回非零码，但仍会输出 JSON 诊断。
repo-wiki config --ci

# 初始化与索引
repo-wiki init
repo-wiki index

# 生成 Wiki（qoder-like 模式，隔离输出）
repo-wiki generate --profile qoder-like --output .repo-agent-eval

# 验证质量
repo-wiki verify --profile qoder-like --ci --output .repo-agent-eval

# 发布 READY release，供 VS Code/Cursor 插件读取
repo-wiki release-publish --output .repo-agent-eval

插件默认读取：

.repo-agent-eval/repowiki/zh/manifest.json

如果只生成 run 目录但未执行 release-publish，插件可能看不到可浏览 Wiki。

Codex 插件

仓库包含 skills-only 的 repo-wiki Codex 插件。它复用当前 Python 环境中的 repo_wiki.main，要求同一解释器中安装 repo-wiki >= 0.1.0，不会自行安装依赖、修改 shell profile，或保存 API Key。v1 不包含 MCP server；只有需要无 shell 主机、typed tools 或进度 UI 时才考虑增加 MCP。

完成上面的 CLI 安装后，在仓库根目录将本地 marketplace 加入 Codex。命令输出会显示 marketplace 名称；在第二条命令中使用该名称：

codex plugin marketplace add <repo-root>
codex plugin add repo-wiki@<marketplace-name>

在新的 Codex conversation 中使用 repo-wiki、repo-wiki-generate、 repo-wiki-maintain 或 repo-wiki-verify skill。生成或改进 run 只会止步于验证成功的 candidate；只有提供完整 G005 质量证据、通过 inspect，并明确确认同一 run ID 后，才会替换本地 READY release。

示例请求：

使用 repo-wiki 检查当前仓库，并告诉我下一步应该初始化、生成还是验证。
使用 repo-wiki-generate 为当前仓库生成 run ID 为 review-2026-08-13 的验证候选。
使用 repo-wiki-verify 验证 run review-2026-08-13，不要发布。

开发插件更新时，先更新 cachebuster，再升级或重新安装 marketplace/plugin，刷新 Codex，并在新的 conversation 中完成 smoke test：

python ~/.codex/skills/.system/plugin-creator/scripts/update_plugin_cachebuster.py \
  plugins/repo-wiki
codex plugin marketplace add <repo-root>
codex plugin add repo-wiki@<marketplace-name>

本地发布前运行官方 package validator，并在可用时运行隔离 Codex smoke test。没有本地 Codex binary 时，smoke test 会明确跳过；该安装检查仍是人工验证缺口。

python ~/.codex/skills/.system/plugin-creator/scripts/validate_plugin.py plugins/repo-wiki
python scripts/smoke_codex_plugin.py

移除插件不会删除已生成的 Wiki 或 READY release：

codex plugin remove repo-wiki@<marketplace-name>
codex plugin marketplace remove repo-wiki-local

第二条命令是可选的；保留 marketplace 可供后续重装。READY replacement 的回滚仍由现有 atomic publisher 的 backup/restore 行为负责。

CLI 命令

命令	说明
`repo-wiki init`	初始化仓库索引
`repo-wiki index`	构建搜索索引
`repo-wiki generate [--profile qoder-like]`	生成 Wiki 文档
`repo-wiki update`	增量更新（基于 git diff）
`repo-wiki verify --ci --profile qoder-like`	质量验证
`repo-wiki release-publish --output .repo-agent-eval`	发布 READY release，供插件读取
`repo-wiki config --ci`	LLM 配置诊断
`repo-wiki search "<query>"`	语义搜索
`repo-wiki graph`	模块依赖图
`repo-wiki cost-estimate`	LLM 成本估算

架构

┌─────────────────────────────────────────────────────────────┐
│                        CLI Layer                            │
│         init | index | generate | verify | search | ...     │
└─────────────────────────────────────────────────────────────┘
                              │
┌─────────────────────────────────────────────────────────────┐
│                    Orchestration Layer                      │
│   Service │ GenerationStateMachine │ GenerationScheduler       │
└─────────────────────────────────────────────────────────────┘
                              │
┌─────────────────────────────────────────────────────────────┐
│                      Agent Layer                            │
│  Scanner │ IndexGraph │ DocGen │ AdapterGovernance │ QA      │
└─────────────────────────────────────────────────────────────┘
                              │
┌─────────────────────────────────────────────────────────────┐
│                      Storage Layer                          │
│     SQLite/FTS5      │      ChromaDB      │    Files       │
└─────────────────────────────────────────────────────────────┘

输出模式

模式	输出位置	特点
qoder-like run	`.repo-agent-eval/runs/<run>/repowiki/zh/**`	隔离运行产物，不碰目标工程
qoder-like release	`.repo-agent-eval/repowiki/zh/{manifest.json,content,meta}`	READY 稳定发布面，VS Code/Cursor 插件默认读取
standard	`docs/`, `.repo-wiki/`	直接写入目标工程

VS Code / Cursor 插件

插件目录：extensions/repo-wiki-browser。

当前插件能力：

浏览 .repo-agent-eval/repowiki/zh/manifest.json 中 READY release 的 navigation_tree；
打开生成的 Markdown 预览；
触发 Repo Wiki: Update Wiki，向集成终端发送 repoWikiBrowser.generateCommand，并按 source 策略注入非空 LLM_*；
可视化配置 provider / model / base URL / api_key_env（Configure LLM Settings）；
用 SecretStorage 保存/清除 API Key（Set / Clear LLM API Key）；
运行 Repo Wiki: Test LLM Configuration（repo-wiki config --ci，输出脱敏）；
展示 repo-wiki.yaml / .repo-wiki.yaml 中的 LLM 摘要。

当前插件限制：

扩展不内嵌 Python，也不直接调用 LLM；
未执行 release-publish 时可能看不到可浏览 Wiki；
旧 VSIX 可能没有 LLM UI，需从本仓按下面步骤重新打包。

重新打包插件：

cd extensions/repo-wiki-browser
npm ci
npm run compile
npx @vscode/vsce package --out repo-wiki-browser-0.1.0.vsix
code --install-extension repo-wiki-browser-0.1.0.vsix --force

Strict Verify 门禁（qoder-like）

检查项	说明	门禁
`qoder-page-dumps`	无列表过重页面	HARD
`qoder-prose-density`	prose 密度 >= 30%	HARD
`qoder-stale-commit`	git commit 最新	HARD
`qoder-content-empty`	内容非空	HARD
`qoder-toc`	有目录	SOFT
`qoder-citations`	有引用	SOFT
`qoder-mermaid`	有图表	SOFT
`qoder-api-aggregation`	API 聚合质量	HARD
`qoder-dm-aggregation`	Data model 聚合质量	HARD
`qoder-citation-relevance`	引用相关性	HARD
`qoder-dirty-worktree`	工作树干净	HARD

文档

项目状态

指标	状态
Strict Verify	可通过 `repo-wiki verify --profile qoder-like --ci` 复现
Release Gate	仅发布通过当前门禁的 READY 产物
Tests	以公开 CI 结果为准

技术栈

Python 3.11+ with uv package manager
SQLite/FTS5 — 本地状态和全文检索
ChromaDB — 可选语义向量存储（repo-wiki[vector]）；未安装时 JSON fallback
LLM — OpenAI-compatible / Minimax
VS Code/Cursor Extension — TypeScript sidebar for browsing READY Wiki releases

License

Apache License 2.0 - see LICENSE

Name		Name	Last commit message	Last commit date
.agents/plugins		.agents/plugins
.github		.github
ai/source-of-truth		ai/source-of-truth
ci		ci
docs		docs
extensions/repo-wiki-browser		extensions/repo-wiki-browser
plugins/repo-wiki		plugins/repo-wiki
repo_wiki.egg-info		repo_wiki.egg-info
repo_wiki		repo_wiki
scripts		scripts
templates		templates
tests		tests
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
MANIFEST.in		MANIFEST.in
Makefile		Makefile
README.md		README.md
SECURITY.md		SECURITY.md
pyproject.toml		pyproject.toml
uv.lock		uv.lock

Navigation Menu

Repository files navigation

repo-wiki

核心能力

快速开始

1. 安装 `repo-wiki` CLI

2. 在目标项目配置 LLM

3. 诊断、生成、验证、发布

Codex 插件

CLI 命令

架构

输出模式

VS Code / Cursor 插件

Strict Verify 门禁（qoder-like）

文档

项目状态

技术栈

License

About

Releases

Packages

Used by

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

repo-wiki

核心能力

快速开始

1. 安装 repo-wiki CLI

2. 在目标项目配置 LLM

3. 诊断、生成、验证、发布

Codex 插件

CLI 命令

架构

输出模式

VS Code / Cursor 插件

Strict Verify 门禁（qoder-like）

文档

项目状态

技术栈

License

About

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages

1. 安装 `repo-wiki` CLI