Prototype standalone linked guidance documents and discovery UI

docs/linked-guidance/product-plan.md

@@ -0,0 +1,38 @@
+# 从素材瀑布流到独立指导文档网络
+
+## 研究状态（2026-10-29）
+
+已阅读 Karpathy LLM Wiki 原始提案，检查用户提供的 Hugging Face Qwen 页面与 GitHub Chromium 页面。已通过 Chrome 截取 SkillHub 首页、目录、详情概述三个画面，读取文件树状态；截图显示在主 chat 工具结果中，未导出为仓库图片。文件页截图请求超时。研究仍未覆盖所有页面，不宣称已完成逐页分析。
+
+待采集：SkillHub 首页首屏和下半屏、搜索与筛选、技能详情、文档/文件视图、作者页、登录入口、发布入口、移动视图；逐页记录实际 URL、截图、布局、控件、交互和对本项目的取舍。无法匿名访问的页面明确注明登录限制，不冒充已检查。
+
+Hugging Face 可借鉴：owner/name 身份、标签、概览与文件/社区分栏、主内容加元数据侧栏。GitHub 可借鉴：稳定地址、版本历史、README 阅读层级、文件和讨论分离。这里应把“单篇文档”放在中心，集合只是可选组织方式；不复制仓库文件树为强制入口。
+
+## 页面与组件
+
+| 页面 | 首版行为 | 核心组件 |
+| --- | --- | --- |
+| / | 搜索、种类筛选、文档目录 | 顶栏、搜索框、分类导航、文档行、说明侧栏 |
+| /guide/:id | 独立阅读、条件链接、反向链接、XML | 面包屑、版本标记、正文、步骤、采用提示、关联文档 |
+| /protocol | 展示 0.1 约定与使用边界 | 语法示例、读取流程、协议状态 |
+| /account | 注册、验证邮箱、登录、退出 | 表单、错误反馈、会话状态 |
+| 作者与集合 | 后续真实用户内容组织 | 作者简介、非强制集合、收藏 |
+| 编辑与历史 | 后续持久化发布流程 | 编辑器、校验结果、预览、版本差异 |
+
+第一阶段提供真实可读样例和单篇机器接口。账户系统独立 PR；内容创作、收藏、讨论不可用静态按钮冒充完成。后续将原素材中的适用指导迁移为独立文档，保留原始来源，迁移前不删除。
+
+## 技术与验收
+
+沿用 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 创建视为部署成功。
+
+
+## 已观察的 SkillHub 页面
+
+- `/`：白底黑字、宽屏顶栏、大面积留白、巨大居中标题、复制给 AI 安装条；下方轮播服务卡、近期飙升/下载榜、插件、个人企业发布与商业服务。营销与发现混合。
+- `/skills?sortBy=trending`：标题与总数，排序标签、来源/场景/API Key 三个筛选、搜索框、列表/卡片切换。列表以图标、名称、认证、分类、截断摘要、收藏和下载统计组成，细灰边框和分隔线。
+- `/skills/zcwl/multi-search-engine`：面包屑、图标与名称、命名空间、AI 评分、安全、作者、摘要与标签；概述/文件/评论/版本历史/评测报告五个标签。正文占宽约三分之二，右栏为安装提示词、ZIP、Agent 安装与元数据。
+- 文件标签：观察到 references、scripts 文件夹和 SKILL.md、共 4 文件；侧栏有 token 预估、下载收藏、作者、安全报告、内容指纹、数字签名与相关推荐。文件树仍将整个包作为单位。
+
+本项目取舍：保留清晰命名空间、列表可扫描性、阅读与源文档切换；将安装栏改为“采用单篇”，将包文件树改为条件链接和反向引用。暂不复制评分、下载热度、认证徽章，避免没有真实数据的信任暗示。当前暖绿原型是独立视觉探索，需完成参考截图与服务器验收后修订。

docs/linked-guidance/protocol.md

@@ -0,0 +1,49 @@
+# Linked Guidance 0.1 — 提案，名称待定
+
+目标是让任何一篇文档都能作为 coding agent 或 personal agent 的入口。不需要安装目录、不要求加载集合、不通过仓库位置继承权限。集合只是书签，不是执行单元。
+
+## 文档语法
+
+使用 UTF-8 XML 1.0；媒体类型 application/xml。正文与步骤使用纯文本，XML 转义适用于全部文本和属性；不允许 DTD、外部实体、处理指令和可执行嵌入。0.1 的标准输出由服务端生成，不接受任意 XML 上传执行。
+
+```xml
+<guidance xmlns="urn:linked-guidance:0.1" id="review-changes" revision="1" kind="guide" lang="zh-CN">
+  <title>审查一次代码变更</title>
+  <summary>定位实际影响，并给出可验证的审查结论。</summary>
+  <applies>用户请求 review、检查变更或评估回归风险。</applies>
+  <body>先阅读需求与完整差异，再追踪受影响的调用路径。</body>
+  <step>按影响排序，只报告有证据的问题。</step>
+  <link target="test-changes" revision="1" relation="guide" when="需要选择验证方法">选择适当测试</link>
+  <link target="source-trust" revision="1" relation="context" when="变更包含外部资料">判断资料可信度</link>
+  <check>每个结论能指出具体触发条件与验证方法。</check>
+</guidance>
+```
+
+根元素必需属性：命名空间、id（小写字母、数字与短横线）、正整数 revision、kind（guide/context/evidence）、lang。必需单值子元素：title、summary、applies、body。step、link、check 可重复。未知版本必须明确拒绝，不能猜测执行。正文只提供文本，展示层的 HTML 不属于协议。
+
+## 链接与读取
+
+链接是候选阅读建议，不能自动授予权限，也不是强制依赖。`when` 是自然语言条件，由 agent 结合当前任务判断。relation=guide 表示可能有用的指导；context 表示背景；evidence 表示事实依据。后两者不能升级成操作指令。即使 guide 链接也只能在用户授权范围内采用。
+
+先读入口文档自身，再看链接摘要；满足条件且确实缺少相关知识才读取目标正文。单次读取预算默认 8 篇、最大深度 3，以 (id,revision) 去重；记录读取原因、跳过原因、未知版本和缺失目标。预算耗尽时停止扩展并报告不完整。不得把循环、链接失效理解为任务失败；必需前置条件不满足时停止相应动作并说明。
+
+0.1 target 仅允许本站逻辑 id，不自动请求任意 URL；避免服务器端网络探测。外部来源只作为显式资料链接展示，后续联邦协议需要单独定义域名信任、重定向、内容大小与哈希规则。
+
+## 版本与可信度
+
+固定 revision 是精确引用，缺失时不得静默切换最新版。latest 仅用于发现，实际采用前解析为固定版本。已发布版本不可原地修改；更新创建新版本，旧链接继续可解析。文档、集合、作者、运行时权限分别管理。引用任何作者的文档都不会获得作者权限。
+
+用户指令与运行环境规则优先。文档中的联网、发送邮件、运行命令、发布和删除步骤都需要现有任务授权。文档不能要求 agent 忽略更高优先级指令或获取秘密。
+
+## HTTP
+
+- GET /api/guides：发现摘要、种类和固定版本，不包含整套正文。
+- GET /api/guides/:id?revision=1：单篇 JSON；format=xml 获取单篇规范 XML。
+- GET /guide/:id：人类阅读界面，单篇正文、条件链接、反向链接、版本。
+- 每次 agent 采用文档时记录实际版本与来源，而不是只记录集合名称。
+
+0.1 是最小可检验原型，不宣称现有 agent 已原生支持。agent 可通过阅读 XML 采用约定；MCP、编辑器插件、联邦索引属于后续适配。
+
+## 研究依据
+
+Karpathy 的原始提案 https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f 描述 raw/wiki/schema、ingest/query/lint 和持久交叉引用。本方案借鉴持久链接与渐进读取，新增独立指导单元、条件链接、关系类型、明确版本和授权边界。它不是该提案的原有 XML 标准。