@xgent-ai/skills 0.7.4 → 0.7.6

package/skills/use-rustify-docs/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: use-rustify-docs
+description: "用于以 Rustify Docs 创建、改造文档站或 Landing Page；落地页必跑 ui-loop 打磨首屏吸引力与转化路径。不用于 Rustify 框架开发或已指定其他建站技术的任务。"
+---
+
+# Use Rustify Docs
+
+用 Rustify Docs 交付可阅读、可部署的静态站点。文档站让读者找到答案并完成操作；Landing Page 让目标客户第一眼理解价值、愿意继续了解并采取行动。
+
+## 实现与设计边界
+
+- 面向站点作者，在用户的目标项目工作；不要求克隆或修改 Rustify UI 仓库。默认采用静态 HTML/CSS 的 DOM 路径，纯内容站不编译站点 Rust、不加载 wasm，也不需要 Node、Tailwind CLI 或 Makepad。只有具体的交互组件或 demo 需求才选 components 模板与 DOM islands；不预建 GPU 路径。
+- 保留用户的产品事实、品牌、已有设计和技术选择。普通创建、局部修改不扩成框架开发、整站迁移、后端、统计服务或发布。仅咨询时只读。
+- **实际调用 impeccable 做设计**：从当前技能目录找到并读取其 `SKILL.md`，按其流程执行；文档面选择 Read，营销落地页选择 Persuade。Rustify 自身的 Theme Studio 外观不约束客户站点。
+- **Landing Page 必须实际调用 ui-loop**：读取当前可用的 `ui-loop/SKILL.md` 并执行其流程，不能用本文件的检查表代替调用。impeccable 负责设计方向与实现；落地页按用户要求接续 ui-loop，不以通用自检轮数上限跳过所需迭代。
+- 找不到上述依赖时先说明缺少哪个 skill、影响哪个阶段及如何补齐；继续可独立完成的内容与构建，不擅自安装、不声称已调用，缺少 ui-loop 时不能宣布 Landing Page 设计验收完成。
+
+## 确定站点与入口
+
+1. 读目标项目的 AGENTS、README、PRODUCT、DESIGN、工具链配置及相关计划，核对工作树和现有站点。确定工作目录、文档站 / Landing Page / 两者组合、受众、语言、品牌素材、部署 base，以及本次主要行动的真实目标。
+2. 文档站确认读者要完成的任务与现有内容；Landing Page 确认卖给谁、解决什么问题、有什么可用证据、希望客户下一步做什么。可从材料查明的先查；会改变价值主张或 CTA 的缺项才询问，先推进不依赖答案的工作。不得虚构客户、评价、数据或产品能力。
+3. 创建或配置前读 [Rustify Docs 作者契约](references/rustify-docs.md)，核对实际 CLI 的 `--version`、`--build-info` 和 `--help`。复用现有版本和项目入口；安装、组件配对、主题、落地页配置按该参考执行，不猜不存在的参数或配置键。
+4. 现有站点只改对应源文件、配置与资源；新站用 `rustify-docs new` 创建到新目录或空目录。先说明内容 / components 选择及依据，再落地最小完整路径。
+
+## 文档站
+
+- 按读者任务组织入门、操作指南、参考和必要解释；导航服务于这些任务，不照搬源码目录。首页需要引导时用 `layout: home`，正文用默认文档布局。
+- 先打通一条真实阅读路径：入口 → 快速上手 → 可执行示例 → 深入参考。代码、API、命令和输出须从实际资料核对，避免占位指南和失效链接。
+- 配好标题、description、侧栏分组、标题层级、图片替代文本与站内链接。既有仓库混放计划、评审和私密资料时，用 `content.include` 明确选择发布源；不把导航隐藏当作不发布。
+- 在实际页面检查阅读宽度、代码与表格滚动、移动导航、键盘与焦点。对本次涉及的搜索、复制代码、主题或多语言覆盖主路径及空 / 错状态；不为目录对称补未要求的语言或组件。
+
+## Landing Page：先吸引，再让行动成立
+
+使用 Markdown 的 `layout: landing`；它保留品牌与 hero，移除文档导航、搜索、侧栏和目录。没有 `--template landing`。只有要加载第三方脚本、表单、iframe 或透传参数时，才声明命名 profile 并用 `landing:` 选择。
+
+先依据受众建立有辨识度的视觉方向与内容顺序：首屏价值主张和主 CTA、能解释产品的真实视觉、支持承诺的证据、必要异议解答及后续行动。按产品选择区块，不机械堆砌特性卡片，也不以夸张文案弥补价值不清。
+
+**首个可运行版本完成后，实际进入 ui-loop，并把以下目标随页面上下文一起交给它。** 使用运行页面的真实桌面和移动首屏截图；首屏通过后仍检查整页与行动路径。
+
+| 检查 | 可观察的通过条件 |
+| --- | --- |
+| 第一眼的价值 | 按约 5 秒的首次扫读自检，能说出面向谁、提供什么价值、下一步是什么；不用读完整页才明白。 |
+| 视觉吸引力 | 主标题、产品视觉与 CTA 形成清楚焦点；排版、留白、色彩与构图体现品牌和产品特征。说明吸引目标客户的具体理由。 |
+| 可信度 | 视觉展示实际产品或明确的概念表达；证明材料可追溯，没有伪造 logo、客户评价或收益数字。 |
+| 行动路径 | 一个明确的主转化目标；CTA 文案说明行动及收益，点击可到达真实目的地。表单及成功 / 失败反馈符合本次实际接入。 |
+| 移动与无障碍 | 移动首屏仍有价值与主要行动；无横向溢出，正文与控件可读可用，键盘焦点可见，减弱动态偏好得到尊重。 |
+
+同时完整执行 ui-loop 的 typography、whitespace、visual_hierarchy、color、motion、micro_interaction、responsive、originality 检查。实际查看其要求的获奖参考，记录来源与可借鉴之处；不凭搜索摘要或代码认定视觉效果，不复制参考品牌和承诺。
+
+发现差距就改源文件、更新运行产物并复验，直到 ui-loop 各维度和上述目标都无可见改进。动效服从内容与可用性，不为检查项强加动画。缺页面、参考或交互证据时保留缺项；不能把受阻、预算耗尽或自评分数当作达标。5 秒检查是设计自检，实际客户吸引力和转化率需另有真实用户或投放证据。
+
+落地页的 `index`、`search`、`ai` 默认均为 false；根据推广目标明确处理，SEO 获客需要时显式开启 `index: true`，不能因为叫 Landing Page 就一律禁止收录。表单、统计与托管策略见作者契约；没有真实接收端不能声称已收集线索或完成转化集成。
+
+## 验证与交付
+
+- 按目标项目现有入口执行受影响检查；通常运行 `rustify-docs check --deny-warnings`、`rustify-docs build`，再用 `rustify-docs preview` 验收生产输出。`dev` 用于编辑预览，不能代替最终构建。
+- 浏览器确认展示的是最新产物，记录入口、视口、主路径、必要截图、console 与失败请求。覆盖本次涉及的导航 / CTA、资源、移动布局、404、主题及语言；子路径部署核对 URL、base、资源和深链。
+- Landing Page 另验 profile 的按页 CSP、表单 / iframe 和所用参数透传；未配置这些能力则不强行新增。有广告脚本时确认其失败不会阻断主要内容与原生表单。真实提交、发送通知或生产发布须在已有授权内进行。
+- build、lint 或单测不替代浏览器验收。未能打开页面时明确写「未在浏览器中验证」，说明原因及解除条件，不宣布 UI 或 ui-loop 通过。
+- 交付源文件和构建输出位置、启动命令、实际检查结果与未验证项；Landing Page 附首屏截图、ui-loop 的参考与差距处置结论。没有真实转化数据时只报告设计和功能验收，不承诺转化提升。

package/skills/use-rustify-docs/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Use Rustify Docs"
+  short_description: "用 Rustify Docs 创建文档站与 Landing Page，并通过 ui-loop 打磨首屏吸引力"
+  default_prompt: "使用 $use-rustify-docs 创建文档站或 Landing Page；落地页执行 ui-loop，重点打磨首屏价值表达、视觉吸引力和主要 CTA。"

package/skills/use-rustify-docs/references/rustify-docs.md

@@ -0,0 +1,138 @@
+# Rustify Docs 作者契约
+
+创建或配置站点前读取本文件。此处是可跨项目携带的最小作者契约，不依赖本机 Rustify 源码目录。
+
+核对依据：Rustify UI 源码 `032756c041615dca075a49685fbb458ce7cc833f` 的 [作者指南](https://github.com/rockie/rustify-ui/blob/032756c041615dca075a49685fbb458ce7cc833f/docs/docs-ssg.md)、[CLI README](https://github.com/rockie/rustify-ui/blob/032756c041615dca075a49685fbb458ce7cc833f/crates/rustify-docs-cli/README.md) 与 CLI 参数定义。基线版本为 0.2.1，不表示永远是最新版；目标项目版本不同时先读其匹配文档和实际帮助，不混用契约。
+
+## CLI 与项目
+
+先探测已安装的 CLI 和 Rust，不因 PATH 缺入口就覆盖安装。新项目没有版本约束且需要安装时，已核对的 registry 命令是：
+
+```sh
+cargo install rustify-docs-cli --version 0.2.1 --locked
+rustify-docs --version
+rustify-docs --build-info
+rustify-docs --help
+```
+
+registry 安装使用标准 release profile，不加 `--profile docs-cli`。此基线使用稳定 Rust 1.99，build-info 应有 `panic: unwind` 和 `distribution: registry`。不要为创建站点擅自升级已有项目工具链、CLI 或依赖。
+
+纯内容站：
+
+```sh
+rustify-docs new my-docs
+cd my-docs
+rustify-docs check --deny-warnings
+rustify-docs dev
+```
+
+`new` 只接受新目录或空目录，默认 content 模板。需要真实 Rust DOM 组件 / 交互 demo 时，使用 `rustify-docs new my-components --template components`；需要稳定 Rust 和 `wasm32-unknown-unknown` target。保留生成的 Cargo.toml、带 checksum 的 Cargo.lock 以及 host SSR / browser hydrate 结构；不得混合 SSR 与 CSR/hydrate 特性。
+
+组件项目严格配对 CLI build-info 中的 rustify-docs、rustify-dom、rustify-components 精确版本和来源。遇到 `rust-framework-pair` 修复整套配对，不用 path、file/link 或随意换 Git revision 绕过。首次组件 check/build 可能获取锁定依赖；纯内容站在 CLI 安装后不需要站点编译、Node、外部 Tailwind CLI 或 GPU 工具链。
+
+编辑完成后停止本任务的 dev，再验生产输出：
+
+```sh
+rustify-docs check --deny-warnings
+rustify-docs build
+rustify-docs preview
+```
+
+使用打印出的实际 URL，勿硬编码端口。`preview` 只服务既有输出，不会重建。`dev`、`check`、`build`、`preview` 可用 `--config` 指定配置；配置内路径相对配置目录，命令行 `--out` / `--dir` 相对工作目录。静态产物通过 HTTP 访问，不用 file URL。
+
+## 配置、资源与外观
+
+生成的 `rustify-docs.toml` 是起点。必要字段与常用路径如下，按实际目录和部署目标修改，不复制示例品牌：
+
+```toml
+schema_version = 1
+
+[site]
+name = "Product Docs"
+lang = "zh"
+base = "/"
+
+[content]
+dir = "content"
+
+[assets]
+dir = "static"
+
+[build]
+out = "dist"
+
+[[nav.groups]]
+label = "入门"
+dir = "guide"
+```
+
+- `content/index.md` 对应 `/`，`content/guide/start.md` 对应 `/guide/start/`。普通页写 title、description 和有序标题；只保留一个 H1，hero 与正文不能重复制造 H1。
+- `site.url` 可选；已知发布地址时设置，其路径必须等于 `site.base`。子路径构建 / 预览必须使用同一 base。不要在未知域名时把示例域名当作 canonical 发布。
+- `content.include` 是相对 content.dir 的精确 `.md` 列表，不支持 glob；缺省递归发现，空数组是选择零页。它控制发布源；`nav.groups` 控制导航，不能代替源选择。
+- 本地图片、下载和 HTML 资源链接进入资源图并按内容发布；`static/` 按整体目录发布，不放密钥或不应公开的资料。普通页面不可直接加载远程图片，先取得可用的本地素材。
+- 外观使用主题与内容中的 utility classes；CLI 在进程内从实际页面 class 编译样式。核对实际输出，不添加不存在的 custom CSS 配置键，不为静态样式引入运行时 utility Worker。
+- `theme.primary` 可分别设 light / dark；完整主题从生成的 `theme.example.json` 复制并用 `[theme] document = "theme.json"` 激活。document 与 primary 不能同时设置。
+- 默认系统字体。自有字体以 `[[theme.fonts]]` 声明本地 family / src / weight / style，同时在主题两种模式的 font token 中选择该 family，保留许可；不引用远程字体 URL。
+- Markdown 原生支持标题、表格、代码组、alerts 和源码 include。内置 Tabs、CardGrid、Steps 不需要作者 Rust 项目；仅使用静态内置组件不是选择 components 模板的理由。
+
+更复杂的 i18n、demo 注册、布局 slot 或主题格式，按需读匹配版本作者指南的相应小节。不要从其他框架类推配置。
+
+## Landing Page 的最小有效形态
+
+在已有 content 项目添加页面或替换对应首页，不运行不存在的 landing 模板：
+
+```markdown
+---
+title: 将产品价值写成客户能理解的结果
+description: 清楚说明目标客户、问题与产品价值。
+layout: landing
+tagline: 用具体事实支持主张，减少客户理解和行动的成本。
+actions:
+  - text: 查看解决方案
+    link: "#solution"
+---
+
+## 解决方案 {#solution}
+
+在这里展示经过核对的产品能力与证据。
+```
+
+这是语法示例，交付时替换为目标产品内容。landing 共用 home hero 的 title、tagline、actions、features；正文接在 hero 后。品牌头部没有文档导航、搜索、语言或主题开关，主题跟随系统或站点已有选择；有 profile footer 或 footer slot 才显示相应页脚。默认 `index` / `search` / `ai` 全为 false，三者独立按目标显式设置。
+
+没有 profile 时仍是严格 CSP。只有需要第三方请求或表单时才加入配置；例如以下只是已存在表单服务的接线形状，域名必须换成实际获准的接收端：
+
+```toml
+[landing.profiles.campaign]
+carry = ["utm_source", "utm_campaign"]
+
+[landing.profiles.campaign.sources]
+form = ["https://leads.example.com"]
+```
+
+页面 frontmatter 添加 `landing: campaign`，正文可放：
+
+```html
+<form id="lead" method="post" action="https://leads.example.com/lead">
+  <label for="email">工作邮箱</label>
+  <input id="email" name="email" type="email" autocomplete="email" required>
+  <input type="hidden" name="utm_source" data-rd-carry>
+  <button type="submit">预约演示</button>
+</form>
+```
+
+- 命名 profile 必须存在且只供 `layout: landing` 使用。`sources` 分 script、connect、img、frame、form；来源填写 origin，不是带路径的 URL。真实厂商域名清单按厂商当前文档核实，勿照猜。
+- profile 的 `scripts` 列表只接受外部 src 或项目内 `.js` 文件；本地脚本宜放 `landing/` 等 static 之外的目录。load 是 async 或 defer，默认 defer；外部脚本 origin 自动加入 script-src。
+- 不允许内联 script/style、style 属性、事件处理属性、eval 或通过 nonce/hash 绕过；Landing Page 不放宽 style-src。把厂商内联初始化放进已声明的本地脚本，不去修改生成器策略。
+- iframe 的来源需在 sources.frame，提供 title、禁止 srcdoc；iframe 服务本身也须允许被嵌入。需内联样式的第三方嵌入不能借此绕过约束。
+- form 的 action / 按钮 formaction 必须匹配获准来源或可解析的站内页面。没有 sources.form 不允许提交；生成器不提供接收、存储或邮件后端。站内静态感谢页本身不是线索接收端。
+- 原生 POST 接收端接受表单编码，保存后用 303 跳向感谢页。GET 会用字段替换 action 的 query，需要固定参数时用 hidden input。实际提交测试须避免未授权的真实客户数据或通知。
+- `carry` 只透传明确列出的参数：hidden input 以 name 匹配，链接 / iframe 用 `data-rd-carry`；hero actions 自动标记。它不使用 cookie/localStorage；无脚本时页面和原生表单仍可用，只缺参数透传。
+- 统计、同意管理与隐私说明按站点已有要求及实际接入处理，不因创建落地页自动新增追踪器。缺厂商 ID、表单服务或授权时完成独立页面并保留接入缺项。
+
+## 托管与验收
+
+输出目录含 `rustify-docs-manifest.json`、HTML、指纹 CSS/JS、引用资源与 404，直接交给静态主机。主机需按目录 index.html 回应，并将不存在的路由以真实 HTTP 404 返回；正确发送 CSS/JS/wasm 等 MIME。部署和回滚替换整份产物，不混用各次 build 的 HTML 与资源。
+
+每页都有 meta CSP。若主机还发送 CSP 响应头，Landing Page 必须按 manifest 的 `page_policies` 使用该页策略，或不在这些页发送 CSP 头；全站强加严格头会继续拦截脚本和表单。GitHub Pages 这类无法设置头的主机使用 meta，无需模拟按页响应头。
+
+生产 preview 里核对资源、深链、404 与实际需要的表单、脚本、iframe、透传。本地替身只证明接线契约，不能记为第三方真实集成或转化统计通过。上线另按目标项目已有授权与流程执行。

package/skills/use-task-gateway/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: use-task-gateway
+description: '用于其他 App 接入 XGENT Task Gateway 完成异步任务，或排查鉴权、提交、幂等、进度与结果回收；需要时对齐 VM 执行器和 workflow 动作面。不用于网关自身开发发布或通用异步架构咨询。'
+when_to_use: "用户会说「接异步任务网关」「任务重复提交了」「进度和结果查不到」时。"
+---
+
+# use-task-gateway
+
+让调用方 App 形成可恢复的闭环：业务执行记录 → 提交任务 → 保存 task_id → 查询进度 → 消费终态结果。普通 App 默认走 Portal HTTP 租户面；任务由已注册服务的节点反向领取，网关不直接执行 payload 中的命令。
+
+## 先确定接入边界
+
+从调用方仓库查找 manifest、门户鉴权/换票封装、后端配置、业务 run/job/step 模型，以及目标服务的 payload 契约。复用其语言和已有 HTTP 客户端，不要求调用方使用 Rust，也不要求克隆网关源码。
+
+先确认四项：实际 Gateway 基址、用户态或后台服务态、真实服务名、执行器所需输入。缺部署信息时先完成可配置的客户端与业务接线；仅在真实联调依赖该信息时索取，不能猜测生产地址、凭据或服务名。
+
+| 当前工作 | 按需读取 |
+| --- | --- |
+| 用户代表调用、后台 SA、manifest 与换票排错 | [references/authentication.md](references/authentication.md) |
+| HTTP 提交、持久化、幂等、状态、取消、回调、重试 | [references/task-api.md](references/task-api.md) |
+| 新接 VM/CLI/API 执行能力、SSH 部署能力确认、任务一直 pending 或领取后失败 | [references/workers.md](references/workers.md) |
+| 明确接入 workflow 引擎动作目录、placement/lease 或运行中止 | [references/workflow-actions.md](references/workflow-actions.md)；先核验引擎专用身份 |
+
+实施普通 App 接入时读取前两份；已有执行服务时不用改节点部署。
+
+## 接入面与凭据
+
+| 调用方 | 接口及凭据 |
+| --- | --- |
+| 普通 Portal App 后端 | `https://<portal-host>/svc/task-gateway` + TDT；提交用 `task_gateway.submit`，发现/查询用 `task_gateway.read` |
+| workflow 引擎专用动作调用 | 同 HTTP 基址下 `/workflow/v1/*`；仅 `kind=service`、`azp=workflow`、`task_gateway.workflow_actions` 同时满足 |
+| 已明确采用原生 gRPC 的平台客户端 | 独立 gRPC 地址 + 网关 API Key（可叠加 mTLS），只可提交公开的平台服务；不得用来绕开租户 HTTP 授权 |
+| VM 上的 `xgent-agent` | 独立 gRPC NodeService + Node Token；该 token 不用于 App 提交 |
+
+`API_BASE_URL` 若指向内部 `portal-api`，只用于门户 API，不能直接拼 `/svc/task-gateway`。容器内直连 Gateway HTTP 地址仅采用部署配置已明确的地址。`:8081` 是内部支撑面，不是任务 API。旧 HTTP API-Key、admin-ui 和任务 SSE 路由已退场。
+
+原生 gRPC 是独立协议：请求 payload 为 JSON 编码字符串，状态为 protobuf 枚举，任务不进入 Portal 租户可见集，且没有 HTTP 提交幂等契约。若用户明确选用它，依据目标部署的 `proto/src/gateway.proto` 和凭据约束接入，不套用本文 HTTP 重试策略。
+
+## 调用方实施要点
+
+1. **先有业务记录，再有网络提交。** 校验本 App 的租户、用户和业务对象权限；保存 run/step/attempt、目标服务、不可变提交体和幂等键。HTTP 成功取到 task_id 后立即关联保存。业务接口可返回“已受理”和本 App 的 run ID，后台继续查询。
+2. **选择正确身份。** 用户发起的代表调用走用户换票；无用户上下文的后台任务走已授权 SA。长任务恢复需明确后续如何获得合法令牌；不能静默将用户授权失败改为高权限服务态执行。
+3. **处理两层成败。** HTTP 非 2xx 或信封 `ok !== true` 均为 API 调用失败。`ok:true` 的提交响应仅表示受理；只有任务 `state=completed` 才表示执行成功。
+4. **可恢复等待。** 后台按 task_id 轮询，进程重启后继续。使用有上限的退避、抖动和观察期限；等待超时返回“仍可查询”，保留任务关联。`partial_result` 是累积文本，每次替换；`result` 可为任意 JSON 值、字符串或 null。终态入库及后续业务动作按 run/attempt 幂等，避免并发观察者或重复通知多次消费结果。
+5. **区分重传和重做。** 提交结果不确定时，在相同租户和来源归因下重用原 key 与原请求。预算耗尽后保留可恢复记录，不无界重试；不要换 key 规避冲突。明确决定重做已失败的业务执行才建立新 attempt；网关去重不保证执行副作用恰好一次。
+6. **保留业务权限。** Gateway 详情和取消目前只按租户校验；同租户其他用户/来源 App 的任务不会自动被隔离。任何 task_id 都先经本 App 的业务记录授权，再向网关查询或取消；不以“能读到任务”判定访问权。
+
+普通任务请求采用 `snake_case`；workflow 动作面采用另一套 `camelCase` 契约。不要把 `taskId/submissionKey/placement/abortIfRunning` 填进普通 `/v1/tasks` 并期待生效。普通面只能取消 pending，停止等待也不代表远端执行已停止。
+
+## 验证与交付
+
+按改动范围验证可观察结果：成功与执行失败；HTTP 200 + `ok:false`；提交已受理但客户端丢失响应后的同 key 恢复；进程重启恢复查询；JSON/文本结果；累积输出不重复；等待超时及 pending 取消/运行中取消拒绝。验证本 App 拦截同租户越权访问，而不只验证网关跨租户隔离。
+
+可用本地 HTTP fixture 覆盖调用方契约；真实闭环应确认任务被目标执行器领取且结果被 App 消费。没有凭据或节点时，明确记录未验证部分，不用 mock 结果声称真实联调成功。仅在任务授权范围内发起测试任务；缺服务/容器时请求已有环境协助，不擅自安装或启动基础设施。
+
+交付调用方代码/配置与实际验证结果，指出仍需的平台授权、服务/节点或凭据配置。仅咨询时解释需要的接线，不强制创建文档、部署机器或修改网关。
+
+## 契约维护依据
+
+本包任务接入契约以 `xgent-ai-task-gateway` 提交 `5e90da9` 为基线（2026-10-16 核对）；SSH 接入说明已核对 `aeca179`（1.9.3，2026-10-17）。可整目录移到其他 App 使用。引用的源码路径是维护线索，不是运行依赖。若能访问更新源码，优先核对 `gateway/src/portal/{gate,tasks,routes,onboarding}.rs`、`gateway/src/portal/workflow_actions/`、`gateway/src/agent/config.rs` 和 `proto/src/gateway.proto`；其次参考 `docs/API.md`、`docs/portal-app-contract.md`、`docs/PORTAL-APP-INTEGRATION.md`。部署可能落后于源码，需通过目标环境验证能力。

package/skills/use-task-gateway/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "Use Task Gateway"
+  short_description: "帮助其他 App 接入 Task Gateway，可靠提交异步任务并恢复查询、回收结果"

package/skills/use-task-gateway/references/authentication.md

@@ -0,0 +1,75 @@
+# Portal 鉴权与调用身份
+
+普通 App 任务调用需要 `task_gateway.read` 与 `task_gateway.submit`。建服务、签节点凭据等管理操作另需 `task_gateway.admin` + 用户 `role=admin`，不应作为日常提交权限。App Secret、SA Secret、Node Token 和网关 API Key 是不同凭据。
+
+## 代表用户调用
+
+在调用方自己的 manifest 合并，保留原有项：
+
+```json
+{
+  "exchangeTargets": ["task-gateway"],
+  "scopes": ["task_gateway.read", "task_gateway.submit"]
+}
+```
+
+前端把当前 App 的用户 TDT 交给自己的后端。后端先验证本 App 身份及业务权限，再换取目标 TDT。不能把 `aud=<调用方 App>` 的用户票直接交给 Gateway。
+
+后端请求（以下为协议示意，变量均从调用方配置/请求上下文取得）：
+
+```http
+POST <PORTAL_BASE_URL>/oauth/token
+Content-Type: application/x-www-form-urlencoded
+
+grant_type=urn:ietf:params:oauth:grant-type:token-exchange
+&subject_token=<当前 App 用户 TDT，逐字段 URL 编码>
+&audience=task-gateway
+&client_id=<调用方 App key>
+&client_secret=<调用方 App Secret>
+&scope=task_gateway.read%20task_gateway.submit
+```
+
+使用 HTTP 库的 form encoder，不手工拼接含 token 的 query。`scope` 可省略以取获准交集，提供时只能收窄。门户根据来源 App 的用户授权、目标声明和请求上界决定结果；以实际获授 scope 为准，不能靠多请求 scope 提权。
+
+除了提交 manifest，门户还须有生效的交换布线：来源允许 `token_exchange`、目标允许交换且白名单含来源、来源到目标授权关系存在、用户同意此交换。新用户可由首次进入 App 的共授覆盖；接入晚于原 consent 的存量用户可能缺同意。缺同意时引导至门户的 `/exchange-consent?source=<app>&target=task-gateway&return=<编码的返回地址>`，不要代填用户同意记录。
+
+读取 `access_token`、`expires_in` 和 `scope`；若目标门户使用 `{ok,data}` 信封，先检查并解包。App Secret 只放后端。
+
+换票缓存至少区分租户、来源 App、目标 App、用户、本次请求 scope/授权上下文；按有效期提前失效，不能按目标 App 单独缓存造成用户串票。已有门户 SDK/代理能正确换票时复用，不另建平行密钥流。
+
+## 后台服务态调用
+
+无当前用户的队列恢复、调度等使用门户 SA `client_credentials`。给用户 manifest 增加 `scopes` 不会给来源 SA 自动增加权限；平台代建的调用方 SA 需实际授予 `task_gateway.read/submit`（通过其服务权限声明/平台配置），并限定租户范围。
+
+单租户也可由租户管理员在 `/admin/service-accounts` 为已安装 Task Gateway 创建专用调用凭据，选择这两个 scope。此凭据绑定的 `azp` 可能是 `task-gateway`，不要假设必为调用方 App；持久化任务恢复需要维持原来源归因，不能随意更换凭据类别。
+
+```http
+POST <API_BASE_URL>/api/tokens/service
+Authorization: Basic <调用方 SA client_id:client_secret 的 Basic 编码>
+Content-Type: application/json
+
+{
+  "grant_type": "client_credentials",
+  "tenant_id": "<从本 App 已授权业务记录确定的租户>",
+  "scope": "task_gateway.read task_gateway.submit"
+}
+```
+
+响应先检查 HTTP 与信封，当前门户服务签票常为 `data.access_token`，兼容 `data.token` 时依实际签发契约处理；检查有效期与实际权限。不要使用 Gateway 自身用于 introspection 的 SA 密钥作为调用方凭据。
+
+**用户票和服务票的 audience 不同：** 当前 `gateway/src/portal/gate.rs::identity_from_claims` 仅要求用户票 `(listingKey ?? aud)=task-gateway`。服务态票的 `aud/listingKey` 可以是来源 SA clientId，例如 `reports-server`，来源 App 由 `azp` 归因；不要因其 audience 不是 `task-gateway` 就拒绝合法后台调用。两类都须是有效票、具有非空真实 `tenant_id` 和相应 scopes；服务票无 `user_id`，不因此拥有 admin role。
+
+长任务持久化业务状态，令牌按有效期刷新/重取，不持久化首次用户 token 当长期凭据。以服务身份继续用户发起的任务，需要本 App 已明确的后台执行授权；无该授权时要求用户重新授权并保留可恢复状态。
+
+## 鉴权排错
+
+| 现象 | 核查 |
+| --- | --- |
+| 401 `INVALID_TOKEN` | 用户票 audience 错误、过期/吊销、无有效租户；不要把服务票的来源 audience 当成故障 |
+| 403 `INSUFFICIENT_SCOPE` | 用户授权交集或 SA 实际权限缺 read/submit；检查当前签发/自省结果 |
+| `EXCHANGE_NOT_ALLOWED` / `GRANT_NOT_ALLOWED` | 交换授权、目标白名单、来源 grant 是否生效 |
+| `EXCHANGE_CONSENT_REQUIRED` | 引导该用户补跨 App 同意，不降级成空列表或高权限 SA |
+| `SECRET_INVALID` | 来源 App Secret 与门户保存值是否漂移；不是 SA Secret |
+| 503 `INTROSPECT_FAILED` | Gateway 到 Portal 的自省连接或 Gateway 自身 SA；交网关运维处理 |
+
+用户 token 401 可在合法刷新/重新授权后有限重试。403、交换配置或 consent 失败不应无界刷新。不能用 payload/metadata/自报头覆盖租户、user_id 或 origin_app。

package/skills/use-task-gateway/references/task-api.md

@@ -0,0 +1,121 @@
+# 普通 App 的异步任务 HTTP 契约
+
+所有路径相对于 `TASK_GATEWAY_BASE_URL`，通常为 `https://<portal-host>/svc/task-gateway`。带 `Authorization: Bearer <合法 TDT>`。业务响应为 `{ok:true,data}` 或 `{ok:false,error:{code,message,details?}}`，业务失败常用 HTTP 200；认证/授权、限流和依赖故障还可能为 401/403/429/503。代理可能返回非 JSON 错误页，客户端应保留 HTTP 状态并报告协议/传输错误，不能把解析失败当任务失败。
+
+## 发现和提交
+
+| 方法 | 路径 | Scope | 数据 |
+| --- | --- | --- | --- |
+| GET | `/v1/services` | `task_gateway.read` | `data.items`：`name,display_name,description,active_nodes,runtime_scope,owned,provisioned` |
+| POST | `/v1/tasks` | `task_gateway.submit` | 需 `Idempotency-Key`；返回 `data.task_id` |
+| GET | `/v1/tasks/{task_id}` | `task_gateway.read` | 详情，含 payload、状态和结果 |
+| GET | `/v1/tasks?service=...&state=...&limit=...&cursor=...` | `task_gateway.read` | `data.items/next_cursor`；列表没有 payload |
+| POST | `/v1/tasks/{task_id}/cancel` | `task_gateway.submit` | 无请求体；仅 pending 可取消 |
+
+服务目录包含本租户自有服务和公开的平台服务。使用真实 `name`，不把展示名当物理名。`runtime_scope` 表示 `tenant_managed/platform_managed`；提交还要求 `provisioned=true`。`active_nodes>0` 只证明节点在线，仍需验证执行能力。
+
+以下示例假定目标 agent 的 `service_key.path=service`；服务名、业务 ID 与 payload 字段需换成目标服务的实际契约：
+
+```json
+{
+  "service_name": "report-worker-a1b2c3-d4e5",
+  "payload": {
+    "service": "report-worker-a1b2c3-d4e5",
+    "operation": "build-report",
+    "report_id": "report-001"
+  },
+  "metadata": {"run_id": "run-001", "attempt": "1"},
+  "streaming": false
+}
+```
+
+```bash
+# 业务后端预先保存 request.json 和 IDEMPOTENCY_KEY；不要每次重传重新生成。
+curl --silent --show-error "$TASK_GATEWAY_BASE_URL/v1/tasks" \
+  -H "Authorization: Bearer $TG_TDT" \
+  -H 'Content-Type: application/json' \
+  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
+  --data-binary @request.json
+```
+
+curl 示例仅展示传输；实现中还须检查 HTTP 状态及响应 `ok`，成功时读取 `data.task_id`，不要从顶层读 task_id。
+
+- `payload` 在网关层可为任意 JSON；执行器 dispatch 从配置的 dot-path 读取服务名。常用 `payload.service == service_name == agent services[].name`；嵌套路径则按执行配置传。没有该字段仍可能受理，随后报 `service_key_missing/mismatch`。
+- `metadata` 必须是 string → string；对象/数字先按业务约定序列化。`_` 开头的键保留给网关，调用方提供时会被剥离。普通 metadata 不构成可信身份。
+- `streaming` 默认 false；true 还需要流式 executor 配置，不会自动改造 CLI。
+- `callback_url` 可选，缺省可能继承租户默认回调。payload 会在详情回显，凭据应留在后端/执行器环境，勿随任务传。
+
+## 持久化与幂等
+
+在第一次发请求前持久化：本 App 的租户/用户/业务对象、run/step/attempt、身份归因策略、目标服务、完整请求体和幂等键。保存不可变请求快照，避免重试时加入新时间戳等字段。接收 task_id 后立即关联；响应丢失或保存 task_id 前崩溃时，用原记录恢复提交。
+
+`Idempotency-Key` 是 1–128 个可打印 ASCII 字符。命名例 `reports:<唯一runId>:<stepId>:attempt:1`；不要把秘密放进 key。去重范围为 **(tenant_id, origin_app, key)**，不含 user_id 或 service_name。相同租户和来源下的不同用户/服务必须避免碰撞。
+
+| 情况 | 处理 |
+| --- | --- |
+| 网络超时/断线，提交是否落地未知 | 原身份归因、原 key、原请求体重传，取得原 task_id |
+| 同 key 改了 service/payload/metadata/streaming/callback_url | `IDEMPOTENCY_CONFLICT`；检查业务记录，不改 key 掩盖问题 |
+| 已确认失败，产品策略决定重新执行 | 创建新 attempt 和新 key；旧 key 只会回放旧任务 |
+| TDT 到期 | 合法刷新/重取，维持原 tenant 和 origin；换成不同 azp 的 SA 可能变成新去重空间 |
+
+提交重传及轮询沿用 App 的有限重试预算，网络/429/503 可退避并加抖动（有 `Retry-After` 时尊重）；预算耗尽保留恢复入口。参数、权限、同意或幂等冲突先处理原因，不自动换身份或重做任务。幂等只保证提交去重，节点重投、超时与外部系统副作用仍需业务幂等或补偿。
+
+任务与幂等记录有保留期，不是永久去重账本。当前 `gateway/src/audit.rs` 按约 30 天清理 tasks 分区，再清理对应幂等记录；过期后同 key 可能创建新任务。本 App 应及时保存终态结果；恢复很久以前的未知执行或遇到 NOT_FOUND 时，先核对业务账本和目标部署保留策略，不直接重提有副作用的工作。
+
+## 状态与结果
+
+普通 HTTP 面的状态是小写六态：
+
+| 状态 | 调用方行为 |
+| --- | --- |
+| `pending` | 已排队，继续观察；无节点可长期停留 |
+| `assigned` / `running` | 节点已领取/执行，继续观察 |
+| `streaming` | 继续观察，可展示 `partial_result` |
+| `completed` | 成功终态，保存/消费 result |
+| `failed` | 失败终态，保存 error_message；取消也归此态 |
+
+不要把 submit 成功当执行完成，不使用 `succeeded/cancelled` 作为普通任务终态。
+
+```json
+{
+  "ok": true,
+  "data": {
+    "task_id": "01900000-0000-7000-8000-000000000001",
+    "state": "completed",
+    "service_name": "report-worker-a1b2c3-d4e5",
+    "payload": {"service": "report-worker-a1b2c3-d4e5", "report_id": "report-001"},
+    "result": {"report_id": "report-001", "file_id": "file-001"},
+    "error_message": null,
+    "partial_result": null,
+    "metadata": {"run_id": "run-001", "attempt": "1"}
+  }
+}
+```
+
+详情还带 `created_at/completed_at` 以及 `tenant_id/user_id/origin_app`。示例省略这些字段。result 在网关中可解析为 JSON 时直接返回 JSON 值，否则返回字符串，空结果为 null；不能一律 `JSON.parse(result)`，也不能把 null 或空字符串当失败。failed 时读取 `error_message`，按执行服务契约保留 result 中的错误细节。多个 poller 或重复回调都可能观察同一终态，本 App 按 run/attempt 条件更新，并对通知、计费或后续步骤等结果消费做幂等。
+
+可从每 1–2 秒轮询起步，再按任务时长逐步放缓。每次取一个有效令牌，进程重启从已保存 task_id 恢复；本次等待期限、单次 HTTP 超时和执行器超时分别配置。期限到达只结束观察，不把任务记成已停止；没有证据时不另起新任务。
+
+`partial_result` 是累积文本：连续拿到 `"a"`、`"ab"` 应展示 `"ab"`。Portal HTTP 没有 `/v1/tasks/{id}/stream`、SSE 或 WebSocket 订阅；需要向浏览器推送时由本 App 后端轮询再转发。
+
+列表默认按用户过滤；`scope=tenant` 需管理员，服务态无 user_id 时看全租户。详情/取消只做租户校验；本 App 必须用自己保存的 run/task 关联执行用户和业务权限检查。列表默认过滤不能代替该授权。
+
+## 取消与回调
+
+普通 `/v1/tasks/{id}/cancel` 只取消 pending，成功 `data={task_id,state:"failed"}`；领取后返回 HTTP 200 + `INVALID_STATE`。重复或竞态请求可能已进入终态，重新查权威状态。添加 `abortIfRunning` 不能让此路由终止运行进程；专用运行中止仅在 workflow 动作面。
+
+可选回调优先级：请求 `callback_url` → 租户默认 → 无。默认拒绝 loopback、私网和 link-local，提交和投递均有 SSRF 检查。内部 `portal-api` 或 App 容器地址不能直接当公开回调。
+
+回调 POST 只有 `{"task_id":"...","state":"..."}`；没有 result、用户 TDT、自定义认证头或当前内建签名。它不能直接通过需要 TDT 的普通业务路由。若采用回调，仅接受本 App 已关联的 task_id，把通知去重后用自己的合法 TDT 回查权威详情，再更新业务状态。投递有重试但不保证送达，保留轮询恢复路径；普通接入可直接只做轮询。
+
+## 非鉴权故障定位
+
+| 现象 | 先检查 |
+| --- | --- |
+| 404/502 或非 JSON | Gateway 安装/启用、实际基址、Portal 反代；是否误拼内部 API_BASE_URL |
+| `NOT_FOUND` | 服务物理名、租户可见性、provisioned；任务是否属于当前租户或已过保留期 |
+| `VALIDATION_FAILED` | 幂等头、JSON、metadata 字符串值、callback SSRF |
+| 长期 pending | 服务 active_nodes、gRPC 出站连接、节点 token 服务集合、并发容量 |
+| 领取后失败 | 对齐 payload dispatch 路径、执行程序/运行账号、依赖、环境凭据与 stderr |
+
+行为依据：`gateway/src/portal/tasks.rs`、`gateway/src/queue/redis.rs`、`gateway/src/metadata_guard.rs`、`gateway/src/portal/respond.rs`。不要求调用方自行实现网关的 canonical JSON 摘要，保存并重传原请求即可。

package/skills/use-task-gateway/references/workers.md

@@ -0,0 +1,85 @@
+# 执行服务与 VM 对齐
+
+仅在需要新增执行能力或排查执行端时使用本参考。调用已有服务的 App 只需掌握其 payload/结果契约，不必安装 agent。
+
+## 服务与机器的分工
+
+App 调用 `service_name`，节点反向领取该服务队列；普通任务请求没有用于直接指定机器的 `host_id/node_id/cwd`。确需某 VM 上的本地仓库/CLI 会话时，可将专门服务只部署到该 VM，并保存业务工作区到服务名的绑定。现有服务亲和配置可影响分配，但普通 metadata 不是任意节点派发接口。
+
+租户管理员创建 `POST /v1/services`（`task_gateway.admin` + 用户 admin role），填写展示名、描述、可选 template_id 和超时；保存服务器返回的真实 name，创建体中的 name 不用于指定物理名。服务 `provisioned=false` 时用 `POST /v1/services/{name}/provision` 修复队列，无需重复创建。
+
+手工接入由管理员用 `POST /v1/node-tokens` 为该机的完整服务集合签发 Node Token，凭据只展示一次。
+
+先确认服务在线节点，再验证实际任务。缺 VM、依赖服务或容器时请求用户/运维提供环境，不擅自拉镜像或安装。
+
+## SSH 自动部署的能力确认
+
+需要新增机器且选择 SSH 自动部署时，先用具有 `task_gateway.read` 的 TDT 调用目标 Gateway 的 `GET /v1/onboarding`。HTTP 成功且信封 `ok:true` 后，读取 `data.auto_deploy`；鉴权或请求失败不能当成能力关闭。`auto_deploy=false` 时向网关维护方提供实际环境和版本，按用户选择使用手工接入或等待开通；不要把“接异步任务”默认扩展成机器部署。
+
+1.9.3 的打包配置默认启用 SSH 部署，根密钥由**网关自己的 manifest** 声明生成，并由支持该能力的门户在同一部署复用。调用方 App 不声明或持有网关根密钥。正常开通和升级由网关维护方通过 manifest、新镜像与发布链完成，不要求管理员登录系统手改环境，也不能通过重新生成存量密钥绕过故障。目标门户和网关仍须完成对应升级与发布；新版 skill 或本地 onebox 验证通过不代表线上能力已开启。
+
+能力确认后仍需准备目标服务/模板，并由机器所有者安装租户 SSH 公钥、核对目标主机指纹。自动部署会按保存快照生成完整 agent 配置并重启该机 agent，可能覆盖手工 YAML；当前服务 PATCH 只改展示名/描述，不是 executor 更新接口。五步向导可见只证明入口可用，实际部署成功还须确认 agent 上线并完成真实任务。
+
+## 最小多服务格式配置
+
+以下单服务配置使用当前 `services[].executor.kind` 格式；所有名称/路径均为需要替换的示例。Node Token 由 agent 进程环境注入，机器只需出站连接 gRPC，不走 Portal `/svc`。
+
+```yaml
+agent_id: "report-vm-01"
+node_token: "${XGENT_NODE_TOKEN}"
+service_key:
+  path: "service"
+gateway:
+  address: "gateway.example.com:50051"
+  tls: true
+services:
+  - name: "report-worker-a1b2c3-d4e5"
+    max_concurrent_tasks: 1
+    executor:
+      kind: cli
+      command: ["/usr/bin/python3", "/opt/task-handlers/report.py"]
+      input_mode: stdin
+      timeout_secs: 300
+      cwd: "/srv/report-work"
+    response:
+      success:
+        body: "<stdout>"
+      failed:
+        body: "<stderr>"
+      max_bytes: 1048576
+```
+
+agent_id 应稳定，不在每次重启时随机生成，尤其使用 lease 时。Node Token 必须允许配置中的所有服务且租户归属相符。开发明文 gRPC 可按实际部署将 tls 设为 false；生产使用平台给定 TLS 地址和信任配置，不默认跳过验证。
+
+服务 `task_timeout_secs` 应覆盖执行器 timeout 并留出回传余量。App 的 HTTP/观察超时不替代上述执行时限。
+
+## payload 与执行模式
+
+`service_key.path` 是从提交 payload 读取服务名的 dot-path。本例要求 `payload.service` 等于服务真实 name；该校验发生在执行侧。stdin 只收到整个 payload，HTTP metadata 不自动并入 stdin。需要 operation/report_id/workspace_id 等参数时放入 payload，并在适配器中校验。
+
+| executor kind | 适用能力 |
+| --- | --- |
+| `cli` | 一次非交互命令执行，退出码 0 成功；按 response 模板返回 stdout/stderr |
+| `sync-api` | agent 调用已有同步 HTTP 服务 |
+| `async-api` | agent 提交下游异步 API 并按配置轮询下游 |
+| `streaming-cli` | 持续转发 CLI stdout，App 提交需 streaming=true |
+| `streaming-sync-api` | 消费下游流式 HTTP 响应 |
+
+这些是执行端模式；App 到 Gateway 的提交/回查始终可以是异步 HTTP。不要因 App 要异步，就要求下游必须用 async-api。采用 API executor 时，以实际下游提交/轮询/流格式补配置；当前 schema 维护入口是 `gateway/src/agent/config.rs`，不要把 CLI 示例直接改 kind 当作完整 API 配置。
+
+CLI 适配器解析 JSON 后选择已配置能力，使用 argv 调用固定程序；网关不会自动执行 payload.command。用户传工作区逻辑 ID，再映射允许目录，避免直接采信任意绝对路径或 shell 文本。`cwd` 与 executor.env 是本机启动配置，不按任务 payload 动态求值；`<payload.prompt>` 当前会产生带引号的 JSON 字符串，不能当已解码 argv，复杂输入优先 stdin。
+
+仓库、工具、模型登录/凭据、产物上传均由 VM/App 准备；systemd 运行环境不会自动继承交互终端 export。模型密钥不放任务 payload，执行输出控制在 response.max_bytes 内，大文件上传对象/文件服务后返回引用，本地路径不自动变下载链接。
+
+需要流式 CLI 时，在 executor 内设置：
+
+```yaml
+kind: streaming-cli
+# command/input_mode/timeout_secs 等 CLI 配置仍须提供
+streaming:
+  response_format: lines
+```
+
+真实进程需换行并 flush。当前 streaming-cli 按原始 stdout 行转发，不按 content_path 自动提取某个 CLI 的 JSON 事件；NDJSON 等要由适配器/App 解析。
+
+`max_concurrent_tasks` 按单服务、单 agent 限制，多服务仍可并行；同仓库写入须调用方串行化、加锁或使用独立 worktree。Gateway 不创建/同步仓库、提供交互终端或管理 coding-agent 会话；task_id 不是 CLI session_id，多节点也不共享本地会话。App 等待超时、普通 cancel 拒绝、乃至任务已 failed，都不能单独证明远端所有进程和外部副作用已停止；严格生命周期由执行适配层管理并验证。