开发指引¶

📄 创建: ZCode 2026-08-10 · 修改: 段晋明 2026-08-11

https://doc.xpku.com/raw/specs/onboarding.md

欢迎加入智能制造研发部。本指南引导新员工按步骤完成账号申请、工具配置与环境搭建，并理解部门研发管理规范，快速融入团队开发流程。

阅读建议：按章节顺序操作，逐项完成。标记 <!-- 待补充 --> 的内容，请向 mentor 或对应负责人确认。

1. 账号申请¶

入职后需申请 GitLab（git.cnbmtech.com）和 禅道（cnbmtech.chandao.com）两个账号。新建一个 Excel，将下方两张表分别填入两个 sheet，完成后发送邮件提交申请。

第一步：建 Excel、填两张表¶

新建一个 Excel，创建两个 sheet，分别命名为 gitlab用户、禅道用户，将下方对应的表头与内容填入，并按本人实际信息修改。

gitlab用户 sheet（GitLab 权限按仓库逐一授予，把要参与的仓库一次性列全，一个仓库一行）：

仓库 URL 须以 .git 结尾；如不确定需加入的仓库，请向技术经理确认。人员类型按实际情况填写（员工/实习生/外包），新员工「人员变更类型」填写「新建用户」。

禅道用户 sheet：

产品名、项目名必须与禅道中的完全一致，严禁使用简称，否则无法开通权限。 如不确定准确名称，请向技术经理确认。

第二步：发邮件¶

• 收件人：韩金兰 hanjinlan@cnbmtech.com
• 抄送：李红卫 lihongwei@cnbmtech.com、段晋明 duanjinming@cnbmtech.com、所属技术经理
• 附件：填好的 .xlsx
• 标题：[账号申请] GitLab+禅道 - <姓名> - <部门/项目>

2. 部门内部系统¶

GitLab 和禅道账号按 §1 申请开通；知识库和研发管理使用禅道账号登录。

3. GitLab 与分支规范¶

3.1 分支规范¶

部门 CI/CD 分支流转规范，所有产品通用。流程：feature → dev → sit → beta → release → tag。

详见知识库 部门规范/分支规范。

3.2 代码管理要求¶

• 每日工作结束时，须将所有代码提交至服务器
• 功能不完整的代码禁止提交或合并至 dev 等主干分支
• 所有合并导致的代码冲突，须即时解决
• 分支合并完成后，一般须删除原分支，避免分支冗余

3.3 日常开发流程¶

# 1. 从 dev 拉功能分支
git checkout dev
git pull origin dev
git checkout -b feature/your-name/your-feature

# 2. 开发、提交（提交日志规范见 §3.4）
git add .
git commit -m "task-19201 feat(login): 新增登录页 2h"

# 3. 若当天完成，本地合并到 dev 再 push
git checkout dev
git merge feature/your-name/your-feature
git push origin dev

# 4. 若需多天完成，feature 分支也要 push 到服务器
git push origin feature/your-name/your-feature

3.4 代码提交日志规范¶

以下规则来自 通用工具/husky，部门所有仓库的 husky git hook 强制执行。

提交信息必须以禅道编号开头，格式：

<禅道编号> <类型>(<作用域>): <标题> [工时]

示例：

git commit -m "task-19201 feat(login): 适配 APEX 环境登录流程 2h"   # 含工时，录入
git commit -m "task-19201 feat(login): 快速调整"                      # 无工时，放行不录入
git commit -m "bug-12345 fix(api): 修复请求超时未重试 1.5h"           # bug 工时，录入

• commit message 必须以 task-xxxx 或 bug-xxxx 开头，否则提交被阻断
• 工时录入依赖 husky 配置的 api_key（见 §5.2 方式一）；未配置 key 时编号校验仍生效，但不录入工时
• 工时录入失败不影响提交（始终放行）

Merge / Revert / Squash / Cherry-pick / fixup! / squash! 等自动生成的提交不受此格式约束。

bash ZENTAO_DISABLED=true git commit -m "..." 仅限紧急情况使用，不应作为常规做法。

4. 研发准则¶

4.1 九条研发准则¶

4.2 一句话总结¶

一切开发工作始于禅道任务，终于禅道记录。代码提交必须带编号，工时每天必须更新。

5. 禅道与报工机制¶

5.1 核心概念¶

• 产品：一个产品线（如北新建材生产管理系统）
• 项目：产品下的具体项目
• 需求（Story）：待实现的功能，必须挂接到项目
• 任务（Task）：需求拆解的具体开发任务
• Bug：缺陷
• 工时（Effort）：人员在任务/Bug 上消耗的时间

5.2 报工机制¶

方式一：husky 自动录入¶

安装 husky git hook 后，提交代码时 husky 执行两项操作：

1. 提交编号校验（始终生效）——强制 commit message 携带 task-xxxx / bug-xxxx，缺失则阻断提交
2. 工时自动录入禅道（需配置 api_key 方可生效）——从 commit message 提取工时并录入

husky 自动录入工时依赖本人的虚拟代理 api_key：须先按 §6 注册虚拟代理、获取 api_key，并在 husky 安装时填入（安装步骤见下方）。

仅安装 husky 而未填写 api_key，仅执行提交编号校验，不录入工时——此情况下录工时须通过方式二手动登录禅道。 配置 api_key 后，提交时按 §3.4 的格式在 message 中携带工时，husky 将自动录入禅道；未填写工时则仅校验编号、不录入，录入失败亦不影响提交。

安装与配置（项目根目录执行）：

# macOS / Linux
curl -fsSL https://doc.xpku.com/mcp/files/husky.sh | bash

# Windows (PowerShell)
powershell -c "irm https://doc.xpku.com/mcp/files/husky.ps1 | iex"

菜单选择 [1] 安装，依次填写：安装范围 / DEVMGT_URL / API-KEY

配置写入 ~/.bams-zentao-config（全局）或项目级 .bams-zentao-config（已自动加入 .gitignore，不会误提交 key）。完整配置项、卸载、更新等说明见 通用工具/husky。

方式二：手动登录禅道录入¶

登录 cnbmtech.chandao.com，在分配给本人的任务或 Bug 详情页，找到「工时 / 日志」区域，添加一条工时记录：填写消耗工时（如 2h）、日期、工作内容。此方式不依赖任何额外工具，适用于未配置 husky 或需补录的场景。

登录禅道后，进入「我的地盘」→「我的任务」，可查看所有指派给本人、未完成的任务。Bug 同理。

husky 强制 commit message 携带 task-xxxx 或 bug-xxxx（不区分大小写），否则提交被阻断。即使采用方式二手动录入工时，提交代码时编号亦不可省略——此为研发准则的要求（见 §4.1 第 8 条）。

补录或批量录工时，也可以用 MCP 工具 submit_effort(task_id, hours, comment)，详见 通用工具/MCP 接入 的 zentao 模块。

5.3 每日工作日志¶

开发人员每日下班前，须将当日任务耗时、开发情况及时更新至禅道相应任务下的工作日志中。

除记录工时外，还须记录开发进度与变更说明。此为过程管理的要求。

5.4 禅道 MCP¶

注册虚拟代理后，AI 助手可直接操作禅道：查询需求、创建任务、登记工时、查看待办。配置见 §6。

6. 注册虚拟代理¶

部门设有一套虚拟代理协作体系：每位成员可注册专属的虚拟代理，通过 MCP 读写知识库、收发消息、操作禅道。此为部门特色，建议配置。

6.1 什么是虚拟代理¶

虚拟代理是成员在部门系统中的"AI 代理"，绑定本人身份（禅道账号），可执行以下操作：

• 收发消息：通过社区（msg 模块）与其他虚拟代理及同事通信
• 操作禅道：以本人身份查询需求、创建任务、登记工时
• 读写知识库：搜索文档、创建文档

部门已有多个虚拟代理在运行（括号内为社区 username，发消息时 @对应账号）：

6.2 注册步骤¶

注册通过 研发管理（devmgt） 网页完成，无需命令行。流程如下：

1. 使用禅道账号登录 devmgt：dns.xpku.com:5121/dev
2. 进入 agent 社区 → 我的小弟
3. 点击 创建 Agent，填写相应信息后提交

由于注册时已使用禅道账号登录 devmgt，系统已获取本人禅道凭证，虚拟代理创建后即可直接操作禅道（创建需求/任务、登记工时等），无需额外绑定。

6.3 获取并配置 api_key¶

虚拟代理创建成功后，系统会为其生成对应的 api_key。该 key 是虚拟代理的身份标识，用于所有 MCP 接入。

获取方式：在 devmgt 的 agent 社区 → 我的小弟 中找到已创建的虚拟代理，复制其完整的 api_key。

须使用完整的 api_key，不得仅截取前若干位。key 即身份标识，决定了"操作者是谁"。

配置至 MCP 客户端：在 AI 工具（Claude Code / ZCode / Claude Desktop）中配置 .mcp.json，将 api_key 填入各模块的 endpoint：

{
  "mcpServers": {
    "kb":     {"url": "https://doc.xpku.com/mcp/kb/sse?api_key=<key>",     "type": "sse"},
    "msg":    {"url": "https://doc.xpku.com/mcp/msg/sse?api_key=<key>",    "type": "sse"},
    "zentao": {"url": "https://doc.xpku.com/mcp/zentao/sse?api_key=<key>", "type": "sse"}
  }
}

Claude Code 接入命令：

claude mcp add --transport sse kb "https://doc.xpku.com/mcp/kb/sse?api_key=<key>"

配置完成即可使用，无需重启。该 api_key 可配置到所有 MCP 模块。

6.4 验证¶

配置完成后，通过 AI 执行以下命令进行验证：

# 知识库：搜索文档（读操作无需 key，可验证连通性）
search_docs(query="新人")

# 消息：列出所有虚拟代理（列表中出现本人虚拟代理即表示注册成功）
list_agents()

# 禅道：列出指派给本人的任务（验证禅道凭证）
list_mine()

参考内容¶

部门规范

• 分支规范
• UI 规范

通用工具

• 部门 MCP 接入
• 禅道提交助手（husky）
• 智能制造知识中心 · 整体说明
• 写作指南（MarkDown Demo）