weaver-work-cli 0.1.42 → 0.1.44

package/skills/weaver-e10-reception-flow/SKILL.md

@@ -0,0 +1,173 @@
+---
+name: weaver-e10-reception-flow
+display_name: 客户参观接待流程助手
+display_name_en: E10 Customer Reception Flow Assistant
+description: "客户来访接待 / 客户参观 / 客户到访 / 接待流程 / 客户接待行程单：泛微客户参观接待全流程助手。从原话抽取客户/人数/日期/参观类型/陪同/需求/后勤保障（接待细节），只补缺口；生成客户版《客户接待行程单》docx 与内部版《接待交流参考文档》md；打开接待流程填单页并预填字段，停在发起节点由用户提交。"
+description_zh: "客户来访接待 / 客户参观 / 客户到访 / 接待流程全流程助手（文件传参，不踩转义）：缺项才出面板（客户需求 + 接待细节，总屏数 ≤2）→ 检索同业案例与内部专家 → 生成客户版《客户接待行程单》docx 与内部版《接待交流参考文档》md，两份附件自动挂到接待流程填单页，停在发起节点由用户提交。"
+description_en: "E10 customer reception flow assistant: extracts customer, headcount, date, visit type, escorts, requirement and logistics from the user's own words, asks only for the gaps with at most two panels, enriches the internal brief with retrieved peer cases and in-house experts, renders the customer-facing itinerary docx and the internal reference md, uploads both as attachments, and opens the pre-filled request form for the user to submit."
+version: 6.4.0
+author: 泛微网络科技股份有限公司
+agent_created: true
+requires:
+  bins: ["weaver-work-cli"]
+cliHelp: "weaver-work-cli reception --help"
+---
+
+**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../weaver-e10-shared/SKILL.md`](../weaver-e10-shared/SKILL.md)，其中包含安装、E10 认证、JSON 输出和高风险写入规则。若共享规则不存在、CLI 未安装或读取失败，说明本技能的必需依赖缺失，必须调用宿主提供的提问/确认弹框，向用户说明必须补齐 `weaver-work-cli` 与共享 skill `weaver-e10-shared`（不补齐本技能无法执行）及补齐计划，并把下面两条待执行命令原样完整展示在确认信息中；Agent 不能在未确认时自行安装。用户明确确认后，Agent 必须直接代为按顺序执行且每条仅执行一次，不得要求或引导用户手动执行：① 缺 CLI 时执行 `npm install -g weaver-work-cli`；② 再执行 `weaver-work-cli skills install shared --target-dir <SKILLS_ROOT>` 装回共享 skill，`<SKILLS_ROOT>` 取本 SKILL.md 所在目录的上一级绝对目录（即与本技能同级的 skills 根目录），不要省略 `--target-dir`——省略会装进默认目录，导致本技能依然读不到共享规则。命令均成功后重新读取共享规则；仍读不到就停止并把结果报告用户，不得凭猜测继续。**
+**`--is-connector` 判据**：用户明确使用连接器、或上下文要求用连接器完成任务 → 传 `true`；本次任务或上下文直接选择单独技能 → 不传；用户没有明确说明时，按**正在运行的这份 Skill 是哪一级**定——**用户级（条目标 `(user)`）不传，连接器级（标 `(connector)`）传**（同名 Skill 只会运行用户级那一份）。传 `true` 时不要再写 `--profile` / `--base-url`。完整规则见 [`../weaver-e10-shared/SKILL.md`](../weaver-e10-shared/SKILL.md)。
+
+> 读共享规则时，本链路**只需要**其中三块：XiaoE 登录与凭据（`references/e10-auth-and-session.md`）、JSON 输出契约（`references/json-output-contract.md`）、高风险写入（`references/high-risk-write.md`）。安装、连接器、OAuth 防挂起本次用不到，不必展开。
+
+# 客户参观接待流程助手
+
+**ask → 一次面板 →（案例 + 专家检索）→ doc → render**，**全程零写请求**。
+
+## 1 · 依赖与启动
+
+`reception` 已内置在 `weaver-work-cli` 里；本技能包只提供字段快照、`render.py`、行程单模板。
+`$SD` = 本 SKILL.md 所在目录（部署路径带 hash，每轮重新确认，别复用旧路径）。
+
+**技能目录就这三样，不要 `ls` 去确认结构**（列目录 + 输出被截断要花掉 8~12 秒）：
+
+```
+$SD/data/fields-snapshot.json        ← doc 的 --snapshot
+$SD/scripts/render.py                ← doc 自动从 --snapshot 反推，不用传
+$SD/assets/行程单模板-泛微.docx        ← 同上
+```
+
+共享规则 `../weaver-e10-shared/SKILL.md` 是**相对本 SKILL.md 所在目录**解析，不是相对当前工作目录。
+本链路**零写请求**，shared 里真正用到的只有「E10 会话由 CLI 内部管理」和「JSON 输出契约」两条，下文已覆盖。
+**读不到 shared 不要中断、不要换路径重试**，按本文件继续执行即可——为它反复试错只会白花时间。
+
+**一律文件传参**：`--known-file` / `--answers-file`。内联 JSON 会被 shell 吃引号。文件带 BOM 无所谓，CLI 解析前会自动去掉。
+
+**落文件与调用合并成一条命令**。拆成两次（先 write_file 再 terminal）会多付一次工具往返的固定开销，
+比 CLI 本身慢一个数量级：
+
+```bash
+# macOS/Linux
+printf '%s' '<known.json 内容>' > known.json && weaver-work-cli reception ask --known-file known.json
+# 面板答完后：doc-render 一次完成「出件 + 传附件 + 拼填单参数」，不要拆成 doc + render 两次
+weaver-work-cli reception doc-render --run-id <id> --answers-file answers.json \
+                                     --snapshot "$SD/data/fields-snapshot.json" [--cases-file cases.json]
+```
+
+```powershell
+# Windows PowerShell 5.1（System32 自带版本）：-Encoding UTF8 会带 BOM，CLI 会自动去掉，不需要特殊处理
+Set-Content -Path known.json -Value '<known.json 内容>' -Encoding UTF8; weaver-work-cli reception ask --known-file known.json
+weaver-work-cli reception doc-render --run-id <id> --answers-file answers.json --snapshot "$SD\data\fields-snapshot.json"
+```
+
+> ⚠️ **不要用 `-Encoding utf8NoBOM`**：那是 PowerShell 7 的参数，5.1 不认，会直接报错、白花一轮。
+> 也不要为了"不带 BOM"去写 `[System.IO.File]::WriteAllText` 那套 .NET 调用，没必要。
+
+> `--snapshot` 只在 `doc` 传一次，`render` 复用 run 里的路径；只有报 `SNAPSHOT_MISSING` 才补传。
+> **不要事先探测命令是否存在**：直接跑 `ask`。只为确认 `reception` 在不在而先跑一次
+> `commands list` 或 `--help`，等于白花一次工具往返（实测 8~12 秒）。
+> 真报 `command not found` 再按 CRITICAL 段处理。
+> **`--user` 是陪同人员，不是当前操作人**。用户说的「由 XX 负责对接」要写进 `known.escorts`——
+> `escorts` 优先级高于 `--user`，否则主联络人会被操作人顶掉。
+
+## 2 · 主流程
+
+1. **一条命令完成「写 `known.json` + `ask`」** → `data.panels[]` + `data.runId`。客户名、人名直接传中文，不查 ID。**不要先说「我先确认一下 CLI」**，直接调。
+2. **`ask_user(panels)` 只调一次**。用户少答的进待办，不追问第二轮。
+3. **案例 + 专家检索**（客户名一确定就发起，可与面板等待并行）
+   - 检索词 = 客户名 + 客户需求（取 `customer_need` 选中值；选「暂未确定」只用客户名）
+   - 两次：同业案例、内部专家，**各取 5 条**即够，不要 10 条
+   - 结果写同一个 `cases.json`：`{query, note, cases:[{title,relevance,date}], expertsQuery, expertsNote, experts:[{name,dept,relevance}]}`
+   - 仅工具缺失/报错/空结果才跳过，且要在 `--answers` 带 `"fields":{"todo":["…未命中（原因）"]}`
+4. **写 `answers.json` → `doc-render`**（一次完成出件、传附件、拼参数）→ `data.files` + `data.attachments` + `data.browsertool`
+   - 报 `RUN_NOT_FOUND` 不要重跑 ask：带 `--known-file` 重跑本条，CLI 现场重建 run，一次搞定
+   - 报 `unknown command` 说明这台机器的 CLI 是旧版，回退 `doc` + `render` 两步，其余不变
+5. **按末尾「交付格式」五段输出**：先贴 `data.internalDoc.content` 全文，再写流程确认与待办，最后接 `data.browsertool`
+   - 宿主若明确支持 `data.browsertoolRef`（`<browsertool-file path="…" />`），只输出那一行，省掉 2KB 生成
+
+| 返回 | 判读 |
+|---|---|
+| `data.panels` | 直接作 `ask_user` 的 pickerList，不重组、不增删 |
+| `data.known.contactFallback` | 恒为空：兜底改在 `render` 阶段做（`ask` 不出网），不必据此判断 |
+| `data.attachments` | 两份 `[{fileid,name,kind}]`，`render` 自动拼挂载字段 |
+| `data.todos` | 交付待办，原样透出，不二次组织 |
+| `warnings` 含「未取得会话」（`doc` 阶段） | 附件传不上，按本地文件交付 |
+
+## 3 · 抽取与面板
+
+7 项由模型抽取，CLI 不重做。只取明确说出的，模糊不猜。
+
+| # | 项 | 线索 | 不唯一时 |
+|---|---|---|---|
+| 1 | 客户 | 「XX 来访/到访/参观/交流」+ 主体词 | 简称也直接传，不追问全称 |
+| 2 | 人数 | 数字 + 人/位/名 | 并入第 7 项 |
+| 3 | 参观日期 | 今天/明天/后天/周X/X月X日 | 换算 `yyyy-MM-dd` |
+| 4 | 参观类型 | 总部 → 参观上海总部；标杆/案例 → 参观典型客户 | 出面板 |
+| 5 | 陪同/对接人 | 陪同/随行/**对接人是** + 姓名；顺带出现的 11 位手机号一并回填 | 对接人写 `known.escorts`、陪同写 `known.companions`，中文名直接传；未提则留空，系统用登录人兜底，**不出屏** |
+| 6 | 客户需求 | 交流/演示/调研 + 主题 | 出面板 |
+| 7 | 接待细节 | 人数/会议室/接送/用餐/住宿/伴手礼/接待人手机 | **1 个面板一次问全** |
+
+**面板铁律**：`panels` 原样传 `ask_user`，**不生成、不改写、不拆屏**；屏数 = `panels.length`，**≤2**（客户需求 + 接待细节，手机号并入不单独出屏）。
+`title` 严格单行、超长必被截断，不得改写或追加说明；`placeholder` 是固定字段清单，不得改写；接待细节**不给选项、一律手输**。
+取值口径（会议室/接送/用餐/住宿/伴手礼枚举）与引导话术见 `references/guide.md`。
+
+## 4 · 数据与建单口径
+
+**议程**：公司参观 09:30-10:15 / 方案介绍 10:15-11:30 / 讨论交流 11:30-12:00，`agendaStart` 可改起点。用餐、接送、住宿、返程**不进时间表**。
+**联系方式**：只写 11 位手机号，来源仅限用户手填；未填只写姓名。
+**会议室**：只有总部 129/130/131，禁止「总部会议室」这类笼统说法。
+**必填不追问**：客户性质/项目金额/带队人与名单/是否高层，没说的一律进待办。
+
+建单（BROWSER_FILL）——**零写请求**：`doc` 只上传附件，**不落库、不提交**，页面由宿主打开、用户自己点提交。
+
+- 客户名传中文原名，参与人员传中文姓名（`,` 分隔）；没填陪同人时 CLI 用登录人 employeeid 兜底，**不要自己编 ID**。
+- 空值字段整个省略，不补空串；`fieldAssignKeys` 必须与 `customParams` 同源，**不手改**。
+- 明细 7 列由 CLI 按快照列序拼 `;`，**不手拼、不换分隔符**。
+- 附件两份（docx + md）由 `render` 拼进挂载字段；拿不到 fileid 就留空，不编造。
+
+## 5 · 约束与红线
+
+**必须做**
+
+1. `panels` 只能原样来自 `ask` 回包，`ask_user` 只调一次。
+2. 填单指令：默认整段输出 `data.browsertool`，不包代码块、不改写、不解析；宿主明确支持文件引用时改输出 `data.browsertoolRef` 一行。
+3. 案例与专家只进内部 md，**绝不进对外行程单**；`doc` 之前必须完成检索。
+4. `ask` 之后立刻记住 `--known` 与 `answers`，`RUN_NOT_FOUND` 靠它们免重跑。
+5. 附件 fileid 只能来自 `doc` 回包。
+
+**禁止做**
+
+6. 自拼 `customParams` / `fieldAssignKeys` / 明细分隔符。
+7. 调 `createForm` / `createRequest`，或代用户点提交。
+8. 用 `workflow` 顶替不可用的 `reception`（那条路会真写库并提交）。
+9. 编造人员、场地、车牌、价格、房间、金额、案例。
+10. 用人员/联系方式接口去取手机号——只能来自用户手填。
+11. 二轮追问、「确认一下」式复述、面板超过 2 屏。
+12. 在对外行程单里出现用餐、接送、住宿、返程。
+13. 内部参考文档正文**只从 `internalDoc.content` 取**，不要 `cat`/`read` 产物文件——md 那份读一遍等于白多一次工具往返，docx 是二进制更读不出东西。
+
+## 6 · 失败与恢复
+
+| 现象 | 动作 |
+|---|---|
+| `*_INVALID` | JSON 非法：看 `error.details.preview` / `hasBom`，修 JSON 本身，**不换传参方式** |
+| `*_REQUIRED` | 确实没传：改用 `--xxx-file` |
+| `*_FILE_UNREADABLE` | 路径错或无权限：看 `error.details.path` |
+| `SNAPSHOT_MISSING` | `doc` 补 `--snapshot`；`render` 也报就同样补（run 被重建过才会缺） |
+| `RENDER_PY_MISSING` / `NO_PYTHON_DOCX` | 前者 `--snapshot` 没给对；后者 `pip install python-docx`，离线只交付 md |
+| `RUN_NOT_FOUND` | 带 `--known-file` 重跑 `doc`，用回包新 `runId` 继续 `render`，**不重跑 ask** |
+| 附件上传失败 | 看 `data.uploadDiagnostics` 的 `error`：`upload_auth_expired` = 会话过期（响应片段会写「token 为空或失效」）；`upload_response_html` = 返回了登录页；`upload_identity_mismatch` = 会话用户与服务端认到的不一致；`upload_business_failed` = 服务端明确拒绝（消息在 `error` 里）。**都不重跑 `doc`**，按本地文件交付、页面手动加 |
+| `detailRowCount: 0` | 传 `schedule` 或 `visitDate`，不带空明细 |
+| browsertool 没弹页面 | 宿主不支持该形态，如实告知用户，**不换链路** |
+| 宿主不认 `browsertoolRef` | 回退整段输出 `data.browsertool`（回包里一定有），**不重跑** `doc-render` |
+| `warnings` 含「未取得会话」 | 附件不上传，按本地文件交付并说明 |
+| 用户没填手机号 | 不是故障：只写姓名 |
+
+> run 落在 `<CLI state>/reception/runs/`，正常持久；只有整目录被沙箱清掉才会 `RUN_NOT_FOUND`。
+> **交付格式（五段，一次成稿，段间不插解释）**：
+> 1. **内部参考文档全文**：把 `data.internalDoc.content` **逐字原样**贴出——Markdown 原样、不加代码块围栏、不改写、不摘要、不合并章节、不省略表格；贴完加一行 `---` 与下文分隔。`internalDoc` 为 `null` 才跳过本段。
+> 2. **流程已就绪**：固定一句「接待流程已准备好，填单页已预填，停在发起节点等您确认提交。」
+> 3. **本次已确认**：只列用户确认过的值，逐条一行，不解释。
+> 4. **待办清单**：直接透出 `data.todos`，一次性列全，此后不再追问。
+> 5. **交付物 + 填单页**：docx 在前、md 在后，注明「两份已挂到附件字段、已预填、未提交，请在页面确认后提交」，随后接 `browsertool` 整段。
+> **按需查阅**：`references/guide.md`（抽取线索、检索口径、面板取值）、`references/browsertool.md`（结构排障）、`references/fields-snapshot.md`（字段对照）、`references/env-pitfalls.md`（环境踩坑）。
+
+> 维护注记：文档与示例禁止写真实客户名称、真实员工姓名，一律用占位名。

package/skills/weaver-e10-reception-flow/data/fields-snapshot.json

@@ -0,0 +1,213 @@
+{
+  "schemaVersion": 1,
+  "kind": "reception-fields-snapshot",
+  "capturedAt": "2026-10-28T14:26:00+08:00",
+  "source": "e10.mjs formctx 真实返回 + SCHEDULE_DETAIL 规格",
+  "env": {
+    "baseUrl": "https://www.e-cology.com.cn",
+    "host": "www.e-cology.com.cn",
+    "profile": "e-cology"
+  },
+  "workflow": {
+    "name": "泛微客户参观接待流程",
+    "workflowId": "100003460000000737",
+    "formId": "100003669000000023",
+    "category": "销售管理"
+  },
+  "mainFieldCount": 10,
+  "fields": [
+    {
+      "id": "100003720000001122",
+      "name": "参观访问类型",
+      "componentKey": "Select",
+      "required": true,
+      "valueFormat": "option-name",
+      "options": [
+        "参观上海总部",
+        "参观典型客户",
+        "参观上海总部及典型客户"
+      ]
+    },
+    {
+      "id": "100003720000001124",
+      "name": "来访客户名称",
+      "componentKey": "Ebuilder",
+      "required": true,
+      "isBrowser": true,
+      "isMultiple": false,
+      "valueFormat": "{id,name}",
+      "note": "必须传对象，禁止 String() 强转；客户 id 需实时查询，不可硬编码"
+    },
+    {
+      "id": "100003720000001125",
+      "name": "客户到达日期",
+      "componentKey": "DateComponent",
+      "required": true,
+      "valueFormat": "yyyy-MM-dd"
+    },
+    {
+      "id": "100003720000001126",
+      "name": "客户参观日期",
+      "componentKey": "DateComponent",
+      "required": true,
+      "valueFormat": "yyyy-MM-dd"
+    },
+    {
+      "id": "100003720000001127",
+      "name": "客户性质",
+      "componentKey": "Select",
+      "required": true,
+      "valueFormat": "option-name",
+      "options": [
+        "国企",
+        "民企",
+        "外企",
+        "台企",
+        "政府事业单位"
+      ]
+    },
+    {
+      "id": "100003720000001128",
+      "name": "客户需求",
+      "componentKey": "TextArea",
+      "required": true,
+      "valueFormat": "text"
+    },
+    {
+      "id": "100003720000001129",
+      "name": "项目金额（万元）",
+      "componentKey": "NumberComponent",
+      "required": true,
+      "valueFormat": "number",
+      "note": "未给留空，禁止估算；单位标记「万元」是字段名的一部分"
+    },
+    {
+      "id": "100003720000001130",
+      "name": "泛微分支机构参与人员（主联络人，此人必须陪客户一同参观）",
+      "componentKey": "Employee",
+      "required": true,
+      "isBrowser": true,
+      "isMultiple": true,
+      "valueFormat": "employee-id-array",
+      "note": "传人员 id 数组，不是 userid / cid"
+    },
+    {
+      "id": "100003720000001131",
+      "name": "是否需要高层参与",
+      "componentKey": "Select",
+      "required": true,
+      "valueFormat": "option-name",
+      "options": [
+        "是",
+        "否"
+      ]
+    },
+    {
+      "id": "100003720000001132",
+      "name": "客户参观接待行程单（由行政经理汇总后反馈）",
+      "componentKey": "FileComponent",
+      "required": true,
+      "valueFormat": "file",
+      "doNotWrite": true,
+      "note": "表单上的文件字段，建单时不写；行程单统一挂到 attachmentMountField"
+    }
+  ],
+  "details": {
+    "name": "日程明细",
+    "subFormId": "100003690000000143",
+    "dataKey": "formtable_main_23_dt2",
+    "note": "details 的键必须是 subFormId；dataKey 是库表名，不能当入参键",
+    "switch": {
+      "fieldId": "100003720000014930",
+      "on": "启用",
+      "codes": {
+        "启用": "1",
+        "关闭": "0"
+      }
+    },
+    "columns": {
+      "date": "100003720000014936",
+      "time": "100003720000014937",
+      "item": "100003720000014938",
+      "place": "100003720000014939",
+      "person": "100003720000014940",
+      "activity": "100003720000014941",
+      "remark": "100003720000014942"
+    }
+  },
+  "attachmentMountField": {
+    "fieldId": "100003720000001141",
+    "valueFormat": "{optionId,content,type}",
+    "note": "唯一允许挂附件的字段；不在 formctx 返回的 10 个字段中属正常"
+  },
+  "mustBeRealtime": [
+    "continuation",
+    "FileComponent.authSignatureStr / authStr",
+    "客户 id",
+    "人员 id",
+    "附件 fileid"
+  ],
+  "invalidation": [
+    "主表字段数量 != 10",
+    "workflowId != 100003460000000737",
+    "formId != 100003669000000023",
+    "details.subFormId != 100003690000000143",
+    "details.dataKey != formtable_main_23_dt2",
+    "host != www.e-cology.com.cn",
+    "任一字段名称与快照不符",
+    "Select 选项数量与快照不符"
+  ],
+  "optionCodes": {
+    "参观访问类型": {
+      "参观上海总部": "0",
+      "参观典型客户": "1",
+      "参观上海总部及典型客户": "2"
+    },
+    "客户性质": {
+      "国企": "0",
+      "民企": "1",
+      "外企": "2",
+      "台企": "3",
+      "政府事业单位": "4"
+    },
+    "是否需要高层参与": {
+      "是": "0",
+      "否": "1"
+    }
+  },
+  "browsertool": {
+    "toolId": "fill_form",
+    "version": 1,
+    "callId": "call_001",
+    "type": "e10",
+    "compName": "ui.CorsComponent",
+    "routerType": "MemoryRouter",
+    "app": "@weapp/workflow",
+    "compNamePc": "Comp.WffpRoute",
+    "compNameMobile": "Comp.MWffpRoute",
+    "createPath": "/flowpage/create/{workflowId}",
+    "srcTemplate": "{base}/sp/workflow/flowpage/create/{workflowId}?workflowId={workflowId}&isCreate=1",
+    "sdkRenderType": "drawer",
+    "sdkRenderTypes": [
+      "inline",
+      "popup",
+      "drawer"
+    ],
+    "sdkRenderNote": "side panel = drawer；不传则用宿主默认（实测为内嵌）"
+  },
+  "customParamsRule": {
+    "multiSeparator": ",",
+    "rowSeparator": ";",
+    "emptyValue": "省略该字段，且不出现在 fieldAssignKeys",
+    "scalarPick": [
+      "id",
+      "optionId",
+      "fileId",
+      "fileid",
+      "fid",
+      "value"
+    ],
+    "detailSort": "按 dataIndex 升序",
+    "source": "weaver-work-cli release: src/shortcuts/workflow/operations/form.ts (xiaoEUrlParamValue / renderXiaoEFillFormMarkdown)"
+  }
+}

package/skills/weaver-e10-reception-flow/references/browsertool.md

@@ -0,0 +1,68 @@
+# browsertool 结构与口径
+
+> 由 `weaver-work-cli reception render` 直接产出整段文本，**模型只负责原样输出**。本文件是排障与改动时的依据。
+> 骨架逐字段对齐 `weaver-work-cli release: src/shortcuts/workflow/operations/form.ts`（`renderXiaoEFillFormMarkdown`），打开形态对齐小e 官方《browsertool 渲染说明》。
+>
+> **三种功能别混**：`fill_form` + `data` = iframe 填单；`fill_form` + `sdkOptions` = E10 组件化渲染（**本技能用这个**）；`open_web` = 打开外部网页并与之通信（不走 E10 表单，也不带字段预填）。
+
+## 一、输出形态
+
+```
+<browsertool>
+{ ...JSON，2 空格缩进... }
+</browsertool>
+```
+
+- **不包代码块**（不要三反引号），**不加前后说明**，**不解析、不改写**。
+- 宿主读到这段标签后打开新建页并把 `customParams` 带进去；页面由用户自己提交。
+
+## 二、JSON 结构
+
+| 路径 | 值 | 来源 |
+|---|---|---|
+| `version` | `1` | 固定 |
+| `callId` | `call_001` | 固定 |
+| `toolId` | `fill_form` | 固定 |
+| `arguments.type` | `e10` | 固定 |
+| `arguments.title` | 工作流名称 | 快照 `workflow.name` |
+| `arguments.src` | `{base}/sp/workflow/flowpage/create/{id}?workflowId={id}&isCreate=1` | 会话 baseUrl + 快照 workflowId |
+| `arguments.sdkRenderType` | `drawer`（默认，右侧抽屉）/ `popup` / `inline` | 快照 `browsertool.sdkRenderType`；`--sdk-render` 可覆盖 |
+| `routerProps_pc.initialEntries` | `["/flowpage/create/{id}"]` | 快照 workflowId |
+| `routerProps_mobile.initialEntries` | 同上 | 同上 |
+| `params_pc` | `{app:"@weapp/workflow", compName:"Comp.WffpRoute", noMDialog:true}` | 固定 |
+| `params_mobile` | 同上 + `noMDialog:true`，compName 为 `Comp.MWffpRoute` | 固定 |
+| `params.customParams` | `{字段id: 值, …, fieldAssignKeys:"id1,id2,…"}` | `render` 计算 |
+
+## 三、customParams 口径（与 CLI 源码一致）
+
+| 规则 | 说明 |
+|---|---|
+| 键用**字段 id** | 不是字段名、不是数据 key |
+| 同字段多值 | 用 `,`（如人员 `1001,1002`） |
+| 明细多行 | 用 `;`（如 `09:30;10:15;11:30`），按行号升序 |
+| 标量对象取值优先级 | `id > optionId > fileId > fileid > fid > value`（附件取 fileid，选项取编码） |
+| **空值字段** | **整个省略，且不出现在 `fieldAssignKeys`**（不要补空串） |
+| `fieldAssignKeys` | `customParams` 里所有字段 id 按首次出现顺序用 `,` 连接，必须与值同源 |
+
+## 四、明细列顺序
+
+| 语义 | 字段 ID |
+|---|---|
+| 日期 | `100003720000014936` |
+| 时间 | `100003720000014937` |
+| 环节 | `100003720000014938` |
+| 地点 | `100003720000014939` |
+| 人员 | `100003720000014940` |
+| 活动内容 | `100003720000014941` |
+| 备注 | `100003720000014942` |
+
+开关 `100003720000014930` 传 `1`（启用）。备注为空时该列整个省略，属正常。
+
+## 五、排障
+
+| 现象 | 原因 | 处理 |
+|---|---|---|
+| 页面没弹出来 | 宿主不执行该标签 | 切 `prepare/build/submit` 兜底链路 |
+| 页面开了但字段没值 | `customParams` 键/值格式不对 | 对比本文件与 `render` 输出；不要手改 |
+| 明细错位 | 列序或分隔符被改 | 用 `render` 输出，不手拼 |
+| 附件丢了 | fileid 未回填或字段被写成空串 | 先 `doc` 再 `render`；空值就省略 |

package/skills/weaver-e10-reception-flow/references/env-pitfalls.md

@@ -0,0 +1,51 @@
+# 环境踩坑与失败处理（按需读）
+
+> 只在 **SKILL.md §8** 的清单对不上时才读本文；正常链路不需要。
+> 本文只讲「`weaver-work-cli reception` + 本技能包资产」这套现行链路，**不含**任何独立 CLI 或旧脚本口径。
+
+## 一、鉴权与状态
+
+- **唯一来源是 `weaver-work-cli`**。本技能不自建登录、不读任何认证文件、不落会话缓存。
+- **不要手动跑任何 `auth` 命令**：登录态由 CLI 统一管理，多跑一轮只是白等。
+- 未登录不阻断：`ask` / `doc` 照常出结果，`warnings` 里会有「未取得 E10 会话」，此时附件不上传，按本地文件交付。
+- 状态目录：`<CLI state 根>/reception/`（Windows 默认 `~/.weaver-work-cli/reception/`），
+  里面是 `runs/`（run 状态）、`python.json`（python 探测缓存）、`out/`（默认产物目录）。
+  跨 `run_command` 可能被沙箱清掉，这是 `RUN_NOT_FOUND` 的唯一来源，按 §10 现场重建即可。
+
+## 二、退出码
+
+| 退出码 | 含义 | 处理 |
+|---|---|---|
+| 0 | 成功 | — |
+| 1 | 业务失败（渲染失败、run 丢失） | 看 `error.subtype` 与 `error.details.hint` |
+| 2 | 参数错误（`*_REQUIRED` / `*_INVALID` / `RUN_ID_MISSING`） | 改参数重跑 |
+| 3 | 环境缺失（未登录且必须登录、快照/渲染脚本找不到） | 按 `error.subtype` 补参数或补环境 |
+
+## 三、已实测的坑
+
+| 坑 | 现象 | 规避 |
+|---|---|---|
+| **同名技能冲突** | 按 `name` 读报 `skill_identity_conflict`，或**行为时新时旧** | 属环境问题：**交付前清理宿主里重复的同名技能**（尤其早期 2.x/4.x/5.x 副本）。文档与脚本都不做安装 ID 兜底 |
+| `run_command` 绑定 `skill_name` 报未加载 | `skill_not_available` | 按 `name` 重读一次主文档后继续；**禁止**用 `skill_list` 兜底（上万 token 白烧），**禁止**改用安装 ID |
+| `RENDER_PY_MISSING` | `doc` 报找不到 render.py | CLI 按 `--snapshot` 反推 `<技能目录>/scripts/render.py`。确认传了 `--snapshot "$SD/data/fields-snapshot.json"`；实在不行用 `--render-py` 直指 |
+| 模板 444 只读位 | `shutil.copy` 后 `d.save()` 抛 `PermissionError` | `render.py` 内置 `copyfile` + `chmod 644`，不要手工渲染 |
+| 缺 python-docx | `NO_PYTHON_DOCX` | `pip install python-docx`；离线装不上则只交付 md 并说明 |
+| 技能部署路径带 hash | 上一轮 `/workspace/skills/att-6dae…`，下一轮变成 `att-b827…` | 每轮重新确认 `$SD`（本 SKILL.md 所在目录），不要跨轮次复用旧绝对路径 |
+| 上传失败但文件已生成 | `attachments: []` + `warnings` 里带原因 | **不是失败**：按本地文件交付，不重跑 `doc` |
+| 沙箱只有 0.25 核 | spawn 一次 python 约 180~600ms | 少 spawn：`ask` 一条命令做完检索；python 探测结果已按 7 天缓存 |
+| 写盘 `Permission denied` | 目标文件 444 只读位 | 换 `--out-dir`；不要在技能目录里写产物 |
+
+## 四、完整失败矩阵
+
+| 依赖 | 缺失表现 | 处理 |
+|---|---|---|
+| `weaver-work-cli` 不可用 | `command not found` / `ENOENT` | 报「流程智能助手未接入」，交付本地文件 + 说明，不硬试。注意：能回 `error.subtype` 就说明 CLI 可用 |
+| 登录态失效 | 401 / 附件不传 | 本链路零写请求；附件传不上就按本地文件交付，`auth` 交给 CLI 自己处理 |
+| 快照缺失 | `SNAPSHOT_MISSING` | 用 `--snapshot "$SD/data/fields-snapshot.json"` |
+| 快照与线上表单不一致 | `snapshot.match:false` | 看 `references/fields-snapshot.md` 对照；必要时更新快照并发 CLI 技能包版本 |
+| 内置模板缺失 | `render.py` 返回「内置模板缺失: assets/行程单模板-泛微.docx」 | 技能资源不完整，重新部署整个技能目录，不临时编版式 |
+
+## 五、判定假阴性（防误判）
+
+- 现象：报「`weaver-work-cli` 不可用」。
+- 先判定为**接口 / 权限问题**，不要直接判定「CLI 未安装」：`ask` 能回 `error.subtype` 就说明 CLI 可用，只有 `command not found` 才是真缺失。