68 lines
5.2 KiB
Markdown
68 lines
5.2 KiB
Markdown
# 页面、组件与功能设计
|
||
|
||
## 产品单位
|
||
|
||
本项目的核心单位是一个可直接打开、引用和采用的文档版本。作者、集合和站点负责组织与发现；它们不构成必须一起下载或使用的安装包。用户把单篇地址交给 coding agent 或 personal agent，agent 根据适用条件阅读，再判断是否需要打开某个关联文档。
|
||
|
||
暂用“织页 / Linked Guidance”作为工作名称，不视为已确定品牌。第一版以文档工作台为主，保留可搜索目录、清晰身份、阅读视图、源文档视图和关联信息。
|
||
|
||
## 参考取舍
|
||
|
||
| 观察到的模式 | SkillHub 实际表现 | 本项目的对应设计 |
|
||
| --- | --- | --- |
|
||
| 首页导向 | 巨大标题、安装提示词、服务轮播、趋势榜 | 解释独立文档概念，直接提供搜索与入口文档 |
|
||
| 可扫描目录 | 名称、分类、摘要、图标、收藏与下载 | 名称、适用任务、关系类型、版本；未产生的热度不展示 |
|
||
| 详情身份 | 命名空间、作者、版本、认证、评分 | 稳定文档 ID、作者身份、精确版本；身份不等于内容正确 |
|
||
| 阅读与源内容 | 概述、文件标签、Markdown 正文 | 阅读与 XML 标签；XML 是指导交换格式 |
|
||
| 固定操作侧栏 | 复制安装提示词、ZIP、Agent 安装 | 复制单篇引用、查看实际机器接口、解释何时读下一页 |
|
||
| 版本追溯 | 时间线、版本说明与下载 | 不可变修订号、版本导航；固定链接不悄悄升级 |
|
||
| 作者空间 | 头像/简介/关注/统计、作品搜索与排序 | 作者身份与其文档；集合是可选导航层 |
|
||
| 发布入口 | 匿名时显示登录要求 | 已验证邮箱身份；结构化表单与 XML 输入共用校验 |
|
||
|
||
Hugging Face 和 GitHub 的身份栏、版本与内容/文件分栏可用作信息层级参考。本项目不将仓库树作为默认知识组织入口。已补截评论与评测详情：评论采用独立卡片、热门/最新排序、点赞与回复；评测采用 TRACE 五维说明、雷达图、综合评级和分项进度条。两者的证据来源不同，不能将自动评分直接视为实际任务成功率。
|
||
|
||
## 页面与路由
|
||
|
||
| 页面 | 用户要完成的事 | 页面需要的状态 |
|
||
| --- | --- | --- |
|
||
| 首页 `/` | 找到与眼前任务相关的一篇文档 | 搜索、种类筛选、真实结果、空结果、加载失败、协议样例标识 |
|
||
| 单篇 `/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 与实际服务器结果都要保存；截图或测试中出现问题就继续修订，而不是把原型样例数量当作交付完成度。
|