repowiki-cli 0.5.0__tar.gz

repowiki_cli-0.5.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 luomsis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

repowiki_cli-0.5.0/PKG-INFO

@@ -0,0 +1,349 @@
+Metadata-Version: 2.4
+Name: repowiki-cli
+Version: 0.5.0
+Summary: Deterministic repo wiki build system, driven by any coding agent. Output language follows the repository (zh/en).
+Author: luomsis
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/luomsis/repowiki
+Project-URL: Repository, https://github.com/luomsis/repowiki
+Project-URL: Issues, https://github.com/luomsis/repowiki/issues
+Project-URL: Changelog, https://github.com/luomsis/repowiki/blob/main/CHANGELOG.md
+Keywords: documentation,wiki,codebase,mermaid,llm,agent,onboarding,developer-tools
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: Chinese (Simplified)
+Classifier: Natural Language :: English
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: Microsoft :: Windows
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyyaml>=6
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Dynamic: license-file
+
+# repowiki
+
+**中文** | [English](README.en.md)
+
+[![CI](https://github.com/luomsis/repowiki/actions/workflows/ci.yml/badge.svg)](https://github.com/luomsis/repowiki/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python ≥ 3.10](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
+[![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-lightgrey)](#可靠性设计)
+
+为任意仓库生成结构化 Wiki 的构建系统。
+
+`repowiki` 是一个确定性的构建系统：负责任务规划、原子认领、产出校验、自动修复、元数据组装；
+智能工作（读代码、写 wiki）由驱动它的 agent（Claude Code / Codex / OpenCode 等 agent CLI，或人）完成。
+零 API Key、零网络调用、零 agent CLI 依赖——任何「能跑 shell + 读写文件」的执行者都能参与，包括并发。
+Wiki 产出语言自动跟随目标仓库（中文仓库 → `zh/`，英文仓库 → `en/`；`plan --locale` 可显式指定）。
+
+![repowiki 系统架构图](docs/assets/repowiki-architecture.png)
+
+*交互版架构图：[docs/repowiki-architecture.html](docs/repowiki-architecture.html)（明暗主题 · 路径高亮 · 节点搜索，下载后在浏览器打开）*
+
+## 为什么是 repowiki
+
+给仓库生成 wiki 的现成方案主要有两条路：云端 AI wiki 服务（代码要上传、按量付费、产出是黑盒），
+或者让一个 agent 直接通读仓库现写（大仓库上下文装不下、中断即前功尽弃、难以并行）。
+repowiki 走第三条路：**读代码、写 wiki 的智能留给任意 agent，其余一切——任务规划、原子认领、
+产出校验、自动修复、断点续跑——做成确定性构建系统。**
+
+| | 云端 AI wiki 服务 | 让 agent 直接读仓库 | repowiki |
+|---|---|---|---|
+| 智能来源 | 内置 LLM（不可换） | 你的 agent（任选） | 你的 agent（任选） |
+| 代码出域 | 是 | 否 | 否 |
+| API Key / 网络 | 需要 | 视 agent 而定 | repowiki 本身零依赖 |
+| 大仓库 | 受服务方配额限制 | 上下文装不下 | 任务切分，逐页生成 |
+| 中断 / 崩溃 | — | 从头再来 | 状态落盘，断点续跑 |
+| 并行加速 | — | 难协调 | 多 worker 原子认领，天然并行 |
+| 产出质量 | 黑盒 | 靠 agent 自觉 | 模板强制 + 程序化校验 + 自动修复 |
+
+一句话：**agent 负责聪明，repowiki 负责靠谱。**
+
+## 特性（Features）
+
+- **确定性构建**：plan / claim / check / 自动修复全是确定性代码，不绑定任何 agent CLI，无需 API Key、零网络调用；
+- **并发安全**：原子任务认领 + 心跳续期 + 过期自动回收，多个 agent / 进程 / 人可同时参与同一个仓库；
+- **断点续跑**：每任务状态落盘，随时中断随时继续，崩溃不留孤儿认领；
+- **增量更新**：`update` 基于 git diff 只重写受影响页面（含祖先链）与总览页，`--dirty` 可纳入未提交/未跟踪变更；只读 `stale` 命令输出同一映射，供 CI 做「wiki 过期」门禁；`coverage` 报告确定性统计 wiki 从未引用的文件；
+- **单文件离线站点**：`site` 产出约 4-5 MB 自包含 HTML——导航、搜索、mermaid、源码弹层，双击即看；
+- **页面原型**：catalog 可按页面主题选 `module`（结构型，默认）/ `flow`（流程型）两种模板，校验器按原型分规则；知识卡片类别可用 `--categories` 整表替换内置六类；
+- **agent 消费接口**：`site` 同时导出 `llms.txt` / `llms-full.txt`（[llmstxt.org](https://llmstxt.org/) 约定），任何 agent / IDE 按索引直接读 wiki，无需 MCP；
+- **双语产出**：zh / en 自动跟随目标仓库语言，表驱动设计可扩展；
+- **跨平台**：macOS / Linux / Windows 原生支持（无需 WSL），CI 三平台 × Python 3.10-3.13 矩阵回归；
+- **强校验**：锚点 / 行号 / H1 / 路径分隔符程序化自动修复，只有语义缺陷才判失败。
+
+## 目录
+
+- [为什么是 repowiki](#为什么是-repowiki) · [特性](#特性features)
+- [安装](#安装) · [快速开始](#快速开始)
+- [用法](#用法usage)（Worker 循环契约 / 并发配方）· [命令一览](#命令一览)
+- [查看 Wiki：单文件离线站点](#查看-wiki单文件离线站点) · [CI 集成](#ci-集成wiki-门禁--pages-发布)
+- [可靠性设计](#可靠性设计) · [设计取舍](#设计取舍) · [已知边界](#已知边界) · [Non-Goals](#non-goals)
+- [Roadmap](#roadmap) · [贡献](#贡献contributing) · [社区](#社区) · [文档](#文档) · [License](#license)
+
+## 安装
+
+### 1. CLI（必需，Python ≥ 3.10，macOS / Linux / Windows）
+
+```bash
+pip install git+https://github.com/luomsis/repowiki.git   # 或 pipx install git+同URL
+# 已克隆本仓库时：cd repowiki && pip install -e .
+```
+
+Windows 原生支持（无需 WSL）：并发状态控制自动使用 `msvcrt` 文件锁（POSIX 用 `fcntl`），
+全部功能在 PowerShell / cmd / git-bash 下可用；后台运行 watch 的 PowerShell 等价命令见
+[skills/repowiki/SKILL.md](skills/repowiki/SKILL.md)。CI 在三大平台上回归。
+
+### 2. Agent Skill（可选，让 agent 自动触发本工作流）
+
+`skills/repowiki/` 是符合 SKILL.md 开放约定的 skill 目录，两种装法任选：
+
+- **插件安装**（支持版本管理）：把本仓库作为插件市场目录或直接指向其 git 地址安装，
+  仓库根部的插件清单会被自动识别；
+- **手动拷贝**：把 `skills/repowiki/` 整个目录拷进所用客户端的个人 skills 目录
+  （常见为 `~/.claude/skills/repowiki/`、`~/.agents/skills/repowiki/` 等）。
+
+skill 只是指引（告诉 agent 按什么流程调用 CLI），真正干活的是第 1 步装的 `repowiki` 命令。
+
+### 3. 离线安装（目标机无法访问 PyPI / GitHub 时）
+
+repowiki 的运行时依赖**只有 `pyyaml>=6`**，离线安装只需三样东西：仓库源码、pyyaml 的 wheel、目标机上的 Python ≥ 3.10。
+
+**在有网的机器上准备物料**：
+
+```bash
+pip download PyYAML==6.* -d wheels/        # 下载 pyyaml wheel（按目标机平台/Python 版本：macOS/Linux 各架构、Windows 的 wheel 互不通用）
+pip wheel --no-deps -w wheels/ .           # 或直接用 Release 页附带的 repowiki_cli-*.whl
+```
+
+把仓库目录（或 `repowiki_cli-*.whl`）与 `wheels/` 一起拷到目标机，然后：
+
+```bash
+pip install --no-index wheels/PyYAML-*.whl        # 先装唯一依赖
+pip install --no-index repowiki_cli-*.whl             # 再装 repowiki 本体（或 -e 源码目录）
+repowiki --version                                # 验证
+```
+
+用 pipx 的话：`pipx install --no-index repowiki_cli-*.whl`。要跑测试套再额外离线装 `pytest`（`[test]` extra）。
+
+Agent Skill 同样离线可用——`skills/repowiki/` 是纯文本目录，直接整目录拷进客户端的
+skills 目录（`~/.claude/skills/repowiki/` 等）即可；skill 只调用本机已装好的 `repowiki` 命令，
+不需要任何在线服务。注意 repowiki 自身零网络，但 `update` 依赖目标仓库本地的 git CLI
+（`git diff` / `git rev-parse`），git 预装的机器无需额外配置。
+
+## 快速开始
+
+```bash
+repowiki plan ~/code/myrepo          # 扫描 → 生成任务清单（代码文件 <10 会拒绝）
+repowiki next ~/code/myrepo --claim --json   # 领取任务，按 instructions 执行
+# ... 按任务规格撰写产出，然后：
+repowiki check ~/code/myrepo --task c01      # 校验+自动修复+状态流转
+repowiki finalize ~/code/myrepo      # 组装 metadata.json（两步：先创建 overview 任务）
+repowiki site ~/code/myrepo          # 生成单文件离线查看站点（--open 自动打开浏览器）
+```
+
+输出结构（`<locale>` 由 plan 自动检测或 `--locale` 指定，当前支持 `zh` / `en`）：
+
+```
+myrepo/.repowiki/
+├── zh/                     # 或 en/ —— 语言跟随目标仓库
+│   ├── content/            # 章节树：目录名=章节名，索引页+子页，固定模板
+│   │   ├── 快速开始.md      # 顶级独立页
+│   │   └── 项目概述/项目概述.md, 核心概念.md, ...
+│   ├── meta/repowiki-metadata.json   # catalogs/items/source_files/snippets/relations
+│   ├── wiki.html           # 单文件离线查看站点（repowiki site 生成，双击即开）
+│   └── llms.txt / llms-full.txt      # agent 消费索引：章节链接目录 + 全文合并（site 同时导出）
+├── knowledge/zh/           # 知识卡片：_index.yaml + 模块文档 + 机制卡片
+└── state/                  # 任务清单/规格/认领/locale（内部状态，可随时删除重规划）
+```
+
+## 查看 Wiki（单文件离线站点）
+
+**在线样例**：repowiki 为自己生成的 wiki 已发布到 GitHub Pages——
+[直接打开看效果](https://luomsis.github.io/repowiki/zh/wiki.html)（由下方 `wiki.yml` 工作流在每次 push main 后自动重建）。
+
+![阅读视图：章节导航 + mermaid 渲染 + 源码引用](docs/assets/site-preview-reading.png)
+
+![点击 file:// 源码引用，页内弹层查看带行号的源码片段](docs/assets/site-preview-snippet.png)
+
+`repowiki site <repo> [--open]` 把整个 wiki 打包成**一个自包含的 HTML 文件**
+（`<repo>/.repowiki/<locale>/wiki.html`，约 4-5 MB）：
+
+- markdown + mermaid 全部渲染，引用的源码行区间直接内嵌，点击 `file://` 引用在页内
+  弹层查看带行号高亮的源码——无需 IDE、无需网络，发给同事一个文件即可浏览整个 wiki；
+- 侧边栏章节导航（可折叠）+ 当前页目录（可折叠、scroll-spy 跟随高亮）、全文搜索（命中词高亮）、
+  代码块一键复制、prev/next 翻页、阅读进度条、暗色/浅色主题（跟随系统 + 手动切换）；
+- 完全离线：markdown/mermaid 渲染库（marked/mermaid，MIT）已内嵌进文件本身；
+- 幂等可重跑：finalize、update 或手动改了页面之后随时重新执行 `repowiki site` 重建；
+- 执行过 `repowiki clean` 也能重建（此时章节顺序退化为目录序，内容不受影响）。
+
+页面模板（校验器按语言强制）按原型分两种：**module（默认，结构型）** H1 → `<cite>` 引用块 →
+目录 → 简介 → 项目结构（mermaid graph TB）→ 核心组件 → 架构总览（sequenceDiagram）→ 详细组件
+分析 → 依赖关系分析（graph LR）→ 性能与一致性考量 → 故障排查指南 → 结论；**flow（流程型）**
+简介 → 流程总览（sequenceDiagram）→ 关键步骤 → 参与组件 → 数据与状态变化（graph LR）→ 故障
+排查指南 → 结论。规划时在 catalog 节点上用可选 `archetype` 字段选择；每节末尾「Section
+sources/章节来源」、每图后「Diagram sources/图表来源」，链接格式
+`[path:Lx-Ly](file://path#Lx-Ly)`；页间零链接（正因如此所有页面任务可完全并行）。
+
+## 用法（Usage）
+
+### Worker 循环契约
+
+任何执行者（subagent / 进程 / 人）按此循环参与，多个循环可同时运行：
+
+```
+loop:
+  t = repowiki next <repo> --claim --json
+  tasks 为空且 busy>0  → 等待重试（他人执行中）
+  tasks 为空且 busy=0  → 退出
+  按 t.tasks[0].instructions 执行（只写指定的 output 文件）
+  执行期定期 repowiki touch <repo> --task <id>   # 心跳续期，防被过期回收
+  repowiki check <repo> --task <id> --json
+    ok=false → 按 errors 修复后重查；放弃则 repowiki release <repo> --task <id> --force
+```
+
+一次只持有一个认领：当前任务 check 通过（或放弃）后才回到 `next`（每次 next 只发放一个任务）——
+worker 中途退出时手中不留孤儿认领；即便异常退出，过期认领也会自动回队列（见可靠性设计）。
+
+### 并发配方
+
+**Subagent 型（Claude Code / OpenCode 等）**：主 agent 先串行完成 plan + catalog，
+然后 spawn N 个 subagent 各自跑 worker 循环（N=3~6 即可，页面任务相互独立）。
+详见 [skills/repowiki/SKILL.md](skills/repowiki/SKILL.md)。
+
+**无人值守（任何 headless agent CLI，由你决定用哪个）**：
+
+```bash
+#!/bin/bash
+# worker.sh —— 把 claude 换成 codex exec / opencode run，工具不感知、不限制用哪个 agent
+while :; do
+  TASK=$(repowiki next . --claim --json)
+  N=$(echo "$TASK" | jq '.tasks | length')
+  if [ "$N" -eq 0 ]; then
+    [ "$(echo "$TASK" | jq '.busy')" -eq 0 ] && break   # 空且无人执行 → 退出
+    sleep 30 && continue                                # 空但 busy>0 → 等待重试
+  fi
+  ID=$(echo "$TASK" | jq -r '.tasks[0].id')
+  claude -p "$(echo "$TASK" | jq -r '.tasks[0].instructions')" --permission-mode acceptEdits &
+  while kill -0 $! 2>/dev/null; do
+    repowiki touch . --task "$ID"; sleep 300            # 执行期心跳，防长任务被回收
+  done
+  repowiki check . --task "$ID" --worker my-worker
+done
+```
+
+## 命令一览
+
+| 命令 | 作用 |
+|---|---|
+| `plan <repo> [--replan [--force]] [--max-pages N] [--knowledge] [--locale auto\|zh\|en]` | 扫描+生成任务清单；产出语言自动检测（README 权重最高）或显式指定，持久化于 `state/locale`；已有合法 catalog.json 则直接展开页面任务；有任务执行中时 replan 需 --force |
+| `next [--claim] [--json]` | 领取就绪任务，每次只发放一个（阶段门控：attempts 少者优先）；worker 死亡后过期的认领会自动回队列，无需人工释放；`--json` 含完整 instructions |
+| `touch --task ID` | 执行期心跳：刷新认领，防长任务被过期回收 |
+| `watch [--interval S] [--timeout S]` | 阻塞监控直到全部完成（exit 0）或停滞/超时（exit 1）；过期认领不算执行中，真停滞可被及时报告 |
+| `check --task ID \| --all` | 校验产出；锚点/行号/H1 自动修复；catalog/knowledge-plan 通过后自动展开后续任务；done 为终态（只读报告）；他人认领的任务需 --force |
+| `release --task ID [--force]` | 释放认领（崩溃恢复） |
+| `finalize` | 组装 metadata.json；要求全部任务 done |
+| `site [--open]` | 把完成的 wiki 渲染成单文件离线 HTML（`<locale>/wiki.html`：导航+搜索+mermaid+源码弹层，知识模块文档与卡片纳入「知识库」章），同时导出 `llms.txt` / `llms-full.txt` agent 索引；要求先 finalize；`--open` 生成后用默认浏览器打开 |
+| `update [--since <sha>] [--dirty]` | git diff → 受影响页面（含祖先链）与总览页 → 增量重写任务（附「更新摘要」）；同时联动知识库：`source_files` 命中变更的卡片与 scope 命中的模块各建刷新任务；默认仅识别**已提交**变更（since..HEAD），`--dirty` 纳入工作区未提交与未跟踪变更 |
+| `stale [--since <ref>] [--dirty] [--fail-if-stale]` | 只读过期报告：复用 `update` 的 diff→受影响页面映射，报告哪些页面/卡片/模块会过期——不创建任务、不写 state；`--fail-if-stale` 供 CI 门禁（命中则 exit 1） |
+| `coverage` | 只读覆盖率报告：统计 wiki 页面/总览/知识卡片从未引用的仓库文件与逐页引用密度（确定性计算，JSON 含全量清单） |
+| `knowledge [--categories <file>]` | 追加知识卡片任务集（机制卡片 + 模块文档）；`--categories` 用 YAML/JSON 文件整表替换内置六类（持久化于 state）；finalize 时聚合导出 `_index.yaml` / `_module.yaml` |
+| `status` | 进度 / 失败列表 / 过期认领 |
+| `clean` | 删除整个 `state/`（wiki 产出保留；失去 update/续跑/幂等 plan） |
+
+退出码：`0` 成功，`1` 校验失败或用法错误，`2` 状态冲突（任务被他人认领），`3` 进展性等待（finalize 已创建 overview 任务，完成后再次运行即可）。
+
+## CI 集成（wiki 门禁 + Pages 发布）
+
+[.github/workflows/wiki.yml](.github/workflows/wiki.yml) 提供两个独立 job（wiki-as-code 模式：
+仓库跟踪 `.repowiki/` 的内容、元数据与知识库；`state/claims`、`state/tasks` 与可重建的
+`wiki.html` 可忽略）：
+
+- **PR wiki 过期门禁**：`repowiki stale . --since origin/main --fail-if-stale` —— 代码改了、
+  wiki 过期则自动评论受影响页面并拦截合并（确定性检查，CI 内不跑任何 agent）；
+- **GitHub Pages 发布**：push main 后自动 `repowiki site .` 重建并发布，README 挂的在线样例
+  即由此产出。
+
+在你的仓库启用：拷贝该 workflow 文件，提交 `.repowiki/`（finalize 之后），并在仓库设置里把
+Pages 来源设为 GitHub Actions。
+
+## 可靠性设计
+
+- **并发安全**：原子 `mkdir` 认领 + 目录 mtime 过期判定（默认 15 分钟，
+  `REPOWIKI_STALE_SECONDS` 可调）。
+- **队列自愈**：崩溃/被杀 worker 的过期认领由 `next` 自动回收重新入队（改名 `.stale-*` 留痕、
+  attempts+1，毒任务上限照常生效），无需人工 `release --force`；活认领靠 `touch` 心跳续期防误抢
+  （repowiki 是短命 CLI 进程，记录的 pid 无存活意义，心跳是唯一存活信号）。
+- **watch 不假活**：过期认领不计入「执行中」，worker 全部死亡时停滞可被及时报告而非干等超时。
+- **确定性优先**：锚点、行号区间、H1、路径分隔符由程序自动修复；
+  只有语义缺陷（缺章节、引用不存在文件、mermaid 不闭合）才判失败。
+- **断点续跑**：每任务状态落盘（`state/index.json`），随时中断随时继续；产出语言持久化于 `state/locale`。
+- **损坏防护**：`state/index.json` 或 `catalog.json` 损坏时保留现场并明确报错（绝不静默清空任务清单），`plan --replan --force` 为显式恢复路径。
+- **自动瘦身**：finalize 成功后自动清除运行时产物（`state/claims/`、`state/tasks/`），
+  保留 `index.json`/`catalog.json`/`knowledge.json` 供增量更新与幂等重跑；
+  不需要增量更新可执行 `repowiki clean <repo>` 删除全部状态（wiki 产出不受影响）。
+- **测试**：187 个单测覆盖竞态、孤儿认领自动回收、校验规则正反例（含 flow 原型）、增量映射、过期门禁、覆盖率统计、自定义知识类别、知识聚合、双语产出（zh/en）、单文件站点与 llms 索引生成、损坏状态文件与非法输入的友好报错（`pytest`；CI 矩阵覆盖 ubuntu/macos/windows × Python 3.10-3.13）。
+
+## 设计取舍
+
+- `metadata.json` 只含可读字段（catalogs/items/source_files/snippets/relations），不输出加密内部状态（运行时状态在 `state/`）。
+- ADR 类知识卡片不生成；机制卡片/模块文档完整支持。
+- 产出语言为简体中文（`zh/`）与英文（`en/`），表驱动设计，新增语言 = 一张字符串表 + 一套模板。
+- CLI 交互消息当前为中文（面向驱动它的 agent），不影响 wiki 产出语言。
+
+## 已知边界
+
+- 每个任务规格内嵌完整模板与文风规范（约 4-6k tokens）——换取任务自包含与并行安全；
+  小上下文 agent 可将规格中的模板段落替换为对 `templates/` 目录的引用。
+- 产出语言由 plan 时确定并持久化，中途换语言需 `plan --replan`；`file://` 引用解析、程序化领取依赖 `jq` 属常见但非必需。
+
+## Non-Goals
+
+LLM API 后端 · 内置 agent CLI 检测/执行器 · MCP 封装（agent 读取 wiki 的需求由 `llms.txt` 静态导出满足） · 常驻预览服务器（`site` 产物是纯静态单文件，双击即看，无需起服务） · zh/en 之外的产出语言。
+
+## Roadmap
+
+- [ ] 发布到 PyPI：打包与元数据已就绪（`pip wheel` 可用、readme/urls/classifiers 齐全），待配置 PyPI 账号 / Trusted Publisher 后首次上传
+- [ ] 更多产出语言：表驱动设计，新增一门语言 = 一张字符串表 + 一套模板（欢迎 PR）
+- [ ] CLI 交互消息中英双语（当前为中文，面向驱动它的 agent）
+
+## 贡献（Contributing）
+
+欢迎 issue 与 PR！本地开发：
+
+```bash
+git clone https://github.com/luomsis/repowiki.git && cd repowiki
+pip install -e '.[test]'
+pytest
+```
+
+- 行为变更请先开 issue 或去 Discussions 对齐方向，再动手；
+- 新增一门产出语言 = 一张字符串表 + 一套模板（见「设计取舍」），是很好的入门贡献点。
+
+## 社区
+
+- 问题、想法，或想晒一晒你生成的 wiki → [GitHub Discussions](https://github.com/luomsis/repowiki/discussions)
+- bug 与功能请求 → [Issues](https://github.com/luomsis/repowiki/issues)
+
+## 文档
+
+全部文档集中于 `docs/`（`zh/` 与 `en/` 镜像目录，同名文件一一对应）：
+
+- [版本日志](CHANGELOG.md)（[English](CHANGELOG.en.md)，位于仓库根部）
+- [领域词汇表](docs/zh/CONTEXT.md)（产出物 / 编排 / 执行三组术语与 Avoid 对照）
+- [决策记录](docs/zh/DECISIONS.md)（规格空白处的 15 条最小合理决策）
+- 架构决策记录（ADR）：[Windows 原生支持的双锁后端](docs/zh/adr/0001-windows-native-support.md) ·
+  [单文件离线站点](docs/zh/adr/0002-single-file-offline-site.md)
+- Agent Skill 指引：[中文](skills/repowiki/SKILL.md) · [English](skills/repowiki/SKILL.en.md)
+
+## License
+
+[MIT](LICENSE) © luomsis