84 lines
3.4 KiB
Markdown
84 lines
3.4 KiB
Markdown
# ZCode 自研插件工作区
|
|
|
|
自研 ZCode 插件的源码在这里改,`~/.zcode/plugins/` 是**运行时读的安装副本**。
|
|
两份并存意味着一个陷阱:改了源码没重装,跑的还是旧代码 —— 而报错会指向你刚改好的
|
|
那个文件,排查全跑偏。这个工作区用 `deploy.mjs` + `audit-plugins.mjs` 把这件事钉死。
|
|
|
|
## 目录
|
|
|
|
```text
|
|
zcode/
|
|
deploy.mjs 源码 → ~/.zcode/plugins,备份 + 测试 + 审计
|
|
audit-plugins.mjs 源码 vs 安装副本 漂移检测 + 文档/语法检查
|
|
tests/tools.test.mjs 上面两个工具自己的测试(含"能不能真发现漂移")
|
|
package.json 一键入口
|
|
zcode-env-sync/ 插件:团队环境同步(导出/导入/校验/清理/诊断)
|
|
zcode-thinking-mode/ 插件:思考档位切换(查看/切换/默认值/自检)
|
|
```
|
|
|
|
## 常用命令
|
|
|
|
```bash
|
|
npm run deploy:dry # 预演:会改哪些文件,不落盘
|
|
npm run deploy # 备份 → 同步 → 跑测试 → 审计
|
|
npm run audit # 只看源码与安装副本是否一致
|
|
npm run audit:drift # 只要漂移结论,跳过文档/语法检查
|
|
npm run test:all # 三个项目全测(工具 24 + env-sync 63 + thinking 28)
|
|
```
|
|
|
|
只想部署一个插件:
|
|
|
|
```bash
|
|
node deploy.mjs zcode-thinking-mode
|
|
node deploy.mjs zcode-thinking-mode --no-test # 只同步
|
|
node deploy.mjs --no-deploy # 只测+审计,不动文件
|
|
```
|
|
|
|
## 漂移检测
|
|
|
|
```bash
|
|
$ npm run audit
|
|
### zcode-env-sync v0.3.0
|
|
✗ 副本与源码有差异:
|
|
内容不同:scripts/export.mjs
|
|
→ 重装:cp -r ".../zcode-env-sync/." ".../zcode/plugins/zcode-env-sync/"
|
|
```
|
|
|
|
判定口径:
|
|
|
|
| 情况 | 判定 |
|
|
|---|---|
|
|
| 源码有、副本没有(新增文件没部署) | ✗ 失败 |
|
|
| 两边都有但内容不同 | ✗ 失败 |
|
|
| 版本号不一致 | ✗ 失败 |
|
|
| **源码已删、副本还在**(`scripts/` `commands/` 等源码管理位置) | ✗ 失败 —— 幽灵代码仍会被加载 |
|
|
| 根目录 / 自定义子目录的本机文件(`local-state.json` 等) | ⚠ 只提示 —— 这是有意的本地产物 |
|
|
| 命令文档缺 `description` / 引用脚本不存在 / 脚本语法错 | ✗ 失败 |
|
|
|
|
**残留判定只认源码管理的位置**(`scripts/`、`commands/`、`.zcode-plugin/`,以及根目录的 `.md`
|
|
与 `package.json`)。不按扩展名一刀切 —— 否则根目录的 `local-state.json` 会被报成
|
|
"残留代码建议删除",把一个只读审计工具变成删数据的推手。
|
|
|
|
## 为什么 deploy 只增改不删
|
|
|
|
副本里可能有你有意放的本机文件(`local-state.json`、本机专用配置)。
|
|
整目录替换会把它们一起抹掉,所以 deploy 逐文件写,只在有差异时动对应文件。
|
|
|
|
源码删掉的文件会留成**幽灵代码**继续被加载 —— deploy 会检测出来并打印 `rm` 命令,
|
|
但**不自动删**:删除不可逆,备份虽有,但"删了才发现还想留"的代价比多敲一行高。
|
|
|
|
## 部署后生效
|
|
|
|
插件、命令、hooks 都在启动时读取,**重启 ZCode 生效**。
|
|
当前会话里想立刻验证,直接跑脚本本体:
|
|
|
|
```bash
|
|
node ~/.zcode/plugins/zcode-thinking-mode/scripts/thinking.mjs doctor
|
|
node ~/.zcode/plugins/zcode-env-sync/scripts/doctor.mjs
|
|
```
|
|
|
|
## 每个插件的文档
|
|
|
|
- [zcode-env-sync/README.md](zcode-env-sync/README.md) —— 快照结构、路径占位符、密钥束、七条命令
|
|
- [zcode-thinking-mode/README.md](zcode-thinking-mode/README.md) —— 双写原理、默认值文件、自检
|