@kmlckj/licos-ai-cli 1.7.0 → 1.7.3

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

@@ -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.7",
-    "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.7
-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/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,11 +1,8 @@
-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/ 提供按需示例
-- 使用 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 = {
@@ -44,7 +41,10 @@ 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__/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/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.7",
-    "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.7
-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.0",
+  "version": "1.7.3",
   "description": "LICOS AI coding workspace CLI - project template engine and dev tools",
   "license": "MIT",
   "author": "kmlckj",