用途
当 Dobby 工作区需要一个可见、可复用的工作表面,且用户与 Dobby 都能打开、回访并改进它时,使用此技能。Dobby artifact 不是单纯的临时预览,也不只是文档,而是一个由工作区拥有的界面,例如 HTML 工作表、追踪器、仪表盘、表格、计算器、地图、时间线或由契合任务的本地数据模式支撑的可视化报告。
所有权规则
除非用户明确指定其他工作区,否则在当前的 Dobby 工作区(~/GitHub/adi 或 ~/GitHub/angie)中工作。将个人私密的 artifact 内容保留在该人的工作区中。将共享的托管、仪表盘列表、路由或引擎行为放在 ~/GitHub/dobby-engine 中。将技能/控制面变更放在 ~/GitHub/agents 中。除非变更确实是机器本地的服务管道,否则不要将 ~/GitHub/scripts 用于 artifact 行为。保持实现与工作区无关。除非 artifact 内容本身是个人性的,否则不要硬编码 Angie 或 Adi。
何时适合使用 Artifact
当工作是可视化的、可交互的、可回访的,或者作为受限界面比散文更易于使用时,创建或提升一个 artifact。不要在以下情况使用 artifact:应属于 canon.md 的简单持久事实;应属于 Shelf 的开放循环或提醒;原始日志/签到文本;不需要回访的一次性草稿文件。如果临时预览变得足够有用而值得保留,就将其提升到下述标准容器中。
标准容器
在创建或更改持久 artifact 容器之前,请阅读 references/artifact-contract.md。默认位置:memory/areas/<area>/artifacts/<slug>/,其中包含 artifact.json、index.html、可选的 data/ 源数据、可选的 style.css、可选的 script.js、可选的 assets/。该文件夹是稳定的边界。在其中选择最适合该 artifact 的最简单源/数据模式。
真实来源选择
为用户做选择;不要让非技术用户去决定实现格式。推荐默认值:对于结构化工作表、追踪器、表格和类仪表盘视图,使用 JSON + HTML;对于小型静态说明或精美的单页视图,仅用 HTML;当散文是主体但更好的可见界面有帮助时,使用 Markdown + HTML;仅当用户会现实地以 CSV 维护表格数据时,才使用 CSV + HTML;仅当用户需要原生电子表格公式、透视或 Excel 编辑时,才使用 XLSX,否则避免将 Excel 保留为隐藏的真实来源。用通俗语言简要解释选择理由。
工作流程
- 确定工作区、领域和 slug。
- 创建或更新 memory/areas/<area>/artifacts/<slug>/。
- 决定内部源模式并确立一个清晰的真实来源。
- 编写或更新 artifact.json。
- 构建可见的入口文件,通常为 index.html。
- 如果仪表盘支持缺失或需要改进,在 dobby-engine 中修改通用行为,而不是在个人工作区中修改。
- 使用每个被触及仓库的快速检查进行验证。
- 如有用,为用户打开本地仪表盘 URL。
仪表盘预期
Dobby 仪表盘可在 /artifacts/<area>/<slug>/ 暴露已声明的 artifact。只有已声明的 artifact 文件夹才应被托管。不要添加对任意工作区文件的广泛静态托管。被固定的 artifact 可以作为工作表面出现在仪表盘主页上。将该行为保持通用并共享于 dobby-engine 中。