@meet-im/lxcli 0.1.2 → 0.1.4

package/dist/commands/generate-skills.js

@@ -149,6 +149,28 @@ function renderParamsTable(params) {
     lines.push('');
     return lines.join('\n');
 }
+function renderExtraSections(metadata) {
+    const sections = metadata?.sections || [];
+    if (sections.length === 0)
+        return '';
+    const lines = [];
+    for (const section of sections) {
+        lines.push(`## ${section.title}`, '');
+        if (section.kind === 'bullets') {
+            for (const item of section.items) {
+                lines.push(`- ${item}`);
+            }
+            lines.push('');
+            continue;
+        }
+        lines.push(`| ${section.headers.join(' | ')} |`, `| ${section.headers.map(() => '---').join(' | ')} |`);
+        for (const row of section.rows) {
+            lines.push(`| ${row.join(' | ')} |`);
+        }
+        lines.push('');
+    }
+    return lines.join('\n');
+}
 async function readPackageVersion() {
     const packageJson = JSON.parse(await fs.readFile(PACKAGE_JSON_PATH, 'utf-8'));
     return packageJson.version || '1.0.0';
@@ -192,7 +214,7 @@ function renderSkillMd(method, version) {
         }
         return `--${param.name} <${param.type === 'integer' ? 'ID' : 'VALUE'}>`;
     });
-    const shortcutUsage = shortcuts.length > 0 ? `lxcli kb ${method} ${shortcuts.join(' ')}` : '';
+    const shortcutUsage = metadata?.shortcutUsageExample || (shortcuts.length > 0 ? `lxcli kb ${method} ${shortcuts.join(' ')}` : '');
     const paramsUsage = hasParams ? `lxcli kb ${method} --params '${JSON.stringify(metadata?.paramsExample || buildParamsExample(params))}'` : '';
     // Usage 部分
     const usageLines = ['## Usage', '', '```bash'];
@@ -240,6 +262,10 @@ metadata:
         lines.push(renderParamsTable(params));
     }
     lines.push('## Examples', '', '```bash', shortcutUsage || paramsUsage || `lxcli kb ${method}`, '```', '');
+    const extraSections = renderExtraSections(metadata);
+    if (extraSections) {
+        lines.push(extraSections);
+    }
     if (metadata?.notes?.length) {
         lines.push('## Notes', '', ...metadata.notes.map((note) => `- ${note}`), '');
     }

package/dist/commands/services/kb/index.js

@@ -4,6 +4,7 @@ import { kbConfig } from './config.js';
 import { METHODS, METHOD_DESCRIPTIONS } from './descriptions.js';
 import { createKbAction } from './handler.js';
 import { PARAM_DEFS } from './params.js';
+import { METHOD_SKILL_METADATA } from './skill-metadata.js';
 function getShortcutParamDescription(method, paramName) {
     const param = PARAM_DEFS[method]?.find((item) => item.name === paramName);
     if (!param) {
@@ -25,10 +26,32 @@ function renderParamsHelp(method) {
     }
     return lines.join('\n');
 }
+function renderMethodExtraHelp(method) {
+    const sections = METHOD_SKILL_METADATA[method]?.sections || [];
+    if (sections.length === 0) {
+        return '';
+    }
+    const lines = [];
+    for (const section of sections) {
+        lines.push(`${section.title}:`);
+        if (section.kind === 'bullets') {
+            for (const item of section.items) {
+                lines.push(`  - ${item.replace(/`/g, '')}`);
+            }
+            continue;
+        }
+        for (const row of section.rows) {
+            const [label, description] = row;
+            lines.push(`  - ${label.replace(/`/g, '')}: ${description}`);
+        }
+    }
+    return lines.join('\n');
+}
 function addParamsOption(command, method) {
     const paramsHelp = renderParamsHelp(method);
+    const extraHelp = renderMethodExtraHelp(method);
     const description = paramsHelp
-        ? `JSON/JSON5 params; CLI fills jsonrpc/method/id\n${paramsHelp}`
+        ? `JSON/JSON5 params; CLI fills jsonrpc/method/id\n${paramsHelp}${extraHelp ? `\n${extraHelp}` : ''}`
         : 'JSON/JSON5 params; CLI fills jsonrpc/method/id';
     return command.option('--params <json>', description);
 }

package/dist/commands/services/kb/params.js

@@ -21,7 +21,7 @@ export const PARAM_DEFS = {
     ],
     searchTasks: [
         { name: 'project_id', type: 'integer', required: true, description: '项目 ID。接口按项目检查查看权限。' },
-        { name: 'query', type: 'string', required: true, description: 'Kanboard 搜索表达式，例如 iteration:456 status:1' },
+        { name: 'query', type: 'string', required: true, description: 'Kanboard 搜索表达式；多个条件以空格分隔，不同字段为 AND，同一字段重复为 OR。' },
     ],
     searchSubtasks: [
         { name: 'project_id', type: 'integer', required: false, description: '项目 ID。传入后仅返回该项目下的子任务，并按项目检查查看权限；不传时仅在当前用户有权限查看的启用项目中查找。' },
@@ -49,7 +49,7 @@ export const PARAM_DEFS = {
         { name: 'owner_id', type: 'integer', required: false, description: '处理人 Kanboard 用户 ID。处理人必须可分配到该项目。' },
         { name: 'creator_id', type: 'integer', required: false, description: '创建人 Kanboard 用户 ID。登录态存在时创建人会使用当前用户。' },
         { name: 'category_id', type: 'integer', required: false, description: '分类 ID。服务端会根据分类和 bug 类型选择泳道。' },
-        { name: 'iteration_id', type: 'integer', required: false, description: '迭代 ID；未传或为 0 时由服务端选择需求池或首个迭代。' },
+        { name: 'iteration_id', type: 'integer', required: false, description: '迭代 ID；未传或为 0 时由服务端选择需求池或首个迭代。可用 getAllActiveIterations 查询启用迭代列表，根据 date_start/date_end（Unix 时间戳）确定目标迭代。' },
         { name: 'date_due', type: 'string', required: false, description: '截止日期，建议使用 YYYY-MM-DD' },
         { name: 'date_started', type: 'string', required: false, description: '开始日期，建议使用 YYYY-MM-DD' },
         { name: 'priority', type: 'integer', required: false, description: '优先级：0 高、1 中、2 低，其他值为无关紧要' },
@@ -74,7 +74,7 @@ export const PARAM_DEFS = {
         { name: 'description', type: 'string', required: false, description: '描述内容（Markdown）' },
         { name: 'owner_id', type: 'integer', required: false, description: '处理人用户 ID。目标用户必须可分配到该项目。' },
         { name: 'category_id', type: 'integer', required: false, description: '分类 ID' },
-        { name: 'iteration_id', type: 'integer', required: false, description: '迭代 ID。传入后修改需求/bug 所属迭代；未传时保持原迭代不变。' },
+        { name: 'iteration_id', type: 'integer', required: false, description: '迭代 ID。传入后修改需求/bug 所属迭代；未传时保持原迭代不变。可用 getAllActiveIterations 查询启用迭代列表，根据 date_start/date_end（Unix 时间戳）确定目标迭代。' },
         { name: 'date_due', type: 'string', required: false, description: '截止日期，建议使用 YYYY-MM-DD' },
         { name: 'date_started', type: 'string', required: false, description: '开始日期，建议使用 YYYY-MM-DD' },
         { name: 'priority', type: 'integer', required: false, description: '优先级：0 高、1 中、2 低，其他值为无关紧要' },

package/dist/commands/services/kb/skill-metadata.d.ts

@@ -4,6 +4,18 @@ export interface MethodSkillMetadata {
     notes?: string[];
     skillParams?: ParamDef[];
     paramsExample?: Record<string, unknown>;
+    shortcutUsageExample?: string;
+    sections?: MethodSkillSection[];
 }
+export type MethodSkillSection = {
+    title: string;
+    kind: 'bullets';
+    items: string[];
+} | {
+    title: string;
+    kind: 'table';
+    headers: string[];
+    rows: string[][];
+};
 export declare const METHOD_SHORTCUT_PARAMS: Partial<Record<Method, string[]>>;
 export declare const METHOD_SKILL_METADATA: Partial<Record<Method, MethodSkillMetadata>>;

package/dist/commands/services/kb/skill-metadata.js

@@ -26,6 +26,78 @@ export const METHOD_SKILL_METADATA = {
             '仅在确实需要时才传 `with_comments`、`with_files`、`with_links`、`with_subtasks`，避免把额外第三方内容带入代理上下文。',
         ],
     },
+    getAllActiveIterations: {
+        paramsExample: {
+            project_id: 4,
+        },
+        sections: [
+            {
+                title: '返回值说明',
+                kind: 'bullets',
+                items: [
+                    '返回数组中每个对象包含 `id`、`name`、`date_start`、`date_end`、`position`、`nb_open_tasks`、`nb_closed_tasks` 等字段。',
+                    '`date_start` 和 `date_end` 是 **Unix 时间戳**（秒级整数），`0` 表示未设置。显示或比较前需转换为可读日期。',
+                ],
+            },
+            {
+                title: '确定下个迭代',
+                kind: 'bullets',
+                items: [
+                    '将当前时间转为 Unix 时间戳（秒），筛选 `date_start > 当前时间戳` 的迭代。',
+                    '在筛选结果中取 `date_start` 最小的那个，即为"下个迭代"。',
+                    '若所有迭代的 `date_start` 都 ≤ 当前时间，说明没有未来的迭代；可取 `date_end` 最大且仍 ≥ 当前时间的迭代作为"当前迭代"。',
+                    '获得迭代后，将其 `id` 传入 `createTask --iteration_id` 或 `updateTask --iteration_id`。',
+                ],
+            },
+        ],
+    },
+    createTask: {
+        notes: [
+            '如需指定迭代，先调用 `getAllActiveIterations` 查询项目的启用迭代列表，根据 `date_start`/`date_end`（Unix 时间戳）确定目标迭代 ID，再传入 `iteration_id`。',
+        ],
+    },
+    searchTasks: {
+        paramsExample: {
+            project_id: 4,
+            query: 'iteration:3 status:0 completedRange:"2026-07-01 00:00:00..2026-07-07 23:59:59"',
+        },
+        shortcutUsageExample: "lxcli kb searchTasks --project_id 4 --query 'iteration:3 status:0'",
+        sections: [
+            {
+                title: 'Query Syntax',
+                kind: 'bullets',
+                items: [
+                    '`字段:值` 是基础条件，多个条件用空格分隔。',
+                    '不同字段之间是 AND。',
+                    '同一字段传多个值时为 OR，例如 `assignee:alice assignee:bob`。',
+                    '值中包含空格、冒号或时间范围时，用双引号包裹。',
+                    '日期字段支持比较符，例如 `completed:>=2026-07-01`。',
+                    '范围字段支持 `start..end`，可省略一端。',
+                ],
+            },
+            {
+                title: 'Common Query Conditions',
+                kind: 'table',
+                headers: ['表达式', '说明'],
+                rows: [
+                    ['`iteration:456` / `iteration:V1.0.0`', '按迭代 ID 或名称查询'],
+                    ['`status:1` / `status:0`', '按打开 / 关闭状态查询'],
+                    ['`completedRange:"2026-07-01 00:00:00..2026-07-07 23:59:59"`', '按完成时间范围查询'],
+                    ['`completed:>=2026-07-01`', '按完成时间做比较查询'],
+                    ['`assignee:alice` / `assignee:me`', '按处理人查询'],
+                    ['`category:Feature` / `column:Ready`', '按分类或状态列查询'],
+                    ['`title:"登录异常"` / `description:"回调失败"`', '按标题或描述查询'],
+                ],
+            },
+            {
+                title: 'Warnings',
+                kind: 'bullets',
+                items: [
+                    '`completedRange` 结束值只写日期时按当天 `00:00:00` 解析；需要覆盖整天时请写到 `23:59:59`。',
+                ],
+            },
+        ],
+    },
     createProjectFile: {
         skillParams: [
             { name: 'project_id', type: 'integer', required: true, description: '项目 ID' },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meet-im/lxcli",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "连续科技命令行工具",
   "type": "module",
   "main": "dist/index.js",