weaver-e10-builder 1.5.12 → 1.5.14

package/skill-docs/references/code-block/ref-recipes.md

@@ -0,0 +1,164 @@
+# 按效果查代码模式
+
+本页覆盖原案例中的独立做法。字段 Key、接口和字段对象均需替换为目标表单真实数据；示例中出现的模拟接口、固定附件对象和测试 ID 不能作为正式值。
+
+| 想要的效果 | 组合方法 | 关键检查 |
+|---|---|---|
+| 保存前汇总明细人员到主表并去重 | `registerCheckEvent(OPER_SAVE)` → `getDetailAllRowIndexStr` → 逐行 `getBrowserOptionEntity` → 按 id 去重 → `changeFieldValue(...,{specialObj})` → `successFn` | 空行、重复人员、失败回调；仅拦表单保存 |
+| 附件字段回填且可预览 | 从附件模块/现有字段取完整对象 → `changeFieldValue(...,{specialObj:[{id,name,data,type:'file'}]})` | 文件权限、预览/下载入口；不可只传 id/name |
+| 多级选项等复杂值赋值 | 先 `getFieldObj` 观察已有对象 → 按 `data.content` 或 `data.dataOptions` 等原结构写 `specialObj` | 选项模板、次级选项正确显示 |
+| 将明细富文本显示为按钮或链接 | `getDetailAllRowIndexStr` 遍历每行 → `proxyFieldComp` 替换该行内容；添加行事件补新行 | 点击跳转地址与作用范围 |
+| 按两个维度分类、累加到另一明细表 | `getDetailData` 建组合 Key → 对目标行更新/新增/删除 → 监听来源值变化和增删行 | 组合 Key 唯一、消失分组删除、重复事件 |
+| 全表单跨模块识别字段并回填外部数据 | 全局 ecode `onFormReady` 取当前实例并限制 module/formId → 字段事件 → 调受支持接口 → `changeMoreField` | 权限、数据范围、主表/明细位置、失败与清空逻辑 |
+| 明细数字合计并算各行占比 | 读取明细每行数值 → `reduce` 求和 → 主表回写 → 逐行占比赋值；监听值变化及增删行 | 空值、非数字、总额 0、精度 |
+| 联动带出后再汇总并触发后续联动 | 对带出字段监听联动 scope → 汇总 → 写主表 → 必要时 `triggerFieldAllLinkage` | 避免循环；确认事件是否实际触发 |
+| 合并多个主表浏览/选项字段 | 多字段 `getBrowserOptionEntity` → 合并或按 id 去重 → 主表 `specialObj` 赋值 | 是否保留重复项、空字段 |
+| 按同行条件选择明细人员合并到主表 | `getDetailData` → 判断同行选项值 → 取人员对象 → 去重 → `changeFieldValue` | 条件变化、增删行后重算 |
+| 子明细按父行汇总金额 | 父、子关系字段匹配 → 筛子表数据 → 合计 → 回写父表指定 `rowId` | 父标识唯一、子行归属、父行删除后的处理 |
+| 按显示序号生成明细值 | 明细行数组按显示顺序 `map((row,index)=>...)` → `changeDetailData`；监听增删行 | 排序后重新计算，避免把序号当 rowId |
+| 某字段为空时触发另一字段联动 | `getFieldValue` 判空 → `triggerFieldAllLinkage(target)`；载入与源字段变化均执行 | 空字符串、0 与未选择的判定 |
+| 自定义页面参数传递/组件换肤 | 全局 ecode `regOvProps` 或表单字段 `proxyFieldContentComp`，按生效范围选择 | 组件名/props 契约、编译入口 |
+
+上述模式涉及的完整 API、参数与风险分别见 [事件](ref-events-validation.md)、[字段](ref-foundations-fields.md)、[明细](ref-details.md)、[控件](ref-controls.md) 和 [组件交互](ref-ui-global.md)。原案例存在重复与少量不完整代码：例如重复的“保存前汇总人员”，附件数据依赖文档模块，组件 props 示例有语法笔误，数字合计示例用 `eval`，全局回填示例包含模拟数据。这里保留其实现思路，代码应按专题中可运行的结构重新组装。
+
+## 保存前汇总明细人员并去重
+
+先定位明细、明细人员字段和主表目标字段；仅在表单数据保存前执行。需要流程“提交”时改用流程 SDK 的节点提交事件。
+
+```js
+const table = formSdk.convertFieldNameToId('people_detail', 'main');
+const detailPerson = formSdk.convertFieldNameToId('person', table);
+const mainPeople = formSdk.convertFieldNameToId('all_people', 'main');
+formSdk.registerCheckEvent(window.WeFormSDK.OPER_SAVE, (ok, stop) => {
+  try {
+    const rowIds = (formSdk.getDetailAllRowIndexStr(table) || '').split(',').filter(Boolean);
+    const unique = new Map();
+    for (const rowId of rowIds) {
+      for (const item of formSdk.getBrowserOptionEntity(`${detailPerson}_${rowId}`) || []) {
+        if (item?.id) unique.set(String(item.id), item);
+      }
+    }
+    formSdk.changeFieldValue(mainPeople, {specialObj: [...unique.values()]});
+    ok();
+  } catch (error) {
+    stop({msg: '人员汇总失败，请检查明细数据'});
+  }
+});
+```
+
+## 明细数值汇总并计算占比
+
+值变化、增行、删行和初次载入都要重新计算；`getDetailData` 的每行包含 `rowId`。示例以数值 0 处理空值，业务若要求空值报错，应另作校验。
+
+```js
+const table = formSdk.convertFieldNameToId('cost_detail', 'main');
+const detailAmount = formSdk.convertFieldNameToId('amount', table);
+const detailShare = formSdk.convertFieldNameToId('share', table);
+const mainTotal = formSdk.convertFieldNameToId('total', 'main');
+function recalculate() {
+  const rows = formSdk.getDetailData(table) || [];
+  const total = rows.reduce((sum, row) => sum + Number(row[detailAmount]?.value || 0), 0);
+  formSdk.changeFieldValue(mainTotal, {value: String(total)}, {jsApiChange: false});
+  for (const row of rows) {
+    const amount = Number(row[detailAmount]?.value || 0);
+    formSdk.changeFieldValue(`${detailShare}_${row.rowId}`, {value: String(total ? amount / total : 0)}, {jsApiChange: false});
+  }
+}
+formSdk.bindFieldChangeEvent(detailAmount, recalculate);
+formSdk.registerAction(`${window.WeFormSDK.ACTION_ADDROW}${table}`, recalculate);
+formSdk.registerAction(`${window.WeFormSDK.ACTION_DELROW}${table}`, recalculate);
+recalculate();
+```
+
+如汇总源值本身来自字段联动，普通字段变化事件可能不触发；依目标基线使用 `scope: window.WeFormSDK.CHANGE_EVENT_LINKAGE` 或监听 `ACTION_DATA_LINKAGE`。占比输出为 0～1 还是 0～100，须按目标字段的百分比显示方式确定。不要直接打开全局联动事件开关而不检查既有监听是否形成循环。
+
+## 父子明细按关系字段回写
+
+父、子明细的关系字段值相同才能归属同一父行。先配置真实二级明细关系，再对每个父行筛选对应子行。这里的业务主键与 `rowId` 分开。
+
+```js
+const parentTable = formSdk.convertFieldNameToId('parent_detail', 'main');
+const childTable = formSdk.convertFieldNameToId('child_detail', 'main');
+const parentKey = formSdk.convertFieldNameToId('parent_key', parentTable);
+const parentTotal = formSdk.convertFieldNameToId('parent_total', parentTable);
+const childKey = formSdk.convertFieldNameToId('child_parent_key', childTable);
+const childAmount = formSdk.convertFieldNameToId('child_amount', childTable);
+function recalculateParents() {
+  const children = formSdk.getDetailData(childTable) || [];
+  for (const parent of formSdk.getDetailData(parentTable) || []) {
+    const key = parent[parentKey]?.value;
+    const total = children.filter(row => row[childKey]?.value === key)
+      .reduce((sum, row) => sum + Number(row[childAmount]?.value || 0), 0);
+    formSdk.changeFieldValue(`${parentTotal}_${parent.rowId}`, {value: String(total)}, {jsApiChange: false});
+  }
+}
+formSdk.bindFieldChangeEvent(childAmount, recalculateParents);
+formSdk.registerAction(`${window.WeFormSDK.ACTION_ADDROW}${childTable}`, recalculateParents);
+formSdk.registerAction(`${window.WeFormSDK.ACTION_DELROW}${childTable}`, recalculateParents);
+recalculateParents();
+```
+
+关系字段若为选项而非文本，按 `getFieldObj` 的 `specialObj` 比较 ID。父行标识必须唯一；删除父行后的子行处置应由业务规则明确。用 `getDetailData` 复制子行时不要复制旧 `rowId`。
+
+## 来源明细按两列分组，同步到目标明细
+
+来源中按“部门 ID + 类型 ID”分组求和；目标中已有分组更新、缺失分组新增、来源已消失的分组删除。监听来源的两列条件字段、数值字段与增删行事件。下面只展示同步函数，绑定方式同上方汇总案例。
+
+```js
+function syncGroups(sourceTable, targetTable, sourceDept, sourceType, sourceAmount,
+                    targetDept, targetType, targetAmount) {
+  const groups = new Map();
+  for (const row of formSdk.getDetailData(sourceTable) || []) {
+    const dept = row[sourceDept]?.specialObj?.[0];
+    const type = row[sourceType]?.specialObj?.[0];
+    if (!dept?.id || !type?.id) continue;
+    const key = `${dept.id}:${type.id}`;
+    const item = groups.get(key) || {dept, type, total: 0};
+    item.total += Number(row[sourceAmount]?.value || 0);
+    groups.set(key, item);
+  }
+  const existing = new Map();
+  for (const row of formSdk.getDetailData(targetTable) || []) {
+    const deptId = row[targetDept]?.specialObj?.[0]?.id;
+    const typeId = row[targetType]?.specialObj?.[0]?.id;
+    if (!deptId || !typeId || !groups.has(`${deptId}:${typeId}`)) {
+      formSdk.delDetailRow(targetTable, row.rowId);
+    } else {
+      existing.set(`${deptId}:${typeId}`, row.rowId);
+    }
+  }
+  for (const [key, item] of groups) {
+    const rowId = existing.get(key);
+    if (rowId) {
+      formSdk.changeFieldValue(`${targetAmount}_${rowId}`, {value: String(item.total)}, {jsApiChange: false});
+    } else {
+      formSdk.addDetailRow(targetTable, {
+        [targetDept]: {specialObj: [item.dept]},
+        [targetType]: {specialObj: [item.type]},
+        [targetAmount]: {value: String(item.total)}
+      });
+    }
+  }
+}
+```
+
+这种同步会删除目标中无来源的行，只有目标表完全由来源派生时才适用；若允许用户手工维护目标行，应改为保留手工行并有明确的来源标识。跨字段 `id` 类型与数值精度须按实际表单处理。
+
+## 根据明细同行条件筛人员，合并到主表
+
+对每行读取条件选项，按不同条件分别取对应人员字段，再按人员 ID 去重并写入主表。初次载入、条件/人员字段变化、明细增删行均重新执行。
+
+```js
+function syncPeople(table, conditionField, firstPeopleField, secondPeopleField, mainPeopleField) {
+  const people = new Map();
+  for (const row of formSdk.getDetailData(table) || []) {
+    const choice = row[conditionField]?.specialObj?.[0]?.id;
+    const selected = choice === '0' ? row[firstPeopleField]?.specialObj :
+      choice === '1' ? row[secondPeopleField]?.specialObj : [];
+    for (const person of selected || []) if (person?.id) people.set(String(person.id), person);
+  }
+  formSdk.changeFieldValue(mainPeopleField, {specialObj: [...people.values()]}, {jsApiChange: false});
+}
+```
+
+条件选项 ID `'0'/'1'` 是示例占位，须读取真实选项 ID。若人员字段由系统联动带出，还要按[事件指南](ref-events-validation.md)监听联动完成事件。

package/skill-docs/references/code-block/ref-troubleshooting.md

@@ -0,0 +1,49 @@
+# JSSDK 排查、版本与边界
+
+## 代码不生效时
+
+1. 确认保存的是目标表单的目标布局及目标终端，或正确的表单级/全局 ecode；JS 编译通过且代码已启用，CSS 单独保存。浏览器打开的是最新布局而非另一设备布局。
+2. 确认 `formSdk` 取自当前表单实例；全局 ecode 用 `onFormReady` 的事件实例并限定 formId/module。较早基线的 `pageSdk.on('formReady')` 与新基线闭包方式不要混用到未支持的入口。
+3. 用 `getBaseInfo`、`convertFieldNameToId`、`getFieldInfo` 检查当前表单和字段；数据 Key 不是字段名或物理表名。明细字段要指定明细表位置，行操作要取得真实 `rowId`。
+4. 用 `getFieldObj` 对照目标类型的数据形状。文本/数字/日期常用 `{value}`；浏览/动态选项/附件常用 `{specialObj}`。附件预览还依赖完整 `data`。
+5. 检查事件是否属于“表单保存”“流程提交”“用户改变”“联动改变”中的哪一种；必要时分开绑定。拦截回调必须调用通过或阻断函数；异步超时约 25 秒。
+6. 检查权限和组件边界。流程节点默认只读或权限锁定的字段，不能仅靠 `changeFieldAttr(2)` 放开；JS 渲染也不改变后端权限。
+
+开发调试时可按环境入口临时屏蔽不同层级二开：ecode 平台、全局初始化代码、布局源码对应不同入口。调试开关仅用于定位，不作为正式配置。对含多表单、父子页面、明细新行的场景，还要检查实例、`postMessage` 来源与渲染时机。
+
+## 设计器源码面板为空 / ECode decode failed
+
+- **症状**：打开布局源码时控制台报 `ECode decode failed, SyntaxError: Expected ':' after property name in JSON at position 5`，源码面板为空，预览按钮失效。
+- **原因**：`sourceCode.ecode` 被 `encodeURIComponent` 写入。设计器用 `JSON.parse(decodeURI(ecode))` 读取，而 `decodeURI` 不还原 `%3A`（冒号），JSON 变成 `{"js"%3A...}`。
+- **处理**：用 `form code layout set` / `wf-form code layout set` 重新写入（CLI 已使用 `encodeURI`，并在写入前、回读后按设计器路径自检）。临时恢复可把 `sourceCode.ecode` 置为空字符串，再用空 JS/CSS 文件重写。
+- **手工调接口**：必须用 `encodeURI(JSON.stringify({js, css}))`，不要用 `encodeURIComponent`。
+
+## 基线速查
+
+| 功能 | 原技术资料标注的最低基线 |
+|---|---|
+| `changeFieldValue` 的联动控制参数 | 241001 |
+| `valueInfo.type/contentObj` 特殊字段 | 241201 |
+| 字段联动拦截及联动动作的 `runData` | 240601 |
+| 字段变化事件的联动 `scope` | 250401；明细专用事件的扩展参数 250901 |
+| 明细批量添加 `addDetailData` | 241201 |
+| 布局/表单代码直接取得当前 `formSdk` | 主体说明标注 250101；另有一处写 241201，稳妥按 250101 判断 |
+| 明细批量更新 `changeDetailData` | 250101 |
+| `changeTabItemAttr` | 20250501 |
+| `controlOptionDisable` | 20250501 |
+| `convertFieldNameToId` 用明细表数据 Key 定位明细字段 | 260601 |
+| `getDetailData` 按当前明细筛选条件取数 | 260401 |
+| `triggerFieldAllLinkage(...).then(...)` | 250901 |
+| 联动赋值导致的明细行变化事件扩展 | 251101 |
+| `pluginGet/pluginExecute` | 260201 |
+
+先确认目标环境版本和实际 API 可用性；未达到基线时不要假设同名功能可用。
+
+## 原案例中需纠正的写法
+
+- 字段赋值示例声明 `textFieldMark` 后却调用 `fieldMark`，日期示例声明 `dateFieldMark` 后调用 `selectFieldMark`；按真正声明的目标字段写。
+- 字段属性示例的明细行模板字符串缺少引号闭合；正确形式为 `` `${detailField}_${rowId}` ``。
+- `getFieldCom` 章节示例调用了 `getFieldInfo`；两者用途不同，前者为组件引用，后者为字段信息。
+- 明细“默认使用末行”章节的示例实际调用 `setDetailAddUseCopy`；先确认所需是复制末行，而非仅控制默认光标或位置。
+- 案例中的 `eval(numbers.join('+'))`、测试 URL、固定附件元数据、模拟外部查询结果不能直接用于业务配置。数值合计用显式转换与 `reduce`，外部接口须有真实契约。
+- 全局 ecode 的 `import`、JSX、`regOvProps` 示例不要直接粘入布局源码；按目标编辑器支持的语法重写。布局源码中的局部字段组件复写则按其 API 单独处理。

package/skill-docs/references/code-block/ref-ui-global.md

@@ -0,0 +1,47 @@
+# 组件渲染、全局交互与扩展
+
+## 当前表单与全局操作
+
+`formSdk.getBaseInfo()` 读取当前表单基本信息；`formSdk.isMobile()` 判断移动端。布局级代码优先使用当前作用域 `formSdk`；提示、弹窗由全局 `window.WeFormSDK` 提供。
+
+| 效果 | API 与要点 |
+|---|---|
+| 提示 | `window.WeFormSDK.showMessage(message, type?, duration?)`；type 为 `1` 警告、`2` 错误、`3` 成功；时长单位秒 |
+| 确认 | `window.WeFormSDK.showConfirm(content, onOk, onCancel?, {title,okText,cancelText}?)`；title 仅 PC 有效 |
+| 自定义弹窗 | `window.WeFormSDK.openCustomDialog({content,width,height,onOk,onCancel,footer?,...})`；返回对象可 `destroy()` |
+| 页面刷新 | `formSdk.reloadPage(params?)` |
+| 提交附加参数 | `formSdk.appendSubmitParam({customParam:{...}})`；接收端仍须能处理该参数 |
+| 主动做必填检查 | `formSdk.verifyFormRequired(mustAddDetail?,fieldRequired?)` |
+| 全局加载 | `window.WeFormSDK.getLoadingGlobal()` 取加载控件，调用 `start()`、`end()`、`destroy()` |
+| 关闭页面提示 | `formSdk.setFormTipCloseStatus(true/false)`；只控制提示状态，不执行保存 |
+
+自定义 footer 使用 `@weapp/ui` 的 import/JSX 是 ecode 构建环境示例；布局源码只允许其编辑器可编译的语法和已暴露对象，不能直接套用 ecode 依赖。
+
+## 字段区域事件和局部渲染
+
+`bindFieldAction(type, fields, handler)` 绑定失焦、聚焦、点击、双击、移入/移出；事件类型为 `onblur/onfocus/onclick/ondbclick/mouseover/mouseout`。
+
+| 需求 | API |
+|---|---|
+| 将当前字段内容替换为自定义内容 | `proxyFieldComp(fieldMark, reactNode或文本, range?)` |
+| 在字段后追加内容 | `afterFieldComp(fieldMark, reactNode或文本, range?)` |
+| 用函数包装原字段内容并利用 props 决定样式 | `proxyFieldContentComp(fieldMark, (props, componentFn) => React.createElement(..., componentFn()))` |
+
+`range` 省略时作用于全部读写状态；`'1'` 只读、`'2'` 可编辑、`'3'` 必填，多个值以逗号分隔。`proxyFieldContentComp` 的回调必须返回组件，第二参数 `componentFn` 可生成原字段内容。`React` 可用性和编译语法要以目标代码入口为准。明细字段不加行 ID 可作用于整列，指定行则加 `_rowId`；新添行的专门逻辑应在添加行事件后检查是否生效。此能力是当前表单字段的局部渲染，不等于发布平台级新组件，也不等于改写后端接口。
+
+```js
+const field = formSdk.convertFieldNameToId('status', 'main');
+formSdk.proxyFieldContentComp(field, (props, original) =>
+  React.createElement('div', {style: {backgroundColor: props?.widgetValue?.content === '1' ? '#e3f2fd' : ''}}, original())
+);
+```
+
+## 插件与页面间通信
+
+260201 及以后基线提供 `formSdk.pluginGet(fieldMark, property)` 和 `formSdk.pluginExecute(fieldMark, method, ...args)`；只能操作该插件实际公开的属性/方法。具体 WPS 或其他插件须取得该插件契约，不能从 JSSDK 通用接口推断方法名。
+
+`window.open` 打开的子页面可通过 `window.opener` 访问父窗口；同源时可操作父页面的表单实例。跨源时用 `postMessage`，接收方检查 `event.origin` 和 `event.data.type`，发送方指定目标 origin；只发送必要数据，不传鉴权信息。
+
+子表控件数据变化后，如需刷新相关显示，布局源码中可调用 `pageSdk.events.emit('field.change', '纯数字字段ID')`；ecode 中可调用 `window.ebuilderSDK.getPageSDK().events.emit('field.change', '纯数字字段ID')`。原资料还提到可附第三个字段数据参数：文本传文本，浏览型传以逗号分隔的 ID；按实际刷新需求决定是否传值。此处第二参数是纯数字字段 ID，不是带 `field` 前缀的标识。
+
+全局 ecode 的 `regOvProps` 可复写特定组件 props，但其包名与目标组件名是项目级契约；它和布局内 `proxyFieldContentComp` 是不同层级。采用哪一层，应以所需生效范围为准。

package/skill-docs/references/coding/guide-page-code.md

@@ -217,6 +217,8 @@ if (editingId) {
 | **资源统一用 `${appRes}/相对路径`**（如 `${appRes}/logo.png`） | `${appRes}` 是平台模板变量，导入后自动替换成正式静态地址。**禁止**写 `./resources/...`、`../resources/...`、`/resources/...`，发布后必 404。 |
 | **禁止在线资源** | 不要 `loadjs('http(s)://...')`、CDN、外链脚本——平台不加载外网资源。确需第三方脚本：先下载进项目，再按上一条 `${appRes}` 引用。 |
 | **禁止在 JS 里 `import` CSS** | ecode 没有 CSS 模块解析，`import './x.css'` 不会生效，样式静默丢失。少量样式用内联 style；独立 CSS 文件的打包规则见 `ref-compile-rules.md`「E10 打包与平台加载规则」。 |
+| **HTML 原型：样式严格 100% 还原** | 用户提供 HTML 原型时，页面样式必须与原型严格一致（布局、间距、字号、颜色、圆角、边框、层级），不得用平台默认样式近似代替；交付前逐项对照原型自检。 |
+| **HTML 复刻：样式写进代码，不建独立 CSS 文件** | 用户提供 HTML/设计稿并要求完整复刻时，样式全部写在组件代码里（内联 `style` / 代码内样式对象），**不要生成独立 `.css` 文件**——拆出去不保证被加载，复刻会静默丢样式。 |
 | **全部用 ESM `import` / `export`，禁止 `module.exports`** | 平台按模块加载，CommonJS 导出解析不到。 |
 | **只用白名单组件及其文档化 props** | 拿不准的组件 / prop / 图标名，先查 `references/components/`，不要凭记忆从 `@weapp/ui` 编造。 |
 | **不碰平台组件内部** | 不读 `props.children[...]`（含可选链写法）、不依赖内部 class / `weId` 段、不做全局无条件 `regOvComponent` 复写——内部结构不是稳定 API，平台升级即坏。 |

package/skill-docs/references/coding/ref-compile-rules.md

@@ -112,6 +112,8 @@ e10-cli project import <projectId> .target/xxx.zip --main-url /sp/custom/...
 ### CSS 规则
 
 - **禁止在 JS 里 `import` CSS**：ecode 无 CSS 模块解析，写了必丢、发布后无样式。
+- **用户提供 HTML 原型时，页面样式严格 100% 还原**（布局、间距、字号、颜色、圆角、边框、层级），不用平台默认样式近似代替。
+- **完整复刻用户提供的 HTML 时，样式一律内联进代码**（内联 style / 代码内样式对象），不要拆成独立 `.css` 文件：拆出去既不保证加载，也容易与页面结构脱节，复刻效果走样。
 - 少量页面样式用内联 style；确需独立 `.css` 文件时，确认它在 `build.json` 的 codes 里（首次自动生成时 `.css` 会登记为 `y`；文件是后加的要自行补登记），否则平台不合并加载。
 - 业务 CSS 选择器挂在页面根容器下，避免裸 `.类名`、`body`、`:root` 或平台内部 class 污染全局。
 

package/skill-docs/references/common/capability-boundaries.md

@@ -0,0 +1,15 @@
+# 平台与 CLI 能力边界
+
+> 下列能力 **CLI 不支持、平台也不支持**。不要声称可以做，也不要输出操作步骤；直接告知用户「当前平台/CLI 不支持」。
+
+| 不支持的能力 | 说明 |
+|---|---|
+| H5 / 移动端菜单 | 移动端是独立体系（不同 URL + 不同 pageId），尚未整理，禁止编造 |
+
+## 判断「CLI 支不支持」的正确方式
+
+1. 先查 `references/common/ref-cli-commands.md` 的对应命令与参数；
+2. 再跑 `e10-cli <命令> --help` 确认当前版本有没有该选项；
+3. 仍无法确认时，问用户或如实说明「当前版本没有对应命令」。
+
+**禁止绕行**：不要为了完成配置临时编写 `.mjs` 脚本调用内部接口，也不要让用户直接操作浏览器或设计器代替命令；确认没有命令时，保留该项未完成状态并说明影响。

package/skill-docs/references/common/guide-install.md

@@ -0,0 +1,44 @@
+# 安装、升级与文档同步
+
+## 版本必须匹配
+
+skill 与 CLI 的版本要一致（见 SKILL.md frontmatter 的 `version`）。版本不一致时，命令、选项和文档可能对不上。
+
+```bash
+e10-cli --version          # 应与 SKILL.md 标注的版本一致
+npm install -g weaver-e10-builder
+```
+
+## CLI 升级
+
+- 一般工具：先 `npm rm -g weaver-e10-builder` 卸掉旧包，再重新安装，避免 bin 残留冲突。
+- WorkBuddy：先直接用 bash 删除旧包目录（不走 npm 删除），再用 npm 纯安装，并指定一个有权限的工作目录作为缓存地址。
+
+## skill 安装 / 升级
+
+先卸旧（旧名 `skill-e10-cli`），再装新：
+
+```bash
+npx -y skills remove skill-e10-cli
+npx -y skills add ./weaver-e10-builder.zip --skill -y
+```
+
+`skills remove` 无效时手动删除后再 add：
+
+- Claude Code：`rm -rf ~/.claude/skills/skill-e10-cli` → 新 skill 装到 `~/.claude/skills/weaver-e10-builder`
+- WorkBuddy：`rm -rf ~/.workbuddy/skills/skill-e10-cli` → 新 skill 装到 `~/.workbuddy/skills/weaver-e10-builder`
+
+## 文档树同步
+
+1.1.0 起发布的 skill 是**薄指令层**：只带 SKILL.md、`_catalog.md`、actionflows 指令层和 scripts，不含深目录文档树（适配 marketplace 两级目录限制）。完整文档随配套 CLI 的 `skill-docs` 分发。
+
+- 每次 `e10-cli auth status` 会自动探测本机已装 skill（`~/.claude/skills`、`~/.workbuddy/skills`、`~/.codex/skills`）并同步文档；版本一致则跳过。
+- 手动刷新：`e10-cli skill sync`；可 `--target <安装根目录>` 指定其他工具目录。
+- 装完 skill 后看到 references 文档多出/更新、旧文档被清理，都是正常的同步现象，不是装错或重复安装。
+- 读 `references/...` 提示文件不存在 → 先 `e10-cli skill sync`，或确认 skill 已装后重跑 `e10-cli auth status`。
+
+## 文档读取与模板拷贝
+
+- 文档在 skill 目录内（如 `~/.claude/skills/weaver-e10-builder/`），`references/...`、`actionflows/...`、`assets/...` 均相对该目录。
+- 按决策树命中哪个读哪个，不要一次性全部读入。
+- 页面模板用 `e10-cli skill copy [目录]` 拷到工作区（默认当前目录，放出 `references/`、`actionflows/`、`assets/`）。

package/skill-docs/references/common/guide-plan-template.md

@@ -92,6 +92,7 @@
 - [ ] 编号规则 | 表单/字段：<名称> | 组成与位数：<内容> | 核验：生成值
 - [ ] 表单权限 | 表单/主体：<名称> | 新建/查看/编辑/删除范围：<内容> | 核验：授权结果
 - [ ] 表单页按钮 | 表单/页面/位置：<名称> | 目标与字段映射：<内容> | 核验：点击结果
+- [ ] 表单代码块 | 表单/布局/终端/代码层级：<名称> | 触发时机、字段/明细 Key、预期效果：<内容> | 方法参考：`code-block/guide-code-block.md` | 核验：读回与运行场景；无受支持写入命令时保持未完成并说明影响
 
 > 每个功能批次先核对覆盖表单清单，再逐表配置；同一表单有多条独立规则时继续拆行。建表时已配置并核验的分组、必填、只读、默认值等写在 2.1 的表单项结果中，不重复执行。
 
@@ -150,7 +151,7 @@
 |---|---|---|---|
 | <章节及要求> | 待业务确认/待环境核查/需其他方式补充/已确认无法实现 | <内容> | <内容> |
 
-> 已确认无法实现的原需求项保持 `[ ]`，不得以替代配置冒充完成；在此说明原因和影响，交由用户决定。其他状态继续保留相应待办与依赖。
+> 当前 CLI 暂不支持的配置项保持 `[ ]`，在此说明能力缺口及影响；不得用临时脚本、内部接口或浏览器操作代做，也不得以替代配置冒充完成。其他状态继续保留相应待办与依赖。
 
 ### 6. 阶段验收与交付资源
 - 第一阶段：全部应建表单的字段、明细、布局和默认台账已核对；表单级与视图级需求逐项销号，后续流程依赖已标注。

package/skill-docs/references/common/map.md

@@ -9,6 +9,15 @@
 3. 规划状态区分：**待业务确认**（语义或取值有歧义）、**待环境核查**（资源、权限或环境行为未证实）、**需其他方式补充**（现有 CLI 只能完成一部分）、**已确认无法实现**（核实无可行路径）。只有最后一种写入 plan 的“无法实现的项”，原需求项保持未完成。
 4. 按资源依赖组织 plan；关键配置写明读回点和最小业务验收点。接口保存、配置读回与页面实际生效是不同层次，按风险选择必要的检查。
 
+## 平台概念
+
+- **Ecode** — 存放和运行代码的平台；自定义页面在这里编码、构建、运行。
+- **Ebuilder 应用** — 独立概念，包含表单、流程等资源（与 Ecode 项目不同）。
+- **默认台账与菜单入口是两件事** — 表单创建后会生成默认台账/列表视图，但 `form create` 默认不加应用菜单；需要入口时用 `--menu`，或建表后 `menu add-table`。默认台账已存在不等于菜单入口已存在。
+- 只有图表仪表盘、跨表单聚合视图、特殊交互流程、对外公开页面等场景才需要自定义页面。
+- 所有系统交互命令均通过 `e10-cli` 执行（已全局 link）。auth 文件自动查找，也可 `--auth <path>` 指定。
+- 当前登录用户的 userId 是固定变量 `TEAMS.currentUser.id`，前端代码里可以直接使用。
+
 ## 一、资源地图：创建、复用或修改什么
 
 | 资源 | 使用场景与解决的问题 | 依赖与 plan 要点 | 能力边界与简要验收 | 详见 |
@@ -50,7 +59,7 @@
 | 布局样表 | 从完整表格提取空间排布 | 写 FLOW/EXCEL、标题、行列、同排、空白和合并 | 字段清单与布局蓝图同时保留；验收实际位置 | [布局规划](../form/guide-form-layout-planning.md) |
 | 字段分组 | 将业务字段归入折叠分段 | 写分组名称、顺序及成员字段 | 需求明确时配置；验收字段归属 | [布局规划](../form/guide-form-layout-planning.md) |
 | 关联字段 | 选择客户、合同、流程等原生业务对象 | 写字段子类、目标对象、单/多选 | 关联对象与通用浏览来源分别选型；验收选择范围 | [字段码表](../form/ref-form-fields.md) |
-| 关联数据范围 | 限定关联字段可选记录 | 关联字段；写过滤条件与字段映射 | 区分弹窗显示列；验收可选数据 | [关联范围](../form/guide-ebuilder-scope.md) |
+| 浏览数据定义 | 限定浏览可选数据、默认搜索及弹窗 Tab | 先查可配置字段，再查各字段开放的配置项与候选值 | 按浏览来源适配；验收实际可选数据、搜索与 Tab | [浏览数据定义](../form/guide-browser-definition.md) |
 | 二级明细 | 父级每行挂载子级明细记录 | 主/子明细表；写父子行标识与层级 | 子表归属需按行核对 | [二级明细](../form/guide-form-sub-detail.md) |
 | 字段公式 | 根据其他字段计算目标值 | 写表达式、目标字段和精度 | 验收公式读回与样例计算 | [公式](../form/guide-form-formula-functions.md) |
 | 函数联动 | 字段变动或载入时赋值计算 | 写触发字段、目标字段、事件和表达式 | 与静态字段公式分开；验收触发结果 | [函数联动](../form/guide-formula-linkage.md) |
@@ -121,6 +130,7 @@
 | 点击按钮打开关联任务或发起流程 | 视图按钮或表单按钮，逐项写目标、当前行过滤与预填映射 |
 | 复杂自动写入其他表 | 动作流，写清触发、字段映射及目标记录定位；单纯本表计算选公式/联动 |
 | 标准配置无法表达的页面交互 | 明确目标范围后规划配置式页面或定制页面，并单列发布和交互验收 |
+| 当前表单布局中的字段、明细或交互需用 JS 实现 | 规划布局源码或表单级 ecode：写目标表单、布局/终端、触发事件、字段 Key、效果和运行检查；按[代码块指南](../code-block/guide-code-block.md)选 CLI 写入入口和对应 JSSDK 方法 |
 
 ## 四、常见依赖与计划顺序