为什么要做成“后端”#

过去用 AI 辅助科研写作时，我反复遇到一个问题：模型本身很会生成文字，但它不知道哪些东西在我的知识系统里已经被审查过，哪些只是 source card，哪些只是 raw PDF，哪些是旧计划，哪些是可以写进论文的证据。

如果不加约束，agent 很容易把以下东西混在一起：

• “文献存在”与“文献支持这个 claim”；
• “source card 摘要”与“publication-grade evidence”；
• “某次实验结果”与“可跨论文复用的 truth evidence”；
• “human review ready”与“release ready”；
• “润色得更像人”与“把证据不足的话说得更强”。

所以 yxj-wiki 的设计目标不是让 agent 更自由，而是让 agent 在足够多的本地知识中，被正确地限制。

我想要的系统不是：

1
给模型一堆文献 → 让它总结 → 让它写论文

而是：

1
source identity
2
→ source card / cluster
3
→ locator-backed evidence
4
→ reviewed truth / claim / ontology
5
→ writing contract
6
→ paragraph plan
7
→ draft candidate
8
→ audit
9
→ minimal patch
10
→ human boundary

这条链的重点是：每一层都知道自己能做什么，也知道自己不能越界做什么。

总体架构：从 raw 到 release boundary#

yxj-wiki 现在大致分成这些层：

其中最重要的原则是：越接近发布，越需要 schema、locator、review 和 human boundary。

1
当前任务说明
2
→ AGENTS.md
3
→ 当前架构入口
4
→ status dashboard / production seal
5
→ backend interface
6
→ object contracts
7
→ refs / source cards / clusters
8
→ truth / writing objects
9
→ source-local cache
10
→ raw only with explicit locator reason

核心理念一：引用不是证据，证据不是 claim#

yxj-wiki 的第一条理念是把科研写作里常被混淆的对象拆开。

一篇论文被注册到 refs/registry.jsonl，只表示它有稳定 source identity 和 citekey。它可以被检索、导出、放入 BibTeX，但这还不意味着它支持某个具体 claim。

一个 source card 可以帮助我记住这篇文章讲了什么、有哪些可复用观点、适合放在哪个 cluster，但它也还不是 publication-grade evidence。

真正能支撑写作中强句子的，是更靠后的对象：

1
claim_id
2
→ evidence_id
3
→ citekey
4
→ locator
5
→ support_label
6
→ conflict_policy
7
→ review gate

这也是为什么我不希望 agent 看到一篇文章标题后就自动写出“已有研究表明”。它必须知道：

• 这个 claim 是不是已经被审查；
• evidence 有没有 locator；
• support 是 strong、partial、weak，还是 conflict；
• 有没有冲突文献要披露；
• 这句话是否超过了证据强度。

核心理念二：ontology 是防止“会写但概念乱”的工具#

很多 AI 写作的问题不是语法错，而是 ontology 错。比如它会把方法、机制、架构、指标、实验条件、设计目标和行动策略混成一类。

yxj-wiki 的 truth/ 层不只存 claim，也存：

• concept；
• term / sense；
• relation；
• measurement model；
• Toulmin claim；
• conflict；
• writing claim binding。

这样做的意义不是形式主义，而是为了让 agent 在写作前先弄清楚：

• 这是一个对象、关系、功能、方法，还是指标？
• 这个词在当前论文里是哪一个 sense？
• 这个 claim 是描述事实、提出机制、还是给出评价？
• 这个实验结果支持的是性能提升、机制解释，还是工程可行性？

当 ontology 边界清楚后，写作会更自然，因为文章不会一直在概念层级之间跳来跳去。

核心理念三：写作不是润色，而是 reader-state control#

这次升级里我最重视的是写作模块。它不是普通润色器，也不是 RAG 写手，而是一个受后端约束的 writing production layer。

它的链条是：

1
reviewed material / source identity
2
→ writing memory / doctrine
3
→ writing brief
4
→ manuscript contract
5
→ claim-evidence contract
6
→ rhetorical + voice/style contract
7
→ paragraph plan
8
→ draft candidate
9
→ review audits
10
→ minimal revision patch
11
→ human_review_ready boundary

它吸收的写作理念可以概括成几条：

1. 论文不是句子集合，而是 main point + narrative arc。 先决定读者应该经历什么，再决定每段写什么。
2. 清晰度不是“写得简单”，而是控制读者认知负荷。 术语、背景、转折、限定都要服务于读者状态变化。
3. metadiscourse 是读者接口。 transition、frame marker、hedge、booster、engagement 不是装饰，而是导航。
4. claim strength 必须匹配 evidence strength。 写得顺不代表能写得强。
5. 人类风格不是表面去 AI 腔。 真正的人类风格来自具体判断、限定、作者责任和段落功能，而不是随机改写。
6. revision 应该是 minimal patch。 能改一句就不要重写整段，否则 trace 会丢。

所以我希望 agent 写作时不要只说“帮我润色”，而是先问：

• 这一节要让读者相信什么？
• 读者在进入这一段前知道什么？
• 读完这一段后应该获得什么状态？
• 哪些 claim 可以强说，哪些只能弱说？
• 哪些地方需要 hedge，哪些地方需要 booster？

写作模块现在有哪些组件#

1
writing/briefs/<project>.yaml
2
writing/contracts/manuscript/<project-section>.yaml
3
writing/contracts/claim_evidence/<project-section>.tsv
4
writing/contracts/rhetorical/<project-section>.tsv
5
writing/contracts/voice_style/<project-section>.yaml
6
writing/plans/section_claim_maps/<project-section>.tsv
7
writing/reviews/**/<project-section>-*.json

1
research-paper-workspace
2
→ scientific-story-contract
3
→ reader-state-contract
4
→ experiment-repo-manifest
5
→ method-contract / experiment-contract
6
→ result-packet
7
→ figure-table-registry
8
→ result-claim-contract
9
→ narrative-safety-audit

1
writing/papers/<paper_id>/

如何在外部论文仓库使用#

具体文章的 LaTeX、实验代码、图表和结果文件通常在外部仓库。此时推荐使用“双仓协议”：

1
external paper repo
2
  manuscript / code / experiments / results / figures
3
        ⇅ manifest + contracts + audits
4
yxj-wiki
5
  refs / truth / writing memory / writing contracts / writing/papers / reviews

外部仓库中的 Codex 应该先建立 session handshake：

1
external_repo_path: <current working directory>
2
yxj_wiki_path: /path/to/yxj-wiki
3
paper_id: <stable id>
4
article_type: method_experiment_results
5
write_intent: init_backend | update_backend | draft_patch | audit_patch
6
external_write_scope:
7
  - manuscript/sections/*.tex
8
yxj_write_scope:
9
  - writing/papers/<paper_id>/
10
command_execution: false by default
11
release_ready_mutation: forbidden

最常用的一句启动语可以是：

1
使用 $yxj-backend，以 /path/to/yxj-wiki 作为受控写作后端。
2
当前仓库是论文生产仓库，请进入 research_paper_writer 模式。
3
先检查后端状态，读取写作模块和外部仓库协议；
4
只在允许范围内读取当前论文仓库，不执行实验，不设置 release_ready。

如果文章已经写了一半，也可以中途接入：

1
使用 $yxj-backend。
2
当前文章已经写作一大半，请进入 mid-draft intervention 模式。
3
先只读稿件、实验结果、图表和 bib，诊断叙事链、claim-evidence 对齐、读者路径和文风问题；
4
输出最小修补 / 中等重构 / 深度重写三个方案，等我确认后再 patch。

我现在比较推荐的实际工作流是：

1
题目和实验基本确定
2
→ deep-interview 访谈核心贡献、读者和结果
3
→ ralplan 生成写作计划
4
→ ralph 顺序执行计划
5
→ yxj-backend 提供资料、contract、audit 和 handoff
6
→ 外部论文仓库只接收经过约束的正文 patch

三种典型使用模式#

1
使用 $yxj-backend 查询 yxj-wiki 中关于 <topic> 的 refs/source-card/wiki/truth/writing surfaces。
2
返回可用于论文写作的材料、已有 claim、缺口和不能越界使用的内容。

1
使用 $yxj-backend + deep-interview。
2
我已经确定题目并完成实验，现在要写 method/experiment/results 类型论文。
3
请先访谈我：核心贡献、实验设置、最强结果、目标期刊、不能夸大的地方。
4
然后建立 paper_id 和 writing/papers/<paper_id>/ 工作区。

1
先做诊断，不改正文。
2
检查 abstract/introduction/method/results/discussion 的叙事链，标出 claim-evidence 不对齐、读者状态断裂、metadiscourse 缺失、AI 腔和过度 claim。
3
然后给出分级修订计划。

验证和边界#

yxj-wiki 的一个重要特点是：很多操作都要留下 machine-readable evidence。

常用检查包括：

1
make verify
2
make writing-verify
3
make research-paper-verify
4
make p4-verify
5
make production-seal-verify
6
python scripts/build_system_status.py --repo-root . --check --json
7
git diff --check

对 release 相关内容，还要检查不能出现非法：

1
grep -RInE 'release_ready: *true|"release_ready" *: *true' writing/releases writing/reviews refs/reviews patches || true

现在 production seal 的状态是 warning，但 warning 是设计内的：

• 仍有 P4 residual locator queue pressure；
• P4 release packets 仍需要 human review；
• 可能存在 generated artifact freshness warning。

这不妨碍它作为 controlled backend 使用，但提醒 agent：不要把后端可用性误读成发布批准。

当前完成度和不足#

可以投入使用的部分：

• source/citation registry 与 BibTeX 管理；
• source-card / cluster 中间层；
• reviewed truth / ontology / claim / conflict 层；
• writing memory 和 writing contracts；
• P8 method/experiment/result paper workspace；
• 外部论文仓库双仓协议；
• writing audit / policy / metadiscourse / result grounding 检查；
• production handoff 和 GitHub 同步；
• 统一 yxj-backend skill 入口。

仍然需要后续推进的部分：

• 很多 source 仍是 source_identity_only，不是 source-card 或 truth evidence；
• raw 文档没有全部深度消化为 locator-backed evidence；
• P8 的实验结果目前是 paper-local support，不是 live truth evidence；
• paragraph plan builder 和 minimal patch workflow 还可以继续 schema 化；
• 针对具体期刊的 policy profile 仍可增强；
• release 仍必须停在人类审批边界。

我希望它最终带来的变化#

我做 yxj-wiki 后端，不是为了让 agent 代替我“自动写论文”。相反，它的目标是让 agent 在写作时更像一个知道边界的研究助手：

• 它知道哪些材料只是线索；
• 它知道哪些 claim 已经被审查；
• 它知道什么时候该 hedge；
• 它知道一段话的读者功能；
• 它知道不能把漂亮句子写得比证据更强；
• 它知道什么时候必须停下来等人类批准。

理想情况下，我只需要在外部论文仓库中告诉 Codex：

1
使用 $yxj-backend，把 yxj-wiki 作为后端，帮我设计这篇文章的故事线并修改当前稿件。

然后 agent 会自动回到正确的资料层、写作层、审查层和 release 边界，而不是临场乱写。

这才是我理解的个人科研知识库后端：它不是把知识堆起来，而是让知识在写作生产中被正确调用、被正确限制、被正确交接。