# mcore机器核心 插件开发文档

> 仓库：`muvuula/DeepSeek-Harness-Core` ｜ 插件名：`mcore` ｜ 运行时：`~/.dsh/profiles/web/node_modules/mcore/`
> 品牌规范见 `docs/BRAND.md`（改 UI 前必读）

---

## 一、目录结构

```
mcore/  # 本地工作区（clone 到哪都行，例：~/work/mcore）
├── logo/                    # 品牌 LOGO 素材（豆包生成候选图）
├── dsh/                     # 插件核心源码（修改主战场）
│   ├── index.mjs            # 主模块：API 路由 / 面板 HTML / 记忆 / 进化逻辑（8800+ 行）
│   ├── stock.mjs            # 股票/行情相关模块
│   ├── brain.mjs            # 大脑（知识图谱）
│   ├── chrono.mjs           # 时间轴
│   ├── cache.mjs            # 缓存
│   ├── broker-everbright.mjs
│   ├── freewill.mjs         # 自由意志
│   ├── selection-model.mjs  # 选择模型
│   ├── trading-model.mjs    # 交易模型
│   ├── vision.mjs           # 视觉
│   ├── client-dhc.mjs       # 客户端源码（esbuild 源）
│   ├── client-entry.mjs     # 客户端入口（只含 dhcClient）
│   ├── client.js            # 构建产物（esbuild + 包壳，harness 实际加载）
├── docs/                    # 文档
│   ├── BRAND.md             # 品牌设计方案（权威）
│   ├── DEVELOPMENT.md       # 本文档
│   ├── integration/         # 五器官集成文档（modlens/at-file/genui/automation/sidebar）
│   ├── screenshots/         # 截图
│   └── poster-copy.md       # 宣传文案（0.46 时代，已归档待更新）
├── archive/                 # 归档（不删，可回溯）
├── build-client.mjs         # client.js 构建脚本
├── release-check.mjs        # 发布检查
├── CHANGELOG.md             # 版本日志
├── persona-core.template.json  # 人格模板
└── package.json
```

## 二、开发环境

| 项 | 值 |
|---|---|
| dev 源码（git） | 你的 clone 目录，例：`~/work/DeepSeek-Harness-Core` |
| 运行时副本 | `~/.dsh/profiles/web/node_modules/mcore/`（⛔ 位置永不改动，开发只 cp 同步内容过去） |
| 状态文件 | `~/.dsh/persona-core.json`（workspaceRoot 统一在此） |
| 服务端口 | `http://127.0.0.1:3080` |
| 面板 API | `GET /api/dhc/panel`（完整 HTML）· `GET /api/dhc/state`（JSON 状态） |
| 启动方式 | 桌面「DeepSeek Harness」按钮 / `node <dsh-cli>/lib/bin.js web` |

**⚠️ 路径铁律**：Windows 上 node 只认 `C:/...` 风格路径，MSYS 的 `/c/...` 会 `MODULE_NOT_FOUND`（实测踩坑）。

## 三、改造纪律（⛔ 最高优先级，2026-08-21 主人批评"不崩乱改"后立）

1. **绝不动 `persona-core.json` 的 identity**（persona/speaking/interests/gender）——那是使用者的人格设定，程序不该自作主张覆盖。改任何配置前先备份（`~/.dsh/backups/`），使用者点名要改才动。
2. **小步验证**：每改一处 → `node --check` → 同步 → 重启 → API 验证。禁止一次大改（曾一次大改留下两处孤立 `}` 导致面板 JS 崩溃）。
3. **不发布"顺手"版本**：要的功能做完、验证通过再 bump 版本；改动大时先本地跑稳再发布。
4. 改动前把删除前文件备份到 `~/.dsh/backups/`（可回滚）。

## 四、标准工作流（每次改代码）

```bash
# 1. 改 dev 源码 dsh/index.mjs（或 stock.mjs / client-dhc.mjs / client-entry.mjs）
# 2. 语法检查
node --check dsh/index.mjs && node --check dsh/stock.mjs
# 3. 同步到运行时副本（注意：混合 hardlink/副本！见坑1）+ md5 必须一致
cp dsh/index.mjs ~/.dsh/profiles/web/node_modules/mcore/dsh/index.mjs
md5sum dsh/index.mjs ~/.dsh/profiles/web/node_modules/mcore/dsh/index.mjs
# 4. 重启（杀 3080 + 拉起，本机无 dsh-restart-now.ps1，用：）
powershell -NoProfile -Command "Get-NetTCPConnection -LocalPort 3080 -State Listen -ErrorAction SilentlyContinue | ForEach-Object { Stop-Process -Id \$_.OwningProcess -Force }"
cd ~/.dsh && node "<dsh-cli>/lib/bin.js" web   # 后台跑（Windows 上 <dsh-cli> 用 C:/... 风格）
# 5. 等端口 + 验证
for i in $(seq 1 45); do netstat -ano 2>/dev/null | grep -q ":3080.*LISTENING" && break; sleep 2; done
curl -s http://127.0.0.1:3080/api/dhc/state
curl -s http://127.0.0.1:3080/api/dhc/panel | grep -o "你要验证的元素" | sort | uniq -c
```

## 五、关键坑（全部实测踩过）

1. **profile 副本 = hardlink 与副本混合**：`client.js`/`client-entry.mjs` 是 hardlink（改 dev 自动同步）；`index.mjs`/`stock.mjs`/`client-dhc.mjs`/`package.json` 是独立副本（必须 cp 同步 + md5 验证，否则改不生效——曾连续 3 次重启"没反应"）。
2. **client.js 重建必须 esbuild + 包壳**：改 client-dhc.mjs 后要重建：esbuild alias/路径必须 Windows 格式 `C:/...`（MSYS `/c/...` 会 `Could not resolve`）；包壳 `node build-client.mjs`（读 client.raw.js → 包 `__ModuleLoader__.load` → client.js）。
3. **模板字符串内的 JS 不受 `node --check` 检查**：面板 HTML 模板（`panelPageHtml`/`stockPageHtml`）里的 `<script>` 段，语法错误只在运行时崩。删除代码块后必须做**括号平衡校验**（提取模板 `<script>` 段、剥 `${...}`、数 `{}` 深度必须 0）和 **div 平衡校验**（`<div` vs `</div>` 必须 0）。曾因删代码留下孤立 `}` 导致 refresh() 崩溃、面板数据全空。
4. **删行整行匹配会误伤同行的其他键**：用 kill_line 前先确认行内没有别的要保留的内容（曾连带删掉同行的 `upCard`/`upAuto` i18n 键 → 面板标题变「upCardupAuto」）。
5. **五器官必须独立插件模式（v0.49.0 起）**：mcore 不再内联/嵌套挂载 modlens/at-file/genui/automation/sidebar。若把器官包加进 profile deps，`dsh web` 启动会 reconcile 进 bundles——此时 mcore 若还内联器官 client → `duplicate factory registration`，harness 页面打不开。
6. **workspaceRoot 分裂**：优先级 = `DSHCORE_WORKSPACE > DSH_HOME > 插件配置 > ~/.dsh 探测 > 沙箱工作区 > cwd`。任何启动方式都必须统一到同一个 DSH home（通常是 `~/.dsh`）。验证：`state.diag.workspaceRoot` 应等于该目录。
7. **node 路径必须 Windows 格式**：`node "C:/Users/<name>/..."`，`/c/Users/<name>/...` 直接 MODULE_NOT_FOUND。
8. **重启脚本已不存在**：重装后 `~/.dsh` 只有 `dsh-start.bat`/`dsh-start.vbs`（桌面启动器），无 ps1。手动重启用第四节命令。

## 六、面板 UI 开发要点

- 面板 = 插件后端动态输出完整 HTML（`/api/dhc/panel`），非 iframe。改 HTML 在 `index.mjs` 的 `panelPageHtml` 模板字符串里。
- **中英双语**：i18n 键在 `P_I18N.zh` / `P_I18N.en` 两块，新增文案必须双语成对加（漏一个 → 另一语言显示键名）。
- **图标零依赖**：图片资源用 data URI 内嵌（`data:image/png;base64,...`），不依赖 harness 静态文件服务。缩放建议：favicon 128px、面板 logo 64px，base64 后约 12KB/4KB。
- 品牌色：主色深空蓝 `#102040`、点缀拟合青 `#22D0C0`（见 BRAND.md）。当前面板暗色底 `#0a0c14` 系旧色，可逐步对齐品牌色。

## 七、版本发布

```bash
# 1. 更新 package.json version
# 2. CHANGELOG.md 记录
# 3. node release-check.mjs
# 4. git add/commit/push（tag: vX.Y.Z）
# 5. 发布 GitHub release
# 6. 用户侧：dsh plugin --profile web add mcore@X.Y.Z
```

版本节奏：小补丁 patch、常规 minor、大改动 major（面板显示升级风险等级：重大/常规/小补丁）。

## 八、品牌落地清单（当前进度见 docs/BRAND.md 末尾）

- [x] 面板顶部 logo + favicon（2026-08-22）
- [x] 面板「🌐 这个网站」按钮 → mcore.fit
- [x] README 品牌更新 + BRAND.md/DEVELOPMENT.md 入库
- [ ] 桌面图标 dsh.ico 按新 LOGO 重绘
- [ ] CLI 启动 banner 字符画 logo
- [ ] 六边形 LOGO 矢量图（GitHub 头像/favicon 高清版）