feat: 结题报告初稿助手首版 v1.0.1（draft-closing-report-default）

assets/examples/README.md

@@ -0,0 +1,9 @@
+# 示例 JSON
+
+- `version-response.json`：`python main.py version` 成功时 stdout 单行对象的形状参考。
+- `skill-policy-snapshot.*.example.json`：Data Policy Snapshot 形状参考（见 `references/POLICY.md`）。
+- `skill-cell-presentation.example.json`：数据管理单元格呈现文档形状参考（见 `references/CELL_PRESENTATION.md`）。
+- `render-html.action.example.json`：HTML 报告「重新生成」Action 形状参考（固定 id `render-html`；见 `references/ACTIONS.md`）。
+- `lookup-action.example.json`：Action 内联 Lookup 形状参考（单选 + `multiple: true` 多选并列；跨表引用勿填编号；见 `references/ACTIONS.md`「跨表引用：Lookup」）。
+- `visible-when-action.example.json`：Action 参数字段条件显隐 `visibleWhen` 形状参考（互斥模式联动；见 `references/ACTIONS.md`「字段条件显隐」；≠ Policy L3）。
+- `replaces-create.action.example.json` / `replaces-update.action.example.json` / `replaces-delete.action.example.json` / `replaces-import.action.example.json`：数据管理默认按钮接管（`replaces`）形状参考；**import 时 UI 仍用宿主「导入数据」面板**，确认后调技能写库（见 `references/ACTIONS.md`「`replaces`」）。

assets/examples/lookup-action.example.json

@@ -0,0 +1,83 @@
+{
+  "_comment": "形状参考：Action 参数引用同库另一张表时用 Lookup。单选与多选同一 lookup 对象，多选只加 multiple:true。完整契约见 references/ACTIONS.md「跨表引用：Lookup」与 references/SCHEMA.md。",
+  "schemaVersion": 1,
+  "skill": "your-skill-slug",
+  "actions": [
+    {
+      "id": "send-with-template",
+      "label": "按模板发送（示例）",
+      "description": "演示内联 lookup 单选：从 message_templates 选模板；-- 表示自动挑选。",
+      "placements": ["toolbar"],
+      "executionProfile": "async",
+      "interaction": "form",
+      "bind": {
+        "tables": ["leads"]
+      },
+      "entrypoint": {
+        "type": "cli",
+        "command": "engage",
+        "args": ["--template-id", "{{templateId}}", "--content", "{{content}}"]
+      },
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "content": {
+            "type": "string",
+            "title": "正文",
+            "description": "填了就按这里发；留空则用下面的话术模板。",
+            "display_type": "textarea"
+          },
+          "templateId": {
+            "type": "number",
+            "title": "话术模板",
+            "description": "仅在正文留空时生效。选 -- = 自动挑选。",
+            "display_type": "lookup",
+            "lookup": {
+              "ref_table": "message_templates",
+              "value_column": "id",
+              "label_column": "name",
+              "extra_column": "channel",
+              "filter_column": "is_active",
+              "filter_value": 1
+            }
+          }
+        }
+      }
+    },
+    {
+      "id": "probe-with-engines",
+      "label": "按引擎抽检（多选示例）",
+      "description": "演示 lookup.multiple：从 engines 多选，提交为逗号分隔 id。",
+      "placements": ["toolbar"],
+      "executionProfile": "async",
+      "interaction": "form",
+      "bind": {
+        "tables": ["queries"]
+      },
+      "entrypoint": {
+        "type": "cli",
+        "command": "query",
+        "args": ["batch-probe", "--engine-ids", "{{engineIds}}"]
+      },
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "engineIds": {
+            "type": "string",
+            "title": "将使用的引擎",
+            "description": "可多选；提交值为逗号分隔编号，如 1,2。",
+            "display_type": "lookup",
+            "lookup": {
+              "ref_table": "engines",
+              "value_column": "id",
+              "label_column": "display_name",
+              "filter_column": "enabled",
+              "filter_value": 1,
+              "multiple": true
+            }
+          }
+        }
+      }
+    }
+  ]
+}

assets/examples/path-root-file-action.example.json

@@ -0,0 +1,36 @@
+{
+  "_comment": "形状参考：Action 表单 file/directory 用 pathRoot 指定原生对话框起始目录（相对技能数据根）。省略则宿主默认 {skill_data}/input。完整契约见 references/ACTIONS.md「本地路径选择与 pathRoot」。勿与宿主导入面板（replaces:import）混用本示例。",
+  "schemaVersion": 1,
+  "skill": "your-skill-slug",
+  "actions": [
+    {
+      "id": "import-pack",
+      "label": "导入数据包",
+      "description": "从本技能输入目录子文件夹选择 JSON 并写入业务表。",
+      "placements": ["toolbar", "agent"],
+      "executionProfile": "sync",
+      "interaction": "form",
+      "bind": { "tables": ["business_items"] },
+      "inputSchema": {
+        "type": "object",
+        "required": ["file"],
+        "properties": {
+          "file": {
+            "type": "string",
+            "title": "数据包文件",
+            "description": "请选择 input/数据包/ 下的 JSON。",
+            "format": "file",
+            "display_type": "file",
+            "pathRoot": "input/数据包"
+          }
+        }
+      },
+      "entrypoint": {
+        "type": "cli",
+        "command": "import-pack",
+        "args": ["--file", "{{file}}"]
+      },
+      "steps": [{ "when": "afterSuccess", "do": "reloadTable" }]
+    }
+  ]
+}

assets/examples/render-html.action.example.json

@@ -0,0 +1,28 @@
+{
+  "id": "render-html",
+  "label": "生成 HTML",
+  "description": "根据业务数据生成 HTML 报告，写入技能数据目录 html/（示例：请改 bind.tables / entrypoint）。",
+  "placements": [
+    "toolbar",
+    "skill-detail",
+    "agent"
+  ],
+  "executionProfile": "sync",
+  "interaction": "direct",
+  "bind": {
+    "tables": [
+      "your_source_table"
+    ]
+  },
+  "entrypoint": {
+    "type": "cli",
+    "command": "render-html",
+    "args": []
+  },
+  "steps": [
+    {
+      "when": "afterSuccess",
+      "do": "refreshCatalog"
+    }
+  ]
+}

assets/examples/replaces-create.action.example.json

@@ -0,0 +1,28 @@
+{
+  "id": "item-create",
+  "label": "新增记录",
+  "description": "新增业务记录并执行领域副作用（走技能 CLI，非宿主直写库）。",
+  "replaces": "create",
+  "placements": [],
+  "executionProfile": "sync",
+  "interaction": "form",
+  "bind": {
+    "tables": ["items"]
+  },
+  "hostEffects": {
+    "onSuccess": ["reloadTable"]
+  },
+  "inputSchema": {
+    "type": "object",
+    "required": ["name"],
+    "properties": {
+      "name": { "type": "string", "title": "名称" },
+      "note": { "type": "string", "title": "备注" }
+    }
+  },
+  "entrypoint": {
+    "type": "cli",
+    "command": "item",
+    "args": ["create", "--name", "{{name}}", "--note", "{{note}}"]
+  }
+}

assets/examples/replaces-delete.action.example.json

@@ -0,0 +1,33 @@
+{
+  "id": "item-delete",
+  "label": "删除记录",
+  "description": "删除业务记录并清理关联副作用。",
+  "replaces": "delete",
+  "placements": [],
+  "executionProfile": "sync",
+  "interaction": "confirm",
+  "confirmation": {
+    "message": "确定删除该记录？关联数据将一并清理。"
+  },
+  "bind": {
+    "tables": ["items"],
+    "inputMapping": {
+      "id": "$row.$pk"
+    }
+  },
+  "hostEffects": {
+    "onSuccess": ["reloadTable", "clearSelection"]
+  },
+  "inputSchema": {
+    "type": "object",
+    "required": ["id"],
+    "properties": {
+      "id": { "type": "number", "title": "编号", "readOnly": true }
+    }
+  },
+  "entrypoint": {
+    "type": "cli",
+    "command": "item",
+    "args": ["delete", "--id", "{{id}}"]
+  }
+}

assets/examples/replaces-import.action.example.json

@@ -0,0 +1,38 @@
+{
+  "id": "item-import",
+  "label": "导入记录",
+  "description": "由宿主「导入数据」面板调用：解析 Excel/CSV 并写入业务表（含领域校验与派生字段）。",
+  "replaces": "import",
+  "placements": [],
+  "executionProfile": "sync",
+  "interaction": "form",
+  "bind": {
+    "tables": ["items"]
+  },
+  "hostEffects": {
+    "onSuccess": ["reloadTable"]
+  },
+  "inputSchema": {
+    "type": "object",
+    "required": ["filePath"],
+    "properties": {
+      "filePath": {
+        "type": "string",
+        "title": "导入文件",
+        "description": "由宿主导入面板传入的 Excel/CSV 路径。",
+        "format": "file"
+      },
+      "onError": {
+        "type": "string",
+        "title": "导入规则（出错时）",
+        "enum": ["跳过该行，继续导入", "立即停止，不再导入后续行"],
+        "default": "跳过该行，继续导入"
+      }
+    }
+  },
+  "entrypoint": {
+    "type": "cli",
+    "command": "item",
+    "args": ["import", "--file", "{{filePath}}", "--on-error", "{{onError}}"]
+  }
+}

assets/examples/replaces-update.action.example.json

@@ -0,0 +1,34 @@
+{
+  "id": "item-update",
+  "label": "编辑记录",
+  "description": "编辑业务记录并重算派生字段。",
+  "replaces": "update",
+  "placements": [],
+  "executionProfile": "sync",
+  "interaction": "form",
+  "bind": {
+    "tables": ["items"],
+    "inputMapping": {
+      "id": "$row.$pk",
+      "name": "$row.name",
+      "note": "$row.note"
+    }
+  },
+  "hostEffects": {
+    "onSuccess": ["reloadTable"]
+  },
+  "inputSchema": {
+    "type": "object",
+    "required": ["id", "name"],
+    "properties": {
+      "id": { "type": "number", "title": "编号", "readOnly": true },
+      "name": { "type": "string", "title": "名称" },
+      "note": { "type": "string", "title": "备注" }
+    }
+  },
+  "entrypoint": {
+    "type": "cli",
+    "command": "item",
+    "args": ["update", "--id", "{{id}}", "--name", "{{name}}", "--note", "{{note}}"]
+  }
+}

assets/examples/selection-label-column.action.example.json

@@ -0,0 +1,38 @@
+{
+  "id": "process-selected",
+  "label": "处理勾选",
+  "description": "对勾选行执行业务处理。示例：声明 labelColumn，让确认弹层「已选择」摘要显示可读名称。",
+  "placements": ["toolbar", "batch"],
+  "executionProfile": "async",
+  "interaction": "confirm",
+  "confirmation": {
+    "message": "将按技能业务规则处理勾选记录（具体是否跳过某些状态由 CLI 决定）。"
+  },
+  "bind": {
+    "tables": ["business_items"],
+    "inputMapping": {
+      "ids": "$selection.ids"
+    },
+    "labelColumn": "display_name"
+  },
+  "inputSchema": {
+    "type": "object",
+    "required": ["ids"],
+    "properties": {
+      "ids": {
+        "type": "string",
+        "title": "编号列表",
+        "description": "逗号分隔主键；宿主会预填勾选行",
+        "readOnly": true
+      }
+    }
+  },
+  "entrypoint": {
+    "type": "cli",
+    "command": "process",
+    "args": ["--ids", "{{ids}}"]
+  },
+  "hostEffects": {
+    "onSuccess": ["reloadTable"]
+  }
+}

assets/examples/skill-cell-presentation.example.json

@@ -0,0 +1,29 @@
+{
+  "schemaVersion": 1,
+  "skill": "your-skill-slug",
+  "table": "business_records",
+  "rowKey": "id",
+  "generatedAt": "2026-08-10T06:00:00Z",
+  "cells": [
+    {
+      "rowId": "42",
+      "column": "qty",
+      "tone": "danger",
+      "message": "库存低于安全线",
+      "alert": true
+    },
+    {
+      "rowId": "42",
+      "column": "status",
+      "tone": "warning",
+      "message": "待审核"
+    },
+    {
+      "rowId": "99",
+      "column": "print_done_at",
+      "tone": "danger",
+      "message": "环节到期未填",
+      "alert": true
+    }
+  ]
+}

assets/examples/skill-policy-snapshot.allowlist.example.json

@@ -0,0 +1,13 @@
+{
+  "schemaVersion": 1,
+  "skill": "your-skill-slug",
+  "actor": {
+    "userId": "u1",
+    "displayName": "张三",
+    "roles": ["clerk"]
+  },
+  "actions": {
+    "mode": "allowlist",
+    "ids": ["whoami", "create-record", "sync-records"]
+  }
+}

assets/examples/skill-policy-snapshot.scope.example.json

@@ -0,0 +1,28 @@
+{
+  "schemaVersion": 1,
+  "skill": "your-skill-slug",
+  "actor": {
+    "userId": "u1"
+  },
+  "actions": {
+    "mode": "open"
+  },
+  "data": {
+    "tables": {
+      "orders": {
+        "rows": {
+          "mode": "scope",
+          "scope": {
+            "all": [
+              {
+                "field": "owner_user_id",
+                "op": "eq",
+                "valueFrom": "actor.userId"
+              }
+            ]
+          }
+        }
+      }
+    }
+  }
+}

assets/examples/version-response.json

@@ -0,0 +1,4 @@
+{
+  "version": "1.0.92",
+  "skill": "your-skill-slug"
+}

assets/examples/visible-when-action.example.json

@@ -0,0 +1,72 @@
+{
+  "_comment": "形状参考：互斥模式用 inputSchema.properties.*.visibleWhen 联动显隐，勿只靠 description 灰字。完整契约见 references/ACTIONS.md「字段条件显隐」。勿与 POLICY.md L3 行态 visibleWhen 混淆。",
+  "schemaVersion": 1,
+  "skill": "your-skill-slug",
+  "actions": [
+    {
+      "id": "scrape-links-demo",
+      "label": "采集链接（示例）",
+      "description": "演示按采集方式切换参数：关键词路径 vs 作者主页路径。",
+      "placements": ["toolbar"],
+      "executionProfile": "async",
+      "interaction": "form",
+      "bind": {
+        "tables": ["demo_items"]
+      },
+      "confirmation": {
+        "message": "将按所选方式采集链接（示例确认文案）。是否继续？"
+      },
+      "entrypoint": {
+        "type": "cli",
+        "command": "run",
+        "args": [
+          "--collect-mode",
+          "{{collectMode}}",
+          "--keyword",
+          "{{keyword}}",
+          "--author-url",
+          "{{authorUrl}}",
+          "--max-count",
+          "{{maxCount}}"
+        ]
+      },
+      "inputSchema": {
+        "type": "object",
+        "required": ["collectMode"],
+        "properties": {
+          "collectMode": {
+            "type": "string",
+            "title": "采集方式",
+            "description": "先选方式，下方只出现对应参数。",
+            "enum": ["按关键词采集", "按作者主页采集"],
+            "default": "按关键词采集"
+          },
+          "keyword": {
+            "type": "string",
+            "title": "关键词",
+            "description": "例如 rpa。",
+            "visibleWhen": {
+              "field": "collectMode",
+              "equals": "按关键词采集"
+            }
+          },
+          "authorUrl": {
+            "type": "string",
+            "title": "作者主页链接",
+            "description": "例如 https://example.com/author/...",
+            "display_type": "url",
+            "visibleWhen": {
+              "collectMode": "按作者主页采集"
+            }
+          },
+          "maxCount": {
+            "type": "number",
+            "title": "数量上限",
+            "default": 50,
+            "minimum": 1
+          }
+        }
+      }
+    }
+  ]
+}