# Lime 工具治理开发计划

## 1. 目标

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

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

---

## 2. 本轮已完成

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

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

### 验收标准

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

---

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

- [x] 建立完整 `ToolCatalogEntry`
- [x] 引入 `ToolSourceKind`
- [x] 引入 `ToolPermissionPlane`
- [x] 引入 `ToolLifecycle`
- [x] 补全 core / workbench / browser assist tools
- [x] 形成默认 allowlist 子集

### 验收标准

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

---

## Phase C：runtime inventory（已完成）

- [x] 新增 `agent_tools/inventory.rs`
- [x] 新增 `agent_runtime_get_tool_inventory`
- [x] 接入 `agentRuntime.ts`
- [x] 接入 mock / governance command catalog / API test

### 验收标准

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

---

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

- [x] 输出 `docs/prd/tools/README.md`
- [x] 输出 `docs/prd/tools/architecture.md`
- [x] 输出 `docs/prd/tools/inventory.md`
- [x] 输出 `docs/prd/tools/development-plan.md`

### 验收标准

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

---

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

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

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

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

### 推荐命令

```bash
# 轻量 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 的工具数继续增长，也不会再回到“上下文失控 + 权限混乱”的状态。