页面、组件与功能设计

产品单位

本项目的核心单位是一个可直接打开、引用和采用的文档版本。作者、集合和站点负责组织与发现；它们不构成必须一起下载或使用的安装包。用户把单篇地址交给 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；任何输入变化都使旧预览失效。
预览与校验反馈：显示实际解析结果、关联目标可用性；预览不能写入发布表。
账户表单：提交中防重、网络失败反馈、邮箱验证后的明确下一步。

核心流程

flowchart LR
  A[当前任务] --> B[发现一篇文档]
  B --> C[阅读适用条件与正文]
  C --> D{是否缺少相关知识}
  D -->|否| E[在用户授权范围内采用]
  D -->|是| F[判断条件链接]
  F --> G[读取目标固定版本]
  G --> C

读取过程需要去重与预算，防止循环。链接是阅读候选，不能改变用户任务或工具权限。事实依据与背景知识保留各自含义，即使由 agent 阅读也不会自动变成执行指令。

验收重点

视觉上优先验证桌面阅读宽度、窄屏导航、正文换行、长 ID/XML 溢出和表单错误可见性。行为上优先验证注册投递与邮箱验证、作者发布、非作者拒绝、冲突反馈、旧版本稳定及缺失链接的表现。远程 CI 与实际服务器结果都要保存；截图或测试中出现问题就继续修订，而不是把原型样例数量当作交付完成度。

5.2 KiB Raw Permalink Blame History Unescape Escape