kcode-pi 0.1.0

package/knowledge/flagship/plugin-lifecycle.md

@@ -0,0 +1,248 @@
+# 金蝶云星空旗舰版插件生命周期
+
+## 表单插件生命周期 (AbstractBillPlugIn)
+
+### 生命周期顺序
+
+```
+表单打开
+  ↓
+afterLoadData() - 加载数据后
+  ↓
+afterCreateNewDataEntity() - 新建数据实体后
+  ↓
+用户操作
+  ↓
+afterPropertyChanged() - 字段值变更后
+  ↓
+beforeSave() - 保存前
+  ↓
+afterSave() - 保存后
+  ↓
+beforeSubmit() - 提交前
+  ↓
+afterSubmit() - 提交后
+  ↓
+beforeAudit() - 审核前
+  ↓
+afterAudit() - 审核后
+  ↓
+表单关闭
+```
+
+### 关键事件详解
+
+#### afterLoadData - 数据加载后
+
+**触发时机：** 表单数据从数据库加载完成后
+
+**用途：**
+- 初始化界面控件
+- 计算派生字段
+- 设置字段可见性
+
+**示例：**
+```java
+@Override
+public void afterLoadData(EventObject e) {
+    super.afterLoadData(e);
+    
+    // 获取数据实体
+    DynamicObject dataEntity = this.getModel().getDataEntity();
+    
+    // 初始化界面
+    this.getView().setVisible(true, "field1");
+    this.getView().setEnable(false, "field2");
+}
+```
+
+#### afterPropertyChanged - 字段值变更后
+
+**触发时机：** 用户修改字段值后
+
+**用途：**
+- 联动计算
+- 数据验证
+- 界面刷新
+
+**示例：**
+```java
+@Override
+public void afterPropertyChanged(PropertyChangedArgs e) {
+    String fieldKey = e.getProperty().getName();
+    
+    if ("qty".equals(fieldKey)) {
+        // 数量变更后计算金额
+        BigDecimal qty = (BigDecimal) e.getNewValue();
+        BigDecimal price = this.getModel().getValue("price");
+        BigDecimal amount = qty.multiply(price);
+        this.getModel().setValue("amount", amount);
+    }
+}
+```
+
+#### beforeSave - 保存前
+
+**触发时机：** 用户点击保存按钮后，数据保存到数据库前
+
+**用途：**
+- 数据校验
+- 自动生成编号
+- 设置默认值
+
+**示例：**
+```java
+@Override
+public void beforeSave(BeforeSaveEventArgs e) {
+    // 校验必填字段
+    DynamicObject dataEntity = this.getModel().getDataEntity();
+    String billNo = dataEntity.getString("billno");
+    
+    if (StringUtils.isEmpty(billNo)) {
+        e.setCancel(true);
+        this.getView().showErrorNotification("单据编号不能为空");
+        return;
+    }
+    
+    // 自动生成编号
+    if ("AUTO".equals(billNo)) {
+        String newBillNo = generateBillNo();
+        dataEntity.set("billno", newBillNo);
+    }
+}
+```
+
+---
+
+## 操作插件生命周期 (AbstractOperatePlugin)
+
+### 生命周期顺序
+
+```
+操作触发
+  ↓
+onGetValidateRules() - 获取校验规则
+  ↓
+beforeExecuteOperationTransaction() - 操作执行前
+  ↓
+executeOperationTransaction() - 执行操作（事务内）
+  ↓
+afterExecuteOperationTransaction() - 操作执行后
+  ↓
+操作完成
+```
+
+### 关键事件详解
+
+#### beforeExecuteOperationTransaction - 操作执行前
+
+**触发时机：** 操作事务开始前
+
+**用途：**
+- 业务规则校验
+- 数据预处理
+- 权限检查
+
+**示例：**
+```java
+@Override
+public void beforeExecuteOperationTransaction(BeforeExecuteOperationTransactionArgs e) {
+    String operateKey = e.getOperateKey();
+    
+    if ("submit".equals(operateKey)) {
+        // 提交前校验
+        DynamicObject[] dataEntities = e.getDataEntities();
+        for (DynamicObject entity : dataEntities) {
+            BigDecimal amount = entity.getBigDecimal("amount");
+            if (amount.compareTo(BigDecimal.ZERO) <= 0) {
+                e.setCancel(true);
+                throw new KDException("", "金额必须大于零");
+            }
+        }
+    }
+}
+```
+
+#### afterExecuteOperationTransaction - 操作执行后
+
+**触发时机：** 操作事务提交后
+
+**用途：**
+- 触发下游业务
+- 发送通知
+- 记录日志
+
+**示例：**
+```java
+@Override
+public void afterExecuteOperationTransaction(AfterExecuteOperationTransactionArgs e) {
+    String operateKey = e.getOperateKey();
+    
+    if ("audit".equals(operateKey)) {
+        // 审核后触发下游业务
+        DynamicObject[] dataEntities = e.getDataEntities();
+        for (DynamicObject entity : dataEntities) {
+            triggerDownstreamBusiness(entity);
+        }
+    }
+}
+```
+
+---
+
+## 校验插件生命周期 (AbstractValidatePlugin)
+
+### 生命周期顺序
+
+```
+数据提交
+  ↓
+onGetValidateRules() - 获取校验规则
+  ↓
+validate() - 执行校验
+  ↓
+校验结果
+```
+
+### 示例
+
+```java
+public class AmountValidatePlugin extends AbstractValidatePlugin {
+    
+    @Override
+    public void onGetValidateRules(GetValidateRulesEventArgs e) {
+        // 添加校验规则
+        e.addValidateRule("amount", "金额必须大于零");
+    }
+    
+    @Override
+    public void validate(ValidateEventArgs e) {
+        DynamicObject dataEntity = e.getDataEntity();
+        BigDecimal amount = dataEntity.getBigDecimal("amount");
+        
+        if (amount.compareTo(BigDecimal.ZERO) <= 0) {
+            e.addError("amount", "金额必须大于零");
+        }
+    }
+}
+```
+
+---
+
+## 列表插件生命周期 (AbstractListPlugin)
+
+### 常用事件
+
+```java
+// 列表加载后
+public void afterLoadData(EventObject e)
+
+// 行选中后
+public void afterRowClick(AfterRowClickEventArgs e)
+
+// 列表操作前
+public void beforeDoOperation(BeforeDoOperationEventArgs e)
+
+// 列表操作后
+public void afterDoOperation(AfterDoOperationEventArgs e)
+```

package/knowledge/flagship/tables.json

@@ -0,0 +1,159 @@
+{
+  "T_PUR_POORDER": {
+    "name": "采购订单表",
+    "module": "采购管理",
+    "description": "采购订单主表，记录采购订单的基本信息",
+    "fields": [
+      { "name": "FID", "type": "bigint", "nullable": false, "description": "主键ID" },
+      { "name": "FBILLNO", "type": "varchar(50)", "nullable": false, "description": "单据编号" },
+      { "name": "FDATE", "type": "datetime", "nullable": false, "description": "单据日期" },
+      { "name": "FDOCUMENTSTATUS", "type": "char(1)", "nullable": false, "description": "单据状态：A=暂存,B=已提交,C=已审核" },
+      { "name": "FCANCELSTATUS", "type": "char(1)", "nullable": false, "description": "作废状态：A=正常,B=已作废" },
+      { "name": "FSUPPLIERID", "type": "bigint", "nullable": false, "description": "供应商ID" },
+      { "name": "FPURCHASEORGID", "type": "bigint", "nullable": false, "description": "采购组织ID" },
+      { "name": "FPURCHASEDEPTID", "type": "bigint", "nullable": true, "description": "采购部门ID" },
+      { "name": "FPURCHASERID", "type": "bigint", "nullable": true, "description": "采购员ID" },
+      { "name": "FCURRENCYID", "type": "bigint", "nullable": false, "description": "币种ID" },
+      { "name": "FEXCHANGERATE", "type": "decimal(18,6)", "nullable": false, "description": "汇率" },
+      { "name": "FTOTALAMOUNT", "type": "decimal(18,2)", "nullable": false, "description": "价税合计" },
+      { "name": "FTOTALTAXAMOUNT", "type": "decimal(18,2)", "nullable": false, "description": "税额" },
+      { "name": "FDESCRIPTION", "type": "varchar(500)", "nullable": true, "description": "备注" },
+      { "name": "FCREATORID", "type": "bigint", "nullable": false, "description": "创建人ID" },
+      { "name": "FCREATETIME", "type": "datetime", "nullable": false, "description": "创建时间" },
+      { "name": "FMODIFIERID", "type": "bigint", "nullable": true, "description": "修改人ID" },
+      { "name": "FMODIFYTIME", "type": "datetime", "nullable": true, "description": "修改时间" },
+      { "name": "FAUDITORID", "type": "bigint", "nullable": true, "description": "审核人ID" },
+      { "name": "FAUDITDATE", "type": "datetime", "nullable": true, "description": "审核日期" }
+    ],
+    "relatedTables": [
+      { "table": "T_PUR_POORDERENTRY", "relation": "FID", "description": "采购订单明细" },
+      { "table": "T_PUR_POORDERFIN", "relation": "FID", "description": "采购订单财务信息" }
+    ]
+  },
+  "T_PUR_POORDERENTRY": {
+    "name": "采购订单明细表",
+    "module": "采购管理",
+    "description": "采购订单明细表，记录采购订单的物料明细",
+    "fields": [
+      { "name": "FENTRYID", "type": "bigint", "nullable": false, "description": "明细ID" },
+      { "name": "FID", "type": "bigint", "nullable": false, "description": "主表ID" },
+      { "name": "FSEQ", "type": "int", "nullable": false, "description": "行号" },
+      { "name": "FMATERIALID", "type": "bigint", "nullable": false, "description": "物料ID" },
+      { "name": "FUNITID", "type": "bigint", "nullable": false, "description": "单位ID" },
+      { "name": "FQTY", "type": "decimal(18,6)", "nullable": false, "description": "数量" },
+      { "name": "FPRICE", "type": "decimal(18,6)", "nullable": false, "description": "单价" },
+      { "name": "FAMOUNT", "type": "decimal(18,2)", "nullable": false, "description": "金额" },
+      { "name": "FTAXPRICE", "type": "decimal(18,6)", "nullable": false, "description": "含税单价" },
+      { "name": "FTAXAMOUNT", "type": "decimal(18,2)", "nullable": false, "description": "价税合计" },
+      { "name": "FTAXRATE", "type": "decimal(18,2)", "nullable": false, "description": "税率" },
+      { "name": "FDELIVERYDATE", "type": "datetime", "nullable": true, "description": "交货日期" },
+      { "name": "FWAREHOUSEID", "type": "bigint", "nullable": true, "description": "收货仓库ID" },
+      { "name": "FDESCRIPTION", "type": "varchar(500)", "nullable": true, "description": "备注" }
+    ],
+    "relatedTables": [
+      { "table": "T_PUR_POORDER", "relation": "FID", "description": "采购订单主表" },
+      { "table": "T_BD_MATERIAL", "relation": "FMATERIALID", "description": "物料表" }
+    ]
+  },
+  "T_SAL_ORDER": {
+    "name": "销售订单表",
+    "module": "销售管理",
+    "description": "销售订单主表，记录销售订单的基本信息",
+    "fields": [
+      { "name": "FID", "type": "bigint", "nullable": false, "description": "主键ID" },
+      { "name": "FBILLNO", "type": "varchar(50)", "nullable": false, "description": "单据编号" },
+      { "name": "FDATE", "type": "datetime", "nullable": false, "description": "单据日期" },
+      { "name": "FDOCUMENTSTATUS", "type": "char(1)", "nullable": false, "description": "单据状态：A=暂存,B=已提交,C=已审核" },
+      { "name": "FCUSTID", "type": "bigint", "nullable": false, "description": "客户ID" },
+      { "name": "FSALEORGID", "type": "bigint", "nullable": false, "description": "销售组织ID" },
+      { "name": "FSALEDEPTID", "type": "bigint", "nullable": true, "description": "销售部门ID" },
+      { "name": "FSALEERID", "type": "bigint", "nullable": true, "description": "销售员ID" },
+      { "name": "FCURRENCYID", "type": "bigint", "nullable": false, "description": "币种ID" },
+      { "name": "FEXCHANGERATE", "type": "decimal(18,6)", "nullable": false, "description": "汇率" },
+      { "name": "FTOTALAMOUNT", "type": "decimal(18,2)", "nullable": false, "description": "价税合计" },
+      { "name": "FDESCRIPTION", "type": "varchar(500)", "nullable": true, "description": "备注" }
+    ],
+    "relatedTables": [
+      { "table": "T_SAL_ORDERENTRY", "relation": "FID", "description": "销售订单明细" }
+    ]
+  },
+  "T_STK_INVENTORY": {
+    "name": "库存余额表",
+    "module": "库存管理",
+    "description": "库存余额表，记录各仓库的物料库存数量",
+    "fields": [
+      { "name": "FID", "type": "bigint", "nullable": false, "description": "主键ID" },
+      { "name": "FSTOCKID", "type": "bigint", "nullable": false, "description": "仓库ID" },
+      { "name": "FMATERIALID", "type": "bigint", "nullable": false, "description": "物料ID" },
+      { "name": "FLOT", "type": "varchar(50)", "nullable": true, "description": "批号" },
+      { "name": "FQTY", "type": "decimal(18,6)", "nullable": false, "description": "库存数量" },
+      { "name": "FBASEQTY", "type": "decimal(18,6)", "nullable": false, "description": "基本单位数量" },
+      { "name": "FSECQTY", "type": "decimal(18,6)", "nullable": true, "description": "辅助单位数量" },
+      { "name": "FAMOUNT", "type": "decimal(18,2)", "nullable": false, "description": "库存金额" },
+      { "name": "FPRICE", "type": "decimal(18,6)", "nullable": false, "description": "库存单价" }
+    ],
+    "relatedTables": [
+      { "table": "T_BD_MATERIAL", "relation": "FMATERIALID", "description": "物料表" },
+      { "table": "T_BD_STOCK", "relation": "FSTOCKID", "description": "仓库表" }
+    ]
+  },
+  "T_BD_MATERIAL": {
+    "name": "物料表",
+    "module": "基础资料",
+    "description": "物料主数据，记录物料的基本信息",
+    "fields": [
+      { "name": "FID", "type": "bigint", "nullable": false, "description": "主键ID" },
+      { "name": "FNUMBER", "type": "varchar(50)", "nullable": false, "description": "物料编码" },
+      { "name": "FNAME", "type": "varchar(200)", "nullable": false, "description": "物料名称" },
+      { "name": "FSPECIFICATION", "type": "varchar(500)", "nullable": true, "description": "规格型号" },
+      { "name": "FBASEUNITID", "type": "bigint", "nullable": false, "description": "基本单位ID" },
+      { "name": "FGROUPID", "type": "bigint", "nullable": false, "description": "物料分组ID" },
+      { "name": "FENABLESTATUS", "type": "char(1)", "nullable": false, "description": "启用状态：A=启用,B=禁用" },
+      { "name": "FDESCRIPTION", "type": "varchar(500)", "nullable": true, "description": "备注" }
+    ],
+    "relatedTables": [
+      { "table": "T_BD_UNIT", "relation": "FBASEUNITID", "description": "计量单位表" }
+    ]
+  },
+  "T_BD_SUPPLIER": {
+    "name": "供应商表",
+    "module": "基础资料",
+    "description": "供应商主数据，记录供应商的基本信息",
+    "fields": [
+      { "name": "FID", "type": "bigint", "nullable": false, "description": "主键ID" },
+      { "name": "FNUMBER", "type": "varchar(50)", "nullable": false, "description": "供应商编码" },
+      { "name": "FNAME", "type": "varchar(200)", "nullable": false, "description": "供应商名称" },
+      { "name": "FSHORTNAME", "type": "varchar(100)", "nullable": true, "description": "简称" },
+      { "name": "FTYPE", "type": "char(1)", "nullable": false, "description": "类型：1=普通供应商,2=内部供应商" },
+      { "name": "FENABLESTATUS", "type": "char(1)", "nullable": false, "description": "启用状态：A=启用,B=禁用" }
+    ],
+    "relatedTables": []
+  },
+  "T_BD_CUSTOMER": {
+    "name": "客户表",
+    "module": "基础资料",
+    "description": "客户主数据，记录客户的基本信息",
+    "fields": [
+      { "name": "FID", "type": "bigint", "nullable": false, "description": "主键ID" },
+      { "name": "FNUMBER", "type": "varchar(50)", "nullable": false, "description": "客户编码" },
+      { "name": "FNAME", "type": "varchar(200)", "nullable": false, "description": "客户名称" },
+      { "name": "FSHORTNAME", "type": "varchar(100)", "nullable": true, "description": "简称" },
+      { "name": "FTYPE", "type": "char(1)", "nullable": false, "description": "类型：1=普通客户,2=内部客户" },
+      { "name": "FENABLESTATUS", "type": "char(1)", "nullable": false, "description": "启用状态：A=启用,B=禁用" }
+    ],
+    "relatedTables": []
+  },
+  "T_BD_STOCK": {
+    "name": "仓库表",
+    "module": "基础资料",
+    "description": "仓库主数据，记录仓库的基本信息",
+    "fields": [
+      { "name": "FID", "type": "bigint", "nullable": false, "description": "主键ID" },
+      { "name": "FNUMBER", "type": "varchar(50)", "nullable": false, "description": "仓库编码" },
+      { "name": "FNAME", "type": "varchar(200)", "nullable": false, "description": "仓库名称" },
+      { "name": "FSTOCKORGID", "type": "bigint", "nullable": false, "description": "库存组织ID" },
+      { "name": "FENABLESTATUS", "type": "char(1)", "nullable": false, "description": "启用状态：A=启用,B=禁用" }
+    ],
+    "relatedTables": []
+  }
+}

package/knowledge/version.json

@@ -0,0 +1,10 @@
+{
+  "version": "1.0.0",
+  "lastUpdated": "2026-05-29",
+  "modules": [
+    "common",
+    "flagship",
+    "enterprise"
+  ],
+  "checksum": ""
+}

package/knowledge/xinghan/product-notes.md

@@ -0,0 +1,15 @@
+# Xinghan Product Notes
+
+Xinghan is a Cosmic-family product. Load Cosmic platform knowledge first, then apply Xinghan-specific product or version rules.
+
+## Default Stack
+
+- Platform: Cosmic.
+- Language: Java.
+- Main concerns: plugin lifecycle, metadata verification, SDK signature verification, transaction boundaries, performance review.
+
+## Harness Rules
+
+- Do not use enterprise C# namespaces or lifecycle assumptions.
+- Do not treat Xinghan as the old enterprise C# product line.
+- Use Cosmic review and unit-test rules unless a Xinghan-specific standard overrides them.

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "kcode-pi",
+  "version": "0.1.0",
+  "description": "Kingdee-specific package and harness for Pi Coding Agent",
+  "type": "module",
+  "private": false,
+  "bin": {
+    "kcode": "./dist/cli/main.js"
+  },
+  "main": "./dist/cli/kcode.js",
+  "types": "./dist/cli/kcode.d.ts",
+  "files": [
+    "dist",
+    "extensions",
+    "skills",
+    "prompts",
+    "themes",
+    "knowledge",
+    "vendor",
+    "docs/KCODE_DISTRIBUTION.md",
+    "README.md"
+  ],
+  "keywords": [
+    "pi-package",
+    "kingdee",
+    "cosmos",
+    "coding-agent",
+    "harness"
+  ],
+  "pi": {
+    "extensions": [
+      "./extensions/kingdee-header.ts",
+      "./extensions/kingdee-harness.ts",
+      "./extensions/kingdee-tools.ts"
+    ],
+    "skills": [
+      "./skills"
+    ],
+    "prompts": [
+      "./prompts"
+    ],
+    "themes": [
+      "./themes/kcode-dark.json"
+    ]
+  },
+  "dependencies": {
+    "@earendil-works/pi-ai": "^0.78.1",
+    "@earendil-works/pi-coding-agent": "^0.78.1"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.2",
+    "tsx": "^4.22.4",
+    "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "build:cli": "tsc -p tsconfig.cli.json",
+    "check": "tsc --noEmit",
+    "smoke:knowledge": "tsx scripts/smoke-knowledge.ts",
+    "smoke:checker": "tsx scripts/smoke-checker.ts",
+    "smoke:harness": "tsx scripts/smoke-harness.ts",
+    "smoke:official": "tsx scripts/smoke-official-tools.ts",
+    "smoke:build-debug": "tsx scripts/smoke-build-debug.ts",
+    "smoke:package": "tsx scripts/smoke-package.ts",
+    "smoke:kcode-cli": "tsx scripts/smoke-kcode-cli.ts",
+    "kcode": "tsx scripts/kcode.ts",
+    "prepack": "npm run build:cli && npm run smoke:package"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  }
+}

package/prompts/kd-discuss.md

@@ -0,0 +1,11 @@
+---
+description: Start or refine the Kingdee Harness Engineering discussion phase.
+---
+
+Use the `kd-discuss` skill.
+
+Start or update the active Kingdee harness run for this request:
+
+{{args}}
+
+Capture business goal, Kingdee product/version, tech stack, plugin type, target object, out-of-scope items, and open questions in `CONTEXT.md`.

package/prompts/kd-execute.md

@@ -0,0 +1,12 @@
+---
+description: Execute the active Kingdee plan under Harness Engineering gates.
+---
+
+Use the `kd-execute` skill.
+
+Before editing code, check the active run with `kd_plan_status`. If `PLAN.md` is missing or the gate is blocked, stop and explain the missing artifact. Otherwise implement only the approved plan and update `EXECUTION.md`.
+
+Extra user guidance:
+
+{{args}}
+

package/prompts/kd-plan.md

@@ -0,0 +1,12 @@
+---
+description: Draft the Kingdee implementation plan artifact for the active harness run.
+---
+
+Use the `kd-plan` skill.
+
+Read `CONTEXT.md` and `SPEC.md`, then draft or update `PLAN.md`. Include files to inspect, files likely to edit, required Kingdee lookups, validation commands, and rollback notes.
+
+Extra user guidance:
+
+{{args}}
+

package/prompts/kd-ship.md

@@ -0,0 +1,12 @@
+---
+description: Prepare Kingdee delivery summary after verification.
+---
+
+Use the `kd-ship` skill.
+
+Read the active run artifacts and produce `SHIP.md` with changed behavior, verification evidence, residual risks, and follow-up tasks. Do not ship if `VERIFY.md` is missing.
+
+Extra user guidance:
+
+{{args}}
+

package/prompts/kd-spec.md

@@ -0,0 +1,12 @@
+---
+description: Draft the Kingdee specification artifact for the active harness run.
+---
+
+Use the `kd-spec` skill.
+
+Read the active Kingdee run context and draft or update `SPEC.md`. Include acceptance criteria, lifecycle hooks, data objects, exception behavior, performance constraints, assumptions, and risks.
+
+Extra user guidance:
+
+{{args}}
+

package/prompts/kd-verify.md

@@ -0,0 +1,12 @@
+---
+description: Verify the active Kingdee implementation and collect evidence.
+---
+
+Use the `kd-verify` skill.
+
+Run the planned validation commands, collect evidence, run available checks, and update `VERIFY.md`. If anything cannot run, record the exact blocker and residual risk.
+
+Extra user guidance:
+
+{{args}}
+

package/skills/kd-check/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: kd-check
+description: Review Kingdee Java/C# plugin code against SDK, lifecycle, performance, exception, and maintainability rules.
+---
+
+# Kingdee Code Check
+
+Use this skill when reviewing Kingdee code.
+
+Checklist:
+
+- Magic values: status codes, operation names, field keys, table names, numbers, and business strings.
+- Naming: Java/C# naming conventions and project-local naming.
+- Lifecycle: correct plugin base class and lifecycle method for the target behavior.
+- SDK usage: no invented API names; uncertain APIs must be verified through `kd_search`.
+- Database access: no DB query or save operation inside loops unless explicitly justified.
+- Exception handling: no empty catch blocks; errors should be logged or converted to business exceptions as appropriate.
+- Resource cleanup: close or dispose resources where the SDK requires it.
+- Thread safety: no unsafe static mutable state in plugin classes.
+
+Output expectations:
+
+- Lead with concrete findings and file/line references when reviewing code.
+- Separate errors, warnings, and improvement suggestions.
+- State which checks were not possible because context or tools were missing.
+