@openturtle/cli 0.3.3 → 0.3.5

package/dist/local-knowledge/library.js

@@ -0,0 +1,357 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { syncLocalKnowledgeIndex } from './index.js';
+import { localKnowledgeStoreRoot } from './root.js';
+const MAX_LOCAL_LIBRARY_FILES = 5_000;
+const SKIPPED_DIRECTORIES = new Set(['node_modules', 'dist', 'build', 'coverage', '.git']);
+function libraryPath(userDataPath = localKnowledgeStoreRoot()) {
+    return path.join(userDataPath, 'knowledge', 'local-assets.json');
+}
+function entriesPath(userDataPath = localKnowledgeStoreRoot()) {
+    return path.join(userDataPath, 'knowledge', 'entries');
+}
+function mimeType(filePath) {
+    const extension = path.extname(filePath).slice(1).toLowerCase();
+    const known = {
+        csv: 'text/csv',
+        gif: 'image/gif',
+        html: 'text/html',
+        jpeg: 'image/jpeg',
+        jpg: 'image/jpeg',
+        json: 'application/json',
+        md: 'text/markdown',
+        markdown: 'text/markdown',
+        pdf: 'application/pdf',
+        png: 'image/png',
+        ppt: 'application/vnd.ms-powerpoint',
+        pptx: 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+        txt: 'text/plain',
+        webp: 'image/webp',
+        xls: 'application/vnd.ms-excel',
+        xlsx: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+        yaml: 'application/yaml',
+        yml: 'application/yaml',
+    };
+    return known[extension] || 'application/octet-stream';
+}
+function assetId(filePath) {
+    return crypto.createHash('sha256').update(path.resolve(filePath)).digest('hex').slice(0, 24);
+}
+async function fileHash(filePath) {
+    const hash = crypto.createHash('sha256');
+    await new Promise((resolve, reject) => {
+        const stream = fs.createReadStream(filePath);
+        stream.on('data', (chunk) => hash.update(chunk));
+        stream.on('error', reject);
+        stream.on('end', resolve);
+    });
+    return hash.digest('hex');
+}
+function entryHash(asset) {
+    const entry = asset.entry;
+    if (!entry)
+        return asset.contentHash;
+    return crypto
+        .createHash('sha256')
+        .update(JSON.stringify({
+        contentHash: asset.contentHash,
+        title: entry.title,
+        kind: entry.kind,
+        projectId: entry.projectId || '',
+        status: entry.status,
+        attachments: entry.attachments.map((attachment) => ({
+            path: attachment.path,
+            contentHash: attachment.contentHash,
+        })),
+    }))
+        .digest('hex');
+}
+function writeTextFileAtomic(filePath, content) {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    const tempPath = `${filePath}.${process.pid}.tmp`;
+    fs.writeFileSync(tempPath, content, 'utf8');
+    fs.renameSync(tempPath, filePath);
+}
+async function buildLocalAttachment(input) {
+    const filePath = path.resolve(input.path);
+    const stat = await fs.promises.stat(filePath);
+    if (!stat.isFile())
+        throw new Error(`附件不是可读取的文件：${input.name || filePath}`);
+    return {
+        name: input.name.trim() || path.basename(filePath),
+        path: filePath,
+        mimeType: mimeType(filePath),
+        sizeBytes: stat.size,
+        modifiedAt: stat.mtimeMs,
+        contentHash: await fileHash(filePath),
+    };
+}
+function readLibrary(userDataPath) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(libraryPath(userDataPath), 'utf8'));
+        return {
+            version: 1,
+            assets: Array.isArray(parsed.assets) ? parsed.assets : [],
+        };
+    }
+    catch {
+        return { version: 1, assets: [] };
+    }
+}
+function writeLibrary(library, userDataPath) {
+    const filePath = libraryPath(userDataPath);
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    const tempPath = `${filePath}.${process.pid}.tmp`;
+    fs.writeFileSync(tempPath, JSON.stringify(library, null, 2), 'utf8');
+    fs.renameSync(tempPath, filePath);
+}
+async function collectFiles(inputPath) {
+    const resolved = path.resolve(inputPath);
+    const stat = await fs.promises.stat(resolved);
+    if (stat.isFile())
+        return [{ filePath: resolved, sourceRoot: path.dirname(resolved) }];
+    if (!stat.isDirectory())
+        return [];
+    const files = [];
+    const visit = async (directory) => {
+        if (files.length >= MAX_LOCAL_LIBRARY_FILES)
+            return;
+        const entries = await fs.promises.readdir(directory, { withFileTypes: true });
+        for (const entry of entries) {
+            if (files.length >= MAX_LOCAL_LIBRARY_FILES)
+                return;
+            if (entry.name.startsWith('.'))
+                continue;
+            const entryPath = path.join(directory, entry.name);
+            if (entry.isDirectory()) {
+                if (!SKIPPED_DIRECTORIES.has(entry.name))
+                    await visit(entryPath);
+            }
+            else if (entry.isFile()) {
+                files.push({ filePath: entryPath, sourceRoot: resolved });
+            }
+        }
+    };
+    await visit(resolved);
+    return files;
+}
+async function refreshedAsset(asset) {
+    try {
+        const stat = await fs.promises.stat(asset.path);
+        if (!stat.isFile())
+            return { ...asset, syncState: 'missing' };
+        const changed = stat.size !== asset.sizeBytes || stat.mtimeMs !== asset.modifiedAt;
+        const contentHash = changed ? await fileHash(asset.path) : asset.contentHash;
+        let refreshed = {
+            ...asset,
+            sizeBytes: stat.size,
+            modifiedAt: stat.mtimeMs,
+            contentHash,
+        };
+        if (asset.entry) {
+            const attachments = await Promise.all(asset.entry.attachments.map(async (attachment) => {
+                try {
+                    const attachmentStat = await fs.promises.stat(attachment.path);
+                    if (!attachmentStat.isFile())
+                        return null;
+                    const attachmentChanged = attachmentStat.size !== attachment.sizeBytes || attachmentStat.mtimeMs !== attachment.modifiedAt;
+                    return {
+                        ...attachment,
+                        sizeBytes: attachmentStat.size,
+                        modifiedAt: attachmentStat.mtimeMs,
+                        contentHash: attachmentChanged ? await fileHash(attachment.path) : attachment.contentHash,
+                    };
+                }
+                catch {
+                    return null;
+                }
+            }));
+            if (attachments.some((attachment) => attachment === null)) {
+                return { ...refreshed, syncState: 'missing' };
+            }
+            refreshed = {
+                ...refreshed,
+                entry: {
+                    ...asset.entry,
+                    attachments: attachments,
+                },
+            };
+        }
+        const syncState = asset.entry
+            ? asset.cloudMemoryId && asset.cloudEntryHash === entryHash(refreshed)
+                ? 'synced'
+                : asset.cloudMemoryId
+                    ? 'outdated'
+                    : 'local_only'
+            : asset.cloudAttachmentId
+                ? asset.cloudContentHash === contentHash
+                    ? 'synced'
+                    : 'outdated'
+                : 'local_only';
+        return { ...refreshed, syncState };
+    }
+    catch {
+        return { ...asset, syncState: 'missing' };
+    }
+}
+export async function listLocalKnowledgeAssets(userDataPath) {
+    const library = readLibrary(userDataPath);
+    const assets = await Promise.all(library.assets.map(refreshedAsset));
+    if (JSON.stringify(assets) !== JSON.stringify(library.assets)) {
+        writeLibrary({ version: 1, assets }, userDataPath);
+    }
+    await syncLocalKnowledgeIndex(assets, userDataPath);
+    return assets.sort((left, right) => right.addedAt.localeCompare(left.addedAt));
+}
+export async function importLocalKnowledgePaths(inputPaths, userDataPath) {
+    const collected = (await Promise.all(inputPaths.map(collectFiles))).flat().slice(0, MAX_LOCAL_LIBRARY_FILES);
+    const library = readLibrary(userDataPath);
+    const byId = new Map(library.assets.map((asset) => [asset.id, asset]));
+    const imported = [];
+    for (const { filePath, sourceRoot } of collected) {
+        const stat = await fs.promises.stat(filePath);
+        const id = assetId(filePath);
+        const existing = byId.get(id);
+        const contentHash = await fileHash(filePath);
+        const asset = {
+            ...existing,
+            id,
+            name: path.basename(filePath),
+            path: filePath,
+            sourceRoot,
+            relativePath: path.relative(sourceRoot, filePath).split(path.sep).join('/'),
+            mimeType: mimeType(filePath),
+            sizeBytes: stat.size,
+            modifiedAt: stat.mtimeMs,
+            contentHash,
+            addedAt: existing?.addedAt || new Date().toISOString(),
+            syncState: existing?.cloudAttachmentId
+                ? existing.cloudContentHash === contentHash
+                    ? 'synced'
+                    : 'outdated'
+                : 'local_only',
+        };
+        byId.set(id, asset);
+        imported.push(asset);
+    }
+    const assets = [...byId.values()];
+    writeLibrary({ version: 1, assets }, userDataPath);
+    await syncLocalKnowledgeIndex(assets, userDataPath);
+    return imported;
+}
+export async function createLocalKnowledgeEntry(input, userDataPath) {
+    const title = input.title.trim();
+    if (!title)
+        throw new Error('本机知识标题不能为空');
+    const id = crypto.randomUUID();
+    const filePath = path.join(entriesPath(userDataPath), `${id}.md`);
+    writeTextFileAtomic(filePath, input.body.trim());
+    const stat = await fs.promises.stat(filePath);
+    const attachments = await Promise.all((input.attachments || []).slice(0, 20).map(buildLocalAttachment));
+    const now = new Date().toISOString();
+    const asset = {
+        id,
+        name: `${title}.md`,
+        path: filePath,
+        sourceRoot: entriesPath(userDataPath),
+        relativePath: `${id}.md`,
+        mimeType: 'text/markdown',
+        sizeBytes: stat.size,
+        modifiedAt: stat.mtimeMs,
+        contentHash: await fileHash(filePath),
+        addedAt: now,
+        syncState: 'local_only',
+        entry: {
+            title,
+            kind: input.kind,
+            ...(input.projectId?.trim() ? { projectId: input.projectId.trim() } : {}),
+            status: input.status,
+            updatedAt: now,
+            attachments,
+        },
+    };
+    const library = readLibrary(userDataPath);
+    const assets = [asset, ...library.assets];
+    writeLibrary({ version: 1, assets }, userDataPath);
+    await syncLocalKnowledgeIndex(assets, userDataPath);
+    return asset;
+}
+export async function updateLocalKnowledgeEntry(id, input, userDataPath) {
+    const library = readLibrary(userDataPath);
+    const index = library.assets.findIndex((asset) => asset.id === id);
+    if (index < 0 || !library.assets[index].entry)
+        throw new Error('本机知识不存在或不能直接编辑');
+    const title = input.title.trim();
+    if (!title)
+        throw new Error('本机知识标题不能为空');
+    const existing = library.assets[index];
+    writeTextFileAtomic(existing.path, input.body.trim());
+    const stat = await fs.promises.stat(existing.path);
+    const attachments = await Promise.all((input.attachments || []).slice(0, 20).map(buildLocalAttachment));
+    const updated = {
+        ...existing,
+        name: `${title}.md`,
+        sizeBytes: stat.size,
+        modifiedAt: stat.mtimeMs,
+        contentHash: await fileHash(existing.path),
+        syncState: existing.cloudMemoryId ? 'outdated' : 'local_only',
+        entry: {
+            title,
+            kind: input.kind,
+            ...(input.projectId?.trim() ? { projectId: input.projectId.trim() } : {}),
+            status: input.status,
+            updatedAt: new Date().toISOString(),
+            attachments,
+        },
+    };
+    library.assets[index] = updated;
+    writeLibrary(library, userDataPath);
+    await syncLocalKnowledgeIndex(library.assets, userDataPath);
+    return updated;
+}
+export async function removeLocalKnowledgeAsset(id, userDataPath) {
+    const library = readLibrary(userDataPath);
+    const removed = library.assets.find((asset) => asset.id === id);
+    const assets = library.assets.filter((asset) => asset.id !== id);
+    writeLibrary({ version: 1, assets }, userDataPath);
+    if (removed?.entry && path.dirname(removed.path) === entriesPath(userDataPath)) {
+        await fs.promises.rm(removed.path, { force: true });
+    }
+    await syncLocalKnowledgeIndex(assets, userDataPath);
+    return assets;
+}
+export function markLocalKnowledgeAssetSynced(id, cloud, userDataPath) {
+    const library = readLibrary(userDataPath);
+    const index = library.assets.findIndex((asset) => asset.id === id);
+    if (index < 0)
+        return null;
+    const asset = {
+        ...library.assets[index],
+        cloudMemoryId: cloud.memoryId,
+        cloudAttachmentId: cloud.attachmentId,
+        cloudContentHash: cloud.contentHash,
+        syncState: library.assets[index].contentHash === cloud.contentHash ? 'synced' : 'outdated',
+    };
+    library.assets[index] = asset;
+    writeLibrary(library, userDataPath);
+    return asset;
+}
+export function markLocalKnowledgeEntryPublished(id, cloud, userDataPath) {
+    const library = readLibrary(userDataPath);
+    const index = library.assets.findIndex((asset) => asset.id === id);
+    if (index < 0 || !library.assets[index].entry)
+        return null;
+    const asset = {
+        ...library.assets[index],
+        cloudMemoryId: cloud.memoryId,
+        cloudEntryHash: entryHash(library.assets[index]),
+        syncState: 'synced',
+    };
+    library.assets[index] = asset;
+    writeLibrary(library, userDataPath);
+    return asset;
+}
+export function getLocalKnowledgeAsset(id, userDataPath) {
+    return readLibrary(userDataPath).assets.find((asset) => asset.id === id) || null;
+}

package/dist/local-knowledge/root.js

@@ -0,0 +1,5 @@
+import os from 'node:os';
+import { cliGlobalDir } from '../core/paths.js';
+export function localKnowledgeStoreRoot(homeDir = os.homedir()) {
+    return process.env.OPENTURTLE_LOCAL_KNOWLEDGE_ROOT?.trim() || cliGlobalDir(homeDir);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openturtle/cli",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "description": "OpenTurtle collaboration, knowledge, meeting, and agent CLI",
   "keywords": [
     "openturtle",
@@ -25,7 +25,9 @@
   },
   "files": [
     "dist",
-    "README.md"
+    "skill",
+    "README.md",
+    "RELEASE_RUNBOOK.md"
   ],
   "publishConfig": {
     "access": "public",

package/skill/openturtle-cli/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: openturtle-cli
+description: 通过 ot CLI 使用 OpenTurtle 的项目、团队成员、项目上下文、云端与本地知识、会议、目标、待办和工作记录，并在 Desktop 中依据已注入的 Connector 清单选择外部服务 CLI。适用于团队协同、聚合知识检索、会议闭环、项目执行和已连接工具路由；Desktop 会话、自动任务、录音和窗口能力不属于 ot，会话内 Goal 使用当前 Provider 官方 /goal。
+---
+
+# OpenTurtle CLI
+
+直接执行 `ot ... --json`。不要安装或调用 OpenTurtle MCP、Hook，也不要把 Desktop 独有能力伪装成 CLI 命令。
+
+Desktop 会在隐藏系统上下文中注入已启用 Connector 的命令、能力摘要、发现命令、鉴权归属和确认策略。只使用该清单中的 Connector；需要核对时调用 `openturtle-desktop` 的 `list_connectors`。不要调用或设计 `ot connectors`。
+
+用户要求新增外部服务时，先准备符合 `schemaVersion: 1` 的 manifest，再调用 `openturtle-desktop` 的 `propose_connector`。该调用只提交待审批提案；用户必须在“扩展 > 连接器”批准，安装和写操作仍需单独确认。不得直接修改 Desktop 配置或 Connector 目录。
+
+开始前运行：
+
+```bash
+command -v ot
+ot --json doctor
+```
+
+缺少登录态时让用户运行 `ot auth login --web`，不要索取或输出 token。Desktop 内置 Agent 会自动复用 Desktop 当前登录态、团队和项目上下文；独立终端使用 CLI 自己的登录配置。
+
+## 读取流程
+
+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`。
+5. 高层命令缺失时才使用只读逃生口 `ot request get /api/...`。
+
+## 写入规则
+
+- 所有结构化写入使用 `--body-file <json>` 或 `--body-file -`，避免 shell 转义损坏内容。
+- 先执行同一命令的 `--dry-run`，检查 `request.path` 和 `request.body`；用户确认后再正式写入。
+- 创建目标、Todo、正式决策/风险、提交审核、审核通过/驳回、确认会议项目更新前，必须展示明确草稿和影响。
+- 项目归属只能来自用户明确选择，或受管 Goal/Meeting 唯一解析出的项目；无法唯一确定时停止写入并询问。
+- Knowledge 保存可长期复用的结论和完整会议纪要；短进展、决策、风险和产物引用写入 WorkLog。原始文件是 Knowledge 的来源材料，不是第二套知识系统。
+
+## Todo 与 Goal
+
+Todo 草稿至少包含来源、范围/环境、2-5 个行动步骤、可判断的验收标准、证据、负责人和截止时间。信息不全时先问一个最关键的问题，不擅自指派。
+
+`ot goals` 管理 OpenTurtle 团队/项目目标。当前 Agent 会话的 Goal 使用 Provider 官方 `/goal` 命令；不要将会话 Goal 写入 OpenTurtle 项目目标，也不要尝试同步两者状态。
+
+```bash
+ot goals create --body-file goal.json --dry-run
+ot todos create --body-file todo.json --dry-run
+ot todos update <todo-id> --body-file todo-update.json --dry-run
+ot todos submit-review <todo-id> --body-file review.json --dry-run
+ot todos review <todo-id> --body-file decision.json --dry-run
+```
+
+## Knowledge
+
+保存前展示标题、摘要、正文范围、Project/Goal、来源 URL、附件和上下文引用。只有用户明确选择并确认的结论才能沉淀；不得自动上传或持久化 Desktop 既有会话历史。
+
+```bash
+ot knowledge search "关键词" --project <project-id>
+ot knowledge local search "关键词"
+ot knowledge local read <asset-id>
+ot knowledge local import ./docs --dry-run
+ot knowledge save --body-file knowledge.json --dry-run
+ot knowledge attach <knowledge-id> ./artifact.pdf --dry-run
+```
+
+`ot knowledge search` 默认聚合云端知识和本地索引；仅查一侧时显式使用 `--cloud-only` 或 `--local-only`。本地知识由 CLI 维护，Desktop 知识库界面复用同一实现和原有数据目录。
+
+## Meeting
+
+1. 先解析 Project、Roster 和 Project Context。
+2. 上传录音或读取已有 Meeting；区分事实、讨论、建议、已确认决策和不确定负责人。
+3. 用 `ot meetings publish <meeting-id> --dry-run` 将完整纪要发布为 `kind=meeting` Knowledge。
+4. 用 `ot meetings updates list <meeting-id>` 展示 action、research、decision、risk 草稿，允许逐条编辑或忽略。
+5. 只有用户确认具体条目后，才用 `ot meetings updates confirm <meeting-id> <update-id...> --knowledge <knowledge-id> --dry-run` 物化；没有已保存的 meeting Knowledge ID 时不得确认。
+6. 同一候选只走一次物化路径，禁止重复创建 Todo 或 WorkLog。
+
+## Desktop 边界
+
+以下能力继续使用 Desktop 界面或 `openturtle-desktop` MCP，不调用 `ot`：会话导入/读取/恢复/Fork、本地自动任务调度与 Agent 执行、麦克风和实时录音、文件选择、窗口/托盘/系统通知、跨设备运行时。Desktop 本地知识不在此边界内，统一走 `ot knowledge local ...`。会话内 Goal 直接使用当前 Provider 官方 `/goal`，不依赖 Desktop 自研状态或 OpenTurtle MCP。
+
+飞书/Lark 能力直接使用官方 `lark-cli`。需要会议工作流时先执行 `lark-cli skills read lark-workflow-meeting-summary --json`，再按其中提示读取 `lark-shared`、`lark-vc` 等内嵌 Skill 内容；不要安装整套 `lark-*` Skills。