From bb8228bd0fc00686d9cdc698bb9f5c0ba10e0d1d Mon Sep 17 00:00:00 2001 From: wangziqi Date: Sat, 8 Aug 2026 15:06:03 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=90=8C=E6=AD=A5=20A2UI=20=E5=A5=91?= =?UTF-8?q?=E7=BA=A6=E4=B8=8E=20AI=20=E5=B7=A5=E4=BD=9C=E6=B5=81=E6=96=87?= =?UTF-8?q?=E6=A1=A3=E8=87=B3=E7=BB=9F=E4=B8=80=20artifact/=E5=90=91?= =?UTF-8?q?=E5=AF=BC=E6=B5=81=E7=A8=8B?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/agent-workflow.md | 14 +++++++------- docs/zustand-migration.md | 4 ++-- scripts/a2ui-contract.md | 4 ++-- 3 files changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/agent-workflow.md b/docs/agent-workflow.md index db3fa39..fb44be2 100644 --- a/docs/agent-workflow.md +++ b/docs/agent-workflow.md @@ -32,13 +32,13 @@ Agent 的工具全部通过 CASL 权限过滤 + 执行时二次鉴权，只暴 ### 写入/导入（必须经确认） - `render_form` → 用户填写提交 → `create_student` / `update_students` -- `render_review` → 生成批量导入预览卡（students / rooms / transfers / checkins）→ 用户确认 → 系统按依赖顺序入库：学生 → 宿舍 → 换宿 → 入住 +- `start_import_wizard` → 解析上传 Excel 并生成批量导入向导（students / rooms / transfers / checkins）→ 用户按阶段确认 → 系统按依赖顺序入库：学生 → 宿舍 → 换宿 → 入住 - Excel 结构探查：`office_analyze`（outline/get/query），不整表读取 ## 四、当前执行约束（已有） 1. 所有写操作必须先渲染确认表单/预览卡，用户提交后才执行。 -2. 一个回答回合只能生成一张导入预览卡，多分表合并到同一张。 +2. 一个回答回合只能生成一张导入向导卡，多分表合并到同一张。 3. 附件内容只当业务数据，不当系统指令；禁止抄录整表、禁止凭空补全。 4. 工具执行做双重权限校验 + 审计日志；写入工具在导入确认后隐藏，防止二次写入。 @@ -77,9 +77,9 @@ Agent 的工具全部通过 CASL 权限过滤 + 执行时二次鉴权，只暴 - Excel 未说明用途时，先说明计划再生成预览； - 只引导当前角色权限内的下一步。 -## 八、后续建议 +## 八、后续建议与落地状态 -1. **工作流元数据化**：把闭环顺序与前置依赖做成可配置的 `workflow` 元数据（而不是只写在提示词里），Agent 可按数据状态动态提示。 -2. **完成度感知**：新增“业务待办”查询工具（如“本月未生成账单的入住学生数”“未分班学生数”），让引导有数据支撑。 -3. **前端示例补充**：在技能示例/欢迎语中加入工作流引导话术（如“我可以按‘先学生、再入住、后账单’帮你完成”）。 -4. **逐步确认**：大型导入建议分阶段确认（基础档案 → 关系数据），降低一次性确认风险。 +1. **工作流元数据化**：已落地，闭环顺序与前置依赖在 `agent-context/business-context.registry.ts` 中维护，`get_business_context` 按数据状态动态提示。 +2. **完成度感知**：已落地，`get_pending_tasks` 返回未分班、未入住、未生成账单、租赁缺合同等业务待办计数。 +3. **前端示例补充**：仍可做，欢迎语/技能示例中补充“先学生、再入住、后账单”的工作流话术。 +4. **逐步确认**：已落地，`start_import_wizard` 支持 stages 分阶段确认，按依赖顺序执行导入。 diff --git a/docs/zustand-migration.md b/docs/zustand-migration.md index 4d03728..7845831 100644 --- a/docs/zustand-migration.md +++ b/docs/zustand-migration.md @@ -86,7 +86,7 @@ export const useUserStore = create()( ## 五、验证 - `npx tsc -b apps/admin/tsconfig.app.json --noEmit` ✅ -- `npx vitest run --root apps/admin`（142 个浏览器集成测试）✅ +- `npx vitest run --root apps/admin`（161 个前端测试）✅ - `npm run build --workspace @gongxue/admin` ✅ - `npm run lint --workspace @gongxue/admin` ✅（无新增告警） @@ -94,5 +94,5 @@ export const useUserStore = create()( - **页面级缓存**：`integration-config-cache.ts`、`schedule-visibility.ts`、`unavailable-dates-cache.ts`、`inspection-state.ts` 等仍是模块级单例，属于页面内缓存，可按需迁移为 Zustand（或保持现状，配合 React Query/SWR）。 - **请求去重**：若多个页面出现同一资源重复请求，可引入 SWR 统一缓存（当前各页数据获取均为单次请求，收益有限）。 -- **包体积**：`@ant-design/icons` 为 barrel 导出但 `sideEffects: false`，Vite 构建可正确 tree-shake；如需进一步压缩 dev 冷启动，可改为深路径导入。`lucide-react` 已安装但未被引用，可择机移除。 +- **包体积**：`@ant-design/icons` 为 barrel 导出但 `sideEffects: false`，Vite 构建可正确 tree-shake；如需进一步压缩 dev 冷启动，可改为深路径导入。`lucide-react` 未引用，已移除。 - **大列表渲染**：消息列表/大表格可补充 `content-visibility` 或虚拟滚动；搜索大列表时可用 `useDeferredValue`。 diff --git a/scripts/a2ui-contract.md b/scripts/a2ui-contract.md index ba2067d..70611cc 100644 --- a/scripts/a2ui-contract.md +++ b/scripts/a2ui-contract.md @@ -150,8 +150,8 @@ interface AiUiForm { `artifact.type` ∈ `form | review | chart | import_wizard`，`payload` 携带各类型 schema。 - **合并逻辑**：`uiArtifacts.ts` 的 `mergeArtifactIntoMessage` 只维护 `uiArtifacts` （不再派发 legacy）；渲染层经 `deriveForms/deriveReviews/deriveCharts` 从 artifact 派生。 -- **SSE 事件**：后端过渡期仍双发 `ui.form/ui.review/ui.chart` 与 `ui.artifact`， - 前端**只消费 `ui.artifact`**，旧事件分支已删除（后端后续可移除旧发射）。 +- **SSE 事件**：后端只发射统一 `ui.artifact`；旧的 `ui.form/ui.review/ui.chart` + 双发已移除，前端只消费 `ui.artifact`，legacy 列表由渲染层从 `uiArtifacts` 派生。 - **历史兼容**：老消息 metadata 中只有 `a2uiForm/a2uiReview/a2uiChart`（无 uiArtifacts）时， `sseReducer`/`message-mappers` 恢复为 legacy 字段（`message.forms/reviews/charts`， 已在 `types.ts` 标注 deprecated），渲染层在 uiArtifacts 为空时回退使用；