diff --git a/app/server/tools/executor.js b/app/server/tools/executor.js index 9f53320..da1905d 100644 --- a/app/server/tools/executor.js +++ b/app/server/tools/executor.js @@ -1039,6 +1039,27 @@ function toolDb(ctx, args) { // 依据 docs/tool-design.md §一;技能不是「无持久状态」的动作,run 不必单独成工具。 // input_args 仅 op=run 用且可缺省:runSkill 把 null 视作 {},真正缺哪些字段由 // 各技能 input_schema 校验点名报错(工具层再 gate 一层是双重门槛,无益)。 +// visit_url(front matter 可选):页面产物类技能声明访问路径模板,run 成功后在本层拼 +// public_link.base_url(与 mint_public_link 同源)追加完整「访问地址」——技能进程跑在 +// executor 隔离视图里不知道公网前缀,AI 拿到相对路径就会原样转给用户,而相对路径打不开。 +async function runSkillWithVisit(ctx, name, inputArgs) { + const out = await skills.runSkill(ctx, name, inputArgs); + let fm; + try { + fm = skills.parseFrontMatter(await skills.getSkillInfo(ctx, name)); + } catch (_) { + return out; // 描述文件异常不该废掉一次成功的 run + } + const tpl = fm && fm.visit_url ? String(fm.visit_url).trim() : ''; + if (!tpl) return out; + const rel = tpl.replace(/\{task_id\}/g, ctx.sessionId || path.basename(path.resolve(ctx.taskDir || ''))); + const pl = (ctx.cfg && ctx.cfg.public_link) || {}; + const base = String(pl.base_url || '').trim().replace(/\/+$/, ''); + return out + '\n访问地址:' + (base + ? base + rel + : rel + '(站内路径:public_link.base_url 未配置,拼不出公网前缀)'); +} + async function toolSkill(ctx, args) { const op = String(args.op || '').trim().toLowerCase(); const name = String(args.name || '').trim(); @@ -1051,7 +1072,7 @@ async function toolSkill(ctx, args) { } case 'run': { if (!name) throw new Error('op=run 缺少必填参数 name'); - return skills.runSkill(ctx, name, args.input_args); + return runSkillWithVisit(ctx, name, args.input_args); } default: throw new Error('未知的 op:"' + op + '"。可用:list / get(需 name)/ run(需 name,input_args 可选)'); diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index ed84ccc..691ceaa 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -291,7 +291,7 @@ stateDiagram-v2 | `terminal` | **唯一一个走 executor 的内置工具**(当 `rexec.isRemote(cfg)`);本地分支用 `spawn` + `detached` + 进程组 kill;远端分支 `rexec.run` SSE 收流,结果套上超时/截断/取消注解后 `truncate(text, cfg.terminal.max_output_chars)` 返回 | | `fetch` | `AbortController` 覆盖全生命周期(响应头之后的 body 读流同样被超时/取消打断,取消用与 terminal 同款的 200ms 轮询);content-type 先行,非文本只回状态/类型/尺寸不读 body;流式读到 `cfg.fetch.max_bytes`(默认 1MB)即断开并标注截断;按响应 charset 解码(full-icu 支持 gbk/gb18030 等,未知编码退回 UTF-8);HTML 用 `htmlToMarkdown` 转;HTML 实体单遍解码(常见命名实体+数字实体通吃,修 `&` 双重解码);网络错误解包 `err.cause` 直述 ENOTFOUND/TLS 等真因;engine 不截工具结果,返回值末尾另有 `truncate` 1MB 字符护栏 | | `mint_public_link` | **唯一的 mint 入口**:与 core 同进程,直接 `publicFiles.mint()`,不绕任何 HTTP;`ctx.taskDir` 就是会话目录,`relOf` 的结果正是取用侧要的 `rel`。校验:`public_link.base_url` 已配 + `resolveInTask` 沙箱 + 确认是文件 + `realpath` 未沿符号链接跳出任务目录;返回单行 URL | -| `skill` | op 分派 list/get/run(三件套合并:同一 `name` 标识空间 + 同一生命周期,见 `docs/tool-design.md` §一);委托 `tools/skills.js`;`input_args` 仅 op=run 且可缺省 `{}`,缺参由各技能 `input_schema` 校验点名报错 | +| `skill` | op 分派 list/get/run(三件套合并:同一 `name` 标识空间 + 同一生命周期,见 `docs/tool-design.md` §一);委托 `tools/skills.js`;`input_args` 仅 op=run 且可缺省 `{}`,缺参由各技能 `input_schema` 校验点名报错;front matter 带 `visit_url` 的技能在 op=run 成功后由 executor 层拼 `public_link.base_url`(与 mint 同源)追加完整「访问地址」行(技能进程不知公网前缀,AI 拿相对路径会原样转给用户) | | `schedule` | **当前会话**(`ctx.sessionId`,AI 不可指定他会话)定时任务的完整生命周期:op 分派 get/create/update/delete(表主键 session_id → 每会话至多一条,无 id 参数);条件必填在代码里校验、错误回显 op 与缺失字段;数据层在 `scheduler.js`(cron 可解析 → 间隔 ≥1h → prompt ≤20000 → 查重/存在性检查),delete 不落 scheduler_note;描述里限定「仅用户明确要求时调用」(安全缓解,见 §5.12) | | `lab` | 元工具统一入口:`tool` + 自由 `args` 转发内置 + MCP 全部能力(目标 schema 定义期不可知,条件校验归内层 handler);`help` 伪工具做现场发现(无参列名单、带 `args.tool` 出完整 schema),未知名回显全清单,禁嵌套、内层错误冒泡不包装。默认被全局 `tools_deny: ['lab']` 屏蔽,仅 `lab` profile(allow `[lab]` + deny `[]` 清空)下发,见 §5.8 | @@ -299,7 +299,7 @@ stateDiagram-v2 ### 5.5 `tools/skills.js` —— Skill Manager -- 技能 = 单层子目录,含 `SKILL.md`(YAML front matter 可选,含 `description` / `input_schema`)+ `run.py` 或 `run.sh` 入口(接收 JSON 字符串作为唯一 argv)。 +- 技能 = 单层子目录,含 `SKILL.md`(YAML front matter 可选,含 `description` / `input_schema` / `visit_url`,后者的完整链接由 executor 层在 op=run 后拼接,见 §5.4)+ `run.py` 或 `run.sh` 入口(接收 JSON 字符串作为唯一 argv)。 - 依赖不由 core 安装(core 只发现与执行):系统层依赖(apt 等,`install.sh` 的副作用)在镜像 `skills` 阶段烘入 M'(需重建镜像);pip 依赖与技能资产(如字体提取)在服务启动前由 `agent-executor-init` 一次性落到宿主 `./skills`。 - init 的 pip 步骤先离线探测(`pip install --no-index --dry-run <逐行>`,不联网):镜像已带的包直接跳过,只把缺的装进 `deps/`;`.deps_installed` marker(requirements/install.sh 两份 hash)也在那里维护。 - 外挂层可见性:`skills/deps` 由 compose 放进 executor 容器 env 的 `PYTHONPATH`(`server.js` 白名单同步放行),技能入口与 AI 终端命令都能 import;运行期 skills 与 deps 均 `:ro`,**加包只需改 `requirements.txt` 后 `docker compose up -d`(重跑 init),不需重建镜像**。 diff --git a/skills/README.md b/skills/README.md index 4d2015f..3e586fd 100644 --- a/skills/README.md +++ b/skills/README.md @@ -52,6 +52,7 @@ input_schema: # 必填参数列表 output_schema: # 输出描述 +visit_url: /app/{task_id}/ # 可选:页面类技能的访问路径模板 --- ``` @@ -59,6 +60,7 @@ output_schema: - `description`:一句话描述技能功能,用于 `skill` op=list 展示。 - `input_schema`:输入参数的 JSON Schema 定义,用于参数校验和文档生成。 - `output_schema`:输出结果的描述(可选)。 +- `visit_url`:(可选)页面类技能声明的访问路径模板,`{task_id}` 占位执行时替换为会话 id。`op=run` 成功后由 core(tools/executor.js)拼上 `public_link.base_url`,在输出末尾追加一行「访问地址:<完整 URL>」——技能进程跑在 executor 隔离视图里不知道公网地址,完整链接只能 core 补;AI 拿到相对路径会原样转给用户,而相对路径打不开。 - 若未提供 Front Matter,系统会尝试从正文第一行提取描述。 ### 3.2 正文内容 diff --git a/skills/data-page/SKILL.md b/skills/data-page/SKILL.md index c0576ed..66ed5f7 100644 --- a/skills/data-page/SKILL.md +++ b/skills/data-page/SKILL.md @@ -1,12 +1,7 @@ --- name: data-page description: 数据页面脚手架:把 table/dashboard/kanban 模板复制到任务目录 app/templates/,配合 db 工具产出 /app/{task_id}/ 可访问、经 /api/db/{task_id}/query 读写 data.db 的查看/管理页 -input_schema: - type: object - properties: - dest: - type: string - description: 模板输出目录(相对会话任务目录,自动预转绝对路径;缺省 app/templates,已存在的文件跳过不覆盖) +visit_url: /app/{task_id}/ --- # data-page @@ -29,14 +24,14 @@ input_schema: - 数据库:任务目录下的 `data.db` - 页面目录:任务目录下的 `app/` - 页面入口:`app/index.html` -- 访问地址:`/app/{task_id}/` +- 访问地址:`/app/{task_id}/`(完整 URL = 站点地址 + 该路径;run 输出末尾的「访问地址」已拼好,直接转发) - 数据 API:`/api/db/{task_id}/query` `{task_id}` 是任务目录的名称。页面通过 URL 动态解析,不要硬编码。 ## 初始化 -生成页面前,调用 `skill(name="data-page", op="run", input_args={"dest": "app/templates"})` 复制模板到任务目录的 `app/templates/`。已存在则跳过,不会覆盖修改过的文件(重跑幂等)。 +生成页面前,调用 `skill(name="data-page", op="run")`(无需参数,模板固定复制到 `app/templates/`)。已存在则跳过,不会覆盖修改过的文件(重跑幂等)。 ## 数据 API @@ -78,9 +73,9 @@ const taskId = location.pathname.split('/').filter(Boolean)[1]; 1. **明确数据结构**:与用户确认字段。如果描述模糊,可以建议合理的结构。 2. **创建表并录入数据**:用 `db` 工具完成。 -3. **初始化模板**:调用 `skill(name="data-page", op="run", input_args={"dest": "app/templates"})`。 +3. **初始化模板**:调用 `skill(name="data-page", op="run")`(无参数)。 4. **生成页面**:从 `app/templates/` 选合适的模板,根据表结构调整字段和 SQL,写入 `app/index.html`。 -5. **告知用户**:访问地址为 `/app/{task_id}/`,简要说明页面功能。 +5. **告知用户**:把 run 输出末尾「访问地址」那行的**完整 URL**(含域名)发给用户——只给 `/app/...` 相对路径用户打不开;再简要说明页面功能。 页面必须包含: @@ -218,4 +213,4 @@ const taskId = location.pathname.split('/').filter(Boolean)[1]; - [ ] 页面动态解析 task_id - [ ] 包含错误处理和加载状态 - [ ] 用户输入渲染时已转义 -- [ ] 已告知用户访问地址 `/app/{task_id}/` +- [ ] 已告知用户完整访问 URL(run 输出「访问地址」那行,含域名,非相对路径) diff --git a/skills/data-page/run.py b/skills/data-page/run.py index 043b2d1..5380cc1 100644 --- a/skills/data-page/run.py +++ b/skills/data-page/run.py @@ -1,6 +1,11 @@ #!/usr/bin/env python3 # data-page 技能入口:把技能自带 templates/*.html 复制到会话任务目录的 app/templates/。 +# 目标目录固定(SKILL.md 环境约定:页面必须在 app/ 下才能被 /app/{task_id}/ 访问)。 +# 不开 dest 参数:manager 对已是绝对路径的参数不做沙箱校验,开放 dest = 开放任意目录写入; +# 且路径写死在文档流程里,可配置只会造成漂移。 # 已存在的同名文件跳过不覆盖(AI 改过的模板要能经受重跑);纯 stdlib,无 requirements。 +# cwd 契约:远端模式(生产)cwd 即会话任务目录;本地模式 cwd 是技能目录—— +# 那会把模板抄进技能家,检测到直接报错拒跑(手动调试请 cd 到任务目录再运行)。 import json import os import shutil @@ -9,13 +14,18 @@ from pathlib import Path def main(): - try: - args = json.loads(sys.argv[1]) if len(sys.argv) >= 2 and sys.argv[1].strip() else {} - if not isinstance(args, dict): - raise ValueError('input_args 必须是 JSON 对象') - except (ValueError, json.JSONDecodeError) as e: - print('参数解析失败:' + str(e), file=sys.stderr) - return 1 + if len(sys.argv) >= 2 and sys.argv[1].strip(): + try: + args = json.loads(sys.argv[1]) + if not isinstance(args, dict): + raise ValueError('input_args 必须是 JSON 对象') + if args: + print('本技能无参数(模板固定复制到任务目录 app/templates/),收到:' + + json.dumps(args, ensure_ascii=False), file=sys.stderr) + return 1 + except (ValueError, json.JSONDecodeError) as e: + print('参数解析失败:' + str(e), file=sys.stderr) + return 1 skill_dir = Path(__file__).resolve().parent src = skill_dir / 'templates' @@ -27,13 +37,10 @@ def main(): print('templates/ 下没有 .html 模板', file=sys.stderr) return 1 - # dest 建议显式传入(key 含 "dest",skill manager 会按会话目录预转绝对路径)。 - # 缺省退回 cwd:远端模式 cwd 即会话目录;若退到技能目录内则明确报错,避免污染技能。 - dest = Path(args.get('dest') or os.path.join(os.getcwd(), 'app', 'templates')) - if not dest.is_absolute(): - dest = dest.resolve() + dest = (Path.cwd() / 'app' / 'templates').resolve() if str(dest) == str(skill_dir) or str(dest).startswith(str(skill_dir) + os.sep): - print('dest 必须落在会话任务目录(请传 input_args {"dest": "app/templates"})', file=sys.stderr) + print('当前工作目录不是会话任务目录(本地直跑 cwd=技能目录会污染技能;' + '生产经 executor 运行天然正确,手动调试请 cd 到任务目录再跑)', file=sys.stderr) return 1 dest.mkdir(parents=True, exist_ok=True)