skill工具op=run支持visit_url契约:front matter声明访问路径模板({task_id}占位),run成功后executor层拼public_link.base_url(与mint同源)在输出末尾追加完整「访问地址」行——技能进程在executor隔离视图里不知公网前缀,AI拿相对路径会原样转用户导致打不开;data-page落实:去dest参数(路径本就是文档固定的app/templates,且manager对绝对路径参数不设防,开放=开放任意写),run.py固定cwd相对+本地模式落技能目录即拒跑,SKILL.md流程与检查清单改为转发run输出的完整URL;README/ARCHITECTURE同步front matter字段

This commit is contained in:
2026-09-23 23:29:20 +08:00
parent 1addf0d95d
commit 5ede5cfd4e
5 changed files with 52 additions and 27 deletions
+22 -1
View File
@@ -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 可选)');
+2 -2
View File
@@ -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),不需重建镜像**。
+2
View File
@@ -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 正文内容
+6 -11
View File
@@ -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 输出「访问地址」那行,含域名,非相对路径)
+20 -13
View File
@@ -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)