From 6b748fbd109c3066c5656c215807e1b0af1b3545 Mon Sep 17 00:00:00 2001
From: haochen <sumtsui@gmail.com>
Date: Tue, 16 Jun 2026 11:15:43 +0800
Subject: [PATCH 1/2] docs(web): clarify tui plugin logging

---
 packages/web/src/content/docs/plugins.mdx       | 10 +++++++++-
 packages/web/src/content/docs/zh-cn/plugins.mdx | 10 +++++++++-
 2 files changed, 18 insertions(+), 2 deletions(-)

diff --git a/packages/web/src/content/docs/plugins.mdx b/packages/web/src/content/docs/plugins.mdx
index a8be798217a8..7db066fa3cc9 100644
--- a/packages/web/src/content/docs/plugins.mdx
+++ b/packages/web/src/content/docs/plugins.mdx
@@ -105,7 +105,13 @@ export const MyPlugin = async (ctx) => {
 
 ```js title=".opencode/plugins/example.js"
 export const MyPlugin = async ({ project, client, $, directory, worktree }) => {
-  console.log("Plugin initialized!")
+  await client.app.log({
+    body: {
+      service: "my-plugin",
+      level: "info",
+      message: "Plugin initialized",
+    },
+  })
 
   return {
     // Hook implementations go here
@@ -113,6 +119,8 @@ export const MyPlugin = async ({ project, client, $, directory, worktree }) => {
 }
 ```
 
+For TUI plugins, avoid `console.log()` and `console.error()`. They write to the same terminal session as the client UI and can disrupt the input area. Prefer `client.app.log()` instead.
+
 The plugin function receives:
 
 - `project`: The current project information.
diff --git a/packages/web/src/content/docs/zh-cn/plugins.mdx b/packages/web/src/content/docs/zh-cn/plugins.mdx
index e8a8bd70cbc3..2b078c7a358c 100644
--- a/packages/web/src/content/docs/zh-cn/plugins.mdx
+++ b/packages/web/src/content/docs/zh-cn/plugins.mdx
@@ -104,7 +104,13 @@ export const MyPlugin = async (ctx) => {
 
 ```js title=".opencode/plugins/example.js"
 export const MyPlugin = async ({ project, client, $, directory, worktree }) => {
-  console.log("Plugin initialized!")
+  await client.app.log({
+    body: {
+      service: "my-plugin",
+      level: "info",
+      message: "Plugin initialized",
+    },
+  })
 
   return {
     // Hook implementations go here
@@ -112,6 +118,8 @@ export const MyPlugin = async ({ project, client, $, directory, worktree }) => {
 }
 ```
 
+对于 TUI 插件，避免使用 `console.log()` 和 `console.error()`。它们会写到和客户端 UI 共用的终端会话里，可能干扰输入区；应优先使用 `client.app.log()`。
+
 插件函数接收以下参数：
 
 - `project`：当前项目信息。

From 41ed9e5c6653b804d64d4b70f7540a7606e6e911 Mon Sep 17 00:00:00 2001
From: haochen <sumtsui@gmail.com>
Date: Tue, 16 Jun 2026 11:50:07 +0800
Subject: [PATCH 2/2] docs(web): keep english-only plugin logging note

---
 packages/web/src/content/docs/zh-cn/plugins.mdx | 10 +---------
 1 file changed, 1 insertion(+), 9 deletions(-)

diff --git a/packages/web/src/content/docs/zh-cn/plugins.mdx b/packages/web/src/content/docs/zh-cn/plugins.mdx
index 2b078c7a358c..e8a8bd70cbc3 100644
--- a/packages/web/src/content/docs/zh-cn/plugins.mdx
+++ b/packages/web/src/content/docs/zh-cn/plugins.mdx
@@ -104,13 +104,7 @@ export const MyPlugin = async (ctx) => {
 
 ```js title=".opencode/plugins/example.js"
 export const MyPlugin = async ({ project, client, $, directory, worktree }) => {
-  await client.app.log({
-    body: {
-      service: "my-plugin",
-      level: "info",
-      message: "Plugin initialized",
-    },
-  })
+  console.log("Plugin initialized!")
 
   return {
     // Hook implementations go here
@@ -118,8 +112,6 @@ export const MyPlugin = async ({ project, client, $, directory, worktree }) => {
 }
 ```
 
-对于 TUI 插件，避免使用 `console.log()` 和 `console.error()`。它们会写到和客户端 UI 共用的终端会话里，可能干扰输入区；应优先使用 `client.app.log()`。
-
 插件函数接收以下参数：
 
 - `project`：当前项目信息。