@cnbmtech/dsh-zentao-session 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CNBM Technology (@cnbmtech)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,135 @@
-# Temporary Holding Version
+# @cnbmtech/dsh-zentao-session
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 的**禅道（ZenTao）会话式集成插件**：9 个模型工具 + 一个「我的工作」面板（BUG / 任务 / 需求），可把条目一键送进对话。
+
+> 走禅道的**会话式接口**（`/my-*.json` + 表单页），不依赖 REST API v1/v2 —— 因此在那些 `api.php` 被网关改造、官方 REST 不可用的禅道实例上照样能用。
+
+## 能力
+
+**面板**（侧边栏「插件」分组 → 禅道）
+
+- 三个页签：我的 BUG / 我的任务 / 我的需求，每个页签自带**浏览范围**下拉（指派给我 / 由我创建 / 由我解决|完成 / 我评审 / 由我关闭 …，与禅道「我的地盘」的 tab 逐一对应）
+- 统计卡点击筛选、标题/编号搜索、列表与详情双栏、详情全屏
+- 详情里：富文本重现步骤/描述（图片走本机代理并可点击放大、左右切换）、基本信息、处理信息、关联对象、操作历史
+- BUG 可直接在面板里走禅道原生表单：确认 / 解决 / 关闭 / 激活 / 指派（提交前拉取真实表单字段，提交后回读证实）
+- 添加备注（三段式模板：问题原因／解决方案／解决时间）
+- 「在禅道中打开」链接附带会话参数，**免登录直达**
+- **拖拽 / 复制为 Markdown 引用**：把条目拖到聊天输入框，或点「复制」后粘贴
+- **按角色处理**：选好职位（开发/测试/产品/管理）→ 点「按【开发】处理」→ 在当前项目新建对话并自动发送「角色提示词 + 条目 Markdown」
+- 自动刷新：关 / 1 / 5 / 15 / 30 分钟（页面不可见时跳过，不打扰禅道）
+
+**模型工具**
+
+| 工具 | 用途 |
+|---|---|
+| `zentao_ping` | 连通性与凭据自检 |
+| `zentao_my_bugs` / `zentao_my_tasks` / `zentao_my_stories` | 三类条目列表，`type` 指定浏览范围 |
+| `zentao_bug_view` / `zentao_story_view` | 单条完整详情 |
+| `zentao_bug_confirm` / `zentao_bug_comment` | 确认 BUG / 追加备注（写操作） |
+| `zentao_plugin_status` | 注册诊断（取数失败时排障用） |
+
+插件还会注册一段系统提示，告诉模型这些工具何时用、未登录该怎么办。
+
+## 安装
+
+前置：DeepSeek Harness（本插件按 `0.2.0-rc.2` 开发与验证）、Node `^22.19 || >=24`。
+
+**方式一：DSH 桌面端插件管理器（推荐）**
+
+设置 → 插件 → 「添加插件」，输入三者之一：
+
+- **包名**：`@cnbmtech/dsh-zentao-session`（npm 或公司私服）
+- **Git 仓库地址**：内网 Git / GitHub 地址
+- **本地目录路径**：例如 `D:\dsh-plugins\dsh-zentao-session`
+
+> ⚠️ **选「本地目录」时务必先在该目录里执行过一次 `npm install`**。包管理器只做目录链接，**不会**替你安装被链接包自己的依赖；目录里没有 `node_modules` 时插件会因为找不到 `@deepseek-ai/dsh-tools` 而起不来。从 npm 包名或 Git 地址安装则没有这个问题（依赖写在 `dependencies` 里，会自动装）。
+
+**方式二：CLI**
+
+```powershell
+# 包名
+dsh plugin --profile web add @cnbmtech/dsh-zentao-session
+# 本地目录（同样记得先 npm install）
+dsh plugin --profile web add D:\dsh-plugins\dsh-zentao-session
+```
+
+安装后**完全重启 DSH**（客户端 bundle 只在启动时加载，关开插件不会刷新）。
+
+> ⚠️ **刚发布的版本装不上？** 插件管理器走 pnpm，带 24 小时供应链策略（`minimumReleaseAge`）——发布不到一天的版本会被静默跳过。等待一天，或者在 profile 的 `~/.dsh/profiles/<profile>/pnpm-workspace.yaml` 里放行：
+>
+> ```yaml
+> minimumReleaseAgeExclude:
+>   - '@cnbmtech/dsh-zentao-session@0.2.0'
+> ```
+
+## 登录与配置
+
+打开侧边栏「禅道」面板，填**禅道地址 / 账号 / 密码**，点「登录并保存」——凭据写入 DSH 凭据库 `~/.dsh/.credentials.yaml`（refs：`ZENTAO_BASE_URL` / `ZENTAO_ACCOUNT` / `ZENTAO_PASSWORD`），之后免登录，且可随时「退出登录」清除密码。
+
+也可以在 profile 的 `cordis.patch.yml` 里配置 `id: zentao-session` 的 `config`（优先级：config > 凭证库 > 环境变量）：
+
+| 字段 | 默认 | 说明 |
+|---|---|---|
+| `baseUrl` | 空 | 禅道地址（不含末尾 `/`）；为空时读凭据 `ZENTAO_BASE_URL` |
+| `account` / `password` | 空 | 同上，建议放凭据库，**不要写进配置文件** |
+| `timeoutMs` | 30000 | 单次请求超时 |
+| `defaultLimit` | 20 | 列表工具默认返回条数 |
+
+未配置地址时插件**不休眠**：照常注册工具与路由，只在你真正取数时提示"请先在面板登录"。
+
+## 安全边界
+
+- 面板数据接口 `/api/dsh-zentao-session/*`：**所有 action（含读）都要求自定义请求头** `x-dsh-zentao-session: 1`，且 Host 必须是回环字面量（防 DNS rebinding）
+- 截图代理 `/api/dsh-zentao-session-file?path=…`：只放行禅道 `/file-(read|download)-数字` 路径，只回位图/PDF（排除 SVG，避免同源脚本执行面），单文件 8 MB 上限
+- 表单写入：令牌 `kuid` 取不到就**硬失败**，绝不带空令牌出网；非幂等 POST **从不自动重试**（避免重复备注——该版本禅道删不掉备注）
+- `posted: true` 只代表"禅道没报错"；确认/备注都会**回读证实**后才报成功
+- 仓库内不含任何禅道地址、账号或密码
+
+## 排障
+
+| 现象 | 处理 |
+|---|---|
+| 面板空白 / 页签缺失 | 客户端 bundle 没重新加载 → **完全重启 DSH**（不是关开插件），再刷新页面 |
+| 工具报「请在面板登录」 | 打开侧边栏「禅道」面板登录一次 |
+| 取数失败 | 让模型调用 `zentao_plugin_status`，它会打出路由/RPC 注册结果与真实错误 |
+| 列表比预期少 | 禅道「我的地盘」一页只回 20 条；面板会标注"服务端共 N 条"，用范围/筛选收窄，或让模型用工具的 `limit` |
+
+## 已知限制
+
+- 目录/链接安装时依赖需自备（见上）
+- 列表按禅道默认分页（一页 20 条）；插件只展示/返回首页数据，不做翻页
+- 需求的**详情**接口不返回产品名（只有产品 id），面板会回落到列表行；列表能拿到就没问题
+- 表单操作只覆盖 BUG（确认/解决/关闭/激活/指派）；任务与需求为只读 + 复制/拖拽/送对话
+- 需要**禅道账号本身有对应权限**；插件不做越权尝试
+
+## 开发与自测
+
+```sh
+npm install
+node test-client.mjs          # 面板全链路（最小 React hooks 模拟宿主）
+node test-tools.mjs           # 9 个工具的渲染 + lossless JSON
+node test-form-encoding.mjs   # 写路径铁律（多选重复键 / 302 不重发 / 缺 kuid 不出网）
+node test-real-render.mjs     # 真实 React SSR 首跳
+node test-real-browser.mjs    # jsdom + 真实 React 全交互链
+```
+
+目录结构：`index.js`（宿主：工具 + HTTP/RPC 路由 + 系统提示）、`src/client.js`（宿主侧禅道客户端：登录/列表/详情/表单）、`client.js`（浏览器面板 bundle）、`cordis.patch.yml`（bundle 安装层）。
+
+## 发布与迭代（维护者）
+
+```powershell
+npm login                                   # 首次：需要 npm 账号，且对 @cnbmtech 组织有发布权
+npm version patch                           # 0.2.0 → 0.2.1（或 minor/major）
+npm publish                                 # publishConfig 已设 access=public，无需再加 --access
+npm view @cnbmtech/dsh-zentao-session versions   # 确认发布成功
+```
+
+- **首次发布前**需要在 npm 上创建组织 `cnbmtech`（免费组织只能发公开包），或用公司私有源：
+  `npm publish --registry https://私服地址`（并让同事的插件管理器指向该源）。
+- **本机开发**不必发布：profile 里以 `link:` 指向源码目录，改完代码**重启 DSH** 即生效；只有同事需要走 npm。
+- **同事升级**：插件管理器里重新添加同名包（或 `dsh plugin --profile web update @cnbmtech/dsh-zentao-session`），再完全重启 DSH。
+- 发布物只含 10 个文件（`package.json` 的 `files` 白名单），不含 `node_modules`、测试脚本与任何凭据——发布前可用 `npm pack --dry-run` 复核。
+
+## 许可
+
+MIT