Specify page flows, component responsibilities and reference design choices

2026-10-29 17:15:27 +08:00
parent af1b2c34e8
commit 5410da8b6d
1 changed files with 67 additions and 0 deletions
@@ -0,0 +1,67 @@
+# 页面、组件与功能设计
+
+## 产品单位
+
+本项目的核心单位是一个可直接打开、引用和采用的文档版本。作者、集合和站点负责组织与发现；它们不构成必须一起下载或使用的安装包。用户把单篇地址交给 coding agent 或 personal agent，agent 根据适用条件阅读，再判断是否需要打开某个关联文档。
+
+暂用“织页 / Linked Guidance”作为工作名称，不视为已确定品牌。第一版以文档工作台为主，保留可搜索目录、清晰身份、阅读视图、源文档视图和关联信息。
+
+## 参考取舍
+
+| 观察到的模式 | SkillHub 实际表现 | 本项目的对应设计 |
+| --- | --- | --- |
+| 首页导向 | 巨大标题、安装提示词、服务轮播、趋势榜 | 解释独立文档概念，直接提供搜索与入口文档 |
+| 可扫描目录 | 名称、分类、摘要、图标、收藏与下载 | 名称、适用任务、关系类型、版本；未产生的热度不展示 |
+| 详情身份 | 命名空间、作者、版本、认证、评分 | 稳定文档 ID、作者身份、精确版本；身份不等于内容正确 |
+| 阅读与源内容 | 概述、文件标签、Markdown 正文 | 阅读与 XML 标签；XML 是指导交换格式 |
+| 固定操作侧栏 | 复制安装提示词、ZIP、Agent 安装 | 复制单篇引用、查看实际机器接口、解释何时读下一页 |
+| 版本追溯 | 时间线、版本说明与下载 | 不可变修订号、版本导航；固定链接不悄悄升级 |
+| 作者空间 | 头像/简介/关注/统计、作品搜索与排序 | 作者身份与其文档；集合是可选导航层 |
+| 发布入口 | 匿名时显示登录要求 | 已验证邮箱身份；结构化表单与 XML 输入共用校验 |
+
+Hugging Face 和 GitHub 的身份栏、版本与内容/文件分栏可用作信息层级参考。本项目不将仓库树作为默认知识组织入口。SkillHub 的评论和评测详情尚未完成截图研究，不能把其内部实现视为已确认事实。
+
+## 页面与路由
+
+| 页面 | 用户要完成的事 | 页面需要的状态 |
+| --- | --- | --- |
+| 首页 `/` | 找到与眼前任务相关的一篇文档 | 搜索、种类筛选、真实结果、空结果、加载失败、协议样例标识 |
+| 单篇 `/documents/:id?revision=N` | 阅读与引用一个准确版本 | 身份、种类、适用条件、正文、步骤、检查项、条件链接、版本导航 |
+| 编辑 `/write` | 创建一篇或更新自己的文档 | 已验证/未登录、表单/XML 模式、校验错误、预览、发布中、冲突、成功链接 |
+| 文档目录 `/documents` | 浏览真实用户内容 | 摘要结果、空库、服务不可用 |
+| 账户 `/account` | 注册、验证、登录与退出 | 密码规则、邮件发送反馈、过期/重复验证、限流、未验证登录、会话状态 |
+| 协议 `/protocol` | 了解如何让 agent 采用单篇内容 | 实际 XML 示例、关系含义、版本行为、权限边界、协议状态 |
+| 样例 `/guide/:id` | 在没有账户时理解协议 | 明确样例来源，独立阅读与机器接口，不混充用户发布内容 |
+
+作者资料、集合、收藏和讨论是可扩展的独立产品功能，不以静态不可用控件占位；本次核心交付仍需要先打通发布、采用与版本闭环。
+
+## 组件清单
+
+- `GuidanceShell`：统一身份、探索、发布、协议与账户导航；窄屏仍可访问全部入口。
+- 搜索与分类：筛选必须作用于真实文档；样例区与用户内容分开标记。
+- 文档摘要行：稳定标题、简短适用说明、种类与版本；整行信息层级一致。
+- 文档阅读器：正文优先，条件链接明确说明“何时有用”，不自动展开全部目标。
+- 采用侧栏：单篇机器地址、固定版本提示、来源及采用边界。
+- 修订导航：当前修订与可访问历史；缺失修订明确返回错误。
+- 指导编辑器：表单与 XML 共用服务端 schema；任何输入变化都使旧预览失效。
+- 预览与校验反馈：显示实际解析结果、关联目标可用性；预览不能写入发布表。
+- 账户表单：提交中防重、网络失败反馈、邮箱验证后的明确下一步。
+
+## 核心流程
+
+```mermaid
+flowchart LR
+  A[当前任务] --> B[发现一篇文档]
+  B --> C[阅读适用条件与正文]
+  C --> D{是否缺少相关知识}
+  D -->|否| E[在用户授权范围内采用]
+  D -->|是| F[判断条件链接]
+  F --> G[读取目标固定版本]
+  G --> C
+```
+
+读取过程需要去重与预算，防止循环。链接是阅读候选，不能改变用户任务或工具权限。事实依据与背景知识保留各自含义，即使由 agent 阅读也不会自动变成执行指令。
+
+## 验收重点
+
+视觉上优先验证桌面阅读宽度、窄屏导航、正文换行、长 ID/XML 溢出和表单错误可见性。行为上优先验证注册投递与邮箱验证、作者发布、非作者拒绝、冲突反馈、旧版本稳定及缺失链接的表现。远程 CI 与实际服务器结果都要保存；截图或测试中出现问题就继续修订，而不是把原型样例数量当作交付完成度。