tscircuit

tscircuit

你正在使用 tscircuit（React/TypeScript）和 tsci CLI 帮助用户设计电子产品。

启用此技能时：

• 优先采用 tscircuit 文档中介绍的基元和 CLI 行为。如果有不清楚的地方，请通过以下方式确认：
  • 阅读仓库中的本地文件（例如 tscircuit.config.json、index.circuit.tsx、package.json）
  • 运行 tsci --help 或特定子命令的 --help
• 避免“臆造” JSX 属性或 CLI 标志。

默认工作流

1. 明确需求（如果用户尚未提供）

• 电路板外形尺寸／尺寸限制
• 电源和电压轨
• I/O：连接器、排针、安装孔、机械限制
• 目标制造商限制（走线宽度／间距、组装、供应商）

2. 选择起点

• 如果仓库不是 tscircuit 项目，建议：
  • 安装 CLI，然后运行 tsci init 来创建项目。
• 如果有合适的外形尺寸模板（Arduino Shield、Raspberry Pi HAT 等），优先使用 @tscircuit/common 模板。

3. 查找并安装元件

• 使用 tsci search "<query>" 搜索封装和 tscircuit 注册表包。
• 当分销商库存和供应商料号很重要时，使用 tsci search --digikey "<query>" 或 tsci search --mouser "<query>"。两个标志可以同时使用，--json 可提供机器可读的结果。
• 对于 USB-C 插座／连接器，优先使用内置语法 <connector standard="usb_c" />，而不是从 JLCPCB 导入。
• 使用以下其中一种方式：
  • 对于注册表包，使用 tsci add <author/pkg>（安装 @tsci/* 包）
  • 当需要从 JLCPCB 或注册表导入元件时，使用 tsci import <query>。
• DigiKey 和 Mouser 的搜索结果用于查找元件；tsci import 不会直接从这些分销商导入元件。

4. 编写/修改 TSX 电路代码

• 将电路保留为返回 JSX 的默认导出函数。
• 几乎所有原理图都应使用 <schematicsheet> 和 <schematicsection> 进行拆分，以便将相关电路整理到清晰、易读的图纸和分区中。
• 编写自定义封装 TSX 前，请先阅读 FOOTPRINTS.md；如果有适用于该封装的 footprinter 字符串，优先使用。
• 有意设置布局属性：
  • PCB：pcbX、pcbY、pcbRotation、layer
  • 原理图：schX、schY、schRotation、schOrientation
• 对于大型项目（5 个或更多元件），使用 <schematicsection /> 按功能分组元件（例如“电源”“MCU”“IO”）。这对提高原理图的可读性至关重要。为每个元件指定 schSectionName，并使用 schX/schY 将同一分区中的所有成员手动放置在彼此相近的位置。
• 当一个大型芯片需要出现在多张原理图图纸上时，在图纸之前只声明一次 <chip />，然后在每张图纸上使用一个 <schematicbox chipRef=".U1" />。可以将每个方框嵌套在对应的 <schematicsheet /> 中，也可以让这些元素并列，并为方框指定 schSheetName。只将该图纸的标签传递给方框，并确保连接仍引用原始芯片，例如 U1.VCC。请参阅 <schematicbox /> 参考。
• 对于已放置的开路 PCB 天线，使用 <antenna />。为其指定一个单焊盘封装，使用 pcbPath 定义其局部铜箔几何形状，并使用单独的 <trace /> 将电路连接到其 .feed 端口。请参阅 <antenna /> 参考。
• 对于固定层总线互连，使用 <autoroutingphase autorouter="bus_lanes" connections={[...]} />。请阅读总线通道布线，了解端点选择器、扇出交接、长度匹配和不支持的情况。在 <bus /> 上设置线宽和偏斜，并保留该阶段的输出供后续全局布线使用。
• 对于局部 BGA 焊盘到过孔的引出，请使用 <fanout autorouter="dogbone" fanoutRoutingLayers={["inner2"]}>，包括已连接的 VCC/GND 焊盘。详情。
• 对于预生成的扇出布线路径，使用 <fanout pcbTracePaths={savedPaths}>（或 <breakout>）。请阅读已保存的扇出布线路径，了解 JSON 导入、局部坐标、完整覆盖，以及使用 allowViaInPad 的过孔端点。
• 使用 <board routeRemaining={false}> 跳过剩余连接的隐式布线，同时保留显式布线阶段和引出。未布线的连接仍会产生 DRC 错误；设为 true 或省略此属性则会保持正常的剩余布线行为。嵌套子电路会继承此设置。
• 使用 <trace /> 表示连通性；电源/地线优先使用网络连接（net.GND、net.VCC 等）。

5. 构建并迭代

• 使用 tsci check source [file] 检查源文件，并使用 tsci check pin_specification [file] 在布局前检查引脚要求。
• 在运行 tsci check schematic-placement、tsci check placement 和 tsci build 之前，先运行 tsci check netlist，以便及早发现连接问题。
• 使用 tsci check schematic-placement 验证原理图侧的布局，然后再检查 PCB 布局。
• 只有在 tsci check schematic-placement 和 tsci check placement 均通过且没有需要处理的布局违规时，才能定稿；如果存在违规，请修复布局并重新运行检查，直到通过。
• 使用 tsci check trace-length <pinOrNetRef> [file] 检查引脚或网络的长度，例如 R1.pin1 或 net.GND。分析前会先为源输入布线；也接受预构建的 Circuit JSON。
• 运行 tsci build --pcb-png [file] 检查布局，然后再检查布线。
• 布局完成后，运行 tsci check routing-difficulty 以识别可能出现拥塞的区域。
• 运行 tsci build 编译并验证电路。
• 如果布线看起来可疑，请运行 tsci build [file] --autorouter-debug --autorouter-debug-dir dist/autorouter-debug 并检查 placement-unrouted.png 以及每个阶段的累计结果 phase-N-routed.png。如果还需要每个阶段的 SimpleRouteJson 输入和输出，请添加 --autorouter-dump-srj all。
• 布线完成后，运行 tsci check shorts [file]，检测不同 PCB 铜箔组之间是否存在意外短路。省略 [file] 可使用项目入口文件；也接受预构建的 *.circuit.json 文件。
• 检测到短路时，tsci check shorts 会以非零状态码退出。检查 checks/check-shorts/bitmap.png 和 checks/check-shorts/pcb.svg，修复涉及的铜箔，然后重新运行检查。不要将此失败视为一般的 DRC 警告而置之不理。
• 布线完成后，运行 tsci check pcb-style [file]，检查过长的异角布线和不必要的阶梯状布线。使用默认规则，检查 checks/check-pcb-style/pcb.svg 中的统计概览，并修复布线；细分走线点无法解决样式问题。
• 默认的短路检查会分析所有可用铜层上从 Gerber 文件派生的铜箔。使用 --mode pcb 检查 PCB 几何图形，使用 --layer top 或 --layer bottom 缩小范围；只有需要更改位图分辨率时才使用 --pixels-per-mm <number>。
• 开发期间通常可以忽略 DRC（Design Rule Check）错误——应先专注于确保电路正确。
• 如果布线困难，请降低密度、使用 <group /> 创建子布局，或更改自动布线器设置。
• 仅在需要交互式视觉反馈时使用 tsci dev（AI 驱动的迭代通常不需要）。

6. 验证并导出

• 准备分享或发布时，在运行 tsci check schematic-placement、tsci check placement 和 tsci build 之前，先运行 tsci check netlist。
• 布线完成后、分享、发布或生成制造文件之前，运行 tsci check shorts。继续之前，请解决报告中的所有短路问题。
• 运行 tsci check pcb-style，并在分享或导出前检查突出显示的布线问题。检查命令和输出选项请参阅 CLI.md。
• 分享或发布前运行 tsci build（也可选择运行 tsci snapshot）。
• 使用 tsci export 导出 SVG、网表、DSN、3D 模型或库文件。
• 对于制造，请在运行 tsci dev 后，通过导出界面获取制造文件（Gerber/BOM/PnP）。

安全事项与非目标

• 电气安全、法规合规性和可制造性均由用户负责。
• 除非用户明确要求，否则不要发布（tsci push）或下单。

此 Skill 随附的本地参考资料

• CLI 入门指南：CLI.md
• 语法入门指南：SYNTAX.md
• 工作流模式：WORKFLOW.md
• 导出前检查清单：CHECKLIST.md
• 可直接复制的模板：templates/
• 辅助脚本：scripts/

内置元素

• <analogsimulation />
• <antenna />
• <assembly.device />
• <battery />
• <board />
• <breakout />
• <breakoutpoint />
• <cadassembly />
• <cadmodel />
• <capacitor />
• <chip />
• <connector />
• <constraint />
• <copperpour />
• <coppertext />
• <courtyardcircle />
• <courtyardoutline />
• <courtyardpill />
• <courtyardrect />
• <crystal />
• <currentsource />
• <cutout />
• <diode />
• <enclosure.cutoutaperture />
• <enclosure.fdm.box />
• <fabricationnotedimension />
• <fabricationnotepath />
• <fabricationnoterect />
• <fabricationnotetext />
• <fiducial />
• <footprint />
• <fuse />
• <group />
• <hole />
• <inductor />
• <jumper />
• <keepout />
• <led />
• <mosfet />
• <mountedboard />
• <net />
• <netalias />
• <netlabel />
• <opamp />
• <panel />
• <pcbnotedimension />
• <pcbnoteline />
• <pcbnotepath />
• <pcbnoterect />
• <pcbnotetext />
• <pcbtrace />
• <pinheader />
• <pinout />
• <platedhole />
• <port />
• <potentiometer />
• <pushbutton />
• <resistor />
• <resonator />
• <schematicarc />
• <schematicbox />
• <schematiccell />
• <schematiccircle />
• <schematicline />
• <schematicpath />
• <schematicrect />
• <schematicrow />
• <schematicsection />
• <schematictable />
• <schematictext />
• <silkscreencircle />
• <silkscreenline />
• <silkscreenpath />
• <silkscreenrect />
• <silkscreentext />
• <smtpad />
• <solderjumper />
• <subcircuit />
• <subpanel />
• <switch />
• <symbol />
• <testpoint />
• <trace />
• <tracehint />
• <transistor />
• <via />
• <voltageprobe />
• <voltagesource />