@openturtle/cli 0.3.7 → 0.4.0

package/README.md

@@ -56,6 +56,9 @@ ot knowledge search "部署"
 ot knowledge local search "部署"
 ot meetings list --project <project-id>
 ot work summary --project <project-id>
+ot worklogs show <worklog-id>
+ot worklogs list --project <project-id> --to <iso-time> --scope team
+ot context get --project <project-id> --query "本周风险" --trace --include-candidates
 ot worklogs record --summary "完成联调" --type progress --todo <todo-id>
 ot report draft --today
 ```
@@ -95,6 +98,30 @@ ot knowledge search "日报" --local-only
 ot knowledge local search "日报"
 ```
 
+需要可重复的服务端语料边界时，使用带时区的 `--as-of` 或不可变快照：
+
+```bash
+ot knowledge search "日报" --project <project-id> --as-of 2026-07-27T07:28:32Z
+ot context get --project <project-id> --query "E1-X1" --snapshot <snapshot-id> --trace --include-candidates
+```
+
+使用 `--as-of`、`--snapshot` 或任一排除参数时，聚合搜索只返回服务端云端结果，避免无版本边界的本地索引混入；这类参数不能与 `--local-only` 同时使用。
+
+### 导出不可变项目快照
+
+创建快照是写操作，先检查 dry-run：
+
+```bash
+ot projects snapshot export <project-id> \
+  --as-of 2026-07-27T07:28:32Z \
+  --exclude-tag evaluation-artifact \
+  --dry-run
+ot projects snapshot list --project <project-id>
+ot projects snapshot show <snapshot-id>
+```
+
+快照包含捕获策略、对象版本时间、逐对象内容哈希和 manifest hash。创建后不能更新或删除。
+
 ### 上传录音并处理会议
 
 ```bash
@@ -360,9 +387,33 @@ ot roster list --project <project-id>
 ot work summary --project <project-id>
 ot digest get --project <project-id> --window this_week
 ot context get --project <project-id> --query "本周风险" --section risk
+ot context get --project <project-id> --query "E1-X1" --trace --include-candidates
+ot context get --project <project-id> --query "E1-X1" --snapshot <snapshot-id> --trace
 ot context item meeting <meeting-id> --project <project-id>
 ```
 
+可重复读取边界：
+
+```bash
+ot goals list --project <project-id> --as-of 2026-07-27T07:28:32Z
+ot todos list --project <project-id> --exclude-tag evaluation-artifact
+ot worklogs list --project <project-id> --exclude-id <worklog-id> --scope team
+ot meetings list --project <project-id> --snapshot <snapshot-id>
+ot knowledge search "关键词" --project <project-id> --snapshot <snapshot-id>
+```
+
+`--exclude-id`、`--exclude-type` 和 `--exclude-tag` 可重复传入。`--snapshot` 与 `--as-of` 或任一排除参数互斥；非法组合会在 CLI 和服务端分别快速失败。服务端 `as_of` 采用保守语义：对象必须在边界前创建且最后更新时间不晚于边界，WorkLog 的 `occurred_at` 也必须不晚于边界。
+
+项目快照：
+
+```bash
+ot projects snapshot export <project-id> --as-of <iso-time> --exclude-tag evaluation-artifact --dry-run
+ot projects snapshot list --project <project-id> --page 1 --page-size 20
+ot projects snapshot show <snapshot-id>
+```
+
+`snapshot export` 会持久化不可变 corpus，因此属于写操作；Agent 必须先展示 dry-run，并在用户确认后才执行正式创建。`show` 会返回完整 manifest/corpus，`list` 只返回摘要。
+
 目标：
 
 ```bash
@@ -387,6 +438,8 @@ ot todos submit-review <todo-id> --body-file review-submission.json --dry-run
 ot todos review <todo-id> --body-file review-decision.json --dry-run
 ```
 
+Todo 响应的顶层 typed 字段是当前 canonical 值。机器消费者应读取 `field_schema_version`、`canonical_fields` 和 `metadata_precedence`；`legacy_metadata` 仅保留历史兼容，`superseded_fields` 指明旧 metadata 键已被哪个顶层字段取代。不得把旧 `v0.4` 或 `J0`-`J9` metadata 当成当前验收标准。
+
 知识对象：
 
 ```bash
@@ -419,7 +472,7 @@ ot knowledge local update <asset-id> --body-file local-note.json --dry-run
 ot knowledge local remove <asset-id> --dry-run
 ```
 
-`ot knowledge search` 返回 `{ query, cloud, local }` 聚合结果；`--cloud-only` 和 `--local-only` 可限定范围。知识对象是可复用的结论、规范、经验、决策沉淀和操作手册。来源文件是知识背后的原文、附件或仓库文档，本地知识索引可脱离 Desktop 使用。
+`ot knowledge search` 返回 `{ query, cloud, local }` 聚合结果；`--cloud-only` 和 `--local-only` 可限定范围。知识对象是可复用的结论、规范、经验、决策沉淀和操作手册。来源文件是知识背后的原文、附件或仓库文档，本地知识索引可脱离 Desktop 使用。显式服务端边界会自动关闭本地聚合；边界参数与 `--local-only` 冲突时命令直接报错。
 
 会议：
 
@@ -445,12 +498,19 @@ ot meetings updates ignore <meeting-id> <update-id> --dry-run
 工作日志：
 
 ```bash
+ot worklogs show <worklog-id>
 ot worklogs list --today
+ot worklogs list --project <project-id> --to <iso-time> --scope team --page-size 100
+ot worklogs list --project <project-id> --window this_week --event-type progress
 ot worklogs record --summary "完成 Qoder CLI 接入验证" --type progress --todo <todo-id>
 ot worklogs record --summary "Codex CLI 登录需要用户确认" --type blocker
 ot worklogs create --body-file worklog.json --dry-run
 ```
 
+`worklogs list` 支持 `--project`、`--from`、`--to`、`--event-type`、`--scope team|managed|mine`、`--page` 和 `--page-size`。`--from` / `--to` 是包含边界，必须是带 `Z` 或 UTC offset 的 ISO 8601 时间。
+
+`--today` 等价于 `--window today`。窗口可选 `today`、`yesterday`、`this_week`、`last_week` 和 `this_month`；不传窗口即保持既有全量读取。日历边界按运行 CLI 的系统本地时区计算，再作为 UTC ISO 时间发送给服务端。`--today` / `--window` 不能和显式 `--from` / `--to` 混用。无效窗口、scope、时间和分页值会在请求前报错。
+
 结构化写操作统一支持 `--body-file <json>`，也可用 `--body-file -` 从 stdin 读取。建议先执行同一条命令的 `--dry-run`，确认 `request.path` 和 `request.body` 后再去掉该参数。
 
 只读 API 还提供受限逃生口，只允许 `/api/` 下的 GET：

package/dist/commands/collaboration.js

@@ -1,5 +1,6 @@
 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';
 export function createCollaborationCommands(client = new ApiClient()) {
     const mutate = async (method, path, body, dryRun = false) => {
         if (dryRun)
@@ -29,6 +30,9 @@ export function createCollaborationCommands(client = new ApiClient()) {
                 candidates: exact ? [] : items,
             };
         },
+        listProjectSnapshots: (projectId, options) => client.get(`/api/projects/${encodeURIComponent(projectId)}/snapshots`, listQuery(options)),
+        showProjectSnapshot: (snapshotId) => client.get(`/api/projects/snapshots/${encodeURIComponent(snapshotId)}`),
+        exportProjectSnapshot: (projectId, options, dryRun = false) => mutate('POST', `/api/projects/${encodeURIComponent(projectId)}/snapshots`, buildSnapshotExportBody(options), dryRun),
         async listRoster(teamId, projectId) {
             const team = teamId ? { id: teamId } : await client.get('/api/teams/me');
             const resolvedTeamId = String(team.id || teamId || '');
@@ -185,6 +189,20 @@ export function registerCollaborationCommands(program, groups, callbacks) {
     projects
         .command('resolve <query>')
         .action(action(async (query) => print(await commands.resolveProject(query))));
+    const snapshots = projects.command('snapshot').description('Immutable Project corpus snapshots');
+    addSnapshotPolicyOptions(snapshots.command('export <projectId>').option('--dry-run')).action(action(async (projectId, options) => print(await commands.exportProjectSnapshot(projectId, options, Boolean(options.dryRun)))));
+    snapshots
+        .command('show <snapshotId>')
+        .action(action(async (snapshotId) => print(await commands.showProjectSnapshot(snapshotId))));
+    snapshots
+        .command('list')
+        .requiredOption('--project <id>')
+        .option('--page <number>', 'page number', Number)
+        .option('--page-size <number>', 'items per page', Number)
+        .action(action(async (options) => print(await commands.listProjectSnapshots(options.project, {
+        page: options.page,
+        page_size: options.pageSize,
+    }))));
     program
         .command('roster')
         .description('Current team roster')
@@ -220,7 +238,7 @@ export function registerCollaborationCommands(program, groups, callbacks) {
         .option('--dry-run')
         .action(action(async (options) => print(await commands.runOrgSyncSynthesis(options, Boolean(options.dryRun)))));
     const context = program.command('context').description('Viewer-scoped project context');
-    context
+    addReadBoundaryOptions(context
         .command('get')
         .option('--project <id>')
         .option('--goal <id>')
@@ -230,7 +248,8 @@ export function registerCollaborationCommands(program, groups, callbacks) {
         .option('--match <mode>', 'any|all|exact', 'any')
         .option('--mode <mode>', 'brief|search', 'brief')
         .option('--limit <number>', 'maximum context items', Number)
-        .action(action(async (options) => print(await commands.resolveContext({
+        .option('--trace', 'include retrieval accounting')
+        .option('--include-candidates', 'include ranked candidate details')).action(action(async (options) => print(await commands.resolveContext({
         project_id: options.project,
         goal_id: options.goal,
         person_id: options.person,
@@ -239,6 +258,9 @@ export function registerCollaborationCommands(program, groups, callbacks) {
         match_mode: options.match,
         mode: options.mode,
         limit: options.limit,
+        trace: options.trace,
+        include_candidates: options.includeCandidates,
+        ...buildReadBoundaryQuery(options),
     }))));
     context
         .command('item <sourceType> <sourceId>')
@@ -275,17 +297,17 @@ export function registerCollaborationCommands(program, groups, callbacks) {
         .option('--dry-run')
         .action(action(async (knowledgeId, attachmentId, options) => print(await commands.downloadKnowledgeAttachment(knowledgeId, attachmentId, options.output, Boolean(options.force), Boolean(options.dryRun)))));
     const meetings = program.command('meetings').description('Meeting upload, minutes, knowledge, and project updates');
-    meetings
+    addReadBoundaryOptions(meetings
         .command('list')
         .option('--project <id>')
         .option('--status <status>')
         .option('--page <number>', 'page number', Number)
-        .option('--page-size <number>', 'items per page', Number)
-        .action(action(async (options) => print(await commands.listMeetings({
+        .option('--page-size <number>', 'items per page', Number)).action(action(async (options) => print(await commands.listMeetings({
         project_id: options.project,
         status: options.status,
         page: options.page,
         page_size: options.pageSize,
+        ...buildReadBoundaryQuery(options),
     }))));
     meetings
         .command('show <meetingId>')

package/dist/commands/local-knowledge.js

@@ -54,10 +54,19 @@ export function createLocalKnowledgeCommands(root = localKnowledgeStoreRoot()) {
 export async function searchKnowledgeEverywhere(query, options, fetchCloud, root = localKnowledgeStoreRoot()) {
     if (options.cloudOnly && options.localOnly)
         throw new Error('Use --cloud-only or --local-only, not both');
+    const hasServerBoundary = Boolean(options.asOf ||
+        options.snapshot ||
+        asStringArray(options.excludeId).length ||
+        asStringArray(options.excludeType).length ||
+        asStringArray(options.excludeTag).length);
+    if (hasServerBoundary && options.localOnly) {
+        throw new Error('Server read-boundary options cannot be combined with --local-only because the local index has no matching corpus boundary');
+    }
+    const cloudOnly = Boolean(options.cloudOnly || hasServerBoundary);
     const local = createLocalKnowledgeCommands(root);
     const [cloudResult, localResult] = await Promise.all([
         options.localOnly ? Promise.resolve(null) : fetchCloud(),
-        options.cloudOnly
+        cloudOnly
             ? Promise.resolve(null)
             : local.search(query, Number(options.limit) || 20, normalizeMatchMode(options.match)),
     ]);
@@ -67,6 +76,9 @@ export async function searchKnowledgeEverywhere(query, options, fetchCloud, root
         local: localResult,
     };
 }
+function asStringArray(value) {
+    return Array.isArray(value) ? value.filter((item) => typeof item === 'string' && Boolean(item)) : [];
+}
 export function registerLocalKnowledgeCommands(knowledge, callbacks) {
     const commands = createLocalKnowledgeCommands();
     const local = knowledge.command('local').description('Local indexed knowledge available without Desktop');

package/dist/commands/read-boundary.js

@@ -0,0 +1,80 @@
+import { collectOption } from '../core/input.js';
+const READ_OBJECT_TYPES = ['goal', 'todo', 'work_log', 'meeting', 'knowledge'];
+export function addReadBoundaryOptions(command) {
+    return addSnapshotPolicyOptions(command).option('--snapshot <id>', 'read exclusively from an immutable project snapshot');
+}
+export function addSnapshotPolicyOptions(command) {
+    return command
+        .option('--as-of <iso>', 'server-enforced ISO timestamp with timezone')
+        .option('--exclude-id <id>', 'repeatable object ID exclusion', collectOption, [])
+        .option('--exclude-type <type>', 'repeatable: goal|todo|work_log|meeting|knowledge', collectOption, [])
+        .option('--exclude-tag <tag>', 'repeatable tag exclusion', collectOption, []);
+}
+export function buildReadBoundaryQuery(options) {
+    const asOf = optionalIsoTimestamp(options.asOf, '--as-of');
+    const excludeId = uniqueStrings(options.excludeId);
+    const excludeType = uniqueStrings(options.excludeType);
+    const excludeTag = uniqueStrings(options.excludeTag);
+    for (const value of excludeType) {
+        if (!READ_OBJECT_TYPES.includes(value)) {
+            throw new Error(`Invalid --exclude-type "${value}". Expected one of: ${READ_OBJECT_TYPES.join(', ')}`);
+        }
+    }
+    if (options.snapshot && (asOf || excludeId.length || excludeType.length || excludeTag.length)) {
+        throw new Error('--snapshot cannot be combined with --as-of or exclusion options');
+    }
+    return compact({
+        as_of: asOf,
+        exclude_id: excludeId.length ? excludeId : undefined,
+        exclude_type: excludeType.length ? excludeType : undefined,
+        exclude_tag: excludeTag.length ? excludeTag : undefined,
+        snapshot_id: options.snapshot,
+    });
+}
+export function buildSnapshotExportBody(options) {
+    if (options.snapshot)
+        throw new Error('--snapshot is not valid when exporting a new snapshot');
+    const query = buildReadBoundaryQuery(options);
+    return compact({
+        as_of: query.as_of,
+        exclude_id: query.exclude_id,
+        exclude_type: query.exclude_type,
+        exclude_tag: query.exclude_tag,
+    });
+}
+function uniqueStrings(values) {
+    return [...new Set((values || []).map((value) => value.trim()).filter(Boolean))];
+}
+function optionalIsoTimestamp(value, name) {
+    if (value == null)
+        return undefined;
+    const match = value.match(/^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2})(?::(\d{2})(?:\.(\d{1,9}))?)?(Z|[+-]\d{2}:\d{2})$/);
+    if (!match)
+        throw new Error(`${name} must be an ISO 8601 timestamp with timezone`);
+    const [, yearText, monthText, dayText, hourText, minuteText, secondText = '0', , offset] = match;
+    const year = Number(yearText);
+    const month = Number(monthText);
+    const day = Number(dayText);
+    const hour = Number(hourText);
+    const minute = Number(minuteText);
+    const second = Number(secondText);
+    const maxDay = month >= 1 && month <= 12 ? new Date(Date.UTC(year, month, 0)).getUTCDate() : 0;
+    const offsetParts = offset === 'Z' ? [0, 0] : offset.slice(1).split(':').map(Number);
+    if (year < 1 ||
+        month < 1 ||
+        month > 12 ||
+        day < 1 ||
+        day > maxDay ||
+        hour > 23 ||
+        minute > 59 ||
+        second > 59 ||
+        offsetParts[0] > 23 ||
+        offsetParts[1] > 59 ||
+        Number.isNaN(Date.parse(value))) {
+        throw new Error(`${name} must be a valid ISO 8601 timestamp with timezone`);
+    }
+    return value;
+}
+function compact(value) {
+    return Object.fromEntries(Object.entries(value).filter(([, item]) => item != null && item !== ''));
+}

package/dist/commands/resources.js

@@ -3,16 +3,34 @@ import path from 'node:path';
 import { ApiClient, listQuery } from '../core/api-client.js';
 import { readAuth } from '../core/auth.js';
 import { initProjectStore, listEvents } from '../core/store.js';
+import { buildReadBoundaryQuery } from './read-boundary.js';
 export function createResourceCommands(client = new ApiClient()) {
     return {
         async listGoals(options) {
-            return client.get('/api/goals', listQuery(options));
+            return client.get('/api/goals', listQuery({
+                project_id: options.project_id || options.project,
+                mine: options.mine,
+                status: options.status,
+                scope: options.scope,
+                role: options.role,
+                page: options.page,
+                page_size: options.pageSize || options.page_size,
+                ...buildReadBoundaryQuery(options),
+            }));
         },
         async showGoal(goalId) {
             return client.get(`/api/goals/${encodeURIComponent(goalId)}`);
         },
         async listTodos(options) {
-            return client.get('/api/todos', listQuery(options));
+            return client.get('/api/todos', listQuery({
+                project_id: options.project_id || options.project,
+                mine: options.mine,
+                status: options.status,
+                scope: options.scope,
+                page: options.page,
+                page_size: options.pageSize || options.page_size,
+                ...buildReadBoundaryQuery(options),
+            }));
         },
         async showTodo(todoId) {
             return client.get(`/api/todos/${encodeURIComponent(todoId)}`);
@@ -48,6 +66,7 @@ export function createResourceCommands(client = new ApiClient()) {
                 person: options.person,
                 scope: options.scope,
                 limit: options.limit,
+                ...buildReadBoundaryQuery(options),
             }));
         },
         async listKnowledgeSources(options) {
@@ -59,6 +78,9 @@ export function createResourceCommands(client = new ApiClient()) {
         async listWorklogs(options) {
             return client.get('/api/work-logs', listQuery(options));
         },
+        async showWorklog(workLogId) {
+            return client.get(`/api/work-logs/${encodeURIComponent(workLogId)}`);
+        },
         async recordWorklog(summary, type = 'note', references = {}) {
             return client.post('/api/work-logs', {
                 ...(references.project ? { project_id: references.project } : {}),
@@ -99,6 +121,7 @@ function knowledgeQuery(options) {
         person: options.person,
         page: options.page,
         page_size: options.pageSize,
+        ...buildReadBoundaryQuery(options),
     });
 }
 export function draftDailyReport(workspace, options = {}) {

package/dist/commands/worklogs.js

@@ -0,0 +1,118 @@
+const WORKLOG_SCOPES = ['team', 'managed', 'mine'];
+const WORKLOG_WINDOWS = ['today', 'yesterday', 'this_week', 'last_week', 'this_month'];
+export function buildWorklogListQuery(options, now = new Date()) {
+    const scope = optionalEnum(options.scope, '--scope', WORKLOG_SCOPES);
+    const page = optionalInteger(options.page, '--page', 1);
+    const pageSize = optionalInteger(options.pageSize, '--page-size', 1, 100);
+    const dateFrom = optionalIsoTimestamp(options.from, '--from');
+    const dateTo = optionalIsoTimestamp(options.to, '--to');
+    if (options.today && options.window) {
+        throw new Error('--today cannot be combined with --window');
+    }
+    const window = options.today ? 'today' : optionalEnum(options.window, '--window', WORKLOG_WINDOWS);
+    if (window && (dateFrom || dateTo)) {
+        throw new Error('--today/--window cannot be combined with --from or --to');
+    }
+    if (dateFrom && dateTo && Date.parse(dateFrom) > Date.parse(dateTo)) {
+        throw new Error('--from must be earlier than or equal to --to');
+    }
+    const windowRange = window ? worklogWindowRange(window, now) : {};
+    return compactQuery({
+        ...buildReadBoundaryQuery(options),
+        project_id: options.project,
+        date_from: windowRange.date_from ?? dateFrom,
+        date_to: windowRange.date_to ?? dateTo,
+        event_type: options.eventType,
+        scope,
+        page,
+        page_size: pageSize,
+    });
+}
+export function worklogWindowRange(window, now = new Date()) {
+    const year = now.getFullYear();
+    const month = now.getMonth();
+    const day = now.getDate();
+    const today = new Date(year, month, day);
+    let start;
+    let next;
+    if (window === 'today') {
+        start = today;
+        next = new Date(year, month, day + 1);
+    }
+    else if (window === 'yesterday') {
+        start = new Date(year, month, day - 1);
+        next = today;
+    }
+    else if (window === 'this_week') {
+        const mondayOffset = (today.getDay() + 6) % 7;
+        start = new Date(year, month, day - mondayOffset);
+        next = new Date(year, month, day - mondayOffset + 7);
+    }
+    else if (window === 'last_week') {
+        const mondayOffset = (today.getDay() + 6) % 7;
+        start = new Date(year, month, day - mondayOffset - 7);
+        next = new Date(year, month, day - mondayOffset);
+    }
+    else {
+        start = new Date(year, month, 1);
+        next = new Date(year, month + 1, 1);
+    }
+    return {
+        date_from: start.toISOString(),
+        date_to: inclusiveMicrosecondBefore(next),
+    };
+}
+function optionalIsoTimestamp(value, name) {
+    if (value == null)
+        return undefined;
+    const match = value.match(/^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2})(?::(\d{2})(?:\.(\d{1,9}))?)?(Z|[+-]\d{2}:\d{2})$/);
+    if (!match)
+        throw new Error(`${name} must be an ISO 8601 timestamp with timezone`);
+    const [, yearText, monthText, dayText, hourText, minuteText, secondText = '0', , offset] = match;
+    const year = Number(yearText);
+    const month = Number(monthText);
+    const day = Number(dayText);
+    const hour = Number(hourText);
+    const minute = Number(minuteText);
+    const second = Number(secondText);
+    const maxDay = month >= 1 && month <= 12 ? new Date(Date.UTC(year, month, 0)).getUTCDate() : 0;
+    const offsetParts = offset === 'Z' ? [0, 0] : offset.slice(1).split(':').map(Number);
+    if (year < 1 ||
+        month < 1 ||
+        month > 12 ||
+        day < 1 ||
+        day > maxDay ||
+        hour > 23 ||
+        minute > 59 ||
+        second > 59 ||
+        offsetParts[0] > 23 ||
+        offsetParts[1] > 59 ||
+        Number.isNaN(Date.parse(value))) {
+        throw new Error(`${name} must be a valid ISO 8601 timestamp with timezone`);
+    }
+    return value;
+}
+function optionalInteger(value, name, minimum, maximum) {
+    if (value == null)
+        return undefined;
+    if (!Number.isInteger(value) || value < minimum || (maximum != null && value > maximum)) {
+        const range = maximum == null ? `at least ${minimum}` : `between ${minimum} and ${maximum}`;
+        throw new Error(`${name} must be an integer ${range}`);
+    }
+    return value;
+}
+function optionalEnum(value, name, allowed) {
+    if (value == null)
+        return undefined;
+    if (!allowed.includes(value)) {
+        throw new Error(`Invalid ${name} "${value}". Expected one of: ${allowed.join(', ')}`);
+    }
+    return value;
+}
+function compactQuery(query) {
+    return Object.fromEntries(Object.entries(query).filter(([, value]) => value != null && value !== ''));
+}
+function inclusiveMicrosecondBefore(value) {
+    return new Date(value.getTime() - 1).toISOString().replace(/\.999Z$/, '.999999Z');
+}
+import { buildReadBoundaryQuery } from './read-boundary.js';

package/dist/index.js

@@ -4,6 +4,8 @@ import { Command } from 'commander';
 import { registerCollaborationCommands } from './commands/collaboration.js';
 import { registerLocalKnowledgeCommands, searchKnowledgeEverywhere } from './commands/local-knowledge.js';
 import { doctor, draftDailyReport, createResourceCommands } from './commands/resources.js';
+import { addReadBoundaryOptions } from './commands/read-boundary.js';
+import { buildWorklogListQuery } from './commands/worklogs.js';
 import { ApiClient, ApiError } from './core/api-client.js';
 import { scheduleAutomaticUpdate, updateCli } from './core/auto-update.js';
 import { clearAuth, readAuth, redactToken, writeAuth } from './core/auth.js';
@@ -152,25 +154,23 @@ program
 }));
 const resources = createResourceCommands();
 const goals = program.command('goals');
-goals
-    .command('list')
-    .option('--project <id>')
-    .option('--mine')
-    .option('--status <status>')
-    .option('--json')
-    .action(action(async (options) => print(await resources.listGoals({ project_id: options.project, mine: options.mine, status: options.status }), options.json)));
+addReadBoundaryOptions(goals.command('list').option('--project <id>').option('--mine').option('--status <status>').option('--json')).action(action(async (options) => print(await resources.listGoals({
+    project_id: options.project,
+    mine: options.mine,
+    status: options.status,
+    ...readBoundaryOptions(options),
+}), options.json)));
 goals
     .command('show <goalId>')
     .option('--json')
     .action(action(async (goalId, options) => print(await resources.showGoal(goalId), options.json)));
 const todos = program.command('todos');
-todos
-    .command('list')
-    .option('--project <id>')
-    .option('--mine')
-    .option('--status <status>')
-    .option('--json')
-    .action(action(async (options) => print(await resources.listTodos({ project_id: options.project, mine: options.mine, status: options.status }), options.json)));
+addReadBoundaryOptions(todos.command('list').option('--project <id>').option('--mine').option('--status <status>').option('--json')).action(action(async (options) => print(await resources.listTodos({
+    project_id: options.project,
+    mine: options.mine,
+    status: options.status,
+    ...readBoundaryOptions(options),
+}), options.json)));
 todos
     .command('show <todoId>')
     .option('--json')
@@ -212,7 +212,7 @@ todos
     print(await resources.updateTodoProgress(todoId, options.message));
 }));
 const knowledge = program.command('knowledge');
-knowledge
+addReadBoundaryOptions(knowledge
     .command('list')
     .option('--project <id>')
     .option('--q <keyword>')
@@ -222,13 +222,12 @@ knowledge
     .option('--person <name-or-id>')
     .option('--page <number>', 'page number', Number)
     .option('--page-size <number>', 'items per page', Number)
-    .option('--json')
-    .action(action(async (options) => print(await resources.listKnowledge(options), options.json)));
+    .option('--json')).action(action(async (options) => print(await resources.listKnowledge(options), options.json)));
 knowledge
     .command('show <knowledgeId>')
     .option('--json')
     .action(action(async (knowledgeId, options) => print(await resources.showKnowledge(knowledgeId), options.json)));
-knowledge
+addReadBoundaryOptions(knowledge
     .command('search <keyword>')
     .option('--project <id>')
     .option('--person <name-or-id>')
@@ -237,8 +236,7 @@ knowledge
     .option('--match <mode>', 'local match mode: any|all|exact', 'any')
     .option('--cloud-only')
     .option('--local-only')
-    .option('--json')
-    .action(action(async (keyword, options) => print(await searchKnowledgeEverywhere(keyword, options, () => resources.searchKnowledge(keyword, options)), options.json)));
+    .option('--json')).action(action(async (keyword, options) => print(await searchKnowledgeEverywhere(keyword, options, () => resources.searchKnowledge(keyword, options)), options.json)));
 knowledge
     .command('sources')
     .option('--path <path>')
@@ -269,12 +267,22 @@ program
     project: options.project,
 }), options.json)));
 const worklogs = program.command('worklogs');
-worklogs
+addReadBoundaryOptions(worklogs
     .command('list')
-    .option('--today')
-    .option('--window <window>')
+    .option('--project <id>')
+    .option('--from <iso>', 'inclusive ISO timestamp with timezone')
+    .option('--to <iso>', 'inclusive ISO timestamp with timezone')
+    .option('--event-type <type>')
+    .option('--scope <scope>', 'team|managed|mine')
+    .option('--page <number>', 'page number', Number)
+    .option('--page-size <number>', 'items per page (1-100)', Number)
+    .option('--today', 'current local calendar day')
+    .option('--window <window>', 'today|yesterday|this_week|last_week|this_month')
+    .option('--json')).action(action(async (options) => print(await resources.listWorklogs(buildWorklogListQuery(options)), options.json)));
+worklogs
+    .command('show <workLogId>')
     .option('--json')
-    .action(action(async (options) => print(await resources.listWorklogs(options), options.json)));
+    .action(action(async (workLogId, options) => print(await resources.showWorklog(workLogId), options.json)));
 worklogs
     .command('record')
     .option('--summary <text>')
@@ -412,6 +420,15 @@ function requireOption(value, name) {
         throw new Error(`Missing required option ${name}`);
     }
 }
+function readBoundaryOptions(options) {
+    return {
+        asOf: options.asOf,
+        excludeId: options.excludeId,
+        excludeType: options.excludeType,
+        excludeTag: options.excludeTag,
+        snapshot: options.snapshot,
+    };
+}
 function expandTargets(target) {
     if (target === 'all')
         return ['claude', 'codex', 'cursor', 'qoder', 'kiro'];

package/package.json

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

package/skill/openturtle-cli/SKILL.md

@@ -24,11 +24,20 @@ ot --json doctor
 
 1. 用 `ot projects list` 或 `ot projects resolve <query>` 定位项目。
 2. 用 `ot roster list --project <id>` 解析成员；先匹配 canonical `display_name`，再参考 aliases 和项目角色，重名或无法唯一匹配时询问用户。
-3. 用 `ot context get --project <id> --query <term>` 获取项目上下文；复杂问题拆成少量明确查询词。
-4. 按对象读取：`ot work summary`、`ot goals list/show`、`ot todos list/show`、`ot knowledge list/show/search`、`ot knowledge local list/search/read`、`ot meetings list/show/transcript/minutes/participants`、`ot worklogs list`。
+3. 用 `ot context get --project <id> --query <term>` 获取项目上下文；复杂问题拆成少量明确查询词。需要审计召回时加 `--trace --include-candidates`。
+4. 按对象读取：`ot work summary`、`ot goals list/show`、`ot todos list/show`、`ot knowledge list/show/search`、`ot knowledge local list/search/read`、`ot meetings list/show/transcript/minutes/participants`、`ot worklogs list/show`。
 5. 记录 Todo 执行进展时优先使用 `ot worklogs record --summary "..." --type progress --todo <todo-id>`，可同时传 `--project` / `--goal`，不要只把关联 ID 塞进 metadata。
 6. 高层命令缺失时才使用只读逃生口 `ot request get /api/...`。
 
+需要可重复语料边界时，优先让服务端执行，不要先全量读取再用 `jq` 猜边界：
+
+```bash
+ot context get --project <id> --query <term> --as-of <iso> --exclude-tag evaluation-artifact --trace
+ot worklogs list --project <id> --snapshot <snapshot-id> --scope team
+```
+
+`--exclude-id`、`--exclude-type`、`--exclude-tag` 可重复传入。`--snapshot` 与 `--as-of` 或任一排除参数互斥，非法组合必须报错。显式边界下 `knowledge search` 只使用云端语料；边界参数不能与 `--local-only` 混用。
+
 ## 写入规则
 
 - 所有结构化写入使用 `--body-file <json>` 或 `--body-file -`，避免 shell 转义损坏内容。
@@ -43,6 +52,8 @@ Todo 草稿至少包含来源、范围/环境、2-5 个行动步骤、可判断
 
 `ot goals` 管理 OpenTurtle 团队/项目目标。当前 Agent 会话的 Goal 使用 Provider 官方 `/goal` 命令；不要将会话 Goal 写入 OpenTurtle 项目目标，也不要尝试同步两者状态。
 
+读取 Todo 时以顶层 typed 字段为 canonical。`field_schema_version`、`canonical_fields` 和 `metadata_precedence` 是机器契约；`legacy_metadata` 只用于审计历史，`superseded_fields` 标明旧键的替代字段。不得把旧 `v0.4` 或 `J0`-`J9` metadata 当成当前验收标准。
+
 ```bash
 ot goals create --body-file goal.json --dry-run
 ot todos create --body-file todo.json --dry-run
@@ -51,6 +62,30 @@ ot todos submit-review <todo-id> --body-file review.json --dry-run
 ot todos review <todo-id> --body-file decision.json --dry-run
 ```
 
+## WorkLog
+
+优先使用结构化读命令，不要用全量 `worklogs list` 后在客户端猜项目或时间范围。读取单条记录用 `ot worklogs show <worklog-id>`；项目历史或快照前数据使用服务端过滤：
+
+```bash
+ot worklogs list --project <project-id> --to <iso-time> --scope team --page-size 100
+ot worklogs list --project <project-id> --window this_week --event-type progress
+```
+
+`--today` 等价于 `--window today`。日历窗口按运行 CLI 的系统本地时区计算；精确截止时间必须使用带时区的 `--from` / `--to`。窗口参数不能与显式时间边界混用，无效窗口、scope、时间和分页值会直接报错。
+
+## Project Snapshot 与 Context Trace
+
+项目快照是持久化写操作，必须先 dry-run 并经用户确认；列表和读取是只读：
+
+```bash
+ot projects snapshot export <project-id> --as-of <iso> --exclude-tag evaluation-artifact --dry-run
+ot projects snapshot list --project <project-id>
+ot projects snapshot show <snapshot-id>
+ot context get --project <project-id> --query <term> --snapshot <snapshot-id> --trace --include-candidates
+```
+
+快照建立后不可更新或删除。`trace` 返回候选数、选中/遗漏数、rank、score、匹配原因和截断信息；需要判断关系链稳定性时，应使用明确查询词并检查结构化关联理由，不能把一次召回当成稳定修复。
+
 ## Knowledge
 
 保存前展示标题、摘要、正文范围、Project/Goal、来源 URL、附件和上下文引用。只有用户明确选择并确认的结论才能沉淀；不得自动上传或持久化 Desktop 既有会话历史。