Archived

This repository has been archived on 2026-06-01. You can view files and clone it. You cannot open issues or pull requests or push a commit.

Files

T

xiaoju 8dd82d99da refactor(core): remove WorkflowTrigger from SenseTrigger — shell only

Senses trigger shell commands only. Workflows are invoked via CLI.

SenseTrigger is now { command: string } — no discriminated union.

Closes #318

Co-authored-by: Cursor <cursoragent@cursor.com>

2026-05-02 12:33:38 +00:00

9.2 KiB

Raw Blame History

Nerve 单仓死代码分析报告

分析日期: 2026-04-30
范围: packages/core, daemon, store, cli, khala, workflow-utils, workflow-meta, adapter-cursor, adapter-hermes 的 TypeScript 源码与 package.json 依赖。
方法: 全仓 ripgrep 交叉验证 import / export 路径；未运行 Knip/TS 死代码专项工具。
说明: 未包含 role-reviewer / role-committer / skills 等包（你列出的范围外），但 workflow-meta 对其中部分有依赖，相关结论已注明。

方法限制（读前必读）

限制	影响
动态 `import(url)`	`cli` 的 `loadDaemonModule` 在运行时加载 `@uncaged/nerve-daemon`，静态分析无法把 `createKernel` 等映射到具体导出。
已发布包的公共 API	大量导出仅被仓外消费者使用；本报告中的「仓内未引用」≠「应删除」。
构建入口	Rslib 多入口（如 `sense-worker`、`workflow-worker`、`daemon-bootstrap`）视为存活入口，不作为孤儿文件。
内部未导出函数	未做逐函数调用图；「死函数」仅列出高置信个例。

1. 未使用导出（仓内无 `import`）

以下符号在 monorepo 内 没有任何文件从 @uncaged/nerve-core / @uncaged/nerve-workflow-utils / @uncaged/nerve-daemon 等包根导出处引用（测试与定义自身除外）。

1.1 `@uncaged/nerve-core`

路径	未使用项	置信度	建议
`packages/core/src/index.ts` → `agent.js`	`KNOWN_AGENT_ADAPTER_IDS`	高	调查：若 CLI/校验应约束 adapter id，可接入；否则可从公共 API 移除或保留作文档性常量并注明。
`packages/core/src/index.ts` → `sense.js`	`labelSenseTrigger`（`senseTriggerLabels` 在 `cli`/`daemon` 有使用）	高（相对仓内）	保留或收敛导出：仅 `senseTriggerLabels` 对外即可；`labelSenseTrigger` 可作为内部函数若不需要单独暴露。
`packages/core/src/index.ts` → `util.js`	`parseDurationStringToMs`（仅 `config.ts` 内部使用）	高	调查：无需在 `index` 再导出则改为非导出或移除 re-export，减少 API 面。
`packages/core/src/index.ts` → `sense.js`	类型 `SenseModule`	中	保留：用户文档/外部 Sense 模块常用；仓内未按名引用属正常。
`packages/core/src/index.ts` → `config.js`	单独导出的类型 `NerveApiConfig`（仅 `config.ts` 与 `index` 出现）	低	保留：通常随 `NerveConfig` 一并使用；单独 export 多为 TS 公共类型便利。

1.2 `@uncaged/nerve-workflow-utils`

下列项在 packages/*/src/**/*.ts 中无人从包入口导入（workflow-meta、role-committer 等主要只用 createRole、decorateRole、onFail、withDryRun、LlmExtractorConfig）。

路径	未使用项	置信度	建议
`packages/workflow-utils/src/index.ts`	`createLlmAdapter`	高	保留（对外 API）或标注文档；仓内无调用。
同上	`llmExtract`、`llmExtractWithRetry`	高	保留：高级用法 / 文档示例；内部与测试使用。
同上	`mergeExtractConfig`、`ExtractConfigLayer`	高	调查：若 RFC 分层配置仍在推进则保留；否则评估移除导出。
同上	`assertZodMetaSchemas`、`createLlmExtractFn`、`extractMetaOrThrow`、`zodMeta`、`ZodMetaSchema`	高	保留（对外 API）；当前仅 `workflow-utils` 测试与内部 `create-role` 链路使用 `extractMetaOrThrow`。
同上	`readNerveYaml`、`nerveAgentContext` 及相关类型	高	调查：若已无 YAML 上下文注入场景可删导出；否则保留给 Agent 工具链。
同上	`spawnSafe`、`nerveCommandEnv` 及 `Spawn*` 类型（从 core 再导出）	高	删除再导出或改为文档链接：仓内均直接从 `@uncaged/nerve-core` 引用 spawn。
同上	`isDryRun`	高	删除或实现：见 §3「死函数」。
同上	`LlmMessage`、`MetaExtractConfig`、`LlmChatError`、`LlmError`、`LlmProvider` 等类型再导出	中	保留：供外部精细类型标注；仓内未单独 import。

1.3 `@uncaged/nerve-daemon`

路径	未使用项	置信度	建议
`packages/daemon/src/index.ts` → `agent-adapters/echo.js`	`createEchoAgent`	高	调查：无任何测试或运行时引用；若设计保留 `type: "echo"` 适配器，应在 workflow/agent 装载路径接线或删除导出与文件。
`packages/daemon/src/index.ts`（及其它导出）	多数 IPC / runtime 符号	低	保留：动态加载与外部集成无法静态判定；仅 `createEchoAgent` 可确定为当前静态图下的死角。

1.4 `@uncaged/nerve-adapter-cursor` / `@uncaged/nerve-adapter-hermes`

路径	未使用项	置信度	建议
`packages/adapter-cursor/src/index.ts`	`cursorAdapter`、`createCursorAdapter`（以及 `cursorAgent` 仅被 `workflow-utils/src/role-cursor.ts` 使用）	中	保留：默认实例与工厂供下游与工作流仓使用；仓内业务包未直接 import `cursorAdapter` 属预期。
`packages/adapter-hermes/src/index.ts`	`hermesAdapter`、`createHermesAdapter`（`hermesAgent` 经 `workflow-utils` 间接使用）	中	同上。

1.5 `@uncaged/nerve-cli`

路径	未使用项	置信度	建议
`packages/cli/src/index.ts`	`getNerveRoot`、`loadDaemonModule` 等程序化导出	高（仓内）	保留：无任何 workspace 包引用 `@uncaged/nerve-cli`；面向 CLI 二次开发者。

2. 孤儿文件（非入口、未被其它源码引用）

在当前 Rslib / cli 入口定义下，未发现「零 import、且非 entry / 非测试」的 .ts 业务文件：

workflow-utils 下的 role-cursor.ts、role-hermes.ts、role-llm.ts、role-react.ts 虽未出现在包 index.ts，但被 packages/workflow-utils/src/__tests__/role-factories.test.ts 直接引用，不是孤儿文件。
daemon 的 sense-worker.ts、workflow-worker.ts 等为 显式构建入口。

置信度: 对全表扫描为中（未跑依赖图工具；动态路径可能掩盖极少数脚本引用）。

3. 死函数（内部未导出且未被调用）

路径	说明	置信度	建议
`packages/workflow-utils/src/role-types.ts`	`isDryRun(_start: StartStep)`：导出在 `index.ts`，但全仓无调用（函数体恒返回 `false` 且标注 deprecated）	高	删除或改为内部常量；若需向后兼容则保留并文档标注「保留占位」。

其它内部函数未系统逐文件枚举。

4. 未使用的 npm 依赖（package.json）

在声明范围内通过源码 import 抽查：未发现明显「完全未使用」的生产依赖。

包	依赖	结论
`cli`	`citty`、`yaml`、`picomatch`	均有对应源码引用。
`khala`	`hono`、`jsonata`、`ulidx`、`@uncaged/nerve-core`	均有引用。
`core` / `daemon`	`yaml`、`drizzle-orm`	均有引用。
`workflow-utils` / `workflow-meta`	`zod`、workspace 包	均有引用。

置信度: 中（未对 peer、可选路径、CLI bin 专用依赖做自动化扫描）。

5. 陈旧测试夹具 / 未引用辅助文件

未发现独立的「fixture 目录」明显失联；cli 下 e2e-harness、__tests__ 内 helper 均有对应测试引用。

置信度: 低（未枚举每个 __tests__ 资源文件）。

6. 重构遗留 / 文档漂移

项目	位置	说明	置信度	建议
~~已更名 API 仍出现在 README~~	`packages/core/README.md`	（已修正）文档与 stateful sense、`parseSenseTrigger`（shell-only）对齐	—	关闭
Hermes 选项合并注释	`packages/workflow-utils/src/shared/hermes-agent.ts`	注释称 absorbed from `hermes-options.ts`，该文件已不存在	中	清理注释，避免误导。
`KNOWN_AGENT_ADAPTER_IDS` 含 `codex`	`packages/core/src/agent.ts`	仓内无 `codex` 适配器包；与常量未被引用叠加	中	对齐产品：实现适配器或从列表移除。

未发现用户提到的 worker-fork-support 等字符串副本（全仓无匹配）。

7. 汇总建议优先级

高优先级调查: createEchoAgent 与 KNOWN_AGENT_ADAPTER_IDS — 要么接入运行时，要么删减以免维护假象。
API 面收敛: parseDurationStringToMs、labelSenseTrigger 若无意对外，可从 core 公共导出移除。
workflow-utils: 评估 isDryRun 删除；spawnSafe 等从 workflow-utils 再导出是否仍有必要。
~~文档: 修正 packages/core/README.md 中 Sense→Workflow 路由 API 名称。~~（已完成）

8. 重新验证命令示例

后续可在本地采用工具增强置信度（非本次执行）：

pnpm add -D -w knip
pnpm exec knip

或在各包对 @uncaged/nerve-* 的导出做面向消费者的契约测试，避免误删对外 API。

9.2 KiB Raw Blame History