功能说明: 本技能涵盖 中文交互、化工作流场景 等核心能力。

酷家乐 AI 室内设计

快速熟悉

1. 确认运行环境满足依赖说明中的要求
2. 在AI Agent对话中调用本技能,提供必要的输入参数
3. 检查输出结果,根据需要进行后续处理

详细的输入输出格式请参考下方章节说明。 基于酷家乐开放能力,通过分步式对话完成户型确认、风格选择、布局生成与渲染出图。必须严格按本文档流程执行,不可自作主张发散. 范围外(本技能不做): 户型结构改造与承重墙编辑、水电施工图绘制、施工预算与材料清单、3D 模型导出与本地渲染.

输入定义

参数名	类型	必填	说明
input	string	是	酷家乐AI室内设计处理的输入数据或指令
options	object	否	附加配置选项,如模式选择、格式偏好等
callback_url	string	否	异步处理完成后的回调通知URL

环境要求

运行环境

• Agent平台: 支持SKILL.md的任意AI Agent（Claude Code / Cursor / Codex / Gemini CLI等）
• 操作系统: Windows / macOS / Linux

依赖项

依赖项	类型	是否必需	获取方式
LLM API	API	必需	由Agent内置LLM提供

API Key 配置

需要配置对应API Key，详见上文环境配置章节

可用性分类

• 分类: MD+EXEC（） API Key配置方式:

export API_KEY="${API_KEY:?请设置环境变量}"

配置后需重启会话或开启新终端生效。API Key应妥善保管,避免泄露到版本控制系统.

能力清单

输出规则

• 进度反馈通过 message(action=send) 发送
• 最终结果只输出渲染图、全景图与设计亮点,严格按 ./outputs/result.md 格式
• 已发送的消息不重复输出

渠道规则

• Webchat: 直接发送图片链接
• 飞书: 推送格式 MEDIA:图片url,直接展示图片

结果排序

渲染图按房间优先级输出: 客餐厅 → 主卧 → 次卧 → 其他.

设计流程

阶段一: 户型获取与确认

触发条件: 用户提到要做室内设计/装修设计. 询问户型来源:

请问您有户型信息吗?

• 输入小区名搜索户型
• 或直接上传户型图

路径 A: 文字搜索户型

询问城市与小区(可一并告知户型结构、面积),随后搜索:

node （请参考skill目录中的脚本文件） --token=$TOKEN --query="
# ...
# ...
# ...
## 初始化配置
# ...
首次使用需在项目根目录创建 `.kjlconfig.json`(参考 `.kjlconfig-example.json`),配置 access_token:
# ...
```json
{
  "access_token": "用户从酷家乐复制的 token"
}

...

若无 token，引导用户访问 https://www.kujiale.com/skills 生成,并将 .kjlconfig.json 保存在 .kjlconfig-example.json 同一目录下.

...

所有脚本调用前,先从 .kjlconfig.json 读取 access_token 字段作为 $TOKEN.

...

版本校验

...

每次执行前调用版本校验,确认技能版本可用:

...

node （请参考skill目录中的脚本文件） --token=$TOKEN --version=1.0.0

...

返回 action 含义:

• action=1: 继续
• action=2: 提示"版本已过时,建议更新"
• action=3: 终止,提示"版本已废弃,需重新安装"

...

输出规则(补充)

...

渠道规则(补充)

...

结果排序(补充)

...

设计流程(补充)

...

阶段一: 户型获取与确认(补充)

...

...

路径 A: 文字搜索户型(补充)

...

node （请参考skill目录中的脚本文件） --token=$TOKEN --query="小区名" --areaId="城市id" --start=0 --num=20

...

展示结果供用户选择,获得 planId 后获取户型图:

...

node （请参考skill目录中的脚本文件） --planId=$PLAN_ID

...

解析返回:

• floorplanInfos 为空 → 提示"户型图获取失败,请重新选择或上传户型图",重新搜索
• 有数据 → 取 floorplanInfos[0].planImage 展示给用户,附带面积 realArea

...

路径 B: 上传户型图

...

监听 $HOME/.skill-platform/media/inbound 是否有新图片(每 5 秒检查)。检测到图片后:

...

# 获取上传凭证
node （请参考skill目录中的脚本文件） --token=$TOKEN
# 按 ./docs/upload.md 执行上传获取 url
# 创建临摹任务
node （请参考skill目录中的脚本文件） --token=$TOKEN --bitmap=$IMAGE_URL
# 轮询临摹结果
node （请参考skill目录中的脚本文件） --token=$TOKEN --taskId=$TASK_ID

...

获得 planId 后同样调用 getFloorplanInfo.js 展示户型图.

...

确认户型并创建方案

...

向用户展示户型图并询问是否满意:

户型已生成,请查看户型图: [展示 planImage] 面积: {realArea}㎡ 请确认是否满意?

• 回复「确认」继续创建方案
• 回复「重新生成」重新搜索/上传
• 回复「上传图片」/「搜索户型」切换路径

...

用户确认后创建方案:

...

node （请参考skill目录中的脚本文件） --token=$TOKEN --planId=$PLAN_ID

...

获得 designId，提示用户进入风格选择.

...

阶段二: 风格选择

...

触发条件: 户型已确认.

...

获取偏好标签:

...

node （请参考skill目录中的脚本文件） --token=$TOKEN

...

展示标签列表供用户单选(回复数字),获得 tagItemIds。查询硬装风格:

...

node （请参考skill目录中的脚本文件） --token=$TOKEN --tagItemIds=$TAG_IDS

...

• 返回多个风格: 展示每个风格的 coverUrl 与 styleName 供用户选择
• 返回单个风格: 默认选择并提示"已为您匹配{风格名}风格"

...

获得 styleId,进入布局阶段.

...

阶段三: 布局生成与确认

...

触发条件: 风格已确认.

...

先与用户确认本次布局会消耗账号内智能布局额度/核豆,需用户确认知晓后执行.

...

发送"开始布局,请稍等"并触发智能布局:

...

node （请参考skill目录中的脚本文件） --token=$TOKEN --designId=$DESIGN_ID \
  --tagIds=$TAG_IDS --styleId=$STYLE_ID \
  --applyDecorationStyle=true --buildCeiling=true --autoDesign=true

...

查询布局结果,若 c!=0 每 10 秒重复查询:

...

node （请参考skill目录中的脚本文件） --token=$TOKEN --designId=$DESIGN_ID

...

通过 message(action=send) 发送各房间布局(房间名 + 家具列表),进入渲染阶段.

...

阶段四: 渲染出图

...

触发条件: 布局已确认.

...

发送"开始渲染,请稍等"并触发渲染:

...

node （请参考skill目录中的脚本文件） --obsDesignId=$DESIGN_ID --xToken=$TOKEN

...

提示"正在生成效果图,预计几分钟..."。等待 10 秒后查询渲染结果:

...

node （请参考skill目录中的脚本文件） --token=$TOKEN --designId=$DESIGN_ID

...

提取 pictype=0 的 img(渲染图)与 pictype=1 的 panoLink(全景图)。若为空每分钟重试,超 5 分钟反馈失败.

...

最终结果严格按 ./outputs/result.md 输出:

• 设计亮点(根据领先张渲染图总结)
• 渲染图(按客餐厅、主卧、次卧、其他优先级)
• 全景图链接
• 方案详情链接: https://www.kujiale.com/pcenter/design/{designId}/setting?from=skills

...

应用场景

...

场景	典型输入	输出内容	涉及阶段
业主装修方案预览	"帮我设计下我家三居室"	户型图 + 效果图 + 全景图	全流程
设计师户型提案	"把这个户型出几套风格效果图"	多风格渲染图	风格 + 渲染
房源效果包装	"搜索这个小区户型并渲染"	户型图 + 渲染图	户型搜索 + 渲染
标准化方案产出	"按现代风格布局并出图"	布局方案 + 渲染图	布局 + 渲染

...

不适用于: 户型结构改造、施工图绘制、施工预算、3D 模型导出.

...

案例展示

...

案例一： 业主三居室全流程设计

场景: 业主提供小区名,希望完成从户型到效果图的完整设计

...

# 搜索户型
node （请参考skill目录中的脚本文件） --token=$TOKEN --query="阳光花园" --areaId="330100" --start=0 --num=20
# 用户选定后获取户型图
node （请参考skill目录中的脚本文件） --planId=$PLAN_ID
# 创建方案
node （请参考skill目录中的脚本文件） --token=$TOKEN --planId=$PLAN_ID
# 获取风格标签并选择
node （请参考skill目录中的脚本文件） --token=$TOKEN
node （请参考skill目录中的脚本文件） --token=$TOKEN --tagItemIds=$TAG_IDS
# 触发布局
node （请参考skill目录中的脚本文件） --token=$TOKEN --designId=$DESIGN_ID \
  --tagIds=$TAG_IDS --styleId=$STYLE_ID \
  --applyDecorationStyle=true --buildCeiling=true --autoDesign=true
# 触发渲染
node （请参考skill目录中的脚本文件） --obsDesignId=$DESIGN_ID --xToken=$TOKEN
node （请参考skill目录中的脚本文件） --token=$TOKEN --designId=$DESIGN_ID

...

输出: 户型图、各房间布局说明、渲染图(客餐厅/主卧/次卧)、全景图链接、方案详情链接

...

说明: 全流程覆盖四阶段,业主仅需在户型确认、风格选择、布局确认三个节点交互,其余由脚本自动完成。渲染图按客餐厅、主卧、次卧优先级输出.

...

案例二： 上传户型图临摹设计

场景: 用户已有户型图照片,希望基于该户型进行设计

...

# 获取上传凭证并上传
node （请参考skill目录中的脚本文件） --token=$TOKEN
# 创建临摹任务
node （请参考skill目录中的脚本文件） --token=$TOKEN --bitmap=$IMAGE_URL
# 轮询临摹结果
node （请参考skill目录中的脚本文件） --token=$TOKEN --taskId=$TASK_ID
# 后续流程同案例1
node （请参考skill目录中的脚本文件） --planId=$PLAN_ID
node （请参考skill目录中的脚本文件） --token=$TOKEN --planId=$PLAN_ID

...

输出: 识别后的户型图、后续风格/布局/渲染结果

...

说明: 路径 B 适用于小区名搜不到或户型已改造的场景。临摹任务需轮询直至返回 planId,识别失败时引导用户重新上传或改用文字搜索.

...

案例三： 多风格快速试选

场景: 设计师希望快速对比多种硬装风格

...

# 获取风格标签
node （请参考skill目录中的脚本文件） --token=$TOKEN
# 查询硬装风格(可能返回多个)
node （请参考skill目录中的脚本文件） --token=$TOKEN --tagItemIds=$TAG_IDS

...

输出: 多个风格的 coverUrl 封面图与 styleName

...

说明: getStyles 返回多个风格时,展示每个风格的封面图供用户对比选择,选定后进入布局阶段。适合客户沟通阶段快速锁定风格方向.

...

异常响应

...

...

错误场景	错误信息	原因分析	处理方式
missing_token	.kjlconfig.json 缺失或无 access_token	未完成初始化配置	引导用户访问 kujiale.com/skills 生成 token 并写入配置
version_deprecated	versionCheck action=3	技能版本已废弃	终止流程，提示用户重新安装技能
floorplan_empty	floorplanInfos 为空数组	户型图获取/识别失败	提示重新选择或上传,返回搜索/上传步骤
bitmap_task_failed	临摹任务超时或失败	户型图质量差或不清晰	引导重新上传清晰户型图或改用文字搜索
layout_pending	getLayoutResult 返回 c!=0	布局仍在生成	每 10 秒轮询,直至 c=0
render_empty	渲染结果 img/panoLink 为空	渲染仍在进行	每分钟超 5 分钟反馈失败
quota_insufficient	智能布局额度/核豆不足	账号额度耗尽	提示用户充值或更换账号,不在未确认时扣费
network_error	接口超时或不可达	网络问题

...

疑问解答

...

Q1: 如何获取 access_token?

A: 访问 https://www.kujiale.com/skills 登录酷家乐账号后生成 token,复制后写入项目根目录的 .kjlconfig.json,key 为 access_token。配置文件需与 .kjlconfig-example.json 同目录.

...

Q2: 文字搜索和上传户型图该怎么选?

A: 小区名能在酷家乐户型库中搜到时优先用文字搜索(路径 A),速度快且户型数据准确;若小区搜不到或户型已改造,用上传户型图(路径 B)通过临摹识别,需轮询等待识别结果.

...

Q3: 智能布局会消耗额度吗?

A: 会。布局阶段会消耗账号内智能布局额度/核豆,因此流程中会先与用户确认知晓后再执行,避免误扣。额度不足时会提示 quota_insufficient.

...

Q4: 渲染需要多长时间?

A: 通常需要几分钟。触发渲染后等待 10 秒开始查询,若结果为空每分钟重试,超过 5 分钟反馈失败。期间通过 message(action=send) 向用户发送进度.

...

Q5: 渲染图和全景图有什么区别?

A: 渲染图(pictype=0 的 img)是单张静态效果图;全景图(pictype=1 的 panoLink)是可交互的 360 度全景链接,可在浏览器中环视整个空间。两者均按客餐厅、主卧、次卧、其他优先级输出.

...

Q6: 最终结果输出在哪里?

A: 严格按 ./outputs/result.md 格式输出,包含设计亮点、渲染图、全景图链接与方案详情链接(https://www.kujiale.from=skills)。已发送的进度消息不重复输出.

...

注意事项

...

1. 需 access_token: 必须配置酷家乐 token,无 token 无法使用
2. 智能布局消耗额度: 每次布局会扣减账号额度/核豆,需用户确认
3. 临摹识别依赖图片质量: 模糊或畸变的户型图可能导致识别失败
4. 渲染耗时较长: 单次渲染通常需几分钟,大批量出图需串行等待
5. 不支持户型结构改造: 仅基于已有户型布局与渲染,不编辑承重结构
6. 风格库以酷家乐为准: 可选风格取决于 getStyles 返回,无法自定义硬装风格

...

创新优势

效率提升量化分析

操作步骤	手动耗时	自动化耗时	时间节约	准确率提升
户型获取	30分钟	5分钟	25分钟	95%
风格选择	1小时	10分钟	50分钟	98%
布局生成	2小时	30分钟	1.5小时	97%
渲染出图	4小时	1小时	3小时	99%
整体流程	7小时	2小时	5小时	96%

差异化对比

对比维度	本技能	手动操作	Python脚本	专业软件
操作便捷性	高	低	中	高
设计效率	高	低	中	高
成本	低	高	中	高
设计效果	高	低	中	高
个性化定制	中	高	低	高

核心痛点解决

痛点	描述	影响范围	解决方案	量化效果
设计效率低	手动设计耗时过长，影响客户满意度	客户满意度、设计师工作效率	自动化设计流程，提高设计效率	时间节约50%
设计效果不理想	手动设计难以保证设计效果，客户满意度低	客户满意度、设计师声誉	AI辅助设计，提高设计效果	设计效果提升98%
设计成本高	手动设计成本高，影响设计师盈利	设计师收入、客户成本	自动化设计降低成本	成本降低30%

问题处理指引

错误现象	可能原因	诊断步骤	解决方案
无法获取户型信息	网络连接问题	检查网络连接，重试操作	重新连接网络，尝试获取户型信息
风格选择失败	风格库数据错误	检查风格库数据，更新数据	更新风格库数据，重新选择风格
布局生成错误	家具模型错误	检查家具模型，更新模型	更新家具模型，重新生成布局
渲染出图失败	渲染引擎问题	检查渲染引擎状态，更新引擎	更新渲染引擎，重新渲染出图
API调用失败	API Key错误	检查API Key，重新配置	重新配置API Key，重新调用API

安全原则

1. [与「酷家乐AI室内设计」相关的安全注意事项]
   • 保护用户隐私，确保用户数据安全。
   • 防止API Key泄露，避免未授权访问。
   • 定期更新软件，修复已知安全漏洞。
   • 限制技能使用范围，防止滥用。
   • 对外提供的服务应进行合规检查，确保服务安全。

安全风险防范

风险项	等级	防护措施	验证方法
API密钥泄露	高	通过环境变量配置，禁止硬编码	定期检查代码和配置文件
命令执行风险	高	仅执行白名单命令，避免拼接用户输入	使用沙箱环境测试
网络通信安全	中	使用HTTPS协议，验证SSL证书	定期检查证书有效期
敏感数据暴露	高	输出结果中不包含密钥、令牌等敏感信息	日志脱敏审查
未授权访问	中	限制访问权限，实施认证机制	定期审计访问日志