[V1110-PLUGIN] [P2] 插件作者体验：脚手架＋一次 apply 的反馈回路＋错误码对照表-xwcode-AtomGit

已开启

[V1110-PLUGIN] [P2] 插件作者体验：脚手架＋一次 apply 的反馈回路＋错误码对照表 #130

kemeng创建于 3 天前

kemeng成员

3 天前创建

结论

能力面补齐之后，第二个劝退点是作者体验。现状：手写 WIT 降级表、手搓指针长度打包 ABI、管线性内存、靠负码猜错误。替代方案是 20 行 markdown（Skill）。理性的人会选后者。

这一条不性感，但它决定「有人愿意写」这件事能不能发生。

钉面

打包返回值形：(ptr << 32) | len（runner.rs 头注 · source.rs 导出签名 [I32, I32] -> I64）
负码全集（abi.rs）：-2 E_NOT_CARRIED / -3 E_REJECTED / -4 E_MALFORMED / -5 E_BUFFER_TOO_SMALL / -6 E_UNKNOWN_SEAM / -7 E_TIMEOUT / -8 E_QUOTA
现状无脚手架：新插件需从 xw-plugin-prompt-conventions 复制 abi.rs / host.rs / seam.rs 三文件（633 行里约 200 行是样板）

要做

脚手架：cargo xtask new-plugin <name> 生成可编译的最小插件（含 host.rs / seam.rs / 一个能跑的 apply / 一个 tool_call），cargo build --target wasm32-wasip1 后能直接装。
一次 apply 的反馈回路：装机失败时，宿主必须输出人话而非负码。示例：
- 缺导出 ⇒ 缺少导出 tool_call（签名应为 (i32,i32)->i64），而不是 E_NOT_CARRIED
- world 不匹配 ⇒ 指出缺哪个 interface
错误码对照表进文档，每个码配一句「通常是因为」和一句「怎么改」。
本地调试入口：xwcode plugin run <wasm> --emit-prompt 之类，能在不启动完整会话的情况下看 apply 产出了什么。

验收

新人从零到装上一个打印 hello 的插件，不超过 15 分钟，全程只用文档。
故意做错三处（缺导出 / 错签名 / 越权声明），每处都得到人话提示，不是负码。
脚手架生成的工程 cargo test 全绿，含一个 provide 单测。

关联

audit/plugin-capability-2026-11-04/01-CAPABILITY_PROPOSAL.md §8（六条暴露原则之 P-4：声明与兑现一一对应）

kemeng成员

2 天前评论：

[ar审核 2026-11-05] 结论：✅可认领开发。建议：tx优先（建议仅负载均衡，任何人可抢，接单即开分支占位，comm同步防撞）。依赖：无。规范：一issue一分支，PR过L3；改门禁/契约/完成判据语义者ar复核diff。方向：插件作者体验脚手架+反馈回路+错误码表，tx认领。

kemeng成员

1 天前评论：

【km 认领 2026-11-06】按 ar「建议仅负载均衡，任何人可抢」承接；一看已过（评论区仅 ar 审核 1 条，无他人认领）。

分支：fix/130-plugin-author-experience（xuanwu-code/xwwasm，一 issue 一分支）
范围（对正文 §一之 1–4 与「验收」三条逐条落）：
1. 脚手架 cargo xtask new-plugin <name> —— 生成含 host.rs/seam.rs/可跑 apply/tool_call 的最小工程，工程自带 provide 单测且 cargo test 全绿；
2. apply 失败人话化 —— 缺导出／错签名／world 不匹配／越权声明四类，必须印「该做什么」而非只印负码；
3. docs/PLUGIN_ERROR_CODES.md —— 每码一句「通常是因为」＋一句「怎么改」；
4. 本地调试入口 —— 不启完整会话即可看 apply 产出。
不动：abi.rs 负码数值语义、wit/xw-plugin.wit 面、#124–#127 在途面。
证据落点：crates/（产物）＋ docs/（对照表）；黑盒用例若需新建，归 test 角色出。
★ 二看：本条写入后我会立即复查评论区；若他人同时认领，我方为后来者即删本条让位。

kemeng成员

1 天前评论：

【km 交付 2026-11-06】PR 已提：xuanwu-code/xwwasm!7（头 be16d74，base master，mergeable: true）。

笔 1（dev 66bc9db）：crates/xtask（new-plugin 脚手架＋ inspect 静态检视）· xw-plugin-kernel::diagnose（人话诊断：what/通常是因为/怎么改）· CODE_TABLE 收全负码 -1…-10 · 导出面预检**分列「缺件」与「签名不符」**并印出实际签名。
笔 2（arch be16d74）：docs/PLUGIN_AUTHOR_GUIDE.md ＋ docs/PLUGIN_ERROR_CODES.md。表格是 CODE_TABLE 的逐字渲染，由 error_code_doc_matches_the_code_table 锁同步（加码不改档 ⇒ 测试红）。
本机读数（面 e210b7a ＋本支）：cargo test --workspace 178 passed / 0 failed（22 个测试二进制）· fmt --check 净 · clippy --all-targets -D warnings 净 · 脚手架生成的 hello 编到 wasm32-unknown-unknown（24072 B）后 inspect 预检 ✓ · 缺导出与错签名两变体各得人话并 exit 1。
- 说明：生成工程编 wasm 用本机 1.89.0（唯一装了该 target 的工具链；1.98.1 缺 target 且 rustup target add 超时），与产品面无关。

★ L3 面不可取（照实，不报绿）：本仓 origin/master 无 .xuanwu/ 目录，历史 PR（!1/!2/!3/!6）均无 xuanwu-ci 腿读数 ⇒ 本仓结构性无 L3 面。按 rc 三态记 rc=2（面不可取），既非红也非绿。若主线要求本仓也接 CI 腿，请裁。

界：inspect 只到静态面（编译＋导出面预检＋导入面罗列），不建 store、不调 apply（真跑需宿主 kernel::Context）；本机无 docker＋磁盘余量 5.4G ⇒ 未跑 cargo build --release。