Crate wanning_init

Expand description

wanning-init:给编码工具吐 Wanning MCP 配置的生成器(W-36;W-43a 产品化改版)。

产品边界(与 wanning-demo 演示台分开):本 crate 是对端工具的接入生成器—— 零网络、零真实消费、零文件副作用(默认只打印 stdout;写文件必须显式 --out 且绝不覆盖已存在文件,动别人工具的配置 = 危险动作,拒)。

W-43a 产品化:配置不再吐占位符——wanning-mcp 可执行文件与审计 WAL 路径在生成时解析成真实绝对路径直写进配置(新用户拿到就能用,不必手改 {{WAL_PATH}}),默认预算策略 --budget 显式写进 args(保守默认,用户可改); 不给 --wal 时落产品默认账本 ~/.wanning/wal.jsonl(Windows %USERPROFILE%\.wanning\wal.jsonl,见 wanning_core::paths)。路径一律转成 正斜杠(Windows 反斜杠在 JSON/YAML/TOML 里都要转义,正斜杠 Windows 也认)。

平台契约来源(零编造):

claude-code:仓内 .mcp.json 现物(W-19 真插实测)——字段面带 type: stdio;
trae:仓内 .trae/mcp.json 现物(W-17 直核)——字段面无 type,且官方明示 command 不能含空格(解析出的路径含空格 = 拒绝生成,绝不产出装不上的配置);
codex:~/.codex/config.toml 的 [mcp_servers.<id>] 片段,W-35 直核无路径变量(W-43a 起写实路径,连占位符也不留)+ TOML # 注释;
kimi:.kimi-code/mcp.json(用户级 $KIMI_CODE_HOME/mcp.json 或项目级), W-40 本机隔离实验修订——kimi-code 0.39.1 实测无 kimi mcp 子命令(W-17 的 kimi mcp add 属 legacy kimi-cli 挂法),mcpServers 形态无 type 字段、无 ${...} 变量,严格 JSON 无注释;
workbuddy:.workbuddy/mcp.json(W-37 直核官方 MCP-Guide),mcpServers 结构同款但字段面无 type(官方示例只有 command/args/env),文档未提及 ${...} 变量;W-17 曾查不到,W-37 换路数(robots/sitemap 绕开 JS 首页)破冰, 见 docs/research/workbuddy.md;
deepseek-harness:不是 mcp.json——Cordis overlay YAML patch(W-44 任务书直核官方 docs/user/guide/mcp-memory.md 通用格式 + 本机 dsh 0.1.0-rc.7 包内 @deepseek-ai/dsh-mcp-client README 字段表)。patch entry = - insert: 列表, cwd: !!js process.cwd() 的 js-tag 按官方示例原样;YAML 支持 # 注释(与 TOML/shell 同侧)。真实 dsh 二进制取证:dsh --profile headless --dump-config --patch <生成文件> exit 0 且 wanning 行进入组合树(W-44 轮,零网络零会话); 会话级端到端待所有者(dsh 会话 = 模型会话 + 网络,红线 2)。
openclaw:原生支持 MCP(本机 2026.5.22 有 openclaw mcp 子命令族,W-45 隔离实测 mcp set/list/show 全绿)——产出 openclaw mcp set 命令行而非文件内容:openclaw.json 由宿主自己管理(实测落盘含 commands/messages/agents 等骨架段),CLI 写入只动 mcp.servers.wanning 一段,天然满足「绝不覆盖」。字段面 {command, args} 与实测落盘逐字一致;官方 docs.openclaw.ai/mcp 直核 stdio 字段 command/args/env/cwd + env 安全过滤(拦 NODE_OPTIONS 等)。
hermes:原生支持 MCP(本机 hermes-agent v0.19.1 有 hermes mcp 子命令族, W-45 隔离实测)——产出 hermes mcp add wanning --command <bin> --args <args> 命令行(discovery-first:add 即真连发现工具,挂载即验证;实测 2/2 工具现身, 落 $HERMES_HOME/config.yaml 的 mcp_servers.<name> = {command, args, enabled: true})。W-45 隔离实测全链路:hermes -z -t wanning + 本地 mock LLM → allow 400 落 WAL;二次会话同 nonce → replay 拒(链连续)。工具现身名 mcp__wanning__*(deferred catalog),模型侧经 tool_call(name, arguments) 间接调用——直接调 mcp__ 名会报 does not exist(实测教训,写进 notes)。

注释纪律:各工具注释语法不同——TOML/shell/YAML 用 # 行内注释;严格 JSON 没有注释语法,claude-code/trae/kimi/workbuddy 的说明只能打在 stdout 的 Artifact::notes(文件内容保持纯净 JSON,防解析崩)。

Structs§

Artifact: 一份生成物:notes 打在 stdout(说明/警示),content 是落盘/复制的净内容。
GenerateOptions: 生成入参:None 的字段按产品默认解析。
Resolved: 解析完成的一对真实路径(生成内容只吃这个,占位符从此不存在)。

Enums§

InitError: 生成失败。全部 fail-closed:宁可拒生成,绝不产出一份装不上/对不上账的配置。
Platform: 支持的平台(生成器矩阵;字段权威=仓内现物与调研文档,见模块文档)。

Constants§

DEFAULT_BUDGET_CENTS: 生成配置里写死的默认总预算(分)。保守默认,用户可在生成配置里改这个数。与 wanning-mcp::DEFAULT_CAP_CENTS 同值——刻意不引依赖同步,改任一侧时两边一起改(契约测试钉住 1000 这个数)。

Functions§

first_run_notes: first-run 三行引导(W-43a):重启 → 认工具 → 验闸。打在 stdout(不进配置文件)。
generate: 生成一份平台配置(W-43a 产品形态:真实绝对路径 + 默认预算,零占位符)。内容与仓内现物/调研的字段面契约锁定(见 crates/wanning-init/tests/matrix.rs)。
generate_with: 已解析路径直接生成(调用方已 resolve 过时免得扫两遍 PATH)。
parse_platform: 解析 --platform 取值;未知值 fail-closed 列全矩阵。
resolve: 解析一对生成入参(PATH 取自进程环境)。
resolve_bin: 解析 wanning-mcp 可执行文件路径(纯函数,PATH 由调用方传入便于测试): 显式路径必须是已存在的文件;否则按 PATH 逐目录找 wanning-mcp(+平台可执行后缀);都找不到 = InitError::McpBinaryNotFound 并列出搜过的目录。
resolve_wal: 解析审计 WAL 路径:显式路径按当前目录转绝对;缺省 = 产品默认 ~/.wanning/wal.jsonl(家目录解析不出 = fail-closed,绝不猜落点)。
run_cli: 统一 CLI 主体:旧 bin wanning-init 与统一入口 wanning init 走同一段逻辑 (program 只进报错前缀,保证两个入口的报错口径一致)。退出码:0 成功;2 用法错(参数缺失/未知);1 运行失败(解析不到路径/拒绝覆盖)。