203 lines
7.6 KiB
TypeScript
203 lines
7.6 KiB
TypeScript
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>
|
||
);
|
||
}
|