导出与维护 Zread 仓库 Wiki
保存 zread.ai 当前可访问的完整正文,一章一文件,以 index.md 导航并用本地 Git 保存历史。不摘要、翻译或重新生成正文来补齐失败章节。
保存位置与用户配置
- 接受 GitHub URL、
owner/repo或 Zread 仓库/章节 URL。章节 URL 仍表示整库导出,除非用户明确缩小范围;没有仓库身份时才询问。 - 保存根目录的优先级:本次明确指定的根目录 → 用户级
~/.agents/zread-wiki-export.json中的export_root。该文件是 UTF-8 JSON 对象,export_root必须是本机绝对路径字符串。按当前用户的主目录定位,不依赖 App 的安装目录或当前项目的.agents/。 - 没有配置文件或没有
export_root,且本次未指定根目录时,询问保存根目录,并说明确认后会记为后续默认值。只在用户确认设置或明确要求更改默认值时写入;保留配置中的其他字段。本次临时路径不覆盖已有默认值。 - 配置无法读取、JSON 无效、路径不合法或保存位置不可访问时,报告实际原因;不能当作首次使用悄悄重置配置,也不换到其他默认目录。遵守当前环境的存储与访问规则。
- 仓库固定保存到
<export_root>/<owner>/<repo>/,更新时沿用此目录,不再为每轮创建时间目录。每个 Agent App 使用时都需读取这项约定;共享文件不代表获得其他 App 的访问权限或自动同步 skill 版本。
文档库与 Git
- 首次创建文档库时,在上述仓库目录执行
git init。核对 Git 根确实是该目录,不能误用祖先目录的 Git 仓库。已有内容先核对来源与归属,不自动接管未知文件或迁移旧时间目录。 - 写入前检查 Git 状态、暂存内容及提交身份。保留用户已有改动;归属不清时先说明并询问,不自动 stash、reset 或夹带提交。同一文档库由一个任务写入,不并行改写。
- 只纳入本轮归属明确的索引、正文和资源。提交前核对完整暂存差异和提交路径,不能用全目录暂存或提交把其他内容带入历史;不配置文档库远端,也不自动推送。
- 每轮采集、更新或续导收尾时,有实际变化才提交一次。提交说明记录仓库、可见源索引版本、成功/总章节数及完整或部分完成;目录覆盖未知时如实标明。没有变化只报告检查结果,不刷新时间戳制造差异,不创建空提交。
- 失败或中断后保留进度;正常收尾时可将部分成果和失败记录提交为
partial检查点。强制中断不能保证已提交,下次先核对文件与索引,将归属明确的上轮未提交成果补交为检查点,再开始会覆盖旧采集内容的更新。Git 提交失败时保留文件并停止后续覆盖,分别报告采集结果和提交错误;不伪造身份、不绕过 hooks 或签名要求。
索引与文件归属
index.md 是章节清单、文件映射与进度的唯一维护入口,记录:
- 仓库、Zread 入口、正文语言、有实际变更时的采集时间及时区、本轮目标的站点索引日期/commit;未提供的来源标记如实注明。导出时间和本地 Git commit 不能代替站点版本。
- 各章节的顺序、层级、标题、源 URL、本地文件链接、状态和失败原因;状态仅使用
pending、saved、failed。只有正文落盘并通过身份、内容及资源核对后才能标为saved。 - 每个受管理正文和本地图像资源的路径及最后一次验收文件的 SHA-256。完成链接改写后计算并更新哈希;它用于识别此后发生的人工修改,不能代替与站点正文的比对。
以实际章节 URL 识别章节,沿用已有 URL 到文件的映射;新增章节使用 URL slug 命名,目录顺序仅记录在索引中,不因重排而重命名已有文件。每章包含标题、源 URL、实际来源索引标记和完整正文。
写入或删除已有受管理文件前,与索引中的上次验收哈希核对。哈希不符或归属不明的文件保留,新采集内容另存为不冲突的文件并更新索引映射,不覆盖用户正文或图像。Git 中已有历史不构成覆盖用户改动的授权。
访问与完整目录
使用当前环境可用的浏览器自动化能力并遵循其操作指引,复用同一浏览器会话与页面。先观察页面,再以链接、按钮及实际 DOM 定位。专用读取入口只有在返回同一 Zread 原文、且身份、语言、来源版本和覆盖面可核对时才可使用。
- 打开
https://zread.ai/<owner>/<repo>,核对仓库身份。若进入搜索页,用页面上的仓库搜索入口找到匹配仓库;不固定未经观察的输入框文案或选择器。 - 需要登录时交给用户完成,随后恢复同一任务,不记录凭据或登录跳转参数。区分可读 Wiki、未索引、排队和错误页;未索引时仅在已有生成/索引授权的情况下提交一次,不重复生成或点击刷新仓库。按用户时限等待,无时限则观察至多 10 分钟后报告状态与恢复入口。
- 504、访问限制或生成失败先定位原因,检查状态后最多手动重试一次;仍失败则停止受阻部分。错误页不能保存为正文,也不能作为页面结构改变的证据。
- 从左侧目录收集真实章节,不从正文引用猜测。展开折叠组,检查目录自身滚动区域;虚拟化目录须逐屏累计到末尾且无新增条目,不能只取最后一屏 DOM。记录层级、顺序、标题和 href,仅保留目标仓库章节并按真实链接去重。
- 比较根页标题、激活项和规范链接,将根页与对应概述章节合并。首次导出在保存正文前将完整清单落到索引,状态为
pending;续导保留已有进度。发现新分组或章节时补入同一清单,结束前再核对目录覆盖,不能把未展开的目录声称为完整。
提取、更新与恢复
逐章提取前读取 提取方法与修复流程 及随包的站点知识。后者维护已观察的选择器、数据结构与可选读取工具,不要求其他浏览器安装特定工具。优先公开页面自身的原始 Markdown,其次是从实际文章 DOM 转换;保留代码、表格、源码引用、Mermaid 和可取得的图像。保持站点正文语言,只在用户要求时切换语言。
- 每次跳转等待目标标题与正文加载完,核对 URL/激活项后提取,防止把上一章重复保存。逐章验收并落盘,再更新同一索引;正文已保存但图表或结构缺失时仍为
failed。 - 续导或更新先核对已有索引、文件和当前站点目录。来源标记相同,只能复用回读后仍与当前章节一致的
saved文件;继续处理pending和failed。缺文件或核对失败需记录原因并补齐,不能凭文件存在或工具退出成功验收。 - 站点索引日期/commit 或正文语言变化时,仍在固定目录更新,以 Git 保留旧版。先将旧版状态对新目标置为
pending,保留旧文件及其来源标记;新内容验收通过后才替换未被用户修改的文件并标为saved。未更新的旧正文不能计入新版本成果,部分更新须在索引中说明。 - 站点未提供版本标记时,逐章对照当前正文后再复用,并说明不能确认同一索引版本。仅来源标记、正文、目录、资源或真实进度发生变化时修改文件;无变化检查保留原采集时间。
- 核全新目录后,移除不再属于当前目录的旧章节索引项;只删除仍匹配上次验收哈希的自有旧正文和不再被其他章节引用的自有资源。用户修改过的文件保留并说明,历史原文仍可从 Git 恢复。
- 保存后将已成功导出章节之间的链接改为实际本地相对路径;核对锚点,无法保证时保留源链接。失败或未导出目标及其他链接保持绝对源 URL,不制造无效本地链接。
提取规则变化与共享修复
允许在当前授权访问范围内探索页面 DOM、公开 HTML 数据、公开文档化 API,以及当前页面实际发出的读取请求,以定位结构或接口变化。先区分访问故障与提取方法失效;不探测未授权接口、不提取凭据,也不为导出安装本地文档生成工具。
验证新方法后,可更新受维护且可写的本地 skill 源码和提取引用文档,保留通用获取方法、适用条件、验证覆盖与限制。不能通过改写来源边界或降低正文验收标准消除失败。具体探索、落位及验证步骤见同一提取引用文档。
向 skill 来源仓库分享修复时,先准备独立分支、补丁、必要版本更新和验证结果,向用户展示目标仓库与可审阅差异,明确征得创建该 PR 的同意后才创建。不把本地路径配置、凭据、用户导出正文或文档库 Git 历史带入 skill PR;本地文档提交不等于远端发布授权。
验收与交付
- 完整目录中每个独立章节都必须有身份正确、内容与资源已核对的正文;对照成功数、总数、失败项和文件存在性,排除登录/错误/加载页面。
- 回读首章、末章及含表格、代码和图表的代表章节;检查首尾完整、代码换行、本地资源与章节链接,结构或图表缺失计为部分完成。
- 只报告实际核对的范围与来源版本,不能声称反映仓库最新代码;来源标记在采集中变化时重新按当前目标核对,不能把不同版本的
saved状态混算。 - 交付
index.md的绝对路径链接、成功/总章节数、完整或部分状态、失败/缺失项、远程图片依赖及其他阅读限制,并报告本轮 Git commit,或无变化/提交失败的实际原因。 - 结束自己创建的浏览器资源,保留用户原有标签页。未经用户同意不创建共享修复 PR。
- Downloads
- Security audit
- Review
- Last updated
- 1w ago
- Current version
- v0.4.0
- License
- MIT-0
