Writing Back Upstream

Production cross-checks sources, and documentation lagging behind code is the normal case. By default the Agent corrects the knowledge from the code facts, so the knowledge is right but the original document stays stale. If you want the originals fixed too, ask the Agent to collect the differences as it goes and handle them together at the end.

flowchart LR
  diff["Document lags code"] --> fix["Knowledge follows<br/>the code facts"]
  diff --> log["Record in update-remote/<br/>context, judgment, suggestion"]
  log --> choose["After the task:<br/>you decide"]
  choose -->|authorized| write["Agent edits the original<br/>and reads it back"]
  choose -->|not now| sugg["Concise suggestion<br/>for the owner"]

Ask for it once

Add the instruction at the start of a task, or permanently in the AGENTS.md of the Context knowledge workspace:

When a revision is caused by documentation lagging behind the code, record it
in update-remote/<date>-<topic>.md with the context, the judgment and the
suggested change. After the task, work through update-remote: find each
upstream document and either revise it or give a concise suggestion for me
to decide on.

Upstream documents then catch up promptly, and knowledge and originals do not drift apart for long.

Is the original actually wrong?

Before proposing an upstream edit, the Agent distinguishes three cases:

Case	What happens
The knowledge misunderstood correct source text	Only the local page is corrected
A confirmed decision has not reached the document	The decision can be saved as a local note while the upstream change is considered
The conclusion is still uncertain	It is not written anywhere as fact

Making the edit

Neither approving knowledge nor fully managed mode authorizes a remote write. For each edit, the Agent shows the exact document, the affected passage, the before/after text, the reason and the knowledge it affects, and uses an authorization you have already given for that concrete edit or asks for one. It rereads the passage just before writing, adapts only within the authorized scope if someone else changed it, writes with its document tool and reads the result back.

The returned document then feeds the normal capture and update flow, so the local snapshot reflects what is really upstream. If the remote edit succeeded but the local build failed, the Agent resumes the local delivery rather than editing again. It does not post comments, notify groups or change permissions; when it lacks permission, it leaves you a concrete suggestion.

回写上游

生产过程会交叉核对各个来源，而文档落后于代码是常态。默认情况下，Agent 依据代码事实修正知识，因此知识是正确的，但原始文档仍然过时。如果你也希望修正原文，可以请 Agent 在过程中收集差异，并在最后统一处理。

flowchart LR
  diff["文档落后于代码"] --> fix["知识遵循<br/>代码事实"]
  diff --> log["记录到 update-remote/<br/>背景、判断、建议"]
  log --> choose["任务结束后：<br/>由你决定"]
  choose -->|已授权| write["Agent 编辑原文<br/>并回读确认"]
  choose -->|暂不处理| sugg["给负责人的<br/>简明建议"]

只需提一次

在任务开始时加入这条指令，或者把它永久写进 Context 知识工作区的 AGENTS.md：

When a revision is caused by documentation lagging behind the code, record it
in update-remote/<date>-<topic>.md with the context, the judgment and the
suggested change. After the task, work through update-remote: find each
upstream document and either revise it or give a concise suggestion for me
to decide on.

这样上游文档就能及时跟上，知识和原文也不会长期脱节。

原文真的错了吗？

在提议修改上游之前，Agent 会区分三种情况：

情况	处理方式
知识误解了正确的来源文本	只修正本地页面
已确认的决定尚未写入文档	可以先把该决定保存为本地笔记，同时考虑上游修改
结论仍不确定	不会作为事实写到任何地方

执行编辑

无论是批准知识还是全托管模式，都不授权远程写入。对于每一处编辑，Agent 都会展示具体文档、受影响的段落、修改前后的文本、原因以及它影响的知识，并使用你已为这处具体编辑给出的授权，或向你申请授权。它会在写入前重新读取该段落，如果有人改动过，只在授权范围内做调整，然后用文档工具写入并回读结果。

修改后的文档随后进入常规的采集和更新流程，使本地快照反映上游的真实内容。如果远程编辑成功但本地构建失败，Agent 会继续完成本地交付，而不是再次编辑。它不会发表评论、通知群组或修改权限；当缺少权限时，它会给你留下一条具体建议。