@openturtle/cli 0.4.1 → 0.4.2

package/dist/commands/collaboration.js

@@ -1,6 +1,7 @@
 import { ApiClient, listQuery } from '../core/api-client.js';
 import { collectOption, parseKeyValueOptions, readJsonBody } from '../core/input.js';
 import { addReadBoundaryOptions, addSnapshotPolicyOptions, buildReadBoundaryQuery, buildSnapshotExportBody, } from './read-boundary.js';
+import { DECISION_CREATE_SCHEMA, DECISION_UPDATE_SCHEMA, GOAL_CREATE_SCHEMA, GOAL_UPDATE_SCHEMA, KNOWLEDGE_SAVE_SCHEMA, TODO_CREATE_SCHEMA, TODO_UPDATE_SCHEMA, WORKLOG_CREATE_SCHEMA, formatSchema, validateBody, } from './schemas.js';
 const PROJECT_ACTIVE_TODO_STATUSES = ['draft', 'pending', 'in_progress', 'pending_review', 'failed'];
 function withProjectTodoSummary(project) {
     const byStatus = project.todo_stats?.by_status;
@@ -125,6 +126,17 @@ export function createCollaborationCommands(client = new ApiClient()) {
         getContextItem: (sourceType, sourceId, options) => client.get(`/api/project-context/items/${encodeURIComponent(sourceType)}/${encodeURIComponent(sourceId)}`, listQuery(options)),
         relations: (knowledgeId) => client.get(`/api/memory/objects/${encodeURIComponent(knowledgeId)}/relations`),
         saveKnowledge: (knowledgeId, body, dryRun = false) => mutate(knowledgeId ? 'PATCH' : 'POST', knowledgeId ? `/api/memory/objects/${encodeURIComponent(knowledgeId)}` : '/api/memory/objects', body, dryRun),
+        listDecisions: (options) => client.get('/api/memory/objects', listQuery({
+            type: 'knowledge',
+            kind: 'decision',
+            project_id: options.project_id || options.project,
+            q: options.q,
+            space: options.space,
+            page: options.page,
+            page_size: options.pageSize || options.page_size,
+            ...buildReadBoundaryQuery(options),
+        })),
+        showDecision: (decisionId) => client.get(`/api/memory/objects/${encodeURIComponent(decisionId)}`),
         attachKnowledge: async (knowledgeId, files, dryRun = false) => {
             const path = `/api/memory/objects/${encodeURIComponent(knowledgeId)}/attachments`;
             if (dryRun)
@@ -292,9 +304,46 @@ export function registerCollaborationCommands(program, groups, callbacks) {
         .action(action(async (knowledgeId) => print(await commands.relations(knowledgeId))));
     groups.knowledge
         .command('save [knowledgeId]')
-        .requiredOption('--body-file <path>', 'JSON body file, or - for stdin')
+        .option('--body-file <path>', 'JSON body file, or - for stdin')
         .option('--dry-run')
-        .action(action(async (knowledgeId, options) => print(await commands.saveKnowledge(knowledgeId, await readJsonBody(options.bodyFile), Boolean(options.dryRun)))));
+        .option('--show-schema', 'print the request body schema and exit')
+        .description(`保存知识 (type=knowledge)。无 id = POST 新建; 带 id = PATCH 更新 (可改 content/metadata_/status/kind, merge 语义)。\n注意 body.content 是对象 (如 {title, body, summary}), 不是字符串——title/body 必须放 content 里, 放顶层会丢。\nFields: ${KNOWLEDGE_SAVE_SCHEMA.fields.map((f) => f.name).join(', ')}\nRequired (create only): kind, content\n推进 status 用 review 子命令, 或 save <id> --body-file '{"status":"validated"}'\n(use --show-schema for full detail)`)
+        .action(action(async (knowledgeId, options) => {
+        if (options.showSchema) {
+            print(formatSchema(KNOWLEDGE_SAVE_SCHEMA));
+            return;
+        }
+        const body = await readJsonBody(options.bodyFile);
+        const dryRun = Boolean(options.dryRun);
+        if (dryRun) {
+            const echoed = await commands.saveKnowledge(knowledgeId, body, true);
+            const report = validateBody(KNOWLEDGE_SAVE_SCHEMA, body, !knowledgeId);
+            print({
+                ...(echoed && typeof echoed === 'object' ? echoed : { result: echoed }),
+                validation: report.errors.length
+                    ? { valid: false, errors: report.errors, warnings: report.warnings }
+                    : { valid: true, warnings: report.warnings },
+                preview: previewMutation(KNOWLEDGE_SAVE_SCHEMA, body, knowledgeId ? { knowledgeId } : {}),
+            });
+            if (report.errors.length)
+                process.exit(1);
+            return;
+        }
+        print(await commands.saveKnowledge(knowledgeId, body, dryRun));
+    }));
+    groups.knowledge
+        .command('review <knowledgeId>')
+        .description('推进知识状态 (draft→validated); 等价 save <id> --body-file {"status":...}; knowledge 无独立审核流')
+        .option('--status <status>', '目标状态 (draft/validated/...)')
+        .option('--approve', '便捷: 等价 --status validated')
+        .option('--dry-run')
+        .action(action(async (knowledgeId, options) => {
+        const status = options.approve ? 'validated' : options.status;
+        if (!status) {
+            throw new Error('Use --status <status> (e.g. validated) or --approve');
+        }
+        print(await commands.saveKnowledge(knowledgeId, { status }, Boolean(options.dryRun)));
+    }));
     groups.knowledge
         .command('attach <knowledgeId> <files...>')
         .option('--dry-run')
@@ -309,6 +358,30 @@ export function registerCollaborationCommands(program, groups, callbacks) {
         .option('--force')
         .option('--dry-run')
         .action(action(async (knowledgeId, attachmentId, options) => print(await commands.downloadKnowledgeAttachment(knowledgeId, attachmentId, options.output, Boolean(options.force), Boolean(options.dryRun)))));
+    const decisions = program
+        .command('decisions')
+        .description('可检索的团队决策 (knowledge kind=decision; 会议 decision/risk 候选物化为 WorkLog)');
+    addReadBoundaryOptions(decisions
+        .command('list')
+        .option('--project <id>')
+        .option('--q <keyword>')
+        .option('--space <space>', 'personal|team')
+        .option('--page <number>', 'page number', Number)
+        .option('--page-size <number>', 'items per page', Number)
+        .option('--json')).action(action(async (options) => print(await commands.listDecisions({
+        project: options.project,
+        q: options.q,
+        space: options.space,
+        page: options.page,
+        pageSize: options.pageSize,
+        ...buildReadBoundaryQuery(options),
+    }), options.json)));
+    decisions
+        .command('show <decisionId>')
+        .option('--json')
+        .action(action(async (decisionId, options) => print(await commands.showDecision(decisionId), options.json)));
+    registerJsonMutation(decisions, 'create', [], (args, body, dryRun) => commands.saveKnowledge(undefined, withDecisionKind(body), dryRun), action, print, DECISION_CREATE_SCHEMA);
+    registerJsonMutation(decisions, 'update <decisionId>', ['decisionId'], (args, body, dryRun) => commands.saveKnowledge(args.decisionId, withDecisionKind(body), dryRun), action, print, DECISION_UPDATE_SCHEMA);
     const meetings = program.command('meetings').description('Meeting upload, minutes, knowledge, and project updates');
     addReadBoundaryOptions(meetings
         .command('list')
@@ -383,12 +456,12 @@ export function registerCollaborationCommands(program, groups, callbacks) {
         .command('ignore <meetingId> <updateId>')
         .option('--dry-run')
         .action(action(async (meetingId, updateId, options) => print(await commands.ignoreProjectUpdate(meetingId, updateId, Boolean(options.dryRun)))));
-    registerJsonMutation(groups.goals, 'create', [], (args, body, dryRun) => commands.createGoal(body, dryRun), action, print);
-    registerJsonMutation(groups.goals, 'update <goalId>', ['goalId'], (args, body, dryRun) => commands.updateGoal(args.goalId, body, dryRun), action, print);
+    registerJsonMutation(groups.goals, 'create', [], (args, body, dryRun) => commands.createGoal(body, dryRun), action, print, GOAL_CREATE_SCHEMA);
+    registerJsonMutation(groups.goals, 'update <goalId>', ['goalId'], (args, body, dryRun) => commands.updateGoal(args.goalId, body, dryRun), action, print, GOAL_UPDATE_SCHEMA);
     registerJsonMutation(groups.goals, 'submit-review <goalId>', ['goalId'], (args, body, dryRun) => commands.submitGoalReview(args.goalId, body, dryRun), action, print);
     registerJsonMutation(groups.goals, 'review <goalId>', ['goalId'], (args, body, dryRun) => commands.reviewGoal(args.goalId, body, dryRun), action, print);
-    registerJsonMutation(groups.todos, 'create', [], (args, body, dryRun) => commands.createTodo(body, dryRun), action, print);
-    registerJsonMutation(groups.todos, 'update <todoId>', ['todoId'], (args, body, dryRun) => commands.updateTodo(args.todoId, body, dryRun), action, print);
+    registerJsonMutation(groups.todos, 'create', [], (args, body, dryRun) => commands.createTodo(body, dryRun), action, print, TODO_CREATE_SCHEMA);
+    registerJsonMutation(groups.todos, 'update <todoId>', ['todoId'], (args, body, dryRun) => commands.updateTodo(args.todoId, body, dryRun), action, print, TODO_UPDATE_SCHEMA);
     registerJsonMutation(groups.todos, 'submit-review <todoId>', ['todoId'], (args, body, dryRun) => commands.submitTodoReview(args.todoId, body, dryRun), action, print);
     registerJsonMutation(groups.todos, 'review <todoId>', ['todoId'], (args, body, dryRun) => commands.reviewTodo(args.todoId, body, dryRun), action, print);
     groups.todos
@@ -399,7 +472,7 @@ export function registerCollaborationCommands(program, groups, callbacks) {
         .command('assign <todoId> <assigneeId>')
         .option('--dry-run')
         .action(action(async (todoId, assigneeId, options) => print(await commands.assignTodo(todoId, assigneeId, Boolean(options.dryRun)))));
-    registerJsonMutation(groups.worklogs, 'create', [], (args, body, dryRun) => commands.createWorklog(body, dryRun), action, print);
+    registerJsonMutation(groups.worklogs, 'create', [], (args, body, dryRun) => commands.createWorklog(body, dryRun), action, print, WORKLOG_CREATE_SCHEMA);
     program
         .command('request')
         .description('Read-only raw API escape hatch')
@@ -411,17 +484,54 @@ export function registerCollaborationCommands(program, groups, callbacks) {
         print(await commands.requestGet(path, parseKeyValueOptions(options.query)));
     }));
 }
-function registerJsonMutation(parent, name, argumentNames, execute, action, print) {
+function registerJsonMutation(parent, name, argumentNames, execute, action, print, schema) {
     const command = parent
         .command(name)
-        .requiredOption('--body-file <path>', 'JSON body file, or - for stdin')
-        .option('--dry-run');
+        .option('--body-file <path>', 'JSON body file, or - for stdin')
+        .option('--dry-run')
+        .option('--show-schema', 'print the request body schema and exit');
+    if (schema) {
+        const required = schema.fields.filter((f) => f.required).map((f) => f.name).join(', ');
+        command.description(`${schema.description}\n\nFields: ${schema.fields.map((f) => f.name).join(', ')}\nRequired: ${required || '(none)'}\n(use --show-schema for full detail and example)`);
+    }
     command.action(action(async (...values) => {
         const options = values[argumentNames.length];
         const args = Object.fromEntries(argumentNames.map((argument, index) => [argument, String(values[index])]));
-        print(await execute(args, await readJsonBody(options.bodyFile), Boolean(options.dryRun)));
+        if (options.showSchema && schema) {
+            print(formatSchema(schema));
+            return;
+        }
+        const body = await readJsonBody(options.bodyFile);
+        const dryRun = Boolean(options.dryRun);
+        if (schema && dryRun) {
+            const echoed = await execute(args, body, true);
+            const report = validateBody(schema, body);
+            print({
+                ...(echoed && typeof echoed === 'object' ? echoed : { result: echoed }),
+                validation: report.errors.length
+                    ? { valid: false, errors: report.errors, warnings: report.warnings }
+                    : { valid: true, warnings: report.warnings },
+                preview: previewMutation(schema, body, args),
+            });
+            if (report.errors.length)
+                process.exit(1);
+            return;
+        }
+        print(await execute(args, body, dryRun));
     }));
 }
+/** Best-effort, human-readable preview of what a mutation will create/update. */
+function previewMutation(schema, body, args) {
+    const label = body.title ?? body.summary ?? body.what ?? body.name;
+    const summary = `${schema.method === 'POST' ? 'create' : 'update'} ${schema.description.split(' — ')[1] || ''}`.trim();
+    return {
+        will: summary,
+        ...(typeof label === 'string' && label ? { label } : {}),
+        ...(body.kind ? { kind: body.kind } : {}),
+        ...(Object.keys(args).length ? { target: args } : {}),
+        provided_fields: Object.keys(body),
+    };
+}
 function dryRunRequest(method, path, body) {
     return {
         dry_run: true,
@@ -439,3 +549,7 @@ function dryRunDownload(path, output, force) {
         output: { path: output || null, force },
     };
 }
+/** Pin a knowledge body to the decision contract so `ot decisions create/update` always stores kind=decision. */
+export function withDecisionKind(body) {
+    return { ...body, type: 'knowledge', kind: 'decision' };
+}

package/dist/commands/schemas.js

@@ -0,0 +1,224 @@
+/** Body schemas for ot CLI write commands, aligned with backend pydantic models.
+ *
+ * These are intentionally hand-mirrored from the backend request schemas so the CLI
+ * can surface required fields and validate dry-run bodies without a network round-trip.
+ * Keep in sync with:
+ *   - packages/backend/.../common/schemas/goal.py        (GoalCreate / GoalUpdate)
+ *   - packages/backend/.../common/schemas/todo.py         (TodoCreate / TodoUpdate)
+ *   - packages/backend/.../common/schemas/work_log.py     (WorkLogCreate)
+ *   - packages/backend/.../common/schemas/memory.py       (MemoryObjectCreate / RememberRequest)
+ */
+const GOAL_STATUS_ENUM = ['active', 'paused', 'completed', 'cancelled'];
+export const GOAL_CREATE_SCHEMA = {
+    description: 'POST /api/goals — 创建目标',
+    method: 'POST',
+    fields: [
+        { name: 'title', type: 'string', required: true, description: '目标标题 (1-256)' },
+        { name: 'success_criteria', type: 'string', required: true, description: '成功标准 (1-4096)' },
+        { name: 'owner_ids', type: 'string[]', required: true, description: '负责人用户 id 列表 (至少 1 个, ≤20)' },
+        { name: 'description', type: 'string', default: '', description: '目标描述' },
+        { name: 'manager_ids', type: 'string[]', description: '管理者 id (≤20)' },
+        { name: 'collaborator_ids', type: 'string[]', description: '协作者 id (≤100)' },
+        { name: 'linked_project_id', type: 'string', description: '关联项目 id' },
+        { name: 'status', type: 'enum', enum: GOAL_STATUS_ENUM, default: 'active', description: '初始状态' },
+    ],
+    example: {
+        title: 'Q3 交付 XX 能力',
+        success_criteria: '灰度上线并达成 N 个团队采用',
+        owner_ids: ['<user-id>'],
+        linked_project_id: '<project-id>',
+    },
+};
+export const GOAL_UPDATE_SCHEMA = {
+    description: 'PATCH /api/goals/{id} — 更新目标 (未提供字段不改)',
+    method: 'PATCH',
+    fields: [
+        { name: 'title', type: 'string', description: '新标题 (1-256)' },
+        { name: 'description', type: 'string', description: '新描述' },
+        { name: 'success_criteria', type: 'string', description: '新成功标准 (1-4096)' },
+        { name: 'owner_ids', type: 'string[]', description: '负责人 id (≥1, ≤20)' },
+        { name: 'manager_ids', type: 'string[]', description: '管理者 id (≤20)' },
+        { name: 'collaborator_ids', type: 'string[]', description: '协作者 id (≤100)' },
+        { name: 'linked_project_id', type: 'string', description: '关联项目 id' },
+        { name: 'status', type: 'enum', enum: GOAL_STATUS_ENUM, description: '状态' },
+        { name: 'progress_description', type: 'string', description: '进度描述' },
+        { name: 'risk_level', type: 'enum', enum: ['low', 'medium', 'high'], description: '风险等级' },
+    ],
+    example: { status: 'paused', progress_description: '等待依赖到位' },
+};
+const TODO_ASSIGNEE_TYPE_ENUM = ['human', 'agent', 'agent_with_skill'];
+export const TODO_CREATE_SCHEMA = {
+    description: 'POST /api/todos — 创建待办',
+    method: 'POST',
+    fields: [
+        { name: 'title', type: 'string', required: true, description: '待办标题 (1-256)' },
+        { name: 'project_id', type: 'string', description: '关联项目 id' },
+        { name: 'goal_id', type: 'string', description: '关联目标 id' },
+        { name: 'task_id', type: 'string', description: '关联 Task id' },
+        { name: 'assignee_id', type: 'string', description: '主负责人 id (兼容旧客户端)' },
+        { name: 'assignee_ids', type: 'string[]', description: '全部负责人 id' },
+        { name: 'description', type: 'string', default: '', description: '详细描述' },
+        { name: 'due_date', type: 'datetime', description: '截止时间 (YYYY-MM-DD 或 ISO)' },
+        { name: 'assignee_type', type: 'enum', enum: TODO_ASSIGNEE_TYPE_ENUM, description: '指派类型' },
+        { name: 'skill_ids', type: 'string[]', description: 'Skill id 列表' },
+        { name: 'depends_on', type: 'string[]', description: '前置依赖 Todo id' },
+        { name: 'reviewer_ids', type: 'string[]', description: '评审人 id (提供则 review_required 自动 true)' },
+        { name: 'acceptance_criteria', type: 'string', description: '验收标准' },
+        { name: 'evidence_required', type: 'string', description: '需要的证据说明' },
+        { name: 'metadata', type: 'object', description: '扩展元数据' },
+    ],
+    example: {
+        title: '完成 XX 接口联调',
+        project_id: '<project-id>',
+        assignee_ids: ['<user-id>'],
+        due_date: '2026-08-15',
+    },
+};
+export const TODO_UPDATE_SCHEMA = {
+    description: 'PATCH /api/todos/{id} — 更新待办 (未提供字段不改; 显式 null 清除 due_date)',
+    method: 'PATCH',
+    fields: [
+        { name: 'title', type: 'string', description: '新标题 (1-256)' },
+        { name: 'description', type: 'string', description: '新描述 (空串清空)' },
+        { name: 'project_id', type: 'string', description: '重新归属项目 (null 清除)' },
+        { name: 'goal_id', type: 'string', description: '重新归属目标 (null 清除)' },
+        { name: 'due_date', type: 'datetime', description: '截止时间 (null 清除)' },
+        { name: 'assignee_id', type: 'string', description: '重新指派' },
+        { name: 'assignee_ids', type: 'string[]', description: '全部负责人 id' },
+        { name: 'assignee_type', type: 'enum', enum: TODO_ASSIGNEE_TYPE_ENUM, description: '指派类型' },
+        { name: 'execution_result', type: 'object', description: '执行结果 (agent 产出 / human 提交)' },
+        { name: 'reviewer_ids', type: 'string[]', description: '评审人 id' },
+        { name: 'review_required', type: 'boolean', description: '是否需要评审' },
+        { name: 'acceptance_criteria', type: 'string', description: '验收标准' },
+        { name: 'evidence_required', type: 'string', description: '需要的证据说明' },
+        { name: 'metadata', type: 'object', description: '扩展元数据' },
+    ],
+    example: { due_date: '2026-08-20', description: '联调完成, 待验收' },
+};
+const WORKLOG_EVENT_TYPE_ENUM = ['progress', 'blocker', 'decision', 'commit', 'note', 'meeting'];
+const WORKLOG_SOURCE_ENUM = ['manual', 'agent', 'system', 'git'];
+export const WORKLOG_CREATE_SCHEMA = {
+    description: 'POST /api/work-logs — 录入工作日志 (便捷写法见 ot worklogs record)',
+    method: 'POST',
+    fields: [
+        { name: 'summary', type: 'string', required: true, description: '摘要 (1-4096)' },
+        { name: 'event_type', type: 'enum', enum: WORKLOG_EVENT_TYPE_ENUM, required: true, description: '事件类型' },
+        { name: 'source', type: 'enum', enum: WORKLOG_SOURCE_ENUM, required: true, description: '来源' },
+        { name: 'project_id', type: 'string', description: '关联项目 id' },
+        { name: 'goal_id', type: 'string', description: '关联目标 id' },
+        { name: 'todo_id', type: 'string', description: '关联待办 id' },
+        { name: 'task_id', type: 'string', description: '关联 Task id' },
+        { name: 'occurred_at', type: 'datetime', description: '发生时间 (默认现在)' },
+        { name: 'changed_files', type: 'string[]', description: '变更文件列表' },
+        { name: 'diff_stat', type: 'string', description: 'diff 摘要' },
+        { name: 'metadata', type: 'object', description: '扩展元数据' },
+    ],
+    example: {
+        summary: '完成 XX 模块联调',
+        event_type: 'progress',
+        source: 'manual',
+        project_id: '<project-id>',
+    },
+};
+const KNOWLEDGE_KIND_ENUM = ['note', 'decision', 'fact', 'meeting'];
+export const KNOWLEDGE_SAVE_SCHEMA = {
+    description: 'POST/PATCH /api/memory/objects — 创建/更新知识 (type=knowledge)',
+    method: 'POST',
+    fields: [
+        { name: 'kind', type: 'enum', enum: KNOWLEDGE_KIND_ENUM, required: true, description: '知识细分类' },
+        { name: 'content', type: 'object', required: true, description: '主体内容, 建议结构 {title, body, summary?, ...}' },
+        { name: 'scope', type: 'string', default: 'org', description: '作用域 (org/project/case/...)' },
+        { name: 'status', type: 'string', default: 'draft', description: '状态 (draft/validated/...)' },
+        { name: 'project_id', type: 'string', description: '关联项目 id' },
+        { name: 'space', type: 'enum', enum: ['team', 'personal'], default: 'team', description: '可见空间' },
+        { name: 'metadata_', type: 'object', description: '元数据' },
+        { name: 'refs', type: 'object', description: '关联实体 [{target_type, target_id}]' },
+    ],
+    example: {
+        kind: 'note',
+        content: { title: '溯源接口在测试环境会 404', body: '根因是 nginx 未代理该路径' },
+    },
+};
+/** Decision-oriented knowledge body (kind=decision). Used by `ot decisions create`. */
+export const DECISION_CREATE_SCHEMA = {
+    description: 'POST /api/memory/objects (kind=decision) — 沉淀一条可检索的决策',
+    method: 'POST',
+    fields: [
+        { name: 'kind', type: 'enum', enum: ['decision'], required: true, default: 'decision', description: '固定 decision' },
+        {
+            name: 'content',
+            type: 'object',
+            required: true,
+            description: '决策内容: {title, body, why?, how_to_apply?, due_date?}',
+        },
+        { name: 'scope', type: 'string', default: 'org', description: '作用域' },
+        { name: 'project_id', type: 'string', description: '关联项目 id' },
+        { name: 'space', type: 'enum', enum: ['team', 'personal'], default: 'team', description: '可见空间' },
+        { name: 'refs', type: 'object', description: '关联实体 [{target_type, target_id}]' },
+    ],
+    example: {
+        kind: 'decision',
+        content: {
+            title: '统一用 ot decisions 沉淀团队决策',
+            body: '会议 decision/risk 候选 confirm 后物化为 WorkLog; 正式决策另存 kind=decision',
+            why: '避免决策散落在聊天记录里无法检索',
+            how_to_apply: '会后用 ot decisions create 写入, 带项目归属',
+        },
+    },
+};
+export const DECISION_UPDATE_SCHEMA = {
+    description: 'PATCH /api/memory/objects/{id} (kind=decision) — 更新决策 (content merge 语义)',
+    method: 'PATCH',
+    fields: [
+        { name: 'content', type: 'object', description: '合并到 content 的字段 {title?, body?, why?, how_to_apply?, due_date?}' },
+        { name: 'metadata_', type: 'object', description: '合并到 metadata 的字段' },
+        { name: 'status', type: 'string', description: '状态 (draft/validated/...)' },
+    ],
+    example: { content: { title: '修订后的决策标题', how_to_apply: '更新后的执行方式' } },
+};
+export const SCHEMAS = {
+    'goals create': GOAL_CREATE_SCHEMA,
+    'goals update': GOAL_UPDATE_SCHEMA,
+    'todos create': TODO_CREATE_SCHEMA,
+    'todos update': TODO_UPDATE_SCHEMA,
+    'worklogs create': WORKLOG_CREATE_SCHEMA,
+    'knowledge save': KNOWLEDGE_SAVE_SCHEMA,
+    'decisions create': DECISION_CREATE_SCHEMA,
+    'decisions update': DECISION_UPDATE_SCHEMA,
+};
+/** Validate a request body against a schema (required fields + unknown-field hints).
+ *
+ * Set `strict=false` for endpoints that double as create+update (e.g. knowledge save):
+ * required-field checks are skipped so a partial update body isn't flagged.
+ */
+export function validateBody(schema, body, strict = true) {
+    const errors = [];
+    const warnings = [];
+    const known = new Set(schema.fields.map((f) => f.name));
+    if (strict) {
+        for (const field of schema.fields) {
+            if (field.required && !(field.name in body)) {
+                errors.push(`missing required field: ${field.name} (${field.type})`);
+            }
+        }
+    }
+    for (const key of Object.keys(body)) {
+        if (!known.has(key)) {
+            warnings.push(`unknown field "${key}" — not in schema (may still be accepted by backend)`);
+        }
+    }
+    return { errors, warnings };
+}
+/** Render a schema as a human-readable block (for --show-schema / --help). */
+export function formatSchema(schema) {
+    const lines = [schema.description, ''];
+    lines.push('Fields:');
+    for (const f of schema.fields) {
+        const req = f.required ? ' (required)' : '';
+        const def = f.default !== undefined ? ` [default: ${f.default}]` : '';
+        const en = f.enum ? ` {${f.enum.join('|')}}` : '';
+        lines.push(`  ${f.name}: ${f.type}${en}${req}${def}  — ${f.description}`);
+    }
+    lines.push('', 'Example:', JSON.stringify(schema.example, null, 2));
+    return lines.join('\n');
+}

package/dist/core/api-client.js

@@ -1,6 +1,6 @@
 import fs from 'node:fs';
 import nodePath from 'node:path';
-import { readAuth, writeAuth } from './auth.js';
+import { jwtExpiresAt, readAuth, writeAuth } from './auth.js';
 import { DEFAULT_SERVER_URL } from './defaults.js';
 export class ApiError extends Error {
     method;
@@ -17,20 +17,21 @@ export class ApiError extends Error {
         this.name = 'ApiError';
     }
 }
+const REFRESH_LEEWAY_MS = 60_000;
 export class ApiClient {
     options;
     constructor(options = {}) {
         this.options = options;
     }
     async request(method, path, body, query) {
-        const { url, token } = this.requestContext(path, query);
-        const response = await this.fetchResponse(method, url, {
+        const buildInit = (token) => ({
             headers: {
                 ...(body == null ? {} : { 'content-type': 'application/json' }),
                 ...(token ? { authorization: `Bearer ${token}` } : {}),
             },
             ...(body == null ? {} : { body: JSON.stringify(body) }),
         });
+        const { url, response } = await this.authenticatedFetch(method, path, query, buildInit);
         return this.parseResponse(method, url, response);
     }
     get(path, query) {
@@ -62,18 +63,18 @@ export class ApiClient {
             const bytes = fs.readFileSync(file.filePath);
             form.append(file.field, new Blob([bytes], { type: contentTypeFor(file.filePath) }), nodePath.basename(file.filePath));
         }
-        const { url, token } = this.requestContext(pathname);
-        const response = await this.fetchResponse(method, url, {
+        const buildInit = (token) => ({
             headers: token ? { authorization: `Bearer ${token}` } : {},
             body: form,
         });
+        const { url, response } = await this.authenticatedFetch(method, pathname, undefined, buildInit);
         return this.parseResponse(method, url, response);
     }
     async download(pathname, outputPath, force = false) {
-        const { url, token } = this.requestContext(pathname);
-        const response = await this.fetchResponse('GET', url, {
+        const buildInit = (token) => ({
             headers: token ? { authorization: `Bearer ${token}` } : {},
         });
+        const { url, response } = await this.authenticatedFetch('GET', pathname, undefined, buildInit);
         if (!response.ok)
             return this.parseResponse('GET', url, response);
         const filename = responseFilename(response) || 'download';
@@ -135,9 +136,86 @@ export class ApiClient {
         }
         return { url, token, server };
     }
+    async authenticatedFetch(method, pathname, query, buildInit) {
+        const { url, server } = this.requestContext(pathname, query);
+        let auth = readAuth(this.options.homeDir);
+        let token = this.options.token || auth.token;
+        // An explicit token (option or env override) is never refreshed: there is
+        // no stored credential to rotate and nothing safe to persist.
+        const canRefresh = !this.options.token && !this.tokenFromEnv() && Boolean(auth.refreshToken);
+        // Proactive refresh: avoid starting a request with a token that is about
+        // to expire (long-running commands would otherwise hit 401 mid-run).
+        if (canRefresh && this.tokenExpiringSoon(token)) {
+            if ((await this.tryRefreshToken(server)) === 'refreshed') {
+                auth = readAuth(this.options.homeDir);
+                token = auth.token;
+            }
+        }
+        let response = await this.fetchResponse(method, url, buildInit(token));
+        // Reactive refresh: on 401, rotate the stored token once and retry.
+        if (response.status === 401 && canRefresh) {
+            const outcome = await this.tryRefreshToken(server);
+            if (outcome === 'refreshed') {
+                const retried = readAuth(this.options.homeDir);
+                response = await this.fetchResponse(method, url, buildInit(retried.token));
+            }
+            else if (outcome === 'invalid') {
+                throw new ApiError(`${method} ${url.pathname} failed: 401 access token expired and the stored refresh token is no longer valid. Run \`ot auth login --web\` to sign in again.`, method, url.pathname, 401);
+            }
+        }
+        return { url, response };
+    }
+    async tryRefreshToken(server) {
+        const auth = readAuth(this.options.homeDir);
+        if (!auth.refreshToken)
+            return 'error';
+        const url = resolveApiUrl(server, '/api/auth/refresh');
+        let response;
+        try {
+            response = await this.fetchImpl()(url.toString(), {
+                method: 'POST',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify({ refresh_token: auth.refreshToken }),
+            });
+        }
+        catch {
+            // Network-level failure: keep the stored tokens, surface the original error.
+            return 'error';
+        }
+        let payload = {};
+        if (response.ok) {
+            payload = (await response.json().catch(() => ({})));
+        }
+        if (!response.ok || !payload.access_token) {
+            // The refresh token is dead too: drop the dead tokens so subsequent
+            // commands fail fast with a clear "please log in" state.
+            const { token: _token, refreshToken: _refreshToken, ...rest } = auth;
+            writeAuth(rest, this.options.homeDir);
+            return 'invalid';
+        }
+        writeAuth({
+            ...auth,
+            token: payload.access_token,
+            refreshToken: payload.refresh_token || auth.refreshToken,
+        }, this.options.homeDir);
+        return 'refreshed';
+    }
+    tokenExpiringSoon(token) {
+        const expiresAt = jwtExpiresAt(token);
+        if (expiresAt == null)
+            return false;
+        const now = (this.options.now || Date.now)();
+        return expiresAt * 1000 - now < REFRESH_LEEWAY_MS;
+    }
+    tokenFromEnv() {
+        return Boolean(process.env.OPENTURTLE_API_TOKEN || process.env.OPENTURTLE_TOKEN);
+    }
+    fetchImpl() {
+        return this.options.fetchImpl || fetch;
+    }
     async fetchResponse(method, url, init) {
         try {
-            return await fetch(url, { ...init, method });
+            return await this.fetchImpl()(url, { ...init, method });
         }
         catch (error) {
             const detail = error instanceof Error ? error.message : String(error);

package/dist/core/auth.js

@@ -28,6 +28,20 @@ export function clearAuth(homeDir = os.homedir()) {
     if (fs.existsSync(filePath))
         fs.unlinkSync(filePath);
 }
+export function jwtExpiresAt(token) {
+    if (!token)
+        return undefined;
+    const parts = token.split('.');
+    if (parts.length !== 3)
+        return undefined;
+    try {
+        const payload = JSON.parse(Buffer.from(parts[1], 'base64url').toString('utf-8'));
+        return typeof payload.exp === 'number' ? payload.exp : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 export function redactToken(token) {
     if (!token)
         return undefined;

package/dist/core/time.js

@@ -0,0 +1,46 @@
+/** Local-timezone helpers for CLI output.
+ *
+ * The backend stores all timestamps as UTC ISO strings (DateTime(timezone=True)).
+ * These helpers add a human-readable, local-tz companion field without mutating the
+ * canonical ISO value, so JSON consumers keep a stable contract while humans get a
+ * readable time. Uses Node's built-in Intl — no third-party dependency.
+ */
+const DEFAULT_TZ = 'Asia/Shanghai';
+/** Format a UTC ISO timestamp as a local-tz string, e.g. "2026-08-15 00:00:00 (Asia/Shanghai)".
+ *
+ * The 'sv-SE' locale is used because it yields ISO-like "YYYY-MM-DD HH:MM:SS" output,
+ * which is far more readable than the default en-US formatting.
+ */
+export function formatLocalDateTime(iso, tz = DEFAULT_TZ) {
+    const date = new Date(iso);
+    if (Number.isNaN(date.getTime()))
+        return iso;
+    const local = date.toLocaleString('sv-SE', { timeZone: tz, hour12: false });
+    return `${local} (${tz})`;
+}
+/** True for full ISO datetime strings (with a `T` and time component), e.g. "2026-08-14T16:00:00Z".
+ * Plain dates ("2026-08-15") are intentionally excluded — they are user-supplied calendar
+ * dates, not UTC timestamps, and should not be shifted.
+ */
+export function isIsoDateTime(value) {
+    return typeof value === 'string' && /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/.test(value);
+}
+/** Recursively walk a value and, for every ISO-datetime field, append a `<field>_local`
+ * companion with the local-tz rendering. The original ISO value is preserved.
+ */
+export function withLocalTimes(value, tz = DEFAULT_TZ) {
+    if (Array.isArray(value)) {
+        return value.map((item) => withLocalTimes(item, tz));
+    }
+    if (value && typeof value === 'object') {
+        const out = {};
+        for (const [key, raw] of Object.entries(value)) {
+            out[key] = withLocalTimes(raw, tz);
+            if (isIsoDateTime(raw)) {
+                out[`${key}_local`] = formatLocalDateTime(raw, tz);
+            }
+        }
+        return out;
+    }
+    return value;
+}

package/dist/index.js

@@ -13,6 +13,7 @@ import { DEFAULT_SERVER_URL } from './core/defaults.js';
 import { forgetInstallation, readInstallations, recordInstallation, replaceInstallations, } from './core/installations.js';
 import { findWorkspaceRoot } from './core/paths.js';
 import { initProjectStore } from './core/store.js';
+import { withLocalTimes } from './core/time.js';
 import { cliVersion } from './core/version.js';
 import { loginWithWeb } from './core/web-auth.js';
 import { installClaude, installCodex, installCursor, installKiro, installQoder, uninstallClaude, uninstallCodex, uninstallCursor, uninstallKiro, uninstallQoder, } from './installers/agents.js';
@@ -24,6 +25,7 @@ program
     .description('OpenTurtle collaboration, knowledge, meeting, and local agent CLI')
     .version(cliVersion());
 program.option('-j, --json', 'emit machine-readable JSON, including errors');
+program.option('-l, --local-time', '为日期时间字段追加 *_local 本地时区渲染 (默认输出 UTC ISO 不变)');
 program
     .command('update')
     .description('check npm for a newer CLI and install it')
@@ -435,6 +437,9 @@ function expandTargets(target) {
     return [target];
 }
 function print(value, asJson = true) {
+    if (program.opts().localTime) {
+        value = withLocalTimes(value);
+    }
     if (asJson) {
         process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
         return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openturtle/cli",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "description": "OpenTurtle collaboration, knowledge, meeting, and agent CLI",
   "keywords": [
     "openturtle",

package/skill/openturtle-cli/SKILL.md

@@ -29,10 +29,11 @@ ot --json doctor
 1. 已知项目和语料边界时，直接执行一次 `context get`。把用户问题拆成 2-6 个自然业务短句，用可重复的 `--query` 一次提交；默认 `--limit 20`，不要先用更大 limit 再缩小重跑。不得把内部实验编号、工作包代号或机器 ID 当成用户必须知道的检索口令，也不要在系统提示或示例中枚举当前项目的实际代号。内部追踪键只放在来源或审计字段；标题包含追踪键时，正文略去该前缀并使用自然业务名称。
 2. 普通综合问答最多执行 2 次 OpenTurtle 业务读取。第二次只能是一次定向 `context get` 或一个已知 ID 的 `show`，不能再展开全量 `goals/todos/worklogs/knowledge/meetings list` 查询链。
 3. 两次读取后仍缺信息时，明确写“未召回”及缺失项并停止。不要为了让答案看起来完整而继续搜索。
-4. 普通回答禁止使用 `--trace`、`--include-candidates`、全量对象列表和全量 WorkLog。`trace` 只用于用户明确要求审计召回或诊断缺失；一次诊断只运行一个 trace 查询。
-5. 机器 ID 在命令和来源中必须完整复制，不得截断、缩写或凭记忆重写。聚合结果已经覆盖用户问题时立即作答。
-6. 普通项目综合问答以 60 秒内完成为目标。项目解析完成后优先只做一次 Context 读取；只有缺失事实会实质改变答案时才做第二次定向读取，不为扩写背景或增加篇幅补查。
-7. 作答前做一次展示层检查：除来源中的机器 ID 外，标题、段落、小标题、列表和来源标签都不得出现仅用于追踪的编号或代号。原始标题或摘要带追踪前缀时，按对象类型和业务内容改述；无法确定自然名称时使用对象类型加内容摘要，不得原样复制追踪键。
+4. 聚合响应带 `evidence_confidence` 字段，按语义使用，不要把它当成拒答开关：`strong` 正常作答；`weak` 可以作答，但标注证据偏弱；`none` 表示没有强直接证据——先按第 2 条做一次定向补查，仍无强证据时，区分两种情形：问题所问事物明显不存在（语料中没有任何相关记录）时，明确回答“未找到/未召回”并停止；语料中存在弱相关记录时，基于这些记录作答，同时显式列出证据缺口和不确定性，不得编造弱证据不支持的内容。
+5. 普通回答禁止使用 `--trace`、`--include-candidates`、全量对象列表和全量 WorkLog。`trace` 只用于用户明确要求审计召回或诊断缺失；一次诊断只运行一个 trace 查询。
+6. 机器 ID 在命令和来源中必须完整复制，不得截断、缩写或凭记忆重写。聚合结果已经覆盖用户问题时立即作答。
+7. 普通项目综合问答以 60 秒内完成为目标。项目解析完成后优先只做一次 Context 读取；只有缺失事实会实质改变答案时才做第二次定向读取，不为扩写背景或增加篇幅补查。
+8. 作答前做一次展示层检查：除来源中的机器 ID 外，标题、段落、小标题、列表和来源标签都不得出现仅用于追踪的编号或代号。原始标题或摘要带追踪前缀时，按对象类型和业务内容改述；无法确定自然名称时使用对象类型加内容摘要，不得原样复制追踪键。
 
 ```bash
 ot context get --project <id> --snapshot <snapshot-id> \
@@ -66,7 +67,7 @@ ot worklogs list --project <id> --snapshot <snapshot-id> --scope team
 ## 写入规则
 
 - 所有结构化写入使用 `--body-file <json>` 或 `--body-file -`，避免 shell 转义损坏内容。
-- 先执行同一命令的 `--dry-run`，检查 `request.path` 和 `request.body`；用户确认后再正式写入。
+- 先执行同一命令的 `--dry-run`，检查 `request.path`、`request.body`、`validation`（body schema 校验）和 `preview`（将创建/改成什么）；用户确认后再正式写入。用 `--show-schema` 查看写命令的 body 字段、必填项和示例。
 - 创建目标、Todo、正式决策/风险、提交审核、审核通过/驳回、确认会议项目更新前，必须展示明确草稿和影响。
 - 项目归属只能来自用户明确选择，或受管 Goal/Meeting 唯一解析出的项目；无法唯一确定时停止写入并询问。
 - Knowledge 保存可长期复用的结论和完整会议纪要；短进展、决策、风险和产物引用写入 WorkLog。原始文件是 Knowledge 的来源材料，不是第二套知识系统。
@@ -127,14 +128,19 @@ ot knowledge attach <knowledge-id> ./artifact.pdf --dry-run
 
 `ot knowledge search` 默认聚合云端知识和本地索引；仅查一侧时显式使用 `--cloud-only` 或 `--local-only`。本地知识由 CLI 维护，Desktop 知识库界面复用同一实现和原有数据目录。
 
+- **content 是对象不是字符串**：`ot knowledge save` 的 body 里 `content` 是对象（如 `{"title":"...","body":"...","summary":"..."}`）；`title`/`body` 必须放在 `content` 内，放在 body 顶层会被忽略。无 id = POST 新建；`save <id>` = PATCH 更新（可改 `content`/`metadata_`/`status`/`kind`，merge 语义）。
+- `ot knowledge show <id>` 顶层 `title`/`summary` 已从 content 提升，正文在 `content.body`；团队记忆索引的短 id（前缀）可直接喂给 `show`，多义时后端返回 409。
+- 推进 draft→validated：`ot knowledge review <id> --approve`（等价 `save <id> --body-file '{"status":"validated"}'`；knowledge 无独立审核流，仅状态推进）。
+
 ## Meeting
 
 1. 先解析 Project、Roster 和 Project Context。
 2. 上传录音或读取已有 Meeting；区分事实、讨论、建议、已确认决策和不确定负责人。
-3. 用 `ot meetings publish <meeting-id> --dry-run` 将完整纪要发布为 `kind=meeting` Knowledge。
+3. 用 `ot meetings publish <meeting-id> --dry-run` 将完整纪要发布为 `kind=meeting` Knowledge。**publish 会自动按 kind 物化**项目更新候选（decision/risk→WorkLog，action/research→Todo，负责人自动指派），无需手动创建产物。
 4. 用 `ot meetings updates list <meeting-id>` 展示 action、research、decision、risk 草稿，允许逐条编辑或忽略。
-5. 只有用户确认具体条目后，才用 `ot meetings updates confirm <meeting-id> <update-id...> --knowledge <knowledge-id> --dry-run` 物化；没有已保存的 meeting Knowledge ID 时不得确认。
+5. 用 `ot meetings updates confirm <meeting-id> <update-id...> --knowledge <knowledge-id> --dry-run` **幂等确认**：已物化的候选返回 `already_materialized`（不重复创建），仅草稿态首次物化；`--all` 确认全部剩余草稿。没有已保存的 meeting Knowledge ID 时不得确认。
 6. 同一候选只走一次物化路径，禁止重复创建 Todo 或 WorkLog。
+7. 会议 decision/risk 候选物化为 WorkLog（进入时间线）；如需可检索的正式决策，另用 `ot decisions create` 沉淀为 `kind=decision` Knowledge，目标用 `ot goals`。`ot knowledge show <短id>` 支持团队记忆索引里的短 id 前缀。
 
 ## Desktop 边界