@phoenix-wing/kt-codegen 0.4.1

package/doc/CAA/345/257/271/350/257/235/346/241/206/351/200/232/347/237/245/345/235/227/350/277/201/347/247/273.md

@@ -0,0 +1,45 @@
+# CAA 对话框通知块迁移
+
+本文记录 ID 14 `DIALOG NOTIFY` 的迁移结果。该块为 CAA Dialog Agent 生成各控件的 `AcceptOnNotify` 注册语句。
+
+## 旧实现与新边界
+
+权威依据是归档基线 `KtaAutoCodeBase/KevinCAAFileGuide.vb` 的 `CreateCAADialogNotifyValueChange`。TypeScript 实现在 [`KtCodegenRenderer.ts`](../src/KtCodegenRenderer.ts)；基线位置见[《来源与许可归档》](来源与许可归档.md)。
+
+Renderer 只消费 `KtCodegenParam` 和已扫描区域，不修改 Item。旧 VB 在单个 RadioButton 分支会把共享 `ComponentCount` 从1改为2；新实现使用局部 `count = 2` 生成完全相同的两条通知语句，但不产生隐式数据副作用。这符合当前 `KtCodegenRenderer` 的只读契约，也避免 Analyze 改变 UI 表格。
+
+## Item 选择与公共命名
+
+- 只消费当前 `NameSuffix`；
+- `id < 1` 跳过；
+- 每个保留 Item 前生成空行和 `// ID, ParamString` 注释；
+- `ParamString` 中所有下划线在控件成员名中删除；
+- `isParamDlg === true` 时控件名前增加 `dialogMore->`；
+- `componentCount <= 0` 只输出 `NO ACTION` 注释。
+
+## 组件分支
+
+所有组件判断保持旧代码的大小写敏感规则。
+
+| Component 条件 | 生成行为 |
+| --- | --- |
+| 精确 `Spinner` | 标量生成一条 Spinner 通知；旧 CAA 点/向量/方向生成 X、Y、Z 三条 |
+| 以 `CheckButton` 开头 | count=1 使用无下标成员；其他数量生成 0～count-1 |
+| 以 `RadioButton` 开头 | count=1 按2处理；其他数量生成 0～count-1 |
+| 以 `Combo` 开头 | 不论 count，生成一个 Combo 通知 |
+| 精确 `Editor` | count=1 使用无下标成员；其他数量生成数组式成员 |
+| 其他正数量 | 输出 `NOT SUPPORT` 注释，不生成注册语句 |
+
+CAA 向量判断复用 `KtCodegenCore.isCaaVector`。`CATMathVector` 等 CAA 类型使用 XYZ；`KtMathVector` 不属于这一旧集合，因此仍按单 Spinner 生成。
+
+## 目标状态
+
+显式只请求 `DIALOG NOTIFY` 时，`caa.dialog` 可以返回 `ready` 和可关联区域的 artifact。`UPDATE DIALOG`、`UPDATE INFORS` 与 ID 19～21 的 Dialog Field 块也已在后续阶段迁移，因此默认请求该目标全部六块时同样返回 `ready`。只有源码中实际存在 ID 20、21 标记并生成兼容代码时，计划才附带废弃 warning。
+
+## 回归证据
+
+- [`caa-dialog-notify.cpp`](../tests/fixtures/source/caa-dialog-notify.cpp)：旧标记块；
+- [`dialog-notify.txt`](../tests/fixtures/expected/caa-dialog/dialog-notify.txt)：逐行 golden；
+- [`caa-dialog-renderer.test.ts`](../tests/caa-dialog-renderer.test.ts)：覆盖 Spinner 标量/CAA向量/Kt向量、Check、Radio、Combo、Editor、子对话框、No Action、不支持组件、ID/后缀过滤和共享数据不变性。
+
+本阶段只生成 Analyze Plan，不执行真实源码写入。

package/doc/CAA/346/216/245/345/217/243/345/244/264/346/226/207/344/273/266/345/235/227/350/277/201/347/247/273.md

@@ -0,0 +1,75 @@
+# CAA 接口头文件块迁移
+
+本文记录 CAA 实现类与纯虚接口类头文件中四个 Get/Set 自动代码块的 TypeScript 迁移结果。
+
+## 迁移范围
+
+| ID | block key | 旧 VB 调用 | 新目标 | 状态 |
+| ---: | --- | --- | --- | --- |
+| 4 | `IMPLEMENTS HEAD GET` | `CreateCAAInterfacesGet(False)` | `caa.core` | 已迁移 |
+| 5 | `IMPLEMENTS HEAD SET` | `CreateCAAInterfacesSet(False)` | `caa.core` | 已迁移 |
+| 8 | `INTERFACES HEAD GET` | `CreateCAAInterfacesGet(True)` | `caa.model` | 已迁移 |
+| 9 | `INTERFACES HEAD SET` | `CreateCAAInterfacesSet(True)` | `caa.model` | 已迁移 |
+
+权威依据是归档基线 `KtaAutoCodeBase/KevinCAAFileGuide.vb` 中的 `CreateCAAInterfacesGet`、`CreateCAAInterfacesSet` 和 `CodeAppendNotes`。TypeScript 实现在 [`KtCodegenRenderer.ts`](../src/KtCodegenRenderer.ts)，列表判断由 `KtCodegenCore.isParamSpecList` 注入 Renderer，避免复制类型规则；基线位置见[《来源与许可归档》](来源与许可归档.md)。
+
+## 共享数据与过滤
+
+四块都直接消费同一个 `KtCodegenParam.items`，按数组顺序筛选当前标记的 `NameSuffix`：
+
+- `id === -1` 跳过；
+- `100 <= id < 200` 跳过；
+- ID 0、其他负数和 ID 200 以上保持旧行为，继续生成；
+- 其他 `NameSuffix` 的 Item 不进入当前类；
+- Reader、Renderer 和 Analyze 都不修改共享 Item。
+
+这一规则与普通 C++ Parameter 块的 `id >= 1` 不同，因此分别保留，不能抽成一个统一过滤条件。
+
+## Get 生成规则
+
+实现类块生成普通成员声明，接口类块增加 `virtual` 和 `= 0`：
+
+```cpp
+int GetMachineId() const;
+virtual int GetMachineId() const = 0;
+```
+
+`KtCodegenCore.isParamSpecList` 为 false 时，Get 直接返回 `DataType`；为 true 时改为旧 CAA 的 `HRESULT + 引用输出参数`：
+
+```cpp
+HRESULT GetGuardLength(double& value) const;
+virtual HRESULT GetGuardLength(double& value) const = 0;
+```
+
+Doxygen `@return` 与函数形式使用同一次列表分类规则。3D 点/向量的优先排除顺序沿用 Core 已有 golden，不会因为 `isList = true` 自动变成列表 Get。
+
+## Set 生成规则
+
+Set 不区分标量与列表，统一保留旧签名：
+
+```cpp
+HRESULT SetMachineId(const int& value, const CATBoolean& checkExist = CATTrue);
+```
+
+纯虚接口版本在末尾增加 `= 0`。Doxygen 保留 `@param[in] value <DataType>`、`@return HRESULT`、可选 author/date/note 和稳定 ID。
+
+## 历史格式兼容
+
+- `public: // Get` 和 `public: // Set` 来自旧 `CodeAppendLine`，不附加 Start 行的 `linePrefix`；
+- 注释和函数声明继续使用 Start 标记提取的 `linePrefix`；
+- Start/End、`clang-format off/on`、文件换行和末尾换行复用公共区域 artifact 逻辑；
+- 每个 artifact 绑定 `regionId`，并由 Analyze 验证区域存在。
+
+## 目标状态
+
+`caa.core` 当前矩阵只有 ID 4、5，因此请求这两个块时目标为 `ready`。
+
+ID 1 `FACTRY ON TREE` 已在后续阶段迁移，因此 `caa.model` 的 Factory 与 ID 8、9 均已完成。使用默认全部 block key 时，CAA Model 不再因本目标遗留块保持 scaffold。
+
+## 回归证据
+
+- [`caa-interface-heads.hpp`](../tests/fixtures/source/caa-interface-heads.hpp) 保存四个待替换旧块；
+- [`expected/caa-interface`](../tests/fixtures/expected/caa-interface) 保存四份逐行 golden；
+- [`caa-renderer.test.ts`](../tests/caa-renderer.test.ts) 覆盖实现/纯虚差异、列表 Get、部分迁移状态、ID 边界和后缀过滤。
+
+本阶段仍只产生 Analyze Plan，不负责真实文件写回。

package/doc/CAA/347/211/271/345/276/201/350/257/273/345/206/231/345/235/227/350/277/201/347/247/273.md

@@ -0,0 +1,77 @@
+# CAA 特征读写块迁移
+
+本文记录 CAA 实现类单参数 Get/Set，以及 Param 聚合对象桥接 Get/Set 四个 Feature I/O 自动代码块的迁移结果。
+
+## 迁移范围
+
+| ID | block key | 旧 VB 方法 | 新目标 | 状态 |
+| ---: | --- | --- | --- | --- |
+| 2 | `IMPLEMENTS CPP GET` | `CreateCAAImplementsCppGet` | `caa.feature-io` | 已迁移 |
+| 3 | `IMPLEMENTS CPP SET` | `CreateCAAImplementsCppSet` | `caa.feature-io` | 已迁移 |
+| 6 | `IMPLEMENTS PARAM GET` | `CreateCAAImplementsCppParamsClassGet` | `caa.feature-io` | 已迁移 |
+| 7 | `IMPLEMENTS PARAM SET` | `CreateCAAImplementsCppParamsClassSet` | `caa.feature-io` | 已迁移 |
+
+权威依据是归档基线 `KtaAutoCodeBase/KevinCAAFileGuide.vb` 中对应四个方法。TypeScript 实现在 [`KtCodegenRenderer.ts`](../src/KtCodegenRenderer.ts)。Renderer 通过 `KtCodegenCaaAlgorithms` 使用 Core 中已验证的列表判断、默认值格式化和末尾大写字符解析，不复制这些规则；基线位置见[《来源与许可归档》](来源与许可归档.md)。
+
+## 两组不同的 ID 边界
+
+CPP 单参数函数与上一阶段接口头文件相同：
+
+- 跳过 `id === -1`；
+- 跳过 100～199；
+- ID 0 和 ID 200 以上继续生成。
+
+Param 聚合对象桥接使用更严格的旧规则，只允许 ID 1～99。ID 0、负数以及所有 ID 100 以上均跳过。两组 artifact 的 `sourceParameters` 保存实际参与生成的参数名，可供 UI 和测试审计。
+
+## CPP Get
+
+类名沿用旧 `GetECPPClassName`：
+
+```text
+NamePrefix + "E" + NameMiddle + NameSuffix
+```
+
+标量 Get 先用默认值构造局部 `value`，调用 `GetValue`，再返回 `value`。无默认值时生成普通未初始化声明。
+
+以下分支保持旧行为：
+
+- `tcKind === "tk_integer"` 且 `dataType` 不区分大小写后不是 `int`：先读入 `int`，返回时强制转换为目标枚举；`tk_integer` 本身仍区分大小写；
+- `tcKind` 不区分大小写等于 `tk_specobject`：使用 `GetSpecValue`；
+- 列表参数：返回 `ktcSpecRW.GetListValue` 的 `HRESULT`；
+- `dataType` 精确等于 `<NameSpace>::SpecObjectCollect`：先 `RemoveAll`，再设置 `GetIsOrderBySerial`；参数名末尾存在单独大写字母时附加该后缀。
+
+旧 VB 在 `SpecObjectCollect` 的第二个内嵌换行后只写四个空格，丢失块 `linePrefix`。TypeScript golden 有意保留这一历史输出，避免迁移时产生未审阅的格式变化。
+
+## CPP Set
+
+所有函数返回 `HRESULT`，并保留 `checkExist` 参数：
+
+- 列表使用 `SetListValue`；
+- SpecObject 使用 `SetSpecValue`；
+- `tk_integer` 枚举先转换为局部 `int valueInput`，再调用 `SetValue`；
+- 其他标量直接调用 `SetValue`。
+
+分支优先级与旧方法一致：列表优先于 SpecObject 和枚举转换。
+
+## Param 聚合对象桥接
+
+Get 对标量执行赋值，对列表传入聚合对象成员作为引用：
+
+```cpp
+value.MachineId = GetMachineId();
+GetGuardLength(value.GuardLength);
+```
+
+Set 逐项调用单参数 Set。失败时向既有 `msg` 追加带 `\n` 的错误文本并设置 `findError`；全部 Item 完成后统一调用 `SetErrMsg` 并返回 `E_FAIL`。旧代码中 `msg`、`findError` 的声明已被注释，因此 Renderer 不擅自新增变量。
+
+## 目标状态与回归证据
+
+ID 0 `CATALOG PARAMS` 已在后续阶段迁移，因此 `caa.feature-io` 的 Catalog 与本阶段四块均已完成。默认请求全部 block 时，该目标不再因本目标遗留块保持 scaffold。
+
+回归材料：
+
+- [`caa-feature-io.cpp`](../tests/fixtures/source/caa-feature-io.cpp)：四个旧标记块；
+- [`expected/caa-feature-io`](../tests/fixtures/expected/caa-feature-io)：四份逐行 golden；
+- [`caa-feature-renderer.test.ts`](../tests/caa-feature-renderer.test.ts)：覆盖 golden、替换边界、枚举大小写、SpecObject、排序列表、两组 ID 边界和部分迁移状态。
+
+本阶段仍只生成 Analyze Plan，不执行真实文件写回。

package/doc/CAA/347/233/256/345/275/225/344/270/216/346/240/221/345/267/245/345/216/202/345/235/227/350/277/201/347/247/273.md

@@ -0,0 +1,78 @@
+# CAA 目录与树工厂块迁移
+
+本文记录 `CATALOG PARAMS` 和旧拼写 `FACTRY ON TREE` 两个 CAA 自动代码块的迁移结果。完成后，迁移矩阵 ID 0～13 已连续迁移。
+
+## 迁移范围
+
+| ID | block key | 旧 VB 方法 | 新目标 | 状态 |
+| ---: | --- | --- | --- | --- |
+| 0 | `CATALOG PARAMS` | `CreateCAACatalogParam` | `caa.feature-io` | 已迁移 |
+| 1 | `FACTRY ON TREE` | `CreateCAAFactoryOnTree` | `caa.model` | 已迁移 |
+
+权威依据是归档基线 `KtaAutoCodeBase/KevinCAAFileGuide.vb` 中的两个生成方法和 `ConvertNameOnTree`。TypeScript 实现位于 [`KtCodegenRenderer.ts`](../src/KtCodegenRenderer.ts)，树标题格式化迁入 [`KtCodegenCore.ts`](../src/KtCodegenCore.ts) 作为可单测纯 helper；基线位置见[《来源与许可归档》](来源与许可归档.md)。
+
+## Catalog 参数注册
+
+Catalog 只排除 ID 100～199；ID -1、0、其他负数以及 ID 200 以上均按旧行为保留。每个 Item 生成三行：
+
+1. 使用分号和 Tab 保存 ID、名称、作者、日期及可选备注的注释；
+2. 调用 `item.SetValue` 或 `item.SetTKListValue`；
+3. 把 `item` 追加到 `itemList`。
+
+当 `isList` 为 true，或 `dataType` 属于 Core 维护的旧3D点/向量集合时，使用 `SetTKListValue`。`tcKind` 和 `catAttrInOut` 继续作为普通字符串原样写入，未知 Combo 值不会被 Renderer 清空或替换。
+
+## Factory On Tree 选择规则
+
+Factory 仅保留：
+
+- `id === -1` 的临时项，不要求 `isOnTree`；
+- `id >= 0` 且 `isOnTree === true` 的普通项。
+
+ID 小于 -1 或非树上普通项跳过。ID -1 固定创建 `CreateInteger("Temp Spec", 0)`，并写入 `ListOnTree.Append(false)`；普通项写入 true。
+
+## 单位与数据类型映射
+
+单位比较不区分大小写：
+
+| 条件 | 工厂函数 |
+| --- | --- |
+| `unit === mm` | `CreateLength` |
+| `unit === degree` | `CreateAngle` |
+| `dataType === int` | `CreateInteger` |
+| `dataType === double` | `CreateReal` |
+| `dataType === CATBoolean` | `CreateBoolean` |
+| `dataType === CATUnicodeString` | `CreateString` |
+
+除单位外，`dataType` 比较保持旧代码的大小写敏感。未知类型仍生成旧中文占位函数名，便于 golden 识别未支持分支，不擅自改成错误、异常或空输出。
+
+旧代码把以下校验信息直接写入候选代码，且不附加块缩进：
+
+- `TCKind` 不精确等于 `tk_specobject`；
+- 长度/角度的 `dataType` 不精确等于 `double`。
+
+新实现保留这些行，同时通过测试固定顺序和内容。
+
+## 树标题格式化
+
+`KtCodegenCore.formatTreeName` 只在“当前字符大写、前一字符不是大写”时插入空格：
+
+| 输入 | 输出 |
+| --- | --- |
+| `MachineId` | `Machine Id` |
+| `AxisX` | `Axis X` |
+| `URLValue` | `URLValue` |
+
+连续大写缩写不会被拆开，保持旧 `ConvertNameOnTree` 行为。
+
+## 目标状态与证据
+
+完成 ID 0 后，`caa.feature-io` 的 Catalog、CPP Get/Set、Param Get/Set 五块全部迁移；完成 ID 1 后，`caa.model` 的 Factory 与纯虚接口 Get/Set 三块全部迁移。默认请求全部 block key 时，这两个目标不再因本目标遗留块而保持 scaffold。
+
+回归材料：
+
+- [`caa-catalog-factory.cpp`](../tests/fixtures/source/caa-catalog-factory.cpp)：两个旧标记块；
+- [`expected/caa-catalog-factory`](../tests/fixtures/expected/caa-catalog-factory)：逐行 golden；
+- [`caa-catalog-factory.test.ts`](../tests/caa-catalog-factory.test.ts)：覆盖 Catalog ID 边界、3D列表、未知字符串、Factory 选择、全部类型映射、旧错误行和树标题；
+- [`core.test.ts`](../tests/core.test.ts)：覆盖 `formatTreeName` 独立行为。
+
+本阶段只形成 Analyze Plan，不执行真实文件写入。

package/doc/CommandAgent/347/224/237/345/221/275/345/221/250/346/234/237/345/235/227/350/277/201/347/247/273.md

@@ -0,0 +1,47 @@
+# Command Agent 生命周期块迁移
+
+本文记录 ID 22～24 三个 CAA Command Agent 生命周期块的 TypeScript 迁移结果。它们根据共享 Parameter 中的 Selector Field，生成 Command 头文件成员声明、构造函数初始化列表和析构清理宏。
+
+## 权威实现与共享规则
+
+旧行为以归档基线 `KtaAutoCodeBase/KevinCAAFileGuide.vb` 中以下方法为准（基线位置见[《来源与许可归档》](来源与许可归档.md)）：
+
+- `CmdAgentDeclare`
+- `CmdAgentConstructor`
+- `CmdAgentDestructor`
+- 三者共同调用的 `AutoCodeStartSelector` 与 `GetCurrentSelectorList`
+
+Renderer 复用 `KtCodegenCore.isSelectorField`，因此只保留当前 Marker `NameSuffix`、`id >= 1` 且 Component 精确属于 `SelectorList`、`MultiList`、`QListWidget`、`QTableWidget`、`QTableView` 的 Item。`componentCount` 和 `dataType` 不参与筛选，输出顺序保持共享 `items` 顺序。
+
+旧 `CmdAgentDeclare` 会计算一个没有被使用的 `paramClass` 局部变量。该变量不影响生成文本，因此不进入 TypeScript 数据流。
+
+## 三个生成块
+
+| ID | block key | 生成内容 |
+| ---: | --- | --- |
+| 22 | `CMD AGENT DECLARE` | Common/Base 声明宏、Field 数量和逐 Field 声明宏 |
+| 23 | `CMD AGENT CONSTRUCTOR` | 以逗号开头的 Common 与逐 Field 构造初始化宏 |
+| 24 | `CMD AGENT DESTRUCTOR` | Field 数量、逐 Field 析构宏，最后生成 Common 清理宏 |
+
+Base 宏参数严格保持旧拼接方式：第一个参数是 `NamePrefix`，第二个参数是 `NameMiddle + NameSuffix`。例如 `Kt + CourseGuard + Cmd` 输出：
+
+```cpp
+KT_AUTO_CMD_AGENT_DECLARE_BASE(Kt, CourseGuardCmd);
+```
+
+三个块都保留旧 `KevinControlID.ToString()` 形成的 `@key`、点分隔线、Marker 缩进、LF/CRLF 和末尾换行。构造宏末尾不擅自增加分号；析构 Common 宏前保留空行与 `// place at the end`。
+
+## 目标状态
+
+显式只请求 ID 22～24 时，`caa.control` 返回 `ready`，完整 Marker 可形成 `canApply: true` 的预览计划。ID 25～31 也已在后续阶段迁移，因此默认请求 `caa.control` 全部10块时同样返回 `ready`。废弃兼容 ID 30 只在源码实际存在对应 Marker 并生成时附加 warning。
+
+Renderer 只消费 `KtCodegenParam` 与安全 Marker 区域，不修改共享 Item，也不访问真实文件系统。
+
+## 回归证据
+
+- [`command-agent-lifecycle.cpp`](../tests/fixtures/source/command-agent-lifecycle.cpp)：三个旧 Marker 区域；
+- [`expected/command-agent-lifecycle`](../tests/fixtures/expected/command-agent-lifecycle)：三份逐行 golden；
+- [`command-agent-renderer.test.ts`](../tests/command-agent-renderer.test.ts)：验证三块输出、Selector 筛选、目标 ready/scaffold 边界和共享数据不变性；
+- [`command-agent-fixtures.ts`](../tests/command-agent-fixtures.ts)：包含数量为0、未知 DataType、非 Field、ID 和后缀排除案例。
+
+本阶段仍只产生 Analyze/Preview，不执行真实源码 Apply。

package/doc/Command/345/212/250/344/275/234/344/270/216/346/264/273/345/212/250/345/255/227/346/256/265/345/235/227/350/277/201/347/247/273.md

@@ -0,0 +1,46 @@
+# Command 动作与活动字段块迁移
+
+本文记录最后一组 ID 28～31 CAA Command 块的 TypeScript 迁移结果：PDA/FIA Action、已经被替代的旧 ElementSelected 兼容逻辑，以及活动 Field 的 HSO 更新。
+
+## 权威实现与 Field 筛选
+
+旧行为以归档基线 `KtaAutoCodeBase/KevinCAAFileGuide.vb` 中以下方法为准（基线位置见[《来源与许可归档》](来源与许可归档.md)）：
+
+- `CmdActionPda`
+- `CmdActionFia`
+- `CmdElementSelected`
+- `CmdSetActiveField`
+
+四块先复用 `KtCodegenCore.isSelectorField` 取得当前后缀的五类 Selector Field。ID 28、29、31 再复用 `KtCodegenCore.isCommandAutoField`：只有精确 `SelectorList`/`QListWidget` 且 `componentCount !== 0` 才生成自动宏；其他 Field 仍保留 switch case，并输出数量为0或组件不支持的原因。
+
+ID 30 是旧实现，按归档行为对所有第一层 Field 生成代码，不检查组件或数量。它只按 `dataType === "CATListValCATISpecObject_var"` 区分列表切换与单值切换。
+
+## 四个生成块
+
+| ID | block key | 行为 | 策略 |
+| ---: | --- | --- | --- |
+| 28 | `CMD ACTION PDA` | Field 变化时清空 HSO，按 Field 调用 PDA 宏 | 正常迁移 |
+| 29 | `CMD ACTION FIA` | 保留局部 `int count = 0`，按 Field 调用 FIA 宏 | 正常迁移 |
+| 30 | `CMD ELEMENT SELECTED` | 列表参数执行 Locate/Append/Remove，单值参数切换选择对象 | 废弃兼容 |
+| 31 | `CMD SET ACTIVE FIELD` | 先清空 HSO，再按 Field 调用 HSO Add，保留 default 分支 | 正常迁移 |
+
+ID 31 的旧方法虽然名为 SetActiveField，但不会写 `_ActiveField = field`；TypeScript 不根据名称补写。ID 29 的 `count` 局部变量即使后续片段没有直接使用也保留。以上可见细节均由 golden 固定。
+
+## 废弃兼容策略
+
+旧 VB 明确注明 ID 30 已被 `CMD ACTION FIA` 替代，但旧 UI 和分派仍能请求它，因此采用与 ID 20、21 相同的兼容策略：
+
+1. 元数据同时保留 `migrationStatus: migrated` 与 `legacyState: legacy-deprecated`；
+2. 实际命中安全 Marker 并生成 artifact 时发出 `renderer.legacy-deprecated-block` warning；
+3. warning 不阻止 `plan.canApply`，`caa.control` 仍为 `ready`；
+4. 宿主可通过 `blockKeys` 排除 ID 30，排除后不产生 artifact 或 warning；
+5. 稳定 key 和 Marker 解析能力继续保留，不能静默删除。
+
+## 回归证据
+
+- [`command-actions.cpp`](../tests/fixtures/source/command-actions.cpp)：四个旧 Marker 区域；
+- [`expected/command-actions`](../tests/fixtures/expected/command-actions)：四份逐行 golden；
+- [`command-action-renderer.test.ts`](../tests/command-action-renderer.test.ts)：覆盖支持/不支持分支、列表/单值兼容逻辑、warning、宿主排除和共享数据不变性；
+- [`command-action-fixtures.ts`](../tests/command-action-fixtures.ts)：同时包含 SelectorList、QListWidget、MultiList、数量0与非 Field 数据。
+
+至此归档枚举 ID 0～31 的32个旧自动代码块均已完成 TypeScript Renderer 与 golden 基线。本包仍只产生 Analyze/Preview，不执行真实源码 Apply。

package/doc/Command/345/233/276/344/270/216/347/212/266/346/200/201/345/235/227/350/277/201/347/247/273.md

@@ -0,0 +1,64 @@
+# Command 图与状态块迁移
+
+本文记录 ID 25～27 三个 CAA Command Graph/State 块的 TypeScript 迁移结果：建立选择 Agent 状态图、清理 FIA 状态，以及按活动 Field 更新 FIA。
+
+## 权威实现
+
+旧行为以归档基线 `KtaAutoCodeBase/KevinCAAFileGuide.vb` 为准（基线位置见[《来源与许可归档》](来源与许可归档.md)）：
+
+- `CmdAgentBuildGraph`
+- `CmdAgentFiaClear`
+- `CmdAgentUpdateState`
+- 共同使用的 `AutoCodeStartSelector`、`GetCurrentSelectorList` 和 `GetFieldTypePrefix`
+
+旧 `CmdAgentBuildGraph` 在创建 notes 前调用过一次 `AutoCodeStartSelector`，随后带 notes 再调用一次。第二次调用会清空 `_codes`，所以第一次结果不会进入最终输出。TypeScript 直接生成最终可见的带说明版本，不保留无效中间副作用。
+
+## 两层 Field 规则
+
+第一层仍由 `KtCodegenCore.isSelectorField` 决定：当前后缀、`id >= 1`，Component 属于五类 Selector Field。第二层由新增的 `KtCodegenCore.isCommandAutoField` 判断某个 Field 是否能使用旧 Command 自动宏：
+
+- Component 必须精确等于 `SelectorList` 或 `QListWidget`；
+- `componentCount` 必须不等于0；
+- 旧代码只判断 `= 0`，因此负数没有被当成0，本迁移保留该边界；
+- 不支持的 Field 仍进入 switch 或编号序列，以注释说明“控件数量为0”或“组件不支持”，不被静默丢弃。
+
+这条规则已由后续迁移的 ID 28、29、31 复用。
+
+## BuildGraph 建议过滤器
+
+`KtCodegenCore.getCommandSuggestedFilter` 按旧优先级对 `ParamString` 做不区分大小写的包含判断：
+
+1. `GRID_AXIS`
+2. `AXIS_SYSTEM`
+3. `DIRECTION`
+4. `SUPPORT`
+5. `POINT`（命中 `point` 或 `origin`）
+6. `LINE`
+7. `CURVE`
+8. `PLANE`
+9. `FACE`（命中 `face` 或 `surface`）
+10. `AXIS`
+11. `DEFAULT`
+
+具体名称先于通用 `AXIS`，因此 `GridAxis` 不会错误落入 `AXIS`。Renderer 先生成 `KT_AUTO_CMD_BUILD_FIA_<FILTER>`，再生成 `KT_AUTO_CMD_BUILD_FIELD`；不支持时保留人工实现提示。
+
+## 三个块的差异
+
+| ID | block key | 行为 |
+| ---: | --- | --- |
+| 25 | `CMD AGENT BUILD GRAPH` | Build Start/End、Field 数量、编号、建议 FIA 与 Field 宏 |
+| 26 | `CMD AGENT UPDATE STATE` | 按 `Field_<Class>_<Param>` switch；支持项更新状态，不支持项输出原因；最后保留 `case 0` 错误宏 |
+| 27 | `CMD AGENT FIA CLEAR` | 对第一层筛选后的所有 Field 生成 FIA Clear 宏，不应用第二层自动支持判断 |
+
+空 Field 时 BuildGraph 仍生成 Start/End 和数量0；FIA Clear 不生成 Field 宏；UpdateState 只生成数量0，不生成 switch。所有块继续保留旧 `@key`、说明、Marker 缩进、换行和末尾换行。
+
+## 目标状态与回归证据
+
+显式请求 ID 25～27 时，`caa.control` 返回 `ready`，安全 Marker 可形成 `canApply: true` 的预览计划。ID 28～31 已在后续阶段迁移，因此默认请求全部 Control 块时也返回 `ready`；只有实际生成废弃兼容 ID 30 时才附加 warning。
+
+- [`command-graph-state.cpp`](../tests/fixtures/source/command-graph-state.cpp)：三个旧 Marker 区域；
+- [`expected/command-graph-state`](../tests/fixtures/expected/command-graph-state)：三份逐行 golden；
+- [`command-graph-renderer.test.ts`](../tests/command-graph-renderer.test.ts)：覆盖自动与人工分支、过滤器、Field 顺序、目标状态和共享数据不变性；
+- [`core.test.ts`](../tests/core.test.ts)：覆盖支持组件、数量0/负数和完整过滤器优先级。
+
+本阶段仍只产生 Analyze/Preview，不执行真实源码 Apply。

package/doc/Dialog/345/255/227/346/256/265/344/270/216/345/272/237/345/274/203/345/205/274/345/256/271/345/235/227/350/277/201/347/247/273.md

@@ -0,0 +1,60 @@
+# Dialog 字段与废弃兼容块迁移
+
+本文记录 ID 19～21 三个 CAA Dialog Field 块的 TypeScript 迁移结果，以及旧 VB 已标记废弃的方法如何在兼容模式下继续安全生成。
+
+## 权威实现
+
+行为以归档基线 `KtaAutoCodeBase/KevinCAAFileGuide.vb` 为准（基线位置见[《来源与许可归档》](来源与许可归档.md)）：
+
+- `GetCurrentSelectorList`：选择当前 Dialog/Command 使用的 Field Item；
+- `AutoCodeStartSelector`：生成三个块共同使用的分隔线、`@key` 和说明；
+- `DlgDefineFieldType`：生成 Field 枚举值；
+- `DlgSetActiveField`：清理其他 Selector 的旧兼容逻辑；
+- `DlgGetSelectorList`：按 Field 返回 Selector 的旧兼容逻辑。
+
+旧 UI 仍会选择 ID 19～31，`CreateCAAItem` 也仍会分派 ID 20、21，因此本阶段保留可审计的兼容输出，而不是根据方法注释静默删除。
+
+## 共享 Selector Field 分类
+
+`KtCodegenCore.isSelectorField` 复现 `GetCurrentSelectorList` 的最终规则。Item 必须满足 `id >= 1`，且 `component` 精确等于以下五个字符串之一：
+
+- `SelectorList`
+- `MultiList`
+- `QListWidget`
+- `QTableWidget`
+- `QTableView`
+
+组件比较大小写敏感。旧代码从2023年起已注释掉 `ComponentCount` 检查，因此数量为0仍属于 Field；`DataType` 不参与判断。当前 Marker 的 `NameSuffix` 由 Renderer 另行过滤，最终顺序保持 `KtCodegenParam.items` 的原始顺序。
+
+该判断放在 Core 而不是 Dialog Renderer 私有函数中，ID 22～31 的 Command Selector 迁移已经复用同一规则。
+
+## 三个生成块
+
+| ID | block key | 输出 | 当前策略 |
+| ---: | --- | --- | --- |
+| 19 | `DLG DEFINE FIELD TYPE` | `Field_<Class>_None = 0`，随后按顺序生成从1开始的 Field 值 | 正常迁移 |
+| 20 | `DLG SET ACTIVE FIELD` | 对非活动 Field 调用 `_SelectorList<Name>->ClearSelect()`，最后设置 `_ActiveField` | 废弃兼容 |
+| 21 | `DLG GET SELECTOR LIST` | `switch (field)` 返回对应 Selector；无 Field 时直接 `return NULL` | 废弃兼容 |
+
+公共 Field 前缀严格保持 `Field_ + NamePrefix + NameMiddle + NameSuffix + _`。公共块头保持旧 `AutoCodeStartSelector` 的点分隔线、枚举式 `@key` 和原英文说明；Start/End、缩进、LF/CRLF 与末尾换行继续遵循 Marker/Renderer 的统一规则。
+
+## 废弃兼容诊断
+
+ID 20、21 在 [`legacy-blocks.ts`](../src/blocks/legacy-blocks.ts) 中继续标记为 `legacy-deprecated`，同时其迁移状态为 `migrated`。策略如下：
+
+1. 只要用户或宿主没有请求相应 block key，Renderer 不生成兼容代码；
+2. 请求了 key 但源码没有对应安全 Marker 区域时，不产生 artifact，也不发废弃 warning；
+3. 实际生成兼容 artifact 时，返回 `renderer.legacy-deprecated-block` warning；
+4. warning 不把目标降为 scaffold，也不阻止 `plan.canApply`；
+5. 宿主可以通过 `blockKeys` 排除这两个块，但不能丢失其稳定身份和 Marker 解析能力。
+
+这使旧项目能够无损迁移，也让新 UI 明确提示用户该代码已过时。未来若确认所有宿主都不再消费，可在新的兼容策略中停止生成，但必须单独记录，不能静默改变旧输出。
+
+## 回归证据
+
+- [`dialog-fields.cpp`](../tests/fixtures/source/dialog-fields.cpp)：三个旧 Marker 区域；
+- [`expected/dialog-fields`](../tests/fixtures/expected/dialog-fields)：三份逐行 golden；
+- [`dialog-field-renderer.test.ts`](../tests/dialog-field-renderer.test.ts)：覆盖五类组件、ID/后缀过滤、数量为0、未知 DataType、空 Field、两个 warning 和共享数据不变性；
+- [`core.test.ts`](../tests/core.test.ts)：约束精确组件集合、大小写和无副作用。
+
+本阶段仍只产生 Analyze/Preview，不访问或写入真实源码文件。

package/doc/KtCodegen/345/221/275/345/220/215/350/277/201/347/247/273/350/257/264/346/230/216.md

@@ -0,0 +1,55 @@
+# KtCodegen 命名迁移说明
+
+参数自动代码领域统一使用 `KtCodegen` 前缀。即使本包未来位于 Phoenix Wing，包的位置也不要求领域对象全部使用 `Pnw`：`Pnw` 留给 Phoenix Wing 通用基础设施，`Kt` 表示锟钛已有的参数驱动自动代码语义和兼容责任。
+
+## 本阶段同步改名
+
+- 源码目录由 `param-codegen` 改为 `kt-codegen`；
+- npm 包名由 `@phoenix-wing/param-codegen` 改为 `@phoenix-wing/kt-codegen`；
+- 原型运行时身份由 `kt.param-codegen.*` 改为 `kt.codegen.*`；
+- CAA、Qt、C++ 生成块 key 和旧 `KEVIN CAA WIZARD` Marker 文本保持不变；
+- 旧17列 CSV 与 v4 JSON 协议保持不变。
+
+包名、目录、类名和运行时身份现在都明确指向 `KtCodegen` 领域，避免继续保留 `param-codegen` 与 `KtCodegen` 两套名称。
+
+## TypeScript API 映射
+
+| 旧前缀 | 新前缀 | 示例 |
+| --- | --- | --- |
+| `PnwCodegen*` | `KtCodegen*` | `KtCodegenParam`、`KtCodegenRenderer` |
+| 其他公开 `Pnw*` 类型 | `KtCodegen*` | `KtCodegenDataResult`、`KtCodegenLegacyCsvDialect` |
+| 内部 `pnw*` 函数 | `ktCodegen*` | `ktCodegenAnalyze` |
+| `PNW_*` 常量 | `KT_CODEGEN_*` | `KT_CODEGEN_LEGACY_BLOCKS` |
+
+九个主要类文件与类名同步改为：
+
+- `KtCodegenParam.ts`
+- `KtCodegenItem.ts`
+- `KtCodegenOptions.ts`
+- `KtCodegenReader.ts`
+- `KtCodegenAdapter.ts`
+- `KtCodegenController.ts`
+- `KtCodegenCore.ts`
+- `KtCodegenMarker.ts`
+- `KtCodegenRenderer.ts`
+
+原型尚未作为外部运行时依赖，因此本阶段直接完成破坏式重命名，不保留两套公开别名。这样可以在进入 Phoenix Wing 前消除长期双命名成本。
+
+## 运行时稳定身份
+
+运行时身份也同步使用小写 `kt` 领域前缀：
+
+| 对象 | 稳定身份 |
+| --- | --- |
+| 共享数据 | `kt.codegen` |
+| Analyze Plan | `kt.codegen.plan` |
+| CAA Renderer | `kt.codegen.renderer.caa` |
+| Qt Renderer | `kt.codegen.renderer.qt` |
+| C++ Renderer | `kt.codegen.renderer.cpp` |
+| Artifact | `kt.codegen.artifact:*` |
+
+旧 v4 JSON 和17列 CSV 没有这些原型运行时字段，因此兼容读写协议不受影响。原生 TS 对象的 `kind` 属于当前原型 API，随类名一起更新。
+
+## 验证边界
+
+[`naming.test.ts`](../tests/naming.test.ts) 从公共 `src/index.ts` 导入新 API，验证数据、Plan、Renderer、Artifact 和常量的统一身份。全量 TypeScript 编译同时证明源码中不存在对旧类文件的残留 import。

package/doc//344/270/244/345/260/217/346/227/266/350/277/201/347/247/273/350/256/241/345/210/222/344/270/216/351/252/214/346/224/266.md

@@ -0,0 +1,52 @@
+# KtCodegen 两小时迁移计划与验收
+
+> 历史归档说明：本文记录 `kt-codegen` 首次迁入 Wing 时的 0.3.0 时间盒与验收事实。Phoenix Wing 当前发布线已升级为 0.4.0；当前版本与消费约束以仓库根 `release-matrix.json` 和 `doc/三库版本矩阵.md` 为准。
+
+## 目标与边界
+
+以 `KtAutoCode@kt-codegen-0.1.0` 为只读基线，在约两小时内把参数代码生成核心迁入 Phoenix Wing，形成可独立构建、测试和发布的 `@phoenix-wing/kt-codegen`。
+
+本阶段只修改 `phoenix-wing`：不修改 `kt-auto-code`、`phoenix-desk-tools` 或历史 `KtAutoCode`，不执行 push。两个宿主的依赖接入、真实文件 Apply 和产品 UI 均留给后续独立任务。
+
+## 时间盒
+
+| 时间 | 工作 | 退出条件 |
+| --- | --- | --- |
+| 0～15 分钟 | 审计本地标签、Wing 多包规范与命名 | 明确来源标签、0.3.0 锁步版本及 `KtCodegen*` 领域例外 |
+| 15～35 分钟 | 建立 `packages/kt-codegen` | package、exports、TS build、LICENSE/NOTICE 和 workspace lockfile 完整 |
+| 35～65 分钟 | 迁入数据与旧格式兼容 | `KtCodegenParam`/`Item`、17列 CSV、v4 JSON、Combo 原值保留通过测试 |
+| 65～95 分钟 | 迁入 Core/Marker/Renderer | Analyze 契约、标记扫描和32个生成块全部进入统一注册与 golden 测试 |
+| 95～110 分钟 | 整理接口、fixture 与中文文档 | 类图、迁移矩阵、来源许可、各 Renderer 行为文档可在本包内独立阅读 |
+| 110～120 分钟 | 执行发布门禁并本地归档 | typecheck、workspace tests、release matrix、tarball smoke 全通过；本地提交和标签完成 |
+
+## 架构结果
+
+```mermaid
+flowchart LR
+    Legacy["旧 CSV / v4 JSON"] --> Reader["KtCodegenReader"]
+    Reader --> Param["KtCodegenParam<br/>共享公开数据"]
+    UI["未来宿主 UI"] <--> Param
+    Param --> Controller["KtCodegenController"]
+    Snapshot["宿主源码快照"] --> Controller
+    Controller --> Core["KtCodegenCore"]
+    Core --> Marker["KtCodegenMarker<br/>只读扫描"]
+    Core --> Renderer["KtCodegenRenderer<br/>32个生成块"]
+    Marker --> Plan["KtCodegenPlan<br/>Analyze 预览"]
+    Renderer --> Plan
+    Plan --> Host["未来宿主 Apply"]
+```
+
+`KtCodegenParam` 与 `KtCodegenItem` 保持类似 `struct` 的全公开、可变字段。Reader 完整读取后由 Adapter 原位更新共享实例；UI、Controller、Core 和 Renderer 因而能消费同一份数据。未知 Combo 字符串不被模型清空，宿主 UI 只负责提示和用户主动修正。
+
+## 验收清单
+
+- [x] 包名、目录和运行时身份统一为 `kt-codegen` / `@phoenix-wing/kt-codegen` / `kt.codegen.*`。
+- [x] `KtCodegen*` 类、`ktCodegen*` 函数和 `KT_CODEGEN_*` 常量作为领域命名例外写入仓库规则。
+- [x] 主要类一个类一个文件，公共字段显式标注类型并提供 JSDoc。
+- [x] 17列 CSV 和 v4 JSON 可读写；旧扩展字段、表头和未知 Combo 值保持可往返。
+- [x] Marker 只读扫描与 Analyze 计划不直接修改宿主源码。
+- [x] 32个 CAA、Qt、普通 C++ 生成块全部有稳定 key、Renderer 或兼容策略。
+- [x] 16 个测试文件、47 个 fixture/golden 文件进入 Phoenix Wing。
+- [x] 根 README、多包总计划、版本矩阵、release matrix 与 tarball smoke 纳入新包。
+- [ ] 两个宿主接入 npm 包并实现 Preview/Apply；不属于本时间盒。
+- [ ] 从第二个真实消费者中识别可进一步提取的公共契约；不预先制造公共库。