@kmlckj/licos-ai-cli 1.7.1 → 1.7.3

package/lib/__templates__/agent/AGENTS.md

@@ -1,71 +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`，不覆盖旧表。内置 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；重连只订阅已有运行，不能再次提交执行。
-- 升级已有项目按 [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 --cases tests/agent_cases.json --report .tmp/agent-verification.json`，失败则修复后重验。人工中断、交接、子智能体或自定义输入图按示例说明通过 `/agent/v1` 或 SDK 分步骤验收。
-- 先读取 Preview 状态和 Output，不手动启动重复常驻服务；未就绪时仅在用户要求启动或运行测试且平台提供启动能力时启动。用户暂不测试或服务不可用时，明确未执行项及原因。静态检查、模板自动化测试和编程 Agent 自主生成项目验收分别记录。
+以下为模板初始状态，开发后按实际配置更新：
 
+- 默认模型与工具对话入口，业务工具清单为空。
+- SDK 提供会话文件和技能工具，具体协议查 SDK 文档。
+- 短期对话记忆：当前进程最近三轮；运行与事件：内存。
+- 聊天历史持久化、检查点、Store、缓存及后台投递：未开启。
+- 数据库迁移：未执行。用户的持久化选择：尚无；不因已有数据库自动启用。
+- 人工交互、自定义图及多智能体示例：未接入，examples/ 不自动运行。
 
-## 平台调用身份
+## 项目技能
 
-- `LICOS_CURRENT_USER_ID` 仅表示容器初始化用户，不能作为网页登录身份。
-- 当前用户信息、企业知识库、本体用户搜索和调用必须显式传本次用户 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 写进共享环境变量。
+| 技能 | 位置 | 资源 |
+| --- | --- | --- |
+| 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

@@ -1,31 +1,11 @@
-# 按需保存智能体状态
+# 持久化接入步骤
 
-默认使用内存。先确定用户希望保存聊天、执行状态还是业务记忆，以及是否需要重启后保留；项目已有数据库也不会自动开启持久化。
+默认沿用内存。先记录用户希望保存的内容和是否需要重启保留；只有选择持久化时才准备数据库，已有数据库不自动改变决定。
 
-| 选择 | 准备工作 |
-| --- | --- |
-| 内存（包括内存语义搜索） | 不执行数据库脚本；语义搜索仍需真实 embedding 配置 |
-| 数据库历史、检查点、运行记录、Store、缓存 | `migrations/agent_runtime_v1.sql` |
-| 数据库 Store 语义搜索 | 基础脚本成功后再执行 `migrations/agent_runtime_vector_v1.sql`，配置 embedding 工厂、维度和索引版本 |
+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、执行结果及待验收项。
 
-内置数据库后端使用当前项目的托管 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)，业务提示词只保留业务内容。
+SQL 不嵌入入口、业务工具、启动脚本或安装钩子。开发迁移不自动操作生产环境。老项目按 [UPGRADING.md](UPGRADING.md) 保留已有数据和功能。

package/lib/__templates__/agent/README.md

@@ -1,206 +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
-├── DATABASE.md                  # 可选持久化与数据库脚本说明
-├── UPGRADING.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 接口
-
-- `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}`：检查点状态、历史、编辑、分支、回放
+- [SDK.md](SDK.md)：定位当前安装版本的 SDK 文档，查询功能、API、配置及限制。
+- [AGENTS.md](AGENTS.md)：本项目的业务目标、实际实现、保存方式和验收记录。
+- [examples/README.md](examples/README.md)：示例选择、合并与运行。
+- [DATABASE.md](DATABASE.md)：用户选择持久化后的接入步骤。
+- [UPGRADING.md](UPGRADING.md)：已有项目升级与兼容性检查。
 
-`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` 获取源码版本。源码和运行配置修改完成后，重新计算并更新启用订阅的 `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`。
-
-模型消息会带附件的保存状态和本地相对路径。`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` 的模型思考开关分别控制
-
-模板 `sp` 保存业务角色和真实结果要求。`build_project_agent` 按实际启用的工具追加文件及技能能力说明；禁用工具不会暴露给模型。模型上下文窗口来自平台目录，缺少窗口信息会返回配置错误。
-
-## 按需启用状态与协作
+业务扩展按需增加 src/storage、src/memory 等模块。用户会话文件由运行时管理，不放进共享源码或技能资源目录。
 
-| 需要的功能 | 配置或代码 |
-| --- | --- |
-| 完成后的聊天记录 | `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` |
-| 重启或多副本恢复 | 运行控制、检查点、事件选择数据库；后台恢复另配置原用户身份解析函数 |
+## 接入与开发
 
-数据库已存在也不会自动启用上述功能。内置 database 后端使用当前项目托管 PostgreSQL。用户选择持久化后，先检查 Schema 和迁移历史，再通过 CLI 显式执行当前安装包的 `migrations/agent_runtime_v1.sql`；数据库 Store 语义搜索另需 `migrations/agent_runtime_vector_v1.sql`。内存模式不执行 SQL。脚本定位及接入步骤见 [DATABASE.md](DATABASE.md)；业务历史表可以通过适配器复用。
+1. 读取 AGENTS.md、配置、业务入口及依赖。首次开发先确定业务目标、工具、输入输出和成功标准。
+2. 按 SDK.md 查对应版本功能文档，选配置或代码扩展；沿用当前业务配置和身份。
+3. 业务工具放 src/tools/，同步导入注册与配置中的工具清单。技能连同附属资源放 skills/ 并维护简介和引用路径。
+4. 修改入口时保留业务工具、提示词和登录机制。合并示例前阅读 examples/README.md，区分完整入口与工具模块。
+5. 同步 AGENTS.md 和本项目测试用例，按实际启用能力验收。
 
-三轮窗口是默认 Harness 的内存策略。启用 `history` 后使用其 `recent_turns`；有检查点时以图会话历史为来源，不再拼接三轮记忆或历史模块的内容。原生 Store `ttl` 单位为分钟，模块 `ttl_seconds` 为秒；检查点的 `retain` 管理检查点数量，不是聊天轮数。
+业务 sp/up 只写角色、任务、策略和输出要求；功能说明和 API 查 SDK，开发步骤和测试结果留在项目文档。
 
-示例见 [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` 加入共享并发。
+平台内复用 Preview，不手动启动重复常驻服务。独立本地开发可运行：
 
-`handoff` 的接收者直接回答用户，同一会话下一轮继续由当前智能体处理。它要求显式开启检查点，默认选择内存；`initial_agent` 指定初始处理者，`max_rounds` 限制每轮交接次数。配置方式自动提供交接工具，代码方式见 `examples/handoff.py`。交接只传用户可见对话、附件和明确说明，保留双方各自的内部工具历史。
-
-内存状态在当前服务进程存活期间可用；数据库模式不依赖粘性会话。运行总时限包含人工等待，审批期限另由 `interactions.timeout_seconds` 控制。恢复必须使用原调用者的有效授权，不能换为项目负责人。已经开始但没有确认回执的外部操作需要业务核对，不能盲目重做。
-
-旧项目不增加 `agent_runtime` 时继续原协议。新模板不会重写已发布项目；用户主动升级时按 [UPGRADING.md](UPGRADING.md) 核对实际版本、用户 Token、订阅指纹及状态兼容性，保留业务代码、登录机制、`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 %>
+```
 
-先读取平台 Preview 状态和 Output，复用已经就绪的服务。默认模型与工具对话图运行：
+预览、本地运行和验收共用 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，失败返回非零退出码。
-
-该命令要求标准 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=...`。
-
-## 编程项目登录身份
+验收参数、用例字段及适用范围查 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

@@ -5,7 +5,7 @@
 ## 1. 记录基线与实际版本
 
 - 读取项目 `AGENTS.md`、入口、业务工具、模型配置、认证配置、事件订阅、依赖及锁文件，记录当前可用接口和真实业务用例。
-- 使用 `scripts/runtime.sh` 所选的项目解释器检查安装包版本，不能用其他全局 Python 环境的版本代替。当前模板依赖为 Runtime >=0.6.8、Platform SDK >=0.7.6、Dev SDK >=0.6.6，Python >=3.11；以项目的依赖声明、锁文件和实际安装结果为准。
+- 使用 `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。不要将用户凭证保存进备份、源码或日志。
 

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

@@ -29,39 +29,13 @@ 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_<名称>` 的参数只提供需要传给接收者的交接说明。内部工具历史按子智能体的记忆范围保存。
+示例未替项目决定持久化。按用户选择准备运行配置；数据库接入见 [DATABASE.md](../DATABASE.md)，模块约束见 [SDK 文档](../SDK.md)。
 
 交接示例保留共享 `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` 参数定义。
-
-SDK 调用顺序：
-
-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` 管理检查点。回放会调用后续模型和工具，必须确认业务写入的幂等规则。
-
-`harness.execution.max_duration_seconds` 包含人工等待；长时间审批需调整该值。内存只在当前进程有效，数据库也不能自动恢复进程中的任意 Python 行，只能从已提交的图边界继续。
-
-## 业务扩展
+## 功能说明
 
-- 标准协作也可直接配置 `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` 去重；重投回调不重新执行智能体。
+配置字段、审批/恢复接口、Loop/Graph 扩展及后台任务的语义统一查 [SDK 文档](../SDK.md)。本文件只说明这些示例的接入与验收，不另维护一套 API 手册。
 
 ## 按图类型验收
 

package/lib/__templates__/agent/pyproject.toml

@@ -1,15 +1,15 @@
-[project]
-name = "<%= appName %>"
-version = "0.1.0"
-description = "LICOS LangGraph agent project"
-requires-python = ">=3.11"
-dependencies = [
-    "licos-agent-runtime>=0.6.8",
-    "licos-platform-sdk>=0.7.6",
-    "licos-dev-sdk>=0.6.6",
-]
-
-[tool.uv]
-[[tool.uv.index]]
-url = "https://mirrors.aliyun.com/pypi/simple/"
-default = true
+[project]
+name = "<%= appName %>"
+version = "0.1.0"
+description = "LICOS LangGraph agent project"
+requires-python = ">=3.11"
+dependencies = [
+    "licos-agent-runtime>=0.6.10",
+    "licos-platform-sdk>=0.7.6",
+    "licos-dev-sdk>=0.6.6",
+]
+
+[tool.uv]
+[[tool.uv.index]]
+url = "https://mirrors.aliyun.com/pypi/simple/"
+default = true

package/lib/__templates__/agent/requirements.txt

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

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

@@ -1,13 +1,8 @@
 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，生成文件上传后返回真实下载链接，文档处理工具按需接入
+- README.md 介绍项目结构与开发步骤，AGENTS.md 记录项目实际实现和用户选择
+- 功能、API、配置字段及限制从 SDK.md 定位实际安装版本的 SDK 文档，按需查阅
+- examples/README.md 说明示例接入；DATABASE.md、UPGRADING.md 分别说明持久化准备和已有项目升级
 - 项目源码位于 /workspace/projects，平台数据位于 /workspace/.licos`;
 
 const config = {
@@ -46,7 +41,8 @@ const config = {
     console.log('  - Runtime: licos-agent-runtime');
     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('  - SDK documentation for the installed version: SDK.md');
+    console.log('  - Example integration: 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__/workflow/AGENTS.md

@@ -1,58 +1,30 @@
 # 项目上下文
 
-## 技术栈
-
-- **项目类型**: WORKFLOW
-- **运行时**: Python + LangGraph + licos-agent-runtime
-- **入口**: `src/graphs/graph.py`
-
-## 目录结构
-
-```text
-├── config/
-├── scripts/
-├── src/
-│   ├── main.py
-│   └── graphs/
-│       ├── graph.py
-│       ├── state.py
-│       └── nodes/
-└── AGENTS.md
-```
-
-## 项目说明
-
-本文件用于记录用户项目可维护的长期上下文，例如业务目标、节点清单、外部 API 约定、输入输出样例、测试方式和后续注意事项。
-
-维护规则：
-
-- `AGENTS.md` 只是项目索引，输入输出样例必须跟随 `src/graphs/state.py` 和节点实现更新。
-- 工作流存在真实业务节点时，不要把输入输出写成 `{}`，除非它确实没有外部输入也没有返回结果。
-- 涉及文件输入/输出时，schema 使用文件对象字段，例如 `url`、`file_type`、`content`、`name`。节点生成文件时优先写入 `assets/`，并在输出中返回 `/assets/<文件名>`、`assets/<文件名>` 或本地文件路径。运行时会自动把输出文件发布到 Studio 对象存储并补齐签名 URL、`download_url`、`file_id`、`expires_at` 等字段。
-- 不要在节点代码里手写 workspace-file-service 公共 URL、MinIO URL、签名参数或平台文件服务路径；部署后的工作流没有开发态文件服务，文件发布交给运行时统一处理。
-- 如果文档与源码 schema 冲突，应修正文档，不要为了匹配文档清空 `GraphInput` / `GraphOutput`。
-- 可视化条件节点必须在 `graph.py` 的 `add_node(..., metadata={...})` 中保存 `definition.branches`；`branches[].id` 与路由函数返回值一致，`branches[].target` 与 `add_conditional_edges(..., path_map=...)` 目标一致。条件节点函数只透传状态，不要把路由函数同时作为节点函数。
-- 根据画布 QueryDiff 修改已有 Action 节点时，必须以 QueryDiff 的 `node.id` 为准更新同一个节点的 metadata、状态字段和实现文件；只有 QueryDiff 明确是新增节点且用户明确要增加业务步骤时才新增节点。
-- 禁止保留默认标题“请填写动作内容”作为最终节点标题；Action 节点标题必须稳定、可读并表达业务含义，已有节点的 ID 不能因为标题或内容调整而改变。
-- 默认不创建持久化配置、迁移文件或检查点表。只有用户明确要求本项目断点续跑时，才按 README 中的运行时契约在本项目生成版本化 SQL 迁移，核对目标项目与环境并执行、加入 `config/workflow-runtime.json`，并检查图编译时使用 `workflow_checkpointer()`。
-- 只有用户明确要求人工处理或异步设备回执时，才在本项目启用 `signals.enabled` 并生成 README 指定的增量迁移；普通项目不加等待表或字段。人工和回执共用 `/workflow/instances/{instance_id}/signals`，`/resume` 只处理执行失败。设备下发与等待回执必须分为两个节点，采用稳定 `wait_id` 和外部幂等键；参见 `examples/wait_signal.md`。
-- 有副作用的业务节点在恢复后可能再次执行。写入外部系统必须使用由工作流实例 ID、稳定节点 ID 和业务操作号组成的幂等键；对没有幂等能力的系统，先查询原操作结果，状态不明时停止并交给业务规则处理，不自动重复写入。
-
-
-## 平台调用身份
-
-- `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 写进共享环境变量。
-
-## 编程项目登录身份
-
-- 有内置登录时使用内置登录会话；没有内置登录时使用当前 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 提示词。
+功能用法查 [SDK.md](SDK.md)，结构与接入见 [README.md](README.md)。本文件只记录当前项目事实。
+
+## 当前项目
+
+- 类型：WORKFLOW。
+- 图入口：src/graphs/graph.py 的 create_graph。
+- 默认输入：topic 字符串；默认输出：answer 字符串。
+- 默认节点：generate_answer，示例文本转换，metadata.type 为 action；未调用外部系统。
+- 业务目标和成功标准：开发时按用户需求填写。
+- 认证：config/licos-auth.json，初始为平台登录；已有项目保留实际登录方案。
+- 依赖与实际版本：以 requirements.txt、pyproject.toml、项目锁文件和运行环境记录为准。
+
+## 保存方式与外部依赖
+
+- 工作流持久化未开启，未创建 config/workflow-runtime.json。
+- 数据库迁移未执行；用户尚未要求持久化。
+- 等待/设备回执示例未接入，不能声明已实现。
+- 开发后记录真实数据库、迁移环境/ID、身份与外部依赖，不写凭证。
+
+## 业务节点与配置索引
+
+新增真实业务后维护节点 ID、类型、标题、源码、输入输出、配置路径和连线；另列子图及循环入口。Schema 与源码为事实来源，文档过时应修正文档。
+
+## 验收与变更记录
+
+尚未记录业务验收。后续记录参数和画布检查、真实运行结果、未完成项及原因；持久化项目另记重启验证、未完成实例与升级回退安排。
+
+节点、状态、连接、配置、提示词和保存方式改变后同步本文件，不复制 SDK 通用 API 手册。

package/lib/__templates__/workflow/DATABASE.md

@@ -0,0 +1,11 @@
+# 工作流持久化接入
+
+用户明确要求保存执行状态、跨重启恢复或持久化等待时，先查 [SDK.md](SDK.md) 中当前版本的工作流协议。工作流与智能体有各自配置和存储契约，不能直接复制对方的配置或 SQL。
+
+1. 记录用户需求和保存方式，核对当前项目、环境、已有 Schema 与迁移历史。
+2. 阅读 SDK docs/workflow-runtime.md 的表、执行权、检查点和信号约束，根据本项目所需功能编写独立版本化 SQL。
+3. 使用平台数据库 CLI 检查、dry-run，并在已有授权范围内显式执行；核对业务状态和实际 Schema，不仅检查退出码。
+4. 修改项目配置和构图入口，保持已有数据、登录方式和业务行为。
+5. 验证实际持久化、隔离、重启恢复及选用的等待/回执路径，在 AGENTS.md 记录环境、迁移 ID 和结果。
+
+不在节点、启动或安装代码执行迁移；已有对象按差异做增量变更。开发环境成功不代表生产已准备。接口和字段以项目安装版本文档为准。

package/lib/__templates__/workflow/README.md

@@ -1,150 +1,53 @@
 # <%= appName %>
 
-LICOS 工作流项目模板，基于 Python、LangGraph 和 `licos-agent-runtime`。
+LICOS 编程工作流项目，基于 Python、LangGraph 和 licos-agent-runtime。
 
-## 目录
+## 文档入口
 
-```text
-.
-├── .licos
-├── AGENTS.md
-├── config/
-├── pyproject.toml
-├── scripts/
-└── src/
-    ├── main.py
-    └── graphs/
-        └── graph.py
-```
-
-## 本地运行
+- [SDK.md](SDK.md)：按项目实际版本查功能、API、配置和限制。
+- [AGENTS.md](AGENTS.md)：本项目真实业务、节点索引、用户选择和验收记录。
+- [DATABASE.md](DATABASE.md)：用户选择持久化后的接入步骤。
+- [UPGRADING.md](UPGRADING.md)：已有项目兼容和升级步骤。
+- [回执示例](examples/wait_signal.md)：下发与等待节点的接入示例。
 
-```bash
-bash scripts/setup.sh
-bash scripts/http_run.sh -p <%= port %>
-```
+## 项目结构
 
-## HTTP 接口
-
-- `GET /health`
-- `POST /run`
-- `POST /stream_run`
-- `POST /cancel/{run_id}`
-- `POST /node_run/{node_id}`
-- `GET /graph_parameter`
-- `GET /agent/canvas`
-- `POST /agent/canvas`
-- `POST /agent/canvas_submit`
-- `POST /v1/api/project/{project_id}/agent/canvas`
-- `POST /v1/api/project/{project_id}/agent/canvas_submit`
-
-`POST /run` 和 `POST /stream_run` 的 Body 必须匹配工作流输入 schema。模板默认输入是：
-
-```json
-{
-  "topic": "AI 新闻热点"
-}
+```text
+.licos                      # CLI 配置文件
+config/licos-auth.json       # 项目认证
+src/main.py                 # 服务入口
+src/graphs/graph.py          # 默认示例图与稳定构建入口
+scripts/                    # 安装、运行、打包
+requirements.txt
+pyproject.toml
 ```
 
-工作流不会把智能体的 `messages` 或平台 `content.query.prompt` 自动转换成图输入；前端应先调用 `/graph_parameter` 获取 schema，再按 schema 组装 Body。
+新增真实业务时按职责增加 src/graphs/state.py、src/graphs/nodes/ 和 config/*_cfg.json；节点、状态和配置按 SDK 约定实现。用户要求画布编辑时修改真实源码，项目说明跟随源码更新。
 
-`POST /stream_run` 使用工作流流式协议，事件类型包括 `workflow_start`、`workflow_end`、`error`、`ping`；请求头 `X-Workflow-Stream-Mode: debug` 会额外输出 `node_start`、`node_end`。
+## 默认示例与开发步骤
 
-每次运行可以预先生成 `X-Run-Id`；调用 `POST /cancel/{run_id}` 后，应以服务端返回的取消状态为准。流式执行只有收到 `workflow_end` 才算完成，`node_end` 是节点调试信息。
+模板输入为 topic 字符串，输出为 answer 字符串，仅演示图执行，不调用模型或外部系统。持久化与等待均未开启。
 
-## 按项目启用断点续跑
+1. 先读项目说明、实际图和依赖，确定业务输入输出与成功标准。
+2. 按 SDK.md 查对应版本的工作流说明，选择节点和配置，保留已有业务、身份及稳定入口。
+3. 新增节点时同步 Schema、图中注册与连线、metadata、配置和 AGENTS.md；不要把真实业务输入输出简化为空。
+4. 按实际图输入构造用例，复用 Preview 验证参数、画布和运行结果。功能用法不在本 README 另维护。
 
-普通项目无需数据库表或持久化配置。只有用户明确要求本项目跨重启恢复时，Agent 才为**该项目**生成版本化 SQL 迁移文件，核对目标项目与环境后执行，并创建 `config/workflow-runtime.json`：
-
-```json
-{
-  "durability": {
-    "enabled": true,
-    "graph_version": "v1"
-  }
-}
-```
+## 运行
 
-项目数据库由 `licos-platform-sdk` 的 database 接口访问。迁移文件放在该用户项目内，由 Agent 根据下列运行时契约生成；不要在 AIOS 仓库预置通用迁移，也不要把建表 SQL 放进节点代码或运行时代码：
+平台内复用已有预览；独立本地开发运行：
 
-- `public.workflow_instances`：`instance_id text` 主键；`workspace_id`、`project_id`、`environment`、`owner_user_id`、`graph_version`、`input_hash`、`input_data`、`status`、`last_run_id` 均为非空 `text`；`lease_until_ms`、`created_at_ms`、`updated_at_ms` 为非空 `bigint`，租约默认 0；`output_data`、`error_message` 为可空 `text`。
-- `public.workflow_checkpoints`：`thread_id`、`checkpoint_ns`、`checkpoint_id` 为非空 `text` 复合主键；`thread_id` 外键引用 `workflow_instances.instance_id` 并级联删除；`run_id`、`checkpoint_type`、`checkpoint_data`、`metadata_type`、`metadata_data` 为非空 `text`，`parent_checkpoint_id` 为可空 `text`。增加 `(thread_id, checkpoint_ns, checkpoint_id DESC)` 索引。
-- `public.workflow_pending_writes`：`thread_id`、`checkpoint_ns`、`checkpoint_id`、`task_id` 为非空 `text`，`write_idx` 为非空 `integer`，五列组成复合主键；`run_id`、`channel`、`value_type`、`value_data`、`task_path` 为非空 `text`。不要给 pending writes 到检查点加外键：LangGraph 可能在对应检查点事务提交前写入 pending writes。删除实例线程时运行时会先清理 pending writes，再清理检查点。
-- 对检查点与 pending writes 的 `INSERT`/`UPDATE` 加同一个数据库触发器：锁定对应的实例行（`SELECT ... FOR SHARE`），只有 `last_run_id` 等于待写行的 `run_id`、`status = 'running'`，且 `lease_until_ms` 晚于数据库当前时间（毫秒）时才能写入；否则拒绝。行锁要和取消/认领实例的更新互斥，避免检查点检查通过后才提交取消，旧运行仍写入。
-
-模板的 `graph.py` 已通过 `workflow_checkpointer()` 按配置编译图；原有项目启用时也须把 `builder.compile()` 改为 `builder.compile(checkpointer=workflow_checkpointer())`。修改图节点、状态 schema 或路由后，应评估旧检查点兼容性，再更新 `graph_version`。版本不兼容的实例不会自动从头执行。
-
-在已选定项目的 CLI 环境中，可以先省略 `--execute` 查看迁移记录，再对目标环境执行。例如 PowerShell：
-
-```powershell
-$migrationSql = Get-Content -Raw 'db/migrations/001_workflow_durability.sql'
-licos-platform database studio-create-migration --title workflow_durability_v1 --env-scope dev --statement $migrationSql --execute
+```bash
+bash scripts/setup.sh
+bash scripts/http_run.sh -p <%= port %>
 ```
 
-生产环境要明确改用 `--env-scope prod`，不能把开发环境的实例表直接复用到生产环境。
-
-启用后，`POST /run` 和 `POST /stream_run` 必须带稳定的 `X-Workflow-Instance-Id`，每次尝试另带新的 `X-Run-Id`。同一实例 ID 与相同输入重复提交时，已完成的运行返回已保存结果；运行中或失败的实例不会被再次启动。使用下列接口查询、显式恢复或取消：
-
-流式连接断开后，持久化执行会继续在服务端运行；页面会记住该项目最近一次实例 ID，重新打开后可查询状态。普通未启用持久化的流式执行在连接断开时会取消。进程重启后，运行中的实例在租约过期时显示为 `interrupted`，且只有已有检查点的实例可以恢复。
-
-- `GET /workflow/instances/{instance_id}`：读取状态、图版本、最近 `run_id`、输出和错误。
-- `POST /workflow/instances/{instance_id}/resume`：仅对失败或中断实例恢复，沿用已保存的 LangGraph 检查点；请求需带新的 `X-Run-Id`。
-- `POST /workflow/instances/{instance_id}/cancel`：取消实例，禁止自动恢复。
+本地单次执行默认示例：
 
-这三个 ID 含义不同：`workflow_instance_id` 是一项业务流程的稳定 ID；`run_id` 是某次执行尝试的追踪 ID；`runtime_instance_id` 是部署容器 ID。数据库和接口均以已验证的用户、工作区、项目和环境限制访问。
-
-### 按项目启用人工处理与设备回执
-
-只有用户明确要求人工等待或异步回执时，才在该项目已有持久化配置中增加 `"signals": {"enabled": true}`，并由 Agent 在**用户项目内**生成增量迁移。新项目可以在初始迁移中一并加入；普通项目不创建这些字段或表。
-
-- `workflow_instances` 增加可空的 `wait_id`、`wait_type`、`wait_node_id`、`wait_details_data`、`signal_id`、`signal_hash`、`signal_data`、`signal_actor_user_id`（`text`）和 `signal_received_at_ms`（`bigint`）。`status` 增加 `waiting_manual`、`waiting_callback`、`signal_pending`。
-- `workflow_signals` 增加非空 `instance_id`、`signal_id`、`wait_id`、`signal_hash`、`signal_data`、`actor_user_id`（`text`）和 `received_at_ms`（`bigint`）；`(instance_id, signal_id)` 为主键，`instance_id` 外键指向 `workflow_instances.instance_id` 并级联删除。
-- 项目数据库的条件 `UPDATE` 将等待状态、信号 ID、摘要和完整数据在**同一实例行**中原子保存。收件表随后记录去重凭据；若进程在此间退出，恢复扫描从实例行补写收件记录并续跑。不要用平台的多操作 `/transaction` 模拟跨表原子提交。
-- 图中的人工确认或回执节点用 `from licos_agent_runtime.workflow_wait import wait_for_signal`，再调用 `wait_for_signal(type="manual" 或 "callback", wait_id=稳定 ID, node_id=当前节点名, details={...})`。`wait_id` 必须与发往外部设备的关联值一致；循环到下一轮须产生新的 `wait_id`。一个实例同时只支持一个等待点。
-- **下发指令和等待回执必须是两个节点**。LangGraph 恢复时会重新进入调用 `interrupt()` 的节点，所以等待节点在 `wait_for_signal()` 之前不能下发设备指令。指令节点使用外部系统认可的稳定幂等键。
-
-运行到等待点时，`POST /run` 返回 HTTP 202 和 `{ "status": "waiting_callback", "instance_id": "...", "run_id": "...", "wait": { "type": "callback", "wait_id": "...", "node_id": "...", "details": {} } }`；`POST /stream_run` 发送 `workflow_waiting` 作为本次流的终止事件，不发送 `workflow_end`。调用 `GET /workflow/instances/{instance_id}` 可查询当前等待。人工处理和设备回执都向 `POST /workflow/instances/{instance_id}/signals` 发送 `{ "signal_id": "稳定去重 ID", "wait_id": "当前等待 ID", "type": "manual|callback", "data": {} }`，收到 HTTP 202 后轮询实例状态。重复提交同一 ID 和内容仍返回 202；迟到、错误类型或同 ID 不同内容返回 409。`/resume` 仍只用于失败或中断，不提交业务回执。`POST /workflow/instances/{instance_id}/cancel` 可以取消等待中的实例。
-
-已发布项目的 API Token 需先调用平台 `POST /api/v1/studio/api-tokens/exchange`（请求头 `Authorization: Bearer <API Token>`、Body `{ "projectId": "..." }`），将返回的 `data.accessToken` 作为运行时接口的 Bearer 令牌；不能把未兑换的 API Token 直接传给实例接口。设备回执也走这个受鉴权入口。
-
-示例节点和状态传递见 [人工处理与设备回执示例](examples/wait_signal.md)。
-
-### 外部业务写入
-
-MES、ERP、审批等有副作用的节点必须使用稳定幂等键。推荐由 `workflow_instance_id`、固定节点 ID 和业务操作号组成，例如 `工单号:approve_order:审批号`；同一业务操作重试时必须复用同一键。节点应先调用外部系统的幂等写入接口，再把结果写入图状态。**检查点不能覆盖“外部写入成功、检查点尚未保存”之间的故障窗口。**
-
-若外部系统不支持幂等键，节点在重试前应查询业务操作结果；结果不确定时停止运行并由业务规则决定补偿或人工处理，不自动重复写入。只读节点可以按外部接口的超时与重试规则重试；有副作用的节点只在写入接口有明确幂等保证时自动重试。
-
-`/agent/canvas` 返回工作流画布结构，`/agent/canvas_submit` 接收前端编辑后的 `after_canvas` 并生成给 Agent 执行源码修改的 `QueryDiff` 文本。
-
-## 文件输入输出
-
-涉及文件输入/输出时，schema 使用文件对象字段，例如 `url`、`file_type`、`content`、`name`。前端上传文件后会按 schema 把文件对象传给工作流。
-
-节点生成文件时，优先写入项目 `assets/` 目录，并在输出中返回文件对象：
-
-```json
-{
-  "pdf_file": {
-    "url": "/assets/result.pdf",
-    "file_type": "document",
-    "name": "result.pdf"
-  }
-}
+```bash
+bash scripts/local_run.sh '{"topic":"LICOS 工作流"}'
 ```
 
-运行时会自动把输出文件发布到 Studio 对象存储，并补齐签名 `url`、`download_url`、`file_id`、`expires_at` 等字段。节点代码不要手写 workspace-file-service URL、MinIO URL 或签名参数。
-
-## 项目上下文
-
-项目内的 `AGENTS.md` 用于记录可由用户维护的项目上下文，例如业务目标、节点清单、输入输出样例和测试方式。
-
-## 编程项目登录身份
+新模板共用 scripts/runtime.sh 选择解释器，命令参数见 SDK docs/workflow-validation.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 提示词。
+按实际完成情况记录检查、真实运行、恢复和未验收项；HTTP 成功不等于业务结果正确。业务提示词只写节点任务和输出要求。

package/lib/__templates__/workflow/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，按本次需求选择文档。索引区分智能体、编程工作流和公共接口；工作流先读 workflow-authoring.md 与 workflow-runtime.md。只读相关章节，再按真实签名实现。
+
+也可以直接打印索引：
+
+```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/wait_signal.md) 介绍模板示例接入；[DATABASE.md](DATABASE.md) 记录持久化准备；AGENTS.md 记录本项目已实现内容和用户决定。

package/lib/__templates__/workflow/UPGRADING.md

@@ -0,0 +1,10 @@
+# 已有工作流升级
+
+默认保持原版本；需要新能力时再制定升级方案。不要重新初始化覆盖业务图、登录、配置或数据。
+
+1. 记录实际包版本、依赖/锁文件、入口、节点、Schema、外部接口和已启用保存方式。
+2. 按 [SDK.md](SDK.md) 比对版本能力，保留原运行接口和业务输入输出；缺少新接口的旧项目继续原功能，鉴权或服务错误不能当作“不支持”忽略。
+3. 合并必要改动，保持节点 ID、类型、路由和原用户授权。图或状态变化要处理旧检查点与未完成实例，不能只改版本号后重跑外部操作。
+4. 持久化变更按 [DATABASE.md](DATABASE.md) 检查并显式迁移，不自动开启或清空数据库。
+5. 在实际项目解释器和 Preview 中核对参数、画布、真实业务结果及本次新增能力；需要重启恢复时实际验证。
+6. 由平台构建部署后核对安装版本和配置；本地源码更新不等于已部署项目升级。在 AGENTS.md 记录结果和回退安排。

package/lib/__templates__/workflow/examples/wait_signal.md

@@ -1,6 +1,6 @@
 # 人工处理与设备回执节点示例
 
-此示例仅用于用户明确要求持久化等待的项目。先按 README 为**该项目**启用 `durability`、`signals` 和项目数据库迁移。示例中的外部接口应替换为项目真实的 WMS/MES/PLC 接口。
+此示例仅用于用户明确要求持久化等待的项目。先按 [SDK.md](../SDK.md) 的工作流文档，为**该项目**启用 `durability`、`signals` 和项目数据库迁移。示例中的外部接口应替换为项目真实的 WMS/MES/PLC 接口。
 
 ```python
 from uuid import NAMESPACE_URL, uuid5

package/lib/__templates__/workflow/pyproject.toml

@@ -1,15 +1,15 @@
-[project]
-name = "<%= appName %>"
-version = "0.1.0"
-description = "LICOS LangGraph workflow project"
-requires-python = ">=3.12"
-dependencies = [
-    "licos-agent-runtime>=0.6.8",
-    "licos-platform-sdk>=0.7.6",
-    "licos-dev-sdk>=0.6.6",
-]
-
-[tool.uv]
-[[tool.uv.index]]
-url = "https://mirrors.aliyun.com/pypi/simple/"
-default = true
+[project]
+name = "<%= appName %>"
+version = "0.1.0"
+description = "LICOS LangGraph workflow project"
+requires-python = ">=3.12"
+dependencies = [
+    "licos-agent-runtime>=0.6.10",
+    "licos-platform-sdk>=0.7.6",
+    "licos-dev-sdk>=0.6.6",
+]
+
+[tool.uv]
+[[tool.uv.index]]
+url = "https://mirrors.aliyun.com/pypi/simple/"
+default = true

package/lib/__templates__/workflow/requirements.txt

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

package/lib/__templates__/workflow/scripts/http_run.sh

@@ -1,7 +1,7 @@
 #!/bin/bash
 set -eo pipefail
 
-PROJECT_DIR="${LICOS_PROJECT_PATH:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 PORT="${PORT:-<%= port %>}"
 HOST="${HOST:-0.0.0.0}"
 
@@ -21,17 +21,4 @@ while [ "$#" -gt 0 ]; do
   esac
 done
 
-cd "$PROJECT_DIR"
-
-export LICOS_PROJECT_PATH="$PROJECT_DIR"
-export AGENT_PROJECT_TYPE="${AGENT_PROJECT_TYPE:-WORKFLOW}"
-
-PYTHON_BIN="${PYTHON_BIN:-python}"
-if ! command -v "$PYTHON_BIN" >/dev/null 2>&1 && command -v python3 >/dev/null 2>&1; then
-  PYTHON_BIN=python3
-fi
-if [ -x "$PROJECT_DIR/.venv/bin/python" ]; then
-  PYTHON_BIN="$PROJECT_DIR/.venv/bin/python"
-fi
-
-exec "$PYTHON_BIN" -m licos_agent_runtime --mode http --host "$HOST" --port "$PORT"
+exec bash "$SCRIPT_DIR/runtime.sh" --mode http --host "$HOST" --port "$PORT"

package/lib/__templates__/workflow/scripts/local_run.sh

@@ -1,12 +1,7 @@
 #!/bin/bash
 set -eo pipefail
 
-PROJECT_DIR="${LICOS_PROJECT_PATH:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 INPUT="${1:-{\"topic\":\"LICOS 工作流\"}}"
 
-cd "$PROJECT_DIR"
-
-export LICOS_PROJECT_PATH="$PROJECT_DIR"
-export AGENT_PROJECT_TYPE="${AGENT_PROJECT_TYPE:-WORKFLOW}"
-
-python -m licos_agent_runtime --mode flow --input "$INPUT"
+exec bash "$SCRIPT_DIR/runtime.sh" --mode flow --input "$INPUT"

package/lib/__templates__/workflow/scripts/runtime.sh

@@ -0,0 +1,17 @@
+#!/bin/bash
+set -eo pipefail
+
+PROJECT_DIR="${LICOS_PROJECT_PATH:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}"
+cd "$PROJECT_DIR"
+export LICOS_PROJECT_PATH="$PROJECT_DIR"
+export AGENT_PROJECT_TYPE="${AGENT_PROJECT_TYPE:-WORKFLOW}"
+
+if [ -z "${PYTHON_BIN:-}" ]; then
+  if [ -d "$PROJECT_DIR/.venv" ]; then
+    PYTHON_BIN="$PROJECT_DIR/.venv/bin/python"
+  else
+    PYTHON_BIN=python
+  fi
+fi
+
+exec "$PYTHON_BIN" -m licos_agent_runtime "$@"

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

@@ -1,8 +1,8 @@
 const description = `Workflow（工作流项目）：\`licos init \${LICOS_PROJECT_PATH} --template workflow\`
 - 适用：Python + LangGraph 工作流项目
-- 使用 licos-agent-runtime 提供 /run、/stream_run、/cancel、/node_run、/graph_parameter、/agent/canvas、/agent/canvas_submit 接口
-- /agent/canvas 返回工作流画布节点，/agent/canvas_submit 接收前端编辑后的画布并生成 QueryDiff
-- /stream_run 输出 workflow_start、node_start、node_end、workflow_end、error、ping 事件`;
+- README.md 说明结构与接入，AGENTS.md 记录项目实际实现和用户选择
+- 功能、API、配置及限制按 SDK.md 查当前安装版本文档，不复制功能全集
+- DATABASE.md 与 UPGRADING.md 分别说明持久化准备和已有项目升级`;
 
 const config = {
   description,
@@ -39,6 +39,7 @@ const config = {
     console.log('\nConfiguration:');
     console.log('  - Runtime: licos-agent-runtime');
     console.log('  - Framework: LangGraph');
+    console.log('  - SDK documentation for the installed version: SDK.md');
     console.log(`  - Port: ${_context.port}`);
   },
 };

package/package.json

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