@lark-apaas/coding-steering 0.1.6-alpha.4 → 0.1.6-alpha.5

package/README.md

@@ -12,7 +12,9 @@ steering/
 │   └── skills/                    # cross-stack shared skills
 ├── <stack>/
 │   ├── tech.md                    # always-loaded, injected into agent system prompt
-│   └── skills/<id>/SKILL.md       # progressive disclosure, triggered by description match
+│   ├── skills/<id>/SKILL.md       # progressive disclosure, triggered by description match
+│   └── skills_local/<id>/SKILL.md # local-only variant; overrides skills/<id> when syncing
+│                                  #   to a local-dev project (e.g. via lark-cli)
 └── ...
 ```
 
@@ -24,9 +26,16 @@ Top-level directory names (other than `_common`) ARE the stackId — discovery i
 |---|---|
 | `steering/<stack>/tech.md` | `.agent/steering/tech.md` |
 | `steering/<stack>/skills/<id>/**` | `.agent/steering/skills/<id>/**` |
+| `steering/<stack>/skills_local/<id>/**` | `.agent/steering/skills/<id>/**` (local-dev sync only) |
 | `steering/_common/skills/<id>/**` | `.agent/steering/skills/<id>/**` |
 
-When a `_common` skill and a stack-specific skill share the same `<id>`, the stack-specific one wins.
+Precedence when the same `<id>` exists in multiple sources (lowest → highest, later wins):
+`_common/skills` → `<stack>/skills` → `<stack>/skills_local` (local-dev sync only).
+
+`skills_local` is a stack-specific variant intended for the local-development sync path
+(`miaoda skills sync --local`, driven by `lark-cli apps`). The cloud sandbox sync path
+ignores `skills_local` and uses `skills` as-is, so authors of `skills_local` content can
+assume "本地 agent" semantics (no `ddl_sql` / `plugin_instance` / sandbox-log tools, etc.).
 
 ## Writing rules
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lark-apaas/coding-steering",
-  "version": "0.1.6-alpha.4",
+  "version": "0.1.6-alpha.5",
   "description": "Stack-specific steering content for miaoda-coding templates",
   "type": "module",
   "files": [

package/steering/design-stack/skills/client-add-aily-web-chat/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: client-add-aily-web-chat
+description: Use when integrating Aily AI chat panel into a web app using @lark-apaas/client-toolkit/aily-chat. 触发词：Aily 聊天, Aily 对话面板, Aily chat, aily-chat SDK, AI 对话组件集成
+---
+
+# 添加 Aily Web 对话面板
+
+使用 `@lark-apaas/client-toolkit/aily-chat` 将 Aily 对话面板集成到 Web 应用。SDK 与框架无关（纯 DOM 操作）。
+
+## Quick Reference
+
+| 操作 | 方法 |
+|------|------|
+| 初始化 | `await initAilyChat(container, config)` |
+| 发送消息 | `chatPanel.sendMessage({ content, skillID? })` |
+| 清空记录 | `chatPanel.clear()` |
+| 清空并停止 | `chatPanel.clearAndStop()` |
+| 更新配置 | `chatPanel.updateConfig(partialConfig)` |
+| 销毁 | `chatPanel.destroy()` |
+
+## 核心流程
+
+### 1. 向用户获取 appKey
+
+实现前必须先询问用户：
+
+> "请提供你的 Aily `appKey` 以配置对话组件。你可以在 [Aily 平台](https://apaas.feishu.cn/ai/projects) 中找到对应应用的 appKey。"
+
+### 2. 集成代码
+
+React 组件示例（vanilla JS 同理，对 DOM 元素调用 `initAilyChat` 即可）：
+
+```tsx
+import { useEffect, useRef } from "react";
+import { initAilyChat, type ChatPanel } from "@lark-apaas/client-toolkit/aily-chat";
+
+interface AilyChatProps {
+  appKey: string;
+  anonymous?: boolean;
+}
+
+const containerStyle = { width: "100%", height: "500px" };
+
+const AilyChat = ({ appKey, anonymous }: AilyChatProps) => {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const chatPanelRef = useRef<ChatPanel | null>(null);
+
+  useEffect(() => {
+    if (!containerRef.current) return;
+    let destroyed = false;
+
+    initAilyChat(containerRef.current, {
+      appKey,
+      anonymous,
+      conversion: { needAvatar: true },
+      events: {
+        onReady: () => console.log("对话就绪"),
+        onError: (err) => console.error("对话错误", err),
+      },
+    }).then((panel) => {
+      if (destroyed) panel.destroy();
+      else chatPanelRef.current = panel;
+    });
+
+    return () => {
+      destroyed = true;
+      chatPanelRef.current?.destroy();
+      chatPanelRef.current = null;
+    };
+  }, [appKey, anonymous]);
+
+  return <div ref={containerRef} style={containerStyle} />;
+};
+
+export default AilyChat;
+```
+
+### 3. 告知用户 UI 定制选项
+
+代码集成完成后，**必须**向用户展示以下可定制选项：
+
+- 修改组件标题/顶部标题
+- 关闭/开启组件标题栏
+- 显示/隐藏关闭按钮
+- 隐藏/展示用户头像、隐藏/展示系统头像
+- 修改用户头像或系统头像，并发送新头像图片 
+- 隐藏/展示组件欢迎语
+
+## 配置参考
+
+### WebSDKConfig（顶层）
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `appKey` | string | 是 | 应用标识 |
+| `uuid` | string | 否 | 用户标识，启用 `needCache` 时必填 |
+| `anonymous` | boolean | 否 | `true` 开启匿名模式，跳过登录。**须在 Aily 应用「渠道管理」中将 SDK 模式开启匿名访问，否则会报错「匿名SDK没有开启支持使用应用身份调用API和SDK」** |
+| `conversion` | object | 否 | 对话配置（头像、缓存、欢迎语） |
+| `editor` | object | 否 | 顶部栏配置（标题、关闭按钮） |
+| `events` | object | 否 | 事件回调 |
+
+### conversion
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `needCache` | boolean | `false` | 启用消息缓存（需同时提供 `uuid`） |
+| `storageType` | string | `"memory"` | `memory` / `sessionStorage` / `localStorage` / `indexDB` / `server` |
+
+> 头像和欢迎语相关字段见上方「UI 定制选项」表。
+
+### editor
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `display` | boolean | `true` | 是否显示编辑器 |
+| `needHeader` | boolean | `true` | 是否显示顶部 header（含标题和新建对话按钮），仅 V2 生效 |
+| `headerTitle` | string | 应用名称 | 对话标题，显示在 header 中 |
+| `needCloseButton` | boolean | `false` | 是否显示关闭按钮。配合 `events.onClose` 监听点击 |
+
+### events
+
+| 事件 | 签名 | 说明 |
+|------|------|------|
+| `onReady` | `() => void` | 对话就绪 |
+| `onError` | `(error: Error) => void` | 发生错误 |
+| `onMessage` | `(message: unknown) => void` | 收到消息 |
+| `onInited` | `(data: { sessionId, conversationId, handler }) => void` | 会话已创建 |
+| `onInitedWithWelcome` | `() => void` | 欢迎语已创建 |
+| `onClose` | `() => void` | 用户点击关闭按钮时触发（需配合 `editor.needCloseButton: true`） |
+
+## Common Mistakes
+
+| 错误 | 正确做法 |
+|------|----------|
+| 忘记在 useEffect 清理时调用 `destroy()` | 必须在 cleanup 中销毁 ChatPanel，否则内存泄漏 |
+| 启用 `needCache` 但未传 `uuid` | 缓存依赖 `uuid` 识别用户，缺失则无法恢复历史消息 |
+| 容器元素无固定宽高 | 容器必须有明确尺寸，否则面板不可见 |
+| 在 React 严格模式下未处理重复初始化 | 用 `destroyed` 标志防止 StrictMode 双重 mount 导致重复面板 |
+| 设置 `anonymous: true` 但未在 Aily 平台开启匿名访问 | 须前往 Aily 应用「渠道管理」将 SDK 模式开启匿名访问，否则报错「匿名SDK没有开启支持使用应用身份调用API和SDK」 |