@openturtle/cli 0.3.7 → 0.4.1

package/README.md

@@ -56,12 +56,17 @@ 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 "本周风险"
 ot worklogs record --summary "完成联调" --type progress --todo <todo-id>
 ot report draft --today
 ```
 
 `ot install` 只安装 CLI 使用指引。Agent 直接执行 `ot ... --json`，不需要 MCP 或 Hook。
 
+普通项目综合问答优先使用一次聚合 `context get`，最多再做一次定向补查。日常回答不要使用 `--trace`、`--include-candidates`、`--help` 或全量对象列表；两次读取后仍缺信息时应明确标记“未召回”并停止。`trace` 只用于召回审计和故障诊断。
+
 ## 常用场景
 
 ### 看我的待办
@@ -95,6 +100,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 "上次回读验收还有什么缺口" --snapshot <snapshot-id>
+```
+
+使用 `--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 +389,34 @@ 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 "上次回读验收还有什么缺口" --snapshot <snapshot-id>
+# 仅在诊断召回时使用：
+ot context get --project <project-id> --query "上次回读验收还有什么缺口" --trace --include-candidates
 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 +441,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 +475,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 +501,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,18 @@
 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';
+const PROJECT_ACTIVE_TODO_STATUSES = ['draft', 'pending', 'in_progress', 'pending_review', 'failed'];
+function withProjectTodoSummary(project) {
+    const byStatus = project.todo_stats?.by_status;
+    const projectActiveTodoCount = byStatus
+        ? PROJECT_ACTIVE_TODO_STATUSES.reduce((total, status) => total + Number(byStatus[status] || 0), 0)
+        : null;
+    return {
+        ...project,
+        active_todo_count_scope: 'current_user',
+        project_active_todo_count: projectActiveTodoCount,
+    };
+}
 export function createCollaborationCommands(client = new ApiClient()) {
     const mutate = async (method, path, body, dryRun = false) => {
         if (dryRun)
@@ -19,9 +32,10 @@ export function createCollaborationCommands(client = new ApiClient()) {
             const response = await client.get('/api/projects', {
                 keyword: query,
                 activated_only: false,
+                include_todo_stats: true,
                 page_size: 100,
             });
-            const items = Array.isArray(response) ? response : response.items || [];
+            const items = (Array.isArray(response) ? response : response.items || []).map((item) => withProjectTodoSummary(item));
             const exact = items.find((item) => item.id === query || String(item.name || '').toLowerCase() === query.toLowerCase());
             return {
                 resolved: Boolean(exact),
@@ -29,6 +43,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 +202,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 +251,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 +261,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 +271,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 +310,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/dist/installers/agents.js

@@ -25,7 +25,8 @@ export function installCursor(options) {
         '---',
         '',
         'Run OpenTurtle operations with the direct `ot ... --json` CLI. Do not use an OpenTurtle MCP server or install OpenTurtle hooks.',
-        'Start with `command -v ot` and `ot --json doctor`; if authentication is missing, ask the user to run `ot auth login --web`.',
+        'On first use in a new execution environment, run `command -v ot` and `ot --json doctor`; do not repeat these checks in the same task.',
+        'For ordinary project synthesis, use OpenTurtle API data as the sole authority, start with one aggregated `ot context get` call using natural business-language queries, and allow at most one targeted follow-up. Never prime the request with project-specific tracking codes. Do not inspect repository files, Git state, or local agent memory. Before answering, remove tracking keys from prose and source labels; keep only machine IDs in citation or audit fields. New object titles and summaries must use natural business language, with tracking keys stored separately.',
         'Before a write, run the same command with `--dry-run` and inspect the request path and body.',
         'Todo quality: include source context, scope/environment, concrete steps, measurable acceptance criteria, and evidence. Ask one concise question when required information is unclear.',
         '',
@@ -41,7 +42,8 @@ export function installKiro(options) {
         '# OpenTurtle CLI',
         '',
         'Run OpenTurtle operations with the direct `ot ... --json` CLI. Do not use an OpenTurtle MCP server or install OpenTurtle hooks.',
-        'Start with `command -v ot` and `ot --json doctor`; if authentication is missing, ask the user to run `ot auth login --web`.',
+        'On first use in a new execution environment, run `command -v ot` and `ot --json doctor`; do not repeat these checks in the same task.',
+        'For ordinary project synthesis, use OpenTurtle API data as the sole authority, start with one aggregated `ot context get` call using natural business-language queries, and allow at most one targeted follow-up. Never prime the request with project-specific tracking codes. Do not inspect repository files, Git state, or local agent memory. Before answering, remove tracking keys from prose and source labels; keep only machine IDs in citation or audit fields. New object titles and summaries must use natural business language, with tracking keys stored separately.',
         'Before a write, run the same command with `--dry-run` and inspect the request path and body.',
         'Todo quality: include source context, scope/environment, concrete steps, measurable acceptance criteria, and evidence. Ask one concise question when required information is unclear.',
         '',
@@ -135,6 +137,7 @@ function appendAgentsSnippet(workspace) {
         '',
         'Use the direct `ot ... --json` CLI for OpenTurtle projects, goals, todos, knowledge, meetings, and worklogs. Do not use an OpenTurtle MCP server or install OpenTurtle hooks.',
         'Run `ot --json doctor` when authentication or server reachability is uncertain, and use `--dry-run` before writes.',
+        'For ordinary project synthesis, use OpenTurtle API data as the sole authority, use one aggregated `ot context get` call with natural business-language queries, and allow at most one targeted follow-up. Never prime the request with project-specific tracking codes. Do not inspect repository files, Git state, or local agent memory. Before answering, remove tracking keys from prose and source labels; keep only machine IDs in citation or audit fields. New object titles and summaries must use natural business language, with tracking keys stored separately.',
         'Todo quality: include source context, scope/environment, concrete steps, measurable acceptance criteria, and evidence. Ask one concise question when required information is unclear.',
         '',
         '<!-- /OPENTURTLE-CLI -->',

package/package.json

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

package/skill/openturtle-cli/SKILL.md

@@ -11,7 +11,7 @@ Desktop 会在隐藏系统上下文中注入已启用 Connector 的命令、能
 
 用户要求新增外部服务时，先准备符合 `schemaVersion: 1` 的 manifest，再调用 `openturtle-desktop` 的 `propose_connector`。该调用只提交待审批提案；用户必须在“扩展 > 连接器”批准，安装和写操作仍需单独确认。不得直接修改 Desktop 配置或 Connector 目录。
 
-开始前运行：
+每个新执行环境首次使用前运行；当前任务已经验证过后不要重复：
 
 ```bash
 command -v ot
@@ -20,15 +20,49 @@ ot --json doctor
 
 缺少登录态时让用户运行 `ot auth login --web`，不要索取或输出 token。Desktop 内置 Agent 会自动复用 Desktop 当前登录态、团队和项目上下文；独立终端使用 CLI 自己的登录配置。
 
+只读 OpenTurtle 业务问题以 OpenTurtle API 返回的 Project Context 和业务对象为唯一权威来源，不读取仓库源码、`CLAUDE.md`、Git 状态、其他本地项目文件或 Codex/Claude 的历史 Memory。只有用户明确要求结合本地历史，或询问代码并要求修改时，才进入对应本地资料流程。Skill 已给出可用命令时不要预先调用 `--help`，只在命令真实报参数错误后查询一次对应帮助。
+
+## 聚合优先与读取预算
+
+普通用户询问项目现状、决策、工作包、会议结论、风险或下一步时，默认测试的是服务端 Project Context 聚合能力：
+
+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 外，标题、段落、小标题、列表和来源标签都不得出现仅用于追踪的编号或代号。原始标题或摘要带追踪前缀时，按对象类型和业务内容改述；无法确定自然名称时使用对象类型加内容摘要，不得原样复制追踪键。
+
+```bash
+ot context get --project <id> --snapshot <snapshot-id> \
+  --query "当前目标和成功标准" \
+  --query "正在推进哪些工作，目前分别是什么状态" \
+  --query "最近一次会议讨论了什么，哪些问题尚未决定" \
+  --query "当前正式决策和验证路径" \
+  --query "最近验收结果和遗留缺口" \
+  --limit 20
+```
+
 ## 读取流程
 
-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`。
+1. 项目未知时优先用 `ot projects resolve <query>` 定位；已有项目 ID 或唯一的当前项目时不要再 list/resolve。
+   `active_todo_count` 是当前用户相关的活跃待办，项目整体进度使用 `project_active_todo_count` 和 `todo_stats`，不得把个人数字表述为项目总数。
+2. 只有问题涉及具体人员时才用 `ot roster list --project <id>` 解析成员；先匹配 canonical `display_name`，再参考 aliases 和项目角色，重名或无法唯一匹配时询问用户。
+3. 用一次 `ot context get --project <id> --query <term>` 获取项目上下文；复杂问题用同一命令的多个 `--query`，遵守上面的读取预算。
+4. 聚合结果缺少一个关键事实时，第二次读取可按已知对象使用 `ot goals/todos/knowledge/meetings/worklogs show`，或执行一次更精确的 Context 查询。对象 list/search 只用于用户明确要求浏览集合，不用于普通综合问答补全。
 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
+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 转义损坏内容。
@@ -36,6 +70,7 @@ ot --json doctor
 - 创建目标、Todo、正式决策/风险、提交审核、审核通过/驳回、确认会议项目更新前，必须展示明确草稿和影响。
 - 项目归属只能来自用户明确选择，或受管 Goal/Meeting 唯一解析出的项目；无法唯一确定时停止写入并询问。
 - Knowledge 保存可长期复用的结论和完整会议纪要；短进展、决策、风险和产物引用写入 WorkLog。原始文件是 Knowledge 的来源材料，不是第二套知识系统。
+- 新建或更新 Goal、Todo、WorkLog、Knowledge 和 Meeting Update 时，面向用户的 `title`、`summary`、正文和验收描述必须使用自然业务语言。需要内部追踪键时放入 metadata 或关系字段，不得把它作为标题前缀或要求用户在后续提问中使用。
 
 ## Todo 与 Goal
 
@@ -43,6 +78,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 +88,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>
+```
+
+快照建立后不可更新或删除。普通业务问答直接使用给定 snapshot ID，不要先 `show/list` 快照。只有服务端明确返回 snapshot 无效时才核对一次完整 ID 和快照列表。诊断召回时可给单个明确查询加 `--trace --include-candidates`；trace 返回候选数、选中/遗漏数、rank、score、匹配原因和截断信息，不能把一次召回当成稳定修复。
+
 ## Knowledge
 
 保存前展示标题、摘要、正文范围、Project/Goal、来源 URL、附件和上下文引用。只有用户明确选择并确认的结论才能沉淀；不得自动上传或持久化 Desktop 既有会话历史。