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
+728 -13
View File
@@ -1,14 +1,729 @@
import { useEffect,useState } from 'react';
import type { Guidance } from '@/content/guides/catalog';
import styles from '@/styles/documents.module.css';
const blank:Guidance={id:'user-',revision:1,kind:'guide',title:'',summary:'',applies:'',body:'',steps:[],checks:[],links:[],tags:[]};
export default function Write(){
const [busy,setBusy]=useState(false),[published,setPublished]=useState<{id:string;revision:number}|null>(null);
const [doc,setDoc]=useState(blank),[xml,setXml]=useState(''),[mode,setMode]=useState(false),[message,setMessage]=useState(''),[preview,setPreview]=useState<{document:Guidance;xml:string;links:{label:string;when:string;resolved:boolean}[]}|null>(null);
useEffect(()=>{setPreview(null);},[doc,xml,mode]);
useEffect(()=>{fetch('/api/account/session').then(r=>r.json()).then(b=>{if(b.user){const id=new URLSearchParams(window.location.search).get('id');if(id)fetch('/api/documents/'+encodeURIComponent(id)).then(responseBody).then(b=>setDoc({...b.document,revision:b.document.revision+1})).catch(e=>setMessage(e.message));else setDoc(d=>({...d,id:'user-'+b.user.id+'-'}));}else setMessage('请先登录并验证邮箱,再发布文档。');}).catch(()=>setMessage('账户服务暂不可用,请稍后重试。'));},[]);
async function responseBody(r:Response){const b=await r.json().catch(()=>({error:'服务返回异常,请稍后重试'}));if(!r.ok)throw Error((b.error||'请求失败')+(b.fields?.length?':'+b.fields.join('、'):''));return b;}
async function load(){setBusy(true);setPreview(null);try{const b=await responseBody(await fetch('/api/documents/'+encodeURIComponent(doc.id)));setDoc({...b.document,revision:b.document.revision+1});setMessage('已加载,保存将创建新版本');}catch(e){setMessage(e instanceof Error?e.message:'加载失败');}finally{setBusy(false);}}
async function submit(action:string){setBusy(true);setMessage('处理中…');setPreview(null);setPublished(null);try{const b=await responseBody(await fetch('/api/documents'+(action==='preview'?'/preview':''),{method:'POST',headers:{'Content-Type':mode?'application/xml':'application/json'},body:mode?xml:JSON.stringify(doc)}));if(action==='preview'){setPreview(b);setMessage('预览成功,尚未发布');}else{setDoc({...b.document,revision:b.document.revision+1});setPublished({id:b.document.id,revision:b.document.revision});if(mode)setXml(xml.replace(/revision="[1-9][0-9]*"/,`revision="${b.document.revision+1}"`));setMessage('已发布版本 '+b.document.revision);}}catch(e){setMessage(e instanceof Error?e.message:'请求失败,请稍后重试');}finally{setBusy(false);}}
return <main className={styles.page}><nav><a href="/">首页</a> · <a href="/documents">用户文档</a> · <a href="/account">邮箱账户</a></nav><h1>发布独立文档</h1><p>需要已验证邮箱。每次发布创建不可变版本;只有原作者可以更新或撤下。</p><fieldset disabled={busy}><label><input type="checkbox" checked={mode} onChange={e=>{setMode(e.target.checked);setPreview(null);}}/> 使用协议 XML(zh-CN)</label>{mode?<label>XML 输入<textarea rows={22} value={xml} onChange={e=>{setXml(e.target.value);setPreview(null);}}/></label>:<><label>文档 ID(保留账户前缀,在末尾填写短名)<input value={doc.id} onChange={e=>setDoc({...doc,id:e.target.value})}/></label><button disabled={busy} onClick={load}>加载最新版本以编辑</button><label>待发布版本<input type="number" min={1} value={doc.revision} onChange={e=>setDoc({...doc,revision:Number(e.target.value)})}/></label><label>种类<select value={doc.kind} onChange={e=>setDoc({...doc,kind:e.target.value as Guidance['kind']})}><option>guide</option><option>context</option><option>evidence</option></select></label>{(['title','summary','applies','body'] as const).map(k=><label key={k}>{{title:'标题',summary:'摘要',applies:'适用条件',body:'正文'}[k]}<textarea value={doc[k]} onChange={e=>{setDoc({...doc,[k]:e.target.value});setPreview(null);}}/></label>)}{(['steps','checks'] as const).map(k=><label key={k}>{k==='steps'?'步骤':'检查项'}(每行一项)<textarea value={doc[k].join('\n')} onChange={e=>setDoc({...doc,[k]:e.target.value.split('\n').filter(Boolean)})}/></label>)}<h2>条件链接</h2>{doc.links.map((l,i)=><fieldset key={i}>{(['target','revision','relation','when','label'] as const).map(k=><label key={k}>{k}<input value={l[k]} onChange={e=>setDoc({...doc,links:doc.links.map((v,j)=>j===i?{...v,[k]:k==='revision'?Number(e.target.value):e.target.value}:v)})}/></label>)}<button onClick={()=>setDoc({...doc,links:doc.links.filter((_,j)=>j!==i)})}>移除链接</button></fieldset>)}<button onClick={()=>setDoc({...doc,links:[...doc.links,{target:'',revision:1,relation:'context',when:'',label:''}]})}>添加精确版本链接</button></>}<p><button disabled={busy} onClick={()=>submit('preview')}>校验并预览</button> <button disabled={busy} onClick={()=>submit('publish')}>发布新版本</button></p></fieldset><p role="status">{message}</p>{published&&<p><a href={'/documents/'+published.id+'?revision='+published.revision}>打开已发布文档 v{published.revision} ↗</a></p>}{preview&&<article><h2>{preview.document.title}</h2><p>{preview.document.summary}</p><p>适用:{preview.document.applies}</p><p className={styles.body}>{preview.document.body}</p>{preview.document.steps.map((s,i)=><p key={i}>{i+1}. {s}</p>)}{preview.links.map((l,i)=><p key={i}>{l.label} · 条件:{l.when} · {l.resolved?'精确版本可用':'目标缺失,读取时需跳过'}</p>)}<pre>{preview.xml}</pre></article>}</main>;
import Link from "next/link";
import { useRouter } from "next/router";
import { useEffect, useRef, useState } from "react";
import {
ArrowUpRight,
Braces,
CheckCircle2,
FileText,
Globe2,
Link2,
ListChecks,
Plus,
ShieldCheck,
Trash2,
} from "lucide-react";
import GuidanceShell, { useGuidanceAccount } from "@/components/GuidanceShell";
import {
EmptyState,
KindBadge,
Notice,
PageHeading,
kindNames,
} from "@/components/GuidanceUI";
import { guidanceXml, type Guidance } from "@/content/guides/catalog";
import s from "@/styles/guidance.module.css";
const blank: Guidance = {
id: "",
revision: 1,
kind: "guide",
title: "",
summary: "",
applies: "",
body: "",
steps: [],
checks: [],
links: [],
tags: [],
};
type Preview = {
document: Guidance;
xml: string;
links: { label: string; when: string; resolved: boolean }[];
};
function fieldName(path: string) {
const labels: Record<string, string> = {
id: "文档短名",
revision: "版本",
kind: "文档类型",
title: "标题",
summary: "一句话摘要",
applies: "适用条件",
body: "正文",
steps: "建议步骤",
checks: "完成检查",
tags: "标签",
target: "目标文档 ID",
relation: "关系类型",
when: "读取条件",
label: "链接标题",
};
const [group, index, field] = path.split(".");
if (group === "links")
return (
"关联文档" +
(index === undefined ? "" : " " + (Number(index) + 1)) +
(field ? " · " + (labels[field] || "内容") : "")
);
return (
(labels[group] || "文档内容") +
(index !== undefined ? " " + (Number(index) + 1) : "")
);
}
async function responseBody(response: Response) {
const body = await response
.json()
.catch(() => ({ error: "服务返回异常,请稍后重试" }));
if (!response.ok)
throw Error(
(body.error || "请求失败") +
(body.fields?.length
? ":" + body.fields.map(fieldName).join("、")
: ""),
);
return body;
}
export default function Write() {
return (
<GuidanceShell title="发布文档">
<Editor />
</GuidanceShell>
);
}
function Editor() {
const account = useGuidanceAccount(),
router = useRouter(),
dialog = useRef<HTMLDialogElement>(null);
const [doc, setDoc] = useState<Guidance>(blank),
[xml, setXml] = useState(""),
[mode, setMode] = useState<"form" | "xml">("form"),
[busy, setBusy] = useState(false),
[loading, setLoading] = useState(false),
[error, setError] = useState(""),
[preview, setPreview] = useState<Preview | null>(null),
[published, setPublished] = useState<{
id: string;
revision: number;
} | null>(null),
[dirty, setDirty] = useState(true);
const prefix = account.user ? "user-" + account.user.id + "-" : "",
editId = typeof router.query.id === "string" ? router.query.id : "";
useEffect(() => {
if (!router.isReady || !account.user) return;
let active = true;
setError("");
setPublished(null);
setPreview(null);
setMode("form");
setDirty(true);
if (!editId) {
setDoc({
...blank,
id:
"user-" +
account.user.id +
"-document-" +
Math.random().toString(16).slice(2, 8),
});
setLoading(false);
return;
}
if (!editId.startsWith("user-" + account.user.id + "-")) {
setError("只能编辑你自己发布的文档。");
setDoc(blank);
return;
}
setLoading(true);
fetch("/api/documents/" + encodeURIComponent(editId))
.then(responseBody)
.then((body) => {
if (active)
setDoc({ ...body.document, revision: body.document.revision + 1 });
})
.catch((e) => {
if (active) {
setError(e.message);
setDoc(blank);
}
})
.finally(() => {
if (active) setLoading(false);
});
return () => {
active = false;
};
}, [account.user?.id, editId, router.isReady]);
function change<K extends keyof Guidance>(key: K, value: Guidance[K]) {
setDoc((current) => ({ ...current, [key]: value }));
setPreview(null);
setDirty(true);
setPublished(null);
}
async function request(action: "preview" | "publish" | "convert") {
setBusy(true);
setError("");
setPreview(null);
try {
const body = await responseBody(
await fetch(
"/api/documents" + (action === "publish" ? "" : "/preview"),
{
method: "POST",
headers: {
"Content-Type":
mode === "xml" ? "application/xml" : "application/json",
},
body: mode === "xml" ? xml : JSON.stringify(normalized()),
},
),
);
if (action === "convert") {
setDoc(body.document);
setMode("form");
} else if (action === "preview") {
setPreview(body);
dialog.current?.showModal();
} else {
setDoc({ ...body.document, revision: body.document.revision + 1 });
setXml(
guidanceXml({
...body.document,
revision: body.document.revision + 1,
}),
);
setPublished({
id: body.document.id,
revision: body.document.revision,
});
setDirty(false);
}
} catch (e) {
setError(e instanceof Error ? e.message : "请求失败,请稍后重试");
} finally {
setBusy(false);
}
}
function normalized() {
return {
...doc,
steps: doc.steps.filter((step) => step.trim()),
checks: doc.checks.filter((check) => check.trim()),
tags: doc.tags.filter((tag) => tag.trim()),
};
}
function selectXml() {
setXml(guidanceXml(normalized()));
setMode("xml");
setPreview(null);
}
const authorized = account.user?.verified_at;
return (
<>
<PageHeading
title="发布独立文档"
description="一篇文档,一项清晰的指导。按需关联,让 Agent 自由选择。"
eyebrow={editId ? "UPDATE DOCUMENT" : "NEW DOCUMENT"}
/>
{account.loading ? (
<div className={s.accountLoading}>正在读取账户…</div>
) : !authorized ? (
<section className={`${s.panel} ${s.publishGate}`}>
<EmptyState
title={account.user ? "验证邮箱后继续" : "登录后开始编写"}
description={
account.error ||
"公开阅读无需登录。发布和维护文档,需要一个已验证的邮箱账户。"
}
>
<Link className={s.primaryButton} href="/account?next=%2Fwrite">
<ShieldCheck size={15} />
{account.user ? "前往验证邮箱" : "登录 / 创建账户"}
</Link>
</EmptyState>
</section>
) : (
<>
{error && <Notice tone="error">{error}</Notice>}
{published && (
<Notice tone="success">
版本 v{published.revision} 已公开发布。
<div className={s.successActions}>
<Link
href={
"/documents/" +
published.id +
"?revision=" +
published.revision
}
>
查看已发布版本
<ArrowUpRight size={12} />
</Link>
<Link href="/documents?scope=mine">查看我的文档</Link>
</div>
</Notice>
)}
{loading ? (
<div className={s.accountLoading}>正在加载最新版本…</div>
) : (
doc.id && (
<fieldset className={s.formFieldset} disabled={busy}>
<div className={s.editorTabs} aria-label="编辑方式">
<button
type="button"
aria-pressed={mode === "form"}
onClick={() => {
if (mode === "xml") void request("convert");
}}
>
可视化编辑
</button>
<button
type="button"
aria-pressed={mode === "xml"}
onClick={() => {
if (mode === "form") selectXml();
}}
>
协议 XML
</button>
</div>
<div className={s.formGrid}>
<div className={s.formSections}>
{mode === "xml" ? (
<section className={`${s.panel} ${s.formPanel}`}>
<h2 className={s.formSectionTitle}>
<Braces size={17} />
协议源文档
</h2>
<p className={s.formDescription}>
可直接粘贴完整
XML。切回可视化编辑时,会先校验并解析当前内容;校验失败时保留输入。
</p>
<label className={s.formField}>
<span className={s.fieldLabel}>XML 输入</span>
<textarea
className={`${s.textarea} ${s.xmlInput}`}
spellCheck={false}
value={xml}
onChange={(e) => {
setXml(e.target.value);
setDirty(true);
setPreview(null);
setPublished(null);
}}
/>
</label>
</section>
) : (
<>
<section className={`${s.panel} ${s.formPanel}`}>
<h2 className={s.formSectionTitle}>
<FileText size={17} />
基本信息
</h2>
<p className={s.formDescription}>
帮助读者和 Agent 判断,这篇文档是否适合当前任务。
</p>
<div className={s.fieldColumns}>
<label className={s.formField}>
<span className={s.fieldLabel}>文档短名</span>
<input
className={s.input}
aria-label="文档短名"
maxLength={37}
pattern="[a-z0-9-]+"
value={doc.id.slice(prefix.length)}
disabled={!!editId || doc.revision > 1}
onChange={(e) =>
change("id", prefix + e.target.value)
}
/>
<small className={s.fieldHint}>
小写字母、数字和连字符。发布后不可修改。
</small>
</label>
<label className={s.formField}>
<span className={s.fieldLabel}>文档类型</span>
<select
className={s.select}
value={doc.kind}
onChange={(e) =>
change(
"kind",
e.target.value as Guidance["kind"],
)
}
>
{Object.entries(kindNames).map(
([id, label]) => (
<option value={id} key={id}>
{label}
</option>
),
)}
</select>
</label>
</div>
{(["title", "summary", "applies"] as const).map(
(key) => (
<label className={s.formField} key={key}>
<span className={s.fieldLabel}>
{
{
title: "标题",
summary: "一句话摘要",
applies: "适用条件",
}[key]
}
<span className={s.required}>*</span>
</span>
{key === "title" ? (
<input
className={s.input}
value={doc[key]}
placeholder="例如:审查一次代码改动"
onChange={(e) =>
change(key, e.target.value)
}
/>
) : (
<textarea
className={s.textarea}
rows={2}
value={doc[key]}
placeholder={
key === "summary"
? "这篇文档可以帮助完成什么?"
: "什么情况下应该阅读?哪些情况不适用?"
}
onChange={(e) =>
change(key, e.target.value)
}
/>
)}
</label>
),
)}
<label className={s.formField}>
<span className={s.fieldLabel}>标签</span>
<input
className={s.input}
value={doc.tags.join(", ")}
placeholder="代码审查, 开发协作"
onChange={(e) =>
change(
"tags",
e.target.value
.split(/[,,]/)
.map((tag) => tag.trim()),
)
}
/>
<small className={s.fieldHint}>
使用逗号分隔。
</small>
</label>
</section>
<section className={`${s.panel} ${s.formPanel}`}>
<h2 className={s.formSectionTitle}>
<ListChecks size={17} />
指导内容
</h2>
<p className={s.formDescription}>
正文应当完整、可独立理解。步骤和检查项可以留空。
</p>
<label className={s.formField}>
<span className={s.fieldLabel}>
正文<span className={s.required}>*</span>
</span>
<textarea
className={`${s.textarea} ${s.bodyInput}`}
value={doc.body}
placeholder="写下清晰、具体的指导…"
onChange={(e) => change("body", e.target.value)}
/>
</label>
{(["steps", "checks"] as const).map((key) => (
<label className={s.formField} key={key}>
<span className={s.fieldLabel}>
{key === "steps" ? "建议步骤" : "完成检查"}
</span>
<textarea
className={s.textarea}
aria-label={
key === "steps" ? "建议步骤" : "完成检查"
}
rows={3}
value={doc[key].join("\n")}
onChange={(e) =>
change(key, e.target.value.split("\n"))
}
/>
<small className={s.fieldHint}>
每行一项,空行会在提交时忽略。
</small>
</label>
))}
</section>
<section className={`${s.panel} ${s.formPanel}`}>
<h2 className={s.formSectionTitle}>
<Link2 size={17} />
条件链接
<span className={s.neutralBadge}>
{doc.links.length}
</span>
</h2>
<p className={s.formDescription}>
仅当条件适用时,才建议读取关联文档。请指定固定版本;无需链接也可以独立发布。
</p>
{!doc.links.length && (
<div className={s.linkEmpty}>
还没有关联文档。你可以先完成正文,再为需要的场景补充链接。
</div>
)}
{doc.links.map((link, index) => (
<div className={s.linkEditor} key={index}>
<div className={s.linkEditorHeader}>
关联文档 {index + 1}
<button
type="button"
className={s.quietButton}
aria-label={"移除关联文档 " + (index + 1)}
onClick={() =>
change(
"links",
doc.links.filter((_, i) => i !== index),
)
}
>
<Trash2 size={13} />
移除
</button>
</div>
<div className={s.fieldColumns}>
{(
[
"target",
"revision",
"relation",
"label",
"when",
] as const
).map((key) => (
<label className={s.formField} key={key}>
<span className={s.fieldLabel}>
{
{
target: "目标文档 ID",
revision: "固定版本",
relation: "关系类型",
label: "链接标题",
when: "什么情况下读取",
}[key]
}
</span>
{key === "relation" ? (
<select
className={s.select}
value={link.relation}
onChange={(e) =>
change(
"links",
doc.links.map((item, i) =>
i === index
? {
...item,
relation: e.target
.value as Guidance["kind"],
}
: item,
),
)
}
>
{Object.entries(kindNames).map(
([id, label]) => (
<option value={id} key={id}>
{label}
</option>
),
)}
</select>
) : (
<input
className={s.input}
type={
key === "revision" ? "number" : "text"
}
min={key === "revision" ? 1 : undefined}
value={link[key]}
onChange={(e) =>
change(
"links",
doc.links.map((item, i) =>
i === index
? {
...item,
[key]:
key === "revision"
? Number(e.target.value)
: e.target.value,
}
: item,
),
)
}
/>
)}
</label>
))}
</div>
</div>
))}
<button
type="button"
className={s.secondaryButton}
onClick={() =>
change("links", [
...doc.links,
{
target: "",
revision: 1,
relation: "context",
when: "",
label: "",
},
])
}
>
<Plus size={14} />
添加条件链接
</button>
</section>
</>
)}
</div>
<aside className={s.publishSidebar}>
<section className={s.sideCard}>
<h3>
<Globe2 size={15} />
发布设置
</h3>
<div className={s.publishMeta}>
公开文档 · 待发布版本 v{doc.revision}
</div>
<KindBadge kind={doc.kind} />
<ul className={s.publishChecklist}>
<li className={s.completed}>
<CheckCircle2 size={14} />
邮箱已验证
</li>
<li>
<CheckCircle2 size={14} />
发布后任何人均可读取
</li>
<li>
<CheckCircle2 size={14} />
每次发布创建不可变版本
</li>
</ul>
<p>内容暂存在当前页面,请在离开前发布或自行保存 XML。</p>
<div className={s.publishButtons}>
<button
type="button"
className={s.secondaryButton}
onClick={() => void request("preview")}
>
校验并预览
</button>
<button
type="button"
className={s.primaryButton}
disabled={!dirty}
onClick={() => void request("publish")}
>
{busy
? "正在处理…"
: doc.revision === 1
? "发布文档"
: "发布新版本"}
</button>
</div>
</section>
<section className={s.sideCard}>
<h3>独立使用,按需连接</h3>
<p>
关系类型和适用条件帮助 Agent
选择下一篇文档。链接不会继承账户权限,也不要求整组加载。
</p>
<Link className={s.textLink} href="/protocol">
阅读协议说明
<ArrowUpRight size={12} />
</Link>
</section>
</aside>
</div>
</fieldset>
)
)}
</>
)}
<dialog
className={`${s.modal} ${s.largeModal}`}
ref={dialog}
aria-labelledby="preview-title"
>
<div className={s.modalBody}>
<h2 id="preview-title">发布预览</h2>
<p>校验已通过,内容尚未发布。请确认正文和关联条件。</p>
</div>
{preview && (
<div className={s.previewBody}>
<KindBadge kind={preview.document.kind} />
<h2 className={s.previewTitle}>{preview.document.title}</h2>
<p className={s.formDescription}>{preview.document.summary}</p>
<div className={s.appliesCard}>
<p>{preview.document.applies}</p>
</div>
<div className={s.proseBody}>{preview.document.body}</div>
{preview.document.steps.length > 0 && (
<ol className={s.stepList}>
{preview.document.steps.map((step, i) => (
<li key={i}>{step}</li>
))}
</ol>
)}
{preview.document.checks.length > 0 && (
<ul className={s.checkList}>
{preview.document.checks.map((check, i) => (
<li key={i}>{check}</li>
))}
</ul>
)}
{preview.links.map((link, i) => (
<div className={s.relationCard} key={i}>
<div>
<strong>{link.label}</strong>
<p>当{link.when}</p>
<small>
{link.resolved ? "固定版本可用" : "目标缺失,读取时需跳过"}
</small>
</div>
</div>
))}
</div>
)}
<div className={s.modalActions}>
<button
type="button"
className={s.secondaryButton}
onClick={() => dialog.current?.close()}
>
返回编辑
</button>
</div>
</dialog>
</>
);
}