scion-c2rust
v1.0.0
Published
Scion - AI-powered migration toolkit for Claude Code
Downloads
141
Readme
Scion（接木）
移花接木 —— 见森林也见树木
最近更新：2026-04-06
C → Rust 迁移工具包。将 C/C++ 代码库的功能"枝条"嫁接到 Rust（safe Rust + 必要时的 unsafe/FFI）的"根基"上。Scion 运行在 AI 编码 harness 之上 —— 同时支持 Claude Code 和 OpenCode。
前置条件
- 已安装以下任一受支持的 AI 编码 harness：
- Node.js（dashboard 脚本需要）
- Rust 工具链（
rustup+cargo+rust-analyzer），用于编译和静态分析目标代码
选择 harness
运行 scion init 时，交互提示会询问"Which code agent are you using?"，并同时提供 Claude Code 和 OpenCode 两个选项。选择你已安装的 harness，Scion 会按该 harness 期望的布局安装命令和 agent：
| 组件 | Claude Code | OpenCode |
|---|---|---|
| 命令 | <project>/.claude/commands/scion/ | <project>/.opencode/commands/scion/ |
| Agent | <project>/.claude/agents/ | <project>/.opencode/agents/ |
| Hooks | 合并入 .claude/settings.json | 不安装（见下文） |
| 下一步 CLI | claude | opencode |
所选 harness 会被记录在 <project>/.scion/harness.json，这样 scion update 就能在不再次询问的情况下重新定位。如需跳过交互提示，可向 scion init 传入 --harness claude-code 或 --harness opencode。
OpenCode hook 限制（v1）：Scion 的 hooks（dashboard 自动刷新、文件归属守卫）依赖 Claude Code 的 PreToolUse/PostToolUse 匹配器，在 OpenCode 的插件模型中没有一对一映射。在 OpenCode 上，安装步骤会打印一条非致命警告并跳过 hook 安装。迁移命令和 agent 仍然可用；你可以通过 node scripts/build-dashboard.js 手动刷新 dashboard。
安装
# 1. 克隆 Scion 工具包
git clone https://github.com/ZhifeiDou/Scion-HW.git
# 2. 进入你的迁移项目目录，运行安装脚本
cd /your/projectmacOS / Linux / Git Bash
chmod +x /path/to/Scion-HW/install.sh
/path/to/Scion-HW/install.shWindows (PowerShell)
.\Scion-HW\install.ps1选项
# 指定项目目录（不用先 cd）
./install.sh --project /path/to/project
.\install.ps1 -ProjectDir "C:\path\to\project"手动安装
skills/ → <project>/.claude/skills/
commands/ → <project>/.claude/commands/
agents/ → <project>/.claude/agents/
scripts/ → <project>/scripts/
web/index.html → <project>/web/
settings-hooks.json → <project>/.claude/settings.json
templates/docs/templates/ → <project>/docs/templates/ (reference templates only)
templates/CLAUDE.md → (not copied — generated by /scion:init)安装后使用
cd your-project
claude # 如果安装时选择了 OpenCode，则改为 `opencode`
/scion:init --source /path/to/c-project --target /path/to/rust-crate
# init 完成后说"开始迁移"，剩下全自动安装器做了什么
| 步骤 | 内容 | 位置 | 覆盖行为 |
|------|------|------|---------|
| 1 | Skills (1个) | <project>/.claude/skills/ | 同名覆盖 |
| 2 | 命令 + Agent (19个) | <project>/.claude/ | 同名覆盖 |
| 3 | Dashboard 脚本 + Web | <project>/scripts/, web/ | 覆盖脚本，不覆盖运行时 JSON |
| 4 | 空目录 + 参考模板 | <project>/docs/templates/, knowledge/ | 覆盖模板 |
| 5 | Hooks 配置 | <project>/.claude/settings.json | 合并 hooks 键 |
不会生成：CLAUDE.md、docs/taskboard.md 等项目状态文件（由 /scion:init 生成）。
可用命令
/scion:* — 迁移工作流
| 命令 | 说明 |
|------|------|
| /scion:init | 初始化迁移项目脚手架 |
| /scion:continue | 智能续作 — 自动判断下一步 |
| /scion:analyze | 深度分析 C 源码模块（编译单元、头文件、宏） |
| /scion:map | 生成 C -> Rust API/惯用法映射表 |
| /scion:decompose | 将分析结果拆解为实现任务 |
| /scion:review | PM 审查代码交付（safety、ownership、测试） |
| /scion:dr | 创建/解决设计冲突 |
| /scion:knowledge | 查询/记录迁移经验库（patterns / pitfalls / api-notes） |
| /scion:status | 查看项目进度 |
| /scion:gates | 跑全部 11 个静态 + 4 个运行时 gate（review 前的快速检查） |
| /scion:doctor | 预检：检查 cargo 工具链 + workspace 基线配置 |
工作流
/scion:init → 说"开始迁移" → 全自动init 配置好路径后，migrate agent 自动接管完整流程：
- 分析 — 扫描 C 源码模块（
.c/.h、Makefile、CMakeLists） - 映射 — C API → Rust crate / std 等价物
- 拆任务 — 细粒度实现任务（按模块、按函数、按数据结构）
- 实现 — 把 C 源码翻译为 idiomatic Rust（最多 3 并行）
- 审查 — 对照 C 源码行为验证（语义保持、内存安全、错误处理）
监控进度：http://localhost:3456 或 /scion:status
手动介入（如需）
| 命令 | 用途 |
|------|------|
| /scion:continue | 恢复自动推进 |
| /scion:analyze {module} | 重新分析某模块 |
| /scion:dr --create | 发起设计冲突裁决 |
| /scion:status | 查看进度 |
项目级护栏
除了 per-file 的静态卫生检查外，Scion 提供两个聚合脚本来强制 workspace 级别
不变式。可以在 target Rust 项目里直接跑（/scion:review Step 5.4 已自动调用）：
静态聚合器（scripts/all-gates.js）—— 11 个 gate
node scripts/all-gates.js <TARGET_PATH>| # | Gate | 对应 Issue | 检查内容 |
|---|------|-----------|---------|
| 1 | pitfall-citation-gate | #3 | PIT-N 引用 30 行内没有 mitigation: 标记 |
| 2 | blocked-marker-gate | #1 | BLOCKED: 窗口内没有 DR-N 引用 |
| 3 | cargo-package-fields-gate | #2 | 每个 crate 的 [package] 缺必填字段 |
| 4 | unsafe-boundary-gate | #6 | unsafe 出现在 src/ffi/ 之外，或任意位置出现 static mut |
| 5 | cargo-deny-config-gate | #7 | deny.toml 缺失或缺必需 section |
| 6 | stub-test-gate | #4 | 测试断言 *Stub 镜像类型 / mod stub / "TODO: requires AppContext" |
| 7 | silent-error-swallow-gate | #5 | let _ = fallible_call() |
| 8 | gate-cargo-metadata | #2 | workspace.members 目录存在性、rust-toolchain.toml components |
| 9 | gate-clippy-config | #6 | clippy.toml + [workspace.lints.rust] unsafe_code = "deny" |
| 10| gate-pitfall-semantic | #3 | PIT-013 / PIT-015 / PIT-019b 引用真的避免了反模式，不只是装饰 |
| 11| gate-blocked-dr-link | #1 | 每个 DR-N 引用都有对应的 DR 文件，状态不是 withdrawn |
运行时聚合器（scripts/all-runtime-gates.js）—— 4 个 gate
node scripts/all-runtime-gates.js --task T-042 <TARGET_PATH>| # | Gate | 对应 Issue | 实际调用 |
|---|------|-----------|---------|
| 1 | gate-supply-chain | #7 | cargo deny check + cargo audit |
| 2 | gate-unsafe-budget | #6 | 对比 .scion/geiger-baseline.json 统计 unsafe LOC 变化 |
| 3 | gate-coverage | #4 | cargo llvm-cov 按任务计算 line coverage（阈值在 .scion/policy.json） |
| 4 | gate-miri | #8 | 对 unsafe 表面有变化的 crate 跑 cargo +nightly miri test |
run-sanitizers.sh（ASan / TSan）有意不放进聚合器 —— 它是 nightly 任务，
逐 PR review 太慢。
按任务记录 marker delta
编排器（/scion:implement）在派遣 AgentR 时拍一张 marker count 快照，交付后
计算 delta：
# Step 1.5（派遣前，自动调用）：
node scripts/snapshot-markers.js --task T-042 --kind before <TARGET>
# Step 5.5（交付后，自动调用）：
node scripts/record-task-delta.js --task T-042 <TARGET>输出：
<TARGET>/docs/deliveries/T-042/delta.json—— 按 marker 类型分别记录新增/消除/净变化<TARGET>/web/marker-deltas.json—— dashboard 的滚动数据源<TARGET>/web/marker-deltas.html—— 可视化（红条 = 新增，绿条 = 消除）
这缓解 issues-found.md Issue #10（聚合 count 把"消除了 3 个 BLOCKED 但新增了
2 个"显示为净改善的反模式）。详见 knowledge-seed/patterns/PAT-026.md，与对应的
反模式 knowledge-seed/pitfalls/PIT-046.md。
环境预检（preflight）
在新机器上第一次用 Scion？跑一下：
node scripts/scion-doctor.js --workspace <target-rust-workspace>列出所有运行时 gate 依赖的 cargo 子命令（cargo-deny、cargo-audit、
cargo-llvm-cov，可选 cargo-fuzz、cargo-geiger、cargo-nextest，以及
miri rustup component），告诉你哪些已装/未装，并给出每个缺失项的精确
cargo install ... --locked（或 rustup component add ...）命令。加
--workspace 还会检查基线配置文件（Cargo.toml、clippy.toml、
deny.toml、rust-toolchain.toml）。CI 用 --json。
退出码 0 表示所有必需项都齐了；可选工具缺失不影响退出码。
报告 schema（给 dashboard 和 CI 审计用）
每个 gate 都会往 <TARGET>/.scion/reports/ 写 JSON（或者写到 per-task
delivery 目录）。每种报告的 shape 都在
docs/gate-report-schemas.md 里有详细文档。
把它当作 API 合约——加字段不影响消费者，但删/改字段必须升版本。
配套模板
真实的 C→Rust 项目需要这些基线配置才能过 gate。一键拷入 target workspace：
node scripts/init-gate-configs.js <target-workspace>
# 幂等：已有的文件会跳过。加 --force 覆盖、--dry-run 预览、--json 机器可读输出。或者从 templates/ 单独复制：
| 文件 | 用途 |
|------|------|
| templates/deny.toml | cargo deny 的 license + advisory 政策 |
| templates/audit.toml | cargo audit 的 ignore 政策 |
| templates/clippy.toml | disallow-method + disallow-type 列表 |
| templates/Cargo.workspace-lints.toml | 可直接 paste 的 workspace [lints] 表 |
| templates/rust-toolchain.toml | pin channel + clippy + rustfmt components |
| templates/policy.json | coverage / miri / blocked-marker 的阈值 |
| templates/fuzz/ | 标准的 C-vs-Rust 差分 fuzz crate 布局（PAT-009 Layer 3） |
包含内容
Scion-HW/
├── install.sh # macOS/Linux 安装脚本
├── install.ps1 # Windows PowerShell 安装脚本
├── README.md # 中文 README
├── README.en.md # English README
├── settings-hooks.json # Dashboard hooks 配置模板
├── skills/ # 全局知识库 -> ~/.claude/skills/
│ └── c-to-rust/
├── commands/ # 项目命令 -> .claude/commands/
│ └── scion/ # 迁移工作流命令
├── agents/ # 项目 Agent -> .claude/agents/
│ ├── agent-analyst.md # C 源码分析师（subagent_type: "agent-analyst"）
│ ├── agent-developer.md # Rust 开发者（subagent_type: "agent-developer"）
│ └── agent-arch.md # 架构分析师（subagent_type: "agent-arch"）
├── scripts/ # Dashboard 脚本 -> scripts/
│ ├── build-dashboard.js
│ ├── log-activity.js
│ ├── serve-dashboard.js
│ ├── check-consistency.js
│ ├── check-pitfalls.js
│ └── complete-task.js
├── web/ # Dashboard 页面 -> web/
│ └── index.html
└── templates/ # 文档模板 -> docs/templates/
└── docs/templates/
├── analysis-template.md
├── dr-template.md
├── session-template.md
└── task-template.md