Hacktoberfest 2026：维护者为十月标记出来的 issue，仍然开放、适合新手。 浏览 Hacktoberfest issue

tracking: 架构缺陷系列（9 项）—— 最小化嵌入不可达 + AG-UI 生产化受阻

未关闭
  • 哪里不对？
#52 6 条评论 0 个 reaction 已指派 0 人 在 GitHub 查看

维护者通常 1 天内回复

还没有人认领这个 Issue。

评估

难度
5/5
预计耗时
一周以上
新手友好度
25/100
Issue 类型
重构
描述清晰度
基本清楚
活跃度
活跃
技术栈
rust
领域
api, backend, build-system, documentation

调研方向

Start by reviewing the linked child issues #53–#61 and the cited files, including docs/architecture/invariants.md, README.md, src/acp/session.rs, and the AG-UI handler. Run the stated cargo checks and invariant tests to confirm the baseline. Done means all child issues are closed and the listed feature, session, documentation, and CI acceptance conditions pass.

由索引模型根据 Issue 内容生成。

描述

记号说明：正文中的「不变量 #N」指 docs/architecture/invariants.md 的编号，不是 GitHub issue 编号。本系列各 issue 的引用一律使用完整链接（如 #53）。

Summary

这是一组架构缺陷的 tracking issue，共 9 项。来源：为评估「C 端 Agent 业务（仅 Skill 加载 + 轻量 CLI 调用，无文件系统）能否基于 recursive 落地」而对全仓做的架构审查。

所有结论均以 path:line 引用 + 实测命令验证，非静态推测。基线 HEAD = cee6279。

两条被阻塞的事：

  • (a) 无法构建任何最小化的 recursive 嵌入版本 —— README.md:38-39 承诺的 --no-default-features 在 HEAD 上完全不工作（8 个 feature 组合实测全部失败）。
  • (b) AG-UI 通道（前端对接协议）产生的会话在系统内是二等公民 —— 多副本部署、按用户计费、跨会话记忆全部受阻。

另有治理层缺陷：「八条不变量」在两份契约文档里不是同一套规则（#2/#4/#6 冲突）。

子 issue 清单

# 标题 优先级 依赖
#53 核心 Tool trait 依赖 acp::ToolKind（分层倒置） P0 —
#54 acp 无 feature gate + agent-client-protocol-schema 非可选 P1 #53
#55 --no-default-features 无法构建（8 组合实测），README 声明不成立 P0 #53,#54（短期可独立修）
#56 AG-UI 服务端未抽象成层：agui_run 654 行单函数 P0 —
#57 AG-UI 另起一套更弱的 session，对 session 系统整体不可见 P0 #56（建议同做）
#58 message.rs ⇄ llm/ 真实循环依赖 P1 —
#59 活文档指向已不存在的路径 P2 —
#60 src/tools/ 36,055 行、49 文件全平铺 P2 —（但与 #59 同做）
#61 「八条不变量」#2/#4/#6 在两份契约文档里冲突 P1 —

建议落地顺序：#53 → #55(短期) → #54 → #56+#57 → #61 → #58 → #59 → #60

这 9 项不是并列的

链条 A — 最小化嵌入不可达（根因在 #53）
#53  Tool trait 返回 acp::ToolKind              ← 根因
        ↓ 强制 acp 无条件编译
#54  acp 无 feature gate（6,953 行 + 非可选 acp-schema 依赖）
        ↓ 而 acp/session.rs:178 用了 crate::mcp::
#55  --no-default-features 8 个组合全部构建失败
        ↓ 于是
     README.md:38-39「可嵌入最小内核」的声明不成立

顺序不可交换：#53 不做，#54 做不了；#54 不做，#55 只能「表面修好」（编译过了，但仍被迫带上 6,953 行 acp + 2,933 行 mcp + agent-client-protocol-schema）。

链条 B — AG-UI 生产化受阻（#56 与 #57 互为表里）
#57  AG-UI 另起一套更弱的 session                 ← 代价
        ↑ 因为没有层去承载它
#56  AG-UI 服务端不是层，是 654 行 handler 函数    ← 成因

#56 是「为什么写成了这样」，#57 是「写成了这样的代价」。建议一个设计、两个 PR。

独立项
  • #58 message.rs ⇄ llm/ 循环依赖 —— 拆分 crate 时的硬路障
  • #59 活文档路径漂移 —— 与 #61 同类病（活文档无守卫）
  • #60 src/tools/ 36,055 行扁平 —— 认知负担；与不变量 #4 冲突，需先决策
  • #61 八条不变量自相矛盾 —— agent 的宪法有两套

规模与风险

# 量级 风险
#53 半天 低（机械移动）
#54 1 天 中（动 workspace feature 声明）
#55 1 小时 / 随 #54 低
#56 2-3 天 中（新增抽象层）
#57 2-3 天 中（新增抽象层）
#58 半天 低
#59 1 小时 无
#60 1-2 天 低（但与不变量 #4 冲突）
#61 需作者决策 低

调查后被排除的候选问题（勿重复立项）

审查过程中有若干项看起来是缺陷但经核实不是。记录在此，避免重复立项。

1. run_core.rs 3,870 行 —— 不是缺陷

初判：全仓最大文件，与不变量 #1「agent loop stays small」冲突。
核实结果：不变量 #1 被严格执行，且当前全绿。

tests/invariants/loop_size_orthogonality.rs 里有四道守卫：

守卫 限制 当前
kernel_loop_stays_small kernel.rs ≤ 1000 行 ✅
runtime_stays_manageable runtime.rs ≤ 3700 行 ✅
run_inner_function_body_stays_small run_inner 函数体 ≤ 150 行 ✅
run_core_production_stays_small run_core.rs 生产代码 ≤ 1500 行 ✅ 1,407 
$ cargo test --test invariants loop_size
test loop_size_orthogonality::run_core_production_stays_small ... ok
test loop_size_orthogonality::runtime_stays_manageable ... ok
test loop_size_orthogonality::kernel_loop_stays_small ... ok
test loop_size_orthogonality::run_inner_function_body_stays_small ... ok
test result: ok. 6 passed; 0 failed

3,870 行的构成：生产代码 1,407 行 + 内联测试 2,462 行（64%）。守卫只量生产代码，内联测试不违规。且该文件有清晰的演进史（loop_size_orthogonality.rs:69-84）：G219 基线 ~394 行 → P1-1 拆分降到 ~117 行。

结论：这是一个被良好守护的文件，不是债务。

2. 两个 doc-comment 假阳性 —— 不是依赖

静态 grep 曾报出两处「向上依赖」，逐行核对确认只是文档注释提到：

  • src/runtime.rs:110 注释里提到 crate::http::SessionState
  • src/skills.rs:616 注释里提到 crate::run_core::call_llm

对比之下，#58 的 message ⇄ llm 是真 use，已逐行确认。

3. metrics_handler 1,320 行 —— 不是缺陷

src/http/handlers.rs 里最大的函数，但绝大部分是 Prometheus format! 静态字符串。不要顺手重构它。

与既有流程的关系

  • 本系列是 defect（已在 HEAD 上验证存在），不是 feature request。C 端能力缺口（远程 SkillSource、RunCli/HttpCall 工具、按租户工具表 resolver）性质不同，应另外排期，不混入本系列。
  • 适合直接走自迭代流程的：#53、#55、#58、#59（机械、低风险、可独立验证）。
  • 需要先出设计/决策的：#54（动 workspace feature）、#56+#57（新增抽象层）、#60（与不变量 #4 冲突）、#61（需作者拍板八条还是十条）。

Acceptance

  • 9 个子 issue 各自关闭（含各自的验收条件）。
  • 链条 A 完成后：cargo check --no-default-features --lib 在不开 acp / mcp 的情况下通过，且 cargo clippy --no-default-features -- -D warnings 干净；CI 有 feature-matrix 守卫。
  • 链条 B 完成后：AG-UI 一轮对话产出 .meta.json，recursive sessions list 可见，episodic_recall 可检索，成本落盘，多副本（Redis/S3）可用。
  • #61 完成后：三份文档的编号 → 标题映射一致，且有自动化守卫。

depends-on: #53
depends-on: #54
depends-on: #55
depends-on: #56
depends-on: #57
depends-on: #58
depends-on: #59
depends-on: #60
depends-on: #61

主要语言
Rust
星标
4
派生
0
平均合并
5 小时 32 分钟
30 天内合并 PR
7

环境准备

  • 提供 Dockerfile 或 Docker Compose 文件
  • 没有 Pull Request 模板
  • 没有贡献指南

从这里开始

  1. 先读完整个 Issue，再读项目的贡献指南。
  2. 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
  3. Fork 仓库，在一个分支上完成修改。
  4. 提交 Pull Request，并在描述里引用这个 Issue 编号。

jeffkit/recursive 的其他 Issue

查看 jeffkit/recursive 的全部 Issue

相似的 Issue

更多 Rust Issue

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。