write-repowiki
/write-repowiki
Generuje lub utrzymuje wiki repozytorium w formacie Qoder, w tym karty wiedzy i synchronizację z kodem.
- Autor
- liushikuan63 ↗
- Repozytorium
- Qoder-Optimization ↗
- Licencja
- MIT
- Ostatnia zmiana repozytorium
- 11.11.2026
Ocena i bezpieczeństwo
- Pliki w paczce
- 3
- Skrypty
- 2
- Komentarze HTML
- 0
- Adresy URL w SKILL.md
- 0
Brak sygnałów. Repozytorium zmienione 11.11.2026, bez odwołań do wycofanych modeli i API.
MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.
- 2 skrypty w paczce. Przejrzyj je przed instalacją, bo Claude może je uruchomić.
Skrypty: scripts/fix-repowiki-toc.js, scripts/validate-repowiki.js
Co robi i kiedy
Generuje lub utrzymuje wiki repozytorium w formacie Qoder, w tym karty wiedzy i synchronizację z kodem.
Wyzwalacze z opisu
Oryginalny opis (EN)
按 Qoder 标准格式生成或维护仓库 wiki(.qoder/repowiki/)。当任务要"先查 wiki 再动手""给仓库建/补/改 wiki""代码改了要同批回写 wiki"、或多写手并行写长文档时使用。关键词:repowiki、仓库 wiki、知识卡、wiki_plan、四层结构、回写 wiki、wiki 与代码冲突、knowledge-plan、/knowledge。
Jak działa
- 何时用 / 不用
- 官方生成器与面板(有官方通道,别手搓)
- 四层结构(缺一不可)
- 内容页格式契约(每页必须满足)
- 生成流程(无 wiki → 建库)
- 校验与修复(机器判据,别靠通读)
- 维护既有 wiki(有 wiki → 更新)
- 反模式(会直接判红)
Podgląd SKILL.md
--- name: write-repowiki description: 按 Qoder 标准格式生成或维护仓库 wiki(.qoder/repowiki/)。当任务要"先查 wiki 再动手""给仓库建/补/改 wiki""代码改了要同批回写 wiki"、或多写手并行写长文档时使用。关键词:repowiki、仓库 wiki、知识卡、wiki_plan、四层结构、回写 wiki、wiki 与代码冲突、knowledge-plan、/knowledge。 --- # 生成与维护 repo wiki(`.qoder/repowiki/`) ## 何时用 / 不用 - **用**:仓库已有 `.qoder/repowiki/`(先查再动手、改完回写);要新建 wiki;要按官方四层标准补知识卡或内容页。 - **不用**:只是想在对话里解释一段代码——那直接读码回答,别为了"留痕"建 wiki。 ## 官方生成器与面板(有官方通道,别手搓) - **CLI**:`qoder wiki`(可多选项目);**IDE**:`/knowledge`(生成 / 修改 / 补充 / 重写)与 `/knowledge-plan`(定制生成策略);**面板**:Generate / Update / Sync 三键。 - **手改内容会被标记保护并反向同步**——"手写 + 官方生成器"两条路可以并存,不必怕手改被覆盖;但要让面板呈现"生成态",需跑一次官方生成器。 - **结构细节的权威出处**:随包官方技能 `qoder-context-knowledge-plan`(`documents` 上限、`scope` 未实现等都在其内);公开说明见 `docs.qoder.com/zh/user-guide/repo-wiki` 与 `docs.qoder.com/zh/cli/repo-wiki`。**本技能与校验脚本的口径以该官方技能为准**——它是会变的,冲突时信它。 ## 四层结构(缺一不可) ``` .qoder/repowiki/ ├── wiki_plan.yaml # 项目范围 / 模板 / notes(章节地图) ├── knowledge/zh/_index.yaml # 模块索引:dir_name, title, scope, children, depends_on, related_to ├── knowledge/zh/<模块>/ # 每模块知识卡:_module.yaml + 概述.md + 技术栈.md + 架构设计.md + 编码规范.md + 特殊配置与命令.md └── zh/content/<章节>/<页>.md # 面向"上手/查资料"的长文页(按功能主题分层) ``` - `wiki_plan.yaml`:**别写 `scope` 块**——`scope.include/exclude` 当前版本**未实现**,解析后只告警然后忽略(本条已对官方技能 v1.0.42 逐字核对)。有用的是 `template`(如 `architecture`)与 `notes`(章节地图)。 - 硬上限(超出**静默截断**,不报错):`notes` ≤ 50 条、单条 ≤ 10000 字符;`documents` ≤ 50 页 / 顶级 ≤ 12 / 每个顶级 ≤ 8 子页。 - `documents` 是**白名单 = 上限**:需要更多页或两级子目录时**正确做法是删掉整块 `documents`**,改用 `notes` 写"章节地图"(固定一级章节名单、允许两级子目录、每个目录有同名索引页、新页必须被本目录索引页提及),并让校验脚本切"无白名单模式"。 - `zh/meta/repowiki-metadata.json` **不要手写**(工具生成物,含 repo_id / 加密 blob);手写权威面 = `wiki_plan.yaml` + `knowledge/` + `zh/content/`。 - 知识卡 schema:`_index.yaml` 的模块键须与各 `_module.yaml` 的 `module_path` 一致;独立卡放 `<标题>/<标题>.md`,frontmatter 必含 `kind/name/category/scope`,`category` 取 overview / architecture_design / tech_stack / coding_conventions / unique_setup_and_commands / configuration_system / dependency_management / logging_system / error_handling / build_system / frontend_style / business_term。 ## 内容页格式契约(每页必须满足) - 顶部 `<cite>` 块列出引用文件(`file://` 相对路径 + **`#Lx-Ly` 行号**)。 - `## 目录` 章节 + 正文 + mermaid 图表;每章节末尾 `**章节来源**` / `**图表来源**`。 - **目录锚点按 github-slugger 语义算**:小写 → 去标点(保留 `_`、`-`、字母数字与 CJK)→ **每个空格替换为一个 `-`(不折叠连续空格)**。所以 `## 症状 B:点了没反应 / 没有报错` → `#症状-b点了没反应--没有报错`,**双横线是对的**。 - 这条有实测依据:用官方 `github-slugger` 对 6314 个真实标题逐条比对,唯一容易写错的就是"连续空白要不要折叠"——折叠会一次性误报几十处。**别自己发明锚点规则**,算错就批量错。 - 长度:知识卡 200–400 B 量级(概述 / 技术栈本就短,别套正文阈值)。 ## 生成流程(无 wiki → 建库) 1. **交付三件套先就位**(见 `rules/doc-authoring.md`):`_FACTS.md`(已核验事实 + `路径:行号` + 冲突裁决)、`_AUTHORING.md`(格式契约 / 禁编造清单 / 凭据一律 `<redacted>`)、**校验脚本**(见下)。 2. **先读码后落笔**:模块划分按代码事实(入口文件、依赖、路由、表结构),不按"应该有什么";每个事实带 `file://...#Lx-Ly`。 3. **多写手并行**:每个写手 **≤10 个文件**、独占目录,prompt 明写"边写边落盘,不要先通读";共享索引页与跨目录登记**由主会话写**,写手禁改。写手异常退出后**先做差集**(已落盘 vs 应产出)再补缺口,**禁止整批重跑**。 4. **事实传播**:写手回报的分歧当线索不当结论,主会话亲自复验(`grep -c`、`wc -l`、看分支常量)再定性;结论定了按"事实源 → plan notes → 知识卡 → 各页"四处传播,改完 grep 复查旧说法残留。 5. **收尾**:跑校验脚本全绿 + 抽查读码;汇报区分"已落地并验证"与"未做 / 未验证"。 ## 校验与修复(机器判据,别靠通读) 两个脚本**随本技能分发**(在技能目录里,不在 `~/.qoder/scripts/`): ```bash node ~/.qoder/skills-library/write-repowiki/scripts/validate-repowiki.js <repo 路径> # 只读,退 0/1/2 node ~/.qoder/skills-library/write-repowiki/scripts/fix-repowiki-toc.js <repo 路径> # 只报 node ~/.qoder/skills-library/write-repowiki/scripts/fix-repowiki-toc.js <repo 路径> --apply # 落盘(逐文件备份 .bak-<时间戳>) ``` - `validate-repowiki.js` 查七项:`wiki_plan.yaml` 顶层键(`version` / `repowiki` / `knowledgecard` —— **不含 `scope`**)、四层目录、代码围栏闭合、内链可达、`#Lx-Ly` 行号、疑似明文凭据、plan↔磁盘一致;另查 YAML 两个真实坑(tab 缩进、双引号标量里嵌引号)。 - `fix-repowiki-toc.js` 按 slug 反查改写目录锚点(归一化后**唯一命中**才自动改,其余只报交人工);`--apply` 才落盘。解析规则与 validate 逐字一致(`file://x` 与 `/x` 都是仓根相对,普通相对链接才按当前文件所在目录解析)——**两处口径漂移会出现"一个说红一个说绿"**。 - **读数口径(实测标定,别自己猜)**:行号锚点分三类——合法(查越界/倒置)、**`#L1-Ln` 整文件写法**(`n` 超行数时锚点仍能打开文件 ⇒ **降级为计数说明,不算问题**,否则一次刷出 160+ 条噪声)、**写法残缺**(如 `#L31-L...`,既不是合法行号也不是标题,两边检查都会漏,故显式报)。一次真语料基线(366 页):526 悬空内链 + 8 切片越界 + 76 残缺行号锚点 + 164 整文件锚点降级——**判断"是不是我改坏的"全靠先跑一次留基线**。 - 无白名单模式:校验"章节名单合规 / 索引页存在 / **每页被本目录索引页提到**(防孤儿页)"。 - **改前先备份**:重写整套 wiki 前先在 `.qoder/` 下做 `repowiki.bak-<date>` 快照(顺带清理快照里的明文口令)。 ## 维护既有 wiki(有 wiki → 更新) - **随时回写**:代码改动后同批更新受影响的知识卡 / 内容页(引用行号变了要一起改);文档不同批更新就会变成"第二真相"。 - **被取代的旧页用隔离而非删除**:`mv` 到 `.qoder/_backups/<工程>-repowiki-superseded-<date>/<章节>/`,汇报里给可恢复路径。 - 新增页:先看本目录索引页格式,登记进索引页与 `_index.yaml`,再补 `<cite>`。 - 报告"已完成"前必须能说明:本轮跑了哪个校验命令、退出码、覆盖面。 ## 反模式(会直接判红) - ❌ 用 `documents` 白名单硬顶页数(超出静默截断,看不出来)——要更多页就删整块,改用 notes 章节地图。 - ❌ 手写 `zh/meta/repowiki-metadata.json`,或把 `scope.include/exclude` 当生效配置写进 plan。 - ❌ 页面没有 `<cite>` / 行号写错 / 锚点自己发明规则 / 引用指向不存在的文件。 - ❌ 多写手整批重投(覆盖已完成页并引入新幻觉)——先做差集。 - ❌ 只删旧页不隔离(无法回溯),或重写前不打快照。 - ❌ 把未核验的推断写成事实("应该是…"),或把凭据 / 内网地址写进页面。
Pliki w paczce (3)
- SKILL.md 9 KB
- scripts/fix-repowiki-toc.js 7 KB
- scripts/validate-repowiki.js 11 KB
Wersje
W bazie nie ma innych skilli o nazwie write-repowiki.
Migawka bazy z 13.11.2026 · wersja paczki c6ed6d39a0d4 (skrót SHA-256 całej paczki)
Pobrania w ostatnich 30 dniach: 0 · ranking
Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.
Podobne skille
- 100wiki-generation
Analizuje repozytorium i generuje lub przyrostowo aktualizuje wiki zrozumiałą dla agentów AI, czyli dokumentację kodu. - 100wiki-keeper
Utrzymuje wiki zespołu zgodną z kodem, aktualizując strony przed commitem i przy zmianach struktury projektu. - 100docs-wiki
Prowadzi wiki dokumentacji w formacie Open Knowledge: dodaje i przenosi strony, aktualizuje je po zmianach w kodzie i odpowiada na pytania z dokumentów. - 100wiki-keeper
Utrzymuje wiki zespołu zgodną z kodem, aktualizując strony przed commitem i przy zmianach struktury projektu. - 100wiki
Odbudowuje wiki projektu ułożone wokół przepływów przy użyciu serwera MCP mimirs, także w trybie odświeżenia. - 100code-mate-qoder
Uruchamia Qoder CLI nieinteraktywnie ze strukturalnym wynikiem, gdy użytkownik chce przekazać zadanie programistyczne do Qodera.