From 59c9dd5153c8279835e3d66d6474a794368285d2 Mon Sep 17 00:00:00 2001
From: JianFeeeee <root@qq.com>
Date: Sat, 15 Aug 2026 18:08:01 +0800
Subject: [PATCH] =?UTF-8?q?docs+test:=20Lua=20stage=20=E5=86=99=E5=9B=9E?=
 =?UTF-8?q?=E8=83=BD=E5=8A=9B=E6=96=87=E6=A1=A3=E4=B8=8E=E6=B5=8B=E8=AF=95?=
 =?UTF-8?q?(=E4=B8=8E=20C=20ABI=20v2=20=E5=AF=B9=E9=BD=90)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 assets/docs/en/PLUGIN_DEV.md | 15 +++++++++++++++
 assets/docs/zh/PLUGIN_DEV.md | 15 +++++++++++++++
 2 files changed, 30 insertions(+)

diff --git a/assets/docs/en/PLUGIN_DEV.md b/assets/docs/en/PLUGIN_DEV.md
index 3536d81..5da2c56 100644
--- a/assets/docs/en/PLUGIN_DEV.md
+++ b/assets/docs/en/PLUGIN_DEV.md
@@ -594,6 +594,21 @@ The `sdk.*` API of Lua plugins is fully aligned with external plugins (C ABI / t
 
 Stage handlers receive the full context (same as external plugins): `raw_message`, `user_id`, `group_id`, `phase`, `llm_text`, `final_text`, `no_memory`, `response` (when responded), `tool_calls`, `tool_results`.
 
+**Stage writeback (ABI v2)**: the `ctx` table passed to the handler is a reference — mutating writable fields inside the handler syncs back to the core `StageContext` (aligned with the C ABI v2 external-plugin capability):
+
+```lua
+sdk.register_stage("on_input", function(ctx)
+  ctx.raw_message = "[clean]" .. ctx.raw_message   -- modify input, adopted by core
+end)
+
+sdk.register_stage("post_action", function(ctx)
+  ctx.llm_text = ctx.llm_text .. "[tail]"            -- modify LLM output
+  ctx.tool_results = { { call_id = "x", result = "rewritten" } }
+end)
+```
+
+Writable fields: `raw_message`, `llm_text`, `final_text`, `user_id`, `group_id`, `no_memory`, `response`, `tool_calls`, `tool_results`. Other fields are read-only.
+
 **IO and config**
 
 | Function | Description |
diff --git a/assets/docs/zh/PLUGIN_DEV.md b/assets/docs/zh/PLUGIN_DEV.md
index b9dea75..2b56859 100644
--- a/assets/docs/zh/PLUGIN_DEV.md
+++ b/assets/docs/zh/PLUGIN_DEV.md
@@ -593,6 +593,21 @@ Lua 插件的 `sdk.*` API 与外部插件（C ABI / 工具链编译的 `.so`/`.d
 
 `register_stage` 的 handler 收到完整上下文（与外部插件一致）：`raw_message`、`user_id`、`group_id`、`phase`、`llm_text`、`final_text`、`no_memory`、`response`（已响应时）、`tool_calls`、`tool_results`。
 
+**Stage 写回（ABI v2）**：handler 收到的 `ctx` 是引用 table——在 handler 内直接修改可写回字段并同步至内核 `StageContext`（与 C ABI v2 外部插件能力对齐）：
+
+```lua
+sdk.register_stage("on_input", function(ctx)
+  ctx.raw_message = "[清洗]" .. ctx.raw_message   -- 修改输入，内核会采用
+end)
+
+sdk.register_stage("post_action", function(ctx)
+  ctx.llm_text = ctx.llm_text .. "[尾部标记]"       -- 修改 LLM 输出
+  ctx.tool_results = { { call_id = "x", result = "改写结果" } } -- 改写工具结果
+end)
+```
+
+可写回字段：`raw_message`、`llm_text`、`final_text`、`user_id`、`group_id`、`no_memory`、`response`、`tool_calls`、`tool_results`。其余字段为只读。
+
 **IO 与配置**
 
 | 函数 | 说明 |