From 2f422679260afac5a26bdf22c5a292e3f1649605 Mon Sep 17 00:00:00 2001 From: BQBBLZ Date: Fri, 7 Aug 2026 10:24:55 +0800 Subject: [PATCH] docs: clarify project positioning and evidence status --- README.md | 30 ++++++++++++++++++++---------- README_CN.md | 30 +++++++++++++++++++----------- docs/RESUME_PROJECT_SUMMARY_CN.md | 20 +++++++++++++------- 3 files changed, 52 insertions(+), 28 deletions(-) diff --git a/README.md b/README.md index 836ad12..2903bb5 100644 --- a/README.md +++ b/README.md @@ -8,21 +8,31 @@ `candle-cli` is a Rust-first diagnostic CLI for PyTorch-to-MindSpore migration. It combines deterministic AST scanning, official mappings, cross-framework runtime evidence, and transactional patches to locate the first semantic divergence and produce verifiable, reversible migration results. +It was built for a concrete migration failure mode: direct API replacement can make a PyTorch example run under MindSpore while silently changing dtype, shape, return structure, default training semantics, random data flow, or optimizer state. `candle-cli` turns that process into an auditable workflow: scan APIs without executing the project, apply evidence-backed rewrites, run both frameworks when configured, compare traces, identify the first observable divergence, and roll back unsafe edits. + +## Current evidence status + +| Area | Current checked-in evidence | Boundary | +|------|-----------------------------|----------| +| Static scan and mapping | 25/25 real-project files scanned; mapped-call coverage improved from 24.22% to 44.77% on PyTorch Examples/nanoGPT/DETR; 41.98% on the frozen Segment Anything holdout | Static coverage, not runtime migration accuracy | +| Runtime parity | PyTorch 2.6.0+cu124 and MindSpore 2.9.0 runs cover API chains, components, training steps, data pipeline/randomness, graph mode, optimizer state, and checkpoint recovery | Fixed small benchmarks, not unseen-project success rate | +| End-to-end workflow | `migrate run` composes scan, rewrite, validation, trace comparison, and rollback; the MNIST classifier-head slice passes 3/3 frozen dual-runtime scenarios with 2/2 byte-level rollbacks | 25-line executable slice, not full MNIST migration | +| Safety and context | M18 Linux heldout blocks or gates 12/12 applicable attacks with 0/8 benign false blocks; context retention keeps 20/20 frozen facts while reducing estimated tokens by 81.76% | Deterministic suites; provider cache hit rate remains unclaimed | +| CI and release readiness | Rust, Python, schema/evidence, Ubuntu Rust, and Windows Rust checks passed on PR #7 | Pending repository merge/release decision | + +Full reproducibility notes and résumé-safe wording are maintained in [`docs/RESUME_PROJECT_SUMMARY_CN.md`](docs/RESUME_PROJECT_SUMMARY_CN.md), [`docs/MILESTONE_EXECUTION_PLAN_CN.md`](docs/MILESTONE_EXECUTION_PLAN_CN.md), and `benchmarks/results/`. + ## Highlights -- **Agentic tool loop** — bounded multi-step execution with sub-agent task delegation -- **Streaming output** — real-time token-by-token display as the model generates -- **Layered memory** — session memory + project-level persistent memory -- **Sandboxed shell** — optional Docker container isolation with network cutoff -- **Multi-model** — DeepSeek, Ollama, vLLM, OpenAI via persistent Python bridge -- **Permission control** — four modes with path boundary enforcement and interactive confirmation -- **Observability** — `/tools`, `/status` (with token estimation), `/trace` (with millisecond timing and JSON export) -- **Fault tolerance** — API retry with exponential backoff (4xx not retried), shell timeout with kill -- **Rust core + Python bridge** — Rust owns CLI, agent loop, tools, permissions; Python bridges model backends with persistent worker - **Migration scanner** — discovers aliased PyTorch calls, inferred Tensor methods, source spans, and arguments without importing either framework -- **Component parity** — captures PyTorch/MindSpore forward and gradient traces separately, then scores equivalence, defect class, and first-divergence Top-1 - **Verified migration rewrites** — previews minimal API/dtype edits, applies them transactionally, runs an explicit validator, and supports checksum-protected rollback - **End-to-end migration workflow** — one command composes scan, preview, apply, program validation, trace comparison, and failure rollback into a JSON/Markdown report +- **Cross-framework diagnostics** — captures PyTorch/MindSpore forward, gradient, data pipeline, graph-mode, optimizer, and checkpoint traces, then scores equivalence, defect class, and first-divergence Top-1 +- **Rust core + Python bridge** — Rust owns CLI, agent loop, tools, permissions, and structured protocols; Python bridges OpenAI-compatible APIs, Ollama native mode, local models, and migration analysis +- **Agentic tool loop** — bounded multi-step execution with read-only sub-agent task delegation and shared budgets +- **Safety controls** — path-boundary enforcement, confirmation gates, bounded read/shell output, optional Docker shell isolation, and frozen security regression/heldout suites +- **Context and observability** — layered memory, deterministic context compaction, `/tools`, `/status`, `/trace`, millisecond timing, JSON export, and provider usage collection hooks +- **Fault tolerance** — API retry with exponential backoff (4xx not retried), persistent Python worker reuse, shell timeout, and process cleanup ## Quickstart diff --git a/README_CN.md b/README_CN.md index ebb1a68..9b87e55 100644 --- a/README_CN.md +++ b/README_CN.md @@ -8,23 +8,31 @@ `candle-cli` 是面向 PyTorch→MindSpore 工程迁移的 Rust-first 智能诊断 CLI：通过确定性 AST 扫描、官方映射、双框架运行证据和事务式 Patch，定位首个语义偏差并生成可验证、可回滚的迁移结果。 -项目的一句话定位、可复现指标、推荐简历表述与能力边界见 [`docs/RESUME_PROJECT_SUMMARY_CN.md`](docs/RESUME_PROJECT_SUMMARY_CN.md)。 +它解决的是框架迁移中的具体问题：机械替换 PyTorch API 后，代码可能仍能运行，但 dtype、shape、返回结构、默认训练语义、随机数据流或优化器状态已经发生变化，最终异常位置往往不是根因。`candle-cli` 将这个过程收敛为可审计流程：不执行目标工程即可扫描 API，基于官方证据生成改写，按需自动启动 PyTorch/MindSpore 双运行时，比较 Trace，定位首个可观测偏差，并在不安全时自动回滚。 + +## 当前证据状态 + +| 能力方向 | 当前随仓库固定的证据 | 边界 | +|---|---|---| +| 静态扫描与映射 | PyTorch Examples/nanoGPT/DETR 共 25/25 文件扫描成功，调用映射覆盖率由 24.22% 提升至 44.77%；冻结规则后 Segment Anything 留出集为 41.98% | 静态覆盖率，不是运行时迁移准确率 | +| 双框架运行诊断 | PyTorch 2.6.0+cu124 与 MindSpore 2.9.0 覆盖 API 链、组件、训练步、数据流水线/随机性、Graph Mode、优化器状态和 Checkpoint 恢复 | 固定小型基准，不代表未知项目成功率 | +| 端到端迁移闭环 | `migrate run` 串联扫描、改写、验证、Trace 比较和回滚；MNIST 分类器头切片完成 3/3 双运行时场景和 2/2 字节级回滚 | 25 行可执行切片，不是完整 MNIST 迁移 | +| 安全与上下文 | M18 Linux 留出集中 12/12 可评估攻击被拦截或门禁，8/8 正常项无误拦；20 个冻结会话中事实保留 20/20，估算 Token 减少 81.76% | 确定性评测集；Provider 缓存命中率仍不声明 | +| CI 与发布状态 | PR #7 已通过 Rust、Python、schema/evidence、Ubuntu Rust 和 Windows Rust 检查 | 仍待合并和是否正式 release 的决策 | + +项目的一句话定位、可复现指标、推荐简历表述与能力边界见 [`docs/RESUME_PROJECT_SUMMARY_CN.md`](docs/RESUME_PROJECT_SUMMARY_CN.md)、[`docs/MILESTONE_EXECUTION_PLAN_CN.md`](docs/MILESTONE_EXECUTION_PLAN_CN.md) 与 `benchmarks/results/`。 ## 核心特性 -- **Agentic 工具循环** — 有界多步执行，支持子 Agent 任务委派 -- **流式输出** — token 级实时打印，边生成边显示 -- **分层记忆** — 会话记忆 + 项目级持久化记忆 -- **沙盒执行** — 可选 Docker 容器隔离，网络切断 -- **多模型后端** — DeepSeek、Ollama、vLLM、OpenAI，通过持久化 Python bridge 统一接入 -- **权限控制** — 四种模式，路径边界检查，交互式确认 -- **可观测性** — `/tools`、`/status`（含 token 估算）、`/trace`（含毫秒计时和 JSON 导出） -- **容错机制** — API 指数退避重试（4xx 不重试），shell 超时强制终止 -- **Rust 核心 + Python 桥接** — Rust 负责 CLI、agent loop、工具、权限；Python 桥接模型后端，子进程跨轮复用 - **迁移静态扫描** — 无需安装 PyTorch/MindSpore，解析 import 别名、Tensor Method、源码位置和参数信息 -- **组件级差分验证** — 分离采集 PyTorch/MindSpore 前向与梯度轨迹，评估等价性、缺陷分类和首错 Top-1 - **可验证迁移重写** — 最小化预览 API/dtype 修改，事务式应用，显式执行验证命令，并支持校验和保护的回滚 - **端到端迁移闭环** — 单个命令串联扫描、预览、应用、程序验证、Trace 比较和失败回滚，输出统一 JSON/Markdown 报告 +- **双框架差分诊断** — 分离采集 PyTorch/MindSpore 前向、梯度、数据流水线、Graph Mode、优化器和 Checkpoint 轨迹，评估等价性、缺陷分类和首错 Top-1 +- **Rust 核心 + Python 桥接** — Rust 负责 CLI、Agent Loop、工具、权限和结构化协议；Python 桥接 OpenAI-compatible API、Ollama 原生模式、本地模型和迁移分析 +- **Agentic 工具循环** — 有界多步执行，支持只读子 Agent 委派和共享预算 +- **安全控制** — 路径边界检查、确认门禁、read/Shell 输出上限、可选 Docker shell 隔离，以及冻结安全回归/留出评测 +- **上下文与可观测性** — 分层记忆、确定性上下文裁切、`/tools`、`/status`、`/trace`、毫秒级计时、JSON 导出和 Provider usage 采集入口 +- **容错机制** — API 指数退避重试（4xx 不重试）、持久化 Python Worker 复用、shell 超时和进程清理 ## 快速开始 diff --git a/docs/RESUME_PROJECT_SUMMARY_CN.md b/docs/RESUME_PROJECT_SUMMARY_CN.md index 2c0b488..1c4e5e2 100644 --- a/docs/RESUME_PROJECT_SUMMARY_CN.md +++ b/docs/RESUME_PROJECT_SUMMARY_CN.md @@ -6,6 +6,12 @@ 这句话比“基于 Rust 的 Agentic CLI”更准确，因为它先说明解决的工程问题，再说明实现形态。 +## 当前工程状态 + +截至当前候选版本，项目已完成 M0–M18 路线中的主要功能闭环：静态扫描、证据映射、事务式改写、双框架 Trace 对齐、训练/数据/Graph 诊断、安全留出集、上下文事实保留、doctor、安装脚本、演示脚本、最终证据聚合和跨平台 CI 配置。PR #7 已通过 GitHub Actions 中的 Python 3.10、Python 3.12、Ubuntu Rust、Windows Rust 以及 schema/benchmark integrity 检查；仓库仍待合并该 PR，并由用户决定是否创建正式版本 tag 与 GitHub Release。 + +尚未完成、也不应写成已完成的数据是：真实 Provider Token/Cache 命中率、正式单/多 Agent 配对收益，以及 Candle 本地推理后端的生产可用实现。 + ## 项目由来与技术演进 项目源于 MindSpore 迁移中的真实痛点：把 PyTorch 示例机械替换为 MindSpore API 后，代码可能继续运行，但中间张量已经发生 dtype、shape、返回结构或默认语义变化，最终报错位置往往不是根因；缺失算子和行为差异也难以仅靠异常栈定位。 @@ -45,9 +51,9 @@ flowchart LR | 安全回归与冻结留出 | M8 开发集 12/12 攻击被拦截/门禁、10/10 正常放行；M18 Linux 留出集 12/12 可评估攻击被拦截/门禁、8/8 正常项无误拦 | M18 共 15 个攻击项，压缩包入口、symlink 竞态和 Windows junction 三项明确不适用且不计入分母；不代表未知攻击防御率 | | 上下文事实保留 | 20/20 文件/命令/错误/待办/决策事实保留；20/20 历史事实任务可回答；估算 Token 23,146→4,221，减少 81.76% | 冻结确定性会话与启发式 Token，不是 Provider 计费数据或未知会话泛化率 | | Provider 缓存 | Bridge 已支持采集并设置完整性门禁；已发布基准仍为 `null` | 尚未固定真实 Provider 请求集，不能声称具体缓存命中率 | -| 当前全量测试 | Rust 177/177；Python 350/350；Clippy `-D warnings` 通过 | Linux 隔离测试目录与 `zgr` Python；托管 Ubuntu/Windows CI 需在 PR 后取得首次结果 | +| 当前全量测试 | Rust 177/177；Python 350/350；Clippy `-D warnings` 通过；PR #7 的 Python 3.10/3.12、Ubuntu Rust、Windows Rust、schema/benchmark integrity 全部通过 | Linux 隔离测试目录与 `zgr` Python；GitHub Actions 结果来自当前 PR 候选分支，仍待合并进入 main | -机器可读结果和完整限制分别位于 `benchmarks/results`、`docs/M6_REAL_PROJECT_RESULTS.md`、`docs/M7_RUNTIME_PARITY.md`、`docs/M8_SECURITY_BENCHMARK.md`、`docs/M9_CONTEXT_BENCHMARK.md`、`docs/M11_COMPONENT_PARITY.md`、`docs/M12_TRAINING_PARITY.md`、`docs/M13_END_TO_END_WORKFLOW.md`、`docs/M14_REAL_MODEL_DUAL_RUNTIME.md`、`docs/M15_DATA_PIPELINE_RANDOMNESS.md` 与 `docs/M16_GRAPH_ADVANCED_TRAINING.md`。 +机器可读结果和完整限制分别位于 `benchmarks/results`、`docs/M6_REAL_PROJECT_RESULTS.md`、`docs/M7_RUNTIME_PARITY.md`、`docs/M8_SECURITY_BENCHMARK.md`、`docs/M9_CONTEXT_BENCHMARK.md`、`docs/M11_COMPONENT_PARITY.md`、`docs/M12_TRAINING_PARITY.md`、`docs/M13_END_TO_END_WORKFLOW.md`、`docs/M14_REAL_MODEL_DUAL_RUNTIME.md`、`docs/M15_DATA_PIPELINE_RANDOMNESS.md`、`docs/M16_GRAPH_ADVANCED_TRAINING.md`、`docs/M17_CONTEXT_AGENT_ABLATION.md`、`docs/M18_RELEASE_SECURITY_CI.md` 与 `docs/FINAL_BENCHMARK_REPORT_CN.md`。 ## 推荐简历版本 @@ -85,11 +91,11 @@ flowchart LR 这些限定不会降低项目含金量，反而说明评测口径、数据泄漏和工程证据意识是设计的一部分。 -## 下一轮最有价值的开发 +## 合并 PR #7 后的建议动作 -1. **运行真实 Token/Cache 评测：** Bridge 已能聚合 input/output/cached input tokens，实验协议也已冻结；下一步选择 Provider、模型和价格日期，完成真实配对运行。 -2. **完成单/多 Agent 消融：** 共享预算机制和 10 个迁移任务已就绪，需在相同请求、工具和超时预算下完成三次重复并决定是否存在可写入简历的收益。 -3. **验证并发布候选版本：** CI、安装脚本、Changelog、证据聚合和 Release dry run 已实现；下一步在 PR 上取得 Ubuntu/Windows 托管结果，再由用户确认版本号、Tag 与 Release。 +1. **同步 main 并创建候选发布版本：** 合并 PR #7 后同步本地和服务器代码，确认 README、README_CN、简历摘要、Changelog、安装脚本和 demo 脚本均指向同一组证据；随后由用户决定版本号、tag 与 GitHub Release。 +2. **运行真实 Token/Cache 评测：** Bridge 已能聚合 input/output/cached input tokens，实验协议也已冻结；下一步选择 Provider、模型和价格日期，完成真实配对运行。完成前只能写“支持采集”，不能写具体缓存命中率。 +3. **完成单/多 Agent 消融：** 共享预算机制和 10 个迁移任务已就绪，需在相同请求、工具和超时预算下完成三次重复，并判断是否存在可写入简历的稳定收益。 4. **继续拆解 AdamW 差异：** 对偏置修正、权重衰减、学习率序列和状态槽逐项消融，形成可执行迁移建议。 -项目已经完成真实模型、数据流水线、Graph Mode、多步训练状态和确定性上下文事实保留的可审计验证；下一步应完成真实 Provider Token/Cache 与单多 Agent 配对运行，再通过 CI 和正式发布形成完整工程闭环。 +项目已经完成真实模型切片、数据流水线、Graph Mode、多步训练状态、安全留出集和确定性上下文事实保留的可审计验证。当前最优先动作不是继续堆功能，而是先合并 PR #7、同步 main、固定发布口径，再决定是否补真实 Provider Token/Cache 与单/多 Agent 配对实验。