# kt-auto-cad

**Repository Path**: phoenixwing/kt-auto-cad

## Basic Information

- **Project Name**: kt-auto-cad
- **Description**: KT Auto CAD 是 KT Auto Code 的 CAD 开发扩展，为 VS Code 提供 CAA/C++ 工程辅助、CAD 模块集成与自动化开发工具
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-07
- **Last Updated**: 2026-08-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# KT Auto CAD

`KT Auto CAD` 是 `KT Auto Code` 的可选 CAD 模块，必须与 `kuntai.kt-auto-code` 基础插件一起使用。

## Code 与 CAD 功能关系

![KT Auto Code 与 KT Auto CAD 功能关系](docs/assets/KT-Auto-Code-CAD功能关系.png)

本目录同时是独立仓库与扩展包根目录，源代码、测试、构建、lockfile 和 VSIX 发布节奏均不再由 KT Auto Code 仓库管理。仓库地址为 [PhoenixWing321/kt-auto-cad](https://gitee.com/PhoenixWing321/kt-auto-cad)。扩展 ID 仍为 `kuntai.kt-auto-cad`，版本仍为 `0.1.0`。

当前版本已验证双 VSIX、共享 Primary Side Bar、Shell API v2，以及 Wing CAD 契约与 CAD 深度读取器 protocol v1。Code/CAD 是原生 View Header 中可独立勾选的模块标签；模块 manifest 把工具定义交给基础插件的共享 Ribbon，CAD 通过 Block provider 只提交标题、状态、Header action 和内容片段。容器、Header、关闭、已打开/当前状态及 MRU 恢复全部由基础插件统一管理，CAD 不再贡献自己的 View。

文件名语义、工作区 FCStd 检索、SQLite 文件索引和基础 BOM 分析直接消费 `@phoenix-wing/cad-core`、VS Code 文件 API 与 TypeScript，不要求安装 Desk Tools。只有“读取 FCStd 内容”的深度对象分析在实际执行时要求 CAD 深度读取器；该读取器随 Desk Tools 安装，但执行时不要求 Desk Tools 窗口或本地 API 正在运行。

“读取”Block 提供两级能力：“TS 轻量读取”直接解压单个 FCStd 的 `Document.xml`，展示对象数量、XLink 和工作区目标诊断；“Desk 深度读取”是可选增强，用于完整对象属性和原生 BOM 数据。未安装 Desk Tools 不会隐藏或禁用轻量读取。

“只读分析 FCStd”只调用 `--protocol 1 read`，不导入数据库 adapter、不创建 `.phoenix`，也不会修改所选文件。native 错误 envelope 会转换为可诊断的信息，不把无效 JSON 当作成功结果。

“扫描工作区 FCStd”使用 VS Code `findFiles`，忽略 `.git` 与 `node_modules`，最多展示 5000 个结果；它只枚举文件，不会自动批量启动 native 进程。

“扫描并更新 SQLite 索引”先用 VS Code API 找到工作区 FCStd，再以纯 TypeScript 从 ZIP 容器读取 `Document.xml`，提取文件名语义和 XLink，写入 `.phoenix/phoenix-workspace.sqlite` 的标准 Schema v13 表。单个文件无法轻量解析时仍会进入文件索引，并记录解析错误；递归 XLink 形成的 BOM 是基础分析，不替代 Rust 对复杂 FreeCAD 对象和精确数量的深度读取。

“搜索文件索引”可按路径、文件名、零件号、版本和名称检索。“查询 BOM 与引用”以只读模式打开同一数据库，执行 Wing `cad-contracts` 中与 `phoenix-cad-query` v1 对齐的参数化查询，展示基础 BOM 树和入向/出向引用摘要。插件不会携带第三方 SQLite/WASM；旧版 Extension Host 缺少 `node:sqlite` 时会保留 VS Code 文件扫描能力并提示升级。

本插件不注册 Activity Bar View Container。安装后仍只使用 `KT Auto Code` 的一个图标，并在工具栏原生 Header 中出现 Code/CAD 切换操作。

本插件是 thin companion，不在 VSIX 内置 Rust 二进制。Desk Tools 从 `@phoenix-wing/cad-rust-source` 编译并随桌面安装包发布 `runtime/native-provider.json`；基础插件优先从 Desk Tools 的持久安装注册自动发现该清单，也允许在统一的 `KT Auto Code › Desk Tools` 设置中手动覆盖。插件使用 Wing `cad-contracts` v1 guard 校验平台、相对路径、SHA-256、能力及 `fcstd-read`/`fcstd-xlink` 的 `--protocol-version`。未发现读取器时，文件名分析、工作区检索、基础 View 和已有数据库查询仍可使用。

当前仓库从 npm Registry 精确消费 Wing CAD 小包 `0.6.2`，不通过 pnpm override、`link:`、`file:` 或 `workspace:` 解析相邻工作副本；发布包中的算法由 esbuild 收入 thin bundle。Workspace Schema 兼容性 fixture 直接来自 Registry，未知未来版本按 fail-closed 策略拒绝写入。`kuntai.kt-auto-cad@0.1.0` 已完成 Marketplace 首发并通过人工审查；完整 Desk Tools native provider 端到端验收仍作为独立实机项保留。

## 独立验证

工程要求 Node.js 22 或更高版本，并锁定 pnpm 10.15.1。安装依赖后可分别执行：

```bash
pnpm test
pnpm typecheck
pnpm build
pnpm package
pnpm verify:artifact
```

`pnpm dev`、`pnpm dev:check`、`pnpm dev:prepare`、`pnpm dev:registry`、`pnpm build` 与 `pnpm package` 全部以独立 `pnpm-lock.yaml` 中的 Registry 依赖为准。正式 build/package 检测到本地 Wing 环境变量会直接拒绝；供 Auto orchestrator 调用的 `dev:prepare` 会先清理上游注入的本地 Wing 变量，再执行相同的 Registry 测试、类型、架构与构建门禁。

## 发布

正式发布建议使用独立 worktree：`../.worktrees/kt-auto-cad-release`。在干净的目标提交上以 frozen lockfile 安装依赖并运行 `pnpm release:check`；可发布 VSIX 与 SHA-256 校验文件会写入已忽略的 `dist/vsix/`，不会进入 Git 或 VSIX。

```bash
cd ../.worktrees/kt-auto-cad-release
git switch --detach <tag或commit>
git status --short
nvm use 22
pnpm install --frozen-lockfile
pnpm release:check
```

发布 worktree 固定复用，但每次必须 detached 到明确 tag 或 commit，不能依赖某个本地分支当时指向哪里。`pnpm release:check` 完成测试、类型、架构、Registry 依赖、打包与制品校验；只需重新生成候选时可使用 `pnpm package && pnpm verify:artifact`。`pnpm package` 内部转发到与 KT Auto Code 一致的 `pnpm ext:package`。

完整准备、验收与收尾步骤见[发布说明](docs/发布.md)。

功能边界、研究与历史记录见[文档索引](docs/README.md)。

## Wing 依赖策略

CAD 近期固定消费 npm Registry 已发布的 `@phoenix-wing/cad-core`、`@phoenix-wing/cad-contracts` 与 `@phoenix-wing/workspace-schema` `0.6.2`。本地开发和正式发布使用同一套已发布依赖，不解析相邻 `phoenix-wing` 源码，也不跟随未发布候选版本。

`pnpm dev:prepare` 仍是供 KT Auto Code orchestrator 调用的稳定无 GUI 接口。Auto 可以自行联调更新的 Wing 候选，但传给 CAD 的 `PHOENIX_WING_ROOT`、开发模式和 wrapper 标记会在 CAD runner 中清理；CAD 随后仍以已提交 lockfile 完成 Registry 依赖检查、测试、类型、架构和构建。

只有当 Wing 新版本已经正式发布、CAD 确有采用需求并完成兼容性评估时，才同时精确升级三个 manifest 版本与 `pnpm-lock.yaml`，再执行 `pnpm release:check`。禁止手写未发布版本、虚假 integrity、`link:`、`file:`、`workspace:` 或本地 override。仓库不归档本机开发二进制，thin VSIX 也拒绝携带 native provider。