Craft Anything 路线图实战指南:里程碑、架构约束与 Agent 协作开发流程

原创2026-11-02 12:24:061,739 阅读
文章标签:人工智能AI 应用AI Agent代码智能体MCP 服务逆向工程桌面应用开发工具

Craft Anything 路线图实战指南:里程碑、架构约束与 Agent 协作开发流程

docs/ROADMAP.md 是 Craft Anything 仓库的"共享计划书":它用可勾选的最小变更单元,把「研究任意软件如何工作,并据此重建」这一产品目标拆成 M0–M4 五个里程碑,并同时约束人类贡献者与 AI Agent 的协作方式。本文以该文档为骨架,逐条拆解它的条目格式、五条架构铁律、依赖排序与开放工作清单,并结合仓库源码说明每条规则在代码里究竟落到哪个 trait、哪张表、哪条 cargo xtask 检查上,读完后你可以直接按图索骥地领取一个 - [ ] 条目并完成它。

一、路线图的定位与快照来源

文档开篇就明确了分工边界:docs/STATUS.md 说明"今天什么能用、怎么验证的",而 docs/ROADMAP.md 说明"接下来做什么、谁负责、Agent 可以领取什么"。两者是互补而非重复的关系,因此阅读顺序应当是先 STATUS 判断能力边界,再用 ROADMAP 选任务。

文档头部记录了它的快照来源,这一点对判断信息新鲜度很关键:

项目 值
起草时间 2026-10-18
起草基线 main 分支 1d47a3e
起草时测试数 624 个测试通过
最近更新 2026-10-22(M4 段落继续更新至发布记录)

也就是说,文档中的"Where it stands"列是时间点快照,不是实时状态。例如 docs/STATUS.md 的抬头写的是"Last updated 2026-10-23 from main(923 tests passing)"——测试数从 624 涨到 923,正说明路线图条目被勾掉时能力已经扩张。根目录 Cargo.toml 的 [workspace.package] 当前 version = "0.2.0",而路线图 M4 段落记录 v0.1.0 已于 2026-10-31 签名发布,说明版本在首次发布后已向前推进;阅读时应以"条目是否 [x]"为准,而不是以里程碑标题的完成度字面理解。

二、一条路线图条目由哪些字段构成

文档规定每个条目包含四类信息,这是全篇最重要的格式约定:

  • id:形如 R<milestone>.<n>,例如 R1.1、R2.9、R3.11。分支名、PR 标题、开发日志都以它为锚点。
  • owner:只有两种角色,从不写人名——maintainers(由项目维护者掌舵,Agent 可领取其中未被认领的待办变更,但标记为 decision 的设计决策必须等维护者)与 open(任何人可领)。
  • status:取值限定为 todo · in progress · blocked (<why>) · done。注意 blocked 必须写明原因,例如 R3.5 的 Status: blocked (needs an Android device or emulator)。
  • pending changes:一串 - [ ] 小条目,文档明确要求它们是"small, independently mergeable units",即能独立合并的最小单元。

文档还给出一个隐含的语法要求:- [ ] 行必须挂在对应的 ### R… 标题下。这不是文学约定,而是被工具解析的机器可读格式,见下文 cargo xtask pending 的实现。

认领(Claiming)的准确写法

在开始之前,把 — claimed: <name>, branch <branch> 写在该待办变更行上,并尽早推送分支(或开 draft PR),让别人看得见。不要领取别人已认领的变更。

这条规则在 AGENTS.md 的"Working rules (mandatory)"和 CONTRIBUTING.md 中被重复强调,可见它是硬性流程而非建议。仓库中目前除文档说明外没有实际的 claimed: 记录(grep 只命中 AGENTS.md、CONTRIBUTING.md 与 ROADMAP.md 的规则描述),意味着所有 - [ ] 条目在写这篇文章时都处于可领取状态。

完成(Finishing)的四步闭环

文档要求收尾时同时完成四件事,缺一不可:

  1. 把该行改成 [x];
  2. 补上 commit 或 PR 链接;
  3. 如果"什么能用"发生了变化,更新 docs/STATUS.md;
  4. 在 log/devlog.md 追加一行。

第 4 步有个容易踩的坑:AGENTS.md 说明 log/ 是被 gitignore 的本地草稿记录——"anything others need goes in the PR, docs/STATUS.md or docs/ROADMAP.md"。所以 devlog 是给自己看的,别人能读到的事实必须落在文档或 PR 里。

三、五条架构规则:新功能必须落在"接缝"上

路线图第二章 "Architecture rules for new work" 开宗明义:"The project should be easy to fork and bend. New features land behind a seam, not inside a match." 这五条规则是判断一个 PR 是否合格的核心标准,下面逐条对照源码。

规则 1:用 trait + registry,而不是枚举

文档原文覆盖 target kinds、checks、builders、asset providers、external engines 五类扩展点,要求"加一个文件加一行注册",就像工具(tool)已经做到的那样。

这条规则在 R1.1 中已经落地为真实类型。打开 crates/ai/src/rebuild/kinds/mod.rs,TargetKind trait 的每个方法都对应文档描述的能力:

pub trait TargetKind: Send + Sync {
    /// Stable id, stored with the project: `"website"`, `"app"`, `"game"`.
    fn id(&self) -> &'static str;
    fn words(&self) -> KindWords;
    /// How strongly the request, target and stack say "this kind" (higher wins); `None` if not.
    fn detect(&self, cx: &DetectCx) -> Option<u32>;
    fn default_stack(&self, cx: &DetectCx) -> &'static str;
    fn named_stack(&self, _cx: &DetectCx) -> Option<&'static str> { None }
    fn goal(&self) -> &'static str;
    fn brief_sections(&self, _cx: &BriefCx) -> Vec<String> { Vec::new() }
    fn checks(&self, ws: &Workspace) -> Vec<Box<dyn Check>>;
    fn refine(&self, check: &CheckResult) -> String { /* … */ }
}

配套的注册表就是文档所说的 "a registry that holds built-in implementations":

impl KindRegistry {
    pub fn built_in() -> KindRegistry {
        KindRegistry { kinds: vec![Arc::new(WebsiteKind), Arc::new(GameKind), Arc::new(AppKind)] }
    }
    pub fn register(&mut self, kind: Arc<dyn TargetKind>) {
        self.kinds.retain(|k| k.id() != kind.id());
        self.kinds.push(kind);
    }
}

register 先删除同 id 的旧实现再追加,因此 fork 者可以用自己的实现替换内置种类,而不必改核心代码——这正是文档"fork 者可以换零件"的意图。

同样地,Check trait 只有三个方法(id、applies、run),返回值是结构化的 CheckResult:

pub trait Check: Send + Sync {
    fn id(&self) -> &'static str;
    fn applies(&self, _cx: &CheckCx) -> bool { true }
    fn run(&self, cx: &mut CheckCx) -> Result<CheckResult, ToolError>;
}

并且文档提到的"加一行注册"在 docs/extending.md 中给出了完整对照表:工具加一个 v.extend(<area>::specs())、新种类实现 TargetKind 并 KindRegistry::register、新判断实现 Check、新外部引擎在 crates/engines/src/table.rs 加一条 ExternalEngine 表项。R1.3 的 AgentAdapter(crates/ai/src/cli_agents/adapters.rs)与 R1.4 的 AssetProvider(crates/engines/src/assets/mod.rs)延续同一模式。

规则 2:目录类数据用表,不用代码

"Stacks, game-engine build recipes, model ids and prices, and engine install pins live in typed tables (or TOML files embedded with include_str!), not in string matches or prompt text."

R1.1 的收尾项给出了这套做法的范例:crates/ai/src/rebuild/stacks.toml 用 [[stack]] 与 [[library]] 描述每种技术栈。以 Next.js 条目为例,它同时承载了四类信息:

[[stack]]
name = "Next.js + TypeScript"
asked_by = [" nextjs ", " next js ", " use next ", " using next ", " in next "]
uses = ["next"]
steps = "Use Next.js (App Router) + React + TypeScript, exported as a static site. ... the output must be app/out ..."
  • asked_by:请求里出现哪些短语就算"点名要这个栈";表头注释说明匹配发生在小写化、标点转空格、两侧补空格之后的文本上,所以 "Next.js," 读作 next js,这也解释了 R2.3 里"Next.js、nextjs 和 next js 都算数"的行为。
  • uses:package.json 中能证明"这个构建确实用了该栈"的依赖,用于 R2.3 的"记录实际使用的栈"。
  • steps:给 builder 的具体指令,支持 {editor}、{player}、{ext} 占位符(见文件头注释)。
  • engine:unity / unreal / godot / rust,把栈与游戏引擎构建配方关联起来。

外部引擎的资料同样被集中:crates/engines/src/table.rs 的模块注释解释了为什么用 const 数组而不是数据文件——字符串是 'static,不需要解析、没有回退路径、字段写错是编译错误、SHA-256 pin 不会因为文件加载失败而丢失。R1.5 的完成条件之一正是"一张引擎表驱动 KNOWN、ToolPaths、install pins 与 Engines 设置页,并有测试保证 tool_paths! 与表一致"。

规则 3:Headless first,流程即工具

"Everything works without the GUI. Anything a person can start from the UI (rebuild, follow-ups, answering questions, engine installs, launching a result) is reachable through Engine::call and the CLI… Orchestration, persistence and process control never live in ui-egui or apps/*."

这条规则在 R1.6 被拆成可执行的检查项,并且落地为自动化测试 crates/ui-egui/tests/headless_parity.rs。该测试的文档注释说明了它的强制力:

每个会"做事情"的 CraftApp 方法或按钮,都必须在 ACTIONS 表中登记它的无界面等价物:一个 tool id(MCP 与 CLI 的 kebab-case 形式)或一个内置 CLI 命令;尚无等价物的记作 Pending 并注明等待的 tool 与 roadmap 条目;纯视图动作记为 UiOnly 并给出理由。

测试会验证四件事:表中提到的每个 tool 都已注册且可通过 CLI 拼写抵达;每个 CLI 命令与 flag 真实存在于 apps/craft-anything-cli/src;某个 Pending 的工具一旦实现,测试就失败,迫使把该行改为 Tool;每个 &mut self 方法必须在表中或 PLUMBING 中,否则"新方法无法悄悄溜进来"。这是一种把路线图条目编码成编译期/测试期约束的典型做法。

配套的还有分层检查(见 xtask/src/main.rs):LAYERS 表规定 ui-egui 是 L6,只能依赖更低层;UI_ONLY 列出只有 UI 层可用的工具包(egui、eframe、winit、rfd 等)。R1.6 进一步要求 ui-egui 不得直接 std::fs 写入或 std::process 启动程序,且允许列表"只能缩小"。

规则 4:所有持久化文件都带版本

"Every file we write and read back (craft.json, config.toml, project.toml) carries a version, has a JSON schema, and has a migration path."

R1.9 把这条规则做成了常量与步骤列表。具体契约集中在 docs/file-formats.md:读取统一走"解析为原始文档 → 按版本逐步迁移到当前版本 → 转成 Rust 类型"三步,迁移执行器在 crates/engine/src/versioned.rs。文件清单给出了每个文件的 owner、当前版本与"更新版本的文件如何处理"策略:

文件 所有者模块 当前版本 遇到更新版本
<project>/craft.json engine::workspace(Manifest) MANIFEST_VERSION = 1 只读打开,拒绝保存
config.toml engine::settings(Settings) SETTINGS_VERSION = 2(版本 2 把 [engines.ghidra] enabled 迁到 deep_mode) 加载但不覆盖保存
<name>.cany/project.toml engine::project(ProjectMeta) FORMAT_VERSION = 1 直接拒绝,提示"update Craft Anything"
<project>/app/mechanics.json engine::mechanics MECHANICS_VERSION = 1 检查失败并说明
<project>/checks/round-N/self-test.json engine::self_test 1 检查失败并说明
<project>/feed.json ai::rebuild::feed FEED_VERSION = 1 从不覆盖

新增迁移步骤的三步法(改常量、向 *_STEPS 追加一个 n→n+1 的函数、补一条读旧样例的测试)也在同一文档中写明,并有一条编译期断言保证列表长度与版本常量一致。这与路线图中"versioned files"是同一个机制的两个视角。

规则 5:结构化结果,不靠英文前缀判定

"Decisions such as 'did the build pass' read typed fields, never English text prefixes."

R1.2 的第一个勾选项就是这条规则的历史修复:CheckResult { check, passed, similarity, note, artifacts } 取代了 note.starts_with("Build succeeded") 这种字符串判断。同一条原则在工具层同样适用:docs/tool-ids.md 明确要求代码"绝不把 tool 名字当作文本判断",而应比较 Registry::canonical(name)、读取声明的 Effects::CARRIES_TARGET_CONTENT,或使用工具附近的 id 常量。

四、里程碑总览与判读方法

路线图第三章用一张表给出五个里程碑的目标、负责人与"截至 2026-10-22 的状态":

里程碑 目标 负责人 当时状态
M0 Foundations 文档与代码一致、许可证核查、违规修复、一次真实端到端运行 maintainers 完成;main 分支保护开关仍待维护者打开
M1 Extensibility 为 target kinds、checks、builders、asset providers、engines、plugins 建立接缝 maintainers 除运行期与行为检查(随 R2.4/R2.5)、引擎传输层(R1.5)外完成
M2 Product completeness 每种 target kind 都走完 study → build → check → refine,且有不含糊的真检查;不依赖 Agent 应用也能构建 maintainers 网站完整;应用与游戏可构建可运行;API-key 构建与其他 Agent 已实现但未真实运行
M3 Engine depth 更多工具,以及已知的部分实现 open 284 个工具;设备类工具等 Android 真机;游戏资源导出继续
M4 Release 打包、CI、签名、托管层 maintainers(later) CI 通过;各平台发布工作流在 main;v0.1.0 已发布并签名

判读这张表要注意三个细节。第一,M0 的"完成"不含分支保护——那是仓库设置而非代码,所以它留着 - [ ]。第二,M1 的"完成"被明确切出缺口,缺口对应的正是尚未 [x] 的子项,说明里程碑状态是子项的函数而非独立断言。第三,M3 的负责人是 open,且文档把它定义为"open lane"——不受相位排序阻塞,随时可做。

五、开放工作清单与 cargo xtask pending

路线图明确规定:"Every unticked - [ ] line in this file is open work, under the item it belongs to." 也就是说,没有第二份 issue 清单——文档本身就是唯一真源。

为了让这句话可执行,仓库提供了 cargo xtask pending。其实现就在 xtask/src/main.rs,逻辑非常直白:

  1. 读 docs/ROADMAP.md;
  2. 逐行扫描:遇 ### 或 ## 标题就切换当前分组;遇 - [ ] 就把该行记为一条待办;接着的缩进行(以 6 个空格开头)拼接到上一条,作为续行;
  3. 其他任何行都视为"待办结束";
  4. 按分组打印,最后输出 N open item(s) under M roadmap entries;--count 只打印总数。
} else if let Some(item) = line.strip_prefix("- [ ] ") {
    flush(&mut open, &mut groups, &heading);
    open = Some(item.trim().to_string());
} else if open.is_some() && line.starts_with("      ") {
    if let Some(o) = open.as_mut() {
        o.push(' ');
        o.push_str(line.trim());
    }
}

这段代码解释了为什么格式必须严格遵守:换行缩进、- [ ] 的空格、标题层级都会被解析。它同时解释了文档中的另一条规则——"当发现缺失的工作时,把它作为 - [ ] 行加到正确条目下,而不是留在 PR 描述或聊天里"。因为只有写进这套语法的工作,才会被 pending 统计到。

日常使用方式:

cargo xtask pending            # 按条目分组列出全部开放工作
cargo xtask pending --count    # 只看总数

由于 pending 不做任何网络或环境探测,它可以在离线、任意分支上运行,适合作为"今天做什么"的第一条命令。

六、相位与依赖:为什么不能随便开工

"Order and dependencies" 表把工作排成 0–4 五个相位,并给每项标注 Depends on,其中加 soft 的依赖"应先行但不阻塞"。规则是:只有 Depends on 列全部完成,条目才能开始;同相位内可并行;M3 是自由泳道。

相位 条目 依赖 放在这个位置的理由
0 Baseline R0.1 文档对齐 main — 每个 Agent 都要读它们
0 R0.7 一次真实端到端运行 —(需要已登录的 claude) 重构前先有可用参照
0 R0.3 许可证卫生 — 便宜,可并行
0 R0.4 规则 10 修复 — 在 R1.6 迁移前先清掉直接进程调用
0 R0.5 小正确性项 — 可并行
0 R0.2 抢救 PR #1 decision 为 M4 解锁
0 R0.8 测试不触碰真实机器 — 由一个测试真的开始下载而发现
0 R0.6 工具命名 decision 在新工具(R1.6)与插件(R1.8)前固定 id
1 Seams R1.1 TargetKind、拆分 rebuild.rs R0.7(soft) match 散落最多;M2 全部建立在它之上
1 R1.2 Check trait R1.1 检查挂在 target kind 上
1 R1.3 Builder 适配器注册表 — 与 R1.1 无关,可并行
1 R1.4 资源提供者 trait — 可并行
1 R1.5 L3 外部引擎 trait — R1.6 的引擎安装依赖它
1 R1.9 版本化文件 — R1.6 的项目服务会写新文件
2 Headless R1.6 GUI 不再是胶水 R1.1、R1.5、R1.9、R0.4、R0.6 此后一切都可脱离 GUI 抵达
3 Product R2.1 用 API key 构建 R1.3、R1.6 去掉对 Agent 应用的依赖
3 R2.2 更多编码 Agent R1.3
3 R2.3 网站覆盖与更好的度量 R1.2
3 R2.6 同时多个重建 R1.6
3 R2.7 请求决定怎么构建 — 曾出现"点名技术栈却被忽略"
3 R2.8 Clean room 就是 Clean room — Clean room 曾读过原件的代码与文件
3 R2.9 日常使用:输入、项目、设置 — 由真实使用发现
3 R2.10 固定构建(pins) — 在项目变化时保留一个可打开的构建
4 Depth R2.4 应用与游戏的运行期研究 R1.2、R1.6
4 R2.5 非 Web 构建的行为检查 R1.2
4 R1.7 动态工具注册表 R1.6
4 R1.8 插件 R1.7、R0.6 冻结扩展 API,所以放最后
Any R3.1–R3.11 引擎深度、游戏归档与资源、应用事实 — 开放泳道
Last M4 Release R0.2、R0.3 与相位 3

这张表的实战价值在于识别"看起来能做但其实被卡住"的条目。例如 R1.8 插件虽已全部 [x],但它的排队逻辑(依赖 R1.7、R0.6)说明了为什么"冻结扩展 API"必须晚于工具命名定稿:插件 id 一旦对外,改名就是破坏性变更。

七、M1 深挖:接缝真正的形状

M1 是整条路线图的技术枢纽,它的验收标准不是"代码能跑",而是"以后加东西不用改核心代码"。下面结合源码看几个关键接缝。

R1.1:从 1.5k 行 rebuild.rs 到 trait 对象

路线图记录了改造前的痛点:"enum Kind {Website, Game, App} 在 ai/src/rebuild.rs(1.5k 行)与 UI 中约十处被 match"。完成条件包括:拆成 rebuild/{mod,kind,study,check,brief,locate,output,tests}.rs 且行为不变;三种 target 变成实现,RunOptions::kinds 持有注册表;162 种组合下 brief 逐字节与改造前一致;UI 从 trait 读取文案;旧的 Kind 枚举、choose、kind_of 全部删除。

"162 种组合下 brief 逐字节一致"这条验收标准值得学习:重构明确禁止顺带改行为,把"没变"变成了可断言的测试,而不是代码评审的主观判断。

R1.2:检查的顺序语义与"未知不算相似"

crates/ai/src/rebuild/kinds/mod.rs 中的 run_checks 揭示了检查链的执行语义:

for c in kind.checks(ws).into_iter().chain(plugin_checks) {
    if !c.applies(&cx) { continue; }
    let r = c.run(&mut cx)?;
    let failed = !r.passed;
    out.push(r);
    if failed { break; }
}

三个语义都在路线图中被显式要求:顺序执行("checks run in order")、失败即停("a failed one stops the rest",因为后续检查依赖前面已证明的事实,例如截图依赖构建成功)、插件检查排在 kind 自己的检查之后(R1.8 的"run after a kind's own checks")。

同一段落还定义了几条容易被忽略但影响很大的判定原则:

  • CheckResult::unknowns:无法比较的部分必须记录,并阻止"good enough"——"missing evidence never counts as alike"。
  • CheckResult::claims:把"构建必须做到什么"拆成可独立判定的断言(网站的每页不得横向滚动、不得新增错误、每个文件都要加载成功、原有的地标必须在;游戏的自测每一步;Deep 模式机制表里的每个原始数值必须出现在代码里)。任一条不通过就不能算好。
  • DeepOnly(C) 包装器:只在 Deep 模式且目标是本地程序时才运行(见 crates/ai/src/rebuild/kinds/mod.rs),对应"Apps in Deep mode keep the sheet too"。

R1.5:引擎表与可复现安装

R1.5 的意图是"一次下载必须可校验"。完成项包括:每个下载都有 SHA-256;支持 tar.gz/tar.xz;单文件 pin(ArchiveFormat::File { name })用于 Vineflower 这类单 jar 分发;Temurin Java 21 在 Linux/macOS 上按 x64/arm64 分别 pin。未完成项也写得同样具体:Ghidra 在 Linux 与 macOS 上的安装"只在测试里校验过 Java pin,尚未真机尝试";Rizin 的 Linux 版本因为解包后约 800 MB,需要流式解压才能支持。

这种"把未验证的部分写成待办"的写法,正是 docs/STATUS.md 中"Known limits"章节的哲学:宁愿标出"只在 Windows 上试过",也不含糊地宣称跨平台可用。

R1.3 与 R1.4:适配器与资源提供者

R1.3 的完成项显示 AgentAdapter 覆盖了 id、参数、必需 flag、流解析、resume、进程设置、登录预检;未知 Agent 走 plain adapter。文档还记录了一次评估后放弃的方案:ACP 被评估为长驻、基于 session 的 JSON-RPC 协议,因此更适合作为另一种 Conversation 实现(AcpConversation 与 CliConversation 并列),而不是每轮一次的 AgentAdapter。这条记录解释了为什么 R2.2 另开一个条目承载 ACP,而不是塞进 R1.3。

R1.4 则把"钱"也变成了表:模型 id 与价格进 assets.toml,提示词从表里读价格,而不是在 assets_note 里重复写死 $0.53;每个 provider 有自己的密钥位置 assets:<id>;预算默认值 ASSET_BUDGET_USD 可被设置覆盖。仍开放的两项都与真实计费有关:用真 key 跑一次 Nano Banana Pro 并核对账单($0.15),以及确认 fal "向上取整到整兆像素"的计费规则究竟把 1024×1024 算 1 还是 2 MP。

八、M2 到 M4:产品完备性、引擎深度与发布

R2 系列:把"能用"变成"可靠"

M2 的条目几乎都来自真实使用的失败,这也是它们可信的原因:

  • R2.7 请求决定怎么构建:起因是一句 "Build it in Electron" 被构建成了 Rust——因为 brief 把 kind 的默认栈当作硬指令排在请求之后。修复方向是"请求里点名的语言、框架、引擎、库或平台优先",栈表只是默认值;同时让 build check、记录的栈与 Play 都跟随 app/ 里真正构建出的东西。仍开放的两项(Electron 应用某次 90 秒内没产出截图、请求点名栈表外的技术时仍要求默认引擎已安装)都被如实保留。
  • R2.8 Clean room 就是 Clean room:2026-10-23 的维护者 decision 明确"Clean room 永不看原件内部",Deep 模式是独立开关而不再绑定 Ghidra。落地方式是 crates/engine/src/clean_room.rs 里的 TOOLS 白名单:只有"不接触目标"或"像访客/用户一样从外部观察"的工具可入列,其余工具(含插件的)在 app、CLI、MCP、Agent 中一律拒绝并提示开启 Deep 模式。新增工具默认是 Deep-only,直到被显式加入白名单——这是一个"默认拒绝"的安全设计。
  • R2.9 日常使用:条目密度最高(数十条 [x]),从"输入框在打字时不再跳动"到"滚动条在静止时可见"、"侧边栏折叠后图标仍对齐"。这类条目证明路线图不只管架构,也承担可用性债的登记。
  • R2.10 固定构建:把一次可用的构建冻结为 pinned/<n>/,或用硬链接做"轻量 pin"共享依赖与媒体;实测把 291 MB 的 pin 降到 49 MB(部分来自剔除 .pdb、.lib、.d、锁文件)。

R3:引擎深度是"开放泳道"

R3 覆盖无线信号解码(rtl_433)、Cutter/rizin 会话、ILSpy 与 Vineflower 反编译、Android 设备工具、浏览器走查深度、可对比的程序运行、游戏归档(Unreal .pak、IoStore .utoc/.ucas、Unity 序列化文件与 bundle)、资源导出(Unity 纹理到 PNG、BC7/BC6H)以及单文件应用解析。它的状态标记很诚实:R3.5 整条 blocked (needs an Android device or emulator),R3.3 仍是 todo(Frida 会话仍是内存记账,尚未真实 attach/detach)。

M4:发布清单

M4 段落是一份可直接照做的发布检查表:密钥扫描(cargo xtask secrets,含 --history 全历史扫描)、CONTRIBUTING.md/SECURITY.md、PR 与 issue 模板、README 快速开始、CI 与各平台发布工作流、图标重建(packaging/icons.sh、cargo xtask ico)、DMG 布局与 codesign --strict 校验、FreeBSD 包内容检查。它也留下了未完成项:main 分支保护与私有漏洞报告需维护者打开;README 快速开始在干净机器上走一遍;把发布工作流从面向 Node.js 20 的 actions 版本迁走;托管层(账号后端、用量计量)尚未开始。

九、把路线图变成日常命令流

路线图的所有检查都能通过 cargo xtask 触发,其入口在 xtask/src/main.rs。与路线图直接相关的命令如下:

命令 作用 与路线图的对应关系
cargo xtask pending 列出全部 - [ ],按条目分组 "Open work" 章节的唯一真源
cargo xtask pending --count 只输出总数 快速看进度
cargo xtask layers 校验 crate 分层、UI 专用依赖、测试隔离 架构规则 1/3 与 R0.8、R1.6 的强制手段
cargo xtask tools / --check 生成/校验 docs/tools.md R3.1"每个工具都列在 docs/tools.md"
cargo xtask schemas / --check 生成/校验 docs/schemas/ R1.9 与 R2.5 的 schema 发布
cargo xtask wasm 校验 L0–L2 能在 wasm32 下构建 AGENTS.md 金规则 6
cargo xtask licenses 许可证清单 R0.3
cargo xtask secrets / --history 扫描待提交内容/全历史 M4 发布清单
cargo xtask ci 串起全部检查 见下方说明

ci 子命令的链路值得单独看,因为它就是"一次合格提交"的定义:

Some("ci") => {
    layers(&root)
        && locks::check(&root)
        && secrets::secrets(&root, false)
        && run("cargo", &["fmt", "--all", "--check"])
        && run("cargo", &["clippy", "--workspace", "--all-targets", "--", "-D", "warnings"])
        && run("cargo", &["test", "--workspace"])
        && run("cargo", &["clippy", "-p", "craft-anything-engine", "--features", "wasm-plugins", "--all-targets", "--", "-D", "warnings"])
        && run("cargo", &["test", "-p", "craft-anything-engine", "--features", "wasm-plugins"])
        && tools(&root, true)
        && schemas(&root, true)
        && wasm()
}

注意 wasm-plugins 那两行是单独跑 clippy 与 test 的:因为该 feature 会编译 wasmtime,体积大且默认关闭,R1.8 明确要求"cargo xtask ci 用 --features wasm-plugins 对引擎做 lint 与测试"。

一个典型条目的完整操作序列

以领取一个 open 且无依赖的 - [ ] 为例:

# 1. 看有哪些开放工作,挑一个没有 claimed 标记、依赖已完成的
cargo xtask pending

# 2. 从最新的 main 开分支,名字带 roadmap id
git switch -c feature/r3.11-packed-standin main

# 3. 在 ROADMAP.md 对应行加上认领标记,并尽早推送
#    - [ ] … — claimed: <name>, branch feature/r3.11-packed-standin
git commit -am "chore(r3.11): claim the stand-in backend item"
git push origin feature/r3.11-packed-standin

# 4. 写代码与测试,跑本次改动相关的检查
cargo fmt --all
cargo test -p <touched crates>
cargo clippy -p <touched crates> --all-targets -- -D warnings
cargo xtask layers
cargo xtask schemas        # 若改了持久化结构

# 5. 收尾:勾选、补链接、必要时更新 STATUS、本地 devlog 记一行

第 3 步的提交与推送顺序,在 docs/pitfalls.md 中有血泪记录:曾有 git switch main && git pull 因未提交改动而失败,却被误读为"还在自己的分支",结果提交与强推直接打到了 main。因此该文档给出的规则是:提交与推送前先 git branch --show-current,并且永远按名字推送 git push origin <branch>。同一文档还记录了"一个 PR 只带着 claim 就被合并"的事故,教训是把 commit、push、建 PR、合并当作四个独立步骤并逐条读取结果,不要串成一条 && 链后盲目继续。

十、阅读与引用这份路线图时的边界

最后强调几条事实边界,避免把计划当成现状:

  1. 未勾选 ≠ 未开始。文档明确 Status: in progress 的条目下可以同时存在已完成的 [x] 与待办 - [ ],例如 R1.5 的表与 pin 已完成,只剩传输层与真机验证。
  2. [x] 的含义是"代码 + 检查通过",但不一定等于"真机跑过"。文档会显式区分,例如"Vineflower: run it once on a real JAR(作者机器上没有 Java)"仍未勾选,而 Cutter 会话"只对 stand-in server 测过,还没对真实 Cutter 测过"。
  3. testing 章节的 624 / 923 是时间点数字,不应作为当前测试数引用;需要当前数字时应运行 cargo test --workspace。
  4. 里程碑表里的工具数(284)与 STATUS 表一致,包含 AI 与 setup 层注册的工具(引擎本体 271),引用时要带上这层限定。
  5. 文档自身的相对链接需要按仓库根目录解析:例如 docs/STATUS.md、docs/tools.md、docs/tool-status.md、docs/extending.md、docs/file-formats.md、docs/tool-ids.md、docs/pitfalls.md、docs/claude-code.md 与 AGENTS.md。

docs/ROADMAP.md 的价值不在于它列了多少功能,而在于它把"计划"写成了机器可解析、可统计、可被测试强制的工程契约:- [ ] 行是唯一的工作真源,cargo xtask pending 负责清点,cargo xtask layers 与 headless_parity 负责守住架构规则 1 与 3,docs/file-formats.md 的版本常量负责守住规则 4,CheckResult 的 typed 字段负责守住规则 5。理解这套对应关系之后,你既能准确判断某个条目"现在能不能做",也能写出一个不会破坏接缝的 PR。

登录后查看全文
craft-anything