@kmlckj/licos-ai-cli 1.7.0 → 1.7.1

package/lib/__templates__/agent/AGENTS.md

@@ -37,22 +37,25 @@
 - `input + session_id` 按认证用户、项目及环境隔离，当前进程保留最近 3 个已完成问答；显式 `messages` 沿用调用方历史协议。重启会丢失短期记忆，多副本需要会话固定路由。
 - 顶层 `harness` 配置计划、上下文预算、执行上限、工具策略和结果校验；`agent_runtime` 独立选择聊天历史、检查点、运行记录、Store、缓存及交互。新项目默认内存，不因已有数据库自动持久化。
 - 用户要求记忆、状态、审批时，先区分功能和保存介质；用户未说明保存介质时请其选择，已有明确选择则直接执行。重启恢复才要求运行控制、检查点和启用的事件使用数据库。
-- 只保存聊天可使用 `history`；已有业务会话表实现 `HistoryAdapter`，不覆盖旧表。数据库模块通过独立的 `agent_runtime_v1.sql` 迁移准备，再打开对应配置；运行时代码不执行迁移。
+- 只保存聊天可使用 `history`；已有业务会话表实现 `HistoryAdapter`，不覆盖旧表。内置 database 使用当前项目托管 PostgreSQL，通过当前安装包的 `agent_runtime_v1.sql` 准备；数据库语义搜索再执行 `agent_runtime_vector_v1.sql`，内存搜索无需 SQL。脚本定位和迁移步骤见 [DATABASE.md](DATABASE.md)，运行时代码不执行迁移。
+- 三轮记忆仅为默认 Harness 策略；启用 `history` 后使用其 `recent_turns`，有检查点时使用图历史，不重复拼接。按实际启用模块更新本文件的存储和记忆说明。
 - 通用文字、单选、多选、表单和审批适用于普通预览和部署，不要求发布企业项目。启用 `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` 只写业务要求，不加入测试结果、迁移步骤或平台实现细节。
+- 升级已有项目按 [UPGRADING.md](UPGRADING.md) 检查实际加载版本、业务代码、登录方式、用户 Token、订阅指纹和状态兼容性。未配置 `agent_runtime` 的项目继续原路径；新模板不自动覆盖旧项目，不强制用户升级依赖。
+- 按需示例见 [examples/README.md](examples/README.md)，区分完整入口和工具模块；`memory.py` 没有 `create_agent`，只追加工具注册。合并入口时保留业务 `sp/up`、工具、hooks、校验器及认证方式。业务提示词不加入测试结果、迁移步骤或平台实现细节。
 - 输入支持 `input`、多轮 `messages`、`event` 及组合，保留附件和多模态内容。
-- `tests/agent_cases.json` 维护可重复的输入及业务工具验收；生成或修改后对已有预览执行 `bash scripts/runtime.sh -m verify`，失败则修复后重验。
+- 默认对话图用 `tests/agent_cases.json` 维护可重复的输入及业务工具验收；生成或修改后对已就绪的预览执行 `bash scripts/runtime.sh -m verify --cases tests/agent_cases.json --report .tmp/agent-verification.json`，失败则修复后重验。人工中断、交接、子智能体或自定义输入图按示例说明通过 `/agent/v1` 或 SDK 分步骤验收。
+- 先读取 Preview 状态和 Output，不手动启动重复常驻服务；未就绪时仅在用户要求启动或运行测试且平台提供启动能力时启动。用户暂不测试或服务不可用时，明确未执行项及原因。静态检查、模板自动化测试和编程 Agent 自主生成项目验收分别记录。
 
 
 ## 平台调用身份
 
 - `LICOS_CURRENT_USER_ID` 仅表示容器初始化用户，不能作为网页登录身份。
-- 当前用户信息、企业知识库、本体搜索/调用/订阅必须显式传本次用户 Token（Node `userToken` / Python `user_token`）。Token 失效直接返回鉴权错误，不换成容器用户。
+- 当前用户信息、企业知识库、本体用户搜索和调用必须显式传本次用户 Token（Node `userToken` / Python `user_token`）。Token 失效直接返回鉴权错误，不换成容器用户。
+- 常驻本体订阅的上游连接使用项目绑定身份；收到事件后的业务执行由 `deliveries`/`recovery` 身份解析取得原用户有效授权。它没有浏览器请求，不能要求固定浏览器 Token，也不能用订阅身份代替网页使用者。
 - 普通知识库、模型与积分接口默认使用项目身份；需要按网页登录用户执行时显式传 Token。数据库、存储、可观测性和 OAuth 应用管理使用项目身份。项目归属与平台签发的计费上下文独立保留。
 - CLI 用户操作默认按 `LICOS_CURRENT_USER_ID` 换 Token；HTTP 服务调用 CLI 时使用 `--token-stdin`。Dev CLI 可用 `--identity project` 明确选择项目身份。
 - 每个请求单独传 Token 或创建客户端，不把请求 Token、用户 ID 写进共享环境变量。

package/lib/__templates__/agent/DATABASE.md

@@ -0,0 +1,31 @@
+# 按需保存智能体状态
+
+默认使用内存。先确定用户希望保存聊天、执行状态还是业务记忆，以及是否需要重启后保留；项目已有数据库也不会自动开启持久化。
+
+| 选择 | 准备工作 |
+| --- | --- |
+| 内存（包括内存语义搜索） | 不执行数据库脚本；语义搜索仍需真实 embedding 配置 |
+| 数据库历史、检查点、运行记录、Store、缓存 | `migrations/agent_runtime_v1.sql` |
+| 数据库 Store 语义搜索 | 基础脚本成功后再执行 `migrations/agent_runtime_vector_v1.sql`，配置 embedding 工厂、维度和索引版本 |
+
+内置数据库后端使用当前项目的托管 PostgreSQL，不是外部数据库连接字符串。已有业务历史可通过 `HistoryAdapter` 接入；它不代表外部库已支持运行时的执行租约、检查点和恢复。只持久化聊天可单独配置 `history`；需要恢复执行时，检查点、运行控制及启用的事件须选一致介质。
+
+## 找到当前版本的脚本和操作说明
+
+脚本和详细说明随 `licos-agent-runtime` 包发布，不复制到启动代码里。使用 `scripts/runtime.sh` 实际选中的解释器；下面以项目虚拟环境为例：
+
+```bash
+.venv/bin/python -c 'from importlib.metadata import version; from importlib.resources import files; root=files("licos_agent_runtime"); print(version("licos-agent-runtime")); print(root.joinpath("migrations/agent_runtime_v1.sql")); print(root.joinpath("migrations/agent_runtime_vector_v1.sql")); print(root.joinpath("docs/database-setup.md"))'
+```
+
+如脚本配置了 `PYTHON_BIN`，使用该解释器；没有项目 `.venv` 时使用实际运行环境的 `python`，不要用其他环境的包版本代替。
+
+## 接入步骤
+
+1. 用 `licos-platform project-config show` 核对项目数据库模式和当前环境；内置后端要求 `licos_managed`。
+2. 检查现有 Schema、函数及迁移记录，阅读当前版本 SQL。基础脚本包含普通 `CREATE TABLE/FUNCTION`，不能重复执行；已安装则核对差异，禁止删表重建。
+3. 阅读以上路径的 `docs/database-setup.md`，通过 `licos-platform database studio-create-migration` 先 dry-run，再按用户已授权范围加 `--execute`。接口使用 `--statement`，不支持 `--file`；完整保留函数体，不按分号拆分。
+4. 检查返回的业务状态及 Schema。dry-run 不执行 SQL，命令退出成功也不能替代返回 `status=SUCCESS` 的确认。成功后再开启所需模块的 `storage: "database"`。
+5. 验证实际功能的读写及用户隔离；需要重启保留时实际验证重启。把版本、介质、迁移环境/ID 和验收结果记入 `AGENTS.md`。
+
+SQL 不随服务启动或安装自动运行。开发环境迁移不自动操作生产环境。老项目升级见 [UPGRADING.md](UPGRADING.md)，业务提示词只保留业务内容。

package/lib/__templates__/agent/README.md

@@ -10,6 +10,8 @@ LICOS 智能体项目模板，基于 Python、LangGraph、LangChain 和 `licos-a
 ├── config/
 │   └── agent_llm_config.json
 ├── AGENTS.md
+├── DATABASE.md                  # 可选持久化与数据库脚本说明
+├── UPGRADING.md                 # 已有项目升级检查清单
 ├── pyproject.toml
 ├── scripts/
 ├── skills/
@@ -77,7 +79,7 @@ Body 可以同时带 `attachments`、`files`、`references` 等业务字段；
 
 升级已有项目时，如果曾手动加入 `create_file_transfer_tools(...)`，删除该注册及配置中的 `download_file`、`upload_file`，由运行时统一提供。
 
-`config/event_subscriptions.json` 默认为空数组。启用本体订阅时，配置 `agent_runtime.deliveries` 的存储和身份解析函数，事件进入同一运行队列；数据库保存需要用户明确选择。绑定当前工作空间、项目及源码指纹，运行 `bash scripts/runtime.sh -m fingerprint` 获取源码版本。持续监听需要常驻部署；上游当前不保证稳定事件 ID 或断线补发。
+`config/event_subscriptions.json` 默认为空数组。启用本体订阅时，配置 `agent_runtime.deliveries` 的存储和身份解析函数，事件进入同一运行队列；数据库保存需要用户明确选择。绑定当前工作空间、项目及源码指纹，运行 `bash scripts/runtime.sh -m fingerprint` 获取源码版本。源码和运行配置修改完成后，重新计算并更新启用订阅的 `project_version`；不能沿用修改前的指纹。持续监听需要常驻部署；上游当前不保证稳定事件 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`。
 
@@ -147,9 +149,11 @@ Body 可以同时带 `attachments`、`files`、`references` 等业务字段；
 | Functional API | `functional_agent`、原生 `task` |
 | 重启或多副本恢复 | 运行控制、检查点、事件选择数据库；后台恢复另配置原用户身份解析函数 |
 
-数据库已存在也不会自动启用上述功能。用户选择持久化后，先检查现有 Schema，使用数据库 CLI 执行运行时包附带的独立迁移 `licos_agent_runtime/migrations/agent_runtime_v1.sql`。默认不建表；业务历史表可以通过适配器复用。
+数据库已存在也不会自动启用上述功能。内置 database 后端使用当前项目托管 PostgreSQL。用户选择持久化后，先检查 Schema 和迁移历史，再通过 CLI 显式执行当前安装包的 `migrations/agent_runtime_v1.sql`；数据库 Store 语义搜索另需 `migrations/agent_runtime_vector_v1.sql`。内存模式不执行 SQL。脚本定位及接入步骤见 [DATABASE.md](DATABASE.md)；业务历史表可以通过适配器复用。
 
-示例见 [examples/README.md](examples/README.md)，包括单智能体、人工输入、专家协作、Send 汇总、Functional API 和 Store。它们由项目按需导入，不会自动运行。完整 API 见运行时包的 `docs/agent-capabilities.md`。
+三轮窗口是默认 Harness 的内存策略。启用 `history` 后使用其 `recent_turns`；有检查点时以图会话历史为来源，不再拼接三轮记忆或历史模块的内容。原生 Store `ttl` 单位为分钟，模块 `ttl_seconds` 为秒；检查点的 `retain` 管理检查点数量，不是聊天轮数。
+
+示例见 [examples/README.md](examples/README.md)，包括单智能体、人工输入、专家协作、Send 汇总、Functional API 和 Store。完整入口与工具模块的接入方式不同：`memory.py` 只注册工具，没有 `create_agent`。它们由项目按需接入，不会自动运行。完整 API 见运行时包的 `docs/agent-capabilities.md`。
 
 配置协作支持 `supervisor/parallel/sequence/router/handoff`，分别对应总控、并行、串行、路由和交接。每个子智能体声明模型、提示词、业务工具名、记忆范围及允许传入的业务 context 字段。父子共用调用预算与标准模型/工具并发限制；自定义调用节点使用 `execution_slot/async_execution_slot` 加入共享并发。
 
@@ -157,7 +161,7 @@ Body 可以同时带 `attachments`、`files`、`references` 等业务字段；
 
 内存状态在当前服务进程存活期间可用；数据库模式不依赖粘性会话。运行总时限包含人工等待，审批期限另由 `interactions.timeout_seconds` 控制。恢复必须使用原调用者的有效授权，不能换为项目负责人。已经开始但没有确认回执的外部操作需要业务核对，不能盲目重做。
 
-旧项目不增加 `agent_runtime` 时继续原协议。新模板不会重写已发布项目；用户主动升级时保留业务代码、登录机制、`sp/up` 和已有表。切换存储采用显式导出、导入，图或状态版本改变需要项目提供迁移方案。
+旧项目不增加 `agent_runtime` 时继续原协议。新模板不会重写已发布项目；用户主动升级时按 [UPGRADING.md](UPGRADING.md) 核对实际版本、用户 Token、订阅指纹及状态兼容性，保留业务代码、登录机制、`sp/up` 和已有表。切换存储采用显式导出、导入，图或状态版本改变需要项目提供迁移方案。
 
 ## 项目上下文
 
@@ -175,7 +179,7 @@ Body 可以同时带 `attachments`、`files`、`references` 等业务字段；
 
 ## 生成后验收
 
-在平台预览启动后运行：
+先读取平台 Preview 状态和 Output，复用已经就绪的服务。默认模型与工具对话图运行：
 
 ```bash
 bash scripts/runtime.sh -m verify --cases tests/agent_cases.json --report .tmp/agent-verification.json
@@ -183,6 +187,10 @@ bash scripts/runtime.sh -m verify --cases tests/agent_cases.json --report .tmp/a
 
 命令检查导入、图输入、工具注册，并对每个用例调用 HTTP 与 SSE，核对真实模型调用、工具调用、输入证据和运行用量。相同 `session_group` 的用例复用会话，检查跨请求短期记忆；业务查询用例可增加 `required_tools`。报告保留 run_id，失败返回非零退出码。
 
+该命令要求标准 input/messages/event 输入、模型调用和一次完成的对话。人工中断、交接、动态子工具或自定义输入图按 [examples/README.md](examples/README.md) 使用 `/agent/v1` 或 SDK 分步骤验证，不直接套用默认用例。
+
+预览未就绪时，在用户要求启动或运行测试且平台提供启动能力的前提下启动并等待，不手动启动重复常驻服务。用户暂不测试或服务不可用时，记录实际完成的检查、未执行项和原因，不能声称功能验收通过。模板自动化验收与让编程 Agent 根据自然语言独立生成项目的验收分别记录。
+
 预览、本地运行和验收共用 `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=...`。

package/lib/__templates__/agent/UPGRADING.md

@@ -0,0 +1,48 @@
+# 已有智能体项目升级检查清单
+
+只有用户要求升级或所需能力确实依赖新版本时才调整依赖。原项目不升级仍可使用其原有功能；不要重新执行初始化来覆盖入口、登录方式、业务表或配置。
+
+## 1. 记录基线与实际版本
+
+- 读取项目 `AGENTS.md`、入口、业务工具、模型配置、认证配置、事件订阅、依赖及锁文件，记录当前可用接口和真实业务用例。
+- 使用 `scripts/runtime.sh` 所选的项目解释器检查安装包版本，不能用其他全局 Python 环境的版本代替。当前模板依赖为 Runtime >=0.6.8、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,21 +1,40 @@
 # 按需使用的智能体示例
 
-默认入口仍是 `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`，不必开启检查点。
+## 接入入口与工具
+
+在新建演示项目中，完整入口可以由 `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`。代码组合入口关闭配置协作，不同时维护两套团队。
+
+`memory.py` 不替换入口。需要保存和搜索偏好时，在 `src/tools/__init__.py` 保留现有工具并追加：
+
+```python
+from examples.memory import save_preference, search_preferences
+
+# 放在现有 TOOLS 定义后，保留原业务工具。
+TOOLS += [save_preference, search_preferences]
+```
+
+同时在配置 `tools` 中追加 `save_preference`、`search_preferences`，开启 `agent_runtime.store.enabled`。语义搜索必须配置接收 `ctx` 的真实 embedding 工厂、实际维度和 `index_version`，具体字段见运行时能力文档；仅需保存偏好时只注册 `save_preference`，不必开启语义索引。按业务需要更新 `sp/up`，不能仅注册工具就宣称能搜索。
+
+示例启用的能力默认放内存。用户要求重启恢复时，把 `checkpoints`、`runs` 和已启用的 `events` 一起改为 `storage: "database"`。先按 [DATABASE.md](../DATABASE.md) 检查托管库并通过 CLI 显式执行基础脚本；数据库语义搜索再加向量脚本，内存搜索无需 SQL。仅要保存聊天则单独配置 `history`，不必开启检查点。
 
 `handoff.py` 使用 SDK 代码声明允许交接的目标；也可用 `collaboration.mode: "handoff"`、`participants`、`initial_agent` 配置标准交接。第一轮从初始智能体开始，后续同一会话从保存的 `active_agent` 开始；`transfer_to_<名称>` 的参数只提供需要传给接收者的交接说明。内部工具历史按子智能体的记忆范围保存。
 
+交接示例保留共享 `sp/up`，校验业务工具清单，并将业务 `TOOLS` 分配给 `support`，`reception` 只负责接待和交接。实际项目应按角色重新分配工具；不要把每个参与者都自动赋予所有工具。专家和交接示例保留 `config.extra_body`，按 `harness.thinking.forward_to_frontend` 传递思考内容开关。配置协作中，各子智能体使用自己声明的 `system_prompt`；交接模式还会合并入口公共提示词，其他模式需要把共同业务约束明确写入各角色配置。
+
 ## 审批与恢复
 
 开启交互和检查点后，把需要审批的真实工具名加入 `harness.tool_policy.require_approval`。前端支持允许、拒绝、修改参数后批准；`interactions.review_output` 可要求审查最终答案。文字、多选、表单通过 `ask_user` 的 `kind/options/schema` 参数定义。
@@ -44,4 +63,14 @@ SDK 调用顺序：
 - 企业发布项目：节点使用 `invoke_enterprise(record_id, arguments, key=..., ctx=ctx)`，平台验证当前使用者、来源项目及发布契约；人工交互沿用图中断和真实用户回执，不伪造个人助手身份。
 - 后台结果：`deliveries.callbacks` 注册异步处理函数，提交时选择 `callback` 名称。业务按 `event_id` 去重；重投回调不重新执行智能体。
 
-改变能力后，维护业务工具清单、项目说明和对应验收用例。按项目要求运行功能验收；仅能导入代码不能证明审批、重启恢复和多副本执行已经通过验证。
+## 按图类型验收
+
+先读取 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,
     )

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

@@ -1,15 +1,19 @@
 """Direct conversation handoffs; explicitly enable memory/database checkpoints."""
+from licos_agent_runtime.agent_graph import validate_tool_registry
 from licos_agent_runtime.agent_handoff import build_handoff, model_handoff_agent
 from licos_agent_runtime.harness_execution import HarnessRun
 from licos_agent_runtime.subagents import Subagents
 from licos_dev_sdk import resolve_llm_endpoint
 
 from examples.experts import configured_model
+from tools import TOOLS
 
 
 def create_agent(ctx):
     snapshot = ctx.metadata["agent_project_config"]
+    validate_tool_registry(TOOLS, snapshot.raw["tools"])
     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"))
     ctx.metadata["agent_harness_run"] = HarnessRun(
         snapshot.harness, endpoint.context_length, config["max_completion_tokens"],
@@ -19,15 +23,15 @@ def create_agent(ctx):
     team = Subagents([
         model_handoff_agent(
             "reception", "接待用户并明确需求",
-            model=configured_model(config), shared_prompt=shared_prompt,
+            model=configured_model(config, preserve_reasoning=preserve_reasoning), shared_prompt=shared_prompt,
             system_prompt="先了解用户的问题。技术问题交给 support，并说明已确认的信息。",
             destinations={"support": "排查和解释技术问题"}, memory="per_call",
         ),
         model_handoff_agent(
             "support", "直接帮助用户解决技术问题",
-            model=configured_model(config), shared_prompt=shared_prompt,
+            model=configured_model(config, preserve_reasoning=preserve_reasoning), shared_prompt=shared_prompt,
             system_prompt="直接和用户沟通技术问题，必要时继续追问。非技术咨询交回 reception。",
-            destinations={"reception": "接待与非技术咨询"}, memory="per_call",
+            destinations={"reception": "接待与非技术咨询"}, tools=TOOLS, memory="per_call",
         ),
     ], ctx=ctx)
     return build_handoff(team, initial_agent="reception", max_handoffs=8)

package/lib/__templates__/agent/pyproject.toml

@@ -4,7 +4,7 @@ version = "0.1.0"
 description = "LICOS LangGraph agent project"
 requires-python = ">=3.11"
 dependencies = [
-    "licos-agent-runtime>=0.6.7",
+    "licos-agent-runtime>=0.6.8",
     "licos-platform-sdk>=0.7.6",
     "licos-dev-sdk>=0.6.6",
 ]

package/lib/__templates__/agent/requirements.txt

@@ -1,3 +1,3 @@
-licos-agent-runtime>=0.6.7
+licos-agent-runtime>=0.6.8
 licos-platform-sdk>=0.7.6
 licos-dev-sdk>=0.6.6

package/lib/__templates__/agent/src/agents/agent.py

@@ -28,7 +28,7 @@ def create_agent(_ctx: Any = None) -> Any:
     model_options = dict(settings["config"])
     thinking = model_options.pop("thinking", "auto")
     if thinking != "auto":
-        model_options["extra_body"] = {"thinking": {"type": thinking}}
+        model_options["extra_body"] = {**model_options.get("extra_body", {}), "thinking": {"type": thinking}}
     model = create_chat_openai(
         **model_options,
         preserve_reasoning=bool(snapshot.harness and snapshot.harness.thinking.forward_to_frontend),

package/lib/__templates__/agent/template.config.js

@@ -1,8 +1,10 @@
-const description = `Agent（智能体项目）：\`licos init \${LICOS_PROJECT_PATH} --template agent\`
+const description = `Agent（智能体项目）：\`licos init \${LICOS_PROJECT_PATH} --template agent --skip-install --skip-dev --skip-commit\`
 - 适用：Python + LangGraph/LangChain 智能体项目
 - 使用 licos-agent-runtime 提供 /run、/stream_run、/cancel、OpenAI compatible 等运行时接口
 - agent_runtime 分别配置状态、聊天、Store、交互及保存方式；默认内存，用户选择持久化才接数据库
 - 支持子智能体、原生图、人工审批、状态恢复、分支和 Functional API；examples/ 提供按需示例
+- examples/README.md 区分完整入口与工具模块；已有项目升级参考 UPGRADING.md，保留业务、授权和状态
+- DATABASE.md 说明托管数据库范围和基础/向量脚本的定位及显式迁移；内存模式不执行 SQL
 - 使用 config/agent_llm_config.json 维护模型、业务提示词和业务工具列表，并通过 /agent/config、/agent/canvas 暴露给预览
 - 默认提供普通文件工具和 skills/<name>/SKILL.md 自动发现，技能资源按需只读加载
 - 上传附件自动保存到当前用户的会话目录，支持 HTTP(S) URL 和 SDK 页的 base64 data URL；默认内置 download_file、upload_file，生成文件上传后返回真实下载链接，文档处理工具按需接入
@@ -45,6 +47,8 @@ const config = {
     console.log('  - Framework: LangGraph + LangChain');
     console.log('  - State storage: memory; enable database only when requested');
     console.log('  - Optional capabilities and examples: examples/README.md');
+    console.log('  - Existing project upgrade checklist: UPGRADING.md');
+    console.log('  - Optional persistence and migrations: DATABASE.md');
     console.log(`  - Port: ${_context.port}`);
   },
 };

package/lib/__templates__/templates.json

@@ -3,7 +3,7 @@
   "templates": [
     {
       "name": "agent",
-      "description": "Agent（智能体项目）：`licos init ${LICOS_PROJECT_PATH} --template agent`\n- 适用：Python + LangGraph/LangChain 智能体项目\n- 使用 licos-agent-runtime 提供 /run、/stream_run、/cancel、OpenAI compatible 等运行时接口\n- agent_runtime 分别配置状态、聊天、Store、交互及保存方式；默认内存，用户选择持久化才接数据库\n- 支持子智能体、原生图、人工审批、状态恢复、分支和 Functional API；examples/ 提供按需示例\n- 使用 config/agent_llm_config.json 维护模型、业务提示词和业务工具列表，并通过 /agent/config、/agent/canvas 暴露给预览\n- 默认提供普通文件工具和 skills/<name>/SKILL.md 自动发现，技能资源按需只读加载\n- 上传附件自动保存到当前用户的会话目录，支持 HTTP(S) URL 和 SDK 页的 base64 data URL；默认内置 download_file、upload_file，生成文件上传后返回真实下载链接，文档处理工具按需接入\n- 项目源码位于 /workspace/projects，平台数据位于 /workspace/.licos",
+      "description": "Agent（智能体项目）：`licos init ${LICOS_PROJECT_PATH} --template agent --skip-install --skip-dev --skip-commit`\n- 适用：Python + LangGraph/LangChain 智能体项目\n- 使用 licos-agent-runtime 提供 /run、/stream_run、/cancel、OpenAI compatible 等运行时接口\n- agent_runtime 分别配置状态、聊天、Store、交互及保存方式；默认内存，用户选择持久化才接数据库\n- 支持子智能体、原生图、人工审批、状态恢复、分支和 Functional API；examples/ 提供按需示例\n- examples/README.md 区分完整入口与工具模块；已有项目升级参考 UPGRADING.md，保留业务、授权和状态\n- DATABASE.md 说明托管数据库范围和基础/向量脚本的定位及显式迁移；内存模式不执行 SQL\n- 使用 config/agent_llm_config.json 维护模型、业务提示词和业务工具列表，并通过 /agent/config、/agent/canvas 暴露给预览\n- 默认提供普通文件工具和 skills/<name>/SKILL.md 自动发现，技能资源按需只读加载\n- 上传附件自动保存到当前用户的会话目录，支持 HTTP(S) URL 和 SDK 页的 base64 data URL；默认内置 download_file、upload_file，生成文件上传后返回真实下载链接，文档处理工具按需接入\n- 项目源码位于 /workspace/projects，平台数据位于 /workspace/.licos",
       "location": "./agent",
       "paramsSchema": {
         "type": "object",

package/lib/__templates__/workflow/pyproject.toml

@@ -4,7 +4,7 @@ version = "0.1.0"
 description = "LICOS LangGraph workflow project"
 requires-python = ">=3.12"
 dependencies = [
-    "licos-agent-runtime>=0.6.7",
+    "licos-agent-runtime>=0.6.8",
     "licos-platform-sdk>=0.7.6",
     "licos-dev-sdk>=0.6.6",
 ]

package/lib/__templates__/workflow/requirements.txt

@@ -1,3 +1,3 @@
-licos-agent-runtime>=0.6.7
+licos-agent-runtime>=0.6.8
 licos-platform-sdk>=0.7.6
 licos-dev-sdk>=0.6.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kmlckj/licos-ai-cli",
-  "version": "1.7.0",
+  "version": "1.7.1",
   "description": "LICOS AI coding workspace CLI - project template engine and dev tools",
   "license": "MIT",
   "author": "kmlckj",