Skip to content
Back to search

narwhal-forum

Narwhal CMS 论坛能力包:MCP server + CLI(dsh / Claude Code / Codex 共用同一套能力)

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/sasazhang2333--narwhal-forum/badge.svg)](/listings/sasazhang2333--narwhal-forum)

HTML

<a href="/listings/sasazhang2333--narwhal-forum"><img src="/api/listings/sasazhang2333--narwhal-forum/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

# 用户级安装(不需要 sudo;~/.local/bin 通常已在 PATH 里)
npm i -g --prefix ~/.local /path/to/narwhal-forum

# 从 npm(发布后)
npm i -g --prefix ~/.local narwhal-forum

# 或者完全不装,直接跑本地包目录
npx --package "$PWD" narwhal-forum --help

⚠️ **本机已知问题**:默认 npm 缓存目录归属异常会让 `npm` 命令失败 (`npm error sudo chown -R 501:20 ~/.npm`)。先换一个可写缓存再装:

export npm_config_cache="$TMPDIR/npmcache"
npm i -g --prefix ~/.local .

`npx` 也能直接解析本地包目录 / tarball:

npx -y narwhal-forum --help                                  # 已发布到 npm
npx --package /path/to/narwhal-forum narwhal-forum --help    # 本地目录
npx --package ./narwhal-forum-0.1.0.tgz narwhal-forum --help # 本地 tarball

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 672 lines
  1. # narwhal-forum
  2. Narwhal CMS 论坛(BBS)能力包:**一个零运行时依赖的 Node 包,同时是 MCP server、CLI 和 dsh 插件**。
  3. 让 dsh、Claude Code、Codex 以及任何支持 MCP 的工具,都能读帖子、看评论、发评论、发帖、搜索、互动。
  4. - MCP stdio server:`narwhal-forum mcp` —— dsh / Claude Code / Codex 共用的唯一能力面
  5. - CLI:`narwhal-forum posts` / `narwhal-forum new-comment 42 --content 你好` —— 给人或脚本用
  6. - dsh 插件:包内 `cordis.patch.yml` 把上面这个 MCP server 接进 `@deepseek-ai/dsh-mcp-client`
  7. > 默认后端 `http://127.0.0.1:8080`;认证用 token(登录后自动保存到本地凭据文件)。
  8. > 本包只调用论坛已有的 HTTP API,不修改、不依赖 narwhal-cms 的任何内部代码。
  9. ---
  10. ## 1. 安装
  11. ```bash
  12. # 用户级安装(不需要 sudo;~/.local/bin 通常已在 PATH 里)
  13. npm i -g --prefix ~/.local /path/to/narwhal-forum
  14. # 从 npm(发布后)
  15. npm i -g --prefix ~/.local narwhal-forum
  16. # 或者完全不装,直接跑本地包目录
  17. npx --package "$PWD" narwhal-forum --help
  18. ```
  19. ⚠️ **本机已知问题**:默认 npm 缓存目录归属异常会让 `npm` 命令失败
  20. (`npm error sudo chown -R 501:20 ~/.npm`)。先换一个可写缓存再装:
  21. ```bash
  22. export npm_config_cache="$TMPDIR/npmcache"
  23. npm i -g --prefix ~/.local .
  24. ```
  25. `npx` 也能直接解析本地包目录 / tarball:
  26. ```bash
  27. npx -y narwhal-forum --help # 已发布到 npm
  28. npx --package /path/to/narwhal-forum narwhal-forum --help # 本地目录
  29. npx --package ./narwhal-forum-0.1.0.tgz narwhal-forum --help # 本地 tarball
  30. ```
  31. ---
  32. ## 2. 30 秒上手
  33. ```bash
  34. narwhal-forum status # 后端地址、登录状态
  35. narwhal-forum post 42 --comments # 帖子详情 + 评论树
  36. narwhal-forum search 关键词
  37. narwhal-forum setup # 首次:检查后端 + 打开浏览器登录授权(会记住,可撤销)
  38. narwhal-forum auth status # 看当前是否已授权、授权方式、profile 位置
  39. narwhal-forum new-comment 42 --content '写点什么'
  40. narwhal-forum whoami
  41. ```
  42. ---
  43. ## 3. 配置
  44. 优先级:**命令行参数 > 环境变量 > 凭据文件 > 默认值**。
  45. | 环境变量 | 作用 | 默认 |
  46. | --- | --- | --- |
  47. | `NARWHAL_FORUM_BASE_URL` | 后端地址,如 `http://127.0.0.1:8080` | `http://127.0.0.1:8080` |
  48. | `NARWHAL_FORUM_TOKEN` | access token(读写之外的操作需要它) | — |
  49. | `NARWHAL_FORUM_REFRESH_TOKEN` | refresh token(401 时自动续期) | — |
  50. | `NARWHAL_FORUM_USERNAME` | 登录用户名 | — |
  51. | `NARWHAL_FORUM_PASSWORD` | 登录密码(仅登录时使用,**从不落盘**) | — |
  52. | `NARWHAL_FORUM_BROWSER` | 指定浏览器可执行文件(默认自动找 Chrome / Edge / Brave / Chromium) | — |
  53. | `NARWHAL_FORUM_BROWSER_PROFILE` | 浏览器授权专用的 profile 目录 | `<HOME>/browser` |
  54. | `NARWHAL_FORUM_HOME` | 凭据目录 | `~/.config/narwhal-forum` |
  55. | `NARWHAL_FORUM_TIMEOUT_MS` | 单请求超时 | `30000` |
  56. 凭据文件:`~/.config/narwhal-forum/credentials.json`(目录 `0700`、文件 `0600`、原子写)。
  57. 只存 baseUrl / token / refreshToken / username / authMode / loggedInAt / browserProfile,**不存密码**。
  58. 浏览器授权的登录态另存在 `<HOME>/browser/`(独立 Chrome profile),撤销时整个目录一起删掉。
  59. > 密钥类信息一律走环境变量或 `token set`,不要写进仓库、脚本或文档。
  60. ---
  61. ## 4. CLI
  62. 全局选项:`--base-url --token --refresh-token --timeout --json --debug --help --version`
  63. 登录相关:`--password --username --browser <路径> --timeout-sec <秒> --keep-browser`
  64. | 命令 | 说明 | 需要登录 |
  65. | --- | --- | --- |
  66. | `status` | 后端地址、登录状态、凭据来源 | 否 |
  67. | `setup` | 首次接入:检查后端 → 打开浏览器授权 → 打印下一步 | 否 |
  68. | `risk` | 授权前必读的风险提示;每次 `login`/`setup` 也会先打印 | 否 |
  69. | `login` | **网页授权登录**:打开独立浏览器窗口,人工登录后自动取 token(见 4.2) | 否 |
  70. | `login --password` | 退回账号密码登录(RSA+AES 加密传输) | 否 |
  71. | `login --device` | **设备码授权**:打印 URL + 8 位码,人在网页点「允许」后拿 token(远程/容器用,见 4.2.3) | 否 |
  72. | `scope [set …]` | 查看 / 修改授权范围(见 4.2.1) | 否 |
  73. | `logout` | **撤销授权**:后端登出 + 删本地凭据 + 删浏览器 profile | 否 |
  74. | `auth status` | 授权状态(是否登录、授权方式、profile 位置) | 否 |
  75. | `token set` / `show` / `clear` | 直接管理 token(适合从浏览器复制) | 否 |
  76. | `whoami` | 当前登录用户 | 是 |
  77. | `posts` | 帖子列表(`--page --page-size --category --order --title-like`) | 否 |
  78. | `post <id>` | 帖子详情(`--comments` 带评论树,`--comment-sort`) | 否 |
  79. | `comments <postId>` | 评论树 | 否 |
  80. | `categories` / `channels` | 论坛分类 / 站点栏目(CMS channel,非版块) | 否 |
  81. | `search <关键词>` | 全文搜索(后端 Lucene) | 否 |
  82. | `my-comments` | 我发过的评论 | 是 |
  83. | `new-comment <postId> --content <文本|-> [--image 图.png]` | 发表评论 / 回复(`--parent` 指定父评论;`--image` 可重复,见 4.4) | 是 |
  84. | `new-post --category <id> --title <t> --content <文本|@file|-> [--image 图.png]` | 发帖 | 是 |
  85. | `upload-image <图.png> [--scene chat]` | 单独上传一张图,返回可写进 markdown 的 URL | 是 |
  86. | `react <postId> [--emoji 👍]` | 表情互动 | 是 |
  87. | `approve-post <postId>` | 批准待审帖(需审核权限:管理员/版主) | 是 |
  88. | `delete-comment <id> --yes` | 删评论(作者/管理员,**不可撤销**,`--yes` 才执行) | 是 |
  89. | `delete-post <postId> --yes` | 删帖(作者/管理员,**不可撤销**,`--yes` 才执行) | 是 |
  90. | `draft <子命令>` | **人审发布**:`new-comment` `new-post` `list` `show` `approve` `reject` `publish` `discard`(见 4.3) | 视子命令 |
  91. | `mcp` | 以 MCP stdio server 运行 | — |
  92. | `tools [--json]` | 列出全部能力及参数 schema | — |
  93. | `call <tool> --json '<参数 JSON>'` | 直接调用任意能力(逃生舱) | 视工具 |
  94. `--content` 支持三种来源:字符串、`@文件路径`、`-`(stdin)。
  95. `--image` 可重复(`--image a.png --image b.png`),也接受逗号分隔;上限 9 张。
  96. ```bash
  97. echo '从 stdin 来的正文' | narwhal-forum new-comment 42 --content -
  98. narwhal-forum new-post --category 3 --title '标题' --content @draft.md
  99. narwhal-forum call create_comment --json '{"postId":"101589601795420674","content":"hi"}'
  100. narwhal-forum approve-post 101589950310625794
  101. narwhal-forum delete-post 101589950310625794 --yes
  102. ```
  103. 退出码:`0` 成功 / `1` 业务或网络错误 / `2` 用法错误(含人审令牌校验失败)/ `3` 未实名,不能发布。加 `--json` 输出机器可读结果。
  104. ---
  105. ### 4.1 授权前的风险提示(必读)
  106. `login` / `setup` **在打开浏览器之前**会先打印风险提示,并要求你本人确认;非交互环境(CI、被脚本或 Agent 管道调用)没有 `--yes` 一律拒绝授权 —— 不允许「静默授权」。同意会记录版本号,文案升级后会再问一次。
  107. ~~~text
  108. $ narwhal-forum login
  109. 授权前请先阅读风险提示(v2) — 目标:http://127.0.0.1:8080
  110. 1. 内容责任在账号:通过本工具发出的帖子与评论,在论坛上算你这个账号发的,后果由账号所有者承担。
  111. 2. AI 不能自行发布:写操作最终由发起调用的方触发;动手前请确认内容你本人看过。……
  112. 3. 自动化有风控风险:论坛与 B 站会对高频、模板化、批量互动限流、删评甚至封号。……
  113. 4. 只用你自己的权限:不提供管理端接口、不提供「以他人身份」操作……
  114. 5. 未实名不能发布:后端 requireVerifyToPost / requireVerifyToComment;本工具不代做实名。
  115. 6. 凭据留在本机,可随时撤销:token 与 profile 在本机(0600 / 0700),logout 可撤销。
  116. 7. 图片与外链:外链可能失效、图片可能被拦。
  117. 8. 操作留痕:本机记录写操作的时间、目标与结果。
  118. 同意即表示你已阅读并接受以上风险;不同意可随时 Ctrl+C 退出。
  119. 确认已阅读并接受以上风险,输入 yes 继续(其它输入取消)>
  120. ~~~
  121. | 场景 | 行为 |
  122. | --- | --- |
  123. | 交互终端,首次 | 展示全文,必须输入 `yes` |
  124. | 交互终端,已同意过同版本 | 展示全文 + 「已同意过」,回车继续 |
  125. | 非交互,已同意过 | 展示全文,继续(同意是一次性人工行为) |
  126. | 非交互,没同意过 | **拒绝授权**,提示在终端里运行或加 `--yes` |
  127. | `--yes` / `NARWHAL_FORUM_ACCEPT_RISK=1` | 跳过交互(只在你能为发布内容负责时使用),并记录同意 |
  128. MCP 侧同理:`mcp__narwhal-forum__login` 第一次调用**不打开浏览器**,只把风险全文返回给模型,要求它展示给你;只有你确认后带 `acknowledgeRisks: true` 再调用,才会真的打开浏览器。
  129. 随时查看完整文案与同意状态:`narwhal-forum risk`(或 `risk --json`);`auth status` 里也会显示 `riskAcknowledged`。
  130. ---
  131. ### 4.2 授权登录与撤销(推荐)
  132. `narwhal-forum login` 不问你密码,而是**打开一个浏览器窗口**:你在里面照常用论坛的登录页登录,
  133. 插件通过 DevTools 协议只读地取出该页面 `localStorage` 里的 `auth_token` / `auth_refresh_token`,
  134. 写入凭据文件后自动关闭窗口。整个过程密码不经过 CLI、不经过 dsh、不经过模型。
  135. ```text
  136. $ narwhal-forum login
  137. · 浏览器已打开:http://127.0.0.1:8080/login
  138. · 请在该窗口里完成登录,登录成功后会自动继续(最多等 300 秒)
  139. 授权成功(网页登录)
  140. 凭据已写入 ~/.config/narwhal-forum/credentials.json(0600,已含 refresh token)
  141. 浏览器 profile: ~/.config/narwhal-forum/browser(撤销授权时会一并删除)
  142. 撤销方式: narwhal-forum logout
  143. ```
  144. | 要点 | 说明 |
  145. | --- | --- |
  146. | 独立 profile | 浏览器用 `--user-data-dir=<HOME>/browser` 启动,和你日常浏览器互不干扰 |
  147. | 只读令牌 | 只 `Runtime.evaluate` 读那两个 localStorage 键,不读 cookie、不读密码框 |
  148. | 一次即可 | token 写入凭据文件,之后 CLI / MCP / 其它工具都用它;refresh token 自动续期 |
  149. | 可撤销 | `narwhal-forum logout`:调后端登出 → 删凭据 → 删 profile(cookie 一起消失) |
  150. | 可保留 | `logout --keep-browser` 只清 token,保留 profile 里的登录态,下次免登录 |
  151. | 无浏览器时 | `login --password` 走账号密码;或 `token set --access <token>` 手工导入 |
  152. **要求**:Node >= 22(内置 `WebSocket` 用来连浏览器调试端口)。低于这个版本 `login` 会直接提示改用 `--password`。
  153. **关于「安装时自动打开浏览器」**:npm 安装不应该在你背后弹窗,所以打开浏览器这一步放在
  154. `setup` / `login` 上。dsh 里装完插件后,第一次用论坛能力前跑一次 `narwhal-forum setup`;
  155. `mcp__narwhal-forum__login` 工具调用时也会打开浏览器(写操作失败提示「需要登录」时让 Agent 调它)。
  156. ### 4.2.1 授权范围:先决定这个工具能做什么
  157. 网页登录把「登录」和「授权」压成了一步:人登完,token 就被读走了,中间没有「允许它做什么」。
  158. `scope` 补上这一层 —— 授权时明确授予哪些能力,越界**在本地就拒**,请求根本不发出去。
  159. ```bash
  160. narwhal-forum login # 交互里确认范围(回车=全量,n=只读)
  161. narwhal-forum login --scope read,write:comment # 管线里直接指定
  162. narwhal-forum scope # 看已授权范围
  163. narwhal-forum scope set read # 收窄成只读,立刻生效
  164. ```
  165. | 范围 id | 覆盖的能力 |
  166. | --- | --- |
  167. | `read` | 帖子列表 / 详情 / 评论 / 分类 / 栏目 / 搜索 |
  168. | `read:own` | `whoami`、我发过的评论 |
  169. | `write:comment` | 发评论、回复、点赞、上传图片 |
  170. | `write:post` | 发帖 |
  171. | `moderate` | 批准待审帖(`approve_post`) |
  172. | `delete` | 删自己的评论与帖子(仍需 `confirm=true`) |
  173. | `draft` | 人审草稿:`draft_create` / `draft_publish` … |
  174. 越界时的输出(退出码 1,不发出请求):
  175. ```text
  176. ✗ 当前授权不含「评论与互动」(write:comment):已授权范围 = read。
  177. 👉 要扩权请重新授权:narwhal-forum login(或在 dsh 里调用 login 工具带 scopes)。只读内容不需要授权。
  178. ```
  179. MCP 侧:`login` 工具带 `scopes` 参数(默认 `all`),`status` 里能看到当前范围。
  180. **边界要说清楚**:这是客户端自律的闸(token 本身仍是账号全权令牌),拦的是「Agent 顺手做了你没
  181. 想到的事」,不是「谁拿到凭据文件后越权」—— 那只能靠后端鉴权与服务端 token 收窄,见 DESIGN §17。
  182. ### 4.2.2 授权页上勾选:人能反悔,工具只能照办
  183. `login --device` 打开的那张授权页不是「一票通过」:**每一项能力前面都有勾选框**,人勾什么,
  184. 工具就只能做什么(默认全勾)。勾掉的能力不会进授予集,工具侧随即本地拒绝——不是提示一下就算了。
  185. ```text
  186. ☑ 阅读帖子、评论、栏目(只读) read
  187. ☑ 发表评论、回复、点赞、上传图片 write:comment
  188. ☐ 发帖 write:post
  189. ```
  190. | 行为 | 结果 |
  191. | --- | --- |
  192. | 勾掉 `write:comment` 后点「允许」 | 凭据里 `grantedScopes` 只有勾中的项;`new-comment` 立即被拒,请求不发 |
  193. | 一项都不勾 | 「允许」按钮置灰;强行提交时服务端回滚授权(仍可重新勾选) |
  194. | 授权后再想扩 | 重跑 `login --device`(人再点一次),不是工具能自己加的 |
  195. | 工具只申请了 2 项 | 页面只列这 2 项,并注明「其余能力它用不了」。申请集是工具报的(`login --scope …` 决定),人只能在申请集里勾 |
  196. **多个工具可以同时授权,各自独立**:Claude Code、Codex、dsh 各拿一份设备码授权,互不互踢,
  197. 也不会把你自己的浏览器登录顶下线。随时在 **设置 → 账号安全 → 登录设备** 里看到「AI 工具授权」
  198. 行(显示工具名与已授予范围),点**移除授权**即刻失效——不需要邮箱验证码,也不影响其它工具。
  199. ### 4.2.3 设备码授权:远程机器 / 容器 / 没有桌面
  200. `login`(浏览器模式)要求**本机能跑 Chrome**。在 SSH、容器、CI 里换成设备码:
  201. ```bash
  202. $ narwhal-forum login --device
  203. 请在浏览器里打开下面这个地址,登录后点「允许」:
  204. http://127.0.0.1:8080/cli/authorize?code=R6DX-T5N6
  205. 授权码:R6DX-T5N6(10 分钟内有效)
  206. 等待你在网页上确认…(300 秒后放弃)
  207. 授权成功(设备码)
  208. 账号: admin
  209. 凭据已写入 ~/.config/narwhal-forum/credentials.json(0600,已含 refresh token)
  210. 授权范围: 全部(7 项)
  211. ```
  212. | 步骤 | 谁做 | 说明 |
  213. | --- | --- | --- |
  214. | 1. 申请设备码 | CLI | `POST /api/cli/device/code` → 拿到 `deviceCode`(工具持有)与 `userCode`(给人看) |
  215. | 2. 点「允许」 | 你,在**任何**已登录的浏览器里 | 打开 `/cli/authorize?code=…`,页面显示调用方与申请范围 → 允许 / 拒绝 |
  216. | 3. 换令牌 | CLI 轮询 | `GET /api/cli/device/poll` → `approved` 时一次性领走 access/refresh token |
  217. | 要点 | 说明 |
  218. | --- | --- |
  219. | 令牌只发一次 | 领走后设备码立即置 `consumed`,同一个码泄露也换不到第二份 |
  220. | 10 分钟过期 | 没人确认就作废,不用管清理 |
  221. | 前后端不同源时 | 本地开发常见「API 在一个端口、页面在另一个端口」,此时加 `--web-url <前端地址>`(或环境变量 `NARWHAL_FORUM_WEB_URL`),否则打印出来的链接指向 API 主机 —— 打开就是 404 |
  222. | 不需要本机浏览器 | 地址和授权码打印出来,人在自己电脑上打开就行 |
  223. | 不会乱开浏览器 | 只有「交互终端 + 没显式关掉」才自动拉起默认浏览器:CI / 被别的程序调用(非 TTY)、或加 `--no-open`、或 `NARWHAL_FORUM_NO_OPEN=1` 时**只打印链接**。曾经因为没有这层守卫,跑测试时默认浏览器被反复拉起并停在 mock 的 `?code=TEST-CODE` 地址上 |
  224. | 允许之后 | 授权页会显示「✓ 已允许」并倒计时 3 秒尝试自动关闭(脚本打开的标签页才关得掉);关不掉也会写明「这一页可以直接关掉」 |
  225. | 后端要求 | narwhal-cms 需包含 `/api/cli/device/*`(`CliDeviceAuthApiController`);没有这个接口时 `--device` 会提示 |
  226. | 授权成功后的反馈 | 授权页点「允许」后显示「✓ 已允许 · 回到终端,工具会自动完成登录 · 这一页可以直接关掉」,并在 3 秒倒计时后尝试自动关闭标签页(只有脚本打开的标签页关得掉;人手动打开的浏览器会拒绝,页面仍写明可以自己关) |
  227. | 撤销 | 和其它模式一样:`narwhal-forum logout` |
  228. ---
  229. ### 4.3 人审发布:AI 写、人批准、再上线
  230. 模型/AI 写的内容**不允许自己发出去**。写、批准、发布是三段分离的动作,批准只能发生在**人的终端**里:
  231. ```bash
  232. narwhal-forum draft new-comment 42 --content @reply.md # AI 侧:只落本地草稿,不联网
  233. narwhal-forum draft show drf-1a2b3c4d # 人:看全文(含目标帖子)
  234. narwhal-forum draft approve drf-1a2b3c4d # 人:TTY 里输入 yes → 打印一次性 token
  235. narwhal-forum draft publish drf-1a2b3c4d --token nfap_… # 持 token 才能发布
  236. ```
  237. - **token 一次性**:用过即废(`E_APPROVAL_USED`),重放不可能;
  238. - **10 分钟有效**(`APPROVAL_TTL_MS`),过期后草稿降级为 `expired`,需重新批准;
  239. - **绑定内容指纹**:批准后改一个字,旧 token 立刻作废(`E_APPROVAL_HASH_MISMATCH`),防「批准 A、发布 B」;
  240. - **绑定动作与用户**:发帖的 token 不能用来发评论(`E_APPROVAL_ACTION` / `E_APPROVAL_USER`);
  241. - **发布前强校验实名**:`verifiedType=0` 直接拒绝(退出码 `3`),且**不消费 token** —— 实名后同一个 token 还能用;
  242. - **MCP 侧没有批准类工具**:Agent 能建草稿、能读草稿、能拿 token 发布,但 `draft approve` 只在 TTY 里跑,Agent 无权自己批;
  243. - `draft publish` 只认 `--token`,没有 `--yes` / `--force`。
  244. 草稿与批准密钥落在 `~/.config/narwhal-forum/`(目录 `0700`、文件 `0600`):`drafts/<id>.json` 存正文与状态,`approval.key` 存 HMAC 密钥(首次批准时生成)。
  245. #### 4.3.1 站点侧草稿(`--server`):把批准搬到网页上
  246. 本地草稿(上一节)的批准只发生在「跑命令的那台机器」上:换台机器看不到,审理记录也留在本机。
  247. `--server` 把草稿交给站点,人**在浏览器里点批准**,站点记下 reviewer / 时间 / 内容指纹。
  248. ```bash
  249. narwhal-forum draft new-comment 42 --content @reply.md --server --web-url http://localhost:3000
  250. # → 已提交站点侧草稿 DR-1A2B3C4D(状态 待审)
  251. # 给人打开的审理页: http://localhost:3000/cli/draft?code=DR-1A2B3C4D
  252. narwhal-forum draft list --server # 看自己交过的草稿与状态
  253. narwhal-forum draft show DR-1A2B3C4D # 看正文 / 指纹 / 谁批的
  254. narwhal-forum draft publish DR-1A2B3C4D # 人批过之后,工具才能领取并发布
  255. ```
  256. - 工具**拿不到可发布的内容**,除非站点上有人点过「批准」(服务端 `consume` 只认 `approved`,且只能领取一次);
  257. - 草稿 24 小时有效,正文在提交时就被 `payload_hash` 钉死,批准后改内容不可行;
  258. - 带图草稿会先把图片上传换成 URL 再提交(图片本来就要上传才能显示);
  259. - 服务端拦住的是「没人点批准」,**拦不住「同一个账号自己批自己」** —— 站点只能留痕(`reviewer_id` / `approved_at` / `payload_hash`)供事后核对;
  260. - MCP 侧对应 `draft_create(mode="server")` → 回 `draftCode` + `reviewUrl`,`draft_publish(draftCode="DR-…")` 发布。
  261. ### 4.4 图片评论(`--image`)
  262. 评论正文是普通字符串,前端用 marked + DOMPurify 渲染(`<img>` 放行),所以**图片不占数据库字段**:
  263. 先把图传到论坛的上传接口拿 URL,再以 markdown `![](url)` 内联进正文。这条路径**不需要改 narwhal-cms 一行代码**。
  264. ```bash
  265. # 一条评论带两张图(图先上传,再内联)
  266. narwhal-forum new-comment 42 --content '复现步骤见下图' --image ./step1.png --image ./step2.png
  267. # 发帖带图
  268. narwhal-forum new-post --category 3 --title '报个 bug' --content @body.md --image ./shot.png
  269. # 只想先拿一个 URL(比如自己拼正文)
  270. narwhal-forum upload-image ./shot.png --json # → {"url":"http://…/uploads/2026/11/xxx.webp", …}
  271. ```
  272. 走的接口就是网页端粘贴上传的那一条:`POST /api/upload/image-upload`(multipart,字段名 `file`,
  273. `@PreAuthorize("isAuthenticated()")`)。**压缩、水印、图片内容审核都在上传时由后端完成**,所以:
  274. | 规则 | 值 | 说明 |
  275. | --- | --- | --- |
  276. | 单张上限 | 10MB | 客户端先挡一层,免得白传 |
  277. | 每条上限 | 9 张 | 再多没有阅读价值 |
  278. | 格式 | png / jpg / jpeg / gif / webp / bmp / avif | 按扩展名推断 Content-Type |
  279. | 审核 | 后端 `ImageModerationProvider` | 命中敏感图直接返回 400,**评论不会发出** |
  280. | 场景 | `--scene chat` | 私信/聊天类内容传 `chat`,文件会被登记为私密 |
  281. 草稿带图时,草稿里只存**本地路径 + sha256**(不联网、不上传);`draft_publish` 会**先重新校验文件指纹**:
  282. 文件被删 → `E_IMAGE_MISSING`;内容变了 → `E_IMAGE_CHANGED`。两种情况都在上传前失败,**token 不消费**,
  283. 所以「人批准的是这张图,发出去的就必须是这张图」。
  284. > 为什么不做「后端加 `images_` 列」:评论正文已经是 markdown,加列等于把同一份信息存两处,
  285. > 还要改实体、迁移、DTO 与前端渲染;内联方案的渲染路径(`BbsMarkdown.vue`)本来就存在。
  286. ---
  287. ## 5. 接入各工具
  288. ### dsh(插件形式)
  289. ```bash
  290. # 1) 先让命令在 PATH 上(三选一)
  291. npm i -g --prefix ~/.local /path/to/narwhal-forum # 推荐:用户级,无需 sudo
  292. # 或 npm i -g narwhal-forum # 已发布到 npm 时
  293. # 2) 装进 dsh:target = 本包绝对目录
  294. plugin_manager action=install_bundle target="/path/to/narwhal-forum"
  295. ```
  296. ```bash
  297. # 3) 授权一次(会打开浏览器;之后 dsh 里的论坛调用都用这份凭据)
  298. narwhal-forum setup
  299. ```
  300. 包内 `cordis.patch.yml` 完成接线:`@deepseek-ai/dsh-mcp-client` 以 stdio 拉起
  301. `narwhal-forum mcp`,工具以 `mcp__narwhal-forum__<tool>` 暴露给 Agent。
  302. 升级 / 卸载走同一入口(`plugin_manager` 的 set_plugin / remove_bundle),不要手改 profile。
  303. | 你的安装方式 | patch 的 command / args |
  304. | --- | --- |
  305. | `npm i -g --prefix ~/.local .`(默认配置) | `narwhal-forum` / `[mcp]` |
  306. | 已发布到 npm,想用 npx | `npx` / `[-y, narwhal-forum, mcp]` |
  307. | 不装全局,源码直跑 | `node` / `[<包目录>/bin/narwhal-forum.js, mcp]`(见 `examples/cordis.local.patch.yml`) |
  308. | **dsh 桌面端(app)** | 见下面 5.1:桌面进程的 PATH 里没有 node,必须用启动器脚本包一层 |
  309. ### 5.1 dsh 桌面端:PATH 里没有 node(必读)
  310. dsh 桌面版(Electron 打包的 app)**不继承你的 shell PATH**,它的进程环境只有
  311. `/usr/bin:/bin:/usr/sbin:/sbin`。可以自己确认:
  312. ```bash
  313. ps eww -p $(pgrep -f 'DeepSeek Harness' | head -1) | tr ' ' '\n' | grep '^PATH='
  314. # → PATH=/usr/bin:/bin:/usr/sbin:/sbin
  315. ```
  316. 于是 `command: narwhal-forum`、`npx`、甚至 `node`(nvm 装的)**全都解析不到**。
  317. 而 `failOnStartupError: false` 会让这种失败**静默发生**:工具列表少了一截,看起来像「插件没装」。
  318. 解法:给它一个绝对路径的启动器(一个 20 行的 sh 脚本,自己找 node,与 nvm 版本解耦)。
  319. ```bash
  320. # 1) 安装启动器(仓库自带)
  321. mkdir -p ~/.dsh/bin
  322. cp examples/narwhal-forum-mcp ~/.dsh/bin/narwhal-forum-mcp
  323. chmod +x ~/.dsh/bin/narwhal-forum-mcp
  324. # 2) 在 profile 的 cordis.patch.yml 里按 id 覆写那一行
  325. # (模板:examples/cordis.desktop.patch.yml)
  326. ```
  327. ```yaml
  328. - id: narwhal-forum-mcp # 必须与包内 cordis.patch.yml 的 id 一致,否则是「新增一行」而不是「改这一行」
  329. name: '@deepseek-ai/dsh-mcp-client'
  330. config: # ⚠️ config 整体替换、不深合并:所有字段都得重述
  331. serverName: narwhal-forum
  332. transport: stdio
  333. command: /Users/<you>/.dsh/bin/narwhal-forum-mcp
  334. args: []
  335. toolCallTimeoutMs: 60000
  336. failOnStartupError: true # 桌面端建议 true:起不来就报错,而不是静默少一批工具
  337. reconnect: { enabled: true, initialDelayMs: 500, maxDelayMs: 30000, maxAttempts: 10 }
  338. ```
  339. 改完**重启 dsh 应用**才会生效;重启后 `mcp__narwhal-forum__*` 才会出现在工具列表里。
  340. 验证:`cordis_inspect_query` 查 `@deepseek-ai/dsh-mcp-client`,应能看到 `patchId: narwhal-forum-mcp` 这一行;
  341. 或者直接让 Agent 调 `mcp__narwhal-forum__status`。
  342. > 不想用启动器也可以写死 node 绝对路径(`command: /Users/<you>/.nvm/versions/node/v24.14.0/bin/node`,
  343. > `args: [<profile>/node_modules/narwhal-forum/bin/narwhal-forum.js, mcp]`),代价是 nvm 换版本时要改这一行。
  344. <details>
  345. <summary>覆写没生效时(重启后仍然没有 <code>mcp__narwhal-forum__*</code>)</summary>
  346. 同一 id 的覆写依赖 patch 层的先后顺序。万一版本升级后顺序变了、覆写被 bundle 层盖掉,
  347. 就直接**把 bundle 那一行关掉、另起一个 id** —— 这招与顺序无关:
  348. ```yaml
  349. # 1) 关掉包自带的那一行(只改 disabled,不动 config)
  350. - id: narwhal-forum-mcp
  351. disabled: true
  352. # 2) 用另一个 id 插一条等价的
  353. - insert:
  354. - id: narwhal-forum-mcp-local
  355. name: '@deepseek-ai/dsh-mcp-client'
  356. config:
  357. serverName: narwhal-forum
  358. transport: stdio
  359. command: /Users/<you>/.dsh/bin/narwhal-forum-mcp
  360. args: []
  361. toolCallTimeoutMs: 60000
  362. failOnStartupError: true
  363. reconnect: { enabled: true, initialDelayMs: 500, maxDelayMs: 30000, maxAttempts: 10 }
  364. ```
  365. `serverName` 必须保持不变(它决定工具前缀 `mcp__narwhal-forum__*`),只有 patch 行的 `id` 可以变。
  366. </details>
  367. ### Claude Code
  368. ```json
  369. {
  370. "mcpServers": {
  371. "narwhal-forum": {
  372. "command": "narwhal-forum",
  373. "args": ["mcp"],
  374. "env": { "NARWHAL_FORUM_BASE_URL": "http://127.0.0.1:8080" }
  375. }
  376. }
  377. }
  378. ```
  379. 放在项目 `.mcp.json` 或 `~/.claude.json`。没装全局就把 `command` 换成 `npx`、`args` 换成 `["-y","narwhal-forum","mcp"]`。
  380. ### Codex CLI
  381. ```toml
  382. [mcp_servers.narwhal-forum]
  383. command = "narwhal-forum"
  384. args = ["mcp"]
  385. [mcp_servers.narwhal-forum.env]
  386. NARWHAL_FORUM_BASE_URL = "http://127.0.0.1:8080"
  387. ```
  388. ### 任意 MCP host
  389. 任何支持 stdio MCP 的客户端:命令 `narwhal-forum`,参数 `mcp`。
  390. 协议版本协商支持 `2025-06-18` / `2025-03-26` / `2024-11-05`。
  391. ---
  392. ## 6. 能力矩阵(MCP 工具与 CLI 同源)
  393. | 工具 | 作用 | 主要参数 | 只读 | 需登录 |
  394. | --- | --- | --- | --- | --- |
  395. | `status` | 配置与登录状态 | — | ✅ | 否 |
  396. | `login` | 网页授权登录(默认)/ 设备码 / 账号密码 | `mode` `scopes` `timeoutSec` `browserPath` `username?` `password?` `captchaToken?` | ❌ | 否 |
  397. | `logout` | 撤销授权(后端登出 + 删凭据 + 删 profile) | `keepBrowser?` | ❌ | 否 |
  398. | `whoami` | 当前用户 | — | ✅ | 是 |
  399. | `list_posts` | 帖子列表 | `page` `pageSize` `categoryId` `userId` `titleLike` `order` | ✅ | 否 |
  400. | `get_post` | 帖子详情 | `postId` `withComments` `commentSort` | ✅ | 否 |
  401. | `list_comments` | 评论树 | `postId` `sort` | ✅ | 否 |
  402. | `list_categories` | 分类 | `page` `pageSize` | ✅ | 否 |
  403. | `list_channels` | **站点栏目**(CMS channel,非论坛版块) | — | ✅ | 否 |
  404. | `search_posts` | 搜索 | `q` `categoryId` `userId` `dateFrom` `dateTo` `sort` `page` `pageSize` | ✅ | 否 |
  405. | `my_comments` | 我的评论 | `page` `pageSize` | ✅ | 是 |
  406. | `create_comment` | 发表评论 | `postId` `content` `parentId?` `replyUserId?` `whisper?` `images?` | ❌ | 是 |
  407. | `create_post` | 发帖 | `categoryId` `title` `content` `summary?` `type?` `cover?` `images?` | ❌ | 是 |
  408. | `upload_image` | 上传一张图,返回 URL | `path` `scene?` | ❌ | 是 |
  409. | `react_post` | 表情互动 | `postId` `emoji` | ❌ | 是 |
  410. | `approve_post` | 批准待审帖(管理员/版主) | `postId` | ❌ | 是 |
  411. | `delete_comment` | 删评论(作者/管理员,**不可撤销**) | `commentId` `confirm=true` | ❌ | 是 |
  412. | `delete_post` | 删帖(作者/管理员,**不可撤销**) | `postId` `confirm=true` | ❌ | 是 |
  413. | `draft_create` | 落本地草稿(**不发出去**) | `kind` `content` `postId?` `parentId?` `replyUserId?` `whisper?` `categoryId?` `title?` `summary?` `images?` | ❌(不联网) | 否 |
  414. | `draft_list` | 草稿列表 | `status?` | ✅ | 否 |
  415. | `draft_get` | 单条草稿 | `draftId` | ✅ | 否 |
  416. | `draft_discard` | 丢弃草稿 | `draftId` | ❌ | 否 |
  417. | `draft_publish` | 用**人给的一次性 token** 发布 | `draftId` `approvalToken` | ❌ | 是 |
  418. `order` 取值:`newest` `hot` `trending` `unanswered` `following` `most-collected` `best-all-time` `on-this-day`。
  419. `emoji` 白名单:👍 ❤️ 😂 🎉 🤔 😮 😢 🚀。
  420. `images` 是**本地文件路径数组**(最多 9 张):工具内部先上传再内联 markdown,调用方不需要自己拼 URL。
  421. 两个容易踩的点(都在真实后端上验过):
  422. - **所有 id 都是雪花号**,schema 里一律声明成 `string`。按数字传会被 JSON 的双精度截断
  423. (`101589601795420674` → `…670`),后端稳定 404。CLI 里照原样贴字符串就行。
  424. - `delete_comment` / `delete_post` 必须带 `confirm=true`(CLI:`--yes`)才执行,
  425. 没带就只回一句「这是不可撤销操作」,不会动数据。
  426. ---
  427. ## 7. 排错
  428. | 现象 | 原因 / 处理 |
  429. | --- | --- |
  430. | 连不上论坛后端 | 后端没起或 `NARWHAL_FORUM_BASE_URL` 不对;先 `narwhal-forum status` |
  431. | 这个操作需要登录 | `narwhal-forum login` 或 `token set` |
  432. | 评论太快了,请等 15 秒再发 | 后端限流,等冷却 |
  433. | 需要手机号 / 实名认证 | 后端策略,补齐账号资料后重试 |
  434. | 401 自动刷新后仍失败 | refresh token 过期,重新登录 |
  435. | 没找到 Chrome / Edge / Brave | `--browser <路径>` 或 `NARWHAL_FORUM_BROWSER`;或 `login --password` |
  436. | 等待登录超时(LOGIN_TIMEOUT) | 窗口里没完成登录;重跑 `login`,或加 `--timeout-sec 600` |
  437. | 当前 Node 没有内置 WebSocket | Node < 22,用 `login --password` 或升级 Node |
  438. | `npm error sudo chown ...` | 见第 1 节,换 `npm_config_cache` |
  439. ---
  440. ## 8. 已知限制
  441. - **已支持**:图片(评论/发帖内联,见 4.4)。
  442. - **未实现**:非图片附件、通知、私信、收藏与关注列表(后端有接口但未纳入本包;`call` 逃生舱可临时补位)。
  443. - **验证边界**(三层,都已跑过):
  444. 1. **单元/集成**:104 个用例跑在进程内 mock 后端(同一套契约)。
  445. 2. **MCP 端到端**:`npm run test:e2e`(`scripts/e2e-mcp.mjs`)用 dsh 桌面端**实际会 spawn 的那条命令**、在
  446. `PATH=/usr/bin:/bin:/usr/sbin:/sbin`(没有 node / npx)的干净环境里走完
  447. initialize → tools/list(23 个)→ `list_posts` → `upload_image` → `create_comment` 带图,并校验 mock 里
  448. 落库的正文确实是 `![](http://…)`。10/10 通过 —— 这一层证明「桌面端 PATH 里没有 node」不再是阻塞。
  449. 3. **真实论坛**:`node scripts/e2e-live.mjs --write` 连真后端(narwhal-cms + MySQL + Redis)跑,**11/11 通过**:
  450. 20+ 工具、雪花 id 以字符串传、`list_posts` / `get_post`(含评论树)/ `list_comments` 读真实数据、
  451. `create_comment` 写库、`react_post` toggle、`create_post` 返回真实 `status`、待审时 `approve_post` 放行、
  452. `delete_post` 清理自造的冒烟帖。另手工验过:图片上传 + 带图评论、嵌套回复、搜索、CMS 栏目、草稿人审闸。
  453. ### 8.0 权限与门禁实测(2026-11-21,真后端逐项验过)
  454. 插件自己不判权限 —— 所有授权都由后端决定,插件只负责把「被拦的原因」和「去哪解决」原样端出来。
  455. 下表是三种身份在真实后端上的实际结果(`✅` 通过 / `🚫` 被后端拒绝并给出可执行提示):
  456. | 操作 | 匿名(未登录) | 普通用户(无角色) | 管理员 |
  457. | --- | --- | --- | --- |
  458. | `list_posts` / `get_post` / `list_comments` / `list_categories` / `list_channels` / `search_posts` | ✅ | ✅ | ✅ |
  459. | `create_comment` | 🚫 `🔒 「发表评论」需要登录`(退出码 1) | ✅(需先绑手机 + 实名,见下) | ✅ |
  460. | `create_post` | 🚫 需要登录 | ✅,但 `status=-1` 待审 | ✅,**同样** `status=-1` 待审 |
  461. | `react_post` | 🚫 需要登录 | ✅ | ✅ |
  462. | `approve_post` | 🚫 需要登录 | 🚫 `No permission`(HTTP 400) | ✅ |
  463. | `delete_comment` | 🚫 需要登录 | ✅ 仅自己的;别人的 🚫 `Only the author can delete this comment` | ✅ 可删任何人的 |
  464. | `delete_post` | 🚫 需要登录 | ✅ 仅自己的;别人的 🚫 `Only the author can delete this post` | ✅ 可删任何人的 |
  465. 两道**内容门禁**(普通用户写内容前必须过,管理员豁免):
  466. 1. 未绑手机 → `需先绑定手机号才能评论` + blocker `actionTo=/forum/settings?tab=binding#mobile-binding`;
  467. 2. 未实名 → `需完成实名认证后才能评论` + blocker `actionTo=/forum/settings?tab=profile`。
  468. 后端的门禁响应是 **HTTP 200 + `status=-1` + `result.blockers[]`**(`{code,title,desc,actionLabel,actionTo,action}`)。
  469. 插件把 `blockers` 一路透传:CLI 打成 `· 完成实名认证(去认证):/forum/settings?tab=profile`,
  470. MCP 的 `isError` 结果正文里附同样的清单、并放进 `structuredContent.error.blockers`,
  471. `--json` 输出顶层带 `blockers`。**被拦时不能只说「失败了」,要给出去哪解决**。
  472. 其它已验证的边界:无效 token → `🔒 未登录或登录已过期(HTTP 401)`;评论 15 秒冷却原样透出;
  473. 删除不存在的 id → `BbsPost not found. ID = <id>(HTTP 404 …)`;不带 `confirm` 的删除在插件层就被拦下(不碰后端)。
  474. ### 8.0.1 凭据热重载:CLI 登录完,不用重启宿主
  475. MCP server 启动时会把配置/凭据快照到内存(`src/mcp/server.js` 构造 `ForumClient` 那一刻)。
  476. 所以「先 `narwhal-forum login`、再让已经跑着的 dsh 用新登录」原本是**不生效**的 —— 得重启整个宿主。
  477. 现在补了一次磁盘重读:请求 401 → 刷新失败(例如 `SESSION_KICKED`)→ 重读
  478. `~/.config/narwhal-forum/credentials.json`,只有当文件里的 access token 与本进程持有的不同才切换,
  479. 然后用新 token 重放**一次**(`#reloadCredentialsOnce()`,绝不循环)。
  480. 判据(`test/client.test.js`):进程里塞一个过期 token、磁盘上是新 token → `whoami()` 仍应返回真实用户名,
  481. 且 `client.token` 已被换成磁盘上的那个。
  482. ### 8.1 真实后端实测踩到的 5 个坑(都已修,附成因)
  483. 这些不是「理论上可能」,是本轮连真后端时**实际把功能跑坏**的东西:
  484. | 现象 | 成因 | 修法 |
  485. | --- | --- | --- |
  486. | `get_post` 稳定 404,id 看着对但不一致 | 雪花 id 超过 2^53,JSON 按数字解析被截断(…674 → …670) | 所有 id 在 schema 里改成 `string`,数字传进来直接报错并给出提示 |
  487. | `list_channels` 永远 404 | `/api/bbs/channel` 在真后端是「创作者频道自助申请」那套(self-serve/apply/my-channel),**没有列表 GET**;真正的栏目列表是 CMS 的 `/api/channel`(扁平数组、不分页) | 改打 `/api/channel`,工具改名为「站点栏目」,并在描述里点名「论坛版块请用 `list_categories`」 |
  488. | 搜索结果时间显示成 `1795248388000` | Lucene 返回的 `created` 是**毫秒时间戳的字符串**,`new Date('1795…')` 在 V8 里是 Invalid Date | `fmtTime` 显式认 10/13 位数字(秒/毫秒) |
  489. | 回复发出去了,评论树里看不见、计数也少 | `GET /api/bbs/comment?postId=&parentId=0` **只回直接子级**,嵌套回复在 `/api/bbs/comment/{id}/replies`(Pageable,pageSize 上限 20) | 逐层拉 replies 拼 `children`(默认 3 层 / 60 次请求封顶,超了标 `truncated`) |
  490. | 发帖成功但列表里没有 | 新账号/未达信任阈值 → 后端给 `status_=-1`(待审),**管理员自己发的也待审**;原来工具无条件说「已发布」 | 按后端真实 `status` 说话(1=已发布,-1=待审并提示用 `approve_post`),并新增 `approve_post` 工具 |
  491. - 浏览器授权把「开浏览器 + 取 token」抽成可注入的取值函数来测,真实弹窗需要人工验证一次。
  492. - **仓库**:GitHub 私有仓 `sasazhang2333/narwhal-forum`(与 narwhal-cms 同级存放,本地目录名同名)。
  493. - **待确认**:是否发布到 npm 私有源(`npx narwhal-forum` 现在需先 `npm i -g`,或用 `npx --package <tarball>`)。
  494. - 论坛若开启验证码 / 双因素登录:**网页授权天然通过**(人就在真浏览器里);只有 `login --password` 会返回 `CAPTCHA_REQUIRED` / `TWO_FACTOR_REQUIRED`。
  495. - 浏览器授权依赖 Chromium 系浏览器(Chrome / Edge / Brave / Chromium);Safari / Firefox 不支持,需 `--password` 或 `token set`。
  496. ---
  497. ## 9. 目录
  498. ```text
  499. narwhal-forum/
  500. ├── bin/narwhal-forum.js # CLI 入口(bin 名:narwhal-forum / nf)
  501. ├── src/
  502. │ ├── client.js # 论坛 API 客户端(错误模型、401 刷新重放)
  503. │ ├── auth.js # 浏览器授权登录 / 撤销 / 状态(CDP 读 token)
  504. │ ├── crypto.js # RSA + AES 登录加密
  505. │ ├── config.js # 配置解析 + 凭据文件
  506. │ ├── images.js # 图片校验 / multipart 拼装 / markdown 内联
  507. │ ├── cli.js # 命令行
  508. │ ├── index.js # 库导出
  509. │ └── mcp/
  510. │ ├── server.js # 手写 MCP stdio JSON-RPC server
  511. │ └── tools.js # 20 个能力定义与渲染
  512. ├── cordis.patch.yml # dsh 插件接线
  513. ├── locale/{en,zh}.json # dsh 插件文案
  514. ├── icon.svg
  515. ├── examples/ # Claude Code / Codex / dsh 启动器 / profile 覆写示例
  516. ├── scripts/e2e-mcp.mjs # 端到端:按桌面端真实命令跑一遍 MCP(10 项断言)
  517. └── test/ # mock 论坛 + 93 个用例(含 multipart 上传端点)
  518. ```
  519. ## 10. 开发
  520. ```bash
  521. npm test # 等价于 node --test "test/*.test.js"(93 个用例)
  522. npm run test:e2e # 端到端:用桌面端的启动器跑一遍 MCP(不需要真论坛,会自动起 mock)
  523. npm run mcp # 本地起 MCP server
  524. ```
  525. ## License
  526. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.