proxycast/docs/prd/tools/development-plan.md

Lime 工具治理开发计划

1. 目标

把 Lime 的工具系统从“多源并存、权限混写、上下文不可审计”收敛为：

• 单一 metadata 事实源
• 单一 native catalog
• MCP runtime 独立但统一注入
• inventory 可审计
• 权限平面分层

---

2. 本轮已完成

Phase A：事实源收口（已完成）

• 把 tool metadata 解析统一到 lime_core::tool_calling
• MCP manager 改为复用共享 metadata
• tool_search bridge tool 改为复用共享 metadata
• provider 转换层改为复用共享 metadata

验收标准

• 不再存在多处独立解析 deferred_loading / allowed_callers / input_examples
• tool search 与 MCP list/search 的语义一致

---

Phase B：native catalog 完整化（已完成）

• 建立完整 ToolCatalogEntry
• 引入 ToolSourceKind
• 引入 ToolPermissionPlane
• 引入 ToolLifecycle
• 补全 core / creator / browser assist tools
• 形成默认 allowlist 子集

验收标准

• 能回答“当前到底有哪些 native tools”
• 能区分 current / compat
• 能区分 session allowlist / parameter restricted / caller filtered

---

Phase C：runtime inventory（已完成）

• 新增 agent_tools/inventory.rs
• 新增 agent_runtime_get_tool_inventory
• 接入 agentRuntime.ts
• 接入 mock / governance command catalog / API test

验收标准

• 一条命令能同时输出 catalog / registry / extension / MCP 四视角
• 能看到 visible / deferred / caller_allowed 状态
• 能发现 registry 未被 catalog 覆盖的漂移项

---

Phase D：文档与治理说明（已完成）

• 输出 docs/prd/tools/README.md
• 输出 docs/prd/tools/architecture.md
• 输出 docs/prd/tools/inventory.md
• 输出 docs/prd/tools/development-plan.md

验收标准

• 有架构图
• 有时序图
• 有流程图
• 有 current / compat / dead-candidate 分类
• 有 Codex / Aster / Lime 对照

---

Phase E：测试矩阵补强（本轮完成）

• 补齐 catalog.rs 的 surface / lifecycle / default allowlist 边界测试
• 补齐 inventory.rs 的 caller / extension source / deferred 状态测试
• 补齐 mcp manager 的冲突保序与默认 defer 阈值测试
• 补齐 tool_search 的 extension 前缀匹配与状态判定测试
• 补齐 provider 层对 x-lime / x_lime alias 与去重行为测试
• 补齐前端 agentRuntime.ts inventory helper 默认参数测试
• 新增 lime-agent 轻量测试载体，复用 catalog.rs / inventory.rs 纯逻辑模块，绕开主包 Tauri 大链接
• 把 tool_permissions.rs / shell_security.rs 迁出 lime-agent 的 lib.rs 编译图，改为独立 integration test 夹具加载，并补治理守卫与 Vitest 护栏

Phase F：执行权限事实源收口（本轮完成）

• 新增 src-tauri/src/agent_tools/execution.rs
• 把 workspace execution permission 模板从 aster_agent_cmd.rs 收回 agent_tools 边界
• 统一 bash / Task warning gate 语义
• 把 execution profile 暴露到 inventory / agentRuntime.ts
• 补齐 execution.rs 与 inventory 的定向测试
• 新增 NativeAgentConfig.tool_execution，承接 persisted policy 覆盖
• 让 request.metadata.harness.executionPolicy 承接 runtime session override
• 让 agent_runtime_get_tool_inventory 支持 metadata，返回 runtime override 后的 effective profile
• 给 inventory 增加 provenance 字段，逐项标记 default / persisted / runtime
• 补齐配置层 default / alias / roundtrip 测试

验收标准

• 对齐 Codex 风格的四类断言：
  1. 默认值是否稳定
  2. legacy / alias 字段是否兼容
  3. 显式配置是否覆盖默认策略
  4. 持久语义是否在多层之间保持一致
• 新增工具治理逻辑至少要被以下矩阵之一覆盖：
  • catalog 边界
  • runtime inventory 快照
  • MCP runtime 过滤 / 搜索 / defer
  • provider metadata 透传
  • 前端命令 helper

本轮验证策略

• 小包优先：优先跑 lime-providers、lime-mcp 与前端 agent.test.ts
• 轻量逻辑优先：catalog.rs / inventory.rs 的纯逻辑单测优先从 lime-agent 执行，测试名使用模块前缀：
  • agent_tools::catalog::tests::...
  • agent_tools::inventory::tests::...
• 主包降级为编译检查：lime 主包测试会触发超大链接；在当前环境磁盘仅余约 4.4Gi 时，优先做 cargo check / 定向编译验证
• 边界说明：若后续 CI 或本地磁盘空间恢复，应追加一次 lime 主包的完整定向测试，把 catalog.rs / inventory.rs / aster_agent_cmd.rs 新增测试全部实跑

推荐命令

# 轻量 Rust 纯逻辑测试
cargo test --manifest-path "src-tauri/Cargo.toml" -p lime-agent \
  agent_tools::catalog::tests::test_tool_catalog_entries_for_surface_counts_and_lifecycle_boundaries -- --exact

cargo test --manifest-path "src-tauri/Cargo.toml" -p lime-agent \
  agent_tools::inventory::tests::test_build_tool_inventory_marks_extension_sources_and_statuses -- --exact

# MCP / Provider 定向测试
cargo test --manifest-path "src-tauri/Cargo.toml" -p lime-mcp empty_query_prioritizes_always_visible_then_name -- --nocapture
cargo test --manifest-path "src-tauri/Cargo.toml" -p lime-providers supports_x_lime_alias -- --nocapture

# 前端契约与治理守卫
npm test -- "src/lib/api/agent.test.ts"
npm test -- "src/lib/governance/legacyToolPermissionGuard.test.ts"
npm run test:contracts
npm run governance:legacy-report

---

3. 下一刀建议

3.1 优先级 P1：删除旧权限系统前先做守卫

本轮已完成：

• tool_permissions.rs / shell_security.rs 已明确标为 dead-candidate
• 已从 lime-agent crate 根移除公开表面
• 已退出 lime-agent 的 lib.rs 编译图，仅通过 tests/legacy_permission_surfaces.rs 测试夹具加载
• 已在治理脚本与 Vitest 护栏中禁止新引用回流

剩余原因：

• 这两套逻辑虽然已不在主链路，但文件级删除仍属于高风险动作，需要单独确认

---

3.2 优先级 P1：把“策略覆盖层”接到 execution 事实源

本轮已完成：

• workspace allowlist / parameter restriction / warning gate / sandbox profile 已有统一 execution 事实源
• aster_agent_cmd.rs 已从手工 permission 模板拼装降级为 orchestration
• inventory 已能审计 execution profile
• NativeAgentConfig.tool_execution 已承接 persisted policy
• request.metadata.harness.executionPolicy 已承接 runtime session override
• inventory 已可查看 runtime override 后的 effective execution profile
• inventory 已可逐项查看 execution provenance，而不是只看最终值

剩余下一步建议：

• 如果后续要做 UI 可视化，再把 effective policy 与来源标识直接展示在工具调试页
• 保持 catalog.rs 只描述目录层，execution.rs 只描述执行层，避免覆盖逻辑再次散回命令层

---

3.3 优先级 P2：继续做减法，而不是再加抽象

不要再新增：

• 第二套 tool metadata parser
• 第二套 native tool list
• 第二套 browser tool 目录
• 第二套 MCP 注入路径

后续所有新工具都应满足：

1. 在 catalog.rs 有记录
2. metadata 走 lime_core::tool_calling
3. runtime inventory 能看见

---

4. 风险与对策

风险	说明	对策
catalog 与 runtime 再次漂移	新增工具时只改注册不改目录	以 inventory + command catalog 作为守卫
MCP caller 语义再次分裂	MCP tool schema / extension allowed_caller 各自解释	一律先过 tool_calling.rs
权限语义再次混写	catalog、allowlist、sandbox、approval 又掺在一起	强制按目录层 / 上下文层 / 执行层汇报与设计
旧权限系统回流	新代码重新引用 tool_permissions.rs	标记 dead-candidate，并增加仓库级扫描守卫

---

5. 最终建议

这次治理完成后，后续迭代请遵守三条硬规则：

1. 新增工具先入 catalog
2. 新增 metadata 字段先入 tool_calling.rs
3. 新增运行时注入能力必须能被 inventory 看见

只要守住这三条，Lime 的工具数继续增长，也不会再回到“上下文失控 + 权限混乱”的状态。