ARTICLE DETAIL

资讯详情

深耕郑州网站建设与运营推广的一线实战洞察。

Huly 统一导入格式实战:从「Project Setup」示例文件解读 Tracker 项目与 Issue 的导入规范

Huly 统一导入格式实战:从「Project Setup」示例文件解读 Tracker 项目与 Issue 的导入规范 Huly 统一导入格式实战从「Project Setup」示例文件解读 Tracker 项目与 Issue 的导入规范【免费下载链接】platformHuly — All-in-One Project Management Platform (alternative to Linear, Jira, Slack, Notion, Motion)项目地址: https://gitcode.com/GitHub_Trending/platform80/platform导读本文以 Huly 仓库中 dev/import-tool/docs/huly/example-workspace 示例工作区内的Project Alpha/1.Project Setup.md为切入点系统讲解 Huly **Unified Import Format统一导入格式**中 Tracker跟踪器项目与 Issue问题的目录组织、YAML frontmatter 字段规范与导入流程。读完本文你将掌握如何用 YAML Markdown 手写或程序化生成符合 Huly 导入规范的工程文件并借助import-tool命令将任意系统中的项目数据一键迁移进 Huly 工作区。关联文档在示例工作区中的定位在进入字段细节之前先明确关联文档所处的层级。示例工作区的根目录下每个「空间Space」由同名配置文件和同名文件夹组成Project Alpha.yamlProject项目空间配置声明项目标识符、所有者、成员等Project Alpha/1.Project Setup.mdIssue问题文件即本次关联文档标题为Project SetupProject Alpha/1.Project Setup/与 Issue 同名的子文件夹存放该 Issue 的子任务subtasks2.Configure CI.md子任务 IssueConfigure CI PipelineProject Alpha/files/空间级附件目录存放 config.yaml 等文件可在 Markdown 内容中引用。这一「配置 YAML 内容 MD 同名子目录 files 附件目录」的四件套结构是 Huly 统一导入格式的核心骨架详细约定可参见 dev/import-tool/docs/huly/README.md 的 File Structure Example 章节。统一格式的文件结构约定根据 dev/import-tool/docs/huly/README.md统一格式以分层文件夹结构表示工作区数据基本规则如下根目录包含空间配置文件*.yaml及其对应的文件夹每个空间文件夹内包含文档/问题*.md以及它们的子文档/子问题文档/问题可以拥有与自身同名的文件夹存放子项例如1.Project Setup.md对应1.Project Setup/目录文件名settings.yaml为保留名称不能用作空间配置缺少 frontmatter 中必需class属性的文件将被跳过不会导入。以示例工作区为参照一个典型的 Tracker 空间目录如下workspace/ ├── Project Alpha.md? # 对照用示例中没有此文件 ├── Project Alpha/ # Project 空间文件夹 │ ├── 1.Project Setup.md # Issue带子任务 │ ├── 1.Project Setup/ # 子任务文件夹与 Issue 同名 │ │ └── 2.Configure CI.md # 子任务 Issue │ ├── 4.Update Docs.md # 独立 Issue │ └── files/ │ └── screenshot.png # 附件可在 Markdown 内容中引用 └── Project Alpha.yaml # Project 空间配置对应地Documentation 示例 使用document:class:Teamspace组织知识库文档QMS Documents 示例 使用documents:class:OrgSpace组织受控文档三种空间类型共用同一套目录约定。Tracker Issue 的 frontmatter 字段规范1.Project Setup.md的完整内容是本文的主角其 YAML frontmatter 定义了 Issue 的全部元数据--- class: tracker:class:Issue title: Project Setup status: In Progress priority: High assignee: John Doe estimation: 8 remainingTime: 4 comments: - author: john.doeexample.com text: | Initial infrastructure is ready! - author: joe.shmoeexample.com text: | Great! Ill start working on Configure CI task now. - author: john.doeexample.com text: | Perfect, dont forget to update [documentation](https://link.gitcode.com/i/47449210aeeb110819323f570a7e6701) when youre done. attachments: - ./files/screenshot.png --- **Initial project infrastructure setup.** Tasks: 1. Repository setup 2. Configure GitHub integration with Huly 3. Set up CI/CD pipeline using [configuration template](https://link.gitcode.com/i/3e9a393f82827d00a299c7758d5c8974) 4. Configure team access and permissions Daily sync-ups in Huly Virtual Office at 10:00 AM UTC.字段速查表字段必填说明示例值class是资源类型标识Issue 固定为tracker:class:Issuetracker:class:Issuetitle是Issue 标题Project Setupstatus是Issue 状态取值见下方枚举In Progresspriority否优先级取值见下方枚举Highassignee否负责人按姓名全名匹配系统内用户John Doeestimation否预估工时小时整数8remainingTime否剩余工时小时整数4comments否评论列表每条含author、text、可选attachments见下文该字段集合与源码中定义的导入接口一一对应见 packages/importer/src/huly/huly.ts 中的HulyIssueHeaderexport interface HulyIssueHeader { class: tracker:class:Issue title: string status: string assignee?: string priority?: string estimation?: number // in hours remainingTime?: number // in hours comments?: HulyComment[] }状态与优先级的允许值根据 dev/import-tool/docs/huly/README.md 的 Allowed Values 章节status与priority只能取以下枚举值否则导入器可能无法映射到 Huly 内置状态机Issue 状态statusBacklog、Todo、In Progress、Done、CanceledIssue 优先级priorityLow、Medium、High、Urgent。示例中的status: In Progress、priority: High均在此枚举范围内。工时字段的语义estimation: 8与remainingTime: 4都以小时为单位源码注释明确标注// in hours。在本示例中这表示 Issue 预估总工时 8 小时、当前剩余 4 小时二者差值4 小时可理解为已投入工时——导入后 Huly 会据此呈现进度视图。评论comments与附件跨文档引用的正确写法comments字段是1.Project Setup.md中信息量最丰富的部分示范了三种典型用法纯文本评论author使用系统内用户的邮箱地址text为 Markdown 正文。例如john.doeexample.com的Initial infrastructure is ready!评论内跨文档链接joe.shmoeexample.com的评论用相对路径链接到子任务 2.Configure CI.md写法是Configure CI注意 URL 编码的空格%20评论内跨空间链接 附件john.doeexample.com的第二条评论链接到 Documentation 空间下的 Installation.md相对路径向上两级../Documentation/...并携带附件attachments: - ./files/screenshot.png。值得注意的是attachments指向的 screenshot.png 位于空间的files/目录中——这正是统一格式的附件约定空间文件夹下的files/目录可存放附件当附件被 Markdown 内容引用时会随导入一并上传README 的 Limitations 章节亦明确Files in space directories can be used as attachments when referenced in markdown content。正文部分的[configuration template](https://link.gitcode.com/i/3e9a393f82827d00a299c7758d5c8974)同样引用了files/目录下的 config.yaml该文件展示了一份常规的开发环境配置模板server/database/github/logging 等导入后可以作为 Issue 描述中的可访问资源。Issue 标识符ID的生成规则统一格式中Issue 的人类可读 ID 由项目标识符Project identifier 文件名中的编号组合而成项目identifier在Project Alpha.yaml中声明为ALPHA必须为字母开头的至多 5 位大写字母/数字Issue 文件名1.Project Setup.md以数字1开头因此该 Issue 导入后获得 IDALPHA-1。同理其子任务 2.Configure CI.md 将获得ALPHA-2。这条规则在 README 的 Issue Identification 章节有明确定义也是手动编排文件名时保持编号唯一性的依据。子任务Subtask如何建模子任务不依赖 frontmatter 中的父子字段而是通过目录层级表达在1.Project Setup/子目录下放置2.Configure CI.md即可。打开该子任务文件可以看到与父 Issue 完全相同的 frontmatter 结构--- class: tracker:class:Issue title: Configure CI Pipeline status: Todo priority: High assignee: Joe Shmoe estimation: 4 --- Set up CI pipeline with GitHub integration: - Configure GitHub Actions - Set up test automation - Add build status notifications to Huly - Configure deployment workflow从源码结构看huly.ts 中的CardsProcessor与UnifiedFormatParser协作导入器遍历目录时按同名文件夹递归的方式建立父子关系因此嵌套深度不受 frontmatter 限制可无限扩展层级。上游Project 空间配置文件Issue 的导入语义依赖同目录下的空间配置 Project Alpha.yaml。其字段与 README 规范完全一致class: tracker:class:Project # 必填空间类型 title: Project Alpha # 必填项目名称 identifier: ALPHA # 必填至多 5 位大写字母/数字须以字母开头 emoji: # 可选项目图标示例额外补充 private: false # 可选默认 false autoJoin: true # 可选默认 true owners: # 可选邮箱列表 - john.doeexample.com members: # 可选邮箱列表 - joe.shmoeexample.com description: Main development project # 可选 defaultIssueStatus: Todo # 可选新 Issue 默认状态其中identifier直接参与 Issue ID 生成owners/members决定导入后的访问控制。对应地源码中的HulyProjectSettings接口huly.ts声明了identifier、projectType、defaultIssueStatus等扩展字段。源码级原理导入链路如何执行1.Project Setup.md这类文件最终由import-tool的import子命令驱动完成导入整条链路在 dev/import-tool/src/index.ts 中定义import dir # 导入统一格式目录等价于 # node bundle.js import /data --user your.emailcompany.com --password ... --workspace ws-id其关键步骤对应authorize()函数index.ts从FRONT_URL/config.json获取ACCOUNTS_URL设置serverClientPlugin.metadata.Endpoint用--user/--password登录账户获取token通过getUserWorkspaces()查找--workspace指定 URL 的工作区并selectWorkspace选中连接 Transactor 端点创建TxOperations客户端并构造FrontFileUploader用于附件上传绑定工作区数据 ID实例化HulyFormatImporter来自hcengineering/importer包实现在 packages/importer/src/huly/huly.ts调用importFolder(dir)递归导入整个目录。导入器内部通过UnifiedFormatParser解析 frontmatterjs-yaml解析 YAML 头以class字段分派处理tracker:class:Issue走 Issue 构建document:class:Document走文档构建documents:mixin:DocumentTemplate/documents:class:ControlledDocument走受控文档构建。这也是前文缺少class的文件会被跳过这一规则的实现依据。其他空间类型速览与 Tracker 同构统一格式不止覆盖 Tracker示例工作区还包含两类常见空间结构与 Tracker 完全同构YAML 配置 MD 内容 子目录 files 附件文档空间Teamspace配置用class: document:class:Teamspace文档用class: document:class:Documenttitle如 Documentation.yaml 与 Getting Started.md受控文档空间OrgSpaceQMS 场景配置用class: documents:class:OrgSpace并支持qualified、manager、qara等质量角色字段模板用documents:mixin:DocumentTemplate含docPrefix、category受控文档用documents:class:ControlledDocument含template、changeControl详见 QMS Documents.yaml 与 SOP-001 系列示例。受控文档的编号写在文件名方括号中如[SOP-002]未指定时可由导入器按模板docPrefix自动生成如SOP-99。运行导入命令在示例工作区目录上运行导入的完整命令来自 dev/import-tool/docs/huly/README.md 的 Run Import Tool 章节docker run \ -e FRONT_URLhttps://huly.app \ -v /path/to/workspace:/data \ hardcoreeng/import-tool:latest \ -- bundle.js import /data \ --user your.emailcompany.com \ --password yourpassword \ --workspace workspace-id要点说明FRONT_URL必须可访问且其/config.json能返回ACCOUNTS_URL否则程序会报please provide front url并退出见 index.ts工作区目录挂载到容器内/dataimport /data指定导入根目录--workspace是工作区的 URL 标识workspace url需与登录用户可访问的工作区匹配。已知限制与最佳实践依据 README 的 Limitations 章节与示例文件的写法落地导入时需注意用户须预先存在所有在assignee、评论author、空间owners/members中出现的用户必须已存在于系统内Assignee 按全名映射评论按邮箱映射文件编号与标识符唯一Issue 文件名编号在同一项目内应递增且不重复项目identifier不超过 5 位且以字母开头受控文档编号须在所有文档空间内唯一受控文档约束受控文档必须与其模板位于同一空间且导入时仅支持Draft状态附件经引用才上传files/目录中的文件只有在 Markdown 内容或评论attachments中被引用时才会作为附件上传因此引用路径务必书写正确注意空格需 URL 编码保留文件名不要使用settings.yaml命名空间配置文件且所有 MD 文件必须携带含class的 frontmatter否则会被静默跳过。按照上述规范编排目录与 frontmatter即可用纯文本维护一整个 Huly 工作区的快照并将其作为可版本化、可审查、可程序化生成的数据源通过import-tool一键导入。【免费下载链接】platformHuly — All-in-One Project Management Platform (alternative to Linear, Jira, Slack, Notion, Motion)项目地址: https://gitcode.com/GitHub_Trending/platform80/platform创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表