cloudcc-cli 2.3.1 → 2.3.3

package/src/timer/doc.js

@@ -0,0 +1,57 @@
+/**
+ * timer（定时类）文档入口：正文均在 `docs/` 目录。
+ */
+const fs = require("fs");
+const path = require("path");
+
+const DOCS_DIR = path.join(__dirname, "docs");
+const BACKEND_SDK_JAVA = path.join(__dirname, "..", "api", "backend-sdk-java.md");
+
+function readDocFile(basename) {
+    return fs.readFileSync(path.join(DOCS_DIR, `${basename}.md`), "utf8");
+}
+
+/** 介绍文档：定时类概念、能力与典型场景 */
+function getIntroductionDoc() {
+    return readDocFile("introduction");
+}
+
+/** 开发指导：定时作业/定时类实践；末尾拼接后端 Java SDK 速查 */
+function getDevGuideDoc() {
+    const base = readDocFile("devguide").trimEnd();
+    let sdk = "";
+    try {
+        sdk = fs.readFileSync(BACKEND_SDK_JAVA, "utf8").trim();
+    } catch (e) {
+        sdk = "";
+    }
+    if (!sdk) {
+        return base;
+    }
+    return [base, "", "---", "", "## 附录：后端 SDK（Java）速查", "", sdk, ""].join("\n");
+}
+
+/**
+ * cc doc timer <introduction|devguide>
+ * @param {string[]} argvs [doc, type, introduction|devguide, ...]
+ */
+function doc(argvs) {
+    const subType = argvs[2];
+    const key = String(subType || "").trim().toLowerCase();
+    if (!key) {
+        throw new Error("cc doc timer 需要子命令：introduction 或 devguide");
+    }
+    if (key === "introduction") {
+        const content = getIntroductionDoc();
+        console.log(content);
+        return content;
+    }
+    if (key === "devguide") {
+        const content = getDevGuideDoc();
+        console.log(content);
+        return content;
+    }
+    throw new Error(`doc 不支持的子命令: ${subType}，请使用 introduction 或 devguide`);
+}
+
+module.exports = doc;

package/{.cursor/skills/cloudcc-cli-dev/docs/cloudcc/345/256/232/346/227/266/344/275/234/344/270/232.md → src/timer/docs/devguide.md}

@@ -4,6 +4,82 @@
 
 ---
 
+## CLI 与本地文件（必读）
+
+本仓库中的**定时类**（与定时作业绑定的 Java 类）通过 **cloudcc-cli** 与平台同步，本地目录为 **`schedule/<类名>/`**（内含 `*.java` 与 `config.json`），源码中的 `// @SOURCE_CONTENT_START` … `// @SOURCE_CONTENT_END` 与发布、拉取逻辑一致。**必须通过下列命令** 完成新建目录、发布、拉取与删除；不要手工新建 `schedule/` 子目录、不要整包复制其他项目的定时类、不要私自篡改 `config.json` 中的 `id` 或版本字段。
+
+**允许的做法**：在 CLI 已生成的主类中，仅在上述 SOURCE 标记之间编写业务逻辑；与云端列表、详情、拉取、删除、发布相关的操作一律走命令。
+
+执行命令前请确认：已完成 `cc doc project devguide` 中的环境初始化，项目根目录配置可用且包含 `accessToken`。
+
+### 命令总览（以代码实现为准）
+
+```bash
+cc create timer <name>
+cc publish timer <name>
+cc pull timer <name>
+cc get timer [listQueryJson] [projectPath]
+cc detail timer <name>
+cc detail timer "" <id>
+cc pullList timer <id> <projectPath>
+cc delete timer <nameOrId> [projectPath]
+cc doc timer <introduction|devguide>
+```
+
+参数约定：
+
+- `name`：定时类名，与 `schedule/<name>/` 目录名一致。
+- `listQueryJson`：可选；列表查询 JSON 经 `encodeURI(JSON.stringify(...))` 编码后传入；不传则使用默认分页参数。
+- `projectPath`：项目根路径，可选。
+- `id`：线上定时类 ID。`detail` 仅查服务器时：`cc detail timer "" <id>`。`pullList` 必填。
+- `nameOrId`：本地目录名或类 ID；若本地 `config.json` 含 `id`，删除时优先使用该 ID。
+
+### 命令作用摘要
+
+| 命令 | 作用 |
+|------|------|
+| `create` | 在 `schedule/<name>/` 生成继承 `CCSchedule` 的 Java 模板与 `config.json` |
+| `publish` | 将 SOURCE 区域提交到服务器；首次成功后可写回 `config.json` 的 `id` |
+| `pull` | 按本地 `id` 拉取远端源码，覆盖主类中 SOURCE 区域（需已发布） |
+| `get` | 查询线上定时类列表（JSON 输出） |
+| `detail` | 按类名优先读本地；或仅按 `id` 读服务器 |
+| `pullList` | 按类 `id` 将线上定时类落到指定项目的 `schedule/<类名>/` |
+| `delete` | 删除服务器上的定时类 |
+| `doc` | 输出模块文档；`devguide` 含附录后端 Java SDK 速查 |
+
+### 推荐操作顺序
+
+```bash
+# 1) 查看线上已有定时类（可选）
+cc get timer
+
+# 2) 新建定时类（仅通过 create 生成目录与模板）
+cc create timer MySchedule
+
+# 3) 编辑 schedule/MySchedule/MySchedule.java 中 SOURCE 区域后发布
+cc publish timer MySchedule
+
+# 4) 与服务器对齐时拉取
+cc pull timer MySchedule
+
+# 5) 按已知线上 ID 拉到指定项目
+cc pullList timer <线上类ID> <projectPath>
+
+# 6) 删除
+cc delete timer MySchedule
+```
+
+### 文档子命令
+
+```bash
+cc doc timer introduction
+cc doc timer devguide
+```
+
+仅支持 `introduction` 与 `devguide`。
+
+---
+
 ## 📌 什么是定时作业？
 
 定时作业是一种**自动化任务调度系统**，允许你：
@@ -416,7 +492,13 @@ function main($CCDK, obj) {
 
 ## 📋 管理操作
 
-### 查询定时作业
+### 定时类：使用 CLI 管理本地 `schedule/`（推荐）
+
+与**定时类源码**的创建、同步、删除，请优先使用上文「CLI 与本地文件（必读）」中的命令，避免绕过 CLI 直接改目录或 `config.json`。
+
+以下接口面向**定时作业配置**（调度时间、启用状态等在设置中的作业），与 `schedule/` 下定时类源码管理是不同层面；具体以你环境的管理后台与 OpenAPI 为准。
+
+### 查询定时作业（平台接口示例）
 
 ```bash
 # 获取列表

package/src/timer/get.js

@@ -1,7 +1,13 @@
 const { getPackageJson } = require("../../utils/config")
 const { postClass } = require("../../utils/http")
 
-async function get(arg1, arg2, isMcp = false) {
+/**
+ * cc get timer [listQueryJson] [projectPath]
+ * @param {string[]} argvs
+ */
+async function get(argvs, isMcp = false) {
+    const arg1 = argvs[2]
+    const arg2 = argvs[3]
     let body = arg1 != null && arg1 != '' ? JSON.parse(decodeURI(arg1)) : { shownum: "2000", showpage: "1", fid: "", sname: '', rptcond: '', rptorder: '' }
     let config = await getPackageJson(arg2);
     let res = await postClass(config.setupSvc + "/api/ccPeak/list", body, config.accessToken)

package/src/timer/index.js

@@ -6,8 +6,10 @@ cc.get = require("./get")
 cc.pullList = require("./pullList")
 cc.detail = require("./detail")
 cc.delete = require("./delete")
+cc.doc = require("./doc")
+
 function Timer(action, argvs) {
-  cc[action](argvs[2], argvs[3])
+  cc[action](argvs)
 }
 
 module.exports = Timer;

package/src/timer/publish.js

@@ -7,7 +7,12 @@ const { javaContentRegular } = require("../../utils/utils")
 
 const { getPackageJson } = require("../../utils/config")
 const { postClass } = require("../../utils/http")
-async function publish(name) {
+/**
+ * cc publish timer <name>
+ * @param {string[]} argvs
+ */
+async function publish(argvs) {
+  const name = argvs[2]
   let res = await checkUpdate();
   if (!res) {
     console.error();

package/src/timer/pull.js

@@ -8,7 +8,12 @@ const { javaContentRegular } = require("../../utils/utils")
 const { getPackageJson } = require("../../utils/config")
 const { postClass } = require("../../utils/http")
 
-async function pull(name) {
+/**
+ * cc pull timer <name>
+ * @param {string[]} argvs
+ */
+async function pull(argvs) {
+  const name = argvs[2]
   let res = await checkUpdate();
   if (!res) {
     console.error();

package/src/timer/pullList.js

@@ -4,10 +4,12 @@ const { getPackageJson } = require("../../utils/config");
 const { postClass } = require("../../utils/http");
 
 /**
- * 批量拉取定时器详情并生成本地文件
- * @param timer id
+ * cc pullList timer <id> <projectPath>
+ * @param {string[]} argvs
  */
-async function pullList(arg1, arg2, isMcp = false) {
+async function pullList(argvs, isMcp = false) {
+    const arg1 = argvs[2]
+    const arg2 = argvs[3]
     const body = { id: arg1 };
     let config = await getPackageJson(arg2);
     const res = await postClass(config.setupSvc + "/api/ccPeak/detail", body, config.accessToken);

package/src/triggers/detail.js

@@ -5,12 +5,12 @@ const { getPackageJson } = require("../../utils/config")
 const { postClass } = require("../../utils/http")
 
 /**
- * 获取触发器详细信息
- * @param {string} namePath - 触发器路径 "objectName/triggerName"（优先从本地查询）
- * @param {string} id - 触发器ID（当没有namePath时从服务器查询）
- * @returns {Object} 触发器详细信息
+ * cc detail triggers <namePath> <id>
+ * @param {string[]} argvs [detail, type, namePath?, id?]
  */
-async function detail(namePath, id) {
+async function detail(argvs) {
+    const namePath = argvs[2]
+    const id = argvs[3]
     // 如果有 namePath，优先查询本地
     if (namePath && namePath !== '') {
         const triggerPath = path.join(process.cwd(), `triggers/${namePath}/`);

package/src/triggers/doc.js

@@ -1,378 +1,63 @@
 /**
- * triggers 文档统一入口（全量一次性输出）
+ * triggers 文档入口：正文均在 `docs/` 目录，本文件只负责按子命令读取并输出。
  */
 const fs = require("fs");
 const path = require("path");
 
-function generateFullMarkdownDoc() {
-    const lines = [
-        "# CloudCC 触发器使用总结",
-        "",
-        "> 基于 25 个生产环境触发器实例分析。",
-        "> 文档版本：v1.0",
-        "> 更新时间：2026-03-24",
-        "",
-        "---",
-        "",
-        "## 一、什么是触发器",
-        "",
-        "CloudCC 触发器是完全符合 Java 语法规范的代码，在特定业务事件发生时自动执行，实现业务逻辑自动化处理。",
-        "",
-        "触发器本质：",
-        "- 一段 Java 代码，运行在 CloudCC 平台沙箱环境中",
-        "- 使用 CCService、CCObject 等平台提供的 API 类",
-        "- 在数据变更的特定时刻（前/后）自动触发执行",
-        "",
-        "## 二、触发器能干什么",
-        "",
-        "### 2.1 核心能力",
-        "",
-        "| 能力 | 说明 | 示例 |",
-        "|------|------|------|",
-        "| 自动赋值 | 在记录保存前自动计算并填充字段 | 个人业绩/部门业绩自动赋值 |",
-        "| 数据校验 | 阻止不符合业务规则的数据保存 | 预算金额校验、审批金额验证 |",
-        "| 关联更新 | 修改一条记录时自动更新关联记录 | 回款明细汇总到收款计划 |",
-        "| 自动生成 | 根据业务规则自动创建新记录 | 审批通过后自动生成回款记录 |",
-        "| 权限控制 | 自动设置数据共享权限 | 按部门/人员自动共享 |",
-        "| 状态同步 | 审批状态变更后同步更新相关字段 | 预算审批状态回写 |",
-        "| 汇总计算 | 实时汇总明细数据到主记录 | 部门业绩字段汇总 |",
-        "",
-        "### 2.2 技术能力（基于 CCService API）",
-        "",
-        "```java",
-        "// 1. 新增记录",
-        "CCObject opp = new CCObject(\"Opportunity\");",
-        "opp.put(\"name\", \"value\");",
-        "cs.insert(opp);",
-        "",
-        "// 2. 查询记录（指定字段）",
-        "List<CCObject> opps1 = cs.cqueryByFields(",
-        "  \"Opportunity\",",
-        "  \"khmc__c='\" + record_new.get(\"id\") + \"'\",",
-        "  \"id,name,createdate\"",
-        ");",
-        "",
-        "// 3. 查询记录（全部字段）",
-        "List<CCObject> opps2 = cs.cquery(",
-        "  \"Opportunity\",",
-        "  \"khmc__c='\" + record_new.get(\"id\") + \"'\"",
-        ");",
-        "",
-        "// 4. 复杂查询",
-        "List<CCObject> ccobjs = cs.cqlQuery(",
-        "  \"Opportunity\",",
-        "  \"select sum(amount) as sumAmount from Opportunity where khmc='0012001238ytwuiw'\"",
-        ");",
-        "",
-        "// 5. 修改/删除",
-        "cs.update(opp);",
-        "cs.delete(opp);",
-        "",
-        "// 6. 发送邮件通知",
-        "SendEmail sendEmail = new SendEmail(userInfo);",
-        "sendEmail.sendMailFromSystem(toAddress, ccAddress, bccAddress, subject, content, isText);",
-        "```",
-        "",
-        "---",
-        "",
-        "## 三、触发器的触发时机详解",
-        "",
-        "### 3.1 beforeUpsert（创建或更新前）",
-        "- 执行时机：记录保存之前，数据尚未写入数据库",
-        "- 典型用途：自动计算字段、数据格式校验、阻止非法数据保存、自动填充默认值",
-        "- 生产实例：个人业绩/部门业绩赋值、计算产研成本/净业绩、生成部门/个人业绩",
-        "",
-        "```java",
-        "// beforeUpsert 示例",
-        "CCObject record = (CCObject) data.get(\"record\");",
-        "BigDecimal income = record.getBigDecimal(\"ysr\");",
-        "BigDecimal cost = record.getBigDecimal(\"cycb\");",
-        "BigDecimal net = income.subtract(cost);",
-        "record.put(\"jyj\", net);",
-        "if (net.compareTo(BigDecimal.ZERO) < 0) {",
-        "  throw new Exception(\"毛利不能为负数！\");",
-        "}",
-        "```",
-        "",
-        "### 3.2 afterInsert（创建后）",
-        "- 执行时机：记录创建成功后（可获取 ID）",
-        "- 典型用途：基于新记录 ID 创建关联记录、发送创建通知、初始化关联数据",
-        "- 生产实例：根据净业绩拆分生成净业绩拆分回款",
-        "",
-        "```java",
-        "// afterInsert 示例",
-        "CCObject newRecord = (CCObject) data.get(\"record\");",
-        "String recordId = newRecord.getString(\"id\");",
-        "CCObject hkRecord = new CCObject(\"Huikuan\");",
-        "hkRecord.put(\"mingxi__c\", recordId);",
-        "hkRecord.put(\"je\", newRecord.get(\"je\"));",
-        "cs.insert(hkRecord);",
-        "```",
-        "",
-        "### 3.3 afterUpsert（创建或更新后）",
-        "- 执行时机：记录保存成功后（新增或修改）",
-        "- 典型用途：汇总数据到父记录、触发下游流程、更新关联记录状态",
-        "- 生产实例：金额汇总到收款计划、更新部门业绩字段、更新回款明细",
-        "",
-        "```java",
-        "// afterUpsert 示例 - 汇总金额到父记录",
-        "CCObject detail = (CCObject) data.get(\"record\");",
-        "String planId = detail.getString(\"skjh__c\");",
-        "List<CCObject> plans = cs.cqueryByFields(",
-        "  \"ShoukuanJihua\",",
-        "  \"id='\" + planId + \"'\",",
-        "  \"id,shyjje,yishouje\"",
-        ");",
-        "if (!plans.isEmpty()) {",
-        "  CCObject plan = plans.get(0);",
-        "  BigDecimal current = plan.getBigDecimal(\"yishouje\");",
-        "  BigDecimal detailAmount = detail.getBigDecimal(\"je\");",
-        "  plan.put(\"yishouje\", current.add(detailAmount));",
-        "  cs.update(plan);",
-        "}",
-        "```",
-        "",
-        "### 3.4 afterDelete（删除后）",
-        "- 执行时机：记录删除成功后",
-        "- 典型用途：清理关联数据、反向汇总更新",
-        "- 生产实例：回款明细删除后重新计算回款金额",
-        "",
-        "### 3.5 approval（审批时）",
-        "- 执行时机：记录提交审批或审批通过时",
-        "- 典型用途：审批前校验、审批通过后执行业务操作",
-        "- 生产实例：更新拆分审批状态、订单审批判断、审批通过计算剩余欠款",
-        "",
-        "---",
-        "",
-        "## 四、为什么要用触发器",
-        "",
-        "### 4.1 解决的核心问题",
-        "",
-        "| 问题 | 传统方案 | 触发器方案 |",
-        "|------|----------|------------|",
-        "| 数据一致性 | 依赖用户手动操作，容易遗漏 | 自动执行，保证数据准确 |",
-        "| 业务规则执行 | 前端校验可绕过 | 统一在平台层执行，无法绕过 |",
-        "| 跨对象联动 | 需要多次手动操作 | 自动关联更新 |",
-        "| 审批复杂逻辑 | 审批流配置难以承载 | Java 代码可实现复杂逻辑 |",
-        "| 实时性要求 | 定时任务有延迟 | 实时触发，立即执行 |",
-        "",
-        "### 4.2 与其他方案对比",
-        "",
-        "| 方案 | 优点 | 缺点 | 适用场景 |",
-        "|------|------|------|----------|",
-        "| 触发器 | 实时、自动、无法绕过 | 需要 Java 开发能力 | 核心业务逻辑 |",
-        "| 审批流 | 配置简单、可视化 | 逻辑能力有限 | 简单审批流程 |",
-        "| 工作流 | 可视化编排 | 复杂逻辑实现困难 | 跨系统流程编排 |",
-        "| 定时任务 | 适合批量处理 | 有延迟 | 数据同步、报表生成 |",
-        "",
-        "---",
-        "",
-        "## 五、典型业务场景",
-        "",
-        "### 5.1 财务业绩管理（核心场景）",
-        "",
-        "```text",
-        "订单 (Order)",
-        "  └─ approval：审批判断",
-        "预算 (Budget)",
-        "  ├─ beforeUpsert：计算产研成本/净业绩",
-        "  └─ afterUpsert：自动拆分/生成回款",
-        "净业绩拆分 (jyjcf)",
-        "  ├─ beforeUpsert：生成部门/个人业绩",
-        "  └─ afterUpsert：校验金额累计是否超预算",
-        "部门业绩 (bmyj)",
-        "  ├─ afterUpsert：更新部门业绩字段",
-        "  └─ afterUpdate：汇总部门资金池",
-        "回款明细 (cloudccproceeddetail)",
-        "  ├─ afterInsert：生成净业绩拆分回款",
-        "  ├─ afterUpsert：金额汇总到收款计划",
-        "  ├─ afterUpsert：更新回款明细",
-        "  └─ afterDelete：回款明细删除",
-        "```",
-        "",
-        "### 5.2 费用报销管理",
-        "",
-        "```text",
-        "费用报销提交",
-        "  -> approval 触发器：验证审批时校验预算（报销金额 <= 预算余额）",
-        "审批通过",
-        "  -> approval 触发器：计算剩余欠款（借款 - 报销）",
-        "```",
-        "",
-        "### 5.3 借款还款管理",
-        "",
-        "| 触发器 | 对象 | 时机 | 作用 |",
-        "|--------|------|------|------|",
-        "| 借款单触发器 | 借款单 | beforeUpsert | 借款前校验、自动计算 |",
-        "| 还款记录审批通过更新借款单 | 还款记录 | approval | 审批后回写借款单 |",
-        "",
-        "---",
-        "",
-        "## 六、触发器开发最佳实践",
-        "",
-        "### 6.1 代码规范",
-        "",
-        "```java",
-        "try {",
-        "  CCObject record = (CCObject) data.get(\"record\");",
-        "  cs.update(record);",
-        "} catch (Exception e) {",
-        "  System.out.println(\"触发器执行失败：\" + e.getMessage());",
-        "  throw new Exception(\"业务校验失败：\" + e.getMessage());",
-        "}",
-        "```",
-        "",
-        "### 6.2 性能优化",
-        "",
-        "```java",
-        "// 推荐：字段过滤，只查询需要的字段",
-        "List<CCObject> records = cs.cqueryByFields(",
-        "  \"Object__c\",",
-        "  \"status__c='active'\",",
-        "  \"id,name,amount__c\"",
-        ");",
-        "",
-        "// 推荐：批量更新，降低递归风险",
-        "cs.updateLt(records);",
-        "```",
-        "",
-        "### 6.3 避免递归触发",
-        "",
-        "```java",
-        "// 方法 1：使用 updateLt",
-        "cs.updateLt(records);",
-        "",
-        "// 方法 2：增加标志位（示例）",
-        "if (\"true\".equals(System.getProperty(\"trigger.running\"))) {",
-        "  return;",
-        "}",
-        "System.setProperty(\"trigger.running\", \"true\");",
-        "cs.update(record);",
-        "System.setProperty(\"trigger.running\", \"false\");",
-        "```",
-        "",
-        "---",
-        "",
-        "## 七、触发器调试与监控",
-        "",
-        "### 7.1 日志记录",
-        "",
-        "```java",
-        "System.out.println(\"=== 触发器开始执行 ===\");",
-        "System.out.println(\"对象：\" + record.getSObjectName());",
-        "System.out.println(\"操作：\" + data.get(\"action\"));",
-        "System.out.println(\"记录 ID：\" + record.get(\"id\"));",
-        "```",
-        "",
-        "### 7.2 常见问题排查",
-        "",
-        "| 问题 | 可能原因 | 解决方案 |",
-        "|------|----------|----------|",
-        "| 触发器不执行 | 未激活、触发时机不对 | 检查状态与配置 |",
-        "| 递归触发 | 更新操作再次触发触发器 | 使用 `updateLt` 或增加条件判断 |",
-        "| 性能问题 | 查询数据量过大 | 增加查询条件、字段过滤 |",
-        "| 数据不一致 | 触发器执行失败 | 增加异常处理与关键日志 |",
-        "",
-        "---",
-        "",
-        "## 八、总结",
-        "",
-        "### 8.1 触发器价值",
-        "1. 自动化：减少人工操作，降低出错率",
-        "2. 一致性：保证数据准确与规则统一执行",
-        "3. 实时性：业务变更立即响应",
-        "4. 灵活性：Java 代码可承载复杂逻辑",
-        "",
-        "### 8.2 适用与不适用场景",
-        "",
-        "**适合使用触发器：**",
-        "- 需要实时数据联动",
-        "- 核心业务规则校验",
-        "- 跨对象数据同步",
-        "- 审批流程复杂逻辑",
-        "- 自动创建或更新关联记录",
-        "",
-        "**不适合使用触发器：**",
-        "- 简单字段默认值（优先配置化能力）",
-        "- 大批量离线数据处理",
-        "- 跨系统集成调用",
-        "- 强交互型前端界面逻辑",
-        "",
-        "### 8.3 触发器开发 Checklist",
-        "",
-        "- [ ] 明确触发时机（before/after/approval）",
-        "- [ ] 评估并规避递归触发风险",
-        "- [ ] 添加异常处理与关键日志",
-        "- [ ] 覆盖边界条件测试",
-        "- [ ] 完成大数据量场景性能测试",
-        "",
-        "---",
-        "",
-        "## 附录：25 个生产触发器清单",
-        "",
-        "| # | 名称 | 对象 | 时机 | 状态 |",
-        "|---|------|------|------|------|",
-        "| 1 | 个人业绩/部门业绩赋值 | 对外付款 | beforeUpsert | ✅ |",
-        "| 2 | 个人业绩/部门业绩赋值 | 费用报销 | beforeUpsert | ❌ |",
-        "| 3 | 本部业绩统计 | 本部业绩统计 | beforeUpsert | ✅ |",
-        "| 4 | 更新拆分审批状态 | 预算 | approval | ✅ |",
-        "| 5 | 订单审批判断 | 订单 | approval | ✅ |",
-        "| 6 | 根据净业绩拆分生成净业绩拆分回款 | 回款明细 | afterInsert | ✅ |",
-        "| 7 | 金额汇总到收款计划 | 回款明细 | afterUpsert | ✅ |",
-        "| 8 | 回款明细删除 | 回款明细 | afterDelete | ❌ |",
-        "| 9 | 计算产研成本/净业绩 | 预算 | beforeUpsert | ✅ |",
-        "| 10 | 保证金回款记录 | 概算 | afterUpdate | ✅ |",
-        "| 11 | 校验金额累计是否超预算 | 净业绩拆分 | afterUpsert | ✅ |",
-        "| 12 | 更新部门业绩字段 | 部门业绩 | afterUpsert | ✅ |",
-        "| 13 | 汇总部门资金池 | 部门业绩 | afterUpdate | ✅ |",
-        "| 14 | 编辑更新部门业绩 | 净业绩拆分回款 | beforeUpsert | ✅ |",
-        "| 15 | 生成部门/个人业绩 | 净业绩拆分 | beforeUpsert | ✅ |",
-        "| 16 | 更新回款明细 | 回款明细 | afterUpsert | ✅ |",
-        "| 17 | 新建自动拆分/审批通过自动生成回款 | 预算 | afterUpsert | ✅ |",
-        "| 18 | 提交审批验证金额 | 对外付款 | approval | ❌ |",
-        "| 19 | 还款记录审批通过更新借款单 | 还款记录 | approval | ✅ |",
-        "| 20 | 审批通过计算剩余欠款 | 费用报销 | approval | ✅ |",
-        "| 21 | 借款单触发器 | 借款单 | beforeUpsert | ✅ |",
-        "| 22 | 创建编辑项目任务时判断 | 项目任务 | beforeUpsert | ✅ |",
-        "| 23 | 任务派工工时限制 | 项目任务 | afterUpsert | ✅ |",
-        "| 24 | 测试 AI 代码生成 | 客户 | beforeInsert | ❌ |",
-        "| 25 | 验证审批时校验预算 | 费用报销 | approval | ❌ |",
-        "",
-        "文档生成时间：2026-03-24",
-        "基于 CloudCC 生产环境 25 个触发器实例分析",
-        "",
-    ];
+const DOCS_DIR = path.join(__dirname, "docs");
+const BACKEND_SDK_JAVA = path.join(__dirname, "..", "api", "backend-sdk-java.md");
 
-    const base = lines.join("\n");
-    const sdkPath = path.join(__dirname, "..", "api", "backend-sdk-java.md");
-    let sdkContent = "";
+function readDocFile(basename) {
+    return fs.readFileSync(path.join(DOCS_DIR, `${basename}.md`), "utf8");
+}
+
+/**
+ * 介绍文档（introduction.md）
+ * 用于了解 CloudCC 触发器的概念、定位、能力与适用场景。
+ */
+function getIntroductionDoc() {
+    return readDocFile("introduction");
+}
+
+/**
+ * 开发指导文档（devguide.md + backend-sdk-java.md）
+ * 用于触发器开发实践：触发时机、常见模式、性能与递归风险等；末尾拼接后端 SDK 速查。
+ */
+function getDevGuideDoc() {
+    const base = readDocFile("devguide").trimEnd();
+    let sdk = "";
     try {
-        sdkContent = fs.readFileSync(sdkPath, "utf8");
+        sdk = fs.readFileSync(BACKEND_SDK_JAVA, "utf8").trim();
     } catch (e) {
-        sdkContent = `# CloudCC 后端 SDK（Java）使用指南\n\n（未找到文件：${sdkPath}）\n`;
+        sdk = "";
     }
-
-    return [
-        base,
-        "",
-        "---",
-        "",
-        "## 附录：后端 SDK（Java）速查",
-        "",
-        "> 来源：`src/api/backend-sdk-java.md`",
-        "",
-        sdkContent.trim(),
-        "",
-    ].join("\n");
+    if (!sdk) {
+        return base;
+    }
+    return [base, "", "---", "", "## 附录：后端 SDK（Java）速查", "", sdk, ""].join("\n");
 }
 
-function doc() {
-    const content = generateFullMarkdownDoc();
-    console.log(content);
-    return content;
+/**
+ * cc doc triggers <introduction|devguide>
+ * @param {string[]} argvs [doc, type, introduction|devguide, ...]
+ */
+function doc(argvs) {
+    const subType = argvs[2];
+    const key = String(subType || "").trim().toLowerCase();
+    if (!key) {
+        throw new Error("cc doc triggers 需要子命令：introduction 或 devguide");
+    }
+    if (key === "introduction") {
+        const content = getIntroductionDoc();
+        console.log(content);
+        return content;
+    }
+    if (key === "devguide") {
+        const content = getDevGuideDoc();
+        console.log(content);
+        return content;
+    }
+    throw new Error(`doc 不支持的子命令: ${subType}，请使用 introduction 或 devguide`);
 }
 
-// 兼容旧调用方：统一返回全量文档
-doc.getEditGuide = doc;
-
 module.exports = doc;