zing-cli

知影智能 多项目统一命令行工具。

安装

npm install -g @zinghub/zing-cli

使用

# 查看帮助
zing --help

# 登录（打开浏览器完成 OAuth 授权）
zing login

# 登录到指定服务器
zing login --server https://你的服务器地址

# 查看当前登录状态
zing whoami

# 退出登录
zing logout

AI 需求自动管理（zing requirement）

将「AI 需求自动管理流水线」集成进命令行：拉取 AI 待办、回写处理结果推进状态机、新增/查看/删除需求。登录复用 zing login，接口调用自动携带 Token。

# 拉取 AI 待办列表（表格输出）
zing requirement +todo

# JSON 格式输出（便于程序解析）
zing requirement +todo --format json

# 新增需求（默认 DRAFT）
zing requirement +add --title "客户数据导出" --desc "支持按条件导出客户明细" --priority P1

# 查看需求详情
zing requirement +detail --id <记录ID>

# 回写处理结果，推进状态机
zing requirement +report \
  --id <记录ID> \
  --target REQ_CONFIRMING \
  --req-doc-path docs/requirements/REQ-xxx.md \
  --req-summary "需求一句话摘要" \
  --remark "处理说明"

# 删除需求（逻辑删除）
zing requirement +delete --id <记录ID>

# 指定环境（开发环境需 -e dev；生产默认 prod）
zing requirement +todo -e dev

+report 回写目标状态说明

| 当前状态 | AI 动作 | --target | | --- | --- | --- | | DRAFT | 提炼 REQ 文档 | REQ_CONFIRMING | | REQ_CONFIRMED | 制定 PLAN | PLAN_CONFIRMING | | REQ_REJECTED | 修改 REQ 重提 | REQ_CONFIRMING | | PLAN_CONFIRMED | 开始编码 | DEVELOPING | | PLAN_REJECTED | 修改 PLAN 重提 | PLAN_CONFIRMING | | DEVELOPING | 编码完成进测试 | TESTING | | TESTING | 测试完成待验收 | PENDING_ACCEPT | | ACCEPT_REJECTED | 重新开发 | DEVELOPING |

--target 必须与状态机一致，否则 zing requirement +report 会返回「非法回写」并拒绝提交。

+report 文档内容上报约束（强制）

每次任务完成后，相关 MD 文档内容必须直接上报（REQ 阶段上报 REQ 文档、PLAN 阶段上报 PLAN 文档、测试阶段上报测试报告），不允许静默缺失：

| 目标状态 | 必填文档内容 | 对应参数 | | --- | --- | --- | | REQ_CONFIRMING / REQ_CONFIRMED | REQ 文档 | --req-doc-path / --req-doc-content | | PLAN_CONFIRMING / PLAN_CONFIRMED | PLAN 文档 | --plan-doc-path / --plan-doc-content | | PENDING_ACCEPT | 测试报告 | --test-report-path / --test-report-content |

注：TESTING（编码完成进入测试的中间态）不强制测试报告，测试完成回写 PENDING_ACCEPT 时才强制。

• 缺失报错：目标状态要求文档但内容为空时，+report 报 [ERROR] xx文档内容为空 并中止回写，状态不落库
• 路径解析：--*-doc-path 优先传绝对路径；相对路径依次尝试 zing-cli 目录（cwd）、仓库根目录（cwd 上一级），命中任一即可
• 绝对路径落库：上报成功后 reqDocPath / planDocPath / testReportPath 落库为解析后的绝对路径，便于后台/App 校验
• 用法示例：

# 推荐：绝对路径（内容自动读取并上报）
zing requirement +report --id <ID> --target REQ_CONFIRMING \
  --req-doc-path /Users/xxx/project/docs/requirements/REQ-xxx.md \
  --req-summary "需求一句话摘要"

# 仓库根相对路径也可（自动解析）
zing requirement +report --id <ID> --target PLAN_CONFIRMING \
  --plan-doc-path docs/plans/PLAN-xxx.md \
  --plan-summary "方案摘要"

# 显式传内容（不依赖文件读取）
zing requirement +report --id <ID> --target TESTING \
  --test-report-content "# 测试报告..." --test-report-path /abs/path/report.md

系统要求

• Node.js >= 18.0.0