+
+ {doc.applies}
+
+
+ {doc.body}
+
+
+ -
+ {doc.steps.map((step, index) => (
+
- {step} + ))} +
+
+ -
+ {doc.checks.map((check, index) => (
+
- {check} + ))} +
+
+ + 只在条件适用、且当前任务需要时，打开下一篇文档。 +
+ {links.map((link, index) => { + const content = ( + <> +
+ {link.label}
+
+ {link.resolved && 当{link.when}
+ + {relationNames[link.relation]} + · + v{link.revision} + {!link.resolved && ( + · 固定版本缺失，请跳过 + )} + +
+ {doc.id}.xml
+
+ {xml}
+
+ ) : (
+
+ {versions.map((version) => (
+
+
+
+
+
+ window.location.origin + api}
+ />
+
+ {!!backlinks.length && (
+
+
+ )}
+
+
+
+
+ );
+}
diff --git a/apps/waterfall-wiki/src/components/GuidanceShell.tsx b/apps/waterfall-wiki/src/components/GuidanceShell.tsx
index bcc5985..8eb3de9 100644
--- a/apps/waterfall-wiki/src/components/GuidanceShell.tsx
+++ b/apps/waterfall-wiki/src/components/GuidanceShell.tsx
@@ -1,4 +1,265 @@
-import Link from 'next/link';
-import type {ReactNode} from 'react';
-import s from '@/styles/guidance.module.css';
-export default function GuidanceShell({children}:{children:ReactNode}){return
+
+
+
+
+
+ 版本 {version.revision}
+ {version.revision === doc.revision && (
+ 当前阅读
+ )}
+
+ {dateLabel(version.createdAt)} · 固定版本
+
+ 当前版本
+
+
+
+
+
+ 可见范围
+ {isWithdrawn ? "仅固定历史版本" : "公开读取"}
+
+
+ {doc.id}
+ {canEdit && !isWithdrawn && (
+
+
+
+ )}
+
+ 本篇目录
+ +
+
+ + 把固定版本的读取地址交给 Agent。关联文档是候选帮助，无需一起加载。 +
+{api}
+ 被这些文档引用
+
+ {backlinks.map((b) => (
+
+ {b.title}
+
+
+
+ 工作空间
+ +资源
+ +
+
+
+ );
+ }
+ return (
+
+ 从一篇文档开始
+
+
+
+ {user ? (
+ user.email.slice(0, 1).toUpperCase()
+ ) : (
+ 选择适用的指导，需要更多背景时，再沿链接继续阅读。
+ + 了解使用方法
+
+ {`${title} · 织页`}
+
+
+
+ 跳到正文
+
+
+
+
+
+
+
+
+ {children}
+
+
+
+
+
+ 工作空间
+
+
+
+
+ Linked Guidance 0.1
+
+ {router.pathname !== "/write" && (
+
+
+
+
+ );
+}
+export function PageHeading({
+ title,
+ description,
+ eyebrow,
+ children,
+}: {
+ title: string;
+ description?: string;
+ eyebrow?: string;
+ children?: ReactNode;
+}) {
+ return (
+ {children}
+
+ {eyebrow && {eyebrow}}
+
+ {children && {title}
+ {description &&{description}
} +{children}
}
+
+
+
+ );
+}
+export function Tabs({
+ tabs,
+ value,
+ onChange,
+}: {
+ tabs: { id: string; label: string; count?: number }[];
+ value: string;
+ onChange: (id: string) => void;
+}) {
+ const group = useId(),
+ refs = useRef<(HTMLButtonElement | null)[]>([]);
+ return (
+ {title}
+{description}
+ {children} +
+ {tabs.map((tab, index) => (
+
+ ))}
+
+ );
+}
diff --git a/apps/waterfall-wiki/src/lib/guidance-store.ts b/apps/waterfall-wiki/src/lib/guidance-store.ts
index 590d37a..f224513 100644
--- a/apps/waterfall-wiki/src/lib/guidance-store.ts
+++ b/apps/waterfall-wiki/src/lib/guidance-store.ts
@@ -1,15 +1,55 @@
-import { db,transaction } from './db';
-import { documentInput } from './guidance-input';
-import { findGuide,type Guidance } from '../content/guides/catalog';
-export async function resolveDocument(id:string,revision?:number):Promise你的知识站账户
-用邮箱保存你的身份。邮箱账户与管理员动态码权限独立。
- {token&&确认邮箱验证
点击后完成验证，再使用邮箱和密码登录。
已登录
{user.email}
邮箱已验证
{message}
-
+
+
+
+ 让有用的知识，
+
+
+
+
+
+
+
+ )}
+ {feedback && {feedback.text} }
+ {account.error && (
+
+ {account.error}{" "}
+
+
+ )}
+ {account.loading ? (
+
+
+ );
}
diff --git a/apps/waterfall-wiki/src/pages/api/documents/[[...path]].ts b/apps/waterfall-wiki/src/pages/api/documents/[[...path]].ts
index 26e03b7..8755877 100644
--- a/apps/waterfall-wiki/src/pages/api/documents/[[...path]].ts
+++ b/apps/waterfall-wiki/src/pages/api/documents/[[...path]].ts
@@ -1,27 +1,126 @@
-import { ZodError } from 'zod';
-import type { NextApiRequest,NextApiResponse } from 'next';
-import { currentAccount } from '@/lib/account';
-import { trustedOrigin } from '@/lib/account-crypto';
-import { documentInput,parseDocumentXml } from '@/lib/guidance-input';
-import { discoverDocuments,publishDocument,resolveDocument,withdrawDocument } from '@/lib/guidance-store';
-import { guidanceXml } from '@/content/guides/catalog';
-export default async function handler(req:NextApiRequest,res:NextApiResponse){
- res.setHeader('Cache-Control','no-store');const path=req.query.path||[];if(!Array.isArray(path)||path.length>1)return res.status(404).end();const id=path[0];
- try{
- if(req.method==='GET'){
- if(!id)return res.json({documents:await discoverDocuments()});
- const revision=req.query.revision;if(revision!==undefined&&(typeof revision!=='string'||! /^[1-9][0-9]{0,9}$/.test(revision)||Number(revision)>2147483647))return res.status(400).json({error:'版本无效'});
- const doc=await resolveDocument(id,revision===undefined?undefined:Number(revision));if(!doc)return res.status(404).json({error:'文档或精确版本不存在'});
- if(req.query.format==='xml'){res.setHeader('Content-Type','application/xml; charset=utf-8');return res.send(guidanceXml(doc));}return res.json({document:doc});}
- if(!['POST','DELETE'].includes(req.method||'')){res.setHeader('Allow','GET, POST, DELETE');return res.status(405).end();}
- const request=new Request(new URL(req.url||'/',process.env.ACCOUNT_PUBLIC_ORIGIN||'http://'+req.headers.host),{headers:new Headers(Object.entries(req.headers).filter(([,v])=>typeof v==='string') as [string,string][])});
- if(!trustedOrigin(request))return res.status(403).json({error:'请求来源不受信任'});
- const user=await currentAccount(request);if(!user)return res.status(401).json({error:'请先登录已验证邮箱账户'});
- if(req.method==='DELETE')return id&&await withdrawDocument(user.id,id)?res.json({ok:true}):res.status(404).json({error:'无权删除或不存在'});
- const input=typeof req.body==='string'?parseDocumentXml(req.body):documentInput.parse(req.body);
- if(id==='preview'){const links=await Promise.all(input.links.map(async l=>({...l,resolved:!!await resolveDocument(l.target,l.revision)})));return res.json({document:input,xml:guidanceXml(input),links});}
- if(id&&id!==input.id)return res.status(400).json({error:'文档 ID 不匹配'});
- return res.status(201).json({document:await publishDocument(user.id,input)});
- }catch(e){if(e instanceof ZodError)return res.status(400).json({error:'输入不符合协议，请检查以下字段',fields:e.issues.slice(0,12).map(i=>i.path.join('.')||'文档')});const message=e instanceof Error?e.message:'';if(message==='INVALID_ID')return res.status(400).json({error:'文档 ID 必须以 user-你的账户ID- 开头，请使用编辑器生成的前缀'});if(message==='FORBIDDEN')return res.status(403).json({error:'仅作者可编辑'});if(message==='CONFLICT'||(e as {code?:string}).code==='23505')return res.status(409).json({error:'版本冲突：请加载最新版本，已发布版本不可修改'});if(e instanceof Error&&(e.name==='ZodError'||/XML|实体|元素|属性|协议|链接/.test(message)))return res.status(400).json({error:'输入不符合协议'});return res.status(503).json({error:'文档服务暂不可用'});}
+import { ZodError } from "zod";
+import type { NextApiRequest, NextApiResponse } from "next";
+import { currentAccount } from "@/lib/account";
+import { trustedOrigin } from "@/lib/account-crypto";
+import { documentInput, parseDocumentXml } from "@/lib/guidance-input";
+import {
+ discoverDocuments,
+ publishDocument,
+ resolveDocument,
+ withdrawDocument,
+} from "@/lib/guidance-store";
+import { guidanceXml } from "@/content/guides/catalog";
+export default async function handler(
+ req: NextApiRequest,
+ res: NextApiResponse,
+) {
+ res.setHeader("Cache-Control", "no-store");
+ const path = req.query.path || [];
+ if (!Array.isArray(path) || path.length > 1) return res.status(404).end();
+ const id = path[0];
+ try {
+ if (req.method === "GET") {
+ if (!id) {
+ const author = req.query.author;
+ if (
+ author !== undefined &&
+ (typeof author !== "string" ||
+ !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(
+ author,
+ ))
+ )
+ return res.status(400).json({ error: "作者 ID 无效" });
+ return res.json({ documents: await discoverDocuments(author) });
+ }
+ const revision = req.query.revision;
+ if (
+ revision !== undefined &&
+ (typeof revision !== "string" ||
+ !/^[1-9][0-9]{0,9}$/.test(revision) ||
+ Number(revision) > 2147483647)
+ )
+ return res.status(400).json({ error: "版本无效" });
+ const doc = await resolveDocument(
+ id,
+ revision === undefined ? undefined : Number(revision),
+ );
+ if (!doc) return res.status(404).json({ error: "文档或精确版本不存在" });
+ if (req.query.format === "xml") {
+ res.setHeader("Content-Type", "application/xml; charset=utf-8");
+ return res.send(guidanceXml(doc));
+ }
+ return res.json({ document: doc });
+ }
+ if (!["POST", "DELETE"].includes(req.method || "")) {
+ res.setHeader("Allow", "GET, POST, DELETE");
+ return res.status(405).end();
+ }
+ const request = new Request(
+ new URL(
+ req.url || "/",
+ process.env.ACCOUNT_PUBLIC_ORIGIN || "http://" + req.headers.host,
+ ),
+ {
+ headers: new Headers(
+ Object.entries(req.headers).filter(
+ ([, v]) => typeof v === "string",
+ ) as [string, string][],
+ ),
+ },
+ );
+ if (!trustedOrigin(request))
+ return res.status(403).json({ error: "请求来源不受信任" });
+ const user = await currentAccount(request);
+ if (!user) return res.status(401).json({ error: "请先登录已验证邮箱账户" });
+ if (req.method === "DELETE")
+ return id && (await withdrawDocument(user.id, id))
+ ? res.json({ ok: true })
+ : res.status(404).json({ error: "无权删除或不存在" });
+ const input =
+ typeof req.body === "string"
+ ? parseDocumentXml(req.body)
+ : documentInput.parse(req.body);
+ if (id === "preview") {
+ const links = await Promise.all(
+ input.links.map(async (l) => ({
+ ...l,
+ resolved: !!(await resolveDocument(l.target, l.revision)),
+ })),
+ );
+ return res.json({ document: input, xml: guidanceXml(input), links });
+ }
+ if (id && id !== input.id)
+ return res.status(400).json({ error: "文档 ID 不匹配" });
+ return res
+ .status(201)
+ .json({ document: await publishDocument(user.id, input) });
+ } catch (e) {
+ if (e instanceof ZodError)
+ return res
+ .status(400)
+ .json({
+ error: "输入不符合协议，请检查以下字段",
+ fields: e.issues.slice(0, 12).map((i) => i.path.join(".") || "文档"),
+ });
+ const message = e instanceof Error ? e.message : "";
+ if (message === "INVALID_ID")
+ return res
+ .status(400)
+ .json({
+ error: "文档 ID 必须以 user-你的账户ID- 开头，请使用编辑器生成的前缀",
+ });
+ if (message === "FORBIDDEN")
+ return res.status(403).json({ error: "仅作者可编辑" });
+ if (message === "CONFLICT" || (e as { code?: string }).code === "23505")
+ return res
+ .status(409)
+ .json({ error: "版本冲突：请加载最新版本，已发布版本不可修改" });
+ if (
+ e instanceof Error &&
+ (e.name === "ZodError" || /XML|实体|元素|属性|协议|链接/.test(message))
+ )
+ return res.status(400).json({ error: "输入不符合协议" });
+ return res.status(503).json({ error: "文档服务暂不可用" });
+ }
}
-export const config={api:{bodyParser:{sizeLimit:'128kb'}}};
+export const config = { api: { bodyParser: { sizeLimit: "128kb" } } };
diff --git a/apps/waterfall-wiki/src/pages/documents/[id].tsx b/apps/waterfall-wiki/src/pages/documents/[id].tsx
index 8fa2407..82f4b56 100644
--- a/apps/waterfall-wiki/src/pages/documents/[id].tsx
+++ b/apps/waterfall-wiki/src/pages/documents/[id].tsx
@@ -1,6 +1,61 @@
-import type { GetServerSideProps } from 'next';
-import type { Guidance } from '@/content/guides/catalog';
-import styles from '@/styles/documents.module.css';
-type Props={canEdit:boolean;versions:number[];doc:Guidance;links:(Guidance['links'][number]&{resolved:boolean})[]};
-export default function Read({doc,links,canEdit,versions}:Props){return
+ 让有用的知识，
+
+ 成为下一次行动的起点。
+
+ + 用邮箱建立你的知识空间。把工作方法写成独立文档，让 Agent + 在需要的时候找到它。 +
+
+
+
+
+
+ 每篇文档，都能独立使用
+
+ 从当前任务出发，无需加载整个集合。
+
+
+
+ 每次更新，都有固定版本
+
+ 历史引用保持可读，修改始终有迹可循。
+
+
+
+ 知识之间，按条件连接
+
+ 需要更多背景时，再沿有用的链接继续阅读。
++ {account.user + ? "你的账户" + : mode === "register" + ? "创建你的账户" + : mode === "resend" + ? "重发验证邮件" + : "欢迎回来"} +
++ {account.user + ? "已准备好发布和管理你的独立文档。" + : mode === "register" + ? "验证邮箱后，就可以发布第一篇文档。" + : mode === "resend" + ? "输入注册时的邮箱和密码，重新获取验证链接。" + : "使用邮箱与密码登录，继续你的知识工作。"} +
+ {token && ( +
+
+ 验证链接有效期为 30 分钟。确认后，再使用邮箱与密码登录。
+ +
+ 正在检查账户状态…
+
+ ) : account.user ? (
+ <>
+
+
+ {account.user.email.slice(0, 1).toUpperCase()}
+
+
+
+ {account.user.email}
+
+
+
+
+
+ 继续使用织页
+
+ 你的内容，由你管理。
+
+ 你可以发布文档、创建新版本，以及撤下自己的内容。公开文档的固定历史版本会继续保留。
+
+
+
+
+ ) : (
+ <>
+ {mode !== "resend" && (
+
+ )}
+
+
+ {mode === "resend" ? (
+
+ ) : (
+
+ )}
+
+ + 注册后需要先验证邮箱。公开文档始终可以直接阅读。 +
+ + )} +{doc.title}
{doc.kind} · {doc.id} · 固定版本 {doc.revision}
版本：{versions.map(v=> v{v} )}
{doc.summary}
适用条件
{doc.applies}
{doc.body}
- {doc.steps.map((s,i)=>
- {s} )}
条件链接
{links.map((l,i)=>条件：{l.when} · {l.relation}
{l.resolved?{l.label} · v{l.revision}:{l.label}：精确版本缺失，请跳过
}检查项
- {doc.checks.map((s,i)=>
- {s} )}
用户发布的文档
{error}
{docs.map(d=>{d.title}
{d.kind} · v{d.revision}
{d.summary}
文档 / protocol-examples / {g.id}
{g.kind.toUpperCase()} · REVISION {g.revision}{g.title}
{g.summary}
{guidanceXml(g)}:<>何时使用
{g.applies}
指导正文
{g.body}
建议步骤
- {g.steps.map(t=>
- {t} )}
完成检查
- {g.checks.map(t=>
- {t} )}
继续探索
{g.links.map(l=>{l.label} ↗当{l.when} · {l.relation} · r{l.revision})}{!g.links.length&&这篇文档可独立使用，没有建议继续读取的链接。
}}一个起点，
连接下一种可能。
- 每一篇文档，都能独立帮助你的 Agent。
从当前问题出发，沿着有用的链接继续探索。
{['代码审查','规划','验证'].map(t=>)}
- {loading?'正在加载用户文档…':loadError?`协议样例 ${items.length} 篇；用户文档加载失败`:`找到 ${total} 篇文档`}
{(q||kind!=='all')&&}用户文档暂未加载：{loadError}。下方仍可阅读协议样例。
} - {!loading&&!loadError&&total===0&&没有匹配文档，请尝试其他关键词或清除筛选。
} -用户发布 {userItems.length} 篇
发布一篇文档 ↗{userItems.map(g=>
- {!loading&&!loadError&&!published.length&&↗
{g.id} · {g.kind} · v{g.revision}
{g.title}
{g.summary}
还没有用户文档。你可以发布第一篇，或先阅读下方样例。
} -从这里开始 {items.length} 篇
协议样例 · v0.1{items.map(g=>
- {g.kind==='guide'?'↗':'≋'}
织页 / protocol-examples · r{g.revision}
{g.title}
{g.summary}
{g.tags.map(t=>{t})}↗ {g.links.length} 个关联
让每一页，都能成为起点。
Linked Guidance 协议草案 · 名称待定
从文档出发，按需连接
每篇文档都有独立正文、适用条件和固定版本。集合只是整理方式，不要求整套安装。Agent 先阅读一篇，再判断链接是否有助于当前任务。
从哪里开始
Agent 阅读入口 ↗ · 真实用户文档 ↗ · 发布文档 ↗
一个最小示例
{guidanceXml(guides[0])}三种关系
guide：可供采用的指导；context：背景知识；evidence：事实依据。背景和依据不会自动成为指令。
读取约定
- 判断入口文档是否适合当前任务。
- 只跟随满足 when 条件且有帮助的链接。
- 按文档与版本去重；默认最多 8 篇、深度 3 层。
- 固定版本缺失不退回最新版；预算耗尽时报告不完整。
权限不沿链接传播
文档不会改变用户授权或运行环境约束。0.1 仅引用本站文档 id，不自动请求任意外部 URL，不执行 XML 实体或脚本。
协议状态
这是待验证原型，并非现有 Agent 原生标准。当前提供单篇 XML 接口、已验证邮箱作者发布与固定版本历史。跨站发现与原生 Agent 适配仍待实现。
研究起点：Karpathy 的 LLM Wiki 原始提案 ↗。XML 语法是本项目提出的设计。
+
+
+
+
+
+
+
+
+ window.location.origin + "/agent/index.md"}
+ />
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ + 每篇文档都有完整正文、适用条件和固定版本。Coding agent 与 personal + agent + 都可以从一篇文档开始；需要更多帮助时，再判断关联链接是否适合当前任务。无需把一整组文档一起安装或加载。 +
+
+
+ + 先通过目录发现摘要，再读取一篇文档的固定版本。人的阅读界面与 Agent + 的 XML 接口引用同一份内容。 +
+
+
+ 探索文档
+
+ /agent/index.md
+
+
+ + XML 描述文档本身，以及何时可能需要其他文档。固定 revision + 保留精确引用；未知版本与缺失目标需要明确处理。 +
+{xml}
+
+
+ + 链接是有条件的阅读建议，不是强制依赖。when + 用自然语言说明何时可能需要目标文档。 +
+
+
+
+
+ 可供采用的工作方法。仍需先判断是否适用，并遵守用户授权。
+
+
+ 用于理解任务的背景知识，不会自动成为操作指令。
+
+
+ 为判断提供事实与依据。引用时需要保留实际来源和版本。
+
+
+ -
+
- 先看入口文档的适用条件，再读正文与步骤。 +
- 只跟随 when 条件成立、且能补充当前任务所需知识的链接。 +
- + 以文档 ID 与版本去重，默认读取预算为 8 篇、最大深度 3 层。 + +
- + 固定版本缺失时不静默回退最新版；遇到循环或预算耗尽时停止扩展，并说明未完成的读取。 + +
+
+ + 读取文档不等于接受其中所有指令。用户任务和运行环境规则始终优先，文档不能要求获取秘密、扩大权限或改变目标。0.1 + 只引用本站逻辑 ID，不自动请求任意外部 URL，也不执行 XML + 实体或脚本。 +
+协议状态
++ Linked Guidance 是本项目提出的实验协议，并非现有 Agent + 已原生支持的标准。当前支持独立 XML/JSON + 读取、已验证邮箱作者发布，以及不可变版本；跨站发现与原生 Agent + 适配仍待实现。 +
+
+
+
+ 研究起点：
+
+ Karpathy 的 LLM Wiki 提案
+
发布独立文档
需要已验证邮箱。每次发布创建不可变版本；只有原作者可以更新或撤下。