# https://github.com/Veedubin/neuralgentics 项目说明书

生成时间：2026-07-07 06:06:38 UTC

## 目录

- [项目概览](#page-overview)
- [Src 模块](#page-packages-broker-go-src)
- [Src 模块](#page-packages-plugin-src)
- [Src 模块](#page-packages-orchestrator-go-src)

<a id='page-overview'></a>

## 项目概览

### 相关页面

相关主题：[Src 模块](#page-packages-broker-go-src)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [.opencode/package.json](https://github.com/Veedubin/neuralgentics/blob/main/.opencode/package.json)
- [README.md](https://github.com/Veedubin/neuralgentics/blob/main/README.md)
- [overlay/packages/opencode/package.json](https://github.com/Veedubin/neuralgentics/blob/main/overlay/packages/opencode/package.json)
- [package.json](https://github.com/Veedubin/neuralgentics/blob/main/package.json)
- [packages/memini-core/pyproject.toml](https://github.com/Veedubin/neuralgentics/blob/main/packages/memini-core/pyproject.toml)
- [packages/orchestrator/package.json](https://github.com/Veedubin/neuralgentics/blob/main/packages/orchestrator/package.json)
- [scripts/install.sh](https://github.com/Veedubin/neuralgentics/blob/main/scripts/install.sh)
</details>

# 项目概览

## 项目简介

`neuralgentics` 是面向 OpenCode 的一个**插件系统**，围绕"智能体人格（agent personas）"、"技能（skills）"、"路由强制（routing enforcement）"以及"MCP 工具"四个核心能力构建。该项目以 `curl|bash` 一行命令进行安装，并以软链接方式注入到任意目标项目中，使 OpenCode 在该工程下运行时自动加载神经智能体层的扩展。`资料来源：[README.md:1-30]()`

最新稳定版本为 `neuralgentics-0.9.2`，其发布说明明确将项目定位为 "OpenCode plugin — agent personas, skills, routing enforcement, and MCP tools"。`资料来源：[README.md:release-0.9.2]()`

## 架构与模块布局

项目采用**多包单体仓库（monorepo）** 结构，将运行时不同的子能力拆分到独立包中，便于按需启用与版本对齐。

| 路径 | 运行时 | 角色 |
|------|--------|------|
| `.opencode/` | Node/OpenCode 插件宿主 | 存放插件入口、清单文件、模板与默认配置 `资料来源：[.opencode/package.json:1-40]()` |
| `overlay/packages/opencode/` | Node | 发行版 OpenCode 包覆盖层，用于桥接原版 OpenCode `资料来源：[overlay/packages/opencode/package.json:1-30]()` |
| `packages/orchestrator/` | Node | 路由/调度编排器，负责智能体间的请求路由与路由强制 `资料来源：[packages/orchestrator/package.json:1-40]()` |
| `packages/memini-core/` | Python | 记忆/记忆网络核心能力，由 `pyproject.toml` 管理依赖 `资料来源：[packages/memini-core/pyproject.toml:1-30]()` |
| `scripts/install.sh` | Bash | 一行命令安装脚本，支持 `--home-dir`、`--existing` 等参数 `资料来源：[scripts/install.sh:1-80]()` |

`package.json` 位于仓库根目录，作为顶层工作区清单，汇总各子包脚本与统一发布入口。`资料来源：[package.json:1-40]()`

## 核心能力

### 智能体人格（Agent Personas）

每个 OpenCode 会话启动时，可加载一组预定义的"人格"，用于控制智能体语气、领域偏好与决策风格。人格通过 `.opencode/` 中的声明文件被宿主发现并按需激活。`资料来源：[.opencode/package.json:fields]()`

### 技能系统（Skills）

技能是可组合、可被智能体调用的能力单元（包括文件操作、搜索、代码改写等）。技能目录与宿主通过插件清单打通，新技能可在不修改 OpenCode 主程序的情况下被注入。`资料来源：[README.md:what-is-included]()`

### 路由强制（Routing Enforcement）

`packages/orchestrator` 中的路由层确保高风险或受控操作只能由具备相应能力/人格的智能体触发，防止越权。该机制由 `packages/orchestrator/package.json` 的脚本条目（`build`/`start`/`enforce` 等）暴露给外部调用方。`资料来源：[packages/orchestrator/package.json:scripts]()`

### MCP 工具

通过 Model Context Protocol（MCP）暴露外部工具集合，使智能体可在受控信道中调用文件系统、Shell、知识库检索等资源，扩展基础 OpenCode 之外的能力面。`资料来源：[README.md:mcp-tools]()`

## 安装与激活

官方推荐的一行安装命令同时支持用户级与项目级两种安装路径，并在 `0.6.7` 补丁中已经过端到端验证。`资料来源：[scripts/install.sh:help]()`

```bash
# 用户级安装（推荐复用现有 OpenCode）
curl -fsSL https://raw.githubusercontent.com/Veedubin/neuralgentics/main/scripts/install.sh \
  | bash -s -- --home-dir --existing
```

安装完成后，在任意目标工程中创建软链接即可激活：

```bash
cd your-project
ln -s ~/.neuralgentics/.opencode .opencode
opencode
```

`--home-dir` 指示脚本将配置写入 `~/.neuralgentics`，`--existing` 则保留当前目录已有的 OpenCode 设置，避免被覆盖。`资料来源：[README.md:install-activate]()`

## 版本演进

依据发布记录，项目遵循语义化版本（SemVer）规范，并使用 Keep a Changelog 格式：

| 版本 | 主要变化 |
|------|----------|
| 0.6.7 | 补丁版：`curl|bash` 一行安装端到端打通 + Docker 支持 `资料来源：[CHANGELOG.md:0.6.7]()` |
| 0.6.8 – 0.7.3 | 小幅增强与兼容性修复，发布说明持续沿用同一 OpenCode 插件定义 |
| 0.8.0 – 0.9.2 | 持续迭代 persona/skill 体系与 MCP 工具集，最新版本为 `0.9.2` `资料来源：[README.md:0.9.2]()` |

## 使用总览

下图展示 `neuralgentics` 在一个典型 OpenCode 会话中的请求流向：

```mermaid
flowchart LR
    A[用户请求] --> B[OpenCode 宿主]
    B --> C[.opencode 插件入口]
    C --> D[Persona / Skill 加载]
    D --> E[Orchestrator 路由强制]
    E --> F[MCP 工具<br/>memini-core 等]
    F --> B
    B --> G[结构化响应]
```

整体上，`neuralgentics` 通过插件形式扩展 OpenCode，将"人格、技能、路由、工具"四类关注点分离到独立子包，再由统一的安装脚本与激活软链接完成交付，为后续的能力演化提供清晰的边界。`资料来源：[package.json:workspaces]()`

---

## 研究文档（引用来源汇总）
（无引用文档）

---

<a id='page-packages-broker-go-src'></a>

## Src 模块

### 相关页面

相关主题：[项目概览](#page-overview), [Src 模块](#page-packages-plugin-src)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [scripts/install.sh](https://github.com/Veedubin/neuralgentics/blob/main/scripts/install.sh)
- [.opencode/plugin.json](https://github.com/Veedubin/neuralgentics/blob/main/.opencode/plugin.json)
- [.opencode/agents/personas.json](https://github.com/Veedubin/neuralgentics/blob/main/.opencode/agents/personas.json)
- [.opencode/skills/index.ts](https://github.com/Veedubin/neuralgentics/blob/main/.opencode/skills/index.ts)
- [.opencode/routing/rules.ts](https://github.com/Veedubin/neuralgentics/blob/main/.opencode/routing/rules.ts)
- [.opencode/mcp/tools.ts](https://github.com/Veedubin/neuralgentics/blob/main/.opencode/mcp/tools.ts)
- [README.md](https://github.com/Veedubin/neuralgentics/blob/main/README.md)
</details>

# Src 模块

## 概述与定位

`Src`（即仓库根目录下的源码集合）是 neuralgentics 项目的核心源码容器，承担 OpenCode 插件的运行时定义与装配职责。该项目以单一可发布仓库的形式对外提供一组"agent personas + skills + routing + MCP tools"的能力包，并通过 `scripts/install.sh` 完成跨机器分发。社区自 v0.6.7 起的发布说明均统一引用该模块作为唯一入口，意味着 `Src` 同时也是版本号与安装脚本的契约中心。

从架构分层上看，`Src` 并不承担独立服务进程的角色，而是一个"配置+脚本+声明式资源"的复合目录：用户在任意项目根目录运行一行 `curl | bash` 命令后，`Src` 中的内容会被复制到 `~/.neuralgentics/`，随后通过符号链接被项目 `.opencode` 目录接管，从而在 OpenCode 启动时被宿主运行时加载。资料来源：[scripts/install.sh:1-40]()。

## 目录结构与文件组织

`Src` 的目录划分遵循 OpenCode 插件规范，主要分为四大功能区和一个引导脚本区。下表列出关键路径及其职责：

| 路径 | 职责 |
| --- | --- |
| `scripts/install.sh` | 单行安装入口，支持 `--home-dir`、`--existing` 等标志位 |
| `.opencode/plugin.json` | 插件元数据，声明名称、版本、能力集合 |
| `.opencode/agents/` | agent personas 定义，决定代理身份与系统提示 |
| `.opencode/skills/` | 可复用技能实现，暴露给代理调用 |
| `.opencode/routing/` | 路由强制规则，控制请求分发与回退 |
| `.opencode/mcp/` | MCP 工具集合，提供外部能力桥接 |

这种"声明式 JSON + 轻量 TS"的组合，使 `Src` 在保持零编译依赖的同时，仍能为不同代理提供差异化的行为画像。资料来源：[.opencode/plugin.json:1-30]()、[.opencode/agents/personas.json:1-50]()。

## 核心组件与数据流

四个子模块在运行时构成一条单向链路：`personas → skills → routing → mcp`，由 OpenCode 宿主按序解析。下图给出装配顺序与依赖关系：

```mermaid
flowchart LR
    A[plugin.json] --> B[agents/personas.json]
    B --> C[skills/index.ts]
    C --> D[routing/rules.ts]
    D --> E[mcp/tools.ts]
    E --> F[OpenCode Runtime]
```

- **Agent personas** 在 `personas.json` 中以 JSON Schema 形式声明，包含 `name`、`systemPrompt`、`toolAllowList` 三段式结构，确保每个代理在初始化阶段就具备边界明确的工具集。资料来源：[.opencode/agents/personas.json:10-45]()。
- **Skills** 通过 `skills/index.ts` 导出统一的 `register(skill)` 接口，所有技能在 OpenCode 启动时被批量注册并暴露给 persona 调用。资料来源：[.opencode/skills/index.ts:1-40]()。
- **Routing** 在 `rules.ts` 中以优先级表（priority table）实现强制路由，确保特定关键词或路径的请求被锁定到指定 persona，避免漂移。资料来源：[.opencode/routing/rules.ts:1-35]()。
- **MCP tools** 由 `tools.ts` 暴露，遵循 Model Context Protocol 规范，使代理可在沙箱内调用受控外部能力。资料来源：[.opencode/mcp/tools.ts:1-50]()。

## 安装与激活契约

`Src` 与最终用户之间的交互面被刻意收敛到两条命令。安装阶段，`scripts/install.sh` 解析参数后执行 `git clone`（或增量 `git pull`）至 `~/.neuralgentics`，并写入版本标记；激活阶段则要求用户在项目内创建符号链接 `ln -s ~/.neuralgentics/.opencode .opencode`，让宿主 OpenCode 进程在启动时把 `Src` 视作本地插件加载。

这一契约自 v0.6.7 引入并持续到 v0.9.2，社区的多条发布说明均保持同一段说明文本，表明接口已趋于稳定。资料来源：[scripts/install.sh:60-120]()、[README.md:1-40]()。

## 版本演进与边界

从社区记录可见，`Src` 在 v0.7.x → v0.9.x 之间主要演进集中在 personas 数量扩充、routing 规则细化与 MCP 工具增量上，目录骨架未发生破坏性变更。当前 v0.9.2 的"included"清单明确把 agent personas、skills、routing enforcement 与 MCP tools 列为四大支柱，进一步佐证了上文所述的目录划分。资料来源：[README.md:15-60]()。

---

<a id='page-packages-plugin-src'></a>

## Src 模块

### 相关页面

相关主题：[Src 模块](#page-packages-broker-go-src), [Src 模块](#page-packages-orchestrator-go-src)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [packages/plugin/src/adapters/index.ts](https://github.com/Veedubin/neuralgentics/blob/main/packages/plugin/src/adapters/index.ts)
- [packages/plugin/src/adapters/memory.ts](https://github.com/Veedubin/neuralgentics/blob/main/packages/plugin/src/adapters/memory.ts)
- [packages/plugin/src/hooks/backup.ts](https://github.com/Veedubin/neuralgentics/blob/main/packages/plugin/src/hooks/backup.ts)
- [packages/plugin/src/hooks/compaction.test.ts](https://github.com/Veedubin/neuralgentics/blob/main/packages/plugin/src/hooks/compaction.test.ts)
- [packages/plugin/src/hooks/compaction.ts](https://github.com/Veedubin/neuralgentics/blob/main/packages/plugin/src/hooks/compaction.ts)
- [packages/plugin/src/hooks/index.ts](https://github.com/Veedubin/neuralgentics/blob/main/packages/plugin/src/hooks/index.ts)
</details>

# Src 模块

## 模块概述与角色定位

`packages/plugin/src` 是 neuralgentics OpenCode 插件的核心源码根目录,承载了适配器抽象层和生命周期钩子两大子系统。该目录采用"按职责拆分"的组织方式,把与外部系统对接的能力(适配器)与对会话/上下文进行治理的能力(钩子)分离开来,从而为上层 agent personas、skills、routing enforcement 与 MCP 工具提供稳定的调用面 资料来源：[packages/plugin/src/adapters/index.ts:1-1]()。

安装脚本 `scripts/install.sh` 配合 `--home-dir --existing` 参数会把该模块生成的产物落地到 `~/.neuralgentics/.opencode`,再通过项目内的符号链接被 OpenCode 加载。这意味着 `src` 下的所有 TypeScript 文件在发布前会被编译、整合,并以单一入口的形式注入到 OpenCode 运行时中。

## 适配器层:外部能力的统一抽象

`adapters/` 子目录承担"将异构外部能力统一为插件可消费接口"的责任,其中 `index.ts` 是适配器集合的导出/聚合入口,`memory.ts` 则实现了一个具体的内存适配器,用于在插件内部提供会话记忆、状态缓冲或上下文缓存等能力 资料来源：[packages/plugin/src/adapters/index.ts:1-1]() 资料来源：[packages/plugin/src/adapters/memory.ts:1-1]()。

由于社区反馈显示 routing enforcement 与 MCP 工具是 neuralgentics 的关键能力,适配器层通常会以统一接口屏蔽底层差异,使得上层 hooks 可以在不感知具体后端的情况下完成读写、缓存或持久化操作。这种"接口-实现"分离也让后续扩展(例如新增数据库或外部存储后端)只需新增一个 adapter 实现即可。

## 钩子系统:会话生命周期的治理点

`hooks/` 子目录通过 `index.ts` 汇总所有钩子,并以 `compaction.ts` 作为上下文压缩的核心实现,配合 `compaction.test.ts` 验证其在边界场景下的正确性 资料来源：[packages/plugin/src/hooks/index.ts:1-1]() 资料来源：[packages/plugin/src/hooks/compaction.ts:1-1]() 资料来源：[packages/plugin/src/hooks/compaction.test.ts:1-1]()。

`backup.ts` 则在压缩或重置上下文之前对关键状态进行快照,以保证发生错误或会话异常时能够回滚,降低 agent 路由或 MCP 工具调用过程中的上下文丢失风险 资料来源：[packages/plugin/src/hooks/backup.ts:1-1]()。

下表概括了 `hooks/` 下文件承担的职责:

| 文件 | 角色 |
| --- | --- |
| `hooks/index.ts` | 钩子聚合导出入口,负责将各钩子注册到插件生命周期 |
| `hooks/backup.ts` | 在压缩前对上下文与状态执行快照备份 |
| `hooks/compaction.ts` | 实现上下文压缩逻辑,收敛 token/消息数量 |
| `hooks/compaction.test.ts` | 验证压缩行为在正常与边界场景下的正确性 |

## 模块协作与扩展指引

`src` 下两套子系统通过明确边界协同工作:适配器层为钩子层提供"如何读写"的实现细节,钩子层则在 OpenCode 触发的事件点(例如会话增长、需要路由切换等)调用适配器完成实际动作。围绕这种分工,贡献者可以:

- 新增适配器:在 `adapters/` 下实现与 `index.ts` 导出契约一致的模块,即可被 hooks 自动消费 资料来源：[packages/plugin/src/adapters/index.ts:1-1]()。
- 调整压缩策略:修改 `compaction.ts` 并通过 `compaction.test.ts` 验证,避免破坏 routing enforcement 的上下文前提 资料来源：[packages/plugin/src/hooks/compaction.ts:1-1]()。
- 加强容错:扩展 `backup.ts` 的快照范围,使 MCP 工具调用与 personas 切换过程中产生的中间态都可恢复 资料来源：[packages/plugin/src/hooks/backup.ts:1-1]()。

整体而言,`src` 模块以"薄抽象 + 强约束"的方式支撑了 neuralgentics 0.9.x 系列在 OpenCode 生态中的可扩展性与稳定性,是插件能够在多个 release 中保持 `curl|bash` 一键安装、符号链接激活这一交付链路不变的核心所在。

---

<a id='page-packages-orchestrator-go-src'></a>

## Src 模块

### 相关页面

相关主题：[Src 模块](#page-packages-plugin-src)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [packages/orchestrator-go/src/neuralgentics/orchestrator/adapter.go](https://github.com/Veedubin/neuralgentics/blob/main/packages/orchestrator-go/src/neuralgentics/orchestrator/adapter.go)
- [packages/orchestrator-go/src/neuralgentics/orchestrator/adapter_test.go](https://github.com/Veedubin/neuralgentics/blob/main/packages/orchestrator-go/src/neuralgentics/orchestrator/adapter_test.go)
- [packages/orchestrator-go/src/neuralgentics/orchestrator/context_builder.go](https://github.com/Veedubin/neuralgentics/blob/main/packages/orchestrator-go/src/neuralgentics/orchestrator/context_builder_test.go)
- [packages/orchestrator-go/src/neuralgentics/orchestrator/context_builder_test.go](https://github.com/Veedubin/neuralgentics/blob/main/packages/orchestrator-go/src/neuralgentics/orchestrator/context_builder_test.go)
- [packages/orchestrator-go/src/neuralgentics/orchestrator/e2e_test.go](https://github.com/Veedubin/neuralgentics/blob/main/packages/orchestrator-go/src/neuralgentics/orchestrator/e2e_test.go)
- [packages/orchestrator-go/src/neuralgentics/orchestrator/improve.go](https://github.com/Veedubin/neuralgentics/blob/main/packages/orchestrator-go/src/neuralgentics/orchestrator/improve.go)
</details>

# Src 模块

## 概述与定位

`Src` 模块是 neuralgentics 项目的 Go 语言编排器（orchestrator）核心实现，位于 `packages/orchestrator-go/src/neuralgentics/orchestrator/` 路径下，遵循 Go 社区常见的 `src/<module>/<package>` 目录布局。该模块承担 OpenCode 插件体系中"路由强制执行（routing enforcement）"、"智能体人格（agent personas）"与"MCP 工具"三大特性的调度中枢职责，对外暴露给上层调用方一套统一、可测试的 Go API 资料来源：[packages/orchestrator-go/src/neuralgentics/orchestrator/adapter.go:1-40]()。

在版本演进过程中，`Src` 模块自 `neuralgentics-0.6.7` 起被确立为安装脚本（`scripts/install.sh`）的主要编译目标，并在 `neuralgentics-0.9.x` 系列中持续强化其可观测性与端到端测试覆盖。用户通过 `curl|bash` 一键安装后，链接到 `~/.neuralgentics/.opencode` 的符号链接会触发 OpenCode 运行时加载此模块编译产出的二进制。

## 核心子系统

### Adapter 适配层

`adapter.go` 定义了编排器与外部 LLM/MCP 客户端之间的协议转换接口。该层将 OpenCode 的内部消息格式归一化为可路由的请求结构，并通过注入式策略（injection policy）确保每次调用都附带正确的人格与技能元数据 资料来源：[packages/orchestrator-go/src/neuralgentics/orchestrator/adapter.go:1-80]()。

配套的 `adapter_test.go` 使用表驱动测试（table-driven tests）覆盖了多模型、多 provider 的兼容性矩阵，社区在 v0.7.x 期间反馈的"切换模型后人格丢失"问题即通过该测试套件被回归捕获 资料来源：[packages/orchestrator-go/src/neuralgentics/orchestrator/adapter_test.go:1-60]()。

### Context Builder 上下文构建器

`context_builder.go` 负责在每次智能体调用前组装运行时上下文，包括：

- 加载当前项目的人格定义与技能清单
- 拼接历史对话片段并应用滑动窗口
- 注入路由策略与权限约束

其单元测试 `context_builder_test.go` 验证了在窗口截断、令牌超限、工具失败等边界条件下上下文仍能保持一致 资料来源：[packages/orchestrator-go/src/neuralgentics/orchestrator/context_builder_test.go:1-90]()。

### Improve 改进循环

`improve.go` 实现了 self-improve 循环：在每次任务结束后收集执行轨迹（trajectory），调用评估函数打分，并将高分样本回灌到技能库。该机制是 `neuralgentics-0.9.0` 引入的"skills routing enforcement"特性的底层支撑 资料来源：[packages/orchestrator-go/src/neuralgentics/orchestrator/improve.go:1-50]()。

## 数据流与依赖关系

下表梳理了 `Src` 模块内主要文件的角色与协作关系：

| 文件 | 角色 | 主要依赖 |
|------|------|---------|
| `adapter.go` | 协议适配入口 | MCP SDK、模型客户端 |
| `context_builder.go` | 上下文组装 | 人格/技能注册表 |
| `improve.go` | 自改进回路 | 评估器、持久化层 |
| `*_test.go` | 单元测试 | testify、mock 工具 |
| `e2e_test.go` | 端到端测试 | docker compose fixture |

端到端测试 `e2e_test.go` 通过 spin up 真实 OpenCode 子进程与本地 LLM stub，验证从 `install.sh` 到智能体回复的完整链路，这与 `neuralgentics-0.6.7` 的补丁说明"curl|bash one-liner now works end-to-end + docker"直接对应 资料来源：[packages/orchestrator-go/src/neuralgentics/orchestrator/e2e_test.go:1-70]()。

## 测试与发布约定

`Src` 模块遵循严格的测试分层：单元测试与被测文件同包同目录，后缀 `_test.go`；集成与端到端测试则集中在 `e2e_test.go`，避免污染单元覆盖率统计。该约定与 `Keep a Changelog` + `Semantic Versioning` 的发布规范共同保证了从 `v0.6.7` 到 `v0.9.2` 共十余个版本的快速迭代稳定性 资料来源：[packages/orchestrator-go/src/neuralgentics/orchestrator/adapter_test.go:1-30]()。

开发者修改此目录下的任何文件后，应运行：

```bash
go test ./packages/orchestrator-go/src/neuralgentics/orchestrator/...
```

以同时触发单元测试与端到端测试套件，确保人格、技能、路由三类行为均无回归。

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：Veedubin/neuralgentics

摘要：发现 16 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 失败模式：installation: Neuralgentics v0.6.7。

## 1. 安装坑 · 失败模式：installation: Neuralgentics v0.6.7

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: Neuralgentics v0.6.7
- 对用户的影响：Upgrade or migration may change expected behavior: Neuralgentics v0.6.7
- 证据：failure_mode_cluster:github_release | https://github.com/Veedubin/neuralgentics/releases/tag/v0.6.7 | Neuralgentics v0.6.7

## 2. 安装坑 · 失败模式：installation: Neuralgentics v0.6.8

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: Neuralgentics v0.6.8
- 对用户的影响：Upgrade or migration may change expected behavior: Neuralgentics v0.6.8
- 证据：failure_mode_cluster:github_release | https://github.com/Veedubin/neuralgentics/releases/tag/v0.6.8 | Neuralgentics v0.6.8

## 3. 安装坑 · 失败模式：installation: Neuralgentics v0.7.0

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: Neuralgentics v0.7.0
- 对用户的影响：Upgrade or migration may change expected behavior: Neuralgentics v0.7.0
- 证据：failure_mode_cluster:github_release | https://github.com/Veedubin/neuralgentics/releases/tag/v0.7.0 | Neuralgentics v0.7.0

## 4. 安装坑 · 失败模式：installation: Neuralgentics v0.7.1

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: Neuralgentics v0.7.1
- 对用户的影响：Upgrade or migration may change expected behavior: Neuralgentics v0.7.1
- 证据：failure_mode_cluster:github_release | https://github.com/Veedubin/neuralgentics/releases/tag/v0.7.1 | Neuralgentics v0.7.1

## 5. 安装坑 · 失败模式：installation: neuralgentics-0.7.2

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: neuralgentics-0.7.2
- 对用户的影响：Upgrade or migration may change expected behavior: neuralgentics-0.7.2
- 证据：failure_mode_cluster:github_release | https://github.com/Veedubin/neuralgentics/releases/tag/v0.7.2 | neuralgentics-0.7.2

## 6. 安装坑 · 失败模式：installation: neuralgentics-0.7.3

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: neuralgentics-0.7.3
- 对用户的影响：Upgrade or migration may change expected behavior: neuralgentics-0.7.3
- 证据：failure_mode_cluster:github_release | https://github.com/Veedubin/neuralgentics/releases/tag/v0.7.3 | neuralgentics-0.7.3

## 7. 安装坑 · 失败模式：installation: neuralgentics-0.8.0

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: neuralgentics-0.8.0
- 对用户的影响：Upgrade or migration may change expected behavior: neuralgentics-0.8.0
- 证据：failure_mode_cluster:github_release | https://github.com/Veedubin/neuralgentics/releases/tag/v0.8.0 | neuralgentics-0.8.0

## 8. 安装坑 · 失败模式：installation: neuralgentics-0.9.0

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: neuralgentics-0.9.0
- 对用户的影响：Upgrade or migration may change expected behavior: neuralgentics-0.9.0
- 证据：failure_mode_cluster:github_release | https://github.com/Veedubin/neuralgentics/releases/tag/v0.9.0 | neuralgentics-0.9.0

## 9. 安装坑 · 失败模式：installation: neuralgentics-0.9.1

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: neuralgentics-0.9.1
- 对用户的影响：Upgrade or migration may change expected behavior: neuralgentics-0.9.1
- 证据：failure_mode_cluster:github_release | https://github.com/Veedubin/neuralgentics/releases/tag/v0.9.1 | neuralgentics-0.9.1

## 10. 安装坑 · 失败模式：installation: neuralgentics-0.9.2

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: neuralgentics-0.9.2
- 对用户的影响：Upgrade or migration may change expected behavior: neuralgentics-0.9.2
- 证据：failure_mode_cluster:github_release | https://github.com/Veedubin/neuralgentics/releases/tag/v0.9.2 | neuralgentics-0.9.2

## 11. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/Veedubin/neuralgentics | README/documentation is current enough for a first validation pass.

## 12. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/Veedubin/neuralgentics | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/Veedubin/neuralgentics | no_demo; severity=medium

## 14. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/Veedubin/neuralgentics | no_demo; severity=medium

## 15. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/Veedubin/neuralgentics | issue_or_pr_quality=unknown

## 16. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/Veedubin/neuralgentics | release_recency=unknown

<!-- canonical_name: Veedubin/neuralgentics; human_manual_source: deepwiki_human_wiki -->