项目简介

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） 结构，将运行时不同的子能力拆分到独立包中，便于按需启用与版本对齐。

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

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

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

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

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

版本演进

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

使用总览

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

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

概述与定位

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 插件规范，主要分为四大功能区和一个引导脚本区。下表列出关键路径及其职责：

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

核心组件与数据流

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

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。

Pitfall Log / 踩坑日志

项目：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