npm - @kmlckj/licos-ai-cli - Versions diffs - 1.3.15 → 1.3.17 - Mend

@kmlckj/licos-ai-cli 1.3.15 → 1.3.17

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (22) hide show

package/lib/__templates__/agent/AGENTS.md CHANGED Viewed

@@ -28,11 +28,12 @@
 本文件用于记录用户项目可维护的长期上下文，例如业务目标、已经实现的工具、外部 API 约定、测试样例和后续注意事项。
 - 默认图通过平台模型执行真实工具循环；`src/tools/__init__.py` 的 `TOOLS` 与配置中的工具名称必须一致。
-- 默认使用 `build_project_agent` 并传入运行时的 `ctx`；普通文件工具与技能工具由运行时注册，配置 `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 不会自动下载。
-- 修改业务提示词时保留技能按需读取、附件成功/失败处理、文件会话范围和真实下载链接的指导。文本读取工具不负责解析 PDF、Word、Excel 等二进制文件。
+- 普通链接按任务需要调用内置 `download_file(url, path)`，成功后使用返回的 `file_path`。生成文件先核对，再调用内置 `upload_file(path)`，用成功结果的完整 `url` 返回 Markdown 下载链接；上传失败说明错误，不能只交付本地路径或虚构链接。
+- 修改业务提示词时保留技能按需读取、附件成功/失败处理、文件会话范围、内置上传下载和真实下载链接的指导。文本读取工具不负责解析 PDF、Word、Excel 等二进制文件。
 - 历史由请求的 `messages` 提供，默认不建立跨请求内存会话；40 条消息是按完整轮次裁剪的软上限，不是固定 20 轮。文件跨请求复用需同一用户使用相同 `session_id`。
 - 输入支持 `input`、多轮 `messages`、`event` 及组合，保留附件和多模态内容。
 - `tests/agent_cases.json` 维护可重复的输入及业务工具验收；生成或修改后对已有预览执行 `bash scripts/runtime.sh -m verify`，失败则修复后重验。

package/lib/__templates__/agent/README.md CHANGED Viewed

@@ -1,150 +1,152 @@
-# <%= appName %>
-LICOS 智能体项目模板，基于 Python、LangGraph、LangChain 和 `licos-agent-runtime`。
-## 目录
-```text
-.
-├── .licos                       # CLI 配置文件；平台数据目录另在 /workspace/.licos/
-├── config/
-│   └── agent_llm_config.json
-├── AGENTS.md
-├── pyproject.toml
-├── scripts/
-├── skills/
-│   ├── file-handling/
-│   └── report-writing/
-└── src/
-    ├── main.py
-    ├── agents/
-    │   └── agent.py
-    └── tools/
-```
-## 本地运行
-```bash
-bash scripts/setup.sh
-bash scripts/http_run.sh -p <%= port %>
-```
-## HTTP 接口
-- `GET /health`
-- `POST /run`
-- `POST /stream_run`
-- `GET /agent/config`
-- `POST /v1/chat/completions`
-`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`。调用方传入多轮 `messages`，模板不使用跨请求共享的内存会话。长对话按完整用户轮次裁剪，当前工具调用及返回始终成对保留。
-默认工具包括 `read_file`、`write_file`、`glob_file`、`list_files`、`list_skills`、`read_skill`。文件工具按当前用户和 `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}` 及目录前缀，按文件修改时间倒序返回。
-上传下载及文档生成是按需注册的业务工具。可在构图函数内用 `create_file_transfer_tools(root, ctx=ctx)` 创建上传下载工具，并把两个工具名加入配置；文档生成可封装 `licos-dev-sdk`，文件写入当前会话目录。上传使用 Platform SDK，真实下载链接由 `storage.share_url` 返回。
-`config/event_subscriptions.json` 默认为空数组。配置本体订阅后由业务运行时管理，绑定当前工作空间、项目及源码指纹，接收到的事件直接执行本项目的图。运行 `bash scripts/runtime.sh -m fingerprint` 获取源码版本；具体配置与接口见运行时包的 README。持续监听需要常驻部署，预览实例休眠时不会监听；上游当前不保证稳定事件 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，或者仅传顶层 `attachments` / `files` / `references` 业务字段，不会触发以上自动落地。外部调用方应使用下方 `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"
-    }
-  ]
-}
-```
-## 智能体配置
-`config/agent_llm_config.json` 是平台预览读取智能体配置和工具列表的来源：
-- `config`：模型、温度、超时、thinking 等运行参数；`model: "auto"` 表示使用平台默认模型
-- `sp`：系统提示词
-- `up`：用户提示补充
-- `tools`：业务工具名称列表，新增或删除业务工具时同步维护；运行时默认注册的六个内置工具不列入此数组
-模板 `sp` 已包含技能调用、附件读取及失败处理、会话文件范围、按需文档处理和真实下载链接要求。`build_project_agent` 还会追加运行时能力说明及已发现技能的名称、简介；技能全文通过工具按需读取。修改业务身份或输出要求时保留这些使用约定。
-## 项目上下文
-项目内的 `AGENTS.md` 用于记录可由用户维护的项目上下文，例如业务目标、已实现工具和测试样例。新增工具时通常需要同步：
-- `src/tools/*_tool.py`：工具实现
-- `src/tools/__init__.py`：在 `TOOLS` 中注册工具
-- `config/agent_llm_config.json`：更新 `tools`，必要时更新 `sp` / `up`
-配置文件错误、业务工具名称与注册列表不一致会在构图时直接失败。工具执行异常会保留在运行记录中，并作为错误工具结果交回模型处理。
-## 生成后验收
-在平台预览启动后运行：
-```bash
-bash scripts/runtime.sh -m verify --cases tests/agent_cases.json --report .tmp/agent-verification.json
-```
-命令检查导入、图输入、工具注册，并对每个用例调用 HTTP 与 SSE，核对真实模型调用、工具调用、输入证据和运行用量。业务查询用例需要增加 `required_tools`，例如 `["query_current"]`；`model_contains` 用于检查输入文本或事件字段进入模型。报告保留 run_id，失败返回非零退出码。默认用例只验证通用输入，不能替代业务证据验收。
-预览、本地运行和验收共用 `scripts/runtime.sh`：显式设置 `PYTHON_BIN` 时使用该解释器，否则使用已创建的项目 `.venv`，全局安装模式使用 `python`。选定环境损坏会直接失败。
-验收默认读取 `LICOS_AGENT_RUN_TIMEOUT_SECONDS`，可用 `--request-timeout` 覆盖 HTTP 等待时间；非法超时配置直接失败。图须符合运行时的 `ainvoke/stream/astream/astream_events` 契约，执行错误不会通过换参数重试或改成非流式调用绕过。订阅状态与投递记录分别读取，记录接口为 `/agent/subscriptions/{id}/deliveries?limit=...&offset=...`。
+# <%= appName %>
+LICOS 智能体项目模板，基于 Python、LangGraph、LangChain 和 `licos-agent-runtime`。
+## 目录
+```text
+.
+├── .licos                       # CLI 配置文件；平台数据目录另在 /workspace/.licos/
+├── config/
+│   └── agent_llm_config.json
+├── AGENTS.md
+├── pyproject.toml
+├── scripts/
+├── skills/
+│   ├── file-handling/
+│   └── report-writing/
+└── src/
+    ├── main.py
+    ├── agents/
+    │   └── agent.py
+    └── tools/
+```
+## 本地运行
+```bash
+bash scripts/setup.sh
+bash scripts/http_run.sh -p <%= port %>
+```
+## HTTP 接口
+- `GET /health`
+- `POST /run`
+- `POST /stream_run`
+- `GET /agent/config`
+- `POST /v1/chat/completions`
+`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`。调用方传入多轮 `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` 默认为空数组。配置本体订阅后由业务运行时管理，绑定当前工作空间、项目及源码指纹，接收到的事件直接执行本项目的图。运行 `bash scripts/runtime.sh -m fingerprint` 获取源码版本；具体配置与接口见运行时包的 README。持续监听需要常驻部署，预览实例休眠时不会监听；上游当前不保证稳定事件 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"
+    }
+  ]
+}
+```
+## 智能体配置
+`config/agent_llm_config.json` 是平台预览读取智能体配置和工具列表的来源：
+- `config`：模型、温度、超时、thinking 等运行参数；`model: "auto"` 表示使用平台默认模型
+- `sp`：系统提示词
+- `up`：用户提示补充
+- `tools`：业务工具名称列表，新增或删除业务工具时同步维护；运行时默认注册的六个内置工具不列入此数组
+模板 `sp` 已包含技能调用、附件读取及失败处理、会话文件范围、按需文档处理和真实下载链接要求。`build_project_agent` 还会追加运行时能力说明及已发现技能的名称、简介；技能全文通过工具按需读取。修改业务身份或输出要求时保留这些使用约定。
+## 项目上下文
+项目内的 `AGENTS.md` 用于记录可由用户维护的项目上下文，例如业务目标、已实现工具和测试样例。新增工具时通常需要同步：
+- `src/tools/*_tool.py`：工具实现
+- `src/tools/__init__.py`：在 `TOOLS` 中注册工具
+- `config/agent_llm_config.json`：更新 `tools`，必要时更新 `sp` / `up`
+配置文件错误、业务工具名称与注册列表不一致会在构图时直接失败。工具执行异常会保留在运行记录中，并作为错误工具结果交回模型处理。
+## 生成后验收
+在平台预览启动后运行：
+```bash
+bash scripts/runtime.sh -m verify --cases tests/agent_cases.json --report .tmp/agent-verification.json
+```
+命令检查导入、图输入、工具注册，并对每个用例调用 HTTP 与 SSE，核对真实模型调用、工具调用、输入证据和运行用量。业务查询用例需要增加 `required_tools`，例如 `["query_current"]`；`model_contains` 用于检查输入文本或事件字段进入模型。报告保留 run_id，失败返回非零退出码。默认用例只验证通用输入，不能替代业务证据验收。
+预览、本地运行和验收共用 `scripts/runtime.sh`：显式设置 `PYTHON_BIN` 时使用该解释器，否则使用已创建的项目 `.venv`，全局安装模式使用 `python`。选定环境损坏会直接失败。
+验收默认读取 `LICOS_AGENT_RUN_TIMEOUT_SECONDS`，可用 `--request-timeout` 覆盖 HTTP 等待时间；非法超时配置直接失败。图须符合运行时的 `ainvoke/stream/astream/astream_events` 契约，执行错误不会通过换参数重试或改成非流式调用绕过。订阅状态与投递记录分别读取，记录接口为 `/agent/subscriptions/{id}/deliveries?limit=...&offset=...`。

package/lib/__templates__/agent/config/agent_llm_config.json CHANGED Viewed

@@ -1,13 +1,13 @@
-{
-  "config": {
-    "model": "auto",
-    "temperature": 0.7,
-    "top_p": 0.9,
-    "max_completion_tokens": 10000,
-    "timeout": 600,
-    "thinking": "auto"
-  },
-  "sp": "你是一个 LICOS 智能体，根据用户需求和可用工具完成任务。任务匹配内置技能时，先用 read_skill 读取 SKILL.md，再按需读取技能引用的文件或子目录。普通文件使用 list_files、glob_file、read_file、write_file，路径相对当前用户的当前会话目录，生成结果放在 assets/ 下。上传附件由运行时自动保存；看到 status: saved 后，使用返回的 local file path 读取文本，无需再次下载，预览内容不一定完整。附件保存失败会由运行时直接终止本次请求并返回错误，不使用同名旧文件替代本次附件。用户只粘贴普通 URL 时，仅在项目已注册 download_file 的情况下调用下载工具。read_file 只读 UTF-8 文本；PDF、Word、Excel 等处理及文件上传按项目已注册的业务工具执行。修改文件前先读取，写入后核对；只有工具实际返回下载 URL 时才提供下载链接。工具报错后根据错误修正参数或调整步骤，不编造文件内容、执行结果或业务数据。",
-  "up": "",
-  "tools": []
-}
+{
+  "config": {
+    "model": "auto",
+    "temperature": 0.7,
+    "top_p": 0.9,
+    "max_completion_tokens": 10000,
+    "timeout": 600,
+    "thinking": "auto"
+  },
+  "sp": "你是一个 LICOS 智能体，根据用户需求和可用工具完成任务。任务匹配内置技能时，先用 read_skill 读取 SKILL.md，再按需读取技能引用的文件或子目录。普通文件使用 list_files、glob_file、read_file、write_file，路径相对当前用户的当前会话目录，生成结果放在 assets/ 下。上传附件由运行时自动保存；看到 status: saved 后，使用返回的 local file path 读取文本，无需再次下载，预览内容不一定完整。附件保存失败会由运行时直接终止本次请求并返回错误，不使用同名旧文件替代本次附件。任务需要读取普通文本中的 HTTP(S) 文件链接时，使用内置 download_file(url, path) 下载到当前会话，再按返回的 file_path 读取。read_file 只读 UTF-8 文本；PDF、Word、Excel 等解析和生成按项目已注册的业务工具执行。修改文件前先读取，写入后核对。向用户交付生成文件时，调用内置 upload_file(path)，上传成功后使用工具返回的完整 url 提供 Markdown 下载链接，链接有效期以 expiresAt 为准；本地路径不是下载链接。上传失败则说明具体错误，不声称交付成功、不编造链接。工具报错后根据错误修正参数或调整步骤，不编造文件内容、执行结果或业务数据。",
+  "up": "",
+  "tools": []
+}

package/lib/__templates__/agent/pyproject.toml CHANGED Viewed

@@ -4,8 +4,8 @@ version = "0.1.0"
 description = "LICOS LangGraph agent project"
 requires-python = ">=3.12"
 dependencies = [
-    "licos-agent-runtime>=0.2.42",
-    "licos-dev-sdk>=0.4.6",
+    "licos-agent-runtime>=0.2.44",
+    "licos-dev-sdk>=0.4.7",
 ]
 [tool.uv]

package/lib/__templates__/agent/requirements.txt CHANGED Viewed

@@ -1,2 +1,2 @@
-licos-agent-runtime>=0.2.42
-licos-dev-sdk>=0.4.6
+licos-agent-runtime>=0.2.44
+licos-dev-sdk>=0.4.7

package/lib/__templates__/agent/skills/file-handling/SKILL.md CHANGED Viewed

@@ -1,28 +1,28 @@
----
-name: file-handling
-description: 查找、读取和编写当前会话的文本文件，包括 Markdown、JSON、CSV、日志及附件资料。用户要求整理文件、读取附件或保存结果时使用。
----
-# 会话文件处理
-## 用户附件
-- 用户通过上传按钮提交的附件由运行时在模型执行前保存，支持 HTTP(S) URL 和 base64 data URL，无需再次下载。
-- 查看附件消息中的状态：`status: saved` 时，直接使用返回的本地路径，例如 `read_file(path="assets/upload/spec.md")`。文本预览可能不完整，不能据此声称读取了全文。
-- 附件保存失败时运行时直接拒绝本次请求，返回文件名和错误原因；用户需修正链接或重新上传，同名旧文件不能替代本次附件。
-- 普通文本中的 URL 不会自动变成本地文件；只有项目注册了 `download_file` 才能下载，再按工具返回的路径读取。
-- PDF、Word、Excel 等附件虽已落地，仍需相应格式的业务工具解析。图片使用模型收到的多模态内容，不能用 `read_file` 当作图像识别工具。
-## 文件操作
-1. 使用 `list_files` 查看当前会话中的目录，或使用 `glob_file` 查找文件，例如 `assets/**/*.csv`。使用返回的真实路径。
-2. 使用 `read_file` 读取 UTF-8 文本，`offset` 是从 1 开始的行号，`limit` 是行数。返回截断提示时，用行号继续读取；没有读取的内容不能据此下结论。
-3. 使用 `write_file` 保存 Markdown、JSON、CSV、普通文本等内容，生成文件放在 `assets/` 下。修改现有文件先读取；`mode="overwrite"` 创建或覆盖，`mode="append"` 追加。写入内容不能带读取结果的行号前缀。
-4. 技能及其附属资源共享只读，用 `read_skill` 的 `path` 指定相对该技能目录的文件或子目录。普通文件工具只操作当前用户的当前会话目录。
-5. 写入后读取核对内容，并给出实际文件路径。
-`read_file` 不解析 PDF、Word、Excel、图片等二进制格式。此类处理，以及上传、下载、分享链接等能力，按当前项目实际注册的业务工具执行。
-项目提前准备的技能可以携带 `references/`、`scripts/`、`assets/` 及其他子目录。读取脚本用于理解其内容；执行脚本需要项目提供相应工具。
-输出约定见 [references/output-files.md](references/output-files.md)。
+---
+name: file-handling
+description: 查找、读取和编写当前会话的文本文件，下载 HTTP(S) 文件，将生成文件上传并交付下载链接。用户要求整理文件、读取附件、下载资料或保存交付结果时使用。
+---
+# 会话文件处理
+## 用户附件
+- 用户通过上传按钮提交的附件由运行时在模型执行前保存，支持 HTTP(S) URL 和 base64 data URL，无需再次下载。
+- 查看附件消息中的状态：`status: saved` 时，直接使用返回的本地路径，例如 `read_file(path="assets/upload/spec.md")`。文本预览可能不完整，不能据此声称读取了全文。
+- 附件保存失败时运行时直接拒绝本次请求，返回文件名和错误原因；用户需修正链接或重新上传，同名旧文件不能替代本次附件。
+- 普通文本中的 HTTP(S) 文件 URL 不会自动变成本地文件；按任务需要调用内置 `download_file(url, path)`，例如保存为 `assets/input/spec.md`，成功后用返回的 `file_path` 读取。已有同名文件时先核对，确认替换才传 `overwrite=true`。
+- PDF、Word、Excel 等附件虽已落地，仍需相应格式的业务工具解析。图片使用模型收到的多模态内容，不能用 `read_file` 当作图像识别工具。
+## 文件操作
+1. 使用 `list_files` 查看当前会话中的目录，或使用 `glob_file` 查找文件，例如 `assets/**/*.csv`。使用返回的真实路径。
+2. 使用 `read_file` 读取 UTF-8 文本，`offset` 是从 1 开始的行号，`limit` 是行数。返回截断提示时，用行号继续读取；没有读取的内容不能据此下结论。
+3. 使用 `write_file` 保存 Markdown、JSON、CSV、普通文本等内容，生成文件放在 `assets/` 下。修改现有文件先读取；`mode="overwrite"` 创建或覆盖，`mode="append"` 追加。写入内容不能带读取结果的行号前缀。
+4. 技能及其附属资源共享只读，用 `read_skill` 的 `path` 指定相对该技能目录的文件或子目录。普通文件工具只操作当前用户的当前会话目录。
+5. 写入后读取核对内容；需要向用户交付文件时调用内置 `upload_file(path)`，上传成功后用返回的完整 `url` 给出 Markdown 下载链接。本地路径不能替代下载链接；上传失败说明工具错误，不声称文件已交付。
+`read_file` 不解析 PDF、Word、Excel、图片等二进制格式，此类解析和生成按当前项目实际注册的业务工具执行。上传下载为默认内置工具，二进制文件生成后同样使用 `upload_file` 交付。
+项目提前准备的技能可以携带 `references/`、`scripts/`、`assets/` 及其他子目录。读取脚本用于理解其内容；执行脚本需要项目提供相应工具。
+输出约定见 [references/output-files.md](references/output-files.md)。

package/lib/__templates__/agent/skills/file-handling/references/output-files.md CHANGED Viewed

@@ -2,7 +2,8 @@
 - 业务输入和生成结果放在当前会话目录的 `assets/` 下，例如 `assets/reports/inspection.md`，不会写入项目源码的 `assets/`。
 - 平台运行数据位于项目目录外的 `/workspace/.licos/`，不要向项目里创建 `.licos/` 数据目录。
-- `write_file` 成功只代表本地文件已写入；只有上传或发布工具实际返回 URL，才能向用户提供下载链接。
-- 业务项目需要文件上传下载时，可在构图函数内按需注册 `create_file_transfer_tools(project_root(), ctx=ctx)`；调用的工具名为 `download_file`、`upload_file`。
+- `write_file` 成功只代表本地文件已写入。向用户交付文件时，先核对内容，再调用内置 `upload_file(path="assets/reports/inspection.md")`，上传成功后用返回的完整 `url` 构造 `[下载报告](工具返回的URL)`，保留签名参数，有效期以 `expiresAt` 为准。
+- `download_file`、`upload_file` 默认由运行时注册，不需要项目重复实现或加入业务工具配置。前者将 HTTP(S) 链接保存到当前会话并返回 `file_path`，后者上传当前会话文件并获取真实下载链接。
+- 上传失败时说明工具返回的具体错误；不要虚构成功链接，也不要把本地路径当作可供用户下载的地址。
 - 上传工具通过平台 SDK 获取当前项目和用户身份。工具参数不需要平台密码、令牌或内部服务地址。
 - 办公文件生成可使用项目按需封装的 `licos-dev-sdk` 工具；不要把普通文本改成 `.docx` 或 `.pdf` 后声称生成了对应格式。

package/lib/__templates__/agent/skills/report-writing/SKILL.md CHANGED Viewed

@@ -9,6 +9,6 @@ description: 根据当前会话的资料、技能附属模板、工具返回结
 2. 用 `read_skill(name="report-writing", path="assets/report-template.md")` 读取报告模板。
 3. 区分已确认事实、推测和缺失资料。不要补造检测值、执行结果、人员或时间。
 4. 将内容整理成 Markdown，使用 `write_file` 保存到 `assets/reports/` 下。
-5. 用 `read_file` 检查输出。向用户提供文件路径和关键结论；需要下载链接时，使用项目已注册的上传工具，并引用它实际返回的 URL。
+5. 用 `read_file` 检查输出，再调用内置 `upload_file(path)` 上传报告。成功后向用户提供工具实际返回的完整 URL 组成的 Markdown 下载链接和关键结论；上传失败说明错误，不把本地路径当作下载链接。
 需要 Word、PDF、Excel 等格式时，调用项目提供的相应生成工具，不能只改变 Markdown 文件的扩展名。

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

@@ -3,7 +3,7 @@ const description = `Agent（智能体项目）：\`licos init \${LICOS_PROJECT_
 - 使用 licos-agent-runtime 提供 /run、/stream_run、/cancel、OpenAI compatible 等运行时接口
 - 使用 config/agent_llm_config.json 维护模型、业务提示词和业务工具列表，并通过 /agent/config、/agent/canvas 暴露给预览
 - 默认提供普通文件工具和 skills/<name>/SKILL.md 自动发现，技能资源按需只读加载
-- 上传附件自动保存到当前用户的会话目录，支持 HTTP(S) URL 和 SDK 页的 base64 data URL；按需接入额外下载、上传及文档处理工具
+- 上传附件自动保存到当前用户的会话目录，支持 HTTP(S) URL 和 SDK 页的 base64 data URL；默认内置 download_file、upload_file，生成文件上传后返回真实下载链接，文档处理工具按需接入
 - 项目源码位于 /workspace/projects，平台数据位于 /workspace/.licos`;
 const config = {

package/lib/__templates__/expo/pnpm-lock.yaml CHANGED Viewed

@@ -266,8 +266,8 @@ importers:
   server:
     dependencies:
       '@kmlckj/licos-dev-sdk':
-        specifier: 0.2.19
-        version: 0.2.19
+        specifier: 0.2.20
+        version: 0.2.20
       '@kmlckj/licos-platform-sdk':
         specifier: 0.10.7
         version: 0.10.7
@@ -1324,8 +1324,8 @@ packages:
   '@jridgewell/trace-mapping@0.3.31':
     resolution: {integrity: sha512-zzNR+SdQSDJzc8joaeP8QQoCQr8NuYx2dIIytl1QeBEZHJ9uW6hebsrYgbz8hJwUQao3TWCMtmfV8Nu1twOLAw==}
-  '@kmlckj/licos-dev-sdk@0.2.19':
-    resolution: {integrity: sha512-HXGIe1PseW7wACGUVeqVYFKgH+//5UsbWHuY8JX06b0ybn+FmEkT3oqAni4iTv4uAhB8nbRt4sE3Eysdy0IKmQ==}
+  '@kmlckj/licos-dev-sdk@0.2.20':
+    resolution: {integrity: sha512-3BcIHQXZWdRMIJEkZgghPRu2awF+VsYZ1BQE59CIeBFt30vZrk2hNlTJgiXvPmjONiu04Ip1NEVHP5Uvho3A/g==}
     engines: {node: '>=18'}
   '@kmlckj/licos-platform-sdk@0.10.7':
@@ -7515,7 +7515,7 @@ snapshots:
       '@jridgewell/resolve-uri': 3.1.2
       '@jridgewell/sourcemap-codec': 1.5.5
-  '@kmlckj/licos-dev-sdk@0.2.19': {}
+  '@kmlckj/licos-dev-sdk@0.2.20': {}
   '@kmlckj/licos-platform-sdk@0.10.7':
     dependencies:

package/lib/__templates__/expo/server/package.json CHANGED Viewed

@@ -10,7 +10,7 @@
     "lint": "tsc --noEmit"
   },
   "dependencies": {
-    "@kmlckj/licos-dev-sdk": "0.2.19",
+    "@kmlckj/licos-dev-sdk": "0.2.20",
     "@kmlckj/licos-platform-sdk": "0.10.7",
     "cors": "^2.8.5",
     "dayjs": "^1.11.19",

package/lib/__templates__/nextjs/package.json CHANGED Viewed

@@ -14,7 +14,7 @@
     "ts-check": "tsc -p tsconfig.json"
   },
   "dependencies": {
-    "@kmlckj/licos-dev-sdk": "0.2.19",
+    "@kmlckj/licos-dev-sdk": "0.2.20",
     "@kmlckj/licos-platform-sdk": "0.10.7",
     "@aws-sdk/client-s3": "^3.958.0",
     "@aws-sdk/lib-storage": "^3.958.0",

package/lib/__templates__/nextjs/pnpm-lock.yaml CHANGED Viewed

@@ -18,8 +18,8 @@ importers:
         specifier: ^5.2.2
         version: 5.4.0(react-hook-form@7.77.0(react@19.2.3))
       '@kmlckj/licos-dev-sdk':
-        specifier: 0.2.19
-        version: 0.2.19
+        specifier: 0.2.20
+        version: 0.2.20
       '@kmlckj/licos-platform-sdk':
         specifier: 0.10.7
         version: 0.10.7
@@ -1380,8 +1380,8 @@ packages:
   '@jridgewell/trace-mapping@0.3.31':
     resolution: {integrity: sha512-zzNR+SdQSDJzc8joaeP8QQoCQr8NuYx2dIIytl1QeBEZHJ9uW6hebsrYgbz8hJwUQao3TWCMtmfV8Nu1twOLAw==}
-  '@kmlckj/licos-dev-sdk@0.2.19':
-    resolution: {integrity: sha512-HXGIe1PseW7wACGUVeqVYFKgH+//5UsbWHuY8JX06b0ybn+FmEkT3oqAni4iTv4uAhB8nbRt4sE3Eysdy0IKmQ==}
+  '@kmlckj/licos-dev-sdk@0.2.20':
+    resolution: {integrity: sha512-3BcIHQXZWdRMIJEkZgghPRu2awF+VsYZ1BQE59CIeBFt30vZrk2hNlTJgiXvPmjONiu04Ip1NEVHP5Uvho3A/g==}
     engines: {node: '>=18'}
   '@kmlckj/licos-platform-sdk@0.10.7':
@@ -6716,7 +6716,7 @@ snapshots:
       '@jridgewell/resolve-uri': 3.1.2
       '@jridgewell/sourcemap-codec': 1.5.5
-  '@kmlckj/licos-dev-sdk@0.2.19': {}
+  '@kmlckj/licos-dev-sdk@0.2.20': {}
   '@kmlckj/licos-platform-sdk@0.10.7':
     dependencies:

package/lib/__templates__/nuxt-vue/package.json CHANGED Viewed

@@ -17,7 +17,7 @@
     "start": "bash ./scripts/start.sh"
   },
   "dependencies": {
-    "@kmlckj/licos-dev-sdk": "0.2.19",
+    "@kmlckj/licos-dev-sdk": "0.2.20",
     "@kmlckj/licos-platform-sdk": "0.10.7",
     "@nuxt/image": "2.0.0",
     "nuxt": "4.3.1",

package/lib/__templates__/nuxt-vue/pnpm-lock.yaml CHANGED Viewed

@@ -13,8 +13,8 @@ importers:
   .:
     dependencies:
       '@kmlckj/licos-dev-sdk':
-        specifier: 0.2.19
-        version: 0.2.19
+        specifier: 0.2.20
+        version: 0.2.20
       '@kmlckj/licos-platform-sdk':
         specifier: 0.10.7
         version: 0.10.7
@@ -731,8 +731,8 @@ packages:
   '@jridgewell/trace-mapping@0.3.31':
     resolution: {integrity: sha512-zzNR+SdQSDJzc8joaeP8QQoCQr8NuYx2dIIytl1QeBEZHJ9uW6hebsrYgbz8hJwUQao3TWCMtmfV8Nu1twOLAw==}
-  '@kmlckj/licos-dev-sdk@0.2.19':
-    resolution: {integrity: sha512-HXGIe1PseW7wACGUVeqVYFKgH+//5UsbWHuY8JX06b0ybn+FmEkT3oqAni4iTv4uAhB8nbRt4sE3Eysdy0IKmQ==}
+  '@kmlckj/licos-dev-sdk@0.2.20':
+    resolution: {integrity: sha512-3BcIHQXZWdRMIJEkZgghPRu2awF+VsYZ1BQE59CIeBFt30vZrk2hNlTJgiXvPmjONiu04Ip1NEVHP5Uvho3A/g==}
     engines: {node: '>=18'}
   '@kmlckj/licos-platform-sdk@0.10.7':
@@ -4773,7 +4773,7 @@ snapshots:
       '@jridgewell/resolve-uri': 3.1.2
       '@jridgewell/sourcemap-codec': 1.5.5
-  '@kmlckj/licos-dev-sdk@0.2.19': {}
+  '@kmlckj/licos-dev-sdk@0.2.20': {}
   '@kmlckj/licos-platform-sdk@0.10.7':
     dependencies:

package/lib/__templates__/taro/pnpm-lock.yaml CHANGED Viewed

@@ -181,8 +181,8 @@ importers:
   server:
     dependencies:
       '@kmlckj/licos-dev-sdk':
-        specifier: 0.2.19
-        version: 0.2.19
+        specifier: 0.2.20
+        version: 0.2.20
       '@kmlckj/licos-platform-sdk':
         specifier: 0.10.7
         version: 0.10.7
@@ -2590,8 +2590,8 @@ packages:
   '@keyv/serialize@1.1.1':
     resolution: {integrity: sha512-dXn3FZhPv0US+7dtJsIi2R+c7qWYiReoEh5zUntWCf4oSpMNib8FDhSoed6m3QyZdx5hK7iLFkYk3rNxwt8vTA==}
-  '@kmlckj/licos-dev-sdk@0.2.19':
-    resolution: {integrity: sha512-HXGIe1PseW7wACGUVeqVYFKgH+//5UsbWHuY8JX06b0ybn+FmEkT3oqAni4iTv4uAhB8nbRt4sE3Eysdy0IKmQ==}
+  '@kmlckj/licos-dev-sdk@0.2.20':
+    resolution: {integrity: sha512-3BcIHQXZWdRMIJEkZgghPRu2awF+VsYZ1BQE59CIeBFt30vZrk2hNlTJgiXvPmjONiu04Ip1NEVHP5Uvho3A/g==}
     engines: {node: '>=18'}
   '@kmlckj/licos-platform-sdk@0.10.7':
@@ -12408,7 +12408,7 @@ snapshots:
   '@keyv/serialize@1.1.1': {}
-  '@kmlckj/licos-dev-sdk@0.2.19': {}
+  '@kmlckj/licos-dev-sdk@0.2.20': {}
   '@kmlckj/licos-platform-sdk@0.10.7':
     dependencies:

package/lib/__templates__/taro/server/package.json CHANGED Viewed

@@ -11,7 +11,7 @@
     "start:prod": "node dist/main"
   },
   "dependencies": {
-    "@kmlckj/licos-dev-sdk": "0.2.19",
+    "@kmlckj/licos-dev-sdk": "0.2.20",
     "@kmlckj/licos-platform-sdk": "0.10.7",
     "@nestjs/common": "^10.4.15",
     "@nestjs/core": "^10.4.15",

package/lib/__templates__/vite/package.json CHANGED Viewed

@@ -14,7 +14,7 @@
     "ts-check": "tsc -p tsconfig.json"
   },
   "dependencies": {
-    "@kmlckj/licos-dev-sdk": "0.2.19",
+    "@kmlckj/licos-dev-sdk": "0.2.20",
     "@kmlckj/licos-platform-sdk": "0.10.7",
     "dotenv": "^17.2.3",
     "express": "^4.21.2"

package/lib/__templates__/vite/pnpm-lock.yaml CHANGED Viewed

@@ -13,8 +13,8 @@ importers:
   .:
     dependencies:
       '@kmlckj/licos-dev-sdk':
-        specifier: 0.2.19
-        version: 0.2.19
+        specifier: 0.2.20
+        version: 0.2.20
       '@kmlckj/licos-platform-sdk':
         specifier: 0.10.7
         version: 0.10.7
@@ -291,8 +291,8 @@ packages:
   '@jridgewell/trace-mapping@0.3.31':
     resolution: {integrity: sha512-zzNR+SdQSDJzc8joaeP8QQoCQr8NuYx2dIIytl1QeBEZHJ9uW6hebsrYgbz8hJwUQao3TWCMtmfV8Nu1twOLAw==}
-  '@kmlckj/licos-dev-sdk@0.2.19':
-    resolution: {integrity: sha512-HXGIe1PseW7wACGUVeqVYFKgH+//5UsbWHuY8JX06b0ybn+FmEkT3oqAni4iTv4uAhB8nbRt4sE3Eysdy0IKmQ==}
+  '@kmlckj/licos-dev-sdk@0.2.20':
+    resolution: {integrity: sha512-3BcIHQXZWdRMIJEkZgghPRu2awF+VsYZ1BQE59CIeBFt30vZrk2hNlTJgiXvPmjONiu04Ip1NEVHP5Uvho3A/g==}
     engines: {node: '>=18'}
   '@kmlckj/licos-platform-sdk@0.10.7':
@@ -1751,7 +1751,7 @@ snapshots:
       '@jridgewell/resolve-uri': 3.1.2
       '@jridgewell/sourcemap-codec': 1.5.5
-  '@kmlckj/licos-dev-sdk@0.2.19': {}
+  '@kmlckj/licos-dev-sdk@0.2.20': {}
   '@kmlckj/licos-platform-sdk@0.10.7':
     dependencies:

package/lib/__templates__/workflow/pyproject.toml CHANGED Viewed

@@ -4,8 +4,8 @@ version = "0.1.0"
 description = "LICOS LangGraph workflow project"
 requires-python = ">=3.12"
 dependencies = [
-    "licos-agent-runtime>=0.2.42",
-    "licos-dev-sdk>=0.4.6",
+    "licos-agent-runtime>=0.2.44",
+    "licos-dev-sdk>=0.4.7",
 ]
 [tool.uv]

package/lib/__templates__/workflow/requirements.txt CHANGED Viewed

@@ -1,2 +1,2 @@
-licos-agent-runtime>=0.2.42
-licos-dev-sdk>=0.4.6
+licos-agent-runtime>=0.2.44
+licos-dev-sdk>=0.4.7

package/package.json CHANGED Viewed

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