Skip to content

Issue 28

Jump to bottom
clean edited this page Sep 17, 2026 · 2 revisions

Issue #28：产品 README 与文档入口重构

背景与目标

原 README 将开发、打包、发布、更新机制和历次验收说明混排，首次访问者难以找到产品用途和安装入口。本次按 Issue 提出的 LobeHub 产品展示方向，以居中标识、简明介绍、真实截图、功能表、下载和快速上手组织中文首页。

不改变应用行为，不新增多语言文档；功能介绍只覆盖当前实现，Worktree 限于打开已有工作区，AI 为可选功能。

内容组织与文档归属

内容 最终入口
品牌标识、用途、六项核心能力、平台下载和四步上手 根 README
从源码运行、桌面构建、图标维护、测试和发布前验收要求 docs/development.md
安装条件、更新机制、桌面行为、数据目录和旧库迁移 docs/desktop.md
提交历史、Worktree、Diff、布局与快捷键 docs/workspace.md
AI 服务商、模型、密钥和数据范围 保留 docs/ai-settings.md
提交规范、hooks、发布流程和安装附件要求 CONTRIBUTE.md
设计、实际验收记录、截图与附件 继续仅在 Wiki 维护

同步更新 docs/README.md 和贡献指南，保留 Issue 模板、公开 TODO、Wiki 分类索引与 #25 迁移清单的入口。移除 README 中“仓库仍为私有”的过时表述，下载指向稳定的 releases/latest，不写死版本号。

直接复用既有 Wiki 实机验收素材，不重新生成演示界面或在代码仓库复制附件：

两张图均使用隔离测试数据，README 明确说明截图版本与实际安装版本可能不同。

验收标准

  • 首页包含产品标识、简明介绍、核心功能、界面截图、下载和快速上手。
  • 功能与当前源码一致，不将 TODO 描述为现有能力；未宣传尚未接通的 SSH Agent 认证或 Worktree 创建/删除。
  • 开发、发布、更新与详细操作说明迁至专门文档，首页保留有效入口。
  • 保留贡献指南和 TODO 看板，与 #25 的文档归属衔接。
  • 本地链接、锚点、截图与下载入口检查通过；GitHub Markdown API 渲染结构正常。

验证记录

日期均为 2026-09-17；环境为 macOS arm64、Node.js 25.5.0。

命令或场景 实际结果
npm ci --no-audit --no-fund 通过；使用锁定依赖，保留原有 hooks 配置
npm run build -w @remote-git/shared、npm run build -w @remote-git/ssh-client、npm run build -w server 通过
GitHub POST /markdown，mode=gfm 返回 HTML；品牌图标、6 个二级章节、3 个表格、2 张截图、折叠区和 4 个上手步骤保留
检查 7 个改动文档中的相对链接与锚点 40 处引用通过
HTTP 检查文档链接、截图、TODO、Issue 模板与下载入口 19 个唯一外部 URL 均返回 HTTP 200
GitHub Release API 最新稳定版 v0.3.0 公开可用；arm64/x64 DMG、Windows x64 EXE、Linux x86_64 AppImage 与 SHA256SUMS 名称匹配安装表
快速上手 API 流程 通过，下述 5 步均使用隔离的真实 Git 和回环 SSH
Prettier 检查 README 及 docs 中的 5 个改动文件；git diff --check 通过

快速上手验证使用仓库已有 startSSHServer 测试辅助工具和生产 NestJS 服务：创建临时仓库与数据目录，配置测试作者，服务和 SSH 均绑定 127.0.0.1 随机端口，完成后关闭服务并清理临时目录。执行顺序：

  1. POST /connections 保存演示密码连接，POST /connections/:id/test 返回成功。
  2. GET /repositories/scan 找到新建的测试仓库，POST /repositories 登记成功。
  3. 修改测试文件，GET /repositories/:id/status 与 /diff 返回对应改动。
  4. POST /repositories/:id/stage 暂存文件，POST /repositories/:id/commit 提交；用 Git 命令核对提交摘要和干净工作区。
  5. GET /repositories/:id/log 包含刚创建的提交。

验证边界与回退

  • 按用户要求优先接口，全程未调用 ego-browser 或其他浏览器自动化；未进行逐像素视觉比对或浏览器点击验收。
  • LobeHub 指定页面与 README 的 HTTP/API 读取在本次环境返回 404，因此按 Issue 中明确的产品首页结构方向组织，没有宣称与当前 LobeHub 页面逐项对照。
  • 未安装各平台发布包、未执行真实升级、未连接用户服务器或调用真实 AI 服务；这些不是本次纯文档改动的回归范围。
  • 首次在未安装依赖的 worktree 编译时误用上层 TypeScript，出现版本弃用诊断；执行本页记录的 npm ci 后三项构建均成功，未更改应用或依赖版本。
  • 代码变更仅涉及 7 个 Markdown 文件。回退代码提交后需另行核对 Wiki 修订和 Issue / PR 链接。

关联资料

设计文档首页 · 维护约定 · 代码仓库

RemoteGit

Clone this wiki locally