@yijiancaotang/cli 0.0.0-stage → 1.1.0

package/dist/calendar-contract.js

@@ -0,0 +1,358 @@
+import { scheduleUUID, scheduleKey, validScheduleDate, validScheduleTime, scheduleReadResult } from "./schedule-contract.js";
+export const calendarRoot = "/api/v1/agent";
+export const calendarKinds = ["project_created", "project_stage", "project_update", "checkin", "knowledge_created", "knowledge_growth", "schedule_completed", "schedule_cancelled", "daily_summary"];
+const record = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+const scalar = (v, max = 5000) => typeof v === "string" && [...v].length <= max && !v.includes("\0") && ![...v].some(c => { const n = c.codePointAt(0); return n >= 0xd800 && n <= 0xdfff; });
+const natural = (v) => typeof v === "number" && Number.isSafeInteger(v) && v >= 0;
+const revision = (v) => natural(v) && v > 0;
+const actors = ["user", "agent", "unknown"];
+const trim = (v) => v.replace(/^\p{White_Space}+|\p{White_Space}+$/gu, "");
+export class CalendarProblem extends Error {
+    code;
+    humanMessage;
+    nextAction;
+    exitCode;
+    details;
+    constructor(code, humanMessage, nextAction, exitCode = 2, details = {}) {
+        super(JSON.stringify({ code, message: humanMessage, next_action: nextAction, ...details }));
+        this.code = code;
+        this.humanMessage = humanMessage;
+        this.nextAction = nextAction;
+        this.exitCode = exitCode;
+        this.details = details;
+    }
+}
+export function calendarInvalid() {
+    throw new CalendarProblem("invalid_arguments", "日历、时间线或当天总结参数无效。", "请查看本命令帮助；日期使用真实 YYYY-MM-DD，含首尾最多一个日历年；只提交本人确认的一句话，保持原幂等键和当前版本。");
+}
+function invalidResponse() {
+    throw new CalendarProblem("invalid_response", "日历或时间线返回了无法核实的内容。", "请核对服务版本和实际读取范围，不把异常响应、权限缺口或未记录的历史解释为没有活动。", 7);
+}
+const leap = (y) => y % 4 === 0 && (y % 100 !== 0 || y % 400 === 0);
+const ordinal = (y, m, d) => { const p = y - 1; return 365 * p + Math.floor(p / 4) - Math.floor(p / 100) + Math.floor(p / 400) + [31, leap(y) ? 29 : 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31].slice(0, m - 1).reduce((s, n) => s + n, 0) + d - 1; };
+function validRange(start, end) {
+    const [sy, sm, sd] = start.split("-").map(Number), [ey, em, ed] = end.split("-").map(Number);
+    const nm = sm === 2 && sd === 29 && !leap(sy + 1) ? 3 : sm, nd = nm !== sm ? 1 : sd;
+    return start <= end && ordinal(ey, em, ed) + 1 <= ordinal(sy + 1, nm, nd);
+}
+export function calendarQuery(input) {
+    const out = {};
+    for (const [name, value] of Object.entries(input)) {
+        if (!["start_date", "end_date", "project_id", "actor_kind", "actor_name", "actor_source_id", "kind", "only_core", "limit", "cursor"].includes(name))
+            calendarInvalid();
+        if (value === undefined)
+            continue;
+        if (name === "only_core") {
+            if (typeof value !== "boolean")
+                calendarInvalid();
+        }
+        else if (name === "limit") {
+            if (!natural(value) || value < 1 || value > 100)
+                calendarInvalid();
+        }
+        else {
+            if (!scalar(value, name === "cursor" ? 4096 : name === "actor_name" ? 80 : 100) || !value)
+                calendarInvalid();
+            if ((name === "start_date" || name === "end_date") && !validScheduleDate(value))
+                calendarInvalid();
+            if ((name === "project_id" || name === "actor_source_id") && !scheduleUUID(value))
+                calendarInvalid();
+            if (name === "actor_kind" && !actors.includes(value))
+                calendarInvalid();
+            if (name === "actor_name" && (trim(value) !== value || /[\p{Cc}\u2028\u2029]/u.test(value)))
+                calendarInvalid();
+            if (name === "kind" && !calendarKinds.includes(value))
+                calendarInvalid();
+            if (name === "cursor" && /\s/u.test(value))
+                calendarInvalid();
+        }
+        out[name] = value;
+    }
+    if ((input.start_date === undefined) !== (input.end_date === undefined))
+        calendarInvalid();
+    if (typeof input.start_date === "string" && typeof input.end_date === "string" && !validRange(input.start_date, input.end_date))
+        calendarInvalid();
+    if (input.actor_source_id !== undefined && input.actor_kind !== undefined && input.actor_kind !== "agent")
+        calendarInvalid();
+    return out;
+}
+export function dailySummaryText(value) {
+    if (!scalar(value, 1000) || /[\p{Cc}\u2028\u2029]/u.test(value))
+        return calendarInvalid();
+    const text = trim(value);
+    if (!text || [...text].length > 200)
+        return calendarInvalid();
+    return text;
+}
+// Format-only validation is also used for immutable historical read receipts.
+export function dailySummaryBody(value) {
+    if (!record(value) || Object.keys(value).some(k => !["date", "summary", "confirmed"].includes(k)) || value.confirmed !== true || !validScheduleDate(value.date))
+        return calendarInvalid();
+    return { date: value.date, summary: dailySummaryText(value.summary), confirmed: true };
+}
+export function dailySummaryDateBounds(now = Date.now()) {
+    if (!Number.isFinite(now) || Number.isNaN(new Date(now).getTime()))
+        return calendarInvalid();
+    const parts = new Intl.DateTimeFormat("en-CA", { timeZone: "Asia/Shanghai", year: "numeric", month: "2-digit", day: "2-digit" }).formatToParts(new Date(now));
+    const part = (type) => parts.find(value => value.type === type).value;
+    const max_date = part("year").padStart(4, "0") + "-" + part("month") + "-" + part("day");
+    const min_date = new Date(Date.parse(max_date + "T00:00:00Z") - 30 * 86400000).toISOString().slice(0, 10);
+    return { min_date, max_date, timezone: "Asia/Shanghai" };
+}
+export function dailySummaryWriteBody(value, now = Date.now()) {
+    const body = dailySummaryBody(value), bounds = dailySummaryDateBounds(now);
+    if (body.date < bounds.min_date || body.date > bounds.max_date)
+        throw new CalendarProblem("summary_date_out_of_range", "当天总结只接受北京时间今天及此前30天（含）。", "请在返回的日期范围内重新确认；不接受未来日期，保留原幂等键，不自动重试。", 2, bounds);
+    return body;
+}
+export function calendarKey(value) { try {
+    return scheduleKey(value);
+}
+catch {
+    return calendarInvalid();
+} }
+export function validSummaryRevision(value) { return natural(value); }
+export function calendarUnknown(key, status) {
+    return new CalendarProblem("write_outcome_unknown", "当天总结写入结果未确认，不能视为已收工。", "保留原幂等键和连接，用 daily-summary status 或 get_daily_summary_write_status 核对；不要换键、自动重试或执行依赖写入。", 6, { write_status: "unknown", idempotency_key: key, ...(status === undefined ? {} : { http_status: status }) });
+}
+export function calendarFailure(status, body, key, operation = "read") {
+    if (key && (status === 202 || status >= 500))
+        return calendarUnknown(key, status);
+    const raw = record(body) ? body.code ?? body.error : undefined;
+    const known = { 400: ["summary_date_out_of_range", "invalid_calendar_query", "invalid_calendar_input", "invalid_daily_summary", "invalid_summary_input", "summary_confirmation_required", "invalid_idempotency_key", "invalid_summary_revision"], 401: ["not_authenticated"], 403: ["token_scope_insufficient", "capability_disabled", "second_confirmation_required", "legal_consent_required", "account_unavailable"], 404: ["summary_not_found", "daily_summary_not_found"], 409: ["calendar_cursor_stale", "summary_revision_conflict", "idempotency_conflict"], 415: ["invalid_content_type"], 429: ["rate_limited"], 503: ["calendar_unavailable", "summary_unavailable"] };
+    const code = record(body) && (body.code === undefined || body.code === raw) && (body.error === undefined || body.error === raw) && typeof raw === "string" && known[status]?.includes(raw) ? raw : "request_rejected";
+    const details = { http_status: status, ...(key ? { idempotency_key: key } : {}) };
+    if (code === "summary_date_out_of_range" && operation === "write") {
+        if (record(body) && body.timezone === "Asia/Shanghai" && validScheduleDate(body.min_date) && validScheduleDate(body.max_date)) {
+            const [ay, am, ad] = body.min_date.split("-").map(Number), [by, bm, bd] = body.max_date.split("-").map(Number);
+            if (ordinal(by, bm, bd) - ordinal(ay, am, ad) === 30)
+                Object.assign(details, { min_date: body.min_date, max_date: body.max_date, timezone: "Asia/Shanghai" });
+        }
+        return new CalendarProblem("summary_date_out_of_range", "当天总结只接受北京时间今天及此前30天（含）。", "请按可接受的日期范围重新确认；不接受未来日期，保留原幂等键，不自动重试。", 2, details);
+    }
+    const allowedCapabilities = operation === "write" ? ["write_project_update"] : operation === "status" ? [] : ["read_projects", "read_knowledge", "read_workbench", "read_drafts"];
+    if (code === "capability_disabled" && record(body) && allowedCapabilities.includes(body.required_capability) && (body.missing_sections === undefined || Array.isArray(body.missing_sections) && body.missing_sections.length === 0))
+        details.required_capability = body.required_capability;
+    const next = code === "calendar_cursor_stale" ? "数据或权限已变化；从第一页重新读取，不自动轮询或拼接新旧页面。" : status === 403 ? "请本人在网页核对账号开关、连接只读/读写范围或协议确认；不要重新授权或换入口绕过限制。" : status === 409 ? "先核对当前总结和版本；保留原幂等键，不自动重试或覆盖。" : "请核对命令输入、服务版本和实际状态，不把失败解释为没有活动，也不自动重试写入。";
+    return new CalendarProblem(code, code === "calendar_cursor_stale" ? "时间线游标已失效。" : status === 403 ? "当前操作权限不足。" : "日历或当天总结请求未完成。", next, status === 401 ? 3 : status === 403 ? 4 : status >= 500 ? 7 : 2, details);
+}
+function actor(value) {
+    if (typeof value.actor_kind !== "string" || !actors.includes(value.actor_kind) || !scalar(value.actor_name, 80) || !value.actor_name || /[\p{Cc}\u2028\u2029]/u.test(value.actor_name))
+        return invalidResponse();
+    const out = { actor_kind: value.actor_kind, actor_name: value.actor_name };
+    if (value.actor_source_id !== undefined) {
+        if (value.actor_kind !== "agent" || !scheduleUUID(value.actor_source_id))
+            invalidResponse();
+        out.actor_source_id = value.actor_source_id;
+    }
+    if (value.actor_kind === "unknown" && value.actor_name !== "未记录")
+        invalidResponse();
+    return out;
+}
+export function dailySummaryResult(value) {
+    if (!record(value) || !scheduleUUID(value.id) || !validScheduleDate(value.date) || !validScheduleTime(value.confirmed_at) || !revision(value.revision) || typeof value.modified !== "boolean")
+        return invalidResponse();
+    let body;
+    try {
+        body = dailySummaryBody({ date: value.date, summary: value.summary, confirmed: true });
+    }
+    catch {
+        return invalidResponse();
+    }
+    if (body.summary !== value.summary)
+        return invalidResponse();
+    return { id: value.id, date: body.date, summary: body.summary, confirmed_at: value.confirmed_at, revision: value.revision, ...actor(value), modified: value.modified };
+}
+const sections = { calendar_projects: "read_projects", calendar_knowledge: "read_knowledge", calendar_schedule: "read_workbench", daily_progress: "read_projects", daily_knowledge: "read_knowledge", project_drafts: "read_drafts", project_draft_checkins: "read_drafts", draft_knowledge: "read_drafts", knowledge_applied_updates: "read_knowledge", draft_knowledge_applied_updates: "read_drafts", daily_summary: "read_projects", daily_activity: "read_workbench", schedule_items: "read_workbench" };
+function missingSections(value, receipt = false) {
+    if (!Array.isArray(value))
+        return invalidResponse();
+    const seen = new Set();
+    return value.map(raw => { if (!record(raw) || typeof raw.section !== "string" || sections[raw.section] !== raw.required_capability || !["capability_disabled", ...(receipt ? ["read_failed"] : [])].includes(raw.reason) || seen.has(raw.section))
+        return invalidResponse(); seen.add(raw.section); return { section: raw.section, required_capability: raw.required_capability, reason: raw.reason }; });
+}
+function eventResult(value) {
+    if (!record(value) || typeof value.kind !== "string" || !calendarKinds.includes(value.kind) || !scalar(value.id, 200) || !/^[A-Za-z0-9:._-]+$/.test(value.id) || !validScheduleDate(value.date) || !validScheduleTime(value.occurred_at) || !scalar(value.snippet) || !scalar(value.title, 300) || typeof value.modified !== "boolean")
+        return invalidResponse();
+    const out = { kind: value.kind, id: value.id, date: value.date, occurred_at: value.occurred_at, ...actor(value), snippet: value.snippet, title: value.title, modified: value.modified };
+    for (const name of ["project_id", "knowledge_card_id"]) {
+        if (value[name] !== undefined) {
+            if (!scheduleUUID(value[name]))
+                invalidResponse();
+            out[name] = value[name];
+        }
+    }
+    if (value.project_title !== undefined) {
+        if (!scalar(value.project_title, 300) || !out.project_id)
+            invalidResponse();
+        out.project_title = value.project_title;
+    }
+    for (const name of ["from_status", "to_status"]) {
+        const status = value[name];
+        if (status === undefined)
+            continue;
+        if (typeof status !== "string")
+            return invalidResponse();
+        if (value.kind === "knowledge_growth") {
+            if (!["captured", "summarized", "applied", "reviewed", "templated"].includes(status))
+                return invalidResponse();
+        }
+        else if (value.kind === "project_stage") {
+            // Project stages are user text, bounded by the existing 30-code-point contract.
+            if (!scalar(status, 30) || !status || trim(status) !== status || /[\p{Cc}\u2028\u2029]/u.test(status))
+                return invalidResponse();
+        }
+        else {
+            if (status !== "")
+                return invalidResponse();
+            continue;
+        }
+        out[name] = status;
+    }
+    return out;
+}
+export function calendarReadResult(status, value, calendar) {
+    if (status !== 200 || !record(value) || value.timezone !== "Asia/Shanghai" || !validScheduleDate(value.start_date) || !validScheduleDate(value.end_date) || !validRange(value.start_date, value.end_date) || !Array.isArray(value.items) || !natural(value.total) || !natural(value.limit) || value.limit < 1 || value.limit > 100 || typeof value.has_more !== "boolean" || value.next_cursor !== undefined && !scalar(value.next_cursor, 4096) || typeof value.partial !== "boolean")
+        return invalidResponse();
+    const cursor = value.next_cursor ?? "";
+    if (value.has_more ? (!cursor || value.items.length !== value.limit) : cursor !== "")
+        invalidResponse();
+    const items = value.items.map(eventResult), ids = new Set();
+    if (items.length > value.limit || items.length > value.total)
+        invalidResponse();
+    let prior = Infinity;
+    for (const item of items) {
+        const k = `${item.kind}:${item.id}`;
+        if (ids.has(k) || String(item.date) < value.start_date || String(item.date) > value.end_date)
+            invalidResponse();
+        ids.add(k);
+        const time = Date.parse(item.occurred_at);
+        if (time > prior)
+            invalidResponse();
+        prior = time;
+    }
+    const missing = missingSections(value.missing_sections === undefined ? [] : value.missing_sections);
+    if (!value.partial && missing.length)
+        invalidResponse();
+    const out = { timezone: "Asia/Shanghai", start_date: value.start_date, end_date: value.end_date, items, total: value.total, limit: value.limit, has_more: value.has_more, next_cursor: cursor, partial: value.partial, missing_sections: missing };
+    if (Array.isArray(value.warnings)) {
+        const warnings = [...new Set(value.warnings.filter((v) => typeof v === "string" && ["historical_mirror_ambiguous", "historical_project_stage_not_recorded", "historical_actor_not_recorded", "historical_knowledge_growth_not_recorded", "actor_attribution_incomplete"].includes(v)))];
+        if (warnings.length)
+            out.warnings = warnings;
+    }
+    if (value.event_coverage !== undefined) {
+        if (!Array.isArray(value.event_coverage))
+            return invalidResponse();
+        const seen = new Set();
+        out.event_coverage = value.event_coverage.map(raw => { if (!record(raw) || typeof raw.stream !== "string" || !["project_stage", "actor", "knowledge_growth"].includes(raw.stream) || !validScheduleTime(raw.started_at) || seen.has(raw.stream))
+            return invalidResponse(); seen.add(raw.stream); return { stream: raw.stream, started_at: raw.started_at }; });
+    }
+    if (value.accumulation !== undefined || value.forgotten !== undefined) {
+        const a = value.accumulation, f = value.forgotten;
+        if (!record(a) || a.scope !== "filtered_period_events" || !validScheduleTime(a.as_of) || !natural(a.event_total) || a.event_total !== value.total || !natural(a.growth_total) || a.growth_total > a.event_total || !record(f) || f.scope !== "current_readable_assets" || !validScheduleTime(f.as_of))
+            return invalidResponse();
+        out.accumulation = { scope: a.scope, as_of: a.as_of, event_total: a.event_total, growth_total: a.growth_total, applied_cards: assetGroup(a.applied_cards, ["applied"]), reviewed_cards: assetGroup(a.reviewed_cards, ["reviewed"]), templated_cards: assetGroup(a.templated_cards, ["templated"]) };
+        out.forgotten = { scope: f.scope, as_of: f.as_of, projects: assetGroup(f.projects, ["draft", "active", "paused"]), knowledge: assetGroup(f.knowledge, ["captured"]) };
+    }
+    if (calendar || value.days !== undefined) {
+        if (!Array.isArray(value.days))
+            return invalidResponse();
+        const dates = new Set();
+        let dayTotal = 0;
+        out.days = value.days.map(raw => {
+            if (!record(raw) || !validScheduleDate(raw.date) || raw.date < value.start_date || raw.date > value.end_date || dates.has(raw.date) || !natural(raw.total) || !Array.isArray(raw.schedule_items) || !natural(raw.schedule_total) || typeof raw.schedule_has_more !== "boolean")
+                return invalidResponse();
+            dates.add(raw.date);
+            dayTotal += raw.total;
+            const day = { date: raw.date, total: raw.total };
+            for (const field of ["started_at", "finished_at"]) {
+                if (raw[field] !== null && !validScheduleTime(raw[field]))
+                    invalidResponse();
+                day[field] = raw[field];
+            }
+            if (raw.started_actor_name !== null && (!scalar(raw.started_actor_name, 80) || !raw.started_actor_name))
+                invalidResponse();
+            if (raw.started_token_id !== null && !scheduleUUID(raw.started_token_id))
+                invalidResponse();
+            if (raw.started_at === null && (raw.started_actor_name !== null || raw.started_token_id !== null))
+                invalidResponse();
+            day.started_actor_name = raw.started_actor_name;
+            day.started_token_id = raw.started_token_id;
+            day.summary = raw.summary === null ? null : dailySummaryResult(raw.summary);
+            if (day.summary && (day.summary.date !== raw.date || raw.finished_at !== day.summary.confirmed_at))
+                invalidResponse();
+            // The same schedule projector used by existing schedule reads validates each entry.
+            let projected;
+            try {
+                projected = raw.schedule_items.map(item => scheduleReadResult(200, { timezone: "Asia/Shanghai", schedule_item: item }, true).schedule_item);
+            }
+            catch {
+                return invalidResponse();
+            }
+            if (projected.length > raw.schedule_total || raw.schedule_has_more !== (projected.length < raw.schedule_total))
+                invalidResponse();
+            day.schedule_items = projected;
+            day.schedule_total = raw.schedule_total;
+            day.schedule_has_more = raw.schedule_has_more;
+            return day;
+        });
+        if (dayTotal !== value.total)
+            invalidResponse();
+    }
+    return out;
+}
+function assetGroup(value, statuses) {
+    if (!record(value) || !Array.isArray(value.items) || value.items.length > 20 || !natural(value.total) || value.items.length > value.total || typeof value.has_more !== "boolean" || value.has_more !== (value.items.length < value.total))
+        return invalidResponse();
+    const seen = new Set();
+    const items = value.items.map(raw => { if (!record(raw) || !scheduleUUID(raw.id) || seen.has(raw.id) || !scalar(raw.title, 300) || !raw.title || typeof raw.status !== "string" || !statuses.includes(raw.status))
+        return invalidResponse(); seen.add(raw.id); const out = { id: raw.id, title: raw.title, status: raw.status }; if (raw.project_id !== undefined) {
+        if (!scheduleUUID(raw.project_id))
+            return invalidResponse();
+        out.project_id = raw.project_id;
+    } if (raw.project_title !== undefined) {
+        if (!out.project_id || !scalar(raw.project_title, 300) || !raw.project_title)
+            return invalidResponse();
+        out.project_title = raw.project_title;
+    } return out; });
+    return { items, total: value.total, has_more: value.has_more };
+}
+export function dailySummaryReceipt(status, value, key) {
+    if (![200, 201].includes(status) || !record(value) || !scheduleUUID(value.id) || value.write_status !== "confirmed" || typeof value.replayed !== "boolean" || value.code !== undefined || value.error !== undefined || value.read_permission_missing !== undefined && typeof value.read_permission_missing !== "boolean" || value.read_unavailable !== undefined && typeof value.read_unavailable !== "boolean")
+        throw calendarUnknown(key, status);
+    const out = { id: value.id, write_status: "confirmed", replayed: value.replayed };
+    try {
+        const missing = missingSections(value.missing_sections === undefined ? [] : value.missing_sections, true);
+        if (value.read_permission_missing === true || value.read_unavailable === true || missing.length) {
+            const unavailable = value.read_unavailable === true;
+            if (value.read_permission_missing === true && unavailable || missing.length !== 1 || missing[0].section !== "daily_summary" || missing[0].reason !== (unavailable ? "read_failed" : "capability_disabled"))
+                throw calendarUnknown(key, status);
+            out[unavailable ? "read_unavailable" : "read_permission_missing"] = true;
+            out.missing_sections = missing;
+        }
+        else {
+            out.daily_summary = dailySummaryResult(value.daily_summary);
+            if (out.daily_summary.id !== value.id)
+                throw calendarUnknown(key, status);
+        }
+    }
+    catch {
+        throw calendarUnknown(key, status);
+    }
+    return out;
+}
+export function isCalendarHeaderPath(path, method) { return method === "POST" && path === `${calendarRoot}/m2/daily-summary` || method === "GET" && path === `${calendarRoot}/m1/daily-summary-write-status`; }
+export function calendarHeaders(path, method, value) {
+    if (!isCalendarHeaderPath(path, method) || !record(value) || Object.keys(value).some(k => !["Idempotency-Key", "If-Match"].includes(k)))
+        return calendarInvalid();
+    const out = { "Idempotency-Key": calendarKey(value["Idempotency-Key"]) };
+    if (method === "POST") {
+        const rev = value["If-Match"];
+        if (typeof rev !== "string" || !/^"(0|[1-9]\d*)"(?![\s\S])/.test(rev) || !validSummaryRevision(Number(rev.slice(1, -1))))
+            return calendarInvalid();
+        out["If-Match"] = rev;
+    }
+    else if (value["If-Match"] !== undefined)
+        return calendarInvalid();
+    return out;
+}

package/dist/calendar-help.js

@@ -0,0 +1,12 @@
+import { dailySummaryDateBounds } from "./calendar-contract.js";
+const key = "calendar-example-key-0001";
+const readOptions = ["--start-date", "--end-date", "--project", "--actor-kind", "--actor-name", "--actor-source-id", "--kind", "--only-core", "--limit", "--cursor"];
+const notes = "只读本人可见事件；默认最近7个北京时间自然日，含首尾最多一个日历年。按项目、本人/AI名称或来源ID、类型筛选；旧来源显示未记录，断开连接保留历史名称。同名AI可用来源ID区分。日历当天明细与时间线同源；总结只取每天最新一句，撤销的待办完成不显示。total是筛选后全部可读事件数，items只是当前页；partial/missing_sections不是没有记录。next_cursor不为空才翻下一页；数据或权限变化返回calendar_cursor_stale时从第一页重新读，不自动轮询或拼接新旧页面。";
+export const calendarCommandHelp = {};
+for (const command of ["calendar", "timeline"]) {
+    calendarCommandHelp[command] = { command, usage: `caotang ${command}`, description: command === "calendar" ? "按日读取开工、当天总结、事件及日程；未记录开工/未收工如实留空。" : "按时间倒序读取本人和各AI做过的事；接手另一个AI的活之前，先看它最近做了什么。", options: readOptions, fields: { "start-date": "选填，真实YYYY-MM-DD；与end-date同时给或同时省；默认最近7天。", "end-date": "选填，真实YYYY-MM-DD；与start-date同时给或同时省；默认今天。", project: "本人项目UUID，不接受none。", "actor-kind": "user、agent或unknown。", "actor-name": "确切来源名称，最多80个Unicode码点。", "actor-source-id": "可信来源连接UUID，配合agent筛选，不猜ID。", kind: "project_created、project_stage、project_update、checkin、knowledge_created、knowledge_growth、schedule_completed、schedule_cancelled或daily_summary。", "only-core": "true或false，省略为false。", limit: "1-100，默认50。", cursor: "上一页返回的不透明next_cursor，最多4096字符；与同一筛选和权限一起使用。" }, example: { command: `caotang ${command} --start-date 2026-11-09 --end-date 2026-11-09 --actor-name Codex` }, notes };
+}
+const writeNotes = "总结日期只接受北京时间今天及此前30个自然日（含），不接受未来；超范围返回summary_date_out_of_range和min_date/max_date。先向本人展示完整日期（北京时间）和当天核心一句，得到确认后才写confirmed:true；平台不能核实口头确认，也不生成或改写总结。summary去首尾空白后1-200个Unicode码点，不含换行/控制符。写归write_project_update，读归read_projects；只读连接不能写。一次保存成功记录收工时刻，同日修改只展示最新一句并标已修改，原键回放不推进收工。幂等键16-128位安全ASCII；revision=0仅首次创建，修改用读回revision。202、网络失败或畸形回执不是成功，保留原键和连接，用daily-summary status核对，不自动换键重试。N22精简回执只确认ID与成败，不代表读到了正文。";
+calendarCommandHelp["daily-summary save"] = { command: "daily-summary save", usage: "caotang daily-summary save --input file|- --idempotency-key KEY --revision N", description: "保存本人已确认的当天核心一句，同时记录收工；同日修改使用当前版本。", options: ["--input", "--idempotency-key", "--revision"], fields: { date: "必填，真实YYYY-MM-DD；仅北京时间今天及此前30天（含），不接受未来。", summary: "必填，已确认的1-200码点单行原文。", confirmed: "必填且只能为true。", revision: "--revision N；首次0，修改为最近读回的正安全整数。" }, required_fields: ["date", "summary", "confirmed"], example: { command: `caotang daily-summary save --input - --idempotency-key ${key} --revision 0`, input: { date: dailySummaryDateBounds().max_date, summary: "本人已确认的当天核心一句", confirmed: true } }, notes: writeNotes };
+calendarCommandHelp["daily-summary status"] = { command: "daily-summary status", usage: "caotang daily-summary status --idempotency-key KEY", description: "只读核对同一连接的原总结回执；原键只放header，不放query/body。", options: ["--idempotency-key"], example: { command: `caotang daily-summary status --idempotency-key ${key}` }, notes: writeNotes };
+export const calendarCommandUsages = Object.values(calendarCommandHelp).map(v => v.usage.replace(/^caotang /, ""));

package/dist/calendar.js

@@ -0,0 +1,64 @@
+import { CliError } from "./errors.js";
+import { validateCommandArguments } from "./input-validation.js";
+import { CalendarProblem, calendarFailure, calendarInvalid, calendarKey, calendarQuery, calendarReadResult, calendarRoot, calendarUnknown, dailySummaryWriteBody, dailySummaryReceipt, validSummaryRevision } from "./calendar-contract.js";
+export async function executeCalendar(args, flags, ctx) {
+    try {
+        validateCommandArguments(args, flags);
+        let path, key, options = { method: "GET", token: ctx.token };
+        if (args[0] === "calendar" || args[0] === "timeline") {
+            const names = { "start-date": "start_date", "end-date": "end_date", project: "project_id", "actor-kind": "actor_kind", "actor-name": "actor_name", "actor-source-id": "actor_source_id", kind: "kind", "only-core": "only_core", limit: "limit", cursor: "cursor" };
+            const input = {};
+            for (const [name, value] of Object.entries(flags)) {
+                if (!Object.hasOwn(names, name))
+                    calendarInvalid();
+                if (name === "limit") {
+                    if (typeof value !== "string" || !/^\d+$/.test(value))
+                        calendarInvalid();
+                    input[names[name]] = Number(value);
+                }
+                else if (name === "only-core") {
+                    if (value !== true && value !== false && value !== "true" && value !== "false")
+                        calendarInvalid();
+                    input[names[name]] = value === true || value === "true";
+                }
+                else
+                    input[names[name]] = value;
+            }
+            const query = new URLSearchParams(Object.entries(calendarQuery(input)).map(([k, v]) => [k, String(v)])).toString();
+            path = `${calendarRoot}/m1/${args[0]}${query ? `?${query}` : ""}`;
+        }
+        else if (args[0] === "daily-summary" && args[1] === "status") {
+            key = calendarKey(flags["idempotency-key"]);
+            path = `${calendarRoot}/m1/daily-summary-write-status`;
+            options.headers = { "Idempotency-Key": key };
+        }
+        else if (args[0] === "daily-summary" && args[1] === "save") {
+            key = calendarKey(flags["idempotency-key"]);
+            const rev = flags.revision;
+            if (typeof rev !== "string" || !/^(0|[1-9]\d*)$/.test(rev) || !validSummaryRevision(Number(rev)) || typeof flags.input !== "string" || !flags.input.trim())
+                calendarInvalid();
+            const body = dailySummaryWriteBody(await ctx.readInput(flags.input));
+            path = `${calendarRoot}/m2/daily-summary`;
+            options = { ...options, method: "POST", body, headers: { "Idempotency-Key": key, "If-Match": `"${rev}"` } };
+        }
+        else
+            return calendarInvalid();
+        let result;
+        try {
+            result = await ctx.api.request(path, options);
+        }
+        catch {
+            if (key)
+                throw calendarUnknown(key);
+            throw new CalendarProblem("network_error", "日历或时间线读取未完成。", "检查当前执行环境的网络；不要反复重试或重新授权。", 6);
+        }
+        if (![200, 201].includes(result.status))
+            throw calendarFailure(result.status, result.body, key, key ? (args[1] === "save" ? "write" : "status") : "read");
+        return { ...result, body: key ? dailySummaryReceipt(result.status, result.body, key) : calendarReadResult(result.status, result.body, args[0] === "calendar") };
+    }
+    catch (error) {
+        if (error instanceof CalendarProblem)
+            throw new CliError(error.code, error.humanMessage, error.nextAction, error.exitCode, error.details);
+        throw error;
+    }
+}

package/dist/capability-result.js

@@ -0,0 +1,85 @@
+import { apiError, asRecord, CliError, expectOK, singleSwitchMetadata, unverifiedSwitchError } from "./errors.js";
+const capabilityActions = {
+    read_notifications: "请在网页检查“读取通知”开关及这台设备的权限。",
+    read_drafts: "请在网页检查“读取草稿”开关及这台设备的权限。",
+    delete_or_archive: "请在网页检查“删除或归档申请”开关及这台设备的读写权限；申请仍需本人在网页确认。",
+};
+export function expectCapabilityResult(result, capability, requestKind) {
+    if (result.status === 403) {
+        const error = apiError(result, requestKind), body = asRecord(result.body);
+        if (error.code === "legal_consent_required" || error.code === "token_scope_insufficient" || error.code === "second_confirmation_required")
+            throw error;
+        if (body && !singleSwitchMetadata(body))
+            throw unverifiedSwitchError();
+        if (body && (Object.hasOwn(body, "required_capability") || (body.code !== undefined && body.error !== undefined && body.code !== body.error))) {
+            if (error.details.required_capability !== undefined && error.details.required_capability !== capability)
+                throw unverifiedSwitchError();
+            throw error;
+        }
+        // Older servers returned bare 403. Offer the known operation's check as
+        // guidance, not a claim that this particular switch was observed closed.
+        const nextAction = capabilityActions[capability];
+        throw new CliError(error.code, "当前操作权限不足。", nextAction, error.exitCode, { ...error.details, required_capability: capability });
+    }
+    return expectOK(result, requestKind);
+}
+// A known switch name is still not evidence if unrelated to this operation.
+export function commandAcceptsSwitch(args, capability) {
+    const [name, op] = args;
+    let eligible;
+    switch (name) {
+        case "knowledge":
+            eligible = op === "add" ? ["write_knowledge", "write_knowledge_sources"] : op === "update" ? ["write_knowledge"] : ["read_knowledge", "read_drafts"];
+            break;
+        case "projects":
+            eligible = ["read_projects", "read_drafts"];
+            break;
+        case "project":
+            eligible = op === "create" || op === "update" ? ["write_project"] : ["read_projects", "read_drafts"];
+            break;
+        case "search":
+            eligible = ["read_projects", "read_knowledge", "read_workbench"];
+            break;
+        case "activity":
+            eligible = ["read_projects", "read_knowledge"];
+            break;
+        case "progress":
+            eligible = op === "add" ? ["write_project_update"] : ["read_projects"];
+            break;
+        case "checkins":
+            eligible = ["read_projects"];
+            break;
+        case "context":
+            eligible = ["read_workbench"];
+            break;
+        case "source":
+        case "upload":
+            eligible = ["write_knowledge_sources"];
+            break;
+        case "link":
+        case "unlink":
+            eligible = ["write_knowledge"];
+            break;
+        case "advance":
+            eligible = ["write_knowledge_stage", "write_project_update"];
+            break;
+        case "cognition":
+            eligible = ["write_project_cognition"];
+            break;
+        case "stage":
+            eligible = ["write_project"];
+            break;
+        case "notifications":
+        case "pending":
+            eligible = ["read_notifications"];
+            break;
+        case "drafts":
+            eligible = ["read_drafts"];
+            break;
+        case "request":
+            eligible = ["delete_or_archive"];
+            break;
+        default: eligible = [];
+    }
+    return typeof capability === "string" && eligible.includes(capability);
+}