dsh-zentao-mark-effort

非官方社区插件，与 DeepSeek、禅道及其官方团队无隶属关系。MIT 许可证。Node.js 20+；兼容性验证使用 DSH 0.1.2-rc.1。上游 76 个工具由外部依赖 @houengineer/[email protected] 提供，首次启动需要访问 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/[email protected]。
• 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 控制器与任务模型。

• 已验证 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 通过后，下一次发布：

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 文档。