openyida 2026.10.20-2 → 2026.10.21

package/lib/samples/yida-print-template/receipt.json

@@ -0,0 +1,13 @@
+{
+  "document": {
+    "title": "收款凭证",
+    "style": "compact",
+    "width": 320,
+    "fontSize": 12,
+    "blocks": [
+      { "type": "fields", "fields": ["收据编号", "付款单位", "收款金额", "收款日期"] },
+      { "type": "divider" },
+      { "type": "html", "html": "<p>收款人：{{发起人}}</p><p>签字：________________</p>" }
+    ]
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openyida",
-  "version": "2026.10.20-2",
+  "version": "2026.10.21",
   "description": "OpenYida CLI - 宜搭低代码 AI 开发工具（安装即用，零配置）",
   "bin": {
     "openyida": "bin/yida.js",

package/yida-skills/SKILL.md

@@ -135,7 +135,7 @@ Fast / Plan 选定的主题和主色属于整个应用：导航、原生页、
 
 `yida-data-card` 只在用户显式指定宜搭原生数据卡片，或继续已明确的原生卡片上下文时触发。泛称数据卡片、指标卡、看板、投放、数据播报或发送到群不满足条件；不能在完整应用搭建中自行添加原生数据卡片。用户主动提供原生卡片链接并要求操作该资源属于明确指定；否定原生时按实际页面、图表或自动化意图路由。按本次实际修改对象判断，提及或引用原生卡片不等于请求修改该资源。
 
-`yida-cool-card` 只在用户明确指定宜搭原生酷卡片（交互卡片、置顶卡片），或继续已明确的酷卡片任务时使用。它使用 `cardPageCode`/`cardTemplateId`，独立于 `yida-data-card` 的 `CARD-xxx` 和页面中的展示卡片。`dataCardDesigner.html?cardCode=CARD-...` 属于原生数据卡片；酷卡片管理入口为 `coolCardManage`。名称与链接冲突时说明实际资源并核对目标，不能互换接口。泛称卡片、图表或群通知不自动选择这两类原生资源。
+`yida-cool-card` 只在用户明确指定宜搭原生酷卡片（交互卡片、置顶卡片），或继续已明确的酷卡片任务时使用。它使用 `cardPageCode`/`cardTemplateId`，独立于 `yida-data-card` 的 `CARD-xxx` 和页面中的展示卡片。`dataCardDesigner.html?cardCode=CARD-...` 属于原生数据卡片；酷卡片管理入口为 `coolCardManage`。创建前核对认证环境；集团版（`alibaba`）直接告知“集团版不支持酷卡片搭建”并停止搭建流程。名称与链接冲突时说明实际资源并核对目标，不能互换接口。泛称卡片、图表或群通知不自动选择这两类原生资源。
 
 ### 大类目录
 
@@ -144,7 +144,7 @@ Fast / Plan 选定的主题和主色属于整个应用：导航、原生页、
 | `yida-skills/context` | 登录、退出、切换组织、组织版本/容量、Schema、fieldId、执行前检查 | `yida-login`、`yida-logout`、`yida-basic-info`、`yida-get-schema`、`yida-corp-efficiency` |
 | `yida-skills/app` | 从零搭应用、完整系统、应用启停、应用导航、多语言、AI 老应用主题升级 | `yida-app`、`yida-create-app`、`yida-app-lifecycle`、`yida-nav-group`、`yida-i18n`、`yida-upgrade-app-theme`（仅明确升级要求并 ask_human 确认） |
 | `yida-skills/design` | 完整应用需求分析、PRD、视觉设计、单页 UI 改造、应用主题色、全局换肤、图片素材 | `yida-requirement-analysis`、`yida-prd`、`yida-design`、`yida-data-manage-ui`、`yida-image-assets` |
-| `yida-skills/form` | 表单字段、公式、校验、业务关联规则、原生自定义按钮、批量录入、数据记录 | `yida-create-form-page`、`yida-custom-button`、`yida-form-view`、`yida-formula`、`yida-formula-evaluate`、`yida-business-rule`、`yida-canvas-table-form`、`yida-table-form`、`yida-data-management` |
+| `yida-skills/form` | 表单字段、公式、校验、业务关联规则、原生自定义按钮、打印模板、批量录入、数据记录 | `yida-create-form-page`、`yida-custom-button`、`yida-print-template`、`yida-form-view`、`yida-formula`、`yida-formula-evaluate`、`yida-business-rule`、`yida-canvas-table-form`、`yida-table-form`、`yida-data-management` |
 | `yida-skills/process` | 审批、流程表单、流程规则、节点/分支/字段权限、流程代理 | `yida-create-process`、`yida-process-rule`、`yida-flow-node-config`、`yida-agent-center` |
 | `yida-skills/page` | 工作台、办事门户、任务看板、自定义展示页、页面源码开发、平台 JSX 组件页面维护、页面发布、页面内导航、PPT 页面 | `yida-create-page`、`yida-canvas-custom-page`、`yida-custom-page`、`yida-canvas-data-binding`、`yida-task-center`（仅显式选择自定义待办）、`yida-canvas-upgrade`、`yida-publish-page`、`yida-openyida-publish-guard`、`yida-density`、`yida-nav-shell`、`yida-ppt-slider` |
 | `yida-skills/analytics` | 用户显式指定宜搭原生数据卡片（含其投放播报）；聚合表、虚拟视图、报表、统计、图表、Recharts、ECharts、经营分析看板、驾驶舱、大屏 | `yida-data-card`、`yida-aggregate-table`、`yida-report`、`yida-rechart`、`yida-chart`、`yida-dashboard` |
@@ -199,6 +199,7 @@ Fast / Plan 选定的主题和主色属于整个应用：导航、原生页、
 | 业务操作队列、业务工作台或办事门户页面 | `yida-canvas-custom-page`；接业务数据时加载 `yida-canvas-data-binding`，不因页面名称或辅助统计转为经营看板；不顺带新增自定义审批待办中心 |
 | 批量录入、表格填写、多行编辑 | 默认 `yida-canvas-table-form`；已检测到平台 JSX 组件页面、native 页面或存量源码使用 `this.utils.yida.saveFormData` 时用 `yida-table-form` |
 | 页面设置中的自定义按钮、客户跟进/分配、审批后发起订单、按钮触发自动化或打开页面 | `yida-custom-button`；配置原生按钮定义和显示位置，自定义页面内 React 按钮不走此入口 |
+| 打印这条数据/数据详情链接、原生打印模板、打印设置、订单/报价/出入库/审批单、单据版式与字段明细、字段二维码/条形码、备份恢复和PDF生成 | `yida-print-template`；复用已有表单和模板，以真实打印字典生成动态内容；Word组件、叮当打印和浏览器页面打印不走此入口 |
 | 原生数据管理页视图列表、显示列配置、字段显隐与顺序、列宽、冻结列、默认筛选、多视图 | `yida-form-view`；使用原生配置读写，保存前备份并回读，不通过 CSS 隐藏字段或重建自定义列表 |
 | 当前数据管理页换风格、只留横线、突出新增/筛选/行操作、列级强调、状态列标签、数据管理 UI 异常、自定义简单数据管理 | `yida-data-manage-ui`（优先于通用美化）；保留承载类型和业务，从目标推导维度、定位 token/CSS 并按页改写；备份发布并实测，不要求选择配方 |
 | 页面视觉方向、页面美化、去 AI 味、优化应用 UI、不好看、太乱、美化后不满意或恢复 | `yida-design`；已有资源优先走 `sub_skill/ui-improve/SKILL.md`，先展示视觉方案，经 `ask_human` 确认并备份后才交接实施，只改 UI；不满意恢复本轮前状态。新页面设计沿用原设计流程 |

package/yida-skills/skills/yida-cool-card/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: yida-cool-card
-description: 仅在用户明确要求宜搭原生酷卡片（交互卡片、置顶卡片），或继续该上下文时使用。支持创建、读取、查询模板、导出配置和样式设计。样式限于钉钉原生组件，不能运行任意 HTML/CSS/React；超出能力时说明限制并提供替代方案。返回官方编辑器链接，由用户配置保存；CLI 不保存、发布或发送。原生数据卡片、Canvas 展示卡片及泛称卡片不触发。
+description: 仅在用户明确要求宜搭原生酷卡片（交互卡片、置顶卡片），或继续该上下文时使用。集团版不支持酷卡片搭建，先核对认证环境。提供创建、读取、查询模板、导出配置和样式设计。样式限于钉钉原生组件，不能运行任意 HTML/CSS/React；超出能力时说明限制并提供替代方案。返回官方编辑器链接，由用户配置保存；CLI 不保存、发布或发送。原生数据卡片、Canvas 展示卡片及泛称卡片不触发。
 ---
 
 # 宜搭原生酷卡片
@@ -21,6 +21,8 @@ description: 仅在用户明确要求宜搭原生酷卡片（交互卡片、置
 
 先用 `openyida login --check-only --json` 核对目标组织、用户和环境，再复用用户指定的应用。用户要求读取已有卡片时不新建；已有标识不明时先列出核对。
 
+**集团版不支持酷卡片搭建。** 用户要求创建或搭建酷卡片时，先依据认证连接的实际 `baseUrl` 判断环境；复用 CLI 的环境识别语义，`alibaba` 为集团版（包括 `yida-group.alibaba-inc.com` 及已识别的内网宜搭环境）。已确认集团版时，直接告知“集团版不支持酷卡片搭建”，结束搭建流程，不创建应用或卡片、不查询模板或提供编辑器链接，也不引导安装 dws 绕过限制。环境不明时先查登录状态，不凭应用名称、组织名称或公有云付费版本猜测。CLI 的 `COOL_CARD_UNSUPPORTED_ENVIRONMENT` 同样按此处理。
+
 ```bash
 openyida app-settings APP_XXX --section cool-card --json
 openyida cool-card list APP_XXX --type im --json

package/yida-skills/skills/yida-feedback/SKILL.md

@@ -37,7 +37,7 @@ openyida feedback report --input summary.json --output-dir feedback-draft-001
 ## 按用户条件交付
 
 - **无 GitHub 账号**：先引导用户创建 GitHub 账号，由用户自行完成注册和登录。实在不行，只提示“反馈到AI开发者群”，附上已整理的脱敏报告。不索取群链接或群 ID，不编造入群入口，不替用户发送群消息。离线或暂不愿注册时同样交付报告，明确“材料已生成，尚未提交”。
-- **有 GitHub 账号，提交 Issue**：不需 clone/fork。先准备正文、核对公开目标、查重，再按 [GitHub 提交](references/github-contribution.md) 执行。登录由用户在可信本机流程完成，不索取 Token。
+- **有 GitHub 账号，提交 Issue**：不需 clone/fork。用户明确选择提交 Issue 后，用 `openyida feedback github status --json` 检查当前 GitHub 账号的 Star 与个人 Fork 状态；仅对明确未完成的操作提供一次可选邀请，已有的不重复提示，未知状态不说成未完成。按 [GitHub 提交](references/github-contribution.md) 处理用户选择、正文公开确认与查重。拒绝 Star/Fork 不影响提交；登录由用户在可信本机流程完成，不索取 Token。
 - **有账号，希望提交修复 PR**：仅适用于公开 OpenYida CLI/skill/docs 的可验证问题。先准备最小修复和验证，再通过用户自己的 Fork 提交到公开上游，详见同一参考。没有源码时由 Agent 在独立目录准备公开源码，不修改 npm 全局安装或用户业务目录。无法定位/验证时如实写入测试对比，优先交付 Issue 草稿；不要承诺未经验证的修复。
 
 创建 Issue、评论、Fork、push 或 PR 前必须有用户对相应外部动作及公开内容的授权；已有对同一最终稿和截图的隐私确认不重复问；单纯授权提 Issue/PR 不能替代公开内容审阅。只要求“排查”“整理反馈”不代表允许公开提交。提交超时先查是否成功，不自动重复创建。

package/yida-skills/skills/yida-feedback/references/github-contribution.md

@@ -6,6 +6,23 @@
 
 ## Issue（无需源码）
 
+用户明确要向 OpenYida 提交 Issue，且选择 GitHub 路径后，再执行以下只读检查；普通排障、离线报告、安装及自动更新不触发：
+
+```bash
+openyida feedback github status --json
+```
+
+命令复用本机 `gh` 的 github.com 当前账号，不读取 Token，不自动安装或登录。`starred` 为 true/false/null，个人 `fork.state` 为 ready/absent/conflict/unknown；同时检查改名的个人 Fork。只有 `suggestedActions` 中的缺失项可提供一次可选邀请：例如“是否愿意 Star 支持项目，或 Fork 留作后续贡献？也可以直接提交 Issue”。已有 Star/Fork 不重复提示；接口失败、权限不足或状态未知时不推断为未完成，不阻塞 Issue。没有可用 gh 时沿用连接器或浏览器；未登录时由用户自行登录，不索取凭据。
+
+用户分别明确选择后，Agent 才执行相应命令（`--confirm` 记录其真实授权，不能自行代选）：
+
+```bash
+openyida feedback github star --confirm --json
+openyida feedback github fork --confirm --json
+```
+
+命令固定目标为 `openyida/openyida`，已有操作直接复用；Fork 只创建到当前用户个人账号，不 clone、不修改 remote。Fork 异步创建可能返回 `pending-verification`；先只读查状态，不重复创建。无论拒绝、失败或未登录，都可继续整理并提交 Issue；Star/Fork 是可选支持，不是提 Issue 的条件，也不代替正文与附件的公开确认。同一反馈流程拒绝过的选项不再次询问。现有 PR 流程的 Fork 授权仅用于贡献代码，不隐含 Star 授权。
+
 1. 先完成 [交互与公开确认](user-interaction.md)：展示实际问题、复现步骤和全部截图，取得用户对最终公开内容的确认。用户未登录时引导注册/登录；实在不行提示“反馈到AI开发者群”。只有用户选择 GitHub 路径才检查 `gh auth status --hostname github.com`；不要读/打印 Token，也不要自动装 gh 或创建账号。
 2. 用 `gh issue list --repo github.com/openyida/openyida --state all --search '<问题关键词>' --json number,title,url` 查重，阅读匹配正文核实症状与版本。相同问题给现有链接；用户明确允许补充时才评论，不关闭别人的 Issue。无法查询时说明查重未完成。
 3. 已完成最终稿和截图的公开确认后，用 `gh issue create --repo github.com/openyida/openyida --title '<脱敏标题>' --body-file '<issue.md>'`。有已确认截图时，先检查当前 `gh issue create --help` 是否支持 `--attach`，每张显式追加 `--attach <审阅后的截图>`；同一命令只包含用户批准的图片，不上传额外附件。不支持时用可操作的 GitHub 网页上传，不静默丢图。默认不指定未知 label/assignee。
@@ -17,10 +34,10 @@ PR 需要真实修复 diff、修复前后测试对比和最终内容公开确认
 
 1. 先说明将下载公开 OpenYida 源码。用户已明确要求修复/PR 时，在业务目录之外的新贡献目录准备代码；无网络、空间不足或不愿下载则交付报告，不阻塞用户原任务。不覆盖现有目录，不修改全局 npm 包。仅 clone `https://github.com/openyida/openyida.git`，读取其 AGENTS.md，fetch 最新公开 main 后新建 `codex/<修复名>` 分支。复现用户安装版本与当前 main 差异，问题已修复时给版本证据，不重复造修复。
 2. 用公开代码/技能和最小合成样例定位问题，补最小改动和有意义的回归验证。验证须覆盖原复现，不把本地通过说成平台/浏览器通过。先交付 diff、修复前后同一复现/测试的实际结果、回归结果、未验证事项和 PR 正文。用结构化问答确认正文、截图、测试报告中有无敏感信息或不想公开的内容；用户要求删除/修改后重新展示并确认，再进行授权范围内的远端操作；仓库约定仍适用。
-3. 读取 `gh api --hostname github.com user --jq .login` 获得实际用户。即使该账号有上游写权限，也坚持个人 Fork。先 `gh repo view github.com/<用户>/openyida --json nameWithOwner,isFork,parent,url` 验证已存在的仓库；不存在且用户已授权 Fork/PR 时执行 `gh repo fork https://github.com/openyida/openyida --clone=false --remote=false`。不能将网络或权限错误当作不存在。再次核验 `isFork: true`、parent 为 `openyida/openyida` 且所有者是当前用户；同名非 Fork、组织账号或所有者为上游时停止远端写入并回到 Issue 路径。
+3. 读取 `openyida feedback github status --json`，复用当前用户已验证的 `fork.url`（包括改名的个人 Fork）。即使该账号有上游写权限，也坚持个人 Fork。仅当状态为 absent 且用户已授权 Fork/PR 时执行 `openyida feedback github fork --confirm --json`；pending-verification 先只读核查，不重复创建。无 gh 时用现有连接器/浏览器完成同等核验。不能将网络或权限错误当作不存在。再次核验 Fork、parent 为 `openyida/openyida` 且所有者是当前用户；同名非 Fork、组织账号或所有者为上游时停止远端写入并回到 Issue 路径。PR/Fork 授权不包含 Star。
 4. 在贡献目录添加指向已核实个人 Fork 的专用 remote（如 `contributor`）。先读 `git remote -v`；同名 remote 不同目标时换新名称，不覆盖。只向该个人 Fork push 当前修复分支。不要执行裸 `git push`，不要推上游，不 force push，不携带业务目录文件。仅在用户授权提交/push 时执行；如需 commit 遵循仓库约定，明确列出本次文件，禁用 `git add .`。
 5. 先查该 head 是否已有 PR：`gh pr list --repo github.com/openyida/openyida --state all --head '<分支>' --json number,url,state,headRepositoryOwner,headRepository,baseRefName`，再核对 head 所有者和仓库是已验证个人 Fork（list 的 --head 不支持 owner:branch）；已有则读取并复用，关闭/合并过的 PR 先核对状态，不自行重开。
 6. 明确指定 head，防止 gh 自动推送或选择上游分支：`gh pr create --repo github.com/openyida/openyida --base main --head '<用户>:<分支>' --draft --title '<脱敏标题>' --body-file '<pr-body.md>'`。PR 正文包含原问题、实际复现步骤、修复行为、修复前后测试对比（版本/命令/实际结果/证据）、回归验证和剩余限制。有已确认截图时检查当前 gh 是否支持 `--attach`，逐张显式附加；不支持则走可操作的网页上传，不省略用户批准的图片。不得使用 `--dry-run` 作为零副作用验证，它可能 push。
 7. 读回 PR 的 base、head 仓库/所有者、分支、正文和 URL，确认个人 Fork → 上游 main。失败或超时先只读检查 Issue/PR/分支，不能自动重复创建或换账号。最终给真实链接与验证结论，不代合并。
 
-官方命令契约：[Fork](https://cli.github.com/manual/gh_repo_fork)、[Issue](https://cli.github.com/manual/gh_issue_create)、[PR](https://cli.github.com/manual/gh_pr_create)、[PR 查重](https://cli.github.com/manual/gh_pr_list)。
+官方契约：[Star API](https://docs.github.com/en/rest/activity/starring)、[Fork API](https://docs.github.com/en/rest/repos/forks)、[个人 Fork 查询](https://docs.github.com/en/graphql/reference/repos)、[Issue](https://cli.github.com/manual/gh_issue_create)、[PR](https://cli.github.com/manual/gh_pr_create)、[PR 查重](https://cli.github.com/manual/gh_pr_list)。

package/yida-skills/skills/yida-print-template/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: yida-print-template
+description: 宜搭原生富文本打印模板管理与单据搭建。用于打印这条数据、打印数据详情链接、打印设置、订单/报价/出入库/审批单模板、字段二维码和条形码，支持按真实字段生成版式、查询、创建、复制、保存、备份恢复、文件名、使用范围、启停、排序和请求原生PDF。不用于Word模板组件、叮当打印、浏览器页面打印或物理打印机控制。
+---
+
+# 宜搭打印模板
+
+让业务表单中的数据按不同单据版式输出。先理解用途、必需字段、明细列、签字位置和打印对象，从真实打印字典中选择字段；不要把一张普通网页截图当作打印模板。
+
+## 范围
+
+- 原生富文本编辑器：标题、段落、字体字号、表格布局、普通字段、日期格式、图片、字段二维码和条形码、子表明细、系统字段、评论记录及字典中存在的审批节点。
+- `document`、`compact`、`formal` 是生成器的排版起点；可自由组合区块和静态 XHTML，形成订单、报价、出入库、审批单、窄内容收据等多种版式。
+- 保存后直接生效，没有独立 publish 命令。默认保留模板启停状态与使用范围，不修改组织版本、权益和额度。
+- 模板正文是原生 `termContents`、`termJsonAttr`、`dictionaryList` 三件套。原生编辑器的复杂样式和组件可导出后修改、保存，不凭空添加未经证实的协议键。
+- 不承诺完整桌面排版能力：纸张规格、页边距、固定页眉页脚、页码、强制分页、精确套打、自动金额大写与汇总不在此编辑器已验证范围内。合计用已有计算字段；宽度是内容宽度，不是纸张规格。
+- Word、叮当和政务打印是不同链路，本技能不通过富文本接口改写它们。标准原生自定义打印仍受平台付费版本和权限限制；遇到拒绝保留原始原因。
+
+## 从数据详情页打印
+
+用户给出宜搭数据详情链接说“打印这条数据/这个详情页”时，优先复用该记录与已有模板，无须先去管理后台新建。使用 [详情链接打印指南](references/detail.md)：读取记录有权限使用的模板，明确选用哪份，生成原生 PDF 并核对文件。多份模板用途不明确时先展示名称让用户选择。
+
+原生模板把该条记录数据排成单据；“把页面按屏幕样子打印”属于浏览器页面打印，应说明两者的效果差别，不能把截图当原生模板。
+
+## 新建与修改入口
+
+按用户意图选择：新建单据用场景 build → create --config；已有模板的正文改动用 inspect → 编辑配置 → save；仅改名称、说明或文件名前缀用 settings；在原稿上做不同版式用 copy 后修改新编号。保留真实业务字段语义，不因套用场景把单价伪装为商品名。
+
+六种场景与字段映射、新建、修改、复制变体的完整用法见 [场景搭建指南](references/scenarios.md)。场景只是可编辑起点，用户可以任意组合已有区块，不受六种名称限制。
+
+## 操作步骤
+
+1. 解析用户已有 app/form/template。链接中 `templateId` 就是模板编号；同一表单可以有多份模板。已有模板默认修改；比较不同版式时优先复制或新建，保留原稿。
+2. 按总入口完成登录态确认，再读取：
+
+```bash
+openyida print-template list <appType> <formUuid> --json
+openyida print-template fields <appType> <formUuid> --out .cache/openyida/print/fields.json --json
+openyida print-template inspect <appType> <formUuid> <templateId> --out .cache/openyida/print/before.json --json
+```
+
+`list` 返回 `orderHash`；`inspect` 返回正文、元信息、`configHash` 和原生 `gmtModified`。尚未保存过正文的模板可返回空正文，不能声称空内容已经是默认版式。内置编号 0 的默认模板正文不能直接编辑。
+
+3. 选择真实字段名或 key。重名时用确切 key；子表列必须从对应子表 children 选择。不可用截图或相似字段名猜 ID。申请单、审批单只放业务需要的系统字段和审批节点，不默认加入个人信息或评论。
+4. 生成配置。示例：
+
+```json
+{
+  "document": {
+    "title": "销售报价单",
+    "style": "document",
+    "font": "宋体",
+    "fontSize": 14,
+    "blocks": [
+      {"type":"fields","columns":2,"fields":["客户名称",{"field":"报价日期","format":"yyyy-MM-dd"}]},
+      {"type":"heading","text":"商品明细"},
+      {"type":"table","field":"报价明细","columns":["商品名称","数量","单价","金额"]},
+      {"type":"fields","fields":["总金额"]},
+      {"type":"html","html":"<p>经办人：{{发起人}}</p><p>客户签字：________________</p>"}
+    ]
+  }
+}
+```
+
+字段名称仅为说明，实施前替换成实际字典中的名称。模板示例通过 `openyida sample yida-print-template order|quotation|delivery|receipt|approval|codes --output <file.json>` 输出。六个 sample 不会创建模板；先替换字段，再执行 build 校验。
+
+```bash
+openyida print-template build <appType> <formUuid> --config .cache/openyida/print/document.json --out .cache/openyida/print/native.json --json
+openyida print-template create <appType> <formUuid> --name "销售报价单" --json
+openyida print-template save <appType> <formUuid> <新templateId> --config .cache/openyida/print/document.json --expected-hash <create返回的configHash> --json
+```
+
+`build` 只编译/校验，不远端保存。`create` 不传 --config 时创建空模板；传 --config 会先校验内容，再创建并保存回读。它由两步原生操作组成，不能视为原子事务；后续保存失败时错误中的 createdTemplateId 指明已创建资源，先 inspect，再对该编号 save，不能重复 create。每次修改已有模板先 inspect，使用最新 configHash；`save` 是全量正文替换，元信息和使用范围保持原样。保存实际送出最新 gmtModified，平台可以拒绝并发冲突；没有正文时间戳的首次保存只能做客户端指纹校验。
+
+5. 需要复制时执行 `copy ... <源templateId> --name "新名称" --expected-hash <源hash>`，回读新编号；复制正文和平台复制规则，以新模板实际回读为准。
+6. 设置与恢复：
+
+```bash
+openyida print-template settings <appType> <formUuid> <templateId> --config .cache/openyida/print/settings.json --expected-hash <hash> --json
+openyida print-template status <appType> <formUuid> <templateId> --status START --expected-hash <hash> --json
+openyida print-template order <appType> <formUuid> --config .cache/openyida/print/order.json --expected-hash <orderHash> --json
+openyida print-template restore <appType> <formUuid> <templateId> --config .cache/openyida/print/before.json --expected-hash <当前hash> --json
+```
+
+`settings.json` 仅支持 title、description、fileNameConfig、roleData。title/description 可用字符串或保留其他语言的 i18n 对象。文件名支持固定文本和 `$!{instanceTitle}`、`$!{originator}`、`$!{createTime}`、`$!{serialNo}`。使用范围必须是用户明确要求的修改，使用平台格式的 `[{"roleType":"ALL","roleValue":"y"}]`，并显式传 `--allow-permission-change`；不默认为所有人扩大范围。默认模板仅允许修改角色范围。
+
+排序文件为所有现有模板编号的数组，包括默认编号 0，每个恰好一次。`restore` 只恢复同 app/form/template 的正文，不恢复角色、启停或文件名。所有远端写操作先独占创建备份文件；不覆盖旧备份。
+
+7. 按任务需要验证真实数据输出：
+
+```bash
+openyida print-template render <appType> <formUuid> <templateId> --instance <真实记录ID> --json
+openyida print-template files <appType> <formUuid> --page 1 --size 50 --json
+```
+
+render 返回 fileId 只说明请求已受理。在 files 中按 ID 确认 FINISH 与下载地址，查看实际 PDF 后才能说排版和数据正确。失败时保留原生状态，不自动重发。该操作使用已有单条记录，不生成/更改业务记录，也不控制物理打印机。受管云端应用搭建任务不能执行 render。
+
+## 区块配置
+
+| type | 内容 |
+| --- | --- |
+| heading / text | text；可选 align=left/center/right |
+| fields | fields 字段数组；columns=1/2/3/4；每项可用字符串或 `{field,label,format,width,height,render}` |
+| field | field 单个动态字段；日期 format 必须命中字典；图片 width/height 为像素 |
+| qrcode / barcode | field 真实字段名或 key；可选 width/height 像素，默认二维码128×128、条形码240×80；按每条记录的字段值动态生成 |
+| table | field 子表、评论或审批节点；columns 指定真实子字段、顺序和标签；可选日期格式 |
+| html | 静态 XHTML；`{{字段名或key}}` 注入原生动态组件；禁止脚本、事件处理器、Velocity 指令 |
+| image | 已有 HTTPS 图片 url，可选 width/height；不自动上传文件 |
+| divider | 分隔线 |
+
+字体只用宋体、Arial、新宋、微软雅黑、黑体。fontSize=8–72，width=160–2000 内容像素。原生配置必须完整提供三件套；复杂复选框等组件可通过原生导出保留，未知 key 或格式不能悄悄降级。
+
+## 二维码与条形码
+
+先读取 fields：可转码字段的 `codeFormats` 返回 qrcode/barcode；不可用时有 codeUnavailableReason。遵循原生编辑器的专业级/专属级版本与功能开关，不通过自行画图、改版本或改开关绕过。文本、数字、单选、下拉单选及系统流水号可转码；日期、成员、附件和明细父组件不能直接转码。明细列按实际子字段判断。
+
+```json
+{"document":{"title":"扫码核验单","blocks":[
+  {"type":"qrcode","field":"订单编号","width":128,"height":128},
+  {"type":"barcode","field":"订单编号","width":320,"height":100}
+]}}
+```
+
+字段网格或子表列可写 `{"field":"商品编码","render":"barcode","width":240,"height":80}`。码图使用原生 `<字段key>.qrcode` / `<字段key>.barcode` 动态图片协议，并可原生导出、恢复和复制。不要把字段名称编码成静态码图，不能把一张码图在不同记录间重复使用。
+
+二维码可承载原字段内容（含中文），条形码按原生编辑器限制使用英文大写字母、数字、中划线、斜杠、点等支持字符；不可擅自将小写变大写、删除中文或替换原字段值。长内容与较小尺寸会影响识别率，按真实PDF检查并解码比对；没有手机/扫码枪验证时不宣称设备验收。原生保存成功、PDF有图片不等于内容正确。
+
+## 完成与失败
+
+成功交付说明模板用途、真实编号、回读结果和编辑入口；完整路径为用户提供域名下的 `/alibaba/web/<appType>/admin/printTemplateEdit?formUuid=<formUuid>&templateId=<templateId>`，无须追加 `defaultTemplate=true`。平台前缀可能随环境不同，以实际已有链接为准。
+
+只有 build 不能说模板已保存；保存成功不能说 PDF 通过；PDF 请求受理不能说文件已生成；截图不能证明物理打印完成。写请求失败或回读不符可能已经产生变更，先 inspect/list 并使用备份恢复，不自动重放写操作。
+
+详细命令及边界见 [打印模板指南](references/guide.md)。

package/yida-skills/skills/yida-print-template/references/detail.md

@@ -0,0 +1,40 @@
+# 打印一条数据详情
+
+原生模板配置归属于表单；模板在数据详情、流程详情等入口选择，套入当前记录。用户给出详情 URL 并说“打印这个”时，已有 render 是生成该记录 PDF 的底层操作，不需要先重建模板或数据。
+
+## 直接使用详情链接
+
+```bash
+openyida print-template list --detail-url "https://tenant.aliwork.com/APP_XXX/formDetail/FORM_XXX?formInstId=FINST_XXX" --json
+openyida print-template render --detail-url "https://tenant.aliwork.com/APP_XXX/formDetail/FORM_XXX?formInstId=FINST_XXX" --template-id <选定编号> --json
+openyida print-template files <appType> <formUuid> --page 1 --size 50 --json
+```
+
+list 通过原生 `listTemplateWithAuth`，以 formUuid + formInstId 查询该登录用户在该记录可用的模板，回执标记 authorizationScoped；不是管理员的模板管理列表，不返回排序指纹。render 使用同一权限列表预检，再调用原生打印接口，不读取需要管理权限的模板正文。文件生成仍受平台记录、模板、版本与额度校验，不能把“预检可用”当作最终打印许可或 PDF 已生成。
+
+模板编号需要明确选择。默认编号 0 仅在可用列表返回时使用；默认打印发送 DEFAULT 且不发送自定义 templateId。其他原生模板使用 CUSTOM。Word/叮当等模板不能通过此命令伪装为 CUSTOM。
+
+如果用户指定“收据/订单/扫码版”等用途，可与列表中的模板名称和既有上下文对应；用途不明确且有多份时展示选择，不自行修改默认模板或新建一份。用户要求新样式、增删字段时再进入模板新建/修改流程。
+
+## 链接规则与环境
+
+- 支持原生 `/<appType>/formDetail/<formUuid>?formInstId=...`、processDetail 同结构；流程链接有 activityId 时保留到打印请求。
+- 支持已包含 formUuid 和 formInstId 的旧 `/alibaba/web|mobile/<appType>/inst/formEdit.html`、taskDetail.html 链接。
+- 必须有明确记录 ID。只有表单地址、列表地址、管理编辑器地址或旧流程链接缺少 formUuid 时，先从可见页面或业务查询确认真实记录与表单，不用相近 ID 猜测。
+- 链接域名/协议必须与当前认证 base_url 同源；不跟随跳转、不访问该链接指向的任意网络资源、不修改 profile 去迁就链接。不同环境需按总入口明确登录/切换后再执行。
+- query 中重复或冲突的 appType/formUuid/formInstId/activityId、带认证信息或 hash 路由的 URL 不接受。短链、钉钉外层跳转及自定义页面地址需先用当前浏览器解析到真实原生详情链接。
+
+也可从已核实的目标标识打印：
+
+```bash
+openyida print-template list <appType> <formUuid> --instance <记录ID> --json
+openyida print-template render <appType> <formUuid> <templateId> --instance <记录ID> --json
+```
+
+不传 --instance 的 list 才是模板管理列表。URL 快捷入口面向本地 CLI；受管云端搭建任务仍禁止 render，不能通过 URL 绕开。
+
+## 输出语义
+
+render 返回 fileId 代表请求受理。按该 ID 查询 FINISH，打开实际 PDF 检查是否为正确记录、明细是否完整、中文、分页与码图是否正确，再交付文件或下载入口。RUNNING、失败、登录缺失和业务错误均保留真实状态，不自动重发请求。不会新增/修改业务记录，也不会自动发给他人或送到物理打印机。
+
+“按详情页当前屏幕原样打印”与“按原生模板打印当前记录”是两种输出。原生 PDF 不保证复制页面导航、按钮、Tab、页面布局或自定义组件。若用户明确要求屏幕原样，说明需要浏览器打印能力；不要宣称此 CLI 已提供任意网页的像素级打印。

package/yida-skills/skills/yida-print-template/references/guide.md

@@ -0,0 +1,35 @@
+# 打印模板指南
+
+原生模板可在宜搭编辑器继续拖改和保存。CLI 保存的是相同资源，无额外的“CLI 发布态”。
+
+原生复制接口在部分环境会复制版式但遗漏字段字典。CLI 仅在新版式与源模板完全相同、且字典确实为空时，对新模板执行一次带备份和版本校验的字典补全，再核对三件套。其他不一致直接报未验证，不盲目覆盖。
+
+## 选择版式
+
+- 订单/报价：document，双栏基本信息，明细表，合计计算字段，签字说明。
+- 审批/申请：formal，单栏关键信息、申请说明、审批节点或审批历史，签字区域。
+- 收据/领取单：compact，较小字号与内容宽度，关键字段与金额，简短备注。窄内容宽度不等于设置了热敏纸规格。
+- 完全自定义：html 区块组织静态 XHTML，把 `{{字段}}` 放在需要的位置。图表、交互脚本、任意浏览器 CSS 不属于原生 PDF 排版契约。
+- 追溯与扫码：qrcode / barcode 区块按真实字段生成动态码图。字段网格、明细列也可用 render 属性显示二维码或条形码；字段资格、版本和功能开关与原生编辑器对齐。码图默认尺寸可改，但尺寸过小不保证扫码识别。
+
+## 原生往返编辑
+
+inspect --out 导出完整快照。将快照 content 中的 termContents、termJsonAttr、dictionaryList 三个字段组成新的 JSON 文件，编辑后用 save。宏 ` #macro_<id> `、组件 ID、dictionaryList 中的 id/type/key 必须一致。termJsonAttr.content 是编辑器动态输入组件的 XHTML，并非运行脚本。
+
+restore 接受完整快照或命令自动备份，校验原目标。备份中的 configHash 是旧版本；恢复时 `--expected-hash` 必须用当前 inspect 返回的新指纹。
+
+## 权限与并发
+
+元信息/启停/排序没有统一服务端 compare-and-swap；客户端指纹能发现读取之后已有的变化，不能锁住其他管理员。正文 save 使用平台已有 gmtModified 检查，平台返回 300051 时重新 inspect 并合并，不可剥掉时间戳强制写入。空模板尚无正文时间戳时仍存在首次保存竞争。
+
+新模板的初始使用范围由平台创建接口决定；create 结果中显示 roleMembers。接入面向特定人员的模板时，应在使用前按用户明确指定的范围调整并验证。不得更改组织权益或绕过打印权限。
+
+roleData 是平台权限角色序列，roleValue 是原始值字符串，不是 roleMembers 中的展开成员数组。不要把展示用 roleMembers 直接作为写入参数。复杂角色应先在平台现有范围中确认角色类型及 ID，再提交。
+
+## PDF 检查
+
+render 使用 CUSTOM 类型请求自定义模板，保留平台模板权限校验。返回文件 ID 后，files 的分页结果由平台提供；FINISH 是文件生成状态。用当前环境的 previewUrl/downloadUrl 访问；相对 URL 依附当前 auth base_url，不改成其他组织域名。
+
+本文不承诺创建 Word 模板、叮当模板、批量打印、删除模板、安装字体、下载或发送到人员/群、修改打印额度与物理打印机操作。
+
+字段码图在原生模板中仍使用 img 类型，字段 key 为原字段加 `.qrcode` 或 `.barcode`。原生导入校验需要确认原字段存在、类型符合原生白名单、当前组织码图能力已核实；不能仅因输入看起来是图片而放行。字段网格和明细列同样进行资格校验。宽高写入原生 td-width/td-height 及容器尺寸。正文备份与恢复保留这些信息。

package/yida-skills/skills/yida-print-template/references/scenarios.md

@@ -0,0 +1,72 @@
+# 打印模板场景搭建
+
+这些场景复用同一个生成器和原生资源接口，不创建对应业务表单，也不生成业务记录。先从 fields 获取真实字段，再确定用途和必要信息；缺少字段时调整版式或说明缺失，不能填造数据。
+
+| scene | 布局起点 | 需要映射的业务角色 |
+| --- | --- | --- |
+| order | 双栏信息、商品明细、金额与签字 | 订单编号、客户名称、订单日期、经办人、订单明细、商品名称、数量、单价、金额、合计金额、备注 |
+| quotation | 正式报价、明细和确认签字 | 报价编号、客户名称、报价日期、经办人、报价明细、商品名称、数量、单价、金额、报价总额、报价说明 |
+| delivery | 交接信息、数量明细、双方签收 | 发货编号、收货单位、发货日期、经办人、发货明细、商品名称、发货数量、交接备注 |
+| receipt | 紧凑单栏、金额和签字 | 收据编号、付款单位、收款金额、收款日期、发起人 |
+| approval | 申请信息、说明、真实审批历史 | 申请编号、申请人、申请日期、申请金额、申请说明、审批历史；审批历史必须映射实际 table 或审批节点，普通复核结果文本应改成 field 区块 |
+| codes | 编号文本、二维码和条形码 | 订单编号；要求 fields 码图资格与组织能力可用 |
+
+## 通过场景新建
+
+示例 bindings.json 是“场景角色 → 实际字段名或 key”的平面对象；子表列会在对应父表范围内解析。默认使用同名真实字段；传错角色名称、字段缺失、重名不明确或列属于其他子表时都失败，不猜测近似字段。
+
+```json
+{
+  "收据编号": "textField_receiptNo",
+  "付款单位": "客户单位",
+  "收款金额": "实收金额",
+  "收款日期": "到账日期",
+  "发起人": "originator"
+}
+```
+
+```bash
+openyida print-template fields <appType> <formUuid> --json
+openyida print-template build <appType> <formUuid> --scene receipt --bindings bindings.json --out receipt-native.json --json
+openyida print-template create <appType> <formUuid> --name "收款凭证" --config receipt-native.json --json
+```
+
+build 不远端保存，--out 写完整原生正文，JSON 回执还返回映射后的 document。create --config 先校验，后创建并保存；成功返回新 templateId、contentSaved、readbackVerified、正文备份 backupPath 和创建前列表备份 createBackupPath。省略 --config 仍可新建空模板，后续单独 save。
+
+需要调整列、标题或签字栏时，先输出可编辑场景源文件，修改后再 build 或 create --config：
+
+```bash
+openyida sample yida-print-template quotation --output quotation-document.json
+# 按实际 fields 替换字段，增删 blocks、重排 columns、调整 style/fontSize/width
+openyida print-template create <appType> <formUuid> --name "客户报价单" --config quotation-document.json --json
+```
+
+映射只选择真实字段，不改动表单值。默认字段网格和明细列显示真实字段名称；需要 label 别名时，应保持业务含义。不同计量、价格与金额不能为了凑齐样例而相互冒用。
+
+## 修改已有模板
+
+已有本地 document 配置时，修改其 blocks、字段顺序、日期格式、码图尺寸或样式，再用当前指纹保存：
+
+```bash
+openyida print-template inspect <appType> <formUuid> <templateId> --out before.json --json
+openyida print-template build <appType> <formUuid> --config quotation-document.json --json
+openyida print-template save <appType> <formUuid> <templateId> --config quotation-document.json --expected-hash <当前configHash> --json
+```
+
+save 全量替换正文。平台已手动编辑或没有源配置时，以 inspect 快照为准，将 content 中 termContents、termJsonAttr、dictionaryList 三件套导出为 native.json，再编辑并保存；不要用旧 document 覆盖新的人工排版。只改名称/说明/文件名前缀走 settings，不重建正文。
+
+## 复制变体与恢复
+
+比较标准版、简洁版、带扫码版时，copy 原模板取得新编号，在新编号上 inspect/save。使用不同字号、字段密度、明细列和签字区，避免只是换标题。不要覆盖用户的原参考模板。
+
+保存后的回执带有 backupPath。恢复时使用同目标的备份，加当前 inspect 指纹执行 restore；恢复正文后再回读。copy 的源指纹不能当作新目标的 save 指纹。
+
+## 完成判断
+
+- 仅编译通过：配置可用，模板尚未保存。
+- 创建并正文回读通过：新资源已保存，可以给出编辑链接。
+- 创建后保存失败：返回的 createdTemplateId 仍可能存在；读取该编号修复，不自动重复创建、删除或重发保存。
+- 修改通过：核对目标编号、正文和未计划修改的元信息；可通过备份恢复。
+- 请求 PDF 后按 fileId 查 FINISH，再查看文件内容、分页、中文、明细、签字位置及码值；没有真实审批历史、附件图片、设备打印等对应证据时单独说明。
+
+每个真实演示记录用途、模板编号、源配置、写入/回读结果与 PDF 验收状态。示例数量不等于所有行业或所有原生编辑器功能已验收。

package/yida-skills/skills-index.json

@@ -3,6 +3,19 @@
   "source": "openyida",
   "entry": "openyida",
   "skills": [
+    {
+      "name": "yida-print-template",
+      "path": "skills/yida-print-template/SKILL.md",
+      "display_name": "原生打印模板",
+      "description": "管理原生富文本打印模板，按真实字段生成订单、报价、交接、凭证、审批、扫码场景；新建、修改、复制、备份恢复与请求PDF。",
+      "category": "yida-skills/form",
+      "tags": ["打印模板", "打印模版", "打印设置", "订单打印", "报价单", "审批单", "打印二维码", "打印条形码", "数据详情打印"],
+      "aliases": ["单据打印", "自定义打印", "print-template"],
+      "positive_signals": ["配置打印模板", "做订单打印单据", "报价单打印", "打印模板编辑器", "复制恢复打印模板", "打印模板配置二维码和条形码", "新建不同场景的打印模板", "修改已有打印模板", "打印这条数据", "打印这个数据详情页", "按详情页链接生成PDF"],
+      "negative_signals": ["Word模板组件", "叮当打印", "浏览器window.print", "物理打印机"],
+      "command_ids": ["print-template", "sample"],
+      "requires_login": true
+    },
     {
       "name": "yida-custom-button",
       "path": "skills/yida-custom-button/SKILL.md",
@@ -40,7 +53,7 @@
       "name": "yida-cool-card",
       "path": "skills/yida-cool-card/SKILL.md",
       "display_name": "宜搭原生酷卡片",
-      "description": "仅在用户明确要求宜搭原生酷卡片（交互卡片、置顶卡片），或继续该上下文时使用。支持创建、读取、查询模板、导出配置和样式设计。样式限于钉钉原生组件，不能运行任意 HTML/CSS/React；超出能力时说明限制并提供替代方案。返回官方编辑器链接，由用户配置保存；CLI 不保存、发布或发送。原生数据卡片、Canvas 展示卡片及泛称卡片不触发。",
+      "description": "仅在用户明确要求宜搭原生酷卡片（交互卡片、置顶卡片），或继续该上下文时使用。集团版不支持酷卡片搭建，先核对认证环境。提供创建、读取、查询模板、导出配置和样式设计。样式限于钉钉原生组件，不能运行任意 HTML/CSS/React；超出能力时说明限制并提供替代方案。返回官方编辑器链接，由用户配置保存；CLI 不保存、发布或发送。原生数据卡片、Canvas 展示卡片及泛称卡片不触发。",
       "category": "yida-skills/integration",
       "tags": [
         "宜搭原生酷卡片",