查看开源仓库 ↗

一篇技术文章不该只是一段被人阅读后遗忘的文本。对个人知识库而言，更理想的形态是：它既能被读者顺畅地通读，也能被 Agent 定位、提取、比较，并在下一次研究或写作中继续使用。

本文既是一份工作流草案，也是 AgentPress 的长文展示样例。它刻意使用了标题层级、提示块、引用、代码、数学公式、表格、图像和流程图，便于集中检查阅读页的细节。

问题：文章为什么很难被继续使用

大多数笔记的问题不在于没有内容，而在于内容只适合第一次阅读。结论散落在段落中，引用没有上下文，图表缺少说明；当人或 Agent 需要回答一个更具体的问题时，只能从头再读一遍。

两种读者，同一份材料

人的阅读是连续的：先理解动机，再跟随论证，最后形成判断。Agent 的读取更接近按需检索：先看摘要和元数据，命中某一个章节，再回到原文验证。两者并不矛盾，关键是让结构成为正文的一部分。

好的技术写作不是把答案藏在文章里，而是让答案有清晰的地址、边界和来路。

一个最小的判断标准

如果六个月后的自己能在一分钟内回答下面三个问题，这篇文章就具有了初步的复用价值：

1. 它试图解决什么问题？
2. 结论依赖哪些假设与证据？
3. 哪个部分值得继续实验、反驳或引用？

文章的双层结构

我倾向于把文章理解为两层：面向读者的叙事层，以及面向工具的结构层。叙事层负责让复杂问题有节奏；结构层则提供稳定的锚点、字段和链接。

叙事层：从问题到可行动的结论

技术文章可以使用一个稳定的骨架：背景、问题、方法、证据、限制与下一步。这个顺序并非模板主义，而是减少读者在不同文章之间切换成本的方式。

结构层：让内容有可引用的坐标

标题、frontmatter 和原始 MDX 共同构成文章的坐标系统。标题提供了自然语言地址；frontmatter 提供了类型、日期、标签和关系；原始 MDX 则保留了人类上下文，避免结构化摘要切断论证链。

一份最小可用的元数据契约

元数据的目标不是“完整描述世界”，而是让常见的筛选和引用无需猜测。以下是本项目中一篇技术报告可使用的最小字段集合。

核心字段

title: "把一篇技术文章做成 Agent 可复用的知识节点"
type: technical-report
publishedAt: 2026-07-11
tags: ["Agent Native", "Knowledge Base"]
agent:
  summary: "可被 Agent 读取、定位和复用的文章组织方式。"
  sourceQuality: personal
  reuseLevel: high
  related: ["agent-memory-report"]

其中 type 决定卡片与归档中的呈现方式；tags 适合横向发现；agent.summary 用于让自动化读取先建立低成本判断。三者各自有边界，不应互相替代。

质量与来源不是同一个维度

来源质量描述“材料来自哪里”，复用等级描述“它有多适合被再次使用”。一篇个人实验记录可能是 personal，但如果假设、步骤和环境写得足够清楚，它同样可以是 high 复用等级。

从原始材料到发布页面

发布不只是把 Markdown 变成 HTML。它包含信息压缩、结构化、构建和暴露接口几个阶段；每一步都应该保留可追溯的输入和输出。

flowchart LR
  A[原始笔记与资料] --> B[MDX 正文]
  B --> C[Frontmatter 校验]
  C --> D[静态构建]
  D --> E[阅读页面]
  D --> F[JSON 元数据]
  D --> G[原始 MDX 接口]
  F --> H[Agent 检索]
  G --> H

写作阶段：先保护原始语境

原始资料可能是论文批注、命令行输出、会议记录或一个未经验证的想法。写作时不要急于把所有内容压缩成结论；先保留来源链接、时间和不确定性。之后再把可复用的部分抽成章节、表格或提示块。

构建阶段：把检查前移

内容模式校验可以在构建时发现日期、链接和文章类型的错误。与其在部署后修复一个损坏的页面，不如让构建在字段不完整时失败。

type Evidence = {
  claim: string;
  source: URL;
  confidence: 'low' | 'medium' | 'high';
};

const isReusable = (items: Evidence[]) =>
  items.some((item) => item.confidence === 'high') &&
  items.every((item) => item.claim.length > 0);

这里的代码并不试图判定“真相”，它只是在发布前确认最基本的证据描述没有丢失。

分发阶段：同一内容，不同入口

页面是为阅读准备的；JSON 是为快速概览和筛选准备的；原始 MDX 则为需要完整上下文的 Agent 或工具保留。三种入口共享同一个源文件，避免多处维护带来的漂移。

阅读体验也是信息架构

视觉设计并非内容的装饰。清晰的行长、标题层级和间距，会直接影响读者能否识别论证边界。长文尤其需要在“连续阅读”和“快速跳转”之间取得平衡。

长目录：导航，而非另一个页面

当可导航的标题达到一定数量时，右侧目录提供一条低干扰的路径。目录应该短、稳定，并在悬浮时才显露完整标题；它的功能是告诉读者文章还有哪些部分，而不是把正文再复制一遍。

本篇文章包含多个二级与三级标题，因此会触发右侧的短横条目录。少于四个标题的短文则不显示目录，避免为极少量内容额外制造视觉重心。

图像应有自己的语义

图像至少需要有替代文本；当它参与论证时，还需要图注说明“读者应该从中看见什么”。如果图片只是装饰，应避免让它承担关键事实。

数学与符号的边界

对于需要量化的讨论，公式应解释变量含义，而不是用符号制造复杂感。例如，可以用一个极简指标描述某个知识节点的再利用优先级：

$$ R = (c × e × a) / (1 + t) $$

其中 $c$ 表示结论清晰度，$e$ 表示证据完备度，$a$ 表示可行动性，$t$ 表示距上次复核的时间。这个式子不是正式评价模型，但它提醒我们：旧内容并不会因为写得长就自动具有复用价值。

给 Agent 的读取顺序

Agent 读取个人知识库时，最容易犯的错误是过早生成结论。一个更稳妥的顺序是：先判断相关性，再读取证据，最后返回带出处的答案。

第一步：低成本筛选

先读取标题、描述、文章类型、标签与 Agent 摘要。它们用于回答“是否值得打开原文”，而不是替代原文。

第二步：按标题定位

如果问题与“发布流程”相关，直接进入对应章节；如果问题需要比较多个观点，再读取相关段落周围的上下文。标题是最轻量也最稳定的检索锚点。

第三步：回到原文核验

任何可能影响决策的结论，都应该回到原始 MDX 或引用资料核验。对不确定的内容，应保留来源、章节和置信度，而不是输出没有边界的断言。

输入：用户问题
  ↓
筛选：metadata / tags / summary
  ↓
定位：heading anchors
  ↓
核验：MDX source + cited evidence
  ↓
输出：结论 + 范围 + 可追溯链接

一个可执行的维护节奏

知识库不需要每天大规模重构，但需要一个轻量、可持续的维护节奏。下面的节奏适合个人站点，也容易被自动化工具协助。

每次发布

• 补齐标题、描述、日期与文章类型。
• 为至少一个关键结论标记来源或不确定性。
• 确认文章在手机与桌面宽度下均可阅读。
• 让构建检查链接、内容模式和静态页面。

每月回顾

• 合并意思相近、相互矛盾或已被新证据覆盖的笔记。
• 检查高复用文章的链接是否仍然有效。
• 将反复被访问的段落抽成独立文章或更明确的索引。

限制与开放问题

这个方案并不解决所有问题。标签仍可能膨胀，摘要仍可能丢失细节，静态构建也不能替代访问控制。更重要的是，Agent 的授权、写入范围与审计记录，需要在后续管理接口中单独设计。

仍待验证的假设

1. 结构化摘要是否能显著降低 Agent 的无效全文读取？
2. 文章间关系应由作者手工维护，还是允许 Agent 提出候选链接？
3. 对于持续更新的技术报告，版本与引用应如何同时保持稳定？

这些问题暂时没有标准答案。把它们公开写在文章里，比假装系统已经完整更有价值。

结语：把未来的自己也当成读者

个人知识中心最终服务的不是某一个页面，而是一连串未来的问题。每篇文章都应该让未来的自己、协作者和被授权的 Agent 以合适的成本重新进入当时的思考。

从一个清晰的标题、一段诚实的摘要和一个可跳转的章节开始，就足够了。其余的能力，可以随着真实的使用场景慢慢长出来。