@cloudglab/zentao-cli 0.1.3

package/CHANGELOG.md

@@ -0,0 +1,50 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## 0.1.3 - 2026-06-05
+
+### Fixed
+
+- 修复构建前未清理 `dist` 导致 npm 包可能混入旧 MCP 产物的问题；构建现会先清空 `dist` 再重新编译。
+
+## 0.1.2 - 2026-06-05
+
+### Changed
+
+- 为 npm trusted publishing 补齐 `package.json.repository.url`，明确绑定到 `https://github.com/cloudglab/zentao-cli.git`。
+- 版本提升到 `0.1.2`，用于重新触发自动发布链路。
+
+## 0.1.1 - 2026-06-05
+
+### Changed
+
+- 发布工作流切换为 npm trusted publishing，去掉 `NPM_TOKEN` 发布依赖。
+- GitHub Actions 发布环境升级为 Node.js 24，以满足 npm OIDC trusted publishing 运行要求。
+
+## 0.1.0 - 2026-06-05
+
+### Added
+
+- 新增更稳的认证错误分类：区分账号密码错误、接口不存在、服务端异常、网络错误、响应异常。
+- 新增 `ZENTAO_API_BASE_URL` 配置，支持非标准禅道 API 部署路径。
+- 新增 `initZentao --save` 显式落盘控制，默认仅校验当前会话配置。
+- 新增线上 Bug 查询强制判断与固定口径文档：`市场和售后问题跟踪` + 模块匹配。
+- 新增 `getMyBugs` / `getMyBugStatistics` 默认跨产品查询能力，`productId` 改为可选收窄条件。
+- 新增 GitHub Actions 发布链路：push `v*` tag 后自动校验、构建、发布 npm、创建 GitHub Release。
+- 新增纯 CLI 运行层：`zentao help`、`zentao list`、`zentao --version`。
+
+### Changed
+
+- 包名统一为 `@cloudglab/zentao-cli`，本地命令统一为 `zentao`。
+- skill 安装方式统一为 `npx skills add @cloudglab/zentao-cli -g`。
+- 运行架构从 MCP server 切换为本地 CLI 命令执行链路。
+- 发布产物运行时目标下调为 `Node.js >= 16`。
+- TypeScript 构建目标下调为 `ES2020`，并移除运行时 `@modelcontextprotocol/sdk` 依赖。
+- README、skill、reference 文档整体同步到“本地 `zentao` + skill 调用”口径。
+
+### Fixed
+
+- 修复 token 获取失败时对所有错误都盲目回退 MD5 的问题，仅在明确鉴权失败时回退。
+- 修复固定 API 路径导致部分实例无法登录的问题。
+- 修复默认将敏感配置落盘的问题，改为显式保存才写入本地。

package/MCP_ZENTAO_REBUILD_PLAN.md

@@ -0,0 +1,505 @@
+# mcp-zentao 重建计划
+
+## 目标
+
+在 `/Users/lixiaoming/Desktop/doing/zentao-cli` 中重建一个新的禅道 MCP 项目。
+
+目标不是 1:1 反编译原作者源码，而是基于现有可运行产物和已验证行为，写一个结构清晰、可维护、适配当前禅道 18.5 的 TypeScript 项目。
+
+## 当前依据
+
+参考来源：
+
+- 全局包：`@zzp123/mcp-zentao@1.18.15`
+  - 路径：`~/.nvm/versions/node/v20.19.2/lib/node_modules/@zzp123/mcp-zentao`
+  - 主要参考：`dist/api/zentaoApi.js`、`dist/index.js`、`dist/index-dev.js`、`README.md`
+- 本地 Legacy 项目：`/Users/lixiaoming/Desktop/open/mcp-zentao-11-3`
+  - 主要参考：导出、批量处理、AI 摘要、图片下载等能力
+- 当前环境验证结果：
+  - 禅道版本：`18.5`
+  - 地址根域名：`https://zentao.cloudglab.cn`
+  - 实际 API 路径：`/zentao/api.php/v1`
+  - `zentao-cli` 依赖 v2，不适配当前环境
+  - `@zzp123/mcp-zentao` 补丁后可用
+
+## 已验证的关键行为
+
+### 认证
+
+当前禅道 `18.5` 的 token 接口：
+
+```txt
+POST /zentao/api.php/v1/tokens
+```
+
+要求：
+
+- 密码优先使用明文
+- 部分环境可能需要 MD5，因此保留 MD5 回退
+
+认证逻辑：
+
+1. 先用明文密码请求 token
+2. 明文失败后再用 MD5 密码请求 token
+3. 成功后请求头携带：`Token: <token>`
+
+### 脏 JSON 响应清洗
+
+当前服务端会在 JSON 前输出 PHP warning，例如：
+
+```html
+<br />
+<b>Deprecated</b>: ...
+{"token":"..."}
+```
+
+因此 HTTP 层必须实现：
+
+1. 如果响应已经是 object，直接返回
+2. 如果响应是 string，查找第一个 `{` 或 `[`
+3. 截取 JSON 部分后再 `JSON.parse`
+
+### 已验证 API
+
+这些接口已经在当前环境验证可用：
+
+```txt
+GET /tasks
+GET /bugs/:id
+GET /stories/:id
+GET /executions/:id
+GET /executions/:id/bugs
+```
+
+其中：
+
+- `getMyTasks()` 成功
+- `getBugDetail(84362)` 成功
+- `getStoryDetail(9680)` 成功
+- `getExecutionDetail(2140)` 成功
+- `request('GET', '/executions/2140/bugs')` 成功
+
+## 技术栈
+
+建议：
+
+- TypeScript
+- Node.js >= 20
+- `@modelcontextprotocol/sdk`
+- `zod`
+- `axios` 或 `ofetch`
+- `tsx` 用于本地开发
+- `tsc` 用于类型检查和构建
+- `oxlint` 用于 lint
+- `oxfmt` 可用于格式化，先试点
+
+不建议一开始使用 OXC 作为主构建系统。当前项目更适合：
+
+```txt
+TypeScript + tsc + oxlint + oxfmt
+```
+
+## 推荐目录结构
+
+```txt
+src/
+  bin/
+    zentao.ts
+    zentao-dev.ts
+    zentao-pm.ts
+    zentao-qa.ts
+
+  core/
+    auth.ts
+    config.ts
+    errors.ts
+    http.ts
+    roles.ts
+    tool-registry.ts
+    transport.ts
+
+  api/
+    bug.ts
+    build.ts
+    comment.ts
+    execution.ts
+    feedback.ts
+    file.ts
+    product.ts
+    project.ts
+    story.ts
+    task.ts
+    testcase.ts
+    ticket.ts
+    user.ts
+
+  tools/
+    bug.ts
+    comment.ts
+    execution.ts
+    init.ts
+    product.ts
+    story.ts
+    task.ts
+    shared.ts
+
+  schemas/
+    bug.ts
+    execution.ts
+    story.ts
+    task.ts
+
+  types/
+    common.ts
+    zentao.ts
+
+  utils/
+    date.ts
+    html.ts
+    json.ts
+    markdown.ts
+```
+
+## 核心模块设计
+
+### `core/http.ts`
+
+职责：
+
+- 创建 HTTP client
+- 统一拼接 API base URL
+- 注入 `Token` header
+- 清洗 PHP warning 脏响应
+- 统一错误格式
+
+必须内置：
+
+```ts
+sanitizeJsonLikeResponse(data)
+```
+
+### `core/auth.ts`
+
+职责：
+
+- 获取 token
+- 明文优先
+- MD5 回退
+- 缓存 token
+- 后续可扩展 401 自动重登
+
+### `core/config.ts`
+
+职责：
+
+- 读取环境变量
+- 读取本地配置
+- 保存配置
+
+建议支持：
+
+```txt
+ZENTAO_URL
+ZENTAO_USERNAME
+ZENTAO_PASSWORD
+ZENTAO_API_VERSION
+```
+
+本地配置路径建议：
+
+```txt
+~/.zentao/config.json
+```
+
+### `core/transport.ts`
+
+职责：
+
+- 启动 stdio MCP server
+- 后续支持 HTTP transport
+
+### `core/tool-registry.ts`
+
+职责：
+
+- 统一注册所有工具
+- 根据角色过滤工具
+
+不要复制四份入口文件。
+
+推荐方式：
+
+```ts
+registerTools(server, { role: 'dev' })
+```
+
+## 角色设计
+
+### full
+
+完整能力，适合维护和排查。
+
+### dev
+
+开发常用：
+
+- task 查询、更新、完成
+- bug 查询、解决、评论
+- story 查询
+- execution 查询
+- build 查询
+
+### qa
+
+测试常用：
+
+- bug 查询、创建、解决
+- testcase 查询
+- testtask 查询
+- story 查询
+
+### pm
+
+产品常用：
+
+- product
+- story
+- requirement
+- plan
+- feedback
+- project
+
+## 分阶段计划
+
+### 阶段 0：项目初始化
+
+产出：
+
+- `package.json`
+- `tsconfig.json`
+- `oxlint` 配置
+- `src/` 基础目录
+- `README.md`
+- 基础 bin 入口
+
+验收：
+
+```bash
+pnpm install
+pnpm typecheck
+pnpm lint
+```
+
+### 阶段 1：MVP 内核
+
+实现：
+
+- `core/config.ts`
+- `core/http.ts`
+- `core/auth.ts`
+- `core/transport.ts`
+- `core/tool-registry.ts`
+- `tools/init.ts`
+
+验收：
+
+- 能启动 MCP server
+- 能读取配置
+- 能拿到 token
+- 能清洗 PHP warning
+
+### 阶段 2：开发最小闭环
+
+实现 API：
+
+- `api/task.ts`
+- `api/bug.ts`
+- `api/story.ts`
+- `api/execution.ts`
+
+实现工具：
+
+- `getMyTasks`
+- `getTaskDetail`
+- `getBugDetail`
+- `getStoryDetail`
+- `getExecutionDetail`
+- `getExecutionBugs`
+
+验收：
+
+- `getBugDetail(84362)` 成功
+- `getExecutionBugs(2140)` 成功
+- `getStoryDetail(9680)` 成功
+
+### 阶段 3：开发常用写操作
+
+实现：
+
+- `updateTask`
+- `finishTask`
+- `resolveBug`
+- `addComment`
+
+注意：
+
+- 写操作必须由调用方确认后再执行
+- 先做只读验证，再做写操作
+
+### 阶段 4：完整模块迁移
+
+按优先级迁移：
+
+1. task
+2. bug
+3. story
+4. execution
+5. product
+6. project
+7. build
+8. testcase
+9. file
+10. comment
+11. feedback
+12. ticket
+13. user
+
+### 阶段 5：吸收 Legacy 项目增强能力
+
+从 `/Users/lixiaoming/Desktop/open/mcp-zentao-11-3` 借鉴：
+
+- `batchUpdateTasks`
+- `batchResolveBugs`
+- `getStoryRelatedBugs`
+- `getBugRelatedStory`
+- `exportStory`
+- `exportBug`
+- `exportItems`
+- Markdown 格式化
+- 图片下载
+- story/bug/task 分析摘要
+- 下一步建议
+
+### 阶段 6：角色入口和发布准备
+
+实现 bin：
+
+- `zentao`
+- `zentao-dev`
+- `zentao-qa`
+- `zentao-pm`
+
+验收：
+
+- 每个 bin 可启动
+- 工具数量符合角色配置
+- 文档和实际工具一致
+
+## API 优先级清单
+
+### P0
+
+必须先实现：
+
+- token 登录
+- request
+- response sanitize
+- getMyTasks
+- getBugDetail
+- getStoryDetail
+- getExecutionBugs
+- getExecutionDetail
+
+### P1
+
+开发日常需要：
+
+- updateTask
+- finishTask
+- resolveBug
+- addComment
+- getProductBugs
+- getProductStories
+
+### P2
+
+完整能力：
+
+- createTask
+- createBug
+- createStory
+- product/project/execution CRUD
+- testcase
+- build
+- file upload/download
+
+### P3
+
+增强体验：
+
+- Markdown 导出
+- 图片下载
+- 批量处理
+- AI 摘要
+- 智能建议
+
+## 与现有包的差异目标
+
+新项目不要重复旧包的问题：
+
+- 不要一个 1400 行 `ZentaoAPI` 大文件
+- 不要四份入口复制大量代码
+- 不要 README 工具数和真实工具数不一致
+- 不要把补丁脚本作为长期方案
+- 不要默认强制 MD5 密码
+- 不要忽略 PHP warning 脏响应
+
+新项目需要内置：
+
+- 明文密码优先
+- MD5 回退
+- PHP warning 清洗
+- execution bug list 正式方法
+- 可扩展的角色工具过滤
+- 后续可加 401 自动重登
+
+## 验收基准
+
+最小验收：
+
+```txt
+getToken 成功
+getMyTasks 成功
+getBugDetail(84362) 成功
+getExecutionBugs(2140) 成功
+getStoryDetail(9680) 成功
+```
+
+完整验收：
+
+```txt
+dev 角色可完成日常开发相关任务
+full 角色覆盖当前 @zzp123/mcp-zentao 的主要能力
+导出能力覆盖 mcp-zentao-11-3 的 Markdown + 图片下载场景
+```
+
+## 后续第一步
+
+建议下一步直接初始化项目：
+
+```bash
+pnpm init
+pnpm add @modelcontextprotocol/sdk zod axios
+pnpm add -D typescript tsx oxlint
+```
+
+然后优先实现：
+
+```txt
+src/core/http.ts
+src/core/auth.ts
+src/api/bug.ts
+src/api/execution.ts
+src/tools/bug.ts
+src/tools/execution.ts
+```