Rebuild guidance wiki as a unified SaaS workspace

This commit is contained in:
2026-10-29 20:26:24 +08:00
parent f490543853
commit 0d8aacb9a2
25 changed files with 5778 additions and 208 deletions
+202 -5
View File
@@ -1,5 +1,202 @@
import Head from 'next/head';
import GuidanceShell from '@/components/GuidanceShell';
import {guides,guidanceXml} from '@/content/guides/catalog';
import s from '@/styles/guidance.module.css';
export default function Protocol(){return <GuidanceShell><Head><title>Linked Guidance 0.1 · 织页</title></Head><main className={s.detail}><span className={s.eyebrow}>AN OPEN EXPERIMENT · 0.1</span><h1>让每一页,都能成为起点。</h1><p>Linked Guidance 协议草案 · 名称待定</p><article className={s.prose}><h2>从文档出发,按需连接</h2><p>每篇文档都有独立正文、适用条件和固定版本。集合只是整理方式,不要求整套安装。Agent 先阅读一篇,再判断链接是否有助于当前任务。</p><h2>从哪里开始</h2><p><a href="/agent/index.md">Agent 阅读入口 ↗</a> · <a href="/documents">真实用户文档 ↗</a> · <a href="/write">发布文档 ↗</a></p><h2>一个最小示例</h2><pre>{guidanceXml(guides[0])}</pre><h2>三种关系</h2><p>guide:可供采用的指导;context:背景知识;evidence:事实依据。背景和依据不会自动成为指令。</p><h2>读取约定</h2><ol><li>判断入口文档是否适合当前任务。</li><li>只跟随满足 when 条件且有帮助的链接。</li><li>按文档与版本去重;默认最多 8 篇、深度 3 层。</li><li>固定版本缺失不退回最新版;预算耗尽时报告不完整。</li></ol><h2>权限不沿链接传播</h2><p>文档不会改变用户授权或运行环境约束。0.1 仅引用本站文档 id,不自动请求任意外部 URL,不执行 XML 实体或脚本。</p><h2>协议状态</h2><p>这是待验证原型,并非现有 Agent 原生标准。当前提供单篇 XML 接口、已验证邮箱作者发布与固定版本历史。跨站发现与原生 Agent 适配仍待实现。</p><p>研究起点:<a href="https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f">Karpathy 的 LLM Wiki 原始提案 ↗</a>。XML 语法是本项目提出的设计。</p></article></main></GuidanceShell>}
import Link from "next/link";
import {
ArrowUpRight,
BookOpen,
Bot,
Braces,
GitBranch,
Link2,
ShieldCheck,
Target,
} from "lucide-react";
import GuidanceShell from "@/components/GuidanceShell";
import { CopyButton, KindBadge, PageHeading } from "@/components/GuidanceUI";
import { guides, guidanceXml } from "@/content/guides/catalog";
import s from "@/styles/guidance.module.css";
const sections = [
["idea", "独立文档"],
["start", "开始读取"],
["syntax", "文档语法"],
["relations", "三种关系"],
["reading", "读取约定"],
["permissions", "权限边界"],
["status", "协议状态"],
];
export default function Protocol() {
const xml = guidanceXml(guides[0]);
return (
<GuidanceShell title="文档协议">
<PageHeading
title="从一篇文档,连接下一种可能。"
description="Linked Guidance 0.1 · 为独立指导文档设计的实验协议"
eyebrow="DOCUMENTATION"
>
<a
href="/agent/index.md"
target="_blank"
rel="noreferrer"
className={s.secondaryButton}
>
<Bot size={15} />
Agent 读取入口
<ArrowUpRight size={13} />
</a>
</PageHeading>
<div className={s.protocolLayout}>
<article className={`${s.panel} ${s.protocolArticle}`}>
<section id="idea" className={s.proseSection}>
<h2>
<BookOpen size={17} />
文档是起点,集合只是组织方式
</h2>
<p>
每篇文档都有完整正文、适用条件和固定版本。Coding agent 与 personal
agent
都可以从一篇文档开始;需要更多帮助时,再判断关联链接是否适合当前任务。无需把一整组文档一起安装或加载。
</p>
</section>
<section id="start" className={s.proseSection}>
<h2>
<Target size={17} />
从哪里开始
</h2>
<p>
先通过目录发现摘要,再读取一篇文档的固定版本。人的阅读界面与 Agent
的 XML 接口引用同一份内容。
</p>
<div className={s.buttonRow} style={{ marginTop: 16 }}>
<Link className={s.secondaryButton} href="/">
探索文档
<ArrowUpRight size={13} />
</Link>
<Link className={s.secondaryButton} href="/documents">
社区文档
<ArrowUpRight size={13} />
</Link>
<Link className={s.secondaryButton} href="/write">
发布文档
<ArrowUpRight size={13} />
</Link>
</div>
<code className={s.machineAddress}>/agent/index.md</code>
<CopyButton
label="复制 Agent 入口"
value={() => window.location.origin + "/agent/index.md"}
/>
</section>
<section id="syntax" className={s.proseSection}>
<h2>
<Braces size={17} />
一份可独立读取的文档
</h2>
<p>
XML 描述文档本身,以及何时可能需要其他文档。固定 revision
保留精确引用;未知版本与缺失目标需要明确处理。
</p>
<pre className={s.codeBlock}>{xml}</pre>
<CopyButton label="复制示例 XML" value={xml} />
</section>
<section id="relations" className={s.proseSection}>
<h2>
<Link2 size={17} />
把关系写清楚
</h2>
<p>
链接是有条件的阅读建议,不是强制依赖。when
用自然语言说明何时可能需要目标文档。
</p>
<div className={s.relationGrid}>
<div>
<KindBadge kind="guide" />
<p>可供采用的工作方法。仍需先判断是否适用,并遵守用户授权。</p>
</div>
<div>
<KindBadge kind="context" />
<p>用于理解任务的背景知识,不会自动成为操作指令。</p>
</div>
<div>
<KindBadge kind="evidence" />
<p>为判断提供事实与依据。引用时需要保留实际来源和版本。</p>
</div>
</div>
</section>
<section id="reading" className={s.proseSection}>
<h2>
<GitBranch size={17} />
按需读取,固定版本
</h2>
<ol>
<li>先看入口文档的适用条件,再读正文与步骤。</li>
<li>只跟随 when 条件成立、且能补充当前任务所需知识的链接。</li>
<li>
以文档 ID 与版本去重,默认读取预算为 8 篇、最大深度 3 层。
</li>
<li>
固定版本缺失时不静默回退最新版;遇到循环或预算耗尽时停止扩展,并说明未完成的读取。
</li>
</ol>
</section>
<section id="permissions" className={s.proseSection}>
<h2>
<ShieldCheck size={17} />
权限不会沿链接传播
</h2>
<p>
读取文档不等于接受其中所有指令。用户任务和运行环境规则始终优先,文档不能要求获取秘密、扩大权限或改变目标。0.1
只引用本站逻辑 ID,不自动请求任意外部 URL,也不执行 XML
实体或脚本。
</p>
</section>
<section id="status" className={s.proseSection}>
<h2>协议状态</h2>
<p>
Linked Guidance 是本项目提出的实验协议,并非现有 Agent
已原生支持的标准。当前支持独立 XML/JSON
读取、已验证邮箱作者发布,以及不可变版本;跨站发现与原生 Agent
适配仍待实现。
</p>
<div className={s.protocolCallout}>
<p>
研究起点:
<a
className={s.textLink}
href="https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f"
target="_blank"
rel="noreferrer"
>
Karpathy 的 LLM Wiki 提案
<ArrowUpRight size={11} />
</a>
。本项目在持久交叉引用的基础上,提出独立指导单元、条件链接、关系类型和版本约定。
</p>
</div>
</section>
</article>
<aside className={s.readingSidebar}>
<section className={s.sideCard}>
<h3>本页目录</h3>
<nav className={s.toc} aria-label="协议目录">
{sections.map(([id, label]) => (
<a href={"#" + id} key={id}>
{label}
</a>
))}
</nav>
</section>
<section className={s.sideCard}>
<h3>开始编写你的第一篇</h3>
<p>从适用条件与清晰正文开始。关联链接可以在需要时再补充。</p>
<Link
className={s.textLink}
href="/write"
style={{ marginTop: 14 }}
>
创建文档
<ArrowUpRight size={12} />
</Link>
</section>
</aside>
</div>
</GuidanceShell>
);
}