dsh-zentao-mark-effort

Readme

# dsh-zentao-mark-effort

非官方社区插件，与 DeepSeek、禅道及其官方团队无隶属关系。MIT 许可证。Node.js 20+；兼容性验证使用 DSH 0.1.2-rc.1。上游 76 个工具由外部依赖 `@houengineer/zentao-mcp-server@1.0.3` 提供，首次启动需要访问 npm registry。

面向 DeepSeek Harness 的禅道 Bundle。它保留上游 76 个通用禅道工具，并增加一组经过保护和校验的扩展工具：按名称递归搜索任务/子任务、创建和配置任务/子任务、记录正式工时、创建/修改/解决/关闭 Bug，以及产品线 Bug 和每周 Bug 报告。

## 安装

安装打包文件：

    dsh plugin --profile web add -w dsh-zentao-mark-effort

或者安装本地文件：

    dsh plugin --profile web add -w ./dsh-zentao-mark-effort-0.2.4.tgz

也可以安装源码目录：

    dsh plugin --profile web add -w ./dsh-zentao-mark-effort

安装后重启 DSH。Bundle 使用 DSH 官方 `dsh.bundle.patch` 机制注册 MCP 和 Skill。

## 配置

在启动 DSH 的同一个环境中设置：

    export ZENTAO_BASE_URL=https://zentao.example.com/zentao
    export ZENTAO_ACCOUNT=你的禅道账号
    export ZENTAO_PASSWORD=你的禅道密码
    dsh web

Windows PowerShell：

    $env:ZENTAO_BASE_URL = 'https://zentao.example.com/zentao'
    $env:ZENTAO_ACCOUNT = 'your-account'
    $secret = Read-Host 'ZenTao password' -AsSecureString
    $env:ZENTAO_PASSWORD = [System.Net.NetworkCredential]::new('', $secret).Password
    dsh web

`config/zentao.env.example` 只是模板，不会自动加载。填写禅道根路径；MCP 支持已有 `/api.php/v1` 后缀，但 Python 脚本要求根路径。Desktop 必须通过其启动环境提供这些变量。不要提交真实配置文件。

可选环境变量：

- `ZENTAO_TOKEN`：已有 REST token 时可直接使用。
- `ZENTAO_MCP_PACKAGE`：覆盖原有通用 MCP 包；默认固定为 `@houengineer/zentao-mcp-server@1.0.3`。
- `ZENTAO_MCP_FAIL_ON_STARTUP_ERROR=true`：明确要求禅道连接失败时阻止 DSH 启动。默认记录错误并允许 DSH 启动。
- `ZENTAO_DSH_PROFILE`：使用非 web profile 时指定 profile 名称。
- `ZENTAO_PLUGIN_ROOT`：直接指定插件安装目录。

账号、密码和 token 只从启动环境读取，不写入插件文件或回复。MCP 服务在 401 后会使用账密重新登录；默认上游版本已固定，避免 `npx` 无意间拉取不兼容的新版本。

## 工具分工

原有工具仍以 `mcp__zentao__*` 暴露。新增工具以 `mcp__zentao-ext__*` 暴露：

- `zentao_search_tasks`：按名称递归搜索所有可见项目/执行中的任务和子任务；可用 `projectId` 或 `executionId` 缩小范围。
- `zentao_create_task`、`zentao_create_subtask`、`zentao_update_task`、`zentao_set_task_status`：创建、配置和变更任务/子任务。
- `zentao_record_task_effort`：可以传任务 ID，也可以传唯一的任务名称；写入后必须读取任务并校验 `consumed`、`left`。
- `zentao_create_bug`、`zentao_update_bug`、`zentao_resolve_bug`、`zentao_close_bug`：Bug 全生命周期操作。
- `zentao_list_product_line_bugs`：按产品线筛选 Bug；默认 `active` 表示未解决 Bug，可用 `openedBuild` 明确指定线上版本。
- `zentao_list_weekly_bugs`：按 `openedDate`、`resolvedDate`、`closedDate` 或 `lastEditedDate` 统计指定周。

所有写工具都要求调用方显式传 `confirm=true`。这不是额外的登录确认，而是防止模型在上下文不完整或网络超时后重复写入；查询工具不需要该参数。

## 记录正式工时

`zentao_record_task_effort` 和脚本都会调用禅道 Web 的 `task-recordEstimate-{id}.html` 表单接口，生成带日期、说明、消耗时长的正式工时明细。不会用 REST 的 `tasks/{id}/estimate`，也不会把 `PUT tasks/{id}` 的 `consumed` 当成正式工时。

脚本示例：

    python3 /path/to/dsh-zentao-mark-effort/scripts/record_effort.py 123 2 --work "写测试用例" --left 3

如果任务 `estimate=0`，必须明确传 `--left` 或 `--done`，不会静默把剩余工时写成 0。脚本和 MCP 写入都在服务端返回成功后重新读取任务并校验结果；校验失败不会自动重试。

## 验证

    dsh --profile web --dump-config

确认配置中同时出现 `mcp-zentao` 和 `mcp-zentao-extra`。启动后应分别看到 `mcp__zentao__*` 和 `mcp__zentao-ext__*`。默认连接失败会记录原因并允许 DSH 启动。

macOS/Linux 启动进程缺少连接变量时，插件通过 `/bin/zsh -ic` 读取用户已配置的 `.zshrc`，仅补齐缺失的四个禅道连接变量。已有环境值优先，密码只保留在进程内存中。无需为旧终端手动执行 source；Windows 仍使用启动环境变量。

“线上 Bug”的业务口径（只看未解决、只看某个线上版本，或其他状态组合）可能因团队约定不同，插件不会擅自把它们混为一谈；调用报告工具时请传 `status` 和/或 `openedBuild`。

## 已知限制与验证范围

- 原有 Python 脚本关闭 HTTPS 证书验证，此行为保留；详见 SECURITY.md。Node MCP 使用默认 TLS 证书验证。
- 任务、子任务和 Bug 的路由、字段及正式工时 Web 表单依赖禅道版本。0.2.4 将普通任务创建改为 `/executions/{id}/tasks`；子任务使用原生 `task-batchCreate` JSON 表单（单行数组字段），不再向 REST 创建接口发送会被忽略的 `parent`。
- 子任务创建在一套禅道 18.5 环境中经用户授权完成真实写入及回读：父子关系、执行、名称、指派、预计/剩余工时符合预期，已耗工时为零。另有本地 MCP 契约回归测试；不代表所有禅道版本均已验证。
- 创建子任务可能使禅道自动重算父任务状态及工时；将已有耗时的普通任务转换为父任务时，禅道还可能生成历史子任务并迁移工时。提交前应向用户说明。网络失败、缺失 ID 或回读失败均不可自动重试，应先检查父任务及返回 ID。

子任务实现契约参考：[禅道 18.5 控制器](https://github.com/easysoft/zentaopms/blob/zentaopms_18.5/module/task/control.php)与[任务模型](https://github.com/easysoft/zentaopms/blob/zentaopms_18.5/module/task/model.php)。
- 已验证 DSH 启动、MCP 工具发现和真实只读任务搜索、产品线/日期范围 Bug 查询。创建、修改、解决、关闭和工时写入尚未进行公开版本的真实业务端到端验证。
- 搜索存在执行数和页大小上限；报表也有读取上限。返回数量表示已读取匹配项，不保证是所有历史数据的总数。默认日期使用 UTC。
- active 表示未解决，并不等于生产环境缺陷；openedBuild 只是影响版本过滤。线上口径需要使用方明确。
- 写操作可能新增记录、变更剩余工时或完成任务；confirm=true 不是幂等键，也不证明用户已批准。结果不确定时先核对服务端。

## 开发验证

    npm install --ignore-scripts
    npm test
    npm pack --dry-run

自动测试使用临时 zsh 配置和本地 MCP 进程，不接触真实禅道或个人凭据。执行测试前先安装依赖。建议使用具有所需最小权限的专用禅道账号。

`.github/workflows/ci.yml` 在 main 推送和 PR 时运行 Node 20/22/24 回归、Python 语法与打包检查，使用锁文件安装，不连接真实禅道。

### 自动发布 npm

`.github/workflows/publish.yml` 在推送 `v*` 标签时运行测试，通过后用 npm Trusted Publishing（OIDC，无需 NPM_TOKEN）发布。仅接受与 package.json 版本一致的正式版本标签，且提交必须属于 main；普通代码推送不会发布。发布任务单独授予短期 OIDC 权限，不安装或执行第三方依赖脚本。

首次需在 npm 包 Settings → Trusted publishing 添加 GitHub Actions：

- Organization or user：`bakeham`
- Repository：`dsh-zentao-mark-effort`
- Workflow filename：`publish.yml`（不带目录）
- Environment：留空
- Allowed actions：允许直接 `npm publish`，否则仅 stage 权限不能自动上线。

确认工作区干净、修改已提交且 CI 通过后，下一次发布：

```bash
npm version patch
git push origin main
git push origin "v$(node -p 'require("./package.json").version')"
```

最后一步仅推送当前版本标签。已存在的 npm 版本不能覆盖；发布中断先检查 npm 是否已有该版本，勿删除标签反复发布。可从 Actions 选择已有标签手动运行发布工作流，选择分支会被拒绝。

首次配置以实际 GitHub Actions 发布成功为验收；仅 YAML 检查或本地测试通过不代表 npm 信任关系已生效。参考 [npm Trusted Publishing 文档](https://docs.npmjs.com/trusted-publishers/)。