From b21b6d5abd2be749fe33800ae604ced15c071467 Mon Sep 17 00:00:00 2001 From: czcdr Date: Mon, 12 Oct 2026 22:57:35 +0800 Subject: [PATCH] docs: durable project notes (release state, decisions, todos) --- docs/project-notes.md | 78 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 78 insertions(+) create mode 100644 docs/project-notes.md diff --git a/docs/project-notes.md b/docs/project-notes.md new file mode 100644 index 0000000..081aab7 --- /dev/null +++ b/docs/project-notes.md @@ -0,0 +1,78 @@ +# 项目记录 / Project notes + +本文件是本仓库的**持久状态记录**（比会话记忆更长命）：发布状态、维护决策、待办与外部约束。 +新会话或新维护者可先读这里，再读 README 与 CHANGELOG。 + +_最后更新：2026-10-12_ + +## 1. 这是什么 + +上游 **REA（Reverse Engineer Anything，，MIT）** 的第三方 DSH 适配插件。 +本插件**不做逆向分析**：它把 REA 的 MCP 服务器注册进 DeepSeek Harness，得到 `mcp__rea__*` 工具， +并把引擎环境变量限制在该 MCP 子进程内。 + +## 2. 发布状态 + +| 项 | 值 | +|---|---| +| 仓库 | （公开，MIT） | +| 形态 | 纯配置型 Cordis bundle：`package.json` 声明 `dsh.bundle.patch` → `cordis.patch.yml` | +| 工具命名 | `mcp__rea__`（serverName = `rea`，transport = stdio） | +| Release 资产 | 固定名 `dsh-plugin-rea.tgz`（**版本无关**，避免 `latest/download` 烂链） | +| 直装链接 | `https://github.com/czcdr/dsh-plugin-rea/releases/latest/download/dsh-plugin-rea.tgz` | +| 市场条目 | 见 `docs/marketplace-entry.yml` | + +实测矩阵（作者机器，2026-10-12）：REA `6.4.0` / DSH 桌面运行时 `0.2.0-rc.2` / +`@deepseek-ai/dsh-mcp-client` 由 harness 自带（npm latest `0.0.1-rc.1`）/ Ghidra `12.1.4` / +Node `24.21.0` / Windows 11 x64。 + +## 3. 市场收录状态 + +- **topic 型市场**：仓库已带 `dsh-plugin` topic，dsh-feed / dsh-plugin-mall / + DSH-Plugins-Marketplace 等按各自同步周期自动抓取，无需操作。 +- **精选列表 awesome-dsh-plugin**：PR 制，提交 `data/plugins/czcdr__dsh-plugin-rea.yml` 一个文件。 + 其 CI 要求**仓库创建满 1 天**：本仓库建于 `2026-10-12T14:42:26Z`， + 因此 PR 最早在 **`2026-10-13T14:42Z`（北京时间 22:42）** 之后提交才过 CI。 + 投稿内容已提交到 fork `czcdr/awesome-dsh-plugin` 的同名路径，可直接开 PR。 +- **npm**：未发布（本机 npm 未登录）。市场收录不依赖它，仅影响下载量展示。 + +## 4. 更新语义（易混淆，务必区分） + +| 对象 | 更新方式 | +|---|---| +| **本插件** | **不会自动更新**。从插件市场安装的 → 在**市场里更新**；本地 `file:` 目录安装的 → 覆盖目录后重装。 | +| **上游 REA** | `npm i -g rea-agents@latest`。其 `bin` 入口 `scripts/rea.mjs` 跨版本稳定，插件无需改动。 | +| **Ghidra** | 受 REA 版本门槛限制（当前 12.1.x）：先升 REA，确认它接受新版 Ghidra 再升。升级需改两处：用户环境变量 `GHIDRA_INSTALL_DIR` 与 `cordis.patch.yml` 的 `env.GHIDRA_INSTALL_DIR`。 | +| **DeepSeek Harness** | 升级可能改变 MCP 客户端配置结构；用 `Config.listConfigs name=@deepseek-ai/dsh-mcp-client` 看该行 schema 后调整字段名。 | + +`check-updates.ps1` 一次跑完上述四项检查（只读）。 + +## 5. 维护决策记录 + +- **为什么不做成"完整逆向源码"的承诺**：上游自己的工具契约写明——原生分析返回**伪代码与汇编**， + 不是原始源码，且"pseudocode is Ghidra decompiler output, not original source and not + text-equivalent to Hopper output"；APK 返回反编译的方法；JEB 返回伪代码。 + 因此 README 增设「能做什么、不能做什么」，明确**无法完整还原源代码**。市场审核会逐条核对 + 描述与代码，夸大描述是主要打回原因，这条也降低了被误读的风险。 +- **为什么用 `!!js` 之外的写法（字面路径）**：配置型 bundle 的 `command`/`args` 由 MCP 客户端 + 直接 spawn，相对路径不可靠；`command: node` 走 PATH，只留 `args[0]` 与 `GHIDRA_INSTALL_DIR` + 两处随机器不同，README 已列明改法。 +- **为什么 Release 资产名不带版本号**：市场的 `latest/download/` 会按字面取文件名， + 带版本号的文件名会在下次发版时静默 404（市场文档明确警告过）。 +- **为什么不写上游 `rea update`**：那是 REA 自身的更新命令，与本 DSH 插件无关， + 容易让用户以为插件会自动更新；已从 README 与脚本中移除。 + +## 6. 环境约束（作者机器，2026-10-12） + +- `github.com` 的 **git 传输被墙**（Connection reset），`git clone/push` 不可用； + 仓库操作全部走 `gh` CLI / `api.github.com`（建仓、上传文件、topics、description、Release 均可）。 +- `raw.githubusercontent.com` 经 `web_fetch` 失败，经 PowerShell 可访问。 +- npm 官方源与 npmmirror 均可用；npm 未登录。 +- 记忆服务（Hindsight）未配置 token，写入返回 401 —— 本文件即为该状态下的本地持久化替代。 + +## 7. 待办 + +- [ ] 仓库满 1 天后提交 awesome-dsh-plugin 的 PR（fork 内容已就绪）。 +- [ ] 可选：仓库内加 `screenshots.json`（1-8 张 GitHub 托管图片）供市场详情页展示。 +- [ ] 可选：`npm publish`（需先登录；包名 `dsh-plugin-rea` 可用；`repository` 字段已指回仓库）。 +- [ ] 上游 REA 有新版本后：跑 `check-updates.ps1`，并同步 README 的验证矩阵与本文档。