# jin-agent

**Repository Path**: aviptle/jin-agent

## Basic Information

- **Project Name**: jin-agent
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-11-11
- **Last Updated**: 2026-11-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# jin-agent · 优化版 DSH 工作台

基于 DSH（DeepSeek Harness）**V0.2.2-rc.1** 引擎的多场景个人 AI 工作台重构版。
前身与评审结论见 `D:\git\github\luanyujia-workbench\`（淋雨家的工作台）——
本仓按评审结论重建：7 个架构级问题逐条修，41 个面板（38 个旧面板全量移植 + DSH 原始界面 + 会话管理 + Reflexion 控制台）。

> 实施进度：[构建清单.md](构建清单.md)（断点续作主清单，机读镜像 [进度.json](进度.json)）。
> **40 步全部完成**（S21 守护节奏器为可选项，见清单）。
> **新会话/新电脑接手**：先读 [docs/开发交接.md](docs/开发交接.md)（现状快照 + 工作流规约 + 踩坑速查）。

## 快速开始

1. 装 Node.js ≥ 24.9（本机 26.13 实测可用）
2. 引擎已就位：`引擎\apps\cli\lib\bin.js`（0.2.2-rc.1 从源码构建；`引擎\` 不入库，换机按[换机清单](docs/换机清单.md)重建）
3. `cd 外壳 && npm install`
4. 双击 项目根的 启动.vbs（或 `cd 外壳 && npm start`）
5. 建会话：`node 外壳/scripts/会话链路.mjs create --scene command`（先写交接文件，跑 create 前保证外壳已启动过一次——token 从 `引擎数据\server.log` 换）
6. 配模型密钥：切到「设置」页签 → 填 DeepSeek API Key（或点「从 DSH 桌面版导入」）→ 保存即热生效（引擎无连通性校验）

## 它修复了旧版哪些架构问题

| 旧版问题 | 本仓修法 |
|---|---|
| 机制靠模型自觉，运行时不拦截 | 记忆唯一写入器（红线/主权/撞车/跨进程锁四道前置闸）+ fs.watch 闸门兜底（`记忆/`） |
| 引擎契约散落各处，升级即断 | **引擎适配层**（`引擎适配/`）：13 个契约点登记制，每条带 verifiedOn 版本记录；`适配体检.mjs` 离线 12/13 验证 + 在线探针 4/4；升级演练已验（伪造 0.3.0 → 13 项全报未验证 exit 10） |
| 18768 行巨石渲染器 | 一面板一文件（`renderer/panels/panel.<type>.js`）+ 注册表 + 逐面板热更（harness 面板热更时保住 AI 会话） |
| 发布链路开箱即坏 | 端口/路径全配置化（`config/workbench.config.json`）+ `scripts/冒烟.mjs` 发布闸门（全绿 exit 0，含面板标签/拆窗/联动防回归）+ `scripts/文档体检.mjs`（文档与实物对数） |
| 单机单宿主假设 | 盘符白名单可配、路径相对项目根（sys:resolve）、无计划任务依赖（S21 守护节奏器） |
| 安全面空白 | webai 桥 token 鉴权（每启动轮换）+ 网页内容 `__untrusted` 隔离标记 + sys:exec 三层白名单（基名闸/无 shell 优先/防注入字符闸）+ 拒绝留痕（data/安全日志.jsonl）+ file/du 全过盘符白名单 |
| grep 检索 | front-matter 结构化索引（`记忆/索引.mjs` + `查记忆.mjs --tag/--scene/--text`，过期检测） |

## 面板（41 个渲染器文件，11 个场景）

- **预览族**：view（文本/图片/音视频/PDF/目录）/ combo / review-doc / review-files
- **文件族**：file（本地双栏）/ site-folder / bl-folder
- **网页族**：embed（真实网页嵌入，一板一分区）/ web / site-preview / site-urls / code-urls / site-media / site-about / site-projects / wb-cards
- **命令台族**：dash（演示）/ shell（白名单执行）/ log / ctl（一键操作：exec 动作联动终端回显命令+输出，无终端面板时内联显示）
- **本机族**：pc-drives（真实磁盘 statfs）/ pc-toplarge / pc-junk / pc-ledger / neuron（记忆神经元，读身份索引+共享记忆）
- **外挂族**：zcode / opencode（编码台双壳共核 panel._core：调各 CLI 无交互写代码——任务输入/流式回显/可停止，模型配置全走各 CLI 原生，工作区 引擎外挂/<id>）
- **行情族**：market / chart（K线/MACD/筹码）/ board / screen / radar —— 🟡 演示数据（确定性种子，接真实行情服务的接口已留）
- **AI 会话**：harness（引擎页入面板 + 写会话键钉住 + 状态机防循环 reload；S38 起每次加载注入隐藏左侧栏 CSS——纯净会话视图，无会话列表/用户信息侧栏）
- **DSH 原始界面**：dsh（引擎原生 Web UI 全量展示，不钉会话；独立分区 + 外链走系统浏览器，见下节）
- **会话管理**：projects-mgr（跨项目/跨会话管理——建会话、fork 继承、归档、下发任务、自动转发规则）
- **Reflexion 控制台**：reflexion（Actor 执行 → Evaluator 打分 → Self-Reflexion 反思 → 三层记忆，见下节）
- **设置**：settings（模型密钥：provider 列表/保存/清除 + 从 DSH 桌面版导入）+ plugins（组件插件管理卡，见下节）

## 组件插件化（S25–S27：场景即插件，热加载不重启）

- **场景即插件**：除「设置」外的 10 个组件（B站/命令/行情/命令台/本地电脑/自我复盘/代码/OpenCode/DSH/项目）个个可开关——往 `外壳/scenarios/` 丢一份场景 json 即自动上架（缺省启用）
- **开关**：设置页签「组件（插件）」卡，逐个启用/停用，**即时热生效不重启**；状态真源 `外壳/data/插件.json`（原子写，缺省=全启用）
- **热加载**：停用 = 标签移除 + 该插件独占面板从注册表卸载（启用插件的共享面板如 harness/embed 不动）；启用 = 面板文件动态补载 + 标签恢复；AI 会话数据只保留不删除，重新启用自动重绑
- **固定组件**：`settings` 不可关（开关的载体不许自关），面板上显式标「固定」
- **公共面板**：未被任何场景引用的 panel 文件（reserved/flow/view 等）永远加载——机制层与冒烟探针不受插件开关影响

## 场景内自由画布 + 场景级独立窗口（S34）

- **场景内自由画布**：场景内所有面板组合在一个画布上（绝对定位，百分比坐标），所有面板同屏可见；初始坐标由场景 JSON col/row/w/h 映射。
- **拖动/缩放/持久化**：拖面板标题/徽标区域移动，**8 向手柄**（四边+四角，S39）自由缩放；DSH 等无 head 面板用左上角 `⠿` 握把；位置/大小/层叠落 `外壳/data/scene-layout.json`（原子写），重启恢复。
- **一键还原布局（S39）**：画布右上角「⟲ 还原布局」清除该场景已存布局并回到 JSON 初始大小/位置（主窗与拆出窗口通用）。
- **场景级拆出**：hover 场景标签显示 `⧉`（右键同效）——整个场景拆成独立 BrowserWindow（主窗占位，solo 窗口 `?solo=1&scene=<id>`）；关闭独立窗自动收回；再次拆同一场景只会聚焦已有窗口。
- **画布/窗口联动**：solo 窗口加载同一套 `index.html` + `canvas.js`（`?solo=1`）；布局编辑双端同步（同一 `scene-layout.json`）；solo 窗口不加载 webai 桥（避免重复隐藏 guest）。
- **生命周期**：主窗关闭 → 场景窗口一并关闭；退出时保留拆出布局快照（`外壳/data/detached-scenes.json`），下次启动按 bounds 恢复并剔除失效条目；插件停用 → 对应场景窗口关闭。
- **S32 面板标签/面板级拆出已由 S34 替代**（面板不再单独拆出；跨窗口事件总线移除）。

## DSH 原始界面（S33）

- **入口**：顶部新增「DSH」场景，场景内一个「DSH 原始界面」面板；加载工作台引擎 `dsh web` 的完整 Web UI，保留原生侧栏/顶栏/详情列，不做聊天精简或宽度铺满注入。
- **不钉会话**：不写 `dsh.sessions.current`、不 reload，用户在引擎侧栏自己选会话；独立分区 `persist:dsh-original-<面板id>`，与 `harness-panel-*` / `embed-*` 隔离。
- **可靠性**：引擎未就绪时显示状态并 5s 重试；加载失败/引擎重启时经 `engine:freshUrl` 从 `server.log` 最后一条 `dsh web:` 行取最新 token 重载；外链 `http(s)/mailto` 走系统浏览器（主进程只接管 `dsh-original-*` guest）。
- **S34 联动**：该面板在场景画布上为单面板（默认 100%×100%），DSH 场景可整场景拆出独立窗口。
- **顺带修**：`harness` / `dsh` 的 `<webview>` 从 `display:block` 改为 `display:flex`——Electron guest 高度此前会停在默认 150px（元素看着满高、guest 只渲染顶部一条）；冒烟新增 guest 高度断言防回归。
- **边界**：展示的是工作台引擎（`引擎数据` 的 DSH_HOME）的 DSH Web UI，不是已安装桌面版 `~/.dsh` 的数据/桌面 profile；桌面版 `dsh-app://` + 随机端口界面无法作为普通 webview 嵌入。

## 会话管理（S35：projects-mgr 面板）

- **入口**：顶部新增「项目」场景；场景内两个面板——左侧会话管理面板（`projects-mgr`），右侧 AI·项目（harness，绑定 `session-aae004d7-…`）。
- **跨项目会话管理**：读取 DSH `workspace.json` 展示项目列表，`session/list` 列出所有会话（标题从 projcache 补全）；按项目分组展示，支持选中。
- **新建会话**：选定项目（workspace）后通过 `session/create` 创建，自动 rename 到用户输入标题。
- **Fork 继承**：选中一个已有会话后点 Fork，通过 `session/fork` 创建分支（新会话继承完整对话历史）并 rename。
- **归档**：rename 为 `已归档·<日期>` + `workspace/archiveSession`，不在侧栏显示。
- **下发任务**：选中会话后输入文本，通过 `session/prompt` 发到 DSH 引擎；结果在 DSH 的 harness 页面里查看。
- **自动转发规则**：创建规则 `{源会话, 关键词, 目标会话}`；主进程每 30s 检查源会话状态，关键词匹配则通过 `session/prompt` 注入目标会话。
- **面板会话绑定**：列出所有场景的 harness 面板及绑定状态（已绑/未绑）；选中一个 DSH 会话绑定到指定面板（回写场景 JSON）；也可新建会话并绑定、或解绑。绑定由会话管理场景独占控制，harness 面板在场景渲染时按绑定的 sessionId 自动钉住。
- **顺带修（S36）**：`session/list` 的 RPC 形参是 `_request` 不是 `request`（typert 网关按控制器 TS 参数名生成描述符）——S35 的项目/会话列表因此加载失败，已修并登记契约点 `rpc.session.list`（连带登记 `rpc.session.wait`/`rpc.session.events`）。
- **S37 全交互修复**（用户实测「功能没有作用」，冒烟真实点击端到端把关）：① Electron 渲染层**不支持 `window.prompt()`**（调用即抛错）——新建/Fork/规则/绑定的 7 处弹窗全是死按钮，改为面板内模态（列表选择/文本输入/确认框）；② `session/list` 条目**不带 workspaceId**——归属从 workspace.json 补全，项目分组/计数才真正生效；③ projcache 标题真身是 `record.rows.title.val`（原读 `tables` 永远为空，树里全是 sessionId）；④ 已归档会话从树中过滤（归档=不在侧栏显示）；⑤ 删除转发规则同步本地缓存（原只删盘，行不消失）；⑥ Fork 源限定当前项目，空会话（无完成轮次）不可 fork 如实提示。

## Reflexion 框架（S36：reflexion 面板）

- **入口**：「项目」场景第三块画布面板（Reflexion，通栏第二行）；框架完全长在 DSH 项目会话上。
- **角色**：**Actor** = 项目里选定的 DSH 会话（同项目可多个并行，一会话同时一个 run）；**Evaluator** = 每项目自动创建的专用会话 `Reflexion·Evaluator·<项目>`，主进程用两套 prompt 模板驱动它分饰两角——打分（严格 JSON `{"success","score":0-10,"issues","summary"}`，即 RL reward）与 Self-Reflexion（错误诊断/根因/下一轮策略 + 长期记忆候选）。
- **循环**：任务注入记忆下发给 Actor（`session/prompt`）→ `session/wait` 30s 一拍等执行完（`afterSeq` 游标只收本轮 assistant 消息；`input-required` 持续等人在 DSH 页作答；30min 超时 `session/cancel` 按部分结果评估）→ Evaluator 打分 → Self-Reflexion 反思 → 三层记忆落盘 → 成功即停，失败自动下一轮（auto 可关，手动「▶ 下一轮」「⚡ 立即评估」）。
- **三层记忆**：**短期** `<项目根>/.jin-agent/<会话ID>.md`（每轮反思追加，仅该 Actor 会话）；**项目长期** `<项目根>/.jin-agent/AGENTS.md`（经验条目 cap 50 去重淘汰最旧，同项目所有会话共用；DSH 引擎本身会把 AGENTS.md 注入上下文，双通道生效）；**工作台长期** `记忆/引擎记忆/project-memory/<项目>.md`（每个任务跑完的总结归纳）。下一轮任务自动注入 AGENTS.md 经验 + 近 3 条短期反思。
- **状态**：run/trial 全程落 `外壳/data/reflexion-runs.json`（原子写，历史 cap 50）；面板经 `reflexion:changed` 实时刷新（分数/反思/输出展开）；纯逻辑自检 `node 外壳/main/services/reflexion.js --selftest`（25 项）。
- **边界**：Evaluator 复用同一会话串行驱动（afterSeq 游标隔离并发回复）；模型密钥未配置时评估失败会如实记入 trial（score 0 + 原因），不中断 run。

## 主题（主程序控权，S29）

- **单一权威**：主题值在 `config/外观.主题`（当前 `dark`——壳浅色未移植）；主进程接管 `nativeTheme.themeSource` ⇒ 全 app（含各 webview 分区）的 `prefers-color-scheme` 由主程序决定
- **引擎页跟随**：壳启动时经 `settings/describe`+`settings/mutate` 把引擎设置文档 `ui-theme.preference` 幂等断言为 `system`（已在 system 不写；有人在引擎页改过会被收回）——全部 harness 页统一渲染深色，与壳一致
- **状态**：`node 外壳/scripts/冒烟.mjs` 有 2 条防回归断言；只读状态 IPC `theme:status`

## 代码组件（zcode + opencode 外挂，S30/S31）

- **做什么**：「代码」「OpenCode」两个页签——任务写进编码台提交，对应 CLI 在各自工作区（`引擎外挂/zcode` / `引擎外挂/opencode`）无交互执行，stdout/stderr 实时回显，可随时停止（杀进程树）；运行审计落 `<工作区>/数据/运行记录.jsonl`
- **模型配置零存储**：全走各 CLI 原生配置（zcode：`~/.zcode` + login；opencode：`~/.config/opencode` + auth login，`--model` 不传走原生默认），壳不存任何密钥/镜像任何配置
- **执行安全**：spawn argv 数组传参不过 shell（任务文本无注入面）；zcode 权限模式在 `config/外挂`（默认 yolo，CLI 官方默认）、opencode 固定 `--auto`+`--standalone`+显式工作目录（headless 必需 + 私有服务不连守护）；超时 15 分钟；单任务运行，重提交被拒
- **实现**：主进程共享 runner `services/cli-agent.js`（zcode/opencode 各一份 spec）+ 渲染层共享控制台 `panel._core.js`（双薄壳面板）——再加一个外挂 CLI = 一份 spec + 一份薄壳
- **换机**：入口路径在 `config/外挂.*入口`（opencode 默认定位桌面版 ai.opencode.desktop 自带的 opencode-cli.exe），盘符不进代码

## 模型密钥（移植自 deepseek-harness 桌面版欢迎页链路）

- 链路：`settings/describe`（找 `apiKeyEnv`）→ `llm/listConfigurableProviders`（全量 provider）→ `credentials/describe`（检测）→ **`credentials/set {ref,value}`**（唯一写入口，引擎落 `$DSH_HOME/.credentials.yaml`，文件 watcher 热生效）；清除走 `credentials/unset`
- 入口：**「设置」页签**（`settings` 面板）或 CLI：`node 外壳/scripts/凭据.mjs list|set <ref> <value>|unset <ref>|import [--file <yaml>]`
- 「从 DSH 桌面版导入」= 显式读 `%USERPROFILE%\.dsh\.credentials.yaml` 的 refs 写入本仓（不自动、不改桌面版文件）
- 无「测试连通性」：引擎没有该 RPC（桌面版也没有），保存即完成；对话报 `MISSING_CREDENTIAL` 时回设置页看状态

## 会话链路（引擎 RPC 经适配层，0.2.2-rc.1 真机全通）

```
node 外壳/scripts/会话链路.mjs probe                    # token→cookie→RPC 探针
node 外壳/scripts/会话链路.mjs create --scene <场景id>   # 建会话+改名+原子回写场景json
node 外壳/scripts/会话链路.mjs check                    # 对照投影缓存逐面板核对（__未绑定__报待绑定不报错）
node 外壳/scripts/会话链路.mjs rotate --panel <面板id> --handoff <交接文件>   # 交接闸门(2h)→建/改名/真归档→回写→身份索引→check
```

## 引擎升级协议（自检适配）

1. 快照：备份 `引擎\` 与 `引擎数据\`
2. 换引擎：新版本构建/安装进 `引擎\`（判据 `apps\cli\lib\bin.js`）
3. 自检：`node 引擎适配/适配体检.mjs --online`——版本变了会逐项报「本版本未验证」+ 在线探针实测
4. 处置：探针全绿 → 把 `capabilities.json` 对应条目补 `verifiedOn`；有红 → 按[换机清单](docs/换机清单.md)回退

## 目录

```
config/      全局配置真源（端口/路径/白名单/记忆红线）
引擎适配/     adapter.mjs + capabilities.json（13 契约点）+ 适配体检.mjs（--online）
外壳/        Electron 壳（main 按域拆 / preload 最小暴露 / renderer 一面板一文件 / scripts 命令行）
记忆/        写入器.mjs（唯一写入入口）/ 闸门.mjs / 索引.mjs / 查记忆.mjs
模板/        记忆样例（front-matter 格式）
工具/        守护.mjs（S21 可选：单进程节奏器）
docs/        迁移指南 / 换机清单
```

## 许可

MIT