Yanshi 项目深度评估报告 (2026-08-05)
- 评估日期:2026-08-05
- 评估范围:workspace 全部 24 个
yanshi-*Rust crate +xtask(共 25 个成员)+yanshi-ui(TypeScript SPA),约 20 万行 Rust(含测试)+ ~5.3K 行 TS。 - 评估方法:6 个独立 agent 并行只读审计(按 L1 执行内核 / L2 LLM·工具·MCP / L2 RAG·记忆·节点·配置 / L3 Agent 框架 / L4 服务平台 / CLI·示例·文档 分工,互不共享结论),外加编排者在本机实跑
cargo test --workspace/cargo clippy/cargo fmt/cargo tree做证据校验。子代理只读源码不跑 cargo;编排者补齐编译期与运行期证据,并逐行复核了 5 个被列为 P0/P1 的关键缺陷。 - 与既往评估关系:延续
docs/archive/PROJECT_EVALUATION_2026-07-30.md(U 段依据,综合 A-(有条件))。本轮是一次从零重扫的全维度评审 + 生产就绪度专项判断,不以旧清单为基线,独立挖掘问题。
0. TL;DR
| 维度 | 评级 | 一句话判断 |
|---|---|---|
| 架构分层与模块化 | A- | 分层清晰、SPI 抽取合理、xtask check-arch 用 8 条依赖律强制;残留 store-spi 的 sqlx 硬依赖、async-util→graph 方向倒置等轻度卫生债。 |
| 模块完整度 / 职责单一 | B+ | 大多完成;但 core 的 retry/timeout/resource/health 未接入执行引擎(门面),部分能力(如 factory 走 Semantic 分块)不可达。 |
| Agent 框架完整度 | A- | 真·生产级核心,限额/取消工程 Rust 生态一流;缺 token 流式、通用 HITL、结构化输出强制、agent 循环级持久化;并有 UTF-8 panic 与 resume 关联两处真实缺陷。 |
| 服务层 / 平台 | B | 真控制面 + 扎实租户隔离 + 参数化 SQL;但工作流执行未沙箱化、默认 fail-open、/v1/runs 无限流。 |
| 代码成熟度 | A- | 生产库 unwrap/expect 干净(已实测 clippy 门禁通过)、fmt + 全量 clippy -D warnings 干净、~8000 测试且断言真实行为;扣分:println! 当日志、可靠性栈未接线、个别潜伏 panic。 |
| 安全性 | C+ / B- | 沙箱/脱敏/签名等原语是 A- 级,但引擎侧执行未强制沙箱 + SSRF 绕过 + file 节点默认 permissive + 默认安全档 fail-open,多租户/不可信输入场景下姿态被拉到 C+。 |
| 综合 | B+(库工程 A-;生产就绪度/多租户安全 C+) | 工程素养罕见地高,但“生产就绪“尚未达标——短板集中在执行引擎正确性语义、可靠性栈接线、执行侧安全强制三处。 |
编排者实测证据(本机 CARGO_TARGET_DIR=/Users/hal/.target):
cargo fmt --check:干净。cargo clippy --workspace --all-targets --no-deps -- -D warnings:0 告警。cargo clippy --workspace --lib -- -D clippy::unwrap_used -D clippy::expect_used:通过 → 生产库代码确实无unwrap/expect(源码里 ~6900 处几乎全落在#[cfg(test)])。cargo test --workspace:除 1 例外全绿。唯一失败yanshi-skills的builder::tests::build_registers_code_exec_tool报code_exec exited with code 1: XPC connection error: Connection invalid——是本机 macOS 沙箱运行时无法建连导致code_exec拉容器失败,属环境限制,非代码缺陷。少量#[ignore]均为真实 API/网络/Qdrant/ONNX 集成测试。实际执行的测试函数总量远超历史文档所称的 “479”。- 依赖:422 个唯一依赖,~30 个 crate 存在双版本;
cargo-audit未安装(未能核验 CVE)。
关键判断:测试全绿 ≠ 正确。 下文 §7 列出的多个 P0/P1 缺陷都位于当前测试未覆盖的路径上——编排者已逐行确认它们是真实潜伏 bug,而非误报。
1. 架构分层与模块化(A-)
结论:分层是本项目的强项,抽象合理、非过度设计。
- 四层心智模型(L1 执行内核 / L2 能力适配 / L3 Agent 编排 / L4 运维平台)在代码里成立;依赖法则由
xtask check-arch用 8 条依赖律在 CI 强制,value→graph→async-util→core单向,未发现 core 反向依赖。 - 契约/SPI 抽取都是有 RFC、有回归测试、re-export 完整的完成态迁移:
yanshi-tool(契约)vsyanshi-tools(实现)(T3.3)、yanshi-nodes(工具层)vsyanshi-nodes-ai(能力层)、store-spi/agent-spi。harness/server/tracing 确实依赖契约而非实现。 - 早前担心的 CLI 分层违规已不存在:executor/schema 已迁到
yanshi-config(P-A2.4),CLI 仅做 clap 胶水 + 委派。
轻度卫生债:
yanshi-store-spi为一个From<sqlx::Error>硬拖sqlx(runtime-tokio-rustls+sqlite)进每个消费者(含 agent-spi),注释已自认待清理。yanshi-async-util仅为借用错误类型而依赖yanshi-graph,方向倒置(已被注释承认)。- 双 crate 命名(单/复数
tool/tools、nodes/nodes-ai)对新人有混淆成本。
2. 模块完整度与职责单一性(B+)
多数模块完成度高、职责单一,但有两类系统性缺口:
(1) 可靠性栈是引擎级门面。 yanshi-core 的 retry / timeout / ConcurrencyLimiter / ResourceManager / StateMonitor / HealthChecker 均未接入 DAG 执行器:DAG 路径无逐节点超时/重试,WorkflowEvent::RetryAttempt 全仓从未发出,execute_with_retry 零生产调用者。README/历史文档所称的“生产级容错“描述的是孤立模块,不是执行行为。(注:CLI 侧 yanshi-config 的 TimeoutRetryNode 装饰器为 YAML 工作流补齐了节点级 timeout/retry,但 yanshi-core::Flow 直接 API 路径仍无。)
(2) 部分已实现能力不可达。 yanshi-rag 的 SemanticChunker 已实现,但 create_chunker(ChunkingStrategy::Semantic, …) 硬报 “not yet implemented” → 配置优先/YAML 语义分块不可达。yanshi-nodes-ai 的 rag 节点 “hybrid”/“keyword” 模式实为 BM25 over 已语义召回的 top-k,非真正的语料级混合检索,静默返回低质量结果。
其余:yanshi-cli/src/main.rs 2678 行 clap 胶水持续增长(项目自评 P3);yanshi-db 的 PgStepRepo/PgArtifactRepo 已定义但无路由调用(schema 与代码的完整度缺口)。
3. Agent 框架完整度(A-,用户重点)
结论:yanshi-agents 是全项目最成熟的部分,AGENTS.md 的能力声明基本属实。
已实现且有竞争力:
- 运行时限额全部真实强制(非建议性):
max_steps/max_tool_calls/ 墙钟timeout(剩余预算传入每次 LLM/工具 race)/token_budget(真实 tokenizer 每轮核对)/cost_limit_usd(按 PricingTable 累计)+ 滑窗LoopDetected+ 连续同调用引导 nudge。见react/agent.rs::check_turn_limits。 - 协作式取消:LLM 前/中、工具前/中、批派发均经
tokio::select!;在途工具 future 会被 drop;tokio::spawn分离任务存活的局限被诚实记录并有测试钉住。 - ReAct 解析健壮:去代码围栏、取最外层
{}、从被截断 JSON 恢复answer;原生 tool_calls 优先、prompt 协议兜底。 - 组合能力真实落地:
AgentNode(agent 入 DAG)+WorkflowTool(DAG 当工具)+AgentNodeResumeContract v1(重放策略 + 三级副作用分类),有集成测试。 - 记忆分层:session 窗口 + 任务摘要 + 项目事实 + 用户偏好,真实按模型 tokenizer 计费。
- Skills / Harness:SKILL.md 严格解析、脚本 SHA-256 完整性、写后执行防御、离线固定哈希 venv、MCP 允许列表;Harness 是回合驱动循环(H0–H4 完成,H5 服务端任务待)。
真实缺陷(见 §7): ReAct 热路径 UTF-8 panic、resume 按名(而非 call-id)关联误判、Parallel supervisor 错误路径泄露 sibling agent。
对标主流框架(LangGraph / AutoGen / OpenAI Agents SDK)缺失项:
- LLM token 级流式(仅 step 粒度,
HarnessEventBody无 delta); - 通用 HITL 中断/恢复原语(只有工具审批,没有“运行中提问再带答案 resume“);
- 结构化输出强制(靠 prompt 协议 + 尽力恢复,无 schema 约束解码/输出类型校验);
- agent 循环级持久 checkpoint(resume 契约仅重放只读/幂等未决调用);
- 内容 guardrail/moderation 抽象;
- 任意 agent 图拓扑(三种 supervisor 是固定模式,非可组合图)。
4. 服务层 / 部署 / 数据管理(B)
结论:真控制面,远超历史文档“130 LOC scaffold“的描述(实为 19.5K LOC),但生产强制姿态未跟上。
亮点:
- 租户隔离防御纵深:每个 handler
row.tenant_id != tenant → 404且 DB 查询按tenant_id过滤(双重);bearer 用 constant-time 比较 + per-tenant token + 生产 fail-closed;auth 覆盖 SSE(在/v1下)。 - DB 层:全参数化 SQL(无注入),多步写用事务,池默认合理;迁移幂等。
- 优雅 SIGTERM/SIGINT 关停 + 有界 trace flush;统一错误信封 + 全局/路由体积上限。
- Worker↔Server gRPC 支持 TLS/mTLS + JWT/PSK 准入(生产 fail-closed),有端到端测试。
主要风险(见 §7 与 §6):执行未沙箱化(默认 FlowRunExecutor 进程内跑客户端提交的 YAML,http/file 节点无运行时沙箱强制,lib.rs:140-142 自认强制“由后续 P1 任务推出“)、默认 fail-open(SecurityProfile::Local)、/v1/runs 无限流/无 per-tenant 并发上限、/metrics 未鉴权且带 tenant 标签。yanshi-tracing 的 OTLP 仅 trait,无真实 wire 传输(文档“OTLP exporter“略有夸大)。
5. 代码成熟度(A-)
见 §0 实测证据。优点:生产库 unwrap/expect/panic/unsafe 干净(唯一“unsafe“几乎全是 edition 2024 要求的 unsafe { env::set_var },集中在测试与 server 启动一次性设置);测试断言真实行为(取消 race、截断 JSON 恢复、事件 seq 排序、SSRF 分类矩阵、沙箱 profile 内容、Ed25519 往返、TLS e2e);CI 门禁强(fmt / clippy -D warnings / lib 层 unwrap DENY / redaction-lint / check-arch / bench-gate);仓库自审闭环有效(docs/audit/ 与归档 evaluation 标记的 CRITICAL/MAJOR 经核对确已修复且留追踪 ID)。
扣分:生产节点代码用 println!/eprintln!(带 emoji)当日志(nodes-ai ~40 处、nodes/core 多处),部分打印 prompt/params/loop state,污染 CLI/JSON 输出并有轻度信息泄露;可靠性栈未接线(§2);个别潜伏 panic 站点(见 §7)。
6. 安全性(C+ / B-)
原语层(A- 级,真材实料): ShellTool argv 状态机拒注入、SandboxPolicy fail-closed 默认(空 allowlist = deny-all)、code_exec 强制容器隔离 + 只读根 + 无网 + 非 root、macOS sandbox-exec deny-default SBPL + Linux seccomp+Landlock+cgroup、Ed25519 marketplace 签名 + tar 解包硬化(路径穿越/zip 炸弹/符号链接)、tracing 全接缝脱敏 + CI redaction-lint、server 租户隔离 + 参数化 SQL。
但强制/默认姿态把整体拉到 C+(尤其多租户/不可信输入): 见 §7 的 P0/P1——引擎执行未沙箱化、SSRF IPv4-mapped 绕过 + DNS-rebinding TOCTOU、file 节点默认 permissive → 任意绝对路径读写、worker-gRPC submit_task 无鉴权、默认 SecurityProfile::Local fail-open、marketplace 默认 checksum-only + 允许 http://、Net capability = allow network* 忽略声明域名。
7. 已逐行复核确认的关键缺陷(编排者亲自验证)
以下缺陷编排者已在指定行号亲眼确认,并确认当前测试套件未覆盖对应路径(故全绿):
- [P0][正确性] ReAct 热路径 UTF-8 字节切片 panic —
yanshi-agents/src/react/agent.rs:1843与:3066的&observation[..observation.len().min(200)]、:3695的content.truncate(160)均按字节切/截断,非字符边界即panic。任何 >200 字节的 CJK/emoji 工具输出会直接 crash agent 循环;对 CJK 受众尤其致命。测试用 ASCII echo 故从未触发。修复:chars().take(n)或floor_char_boundary(项目rag/chunking/recursive.rs已有正确实现可复用)。 - [P0][安全] config-first
file节点默认 permissive —yanshi-nodes/src/nodes/file.rs:40-48Default用SandboxPolicy::permissive();唯一守卫是:149的..组件检查,绝对路径(如/etc/passwd、~/.ssh/id_rsa)无..即通过,path_denial_reason在 permissive 下返回None。若path由 input_mapping / LLM 输出数据驱动 = 任意文件读写。修复:factory 默认改 deny-by-default(空 allowed_paths),工作流显式 opt-in。 - [P0][安全] worker-gRPC
submit_task无鉴权 —yanshi-server/src/scheduler/grpc.rs:82-104显式无凭据接受(其余claim_task/report_result/heartbeat三方法都extract_admission_token并校验)。该 gRPC 绑独立 socket、不在 HTTP bearer 中间件后 → 任何能到达该端口者可投递任意 WorkerTask,链式放大执行侧 SSRF/文件访问。 - [P1][安全] HTTP 工具 SSRF 绕过(IPv4-mapped IPv6) —
yanshi-tools/src/builtin/http.rs:345classify_network_address对IpAddr::V6只查 loopback/fe80/fc00,CLOUD_METADATA_IPS是 V4 字面量;http://[::ffff:169.254.169.254]/…归类为空 → 被默认策略放行。修复:分类前to_ipv4_mapped()归一。另有 DNS-rebinding TOCTOU(校验后 reqwest 重新解析,未 pin IP)。 - [P1][正确性] DAG 良性跳过被计为整体失败 —
yanshi-core/src/flow.rs:441把Err(YanshiError::NodeSkipped)存入 state_pool,:467/:848的state_pool.values().any(Result::is_err)将其计为workflow_failed→ 一个run_if跳过就发WorkflowFailed+ 存 checkpointstatus=Failed(错误的保留类别与 server 终态)。纯跳过→Completed 的情形无测试覆盖。修复:跳过用独立标记而非Err,或终态判定排除NodeSkipped。
来自子代理源码分析、编排者未逐行复核但列为需修的其他高危项(§8 汇总):serial 模式中途 ? abort 无终态事件/checkpoint(flow.rs:759-772,checkpoint 永停 Running);checkpoint 路径穿越 + delete_all_checkpoints("..") 破坏性 remove_dir_all(checkpoint.rs:403);resume 对 DAG 不健全(部分失败被静默升级为 Ok);AgentCancellationToken 漏唤醒竞态(agent-spi/src/runtime.rs:335);MCP stdio 无界 read_line OOM;SemanticMemory 不稳定 ID 回归(semantic.rs:547);Parallel supervisor 错误路径泄露 sibling agent。
8. 跨维度优先级清单
| 优先级 | 发现 | 维度 | 修复成本 |
|---|---|---|---|
| P0 | ReAct 热路径 UTF-8 字节切片 panic(agent.rs:1843/3066/3695) | Agent/正确性 | 极低 |
| P0 | file 节点 factory 默认 permissive → 任意绝对路径读写 | 安全 | 低 |
| P0 | worker-gRPC submit_task 无鉴权(独立 socket) | 安全/服务 | 低 |
| P0 | DAG 良性 run_if 跳过被计为 WorkflowFailed(flow.rs:467/848) | 执行内核/正确性 | 低 |
| P0 | checkpoint/run-dir 路径未净化 + delete_all_checkpoints("..") 破坏性删除 | 执行内核/安全 | 低 |
| P1 | HTTP SSRF:IPv4-mapped IPv6 绕过 + DNS-rebinding TOCTOU | 安全 | 中 |
| P1 | serial 模式中途 abort 无终态事件/checkpoint;serial vs concurrent 语义分叉 | 执行内核 | 中 |
| P1 | resume 对 DAG 不健全(部分失败升级为 Ok;跳过标记丢失) | 执行内核 | 中高 |
| P1 | AgentCancellationToken 漏唤醒竞态 → 可能不可取消 | Agent/并发 | 低 |
| P1 | 可靠性栈(retry/timeout/resource/health)未接入 Flow 执行器 | 完整度 | 中高 |
| P1 | 无 LLM 级 429/5xx 重试退避(config 有字段但未用) | LLM | 中 |
| P1 | 默认 SecurityProfile::Local fail-open;/v1/runs 无限流 | 服务/安全 | 低-中 |
| P2 | resume tool-call 按名而非 call-id 关联 → 重复工具批误判 | Agent | 中 |
| P2 | SemanticMemory 不稳定 ID 回归(仅修了一份拷贝) | 记忆 | 低 |
| P2 | Parallel supervisor 错误路径泄露 orphaned sibling agent | Agent | 中 |
| P2 | MCP stdio 无界 read_line / 无界通知 channel OOM | MCP | 低-中 |
| P2 | marketplace 默认 checksum-only + 允许 http://;plugin install --signed 自证明 | 安全/生态 | 中 |
| P2 | Net capability = allow network* 忽略声明域名 | 安全 | 中 |
| P2 | Gemini 内置注册表 base_url 拼接错误 → 走错 URL | LLM | 低 |
| P2 | 生产节点代码 println! 当日志 → 改 tracing | 成熟度 | 中 |
| P2 | expr 解析器无递归深度上限 → 服务端执行 YAML 栈溢出 DoS | 执行内核/安全 | 低 |
| P2 | input_mapping 空格漂移:validate 通过但 factory 静默丢弃 | 完整度 | 低 |
| P3 | AGENTS.md 严重过时(见 §9),污染所有 agent 上下文 | 文档 | 低 |
| P3 | ~/.yanshi/runs 无保留/清理,无界增长 | 执行内核 | 低 |
| P3 | main.rs 2678 行 clap 胶水持续增长 | 完整度 | 中 |
| P3 | 依赖双版本 ~30 处;无 cargo-audit CI 门 | 供应链 | 低 |
9. 文档与现实一致性
AGENTS.md(根,Last Updated 2026-05-03)严重过时且会误导每一个在本仓工作的 agent(它是 agent 规则文件):
- 称 “14 crates + 2 scaffold”——实际 25 个成员;
- 称
yanshi-server是 “130 LOC scaffold, 0 tests”——实际 19.5K LOC 完整网关; - 称
yanshi-db“48 LOC”——实际 2370 LOC / 9 表 / 9 仓; - 称 “479 tests(2025-11-17 verified)”——实际 ~8000+;
~244ns 开销等为 2025-11 陈迹; - 完全没提
yanshi-harness(8.2K LOC)、config、value/graph/spi、worker、ui; - 仍称
yanshi-nodes含 “16+ 节点 + factory_traits.rs”——那些已迁到nodes-ai,factory_traits 已删;RAG eval 说成 pending——实际已实现。
对照之下 CLAUDE.md / docs/CURRENT_STATUS.md(2026-07-28)是最新的。建议用后两者重新生成 AGENTS.md,并给根目录遗留设计文档(ARCHITECTURE.md、TERA_INTEGRATION_*、LOOP_NODES_IMPLEMENTATION.md、MIGRATION_V2.md)加“历史参考“横幅或移入 docs/archive/。 这是单点杠杆最高的修复。
10. 生产就绪度判断与优先级框架
当前状态: 适合个人/单租户/可信输入场景下使用;不适合多租户或不可信输入的对外服务(执行未沙箱化 + 默认 fail-open + 若干 SSRF/任意文件访问)。
结合“个人智能体框架、服务能力有限“的定位,优化优先级应为:
- 核心能力优先(Core-first): 先修影响**每一种使用(含个人)**的执行/agent 正确性与稳定性缺陷——UTF-8 panic、DAG 终态语义、resume 健全性、取消竞态、可靠性栈接线、LLM 重试、记忆运行时集成。这些是“生产就绪“的地基。
- 核心能力补齐: 结构化输出强制、token 流式、通用 HITL、agent 循环持久化——补齐对标主流框架的能力短板。
- 服务能力次之(Service-second): 执行沙箱强制、默认档 fail-closed、限流/配额、
/metrics鉴权、worker-gRPC 补鉴权、marketplace 默认签名。因服务范围有限,此层可采用“够用即止“的加固强度,但其中 file 节点任意读写、SSRF 两项因会影响个人使用(LLM 驱动的工具调用),提升至 P0/P1 与核心一并处理。 - 文档与卫生:
AGENTS.md重生成、doc drift、main.rs拆分、依赖去重、cargo-audit入 CI。
详细可执行方案见随本报告制定的优化计划(生产就绪路线图,按上述四层排序)。
本报告由 6 路并行只读审计 + 编排者本机 build/test/clippy/fmt 实测 + 5 项关键缺陷逐行复核汇总而成。子代理未运行 cargo;所有“已验证“证据来自编排者实跑。
Co-Authored-By: Oz oz-agent@warp.dev