Orthic-Labs/Cortex

**Cortex 将代码和文档转化为本地、有证据支撑的仓库映射图，让人和智能体（agent）在更改系统之前，能够查明什么是真实的、过时的、矛盾的，或者仍然未知的。** 节点、边和流分别被命名为 **Neurons**、**Synapses** 和 **Circuits**。 [](LICENSE) [](#local-sqlite-graph) ## 它是什么 Cortex 会读取仓库的架构文档、计划、ADR、源文件、符号、调用、测试和配置，然后指出哪些结论是有据可查的、过时的、矛盾的，或仍然未知的。代码讲述了系统故事的一部分，而文档讲述了另一部分，除非将两者进行比对，否则任何一方都无法保持可信。Cortex 会执行这种比对，并将每个结论都与确切的证据相绑定。 ## 工作原理 ``` documents + code + tests + config │ ▼ deterministic repository map │ ▼ local SQLite evidence graph │ ▼ claim verification + synthesis │ ├── machine artifacts for agents └── product + architecture docs for humans ``` Cortex 的运行分为两个阶段： 1. 映射（Map）—— 确定性的代码映射，将文档、声明、文件、符号和关系映射到受版本约束的图中。 2. 理解（Understand）—— 基于证据的验证，将文档声明与源码进行比对，然后综合分析架构、接口、安全性、健康状况、生产就绪情况以及未覆盖的流程。 映射成本低且可重复。高层级的结论始终与确切的证据绑定，而不是脱离证据凭空存在。 ## 快速开始 ``` npm install # or pnpm install python3 -m pip install -r requirements-test.txt npm test # standalone package tests (tests/*.test.mjs) npm run test:workspace # monorepo context-contract suite (tests/workspace/) npm run test:all # both, serialized for watcher/performance isolation ``` 需要 Node `>=20`；完整的测试还需要 Python `>=3.11` 以及 `requirements-test.txt` 中的包（工作区上下文契约套件会通过 shell 调用 `jsonschema`）。CLI 入口点：`cortex`。 ``` cortex # complete Cortex workflow cortex "" # task-focused repository understanding cortex doctor --full --json # freshness, coverage, and artifact health cortex graph search --query "authentication" cortex graph neighbors --node "" cortex graph path --from "" --to "" cortex graph impact --node "" cortex graph architecture cortex graph doc-truth cortex graph export ``` Cortex 还可以为更大的上下文规划器输出有边界的 `ContextCandidateSet`：这是一个附带证据和新鲜度、且与任务相关的切片，而不是整个图。 ## 文档真相 Cortex 将文档视为数据，而不是装饰。它会读取当前的文档、ADR、计划和配置的归档，然后： - 提取带有源路径和行号证据的单个声明； - 将声明链接到所提及的代码、符号以及候选的验证文件； - 将文档的生命周期记录为当前、历史、已废弃或标记无效； - 将已废弃的文档作为来源保留，同时将其从当前事实中排除； - 应用优先级，确保旧计划不能凌驾于当前代码之上； - 将证据关联状态设为 `supports`（支持）、`contradicts`（矛盾）或 `supersedes`（替代）； - 标记过时的引用、无根据的声明以及代码与文档不一致的地方； - 将其自身生成的文档从未来的声明提取中排除，从而避免它陷入自我证实的循环。 阶段 2 会将每个定论与确切的文档和代码指纹绑定。当输入未发生改变时，Cortex 会复用该定论；当某个声明或文件发生改变时，仅重新计算受影响的定论和综合维度。调和记录会保持暴露不一致的情况，直到由人工决定是修改代码还是修改文档。 ## 本地 SQLite 图 每个被映射的仓库都会获得一个派生的、被 gitignore 忽略的存储：`.agent/graph/graph.db`。Cortex 使用 Node 内置的 `node:sqlite`，因此核心存储不需要数据库服务器或原生 SQLite 包。 | 表 | 存储内容 | 重要索引 | |---|---|---| | `files` | 路径、哈希、语言、解析状态、文件节点数据 | generation | | `symbols` | 函数、类型、组件、路由、其他命名的代码对象 | path, generation | | `edges` | 导入、调用、引用、包含、配置、其他关系 | source, target, kind, confidence tier, generation | | `generation` | 清单、provider 组合、文档真相、源观察 | key | | `meta` | 存储模式（schema）版本 | key | | `vectors` | 可选的未来 embedding | model, generation | 该存储在 WAL 模式下运行。构建过程会在事务中写入关系行及其 generation 信封，因此读取者看到的要么是上一个完整的 generation，要么是下一个，绝不会是写入了一半的映射。只读消费者永远不会迁移数据库。查询使用索引化的文件和符号查找、紧凑的边缘核心，并选择性加载完整的节点或边；`neighbors`、`path`、`impact` 和 `architecture` 的响应受 token 预算限制，进行确定性排序，并且可以返回继续游标。每个响应都携带新鲜度信息：generation ID、源状态、脏文件计数。 虽然存在向量存储，但 embedding 默认是关闭的，且 Cortex 目前不生成它们。结构化证据始终是首要的。 ## 代码智能 Cortex 依次结合了三个精度级别：`COMPILER > AST > LEXICAL`。 - Tree-sitter 和 AST 解析涵盖了支持语言的选定结构层。 - 确定性的词法提取是一种广泛且可移植的后备方案，适用于代码、脚本和 schema。 - SCIP 和编译器证据在仓库已经提供可移植的 SCIP JSON 导出时，提供可选的精确引用增强；Cortex 绝不会自行安装或运行索引器。 每条边会单独记录其解析置信度：`EXACT_RESOLUTION > SAME_FILE_LEXICAL > CROSS_FILE_HEURISTIC > UNRESOLVED`。模棱两可的关系将保持未解析状态，而不是靠猜测；消费者可以按最低置信度级别进行过滤。 ## 定向准入 `@orthic-labs/cortex` 还导出了一个仅用于决策的准入 API，而不是阻断性的门控： ``` import { createAdmission } from "@orthic-labs/cortex/admission"; const api = createAdmission({ storeDir, evidenceDir }); const decision = await api.orient({ task, sessionId, repoRoot }); // decision.action: allow | continue | block | noop ``` 回执是主机拥有的本地数据。Sentinel 可消费的定向证据是从这些回执中派生出来的。Fail-closed 钩子、shell 分类器、MCP 强制执行和 CodeRight 代理均不在此核心库的范围内。 ## 输出 `.agent/` 下的机器可读输出： - `map.json`, `claims.json`, `stale.json`, `index.json` — 文档和代码映射； - `queue.json` — 声明与可能的验证证据配对； - `flows.json` — 有边界的产品流清单； - `phase2-plan.json` — 需要复用或重新计算的确切验证和综合工作； - `verdicts.json` — 受版本约束的声明定论； - `understanding.json` — 六维度的仓库理解； - `reconcile.json` — 未解决的代码与文档分歧； - `graph/graph.db` — 完整的本地 SQLite 图。 `.blueprint/manifest.json` 暴露了仓库身份、provider 能力、generation 和覆盖率，且不会提交本地数据库。 人类可读的文档生成于 `docs/product.md`（基于代码的产品概述）和 `docs/architecture.md`（组件、接口、流程、风险、缺口）。 ## 独特之处 - 代码和文档真相被共同映射：实现和既定意图并存，而不是非此即彼。 - 证据谱系：重要的声明保留了路径、跨度、哈希、provider、generation 和置信度。 - 矛盾被显现出来，而不是被平均化掩盖。 - 构造层面的新鲜度：提交、脏文件覆盖层、provider 版本和内容指纹只会使其影响的证据失效。 - 有边界的检索：智能体获取与任务相关的图切片，并附带省略和新鲜度元数据。 - 诚实的置信度：不支持的语言、被截断的扫描和模棱两可的边会保持可见，而不是被隐藏。 - 人类和机器的视图来源于相同的证据：为智能体提供可查询的工件，为人类提供可读的文档。 - Provider 是可替换的：当解析器改进时，SQLite schema 和可移植的清单保持稳定。 ## 信任模型 仓库内容是不受信任的数据，绝不是智能体指令。Cortex 会对输出中的机密信息进行脱敏，将读取范围限制在仓库范围内，并且绝不会将生成的散文作为主要证据。当前代码和可执行证明的优先级高于计划或历史文档。图结果缩小了读取范围；对于安全敏感、发布或破坏性的更改，它们不能替代源码检查。 ## 状态 Cortex 已经作为仓库映射器、SQLite 图、有边界的查询接口、文档真相层、增量式阶段 2 规划器以及人类/机器工件生成器上线。目前的限制： - 解析深度因语言而异；词法回退的覆盖范围比 AST 更广； - 如果没有可执行或编译器证据，动态运行时注册可能仍无法解析； - 可选的 SCIP 精度需要仓库提供导出文件； - embedding 和语义向量搜索未激活； - 暂未提供交互式的可视化图浏览器； - 原始图数据不会被复制到持久化记忆中。 完整的智能体工作流和工件契约：[`SKILL.md`](SKILL.md)。当前实现情况：[`references/IMPLEMENTATION-STATUS.md`](references/IMPLEMENTATION-STATUS.md)。 源码可见的专有许可证，仅供内部使用和评估；禁止重新分发、重新打包和竞争性使用。参见 [LICENSE](LICENSE)。 ## 仓库真相文档 - [产品概述](docs/product.md) — 它是什么以及做什么（生成的，基于代码） - [架构](docs/architecture.md) — 组件、流程、接口（生成的，基于代码） _{Orthic Labs — AI 辅助开发的本地优先基础设施。
Membrane · Cortex · Sentinel · Roundtable · Morph · CutRight · claudecodeX}

标签：AI辅助编程, MITM代理, SOC Prime, SQLite, 代码分析, 凭证管理, 开发工具, 文档生成, 架构分析, 自定义脚本, 逆向工具