Feat: tRPC-Agent对齐Claude Code Plan Mod能力

Author: jinfengliu-688

docs/mkdocs/en/index.md

@@ -16,6 +16,7 @@ Welcome to the English documentation for tRPC-Agent-Python.
 - [Memory](./memory.md): Store and retrieve long-term memories.
 - [Knowledge](./knowledge.md): Build RAG workflows with LangChain components.
 - [Multi-Agent](./multi_agents.md): Compose agents for complex workflows.
+- [Plan Mode](./plan.md): Design-then-implement workflow with write gate and HITL approval.
 - [Evaluation](./evaluation.md): Evaluate agent behavior and response quality.
 
 For source code and examples, see the [GitHub repository](https://github.com/trpc-group/trpc-agent-python).

docs/mkdocs/en/plan.md

@@ -16,6 +16,7 @@
 - [Memory](./memory.md)：存储和检索长期记忆。
 - [Knowledge](./knowledge.md)：基于 LangChain 组件构建 RAG 工作流。
 - [多 Agent](./multi_agents.md)：编排多个 Agent 完成复杂任务。
+- [Plan Mode](./plan.md)：先规划后实施，写工具 gate + HITL 审批。
 - [Evaluation](./evaluation.md)：评测 Agent 行为和回复质量。
 
 源码与示例请参考 [GitHub 仓库](https://github.com/trpc-group/trpc-agent-python)。

docs/mkdocs/zh/index.md

@@ -0,0 +1,4 @@
+# Set TRPC_AGENT_API_KEY、TRPC_AGENT_BASE_URL、TRPC_AGENT_MODEL_NAME
+TRPC_AGENT_API_KEY=your-api-key
+TRPC_AGENT_BASE_URL=your-base-url
+TRPC_AGENT_MODEL_NAME=your-model-name

docs/mkdocs/zh/plan.md

@@ -0,0 +1,100 @@
+# Plan Mode 示例
+
+演示 tRPC-Agent-Python 的 **Plan Mode**：用 `setup_plan()` 给 LLM Agent 装上「先规划、后实施」的工作流，并配合 `SpawnSubAgentTool`（Explore / Plan 两种子 agent 原型）完成代码探索与方案设计。
+
+## 它解决什么问题
+
+普通 coding agent 容易上来就改文件、边写边改方向。Plan Mode 把流程拆成两段：
+
+1. **规划阶段** —— 模型只能用只读工具（Read / Grep / Glob）和子 agent（Explore / Plan）调研代码、撰写计划文档；写文件、改代码、执行命令等「副作用」工具被自动 gate，直到计划被人工批准。
+2. **实施阶段** —— 计划通过后，写工具自动解锁，模型按照批准的计划落地实现，并可用 `todo_write` 跟踪进度。
+
+规划期间需要人工介入的三个动作——`enter_plan_mode` / `exit_plan_mode` / `ask_user_question`——都是 `LongRunningFunctionTool`，运行会暂停等待人类响应。这种交互用浏览器页面承载比 CLI 更自然，所以本示例同时提供了一个 AG-UI 服务端和一张零依赖的静态页面。
+
+## 目录结构
+
+```
+plan_mode/
+├── agent/
+│   ├── agent.py        # orchestrator agent 定义：FileToolSet + SpawnSubAgentTool + TodoWriteTool + setup_plan
+│   ├── prompts.py      # system instruction
+│   └── __init__.py
+├── static/
+│   └── index.html      # AG-UI 浏览器 Demo（单文件，无构建依赖）
+├── run_agent_with_agui.py  # FastAPI + AG-UI 服务端，托管 agent 接口与静态页
+├── .env                # 模型配置（TRPC_AGENT_API_KEY / BASE_URL / MODEL_NAME）
+└── README.md
+```
+
+## 架构
+
+```
+orchestrator (LlmAgent + setup_plan)
+├── FileToolSet         # Read/Grep/Glob 始终可用；Write/Edit/Bash 在计划批准后解锁
+├── SpawnSubAgentTool(EXPLORE_AGENT, PLAN_AGENT)  # 只读调研与方案设计子 agent
+├── TodoWriteTool       # 实施阶段用于跟踪进度
+└── PlanToolSet         # enter_plan_mode / update_plan_content / exit_plan_mode / ask_user_question
+```
+
+- 计划文档持久化在**主 agent 的 session** 中（`state["plan"]`）。
+- 被 spawn 出来的子 agent 只返回文本，不直接改动主 agent 的状态。
+
+## 前置条件
+
+```bash
+# 1. 安装 SDK（含 AG-UI 依赖）
+git clone https://github.com/trpc-group/trpc-agent-python.git
+cd trpc-agent-python
+python3 -m venv .venv
+source .venv/bin/activate
+pip3 install -e .
+
+# 2. 配置模型访问
+# 复制并填写 examples/plan_mode/.env：
+TRPC_AGENT_API_KEY=<你的 key>
+TRPC_AGENT_BASE_URL=<可选，自定义 endpoint>
+TRPC_AGENT_MODEL_NAME=<可选，默认 gpt-4.1-mini>
+```
+
+## 运行
+
+```bash
+cd examples/plan_mode
+
+# 完整 agent + 基于 AG-UI 的浏览器页面（推荐）
+python3 run_agent_with_agui.py
+
+# 自定义监听地址 / 端口
+python3 run_agent_with_agui.py --host 0.0.0.0 --port 8080
+```
+
+启动后控制台会打印三个地址：
+
+```
+Plan Mode AG-UI demo:  http://127.0.0.1:18090/
+Agent endpoint:        http://127.0.0.1:18090/plan_agent
+Health check:          http://127.0.0.1:18090/health
+```
+
+> 未设置 `TRPC_AGENT_API_KEY` 时服务仍能启动，但会打印警告，agent 调用会失败。
+
+## 浏览器 Demo 说明
+
+打开 <http://127.0.0.1:18090/> ——静态页面和 agent 接口（`/plan_agent`）由同一个 FastAPI 应用提供，因此页面可同源调用接口，无需任何 CORS 配置。
+
+页面提供：
+
+- **聊天面板** —— 与 orchestrator 对话。
+- **实时计划面板** —— 根据 AG-UI 每次运行结束发送的 `STATE_SNAPSHOT` 事件更新（解析 `plan:orchestrator` 这个 session state key，见 `trpc_agent_sdk/plan_mode/_helpers.py:state_key`）。
+
+三种 HITL 交互的页面表现：
+
+| 模型动作 | 页面表现 | 用户操作后续跑格式 |
+|---|---|---|
+| `enter_plan_mode` | 展示「确认进入 Plan Mode」卡片 | 确认后进入 `exploring` 状态，开启写工具 gate |
+| `exit_plan_mode` | 展示「通过 / 拒绝计划」卡片 | `{"role":"tool","toolCallId":...,"content":"{\"status\":\"approved\",...}"}` |
+| `ask_user_question` | 展示问题与选项卡片 | 同上；问题文本/选项/`question_id` 取自状态快照中的 `askedQuestions` |
+
+> `exit_plan_mode` 触发时本次运行会在没有 `TOOL_CALL_RESULT` 的情况下结束——这是 AG-UI 表示「长时间运行的工具调用被暂停」的方式。点击按钮续跑的报文格式，与任何宿主应用需满足的 `process_hitl_function_response` 期望格式一致。
+
+静态页 `static/index.html` 是一个**无任何依赖的单文件**（无需构建、无需 npm install），可直接在浏览器打开。如需用 Node 驱动同一接口（例如写测试脚本），参考 [examples/agui/client_js](../agui/client_js) 中的 `@ag-ui/client` 写法。

examples/plan_mode/.env

@@ -0,0 +1,9 @@
+# Tencent is pleased to support the open source community by making tRPC-Agent-Python available.
+#
+# Copyright (C) 2026 Tencent. All rights reserved.
+#
+# trpc-agent-python is licensed under the Apache License Version 2.0.
+
+from .agent import create_plan_agent
+
+__all__ = ["create_plan_agent"]

examples/plan_mode/README.md

@@ -0,0 +1,46 @@
+# Tencent is pleased to support the open source community by making tRPC-Agent-Python available.
+#
+# Copyright (C) 2026 Tencent. All rights reserved.
+#
+# trpc-agent-python is licensed under the Apache License Version 2.0.
+
+from __future__ import annotations
+
+import os
+
+from dotenv import load_dotenv
+from trpc_agent_sdk.agents import LlmAgent
+from trpc_agent_sdk.agents.sub_agent import EXPLORE_AGENT
+from trpc_agent_sdk.agents.sub_agent import PLAN_AGENT
+from trpc_agent_sdk.models import OpenAIModel
+from trpc_agent_sdk.plan_mode import setup_plan
+from trpc_agent_sdk.tools import FileToolSet
+from trpc_agent_sdk.tools import SpawnSubAgentTool
+from trpc_agent_sdk.tools import TodoWriteTool
+
+from .prompts import SYSTEM_INSTRUCTION
+
+load_dotenv()
+
+
+def create_plan_agent() -> LlmAgent:
+    model = OpenAIModel(
+        model_name=os.environ.get("TRPC_AGENT_MODEL_NAME", "gpt-4.1-mini"),
+        api_key=os.environ.get("TRPC_AGENT_API_KEY", ""),
+        base_url=os.environ.get("TRPC_AGENT_BASE_URL"),
+    )
+    agent = LlmAgent(
+        name="orchestrator",
+        model=model,
+        instruction=SYSTEM_INSTRUCTION,
+        tools=[
+            # Full file toolset: write/edit/bash are gated by setup_plan()
+            # while a plan is active and unlock automatically on approval.
+            FileToolSet(),
+            SpawnSubAgentTool(agents=[EXPLORE_AGENT, PLAN_AGENT]),
+            # todo_write is gated during plan mode; use after approval to track implementation.
+            TodoWriteTool(),
+        ],
+    )
+    setup_plan(agent)
+    return agent

examples/plan_mode/agent/__init__.py

@@ -0,0 +1,8 @@
+# Tencent is pleased to support the open source community by making tRPC-Agent-Python available.
+#
+# Copyright (C) 2026 Tencent. All rights reserved.
+#
+# trpc-agent-python is licensed under the Apache License Version 2.0.
+
+SYSTEM_INSTRUCTION = """\
+You are a coding assistant. Prefer reusing existing code and patterns in the workspace."""

examples/plan_mode/agent/agent.py

@@ -0,0 +1,132 @@
+# Tencent is pleased to support the open source community by making tRPC-Agent-Python available.
+#
+# Copyright (C) 2026 Tencent. All rights reserved.
+#
+# trpc-agent-python is licensed under the Apache License Version 2.0.
+"""AG-UI server for the Plan Mode example.
+
+Exposes the plan_mode orchestrator (see agent/agent.py) over the AG-UI
+protocol and serves a small, dependency-free static HTML page
+(static/index.html) from the same FastAPI app so it can call the agent
+endpoint same-origin (no CORS setup needed).
+
+The page lets a human watch the plan document update live and
+approve / reject / answer questions from the browser instead of
+simulating the decision in Python.
+
+Run:
+    cd examples/plan_mode
+    python3 run_agent_with_agui.py
+
+Then open http://127.0.0.1:18090/ in a browser.
+
+Prerequisites:
+    pip install -e '.[ag-ui]'
+    Set TRPC_AGENT_API_KEY (and optionally TRPC_AGENT_BASE_URL / TRPC_AGENT_MODEL_NAME)
+    in examples/plan_mode/.env
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from contextlib import asynccontextmanager
+from pathlib import Path
+
+from dotenv import load_dotenv
+from fastapi import FastAPI
+from fastapi.responses import FileResponse
+from pydantic import BaseModel
+
+from trpc_agent_sdk.log import logger
+from trpc_agent_sdk.server.ag_ui import AgUiAgent
+from trpc_agent_sdk.server.ag_ui import AgUiManager
+from trpc_agent_sdk.server.ag_ui import AgUiService
+
+_EXAMPLE_DIR = Path(__file__).resolve().parent
+if str(_EXAMPLE_DIR) not in sys.path:
+    sys.path.insert(0, str(_EXAMPLE_DIR))
+
+load_dotenv(_EXAMPLE_DIR / ".env")
+
+HOST = "127.0.0.1"
+PORT = 18090
+APP_NAME = "plan_mode_agui_demo"
+AGENT_URI = "/plan_agent"
+STATIC_DIR = _EXAMPLE_DIR / "static"
+INDEX_HTML = STATIC_DIR / "index.html"
+
+agui_manager = AgUiManager()
+
+
+class HealthResponse(BaseModel):
+    """Response body for GET /health."""
+
+    status: str = "ok"
+    app_name: str
+    agent_uri: str
+
+
+def _create_agui_agent() -> AgUiAgent:
+    """Lazy factory so each worker process gets its own agent instance."""
+    from agent.agent import create_plan_agent
+
+    return AgUiAgent(trpc_agent=create_plan_agent(), app_name=APP_NAME)
+
+
+@asynccontextmanager
+async def _lifespan(app: FastAPI):  # noqa: ARG001
+    if not os.environ.get("TRPC_AGENT_API_KEY"):
+        logger.warning(
+            "TRPC_AGENT_API_KEY is not set — copy .env.example values into %s/.env",
+            _EXAMPLE_DIR,
+        )
+    if not INDEX_HTML.is_file():
+        raise FileNotFoundError(f"Demo page not found: {INDEX_HTML}")
+    logger.info("Plan Mode AG-UI demo starting up.")
+    yield
+    logger.info("Plan Mode AG-UI demo shutting down.")
+    await agui_manager.close()
+
+
+def create_app() -> FastAPI:
+    """Build the FastAPI app: AG-UI agent endpoint + static demo page."""
+    app = FastAPI(title="Plan Mode AG-UI Demo", lifespan=_lifespan)
+
+    @app.get("/", response_class=FileResponse)
+    async def index() -> FileResponse:
+        return FileResponse(INDEX_HTML)
+
+    @app.get("/health", response_model=HealthResponse)
+    async def health() -> HealthResponse:
+        return HealthResponse(app_name=APP_NAME, agent_uri=AGENT_URI)
+
+    service = AgUiService(APP_NAME, app=app)
+    service.add_agent(AGENT_URI, _create_agui_agent)
+    agui_manager.register_service(APP_NAME, service)
+    agui_manager.set_app(app)
+    return app
+
+
+app = create_app()
+
+
+def serve(host: str = HOST, port: int = PORT) -> None:
+    """Start the FastAPI + AG-UI server."""
+    print(f"Plan Mode AG-UI demo:  http://{host}:{port}/")
+    print(f"Agent endpoint:        http://{host}:{port}{AGENT_URI}")
+    print(f"Health check:          http://{host}:{port}/health")
+    agui_manager.run(host, port)
+
+
+def _parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Plan Mode AG-UI browser demo")
+    parser.add_argument("--host", default=HOST, help=f"bind address (default: {HOST})")
+    parser.add_argument("--port", type=int, default=PORT, help=f"listen port (default: {PORT})")
+    return parser.parse_args()
+
+
+if __name__ == "__main__":
+    args = _parse_args()
+    serve(host=args.host, port=args.port)