# cogiumy **Repository Path**: yanjunhua/cogiumy ## Basic Information - **Project Name**: cogiumy - **Description**: 用于个人助理,离线为主 - **Primary Language**: Unknown - **License**: AGPL-3.0 - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-11-08 - **Last Updated**: 2026-11-16 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # Cogiumy 本地优先个人助理的开发预览,依据[项目设计](docs/README.md)。已实现任务与日程的加密存储(合并组整组写入/撤销)、来源与读取范围、基础查询与游标、批量写入、建议与逐单元撤销(逻辑状态身份、精确逆)、失败分类(PARTIAL_COMMIT)、字段分段读取、动作宿主(`tasks.complete/reopen/move/agenda`、日历三动作含参与者解析、`contacts.resolve` 整值解析)、MCP `cog_invoke_read` 与模型呈现(字段级包装、时区偏移、不可见字符转义),并提供 CLI/MCP 演示。应用内助手已接设置页模型配置、持久同意与真实工具调用。 ## 在 Mac 上试用 1. 日用版固定装在 **`~/Applications/Cogiumy.app`**,从 Finder、启动台或 Spotlight 打开这一份即可。更新到新的候选包时运行 `node apps/desktop/install-app.mjs install <候选包路径>/Cogiumy.app`:它核对签名,正常退出正在运行的版本,替换后重新打开并确认进入同一份数据;新版没能打开原数据时会自动换回原来那份。要退回上一版运行 `node apps/desktop/install-app.mjs rollback`,查看安装状态运行 `node apps/desktop/install-app.mjs status`。候选包的位置见[实施现状](docs/implementation/NEXT-STEPS.md)。 2. 全新安装首次打开会直接进入主界面。这台 Mac 的登录钥匙串保管工作区凭据,日常使用无需设置或输入档案口令。如果上次选的是旧 TEST 数据,点 **进入日常工作区** 即可使用独立的任务、日程和笔记。原记录和模型设置保留在旧位置;要取回它们,选 **打开当前档案**,或从 **已有数据与更多选项 → 选择已有数据** 打开原位置。 3. 在主界面创建任务、日程或笔记。按 **⌘K** 搜索标题,例如输入「报销」、`baoxiao` 或 `bx`。从 **设置 → 提醒通知** 启用系统通知后,关闭主窗口仍可收到提醒。可从菜单栏 **C → 打开 Cogiumy** 回到主界面。 4. 要用助手创建任务,在 **设置 → 助手模型** 填写服务协议、地址、模型和密钥,勾选发送对话同意和 **任务**,点 **保存设置** 并完成系统确认。打开 **助手** 后,可输入“创建一个任务,标题为整理书桌”,再到任务列表查看。 5. 手动备份时打开 **C → 档案与后台 → 已有数据与更多选项 → 创建备份**,选保存位置,完成 Mac 身份验证并设置备份口令。恢复时先点 **停止后台**,再选 **从备份恢复**。用备份口令或恢复短语读取备份,在新位置设置新档案口令,完成系统确认后打开恢复的数据。保存笔记附件或下载 MCP 配置文件时,也会请你通过一次 Mac 身份验证。 如果希望登录 Mac 后自动收到提醒,可在 **档案与后台** 选择 **启用登录后后台运行**。若系统提示需要批准,点 **打开系统登录项设置**。使用开发签名的新版取回旧工作区时,如果系统无法沿用之前的凭据,可在 macOS「钥匙串访问」中查看 **Cogiumy 本机工作区恢复口令**,用它打开原有数据。真实睡眠与登录重启仍待实机验收。 ## 从源码运行 ```sh pnpm install --frozen-lockfile pnpm check pnpm build pnpm demo ``` 源码运行要求 Node 24.14.x、pnpm 10.33.0。也可以运行 `pnpm ui` 打开浏览器界面。 1. 首次启动在终端设置并确认档案口令(无回显,至少12字节);打开打印的一次性浏览器链接。 2. 录入自己的任务、笔记和日程;支持完成、修改、删除及逐条撤销。个人档案不填入演示数据。 3. 按 Ctrl+C 退出,下次再运行 `pnpm ui` 并输入相同口令,继续使用原有数据。 数据加密保留在本机固定目录:macOS 为 `~/Library/Application Support/Cogiumy/profiles/default`,Linux 为 `${XDG_DATA_HOME:-~/.local/share}/Cogiumy/profiles/default`,Windows 为 `%LOCALAPPDATA%/Cogiumy/profiles/default`。`pnpm ui --profile /本地路径/个人档案` 可另选目录;同一档案一次只允许一个宿主打开。`pnpm ui [端口]` 或 `--port 端口` 可指定监听端口,仍只监听回环地址。 在“任务”页点击 **导入 CSV**,选择带表头的 UTF-8 逗号分隔文件。核对每列的映射(必须有标题),生成预览,再确认导入。可映射状态、截止日期、描述、优先级、清单、标签和带时区的时间。无效行显示原因;重复任务默认跳过;结果可以整批撤销。 在“任务”页点击 **导入待办(ICS)**,选择含待办(VTODO)的 `.ics` 文件,并为未注明时区的时间选择时区,预览截止、状态和优先级后确认导入。只有日期的截止保持为日期;带时刻的截止按文件时区换算。相同标识或内容的任务默认跳过;重复系列、附带提醒和日程不会导入。导入结果可以整批撤销。 在“联系人”页点击 **导入 vCard**,选择一个或多个 UTF-8 的 `.vcf` 或 `.vcard` 文件(3.0/4.0)。预览每张名片的姓名、电话、邮箱等资料,核对跳过的字段后确认。重复名片默认跳过,同名但资料不同可以各自保留;可从结果中整批撤销。联系人列表显示昵称、别名、关系和首选联系方式。打开详情可逐项新增、修改或移除邮箱与电话,原名片的类型和优先级会随该项保留。照片和不含年份的生日不会导入。 在“笔记”页点击 **导入 Markdown**,选择 `.md`/`.markdown` 文件或文件夹,生成预览后可调整标题、取消选中个别文件,再确认导入。疑似重复内容默认跳过,已有笔记和回收站都不会被覆盖;导入结果中的“撤销这次导入”可整批撤回。默认保留外部来源,只有明确勾选“我自己的数据”才按本人内容导入。 正文原样保留(包括 front matter 和双链文本)。兼容 Obsidian:front matter 的 `title`、`tags` 和正文中的 `#标签`(代码中的除外)会写入笔记标题与标签;笔记详情的"链接"区列出正文中的 `[[双链]]` 指向的笔记,以及提到本笔记的其他笔记。每次最多500份,合计序列化内容768KB;单条写入含标题等最多64KB,正文最多5万字符。超限或编码错误在导入前提示,不静默截断。 在“日历”页点击 **导入 ICS**,选择 `.ics` 文件,并为未注明时区的时间选择时区(如 `Asia/Taipei`),生成预览后核对日期、时间及跳过原因,再确认导入。支持全天、定时日程、标题、说明、地点和标签;标题可修改,整批可撤销。UID相同的日程默认跳过(包括回收站),无UID时按内容提示疑似重复;可明确创建副本,不覆盖旧日程。默认保留 `import:ics` 来源,只有明确本人确认才按本人数据导入。 ICS每次最多50份、500条日程、总量768KB。按天、周(可指定星期)、月、年重复的系列及其例外日期会导入为重复日程,含单次改期或其他规则的系列整组跳过;取消日程和提醒暂不导入,待办请用任务页的“导入待办(ICS)”;未映射字段会显示警告,不发送邀请、不访问附件链接。内嵌时区按文件规则解析;无法准确解释的时间明确跳过,不猜测夏令时歧义。定时事件没有结束时间时保留零时长。导入用于迁入数据,尚不提供外部日历同步;可在“日历”页点击“导出 ICS”导出全部日程。 在“日历”页勾选 **全天**,填写开始日期;结束日期不包含当天,不填则默认一天。例如11月7日至9日的安排,结束日期填11月10日。详情中可编辑日期范围、切换为定时日程并整次撤销;全天日期不随显示时区改变,定时日程按设备本地日期分组。跨多日的全天安排会出现在覆盖日期的“今日”中。 “今日”用本地模板生成当天简报,列出农历、节气、工作日和当天安排。下方时间线将任务截止、任务排程和日程显示在一起;点击“详情”打开原记录,编辑或撤销后同步更新。“日历”默认显示从今天起30天,可填写起止日期(结束日包含当天)、前后翻段;超过100条时点击“继续加载安排”。跨日条目保留完整时间范围,导入标题保留来源标记。在日历的新建表单或详情中选择 **重复**,可按天、周、月、年或农历年创建系列。每周可多选星期,可填写间隔、次数或截至日期。详情中的修改应用到整个系列。月、周、日视图显示农历、节气和调休信息。这两个视图与 MCP `cog_timeline` 使用同一时间线接口;任务排程字段目前可由 SDK/MCP 写入,专用排程表单列入 M1。 MCP的`cog_time`可计算时区和相对日期。例如`{"op":"toUtc","value":"2026-11-09T09:00","zone":"Asia/Taipei"}`返回可直接用于日程/任务排程的UTC时间;`{"op":"resolveRel","expr":"tomorrow+2d","format":"date"}`按档案时区给出日期。遇到夏令时歧义会要求明确时刻。可用 `workday` 查询已收录年份的放假调休,用 `lunar` 查询农历与已收录的节气。完整参数见[客户端契约](specs/client-api.md)。 `pnpm ui --demo` 是退出即删的一次性样本体验;`pnpm demo` 演示创建任务→完成→撤销→查询,也不保留数据。个人档案与样本模式明确分开。 当前提供本机开发签名的 macOS 预览包。请妥善保存档案口令和备份口令。口令找回、恢复短语、G05 格式审查、正式发行签名和 Windows/Linux 实机验收仍待完成。 `pnpm --silent mcp:demo` 启动同样隔离的 MCP stdio 样本服务;stdout 仅输出协议。客户端的命令可以设为 `node`,参数为本工作区 `apps/daemon/src/main.ts` 的绝对路径和 `mcp-demo`。每次进程启动是一个新样本档案,工具不能批准请求。`pnpm --silent tools:schema` 输出实际工具 Schema。 - [实施台账与未完成门禁](docs/implementation/M0.md);[本机可用版进展](docs/implementation/NEXT-STEPS.md) - [可替换 Agent 执行层与宿主注入](docs/implementation/agent-runtime.md)(具体框架为可选适配器;不绑定业务代码) - [公开契约预览](specs/README.md) - [当前状态](STATUS.md)、[有效决策](DECISIONS.md)、[环境与验证约定](CONVENTIONS.md) SDK 为 Apache-2.0;内核、应用和第一方插件采用 AGPL-3.0。当前私有预览未发布;接受外部贡献前仍须按设计补齐许可文本与两项附加许可。 提醒服务已支持统一列表、确认与稍后提醒:SDK `reminders.list/ack/snooze` 和 MCP `cog_reminders` 共用持久状态,稍后提醒不改原任务时间。列表包含尚未触发的提醒,处理要求当前版本以避免覆盖并发决定。界面中可在任务详情设置或清除提醒时间,再到“提醒”页筛选日期与状态、确认或选择稍后时长。确认和稍后提醒不支持通用撤销。macOS 桌面后台可在关闭主窗口后投递系统通知,任务通知可直接完成或稍后 10 分钟。具体参数与限制见[客户端契约](specs/client-api.md#统一提醒消费82c2b1)。 连接外部 AI 客户端(macOS/POSIX 开发预览):运行 `pnpm ui` 解锁个人档案,打开 **设置 → 连接 AI 客户端**。填写名称、逐类勾选允许访问的数据,点击“核对并注册”后在独立窗口完成系统验证。成功后可下载配置或展开查看,保存到 MCP 客户端;离开设置页或关闭配置后无法再次查看。已注册列表显示每个客户端的允许类别,可直接吊销。 也可在另一个终端注册名称与数据类别: ```sh node apps/daemon/src/main.ts mcp-register --client editor --categories tasks,notes,calendar ``` 注册会打开独立原生确认窗口,核对客户端名称、类别和外发说明,并由 macOS 验证身份。成功后终端只输出一次可粘贴到 MCP 客户端的 `mcpServers` 配置,包含独立密钥 `COGIUMY_MCP_TOKEN`;妥善保存该配置。注册需要先按[原生构建约定](CONVENTIONS.md#独立原生确认应用83c2d1b1)生成本机确认应用。取消或拒绝不创建客户端,也不发出配置。 当前类别为 `tasks`、`notes`、`calendar`、`contacts`,以及未声明类别的 `other`;健康、财务、证件对应 `health`、`finance`、`identity`,只有明确列出才允许。`--categories none` 不开放数据类别。客户端一律按云端处理,`local-only` 始终隐藏;返回的数据可能经由客户端自己的模型和工具离开设备。授权持续到吊销。新集合按其声明类别判断,未同意类别及由它们派生的字段不会开放。 配置含客户端密钥,请保存在自己的 MCP 客户端配置中;遗失时可在设置页吊销,再用新名称注册。样本模式只展示连接说明,不开放注册。 配置启动的是 stdio 桥,经权限受限的本地域套接字连接正在运行的同一档案;它不另外解锁或打开数据库。使用自定义档案时,注册命令加 `--profile /本地路径/个人档案`,生成配置会保留该路径。先关闭 `pnpm ui` 后,MCP 不再可用;下次解锁同一档案后原配置可重连。Windows 安全命名管道仍待接入。 在终端使用 Cogiumy(`cogiumy` 命令,macOS/POSIX 开发预览):先运行 Cogiumy 打开档案,再签发一个终端令牌。本人使用: ```sh node apps/daemon/src/main.ts cli-register --name me ``` 给终端里的 AI 编码智能体使用时加 `--ai`(主体为 `ai:cli:<名字>`,会话始终按外部内容处理)。签发会打开独立确认窗口;成功后只输出一次 `COGIUMY_CLI_NAME` 与 `COGIUMY_CLI_TOKEN`,导出到环境变量后即可调用,输出为 JSON: ```sh node apps/daemon/src/main.ts add 明天下午3点 交报告 #工作 !高 node apps/daemon/src/main.ts call records.query '{"query":{"collection":"tasks.task","limit":5}}' ``` `add` 与今日页的快速录入一样:设置页配置了模型、并允许"任务"类别时,先用模型把这句话解析成任务(只发送这句话、当前时间与规则解析的参考结果),4 秒内没有合格结果就按本机规则解析;输入时的预览始终用本机规则。`call` 支持记录读写、动作、撤销、时间线、提醒列表与时间服务;终端令牌不能回答审批、修改授权或注册客户端。`cli-revoke --name me` 吊销令牌。本人令牌还可以运行 `node apps/daemon/src/main.ts doctor` 检查数据库完整性,加 `--rebuild` 从当前记录重建检索索引(不改动数据)。 需要本人处理的请求出现在收件箱,点击“核对”进入独立窗口;允许后由原客户端调用 `cog_approval` 取得结果。目前支持记录、本地动作与计划,撤销和外部效果的完整确认执行仍待接通。随时吊销客户端: ```sh node apps/daemon/src/main.ts mcp-revoke --client editor ``` 吊销会断开该客户端连接并阻止等待中的操作继续写入。当前名称不复用,重新注册请使用新名称;其他客户端和手动界面继续使用。 默认助手模型宿主已支持在档案中加密保存密钥和逐类数据同意,启用前通过独立窗口核对端点、模型和数据范围。模型可调用同一内核工具实际创建/读取任务;停用或减少类别会终止旧操作并清空旧模型会话,收紧不需再次验证,扩大范围需重新批准。配置关闭重开可保留,状态不显示密钥。 在“设置 → 助手模型”选择协议,填写服务地址、模型名称和 API 密钥,勾选发送对话同意及所需数据类别,再点击“保存设置”。首次同意默认未选;启用、修改配置或扩大范围将打开独立窗口并要求系统验证。保存后点击“助手”开始对话。支持流式输出的模型会逐段显示回复。看到回复时仍可点“停止”,已执行的操作可在活动中核对。没有系统确认能力时仍可收紧已授权类别或停用。 密钥不会回显,提交或离开设置页立即清空输入;同地址留空可保留原加密密钥,更换地址必须重新输入。保存不测试服务,首次对话才连接模型。收紧或停用不需要重复系统验证;取消对话同意后保存也会停用。已执行的操作可在活动中核对,重开同一档案后可继续当前对话,也可在助手的历史记录里选择其他对话。 助手遇到需要本人决定的记录写入、本地动作、计划或建议时,会在面板显示“需要你核对”,暂停当前工具调用。点击“打开独立核对窗口”,核对内核显示的实际内容并完成系统验证;允许后自动取得原请求结果,继续同一对话,拒绝则把拒绝结果交回助手。取消窗口会保留等待,可再次核对或停止本轮;停止不撤销已执行的操作,未处理请求仍在收件箱。没有可用确认窗口、以及尚不支持的撤销/外部效果流程会明确提示,不能由聊天回复代替批准。 默认助手读取经确认的持久配置,环境变量不再自动触发模型问答。未知本机模型端点也按云端处理;正式本地检测、供应商/地区预设、模型能力自检与每日预算仍待完成。在此 Mac 的独立测试档案中,用户完成系统确认后,`glm-5.3-flash` 已通过助手创建一条真实任务,重开后可以核对任务和对话。 跨步骤任务可由助手使用 `cog_plan` 合成一张核对卡:独立窗口列明每步动作、目标和记录差异,AI 撰写的计划说明单独标注作者。批准后按保存的步骤顺序执行,重复取结果不会重做;若某一步失败,报告已执行、失败与跳过的步骤,只补偿失败动作的本地写入,已完成步骤可在活动中核对与撤销。当前限于本地记录/动作,外部发送与撤销的批准后执行仍待接入。