@xinhehuimeng/cli 0.2.5 → 0.2.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xinhehuimeng/cli",
-  "version": "0.2.5",
+  "version": "0.2.6",
   "description": "心河 OA 客户端 CLI（Node 版）：多维表格 / 应用 / 权限的唯一命令行入口",
   "keywords": [
     "xinhe-oa",

package/src/commands/index.js

@@ -4,9 +4,9 @@
 // 自己负责把结果写出去（`runtime.finish(...)` / `runtime.finishWithHuman(...)`），
 // 失败就 `throw CliError`。**退出码由 `main.js` 统一收口**（契约 §3.2）。
 //
-// 为什么一张显式的表，而不是按域名动态 import：命令面是**冻结契约**（153 条），
+// 为什么一张显式的表，而不是按域名动态 import：命令面是**冻结契约**（160 条），
 // 表里缺一条就是"这条命令在 Node 版上不存在"——显式的表能让这件事一眼可见，
-// 也方便 `test/surface.test.js` 断言"153 条命令每条都有处理函数"。
+// 也方便 `test/surface.test.js` 断言"160 条命令每条都有处理函数"。
 
 import { handleLogin, handleLogout, handleMe } from './session.js';
 import { handleTenant } from './tenant.js';
@@ -14,6 +14,7 @@ import { handleMember } from './member.js';
 import { handleInvestor } from './investor.js';
 import { handleOrg } from './org.js';
 import { handleBitable } from './bitable.js';
+import { handleProject } from './project.js';
 import { handleApplication } from './application.js';
 import { handleDashboard } from './dashboard.js';
 import { handleWorkflow } from './workflow.js';
@@ -42,6 +43,7 @@ export const HANDLERS = new Map([
   ['bitable record', handleBitable],
   ['bitable view', handleBitable],
   ['bitable form', handleBitable],
+  ['project', handleProject],
   ['application', handleApplication],
   ['dashboard', handleDashboard],
   ['workflow', handleWorkflow],

package/src/commands/member.js

@@ -1,4 +1,4 @@
-// 成员域：`member --list|--search|--create|--role|--revoke-role|--remove|--reset-password`，
+// 成员域：`member --list|--search|--create|--role|--revoke-role|--remove|--reset-password|--link`，
 // 含 ORG-001 的部门归属三件套（`--set-dept` / `--unset-dept` / `--set-manager|--clear-manager`）、
 // ORG-002 的授权三动作（`--grant|--revoke-grant|--grants`，issue #82）、
 // ORG-004 的离职 / 移交四动作（issue #81）与 MEMBER-001 的 `--search`（issue #99）。
@@ -83,6 +83,8 @@ export async function handleMember({ args, runtime }) {
       return removeMember(runtime, action.user, args);
     case 'reset-password':
       return resetPassword(runtime, action.user);
+    case 'link':
+      return portalLink(runtime, args, action.user);
     case 'set-dept':
       return setDept(runtime, args, action.user, action.deptId, action.primary);
     case 'unset-dept':
@@ -132,6 +134,7 @@ function memberAction(args) {
       ['--revoke-role', given('--revoke-role')],
       ['--remove', given('--remove')],
       ['--reset-password', given('--reset-password')],
+      ['--link', given('--link')],
       ['--set-dept', given('--set-dept')],
       ['--unset-dept', given('--unset-dept')],
       ['--set-manager', given('--set-manager')],
@@ -408,11 +411,38 @@ function memberAction(args) {
           '例：xinhe-oa-cli member --reset-password usr_123 --yes --json',
         ),
       };
+    case '--link': {
+      const user = normalizeId(val('--link'));
+      if (user === null) {
+        throw CliError.usage('`member --link` 需要 --link <USER_ID>').withHint(
+          '先看 user_id：xinhe-oa-cli member --list --json',
+        );
+      }
+      return { kind: 'link', user };
+    }
     default:
       return { kind: 'remove', user: String(val('--remove') ?? '') };
   }
 }
 
+async function portalLink(runtime, args, userId) {
+  const tenant = await resolveTenant(runtime, flagValue(args, '--tenant'));
+  if (tenant === null) {
+    throw CliError.usage('签发门户链接必须指明企业').withHint(
+      '加 --tenant <TENANT_ID>；用 `xinhe-oa-cli tenant --list` 查看',
+    );
+  }
+  const spec = requestSpec({
+    body: { tenant_id: tenant, user_id: userId },
+  });
+  if (runtime.dryRun) return runtime.dryRunReport('POST', '/portal/auth/links', spec);
+  const response = await runtime.sendAuthed('POST', '/portal/auth/links', spec);
+  runtime.finishFrom(response, {
+    ...dataOf(response),
+    next_step: '把 url 发给对应成员；链接 10 分钟内有效且只能使用一次',
+  });
+}
+
 /** 0 个或多于 1 个动作都是用法错误（与 Rust `exactly_one` 同文案）。 */
 function exactlyOne(selected, what, hint) {
   const picked = selected.filter(([, active]) => active).map(([name]) => name);

package/src/commands/project.js

@@ -0,0 +1,685 @@
+// 项目应用适配域：`project --list|--show|--create|--update|--context`
+// 与 `project milestone|task|progress`。
+//
+// 项目不是平台核心的新固定业务表：这里只把项目语义翻译到已安装的
+// `project_delivery` Manifest，最终仍走 `/tables/{id}/records` 的同一条
+// 幂等、乐观锁、权限和审计路径。Web 门户读取的也是这些记录。
+
+import { CliError, Kind, exactlyOne } from '../core/error.js';
+import { flagList, flagOn, flagValue, intFlag } from '../core/args.js';
+import { dataOf, idempotencyKey, requestSpec } from '../core/runtime.js';
+import { parseSetPairs, valuesObject } from '../core/values.js';
+import { resolveTenant } from './tenant.js';
+
+const APP_DEFAULT = 'project_delivery';
+const MAX_PAGE = 1000;
+const MAX_PAGES = 100;
+
+const PROJECT_STATUS = ['planning', 'in_progress', 'acceptance', 'done', 'paused'];
+const HEALTH = ['on_track', 'attention', 'at_risk', 'delayed'];
+const MILESTONE_STATUS = ['upcoming', 'in_progress', 'completed', 'overdue'];
+const TASK_STATUS = ['todo', 'in_progress', 'review', 'done', 'blocked'];
+const PRIORITIES = ['high', 'medium', 'low'];
+
+export async function handleProject({ args, runtime, command }) {
+  const resource = String(command?.name ?? 'project').split(' ')[1] ?? null;
+  if (resource === 'milestone') return milestone(runtime, args);
+  if (resource === 'task') return task(runtime, args);
+  if (resource === 'progress') return progress(runtime, args);
+
+  const action = exactlyOne(
+    [
+      ['--list', flagOn(args, '--list')],
+      ['--show', flagValue(args, '--show') !== null],
+      ['--create', flagOn(args, '--create')],
+      ['--update', flagValue(args, '--update') !== null],
+      ['--context', flagOn(args, '--context')],
+    ],
+    'project',
+    '例：xinhe-oa-cli project --list --tenant <TENANT_ID> --json',
+  );
+  if (action === '--list') return list(runtime, args);
+  if (action === '--show') return show(runtime, args, required(args, '--show'));
+  if (action === '--create') return create(runtime, args);
+  if (action === '--update') return update(runtime, args, required(args, '--update'));
+  return context(runtime, args);
+}
+
+async function list(runtime, args) {
+  const payload = {
+    all: flagOn(args, '--all'),
+    health: flagValue(args, '--health'),
+    limit: intFlag(args, '--limit', { fallback: 200 }),
+    offset: intFlag(args, '--offset', { fallback: 0 }),
+    owner: flagValue(args, '--owner'),
+    status: flagValue(args, '--status'),
+  };
+  if (runtime.dryRun) return dryRun(runtime, 'project.list', args, payload);
+
+  const binding = await resolveBinding(runtime, args);
+  const needAll =
+    payload.all || payload.status !== null || payload.health !== null || payload.owner !== null;
+  const { records, response } = await fetchRecords(
+    runtime,
+    table(binding, 'project'),
+    payload.limit,
+    payload.offset,
+    needAll,
+  );
+  const projects = records.filter(
+    (record) =>
+      (payload.status === null || recordValue(record, 'project_status') === payload.status) &&
+      (payload.health === null || recordValue(record, 'health_status') === payload.health) &&
+      (payload.owner === null || recordValue(record, 'project_owner') === payload.owner),
+  );
+  runtime.finishFrom(response, {
+    binding,
+    count: projects.length,
+    projects,
+    next_step:
+      '看详情：xinhe-oa-cli project --show <PROJECT_ID|CODE> --tenant <TENANT_ID> --json',
+  });
+}
+
+async function show(runtime, args, projectRef) {
+  if (runtime.dryRun) return dryRun(runtime, 'project.show', args, { project: projectRef });
+  const binding = await resolveBinding(runtime, args);
+  const projectId = await resolveProjectId(runtime, binding, projectRef);
+  const response = await runtime.sendAuthed('GET', `/records/${projectId}`, requestSpec());
+  runtime.finishFrom(response, { binding, project: dataOf(response) });
+}
+
+async function context(runtime, args) {
+  if (runtime.dryRun) return dryRun(runtime, 'project.context', args, {});
+  const binding = await resolveBinding(runtime, args);
+  runtime.finish({
+    binding,
+    next_step: 'xinhe-oa-cli project --list --tenant <TENANT_ID> --json',
+  });
+}
+
+async function create(runtime, args) {
+  const name = required(args, '--name');
+  const owner = required(args, '--owner');
+  const due = required(args, '--due');
+  const code = flagValue(args, '--code') ?? `PRJ-${timestamp()}`;
+  const status = flagValue(args, '--status') ?? 'planning';
+  const health = flagValue(args, '--health') ?? 'on_track';
+  choice(status, PROJECT_STATUS, '--status');
+  choice(health, HEALTH, '--health');
+
+  const pairs = [
+    textPair('project_name', name),
+    textPair('project_code', code),
+    textPair('project_status', status),
+    textPair('health_status', health),
+    textPair('project_owner', owner),
+    textPair('target_date', due),
+    numberPair('progress_percent', percentValue(args, 0)),
+    textPair('last_update_at', today()),
+  ];
+  addText(pairs, args, '--start', 'start_date');
+  addText(pairs, args, '--description', 'project_description');
+  addText(pairs, args, '--current-milestone', 'current_milestone');
+  pairs.push(...parseSetPairs(flagList(args, '--set'), '--set'));
+
+  if (runtime.dryRun) {
+    return dryRun(runtime, 'project.create', args, {
+      reason: flagValue(args, '--reason'),
+      table: 'project',
+      values: valuesObject(pairs),
+    });
+  }
+  const binding = await resolveBinding(runtime, args);
+  await ensureCodeAvailable(runtime, binding, code, null);
+  return createRecord(runtime, table(binding, 'project'), pairs, args, '项目立项');
+}
+
+async function update(runtime, args, projectRef) {
+  const pairs = [];
+  addText(pairs, args, '--name', 'project_name');
+  addText(pairs, args, '--code', 'project_code');
+  addText(pairs, args, '--owner', 'project_owner');
+  addText(pairs, args, '--start', 'start_date');
+  addText(pairs, args, '--due', 'target_date');
+
+  const status = flagValue(args, '--status');
+  if (status !== null) {
+    choice(status, PROJECT_STATUS, '--status');
+    pairs.push(textPair('project_status', status));
+  }
+  const health = flagValue(args, '--health');
+  if (health !== null) {
+    choice(health, HEALTH, '--health');
+    pairs.push(textPair('health_status', health));
+  }
+  const progress = flagValue(args, '--progress');
+  if (progress !== null) pairs.push(numberPair('progress_percent', percent(progress, '--progress')));
+  addText(pairs, args, '--current-milestone', 'current_milestone');
+  addText(pairs, args, '--description', 'project_description');
+  pairs.push(...parseSetPairs(flagList(args, '--set'), '--set'));
+  if (pairs.length === 0) throw CliError.usage('`project --update` 至少要给一个更新字段或 --set');
+  pairs.push(textPair('last_update_at', today()));
+
+  if (runtime.dryRun) {
+    return dryRun(runtime, 'project.update', args, {
+      project: projectRef,
+      reason: flagValue(args, '--reason'),
+      table: 'project',
+      values: valuesObject(pairs),
+      version: versionFlag(args),
+    });
+  }
+  const binding = await resolveBinding(runtime, args);
+  const projectId = await resolveProjectId(runtime, binding, projectRef);
+  const code = flagValue(args, '--code');
+  if (code !== null) await ensureCodeAvailable(runtime, binding, code, projectId);
+  return updateRecord(runtime, projectId, pairs, args, '项目进度更新');
+}
+
+async function milestone(runtime, args) {
+  const action = exactlyOne(
+    [
+      ['--list', flagOn(args, '--list')],
+      ['--add', flagOn(args, '--add')],
+      ['--update', flagValue(args, '--update') !== null],
+    ],
+    'project milestone',
+    '例：xinhe-oa-cli project milestone --add --project <PROJECT_ID|CODE> --name 灰度发布 --due 2026-11-12 --weight 25 --json',
+  );
+  if (action === '--list') {
+    const projectRef = required(args, '--project');
+    if (runtime.dryRun) {
+      return dryRun(runtime, 'project.milestone.list', args, { project: projectRef });
+    }
+    const binding = await resolveBinding(runtime, args);
+    const projectId = await resolveProjectId(runtime, binding, projectRef);
+    const { records, response } = await fetchRecords(
+      runtime,
+      table(binding, 'milestone'),
+      500,
+      0,
+      true,
+    );
+    const milestones = records.filter((item) => mentions(item, 'project_ref', projectId));
+    return runtime.finishFrom(response, { count: milestones.length, milestones, project: projectId });
+  }
+
+  if (action === '--add') {
+    const projectRef = required(args, '--project');
+    const name = required(args, '--name');
+    const due = required(args, '--due');
+    const weightRaw = required(args, '--weight');
+    const weight = number(weightRaw, '--weight');
+    const status = flagValue(args, '--status') ?? 'upcoming';
+    choice(status, MILESTONE_STATUS, '--status');
+    const pairs = [
+      jsonPair('project_ref', [projectRef]),
+      textPair('milestone_name', name),
+      textPair('milestone_status', status),
+      textPair('milestone_due_date', due),
+      numberPair('milestone_progress', percentValue(args, 0)),
+      numberPair('milestone_weight', weight),
+    ];
+    addText(pairs, args, '--owner', 'milestone_owner');
+    addText(pairs, args, '--description', 'milestone_description');
+    pairs.push(...parseSetPairs(flagList(args, '--set'), '--set'));
+    if (runtime.dryRun) {
+      return dryRun(runtime, 'project.milestone.add', args, {
+        project: projectRef,
+        table: 'milestone',
+        values: valuesObject(pairs),
+      });
+    }
+    const binding = await resolveBinding(runtime, args);
+    const projectId = await resolveProjectId(runtime, binding, projectRef);
+    pairs[0] = jsonPair('project_ref', [projectId]);
+    return createRecord(runtime, table(binding, 'milestone'), pairs, args, '新增项目里程碑');
+  }
+
+  const milestoneId = required(args, '--update');
+  const pairs = [];
+  addText(pairs, args, '--name', 'milestone_name');
+  addText(pairs, args, '--owner', 'milestone_owner');
+  addText(pairs, args, '--due', 'milestone_due_date');
+  addText(pairs, args, '--description', 'milestone_description');
+  const status = flagValue(args, '--status');
+  if (status !== null) {
+    choice(status, MILESTONE_STATUS, '--status');
+    pairs.push(textPair('milestone_status', status));
+  }
+  const progress = flagValue(args, '--progress');
+  if (progress !== null) pairs.push(numberPair('milestone_progress', percent(progress, '--progress')));
+  const weight = flagValue(args, '--weight');
+  if (weight !== null) pairs.push(numberPair('milestone_weight', number(weight, '--weight')));
+  pairs.push(...parseSetPairs(flagList(args, '--set'), '--set'));
+  if (pairs.length === 0) {
+    throw CliError.usage('`project milestone --update` 至少要给一个更新字段或 --set');
+  }
+  if (runtime.dryRun) {
+    return dryRun(runtime, 'project.milestone.update', args, {
+      milestone_id: milestoneId,
+      table: 'milestone',
+      values: valuesObject(pairs),
+      version: versionFlag(args),
+    });
+  }
+  return updateRecord(runtime, milestoneId, pairs, args, '更新项目里程碑');
+}
+
+async function task(runtime, args) {
+  const action = exactlyOne(
+    [
+      ['--list', flagOn(args, '--list')],
+      ['--create', flagOn(args, '--create')],
+      ['--update', flagValue(args, '--update') !== null],
+    ],
+    'project task',
+    '例：xinhe-oa-cli project task --create --project <PROJECT_ID|CODE> --title 完成灰度名单校验 --json',
+  );
+  if (action === '--list') {
+    const projectRef = required(args, '--project');
+    if (runtime.dryRun) return dryRun(runtime, 'project.task.list', args, { project: projectRef });
+    const binding = await resolveBinding(runtime, args);
+    const projectId = await resolveProjectId(runtime, binding, projectRef);
+    const { records, response } = await fetchRecords(
+      runtime,
+      table(binding, 'work_item'),
+      500,
+      0,
+      true,
+    );
+    const tasks = records.filter((item) => mentions(item, 'project_ref', projectId));
+    return runtime.finishFrom(response, { count: tasks.length, project: projectId, tasks });
+  }
+
+  if (action === '--create') {
+    const projectRef = required(args, '--project');
+    const title = required(args, '--title');
+    const status = flagValue(args, '--status') ?? 'todo';
+    const priority = flagValue(args, '--priority') ?? 'medium';
+    choice(status, TASK_STATUS, '--status');
+    choice(priority, PRIORITIES, '--priority');
+    const pairs = [
+      jsonPair('project_ref', [projectRef]),
+      textPair('work_item_title', title),
+      textPair('work_item_status', status),
+      textPair('priority', priority),
+    ];
+    addText(pairs, args, '--owner', 'work_item_owner');
+    addText(pairs, args, '--due', 'work_item_due_date');
+    addText(pairs, args, '--milestone', 'milestone_ref', true);
+    pairs.push(...parseSetPairs(flagList(args, '--set'), '--set'));
+    if (runtime.dryRun) {
+      return dryRun(runtime, 'project.task.create', args, {
+        project: projectRef,
+        table: 'work_item',
+        values: valuesObject(pairs),
+      });
+    }
+    const binding = await resolveBinding(runtime, args);
+    const projectId = await resolveProjectId(runtime, binding, projectRef);
+    pairs[0] = jsonPair('project_ref', [projectId]);
+    return createRecord(runtime, table(binding, 'work_item'), pairs, args, '新增项目任务');
+  }
+
+  const taskId = required(args, '--update');
+  const pairs = [];
+  addText(pairs, args, '--title', 'work_item_title');
+  addText(pairs, args, '--owner', 'work_item_owner');
+  addText(pairs, args, '--due', 'work_item_due_date');
+  addText(pairs, args, '--milestone', 'milestone_ref', true);
+  const status = flagValue(args, '--status');
+  if (status !== null) {
+    choice(status, TASK_STATUS, '--status');
+    pairs.push(textPair('work_item_status', status));
+  }
+  const priority = flagValue(args, '--priority');
+  if (priority !== null) {
+    choice(priority, PRIORITIES, '--priority');
+    pairs.push(textPair('priority', priority));
+  }
+  pairs.push(...parseSetPairs(flagList(args, '--set'), '--set'));
+  if (pairs.length === 0) {
+    throw CliError.usage('`project task --update` 至少要给一个更新字段或 --set');
+  }
+  if (runtime.dryRun) {
+    return dryRun(runtime, 'project.task.update', args, {
+      table: 'work_item',
+      task_id: taskId,
+      values: valuesObject(pairs),
+      version: versionFlag(args),
+    });
+  }
+  return updateRecord(runtime, taskId, pairs, args, '更新项目任务');
+}
+
+async function progress(runtime, args) {
+  const action = exactlyOne(
+    [['--list', flagOn(args, '--list')], ['--submit', flagOn(args, '--submit')]],
+    'project progress',
+    '例：xinhe-oa-cli project progress --submit --project <PROJECT_ID|CODE> --progress 72 --summary "本周完成联调" --json',
+  );
+  const projectRef = required(args, '--project');
+  if (action === '--list') {
+    if (runtime.dryRun) {
+      return dryRun(runtime, 'project.progress.list', args, { project: projectRef });
+    }
+    const binding = await resolveBinding(runtime, args);
+    const projectId = await resolveProjectId(runtime, binding, projectRef);
+    const { records, response } = await fetchRecords(
+      runtime,
+      table(binding, 'progress_update'),
+      500,
+      0,
+      true,
+    );
+    const updates = records.filter((item) => mentions(item, 'project_ref', projectId));
+    return runtime.finishFrom(response, { count: updates.length, project: projectId, updates });
+  }
+
+  const progressValue = percent(required(args, '--progress'), '--progress');
+  const summary = required(args, '--summary');
+  const reportDate = flagValue(args, '--date') ?? today();
+  const author = currentUserId(runtime);
+  if (author === null) {
+    throw CliError.usage('当前 CLI 会话缺少用户摘要，无法记录进度更新人').withHint(
+      '重新登录或先执行 `xinhe-oa-cli me --json`',
+    );
+  }
+  const pairs = [
+    jsonPair('project_ref', [projectRef]),
+    textPair('report_date', reportDate),
+    numberPair('reported_progress', progressValue),
+    textPair('update_summary', summary),
+    textPair('update_author', author),
+  ];
+  addText(pairs, args, '--risk', 'update_risk');
+  addText(pairs, args, '--next-step', 'update_next_step');
+  pairs.push(...parseSetPairs(flagList(args, '--set'), '--set'));
+  if (runtime.dryRun) {
+    return dryRun(runtime, 'project.progress.submit', args, {
+      project: projectRef,
+      table: 'progress_update',
+      values: valuesObject(pairs),
+    });
+  }
+  const binding = await resolveBinding(runtime, args);
+  const projectId = await resolveProjectId(runtime, binding, projectRef);
+  pairs[0] = jsonPair('project_ref', [projectId]);
+  return createRecord(runtime, table(binding, 'progress_update'), pairs, args, '提交项目周度进度');
+}
+
+async function resolveBinding(runtime, args) {
+  const appKey = (flagValue(args, '--app') ?? APP_DEFAULT).trim() || APP_DEFAULT;
+  const tenantId = await resolveTenant(runtime, flagValue(args, '--tenant'));
+  if (tenantId === null) {
+    throw CliError.usage('项目命令需要企业上下文').withHint(
+      '加 --tenant <TENANT_ID>；用 `xinhe-oa-cli tenant --list` 查看',
+    );
+  }
+  const appsResponse = await runtime.sendAuthed(
+    'GET',
+    '/apps',
+    requestSpec({ query: [['tenant', tenantId], ['limit', '200']] }),
+  );
+  const apps = Array.isArray(dataOf(appsResponse)?.apps) ? dataOf(appsResponse).apps : [];
+  const app = apps
+    .filter((item) => item?.key === appKey)
+    .sort((left, right) => versionKey(right?.version) - versionKey(left?.version))[0];
+  if (app === undefined) {
+    throw CliError.usage(`企业 ${tenantId} 尚未安装项目应用 ${appKey}`).withHint(
+      '安装 Manifest：xinhe-oa-cli application --install --file apps/web/project-app.manifest.json --tenant <TENANT_ID> --plan --yes',
+    );
+  }
+  const appId = app.id;
+  const appResponse = await runtime.sendAuthed('GET', `/apps/${appId}`, requestSpec());
+  const baseKey = dataOf(appResponse)?.manifest?.bases?.[0]?.key;
+  if (typeof baseKey !== 'string') {
+    throw CliError.usage('项目 Manifest 没有声明 bases[0].key');
+  }
+  const basesResponse = await runtime.sendAuthed(
+    'GET',
+    '/bases',
+    requestSpec({ query: [['tenant', tenantId], ['limit', '200']] }),
+  );
+  const bases = Array.isArray(dataOf(basesResponse)?.bases) ? dataOf(basesResponse).bases : [];
+  const base = bases.find((item) => item?.key === baseKey);
+  if (base === undefined || typeof base.id !== 'string') {
+    throw CliError.usage(`找不到项目应用库 ${baseKey}`).withHint(
+      '确认应用已成功应用，并且当前身份有该库的读取权限',
+    );
+  }
+  const tablesResponse = await runtime.sendAuthed(
+    'GET',
+    `/bases/${base.id}/tables`,
+    requestSpec(),
+  );
+  const tableRows = Array.isArray(dataOf(tablesResponse)?.tables)
+    ? dataOf(tablesResponse).tables
+    : [];
+  const tables = {};
+  for (const key of ['project', 'milestone', 'work_item', 'progress_update']) {
+    const row = tableRows.find((item) => item?.key === key);
+    if (typeof row?.id === 'string') tables[key] = row.id;
+  }
+  return {
+    app_id: appId,
+    app_key: appKey,
+    app_version: app.version ?? null,
+    base_id: base.id,
+    tables,
+    tenant_id: tenantId,
+  };
+}
+
+function table(binding, key) {
+  const id = binding.tables[key];
+  if (typeof id !== 'string') {
+    throw CliError.usage(`项目应用缺少 ${key} 表`).withHint(
+      '重新应用项目 Manifest：xinhe-oa-cli application --install --file apps/web/project-app.manifest.json --tenant <TENANT_ID> --yes',
+    );
+  }
+  return id;
+}
+
+async function resolveProjectId(runtime, binding, projectRef) {
+  const wanted = String(projectRef).trim();
+  if (wanted.startsWith('rec_')) return wanted;
+  const { records } = await fetchRecords(runtime, table(binding, 'project'), 500, 0, true);
+  const matches = records.filter((record) => recordValue(record, 'project_code') === wanted);
+  if (matches.length > 1) {
+    throw CliError.usage(`项目编号 ${JSON.stringify(wanted)} 对应多条记录，无法唯一确定`)
+      .withDetails({ project_code: wanted, record_ids: matches.map((item) => item.id) })
+      .withHint('改用项目记录 ID，并为已有数据修正重复编号');
+  }
+  if (typeof matches[0]?.id !== 'string') {
+    throw CliError.usage(`找不到项目 ${JSON.stringify(wanted)}`).withHint(
+      '用项目记录 ID 或精确项目编号；先跑 `project --list --all --json`',
+    );
+  }
+  return matches[0].id;
+}
+
+async function ensureCodeAvailable(runtime, binding, code, excludeId) {
+  const { records } = await fetchRecords(runtime, table(binding, 'project'), 500, 0, true);
+  const conflict = records.find(
+    (record) => recordValue(record, 'project_code') === code && record.id !== excludeId,
+  );
+  if (conflict !== undefined) {
+    throw CliError.usage(`项目编号 ${JSON.stringify(code)} 已存在`)
+      .withDetails({
+        existing_project_name: conflict?.values?.project_name ?? null,
+        existing_record_id: conflict.id,
+        project_code: code,
+      })
+      .withHint('项目编号应稳定且唯一；换一个编号，或更新已有项目');
+  }
+}
+
+async function fetchRecords(runtime, tableId, limit, startOffset, all) {
+  const pageLimit = Math.min(Math.max(limit, 1), MAX_PAGE);
+  let offset = startOffset;
+  const records = [];
+  let lastResponse = null;
+  for (let page = 0; page < MAX_PAGES; page += 1) {
+    const response = await runtime.sendAuthed(
+      'GET',
+      `/tables/${tableId}/records`,
+      requestSpec({
+        query: [
+          ['limit', String(pageLimit)],
+          ['offset', String(offset)],
+          ['order', 'created_at:desc,id:desc'],
+        ],
+      }),
+    );
+    const data = dataOf(response);
+    const rows = Array.isArray(data?.records) ? data.records : [];
+    records.push(...rows);
+    offset += rows.length;
+    lastResponse = response;
+    if (!all || rows.length === 0 || rows.length < pageLimit) break;
+    if (typeof data?.total === 'number' && offset >= data.total) break;
+  }
+  return { records, response: lastResponse };
+}
+
+async function createRecord(runtime, tableId, pairs, args, defaultReason) {
+  const body = {
+    reason: flagValue(args, '--reason') ?? defaultReason,
+    source: 'cli:project',
+    values: valuesObject(pairs),
+  };
+  const spec = requestSpec({
+    body,
+    idempotencyKey: idempotencyKey('project-create', flagValue(args, '--idempotency-key')),
+  });
+  const response = await runtime.sendAuthed('POST', `/tables/${tableId}/records`, spec);
+  runtime.finishFrom(response, { record: dataOf(response) });
+}
+
+async function updateRecord(runtime, recordId, pairs, args, defaultReason) {
+  const version =
+    versionFlag(args) ?? (await currentVersion(runtime, recordId));
+  const spec = requestSpec({
+    body: {
+      reason: flagValue(args, '--reason') ?? defaultReason,
+      values: valuesObject(pairs),
+      version,
+    },
+    idempotencyKey: idempotencyKey('project-update', flagValue(args, '--idempotency-key')),
+  });
+  const response = await runtime.sendAuthed('PATCH', `/records/${recordId}`, spec);
+  runtime.finishFrom(response, { record: dataOf(response) });
+}
+
+async function currentVersion(runtime, recordId) {
+  const response = await runtime.sendAuthed('GET', `/records/${recordId}`, requestSpec());
+  const version = dataOf(response)?.version;
+  if (typeof version !== 'number' || !Number.isInteger(version)) {
+    throw new CliError(Kind.Server, 'cli.bad_response', '读不到记录的 version（乐观锁必须用它）');
+  }
+  return version;
+}
+
+function dryRun(runtime, operation, args, payload) {
+  runtime.finish({
+    app_key: flagValue(args, '--app') ?? APP_DEFAULT,
+    dry_run: true,
+    note: '--dry-run：没有联网解析 ID，也没有写入任何数据',
+    operation,
+    payload,
+    tenant: flagValue(args, '--tenant') ?? '<由唯一可见企业解析>',
+    will_resolve: ['app_id', 'base_id', 'project/milestone/work_item/progress_update table_id'],
+  });
+}
+
+function required(args, flag) {
+  const raw = flagValue(args, flag);
+  if (raw === null || String(raw).trim().length === 0) {
+    throw CliError.usage(`缺少 ${flag}`).withHint('先加 --dry-run --json 查看完整参数，再正式执行');
+  }
+  return String(raw).trim();
+}
+
+function choice(value, choices, flag) {
+  if (!choices.includes(value)) {
+    throw CliError.usage(`${flag} 只能是 ${choices.join(' | ')}，收到 ${JSON.stringify(value)}`);
+  }
+}
+
+function number(raw, flag) {
+  const value = Number(raw);
+  if (!Number.isFinite(value)) throw CliError.usage(`${flag} 需要一个数字，收到 ${JSON.stringify(raw)}`);
+  return value;
+}
+
+function percent(raw, flag) {
+  const value = number(raw, flag);
+  if (value < 0 || value > 100) throw CliError.usage(`${flag} 必须在 0..100，收到 ${value}`);
+  return value;
+}
+
+function percentValue(args, fallback) {
+  const raw = flagValue(args, '--progress');
+  return raw === null ? fallback : percent(raw, '--progress');
+}
+
+function versionFlag(args) {
+  const raw = flagValue(args, '--version');
+  if (raw === null) return null;
+  const text = String(raw).trim();
+  if (!/^[+-]?\d+$/.test(text)) {
+    throw CliError.usage(`\`--version\` 要一个整数，收到 ${JSON.stringify(raw)}`);
+  }
+  return Number.parseInt(text, 10);
+}
+
+function addText(pairs, args, flag, key, relation = false) {
+  const value = flagValue(args, flag);
+  if (value === null) return;
+  pairs.push(relation ? jsonPair(key, [String(value)]) : textPair(key, String(value)));
+}
+
+function textPair(key, value) {
+  return { forceString: true, key, value: String(value) };
+}
+
+function numberPair(key, value) {
+  return { forceString: false, key, value: String(value) };
+}
+
+function jsonPair(key, value) {
+  return { forceString: false, key, value: JSON.stringify(value) };
+}
+
+function recordValue(record, key) {
+  const value = record?.values?.[key];
+  return value === null || value === undefined ? '' : String(value);
+}
+
+function mentions(record, key, recordId) {
+  const value = record?.values?.[key];
+  if (Array.isArray(value)) return value.some((item) => item === recordId);
+  return value === recordId;
+}
+
+function currentUserId(runtime) {
+  const user = runtime.credentials.get(runtime.profile)?.user;
+  return typeof user?.id === 'string' ? user.id : null;
+}
+
+function versionKey(raw) {
+  return String(raw ?? '')
+    .split('.')
+    .reduce((value, part) => value * 1000 + (Number.parseInt(part, 10) || 0), 0);
+}
+
+function today() {
+  return new Date().toISOString().slice(0, 10);
+}
+
+function timestamp() {
+  return new Date().toISOString().replace(/[-:TZ.]/g, '').slice(0, 14);
+}

package/src/spec/command_surface.json

@@ -27117,6 +27117,248 @@
       "synonym_flags": [],
       "rejected_flags": []
     },
+    {
+      "name": "project",
+      "flags": {
+        "--context": {"takes_value": false, "required": false, "optional_value": false},
+        "--list": {"takes_value": false, "required": false, "optional_value": false},
+        "--create": {"takes_value": false, "required": false, "optional_value": false},
+        "--show": {"takes_value": true, "required": false, "optional_value": false},
+        "--update": {"takes_value": true, "required": false, "optional_value": false},
+        "--add": {"takes_value": false, "required": false, "optional_value": false},
+        "--submit": {"takes_value": false, "required": false, "optional_value": false},
+        "--app": {"takes_value": true, "required": true, "optional_value": true},
+        "--tenant": {"takes_value": true, "required": false, "optional_value": false},
+        "--name": {"takes_value": true, "required": false, "optional_value": false},
+        "--code": {"takes_value": true, "required": false, "optional_value": false},
+        "--owner": {"takes_value": true, "required": false, "optional_value": false},
+        "--start": {"takes_value": true, "required": false, "optional_value": false},
+        "--due": {"takes_value": true, "required": false, "optional_value": false},
+        "--status": {"takes_value": true, "required": false, "optional_value": false},
+        "--health": {"takes_value": true, "required": false, "optional_value": false},
+        "--progress": {"takes_value": true, "required": false, "optional_value": false},
+        "--current-milestone": {"takes_value": true, "required": false, "optional_value": false},
+        "--description": {"takes_value": true, "required": false, "optional_value": false},
+        "--set": {"takes_value": true, "required": false, "optional_value": false},
+        "--version": {"takes_value": true, "required": false, "optional_value": false},
+        "--reason": {"takes_value": true, "required": false, "optional_value": false},
+        "--idempotency-key": {"takes_value": true, "required": false, "optional_value": false},
+        "--all": {"takes_value": false, "required": false, "optional_value": false},
+        "--limit": {"takes_value": true, "required": true, "optional_value": true},
+        "--offset": {"takes_value": true, "required": false, "optional_value": false},
+        "--project": {"takes_value": true, "required": false, "optional_value": false},
+        "--milestone": {"takes_value": true, "required": false, "optional_value": false},
+        "--weight": {"takes_value": true, "required": false, "optional_value": false},
+        "--title": {"takes_value": true, "required": false, "optional_value": false},
+        "--priority": {"takes_value": true, "required": false, "optional_value": false},
+        "--risk": {"takes_value": true, "required": false, "optional_value": false},
+        "--next-step": {"takes_value": true, "required": false, "optional_value": false},
+        "--date": {"takes_value": true, "required": false, "optional_value": false}
+      },
+      "extra_flags": [
+        "--context", "--list", "--create", "--show", "--update", "--add", "--submit",
+        "--app", "--tenant", "--name", "--code", "--owner", "--start", "--due",
+        "--status", "--health", "--progress", "--current-milestone", "--description",
+        "--set", "--version", "--reason", "--idempotency-key", "--all", "--limit",
+        "--offset", "--project", "--milestone", "--weight", "--title", "--priority",
+        "--risk", "--next-step", "--date"
+      ],
+      "allowed_flags": [],
+      "params_raw": [
+        "--list | --show <ID|CODE> | --create | --update <ID|CODE> | --context",
+        "[--tenant <TENANT_ID>]",
+        "[--app <APP_KEY>]"
+      ],
+      "params": [
+        {"flag": "--tenant", "value": "TENANT_ID", "optional": true},
+        {"flag": "--app", "value": "APP_KEY", "optional": true}
+      ],
+      "risk": "write",
+      "requires_yes": false,
+      "endpoints": [
+        "GET /apps",
+        "GET /apps/{id}",
+        "GET /bases",
+        "GET /bases/{id}/tables",
+        "GET|POST|PATCH /tables/{id}/records",
+        "GET|PATCH /records/{id}"
+      ],
+      "examples": [
+        "xinhe-oa-cli project --list --tenant huimeng_xinhe --json",
+        "xinhe-oa-cli project --create --tenant huimeng_xinhe --name 新项目 --owner usr_123 --due 2026-12-31",
+        "xinhe-oa-cli project --update HM-PRJ-001 --tenant huimeng_xinhe --progress 65 --health attention"
+      ],
+      "output_schema": "{binding?, project(s), count, next_step?}",
+      "synonym_flags": [],
+      "rejected_flags": []
+    },
+    {
+      "name": "project milestone",
+      "flags": {
+        "--list": {"takes_value": false, "required": false, "optional_value": false},
+        "--add": {"takes_value": false, "required": false, "optional_value": false},
+        "--update": {"takes_value": true, "required": false, "optional_value": false},
+        "--app": {"takes_value": true, "required": true, "optional_value": true},
+        "--tenant": {"takes_value": true, "required": false, "optional_value": false},
+        "--project": {"takes_value": true, "required": true, "optional_value": false},
+        "--name": {"takes_value": true, "required": false, "optional_value": false},
+        "--owner": {"takes_value": true, "required": false, "optional_value": false},
+        "--due": {"takes_value": true, "required": false, "optional_value": false},
+        "--status": {"takes_value": true, "required": false, "optional_value": false},
+        "--progress": {"takes_value": true, "required": false, "optional_value": false},
+        "--weight": {"takes_value": true, "required": false, "optional_value": false},
+        "--description": {"takes_value": true, "required": false, "optional_value": false},
+        "--set": {"takes_value": true, "required": false, "optional_value": false},
+        "--version": {"takes_value": true, "required": false, "optional_value": false},
+        "--reason": {"takes_value": true, "required": false, "optional_value": false},
+        "--idempotency-key": {"takes_value": true, "required": false, "optional_value": false},
+        "--all": {"takes_value": false, "required": false, "optional_value": false}
+      },
+      "extra_flags": [
+        "--list", "--add", "--update", "--app", "--tenant", "--project", "--name",
+        "--owner", "--due", "--status", "--progress", "--weight", "--description",
+        "--set", "--version", "--reason", "--idempotency-key", "--all"
+      ],
+      "allowed_flags": [],
+      "params_raw": ["--list | --add | --update <MILESTONE_ID>", "--project <ID|CODE>"],
+      "params": [
+        {"flag": "--project", "value": "ID|CODE"}
+      ],
+      "risk": "write",
+      "requires_yes": false,
+      "endpoints": ["GET|POST|PATCH /tables/{id}/records"],
+      "examples": [
+        "xinhe-oa-cli project milestone --list --project HM-PRJ-001 --tenant huimeng_xinhe --json",
+        "xinhe-oa-cli project milestone --add --project HM-PRJ-001 --name MVP交付 --due 2026-12-01 --weight 30"
+      ],
+      "output_schema": "{project, milestones, count}",
+      "synonym_flags": [],
+      "rejected_flags": []
+    },
+    {
+      "name": "project task",
+      "flags": {
+        "--list": {"takes_value": false, "required": false, "optional_value": false},
+        "--create": {"takes_value": false, "required": false, "optional_value": false},
+        "--update": {"takes_value": true, "required": false, "optional_value": false},
+        "--app": {"takes_value": true, "required": true, "optional_value": true},
+        "--tenant": {"takes_value": true, "required": false, "optional_value": false},
+        "--project": {"takes_value": true, "required": true, "optional_value": false},
+        "--milestone": {"takes_value": true, "required": false, "optional_value": false},
+        "--title": {"takes_value": true, "required": false, "optional_value": false},
+        "--owner": {"takes_value": true, "required": false, "optional_value": false},
+        "--status": {"takes_value": true, "required": false, "optional_value": false},
+        "--priority": {"takes_value": true, "required": false, "optional_value": false},
+        "--due": {"takes_value": true, "required": false, "optional_value": false},
+        "--set": {"takes_value": true, "required": false, "optional_value": false},
+        "--version": {"takes_value": true, "required": false, "optional_value": false},
+        "--reason": {"takes_value": true, "required": false, "optional_value": false},
+        "--idempotency-key": {"takes_value": true, "required": false, "optional_value": false},
+        "--all": {"takes_value": false, "required": false, "optional_value": false}
+      },
+      "extra_flags": [
+        "--list", "--create", "--update", "--app", "--tenant", "--project",
+        "--milestone", "--title", "--owner", "--status", "--priority", "--due",
+        "--set", "--version", "--reason", "--idempotency-key", "--all"
+      ],
+      "allowed_flags": [],
+      "params_raw": ["--list | --create | --update <TASK_ID>", "--project <ID|CODE>"],
+      "params": [
+        {"flag": "--project", "value": "ID|CODE"}
+      ],
+      "risk": "write",
+      "requires_yes": false,
+      "endpoints": ["GET|POST|PATCH /tables/{id}/records"],
+      "examples": [
+        "xinhe-oa-cli project task --list --project HM-PRJ-001 --tenant huimeng_xinhe --json",
+        "xinhe-oa-cli project task --create --project HM-PRJ-001 --title 完成联调 --owner usr_123"
+      ],
+      "output_schema": "{project, tasks, count}",
+      "synonym_flags": [],
+      "rejected_flags": []
+    },
+    {
+      "name": "project progress",
+      "flags": {
+        "--list": {"takes_value": false, "required": false, "optional_value": false},
+        "--submit": {"takes_value": false, "required": false, "optional_value": false},
+        "--app": {"takes_value": true, "required": true, "optional_value": true},
+        "--tenant": {"takes_value": true, "required": false, "optional_value": false},
+        "--project": {"takes_value": true, "required": true, "optional_value": false},
+        "--progress": {"takes_value": true, "required": false, "optional_value": false},
+        "--summary": {"takes_value": true, "required": false, "optional_value": false},
+        "--risk": {"takes_value": true, "required": false, "optional_value": false},
+        "--next-step": {"takes_value": true, "required": false, "optional_value": false},
+        "--date": {"takes_value": true, "required": false, "optional_value": false},
+        "--set": {"takes_value": true, "required": false, "optional_value": false},
+        "--reason": {"takes_value": true, "required": false, "optional_value": false},
+        "--idempotency-key": {"takes_value": true, "required": false, "optional_value": false},
+        "--all": {"takes_value": false, "required": false, "optional_value": false}
+      },
+      "extra_flags": [
+        "--list", "--submit", "--app", "--tenant", "--project", "--progress",
+        "--summary", "--risk", "--next-step", "--date", "--set", "--reason",
+        "--idempotency-key", "--all"
+      ],
+      "allowed_flags": [],
+      "params_raw": ["--list | --submit", "--project <ID|CODE>", "--progress <PERCENT>", "--summary <TEXT>"],
+      "params": [
+        {"flag": "--project", "value": "ID|CODE"}
+      ],
+      "risk": "write",
+      "requires_yes": false,
+      "endpoints": ["GET|POST /tables/{id}/records"],
+      "examples": [
+        "xinhe-oa-cli project progress --list --project HM-PRJ-001 --tenant huimeng_xinhe --json",
+        "xinhe-oa-cli project progress --submit --project HM-PRJ-001 --progress 72 --summary 本周完成联调 --risk 等待测试数据"
+      ],
+      "output_schema": "{project, updates, count}",
+      "synonym_flags": [],
+      "rejected_flags": []
+    },
+    {
+      "name": "member --link",
+      "flags": {
+        "--link": {
+          "takes_value": true,
+          "required": true,
+          "optional_value": false
+        },
+        "--tenant": {
+          "takes_value": true,
+          "required": false,
+          "optional_value": false
+        }
+      },
+      "extra_flags": [],
+      "allowed_flags": [],
+      "params_raw": [
+        "--link <USER_ID>",
+        "[--tenant <TENANT_ID>]"
+      ],
+      "params": [
+        {
+          "flag": "--link",
+          "value": "USER_ID"
+        },
+        {
+          "flag": "--tenant",
+          "value": "TENANT_ID",
+          "optional": true
+        }
+      ],
+      "risk": "write",
+      "requires_yes": false,
+      "endpoints": [
+        "POST /portal/auth/links"
+      ],
+      "examples": [
+        "xinhe-oa-cli member --link usr_123 --tenant huimeng_xinhe --json"
+      ],
+      "output_schema": "{url, ticket, expires_at, user, tenant}",
+      "synonym_flags": [],
+      "rejected_flags": []
+    },
     {
       "name": "schema",
       "flags": {

package/src/version.js

@@ -6,7 +6,7 @@
 //
 // 这个常量与 `package.json` 的 `version` **必须一致**：`test/version.test.js`
 // 会逐字比对，`npm version` 之后忘了改这里就会红。
-export const VERSION = '0.2.5';
+export const VERSION = '0.2.6';
 
 /**
  * npm 包名（升级指引 `npm i -g <包名>@latest` 与 `doctor` 的 npm 探测都用它）。