Record confirmed SMTP delivery and current main CI evidence

docs/linked-guidance/acceptance.md

@@ -0,0 +1,33 @@
+# 交付验收清单
+
+这是要求与证据的对照表，不能用提交、PR 或测试意图代替实际验收。所有 PR 由用户手动合并。构建只使用 ces-control，网页只在指定服务器验收。
+
+| 用户要求 | 应验证的行为 | 当前证据 / 待办 |
+| --- | --- | --- |
+| 研究 LLM Wiki | 能指出原始提案与本项目新增设计的边界 | protocol.md 引用 Karpathy 原始 gist；XML、条件链接和版本规则为本项目提案 |
+| SkillHub 逐页截图与设计分析 | 首页、目录、详情各标签、作者、登录、发布入口具备截图和观察记录 | 主 chat 已截取首页首屏与下半屏、目录、概述、文件、版本、评论、评测、登录、作者及发布限制；另补插件、SkillPay、大赛、使用指南、专家包列表/详情与企业专区首屏；截图目前在 chat 中，窄屏参考待补 |
+| 可独立使用的文档 | 单篇内容具有适用条件、正文和步骤，不要求安装包 | catalog.ts 与 /guide 原型；真实文档实现已随 PR #9 合入，待 CI 与运行时验证 |
+| 按链接寻找帮助 | 条件、关系、精确版本可读，缺失目标明确，背景不升级权限 | 协议及静态阅读页；真实文档预览与链接解析待 PR #9 验证 |
+| 新语法 | XML 可序列化、校验、往返，拒绝未知协议与非法实体 | 原型 XML 输出已合入；严格输入与往返测试已随 PR #9 合入，远程执行待确认 |
+| 基于现有 wiki 改造 | 沿用 Pages Router 与现有部署数据 | main 已包含新首页原型，实际服务仍在旧版本，等待 CI 部署 |
+| 保留旧小红书 UI | 旧首页和组件仍可在代码库找到，新入口不再使用 | src/legacy/WaterfallHome.tsx 以及原 ExploreFeed/Shell 保留；部署后需检查新首页 |
+| 邮箱与密码登录并验证邮箱 | 注册发信、验证一次消费、未验证不能登录、会话可注销 | #6/#8 已由用户合并；SMTP 配置、TLS 登录及诊断邮件实际投递已验证；实际注册、验证和登录待部署 |
+| 正常用户与管理员隔离 | 普通邮箱 cookie 无法授权旧管理写 API | auth.test.ts 与 account-integration.ts；最终 main CI 结果仍待确认 |
+| 真实发布与版本 | 已验证作者能发布和更新，其他人不能覆盖，旧版本不变 | PR #9 的 PostgreSQL 所有权/并发/撤下保留测试，待远程执行与网页验证 |
+| 独立开发与人工合并 | 每个方向独立分支和可评审 PR | #6/#7/#8/#9/#11/#12/#13/#14/#15/#16 已由用户合并；#10 待最终证据完善；所有 merge 由用户完成 |
+
+## SMTP 验收边界
+
+配置已写入服务器 root 所有、0600 权限的 /etc/prompt.env。密码不在仓库、PR 或 CI 日志中。SMTP_SSL 证书验证、连接与认证已通过。2026-10-29 10:23 UTC 发送诊断邮件 LG-SMTP-20261029-01，SMTP 接受；随后通过 Gmail 定向检索确认该编号邮件位于指定测试收件箱的 INBOX、UNREAD、CATEGORY_PERSONAL，非垃圾邮件。诊断邮件不含验证链接；这不证明注册流程已经完成。生产服务尚未因配置而手动重启，等待正常 CI/CD 部署。
+
+## 当前未完成工作
+
+补齐窄屏参考及验收截图；完成当前 main 的远程 CI（仅 main 更新触发，PR/手动不触发）；其余 PR 由用户手动合并；等待正常部署；在服务器上测试邮箱注册验证与文档发布、编辑、精确版本及关联阅读；记录桌面与窄屏效果。只有运行时证据齐全后才认定完整交付。
+
+## Agent 发现入口
+
+PR #12 将 llms.txt 与 /agent/index.md、/index.md 导向独立指导文档，索引同时包含持久化用户文档与示例，并只公开 GET/HEAD。测试覆盖发现入口、预算与固定版本链接；已由用户合并；远程 CI 和部署验收尚未完成。
+
+## 最近的 main CI 证据
+
+run 504（main 1925d15）类型检查、50 项单元测试与生产构建通过，随后 smoke 因缺管理员配置返回 503 而失败；不代表完整 CI 通过。PR #16 仅给绑定回环地址的 smoke 子进程设置显式测试模式，已由用户合并。main 254ac62 的后续检查仍待完成；未在本机编译，未手动触发构建。

docs/linked-guidance/design-system.md

@@ -0,0 +1,67 @@
+# 页面、组件与功能设计
+
+## 产品单位
+
+本项目的核心单位是一个可直接打开、引用和采用的文档版本。作者、集合和站点负责组织与发现；它们不构成必须一起下载或使用的安装包。用户把单篇地址交给 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 与实际服务器结果都要保存；截图或测试中出现问题就继续修订，而不是把原型样例数量当作交付完成度。

docs/linked-guidance/product-plan.md

@@ -2,9 +2,9 @@
 
 ## 研究状态（2026-10-29）
 
-已阅读 Karpathy LLM Wiki 原始提案，检查用户提供的 Hugging Face Qwen 页面与 GitHub Chromium 页面。已通过 Chrome 截取 SkillHub 首页、目录、详情概述三个画面，读取文件树状态；截图显示在主 chat 工具结果中，未导出为仓库图片。文件页截图请求超时。研究仍未覆盖所有页面，不宣称已完成逐页分析。
+已阅读 Karpathy LLM Wiki 原始提案，检查用户提供的 Hugging Face Qwen 页面与 GitHub Chromium 页面。已通过 Chrome 逐项截取核心页面与状态，具体记录见下文。截图显示在主 chat 工具结果中，未导出为仓库图片；未覆盖整个网站，发布编辑器受实名限制。
 
-待采集：SkillHub 首页首屏和下半屏、搜索与筛选、技能详情、文档/文件视图、作者页、登录入口、发布入口、移动视图；逐页记录实际 URL、截图、布局、控件、交互和对本项目的取舍。无法匿名访问的页面明确注明登录限制，不冒充已检查。
+已采集：首页首屏与下半屏、目录筛选布局、技能详情全部五个标签、企业作者页、登录弹窗、发布访问限制。移动视图尚未采集，已验证分类筛选和搜索空结果，其他筛选组合尚未完整遍历；无法访问的页面明确注明限制，不冒充已检查。
 
 Hugging Face 可借鉴：owner/name 身份、标签、概览与文件/社区分栏、主内容加元数据侧栏。GitHub 可借鉴：稳定地址、版本历史、README 阅读层级、文件和讨论分离。这里应把“单篇文档”放在中心，集合只是可选组织方式；不复制仓库文件树为强制入口。
 
@@ -17,7 +17,7 @@ Hugging Face 可借鉴：owner/name 身份、标签、概览与文件/社区分
 | /protocol | 展示 0.1 约定与使用边界 | 语法示例、读取流程、协议状态 |
 | /account | 注册、验证邮箱、登录、退出 | 表单、错误反馈、会话状态 |
 | 作者与集合 | 后续真实用户内容组织 | 作者简介、非强制集合、收藏 |
-| 编辑与历史 | 后续持久化发布流程 | 编辑器、校验结果、预览、版本差异 |
+| /write、/documents/:id | 持久化发布、作者更新、固定版本阅读与撤下 | 结构化/XML 编辑器、校验、预览、版本导航；差异比较后续实现 |
 
 第一阶段提供真实可读样例和单篇机器接口。账户系统独立 PR；内容创作、收藏、讨论不可用静态按钮冒充完成。后续将原素材中的适用指导迁移为独立文档，保留原始来源，迁移前不删除。
 
@@ -25,7 +25,7 @@ Hugging Face 可借鉴：owner/name 身份、标签、概览与文件/社区分
 
 沿用 Next.js Pages Router、TypeScript、现有 PostgreSQL、Tailwind 基础；旧首页保存到 src/legacy/WaterfallHome.tsx，原组件保留。新 UI 使用独立 CSS Module，避免影响原素材和 Studio 页面。认证保留管理员动态码，邮箱用户具有独立身份，不能获得现有管理员写权限。
 
-构建只在用户确认的 ces-control；页面验收只访问 http://8.211.154.134:18131/。远程 CI、部署、浏览器验证分别记录结果。主 chat 获本次子任务 PR 合并授权；不把 PR 创建视为部署成功。
+构建只在用户确认的 ces-control；页面验收只访问 http://8.211.154.134:18131/。远程 CI、部署、浏览器验证分别记录结果。所有 PR 均由用户手动合并，主 chat 不执行 merge 或自动合并；不把 PR 创建视为部署成功。
 
 
 ## 已观察的 SkillHub 页面
@@ -44,3 +44,46 @@ Hugging Face 可借鉴：owner/name 身份、标签、概览与文件/社区分
 版本历史为时间线，显示当前版本标记、日期、说明、展开/下载控件；安装右栏在不同标签间保持一致。登录弹窗区分个人/团队，个人有微信和手机号模式，手机号模式包含验证码输入、协议勾选、主按钮；没有执行登录或同意协议。作者页包含头像/名称/认证/简介、关注、横向统计条、左侧排序分类、右侧搜索与作品目录。发布入口 `/dashboard/publish` 匿名访问明确显示“需要登录才能访问”，无法检查其内部编辑器，不假定内部布局。
 
 待补：详情评论和评测标签、首页下半屏的独立截图、移动端；插件、付费服务、大赛作为非核心周边功能，不进入本次开发首版。第一版发布使用结构化指导编辑器，支持 XML 校验与预览，不沿用未知的 SkillHub 内部发布流程。
+
+
+## 第三轮截图与发现
+
+在独立 Chrome 窗口补截了详情“评论”和“评测报告”：评论输入区限制 500 字，支持表情和最多 9 张图片，下方以热门/最新排序展示独立评论卡，包含点赞与回复。没有发表评论、点赞或上传内容。评测报告使用紫色信息卡、五维雷达图、综合分数、评级摘要及分项进度条，并注明基于 AI 自动检测、结果供参考。
+
+当前公开评论包含使用故障反馈，而页面仍展示高自动评分。本记录只说明两种信息同时存在，不核实或转述评论中的故障结论。对本项目的启发是把“作者身份”“静态校验”“真实任务验证”和“用户反馈”分别表达，不能将它们合成一个未经说明的可信徽章。
+
+本轮发现浏览器已有用户登录状态；进入 `/dashboard/publish` 仍显示“需要完成实名认证”，尚不能查看编辑器。没有进入实名认证或提交资料。此前匿名登录限制与本轮实名限制属于不同访问状态，均须保留，不能声称已研究发布表单。
+
+## 第四轮：首页下半屏截图与首版取舍
+
+本轮补截首页榜单、个人与企业发布流程、商业服务区、企业展示区、专家包入口及页脚。榜单以黑底第一名大卡和两列紧凑列表突出排行；发布流程用个人/企业双列分步说明，辅以操作界面图片；商业区以灰蓝底大面板展示按调用计费的服务示意。企业区使用横排浅灰卡片，专家包以横幅和单一浏览按钮收束，页脚列出服务/隐私协议、来源和版权说明。这里只记录可见设计，不将示意收益或排名视作已核实数据。
+
+首版采用三种可复用结构：可扫描的文档列表、宽正文加窄元数据侧栏、清晰的发布步骤及校验反馈。首页不展示无真实来源的排行、收益、企业背书或专家包。可选集合以后可以作为导航，但每篇文档始终保有独立地址、独立版本和独立适用范围，不要求整组加载。
+
+## 当前实现与交付状态
+
+原型、邮箱账户及持久化发布已由用户合并（PR #6/#7/#8/#9），运行时仍需 ces-control CI 成功并部署后验收。PR #11 修正首页 data URL 的旧测试预期；PR #12 修复 llms.txt、Markdown 入口和 /api/guides 的公开只读发现规则，均等待用户手动合并。单篇 XML/JSON、条件链接、固定版本与作者权限已有实现和测试代码，不等于远程验证已经通过。
+
+## 第五轮：目录筛选与空结果
+
+实测 `/skills?sortBy=trending` 的“所有场景分类”菜单，选择开发编程后地址变为 `/skills?category=dev-programming&sortBy=trending`，结果数量随之更新。输入不匹配关键词后，地址同时保留 keyword/category/sortBy，显示 0 个结果、空结果插画和“清除所有筛选”按钮。菜单、分类结果和空状态均已在主 chat 截图。
+
+本项目对应修复在 PR #13：分类数量包含用户文档与样例，避免只因样例未命中而误报全局无结果；区分加载失败与真实空结果；搜索提交、分类和快捷主题写入 URL，可刷新恢复并清除。真实数据库与 Chromium 回归代码已提交，远程 CI 尚待执行。
+
+## 第六轮：其他主要页面模板
+
+在新建 Chrome 研究窗口补截以下页面首屏，未安装插件、购买服务、投稿或执行页面中的命令：
+
+| 实际页面 | 可见结构 | 对本项目的取舍 |
+| --- | --- | --- |
+| `/plugins` | 大标题与数量、横向安装说明条、分类按钮、搜索/排序/视图切换、来源与统计列表 | 复用目录控件层级；独立文档采用读取地址，不要求安装运行时 |
+| `/skillpay` | 巨大居中标题、普通/付费服务双栏对照、上架与接入流程按钮 | 说明页可用清晰对照，但本次不引入交易或调用计费 |
+| `/contest` | 期数与状态、主题大标题、投稿/作品按钮、三联图片、数据及后续赛事说明 | 活动运营是独立模块；不作为文档发现或可信度的基础 |
+| `/tutorials` | 左侧分组文档树、中间长文与表格、右侧本篇目录、阅读进度 | 协议与作者指南可借鉴锚点目录；文档本身不绑定整棵目录 |
+| `/skillspackage` | 行业分类横栏、列表/卡片切换、专家角色与技能数量 | 只把集合视为可选导航；保留单篇独立入口 |
+| `/skillspackage/tech-test-automation` | 概述/技能模块标签、串联工作步骤、右栏整包安装提示与 ZIP | 本项目使用每条链接的 when/relation/revision，Agent 根据当前任务决定下一篇，不能默认执行全组步骤 |
+| `/enterprise-zone` | 精选/最新/热门三块彩色面板、行业筛选、搜索和企业卡片区域 | 作者来源可展示；认证与热门数据不能代替单篇的适用条件和实际验证 |
+
+企业专区截图仍包含加载骨架，后续读取超时；未据此声称卡片全部加载或交互已验证。活动页截图包含入场渐显效果，只用于识别版式；没有核实其运营数字。窄屏参考尚未采集，服务器视觉验收仍须覆盖窄屏。
+
+截至本轮，已覆盖 SkillHub 主要公开页面模板和核心详情状态；实名受限的发布编辑器、个人后台及全部筛选组合未遍历。截图保留在主 chat 工具结果中。组件/页面规划见 design-system.md，研究观察与功能验证分开记录。