Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

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(契约)vs yanshi-tools(实现)(T3.3)、yanshi-nodes(工具层)vs yanshi-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)缺失项:

  1. LLM token 级流式(仅 step 粒度,HarnessEventBody 无 delta);
  2. 通用 HITL 中断/恢复原语(只有工具审批,没有“运行中提问再带答案 resume“);
  3. 结构化输出强制(靠 prompt 协议 + 尽力恢复,无 schema 约束解码/输出类型校验);
  4. agent 循环级持久 checkpoint(resume 契约仅重放只读/幂等未决调用);
  5. 内容 guardrail/moderation 抽象;
  6. 任意 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. 已逐行复核确认的关键缺陷(编排者亲自验证)

以下缺陷编排者已在指定行号亲眼确认,并确认当前测试套件未覆盖对应路径(故全绿):

  1. [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 已有正确实现可复用)。
  2. [P0][安全] config-first file 节点默认 permissive — yanshi-nodes/src/nodes/file.rs:40-48 Default 用 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。
  3. [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/文件访问。
  4. [P1][安全] HTTP 工具 SSRF 绕过(IPv4-mapped IPv6) — yanshi-tools/src/builtin/http.rs:345 classify_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)。
  5. [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 + 存 checkpoint status=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. 跨维度优先级清单

优先级发现维度修复成本
P0ReAct 热路径 UTF-8 字节切片 panic(agent.rs:1843/3066/3695)Agent/正确性极低
P0file 节点 factory 默认 permissive → 任意绝对路径读写安全低
P0worker-gRPC submit_task 无鉴权(独立 socket)安全/服务低
P0DAG 良性 run_if 跳过被计为 WorkflowFailed(flow.rs:467/848)执行内核/正确性低
P0checkpoint/run-dir 路径未净化 + delete_all_checkpoints("..") 破坏性删除执行内核/安全低
P1HTTP SSRF:IPv4-mapped IPv6 绕过 + DNS-rebinding TOCTOU安全中
P1serial 模式中途 abort 无终态事件/checkpoint;serial vs concurrent 语义分叉执行内核中
P1resume 对 DAG 不健全(部分失败升级为 Ok;跳过标记丢失)执行内核中高
P1AgentCancellationToken 漏唤醒竞态 → 可能不可取消Agent/并发低
P1可靠性栈(retry/timeout/resource/health)未接入 Flow 执行器完整度中高
P1无 LLM 级 429/5xx 重试退避(config 有字段但未用)LLM中
P1默认 SecurityProfile::Local fail-open;/v1/runs 无限流服务/安全低-中
P2resume tool-call 按名而非 call-id 关联 → 重复工具批误判Agent中
P2SemanticMemory 不稳定 ID 回归(仅修了一份拷贝)记忆低
P2Parallel supervisor 错误路径泄露 orphaned sibling agentAgent中
P2MCP stdio 无界 read_line / 无界通知 channel OOMMCP低-中
P2marketplace 默认 checksum-only + 允许 http://;plugin install --signed 自证明安全/生态中
P2Net capability = allow network* 忽略声明域名安全中
P2Gemini 内置注册表 base_url 拼接错误 → 走错 URLLLM低
P2生产节点代码 println! 当日志 → 改 tracing成熟度中
P2expr 解析器无递归深度上限 → 服务端执行 YAML 栈溢出 DoS执行内核/安全低
P2input_mapping 空格漂移:validate 通过但 factory 静默丢弃完整度低
P3AGENTS.md 严重过时(见 §9),污染所有 agent 上下文文档低
P3~/.yanshi/runs 无保留/清理,无界增长执行内核低
P3main.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/任意文件访问)。

结合“个人智能体框架、服务能力有限“的定位,优化优先级应为:

  1. 核心能力优先(Core-first): 先修影响**每一种使用(含个人)**的执行/agent 正确性与稳定性缺陷——UTF-8 panic、DAG 终态语义、resume 健全性、取消竞态、可靠性栈接线、LLM 重试、记忆运行时集成。这些是“生产就绪“的地基。
  2. 核心能力补齐: 结构化输出强制、token 流式、通用 HITL、agent 循环持久化——补齐对标主流框架的能力短板。
  3. 服务能力次之(Service-second): 执行沙箱强制、默认档 fail-closed、限流/配额、/metrics 鉴权、worker-gRPC 补鉴权、marketplace 默认签名。因服务范围有限,此层可采用“够用即止“的加固强度,但其中 file 节点任意读写、SSRF 两项因会影响个人使用(LLM 驱动的工具调用),提升至 P0/P1 与核心一并处理。
  4. 文档与卫生: AGENTS.md 重生成、doc drift、main.rs 拆分、依赖去重、cargo-audit 入 CI。

详细可执行方案见随本报告制定的优化计划(生产就绪路线图,按上述四层排序)。


本报告由 6 路并行只读审计 + 编排者本机 build/test/clippy/fmt 实测 + 5 项关键缺陷逐行复核汇总而成。子代理未运行 cargo;所有“已验证“证据来自编排者实跑。

Co-Authored-By: Oz oz-agent@warp.dev