ChrisTkm/nostromo_cortex

来源：https://github.com/ChrisTkm/nostromo_cortex

Cortex Banner

Cortex

Cortex 是一个 面向工程团队的本地优先知识驾驶舱：它在 VS Code 内结合了执行图、文档导航、笔记、日志和遥测。从类别上讲，Cortex 位于以下领域的交集：

• 本地知识图谱：用于 .md/.mdx 文档、标签、引用和概念。
• 项目智能 / 执行图：用于计划、依赖任务、状态、阻塞和循环。
• 开发者操作驾驶舱：用于操作笔记、日志、提醒、归档和遥测。
• 文档架构工具：用于检测孤立文档、损坏的引用和技术知识中连接稀疏的区域。

所有功能都在工作区附近运行：本地文件、VS Code、本地 MongoDB（适用时）、内存快照和 React Flow Webview。

TypeScript (https://www.typescriptlang.org/)
Node.js (https://nodejs.org/)
MongoDB (https://www.mongodb.com/)
VS Code (https://code.visualstudio.com/api)
React Flow (https://reactflow.dev/)

解决的问题

Cortex 诞生之初是一个内部工具，旨在解决复杂计划状态和分散技术知识难以追踪的问题：例如长期重构、任务间的依赖关系、Markdown/MDX 文档、技术笔记和操作日志。具体攻击的问题是：当一个计划有二十个交叉依赖的任务，或者一份文档通过标签和引用连接了几十页时，纯列表视图远远不够。你需要一个可导航的图谱、跨会话的持久性以及操作界面的一键可达。

模块

Cortex 提供 8 个模块（Webview）及一个侧边栏：

此外还有：侧边栏 Task Navigator（cortex.openTasks），以按计划分组的任务树形式展示；Plan Editor（从 Graph 或 Plans 打开），用于完整编辑元数据和任务。面板切换快捷键：Ctrl+Alt+Shift+N / Ctrl+Alt+N。过滤器按计划、项目、标签、状态和严重级别持久化。

截图

Graph — PERT/DAG 图，采用 Dagre 布局、循环检测，并叠加活动计划的进度、任务和元数据。

Plans — 所有计划的数据表格，支持按状态/产品/版本/作者筛选、搜索、进度显示和包含详细信息的抽屉。

Archive — 归档计划及其冻结任务的探索，支持搜索和导出。Cortex 不仅可视化，还保留历史。

架构视图

VS Code Extension Host (Node)
|
|-- SharedMongoClient (单例，复用连接池)
|   |
|   |-- MongoTaskStore (任务 + ensureIndexes)
|   |-- MongoActionPlanStore (计划 + ensureIndexes)
|   |-- MongoNoteStore (笔记 + ensureIndexes)
|   '-- Logs collection (只读)
|
|-- ExtensionTaskService
|   '-- buildGraphSnapshot (纯函数，内存中)
|
'-- Webviews (esbuild, IIFE, 生产环境压缩)
    |-- Graph (React + React Flow + Dagre)
    |-- Plans (React + DataTable + 抽屉)
    |-- Ledger (React + DataTable + 遥测)
    |-- Notes (React + Markdown 编辑器)
    |-- Logs (React + 分页列表)
    |-- Archive (React + 归档计划)
    |-- Brain (React Flow + 本地扫描 .md/.mdx)
    '-- Script Flow (TS / Python / SQL)

Webview 从不直接与 MongoDB 通信。扩展在主机中解析数据，并发送序列化的 JSON 快照。

相关设计决策

• 共享 Mongo 客户端：每个扩展会话只有一个 MongoClient 实例，在 activate() 中打开，在 deactivate() 中关闭。之前每次操作都打开和关闭，导致每次刷新手势倍增。
• 持久化过滤器状态：缩放、平移、选中的计划和过滤器在 VS Code 重启后依然存在。针对旧版 workspaceState 形状进行防御性结构合并。
• 内存数据的纯算法：拓扑排序使用 Kahn 算法（O(V+E)），避免在循环内排序。批量写入使用 bulkWrite 并设置 ordered: false。
• Mongo 索引幂等性：扩展激活时调用 ensureIndexes()。code_unique 使用部分过滤器（仅在该字段存在且为字符串时），以兼容旧数据。
• 生产环境压缩包：esbuild 的四个入口点（extension, graph, notes, logs）均链接 sourcemap。观察模式不压缩，以保留错误可读性。
• 结构化日志：扩展主机不使用 console.log；所有可观察性通过一个可配置的日志记录器（pretty / json）传递，并附带组件上下文。

组件

• apps/vscode-extension — VS Code 扩展，包含文本导航、PERT/DAG、Notes、Logs、Archive、Cortex Brain 和 Script Flow（参见 节点和边词汇表）。
• apps/mcp-server — 本地 MCP 服务器，提供关于任务和遥测的工具、资源和提示。
• packages/core — 共享领域：类型、Zod 规范化、图、Mongo 和种子数据。
• packages/telemetry — 可复用的遥测层，包含版本化定价、日志和本地持久化。

技术栈

• TypeScript 在整个 monorepo 中严格使用。
• MongoDB 本地作为真实来源。
• React + React Flow + Dagre 用于 Webview 中的图。
• esbuild 用于打包（扩展主机 CJS，Webview IIFE）。
• Zod 用于防御性文档规范化。
• Vitest 用于单元测试。
• pnpm workspaces 作为包管理器。

面板与键盘快捷键

从任何面板中，cortex.showOptions 打开一个 QuickPick，可访问 8 个模块和过滤器。Graph/Plans/Ledger/Notes/Logs/Archive 共享同一个 SharedMongoClient；Brain 在没有 Mongo 的情况下操作本地文件夹。

v0.1.6 版本

本次发布专注于改进 Cortex Brain 对 Starlight 文档的支持，并优化 MD/MDX 图的读取体验。

• Cortex Brain + Starlight：现在，诸如 href="/accounting/activos-fijos/" 的绝对链接可以解析到 src/content/docs 和 content/docs 下的文档，即使 Brain 是从项目根目录或像 accounting 这样的子部分进行扫描。这避免了错误的外部节点，并正确绘制 Starlight 的内部关系。
• 关系过滤器：Brain 将 related.upstream、related.downstream、related.standards 和 related.accounts 分开；面板允许单独开启或关闭这些关系线的显示，以及链接、标签和未解析项。
• 索引器覆盖率：添加了针对性测试，确保 Starlight 绝对路径链接到对应的 .mdx 文档。
• 构建/Webview：包含 Brain 面板的更新包以及待定的图形视觉调整。

v0.1.5 版本

本次发布专注于关闭扩展的日常操作功能：计划归档、更易浏览的日志、更清晰的 PERT 图以及 Webview 安全调整。

• Archive 面板：新增界面 Cortex: Open Archive，用于浏览归档计划及其任务。done 状态的计划可以从导航器通过 cortex.archivePlan 归档；目标路径由 cortex.archivePath 配置，默认为 ~/cortex-archive。
• 按执行 ID 分组的日志：Logs 面板按 execution_id 分组事件，旧版文档保留在 ungrouped 部分，新增 tag 过滤器。Python 生产者的预期合约记录在 docs/log-contract.md 中。
• PERT 图优化：对不完整或不一致的数据显示可见警告，计划标题更清晰，间距调整，布局更少重叠。
• 安全强化：Mongo URL 通过 Cortex: Set Mongo URL 在 VS Code SecretStorage 中管理；设置项 cortex.mongoUrl 保留为弃用兼容项。
• Notes 面板：修复滚动问题，确保编辑器和列表在长时间会话中保持稳定体验。
• Cortex Brain：新增轻量级面板，用于选择本地文件夹、扫描 .md/.mdx 文件并通过链接、标签、路径和会计账户渲染关系，无需依赖 Mongo。
• 构建/Webview：为 Archive 添加专用包，并更新面板的资产和图标。

v0.1.4 版本

基于 0.1.3 的维护版本。无新功能，重点在于包稳定性和 MongoDB 连接稳定性。

• 默认 Mongo URL 从 mongodb://localhost:27017 改为 mongodb://127.0.0.1:27017（配置、设置、服务和测试）。这避免了 Node 解析器在双栈主机上优先尝试 IPv6 而 Mongo 仅监听 IPv4 时出现的延迟/超时。
• esbuild CJS 打包：web-tree-sitter 现在内联打包到 dist/extension.cjs 中。从 external 数组中移除，并通过 banner + define 注入 import.meta.url 的 shim，使 ESM 模块能在扩展主机的 CommonJS 包中运行。
• Notes 面板：Webview 的 ready 消息处理器不再在收到同一事件的回放时重新发出初始模式。添加测试验证在多次 ready 时 open 只发送一次。
• 内部重构 useNotesController.ts 并重建 media/notes.js。

v0.1.3 版本

v0.1.3 分支完成了扩展中 Notes + Reminders + Script Flow 的功能周期。

笔记中的提醒

• 每张笔记可以在 Notes 面板编辑器中保存一个一次性提醒时间 remindAt。
• 状态栏中的铃铛图标显示待提醒的数量，并打开聚焦于提醒的 Notes 面板。
• 启动 VS Code 时，扩展执行 fireDue(..., "startup")，然后通过 scheduleAll(...) 重新安排定时器，因此当 VS Code 关闭时到期的提醒在重新打开时会再次触发。
• 提醒流程支持 snooze 和 dismiss：推迟会将 remindAt 向前移动并清除 remindedAt；忽略则将 remindedAt 标记，避免再次处理。

Script Flow 面板

• Script Flow 面板现在可以分析 .ts、.tsx、.py 和 .sql 文件。
• 可以通过 Cortex: Open Script Flow 或编辑器上下文菜单打开。
• 如果选择了活动区域，Cortex: Open Script Flow for Selection 将分析范围限定在所选区域。
• 面板维护节点导航、分析抽屉、交互遥测以及编辑器的点击定位范围。
• SQL 在扩展主机中使用 node-sql-parser 解析，首先尝试 postgresql，然后回退到 mysql。

新的及重要的命令

• cortex.openNotes
• cortex.newNote
• cortex.editNote
• cortex.deleteNote
• cortex.snoozeReminder
• cortex.openLogs
• cortex.openScriptFlow
• cortex.openScriptFlowForSelection
• cortex.togglePlanStatusFilter

已知限制

• Script Flow 仍然是单文件：不解析 imports 或跨文件依赖。
• SQL 覆盖了 WITH/CTE、SELECT、JOIN 和常见子查询的最小可行产品；不追求完整语言覆盖。
• 提醒是一次性的；没有周期性或复杂日历。
• 在最终合并前，建议进行手动 UX 冒烟测试，因为包和测试夹具不能替代完整的交互运行。

Notes 面板

笔记的 CRUD 持久化在与任务/计划相同的 Mongo 实例中。

• 字段：code、title、body（Markdown）、tags[]、taskCode?、planCode?、pinned、createdAt、updatedAt。
• 命令：Cortex: Open notes panel、Cortex: New note、Cortex: Edit note、Cortex: Delete note。
• 配置：cortex.mongoNotesCollection（默认 notes）。
• 索引：code_unique、task_code_idx、plan_code_idx、updated_at_desc_idx。

Logs 面板

只读面板，显示 Mongo 中持久化的最后 500 个事件。

• 配置：cortex.mongoLogsCollection（默认 logs）。
• 索引：logs_source_timestamp、logs_level_timestamp、logs_process_timestamp。

根脚本

• pnpm install
• pnpm dev
• pnpm build
• pnpm test
• pnpm lint
• pnpm mongo:up
• pnpm seed
• pnpm check:cycles
• pnpm inspect:snapshot
• pnpm inspect:telemetry:runs
• pnpm inspect:telemetry:failures
• pnpm inspect:cost

文档

• 架构
• 本地开发
• 日志合约
• Script Flow 词汇表