| name | tuna-revit-toolkit |
| description | Guides building Revit add-ins with Tuna.Revit.Extensions/Infrastructure (commands, ribbon, selection, transactions). Invoke when user asks how to do X with Tuna or is coding a Revit add-in. |
Tuna.Revit.Toolkit Skill
本技能是关于如何在 Revit 二开中使用 Tuna.Revit.Toolkit（常见为 Tuna.Revit.Extensions 与 Tuna.Revit.Infrastructure）完成查询、选择、事务、变换、Ribbon 与命令编写。
Use this skill when the user asks practical “how to do X with Tuna” questions: Document queries, selection, transactions, transforms, ribbon wiring, and command patterns.
Quick routing / 快速定位
按功能分级把需求路由到 resources/ / templates/，再从对应小节复制最短可运行代码。
A) 入口与 UI（App / Ribbon / Command）
- App 入口（OnStartup / InitailizeComponents）→
templates/app.tmpl.cs + resources/02-ribbon-wiring.md
- Ribbon 挂载（Tab / Panel / Button / Icon）→
resources/02-ribbon-wiring.md
- Command 骨架 / 命令上下文（UIApplication/UIDocument/Document）→
templates/command.tmpl.cs + resources/03-command-context.md
B) 交互与数据（Query / Selection）
- 图元查询 / element query（Document.GetElements...）→
resources/01-element-query.md
- 单选 / select one element（SelectElement）→
resources/04-selection.md
- 多选 / select multiple elements（SelectElements）→
resources/04-selection.md
- 框选 / select by rectangle（SelectElementsByRectangle）→
resources/04-selection.md
直接参考：04-selection.md:L89-L109
- 点选 / pick point（SelectPoint）→
resources/04-selection.md
C) 修改模型（Transactions / Transforms）
- 事务 / transactions（NewTransaction / NewTransactionGroup）→
resources/05-transactions.md
- 变换 / transforms（Move / Rotate / Transform）→
resources/06-transforms.md
D) 进阶（ExternalEvent / Transient / Pitfalls）
- 外部事件 / external event（非 Revit 上下文回到 Revit API）→
resources/03-command-context.md（ExternalEvent 段落）
- 临时显示 / transient display（TransientDisplay）→
resources/06-transforms.md（TransientDisplay 段落）
- 常见坑 / pitfalls →
resources/07-pitfalls.md
Fastest path / 最短上手路径
目标：用最少代码把 “App + Ribbon + Command” 跑起来，然后再叠加 selection / transaction / query。
1) Application 入口（Revit 启动时注册 Ribbon）
推荐继承 TunaApplication 并实现 InitailizeComponents()：
- 可复制骨架：
templates/app.tmpl.cs
- 详细说明：
resources/02-ribbon-wiring.md
2) Command 入口（从 TunaCommand 拿上下文 + 写业务）
推荐继承 TunaCommand，并在 Execute() 中拿到 UIApplication/UIDocument/Document：
- 可复制骨架：
templates/command.tmpl.cs
- 详细说明：
resources/03-command-context.md
3) 在事务里修改模型（推荐用 Extensions 的 NewTransaction）
修改模型必须进事务：优先使用 document.NewTransaction(...) / document.NewTransactionGroup(...)：
- 详细说明：
resources/05-transactions.md
How to use / 使用方式
当被调用时，请按以下顺序组织输出：
- 先给出最短路径（最少代码、最少步骤）让用户跑起来
- 再补充可选增强（过滤器、错误处理、多版本兼容、性能）
- 输出可直接粘贴的代码片段，并引用仓库内已有模式（如
TunaApplication / TunaCommand）
Patterns / 输出模式（写答案时的默认套路）
- 如果用户问“怎么写插件入口 / Ribbon 怎么挂” → 先给
TunaApplication + AddRibbonTab + AddRibbonPanel + AddPushButton 的最短骨架，再补 CommandButtonAttribute 与图标路径规则。
- 如果用户问“怎么选 / 框选 / 点选” → 直接用
SelectionExtensions，并提醒用 SelectionResult<T>.SelectionStatus 判断是否 Cancelled。
- 如果用户问“怎么改模型 / 移动旋转” → 先包
document.NewTransaction(...)，再用 Revit API（如 ElementTransformUtils），并提示 pinned/constraints/group 失败场景。
- 如果用户问“怎么在非命令上下文改模型” → 先用
IExternalEventService.PostCommand(...) 把动作投递回 Revit 上下文。
Knowledge layout / 知识结构
- 治理入口：
metadata.yaml（版本、触发、归属等）
- 稳定性基座：
examples/（输入输出示例）
- 结构一致性：
templates/（可复用代码骨架）
- 确定性能力：
scripts/（可执行检查/生成逻辑）
- 知识上下文：
resources/（按需引用的详细说明）
优先从 resources/ 选择最相关小节组合答案；需要给出“可复制骨架”时，引用 templates/；需要展示期望输出形态时，引用 examples/。
