galaxy-opc-plugin 0.1.1 → 0.2.0

package/src/tools/hr-tool.test.ts

@@ -0,0 +1,153 @@
+/**
+ * 星环OPC中心 — hr-tool 核心计算函数单元测试
+ */
+
+import { describe, it, expect } from "vitest";
+
+// 复制 hr-tool.ts 中的纯计算函数进行测试
+
+/** 社保公积金估算（一般城市标准） */
+function calcSocialInsurance(salary: number) {
+  const base = Math.max(Math.min(salary, 31884), 6377); // 一般上下限
+  const company = {
+    pension: Math.round(base * 0.16 * 100) / 100,
+    medical: Math.round(base * 0.095 * 100) / 100,
+    unemployment: Math.round(base * 0.005 * 100) / 100,
+    injury: Math.round(base * 0.004 * 100) / 100,
+    housing_fund: Math.round(base * 0.12 * 100) / 100,
+  };
+  const personal = {
+    pension: Math.round(base * 0.08 * 100) / 100,
+    medical: Math.round(base * 0.02 * 100) / 100,
+    unemployment: Math.round(base * 0.005 * 100) / 100,
+    housing_fund: Math.round(base * 0.12 * 100) / 100,
+  };
+  return {
+    base,
+    company_total: Object.values(company).reduce((a, b) => a + b, 0),
+    personal_total: Object.values(personal).reduce((a, b) => a + b, 0),
+    company,
+    personal,
+  };
+}
+
+/** 个税累进税率计算 */
+function calcPersonalTax(monthlyTaxable: number): { tax: number; rate: number; deduction: number } {
+  const annual = monthlyTaxable * 12;
+  const brackets = [
+    { limit: 36000, rate: 0.03, deduction: 0 },
+    { limit: 144000, rate: 0.10, deduction: 2520 },
+    { limit: 300000, rate: 0.20, deduction: 16920 },
+    { limit: 420000, rate: 0.25, deduction: 31920 },
+    { limit: 660000, rate: 0.30, deduction: 52920 },
+    { limit: 960000, rate: 0.35, deduction: 85920 },
+    { limit: Infinity, rate: 0.45, deduction: 181920 },
+  ];
+  for (const b of brackets) {
+    if (annual <= b.limit) {
+      const annualTax = Math.round((annual * b.rate - b.deduction) * 100) / 100;
+      return { tax: Math.round(annualTax / 12 * 100) / 100, rate: b.rate, deduction: b.deduction };
+    }
+  }
+  return { tax: 0, rate: 0, deduction: 0 };
+}
+
+describe("hr-tool calculations", () => {
+  describe("calcSocialInsurance — 社保公积金计算", () => {
+    it("should calculate social insurance for normal salary", () => {
+      const result = calcSocialInsurance(10000);
+      expect(result.base).toBe(10000);
+
+      // 公司部分
+      expect(result.company.pension).toBe(1600);       // 10000 × 16%
+      expect(result.company.medical).toBe(950);         // 10000 × 9.5%
+      expect(result.company.unemployment).toBe(50);     // 10000 × 0.5%
+      expect(result.company.injury).toBe(40);           // 10000 × 0.4%
+      expect(result.company.housing_fund).toBe(1200);   // 10000 × 12%
+
+      // 个人部分
+      expect(result.personal.pension).toBe(800);         // 10000 × 8%
+      expect(result.personal.medical).toBe(200);         // 10000 × 2%
+      expect(result.personal.unemployment).toBe(50);     // 10000 × 0.5%
+      expect(result.personal.housing_fund).toBe(1200);   // 10000 × 12%
+    });
+
+    it("should apply lower bound for low salary", () => {
+      const result = calcSocialInsurance(3000);
+      expect(result.base).toBe(6377); // 下限
+      expect(result.personal.pension).toBe(Math.round(6377 * 0.08 * 100) / 100);
+    });
+
+    it("should apply upper bound for high salary", () => {
+      const result = calcSocialInsurance(50000);
+      expect(result.base).toBe(31884); // 上限
+      expect(result.company.pension).toBe(Math.round(31884 * 0.16 * 100) / 100);
+    });
+
+    it("should compute correct totals", () => {
+      const result = calcSocialInsurance(10000);
+      const expectedCompanyTotal = 1600 + 950 + 50 + 40 + 1200;
+      const expectedPersonalTotal = 800 + 200 + 50 + 1200;
+      expect(result.company_total).toBeCloseTo(expectedCompanyTotal, 2);
+      expect(result.personal_total).toBeCloseTo(expectedPersonalTotal, 2);
+    });
+
+    it("should handle salary at lower boundary", () => {
+      const result = calcSocialInsurance(6377);
+      expect(result.base).toBe(6377);
+    });
+
+    it("should handle salary at upper boundary", () => {
+      const result = calcSocialInsurance(31884);
+      expect(result.base).toBe(31884);
+    });
+  });
+
+  describe("calcPersonalTax — 个税计算", () => {
+    it("should calculate tax at 3% bracket", () => {
+      // 月应纳税所得额 2000，年 24000，3% 税率
+      const result = calcPersonalTax(2000);
+      expect(result.rate).toBe(0.03);
+      expect(result.deduction).toBe(0);
+      expect(result.tax).toBe(60); // 2000 × 3%
+    });
+
+    it("should calculate tax at 10% bracket", () => {
+      // 月应纳税所得额 5000，年 60000，10% 税率
+      const result = calcPersonalTax(5000);
+      expect(result.rate).toBe(0.10);
+      expect(result.deduction).toBe(2520);
+      // (60000 × 0.10 - 2520) / 12 = (6000 - 2520) / 12 = 290
+      expect(result.tax).toBe(290);
+    });
+
+    it("should calculate tax at 20% bracket", () => {
+      // 月应纳税所得额 15000，年 180000
+      const result = calcPersonalTax(15000);
+      expect(result.rate).toBe(0.20);
+      // (180000 × 0.20 - 16920) / 12 = (36000 - 16920) / 12 = 1590
+      expect(result.tax).toBe(1590);
+    });
+
+    it("should return 0 for zero taxable income", () => {
+      const result = calcPersonalTax(0);
+      expect(result.tax).toBe(0);
+      expect(result.rate).toBe(0.03);
+    });
+
+    it("should handle boundary at 3000/month (36000/year)", () => {
+      const result = calcPersonalTax(3000);
+      // annual = 36000, falls in first bracket (limit: 36000)
+      expect(result.rate).toBe(0.03);
+      expect(result.tax).toBe(90); // 3000 × 3%
+    });
+
+    it("should handle high income at 45% bracket", () => {
+      // 月应纳税所得额 100000，年 1200000
+      const result = calcPersonalTax(100000);
+      expect(result.rate).toBe(0.45);
+      // (1200000 × 0.45 - 181920) / 12 = (540000 - 181920) / 12 = 29840
+      expect(result.tax).toBe(29840);
+    });
+  });
+});

package/src/tools/hr-tool.ts

@@ -5,7 +5,7 @@
 import { Type, type Static } from "@sinclair/typebox";
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
 import type { OpcDatabase } from "../db/index.js";
-import { json } from "../utils/tool-helper.js";
+import { json, toolError } from "../utils/tool-helper.js";
 
 const HrSchema = Type.Union([
   Type.Object({
@@ -151,7 +151,9 @@ export function registerHrTool(api: OpenClawPluginApi, db: OpcDatabase): void {
               fields.push("updated_at = ?"); values.push(new Date().toISOString());
               values.push(p.record_id);
               db.execute(`UPDATE opc_hr_records SET ${fields.join(", ")} WHERE id = ?`, ...values);
-              return json(db.queryOne("SELECT * FROM opc_hr_records WHERE id = ?", p.record_id) ?? { error: "记录不存在" });
+              const hrRec = db.queryOne("SELECT * FROM opc_hr_records WHERE id = ?", p.record_id);
+              if (!hrRec) return toolError(`员工记录 ${p.record_id} 不存在`, "EMPLOYEE_NOT_FOUND");
+              return json(hrRec);
             }
 
             case "calc_social_insurance":
@@ -197,10 +199,10 @@ export function registerHrTool(api: OpenClawPluginApi, db: OpcDatabase): void {
             }
 
             default:
-              return json({ error: `未知操作: ${(p as { action: string }).action}` });
+              return toolError(`未知操作: ${(p as { action: string }).action}`, "UNKNOWN_ACTION");
           }
         } catch (err) {
-          return json({ error: err instanceof Error ? err.message : String(err) });
+          return toolError(err instanceof Error ? err.message : String(err), "DB_ERROR");
         }
       },
     },

package/src/tools/investment-tool.ts

@@ -5,7 +5,7 @@
 import { Type, type Static } from "@sinclair/typebox";
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
 import type { OpcDatabase } from "../db/index.js";
-import { json } from "../utils/tool-helper.js";
+import { json, toolError } from "../utils/tool-helper.js";
 
 const InvestmentSchema = Type.Union([
   Type.Object({
@@ -158,7 +158,7 @@ export function registerInvestmentTool(api: OpenClawPluginApi, db: OpcDatabase):
               if (p.lead_investor !== undefined) { sets.push("lead_investor = ?"); vals.push(p.lead_investor); }
               if (p.close_date !== undefined) { sets.push("close_date = ?"); vals.push(p.close_date); }
               if (p.notes !== undefined) { sets.push("notes = ?"); vals.push(p.notes); }
-              if (sets.length === 0) return json({ error: "未提供任何更新字段" });
+              if (sets.length === 0) return toolError("未提供任何更新字段", "VALIDATION_ERROR");
               vals.push(p.round_id);
               db.execute(`UPDATE opc_investment_rounds SET ${sets.join(", ")} WHERE id = ?`, ...vals);
               return json(db.queryOne("SELECT * FROM opc_investment_rounds WHERE id = ?", p.round_id));
@@ -187,10 +187,10 @@ export function registerInvestmentTool(api: OpenClawPluginApi, db: OpcDatabase):
             }
 
             default:
-              return json({ error: `未知操作: ${(p as { action: string }).action}` });
+              return toolError(`未知操作: ${(p as { action: string }).action}`, "UNKNOWN_ACTION");
           }
         } catch (err) {
-          return json({ error: err instanceof Error ? err.message : String(err) });
+          return toolError(err instanceof Error ? err.message : String(err), "DB_ERROR");
         }
       },
     },

package/src/tools/legal-tool.ts

@@ -5,7 +5,7 @@
 import { Type, type Static } from "@sinclair/typebox";
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
 import type { OpcDatabase } from "../db/index.js";
-import { json } from "../utils/tool-helper.js";
+import { json, toolError } from "../utils/tool-helper.js";
 
 const LegalSchema = Type.Union([
   Type.Object({
@@ -120,8 +120,11 @@ export function registerLegalTool(api: OpenClawPluginApi, db: OpcDatabase): void
               return json(db.query(sql, ...params2));
             }
 
-            case "get_contract":
-              return json(db.queryOne("SELECT * FROM opc_contracts WHERE id = ?", p.contract_id) ?? { error: "合同不存在" });
+            case "get_contract": {
+              const contract = db.queryOne("SELECT * FROM opc_contracts WHERE id = ?", p.contract_id);
+              if (!contract) return toolError("合同不存在", "CONTRACT_NOT_FOUND");
+              return json(contract);
+            }
 
             case "update_contract": {
               const fields: string[] = [];
@@ -133,7 +136,9 @@ export function registerLegalTool(api: OpenClawPluginApi, db: OpcDatabase): void
               fields.push("updated_at = ?"); values.push(new Date().toISOString());
               values.push(p.contract_id);
               db.execute(`UPDATE opc_contracts SET ${fields.join(", ")} WHERE id = ?`, ...values);
-              return json(db.queryOne("SELECT * FROM opc_contracts WHERE id = ?", p.contract_id) ?? { error: "合同不存在" });
+              const updated = db.queryOne("SELECT * FROM opc_contracts WHERE id = ?", p.contract_id);
+              if (!updated) return toolError("合同不存在", "CONTRACT_NOT_FOUND");
+              return json(updated);
             }
 
             case "contract_risk_check": {
@@ -166,7 +171,7 @@ export function registerLegalTool(api: OpenClawPluginApi, db: OpcDatabase): void
             case "contract_template": {
               const tpl = CONTRACT_TEMPLATES[p.contract_type];
               if (!tpl) {
-                return json({ error: `无此模板，可用: ${Object.keys(CONTRACT_TEMPLATES).join(", ")}` });
+                return toolError(`无此模板，可用: ${Object.keys(CONTRACT_TEMPLATES).join(", ")}`, "INVALID_INPUT");
               }
               return json(tpl);
             }
@@ -177,10 +182,10 @@ export function registerLegalTool(api: OpenClawPluginApi, db: OpcDatabase): void
             }
 
             default:
-              return json({ error: `未知操作: ${(p as { action: string }).action}` });
+              return toolError(`未知操作: ${(p as { action: string }).action}`, "UNKNOWN_ACTION");
           }
         } catch (err) {
-          return json({ error: err instanceof Error ? err.message : String(err) });
+          return toolError(err instanceof Error ? err.message : String(err), "DB_ERROR");
         }
       },
     },

package/src/tools/lifecycle-tool.ts

@@ -5,7 +5,7 @@
 import { Type, type Static } from "@sinclair/typebox";
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
 import type { OpcDatabase } from "../db/index.js";
-import { json } from "../utils/tool-helper.js";
+import { json, toolError } from "../utils/tool-helper.js";
 
 const LifecycleSchema = Type.Union([
   Type.Object({
@@ -151,7 +151,7 @@ export function registerLifecycleTool(api: OpenClawPluginApi, db: OpcDatabase):
                 sets.push("completed_date = ?");
                 vals.push(new Date().toISOString().slice(0, 10));
               }
-              if (sets.length === 0) return json({ error: "未提供任何更新字段" });
+              if (sets.length === 0) return toolError("未提供任何更新字段", "VALIDATION_ERROR");
               vals.push(p.milestone_id);
               db.execute(`UPDATE opc_milestones SET ${sets.join(", ")} WHERE id = ?`, ...vals);
               return json(db.queryOne("SELECT * FROM opc_milestones WHERE id = ?", p.milestone_id));
@@ -159,7 +159,7 @@ export function registerLifecycleTool(api: OpenClawPluginApi, db: OpcDatabase):
 
             case "generate_report": {
               const company = db.queryOne("SELECT * FROM opc_companies WHERE id = ?", p.company_id);
-              if (!company) return json({ error: "公司不存在" });
+              if (!company) return toolError("公司不存在", "COMPANY_NOT_FOUND");
 
               const employees = db.query(
                 "SELECT COUNT(*) as count FROM opc_hr_records WHERE company_id = ? AND status = 'active'", p.company_id,
@@ -237,10 +237,10 @@ export function registerLifecycleTool(api: OpenClawPluginApi, db: OpcDatabase):
             }
 
             default:
-              return json({ error: `未知操作: ${(p as { action: string }).action}` });
+              return toolError(`未知操作: ${(p as { action: string }).action}`, "UNKNOWN_ACTION");
           }
         } catch (err) {
-          return json({ error: err instanceof Error ? err.message : String(err) });
+          return toolError(err instanceof Error ? err.message : String(err), "DB_ERROR");
         }
       },
     },

package/src/tools/media-tool.ts

@@ -5,7 +5,7 @@
 import { Type, type Static } from "@sinclair/typebox";
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
 import type { OpcDatabase } from "../db/index.js";
-import { json } from "../utils/tool-helper.js";
+import { json, toolError } from "../utils/tool-helper.js";
 
 const MediaSchema = Type.Union([
   Type.Object({
@@ -130,7 +130,9 @@ export function registerMediaTool(api: OpenClawPluginApi, db: OpcDatabase): void
               fields.push("updated_at = ?"); values.push(new Date().toISOString());
               values.push(p.content_id);
               db.execute(`UPDATE opc_media_content SET ${fields.join(", ")} WHERE id = ?`, ...values);
-              return json(db.queryOne("SELECT * FROM opc_media_content WHERE id = ?", p.content_id) ?? { error: "内容不存在" });
+              const updated = db.queryOne("SELECT * FROM opc_media_content WHERE id = ?", p.content_id);
+              if (!updated) return toolError("内容不存在", "RECORD_NOT_FOUND");
+              return json(updated);
             }
 
             case "content_calendar": {
@@ -149,7 +151,7 @@ export function registerMediaTool(api: OpenClawPluginApi, db: OpcDatabase): void
             case "platform_guide": {
               const guide = PLATFORM_GUIDES[p.platform];
               if (!guide) {
-                return json({ error: `无此平台指南，可用: ${Object.keys(PLATFORM_GUIDES).join(", ")}` });
+                return toolError(`无此平台指南，可用: ${Object.keys(PLATFORM_GUIDES).join(", ")}`, "INVALID_INPUT");
               }
               return json({ platform: p.platform, ...guide });
             }
@@ -160,10 +162,10 @@ export function registerMediaTool(api: OpenClawPluginApi, db: OpcDatabase): void
             }
 
             default:
-              return json({ error: `未知操作: ${(p as { action: string }).action}` });
+              return toolError(`未知操作: ${(p as { action: string }).action}`, "UNKNOWN_ACTION");
           }
         } catch (err) {
-          return json({ error: err instanceof Error ? err.message : String(err) });
+          return toolError(err instanceof Error ? err.message : String(err), "DB_ERROR");
         }
       },
     },

package/src/tools/monitoring-tool.ts

@@ -5,7 +5,7 @@
 import { Type, type Static } from "@sinclair/typebox";
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
 import type { OpcDatabase } from "../db/index.js";
-import { json } from "../utils/tool-helper.js";
+import { json, toolError } from "../utils/tool-helper.js";
 
 const MonitoringSchema = Type.Union([
   Type.Object({
@@ -120,7 +120,9 @@ export function registerMonitoringTool(api: OpenClawPluginApi, db: OpcDatabase):
                 "UPDATE opc_alerts SET status = 'resolved', resolved_at = ? WHERE id = ?",
                 now, p.alert_id,
               );
-              return json(db.queryOne("SELECT * FROM opc_alerts WHERE id = ?", p.alert_id) ?? { error: "告警不存在" });
+              const alert = db.queryOne("SELECT * FROM opc_alerts WHERE id = ?", p.alert_id);
+              if (!alert) return toolError("告警不存在", "RECORD_NOT_FOUND");
+              return json(alert);
             }
 
             case "kpi_summary": {
@@ -193,10 +195,10 @@ export function registerMonitoringTool(api: OpenClawPluginApi, db: OpcDatabase):
             }
 
             default:
-              return json({ error: `未知操作: ${(p as { action: string }).action}` });
+              return toolError(`未知操作: ${(p as { action: string }).action}`, "UNKNOWN_ACTION");
           }
         } catch (err) {
-          return json({ error: err instanceof Error ? err.message : String(err) });
+          return toolError(err instanceof Error ? err.message : String(err), "DB_ERROR");
         }
       },
     },

package/src/tools/opb-tool.ts

@@ -8,7 +8,7 @@
 import { Type, type Static } from "@sinclair/typebox";
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
 import type { OpcDatabase } from "../db/index.js";
-import { json } from "../utils/tool-helper.js";
+import { json, toolError } from "../utils/tool-helper.js";
 
 const OPB_FIELDS = [
   "track",             // 赛道（所处行业/细分市场）
@@ -110,7 +110,7 @@ export function registerOpbTool(api: OpenClawPluginApi, db: OpcDatabase): void {
                 "SELECT id FROM opc_opb_canvas WHERE company_id = ?", p.company_id,
               ) as { id: string } | null;
               if (existing) {
-                return json({ ok: false, error: "该公司画布已存在，请使用 canvas_update 更新" });
+                return toolError("该公司画布已存在，请使用 canvas_update 更新", "VALIDATION_ERROR");
               }
               const id = db.genId();
               const now = new Date().toISOString();
@@ -139,7 +139,7 @@ export function registerOpbTool(api: OpenClawPluginApi, db: OpcDatabase): void {
                 "SELECT * FROM opc_opb_canvas WHERE company_id = ?", p.company_id,
               ) as CanvasRow | null;
               if (!canvas) {
-                return json({ ok: false, error: "该公司暂无 OPB 画布，请先使用 canvas_init 创建" });
+                return toolError("该公司暂无 OPB 画布，请先使用 canvas_init 创建", "RECORD_NOT_FOUND");
               }
               // Calculate completion percentage
               const filled = OPB_FIELDS.filter(f => canvas[f as keyof CanvasRow] && String(canvas[f as keyof CanvasRow]).trim() !== "").length;
@@ -152,7 +152,7 @@ export function registerOpbTool(api: OpenClawPluginApi, db: OpcDatabase): void {
                 "SELECT id FROM opc_opb_canvas WHERE company_id = ?", p.company_id,
               ) as { id: string } | null;
               if (!existing) {
-                return json({ ok: false, error: "该公司暂无 OPB 画布，请先使用 canvas_init 创建" });
+                return toolError("该公司暂无 OPB 画布，请先使用 canvas_init 创建", "RECORD_NOT_FOUND");
               }
               const now = new Date().toISOString();
               const updates: string[] = [];
@@ -165,7 +165,7 @@ export function registerOpbTool(api: OpenClawPluginApi, db: OpcDatabase): void {
                 }
               }
               if (updates.length === 0) {
-                return json({ ok: false, error: "未提供任何更新字段" });
+                return toolError("未提供任何更新字段", "VALIDATION_ERROR");
               }
               updates.push("updated_at = ?");
               vals.push(now, existing.id);
@@ -180,10 +180,10 @@ export function registerOpbTool(api: OpenClawPluginApi, db: OpcDatabase): void {
             }
 
             default:
-              return json({ error: "未知 action" });
+              return toolError(`未知操作: ${(p as { action: string }).action}`, "UNKNOWN_ACTION");
           }
         } catch (err) {
-          return json({ error: err instanceof Error ? err.message : String(err) });
+          return toolError(err instanceof Error ? err.message : String(err), "DB_ERROR");
         }
       },
     },

package/src/tools/opc-tool.ts

@@ -10,7 +10,7 @@ import { CompanyManager } from "../opc/company-manager.js";
 import type { OpcCompanyStatus, OpcTransactionCategory, OpcTransactionType } from "../opc/types.js";
 import { ensureCompanyWorkspace } from "../opc/workspace-factory.js";
 import { OpcManageSchema, type OpcManageParams } from "./schemas.js";
-import { json } from "../utils/tool-helper.js";
+import { json, toolError, validationError } from "../utils/tool-helper.js";
 
 /**
  * 将 company_id（可能是 DB ID 或公司名称）解析为实际数据库 ID。
@@ -75,34 +75,42 @@ export function registerOpcTool(api: OpenClawPluginApi, db: OpcDatabase): void {
               return json(company);
             }
 
-            case "get_company":
-              return json(manager.getCompany(p.company_id) ?? { error: "公司不存在" });
+            case "get_company": {
+              const found = manager.getCompany(p.company_id);
+              if (!found) return toolError(`公司 ${p.company_id} 不存在`, "COMPANY_NOT_FOUND");
+              return json(found);
+            }
 
             case "list_companies":
               return json(
                 manager.listCompanies(p.status as OpcCompanyStatus | undefined),
               );
 
-            case "update_company":
-              return json(
-                manager.updateCompany(p.company_id, {
-                  name: p.name,
-                  industry: p.industry,
-                  description: p.description,
-                  owner_contact: p.owner_contact,
-                }) ?? { error: "公司不存在" },
-              );
+            case "update_company": {
+              const updated = manager.updateCompany(p.company_id, {
+                name: p.name,
+                industry: p.industry,
+                description: p.description,
+                owner_contact: p.owner_contact,
+              });
+              if (!updated) return toolError(`公司 ${p.company_id} 不存在`, "COMPANY_NOT_FOUND");
+              return json(updated);
+            }
 
-            case "activate_company":
-              return json(manager.activateCompany(p.company_id) ?? { error: "公司不存在" });
+            case "activate_company": {
+              const activated = manager.activateCompany(p.company_id);
+              if (!activated) return toolError(`公司 ${p.company_id} 不存在`, "COMPANY_NOT_FOUND");
+              return json(activated);
+            }
 
-            case "change_company_status":
-              return json(
-                manager.transitionStatus(
-                  p.company_id,
-                  p.new_status as OpcCompanyStatus,
-                ) ?? { error: "公司不存在" },
+            case "change_company_status": {
+              const transitioned = manager.transitionStatus(
+                p.company_id,
+                p.new_status as OpcCompanyStatus,
               );
+              if (!transitioned) return toolError(`公司 ${p.company_id} 不存在`, "COMPANY_NOT_FOUND");
+              return json(transitioned);
+            }
 
             // ── 交易记录 ──
             case "add_transaction":
@@ -160,7 +168,9 @@ export function registerOpcTool(api: OpenClawPluginApi, db: OpcDatabase): void {
               if (p.tags) updateData.tags = p.tags;
               if (p.notes) updateData.notes = p.notes;
               if (p.last_contact_date) updateData.last_contact_date = p.last_contact_date;
-              return json(db.updateContact(p.contact_id, updateData) ?? { error: "联系人不存在" });
+              const updatedContact = db.updateContact(p.contact_id, updateData);
+              if (!updatedContact) return toolError(`联系人 ${p.contact_id} 不存在`, "CONTACT_NOT_FOUND");
+              return json(updatedContact);
             }
 
             case "delete_contact":
@@ -192,10 +202,10 @@ export function registerOpcTool(api: OpenClawPluginApi, db: OpcDatabase): void {
             }
 
             default:
-              return json({ error: `未知操作: ${(p as { action: string }).action}` });
+              return toolError(`未知操作: ${(p as { action: string }).action}`, "UNKNOWN_ACTION");
           }
         } catch (err) {
-          return json({ error: err instanceof Error ? err.message : String(err) });
+          return toolError(err instanceof Error ? err.message : String(err));
         }
       },
     },

package/src/tools/procurement-tool.ts

@@ -5,7 +5,7 @@
 import { Type, type Static } from "@sinclair/typebox";
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
 import type { OpcDatabase } from "../db/index.js";
-import { json } from "../utils/tool-helper.js";
+import { json, toolError } from "../utils/tool-helper.js";
 
 const ProcurementSchema = Type.Union([
   Type.Object({
@@ -123,7 +123,7 @@ export function registerProcurementTool(api: OpenClawPluginApi, db: OpcDatabase)
               if (p.status !== undefined) { sets.push("status = ?"); vals.push(p.status); }
               if (p.delivery_date !== undefined) { sets.push("delivery_date = ?"); vals.push(p.delivery_date); }
               if (p.notes !== undefined) { sets.push("notes = ?"); vals.push(p.notes); }
-              if (sets.length === 0) return json({ error: "未提供任何更新字段" });
+              if (sets.length === 0) return toolError("未提供任何更新字段", "VALIDATION_ERROR");
               vals.push(p.order_id);
               db.execute(`UPDATE opc_procurement_orders SET ${sets.join(", ")} WHERE id = ?`, ...vals);
               return json(db.queryOne("SELECT * FROM opc_procurement_orders WHERE id = ?", p.order_id));
@@ -177,10 +177,10 @@ export function registerProcurementTool(api: OpenClawPluginApi, db: OpcDatabase)
             }
 
             default:
-              return json({ error: `未知操作: ${(p as { action: string }).action}` });
+              return toolError(`未知操作: ${(p as { action: string }).action}`, "UNKNOWN_ACTION");
           }
         } catch (err) {
-          return json({ error: err instanceof Error ? err.message : String(err) });
+          return toolError(err instanceof Error ? err.message : String(err), "DB_ERROR");
         }
       },
     },

package/src/tools/project-tool.ts

@@ -5,7 +5,7 @@
 import { Type, type Static } from "@sinclair/typebox";
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
 import type { OpcDatabase } from "../db/index.js";
-import { json } from "../utils/tool-helper.js";
+import { json, toolError } from "../utils/tool-helper.js";
 
 const ProjectSchema = Type.Union([
   Type.Object({
@@ -120,7 +120,9 @@ export function registerProjectTool(api: OpenClawPluginApi, db: OpcDatabase): vo
               fields.push("updated_at = ?"); values.push(new Date().toISOString());
               values.push(p.project_id);
               db.execute(`UPDATE opc_projects SET ${fields.join(", ")} WHERE id = ?`, ...values);
-              return json(db.queryOne("SELECT * FROM opc_projects WHERE id = ?", p.project_id) ?? { error: "项目不存在" });
+              const updated = db.queryOne("SELECT * FROM opc_projects WHERE id = ?", p.project_id);
+              if (!updated) return toolError("项目不存在", "RECORD_NOT_FOUND");
+              return json(updated);
             }
 
             case "add_task": {
@@ -155,12 +157,14 @@ export function registerProjectTool(api: OpenClawPluginApi, db: OpcDatabase): vo
               fields.push("updated_at = ?"); values.push(new Date().toISOString());
               values.push(p.task_id);
               db.execute(`UPDATE opc_tasks SET ${fields.join(", ")} WHERE id = ?`, ...values);
-              return json(db.queryOne("SELECT * FROM opc_tasks WHERE id = ?", p.task_id) ?? { error: "任务不存在" });
+              const updatedTask = db.queryOne("SELECT * FROM opc_tasks WHERE id = ?", p.task_id);
+              if (!updatedTask) return toolError("任务不存在", "RECORD_NOT_FOUND");
+              return json(updatedTask);
             }
 
             case "project_summary": {
               const project = db.queryOne("SELECT * FROM opc_projects WHERE id = ?", p.project_id);
-              if (!project) return json({ error: "项目不存在" });
+              if (!project) return toolError("项目不存在", "RECORD_NOT_FOUND");
               const tasks = db.query("SELECT status, COUNT(*) as count, SUM(hours_estimated) as est, SUM(hours_actual) as actual FROM opc_tasks WHERE project_id = ? GROUP BY status", p.project_id);
               const overdue = db.query(
                 "SELECT * FROM opc_tasks WHERE project_id = ? AND status != 'done' AND due_date != '' AND due_date < date('now')",
@@ -189,10 +193,10 @@ export function registerProjectTool(api: OpenClawPluginApi, db: OpcDatabase): vo
             }
 
             default:
-              return json({ error: `未知操作: ${(p as { action: string }).action}` });
+              return toolError(`未知操作: ${(p as { action: string }).action}`, "UNKNOWN_ACTION");
           }
         } catch (err) {
-          return json({ error: err instanceof Error ? err.message : String(err) });
+          return toolError(err instanceof Error ? err.message : String(err), "DB_ERROR");
         }
       },
     },