@kmlckj/licos-ai-cli 1.3.13 → 1.3.16

package/lib/__templates__/agent/AGENTS.md

@@ -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

@@ -64,21 +64,23 @@ Body 可以同时带 `attachments`、`files`、`references` 等业务字段；
 
 默认图通过平台模型与已注册工具循环执行，使用 `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 令牌确认身份，普通文件不能跨会话访问。
+默认工具包括 `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}` 及目录前缀，按文件修改时间倒序返回。
 
-上传下载及文档生成是按需注册的业务工具。可在构图函数内用 `create_file_transfer_tools(root, ctx=ctx)` 创建上传下载工具，并把两个工具名加入配置；文档生成可封装 `licos-dev-sdk`，文件写入当前会话目录。上传使用 Platform SDK，真实下载链接由 `storage.share_url` 返回。
+内置 `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")`；文本预览不保证完整，需要时按行读取原文件。`status: failed` 时消息会带错误原因，不应使用同名旧文件。图片继续以多模态内容传入，能否识别取决于所选模型；PDF、Word、Excel 等解析需要项目按需注册格式处理工具。
+模型消息会带附件的保存状态和本地相对路径。`status: saved` 时可直接调用 `read_file(path="assets/upload/spec.md")`；文本预览不保证完整，需要时按行读取原文件。附件保存失败时，运行时在调用模型前终止本次请求，返回文件名和具体错误；不会让模型使用同名旧文件替代。图片继续以多模态内容传入，能否识别取决于所选模型；PDF、Word、Excel 等解析需要项目按需注册格式处理工具。
 
-仅在普通聊天文本中粘贴 URL，或者仅传顶层 `attachments` / `files` / `references` 业务字段，不会触发以上自动落地。外部调用方应使用下方 `upload_file` 协议；普通链接需要按需注册 `download_file`。重复访问同一会话文件时，传相同 `session_id` 和平台用户 Bearer 令牌。
+仅在普通聊天文本中粘贴 URL 不会触发以上自动落地。外部调用方应使用下方 `upload_file` 协议；普通链接由模型按任务需要调用内置 `download_file`。重复访问同一会话文件时，传相同 `session_id` 和平台用户 Bearer 令牌。
 
 ```json
 {

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

@@ -7,7 +7,7 @@
     "timeout": 600,
     "thinking": "auto"
   },
-  "sp": "你是一个 LICOS 智能体，根据用户需求和可用工具完成任务。任务匹配内置技能时，先用 read_skill 读取 SKILL.md，再按需读取技能引用的文件或子目录。普通文件使用 list_files、glob_file、read_file、write_file，路径相对当前用户的当前会话目录，生成结果放在 assets/ 下。上传附件由运行时自动保存；看到 status: saved 后，使用返回的 local file path 读取文本，无需再次下载，预览内容不一定完整。附件 status: failed 时说明具体错误，不读取同名旧文件或声称已解析。用户只粘贴普通 URL 时，仅在项目已注册 download_file 的情况下调用下载工具。read_file 只读 UTF-8 文本；PDF、Word、Excel 等处理及文件上传按项目已注册的业务工具执行。修改文件前先读取，写入后核对；只有工具实际返回下载 URL 时才提供下载链接。工具报错后根据错误修正参数或调整步骤，不编造文件内容、执行结果或业务数据。",
+  "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

@@ -4,7 +4,7 @@ version = "0.1.0"
 description = "LICOS LangGraph agent project"
 requires-python = ">=3.12"
 dependencies = [
-    "licos-agent-runtime>=0.2.40",
+    "licos-agent-runtime>=0.2.43",
     "licos-dev-sdk>=0.4.6",
 ]
 

package/lib/__templates__/agent/requirements.txt

@@ -1,2 +1,2 @@
-licos-agent-runtime>=0.2.40
+licos-agent-runtime>=0.2.43
 licos-dev-sdk>=0.4.6

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

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

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

@@ -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

@@ -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

@@ -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__/workflow/pyproject.toml

@@ -4,7 +4,7 @@ version = "0.1.0"
 description = "LICOS LangGraph workflow project"
 requires-python = ">=3.12"
 dependencies = [
-    "licos-agent-runtime>=0.2.40",
+    "licos-agent-runtime>=0.2.43",
     "licos-dev-sdk>=0.4.6",
 ]
 

package/lib/__templates__/workflow/requirements.txt

@@ -1,2 +1,2 @@
-licos-agent-runtime>=0.2.40
+licos-agent-runtime>=0.2.43
 licos-dev-sdk>=0.4.6

package/package.json

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