@kmlckj/licos-ai-cli 1.7.0 → 1.7.3

package/lib/__templates__/agent/AGENTS.md

@@ -1,68 +1,44 @@
 # 项目上下文
 
-## 技术栈
+本文件记录本项目的事实和用户选择。功能用法从 [SDK.md](SDK.md) 查当前安装版本的 SDK 文档，目录与开发步骤见 [README.md](README.md)。
 
-- **项目类型**: AGENT
-- **运行时**: Python + LangGraph/LangChain + licos-agent-runtime
-- **入口**: `src/agents/agent.py`
+## 业务目标
 
-## 目录结构
+- 项目类型：AGENT。
+- 业务用途、目标用户和验收标准：开发时根据用户需求填写，未填写前不宣称业务已完成。
 
-```text
-├── config/
-│   └── agent_llm_config.json
-├── scripts/
-├── skills/
-│   └── <name>/SKILL.md
-├── src/
-│   ├── main.py
-│   ├── agents/
-│   │   └── agent.py
-│   ├── tools/
-│   └── storage/
-└── AGENTS.md
-```
+## 入口与配置
 
-## 项目说明
+- 业务入口：src/agents/agent.py。
+- 业务工具注册：src/tools/__init__.py。
+- 模型、提示词与运行配置：config/agent_llm_config.json。
+- 登录配置：config/licos-auth.json，模板为平台登录；修改已有项目保留其实际登录方式。
+- 订阅配置：config/event_subscriptions.json，模板为空。
+- 依赖：requirements.txt、pyproject.toml 及项目实际锁文件；实际安装版本在运行验收时记录。
 
-本文件用于记录用户项目可维护的长期上下文，例如业务目标、已经实现的工具、外部 API 约定、测试样例和后续注意事项。
+## 当前实现与保存方式
 
-- 默认图通过平台模型执行真实工具循环；`src/tools/__init__.py` 的 `TOOLS` 与配置中的工具名称必须一致。
-- 默认使用 `build_project_agent` 并传入运行时的 `ctx`；普通文件、`download_file`、`upload_file` 与技能工具由运行时注册，不重复加入 `TOOLS` 或配置 `tools`，配置只列业务工具。
-- `skills/<name>/SKILL.md` 自动发现，技能可携带任意子目录和文件，通过 `read_skill` 按相对路径读取。同步维护技能的名称、简介及引用路径。
-- 普通文件、上传下载和聊天附件按当前用户、会话隔离；路径相对会话目录，技能资源共享只读。办公文件解析和生成按项目需求注册为业务工具。
-- 平台 `upload_file` 附件块中的 HTTP(S) URL 或 base64 data URL 由运行时自动落地，不需要项目重复实现下载。模型根据 `status: saved` 和本地路径使用 `read_file` 读取文本；失败时说明错误，不读取同名旧文件。普通文本中的 URL 不会自动下载。
-- 普通链接按任务需要调用内置 `download_file(url, path)`，成功后使用返回的 `file_path`。生成文件先核对，再调用内置 `upload_file(path)`，用成功结果的完整 `url` 返回 Markdown 下载链接；上传失败说明错误，不能只交付本地路径或虚构链接。
-- 修改业务提示词时只描述项目业务角色和额外能力；内置工具说明由运行时按实际启用集合生成。文本读取工具不负责解析 PDF、Word、Excel 等二进制文件。
-- `input + session_id` 按认证用户、项目及环境隔离，当前进程保留最近 3 个已完成问答；显式 `messages` 沿用调用方历史协议。重启会丢失短期记忆，多副本需要会话固定路由。
-- 顶层 `harness` 配置计划、上下文预算、执行上限、工具策略和结果校验；`agent_runtime` 独立选择聊天历史、检查点、运行记录、Store、缓存及交互。新项目默认内存，不因已有数据库自动持久化。
-- 用户要求记忆、状态、审批时，先区分功能和保存介质；用户未说明保存介质时请其选择，已有明确选择则直接执行。重启恢复才要求运行控制、检查点和启用的事件使用数据库。
-- 只保存聊天可使用 `history`；已有业务会话表实现 `HistoryAdapter`，不覆盖旧表。数据库模块通过独立的 `agent_runtime_v1.sql` 迁移准备，再打开对应配置；运行时代码不执行迁移。
-- 通用文字、单选、多选、表单和审批适用于普通预览和部署，不要求发布企业项目。启用 `interactions` 时同时启用检查点；工具审批名称仍配置在 `harness.tool_policy.require_approval`。
-- 自定义图使用原生 StateGraph、Command、Send、reducer，通过 `compile_graph(builder, ctx=ctx)` 装配；Functional API 使用 `functional_agent`。子智能体使用 `Subagents`，独立模型、提示词和工具，继承当前用户和总预算。
-- 标准协作可配置 `agent_runtime.subagents/collaboration`，支持总控、并行、串行、路由、交接；复杂拓扑用 SDK 代码。自定义模型或外部操作使用 `execution_slot/async_execution_slot` 接入父子共享并发，不自行另建预算。
-- `handoff` 由当前智能体通过 `transfer_to_<目标>(context)` 交接，接收者直接对话；`initial_agent` 只指定新会话入口。显式启用内存或数据库检查点以保持 `active_agent`；`max_rounds` 限制每轮交接次数。代码方式使用 `model_handoff_agent/build_handoff`，示例为 `examples/handoff.py`。
-- `agent_runtime.graph_version/state_version` 标识图与状态兼容性。状态检查、编辑、恢复、分支、回放通过 `/agent/v1` 或 Agent SDK；重连只订阅已有运行，不能再次提交执行。
-- 升级已有项目先检查实际加载版本、业务代码、登录方式、配置和 Schema。未配置 `agent_runtime` 的项目继续原路径；新模板不自动覆盖旧项目，不强制用户升级依赖。
-- 按需示例位于 `examples/`；示例不会由默认入口自动加载。业务 `sp/up` 只写业务要求，不加入测试结果、迁移步骤或平台实现细节。
-- 输入支持 `input`、多轮 `messages`、`event` 及组合，保留附件和多模态内容。
-- `tests/agent_cases.json` 维护可重复的输入及业务工具验收；生成或修改后对已有预览执行 `bash scripts/runtime.sh -m verify`，失败则修复后重验。
+以下为模板初始状态，开发后按实际配置更新：
 
+- 默认模型与工具对话入口，业务工具清单为空。
+- SDK 提供会话文件和技能工具，具体协议查 SDK 文档。
+- 短期对话记忆：当前进程最近三轮；运行与事件：内存。
+- 聊天历史持久化、检查点、Store、缓存及后台投递：未开启。
+- 数据库迁移：未执行。用户的持久化选择：尚无；不因已有数据库自动启用。
+- 人工交互、自定义图及多智能体示例：未接入，examples/ 不自动运行。
 
-## 平台调用身份
+## 项目技能
 
-- `LICOS_CURRENT_USER_ID` 仅表示容器初始化用户，不能作为网页登录身份。
-- 当前用户信息、企业知识库、本体搜索/调用/订阅必须显式传本次用户 Token（Node `userToken` / Python `user_token`）。Token 失效直接返回鉴权错误，不换成容器用户。
-- 普通知识库、模型与积分接口默认使用项目身份；需要按网页登录用户执行时显式传 Token。数据库、存储、可观测性和 OAuth 应用管理使用项目身份。项目归属与平台签发的计费上下文独立保留。
-- CLI 用户操作默认按 `LICOS_CURRENT_USER_ID` 换 Token；HTTP 服务调用 CLI 时使用 `--token-stdin`。Dev CLI 可用 `--identity project` 明确选择项目身份。
-- 每个请求单独传 Token 或创建客户端，不把请求 Token、用户 ID 写进共享环境变量。
+| 技能 | 位置 | 资源 |
+| --- | --- | --- |
+| file-handling | skills/file-handling/SKILL.md | references/output-files.md |
+| report-writing | skills/report-writing/SKILL.md | assets/report-template.md |
 
-## 编程项目登录身份
+新增技能、工具或外部业务依赖后，在此记录实际路径、用途和输入输出；不复制 SDK 的通用参数手册。
 
-- 有内置登录时使用内置登录会话；没有内置登录时使用当前 LICOS 网页登录。内置登录未登录或过期时不能切换成平台用户。
-- Node 服务端使用 `createProjectAuth({ mode: 'builtin', resolveBuiltinToken })` 或 `createProjectAuth({ mode: 'platform' })`，每次请求调用 `await projectAuth.userToken(request)`。内置解析器必须读取已有认证会话并返回用户已授权的 LICOS 凭证。
-- 无内置登录的浏览器用户接口使用 `@kmlckj/licos-platform-sdk/browser` 的 `createProjectUserFetch`：平台登录桥领取一次性票据，项目后端兑换 Token。不要直接读取跨域平台 localStorage，不在 URL 中传 Token，不修改全局 fetch。项目级 API 保持原有请求方法。
-- Python 使用 `ProjectAuth`；Agent/Workflow 通过 `config/licos-auth.json` 配置模式，内置登录设置 `resolver: "模块:函数"`，业务代码使用 `ctx.identity.user_token`。
-- 当前用户、企业知识库、本体用户操作显式传 `userToken`/`user_token`。模型、积分和普通知识库按业务选择用户或项目身份。数据库、对象存储和可观测性继续使用项目身份。
-- 沿用现有 OAuth 授权范围与接口权限。凭证无权访问目标接口时返回现有鉴权错误，不扩大权限或换用其他身份。
-- 修改已有项目时先接它的现有登录机制，不能用新模板的默认平台模式覆盖。真实 Token 只存在于运行时请求/会话，不写入源代码、共享环境变量或 Agent 提示词。
+## 验收与维护记录
+
+- 默认用例：tests/agent_cases.json；需按真实业务维护。
+- 当前未记录运行验收。后续记录实际结果、运行 ID、未验证项及原因。
+- 持久化项目补充数据库环境、Schema 与迁移 ID；升级补充原版本、目标版本、未完成任务处理及回退安排。
+- 修改工具、技能、配置、提示词、保存方式及关键测试后同步本文件。

package/lib/__templates__/agent/DATABASE.md

@@ -0,0 +1,11 @@
+# 持久化接入步骤
+
+默认沿用内存。先记录用户希望保存的内容和是否需要重启保留；只有选择持久化时才准备数据库，已有数据库不自动改变决定。
+
+1. 按 [SDK.md](SDK.md) 定位项目实际安装包，阅读 docs/agent-capabilities.md 和 docs/database-setup.md。模块约束、数据库类型、脚本与命令以该版本文档为准。
+2. 核对当前项目、环境、数据库模式、Schema 及迁移历史，确定本次需要执行的独立脚本或增量迁移。
+3. 依 SDK 文档完成检查、dry-run、已授权的显式执行及业务状态核验。已存在对象不重复安装，不删业务数据。
+4. Schema 就绪后配置用户选择的模块和介质，验证真实读写、隔离及需求中的重启行为。
+5. 在 AGENTS.md 记录版本、用户决定、环境、迁移 ID、执行结果及待验收项。
+
+SQL 不嵌入入口、业务工具、启动脚本或安装钩子。开发迁移不自动操作生产环境。老项目按 [UPGRADING.md](UPGRADING.md) 保留已有数据和功能。

package/lib/__templates__/agent/README.md

@@ -1,198 +1,62 @@
 # <%= appName %>
 
-LICOS 智能体项目模板，基于 Python、LangGraph、LangChain 和 `licos-agent-runtime`。
+LICOS 智能体项目，基于 Python、LangGraph/LangChain 和 licos-agent-runtime。
 
-## 目录
+## 文档入口
 
-```text
-.
-├── .licos                       # CLI 配置文件；平台数据目录另在 /workspace/.licos/
-├── config/
-│   └── agent_llm_config.json
-├── AGENTS.md
-├── pyproject.toml
-├── scripts/
-├── skills/
-│   ├── file-handling/
-│   └── report-writing/
-└── src/
-    ├── main.py
-    ├── agents/
-    │   └── agent.py
-    └── tools/
-```
-
-## 本地运行
-
-```bash
-bash scripts/setup.sh
-bash scripts/http_run.sh -p <%= port %>
-```
-
-## HTTP 接口
+- [SDK.md](SDK.md)：定位当前安装版本的 SDK 文档，查询功能、API、配置及限制。
+- [AGENTS.md](AGENTS.md)：本项目的业务目标、实际实现、保存方式和验收记录。
+- [examples/README.md](examples/README.md)：示例选择、合并与运行。
+- [DATABASE.md](DATABASE.md)：用户选择持久化后的接入步骤。
+- [UPGRADING.md](UPGRADING.md)：已有项目升级与兼容性检查。
 
-- `GET /health`
-- `POST /run`
-- `POST /stream_run`
-- `GET /agent/config`
-- `POST /v1/chat/completions`
-- `GET /agent/v1/capabilities`：查询当前启用能力及保存方式
-- `/agent/v1/runs`：创建、查询、取消、恢复运行，事件按游标续读
-- `/agent/v1/threads/{session_id}`：检查点状态、历史、编辑、分支、回放
+## 目录与职责
 
-`POST /run` 的 Body 是智能体状态输入，常用：
-
-```json
-{
-  "input": "请分析这个需求"
-}
-```
-
-也可以传 OpenAI-style `messages`：
-
-```json
-{
-  "messages": [
-    {
-      "role": "user",
-      "content": "请分析这个需求"
-    }
-  ]
-}
-```
-
-Body 可以同时带 `attachments`、`files`、`references` 等业务字段；运行时会作为图状态传入，具体解释由智能体项目代码决定。
-
-结构化事件使用顶层 `event` 对象，例如 `{"event":{"type":"test.observation","source":"MANUAL_REPLAY","value":42}}`。可以同时传 `input` 和 `event`，两者都会进入模型；`input` 与最后一条用户消息内容相同则只处理一次。事件来源必须据实填写，人工回放不能标成实时事件。
-
-默认图通过平台模型与已注册工具循环执行，使用 `licos_agent_runtime.project_agent.build_project_agent`，传入本次运行的 `ctx`。`input + session_id` 按认证用户隔离，在当前进程保留最近 3 个已完成问答；显式传入 `messages` 时只使用调用方历史。进程重启会清空短期记忆，多副本需单实例或会话固定路由。
-
-默认工具包括 `read_file`、`write_file`、`glob_file`、`list_files`、`download_file`、`upload_file`、`list_skills`、`read_skill`，无需加入业务 `TOOLS` 或配置 `tools`。文件工具按当前用户和 `session_id` 隔离，路径相对会话目录；同一会话可继续读取先前生成的文件。HTTP 请求使用平台用户 Bearer 令牌确认身份，普通文件和上传下载不能跨会话访问。
-
-项目技能放在 `skills/<name>/SKILL.md`，以 YAML 头定义 `name`、`description`；新放入的技能会自动发现。技能全文、`references/`、`scripts/`、`assets/` 等附属资源按需读取，随项目完整打包。示例：`read_skill(name="report-writing", path="assets/report-template.md")`；`path` 为目录时返回目录列表。技能读取不会执行脚本。
-
-`read_file` 的 `offset` 是从 1 开始的行号，`limit` 是行数；输出带行号，截断时继续按行读取。`write_file` 的 `mode` 支持默认 `overwrite` 和 `append`。`glob_file` 支持 `**/*.md`、`assets/*.{csv,json}` 及目录前缀，按文件修改时间倒序返回。
-
-内置 `download_file(url, path)` 将 HTTP(S) 文件保存到当前会话，返回可继续读取的 `file_path`。向用户交付文件时，先生成并核对，再调用内置 `upload_file(path)`，用成功结果的完整 `url` 返回 Markdown 下载链接，链接有效期以 `expiresAt` 为准。上传使用 Platform SDK，真实下载链接由 `storage.share_url` 返回；失败时说明错误，不能把本地路径当成下载链接。办公文档解析和生成仍按需封装 `licos-dev-sdk`，文件写入当前会话目录。
-
-升级已有项目时，如果曾手动加入 `create_file_transfer_tools(...)`，删除该注册及配置中的 `download_file`、`upload_file`，由运行时统一提供。
-
-`config/event_subscriptions.json` 默认为空数组。启用本体订阅时，配置 `agent_runtime.deliveries` 的存储和身份解析函数，事件进入同一运行队列；数据库保存需要用户明确选择。绑定当前工作空间、项目及源码指纹，运行 `bash scripts/runtime.sh -m fingerprint` 获取源码版本。持续监听需要常驻部署；上游当前不保证稳定事件 ID 或断线补发。
-
-`POST /run` 和 `POST /stream_run` 支持 `input` / `messages`，也支持平台 `content.query.prompt` 包装；文本和附件会归一成智能体图输入，`references` 等业务字段会保留并传给智能体图。`content.query.prompt` 内的 `upload_file` 由运行时在模型执行前保存到当前用户会话目录的 `assets/upload/`，并写入 `attachments` 和 `files`。预览页传 HTTP(S) 文件 URL，SDK 聊天页传 `data:<mime>;base64,...`，两种均自动落地，不依赖模型调用 `download_file`。
-
-模型消息会带附件的保存状态和本地相对路径。`status: saved` 时可直接调用 `read_file(path="assets/upload/spec.md")`；文本预览不保证完整，需要时按行读取原文件。附件保存失败时，运行时在调用模型前终止本次请求，返回文件名和具体错误；不会让模型使用同名旧文件替代。图片继续以多模态内容传入，能否识别取决于所选模型；PDF、Word、Excel 等解析需要项目按需注册格式处理工具。
-
-仅在普通聊天文本中粘贴 URL 不会触发以上自动落地。外部调用方应使用下方 `upload_file` 协议；普通链接由模型按任务需要调用内置 `download_file`。重复访问同一会话文件时，传相同 `session_id` 和平台用户 Bearer 令牌。
-
-```json
-{
-  "session_id": "conversation-001",
-  "content": {
-    "query": {
-      "prompt": [
-        {
-          "type": "text",
-          "content": {
-            "text": "请结合附件分析需求"
-          }
-        },
-        {
-          "type": "upload_file",
-          "content": {
-            "upload_file": {
-              "file_name": "spec.md",
-              "url": "https://files.example.com/spec.md?sign=xxx",
-              "mime_type": "text/markdown"
-            }
-          }
-        }
-      ]
-    }
-  },
-  "references": [
-    {
-      "type": "file",
-      "path": "docs/spec.md"
-    }
-  ]
-}
+```text
+.licos                          # CLI 配置文件；平台数据目录另在 /workspace/.licos/
+config/
+  agent_llm_config.json          # 模型、业务提示词、工具清单和运行配置
+  licos-auth.json                # 项目认证配置
+  event_subscriptions.json       # 项目订阅配置
+src/
+  main.py                       # 运行入口
+  agents/agent.py                # 业务图构建入口
+  tools/__init__.py              # 业务工具注册
+skills/                         # 项目共享技能及附属资源
+examples/                       # 按需合并的示例，默认不执行
+tests/agent_cases.json           # 默认图验收用例
+scripts/                        # 安装、运行、验收、打包脚本
+requirements.txt
+pyproject.toml
 ```
 
-## 智能体配置
-
-`config/agent_llm_config.json` 是平台预览读取智能体配置和工具列表的来源：
-
-- `config`：模型、温度、超时、thinking 等运行参数；`model: "auto"` 表示使用平台默认模型
-- `sp`：系统提示词
-- `up`：用户提示补充
-- `tools`：业务工具名称列表，新增或删除业务工具时同步维护；运行时的八个内置工具不列入此数组
-- `harness`：版本 1 的短期记忆、计划、模型上下文预算、调用限制、工具策略、结果校验和思考内容透传；配置修改从下一任务生效
-- `agent_runtime`：版本 1 的运行协议，分别开启功能并选择 `memory` 或 `database`；默认只在内存保存运行和事件，保留原有三轮短期记忆
-- `harness.thinking.forward_to_frontend`：默认 `false`。开启时，模型返回的思考内容以独立流事件发送到预览页和 SDK 页面，思考完成自动折叠；与 `config.thinking` 的模型思考开关分别控制
+业务扩展按需增加 src/storage、src/memory 等模块。用户会话文件由运行时管理，不放进共享源码或技能资源目录。
 
-模板 `sp` 保存业务角色和真实结果要求。`build_project_agent` 按实际启用的工具追加文件及技能能力说明；禁用工具不会暴露给模型。模型上下文窗口来自平台目录，缺少窗口信息会返回配置错误。
+## 接入与开发
 
-## 按需启用状态与协作
+1. 读取 AGENTS.md、配置、业务入口及依赖。首次开发先确定业务目标、工具、输入输出和成功标准。
+2. 按 SDK.md 查对应版本功能文档，选配置或代码扩展；沿用当前业务配置和身份。
+3. 业务工具放 src/tools/，同步导入注册与配置中的工具清单。技能连同附属资源放 skills/ 并维护简介和引用路径。
+4. 修改入口时保留业务工具、提示词和登录机制。合并示例前阅读 examples/README.md，区分完整入口与工具模块。
+5. 同步 AGENTS.md 和本项目测试用例，按实际启用能力验收。
 
-| 需要的功能 | 配置或代码 |
-| --- | --- |
-| 完成后的聊天记录 | `agent_runtime.history.enabled`；已有表可用 `history.adapter` |
-| 查看状态、继续执行、分支、回放 | `checkpoints.enabled`，默认内存 |
-| 提问、表单、工具审批 | 同时开启 `checkpoints` 和 `interactions`；工具名单放在 `harness.tool_policy.require_approval` |
-| 审查最终输出 | `interactions.review_output: true`；批准后交付最终答案 |
-| 跨会话记忆、语义搜索 | `store`；语义搜索另外配置真实 embedding 工厂、维度和索引版本 |
-| 节点缓存与重试 | `cache` 和节点 `CachePolicy`；`retry` 默认不重试工具写操作 |
-| 子智能体、路由、并行、交接 | `agent_runtime.subagents/collaboration`；复杂图用 `Subagents`、`SubagentSpec`、`route`、`dispatch` |
-| Functional API | `functional_agent`、原生 `task` |
-| 重启或多副本恢复 | 运行控制、检查点、事件选择数据库；后台恢复另配置原用户身份解析函数 |
+业务 sp/up 只写角色、任务、策略和输出要求；功能说明和 API 查 SDK，开发步骤和测试结果留在项目文档。
 
-数据库已存在也不会自动启用上述功能。用户选择持久化后，先检查现有 Schema，使用数据库 CLI 执行运行时包附带的独立迁移 `licos_agent_runtime/migrations/agent_runtime_v1.sql`。默认不建表；业务历史表可以通过适配器复用。
+## 运行与验收
 
-示例见 [examples/README.md](examples/README.md)，包括单智能体、人工输入、专家协作、Send 汇总、Functional API 和 Store。它们由项目按需导入，不会自动运行。完整 API 见运行时包的 `docs/agent-capabilities.md`。
+平台内复用 Preview，不手动启动重复常驻服务。独立本地开发可运行：
 
-配置协作支持 `supervisor/parallel/sequence/router/handoff`，分别对应总控、并行、串行、路由和交接。每个子智能体声明模型、提示词、业务工具名、记忆范围及允许传入的业务 context 字段。父子共用调用预算与标准模型/工具并发限制；自定义调用节点使用 `execution_slot/async_execution_slot` 加入共享并发。
-
-`handoff` 的接收者直接回答用户，同一会话下一轮继续由当前智能体处理。它要求显式开启检查点，默认选择内存；`initial_agent` 指定初始处理者，`max_rounds` 限制每轮交接次数。配置方式自动提供交接工具，代码方式见 `examples/handoff.py`。交接只传用户可见对话、附件和明确说明，保留双方各自的内部工具历史。
-
-内存状态在当前服务进程存活期间可用；数据库模式不依赖粘性会话。运行总时限包含人工等待，审批期限另由 `interactions.timeout_seconds` 控制。恢复必须使用原调用者的有效授权，不能换为项目负责人。已经开始但没有确认回执的外部操作需要业务核对，不能盲目重做。
-
-旧项目不增加 `agent_runtime` 时继续原协议。新模板不会重写已发布项目；用户主动升级时保留业务代码、登录机制、`sp/up` 和已有表。切换存储采用显式导出、导入，图或状态版本改变需要项目提供迁移方案。
-
-## 项目上下文
-
-会话列表、创建、重命名、删除及消息分页由 SDK 提供，界面按能力查询启用。目录跟随聊天历史的存储，未启用历史时跟随运行控制；数据库表结构需显式安装。检查点复制、按运行删除和裁剪供停止写入后的维护使用，用户分支使用 `forkThread`。
-
-调用企业发布项目使用 `licos_agent_runtime.enterprise_agents.invoke_enterprise`；当前用户与来源项目凭证分别验证，交互沿用图中断和真实用户回执。后台结果通过 `deliveries.callbacks` 注册异步处理函数，业务按事件 ID 去重。配置和 API 详见运行时包 `docs/agent-capabilities.md`。
-
-项目内的 `AGENTS.md` 用于记录可由用户维护的项目上下文，例如业务目标、已实现工具和测试样例。新增工具时通常需要同步：
-
-- `src/tools/*_tool.py`：工具实现
-- `src/tools/__init__.py`：在 `TOOLS` 中注册工具
-- `config/agent_llm_config.json`：更新 `tools`，必要时更新 `sp` / `up`
-
-配置文件错误、业务工具名称与注册列表不一致会在构图时直接失败。工具执行异常会保留在运行记录中，并作为错误工具结果交回模型处理。
-
-## 生成后验收
+```bash
+bash scripts/setup.sh
+bash scripts/http_run.sh -p <%= port %>
+```
 
-在平台预览启动后运行：
+预览、本地运行和验收共用 scripts/runtime.sh 的解释器选择。默认模型与工具对话图在已有服务上验收：
 
 ```bash
 bash scripts/runtime.sh -m verify --cases tests/agent_cases.json --report .tmp/agent-verification.json
 ```
 
-命令检查导入、图输入、工具注册，并对每个用例调用 HTTP 与 SSE，核对真实模型调用、工具调用、输入证据和运行用量。相同 `session_group` 的用例复用会话，检查跨请求短期记忆；业务查询用例可增加 `required_tools`。报告保留 run_id，失败返回非零退出码。
-
-预览、本地运行和验收共用 `scripts/runtime.sh`：显式设置 `PYTHON_BIN` 时使用该解释器，否则使用已创建的项目 `.venv`，全局安装模式使用 `python`。选定环境损坏会直接失败。验收已启用会话记忆的项目时，先把测试用户的 Bearer 令牌放入环境变量 `LICOS_AGENT_VERIFY_BEARER_TOKEN`；验收报告不会记录令牌。
-
-验收默认读取 `LICOS_AGENT_RUN_TIMEOUT_SECONDS`，可用 `--request-timeout` 覆盖 HTTP 等待时间；非法超时配置直接失败。图须符合运行时的 `ainvoke/stream/astream/astream_events` 契约，执行错误不会通过换参数重试或改成非流式调用绕过。订阅状态与投递记录分别读取，记录接口为 `/agent/subscriptions/{id}/deliveries?limit=...&offset=...`。
-
-## 编程项目登录身份
+验收参数、用例字段及适用范围查 SDK 的 docs/validation.md；自定义图和交互示例按 examples/README.md 验收。用户授权只传入测试进程，不写源码或报告。
 
-- 有内置登录时使用内置登录会话；没有内置登录时使用当前 LICOS 网页登录。内置登录未登录或过期时不能切换成平台用户。
-- Node 服务端使用 `createProjectAuth({ mode: 'builtin', resolveBuiltinToken })` 或 `createProjectAuth({ mode: 'platform' })`，每次请求调用 `await projectAuth.userToken(request)`。内置解析器必须读取已有认证会话并返回用户已授权的 LICOS 凭证。
-- 无内置登录的浏览器用户接口使用 `@kmlckj/licos-platform-sdk/browser` 的 `createProjectUserFetch`：平台登录桥领取一次性票据，项目后端兑换 Token。不要直接读取跨域平台 localStorage，不在 URL 中传 Token，不修改全局 fetch。项目级 API 保持原有请求方法。
-- Python 使用 `ProjectAuth`；Agent/Workflow 通过 `config/licos-auth.json` 配置模式，内置登录设置 `resolver: "模块:函数"`，业务代码使用 `ctx.identity.user_token`。
-- 当前用户、企业知识库、本体用户操作显式传 `userToken`/`user_token`。模型、积分和普通知识库按业务选择用户或项目身份。数据库、对象存储和可观测性继续使用项目身份。
-- 沿用现有 OAuth 授权范围与接口权限。凭证无权访问目标接口时返回现有鉴权错误，不扩大权限或换用其他身份。
-- 修改已有项目时先接它的现有登录机制，不能用新模板的默认平台模式覆盖。真实 Token 只存在于运行时请求/会话，不写入源代码、共享环境变量或 Agent 提示词。
+按实际结果记录已执行检查、运行 ID、失败原因及待验收项。静态检查、模拟测试、真实业务调用、重启恢复、编程 Agent 独立生成项目分别记录。

package/lib/__templates__/agent/SDK.md

@@ -0,0 +1,31 @@
+# 查阅项目实际使用的 SDK
+
+功能说明、API、配置字段、默认值和限制统一查 SDK 文档，按任务读取，不复制进本项目规则或业务提示词。
+
+## 1. 确认项目解释器
+
+先看 scripts/runtime.sh：显式 PYTHON_BIN 优先；否则项目有 .venv 时用 .venv/bin/python；没有时用当前运行环境的 python。不要用全局环境替代项目环境。
+
+以下命令以项目虚拟环境为例，按实际解释器替换命令开头：
+
+```bash
+.venv/bin/python -c 'from importlib.metadata import version; from importlib.resources import files; print(version("licos-agent-runtime")); print(files("licos_agent_runtime").joinpath("docs"))'
+```
+
+## 2. 先读索引，再读相关主题
+
+打开上一步目录中的 index.md，按本次需求选择文档。索引包括配置、Loop/Graph 扩展、状态与多智能体、文件技能、数据库准备、运行协议和验收。只读相关章节，再按真实签名实现。
+
+也可以直接打印索引：
+
+```bash
+.venv/bin/python -c 'from importlib.resources import files; print(files("licos_agent_runtime").joinpath("docs/index.md").read_text(encoding="utf-8"))'
+```
+
+其他依赖 SDK 同样查对应包的实际版本、文档和签名。包内资源可通过 importlib.resources 定位，包描述可通过 importlib.metadata.metadata 查看，不猜 site-packages 路径。
+
+## 3. 老项目兼容
+
+老版本没有索引时列出其实际文档、查看包描述及源码签名，不从另一版本复制 API。确需新能力时按 [UPGRADING.md](UPGRADING.md) 制定升级与验收步骤；不因查文档自动升级。
+
+[README.md](README.md) 介绍项目结构；[examples/README.md](examples/README.md) 介绍模板示例接入；[DATABASE.md](DATABASE.md) 记录持久化准备；AGENTS.md 记录本项目已实现内容和用户决定。

package/lib/__templates__/agent/UPGRADING.md

@@ -0,0 +1,48 @@
+# 已有智能体项目升级检查清单
+
+只有用户要求升级或所需能力确实依赖新版本时才调整依赖。原项目不升级仍可使用其原有功能；不要重新执行初始化来覆盖入口、登录方式、业务表或配置。
+
+## 1. 记录基线与实际版本
+
+- 读取项目 `AGENTS.md`、入口、业务工具、模型配置、认证配置、事件订阅、依赖及锁文件，记录当前可用接口和真实业务用例。
+- 使用 `scripts/runtime.sh` 所选的项目解释器检查安装包版本，不能用其他全局 Python 环境的版本代替。当前模板依赖为 Runtime >=0.6.10、Platform SDK >=0.7.6、Dev SDK >=0.6.6，Python >=3.11；以项目的依赖声明、锁文件和实际安装结果为准。
+- 更新 `requirements.txt`、`pyproject.toml` 及项目实际使用的锁文件，保留原有业务依赖。在项目环境安装并检查依赖；不要把“修改了版本声明”当成“预览或部署已升级”。
+- 修改前保留可回退的源码版本，核对部署配置和数据库 Schema。不要将用户凭证保存进备份、源码或日志。
+
+## 2. 适配业务代码与调用身份
+
+- 核对新版本 SDK 的真实函数签名。当前用户信息、企业知识库、本体用户操作显式传 `user_token=ctx.identity.user_token`；依赖用户身份的业务工具在 `create_agent(ctx)` 中由工厂创建，再合并业务工具并校验配置。
+- 保留现有平台登录或内置登录解析器，不用新模板的默认认证覆盖旧登录。没有有效用户授权时返回鉴权错误，不使用容器初始化用户或项目负责人代替。
+- 后台投递/恢复沿用项目声明的身份解析机制，重新取得原用户的有效授权。模型、数据库、存储等按各自身份契约执行，不能把所有 SDK 操作都改成同一种身份。
+- 常驻本体订阅的上游连接没有浏览器请求，现有运行时使用项目绑定身份订阅；事件进入业务执行后的身份由投递/恢复配置解析。分别检查这两段授权，不能用上游订阅身份替换网页调用者，也不能凭空要求常驻连接提供浏览器 Token。
+- 合并完整入口示例时保留 `sp/up`、业务工具、hooks、结果校验器和自定义输入。标准协作优先使用配置；Store 示例只提供工具，见 [examples/README.md](examples/README.md)。
+- 如果旧项目手动注册了 `create_file_transfer_tools(...)`，移除该注册及业务配置中的 `download_file`、`upload_file`，由运行时统一提供，避免重复工具名。
+
+## 3. 保留已有状态与存储选择
+
+- 记录每个模块是否启用及使用 memory/database。已有数据库不代表用户同意持久化，不自动开启历史、检查点或 Store。
+- 只保存聊天用 `history`；未完成运行、人工等待和恢复依赖检查点及运行控制。进程重启会丢失内存状态，升级前完成或明确结束受影响任务。
+- 持久化准备按 [DATABASE.md](DATABASE.md) 定位项目实际安装版本的脚本，检查托管数据库、Schema 和迁移记录；数据库语义搜索还需向量脚本。基础对象已存在时不要重新执行完整建表脚本，结构变化应使用独立增量迁移。
+- 图/状态结构变化时更新 `graph_version/state_version`，先停止相关写入，再按明确方案迁移。更换介质使用 `agent_migration.export_thread/import_thread`；数据库 Schema 使用独立迁移，不能在启动代码中执行 SQL 迁移。
+- 保留历史数据和未完成任务的可追溯信息。外部写操作结果不明时先核对回执，不能通过新建运行或重跑工具冒充恢复。
+
+## 4. 更新事件订阅绑定
+
+- 修改已启用订阅的项目之前，停止相关订阅投递，避免旧图和新图混用。保留订阅 ID、原授权和实际目标，不删除业务订阅来绕过错误。
+- 完成源码和运行配置修改后执行 `bash scripts/runtime.sh -m fingerprint`，把结果更新到启用订阅的 `project_version`。指纹更新后若再修改参与计算的文件，必须重新计算。
+- 核对 `workspace_id`、`project_id` 和上游对象/动作是否仍然存在、当前授权是否可用，再恢复订阅。上游目标失效时报告准确错误，不能擅自绑定其他对象。
+- 检查订阅状态和真实投递记录，人工回放明确标识来源，不能声称为实时事件。
+
+## 5. 验证兼容性与新增能力
+
+- 先读取 Preview 状态和 Output，复用已有服务；用户要求启动或运行测试时通过可用的平台预览能力启动，不手动启动重复的常驻服务。用户暂不测试或服务不可用时，明确记录运行验收未执行及原因。
+- 核对 `/health`、`/graph_parameter`、`/agent/config`、`/agent/canvas` 和 `/openapi.json`，再查询 `/agent/v1/capabilities`。未升级服务缺少新接口时保留原页面和调用方式；新接口的 401、500 等错误不能按“不支持”忽略。
+- 保留原 `/run`、`/stream_run`、`/v1/chat/completions` 及真实业务输入输出。默认模型/工具对话图按 README 执行 verify，检查真实模型和工具回执；自定义图、交接和中断按示例逐步验证。
+- 只验证本次启用或改动的状态能力，包括用户/会话隔离、等待与回复、取消、恢复、回放及订阅。持久化需要实际重启后检查；内存测试不能当成数据库恢复通过。
+- 自动化样例执行与编程 Agent 自然语言生成项目是不同验收，分别记录证据和未覆盖项。
+
+## 6. 部署后核对
+
+- 由平台重新构建和部署项目，确认部署环境实际安装的包版本、运行入口和配置；本地修改或平台服务升级不会自动更新已部署项目的依赖。
+- 保持用户选择的状态介质及部署同步开关，避免部署覆盖已有数据库或对象文件。
+- 在目标部署上检查元数据、真实业务调用和已启用订阅，记录实际结果。项目 `AGENTS.md` 更新版本、状态方案和维护说明；测试报告、迁移过程和平台实现细节不写入业务 `sp/up`。

package/lib/__templates__/agent/examples/README.md

@@ -1,47 +1,50 @@
 # 按需使用的智能体示例
 
-默认入口仍是 `src/agents/agent.py`，不会自动加载本目录。选择示例后，在该入口中导入它的 `create_agent`，例如 `from examples.human_input import create_agent`。保留项目已有业务配置和认证方式。
+默认入口仍是 `src/agents/agent.py`，不会自动加载本目录。先区分“完整入口示例”和“工具模块”，再按需接入。已有项目应合并所需代码，保留业务配置、登录方式、业务工具、hooks 和结果校验器，不直接替换整个入口。
 
-| 文件 | 能力 | 必需配置 |
+| 文件 | 能力 | 接入方式与必需配置 |
 | --- | --- | --- |
-| 默认 `src/agents/agent.py` | 单智能体、文件、技能、三轮内存 | 模板默认配置 |
-| `human_input.py` | 单选交互、自定义状态、自定义进度 | `checkpoints.enabled`、`interactions.enabled` |
-| `experts.py` | 总控和独立专家模型、子工具调用 | `agent_runtime`；选 `per_thread` 时再开启检查点 |
-| `handoff.py` | 智能体主动交接、直接对话、跨轮次保持当前处理者 | `checkpoints.enabled`，内存或数据库按需选择 |
-| `map_reduce.py` | 原生 Send、reducer、并发汇总、节点超时 | 缓存可选；输入 `{"items":["a","b"]}` |
-| `functional.py` | Functional API、任务结果复用、人工输入 | `checkpoints.enabled`、`interactions.enabled` |
-| `memory.py` | Store 工具、TTL、真实语义检索 | `store.enabled`；搜索另配 embedding 工厂及维度 |
+| 默认 `src/agents/agent.py` | 单智能体、文件、技能、三轮内存 | 保留默认入口及配置 |
+| `human_input.py` | 单选交互、自定义状态、自定义进度 | 完整图入口；开启 `checkpoints.enabled`、`interactions.enabled` |
+| `experts.py` | 总控和独立专家模型、子工具调用 | 完整入口；开启 `agent_runtime`；选 `per_thread` 时再开启检查点 |
+| `handoff.py` | 智能体主动交接、直接对话、跨轮次保持当前处理者 | 完整入口；开启 `checkpoints.enabled`，显式给各参与者分配业务工具 |
+| `map_reduce.py` | 原生 Send、reducer、并发汇总、节点超时 | 完整图入口；缓存可选；输入 `{"items":["a","b"]}` |
+| `functional.py` | Functional API、任务结果复用、人工输入 | 完整图入口；开启 `checkpoints.enabled`、`interactions.enabled` |
+| `memory.py` | Store 工具、TTL、真实语义检索 | 仅工具模块，没有 `create_agent`；开启 `store.enabled`；搜索另配 embedding 工厂及维度 |
 
-示例启用的能力默认放内存。用户要求重启恢复时，把 `checkpoints`、`runs` 和已启用的 `events` 一起改为 `storage: "database"`，通过数据库 CLI 执行运行时提供的独立迁移。仅要保存聊天则单独配置 `history`，不必开启检查点。
+## 接入入口与工具
 
-`handoff.py` 使用 SDK 代码声明允许交接的目标；也可用 `collaboration.mode: "handoff"`、`participants`、`initial_agent` 配置标准交接。第一轮从初始智能体开始，后续同一会话从保存的 `active_agent` 开始；`transfer_to_<名称>` 的参数只提供需要传给接收者的交接说明。内部工具历史按子智能体的记忆范围保存。
+在新建演示项目中，完整入口可以由 `src/agents/agent.py` 导出，例如 `from examples.human_input import create_agent`。这些图通过运行时接收 `ctx` 并装配组件，应从实际运行接口调用，不能在普通脚本里无上下文执行 `create_agent()`。自定义状态图按自己的输入 Schema 调用，不一定支持默认对话图的所有输入。
 
-## 审批与恢复
+标准多智能体需求优先保留默认入口，用 `agent_runtime.subagents/collaboration` 配置。需要代码组合时再合并 `experts.py`：示例校验配置与业务 `TOOLS` 一致，保留总控的原业务工具及 `sp/up`，并把共享业务提示词传给专家。专家默认只分析传入材料，需要访问数据时显式选择其 `tools`，不能把所有业务工具自动交给每个专家。`research/review` 由代码生成，不加入业务配置 `tools`。代码组合入口关闭配置协作，不同时维护两套团队。
 
-开启交互和检查点后，把需要审批的真实工具名加入 `harness.tool_policy.require_approval`。前端支持允许、拒绝、修改参数后批准；`interactions.review_output` 可要求审查最终答案。文字、多选、表单通过 `ask_user` 的 `kind/options/schema` 参数定义。
+`memory.py` 不替换入口。需要保存和搜索偏好时，在 `src/tools/__init__.py` 保留现有工具并追加：
 
-SDK 调用顺序：
+```python
+from examples.memory import save_preference, search_preferences
 
-1. `startRun(input, { background: true, run_id })` 创建运行，保存返回的运行 ID。
-2. `streamEvents(runId, cursor)` 或 `getRun(runId)` 查看运行；网络断开后查询原运行。
-3. 等待用户输入时调用 `resumeRun(runId, { response_id, responses: { [interruptId]: answer } })`。
-4. `getState/stateHistory/updateState/forkThread/replayThread` 管理检查点。回放会调用后续模型和工具，必须确认业务写入的幂等规则。
+# 放在现有 TOOLS 定义后，保留原业务工具。
+TOOLS += [save_preference, search_preferences]
+```
 
-`harness.execution.max_duration_seconds` 包含人工等待；长时间审批需调整该值。内存只在当前进程有效，数据库也不能自动恢复进程中的任意 Python 行，只能从已提交的图边界继续。
+同时在配置 `tools` 中追加 `save_preference`、`search_preferences`，开启 `agent_runtime.store.enabled`。语义搜索必须配置接收 `ctx` 的真实 embedding 工厂、实际维度和 `index_version`，具体字段见运行时能力文档；仅需保存偏好时只注册 `save_preference`，不必开启语义索引。按业务需要更新 `sp/up`，不能仅注册工具就宣称能搜索。
 
-## 业务扩展
+示例未替项目决定持久化。按用户选择准备运行配置；数据库接入见 [DATABASE.md](../DATABASE.md)，模块约束见 [SDK 文档](../SDK.md)。
 
-- 标准协作也可直接配置 `agent_runtime.subagents` 与 `collaboration`，选择总控、并行、串行、路由或交接模式；工具必须引用已有注册函数。自定义图保留代码组合入口。
-- 标准模型和工具共享父运行并发限制；自行编写的外部操作用 `async_execution_slot` / `execution_slot` 包围调用。可以用 `childState/childHistory` 查看子调用的检查点。
-- 条件分支和循环：原生 `StateGraph.add_conditional_edges`；交接：`route(..., parent=True)` 返回 `Command.PARENT`。父图用 reducer 接收子图的更新。
-- 私有上下文：`SubagentSpec.input_mapper/output_mapper` 决定子图收到与返回哪些字段。
-- 节点级重试：在无副作用节点设置 `RetryPolicy(retry_on=...)`；缓存设置 `CachePolicy`，不缓存外部写操作。
-- 动态提示词、模型选择、结构化输出：`build_project_agent` 的 `system_prompt` 回调、`model_selector`、`response_schema`；模型/工具前后回调为 `AgentHooks`。
-- 外部操作：`effect/effect_sync` 接收业务幂等键及 `reconcile` 核对函数；不能用新运行替代未知结果核对。
-- 后台任务：配置 `deliveries` 并提交稳定 `delivery_id`；数据库恢复另外配置 `recovery.identity_resolver`。解析函数必须重新取得原用户授权，不把 Token 存入运行数据。
-- 现有业务会话表：实现 `HistoryAdapter` 的 `read/append/delete` 并配置 `history.adapter`，保留旧数据和登录方式。
-- 会话目录：SDK `listSessions/createSession/renameSession/deleteSession/sessionMessages`，分页默认 50；用消息游标加载更早记录。目录跟随历史存储，未启用历史则跟随运行控制。
-- 企业发布项目：节点使用 `invoke_enterprise(record_id, arguments, key=..., ctx=ctx)`，平台验证当前使用者、来源项目及发布契约；人工交互沿用图中断和真实用户回执，不伪造个人助手身份。
-- 后台结果：`deliveries.callbacks` 注册异步处理函数，提交时选择 `callback` 名称。业务按 `event_id` 去重；重投回调不重新执行智能体。
+交接示例保留共享 `sp/up`，校验业务工具清单，并将业务 `TOOLS` 分配给 `support`，`reception` 只负责接待和交接。实际项目应按角色重新分配工具；不要把每个参与者都自动赋予所有工具。专家和交接示例保留 `config.extra_body`，按 `harness.thinking.forward_to_frontend` 传递思考内容开关。配置协作中，各子智能体使用自己声明的 `system_prompt`；交接模式还会合并入口公共提示词，其他模式需要把共同业务约束明确写入各角色配置。
 
-改变能力后，维护业务工具清单、项目说明和对应验收用例。按项目要求运行功能验收；仅能导入代码不能证明审批、重启恢复和多副本执行已经通过验证。
+## 功能说明
+
+配置字段、审批/恢复接口、Loop/Graph 扩展及后台任务的语义统一查 [SDK 文档](../SDK.md)。本文件只说明这些示例的接入与验收，不另维护一套 API 手册。
+
+## 按图类型验收
+
+先读取 Preview 状态及 Output，复用已就绪的服务。预览未启动时，仅在用户要求启动或运行测试且平台提供启动能力时启动；不手动启动重复的常驻服务。用户暂不测试或服务不可用时，记录未执行项及原因。
+
+- 默认模型/工具对话图（包括接入 Store 工具后）可使用 `bash scripts/runtime.sh -m verify --cases tests/agent_cases.json --report .tmp/agent-verification.json`。用真实注册工具名配置 `required_tools`；Store 用例保存后读取或搜索，并验证另一用户不能读到该数据。
+- `experts.py`：通过 `/agent/v1/runs` 或 SDK 创建运行，验证原业务工具和专家实际被调用、共享业务要求进入各模型、子调用记录及最终回答。默认 verify 的独立构图与业务工具清单检查不适用于此类动态子工具入口。
+- `handoff.py`：同一用户同一会话验证 A 转 B、下一轮仍由 B 接待、B 转回 A；核对检查点、工具回执和交接次数限制。
+- `human_input.py` / `functional.py`：验证运行进入等待，使用返回的中断 ID 提交真实回复，再确认状态和最终结果；不能把等待中当成失败或假造回复跳过。
+- `map_reduce.py`：按 `items` Schema 发送输入，核对各分支及 reducer 汇总。它没有模型调用，不适用默认 verify 的模型记录断言。
+
+改变能力后维护业务工具清单、项目说明及对应验收用例。默认 verify 不能替代交互、重启恢复和多副本验收；自动化样例通过也不能表述为编程 Agent 已根据自然语言独立生成并验收通过。

package/lib/__templates__/agent/examples/experts.py

@@ -1,21 +1,27 @@
-"""Three real model calls through the platform; no database is required."""
+"""A business agent with optional expert delegation; no database is required."""
+from licos_agent_runtime.agent_graph import validate_tool_registry
 from licos_agent_runtime.harness_execution import HarnessRun
 from licos_agent_runtime.project_agent import build_project_agent
 from licos_agent_runtime.subagents import Subagents, model_subagent
 from licos_dev_sdk import create_chat_openai, resolve_llm_endpoint
 
+from tools import TOOLS
 
-def configured_model(config):
+
+def configured_model(config, *, preserve_reasoning):
     options = dict(config)
     thinking = options.pop("thinking", "auto")
     if thinking != "auto":
-        options["extra_body"] = {"thinking": {"type": thinking}}
-    return create_chat_openai(**options)
+        options["extra_body"] = {**options.get("extra_body", {}), "thinking": {"type": thinking}}
+    return create_chat_openai(**options, preserve_reasoning=preserve_reasoning)
 
 
 def create_agent(ctx):
     snapshot = ctx.metadata["agent_project_config"]
+    validate_tool_registry(TOOLS, snapshot.raw["tools"])
+    shared_prompt = "\n\n".join((snapshot.raw["sp"], snapshot.raw["up"]))
     config = snapshot.raw["config"]
+    preserve_reasoning = snapshot.harness.thinking.forward_to_frontend
     endpoint = resolve_llm_endpoint(model=config["model"], model_group=config.get("model_group", "text"))
     harness_run = HarnessRun(snapshot.harness, endpoint.context_length, config["max_completion_tokens"],
                              input_limit=endpoint.max_input_length)
@@ -23,13 +29,17 @@ def create_agent(ctx):
     # Each specialist can read its own model configuration from a project file.
     # Use per_thread only when the user wants the specialist to remember prior calls.
     team = Subagents([
-        model_subagent("research", "分析问题并整理依据", model=configured_model(config),
-                       system_prompt="根据提供的资料分析问题。依据不足时明确说明，不编造来源。",
+        model_subagent("research", "分析问题并整理依据",
+                       model=configured_model(config, preserve_reasoning=preserve_reasoning),
+                       system_prompt=shared_prompt + "\n\n根据提供的资料分析问题。依据不足时明确说明，不编造来源。",
                        memory="per_call"),
-        model_subagent("review", "检查答案中的逻辑和事实依据", model=configured_model(config),
-                       system_prompt="审查结论是否得到输入资料支持，并指出不确定性。", memory="per_call"),
+        model_subagent("review", "检查答案中的逻辑和事实依据",
+                       model=configured_model(config, preserve_reasoning=preserve_reasoning),
+                       system_prompt=shared_prompt + "\n\n审查结论是否得到输入资料支持，并指出不确定性。", memory="per_call"),
     ], ctx=ctx)
     return build_project_agent(
-        configured_model(config), team.tools(), ctx=ctx, harness=snapshot.harness, harness_run=harness_run,
-        system_prompt="协调研究和审查，按需要调用专家，再向用户提供结论。",
+        configured_model(config, preserve_reasoning=preserve_reasoning), [*TOOLS, *team.tools()], ctx=ctx,
+        harness=snapshot.harness, harness_run=harness_run,
+        system_prompt=shared_prompt + "\n\n协调研究和审查，按需要调用专家，再向用户提供结论。",
+        use_configured_agents=False,
     )